| name | codewiki-wiki-generator |
| description | 使用 CodeWiki-CN MCP 工具为代码仓库生成 Wiki 文档并管理 LLM Wiki 知识库。当用户要求生成 Wiki、代码文档、仓库文档、分析代码库结构时使用；也适用于查询已有 Wiki（query_wiki）、归档设计决策和经验教训（ingest_note）、检查文档一致性（lint_wiki）。需要已配置 CodeWiki-CN MCP 服务器。可选搭配 CodeGraph MCP 获得调用图和影响范围分析增强。 |
| version | 4.0.0 |
CodeWiki 文档生成器
使用 CodeWiki-CN MCP 工具链为代码仓库生成全面的 Wiki 文档。CodeWiki 提供工具链，你提供全部智能推理能力。
使用边界
做什么： 代码仓库文档生成、Wiki 知识库管理（查询/归档/一致性检查）。
不做什么：
- 不处理非代码类文档生成（报告、PPT、邮件等）
- 不用代码搜索替代 Wiki 查询——「为什么」和「踩过什么坑」类问题只用
query_wiki
- 子代理不得自行调用
analyze_repo 创建新 session，必须共享主代理的 session_id
- Mermaid 节点 ID 禁止使用中文、空格、冒号
阶段 0：环境检测
- 检查 MCP 工具列表中是否存在
analyze_repo。不存在 → 提示用户安装（详见 安装指南）
- 检查是否存在
codegraph_status：
- 存在 → 增强模式（标注
🔗 CodeGraph 增强 的步骤）
- 不存在 → 标准模式（跳过增强步骤）
两种模式产出的文档结构和质量一致，增强模式在模块聚类精度和调用关系描述上更优。
schema.yaml 配置
schema.yaml 是项目的文档"宪法"，控制命名规范、必需章节、文档维度、Mermaid 要求、行数限制、交叉链接开关、lint 阈值等。
- 全局默认值：CodeWiki-CN 安装目录下的
config.yaml 定义与语言无关的默认配置，首次 analyze_repo 时自动读取并生成 output_dir/schema.yaml
- 自定义：修改
config.yaml 改变全局默认值；修改 output_dir/schema.yaml 只影响该项目（增量更新时自动合并保留自定义字段，project 字段始终自动更新）
核心机制：文件侧通道
CodeWiki MCP 采用文件侧通道架构：大体量数据写入磁盘文件，MCP 只返回路径和精简摘要。你需要用自己的文件读取能力读取 workspace 文件获取完整数据。
Workspace 目录：{repo_path}/.codewiki/sessions/{session_id}/
完整文件清单和读取时机见 文件侧通道详解。
五阶段工作流
严格按顺序执行。阶段 1 之后的所有工具调用都需要 analyze_repo 返回的 session_id。
阶段 1：分析仓库
analyze_repo → {"repo_path": "<仓库绝对路径>", "output_dir": "<仓库路径>/repowiki"}
返回 session_id、workspace_dir、stats、files、changes。牢记 session_id。
接下来：
list_components → {"session_id": "...", "summary": true} → 读取返回的 component_summary.json- 读取
{workspace_dir}/summary.json
- 根据 stats 规划聚类策略
- 阶段 3 生成文档时，再调用
list_components(file_prefix: "模块目录/") 获取完整组件 ID
🔗 增强模式额外步骤见 CodeGraph 增强。
阶段 2：模块聚类
这是最需要理解力的阶段。
get_prompt → {"prompt_type": "cluster"} 获取聚类规则read_code_components 读取组件源码（传入 ID 列表 → 写入 sources/*.src → 读取 .src 文件）- 如需补充，直接读取仓库内源文件
- 分组原则：
- 功能内聚：关系紧密的组件放入同一模块
- 文件归属：同文件/目录的组件倾向同一模块
- 规模控制：3-8 个顶层模块，每模块 5-30 个组件
- ID 保留：组件 ID 原样保留（含
:: 分隔符）
🔗 增强模式：用 codegraph_callers/codegraph_callees 验证聚类，详见 CodeGraph 增强。
- 保存模块树：
save_module_tree → {
"session_id": "<session_id>",
"module_tree": {
"模块名": {
"components": ["file.py::ClassA", "file.py::func_b"],
"children": {}
}
}
}
读取返回的 processing_order_file 获取叶优先的处理顺序。
阶段 3：逐模块生成文档
读取 processing_order.json，先处理叶模块，再处理父模块。
并发约束（共享 session_id）：
| 可并发 | 必须串行 |
|---|
write_doc_file / edit_doc_file | list_components（写同一文件） |
read_code_components | |
推荐模式：主代理串行调用 list_components(file_prefix) 获取组件 ID → 2-3 个子代理并发执行（读源码 → 撰写 → 写文档）→ 批次完成后取下一批。
子代理必须使用主代理传入的 session_id 和预获取的组件 ID 列表，不得自行调用 analyze_repo 或 list_components。CodeWiki MCP 最多维护 10 个 session，超出后静默驱逐最久未访问的。
叶模块（is_leaf=true）：
get_prompt → {"prompt_type": "system_leaf", "variables": {"module_name": "<模块名>"}}read_code_components → 读取源码- 🔗 增强模式：收集调用关系数据（详见 CodeGraph 增强）
- 撰写文档：模块简介、架构图（≥1 个 Mermaid）、组件职责、交叉引用
[模块名](模块名.md)
write_doc_file → {"session_id": "...", "filename": "<模块名>.md", "content": "..."}
父模块（is_leaf=false）：
- 读取所有子模块已生成的
.md 文件
get_prompt → {"prompt_type": "overview_module", "variables": {"module_name": "<模块名>"}}- 综合子模块文档生成总览 →
write_doc_file 保存
阶段 4：生成仓库总览
get_prompt → {"prompt_type": "overview_repo", "variables": {"repo_name": "<仓库名>"}}- 读取所有模块文档
- 撰写总览：项目简介 + 端到端架构图（Mermaid）+ 各模块引用链接
write_doc_file → filename: "overview.md"
阶段 5：清理
close_session → {"session_id": "<session_id>"}
🔗 增强模式额外保存增量更新元数据，详见 CodeGraph 增强。
增量更新
当 output_dir/.meta/ 下存在元数据时，analyze_repo 返回 changes 字段（完整数据在 changes.json）。
标准模式：
- 检查
changes → no_changes: true 则告知用户文档已是最新
no_changes: false → 只更新 affected_modules 中的模块- 用
edit_doc_file(str_replace) 局部修改，不整篇重写
- 级联刷新
cascade_modules 的父模块总览 → 更新 overview.md
增强模式：用 codegraph_impact(depth: 2) 实现符号级精度的变更追踪，详见 CodeGraph 增量更新。
回退全量重生成的条件：元数据文件缺失、>50% 模块受影响、新增/删除了不属于任何现有模块的源文件、用户明确要求。
LLM Wiki 知识库
Wiki 生成后，三个知识管理工具无需活跃 session，通过 output_dir 定位 Wiki 即可使用。完整用法和示例见 知识库详解。
工具选择原则
| 信息类型 | 工具 | 禁止用 |
|---|
| 历史踩坑、设计决策、架构约定 | query_wiki | grep / 代码搜索 |
| 函数实现、调用链、文件内容 | grep / 代码搜索 / 直接读文件 | query_wiki |
核心规则：代码里只有 what，没有 why 和 lesson——后者只存在于 Wiki 笔记中。
快速参考
query_wiki — 搜索文档和笔记：
{"query": "自然语言问题", "include_notes": true, "expand_terms": ["同义词1", "同义词2"]}
ingest_note — 归档经验到知识库：
{"note_type": "decision|lesson|architecture|bug_fix|general", "title": "标题", "content": "Markdown 内容", "related_modules": ["模块名"]}
lint_wiki — 文档-代码一致性检查（5 项：过时引用、断链、未文档化组件、循环依赖、覆盖率）：
{}
Mermaid 规范
- 节点 ID 仅用字母和数字
- 节点标签用方括号：
A[显示文本]
- 子图：
subgraph title ... end
- 禁止
click、linkStyle 等交互语法
- 校验失败 → 用
edit_doc_file(str_replace) 修正
文档质量标准
- 语言：默认中文
- 图表：每个叶模块 ≥1 个 Mermaid 架构图，优先
graph TD 或 graph LR
- 交叉引用：
[模块名](模块名.md)
- 篇幅：叶模块 200-500 行，父模块 100-300 行，仓库总览 80-200 行
- 代码示例：关键函数/类展示签名和简要用法
参考文档
按需加载以下参考文档，不要在开始时全部读取：
