Ouroboros Seed Architect 完全指南：从访谈会话到不可变 Seed 规格的需求提取与验收契约设计

• AI Agent
• 人工智能
• 代码智能体
• Agent 编排
• AI 评测
• CLI
• 开发工具

Seed Architect 是 Ouroboros Agent OS 中负责"把访谈（Interview）会话转化为不可变 Seed 规格"的关键 Agent 角色——Seed 被称为工作流执行的"宪法"（constitution），承载目标、约束、验收标准与领域本体。本文以 Seed Architect 角色定义 为骨架，结合seed_generator、answer_provenance、core/seed等源码实现，系统讲解 provenance 标记语义、七大提取组件、验收标准（AC）成功契约的verify/artifacts/expect三件套写法、粒度契约判定，以及 Seed 生成的歧义门槛与严格解析边界，让你既能照规范手写可被执行的 Seed 提取输出，也能理解底层引擎如何校验与落盘。

Seed Architect 在 Agent OS 中的位置

Ouroboros 的典型工作流是一条"访谈门控（Interview-gated）"流水线：先通过多轮访谈把模糊的原始诉求收敛为明确需求，再由 Seed Architect 从访谈逐字稿中提取结构化需求，生成不可变的 Seed 规格，最后执行引擎（orchestrator、boundary 执行胶囊等）以该 Seed 为唯一事实来源运行与评估。源码中这一转换由 seed_generator.py 的SeedGenerator承担，它会调用 loader.py 的load_agent_prompt("seed-architect")加载本角色提示词，并让 LLM 按提示词中的输出格式完成结构化提取（见 seed_generator.py:2132）。

Seed 一经生成即不可变（Pydanticfrozen=True），方向性字段（goal、constraints、acceptance_criteria）在生成后不可修改，作为评估与迭代的"ground truth"；而本体（ontology）可在后续进化迭代中演进。相关数据模型定义在 core/seed.py，运行时语义解释层（把 Seed 投影为执行契约）在 core/seed_contract.py。

阅读访谈记录：provenance 标记与"观察扣留"

访谈中每条回答都带一个来源标记（provenance marker），Seed Architect 的第一步就是据此区分"决策"与"事实"：

• [from-user]（或无标记）：用户做出的决策（decision）。
• [from-code]、[from-repo]、[from-research]：用户从别处采纳的事实（adopted fact）——例如现有系统的状态、查到的资料。事实不是决策，只有决策才能成为需求。

这条规则在源码中有严格落地：answer_provenance.py 定义了OBSERVATION_PREFIXES = ("[from-code]", "[from-repo]", "[from-research]", "[from-data]")，classify_answer_provenance()据此把回答分类为"user"或"observation"；extraction_rounds()对 observation 回答不做投影——内容根本不会出现在需求读取的"回答槽位"里，从而在构造上杜绝"把事实复述成决策"。

当一条被采纳的事实本应出现时，你会看到占位符：

A: [observation withheld — an adopted fact, not a decision. It informed the questions that follow.]

这是故意为之，不是截断或错误。不要索取其内容、不要猜测、不要把这条注释本身当作需求——用户从该事实中提炼的需求已经存在于他自己的回答里，提取那个即可。观察内容仍然完整保留在"问题槽位"中，因为它的职责是打磨后续提问。

关于问题行：问题会完整展示（包括复述采纳事实的问题）。问题只用于让紧随其后的回答可被解读，问题本身不是决策，问题行里的任何内容都不能单独成为需求。

需要提取的七大组件

1. GOAL —— 目标

清晰、具体的主要目标陈述。例如：

GOAL: Build a CLI task management tool in Python

在 Seed 模型中对应Seed.goal（min_length=1，非空字符串，见 core/seed.py）。

2. CONSTRAINTS —— 约束

必须满足的硬性限制。格式为单行 JSON 字符串数组。值中可以包含任意字符（包括字面|管道符），绝不能用裸管道符作为列表分隔符——这正是要求 JSON 数组的原因，让数据内的|存活为数据。示例：

CONSTRAINTS: ["Python >= 3.12", "No external database", "Must work offline"]

对应Seed.constraints: tuple[str, ...]。解析实现在_parse_string_array_values()（seed_generator.py）：严格模式（提取时）要求必须是合法 JSON 字符串数组，否则走重试路径让模型重排格式；宽松模式（读取存量旧数据）才回退到历史管道符切分。

3. ACCEPTANCE_CRITERIA —— 验收标准（核心）

具体、可度量的成功标准。格式为恰好一个非空的单行 JSON 数组，每个对象恰好包含description、verify、artifacts、expect四个字段：

• description：字符串，可观察的产出状态。
• verify：字符串（shell 命令）或NONE。
• artifacts：路径的 JSON 数组，或字符串NONE。
• expect：字符串（输出字面量断言）或NONE。

单契约示例：

ACCEPTANCE_CRITERIA: [{"description":"Tasks can be created","verify":"python -m pytest tests/test_tasks.py -q","artifacts":"NONE","expect":"NONE"}]

多产物示例：

ACCEPTANCE_CRITERIA: [{"description":"Build outputs exist","verify":"NONE","artifacts":["dist/app","docs/User Guide.md"],"expect":"NONE"}]

注意：ACCEPTANCE_CRITERIA必须作为一行上的一个字段输出，绝不能展开成嵌套的多行AC:行。行锚定的字段前缀（GOAL:、CONSTRAINTS:等）是提取器扫描的基础——seed_generator.py 甚至会先剥离某些 CLI 前端给行首加的时间戳（如[13:57:34]），因为这类前缀会破坏行锚定解析。

verify / verify_command 语义

• 使用恰好一条单行 shell 命令。
• 绝不使用 heredoc 或任何多行 shell 语法：<<、<<'PY'、cat <<EOF、续行脚本、未闭合的命令块都不行。AC 契约格式是一行，多行命令体在落盘时会被丢弃。
• Python 片段用python -c "..."/python3 -c "..."；较长的检查应产出可被 pytest 发现的测试产物，然后用python -m pytest -q。
• verify是观察者（OBSERVER），绝不是写入者（writer）：runner 会哈希命令执行前后的工作区，任何创建、修改或删除了工作区文件的运行都会被拒绝（workspace_mutated），且重试无法修复——因为契约本身错了。字节码缓存和 Git 忽略的构建产物可豁免；状态文件、fixture、日志、生成数据不可豁免。
• 因此，当被测程序会写状态（JSON 存储、数据库文件、输出文档）时，把它复制进临时目录并在那里运行：

verify: t=$(mktemp -d) && cp app.py "$t"/ && cd "$t" && python3 app.py add x && python3 app.py list

绝不在工作区里写rm -f state.json && python3 app.py ...这种先删后跑的命令。

这些规则在源码层被硬校验：_unsupported_verify_command_reason()拒绝含换行/回车或 POSIX heredoc 操作符（<</<<-）的命令（seed_generator.py），检测器_contains_posix_heredoc_operator()甚至能在引号、参数展开、算术展开的上下文中正确识别嵌套 heredoc，防止用<<'EOF'之类拼写绕过。

artifacts / expected_artifacts 语义

• 每个条目都是相对于运行工作区的精确可移植路径（文件或目录）。runner 逐字解析每个条目并要求其存在。
• 多个条目编码为一个 JSON 数组，例如"artifacts":["dist/app","docs/User Guide.md"]。
• 路径内不要放逗号或反斜杠。路径分隔符统一用 POSIX/。
• 绝不用描述性标签当路径，例如schema v2 outputs、user approval record都不行。
• 顶层含空格的文件/目录要加./前缀，例如./Build Outputs；嵌套路径如docs/User Guide.md本身已明确，无需前缀。
• 不知道确切路径时写artifacts: NONE，并给出具体的verify命令。
• 文件/目录存在性本身可以构成完整契约；对于可能仍处于 pending 或 blocked 的有状态产物，还应补充一条检查其语义状态的verify命令。

路径可移植性在AcceptanceCriterionSpec的校验器中有完整实现（core/seed.py）：拒绝空值/控制字符、NONE混入、反斜杠、逗号、绝对路径、..逃逸、Windows 保留组件（CON/COM1/LPT1等）、单组件超过 255 字节、完整规范化路径超过 255 可移植字节、以及"含空格但无显式目录结构又未加./"的歧义写法。此外还有成功契约总预算：产物数 ≤ 253、每条 ≤ 2038 字符、契约总字符 ≤ 64000（见 core/seed.py 与validate_ac_success_contract_values()）。

expect / output_assertion 语义

• expect只用于断言 verify 命令合并 stdout+stderr 中逐字出现的字面字符串，例如OK或5 passed。
• 绝不用条件、状态或退出码描述，如exit code 0、exit 0、returns 0、success、no errors、passed、passes——退出码 0 已由 runner 另行验证。
• 命令没有可断言的独特输出字面量时写expect: NONE。

源码用正则_OUTPUT_ASSERTION_CONDITION_RE（core/seed.py）直接拒绝上述条件类描述，且output_assertion必须与verify_command成对出现（没有 verify 的断言会触发校验错误）。注意：只要expect非NONE，verify也必须非NONE。

粒度契约（务必细读）

验收标准命名的是成品工作的状态（state of the finished work）——用户能亲眼确认其为真的东西；实现步骤命名的则是抵达该状态的手段（means of reaching that state）。这是两个不同范畴，只有前者属于这里——决定手段是执行引擎在运行时的工作，它在掌握最终结果时比你对路径的猜测决策得更好。

所以对每条标准都要问：它是什么类型的东西？把它和兄弟条目放在一起读：

• 能独立成立、是用户会珍视的东西 →outcome（结果），留在列表。
• 只有作为向兄弟条目迈进的步骤才能被理解 → 那是该兄弟的means穿着 outcome 的外衣，应并入它所服务的结果条目。

把 means 留在验收标准列表里，其严重性等同于缺失需求——它在任何人验证路径正确之前就锁死了执行路径。一个目标有多少条标准，是该目标的属性，通过做出上述判断来发现，而不是预设数量。

对应模型层面，AcceptanceCriterionSpec提供has_success_contract属性（core/seed.py）——契约只添加证据，绝不减少逐字稿义务，也不覆盖 worker 执行结果。

4. ONTOLOGY —— 本体（领域模型）

本工作的数据结构/领域模型：

• ONTOLOGY_NAME：领域模型的名字。
• ONTOLOGY_DESCRIPTION：本体代表什么。
• ONTOLOGY_FIELDS：关键字段，单行 JSON 对象数组，每项含name、type、description。

字段类型只能是：string、number、boolean、array、object。

对应模型OntologySchema/OntologyField（core/seed.py），其中OntologyField.required默认true。本体是工作流各迭代轮次应保持的概念透镜，但不强制规定最终输出形态。解析器_parse_ontology_fields()同时接受别名field_type与可选的布尔required。

5. EVALUATION_PRINCIPLES —— 评估原则

评估产出质量的准则。格式：单行 JSON 对象数组，每项含name、description、weight（0.0–1.0），以 JSON 数组承载是为了让文本里的冒号和管道符作为数据存活。示例：

EVALUATION_PRINCIPLES: [{"name":"completeness","description":"All requirements implemented","weight":0.4},{"name":"quality","description":"Code meets standards","weight":0.3}]

对应EvaluationPrinciple模型（core/seed.py），weight默认 1.0，超范围会 clamp 到 [0.0, 1.0]（_clamp_weight()处理溢出饱和、NaN、Infinity 等边界）。Seed模型还容忍手写种子用纯字符串列表表达原则（自动包装为principle_N对象）。

6. EXIT_CONDITIONS —— 退出条件

指示工作流应终止的条件。格式：单行 JSON 对象数组，每项含name、description、criteria。对应ExitCondition（core/seed.py，criteria是evaluation_criteria的别名）。

7. BROWNFIELD CONTEXT —— 存量代码库上下文（如适用）

若访谈提到现有代码库，提取：

• PROJECT_TYPE：greenfield或brownfield。
• CONTEXT_REFERENCES：单行 JSON 对象数组，每项含path、role（primary表示要修改、reference表示只读）与可选summary。对应ContextReference（core/seed.py）。
• EXISTING_PATTERNS：必须遵循的关键模式，单行 JSON 字符串数组。
• EXISTING_DEPENDENCIES：要复用的关键依赖，单行 JSON 字符串数组。

对应BrownfieldContext（core/seed.py）；greenfield 项目保持默认值（project_type="greenfield"、空引用）。

输出格式：完整的结构化字段模板

按下列精确结构输出分析结果。特别注意ACCEPTANCE_CRITERIA是一行上的一个字段，绝不发出嵌套的AC:行：

GOAL: <clear goal statement> CONSTRAINTS: ["<constraint 1>", "<constraint 2>", ...] ACCEPTANCE_CRITERIA: [{"description": "Observable outcome", "verify": "python -m pytest -q", "artifacts": ["path/to/artifact"], "expect": "NONE"}] ONTOLOGY_NAME: <name> ONTOLOGY_DESCRIPTION: <description> ONTOLOGY_FIELDS: [{"name": "<name>", "type": "<string|number|boolean|array|object>", "description": "<description>"}, ...] EVALUATION_PRINCIPLES: [{"name": "<name>", "description": "<description>", "weight": <0.0-1.0>}, ...] EXIT_CONDITIONS: [{"name": "<name>", "description": "<description>", "criteria": "<criteria>"}, ...] PROJECT_TYPE: greenfield|brownfield CONTEXT_REFERENCES: [{"path": "<path>", "role": "<primary|reference>", "summary": "<summary>"}, ...] EXISTING_PATTERNS: ["<pattern 1>", "<pattern 2>", ...] EXISTING_DEPENDENCIES: ["<dep 1>", "<dep 2>", ...]

• 字段类型限string/number/boolean/array/object；权重在 0.0–1.0 之间。
• 要具体、要落到实处：从对话中提取真实需求，而不是通用占位符。
• 对于 brownfield 项目，必须从访谈中提取上下文引用和模式，不能凭空编造。

角色提示词还内置了 few-shot 示例，展示多条 AC 与多条 verify 的组合写法：

ACCEPTANCE_CRITERIA: [{"description":"Task create/list flows pass automated verification","verify":"python -m pytest tests/test_tasks.py -q && echo OK","artifacts":"NONE","expect":"OK"},{"description":"Greeting import check prints OK","verify":"python -c \"from hello import greet; assert greet('Alice') == 'Hello, Alice'; print('OK')\"","artifacts":["hello.py"],"expect":"OK"},{"description":"README documents the CLI usage examples","verify":"NONE","artifacts":["README.md"],"expect":"NONE"}]

源码级纵深：SeedGenerator 如何消费这份输出

理解角色输出格式后，再看生成器如何校验它，有助于你一次写对：

1. 歧义门槛（ambiguity gate）：SeedGenerator.generate()在提取前先检查访谈的歧义分数必须 ≤ 0.2（AMBIGUITY_THRESHOLD，见 seed_generator.py），不达标则返回ValidationError而非生成 Seed。force=True可绕过门槛，但真实分数仍写入SeedMetadata.ambiguity_score，保证 provenance 诚实。Gen 2+ 路径（提供reflect_output与parent_seed）则直接使用 ReflectEngine 精炼后的 AC 与本体突变，跳过歧义门控。
2. 低温度提取：提取用的温度固定为EXTRACTION_TEMPERATURE = 0.2，最大重试_MAX_EXTRACTION_RETRIES = 1，模型可通过OuroborosConfig的seed_generation角色或构造参数指定（get_llm_model_for_role("seed_generation")）。
3. 严格 JSON 边界：ACCEPTANCE_CRITERIA 的解析是"精确设计"——acceptance_criteria_parsing.py 拒绝未知字段（不会静默丢弃）、拒绝重复 JSON 键、拒绝空数组、要求每个对象恰好含description/verify/artifacts/expect（可选exempt携带免验证原因），并拒绝"声称有输出断言却没有产生它的命令"的条目。
4. POSIX 词法扫描：_iter_outer_ac_field_markers()用带状态机的 POSIX shell 词法分析器扫描 verify 命令串，能在单引号、双引号、转义、$()/${}/反引号替换、甚至嵌套case结构内部正确区分"外层| verify:/| artifacts:字段标记"与"命令载荷里的同名文本"，防止伪造或截断（见 seed_generator.py）。
5. 需求蒸馏与提升策略（Requirement Promotion Policy）：当存在确定性的需求提升策略时，它以权威身份生效——只有被列入 promoted 集合的候选才能成为硬需求或验收标准，参考派生与模型推断的被遗漏候选保持为假设。绝不能在没有用户明确确认的情况下，把产品参考资料、术语表解释、视觉品味信号或模型猜测变成验收标准。该机制由 requirement_distillation.py 实现：build_requirement_distillation()从初始上下文与访谈轮次构建保守候选投影，observation 回答在候选提升这一步同样被跳过（与提示词中的扣留规则一致），参考感知的蒸馏还会走无 LLM 的确定性 Seed 构建路径。
6. 持久化：生成的 Seed 可通过save_seed_sync()/save_seed()写入 YAML（默认输出目录~/.ouroboros/seeds），也可用load_seed()读回。Seed 用metadata.seed_id、version、created_at、ambiguity_score、interview_id、generation_mode等记录生成来源；降级恢复路径（如partial_seed_from_evidence）必须声明degraded=True与unresolved_slots，否则校验失败（core/seed.py）。

验证与测试：你的输出会在哪里被检验

test_seed_generator.py 对上述行为做了大量回归覆盖：包括对 verify 命令中"相邻单引号片段"（如printf'%s| artifacts: literal'、python -c'print("| verify: literal")'）的解析、对遗留管道分隔数据的宽容回退、对畸形 AC 字段的拒绝等。测试还验证了 runner 侧ParallelACExecutor以verify_command_timeout_seconds和ac_retry_attempts=0执行契约时的行为——也就是说，你写进verify的每条命令最终都会由执行器在运行时真实运行、哈希比对工作区变化、解析产物存在性并匹配expect字面量。

写作检查清单（输出前自问）：

• 这条回答是用户做出的决策，还是从别处采纳的事实？只有前者能进需求。
• 这条 AC 是成品状态（outcome），还是达成兄弟条目的手段（means）？means 必须并入它所服务的结果。
• verify是否单行、无 heredoc、且绝不写入工作区？写状态就用mktemp -d复制后运行。
• artifacts是否都是精确可移植路径，无逗号、无反斜杠、无描述性标签、顶层空格路径加了./？
• expect是否是命令输出中逐字出现的字面字符串，而非退出码/状态的描述？
• 所有字段是否都按单行 JSON 数组的格式输出，且ACCEPTANCE_CRITERIA独占一行？

遵循上述规范产出的 Seed，才能通过歧义门槛与严格契约校验，成为后续执行与评估可信赖的"宪法"。

• AI Agent
• 人工智能
• 代码智能体
• Agent 编排
• AI 评测
• CLI
• 开发工具