cc-agents

三面板 TUI，让 engineer、Genius Challenger、judge 三个 AI agent 相互博弈，帮你把问题想清楚。

┌─────────────────┬─────────────────┬─────────────────┬────────────────────┐
│  1 engineer     │  2 Genius       │  3 judge        │  ● engineer        │
│                 │    Challenger   │                 │    MiniMax-M3      │
│  给出技术方案   │  质疑 + 巧思    │  组会导师反问   │    45k/200k 22%    │
│  解释理由       │  提更深方案     │  适时追问双方   │  ● genius          │
│                 │                 │                 │    claude-opus-4-7 │
│                 │                 │                 │    12k/200k 6%     │
│                 │                 │                 │  ● judge           │
│                 │                 │                 │    claude-opus-4-7 │
│                 │                 │                 │    8k/200k 4%      │
│                 │                 │                 │  ──────────────────│
│                 │                 │                 │   Σ 65k            │
│                 │                 │                 │   tokens           │
└─────────────────┴─────────────────┴─────────────────┴────────────────────┘
→ engineer  /engineer /genius /judge /summarize /clear · Tab 预填 · 1/2/3 切换栏
> _

工作流程

1. 输入问题 → engineer 调用工具、查阅代码，给出方案
2. /genius 你觉得这个假设合理吗 → Genius Challenger 质疑 engineer + 给一个巧思
3. /judge → judge（组会导师）观察双方，适时反问，给出下一步追问
4. 按 Tab 预填追问，继续下一轮
5. /summarize → 生成讨论总结写入 docs/

安装

需要 Node.js ≥ 22.19。

git clone <repo>
cd cc-agents
npm install

配置

首次运行会自动在 ~/.cc-agents/settings.json 生成配置模板，填入 key 即可。也可在项目根目录创建 .cc-agents/settings.json 做项目级覆盖（优先级更高）。

{
  "engineer": {
    "model": "claude-sonnet-4-6",
    "apiKey": "sk-ant-...",
    "themeColor": "#79c0ff"
  },
  "genius": {
    "model": "claude-opus-4-7",
    "apiKey": "sk-ant-..."
  },
  "judge": {
    "model": "claude-opus-4-7",
    "apiKey": "sk-ant-..."
  }
}

system prompt、temperature 等已内置，settings.json 只需填 apiKey、model、themeColor（可选）。参考完整示例：.cc-agents/settings.example.json。

兼容其他 API

任何兼容 Anthropic API 格式的服务都可以接入，通过 baseUrl 和 authType 字段指定：

{
  "engineer": {
    "baseUrl": "https://api.minimaxi.com/anthropic",
    "authType": "bearer",
    "model": "MiniMax-M3",
    "apiKey": "your-key"
  }
}

authType 默认为 "api-key"（使用 x-api-key 请求头），设为 "bearer" 则使用 Authorization: Bearer 请求头。

baseUrl 填到路径前缀即可，不要加 /v1（代码会自动拼接）：

• ✓ "https://api.minimaxi.com/anthropic"
• ✗ "https://api.minimaxi.com/anthropic/v1"

启动

# 在你的项目目录下运行
cd /your/project
npx --prefix /path/to/cc-agents cc-agents

# 或者全局安装后
npm link   # 在 cc-agents 目录执行一次
cd /your/project
cc-agents

命令

| 命令 | 说明 | |------|------| | 直接输入 | 发送给当前模式的 agent（engineer 或 genius） | | /engineer [内容] | 切换到 engineer 模式，可附带消息 | | /genius [内容] | 切换到 Genius Challenger 模式，可附带消息 | | /judge | 触发 judge（组会导师）反问当前局势 | | /summarize | 让 judge 生成总结文档并写入 docs/ | | /resume | 恢复上次保存的对话历史（断点续会） | | /copy engineer\|genius\|judge\|all | 复制面板内容到剪贴板 | | /clear | 清空所有面板和对话历史（二次确认） | | /hide engineer\|genius\|judge | 隐藏指定面板，重启后保留 | | /show engineer\|genius\|judge\|all | 显示指定面板 | | /skills | 列出 .cc-agents/skills/ 下所有可用 skill | | /help | 显示帮助（独立全屏窗口） |

键盘快捷键

| 按键 | 说明 | |------|------| | ↑ / ↓ | 滚动当前模式面板（随时可用，无需切焦点） | | Cmd+1 / 2 / 3 | 聚焦指定面板，之后可用 ↑/↓ 滚动 | | Tab（面板焦点中） | 循环切换面板焦点 | | Tab（输入框中） | 预填 judge 建议的追问 | | Esc | 退出面板焦点，回到输入框；取消待确认的 /clear | | Alt+1 / 2 / 3 | 切换面板显示/隐藏（持久化） | | Ctrl+C / Ctrl+Q | 退出 |

Agent 工具权限

每个 agent 的工具权限不同，engineer 可写文件，genius 只读：

| 工具 | engineer | genius | 说明 | |------|:--------:|:------:|------| | read_file | ✓ | ✓ | 读取文件，支持行范围 | | list_dir | ✓ | ✓ | 列出目录内容 | | grep | ✓ | ✓ | 正则/字符串搜索 | | find | ✓ | ✓ | 按名称查找文件 | | write_file | ✓ | — | 写入/覆盖文件 | | edit_file | ✓ | — | 替换文件中的字符串 | | bash | ✓ | — | 执行 shell 命令（删除操作被屏蔽） |

genius 只有读权限，确保它聚焦质疑而不是执行修改。

长会话管理

cc-agents 内置了多层机制保障长会话的稳定性：

自动压缩历史

当 engineer 的上下文用量超过 75%（即 200k 窗口的 150k）时，会自动将老轮次压缩为 Markdown 摘要，保留最近 2 轮原文。压缩后 engineer 面板会显示提示：

✓ 已将 N 轮历史压缩为摘要（保留最近 2 轮原文）

压缩失败时 non-fatal，跳过后继续正常运行。

上下文压力预警

侧边栏的 token 使用率按压力等级着色：

• 正常（< 70%）：暗色
• 警告（≥ 70%）：橙色
• 危险（≥ 90%）：红色加粗

当 engineer 上下文超过 50% 时，judge 面板还会弹出文字提示，建议 /summarize 归档。

断点续会

每次 engineer/genius 响应后，会话状态自动写入 .cc-agents/sessions/current.json。下次启动后用 /resume 恢复：

/resume
✓ 已恢复会话（含历史压缩摘要）
  保存时间：2026/6/22 14:30:00
  历史轮次：8 轮
  当前模式：engineer

/clear 会同步清除保存的会话文件。

侧边栏

右侧侧边栏实时显示每个 agent 的状态：

• ● / ○：面板当前是否可见
• 模型名称：来自配置的 model 字段
• 上下文压力：当前输入 token / 上下文窗口 百分比（颜色随压力变化）
• Σ tokens：三个 agent 的累计 token 消耗

Token Tracker（可选）

启用后在本地起一个 Web 服务，实时展示每次 API 调用的 token 用量、耗时、模型分布等指标：

{
  "tokenTracker": {
    "enabled": true,
    "port": 3131
  }
}

启动后 URL 会在侧边栏显示 8 秒，之后可在浏览器访问 http://localhost:3131。

项目级上下文

cc-agents 会自动读取你项目下的以下内容注入 agent 系统提示：

• AGENTS.md — 项目说明、约定、背景知识
• package.json — 项目名和描述
• .cc-agents/skills/ — 自定义技能文件夹

技能文件格式示例（.cc-agents/skills/my-skill/SKILL.md）：

---
name: my-skill
description: 描述这个技能做什么
---

具体指令内容…

当用户任务与某个 skill 的 description 匹配时，LLM 会自动读取对应 SKILL.md 并按其指令行事。/skills 命令可列出当前所有可用 skill。

面板持久化

/hide 和 Alt+1/2/3 切换的面板可见性会自动保存到 .cc-agents/settings.json 的 panels 字段，重启后恢复。

图片粘贴（macOS）

在输入框中粘贴剪贴板图片（Cmd+V），会生成占位符 [Image #1]。发送消息时图片会作为附件一并传给 engineer 或 genius（需模型支持视觉输入）。