Skill/openspec/changes/archive/2026-02-25-build-skillmgr-cli/tasks.md

1. 项目初始化

• 1.1 在 manager/ 目录创建 Go 项目，初始化 go.mod（module: skillmgr）
• 1.2 创建项目目录结构（cmd/、internal/、pkg/、testdata/）
• 1.3 添加 Cobra 依赖（github.com/spf13/cobra）
• 1.4 创建 .gitignore 文件
• 1.5 创建测试脚本目录（scripts/）

2. 核心类型定义

• 2.1 创建 internal/types/types.go，定义 Platform、ItemType、Scope 枚举类型
• 2.2 定义 Repository 结构体（name、url、branch、added_at）
• 2.3 定义 RepositoryConfig 结构体（repositories 数组）
• 2.4 定义 InstallRecord 结构体（type、name、source_repo、platform、scope、install_path、installed_at、updated_at）
• 2.5 定义 InstallConfig 结构体（installations 数组）
• 2.6 定义 SkillMetadata 和 CommandGroup 结构体

3. 配置管理模块

• 3.1 创建 internal/config/paths.go，实现配置目录路径函数（GetConfigRoot、GetRepositoryConfigPath、GetInstallConfigPath、GetCachePath）
• 3.2 在 GetConfigRoot 中添加环境变量 SKILLMGR_TEST_ROOT 支持（测试隔离）
• 3.3 实现 EnsureConfigDirs 函数，确保配置目录存在
• 3.4 创建 internal/config/repository.go，实现 LoadRepositoryConfig 和 SaveRepositoryConfig
• 3.5 实现 AddRepository 函数（检查同名仓库，存在则拒绝并提示先移除）
• 3.6 实现 RemoveRepository 和 FindRepository 函数
• 3.7 创建 internal/config/install.go，实现 LoadInstallConfig 和 SaveInstallConfig
• 3.8 实现 AddInstallRecord、RemoveInstallRecord、FindInstallRecord、UpdateInstallRecord 函数
• 3.9 实现 CleanOrphanRecords 函数（扫描并清理安装路径不存在的记录）

4. 文件工具模块

• 4.1 创建 pkg/fileutil/fileutil.go
• 4.2 实现 CopyFile 函数（复制单个文件并保留权限）
• 4.3 实现 CopyDir 函数（递归复制目录）

5. Git 仓库管理模块

• 5.1 创建 internal/repo/git.go
• 5.2 实现 URLToPathName 函数（将 git URL 转换为缓存目录名）
• 5.3 实现 CloneOrPull 函数（检查仓库是否存在，不存在则 clone，存在则 pull）
• 5.4 实现 cloneRepo 函数（执行 git clone --depth 1）
• 5.5 实现 pullRepo 函数（执行 git pull）
• 5.6 创建 internal/repo/scanner.go
• 5.7 实现 ScanSkills 函数（扫描 skills/ 目录，返回 skill 列表）
• 5.8 实现 ScanCommands 函数（扫描 commands/ 目录，返回命令组列表）
• 5.9 实现 FindSkill 函数（在所有仓库缓存中查找指定 skill）
• 5.10 实现 FindCommand 函数（在所有仓库缓存中查找指定命令组）

6. 平台适配器模块

• 6.1 创建 internal/adapter/adapter.go，定义 PlatformAdapter 接口
• 6.2 实现 GetAdapter 函数（根据 Platform 返回对应适配器，不支持则报错）
• 6.3 实现 getBasePath 辅助函数（根据 Scope 返回基础路径，支持 SKILLMGR_TEST_BASE 环境变量）
• 6.4 创建 internal/adapter/claude.go，实现 ClaudeAdapter 结构体
• 6.5 实现 Claude 的 GetSkillInstallPath 和 GetCommandInstallPath 方法
• 6.6 实现 Claude 的 AdaptSkill 方法（遍历源目录，生成文件映射）
• 6.7 实现 Claude 的 AdaptCommand 方法（保持目录结构）
• 6.8 创建 internal/adapter/opencode.go，实现 OpenCodeAdapter 结构体
• 6.9 实现 OpenCode 的 GetSkillInstallPath（注意 command 是单数）和 GetCommandInstallPath 方法
• 6.10 实现 OpenCode 的 AdaptSkill 方法（与 Claude 相同）
• 6.11 实现 OpenCode 的 AdaptCommand 方法（扁平化文件名：-.md）

7. 事务性安装模块

• 7.1 创建 internal/installer/transaction.go
• 7.2 定义 Transaction 结构体（stagingDir、targetDir、fileMap）
• 7.3 实现 NewTransaction 函数（在系统临时目录创建 staging）
• 7.4 实现 Stage 方法（复制所有文件到 staging，创建必要的子目录）
• 7.5 实现 Commit 方法（确保父目录存在，删除已存在的目标，移动 staging 到目标）
• 7.6 处理 Commit 中的跨文件系统情况（Rename 失败则 fallback 到 CopyDir）
• 7.7 实现 Rollback 方法（删除 staging 目录）
• 7.8 在 NewTransaction 中使用 defer 确保清理

8. 用户交互模块

• 8.1 创建 internal/prompt/prompt.go
• 8.2 实现 ConfirmWithReader 函数（接受 io.Reader，支持测试 mock）
• 8.3 实现 Confirm 函数（调用 ConfirmWithReader，使用 os.Stdin）

9. 安装器模块

• 9.1 创建 internal/installer/installer.go
• 9.2 实现 checkExistingInstallation 函数（检查 install.json 记录和目录存在性，询问用户是否覆盖）
• 9.3 实现 InstallSkill 函数（查找 skill、获取适配器、确定路径、检查冲突、适配、事务安装、记录）
• 9.4 实现 InstallCommand 函数（查找 command、获取适配器、确定路径、检查冲突、适配、事务安装、记录）
• 9.5 创建 internal/installer/uninstaller.go
• 9.6 实现 UninstallSkill 函数（查找记录、删除目录、移除记录）
• 9.7 实现 UninstallCommand 函数（查找记录、删除目录或文件、移除记录）

10. CLI 根命令

• 10.1 创建 cmd/skillmgr/root.go
• 10.2 定义 rootCmd，设置 Use、Short、Long
• 10.3 实现 Execute 函数
• 10.4 在 init 中调用 config.EnsureConfigDirs 初始化配置目录
• 10.5 创建 cmd/skillmgr/main.go，调用 Execute

11. 仓库管理命令

• 11.1 创建 cmd/skillmgr/add.go，实现 addCmd
• 11.2 添加 --name 和 --branch 参数
• 11.3 实现 RunE：解析参数、调用 repo.CloneOrPull、调用 config.AddRepository、显示成功信息
• 11.4 创建 cmd/skillmgr/remove.go，实现 removeCmd
• 11.5 实现 RunE：调用 config.RemoveRepository
• 11.6 创建 cmd/skillmgr/list_repos.go，实现 listReposCmd
• 11.7 实现 RunE：调用 config.LoadRepositoryConfig、格式化输出
• 11.8 创建 cmd/skillmgr/sync.go，实现 syncCmd
• 11.9 实现 RunE：支持指定仓库名或同步所有，调用 repo.CloneOrPull

12. 安装命令

• 12.1 创建 cmd/skillmgr/install.go，实现 installCmd
• 12.2 添加 --platform（必需）、--global、--from 参数
• 12.3 实现 Args 验证（必须有 2 个参数：type 和 name）
• 12.4 实现 RunE：解析 type（skill/command）、调用对应安装函数
• 12.5 处理 --from 参数（TODO：临时仓库，暂时跳过实现）

13. 追踪管理命令

• 13.1 创建 cmd/skillmgr/list.go，实现 listCmd
• 13.2 添加 --type、--platform、--global 参数
• 13.3 实现 RunE：加载 install.json、根据参数过滤、格式化输出
• 13.4 创建 cmd/skillmgr/uninstall.go，实现 uninstallCmd
• 13.5 添加 --platform（必需）、--global 参数
• 13.6 实现 Args 验证和 RunE：调用对应卸载函数
• 13.7 创建 cmd/skillmgr/update.go，实现 updateCmd
• 13.8 添加 --platform、--global、--all 参数
• 13.9 实现 RunE：支持更新单个或全部已安装项
• 13.10 创建 cmd/skillmgr/clean.go，实现 cleanCmd
• 13.11 实现 RunE：调用 config.CleanOrphanRecords、显示清理结果

14. 搜索命令（可选）

• 14.1 创建 cmd/skillmgr/search.go，实现 searchCmd
• 14.2 实现 RunE：遍历所有仓库缓存、扫描 skills 和 commands、匹配关键词、输出结果

15. 错误处理和用户体验优化

• 15.1 确保所有 Git 操作失败时显示清晰错误信息
• 15.2 安装/卸载成功时显示 ✓ 符号和路径信息
• 15.3 配置文件解析错误时提示用户检查 JSON 格式
• 15.4 未找到 skill/command 时列出可用项

16. 测试基础设施

• 16.1 创建 testdata/fixtures/ 目录
• 16.2 创建测试用 fixture 仓库（test-repo，包含 2 个 skills 和 1 个 command 组）
• 16.3 编写测试辅助函数 setupTestRepo（初始化临时 git 仓库）
• 16.4 编写测试辅助函数 copyFixtureRepo（复制 fixture 并初始化 git）
• 16.5 创建 scripts/test.sh（设置测试环境变量并运行测试）
• 16.6 创建 scripts/sandbox.sh（手动测试沙盒环境）

17. 单元测试

• 17.1 创建 internal/config/paths_test.go，测试环境变量覆盖
• 17.2 创建 internal/config/repository_test.go，测试仓库配置增删改查
• 17.3 测试 AddRepository 拒绝同名仓库场景
• 17.4 创建 internal/config/install_test.go，测试安装记录管理
• 17.5 测试 CleanOrphanRecords 功能
• 17.6 创建 internal/adapter/claude_test.go，测试路径计算和文件映射
• 17.7 创建 internal/adapter/opencode_test.go，测试扁平化命名转换
• 17.8 创建 internal/repo/git_test.go，测试 URL 转换
• 17.9 创建 internal/installer/transaction_test.go，测试 Stage/Commit/Rollback
• 17.10 创建 internal/prompt/prompt_test.go，测试用户输入 mock
• 17.11 创建 pkg/fileutil/fileutil_test.go，测试文件复制

18. 集成测试

• 18.1 创建 internal/installer/installer_test.go
• 18.2 测试完整安装流程（add repo → install skill → 验证文件和记录）
• 18.3 测试冲突覆盖场景（已安装 → 再次安装 → 用户确认）
• 18.4 测试事务回滚（Stage 失败 → 验证 staging 清理）
• 18.5 测试卸载流程（install → uninstall → 验证删除）
• 18.6 测试更新流程（install → update → 验证更新）
• 18.7 测试清理孤立记录（install → 手动删除 → clean）
• 18.8 测试 Claude Code 平台安装（skill 和 command）
• 18.9 测试 OpenCode 平台安装（skill 和 command 扁平化）

19. 构建和手动验证

• 19.1 编写 Makefile 或构建脚本，支持 go build -o skillmgr
• 19.2 在沙盒环境手动测试基本流程
• 19.3 验证全局和项目级安装
• 19.4 验证两个平台的适配正确性

20. 文档

• 20.1 编写 README.md，包含安装说明、使用示例、命令参考
• 20.2 记录配置文件格式和路径
• 20.3 添加常见问题和故障排除指南
• 20.4 添加测试说明（如何运行测试、测试环境变量）