内容
<div align="center">
# 自动维基
**工业级代码知识库自动生成引擎**
[](https://github.com/izhengnan/autowiki-mcp/actions/workflows/ci.yml)
</div>
一款可复用的 [MCP Server](https://modelcontextprotocol.io) + [Claude Code](https://claude.ai) 技能，能够从任意代码库自动生成 **50+ 篇**工业级 Wiki 文档。在目标项目中运行 `/autowiki`，即可获得带 Mermaid 图表、行级代码溯源、故障排查指南的深度文档。
> **推荐搭配：** Claude Code + Opus 4.7 效果最佳，其他版本亦可使用。
---
## 概述
自动维基扫描您的项目，分析依赖关系，并跨 **10 个类别** 生成全面文档。每个页面遵循 **11 节模板**，并包含 **7 项强制质量检查**。
### 文档分类
| 分类 | 覆盖范围 |
|------|---------|
| 全局与规范 | 技术栈、目录结构、系统概述、开发者指南 |
| 前端架构 | 路由、状态管理、组件树、API 集成 |
| 后端架构（MVC） | Controller、Service、Mapper 层及调用链路 |
| 后端架构（设计） | 实体模型、DTO、统一响应、分层规范 |
| 后端架构（依赖管理） | DI 机制、组件调用链、启动流程 |
| 数据库设计 | ER 图、表结构、索引、典型查询 |
| 核心功能设计 | 领域模型、状态机、业务引擎、定时任务 |
| API 接口文档 | 端点参考、请求/响应结构 |
| 安全设计 | JWT 认证、RBAC 权限、数据保护 |
| 部署与配置 | 环境配置、数据库配置、部署拓扑 |
---
## 快速开始
```bash
# 1. 安装依赖
npm install
# 2. 注册为全局 MCP Server
claude mcp add autowiki -- node "$(pwd)/index.js"
# 3. 安装技能
mkdir -p ~/.claude/skills/autowiki
cp SKILL.md ~/.claude/skills/autowiki/SKILL.md
# 4. 重启 Claude Code，在任意项目中输入：
/autowiki
```
系统会自动扫描源码树、分 5 批排期 50+ 个文档任务，全部输出到 `docs/wiki/` 目录。
---
## 工作原理
自动维基运行一个 **多阶段管道**：
### 1. 领域驱动规划
扫描项目树并为 10 个类别安排 50+ 个任务，分 5 批执行 — 全局变量、数据库、后端、前端、核心业务 + API、安全 + 部署。
### 2. 依赖分析
对于每个任务，分析 `import`/`require` 语句以识别相关源文件，确保每个文档都有全面的上下文（≥6 个文件每页）。
### 3. 串行写作循环
一次一个任务，系统：
- 读取所有相关源文件，带有**实际行号**
- 编写带有 **11 节 Markdown** 和 **4+ Mermaid 图表**的页面
- 包括 `<cite>` 块，追溯每个声明到源代码
### 4. 质量验证
每个提交都经过 **7 项自动检查**，然后再保存 — 字数、章节覆盖率、图表数量、引用数量、附录代码示例、Mermaid 语法和引用块存在。
### 5. 人工编辑保护
手动编辑的块（标记为 `<!-- human-edited -->`）在重新生成时被保留 — 永远不会覆盖您的自定义。
---
## 使用场景
| 场景 | 描述 |
|------|-------------|
| **入职** | 新团队成员在几分钟内获得完整的代码库文档 |
| **旧系统复兴** | 为无文档或废弃的代码库生成深度文档 |
| **API 文档** | 自动生成的端点引用，带有 curl 示例 |
| **知识保留** | 防止关键开发人员离开时知识流失 |
### 不适用场景
- 替换需要产品级决策的手写设计文档
- 面向公众的开发者门户（输出为团队内部 Wiki 质量）
- 即时预览或实时编辑 — 它是一个批量生成工具
---
## 先决条件
- **Node.js** ≥ 18
- **Claude Code** CLI 已安装并认证
## 技术栈
| 组件 | 技术 |
|-----------|-----------|
| 运行时 | Node.js 18+ |
| 协议 | [MCP SDK](https://github.com/modelcontextprotocol/sdk) |
| 文件扫描 | [fast-glob](https://github.com/mrmlnc/fast-glob) |
| 技能定义 | Claude Code SKILL.md |
---
## MCP 工具
| 工具 | 功能 |
|------|----------|
| `autowiki_get_project_tree` | 扫描项目源结构 |
| `autowiki_analyze_dependencies` | 基于 AST 的 import/require 推断 |
| `autowiki_scan_files` | 基于 glob 模式的文件扫描 |
| `autowiki_clear_task_queue` | 重置任务队列 |
| `autowiki_add_tasks_to_queue` | 批量添加文档任务 |
| `autowiki_get_pending_task` | 获取下一个任务（注入 11 节模板） |
| `autowiki_submit_task` | 提交并进行 7 项质量检查 |
| `autowiki_append_knowledge` | 将片段知识附加到现有卡片 |
---
## 质量门控
每个提交的文档必须通过这些检查：
| 检查 | 阈值 |
|-------|-----------|
| 字数 | ≥ 2000 个字符 |
| 引证块 | `<cite>` 标签必须存在 |
| 引用文件 | ≥ 4 个唯一源文件 |
| Mermaid 图表 | 每页 ≥ 4 个（图、序列图、流程图、ER/类图） |
| 章节覆盖率 | ≥ 11 个必需章节中的 8 个 |
| 附录 | 可运行的代码示例（curl、JS 或 Java） |
| Mermaid 语法 | 无未引用的 `@` 符号，ER 图属性中无 `;` |
如果失败，服务器会返回一个详细的遗漏列表 — 修改并重新提交。
---
## 项目结构
```
autowiki-mcp/
├── index.js # MCP Server（任务队列 + 验证引擎）
├── package.json # 依赖项
├── SKILL.md # Claude Code 技能定义（写作规则 + 管道）
├── README.md # 本文件
├── .gitignore
├── .github/workflows/
│ └── ci.yml # GitHub Actions CI
├── test/
│ └── human-edited.test.js
└── docs/wiki/ # 生成的 Wiki 输出（运行时创建）
```
---
## 命令
```bash
npm install # 安装依赖
npm test # 运行测试套件（4 个测试）
node index.js # 启动 MCP Server（用于调试/手动使用）
```
---
## 设计原则
纯 LLM 驱动的文档生成有三个缺陷：**输出截断**、**上下文缺失** 和 **结构不一致**。自动维基通过工程方法解决了每个问题：
| 缺陷 | 解决方案 |
|--------|----------|
| 长 JSON 输出截断 | 5 批次调度，8-15 个任务/批次 |
| 缺失相关源文件 | `autowiki_analyze_dependencies` 代码级推断 |
| 文档章节遗漏 | `requiredSections` 模板注入 + 服务器端验证 |
| 图表数量不足 | 强制 `minDiagrams: 4`，不满足则拒绝 |
| 行号幻觉 | 强制使用 `Read` 工具输出的真实行号 |
---
## 自定义
`SKILL.md` 文件是文档结构、类别和质量阈值的唯一来源。编辑它以：
- 添加或删除文档类别
- 调整质量检查阈值
- 更改 11 节写作模板
- 添加项目特定术语规则
对于项目特定规则，请添加 `CLAUDE.md` 或追加到现有的文件中。
---
## 许可证
MIT
---
## 概述
自动维基是一个 MCP Server + Claude Code 技能，能够从任意代码库自动生成 **50+ 篇**工业级 Wiki 文档。在目标项目中运行 `/autowiki`，即可获得带 Mermaid 图表、行级代码溯源、故障排查指南的深度文档。
> **推荐搭配：** Claude Code + Opus 4.7 效果最佳，其他版本亦可使用。
### 文档分类
| 分类 | 覆盖范围 |
|------|---------|
| 全局与规范 | 技术栈、目录结构、系统概述、开发者指南 |
| 前端架构 | 路由、状态管理、组件树、API 集成 |
| 后端架构（MVC） | Controller、Service、Mapper 层及调用链路 |
| 后端架构（设计） | 实体模型、DTO、统一响应、分层规范 |
| 后端架构（依赖管理） | DI 机制、组件调用链、启动流程 |
| 数据库设计 | ER 图、表结构、索引、典型查询 |
| 核心功能设计 | 领域模型、状态机、业务引擎、定时任务 |
| API 接口文档 | 端点参考、请求/响应结构 |
| 安全设计 | JWT 认证、RBAC 权限、数据保护 |
| 部署与配置 | 环境配置、数据库配置、部署拓扑 |
### 快速开始
```bash
# 1. 安装依赖
npm install
# 2. 注册为全局 MCP Server
claude mcp add autowiki -- node "$(pwd)/index.js"
# 3. 安装技能
mkdir -p ~/.claude/skills/autowiki
cp SKILL.md ~/.claude/skills/autowiki/SKILL.md
# 4. 重启 Claude Code，在任意项目中输入：
/autowiki
```
系统会自动扫描源码树、分 5 批排期 50+ 个文档任务，全部输出到 `docs/wiki/` 目录。
### 工作流程
1. **领域排期** — 按 10 大分类分 5 批追加任务
2. **依赖分析** — 通过 import/require 推导关联文件，确保每篇文档 ≥6 个引用文件
3. **串行撰写** — 逐个读取源文件 → 按 11 段模板撰写 → 嵌入 4+ 个 Mermaid 图表
4. **质量校验** — 7 项自动检查，不达标详细打回
5. **人工保护** — `<!-- human-edited -->` 区块在重新生成时自动保留
### 适用场景
| 场景 | 说明 |
|------|------|
| **团队 onboarding** | 新成员几分钟内获完整代码库文档 |
| **遗留系统重建** | 为无文档或废弃项目生成深度文档 |
| **API 文档** | 自动生成带 curl 示例的接口文档 |
| **知识留存** | 防止核心人员离开导致知识断层 |
### 质量校验
| 检查项 | 阈值 |
|--------|------|
| 字数 | ≥ 2000 字符 |
| 溯源区块 | 必须包含 `<cite>` 标签 |
| 引用文件 | ≥ 4 个唯一文件 |
| Mermaid 图表 | ≥ 4 个（graph/sequence/flowchart/ER-class） |
| 章节覆盖 | ≥ 8/11 段 |
| 附录代码 | 可运行的 curl、JS 或 Java 示例 |
| Mermaid 语法 | @ 符号必须加引号，ER 属性不能有分号 |
### 项目结构
```
autowiki-mcp/
├── index.js # MCP Server 主程序（任务队列 + 校验引擎）
├── package.json # 依赖声明
├── SKILL.md # Claude Code 技能定义（写作规范 + 排期管线）
├── README.md # 本文件
├── .gitignore
├── .github/workflows/
│ └── ci.yml # GitHub Actions CI
├── test/
│ └── human-edited.test.js
└── docs/wiki/ # 生成的 Wiki 文档目录（运行时自动创建）
```
### 设计原理
纯 LLM 驱动的文档生成有三大缺陷：**输出截断**、**上下文遗漏**、**结构不一致**。本引擎通过以下手段逐一破解：
| 缺陷 | 对策 |
|------|------|
| 长 JSON 输出截断 | 分 5 批次排期，每次只追加 8-15 个任务 |
| 找不全关联文件 | `autowiki_analyze_dependencies` 代码级依赖推导 |
| 文档章节遗漏 | `requiredSections` 模板注入 + 服务端校验打回 |
| 图表数量不足 | 强制 `minDiagrams: 4`，不达标拒绝保存 |
| 行号幻觉 | 强制引用 `Read` 工具返回的真实行号 |
### 自定义扩展
编辑 `SKILL.md` 即可调整文档结构、分类树和质量阈值。项目级别的配置可在 `CLAUDE.md` 中添加。
### 命令
```bash
npm install # 安装依赖
npm test # 运行测试（4 个用例）
node index.js # 启动 MCP Server（调试用）
```
### 许可证
MIT
