用途
Codebase Wiki 是一个由智能体编写、以源码为依据的代码库 Wiki 起始包。它把代码库的文档以 Markdown 形式存放在仓库的 wiki/ 目录下，受版本控制、可 diff、默认私有，支持人与智能体协同编辑，可在 OK 的实时预览中渲染，并可作为未来智能体会话的持久上下文。它没有独立的问答界面，问答即“基于 OK 的智能体 + 搜索”。
本技能是包级指导。平台 /open-knowledge 技能（读/写/预览/链接/溯源规则）仍约束每一次 Markdown 操作，本技能在其之上叠加 Wiki 工作流。
目录结构
wiki/
OVERVIEW.md hub：是什么、整体架构图、指向每个章节的导航图。
Frontmatter 携带 `profile`（受众/深度）+ `source_commit`（新鲜度锚点）。
log.md 仅追加的生成/刷新审计记录
architecture/ 系统边界、分层、子系统、横切关注点 + 图表
modules/ 每个包/模块一页：用途、入口点、关键文件、依赖
flows/ 关键端到端流程，以时序/流程图 + 叙述呈现
concepts/ 术语表：领域术语/核心抽象的原子页面
guides/ 面向任务的“如何/在哪里修改 X”（在 depth >= standard 时填充）
生成与刷新
不要手工随意编写——阅读 references/generate-and-refresh.md 并遵循分阶段、带 STOP 门控的流程。它会自动检测模式：
- 若 OVERVIEW.md 为占位状态（source_commit 为空）→ 生成（survey → overview → architecture → modules → flows → concepts → link-graph audit）；
- 若 source_commit 已标记 → 刷新（diff source_commit..HEAD，仅更新受影响的页面，然后重新标记）。
使用两套工具：用原生工具（Read/Grep/Glob/Bash）阅读源码——OK MCP 不索引非 Markdown 源码；用 OK MCP 动词编写和审计 Wiki（write/edit 写页面，links/search 处理图谱）。切勿用原生 Write/Edit 手写 Wiki Markdown。
两个旋钮
两个自然语言旋钮，从用户请求中读取（例如“build the wiki, public and exhaustive”），并记录在 OVERVIEW.md 的 frontmatter 中（profile: <audience>/<depth>），以便刷新保持一致：
- audience — internal（默认）或 public。public 意味着打磨过的行文、不含机密/内部基础设施/工单编号，并使用 GitHub URL 源码引用。
- depth — tour | standard（默认）| exhaustive。覆盖范围从 OVERVIEW + architecture + 顶层 flows，向上扩展到逐包 module 页面、concepts 和任务 guides。
references/generate-and-refresh.md 是每个旋钮如何塑造输出的权威来源——生成前请先阅读。
源码引用约定
- Wiki 内导航 → OK 文档链接——它们构建反向链接/枢纽/孤儿图谱，因此可大量链接；密度是 Wiki 保持可导航的方式。
- 代码引用 → 相对链接 + 符号 code-span（internal）或 GitHub blob URL（public）。源码文件链接不进入导航图谱（links 只跟踪 .md/.mdx 边，因此它们不会显示为图谱死链或孤儿）——但错误深度的路径仍会在 write/edit 的 brokenLinks 响应中暴露（no-such-file，或若超出内容根则 unresolvable），因此要从页面所在文件夹计算 ../ 跳数。切勿虚构路径——只引用你实际读过的文件。
完整规则——GitHub URL/相对回退、#Lxx 注意事项以及确切的 code-span 形态——见 references/generate-and-refresh.md。
各文件夹规则
- architecture/ — 每个架构领域一页（边界、分层、子系统、横切关注点）。每页包含：一张 mermaid 系统上下文或组件图、关键组件（带源码引用）及其背后的设计决策。使用 architecture-page 模板。在 depth: tour 时，modules 折叠到这里。
- modules/ — 每个包/模块一页：用途、职责、公共 API/入口点、关键文件（按约定链接）、依赖，以及它参与的 flows。使用 module-page 模板。tour 时跳过；子模块深度随旋钮缩放。
- flows/ — 关键端到端序列，以 mermaid 时序/流程图 + 叙述呈现。使用 flow-page 模板；在 exhaustive 时增加 Failure modes 章节。链接流程经过的每个 module 和 concept。
- concepts/ — 原子术语页（每页一个术语）：定义、为何重要、在代码中的位置。使用 concept-page 模板。保持小巧且密集交叉链接，使每个概念成为枢纽。
- guides/ — 面向任务的“如何/在哪里修改 X”演练：目标、步骤、相关代码、注意事项。使用 guide-page 模板。在 standard 时填充，exhaustive 时丰富，tour 时稀疏/为空。
新鲜度纪律（必须）
OVERVIEW.md 的 frontmatter 携带 source_commit——即 Wiki 上次生成/刷新所对应的 git HEAD。它是新鲜度锚点：刷新模式 diff source_commit..HEAD 以仅更新受影响的页面，然后重新标记它。每次生成或刷新运行后务必重新标记 source_commit——过期的锚点会静默破坏增量刷新。
日志纪律（必须）
wiki/log.md 是仅追加的审计记录。每次生成或刷新运行追加一条带日期的条目——每次运行一条，而非每页一条。将被触及的页面引用为 Markdown 链接（Server），以便它们注册到反向链接图谱。条目形态：
## YYYY-MM-DD: <generate | refresh>
- Profile: <audience>/<depth>
- source_commit: <short-sha> (was <prev-sha> on refresh)
- Coverage: <sections / packages written or updated>
- Pages: [Overview](./OVERVIEW.md), [Server](./modules/server.md), ...
模板
每个文件夹附带一个起始模板（architecture-page、module-page、flow-page、concept-page、guide-page）。使用 write({ document: { path, template: "<name>" } }) 创建。模板只携带结构（标题 + frontmatter 脚手架）；每个章节的用途在上文及 references/generate-and-refresh.md 中描述，不在文档正文内重复。
适用场景与限制
适用于需要为代码库生成可导航、可溯源、可版本控制的文档，并希望其作为未来智能体会话持久上下文的场景。限制：OK MCP 不索引非 Markdown 源码，因此阅读源码必须使用原生工具；源码文件链接不进入导航图谱；路径必须真实存在，不可虚构；source_commit 必须及时重新标记，否则增量刷新会失效。