chatccc 0.2.309 → 0.2.310

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,213 +1,213 @@
1
- # ChatCCC
2
-
3
- **用飞书或微信聊天控制 Claude Code / Cursor / Codex / CCC Agent / DeepSeek Harness。**
4
-
5
- ChatCCC 把本地 AI 编程工具接入即时通讯软件。你可以在手机上发消息,让 Claude Code、Cursor Agent、Codex、内置 CCC Agent 或 DeepSeek Harness 继续写代码、查问题、跑命令;不用一直守在电脑前。
6
-
7
- 飞书是推荐入口:直接私聊机器人即可持续使用同一个专属会话,需要并行任务时再用 `/new` 创建独立会话群;卡片能流式更新,体验完整。微信 iLink 更适合快速试用或临时使用:扫码即可接入,但只能走私聊文本模式。
8
-
9
- <p align="center">
10
- <img src="images/img_readme_messages.jpg" alt="飞书会话列表" width="220" align="top" />
11
- &nbsp;
12
- <img src="images/img_readme_0.jpg" alt="飞书群聊中使用 ChatCCC" width="220" align="top" />
13
- &nbsp;
14
- <img src="images/img_readme_1.jpg" alt="思考过程和工具调用" width="220" align="top" />
15
- </p>
16
-
17
- ---
18
-
19
- ## 为什么用 ChatCCC
20
-
21
- - **手机上也能用 AI 编程工具**:在飞书或微信发消息,就像在终端给 Agent 下指令。
22
- - **飞书体验更完整**:私聊可持续对话,`/new` 创建的一群一会话支持多任务并行,CardKit 卡片可流式更新。
23
- - **微信接入更轻**:不用创建飞书应用,启动后扫码即可在微信私聊里使用。
24
- - **多 Agent 切换**:`/new` 使用默认 Agent,也可以用 `/new claude`、`/new cursor`、`/new codex`、`/new ccc`、`/new dsh` 指定工具。
1
+ # ChatCCC
2
+
3
+ **用飞书或微信聊天控制 Claude Code / Cursor / Codex / CCC Agent / DeepSeek Harness。**
4
+
5
+ ChatCCC 把本地 AI 编程工具接入即时通讯软件。你可以在手机上发消息,让 Claude Code、Cursor Agent、Codex、内置 CCC Agent 或 DeepSeek Harness 继续写代码、查问题、跑命令;不用一直守在电脑前。
6
+
7
+ 飞书是推荐入口:直接私聊机器人即可持续使用同一个专属会话,需要并行任务时再用 `/new` 创建独立会话群;卡片能流式更新,体验完整。微信 iLink 更适合快速试用或临时使用:扫码即可接入,但只能走私聊文本模式。
8
+
9
+ <p align="center">
10
+ <img src="images/img_readme_messages.jpg" alt="飞书会话列表" width="220" align="top" />
11
+ &nbsp;
12
+ <img src="images/img_readme_0.jpg" alt="飞书群聊中使用 ChatCCC" width="220" align="top" />
13
+ &nbsp;
14
+ <img src="images/img_readme_1.jpg" alt="思考过程和工具调用" width="220" align="top" />
15
+ </p>
16
+
17
+ ---
18
+
19
+ ## 为什么用 ChatCCC
20
+
21
+ - **手机上也能用 AI 编程工具**:在飞书或微信发消息,就像在终端给 Agent 下指令。
22
+ - **飞书体验更完整**:私聊可持续对话,`/new` 创建的一群一会话支持多任务并行,CardKit 卡片可流式更新。
23
+ - **微信接入更轻**:不用创建飞书应用,启动后扫码即可在微信私聊里使用。
24
+ - **多 Agent 切换**:`/new` 使用默认 Agent,也可以用 `/new claude`、`/new cursor`、`/new codex`、`/new ccc`、`/new dsh` 指定工具。
25
25
  - **群里能跑 git**:`/git status`、`/git pull`、`/git log` 会在当前会话工作目录执行,并把输出发回聊天窗口。
26
26
  - **飞书混合附件不丢失**:同一条富文本中的标题、文字、图片、视频和文件传给 Agent,兼容正文为空但标题和顶层 `files` 有内容的组合消息;保留正文顺序,顶层附件按原顺序补在正文后,并按文件 key 避免与内联附件重复。正文为空时兼容 `content_v2`,无法识别的富文本给出明确提示,不再静默忽略。视频保留原附件下载信息,不把封面误当成原视频。附件信息不完整时会明确提示。视频和文件仍由 Agent 按需下载处理,不代表模型原生支持视频输入。
27
-
28
- ## 飞书和微信的差异
29
-
30
- | 项目 | 飞书(推荐) | 微信 iLink |
31
- | --- | --- | --- |
32
- | 使用场景 | 长期主力使用 | 快速试用、临时远程控制 |
33
- | 会话形态 | 私聊固定专属会话;`/new` 创建一群一会话 | 私聊,一对一 |
34
- | 消息展示 | CardKit 卡片,流式更新 | 纯文本,增量推送 |
35
- | `/new` | 自动创建新群并绑定新会话 | 在当前私聊里创建新会话 |
36
- | 多会话并行 | 直接切换不同群 | 支持并行,使用切换指令后未完成的任务会继续在后台进行,但不如飞书直观方便 |
37
- | 群管理 | 支持创建、重命名、解散、头像 | 不支持 |
38
- | 接入成本 | 需要配置飞书应用 | 启动后扫码登录 |
39
-
40
- 如果你主要在手机上长期控制 AI 编程工具,优先用飞书;如果只是想马上跑起来,微信更省配置。
41
-
42
- ---
43
-
44
- ## 怎么部署
45
-
46
- ### 1. 安装
47
-
48
- #### Windows 一键安装(零依赖起步)
49
-
50
- 如果你的电脑没有装任何东西,**复制下面全部内容,打开 PowerShell 粘贴,回车**。脚本会自动检测并安装所有缺失的依赖,最后启动 ChatCCC。全程只需确认一次 UAC 弹窗。
51
-
52
- ```powershell
53
- # ============================================================
54
- # ChatCCC Windows 一键安装脚本
55
- # 用法: 复制全部内容 → 打开 PowerShell → 粘贴 → 回车
56
- # 优先用 winget(快),没有则直接下载安装包(零依赖)
57
- # ============================================================
58
-
59
- # --- 辅助函数:安装完程序后刷新 PATH,让当前窗口立即可用 ---
60
- function Refresh-Path {
61
- $env:Path = [System.Environment]::GetEnvironmentVariable('Path','Machine') + ';' + [System.Environment]::GetEnvironmentVariable('Path','User')
62
- }
63
-
64
- # --- 辅助函数:判断一个命令是否已安装 ---
65
- function Test-Cmd($name) { return [bool](Get-Command $name -ErrorAction SilentlyContinue) }
66
-
67
- # --- 判断 winget 是否可用 ---
68
- $useWinget = Test-Cmd winget
69
-
70
- Write-Host ''
71
- Write-Host '============================================================' -ForegroundColor Cyan
72
- Write-Host ' ChatCCC 环境检测与一键安装' -ForegroundColor Cyan
73
- if ($useWinget) {
74
- Write-Host ' 安装方式: winget(Windows 包管理器)' -ForegroundColor DarkGray
75
- } else {
76
- Write-Host ' 安装方式: 直接下载(无需 winget)' -ForegroundColor DarkGray
77
- }
78
- Write-Host '============================================================' -ForegroundColor Cyan
79
- Write-Host ''
80
-
81
- # ============================================================
82
- # [1/2] 安装 Node.js(ChatCCC 运行环境,要求 >= 20)
83
- # ============================================================
84
- if (Test-Cmd node) {
85
- Write-Host "[1/2] Node.js 已安装: $(node --version 2>$null)" -ForegroundColor Green
86
- } else {
87
- Write-Host '[1/2] Node.js 未安装,正在安装...' -ForegroundColor Yellow
88
-
89
- if ($useWinget) {
90
- # 方式 A:winget 安装(推荐,速度快)
91
- Write-Host ' (如弹出 UAC 窗口请点击"是")' -ForegroundColor DarkGray
92
- winget install OpenJS.NodeJS.LTS --accept-source-agreements --accept-package-agreements
93
- } else {
94
- # 方式 B:直接请求 Node.js 官网目录页,从页面中提取最新 LTS 安装包链接
95
- Write-Host ' 正在获取最新 LTS 版本...' -ForegroundColor DarkGray
96
- # 请求 latest-v22.x 目录页(返回该大版本下最新的小版本列表)
97
- $dirHtml = (Invoke-WebRequest 'https://nodejs.org/dist/latest-v22.x/' -UseBasicParsing).Content
98
- # 从 HTML 中匹配 MSI 文件名,如 node-v22.15.0-x64.msi
99
- $msiFile = [regex]::Match($dirHtml, 'node-v\d+\.\d+\.\d+-x64\.msi').Value
100
- if (-not $msiFile) {
101
- Write-Host ' 错误: 未能从页面中提取 MSI 下载链接' -ForegroundColor Red
102
- exit 1
103
- }
104
- Write-Host " 正在下载 $msiFile ..." -ForegroundColor DarkGray
105
- # 用提取到的文件名拼出完整下载链接
106
- $nodeMsi = "$env:TEMP\$msiFile"
107
- Invoke-WebRequest "https://nodejs.org/dist/latest-v22.x/$msiFile" -OutFile $nodeMsi
108
- Write-Host ' 正在静默安装(请稍候)...' -ForegroundColor DarkGray
109
- # /quiet 静默安装,/norestart 不自动重启
110
- Start-Process msiexec.exe -ArgumentList "/i `"$nodeMsi`" /quiet /norestart" -Wait
111
- Remove-Item $nodeMsi -Force
112
- }
113
-
114
- Refresh-Path
115
- Write-Host "[1/2] Node.js 安装完成: $(node --version 2>$null)" -ForegroundColor Green
116
- }
117
-
118
- # ============================================================
119
- # [2/2] 安装 ChatCCC 本体(npm 全局安装)
120
- # ============================================================
121
- Write-Host '[2/2] 正在从 npm 安装 ChatCCC...' -ForegroundColor Yellow
122
- npm install -g chatccc
123
- Write-Host '[2/2] ChatCCC 安装完成!' -ForegroundColor Green
124
-
125
- # ============================================================
126
- # 启动 ChatCCC(首次启动自动打开浏览器进入配置向导)
127
- # ============================================================
128
- Write-Host ''
129
- Write-Host '============================================================' -ForegroundColor Cyan
130
- Write-Host ' 环境就绪,正在启动 ChatCCC ...' -ForegroundColor Cyan
131
- Write-Host ' 浏览器将自动打开 Web 配置页面' -ForegroundColor Cyan
132
- Write-Host '============================================================' -ForegroundColor Cyan
133
- Write-Host ''
134
- chatccc
135
- ```
136
-
137
- 如果一切顺利,系统默认浏览器会自动打开 `http://localhost:18080/` 的 Web 配置页面。按页面提示填入飞书 App ID / App Secret,点击"保存并启动"即可。
138
-
139
- > **只想装 ChatCCC 本体?** 如果你已经有 Node.js,直接 `npm install -g chatccc && chatccc` 即可,不需要跑上面的完整脚本。
140
-
141
- #### 其他安装方式
142
-
143
- ```bash
144
- npm install -g chatccc
145
- chatccc
146
- ```
147
-
148
- 要求 Node.js >= 20。安装完成后,在任意目录执行 `chatccc` 即可启动。配置、日志和状态文件会保存在用户目录的 `.chatccc` 下:
149
-
150
- - Windows:`C:\Users\<用户名>\.chatccc\`
151
- - macOS / Linux:`~/.chatccc/`
152
-
153
- 旧版本留在仓库或包目录下的 `config.json`、`logs/`、`state/` 会在首次启动时自动迁移到用户目录。
154
-
155
- 每次直接运行 `chatccc` 时,无论是否已经完成配置,ChatCCC 默认都会用系统默认浏览器打开本地 Web UI(默认 `http://localhost:18080/`,修改 `config.port` 后跟随实际端口)。可在首次配置向导或管理页的 **Web UI** 设置中关闭;关闭后从下一次直接启动起生效。由 `/restart`、`/update` 或 Web UI 发起的内部重启始终不会重复打开浏览器。Linux 服务器没有 `DISPLAY`/`WAYLAND_DISPLAY` 时会跳过打开,并在终端输出 SSH 隧道访问提示。主页顶部的 **Agent Team** 入口会跳转到独立的 `/agent-team` 页面。
156
-
157
- #### 本地任务看板(Agent Team)
158
-
159
- Agent Team 提供本地任务看板和项目主 Agent 入口。每个规范化后的本机目录对应一个独立项目和看板,固定包含“头脑风暴、Todo、Doing、Done、搁置”五列,支持新增、单击卡片编辑、拖动排序和删除任务。页面会自动保存,不需要手动提交。当前按路径识别项目,不检查 Git 仓库或 worktree 关系,任意子目录都可以作为独立项目。
160
-
161
- 打开项目后可以选择 CCC、Claude、Cursor 或 Codex 作为主 Agent。首次设置会创建固定命名为 `主Agent-<目录短名>` 的飞书群和空 Agent Session;后续切换 Agent 或重新关联目录会复用原群,运行中的主 Agent 不允许切换。建群成员取自机器人最近一次收到的飞书私聊;如果尚无私聊记录,网页会提示先给机器人发送任意私聊消息并自动检测。项目群名不会随第一句话或 `/forget` 改变。
162
-
163
- 任务卡片可通过“交给主 Agent”启动真实执行:任务会从 Todo 移到 Doing,成功后自动移到 Done,失败、停止或中断则移到搁置并显示具体原因,支持安全重试。同一项目同一时间只运行一个看板任务;每次尝试都有独立的 Run ID、Trace ID、失败类型、耗时和完整执行时间线,可以在任务详情中切换历史尝试或复制记录。
164
-
165
- 运行中的时间线和最后进度会定期持久化;长时间没有进度会在看板中标记为疑似停滞,停止请求超过截止时间会强制收敛到终态。服务异常退出后会保留最后已写入的执行过程并把未完成任务标记为中断;启动时还会自动对账任务终态与卡片列,修复“Agent 已完成但卡片移动失败”等部分成功。损坏的单条运行 JSON 会被隔离为 `.corrupt-*` 文件,不会阻断同项目其他历史记录。
166
-
167
- 看板数据默认保存在 `~/.chatccc/agent-team/`,其中 `workspaces.json` 保存最近工作目录索引,`boards/` 保存按稳定 ID 分隔的看板 JSON,`main-agent-bindings/` 单独保存本机飞书群与 Session 绑定,`task-runs/` 保存每次任务执行及其诊断时间线。目录移动或重命名后,可从最近目录列表重新关联。数据访问通过仓储接口隔离,后续接入飞书多维表格时可增加双向同步适配器,无需把本机群聊和 Session 状态混入任务同步模型。选择目录、创建群聊和启动 Agent 等操作都由本机 Node 后端执行;当前实现不依赖 Electron。
168
-
169
- #### 从源码运行
170
-
171
- ```bash
172
- git clone https://github.com/wzj998/ChatCCC.git
173
- cd ChatCCC
174
- npm install
175
- npm run dev
176
- ```
177
-
178
- ### 2. 即时通讯软件配置
179
-
180
- #### 飞书(推荐)
181
-
182
- 如果 Chrome 已登录飞书开放平台,也可以让 Codex、Claude 或 Cursor 使用项目内的 [`create-chatccc-feishu-app`](.agents/skills/create-chatccc-feishu-app/SKILL.md) Skill,通过 Chrome DevTools/CDP 自动创建并配置机器人(默认 CDP 端口为 `15166`)。创建应用、开通权限和正式发布属于外部变更,执行前仍需明确确认;不要把 App Secret 写入对话或仓库。
183
-
184
- 1. 打开 [飞书开放平台](https://open.feishu.cn),创建一个**企业自建应用**。
185
- 2. 在「应用功能」里开启**机器人**能力。
186
- 3. 在「权限管理」里开通**所有权限名称以 `im:` 或 `cardkit:` 开头的权限**。不要只依赖事件页面自动推荐的权限;开通后应分别搜索这两个前缀并逐项确认:
187
-
188
- | 前缀 | 用途 |
189
- | --- | --- |
190
- | `im:` | 全部开通,用于收发消息、创建和管理群聊、机器人发言等 |
191
- | `cardkit:` | 全部开通,用于卡片展示、流式更新、按钮和交互回调等 |
192
-
193
- > [!IMPORTANT]
194
- > 请额外单独搜索并确认已开通 `im:message.p2p_msg:readonly`(获取用户发给机器人的单聊消息)。这个权限在飞书开发者后台配置时容易遗漏;缺少它可能导致 ChatCCC 无法正常识别或处理私聊消息。
195
-
196
- <p align="center">
197
- <img src="images/img_readme_permission.png" alt="飞书应用权限配置" width="280" />
198
- </p>
199
-
200
- 4. 在「事件与回调」里订阅 `im.message.receive_v1` 和 `card.action.trigger`。
201
-
202
- <p align="center">
203
- <img src="images/img_readme_event.png" alt="飞书事件订阅" width="280" />
204
- &emsp;
205
- <img src="images/img_readme_callback.png" alt="飞书请求网址与回调" width="280" />
206
- </p>
207
-
208
- 5. 创建应用版本并发布(企业内部可用即可)。
209
- 6. 在「凭证与基础信息」复制 **App ID** 和 **App Secret**,填入本地 Web 配置向导或 `config.json`。
210
-
27
+
28
+ ## 飞书和微信的差异
29
+
30
+ | 项目 | 飞书(推荐) | 微信 iLink |
31
+ | --- | --- | --- |
32
+ | 使用场景 | 长期主力使用 | 快速试用、临时远程控制 |
33
+ | 会话形态 | 私聊固定专属会话;`/new` 创建一群一会话 | 私聊,一对一 |
34
+ | 消息展示 | CardKit 卡片,流式更新 | 纯文本,增量推送 |
35
+ | `/new` | 自动创建新群并绑定新会话 | 在当前私聊里创建新会话 |
36
+ | 多会话并行 | 直接切换不同群 | 支持并行,使用切换指令后未完成的任务会继续在后台进行,但不如飞书直观方便 |
37
+ | 群管理 | 支持创建、重命名、解散、头像 | 不支持 |
38
+ | 接入成本 | 需要配置飞书应用 | 启动后扫码登录 |
39
+
40
+ 如果你主要在手机上长期控制 AI 编程工具,优先用飞书;如果只是想马上跑起来,微信更省配置。
41
+
42
+ ---
43
+
44
+ ## 怎么部署
45
+
46
+ ### 1. 安装
47
+
48
+ #### Windows 一键安装(零依赖起步)
49
+
50
+ 如果你的电脑没有装任何东西,**复制下面全部内容,打开 PowerShell 粘贴,回车**。脚本会自动检测并安装所有缺失的依赖,最后启动 ChatCCC。全程只需确认一次 UAC 弹窗。
51
+
52
+ ```powershell
53
+ # ============================================================
54
+ # ChatCCC Windows 一键安装脚本
55
+ # 用法: 复制全部内容 → 打开 PowerShell → 粘贴 → 回车
56
+ # 优先用 winget(快),没有则直接下载安装包(零依赖)
57
+ # ============================================================
58
+
59
+ # --- 辅助函数:安装完程序后刷新 PATH,让当前窗口立即可用 ---
60
+ function Refresh-Path {
61
+ $env:Path = [System.Environment]::GetEnvironmentVariable('Path','Machine') + ';' + [System.Environment]::GetEnvironmentVariable('Path','User')
62
+ }
63
+
64
+ # --- 辅助函数:判断一个命令是否已安装 ---
65
+ function Test-Cmd($name) { return [bool](Get-Command $name -ErrorAction SilentlyContinue) }
66
+
67
+ # --- 判断 winget 是否可用 ---
68
+ $useWinget = Test-Cmd winget
69
+
70
+ Write-Host ''
71
+ Write-Host '============================================================' -ForegroundColor Cyan
72
+ Write-Host ' ChatCCC 环境检测与一键安装' -ForegroundColor Cyan
73
+ if ($useWinget) {
74
+ Write-Host ' 安装方式: winget(Windows 包管理器)' -ForegroundColor DarkGray
75
+ } else {
76
+ Write-Host ' 安装方式: 直接下载(无需 winget)' -ForegroundColor DarkGray
77
+ }
78
+ Write-Host '============================================================' -ForegroundColor Cyan
79
+ Write-Host ''
80
+
81
+ # ============================================================
82
+ # [1/2] 安装 Node.js(ChatCCC 运行环境,要求 >= 20)
83
+ # ============================================================
84
+ if (Test-Cmd node) {
85
+ Write-Host "[1/2] Node.js 已安装: $(node --version 2>$null)" -ForegroundColor Green
86
+ } else {
87
+ Write-Host '[1/2] Node.js 未安装,正在安装...' -ForegroundColor Yellow
88
+
89
+ if ($useWinget) {
90
+ # 方式 A:winget 安装(推荐,速度快)
91
+ Write-Host ' (如弹出 UAC 窗口请点击"是")' -ForegroundColor DarkGray
92
+ winget install OpenJS.NodeJS.LTS --accept-source-agreements --accept-package-agreements
93
+ } else {
94
+ # 方式 B:直接请求 Node.js 官网目录页,从页面中提取最新 LTS 安装包链接
95
+ Write-Host ' 正在获取最新 LTS 版本...' -ForegroundColor DarkGray
96
+ # 请求 latest-v22.x 目录页(返回该大版本下最新的小版本列表)
97
+ $dirHtml = (Invoke-WebRequest 'https://nodejs.org/dist/latest-v22.x/' -UseBasicParsing).Content
98
+ # 从 HTML 中匹配 MSI 文件名,如 node-v22.15.0-x64.msi
99
+ $msiFile = [regex]::Match($dirHtml, 'node-v\d+\.\d+\.\d+-x64\.msi').Value
100
+ if (-not $msiFile) {
101
+ Write-Host ' 错误: 未能从页面中提取 MSI 下载链接' -ForegroundColor Red
102
+ exit 1
103
+ }
104
+ Write-Host " 正在下载 $msiFile ..." -ForegroundColor DarkGray
105
+ # 用提取到的文件名拼出完整下载链接
106
+ $nodeMsi = "$env:TEMP\$msiFile"
107
+ Invoke-WebRequest "https://nodejs.org/dist/latest-v22.x/$msiFile" -OutFile $nodeMsi
108
+ Write-Host ' 正在静默安装(请稍候)...' -ForegroundColor DarkGray
109
+ # /quiet 静默安装,/norestart 不自动重启
110
+ Start-Process msiexec.exe -ArgumentList "/i `"$nodeMsi`" /quiet /norestart" -Wait
111
+ Remove-Item $nodeMsi -Force
112
+ }
113
+
114
+ Refresh-Path
115
+ Write-Host "[1/2] Node.js 安装完成: $(node --version 2>$null)" -ForegroundColor Green
116
+ }
117
+
118
+ # ============================================================
119
+ # [2/2] 安装 ChatCCC 本体(npm 全局安装)
120
+ # ============================================================
121
+ Write-Host '[2/2] 正在从 npm 安装 ChatCCC...' -ForegroundColor Yellow
122
+ npm install -g chatccc
123
+ Write-Host '[2/2] ChatCCC 安装完成!' -ForegroundColor Green
124
+
125
+ # ============================================================
126
+ # 启动 ChatCCC(首次启动自动打开浏览器进入配置向导)
127
+ # ============================================================
128
+ Write-Host ''
129
+ Write-Host '============================================================' -ForegroundColor Cyan
130
+ Write-Host ' 环境就绪,正在启动 ChatCCC ...' -ForegroundColor Cyan
131
+ Write-Host ' 浏览器将自动打开 Web 配置页面' -ForegroundColor Cyan
132
+ Write-Host '============================================================' -ForegroundColor Cyan
133
+ Write-Host ''
134
+ chatccc
135
+ ```
136
+
137
+ 如果一切顺利,系统默认浏览器会自动打开 `http://localhost:18080/` 的 Web 配置页面。按页面提示填入飞书 App ID / App Secret,点击"保存并启动"即可。
138
+
139
+ > **只想装 ChatCCC 本体?** 如果你已经有 Node.js,直接 `npm install -g chatccc && chatccc` 即可,不需要跑上面的完整脚本。
140
+
141
+ #### 其他安装方式
142
+
143
+ ```bash
144
+ npm install -g chatccc
145
+ chatccc
146
+ ```
147
+
148
+ 要求 Node.js >= 20。安装完成后,在任意目录执行 `chatccc` 即可启动。配置、日志和状态文件会保存在用户目录的 `.chatccc` 下:
149
+
150
+ - Windows:`C:\Users\<用户名>\.chatccc\`
151
+ - macOS / Linux:`~/.chatccc/`
152
+
153
+ 旧版本留在仓库或包目录下的 `config.json`、`logs/`、`state/` 会在首次启动时自动迁移到用户目录。
154
+
155
+ 每次直接运行 `chatccc` 时,无论是否已经完成配置,ChatCCC 默认都会用系统默认浏览器打开本地 Web UI(默认 `http://localhost:18080/`,修改 `config.port` 后跟随实际端口)。可在首次配置向导或管理页的 **Web UI** 设置中关闭;关闭后从下一次直接启动起生效。由 `/restart`、`/update` 或 Web UI 发起的内部重启始终不会重复打开浏览器。Linux 服务器没有 `DISPLAY`/`WAYLAND_DISPLAY` 时会跳过打开,并在终端输出 SSH 隧道访问提示。主页顶部的 **Agent Team** 入口会跳转到独立的 `/agent-team` 页面。
156
+
157
+ #### 本地任务看板(Agent Team)
158
+
159
+ Agent Team 提供本地任务看板和项目主 Agent 入口。每个规范化后的本机目录对应一个独立项目和看板,固定包含“头脑风暴、Todo、Doing、Done、搁置”五列,支持新增、单击卡片编辑、拖动排序和删除任务。页面会自动保存,不需要手动提交。当前按路径识别项目,不检查 Git 仓库或 worktree 关系,任意子目录都可以作为独立项目。
160
+
161
+ 打开项目后可以选择 CCC、Claude、Cursor 或 Codex 作为主 Agent。首次设置会创建固定命名为 `主Agent-<目录短名>` 的飞书群和空 Agent Session;后续切换 Agent 或重新关联目录会复用原群,运行中的主 Agent 不允许切换。建群成员取自机器人最近一次收到的飞书私聊;如果尚无私聊记录,网页会提示先给机器人发送任意私聊消息并自动检测。项目群名不会随第一句话或 `/forget` 改变。
162
+
163
+ 任务卡片可通过“交给主 Agent”启动真实执行:任务会从 Todo 移到 Doing,成功后自动移到 Done,失败、停止或中断则移到搁置并显示具体原因,支持安全重试。同一项目同一时间只运行一个看板任务;每次尝试都有独立的 Run ID、Trace ID、失败类型、耗时和完整执行时间线,可以在任务详情中切换历史尝试或复制记录。
164
+
165
+ 运行中的时间线和最后进度会定期持久化;长时间没有进度会在看板中标记为疑似停滞,停止请求超过截止时间会强制收敛到终态。服务异常退出后会保留最后已写入的执行过程并把未完成任务标记为中断;启动时还会自动对账任务终态与卡片列,修复“Agent 已完成但卡片移动失败”等部分成功。损坏的单条运行 JSON 会被隔离为 `.corrupt-*` 文件,不会阻断同项目其他历史记录。
166
+
167
+ 看板数据默认保存在 `~/.chatccc/agent-team/`,其中 `workspaces.json` 保存最近工作目录索引,`boards/` 保存按稳定 ID 分隔的看板 JSON,`main-agent-bindings/` 单独保存本机飞书群与 Session 绑定,`task-runs/` 保存每次任务执行及其诊断时间线。目录移动或重命名后,可从最近目录列表重新关联。数据访问通过仓储接口隔离,后续接入飞书多维表格时可增加双向同步适配器,无需把本机群聊和 Session 状态混入任务同步模型。选择目录、创建群聊和启动 Agent 等操作都由本机 Node 后端执行;当前实现不依赖 Electron。
168
+
169
+ #### 从源码运行
170
+
171
+ ```bash
172
+ git clone https://github.com/wzj998/ChatCCC.git
173
+ cd ChatCCC
174
+ npm install
175
+ npm run dev
176
+ ```
177
+
178
+ ### 2. 即时通讯软件配置
179
+
180
+ #### 飞书(推荐)
181
+
182
+ 如果 Chrome 已登录飞书开放平台,也可以让 Codex、Claude 或 Cursor 使用项目内的 [`create-chatccc-feishu-app`](.agents/skills/create-chatccc-feishu-app/SKILL.md) Skill,通过 Chrome DevTools/CDP 自动创建并配置机器人(默认 CDP 端口为 `15166`)。创建应用、开通权限和正式发布属于外部变更,执行前仍需明确确认;不要把 App Secret 写入对话或仓库。
183
+
184
+ 1. 打开 [飞书开放平台](https://open.feishu.cn),创建一个**企业自建应用**。
185
+ 2. 在「应用功能」里开启**机器人**能力。
186
+ 3. 在「权限管理」里开通**所有权限名称以 `im:` 或 `cardkit:` 开头的权限**。不要只依赖事件页面自动推荐的权限;开通后应分别搜索这两个前缀并逐项确认:
187
+
188
+ | 前缀 | 用途 |
189
+ | --- | --- |
190
+ | `im:` | 全部开通,用于收发消息、创建和管理群聊、机器人发言等 |
191
+ | `cardkit:` | 全部开通,用于卡片展示、流式更新、按钮和交互回调等 |
192
+
193
+ > [!IMPORTANT]
194
+ > 请额外单独搜索并确认已开通 `im:message.p2p_msg:readonly`(获取用户发给机器人的单聊消息)。这个权限在飞书开发者后台配置时容易遗漏;缺少它可能导致 ChatCCC 无法正常识别或处理私聊消息。
195
+
196
+ <p align="center">
197
+ <img src="images/img_readme_permission.png" alt="飞书应用权限配置" width="280" />
198
+ </p>
199
+
200
+ 4. 在「事件与回调」里订阅 `im.message.receive_v1` 和 `card.action.trigger`。
201
+
202
+ <p align="center">
203
+ <img src="images/img_readme_event.png" alt="飞书事件订阅" width="280" />
204
+ &emsp;
205
+ <img src="images/img_readme_callback.png" alt="飞书请求网址与回调" width="280" />
206
+ </p>
207
+
208
+ 5. 创建应用版本并发布(企业内部可用即可)。
209
+ 6. 在「凭证与基础信息」复制 **App ID** 和 **App Secret**,填入本地 Web 配置向导或 `config.json`。
210
+
211
211
  如果你同时使用公司飞书和个人飞书,建议把个人账号放在另一个客户端里:安卓可用系统「应用双开」,iOS 可用 Lark。
212
212
 
213
213
  #### 最终回复的表格汇总
@@ -219,275 +219,277 @@ npm run dev
219
219
  汇总表格不冻结首列,所有列一起横向滚动,避免手机端表头换行时冻结区域与其余列出现纵向偏移;长名称仍允许自动换行。升级只影响新生成的卡片,历史卡片不会自动重排。
220
220
 
221
221
  受[飞书表格组件限制](https://open.feishu.cn/document/feishu-cards/card-json-v2-components/content-components/table),超过每卡 5 个表格、每表 50 列或消息大小预算时,会按行/列分段并标注编号,全部数据保留。单个单元格或表头过长时,改用标明位置的完整文本续页;客户端可能折叠较长单元格,可点击查看。补充卡片发送失败会记录日志,原回复仍可使用;为避免重连或结果不确定时重复发送,不自动重发补充卡片。若进程恰好在原回复成功后退出,补充卡片可能未发完。
222
-
223
- #### 微信 iLink(可选)
224
-
225
- 微信模式不需要创建飞书应用。保持 `config.json` 里的 `platforms.ilink.enabled` 为 `true`(默认开启),启动 `chatccc` 后,终端会打印微信扫码登录二维码。
226
-
227
- ```bash
228
- chatccc
229
- # 控制台出现二维码后,用微信扫一扫登录
230
- # 在微信里找到机器人,发送 /new 开始对话
231
- ```
232
-
233
- 微信登录信息会保存到 `~/.chatccc/state/ilink-auth.json`。token 过期后重新扫码即可。
234
-
235
- ### 3. AI 工具配置
236
-
237
- Claude Code、Cursor 和 Codex 需要对应的本地工具;CCC Agent 内置于 ChatCCC,开箱即用,**模型接入不限于 DeepSeek**——它支持 OpenAI-compatible 和 Anthropic Messages 两种协议(详见下文 CCC Agent)。DeepSeek Harness(DSH)采用按需安装,不计入 ChatCCC 主包生产依赖。
238
-
239
- #### CCC Agent
240
-
222
+
223
+ #### 微信 iLink(可选)
224
+
225
+ 微信模式不需要创建飞书应用。保持 `config.json` 里的 `platforms.ilink.enabled` 为 `true`(默认开启),启动 `chatccc` 后,终端会打印微信扫码登录二维码。
226
+
227
+ ```bash
228
+ chatccc
229
+ # 控制台出现二维码后,用微信扫一扫登录
230
+ # 在微信里找到机器人,发送 /new 开始对话
231
+ ```
232
+
233
+ 微信登录信息会保存到 `~/.chatccc/state/ilink-auth.json`。token 过期后重新扫码即可。
234
+
235
+ ### 3. AI 工具配置
236
+
237
+ Claude Code、Cursor 和 Codex 需要对应的本地工具;CCC Agent 内置于 ChatCCC,开箱即用,**模型接入不限于 DeepSeek**——它支持 OpenAI-compatible 和 Anthropic Messages 两种协议(详见下文 CCC Agent)。DeepSeek Harness(DSH)采用按需安装,不计入 ChatCCC 主包生产依赖。
238
+
239
+ #### CCC Agent
240
+
241
241
  CCC Agent 是 ChatCCC 内置的编程 Agent,不需要额外安装 CLI,开箱即用。在首次配置向导或 Web 管理页中启用后,填写 API Key、Base URL 和模型即可使用;它可以设为 `/new` 的默认 Agent,也可以通过 `/new ccc` 显式创建会话。
242
242
 
243
243
  CCC Agent 支持图片理解:飞书/微信发送的图片与独立 DeepCCC 的 Web/CLI 附件共用内核,可看多张截图、图表及本地 `read_image` 工具产物。支持 PNG/JPEG/WebP/GIF,每条最多 10 张、单图 20 MiB、图片合计 24 MiB。主模型支持视觉时直接传图;主模型不支持时,可在设置页填写“图片模型”(`ccc.visionModel`,如 `deepseek-flash`),先由它观察图片,再由主模型继续任务。留空跟随独立 DeepCCC 的 `visionModel`;两边都未配置则使用主模型原生视觉。图片模型复用当前 API Key/Base URL/协议,界面显示实际使用的模型;错误不会静默降级。历史保存附件引用,日志过滤图片编码。详见 [DeepCCC 图片与 CLI 用法](deepccc-agent/README.md)。
244
244
 
245
245
  纯 CLI 用户可以运行 `cccagent --image "C:\截图\报错.png"` 后输入问题,或在运行中的交互终端等待回复结束后输入 `/image "图片路径"`,再发下一条问题。多图重复添加;一次性运行可用 `cccagent --stream-json --prompt "解释截图" --image "图片路径"`。`cccagent` 读取 `~/.deepccc/config.json` 或 `DEEPCCC_*` 环境变量。
246
-
247
- CCC Agent 支持**协作式让位**:任务运行期间你可以继续在群里发消息,ChatCCC 会在 Agent 的每个模型步骤边界把新消息注入当前任务,不打断正在执行的工具步骤、不新开一轮对话。已完成的中间工作会保留,Agent 收到插话后会调整后续方向。运行中的消息进入独立的注入队列(深度 50),与整轮排队(深度 1)分离。飞书中每条消息实际注入后,机器人会发送一条最多 200 字的回执,冻结注入前的过程卡片,并用新的“生成中”卡片展示后续过程。
248
-
249
- DeepCCC 同时提供独立端口的本地 Web UI。ChatCCC 管理页顶部点击 **DeepCCC Web** 会复用或按需启动该服务;只全局安装 `deepccc` 的用户直接运行 `deepccc` 即可启动并打开网页版,终端模式改用 `deepccc-cli`。默认地址为 `http://127.0.0.1:28080/`,端口可通过 `~/.deepccc/config.json` 的 `web.port` 修改。网页版支持多会话并发、持久化历史、会话级 model/effort、API 设置和会话内高风险操作审批。
250
-
251
- ChatCCC 会把 `ccc.DEEPSEEK_API_KEY`、`ccc.DEEPSEEK_BASE_URL` 和模型显式传给内置 Agent;API Key 为空时 CCC Agent 会自动保持禁用。`ccc.effort` 与 `ccc.maxOutputTokens` 是可选 override:非空时覆盖 DeepCCC,留空时跟随 `~/.deepccc/config.json` / `DEEPCCC_*` 环境变量,DeepCCC 也未配置时使用模型服务端默认值。DeepCCC 的传输层选项 `provider`(默认 `openai`)和 `streaming`(默认 `true`)同样可通过内核配置,无需额外安装独立 CLI。
252
-
253
- **协议 override:** 也可以在 ChatCCC 的配置(`config.json` 的 `ccc.provider`,或 Web 管理页的「CCC Agent → API 协议」)显式指定 `openai` / `anthropic` 覆盖内核配置;留空(默认)时跟随 `~/.deepccc/config.json` / `DEEPCCC_PROVIDER`。`streaming` 不做 override,始终由 DeepCCC 内核配置控制。
254
-
255
- **Git 共同作者:** DeepCCC 默认给它创建的提交追加 `Co-authored-by: DeepCCC <20184052+wzj998@users.noreply.github.com>`,保留用户为主 Author。全局开关是 `~/.deepccc/config.json` 的 `git.coAuthor.enabled`(缺省 `true`);ChatCCC 的 `ccc.gitCoAuthor` 为三态 override:`null`/缺失跟随全局,`true` 强制开启,`false` 强制关闭。Web 管理页的「CCC Agent → Git 提交共同作者」可设置同样的三种状态。
256
-
257
- **API 支持不限于 DeepSeek。** 默认的 `provider: "openai"` 使用 OpenAI 兼容协议(`@ai-sdk/openai-compatible`),DeepSeek 只是出厂默认端点;设置 `provider: "anthropic"` 后改用 Anthropic Messages 协议(`@ai-sdk/anthropic`)。两种模式都支持流式输出,并复用相同的 API Key、Base URL 和模型配置。
258
-
259
- | 服务 | Base URL 示例 | 说明 |
260
- | --- | --- | --- |
261
- | DeepSeek(默认) | `https://api.deepseek.com/v1` | 官方端点,支持 `/usage` 余额查询 |
262
- | OpenAI | `https://api.openai.com/v1` | 官方模型 |
263
- | Kimi / Moonshot | `https://api.moonshot.cn/v1` | 国内直连 |
264
- | 通义千问 / 智谱 GLM / 豆包 / MiniMax | 各家 `…/v1` 端点 | 国内 OpenAI 兼容服务 |
265
- | Ollama / vLLM / LM Studio | `http://localhost:11434/v1` | 本地或自建推理服务 |
266
-
267
- 更换服务只需把 `ccc.DEEPSEEK_BASE_URL` 改为对应端点、`ccc.DEEPSEEK_API_KEY` 改为对应 Key、`ccc.model` 改为目标模型名即可。`effort` 留空时不会由 ChatCCC override DeepCCC;若两边都留空,则不发送 `reasoning_effort`。只有确认目标模型支持时才应显式填写,否则服务端可能返回参数错误。余额查询仅对官方 DeepSeek 域名(`api.deepseek.com`)生效,指向其他端点时自动跳过,不影响对话。
268
-
269
- `ccc.alternativeModel` 是单个备选模型,只会加入 `/model` 的人工切换列表,不会在请求失败时自动重试或切换,避免重复执行带副作用的工具调用。
270
-
271
- #### Claude Code
272
-
273
- ChatCCC 通过 Anthropic Claude Agent SDK 调用 Claude Code 能力。SDK 引擎(含 Claude Code CLI 原生二进制,约 220MB)**按需下载**:在首次配置向导或 Web 管理页打开 Claude Code 开关,或点击一次安装按钮,页面会连续显示环境检查、下载、校验、Runtime 验证、原子切换和清理进度,不需要逐步确认。**只有启用 Claude Code 的用户才需要下载**,不使用 Claude Code 的安装不包含该引擎,chatccc 主包体积保持精简。
274
-
275
- SDK 始终使用其内置的 Claude Code CLI(档位 b),不依赖用户自行安装的 `claude` 命令。本机完成 Claude Code 登录后即可使用(SDK 复用 `~/.claude` 登录态);同时支持官方和第三方 Anthropic 兼容 API:使用官方服务无需额外配置,使用第三方 API 则填写 `claude.apiKey` 和 `claude.baseUrl`。`claude.model`、`claude.subagentModel`、`claude.effort`、`claude.apiKey`、`claude.baseUrl` 均为选填;`claude.maxTurn` 控制每次对话的最大轮数(默认 0,即无限制)。填写后会把对应配置传给 Claude Agent SDK;留空则以 `~/.claude/settings.json` 为准。
276
-
277
- #### DeepSeek Harness
278
-
279
- DeepSeek Harness 是可选 Agent。在首次配置向导或 Web 管理页打开 DSH 开关,ChatCCC 会一次点击完成环境检查、临时目录准备、精确版本下载、包校验、Runtime 握手、原子切换和旧版本清理,并在页面逐步显示进度。安装失败时不会替换当前可用版本;刷新页面后仍可恢复安装进度。当前固定安装 `0.1.0-rc.6`,要求 Node.js >= 22.19.0。
280
-
281
- DSH 引擎安装在 `~/.chatccc/engines/dsh/`,不加入 ChatCCC 的 `dependencies`。配置 `dsh.apiKey`、`dsh.baseUrl`、`dsh.model`、`dsh.provider` 和 `dsh.maxTokens` 后,可设为默认 Agent 或使用 `/new dsh` 新建会话。安装验证只做本地 JSON-RPC Runtime 握手,不会调用付费模型。
282
-
283
- #### Cursor Agent CLI
284
-
285
- Windows 推荐安装:
286
-
287
- ```powershell
288
- irm 'https://cursor.com/install?win32=true' | iex
289
- agent login
290
- ```
291
-
292
- 验证:
293
-
294
- ```bash
295
- agent --version
296
- ```
297
-
298
- #### Codex CLI
299
-
300
- ```bash
301
- npm install -g @openai/codex
302
- codex login
303
- codex --version
304
- ```
305
-
306
- Codex 的默认模型和推理强度可继续由 `~/.codex/config.toml` 管理,也可以在 `config.json` 中覆盖。
307
-
308
- ChatCCC 通过 Codex 的 **app-server 模式**(一个常驻进程 + WebSocket JSON-RPC)驱动 Codex,而不是一次性 `codex exec` 子进程。因此 Codex 与 CCC Agent 一样支持**协作式让位**:任务运行期间继续发消息,ChatCCC 会在 Codex 的工具步骤边界把消息注入当前 turn(`turn/steer`),不打断正在执行的命令、不丢已完成的工作;飞书会在 `turn/steer` 成功后发送注入回执,并从新的过程卡片继续展示。`/stop` 通过 `turn/interrupt` 只打断当前 turn,不影响同进程内的其他会话。权限策略与旧 exec 的 `--dangerously-bypass-approvals-and-sandbox` 等价(零审批、完整沙箱权限),`/plan`、`/ask` 退化为只读沙箱。要求 Codex CLI >= 0.60.0(建议保持最新版)。
309
-
310
- #### 可选:Chrome CDP
311
-
312
- 常驻 Chrome CDP 开关用于维护本机 Chrome DevTools Protocol 端口;Codex `/usage` 可通过它读取 ChatGPT 订阅到期时间和剩余天数。
313
-
314
- 依赖:
315
-
316
- - 本机已安装 **Google Chrome**。
317
- - 查询 ChatGPT 订阅到期时间时,需要在这个 CDP 专用 Chrome 窗口里登录 ChatGPT。
318
-
319
- 默认端口是 `15166`,健康检查地址是 `http://127.0.0.1:15166/json/version`。Windows 下留空 `chromeDevtools.chromePath` 时会自动查找 Google Chrome。
320
-
321
- ### 4. `config.json`
322
-
323
- `~/.chatccc/config.json` 不存在时,ChatCCC 会从 `config.sample.json` 复制一份。常用结构如下:
324
-
325
- ```json
326
- {
327
- "feishu": {
328
- "appId": "cli_xxxxxxxxxxxx",
329
- "appSecret": "xxxxxxxxxxxxxxxxxxxxxxxxxx"
330
- },
331
- "platforms": {
332
- "feishu": { "enabled": true, "platformType": "feishu" },
333
- "ilink": { "enabled": true, "reuseTokenOnStart": true }
334
- },
335
- "webUi": {
336
- "openOnStart": true
337
- },
338
- "chromeDevtools": {
339
- "enabled": false,
340
- "port": 15166,
341
- "chromePath": ""
342
- },
343
- "port": 18080,
344
- "gitTimeoutSeconds": 180,
345
- "allowInterrupt": false,
346
- "claude": {
347
- "enabled": false,
348
- "defaultAgent": true,
349
- "model": "claude-sonnet-4-6",
350
- "subagentModel": "",
351
- "effort": "",
352
- "apiKey": "",
353
- "baseUrl": "",
354
- "maxTurn": 0
355
- },
356
- "cursor": {
357
- "enabled": false,
358
- "defaultAgent": false,
359
- "path": "",
360
- "model": "",
361
- "alternativeModel": "",
362
- "avatarBatteryMode": "apiPercent",
363
- "onDemandMonthlyBudget": 1000
364
- },
365
- "codex": {
366
- "enabled": false,
367
- "defaultAgent": false,
368
- "path": "",
369
- "model": "",
370
- "alternativeModel": "",
371
- "effort": "",
372
- "fastMode": false
373
- },
374
- "ccc": {
375
- "enabled": false,
376
- "defaultAgent": false,
377
- "DEEPSEEK_API_KEY": "",
378
- "DEEPSEEK_BASE_URL": "https://api.deepseek.com/v1",
379
- "model": "deepseek-v4-pro",
380
- "alternativeModel": "",
381
- "gitCoAuthor": null
382
- }
383
- }
384
- ```
385
-
386
- | 字段 | 说明 |
387
- | --- | --- |
388
- | `feishu.appId` / `feishu.appSecret` | 飞书应用凭证 |
389
- | `platforms.feishu.enabled` | 是否启用飞书 |
390
- | `platforms.feishu.platformType` | 飞书平台类型,默认 `feishu` |
391
- | `platforms.ilink.enabled` | 是否启用微信 iLink |
392
- | `platforms.ilink.reuseTokenOnStart` | 启动时是否复用已有微信登录 token |
393
- | `webUi.openOnStart` | 直接启动时是否打开系统默认浏览器;默认 true,内部重启始终跳过 |
394
- | `chromeDevtools.enabled` | 是否启用常驻 Chrome CDP;默认 false |
395
- | `chromeDevtools.port` | Chrome CDP 端口;默认 15166 |
396
- | `chromeDevtools.chromePath` | Chrome 可执行文件路径;留空时自动探测 |
397
- | `port` | 本地 Web 配置面板和中继服务端口 |
398
- | `gitTimeoutSeconds` | `/git` 命令超时时间,默认 180 秒 |
399
- | `allowInterrupt` | 是否允许新消息中断正在运行的任务;默认 false |
400
- | `*.enabled` | 是否启用对应 AI Agent |
401
- | `*.defaultAgent` | `/new` 未指定 Agent 时使用哪个工具;飞书私聊会在下一条普通消息到达时跟随变化并创建新的空会话 |
402
- | `cursor.path` / `codex.path` | CLI 可执行文件路径;留空时自动探测或使用 PATH |
403
- | `codex.fastMode` | Codex Fast 模式的全局默认值;默认 `false`,每次调用都会显式覆盖 Codex CLI 的 service tier |
404
- | `cursor.avatarBatteryMode` | Cursor 头像电量显示来源:`apiPercent` 或 `onDemandUse` |
405
- | `cursor.onDemandMonthlyBudget` | `avatarBatteryMode=onDemandUse` 时用于计算电量的月预算 |
406
- | `claude.model` / `claude.subagentModel` / `claude.effort` | 选填;设置后传给 Claude Agent SDK,留空以 `~/.claude/settings.json` 为准 |
407
- | `claude.apiKey` / `claude.baseUrl` | 选填;设置后传给 Claude Agent SDK,留空以 `~/.claude/settings.json` 为准 |
408
- | `claude.maxTurn` | 选填;Claude 最大对话轮数,默认 0(无限制),可在 Web UI 编辑 |
409
- | `cursor.alternativeModel` / `codex.alternativeModel` / `ccc.alternativeModel` / `dsh.alternativeModel` | 单个备选模型;加入 `/model` 人工切换列表,不会自动故障转移 |
410
- | `ccc.DEEPSEEK_API_KEY` / `ccc.DEEPSEEK_BASE_URL` | CCC Agent 的 API Key 和服务地址;**不限于 DeepSeek**——可填任意 OpenAI 兼容端点(OpenAI、Kimi、通义、智谱、Ollama 本地等) |
411
- | `ccc.model` | CCC Agent 默认模型 |
412
- | `ccc.subModel` | CCC Agent 子模型(选填):用于内部轻量环节(压缩摘要生成、task 子代理任务);留空跟随主模型 |
413
- | `ccc.effort` | CCC Agent 推理强度 override;留空跟随 DeepCCC 内核配置,内核也留空时使用模型服务端默认值 |
414
- | `ccc.maxOutputTokens` | CCC Agent 主对话最大输出 token override;正整数,`null`/留空时跟随 DeepCCC 内核配置,内核也未配置时使用模型服务端默认值 |
415
- | `ccc.compactionTimeoutMs` | CCC Agent 上下文压缩单轮超时(毫秒),默认 300000(5 分钟);压缩超时会让整轮对话失败,建议保持默认或调大 |
416
- | `ccc.contextWindow` | CCC Agent 模型上下文窗口(token),默认 1048576(1M,DeepSeek V4 Pro/Flash 原生规格);压缩阈值自动 = 窗口 × 80%;超过模型/服务端实际上限会被 API 拒绝,可在 Web UI 下拉选择或自定义(单位 k) |
417
- | `dsh.apiKey` / `dsh.baseUrl` | DeepSeek Harness 的 API Key 和官方 DeepSeek 服务地址 |
418
- | `dsh.model` / `dsh.provider` / `dsh.maxTokens` | DSH 默认模型、Runtime provider 和最大 token 数 |
419
- | `dsh.subModel` | DSH 子代理模型(选填):用于 `subagent` 工具派生的子代理;留空跟随主模型(与 `ccc.subModel` 语义一致) |
420
-
421
- > **权限控制**:普通消息以 `bypassPermissions` 模式运行,跳过 Agent 操作确认。使用 `/plan` 或 `/ask` 前缀时,ChatCCC 自动切换为只读模式:Claude SDK 仅放行 Read + stop-stuck-loop 网络请求,Codex 使用 `--sandbox read-only`,Cursor 使用 `--mode plan/ask`。请只在可信环境中使用。
422
-
423
- ### 5. 开始使用
424
-
425
- **飞书:** 找到机器人后直接发送普通消息,即可在当前私聊中创建并持续使用专属 AI 会话;私聊工作目录固定为运行 ChatCCC 的系统账号用户目录。默认 Agent 发生变化后,下一条私聊普通消息会触发切换并创建新的空会话;若旧 Agent 正在生成,该消息会先排队,待当前回复完成后再切换。命令不会触发自动切换。需要独立任务时,发送 `/new`、`/new claude`、`/new cursor`、`/new codex`、`/new ccc` 或 `/new dsh`,机器人会另外创建会话群。
426
-
427
- **微信:** 扫码登录后,在机器人私聊里发送 `/new` 或指定 Agent 的 `/new ...` 命令即可开始。功能与飞书基本一致,但展示为纯文本。
428
-
246
+
247
+ CCC Agent 支持**协作式让位**:任务运行期间你可以继续在群里发消息,ChatCCC 会在 Agent 的每个模型步骤边界把新消息注入当前任务,不打断正在执行的工具步骤、不新开一轮对话。已完成的中间工作会保留,Agent 收到插话后会调整后续方向。运行中的消息进入独立的注入队列(深度 50),与整轮排队(深度 1)分离。飞书中每条消息实际注入后,机器人会发送一条最多 200 字的回执,冻结注入前的过程卡片,并用新的“生成中”卡片展示后续过程。
248
+
249
+ DeepCCC 同时提供独立端口的本地 Web UI。ChatCCC 管理页顶部点击 **DeepCCC Web** 会复用或按需启动该服务;只全局安装 `deepccc` 的用户直接运行 `deepccc` 即可启动并打开网页版,终端模式改用 `deepccc-cli`。默认地址为 `http://127.0.0.1:28080/`,端口可通过 `~/.deepccc/config.json` 的 `web.port` 修改。网页版支持多会话并发、持久化历史、会话级 model/effort、API 设置和会话内高风险操作审批。
250
+
251
+ ChatCCC 会把 `ccc.DEEPSEEK_API_KEY`、`ccc.DEEPSEEK_BASE_URL` 和模型显式传给内置 Agent;API Key 为空时 CCC Agent 会自动保持禁用。`ccc.effort` 与 `ccc.maxOutputTokens` 是可选 override:非空时覆盖 DeepCCC,留空时跟随 `~/.deepccc/config.json` / `DEEPCCC_*` 环境变量,DeepCCC 也未配置时使用模型服务端默认值。DeepCCC 的传输层选项 `provider`(默认 `openai`)和 `streaming`(默认 `true`)同样可通过内核配置,无需额外安装独立 CLI。
252
+
253
+ **协议 override:** 也可以在 ChatCCC 的配置(`config.json` 的 `ccc.provider`,或 Web 管理页的「CCC Agent → API 协议」)显式指定 `openai` / `openai-responses` / `anthropic` 覆盖内核配置;留空(默认)时跟随 `~/.deepccc/config.json` / `DEEPCCC_PROVIDER`。`streaming` 不做 override,始终由 DeepCCC 内核配置控制。
254
+
255
+ **Git 共同作者:** DeepCCC 默认给它创建的提交追加 `Co-authored-by: DeepCCC <20184052+wzj998@users.noreply.github.com>`,保留用户为主 Author。全局开关是 `~/.deepccc/config.json` 的 `git.coAuthor.enabled`(缺省 `true`);ChatCCC 的 `ccc.gitCoAuthor` 为三态 override:`null`/缺失跟随全局,`true` 强制开启,`false` 强制关闭。Web 管理页的「CCC Agent → Git 提交共同作者」可设置同样的三种状态。
256
+
257
+ **OpenAI Responses:** Web 管理页「CCC Agent → API 协议」选择 `openai-responses`,Base URL 填 `https://api.openai.com/v1`,填写该 API 组织的密钥和可用模型(如 `gpt-6.2-sol`),保存后重启 ChatCCC。内嵌 DeepCCC 的主模型、子模型、图片模型和摘要共用此协议;原有配置不自动切换。Responses 使用 `store:false` 并在工具循环中续传加密推理状态。
258
+
259
+ **API 支持不限于 DeepSeek。** 默认的 `provider: "openai"` 使用 OpenAI 兼容协议(`@ai-sdk/openai-compatible`),DeepSeek 只是出厂默认端点;设置 `provider: "anthropic"` 后改用 Anthropic Messages 协议(`@ai-sdk/anthropic`)。三种模式都支持流式输出,并复用相同的 API Key、Base URL 和模型配置。
260
+
261
+ | 服务 | Base URL 示例 | 说明 |
262
+ | --- | --- | --- |
263
+ | DeepSeek(默认) | `https://api.deepseek.com/v1` | 官方端点,支持 `/usage` 余额查询 |
264
+ | OpenAI | `https://api.openai.com/v1` | GPT-6.2 等模型的工具调用请选择 `openai-responses` |
265
+ | Kimi / Moonshot | `https://api.moonshot.cn/v1` | 国内直连 |
266
+ | 通义千问 / 智谱 GLM / 豆包 / MiniMax | 各家 `…/v1` 端点 | 国内 OpenAI 兼容服务 |
267
+ | Ollama / vLLM / LM Studio | `http://localhost:11434/v1` | 本地或自建推理服务 |
268
+
269
+ 更换服务只需把 `ccc.DEEPSEEK_BASE_URL` 改为对应端点、`ccc.DEEPSEEK_API_KEY` 改为对应 Key、`ccc.model` 改为目标模型名即可。`effort` 留空时不会由 ChatCCC override DeepCCC;若两边都留空,则不发送 `reasoning_effort`。只有确认目标模型支持时才应显式填写,否则服务端可能返回参数错误。余额查询仅对官方 DeepSeek 域名(`api.deepseek.com`)生效,指向其他端点时自动跳过,不影响对话。
270
+
271
+ `ccc.alternativeModel` 是单个备选模型,只会加入 `/model` 的人工切换列表,不会在请求失败时自动重试或切换,避免重复执行带副作用的工具调用。
272
+
273
+ #### Claude Code
274
+
275
+ ChatCCC 通过 Anthropic Claude Agent SDK 调用 Claude Code 能力。SDK 引擎(含 Claude Code CLI 原生二进制,约 220MB)**按需下载**:在首次配置向导或 Web 管理页打开 Claude Code 开关,或点击一次安装按钮,页面会连续显示环境检查、下载、校验、Runtime 验证、原子切换和清理进度,不需要逐步确认。**只有启用 Claude Code 的用户才需要下载**,不使用 Claude Code 的安装不包含该引擎,chatccc 主包体积保持精简。
276
+
277
+ SDK 始终使用其内置的 Claude Code CLI(档位 b),不依赖用户自行安装的 `claude` 命令。本机完成 Claude Code 登录后即可使用(SDK 复用 `~/.claude` 登录态);同时支持官方和第三方 Anthropic 兼容 API:使用官方服务无需额外配置,使用第三方 API 则填写 `claude.apiKey` 和 `claude.baseUrl`。`claude.model`、`claude.subagentModel`、`claude.effort`、`claude.apiKey`、`claude.baseUrl` 均为选填;`claude.maxTurn` 控制每次对话的最大轮数(默认 0,即无限制)。填写后会把对应配置传给 Claude Agent SDK;留空则以 `~/.claude/settings.json` 为准。
278
+
279
+ #### DeepSeek Harness
280
+
281
+ DeepSeek Harness 是可选 Agent。在首次配置向导或 Web 管理页打开 DSH 开关,ChatCCC 会一次点击完成环境检查、临时目录准备、精确版本下载、包校验、Runtime 握手、原子切换和旧版本清理,并在页面逐步显示进度。安装失败时不会替换当前可用版本;刷新页面后仍可恢复安装进度。当前固定安装 `0.1.0-rc.6`,要求 Node.js >= 22.19.0。
282
+
283
+ DSH 引擎安装在 `~/.chatccc/engines/dsh/`,不加入 ChatCCC 的 `dependencies`。配置 `dsh.apiKey`、`dsh.baseUrl`、`dsh.model`、`dsh.provider` 和 `dsh.maxTokens` 后,可设为默认 Agent 或使用 `/new dsh` 新建会话。安装验证只做本地 JSON-RPC Runtime 握手,不会调用付费模型。
284
+
285
+ #### Cursor Agent CLI
286
+
287
+ Windows 推荐安装:
288
+
289
+ ```powershell
290
+ irm 'https://cursor.com/install?win32=true' | iex
291
+ agent login
292
+ ```
293
+
294
+ 验证:
295
+
296
+ ```bash
297
+ agent --version
298
+ ```
299
+
300
+ #### Codex CLI
301
+
302
+ ```bash
303
+ npm install -g @openai/codex
304
+ codex login
305
+ codex --version
306
+ ```
307
+
308
+ Codex 的默认模型和推理强度可继续由 `~/.codex/config.toml` 管理,也可以在 `config.json` 中覆盖。
309
+
310
+ ChatCCC 通过 Codex 的 **app-server 模式**(一个常驻进程 + WebSocket JSON-RPC)驱动 Codex,而不是一次性 `codex exec` 子进程。因此 Codex 与 CCC Agent 一样支持**协作式让位**:任务运行期间继续发消息,ChatCCC 会在 Codex 的工具步骤边界把消息注入当前 turn(`turn/steer`),不打断正在执行的命令、不丢已完成的工作;飞书会在 `turn/steer` 成功后发送注入回执,并从新的过程卡片继续展示。`/stop` 通过 `turn/interrupt` 只打断当前 turn,不影响同进程内的其他会话。权限策略与旧 exec 的 `--dangerously-bypass-approvals-and-sandbox` 等价(零审批、完整沙箱权限),`/plan`、`/ask` 退化为只读沙箱。要求 Codex CLI >= 0.60.0(建议保持最新版)。
311
+
312
+ #### 可选:Chrome CDP
313
+
314
+ 常驻 Chrome CDP 开关用于维护本机 Chrome DevTools Protocol 端口;Codex `/usage` 可通过它读取 ChatGPT 订阅到期时间和剩余天数。
315
+
316
+ 依赖:
317
+
318
+ - 本机已安装 **Google Chrome**。
319
+ - 查询 ChatGPT 订阅到期时间时,需要在这个 CDP 专用 Chrome 窗口里登录 ChatGPT。
320
+
321
+ 默认端口是 `15166`,健康检查地址是 `http://127.0.0.1:15166/json/version`。Windows 下留空 `chromeDevtools.chromePath` 时会自动查找 Google Chrome。
322
+
323
+ ### 4. `config.json`
324
+
325
+ `~/.chatccc/config.json` 不存在时,ChatCCC 会从 `config.sample.json` 复制一份。常用结构如下:
326
+
327
+ ```json
328
+ {
329
+ "feishu": {
330
+ "appId": "cli_xxxxxxxxxxxx",
331
+ "appSecret": "xxxxxxxxxxxxxxxxxxxxxxxxxx"
332
+ },
333
+ "platforms": {
334
+ "feishu": { "enabled": true, "platformType": "feishu" },
335
+ "ilink": { "enabled": true, "reuseTokenOnStart": true }
336
+ },
337
+ "webUi": {
338
+ "openOnStart": true
339
+ },
340
+ "chromeDevtools": {
341
+ "enabled": false,
342
+ "port": 15166,
343
+ "chromePath": ""
344
+ },
345
+ "port": 18080,
346
+ "gitTimeoutSeconds": 180,
347
+ "allowInterrupt": false,
348
+ "claude": {
349
+ "enabled": false,
350
+ "defaultAgent": true,
351
+ "model": "claude-sonnet-4-6",
352
+ "subagentModel": "",
353
+ "effort": "",
354
+ "apiKey": "",
355
+ "baseUrl": "",
356
+ "maxTurn": 0
357
+ },
358
+ "cursor": {
359
+ "enabled": false,
360
+ "defaultAgent": false,
361
+ "path": "",
362
+ "model": "",
363
+ "alternativeModel": "",
364
+ "avatarBatteryMode": "apiPercent",
365
+ "onDemandMonthlyBudget": 1000
366
+ },
367
+ "codex": {
368
+ "enabled": false,
369
+ "defaultAgent": false,
370
+ "path": "",
371
+ "model": "",
372
+ "alternativeModel": "",
373
+ "effort": "",
374
+ "fastMode": false
375
+ },
376
+ "ccc": {
377
+ "enabled": false,
378
+ "defaultAgent": false,
379
+ "DEEPSEEK_API_KEY": "",
380
+ "DEEPSEEK_BASE_URL": "https://api.deepseek.com/v1",
381
+ "model": "deepseek-v4-pro",
382
+ "alternativeModel": "",
383
+ "gitCoAuthor": null
384
+ }
385
+ }
386
+ ```
387
+
388
+ | 字段 | 说明 |
389
+ | --- | --- |
390
+ | `feishu.appId` / `feishu.appSecret` | 飞书应用凭证 |
391
+ | `platforms.feishu.enabled` | 是否启用飞书 |
392
+ | `platforms.feishu.platformType` | 飞书平台类型,默认 `feishu` |
393
+ | `platforms.ilink.enabled` | 是否启用微信 iLink |
394
+ | `platforms.ilink.reuseTokenOnStart` | 启动时是否复用已有微信登录 token |
395
+ | `webUi.openOnStart` | 直接启动时是否打开系统默认浏览器;默认 true,内部重启始终跳过 |
396
+ | `chromeDevtools.enabled` | 是否启用常驻 Chrome CDP;默认 false |
397
+ | `chromeDevtools.port` | Chrome CDP 端口;默认 15166 |
398
+ | `chromeDevtools.chromePath` | Chrome 可执行文件路径;留空时自动探测 |
399
+ | `port` | 本地 Web 配置面板和中继服务端口 |
400
+ | `gitTimeoutSeconds` | `/git` 命令超时时间,默认 180 秒 |
401
+ | `allowInterrupt` | 是否允许新消息中断正在运行的任务;默认 false |
402
+ | `*.enabled` | 是否启用对应 AI Agent |
403
+ | `*.defaultAgent` | `/new` 未指定 Agent 时使用哪个工具;飞书私聊会在下一条普通消息到达时跟随变化并创建新的空会话 |
404
+ | `cursor.path` / `codex.path` | CLI 可执行文件路径;留空时自动探测或使用 PATH |
405
+ | `codex.fastMode` | Codex Fast 模式的全局默认值;默认 `false`,每次调用都会显式覆盖 Codex CLI 的 service tier |
406
+ | `cursor.avatarBatteryMode` | Cursor 头像电量显示来源:`apiPercent` 或 `onDemandUse` |
407
+ | `cursor.onDemandMonthlyBudget` | `avatarBatteryMode=onDemandUse` 时用于计算电量的月预算 |
408
+ | `claude.model` / `claude.subagentModel` / `claude.effort` | 选填;设置后传给 Claude Agent SDK,留空以 `~/.claude/settings.json` 为准 |
409
+ | `claude.apiKey` / `claude.baseUrl` | 选填;设置后传给 Claude Agent SDK,留空以 `~/.claude/settings.json` 为准 |
410
+ | `claude.maxTurn` | 选填;Claude 最大对话轮数,默认 0(无限制),可在 Web UI 编辑 |
411
+ | `cursor.alternativeModel` / `codex.alternativeModel` / `ccc.alternativeModel` / `dsh.alternativeModel` | 单个备选模型;加入 `/model` 人工切换列表,不会自动故障转移 |
412
+ | `ccc.DEEPSEEK_API_KEY` / `ccc.DEEPSEEK_BASE_URL` | CCC Agent 的 API Key 和服务地址;**不限于 DeepSeek**——可填任意 OpenAI 兼容端点(OpenAI、Kimi、通义、智谱、Ollama 本地等) |
413
+ | `ccc.model` | CCC Agent 默认模型 |
414
+ | `ccc.subModel` | CCC Agent 子模型(选填):用于内部轻量环节(压缩摘要生成、task 子代理任务);留空跟随主模型 |
415
+ | `ccc.effort` | CCC Agent 推理强度 override;留空跟随 DeepCCC 内核配置,内核也留空时使用模型服务端默认值 |
416
+ | `ccc.maxOutputTokens` | CCC Agent 主对话最大输出 token override;正整数,`null`/留空时跟随 DeepCCC 内核配置,内核也未配置时使用模型服务端默认值 |
417
+ | `ccc.compactionTimeoutMs` | CCC Agent 上下文压缩单轮超时(毫秒),默认 300000(5 分钟);压缩超时会让整轮对话失败,建议保持默认或调大 |
418
+ | `ccc.contextWindow` | CCC Agent 模型上下文窗口(token),默认 1048576(1M,DeepSeek V4 Pro/Flash 原生规格);压缩阈值自动 = 窗口 × 80%;超过模型/服务端实际上限会被 API 拒绝,可在 Web UI 下拉选择或自定义(单位 k) |
419
+ | `dsh.apiKey` / `dsh.baseUrl` | DeepSeek Harness 的 API Key 和官方 DeepSeek 服务地址 |
420
+ | `dsh.model` / `dsh.provider` / `dsh.maxTokens` | DSH 默认模型、Runtime provider 和最大 token 数 |
421
+ | `dsh.subModel` | DSH 子代理模型(选填):用于 `subagent` 工具派生的子代理;留空跟随主模型(与 `ccc.subModel` 语义一致) |
422
+
423
+ > **权限控制**:普通消息以 `bypassPermissions` 模式运行,跳过 Agent 操作确认。使用 `/plan` 或 `/ask` 前缀时,ChatCCC 自动切换为只读模式:Claude SDK 仅放行 Read + stop-stuck-loop 网络请求,Codex 使用 `--sandbox read-only`,Cursor 使用 `--mode plan/ask`。请只在可信环境中使用。
424
+
425
+ ### 5. 开始使用
426
+
427
+ **飞书:** 找到机器人后直接发送普通消息,即可在当前私聊中创建并持续使用专属 AI 会话;私聊工作目录固定为运行 ChatCCC 的系统账号用户目录。默认 Agent 发生变化后,下一条私聊普通消息会触发切换并创建新的空会话;若旧 Agent 正在生成,该消息会先排队,待当前回复完成后再切换。命令不会触发自动切换。需要独立任务时,发送 `/new`、`/new claude`、`/new cursor`、`/new codex`、`/new ccc` 或 `/new dsh`,机器人会另外创建会话群。
428
+
429
+ **微信:** 扫码登录后,在机器人私聊里发送 `/new` 或指定 Agent 的 `/new ...` 命令即可开始。功能与飞书基本一致,但展示为纯文本。
430
+
429
431
  **会话停滞保护:** 只有 Agent 明确进入“生成回复中”后,连续没有新增回复字符或推理进展心跳且尚未报告权威终态,ChatCCC 才判定停滞:**DeepCCC(CCC Agent)默认等待 10 分钟,其他 Agent 仍为 3 分钟**。触发后结束旧执行,并优先补发一次“完成了吗?如果没完成继续”;恢复轮使用同一阈值,再次停滞时不再递归续跑,日志及恢复失败提示会显示对应时长。这是 ChatCCC 的流式无进展保护,不是整轮时长上限,也不修改模型服务或工具超时;独立 DeepCCC CLI/Web 不受此看门狗配置影响。启动、上下文压缩、思考、搜索和工具调用阶段不会触发这项回复停滞计时;DeepCCC 关闭 streaming 时只会在请求完成后一次性返回结果,因此不会启用这项基于流式进度的停滞检测。其中 CCC Agent 会单独显示“压缩上下文中”,压缩最多等待 5 分钟,失败时直接报告具体原因且不自动重放。`/new claude` 和 `/new cursor` 等创建会话操作仍有独立的 3 分钟 init 超时,进程资源监控也继续负责识别真正僵死。Codex 只有 `turn.completed` 才算权威终态,阶段性的 `agent_message` 不算;任一 Agent 报告权威终态后若输出流仍超过 10 秒未关闭,ChatCCC 会强制清理该 CLI 并按正常完成收尾,不会重复询问 Agent。
430
-
431
- **CCC Agent 代码搜索:** `search_code` 使用项目自带的跨平台 ripgrep,不要求系统另行安装 `rg`。如果当前平台没有可用的 bundled/system ripgrep,会自动降级为内置 Node 搜索,并继续支持常用正则、glob、结果上限、中止和超时控制。
432
-
433
- **项目理解与证据:** CCC 与独立 DeepCCC 共用通用内核。`search_code` 默认按项目范围降噪;明确指定子目录/文件时默认扩大范围,也可使用 `scope: "all"` 搜索 `.venv`、`node_modules`、隐藏和被忽略文件,并非禁止访问依赖。结果显示搜索范围、排除规则、警告与截断情况。`workspace_map` 提供按需的本地文件/词法符号地图;涉及项目实现的对话会获得小预算导航,不把地图重复写进聊天历史。`remember_project_fact` 可保存带原文和文件哈希的项目笔记,源文件改变或删除后不再注入该笔记。缓存位于 `~/.deepccc/workspace-index/`,不修改业务仓库,也不需要新增向量数据库或模型下载。地图和笔记只是查证入口,不能代替阅读当前源码。详见 [DeepCCC 项目理解说明](deepccc-agent/docs/workspace-understanding.md)。
434
-
435
- **长会话上下文:** 压缩摘要按“当前状态 / 仍待处理 / 已取代历史 / 项目事实 / 证据与局限 / 操作记录”重写,最近消息、明确纠正和当前源码优先于旧摘要。单次或单 seed 结果不会在提示中被升级成“彻底证伪”。同一轮多次工具调用时,较早的大结果只在后续模型步骤中缩短(界面与原始日志仍保留既有记录),最近结果优先保留,工具调用与结果配对不会被破坏。自动项目导航还覆盖范式、策略、实验、指标、进度等常见项目问法;明确表示与当前项目无关时不会扫描地图。
436
-
437
- ## 可用指令
438
-
439
- | 指令 | 作用 |
440
- | --- | --- |
441
- | `/new` | 使用默认 Agent 创建新会话;飞书中会创建新群 |
442
- | `/new claude` | 创建 Claude Code 会话;飞书中会创建新群 |
443
- | `/new cursor` | 创建 Cursor 会话;飞书中会创建新群 |
444
- | `/new codex` | 创建 Codex 会话;飞书中会创建新群 |
445
- | `/new ccc` | 创建内置 CCC Agent 会话;飞书中会创建新群 |
446
- | `/new dsh` | 创建 DeepSeek Harness 会话;飞书中会创建新群 |
447
- | `/forget` | 在当前聊天原地重置会话(忘掉上下文);群聊保留工作目录,飞书私聊固定使用系统用户目录 |
448
- | `/model` | 查看或切换当前会话的模型 |
449
- | `/fast` | 查看当前 Codex 会话的 Fast 模式;使用 `/fast on` 或 `/fast off` 切换 |
450
- | `/stop` | 停止当前回复 |
451
- | `/cancel` | 取消当前会话里排队等待处理的消息 |
452
- | `/state` | 查看当前会话状态 |
453
- | `/cd` | 查看或设置后续新建会话的默认工作目录,不改变当前会话;飞书私聊自身始终使用系统用户目录 |
454
- | `/sessions` | 查看所有会话状态 |
455
- | `/session <数字>` | 将当前群聊切换到 `/sessions` 列表中的指定会话;飞书私聊不支持切换 |
456
- | `/usage` | 查看当前会话对应 Agent 的用量;Codex 使用本机 Codex 登录凭据中的账户 ID 查询额度,只显示接口实际返回的 5h/7天窗口,主动重置次数查询失败时会明确展示上次成功快照及其查询时间(缓存结果不提供重置按钮);Cursor 显示当前周期用量,CCC Agent 和 DSH 仅在官方 DeepSeek 端点时显示账户余额(其他兼容端点自动跳过) |
457
- | `/git <子命令>` | 在当前会话工作目录执行 `git ...` 并回传输出 |
458
- | `/abd<内容>` | 去掉 `/abd` 前缀后把内容发给 Agent,并在消息末尾追加第一性原理需求澄清提示 |
459
- | `/plan <内容>` | 只读计划模式:仅允许读文件和 stop-stuck-loop 请求,不执行任何写操作 |
460
- | `/ask <内容>` | 只读问答模式:与 /plan 相同,仅允许读文件和 stop-stuck-loop 请求 |
461
- | `/restart` | 重启机器人进程 |
462
- | `/restart safe` / `/restartsf` | 停止接受新任务,等待现有会话、缓存消息和依赖安装完成后重启 |
463
- | `/update` | 更新 npm 全局包并重启(仅限 `npm install -g chatccc` 安装的全局进程;同一飞书事件跨重启去重) |
464
- | `/update safe` / `/updatesf` | 停止接受新任务,排空现有工作后更新并重启 |
465
- | `/safestatus` | 查看安全重启/更新的等待状态 |
466
- | `/cancelsf` | 取消尚未开始执行的安全重启/更新预约 |
467
- | `/deleteg` | 解散当前飞书会话群;Agent 会话记录保留 |
468
-
469
- `/update`、`/update safe` 与短别名 `/updatesf` 会把飞书消息或按钮事件 ID 原子写入 `~/.chatccc/state/update-command-guard.json`。同一 ID 跨重启重投时会静默忽略;用户主动发送的新更新指令因事件 ID 不同,仍可执行。该保护不改变普通消息与重启指令的处理方式。
470
-
471
- `/restart safe`(短别名 `/restartsf`)与 `/update safe`(短别名 `/updatesf`)会先建立全局准入门禁:指令到达前已经运行或进入单会话缓存队列的工作会继续完成,之后到达的新普通任务会被提示在维护完成后重发。维护任务持久化到 `~/.chatccc/state/safe-maintenance.json`,进程意外退出后可继续排空;依赖安装、会话收尾、自动恢复和 Agent Teams 执行也计入等待条件。内存缓存随重启自然重建,磁盘会话、看板、图片等持久数据不会被清理。
472
-
473
- ChatCCC 的普通内部重启使用跨平台父子进程握手:替代进程完成启动预检后通知父进程退出,再等待旧监听端口实际释放并接管 PID;替代进程未就绪或握手超时时,父进程会保留并继续服务。自更新则先把仅依赖 Node.js 的更新器复制到 `~/.chatccc/update/`,确认更新器就绪后退出旧进程,再由安装目录外的更新器执行 npm 安装并启动新版,从而避免 Windows 因运行中进程或原生模块占用全局包目录而报 `EBUSY`。更新失败时会尝试恢复并重启原版本,详细记录写入 `~/.chatccc/logs/update-watcher.log`。
474
-
475
- Codex 和 Cursor 在 Linux/macOS 下使用独立进程组。停止时先显示“正在停止”,待进程组内后代退出后再显示“已停止”;仅外层 shell 退出不算清理完成。重复停止请求合并处理,清理失败会保留会话进程占用保护并报告“Agent 停止未完成”,后续请求必须先完成清理才能启动新 Agent。Windows 继续使用 `taskkill /T /F`,命令失败或超时不会当作成功。
476
-
477
- 飞书接收长连接启用 15 秒握手超时和 30 秒心跳应答超时;首次启动最多等待 45 秒真实连接确认后才提示就绪。运行期间连接持续异常 90 秒时,会关闭并重新建立接收连接,保留会话、消息去重和正在执行的任务。没有用户消息不会触发重连。连接状态与恢复记录写入运行日志和 `startup-trace.log`(`FEISHU-CONNECTION` / `feishu-connection`)。卡片更新遇到网络失败或序号冲突时不会当成送达成功,错误通知保留文本兜底;TLS 断线会明确显示为网络连接失败,已中断的 Agent 任务不会因此自动重放。
478
-
479
- > **模型切换**:`/model` 查看当前会话 Agent 的可选模型清单,`/model <名称>` 模糊匹配切换,`/model clear` 恢复默认。可选模型来自当前 Agent 的配置:Claude 使用 `claude.model` / `claude.subagentModel`;Cursor、Codex、CCC Agent 和 DSH 使用各自的 `model` / `alternativeModel`。
480
-
481
- Agent 的初始化、输入回显与重连通知不代表任务成功。Cursor、Codex 和 Claude 缺少成功完成事件,或任一 Agent 没有产生有效回复时,会明确提示异常;已生成的部分回复会保留并标为可能不完整。Cursor 重连过程显示在状态区,上游的 `resource_exhausted` / `unavailable` 分别提示请求受限 / 服务暂不可用,不推断为余额耗尽。执行失败不会自动重放整条任务。
482
-
483
- > **Codex Fast 模式**:Web UI 中的“Fast 模式”设置新 Codex 会话的全局默认值,默认关闭。进入 Codex 会话后,`/fast` 查询当前状态,`/fast on` 和 `/fast off` 只覆盖当前会话并从下一条消息生效。ChatCCC 会显式向 Codex CLI 传入 `service_tier="fast"` 或 `service_tier="default"`,因此关闭时不会继承用户 `config.toml` 中可能开启的 Fast。
484
-
485
- ---
486
-
432
+
433
+ **CCC Agent 代码搜索:** `search_code` 使用项目自带的跨平台 ripgrep,不要求系统另行安装 `rg`。如果当前平台没有可用的 bundled/system ripgrep,会自动降级为内置 Node 搜索,并继续支持常用正则、glob、结果上限、中止和超时控制。
434
+
435
+ **项目理解与证据:** CCC 与独立 DeepCCC 共用通用内核。`search_code` 默认按项目范围降噪;明确指定子目录/文件时默认扩大范围,也可使用 `scope: "all"` 搜索 `.venv`、`node_modules`、隐藏和被忽略文件,并非禁止访问依赖。结果显示搜索范围、排除规则、警告与截断情况。`workspace_map` 提供按需的本地文件/词法符号地图;涉及项目实现的对话会获得小预算导航,不把地图重复写进聊天历史。`remember_project_fact` 可保存带原文和文件哈希的项目笔记,源文件改变或删除后不再注入该笔记。缓存位于 `~/.deepccc/workspace-index/`,不修改业务仓库,也不需要新增向量数据库或模型下载。地图和笔记只是查证入口,不能代替阅读当前源码。详见 [DeepCCC 项目理解说明](deepccc-agent/docs/workspace-understanding.md)。
436
+
437
+ **长会话上下文:** 压缩摘要按“当前状态 / 仍待处理 / 已取代历史 / 项目事实 / 证据与局限 / 操作记录”重写,最近消息、明确纠正和当前源码优先于旧摘要。单次或单 seed 结果不会在提示中被升级成“彻底证伪”。同一轮多次工具调用时,较早的大结果只在后续模型步骤中缩短(界面与原始日志仍保留既有记录),最近结果优先保留,工具调用与结果配对不会被破坏。自动项目导航还覆盖范式、策略、实验、指标、进度等常见项目问法;明确表示与当前项目无关时不会扫描地图。
438
+
439
+ ## 可用指令
440
+
441
+ | 指令 | 作用 |
442
+ | --- | --- |
443
+ | `/new` | 使用默认 Agent 创建新会话;飞书中会创建新群 |
444
+ | `/new claude` | 创建 Claude Code 会话;飞书中会创建新群 |
445
+ | `/new cursor` | 创建 Cursor 会话;飞书中会创建新群 |
446
+ | `/new codex` | 创建 Codex 会话;飞书中会创建新群 |
447
+ | `/new ccc` | 创建内置 CCC Agent 会话;飞书中会创建新群 |
448
+ | `/new dsh` | 创建 DeepSeek Harness 会话;飞书中会创建新群 |
449
+ | `/forget` | 在当前聊天原地重置会话(忘掉上下文);群聊保留工作目录,飞书私聊固定使用系统用户目录 |
450
+ | `/model` | 查看或切换当前会话的模型 |
451
+ | `/fast` | 查看当前 Codex 会话的 Fast 模式;使用 `/fast on` 或 `/fast off` 切换 |
452
+ | `/stop` | 停止当前回复 |
453
+ | `/cancel` | 取消当前会话里排队等待处理的消息 |
454
+ | `/state` | 查看当前会话状态 |
455
+ | `/cd` | 查看或设置后续新建会话的默认工作目录,不改变当前会话;飞书私聊自身始终使用系统用户目录 |
456
+ | `/sessions` | 查看所有会话状态 |
457
+ | `/session <数字>` | 将当前群聊切换到 `/sessions` 列表中的指定会话;飞书私聊不支持切换 |
458
+ | `/usage` | 查看当前会话对应 Agent 的用量;Codex 使用本机 Codex 登录凭据中的账户 ID 查询额度,只显示接口实际返回的 5h/7天窗口,主动重置次数查询失败时会明确展示上次成功快照及其查询时间(缓存结果不提供重置按钮);Cursor 显示当前周期用量,CCC Agent 和 DSH 仅在官方 DeepSeek 端点时显示账户余额(其他兼容端点自动跳过) |
459
+ | `/git <子命令>` | 在当前会话工作目录执行 `git ...` 并回传输出 |
460
+ | `/abd<内容>` | 去掉 `/abd` 前缀后把内容发给 Agent,并在消息末尾追加第一性原理需求澄清提示 |
461
+ | `/plan <内容>` | 只读计划模式:仅允许读文件和 stop-stuck-loop 请求,不执行任何写操作 |
462
+ | `/ask <内容>` | 只读问答模式:与 /plan 相同,仅允许读文件和 stop-stuck-loop 请求 |
463
+ | `/restart` | 重启机器人进程 |
464
+ | `/restart safe` / `/restartsf` | 停止接受新任务,等待现有会话、缓存消息和依赖安装完成后重启 |
465
+ | `/update` | 更新 npm 全局包并重启(仅限 `npm install -g chatccc` 安装的全局进程;同一飞书事件跨重启去重) |
466
+ | `/update safe` / `/updatesf` | 停止接受新任务,排空现有工作后更新并重启 |
467
+ | `/safestatus` | 查看安全重启/更新的等待状态 |
468
+ | `/cancelsf` | 取消尚未开始执行的安全重启/更新预约 |
469
+ | `/deleteg` | 解散当前飞书会话群;Agent 会话记录保留 |
470
+
471
+ `/update`、`/update safe` 与短别名 `/updatesf` 会把飞书消息或按钮事件 ID 原子写入 `~/.chatccc/state/update-command-guard.json`。同一 ID 跨重启重投时会静默忽略;用户主动发送的新更新指令因事件 ID 不同,仍可执行。该保护不改变普通消息与重启指令的处理方式。
472
+
473
+ `/restart safe`(短别名 `/restartsf`)与 `/update safe`(短别名 `/updatesf`)会先建立全局准入门禁:指令到达前已经运行或进入单会话缓存队列的工作会继续完成,之后到达的新普通任务会被提示在维护完成后重发。维护任务持久化到 `~/.chatccc/state/safe-maintenance.json`,进程意外退出后可继续排空;依赖安装、会话收尾、自动恢复和 Agent Teams 执行也计入等待条件。内存缓存随重启自然重建,磁盘会话、看板、图片等持久数据不会被清理。
474
+
475
+ ChatCCC 的普通内部重启使用跨平台父子进程握手:替代进程完成启动预检后通知父进程退出,再等待旧监听端口实际释放并接管 PID;替代进程未就绪或握手超时时,父进程会保留并继续服务。自更新则先把仅依赖 Node.js 的更新器复制到 `~/.chatccc/update/`,确认更新器就绪后退出旧进程,再由安装目录外的更新器执行 npm 安装并启动新版,从而避免 Windows 因运行中进程或原生模块占用全局包目录而报 `EBUSY`。更新失败时会尝试恢复并重启原版本,详细记录写入 `~/.chatccc/logs/update-watcher.log`。
476
+
477
+ Codex 和 Cursor 在 Linux/macOS 下使用独立进程组。停止时先显示“正在停止”,待进程组内后代退出后再显示“已停止”;仅外层 shell 退出不算清理完成。重复停止请求合并处理,清理失败会保留会话进程占用保护并报告“Agent 停止未完成”,后续请求必须先完成清理才能启动新 Agent。Windows 继续使用 `taskkill /T /F`,命令失败或超时不会当作成功。
478
+
479
+ 飞书接收长连接启用 15 秒握手超时和 30 秒心跳应答超时;首次启动最多等待 45 秒真实连接确认后才提示就绪。运行期间连接持续异常 90 秒时,会关闭并重新建立接收连接,保留会话、消息去重和正在执行的任务。没有用户消息不会触发重连。连接状态与恢复记录写入运行日志和 `startup-trace.log`(`FEISHU-CONNECTION` / `feishu-connection`)。卡片更新遇到网络失败或序号冲突时不会当成送达成功,错误通知保留文本兜底;TLS 断线会明确显示为网络连接失败,已中断的 Agent 任务不会因此自动重放。
480
+
481
+ > **模型切换**:`/model` 查看当前会话 Agent 的可选模型清单,`/model <名称>` 模糊匹配切换,`/model clear` 恢复默认。可选模型来自当前 Agent 的配置:Claude 使用 `claude.model` / `claude.subagentModel`;Cursor、Codex、CCC Agent 和 DSH 使用各自的 `model` / `alternativeModel`。
482
+
483
+ Agent 的初始化、输入回显与重连通知不代表任务成功。Cursor、Codex 和 Claude 缺少成功完成事件,或任一 Agent 没有产生有效回复时,会明确提示异常;已生成的部分回复会保留并标为可能不完整。Cursor 重连过程显示在状态区,上游的 `resource_exhausted` / `unavailable` 分别提示请求受限 / 服务暂不可用,不推断为余额耗尽。执行失败不会自动重放整条任务。
484
+
485
+ > **Codex Fast 模式**:Web UI 中的“Fast 模式”设置新 Codex 会话的全局默认值,默认关闭。进入 Codex 会话后,`/fast` 查询当前状态,`/fast on` 和 `/fast off` 只覆盖当前会话并从下一条消息生效。ChatCCC 会显式向 Codex CLI 传入 `service_tier="fast"` 或 `service_tier="default"`,因此关闭时不会继承用户 `config.toml` 中可能开启的 Fast。
486
+
487
+ ---
488
+
487
489
  ## 联合发布
488
490
 
489
491
  ChatCCC 与独立 Deepccc 是两个 npm 包。联合发布须分别更新版本、检查构建产物并发布,合并 ChatCCC PR 不代表 ChatCCC npm 已更新。流程为私有 dev 开发测试并推送、私有 PR 合并、同步公开 dev、公开 PR 以 merge commit 合并、同步独立 Deepccc main、验证并发布两个 npm 包;内核无新增变化时复用已验证的同版本包,不重复发布同一版本。发布完成以 registry 中两个版本及产物摘要核同为准,本机安装和运行中进程版本分别核验。
490
492
 
491
493
  ## 技术栈
492
-
493
- TypeScript(发布前编译为 JavaScript,tsx 仅用于开发)/ Node.js >= 20 / AI SDK / Anthropic Claude Agent SDK(按需下载)/ DeepSeek Harness SDK + JSON-RPC Runtime(按需下载,要求 Node.js >= 22.19.0)/ Cursor Agent CLI / Codex CLI / 飞书 WebSocket API / CardKit / 微信 iLink
494
+
495
+ TypeScript(发布前编译为 JavaScript,tsx 仅用于开发)/ Node.js >= 20 / AI SDK / Anthropic Claude Agent SDK(按需下载)/ DeepSeek Harness SDK + JSON-RPC Runtime(按需下载,要求 Node.js >= 22.19.0)/ Cursor Agent CLI / Codex CLI / 飞书 WebSocket API / CardKit / 微信 iLink