minimal-agent 0.10.0 → 0.12.0

package/plugins/computer_use/app/weread.md

@@ -0,0 +1,319 @@
+---
+schemaVersion: 2
+guideVersion: 1
+status: layout-verified
+platforms: [macOS]
+match:
+  bundleId: [com.tencent.weread, com.tencent.wereadmac]
+  processName: [WeRead, 微信读书]
+  displayName: [微信读书, WeRead]
+irreversible:
+  critical: []
+  normal:
+  - intent:purchase
+  - intent:subscribe
+  - intent:share
+  - intent:gift
+verifiedRange:
+  macOS: 微信读书 iOS 套壳版（/Applications/微信读书.app/Wrapper/WeRead.app），身份 / 分区 / 页码位置 / 翻页键 / 沉浸模式唤出菜单 / 返回流程
+lastVerifiedAt: 2026-08-09
+
+# ---- schema v2 结构化部分 ----
+#
+# ⚠️ 微信读书是 **iOS 应用套壳**，无障碍树只给得出一个空壳 AXGroup（实测焦点恒为
+# `AXGroup · caret(51,97)` 这类窗口角落的退化包装节点）。所以这里**不写 ax 锚点、
+# 不写绝对 rect** —— 写了就是编的，而编出来的锚点比没有更糟：模型会拿它当事实去点。
+# 分区只声明「存在、大致在窗口的哪一带」，真实位置每次从当次观测里读。
+#
+# ⚠️ 所有位置一律用**窗口相对比例**表达，不用屏幕坐标。见正文「坐标必须锚窗口」一节，
+# 那是本应用最容易致命的一个坑。
+
+layout:
+  - id: tab_bar
+    desc: 窗口**底部**四个标签「阅读 / 书架 / 书友 / 我」，y 约在窗口高度的 93% 一带；只在非阅读界面出现
+    verified: true
+  - id: search_box
+    desc: 窗口**顶部**通栏搜索框，y 约在窗口高度的 7% 一带；**阅读页和书架页都有**，不必先切到书架
+    verified: true
+  - id: weekly_card
+    desc: 「阅读」页左上角的「本周阅读」卡片，右侧横排着最近在读的书，封面上直接印着书名 —— 常读的书从这里一次点击就能进
+    verified: true
+  - id: shelf_grid
+    desc: 「书架」页的封面网格，书名印在封面上；常看的书直接点封面即可
+    verified: true
+  - id: search_results
+    desc: 搜索结果页，**分两组且书架组在上**：「在书架中搜索：<词>」（你账号里已有的书）在上，「在书城中搜索：<词>」在下；顶部还有 全部/电子书/有声书/全文/作者/书单/公众号/文章 分类
+    verified: true
+  - id: book_detail
+    desc: 书籍详情页（书名 + 推荐值 + 点评）；**底部一条通栏蓝色大按钮**「阅读 / 继续阅读」是进正文的入口
+    verified: true
+  - id: reading_pane
+    desc: 正文阅读区，宽窗口下是**左右双页对开**（左右各一页），窄窗口下单页；沉浸模式下没有标题栏也没有返回箭头
+    verified: true
+  - id: page_footer
+    desc: 页码在**每一页的右下角**（不是居中）：左页那个在中缝左侧、右页那个在窗口最右侧，形如「32 / 115」（当前页 / 总页数）
+    verified: true
+  - id: back_arrow
+    desc: 窗口**左上角**的返回箭头 ‹；在搜索结果页/详情页/二级页面常驻，在沉浸阅读模式下隐藏（点窗口正中心唤出菜单后才出现）
+    verified: true
+  - id: reading_toolbar
+    desc: 沉浸阅读模式下唤出的底部工具条，含目录/书签、主题切换、字体大小调节、Ai 等按钮；与返回箭头同时出现/同时隐藏
+    verified: true
+  - id: reading_topbar
+    desc: 沉浸阅读模式下唤出的顶部工具栏，含左侧返回箭头、右侧分享/目录/设置等图标；与底部工具条同步显隐
+    verified: true
+
+controls: []
+
+flows:
+  read_page_number:
+    goal: 读出当前页码 —— 本应用一切定位的基础，翻页前必做
+    verified: true
+    steps:
+      - do: |
+          observe 时带上放大镜读页脚，**坐标用相对窗口的、固定值**：
+          magnify: { x: 0, y: 945, width: 1000, height: 55 }
+          magnifyAnchor: "window"
+          引擎会按当前窗口位置自己换算 —— 你**不需要**从回执里抠窗口范围手算。
+          它从**原始分辨率帧**裁一条窗口底部通宽的横条放大后附成第 2 张图。
+          页码形如「32 / 115」（当前页 / 总页数），双页对开时左右两页各一个。
+      - do: 框不中就把 y 在 900~975 之间挪一挪重试（仍用 magnifyAnchor:"window"）
+    pitfalls:
+      - ⛔ **不用放大镜是读不出页码的。** 原图 5120×2880 压到约 1371×771 才发给你，20px 高的页码只剩约 5px，是一团马赛克 —— 猜必错，此前模型报的页码全是蒙的
+      - 宽度必须取整个窗口宽（width:1000 + anchor window）：两个页码分别贴在左页和右页的右下角，只框中间那一段会把右页那个切掉
+      - ⛔ 放大镜只能**读字**，不能拿来定位点击 —— 点击坐标一律以第 1 张全屏图为准
+      - 放大镜里读不到「N / 总数」= 当前不是正文页（封面/详情/目录/附件文件夹页），此时所有键盘翻页都无效
+
+  toggle_reading_menu:
+    goal: 在沉浸阅读模式下唤出或隐藏顶部返回箭头 + 底部工具条
+    verified: true
+    steps:
+      - do: |
+          点击**窗口正中心**（约 L+W×0.5, T+H×0.5）。
+          这是唯一可靠的切换方式：点一下唤出，再点一下隐藏。
+      - do: observe 确认左上角返回箭头 ‹ 和底部工具条是否出现
+    pitfalls:
+      - ⛔ **不要点页面边缘**：点左/右边缘会触发翻页，点顶部/底部可能点到页码或空白
+      - ⛔ **不要连续点多次**：菜单是切换式的，点两下又回去了；每次只点一下，observe 确认后再决定
+      - ⛔ 不要点正文中的图片/插图：会把图片放大成遮罩盖住整本书，后续截图全废
+      - 唤出菜单后不操作，过几秒会自动隐藏；要操作就抓紧
+
+  open_book:
+    goal: 从任意主界面打开指定的书并进入正文
+    verified: true
+    steps:
+      - do: observe 看清在哪。底部四个标签是「阅读 / 书架 / 书友 / 我」，顶部一行是搜索框（阅读页、书架页都有）
+      - do: |
+          **先走不用搜索的最短路**（一次点击就进书）：
+          · 「阅读」页左上的「本周阅读」卡片里横排着最近在读的书
+          · 「书架」页是封面网格
+          两处的封面上都直接印着书名。看得见目标书 → **直接点封面中心**。
+      - do: |
+          看不见才搜索：点顶部搜索框 → 输入书名 → 回车 → observe。
+          结果**分两组**：「在书架中搜索：<词>」在上，「在书城中搜索：<词>」在下。
+          → **优先点书架组**那条 —— 那是账号里已有的书，点开直接能读。
+      - do: 若落在书籍详情页（底部一条通栏蓝色「阅读 / 继续阅读」按钮）→ 点它 → observe
+      - do: 按 read_page_number 确认能读到「N / 总数」页码 —— 读得到才算真进了正文
+    pitfalls:
+      - ⚠️ **书城里名字高度相似的书极多**（实测搜「claude code」同时列出「Claude Code 实战」「Claude Code 橙皮书」「Claude Code 源码架构」「Claude Code 源码解析」…），只看前几个字必点错 —— 必须核对**完整书名 + 作者**
+      - 书架组的结果永远排在书城组上面；点书城组的书可能要购买/订阅，是只读任务的红线
+      - 书重新打开时停在**上次读到的位置**，不是第 1 页
+      - 详情页/封面页/目录页上键盘翻页全部无效，必须先真正进到正文
+      - 点封面时要点**封面中心区域**，点边缘可能触发翻页或其他交互
+
+  back_to_home:
+    goal: 从任意界面退回到带底部标签栏的主界面
+    verified: true
+    steps:
+      - do: observe 一次，先看清在哪；⛔ 不要在看清之前点任何东西。窗口范围 L/T/R/B 的取法见 read_page_number 第 1 步
+      - do: |
+          看**窗口**左上角（约 L+W×0.02, T+H×0.04）有没有返回箭头 ‹ —— 有就点它退一级，然后 observe
+          注意：点返回箭头的命中区域很小，要精确点在箭头符号上，点偏可能变成翻页或无反应
+      - do: 没有返回箭头就点一次**窗口正中心**（约 L+W×0.5, T+H×0.5）把菜单唤出来，再看左上角
+      - do: 重复上面两步，直到窗口底部出现那排标签（阅读 / 书架 / 书友 / 我）
+      - do: |
+          试到第 4 轮还回不去就**彻底关掉应用重启**，别在原地耗：
+          hotkey cmd+q → wait 2 秒 → activate_app com.tencent.weread → observe
+          重启后会落在首页，流程就能回到正轨。这一招只用一次。
+    pitfalls:
+      - ⛔ **返回箭头在窗口左上角，不是屏幕左上角。** 窗口通常不是全屏的，按屏幕坐标点会点到窗口外面的别的应用上（实测点 x=10,y=60 → 前台变成 Google Chrome，任务当场卡死）
+      - 这个循环里只许点两个位置：窗口左上角返回箭头、窗口正中心。点窗口右上角是最大化/关闭；点目录、书签、附件文件夹、正文里的图片都会把状态搞乱
+      - ⛔ 点中正文插图会把图片放大成遮罩盖住整本书，后续截图全废
+      - 菜单唤出后如果等太久会自动隐藏，要及时点返回箭头
+      - 返回箭头按钮很小（约 20×20 px），点偏一点都不触发；AX 吸附有时能自动校正，但别依赖
+
+  seek_to_page:
+    goal: 把书翻到指定页码
+    verified: true
+    steps:
+      - do: 按 read_page_number 流程读出当前页码 N（不读页码就翻页 = 盲翻，方向都可能是反的）
+      - do: |
+          先算**还要按几次**（不是页码差！双页对开一次翻两页，两者差一倍，混淆会永远进不了批量档）：
+          方向 = 当前页 > 目标页 ? left : right
+          按键次数 N = 向上取整( |当前页 − 目标页| ÷ 2 )
+      - do: |
+          N ≥ 5 → **批量档**，一次发满：
+          {action:"key", key:"<方向>", repeat:<min(N,8)>, repeatFrames:"last"}
+          N ≤ 4 → **精准档**，一次一按：{action:"key", key:"<方向>"}
+      - do: 每发完一批（或一下）都回去重读页码，按新的 N 决定下一批；以**读到的页码**为准，不要凭按了几下推算
+    pitfalls:
+      - 批量翻页不加 repeatFrames:"last" 的话，repeat:8 会一次回 8 张全屏图（约 1 万 token），而中间那些页根本不看
+      - 回执报「变化很小」（前后差分接近 0）= 撞到书的首页或末页了，继续按不会有任何变化
+      - ⚠️ **批量翻页可能被「前台被别的窗口抢走」打断**。回执里会写「repeat：已连续执行 M/N 次」——
+        **以 M 为准算页码，不要按你请求的 N 推算**。前台被抢时还会附一句自动恢复提示
+      - 目标页可能落在对开的左页或右页任意一侧，两边命中都算到位，不必强求落在左页
+
+verification:
+  environment: macOS 26.5.2 / 微信读书 iOS 套壳版 / 5120×2880 屏，窗口非全屏；证据来自本仓库多轮实机 trace 与截图
+  verifiedAt: 2026-08-09
+  verifiedItems: [identity, layout, page-number-position, paging-keys, pages-per-keypress, window-anchored-coordinates, toggle-reading-menu, open-book, back-to-home]
+  unverifiedItems: []
+---
+
+# 微信读书 / WeRead App Guide
+
+## 稳定身份
+
+- Bundle ID：`com.tencent.weread` / `com.tencent.wereadmac`
+- 这是 **iOS 应用套壳**：`/Applications/微信读书.app/Wrapper/WeRead.app`
+- 后果：无障碍树只有一个空壳 `AXGroup`（实测焦点恒为窗口角落的退化包装节点，
+  形如 `AXGroup · caret(51,97)`）。**`elementId` / `textTarget` 全部走不通**，
+  只能看截图估比例坐标 + 键盘。
+
+## ⛔ 坐标必须锚窗口，不能锚屏幕
+
+这是本应用**最容易致命**的一个坑，而且症状完全指不向原因。
+
+微信读书的窗口通常**不是全屏**的。observe 回执的窗口列表里有一行形如：
+
+
+方括号里是 0–1000 比例坐标 `[左,上]-[右,下]`。记作 `L / T / R / B`，`W = R−L`，`H = B−T`。
+所有位置都从这四个数算：
+
+| 目标 | 算法 |
+|---|---|
+| 左上角返回箭头 | `x ≈ L + W×0.02`，`y ≈ T + H×0.04` |
+| 窗口正中心（唤出菜单用） | `x ≈ L + W×0.50`，`y ≈ T + H×0.50` |
+| 底部标签栏 | `y ≈ T + H×0.93` 一带 |
+| 顶部搜索框 | `y ≈ T + H×0.07` 一带 |
+| 页脚页码放大镜 | `{ x: L, y: B − H×0.055, width: W, height: H×0.055 }` |
+
+**实测事故**：按屏幕坐标点「左上角」用了 `x=10, y=60` —— 那个位置在窗口**外面**，
+点中了后面的 Google Chrome，前台被抢走，整个任务当场卡死，
+而回执只报 `human_intervention_required: 前台应用已变成「Google Chrome」`，
+根本看不出是坐标锚错了参照系。
+
+## ★ 页码必须用放大镜读，直接看全屏图是读不出来的
+
+页码在**每一页的右下角**（不是居中），形如 `32 / 115`（当前页 / 总页数）。
+宽窗口是左右双页对开：左页那个落在中缝左侧（约窗口宽的 48%），右页那个落在窗口最右（约 98%）。
+所以放大镜的框**必须取整个窗口宽**，只框中间会把右页那个切掉。
+
+**为什么必须放大**：原始截图 5120×2880，发给模型前会被压到约 1371×771（约 100 万像素预算）。
+页码原本约 20px 高，压完只剩约 **5px** —— 把那张图再放大 8 倍看到的是一团马赛克，
+**信息在降采样那一步就物理销毁了，任何提示词都救不回来**。此前模型报的页码全是猜的。
+
+正确做法是 `observe` 带上 `magnify`，它从**原始分辨率帧**上裁一块放大，作为第 2 张图附上：
+
+
+宽度取**整个窗口宽**：两个页码分别贴在左页和右页的右下角，只框中间那一段会把右页那个切掉。
+框不中就把 `y` 上下挪几十再试一次。
+
+⛔ 放大镜**只能读字，不能拿来定位点击** —— 点击坐标一律以第 1 张全屏图为准。
+
+## 翻页只用键盘
+
+| 键 | 效果 |
+|---|---|
+| `right` | 下一页 |
+| `left` | 上一页 |
+
+宽窗口是双页对开，**按一次翻两页**（已多次实测验证），
+所以按键次数 N = 向上取整(页码差 ÷ 2)。
+
+⚠️ **选档位用 N（按键次数），不是页码差。** 两者差一倍 —— 拿页码差去比阈值，
+或者拿 N 去比一个按页码差定的阈值，都会让批量档几乎永远进不去。
+`N ≥ 5` 走批量（`repeat` 一次发满），`N ≤ 4` 一次一按。
+
+判断有没有翻动看回执里的**前后差分变化率**：实测真翻动是 **15%~26%**，
+撞到书的首页/末页是**精确的 0.00**，两者泾渭分明，可以直接当判据用。
+
+**不要用鼠标翻页。** 进了正文之后点击只有坏处：会唤出菜单、会点中插图把它放大成遮罩
+盖住整本书、会点中正文里的链接。方向键翻页零副作用。
+
+想快速翻很多页时用 `repeat`（上限 8）批量连发，并且**必须加 `repeatFrames:"last"`** ——
+不加的话 `repeat:8` 会一次回 8 张全屏图（约 1 万 token），而中间翻过的页根本不看。
+
+## ★ 沉浸阅读模式与菜单唤出
+
+进入书籍正文后默认进入**沉浸阅读模式**：
+
+- 满屏正文，没有标题栏、没有底部标签栏、没有返回箭头
+- 左右双页对开（宽窗口），每页右下角有页码
+- 所有 UI 控件全部隐藏
+
+**唤出菜单的唯一方式：点击窗口正中心**
+
+- 点一下 → 顶部返回箭头 + 底部工具条同时出现
+- 再点一下 → 同时隐藏（切换式）
+- 唤出后不操作，过几秒会自动隐藏
+
+底部工具条从左到右大致包含：目录/书签按钮、主题切换、字体大小、Ai 按钮等。
+顶部工具栏左侧是返回箭头 ‹，右侧有分享、目录、设置等图标。
+
+**点击位置的注意事项：**
+
+- ✅ 点窗口正中心（W×0.5, H×0.5）附近的正文文字区域 —— 最稳妥
+- ❌ 不要点左/右边缘 —— 会触发翻页
+- ❌ 不要点正文中的图片 —— 会把图片放大成全屏遮罩
+- ❌ 不要连续点多次 —— 菜单是切换的，点两下又回去了
+
+## 界面状态与出入口
+
+- **沉浸阅读模式**：满屏正文，没有标题栏、没有底部标签栏、没有返回箭头。
+  点一次**窗口正中心**把菜单唤出来，左上角的返回箭头才会出现。
+- **首页（「阅读」标签）**：顶部通栏搜索框；左上角「本周阅读」卡片里横排着最近在读的书。
+- **书架页**：封面网格，书名印在封面上。看得见目标书就**直接点封面**，一次点击进书 ——
+  这是最短路径。搜索是后备：点框 + 输入 + 回车 + 挑结果，四个来回，一步偏就容易开始乱试。
+- **搜索结果页**：分「在书架中搜索」（在上，账号里已有的书）和「在书城中搜索」（在下）两组，
+  优先点书架组。书城组里名字高度相似的书极多，只看前几个字必点错。
+- **书籍详情页**：底部一条通栏蓝色「阅读 / 继续阅读」按钮，点它进正文。
+- **书重新打开时停在上次读到的位置**，不要假设在第 1 页。
+- **前置附件 / 文件夹页**（如「XX 9MB，3个项目」的蓝色文件夹图标页）：
+  实测 `right/left/up/down/pageup/pagedown/space/return/tab` 和 `scroll` **全部 0.0%**，
+  键盘在这类页面上完全无效。判据很简单：**放大镜里读不到「N / 总数」页码，就不是正文页**，
+  得先靠返回箭头退出去、重新从书架进正文。
+
+## 返回首页的完整流程
+
+从沉浸阅读模式返回首页，标准操作序列：
+
+1. **observe** 确认当前在正文页（能看到双页正文，但看不到返回箭头和底部标签栏）
+2. 点击**窗口正中心**唤出菜单 → observe 确认左上角返回箭头出现
+3. 点击**窗口左上角返回箭头** ‹ → observe
+4. 确认底部出现「阅读 / 书架 / 书友 / 我」标签栏 = 回到首页
+
+如果第 3 步点完还在二级页面（如详情页、搜索结果页），继续点左上角返回箭头，直到底部标签栏出现。
+
+**关键口诀：中心唤菜单，左上角返回。**
+
+## 只读边界
+
+微信读书在自动化里应当按**只读**对待：不点「购买」「订阅」「分享」「赠一得一」「加入书架」
+这类按钮。翻页、截图、读页码都不改变书的任何状态（阅读进度会前进，这是可接受的副作用）。
+
+## 实测记录
+
+- 2026-08-09 · 沉浸模式唤出菜单：从「阅读」页点击本周阅读中的《Claude Code 源码解析》封面，进入沉浸阅读模式，满屏无 UI。点击窗口正中心后，顶部返回箭头和底部工具条同时出现，AX 吸附自动识别到「返回」按钮。再次点击中心后菜单隐藏。
+- 2026-08-09 · 返回流程验证：在沉浸阅读模式下，点中心唤出菜单 → 点左上角返回箭头 → 成功回到「阅读」首页，底部四格标签栏可见。
+- 2026-08-09 · bundleId 补充：macOS 桌面端微信读书的 bundleId 同时存在 `com.tencent.weread` 和 `com.tencent.wereadmac` 两种，match 列表中均已收录。
+- 2026-08-06 · 页码位置与放大镜读数：窗口 `[36,44]-[932,862]`，
+  `magnify {x:36, y:817, width:896, height:45}` 裁出 4588×130 的横条，
+  页码 `81 / 116`、`84 / 115` 清晰可读。同一处在模型看到的全屏图上是约 5px 的马赛克。
+- 2026-08-06 · 翻页键：连按 3 次 `right`，书从 15/106 翻到 21/106（6 页），
+  逐次前后差分 0.151 / 0.209 / 0.241。撞到书末后连续 10 次 `right` 全部精确 0.00。
+- 2026-08-06 · 坐标锚参照系：按屏幕坐标点 `x=10,y=60` 找返回箭头 → 前台变成 Google Chrome。
+  按窗口算 `(33,82)`（窗口 `[20,48]-[916,864]`，即 `L+W×0.014, T+H×0.042`）一次命中。
+- 2026-08-06 · 书架进书：停在书架页时，`observe → 点封面` 两个动作即进入正文。
+  同一任务停在【发现】页时改走搜索，用了 `click → return → click → hotkey×2 → type×3 →
+  click → click失败 → 重新激活 → click → click` 共十余个动作仍未进书。

package/plugins/computer_use/commands/computeruse.md

@@ -0,0 +1,25 @@
+---
+description: Computer Use 状态、权限体检、应用说明书、遥测与审计
+argument-hint: "[doctor|apps|app <name>|capture [name] [--write]|report|audit [n]|observe]"
+---
+
+# /computeruse
+
+由 computer-use 插件接管（plugin.ts.runCommand），**全部子命令都是确定性的**，
+不经过 LLM。
+
+| 子命令 | 作用 |
+|---|---|
+| （空） | 总览：平台、守护进程、权限、能力三态分组、说明书写入目录 |
+| `doctor` | 权限体检 + 逐项修复指引 |
+| `apps` | 列出所有应用说明书、冲突，并指出当前前台应用命中哪一份 |
+| `app <name>` | 打印某份说明书的摘要与校验报告 |
+| `capture [name] [--write]` | 观测当前前台应用生成说明书草稿；默认只打印，`--write` 才落盘（写前确认、不覆盖已有文件） |
+| `observe` | 跑一次观测，结果直接给你看 |
+| `report` | 遥测汇总 |
+| `audit [n]` | 守护进程审计流水 + 不可逆授权记录（两份并排，不合并） |
+
+`/cu` 是等价别名。
+
+**注意**：真正操作桌面用 `ComputerUse` 工具，不是这些命令。这里只做诊断与知识
+管理——命令是给人用的，工具是给模型用的。

package/plugins/computer_use/commands/cu.md

@@ -0,0 +1,9 @@
+---
+description: /computeruse 的简写别名
+argument-hint: "[doctor|apps|app <name>|capture [name] [--write]|report|audit [n]|observe]"
+---
+
+# /cu
+
+`/computeruse` 的等价别名，由同一个 `plugin.ts.runCommand` 分发。
+完整说明见 `/computeruse`。

package/plugins/computer_use/plugin.js

@@ -0,0 +1,26 @@
+/**
+ * ============================================================
+ *  plugins/computer_use/plugin.ts —— computer-use 插件入口
+ * ------------------------------------------------------------
+ *  两件事：
+ *   ① `app/` 下的应用说明书 —— 由内核 `vision/appGuide.ts::appManualProviders`
+ *      按目录约定发现，**不经过本文件**。工具在每次观测时强制注入，
+ *      模型没有「不看」这个选项。
+ *   ② `/computeruse`（别名 `/cu`）—— 确定性的诊断与知识管理命令面。
+ *
+ *  刻意不实现 `activate()`：本插件没有需要在宿主启动时常驻的东西。
+ * ============================================================
+ */
+import { handleComputerUseCommand } from './src/commands.js';
+const api = {
+    async *runCommand(commandName, args, ctx) {
+        if (commandName !== 'computeruse' && commandName !== 'cu') {
+            yield { type: 'error', error: `computer-use: 未知命令 /${commandName}` };
+            return;
+        }
+        const text = await handleComputerUseCommand(args, ctx.signal);
+        yield { type: 'text', delta: text };
+        yield { type: 'turn_done' };
+    },
+};
+export default api;

package/plugins/computer_use/plugin.ts

@@ -0,0 +1,30 @@
+/**
+ * ============================================================
+ *  plugins/computer_use/plugin.ts —— computer-use 插件入口
+ * ------------------------------------------------------------
+ *  两件事：
+ *   ① `app/` 下的应用说明书 —— 由内核 `vision/appGuide.ts::appManualProviders`
+ *      按目录约定发现，**不经过本文件**。工具在每次观测时强制注入，
+ *      模型没有「不看」这个选项。
+ *   ② `/computeruse`（别名 `/cu`）—— 确定性的诊断与知识管理命令面。
+ *
+ *  刻意不实现 `activate()`：本插件没有需要在宿主启动时常驻的东西。
+ * ============================================================
+ */
+
+import type { PluginApi } from '../../src/plugin-sdk.js';
+import { handleComputerUseCommand } from './src/commands.js';
+
+const api: PluginApi = {
+  async *runCommand(commandName, args, ctx) {
+    if (commandName !== 'computeruse' && commandName !== 'cu') {
+      yield { type: 'error', error: `computer-use: 未知命令 /${commandName}` };
+      return;
+    }
+    const text = await handleComputerUseCommand(args, ctx.signal);
+    yield { type: 'text', delta: text };
+    yield { type: 'turn_done' };
+  },
+};
+
+export default api;

package/plugins/computer_use/src/capture.js

@@ -0,0 +1,90 @@
+/**
+ * ============================================================
+ *  plugins/computer_use/src/capture.ts —— 把一次真实观测沉淀成说明书草稿
+ * ------------------------------------------------------------
+ *  这条命令存在的理由是**闭环**：说明书里绝大多数内容目前是从面向人的文档
+ *  转写来的、没实机跑过。没有采集入口，「观察真实 App → 生成草稿 → 实机
+ *  校验 → 沉淀」这个提升成功率的循环就断在第一步。
+ *
+ *  ★ 采集与写盘都在内核门面（`computerUseDiagnostics`）里：写盘要用户确认 +
+ *    原子写，若留在插件里，插件就得直接 import askBridge 与文件 API ——
+ *    刚收窄的 SDK 会立刻从别的路径重新变宽。本文件只负责**编排与呈现**。
+ *
+ *  ★ 默认只打印。`--write` 才落盘，因为这是往用户项目里放文件。
+ * ============================================================
+ */
+import { computerUseDiagnostics } from '../../../src/plugin-sdk.js';
+/**
+ * 解析 `capture [name] [--write]`。
+ *
+ * 名字可省：省了就由内核按前台应用的 bundleId 末段推。显式给名字的场景是
+ * 「我知道这份该叫什么」，比如已有 `wechat.md` 想重采一份对照。
+ */
+export function parseCaptureArgs(raw) {
+    const parts = raw.trim().split(/\s+/).filter(Boolean);
+    const write = parts.includes('--write');
+    const name = parts.find((part) => !part.startsWith('--'));
+    return { ...(name ? { name } : {}), write };
+}
+export async function runCapture(raw, signal) {
+    const args = parseCaptureArgs(raw);
+    const draft = await computerUseDiagnostics.captureDraft(args.name, signal);
+    // 内核在无法采集时返回一句人话（平台不支持 / 权限不足 / 拿不到前台应用），
+    // 不抛异常也不返回半个草稿 —— 「采不到」和「采到了但内容少」是两回事。
+    if (typeof draft === 'string')
+        return `# 采集说明书草稿\n\n${draft}`;
+    const sections = [
+        `# 采集说明书草稿：${draft.name}`,
+        '',
+        ...renderWarnings(draft),
+        ...(args.write ? await renderWriteResult(draft, signal) : renderPreview(draft)),
+    ];
+    return sections.join('\n');
+}
+function renderWarnings(draft) {
+    if (draft.warnings.length === 0)
+        return [];
+    return ['## 采集时的情况', '', ...draft.warnings.map((warning) => `- ${warning}`), ''];
+}
+function renderPreview(draft) {
+    return [
+        '## 草稿',
+        '',
+        '```markdown',
+        draft.markdown.trimEnd(),
+        '```',
+        '',
+        '## 下一步',
+        '',
+        // 说清楚它是什么、不是什么。草稿看起来很像成品，这句话是防止它被当成成品。
+        '这份草稿里**只有应用身份是实测的**：控件候选来自采集当时的 AX 树、未经验证，',
+        '界面分区与典型流程是空的（一次观测看不出它们，编出来的比空着更糟）。',
+        '**不可逆动作清单也是空的** —— 屏幕上看不出「哪个动作收不回来」，那是产品语义，',
+        '必须由人补全；留空等于这个应用没有任何不可逆防护。',
+        '',
+        `想直接落盘到 \`${computerUseDiagnostics.manualDir()}\`，重跑一次并加 \`--write\`：`,
+        '',
+        `    /computeruse capture ${draft.name} --write`,
+    ];
+}
+async function renderWriteResult(draft, signal) {
+    const result = await computerUseDiagnostics.writeManualDraft(draft, signal);
+    if (result.ok) {
+        return [
+            '## 已写入',
+            '',
+            `✅ ${result.path}`,
+            '',
+            '它现在会被 `/computeruse apps` 与 ComputerUse 工具一起加载。',
+            '**请立刻补全 frontmatter 里的 `irreversible:` 清单** —— 空清单意味着这个应用',
+            '的任何操作都不会触发不可逆确认。',
+        ];
+    }
+    return [
+        '## 未写入',
+        '',
+        `❌ ${result.error}`,
+        '',
+        '草稿没有丢：去掉 `--write` 重跑一次就能拿到完整内容自己保存。',
+    ];
+}

package/plugins/computer_use/src/capture.ts

@@ -0,0 +1,104 @@
+/**
+ * ============================================================
+ *  plugins/computer_use/src/capture.ts —— 把一次真实观测沉淀成说明书草稿
+ * ------------------------------------------------------------
+ *  这条命令存在的理由是**闭环**：说明书里绝大多数内容目前是从面向人的文档
+ *  转写来的、没实机跑过。没有采集入口，「观察真实 App → 生成草稿 → 实机
+ *  校验 → 沉淀」这个提升成功率的循环就断在第一步。
+ *
+ *  ★ 采集与写盘都在内核门面（`computerUseDiagnostics`）里：写盘要用户确认 +
+ *    原子写，若留在插件里，插件就得直接 import askBridge 与文件 API ——
+ *    刚收窄的 SDK 会立刻从别的路径重新变宽。本文件只负责**编排与呈现**。
+ *
+ *  ★ 默认只打印。`--write` 才落盘，因为这是往用户项目里放文件。
+ * ============================================================
+ */
+
+import { computerUseDiagnostics, type ManualDraft } from '../../../src/plugin-sdk.js';
+
+export interface CaptureArgs {
+  name?: string;
+  write: boolean;
+}
+
+/**
+ * 解析 `capture [name] [--write]`。
+ *
+ * 名字可省：省了就由内核按前台应用的 bundleId 末段推。显式给名字的场景是
+ * 「我知道这份该叫什么」，比如已有 `wechat.md` 想重采一份对照。
+ */
+export function parseCaptureArgs(raw: string): CaptureArgs {
+  const parts = raw.trim().split(/\s+/).filter(Boolean);
+  const write = parts.includes('--write');
+  const name = parts.find((part) => !part.startsWith('--'));
+  return { ...(name ? { name } : {}), write };
+}
+
+export async function runCapture(raw: string, signal?: AbortSignal): Promise<string> {
+  const args = parseCaptureArgs(raw);
+  const draft = await computerUseDiagnostics.captureDraft(args.name, signal);
+
+  // 内核在无法采集时返回一句人话（平台不支持 / 权限不足 / 拿不到前台应用），
+  // 不抛异常也不返回半个草稿 —— 「采不到」和「采到了但内容少」是两回事。
+  if (typeof draft === 'string') return `# 采集说明书草稿\n\n${draft}`;
+
+  const sections = [
+    `# 采集说明书草稿：${draft.name}`,
+    '',
+    ...renderWarnings(draft),
+    ...(args.write ? await renderWriteResult(draft, signal) : renderPreview(draft)),
+  ];
+  return sections.join('\n');
+}
+
+function renderWarnings(draft: ManualDraft): string[] {
+  if (draft.warnings.length === 0) return [];
+  return ['## 采集时的情况', '', ...draft.warnings.map((warning) => `- ${warning}`), ''];
+}
+
+function renderPreview(draft: ManualDraft): string[] {
+  return [
+    '## 草稿',
+    '',
+    '```markdown',
+    draft.markdown.trimEnd(),
+    '```',
+    '',
+    '## 下一步',
+    '',
+    // 说清楚它是什么、不是什么。草稿看起来很像成品，这句话是防止它被当成成品。
+    '这份草稿里**只有应用身份是实测的**：控件候选来自采集当时的 AX 树、未经验证，',
+    '界面分区与典型流程是空的（一次观测看不出它们，编出来的比空着更糟）。',
+    '**不可逆动作清单也是空的** —— 屏幕上看不出「哪个动作收不回来」，那是产品语义，',
+    '必须由人补全；留空等于这个应用没有任何不可逆防护。',
+    '',
+    `想直接落盘到 \`${computerUseDiagnostics.manualDir()}\`，重跑一次并加 \`--write\`：`,
+    '',
+    `    /computeruse capture ${draft.name} --write`,
+  ];
+}
+
+async function renderWriteResult(
+  draft: ManualDraft,
+  signal?: AbortSignal,
+): Promise<string[]> {
+  const result = await computerUseDiagnostics.writeManualDraft(draft, signal);
+  if (result.ok) {
+    return [
+      '## 已写入',
+      '',
+      `✅ ${result.path}`,
+      '',
+      '它现在会被 `/computeruse apps` 与 ComputerUse 工具一起加载。',
+      '**请立刻补全 frontmatter 里的 `irreversible:` 清单** —— 空清单意味着这个应用',
+      '的任何操作都不会触发不可逆确认。',
+    ];
+  }
+  return [
+    '## 未写入',
+    '',
+    `❌ ${result.error}`,
+    '',
+    '草稿没有丢：去掉 `--write` 重跑一次就能拿到完整内容自己保存。',
+  ];
+}