Tekton — 与智能体共同设计架构的一致模型

Tekton — 在一份共享模型上共同设计架构

简介

一个用于人类↔智能体架构协作的基础层。设计存在于一个 YAML 模型中，我们双方都能编辑；Git 是往返的载体。你看到它（HTML 查看器）；我读写同一个模型。我们在相同的上下文中思考。

它解决的问题：手工编写的 HTML/SVG 文档是终端渲染——你无法遍历、查询或编辑它，并且其图表不携带任何含义。Tekton 将实时模型上移到渲染的上游。

引擎

scripts/tekton.py（Python 3，依赖 pyyaml）。本体定义在 references/ontology.md 中。

python3 scripts/tekton.py validate <model.arch.yaml>       # 完整性检查
python3 scripts/tekton.py lint     <model.arch.yaml>       # v0.2 — 适应度函数；违规时退出码为 1
python3 scripts/tekton.py stats    <model.arch.yaml>       # 节点/边/状态/规则计数
python3 scripts/tekton.py views                            # 列出 6 种视图
python3 scripts/tekton.py mermaid  <model.arch.yaml> <view># 原始 mermaid（可嵌入/智能体可读）
python3 scripts/tekton.py render   <model.arch.yaml> [-o out.html]  # 品牌 HTML 查看器
python3 scripts/tekton.py query    <model.arch.yaml> <from> <to>    # 跨层级路径

v0.2 本体升级（来自架构评审）

• 包含关系 — 任何节点上的 parent: + boundary 类型；查看器渲染嵌套分组，双击可折叠/展开（C4 风格的向下钻取）。
• 生命周期 — 节点上的 status:（current|target|deprecated；target 渲染为虚线 = 同一模型中的现状与未来状态）以及决策上的完整 Nygard ADR 字段（context、consequences、status、supersedes）。
• 质量属性 — qualities: 块；NFR 通过 constrains 约束元素；在详情面板 + 专用视图中展示。
• 适应度函数 — rules: 块（forbid-dep、no-cycle、layer-order）；tekton lint 可作为 CI 门禁（退出码 1）。设计循环的独立验证器。

智能体在设计会话中的使用方式

1. 定位/创建模型：<project>/docs/design/<name>.arch.yaml（临时使用 examples/ 目录）。
2. 边思考边修改 — 随着对话揭示组件、流程、数据、基础设施和 ADR，直接向 YAML 中添加/调整节点、边和决策。
3. 每次实质性编辑后执行 validate + lint（检查悬空引用、错误类型、适应度规则）。
4. render，然后——在将查看器呈现为正确之前——运行几何审计：bash tests/visual-audit.sh <model.arch.yaml>。它会在无头模式下渲染每个视图，并在出现节点重叠或空捕获时失败。没有它就声称“图表正确”正是第一个内部试用（dogfood）所捕获的确切失败（组内边断开、节点重复——这些对 DOM 计数探测不可见，仅通过几何审计捕获）。在 URL 中使用 #<view> 深度链接到某个视图。
5. query 以回答可追溯性问题（“这影响什么？”），而不是猜测。
6. 引导 → 重复。 人类编辑 YAML 或查看器意图；git diff 是交接的凭证。

已知的装饰性残余（非审计失败）：旅程中的自循环边会使 ELK 在任意步骤处中断循环（循环必须在某处断开）；在密集分组中，相邻的平行边标签可能靠得很近。

约定

• 模型文件：*.arch.yaml。渲染后的查看器：*.view.html（可选择加入 gitignore 或提交）。
• 每个有界系统一个模型；通过 external 节点 + uses 边链接系统。
• 决策（ADR）是一等公民节点——将它们钉在它们所govern的内容上。
• Category-C HTML 报告成为模型的下游导出产物，而非真理来源。

渲染 — 为什么不是 Mermaid

主要查看器是自定义渲染器，而非 Mermaid。Mermaid 的主题化能力上限无法表达 Broomva 设计系统（OKLCH 蓝色轴、磨砂卡片、有资格获得的玻璃效果、彗星光晕），且其 dagre 布局在密集图上性能下降。替代方案：elkjs 在浏览器中计算布局（纯 JS → 输出仍为单个自包含的 HTML 文件），节点绘制为 Broomva 磨砂卡片（玻璃效果保留给浮动详情面板，遵循设计系统中“玻璃效果是赚来的”规则）。设计令牌（Design Tokens）从 Broomva 设计系统内联生成。tekton mermaid 仅保留为一次性嵌入/智能体可读的目标。

路线图（v0 → v2）

• v0.2（当前）： YAML 模型 · validate + lint（适应度函数） · 6 种视图 · 品牌 elkjs 查看器（包含关系折叠/展开，现状与未来状态，点击追踪，玻璃效果详情面板） · 跨层级查询 · Mermaid 回退嵌入。
• v1： 双向往返（在查看器中拖拽/编辑 → 序列化回 YAML）；MCP 服务器（已验证的突变，确保智能体无法发出无效模型）；引入完整的 Broomva 设计系统以构建 React-Flow 交互式画布。
• v2： CRDT（loro）实时人类↔智能体协同编辑；实时同步到 Prosopon 作为表现层。

状态

v0 内部试用 — 内部设计工具。在≥3 个真实系统上使用过一次设计循环后（三回原则），再技能化（已测试 + 注册）。