2026-04-27：Tech Graph — 自动渲染 + 跨仓契约 + CI 门禁

记录日期：2026-04-27 摘要：把“架构图/契约”从人工维护的说明文档升级为“真值驱动 + 自动渲染 + CI 门禁”的工程闭环；通过跨仓静态校验同时约束后端最小输出与前端不越界读取，减少接口漂移与排障成本。 标签：架构治理 / 文档工程化 / API 契约 / SSE / CI / 门禁 / 可验证文档 / 工程协作 涉及任务：自动渲染 .ai.md、跨仓契约定义、CI 自动门禁 核心主题：Architecture Graph 的工程化落地 —— 从“人工维护”到“真值驱动 + 自动校验”

一、三个任务的关系

单仓真值校验      自动渲染 .ai.md         跨仓契约定义           CI 自动门禁
(manifest_check)  (render_ai)            (contract_check)       (GitHub Actions)
  │                    │                      │                      │
  ▼                    ▼                      ▼                      ▼
  └────────────────────┴──────────────────────┴──────────────────────┘
                              │
                              ▼
                    技术图谱工程化闭环

递进关系：

• 单仓真值校验（已完成）：解决"单仓内部"的真值一致性（端点/RPC/表/env）
• 自动渲染 .ai.md（本次）：解决"真值 → 文档"的自动同步（减少人工维护）
• 跨仓契约定义（本次）：解决"前后端"的隐式耦合（SSE events 字段契约）
• CI 自动门禁（本次）：解决"校验自动化"（PR 阶段拦截契约漂移）

二、“三类图谱”的对应关系

本次工作的本质：围绕 Architecture Graph 做工程化增强 —— 把“人工维护的架构文档”升级为“真值驱动、自动渲染、CI 校验”的可信架构事实源。

三、自动补全/增量渲染（从 manifest 生成 .ai.md）

核心问题

改端点后，需要手工同步 00_main.ai.md，容易出现“manifest 更新了，但 .ai.md 没更新”。

解决方案

区块替换策略：在 00_main.ai.md 中标记可机械生成的区块，脚本只替换该区块。

<!-- 00_main.ai.md -->
## 端点列表

<!-- AUTO:ENDPOINTS_AND_ANCHORS BEGIN -->
<!-- 以下内容由 tools/tech_graph_render_ai.py 自动生成 -->
- `GET /api/py/health`
- `POST /api/py/chat`
...
<!-- AUTO:ENDPOINTS_AND_ANCHORS END -->

## 业务子流程（手写，不动）
...

关键技术点

涉及文件

• tools/tech_graph_render_ai.py — 渲染脚本
• docs/_tech_graph/00_main.ai.md — 新增 auto 区块标记
• tools/tech_graph_manifest_check.py — 增加"建议运行 render"提示

四、跨仓契约 + Cross-Repo 门禁脚本

核心问题

前后端隐式耦合：后端改了 SSE events 字段，前端解析崩；前端依赖了字段，但后端未承诺稳定。

解决方案

契约真值 + 双向校验：

后端产出 (truth)  ──⊇──  契约 (contract)  ──⊇──  前端消费 (expect)
     │                       │                       │
     └─────── 脚本校验 ──────┴─────── 脚本校验 ──────┘

契约文件结构

// docs/_tech_graph/_contract_manifest.json
{
  "sse": {
    "envelope": {
      "event_values": ["chain", "done"]
    },
    "chain": {
      "data_keys": ["type", "ts", "step_id", "payload"]
    },
    "done": {
      "data_keys": ["ok", "mode", "run_id", "session_id"]
    }
  },
  "frontend_anchors": [
    "../ai-ink-brain/components/unified-chat/UnifiedChatPageClient.tsx",
    "../ai-ink-brain/app/api/py/unified/chat/stream/route.ts"
  ]
}

校验规则

关键技术点

涉及文件

• docs/_tech_graph/_contract_manifest.json — 跨仓契约真值
• tools/tech_graph_contract_check.py — 校验脚本
• tools/tech_graph_contract_demo.py — 演示脚本（一键体验负向→恢复）
• docs/_tech_graph/15_e2e_boundary.ai.md — 图谱补充说明

五、Cross-Repo Contract Check 接入 CI

核心问题

契约校验目前只能本地手动运行，PR 合并后才暴露漂移。

解决方案

GitHub Actions 自动门禁：每次 PR / push main 自动执行跨仓契约检查。

CI 设计要点

Checkout 策略（方案 A）：

# .github/workflows/tech-graph-contract.yml
jobs:
  contract_check:
    steps:
      - name: Checkout backend
        uses: actions/checkout@v4
        with:
          path: ai-ink-brain-api-python
      
      - name: Checkout frontend
        uses: actions/checkout@v4
        with:
          repository: cyning/ai-ink-brain
          path: ai-ink-brain
      
      - name: Run contract check
        working-directory: ai-ink-brain-api-python
        run: python tools/tech_graph_contract_check.py

关键约束：

• CI 只做静态检查（键名集合/枚举），不运行服务
• 前端仓 checkout 到 ../ai-ink-brain/ 保持相对路径一致
• 不引入外部私有依赖

涉及文件

• .github/workflows/tech-graph-contract.yml — CI workflow
• docs/_tech_graph/15_e2e_boundary.ai.md — 补充 CI 门禁说明

六、今日技术点汇总

1. 真值驱动（Single Source of Truth）

_manifest.json          → 单仓真值（端点/RPC/表/env）
_contract_manifest.json → 跨仓真值（SSE events 字段契约）
     │
     ▼
tools/xxx_check.py      → 校验脚本（返回码 0/1/2）
tools/xxx_render_ai.py  → 渲染脚本（增量更新文档）

核心思想：先定义真值，再让代码和文档都向真值对齐。

2. 区块替换（Incremental Render）

不是全量生成文档，而是标记可机械生成的区块，只替换该区块。

<!-- AUTO:XXX BEGIN -->
<!-- 机器生成 -->
<!-- AUTO:XXX END -->

好处：减少 diff、避免误伤手写内容、可一键修复。

3. 双向契约校验（Cross-Repo Contract）

不是单向的"后端定义、前端遵守"，而是双向约束：

• 后端必须覆盖契约（不能少字段）
• 前端必须不越界（不能读未承诺字段）

4. 返回码语义化

0  # OK — 校验通过
1  # drift — 真值不一致（可被 CI 识别为失败）
2  # error — 运行错误（文件缺失、脚本异常）

5. CI 静态检查

不运行服务、不做 e2e，只做静态键名/枚举校验，速度快、稳定性高。

6. 变更 SOP（契约优先）

端点变更:     改后端 → 更新 manifest → 跑 manifest_check → （可选）跑 render
Events 变更:  更新 contract → 改后端 → 跑 contract_check → 改前端 → 再跑 contract_check

七、三类图谱的后续设计思考

根据文章中的框架，当前三类图谱的落地状态：

Architecture Graph（架构图谱）— 本次强化

已落地:

• 00_main.md — 入口总图（Mermaid 拓扑）
• 01_struct.md — 数据库结构
• 10~13_flow_*.md — 业务流程图（RAG/Text2SQL/FTS/RPC）
• _manifest.json — 真值来源
• tech_graph_manifest_check.py — 漂移校验
• tech_graph_render_ai.py — 自动渲染

待增强:

• 模块依赖图（当前只有入口图，无模块间调用关系）
• 配置依赖图（39 个 env 变量的依赖关系）
• 失败路径图（当前只有 happy path）

Runtime Graph（运行图谱）— 已落地

已落地:

• 14_runtime_observability.md — 事件流、日志落点
• _contract_manifest.json — SSE 事件契约
• tech_graph_contract_check.py — 跨仓校验
• tech-graph-contract.yml — CI 门禁

待增强:

• 错误码分层图（当前只有事件类型，无错误分级）
• 超时/重试策略图（散落在代码中，未集中）
• 降级策略图（当前无显式定义）

System Graph（系统图谱 / 跨仓契约）— 已落地

已落地:

• 15_e2e_boundary.md — E2E 边界、锚点
• _contract_manifest.json — 前后端契约
• tech_graph_contract_check.py — 双向校验

待增强:

• 前端状态机图（当前只有后端流程）
• API 版本演进图（当前无版本管理）
• 数据流图（内容仓库 → 向量库 → 前端展示的完整链路）

八、落地文件清单

九、一句话总结

今天的核心成果：把 Architecture Graph 从人工维护的文档，升级为"真值驱动 + 自动渲染 + CI 门禁"的工程化体系。 关键思想：先定义真值（manifest），再让代码、文档、前后端都向真值对齐，用脚本自动发现和拦截漂移。 后续方向：补齐 Runtime Graph 的错误分级/超时策略、System Graph 的前端状态机/数据流。

十、结尾

如果用一句话总结今天做的事：

把“架构图/契约/任务”从可读的文档，升级为可验证的协作协议，并用 CI 门禁把“越界读取”和“字段漂移”提前拦截在合并之前。

这类工作短期看像“偏工程治理”，但长期价值很直接：

• 少猜测、少口口相传
• 字段变更不再靠人肉通知
• 新人/新 Agent 接手的学习路径更短
• 排障更快，因为你有稳定的请求标识与一致的契约边界

如果你也在做 AI 辅助工程协作，我建议优先从这条“可验证的静态收敛层”开始：它能显著降低幻觉与漂移带来的隐性成本。