CodeWiki 使用指南

简介：CodeWiki 是由 FPT Software AI Center（FSoft-AI4Code）开发并发表于 ACL 2026 的开源工具。它专门用于解决“大模型难以理解整个代码仓库”的问题，能够自动将庞大、多语言的代码仓库梳理成结构清晰、架构完备的 Wiki 文档。

📖 平台介绍与核心定位

传统的 AI 助手往往只能理解单个函数或文件，缺乏全局视野。CodeWiki 采用“自顶向下”的层次分解和多智能体（Multi-agent）递归生成机制：

• 系统级理解：将复杂的代码仓库剥离成模块、组件。
• 依赖梳理：分析跨文件、跨模块的系统交互与数据流关系。
• 架构图生成功能：像人类架构师一样，最终生成包含 Mermaid 架构图的完整 Wiki 文档体系。

✨ 核心功能亮点

🔍 仓库级架构理解 (Repository-Level)

不仅限于解释单个文件，工具能够梳理跨文件的模块交互、数据流以及系统级的依赖关系，真正掌握代码全局逻辑。

🖼️ 多模态文档合成 (Multi-Modal Synthesis)

• 自动配图：结合文字描述自动生成架构图（Mermaid）、数据流图和序列图。
• 智能校验：集成 Mermaid 工具链确保生成的图示可直接渲染且语法正确可用。

🧠 递归智能体生成机制 (Recursive Agents)

能够根据模块的复杂程度，动态分配 LLM 任务给多个智能体协作完成，确保即便是百万行级别的庞大项目，文档细节质量依然不滑坡（Scale without Sliding Quality）。

🌐 多语言原生支持

无需二次配置即可解析主流后端与前端代码：

• 编程语言：Python, Java, JavaScript/TypeScript, C/C++, C#等。
• 生态兼容：同时处理脚本、配置文件及测试文件，全面覆盖技术栈。

👥 适用人群与建议场景

目标角色典型应用场景开源项目维护者快速为项目构建高质量官方 Readme / Wiki，降低社区文档门槛。新入职/接手项目的研发人员一键分析历史遗留系统（“屎山”代码），通过生成架构图迅速摸清业务逻辑与结构。技术主管/架构师快速生成系统交互、调用关系图谱，用于复盘系统健康度及依赖风险复核。

💰 费用模式说明 (免费 & 开源)

• 软件本身：完全免费。基于 GitHub 开源协议发布，无平台订阅费或商业授权限制。
• 运行成本：按需付费 (Token 消耗)。工具作为本地 CLI 命令行版本运行（无需 SaaS 托管），生成文档时需调用外部大模型 API（如 Anthropic Claude、OpenAI）。您只需支付 LLM 厂商的 Token 费用，无其他隐形消费。

🚀 快速上手指南 (极简版)

1️⃣ 准备环境

确保本地已安装以下基础运行库：

• Python: 3.12 或更高版本 (pip)。
• Node.js：用于校验 Mermaid 架构图的渲染与语法（可选但推荐）。

2️⃣ 一键安装 (PyPI / Git)

直接在终端中执行以下命令获取最新源码安装包：

bash

# 从 GitHub 主仓库安装最新版代码库
pip install git+https://github.com/FSoft-AI4Code/CodeWiki.git

# 验证安装是否成功
codewiki --version
# 从 GitHub 主仓库安装最新版代码库
pip install git+https://github.com/FSoft-AI4Code/CodeWiki.git

# 验证安装是否成功
codewiki --version

3️⃣ 配置 LLM API (以 Claude 为例)

设置您的模型连接与凭证，支持 Anthropic、OpenAI 等主流接口：

bash

# 1. 填入 Key, Base URL, Model Name (如 claude-sonnet-4)
codewiki config set \
  --api-key YOUR_API_KEY \
  --base-url https://api.anthropic.com \
  --main-model claude-sonnet-4 \
  --cluster-model claude-sonnet-4

# 2. 配置验证 (检查状态与连通性)
codewiki config show 
codewiki config validate
# 1. 填入 Key, Base URL, Model Name (如 claude-sonnet-4)
codewiki config set \
  --api-key YOUR_API_KEY \
  --base-url https://api.anthropic.com \
  --main-model claude-sonnet-4 \
  --cluster-model claude-sonnet-4

# 2. 配置验证 (检查状态与连通性)
codewiki config show 
codewiki config validate

4️⃣ 生成文档

进入项目根目录，执行核心命令：

• 场景 A：在本地生成标准 Markdown Wiki（默认存入 ./docs/）
• bash

cd /path/to/your/project
codewiki generate
cd /path/to/your/project
codewiki generate

• 场景 B：生成适用于 GitHub Pages 的 HTML 预览版链接
• bash

codewiki generate --github-pages
codewiki generate --github-pages

⚠️ 注意事项与避坑指南

1. Token 消耗预算

• 对中大型项目（如数十万行代码）进行全局深度分析会产生巨量 Token。
• 💡 建议策略：首次使用时，先用小型测试项目试运行。估算单次生成的费用后，再决定是否对超大规模仓库进行分析。

1. 网络与代理设置

• 由于工具需调用外部 API（LLM），请确保本地终端的网络或公司出口代理通畅。
• ❌ 常见报错：API 连接超时、中断或服务不可用通常源于防火墙拦截或缺失的 Proxy 环境配置。

1. Mermaid 依赖检查

• 生成的文档包含大量流程图。若 Node.js 版本过低或未安装相关校验脚本，可能会导致 Mermaid 语法图无法渲染或报错。请确保满足最低运行要求后再生成大文件。