---
name: business-knowledge-workflow
description: 业务知识获取与 Skill 文档编写工作流。当用户需要熟悉新业务模块、从 iWiki 获取文档、结合代码分析生成架构文档、或将业务知识沉淀为 Skill 时使用。
---

# 业务知识获取与 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 构建知识框架

从文档中提取并整理：

```markdown
## 初步知识框架

### 核心概念
- 概念 A：xxx
- 概念 B：xxx

### 架构要点
- 组件关系
- 数据流向

### 待验证问题
- [ ] 代码中是否如此实现？
- [ ] 是否有遗漏的细节？
```

## 阶段 2：代码验证

### 2.1 定位核心代码

根据文档中的类名、方法名、配置项定位代码：

```
工具：search_content / search_file
策略：
1. 搜索核心类名 → 找到入口
2. 搜索关键方法 → 理解流程
3. 搜索配置项 → 确认参数
```

**示例搜索序列**：
```bash
# 1. 找核心服务类
search_content: "class BuildLessStartDispatcher"

# 2. 找核心方法
search_content: "fun canDispatch"

# 3. 找配置项
search_content: "dispatch.buildless"
```

### 2.2 交叉验证

将文档描述与实际代码对照：

| 文档描述 | 代码验证 | 结果 |
|:--------|:--------|:-----|
| Redis Key 格式 | 检查实际 Key 定义 | ✅ 一致 / ⚠️ 有差异 |
| 流程步骤 | 检查方法调用链 | ✅ 一致 / ⚠️ 有差异 |
| 数据模型 | 检查实体类定义 | ✅ 一致 / ⚠️ 有差异 |

### 2.3 补充代码细节

文档通常缺失的内容：
- 异常处理逻辑
- 边界条件判断
- 性能优化细节
- 依赖注入关系
- 配置默认值

**补充方式**：
```kotlin
// 从代码中提取关键逻辑
data class CodeInsight(
    val className: String,
    val keyMethod: String,
    val businessLogic: String,
    val edgeCases: List<String>
)
```

## 阶段 3：知识沉淀

### 3.1 文档重构原则

**精简原则**：
| 原则 | 说明 |
|:-----|:-----|
| 去重 | 相同内容只保留一处 |
| 聚合 | 分散的相关内容合并 |
| 分层 | 概述 → 详情 → 代码 |
| 表格化 | 列表内容转表格 |

**结构模板**：
```markdown
# 模块名称

## 概述
一句话说明 + 核心特点表格

## 架构设计
一图说明 + 组件表格

## 核心流程
流程图 + 阶段说明表

## 数据模型
ER 图 + 字段表格

## 配置参考
配置项表格

## 代码索引
文件路径表格
```

### 3.2 重构检查清单

- [ ] 无重复内容（同一概念只出现一次）
- [ ] 无冗余流程图（合并相似图示）
- [ ] 代码示例精简（只保留关键逻辑）
- [ ] 表格优于长文本
- [ ] 层次清晰（可快速定位）

### 3.3 生成 Skill 文档

按照 `skill-writer` 规范创建：

```yaml
---
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：文档与代码不一致怎么办？

以代码为准，在文档中标注差异：

```markdown
> ⚠️ **注意**：iWiki 文档描述为 xxx，但实际代码实现为 yyy
```

### Q2：文档内容过多如何处理？

采用分层策略：
1. SKILL.md 放核心内容（概述、流程、配置）
2. reference/ 目录放详细内容（完整数据模型、所有配置项）

### Q3：如何判断哪些内容该保留？

**保留标准**：
- 理解模块必需的概念
- 开发时需要查阅的信息
- 排查问题需要的线索

**删除标准**：
- 重复出现的内容
- 过于细节的实现
- 已过时的描述

## 输出成果

完成本工作流后，将产出：

1. **架构 Skill 文档**：模块的核心知识沉淀
2. **reference 补充文档**（可选）：详细参考信息
3. **代码索引**：关键文件路径清单

## 相关 Skill

- `skill-writer`：Skill 编写规范
- `00-bkci-global-architecture`：全局架构概览
- 各模块架构 Skill（29-xx 系列）：具体模块参考