2026-04-24｜图谱驱动开发---告别大段文档，上下文省 70%，让 AI 按你的流程写代码

小小猪排画中游

发布于 2026-06-17 08:36:27

1000

从纯文本到拓扑协议：Mermaid 双轨制与 i18n 跨语言召回 v1 落地

Mermaid 拓扑协议双轨制在后端（5 图）与前端（5 图）全部落地：.md 人类版 + .ai.md AI 协议版 + validate_mermaid.py 验证脚本
i18n 跨语言召回 v1 验收通过：中文 query → 英文候选 OR 扩展，术语表 42 条，pytest 32 全绿
技术图谱从「纯文本叙述」→「Mermaid 流程图」→「拓扑协议结构化」的三阶段演进完成

1) 今日关键目标

[x] 将 Mermaid 拓扑协议从概念落地为可执行规范（双轨制 + 验证脚本）
[x] 后端 5 张 flowchart 全部完成 .ai.md AI 协议版重写
[x] 前端 5 张 flowchart 同步完成 .ai.md 与 .cursorrules 更新
[x] i18n 跨语言召回 v1 任务验收（术语表 + query-side OR 扩展 + 可观测性）

2) 关键产出 / 决策

决策 1：Mermaid 双轨制（人类版 + AI 协议版）

Why：LLM 生成 Mermaid 时裸边（A --> B）幻觉率高，但人类读带引号的边（A --"->"--> B）视觉噪音大。

What：

.md = 人类友好版：简洁标签、裸边可用、锚点写在节点内
.ai.md = AI 协议版：结构化标记（~> 异步、?> 条件、[ok]/[err] 状态、::xxx 元关系）、零裸边、锚点分离为 // → path#Ln

影响面：

后端：docs/_tech_graph/ 5 张 flowchart 双轨化 + 99_mermaid_protocol.md 规范
前端：docs/_tech_graph/ 5 张 flowchart 双轨化 + .cursorrules 引用总规范
验证：scripts/validate_mermaid.py 支持前后端通用扩展名

决策 2：拓扑协议边标记语义

标记	语义	示例
->	同步执行	process() → save()
~>	异步（await）	await embed_text()
=>	映射/赋值	result = transform(data)
?>	条件分支	if not valid: / try/except
[ok]	成功路径	validate() --"[ok]"--> save()
[err]	错误路径	parse() --"[err]"--> fallback()
::yields	流式产出	LLM --"::yields"--> sources
::branches	并行分支	gather 多路
::merges	结果归并	fuse_hits_rrf()
::archives	日志归档	OUT --"::archives"--> DB

决策 3：i18n v1 最小可用方案

Why：中文提问无法召回英文文档（如 "消息历史" 无法命中 RunnableWithMessageHistory）。

What：

术语表 data/i18n_glossary.json：42 条中文 → 英文候选（如 "消息历史" → ["message history"]）
Query-side OR 扩展：原始 query + 候选以 OR 合并进 keyword_documents(query_text)
严格上限：候选数 ≤ 5、单候选 ≤ 48 字符、总 query ≤ 240 字符
可观测：rag.query_expand 事件输出扩展前后对比

验收：pytest 32 passed，包括候选生成、上限截断、异常兜底。

3) 实现要点

3.1 拓扑协议验证脚本

# scripts/validate_mermaid.py
# 检查项：
# 1. 零裸边（无边标记的 -->）
# 2. 锚点格式 // → path#Ln
# 3. 异步节点 [[async def ...]] 必须用 ~> 边

3.2 i18n Query 扩展流程

flowchart LR
    Q[中文 Query] --> G{术语表命中?}
    G -->|命中| C[生成英文候选]
    G -->|未命中| R[返回原 query]
    C --> L{超限?}
    L -->|是| T[截断]
    L -->|否| O[OR 合成]
    T --> O
    O --> K[keyword_documents]
    R --> K