Mini-Wiki Skill 完全指南

自动将代码库生成为企业级结构化 Wiki 文档，输出到 .mini-wiki/ 目录。

核心目标

将任意代码库的结构、逻辑、API、架构自动文档化，生成面向 AI 和架构评审使用的专业级 Wiki。

触发方式

用户指令	说明
`generate wiki`	生成 Wiki
`create docs`	创建文档
`create documentation`	创建文档
`继续生成 wiki`	断点续传
`检查 wiki 质量`	质量评估
`升级 wiki`	渐进式升级旧文档
`刷新全部 wiki`	重新生成全部文档

底层原理

1. 动态质量模型

文档深度不是固定行数，而是根据模块复杂度动态计算：

指标	计算公式
文档行数	`max(100, 源码行数 × 0.3 + 导出接口数 × 20)`
代码示例数	`max(2, 导出接口数 × 0.5)`
图表数量	`max(1, ceil(文件数 / 5))`
章节数	`6 + 模块角色权重`

2. 模块角色权重

角色	权重	期望深度
core (核心模块)	+4	深度分析、完整示例、性能优化
util (工具模块)	+2	接口说明、使用示例
config (配置)	+1	配置项说明、默认值
test (测试)	+0	测试策略、覆盖率
example (示例)	+0	运行说明

3. 业务领域自动识别

不生成扁平的 modules/ 目录，而是按业务域分层：

yaml

domain_mapping:
  AI系统:
    keywords: [agent, ai, llm, chat, mcp, tool]
  存储系统:
    keywords: [store, storage, persist, state]
  编辑器:
    keywords: [editor, tiptap, markdown, document]
  跨平台:
    keywords: [electron, desktop, web, app]
  组件库:
    keywords: [component, ui, shadcn]

完整工作流程

各阶段详解

阶段 1：初始化检查

.mini-wiki/ 不存在 → 全新生成所有文档
已存在 → 读取 config.yaml + cache/checksums.json，执行增量更新

阶段 2：插件发现（安全）

读取 plugins/_registry.yaml 获取启用的插件列表
读取每个插件的 PLUGIN.md 获取 Hook 指令
关键：插件仅提供文本指令，绝不执行插件代码

阶段 3：项目分析

识别技术栈（package.json / requirements.txt / go.mod 等）
找入口点（index.ts / main.py 等）
扫描模块结构
结果保存到 cache/structure.json

阶段 4：深度代码分析（关键）

实际读取源文件内容，不只看目录结构
理解函数语义、参数含义、返回值
分析类层次关系、数据流
识别错误处理模式、设计模式

阶段 5：变更检测

对比文件 checksum
新增文件 → 生成文档
修改文件 → 更新文档
删除文件 → 标记废弃

阶段 6：内容生成

按模块优先级排序后生成：

优先级维度	权重
是否为入口点	5
被其他模块依赖次数	4
有现有文档	3
代码行数	2
最近修改时间	1

阶段 7：质量验证

每批生成后自动验证，未达标则重新生成。

输出目录结构

.mini-wiki/
├── config.yaml                 # 生成配置
├── meta.json                   # 版本信息、质量记录
├── cache/
│   ├── structure.json          # 项目结构缓存
│   ├── checksums.json          # 文件 checksum
│   └── progress.json           # 大型项目渐进式进度
├── wiki/
│   ├── index.md                # 项目首页（含架构预览图）
│   ├── architecture.md         # 系统架构文档
│   ├── getting-started.md      # 快速开始
│   ├── doc-map.md              # 文档关系图
│   │
│   ├── AI系统/                  # 业务领域（自动识别）
│   │   ├── _index.md           # 领域概述
│   │   ├── Agent核心/
│   │   │   ├── 客户端.md       # 400+ 行
│   │   │   └── 工具系统.md
│   │   └── MCP协议/
│   │       └── 配置管理.md
│   │
│   ├── 存储系统/
│   │   ├── _index.md
│   │   └── 状态管理/
│   │       └── Zustand.md
│   │
│   └── api/                    # API 参考
│       └── <module-name>.md
└── plugins/
    └── _registry.yaml

文档质量标准

每个模块文档必须包含（16 章节）

#	章节	说明
1	模块概述	2-3 段详细描述，非 2-3 句
2	核心价值	解释为什么这个模块存在
3	架构位置图	Mermaid flowchart 高亮当前模块
4	功能特性表	功能 → 对应 API 映射
5	文件结构	文件树 + 每个文件职责
6	核心工作流图	Mermaid flowchart
7	状态图	Mermaid stateDiagram（如适用）
8	公共 API 概览表	接口名、签名、说明
9	详细 API 文档	参数表、返回值、示例
10	类型定义	含属性字段表
11	快速开始代码	完整可运行示例
12	3+ 使用场景示例	基础 / 高级 / 错误处理
13	最佳实践	Do's and Don'ts
14	设计决策	解释 Why，记录 trade-offs
15	依赖关系图	Mermaid flowchart LR
16	相关文档链接	交叉引用

Mermaid 图表类型规范

内容类型	图表类型
架构	`flowchart TB` with subgraphs
数据/调用流	`sequenceDiagram`
状态变化	`stateDiagram-v2`
类/接口	`classDiagram` with properties + methods
依赖关系	`flowchart LR`

强制要求：源码可溯源

每个章节末尾必须附加：

markdown

**Section sources**
- [filename.ts](file://path/to/file.ts#L1-L50)

**Diagram sources**
- [architecture.ts](file://src/architecture.ts#L1-L100)

大型项目渐进式策略

触发条件：模块数 > 10，或源文件数 > 50，或代码行数 > 10,000

渐进式执行

✅ 第 2 批完成 (6/25 模块)

已生成:
- AI系统/Agent核心/客户端.md (612 行, Professional ✅)
- 存储系统/Zustand.md (287 行, Professional ✅)

质量检查: 全部通过 ✅

待处理: 19 个模块
预计还需: 10 批次

👉 输入 "继续" 生成下一批
👉 输入 "检查质量" 运行质量检查
👉 输入 "重新生成 <模块名>" 重新生成特定模块

断点续传

进度记录在 cache/progress.json：

json

{
  "total_modules": 25,
  "completed_modules": ["AI系统/Agent核心", "存储系统"],
  "pending_modules": ["编辑器", "跨平台"],
  "current_batch": 3,
  "last_updated": "2026-03-17T10:00:00Z"
}

文档升级机制

版本检测

meta.json 记录每个文档的生成版本和质量等级：

质量等级	章节数	图表数	示例数
`basic`	< 8	0	0-1
`standard`	8-12	1	1-2
`professional`	13-16	2+	3+

升级命令

命令	策略
`升级 wiki`	渐进式升级低质量文档
`刷新全部 wiki`	重新生成所有文档
`升级 <模块> 文档`	只升级指定模块
`检查 wiki 质量`	生成质量评估报告

插件系统

安全模型

插件是纯文本指令，通过 4 个 Hook 影响生成策略，不执行任何代码：

Hook	触发时机
`on_init`	初始化阶段前
`after_analyze`	项目分析完成后
`before_generate`	文档生成前
`after_generate`	文档生成后

插件管理命令（供人工执行）

bash

python scripts/plugin_manager.py list
python scripts/plugin_manager.py install owner/repo
python scripts/plugin_manager.py enable <name>
python scripts/plugin_manager.py disable <name>

关键配置

.mini-wiki/config.yaml 核心选项：

yaml

generation:
  language: zh              # zh / en / both
  detail_level: detailed    # minimal / standard / detailed
  include_diagrams: true
  include_examples: true
  link_to_source: true

progressive:
  enabled: auto             # auto / always / never
  batch_size: 1             # 每批 1-2 个模块
  quality_check: true       # 每批后自动验证
  auto_continue: false      # 是否自动继续（不等确认）

domain_hierarchy:
  enabled: true             # 启用业务领域分层
  auto_detect: true
  language: zh              # 目录名语言

exclude:
  - node_modules
  - dist
  - "*.test.ts"

核心设计哲学

深度优先：读实际源码，理解语义，不只看目录结构
动态标准：文档深度与模块复杂度成正比，避免过浅或过度冗余
可溯源：每章节必须附源文件链接，确保文档与代码同步
增量友好：checksum 检测机制，只更新变更的模块
业务语义：按业务域组织，而非技术层次平铺
安全插件：插件仅提供文本指令，不执行外部代码

文档整理自 mini-wiki skill，日期：2026-03-17

Mini-Wiki Skill 完全指南 ​

核心目标 ​

触发方式 ​

底层原理 ​

1. 动态质量模型 ​

2. 模块角色权重 ​

3. 业务领域自动识别 ​

完整工作流程 ​

各阶段详解 ​

阶段 1：初始化检查 ​

阶段 2：插件发现（安全） ​

阶段 3：项目分析 ​

阶段 4：深度代码分析（关键） ​

阶段 5：变更检测 ​

阶段 6：内容生成 ​

阶段 7：质量验证 ​

输出目录结构 ​

文档质量标准 ​

每个模块文档必须包含（16 章节） ​

Mermaid 图表类型规范 ​

强制要求：源码可溯源 ​

大型项目渐进式策略 ​

渐进式执行 ​

断点续传 ​

文档升级机制 ​

版本检测 ​

升级命令 ​

插件系统 ​

安全模型 ​

插件管理命令（供人工执行） ​

关键配置 ​

核心设计哲学 ​