@cr1992/agentkit 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+本项目遵循 [Semantic Versioning](https://semver.org/)。
+
+## 1.0.0 - 2026-09-04
+
+- 将四个 Agent 工程 Skill 收敛为一个零依赖 Node.js CLI 与四个薄壳。
+- 提供 orchestrate、worktree、verify、loop、capabilities、doctor 与 docs 命令面。
+- 将共享运行时、canonical schema、安装身份和内容摘要统一到单个版本化发布单元。
+- 保留 1.x Skill 脚本兼容入口，并增加 CLI/shell 版本失配的 fail-closed 门禁。
+- 覆盖四个 Skill 的 15 种非空安装组合、跨域协议、恢复路径与 npm tarball 反装。
+- 将 `cr1992/agentkit` 设为代码、测试、架构文档和发布流程的唯一真源。

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 cr1992
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.en.md

@@ -0,0 +1,107 @@
+# agentkit
+
+[中文](./README.md) · **English**
+
+A zero-dependency Node.js CLI with four thin skills for agentic software engineering—from task orchestration and Git
+worktree isolation to one-shot independent verification and explicit bounded loops.
+
+![On-demand selection and composition of agent-engineering skills](./docs/architecture/skill-collaboration.svg)
+
+The diagram starts from request facts and selects independent capabilities. Only multi-agent or multi-node work enters
+the `orchestrate-subagents` control plane, which then chooses lightweight or full operation and evidence-driven
+rerouting from effective capabilities, task scale, and local model policy. Providers remain independently usable and
+compose through frozen Artifact, Binding, and Evidence envelopes.
+
+[Detailed collaboration contracts and safety boundaries (Chinese, v1.0.0)](./docs/architecture/skill-system-architecture.md)
+
+## Included skills
+
+| Skill | Purpose |
+| --- | --- |
+| [`orchestrate-subagents`](./orchestrate-subagents/) | Decides whether a task should be delegated, builds dependency-aware task contracts, selects suitable agent capabilities, and keeps final acceptance with the controller agent. |
+| [`manage-worktrees`](./manage-worktrees/) | Detects write collisions, creates auditable Git worktrees, produces commit-pinned batch integration plans, and safely reclaims worktrees. |
+| [`verify-agent-output`](./verify-agent-output/) | Independently verifies one frozen Git Artifact through L0/L1/L0 and emits digest-bound, reviewable Evidence without modifying or retrying the Artifact. |
+| [`run-agent-verify-loop`](./run-agent-verify-loop/) | Runs an implementer/verifier loop with isolated context, deterministic checks, evidence tracking, circuit breakers, and human gates. |
+
+This group currently contains four skills. Each works independently and composes through frozen JSON envelopes.
+Ordinary tasks need none of them. Use `verify-agent-output` for one-shot verification of a fixed Artifact, and use the
+Loop only when bounded repeated implementation and independent re-verification are explicitly requested. Add
+orchestration and worktrees only when the task actually needs multiple nodes or Git isolation.
+
+## Installation
+
+### CLI
+
+The CLI requires Node.js 22 or newer:
+
+```bash
+npm install -g @cr1992/agentkit
+agentkit doctor
+```
+
+### Skills
+
+Install all four skills:
+
+```bash
+npx skills add https://github.com/cr1992/agentkit.git -g --agent '*'
+```
+
+Install a single skill:
+
+```bash
+npx skills add https://github.com/cr1992/agentkit.git -g --agent '*' --skill manage-worktrees
+```
+
+Replace `manage-worktrees` with any other skill name in the table as needed. After an install or update, start a new
+agent task. Some hosts cache skill discovery or contents and may require a restart.
+
+## CLI
+
+The skills only define triggers and invariants. Their deterministic runtime is provided by `agentkit`. Existing 1.x
+script entry points remain as compatibility forwarders; new integrations should call the CLI directly:
+
+```bash
+agentkit capabilities --json
+agentkit doctor --json
+agentkit worktree --help
+agentkit contract --help
+agentkit orchestrate ledger --help
+agentkit verify --help
+agentkit docs
+```
+
+## Usage
+
+Invoke a skill in natural language and state the intended workflow explicitly:
+
+```text
+Use orchestrate-subagents to split this feature across multiple agents.
+Use manage-worktrees to prepare batch integration acceptance for these feature branches.
+Use verify-agent-output to independently verify this fixed commit once and emit Evidence.
+Use run-agent-verify-loop so one agent implements and another independently verifies until it passes or a stop condition fires.
+```
+
+Each skill adapts to the agents, terminal, Git, and task-control primitives available in the current host. When a
+capability is unavailable, follow the documented fallback path instead of assuming a specific agent product or tool
+exists.
+
+## Requirements
+
+- Git.
+- Node.js 22 or newer.
+- A globally available `agentkit` command; run `agentkit doctor` to validate the package version, entry points, and runtime manifest.
+- A host with task or sub-agent isolation primitives when actual multi-agent execution is required.
+
+## Local validation
+
+```bash
+npm test
+npm run pack:check
+```
+
+## Repository scope
+
+This repository is the sole source of truth for the `agentkit` CLI, all four skills, canonical schemas, tests, and
+architecture documentation. It is no longer generated or overwritten by another repository. See
+[source-of-truth and release maintenance](./docs/maintenance/source-of-truth.md) for the ownership boundary.

package/README.md

@@ -0,0 +1,103 @@
+# agentkit
+
+**中文** · [English](./README.en.md)
+
+一个零依赖 Node.js CLI，加四个面向 Agent 软件工程的薄壳 Skill：从任务编排、Git worktree 隔离，
+到一次性独立验收和显式有界循环。
+
+![Agent 工程 Skill 的按需选择与组合](./docs/architecture/skill-collaboration.svg)
+
+图中先按请求事实选择独立能力；只有多 Agent / 多节点任务才进入 `orchestrate-subagents` 控制面，
+其内部再按有效能力、任务规模、本地模型配置和验收证据选择轻量或完整运行方式及后续重路由。
+各 provider 仍可独立使用，并通过冻结的 Artifact、Binding 和 Evidence envelope 按需组合。
+
+[Agent Skills 协作契约与安全边界（v1.0.0）](./docs/architecture/skill-system-architecture.md)
+
+## 包含的 Skill
+
+| Skill | 用途 |
+| --- | --- |
+| [`orchestrate-subagents`](./orchestrate-subagents/) | 判断任务是否值得拆分，设计依赖图与派发契约，选择合适的 Agent 能力，并由主控 Agent 统一验收结果。 |
+| [`manage-worktrees`](./manage-worktrees/) | 扫描写入冲突，创建和登记可追踪的 Git worktree，为多个功能分支生成固定提交的批量验收计划，并安全回收 worktree。 |
+| [`verify-agent-output`](./verify-agent-output/) | 对冻结的单一 Git Artifact 做一次独立验收，执行 L0/L1/L0 并输出与摘要绑定、可复核的 Evidence Package；不修改产物、不自动重试。 |
+| [`run-agent-verify-loop`](./run-agent-verify-loop/) | 让实现 Agent 与隔离上下文中的验收 Agent 形成闭环，通过确定性检查、证据台账、熔断和人工门控制收敛。 |
+
+本组目前包含 4 个 Skill。它们都可以独立使用，也可以通过冻结的 JSON envelope 联动。普通任务不必
+加载任何一个；固定 Artifact 只验一次时直接使用 `verify-agent-output`；只有明确要求反复修复和独立
+复验时才使用 Loop。多节点编排和 worktree 隔离同样按实际需要添加，不是默认必经步骤。
+
+## 安装
+
+### CLI
+
+CLI 需要 Node.js 22 或更高版本：
+
+```bash
+npm install -g @cr1992/agentkit
+agentkit doctor
+```
+
+### Skill
+
+安装全部 Skill：
+
+```bash
+npx skills add https://github.com/cr1992/agentkit.git -g --agent '*'
+```
+
+只安装一个 Skill：
+
+```bash
+npx skills add https://github.com/cr1992/agentkit.git -g --agent '*' --skill manage-worktrees
+```
+
+将 `manage-worktrees` 替换为表中的其他 Skill 名称即可。安装或更新后，建议新建 Agent 任务；部分宿主
+会缓存 Skill 清单或正文，需要重启后才会加载新版本。
+
+## CLI
+
+四个 Skill 只负责触发条件和不变量，确定性运行时统一由 `agentkit` 提供。现有 1.x 脚本入口仍保留
+兼容转发；新调用建议直接使用下列命令：
+
+```bash
+agentkit capabilities --json
+agentkit doctor --json
+agentkit worktree --help
+agentkit contract --help
+agentkit orchestrate ledger --help
+agentkit verify --help
+agentkit docs
+```
+
+## 使用方式
+
+安装完成后，直接用自然语言描述目标，并明确触发对应能力，例如：
+
+```text
+用 orchestrate-subagents 把这个功能拆给多个 Agent 并行处理。
+用 manage-worktrees 为这些 feature 分支准备一批集成验收。
+用 verify-agent-output 独立验收这个固定 commit，只验一次并输出 Evidence。
+用 run-agent-verify-loop 让一个 Agent 实现、另一个 Agent 独立验收，直到通过或触发停止条件。
+```
+
+Skill 会根据当前宿主可用的 Agent、终端、Git 和任务控制能力进行适配。宿主缺少某项能力时，应遵循
+各 Skill 中的降级路径，而不是假设某个特定产品或工具一定存在。
+
+## 环境要求
+
+- Git。
+- Node.js 22 或更高版本。
+- 全局可用的 `agentkit` 命令；运行 `agentkit doctor` 可检查包版本、入口与运行时清单。
+- 若要实际派生和隔离多个 Agent，上层宿主需要提供相应的任务或子 Agent 能力。
+
+## 本地验证
+
+```bash
+npm test
+npm run pack:check
+```
+
+## 仓库范围
+
+本仓库是 `agentkit` CLI、上述 4 个 Skill、canonical schema、测试与架构文档的唯一真源，不再由其他
+仓库生成或反向覆盖。维护边界与发布流程见[真源与发布维护](./docs/maintenance/source-of-truth.md)。

package/bin/agentkit.mjs

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { main } from './cli.mjs';
+
+process.exitCode = await main(process.argv.slice(2));

package/bin/cli.mjs

@@ -0,0 +1,273 @@
+// agentkit 顶层路由。P1 只解析前缀，argv 其余部分原样转发给现有入口：
+// 转发路径上 stdout、stderr 分类与退出码必须与直接调用旧入口逐字节等价，
+// 因此一律用 stdio: 'inherit' 直通，不做任何包装、重排或补充输出。
+// CLI 自身的输出（help、version、capabilities 聚合、docs、doctor 汇总）不受该约束，
+// 但任何迁移提示只写 stderr，避免污染可被管道消费的 stdout。
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import {
+  assertPublicCommandCompatibility,
+  RuntimeBundleError,
+  runtimeBundleDigest,
+  validateShellManifest,
+} from '../core/runtime-bundle.mjs';
+
+const PACKAGE_ROOT = dirname(dirname(fileURLToPath(import.meta.url)));  // bin/ 的上一级即包根
+
+// 一级域：前缀之后的 argv 直接交给同一个脚本。
+const DOMAINS = {
+  worktree: { domain: 'worktree', skill: 'manage-worktrees', script: 'worktree-mgr.mjs', verbs: { scan: 'worktree-scan.mjs' } },
+  contract: { domain: 'orchestrate', skill: 'orchestrate-subagents', script: 'contract-tool.mjs' },
+  verify: { domain: 'verify', skill: 'verify-agent-output', script: 'verification-runtime.mjs' },
+  loop: { domain: 'loop', skill: 'run-agent-verify-loop', script: 'loop-runtime.mjs' },
+};
+
+// 二级域：四个 orchestrate 工具都有 capabilities，preflight 与 contract 都有 normalize，
+// 扁平化会让同名动词互相遮蔽，因此保留工具名这一级，动词本身一个都不改。
+const GROUPS = {
+  orchestrate: {
+    ledger: { domain: 'orchestrate', skill: 'orchestrate-subagents', script: 'orchestration-ledger.mjs' },
+    preflight: { domain: 'orchestrate', skill: 'orchestrate-subagents', script: 'worker-capability-preflight.mjs' },
+    'review-budget': { domain: 'orchestrate', skill: 'orchestrate-subagents', script: 'review-budget.mjs' },
+    reflection: { domain: 'orchestrate', skill: 'orchestrate-subagents', script: 'orchestration-reflection.mjs' },
+  },
+  host: {
+    cache: { domain: 'orchestrate', skill: 'orchestrate-subagents', script: 'host_capability_cache.mjs' },
+    'model-policy': { domain: 'orchestrate', skill: 'orchestrate-subagents', script: 'resolve_model_policy.mjs' },
+  },
+};
+
+// capabilities 与安装级 doctor 的成员入口。域级 doctor 需要 ledger/run/loop 等状态选择器，
+// 顶层 doctor 只检查安装和能力发现，不能把“未指定某次运行”误报成不健康。
+const CAPABILITY_TARGETS = [
+  { domain: 'orchestrate', skill: 'orchestrate-subagents', script: 'orchestration-ledger.mjs' },
+  { domain: 'worktree', skill: 'manage-worktrees', script: 'worktree-mgr.mjs' },
+  { domain: 'verify', skill: 'verify-agent-output', script: 'verification-runtime.mjs' },
+  { domain: 'loop', skill: 'run-agent-verify-loop', script: 'loop-runtime.mjs' },
+];
+const DOCTOR_TARGETS = CAPABILITY_TARGETS;
+
+// docs 路由：参考文档按域收在包根 docs/<域>/ 下。
+const DOC_DOMAINS = { orchestrate: 'orchestrate', worktree: 'worktree', verify: 'verify', loop: 'loop' };
+
+function packageVersion() {
+  try { return JSON.parse(readFileSync(join(PACKAGE_ROOT, 'package.json'), 'utf8')).version; }
+  catch { return 'unknown'; }
+}
+
+function scriptPath(target) {
+  // 运行时住在 domains/ 下；Skill 目录只剩 SKILL.md、参考文档与 1.x 兼容 stub。
+  return join(PACKAGE_ROOT, 'domains', target.domain, target.script);
+}
+
+function missing(target) {
+  process.stderr.write(`agentkit: 未找到 domains/${target.domain}/${target.script}，该 Skill 未随本安装分发\n`);
+  return 127;
+}
+
+// 直通转发：子进程直接继承本进程的 stdio，父进程不碰任何一个字节。
+function forward(target, args) {
+  const path = scriptPath(target);
+  if (!existsSync(path)) return missing(target);
+  try {
+    assertPublicCommandCompatibility({ skill: target.skill, entryName: target.script, command: args[0] });
+  } catch (error) {
+    if (!(error instanceof RuntimeBundleError)) throw error;
+    process.stderr.write(`agentkit runtime compatibility error: ${error.message}\n`);
+    return 3;
+  }
+  const result = spawnSync(process.execPath, [path, ...args], { stdio: 'inherit' });
+  if (result.error) {
+    process.stderr.write(`agentkit: 执行 ${target.script} 失败：${result.error.message}\n`);
+    return 1;
+  }
+  if (result.signal) {
+    // facade 若吞掉子进程信号并改写为 exit 1，就不再满足“退出语义一致”。
+    try { process.kill(process.pid, result.signal); } catch { return 1; }
+    return 1;
+  }
+  return result.status === null ? 1 : result.status;
+}
+
+// 捕获式调用：只用于 CLI 自己要解析子进程输出的聚合命令。
+function capture(target, args) {
+  const path = scriptPath(target);
+  if (!existsSync(path)) return null;
+  const result = spawnSync(process.execPath, [path, ...args], { encoding: 'utf8' });
+  if (result.status !== 0 || !result.stdout) return null;
+  try { return JSON.parse(result.stdout); } catch { return null; }
+}
+
+function helpText() {
+  const lines = [
+    `agentkit ${packageVersion()}`,
+    '',
+    '用法: agentkit <域> <命令> [选项]',
+    '',
+    '域：',
+    '  worktree <命令>              Git worktree 隔离与生命周期（含 worktree scan）',
+    '  contract <命令>              任务契约规范化、校验、摘要与投影',
+    '  orchestrate <工具> <命令>    ledger | preflight | review-budget | reflection',
+    '  host <工具> <命令>           cache | model-policy',
+    '  verify <命令>                冻结 Artifact 的一次性独立验收',
+    '  loop <命令>                  有界的实现—验收循环',
+    '',
+    '跨域命令：',
+    '  capabilities [--json]        汇总四个 Skill 的能力发现结果',
+    '  doctor [--json]              检查 Node、Git、安装完整性与各域能力发现',
+    '  docs [<域>] [<主题>]         输出参考文档原文；缺主题时只列索引',
+    '  --version                    打印版本',
+    '',
+    '域与工具之后的参数原样转发给对应入口，输出与退出码保持一致。',
+  ];
+  return `${lines.join('\n')}\n`;
+}
+
+function runCapabilities(args) {
+  const json = args.includes('--json');
+  const skills = {};
+  for (const target of CAPABILITY_TARGETS) {
+    const payload = capture(target, ['capabilities', '--json']);
+    if (payload) skills[target.skill] = payload;
+  }
+  if (!Object.keys(skills).length) {
+    process.stderr.write('agentkit: 没有任何 Skill 能力可发现\n');
+    return 1;
+  }
+  if (json) {
+    process.stdout.write(`${JSON.stringify({ cli: 'agentkit', cli_version: packageVersion(), runtime_bundle_digest: runtimeBundleDigest(), skills }, null, 2)}\n`);
+    return 0;
+  }
+  for (const [skill, payload] of Object.entries(skills)) {
+    process.stdout.write(`${skill} runtime ${payload.runtime_version ?? '?'}\n`);
+  }
+  return 0;
+}
+
+function runDoctor(args) {
+  const unknown = args.filter((arg) => arg !== '--json');
+  if (unknown.length) {
+    process.stderr.write(`agentkit doctor: 未知选项「${unknown[0]}」；状态检查请使用对应域的 doctor 并传入 ledger/run/loop\n`);
+    return 2;
+  }
+  const json = args.includes('--json');
+  const nodeMajor = Number.parseInt(process.versions.node.split('.')[0], 10);
+  const node = { healthy: Number.isSafeInteger(nodeMajor) && nodeMajor >= 22, version: process.versions.node, required: '>=22' };
+  const gitResult = spawnSync('git', ['--version'], { encoding: 'utf8' });
+  const git = {
+    healthy: gitResult.status === 0,
+    version: gitResult.status === 0 ? gitResult.stdout.trim().replace(/^git version\s+/u, '') : null,
+    error: gitResult.status === 0 ? null : (gitResult.error?.message ?? gitResult.stderr?.trim() ?? 'unavailable'),
+  };
+  let manifest;
+  try {
+    const value = validateShellManifest();
+    manifest = { healthy: true, package_name: value.package_name, package_version: value.package_version, error: null };
+  } catch (error) {
+    manifest = { healthy: false, package_name: null, package_version: null, error: error instanceof Error ? error.message : String(error) };
+  }
+  const skills = {};
+  let installed = 0;
+  for (const target of DOCTOR_TARGETS) {
+    if (!existsSync(scriptPath(target))) {
+      skills[target.skill] = { installed: false, healthy: null, state_doctor: 'not_run' };
+      continue;
+    }
+    installed += 1;
+    const capabilities = capture(target, ['capabilities', '--json']);
+    skills[target.skill] = {
+      installed: true,
+      healthy: capabilities !== null,
+      runtime_version: capabilities?.runtime_version ?? null,
+      content_digest: capabilities?.content_digest ?? null,
+      state_doctor: 'requires_explicit_state',
+    };
+  }
+  const healthy = node.healthy && git.healthy && manifest.healthy && installed > 0
+    && Object.values(skills).filter((item) => item.installed).every((item) => item.healthy);
+  const result = { cli: 'agentkit', cli_version: packageVersion(), runtime_bundle_digest: runtimeBundleDigest(), healthy, checks: { node, git, manifest }, skills };
+  if (json) process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  else {
+    process.stdout.write(`agentkit ${packageVersion()} doctor: ${healthy ? 'healthy' : 'unhealthy'}\n`);
+    process.stdout.write(`node ${node.version} (${node.healthy ? 'ok' : `需要 ${node.required}`})\n`);
+    process.stdout.write(`git ${git.version ?? git.error} (${git.healthy ? 'ok' : 'unavailable'})\n`);
+    process.stdout.write(`shell manifest ${manifest.package_version ?? manifest.error} (${manifest.healthy ? 'ok' : 'invalid'})\n`);
+    for (const [skill, check] of Object.entries(skills)) {
+      process.stdout.write(`${skill}: ${check.installed ? (check.healthy ? `runtime ${check.runtime_version ?? '?'} ok` : 'capabilities failed') : 'not installed'}\n`);
+    }
+  }
+  if (!installed) return 127;
+  return healthy ? 0 : 1;
+}
+
+function docsIndex(domain) {
+  const dir = join(PACKAGE_ROOT, 'docs', DOC_DOMAINS[domain]);
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir).filter((name) => name.endsWith('.md')).map((name) => basename(name, '.md')).sort();
+}
+
+function runDocs(args) {
+  const [domain, topic] = args;
+  if (!domain) {
+    process.stdout.write(`${Object.keys(DOC_DOMAINS).sort().join('\n')}\n`);
+    return 0;
+  }
+  if (!DOC_DOMAINS[domain]) {
+    process.stderr.write(`agentkit: 未知文档域「${domain}」，可选：${Object.keys(DOC_DOMAINS).sort().join(', ')}\n`);
+    return 2;
+  }
+  const topics = docsIndex(domain);
+  if (!topic) {
+    if (!topics.length) { process.stderr.write(`agentkit: ${domain} 没有可用参考文档\n`); return 127; }
+    process.stdout.write(`${topics.join('\n')}\n`);
+    return 0;
+  }
+  if (!topics.includes(topic)) {
+    // 主题不存在时只列索引，不猜测最相近的文档。
+    process.stderr.write(`agentkit: ${domain} 没有主题「${topic}」\n`);
+    process.stdout.write(`${topics.join('\n')}\n`);
+    return 2;
+  }
+  process.stdout.write(readFileSync(join(PACKAGE_ROOT, 'docs', DOC_DOMAINS[domain], `${topic}.md`), 'utf8'));
+  return 0;
+}
+
+export async function main(argv) {
+  const [head, ...rest] = argv;
+
+  if (!head || head === '--help' || head === '-h' || head === 'help') {
+    process.stdout.write(helpText());
+    return 0;
+  }
+  if (head === '--version' || head === '-v') {
+    process.stdout.write(`${packageVersion()}\n`);
+    return 0;
+  }
+  if (head === 'capabilities') return runCapabilities(rest);
+  if (head === 'doctor') return runDoctor(rest);
+  if (head === 'docs') return runDocs(rest);
+
+  const domain = DOMAINS[head];
+  if (domain) {
+    const override = domain.verbs?.[rest[0]];
+    if (override) return forward({ ...domain, script: override }, rest);
+    return forward(domain, rest);
+  }
+
+  const group = GROUPS[head];
+  if (group) {
+    const [tool, ...args] = rest;
+    if (!tool || !group[tool]) {
+      process.stderr.write(`agentkit ${head}: 需要工具名，可选：${Object.keys(group).join(', ')}\n`);
+      return 2;
+    }
+    return forward(group[tool], args);
+  }
+
+  process.stderr.write(`agentkit: 未知域「${head}」\n`);
+  process.stderr.write(helpText());
+  return 2;
+}

package/core/atomic-fs.mjs

@@ -0,0 +1,23 @@
+// 文件写入原语。五处 writeNewJson 此前各带一份，两种写法只有选项顺序差异，语义相同。
+import { randomUUID } from 'node:crypto';
+import { renameSync, writeFileSync } from 'node:fs';
+
+// wx：目标已存在即失败，保证「只写新文件」不会覆盖既有状态。
+/** @param {string} path @param {unknown} value */
+export function writeNewJson(path, value) {
+  writeFileSync(path, `${JSON.stringify(value, null, 2)}\n`, { flag: 'wx', mode: 0o600 });
+}
+
+/** @param {string} path @param {unknown} value */
+export function atomicWriteJson(path, value) {
+  const temporary = `${path}.${process.pid}.${randomUUID()}.tmp`;
+  writeFileSync(temporary, `${JSON.stringify(value, null, 2)}\n`, { flag: 'wx', mode: 0o600 });
+  renameSync(temporary, path);
+}
+
+/** @param {string} path @param {string} value */
+export function atomicWriteText(path, value) {
+  const temporary = `${path}.${process.pid}.${randomUUID()}.tmp`;
+  writeFileSync(temporary, value, { flag: 'wx', mode: 0o600 });
+  renameSync(temporary, path);
+}

package/core/cli-help.mjs

@@ -0,0 +1,54 @@
+// @ts-check
+
+// 五个编排脚本共用的 `--help` 渲染。命令与参数清单只从各脚本已有的 CLI_SPEC 表推导，
+// 不允许在正文里手写第二份清单——否则表和帮助会各自漂移。
+
+/** @typedef {{ required?: string[], optional?: string[], flags?: string[] }} CommandSpec */
+
+const HELP_TOKENS = new Set(['--help', '-h', 'help']);
+
+/**
+ * 无参数、`help`、`--help`、`-h` 都按求助处理。
+ * @param {string[]} argv
+ */
+export function isHelpRequest(argv) {
+  return argv.length === 0 || HELP_TOKENS.has(argv[0]);
+}
+
+/**
+ * CLI_SPEC 中一条命令接受的全部带值选项（required + optional）。
+ * @param {CommandSpec} spec
+ */
+export function specOptionNames(spec) {
+  return [...(spec.required ?? []), ...(spec.optional ?? [])];
+}
+
+/**
+ * CLI_SPEC 全部命令接受的带值选项并集，供只做全局选项校验的脚本使用。
+ * @param {Record<string, CommandSpec>} cliSpec
+ */
+export function allOptionNames(cliSpec) {
+  return new Set(Object.values(cliSpec).flatMap((spec) => specOptionNames(spec)));
+}
+
+/**
+ * @param {string} script 脚本文件名
+ * @param {Record<string, CommandSpec>} cliSpec
+ * @param {string[]} notes 额外说明行
+ */
+export function renderCliHelp(script, cliSpec, notes = []) {
+  const lines = [`用法: node ${script} <command> [options]`, '', '命令:'];
+  for (const [command, spec] of Object.entries(cliSpec)) {
+    const parts = [command];
+    for (const name of spec.required ?? []) parts.push(`--${name} <value>`);
+    for (const name of spec.optional ?? []) parts.push(`[--${name} <value>]`);
+    for (const name of spec.flags ?? []) parts.push(`[--${name}]`);
+    lines.push(`  ${parts.join(' ')}`);
+  }
+  if (notes.length) {
+    lines.push('', '说明:');
+    for (const note of notes) lines.push(`  ${note}`);
+  }
+  lines.push('', '无参数 / help / --help / -h 打印本清单并退出 0；未知命令与非法输入仍按各脚本原有错误形状返回并非零退出。');
+  return `${lines.join('\n')}\n`;
+}

package/core/content-digest.mjs

@@ -0,0 +1,66 @@
+// @ts-check
+// 域级内容摘要：覆盖一个 Skill 实际执行所依赖的完整分发内容。
+//
+// 收敛前四个 Skill 各带一份实现，都只遍历自己的目录。schema 收敛与 core 抽取之后，
+// 执行还依赖包根的 core/ 与 schemas/，只算 Skill 目录会漏掉真正会漂移的代码——
+// 改这两处不会触发 skill_drift，冻结的任务却已经跑在不同的实现上。
+//
+// 因此摘要改为多根：每个根用固定的逻辑前缀（skill / domain / core / schemas）记录，
+// 与安装绝对路径无关。CLI 路由（bin/）不在覆盖范围内：它决定命令怎么分发，
+// 不参与任何 Skill 的执行语义，把它算进来会让改一行帮助文案就让四个域一起漂移。
+import { existsSync, lstatSync, readFileSync, readdirSync, realpathSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { createDigestKit, sha256 } from './digest.mjs';
+
+// 摘要的序列化口径与各 Skill 的 canonicalJson 解耦：四处摘要必须算得出同一个结果，
+// 不能因为某个 Skill 的严格度不同而分叉。
+const { canonicalJson } = createDigestKit({ ValidationError: Error, strict: false });
+
+const SKILL_ENTRIES = ['SKILL.md', 'agents', 'scripts'];
+
+function collect(root, prefix, entries, output) {
+  if (!existsSync(root)) return;
+  const base = realpathSync(root);
+  const visit = (absolute, relativePath) => {
+    const stat = lstatSync(absolute);
+    if (stat.isDirectory()) {
+      for (const name of readdirSync(absolute).sort()) visit(join(absolute, name), `${relativePath}/${name}`);
+      return;
+    }
+    if (stat.isFile() || stat.isSymbolicLink()) {
+      const bytes = readFileSync(absolute);
+      output.push({ path: relativePath, size: bytes.length, sha256: sha256(bytes) });
+    }
+  };
+  if (!entries) { visit(base, prefix); return; }
+  for (const name of entries) if (existsSync(join(base, name))) visit(join(base, name), `${prefix}/${name}`);
+}
+
+/** @param {{ prefix: string, path: string, entries?: string[] }[]} roots */
+export function distributionManifest(roots) {
+  const output = [];
+  for (const { prefix, path, entries } of roots) collect(path, prefix, entries, output);
+  // 码点序，不用 localeCompare：后者随运行环境的 collation 变化，摘要必须与环境无关。
+  return output.sort((left, right) => (left.path < right.path ? -1 : left.path > right.path ? 1 : 0));
+}
+
+/** @param {{ prefix: string, path: string, entries?: string[] }[]} roots */
+export function distributionDigest(roots) {
+  return sha256(Buffer.from(canonicalJson(distributionManifest(roots)), 'utf8'));
+}
+
+/**
+ * 一个 Skill 的分发内容 = 自己的 Skill 目录 + 对应 domain 运行时 + 按需文档
+ * + 共享 core + canonical schemas。
+ * @param {{ packageRoot: string, skillRoot: string, domainRoot?: string, docsRoot?: string }} options
+ */
+export function skillDistributionRoots({ packageRoot, skillRoot, domainRoot, docsRoot }) {
+  const roots = [{ prefix: 'skill', path: skillRoot, entries: SKILL_ENTRIES }];
+  if (domainRoot) roots.push({ prefix: 'domain', path: domainRoot });
+  if (docsRoot) roots.push({ prefix: 'docs', path: docsRoot });
+  roots.push({ prefix: 'core', path: join(packageRoot, 'core') });
+  roots.push({ prefix: 'schemas', path: join(packageRoot, 'schemas') });
+  roots.push({ prefix: 'shell-manifest', path: join(packageRoot, 'shell-manifest.json') });
+  return roots;
+}