# @fantasticit/sumi 中文文档

规范地址：https://npmcn.com/package/%40fantasticit/sumi/

版本：0\.14\.5
npm 元数据更新时间：2026-11-13T06:13:23.947Z
中文译文更新时间：2026-11-14T10:00:30.028Z
软件包许可：未声明

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40fantasticit/sumi
原文对照：https://npmcn.com/package/%40fantasticit/sumi/?lang=original

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：7.6 MB，1439 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：10 个
- 首次发布：2026-10-15T12:05:22.418Z
- 最新版本发布：2026-11-13T06:13:23.697Z
- 近 30 天下载量：5637（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：30（近 12 个月 30 个）

## 中文简介

sumi 命令行

## 安装

```sh
npm install @fantasticit/sumi
```

也可以使用：`pnpm add @fantasticit/sumi`、`yarn add @fantasticit/sumi`、`bun add @fantasticit/sumi`

## README

# @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` 等。导入入口时会注册全部内置命令。

## 常见问题

### @fantasticit/sumi 是什么？

sumi 命令行

### 如何安装 @fantasticit/sumi？

在项目目录运行 npm install @fantasticit/sumi，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 sumi，可以用 npx sumi 直接运行。

### @fantasticit/sumi 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @fantasticit/sumi 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @fantasticit/sumi 可以商用吗？

@fantasticit/sumi 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @fantasticit/sumi 的下载量有多少？

根据 npm 官方下载统计，@fantasticit/sumi 在 2026/10/15 – 2026/11/13 这 30 天内被下载 5,637 次，日均约 188 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @fantasticit/sumi 还在维护吗？

最新版本 0\.14\.5 发布于 2026/11/13（1 天前）；至今共发布 30 个版本，其中过去 12 个月发布了 30 个；首次发布于 2026/10/15。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。