codebee 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 scwuxinping
+
+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,392 @@
+# <img src="app/ui/icons/logo-horizontal.png" width="96" align="top" alt="CodeBee"> CodeBee · 多智能体编排台
+
+> All agents, one hive. —— 一声令下，群蜂齐作。
+> *CodeBee*，码蜂：蜂后统筹（编排者）、侦察蜂定方向（规划/评审）、工蜂采蜜（实现）——
+> 一个蜂巢，多只蜜蜂，酿同一份蜜。
+
+**AI 是引擎，你的经验是方向盘。** CodeBee 为你指挥一支跨厂商的执笔/编码小队：
+统一调度本机已装的 AI 编码 CLI（Codex CLI、[CC]、QwenCode、OpenCode、Aider……），
+提供 **目标 → 自动拆解 → 智能路由 → 执行 → 客观验证 → 跨厂商评审 → 自动修复/换将 → 汇总报告**
+的完整闭环。你不在时它们自动推进、自我打磨；需要你拍板的地方——质量闸门、
+任务分支的采纳与丢弃——它们会亮起「待裁决」等你，绝不静默替你决定。
+
+- **跨厂商对抗式评审**：评审者强制来自与作者不同的模型族——同族自评有同款盲区，
+  换一双"眼睛"才挑得出陈词滥调（无跨厂商可用时如实备注，绝不伪装）。
+- **产物隔离在任务分支**：指定代码版本的任务，产物提交在 `tutti/<task-id>` 分支上，
+  你的工作区始终干净；UI 或 `tools/bee.py` 里过目变更，一键「合并回原分支」或「丢弃」。
+- **多任务并发互不打扰**（1-6 可配）、**六种内置任务类型 + 自定义流程**；
+  「编排设置」可指定任意厂商的 API 模型作为**编排者**；CLI 可绑定**跨厂商模型链**。
+- 附带智能体管理台（检测 / 安装 / 升级 / 模型配置 / 编排开关，安装失败时 AI 自动诊断修复）。
+
+零第三方依赖：纯 Python 标准库（3.8+），本地 Web 界面，数据全部落盘可回放。
+
+## 作者侧命令行（可选）
+
+不开浏览器也能过裁决队列（本机免令牌）：
+
+```bat
+python toolsee.py status            :: 任务总览（含待裁决标记）
+python toolsee.py pending           :: 待裁决队列（分支 / 变更文件）
+python toolsee.py diff    <task>    :: 看本次变更
+python toolsee.py approve <task>    :: 采纳——任务分支合并回原分支
+python toolsee.py discard <task>    :: 否决——删除任务分支（需输 yes）
+```
+
+## 快速开始
+
+```bat
+start.bat
+:: 或
+python app\main.py --port 8765
+```
+
+自动打开 `http://127.0.0.1:8765`。首次运行会在 `data/` 下生成默认目录。
+
+## 手机 / 远程访问
+
+服务默认监听 `0.0.0.0`，启动时控制台会打印所有可用地址：
+
+```
+[CodeBee] 本机      http://127.0.0.1:8765
+[CodeBee] 局域网    http://192.168.x.x:8765/?token=xxxxxxxx   ← 手机同一 WiFi 直接打开
+[CodeBee] Tailscale http://100.x.x.x:8765/?token=xxxxxxxx     ← 外网随时随地访问
+```
+
+- **令牌**：远程访问受访问令牌保护（首次启动生成，存于 `data/remote.json`；本机 127.0.0.1 免令牌）。
+  手机打开上面带 `?token=` 的地址后自动记住，之后可直接输裸地址。令牌错误会弹出输入门，重新输入即可。
+- **多端同步**：所有设备看到同一份实时状态（SSE 推送，秒级），断线自动降级为轮询。
+- **控制权**：同一时刻只有一台设备能操作。空闲时执行任意操作会自动接管；其他设备变为只读，
+  顶栏胶囊显示「🔒 xx 控制中」，点一下可抢回。45 秒无操作自动释放，单设备使用完全无感。
+- **随时随地访问**：手机与电脑都安装 [Tailscale](https://tailscale.com) 并登录同一账号，
+  重启 CodeBee 后控制台会打印 Tailscale 地址，无需端口映射，流量端到端加密。
+- 只想本机使用：`python app\main.py --host 127.0.0.1`。
+
+### 公网访问（自己的域名 + Cloudflare Tunnel）
+
+有一台电脑常开时，可把 CodeBee 暴露到公网（示例域名换成自己的）：
+
+```bat
+:: 一次性配置：cloudflared 登录后创建隧道并绑定子域名
+cloudflared tunnel login
+cloudflared tunnel create tutti
+cloudflared tunnel route dns --overwrite-dns <隧道UUID> tutti.你的域名.com
+
+:: 之后日常启动（服务 + 隧道一键起）：
+start-public.bat
+```
+
+- **`--trusted-proxy` 必须开启**：隧道都从本机（127.0.0.1）回源，不感知代理的话
+  公网请求会被当成"本机"而豁免令牌，等于把控制台裸奔到公网。开启后带转发头
+  （Cloudflare 强制注入 `CF-Connecting-IP`）的回源请求一律强制校验令牌，
+  真本机（不带转发头的 loopback）不受影响。
+- `--public-url` 让「手机连接」弹框的二维码直接给公网地址，出门扫码即用。
+- 公网暴露面 = 8 位访问令牌。想更强可叠加 [Cloudflare Access](https://developers.cloudflare.com/cloudflare-one/policies/access/)
+  （零信任，给子域名再加一层邮箱验证码/SSO，免费档 50 用户）。
+- Cloudflare 免费版即可，无需公网 IP、无需备案（走 CF 海外边缘节点）、不开任何入站端口。
+
+### 公网访问（零配置临时隧道）
+
+装了 [cloudflared](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/)
+（`winget install Cloudflare.cloudflared`）后，**默认启动即自动建立 Cloudflare 临时隧道**：
+控制台打印一个随机的 `https://xxx.trycloudflare.com` 公网地址，出门扫码即用，
+不需要账号、域名和任何配置。每次重启地址会变（手机重新扫码即可）。
+
+- 已有 Cloudflare 隧道凭据的机器（`~/.cloudflared` 下有 `*.json`）不会自动起临时隧道
+  （此类机器上临时隧道不可用），请走上面的固定域名路径。
+- 局限：临时隧道不保证可用性与速度（官方定位测试用途），部分网络环境可能打不开；
+  要稳定请用固定域名。`--no-public-tunnel` 可彻底关闭该行为。
+- 打开即自动强制 `--trusted-proxy`：公网暴露 ⇆ 反代回源令牌校验，二者永不分离。
+
+## 极简输入 + 会话延续
+
+主表单只有 3 项：**类型、目标（一句话）、工作目录**（自动记住上次填写）。
+标题自动取目标首行；其余（上下文/验证命令/编排模式/实现者/评审组/轮数/阈值）全部收进"高级选项"折叠，默认全智能无需改动。
+
+**在已有会话上继续**：「继续会话」下拉列出本机**已安装且支持会话恢复**的 CLI
+（Codex CLI、[CC]、OpenCode、QwenCode、MiMo Code 等），选中后 CodeBee 扫描其本地会话
+（时间 / 项目 / 内容预览），挑一条即可延续那个会话的完整上下文——实现者自动指定为
+对应智能体，规划、实现、修复都在原会话上进行（评审仍用新鲜上下文避免偏见）。
+
+各家会话存放位置与恢复方式（2026-09 本机实测）：
+
+| CLI | 会话位置 | 恢复方式 |
+| --- | --- | --- |
+| Codex CLI | `~/.codex/sessions/**.jsonl` | `codex exec resume <sid>` |
+| [CC] | `~/.claude/projects/*/<sid>.jsonl` | `claude -p --resume <sid>` |
+| OpenCode | `~/.local/share/opencode/opencode.db`（SQLite） | `opencode run -s <sid>` |
+| QwenCode | `~/.qwen/projects/*/chats/<sid>.jsonl` | `qwen -r <sid>` |
+| MiMo Code | `~/.local/share/mimocode/mimocode.db`（SQLite） | `mimo run -s <sid>` |
+
+两点注意：续会话是**显式指定**，不要求该 CLI 在设置页开启「参与编排」；
+另外 OpenCode / QwenCode 按**当前目录**定位会话，所以续接时 CodeBee 会自动把 CLI
+启动目录切到该会话所属项目（表单里会提示具体路径），任务工作目录仍按你填的来。
+其他 generic 类 CLI 只要在 catalog 的 `orch.resume_argv_template` 里登记恢复参数
+（如 `["run", "-s", "{session}"]`）即可接入。
+
+## 任务类型与自定义流程
+
+主表单的「类型」下拉即流程列表，点「管理」可新增/编辑自定义流程（引擎、评审维度、
+阈值、轮数、产出文件名、起草/评审提示词覆盖）。内置七种：
+
+| 类型 | 引擎 | 流程 |
+|---|---|---|
+| 💻 代码 | code | 实现 → 验证 → 跨厂商评审 → 自动修复/换将 |
+| 📖 小说 | review | 起草 → 多维评审（情节/人物/文笔/节奏/吸引力）→ 修订 → 发布门禁 |
+| 📚 连载小说 | review | 大纲 → 逐章起草/评审/修订 → 全局一致性评审 → 合并成书（可断点续跑/继续连载） |
+| 📝 文档 | review | 起草 → 多维评审（准确性/结构/表达/实用）→ 修订 → 门禁 |
+| 🌐 翻译 | review | 起草 → 多维评审（忠实度/流畅度/术语/风格）→ 修订 → 门禁 |
+| 🔍 调研报告 | review | 起草 → 多维评审（全面性/深度/论据/结论）→ 修订 → 门禁 |
+| 🎤 演讲稿 | review | 起草 → 多维评审（主题/结构/感染力/语言）→ 修订 → 门禁 |
+
+两种引擎：
+- **code 引擎**：实现者在工作目录直接改代码 → 执行验证命令（确定性结果）→ 跨厂商评审
+  （结构化 JSON）→ 不通过则自动修复循环（至多 2 轮）→ 仍失败自动换将全量重实现；
+- **review 引擎**：作者起草产出文件 → 多个评审智能体按维度独立打分 + 提问题 →
+  任一维度低于阈值则汇总 major 意见回炉修订 → 所有维度达标才标记"达到发布标准"。
+
+自定义流程的参数在创建任务时固化到任务上，之后修改流程定义不影响已建任务。
+
+### 连载小说与继续连载
+
+「连载小说」按批次写作：大纲 → 逐章起草/每章评审修订 → 全局一致性评审 → 合并成书。
+写完一批想接着写下一批（比如先写了前 10 章，现在续写 11–20 章）：
+
+- **侧栏任务右键 → 「继续连载（新任务）」**，或打开任务/运行详情点「继续连载」按钮；
+- 弹框填续写章数（默认与上一批相同）→ 自动**新建一个任务**开跑。
+
+续写任务沿用原任务的目标/上下文/工作目录/评审设置，从已写到的新一章接着写：
+旧章一字不动，章节文件（`chapter-NN.md`）与成书合并（`manuscript.md`）都按
+全书章号衔接；续写大纲会自动注入前情大纲与最新一章结尾作衔接锚点，保证跨批
+剧情连贯；新任务标题自动带「·续 / ·续2」代数。若上一批没写完（超时/中断），
+先用「↻ 重试任务」断点续跑补完本批（继承大纲与已完成章），再「继续连载」写
+下一批。「继续连载」只出现在连载任务上（带章节衔接语义）。
+
+### 基于此任务新建（所有任务通用）
+
+任何任务（小说/文档/翻译/调研/演讲/代码/连载）右键 → 「基于此任务新建」，
+或任务/运行详情页点「基于此任务新建」：把该任务的类型/标题/目标/上下文/工作目录/
+编排与评审设置**预填进新建表单**，确认或修改后提交——适合「用同款配置开一篇新的」
+（换个题材再写一本、同目录跑下一份文档等）。它不做章节衔接：连载任务要接着
+上一批往下写，请用上面的「继续连载」。注意沿用同一工作目录时，新任务的成书
+文件（及连载的章节文件）会覆盖原产出，表单里会给出提醒。
+
+## 多任务并发
+
+任务队列是可并发 worker 池（默认 3，设置页「编排设置」可调 1-6）：多个任务同时跑、
+互不打扰——每个任务独立线程，运行数据按 run 隔离，互不等待。并发数调小后多余线程
+在空闲检查点自行退出，调大即时补齐。串行模式（=1）也可用。
+
+## 用量统计
+
+「用量统计」设置页：所有真实 LLM 调用（编排各角色步骤、编排者直连 API、
+连通性冒烟与 AI 修复）都会记入 append-only 台账（`data/usage/usage-YYYYMM.jsonl`，
+按月分文件），mock 智能体与本地验证命令不计入。页面提供：
+
+- **KPI 总览**：总 tokens（输入/输出/缓存细分）、调用次数与成功率、累计费用（claude 报告值）、
+  单次均值、缓存命中率、活跃天数与累计调用时长，每张卡带语义图标；
+- **每日趋势**：输入/缓存/输出堆叠柱状图（纯 SVG，零依赖）；
+- **时间范围**：分段控件切换今天 / 近 7 天 / 近 30 天 / 全部，**默认「今天」**（最常关心当下消耗），
+  选择会记住，下次进入沿用；
+- **五个维度排行**：按工具（Codex CLI / [CC] / 编排者 API…）、按智能体、按模型、
+  按步骤角色（规划/实现/评审/修订…）、按任务类型，各带调用数、tokens、耗时、费用与成功率；
+- **最近调用明细**：时间、工具、智能体、模型、角色、成败、tokens 细分与单次费用。
+
+聚合接口：`GET /api/usage?days=N`（N=0 表示全部历史；按天序列自动补零可直接画图）。
+
+启动时会自动把**历史运行**里已记录的 token 与费用回填进台账（幂等，重复启动不重复计入），
+所以升级后第一次打开就能看到此前的用量，不会从零开始。历史运行只存了总量、没有输入/输出
+细分，因此这部分记录的细分显示为 0、模型列标注「(历史未记录)」，页面会给出说明；
+从新调用开始记录完整细分。
+
+## 皮肤 / 换肤
+
+设置页「皮肤」（顶栏右侧的调色盘胶囊也直接进这一页）内置 6 套皮肤，**默认「经典」就是原本的界面**，不换肤时观感与以前完全一致：
+
+| 皮肤 | 风格 |
+|---|---|
+| 经典 | 黑白灰 + 蓝色强调（默认，即原界面） |
+| 深海 | 藏青底色 + 天蓝强调 |
+| 森野 | 墨绿底色 + 青翠强调 |
+| 暖阳 | 暖棕底色 + 琥珀强调 |
+| 霓虹 | 暗紫底色 + 品红强调 |
+| 高对比 | 纯黑 / 纯白 + 硬边框、去阴影（弱视 / 强光环境） |
+
+每套皮肤都自带**日间与夜间两版**，所以顶栏原来的「夜间 / 日间」按钮继续可用，切明暗不会丢皮肤；
+皮肤页里也有同样的明暗分段控。点卡片即时生效，选择记在本机（`localStorage` 的 `orch.skin`，
+手机与电脑各自独立），首屏有预涂脚本，刷新不会闪一下默认配色。皮肤值缺失或非法时自动回落经典。
+
+实现上：一套皮肤=一份完整调色板，全部由 `app/ui/style.css` 顶部的同一组 CSS 变量描述
+（`html[data-skin="X"]` 与 `html[data-skin="X"][data-theme="light"]`），换肤只改变量，布局与组件样式不动；
+原先写死的几处强调色底纹（状态 chip、徽标、执行日志框等）已改成 `color-mix(var(--accent) …)`，
+所以新皮肤下不会出现串色。皮肤卡片上的配色预览由 JS 读 CSS 变量实时生成，不重复维护色值。
+
+**新增一套皮肤**：在 `style.css` 里照抄一组变量写 `html[data-skin="你的id"]` 与其
+`[data-theme="light"]` 版（两组都要写全同一组变量名），再在 `app/ui/app.js` 的 `SKINS`
+数组里加一行（id / 名字 / 一句描述）即可，其余（入口、预览、持久化、手机状态栏色）都自动生效。
+`node tests/ui_skin.mjs` 会校验「每个皮肤的日夜两版变量是否与经典完全对齐」，防止漏写变量。
+
+## 编排设置（编排者模型）
+
+「编排设置」设置页里可以给 **CodeBee 自己的智能体**指定一个厂商的模型
+（直连 API，不占 CLI 会话）：统一负责任务的**规划拆解、难度判定与写作大纲**。
+未启用或调用失败时自动回落为「最强可用 CLI 智能体」规划，流程永不阻塞。
+三种协议（anthropic / openai / google）都可作编排者；一键测试连通。
+
+## 两种智能体
+
+- **真实智能体**：来自 `data/catalog.json`，已安装且在管理页勾选"参与编排"的 CLI；
+- **mock 智能体**（演示智能体 A/B）：内置、零消耗，用于验证流程 / 演示 / 回归测试。
+
+mock 的评分逻辑是确定性的：第 1 轮故意略低于阈值、第 2 轮达标——用来验证发布门禁。
+mock 不出现在新建任务表单的「实现者/评审组」选择器里（手动编排不会误选）；仅当本机
+一个真实智能体都没有时才回退显示，自动路由与测试也仍会把它作为兜底。
+
+## 模型接入（API 供应商）
+
+"模型接入"页是**主从视图**：左侧选供应商，右侧看该供应商的模型。
+
+- **导入（多来源）**：点「导入」弹出扫描结果，列出本机所有受支持的 AI 工具及各自可导入
+  的供应商数量，勾选后可一次导入。支持 **CCSwitch（含 Claude Desktop / Codex / Gemini /
+  OpenClaw）、Claude Code、Codex CLI、ZCode、Qwen Code、Gemini CLI、OpenCode、Continue、
+  Cursor、Trae**——只读这些工具的配置，不改写它们本身；导入后**自动拉取各供应商的可用
+  模型列表**（后台并发，CCSwitch 的每百万 token 价格表一并带入）；按「来源 + 原始条目」
+  幂等，重复导入原地更新并保留你设置的模型、启停状态与已删除墓碑；
+- **手动添加**：点「＋」弹出表单（名称 / 协议 / API 地址 / 密钥 / 默认与难度模型），
+  保存后自动拉取模型列表；地址若误填成 `.../v1/chat/completions` 会自动收敛为基址；
+- **协议**：`anthropic` 与 `openai` 可注入 CLI；`google`（Gemini）**仅登记**——
+  可查看、可拉取模型列表，但不会出现在 CLI 绑定的下拉里；
+- **左侧供应商列表**：名称、协议、来源标签、已拉取的模型数；顶部「⟳ 全部刷新 / 导入 / ＋」；
+  每行左侧有勾选框（顶部「全选」），勾选后出现批量条：**启用 / 停用 / 删除**；
+- **停用供应商**：停用即「暂不参与编排」——运行时解析会跳过它，绑定回落为 CLI 默认
+  配置；地址/密钥/模型列表与已删除墓碑都保留，「全部刷新」也会跳过它，随时可再启用；
+- **右侧供应商详情**：
+  - **测试连接**：GET `/v1/models` 测供应商级连通性与延迟（显示
+    `✓ 连通 410ms · 16 个模型`）；
+  - **模型按协议分组**展示，每行 = 勾选框 + 优先级 #N + 模型名 + 价格 + **测试按钮**
+    （发一条 1-token 真实对话，显示 `✓ 850ms` 或 `✗ HTTP 402 欠费`）+
+    启停开关；
+  - **批量操作模型**：勾选任意多行（分组标题「全选」可整组选中）后，用上方批量条
+    **启用 / 停用 / 恢复 / 删除**所选模型；「已删除 N 个」展开后也能勾选并「恢复所选」；
+  - **拖动 ☰ 调整调用优先级**：组内拖拽即重排，#1 即默认模型；
+  - **删除模型**：每行「删除」把不用的模型移出优先级列表。删除是**标记隐藏而非
+    物理移除**——「获取模型列表 / 全部刷新 / 重新导入」都不会再把删掉的模型带回来；
+    分组底部「已删除 N 个 · 恢复全部」可找回（恢复后排在优先级末尾）。若删掉的正是
+    默认模型或难度映射，相关引用会同步清空，不会留下悬空的模型名；
+  - **批量的原子性**：所选里只要有一个模型名不存在、或对已删除的模型做启用/停用，
+    整个请求都不生效（不会改一半）；批量恢复与可见模型混选时，可见项直接跳过；
+  - 「编辑供应商配置」折叠区：改地址/密钥/难度模型映射；
+- **自动优先级**：新拉取的模型按名称启发式自动排序（pro/opus 强者靠前，
+  mini/flash 便宜者靠后），手动调序后刷新会保留你的顺序；
+- **运行时语义**：「CLI 绑定」页的**模型链可跨厂商混搭**——每条自带该供应商的
+  凭据注入（API key + 地址），第 1 条是主模型，其余按序降级：主模型瞬态失败
+  （503/限流/无可用通道）自动切到下一条，**可能是另一家厂商的模型**（最多 3 条）；
+  链空则按供应商默认 / 难度路由自动选；调用失败若是瞬态错误**自动降级**；
+- **CLI 绑定**：claude 走 `ANTHROPIC_*` 环境变量、codex 走 `-c model_provider`
+  覆盖，运行时注入不改写 CLI 全局配置；密钥只存本机 `data/models.json`；
+- **安全**：拉取与测试仅访问用户自己配置的 http/https 地址，解析 IP 做边界校验、
+  禁用重定向；内网自建网关（私网 IP）导入时自动放行 `allow_private`。
+
+## 智能编排（默认模式）
+
+任务表单默认"智能"模式：只填 **目标 + 工作目录**，其余由系统决定：
+
+1. **规划**：最强可用智能体把目标拆成 ≤4 个有序子任务（JSON 计划，失败退化为单步模板），计划在运行详情可见；
+2. **智能路由**：能力基线 × 历史胜率（过往 run 的 verdict 统计）打分选实现者；评审者强制跨厂商；每一步记录"为什么选它"；
+3. **自动修复**：验证或评审不通过 → 问题清单自动发回实现者修复 → 重验证 → 重评审（至多 2 轮）；
+4. **自动换将**：修复穷尽仍失败 → 自动切换到次优智能体全量重实现一次；
+5. **报告**：结论、评分、路由依据、修复轮数、问题清单。
+
+"手动"模式保留完整人工控制（指定实现者、评审组等），行为同 v1。
+
+## 智能体管理
+
+"智能体管理"页提供：
+
+- **检测**：已装 / 未装、版本号（CLI `--version` / UWP AppxManifest / PowerShell）；
+- **安装 / 升级 / 卸载**：执行 catalog 里配置的命令，日志**实时流式落盘**（边跑边看，
+  不再等进程结束才出字）；**安装失败时 AI 自动诊断**——
+  真实智能体读取失败日志 + 本机环境（node/npm/pnpm 有无）给出修正命令，
+  只有命中白名单（`npm install` / `winget install` / `pip install` 前缀）才自动执行，否则留待人工确认；
+  卸载命令由安装命令自动推导（npm → `npm uninstall -g`、winget → `winget uninstall`、
+  pip → `pip uninstall -y`），无需在 catalog 里再维护一份、不会与安装命令不同步；
+  特殊渠道可在条目里显式写 `uninstall` 字段覆盖。卸载不可逆，点按钮会先摊开真实命令二次确认；
+- **模型配置**：工具默认模型（写回各家配置文件，自动备份 `.bak`）；
+  CodeBee 编排运行时用哪个供应商 / 模型统一在「CLI 绑定」页配置
+  （`data/models.json` 的 `bindings`，含有序模型链与难度路由）；
+- **编排开关**：决定哪些 CLI 参与任务路由。
+
+Kimi Code / MiMo Code / Grok Build / Pi / DeepSeek Harness 的安装命令已内置（均取自各工具官方渠道）：
+Kimi Code 与 Pi 需要 Node ≥ 22.19，Grok Build 的官方可执行名是 `grok`（条目 id 仍为
+`grok-build`），MiMo Code 的无头调用是子命令 `mimo run "提示词"`（该 CLI 的 `-p` 是
+`--password`）。DeepSeek Harness 的可执行名是 `dsh`，无头调用走 `--profile headless`
+（细节见下表）。若某个条目的安装命令仍缺失，直接编辑 `data/catalog.json` 补上
+`install` 字段，保存后点"重新加载 catalog"即可；点"恢复默认 catalog"可回滚。
+
+## 接入原理（已在本机实测）
+
+| CLI | 无头调用 | 输出解析 |
+|---|---|---|
+| Codex CLI | `codex exec --skip-git-repo-check --json -s <sandbox>`（stdin 传提示词；.cmd 垫片经 `cmd /c`） | JSONL 事件流：`item.completed`=回答，`turn.completed`=token 用量 |
+| Claude Code | `claude -p --output-format json`（stdin 传提示词；自动注入 `CLAUDE_CODE_GIT_BASH_PATH` 与输出上限） | 单个 JSON：`result` / `total_cost_usd` / `usage` |
+| DeepSeek Harness | `dsh --profile headless "<任务>"`（任务**只能**走位置参数：headless 应用只认 `[task...]` 与 `--help`，不支持 stdin 与 `--model`；`.cmd` 垫片经 `cmd /c`） | stdout 即最终回答纯文本；退出码 0=完成 / 1=错误（推理流另走 stderr） |
+
+DeepSeek Harness 的三个特殊点（均已实测确认）：
+
+1. **模型不能靠 env/flag 指定**，只能由配置层决定。headless 应用只认 `[task...]` 与 `--help`，
+   `--model` 会被拒。所以 CodeBee 把模型写进 `~/.dsh/settings.yaml` 的
+   `agent-default-model.model`（该文件若不存在则由 CodeBee 按需创建）；
+2. **凭据走 env**：由「CLI 绑定」注入 `DEEPSEEK_API_KEY`，这是 dsh 凭据解析的最高优先级
+   （高于它自己的 `.credentials.yaml`），不会落盘；
+3. **端点优先级是「settings 高于 env」**：`~/.dsh/settings.yaml` 里若写了
+   `llm-deepseek.baseURL`，CodeBee 注入的 `DEEPSEEK_BASE_URL` 会被忽略；只有没写时才生效
+   （实测：settings 固定 `vsllm.cc` 时，把 env 指到一个不存在的域名，请求仍然打到 `vsllm.cc`）。
+
+由此带来一个必须注意的约束：绑定的供应商要和 dsh 实际使用的端点**配成一对**。若 dsh 的
+settings.yaml 已经把端点钉在别处，而你在「CLI 绑定」里绑了另一家网关的供应商，那个密钥会被
+发到你钉住的端点上，表现为鉴权失败。此时要么让两边端点一致，要么不绑供应商、让 dsh 用它自己的
+凭据。另外绑定只会选中 **openai 协议**的供应商（dsh 的适配器打的是 OpenAI 兼容的
+`/chat/completions`），anthropic 协议的网关会被跳过。headless 是「一次性任务」，不支持会话
+恢复，也不会出现在「继续会话」下拉里；超长提示词还受 Windows 命令行上限（约 32k 字符）约束
+——这也是所有 generic 类 CLI 的共有约束。
+
+所有子进程：并发读管道防死锁、超时/取消杀整棵进程树（`taskkill /T`）、stdout 全量落盘。
+
+## 目录约定
+
+```
+data/
+  catalog.json          智能体目录（可手动编辑）
+  orchestration.json    编排偏好（参与编排开关）
+  models.json           供应商 / CLI 绑定（跨厂商模型链）/ 编排者配置
+  flows.json            自定义任务流程
+  settings.json         运行设置（最大并发数）
+  tasks/*.json          任务
+  runs/<run_id>/        每次运行：run.json、steps/*.log、report.md、error.log
+  usage/                用量台账（usage-YYYYMM.jsonl，按月分文件，append-only）
+```
+
+安全约束（内置，勿绕过）：配置路径必须位于用户主目录内；任务工作目录必须是已存在的
+绝对路径；稿件文件名消毒后限制在工作目录内；步骤日志读取禁止目录穿越。
+
+## 测试
+
+```bat
+cd tests && python -m unittest test_units test_pipeline test_flows test_binding_models test_binding_chain test_modelhub test_catalog_models test_orchestrator test_remote test_sessions test_auto test_usage -v
+python tests\e2e_service.py   :: 起真实服务的端到端（临时数据目录 + 独立端口，零配额）
+python tests\e2e_usage.py     :: 用量统计端到端（预置台账 → 聚合断言 → mock 不入账）
+node tests\ui_check.mjs      :: Edge headless + CDP 的 UI 交互验证（需本机服务在 18798）
+node tests\ui_check_usage.mjs :: 用量页 UI 验证（自起临时服务 + 种子数据 + 截图）
+node tests\ui_check_usage_icons.mjs :: 用量页图标/分段控件（SVG 图标、默认今天、选中态、主题跟随）
+node tests\ui_check_models_icons.mjs :: 模型页图标（刷新按钮加载态、拖拽手柄，对运行中服务只读）
+node tests\ui_probe_geometry.mjs :: 布局几何（重叠/裁切/越界/横向溢出，桌面 + 手机视口）
+node tests\ui_audit.mjs      :: 全页面体检（逐页可见性 + 空台账/有数据两套场景 + 控制台异常）
+node tests\ui_skin.mjs       :: 皮肤核验（调色板变量对齐 + 换肤/持久化/窄屏，需 18798 服务）
+```
+
+单元测试（解析器/消毒/穿越防护/mock 确定性/流程注册表/跨厂商链/编排者/并发池）+
+端到端（mock 全流程、门禁逻辑、验证失败拦截、服务级 API 全链路），全部不消耗真实配额。
+
+## 后续路线
+
+- v2：多智能体并行 + 投票/辩论；成本预算；历史胜率反哺路由；
+- git worktree 隔离支持并行写同一仓库（并发任务已就绪，worktree 隔离待做）。