lanyuanxiaoyao/Skill
1
0
Fork 0
Code Activity
Files
master
Skill/openspec/changes/archive/2026-02-25-build-skillmgr-cli/design.md

10 KiB
Raw Permalink Blame History

Context

当前手动管理 AI 编程平台的 skills/commands 面临以下挑战：

  • 平台差异：Claude Code 使用目录结构，OpenCode 使用扁平化文件命名（如 lyxy-kb-init.md）
  • 手动操作：需要手动理解每个平台的规范、复制文件、重命名
  • 追踪困难：无法知道哪些 skills/commands 已安装、来自哪个源、何时安装
  • 更新风险：手动更新容易遗漏文件或破坏已有配置

目标用户是作者本人，工具需要简单直接，优先实现核心功能而非过度设计。

约束条件：

  • 单用户场景，不考虑多用户协作
  • 仅支持最新版本，不处理多版本共存
  • 不解析依赖关系，用户手动管理依赖
  • 平台支持范围：Claude Code、OpenCode（未来可扩展）

Goals / Non-Goals

Goals:

  • 自动化从 git 源仓库到目标平台的完整安装流程
  • 支持全局和项目级两种安装作用域
  • 内置 Claude Code 和 OpenCode 的平台适配规则
  • 记录所有安装操作，支持查询、更新、卸载、清理
  • 事务性安装机制，避免部分失败导致的不一致状态
  • 用户友好的交互体验（确认覆盖、清晰的错误提示）

Non-Goals:

  • ❌ 多版本管理（语义化版本、版本锁定、版本冲突解决）
  • ❌ 依赖解析和自动安装依赖
  • ❌ 插件化的平台适配器系统
  • ❌ 复杂的仓库注册中心或包索引服务
  • ❌ 跨平台迁移或批量同步

Decisions

1. 技术栈选择：Go + Cobra

决策：使用 Go 语言开发，CLI 框架选择 Cobra。

理由：

  • Go：编译为单一可执行文件，无运行时依赖，跨平台分发简单
  • Cobra：业界标准 CLI 框架（kubectl、docker 都用它），支持子命令、自动帮助生成、参数验证
  • 替代方案：标准库 flag 包功能过于简单，不适合多子命令场景

影响：开发者需要熟悉 Go 和 Cobra 的基本用法。

2. 配置文件格式：JSON

决策：使用 JSON 格式存储配置（repository.json、install.json）。

理由：

  • Go 标准库原生支持，无需第三方依赖
  • 结构清晰，易于程序读写和人工检查
  • 替代方案：YAML（需要第三方库）、TOML（生态较小）

配置结构：

~/.skillmgr/
├── repository.json    # 源仓库列表
├── install.json       # 安装记录
└── cache/             # git 仓库缓存

3. 事务性安装：Tmp Staging

决策：采用三阶段事务性安装（Stage → Commit → Rollback）。

理由：

  • 避免部分文件复制失败导致目标目录处于不一致状态
  • 先在系统临时目录（os.TempDir()）组装完整的目标文件树
  • 验证成功后一次性移动到最终位置
  • 失败时自动清理临时目录，不污染目标

流程：

1. 创建 staging 目录（/tmp/skillmgr-xxxxx/）
2. 复制所有文件到 staging（应用平台适配规则）
3. 验证 staging 目录完整性
4. 移动 staging 到目标位置（原子操作）
5. 失败则删除 staging，不影响目标

替代方案：直接复制到目标（风险高）、使用 Git worktree（过于复杂）。

4. 平台适配器：内置而非插件化

决策：将 Claude Code 和 OpenCode 的适配规则硬编码在程序内，不支持用户自定义适配器。

理由：

  • 目标平台数量少且稳定（2 个），插件系统收益低
  • 硬编码保证规则的正确性和一致性
  • 简化实现和维护成本
  • 替代方案：配置文件定义适配规则（增加复杂度）、插件系统（过度设计）

适配器接口：

type PlatformAdapter interface {
    GetSkillInstallPath(scope, name) (string, error)
    GetCommandInstallPath(scope, group) (string, error)
    AdaptSkill(sourcePath, destPath) (map[string]string, error)
    AdaptCommand(sourcePath, destPath, group) (map[string]string, error)
}

差异处理：

  • Skills：两个平台都保持目录结构，直接复制
  • Commands：
    • Claude Code 保持目录结构（commands/lyxy-kb/init.md）
    • OpenCode 扁平化文件名（command/lyxy-kb-init.md）

5. 安装策略：复制而非符号链接

决策：全局和项目级安装都使用文件复制，不使用符号链接。

理由：

  • 避免符号链接在跨平台和跨文件系统时的兼容性问题（尤其是 Windows）
  • 项目可以独立于全局安装，避免意外修改影响其他项目
  • 磁盘空间在现代系统中不是瓶颈
  • 替代方案：全局符号链接（复杂度高，跨平台问题）

影响：

  • 更新全局安装不会自动影响项目级安装（需显式更新）
  • 多个项目可以独立更新各自的 skills/commands

6. 命令文件组织：命令组概念

决策：将 commands 按目录组织，整个目录作为"命令组"一起安装。

理由：

  • 源仓库中 commands 按功能分组（如 commands/lyxy-kb/ 包含 init/ask/ingest/rebuild）
  • 命令组内的命令通常有关联，应一起安装
  • 简化用户操作，避免逐个命令安装

命令组到命令的映射：

  • Claude Code：/lyxy-kb-init → commands/lyxy-kb/init.md
  • OpenCode：/lyxy-kb:init → command/lyxy-kb-init.md

7. 安装记录清理：Clean 命令

决策：提供 clean 命令扫描并清理孤立记录（install.json 中存在但目标路径已删除）。

理由：

  • 用户可能手动删除已安装的目录
  • 避免 install.json 与实际文件系统状态不一致
  • 不自动清理（避免误删），由用户显式触发

实现：

skillmgr clean
# 扫描 install.json 中所有记录
# 检查 install_path 是否存在
# 列出孤立记录并确认删除

8. 目录冲突处理：用户决策

决策：安装前检查目标目录是否存在，存在时由用户决定是否覆盖。

场景：

  1. install.json 有记录 + 目录存在：已安装，询问是否覆盖
  2. install.json 无记录 + 目录存在：未被 skillmgr 管理的目录，询问是否覆盖
  3. install.json 有记录 + 目录不存在：孤立记录，清理记录后继续安装

用户交互：

Skill 'lyxy-kb' is already installed. Overwrite? [y/N]:

9. 项目结构：独立 Go 项目

决策：在 manager/ 目录下创建独立的 Go 项目，与现有 skills 仓库分离。

目录结构：

manager/
├── cmd/skillmgr/        # CLI 命令实现
├── internal/            # 内部包（不对外暴露）
│   ├── config/          # 配置文件读写
│   ├── repo/            # Git 仓库管理
│   ├── adapter/         # 平台适配器
│   ├── installer/       # 安装逻辑
│   └── prompt/          # 用户交互
├── pkg/                 # 可对外暴露的包
│   └── fileutil/        # 文件工具
├── go.mod
└── README.md

理由：

  • 不污染现有 skills 仓库结构
  • 工具本身可以独立开发、测试、发布
  • 清晰的模块边界

10. 测试隔离：环境变量注入

决策：通过环境变量覆盖配置和目标路径，实现零污染测试。

理由：

  • 测试不应影响用户的实际配置（~/.skillmgr/）和安装目录（~/.claude/）
  • 环境变量注入是轻量级且侵入性最小的方案
  • 支持并行测试（每个测试独立目录）

实现：

// 配置路径注入
func GetConfigRoot() (string, error) {
    if testRoot := os.Getenv("SKILLMGR_TEST_ROOT"); testRoot != "" {
        return testRoot, nil
    }
    // 生产模式...
}

// 目标路径注入
func getBasePath(scope Scope) (string, error) {
    if testBase := os.Getenv("SKILLMGR_TEST_BASE"); testBase != "" {
        return testBase, nil
    }
    // 生产模式...
}

测试使用：

func TestInstall(t *testing.T) {
    testRoot := t.TempDir()
    testBase := t.TempDir()
    os.Setenv("SKILLMGR_TEST_ROOT", testRoot)
    os.Setenv("SKILLMGR_TEST_BASE", testBase)
    defer os.Unsetenv("SKILLMGR_TEST_ROOT")
    defer os.Unsetenv("SKILLMGR_TEST_BASE")
    // 测试代码...
}

替代方案：

  • 依赖注入（将路径作为参数传递）：侵入性强，需要重构所有函数签名
  • Mock 文件系统（如 afero）：复杂度高，且无法测试真实文件系统行为
  • 专用测试模式标志：需要额外的全局状态管理

Risks / Trade-offs

1. 无版本管理

风险：用户无法回退到旧版本的 skill/command，更新可能引入破坏性变更。

缓解：

  • 文档中建议用户在重要项目中使用 git 管理项目配置目录（如 .claude/）
  • 工具记录 updated_at 时间，方便追溯

2. 无依赖解析

风险：安装 command 时，依赖的 skill 可能未安装（如 lyxy-kb 命令依赖 lyxy-reader-office skill）。

缓解：

  • 在 skill 的 SKILL.md 中明确记录依赖关系（如 compatibility 字段）
  • 错误提示中建议用户检查依赖
  • 未来可选增强：扫描 SKILL.md 提示缺失依赖

3. Git 依赖

风险：工具依赖系统中已安装 Git 客户端，无 Git 则无法拉取仓库。

缓解：

  • 在 README 中明确前置条件
  • 首次运行时检测 Git 是否可用，提示安装
  • 错误消息中包含 Git 安装指引

4. 跨文件系统移动失败

风险：os.Rename() 在跨文件系统时会失败（如 tmp 在 tmpfs，目标在 ext4）。

缓解：

  • 捕获 Rename 错误，fallback 到递归复制 + 删除 staging
  • 在事务实现中明确处理两种路径

5. 平台适配规则变化

风险：Claude Code 或 OpenCode 未来修改目录结构规范，导致工具失效。

缓解：

  • 将适配规则集中在 internal/adapter/ 包中，便于修改
  • 提供版本号，用户可锁定工具版本以保证稳定性
  • 文档中建议关注平台更新公告

6. 手动修改配置文件

风险：用户手动编辑 repository.json 或 install.json 可能破坏格式，导致解析失败。

缓解：

  • JSON 解析错误时提示备份并重建配置文件
  • 提供 doctor 命令（未来增强）诊断和修复配置
View Git Blame Copy Permalink