# cc-agent

**Repository Path**: Wilson_Lws/cc-agent

## Basic Information

- **Project Name**: cc-agent
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-11-01
- **Last Updated**: 2026-11-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# cc-agent

**CC Agent** 是一个本地运行的 Claude Code 桌面客户端：Electron + Vue3 界面，后端通过
stream-json 双向协议驱动 `claude.exe`，把权限审批、提问、计划、子代理、后台任务、MCP、
上下文压缩等能力桥接成可视化交互。

它内置一个本地代理（`proxy/`，默认 `127.0.0.1:8788`），把 Claude Code 发给模型的英文
system 提示词替换为中文版（可选强制中文思考）——界面、推理和回答都是中文，且所有会话都被
强制走这个代理。

## 为什么用它

- **完整桥接 Claude Code**：五种权限模式、权限审批、提问、计划、后台任务、子代理、MCP、
  压缩，一个都不少，而且都能在界面上看到和操作。
- **多会话、多工作空间**：每个会话一个常驻 `claude` 进程，可随时中断/恢复；每个工作空间
  对应一个真实目录（默认 `~/cc-agent-workspaces/<名称>`），claude 的 cwd 就是它。
- **中文**：内置提示词代理改写 system 提示词，并可选追加"全程中文推理"指令。
- **本地**：claude、代理、后端都只监听 `127.0.0.1`，会话记录存在本机。
- **绿色版**：打包产物内置 `claude.exe`，目标机器无需安装 Claude Code。

## 界面预览

| 计划批准 | 文件编辑 |
|---|---|
| <img src="docs/screenshots/plan-approval.png" width="480" alt="计划批准" /> | <img src="docs/screenshots/edit-diff.png" width="480" alt="文件编辑 diff" /> |
| 计划以 markdown 呈现，批准后退出计划模式并恢复进入前的权限模式 | Edit 以红绿 diff 展示，Read/Write/Bash 使用统一的 IN/OUT 形态 |

| 问题卡片 | 权限审批 |
|---|---|
| <img src="docs/screenshots/question-card.png" width="480" alt="问题卡片" /> | <img src="docs/screenshots/permission-request.png" width="480" alt="权限审批" /> |
| AskUserQuestion 支持单选/多选、自定义回答，多问题分 tab | 工具执行前弹出审批卡，可允许或拒绝并回传理由 |

## 功能一览

### 会话与工作空间

- 侧栏统一「工作空间」菜单：创建新工作空间（`~/cc-agent-workspaces/<名称>`）、选择本机
  任意目录、最近使用、删除（可选同时删除文件夹）。
- 历史对话 = claude 原生历史 ∪ 本应用在当前工作空间的会话，新建会话发送后立即置顶高亮；
  外部 claude 会话追加的内容每次打开自动同步。
- 打开历史会话有加载浮层，渲染完成后定位到最新位置，不在底部时显示"一键到底"按钮。
- 用户消息里的图片（含 `[Image: source: 路径]`）可直接显示并点击预览。

### 权限与审批

- 五种权限模式：✋ Manual / 📝 Accept edits / 📋 Plan / 🤖 Auto / ⚡ Bypass；运行中切换
  走 `set_permission_mode` 热切换，不杀进程。
- 未选会话时切模式/模型不弹窗，静默作为下一个新会话的默认值。
- 权限审批卡：允许/拒绝，拒绝理由会回传给模型。
- AskUserQuestion 提问卡：多问题 tab、单选自动跳下一题、多选提交。
- ExitPlanMode 计划审批：计划以 markdown 渲染；批准后退出计划模式并恢复到进入计划前的
  权限模式，拒绝则要求模型继续完善计划。

### 工具调用可视化

- Bash / Read / Write 统一 IN/OUT 形态：限高显示、底部渐隐提示未显示完；点击可在右侧打开
  预览面板（可拖宽、不换行），支持纯文本 / markdown / 图片。
- Read 支持直接预览图片与 `.md` 文件；Write 可预览待写入内容；Edit 以红绿 diff 展示。
- 输出自动剥离 ANSI 转义序列，不再出现颜色码乱码。
- `run_in_background`：命令运行 3 秒后可在卡片下方转为后台运行，卡片显示后台状态与结果。

### 子代理

- Agent / Task 卡内嵌子代理活动日志；底部常显"N agent"按钮，列出运行中/已完成的子代理，
  点击直接定位到对应工具卡。
- 子代理还在跑而主线程空闲时，发送按钮仍显示"发送"而不是"停止"。

### 上下文

- 状态栏显示上下文剩余百分比；点一下立即压缩。
- 压缩后插入分割线（如「🗜 已压缩对话 · 手动 · 释放 25k tokens · 23.5s」），悬停可看压缩
  前后 token 数；压缩产生的摘要与命令回显不会混进消息列表。

### MCP

- 读取 `~/.claude.json` 的全局 MCP + 应用级 MCP（`agent/data/mcp.json`），支持 Add server。
- 按工作空间启用/禁用（`agent/data/mcp-workspaces.json`）。
- `command` 为 `node/nodejs` 的服务器自动改用 Electron 内置 node；Python 类（uv/python）
  直接透传，暂未做专门适配。

### 模型供应商

- 设置 → 模型供应商：维护多个上游（名称 / Base URL / API Key）；每个供应商一个开关，打开即切换并自动保存，同一时刻只有一个生效。
- 配置存 `proxy/providers.json`，代理按文件热加载——保存后**下一条请求**即走新供应商，无需重启。
- API Key 留空则沿用 Claude Code 自身的凭据；首次启动时若没有该文件，代理会按 `.env` 的 `UPSTREAM` 生成一条默认供应商。

### 外观与设置

- 主题默认浅色，可切深色；强调色可换；侧栏可收起。
- 设置面板（版本 / 主题 / MCP），侧栏底部预留用户登录模块。

## 快速开始

### 桌面端（推荐）

```bash
cd agent
npm install               # 首次：Electron 依赖
npm --prefix web install  # 首次：前端依赖
npm start                 # 构建前端 + 启动 Electron
```

启动流程（`agent/electron/main.js`）：探活/拉起代理(:8788) → 启动内嵌后端(:8790) →
窗口加载该地址。已有代理或后端在运行则直接复用。

> 终端环境若带 `ELECTRON_RUN_AS_NODE=1`，Electron 会退化成 node 不显示窗口；开发启动
> shim 已自动剥离该变量。

### 绿色版（免安装）

```bash
node agent/tools/pack.js
# 产物: agent/release/cc-agent-win32-x64/"CC Agent.exe"
```

绿色版内置 `vendor/claude/claude.exe`，目标机器无需安装 Claude Code。想换用本机或其他
版本，设置环境变量 `CLAUDE_BIN` 指向可执行文件即可（优先级最高）。

### 只用代理

```bash
node proxy/proxy.js
ANTHROPIC_BASE_URL=http://127.0.0.1:8788 claude
```

## 架构速览

| 层 | 位置 | 作用 |
|---|---|---|
| 代理 | `proxy/proxy.js` | 识别 system 变体，替换为中文提示词，转发请求并记录日志 |
| 会话管理 | `agent/server/manager.js` | spawn/续跑 claude、解析事件流、桥接控制协议、历史回填 |
| 存储 | `agent/server/store.js` | `agent/data/sessions.json` 索引 + `<uuid>.jsonl` 时间线 |
| 后端 | `agent/server/index.js` | REST + SSE（`/api/sessions/:id/events`）+ 托管 `web/dist` |
| 前端 | `agent/web/` | Vue3 + Vite：时间线、工具卡、审批/提问卡、侧栏、输入栏 |
| 外壳 | `agent/electron/` | 拉起代理与后端、窗口、IPC、框选截屏、开发调试端口 9222 |

关键机制：

- **会话进程**：`claude -p --input-format stream-json --output-format stream-json
  --include-partial-messages --permission-prompt-tool=stdio`。新会话用 `--session-id`，
  已有记录必须 `--resume`（否则报 "Session ID is already in use"）。
- **强制走代理**：`~/.claude/settings.json` 的 `env` 会覆盖进程环境变量，所以每个会话
  生成 `data/settings-<id>.json`，用 `--settings` 只改 `ANTHROPIC_BASE_URL`。
- **事件流**：stdout NDJSON → 过滤 → SSE 广播 + 选择性落盘；回放时批量渲染
  （`replay_begin/end`），长会话也不卡。
- **历史**：本应用时间线存 `agent/data/<uuid>.jsonl`；打开 claude 原生对话时从
  `~/.claude/projects/<slug>/<uuid>.jsonl` 回填，`slug` 由 cwd 非字母数字转 `-`。

## 代理配置（`proxy/.env`）

`.env` 不存在也能运行；进程环境变量优先于 `.env`。相对路径以 `proxy/` 目录为基准。

| 变量 | 默认 | 说明 |
|---|---|---|
| `PORT` | `8788` | 本地监听端口 |
| `UPSTREAM` | `https://api.anthropic.com` | 上游地址 |
| `SYSTEM_FILE` | `system_1.zh.txt` | 老版提示词中文版 |
| `SYSTEM_FILE_NEW` | `system_2.zh.txt` | 新版提示词中文版（按请求变体自动选用） |
| `DROP_FIRST` | `true` | 丢弃原 `system[0]` 身份句，仅保留中文版 |
| `KEEP_CACHE` | `true` | 替换后给 system 打 `cache_control` |
| `LOG_FILE` | `proxy.log` | 请求日志（每请求一行）；`false` 关闭落盘 |
| `THINK_IN_CHINESE` | `true` | 追加"全程中文推理"指令 |

两份中文提示词按 mtime 热加载，编辑后无需重启。

**关键不变量**：辅助请求必须原样透传、不得改写——auto 模式安全分类器
（`system[0]` 以 `You are a security monitor` 开头）与所有**无 tools** 的请求。改写分类器
会导致 "Auto mode could not evaluate this action" 一律拦截。日志中的 `透传(...)` 即此类
请求，`tools=N` 与 `sys0="首24字符"` 指纹用于发现新的"不该改写"的请求形态。

## CC Agent 环境变量

| 变量 | 默认 | 说明 |
|---|---|---|
| `PROXY_URL` | `http://127.0.0.1:8788` | 让 claude 走的代理地址 |
| `CLAUDE_BIN` | 自动探测 | 优先级：显式设置 > 打包内置 `vendor/claude/claude.exe` > PATH 中的 `claude` |
| `DATA_DIR` | `agent/data` | 会话索引与 transcript 存放目录 |
| `AGENT_PORT` | `8790` | 后端端口（Electron 内嵌启动时使用） |
| `REMOTE_DEBUG` | 开启 | 设为 `false` 关闭 9222 远程调试 |

## 目录结构

```
cc-agent/
├─ proxy/                     # 提示词改写代理(:8788)
│  ├─ proxy.js                # 丢弃英文 system[0], 注入中文提示词
│  ├─ system_1.zh.txt         # 老版提示词中文版(含 ${memoryPath} 占位符)
│  ├─ system_2.zh.txt         # 新版提示词中文版(# Harness / # Memory)
│  └─ .env                    # 代理配置(端口/上游/开关), 不入库
├─ docs/screenshots/          # README 界面截图
└─ agent/                     # CC Agent 桌面客户端
   ├─ server/                 # HTTP/SSE 后端: manager(会话/协议)、store(存储)、index(路由)
   ├─ web/                    # Vue3 + Vite 前端
   ├─ electron/               # Electron 主进程 / 预加载 / 框选截屏 overlay
   └─ tools/                  # pack.js 绿色版打包、test-mcp.js 测试用 MCP 服务器
```

## 数据与日志（不入库）

- `agent/data/`：会话索引/transcript、`settings-<id>.json`、`mcp.json`、
  `mcp-workspaces.json`、`claude-settings.json`（探针用基础 settings）。
- `proxy/proxy.log`：代理请求日志（每请求一行）。
- 用户侧：`~/.claude.json`（全局 MCP）、`~/.claude/settings.json`（env/权限）、
  `~/.claude/projects/<slug>/*.jsonl`（原生对话记录）、`~/cc-agent-workspaces/`（工作空间）。

## 说明

- 代理与后端都仅监听 `127.0.0.1`，面向本机单用户使用；工具会在所选工作空间内执行，自用请留意。
- 除桌面端外，也可以不启动 Electron：`node agent/server/index.js` 后用浏览器打开
  `http://127.0.0.1:8790`（前端开发用 `cd agent/web && npm run dev`）。
- 调试：Electron 默认开启 `127.0.0.1:9222` 远程调试，可用 chrome-devtools MCP
  （`--browserUrl http://127.0.0.1:9222`）驱动界面。
- 开发约定与更细的架构说明见 [CLAUDE.md](CLAUDE.md)；桌面端细节见
  [agent/README.md](agent/README.md)。