Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

第 17 章 Live Wiki 与 MCP

定位：本章讲 Agent 的工作记忆（源码溯源的 live wiki）与知识层的在线服务 （只读 MCP）。前置依赖：第 15 章。基于 agent-spec 1.0.0。

Live Wiki：会过期报警的工作记忆

.agent-spec/wiki 是仓库内被 git 跟踪的 wiki——不是 KLL 真相，不是发布文档， 而是 Agent 的工作记忆：模块页、概念页、决策页、架构清单、跨项目地图。 每篇文章声明 source_files，源码一变即被标记陈旧：

agent-spec wiki init --code .            # 铺目录(各文章目录带 .gitkeep)
agent-spec wiki seed --code .            # 聚焦式草稿页,不覆盖手工维护页
agent-spec wiki status                   # 哪些页陈旧了(含 worktree 未提交变更)
agent-spec wiki query "requirements compiler"
agent-spec wiki inspect src/spec_wiki/live.rs
agent-spec wiki check                    # 索引新鲜度+lint+陈旧状态,CI 结构门

graph LR
    CODE[源码] -->|source_files| ART[wiki 文章]
    ART -->|"wiki status"| STALE{源码变了?}
    STALE -->|是| WARN[标记陈旧页]
    PROJ["projects/*.md<br/>外部项目页"] --> MAP["project-map.json/.mmd<br/>派生地图"]
    FLOW["flows/*.md<br/>跨项目数据流"] --> MAP
    MAP -.lint 要求与文章精确一致.- ART

跨项目场景用 project/flow 文章：projects 列表的相邻对构成有向边，仓库外的 路径只进 external_sources 证据标签（agent-spec 不扫描外部仓库）。派生的 project-map 必须与维护文章精确一致，wiki lint 守着。工作纪律：大量读源码前 先 wiki query；旧内容移入 learnings/ 存档而非粗暴删除。

只读 MCP：项目真相在线可查

agent-spec mcp --knowledge knowledge

通过 stdio JSON-RPC 提供 11 个确定性只读工具（无 RAG、无网络）：

组工具
知识knowledge.find / knowledge.governing / context.read
活性liveness.status
合同spec.contract
指导guidance.for
代码图atlas_tree / atlas_query / atlas_refs / atlas_impls / atlas_status

任何 MCP 客户端（Claude Code、Codex、自研编排器）都能实时查询项目真相，而 不是反复重读文件。只读是边界承诺：审批、治理转换等写操作永远走 CLI—— 这与第 18 章的 ADR-001 一脉相承。