@fantasticit/sumi 0.0.0-stage → 0.5.1

package/README.md

@@ -1,3 +1,82 @@
-# Temporary Holding Version
+# @sumi/cli（发布名 `@fantasticit/sumi`）
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+`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`                       | 诊断：配置、版本、配置位置、各流程能否加载、适配漂移、工具能力缺口；外来接线只报告                                                                                                                          |
+| `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` 流程中命中这些路径的检查、插件约束查询命令给出的条目、引用这些执行者的规则原文（control 区与 `AGENTS.md` 中的 Markdown）                                                            |
+| `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。
+
+## AI 工具适配
+
+`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` | `PreToolUse`（`Bash\|Edit\|Write\|MultiEdit\|NotebookEdit`）→ 插件的 `beforeTool`；`PostToolUse`（编辑类工具）→ `afterEdit`；`Stop` → `sumi hint` |
+| Codex  | `.codex/hooks.json`     | `PreToolUse`（`^(Bash\|apply_patch\|Edit\|Write)$`）、`PostToolUse`（`^(apply_patch\|Edit\|Write)$`）；无会话结束提示                             |
+| Cursor | —                       | 不支持 hook，`doctor` 报告能力缺口，依赖 git hook 兜底                                                                                            |
+
+更新时只增删命令以 `sumi ` 开头的条目，其他条目保留。
+
+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`。PATH 中是否存在全局 `sumi` 不影响项目执行。
+
+## 指令主题
+
+| 主题      | 来源     | 形态            | 内容                                                                                            |
+| --------- | -------- | --------------- | ----------------------------------------------------------------------------------------------- |
+| `develop` | CLI 内置 | skill + command | 先 `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` 等。导入入口时会注册全部内置命令。

package/dist/adapters.d.ts

@@ -0,0 +1,86 @@
+import { type SumiConfig, type Registry } from '@sumi/kernel';
+/** 每个 AI 工具适配器如实声明它在该工具上能实现的能力。 */
+export interface Capabilities {
+    editIntercept: boolean;
+    commandIntercept: boolean;
+    afterEdit: boolean;
+    stopCheck: boolean;
+    commands: boolean;
+}
+/** 生成到某个目录下的一类文件；render 的 target 是被引用的 .agents 文件（只有引用桩使用）。 */
+interface Output {
+    dir: string;
+    pattern: RegExp;
+    path: (name: string) => string;
+    render: (name: string, description: string, target: string) => string;
+}
+/** AI 工具的 hook 配置文件：只增删 sumi 条目，保留其他条目。 */
+interface AgentHookFile {
+    path: string;
+    format: 'nested' | 'cursor';
+    /** 前置拦截覆盖的工具（命令与编辑类）。 */
+    before?: string;
+    /** 编辑后反馈覆盖的编辑类工具。 */
+    afterEdit?: string;
+    /** 没有插件停止检查时也生成不阻断的会话结束提示。 */
+    hint?: boolean;
+}
+export interface Adapter {
+    name: string;
+    capabilities: Capabilities;
+    /** 引用 .agents 中 skill 的桩；工具原生读取 .agents 时不需要。 */
+    skill?: Output;
+    command?: Output;
+    hooks?: AgentHookFile;
+}
+export declare const MARK = "generated-by: sumi update";
+/** skills 与 commands 的完整正文只生成在 .agents：任一工具启用时都生成，Codex 直接读取。 */
+export declare const AGENTS_SKILL: Output;
+export declare const AGENTS_COMMAND: Output;
+export declare const ADAPTERS: Record<string, Adapter>;
+/** 收集插件声明的 hook：git hook 名称 → 命令，以及 AI 工具前置、编辑后与停止检查命令。 */
+export declare function declaredHooks(registry: Registry): {
+    git: Map<string, string[]>;
+    beforeTool: string[];
+    afterEdit: string[];
+    stop: string[];
+};
+export type HookManager = 'git' | 'husky' | 'other';
+/** 识别 hook 管理器：husky（core.hooksPath 指向 .husky）、原生 git hook、其他（自定义 hooksPath 或 lefthook 等）。 */
+export declare function hookManager(root: string): HookManager;
+export declare function gitHooksDir(root: string): string;
+/** 把 sumi 区块写入 husky 的 hook 文件：替换已有区块或追加，标记之外的内容原样保留。 */
+export declare function withBlock(existing: string | null, block: string): string;
+export interface Drift {
+    path: string;
+    problem: string;
+}
+export interface UpdateFilePlan {
+    action: 'write' | 'delete';
+    /** 相对仓库路径；原生 Git hook 位于 .git 时使用展示标签。 */
+    path: string;
+    /** 实际写入目标，仅供计划应用器使用。 */
+    target: string;
+    content?: string;
+    mode?: number;
+}
+export declare function enabledAgents(config: SumiConfig): string[];
+/** AI 工具 hook 配置文件中不是由 sumi 生成的命令（纳管的接线债务）。 */
+export declare function foreignAgentHooks(root: string): {
+    file: string;
+    command: string;
+}[];
+/** git hook 文件中 sumi 区块之外的命令行（不计 shebang、空行与注释）。husky 为 .husky/<hook>，原生为 git hooks 目录。 */
+export declare function foreignGitHookLines(root: string): {
+    file: string;
+    command: string;
+}[];
+export declare function readHookFile(root: string, path: string): Record<string, unknown>;
+export declare function checkDrift(root: string): Drift[];
+/** 只读计算 update 的完整文件计划；不写文件，也不理解具体插件命令。 */
+export declare function updatePlan(root: string): UpdateFilePlan[];
+export declare function applyUpdatePlan(plan: UpdateFilePlan[]): string[];
+export declare function sync(root: string): string[];
+/** 已启用工具缺失的能力及因此失去的保证；其他 hook 管理器需要手动接入。 */
+export declare function capabilityGaps(root: string): string[];
+export {};

package/dist/adapters.js

@@ -0,0 +1,469 @@
+import { execFileSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { chmodSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { KernelError, loadConfig, loadFlow, loadRegistry } from '@sumi/kernel';
+import { gitHookScript, HOOK_BLOCK_END, HOOK_BLOCK_START, hookBlock, PROJECT_SUMI } from '@sumi/plugin-sdk';
+import { projectInstruction, topicContext, topics } from './instructions.js';
+import { fileSha256, PROJECT_LAUNCHER, RUNTIME_MANIFEST, runtimeManifestText } from './runtime-manifest.js';
+export const MARK = 'generated-by: sumi update';
+const HOOK_PREFIX = `${PROJECT_SUMI} `;
+/** 旧版本生成的 hook 命令前缀，更新时一并识别为 sumi 的条目。 */
+const LEGACY_PREFIXES = ['sumi ', 'npx --no-install sumi '];
+const hash = (text) => createHash('sha256').update(text).digest('hex').slice(0, 16);
+const marked = (body) => `<!-- ${MARK}; content-hash: ${hash(body)} -->\n${body}`;
+const skillFront = (name, description) => `---\nname: ${name}\ndescription: ${description}\n---\n`;
+/** 项目已改用依赖方式时，现有 runtime 清单中记录的包名。 */
+function dependencyPackage(root) {
+    try {
+        const manifest = JSON.parse(readFileSync(join(root, RUNTIME_MANIFEST), 'utf8'));
+        return typeof manifest.package === 'string' ? manifest.package : null;
+    }
+    catch {
+        return null;
+    }
+}
+function launcherBundle() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    return [join(here, 'launcher.cjs'), join(here, '../dist/launcher.cjs')].find(existsSync) ?? null;
+}
+/** skills 与 commands 的完整正文只生成在 .agents：任一工具启用时都生成，Codex 直接读取。 */
+export const AGENTS_SKILL = {
+    dir: '.agents/skills',
+    pattern: /^sumi-/,
+    path: (n) => `.agents/skills/sumi-${n}/SKILL.md`,
+    render: (n, d, body) => `${skillFront(`sumi-${n}`, d)}${marked(body)}`,
+};
+export const AGENTS_COMMAND = {
+    dir: '.agents/commands/sumi',
+    pattern: /\.md$/,
+    path: (n) => `.agents/commands/sumi/${n}.md`,
+    render: (_n, d, body) => `---\ndescription: ${d}\n---\n${marked(body)}`,
+};
+/** 引用桩的正文：只有一句指向 .agents 完整正文的指令。 */
+const stubBody = (target) => `完整读取并严格按照 \`${target}\` 执行；本文件只是引用，不包含指令正文。\n`;
+export const ADAPTERS = {
+    claude: {
+        name: 'claude',
+        capabilities: { editIntercept: true, commandIntercept: true, afterEdit: true, stopCheck: true, commands: true },
+        hooks: {
+            path: '.claude/settings.json',
+            format: 'nested',
+            before: 'Bash|Edit|Write|MultiEdit|NotebookEdit',
+            afterEdit: 'Edit|Write|MultiEdit|NotebookEdit',
+            hint: true,
+        },
+        skill: {
+            dir: '.claude/skills',
+            pattern: /^sumi-/,
+            path: (n) => `.claude/skills/sumi-${n}/SKILL.md`,
+            render: (n, d, target) => `${skillFront(`sumi-${n}`, d)}${marked(stubBody(target))}`,
+        },
+        command: {
+            dir: '.claude/commands/sumi',
+            pattern: /\.md$/,
+            path: (n) => `.claude/commands/sumi/${n}.md`,
+            render: (_n, d, target) => `---\ndescription: ${d}\n---\n${marked(stubBody(target))}`,
+        },
+    },
+    codex: {
+        name: 'codex',
+        capabilities: { editIntercept: true, commandIntercept: true, afterEdit: true, stopCheck: true, commands: false },
+        hooks: {
+            path: '.codex/hooks.json',
+            format: 'nested',
+            before: '^(Bash|apply_patch|Edit|Write)$',
+            afterEdit: '^(apply_patch|Edit|Write)$',
+        },
+    },
+    cursor: {
+        name: 'cursor',
+        capabilities: { editIntercept: false, commandIntercept: false, afterEdit: false, stopCheck: true, commands: true },
+        hooks: { path: '.cursor/hooks.json', format: 'cursor' },
+        skill: {
+            dir: '.cursor/rules',
+            pattern: /^sumi-.+\.mdc$/,
+            path: (n) => `.cursor/rules/sumi-${n}.mdc`,
+            render: (_n, d, target) => `---\ndescription: ${d}\nalwaysApply: false\n---\n${marked(`${stubBody(target)}\n@file ${target}\n`)}`,
+        },
+        command: {
+            dir: '.cursor/commands',
+            pattern: /^sumi-.+\.md$/,
+            path: (n) => `.cursor/commands/sumi-${n}.md`,
+            render: (_n, _d, target) => marked(stubBody(target)),
+        },
+    },
+};
+/** 收集插件声明的 hook：git hook 名称 → 命令，以及 AI 工具前置、编辑后与停止检查命令。 */
+export function declaredHooks(registry) {
+    const git = new Map([['pre-commit', ['run', 'check']]]);
+    const owner = new Map([['pre-commit', '内核']]);
+    const beforeTool = [];
+    const afterEdit = [];
+    const stop = [];
+    for (const { decl } of registry.plugins.values()) {
+        for (const [hook, command] of Object.entries(decl.hooks?.git ?? {})) {
+            if (owner.has(hook))
+                throw new KernelError(`git hook ${hook} 被重复声明（${owner.get(hook)} 与 ${decl.id}）`);
+            owner.set(hook, decl.id);
+            git.set(hook, [command]);
+        }
+        if (decl.hooks?.agent?.beforeTool)
+            beforeTool.push(decl.hooks.agent.beforeTool);
+        if (decl.hooks?.agent?.afterEdit)
+            afterEdit.push(decl.hooks.agent.afterEdit);
+        if (decl.hooks?.agent?.stop)
+            stop.push(decl.hooks.agent.stop);
+    }
+    return { git, beforeTool, afterEdit, stop };
+}
+/** 识别 hook 管理器：husky（core.hooksPath 指向 .husky）、原生 git hook、其他（自定义 hooksPath 或 lefthook 等）。 */
+export function hookManager(root) {
+    let hooksPath = '';
+    try {
+        hooksPath = execFileSync('git', ['config', 'core.hooksPath'], { cwd: root, encoding: 'utf8', windowsHide: true }).trim();
+    }
+    catch {
+        hooksPath = '';
+    }
+    if (/(^|\/)\.husky(\/|$)/.test(hooksPath))
+        return 'husky';
+    if (hooksPath)
+        return 'other';
+    if (['lefthook.yml', 'lefthook.yaml', '.lefthook.yml'].some((f) => existsSync(join(root, f))))
+        return 'other';
+    return 'git';
+}
+export function gitHooksDir(root) {
+    return resolve(root, execFileSync('git', ['rev-parse', '--git-path', 'hooks'], { cwd: root, encoding: 'utf8', windowsHide: true }).trim());
+}
+/** 把 sumi 区块写入 husky 的 hook 文件：替换已有区块或追加，标记之外的内容原样保留。 */
+export function withBlock(existing, block) {
+    if (existing === null)
+        return `${block}\n`;
+    const start = existing.indexOf(HOOK_BLOCK_START);
+    const end = existing.indexOf(HOOK_BLOCK_END);
+    if (start >= 0 && end > start)
+        return existing.slice(0, start) + block + existing.slice(end + HOOK_BLOCK_END.length);
+    return `${existing}${existing.endsWith('\n') ? '' : '\n'}${block}\n`;
+}
+function agentHookGroups(agent, h, hooks) {
+    if (h.format === 'cursor') {
+        return hooks.stop.length ? { stop: [{ command: `${HOOK_PREFIX}hook agent-stop ${agent}`, type: 'command', loop_limit: null }] } : {};
+    }
+    const entry = (matcher, commands) => ({
+        matcher,
+        hooks: commands.map((command) => ({ type: 'command', command: `${HOOK_PREFIX}${command}` })),
+    });
+    const stopCommands = [...(h.hint ? ['hint'] : []), ...(hooks.stop.length ? [`hook agent-stop ${agent}`] : [])];
+    return {
+        ...(hooks.beforeTool.length && h.before ? { PreToolUse: [entry(h.before, hooks.beforeTool)] } : {}),
+        ...(hooks.afterEdit.length && h.afterEdit ? { PostToolUse: [entry(h.afterEdit, hooks.afterEdit)] } : {}),
+        ...(stopCommands.length
+            ? { Stop: [{ hooks: stopCommands.map((command) => ({ type: 'command', command: `${HOOK_PREFIX}${command}` })) }] }
+            : {}),
+    };
+}
+export function enabledAgents(config) {
+    const agents = config.agents ?? ['claude'];
+    return agents.filter((a) => a in ADAPTERS);
+}
+function listFlows(root, config, registry) {
+    const dir = join(root, config.flows);
+    if (!existsSync(dir))
+        return [];
+    return readdirSync(dir)
+        .filter((f) => f.endsWith('.flow.yaml'))
+        .sort()
+        .map((f) => loadFlow(root, config, registry, f.replace(/\.flow\.yaml$/, '')));
+}
+function expected(root) {
+    const config = loadConfig(root);
+    const registry = loadRegistry(root, config);
+    // 加载每个流程以校验其合法；指令中的流程清单来自同一批文件。
+    listFlows(root, config, registry);
+    const available = topics(root);
+    const ctx = topicContext(root);
+    const hooks = declaredHooks(registry);
+    const files = new Map();
+    if (config.sumi && config.sumiBuild) {
+        const archive = `control/vendor/sumi-cli-${config.sumi}.tgz`;
+        const archivePath = join(root, archive);
+        const launcher = launcherBundle();
+        const dependency = dependencyPackage(root);
+        if (dependency && launcher) {
+            // 依赖方式：清单记录包名与身份，CLI 由包管理器安装
+            files.set(PROJECT_LAUNCHER, readFileSync(launcher, 'utf8'));
+            const manifest = { package: dependency, build: config.sumiBuild, version: config.sumi };
+            files.set(RUNTIME_MANIFEST, runtimeManifestText(manifest));
+        }
+        else if (existsSync(archivePath) && launcher) {
+            files.set(PROJECT_LAUNCHER, readFileSync(launcher, 'utf8'));
+            files.set(RUNTIME_MANIFEST, runtimeManifestText({ archive, archiveSha256: fileSha256(archivePath), build: config.sumiBuild, version: config.sumi }));
+        }
+    }
+    const stale = [];
+    const agents = enabledAgents(config);
+    /** 生成一类文件并登记清理范围：不再对应任何主题的旧文件视为漂移。 */
+    const emitAll = (out, names, render) => {
+        const keep = new Set();
+        for (const name of names) {
+            const path = out.path(name);
+            files.set(path, render(name));
+            keep.add(path);
+        }
+        stale.push({ dir: out.dir, pattern: out.pattern, keep, nested: out.path('x').endsWith('/SKILL.md') });
+    };
+    if (agents.length) {
+        const skillTopics = [...available].filter(([, t]) => t.skill).map(([n]) => n);
+        const allTopics = [...available.keys()];
+        emitAll(AGENTS_SKILL, skillTopics, (n) => AGENTS_SKILL.render(n, projectInstruction(available.get(n).description), projectInstruction(available.get(n).text(ctx))));
+        emitAll(AGENTS_COMMAND, allTopics, (n) => AGENTS_COMMAND.render(n, projectInstruction(available.get(n).description), projectInstruction(available.get(n).text(ctx))));
+        for (const name of agents) {
+            const adapter = ADAPTERS[name];
+            if (adapter.skill) {
+                emitAll(adapter.skill, skillTopics, (n) => adapter.skill.render(n, available.get(n).description, AGENTS_SKILL.path(n)));
+            }
+            if (adapter.command) {
+                emitAll(adapter.command, allTopics, (n) => adapter.command.render(n, available.get(n).description, AGENTS_COMMAND.path(n)));
+            }
+        }
+    }
+    const agentHooks = new Map();
+    for (const name of enabledAgents(config)) {
+        const h = ADAPTERS[name].hooks;
+        if (h) {
+            const groups = agentHookGroups(name, h, hooks);
+            if (Object.keys(groups).length)
+                agentHooks.set(h.path, groups);
+        }
+    }
+    return { files, agentHooks, gitHooks: hooks.git, manager: hookManager(root), stale };
+}
+const isSumiCommand = (command) => !!command && (command.startsWith(HOOK_PREFIX) || LEGACY_PREFIXES.some((prefix) => command.startsWith(prefix)));
+function commandsInHookEntry(entry) {
+    if (!entry || typeof entry !== 'object')
+        return [];
+    const record = entry;
+    const direct = typeof record.command === 'string' ? [record.command] : [];
+    const nested = Array.isArray(record.hooks)
+        ? record.hooks.flatMap((hook) => hook && typeof hook === 'object' && typeof hook.command === 'string'
+            ? [hook.command]
+            : [])
+        : [];
+    return [...direct, ...nested];
+}
+/** AI 工具 hook 配置文件中不是由 sumi 生成的命令（纳管的接线债务）。 */
+export function foreignAgentHooks(root) {
+    const out = [];
+    for (const path of new Set(Object.values(ADAPTERS).flatMap((a) => (a.hooks ? [a.hooks.path] : [])))) {
+        const groups = (readHookFile(root, path).hooks ?? {});
+        for (const [event, list] of Object.entries(groups)) {
+            for (const entry of list) {
+                for (const command of commandsInHookEntry(entry)) {
+                    if (!isSumiCommand(command))
+                        out.push({ file: path, command: `${event}: ${command}` });
+                }
+            }
+        }
+    }
+    return out;
+}
+/** git hook 文件中 sumi 区块之外的命令行（不计 shebang、空行与注释）。husky 为 .husky/<hook>，原生为 git hooks 目录。 */
+export function foreignGitHookLines(root) {
+    const manager = hookManager(root);
+    const dir = manager === 'husky' ? join(root, '.husky') : manager === 'git' ? gitHooksDir(root) : null;
+    if (!dir || !existsSync(dir))
+        return [];
+    const label = manager === 'husky' ? '.husky' : 'git hooks';
+    const out = [];
+    for (const name of readdirSync(dir).sort()) {
+        const full = join(dir, name);
+        if (name.startsWith('_') || name.startsWith('.') || name.endsWith('.sample') || !statSync(full).isFile())
+            continue;
+        let inBlock = false;
+        for (const raw of readFileSync(full, 'utf8').split('\n')) {
+            const line = raw.trim();
+            if (line === HOOK_BLOCK_START)
+                inBlock = true;
+            else if (line === HOOK_BLOCK_END)
+                inBlock = false;
+            else if (!inBlock && line && !line.startsWith('#'))
+                out.push({ file: `${label}/${name}`, command: line });
+        }
+    }
+    return out;
+}
+function isSumiEntry(entry) {
+    return commandsInHookEntry(entry).some(isSumiCommand);
+}
+export function readHookFile(root, path) {
+    const full = join(root, path);
+    return existsSync(full) ? JSON.parse(readFileSync(full, 'utf8')) : {};
+}
+function sumiHooksIn(settings) {
+    const hooks = (settings.hooks ?? {});
+    const out = {};
+    for (const [event, groups] of Object.entries(hooks)) {
+        const ours = groups.filter(isSumiEntry);
+        if (ours.length)
+            out[event] = ours;
+    }
+    return out;
+}
+/** 每个 git hook 的落点与期望内容：husky 为 .husky/<hook> 中的区块，原生为独占文件。 */
+function hookTargets(root, exp) {
+    if (exp.manager === 'other')
+        return [];
+    return [...exp.gitHooks].map(([name, command]) => {
+        if (exp.manager === 'husky') {
+            const block = hookBlock(command);
+            return {
+                name,
+                path: join(root, '.husky', name),
+                label: `.husky/${name}`,
+                // 提交在仓库里的 hook 被检出为 CRLF 时 sh 无法解析（`}\r`），行尾也算作漂移。
+                ok: (t) => t !== null && !t.includes('\r') && t.includes(block),
+                next: (t) => withBlock(t?.replace(/\r\n/g, '\n') ?? null, block),
+            };
+        }
+        const script = gitHookScript(command);
+        return { name, path: join(gitHooksDir(root), name), label: `git hooks/${name}`, ok: (t) => t === script, next: () => script };
+    });
+}
+const read = (path) => (existsSync(path) ? readFileSync(path, 'utf8').replace(/\r\n/g, '\n') : null);
+const readRaw = (path) => (existsSync(path) ? readFileSync(path, 'utf8') : null);
+/** husky 的 hook 提交在仓库中：要求 git 以 LF 检出，否则 Windows（core.autocrlf=true）上 hook 无法执行。 */
+const HUSKY_EOL = '.husky/** text=auto eol=lf';
+const missingHuskyEol = (root, exp) => exp.manager === 'husky' && !(read(join(root, '.gitattributes')) ?? '').split('\n').includes(HUSKY_EOL);
+const withHuskyEol = (text) => `${text ?? ''}${text && !text.endsWith('\n') ? '\n' : ''}# sumi：husky hook 必须以 LF 检出\n${HUSKY_EOL}\n`;
+export function checkDrift(root) {
+    const exp = expected(root);
+    const drift = [];
+    for (const [path, content] of exp.files) {
+        const text = read(join(root, path));
+        if (text === null)
+            drift.push({ path, problem: '缺失，需要生成' });
+        else if (text !== content)
+            drift.push({ path, problem: '与 control 层不一致（被手改或未重新生成）' });
+    }
+    for (const { dir, pattern, keep, nested } of exp.stale) {
+        const full = join(root, dir);
+        if (!existsSync(full))
+            continue;
+        for (const name of readdirSync(full).filter((n) => pattern.test(n))) {
+            const candidate = nested ? `${dir}/${name}/SKILL.md` : `${dir}/${name}`;
+            // 只有带生成标记的文件才是 sumi 的生成物；同名前缀的项目文件不算漂移。
+            if (!keep.has(candidate) && read(join(root, candidate))?.includes(MARK)) {
+                drift.push({ path: candidate, problem: '对应的主题已不存在' });
+            }
+        }
+    }
+    const sorted = (o) => JSON.stringify(Object.fromEntries(Object.entries(o).sort(([a], [b]) => a.localeCompare(b))));
+    for (const [path, groups] of exp.agentHooks) {
+        if (sorted(sumiHooksIn(readHookFile(root, path))) !== sorted(groups))
+            drift.push({ path, problem: 'sumi hook 条目缺失或被修改' });
+    }
+    for (const target of hookTargets(root, exp)) {
+        const text = readRaw(target.path);
+        if (!target.ok(text))
+            drift.push({ path: target.label, problem: text?.includes('\r') ? '行尾为 CRLF，sh 无法执行' : '未安装或被修改' });
+    }
+    if (missingHuskyEol(root, exp))
+        drift.push({ path: '.gitattributes', problem: `缺少 ${HUSKY_EOL}` });
+    return drift;
+}
+/** 只读计算 update 的完整文件计划；不写文件，也不理解具体插件命令。 */
+export function updatePlan(root) {
+    const exp = expected(root);
+    const plan = [];
+    for (const [path, content] of exp.files) {
+        const full = join(root, path);
+        if (read(full) === content)
+            continue;
+        plan.push({ action: 'write', path, target: full, content });
+    }
+    // 删除不再对应任何主题的旧生成物；只删带生成标记的文件，项目自己的文件保持不动。
+    for (const { dir, pattern, keep, nested } of exp.stale) {
+        const full = join(root, dir);
+        if (!existsSync(full))
+            continue;
+        for (const name of readdirSync(full).filter((n) => pattern.test(n))) {
+            const candidate = nested ? `${dir}/${name}/SKILL.md` : `${dir}/${name}`;
+            if (keep.has(candidate) || !read(join(root, candidate))?.includes(MARK))
+                continue;
+            plan.push({ action: 'delete', path: candidate, target: join(root, nested ? `${dir}/${name}` : candidate) });
+        }
+    }
+    for (const [path, groups] of exp.agentHooks) {
+        const settings = readHookFile(root, path);
+        const hooks = (settings.hooks ?? {});
+        for (const event of Object.keys(hooks)) {
+            hooks[event] = hooks[event].filter((g) => !isSumiEntry(g));
+            if (hooks[event].length === 0)
+                delete hooks[event];
+        }
+        for (const [event, ours] of Object.entries(groups))
+            hooks[event] = [...(hooks[event] ?? []), ...ours];
+        const next = JSON.stringify({ ...settings, hooks }, null, 2) + '\n';
+        const full = join(root, path);
+        if (read(full) !== next) {
+            plan.push({ action: 'write', path, target: full, content: next });
+        }
+    }
+    for (const target of hookTargets(root, exp)) {
+        const current = readRaw(target.path);
+        if (target.ok(current))
+            continue;
+        plan.push({ action: 'write', path: target.label, target: target.path, content: target.next(current), mode: 0o755 });
+    }
+    if (missingHuskyEol(root, exp)) {
+        const target = join(root, '.gitattributes');
+        plan.push({ action: 'write', path: '.gitattributes', target, content: withHuskyEol(readRaw(target)) });
+    }
+    return plan;
+}
+export function applyUpdatePlan(plan) {
+    for (const item of plan) {
+        if (item.action === 'delete') {
+            rmSync(item.target, { recursive: true, force: true });
+            continue;
+        }
+        mkdirSync(dirname(item.target), { recursive: true });
+        writeFileSync(item.target, item.content);
+        if (item.mode !== undefined)
+            chmodSync(item.target, item.mode);
+    }
+    return plan.map((item) => (item.action === 'delete' ? `${item.path}（已删除）` : item.path));
+}
+export function sync(root) {
+    return applyUpdatePlan(updatePlan(root));
+}
+/** 已启用工具缺失的能力及因此失去的保证；其他 hook 管理器需要手动接入。 */
+export function capabilityGaps(root) {
+    const config = loadConfig(root);
+    const registry = loadRegistry(root, config);
+    const { beforeTool, afterEdit, stop, git } = declaredHooks(registry);
+    const fallback = [...git.keys()].filter((h) => h !== 'pre-commit').join('、') || 'pre-commit';
+    const gaps = [];
+    if (hookManager(root) === 'other') {
+        gaps.push(`未识别的 hook 管理器：请手动在 ${[...git.keys()].join('、')} 中分别调用 ${[...git.values()].map((c) => `${PROJECT_SUMI} ${c.join(' ')}`).join('、')}`);
+    }
+    for (const name of enabledAgents(config)) {
+        const c = ADAPTERS[name].capabilities;
+        const via = `插件声明的拦截（${beforeTool.join('、')}）不生效，依赖 git hook（${fallback}）兜底`;
+        if (beforeTool.length && !c.editIntercept)
+            gaps.push(`${name} 不支持文件编辑前置 hook：${via}`);
+        if (beforeTool.length && !c.commandIntercept)
+            gaps.push(`${name} 不支持命令前置 hook：${via}`);
+        if (afterEdit.length && !c.afterEdit)
+            gaps.push(`${name} 不支持编辑后 hook：插件声明的反馈（${afterEdit.join('、')}）不生效，依赖提交前检查兜底`);
+        if (stop.length && !c.stopCheck)
+            gaps.push(`${name} 不支持停止阶段检查：${stop.join('、')} 不生效`);
+        if (!c.commands)
+            gaps.push(`${name} 不支持项目级 commands，只生成 skills`);
+    }
+    return gaps;
+}
+//# sourceMappingURL=adapters.js.map