git:20260913.68ea954 to git:20260913.4dd0b6f

- ClawBench 是面向手机 / 平板 / 桌面的多端 AI 工作台，移动端交互适配优先、桌面端完整支持，将 AI CLI 工具（CodeBuddy、Claude Code、OpenCode、Codex、Qoder CLI、VeCLI、CodeWhale、MiMo-Code、Pi、Copilot、Kimi）封装为 Web 平台。Go 后端调用 CLI 工具，通过 WebSocket 流式传输 JSON 事件；Vue 3 前端实时渲染。支持 ACP (Agent Client Protocol) stdio 传输（含桥接适配器）、SSH 隧道端口转发、定时任务系统。

- 规格文档：`docs/spec/`

- ./build.sh # 完整构建（Go 二进制 + Vue 前端 + Excalidraw 独立构建）

- ./build.sh --windows # 交叉编译：Windows amd64

- ./build.sh --linux # 交叉编译：Linux amd64

- ./build.sh --linux-arm64 # 交叉编译：Linux arm64

- ./build.sh --darwin # 交叉编译：macOS arm64

-

- ./dev-server.sh # 开发模式（Vite HMR 代理到后端）

- ./dev-server.sh --fg # 前台运行

- ./dev-server.sh --stop # 停止

- ./dev-server.sh --restart # 重启

-

- ./clawbench # 直接运行（前台，默认端口 20000）

- ./clawbench --port 8080 # 指定端口

- ./clawbench --data-dir /data/.clawbench # 自定义数据目录

- go build -o clawbench ./cmd/server # 仅构建 Go 二进制

- go test ./... # 所有 Go 测试

- go test ./internal/ai/... # 指定包测试

- npm test # Vitest 前端测试

- ./scripts/pre-push-checks.sh # 推送前全量检查（lint + test + build + typecheck + 覆盖率）

- ./scripts/pre-push-checks.sh --skip-coverage # 跳过覆盖率门槛

- ./scripts/pre-push-checks.sh --skip-android # 跳过 Android 覆盖率

- ./build.sh --restart # 编译 + 后台重启 ClawBench（可在 Web 终端内执行）

- ./build.sh --restart-skip-build # 跳过编译，仅重启

- ./build.sh --restart --restart-port=8080 # 重启并指定端口

- `./scripts/kill-zombies.sh` 清理僵尸（defunct）进程及其孤儿进程树。僵尸进程无法直接 kill，只能靠父进程 reap 或杀掉父进程后由 init 收养清理。

-

- ```bash

- ./scripts/kill-zombies.sh # dry-run：列出僵尸与将要杀的进程树

- ./scripts/kill-zombies.sh --kill # 实际清理（带确认）

- ./scripts/kill-zombies.sh --kill --force # 跳过确认

- ./scripts/kill-zombies.sh --port 8080 # 额外保护 8080 端口的服务器

- ```

- - **开启设置**：设置 → 调试（Debug）→「调试日志捕获」（`logCapture`，默认关）。开启后：

- - **App 模式（Android）**：前端 JS 日志跳过 console 与 native 桥，仅 HTTP 上报一份（单份，无 `WebView:LOG` 重复与 `[object Object]` 失真）；

- - **网页模式**：console 照常输出 + HTTP 上报；

- - 关闭时日志只在本地可见（logcat / console），不发服务器。

- - **查看**：`tail -f {data-dir}/logs/client.log`、`grep '\[js\]' {data-dir}/logs/client.log`（例：`tail -f /opt/clawbench-green-data/logs/client.log`）。

- 入口：`cmd/server/main.go`

-

- 核心包：

- | `internal/handler/` | HTTP 端点，所有 `/api/` 路由经 `middleware.Auth` 鉴权，聊天通过 WebSocket 流式传输；含用量统计（`/api/usage/stats`）、主题壁纸（`/api/theme/local/*` 多图图库、`/api/theme/bing/*` 每日壁纸）等端点 |

- | `internal/wallpaper/` | 壁纸图片处理与磁盘布局：`Process`/`ProcessWithMaxEdge`（白名单校验/缩放/编码，PNG 保透明、JPEG 重编码、GIF/WebP/SVG 原样 + `SVGLooksSafe`；缩放上限按调用方指定——上传用 `MaxLongEdge`=2048，Bing 用 `BingMaxLongEdge`=3840 保留原生 4K，因为从 4K 缩到 2048 比直接编码更费 CPU/内存且更糊）、`FilePath`（裸名 + 扩展白名单 + symlink 安全 containment）、`ResolveActive`（mode/enabled/选中项 → 生效文件）、`BingMktForLocale`。handler 与 service worker 共用，避免 service→handler 反向依赖 |

- | `internal/service/` | 业务逻辑：聊天持久化、自动摘要、对话推荐、调度器、SQLite、Schema 迁移、Agent 存储、会话归档留存期自动清理（SessionCleanupWorker）、Bing 每日壁纸抓取（BingWallpaperWorker，常驻 + Trigger 立即同步，Trigger 可绕过启动延迟；抓取失败沿用上次缓存且**不剪枝**，剪枝保留集含配置仍引用的文件）、用量聚合（`usage_stats.go`：按维度 GROUP BY `chat_metadata`）、会话截断（Rewind/TruncateSessionAfterMessage + RAG 范围清理） |

- | `internal/ai/` + `backends/` | AI 后端抽象：`AIBackend` → `CLIBackend`（CLI+行解析）或 `ACPBackend`（JSON-RPC over stdio）。14 个后端子包通过 `ai.RegisterBackend()` 注册。CLI/ACP 均支持无进度看门狗（NoProgressTimeout/stallTimeout），防止进程挂起。CodeBuddy ACP 含 Plugin Skills 竞态修复（预扫描+延迟重发）与 `~/.codebuddy/skills/` 技能扫描（YAML frontmatter 解析 → 斜杠命令 + 系统提示词注入）。ACP 子智能体内容经 `_meta` 父工具调用 id 归属（`acp_parent_link.go`，CodeBuddy 扁平键 / Claude·Qoder 嵌套键），子块按父边界隔离（累加不跨父合并），随 `ParentToolCallID` 贯穿到前端分组渲染 |

- | `internal/speech/` | TTS：Edge TTS、Piper、Kokoro、MOSS-TTS-Nano |

- | `internal/stt/` | STT（语音输入）：vLLM Whisper，流式/非流式双端点 |

- | `internal/rag/` | RAG：SQLite + sqlite-vec 向量存储 + FTS5 全文检索，OpenAI 兼容嵌入 API；消息聚类分析（ClusterWorker：Union-Find + Sørensen-Dice） |

- | `internal/ws/` | WebSocket 事件通道，StreamHub 会话级扇出，Manager 广播+重连缓冲回放 |

- | `internal/ssh/` | SSH 隧道服务器 |

- | `internal/push/` | IM 机器人推送：`common/`（共享接口+会话命令）、`dingtalk/`（钉钉 Stream API）、`feishu/`（飞书 Lark SDK WebSocket+互动卡片） |

- | `internal/proxy/` | HTTP 反向代理+端口转发 |

- | `internal/summarize/` | 文本摘要、对话推荐（next-step recommendation） |

- | `internal/system/` | 系统资源监控：CPU、内存、磁盘、网络实时采集与推送 |

- | `internal/cli/` | AI Agent 自助命令：task、rag、migrate |

- Composable 按域分组：Chat、Session、Terminal、File、Navigation/Gesture、Settings、Agent、Task、Infrastructure、System。新建 composable 须放 `web/src/composables/` 并以 `useXxx` 命名，测试用 `*.test.ts` 同目录或 `__tests__/`。数据统计（`useUsageStats` + `web/src/components/stats/`）与壁纸主题（`web/src/utils/themeBackground.ts` + `components/settings/WallpaperSetting.vue`）是相对独立的功能分组。

-

- 组件按域分组：Chat、File、Terminal、Git、Session/Agent、Task、Settings、Common。

- `web/vendor-build/excalidraw/` 是独立的 Excalidraw 编辑器构建（React），由 `build.sh` 单独构建到 `public/vendor/excalidraw/`，`.excalidraw` 文件通过 iframe 懒加载它，Vue 主包不包含 React 依赖。

- - **前端必须使用 appLog**：所有前端代码使用 `appLog.d/i/w/e()`（`@/utils/appLog`），禁止原始 `console.*`（测试文件除外）。Tag 约定：短 PascalCase 模块名。

- - **Android 必须使用 AppLog**：所有 Android 代码使用 `AppLog.d/i/w/e()`，禁止原始 `android.util.Log`（`AppLog.java` 本身和测试除外）。

- - **改动 HTTP 接口必须同步 OpenAPI 文档**：任何新增 / 删除 / 修改 `/api/` 端点（路径、方法、鉴权、query 参数、请求体字段、响应字段、状态码）时，必须同步更新 `docs/spec/api/openapi.yaml`。

-

- 该文档是**手工维护**的，不会自动生成，因此极易与实际实现脱节。历史教训：曾出现 `POST /api/ai/chat` 的 `prompt` 实际是 `message`、`PATCH /api/ai/session/update` 的 `mode` 实际是 `modeId`、RAG 四个端点的 `message_id` 实际是 `id`、`/api/file/watch/update` 实为 PUT 却写成 POST、文档承诺 `view=summary` 但后端根本不读等 40+ 处不一致。

-

- 硬性要求：

-

- - 字段名、参数名、方法**必须从 handler 代码里抄**（对照 `decodeJSON` 结构体的 JSON tag、`r.URL.Query().Get(...)`、`requireMethod(...)` / `switch r.Method`），**禁止凭路由名望文生义**；

- - 路径注册的唯一来源是 `internal/handler/handler.go` 的 `RegisterRoutes`；删除端点时须从文档移除，并留意通配路由（`/api/tasks/`、`/api/agents/`、`/api/file/` 等）的子路径分发；

- - 鉴权变化须同步 `security` 标注（默认 `cookieAuth`，免鉴权端点显式写 `security: []`）；

- - 改完必须自检：路由无遗漏无多余、YAML 合法、无重复 `operationId`、`$ref` 可解析。

-

- - **纯前端改动完成后必须自觉编译**：若本次改动只涉及前端（`web/src/`、`web/index.html` 等，未动 Go / Android），改完并跑通测试后**直接执行前端编译**，供用户立即在浏览器/App 中测试，无需用户再要求：

-

- ```bash

- cd web && npm run build # 或项目根目录：npm run build

- ```

-

- 产物输出到 `public/`，并同步到 Go embed 目录（服务端从 `internal/frontend/dist` 读取内嵌资源，不同步则运行中的服务看不到改动）：

- 注意：`internal/frontend/dist` 是 gitignore 的构建产物，只影响本地/部署运行，不进提交。

- - **覆盖率门槛**：每 PR/推送到 main 强制执行——包级覆盖率不低于基线、变更行覆盖率 ≥ 80%。

-