codewiki-generator

Codewiki 生成器

概述

为指定仓库生成 DeepWiki 风格、以代码为先的文档站点。输出内容位于 codewiki/ 目录中，其中包括 VitePress 配置和自动生成的侧边栏。文档必须反映项目的当前状态，并优先解释系统的设计原理，而非仅描述其功能。

工作流

0) 确认语言偏好

询问用户：“文档应该使用哪种语言编写？（例如：English、中文、日本語等）” 如果用户指定了语言，则存储用户提供的语言，并将其应用于所有生成的散文内容。 否则，如果用户未指定语言，则默认使用 English。

1) 首先检查代码库（代码 > 文档）

• 扫描源文件、配置文件、构建和测试流水线、入口点以及架构目录。
• 将现有文档（例如 README、docs/）视为次要线索。
• 优先以代码证据作为最终事实依据。
• 识别并报告文档与代码之间的任何差异。

2) 分析代码库 → 结构化元数据

执行分析器脚本以扫描代码库并生成结构化元数据。<skill-root> 指包含此 SKILL.md 的目录。

python3 <skill-root>/scripts/codewiki_analyze.py \
  --repo-root <repo-root> \
  --out-dir codewiki \
  --force

此命令会生成以下输出：

• codewiki/.meta/ 目录，其中包含 deps.json、entrypoints.json、evidence.json、doc_plan.json 和 symbols.json（如果有 ctags）。
• codewiki/quality-report.md，详细说明覆盖率和置信度较低的页面。
• VitePress 配置脚手架，不包含占位 .md 文件。

注意：此步骤不会生成占位 .md 文件。LLM 负责在步骤 4 中直接撰写文档内容。 注意：现有 Markdown 文件中引用的图像会复制到 codewiki/assets/。

3) 动态确定文档集

• 包含所有最低限度必需的页面。
• 仅在存在相应代码证据时添加条件模块。
• 根据项目规模和复杂度拆分或合并页面。
• 遵循 references/structure-and-heuristics.md 中指定的指南。
• 所有生成文档的目录名和文件名均使用小写。

4) 撰写文档（代码优先，视觉优先）

阅读 codewiki/.meta/doc_plan.json 并处理其中规划的每个页面：

• 如果某个页面没有支持证据，或与代码库的相关性较低，则跳过该页面。
• 否则，仅为包含实际内容的页面创建 .md 文件。

撰写指南：

• 所有散文内容均使用步骤 0 中确定的语言。
• 保留代码片段、文件路径和技术术语的原始格式。
• 每个页面都以低对比度的 # Related Code 区块开头（使用围栏式 text 代码块），而不是标题。
• 使用 Mermaid 绘制图表（上下文图、类图、时序图、组件图、数据流图）。
• 遵循 Mermaid 安全语法：使用简单的节点 ID，标签中避免使用 /、() 和 :，并优先采用 node[plain label] 格式。
• 解释设计选择背后的原理、权衡和限制。
• 提供有根据的见解：指出优势、技术债务或“代码异味”。
• 将概念链接到具体的文件路径、类或入口点。
• 如果现有图像或图表准确，则重复使用。
• 遵循便于 Markdown lint 检查的实践：标题保持一致、不留尾随空格，并正确设置列表格式。

详细的、与证据关联的页面模板请参阅 references/doc-templates.md。

5) 刷新侧边栏并运行站点

生成文档后，更新侧边栏，使其反映实际文件：

python3 <skill-root>/scripts/codewiki_bootstrap.py \
  --repo-root <repo-root> \
  --out-dir codewiki \
  --refresh-sidebar

安装文档依赖项（默认启用 Mermaid 支持）：

npm --prefix codewiki install

启动文档站点：

npm --prefix codewiki run docs:dev

备选启动命令（无需先运行 npm install）：

npx -p vitepress -p vitepress-plugin-mermaid -p mermaid vitepress dev codewiki

6) 提供可选工作流

网站正常运行后，告知用户有哪些可选项：

“文档网站已就绪！现在可以：

• 选项 A：部署到 Cloudflare Pages — 将网站发布到可访问的 URL
• 选项 B：添加多语言支持（i18n）— 将文档翻译成另一种语言

如果你想继续执行其中任一选项，请告诉我。”

可选工作流

核心文档生成流程完成后，可执行以下工作流。

选项 A) 部署到 Cloudflare Pages

使用 wrangler CLI 将文档网站部署到 Cloudflare Pages。

触发条件：用户请求部署、发布或托管文档。

参见：references/deploy-cloudflare.md，其中包含详细说明（包括 wrangler 的安装、登录验证、构建流程、部署，以及使用线上 URL 更新 index.md）。

选项 B) 添加多语言支持（i18n）

将现有文档翻译成第二种语言，并配置 VitePress 语言切换器。

触发条件：用户请求翻译、多语言或国际化（i18n）支持。

参见：references/i18n-setup.md，其中包含详细说明（包括目录结构、VitePress locales 配置和翻译指南）。

质量标准（不可妥协）

• 视觉优先：优先使用图表，而不是大段文字。
• 洞察深刻：除了说明机制，还要阐释设计意图。
• 观点鲜明：指出架构优势和已识别的风险。
• 引用关联：为所有关键概念提供具体文件／类的引用。
• 代码优先：代码库是权威信息来源；文档用于补充说明。

资源

scripts/

• codewiki_analyze.py：扫描代码库并生成 .meta/*.json 元数据文件。
• codewiki_bootstrap.py：搭建 codewiki/ 目录、复制引用的图像并生成侧边栏。

references/

• structure-and-heuristics.md：包含模块选择和信号识别规则。
• doc-templates.md：提供适用于所有页面类型的全面模板，并附有证据链接。
• deploy-cloudflare.md：详细说明部署到 Cloudflare Pages 的工作流。
• i18n-setup.md：概述多语言支持的配置流程。

assets/

• vitepress/：包含精简的 VitePress 配置和首页模板。