Skip to content

utility-integration-guide.md

Latest commit

 

History

History
358 lines (264 loc) · 8.39 KB

utility-integration-guide.md

File metadata and controls

358 lines (264 loc) · 8.39 KB
Raw

工具集成指南

🌐 EN | PT | ZH | ES

版本: 1.0.0 创建于: 2025-10-29 作者: Sarah (@po)、Winston (@architect) 目的: 为在 AIOX 框架中集成工具脚本定义模式

什么是工具集成?

定义: 工具集成是使孤立工具脚本可发现、文档化和可用的过程，位于 AIOX 框架内。

工具被认为完全集成当:

  1. ✅ 已注册 在 core-config.yaml 中
  2. ✅ 被引用 至少由一个代理或任务
  3. ✅ 已文档化 包含目的和用法
  4. ✅ 已测试 以确保正确加载
  5. ✅ 可发现 通过框架机制

集成模式

模式 1: 代理辅助工具

何时使用: 工具提供代理直接使用的辅助函数

集成步骤:

  1. 将工具添加到目标代理的 dependencies.utils 数组
  2. 在代理文件中记录工具的目的
  3. 在 core-config.yaml 中注册 (如果还未注册)
  4. 测试代理是否成功加载工具

示例: util-batch-creator

# .aiox-core/agents/dev.yaml
id: dev
name: 开发代理
dependencies:
  utils:
    - batch-creator  # 创建相关任务的批次
    - code-quality-improver

修改的文件:

  • .aiox-core/agents/{agent}.yaml (添加到 dependencies.utils)
  • .aiox-core/core-config.yaml (如必要则注册)
  • .aiox-core/utils/README.md (记录工具)

模式 2: 任务执行工具

何时使用: 工具由任务在执行期间调用

集成步骤:

  1. 识别或创建使用工具的任务
  2. 在任务的 execution.utils 部分添加工具引用
  3. 记录任务如何使用工具
  4. 在 core-config.yaml 中注册 (如必要)
  5. 使用工具测试任务执行

示例: util-commit-message-generator

# .aiox-core/tasks/generate-commit-message.md
id: generate-commit-message
name: 生成提交信息
execution:
  utils:
    - commit-message-generator  # 该任务的主工具
  steps:
    - 分析暂存的更改
    - 使用工具生成语义提交信息
    - 向用户呈现信息以批准

修改的文件:

  • .aiox-core/tasks/{task}.md (添加 execution.utils)
  • .aiox-core/agents/{agent}.yaml (添加任务到 executes 列表)
  • .aiox-core/core-config.yaml (如必要则注册)
  • .aiox-core/utils/README.md (记录工具)

模式 3: 框架基础设施工具

何时使用: 工具由框架本身使用，而不是由代理/任务直接使用

集成步骤:

  1. 在 core-config.yaml 的适当类别中注册
  2. 在 utils/README.md 中记录为 "框架工具"
  3. 添加到框架文档
  4. 测试工具在框架上下文中加载

示例: util-elicitation-engine

# .aiox-core/core-config.yaml
utils:
  framework:
    - elicitation-engine  # 用于代理创建工作流
    - aiox-validator

修改的文件:

  • .aiox-core/core-config.yaml (在框架中注册)
  • .aiox-core/utils/README.md (记录为框架工具)
  • 框架文档 (如适用)

模式 4: 文档/分析工具

何时使用: 工具执行分析或文档生成

集成步骤:

  1. 添加到相关代理的工具 (通常是 architect、qa 或文档代理)
  2. 创建或更新使用工具的任务
  3. 记录分析/输出格式
  4. 在 core-config.yaml 中注册

示例: util-documentation-synchronizer

# .aiox-core/agents/architect.yaml
dependencies:
  utils:
    - documentation-synchronizer  # 保持文档与代码同步
    - dependency-analyzer

修改的文件:

  • .aiox-core/agents/{agent}.yaml
  • .aiox-core/tasks/{task}.md (如创建任务)
  • .aiox-core/core-config.yaml
  • .aiox-core/utils/README.md

集成工作流

标准流程 (适用于所有模式):

1. 分析
   ├─ 检查工具代码以理解目的
   ├─ 识别工具类别 (辅助、执行器、分析器等)
   └─ 确定适当的集成模式

2. 映射
   ├─ 识别应使用工具的目标代理
   ├─ 识别或创建调用工具的任务
   └─ 记录映射决策

3. 集成
   ├─ 将工具引用添加到代理/任务文件
   ├─ 在 core-config.yaml 中注册 (如必要)
   └─ 在 utils/README.md 中记录

4. 测试
   ├─ 加载工具以验证无错误
   ├─ 加载代理以验证依赖解析
   ├─ 如适用则测试任务执行
   └─ 运行间隙检测以验证正确性

5. 文档
   ├─ 在 README 中添加工具描述
   ├─ 记录用法模式
   ├─ 注解使用它的代理/任务
   └─ 更新架构图

工具分类

工具应进行分类以便于集成:

类别 1: 代码质量

目的: 分析、改进、验证代码 模式: 代理辅助工具 (代理 dev、qa) 示例: aiox-validator、code-quality-improver、coverage-analyzer

类别 2: Git/工作流

目的: Git 操作、工作流自动化 模式: 任务执行 (代理 dev、github-devops) 示例: commit-message-generator、branch-manager、conflict-resolver

类别 3: 组件管理

目的: 生成、管理、搜索组件 模式: 代理辅助工具 + 任务执行 示例: component-generator、component-search、deprecation-manager

类别 4: 文档

目的: 生成、同步、分析文档 模式: 文档工具 (代理 architect、docs) 示例: documentation-synchronizer、dependency-impact-analyzer

类别 5: 批处理/辅助

目的: 批量操作、框架辅助 模式: 变化 (代理辅助工具或框架) 示例: batch-creator、clickup-helpers、elicitation-engine

测试要求

对于每个集成的工具:

1. 加载测试

// 验证工具加载无错误
const utility = require('.aiox-core/utils/{utility-name}');
// 不应抛出错误

2. 引用验证

# 验证代理/任务引用有效
node outputs/architecture-map/schemas/validate-tool-references.js

3. 间隙检测

# 验证间隙已解决
node outputs/architecture-map/schemas/detect-gaps.js
# 应显示 0 个工具间隙

4. 集成测试 (如适用)

// 验证代理加载工具依赖
const agent = loadAgent('agent-name');
// 应在解析的依赖中包含工具

文档要求

utils/README.md 中的模板条目:

### util-{name}

**目的:** 工具执行功能的简要描述

**由以下使用:**
- agent-{name} (用于 {目的})
- task-{name} (在 {阶段} 期间)

**集成模式:** {模式-名称}

**位置:** `.aiox-core/utils/{name}.js`

**使用示例:**
\`\`\`javascript
const util = require('./utils/{name}');
// 代码示例
\`\`\`

core-config.yaml 中的注册

将工具添加到适当的部分:

utils:
  # 代理辅助工具
  helpers:
    - batch-creator
    - code-quality-improver

  # 任务执行工具
  executors:
    - commit-message-generator
    - component-generator

  # 框架基础设施工具
  framework:
    - elicitation-engine
    - aiox-validator

  # 分析/文档工具
  analyzers:
    - documentation-synchronizer
    - dependency-analyzer

成功标准

工具集成成功时:

✅ 可发现:

  • 在 core-config.yaml 中列出
  • 在 utils/README.md 中记录
  • 由代理/任务引用

✅ 功能性:

  • 加载无错误
  • 代理/任务可使用它
  • 测试通过

✅ 已验证:

  • 间隙检测显示 0 个间隙
  • 引用验证通过
  • 集成测试通过

✅ 已文档化:

  • 目的清晰表述
  • 提供使用示例
  • 已识别集成模式

常见陷阱

❌ 不要: 添加工具到代理而不理解其目的 ✅ 要: 首先检查代码，理解功能

❌ 不要: 如果现有任务可使用则创建新任务 ✅ 要: 在适当时扩展现有任务

❌ 不要: 注册而不文档化 ✅ 要: 始终添加 README 条目

❌ 不要: 跳过测试 ✅ 要: 验证工具加载并解析

快速参考

模式 目标 修改的文件 测试
代理辅助工具 Agent YAML agent.yaml、core-config、README 加载代理
任务执行 Task MD + Agent task.md、agent.yaml、core-config、README 执行任务
框架 框架 core-config、README、文档 加载工具
文档 Architect/Docs agent.yaml、core-config、README 间隙检测

指南版本: 1.0.0 最后更新: 2025-10-29 维护者: Winston (@architect)