用 AI 生成代码库Wiki技术文档: CodeWiki上手体验&定制化改造

绍兴古城实景

作为AI Coding重度用户，个人觉得虽然现在开发代码降低了技术门槛，但是对一个人的架构以及业务理解能力反而提高了，因为你要能够驾驭AI这辆"超跑"运行在正确的轨道上，为了提升对陌生代码库的理解，我一直想找一个既能给人看又能给AI看的技术文档，尤其是要能给人看。最近我接触到如下几个工具:(1) Qoder自带的repowiki，功能强大但是深度绑定qoder且需要开会员; (2) deepwiki闭源，开源版本deepwiki-open需要配大模型。(3)understand-anything、graphify可读性比较差。

CodeWiki 的定位很明确：做一个开源的、支持多语言的、能生成仓库级全景文档的框架，并且在文档质量上对标甚至超越商业方案。虽然其需要配模型才能跑，但经过改造，完全可以使用AI IDE驱动其生成wiki。(文末有介绍)

效果如何？与 DeepWiki 的对比

为了评估代码文档的质量，CodeWiki 团队还推出了配套的评测基准 CodeWikiBench，涵盖多种编程语言的仓库级文档质量评估。

根据论文中的实验数据，CodeWiki 在 CodeWikiBench 上的整体平均得分比 DeepWiki 高出约 4.73%，尤其在 Python、JavaScript 等脚本语言上表现突出。在 C/C++ 等系统级语言上，由于代码结构更加复杂（宏定义、指针、内存管理等），DeepWiki 在该类别上略占优势（高出约 3.15%），但 CodeWiki 在整体表现上仍然领先。

这个成绩说明 CodeWiki 作为一个开源方案，在文档生成质量上已经可以与商业产品一较高下。

适用场景

CodeWiki 特别适合以下几种场景：

新人 Onboarding。当一个新成员加入团队时，面对一个有几十万行代码的仓库，CodeWiki 可以帮他快速建立对项目的整体认知，了解模块划分和核心逻辑，大幅缩短上手时间。

开源项目维护。开源项目的文档质量直接影响社区的参与度。用 CodeWiki 自动生成并更新文档，可以降低维护者的文档负担，让更多人愿意参与贡献。

代码审查与重构。在进行大规模重构或代码审查时，CodeWiki 生成的架构文档可以帮助团队更好地理解模块间的依赖关系，避免"牵一发而动全身"的风险。

技术选型与调研。当你需要评估一个陌生的开源项目是否适合你的需求时，CodeWiki 可以帮你快速生成一份项目概览，省去大量阅读源码的时间。

上手实战（CLI模式）

1 安装

Code

pip install git+https://github.com/FSoft-AI4Code/CodeWiki.git

2 验证安装结果

Code

(base) kirito@KiritodeMacBook-Pro CodingHub % codewiki --version
CodeWiki CLI, version 1.0.1

3 模型设置

Code

codewiki config set \
  --provider openai-compatible \
  --api-key YOUR_API_KEY \
  --base-url https://ark.cn-beijing.volces.com/api/coding/v3 \
  --main-model GLM-5.2 \
  --cluster-model GLM-5.2 \
  --fallback-model MiniMax-M3

Code

✓ Base URL: https://ark.cn-beijing.volces.com/api/coding/v3
✓ Main model: GLM-5.2
✓ Cluster model: GLM-5.2

⚠️  Cluster model is not a top-tier LLM. Documentation quality may be suboptimal.
   Recommended models: claude-opus, claude-sonnet-4, gpt-4, gpt-4-turbo
✓ Fallback model: MiniMax-M3
✓ Provider: openai-compatible

Configuration updated successfully.

4 其他设置：

有很多参数可以设置，例如默认输出的文档为英文，设置输出中文

Code

codewiki config agent --instructions "请用中文撰写所有文档"

5 生成文档

以github pages文档为例

Code

codewiki generate --github-pages --verbose

运行时可能会遇到这个报错

Code

[20:41:58] ERROR    Error processing module user_management: Tool 'str_replace_editor' exceeded max retries count of 1

把错误贴给AI顺利解决：

user\_management 模块的内容太大，LLM 试图一次性用 str_replace_editor 写入大量内容，输出 token 达到上限后被截断，JSON 不完整自然无法解析。

问题在于 leaf module 的 token 限制（16000）可能不够。让我调大相关参数：

参数	原值	新值
Max Tokens	32,768	65,536
Max Token/Module	36,369	50,000
Max Token/Leaf Module	16,000	32,000

或者直接用codewiki命令修改

Code

codewiki config set --max-tokens 65536 --max-token-per-module 50000 --max-token-per-leaf-module 32000

✓ Max tokens: 65536
✓ Max token per module: 50000
✓ Max token per leaf module: 32000

Configuration updated successfully.

问题解决后重新执行命令，成功完成

发布到github pages:

打开你的 GitHub 仓库，进入 Settings → 左侧菜单找到 Pages。在 "Build and deployment" 部分：

Source：选择 "Deploy from a branch"

Branch：选择你要发布的分支（比如 main）和目录（通常是 / (root)）

点击 Save

生成后端技术文档

Code

codewiki generate --output ./codewiki --focus "backend" --instructions "请用中文撰写所有文档"

文档输出到codewiki文件夹，只分析backend文件夹（后端代码），生成中文文档。

Code

[1/4] Validating configuration...
✓ Configuration valid
[2/4] Validating repository...
✓ Repository valid: CodingHub
✓ Output directory: /Users/kirito/repos/CodingHub/codewiki
[4/4] Generating documentation...

[1/5] Dependency Analysis
[2/5] Module Clustering
[3/5] Documentation Generation
Warning: IPython is not installed. Mermaidjs magic function is not available.

✓ Documentation generated successfully!

Output directory:
  /Users/kirito/repos/CodingHub/codewiki

Generated files:
  - authentication.md
  - forum.md
  - overview.md
  - ai-skills.md
  - first_module_tree.json
  - metadata.json
  - mcp-server.md
  - module_tree.json
  - tool-management.md
  - frontend.md

Statistics:
  Total modules:     0
  Files analyzed:    598
  Generation time:   44 minutes 55 seconds

文档效果：

图文结合，给新员工用来熟悉项目应该很好，个人感觉比understand-anything生成的图表要更加清晰

对比一下understand-anything生成的图表：

CodeWiki也提供web页面，可以在页面输入代码库地址，在线生成wiki。

另外，deepwiki-open项目是跟codewiki功能类似且star数更多的一个开源项目，而且支持基于代码的RAG问答，也值得尝试。

改造为不需要配置大模型

CodeWiki-CN诞生记

在CodeBuddy/Qoder等国产工具中使用CodeWiki是需要单独配置大模型的，这一点不太友好，我已经把它改造为完全由AI IDE驱动，无需单独配置模型，改造思路就是把源码中需要大模型的部分改为MCP接口，使之可以通过IDE调用。

代码库地址：

https://github.com/mambo-wang/CodeWiki-CN

欢迎试用！

使用效果：

按照README文档配置完成后直接在IDE对话框输入提示词即可

Code

帮我分析这个仓库并生成 Wiki 文档

Code

所有任务均已完成。Wiki 文档已全部生成于 `repowiki/` 目录，会话已清理，工作记忆已更新。

让我打开总览文档供你查看。
Wiki 文档生成任务已全部完成。以下是交付总结：

## 交付物

`repowiki/` 目录下共生成 **7 个 Markdown 文档**：

| 文档 | 内容 | 行数 |
|------|------|------|
| `overview.md` | 仓库总览（项目简介、端到端架构图、模块导航、核心工作流、关键设计决策） | 154 |
| `schema.md` | Schema 数据契约层（Message/ToolCall/ToolResult/ToolDefinition） | 101 |
| `provider.md` | Provider LLM 适配层（OpenAI/Anthropic 双实现 + 配置体系） | 139 |
| `tools.md` | 工具层（Registry 注册表 + bash/read/write/edit 四款工具） | 140 |
| `engine.md` | 引擎层（ReAct 主循环 + Reporter 接口） | 162 |
| `feishu.md` | 飞书集成（WebSocket 接入 + FeishuReporter） | 131 |
| `entry.md` | 入口层（程序装配 + 双模式启动） | 145 |

## 说明

- CodeWiki 的 Tree-sitter Go 解析器未能产出组件索引（组件数为 0），因此采用了**手动浏览全部源码 + 直接生成文档**的退化方案，完整覆盖了 14 个 Go 源文件。
- 所有 Mermaid 架构图语法校验通过（`engine.md` 有一处 mermaid.ink 远程服务的 SSL 连接警告，非图表语法问题）。
- 文档间通过 `[模块名](模块名.md)` 格式建立了交叉引用，可从 `overview.md` 导航到各模块详情。

效果：

说句题外话，AI编程提效相关文章和我平时的笔记我保存在ima共享知识库了，欢迎大家查看