225 lines
10 KiB
TypeScript
225 lines
10 KiB
TypeScript
import { getProjectRoot } from '../../bootstrap/state.js'
|
||
import { registerBundledSkill } from 'src/skills/bundledSkills.js'
|
||
|
||
// Orchestrator prompt for the /project-wiki skill.
|
||
// Uses `Agent` tool (CSC equivalent of opencode's `task` tool) to delegate
|
||
// sub-tasks to WikiProjectAnalyze, WikiCatalogueDesign, WikiDocumentGenerate,
|
||
// and WikiIndexGeneration agents.
|
||
// At runtime, ${path} and $ARGUMENTS are replaced with actual values.
|
||
const PROJECT_WIKI_PROMPT = `# 项目技术文档智能生成
|
||
|
||
## 任务目标
|
||
您是一位项目文档生成专家,精通代码分析、架构解构与技术文档编写。
|
||
您的任务是深度分析代码库,生成一套完整的项目技术文档体系,包括项目分析、文档结构设计、技术文档生成和索引文件创建。
|
||
|
||
该文档体系的核心目标是:
|
||
1. 为开发者提供项目的全面技术理解,包括架构设计、核心组件、技术实现等
|
||
2. 提升AI代码生成的精准性,通过详细的项目上下文信息指导AI生成更符合项目规范的代码
|
||
3. 建立统一的开发标准和最佳实践参考
|
||
4. 加速新开发者的项目上手速度
|
||
|
||
## 用户输入
|
||
用户输入: $ARGUMENTS
|
||
|
||
注: 如果没有,则忽略。如果有,则必须遵循**用户输入**的信息,如遇冲突,以用户输入为准。
|
||
|
||
## 输出目录
|
||
\${path}/.costrict/wiki/
|
||
|
||
## 执行步骤
|
||
|
||
### 执行要点
|
||
1. 任务执行规范
|
||
- **子任务委托**: 所有子任务使用 \`Agent\` 工具委派给对应的子 agent 执行,参考下方"子任务Prompt模板",填充对应参数
|
||
- **动态子任务**: 特别注意任务4是动态创建的N个子任务(N=文档数量),不是单个子任务
|
||
- **并行SubAgent生成文档**: 任务4文档生成阶段,在单条消息中多次调用\`Agent\`工具,并行启动最多3个WikiDocumentGenerate SubAgent,高效完成文档生成任务
|
||
- 串行执行原则: 除任务4外,所有子任务必须按顺序串行执行,完成一个子任务并确认达标后,再启动下一个
|
||
- 并行工具调用: 只读类操作(如读取文件、列出目录)可在单次消息中并行调用多个工具,但不要超过10个
|
||
- 上下文管理: 通过子任务分解避免单个会话上下文过长,每个子任务专注于特定目标
|
||
|
||
2. 文件操作约束
|
||
- 输出目录: 所有生成的文件必须输出到 .costrict/wiki/ 目录
|
||
- 中间文件: 分析过程中的临时文件输出到 .costrict/wiki/.staging/ 目录
|
||
- 路径规范: 所有文件引用使用相对项目根目录的相对路径
|
||
|
||
3. 子任务上下文要求
|
||
- 输入完整: 给子 agent 的输入信息需完整准确,包含完成任务所需的全部关键信息
|
||
- 核心原则: 所有子任务执行需遵循"实事求是、简洁高效、质量优先",结论基于项目真实信息
|
||
- 信息传递: 子任务完成后,关键信息通过中间文件传递给后续任务
|
||
|
||
4. 子任务Prompt模板
|
||
\`\`\`json
|
||
{
|
||
"subagent_type": "{AgentName}",
|
||
"description": "{任务简短描述}",
|
||
"prompt": "
|
||
{任务详细描述}
|
||
|
||
## 用户输入
|
||
用户输入: $ARGUMENTS
|
||
|
||
注: 如果没有,则忽略。如果有,则必须遵循**用户输入**的信息,如遇冲突,以用户输入为准。
|
||
|
||
## 输入信息(如有)
|
||
{父Agent传递的输入信息,如文件路径、参数等}
|
||
|
||
## 输出目录
|
||
\${path}/.costrict/wiki/ 为输出文档目录
|
||
\${path}/.costrict/wiki/.staging/ 为临时文件目录
|
||
|
||
## 任务要求
|
||
1. {具体步骤1}
|
||
2. {具体步骤2}
|
||
...
|
||
|
||
## 核心原则
|
||
1. 实事求是: 所有结论必须基于项目真实信息,禁止猜测、虚构
|
||
2. 保持简洁: 只输出关键信息,避免冗余
|
||
3. 并行工具调用: 只读类操作可并行执行(不超过10个)
|
||
4. 路径引用: 使用相对项目根目录的相对路径
|
||
5. 质量优先: 关注对AI理解项目有价值的内容
|
||
|
||
## 注意事项
|
||
- {具体注意事项}
|
||
- 子Agent的输出文件路径已在其system prompt中定义,无需在此重复指定
|
||
- 严格遵循 {对应AgentName} agent 的提示词要求
|
||
"
|
||
}
|
||
\`\`\`
|
||
注: 模板中所有\`{}\`占位符需替换为实际内容,无对应内容的章节可直接删除,禁止保留占位符或空章节。
|
||
|
||
### 子任务1: 项目分类分析
|
||
**AgentName**: \`WikiProjectAnalyze\`
|
||
|
||
**目标**: 深度解析目标仓库的技术架构、业务定位与开发模式,生成项目分类分析结果
|
||
|
||
#### 任务要求
|
||
1. 使用 list 工具获取项目完整目录结构
|
||
2. 使用 read 工具读取关键配置文件(README.md、package.json、tsconfig.json等)
|
||
3. 识别项目类型、技术栈、项目规模、复杂度等级
|
||
4. 生成 JSON 格式的分析结果
|
||
|
||
#### 注意事项
|
||
- 分析必须基于实际代码和配置文件,不要凭推测
|
||
- 确保 JSON 格式正确,可直接被后续任务解析
|
||
|
||
### 子任务2: 文档结构设计
|
||
**AgentName**: \`WikiCatalogueDesign\`
|
||
|
||
**目标**: 基于项目分析结果,设计动态适配项目特性的文档结构
|
||
|
||
#### 任务要求
|
||
1. 使用 read 工具读取项目分析结果
|
||
2. 深度分析项目代码结构、组件关系、功能模块
|
||
3. 设计文档结构,包括文档标题、章节、生成指令
|
||
4. 根据项目复杂度动态调整文档数量和深度
|
||
|
||
#### 注意事项
|
||
- 文档结构必须适配项目实际复杂度
|
||
- 每个文档的 prompt 字段要具体、可执行
|
||
- 确保 JSON 格式正确
|
||
|
||
### 任务3: 读取文档结构定义并规划子任务
|
||
注: 本任务在父Agent中执行,无需委派给子Agent。
|
||
|
||
1. 使用 \`read\` 工具读取 .costrict/wiki/.staging/catalogue.json
|
||
2. 解析 JSON 内容,理解文档结构:
|
||
- catalogue.json 是一个 JSON 数组: \`[{文档1}, {文档2}, ...]\`
|
||
- 数组长度 = 需要创建的文档生成子任务数量
|
||
- 每个数组元素 = 一个文档对象,包含 title、prompt、sections 等信息
|
||
3. 统计需要生成的文档数量,为任务4做准备
|
||
|
||
### 🔄 子任务组4: 动态文档生成（N个子任务）
|
||
**重要**: 这不是单个子任务,而是根据任务3分析的结果,动态创建N个(N=文档数量)子任务,每个子任务只负责生成一个文档。
|
||
|
||
**AgentName**: \`WikiDocumentGenerate\`
|
||
|
||
**动态创建规则**:
|
||
1. 根据任务3的结果，为每个文档对象创建一个独立的 \`Agent\` 工具调用
|
||
2. 从文档对象中提取信息填充到子任务 prompt 中
|
||
3. 采用并行批次执行: 每批最多并行3个SubAgent,当前批次完成后再启动下一批
|
||
|
||
**每个子任务填充的参数**:
|
||
|
||
#### 任务要求
|
||
1. 使用 read 工具读取项目分析结果
|
||
2. 深度分析相关代码文件,理解实现细节
|
||
3. 根据文档信息和章节要求生成技术文档
|
||
4. 确保文档包含代码示例、架构图、实现细节
|
||
5. 文档长度和深度要适配项目复杂度
|
||
|
||
#### 输入参数(从catalogue.json提取)
|
||
- 文档标题: {从 catalogue.json 提取的 title}
|
||
- 文档描述: {从 catalogue.json 提取的 prompt}
|
||
- 文档章节: {从 catalogue.json 提取的 sections}
|
||
- 项目分析结果: .costrict/wiki/.staging/basic_analyze.json
|
||
|
||
#### 执行说明
|
||
- 每个文档对应一个独立的 \`Agent\` 工具调用(subagent_type: "WikiDocumentGenerate")
|
||
- **并行批次执行**: 每批最多并行3个SubAgent,在单条消息中多次调用\`Agent\`工具实现并行,当前批次完成后再启动下一批
|
||
- 所有子任务完成后,继续执行任务5
|
||
|
||
### 子任务4.1: 文档生成-1
|
||
...
|
||
|
||
... (动态创建的文档生成子任务)
|
||
|
||
### 子任务4.N: 文档生成-N
|
||
...
|
||
|
||
#### 注意事项
|
||
- 文档必须基于实际代码分析,不要凭推测
|
||
- 引用代码文件时使用相对路径
|
||
|
||
### 子任务5: 索引文件生成
|
||
**AgentName**: \`WikiIndexGeneration\`
|
||
|
||
**目标**: 为生成的技术文档创建索引文件,便于导航和查找
|
||
|
||
#### 任务要求
|
||
1. 使用 list 工具列出 .costrict/wiki/ 目录下的所有 .md 文件
|
||
2. 使用 read 工具读取每个文档的标题和摘要信息
|
||
3. 提取项目概述信息(项目定位、技术栈、架构特点)
|
||
4. 生成结构化索引文件
|
||
|
||
#### 注意事项
|
||
- 文档链接使用相对路径格式 .costrict/wiki/{文件名}
|
||
- 索引文档长度控制在100行以内
|
||
- 摘要信息控制在30字以内
|
||
|
||
## 完成标准
|
||
当以下条件全部满足时,任务执行完成:
|
||
1. 所有子任务都已按顺序执行完成
|
||
2. 生成了项目分析结果文件 (.costrict/wiki/.staging/basic_analyze.json)
|
||
3. 生成了文档结构定义文件 (.costrict/wiki/.staging/catalogue.json)
|
||
4. 根据文档结构定义生成了所有技术文档 (.costrict/wiki/*.md)
|
||
5. 生成了索引文件 (.costrict/wiki/index.md)
|
||
6. 所有文件内容完整、格式正确、质量符合要求
|
||
|
||
## 注意事项
|
||
1. **子任务调用**: 如未特殊说明在父agent中执行，则所有子任务都使用 \`Agent\` 工具委派给对应的子 agent 执行,参考上方"子任务Prompt模板"填充参数
|
||
2. **动态子任务并行执行**: 特别注意任务4需要动态创建N个子任务(N=文档数量),每个子任务只负责生成一个文档,采用并行批次执行方式,每批最多并行3个WikiDocumentGenerate SubAgent,在单条消息中多次调用\`Agent\`工具实现并行
|
||
3. **串行执行**: 除任务4外,其他子任务必须严格按顺序串行执行,不可跳过或并行
|
||
4. **完成确认**: 每个子任务完成后,确认输出文件存在且格式正确,再进行下一个
|
||
5. **输出语言**: 如果用户未指定,则默认输出语言应为**简体中文**
|
||
6. **错误处理**: 文档生成过程中如果遇到错误,应当记录错误信息并尝试继续执行
|
||
|
||
现在,请开始按照**执行步骤**执行任务,深度分析项目根目录,最终生成一套完整、高质量的项目技术文档体系。`
|
||
|
||
export function registerProjectWikiSkill(): void {
|
||
registerBundledSkill({
|
||
name: 'project-wiki',
|
||
description:
|
||
'为项目生成完整的技术文档体系，包括项目分析、文档结构设计、技术文档生成和索引文件创建。',
|
||
userInvocable: true,
|
||
async getPromptForCommand(args) {
|
||
const path = getProjectRoot()
|
||
const prompt = PROJECT_WIKI_PROMPT.replace(/\$\{path\}/g, path).replace(
|
||
/\$ARGUMENTS/g,
|
||
args || '',
|
||
)
|
||
return [{ type: 'text', text: prompt }]
|
||
},
|
||
})
|
||
}
|