用途:帮助新开发者搭建 Chops 开发环境,并快速了解代码库。
使用方式:按步骤执行以下流程。
-
检查前置条件:macOS 15+(sw_vers -productVersion,需 ≥ 15.0)、Xcode CLI 工具(xcode-select -p,缺失则 xcode-select --install)、Homebrew(which brew,缺失则访问 https://brew.sh)、xcodegen(which xcodegen,缺失则 brew install xcodegen)。任一项缺失时,告知用户需安装的内容并停止。
-
生成 Xcode 工程:运行 xcodegen generate。该命令读取 project.yml(所有 Xcode 工程设置的唯一来源)并生成 Chops.xcodeproj;project.yml 变更后需重新运行。不要直接编辑 .xcodeproj。
-
构建与运行:可用 xcodebuild -scheme Chops -configuration Debug build,或在 Xcode 中打开(open Chops.xcodeproj)并执行 Cmd+R。
-
架构概览:入口为 Chops/App/ChopsApp.swift,设置 SwiftData ModelContainer(Skill + SkillCollection),启动 Sparkle 更新器,并向环境注入 AppState。状态在 Chops/App/AppState.swift,为 @Observable 单例,保存 UI 状态(选中的工具、选中的技能、搜索文本、侧边栏筛选)。数据模型(SwiftData):Skill.swift 表示发现的技能文件,以解析后的符号链接路径唯一标识;Collection.swift 表示用户创建的分组;ToolSource.swift 是受支持工具的枚举,含显示名、图标、颜色与文件系统路径。服务:SkillScanner.swift 探测工具目录、解析 frontmatter 并 upsert 到 SwiftData,按解析后的符号链接路径去重;FileWatcher.swift 通过 DispatchSource 使用 FSEvents,在文件变化时触发重扫;SkillParser.swift 分派到 FrontmatterParser(.md)或 MDCParser(.mdc);SearchService.swift 提供内存全文搜索。视图为三栏 NavigationSplitView(侧边栏→列表→详情),编辑器包装 NSTextView 以实现原生文本编辑,Cmd+S 通过 FocusedValues 保存。
关键设计:应用不启用沙盒,以便无限制读取 ~/ 下的点文件;符号链接去重使同一文件出现在多个工具目录时显示为一个技能并带多个工具徽标;没有测试套件,需手动构建运行验证。扫描路径:Claude Code 为 ~/.claude/skills/、~/.agents/skills;Cursor 为 ~/.cursor/skills/、~/.cursor/rules;Windsurf 为 ~/.codeium/windsurf/memories/、~/.windsurf/rules;Codex 为 ~/.codex;Amp 为 ~/.config/amp;Copilot 与 Aider 仅检测项目级技能,无全局路径。
常见任务:新增工具需在 Chops/Models/ToolSource.swift 的枚举中添加 case 并填写 displayName、iconName、color、globalPaths,若文件布局非标准还需更新 SkillScanner。修改解析:Frontmatter 在 Chops/Utilities/FrontmatterParser.swift,Cursor .mdc 在 Chops/Utilities/MDCParser.swift,分派逻辑在 Chops/Services/SkillParser.swift。修改 UI:视图位于 Chops/Views/(Sidebar/、Detail/、Settings/、Shared/),主布局为 Chops/App/ContentView.swift。
重要规则:project.yml 是 Xcode 设置唯一来源,不要直接编辑 .xcodeproj;Sparkle 是唯一外部依赖,经 SPM 自动拉取;没有测试套件,必须手动构建运行验证;应用无沙盒运行,这是有意且必需的。
限制:技能中的扫描路径与工具支持范围以资料为准;未提供的功能、收费、平台细节暂未提供。