minimal-agent 0.10.0 → 0.12.0

package/README.md

@@ -1,7 +1,7 @@
 # minimal-agent
 
 > 一个**最小化但功能完整**的 AI 编程助手 —— Bun + React + TypeScript + Ink TUI 构建，
-> OpenAI 兼容、多 provider，16 个内置工具 + Skills + 插件 + Workflow DSL + 自动上下文压缩。
+> OpenAI 兼容、多 provider，内置工具 + Skills + 插件 + Workflow DSL + 自动上下文压缩。
 > 为**学习与教学**而生：代码量克制、注释充分，把一个 agent「从输入到工具循环到落盘」讲透。
 
 `v0.5.1` · Runtime: **Bun**（主）/ Node ≥ 20 · License: **PolyForm Noncommercial 1.0.0**
@@ -22,12 +22,13 @@
 
 ## 特性
 
-- **16 个内置工具**：Read / Write / Edit / MultiEdit / Glob / Grep / WebSearch / WebFetch / WebBrowser / Download / GenerateImage / GenerateSpeech / Bash / AskUserQuestion（向用户提结构化选择题，动态工作流交互底座）/ Advisor（独立配置的第二个 LLM，关键节点取第二意见）/ Agent（并行子任务分身：explore 只读调研 / general 读写执行，可 git worktree 隔离）
+- **内置工具系统**：文件与终端、网页检索、媒体生成、结果交付、长期记忆、结构化提问、顾问、Computer Use 和并行 Agent。
 - **OpenAI 兼容**：Message 形状对齐 Chat Completions，一套代码接 MiniMax / 火山 ARK / DeepSeek / OpenAI / Moonshot…
 - **Skills 系统**：放一个 `SKILL.md` 就能扩展能力，运行时实时扫描注入 prompt，改文件即生效
 - **插件系统**：`plugins/<id>/` drop-in，自带 `/workflow`（YAML 工作流引擎，支持 while 循环 + 验证门 + fresh_context）
 - **自动上下文压缩**：接近上限时把旧对话压成摘要，保留系统提示 + 摘要 + 最近几条
 - **多 session + 归档**：同一工作目录多个并行会话，`/new` 归档、`/restore` 恢复
+- **Markdown 长期记忆**：全局人格与偏好、按工作目录隔离的项目记忆，可通过自然语言新增、更新、召回和删除
 - **可编程子进程**：`-p --output-format json` 输出一行结构化结局契约，方便被宿主程序 spawn 调度
 - **三种运行形态**：源码跑（dev）/ npm 全局安装 / **bun --compile 绿色单文件夹**（免安装，可装 U 盘）
 
@@ -143,10 +144,17 @@ minimal-agent -p --output-format json "做点事"           # 一行结构化结
 | **WebSearch** | Tavily API | 需 `TAVILY_API_KEY` |
 | **WebFetch** | `fetch` + `turndown` | HTML → Markdown，LRU 缓存 |
 | **WebBrowser** | `playwright-core`（可选） | 缺依赖时自动降级 WebFetch |
+| **Memory** | Markdown + YAML frontmatter | 全局人格、个人记忆、项目记忆及增删改查；旧 JSON 自动迁移 |
 | **Bash** | `child_process` | 黑名单 + 超时双保险 |
 
 工具失败**不抛异常**——把 error 写进结果喂回 LLM 让它自己重试。
 
+### 长期记忆
+
+本机主人会话可以直接说“记住……”“把之前的……改成……”“忘记……”，Agent 会在当前回合调用记忆工具。全局人格与个人记忆位于 `~/.minimal-agent/memory/global/`，项目记忆位于 `~/.minimal-agent/memory/workspaces/<workspaceId>/`；每条事实都是可读、可编辑的 Markdown 文件。记录带修订号、确认时间和内容版本，过期只进入复核队列，不会被自动删除。当前消息始终优先于旧记忆，密码、Token、验证码和私钥不会写入。
+
+历史用户消息和最终回答以清理后的 JSONL 存在 `~/.minimal-agent/episodes/`，独立于上下文压缩；检索默认仅限当前工作区。非交互模式默认不开放本机记忆；受信任宿主需显式传入 `--memory-access local-owner`。首次访问会把旧 JSON 和 v1 Markdown 幂等迁移到 v2 Markdown，并保留时间戳备份。
+
 ## Skills · 插件 · Workflow
 
 - **Skills**：每个 `skills/<name>/SKILL.md`（带 frontmatter）。运行时实时扫描注入 prompt，prompt 体按需懒加载。
@@ -199,7 +207,7 @@ dev 下 Bun 透明回退到 `.ts` 兄弟，发布前 `tsc --build` 原地产出
 | `src/loop.ts` | `runQuery()` 主循环（AsyncGenerator）—— 系统的「心脏」 |
 | `src/llm/client.ts` | OpenAI 兼容流式客户端（text / tool_call / reasoning 三路） |
 | `src/types.ts` | 对齐 Chat Completions 的 Message / ToolCall / 事件类型 |
-| `src/tools/` | 11 个工具 + `executeTool()` 参数防线（JSON.parse → Zod → call） |
+| `src/tools/` | 内置工具 + `executeTool()` 参数防线（JSON.parse → Zod → call） |
 | `src/context/compact.ts` | 自动上下文压缩 |
 | `src/prompts/` | system prompt 组装 + Skills 实时扫描注入 |
 | `src/plugins/` | 插件框架（discovery / 命令路由 / hook 引擎 / transcript） |

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "minimal-agent",
-  "version": "0.10.0",
-  "description": "最小化 Agent 系统 —— 10 工具 + 插件系统 + workflow DSL + 自动压缩 + OpenAI 兼容 + Ink TUI；NodeNext + tsc 原地编译，dev 用 Bun .ts、install 用 Node .js（学习/教学用）",
+  "version": "0.12.0",
+  "description": "Bun-first 的本地 Agent 内核，支持工具、插件、工作流、上下文压缩、长期记忆与 OpenAI 兼容接口；Tauri 桌面宿主和 Node.js npm 发布可复用同一内核",
   "license": "SEE LICENSE IN LICENSE",
   "author": "Bill Wang <leiwang0359@gmail.com>",
   "repository": {
@@ -40,6 +40,41 @@
       "bun": "./src/config/configService.ts",
       "default": "./src/config/configService.js"
     },
+    "./config-limits": {
+      "types": "./src/config/numericLimits.ts",
+      "bun": "./src/config/numericLimits.ts",
+      "default": "./src/config/numericLimits.js"
+    },
+    "./config-management": {
+      "types": "./src/config/configManagement.ts",
+      "bun": "./src/config/configManagement.ts",
+      "default": "./src/config/configManagement.js"
+    },
+    "./config-diagnostics": {
+      "types": "./src/config/configDiagnostics.ts",
+      "bun": "./src/config/configDiagnostics.ts",
+      "default": "./src/config/configDiagnostics.js"
+    },
+    "./memory-service": {
+      "types": "./src/memory/memoryService.ts",
+      "bun": "./src/memory/memoryService.ts",
+      "default": "./src/memory/memoryService.js"
+    },
+    "./human-intervention": {
+      "types": "./src/humanIntervention.ts",
+      "bun": "./src/humanIntervention.ts",
+      "default": "./src/humanIntervention.js"
+    },
+    "./prompt-cache": {
+      "types": "./src/llm/promptCache.ts",
+      "bun": "./src/llm/promptCache.ts",
+      "default": "./src/llm/promptCache.js"
+    },
+    "./runtime-context": {
+      "types": "./src/runtime/agentRuntimeContext.ts",
+      "bun": "./src/runtime/agentRuntimeContext.ts",
+      "default": "./src/runtime/agentRuntimeContext.js"
+    },
     "./provider-presets": {
       "types": "./src/cli/wizards/providerPresets.ts",
       "bun": "./src/cli/wizards/providerPresets.ts",
@@ -58,41 +93,52 @@
     "node": ">=20"
   },
   "files": [
+    "src/**/*.ts",
+    "src/**/*.tsx",
     "src/**/*.js",
     "src/**/*.d.ts",
+    "plugins/**/*.ts",
     "plugins/**/*.js",
     "plugins/**/*.d.ts",
     "plugins/**/.claude-plugin/**",
     "plugins/**/commands/**",
     "plugins/**/hooks/**",
+    "plugins/**/app/**",
     "plugins/HOW-TO-WRITE-A-PLUGIN.md",
     "skills/**",
+    "!skills/**/__pycache__/**",
+    "!skills/**/*.pyc",
     "workflows/**",
     "vendor/ripgrep/**",
+    "vendor/computer-use/**",
     "README.md",
     "MINIMAL-TRACE.md",
     "LICENSE"
   ],
   "scripts": {
-    "start": "bun run src/main.tsx",
-    "dev": "bun --watch src/main.tsx",
+    "start": "bun run clean && bun run src/main.tsx",
+    "dev": "bun run clean && bun --watch src/main.tsx",
     "build": "tsc --build",
     "clean": "bun scripts/clean-build.ts",
     "check:build-artifacts": "bun scripts/check-build-artifacts.ts",
-    "test": "bun test",
+    "test": "bun run clean && bun test",
     "typecheck": "tsc --noEmit -p tsconfig.typecheck.json",
     "verify-all": "bun scripts/verify-all.ts",
+    "eval:harness": "bun scripts/eval-harness.ts",
     "compile:green": "bun scripts/build-green.ts",
     "compile:green:host": "bun scripts/build-green.ts --host",
     "doc:gen": "node doc/scripts/gen-pptx.mjs",
     "prepublishOnly": "bun run clean && bun run build"
   },
   "dependencies": {
+    "diff": "^8.0.2",
     "fast-glob": "^3.3.2",
     "ink": "^5.0.1",
     "marked": "^18.0.6",
+    "pdfjs-dist": "4.10.38",
     "react": "^18.3.1",
     "turndown": "^7.2.4",
+    "vscode-jsonrpc": "^8.2.1",
     "yaml": "^2.9.0",
     "zod": "^3.23.8",
     "zod-to-json-schema": "^3.25.2"
@@ -104,6 +150,7 @@
     "typescript": "^5.5.0"
   },
   "optionalDependencies": {
+    "@napi-rs/canvas": "^0.1.100",
     "playwright-core": "^1.40.0",
     "pngjs": "^7.0.0",
     "pptxgenjs": "^4.0.1"

package/plugins/computer_use/.claude-plugin/plugin.json

@@ -0,0 +1,6 @@
+{
+  "name": "computer-use",
+  "version": "0.1.0",
+  "description": "桌面操作的应用说明书与诊断命令面。说明书住在 app/，由内核 ComputerUse 工具强制注入；本插件提供 /computeruse 与 /cu 的确定性命令（状态、体检、说明书、采集、遥测、审计、观测）。",
+  "appManuals": "app"
+}

package/plugins/computer_use/README.md

@@ -0,0 +1,94 @@
+# computer-use 插件
+
+两件事：**应用说明书**（`app/`）和 **`/computeruse` 诊断命令面**。
+
+桌面操作本身不在这里 —— 那是内核 `ComputerUse` 工具的活。
+
+## 为什么强制点不在插件里
+
+模型是在任意一轮对话里直接调 `ComputerUse` 工具的，而 `plugin.ts` 的
+`runCommand` 只在用户**显式敲斜杠命令**时才会被调用（非 `/` 输入直通
+`runQuery`，这是框架的 V1 红线且有测试守着）。
+
+所以说明书的消费点必须在工具层：引擎在每次观测时**直接把说明书写进回执**，
+并在不可逆动作前校验说明书声明的前置条件。把强制逻辑写进 plugin.ts，会得到
+一个看着像插件、实际只在用户敲命令时才生效的安全机制。
+
+这也是这个插件与「skill 版本」的真正差别 —— 不是换了个目录，而是知识从
+「模型可参考可不参考」变成了「引擎必注入 + 部分条目机器可强制」。
+
+## 说明书从哪儿来
+
+两类 Provider，**按优先级从高到低**（`vision/appGuide.ts::appManualProviders`）：
+
+1. **工作区** `<cwd>/app-manuals/<app>.md` —— 用户自己的，可写，`capture --write`
+   的落点。不需要任何 manifest。
+2. **插件声明** —— plugin.json 里 `"appManuals": "app"` 的**显式 opt-in**。
+
+第 2 类此前是纯目录约定（任何插件目录下有 `app` 子目录就自动生效），等于
+「任意目录自动影响可信内核」。现在必须显式声明，路径还要经
+`src/plugins/pluginManifest.ts` 收敛（拒绝绝对路径、`..`、软链逃逸）。
+
+覆盖是**逐文件**的：放一份同名 `wechat.md` 只覆盖那一份，不会屏蔽同一来源的
+其余说明书。
+
+**为什么工作区目录叫 `app-manuals/` 而不是 `.minimal-agent/…`**：
+`.minimal-agent` / `.minimal-agent-*` 是框架保留前缀，`/new` 会把 cwd 下所有
+这类目录**递归删掉**（`persistContext.ts::clearContext`）。捕获的说明书是长期
+知识，不是会话状态。
+
+⚠️ 插件的 `app/` 是**数据不是代码**：打不进 exe、也不会被 tsc 编译带走，必须由
+构建脚本显式拷贝。三条分发路径都要带上它（`package.json::files`、
+`scripts/build-green.ts`、`minimal-desktop/scripts/build-sidecar.ts`），
+漏一条的后果是「每个应用都报未找到说明书」，且没有任何构建期错误。
+
+## 说明书格式
+
+一个文件两层，抄 `_template.md` 起步：
+
+- **frontmatter（机器层）** —— 引擎读它做匹配、不可逆判定、前置条件校验：
+  `match` / `irreversible` / `layout` / `controls` / `flows` / `verification`
+- **正文（散文层）** —— 给模型看的事实：界面布局、控件语义、坑与恢复出口、
+  `## 实测记录`
+
+**每个结构化条目自带 `verified`。** 未实机验证就写 `false` —— 引擎注入时会如实
+标注。丢掉这个限定词等于把猜测说成事实，而说明书里多数内容目前正是从面向人的
+文档转写来的、没跑过。
+
+`flows[].steps[].precondition` 只允许引擎能独立验证的五个谓词：
+
+```
+foreground_app_is <id或名字片段>    window_title_contains <文本>
+focused_role_is <AXRole>            ax_available
+element_exists <AXRole[:名字片段]>
+```
+
+写不成这几种形状的约束请放进 `pitfalls` 当散文。把不可验证的东西写成
+`precondition:` 会得到一个永远通过的检查——那比没有检查更糟，因为它看起来
+像有保护。`/computeruse app <name>` 会把写错的形状报出来。
+
+## 命令
+
+全部确定性执行，不烧 LLM：
+
+| 命令 | 作用 |
+|---|---|
+| `/computeruse` | 总览：平台、守护进程、权限、能力三态分组 |
+| `/computeruse doctor` | 权限体检 + 逐项修复指引 |
+| `/computeruse apps` | 说明书清单、冲突、当前前台应用命中哪一份 |
+| `/computeruse app <name>` | 某份说明书的摘要与 schema 校验报告 |
+| `/computeruse capture [name] [--write]` | 观测当前前台应用生成草稿；默认只打印 |
+| `/computeruse verify <app>` | 半自动实机验收：逐步提示、每步记录实际观测、全过才翻 `verified` |
+| `/computeruse observe` | 跑一次观测，结果给人看 |
+| `/computeruse report` | 遥测汇总 |
+| `/computeruse audit [n]` | 守护进程动作流水 + 不可逆授权记录（两份并排，不合并） |
+
+`/cu` 是等价别名。
+
+### capture 采到的是什么
+
+**只有应用身份是实测的**。控件候选来自采集当时的 AX 树、未经验证；
+界面分区与典型流程**留空**——一次观测看不出它们，编出来的比空着更糟；
+不可逆动作清单也留空，因为屏幕上看不出「哪个动作收不回来」，那是产品语义，
+必须由人补。草稿里**不含任何 rect**：窗口能拉伸、能全屏、能换显示器，
+一次观测的坐标写进 schema 就是一批看着像已验证、下一次就失准的数据。

package/plugins/computer_use/app/_template.md

@@ -0,0 +1,142 @@
+---
+schemaVersion: 2
+guideVersion: 1
+status: draft
+platforms: [macOS, Windows]
+match:
+  bundleId: []
+  processName: []
+  displayName: []
+irreversible:
+  - intent:replace-with-a-stable-intent
+
+# ---- 以下三段是 schema v2 的结构化部分，引擎会直接注入给模型 ----
+
+# 界面分区。相对坐标 [x, y, width, height]，0–1000，只表达"大致在哪一块"，
+# 不用于点击 —— 点击一律靠 elementId 或当次观测。
+# ── 可选：这个应用专属的「该叫人来」信号 ──
+# 引擎自己认识跨应用通用的边界（密码框、验证码、二维码登录、权限弹窗…），靠扫无障碍
+# 树里的文字就能判。只有当**这个应用的边界通用规则认不出来**时才需要写这一段。
+#
+# 典型场景：某个登录窗压根不出现「登录」「扫码」这类字样，只能靠几个控件**同时出现**
+# 来认。allOf 里每条正则都要在 AX 的 `role name` 文本里命中才算成立。
+#
+# ⚠️ 别只写一个关键词：单信号极易误判（比如「二维码」单独出现，可能只是聊天里
+#    别人发的一张图）。引擎会对单信号声明报 warn。
+# ⚠️ reason 只能取：password / otp / captcha / qr_login / login /
+#    permission / security_warning / blocked / manual —— 写别的会在加载期报 error。
+#
+# humanBoundary:
+#   - reason: qr_login
+#     summary: 需要你扫码完成登录
+#     allOf:
+#       - 二维码
+#       - 仅传输文件
+
+layout: []
+#  - id: sidebar
+#    rect: [0, 60, 220, 940]
+#    desc: 会话列表
+#    verified: false
+
+# 关键控件。优先写 AX 锚点（换分辨率/换版本都成立），坐标只作兜底。
+controls: []
+#  - id: search_box
+#    ax: { role: AXTextField, name: [搜索, Search] }
+#    desc: 顶部搜索框
+#    verified: false
+
+# 典型流程。steps[].precondition 只能用引擎可独立验证的谓词：
+#   foreground_app_is <id或名字片段>  window_title_contains <文本>
+#   focused_role_is <AXRole>          ax_available
+#   element_exists <AXRole[:名字片段]>
+# 写不成这几种形状的约束请写进 pitfalls 当散文 —— 把不可验证的东西写成
+# precondition 会得到一个永远通过的检查，那比没有检查更糟。
+flows: {}
+#  send_message:
+#    goal: 给指定联系人发一条文字消息
+#    verified: false
+#    steps:
+#      - do: 用搜索框定位联系人，回车打开会话
+#      - do: 确认聊天标题与目标联系人一致
+#        precondition: window_title_contains 联系人名
+#      - do: 发送
+#        irreversible: true
+#    pitfalls:
+#      - 群名与联系人可能重名，只看标题会发错对象
+
+verification:
+  environment: 未验证
+  verifiedAt: never
+  verifiedItems: []
+  unverifiedItems: [identity, layout, controls, flows]
+---
+
+# <应用名> App Guide
+
+> 复制为小写、稳定的文件名后填写。frontmatter 是**机器层**（引擎读它做匹配、
+> 不可逆判定、前置条件校验），正文是**散文层**（给模型看的事实）。
+>
+> 只记录可复核的应用事实。通用执行策略、权限规则和临时事故不写入说明书。
+> **每个结构化条目都带 `verified`**，未实机验证就写 `false` —— 引擎注入时会
+> 如实标注，丢掉这个限定词等于把猜测说成事实。
+
+## 稳定身份
+
+### macOS
+
+- Bundle ID：
+- 进程名：
+- 常见显示名：
+
+### Windows
+
+- 可执行文件名：
+- 进程名：
+- 常见显示名：
+
+## AX / UIA 可发现线索
+
+- **macOS AX 候选线索**：
+- **Windows UIA 候选线索**：
+- **焦点通道可用层级**：未实机验证。验证后记录平台、应用版本和实际层级。
+- 候选线索仅用于缩小观测范围；必须由当前 Accessibility 快照确认后才能操作。
+
+## 常见自绘区
+
+- （仅写 Accessibility 可能不完整、需要视觉兜底的区域；未验证时明确标注。）
+
+## 风险动作与不可逆动作
+
+- Frontmatter 只使用稳定的 `intent:<name>`，不使用像素区域。
+- 写明会产生外部发送、覆盖、删除、发布、付款或安全设置变化的动作。
+- 快捷键会受用户偏好影响时，不把快捷键声明为不可逆触发器。
+
+## 弹窗与恢复
+
+| 弹窗或状态 | 可观察线索 | 安全恢复出口 |
+|---|---|---|
+|  |  |  |
+
+## 可替代 API
+
+- （列出比桌面操作更稳定的官方 API、文件接口或系统通道；没有则写“无已验证替代 API”。）
+
+## 已验证范围
+
+- **验证环境**：未验证。
+- **已验证**：无。
+- **仍需验证**：身份、AX/UIA 结构、自绘区、风险动作、弹窗和恢复路径。
+- 验证完成后更新 `guideVersion`、`verification` 与对应条目的 `verified: true`；
+  不要扩大到未测试版本。
+
+## 实测记录
+
+> **这一节是 agent 的自我完善区。** 说明书与实况不符时（写着的控件找不到、
+> precondition 反复失败、流程步骤对不上），把**观察到的事实**追加到这里，
+> 一条一行，带日期与应用版本。
+>
+> 只写观察到的，不写推测。确认稳定之后再由人把它提升进 frontmatter 的
+> 结构化条目并标 `verified: true` —— 单次观察不能直接升级为永久事实。
+
+- （暂无）

package/plugins/computer_use/app/chrome.md

@@ -0,0 +1,165 @@
+---
+schemaVersion: 2
+guideVersion: 1
+status: draft
+platforms: [macOS, Windows]
+match:
+  bundleId: [com.google.Chrome, com.google.Chrome.beta, com.google.Chrome.canary]
+  processName: [Google Chrome, chrome.exe]
+  displayName: [Google Chrome, Chrome, 谷歌浏览器]
+irreversible:
+  - intent:submit-web-form
+  - intent:clear-browsing-data
+  - intent:remove-profile
+  - intent:install-extension
+  - intent:change-security-setting
+
+layout:
+  - id: tab_strip
+    desc: 顶部标签栏，最右是新建标签按钮
+    verified: false
+  - id: toolbar
+    desc: 地址栏一行；左侧前进/后退/刷新，右侧扩展、个人资料、三点菜单
+    verified: false
+  - id: bookmarks_bar
+    desc: 书签栏，可被用户隐藏 —— 不能假定它存在
+    verified: false
+  - id: page_viewport
+    desc: 网页内容区。**这一块不要用 ComputerUse 操作**，见下
+    verified: false
+  - id: download_shelf
+    desc: 下载提示。新版 Chrome 是工具栏上的下载气泡，不是底部横条
+    verified: false
+
+controls: []
+
+flows:
+  hand_off_to_webbrowser:
+    goal: 判断这件事该不该用 ComputerUse 做
+    verified: false
+    steps:
+      - do: 如果目标是网页里的内容（读文字、点按钮、填表单、抓数据）—— 停，改用 WebBrowser 工具
+      - do: 只有目标是浏览器外壳本身（切标签、管窗口、处理系统弹窗）才继续用 ComputerUse
+    pitfalls:
+      - WebBrowser 有 DOM 和 CDP，能按选择器精确定位；看屏幕点像素在网页上是纯粹的降级
+      - 网页布局随滚动、懒加载、响应式断点变化，上一次观测的坐标下一秒就可能失效
+      - 两个工具各自持有独立的浏览器会话，不要指望在一个里登录、另一个里用
+
+  switch_tab:
+    goal: 在已打开的标签之间切换
+    verified: false
+    steps:
+      - do: 确认 Chrome 在前台
+        precondition: foreground_app_is com.google.Chrome
+      - do: observe 读出标签栏上各标签的标题与位置
+      - do: 点击目标标签后重新 observe，用窗口标题确认切过去了
+    pitfalls:
+      - 标签多到装不下时会被压缩成只剩图标，标题读不出来
+      - 窗口标题跟随当前标签变化，是确认"现在在哪个标签"的最可靠信号
+
+  handle_system_dialog:
+    goal: 处理 Chrome 弹出的系统级对话框（文件选择、权限请求、打印）
+    verified: false
+    steps:
+      - do: observe 确认弹出的确实是系统对话框而不是网页里画的假框
+        precondition: ax_available
+      - do: 文件选择框用 file_drop 的 open_panel 方式送路径
+      - do: 权限请求（摄像头、麦克风、位置、通知）一律交还用户，不代为同意
+    pitfalls:
+      - 网页可以画出以假乱真的"系统对话框"；真的那个有无障碍信息，假的没有
+      - 权限授予是账号级别的持久变更，不属于可以替用户点的那一类
+
+verification:
+  environment: 未验证
+  verifiedAt: never
+  verifiedItems: []
+  unverifiedItems: [identity, layout, controls, flows]
+---
+
+# Google Chrome App Guide
+
+## 这份说明书最重要的一句话
+
+**网页里的事交给 `WebBrowser` 工具，不要用 ComputerUse。**
+
+ComputerUse 在浏览器上是**降级**手段：它只能看像素、按坐标点。而
+`WebBrowser` 走 CDP，拿得到 DOM、能按选择器定位、能读到看不见的属性、
+能等待网络空闲。在网页这个场景里，后者不是"另一个选项"，是正确答案。
+
+ComputerUse 在 Chrome 上只剩下 WebBrowser 够不着的那部分：
+
+| 该用 ComputerUse | 该用 WebBrowser |
+|---|---|
+| 切换标签、关窗口、调整窗口大小 | 点页面上的按钮、填表单、读正文 |
+| 处理系统文件选择框 / 打印对话框 | 等待页面加载、抓结构化数据 |
+| 应对 Chrome 自身的更新提示、崩溃恢复条 | 任何需要"这个元素在哪"的事 |
+| 用户已经开着的、有登录态的那个 Chrome | 自动化任务自己开的浏览器 |
+
+最后一行是最常见的真实理由：用户手头这个 Chrome 有他的登录态和插件，
+而 WebBrowser 起的是独立 profile。这时用 ComputerUse 是合理的，但要清楚
+自己在用一件更钝的工具，每一步都得 observe 核实。
+
+## 稳定身份
+
+### macOS
+
+- Bundle ID：`com.google.Chrome`（beta/canary 各有自己的 id）
+- 进程名：`Google Chrome`
+- 常见显示名：`Google Chrome`、`Chrome`、`谷歌浏览器`
+
+### Windows
+
+- 可执行文件名：`chrome.exe`
+- Windows 身份尚未实机验证。
+
+## AX / UIA 可发现线索
+
+- **浏览器外壳**（标签栏、地址栏、菜单）通常有无障碍信息，可以用 elementId 定位。
+- **网页内容区**的无障碍树取决于页面本身，且与 DOM 不是一回事 —— 想按结构
+  操作页面就该用 WebBrowser，不要试图从 AX 里还原 DOM。
+- **焦点通道可用层级**：未实机验证。
+
+## 常见自绘区
+
+- 网页内容区（由页面决定，什么都可能）
+- PDF 内置查看器、DevTools 面板、部分扩展弹窗
+
+## 风险动作与不可逆动作
+
+- 在网页里提交表单、下单、发帖 —— 后果在浏览器之外，收不回来。
+- 清除浏览数据、删除个人资料：会连带登录态、Cookie、历史一起没。
+- 安装扩展、改隐私与安全设置：持久变更，且扩展拿到的权限可能很大。
+- 授予网页权限（摄像头、麦克风、位置、通知）：交还用户，不代为点击。
+
+## 弹窗与恢复
+
+| 弹窗或状态 | 可观察线索 | 安全恢复出口 |
+|---|---|---|
+| 系统文件选择框 | 独立窗口，有完整无障碍信息 | 用 file_drop 的 open_panel 送路径 |
+| 网页画的假对话框 | 停留在页面内、无无障碍信息 | 当成普通页面元素，改用 WebBrowser 处理 |
+| 权限请求气泡 | 地址栏下方的浮层 | 交还用户，不代为同意 |
+| "Chrome 未正确关闭"恢复条 | 页面顶部黄条 | 报告给用户，不要自作主张恢复全部标签 |
+| 更新后需重启提示 | 三点菜单变色、提示条 | 不代为重启 —— 会丢用户没保存的页面状态 |
+
+## 可替代 API
+
+- **首选 `WebBrowser` 工具**（`agent-browser` + CDP），覆盖绝大多数网页任务。
+- 只取内容不交互时 `WebFetch` 更省：直接拿 HTML→Markdown，不启动浏览器。
+- 下载文件用 `Download` 工具，不要驱动浏览器点下载按钮。
+
+## 实测记录
+
+> **这一节是 agent 的自我完善区。** 说明书与实况不符时，把**观察到的事实**
+> 追加到这里，一条一行，带日期与 Chrome 版本。
+>
+> 只写观察到的，不写推测。确认稳定后由人提升进 frontmatter 并标
+> `verified: true`。
+
+- （暂无）
+
+## 已验证范围
+
+- **验证环境**：未验证。
+- **已验证**：无。
+- **仍需验证**：全部 —— 身份、布局、流程都来自公开文档转写，没有实机跑过。
+- 与 WebBrowser 的职责边界是**设计决定**，不需要实机验证；其余都需要。

package/plugins/computer_use/app/finder.md

@@ -0,0 +1,76 @@
+---
+schemaVersion: 2
+guideVersion: 1
+status: identity-verified
+platforms: [macOS]
+match:
+  bundleId: [com.apple.finder]
+  processName: [Finder]
+  displayName: [Finder, 访达]
+irreversible:
+  - intent:delete-item
+  - intent:empty-trash
+  - intent:replace-item
+  - intent:eject-volume
+verifiedRange:
+  macOS: Finder 26.4 identity only
+  windows: not-applicable
+lastVerifiedAt: 2026-07-29
+verification:
+  environment: macOS 26.4 / Finder 26.4
+  verifiedAt: 2026-07-29
+  verifiedItems: [identity]
+  unverifiedItems: [layout, controls, flows]
+---
+
+# Finder App Guide
+
+## 稳定身份
+
+### macOS
+
+- Bundle ID：`com.apple.finder`
+- 进程名：`Finder`
+- 常见显示名：`Finder`、`访达`
+
+### Windows
+
+- 不适用；Windows 文件管理器应建立独立指南，不能与 Finder 共用身份或交互事实。
+
+## AX / UIA 可发现线索
+
+- **macOS AX 候选线索**：窗口标题通常对应当前位置；工具栏、侧边栏、文件浏览区、路径栏和表格/图标视图应分别从当前 AX 快照确认。
+- **焦点通道可用层级**：未实机验证。
+- 文件名、选择状态和当前目录必须以本次 AX 快照或文件系统结果为准，不能从旧截图推断。
+
+## 常见自绘区
+
+- 图标视图中的缩略图、Quick Look、图库视图和云端同步徽标可能需要视觉兜底；当前版本尚未实机验证这些区域的 AX 完整度。
+
+## 风险动作与不可逆动作
+
+- 移到废纸篓、立即删除、清倒废纸篓。
+- 覆盖同名文件、合并文件夹。
+- 弹出外接磁盘或网络卷。
+- 修改文件名或移动文件可能使其他会话保存的路径失效。
+
+## 弹窗与恢复
+
+| 弹窗或状态 | 可观察线索 | 安全恢复出口 |
+|---|---|---|
+| 同名项目冲突 | 系统 Sheet 中出现停止、替换、保留两者等选项 | 未获得覆盖意图时取消，重新观测目标目录 |
+| 文件被占用或权限不足 | 系统错误 Sheet 或认证提示 | 停止重试，保留原文件并报告 |
+| iCloud 项目尚未下载 | 云端状态或下载进度仍存在 | 通过文件存在且大小稳定确认，不依赖缩略图 |
+| 外接卷离线 | 侧边栏卷消失或文件系统路径不可访问 | 保留路径引用，等待重新挂载，不改绑其他同名卷 |
+
+## 可替代 API
+
+- 列举、搜索、复制、移动、重命名和校验文件优先使用受控文件工具。
+- 打开文件或在 Finder 中定位可使用宿主提供的系统文件接口。
+- Quick Look 仅用于预览，不作为文件存在、上传完成或写入成功的权威证据。
+
+## 已验证范围
+
+- **验证环境**：macOS 26.5.2，Finder 26.4。
+- **已验证**：Bundle ID、进程名和应用包版本元数据。
+- **仍需验证**：AX 层级、各视图模式、自绘区、冲突 Sheet、外接卷与 iCloud 恢复流程。