🔴 强制要求：源代码可追溯性

每个章节末尾必须包含源代码引用：

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

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

🔴 强制要求：动态质量标准

质量标准基于模块复杂度动态计算，而非固定数字

复杂度评估因子

complexity_factors:
  # 源码指标
  source_lines: 0       # 模块源码行数
  file_count: 0         # 文件数量
  export_count: 0       # 导出的接口数量
  dependency_count: 0   # 依赖的模块数
  dependent_count: 0    # 被依赖次数
  
  # 项目上下文
  project_type: "fullstack"  # frontend / backend / fullstack / library / cli
  language: "typescript"     # typescript / python / go / java / rust
  module_role: "core"        # core / util / config / test / example

动态质量公式

模块角色权重

项目类型适配

语言适配

模块文档章节

根据模块角色动态包含以下章节：

🔴 代码示例（目标受众：AI 与架构评审）

文档主要受众是 AI 和架构评审，代码示例必须：

1. 完整可运行：包含 import、初始化、调用、结果处理

2. 覆盖导出接口：每个主要导出 API 至少 1 个示例

3. 包含注释说明：解释关键步骤和设计意图

4. 适配项目语言：遵循语言最佳实践

   // ✅ 好的示例：完整、可运行、有注释 import { AgentClient } from '@editverse/agent-core';

   // 1. 创建客户端（展示必需配置） const agent = await AgentClient.create({ provider: 'openai', model: 'gpt-4', });

   // 2. 基础对话 const response = await agent.chat({ messages: [{ role: 'user', content: '你好' }], }); console.log(response.content);

   // 3. 错误处理 try { await agent.chat({ messages: [] }); } catch (error) { if (error.code === 'INVALID_MESSAGES') { console.error('消息列表不能为空'); } }

示例类型根据导出 API 数量动态调整：

🔴 强制要求：核心类的 classDiagram

对于每个核心类/接口，生成详细的 classDiagram：

classDiagram
class ClassName {
  +property1 : Type
  +property2 : Type
  -privateField : Type
  +method1(param : Type) : ReturnType
  +method2() : void
}

文档关系

• 每份文档必须有 "相关文档" 章节
• 模块文档链接到：架构位置、API 参考、依赖项
• API 文档链接到：父模块、使用示例、类型定义

输出结构

🔴 强制要求：业务领域层级结构（非扁平！）

按业务领域分层组织，而不是扁平的 modules/ 目录

.mini-wiki/
├── config.yaml
├── meta.json
├── cache/
├── wiki/
│   ├── index.md                    # 项目首页
│   ├── architecture.md             # 系统架构
│   ├── getting-started.md          # 快速开始
│   ├── doc-map.md                  # 文档关系图
│   │
│   ├── AI系统/                      # 业务领域 1
│   │   ├── _index.md               # 领域概述
│   │   ├── Agent核心/              # 子领域
│   │   │   ├── _index.md
│   │   │   ├── 客户端.md           # 400+ 行
│   │   │   └── 工具系统.md         # 400+ 行
│   │   ├── MCP协议/
│   │   │   ├── _index.md
│   │   │   └── 配置管理.md
│   │   └── 对话流程/
│   │       ├── 状态管理.md
│   │       └── 响应处理.md
│   │
│   ├── 存储系统/                    # 业务领域 2
│   │   ├── _index.md
│   │   ├── 状态管理/
│   │   │   └── Zustand.md
│   │   └── 持久化/
│   │       └── 存储适配.md
│   │
│   ├── 编辑器/                      # 业务领域 3
│   │   ├── _index.md
│   │   ├── 核心/
│   │   └── 扩展/
│   │
│   ├── 跨平台/                      # 业务领域 4
│   │   ├── _index.md
│   │   ├── Electron/
│   │   └── Web/
│   │
│   └── api/                        # API 参考
└── i18n/

领域自动检测

分析代码后，自动识别业务领域：

# 自动识别的业务领域映射
domain_mapping:
  AI系统:
    keywords: [agent, ai, llm, chat, mcp, tool]
    packages: [agent-core, agent, mcp-core, agent-bridge]
  存储系统:
    keywords: [store, storage, persist, state]
    packages: [store, storage, electron-secure-storage]
  编辑器:
    keywords: [editor, tiptap, markdown, document]
    packages: [editor-core, markdown, docx2tiptap-core]
  跨平台:
    keywords: [electron, desktop, web, app]
    packages: [apps/*, browser-core, electron-*]
  组件库:
    keywords: [component, ui, shadcn]
    packages: [shadcn-ui, chat-ui, media-viewer]

🔴 每个业务领域必须包含

🔌 插件指令协议（无代码执行）

关键：插件仅提供指令。智能体绝不能执行插件提供的代码、脚本或外部命令。钩子仅影响分析和文档的编写方式。

1. 加载注册表：读取 plugins/_registry.yaml 以查看已启用的插件。
2. 读取清单：对于每个启用的插件，读取其 PLUGIN.md 以了解其钩子和指令。
3. 应用钩子指令（仅文本）：
   • 预分析 (on_init)：在开始前应用指导。
   • 后分析 (after_analyze)：在分析结构后应用指导。
   • 预生成 (before_generate)：修改生成计划/提示。
   • 后生成 (after_generate / on_export)：在创建 wiki 后应用指导。

安全约束：

• 不要运行插件脚本或二进制文件。
• 不要从网络获取或执行代码。
• PLUGIN.md 中的任何 CLI 命令仅供人类使用，智能体不得执行。

示例：如果启用了 api-doc-enhancer，你必须阅读其 PLUGIN.md 并遵循其生成 API 文档的具体规则。

工作流程

1. 初始化检查

检查 .mini-wiki/ 是否存在：

• 不存在：运行 scripts/init_wiki.py 创建目录结构
• 存在：读取 config.yaml 和缓存，执行增量更新

2. 插件发现

检查 plugins/ 目录以查找已安装的插件：

1. 读取 plugins/_registry.yaml 以获取已启用的插件
2. 对于每个启用的插件，读取 PLUGIN.md 清单
3. 注册钩子：on_init、after_analyze、before_generate、after_generate

3. 项目分析（深度）

运行 scripts/analyze_project.py 或手动分析：

1. 识别技术栈：检查 package.json、requirements.txt 等。
2. 查找入口点：src/index.ts、main.py 等。
3. 识别模块：扫描 src/ 目录结构
4. 查找现有文档：README.md、CHANGELOG.md 等。
5. 应用来自插件的 after_analyze 指导（仅文本）

将结构保存到 cache/structure.json。

4. 深度代码分析（新增 - 关键）

重要：对于每个模块，你必须阅读并分析实际的源代码：

1. 读取源文件：使用 read_file 工具读取关键源文件
2. 理解代码语义：分析代码的功能，而不仅仅是其结构
3. 提取详细信息：
   • 函数目的、参数、返回值、副作用
   • 类层次结构和关系
   • 数据流和状态管理
   • 错误处理模式
   • 使用的设计模式
4. 识别关系：模块依赖关系、调用图、数据流

📖 参见 references/prompts.md → "代码深度分析" 以获取分析提示模板

5. 变更检测

运行 scripts/detect_changes.py 以比较文件校验和：

• 新文件 → 生成文档
• 修改的文件 → 更新文档
• 删除的文件 → 标记为过时

6. 内容生成（专业级）

应用来自插件的 before_generate 指导（仅文本），然后遵循严格的质量标准生成内容：

6.1 首页 (index.md)

必须包含：

• 项目徽章和一句话描述
• 2-3 段详细介绍（不仅仅是要点列表）
• 架构预览图（Mermaid 流程图）
• 带有受众群体的文档导航表
• 核心功能表，链接到模块
• 快速开始代码示例及预期输出
• 项目统计表
• 模块概览表，包含链接

6.2 架构文档 (architecture.md)

必须包含：

• 执行摘要（定位、技术概览、架构风格）
• 系统架构图（带有子图的 Mermaid flowchart TB）
• 技术栈表，包含版本和选择理由
• 模块依赖关系图（Mermaid 流程图）
• 详细的模块描述，包含职责和接口
• 数据流图（Mermaid sequenceDiagram）
• 状态管理图（如果适用）
• 目录结构及说明
• 设计模式和原则
• 扩展指南

6.3 模块文档 (modules/<name>.md)

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

1. 模块概述（2-3 段，不是 2-3 句）
2. 核心价值主张
3. 架构位置图（突出显示当前模块）
4. 功能表，包含相关 API
5. 文件结构及职责描述
6. 核心工作流图（Mermaid 流程图）
7. 状态图（如果适用）
8. 公共 API 概览表
9. 详细的 API 文档（签名、参数、返回值、示例）
10. 类型定义，包含字段表
11. 快速开始代码
12. 3+ 个使用示例，包含场景
13. 最佳实践（推荐做法与避免做法）
14. 设计决策和权衡
15. 依赖关系图
16. 相关文档链接

6.4 API 文档 (api/<name>.md)

每个 API 文档必须包含：

• 模块概述，包含导入示例
• API 概览表
• 类型定义，包含属性表
• 对于每个函数：
  • 一句话描述 + 详细描述（3+ 句）
  • 函数签名
  • 参数表，包含约束和默认值
  • 返回值，包含可能的情况
  • 异常表
  • 3 个代码示例（基础、高级、错误处理）
  • 警告和提示
  • 相关 API
• 对于类：类图、构造函数、属性、方法
• 使用模式（2-3 个完整场景）
• 常见问题解答部分
• 相关文档

6.5 快速开始 (getting-started.md)

必须包含：

• 先决条件表，包含版本要求
• 多种安装方法
• 配置文件说明
• 分步第一个示例
• 后续步骤表
• 常见问题解答

6.6 文档地图 (doc-map.md)

必须包含：

• 文档关系图（Mermaid 流程图）
• 按角色推荐的阅读路径
• 完整的文档索引
• 模块依赖矩阵

应用来自插件的 after_generate 指导（仅文本）。

7. 源代码链接

向代码块添加源代码链接：

### `functionName` [📄](file:///path/to/file.ts#L42)

8. 保存

• 将 wiki 文件写入 .mini-wiki/wiki/
• 更新 cache/checksums.json
• 更新 meta.json 时间戳

🚀 大型项目渐进式扫描

问题：对于大型项目，AI 可能只生成少量文档而没有全面覆盖所有模块。

触发条件

当项目满足以下任一条件时，必须使用渐进式扫描策略：

• 模块数量 > 10
• 源文件数量 > 50
• 代码行数 > 10,000

渐进式扫描策略

flowchart TB
    A[项目分析] --> B{模块数量 > 10?}
    B -->|是| C[启用渐进式扫描]
    B -->|否| D[标准扫描]
    C --> E[模块优先级排序]
    E --> F[批次划分]
    F --> G[逐批生成文档]
    G --> H{还有未处理模块?}
    H -->|是| I[保存进度]
    I --> J[提示用户继续]
    J --> G
    H -->|否| K[生成索引和关系图]

执行步骤

Step 1: 模块优先级排序

按以下维度计算优先级分数：

Step 2: 批次划分

🔴 关键：每批 1-2 个模块，深度基于模块复杂度动态调整

batch_config:
  batch_size: 1              # 每批处理 1-2 个模块
  quality_mode: dynamic      # dynamic / fixed
  pause_between_batches: true
  auto_continue: false

批次分配示例（按业务领域 + 复杂度）:

Step 3: 进度跟踪

在 cache/progress.json 中记录：

{
  "version": "2.0.0",
  "total_modules": 25,
  "completed_modules": ["core", "utils", "api"],
  "pending_modules": ["auth", "db", ...],
  "current_batch": 2,
  "last_updated": "2026-01-28T21:15:00Z",
  "quality_version": "professional-v2"
}

Step 4: 断点续传

当用户说 "继续生成 wiki" 或 "continue wiki generation" 时：

1. 读取 cache/progress.json
2. 跳过已完成的模块
3. 从下一批次继续

🔴 每批次质量检查

生成每批后，必须验证质量：

# 检查本批生成的文档
python scripts/check_quality.py .mini-wiki --verbose

质量门槛（动态计算）：

质量检查基于模块复杂度动态评估，而非固定数字：

# 运行动态质量检查
python scripts/check_quality.py .mini-wiki --analyze-complexity

质量评级：

用户交互提示

每批次完成后，向用户报告：

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

已生成:
- modules/store.md (245 行, Professional ✅)
- modules/editor-core.md (312 行, Professional ✅)

质量检查: 全部通过 ✅

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

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

配置选项

# .mini-wiki/config.yaml
progressive:
  enabled: auto               # auto / always / never
  batch_size: 1               # 每批模块数（1-2 确保深度）
  min_lines_per_doc: 400      # 每个文档最少行数
  min_code_examples: 5        # 每个文档最少代码示例数
  quality_check: true         # 每批后自动检查质量
  auto_continue: false        # 自动继续无需确认
  
# 业务领域分层配置
domain_hierarchy:
  enabled: true               # 启用业务领域分层
  auto_detect: true           # 自动识别业务领域
  language: zh                # 目录名语言 (zh/en)
  priority_weights:           # 自定义优先级权重
    entry_point: 5
    dependency_count: 4
    code_lines: 2
    has_docs: 3
    recent_modified: 1
  skip_modules:               # 跳过的模块
    - __tests__
    - examples

🔄 文档升级与刷新

问题：升级 mini-wiki 后，之前生成的低质量文档需要刷新升级。

版本检测机制

在 meta.json 中记录文档生成版本，并在每个文档页脚显示：

页脚格式：*由 [Mini-Wiki v{{ MINI_WIKI_VERSION }}](https://github.com/trsoliu/mini-wiki) 自动生成 | {{ GENERATED_AT }}*

{
  "generator_version": "3.0.6",  // 用于 {{ MINI_WIKI_VERSION }}
  "quality_standard": "professional-v2",
  "generated_at": "2026-01-28T21:15:00Z",
  "modules": {
    "core": {
      "version": "1.0.0",
      "quality": "basic",
      "sections": 6,
      "has_diagrams": false,
      "last_updated": "2026-01-20T10:00:00Z"
    }
  }
}

质量评估标准

升级触发条件

flowchart TB
    A[检测 .mini-wiki/] --> B{meta.json 存在?}
    B -->|否| C[全新生成]
    B -->|是| D[读取版本信息]
    D --> E{版本 < 2.0.0?}
    E -->|是| F[标记需要升级]
    E -->|否| G{quality != professional?}
    G -->|是| F
    G -->|否| H[增量更新]
    F --> I[生成升级计划]
    I --> J[提示用户确认]

升级策略

策略 1: 全量刷新 (refresh_all)

适用于：版本差异大、文档质量差

用户命令: "刷新全部 wiki" / "refresh all wiki"

策略 2: 渐进式升级 (upgrade_progressive)

适用于：模块多、希望保留部分内容

用户命令: "升级 wiki" / "upgrade wiki"

策略 3: 选择性升级 (upgrade_selective)

适用于：只想升级特定模块

用户命令: "升级 core 模块文档" / "upgrade core module docs"

升级执行流程

Step 1: 扫描现有文档

# 伪代码
for doc in existing_docs:
    score = evaluate_quality(doc)
    if score.sections < 10 or not score.has_diagrams:
        mark_for_upgrade(doc, priority=HIGH)
    elif score.sections < 13:
        mark_for_upgrade(doc, priority=MEDIUM)

Step 2: 生成升级报告

📊 Wiki 升级评估报告

当前版本: 1.0.0 (basic)
目标版本: 2.0.0 (professional)

需要升级的文档:
┌─────────────────┬──────────┬────────┬─────────┬──────────┐
│ 文档            │ 当前章节 │ 目标   │ 缺少图表│ 优先级   │
├─────────────────┼──────────┼────────┼─────────┼──────────┤
│ modules/core.md │ 6        │ 16     │ 是      │ 🔴 高    │
│ modules/api.md  │ 8        │ 16     │ 是      │ 🔴 高    │
│ modules/utils.md│ 10       │ 16     │ 否      │ 🟡 中    │
│ architecture.md │ 5        │ 12     │ 是      │ 🔴 高    │
└─────────────────┴──────────┴────────┴─────────┴──────────┘

👉 输入 "确认升级" 开始，或 "跳过 <文档>" 排除特定文档

Step 3: 保留与合并

升级时保留：

• 用户手动添加的内容（通过 <!-- user-content --> 标记）
• 自定义配置
• 历史版本备份到 cache/backup/

Step 4: 渐进式升级执行

🔄 正在升级 modules/core.md (1/8)

升级内容:
  ✅ 扩展模块概述 (2句 → 3段)
  ✅ 添加架构位置图
  ✅ 添加核心工作流图
  ✅ 扩展 API 文档 (添加3个示例)
  ✅ 添加最佳实践章节
  ✅ 添加设计决策章节
  ✅ 添加依赖关系图
  ✅ 添加相关文档链接

章节数: 6 → 16 ✅
图表数: 0 → 3 ✅

配置选项

# .mini-wiki/config.yaml
upgrade:
  auto_detect: true           # 自动检测需要升级的文档
  backup_before_upgrade: true # 升级前备份
  preserve_user_content: true # 保留用户自定义内容
  user_content_marker: "<!-- user-content -->"
  upgrade_strategy: progressive  # all / progressive / selective
  min_quality: professional   # 最低质量要求

用户命令

插件系统

安全模型：插件仅提供文本指令，用于影响分析与写作策略；不执行任何插件代码/脚本。

插件命令

安装来源：

• 本地：/path/to/plugin
• GitHub：owner/repo（例如，trsoliu/mini-wiki-extras）
• Skills.sh：任何兼容的技能仓库
• URL：https://example.com/plugin.zip

注意：通用技能（SKILL.md）将自动包装为插件。这些仍然是仅指令，并且不作为代码执行。

插件脚本

python scripts/plugin_manager.py list
python scripts/plugin_manager.py install owner/repo
python scripts/plugin_manager.py install ./my-plugin

仅限手动：CLI 命令仅供人类使用。智能体不得运行插件脚本或外部命令。

创建插件

参见 references/plugin-template.md 了解插件格式。

插件支持钩子：

• on_init - 初始化指导
• after_analyze - 添加分析指导
• before_generate - 修改提示/生成指导
• after_generate - 后处理指导
• on_export - 导出指导

脚本参考

质量检查脚本

# 基本检查
python scripts/check_quality.py /path/to/.mini-wiki

# 详细报告
python scripts/check_quality.py /path/to/.mini-wiki --verbose

# 导出 JSON 报告
python scripts/check_quality.py /path/to/.mini-wiki --json report.json

检查项目：

• 行数 (≥200)
• 章节数 (≥9)
• 图表数 (≥2-3)
• classDiagram 类图
• 代码示例 (≥3)
• 源码追溯 (Section sources)
• 必需章节 (最佳实践、性能优化、错误处理)

质量等级：

参考资料

参见 references/ 目录以获取详细的模板和提示：

• prompts.md：用于生成专业级内容的 AI 提示模板
  • 通用质量标准 (Universal quality standards)
  • 代码深度分析 (Deep code analysis)
  • 模块文档 (Module documentation - 16 sections)
  • 架构文档 (Architecture documentation)
  • API 文档 (API reference)
  • 首页 (Homepage)
  • 关系图谱 (Document relationship map)
• templates.md：包含 Mermaid 图表的 Wiki 页面模板
  • 首页模板 (Homepage template)
  • 架构文档模板 (Architecture template)
  • 模块文档模板 (Module template - comprehensive)
  • API 参考模板 (API reference template)
  • 快速开始模板 (Getting started template)
  • 文档索引模板 (Doc map template)
  • 配置模板 (Config template)
• plugin-template.md：插件格式

配置

.mini-wiki/config.yaml 格式：

generation:
  language: zh              # zh / en / both
  detail_level: detailed    # minimal / standard / detailed
  include_diagrams: true    # Generate Mermaid diagrams
  include_examples: true    # Include code examples
  link_to_source: true      # Link to source files
  min_sections: 10          # Minimum sections per module doc

diagrams:
  architecture_style: flowchart TB
  dataflow_style: sequenceDiagram
  use_colors: true          # Color-code module types

linking:
  auto_cross_links: true    # Auto-generate cross references
  generate_doc_map: true    # Generate doc-map.md
  generate_dependency_graph: true

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

每周安装量

141

仓库

trsoliu/mini-wiki

GitHub 星标数

49

首次出现

Jan 26, 2026

安全审计

Gen Agent Trust HubPassSocketPassSnykFail

安装于

opencode112

codex107

cursor107

gemini-cli105

github-copilot97

kimi-cli88