sinapse-ai 5.0.8 → 6.0.0

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

@@ -1,336 +0,0 @@
-<!-- 翻译: 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
-**状态**: 官方参考
-
----
-
-## 概述
-
-本指南说明如何将工具与 SINAPSE 代理集成。工具通过提供对外部服务、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`        | 任务工作流文件                 | `.sinapse-ai/development/tasks/`    |
-| `checklists`   | 验证清单                       | `.sinapse-ai/product/checklists/`   |
-
-### 声明示例
-
-```yaml
-# 来自 .sinapse-ai/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 限制架构
-
-SINAPSE 实现严格的 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)
-- [代理定义](../../../.sinapse-ai/development/agents/)
-
----
-
-**维护者**: @architect (Aria)

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

@@ -1,151 +0,0 @@
-<!-- 翻译: 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 成本优化
-
-## 概述
-
-SINAPSE 使用 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'
-  - '.sinapse/**'
-  - '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/)