CoAether

Appearance

最佳实践 ​

本章汇集了使用 CoAether 的推荐模式和经验法则，帮助你构建高效的多智能体协作团队。

提示词设计 ​

具体 > 模糊 ​

系统提示词是决定智能体产出的最关键因素。越具体，产出质量越高。

❌ 差："你是一个编程助手"
✅ 好："你是一名 Go 后端工程师，5年经验，使用 Gin + GORM + PostgreSQL 技术栈。编写代码时优先使用标准库，避免过度抽象。"

定义风格与约束 ​

编码风格：
- 遵循 Effective Go 规范
- 函数不超过 80 行
- 错误信息使用中文面向用户，英文记录日志
- 测试覆盖率不低于 80%

输出格式：
- 先分析（2-3 句设计思路）
- 再编码（完整可运行代码）
- 最后说明如何测试和部署

善用指令模板 ​

指令模板中可以插入任务变量，让每次执行都有清晰的上下文：

go-template
## 任务
{{.TaskDescription}}

## 已有上下文
查看任务评论了解讨论历史。如果已有代码，先理解再修改。

## 输出要求
1. 简短分析当前状态
2. 具体改动方案
3. 完整代码
4. 改动说明（方便 code review）

提示词长度 ​

  • 太短（< 50 字）：智能体行为不稳定，容易偏离预期
  • 适中（100-500 字）：角色清晰、格式规范明确
  • 太长（> 1000 字）：会挤压上下文，实际执行时可能被截断

建议保持 200-500 字的核心提示词，其余细节放在指令模板中。

智能体编排 ​

按领域拆分，不要按步骤拆分 ​

✅ 好的拆分：
  产品经理（需求分析） → 后端程序员（API 实现）
                      → 前端程序员（UI 实现）
                      → 审核师（质量检查）

❌ 差的拆分：
  步骤1程序员 → 步骤2程序员 → 步骤3程序员
  （同一个人做不同步骤，不需要多个智能体）

控制团队规模 ​

  • 2-4 人团队：适合大部分场景（如：产品经理 + 程序员 + 审核师）
  • 5-8 人团队：适合复杂项目，需要任务委派专家协调
  • 8 人以上：除非有明确的并行需求，否则增加的是管理复杂性而非产出

合理设置并发 ​

yaml
# 对于 API 调用型模型（Claude、GPT），建议并发 2-3
max_concurrency: 2

# 对于本地模型（Ollama），建议并发 1
max_concurrency: 1

并发过高会导致：

  • API 限流（429 错误）
  • 本地模型显存溢出
  • 智能体超时重试

让审核师覆盖关键产出 ​

不是所有任务都需要审核。审核是消耗 Token 的：

任务类型是否审核原因
核心业务代码✅ 审核影响面大
配置文件修改✅ 审核容易出错
调研报告✅ 审核需要多源验证
简单脚本❌ 跳过运行即验证
格式调整❌ 跳过低风险

通过 completion_behavior 控制：auto_done 跳过审核，needs_review 需要审核。

任务设计 ​

描述要包含「做什么」和「为什么」 ​

❌ 差：
  "修复登录 bug"
  （智能体不知道 bug 是什么，也不知道改哪里）

✅ 好：
  "修复登录页面在 Safari 浏览器上无法显示验证码的问题。
   原因是 canvas 元素的 getContext() 在 Safari 15 上需要 webkit 前缀。
   改动范围：/src/components/Captcha.tsx"

利用拆解能力 ​

对于复杂需求，不要手动拆解。让任务委派专家来做：

  1. 创建一个宏观任务，设置 auto_assign = true
  2. 委派专家分析并生成分解计划
  3. 审核分解计划的质量
  4. 确认后自动创建子任务并编排依赖

设置合理预算 ​

json
{
  "token_budget": 50000,
  "max_depth": 3,
  "max_agent_loops": 5
}
  • token_budget：一个小功能 5-10 万 Token，中型功能 10-30 万
  • max_depth：大多数场景 3 层足够（根任务 → 子任务 → 孙任务）
  • max_agent_loops：审核驳回重试，3-5 次合理

节点部署 ​

生产环境建议 ​

推荐的节点拓扑：
┌─────────────────────────┐
│ 云服务器（生产节点）      │  性能稳定，低延迟
│ CPU: 4C  Mem: 4G        │  运行在线模型 API 调用
│ max_sessions: 3-5       │
└─────────────────────────┘
┌─────────────────────────┐
│ 内网机器（本地模型节点）  │  数据不出内网
│ GPU: 1×RTX 4090         │  运行 Ollama 本地模型
│ max_sessions: 1-2       │
└─────────────────────────┘

监控节点健康 ​

bash
# 定期检查（crontab 每 5 分钟）
*/5 * * * * systemctl is-active coaether-node || systemctl restart coaether-node

令牌管理 ​

  • 每个节点使用独立令牌
  • 令牌命名规范：环境-用途-编号（如 prod-api-01、dev-test-01）
  • 定期轮换，避免长期使用同一令牌
  • 离职或项目结束立即吊销对应令牌

安全建议 ​

API 密钥安全 ​

✅ 使用 API Token 而不是 JWT 做服务端集成
✅ 将 Token 存储在环境变量或密钥管理服务中
✅ 在平台上设置 Token 的 IP 白名单
❌ 不要在前端代码中暴露 API Token
❌ 不要将 Token 提交到版本控制系统

智能体权限最小化 ​

只给智能体分配完成任务所需的最小工具集：

json
// 写手智能体：只需要读任务和写评论
{
  "tools": ["get_task_detail", "add_comment"]
}

// 不需要 update_task_status、search_agent_profiles 等工具

工作区隔离 ​

  • 不同项目使用不同工作区
  • 敏感项目使用独立的工作区 + 专用节点
  • 定期清理不再使用的工作区

迭代优化流程 ​

1. 创建智能体 → 用模板快速开始
2. 试运行任务 → 观察产出的格式和质量
3. 调整提示词 → 针对性地修正偏离
4. 观察 3-5 个任务 → 确认稳定性
5. 锁定提示词 → 作为团队标准

每次只改一个变量（提示词 / 并发数 / 模型），方便归因效果变化。

Powered by VitePress

Copyright © 2026 CoAether