# 2026-04-24｜从纯文本到拓扑协议：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 拓扑协议验证脚本

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

### 3.2 i18n Query 扩展流程

![ScreenShot_2026-04-24_211850_567.png](https://developer.qcloudimg.com/http-save/yehe-12403993/8b6a07dbb800810b43b0e8a9d749b1dc.png)

### 3.3 双轨文件行数对比

| 图 | 人类版 | AI 版 | 膨胀率 |
|---|-------|------|--------|
| 00_main | 54 | 70 | +29% |
| 10_flow_rag | 52 | 78 | +50% |
| 11_text2sql | 45 | 63 | +40% |
| 12_fts | 45 | 64 | +42% |
| 13_rpc | 40 | 59 | +47% |

---

## 4) 风险与坑位

- **锚点正则兼容**：前端使用 `.tsx` `.ts` 扩展名，初始验证脚本只支持 `.py` `.sql` `.md`，已修复
- **通配符路径**：`app/**/page.tsx` `[...slug]` 等 glob 语法不符合标准锚点格式，作为合理例外
- **人类版维护成本**：双轨意味着改代码需同步更新两份图。缓解：优先更新 `.ai.md`，`.md` 按需同步
- **i18n 术语表运营**：42 条仅覆盖高频术语，长期需回填机制（遇到未命中 → 人工补充 → 回归验证）

---

## 5) 明日计划

- [ ] 验证拓扑协议在真实 LLM 生成场景中的幻觉降低效果（对比实验）
- [ ] i18n 术语表回填：从最近 3 天未命中 query 中提取候选补充

---


## 工程图｜i18n v1 Query-Side 扩展
![ScreenShot_2026-04-24_211917_953.png](https://developer.qcloudimg.com/http-save/yehe-12403993/e5f63dbcc4606d475b2c2820d74303e8.png)


Mermaid 拓扑协议双轨制在后端（5 图）与前端（5 图）全部落地：.md 人类版 + .ai.md AI 协议版 + validate_mermaid.py 验证脚本

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

今天把 Mermaid 图谱从"人画人看"升级成了"人画 AI 读"的双轨制——人类版简洁，AI 版带结构化标记防幻觉。顺手把 i18n 跨语言召回也验收了，中文问"消息历史"现在能命中英文的 RunnableWithMessageHistory 了。

人工智能

后端

开发工具

Mermaid拓扑协议双轨制落地，实现.md人类版与.ai.mdAI协议版同步开发，配套验证脚本确保规范执行。i18n跨语言召回v1通过验收，支持中文query扩展英文候选，建立42条术语表。技术演进完成从纯文本到拓扑协议的三阶段升级，提升开发效率与代码可读性。

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云AI代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

功能1上新10个字符

功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符。

功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符。

功能5描述100个字符功能5描述100个字符功能5描述100个字符功能5描述100个字符功能5描述100个字符功能5描述100个字符

功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符

功能4上新

文章&问答评论现已支持表情

全新交互，全新视觉，新增快捷键、悬浮工具栏、高亮块等功能并同时优化现有功能，全面提升创作效率和体验

社区富文本编辑器全新改版！诚邀体验～ 

精选全网热门MCP server，让你的AI更好用 🚀

💥开发者 MCP广场重磅上线！

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

图谱驱动开发---告别大段文档，上下文省 70%，让 AI 按你的流程写代码-腾讯云开发者社区-腾讯云

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

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

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐