codebase-wiki

代码库 Wiki 包 — 如何在此工作

本项目包含一份由 Agent 编写的代码库 Wiki——DeepWiki，但它存在于代码仓库中。编码 Agent 阅读源代码，并在 wiki/ 下用 Markdown 编写一份可导航、包含丰富图表且以源代码为依据的 Wiki。它受版本控制且可查看差异，默认私有，支持人类与 Agent 协同编辑，可在 OK 的实时预览中渲染，还能为未来的 Agent 会话提供持久可靠的上下文。这里没有单独的问答界面——问答就是“基于 OK 的 Agent + search”。

本技能提供的是包级指导。平台的 /open-knowledge 技能（读取／写入／预览／链接／依据规则）仍适用于所有 Markdown 操作；本指南是在此基础上叠加 Wiki 工作流。

结构

wiki/
  OVERVIEW.md     hub: what it is, a big-picture architecture diagram, a nav map to every section.
                  Frontmatter carries `profile` (audience/depth) + `source_commit` (freshness anchor).
  log.md          append-only generation / refresh audit trail
  architecture/   system boundaries, layers, subsystems, cross-cutting concerns + diagrams
  modules/        one page per package / module: purpose, entry points, key files, deps
  flows/          key end-to-end flows as sequence / flow diagrams + narrative
  concepts/       glossary: atomic pages for domain terms / core abstractions
  guides/         task-oriented "how / where do I change X" (filled at depth >= standard)

生成与刷新

不要凭感觉编写——请阅读 references/generate-and-refresh.md，并遵循分阶段、设有 STOP 门槛的流程。它会自动检测模式：没有填写 source_commit 的 OVERVIEW.md 占位文件 → 生成（调查 → 概览 → 架构 → 模块 → 流程 → 概念 → 链接图审计）；已写入 source_commit → 刷新（比较 source_commit..HEAD，仅更新受影响的页面，然后重新写入提交标记）。

两套工具。 使用原生工具（Read/Grep/Glob/Bash）读取源代码——OK MCP 不会索引非 Markdown 源文件。使用 OK MCP 动词（对页面使用 write/edit，对图谱使用 links/search）编写并审计 Wiki。切勿使用原生 Write/Edit 手动编写 Wiki Markdown。

两个调节项

从用户请求中读取两个自然语言调节项（例如“构建 Wiki，面向公众且内容详尽”），并将其记录在 OVERVIEW.md 的 frontmatter 中（profile: <audience>/<depth>），以确保刷新时保持一致：

• audience — internal（默认）或 public。public 表示使用润色后的文案，不包含机密／内部基础设施／工单编号，并使用 GitHub URL 作为源代码引用。
• depth — tour | standard（默认）| exhaustive。覆盖范围从 OVERVIEW、架构和主要流程，扩展到逐包模块页面、概念和任务指南。

references/generate-and-refresh.md 是关于各调节项如何具体影响输出的权威说明——生成前请先阅读。

源代码引用约定

• Wiki 内导航 → OK 文档链接——它们会构建反向链接／枢纽／孤立页面图谱，因此应尽可能多地添加链接；链接密度是 Wiki 保持易于导航的关键。
• 代码引用 → 使用相对链接 + 符号代码跨度（internal），或 GitHub blob URL（public）。源文件链接不会进入导航图谱（links 只追踪 .md/.mdx 边，因此这些链接不会显示为图谱中的失效链接或孤立页面）——但路径层级错误仍会出现在 write/edit 的 brokenLinks 响应中（no-such-file，或超出内容根目录时为 unresolvable），因此请根据页面所在文件夹计算 ../ 的层数。切勿臆造路径——只引用你实际读取过的文件。

完整规则——包括 GitHub URL／相对路径回退方案、#Lxx 注意事项以及精确的代码跨度格式——请参阅 references/generate-and-refresh.md。

各文件夹规则

architecture/ — 每个架构领域（边界、层、子系统、横切关注点）编写一个页面。每页包含一个 mermaid 系统上下文图或组件图、关键组件（附源代码引用），以及背后的设计决策。使用 architecture-page 模板。在 depth: tour 模式下，模块内容会合并到此处。

modules/ — 每个包 / 模块编写一个页面：用途、职责、公共 API / 入口点、关键文件（按约定添加链接）、依赖项，以及参与的流程。使用 module-page 模板。在 tour 模式下跳过；子模块深度由相应的调节项控制。

flows/ — 将关键端到端序列编写为 mermaid 时序图 / 流程图，并附上说明。使用 flow-page 模板；在 exhaustive 模式下添加 故障模式 一节。链接流程涉及的每个模块和概念。

concepts/ — 编写原子化的术语表页面（每页一个术语）：定义、重要性，以及在代码中的位置。使用 concept-page 模板。保持页面简短并密集交叉链接，让每个概念都成为一个枢纽。

guides/ — 编写以任务为导向的“如何 / 在哪里修改 X”指南：目标、步骤、相关代码、注意事项。使用 guide-page 模板。在 standard 模式下填充，在 exhaustive 模式下内容丰富，在 tour 模式下内容精简或留空。

新鲜度规范（必须遵守）

OVERVIEW.md 的 frontmatter 中包含 source_commit，表示上次生成 / 刷新 Wiki 时对应的 Git HEAD。它是新鲜度的锚点：刷新模式会对比 source_commit..HEAD，仅更新受影响的页面，然后重新标记该值。每次生成或刷新后都必须重新标记 source_commit——锚点过时会导致增量刷新静默失效。

日志规范（必须遵守）

wiki/log.md 是仅追加的审计记录。每次生成或刷新运行都追加一条带日期的记录——每次运行一条，而非每页一条。使用 Markdown 链接引用已修改的页面（[Server](./modules/server.md)），以便它们记录在反向链接图中。记录格式：

## 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 中说明，不会在文档正文中重复。