MetaCoder 文档

MetaCoder Harness Engineering 流水线（/harness）与四款自动化工具的命令参考。本页的语法、参数与默认值均已对照 MetaCoder 源代码核验。

所有命令都在 MetaCoder 中运行（桌面版或 agent 提示框）。斜杠命令按所示原样输入，例如 /harness status。

概览

MetaCoder 是一款面向大规模系统、以图谱为先的 AI 开发工具。它把代码库转化为语义知识图谱，并通过 Harness Engineering 驱动 AI 开发——一条规范的 10 阶段流水线，配以机器校验的质量门。两大命令家族：

/harness — 规律系统：一台带角色、质量门、上下文层与审计轨迹的 10 阶段状态机。共 18 个子命令。
自动化工具 — /modernize、/newproject、/systest、/env：构建在同一套知识图谱之上的端到端技能。

安装与首次运行

从下载页获取面向 Windows 或 macOS 的免费桌面应用。一次典型的首次会话：

› /harness init --template react-nextjs-frontend › /harness spec --advance "user dashboard with auth and i18n" › /harness implement › /harness phase advance

Harness Engineering — 理念与流水线

Harness Engineering 为 AI 驱动的开发赋予固定的顺序与由机器（而非乐观的自我报告）验证的质量标准。人与 AI 走在同一条轨道上。

10 阶段流水线

每个阶段只有质量门通过才会前进；rollback 一次回退一个阶段。

requirements → design → test-spec → implementation → code-review → integration-test → performance → security → deploy-plan → confirm ✅

4 种角色（每阶段自动接管）

角色	阶段
`pm`	requirements / design / deploy-plan / confirm
`tester`	test-spec / integration-test
`developer`	implementation / performance
`reviewer`	code-review / security

机器校验的质量门 — 质量门的检查项定义在 harness/workflow/gates.yaml 中。诚实失败：从未运行、返回 0 个用例、或无法触达浏览器的测试始终保持红色。
3 层上下文 — session / phase / on-demand，由 /harness context 管理。
审计轨迹 — phase-advance / rollback / gate-run / role-assume 以 NDJSON 追加记录；/harness ai-rate 从 git 历史测算 AI 采用率。

质量门的内容由项目定义。每个质量门具体运行哪些检查，来自你的 harness/workflow/gates.yaml。本文档中的列表反映的是 /harness init 生成的标准模板。

spec-kit — 先设计，再不折不扣地按设计构建

spec-kit 是关键创新：AI 先产出一份符合业界规范的设计（一份项目宪法加上一条 spec.md → plan.md → tasks.md 链路），再严格据此实现——不多，也不少。这可以防止 AI 因幻觉而添加凭空臆造、超出范围的功能。当 METACODER_HARNESS_SPEC_MODE 不为 off 时 spec-kit 即处于启用状态；它为 /harness spec 提供动力，在 design → test-spec 前进时自动生成 tasks.md，并把横切功能（认证、i18n、AI 助手）提升为一级任务，确保不被埋没。

/harness — 命令参考

分三组共 18 个子命令。下文的参数与默认值取自源代码（src/skills/bundled/harness.ts 与 _exec 注册表）。

准备与检查

/harness init

/harness init [--template TYPE] [--force]

用途：在工作区中脚手架生成一个 harness/ 规律目录。前提：无（若 harness/ 已存在则警告，除非加 --force）。

效果：创建 harness/{rules,skills,agents,workflow,context}/ 以及 workflow/phases.yaml 与 gates.yaml。启用 spec-kit 时，还会写入 harness/constitution.md（3 条条款）与 harness/specs/.gitkeep。

参数	默认	说明
`--template TYPE`	`minimal`	`minimal`、`java-spring-enterprise`、`node-fastapi`、`python-django`、`go-microservice`、`react-nextjs-frontend`、`cobol-modernization`
`--force`	`false`	无需确认直接覆盖已存在的 `harness/` 文件

/harness spec

/harness spec [--feature <name>] [--inputs <paths>] [--advance] [--db <dir>] <brief>

用途：启动需求/设计阶段——让 AI 从声明的输入撰写设计文档且不写产品代码（与 /harness implement 对称的对应命令）。状态：已实现。

前提：当前阶段必须为 requirements 或 design（若从未设置过阶段状态，则自动初始化为 requirements）。在 requirements 阶段必须提供 <brief>。

效果：解析当前 feature（如有需要则脚手架生成一个），从 harness/inputs.yaml + --inputs 加载设计输入，写入 docs/SPEC_PLAN.md（撰写 SOP），由 AI 撰写 spec.md（再在 design 阶段撰写 plan.md + data-model.md），并运行自检（模板占位符、空的横切章节、未解决的 [NEEDS CLARIFICATION]）。加 --advance 且自检干净时，运行质量门并继续进入下一阶段。

参数	默认	说明
`--feature <name>`	从 brief 推导	Feature 显示名
`--inputs <p1,p2,…>`	`harness/inputs.yaml`	追加到输入注册表的设计输入路径 CSV
`--advance`	关闭	自检干净后，运行质量门并继续进入下一阶段
`--db <dir>`	空	设计文档目录。作为 spec 假设记录的实时 DB URL 来自 `DATABASE_URL`，而非此参数。

/harness validate

用途：检查 harness/ 布局完整性。前提：已完成 init。

效果：报告 ok、错误（✗）与警告（⚠）。启用 spec-kit 时，还会显示宪法章节与跨产物一致性章节。无参数。

/harness lint

用途：对源码运行 harness/rules/*.md 中的规则。前提：已完成 init。

效果：返回 0–100 分及一张违规表（严重度 / 文件 / 行 / 规则 / 信息）。启用 spec-kit 时，constitution-conformance 与 no-unresolved-clarification 始终运行。无参数。

/harness status

用途：显示当前 harness 状态。前提：无（若不存在则打印 “not initialized”）。

效果：检测到的模板、必需/可选文件的存在/缺失。启用 spec-kit 时，还显示宪法版本、active feature、未解决澄清项数量。裸 /harness 默认执行 status。无参数。

/harness phase init

/harness phase init [--phase <id>] [--feature <name>]

用途：初始化阶段状态机。前提：已完成 init。

参数	默认	说明
`--phase <id>`	`requirements`	初始化所在的阶段
`--feature <name>`	无	仅 spec-kit：脚手架生成 `specs/<NNN-name>/{spec,plan,tasks}.md` 并设置 active feature

流水线操作

/harness phase status

用途：打印当前阶段、角色、回滚次数与最近一次质量门结果。前提：阶段状态已初始化。

效果：启用 spec-kit 时，还显示 active feature、任务进度（完成/总数 %），以及在 requirements 阶段显示未解决的澄清项。无参数。

/harness phase advance

/harness phase advance [--reason "…"] [--no-interactive]

用途：运行当前阶段的质量门，通过后前进到下一阶段并自动重新接管角色。最常用的命令。

效果：（spec-kit，requirements）交互式解决 [NEEDS CLARIFICATION]；运行质量门；前进并重新接管该阶段的默认角色；在 design → test-spec 时自动生成 tasks.md；进入 implementation 时提示你先使用 /harness implement。

参数	默认	说明
`--reason "…"`	空	审计原因
`--no-interactive`	关闭	仅 spec-kit：在 requirements 阶段，当澄清项未解决时阻断而非提示

/harness phase rollback

/harness phase rollback [--reason "…"]

用途：回退一个阶段。前提：未超过回滚尝试上限（否则提示 “Human approval required”）。

效果：返回上一阶段并递增尝试计数器。参数：--reason（审计原因）。

/harness gate

/harness gate <gateId>

用途：从 gates.yaml 运行单个命名质量门（仅校验，不改变阶段）。前提：已定义 <gateId>（省略则列出质量门 id）。

效果：返回逐项的通过/失败表。gate-integration-test 较为特殊：它在会话内运行 /systest 流水线（继承 Claude-in-Chrome MCP），而非作为程序化检查。

/harness assume

/harness assume <role> [--reason "…"]

用途：手动设置当前角色（抑制阶段自动接管）。角色：pm | developer | reviewer | tester。

效果：设置手动角色，将 persona 块写入 CLAUDE.md，追加一条 role-assume 审计记录。

/harness role

用途：显示当前角色、是否被手动覆盖、以及该阶段的默认角色。无参数。

实现与进阶

/harness implement

用途：实现 tasks.md 中下一个未完成的任务，并以 test-plan.md 的验收标准把关。前提：当前阶段必须为 implementation；必须存在带 tasks.md 的 active feature。

效果：将下一个（些）任务 + 验收标准汇总到 docs/IMPLEMENT_PLAN.md；AI 在实现时强制执行逐任务自检（AC 覆盖 + 为遗漏的横切功能重读设计），随后将任务标记为完成。模式由权限模式驱动：auto / bypassPermissions → 连续（按顺序实现所有任务）；否则单任务后停止。无参数。

/harness context

/harness context <show | refresh | query <text>>

用途：管理 3 层上下文（session / phase / on-demand）。前提：已完成 init。

show — 打印快照 + 逐层条目/令牌表（不持久化）。
refresh — 重建快照，写入 CLAUDE.md，追加一条审计记录。启用 spec-kit 时，将 active feature 的 spec/plan/tasks 注入 phase 层。
query <text> — 针对该文本运行 on-demand 层，不持久化。

/harness approve

/harness approve <gateId> [--reason "…"]

用途：为某个待处理的 human-approval 质量门检查项记录人工批准。效果：写入一条 YAML 批准记录（在下次运行质量门时消费）及一条审计记录。

/harness drill

/harness drill [--skip-gates] [--from <phaseId>] [--to <phaseId>]

用途：对整条流水线做虚拟试跑，不持久化状态。前提：已完成 init。

参数	默认	说明
`--skip-gates`	`false`	走遍所有阶段，仅做结构检查（跳过质量门执行）
`--from <phaseId>`	默认阶段	起始阶段（含）
`--to <phaseId>`	终止阶段	结束阶段（含）

/harness ai-rate

/harness ai-rate [--since <days>]

用途：从 git 历史测算 AI 采用率（由 AI 撰写/接受的代码占比）。前提：一个 git 仓库。

效果：检测 AI 提交（作者/邮箱匹配 claude|anthropic，或含 Co-Authored-By: Claude 尾注），并报告提交级 + 行级采用率及一张逐作者表。参数：--since <days>（默认 30）。

/harness ci-init

/harness ci-init [--target github|gitlab|both] [--force]

用途：生成 CI 脚手架文件（幂等）。效果：github → .github/workflows/harness.yml；gitlab → .gitlab-ci.yml；both → 两者皆生成。已存在的文件会被跳过，除非加 --force。

参数	默认	说明
`--target`	`github`	`github` \| `gitlab` \| `both`
`--force`	`false`	覆盖已存在的 CI 文件

自动化工具

/modernize 与 /newproject 共用同一个参数解析器；/systest 有自己的解析器；/env 是提示驱动的（子命令）。下文所有参数均已对照源代码核验。

/modernize

重构遗留代码库——通过知识图谱分析遗留源码（及截图），拆分为 PRP 模块，再以多智能体 TDD 方式开发、测试并文档化一个全新的 Web 应用，全程不触碰遗留代码树。

/modernize --workspace <legacy> --database <conn> [--output <dir>] [--design-style <name>] [--backend-lang] [--frontend-lang] [--language ja|en|zh] [--team] [-v] [--env <name>]

参数（长 / 短）	默认	说明
`--workspace` / `-w`	必填	遗留代码路径（只读参考）
`--output` / `-o`	= workspace	现代化代码的输出目录
`--database` / `--db`	未设置	数据库连接 URL
`--design-docs` / `-d`	未设置	需求/设计文档目录
`--design-style`	未设置	生成 UI 所用的品牌设计语言——见 Design styles（70+ 预设，例如 stripe、linear.app、notion）
`--backend-lang` / `--frontend-lang`	未设置	目标后端 / 前端框架
`--reference` / `-r`	未设置	参考项目路径
`--language` / `-l`	`ja`	文档语言
`--team`	`false`	启用实验性 Agent Teams
`-v` / `--verify`	`false`	在 Phase 3 结束时暂停以供评审
`--env`	未设置	激活一个命名的基础设施环境（URL 自动填充）

阶段流程

Phase 0 Graph Init（legacy + output 图谱）→ Phase 3 Module Decomposition（PRP）→ Phase 3.5 Contract Generation（openapi.yaml）→ Phase 4 Multi-Agent TDD Development → Phase 4.5 Acceptance Cross-check → Phase 5 Automated Test → Phase 6 MODERNIZATION_REPORT.md

双图谱架构 — 用于分析/拆分的只读 legacy 图谱，加上在 Phase 4 期间生长、并由门查询校验的 output 图谱。
截图驱动的 UI 映射 — 至多 10 张预选的遗留截图，1:1 映射到现代页面。
契约先行 — 生成 openapi.yaml，使后端与前端无法漂移。
PRP + 完成标记 — 每个模块都有可被 grep 检测、可重跑的证据；即使没有 package.json（如 COBOL）也能解析技术栈。

Design styles（`--design-style`）

传入 --design-style <name> 可让生成的前端遵循一套现成的品牌设计语言。MetaCoder 从开源的 awesome-design-md 库读取设计规格（颜色、排版、间距、组件模式），并在 Phase 3–4 期间应用匹配的 DESIGN.md——让现代 UI 看起来是经过用心设计的，而非千篇一律。

提供 70+ 品牌预设，例如：apple、stripe、linear.app、notion、vercel、claude、figma、airbnb、spotify、tesla、shopify、supabase、raycast、nike、uber。

浏览完整目录（每个预设都是一个含 DESIGN.md 的文件夹）：github.com/VoltAgent/awesome-design-md。使用文件夹名作为 --design-style 的值，例如 --design-style stripe。

/newproject

从需求文档构建一个全新项目——通过苏格拉底式问答确认决策，拆分为 PRP，再以多智能体 TDD 方式开发、测试并文档化一个全栈 Web 应用。

/newproject --workspace <dir> --design-docs <reqs> [--database <conn>] [--reference <proj>] [--design-style] [--backend-lang] [--frontend-lang] [-v] [--env]

使用与 /modernize 相同的共享解析器，因此完整参数集一致。值得注意的差异如下。

参数	默认	说明
`--workspace` / `-w`	必填	新代码的输出工作区
`--design-docs` / `-d`	未设置	需求文档（仅做列举，不做正则解析）
`--reference` / `-r`	自动	参考/PoC 项目；若省略则从常见文件夹自动检测
`--database` / `--db`	已解析	若省略：会话 TiDB（`DATABASE_URL`）→ 否则本地 SQLite
`-v` / `--verify`	`false`	在 Phase 3 结束时暂停（苏格拉底阶段本身即为交互式）

阶段流程

Phase 0 Graph Init（空）→ Phase 1.5 Socratic Requirements Confirmation（7–15 问）→ Phase 3 Module Decomposition → Phase 3.5 OpenAPI 3.1 Contract → Phase 4 Code Generation → Phase 4.5 Acceptance Cross-check → Phase 5 Automated Test → Phase 6 Docs

苏格拉底式 Phase 1.5 — 7–15 个必答问题（架构 / 业务 / UI-UX / 非功能 / MVP），在编码前锁定语言、认证、数据库、部署目标与范围。
DB 自动解析 — 显式 --database > 会话 TiDB Cloud > 本地 SQLite。
文档不做机器解析 — 仅做列举；结构化是 AI 的工作。参考代码会被自动检测，并生成一份环境脚手架。
Design styles — 与 /modernize 一样，--design-style <name> 应用来自 awesome-design-md 的 70+ 品牌预设之一（例如 --design-style notion）。

/systest

对运行中的应用做自动化系统 QA——构建知识图谱，生成两层测试用例，再运行 API + Chrome-MCP 前端 E2E 测试，配以自动修复循环与有证据支撑的自审。

/systest run --workspace <path> [--backend-url <url>] [--frontend-url <url>] [--database <conn>] [--env <name>] [--design-docs <path>]

参数（长 / 别名 / 短）	默认	说明
`--workspace` / `-w`	必填	待测试的项目工作区
`--backend-url` / `--backend` / `-b`	未设置 / 来自 env	后端基础 URL → 启用 Phase 5B（API 测试）
`--frontend-url` / `--frontend` / `-f`	未设置 / 来自 env	前端 URL → 启用 Phase 5C（E2E）。缺失 ⇒ 跳过 5C
`--database` / `--database-url` / `--db`	未设置 / 来自 env	数据库 URL（用户创建、管理员提权）
`--env`	未设置	命名环境；填补缺失的 URL 槽位（显式参数优先）
`--design-docs` / `-d`	未设置	设计文档目录

阶段流程

Step 0 Env Discovery（production ⇒ 硬性拒绝）→ Phase 1–3 Init / Graph → Phase 4 Test-case Generation（Layer1 CRUD / Layer2 scenario）→ Phase 5A Seed + Quality Gate → Phase 5B Backend API → Phase 5C Frontend E2E（Chrome MCP）→ Phase 6 TEST_REPORT.md → Phase 6.5 Evidence Self-audit

两层测试 — 先 Layer 1 CRUD/happy-path，再 Layer 2 negative/auth/validation/boundary/role-routing。只跑其中一层即为 VIOLATION。
Chrome-MCP 驱动的 E2E — 真实浏览器的导航/表单提交；将 2xx POST 捕获为证据；Phase 5C 唯一的跳过触发条件是缺少 --frontend-url。
诚实失败自审（6.5） — 重读证据文件；任何没有相应证据的通过声明都会被降级为 FAIL。
生产安全 — 标记为 production 的环境会在 Phase 1 之前被拒绝。

/env

提示驱动的基础设施环境管理器——对定义在 .metacoder/environments.yaml 中的环境进行列举、切换、导入/导出、编辑、健康检查与对比，带有密钥安全保护以及预览 → /apply 护栏。

子命令	说明
`/env list [--tag TAG]`	列出环境 + 当前激活项（裸 `/env` = list）
`/env use NAME [Reason: …]`	切换激活环境
`/env reset`	返回默认环境
`/env import PATH --as NAME`	导入一个 `.env`；自动将键分类为 var/secret
`/env export NAME [--include-secrets]`	导出为 `.env`；除非加该参数否则密钥被脱敏
`/env add NAME [extends PARENT] [field=VALUE …]`	新增环境（需要 cloud.provider、cloud.region、safety.destructive_ops）
`/env edit NAME [field=VALUE …]`	浅合并字段更新
`/env remove NAME`	删除环境（对依赖项发出警告）
`/env clone SRC DST [field=VALUE …]`	带覆盖项的复制
`/env set NAME.PATH VALUE`	按点路径设置单个字段
`/env doctor [--level basic\|standard\|full] [--env NAME] [--force] [--offline]`	健康检查（full 在 production 上被阻断，除非加 --force）
`/env diff A B`	解析 extends 后的并排对比

密钥安全 — list/doctor/diff 从不打印密钥值，只显示 ${var:KEY} / ${secret:KEY} 名称。导入时把含 PASSWORD/SECRET/TOKEN/CREDENTIAL/PASS/PWD/KEY 的键分类为 secret；把 NEXT_PUBLIC_/VITE_PUBLIC_/PUBLIC_ 前缀分类为 var。
预览 → /apply — 每个会修改内容的命令都会展示一份 YAML diff，在你输入 /apply 之前不写入任何内容（/cancel 丢弃）。
doctor 3 级 — basic（解析引用）、standard（+ TCP 可达性）、full（+ 云 CLI 身份；受生产保护）。--offline 跳过网络检查。
跨技能桥接 — --env 把后端/前端/数据库 URL 输送给 /systest、/modernize、/newproject；生产环境在运行前会被消费方技能拒绝。

准确性说明：一份 60 条规则的 CLI 许可清单、一个 SQL 分类器以及两段式提交属于另一个独立的 /deploy 技能，而非 /env。/env 仅在 /env diff 中将 safety.writes_two_phase_commit 作为一个被标记的字段呈现。

本文档对应 MetaCoder Desktop v3.6.22。命令语法已对照源代码核验；质量门的内容由各项目在 harness/workflow/gates.yaml 中定义。

MetaCoder 文档

概览

安装与首次运行

Harness Engineering — 理念与流水线

10 阶段流水线

4 种角色（每阶段自动接管）

spec-kit — 先设计，再不折不扣地按设计构建

/harness — 命令参考

/harness init

/harness spec

/harness validate

/harness lint

/harness status

/harness phase init

/harness phase status

/harness phase advance

/harness phase rollback

/harness gate

/harness assume

/harness role

/harness implement

/harness context

/harness approve

/harness drill

/harness ai-rate

/harness ci-init

自动化工具

/modernize

阶段流程

Design styles（--design-style）

/newproject

阶段流程

/systest

阶段流程

/env

Design styles（`--design-style`）