Back to Details

codebase-wiki

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Codebase Wiki pack — how to work here

Codebase Wiki 启动包——如何在此开展工作

This project holds an agent-authored wiki of a codebase — DeepWiki, but living in the repo. A coding agent reads the source and writes a navigable, diagram-rich, source-grounded wiki as markdown under 
wiki/
. It is version-controlled and diffable, private by default, human+agent co-editable, renders in OK's live preview, and doubles as durable grounding context for future agent sessions. There is no separate Q&A surface — Q&A is "the OK-grounded agent + 
search
".
This skill is pack guidance. The platform 
/open-knowledge
skill (read/write/preview/linking/grounding rules) still governs every markdown operation — this layers the wiki workflow on top.
本项目包含一个由Agent编写的代码库wiki——即DeepWiki，但它直接托管在代码仓库中。编码Agent会读取源代码，并在
wiki/
目录下以Markdown格式编写一个可导航、富含图表、基于源代码的wiki。该wiki支持版本控制与差异对比，默认私有，支持人类与Agent协同编辑，可在OK的实时预览中渲染，同时还能作为未来Agent会话的持久化上下文。本项目没有独立的问答界面——问答功能由「基于OK的Agent + 
search
工具」实现。
本技能为套件使用指南。平台的
/open-knowledge
技能（读写/预览/链接/上下文关联规则）仍管控所有Markdown操作——本指南仅在其基础上叠加wiki工作流。

The shape

目录结构

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)
wiki/
  OVERVIEW.md     核心页面：介绍wiki内容、全局架构图、各板块导航地图。
                  前置元数据包含`profile`（受众/深度）与`source_commit`（新鲜度锚点）。
  log.md          仅追加式的生成/刷新审计日志
  architecture/   系统边界、层级、子系统、横切关注点及相关图表
  modules/        每个包/模块对应一个页面：说明用途、入口点、关键文件、依赖
  flows/          以序列图/流程图加文字说明呈现核心端到端流程
  concepts/       术语表：每个领域术语/核心抽象对应一个独立页面
  guides/         面向任务的「如何/在哪里修改X」指南（仅当深度≥standard时填充）

Generating + refreshing

生成与刷新

Don't free-hand it — read references/generate-and-refresh.md and follow the phased, STOP-gated procedure. It auto-detects mode: a stubbed 
OVERVIEW.md
(empty 
source_commit
) → generate (survey → overview → architecture → modules → flows → concepts → link-graph audit); a stamped 
source_commit
→ refresh (diff 
source_commit..HEAD
, update only affected pages, re-stamp).
Two toolsets. Read source code with NATIVE tools (
Read
/
Grep
/
Glob
/
Bash
) — OK MCP does not index non-markdown source. Author and audit the wiki with OK MCP verbs (
write
/
edit
for pages, 
links
/
search
for the graph). Never hand-write wiki markdown with native 
Write
/
Edit
.
请勿随意编写——请阅读**references/generate-and-refresh.md并遵循分阶段、带检查点的流程。系统会自动检测模式：若
OVERVIEW.md
为草稿（
source_commit
为空）则进入生成模式**（调研→概述→架构→模块→流程→概念→链接图谱审计）；若
OVERVIEW.md
已标记
source_commit
则进入刷新模式（对比
source_commit..HEAD
的差异，仅更新受影响页面，重新标记
source_commit
）。
两套工具集。使用原生工具（
Read
/
Grep
/
Glob
/
Bash
）读取源代码——OK MCP不会索引非Markdown格式的源代码。使用OK MCP指令编写和审计wiki（页面操作使用
write
/
edit
，图谱操作使用
links
/
search
）。请勿使用原生
Write
/
Edit
工具手动编写wiki的Markdown内容。

The two knobs

两个调节项

Two natural-language knobs, read from the user's request (e.g. "build the wiki, public and exhaustive") and recorded in 
OVERVIEW.md
frontmatter (
profile: <audience>/<depth>
) so refreshes stay consistent:
  • audience
     — 
    internal
    (default) or 
    public
    . 
    public
    means polished prose, no secrets / internal infra / ticket numbers, and GitHub-URL source references.
  • depth
     — 
    tour
    | 
    standard
    (default) | 
    exhaustive
    . Scales coverage from OVERVIEW + architecture + top flows up through per-package module pages, concepts, and task guides.
references/generate-and-refresh.md is the authoritative source for exactly how each knob shapes the output — read it before generating.
两个自然语言调节项，从用户请求中读取（例如“构建wiki，公开且详尽”）并记录在
OVERVIEW.md
的前置元数据中（格式为
profile: <audience>/<depth>
），确保刷新操作保持一致性：
  • audience
     — 可选
    internal
    （默认）或
    public
    。
    public
    意味着需使用精炼的表述，不得包含机密信息/内部基础设施/工单编号，且源代码引用需使用GitHub URL。
  • depth
     — 可选
    tour
    | 
    standard
    （默认） | 
    exhaustive
    。覆盖范围从概述+架构+核心流程，扩展至每个包的模块页面、术语表及任务指南。
references/generate-and-refresh.md是关于各调节项如何影响输出的权威说明——生成前请务必阅读。

Source-reference convention

源代码引用约定

  • Intra-wiki navigation → OK doc links — they build the backlink / hub / orphan graph, so link liberally; density is how the wiki stays navigable.
  • Code references → relative links + symbol code-spans (
    internal
    ) or GitHub blob URLs (
    public
    ). Source-file links stay out of the navigation graph (
    links
    tracks only 
    .md
    /
    .mdx
    edges, so they never show as graph dead-links or orphans) — but a wrong-depth path still surfaces in the write/edit 
    brokenLinks
    response (
    no-such-file
    , or 
    unresolvable
    if it overshoots the content root), so count the 
    ../
    hops from the page's folder. Never invent paths — reference only files you actually read.
The full rules — the GitHub-URL / relative fallback, the 
#Lxx
caveat, and the exact code-span shape — live in references/generate-and-refresh.md.
  • wiki内部导航 → 使用OK文档链接——此类链接会构建反向链接/核心页面/孤立页面图谱，因此请尽量多添加链接；链接密度是保证wiki可导航性的关键。
  • 代码引用 → 内部环境使用相对链接+符号代码段，公开环境使用GitHub blob URL。源代码文件链接不会纳入导航图谱（
    links
    仅追踪
    .md
    /
    .mdx
    文件的关联），因此不会被标记为图谱中的死链或孤立链接——但路径深度错误仍会在写入/编辑的
    brokenLinks
    响应中显示（
    no-such-file
    ，若超出内容根目录则显示
    unresolvable
    ），因此请务必计算当前页面目录到目标文件的
    ../
    跳转次数。请勿编造路径——仅引用实际读取过的文件。
完整规则——包括GitHub URL/相对链接的 fallback 机制、
#Lxx
的注意事项以及代码段的具体格式——请查看references/generate-and-refresh.md。

Per-folder rules

各目录规则

architecture/
 — One page per architectural area (boundaries, layers, subsystems, cross-cutting concerns). Each: a 
mermaid
system-context or component diagram, key components (with source refs), and the design decisions behind them. Uses the 
architecture-page
template. At 
depth: tour
, modules fold in here.
modules/
 — One page per package / module: purpose, responsibilities, public API / entry points, key files (linked per the convention), dependencies, and flows it participates in. Uses the 
module-page
template. Skipped at 
tour
; sub-module depth scales with the knob.
flows/
 — Key end-to-end sequences as 
mermaid
sequence / flow diagrams + narrative. Uses the 
flow-page
template; add a Failure modes section at 
exhaustive
. Link every module and concept the flow crosses.
concepts/
 — Atomic glossary pages (one term each): definition, why it matters, where it lives in the code. Uses the 
concept-page
template. Keep small and densely cross-linked so each concept becomes a hub.
guides/
 — Task-oriented "how / where do I change X" walkthroughs: goal, steps, relevant code, gotchas. Uses the 
guide-page
template. Populated at 
standard
, rich at 
exhaustive
, thin/empty at 
tour
.
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
深度下内容简略或为空。

Freshness discipline (MUST)

新鲜度管理规范（必须遵守）

OVERVIEW.md
frontmatter carries 
source_commit
— the git HEAD the wiki was last generated/refreshed against. It is the freshness anchor: refresh mode diffs 
source_commit..HEAD
to update only the affected pages, then re-stamps it. Always re-stamp 
source_commit
after a generate or refresh run — a stale anchor silently breaks incremental refresh.
OVERVIEW.md
的前置元数据包含
source_commit
——即wiki最后一次生成/刷新时对应的git HEAD。它是新鲜度锚点：刷新模式会对比
source_commit..HEAD
的差异，仅更新受影响的页面，然后重新标记
source_commit
。每次生成或刷新后务必重新标记
source_commit
——失效的锚点会悄无声息地破坏增量刷新功能。

Log discipline (MUST)

日志记录准则（必须遵守）

wiki/log.md
is an append-only audit trail. Append one dated entry per generation or refresh run — one per run, not per page. Reference touched pages as markdown links (
[Server](./modules/server.md)
) so they register in the backlink graph. Entry shape:
markdown
undefined
wiki/log.md
是仅追加式的审计日志。每次生成或刷新运行后追加一条带日期的记录——每运行一次添加一条，而非每个页面一条。使用Markdown链接引用涉及的页面（如
[Server](./modules/server.md)
），使其在反向链接图谱中被记录。记录格式如下：
markdown
undefined

YYYY-MM-DD: <generate | refresh>

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, Server, ...
undefined
  • Profile: <audience>/<depth>
  • source_commit: <short-sha> (刷新前为<prev-sha>)
  • 覆盖范围: <已编写或更新的板块/包>
  • 涉及页面: Overview, Server, ...
undefined

Templates

模板

Each folder ships a starter template (
architecture-page
, 
module-page
, 
flow-page
, 
concept-page
, 
guide-page
). Create with 
write({ document: { path, template: "<name>" } })
. Templates carry only structure (headings + frontmatter scaffold); what each section is for is described above and in references/generate-and-refresh.md, not repeated inside document bodies.
每个目录都提供了初始模板（
architecture-page
、
module-page
、
flow-page
、
concept-page
、
guide-page
）。使用
write({ document: { path, template: "<name>" } })
指令创建页面。模板仅包含结构（标题+前置元数据框架）；每个章节的用途已在本文档和references/generate-and-refresh.md中说明，不会在文档正文中重复。