@sumi/cli（发布名 @fantasticit/sumi）
本页说明当前仓库的 0.9.2 CLI 源码；本仓库 control 使用的已发布 0.10.3 依赖入口见根目录 README。
sumi 命令的入口：解析参数、调用内核运行流程、分发插件注册的命令、为 AI 工具生成适配（skills、commands 与 hook），并提供 init、doctor、context 等内置命令。五个插件包随 CLI 一起安装，内核从 CLI 自身的安装位置解析它们。
命令
项目根由当前目录向上查找含 control/config.yaml（或旧的 sumi.config.yaml）的目录确定。受管项目统一以 node ./control/bin/sumi.cjs 作为命令前缀；下表为省略此前缀后的子命令。首次接入使用 npm exec --offline --package <tgz> -- sumi init。大多数内置命令支持 --json 输出结构化结果。
| 命令 | 说明 |
|---|---|
sumi --version | 输出 CLI 版本 |
sumi run <flow> | 运行流程：--tier <档位>、--all、--base <ref>、--label k=v（可重复）；--commit <oid> [--base <oid>] 为固定提交模式，供插件在独立检出中验收指定提交。输出简报，退出码即结论 |
sumi instructions <主题> [--json] | 输出某个主题的操作指令 |
sumi fix <step-id> | 以当前工作树最近一次包含该步骤的运行范围执行插件声明的 fix；运行后内容又变化时拒绝 |
sumi update [--check] | 重新生成 AI 工具适配与 hook；--check 只报告漂移，有漂移时退出码 1 |
sumi hint | 会话结束提示：最近一次 check 运行未通过时输出 systemMessage，从不阻止结束 |
sumi doctor | 诊断：配置、版本、配置位置、各流程能否加载、适配漂移、工具能力缺口；hook 能否被加载（Codex 信任记录、本工作区 hook 配置是否落后上游、worktree 是否装了 Sumi）；外来接线只报告 |
init [目录] | --tools claude,codex,cursor（别名 --agents）。空目录或不存在的目录：生成模板项目并 git init；已有仓库：写入骨架、去掉 needs 不满足的步骤、生成适配与 hook、全量运行 check、执行插件的 afterInit |
sumi add plugin <name> | 在 control/plugins/<name>/ 生成 plugin.yaml、index.mjs、index.test.mjs（id 为 local/<name>），并把 control/plugins 加进配置的 plugins |
sumi context <路径...> | 写代码前查约束：check 流程中命中这些路径的检查、插件约束查询命令给出的条目、去重后的规则位置。默认摘要最多 6,000 字符，--full 输出原文，--json 保留完整结构 |
sumi task "<意图>" / sumi task --select <id,...> | 先取得有界任务目录，由宿主代理选择相关 ID，再按 ID 取得有界摘要；--full 强制原文。Sumi 不做关键词分类。 |
sumi task --eval <golden.jsonl> | 对冻结样本中宿主代理独立给出的 selected 与 expected ID 集合离线计算命中率、精确率和召回率，不调用模型自评。两者均为空的样本算命中；精确率或召回率分母为零时记 0。 |
sumi visualize [--port N] | 启动仅监听 127.0.0.1 的 HTML 服务，按会话查看送达了什么上下文、为什么送、为什么没送，并从宿主会话记录回读确认；也可查看提示词、宿主 Read 工具返回的项目文件、Sumi 命令与文档读取；Shell、MCP 和自动加载的读取不在当前观测范围内。事件持续保存在被忽略的 .sumi/visualize/events.jsonl，即使页面未启动；按 Ctrl+C 只关闭页面服务。 |
sumi vendor <sumi-cli-版本.tgz> | 校验离线安装包的完整构建身份，放进 control/vendor/（删除旧版本，必要时为 .gitignore 追加例外），在配置中写入 install、精确 sumi 版本与 sumiBuild，然后运行 sumi update |
sumi vendor --dependency [包名] | 使用已作为 devDependency 安装的 CLI（缺省 @fantasticit/sumi）：校验 node_modules 中的构建身份，清单改为记录包名、版本与身份，删除 control/vendor/ 下的离线安装包，然后运行 sumi update |
未匹配内置命令时，CLI 按项目注册表分发插件命令：以仓库根为工作目录执行其 argv 加剩余参数，环境中带 SUMI_ROOT 与 SUMI_BIN，原样返回退出码。插件命令不能与内置命令重名，只在已接入的项目中可用。不带参数或命令未知时列出可用命令，退出码 3；内核错误输出 内核错误：…，退出码 3。
会写文件的内置命令（init、vendor、update、add、fix）遇到 --help/-h 只打印用法、退出码 0；遇到未知参数（含 -x 这类短参数）以内核错误结束、退出码 3；两种情况都不执行写入。插件包中会写文件的命令（adopt、baseline、promote、submit、pr-report）用插件 SDK 的 guardCommandArgs 做同样的检查，未知参数沿用各命令原有的用法错误退出码。
AI 工具适配
AI 工具只加载会话启动目录的 hook。插件声明的写入前与编辑后 hook 运行时，CLI 会先看写入目标属于哪个项目：目标在另一个已接入 Sumi 的项目或 worktree 中，就用同一条命令和同一份负载交给那个项目安装的 Sumi 判定（任一项目拒绝即拒绝写入）；那个项目没有安装 Sumi 时拒绝写入并提示安装依赖；目标不属于任何项目（如临时目录）时不处理。
sumi update（以及 init、vendor）按项目配置的 agents 生成适配；未配置时只启用 claude。每个生成文件带 generated-by: sumi update 标记与内容摘要，--check 与 doctor 据此报告手改、缺失和已无对应主题的旧文件；不带标记的项目文件不会被视为生成物。
| 位置 | 内容 |
|---|---|
.agents/skills/sumi-<主题>/SKILL.md | skill 完整正文（任一工具启用时生成） |
.agents/commands/sumi/<主题>.md | command 完整正文 |
.claude/skills/sumi-<主题>/SKILL.md、.claude/commands/sumi/<主题>.md | 引用桩：只有一句指向 .agents 对应文件的指令 |
.cursor/rules/sumi-<主题>.mdc、.cursor/commands/sumi-<主题>.md | 引用桩（rule 另附 @file <目标>，alwaysApply: false） |
| Codex | 不生成桩，直接读取 .agents |
所有主题都生成 command；只有 skill 主题生成 skill。
hook
| 工具 | 写入位置 | 条目 |
|---|---|---|
| Claude | .claude/settings.json | SessionStart、SubagentStart → hook session-start、hook subagent-start 主动注入；PreToolUse（Bash|Edit|Write|MultiEdit|NotebookEdit）→ 插件的 beforeTool；PostToolUse（编辑与读取工具）→ hook after-tool；UserPromptSubmit → hook user-prompt；Stop → hook stop 汇总检查与提示 |
| Codex | .codex/hooks.json | SessionStart、SubagentStart → 同上；PreToolUse（^(Bash|apply_patch|Edit|Write)$）、PostToolUse（编辑与读取工具）、UserPromptSubmit → 单入口；Stop → hook stop |
| Cursor | .cursor/hooks.json | sessionStart → 注入规则与任务目录；preToolUse → 单入口守卫；postToolUse → 编辑后上下文；stop → 单入口停止检查 |
AI 工具以会话当前目录执行 hook，会话可能位于项目子目录，因此命令不依赖当前目录定位 launcher：
| 工具 | 命令 |
|---|---|
| Claude | node "$CLAUDE_PROJECT_DIR/control/bin/sumi.cjs" <命令>（sh 执行，Windows 上为 Git Bash） |
| Codex | node "$(git rev-parse --show-toplevel)/control/bin/sumi.cjs" <命令>；Windows（cmd.exe）用 commandWindows：for /f "delims=" %r in ('git rev-parse --show-toplevel') do @node "%r/control/bin/sumi.cjs" <命令> |
| Cursor | node ./control/bin/sumi.cjs <命令>（项目 hook 固定从项目根执行） |
前置拦截只有退出码 2 会阻断，因此前置拦截条目追加 || exit 2：找不到 launcher、runtime 无效或命令崩溃时同样拒绝，命令的标准错误即拒绝说明。编辑后与停止检查条目的退出码原样返回。
更新时只增删 sumi 的条目（命令以上述 launcher 写法、旧版本的 node ./control/bin/sumi.cjs 、sumi 开头），其他条目保留；旧写法的条目被 --check 与 doctor 报告为漂移，由 sumi update 替换。
git hook 固定包含 pre-commit → node ./control/bin/sumi.cjs run check，其余由插件 hooks.git 声明（同一 hook 不能被重复声明）。写入位置取决于 hook 管理器：
| 管理器 | 识别方式 | 写入 |
|---|---|---|
| 原生 | 未设置 core.hooksPath、没有 lefthook 配置 | git hooks 目录下由 sumi 独占的脚本 |
| husky | core.hooksPath 指向 .husky | .husky/<hook> 中的 sumi 区块，区块之外的内容原样保留 |
| 其他 | 其他 hooksPath 或存在 lefthook 配置 | 不写入，doctor 提示手动调用对应的 sumi 命令 |
hook 只调用项目 launcher；launcher、runtime 清单或 vendored 安装包缺失/无效时拒绝，并提示重新用目标版本安装包执行临时 vendor。依赖方式下已安装的依赖与清单身份不一致（例如刚 pnpm add -D @fantasticit/sumi@<新版本>）时，launcher 只放行 vendor --dependency，用已安装的依赖重新锁定；其他命令拒绝，提示重新安装依赖或运行 vendor --dependency。PATH 中是否存在全局 sumi 不影响项目执行。
指令主题
| 主题 | 来源 | 形态 | 内容 |
|---|---|---|---|
develop | CLI 内置 | skill + command | 先 sumi task 选择任务范围，再 sumi context 查路径约束、实现并运行 sumi run check；列出项目的区域、档位、流程与其他主题 |
check | CLI 内置 | command | 运行检查流程并按简报中的 next 处理 |
doctor | CLI 内置 | command | 运行 sumi doctor 并修复 |
| 其他 | 插件包 | 按指令文件 | 插件声明的 instructions（主题名 → Markdown 文件） |
插件指令文件的 frontmatter 中 description: 作为说明，skill: false 表示只生成 command。主题重名或文件不存在时报错。
离线打包
| 脚本 | 说明 |
|---|---|
scripts/pack.mjs（pnpm pack:cli） | 构建全部包与单文件 launcher，pnpm deploy 出扁平的 node_modules，改写清单（发布名 @fantasticit/sumi）并产出 dist/sumi-cli-<版本>.tgz，可直接 npm publish。安装包只用于临时 init/vendor 与项目 vendoring；项目工具（ESLint、Prettier、TypeScript 等）不打包 |
scripts/verify-pack.mjs | 在隔离 PATH、无全局 Sumi 的环境中临时执行本地 tgz，验证 init、vendor、update、doctor 与项目 launcher 的 run check；runtime 准备过程保持离线 |
本仓库通过项目插件 repo/pack（control/plugins/pack/）在 full 档运行 verify-pack.mjs。
导出
包入口导出 main(argv, io)、parseArgs、findRoot、registerCommand、requireRoot、emit，以及适配相关的 ADAPTERS、sync、checkDrift、declaredHooks、hookManager、capabilityGaps、enabledAgents 等。导入入口时会注册全部内置命令。