aiox-core 5.0.0

package/docs/zh/architecture/agent-tool-integration-guide.md

@@ -0,0 +1,336 @@
+<!-- 翻译: ZH-CN | 原始: /docs/pt/architecture/agent-tool-integration-guide.md | 同步: 2026-02-22 -->
+
+# 代理工具集成指南
+
+> **ZH** | [EN](../architecture/agent-tool-integration-guide.md) | [PT](../pt/architecture/agent-tool-integration-guide.md)
+
+---
+
+**版本**: 1.0.0
+**最后更新**: 2026-01-26
+**状态**: 官方参考
+
+---
+
+## 概述
+
+本指南说明如何将工具与 AIOX 代理集成。工具通过提供对外部服务、API 和系统资源的访问来扩展代理的能力。
+
+---
+
+## 架构
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                 代理工具集成架构          │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│   代理定义 (YAML 格式的 .md 文件)                           │
+│   ┌─────────────────────────────────────────────────────┐   │
+│   │  dependencies:                                      │   │
+│   │    tools: [git, coderabbit, context7]              │   │
+│   │    tasks: [task-a.md, task-b.md]                   │   │
+│   │    checklists: [checklist-a.md]                    │   │
+│   └─────────────────────────────────────────────────────┘   │
+│                           │                                 │
+│                           ▼                                 │
+│   ┌─────────────────────────────────────────────────────┐   │
+│   │  工具类型                                             │   │
+│   │  ├── CLI 工具 (git、npm、gh)                        │   │
+│   │  ├── MCP 服务器 (EXA、Context7、Apify)              │   │
+│   │  └── 外部服务 (CodeRabbit、Supabase)               │   │
+│   └─────────────────────────────────────────────────────┘   │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 依赖声明
+
+代理在其 `.md` 定义文件中的 YAML 块中声明其依赖关系。
+
+### 依赖类型
+
+| 类型           | 描述                           | 位置                        |
+| -------------- | ------------------------------ | -------------------------- |
+| `tools`        | CLI 工具和外部服务             | 系统 PATH 或 MCP           |
+| `tasks`        | 任务工作流文件                 | `.aiox-core/development/tasks/`    |
+| `checklists`   | 验证清单                       | `.aiox-core/product/checklists/`   |
+
+### 声明示例
+
+```yaml
+# 来自 .aiox-core/development/agents/dev.md
+dependencies:
+  checklists:
+    - story-dod-checklist.md
+  tasks:
+    - apply-qa-fixes.md
+    - create-service.md
+    - dev-develop-story.md
+    - execute-checklist.md
+  tools:
+    - coderabbit # 提交前代码质量检查
+    - git # 本地操作: add、commit、status、diff
+    - context7 # 库文档查询
+    - supabase # 数据库操作
+    - n8n # 工作流自动化
+    - browser # Web 应用测试
+    - ffmpeg # 媒体文件处理
+```
+
+---
+
+## 按代理的工具类别
+
+### @dev (Dex - 开发代理)
+
+| 工具   | 类型     | 目的                                    |
+| ------ | -------- | -------------------------------------- |
+| `git`        | CLI      | 版本控制 (仅本地操作) |
+| `coderabbit` | 外部  | 提交前代码质量审查    |
+| `context7`   | MCP      | 库文档查询        |
+| `supabase`   | 外部  | 数据库操作和迁移      |
+| `n8n`        | 外部  | 工作流自动化                       |
+| `browser`    | MCP      | Web 应用测试                     |
+| `ffmpeg`     | CLI      | 媒体文件处理           |
+
+**@dev 的 Git 限制**:
+
+- 允许: `git add`、`git commit`、`git status`、`git diff`、`git log`、`git branch`
+- 阻止: `git push`、`gh pr create`、`gh pr merge`
+- 推送操作需要 @devops 代理
+
+### @devops (Gage - DevOps 代理)
+
+| 工具   | 类型     | 目的                           |
+| ------ | -------- | ------------------------------- |
+| `git`        | CLI      | 完整 git 操作包括推送 |
+| `gh`         | CLI      | GitHub CLI 用于 PR 操作 |
+| `docker`     | CLI      | 容器操作             |
+| `coderabbit` | 外部  | 自动代码审查 |
+
+**独占能力**:
+
+- 唯一授权推送到远程的代理
+- 唯一授权创建/合并 PR 的代理
+- MCP 基础设施管理
+
+### @qa (Quinn - QA 代理)
+
+| 工具   | 类型 | 目的                          |
+| ------ | ---- | ----------------------------- |
+| `jest`       | CLI  | 单元测试                   |
+| `playwright` | MCP  | E2E 测试和浏览器自动化  |
+| `npm test`   | CLI  | 测试执行器                 |
+
+### @architect (Aria - 架构师代理)
+
+| 工具 | 类型 | 目的                   |
+| ---- | ---- | ---------------------- |
+| `exa`      | MCP  | 研究和分析          |
+| `context7` | MCP  | 文档参考  |
+
+---
+
+## MCP 集成
+
+### 可用的 MCP 工具
+
+MCP 服务器 (Model Context Protocol) 为代理使用提供结构化 API。
+
+| MCP 服务器 | 提供的工具                                               | 使用者        |
+| ---------- | -------------------------------------------------------- | ------------- |
+| EXA        | `web_search_exa`、`company_research_exa`、`get_code_context_exa`    | @architect       |
+| Context7   | `resolve-library-id`、`query-docs`                  | @dev、@architect |
+| Playwright | `browser_navigate`、`browser_screenshot`、`browser_click`           | @qa              |
+| Apify      | `search-actors`、`call-actor`、`get-actor-output`                   | @devops          |
+
+### MCP 配置
+
+MCP 服务器通过 Docker MCP 工具包配置。见 [MCP API 密钥管理](./mcp-api-keys-management.md) 用于配置。
+
+### 使用模式
+
+```
+1. 代理收到需要外部数据的任务
+2. 代理从其依赖中识别适当的 MCP 工具
+3. 代理通过工具接口调用 MCP 工具
+4. MCP 返回结构化响应
+5. 代理处理响应并继续任务
+```
+
+---
+
+## CodeRabbit 集成
+
+@dev 代理包括 CodeRabbit 进行提交前质量检查。
+
+### 配置
+
+```yaml
+coderabbit_integration:
+  enabled: true
+  installation_mode: wsl # 或 'native'
+
+  self_healing:
+    enabled: true
+    type: light
+    max_iterations: 2
+    timeout_minutes: 15
+    trigger: story_completion
+    severity_filter:
+      - CRITICAL
+    behavior:
+      CRITICAL: auto_fix
+      HIGH: document_only
+      MEDIUM: ignore
+      LOW: ignore
+```
+
+### 工作流
+
+在将故事标记为 "准备审查" 前:
+
+1. 在未提交的变更上执行 CodeRabbit
+2. 如果发现关键问题，尝试自动修复 (最多 2 次迭代)
+3. 在故事的开发笔记中记录高严重级别问题
+4. 如果关键问题在迭代后仍然存在，停止并通知用户
+
+---
+
+## Git 限制架构
+
+AIOX 实现严格的 git 操作治理:
+
+### @dev 代理的权限
+
+```yaml
+git_restrictions:
+  allowed_operations:
+    - git add
+    - git commit
+    - git status
+    - git diff
+    - git log
+    - git branch
+    - git checkout
+    - git merge
+  blocked_operations:
+    - git push
+    - git push --force
+    - gh pr create
+    - gh pr merge
+```
+
+### @devops 代理的权限
+
+```yaml
+git_permissions:
+  full_access: true
+  special_capabilities:
+    - push to remote
+    - create pull requests
+    - merge pull requests
+    - admin bypass for branch protection
+```
+
+### 切换工作流
+
+```
+@dev 完成故事
+    ↓
+@dev 标记状态: "准备审查"
+    ↓
+用户激活 @devops
+    ↓
+@devops 创建 PR 并推送
+```
+
+---
+
+## 添加新工具
+
+### 步骤 1: 更新代理定义
+
+将工具添加到代理的 `dependencies.tools` 列表:
+
+```yaml
+dependencies:
+  tools:
+    - existing-tool
+    - new-tool # 在此添加
+```
+
+### 步骤 2: 记录工具使用
+
+如果工具需要特定配置或有特殊使用模式，添加文档:
+
+```yaml
+tool_integration:
+  new-tool:
+    purpose: '简短描述'
+    common_commands:
+      - 'new-tool --help'
+      - 'new-tool run <args>'
+    when_to_use: '当条件 X 满足时使用'
+```
+
+### 步骤 3: 测试集成
+
+激活代理并验证工具是否可访问且可正常工作。
+
+---
+
+## 最佳实践
+
+### 应该做的事
+
+- 在代理定义中声明所有工具依赖关系
+- 为每种任务类型使用合适的工具
+- 遵循代理的权限界限
+- 记录工具使用以用于调试
+- 使用前验证工具输出
+
+### 不应该做的事
+
+- 使用在依赖中未声明的工具
+- 绕过 git 限制 (使用合适的代理)
+- 忽略工具返回码
+- 在工具日志中公开敏感数据
+- 跳过输入验证
+
+---
+
+## 故障排除
+
+### 未找到工具
+
+1. 验证工具是否已安装: `which <tool-name>`
+2. 检查环境变量 PATH
+3. 验证工具在代理依赖中声明
+
+### MCP 工具错误
+
+1. 验证 MCP 服务器是否正在运行
+2. 验证 API 密钥是否已配置 (见 [MCP API 密钥管理](./mcp-api-keys-management.md))
+3. 查阅工具特定文档
+
+### 权限被拒绝
+
+1. 验证此代理是否阻止该操作
+2. 验证是否应该使用 @devops
+3. 检查文件/目录权限
+
+---
+
+## 相关文档
+
+- [MCP API 密钥管理](./mcp-api-keys-management.md)
+- [MCP 使用规则](../../../.claude/rules/mcp-usage.md)
+- [代理定义](../../../.aiox-core/development/agents/)
+
+---
+
+**维护者**: @architect (Aria)

package/docs/zh/architecture/ci-cd.md

@@ -0,0 +1,151 @@
+<!-- 翻译: ZH-CN | 原文: /docs/en/architecture/ci-cd.md | 同步: 2026-02-22 -->
+
+# CI/CD 架构
+
+> 🌐 [EN](../../architecture/ci-cd.md) | [PT](../../pt/architecture/ci-cd.md) | **ZH** | [ES](../../es/architecture/ci-cd.md)
+
+---
+
+> 故事 6.1: GitHub Actions 成本优化
+
+## 概述
+
+AIOX-Core 使用 GitHub Actions 进行持续集成和部署。本文档描述了故事 6.1 中实现的优化工作流架构。
+
+## 工作流层级
+
+```text
+┌─────────────────────────────────────────────────────────────────┐
+│                        触发事件                                  │
+├─────────────────────────────────────────────────────────────────┤
+│  拉取请求 → ci.yml (必需) + pr-automation.yml (指标)              │
+│  推送到 main → ci.yml + semantic-release.yml + test.yml         │
+│              + cross-platform (ci.yml 中的条件)                 │
+│  标签 v*   → release.yml → npm-publish.yml                      │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+**说明:** PR 仅执行 ci.yml 和 pr-automation.yml (~12 个作业)。扩展测试 (test.yml) 仅在推送到 main 时执行。
+
+## 活跃工作流
+
+| 工作流                | 目的                                  | 触发           | 关键 |
+| --------------------- | ------------------------------------- | -------------- | ---- |
+| `ci.yml`              | 主要 CI 验证 (lint、typecheck、test) | PR、push main  | 是   |
+| `pr-automation.yml`   | 覆盖率报告和指标                      | 仅 PR          | 否   |
+| `semantic-release.yml` | 自动版本化和 changelog                | 推送到 main    | 是   |
+| `test.yml`            | 扩展测试 (安全、构建、集成)          | 仅 push main   | 否   |
+| `macos-testing.yml`   | macOS 特定测试 (Intel + ARM)         | 按 path 过滤   | 否   |
+| `release.yml`         | GitHub 发布创建                       | 标签 v\*       | 是   |
+| `npm-publish.yml`     | 发布到 NPM                            | 发布已发布     | 是   |
+| `pr-labeling.yml`     | 自动 PR 标签                          | PR 打开/同步   | 否   |
+| `quarterly-gap-audit.yml` | 计划审计                           | Cron           | 否   |
+| `welcome.yml`         | 欢迎新手贡献者                        | PR             | 否   |
+
+## 优化策略
+
+### 1. 并发控制
+
+所有工作流使用并发组来避免重复执行:
+
+```yaml
+concurrency:
+  group: <workflow>-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true  # 用于 CI 工作流
+  # 或
+  cancel-in-progress: false  # 用于发布/发布工作流
+```
+
+### 2. 路径过滤
+
+工作流忽略仅文档更改的不必要执行:
+
+```yaml
+paths-ignore:
+  - 'docs/**'
+  - '*.md'
+  - '.aiox/**'
+  - 'squads/**'
+  - 'LICENSE'
+  - '.gitignore'
+```
+
+### 3. 条件跨平台测试
+
+跨平台矩阵 (3 个操作系统 x 3 个 Node 版本 = 排除后 7 个作业) 仅在推送到 main 时执行:
+
+```yaml
+cross-platform:
+  if: github.ref == 'refs/heads/main' && github.event_name == 'push'
+  strategy:
+    matrix:
+      os: [ubuntu-latest, windows-latest, macos-latest]
+      node: ['18', '20', '22']
+      exclude:
+        - os: macos-latest
+          node: '18' # isolated-vm 的 SIGSEGV
+        - os: macos-latest
+          node: '20' # isolated-vm 的 SIGSEGV
+```
+
+### 4. 统一验证
+
+单一的真实来源用于验证:
+
+- **ci.yml** 处理所有验证 (lint、typecheck、test)
+- **semantic-release.yml** 依赖分支保护 (不需要重复的 CI)
+- **pr-automation.yml** 仅关注指标/覆盖率
+
+## 可计费分钟减少
+
+| 前        | 后         | 节省 |
+| --------- | ---------- | ---- |
+| ~340 分钟/周 | ~85 分钟/周 | ~75% |
+
+### 详细说明:
+
+- 并发: 40% 减少 (取消过时的执行)
+- 路径过滤: 30% 减少 (忽略仅文档 PR)
+- 统一跨平台: 25% 减少 (7 对 16 个作业)
+- 移除冗余工作流: 5% 减少
+
+## 分支策略
+
+所有工作流仅面向 `main` 分支:
+
+- 无 `master` 或 `develop` 分支
+- 功能分支 → 拉取请求到 main
+- 通过 main 上的 semantic-release 发布
+
+## 强制状态检查
+
+用于 `main` 上的分支保护:
+
+1. `CI / ESLint`
+2. `CI / TypeScript Type Checking`
+3. `CI / Jest Tests`
+4. `CI / Validation Summary`
+
+## 故障排除
+
+### 工作流不执行?
+
+1. 检查路径是否在 `paths-ignore` 中
+2. 检查分支是否与触发条件匹配
+3. 检查并发组 (可能已被取消)
+
+### 发布未发布?
+
+1. 检查 `NPM_TOKEN` secret 是否配置
+2. 检查 semantic-release 配置
+3. 检查常规 commit 格式
+
+### macOS 测试失败?
+
+- Node 18/20 在 macOS 上存在 isolated-vm 的 SIGSEGV 问题
+- 仅 Node 22 在 macOS 上执行 (按设计)
+
+## 相关文档
+
+- [GitHub Actions 计费](https://docs.github.com/en/billing/managing-billing-for-github-actions)
+- [Semantic Release](https://semantic-release.gitbook.io/)