MSG Chain AI Agent FAQ 路由与问答模板

链 ID: msg-chain-1 | 共识: DAR | 虚拟机: CosmWasm (WasmVM)
状态: 规划文档 — 主网裁决为 No-Go，所有数据均为主网预演
Gas: 1,000,000,000 attoMSG/gas
Gas 分配: 40% 验证者 / 30% 开发者 / 20% 燃烧 / 10% 基金会金库
地址格式: SHA3-512(前40位) + SHA-256 校验 | 签名: Dilithium-5 (公钥2592字节 / 私钥4864字节 / 签名4595字节)
AI Agent安全边界: 永不自主创建新合约，永不自主调整 Gas 参数，永不自主铸造/销毁代币

1. 概述

1.1 什么是 FAQ 路由

FAQ 路由（FAQ Router）是 MSG Chain 白皮书机器层提供的一套标准提示词与文件读取流程,专门供工具调用型 AI Agent、Telegram 群机器人、开发者聊天助手和官网 FAQ 机器人使用。它定义了一条从用户问题到白皮书证据的稳定检索路径,确保 AI Agent 的回答始终基于白皮书机器层,而非通用先验知识。

1.2 何时使用此模板

1.3 为什么需要 FAQ Router

直接使用通用 LLM 回答 MSG Chain 相关问题存在四个固有风险:

FAQ Router 本质上是一个"证据到答案的翻译层": 将白皮书机器层的结构化证据（chunk/export/HTML）翻译成端用户可读的 FAQ 答案,同时保留原始证据边界,不让 LLM 在翻译过程中丢失或夸大信息。

1.4 Knowledge Router 架构

MSG Chain 白皮书机器层（Machine Layer）由三层构成:

┌─────────────────────────────────────────────────────┐
│                   权威叙事层                          │
│  modules/*.html (authoritative narrative layer)      │
│  └─ economy.html, consensus.html, dao.html ...      │
├─────────────────────────────────────────────────────┤
│                   机器友好派生层                      │
│  module_exports/*.json (模块级结构化导出)            │
│  module_chunks/*.json (分块检索文档)                  │
├─────────────────────────────────────────────────────┤
│                   入口与路由层                        │
│  agent_entry.json        → 稳定机器入口              │
│  retrieval_hints.json    → 主题路由提示              │
│  module_chunks/index.json→ 全量分块索引              │
│  module_exports/index.json→ 全量模块索引             │
└─────────────────────────────────────────────────────┘

FAQ Router 位于第三层（入口与路由层）,职责是:

1. 读取 agent_entry.json 发现当前稳定入口与爬取契约
2. 读取 retrieval_hints.json 将用户问题映射到最相关主题
3. 按 Chunk → Export → HTML 优先级拉取证据
4. 回答时携带实现边界、状态标签与证据谨慎声明

2. FAQ 路由协议

2.1 分步路由流程 (Step-by-Step Routing Flow)

FAQ Router 必须严格遵守以下五步流程,任何一步都不可跳过。

Step 1: 读取 agent_entry.json

URL: https://msgchain.org/whitepaper/agent_entry.json
用途: 发现当前稳定机器入口与爬取契约

agent_entry.json 核心字段:

• schema_version: 当前为 v1
• project: MSG Chain Whitepaper System
• public_base_url: https://msgchain.org/whitepaper/
• entry_points: 所有公开入口映射
• crawl_contract: 爬取契约,定义文件间关联关系
• recommended_crawl_order: 推荐爬取顺序
• current_boundaries: 当前系统边界声明

关键 entry_points 表格:

Step 2: 读取 retrieval_hints.json 进行主题路由

URL: https://msgchain.org/whitepaper/retrieval_hints.json
用途: 将用户问题映射到最相关主题

retrieval_hints.json 当前包含 8 个主题,结构如下:

{
  "schema_version": "v1",
  "topic_count": 8,
  "topics": [
    {
      "topic_id": "economics",
      "title": "经济模型与发行结算",
      "questions": ["MSG 的发行规则是什么", ...],
      "preferred_tags": ["铸造", "奖励", "结算"],
      "recommended_modules": [...],
      "recommended_chunks": [...],
      "answering_guidance": [...]
    }
  ]
}

Step 3: 优先拉取推荐 Chunk

对于路由到的主题,读取 recommended_chunks[] 中的前 2-4 个 chunk 文件。

Chunk 文件路径模板:

module_chunks/{module_stem}__chunk_{chunk_no}.json
公网: https://msgchain.org/whitepaper/module_chunks/{module_stem}__chunk_{chunk_no}.json

Chunk 文件特征:

• 目标大小: 900 字符
• 重叠大小: 120 字符
• 包含 "铁证" (🔍) 块、流程图、原始 JSON 示例和边界声明

Step 4: Chunk 不足时拉取模块 Export 或 HTML

如果 chunk 内容不足以回答问题,按以下顺序升级:

1. 模块 Export JSON: module_exports/{module_stem}.json
   • 公网: https://msgchain.org/whitepaper/module_exports/{module_stem}.json
   • 包含结构化元数据: status, status_label, group, group_label, code_refs, evidence_refs, boundary_clauses
2. 模块 HTML 页面: modules/{filename}
   • 公网: https://msgchain.org/whitepaper/modules/{filename}
   • 权威叙事来源

Step 5: 回答时携带边界声明

最终回答必须包含:

• 直接答案
• 当前状态 (status / status_label)
• 实现边界
• 必要时引用白皮书链接

2.1.1 单步执行示例

假设用户问 "MSG 的发行规则是什么"：

Step 1: 读取 agent_entry.json
  → 发现 crawl_contract, public_base_url = https://msgchain.org/whitepaper/
  → 发现 retrieval_hints 路径 = retrieval_hints.json

Step 2: 读取 retrieval_hints.json
  → 查找 topics[].questions, 匹配 "MSG 的发行规则是什么"
  → 命中 topic_id = "economics", title = "经济模型与发行结算"
  → recommended_chunks 前两条:
    - module_chunks/economy__chunk_01.json
    - module_chunks/emission__chunk_01.json
  → recommended_modules 前两条:
    - modules/economy.html (implemented)
    - modules/emission.html (implemented)

Step 3: 拉取 economy__chunk_01.json
  → 内容包含: "🔍 铁证: 发行与结算主规则"
               "🔍 铁证: Gas 分账与金库口径"
               "🔍 验收: 经济模型 raw 证据清单"
  → chunk 足够回答 → 不继续拉取模块

Step 4: 不走 (chunk 已够)

Step 5: 回答
  直接答案: MSG 的发行采用双池结算模型...
  当前状态: ✅ 已实现 (economy 模块)
  边界: 当前口径基于白皮书机器层,主网实际发行参数以链上配置为准
  推荐: https://msgchain.org/whitepaper/module_chunks/economy__chunk_01.json

2.1.2 Chunk 不足时的升级路径

假设 chunk 内容不完整（例如 chunk 只覆盖了流程图和铁证标题但没有完整数值参数）:

Step 3 (补充): 拉取 economy__chunk_02.json
  → 内容包含: "候选 inflow = emission * candidate qualified count / candidate economic denominator"
  → 数值参数已有,但仍不完整

Step 4: 拉取 module_exports/economy.json (模块导出)
  → 包含: status_label, group_label, evidence_refs, boundary_clauses
  → 确认模块证据边界

Step 4 (升级): 拉取 modules/economy.html (权威原文)
  → 完整的白皮书经济模型章节
  → 所有数值和逻辑的最终来源

2.2 agent_entry.json 发现机制

FAQ Router 第一步动作必须是读取 agent_entry.json。该文件是白皮书系统所有机器可读文件的单一起点。

爬取契约 (crawl_contract) 中的关键关联:

注意: crawl_contract 中申明了权威层级:
"Module HTML pages remain the authoritative narrative source; module_exports/*.json provide a machine-friendly derivative layer."

recommended_crawl_order 列出了 40+ 条推荐爬取路径,前几位为:

1. index.html
2. modules/knowledge_network.html
3. knowledge_network.json
4. module_exports/index.json
5. module_exports/by_group.json
6. module_exports/by_status.json
7. module_chunks/index.json
8. retrieval_hints.json
9. product_delivery_entry.json
10. developer_entry.json

2.3 retrieval_hints.json 主题映射

8 个主题的完整列表:

2.3.1 answering_guidance 通用指导

每个主题在 retrieval_hints.json 中都包含 answering_guidance 字段,值为三条通用指导:

"answering_guidance": [
  "先回答当前已实现或已证实的部分，再明确未完成边界。",
  "若涉及经济、治理、Explorer 或 live/public 结论，优先引用带 evidence_refs 与 boundary_clauses 的模块或 chunk。",
  "不要把 partial、planned 或本地子门禁关闭偷换成主网 ready。"
]

FAQ Router 必须无条件遵守此指导。

2.3.2 主题路由边界情况

无匹配: 如果用户问题未命中任何 topics[].questions,回退到:

1. 用 preferred_tags 做模糊匹配
2. 仍无匹配 → 返回"当前白皮书机器层未覆盖此问题"或引导至 knowledge_network.json 全量搜索

多主题命中: 如果问题同时命中多个 topic_id（例如 "MSG 的发行对验证者有什么影响" 同时涉及 economics 和 consensus_validator）:

1. 优先选择与问题关键词最匹配的主题
2. 在回答中交叉引用另一个主题的模块
3. 在"推荐参考"中同时提供两个主题的模块 URL

2.4 Chunk vs Export vs Module HTML 层级

数据读取优先级:

第一优先: Chunk (最快检索,适合常见 FAQ)
  ├─ 位置: module_chunks/{stem}__chunk_{no}.json
  ├─ 包含: 铁证块、流程图、原始证据片段
  └─ 限制: 仅覆盖模块的部分段落

第二优先: Module Export (结构化元数据)
  ├─ 位置: module_exports/{stem}.json
  ├─ 包含: 完整状态标签、证据引用、边界条款
  └─ 限制: 不含完整原文

第三优先: Module HTML (权威原文)
  ├─ 位置: modules/{filename}.html
  ├─ 包含: 完整白皮书模块原文
  └─ 特性: 唯一权威来源

当前系统共有 65 个模块 (module_chunks/index.json 中的 module_count: 65)。

3. 硬性规则

3.1 不得宣称主网就绪

规则原文: "Do not claim mainnet ready unless the retrieved content explicitly supports that conclusion."

FAQ Router 在白皮书机器层内运行,只能基于已检索内容做结论。任何声称主网（mainnet）就绪的断言,必须满足:

• 检索到的模块或 chunk 明确包含 status: "implemented" 且 status_label: "已实现"
• 检索内容中存在明确的 evidence_refs 指向主网开发参考级证据
• 不存在未解决的 boundary_clauses 否定该结论

不得:

• 将 partial（部分实现）解释为"大部分可用"
• 将 planned（规划态）解释为"即将上线"
• 将本地子门禁（local gate）关闭解释为主网 ready

3.2 Partial / Planned 边界处理

所有模块在 module_exports/index.json 中拥有明确的 status 和 status_label:

Partial 处理示例:

• AI Agent 模块 (ai_agent.html): status = partial, status_label = 部分实现
• 回答必须: "当前 Agent API 的只读查询面已经真实存在（查询、事件、钱包、MPC）,但部分高级写路径（DeFi、Bridge、Registry 写接口）目前仍是路由保护模式下的 Stub 预留接口,不得写成'全部实装'。"

Planned 处理示例:

• AI Registry 市场层 (ai_registry_market.html): status = planned, status_label = 规划态
• 回答必须: "agent / model / dataset / compute / task 市场目前属于规划态。当前可复用的底座包括 genesis registry v1（canonical key / active address 语义）和 economy / foundation（gas、结算与 treasury 规则）,但完整的市场层尚未上线。"

3.3 敏感主题的边界条款

agent_entry.json 中定义了三条全局边界声明 (current_boundaries):

[
  "白皮书系统适合机器遍历，但模块结论仍必须服从原始证据边界。",
  "implemented 或 partial 只表示当前白皮书口径，不自动等于 MSG 主网 ready。",
  "涉及经济、治理、NAT、Explorer、DAO live/public 的结论，必须继续区分本地子门禁与真实生产证据。"
]

对于以下主题,回答时必须包含至少一条边界条款 (boundary clause):

3.4 各状态的实际回答策略矩阵

3.5 证据薄弱时的处理

规则原文: "If evidence is weak or missing, say that the current whitepaper machine layer does not prove the claim."

所有 module_exports/index.json 中的模块都包含以下字段用于评估证据强度:

• code_ref_count: 源代码引用数量
• evidence_ref_count: 证据引用数量
• boundary_clause_count: 边界条款数量

回答策略:

1. 如果 evidence_ref_count 为 0,且 boundary_clause_count 较高: 优先引用模块 HTML 原文
2. 如果检索结果不存在对应证据: 明确声明"当前白皮书机器层无法证明该断言"
3. 如果用户问题超出白皮书范围: 回答"该问题超出了当前白皮书机器层的覆盖范围"

4. 回答格式模板

4.1 标准回答格式

Preferred answer format (来自 faq_router_prompt_template.md):

- Direct answer
- Current status
- Boundaries
- If needed: recommended whitepaper link

中文标准化版本:

- 直接答案: [用 1-2 句话直接回答用户问题]
- 当前状态: [status / status_label, 基于检索到的模块或 chunk]
- 边界说明: [明确的实现边界,未完成的能力,证据限制]
- 推荐参考: [如有必要,附上白皮书模块或 chunk 的 URL]

4.2 状态标签格式

状态标签直接复制自 module_exports/*.json 或 retrieval_hints.json 中的 status_label 字段。

4.3 边界条款格式

边界条款应引用模块 boundary_clauses 中的原始表述,或使用以下标准化句式:

经济/治理边界句式:

边界: 当前经济模型的 {部分} 已经实现并具备证据,但 {另一部分} 仍处于 {status_label},
       不得将本地子门禁解释为主网 ready。

AI Agent 边界句式:

边界: AI Agent 的查询/事件/钱包面已经真实存在,但 {写路径/治理/DeFi} 接口仍属
       Stub 或预留状态,不得宣称全部实装。

Explorer/Indexer 边界句式:

边界: Explorer/Indexer 的本地子门禁已补强并通过 preflight,但 live/public 端点
       仍未部署完成,非开发参考级证据不得替代主网验收。

通用弱证据句式:

边界: 当前白皮书机器层中,该话题对应的模块 {module_name} 的 evidence_ref_count 为 {n},
       尚不足以独立证明该断言。建议以下游权威 HTML 页面为准。

4.4 白皮书链接引用

推荐引用格式:

- 参考: 白皮书 {module_title} 模块
  - HTML: https://msgchain.org/whitepaper/modules/{filename}
  - Export: https://msgchain.org/whitepaper/module_exports/{module_stem}.json
  - Chunk: https://msgchain.org/whitepaper/module_chunks/{module_stem}__chunk_{no}.json

引用原则:

• FAQ 场景优先引用 Chunk URL（篇幅短、聚焦快）
• 深入场景优先引用模块 Export URL（结构化元数据完整）
• 权威确认场景优先引用模块 HTML URL（原始原文）

4.5 完整回答示例

示例 1: 已实现能力

用户: MSG 的出块时间是多少？
直接答案: MSG Chain 的区块目标间隔为 5 秒/块 (block time = 5s)。
当前状态: ✅ 已实现 (consensus 模块)
边界: 5 秒目标出块时间已在白皮书机器层中明确记录,但实际出块时间受网络状况、
      验证者调度和 DAR 评分影响,生产环境应以链上观测值为准。
推荐参考:
  - Chunk: https://msgchain.org/whitepaper/module_chunks/consensus__chunk_01.json
  - HTML: https://msgchain.org/whitepaper/modules/consensus.html

示例 2: 部分实现能力

用户: MSG 的 Explorer 支持哪些查询？
直接答案: MSG Chain 的本地 Explorer 子门禁已支持合约 source/interface/wasm metadata 查询、
          source verification state 查询、以及事件日志过滤。
当前状态: ⚠️ 部分实现 (Explorer 模块)
边界: 以上能力属于本地子门禁已补强的范围。live/public Explorer 端点仍待部署,
      且 eth_getLogs 和 WS logs 的支持程度需以实际端点返回为准。开发参考级查询
      仍需通过全节点 RPC /JSON-RPC /REST /gRPC 接口进行。
推荐参考:
  - Chunk: https://msgchain.org/whitepaper/module_chunks/explorer__chunk_01.json
  - Export: https://msgchain.org/whitepaper/module_exports/explorer.json

示例 3: 规划态能力

用户: MSG 的跨链桥怎么用？
直接答案: MSG Chain 的跨链桥接与互操作能力目前属于规划态。
当前状态: 🕐 规划态 (crosschain 模块)
边界: 当前白皮书机器层中尚无跨链桥的开发参考级实现证据。crosschain.html 模块
      的 status 为 "planned",表示此能力仍处于规划阶段,不可作为已实装功能
      使用。合约优先迁移路径涉及桥接适配器的边界也在 web3_contract_first_protocols
      模块中有初步讨论,但同样未实现。
推荐参考: (无已实现模块可推荐)

5. FAQ 场景示例

5.1 "What is MSG Chain?"

直接答案: MSG Chain (Micro Secure Grid) 是一个抗量子（Post-Quantum）安全的分
          布式治理网格。它采用 Round-Robin + DAR 共识机制和 Dilithium-5 后量
          子签名,以 5 秒/块的目标出块时间运行。
当前状态: ✅ 已实现。共识引擎 (consensus.html)、抗量子签名 (quantum.html)、
          P2P 组网 (p2p.html) 等核心模块均为 "implemented" 状态。
边界: MSG Chain 官方描述为 "The Quantum-Safe Mesh for Decentralized Governance",
      白皮书机器层覆盖了已实现的核心机制和部分实现/规划态的 AI 与生态扩展能力。
      当前声明的是白皮书机器层口径,不完全等价于主网所有功能已生产就绪。
推荐参考:
  - HTML: https://msgchain.org/whitepaper/modules/executive_summary.html
  - HTML: https://msgchain.org/whitepaper/modules/overview.html

5.2 "How do I deploy a contract?"

直接答案: MSG Chain 使用 CosmWasm 作为智能合约引擎。部署流程遵循标准的
          StoreCode → Instantiate → Execute → Query 管道。开发者需要使用
          MSG SDK (@msg-chain/sdk, 当前版本 0.1.0-alpha) 或直接通过
          RPC /JSON-RPC /REST /gRPC 接口与链交互。
当前状态: ✅ 合约引擎已实现 (contract.html, status: "implemented")
          ⚠️ SDK 部分实现 (sdk_dev_surface.html, status: "partial")
边界: 合约引擎 (StoreCode / Instantiate / Execute / Query / Migrate) 已在白
      皮书机器层中记录为已实现。SDK 当前为 alpha 版本 (0.1.0-alpha),尚未发布
      public signed release。推荐开发顺序请参考 developer_entry.json 中的
      recommended_contract_bootstrap_order。
推荐参考:
  - Export: https://msgchain.org/whitepaper/module_exports/contract.json
  - Recipe: https://msgchain.org/whitepaper/recipes/contract_minimal.json
  - SDK: https://msgchain.org/whitepaper/module_exports/sdk_dev_surface.json

5.3 "Can AI agents control the treasury?"

直接答案: 当前阶段的 AI Agent 不可以完全自主控制金库。基金会金库 (foundation
          treasury v2) 受 DAO 和 DAR 双约束,高价值执行需要满足多签阈值和
          timelock 冷静期要求。AI Agent 可以通过 Agent API 进行查询和部分
          受限操作,但不能绕过 DAO 治理和资金门禁。
当前状态: ✅ 金库与治理已实现 (foundation.html + dao.html, status: "implemented")
          ⚠️ AI Agent 部分实现 (ai_agent.html, status: "partial")
边界: AI 控制平面当前真实存在的是 /agent/v1/query/ 系列只读端点、
      /agent/v1/events/ 事件面和 /agent/v1/wallet/ 局部写操作。
      治理写入 (governance/create / vote / execute)、验证者管理、
      合约执行的高风险路径仍需要人类审批。AI 不得：
      1. 绕过 DAO 治理门禁执行金库操作
      2. 在 timelock 未结束时强制执行
      3. 绕过多签阈值执行高价值交易
      4. 将 Stub 写路径 (DeFi / Bridge / Registry 写接口) 伪装为实装
推荐参考:
  - HTML: https://msgchain.org/whitepaper/modules/ai_control_plane.html
  - HTML: https://msgchain.org/whitepaper/modules/foundation.html
  - HTML: https://msgchain.org/whitepaper/modules/dao.html
  - Export: https://msgchain.org/whitepaper/module_exports/ai_agent.json
  - Export: https://msgchain.org/whitepaper/module_exports/ai_policy_capability.json

5.4 "Is the testnet live?"

直接答案: 当前白皮书机器层中没有明确说明 testnet 是否已公开上线。链状态通过
          全节点 RPC 接口可查,但这是本地可运行节点的能力,不自动等于公开
          testnet 已开放。
当前状态: ⚠️ 部分实现模式。共识与节点启动（genesis startup / quantum startup /
          dual_node_startup_topology）已被记录为 "implemented",但 explorer 和
          公开测试网入口被标记为 "partial"。
边界: 白皮书中的 {implemented 或 partial} 只表示当前白皮书口径,不自动等于
      MSG 主网或 testnet ready。explorer 模块的边界明确写道: "live/public
      Explorer 仍需部署"。要确认 testnet 的公开可用性,建议直接参考官方
      Explorer 页面或开发者入口的最新公告。
推荐参考:
  - HTML: https://msgchain.org/whitepaper/modules/dual_node_startup_topology.html
  - HTML: https://msgchain.org/whitepaper/modules/explorer.html
  - Export: https://msgchain.org/whitepaper/module_exports/explorer.json

5.5 更多场景速查表

6. 工具调用集成

6.1 Telegram Bot 集成

参考文件: integration_examples/telegram_bot_crawl_flow.json
公网 URL: https://msgchain.org/whitepaper/integration_examples/telegram_bot_crawl_flow.json

推荐流程:

Step 1: load_agent_entry
  读取: ../agent_entry.json
  用途: 发现当前稳定机器入口、公网 URL 映射和爬取顺序

Step 2: route_question
  读取: ../retrieval_hints.json
  用途: 将用户问题匹配到最相关的 topic_id

Step 3: fetch_recommended_chunks
  读取: topics[*].recommended_chunks (前 2-4 条)
  用途: 获取快速回答上下文

Step 4: fetch_recommended_modules_if_needed
  读取: topics[*].recommended_modules
  用途: 在 chunk 不足时拉取完整模块证据

Step 5: answer_with_boundaries
  输入: boundary_clauses + evidence_refs + status/status_label
  用途: 返回带边界声明的回答

回复策略 (来自 telegram_bot_crawl_flow.json):

{
  "reply_policy": [
    "Prefer implemented modules over partial or planned modules when both address the same question.",
    "If only partial or planned material exists, say so explicitly.",
    "For economics, governance, Explorer, and live/public claims, include at least one boundary clause.",
    "If the question is operationally sensitive, point the user to the authoritative module HTML page."
  ]
}

示例路由 (来自 telegram_bot_crawl_flow.json):

{
  "question": "MSG 的发行规则是什么",
  "topic_id": "economics",
  "first_fetch": [
    "../retrieval_hints.json",
    "../module_chunks/economy__chunk_01.json",
    "../module_chunks/emission__chunk_01.json"
  ]
}

Fallback 顺序 (精确定义):

1. retrieval_hints.json
2. module_exports/by_group.json
3. module_exports/by_status.json
4. module_chunks/index.json
5. knowledge_network.json

6.2 多轮对话与上下文保持

在 Telegram / Discord 场景中,FAQ Router 可能需要保持多轮对话上下文。建议的上下文管理:

会话上下文结构:
{
  "session_id": "uuid",
  "history": [
    { "role": "user", "question": "MSG 的发行规则是什么" },
    { "role": "assistant", "topic": "economics", "modules": [...], "answer": "..." }
  ],
  "current_topic": "economics",
  "last_modules": ["economy.html", "emission.html"]
}

上下文复用规则:

1. 用户新提问时,优先在当前 last_modules 和 current_topic 中检索
2. 如果匹配失败,再回退到检索整个 retrieval_hints.json
3. 当用户说"继续"、"详细说"、"还有呢"时,拉取当前推荐模块的更多 chunk
4. 当用户问完全不相关的主题时,清除上下文,重新从 Step 1 开始

6.3 Discord Bot 集成

Discord 机器人集成需先核验后使用 Telegram Bot 的流程框架,仅以下差异:

建议将 retrieval_hints.json 中的 8 个主题作为 Discord Bot 斜杠命令的子选项:

/ask topic:economics "MSG 的发行规则是什么"
/ask topic:consensus_validator "DAR 如何工作"
/ask topic:ai_agent_runtime "Agent API 能做什么"

6.4 开发者聊天集成

开发者聊天助手（Developer Chat Bot）需要额外集成 developer_entry.json 中的开发路径:

文件路径:

• https://msgchain.org/whitepaper/developer_entry.json
• https://msgchain.org/whitepaper/developer_capability_matrix.json
• https://msgchain.org/whitepaper/quickstart/contract_and_dapp_minimal.json

开发任务处理流:

Step 1: 加载 agent_entry.json → developer_entry.json
Step 2: 根据任务类型选择引导路径
   - 合约开发: recommended_contract_bootstrap_order
   - dApp 开发: recommended_dapp_bootstrap_order
   - 全生命周期: recommended_full_lifecycle_order
Step 3: 读取对应 Recipe
   - 合约: recipes/contract_minimal.json
   - dApp: recipes/dapp_minimal.json
Step 4: 读取 contract_reference 和 api_specs 获取技术细节
Step 5: 生成代码 + 测试 + 部署计划 + 回执验证
Step 6: 需要签名/部署/资金/治理时要求人类审批

硬性规则: 来自 external_ai_agent_bootstrap_prompt.json

{
  "hard_rules": [
    "Always start from agent_entry.json.",
    "Use developer_entry.json for coding tasks.",
    "Use retrieval_hints.json for topic routing and question answering.",
    "Treat modules/*.html as the authoritative narrative layer.",
    "Do not upgrade partial, planned, local-only closeout, or guarded slices into production-complete claims.",
    "Require human approval for signing, deployment, treasury, governance, domain, CI/CD, production release, and money-moving actions."
  ]
}

6.5 Web Widget 集成

网站 FAQ 路由 Widget 可以看作免安装的 HTTP 版本 FAQ Router。

最小前端架构:

<!-- FAQ 输入框 -->
<input id="faq-input" placeholder="输入你的问题..." />

<!-- 后台处理 -->
FAQ Widget → HTTP → Backend Service → 读取 agent_entry.json
                                     → 读取 retrieval_hints.json
                                     → 路由topic_id
                                     → 拉取 Chunk / Export / HTML
                                     → 格式化回答 + 边界声明
                                     → 返回前端

后端可用 JSON 入口 (读取后缓存可大幅提升响应速度):

API 设计建议:

POST /api/faq/ask
Request:  { "question": "MSG 的发行规则是什么" }
Response: {
  "answer": "...",
  "status": "已实现",
  "boundary": "...",
  "sources": [
    { "type": "chunk", "url": "https://msgchain.org/whitepaper/module_chunks/economy__chunk_01.json" },
    { "type": "export", "url": "https://msgchain.org/whitepaper/module_exports/economy.json" }
  ]
}

GET /api/faq/topics
Response: {
  "topics": [
    { "topic_id": "economics", "title": "经济模型与发行结算", "questions": [...] },
    { "topic_id": "consensus_validator", "title": "共识、DAR 与验证者资格", "questions": [...] },
    ...
  ]
}

6.6 RAG 集成参考

如果 FAQ Router 需要接入向量检索（RAG）,建议参考 rag_ingest_flow.json:

批量摄入流程:

Step 1: load_manifest (whitepaper_manifest.json)
Step 2: load_module_index (module_exports/index.json)
Step 3: load_chunk_index (module_chunks/index.json)
Step 4: ingest_chunk_documents (module_chunks/*.json)
Step 5: ingest_module_documents (module_exports/*.json)
Step 6: attach_boundaries (保留 boundary_clauses + evidence_refs)

推荐元数据字段:

[
  "module_filename", "module_title", "status", "status_label",
  "group", "group_label", "tags", "chunk_id",
  "module_public_url", "chunk_public_url",
  "evidence_refs", "boundary_clauses"
]

重排序策略:

1. Topic hints from retrieval_hints.json
2. Status priority: implemented > partial > planned
3. Shared tags
4. Group affinity

服务策略:

• 优先返回 chunk 级命中以保持回答简短
• 多 chunk 冲突时,优先证据更强、边界更明确的 chunk
• 始终链接回 module_public_url 提供完整上下文
• 避免用规划态模块作为实施类问题的主要证据

附录 D: FAQ Router 常用命令行测试

快速验证 FAQ Router 指向的文件是否可访问:

# 测试 agent_entry.json 是否可达
curl -sI https://msgchain.org/whitepaper/agent_entry.json | head -1

# 测试 retrieval_hints.json 主题数量
curl -s https://msgchain.org/whitepaper/retrieval_hints.json | jq '.topic_count'

# 测试模块总数
curl -s https://msgchain.org/whitepaper/module_exports/index.json | jq '.module_count'

# 测试 chunk 索引是否加载
curl -s https://msgchain.org/whitepaper/module_chunks/index.json | jq '.items | length'

# 获取所有 implemented 模块列表
curl -s https://msgchain.org/whitepaper/module_exports/by_status.json | jq '.implemented'

# 获取经济模块的边界条款数
curl -s https://msgchain.org/whitepaper/module_exports/index.json | jq '.items[] | select(.filename=="economy.html") | {filename, status, boundary_clause_count}'

这些端点返回 JSON 且不要求认证,适合部署为 CI 检查。

附录 E: agent_entry.json crawled_fields 关系图

agent_entry.json (crawl_contract)
    │
    ├── primary_seed: knowledge_network.json
    │   └── entries[*].filename → modules/{filename}.html
    │
    ├── retrieval_hints: retrieval_hints.json
    │   └── topics[*].recommended_modules → modules/{filename}.html
    │   └── topics[*].recommended_chunks → module_chunks/{stem}__chunk_{no}.json
    │
    ├── module_export_index: module_exports/index.json
    │   └── items[].filename → module_exports/{stem}.json
    │
    ├── module_chunk_index: module_chunks/index.json
    │   └── items[].chunks[].chunk_url → module_chunks/{stem}__chunk_{no}.json
    │
    ├── module_export_template: module_exports/{module_stem}.json
    ├── module_chunk_template: module_chunks/{module_stem}__chunk_{chunk_no}.json
    │
    └── fallback (telegram_bot_crawl_flow.json):
        1. retrieval_hints.json
        2. module_exports/by_group.json
        3. module_exports/by_status.json
        4. module_chunks/index.json
        5. knowledge_network.json

附录 A: 关键文件引用表

附录 B: 模块状态速查

来自 module_exports/index.json (共 65 个模块):

附录 C: Telegram Bot 完整样例代码

# 伪代码示例: MSG Chain FAQ Telegram Bot
import json, requests

BASE = "https://msgchain.org/whitepaper"

def handle_faq(question: str) -> dict:
    # Step 1: Load agent_entry.json
    entry = requests.get(f"{BASE}/agent_entry.json").json()
    crawl = entry["crawl_contract"]

    # Step 2: Route question via retrieval_hints.json
    hints = requests.get(f"{BASE}/{crawl['retrieval_hints']}").json()
    topic = route_question(question, hints["topics"])

    if topic is None:
        return {"answer": "当前白皮书机器层未覆盖此问题", "status": "unknown"}

    # Step 3: Fetch first 2 chunks
    chunks = topic["recommended_chunks"][:2]
    chunk_texts = []
    for c in chunks:
        resp = requests.get(c["chunk_public_url"])
        if resp.status_code == 200:
            chunk_texts.append(resp.json())

    # Step 4: If insufficient, fetch module export
    if not sufficient(chunk_texts, question):
        mod = topic["recommended_modules"][0]
        export = requests.get(mod["export_public_url"]).json()
        # use export data

    # Step 5: Answer with boundaries
    status = topic["recommended_modules"][0]["status_label"]
    answer = format_answer(chunk_texts, question, status)
    return answer

版本说明

• 本文档基于 msgchain.org 白皮书系统的实时文件编写
• 关键引用文件: agent_entry.json (schema_version v1), retrieval_hints.json (topic_count 8), module_exports/index.json (module_count 65), module_chunks/index.json
• 所有状态标签、边界条款、证据引用均来自白皮书机器层实际内容
• 本指南本身不构成 MSG Chain 的官方文档,仅为技术整合参考