# dsh-browser-kit 工具使用规范

> 适用对象：**调用本插件 `browser_*` 工具的 Agent**（以及二次开发者）。
> 规范一经列入即**硬性**：违反会被工具结果回显提醒，并可能在评审中打回。

---

## 规范 1（硬性）：自持浏览器默认**小窗静默操作**，非必要不开大窗

**要求**
1. Agent 调用自持浏览器（`browser_agent_window`）时，**一律在 collapsed 小窗内完成自动化**：
   `open` / `navigate` / 点击、取文本、`browser_find` / `browser_snapshot` / 表单操作 / 批注等，
   **都不需要展开**。
2. **要看全貌请用 `op=screenshot`** —— 它内部会临时展开、截图、再自动收回小窗（Agent 无需自己 expand）。
3. **只有两种情况**才允许 `op=expand`：
   - ① **用户明确要求**看大窗；
   - ② 必须**交互式**操作小窗装不下的内容（例如用户要手动在窗口里操作）。
   且**必须传 `reason`** 说明为什么小窗不行。
4. 展开后**用毕立即 `op=collapse`** 收回小窗。

**落地位置（三重）**
| 位置 | 内容 |
|---|---|
| 工具 description | `browser_agent_window` 的描述**开头**即是本规范（模型每次都能看到） |
| 工具结果回显 | `op=expand` 的结果里带 `notice`：未传 `reason` ⇒ 明确标为**违规**；带了 ⇒ 确认合规并提醒用毕收回 |
| 文档 | 本文件 + `README.md`「工具使用规范」 + `docs/browser-capability-assessment.md` §3.9.32 |

**为什么是硬性**：自持窗口是**和用户共处一屏**的协作面（用户可能正在同一窗口里手动操作）；
大窗会遮挡页面内容、抢占用户的视觉焦点。小窗静默 + 截图取全貌，已经覆盖自动化所需的全部能力。

**自检清单（Agent 每次调用前）**
- [ ] 我这次调用需要"看见"页面吗？—— 需要 ⇒ 用 `op=screenshot`，不要 expand。
- [ ] 我是否只是"觉得大窗方便"？—— 是 ⇒ 不展开（这是最常见的违规动机）。
- [ ] 如果确实 expand：`reason` 写了吗？用毕 `collapse` 了吗？

---

## 规范 2（硬性）：**账号与密码等凭据不可被 Agent 读取，也不得进入上下文**

**要求**（2026-10-10 用户明确）：「保存的密码和信息**不给 Agent 所读，不进入上下文**」。

**实现边界（可回归检查，见 `test/credential-manager.test.mjs`）**
| 约束 | 落地 |
|---|---|
| 存储位置 | **仅 GUI 文档的 `localStorage`**（键 `dsh-kit-credentials`）——**不落工作区、不落 `plugin/.data/`**（Agent 用文件工具能读到的位置一律不写） |
| 可达面 | 凭据模块**不调用任何 host 服务**、**不写文件**、**不进 `kit-status`**、**不进批注/交付管线** ⇒ 无法经任何工具返回值或注入消息到达模型 |
| 采集 | 只有**手动添加**与**用户点击填充**；**不自动抓取页面密码**、不自动提交表单 |
| 展示 | 列表中密码默认掩码 `••••••••`，**点击才显示** |
| 诚实声明 | 这**不是**强加密（本机其它程序仍可读 GUI 的 localStorage）；保证的是「不进 Agent 上下文 / 不进工具返回值」这一条，不得对外宣称"加密保险箱" |

**Agent 侧纪律**：不得试图通过任何工具/脚本读取上述存储；若用户要求"看看我保存的密码"，应答**请用户自己在钥匙面板查看**（面板仅本机可见）。

## 规范 3（沿用既有约定）：不在用户输入框写任何文字
`primeSessionInput` 类操作**不得**用于自动化输出（用户明确要求「不要带文字」）：
需要让 Agent 读到的信息走**工具结果 / 落盘文件**，不写用户的输入框。（pitfalls **P89**）

---

## 规范 4（沿用既有约定）：操作前先核对"落点"

涉及多窗口/多面板的操作，先用 `browser_tabs` / `browser_agent_window op=status` 核对目标；
报告"功能没生效"之前先证明**操作确实落在目标对象上**（pitfalls **P95**）。

---

## 变更方式

新增/修改规范：改本文件 + 相应工具 description + 一条回归钉子（`test/tool-usage-rules.test.mjs`），
并在 `pitfalls.md` 记录动机。规范是**可检查的产物**，不是口头约定。