业务知识获取与 Skill 文档编写工作流
本 Skill 描述了从外部文档（如 iWiki）获取业务知识，结合代码分析，最终沉淀为高质量 Skill 文档的完整工作流。
触发条件
当用户需要：
- 熟悉一个新的业务模块或子系统
- 从 iWiki 或其他文档系统获取业务知识
- 将文档内容与实际代码进行交叉验证
- 生成或重构模块架构文档
- 将业务知识沉淀为可复用的 Skill
核心工作流
┌─────────────────────────────────────────────────────────────────┐
│ 业务知识获取工作流 │
├─────────────────────────────────────────────────────────────────┤
│ │
│ 阶段 1：文档获取 阶段 2：代码验证 阶段 3：知识沉淀 │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ iWiki 搜索 │───────▶│ 代码定位 │───────▶│ 文档重构 │ │
│ │ 文档阅读 │ │ 交叉验证 │ │ Skill 编写 │ │
│ │ 结构提取 │ │ 补充细节 │ │ 质量审查 │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘阶段 1：文档获取
1.1 使用 iWiki MCP 工具搜索
工具：iWiki.searchDocument
参数：query = "模块名称 + 关键词"搜索策略：
| 场景 | 搜索词示例 |
|---|---|
| 了解模块架构 | Buildless 架构设计 |
| 了解具体功能 | Buildless 任务调度 |
| 了解数据模型 | Buildless Redis 存储 |
1.2 获取文档内容
工具：iWiki.getDocument
参数：docId = 搜索结果中的文档 ID关键提取项：
- 背景与目标
- 核心概念/术语
- 架构设计图
- 流程说明
- 数据模型
- 配置说明
1.3 构建知识框架
从文档中提取并整理：
## 初步知识框架
### 核心概念
- 概念 A：xxx
- 概念 B：xxx
### 架构要点
- 组件关系
- 数据流向
### 待验证问题
- [ ] 代码中是否如此实现？
- [ ] 是否有遗漏的细节？阶段 2：代码验证
2.1 定位核心代码
根据文档中的类名、方法名、配置项定位代码：
工具：search_content / search_file
策略：
1. 搜索核心类名 → 找到入口
2. 搜索关键方法 → 理解流程
3. 搜索配置项 → 确认参数示例搜索序列：
# 1. 找核心服务类
search_content: "class BuildLessStartDispatcher"
# 2. 找核心方法
search_content: "fun canDispatch"
# 3. 找配置项
search_content: "dispatch.buildless"2.2 交叉验证
将文档描述与实际代码对照：
| 文档描述 | 代码验证 | 结果 |
|---|---|---|
| Redis Key 格式 | 检查实际 Key 定义 | ✅ 一致 / ⚠️ 有差异 |
| 流程步骤 | 检查方法调用链 | ✅ 一致 / ⚠️ 有差异 |
| 数据模型 | 检查实体类定义 | ✅ 一致 / ⚠️ 有差异 |
2.3 补充代码细节
文档通常缺失的内容：
- 异常处理逻辑
- 边界条件判断
- 性能优化细节
- 依赖注入关系
- 配置默认值
补充方式：
// 从代码中提取关键逻辑
data class CodeInsight(
val className: String,
val keyMethod: String,
val businessLogic: String,
val edgeCases: List<String>
)阶段 3：知识沉淀
3.1 文档重构原则
精简原则：
| 原则 | 说明 |
|---|---|
| 去重 | 相同内容只保留一处 |
| 聚合 | 分散的相关内容合并 |
| 分层 | 概述 → 详情 → 代码 |
| 表格化 | 列表内容转表格 |
结构模板：
# 模块名称
## 概述
一句话说明 + 核心特点表格
## 架构设计
一图说明 + 组件表格
## 核心流程
流程图 + 阶段说明表
## 数据模型
ER 图 + 字段表格
## 配置参考
配置项表格
## 代码索引
文件路径表格3.2 重构检查清单
- 无重复内容（同一概念只出现一次）
- 无冗余流程图（合并相似图示）
- 代码示例精简（只保留关键逻辑）
- 表格优于长文本
- 层次清晰（可快速定位）
3.3 生成 Skill 文档
按照 skill-writer 规范创建：
---
name: module-name-architecture
description: 模块描述。当用户需要了解 xxx、开发 xxx 功能时使用。
---工具使用速查
iWiki MCP 工具
| 工具 | 用途 | 常用参数 |
|---|---|---|
searchDocument | 搜索文档 | query |
getDocument | 获取内容 | docId |
getSpacePageTree | 获取目录 | spaceKey, parentId |
metadata | 获取元数据 | docId |
代码分析工具
| 工具 | 用途 | 示例 |
|---|---|---|
search_content | 搜索代码内容 | 类名、方法名、字符串 |
search_file | 搜索文件名 | *.kt, *Service.kt |
read_file | 读取文件 | 查看完整实现 |
list_files | 列出目录 | 了解模块结构 |
实战案例：Buildless 模块
第一步：iWiki 文档获取
1. searchDocument("Buildless 无编译构建机")
2. getDocument(docId) → 获取 2000+ 行原始文档
3. 提取核心概念：容器池、任务队列、DeferredResult第二步：代码交叉验证
1. search_content("BuildLessStartDispatcher") → 入口类
2. search_content("BuildLessTaskResource") → API 定义
3. search_content("dispatch.buildless") → 配置项
4. read_file 逐个验证文档描述第三步：文档重构
原文档：~2100 行，存在以下问题：
- Redis Key 说明重复 3 处
- 任务流程重复描述
- 代码片段分散
重构后：~500 行，改进：
- 合并重复内容
- 统一流程描述
- 表格化配置和索引质量标准
文档质量指标
| 指标 | 标准 |
|---|---|
| 篇幅精简率 | ≥ 50%（相比原始文档） |
| 重复内容 | 0 处 |
| 流程图数量 | ≤ 3 个核心图 |
| 代码示例 | 只保留关键逻辑 |
| 表格占比 | ≥ 30% |
Skill 验证清单
- frontmatter 格式正确
- description 包含触发词
- 内容结构清晰
- 与代码一致
- 可独立理解
常见问题
Q1：文档与代码不一致怎么办？
以代码为准，在文档中标注差异：
> ⚠️ **注意**：iWiki 文档描述为 xxx，但实际代码实现为 yyyQ2：文档内容过多如何处理？
采用分层策略：
- SKILL.md 放核心内容（概述、流程、配置）
- reference/ 目录放详细内容（完整数据模型、所有配置项）
Q3：如何判断哪些内容该保留？
保留标准：
- 理解模块必需的概念
- 开发时需要查阅的信息
- 排查问题需要的线索
删除标准：
- 重复出现的内容
- 过于细节的实现
- 已过时的描述
输出成果
完成本工作流后，将产出：
- 架构 Skill 文档：模块的核心知识沉淀
- reference 补充文档（可选）：详细参考信息
- 代码索引：关键文件路径清单
相关 Skill
skill-writer：Skill 编写规范00-bkci-global-architecture：全局架构概览- 各模块架构 Skill（29-xx 系列）：具体模块参考