chatccc 0.2.270 → 0.2.276

package/README.md

@@ -159,9 +159,11 @@ Agent Team 提供本地任务看板和项目主 Agent 入口。每个规范化
 
 打开项目后可以选择 CCC、Claude、Cursor 或 Codex 作为主 Agent。首次设置会创建固定命名为 `主Agent-<目录短名>` 的飞书群和空 Agent Session；后续切换 Agent 或重新关联目录会复用原群，运行中的主 Agent 不允许切换。建群成员取自机器人最近一次收到的飞书私聊；如果尚无私聊记录，网页会提示先给机器人发送任意私聊消息并自动检测。项目群名不会随第一句话或 `/forget` 改变。
 
-任务卡片可通过“交给主 Agent”启动真实执行：任务会从 Todo 移到 Doing，成功后自动移到 Done，失败则保留在 Doing 并显示错误，支持停止与重试。同一项目同一时间只运行一个看板任务；运行记录持久化在本地 JSON 中，服务异常退出后会把未完成执行标记为中断，避免错误显示为仍在运行。
+任务卡片可通过“交给主 Agent”启动真实执行：任务会从 Todo 移到 Doing，成功后自动移到 Done，失败、停止或中断则移到搁置并显示具体原因，支持安全重试。同一项目同一时间只运行一个看板任务；每次尝试都有独立的 Run ID、Trace ID、失败类型、耗时和完整执行时间线，可以在任务详情中切换历史尝试或复制记录。
+
+运行中的时间线和最后进度会定期持久化；长时间没有进度会在看板中标记为疑似停滞，停止请求超过截止时间会强制收敛到终态。服务异常退出后会保留最后已写入的执行过程并把未完成任务标记为中断；启动时还会自动对账任务终态与卡片列，修复“Agent 已完成但卡片移动失败”等部分成功。损坏的单条运行 JSON 会被隔离为 `.corrupt-*` 文件，不会阻断同项目其他历史记录。
 
-看板数据默认保存在 `~/.chatccc/agent-team/`，其中 `workspaces.json` 保存最近工作目录索引，`boards/` 保存按稳定 ID 分隔的看板 JSON，`main-agent-bindings/` 单独保存本机飞书群与 Session 绑定。目录移动或重命名后，可从最近目录列表重新关联。数据访问通过仓储接口隔离，后续接入飞书多维表格时可增加双向同步适配器，无需把本机群聊和 Session 状态混入任务同步模型。选择目录、创建群聊和启动 Agent 等操作都由本机 Node 后端执行；当前实现不依赖 Electron。
+看板数据默认保存在 `~/.chatccc/agent-team/`，其中 `workspaces.json` 保存最近工作目录索引，`boards/` 保存按稳定 ID 分隔的看板 JSON，`main-agent-bindings/` 单独保存本机飞书群与 Session 绑定，`task-runs/` 保存每次任务执行及其诊断时间线。目录移动或重命名后，可从最近目录列表重新关联。数据访问通过仓储接口隔离，后续接入飞书多维表格时可增加双向同步适配器，无需把本机群聊和 Session 状态混入任务同步模型。选择目录、创建群聊和启动 Agent 等操作都由本机 Node 后端执行；当前实现不依赖 Electron。
 
 #### 从源码运行
 
@@ -222,9 +224,11 @@ Claude Code、Cursor 和 Codex 需要对应的本地工具；CCC Agent 内置于
 
 #### CCC Agent
 
-CCC Agent 是 ChatCCC 内置的编程 Agent，不需要额外安装 CLI，开箱即用。在首次配置向导或 Web 管理页中启用后，填写 API Key、Base URL 和模型即可使用；它可以设为 `/new` 的默认 Agent，也可以通过 `/new ccc` 显式创建会话。
+CCC Agent 是 ChatCCC 内置的编程 Agent，不需要额外安装 CLI，开箱即用。在首次配置向导或 Web 管理页中启用后，填写 API Key、Base URL 和模型即可使用；它可以设为 `/new` 的默认 Agent，也可以通过 `/new ccc` 显式创建会话。
+
+DeepCCC 同时提供独立端口的本地 Web UI。ChatCCC 管理页顶部点击 **DeepCCC Web** 会复用或按需启动该服务；只全局安装 `deepccc` 的用户直接运行 `deepccc` 即可启动并打开网页版，终端模式改用 `deepccc-cli`。默认地址为 `http://127.0.0.1:28080/`，端口可通过 `~/.deepccc/config.json` 的 `web.port` 修改。网页版支持多会话并发、持久化历史、会话级 model/effort、API 设置和会话内高风险操作审批。
 
-ChatCCC 会把 `ccc.DEEPSEEK_API_KEY`、`ccc.DEEPSEEK_BASE_URL`、模型和 effort 显式传给内置 Agent；API Key 为空时 CCC Agent 会自动保持禁用。DeepCCC 的传输层选项 `provider`（默认 `openai`）和 `streaming`（默认 `true`）可通过 `~/.deepccc/config.json` 或 `DEEPCCC_PROVIDER` / `DEEPCCC_STREAMING` 配置，无需额外安装独立 CLI。
+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。
 
 **协议 override：** 也可以在 ChatCCC 的配置（`config.json` 的 `ccc.provider`，或 Web 管理页的「CCC Agent → API 协议」）显式指定 `openai` / `anthropic` 覆盖内核配置；留空（默认）时跟随 `~/.deepccc/config.json` / `DEEPCCC_PROVIDER`。`streaming` 不做 override，始终由 DeepCCC 内核配置控制。
 
@@ -240,7 +244,7 @@ ChatCCC 会把 `ccc.DEEPSEEK_API_KEY`、`ccc.DEEPSEEK_BASE_URL`、模型和 effo
 | 通义千问 / 智谱 GLM / 豆包 / MiniMax | 各家 `…/v1` 端点 | 国内 OpenAI 兼容服务 |
 | Ollama / vLLM / LM Studio | `http://localhost:11434/v1` | 本地或自建推理服务 |
 
-更换服务只需把 `ccc.DEEPSEEK_BASE_URL` 改为对应端点、`ccc.DEEPSEEK_API_KEY` 改为对应 Key、`ccc.model` 改为目标模型名即可。`reasoning_effort` 等 DeepSeek 扩展字段对不认识的模型会自动忽略，不影响其他服务。余额查询仅对官方 DeepSeek 域名（`api.deepseek.com`）生效，指向其他端点时自动跳过，不影响对话。
+更换服务只需把 `ccc.DEEPSEEK_BASE_URL` 改为对应端点、`ccc.DEEPSEEK_API_KEY` 改为对应 Key、`ccc.model` 改为目标模型名即可。`effort` 留空时不会由 ChatCCC override DeepCCC；若两边都留空，则不发送 `reasoning_effort`。只有确认目标模型支持时才应显式填写，否则服务端可能返回参数错误。余额查询仅对官方 DeepSeek 域名（`api.deepseek.com`）生效，指向其他端点时自动跳过，不影响对话。
 
 `ccc.alternativeModel` 是单个备选模型，只会加入 `/model` 的人工切换列表，不会在请求失败时自动重试或切换，避免重复执行带副作用的工具调用。
 
@@ -383,7 +387,9 @@ Codex 的默认模型和推理强度可继续由 `~/.codex/config.toml` 管理
 | `cursor.alternativeModel` / `codex.alternativeModel` / `ccc.alternativeModel` / `dsh.alternativeModel` | 单个备选模型；加入 `/model` 人工切换列表，不会自动故障转移 |
 | `ccc.DEEPSEEK_API_KEY` / `ccc.DEEPSEEK_BASE_URL` | CCC Agent 的 API Key 和服务地址；**不限于 DeepSeek**——可填任意 OpenAI 兼容端点（OpenAI、Kimi、通义、智谱、Ollama 本地等） |
 | `ccc.model` | CCC Agent 默认模型 |
-| `ccc.subModel` | CCC Agent 子模型（选填）：用于内部轻量环节（压缩摘要生成、task 子代理任务）；留空跟随主模型 |
+| `ccc.subModel` | CCC Agent 子模型（选填）：用于内部轻量环节（压缩摘要生成、task 子代理任务）；留空跟随主模型 |
+| `ccc.effort` | CCC Agent 推理强度 override；留空跟随 DeepCCC 内核配置，内核也留空时使用模型服务端默认值 |
+| `ccc.maxOutputTokens` | CCC Agent 主对话最大输出 token override；正整数，`null`/留空时跟随 DeepCCC 内核配置，内核也未配置时使用模型服务端默认值 |
 | `ccc.compactionTimeoutMs` | CCC Agent 上下文压缩单轮超时（毫秒），默认 300000（5 分钟）；压缩超时会让整轮对话失败，建议保持默认或调大 |
 | `ccc.contextWindow` | CCC Agent 模型上下文窗口（token），默认 1048576（1M，DeepSeek V4 Pro/Flash 原生规格）；压缩阈值自动 = 窗口 × 80%；超过模型/服务端实际上限会被 API 拒绝，可在 Web UI 下拉选择或自定义（单位 k） |
 | `dsh.apiKey` / `dsh.baseUrl` | DeepSeek Harness 的 API Key 和官方 DeepSeek 服务地址 |
@@ -427,16 +433,16 @@ Codex 的默认模型和推理强度可继续由 `~/.codex/config.toml` 管理
 | `/plan <内容>` | 只读计划模式：仅允许读文件和 stop-stuck-loop 请求，不执行任何写操作 |
 | `/ask <内容>` | 只读问答模式：与 /plan 相同，仅允许读文件和 stop-stuck-loop 请求 |
 | `/restart` | 重启机器人进程 |
-| `/restart safe` | 停止接受新任务，等待现有会话、缓存消息和依赖安装完成后重启 |
+| `/restart safe` / `/restartsf` | 停止接受新任务，等待现有会话、缓存消息和依赖安装完成后重启 |
 | `/update` | 更新 npm 全局包并重启（仅限 `npm install -g chatccc` 安装的全局进程；同一飞书事件跨重启去重） |
-| `/update safe` | 停止接受新任务，排空现有工作后更新并重启 |
+| `/update safe` / `/updatesf` | 停止接受新任务，排空现有工作后更新并重启 |
 | `/safestatus` | 查看安全重启/更新的等待状态 |
 | `/cancelsf` | 取消尚未开始执行的安全重启/更新预约 |
 | `/deleteg` | 解散当前飞书会话群；Agent 会话记录保留 |
 
-`/update` 与 `/update safe` 会把飞书消息或按钮事件 ID 原子写入 `~/.chatccc/state/update-command-guard.json`。同一 ID 跨重启重投时会静默忽略；用户主动发送的新更新指令因事件 ID 不同，仍可执行。该保护不改变普通消息与重启指令的处理方式。
+`/update`、`/update safe` 与短别名 `/updatesf` 会把飞书消息或按钮事件 ID 原子写入 `~/.chatccc/state/update-command-guard.json`。同一 ID 跨重启重投时会静默忽略；用户主动发送的新更新指令因事件 ID 不同，仍可执行。该保护不改变普通消息与重启指令的处理方式。
 
-`/restart safe` 与 `/update safe` 会先建立全局准入门禁：指令到达前已经运行或进入单会话缓存队列的工作会继续完成，之后到达的新普通任务会被提示在维护完成后重发。维护任务持久化到 `~/.chatccc/state/safe-maintenance.json`，进程意外退出后可继续排空；依赖安装、会话收尾、自动恢复和 Agent Teams 执行也计入等待条件。内存缓存随重启自然重建，磁盘会话、看板、图片等持久数据不会被清理。
+`/restart safe`（短别名 `/restartsf`）与 `/update safe`（短别名 `/updatesf`）会先建立全局准入门禁：指令到达前已经运行或进入单会话缓存队列的工作会继续完成，之后到达的新普通任务会被提示在维护完成后重发。维护任务持久化到 `~/.chatccc/state/safe-maintenance.json`，进程意外退出后可继续排空；依赖安装、会话收尾、自动恢复和 Agent Teams 执行也计入等待条件。内存缓存随重启自然重建，磁盘会话、看板、图片等持久数据不会被清理。
 
 > **模型切换**：`/model` 查看当前会话 Agent 的可选模型清单，`/model <名称>` 模糊匹配切换，`/model clear` 恢复默认。可选模型来自当前 Agent 的配置：Claude 使用 `claude.model` / `claude.subagentModel`；Cursor、Codex、CCC Agent 和 DSH 使用各自的 `model` / `alternativeModel`。
 

package/config.sample.json

@@ -57,9 +57,10 @@
     "DEEPSEEK_BASE_URL": "https://api.deepseek.com/v1",
     "model": "deepseek-v4-pro",
     "subModel": "",
-    "alternativeModel": "",
-    "effort": "",
-    "provider": "",
+    "alternativeModel": "",
+    "effort": "",
+    "maxOutputTokens": null,
+    "provider": "",
     "gitCoAuthor": null,
     "compactionTimeoutMs": 300000,
     "contextWindow": 1048576

package/deepccc-agent/README.md

@@ -1,35 +1,71 @@
-# deepccc
-
-`deepccc` 是一个轻量级本地编程 Agent，针对 DeepSeek 使用体验做了优化，同时支持其他 OpenAI-compatible 模型接口。
-
-它提供交互式命令行、JSONL 流式输出、本地文件工具、命令执行、项目提示词自动注入和持久化上下文。
-
-## 当前状态
-
-代码已经开源在 GitHub：
-
-https://github.com/wzj998/deepccc-agent
-
-npm 包名规划为 `deepccc`。如果 npm 包已经发布，可以直接全局安装：
+# DeepCCC
+
+DeepCCC 是一个本地优先的开源 Coding Agent，同时提供浏览器多会话界面、终端 CLI 和适合自动化集成的 JSONL 流。它针对 DeepSeek 做了缓存和上下文优化，也支持任意 OpenAI-compatible 服务以及 Anthropic Messages 协议。
+
+- 项目主页：https://github.com/wzj998/deepccc-agent
+- npm 包：https://www.npmjs.com/package/deepccc
+- 运行要求：Node.js >= 20，以及一个兼容模型服务的 API Key
+
+## 安装与快速开始
+
+全局安装：
 
 ```bash
-npm install -g deepccc
-```
-
-如果还没有发布，可以从源码运行：
+npm install -g deepccc
+```
+
+配置 `~/.deepccc/config.json` 或 `DEEPCCC_*` 环境变量后，运行：
+
+```bash
+deepccc
+```
+
+浏览器会自动打开 `http://127.0.0.1:28080/`。终端模式使用：
+
+```bash
+deepccc-cli
+```
+
+从源码运行：
 
 ```bash
 git clone https://github.com/wzj998/deepccc-agent.git
 cd deepccc-agent
-npm install
-npm run build
-node bin/deepccc.mjs --help
-```
-
-运行要求：
-
-- Node.js >= 20
-- DeepSeek 或其他 OpenAI-compatible 模型服务的 API Key
+npm install
+npm run build
+npm run dev
+```
+
+## Web UI 预览
+
+以下画面来自 DeepCCC 对本项目真实开发需求的 Agent 调用。截图仅将用户名、组织名、
+内部域名和绝对路径替换为公开示例，任务内容、模型配置、Agent 回复和审批流程均来自
+实际运行结果。
+
+多会话可以并行处理不同任务，每个会话分别选择 model、subModel 和 effort。下图来自
+`deepccc-agent/` 工作目录中的真实提问“这个项目妙在哪？”：
+
+![DeepCCC Web UI 图片附件与真实 Agent 回复](docs/deepccc-web-ui.png)
+
+命中需要确认的命令时，审批卡会直接出现在当前会话时间线中，不打断到弹窗：
+
+![DeepCCC 会话内操作审批](docs/deepccc-inline-approval.png)
+
+单一 API 配置作为新会话默认值，模型与 effort 仍可在每个会话中单独覆盖：
+
+![DeepCCC API 与 Web 设置](docs/deepccc-api-settings.png)
+
+## 核心能力
+
+- Web-first：多会话、持久化历史、实时流式过程、停止和恢复
+- 工具时间线：ChatCCC 风格 emoji 摘要、参数/结果折叠、省略行展开和状态记忆
+- 会话配置：每个会话独立选择 model、subModel 和 effort
+- 图片附件：Web 支持选择、粘贴和拖拽 PNG/JPEG/WebP；Agent 可用 `present_file` 回传图片
+- 本地工具：代码搜索、文件读写、补丁、命令执行、Git、网页搜索和抓取
+- 权限审批：危险命令在会话时间线中暂停，支持拒绝、允许一次、会话允许和永久允许
+- 上下文管理：自动压缩、原始流日志和跨会话历史检索
+- 项目约定：自动加载 AGENTS.md、CLAUDE.md、系统提示和目录式 Skills
+- 自动化：`deepccc-cli --stream-json` 提供稳定 JSONL 事件接口
 
 ## 缓存命中率
 
@@ -46,8 +82,10 @@ deepccc 的本地缓存优化实测命中率 **96.7%**，有效降低重复请
 ```bash
 export DEEPCCC_API_KEY="sk-..."
 export DEEPCCC_BASE_URL="https://api.deepseek.com/v1"
-export DEEPCCC_MODEL="deepseek-v4-pro"
-export DEEPCCC_STREAMING="true"
+export DEEPCCC_MODEL="deepseek-v4-pro"
+export DEEPCCC_EFFORT="high"
+export DEEPCCC_MAX_OUTPUT_TOKENS="32768"
+export DEEPCCC_STREAMING="true"
 ```
 
 Windows PowerShell：
@@ -56,8 +94,10 @@ Windows PowerShell：
 $env:DEEPCCC_API_KEY="sk-..."
 $env:DEEPCCC_PROVIDER="openai"
 $env:DEEPCCC_BASE_URL="https://api.deepseek.com/v1"
-$env:DEEPCCC_MODEL="deepseek-v4-pro"
-$env:DEEPCCC_STREAMING="true"
+$env:DEEPCCC_MODEL="deepseek-v4-pro"
+$env:DEEPCCC_EFFORT="high"
+$env:DEEPCCC_MAX_OUTPUT_TOKENS="32768"
+$env:DEEPCCC_STREAMING="true"
 ```
 
 也兼容这些 DeepSeek 别名：
@@ -75,9 +115,10 @@ $env:DEEPCCC_STREAMING="true"
   "apiKey": "sk-...",
   "baseURL": "https://api.deepseek.com/v1",
   "model": "deepseek-v4-pro",
-  "subModel": "",
-  "effort": "",
-  "streaming": true,
+  "subModel": "",
+  "effort": "",
+  "maxOutputTokens": null,
+  "streaming": true,
   "contextWindow": 1048576,
   "git": {
     "coAuthor": {
@@ -86,14 +127,39 @@ $env:DEEPCCC_STREAMING="true"
       "email": "20184052+wzj998@users.noreply.github.com"
     }
   },
-  "rawStreamLogs": {
+  "rawStreamLogs": {
     "enabled": true,
     "maxBytesPerTurn": 1048576,
     "retentionDays": 7,
-    "keepCompleted": false
-  }
-}
-```
+    "keepCompleted": false
+  },
+  "web": {
+    "port": 28080,
+    "openOnStart": true
+  }
+}
+```
+
+## Web UI
+
+全局安装后可以直接启动本地网页版：
+
+```bash
+deepccc
+```
+
+默认只监听 `http://127.0.0.1:28080/`，不会暴露到局域网。可在
+`~/.deepccc/config.json` 的 `web.port` 修改端口，`web.openOnStart` 控制启动时是否自动打开浏览器；也可以临时使用 `deepccc --port 28081 --no-open`。默认启动会安全替换经过实例身份验证的旧 DeepCCC Web；传入 `--reuse-existing` 时复用已有实例。`deepccc web` 保留为兼容别名。
+
+从源码开发时，`npm run dev` 启动 Web Server 并打开页面（不启用 watch）；`npm run dev:cli` 启动终端模式。
+
+Web UI 支持新建、恢复、重命名和删除多会话，多个会话可以同时运行，即使它们指向同一个工作目录。每个会话可独立选择 model、subModel 和 effort，并持续复用 CLI 已保存的历史。注意：当前版本不自动创建 Git worktree；同目录的多个运行中 Agent 直接修改同一组文件，页面会提示覆盖与冲突风险。
+
+模型文本、reasoning 心跳和工具事件通过 SSE 实时更新。每轮消息按真实发生顺序持久化和回放，因此刷新后仍会保持“阶段说明 → 工具调用 → 后续结论”的交错时间线；旧版会话没有顺序数据时，会兼容显示为“工具调用 → 最终回答”。每次工具调用与对应结果合并成一张卡片，折叠态显示 emoji、工具名、状态和关键参数；展开后调用参数默认保留前 8/后 4 行，工具结果保留前 12/后 6 行，省略内容可继续展开。工具卡及省略行的展开状态保存在当前浏览器标签页的 `sessionStorage`，持续生成、切换会话和刷新页面均不会自动收起。消息正文支持标题、表格、列表、引用、链接和代码块等常用 Markdown。
+
+图片始终按本地附件处理，不转换为 Provider 原生多模态消息。Web 支持文件选择、剪贴板粘贴和拖拽，每条消息最多 10 张 PNG/JPEG/WebP、单张最大 20 MB；附件复制到 `~/.deepccc/attachments/<session-id>/`，Agent 收到本地绝对路径后使用可用工具自行处理。Agent 可调用 `present_file` 把当前工作目录或会话附件目录中的图片直接展示在会话中；删除会话时对应附件一并清理。
+
+API 设置采用单一 Provider 配置，支持 OpenAI-compatible 与 Anthropic Messages。完整 API Key 只保存在本机 `~/.deepccc/config.json`，浏览器读取设置时仅返回掩码。危险命令会在会话中暂停并请求“拒绝、允许一次、本会话允许、永久允许”，浏览器断开或审批超时默认拒绝。
 
 `git.coAuthor.enabled` 默认开启。DeepCCC 通过 `run_command` 创建 Git 提交时会保留用户为
 主 Author，并追加 `Co-authored-by: DeepCCC <20184052+wzj998@users.noreply.github.com>`。
@@ -104,13 +170,19 @@ $env:DEEPCCC_STREAMING="true"
 `DEEPCCC_PROVIDER` 或命令行 `--provider` 覆盖：
 
 - `openai` 使用 OpenAI-compatible Chat Completions 协议，兼容 DeepSeek、OpenAI、LiteLLM、vLLM 等服务。
-- `anthropic` 使用 Anthropic Messages 协议。配置中的 `baseURL` **完全按填写值使用，不自动补 `/v1`**，请填写到完整版本化地址，例如 DeepSeek 官方 Anthropic 端点为 `https://api.deepseek.com/anthropic/v1`（官方 Anthropic SDK 使用的 `https://api.deepseek.com/anthropic` 基址会拼接为 `.../anthropic/v1/messages`）。`effort` 是 OpenAI/DeepSeek 扩展参数，在 Anthropic 模式下不会发送。
-
-`streaming` 控制主对话是否使用流式请求，默认 `true`；也可以通过
-`DEEPCCC_STREAMING=true|false` 覆盖。关闭后，终端会在整条模型响应完成后一次性显示结果。
-
-`contextWindow` 是模型上下文窗口（token），默认 `1048576`（1M，DeepSeek V4 Pro/Flash
-原生规格）；上下文压缩阈值自动 = `contextWindow × 0.8`（超出即把较早消息压缩为摘要）。
+- `anthropic` 使用 Anthropic Messages 协议。配置中的 `baseURL` **完全按填写值使用，不自动补 `/v1`**，请填写到完整版本化地址，例如 DeepSeek 官方 Anthropic 端点为 `https://api.deepseek.com/anthropic/v1`（官方 Anthropic SDK 使用的 `https://api.deepseek.com/anthropic` 基址会拼接为 `.../anthropic/v1/messages`）。`effort` 在 OpenAI-compatible 模式映射为 `reasoning_effort`，在 Anthropic 模式映射为 `output_config.effort`；目标服务不支持时应留空。
+
+`streaming` 控制主对话是否使用流式请求，默认 `true`；也可以通过
+`DEEPCCC_STREAMING=true|false` 覆盖。关闭后，终端会在整条模型响应完成后一次性显示结果。
+
+`maxOutputTokens` 限制主对话单次最大输出 token，默认不配置（`null`/缺失），此时不向
+Provider 发送 `max_tokens`，使用模型服务端默认值。可通过 `DEEPCCC_MAX_OUTPUT_TOKENS`
+或命令行 `--max-output-tokens` 覆盖；只接受正整数。该限制会同时覆盖模型思考内容、
+工具参数和最终回答，设置过小可能导致工具调用或长回复被截断。
+
+`contextWindow` 是模型上下文窗口（token），默认 `1048576`（1M，DeepSeek V4 Pro/Flash
+原生规格）；常规上下文压缩阈值自动 = `contextWindow × 0.8`。工具输入与结果另有独立预算：
+默认取 `min(64000, 常规压缩阈值 × 25%)`，超过后会提前压缩，避免长会话积累大量低信号工具输出。
 可通过 `DEEPCCC_CONTEXT_WINDOW` 环境变量覆盖。⚠️ 超过模型/服务端实际上限时请求会被
 API 拒绝（context length exceeded），实际窗口以模型与所用服务端为准（如 litellm 的
 `max_input_tokens`）。
@@ -137,48 +209,62 @@ API 拒绝（context length exceeded），实际窗口以模型与所用服务
 在当前目录启动一个交互式 Agent：
 
 ```bash
-deepccc
+deepccc-cli
 ```
 
 指定其他模型或 OpenAI-compatible 接口：
 
 ```bash
-deepccc --base-url https://api.openai.com/v1 --api-key "$OPENAI_API_KEY" --model gpt-4.1
+deepccc-cli --base-url https://api.openai.com/v1 --api-key "$OPENAI_API_KEY" --model gpt-4.1
 ```
 
 使用 Anthropic Messages 协议（同样支持流式输出）：
 
 ```bash
-deepccc --provider anthropic --base-url https://api.example.com --api-key "$API_KEY" --model claude-sonnet-4-6
+deepccc-cli --provider anthropic --base-url https://api.example.com --api-key "$API_KEY" --model claude-sonnet-4-6
 ```
 
-指定工作目录：
+指定工作目录：
 
 ```bash
-deepccc --cwd /path/to/project
-```
+deepccc-cli --cwd /path/to/project
+```
+
+附加一张或多张本地图片（可重复传入 `--image`，仍采用本地附件路径，不发送原生多模态内容）：
+
+```bash
+deepccc-cli --image ./error.png --image ./expected.webp
+```
 
 恢复当前工作目录最近一次会话：
 
 ```bash
-deepccc --resume
+deepccc-cli --resume
 ```
 
 设置工具调用步数上限：
 
 ```bash
-deepccc --max-steps 20
+deepccc-cli --max-steps 20
 ```
 
-默认情况下，`deepccc` 不设置固定步数上限，会让模型自然完成工具循环。
+默认情况下，`deepccc-cli` 不设置固定步数上限，会让模型自然完成工具循环。
 
 设置推理强度（reasoning effort）：
 
 ```bash
-deepccc --effort high
+deepccc-cli --effort high
 ```
 
-可选值：`none` / `minimal` / `low` / `medium` / `high` / `xhigh` / `max`（留空则不传 `reasoning_effort` 请求字段）。
+可选值：`none` / `minimal` / `low` / `medium` / `high` / `xhigh` / `max`（留空则不传 `reasoning_effort` 请求字段）。
+
+限制主对话最大输出 token：
+
+```bash
+deepccc-cli --max-output-tokens 8192
+```
+
+不设置时使用 Provider 默认值。
 
 ## 权限机制
 
@@ -230,7 +316,7 @@ deepccc --effort high
 `--stream-json` 或程序化调用（无终端可交互）时，高危命令**安全默认拒绝**。需要全自动场景可显式传入：
 
 ```bash
-deepccc --dangerously-bypass-permissions
+deepccc-cli --dangerously-bypass-permissions
 ```
 
 该参数与 `ChatSession` 的 `permissionMode: "bypass"` 等价，也是 chatccc 集成 deepccc 时使用的模式（对齐 chatccc 调用 Claude Code / Codex 的 bypass 方式）。
@@ -239,12 +325,12 @@ deepccc --dangerously-bypass-permissions
 
 交互模式下，每轮回复渲染为固定"过程区块"：状态行（压缩上下文中/生成回复中/完成/已停止/异常结束）+ 折叠工具行 + 原地更新正文，不滚屏刷 JSON。活动状态有心跳点号动画；完成/停止/异常后区块定型留在屏幕上。
 
-持久化上下文达到 token 阈值时，deepccc 会先按 token 预算保留最近消息，再压缩较早内容；超长历史消息、工具记录和压缩输入会被限长，避免单次摘要请求反复吞入巨量文本。一次压缩最多等待 5 分钟，超时或摘要失败会给出明确错误，不会自动重放用户请求。
+持久化上下文达到常规 token 阈值或独立工具预算时，deepccc 会先按预算保留最近消息，再压缩较早内容；工具历史使用标准结构化 tool-call/tool-result 消息重放，不会把内部 `[工具记录]` 文本重复送回模型。若模型仍输出伪工具记录，系统会丢弃并重试一次；重复失败时安全终止，避免把未执行命令当成真实结果。超长历史消息、工具记录和压缩输入会被限长，一次压缩最多等待 5 分钟。
 
 如果终端渲染出现异常，可以强制回退为纯文本流式输出：
 
 ```bash
-deepccc --plain
+deepccc-cli --plain
 ```
 
 ## JSONL 流式输出
@@ -252,13 +338,13 @@ deepccc --plain
 JSONL 模式适合脚本、服务端集成或其他上层系统调用：
 
 ```bash
-deepccc --stream-json --prompt "检查这个仓库并总结测试命令"
+deepccc-cli --stream-json --prompt "检查这个仓库并总结测试命令"
 ```
 
 也可以从 stdin 传入提示词：
 
 ```bash
-echo "运行测试并解释失败原因" | deepccc --stream-json
+echo "运行测试并解释失败原因" | deepccc-cli --stream-json
 ```
 
 输出是逐行 JSON：

package/deepccc-agent/package.json

@@ -1,6 +1,6 @@
 {
   "name": "deepccc",
-  "version": "0.1.27",
+  "version": "0.2.10",
   "description": "A lightweight coding agent with OpenAI-compatible and Anthropic Messages API support.",
   "license": "Apache-2.0",
   "keywords": [
@@ -29,7 +29,8 @@
     }
   },
   "bin": {
-    "deepccc": "bin/deepccc.mjs"
+    "deepccc": "bin/deepccc.mjs",
+    "deepccc-cli": "bin/deepccc-cli.mjs"
   },
   "files": [
     "dist/",
@@ -41,6 +42,8 @@
     "LICENSE"
   ],
   "scripts": {
+    "dev": "tsx src/web-entry.ts",
+    "dev:cli": "tsx src/cli.ts",
     "build": "node node_modules/typescript/bin/tsc -p tsconfig.build.json",
     "prepack": "node node_modules/typescript/bin/tsc -p tsconfig.build.json",
     "test": "vitest run",

package/dist/deepccc-agent/src/attachments.js

@@ -0,0 +1,192 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, readFile, rename, rm, stat, unlink, writeFile } from "node:fs/promises";
+import { basename, join, resolve } from "node:path";
+import { DEEPCCC_HOME } from "./config.js";
+import { normalizeBuiltinSessionId } from "./context.js";
+export const MAX_ATTACHMENT_BYTES = 20 * 1024 * 1024;
+export const MAX_ATTACHMENTS_PER_MESSAGE = 10;
+export const ATTACHMENT_PROMPT_START = "<deepccc-attachments>";
+export const ATTACHMENT_PROMPT_END = "</deepccc-attachments>";
+export class AttachmentStore {
+    rootDir;
+    idFactory;
+    constructor(options = {}) {
+        this.rootDir = resolve(options.rootDir ?? join(DEEPCCC_HOME, "attachments"));
+        this.idFactory = options.idFactory ?? (() => randomUUID());
+    }
+    async save(sessionId, input) {
+        const bytes = Buffer.from(input.bytes);
+        if (!bytes.length)
+            throw new Error("Image attachment must not be empty");
+        if (bytes.length > MAX_ATTACHMENT_BYTES)
+            throw new Error("Image attachment exceeds the 20 MB limit");
+        const mimeType = detectImageMime(bytes);
+        if (!mimeType)
+            throw new Error("Only PNG, JPEG, or WebP image attachments are supported");
+        const normalizedSessionId = normalizeBuiltinSessionId(sessionId);
+        const attachmentId = normalizeAttachmentId(this.idFactory());
+        const extension = extensionForMime(mimeType);
+        const fileName = `${attachmentId}${extension}`;
+        const sessionDir = this.sessionDir(normalizedSessionId);
+        const absolutePath = join(sessionDir, fileName);
+        const meta = {
+            attachmentId,
+            originalName: cleanOriginalName(input.originalName, extension),
+            mimeType,
+            size: bytes.length,
+            absolutePath,
+            fileName,
+        };
+        await mkdir(sessionDir, { recursive: true });
+        const dataTemp = `${absolutePath}.${process.pid}.tmp`;
+        const metaPath = this.metaPath(normalizedSessionId, attachmentId);
+        const metaTemp = `${metaPath}.${process.pid}.tmp`;
+        await writeFile(dataTemp, bytes);
+        await rename(dataTemp, absolutePath);
+        await writeFile(metaTemp, `${JSON.stringify(meta, null, 2)}\n`, "utf8");
+        await rename(metaTemp, metaPath);
+        return publicMeta(meta);
+    }
+    async importFile(sessionId, path) {
+        const absolutePath = resolve(path);
+        const info = await stat(absolutePath).catch(() => null);
+        if (!info?.isFile())
+            throw new Error(`Image attachment not found: ${path}`);
+        if (info.size > MAX_ATTACHMENT_BYTES)
+            throw new Error(`Image attachment exceeds the 20 MB limit: ${path}`);
+        return this.save(sessionId, {
+            originalName: basename(absolutePath),
+            bytes: await readFile(absolutePath),
+        });
+    }
+    async get(sessionId, attachmentId) {
+        const stored = await this.readStored(sessionId, attachmentId);
+        return stored ? publicMeta(stored) : null;
+    }
+    async read(sessionId, attachmentId) {
+        const stored = await this.readStored(sessionId, attachmentId);
+        if (!stored)
+            return null;
+        try {
+            const bytes = await readFile(stored.absolutePath);
+            if (bytes.length !== stored.size || detectImageMime(bytes) !== stored.mimeType)
+                return null;
+            return { attachment: publicMeta(stored), bytes };
+        }
+        catch {
+            return null;
+        }
+    }
+    async delete(sessionId, attachmentId) {
+        const stored = await this.readStored(sessionId, attachmentId);
+        if (!stored)
+            return false;
+        await Promise.all([
+            unlink(stored.absolutePath).catch(() => { }),
+            unlink(this.metaPath(sessionId, attachmentId)).catch(() => { }),
+        ]);
+        return true;
+    }
+    async deleteSession(sessionId) {
+        await rm(this.sessionDir(sessionId), { recursive: true, force: true });
+    }
+    async readStored(sessionId, attachmentId) {
+        const normalizedId = normalizeAttachmentId(attachmentId);
+        try {
+            const value = JSON.parse(await readFile(this.metaPath(sessionId, normalizedId), "utf8"));
+            if (value.attachmentId !== normalizedId || typeof value.fileName !== "string")
+                return null;
+            if (typeof value.originalName !== "string" || typeof value.size !== "number")
+                return null;
+            if (value.mimeType !== "image/png" && value.mimeType !== "image/jpeg" && value.mimeType !== "image/webp")
+                return null;
+            if (value.fileName !== `${normalizedId}${extensionForMime(value.mimeType)}`)
+                return null;
+            const absolutePath = join(this.sessionDir(sessionId), value.fileName);
+            return { ...value, absolutePath };
+        }
+        catch {
+            return null;
+        }
+    }
+    sessionDir(sessionId) {
+        return join(this.rootDir, normalizeBuiltinSessionId(sessionId));
+    }
+    metaPath(sessionId, attachmentId) {
+        return join(this.sessionDir(sessionId), `${normalizeAttachmentId(attachmentId)}.json`);
+    }
+}
+export function buildAttachmentPrompt(text, attachments) {
+    const prompt = text.trim() || "请分析这些图片。";
+    if (!attachments.length)
+        return prompt;
+    const manifest = attachments.map((attachment) => ({
+        attachmentId: attachment.attachmentId,
+        originalName: attachment.originalName,
+        mimeType: attachment.mimeType,
+        size: attachment.size,
+        absolutePath: attachment.absolutePath,
+    }));
+    return [
+        prompt,
+        "",
+        ATTACHMENT_PROMPT_START,
+        JSON.stringify(manifest),
+        ATTACHMENT_PROMPT_END,
+        "以上图片以本地附件文件提供。不要假设模型原生支持图片；请使用可用工具读取这些绝对路径并自行处理。",
+    ].join("\n");
+}
+export function parseAttachmentPrompt(content) {
+    const start = content.indexOf(ATTACHMENT_PROMPT_START);
+    const end = content.indexOf(ATTACHMENT_PROMPT_END, start + ATTACHMENT_PROMPT_START.length);
+    if (start < 0 || end < 0)
+        return { text: content, attachments: [] };
+    const raw = content.slice(start + ATTACHMENT_PROMPT_START.length, end).trim();
+    let attachments = [];
+    try {
+        const parsed = JSON.parse(raw);
+        if (Array.isArray(parsed))
+            attachments = parsed.filter(isAttachmentMeta);
+    }
+    catch {
+        return { text: content, attachments: [] };
+    }
+    return { text: content.slice(0, start).trimEnd(), attachments };
+}
+export function detectImageMime(bytes) {
+    const buffer = Buffer.from(bytes);
+    if (buffer.length >= 8 && buffer.subarray(0, 8).equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10])))
+        return "image/png";
+    if (buffer.length >= 3 && buffer[0] === 0xff && buffer[1] === 0xd8 && buffer[2] === 0xff)
+        return "image/jpeg";
+    if (buffer.length >= 12 && buffer.subarray(0, 4).toString("ascii") === "RIFF" && buffer.subarray(8, 12).toString("ascii") === "WEBP")
+        return "image/webp";
+    return null;
+}
+function extensionForMime(mimeType) {
+    return mimeType === "image/png" ? ".png" : mimeType === "image/jpeg" ? ".jpg" : ".webp";
+}
+function cleanOriginalName(value, extension) {
+    const cleaned = basename(value || `image${extension}`).replace(/[\u0000-\u001f<>:"/\\|?*]+/g, "_").slice(0, 180);
+    return cleaned || `image${extension}`;
+}
+function normalizeAttachmentId(value) {
+    const normalized = value.replace(/[^a-zA-Z0-9_.-]+/g, "_").replace(/^_+|_+$/g, "");
+    if (!normalized || normalized === "." || normalized === "..")
+        throw new Error("Invalid attachment id");
+    return normalized;
+}
+function publicMeta(value) {
+    const { fileName: _, ...meta } = value;
+    return meta;
+}
+function isAttachmentMeta(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const attachment = value;
+    return typeof attachment.attachmentId === "string"
+        && typeof attachment.originalName === "string"
+        && typeof attachment.absolutePath === "string"
+        && typeof attachment.size === "number"
+        && (attachment.mimeType === "image/png" || attachment.mimeType === "image/jpeg" || attachment.mimeType === "image/webp");
+}