企业官网建设流程全解析

Yuxi 工程信任系统：以语义 Owner 为权威的可验证完成证据体系

【免费下载链接】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 自研的"工程信任系统"（Engineering Trust System）：一套把 Agent 或开发者提交的实现视为"待证伪候选"，用语义 Owner、独立 oracle、只读 gate 与可问责语义 Review 共同证明"完成"的方法论与落地工具。读完本文，你将掌握 Yuxi 如何用scripts/verify_engineering_contracts.py从仓库事实派生审计投影、如何按证据等级设计门禁、如何管理决策记忆与事故复盘，并可直接把同一套"主张在语义 Owner 处闭合"的机制应用到自己的仓库治理中。

完成证据的底线：自述、测试数量与演示都不能单独构成完成

Yuxi 工程信任系统的出发点是一个严格判定：提交者自述、测试数量和一次手工演示不能单独形成完成证据。仓库把 Agent 或开发者提交的实现视为"待证伪候选"（falsifiable candidate），其完成状态必须同时满足四类证明：

• 明确的Owner：谁拥有这一行为的事实；
• 真实系统事实：状态、副作用、持久化与发布边界实际存在；
• 与风险匹配的oracle：与实现失败方式不同、且能独立判定的验证手段；
• 只读gate与可问责的语义 Review：门禁只验证不修改，Review 对取舍负责。

从请求、提案、实现、证据到收敛的日常顺序由 Yuxi Spec Loop 维护；工程信任系统本身只拥有信任闭环与证据等级的定义，不重复 Spec Loop 的阶段流程。

权威模型：主张在语义 Owner 处闭合

Yuxi不维护可独立编辑的中央 risk/claim inventory，也不要求 claim ID。原因很直接：中央清单会复制源码、数据约束、测试和 workflow 已经拥有的事实，最终形成一份需要人工同步的"第二真相"（second source of truth），人一懒就漂移，漂移就没人发现。

取而代之的是：一个重要工程主张由最接近行为的语义 Owner 拥有，并在该 Owner 周围形成可追踪闭环。每个闭环部分都有明确的当前权威：

这些材料可以分布在各自正确的位置（源码、测试、workflow、决策记录），但必须能从一次变更追踪到同一个行为。当一次变更触及持久状态、信任边界、长生命周期、权限、公开兼容或模型体验时，PR 必须直接用自然语言列出：受影响主张及其 Owner、观察边界、oracle、负向案例和未验证范围——不得用"中央登记已完成"来替代真实闭环。

这一决策在仓库中有明确记录：决策 2026-08-16-agent-first-engineering-trust.md 记载，维护中央engineering-claims.json主张清单的替代方案已被拒绝，原因是它会复制 Owner 已拥有的事实并形成第二真相；而 verifier 的源码中FORBIDDEN_CENTRAL_INVENTORIES = (Path("docs/develop-guides/engineering-claims.json"),)（见 scripts/verify_engineering_contracts.py）直接把这类文件判为禁止项。

派生审计投影：verifier 从仓库事实重新生成审计视图

信任系统提供一条命令，从当前 Owner-local 材料生成审计投影（audit projection）：

python3 scripts/verify_engineering_contracts.py --report

投影是一个 JSON 视图，涵盖五类检查（源码位于 scripts/verify_engineering_contracts.py）：

1. decision lifecycle：proposed/implemented/rejected/archived四类记录的文件名、状态、类型、Owner 与必需章节；
2. workflow 接线：每个 workflow 契约必须存在真实、阻断、不吞错的runstep，且 PR path filter 覆盖 owning scope；
3. 路径覆盖与链接完整性：分层 AGENTS 指令文件的链接、单一 H1 与字符预算；
4. 分层 AGENTS 指令：链接/标题/预算检查；
5. 可机械判断的架构边界：router 不得直接执行持久化、web/src/apis之外不得出现/api路径、普通 Service/Repository 不得取得 UserWorkspace 宿主路径、正式文档禁止对举式否定。

投影的定位有三个关键约束：

• 由仓库事实重新生成，不提交、不手工编辑，也不反向定义事实；
• 删除投影后，从同一代码、测试、decision 和 workflow 应得到相同结果（可重复派生）；
• Verifier 只证明引用、接线和部分边界检查真实存在；router/web 边界检查只覆盖静态可判部分，service 层事务、锁与 lease 语义仍由真实 PostgreSQL integration 证明。

它不判断：目标是否值得做、测试断言是否正确、oracle 是否真正独立、远端是否把检查设为 required、某个 diff 是否被错误归类为 trivial。这些语义仍由 Reviewer 结合真实系统证据裁决。

证据等级：每层证据证明什么、不能替代什么

信任系统定义六层证据，每一层都有明确的"证明什么"与"不能替代什么"：

配套的纪律是：每个 guard 都要证明目标缺陷会让它变红——也就是说，门禁的负向能力必须可验证，而不是"看起来会失败"。Snapshot、fixture 和 expected output 只能显式更新，CI 只读验证；随机/并发测试失败必须保留可重放输入、seed 或数据库事实，不能用重试掩盖。

决策记忆：decisions 目录是 why 的仓库

decisions/ 目录保存代码和当前文档无法表达的内容：问题、why、替代方案、代价与验证。它不保存 Agent 推理流水账、Review 过程或迁移 checklist。生命周期语义清晰：

• implemented/：当前决定，使用现在时，只保留问题、决策、替代方案、后果、验证；
• proposed/与rejected/：不构成运行时权威；
• archived/：冻结历史，不能修改，也不作为当前权威。

记录格式有机械约束（verifier 会强制）：文件名必须匹配YYYY-MM-DD-topic.md；状态必须与所在 lifecycle 目录一致；类型只能取feature/bug-fix/simplification/architecture/process/testing；Owner必须指向仓库内真实存在的文件。implemented与archived记录禁止保留"提案/实施步骤/迁移步骤/Checklist/进度"章节；proposed的验收标准必须包含六列证据矩阵，且"当前结果"只能是Passed/Inspected/Not run/Inferred之一——后三者都不能写成测试通过。

普通代码注释和正式文档仍只描述当前行为、Owner、失败、时序和安全用法；不要把 decision rationale 复制到多个位置，否则又会制造需要人工同步的第二真相。

Gate 的运行与维护

工程信任 gate 的本地运行与自检只有两条命令：

python3 scripts/verify_engineering_contracts.py python3 -m unittest scripts.test_verify_engineering_contracts

verify_engineering_contracts.py执行全部 Owner-local 契约检查并给出汇总（decisions / workflows / agents files / docs / routers / web sources 数量）；test_verify_engineering_contracts.py是 verifier 自身的负向测试（negative controls），在临时目录构造"有效仓库"与"破坏契约的仓库"，证明每项检查都能因正确原因失败（见 scripts/test_verify_engineering_contracts.py）。

Gate 的维护原则（源码中体现为WORKFLOW_CONTRACTS，见 scripts/verify_engineering_contracts.py）：

• 必须只读、失败可诊断、拥有明确 Owner、保持有限延迟；
• 低成本只读检查（trust.yml）在每个 PR 无条件阻塞：它在 main 与 PR 上都不使用 path filter（unfiltered_pull_request=True），即全仓任意变更都要过；
• 真实 Compose integration/E2E（system-tests.yml等）只按路径触发：required_paths覆盖backend/**、docker/**、测试与 workflow 自身，命中高风险范围才运行；
• 高风险 Agent 主链路用无外部密钥的 deterministic assembled-path E2E 阻断（如test_deterministic_agent_path_e2e.py），real-provider-probe.yml手工探针负责外部 provider 校准；两者不能互相冒充；
• Workflow、selector、skip 或 expected-output 更新都按生产代码审查；
• 长期 flake、误报、绕过或无 consumer 的 gate 应及时修复或退役，禁止用新增规则掩盖既有缺陷——verifier 会拒绝登记吞错命令（|| true、set +e、exit 0等模式），也拒绝把命令放在被跳过或 continue-on-error 的 step 里。

trust.yml的实际配置（.github/workflows/trust.yml）在 5 分钟超时内顺序执行 verifier、verifier 负向测试、依赖更新策略测试、版本同步测试与发布 workflow 边界测试，permissions: contents: read保证只读。这与信任系统的定位一致：运行时当前事实属于ARCHITECTURE.md、对应代码 Owner 与测试，本页不复制 readiness、Run 或 checkpoint 契约；相关非显然取舍保存在聚焦的 implemented decision records 中，审计时从这些局部 Owner 派生，不维护另一份手工状态表。

事故反馈：只有达到门槛的逃逸事故才形成 postmortem

postmortems/ 只用于已经逃逸且达到项目复盘门槛的高影响缺陷。触发门槛的条件包括：造成安全、权限、数据完整性、数据丢失或外部副作用风险；关键用户链路或生产可用性显著受影响；多个模块/入口/部署以同一机制重复失败；既有测试、gate 或 Review 全绿仍让高价值错误逃逸且再发现成本高。

每份符合门槛的事故必须有 Owner，并说明：

• 真实影响与事实时间线；
• 因果链（为什么走到这一步）；
• 为什么既有安全网漏过；
• 新增或修正的 reproducer、oracle、gate、decision 或 standing order——即把这次逃逸转化为更早、更明确的未来失败。

复盘模板（TEMPLATE.md）的七个固定章节（影响、事实时间线、因果链、安全网为何漏过、修正与验证、防复发措施、未解决风险）会被 verifier 强制校验。学习需要主动实现和 Review，不会自动发生；仅增加 checklist、培训提醒或"加强 Review"不能单独关闭复盘。普通缺陷仍保留与风险相称的回归证据，但不强制制造事故文档。

从源码看信任系统的检查面

结合 scripts/verify_engineering_contracts.py 的完整实现，信任系统的静态检查面可以归纳为五个方向，均以"从真实 Owner 派生、不维护中央清单"为设计约束：

1. 决策契约（_validate_decisions）：lifecycle 目录必须齐全、至少有一份 tracked decision；每条记录校验文件名、状态、类型、Owner 文件存在性、必需章节及章节非空；implemented/archived禁止提案/进度类章节；proposed强制六列证据矩阵且六列全填；simplification类型在验收/验证中强制包含"旧能力不存在："与"重新引入条件："两个标签（第 697-784 行）。

2. Workflow 接线（_validate_workflows）：解析 workflow 的on事件、PR paths/paths-ignore 过滤与每个runstep 的条件/吞错配置；契约要求真实阻断 step、禁止吞错、阻断 workflow 不得用paths-ignore隐藏变更、全仓信任 workflow 不得使用 path filter、PR paths 必须覆盖 owning scope（第 459-529 行）。

3. 分层 AGENTS 指令（_validate_agents_files）：根AGENTS.md、backend/AGENTS.md、web/AGENTS.md、docs/AGENTS.md必须有且只有一个 H1、仓库内链接必须有效、字符数不得超过各自预算（5000/2400/1000/3200），防止指令文件无限膨胀（第 817-840 行）。

4. 架构边界（静态可判部分）：router 不得 import SQLAlchemy query builder（仅允许AsyncSession）、不得直接执行db/session/connection/database的持久化方法（第 870-911 行）；web/src/apis目录之外不得出现/api字面量（第 914-930 行）；普通 Service/Repository 不得取得yuxi.workspace.paths的宿主路径导出或读取YUXI_USER_DATA_DIR（第 933-984 行）。

5. 正式文档措辞（_validate_document_prose）：拒绝docs/正式文档中的"对举式否定"（如"不是 X 而是 Y"），要求直接陈述目标事实；docs/vibe/与node_modules视为非正式资料豁免。

这五个检查面共同证明一件事：引用、接线和部分边界真实存在。而 service 层事务、锁与 lease 语义仍由真实 PostgreSQL integration 证明，模型/浏览器行为由 real probe 校准——信任系统的边界在代码里写得一清二楚，不越权、不冒充。

把信任系统接入你的仓库：操作清单

如果你希望在自有仓库复刻这套机制，可以按以下顺序落地：

1. 建立决策记忆目录：创建docs/develop-guides/decisions/下的proposed/、implemented/、rejected/、archived/，并确立YYYY-MM-DD-topic.md命名与六种决策类型；
2. 确定语义 Owner 清单：为"意图与外部结果、状态与副作用、独立 oracle、负向案例、执行后果、理由与代价"六个闭环部分指定当前权威，拒绝任何中央 claim 文件；
3. 接入只读 gate：将python3 scripts/verify_engineering_contracts.py与 verifier 负向测试放入无 path filter 的 PR 阻断 workflow，低延迟高覆盖；高风险路径用按路径触发的 Compose integration/E2E，外部 provider 校准走手工 workflow_dispatch 探针；
4. 给每个新 guard 配负向案例：恢复目标缺陷后门禁必须变红，snapshot/fixture/expected output 只能显式更新；
5. 建立事故复盘门槛：只有逃逸且高影响的缺陷才写 postmortem，且必须包含 reproducer、因果链、安全网漏过原因与防复发机制。

这套体系的最终检验标准与 Yuxi 一致：删除任何一份手工维护的"状态总表"之后，从同一代码、测试、decision 和 workflow 重新派生，仍能得到相同结论——事实在语义 Owner 处闭合，信任由可复现的证据而非自述支撑。

【免费下载链接】Yuxi可私有部署的多租户知识智能体平台：统一 RAG、知识图谱、多智能体、MCP/Skills、沙盒与权限管理。Self-hosted knowledge agent platform for RAG, knowledge graphs and multi-agent workflows.项目地址: https://gitcode.com/GitHub_Trending/yu/Yuxi