Back to Details

business-knowledge-workflow

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

业务知识获取与 Skill 文档编写工作流

Workflow for Business Knowledge Acquisition and Skill Document Creation

本 Skill 描述了从外部文档（如 iWiki）获取业务知识，结合代码分析，最终沉淀为高质量 Skill 文档的完整工作流。
This Skill describes the complete workflow for acquiring business knowledge from external documents (such as iWiki), verifying with code analysis, and ultimately institutionalizing it into high-quality Skill documents.

触发条件

Trigger Conditions

当用户需要：
  • 熟悉一个新的业务模块或子系统
  • 从 iWiki 或其他文档系统获取业务知识
  • 将文档内容与实际代码进行交叉验证
  • 生成或重构模块架构文档
  • 将业务知识沉淀为可复用的 Skill
Use this when you need to:
  • Familiarize yourself with a new business module or subsystem
  • Acquire business knowledge from iWiki or other document systems
  • Cross-verify document content with actual code
  • Generate or restructure module architecture documents
  • Institutionalize business knowledge into reusable Skills

核心工作流

Core Workflow

┌─────────────────────────────────────────────────────────────────┐
│                    业务知识获取工作流                              │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  阶段 1：文档获取          阶段 2：代码验证          阶段 3：知识沉淀   │
│  ┌─────────────┐        ┌─────────────┐        ┌─────────────┐ │
│  │  iWiki 搜索  │───────▶│  代码定位   │───────▶│  文档重构   │ │
│  │  文档阅读    │        │  交叉验证   │        │  Skill 编写 │ │
│  │  结构提取    │        │  补充细节   │        │  质量审查   │ │
│  └─────────────┘        └─────────────┘        └─────────────┘ │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────┐
│                Business Knowledge Acquisition Workflow          │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Phase 1: Document Acquisition   Phase 2: Code Verification   Phase 3: Knowledge Institutionalization │
│  ┌─────────────┐        ┌─────────────┐        ┌─────────────┐ │
│  │  iWiki Search  │───────▶│  Code Location   │───────▶│  Document Restructuring │ │
│  │  Document Reading │        │  Cross-Verification │        │  Skill Creation │ │
│  │  Structure Extraction │        │  Detail Supplementation │        │  Quality Review │ │
│  └─────────────┘        └─────────────┘        └─────────────┘ │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

阶段 1：文档获取

Phase 1: Document Acquisition

1.1 使用 iWiki MCP 工具搜索

1.1 Search with iWiki MCP Tool

工具：iWiki.searchDocument
参数：query = "模块名称 + 关键词"
搜索策略：
场景搜索词示例
了解模块架构
Buildless 架构设计
了解具体功能
Buildless 任务调度
了解数据模型
Buildless Redis 存储
Tool: iWiki.searchDocument
Parameters: query = "Module Name + Keywords"
Search Strategy:
ScenarioExample Search Terms
Understand module architecture
Buildless Architecture Design
Understand specific functions
Buildless Task Scheduling
Understand data models
Buildless Redis Storage

1.2 获取文档内容

1.2 Retrieve Document Content

工具：iWiki.getDocument
参数：docId = 搜索结果中的文档 ID
关键提取项：
  • 背景与目标
  • 核心概念/术语
  • 架构设计图
  • 流程说明
  • 数据模型
  • 配置说明
Tool: iWiki.getDocument
Parameters: docId = Document ID from search results
Key Extraction Items:
  • Background and objectives
  • Core concepts/terminology
  • Architecture design diagrams
  • Process descriptions
  • Data models
  • Configuration instructions

1.3 构建知识框架

1.3 Build Knowledge Framework

从文档中提取并整理：
markdown
undefined
Extract and organize from documents:
markdown
undefined

初步知识框架

Initial Knowledge Framework

核心概念

Core Concepts

  • 概念 A：xxx
  • 概念 B：xxx
  • Concept A: xxx
  • Concept B: xxx

架构要点

Architecture Key Points

  • 组件关系
  • 数据流向
  • Component relationships
  • Data flow

待验证问题

Pending Verification Questions

  • 代码中是否如此实现？
  • 是否有遗漏的细节？
undefined
  • Is this implemented this way in the code?
  • Are there any missing details?
undefined

阶段 2：代码验证

Phase 2: Code Verification

2.1 定位核心代码

2.1 Locate Core Code

根据文档中的类名、方法名、配置项定位代码：
工具：search_content / search_file
策略：
1. 搜索核心类名 → 找到入口
2. 搜索关键方法 → 理解流程
3. 搜索配置项 → 确认参数
示例搜索序列：
bash
undefined
Locate code based on class names, method names, and configuration items from documents:
Tools: search_content / search_file
Strategy:
1. Search core class names → Find entry points
2. Search key methods → Understand processes
3. Search configuration items → Confirm parameters
Example Search Sequence:
bash
undefined

1. 找核心服务类

1. Find core service class

search_content: "class BuildLessStartDispatcher"
search_content: "class BuildLessStartDispatcher"

2. 找核心方法

2. Find core method

search_content: "fun canDispatch"
search_content: "fun canDispatch"

3. 找配置项

3. Find configuration items

search_content: "dispatch.buildless"
undefined
search_content: "dispatch.buildless"
undefined

2.2 交叉验证

2.2 Cross-Verification

将文档描述与实际代码对照：
文档描述代码验证结果
Redis Key 格式检查实际 Key 定义✅ 一致 / ⚠️ 有差异
流程步骤检查方法调用链✅ 一致 / ⚠️ 有差异
数据模型检查实体类定义✅ 一致 / ⚠️ 有差异
Compare document descriptions with actual code implementations:
Document DescriptionCode VerificationResult
Redis Key formatCheck actual Key definitions✅ Consistent / ⚠️ Has discrepancies
Process stepsCheck method call chains✅ Consistent / ⚠️ Has discrepancies
Data modelsCheck entity class definitions✅ Consistent / ⚠️ Has discrepancies

2.3 补充代码细节

2.3 Supplement Code Details

文档通常缺失的内容：
  • 异常处理逻辑
  • 边界条件判断
  • 性能优化细节
  • 依赖注入关系
  • 配置默认值
补充方式：
kotlin
// 从代码中提取关键逻辑
data class CodeInsight(
    val className: String,
    val keyMethod: String,
    val businessLogic: String,
    val edgeCases: List<String>
)
Content usually missing from documents:
  • Exception handling logic
  • Boundary condition judgments
  • Performance optimization details
  • Dependency injection relationships
  • Default configuration values
Supplementation Method:
kotlin
// Extract key logic from code
data class CodeInsight(
    val className: String,
    val keyMethod: String,
    val businessLogic: String,
    val edgeCases: List<String>
)

阶段 3：知识沉淀

Phase 3: Knowledge Institutionalization

3.1 文档重构原则

3.1 Document Restructuring Principles

精简原则：
原则说明
去重相同内容只保留一处
聚合分散的相关内容合并
分层概述 → 详情 → 代码
表格化列表内容转表格
结构模板：
markdown
undefined
Simplification Principles:
PrincipleDescription
DeduplicationKeep only one instance of identical content
AggregationMerge scattered related content
LayeringOverview → Details → Code
TabulationConvert list content to tables
Structure Template:
markdown
undefined

模块名称

Module Name

概述

Overview

一句话说明 + 核心特点表格
One-sentence description + Core features table

架构设计

Architecture Design

一图说明 + 组件表格
Diagram + Component table

核心流程

Core Processes

流程图 + 阶段说明表
Flowchart + Phase description table

数据模型

Data Models

ER 图 + 字段表格
ER diagram + Field table

配置参考

Configuration Reference

配置项表格
Configuration item table

代码索引

Code Index

文件路径表格
undefined
File path table
undefined

3.2 重构检查清单

3.2 Restructuring Checklist

  • 无重复内容（同一概念只出现一次）
  • 无冗余流程图（合并相似图示）
  • 代码示例精简（只保留关键逻辑）
  • 表格优于长文本
  • 层次清晰（可快速定位）
  • No duplicate content (same concept appears only once)
  • No redundant flowcharts (merge similar diagrams)
  • Simplified code examples (only keep key logic)
  • Tables preferred over long text
  • Clear hierarchy (easy to navigate)

3.3 生成 Skill 文档

3.3 Generate Skill Documents

按照 
skill-writer
规范创建：
yaml
---
name: module-name-architecture
description: 模块描述。当用户需要了解 xxx、开发 xxx 功能时使用。
---
Create according to 
skill-writer
specifications:
yaml
---
name: module-name-architecture
description: Module description. Use this when you need to understand xxx, develop xxx features, etc.
---

工具使用速查

Quick Reference for Tool Usage

iWiki MCP 工具

iWiki MCP Tools

工具用途常用参数
searchDocument
搜索文档
query
getDocument
获取内容
docId
getSpacePageTree
获取目录
spaceKey
, 
parentId
metadata
获取元数据
docId
ToolPurposeCommon Parameters
searchDocument
Search documents
query
getDocument
Retrieve content
docId
getSpacePageTree
Retrieve directory
spaceKey
, 
parentId
metadata
Retrieve metadata
docId

代码分析工具

Code Analysis Tools

工具用途示例
search_content
搜索代码内容类名、方法名、字符串
search_file
搜索文件名
*.kt
, 
*Service.kt
read_file
读取文件查看完整实现
list_files
列出目录了解模块结构
ToolPurposeExample
search_content
Search code contentClass names, method names, strings
search_file
Search file names
*.kt
, 
*Service.kt
read_file
Read filesView complete implementations
list_files
List directoriesUnderstand module structure

实战案例：Buildless 模块

Practical Case: Buildless Module

第一步：iWiki 文档获取

Step 1: Retrieve iWiki Documents

1. searchDocument("Buildless 无编译构建机")
2. getDocument(docId) → 获取 2000+ 行原始文档
3. 提取核心概念：容器池、任务队列、DeferredResult
1. searchDocument("Buildless Compile-Free Build Machine")
2. getDocument(docId) → Retrieve over 2000 lines of original documents
3. Extract core concepts: Container Pool, Task Queue, DeferredResult

第二步：代码交叉验证

Step 2: Code Cross-Verification

1. search_content("BuildLessStartDispatcher") → 入口类
2. search_content("BuildLessTaskResource") → API 定义
3. search_content("dispatch.buildless") → 配置项
4. read_file 逐个验证文档描述
1. search_content("BuildLessStartDispatcher") → Entry class
2. search_content("BuildLessTaskResource") → API definition
3. search_content("dispatch.buildless") → Configuration items
4. read_file to verify document descriptions one by one

第三步：文档重构

Step 3: Document Restructuring

原文档：~2100 行，存在以下问题：
- Redis Key 说明重复 3 处
- 任务流程重复描述
- 代码片段分散

重构后：~500 行，改进：
- 合并重复内容
- 统一流程描述
- 表格化配置和索引
Original document: ~2100 lines, with the following issues:
- Redis Key description duplicated 3 times
- Task process described repeatedly
- Code snippets scattered

Restructured version: ~500 lines, with improvements:
- Merged duplicate content
- Unified process descriptions
- Tabulated configurations and indexes

质量标准

Quality Standards

文档质量指标

Document Quality Metrics

指标标准
篇幅精简率≥ 50%（相比原始文档）
重复内容0 处
流程图数量≤ 3 个核心图
代码示例只保留关键逻辑
表格占比≥ 30%
MetricStandard
Simplification Rate≥ 50% (compared to original document)
Duplicate Content0 instances
Number of Flowcharts≤ 3 core diagrams
Code ExamplesOnly keep key logic
Table Proportion≥ 30%

Skill 验证清单

Skill Verification Checklist

  • frontmatter 格式正确
  • description 包含触发词
  • 内容结构清晰
  • 与代码一致
  • 可独立理解
  • Correct frontmatter format
  • Description includes trigger terms
  • Clear content structure
  • Consistent with code
  • Comprehensible independently

常见问题

Frequently Asked Questions

Q1：文档与代码不一致怎么办？

Q1: What if documents and code are inconsistent?

以代码为准，在文档中标注差异：
markdown
> ⚠️ **注意**：iWiki 文档描述为 xxx，但实际代码实现为 yyy
Prioritize code, and mark discrepancies in the document:
markdown
> ⚠️ **Note**: The iWiki document describes xxx, but the actual code implementation is yyy

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

Q2: How to handle overly long documents?

采用分层策略：
  1. SKILL.md 放核心内容（概述、流程、配置）
  2. reference/ 目录放详细内容（完整数据模型、所有配置项）
Adopt a layered strategy:
  1. Place core content (overview, processes, configurations) in SKILL.md
  2. Place detailed content (complete data models, all configuration items) in the reference/ directory

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

Q3: How to decide which content to keep?

保留标准：
  • 理解模块必需的概念
  • 开发时需要查阅的信息
  • 排查问题需要的线索
删除标准：
  • 重复出现的内容
  • 过于细节的实现
  • 已过时的描述
Retention Criteria:
  • Concepts necessary for understanding the module
  • Information needed during development
  • Clues required for troubleshooting
Removal Criteria:
  • Repeated content
  • Overly detailed implementations
  • Outdated descriptions

输出成果

Output Deliverables

完成本工作流后，将产出：
  1. 架构 Skill 文档：模块的核心知识沉淀
  2. reference 补充文档（可选）：详细参考信息
  3. 代码索引：关键文件路径清单
After completing this workflow, you will produce:
  1. Architecture Skill Document: Core knowledge institutionalization for the module
  2. Reference Supplementary Documents (optional): Detailed reference information
  3. Code Index: List of key file paths

相关 Skill

Related Skills

  • skill-writer
    ：Skill 编写规范
  • 00-bkci-global-architecture
    ：全局架构概览
  • 各模块架构 Skill（29-xx 系列）：具体模块参考
  • skill-writer
    : Skill writing specifications
  • 00-bkci-global-architecture
    : Global architecture overview
  • Module architecture Skills (Series 29-xx): References for specific modules