业务知识获取与 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，但实际代码实现为 yyy

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

采用分层策略：

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

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

保留标准：

• 理解模块必需的概念
• 开发时需要查阅的信息
• 排查问题需要的线索

删除标准：

• 重复出现的内容
• 过于细节的实现
• 已过时的描述

输出成果

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

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

相关 Skill

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