cc-agents 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 tju-tomorrow
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,230 @@
+# 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。
+
+```bash
+git clone <repo>
+cd cc-agents
+npm install
+```
+
+## 配置
+
+在你的项目根目录（即运行 cc-agents 的目录）创建 `.cc-agents/settings.json`：
+
+```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` 字段指定：
+
+```json
+{
+  "engineer": {
+    "baseUrl": "https://api.minimaxi.com/anthropic",
+    "authType": "bearer",
+    "model": "MiniMax-M3",
+    "apiKey": "your-key"
+  }
+}
+```
+
+`authType` 默认为 `"api-key"`（使用 `x-api-key` 请求头），设为 `"bearer"` 则使用 `Authorization: Bearer` 请求头。
+
+## 启动
+
+```bash
+# 在你的项目目录下运行
+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 用量、耗时、模型分布等指标：
+
+```json
+{
+  "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`）：
+
+```markdown
+---
+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（需模型支持视觉输入）。

package/bin/cc-agents.mjs

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+const __dir = dirname(fileURLToPath(import.meta.url));
+const entry = join(__dir, "..", "dist", "index.js");
+
+const child = spawn(process.execPath, [entry], {
+	stdio: "inherit",
+	env: process.env,
+	cwd: process.cwd(),
+});
+child.on("exit", (code, signal) => {
+	if (signal) process.kill(process.pid, signal);
+	else process.exit(code ?? 0);
+});