内容
# 代理 AI 框架（通用代理中心）
**适用于 Gemini、Claude、AntiGravity 和 Codex 的专业 AI 代理标准化编排。**
## 🧠 认知锚点（AI 优化）
AI 代理的主要入口点是 **[[AGENTS.md]]**（通用）、**[[GEMINI.md]]**（Gemini CLI）和 **[[CLAUDE.md]]**（Claude 代码）文件。
- **效率**：针对 AI 消费进行优化，以最小化令牌开销。
- **标准化**：`AGENTS.md` 遵循跨工具兼容性的开放标准（AntiGravity、Cursor、Claude）。
- **图优先**：直接链接到 `docs/pages/` 中的 Logseq 供电知识图。
---
## 🧠 图优先文档（AI 优化）
该项目为其文档使用 **Logseq 供电知识图**。
- **效率**：针对 AI 消费进行优化，以最小化令牌开销，同时最大化信号精度。
- **可追溯性**：每个技术声明都链接到 AST 引用（`（ref：symbol）`）。
- **导航**：从 **[[ai-agents-graph]]** 节点开始，进行完整的架构深入研究。
---
## 🚀 安装和更新（MCP 优先）
通用代理中心设计为主要作为 **模型上下文协议（MCP）服务器** 运行。这种配置允许任何 AI 助手动态调用我们的专业代理，而无需在目标项目工作空间中克隆代码库。
### 1. 注册 MCP 服务器
将代理中心添加到您首选的 AI 环境中。
#### A. Claude 代码（CLI）
运行标准 MCP 命令：
```bash
mcp add tech-agents -- npx -y github:SouzaEduardoAC/tech-agents serve
```
#### B. Claude 桌面版
将其添加到您的配置文件中（请参见 [CLAUDE.md](file:///home/ecoza/Projects/ai-agents/CLAUDE.md) 中的位置）：
```json
{
"mcpServers": {
"tech-agents": {
"command": "npx",
"args": ["-y", "github:SouzaEduardoAC/tech-agents", "serve"]
}
}
}
```
#### C. Gemini CLI 和 AntiGravity
将其添加到 `~/.gemini/settings.json`：
```json
{
"mcpServers": {
"tech-agents": {
"command": "npx",
"args": ["-y", "github:SouzaEduardoAC/tech-agents", "serve"]
}
}
}
```
### 2. IDE 静态集成（Codex / Cursor）
如果您的 IDE 不支持动态 MCP 服务器，您可以静态链接代理的核心 persona 文件到您的工作空间（例如 `.cursorrules`）：
```bash
npx github:SouzaEduardoAC/tech-agents link [agent-name] [target-file]
```
*（示例：`npx github:SouzaEduardoAC/tech-agents link squad .cursorrules`）*
您还可以链接完整的 MCP 使用指南，以配置客户端 LLM 使用正确的工具使用协议：
```bash
npx github:SouzaEduardoAC/tech-agents link mcp .clauderules # （或 .cursorrules，.windsurfrules）
```
### 3. 旧版斜杠命令设置（可选）
如果您需要在 Gemini CLI/AntiGravity 中使用终端原生斜杠命令（例如 `/squad:run`，`/architect:create`），请在本地运行引导安装程序：
```bash
npx github:SouzaEduardoAC/tech-agents bootstrap
```
### 🔄 保持最新（自动更新）
通过 `npx` 注册后，更新会在启动时动态获取。要强制更新服务器到最新版本，请使用 `--prefer-online` 标志运行服务器：
```bash
npx --prefer-online github:SouzaEduardoAC/tech-agents serve
```
如果您使用克隆的存储库在本地开发，简单的拉取更新服务器：
```bash
git pull && npm install
```
---
## 🎮 如何调用代理（按 LLM 环境使用）
根据您活跃的 LLM 界面，调用和编排代理的标准适用于三种主要的执行模式：
### 1. AntiGravity CLI 和 Gemini CLI（斜杠命令）
运行 `bootstrap` 命令后，所有代理都注册自定义 **斜杠命令** 和 **角色** 直接在您的 CLI 环境中。
* **格式**：`/ [agent]：[command] [your goal]`
* **关键示例**：
* **Squad Orchestrator**：`/squad:run "Implement JWT authentication flow"`
* **Quicky（快速修复）**：`/quicky:fix "Fix the type mismatch on line 42 in api.ts"`
* **Architect（设计/文档）**：`/architect:create "Design a resilient connection pool"` 或 `/architect:docs "Sync the Logseq graph with recent migrations"`
* **Product Owner（发现/PO 面试）**：`/po:interview "A new service to parse PDFs"`
* **Council（设计辩论和综合）**：`/council:debate "Implement real-time location and telemetry-based pricing"`
### 2. Claude 代码（模型上下文协议 / MCP）
Claude 代码使用 **MCP 工具调用** 与中心通信。由于 Claude 是一个代理助手，您 **不需要** 在聊天中编写原始代码或命令语法。您只需用自然语言与 Claude 交谈，Claude 将自主调用正确的中心工具。
* **自然对话提示（推荐）**：
* *“嘿 Claude，请调用 squad 来构建用户仪表板页面。”*
* *“Claude，请询问 quicky 修复摘要页面上的标签。”*
* *“请 Architect 设计一个用于支付的 CQRS 模式。”*
* **幕后工具合同** （Claude 如何在幕后执行它）：
* 格式：`call_agent_command（agent = “[agent-name]”，command = “[command]”，args = “[your goal]”）`
* 示例：`call_agent_command（agent = “quicky”，command = “fix”，args = “Fix the summary label mismatch”）`
* **SSO/基于令牌的循环执行（MCP 采样）**：
在企业或基于令牌的 SSO 环境（例如 AntiGravity 或 Codex）中，当本地 API 密钥不可用时，您可以在服务器管理的执行循环中使用客户端自己的 LLM 会话运行代理：
* *自然对话提示*：*“嘿助手，请运行 quicky 循环来修复标签不匹配问题。”*
* *幕后工具合同*：`run_agent_loop（agent = “quicky”，command = “fix”，args = “Fix the label mismatch”）`
* *行为*：服务器管理对话历史，固定系统提示（防止 Codex 角色漂移），拦截本地工具操作（文件系统，终端命令）格式化为 XML 标签（`<read_file>`，`<write_file>`，`<run_command>`，`<task_complete>`），在主机上执行它们，并将输出反馈到循环中。
* **可用 MCP 工具**：
* `list_agents`：列出所有可用的专业代理及其命令。
* `call_agent_command`：激活专业代理命令，返回原始编译提示（提示注入回退）。
* `run_agent_loop`：通过客户端 LLM 采样在服务器端执行多轮代理循环（SSO 兼容）。
* `get_agent_prompt`：检索特定代理的角色、技能和知识。
* `pipeline_start`：初始化新的管道会话并锁定 `.squad-state-[branch].json` 中的所有门。
* `request_approval`：将门状态设置为 `pending` 并暂停管道以供人类签署。
* `check_gate`：检查在启动下一阶段之前是否批准了特定管道门。
* `pipeline_approve`：批准特定管道门以解锁下一阶段。
### 3. Cursor 和 Codex IDE（系统规则和角色链接）
对于 Cursor、VS Code 或其他使用上下文文件（例如 `.cursorrules` 或自定义系统说明）的 IDE，您直接将代理的核心身份文件链接到您的工作空间。
* **链接命令**：
```bash
npx github:SouzaEduardoAC/tech-agents link [agent-name] [target-file]
```
*（例如，`npx github:SouzaEduardoAC/tech-agents link squad .cursorrules`，`link quicky .cursorrules` 或 `npx github:SouzaEduardoAC/tech-agents link mcp .clauderules` 以链接完整的 MCP 使用指南）*
* **用法**：IDE 模型立即继承该代理的完整角色、技能和防护措施。只需在 Composer 或侧边栏聊天中引用 `@.cursorrules` 即可执行流程。
---
## 🛠 贡献和工程标准
我们为代码和文档完整性维护“零信任”模型。
- **工程 DNA**：基础模式和标准在 **[[code-dna]]** 中编码。
- **稳定性协议**：弹性策略（重试，电路中断器）在 **[[resilience-policies]]** 中。
- **约定提交**：我们严格遵循 [约定提交 1.0.0](https://www.conventionalcommits.org/)。
### 如何贡献
1. **PRD 优先**：在图中验证需求页面后，不会发生任何逻辑更改。
2. **测试优先**：错误修复需要失败测试重现；新功能需要 100% 逻辑覆盖。
3. **图同步**：每个代码更改 **必须** 使用 `/architect:docs` 与 Logseq 图同步。
---
## 📂 文档套件（图节点）
- **[[ai-agents-graph]]**：主入口点。
- **[[TECHNICAL_SPECS]]**：内部逻辑，MCP 工具和运行时规范。
- **[[BUSINESS_FLOW]]**：用例和全局业务规则。
- **[[Standardized Pipeline]]**：自主工程生命周期。
---
## 🤖 核心代理
- **[[Squad Orchestrator]]**：PM / 首席协调员。
- **[[Product Owner]]**：PO / 需求网关。
- **[[Architect]]**：系统负责人 / 安全审计员。
- **[[Backend]]**，**[[Frontend]]**，**[[Mobile]]**：实施专家。
- **[[Compliance]]**：监管和风险审计员。
- **[[Researcher]]**：战略分析师。
- **[[Automata]]**：自动化架构师。
- **[[Decoder]]**：技术规范到业务翻译器。
- **[[Forge]]**：设计、搭建、审计和升级其他代理的专业元代理（#MetaAgent）。
- **[[Quicky]]**：快速修复、微调和隔离任务的专家，维护文档完整性。
- **[[Council]]**：对称多视角辩论和设计综合引擎。
