ai-kit

opencode 扩展工具集 (ai-kit)

本项目集中管理我要用的 opencode 自定义扩展：一部分是 commands-opencode/（斜杠指令），一部分是 skills/（技能）；同源逻辑还以 commands-dsh/ 插件形式接入 dsh（见 dsh 接入）。

目录结构

ai-kit/
├── README.md                  # 本说明
├── LICENSE
├── PUBLISHING.md              # npm 发包流程与踩坑说明（@morehao/dsh-commands / OIDC）
├── commands-opencode/          # opencode 斜杠指令
│   ├── README.md              # 指令功能与用法说明
│   └── git/                   # Git 相关指令
│       ├── branch.md
│       ├── message.md
│       ├── pr-create.md
│       ├── pr-merge.md
│       ├── tag.md
│       ├── commit-push.md
│       ├── slim.md
│       └── star-classify.md
├── commands-dsh/              # dsh 插件：git-kit 的 dsh 原生斜杠命令入口（命令=意图表，与 opencode 入口共享 git-kit）
│   ├── package.json
│   ├── cordis.patch.yml
│   ├── lib/index.js
│   └── README.md
├── scripts/
│   └── dsh-install.sh         # dsh 一键接入：软链 skills + 注册 commands-dsh 插件
└── skills/                    # 技能（opencode 与 dsh 共用）
    ├── git-kit/               # Git 工作流辅助（message/commit-push/branch/pr-create/pr-merge/tag/slim/star）
    │   ├── references/        # 拆分的辅助逻辑
    │   └── scripts/           # 附带脚本
    ├── project-insight/       # 开源项目深度解读
    │   ├── references/        # 拆分的辅助逻辑
    │   └── scripts/           # 附带脚本
    ├── tech-design/           # 技术方案/技术设计文档生成（原 tech-design-proposal / design-doc）
    │   ├── references/        # 三档骨架/场景义务包/专题加固/量化估算/质量红线
    │   └── scripts/           # Mermaid 校验薄壳（复用 project-insight 引擎）
    └── svg-maker/             # 自包含纯 SVG 图表生成
        └── references/

skills —— 技能

路径	功能
skills/git-kit	Git 工作流辅助工具包，按意图路由到生成 commit message、提交推送、创建/切换分支、创建/更新 PR/MR、按编号合并 PR/MR 并回主干更新、给分支打版本标签并推送、仓库瘦身、分类 star。
skills/project-insight	开源项目深度解读，产出每个论断都带可点开验证的真实源码引用（文件:行号），避免幻觉。
skills/tech-design（原 tech-design-proposal，曾用名 design-doc）	编写技术方案/技术设计文档：三轴决策——档位（轻量/标准/完整）定篇幅、场景（新建/增量改造/结构重构/替换与迁移/下线与废弃/专项优化，单选）定叙事起点与过程义务（影响面与兼容、行为基线与等价性验证、对账与回退窗口、消费者盘点与下线判据）、专题（架构/API/数据模型/性能与容量/安全/迁移手法，可多选）定技术加固点；强制量化义务（性能/容量/可用性/成本的论断须给数字 + 口径 + 假设，量级表见 quantification.md）与取舍对偶（每个选型写代价与不该选的场景），内嵌 Mermaid 图可脚本校验，产出量化、可执行、可评审的 Markdown 文档。
skills/svg-maker	生成自包含、纯 SVG 的架构图、流程图与概念图，可离线打开。

每个 skill 目录下是一个 SKILL.md（含 frontmatter 定义触发条件），复杂逻辑可拆到 references/ 子目录。skills/ 下只放各技能的目录，不放置说明性文件（见下方"用法说明"）。

联动：skills/git-kit 是 Git 工作流逻辑与意图路由的唯一真源；commands-opencode/git/*（opencode 斜杠）与 commands-dsh/（dsh 斜杠）只是命令入口，声明「命令 → git-kit 分支」映射并交给 git-kit 执行，互为多条入口（opencode 斜杠指令 / dsh 斜杠命令 / 自然语言触发）。

commands —— 斜杠指令

commands-opencode/ 下是与 Git 相关的自定义指令：

路径	功能
commands-opencode/git/branch	基于中文描述生成候选分支名，选择后从基准分支创建并切换
commands-opencode/git/message	将中文描述转换为 Conventional Commits 格式的 commit message（纯生成，不提交）
commands-opencode/git/pr-create	基于代码差异向目标仓库创建或更新 PR/MR（自动识别 gh/glab）
commands-opencode/git/pr-merge	按编号合并 PR/MR，删除原分支，切回主干并更新代码（自动识别 gh/glab）
commands-opencode/git/tag	查看最新 tag 与来源分支，选择要打 tag 的分支与版本号，构建注记 tag 并推送
commands-opencode/git/commit-push	基于代码变更自动生成 commit message 并执行提交推送
commands-opencode/git/slim	将当前 git 仓库瘦身为浅克隆，默认保留 30 天历史
commands-opencode/git/star-classify	拉取并分类自己的 GitHub star 仓库，输出中文分组清单

详见 commands-opencode/README.md。

dsh 接入（可选）

commands-dsh/ 以 dsh 原生命令形式暴露 git-kit 工作流：/git-message、/git-commit-push、/git-branch、/git-pr-create、/git-pr-merge、/git-tag、/git-slim、/git-star-classify。插件是自包含意图表（一行声明 = 命令名 + git-kit 分支 key），命令执行时向当前 agent 注入一条加载 git-kit 并按其分支执行的指令——与 opencode 入口共用 git-kit、单一真源，编辑 skills/git-kit/ 即同步生效（改插件 lib/index.js 需重启 dsh web）。

一键接入（幂等，可重复执行）：

./scripts/dsh-install.sh        # 默认接入 web profile；可用 DSH_PROFILE=<name> 指定
# 完成后重启 dsh web

脚本做两件事：① 软链 skills/* 到 $DSH_HOME/skills（默认 ~/.dsh/skills）；② dsh plugin --profile web add link:<本仓库>/commands-dsh（link: 为真软链，源码改动即生效；自动追加进 profile 的 bundles）。

插件已发布到 npm（@morehao/dsh-commands），也可只装命令插件本体：dsh plugin --profile web add @morehao/dsh-commands。注意 git-kit skill 仍需来自本仓库（dsh 不从 node_modules 扫描 skill），所以用 npm 方式时请另行软链 skills/* 或执行本脚本的 skills 步骤。发包/更新到 npm 的完整流程见 PUBLISHING.md。

卸载：dsh plugin --profile web remove @morehao/dsh-commands，再删除对应的 skill 软链即可。（旧版曾以 dsh-git-commands 或 @morehao/dsh-git-commands 安装过：对应 dsh plugin --profile web remove dsh-git-commands / dsh plugin --profile web remove @morehao/dsh-git-commands。）

详见 commands-dsh/README.md。

用法说明

这些命令与技能通过软链接注册到本机 opencode 配置目录来启用，不改动本仓库内的文件，便于后续 git pull 同步更新。配置目录默认为 ~/.config/opencode/。

将本仓库路径替换到下方命令中的 /path/to/ai-kit 后执行：

# 软链 skills 到 opencode 的 skills 目录
ln -sfn /path/to/ai-kit/skills/* ~/.config/opencode/skills/

# 软链 commands 到 opencode 的 command 目录
ln -sfn /path/to/ai-kit/commands-opencode/git ~/.config/opencode/command/git

约定：skills/ 下只放各技能的目录（如 git-kit/），不放置说明性文件。skills/* 会展开全部条目，若未来在 skills/ 新增非目录文件，会一并被软链到 skills 目录，故请保持该约定。

提示：若不希望跟随本仓库更新，也可改用复制方式（cp -r）；若本机已在对应位置存在同名真实目录，需先手动移走再由命令建立软链。

安装/卸载逻辑均只涉及本机配置目录（~/.config/opencode/）。commands-opencode/README.md 仅说明功能与用法，不重复安装步骤；本仓库的功能一览见本文档，各 skill 与指令的命名与目录结构见上文目录树。