likang/cdsl-cad

Fork 0

Files

T

likang bc87bd6d2d 重构改为标准化输出

2026-09-01 14:10:23 +08:00

70 KiB

Raw Permalink Blame History

自主 CAD 生成协议：可靠性与 Token 效率目标

1. 目标与结论

本目标直接替换当前自主 CAD 协议，不保留旧任务兼容、迁移或恢复路径。目标是在不降低建模判断能力的前提下，消除当前“先生成大型 Markdown 建模计划，再按计划生成 CDSL”的硬门，并把每一轮 LLM 的输出缩小为可验证的单个建模动作。

必须达成：

LLM 决定下一步建模意图和操作。 服务端不生成 CAD 步骤、不替 LLM 选 operation、不把需求编译成几何模板。
服务端只负责事实、约束和状态转换。 它提供不可变需求、当前模型、拓扑、Runtime 合同、已接受动作及复核证据；校验 LLM 的选择，执行 CDSL，持久化真实结果。
不再要求新任务生成或复核 modeling-plan.md，不再出现计划版本、计划解析、计划动作 ID、计划 revision limit 或计划跳步门。
保留 source-requirements.md、requirements.md、completion.md、单 feature CDSL、候选构建、独立候选复核、检查点和最终独立复核。
LLM 产生的每一项会改变状态、影响执行或作为验收依据的数据，必须通过固定 Pydantic schema 或 Runtime 动态 JSON Schema 校验。Markdown 和解释文本只由服务端从已验证数据渲染，绝不被解析为状态机输入。
可靠性的含义不是假定任何 LLM 永不产生错误格式，而是错误格式、过期引用和不符合 operation 合同的输出在任何副作用之前被确定性拒绝；它们不能创建候选、污染状态、消耗构建预算或触发无限重试。
文档和动作的格式问题必须是无副作用的可诊断拒绝；内部服务错误必须一次失败并保留检查点，不能被伪装成 LLM/CDSL 错误后循环重试。
v3 必须完成架构解耦。 “LLM 决策、Runtime contract、任务状态机、候选构建、持久化、渲染/复核”必须是职责明确、依赖方向受控的独立模块；不能继续集中在一个巨型 runner/service 中，或通过模块全局对象互相访问。
使用真实 API usage（可用时）和服务端上下文字节数度量 token 消耗，验收时以基线任务集比较，不以主观感觉判断。

这不是“取消计划后让服务端推断下一步”。计划能力仍存在，但由 LLM 在每个检查点结合当前事实重新判断；服务端保存的是实际发生过的动作账本，而不是预先要求 LLM 写完整未来路径。

2. 当前基线与已确认问题

当前路径由 backend/app/services/autonomous_cdsl_generation.py 实现：

服务端创建不可变 source-requirements.md。
作者 LLM 写入并立即冻结 requirements.md。
作者 LLM 写入并立即冻结 completion.md。
作者 LLM 必须写大型 modeling-plan.md，独立模型审查它，失败后重写版本。
作者 LLM 按计划动作读 Runtime contract，提交一条 CDSL feature。
服务端构建候选，独立模型审查，接受后提交 checkpoint。
完成清单覆盖后执行最终重建和视觉复核。

cad_30933fe2fc6b 已在 rev_003 生成正确的法兰：圆盘、中心贯穿孔、四个均布孔均已构建并接受。该任务随后失败的根因包括：

_final_review 使用了未赋值的 global_violations，导致每次 complete_task 都触发 NameError。这是确定性的后端缺陷，不是 CDSL 或 LLM 错误。
调度器把上述内部异常归类为 authoring/fragment 错误，并允许重复 complete_task；因此无检查点进展的重试最终命中 NO_PROGRESS_LIMIT。
建模计划审查要求精确 operation、selector、盲孔深度和 action 粒度，但计划又允许自然语言。这种“自然语言写入，严格执行含义”的双重合同使法兰计划在 hole_blind | hole_wizard、多孔单 action 和 through-equivalent 深度等问题上反复返工。
CDSL_MODELING_PLAN_MAX_REVISIONS=2 的检查在计划已写入及审查后执行，并且后续循环仍可能继续，形成“已到上限却继续调用”的矛盾控制流。

已直接修复第一项：最终重建得到 health 后，现在会先调用 _global_geometry_violations(...)，再使用该变量。这一改动必须保留，并以最终复核回归测试覆盖。

2.1 真实 LLM 连通性测试

2026-08-31 在隔离临时任务根目录中，直接使用当前后端的 AgentService._complete_once 和完整 runner 调用配置的真实作者模型，依次发送了三个请求：矩形底板、简单法兰、带肋和四个安装孔的底板。第一个请求尚未产生工具调用或 CAD 工件时，OpenAI 作者请求已连续三次连接失败；runner 随后切换到 DeepSeek，同样连续三次失败。

测试发现 _is_author_transport_error 分支在所有作者 provider 失败后仍以约 4.5 秒间隔无限重试，使任务永久处于 running。测试已手动终止，以避免无意义 API/CPU 消耗；没有生成模型，因此不能把这次测试伪称为模型生成质量结果。该证据证明当前 transport 恢复策略存在流程缺陷，必须在 P0 修复：记录有限的 provider/总调用预算和指数退避，超限后将任务转为 WAITING_RETRY，保留 checkpoint 和调用诊断；只能由显式恢复操作或受控调度重新启动，而不能在同一个 run 中无限循环。

3. 不采用的方案

以下方案不满足本目标：

不保留现有 Markdown 计划，只改提示词。 它仍把未来的操作、selector 和精确 Runtime 语义要求压到一次大输出中，根因未消失。
改成 LLM 一次输出大型 JSON/DAG 执行计划。 JSON 更容易解析，但不能消除大输出遗漏、过期 selector、前后依赖和重试 token 消耗；问题从 Markdown 转移到 JSON。
服务端依据未覆盖需求决定下一步。 这会把建模策略藏在程序规则中，违反“LLM 决定下一步”的边界，也会让复杂零件的 CAD 判断不可审计。
取消独立候选/最终复核。 能减少 token，但会显著降低最终几何可信度；优化应先删除重复的计划复核与冗余上下文，而不是删除实际结果复核。
用盲孔深度大于厚度作为所有通孔的唯一证明。 这只是候选输入条件；最终仍须从拓扑/几何证明孔连接了预期两侧面、孔数和直径满足要求。

4. 新协议中的工件、结构化输出与验证

4.1 统一的结构化输出边界

不得让 LangChain、任何 provider 或 Pydantic 自身成为可信边界。它们只负责请求和解析；服务端必须对原始 tool arguments 再做一次 canonical validation，验证通过后才允许写库、构建候选或改变 revision。

LLM provider
  -> LangChain structured-output adapter
  -> 原始 tool arguments / JSON
  -> Pydantic 或 JSON Schema canonical validator
  -> 当前 task、revision、权限和幂等校验
  -> Runtime / CDSL / 几何验证
  -> SQLite 事务提交

固定业务对象使用 Pydantic v2 模型生成 JSON Schema；例如需求草稿、审查 verdict、动作提案、修复决定都必须是 extra="forbid" 的模型。不同 operation 的 CDSL fragment 由 Runtime contract 生成动态 JSON Schema，不能伪装成一个“所有参数都可选”的静态 Pydantic 模型。需求草稿的外层是固定 Pydantic schema，但每个 acceptance_claim.expected 是 verifier registry 在当前任务启动时生成的 closed oneOf；这同样是动态 schema，不能用 dict[str, Any] 放过未知 claim 数据。

LangChain 仅封装在 cad_agent/adapters/structured_llm.py 或等价 adapter 内：

固定对象使用 with_structured_output(PydanticModel)。
动态 operation contract 使用 bind_tools() 或 provider 的等价 tool schema 接口，传入服务端生成的 JSON Schema。
无论 provider 宣称支持 strict JSON、function calling 或 JSON mode，服务端都使用相同的 Pydantic/jsonschema validator 二次验证。
禁止使用 LangChain Agent、Memory、文本 JSON 提取、自动无限 re-ask 或自动 tool 执行。CAD runner 仍是唯一状态机。
不具备成功通过 provider conformance test 的 structured-output / tool-call 能力的模型，不可作为生产作者或审查模型。不能为了“支持任意模型”退回纯文本解析。

每次 LLM tool call 都经过同一条严格管线：限制一个允许的 tool name 和一个 call、限制原始 arguments 的字节数/JSON 深度、解析 JSON、schema canonical validation、当前状态与版本绑定、跨字段/几何 preflight，最后才进入事务或候选构建。provider 的 parser、LangChain 的 parser 和 Pydantic 的第一次反序列化都不是最终结论。服务端保留经脱敏的原始 arguments 与字段级错误用于诊断，但不会以“尽量修复”方式补全、重命名或猜测 LLM 字段。

工具的 schema_name、schema_version、当前 working_head、contract_hash 和 selector snapshot 由服务端 route/state 绑定，而不是信任 LLM 声称的版本。固定对象可以在工具 schema 中携带这些字段并做 canonical equality 校验；空参数命令（例如完成请求）则只以服务端暴露它的状态作为版本绑定。任何 schema 或 contract 变更都会使旧 pending action 失效，必须重新读取当前事实和合同。

4.2 需求和完成工件

source-requirements.md 是服务端保存的用户原文，不要求格式。服务端把它按原始段落或附件块生成稳定 source_id，只作为可引用证据，不尝试用规则理解自然语言。

LLM 不直接写 requirements.md 或 completion.md。它提交受严格 schema 约束的、分批且有上限的 RequirementsDraftBatch；服务端校验并保存 JSON，再渲染人类可读 Markdown。草稿阶段还必须使用结构化 RequirementsPatchBatch 修订 reviewer 指出的条目，并以零参数 finalize_requirements_draft() 明确请求进入独立复核。服务端在 source coverage 不完整时拒绝该最后一步，不自行猜测“需求已经写完”：

source-requirements.md                    # 服务端创建，不可变
documents/source-index.json               # 服务端生成：source_id -> 原始文本
documents/requirements-draft-v1.json      # 仅已验证 RequirementsDraftBatch 合并结果
documents/requirements-review-v1.json     # 严格结构化的独立审查结果
requirements-contract.json                # 冻结的机器可验证需求与验收合同
requirements.md                           # 服务端从 contract 渲染，不作为程序输入
completion.md                             # 服务端从 contract 渲染，不作为程序输入
requirements-index.json                   # 服务端生成的 req/claim 索引

每次 submit_requirements_draft_batch 最多提交 8 条 requirement，避免大型一次性文档输出。外层固定 schema 至少包含：

{
  "items": [
    {
      "source_ids": ["src_001"],
      "statement": "法兰为外径 120 mm、厚度 12 mm 的单一连通实体",
      "assumptions": ["未指定标准时采用普通平面法兰"],
      "acceptance_claims": [
        {
          "claim_kind": "solid_count_equals",
          "expected": {"value": 1}
        },
        {
          "claim_kind": "bbox_dimension_mm",
          "expected": {"axis": "z", "value": 12, "tolerance_mm": 0.01}
        }
      ]
    }
  ]
}

source_ids 必须来自服务端 enum；claim_kind 必须来自已注册 verifier enum；每一种 claim_kind 的 expected 都按该 verifier 专属 JSON Schema 校验。服务端分配不可变的 draft item ID、req_### 与 claim_###，不会接受 LLM 自定义 ID。

RequirementsPatchBatch 的每一项只能是 replace 或 remove，并且 target_draft_id 必须是当前 draft revision 的 enum。replace 必须携带完整、重新验证过的 requirement 对象，不能提交局部自然语言 patch；remove 必须给出长度受限的原因。这样 reviewer 修改的是可审计的单项，而不是要求模型重写整份文档。删除后若使 source 无覆盖，finalize_requirements_draft() 必须被拒绝。

冻结前，独立 reviewer 必须返回 RequirementsReview。它对每一个 source_id 给出恰好一行 coverage（该行可引用一个或多个 requirement ID），并对每一个 draft item 给出 pass、revise 或 waiting_for_user。pass 只有在全部 source 已被映射、全部 claim 的 verifier 可用且不存在冲突时有效。一个 source 可以支撑多条 requirement；因此不要求 source 只被一条 requirement 引用，只要求 reviewer coverage 行唯一且完整。waiting_for_user 必须具有 machine-readable reason code 和受限的提问文本，不能用模糊 prose 隐藏关键尺寸或基准缺失。

requirements.md 和 completion.md 可以是自然、自由的 Markdown，因为它们是 JSON contract 的只读渲染。例如：

- [ ] 单一连通实体，外径 120 mm、厚度 12 mm
- [ ] 同轴直径 40 mm 的中心贯穿孔
- [ ] 节圆直径 90 mm 上四个直径 10 mm 的均布贯穿螺栓孔

程序永远不从上述 Markdown 重新提取 ID、验收项、步骤或状态。任何可测几何需求若没有注册 verifier，必须在需求阶段报 VERIFIER_UNAVAILABLE，不得偷偷降级为“让视觉模型看一看”。确实只能依赖外观判断的要求可显式声明为 visual claim，但其风险必须在任务界面标记。

需求草稿、修订和 review 的 canonical schema 还必须有以下共同约束：所有数组有上下限，所有可见文本有长度上限，所有枚举/ID 来自当前服务端快照，嵌套对象 additionalProperties=false；禁止任意 JSON object、任意键值 metadata 和未注册 claim。若需求是文件命名、材料、单位或展示约束，也必须绑定相应的确定性 verifier；没有 verifier 就不能被冻结为可发布合同。

4.3 LLM 的单动作意图

LLM 不再写模型级执行计划。没有待处理动作时，作者只可调用 propose_next_action。该 tool 的 JSON Schema 由服务端传给模型并在服务端再次校验；不得接受 Markdown、自由 JSON 字符串或未知字段。

{
  "working_head": "head_5f2e...",
  "intent": "在当前法兰顶面加工四个均布螺栓孔",
  "requirement_ids": ["req_003"],
  "atomic_id": "hole_blind",
  "expected_change": "新增四个直径 10 mm、在节圆直径 90 mm 上等角分布并贯穿 12 mm 本体的孔"
}

约束：

intent、expected_change 为短文本（建议分别最多 360 字符），只说明当前动作，不复述全任务。
requirement_ids 必须来自 requirements-index.json 的 enum，最多引用五项。
atomic_id 必须来自当前 Runtime SUPPORTED_ATOMIC_IDS enum。
working_head 必须与服务端发出的 opaque current-head token 完全相等；Pydantic 检查其形状，canonical state validator 检查其相等性。
提案不包含 selector、草图、参数、深度、工作平面或 CDSL；这些属于后续读取精确 contract 后的 canonical fragment。
提案必须绑定当前 working_head。检查点变化后旧提案不可提交，需由 LLM 基于新事实重新提出。

因此格式错误无法“完全不发生”，但影响面被限制为一个极小、严格 schema 的无副作用调用：服务端返回字段级错误并保留模型/检查点，不会再生成计划版本、消耗候选构建次数或污染账本。

4.4 服务端动作账本

账本不是 LLM 输出，也不是执行计划。服务端在动作提案、拒绝、候选构建、复核和 checkpoint 后，以 append-only JSON Lines 写入 actions/action-ledger.jsonl。每一行是一个状态事件，便于审计、恢复和增量读取：

{"schema_version":"cad.action-ledger.v1","sequence":7,"event":"proposed","action_id":"act_003","working_head":"main:rev_002","intent":"在当前法兰顶面加工四个均布螺栓孔","requirement_ids":["req_003"],"proposed_atomic_id":"hole_blind","expected_change":"新增四个直径10 mm贯穿孔","at":"2026-08-31T...Z"}
{"schema_version":"cad.action-ledger.v1","sequence":8,"event":"accepted","action_id":"act_003","working_head_before":"main:rev_002","revision_id":"rev_003","actual_atomic_id":"hole_blind","fragment_sha256":"...","selector_snapshot_id":"...","candidate_id":"candidate_...","review_path":"revisions/rev_003/reviews/candidate-review/candidate-review.json","coverage":[{"requirement_id":"req_003","status":"complete"}],"at":"2026-08-31T...Z"}

运行中的 pending action 是事务状态，不从 JSONL 反推。它只保存 action_id、working_head、提案内容、contract hash 和幂等 key。给作者的上下文只包含 pending action 与压缩后的最近动作摘要，完整账本仅用于审计/UI 查询，避免随模型复杂度线性膨胀 prompt。

4.5 CDSL 与完成调用

提交 CDSL 的动态 tool schema 不存在“统一的 feature JSON 模板”。它只暴露当前 pending action 已选择的一个 operation 的 author-owned 字段；下面只是一个形状示意，实际是否有 sketch、是否有 params、是否有 selector/reference token 由 operation contract 决定：

{"fragment": {"sketch": {"...": "仅 contract 要求时存在"}, "feature": {"atomic_id": "与 pending action 相同", "params": {"...": "contract 精确字段"}}}}

移除 batch_goal、plan_step_id、plan_action_id。候选复核的目标、需求映射和 operation 均从 pending action 与真实 fragment 取得，不能由 LLM 在提交时再次声称。

动态 schema 必须由当前 Runtime 的完整、版本化 feature_atomic_contract 唯一生成，并与 contract_hash、working_head、engine/profile schema revision 和 selector snapshot ID 绑定。当前 feature_atomic_contract 仅列出 required/optional 参数，而 cdsl_authoring_schema.py 仍按 operation 名称硬编码很多 JSON 类型、hole 特例和 pattern 注入；这会产生 contract drift，不能作为 v3 的终态。P2 必须把这些信息收拢到 Runtime contract registry，删除 authoring schema 中按 operation 前缀补规则的兜底分支。

每个 operation contract 至少声明以下数据，且 contract 自身先经 JSON Schema / registry integrity validator 验证：

{
  "atomic_id": "hole_blind",
  "contract_version": "3.0",
  "fragment_shape": {
    "sketch": "forbidden",
    "params": "required_object",
    "selector_tokens": "required"
  },
  "author_params_schema": {"type": "object", "additionalProperties": false},
  "selector_policy": {
    "slot": "params.host_face",
    "token_kind": "face",
    "min_items": 1,
    "max_items": 1,
    "snapshot_bound": true
  },
  "server_injected_paths": ["params.host_face"],
  "reference_policy": {"mode": "none"},
  "semantic_preflight": ["host_face_exists", "hole_positions_on_host_plane"],
  "candidate_verifiers": ["cylindrical_bore", "through_cylindrical_bore"]
}

其中 author_params_schema 是 closed JSON Schema，必须递归关闭其嵌套对象。禁止用 {}、type: object 未限制 properties、任意 dict 或“其它 operation 以后再解释”的 fallback 暴露给作者。hole_wizard 的 hole_type、thread、countersink、counterbore 等嵌套对象必须各有枚举/closed 子 schema；当前的开放对象定义不满足此要求，必须在该 operation 可暴露前补齐。

动态 schema 必须精确表达以下 operation 差异，而不能靠 prompt 约定：

fragment_shape.sketch=required 时 sketch.workplane 和 sketch.profile 必填；forbidden 时 sketch 出现即拒绝。profile 类型和每层字段同样由 closed schema 限制。
fragment_shape.params=required_object 时 params 必须存在并匹配该 operation 的专属 schema；若 operation 没有 author-owned 参数，contract 明确指定 params 是必填的空 object 还是 forbidden，不能假设所有 feature 均需或均不需参数。
selector_policy 只能为 forbidden、required 或明确的 optional。required selector 的 token schema 是当前 snapshot 中匹配 kind 的 opaque token enum，并有精确数量上限；没有有效 snapshot 时根本不暴露 fragment tool。host_face、mirror plane 等 server-owned selector 只由 resolver 注入，LLM 提供原始 selector object 或注入字段即拒绝。
reference_policy 处理 feature-source、reference plane/axis 等关系。禁止当前实现中“默认把最后一个 committed feature 当 pattern source”的通用猜测；若关系不是 contract 可唯一推导，schema 必须要求来自当前 feature-reference snapshot 的 opaque token，并由服务端解析为 Runtime ID。
每个 operation 只允许自身的 required/optional params，additionalProperties=false；例如 extrude_cut_blind.distance_mm 不能替换为 hole 的 depth_mm，hole 的 positions 也不能出现在 extrude。所有数字必须是有限值，并满足 Runtime 安全范围、单位和 operation 专属的跨字段限制。
atomic_id 必须同时等于 pending action、active contract 和动态 schema 的 const；三者任一不一致均在构建前拒绝。
新增 Runtime operation 时，必须同时新增完整 operation contract、contract integrity fixture、动态 schema fixture、canonical validator 测试、semantic-preflight 测试、引擎执行测试和对应 verifier；缺任一项不得进入作者可选 atomic_id enum。

动态 schema 校验成功后仍必须依次通过：当前 revision/head 校验、contract hash 与 registry revision 校验、selector/reference snapshot 校验、operation semantic preflight、静态 CDSL schema、完整 materialized CDSL validation 和隔离 CDSL-only rebuild。前六项均不产生候选目录；只有通过后才消耗候选构建预算。schema 不能表达的关系必须由 preflight/geometry validator 检查，例如工作平面正交且法向非零、profile 不自交、hole position 位于宿主面、revolve axis 位于草图平面，以及为了满足“贯穿” claim 的 hole_blind 或 extrude_cut_blind 的切削方向、有效行程和出口面连通性。

complete_task 改为无参数 tool。删除 self_review，因为作者的自我声明不能作为完成证据。服务端仅在当前 revision 的独立 coverage 全部完成且没有 pending/rejected repair 时暴露该 tool。

4.6 每类 LLM 输出的可信边界

LLM 输出	输出方式	必须由程序验证	不由它控制的内容
需求草稿/修订/提交复核	`RequirementsDraftBatch`、`RequirementsPatchBatch`、`finalize_requirements_draft()`	字段、source/draft-ID enum、批量上限、claim kind 的动态 `oneOf`、重复项、累计 source coverage	Markdown 文档、req/claim ID、draft/review 状态、冻结状态
需求独立审查	`RequirementsReview` Pydantic schema	每个 source_id 的唯一 coverage 行、每个 draft item verdict、引用的 req/claim 存在、`WAITING_FOR_USER` reason code	是否冻结由服务端 coverage gate 决定
下一动作	`NextAction` Pydantic schema	requirement ID enum、Runtime operation enum、working head、无 pending action、幂等键	action_id、pending 状态、实际 CDSL ID
观察/测量/contract 请求	固定 Pydantic tool schema，动态 enum 绑定当前 head/snapshot	参数范围、当前 revision、selector kind/limit、operation enum；每回合只接受允许的一个 tool call	观察结果、contract、selector/reference token 均由服务端生成
CDSL feature	当前 operation 的动态 JSON Schema	contract hash、`const atomic_id`、fragment shape、递归 closed params、selector/reference enum、静态 CDSL、语义 preflight、引擎 preflight	feature/sketch ID、dependency、host face、selector/reference 解析
诊断、回滚与完成请求	`GeometryConclusion`、`RollbackCheckpoint`、`complete_task()`	decision enum、当前 evidence ref enum、rollback token、head、文本/数组上限；完成 gate 由服务端先验证	几何诊断证据、回滚可达性、发布判断
候选审查	`CandidateReview` Pydantic schema	candidate/revision enum、claim coverage 的精确集合、verdict enum、证据上限；确定性 verifier 必须先通过	checkpoint 提交、coverage 更新
最终审查	`FinalReview` Pydantic schema	current revision、所有 final claim 的精确集合、verdict enum、证据上限；所有 deterministic claim 必须通过	发布、published revision
可见解释/意图文字	普通文本字段，长度限制	仅编码、安全和长度检查	不参与任何状态转移或 CAD 参数计算

“结构化输出通过”只证明对象格式和引用有效，不证明 CAD 语义必然正确。语义正确性必须由 source coverage、requirement acceptance contract、Runtime、几何 verifier 和独立 review 共同证明；其中 deterministic verifier 失败时，任何 LLM 的 accept verdict 都不能覆盖失败。

4.7 Canonical schema 目录与二次校验

以下目录是 v3 必须实现的唯一 LLM 输入合同。每个固定模型均使用 Pydantic v2 的 strict model（extra="forbid"、显式长度/数量限制），由服务端导出 JSON Schema；动态 enum 和 dynamic oneOf 在每次 tool 暴露时由服务端收窄。任何新的 state-changing LLM tool 必须先加入本表、fixture、conformance test 和错误映射，不能临时添加自由 object 参数。

Tool / 输出模型	必填结构化字段	schema 类型	格式后仍必须程序校验
`submit_requirements_draft_batch` / `RequirementsDraftBatch`	`items[1..8]`；每项有 `source_ids`、`statement`、`assumptions`、`acceptance_claims`	Pydantic outer + verifier registry 的 closed claim `oneOf`	source enum、去重、claim 语义/单位、可用 verifier、draft transaction
`patch_requirements_draft` / `RequirementsPatchBatch`	`patches[1..8]`；`target_draft_id`、`op=replace	remove`；replace 携带完整 item	Pydantic + current draft-ID enum
`finalize_requirements_draft`	空 object	fixed empty schema	至少一个 draft item、无缺 source、无不可用 claim 后才可进入 review
`review_requirements` / `RequirementsReview`	`verdict`、每个 source 的唯一 coverage row、每个 draft item verdict、`issues[]`	Pydantic + source/draft/claim ID enum	coverage 精确集合、issue code、approve gate；服务端而非 reviewer 冻结 contract
`propose_next_action` / `NextAction`	`working_head`、`intent`、`requirement_ids`、`atomic_id`、`expected_change`	Pydantic + Runtime operation/requirement ID enum	head equality、无 pending action、operation available、idempotency
事实读取工具	例如 `inspect_topology(kind, limit)`、`get_cdsl_operation_contract(atomic_id)`、`render_section(origin_mm, normal)`	Pydantic，动态 operation/head/snapshot enum	参数范围、访问当前 revision、预算/缓存；结果只能由服务端生成
`submit_cdsl_fragment`	只有当前 operation contract 定义的 fragment	Runtime-generated Draft 2020-12 JSON Schema	contract/schema/snapshot hash、引用解析、cross-field semantic preflight、materialized CDSL schema、engine preflight
`record_geometry_conclusion` / `GeometryConclusion`	`working_head`、`evidence_refs`、`root_cause`、`decision`、受限 `corrective_intent`	Pydantic + current evidence enum	evidence 属于同一 head、decision 可达；`corrective_intent` 不直接成为 CDSL
`rollback_checkpoint` / `RollbackCheckpoint`	`working_head`、`checkpoint_token`、受限 reason	Pydantic + active lineage enum	token 是祖先、没有 candidate/transaction 冲突、原子 branch transition
`review_candidate` / `CandidateReview`	`candidate_id`、`revision/head`、`verdict`、精确 claim coverage、受限 evidence/issues	Pydantic + candidate/claim enum	candidate identity、确定性 claim gate、reviewer 不能覆盖 deterministic result
`complete_task`	空 object	fixed empty schema	没有 pending action/repair，所有 deterministic claim pass；为 final review 创建幂等工作项
`review_final` / `FinalReview`	`revision/head`、`verdict`、精确 final claim coverage、受限 evidence/issues	Pydantic + final claim enum	final rebuild identity、全局 invariant、deterministic/visual gate、一次发布事务

GeometryConclusion.decision 只能是 return_to_action_selection、rollback 或 waiting_for_user；它不包含 feature ID、参数、selector 或下一段 CDSL。选择修复仍由下一次 NextAction 明确作出，避免诊断对象暗中变成第二套执行计划。CandidateReview 与 FinalReview 允许模型提出 reject/repair；对确定性 claim，服务端只把 reviewer 的 accept 当作额外条件，而不是证明。

5. 完整执行流程及 LLM 边界

阶段	输入/产物	LLM 生成内容	服务端职责	失败后的唯一去向
0. 创建	用户请求	无	创建 `source-requirements.md`、任务与 run	请求错误，拒绝创建
1. 需求草稿	source index + 用户上下文	`submit_requirements_draft_batch(RequirementsDraftBatch)`，每次最多 8 项；按需 `patch_requirements_draft(RequirementsPatchBatch)`，最后 `finalize_requirements_draft()`	outer Pydantic、source/draft-ID enum、verifier dynamic schema、去重和批量事务；只保存 JSON	`AUTHOR_FORMAT_INVALID` 或 `REQUIREMENTS_COVERAGE_INCOMPLETE`，不写 Markdown、不进入建模
2. 需求独立复核	source index + draft contract	`review_requirements(RequirementsReview)`	coverage 行、假设/冲突/验收可行性；通过后冻结 JSON 并渲染 `requirements.md` / `completion.md`	`revise` 回到阶段 1；歧义为 `WAITING_FOR_USER`；缺 verifier 为 `VERIFIER_UNAVAILABLE`
3. 选择下一动作	frozen contract、claim coverage、当前模型摘要、账本摘要、Runtime operation enum	`propose_next_action(NextAction)`	Pydantic、ID enum、head、operation、幂等和 pending-action 校验	无副作用 `AUTHOR_DECISION_REJECTED` 或 Runtime 前置条件错误
4. 收集事实	当前 checkpoint	LLM 自主调用结构化 inspect/measure/render/topology/contract tools	返回真实、版本绑定数据；为动态 fragment 生成 selector/reference enum、限额和缓存	snapshot 过期或 selector/reference 不匹配，保留 checkpoint，重新观察
5. 生成 CDSL	pending action + 精确 operation contract + 相关 snapshot	`submit_cdsl_fragment(DynamicOperationSchema)`	contract/head/snapshot-bound dynamic JSON Schema、静态 CDSL、语义/引擎零副作用 preflight	`CDSL_SCHEMA_INVALID` 或 `RUNTIME_PRECONDITION_FAILED`，只允许修正当前动作；不消耗候选尝试
6. 构建候选	materialized CDSL	无	隔离 rebuild、健康检查、拓扑、deterministic claim verifier、渲染	`CANDIDATE_BUILD_FAILED` 或 `CLAIM_VERIFICATION_FAILED`，保留基线并进入诊断/修复或回滚
7. 独立候选复核	渲染、真实 CDSL、拓扑、pending action、只读 claim 结果	`review_candidate(CandidateReview)`	验证结构化 verdict/claim coverage；deterministic claim 失败时强制 reject	reject 形成明确 repair card；review 服务故障为 typed service failure，不让作者重做几何
8. 写账本/检查点	accepted candidate	无	原子提交 revision，追加 accepted ledger，更新 claim coverage，清除 pending action	存储失败必须原子回滚，不出现半提交
9. 下一轮	新 checkpoint	回到阶段 3，由 LLM 决定下一动作	仅提供最新事实	同上
10. 最终完成	当前 revision、claim coverage、最终渲染	`complete_task()`，无参数；`review_final(FinalReview)` 由独立 reviewer 输出	CDSL-only rebuild、全部 deterministic claim、全局几何不变量、结构化最终独立复核、发布	repair 回阶段 3；内部故障一次标为 `FAILED_INTERNAL`

阶段 3 的“下一步”必须由 LLM 做决定。服务端不可根据未覆盖的 req_003 自动构造“加工螺栓孔”；它只能在 LLM 提出 hole_blind 后检查该选择是否是当前 Runtime 支持的原子操作、是否与 checkpoint/contract 相容，以及是否可安全进入下一阶段。

6. 可靠性规则

6.1 明确错误分类

定义可序列化的错误码和类别，禁止将 Python 异常文本当作 authoring error：

AUTHOR_FORMAT_INVALID：tool 参数或 canonical CDSL schema 无效；无 CAD 副作用，可限次数修正。
AUTHOR_DECISION_REJECTED：动作与当前 pending/head/contract 不一致；无 CAD 副作用，要求重新选择或修订。
STALE_WORKING_HEAD：command 的 head、state version、contract 或 selector/reference snapshot 已过期；无 CAD 副作用，返回最新事实，禁止自动合并或覆盖新的 checkpoint。
FAILED_AUTHOR_FORMAT：同一 schema 的字段级修正次数达到上限，或 provider 持续不能交付该 schema；终止本 run 并保留 checkpoint，不能改记为 NO_PROGRESS_LIMIT 或降级到自由文本。
RUNTIME_PRECONDITION_FAILED：selector 不存在/歧义、body/host 缺失、操作不支持；保留 checkpoint，要求新的观察或动作决策。
RUNTIME_CONTRACT_INVALID：operation registry 缺少 closed field schema、注入/selector/reference policy、semantic preflight 或与 engine schema 不一致；这是部署/代码缺陷，feature 不得暴露给作者，也不能归因于 LLM。
CANDIDATE_BUILD_FAILED：BRep/STEP 构建失败；消耗候选预算，进入诊断、修复或回滚。
CANDIDATE_REVIEW_REJECTED：几何已构建但不符合动作或需求；保留证据，LLM 决定修复/回滚。
VERIFIER_UNAVAILABLE：冻结的 requirement claim 没有已注册且可运行的 verifier；不得创建 task contract 或发布。
CLAIM_VERIFICATION_FAILED：候选/最终 deterministic verifier 得到 fail；LLM reviewer 不能覆盖该结果。
MODEL_STRUCTURED_OUTPUT_UNSUPPORTED：provider/model 未通过当前 schema 的 conformance suite；任务开始前拒绝，不进入 author loop。
AUTHOR_TRANSPORT_UNAVAILABLE、REVIEW_SERVICE_UNAVAILABLE、RENDER_SERVICE_UNAVAILABLE、STORAGE_FAILURE：基础设施失败；不归入 no-progress、不允许 author 重复 CDSL。使用相同幂等键和有限指数退避重试服务操作，超限后进入 WAITING_RETRY，由显式恢复操作或受控调度重新开始。
FAILED_INTERNAL：未预期异常（例如 NameError）；记录 traceback/版本/调用幂等键，立即终止该 run，保留最后 checkpoint。
WAITING_FOR_USER：源需求冲突、关键尺寸/基准不可合理假设、或多轮文档复核无法消除的语义歧义；不是 failed。

NO_PROGRESS_LIMIT 只统计作者在允许的观察/决策阶段反复作出没有状态推进的合法但无效选择；同一无副作用格式错误超过上限应归为 FAILED_AUTHOR_FORMAT。它绝不能统计 FAILED_INTERNAL、RUNTIME_CONTRACT_INVALID、verifier/review/render/network/storage 故障，也不能把重复 complete_task 视为可继续作者修正的机会。WAITING_RETRY 只用于可恢复的基础设施失败，WAITING_FOR_USER 只用于用户决定缺失，二者都不能掩盖 author format failure。

6.2 幂等与事务

每个状态改变 tool call 有 invocation_id；每个候选/最终复核有基于 task_id + working_head + action_id + fragment_hash 的幂等键。
同一 complete_task 对同一 revision 最多执行一次最终重建/复核；调用中断后恢复相同结果或明确失败，不能重新进入作者循环。
candidate commit、task revision 更新、pending-action 清除和 ledger append 必须在同一事务内完成。
新协议的权威可变状态采用 SQLite（任务、run、pending action、ledger index、invocation、coverage），STEP/GLB/CDSL/Markdown/渲染仍保留在任务目录作为不可变工件。WorkspaceStore 重构为“数据库状态 + 文件工件”，不允许 JSON 与数据库双写且各自成为事实来源。
task.json 可以作为 API/人工查看的派生快照，不能再是并发状态机的权威来源。
外部 build/render/review 不能与 SQLite 假装存在同一事务。候选工件先写入不可见的 staging 目录，并带有输入 head、fragment hash、engine version 和每个文件 sha256 的 manifest；只有所有 preflight/build/verifier 都成功，才原子 rename 到不可变 revision artifact 位置。随后 SQLite 条件事务写入 revision、coverage、ledger index 和已存在 artifact manifest 引用；API 只通过 SQLite 引用读取工件，因此在数据库提交前已发布的文件仍不可见。进程崩溃时恢复器验证 manifest/hash，清理未引用工件或复用已发布的同 hash 工件；不会让 active revision 指向尚未发布的文件。
状态事件写入 transactional outbox，与状态迁移同一 SQLite 事务提交；stream/UI 通知由 outbox dispatcher 幂等发布，不能由 command handler 直接 emit。这样断连、重放或前端失败不会回滚已确认的 CAD checkpoint，也不会导致重复 build。

6.3 几何验证

selector 必须来自当前 topology snapshot；零个候选报 selector_not_found，并列候选报 selector_ambiguous，不可默认取第一个。
对“贯穿孔”建立 topology 断言：孔轴对应的圆柱面必须连通目标进/出平面；验证孔数、直径、位置/节圆和穿透方向。depth_mm >= body_thickness 只可作为 preflight 辅助证据。
对需要“等效贯穿”的 hole_blind 和 extrude_cut_blind，preflight 必须从实际宿主面/工作平面、切削方向和目标实体计算最小出口距离；不足则拒绝为 RUNTIME_PRECONDITION_FAILED。候选与最终阶段仍以拓扑连通性为最终结论，不能以参数名称或深度文字代替。
多位置 hole_blind 在同一 host face、孔径和深度一致时必须允许为一个 action/一个 feature；不得被 review 层拆成四条虚假要求。
全局不变量（单实体、显式尺寸等）在候选和最终重建两处都执行，二者使用同一函数；最终复核不得引用未初始化的局部变量。

6.4 验收 verifier registry

requirements-contract.json 中的每一个 acceptance_claim 必须引用一个注册 verifier。每个 verifier 是服务端代码，不是 LLM prompt，至少定义：

claim_kind
expected_json_schema
required_artifacts                # CDSL / rebuild report / topology / render
evaluate(current_revision) -> pass | pending | fail | unavailable
evidence() -> 结构化测量和工件引用

首批必须覆盖当前项目已能可靠观测的内容：

claim_kind	程序化证据
`solid_count_equals`	CDSL-only rebuild 的 `solid_count`
`bbox_dimension_mm`	rebuild bbox 指定轴和容差
`cylindrical_bore`	topology 的圆柱面、直径、轴线和位置
`through_cylindrical_bore`	bore verifier 加上入口/出口平面连通性
`circular_hole_pattern`	孔数、直径、节圆半径、角间距、宿主面与穿透状态
`coaxial` / `coplanar`	topology 几何轴线、法向和容差
`single_connected_body`	rebuild solid count 与连通性
`visual`	固定 render + 独立 reviewer；必须明确标为非确定性

每个 checkpoint 都计算所有 claims：尚未由前序几何满足的 claim 为 pending，已经被错误几何破坏的 claim 为 fail。候选不得因未来工作仍是 pending 而被拒绝；但如果动作引用的 requirement 已经被 fail、或任何全局 invariant 为 fail，候选必须拒绝。最终发布要求所有 deterministic claim 为 pass，所有 visual claim 获独立 reviewer pass。LLM reviewer 只能拒绝或为 visual claim 提供证据，永远不能把 deterministic fail 改成 pass。

verifier registry 的注册也是可靠性边界：registry 启动时必须校验 claim_kind 唯一、expected_json_schema 为有效的 closed schema、required artifacts 可由当前 engine/rebuild 产生、evaluate 可序列化返回结构化 evidence。任何 verifier 在候选/最终运行时不可用都返回 unavailable 和 VERIFIER_UNAVAILABLE，不得把 claim 静默转成 visual。

6.5 Provider conformance 与模型切换

切换模型不得修改 CAD runner、Pydantic 模型、Runtime contract 或 verifier。新增 provider/model 时先运行真实 API conformance suite，成功后才写入 model_capabilities：

固定 Pydantic schema：必填字段、enum、嵌套对象、数组上限、additionalProperties=false。
强制指定 tool 与模型返回多个 tool call 时的行为。
每一个已注册 Runtime operation 的动态 fragment schema，至少验证 required params、forbidden params、requires_sketch 差异、selector token enum 和 const atomic_id。
usage、timeout、429、断连、空 choices、无 tool call 和无效 JSON 的统一错误映射。
provider 的 strict schema、普通 tool calling、JSON mode 分别记录；只能选择实测通过的模式。

能力档案不通过时拒绝启动任务，返回 MODEL_STRUCTURED_OUTPUT_UNSUPPORTED。格式失败时允许有限次数的同 schema re-ask，错误信息只含 validator 的字段级结果；每次失败均不创建候选、不消耗 build 预算、不改变 revision。达到格式上限必须显式进入 FAILED_AUTHOR_FORMAT；只有 transport/限流等基础设施重试超限才进入 WAITING_RETRY。两者都绝不降级为自由文本执行。

6.6 架构、依赖与状态机边界

v3 采用 Ports and Adapters（六边形）架构、显式 command handler 和有限状态机。目的不是增加抽象层数量，而是让“LLM 选择下一动作”和“程序证明、执行、持久化该动作”在代码上无法相互越界。autonomous_cdsl_generation.py 当前同时承担 prompt、tool schema、状态迁移、CDSL materialization、文件读写、候选构建、review 和重试；v3 不得保留这种万能 service。

依赖方向只能由外向内：API/UI 与 adapter 可依赖 application；application 可依赖 domain 与 port；domain 不得导入 FastAPI、LangChain、SQLite、文件路径、engine、renderer 或 settings。adapter 只能实现 port，不能直接改变 task state 或绕开 command handler。composition root 是唯一可以同时 import application、adapter 和 settings 的位置。

API / worker / stream
        -> application: command handlers + workflow coordinator
        -> domain: immutable state, transitions, contracts, policies
        <- ports: TaskRepository, ArtifactStore, ModelGateway, CadRuntime,
                  ReviewGateway, VerifierExecutor, EventPublisher, Clock
        <- adapters: SQLite/files, LangChain/providers, CDSL engine,
                     renderer, reviewer, outbox dispatcher

模块职责固定如下：

层级	模块/对象	允许做什么	明确禁止
domain	`TaskState`、`PendingAction`、`Revision`、`OperationContract`、claim/verifier policy、transition function	不可变 value object、跨字段规则、合法状态迁移、typed error/result	I/O、网络、文件、SQL、prompt 拼接、选择下一 CAD action
application	`CommandHandler`、`WorkflowCoordinator`、`UnitOfWork` 使用方、context assembler	接收已验证 command、读取 snapshot、调用 port、安排幂等 side effect、提交 transition/outbox	直接解析原始 LLM JSON、直接访问 SQLite/路径、按 operation 名称写参数规则、从 requirement 推导下一动作
ports	Python `Protocol`/interface	声明 repository、artifact、LLM、runtime、review、event 等依赖的输入输出和 failure contract	保存业务状态、提供默认实现、泄漏 provider/engine 私有对象
adapters	`StructuredModelGateway`、SQLite repository、artifact store、CDSL runtime、renderer/reviewer、outbox dispatcher	调用外部系统并翻译为 port 的 typed result/error	决定 workflow transition、修改 domain object、吞掉/重新归类内部异常
delivery	FastAPI、worker、stream、frontend mapper	鉴权、请求/响应、启动 command、消费 outbox event	CAD 规则、状态迁移、直接读写 task 文件

固定采用以下模式和约束：

Command + Result。 每个 state-changing tool 映射到一个 typed command；handler 只返回 Accepted、Rejected(typed_error)、Waiting 或 FailedInternal 这类结果。预期业务失败不以 Python exception 驱动控制流；adapter 未预期 exception 在边界转为 FAILED_INTERNAL 并携带 correlation ID。
有限状态机。 持久化状态至少为 DRAFTING_REQUIREMENTS、REVIEWING_REQUIREMENTS、AWAITING_ACTION、ACTION_PENDING、CANDIDATE_BUILDING、CANDIDATE_REVIEW、FINAL_VALIDATION、WAITING_RETRY、WAITING_FOR_USER、COMPLETED、FAILED。观察/测量是只读 command，不新增持久化 phase；tool 可见性由 state、pending action 和 snapshot 派生，不能由 prompt 文本隐式决定。
Strategy + registry。 operation contract、semantic preflight 和 verifier 以已验证 registry entry 注册；不得以 if atomic_id.startswith(...) 在 runner 中散落规则。registry 选择由已验证 atomic_id 完成，不能演变为 service locator 或反射执行任意插件。
不可变快照与乐观并发。 command 带 working_head、schema/contract hash、必要的 selector/reference snapshot；repository 以 task state version/head 做 compare-and-swap。冲突返回 STALE_WORKING_HEAD，不会合并或覆盖较新的 checkpoint。
Unit of Work + transactional outbox。 SQLite 是唯一状态提交点；工件、LLM、engine、renderer 等非事务性副作用通过 invocation/candidate staging 和 outbox 与状态机衔接，不允许“先更新 task.json，再希望文件/stream 成功”。
依赖注入和 composition root。 handler 构造时显式传入 ports；测试替换为 in-memory/fake adapter。禁止 handler/validator 内部调用 load_engine()、读取全局 settings、创建 HTTP client 或直接 new WorkspaceStore。

状态迁移必须集中在纯函数/transition table 中，并作为架构测试覆盖。一个 handler 的标准过程是：读取 immutable snapshot -> canonical/schema/state validation -> 注册或复用 invocation idempotency record -> 调用必要 port -> 以 expected state version 计算 domain transition -> 单一 Unit of Work 提交 state、ledger index、outbox。build/review 这类长时操作先持久化 processing invocation/candidate 状态，重启后从该记录恢复；同一 idempotency key 只能得到一个最终 result，不允许重新生成第二个候选。每一次 command、adapter call、candidate、review 和 outbox event 都记录同一 task_id、run_id、invocation_id、head/state version 的结构化 correlation fields；日志不得保存密钥、完整用户附件或未脱敏 prompt。

LLM 的回合管理也服从这个边界：WorkflowCoordinator 只根据当前 workflow state 请求 ModelGateway 输出允许的一个 structured command，然后交给对应 handler；它不分析 requirement 文本、不了解某个 hole 的字段，也不自行选择 operation。prompt/context assembly 是 application service，输入只能是 domain projection 和 port 返回的事实快照；operation schema 由 runtime contract adapter 提供。

为防止架构随时间退化，测试必须检查 import dependency rules、每个 port 的 adapter conformance、domain transition table、crash recovery/outbox 重放和并发 CAS 冲突。autonomous_cdsl_generation.py 只能在过渡期作为迁移入口；v3 发布前必须删除其中的业务实现，替换为薄 composition/compatibility-free bootstrap，不能只是把原函数移动到新文件。

6.7 真实 LLM 端到端评测与 Codex 执行门

provider conformance 只证明某个模型在小型、受控 schema 提示下能返回合法 tool arguments；它不能证明该模型在完整 requirements、动态 operation contract、真实 CAD 结果和多轮状态机中能稳定完成零件。因此 v3 必须提供可由 Codex 非交互执行的真实评测入口，并将其作为完成该目标与发布的硬门。实现本目标的 Codex 必须实际运行它、读取失败工件与诊断、修复可修复的实现缺陷后重新运行；不得只运行 mock/unit tests 后声称目标完成。

必须新增命令：

cd backend
python -m app.cad_agent.evals.live --suite release --require-live

该命令默认从当前 Settings 取得已选择的 author provider/model 和独立 reviewer provider/model；允许以显式、非秘密的 provider/model ID 覆盖，便于逐个验证已配置模型。凭据只从现有配置来源读取，CLI 参数、输出、工件和日志绝不回显密钥。它必须经由生产 StructuredModelGateway、生产 CadRuntime、生产 ReviewGateway、v3 WorkflowCoordinator、SQLite repository 与 ArtifactStore adapter 运行，测试代码不得替换 LLM、CAD engine、reviewer、状态机或动态 schema validator 为 mock/fake。唯一允许的隔离是每次评测创建临时 v3 SQLite 数据库和独立 artifact root，绝不读取、修改或发布普通用户 task。

命令开始时先以实际 provider 请求执行选定模式的 conformance preflight；author 与 reviewer 均需成功。配置缺失、凭据无效、网络不可达、provider 限流、模型未通过 structured-output capability 或引擎不可用时，命令写出结构化 LIVE_EVAL_BLOCKED/对应 typed error 并以非零退出。--require-live 禁止任何 skip、离线 fallback、mock fallback 或把 WAITING_RETRY 记为通过。只有用户显式选择不执行 live eval 的开发场景才允许 --allow-skip；该模式产生 skipped，永远不满足本目标的完成或发布验收。

评测分层以控制成本但保留真实覆盖：

smoke：矩形底板和简单法兰各一次，用于 Codex 在完成高风险改动后快速验证真实 author/reviewer/engine 串联。
release：矩形底板、法兰、带肋和安装孔的支架、含 face/edge selector 的修饰特征；每个场景至少连续运行三次，以独立 task/run 执行。任务需求、units、验收 claims、最大 author/reviewer turn 数、最长 wall time、总 token/调用预算和期望终态作为版本化 fixture 保存在仓库。
新增或修改 operation contract、selector/reference policy、verifier 或动态 schema 时，release 还必须包含该 operation 的最小真实生成场景；不能只补 unit fixture。

每个 live run 的成功只取决于当前 revision 的可验证结果，不取决于 LLM 是否恰好选择某个预期 feature sequence。它必须：完成到 COMPLETED、通过全部 deterministic claims 和必要 visual review、生成可读取的 immutable artifacts；无 FAILED_INTERNAL、NO_PROGRESS_LIMIT、未终止 running、重复 revision、重复 complete/build invocation 或未分类异常；所有 state-changing LLM 输出均有 raw-arguments hash、canonical validation、head/contract/snapshot binding 的审计记录；任何格式拒绝均在候选创建前发生。reference happy-path fixture 的 schema/decision rejection 计数必须为零；若出现，即使系统后来恢复，也视为 live quality failure，Codex 必须报告字段级原因并调整 schema/context/contract 或模型 capability，而不能隐藏为普通重试。

每次运行写入 live-evals/<run_id>/report.json 和链接到隔离工件的 manifest。报告至少包含：git revision、protocol/contract/verifier 版本、author/reviewer provider+model ID、实际 structured-output mode、每场景和每重复的最终 lifecycle、typed failure、所有 invocation/candidate/revision IDs、每个 claim 结果、schema rejection/重试/rollback 计数、token usage/上下文字节/耗时、预算是否超限，以及脱敏后的 correlation ID。保存 JSON summary、ledger、CDSL、拓扑、rebuild/verifier evidence 和 reviewer verdict；禁止保存密钥、完整未脱敏 prompt、附件原文或 provider 响应中的敏感 metadata。

Codex 的最终交付必须在结果中逐项说明实际执行的 live command、author/reviewer model、通过/失败场景、可定位的 report/artifact 路径、token 用量与任何失败的根因。发生网络/凭据等外部阻塞时，Codex 必须明确报告 LIVE_EVAL_BLOCKED，而不是宣称真实模型质量已验证；这会阻止把本目标标记为完成。运行有成本，因此开发中先跑相关 smoke，但实现完成前必须运行一次无 skip 的完整 release suite。

7. Token 优化目标与实现规则

优化优先级是减少无效轮次，其次再压缩每轮上下文；不能通过删除必要的运行时合同或独立复核来换 token。

删除新任务的大型 modeling-plan.md、它的 parser、一次或多次计划 review 和重写循环。
requirements contract 由最多 8 项的结构化 batch 构成；requirements.md / completion.md 由服务端渲染，作者不再生成或重写 Markdown。复核通过后，建模循环不再重复发送 source-requirements.md，只发送冻结 contract 的紧凑摘要、requirement/claim ID 和未完成状态。最终复核仍发送 source，以防冻结 contract 遗漏源需求。
每轮作者上下文固定为：冻结 requirements、ID/coverage 摘要、当前模型紧凑测量、pending action 或最近动作摘要、最近一次相关错误、Runtime operation 名称。只在 LLM 调用 inspect_topology 后附带当前 selector token bank，只在调用 contract 后附带该 operation 的精确 schema。
一次 LLM 回合最多执行一个 tool call；每个候选只允许一个 feature。此约束已经存在，必须保留。
tool 结果按结构化摘要持久化，prompt 只保留最新且仍与当前 working_head 有关的内容；历史完整证据在工件/账本中按需读取。
batch_goal、plan step/action 文本和 author self_review 从反复 prompt/调用中删除，改为服务端引用 pending action。
记录每次 author/reviewer 调用的 provider usage.prompt_tokens、usage.completion_tokens（支持时）、序列化 context 字符数、工具名、重试原因和缓存命中。没有 usage 的 provider 使用 context 字符数作为次级指标，不伪造 token 数据。

验收指标以一组固定代表任务为准：矩形底板、简单法兰、带肋和安装孔的支架、含 selector 的修饰特征。与当前协议对比，目标是：

计划相关作者/审查调用降为零；
无失败的常规零件中，每一检查点只发生一次作者 fragment 调用和一次独立 candidate review；
无副作用格式错误不进入候选构建、不创建 revision；
因内部异常产生的重复完成调用为零；
总 author+plan-review prompt tokens 的中位数下降至少 30%，同时完成率、最终复核通过率和几何断言通过率不低于基线。

30% 是初始验收线，不是凭空承诺。实现前须在现有协议上记录相同任务集的实际 usage，实施后以同一模型、温度、运行时版本和需求文本复测。

8. 实现范围与顺序

P0：立即修复和回归（可直接实施）

保留已修复的 _final_review global_violations 初始化。
让未预期异常进入 FAILED_INTERNAL；不要走 _fragment_diagnostic 或增加 no_progress。
为 complete_task 加 revision-scoped idempotency，排除内部/基础设施错误对 NO_PROGRESS_LIMIT 的影响。
将 author transport fallback 改为有界状态机：每 provider 有限重试、最多一次 provider failover、全 run 总预算和指数退避；超限后进入 WAITING_RETRY，绝不保持 running 无限循环。
修复 modeling-plan revision-limit 的后检查控制流，直到 P2 完成前也不得出现“报上限后继续写计划”。
添加最小测试：最终审计全局不变量、内部错误只失败一次、同 revision 完成调用幂等、法兰四位置 hole_blind 单 feature 允许、贯穿孔拓扑断言。

P1：文档先复核后冻结（可直接实施，独立于 P2）

建立 v3 domain、application、ports、adapters 包边界与 composition root；先迁移 requirements draft/review 这条窄路径作为样板。新增代码不得继续写入 AutonomousCdslGenerationRunner，也不得让 domain import 当前 services/engine/storage。
在 backend/requirements.txt 显式加入并锁定兼容的 Pydantic v2 与 LangChain core / 已配置 provider integration 依赖；adapter 需要保留 raw_arguments_json（固定 schema 可使用 with_structured_output(..., include_raw=True) 或等价 raw tool-call 模式），不能只接收 LangChain 已解析的对象。依赖升级必须通过现有 API、timeout 和 usage 回归测试。
新增 Pydantic RequirementsDraftBatch、RequirementsPatchBatch、RequirementsReview 和空参数 finalize tool，由 cad_agent/adapters/structured_llm.py 的 LangChain adapter 调用，并在服务端原始 arguments 上二次验证。每 batch 最多 8 项，禁止 Markdown 写入工具。
在 TaskRepository 与 ArtifactStore adapter 增加 source index、requirements JSON draft、requirements contract、review 和 render API；不得覆盖冻结 contract 或由 Markdown 反向读入状态。
实现 verifier registry、每种 claim 的 expected dynamic oneOf schema、registry integrity check 和 requirements-contract.json renderer；缺少 verifier 的可测需求必须明确失败。
在 runner 中替换“首次写入即 freeze”为结构化草稿状态机；复核失败有明确修改次数，达到上限时 WAITING_FOR_USER，不能无限重试或静默降级。
冻结 contract 后一次性生成 requirements.md、completion.md 和 requirements-index.json。

P2：以单动作协议替换建模计划（主要改动）

实现第 6.6 节的 finite state machine、typed command/result、port interfaces、Unit of Work、invocation idempotency、candidate staging/immutable publish 和 transactional outbox；先通过 domain/handler 测试，再接入真实 LLM、runtime 与 UI adapter。
新增固定 Pydantic NextAction、GeometryConclusion、RollbackCheckpoint、CandidateReview、FinalReview；autonomous_tools() 仅暴露第 4.7 节列出的严格结构化工具，移除 write_modeling_plan、skip_satisfied_plan_step、自由 self_review 和 plan 专属字段。
将 _author_tools()、_prompt_messages()、_execute_tool() 拆为 context assembler、LLM turn coordinator 与独立 command handler；candidate metadata、coverage、repair 路径使用 pending action/ledger/claim result，不再读取或写入 modeling plan。handler 不得直接 import file/SQLite/provider/engine implementation。
将 profile_schema.json 中的 feature contract 升级为完整 versioned operation contract registry：author param JSON Schema、fragment shape、selector/reference policy、server injection、semantic-preflight 和 verifier binding 都由此处声明。删除 cdsl_authoring_schema.py、cdsl_fragment.py、autonomous_cdsl_generation.py 中按 operation 名称/前缀推断 params、selector 或默认 pattern source 的兜底规则。
submit_cdsl_fragment 从完整 feature_atomic_contract 生成并绑定动态 schema；不得用一个宽松通用模型容纳不同 operation 的 params、sketch、selector、reference 或注入字段。schema 必须使用当前 snapshot 的 token enum，而不是任意 string 后补检。
candidate/final 先执行 verifier registry，再调用结构化独立 review；ReviewGateway 接收 action card、claim IDs 和只读验证结果，而非 plan_step/plan_action。requirements review 是独立的 application command handler，不把它伪装成 completion Markdown review。
complete_task 无参数；最终完成门检查所有 claim、pending action、repair 与最终复核。
增加 provider/model conformance suite 和 model_capabilities 持久化；不通过时禁止启动。
设计并实现 SQLite 状态层、账本 append 和幂等事务；文件工件由独立 ArtifactStore adapter 管理。

P3：删除旧协议、API 和 UI

将任务 schema 直接升级为 3.0；不实现 2.0 迁移器、只读读取器或恢复逻辑。旧任务目录不由运行时扫描、打开或恢复，可在部署前由运维单独归档。
删除 AutonomousCdslGenerationRunner 的巨型实现及其 module-global helper 状态；入口仅负责 dependency composition 和发起 WorkflowCoordinator。旧 WorkspaceStore 不能继续同时是 repository、artifact store、task JSON writer 和状态机。
从 WorkspaceStore、runner、API、前端类型和测试中删除 modeling_plan_*、plan step/action、write_modeling_plan、skip_satisfied_plan_step 及其 Markdown parser/reviewer。新协议中不得保留隐藏 fallback、遗留 tool 参数或分支。
GET /v1/tasks/{id} 和前端 cad-types.ts 替换 modeling-plan 字段为 requirements contract/review、claim summary、pending action、action ledger summary 和 protocol version；不再有 completion Markdown review 字段。
agent_service.py、cad-stream.ts 删除“建模计划 / 计划独立复核 / 计划步骤已满足”事件，增加“需求合同独立复核 / 动作选择 / 候选独立复核 / 最终独立复核 / 动作账本”事件。
前端显示事实和状态，不能把 ledger 误显示为 LLM 的未来计划。

P4：验证与发布门

单元：所有固定 Pydantic model 的 valid/invalid fixtures、每个 Runtime operation 的动态 schema fixture、operation mismatch、stale head、selector ambiguity、single multi-position hole、through topology、每个 verifier、ledger/transaction/idempotency、typed errors。
架构：domain transition table 的全部合法/非法状态边、每个 command handler 的纯 result、port adapter conformance、dependency-rule test、SQLite CAS 冲突、staged artifact crash recovery、outbox 至少一次投递与消费者幂等；不得依赖端到端 LLM run 才发现状态机错误。
集成：每个配置 provider/model 的真实 conformance suite；实现过程中按第 6.7 节调用真实 LLM smoke，并在完成前由 Codex 实际执行 python -m app.cad_agent.evals.live --suite release --require-live。release 报告必须保存匿名化调用指标与工件路径；分别覆盖成功、格式拒绝、候选拒绝、verifier fail、review service 失败、内部异常。任何 LIVE_EVAL_BLOCKED、skip、预算超限或场景失败均阻止发布，不能以 mock/integration test 替代。
回归：全量 backend 测试、前端类型/stream 测试，以及不识别旧任务 schema 的拒绝测试。
发布：一次性切换到 v3；部署前停止旧 worker 并归档旧任务目录。上线后删除 v2 plan 生成路径、parser/reviewer 和全部关联测试，不保留 feature flag 双轨或历史工件读取能力。

9. 主要代码触点

位置	必须修改
`backend/app/services/autonomous_cdsl_generation.py`	删除巨型 runner 的业务实现；迁移期间只可作为入口 shim，v3 发布前移除，不能继续承载状态、CAD、LLM、文件和复核逻辑
`backend/app/cad_agent/domain/*.py`（新增）	不可变 task/action/revision value objects、workflow state/transition table、operation/claim policy、typed domain result/error；无任何 I/O import
`backend/app/cad_agent/application/*.py`（新增）	command schemas 到 domain command 的转换、command handlers、workflow coordinator、context assembler、Unit of Work 使用；不直接依赖 adapter 实现
`backend/app/cad_agent/application/llm_contracts.py`（新增）	Pydantic v2 固定 LLM input/output DTO；只负责 schema，不包含 persistence、Runtime 或 transition 规则
`backend/app/cad_agent/ports.py`（新增）	`TaskRepository`、`ArtifactStore`、`ModelGateway`、`CadRuntime`、`ReviewGateway`、`VerifierExecutor`、`EventPublisher` 等 Protocol 与 typed failure contract
`backend/app/cad_agent/adapters/*.py`（新增）	SQLite/file、CDSL engine、render/review、provider、outbox 的 port 实现；所有外部异常在此映射为 typed adapter error
`backend/app/cad_agent/adapters/structured_llm.py`（新增）	唯一 LangChain provider adapter；固定 Pydantic 和动态 JSON Schema 调用、原始 arguments 捕获、canonical 二次验证入口、provider capability mapping；不含 CAD 状态机
`backend/app/cad_agent/evals/live.py`、`backend/app/cad_agent/evals/fixtures/*.json`（新增）	非交互真实 provider/engine/reviewer release runner、版本化场景/预算/claim fixtures、隔离 SQLite/artifact root、脱敏 report/manifest；`--require-live` 时任何 skip 或 fake adapter 都必须失败
`backend/requirements.txt`（及实际使用的 lock file）	显式 Pydantic v2、LangChain core 和对应 provider integration 的兼容范围；不能依赖 FastAPI 间接安装的 Pydantic 版本
`backend/app/cad_agent/application/requirements_review.py`（新增）	结构化 requirements review command handler、coverage gate、draft patch feedback；不解析或写入 Markdown
`backend/app/cad_agent/domain/verifier_registry.py`（新增）	claim schema registry、contract integrity、针对 typed verification facts 的纯 deterministic evaluator；启动时拒绝不可用 verifier
`backend/app/services/cdsl_authoring_schema.py`、`backend/app/services/cdsl_fragment.py`、`backend/engine/cdsl_engine/profile_schema.json`	迁移为 `CadRuntime` adapter 的完整 versioned operation contract、dynamic fragment schema、selector/reference resolver、semantic preflight；删除按 atomic ID 的重复/开放式 author schema 和默认 source 注入
`backend/app/services/storage.py`	拆分为 SQLite `TaskRepository`/`UnitOfWork` adapter 与不可变 `ArtifactStore` adapter；加入 invocation、state version、candidate staging manifest、ledger index、outbox；删除 task.json 权威状态和 v2 兼容
`backend/app/services/visual_review.py`	迁移为 `ReviewGateway` adapter；action-based candidate/final review，不再承担 requirement 或 completion Markdown review
`backend/app/services/agent_service.py`	delivery/worker adapter，只启动 `WorkflowCoordinator`、记录 usage 并消费 typed result；不得重试内部失败为 author turn
`backend/app/settings.py`	protocol version、文档修订上限、action/context/usage 配置；删除 plan 配置
`backend/app/main.py`	API 输出 v3 文档审核和动作账本摘要
`frontend/src/lib/cad-types.ts`、`frontend/src/lib/cad-stream.ts`	新事件与字段，删除 plan 特有状态
`backend/tests/`、`frontend/src/lib/.test.ts`	删除 v2 plan 行为测试，新增 P0-P4 回归

10. 需要确认的架构决策

以下是本目标已作出的绑定选择，不留作实现期间临时决定：

采用 SQLite 作为 v3 可变状态的唯一权威来源。 当前 task.json/agent-state.json 的文件读写无法为 checkpoint、pending action、幂等调用和 ledger append 提供真正的原子事务。保留 JSONL 账本和文件工件，但它们不是可变状态源。代价是 WorkspaceStore 持久化层重构；这是达到可靠性目标的必要改动。
不兼容旧任务。 不应把已有 modeling-plan.md 任务转换为 pending action，因为无法无歧义地映射历史计划状态；v3 运行时只识别新协议工件。
建议把无法可靠消除的需求歧义显式置为 WAITING_FOR_USER。 对“简单法兰”一类可合理假设的请求，LLM 仍可写明假设并继续；只有冲突、关键基准/尺寸导致多种同等合理且会明显改变模型的情况才暂停。
采用第 6.6 节的六边形边界和显式状态机。 这不是可选重构或文件整理；不允许以“赶进度”为由把 Runtime/LLM/SQLite 直接重新接回 workflow handler。

11. 非功能验收

实现完成时必须能证明：

法兰任务不会因 global_violations、重复 complete_task 或 plan revision limit 失败；最终复核若故障，任务保留 rev_003 类的最后健康 checkpoint 和精确错误类别。
LLM 看到 requirements、coverage、当前模型和账本摘要后，自己提出“下一动作”；服务端日志可证明它没有自动替 LLM 推导该动作。
hole_blind 的四个同宿主位置作为一个 action/feature 通过，中心/螺栓通孔通过最终 topology 断言而非仅靠盲孔深度文字。
任意 action proposal 或 CDSL 格式错误均不产生 revision、不改变 active head、不消耗候选构建预算。
每个接受的 checkpoint 都能从 ledger 追到 author intent、真实 atomic/fragment hash、selector snapshot、独立复核和 coverage 证据。
静态 dependency-rule test 证明 domain 不导入 FastAPI、LangChain、SQLite、文件、engine、render 或 settings；application 不导入 adapter 实现。状态迁移只存在于 domain transition table/command handler，API、stream、adapter 和 reviewer 均不能直接写任务状态。
进程在 candidate build、artifact publish、SQLite commit、outbox dispatch 或 stream publish 的任一点终止后，恢复测试均证明：系统要么保留原 checkpoint，要么通过同一 invocation/manifest 完成一次提交；不会出现公开半工件、双 revision、重复 build 或丢失已提交 ledger event。
所有会改变状态、影响 CAD 执行或作为验收依据的 LLM 输出均对应第 4.7 节的一项 canonical schema，并在状态变更前通过 schema、state binding 和适用的 domain validator；不存在 Markdown/自由文本/开放 object 的旁路。
每个 Runtime operation 均通过完整 contract integrity、valid/invalid dynamic-schema fixture、selector/reference snapshot、semantic preflight 和 engine-execution 测试；缺少参数、无参数、草图、非草图、required/forbidden selector 和 nested option 的差异均由 schema 而非 prompt 表示。
task 开始前，选定 provider/model 在全部固定 schema 与每个已注册 dynamic operation schema 的真实 API conformance suite 中通过；未通过只报 MODEL_STRUCTURED_OUTPUT_UNSUPPORTED，不允许回退为自由文本。
实现目标的 Codex 已实际运行第 6.7 节的无 skip release 命令，使用当前配置的真实 author/reviewer 模型、真实 CAD engine 和 v3 状态机完成固定任务集三次重复；结果报告和工件 manifest 可定位，且没有 LIVE_EVAL_BLOCKED、失败场景、预算超限或隐藏的 schema/decision rejection。
发布前全部 deterministic claim 必须以当前 revision 的程序化 evidence pass；LLM review 只作为 visual/语义的独立补充，永远不能覆盖 fail 或 unavailable。
P4 固定任务集给出实施前后真实调用指标，满足第 7 节的可靠性及 token 目标。

70 KiB Raw Permalink Blame History Unescape Escape