# MSG 白皮书系统知识网络化实现说明（自用执行版）

**日期**: 2026-04-29  
**用途**: 本文档不是发给 MSG 开发团队的对外任务单，而是给我自己后续继续实现 `msgchain` 白皮书系统时使用的执行说明。  
**执行原则**: 等待用户进一步命令后，按本文档的阶段顺序继续实现，不抢跑、不把规划态写成实现态、不用展示层替代底层证据。  

---

## 1. 本文档要解决什么问题

用户希望把当前 `MSG 公链白皮书系统` 进一步升级为一种兼具以下能力的网页系统：

1. **白皮书导航能力**  
   能用总拓扑、专题页、证据页、母图页快速理解 `MSG Chain` 的制度、架构、能力边界和实施路线。

2. **知识网络化能力**  
   能接近 `Hermes / Obsidian / LLM Wiki / Graph View` 一类产品的效果，把多个概念、模块、接口、制度、证据、实现状态组织成可跳转、可检索、可视化的知识网络。

3. **证据回溯能力**  
   不把“图谱很完整”误当成“链上能力已完成”，所有关键结论都必须尽可能回到 `源码 / query / tx / receipt / log / 原文档`。

4. **可持续增量扩展能力**  
   当 `msgchain` 仓库新增功能点、接口、合约、基础设施、运维能力时，白皮书系统要能持续吸纳，而不是每次都变成一堆散乱的新页面。

---

## 2. 当前判断：是否要先完善白皮书系统

**结论**: 要，而且应该先做。

不是先去追求更炫的知识网络动画，而是应该先把 **白皮书系统的覆盖面、状态标注、功能挂载、证据映射** 补完整，再继续做“知识网络化增强”。

原因如下：

1. 当前白皮书系统已经具备较强的图谱导航底座  
   已有母图、专题图、搜索、点击锁定、上下游链路切换、`showModal` 证据弹窗等能力，说明“图谱网页层”已经可用，不需要推翻重做。

2. 仓库内已经出现多条新增功能线，但尚未系统化挂进白皮书导航  
   这些功能点如果不先补到白皮书系统里，后续再做知识网络化，只会把“旧地图”做得更花，而不是让地图更完整。

3. 用户后续希望由我继续亲自实现  
   因此更合理的顺序应是：  
   `先补覆盖 -> 再补知识网络关系 -> 再补自动化知识引擎`

4. 项目规则要求不能用展示替代真实完成判断  
   所以任何“Graph View”“双向链接”“智能推荐”都必须建立在明确的实现态 / 部分实现 / 规划态标注之上。

---

## 3. 当前白皮书系统已具备的基础

当前白皮书系统并不是空白项目，而是已经形成了较成熟的网页化白皮书骨架，至少具备以下底座：

1. `generate_all_v5.py` 驱动的统一生成机制  
   说明白皮书页面不是零散手工页，而是可集中维护、可批量生成、可统一回灌。

2. 母图 + 专题页 + 审计页 + 证据页的分层结构  
   适合继续演进为知识网络型白皮书。

3. 交互基础能力已经存在  
   包括但不限于：
   - 节点搜索
   - 点击锁定
   - 上游 / 下游 / 一跳 / 全链路切换
   - `showModal` 证据弹窗
   - 专题页之间的相互跳转

4. 已新增 AI 专题页簇  
   当前已补入：
   - `ai_control_plane`
   - `ai_policy_capability`
   - `ai_task_l2`
   - `ai_value_flow`
   - `ai_registry_market`
   - `ai_governance_autonomy`
   - `ai_validator_autonomy`
   - `ai_world_computer_roadmap`

这说明白皮书系统已经非常适合继续升级为“知识网络化白皮书”，而不是改成另一套全新站点。

---

## 4. 当前仓库里已出现、但白皮书系统仍需优先补面的功能线

以下内容是本轮核对仓库后，判断对白皮书系统“必须优先补挂”的新能力面。  
注意：这里说的是“仓库已有相关实现、文档或接口表面”，不代表都已经达到主网真实完成态。

### 4.1 AI Agent API / OpenAPI 能力面

仓库中存在 `docs/api/agent_openapi.yaml`，显示已有较完整的 `MSG Chain AI Agent API` 接口表面，包括：

- `Query`
- `Wallet`
- `NFT`
- `Events`
- `Registry`
- `MPC`
- `DeFi`（含 stub）
- `Oracle`（含 stub）
- `Payment`（含 stub）
- `Bridge`（含 stub）

这说明白皮书系统仅有 `ai_agent / ai_control_plane / ai_policy_capability` 还不够，后续应补一页更偏“接口表面与能力分层”的专题页。

### 4.2 Indexer / Memo 检索能力面

仓库中存在 `docs/logs/re-billion/71_Integration_Ready_Notice_20251230.md`，其内容表明：

- `Indexer 服务` 已作为独立组件出现
- 有 `Indexer API`
- 已出现 `memos`、`search`、`types`、`submit` 等端点

这类能力目前不应继续散落在日志和联调通知里，白皮书系统应有独立“索引与可检索数据层”表达。

### 4.3 Monitoring / Metrics / Grafana 能力面

仓库中存在 `docs/logs/week2_day11_monitoring_integration_guide.md`，显示：

- 已有 `Prometheus metrics`
- 已有 `Grafana dashboard`
- 已有 `20 个 metrics + 11 个 panels`
- 已有性能监控、安全防护、故障排查等运维表达

当前白皮书导航虽有系统母图，但仍缺一张专门讲“观测性 / 监控 / 指标 / 运维可观测”的专题页。

### 4.4 L1 / L2 架构集成能力面

仓库中存在 `docs/logs/Week5_Day1_L1_L2_Integration_Plan_20251207.md`，显示：

- 有 `L1 Discovery`
- 有 `L2 Bootstrap`
- 有统一 `Message Router`
- 有统一 `Connection Pool`
- 有从旧架构向统一架构迁移的设计

这类能力与当前 AI / world_computer / scaling_cost 有关联，但尚未在白皮书系统中被抽成一张明确的“L1-L2 架构专题图”。

### 4.5 SDK / Developer Surface 能力面

仓库中存在 `docs/logs/re-billion/02_SDK_API_Reference.md`，显示有独立的 SDK 设计方向：

- `MSGWallet`
- `MSGClient`
- `ContractClient`
- `TxBuilder`
- `Utils`

即便该文档口径仍写着“规划中”，白皮书系统也应把这类能力面挂进去，并明确标为“开发者表面 / 规划态或部分实现态”，而不是完全缺席。

---

## 5. 核心判断：下一步不应该直接做什么

在继续实现之前，需要明确几条禁止事项：

1. **不能直接跳到“自动知识库引擎”**
   如果白皮书母图对新增功能面的覆盖还不完整，先做自动抽取和双向链接只会放大结构混乱。

2. **不能把仓库里出现过的文档都当成已实现能力**
   尤其像 `SDK`、某些 `stub API`、某些联调文档、某些规划文档，都必须按 `实现态 / 部分实现 / 规划态` 分开。

3. **不能把视觉炫技当成完成**
   `Graph View`、节点动效、布局转场都只是展示层增强，不是白皮书核心完成标准。

4. **不能绕过底层证据规则**
   任何新增专题页都必须尽量保留到 `query / tx / receipt / log / 源码 / 接口原文 / 文档原文` 的映射入口。

---

## 6. 自用执行总路线

后续如果用户下令由我继续实现，应按以下阶段推进。

### Phase 0：白皮书系统覆盖面复核与补面清单冻结

目标：先把“还缺哪些功能专题页”收口清楚。

要做的事：

1. 盘点当前所有已生成模块页
2. 对照仓库新增功能线，形成“需补页清单”
3. 给每条功能线标记：
   - 已实现
   - 部分实现
   - 规划态
   - 禁止越级宣称
4. 明确每页要挂哪些证据入口

本阶段交付物：

- 一份覆盖面清单
- 一份页面优先级清单
- 一份状态标注规则

### Phase 1：先补白皮书系统的新增功能专题页

目标：先让白皮书地图完整。

优先补以下页面：

1. `agent_api_surface.html`
   - 说明 `OpenAPI / Query / Wallet / Events / Registry / MPC / Stub API`
   - 明确哪些端点是真实可用，哪些仍是 stub

2. `indexer_data_plane.html`
   - 说明 `Indexer / Memo / Search / Submit / Types`
   - 连接到数据、检索、AI 训练素材、生态数据层

3. `observability_monitoring.html`
   - 说明 `Prometheus / Grafana / Metrics / Monitoring / Alerting`
   - 作为“链上运行可观测性”专题页

4. `l1_l2_architecture.html`
   - 说明 `L1 Discovery / L2 Bootstrap / Unified Router / Connection Pool`
   - 对接现有 P2P、世界计算机、扩容页

5. `sdk_dev_surface.html`
   - 说明 `Wallet / Client / ContractClient / TxBuilder / Utils`
   - 明确是开发者能力表面，不一定等于当前已完全发布

本阶段原则：

- 先补“地图完整度”
- 不追求知识库自动化
- 所有新增页都纳入首页、母图、专题跳转和结构巡检

### Phase 2：把白皮书升级成“知识网络化白皮书”

目标：让白皮书从“页面集合”升级成“关系网络”。

要做的事：

1. 为每个模块页新增 `相关节点`
2. 为每个模块页新增 `backlinks`
3. 新增全局 `knowledge_graph.html`
4. 新增按实体/概念分类的索引页
5. 引入“来源卡片 / 证据卡片 / 代码卡片”
6. 新增“相邻概念推荐”

这一阶段做出来后，视觉和使用体验会开始接近：

- `Hermes`
- `Obsidian Graph View`
- `LLM Wiki`
- “网页化知识地图”

### Phase 3：知识抽取与增量构建引擎

目标：让白皮书不只是手工编排，而是能增量吸收新文档。

要做的事：

1. 从 `docs/`、`docs/logs/`、`api/`、关键源码注释中抽取实体
2. 自动生成概念节点和关系边
3. 自动识别：
   - 合约
   - API
   - 模块
   - 证据
   - 角色
   - 制度
   - 规划项
4. 生成双向链接
5. 记录来源与更新时间
6. 在冲突时标记“候选关系”，而不是自动写死为事实

这一阶段才真正接近“知识网络自动整理”的效果。

---

## 7. 我后续实现时的优先级判断

如果用户下一步让我继续实现，我应按下面的优先级执行：

1. **优先级 P0**：先补白皮书系统覆盖面  
   不先补这一步，后续知识网络化会建立在不完整地图上。

2. **优先级 P1**：再做知识网络化浏览能力  
   包括 `backlinks`、`相关节点`、`关系索引`、`全局知识图谱页`。

3. **优先级 P2**：最后做自动化知识引擎  
   包括实体抽取、关系抽取、增量更新、来源回溯。

一句话执行决策：

> 当前 `msgchain` 新增了许多功能点，因此 **还要先继续完善白皮书系统**，而且这是后续知识网络化升级的前置步骤。

---

## 8. 后续我应重点检查的文件与入口

后续继续实现前，应优先回看这些位置：

### 白皮书系统核心

- `docs/architecture_diagrams/generate_all_v5.py`
- `docs/architecture_diagrams/check_architecture_diagrams.py`
- `docs/architecture_diagrams/modules/*.html`

### 新能力面参考源

- `docs/api/agent_openapi.yaml`
- `docs/logs/re-billion/71_Integration_Ready_Notice_20251230.md`
- `docs/logs/week2_day11_monitoring_integration_guide.md`
- `docs/logs/Week5_Day1_L1_L2_Integration_Plan_20251207.md`
- `docs/logs/re-billion/02_SDK_API_Reference.md`

### 已有 AI / 自治 / 世界计算机专题页

- `ai_control_plane`
- `ai_policy_capability`
- `ai_task_l2`
- `ai_value_flow`
- `ai_registry_market`
- `ai_governance_autonomy`
- `ai_validator_autonomy`
- `ai_world_computer_roadmap`

---

## 9. 下一次接到命令后的执行模板

如果用户下一条命令是“继续实现”，我应按以下模板行动：

1. 先确认本轮要补哪一条功能线
2. 读对应源文档与源码入口
3. 判断其状态：
   - 实现态
   - 部分实现
   - 规划态
4. 在 `generate_all_v5.py` 中补对应模块页
5. 把页面挂入首页 / 母图 / 相关专题页
6. 更新 `check_architecture_diagrams.py`
7. 重生成模块页
8. 运行结构巡检
9. 抽查交互效果与文案边界
10. 向用户汇报：
   - 本轮新增了什么
   - 哪些仍是规划态
   - 哪些不能越级宣称

---

## 10. 当前结论

当前最合理的下一步不是停在分析层，也不是立刻做最重的知识自动化，而是：

1. **继续完善 `msgchain` 白皮书系统**
2. **优先把新增功能点补进白皮书地图**
3. **在地图完整后，再继续做知识网络化增强**

这份文档到此作为后续自用执行基线保留。等待用户下一步命令后，按本文档继续实施。

 ---

## 11. 2026-05-15 追加：知识网络浏览层已进入现行生成器

当前已不再停留于“模块同步”层，现行 `generate_all_v5.py` 已进一步承担以下知识网络化职责：

1. 生成统一的 `knowledge_network.json`
   - 记录模块标题、状态、分组、标签、出链、回链、相邻推荐
   - 作为后续继续自动化知识抽取前的轻量中间层

2. 为单页模块补入“知识网络定位”面板
   - 说明当前页面属于哪一类知识节点
   - 展示它继续通向哪些页面
   - 展示哪些页面会回到它
   - 给出相邻概念推荐

3. 新增 `knowledge_network.html`
   - 作为整站知识网络浏览层总览页
   - 支持按状态、分组、关键词浏览模块关系
   - 让白皮书从“模块集合”推进为“关系网络”

这一层的定位必须始终保持克制：

- 它是**关系浏览层**
- 不是自动事实引擎
- 不是把弱证据包装成强证据
- 不是用展示层替代 `query / receipt / log / code anchor`

---

## 12. 后续持续迭代规则（白皮书系统与 msgchain 同步）

后续当 `msgchain` 继续开发新增能力时，白皮书系统应按下面顺序持续迭代：

1. 先核对真实来源
   - 代码
   - query
   - receipt
   - log
   - 当前有效文档

2. 再判定状态
   - 已实现
   - 部分实现
   - 规划态

3. 再补页面与关系
   - 单页内容
   - 首页入口
   - 母图入口
   - 相关专题页入口
   - 知识网络层分组 / 标签 / 出链 / 回链

4. 最后重生成与审计
   - `python3 docs/architecture_diagrams/generate_all_v5.py`
   - `python3 docs/architecture_diagrams/check_architecture_diagrams.py`
   - 保存新的 `module_audit_report.json`

一句话要求：

> 后续不是只增页面，而是要让“模块页 + 关系层 + 证据层”一起演进。

---

## 13. Cloudflare 免费套餐适配原则

白皮书系统继续演进时，必须始终符合以下静态部署原则，确保能长期跑在 Cloudflare 免费套餐：

1. 保持**纯静态优先**
   - HTML
   - JSON
   - 图片
   - 少量内联脚本

2. 不默认引入重型后端
   - 不依赖数据库
   - 不依赖自建搜索服务
   - 不依赖必须在线执行的动态 API

3. 知识网络层优先采用**单 JSON + 静态页面渲染**
   - 先用生成器产物解决浏览和检索
   - 未来确有必要，再考虑 Workers 增量增强

4. 继续控制资源规模
   - 避免无节制新增散页与大图片
   - 避免把构建缓存、临时文件、历史杂项一起发到发布目录

5. 继续保持可本地生成、可静态托管、可对外访问
   - 本地生成仍由 `generate_all_v5.py` 完成
   - Cloudflare 只负责托管静态产物
   - 访客浏览交互不应依赖私有运行环境

6. 优先本地化第三方前端依赖
   - Mermaid 等关键图形脚本优先放入站内静态资源目录
   - 避免把图渲染能力绑死在外部 CDN 可用性上

7. 发布目录要保持干净
   - 不把 `__pycache__`、本地编译缓存、临时调试文件一起发到静态站点
   - 大图尽量只在专题页按需加载，不放进首页默认渲染链路