cc-agents

📧 作者：陈凯旋，天津大学 · [email protected]

🌐 Website: https://ccagents.cc — 项目介绍、功能展示

三面板 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 预填 · Ctrl+Shift+1/2/3 切换面板
> _

这是什么

三角色盲审（scrutiny），不是辩论。engineer 不知道 Genius Challenger 和 judge 的存在（盲审），正常给出方案和理由。Genius Challenger 旁观 engineer 的回答，站在批判立场质疑 + 给出巧思，但形式上假装是用户的追问。judge 观察双方对线，输出结构化 JSON 告诉用户下一步该追问谁、问什么。

工作流程

1. 输入问题 → engineer 调用工具、查阅代码，给出方案
2. /genius 你觉得这个假设合理吗 → Genius Challenger 质疑 engineer + 给一个巧思
3. /judge → judge（组会导师）观察双方，输出 {analysis, verdict, next: {target, question}}
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 Key 支持环境变量

所有 apiKey 字段支持 env:VAR_NAME 语法，不写明文 key：

{
  "engineer": {
    "apiKey": "env:ANTHROPIC_API_KEY"
  }
}

系统自动从对应环境变量读取，兼容标准密码管理器注入。

兼容其他 Anthropic 格式 API

任何兼容 Anthropic Messages 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（代码会自动拼接）

使用 OpenAI 格式 API

设置 provider 为 openai 即可接入任何 OpenAI 兼容 API（ChatGPT、DeepSeek、兼容网关等）：

{
  "engineer": {
    "provider": "openai",
    "baseUrl": "https://api.deepseek.com",
    "model": "deepseek-chat",
    "apiKey": "your-key"
  }
}

启动

# 在你的项目目录下运行
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（组会导师）反问当前局势 | | /goal | Judge 主导的三角色自动协作，收敛后自动停 | | /summarize | 让 judge 生成总结文档并写入 docs/ | | /resume | 恢复上次保存的对话历史（断点续会） | | /copy [engineer\|genius\|judge] [~N] | 复制面板中第 N 条最近消息（默认 ~1，省略 panel 则复制当前模式） | | /clear | 清空所有面板和对话历史（二次确认） | | /autogenius [true\|false\|toggle] | 开关 AutoGenius 实时审视（默认 false） | | /select [E\|G\|J\|on\|off\|toggle] | 单面板原生选择 / 鼠标框选模式切换 | | /memory [type] [内容] | 显式创建长期记忆（user / project / agent） | | /skills | 列出 .cc-agents/skills/ 下所有可用 skill | | /hide engineer\|genius\|judge | 隐藏指定面板，重启后保留 | | /show engineer\|genius\|judge\|all | 显示指定面板 | | /history | 弹出历史输入选择器（↑↓ 选择，Enter 填入） | | /tg | 查看 Telegram Bot 连接状态 | | /help | 显示帮助（独立全屏窗口） |

键盘快捷键

输入框

| 按键 | 说明 | |------|------| | Tab | 预填 judge/genius 建议的追问 / 补全 slash 命令 | | Shift+Enter | 换行（多行输入） |

| Ctrl+X | 中断当前流式输出并清空排队消息 | | Ctrl+C | 中断流式输出；连按两次在 2 秒内才退出 | | Ctrl+Q | 立即退出 |

面板

| 按键 | 说明 | |------|------| | Ctrl+Shift+1 / 2 / 3 | 切换/聚焦指定面板 | | ↑ / ↓ | 滚动当前面板（5 行） | | PageUp / PageDown | 翻页滚动（一页） | | g / G（面板焦点中） | 跳到顶部 / 底部 | | Tab（面板焦点中） | 正向循环切换面板焦点 | | Shift+Tab（面板焦点中） | 反向循环切换面板焦点；AutoGenius 冻结时放行 engineer | | Esc | 退出面板焦点，回到输入框；取消待确认的 /clear | | Alt+1 / 2 / 3 | 切换面板显示/隐藏（持久化） | | 拖拽选择 + Enter | 矩形框选面板文本并复制（自动去 ANSI） | | Ctrl+L | 清屏重绘 |

核心功能

三角色盲审

三个 agent 共享不共享会话状态——engineer 不知道自己被审查。

| 角色 | 知道机制？ | 任务 | |------|:---:|------| | engineer | ✗ | 正常给出方案 + 理由 | | Genius Challenger | ✓ | 质疑 engineer、给出巧思 | | judge | ✓ | 分析全局 → 输出下一步追问 |

judge 输出结构化 JSON {analysis, verdict, next: {target, question}}。系统自动解析 next.question，按 Tab 即可预填追问。genius 也可在回复末尾附 {"prefill": {target, question}} 提供预填建议（优先级低于 judge）。

零探索启动

cc-agents 启动时自动"读完"整个项目——目录结构、关键配置文件、每个模块导出什么函数——直接整理成一张"代码地图"交给 AI agent。agent 在回答第一个问题之前就已经知道项目长什么样。

效果：不存在"探索阶段"。agent 不会花十秒满项目搜索文件、追问"这个函数在哪"。你提的第一个问题，它就能立刻定位到代码位置开始改，像在这个项目里干过一样。换项目自动重新扫描，项目没改动就缓存秒加载。

AutoGenius 实时审视

/autogenius true 开启。engineer 流式输出过程中系统实时检测风险信号，发现后冻结 engineer 流、弹出 genius 卡片、你决定是否采纳。

四层检测架构：

• Tier 0 规则引擎：纯正则匹配危险操作（rm -rf、DROP TABLE、git push --force 等），命中立即冻结
• Tier 1 事件触发：理由小节边界、bash 工具完成、空闲超时、token 累积等 5 个触发点
• Tier 2 Agnes 分类器：廉价 LLM 判断信号是否值得叫醒 genius
• Tier 3 Genius LLM：只有确认需要才调用 genius，拿到切入角度和建议

关键设计：monitor 只产生卡片，不自动写面板。Tab 采纳、Shift+Tab 放行。默认关闭，不打扰正常使用。

记忆系统

三种长期记忆，跨 session 复用：

| 类型 | 容量 | 存储位置 | 作用 | |------|:---:|------|------| | user | 无上限 | ~/.cc-agents/memory/user.json | 用户偏好、沟通习惯、纠正记录 | | project | 无上限 | .cc-agents/memory/project.json | 项目规范、常踩的坑 | | agent | 无上限 | ~/.cc-agents/memory/agent.json | 模型已知错误记录 |

两种写入路径：

1. 自动触发：每凑够 5 轮用户输入，系统自动筛选记忆候选，弹出卡片让你 ABC 三选一——绝不自动写盘
2. 显式创建：/memory project 这个项目用 pnpm 而不是 npm，系统回显确认后落盘

消息排队

engineer 正在流式输出时你可以继续输入下一条消息——不丢失，自动进入排队队列。engineer 完成后自动发送。多条排队时弹出 Queue Picker 让你选择。Ctrl+X 中断当前输出并清空队列。

上下文自动压缩

engineer 上下文超过窗口 75% 时自动触发。老轮次压缩为结构化摘要，保留最近 2 轮原文。侧边栏 token 占比变色预警：

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

断点续会

崩溃后重启自动提示恢复，/resume 加载上次会话。/clear 同步清除保存文件。

Skills 自定义技能

把 SKILL.md（含 YAML frontmatter name + description + Markdown 正文）放入 .cc-agents/skills/<名称>/。agent 对话时根据 description 自动匹配加载。/skills 列出所有可用 skill。每个角色只看到自己有权使用的 skill 列表（engineer/prototype/tdd/diagnose、genius/grill-me、judge/zoom-out 等）。

Telegram Bot

在 .cc-agents/settings.json 中加一行即可在手机 Telegram 使用 cc-agents：

{
  "telegram": { "enabled": true, "botToken": "你的bot token" }
}

支持长轮询（默认，零配置，延迟 < 2 秒）和 webhook 两种模式。/tg 查看连接状态。

Website

项目介绍网站：https://ccagents.cc，展示三角色审视工作流和实时并行 section。源码见 apps/website/。

Token Tracker（可选）

内置 Web 服务，SQLite 记录每次 LLM 调用的模型、角色、输入/输出 token 数、延迟。启用：

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

启动后 URL 显示在侧边栏 8 秒，浏览器访问 http://localhost:3131 查看实时用量趋势。

Payload Tracker（可选）

和 Token Tracker 平行，记录完整 I/O（system prompt、messages、tools、输出文本）。用于 debug prompt 效果，不推荐长期开启。

{
  "payloadTracker": { "enabled": true, "port": 3132 }
}

Agent 工具权限

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

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

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

侧边栏

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

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

项目级上下文

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

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

面板持久化

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

图片粘贴（跨平台）

在输入框中粘贴剪贴板图片，会生成占位符 [Image #1]。发送消息时图片作为附件一并传给 engineer 或 genius（需模型支持视觉输入）。macOS 通过 pbpaste、Linux 通过 xclip、Windows 通过 PowerShell 读取剪贴板图片。

联系

欢迎反馈、建议、合作交流：

• 📧 Email: [email protected]
• 🌐 Website: https://ccagents.cc