AI Agent 白皮书清单与知识网络指南

基于 MSG Chain 官方 whitepaper_manifest.json 和 knowledge_network.json
链标识: msg-chain-1 | Bech32 前缀: msg
生成管道: msg_whitepaper_pipeline_v1
元数据画像: public_stable
文档版本: 2026-07

⚠️ No-Go Disclaimer: MSGChain 主网裁决为 No-Go。本文件所有内容反映的是开发阶段的技术设计，不代表主网未独立核验上线状态。生产部署状态请以白皮书为准：https://msgchain.org/whitepaper/

1. 概述

MSG Chain 白皮书机器层维护了两份核心结构化文件，它们是 AI Agent 理解白皮书系统全貌的关键起点：

这两个文件与 agent_entry.json 一起构成了白皮书机器层的"三核心入口三角"：

agent_entry.json ──── crawl_contract ──── primary_seed: knowledge_network.json
       │
       ├── entry_points ──── whitepaper_manifest.json
       ├── entry_points ──── knowledge_network.json
       └── entry_points ──── knowledge_network_html

whitepaper_manifest.json 提供的是静态快照——当前版本下白皮书生成了哪些文件、各目录的结构是什么。knowledge_network.json 提供的是语义关联——模块之间如何连接、读者/爬虫可以按什么路径遍历。

两条核心限制贯穿全文：

• 本指南所述内容基于 msg-chain-1 链的白皮书机器层。所有地址均使用 msg 前缀的 bech32 编码。
• 模块的 implemented 或 partial 状态仅表示白皮书口径，不自动等于 MSG 主网生产就绪。

2. whitepaper_manifest.json 的作用

2.1 文件定位

whitepaper_manifest.json 是白皮书系统的全局清单文件。它由 msg_whitepaper_pipeline_v1 管道在每次白皮书更新时自动生成，记录了当前白皮书版本的全部机器可读资源的清单和索引结构。

与 agent_entry.json 不同，whitepaper_manifest.json 不定义"如何爬取"（那是 crawl_contract 的职责），而是定义"生成了什么"——相当于白皮书机器层的文件系统目录表。

2.2 Schema 版本追踪

文件顶部的 schema_version 字段是 AI Agent 进行版本判断的首要依据：

{
  "schema_version": "v1",
  "generated_by": "msg_whitepaper_pipeline_v1",
  "module_count": 65,
  "metadata_profile": "public_stable"
}

schema_version 的作用：

• 版本锚点：AI Agent 在缓存白皮书数据时，应记录 schema_version。当检测到版本变更时，触发全量或增量刷新。
• 管线溯源：generated_by 标明数据来源管道，当 Agent 发现某条信息与预期不符时，可通过此字段追踪生成线索。
• 元数据画像：metadata_profile 当前为 public_stable，表示这是一个稳定的公开版本。未来可能出现 beta、draft 等画像，AI Agent 应根据画像调整可信度阈值。

版本检测示例：

import httpx

MANIFEST_URL = "https://msgchain.org/whitepaper/whitepaper_manifest.json"
CACHED_VERSION = None  # 从持久化存储读取

async def check_version_changed() -> bool:
    global CACHED_VERSION
    async with httpx.AsyncClient() as client:
        resp = await client.get(MANIFEST_URL)
        manifest = resp.json()
        current = manifest["schema_version"]
        if CACHED_VERSION and CACHED_VERSION != current:
            print(f"版本变更: {CACHED_VERSION} -> {current}")
            CACHED_VERSION = current
            return True
        CACHED_VERSION = current
        return False

2.3 模块列表与版本快照

module_count: 65 记录了当前白皮书包含的模块总数。当此数字发生变化时，意味着有模块被新增或移除。

清单还提供了模块导出的完整结构：

"module_exports": {
    "directory": "module_exports/",
    "index": "module_exports/index.json",
    "by_group": "module_exports/by_group.json",
    "by_status": "module_exports/by_status.json",
    "item_template": "module_exports/{module_stem}.json",
    "authoritative_body": "Each module JSON is derived from the generator source text for the corresponding module page."
}

这意味着 AI Agent 可以通过 module_exports/index.json 获取所有模块的摘要，通过 module_exports/{module_stem}.json 获取单个模块的结构化导出。每个导出文件都是从对应模块 HTML 页面自动推导的机器友好衍生层。

如果 Agent 按 group 筛选（如只关注 AI 相关模块），应读取 module_exports/by_group.json；如果按 status 筛选（如只关注已实现模块），应读取 module_exports/by_status.json。

2.4 分块配置

对于需要 RAG 摄取的场景，whitepaper_manifest.json 提供了关键的分块元数据：

"module_chunks": {
    "directory": "module_chunks/",
    "index": "module_chunks/index.json",
    "item_template": "module_chunks/{module_stem}__chunk_{chunk_no}.json",
    "chunk_target_size": 900,
    "chunk_overlap_size": 120,
    "authoritative_body": "Chunk files are machine-friendly segment derivatives for retrieval, citation, and RAG ingestion."
}

重要参数说明：

• chunk_target_size: 900：每个分块的目标文本长度（字符数）。AI Agent 在设置 RAG 管道的分块器参数时，可以以此值为参考。
• chunk_overlap_size: 120：相邻分块之间的重叠字符数。确保跨分块的上下文不被切断。
• 命名规则：{module_stem}__chunk_{chunk_no}.json，其中 chunk_no 是零填充的两位数编号。

这些参数让 AI Agent 无需自行决定分块策略——直接以机器层分块作为 RAG 的原始文档单元即可。

2.5 生成时间戳与变更追踪

虽然当前版本的 whitepaper_manifest.json 不包含显式的时间戳字段，但 AI Agent 可以通过 HTTP 响应的 Last-Modified 或 ETag 头部来追踪变更：

async def check_manifest_last_modified() -> str | None:
    async with httpx.AsyncClient() as client:
        resp = await client.head(MANIFEST_URL)
        return resp.headers.get("last-modified")

当 last-modified 变化时，AI Agent 应触发：

1. 重新读取 whitepaper_manifest.json
2. 对比 module_count 是否变化
3. 按需重新摄取 module_chunks 目录下的所有分块文件

2.6 如何用于增量同步

whitepaper_manifest.json 是增量同步的最佳起点。建议的同步流程如下：

Step 1: 读取本地缓存的 schema_version 和 last-modified
Step 2: HEAD 请求 whitepaper_manifest.json，获取当前 last-modified
Step 3: 如果未变更 → 跳过同步
        如果已变更 → 继续
Step 4: GET whitepaper_manifest.json，获取完整清单
Step 5: 对比 module_count 是否变化
        - 如果增加 → 新增模块，读取新模块的导出和分块
        - 如果减少 → 从向量库中移除已删除模块的索引
        - 如果不变 → 仅更新入口点结构和分块配置
Step 6: 读取 module_chunks/index.json，与本地分块索引对比
Step 7: 对每个新的或变更的分块执行重新摄取

async def incremental_sync(
    client: httpx.AsyncClient,
    local_cache: dict,
) -> dict:
    head_resp = await client.head(MANIFEST_URL)
    remote_modified = head_resp.headers.get("last-modified", "")
    local_modified = local_cache.get("last_modified", "")

    if remote_modified == local_modified and local_cache.get("schema_version") == "v1":
        print("Manifest 未变更，跳过同步")
        return local_cache

    manifest = (await client.get(MANIFEST_URL)).json()
    local_cache["schema_version"] = manifest["schema_version"]
    local_cache["last_modified"] = remote_modified
    local_cache["module_count"] = manifest["module_count"]
    local_cache["manifest"] = manifest

    # 读取最新的分块索引
    chunk_index = (await client.get(
        "https://msgchain.org/whitepaper/module_chunks/index.json"
    )).json()
    local_cache["chunk_count"] = len(chunk_index.get("chunks", []))

    return local_cache

3. knowledge_network.json 的作用

3.1 文件定位

knowledge_network.json 是白皮书系统的知识图谱文件。它记录了 65 个模块之间的所有语义关联：每个模块引用了哪些其他模块（outlinks）、哪些其他模块引用了它（backlinks）、以及基于内容相似度推荐的相邻模块（related）。

该文件在 agent_entry.json 中被指定为 crawl_contract.primary_seed，意味着它是白皮书爬取流程的首要种子文件。

3.2 模块之间的出链/回链/相邻推荐关系

knowledge_network.json 的 entries 对象包含每个模块的完整关系数据。以 overview.html 为例：

"overview.html": {
    "filename": "overview.html",
    "title": "白皮书总拓扑母图",
    "status": "audit",
    "status_label": "审计页",
    "group": "audit",
    "group_label": "审计与证据",
    "tags": ["金库", "多签", "阈值", "治理", "时间锁", "提案", "注册中心", "规范键"],
    "outlinks": [
        "ai_agent.html", "ai_registry_market.html", "ai_task_l2.html",
        "ai_validator_autonomy.html", "ai_world_computer_roadmap.html",
        "ai_value_flow.html", "ai_control_plane.html", "ai_wallet.html",
        "ai_policy_capability.html", "ai_governance_autonomy.html",
        "agent_api_surface.html", "block01_contract_topology.html",
        "dao.html", "dual_node_startup_topology.html",
        "indexer_data_plane.html", "l1_l2_architecture.html",
        "rpc.html", "sdk_dev_surface.html", "world_computer.html",
        "txpool.html", "proof_map.html", "consensus.html",
        "registry.html", "genesis_startup.html", "evidence_gallery.html",
        "credibility.html", "proof_chain.html", "foundation.html",
        "security_overview.html", "storage.html", "scaling_cost.html",
        "quantum.html", "contract.html", "review_playbook.html",
        "keplr.html", "explorer.html", "topology_export.html",
        "executive_summary.html", "economy.html", "observability_monitoring.html",
        "evidence_strength.html", "evidence_index.html", "slashing.html",
        "crosschain.html", "emission.html", "blockchain.html",
        "code_dependency.html"
    ],
    "backlinks": [
        "dao.html", "world_computer.html", "proof_map.html",
        "registry.html", "topology_onepage.html", "credibility.html",
        "proof_chain.html", "trust_verdict.html", "foundation.html",
        "taskflow_entry.html", "review_playbook.html", "topology_export.html",
        "executive_summary.html", "economy.html", "role_paths.html",
        "evidence_index.html", "evidence_coverage.html", "slashing.html",
        "emission.html", "code_dependency.html"
    ],
    "related": [
        "proof_map.html", "credibility.html", "proof_chain.html",
        "review_playbook.html", "topology_export.html",
        "executive_summary.html", "evidence_index.html", "dao.html"
    ]
}

三个关系字段的含义：

三类关系的数据量差异显著：审计页（如 overview.html）的 outlinks 密度极高（48 个），而孤立模块（如 crosschain.html）的 outlinks 为 0。这种拓扑差异反映了白皮书内容的成熟度——实现度越高的模块，其互联程度越高。

3.3 拓扑数据：出链数、回链数、相邻推荐数

AI Agent 可以将 knowledge_network.json 的拓扑数据进行量化分析，以判断模块的中心度和内容广度。

以几个典型模块为例：

拓扑数据分析方法：

def analyze_topology(knowledge_network: dict) -> dict:
    entries = knowledge_network.get("entries", {})
    results = {}
    for filename, meta in entries.items():
        outlinks = meta.get("outlinks", [])
        backlinks = meta.get("backlinks", [])
        related = meta.get("related", [])
        results[filename] = {
            "title": meta["title"],
            "status": meta["status"],
            "group": meta["group"],
            "outlink_count": len(outlinks),
            "backlink_count": len(backlinks),
            "related_count": len(related),
            "connectivity_score": len(outlinks) + len(backlinks),
            "is_isolated": len(outlinks) == 0 and len(backlinks) == 0,
            "is_hub": len(outlinks) > 30,
        }
    return results

拓扑数据的典型用途：

• 枢纽识别：overview.html、credibility.html、proof_map.html、trust_verdict.html 等审计页的出链数极高，适合作为知识遍历的起点。
• 孤立检测：crosschain.html（规划态）和 keplr.html（部分实现）的 outlinks 为零，说明这些模块尚未与其他模块建立内容引用关系，AI Agent 在使用这些模块时应降低其可信权重。
• 中心度排序：按 outlinks + backlinks 总和排序，可以得到白皮书模块的中心度排名，用于决定 RAG 检索时的优先级。

3.4 分类与状态元数据

每个模块在 knowledge_network.json 中都包含完整的分类和状态元数据：

{
    "status": "implemented | partial | planned | audit",
    "status_label": "已实现 | 部分实现 | 规划态 | 审计页",
    "status_class": "pill-implemented | pill-partial | pill-planned | pill-audit",
    "group": "control | runtime | funds | ai | developer | ecosystem | ops | audit",
    "group_label": "控制与治理 | 运行与状态 | 经济与资金 | AI 与自治 | 开发者与接口 | 生态与路线 | 启动与运维 | 审计与证据",
    "tags": ["金库", "多签", "阈值", ...]
}

3.4.1 Status（状态）

四个状态的语义和使用规则：

AI Agent 在引用模块时应遵循的优先级：implemented > partial > planned > audit。当多个模块包含同一主题的答案时，优先使用 implemented 模块的内容。

3.4.2 Group（分组）

八个分组覆盖白皮书的不同关注领域：

3.4.3 Tags（标签）

tags 字段提供模块的细粒度标记。当前白皮书使用的标签体系包含但不限于：

金库, 多签, 阈值, 治理, 时间锁, 提案, 注册中心, 规范键,
铸造, 奖励, 结算, 接口, 查询, P2P, 组网, NAT,
状态, 存储, 证据, 证明, 复核, 处罚, 挑战, 恢复,
SDK, 开发者, 安全, 抗量子, AI, Agent

标签的用途：

• RAG 路由辅助：当用户问题包含特定关键词时，通过标签匹配缩小检索范围
• 交叉分组合并：某些主题跨越多个分组（如"金库"出现在 control、funds、ai 等多个分组），标签提供横向关联
• 检索重排序：检索结果按与查询标签的匹配度重新排序

def rank_modules_by_tags(
    knowledge_network: dict, query_tags: list[str]
) -> list[tuple[str, int]]:
    entries = knowledge_network.get("entries", {})
    scores = []
    for filename, meta in entries.items():
        module_tags = meta.get("tags", [])
        overlap = len(set(query_tags) & set(module_tags))
        if overlap > 0:
            scores.append((filename, overlap))
    return sorted(scores, key=lambda x: x[1], reverse=True)

3.5 与 RAG 摄取的关系

knowledge_network.json 为 RAG 摄取提供了关键的语义关联层。标准的 RAG 管道通常只关注文本相似度，而知识网络提供了模块之间的结构关联。

3.5.1 语义关联的价值

当 AI Agent 回答一个问题时，仅依赖文本相似度的 RAG 检索可能遗漏重要的上下文。知识网络提供了三条补充路径：

1. 出链跟随：如果分块 A 提到"注册中心"，通过 knowledge_network.json 找到 registry.html 的 outlinks，可发现它关联到的合约引擎、共识模块等——即使这些模块的文本与查询不直接相似。

2. 回链溯源：如果分块 B 来自 economy.html，通过 backlinks 可找到哪些模块引用了经济模型（如 emission.html、slashing.html、overview.html），确保问题回答不遗漏上层依赖。

3. 相邻推荐：related 字段提供了基于内容编辑判断（而非纯文本相似度）的推荐关系，适合用作 RAG 结果的"扩展阅读"建议。

3.5.2 在向量库中存储关系数据

建议在 RAG 向量库中为每个模块存储以下知识网络元数据：

RAG_DOCUMENT_SCHEMA = {
    "id": "模块文件名（如 overview.html）",
    "title": "模块标题",
    "text": "模块的文本内容（来自分块或导出）",
    "status": "implemented | partial | planned | audit",
    "status_label": "状态中文标签",
    "group": "分组 ID",
    "group_label": "分组中文标签",
    "tags": ["标签数组"],
    "outlinks": ["出链目标数组"],
    "backlinks": ["回链来源数组"],
    "related": ["相邻推荐数组"],
    "outlink_count": 47,
    "backlink_count": 20,
    "connectivity_score": 67,
}

在检索时，这些关系字段可用于：

• 结果扩展：对检索命中的模块，跟随其 outlinks 和 related 获取更多上下文
• 结果过滤：排除 planned 或 outlink_count=0 的低可信度模块
• 结果重排序：按 connectivity_score 降序排列，中心度高的模块优先

async def retrieve_with_knowledge_network(
    client: httpx.AsyncClient,
    query: str,
    kn: dict,
    top_k: int = 5,
) -> list[dict]:
    entries = kn.get("entries", {})
    # 第一步：向量检索（伪代码）
    vector_results = await vector_search(query, top_k=top_k)

    # 第二步：使用知识网络扩展结果
    expanded = []
    seen = set()
    for result in vector_results:
        filename = result["filename"]
        if filename in seen:
            continue
        seen.add(filename)
        meta = entries.get(filename, {})
        result.update({
            "status": meta.get("status"),
            "group": meta.get("group"),
            "tags": meta.get("tags", []),
            "outlink_count": len(meta.get("outlinks", [])),
            "backlink_count": len(meta.get("backlinks", [])),
        })
        expanded.append(result)

        # 添加 related 模块（如果在 top_k 范围内）
        for rel in meta.get("related", []):
            if rel not in seen and len(expanded) < top_k + 3:
                seen.add(rel)
                rel_meta = entries.get(rel, {})
                expanded.append({
                    "filename": rel,
                    "title": rel_meta.get("title", ""),
                    "status": rel_meta.get("status"),
                    "group": rel_meta.get("group"),
                    "tags": rel_meta.get("tags", []),
                    "source": "knowledge_network_related",
                    "outlink_count": len(rel_meta.get("outlinks", [])),
                    "backlink_count": len(rel_meta.get("backlinks", [])),
                })

    # 第三步：按状态优先级排序
    status_priority = {"implemented": 0, "partial": 1, "planned": 2, "audit": 3}
    expanded.sort(key=lambda x: status_priority.get(x.get("status", "planned"), 99))

    return expanded[:top_k]

3.5.3 分块与知识网络的协同

whitepaper_manifest.json 定义了分块结构（chunk_target_size=900, chunk_overlap_size=120），knowledge_network.json 定义了模块关系。两者协同工作的流程：

RAG 摄取流程:
Step 1: 读取 whitepaper_manifest.json 获取分块配置
Step 2: 读取 module_chunks/index.json 枚举所有分块
Step 3: 读取 knowledge_network.json 获取关系数据
Step 4: 为每个分块注入所属模块的关系元数据
        ├── 分块文本 → 向量化
        ├── 模块 status → 过滤条件
        ├── 模块 outlinks/backlinks/related → 检索扩展
        └── 模块 tags → 路由辅助
Step 5: 写入向量库

4. AI Agent 如何消费这两个文件

4.1 Manifest 用于版本判断和增量更新

whitepaper_manifest.json 是 AI Agent 的"第一眼文件"——在开始任何白皮书消费操作前，应先检查 manifest 的版本状态。

4.1.1 启动时的版本判断

class WhitepaperConsumer:
    def __init__(self, cache_dir: str = ".whitepaper_cache"):
        self.cache_dir = cache_dir
        self.client = httpx.AsyncClient()
        self.manifest: dict | None = None
        self.knowledge_network: dict | None = None
        self.local_version: str | None = self._load_cached_version()

    def _load_cached_version(self) -> str | None:
        try:
            path = f"{self.cache_dir}/manifest.json"
            with open(path) as f:
                cached = json.load(f)
                return cached.get("schema_version")
        except (FileNotFoundError, json.JSONDecodeError):
            return None

    async def check_and_sync(self) -> bool:
        manifest = (await self.client.get(
            "https://msgchain.org/whitepaper/whitepaper_manifest.json"
        )).json()
        current_version = manifest["schema_version"]

        if self.local_version and self.local_version == current_version:
            if os.path.exists(f"{self.cache_dir}/knowledge_network.json"):
                return False  # 无需同步

        self.manifest = manifest
        self.local_version = current_version
        os.makedirs(self.cache_dir, exist_ok=True)
        with open(f"{self.cache_dir}/manifest.json", "w") as f:
            json.dump(manifest, f)
        return True  # 需要同步

    async def sync_knowledge_network(self) -> dict:
        kn = (await self.client.get(
            "https://msgchain.org/whitepaper/knowledge_network.json"
        )).json()
        self.knowledge_network = kn
        with open(f"{self.cache_dir}/knowledge_network.json", "w") as f:
            json.dump(kn, f)
        return kn

    async def close(self):
        await self.client.aclose()

4.1.2 增量更新的触发条件

以下条件应触发 AI Agent 执行增量更新：

4.1.3 与 agent_entry.json 的配合

whitepaper_manifest.json 和 agent_entry.json 在版本判断上的分工不同：

• agent_entry.json：定义爬取契约（crawl_contract）和推荐爬取顺序（recommended_crawl_order）
• whitepaper_manifest.json：定义文件清单和结构配置（分块大小、导出模板等）

AI Agent 应该先读取 agent_entry.json 获取爬取策略，再读取 whitepaper_manifest.json 获取文件清单：

async def bootstrap_whitepaper(client: httpx.AsyncClient) -> dict:
    # Step 1: 读取 agent_entry.json 获取爬取策略
    agent_entry = (await client.get(
        "https://msgchain.org/whitepaper/agent_entry.json"
    )).json()
    crawl_contract = agent_entry["crawl_contract"]

    # Step 2: 读取 whitepaper_manifest.json 获取文件清单
    manifest = (await client.get(
        "https://msgchain.org/whitepaper/whitepaper_manifest.json"
    )).json()

    # Step 3: 根据 crawl_contract 读取 primary seed
    seed_url = "https://msgchain.org/whitepaper/" + crawl_contract["primary_seed"]
    knowledge_network = (await client.get(seed_url)).json()

    return {
        "schema_version": manifest["schema_version"],
        "module_count": manifest["module_count"],
        "chunk_config": manifest["module_chunks"],
        "seed": knowledge_network,
        "taxonomy_fields": crawl_contract["taxonomy_fields"],
        "relation_fields": crawl_contract["relation_fields"],
    }

4.2 Knowledge Network 用于推荐最近模块和规划阅读路径

knowledge_network.json 是 AI Agent 进行语义导航的核心工具。它的主要用途包括：

4.2.1 基于当前话题的模块推荐

当 AI Agent 正在处理某个主题时，可通过 knowledge_network.json 获得最相关的"下一个"模块。例如，用户正在查询合约开发，Agent 已读取 contract.html：

async def recommend_next_modules(
    kn: dict,
    current_filename: str,
    max_recommendations: int = 5,
) -> list[dict]:
    entries = kn.get("entries", {})
    current = entries.get(current_filename)
    if not current:
        return []

    candidates = []
    seen = {current_filename}

    # 优先级 1: related 模块（编辑推荐的相邻模块）
    for rel in current.get("related", []):
        if rel not in seen:
            seen.add(rel)
            meta = entries.get(rel, {})
            candidates.append({
                "filename": rel,
                "title": meta.get("title", ""),
                "status": meta.get("status"),
                "reason": "related",
            })

    # 优先级 2: outlinks（当前模块引用的模块）
    for out in current.get("outlinks", []):
        if out not in seen and len(candidates) < max_recommendations * 2:
            seen.add(out)
            meta = entries.get(out, {})
            candidates.append({
                "filename": out,
                "title": meta.get("title", ""),
                "status": meta.get("status"),
                "reason": "outlink",
            })

    # 优先级 3: backlinks（引用当前模块的模块）
    for back in current.get("backlinks", []):
        if back not in seen and len(candidates) < max_recommendations * 2:
            seen.add(back)
            meta = entries.get(back, {})
            candidates.append({
                "filename": back,
                "title": meta.get("title", ""),
                "status": meta.get("status"),
                "reason": "backlink",
            })

    # 按状态优先级排序
    status_priority = {"implemented": 0, "partial": 1, "planned": 2, "audit": 3}
    candidates.sort(key=lambda x: status_priority.get(x["status"], 99))

    return candidates[:max_recommendations]

4.2.2 阅读路径规划

从起点模块到目标模块的最短路径算法可以帮助 AI Agent 规划高效的阅读路径：

from collections import deque

def find_shortest_path(
    kn: dict, start: str, target: str
) -> list[str] | None:
    entries = kn.get("entries", {})
    if start not in entries or target not in entries:
        return None

    visited = {start}
    queue = deque([(start, [start])])

    while queue:
        current, path = queue.popleft()
        meta = entries.get(current, {})
        neighbors = set(
            meta.get("outlinks", [])
            + meta.get("backlinks", [])
            + meta.get("related", [])
        )

        for neighbor in neighbors:
            if neighbor == target:
                return path + [target]
            if neighbor not in visited and neighbor in entries:
                visited.add(neighbor)
                queue.append((neighbor, path + [neighbor]))

    return None

例如，从 keplr.html（钱包集成）到 emission.html（铸造结算）的路径可能是：

keplr.html → overview.html (钱包->总图) → emission.html (总图->铸造)

这种路径规划在用户提出跨主题问题（如"钱包如何影响代币铸造"）时非常有用。

4.2.3 知识图谱遍历与置信度传播

knowledge_network.json 的关系数据还可以用于置信度传播——当一个模块的某个声明被确认后，通过 outlinks/backlinks 通道传播置信度到相邻模块：

模块 A（implemented）──outlinks──→ 模块 B（partial）
                                  ↑ 传播方向：A 的高置信度通过 outlinks 提升 B 的置信度

def propagate_confidence(
    kn: dict,
    seed_module: str,
    decay_factor: float = 0.5,
    max_depth: int = 3,
) -> dict[str, float]:
    entries = kn.get("entries", {})
    confidence = {seed_module: 1.0}
    queue = deque([(seed_module, 0)])

    while queue:
        current, depth = queue.popleft()
        if depth >= max_depth:
            continue

        current_conf = confidence[current]
        meta = entries.get(current, {})

        neighbors = set(
            meta.get("outlinks", [])
            + meta.get("backlinks", [])
        )

        for neighbor in neighbors:
            new_conf = current_conf * decay_factor
            if neighbor not in confidence or new_conf > confidence[neighbor]:
                confidence[neighbor] = new_conf
                queue.append((neighbor, depth + 1))

    return confidence

4.2.4 按分组和状态的批量查询

当 AI Agent 需要按分组或状态批量查询模块时，可以直接从 knowledge_network.json 索引：

def get_modules_by_group(kn: dict, group: str) -> list[dict]:
    entries = kn.get("entries", {})
    results = []
    for filename, meta in entries.items():
        if meta.get("group") == group:
            results.append({
                "filename": filename,
                "title": meta["title"],
                "status": meta["status"],
                "tags": meta.get("tags", []),
            })
    return results


def get_modules_by_status(kn: dict, status: str) -> list[dict]:
    entries = kn.get("entries", {})
    results = []
    for filename, meta in entries.items():
        if meta.get("status") == status:
            results.append({
                "filename": filename,
                "title": meta["title"],
                "group": meta.get("group"),
                "tags": meta.get("tags", []),
            })
    return results

4.2.5 与 retrieval_hints.json 的集成

retrieval_hints.json（路由提示）和 knowledge_network.json（知识网络）是互补的：

AI Agent 的策略：先用 retrieval_hints.json 快速定位主题，再用 knowledge_network.json 扩展上下文：

async def deep_research(
    client: httpx.AsyncClient,
    question: str,
) -> dict:
    # 阶段 1: 使用 retrieval_hints.json 快速路由
    hints = (await client.get(
        "https://msgchain.org/whitepaper/retrieval_hints.json"
    )).json()
    router = QuestionRouter(hints)
    matches = router.route(question)

    if not matches:
        return {"answer": "未匹配到相关主题", "confidence": "low"}

    best_topic = matches[0]
    recommended_modules = router.get_recommended_modules(best_topic["topic_id"])

    # 阶段 2: 使用 knowledge_network.json 扩展阅读路径
    kn = (await client.get(
        "https://msgchain.org/whitepaper/knowledge_network.json"
    )).json()

    all_modules = []
    for mod in recommended_modules:
        all_modules.append(mod["filename"])
        entry = kn.get("entries", {}).get(mod["filename"], {})
        for rel in entry.get("related", [])[:2]:
            if rel not in all_modules:
                all_modules.append(rel)

    # 阶段 3: 按 implemented > partial > planned 排序
    status_order = {"implemented": 0, "partial": 1, "planned": 2}
    all_modules.sort(key=lambda f: status_order.get(
        kn.get("entries", {}).get(f, {}).get("status", "planned"), 99
    ))

    return {
        "topic": best_topic["title"],
        "modules": all_modules,
        "confidence": best_topic["confidence"],
    }

5. 实践建议

5.1 缓存策略

AI Agent 应缓存 whitepaper_manifest.json 和 knowledge_network.json 的内容，以减少网络请求和提升响应速度。推荐策略：

缓存层级:
  L1: 内存缓存（当前会话）
    ├── whitepaper_manifest.json（建议 TTL: 1 小时）
    └── knowledge_network.json（建议 TTL: 24 小时）
  
  L2: 磁盘缓存（跨会话）
    ├── manifest.json + 版本号 + last-modified
    ├── knowledge_network.json
    └── module_exports/index.json（按需）
  
  刷新规则:
    - 每次会话启动时 HEAD 请求 manifest，比对 last-modified
    - 如果 last-modified 未变，跳过全量刷新
    - 如果 last-modified 变化，增量更新

5.2 文件大小与请求优化

• whitepaper_manifest.json：约 15-25 KB，建议每次会话获取一次
• knowledge_network.json：约 35-50 KB，建议每天获取一次
• 两个文件都是纯 JSON，解析开销小，适合高频率读取

AI Agent 在启动时应优先获取这两个文件（并行请求），以尽快构建白皮书目录和知识图谱：

async def parallel_bootstrap(client: httpx.AsyncClient) -> dict:
    tasks = [
        client.get("https://msgchain.org/whitepaper/whitepaper_manifest.json"),
        client.get("https://msgchain.org/whitepaper/knowledge_network.json"),
        client.get("https://msgchain.org/whitepaper/agent_entry.json"),
    ]
    results = await asyncio.gather(*tasks)
    return {
        "manifest": results[0].json(),
        "knowledge_network": results[1].json(),
        "agent_entry": results[2].json(),
    }

5.3 版本管理

假设未来 schema_version 从 v1 升级到 v2，AI Agent 的应对策略：

VERSION_MIGRATIONS = {
    "v1": {
        "v2": {
            "breaking_changes": [
                "chunk_target_size 可能变化",
                "entry_points 结构可能调整",
                "module_count 可能变化",
            ],
            "action": "full_resync",
        }
    }
}

async def handle_version_upgrade(
    old_version: str, new_version: str
) -> str:
    migrations = VERSION_MIGRATIONS.get(old_version, {})
    migration = migrations.get(new_version, {})
    action = migration.get("action", "full_resync")
    if action == "full_resync":
        print(f"版本 {old_version} -> {new_version}：需要全量重新摄取")
    return action

5.4 错误处理

在消费这两个文件时，AI Agent 应考虑以下错误场景：

async def safe_fetch_json(url: str, retries: int = 2) -> dict | None:
    async with httpx.AsyncClient(timeout=30.0) as client:
        for attempt in range(retries + 1):
            try:
                resp = await client.get(url)
                resp.raise_for_status()
                return resp.json()
            except httpx.HTTPStatusError as e:
                if e.response.status_code == 404:
                    print(f"资源不存在: {url}")
                    return None
                if e.response.status_code == 429 and attempt < retries:
                    wait = 2 ** attempt
                    await asyncio.sleep(wait)
                    continue
                print(f"HTTP {e.response.status_code}: {url}")
                return None
            except (httpx.RequestError, json.JSONDecodeError) as e:
                if attempt < retries:
                    await asyncio.sleep(2 ** attempt)
                    continue
                print(f"获取失败: {url}, {e}")
                return None
    return None

5.5 与其他文件的协同

AI Agent 在消费 whitepaper_manifest.json 和 knowledge_network.json 时，应与以下文件协同工作：

5.6 测试与验证

AI Agent 在集成这两个文件后，应执行以下验证测试：

VALIDATION_TESTS = [
    {
        "name": "manifest_schema_version",
        "test": lambda m: m.get("schema_version") == "v1",
        "fail_message": "whitepaper_manifest.json schema_version 必须为 v1",
    },
    {
        "name": "manifest_module_count",
        "test": lambda m: m.get("module_count", 0) == 65,
        "fail_message": "whitepaper_manifest.json module_count 必须为 65",
    },
    {
        "name": "kn_module_count",
        "test": lambda k: k.get("module_count", 0) == 65,
        "fail_message": "knowledge_network.json module_count 必须为 65",
    },
    {
        "name": "kn_entries_not_empty",
        "test": lambda k: len(k.get("entries", {})) == 65,
        "fail_message": "knowledge_network.json entries 必须包含 65 个模块",
    },
    {
        "name": "kn_entry_has_required_fields",
        "test": lambda k: all(
            all(f in meta for f in ["filename", "title", "status", "group"])
            for meta in k.get("entries", {}).values()
        ),
        "fail_message": "knowledge_network.json 每个 entry 必须包含 filename/title/status/group",
    },
    {
        "name": "manifest_chunk_config",
        "test": lambda m: m.get("module_chunks", {}).get("chunk_target_size") == 900,
        "fail_message": "whitepaper_manifest.json chunk_target_size 必须为 900",
    },
]


def validate_manifest_and_kn(manifest: dict, kn: dict) -> list[str]:
    failures = []
    for test in VALIDATION_TESTS:
        data = manifest if "manifest" in test["name"] else kn
        if not test["test"](data):
            failures.append(test["fail_message"])
    return failures

6. 与现有入口文件的关系总结

6.1 白皮书机器层文件全景

MSG Chain 白皮书机器层的入口文件遵循分层设计。以下从"最宏观"到"最微观"的顺序列出核心入口文件及其关系：

层 0: 全局清单和知识网络
  ├── whitepaper_manifest.json ──── 全局清单：版本、模块数、所有入口 URL、分块配置
  └── knowledge_network.json ────── 知识网络：65 个模块的关联图谱、状态和分组元数据
        │
层 1: 爬取入口
  └── agent_entry.json ──────────── Agent 入口：crawl_contract、recommended_crawl_order、边界
        │
层 2: 路径索引
  ├── retrieval_hints.json ──────── 路由提示：8 个主题的问题→模块→分块映射
  ├── module_exports/index.json ─── 模块导出索引：65 个模块的结构化摘要
  ├── module_chunks/index.json ──── 分块索引：所有分块文件的索引
  └── developer_entry.json ──────── 开发者入口：三种引导顺序、能力矩阵引用
        │
层 3: 执行和交付
  ├── product_delivery_entry.json ── 产品交付入口：五阶段交付模型、硬边界
  ├── execution_pack/index.json ──── 执行包入口：命令注册表、审批门禁、交付工作流
  └── developer_capability_matrix.json ── 能力矩阵：16 个表面的机器就绪度
        │
层 4: 具体内容
  ├── module_exports/{stem}.json ─── 单个模块的结构化导出
  ├── module_chunks/{stem}__chunk_*.json ── 单个模块的分块文本
  └── modules/*.html ─────────────── 权威叙事 HTML 页面

6.2 各入口文件的定位对比

6.3 两个文件与其他入口的一体化使用

推荐的一体化消费流程：

用户提问 / Agent 启动
        │
        ▼
Step 1: 读取 whitepaper_manifest.json 检查版本
        ├── 版本未变 → 使用缓存
        └── 版本已变 → 增量同步
              │
              ▼
Step 2: 读取 knowledge_network.json 构建知识图谱
        ├── 用于模块推荐
        └── 用于路径规划
              │
              ▼
Step 3: 根据任务类型选择入口
        ├── FAQ/问答 → retrieval_hints.json → module_chunks
        ├── 合约开发 → developer_entry.json → contract_templates / recipes
        ├── 产品交付 → product_delivery_entry.json → execution_pack
        ├── dApp 开发 → developer_entry.json → examples / recipes
        └── 全生命周期 → agent_entry.json → crawl_contract
              │
              ▼
Step 4: 使用 knowledge_network.json 扩展结果
        ├── 跟随 related 获取相邻推荐
        ├── 跟随 outlinks 深入子话题
        └── 跟随 backlinks 找到上层叙述
              │
              ▼
Step 5: 生成带边界的答案
        ├── 引用模块的 status 声明实现程度
        ├── 引用模块的 group 声明所属领域
        └── 如涉及经济/治理/Explorer，附加边界子句

6.4 两个文件的关键数据流

数据在不同入口文件之间的流动方向：

msg_whitepaper_pipeline_v1
        │
        ├──→ modules/*.html (人类权威叙事)
        │
        ├──→ module_exports/*.json (结构化导出)
        │         │
        │         └──→ whitepaper_manifest.json 的 module_exports 部分记录其结构
        │
        ├──→ module_chunks/*.json (分块文本)
        │         │
        │         └──→ whitepaper_manifest.json 的 module_chunks 部分记录其配置
        │
        ├──→ knowledge_network.json (知识图谱)
        │         │
        │         ├──→ agent_entry.json 的 crawl_contract.primary_seed 指定为种子
        │         └──→ 从 HTML 页面之间的超链接自动推导 outlinks/backlinks
        │
        └──→ whitepaper_manifest.json (全局清单)
                  │
                  ├──→ agent_entry.json 的 entry_points 引用其 URL
                  └──→ 用于版本追踪和增量同步

6.5 对 AI Agent 的最终建议

1. 永远不要跳过 whitepaper_manifest.json：即使你已经缓存了白皮书数据，每次会话启动时都应该检查 manifest 的版本状态。一次 HEAD 请求的开销远小于使用过时数据带来的错误风险。

2. 视 knowledge_network.json 为第二入口：在读取 agent_entry.json 获取爬取策略后，立即读取 knowledge_network.json 构建模块关系图。这为后续的所有检索和问答提供语义上下文。

3. 利用拓扑数据做置信度判断：outlink_count=0 的模块（如 crosschain.html、keplr.html）通常处于早期阶段，其内容应谨慎引用。hub 模块（如 overview.html、credibility.html）提供全站概览，但不提供具体功能实现。

4. 用 related 做检索扩展：当向量检索只命中少数模块时，使用 knowledge_network.json 的 related 字段扩展检索结果。这些推荐基于编辑判断而非文本相似度，能补充语义盲区。

5. 版本升级时全量刷新：当 whitepaper_manifest.json 的 schema_version 变更时，执行全量刷新而非增量补丁。版本号变更意味着底层结构可能已变化，增量补丁可能遗漏关键变更。

6. 备份关系字段到 RAG 元数据：在将模块分块写入向量库时，同时存储 outlinks、backlinks、related、status、group、tags 等知识网络字段。这些元数据在检索后处理阶段（重排序、扩展、过滤）发挥关键作用。

本指南基于 MSG Chain 白皮书机器层实际内容编写。所有 URL 均指向 https://msgchain.org/whitepaper/ 上的真实文件。
域名为 msgchain.org，链标识为 msg-chain-1，Bech32 地址前缀为 msg。
生成管道: msg_whitepaper_pipeline_v1，元数据画像: public_stable。