Yuxi Spec Loop 工程闭环用八阶段流程把 Agent 变更收敛为可反证、可审查、可长期维护的仓库事实【免费下载链接】Yuxi可私有部署的多租户知识智能体平台统一 RAG、知识图谱、多智能体、MCP/Skills、沙盒与权限管理。Self-hosted knowledge agent platform for RAG, knowledge graphs and multi-agent workflows.项目地址: https://gitcode.com/GitHub_Trending/yu/Yuxi导读Yuxi 是一个可私有部署的多租户知识智能体平台围绕 RAG、知识图谱与多智能体工作流持续演进。随着仓库同时被人类开发者和 Agent 提交大量非平凡变更Yuxi 引入了一整套名为Yuxi Spec Loop的工程闭环决策记录见 docs/develop-guides/decisions/implemented/2026-08-16-yuxi-spec-loop.md完整流程见 docs/develop-guides/spec-loop.md把实现建议收敛为可以被反证、审查和长期维护的仓库事实。阅读本文后你将掌握非平凡/平凡变更如何分类、八阶段闭环每一步的具体要求、证据矩阵与结果词Passed/Inspected/Not run/Inferred的语义以及无密钥确定性 E2E 门禁与真实 Provider 探针如何互补工作。背景为什么 Yuxi 需要 Spec LoopYuxi 此前已经建立了语义 Ownersemantic Owner、decision lifecycle、测试分层、负向案例和独立 Review 约束但工程实践仍暴露出四个缺口决策滞后非平凡变更仍可能在实现之后才补写决定证据分散验收证据散落在散文叙述中难以被机械核对缺少稳定门禁高风险 assembled path真实装配路径缺少无密钥的 E2E 门禁收敛载体缺失简化simplification和高影响逃逸事故缺少可直接执行的收敛载体。单独存在的规则无法保证从问题到证据、从失败到学习形成闭环。为此Yuxi 以本决策记录类型processOwner 为 docs/develop-guides/spec-loop.md正式采用 Spec Loop 统一 Scope/classify、权威重建、Propose、assembled-path 实现、Verify、独立 Review、Converge 和 Learn 八个阶段。该决策不改变 AgentRun、lease、retry、manifest、attempt 或外部副作用的运行时语义相关演进由后续待办单独承接。适用范围与任务分类substantial 与 trivial 的判定开始任何工作时先把请求压缩为六要素可验证目标、非目标、显式假设、任务类型和风险层级。任务类型被固定为六种从源码中的 verifier 约束也可以看到这一枚举被机械强制见 scripts/verify_engineering_contracts.py任务类型含义feature新增能力bug-fix缺陷修复simplification简化/删除现有表面architecture架构演进process流程/工程规范演进testing测试与验证体系演进满足任一条件即为非平凡substantial改变持久状态或事务发布点改变权限、隔离、外部副作用或公开兼容改变 Run / worker / 队列 / 恢复等长生命周期改变模型可见输入引入抽象、依赖、配置、fallback、状态机或长期维护表面接受未来可能重开的非显然取舍。非平凡工作必须在实现前创建 trackedproposeddecision不允许先实现后补记。而局部文案、机械重命名和不改变行为的等价清理可视为 trivial小而完整、在同一变更中已经生效且没有待裁决替代方案或风险的修复可以直接写implemented但 PR 必须说明为什么不需要 proposal。是否 trivial 属于语义 Review 职责不得用 diff 大小、文件数量或静态 heuristic 代替判断——这正是本决策排除用 diff heuristic 自动判定 substantial/trivial方案的原因。八阶段闭环详解1. Scope / classify界定与分类先写solution-independent problem描述失败的外部结果、观察边界和约束不预设类名、表名或框架。明确 goal、non-goal、assumption、task class、受影响 Owner 与最低证据等级。这一步保证问题定义不被过早的解决方案细节污染。2. Reconstruct authority重建权威按固定优先级重建当前权威发现冲突时先确认哪个材料拥有当前事实根与子树AGENTS.md、ARCHITECTURE.md和安全不变量当前公开契约、真实 provider / registration / composition、持久化与用户入口可执行测试、workflow、构建产物和运行时探针active decisionhistory、archive、changelog 与docs/vibe/临时材料。关键纪律后序材料不能静默覆盖前序当前事实history 只解释来源不证明现在仍成立。3. Propose提案非平凡变更先在 docs/develop-guides/decisions/proposed/ 写问题、类型、Owner、真实替代、验收与证据矩阵和风险。提案不保存推理流水账也不成为运行时事实源。每条验收主张使用同一结构这也是 verifier 机械校验的固定表头见 scripts/verify_engineering_contracts.py验收主张失败面语义 Owner直接证据 / 命令负向案例当前结果用户可观察结果或工程不变量它可能怎样错误地通过最接近行为的代码、数据或契约可复现 oracle 与准确命令恢复目标缺陷后如何变红Passed/Inspected/Not run/Inferred结果词的含义固定Passed是命令实际成功且结果已核对Inspected是只读检查了事实Not run是未执行并说明原因/风险Inferred是根据间接证据推断。后三者都不能写成测试通过。4. Implement assembled path沿真实装配路径实现只实现验收所需的最小线性方案并沿真实装配路径追踪producer → registration → consumer → persistence/publication → user/model-visible result。同步更新真正拥有当前行为的文档、测试、fixture/snapshot/generated output 和 decision不得以孤立 helper、mock 调用次数或未被 shipping composition 使用的实现宣告完成。5. Verify验证先运行最小相关检查再按风险升级到真实 PostgreSQL、HTTP、worker、SSE、对象/文件、浏览器或外部 provider。每个新 guard 必须有能恢复目标缺陷的负向案例expected output 只能显式更新并 Review。完成结论需要回读数据库、文件、对象、DOM 或协议结果不能只看 Agent 自述、HTTP 200、日志关键词或 workflow 绿色状态。确定性 replay 与真实 provider probe 是互补证据前者适合 PR 阻断并证明 shipping composition后者校准外部漂移。缺少密钥或环境时写Not run不把 optional skip 计为产品通过。6. Independent review独立 Reviewcommit 前由不继承开发上下文的全新 Reviewer 读取完整需求、decision、完整 diff、实际测试结果和未验证范围。Reviewer 检查目标/非目标、Owner、oracle 独立性、负控、复杂度和当前文档但不能替代直接证据。本决策实施时全新上下文 Reviewer 审查了需求、完整 diff、测试和规范没有 P0/P1其 5 个 P2手工 probe 契约、replay 请求校验、失败清理、空/非法证据矩阵、decision Owner均已修复并由新增负控或 E2E 覆盖。7. Converge收敛证据一致后把 proposed 移到 docs/develop-guides/decisions/implemented/ 并改写为现在时的问题、决定、替代、后果和验证拒绝则进入rejected/。部分取代用新旧记录交叉链接失去当前价值才归档。docs/vibe/继续只做本地临时计划不迁移旧计划冒充组织记忆。8. Learn学习达到 postmortem 门槛 的高影响逃逸缺陷必须留下 reproducer、因果链、安全网漏过原因和更早的拒绝机制。普通缺陷仍需要风险相称的回归测试但不制造事故文档。PR 模板分层严格模板与简化模板Agent 创建 PR 时使用默认严格模板人工或其他非 Agent 提交可以显式选择简化模板只保留变更、验证、风险和关联事项。Proposed decision 和 PR 使用同一组验收字段——验收主张、失败面、语义 Owner、直接 oracle/命令、负向案例和结果——决策记录以证据矩阵表呈现PR 模板以逐条分组呈现。Verifier 只检查确定性结构、结果词、Owner 和 workflow 接线不代替语义 Review。模板分层不免除非 trivial / 高风险变更在贡献指南中的 decision、直接证据和未验证范围要求。无密钥 E2E 门禁与真实 Provider 探针Deterministic replay低噪声的 PR 阻断门禁.github/workflows/system-tests.yml 在相关 PR 上运行无外部密钥的 OpenAI-compatible deterministic replay拉起postgres redis minio sandbox-provisioner api worker的 focused topology先等待真实的/api/system/ready再初始化隔离 E2E 管理员然后启动 backend/test/support/openai_replay_server.py 作为确定性 OpenAI-compatible 服务最终运行test/e2e/test_deterministic_agent_path_e2e.py。该 E2Ebackend/test/e2e/test_deterministic_agent_path_e2e.py真实经过 Compose API、worker、SSE 和PostgreSQL 因果回读——断言同一 Run 的 output 被持久化回读EXPECTED_OUTPUT DETERMINISTIC_AGENT_E2E_OK而不是只看 HTTP 200。它还包含请求契约负控replay 拒绝invalid_authorization、invalid_model、stream_required等不合规请求以及test_replay_rejects_requests_outside_deterministic_contract这类保证 replay 服务自身不被滥用的测试。system-tests.yml 还按路径过滤只在匹配高风险范围backend/package/yuxi、backend/server、docker、integration/e2e 测试等时运行并验证 worker 健康 lease 是过期即失效的运行时事实暂停 worker 后 readiness 必须返回 503。Real provider probe人工校准外部漂移.github/workflows/real-provider-probe.yml 由workflow_dispatch手工触发使用仓库 secretSILICONFLOW_API_KEY运行test/e2e/test_agent_async_e2e.py校准真实 provider。缺少 secret 时 workflow 在第一步就明确失败并输出可诊断的错误信息未执行时在决策验证矩阵中记录Not run。两者互相不能冒充replay 证明 shipping composition 却无法证明外部 provider 自然语言行为真实探针校准外部漂移却不够低噪声、不能成为每 PR 阻塞 gate。Simplification / deletion 闭环simplification不是添加另一套更抽象的实现。决策必须真实比较keep、narrow、replace、remove并回答删除会破坏哪个当前 consumer 或承诺。删除验收至少检查runtime consumer、provider registration、export/import 与调用入口配置、环境变量、manifest、generated catalog 和 capability discoverydurable/wire schema、migration、兼容承诺和部署脚本tests、fixture/snapshot、示例、正式文档和依赖声明。提案的验收矩阵必须包含旧能力不存在的负向搜索并明确重新引入条件verifier 对 simplification 记录强制这两个标签见 scripts/verify_engineering_contracts.py。若以依赖为简化理由结果必须净删除 Yuxi 自有实现或维护表面若依赖实际新增能力应改为独立feature决策。公开 API、持久数据、部署脚本和真实用户都算 consumer不能因代码搜索为空就假设可删除。Verifier 派生契约让规范成为可机械检查的事实决策与流程并不停留在文档层面而是被 scripts/verify_engineering_contracts.py 固化为可执行契约其负向测试见 scripts/test_verify_engineering_contracts.pyDecision lifecycle文件名必须符合YYYY-MM-DD-topic.md状态必须与目录匹配类型必须属于六种枚举implemented/archived禁止保留提案/进度标题proposed 的验收标准必须包含六列证据矩阵表头且每行六列全部填写、结果词合法Simplificationproposed 与 implemented 记录必须同时含旧能力不存在与重新引入条件Postmortem 模板docs/develop-guides/postmortems/TEMPLATE.md 必须包含影响、事实时间线、因果链、安全网为何漏过、修正与验证、防复发措施、未解决风险七节Workflow 接线从 workflow 文件真实解析runstep检查契约命令必须存在且是阻塞 step禁止吞错命令trust.yml必须监听 pull_request 且不得使用 path filter阻断 workflow 不得用paths-ignore隐藏变更path filter 必须覆盖 owning scope架构边界router 不得拥有 SQLAlchemy query builder 或直接执行持久化操作web/src/apis之外不得出现/api路径字面量普通 Service/Repository 不得取得 UserWorkspace 宿主 PathAGENTS 指令分层 AGENTS 文件必须单一 H1、链接全部有效、不超字符预算文档散文正式文档禁止对举式否定不是…而是…式表述被 docs 规范 视为低信息密度表达。.github/workflows/trust.yml 在每个 PR 无条件运行python3 scripts/verify_engineering_contracts.py与python3 -m unittest scripts.test_verify_engineering_contracts并额外验证依赖更新策略、版本同步与 release workflow 边界。此外可临时输出审计投影python3 scripts/verify_engineering_contracts.py --report——该输出由仓库事实重新生成不提交、不手工编辑删除投影后应从同一代码、测试、decision 和 workflow 得到相同结果。Verifier 只证明引用、接线和部分边界检查真实存在不判断目标是否值得、断言是否正确、oracle 是否真正独立、远端是否把检查设为 required这些语义仍由 Reviewer 结合真实系统证据裁决。各材料职责与证据等级材料职责工程信任系统定义 Owner、oracle、gate 与证据等级测试规范拥有测试分层和运行命令工程决策记录保存问题、决定、替代、后果与验证事故复盘只保存达到门槛的逃逸事故及其防复发机制PR 描述记录本次变更实际执行的命令、结果、Reviewer 结论与未验证范围证据等级从低到高Unit纯逻辑、边界值、状态转换→ Integration真实 API、认证、事务、锁和服务副作用→ E2ECompose 中的 shipping entry、worker、SSE、文件/对象和最终业务结果→ Deterministic replay不依赖真实 provider 的 assembled-path 回归→ Real probe外部模型/浏览器/部署实例的现实校准→ Semantic Review目标、取舍、oracle 独立性和 expected-output 语义。每个 guard 都要证明目标缺陷会让它变红随机/并发测试失败必须保留可重放输入、seed 或数据库事实不能用重试掩盖。替代方案与选择理由本决策评估并拒绝了四个替代方案复制 ds-spec-loop 的.agents/notes与现有 decision lifecycle 重复形成第二套组织记忆建立中央 claim/risk registry复制代码、数据约束、测试和 workflow 已拥有的事实产生可独立漂移的第二真相verifier 甚至将这类中央清单路径列入FORBIDDEN_CENTRAL_INVENTORIES直接禁止只扩充文档、不接 gate 与真实 E2E无法给违规产生稳定后果用 diff heuristic 自动判定 substantial/trivial无法可靠判断语义风险保留为 Reviewer 责任。实施验证证据矩阵实录本决策记录的验证矩阵原文完整继承如下验收主张直接证据结果Decision 类型、证据矩阵、simplification、postmortem 与 workflow 漂移会被拒绝python3 scripts/verify_engineering_contracts.pypython3 -m unittest scripts.test_verify_engineering_contractsPassed5 workflows48 tests无密钥 Agent 主链路经过 API、worker、SSE 并回读同一 Run 的 PostgreSQL outputdocker compose exec -T api uv run --no-sync --no-dev pytest test/e2e/test_deterministic_agent_path_e2e.py -qPassed2 tests新增 E2E/replay Python 代码满足静态检查docker compose exec -T api uv run ruff check test/e2e/test_deterministic_agent_path_e2e.py test/support/openai_replay_server.pyPassed正式文档与导航可构建cd docs pnpm run buildPassed仅有既有 Rolldown、env lexer 与 chunk warningsWorkflow YAML 可解析Ruby stdlib YAML 逐文件读取.github/workflows/*.ymlPassedactionlintNot run本机未安装全量 backend unit inventorydocker compose exec -T api uv run --group test pytest test/unit -m not slowNot run收集 1279 项后约 14% 时进程 exit 137不能给出全套结论真实 SiliconFlow shipping probeGitHub ActionsReal Provider Agent ProbeNot run本地不使用仓库 secretworkflow 接线与凭证负控已 Inspected这张矩阵本身就是证据纪律的示范如实记录Not run及其原因本机未安装 actionlint、unit 全量因 OOM exit 137、本地不使用仓库 secret而不是把未执行的检查伪装成通过。同时它印证了决策的后果描述——非平凡工作增加了一个实现前决策点和逐主张证据记录但小而完整、没有待裁决替代或风险的同变更修复仍可解释后直接 implementedDeterministic replay 提供低噪声 PR 阻断却不证明外部 provider 自然语言行为。总结Yuxi Spec Loop 的价值在于它不引入任何平行的第二套真相没有中央 claim registry、没有手工状态清单、没有平行 notes而是把验收主张闭合在离行为最近的语义 Owner 处用证据矩阵统一决策记录与 PR 模板用verify_engineering_contracts.py把决策类型、证据矩阵、simplification 标签、postmortem 模板与 workflow 接线固化为每 PR 无条件运行的派生契约用无密钥 deterministic replay 提供低噪声 assembled-path 门禁再用真实 provider 探针校准外部漂移。业务语义始终由最接近风险的代码、数据库、协议结果和 Reviewer 拥有——规则保证的是从问题到证据、从失败到学习的闭环能够机械可查、持续生效。【免费下载链接】Yuxi可私有部署的多租户知识智能体平台统一 RAG、知识图谱、多智能体、MCP/Skills、沙盒与权限管理。Self-hosted knowledge agent platform for RAG, knowledge graphs and multi-agent workflows.项目地址: https://gitcode.com/GitHub_Trending/yu/Yuxi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Yuxi Spec Loop 工程闭环：用八阶段流程把 Agent 变更收敛为可反证、可审查、可长期维护的仓库事实
Yuxi Spec Loop 工程闭环用八阶段流程把 Agent 变更收敛为可反证、可审查、可长期维护的仓库事实【免费下载链接】Yuxi可私有部署的多租户知识智能体平台统一 RAG、知识图谱、多智能体、MCP/Skills、沙盒与权限管理。Self-hosted knowledge agent platform for RAG, knowledge graphs and multi-agent workflows.项目地址: https://gitcode.com/GitHub_Trending/yu/Yuxi导读Yuxi 是一个可私有部署的多租户知识智能体平台围绕 RAG、知识图谱与多智能体工作流持续演进。随着仓库同时被人类开发者和 Agent 提交大量非平凡变更Yuxi 引入了一整套名为Yuxi Spec Loop的工程闭环决策记录见 docs/develop-guides/decisions/implemented/2026-08-16-yuxi-spec-loop.md完整流程见 docs/develop-guides/spec-loop.md把实现建议收敛为可以被反证、审查和长期维护的仓库事实。阅读本文后你将掌握非平凡/平凡变更如何分类、八阶段闭环每一步的具体要求、证据矩阵与结果词Passed/Inspected/Not run/Inferred的语义以及无密钥确定性 E2E 门禁与真实 Provider 探针如何互补工作。背景为什么 Yuxi 需要 Spec LoopYuxi 此前已经建立了语义 Ownersemantic Owner、decision lifecycle、测试分层、负向案例和独立 Review 约束但工程实践仍暴露出四个缺口决策滞后非平凡变更仍可能在实现之后才补写决定证据分散验收证据散落在散文叙述中难以被机械核对缺少稳定门禁高风险 assembled path真实装配路径缺少无密钥的 E2E 门禁收敛载体缺失简化simplification和高影响逃逸事故缺少可直接执行的收敛载体。单独存在的规则无法保证从问题到证据、从失败到学习形成闭环。为此Yuxi 以本决策记录类型processOwner 为 docs/develop-guides/spec-loop.md正式采用 Spec Loop 统一 Scope/classify、权威重建、Propose、assembled-path 实现、Verify、独立 Review、Converge 和 Learn 八个阶段。该决策不改变 AgentRun、lease、retry、manifest、attempt 或外部副作用的运行时语义相关演进由后续待办单独承接。适用范围与任务分类substantial 与 trivial 的判定开始任何工作时先把请求压缩为六要素可验证目标、非目标、显式假设、任务类型和风险层级。任务类型被固定为六种从源码中的 verifier 约束也可以看到这一枚举被机械强制见 scripts/verify_engineering_contracts.py任务类型含义feature新增能力bug-fix缺陷修复simplification简化/删除现有表面architecture架构演进process流程/工程规范演进testing测试与验证体系演进满足任一条件即为非平凡substantial改变持久状态或事务发布点改变权限、隔离、外部副作用或公开兼容改变 Run / worker / 队列 / 恢复等长生命周期改变模型可见输入引入抽象、依赖、配置、fallback、状态机或长期维护表面接受未来可能重开的非显然取舍。非平凡工作必须在实现前创建 trackedproposeddecision不允许先实现后补记。而局部文案、机械重命名和不改变行为的等价清理可视为 trivial小而完整、在同一变更中已经生效且没有待裁决替代方案或风险的修复可以直接写implemented但 PR 必须说明为什么不需要 proposal。是否 trivial 属于语义 Review 职责不得用 diff 大小、文件数量或静态 heuristic 代替判断——这正是本决策排除用 diff heuristic 自动判定 substantial/trivial方案的原因。八阶段闭环详解1. Scope / classify界定与分类先写solution-independent problem描述失败的外部结果、观察边界和约束不预设类名、表名或框架。明确 goal、non-goal、assumption、task class、受影响 Owner 与最低证据等级。这一步保证问题定义不被过早的解决方案细节污染。2. Reconstruct authority重建权威按固定优先级重建当前权威发现冲突时先确认哪个材料拥有当前事实根与子树AGENTS.md、ARCHITECTURE.md和安全不变量当前公开契约、真实 provider / registration / composition、持久化与用户入口可执行测试、workflow、构建产物和运行时探针active decisionhistory、archive、changelog 与docs/vibe/临时材料。关键纪律后序材料不能静默覆盖前序当前事实history 只解释来源不证明现在仍成立。3. Propose提案非平凡变更先在 docs/develop-guides/decisions/proposed/ 写问题、类型、Owner、真实替代、验收与证据矩阵和风险。提案不保存推理流水账也不成为运行时事实源。每条验收主张使用同一结构这也是 verifier 机械校验的固定表头见 scripts/verify_engineering_contracts.py验收主张失败面语义 Owner直接证据 / 命令负向案例当前结果用户可观察结果或工程不变量它可能怎样错误地通过最接近行为的代码、数据或契约可复现 oracle 与准确命令恢复目标缺陷后如何变红Passed/Inspected/Not run/Inferred结果词的含义固定Passed是命令实际成功且结果已核对Inspected是只读检查了事实Not run是未执行并说明原因/风险Inferred是根据间接证据推断。后三者都不能写成测试通过。4. Implement assembled path沿真实装配路径实现只实现验收所需的最小线性方案并沿真实装配路径追踪producer → registration → consumer → persistence/publication → user/model-visible result。同步更新真正拥有当前行为的文档、测试、fixture/snapshot/generated output 和 decision不得以孤立 helper、mock 调用次数或未被 shipping composition 使用的实现宣告完成。5. Verify验证先运行最小相关检查再按风险升级到真实 PostgreSQL、HTTP、worker、SSE、对象/文件、浏览器或外部 provider。每个新 guard 必须有能恢复目标缺陷的负向案例expected output 只能显式更新并 Review。完成结论需要回读数据库、文件、对象、DOM 或协议结果不能只看 Agent 自述、HTTP 200、日志关键词或 workflow 绿色状态。确定性 replay 与真实 provider probe 是互补证据前者适合 PR 阻断并证明 shipping composition后者校准外部漂移。缺少密钥或环境时写Not run不把 optional skip 计为产品通过。6. Independent review独立 Reviewcommit 前由不继承开发上下文的全新 Reviewer 读取完整需求、decision、完整 diff、实际测试结果和未验证范围。Reviewer 检查目标/非目标、Owner、oracle 独立性、负控、复杂度和当前文档但不能替代直接证据。本决策实施时全新上下文 Reviewer 审查了需求、完整 diff、测试和规范没有 P0/P1其 5 个 P2手工 probe 契约、replay 请求校验、失败清理、空/非法证据矩阵、decision Owner均已修复并由新增负控或 E2E 覆盖。7. Converge收敛证据一致后把 proposed 移到 docs/develop-guides/decisions/implemented/ 并改写为现在时的问题、决定、替代、后果和验证拒绝则进入rejected/。部分取代用新旧记录交叉链接失去当前价值才归档。docs/vibe/继续只做本地临时计划不迁移旧计划冒充组织记忆。8. Learn学习达到 postmortem 门槛 的高影响逃逸缺陷必须留下 reproducer、因果链、安全网漏过原因和更早的拒绝机制。普通缺陷仍需要风险相称的回归测试但不制造事故文档。PR 模板分层严格模板与简化模板Agent 创建 PR 时使用默认严格模板人工或其他非 Agent 提交可以显式选择简化模板只保留变更、验证、风险和关联事项。Proposed decision 和 PR 使用同一组验收字段——验收主张、失败面、语义 Owner、直接 oracle/命令、负向案例和结果——决策记录以证据矩阵表呈现PR 模板以逐条分组呈现。Verifier 只检查确定性结构、结果词、Owner 和 workflow 接线不代替语义 Review。模板分层不免除非 trivial / 高风险变更在贡献指南中的 decision、直接证据和未验证范围要求。无密钥 E2E 门禁与真实 Provider 探针Deterministic replay低噪声的 PR 阻断门禁.github/workflows/system-tests.yml 在相关 PR 上运行无外部密钥的 OpenAI-compatible deterministic replay拉起postgres redis minio sandbox-provisioner api worker的 focused topology先等待真实的/api/system/ready再初始化隔离 E2E 管理员然后启动 backend/test/support/openai_replay_server.py 作为确定性 OpenAI-compatible 服务最终运行test/e2e/test_deterministic_agent_path_e2e.py。该 E2Ebackend/test/e2e/test_deterministic_agent_path_e2e.py真实经过 Compose API、worker、SSE 和PostgreSQL 因果回读——断言同一 Run 的 output 被持久化回读EXPECTED_OUTPUT DETERMINISTIC_AGENT_E2E_OK而不是只看 HTTP 200。它还包含请求契约负控replay 拒绝invalid_authorization、invalid_model、stream_required等不合规请求以及test_replay_rejects_requests_outside_deterministic_contract这类保证 replay 服务自身不被滥用的测试。system-tests.yml 还按路径过滤只在匹配高风险范围backend/package/yuxi、backend/server、docker、integration/e2e 测试等时运行并验证 worker 健康 lease 是过期即失效的运行时事实暂停 worker 后 readiness 必须返回 503。Real provider probe人工校准外部漂移.github/workflows/real-provider-probe.yml 由workflow_dispatch手工触发使用仓库 secretSILICONFLOW_API_KEY运行test/e2e/test_agent_async_e2e.py校准真实 provider。缺少 secret 时 workflow 在第一步就明确失败并输出可诊断的错误信息未执行时在决策验证矩阵中记录Not run。两者互相不能冒充replay 证明 shipping composition 却无法证明外部 provider 自然语言行为真实探针校准外部漂移却不够低噪声、不能成为每 PR 阻塞 gate。Simplification / deletion 闭环simplification不是添加另一套更抽象的实现。决策必须真实比较keep、narrow、replace、remove并回答删除会破坏哪个当前 consumer 或承诺。删除验收至少检查runtime consumer、provider registration、export/import 与调用入口配置、环境变量、manifest、generated catalog 和 capability discoverydurable/wire schema、migration、兼容承诺和部署脚本tests、fixture/snapshot、示例、正式文档和依赖声明。提案的验收矩阵必须包含旧能力不存在的负向搜索并明确重新引入条件verifier 对 simplification 记录强制这两个标签见 scripts/verify_engineering_contracts.py。若以依赖为简化理由结果必须净删除 Yuxi 自有实现或维护表面若依赖实际新增能力应改为独立feature决策。公开 API、持久数据、部署脚本和真实用户都算 consumer不能因代码搜索为空就假设可删除。Verifier 派生契约让规范成为可机械检查的事实决策与流程并不停留在文档层面而是被 scripts/verify_engineering_contracts.py 固化为可执行契约其负向测试见 scripts/test_verify_engineering_contracts.pyDecision lifecycle文件名必须符合YYYY-MM-DD-topic.md状态必须与目录匹配类型必须属于六种枚举implemented/archived禁止保留提案/进度标题proposed 的验收标准必须包含六列证据矩阵表头且每行六列全部填写、结果词合法Simplificationproposed 与 implemented 记录必须同时含旧能力不存在与重新引入条件Postmortem 模板docs/develop-guides/postmortems/TEMPLATE.md 必须包含影响、事实时间线、因果链、安全网为何漏过、修正与验证、防复发措施、未解决风险七节Workflow 接线从 workflow 文件真实解析runstep检查契约命令必须存在且是阻塞 step禁止吞错命令trust.yml必须监听 pull_request 且不得使用 path filter阻断 workflow 不得用paths-ignore隐藏变更path filter 必须覆盖 owning scope架构边界router 不得拥有 SQLAlchemy query builder 或直接执行持久化操作web/src/apis之外不得出现/api路径字面量普通 Service/Repository 不得取得 UserWorkspace 宿主 PathAGENTS 指令分层 AGENTS 文件必须单一 H1、链接全部有效、不超字符预算文档散文正式文档禁止对举式否定不是…而是…式表述被 docs 规范 视为低信息密度表达。.github/workflows/trust.yml 在每个 PR 无条件运行python3 scripts/verify_engineering_contracts.py与python3 -m unittest scripts.test_verify_engineering_contracts并额外验证依赖更新策略、版本同步与 release workflow 边界。此外可临时输出审计投影python3 scripts/verify_engineering_contracts.py --report——该输出由仓库事实重新生成不提交、不手工编辑删除投影后应从同一代码、测试、decision 和 workflow 得到相同结果。Verifier 只证明引用、接线和部分边界检查真实存在不判断目标是否值得、断言是否正确、oracle 是否真正独立、远端是否把检查设为 required这些语义仍由 Reviewer 结合真实系统证据裁决。各材料职责与证据等级材料职责工程信任系统定义 Owner、oracle、gate 与证据等级测试规范拥有测试分层和运行命令工程决策记录保存问题、决定、替代、后果与验证事故复盘只保存达到门槛的逃逸事故及其防复发机制PR 描述记录本次变更实际执行的命令、结果、Reviewer 结论与未验证范围证据等级从低到高Unit纯逻辑、边界值、状态转换→ Integration真实 API、认证、事务、锁和服务副作用→ E2ECompose 中的 shipping entry、worker、SSE、文件/对象和最终业务结果→ Deterministic replay不依赖真实 provider 的 assembled-path 回归→ Real probe外部模型/浏览器/部署实例的现实校准→ Semantic Review目标、取舍、oracle 独立性和 expected-output 语义。每个 guard 都要证明目标缺陷会让它变红随机/并发测试失败必须保留可重放输入、seed 或数据库事实不能用重试掩盖。替代方案与选择理由本决策评估并拒绝了四个替代方案复制 ds-spec-loop 的.agents/notes与现有 decision lifecycle 重复形成第二套组织记忆建立中央 claim/risk registry复制代码、数据约束、测试和 workflow 已拥有的事实产生可独立漂移的第二真相verifier 甚至将这类中央清单路径列入FORBIDDEN_CENTRAL_INVENTORIES直接禁止只扩充文档、不接 gate 与真实 E2E无法给违规产生稳定后果用 diff heuristic 自动判定 substantial/trivial无法可靠判断语义风险保留为 Reviewer 责任。实施验证证据矩阵实录本决策记录的验证矩阵原文完整继承如下验收主张直接证据结果Decision 类型、证据矩阵、simplification、postmortem 与 workflow 漂移会被拒绝python3 scripts/verify_engineering_contracts.pypython3 -m unittest scripts.test_verify_engineering_contractsPassed5 workflows48 tests无密钥 Agent 主链路经过 API、worker、SSE 并回读同一 Run 的 PostgreSQL outputdocker compose exec -T api uv run --no-sync --no-dev pytest test/e2e/test_deterministic_agent_path_e2e.py -qPassed2 tests新增 E2E/replay Python 代码满足静态检查docker compose exec -T api uv run ruff check test/e2e/test_deterministic_agent_path_e2e.py test/support/openai_replay_server.pyPassed正式文档与导航可构建cd docs pnpm run buildPassed仅有既有 Rolldown、env lexer 与 chunk warningsWorkflow YAML 可解析Ruby stdlib YAML 逐文件读取.github/workflows/*.ymlPassedactionlintNot run本机未安装全量 backend unit inventorydocker compose exec -T api uv run --group test pytest test/unit -m not slowNot run收集 1279 项后约 14% 时进程 exit 137不能给出全套结论真实 SiliconFlow shipping probeGitHub ActionsReal Provider Agent ProbeNot run本地不使用仓库 secretworkflow 接线与凭证负控已 Inspected这张矩阵本身就是证据纪律的示范如实记录Not run及其原因本机未安装 actionlint、unit 全量因 OOM exit 137、本地不使用仓库 secret而不是把未执行的检查伪装成通过。同时它印证了决策的后果描述——非平凡工作增加了一个实现前决策点和逐主张证据记录但小而完整、没有待裁决替代或风险的同变更修复仍可解释后直接 implementedDeterministic replay 提供低噪声 PR 阻断却不证明外部 provider 自然语言行为。总结Yuxi Spec Loop 的价值在于它不引入任何平行的第二套真相没有中央 claim registry、没有手工状态清单、没有平行 notes而是把验收主张闭合在离行为最近的语义 Owner 处用证据矩阵统一决策记录与 PR 模板用verify_engineering_contracts.py把决策类型、证据矩阵、simplification 标签、postmortem 模板与 workflow 接线固化为每 PR 无条件运行的派生契约用无密钥 deterministic replay 提供低噪声 assembled-path 门禁再用真实 provider 探针校准外部漂移。业务语义始终由最接近风险的代码、数据库、协议结果和 Reviewer 拥有——规则保证的是从问题到证据、从失败到学习的闭环能够机械可查、持续生效。【免费下载链接】Yuxi可私有部署的多租户知识智能体平台统一 RAG、知识图谱、多智能体、MCP/Skills、沙盒与权限管理。Self-hosted knowledge agent platform for RAG, knowledge graphs and multi-agent workflows.项目地址: https://gitcode.com/GitHub_Trending/yu/Yuxi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考