@huicai/cli 2026.814.0 → 2026.1019.0

package/README.md

@@ -7,7 +7,7 @@
 
 ## 直接运行
 
-纯 Node.js（ESM），需 Node ≥ 18（推荐 20+）。
+Node.js（ESM）：普通模式 ≥18，全屏工作台 ≥22。
 
 ```bash
 cd huicai-cli
@@ -16,7 +16,7 @@ npm link            # 安装全局 huicai 命令（或：node bin/huicai.js）
 ```
 
 核心链路**零第三方运行时依赖**（`--plain` 或未装 ink 时，只用 Node 内置模块即可跑）。
-富 TUI（`--tui`，默认在 TTY 下启用）需 `ink`+`react`（package.json 已声明）；缺失时自动回退到 readline REPL。
+TTY 默认全屏，退出恢复终端；`--plain` 普通模式。缺依赖时回退。见[操作指南](docs/terminal-workbench.md)。
 
 ## 配置
 
@@ -106,6 +106,66 @@ huicai -c -p "继续修" --yolo   # 非交互续接（CI）
 
 `/init` 让智能体实际调研项目后生成/完善 `HUICAI.md`（非静态模板）；`/status` 显示版本/模型/会话/MCP/权限规则。
 
+## 三层班子与预算化编排（P2-14，默认关闭）
+
+编排设施本来就有（子智能体、专家团、脚本化工作流、自动升配、兜底模型），缺的是**显式预算**：
+一个长任务会派多少次、问几次顾问、花超了怎么办——不可预期的直接后果是没人敢放手让它跑大任务。
+
+开启：`~/.huicai/config.json` 里 `"crewBudget": true`，或 `HUICAI_CREW_BUDGET=1`。
+
+```json
+{
+  "crewBudget": true,
+  "crewBudgetPlan": { "subtasks": 6, "dispatchesPerSubtask": 2, "advisories": 5 },
+  "advisorModel": "<更强的推理模型id>"
+}
+```
+
+### 三层角色，各自的纪律
+
+| 角色 | 是谁 | 纪律 |
+| --- | --- | --- |
+| **编排者** | 主线智能体 | 规划、派发、校验、综合。**绝不做工人级的活**（自己埋头串行啃），**绝不通过顾问去执行**（那是拿最贵的模型当工人使） |
+| **工人** | `dispatch_agent` / `dispatch_agents`（便宜模型，并行） | 无状态生成单元，扇出执行。交结论前必须**真验证**，验不了就如实说验不了 |
+| **顾问** | `ask_advisor`（最强模型，串行且稀少） | 只在**承诺边界**问：方案评审 / 成稿评审 / 工人结论矛盾且自己核不动 / 同一子任务连栽两次 / 发现跑偏出成功标准 / 方案要推翻重来 |
+
+顾问的价值在稀少。遇到难题就问，它就退化成第二个工人——所以「何时该问」是六条**可判定的规则**，
+写在工具描述里，而不是一句「不要滥用」。
+
+### 预算：管的是编排的形状，不是总消耗
+
+与既有的 `budgetTokens`（`/budget`，软提醒的 token 总量）是两件互补的事。这里的形状是
+**「子任务数 × 每个最多派 2 次 + 顾问 5 次」**。大任务动手前先调 `plan_budget` 立框，
+把子任务数与**成功标准**一起说出来——说不出自己要派几次，多半也没想清楚要干什么。
+`budget_status` 随时自查，`/cost` 一并展示。
+
+### 一条不可让步的纪律：超支不许静默
+
+额度用尽时工具**拒绝执行**，并返回一句给模型的指令：停下来告诉用户已完成什么、还剩什么、
+再给多少额度能做完，由用户决定。不是抛错（模型会重试），也不是放行加个警告（那就是静默超支本身）。
+批量派发按**路数**扣而非调用次数——否则一次派八路和派一路花一样的钱，预算立刻失效。
+剩余不足以覆盖整批时会派完剩下的并**如实说明只派了几路**：少做而不说是另一种静默。
+
+### 撞顶之后，只有你能放行
+
+额度用尽后模型**不能自己把额度调大**（再调 `plan_budget` 报个更大的数字会被拒）。
+不堵这个口子，「由用户决定」就是一句空话——模型自签自批，你永远不会被问到。
+它这时只剩一条路：停下来说明还需要多少。放额度是你的动作：
+
+```
+/crew              # 看当前进度（派发/顾问/成功标准/降级情况）
+/crew 6            # 再放 6 个子任务的派发额度
+/crew advisor 3    # 再放 3 次顾问额度
+```
+
+### 降级契约
+
+某一层不可用时（如未配 `advisorModel`），编排者可临时兼任，但有四条硬约束：
+预算不变、受影响的部分**打降级标记**、注明**上下文隔离性已丢失**（既当执行者又当评审者，看不出自己的盲区）、
+且**最多兼任一个角色**——两个都自己兼，三层班子就名存实亡了，而"名存实亡"不会有任何报错。
+
+未开启时这一层整个不存在：不注册那两个工具、不套装饰器，`dispatch`/`advisor` 的行为与改造前逐位一致。
+
 ## 内置本机工具
 
 | 工具 | 说明 | 授权 |
@@ -127,11 +187,11 @@ huicai -c -p "继续修" --yolo   # 非交互续接（CI）
 | `schedule_followup` | 智能体给自己排后续任务（等构建完成后检查、明早再跑…），到点起全新无头会话续做 | **是否继续？三选项确认** |
 | `send_notification` | 弹系统通知把用户叫回来（长任务完成 / 需要人拍板 / 无人值守出结果） | 自动放行（本机提示，不外发） |
 | `machine_presence` / `set_wake_lock` / `wait_for_unlock` | 查锁屏与空闲状态 / 持防休眠锁让长任务跑完 / 等用户解锁再做界面操作 | 查看自动放行；持锁**三选项确认** |
+| `read_ui_tree` | **读界面结构**（可访问性树）：拿到当前窗口所有可点/可填控件的名称、精确坐标与快捷键，不用截图也不用目测坐标 | **是否继续？三选项确认** |
 | `computer_screenshot` / `computer_click` / `computer_move` / `computer_drag` / `computer_scroll` / `computer_type` / `computer_key` / `computer_apps` / `computer_focus_app` | 计算机使用：看屏幕、点鼠标、敲键盘、切换窗口——操作没有命令行的桌面软件 | **是否继续？三选项确认**（`computer_apps` 只读放行） |
 | `run_native_script` | 用系统原生脚本直接指挥应用（macOS AppleScript/JXA、Windows PowerShell/COM）——**操作桌面软件的首选**，比对着截图点坐标可靠 | **是否继续？三选项确认** |
 
-**自动化操作的三选项确认**（三端一致）：执行前询问「是否继续？」——`1、是`（仅此一次）·
-`2、是，并允许在当前对话中后续相同操作不再询问`（按工具名记忆，仅本会话）· `3、否`（可直接输入原因，会回灌给模型调整方案）。
+**自动化操作的三选项确认**：本次允许、会话同类操作允许、拒绝。终端用 ↑↓ 选择、Enter 确认、Esc 取消，无需输入编号；方案提问支持单选、多选与“其他意见”，见[操作指南](docs/terminal-workbench.md)。
 沙箱模式（`/sandbox`）下这些操作与 shell/联网一样被禁止；全部以 argv 直接 spawn（不经 shell）+ 参数白名单校验，杜绝命令注入。
 
 **执行策略**：同一轮里连续的只读工具调用**并行执行**（结果仍按序回灌）；单条工具输出超长自动**截断保头尾**，
@@ -143,12 +203,21 @@ huicai -c -p "继续修" --yolo   # 非交互续接（CI）
 无需用户配置，对话里按需自动生效：
 
 - **自动加载技能 / 专家团 / 专家**：本地技能（`.huicai/skills` + `~/.huicai/skills` + 随包内置）以「名称+描述」
-  常驻系统提示词、正文经 `load_skill` 按需载入；本地专家团（`.huicai/squads` + 内置 11 个）与子智能体人格
+  作为一条紧跟系统提示词的独立目录消息投放、正文经 `load_skill` 按需载入；**会话中途装的技能下一轮即可见**
+  （目录变了就追加一条替换目录，不必重开会话）。用户也可直接敲 `/技能名` 把某条技能的操作指引投进当前对话。
+  技能可用 frontmatter 的 `disable-model-invocation` / `user-invocable` 分别关闭模型侧或用户侧调用。
+  本地专家团（`.huicai/squads` + 内置 11 个）与子智能体人格
   进「能力目录」，模型据此自行 `dispatch_member` 派活；平台上你有权限的专家团/工作流/智能体/数字人自动编队成
   `consult_expert`。平台技能库还会在后台自动同步到本地（**本地优先、只增不删**，6 小时节流，`autoSkillSync:false` 关）。
 - **会话中途接入 MCP**：发现缺能力时 `list_mcp_servers` → `connect_mcp`，新工具**下一轮就能调用**
   （agent 循环每轮重算工具表），不必重开会话。
 - **对话式自动化任务**：说「以后每天…」就直接落成定时任务；改/停/删也是一句话。
+- **调度本机装着的别家智能体**：检测到 Claude Code / Codex 命令行时出现 `dispatch_external_agent`，
+  可把一个自足任务派给它们做交叉验证（每次调用都要用户批准——它会真的在本机读写文件、执行命令）。
+- **翻旧账翻到具体那一步**：`search_history` 找「哪次对话」，`session_event_search` 找「哪一条消息」，
+  `session_event_trace` 摊开那一步的前因后果（谁要求的 → 调了什么 → 返回什么 → 结论是什么）。
+- **联网搜索**：`web_search` 统一走平台（提供商与密钥由管理员后台配置，本机不直连搜索引擎），
+  **结果注明出自哪个提供商**。`/websearch on|off` 开关（与桌面端/IDEA 同源），关后平台智能体也不联网。
 - **消息通知**：长任务跑完（默认 ≥60s）自动弹系统通知；模型也可主动 `send_notification` 叫人。
 - **锁屏与无人值守**：Auto 模式与 `-p --yolo`（含 `huicai daemon` 派生的任务）全程持**防休眠锁**，
   合盖离开也不断。锁屏期间命令 / Python / 文件 / 联网照常跑；**只有屏幕点击键入会被操作系统挡住**——
@@ -198,8 +267,8 @@ huicai -c -p "继续修" --yolo   # 非交互续接（CI）
 双触发：上一轮**真实 `prompt_tokens`** 超阈值，或（尚无实测值时）本地估算超阈值——估算与 `/context`
 同口径、CJK 感知。**默认阈值 100 万 tokens**（`autoCompactTokens` 或 `/autocompact <N>` 可调，`off` 关闭）。
 
-阈值刻意高于多数模型的实际窗口：真正的把关在于**模型报「上下文装不下」时会自动强制压缩一次再重试同一模型**
-（用户无感，每回合至多 3 次），所以小窗口模型不必手动调小阈值，长会话也不会每隔几轮就被摘要打断。
+**会员等级有上下文上限时它就是窗口**：按平台口径估算到 90% 即压缩，摘要分块、工具结果、技能目录都按窗口收紧。
+模型或平台报「装不下」时强制压缩再重试（每回合至多 3 次），无需手动调小阈值。
 
 **摘要独立存储在会话的 compaction 状态里，原对话消息与页面显示完全不变**——只是发给模型的上下文换成
 「system + 摘要 + 最近几轮」的视图。优先以用户消息为切割边界；单个超长回合（一条提问 + 上百轮工具往返）
@@ -223,6 +292,66 @@ huicai -c -p "继续修" --yolo   # 非交互续接（CI）
 - 流式响应 90s 无数据由**停滞看门狗**中止（不再挂死），可直接重发。
 - 单回合最大工具轮数默认 60（`--max-turns` / `HUICAI_MAX_TURNS` / 配置 `maxTurns` 可调）。
 
+## 无视觉 GUI 自动化（P2-15）
+
+操作桌面软件原本只有两条路，各有硬伤：`run_native_script` 最准，但每个应用都要单独写脚本；
+视觉点击最通用，但慢（每步一张截图）、贵（一张图上千 token）、还不准（坐标靠模型目测）。
+
+`read_ui_tree` 是第三条：直接读**操作系统自己维护的那份界面结构**。按钮叫什么、在哪、能不能点、
+快捷键是什么，系统全都知道——比看截图快一个数量级、坐标是精确值、token 省两个数量级。
+
+优先级因此变成：**命令行/接口 → 原生脚本 → 读界面结构 → 视觉兜底**。
+
+```
+read_ui_tree                      # 读当前前台应用的可交互控件
+read_ui_tree {app:"预览"}          # 读指定应用
+read_ui_tree {menu:true}          # 只读菜单栏里带快捷键的命令
+```
+
+输出是紧凑行而非 JSON（同样的信息 JSON 要多花三倍 token）：
+
+```
+【预览 · 报表.pdf】可交互控件 12 个（原始节点 843 个，已按可交互/可见/可用/有名筛选）：
+1. 按钮「保存」中心(640,435) 80×30 快捷键 S
+2. 输入框「文件名」中心(420,380) 220×24
+...
+```
+
+**有快捷键就别去点按钮**——不用先定位、不受窗口移动影响、也不会点错到旁边的控件上。
+所以 `menu:true` 那条路往往比读控件更值。
+
+### 剪枝：这条路最容易翻车的是「量」，不是「难」
+
+一棵可访问性树几十万字符，不剪枝的话一次读取就能撑爆上下文，而且撑爆之前它还很慢。
+四条筛选规则（可交互类型 / 可见且面积够大且不在屏幕外 / 可用 / 有名）就地过滤，
+再加节点数与输出长度双重硬上限。一屏几百上千个节点通常筛到几十个。
+
+### 平台与权限
+
+| 平台 | 机制 | 需要授权 |
+| --- | --- | --- |
+| macOS | `osascript -l JavaScript` 驱动 System Events（底层即 AXUIElement） | **需要**「辅助功能」权限 |
+| Windows | PowerShell + `UIAutomationClient`（.NET 自带） | 不需要 |
+| Linux | 暂不支持（AT-SPI 需额外运行时，各桌面环境差异大） | — |
+
+两个平台用的都是既有 `run_native_script` 那套命令，**不引入任何新依赖**。
+
+macOS 未授权时系统返回 `-25211`，工具会识别出来并给出照着能做的三步指引——
+其中「**授权后要重启该程序**」是最容易漏掉的一步，漏了就是「我明明开了还是不行」。
+
+读不到时（应用没实现可访问性接口，常见于自绘界面、游戏、旧版 Electron）会明说原因并指向视觉路径，
+不会假装成功。锁屏约束不变：可访问性树在锁屏下同样不可用。
+
+> 它与截屏是同一类隐私暴露（都会读到别的窗口里的内容），所以同样走三选项审批，
+> 不因为"只是读"就默认放行。
+
+## 程序化驱动（ACP / SDK）
+
+`huicai acp` 起一个 **ACP（Agent Client Protocol）服务端**，编辑器与自动化客户端可经 JSON-RPC over stdio
+长驻驱动惠彩；`src/sdk.js` 是配套客户端（`spawn()` 起子进程，三个方法：开会话 / 提问 / 关掉）。
+与 `-p` 的分工——那个跑完就退出，这个能在同一段上下文里连续对话。
+协议方法、权限模型与用法示例见 [`docs/acp-sdk.md`](docs/acp-sdk.md)。
+
 ## 富 TUI（ink）
 
 TTY 下默认启用 ink + React 全屏界面：已定稿对话记录 + 流式正文、任务清单面板（☐/◐/☑）、思考 spinner、
@@ -233,7 +362,7 @@ TTY 下默认启用 ink + React 全屏界面：已定稿对话记录 + 流式正
 
 ## VS Code / Cursor 集成
 
-见 [`vscode/`](vscode/README.md)：纯 JS 扩展（无需构建），三项深度集成：
+见 [`huicai-vscode/`](../huicai-vscode/README.md)：纯 JS 扩展（无需构建），三项深度集成：
 - **诊断上下文**：把 Problems 诊断 + 当前文件/选区经环境变量注入智能体（`HUICAI_IDE_FILE`/`SELECTION`/`DIAGNOSTICS`）。
 - **内联 diff 审阅**：智能体写文件时，CLI 经本地服务把改动交扩展弹**原生 diff + 应用/拒绝**（`WorkspaceEdit`，可撤销）；未在扩展终端里则直接写盘。
 - **侧边栏面板**：快捷操作 + 最近会话列表（点击恢复）。