业务知识获取与 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 )

阶段 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：文档内容过多如何处理？

采用分层策略：

SKILL.md 放核心内容（概述、流程、配置） reference/ 目录放详细内容（完整数据模型、所有配置项） Q3：如何判断哪些内容该保留？

保留标准：

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

删除标准：

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

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

架构 Skill 文档：模块的核心知识沉淀 reference 补充文档（可选）：详细参考信息 代码索引：关键文件路径清单 相关 Skill skill-writer：Skill 编写规范 00-bkci-global-architecture：全局架构概览 各模块架构 Skill（29-xx 系列）：具体模块参考