ai-architect-mcp-spec

在幻觉规格说明变成代码之前将其识别出来。
它会检查每个符号是否存在、每项验收标准是否可追溯到某项需求，以及每项性能声明是否经过测量验证——以确定性方式执行，检查环节不使用任何模型。
适用于 Codex、Gemini CLI、Claude Code 和 CI。在你的机器上运行。

Agent 可以提出什么问题 · 快速入门 · 流水线 · 工具 · 验证 · 校准 · 架构 · 求真标准

_{三款可独立运行的 MCP 服务之一，分别用于记忆、代码图谱和规格验证。了解它们如何协同 ↓}

---

每个起草 PRD 的 AI Agent 最终都会编造一个并不存在的函数、声称一个无法测量的延迟，或写出与待测试需求毫无关联的验收标准。输出听起来信心十足，却无法付诸行动。流水线的下一个阶段——代码生成、工单导入、冲刺规划——会悄无声息地继承并交付这些幻觉，最终付出代价。

AI Architect MCP Spec 是一个 TypeScript MCP 服务，从结构层面解决这一问题。它的可移植验证器为 Codex、Gemini CLI、Claude Code、CI 和其他 stdio MCP 宿主提供相同的确定性严格输出规则和跨章节可追溯性检查。完整流水线是一个无状态归约器（step(state, result?) → next_state, action），由能够执行其编排操作的宿主驱动；目前，Claude Code 是唯一打包提供的完整流水线宿主。内容逐节生成，在宿主看到之前先进行验证；每项关键声明都会由来自 zetetic-team-subagents 的顶尖推理 Agent 组成的评审组，结合 ai-architect-mcp-codebase 的代码库图谱进行评判。整个闭环会根据历史数据校准每位评审的可靠性，根据存续统计推导重试预算，并针对冻结的基线调整 KPI 门槛；留出分区则通过机械方式封存，确保评估前无法窥见任何校准结果。

你将获得

• 经得起实际代码检验的规范。 符号会与真实代码库图进行交叉核对，因此 PRD 不会引用上周刚重命名的函数。
• 真正经过检查的可追溯性。 每项验收标准都必须关联到一项需求；编号缺漏会被发现，而不会被默认忽略。
• 没有测量结果，就不判定为通过。 判定分类机制会拒绝通过延迟、吞吐量、fps 或存储方面的声明——它会返回 SPEC-COMPLETE 或 NEEDS-RUNTIME，而不是给出自信的猜测。
• 防范一味附和的评审者。 如果评审组对 5 项以上声明的意见一致率达到 100%，就会触发 distribution_suspicious，而不会将其视为共识。
• 可在你的工作环境中运行。 确定性验证器可用于 Codex、Gemini CLI、Claude Code 和 CI；完整生成流水线则运行在能够执行其编排操作的主机上。

以自主可控为本，以生态负责为目标

自主可控是当前的实际情况。 该服务是一个无状态归约器：step(state, result?) → next_state, action。它会发出操作，由你的主机执行。它在你的机器上运行，绝不会向外发送请求以获取判定结果。

生态负责是我们的努力方向。 它发挥作用的方式与同类项目不同：避免返工。一份有幻觉内容的 PRD，会在有人察觉之前被代码生成、工单导入和迭代规划继承；而每个使用过它的阶段都必须重做。规范阶段是在流水线中发现此类问题成本最低的环节，而以下三项设计选择也让发现问题本身的成本保持低廉：

• 这些检查不运行模型。 硬性输出规则和跨章节可追溯性都是确定性的；发现一条有问题的 FR-AC 链接不耗费任何推理资源。
• 章节尚未完成就会检查失败。 每个章节都会在主机接收之前经过验证，而不是先完整生成，再将其丢弃。
• 重试预算通过推导得出，而非猜测。 MAX_ATTEMPTS 根据 Kaplan-Meier 生存分析数学计算得出，而 map_failure_to_retrieval 会在重试前发送纠正性查询——重用刚刚导致失败的上下文进行重试，就是有据可查的浪费。

与同类代码库一样，我们不发布能耗或 CO₂ 数值：本仓库不测量焦耳数，而避免返工属于设计论据，并非测量结果。

10 个软件包。17 个 MCP 工具。20 个流水线步骤（11 个 PRD 生成步骤 + 9 个可选实施步骤）。采用共识机制的多评审者验证。基于外部依据反证进行的闭环校准。1506 项测试。每个数值常量都可追溯到引用、基准测试，或 // source: provisional heuristic 的说明。

闭环可靠性校准

验证不是一次性的通过／失败报告。每次认定某项声明，都可以将观察结果写回校准存储库；每次共识运行，都可以从历史记录中提取经过校准的后验值；每个闭环都会运行一个外部对照组，以便测量校准的效果，而不是想当然地认定有效。

• 逐评审者贝叶斯可靠性校准 — 使用 Beta(7,3) 先验，并按 claim_type 分别拆分灵敏度／特异度。后验值存储在基于 SQLite 的 ReliabilityRepository 中；每次认定声明后都会写入观察结果。
• MAX_ATTEMPTS 重试校准 — Kaplan-Meier 生存分析计算（kmEstimate / kmMedianAttempts / logRankTest，含 Greenwood 和 Brookmeyer-Crowley 置信区间）；Schoenfeld 样本量推导根据事件率校正后约为 519（原为 823），基于实测 event_rate=0.4762，CP CI [0.4456, 0.5069]。
• KPI 门槛调优 — Clopper-Pearson 精确置信区间；通过 5 桶 detectMachineClass 按机器类别归一化 wall_time；冻结基线内容哈希断言；loadCalibratedGates + hold_provisional 棘轮保护。
• 计划不匹配触发率 — 通过 XmR 控制图（Wheeler 1995、Western Electric 1956）测量，并在预检阶段进行合成注入往返测试，以捕获诊断前缀与正则匹配器之间的偏移。
• 以外部依据构建的留出子集 — Ajv 模式预言机、mathjs 预言机、tsc 子进程代码预言机、validateSection 规范预言机。用类型化抛出 OracleUnavailableError 取代存根模式下的伪造结果。这一层打破了标注者循环依赖：评审者和预言机之间没有共享推理路径。
• CC-3 强制探索对照组 — 每个闭环都会划出 20% 的分区并恢复为先验值。没有这个对照组，即使校准实际上毫无效果，校准自身的结果看起来也会像是在进步。
• 跨组比较指标 — computeAblationComparison / computeReliabilityComparison / computeKpiGateComparison 会生成配对自助法置信区间（Efron & Tibshirani 1993 §16.4；确定性 mulberry32 RNG；12 位小数的可复现性锁定）。结果是一项可证伪的建议：calibrated_helps、prior_helps 或 inconclusive_underpowered。
• 通过机制强制执行的留出分区封印 — 三个已封印的锁文件（maxattempts-heldout.lock.json、kpigates-heldout.lock.json、heldout-partition.lock.json）会在评估前提交分区的 sha256。只有 SEAL_VERIFIED typeof 哨兵才能用于计算封印分区上的跨组指标；传入任何其他内容都会在边界处触发类型错误。
• 生产模式调度器 — makeProductionDispatcher + AgentInvoker 接口。CLI 的 --mode production|canned 标志用于选择校准接收真实判定还是预设判定；为保证离线可复现性，保留了预设对照组。

---

Agent 可以向它提出什么请求

start_pipeline(feature_description, codebase_path?)
  → returns the first NextAction; the host executes it and feeds the result
    back via submit_action_result. Eleven steps later: 9 PRD files written.

submit_action_result(run_id, result)
  → drives the reducer one more step. The host sees only SUBSTANTIVE actions
    (ask_user, call_pipeline_tool, call_cortex_tool, spawn_subagents,
     write_file, done, failed). emit_message is coalesced into the
     messages array; the host never has to "advance past" a banner.

validate_prd_section(content, section_type)
  → deterministic Hard Output Rules — zero LLM calls, pure regex/parsing.
  → returns: violations[], hasCriticalViolations, totalScore.

validate_prd_document(sections[])
  → cross-section checks: SP arithmetic, AC numbering, FR-AC coverage,
    test traceability. Catches what per-section validation misses.

coordinate_context_budget(prd_context, completed_sections[])
  → per-section retrieval/generation token budgets so Cortex recall and
    section drafting don't fight over the same context window.

map_failure_to_retrieval(violations[])
  → closes the validation→retrieval feedback loop. When a section fails
    validation, this returns the corrective Cortex query that would
    have prevented the failure.

---

入门

_{关于命名的说明。本项目以 ai-architect-mcp-spec 的名称发布，覆盖 Claude Code、Codex、Gemini、MCPB、PyPI/npm 和 MCP Registry。0.7.0 将 Registry 条目和主 bundle 迁移到了这一名称；0.8.0 完成了迁移，因此不再保留任何 prd-spec-generator 插件或发布别名。旧版 io.github.cdeust/prd-spec-generator Registry 版本已弃用，并指向规范条目，而不是继续保持启用和冻结状态。}

安装（推荐使用 marketplace）

claude plugin marketplace add cdeust/ai-architect-mcp-spec
claude plugin install ai-architect-mcp-spec@ai-architect-mcp-spec-marketplace

重启 Claude Code 会话。17 个 MCP 工具将在首次 stdio 握手时注册。然后：

/generate-prd build OAuth login for the admin console

插件捆绑的 MCP 服务 mcp-server/index.js 是自包含的 （证据存储库仅将 better-sqlite3 作为可选原生依赖项——若该依赖项缺失，则会优雅地降级为内存模式）。

从 prd-spec-generator 迁移

旧插件和市场条目是已弃用的发布版本，并非别名。安装规范软件包前，请先将它们移除：

claude plugin uninstall prd-spec-generator@prd-spec-generator-marketplace
claude plugin marketplace remove prd-spec-generator-marketplace
claude plugin marketplace add cdeust/ai-architect-mcp-spec
claude plugin install ai-architect-mcp-spec@ai-architect-mcp-spec-marketplace

使用 prd-spec-generator:generate-prd 的调用方必须改用 ai-architect-mcp-spec:generate-prd。prd-gen MCP 服务名称、 @prd-gen/* 私有工作区软件包、PRD_GEN_* 环境变量以及 .prd-gen 本地数据目录仍是稳定的内部接口；它们不会让已弃用的发布版本继续保持安装状态。

插件范围内的 MCP 工具名称同时包含发布名称和稳定的服务键，因此提示词、自动化和允许列表必须迁移完整前缀：

• 旧：mcp__plugin_prd-spec-generator_prd-gen__<tool>
• 新：mcp__plugin_ai-architect-mcp-spec_prd-gen__<tool>

Gemini CLI 也会根据清单名称标识已安装的扩展。请以新身份替换原身份下安装的扩展，而不是在原位更新：

gemini extensions uninstall prd-spec-generator
gemini extensions install https://github.com/cdeust/ai-architect-mcp-spec

配套生态

为充分发挥效果，请安装三个配套插件，让流水线能够利用代码库智能、持久记忆和 genius-agent 面板：

claude plugin marketplace add cdeust/ai-architect-mcp-codebase  # codebase graph intel
claude plugin marketplace add cdeust/Cortex                  # persistent memory
claude plugin marketplace add cdeust/zetetic-team-subagents  # the genius + team agents

claude plugin install ai-architect-mcp-codebase
claude plugin install hypermnesia-mcp
claude plugin install zetetic-team-subagents

每个插件都可以独立使用；组合起来便构成 ai-architect 生态系统。请参阅上文的配套生态。

从源代码构建

用于开发或在本地运行审计流程：

git clone https://github.com/cdeust/ai-architect-mcp-spec.git
cd ai-architect-mcp-spec
pnpm install --frozen-lockfile
pnpm build      # builds all 9 buildable packages via tsc
pnpm bundle     # produces the standalone mcp-server/index.js
pnpm test       # 1506 tests (vitest workspace, all packages; the
                # ai-architect-mcp-codebase wire contract is pinned
                # unconditionally — see docs/INTEGRATION-TESTING.md)

pnpm verify 会运行上述所有步骤（安装 + 构建 + 打包 + 测试）， 与 CI 相同。

从源代码构建的前置条件： Node.js 20.x 或 22.x、pnpm v10+ （corepack enable && corepack prepare pnpm@10）。

离线冒烟测试

# Reducer end-to-end without a real host (uses the canned dispatcher):
pnpm test --filter @prd-gen/orchestration smoke

# Benchmark KPI run:
pnpm test --filter @prd-gen/benchmark pipeline-kpis

两项测试在 M 系列 Mac 上均可在 <2s 内完成。不调用大模型，也不产生 MCP 流量——reducer 完全由预先录制的 ActionResults 驱动，因此你可以离线审计行为。

与其他 MCP 主机搭配使用

先明确适用范围。完整流水线依赖主机：reducer 会返回操作（ask_user、spawn_subagents、write_file），并假定主机能够执行这些操作并反馈结果。对于该工作流，Claude Code（通过插件 + /generate-prd 技能）仍是唯一提供打包支持的主机。

Codex 和 Gemini 则会接入可移植的规格验证器：不使用大模型，仅提供两个确定性工具以及相同的 audit-prd 和 validate-spec 技能：

• validate_prd_section — 对单个章节应用硬性输出规则
• validate_prd_document — 跨章节检查（SP/AC/FR/测试可追溯性）

通过代码库市场在 Codex 中安装：

codex plugin marketplace add cdeust/ai-architect-mcp-spec
codex plugin add ai-architect-mcp-spec@ai-architect-mcp-spec-marketplace

将同一软件包安装为 Gemini CLI 扩展：

gemini extensions install https://github.com/cdeust/ai-architect-mcp-spec

两个清单都会通过 --profile verifier 启动 mcp-server/index.js。现有的 Claude 清单不传入 profile，因此仍保留默认的 17 工具 full 接口。

零违规结果表示文档符合已实现的结构规则。它并不证明事实准确性、产品价值、实现可行性、安全性或语义正确性。

对于未打包的 MCP 主机，请克隆代码库并明确选择相同的精简 profile。将 /abs/path 替换为克隆位置。

git clone https://github.com/cdeust/ai-architect-mcp-spec.git /abs/path/ai-architect-mcp-spec
cd /abs/path/ai-architect-mcp-spec/mcp-server
npm ci --omit=dev

OpenAI Codex CLI（~/.codex/config.toml，与 ChatGPT 桌面应用和 Codex IDE 扩展共用）：

codex mcp add prd-spec -- node /abs/path/ai-architect-mcp-spec/mcp-server/index.js --profile verifier

Cursor（.cursor/mcp.json）和 Windsurf （~/.codeium/windsurf/mcp_config.json）：

{
  "mcpServers": {
    "prd-spec": {
      "command": "node",
      "args": [
        "/abs/path/ai-architect-mcp-spec/mcp-server/index.js",
        "--profile",
        "verifier"
      ]
    }
  }
}

VS Code（.vscode/mcp.json）：

{
  "servers": {
    "prd-spec": {
      "type": "stdio",
      "command": "node",
      "args": [
        "/abs/path/ai-architect-mcp-spec/mcp-server/index.js",
        "--profile",
        "verifier"
      ]
    }
  }
}

---

工作流

Reducer 会生成 20 个顺序执行的步骤：前 11 个用于生成 PRD，之后 9 个是可选的规格编写后实现步骤，只有通过人工关卡后才能进入。每个步骤最多发出一个实质性操作；宿主执行该操作并将结果反馈回来。一次典型的试用版功能运行（11 个章节）需要约 62 次宿主可见的迭代。

#	步骤	产出内容
1	banner	欢迎横幅，包含运行 ID、功能描述和能力摘要
2	preflight	在流水线依赖相关生态 MCP 之前，探测所需的生态 MCP（Cortex、ai-architect）；可通过 skip_preflight 跳过
3	context_detection	根据触发词检测 PRD 类型；遇到歧义时询问用户
4	input_analysis	提供路径时调用 index_codebase（ai-architect-mcp-codebase）；设置 codebase_graph_path
5	feasibility_gate	检测史诗级范围的输入（≥2 个 EPIC_SIGNALS）；请用户聚焦范围
6	clarification	先拟定问题再作答，轮数根据层级为 4–10 轮；用户表示“proceed”时提前结束
7	budget	根据 Cortex 论文的 60/30/10 比例，为每个章节分配检索／生成令牌预算
8	section_generation	一次处理一个章节：Cortex 召回 → 工程师起草 → 验证 →（最多重试 3 次）
9	jira_generation	根据 requirements + user_stories + acceptance_criteria 综合生成 JIRA 工单
10	file_export	按照 SKILL.md 写入 9 个文件（6 个核心文件 + 3 个配套文件）
11	self_check	两阶段多评审者验证（见下文）；在 done 中设置类型化的 verification 字段

步骤 12–20 是可选的规格编写后实现循环：implementation_gate（人工关卡——选择“Implement”或“PRD only”；同时写入 10-verification-report.md）→ pre_impl_grounding → implementation（在隔离的工作树中运行工程师子 Agent）→ post_impl_verification（索引 → 检测变更 → 语义差异 → 安全关卡）→ testing → review（FAIL 判定会在同一工作树上重试 implementation，重试次数受 REVIEW_RETRY_CAP 限制）→ pr_gate（推送前必须通过人工关卡）→ pr_creation → finalize。在 implementation_gate 回答“PRD only”会直接跳到 finalize；complete 是终止标记，而不是一个步骤。

每个步骤都可以独立测试（stepOnce(state, result?) 返回的结构与运行器相同）。运行器会在内部合并 emit_message 操作，因此宿主不会看到无操作。

---

MCP 工具

共有三个界面。Reducer 驱动完整流水线；其他系统无需进入流水线，即可直接使用验证、核验和预算工具；诊断界面则提供配置、健康状态和历史记录。

Reducer (3):
  start_pipeline             Initialize a run; returns first NextAction
  submit_action_result       Drive the reducer one step; returns next NextAction
  get_pipeline_state         Read-only state snapshot for diagnostics

Validation (2):
  validate_prd_section       Hard Output Rules — single section
  validate_prd_document      Cross-section checks (SP/AC/FR/test traceability)

Verification (3):
  plan_section_verification  Extract claims + select judge panels
  plan_document_verification Same, document-wide
  conclude_verification      Aggregate JudgeVerdict[] → VerificationReport;
                             accepts optional `claims` array carrying
                             `external_grounding` so oracle-resolved ground
                             truth can replace LLM-only consensus where
                             schema/math/code/spec oracles are available

Budget + feedback (2):
  coordinate_context_budget  Per-section token allocation
  map_failure_to_retrieval   Validation failure → corrective Cortex query

Diagnostics (7):
  get_config, read_skill_config, check_health, get_prd_context_info,
  list_available_strategies, get_quality_history, get_strategy_effectiveness

每个工具都接受经 Zod 验证的结构化参数，并返回类型化响应。没有工具会调用 LLM——章节草稿和评审者判定会通过宿主的 spawn_subagents 操作返回，因此同一条流水线可在任何 Agent 运行时上运行。

---

多评审者验证

self_check 步骤采用两阶段契约。阶段 A 规划验证批次，并将 (claim_ids, judges) 快照持久化到状态中。阶段 B 接收判定结果，根据快照解析这些结果，并通过共识引擎进行汇总。

plan_document_verification(sections[])
  → extracts atomic Claims (FR-001, AC-005, NFR-LATENCY-1, ...)
  → selects a panel per claim type:
      architecture        → liskov + alexander + dijkstra + architect
      performance         → fermi + carnot + curie + erlang
      security            → wu + ibnalhaytham + security-auditor
      data_model          → mendeleev + dba + lavoisier
      acceptance_criteria → toulmin + popper + test-engineer
      ...

[host spawns the panel; each agent returns a JSON verdict]

conclude_verification(verdicts[])
  → Per claim, runs consensus():
      strategy: weighted_average (default) | bayesian
      fail_threshold: 0.5  (≥50% confidence-weighted FAIL → forces FAIL)
      precautionary tie-breaker: more-severe verdict wins
  → distribution_suspicious flag fires when 100% PASS over ≥5 claims
  → returns ConsensusVerdict[] with full distribution + dissenting list

判定分类特意设置为五个级别，而非二元分类。NFR 声明（延迟、fps、吞吐量、存储）不得获得 PASS：如果指定了测量方法，则判定为 SPEC-COMPLETE；否则判定为 NEEDS-RUNTIME。默认对所有内容都判定为 PASS 的评审者会被 distribution_suspicious 检测器捕获，并在类型化的 done.verification 字段中标记。

校准与证伪

验证子系统本身也是一个假设：按历史校准的可靠性加权的共识优于按均匀先验加权的共识。下面的闭环正是用于检验这一假设。

1. 观察。 每次验证运行都可以将各评审者的观测结果（claim_id、claim_type、judge_id、verdict、oracle_truth?）写入 SQLite 可靠性存储库。观测结果包含 external_grounding 字段，该字段从 Claim 经过编排器传递到预言机判定路径；当外部预言机（Ajv schema、mathjs、tsc、validateSection）能够判定声明时，其真值将取代仅由 LLM 得出的共识。
2. 校准。 在后续运行中，校准后的后验概率会按评审者和 claim_type 对共识加权。20% 的对照组分区会强制使用先验进行探索（getReliabilityForRun / getRetryArmForRun 根据 run_id 确定性地决定某次运行进入哪个组）。没有对照组，校准效果的自我验证看起来总像是有进展，无论实际情况如何。
3. 比较。 跨组指标（computeAblationComparison、computeReliabilityComparison、computeKpiGateComparison）会运行成对自助法置信区间（Efron & Tibshirani 1993 §16.4；确定性 mulberry32 RNG；12 位小数的可复现性约束），并给出三种可证伪的建议之一：calibrated_helps、prior_helps 或 inconclusive_underpowered。
4. 封存。 留出分区会写入锁文件（§4.2 对应 maxattempts-heldout.lock.json，§4.5 对应 kpigates-heldout.lock.json，§4.1 中 50 条由外部依据判定的语料对应 heldout-partition.lock.json），并附上分区的 sha256 哈希。跨组指标函数将 SEAL_VERIFIED typeof sentinel 作为参数；只有先验证封存才能获得该 sentinel。在评估前查看留出分区会导致类型错误。
5. 以外部依据判定。 外部预言机能够确定性地判定声明时，就由它进行判定。如果无法判定，则抛出 OracleUnavailableError，而不是伪造存根模式下的真值。这正是打破标注者循环性的关键：使用非 LLM 真值进行校准时，接受过 LLM 风格推理训练（或受其影响）的评审者无法污染校准结果。

锁文件、封存验证流程和对照组分区结合在一起意味着：当跨组比较得出“在 95% 置信区间不包含零的情况下 calibrated_helps”时，这个结论是经过测量的，而非凭感觉判断的。如果结果是 inconclusive_underpowered，这同样是一个可证伪的结论——你需要更多数据，而不是更多信心。

---

架构

十个工作区包，各自都可以独立构建，并通过包边界强制执行严格的 Clean Architecture 分层。

core              ← domain types, schemas, agent identities
                    │  no I/O, no infrastructure dependency
                    │  Zod-validated; the only place where verdict /
                    │  section_type / capability shapes are defined
                    ▼
validation        ← Hard Output Rules (per-section + cross-section)
                    │  pure functions; no I/O
                    ▼
strategy          ← thinking-strategy selector (genius pattern routing)
                    │
meta-prompting    ← prompt builders for clarification / draft / jira
                    │  pure string composition
                    ▼
verification      ← claim extraction + judge selection +
                    │  consensus engine (weighted_average + Bayesian)
                    │  + buildJudgePrompt
                    ▼
orchestration     ← stateless reducer, 20 step handlers, runner
                    │  step(state, result?) → next_state, action
                    │  emit_message coalescing; canned-dispatcher utility
                    ▼
ecosystem-adapters← StdioMcpClient, AiArchitectCodebaseClient, CortexClient
                    │  the only package allowed to do I/O
                    ▼
mcp-server        ← composition root; 17 tools registered;
                    │  evidence repository (better-sqlite3, optional)
                    ▼
benchmark         ← pipeline KPI measurements + golden-fixture HOR scoring
                    │  + calibration/ subtree:
                    │    · ReliabilityRepository (SQLite, observation flush)
                    │    · Kaplan-Meier + log-rank + Schoenfeld N
                    │    · Clopper-Pearson exact CI + XmR control charts
                    │    · paired-bootstrap (Efron-Tibshirani 1993 §16.4)
                    │    · external oracles (Ajv / mathjs / tsc / validate)
                    │    · machine-class detector + frozen-baseline gates
                    │    · sealed held-out lock files (sha256 + SEAL_VERIFIED)
                    │    · production-mode dispatcher + AgentInvoker seam
                    │  Audit lineage: JSONL + .xmr sidecars per run.
skill             ← SKILL.md + slash-command definitions for Claude Code

依赖规则（绝对）

会检查每个包的 package.json：core 只能依赖 zod；verification 只能依赖 core；orchestration 依赖 core/validation/verification/meta-prompting（不能依赖 ecosystem-adapters）；ecosystem-adapters 依赖 core + verification；mcp-server 是唯一组合所有内容的地方。

一次跨层审计发现并修复了两处违反分层规则的问题：

• orchestration 从 ecosystem-adapters 导入了 extractJsonObject 和 buildJudgePrompt——纯工具函数放在了错误的包中；分别移至 core 和 verification。
• 纯领域类型（Claim、JudgeVerdict、JudgeRequest、AgentIdentity）位于 ecosystem-adapters/contracts/subagent.ts；现已移至 core/domain/agent.ts。基础设施包现在会重新导出这些类型，作为向后兼容垫片。

---

这解决了以往 PRD 生成器存在的问题

失效模式	我们的做法
各轮之间的章节内容漂移	每一步使用单一、不可变的 PipelineState 快照；reducer 为纯函数；宿主可以重放任意步骤
臆造符号	validate_prd_section 执行 Hard Output Rules；如果设置了 codebase_path，则将符号与 ai-architect-mcp-codebase 图谱交叉核对
NFR 未经测量便声称 PASS	判定分类不允许延迟/吞吐量/fps/存储相关结果判为 PASS；共识引擎会传递 SPEC-COMPLETE / NEEDS-RUNTIME
确认偏差（每位评审者都判定为 PASS）	当 ≥5 项声明的 PASS 比例达到 100% 时，触发 distribution_suspicious 标记；该标记会显示在类型化的 done.verification.distribution_suspicious 中
验收标准无法追溯到需求	跨文档校验器检查 FR-AC 覆盖情况和 AC 编号缺口
测试声称「全面」，却未列出覆盖内容	测试可追溯性规则：每个章节声称的测试都必须引用 FR 或 AC ID
重试时沿用导致失败的上下文	map_failure_to_retrieval 闭合 validator→Cortex 反馈环；重试前执行纠正性查询
预算采用魔法数字（「检索用 4K tokens」）	coordinate_context_budget 根据规范的 SECTIONS_BY_CONTEXT 计划生成各章节的分配额度

---

它如何与生态系统的其他部分协作

                            ┌────────────────────────────────────┐
                            │         Claude Code (host)         │
                            └────────────────────┬───────────────┘
                                                 │ stdio MCP
              ┌──────────────────────────────────┼──────────────────────────────────┐
              ▼                                  ▼                                  ▼
   ┌───────────────────┐              ┌────────────────────┐              ┌───────────────────┐
   │   ai-architect-   │   graph_path │   ai-architect-    │  recall      │      Cortex       │
   │   mcp-codebase    │ ───────────► │   mcp-spec         │ ◄─────────── │   (memory engine) │
   │   (Rust MCP)      │              │   (TS MCP)         │              │   (Python MCP)    │
   │                   │   symbols    │                    │  excerpts    │                   │
   │   read-only       │ ◄──────────► │   stateless        │ ───────────► │   thermodynamic   │
   │   intelligence    │              │   reducer          │              │   memory          │
   └───────────────────┘              └─────────┬──────────┘              └───────────────────┘
                                                │
                                                │ spawn_subagents
                                                ▼
                                  ┌─────────────────────────────┐
                                  │   zetetic-team-subagents    │
                                  │   97 genius + 19 team       │
                                  │   Each judge cites its      │
                                  │   primary paper.            │
                                  └─────────────────────────────┘

每个项目各司其职。ai-architect-mcp-codebase 负责了解代码中的事实。Cortex 负责了解我们已经做出的决策。zetetic-team-subagents 负责针对特定类型的声明进行推理。AI Architect MCP Spec 是确定性的粘合层，可将这三种信号转化为 Agent 可执行的 PRD。

---

求真标准

此代码库中的每个关键常量都带有 // source: 注释。接受以下三种形式：

// source: <citation>          // a paper, a spec, a referenced design doc
// source: benchmark <path>    // a committed benchmark whose output produced this value
// source: provisional heuristic — <calibration plan>
                               // honest admission; tells the next reader
                               // (a) why the value is what it is today and
                               // (b) what evidence would change it

交叉审计发现并标记了所有先前未标注的常量。示例：

// pipeline-kpis.ts
const KPI_GATES = {
  /** source: provisional heuristic. Smoke baseline = 62 iterations on
   *  trial+codebase; cap is 100 (~60% headroom). dijkstra cross-audit
   *  derived a structural max of 9 emit_message hops; the substantive-
   *  action count builds on that. Replace with measured P95 + 1σ once
   *  the calibrated baseline has enough runs. */
  iteration_count_max: 100,
  ...
};

// verification/consensus.ts
/** source: provisional heuristic — Beta(7,3) (mean 0.7, ESS=10,
 *  moderately informative toward reliability). Replaced per agent by
 *  Beta(α+correct, β+incorrect) once calibrated from history. */
const DEFAULT_RELIABILITY_PRIOR_MEAN = 0.7;

四大支柱（一致、真实、有用、必要）和求真探究的七条规则继承自 zetetic-team-subagents 标准。临时值不会被悄然当作事实传播。

---

这个系统不会做什么

同样的标准也适用于系统自身。

1. PRD 流水线不会编写代码——服务本身也绝不会编写代码。 步骤 1–11 会生成 PRD；PRD 中的符号会依据图进行验证，但我们绝不会编辑这些符号。选择加入的实现循环（步骤 12–20）只有在人类在 implementation_gate 回答“Implement”时才会运行；在此阶段，宿主的工程师、测试工程师和代码审查员子 Agent 会在隔离的工作树中编写、测试和审查实现，而且未经强制要求的 pr_gate 批准，不会推送任何内容，也不会将其转成 PR。此服务只会发出 spawn_subagents 操作——绝不会自行编辑源文件或推送分支。
2. 它不会验证文案质量。 硬性输出规则会检查结构不变量（FR 编号、AC 可追溯性、NFR 格式、交叉引用），但不会检查句子是否写得流畅或有说服力。这正是多评审阶段的作用；即便如此，评审者也只会对主张——原子化断言——给出判定，而不是评判风格。
3. 评审阶段可以端到端测试，但评审者并不具备确定性。 在测试中，我们使用一个固定的分发器，按设计始终返回 100% PASS；distribution_suspicious 检测器的存在，正是因为真实的评审小组也可能退化为确认式共识，而我们不会假装这不可能发生。
4. KPI 门槛经过校准，而非随意选定。 iteration_count_max、wall_time_ms_max 和 mean_section_attempts_max 是基于 K=100 冻结基线进行校准的，采用 Clopper-Pearson 精确 CI、按机器类别进行 wall_time 标准化，以及 loadCalibratedGates + hold_provisional 防护机制。锁定文件会提交基线的内容哈希；事后篡改会导致密封验证失败。数据仍然不足时，门槛会保持 hold_provisional 状态，而不会被锁定。完整的预注册方案请参阅 docs/PHASE_4_PLAN.md。
5. 存在引用 ≠ 引用有效。 无论 Knuth 1998 是否真实存在，或是否能支持该数值，// source: Knuth 1998 注释都符合约定。我们强制要求引用确实存在；而跨审计循环（每个阶段均进行 genius + 团队审查）才是确保引用真实可靠的机制。

---

重现审计循环

此代码库提供了一个多 Agent 跨审计工作流。每个重要阶段结束后：

# Engineering team review:
#   architect, code-reviewer, refactorer, test-engineer, security-auditor,
#   devops-engineer, dba (when relevant)

# Genius team review:
#   feynman (integrity), curie (measurement), popper (falsifiability),
#   dijkstra (correctness), shannon (signal), deming (variation),
#   poincare (qualitative), ...

每个 Agent 都会读取代码的当前状态（而非凭记忆），并按严重程度排序，生成一份分级问题清单。在提出问题的那个周期内就会关闭问题；任何无法在不进行新测量的情况下关闭的问题，都会连同关闭它所需的证据一并记录并结转，因此延期是一项明确列出的义务，而不是沉默不语。

---

项目布局

packages/
├── core/                  Domain types · schemas · agent identities · evidence repo
├── validation/            Hard Output Rules · per-section + cross-section validators
├── verification/          Claim extraction · judge selection · consensus engine
├── meta-prompting/        Prompt builders (clarification / draft / jira)
├── strategy/              Thinking-strategy selector
├── orchestration/         Stateless reducer · 20 step handlers · runner · canned-dispatcher
├── ecosystem-adapters/    StdioMcpClient · AiArchitectCodebaseClient · CortexClient
├── mcp-server/            Composition root · 17 MCP tools registered
├── benchmark/             Pipeline KPI measurement · golden-fixture HOR scoring
│   └── calibration/       ReliabilityRepository · KM survival ·
│                          Clopper-Pearson · XmR · paired-bootstrap ·
│                          external oracles · sealed held-out partitions ·
│                          production-mode dispatcher
└── skill/                 SKILL.md · slash-command definitions

---

许可证

MIT — 详见 LICENSE。

项目文档： 路线图（项目未来一年计划做什么，以及不会做什么）· 贡献指南（如何提议更改，以及测试政策）· 治理（由谁决策，以及维护者停止维护后项目会如何发展）· 安全（如何报告漏洞，以及供应链保障）· 保障论证（安全论证及其适用范围）· 行为准则 · 更新日志。

本软件由 Clément Deust 独立开发，属于其个人作品。它在任何雇佣关系之外开发，与任何过去或现在的雇主均无关联，也未获其背书或归其所有。本软件是 ai-architect 生态系统的一部分（Cortex、 ai-architect-mcp-codebase、 zetetic-team-subagents）。

算法和常量的引用及主要来源，均按照项目的来源标注规则，通过代码中的 // source: 注释记录。移除这些注释不会改变许可条款，但会失去对代码所依据的原始研究的归属说明。

---

别发布一份凭空捏造出无法衡量的功能的 PRD。
发布一份由 Pearl、Curie、Liskov 和另外七位评审者共同评判、依据调用图验证，并以 Cortex 对昨日的记忆为基础的 PRD，让其中的每一项声明都有据可依。