# WorkGround2 使用指南

<a href="../README.zh-CN.md">README</a>
&nbsp;·&nbsp;
<a href="./GUIDE.md">English</a>
&nbsp;·&nbsp;
<a href="./SPEC.md">规格</a>

> 日常配置与使用。工程契约与内部实现（数据类型、registry、包结构、路线图）见
> **[规格 SPEC.md](./SPEC.md)**。

## 目录

- [配置](#配置)
- [环境变量](#环境变量)
- [Serve Web 前端](#serve-web-前端)
- [配置路径](./CONFIG_PATHS.zh-CN.md)
- [思考语言](./REASONING_LANGUAGE.zh-CN.md)
- [自定义 OpenAI-compatible provider](#自定义-openai-compatible-provider)
- [桌面端 Hooks](./DESKTOP_HOOKS.zh-CN.md)
- [快捷键](#快捷键)
- [权限与沙盒](#权限与沙盒)
- [插件（MCP）](#插件mcp)
- [斜杠命令](#斜杠命令)
- [@ 引用](#-引用)
- [双模型协同](#双模型协同)
- [能力辅助（Capability Assist）](#能力辅助capability-assist)

## 配置

优先级：**flag > `./WorkGround2.toml` > 用户配置文件 > 内置默认值**。从
**WorkGround2 v1.8.1** 开始，用户配置位于 macOS/Linux 的
`~/.WorkGround2/config.toml`，Windows 为 `%AppData%\WorkGround2\config.toml`；迁移和相关数据路径见
[配置路径](./CONFIG_PATHS.zh-CN.md)。标注为“仅用户/全局”的字段（包括 agent 轮数上限）不会被 `./WorkGround2.toml` 覆盖。
Provider 通过 `api_key_env` 命名密钥，真实密钥值保存在 CLI 与桌面端共用的
WorkGround2 全局 `<WorkGround2 home>/.env`。项目 `.env`、home `.env`、继承的 shell 环境变量、旧 credentials 和系统 keyring 都不再作为 provider key 的运行时 fallback；旧凭据只作为迁移来源读取。项目 `.env` 仍会作为当前 workspace 范围内的 MCP/plugin 非 provider `${VAR}` 展开来源，但不会导入 provider key 或 WorkGround2 控制变量。全局 `config.toml` 和 `.env` 的完整结构见
[配置路径](./CONFIG_PATHS.zh-CN.md)。

桌面端和 CLI 端的可见思考语言设置，见 [思考语言](./REASONING_LANGUAGE.zh-CN.md)。
桌面端 Hooks 的 JSON 配置、事件 key 和 payload 字段，见 [桌面端 Hooks](./DESKTOP_HOOKS.zh-CN.md)。
`SessionStart` hook 可通过 stdout 或 `hookSpecificOutput.additionalContext` 把插件/工作流 bootstrap 内容一次性注入下一轮真实用户输入上下文，而不是写入稳定 system prompt。

```toml
default_model = "deepseek-flash"   # 执行器；设 [agent].planner_model 可加规划器
# language    = "zh"               # 界面语言；为空则按 $LANG / $WorkGround2_LANG 自动检测

[ui]
# shortcut_layout = "desktop"      # classic|desktop；兼容旧配置
# cursor_shape = "underline"       # block|underline|bar；CLI/TUI 输入光标

[agent]
max_steps = 0                    # 仅用户/全局；执行器工具调用轮数；0 表示不限
planner_max_steps = 0            # 仅用户/全局；规划器只读工具调用轮数；0 表示不限
reasoning_language = "auto"      # 可见思考过程语言：auto|zh|en
# plan_mode_allowed_tools = ["custom_reader"]   # 仅声明额外只读自定义工具；
#                                                # 不能解锁被计划模式阻断的工具或 unsafe bash
# planner_model = "deepseek-pro"      # 可选的低频规划器
# subagent_model = "deepseek-pro"     # runAs=subagent skill 的默认模型
# subagent_models = { review = "deepseek-pro", security_review = "deepseek-pro" }
# max_subagent_depth = 2              # 子代理嵌套委派深度；设为 1 可恢复旧的单层边界
auto_plan = "off"                  # 仅用户级生效；off|on；off 表示计划模式仅手动开启
# auto_plan_classifier = "deepseek-flash"   # 可选；只在边界任务上调用
tool_result_snip_ratio = 0.6       # 在摘要 compaction 前先缩短旧工具输出

[[providers]]
name        = "deepseek-flash"
kind        = "openai"
base_url    = "https://api.deepseek.com"
model       = "deepseek-v4-flash"
api_key_env = "DEEPSEEK_API_KEY"
# 还有预设：deepseek-pro

[tools]
enabled = []   # 省略/为空 = 全部内置工具
bash_timeout_seconds = 120   # 前台安全上限；设为 0 表示不设工具层超时
mcp_call_timeout_seconds = 300   # MCP 调用默认安全上限；可用 plugin/tool 覆盖

[tools.browser]
enabled = true
kind = "auto"                    # auto|chrome|edge|chromium|chrome_for_testing
# executable_path = "C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe"
headless = false
idle_timeout_seconds = 0   # 0 = 永不因空闲自动关闭；30..86400 表示正数生命周期
incognito = false          # true 后新建浏览器进程以隐身模式（incognito）启动

[environment]
enabled = true   # 启动时把 OS、shell 和常见工具摘要稳定注入 prompt
# [environment.tools]
# go = "/opt/homebrew/bin/go"   # 可选：显式可信路径；workspace 内路径不会在启动时自动执行

[skills]
# paths = ["~/my-skills", "../shared/skills"]   # 额外的自定义技能目录
# excluded_paths = ["~/.agents/skills"]         # 隐藏约定来源，不删除目录
# disabled_skills = ["review"]                  # 隐藏技能，直到 /skill enable <name>

[permissions]
mode  = "ask"                                # 无规则命中时 writer 的兜底：ask|allow|deny
deny  = ["Bash(rm -rf*)", "Bash(git push*)"] # 任何模式下都硬阻断
allow = ["Bash(go test:*)"]                  # 从不询问

[sandbox]
# workspace_root = ""          # 文件写工具被限制在此目录；留空 = 当前目录
# allow_write    = ["/tmp"]    # write_file/edit_file/multi_edit/move_file 额外可写的目录
# forbid_read    = ["${HOME}/.ssh"]   # agent 不可读取或列出的目录

[serve]
auth_mode = "none"             # none|token|password；绑定到非 localhost 前请先开启认证
# token = ""                   # 可选固定 token；token 模式为空时启动时自动生成
# password_hash = ""           # 用 WorkGround2 serve --hash-password --password '...' 生成
# behind_proxy = false         # 只在可信反向代理后方设为 true

[[plugins]]
name    = "example"
command = "WorkGround2-plugin-example"
call_timeout_seconds = 600   # 可选：单个 MCP server 的调用超时
tool_timeout_seconds = { "generate_video" = 1800 }   # 可选：raw MCP tool 名称
```

完整 schema 与每个字段的契约见 [`SPEC.md` §5](./SPEC.md#5-configuration-toml)。

### 原生浏览器工具

默认 full 工具面包含 `browser_open`、`browser_attach`、`browser_navigate`、`browser_state`、
`browser_click`、`browser_type`、`browser_scroll`、`browser_tab`、`browser_upload`、
`browser_close` 十个工具。第一优先支持 Google Chrome；Edge、Chromium、Chrome for Testing
通过同一套 Chrome DevTools Protocol 兼容。浏览器只在第一次 `browser_open`
时发现并启动，因此机器未安装受支持浏览器也不影响 WorkGround2 启动，失败会在打开时显式返回。

每个用户共享一个持久化自动化浏览器，跨 Controller、Task、设置重建和应用重启复用。它使用独立的
自动化 Profile（绝非默认 Chrome Profile），并把回环 CDP endpoint 元数据写入稳定的每用户运行时文件。
`browser_open` 在记录校验通过时 attach 到已运行的浏览器，仅在首次使用时启动可脱离 WorkGround2 进程
继续存活的 Chromium。Session 关闭和调用 `browser_close` 只分离该 Session 的 CDP 客户端并释放内存资源，
不会退出共享 Chromium、不删除其持久 Profile 或有效 endpoint 记录；空闲回收只在配置了正数
`idle_timeout_seconds`（30..86400）时生效，默认 `0` 表示永不因空闲自动关闭，且即使触发也只分离客户端。
V1 读取页面文本和带编号交互元素，明确不提供截图、下载、拖放、目录上传或视觉坐标定位。
`browser_type` 只用于普通文本：工具参数会进入会话记录，因此除非你确实希望被记录，否则不要传入密码、
API key、token 等秘密。密码输入和本地文件上传各自有 `[tools.browser]` 下的独立开关 ——
`allow_password_input` 与 `allow_file_upload`（默认均 `true`，显式 `false` 关闭）；
关闭任一会把对应操作在到达浏览器之前硬拒绝，且不影响另一项。`browser_upload` 可向
`input[type=file]` 设置 1-20 个存在的本地普通文件（多文件目标要求 `multiple` 属性）；
上传的文件路径会原样进入 ToolCall transcript，且文件内容会交给页面，因此不要用它上传机密文件。
file 输入框始终不接受 `browser_type`。

`browser_attach` 返回当前 Session 的回环 CDP endpoint，供 Playwright `chromium.connectOverCDP()`
使用；必须先 `browser_open`，绝不启动第二个浏览器。任何 Playwright 写操作后必须调用
`browser_state(refresh=true)` —— 旧 `revision` 已失效，CDP invalidation 继续生效，原生
`browser_state` 仍是 DOM/AX 摘要和 revision 的单一可信源。endpoint 绝不暴露 PID、Profile 路径或凭据，
Playwright 断连不会退出浏览器。

浏览器启动偏好由 `[tools.browser].incognito` 控制（默认 `false`，显式 `true` 开启）：
开启后新建的 Chrome/Edge/Chromium 进程以 Chromium 隐身模式（incognito）启动，不保留该会话的
历史与 Cookie。它是启动配置而非权限。Desktop 保存设置时只重建并分离控制端，已运行的共享浏览器
继续保持原启动模式；该浏览器自行退出或 endpoint 失效后，下一次新建才使用更新后的模式。

运行时已经为后续 managed Profile、经用户明确授权连接日常 Chrome、复用 Cookie/登录态和密码库填充
预留 ProfileProvider/CredentialProvider 边界；V1 不启用这些能力，也不会把 managed/attach 请求静默降级为
临时 Profile。关闭 `[tools.browser].enabled`、通过 `tools.enabled` 筛掉浏览器工具或启用 token economy
都会隐藏这组工具。revision/request_id 规则见[工具合约](./TOOL_CONTRACT.zh-CN.md)。

每个启动的浏览器都在新选的随机非零回环端口（`127.0.0.1:<port>`）暴露 DevTools endpoint，替代 port=0 的自动化信号；endpoint 绝不绑定非回环接口，其元数据以 0600、临时文件+rename 原子写入每用户运行时文件且绝不进入日志。这移除的是一个标准自动化信号——可见（非 headless）浏览器不再因为端口而报告 `navigator.webdriver === true`——但它不是反检测保证：网站仍可通过其他手段识别自动化，且 headless 模式仍会报告 `navigator.webdriver === true`，因此不承诺任何 stealth 效果。Chrome 136 起远程调试要求非默认 `--user-data-dir`；WorkGround2 总是使用独立自动化 Profile 启动，该要求天然满足。

`[agent].plan_mode_allowed_tools` 用于把 WorkGround2 无法自动分类的自定义/外部工具声明为额外只读工具。
对 MCP/plugin 工具，像 `mcp__github__issue_read` 这样的具体模型可见名也会把该工具提升为
planner / read-only research 可用的可信只读工具。优先使用 MCP 只读信任的一次性确认；需要预置已审过工具时，
再在 plugin 上写 `trusted_read_only_tools`，`plan_mode_allowed_tools` 保留为兼容逃生阀。它不再解锁 `bash`、`task`、
写文件工具、安装器、记忆变更工具等计划模式已知阻断项，也不会绕过 bash 在计划模式下的安全检查。

### 环境变量

多数日常设置应写在 `config.toml` 或前文提到的 WorkGround2 全局 `.env` 中。下面这些变量是进程级高级开关；
需要在启动 WorkGround2 之前设置。项目 `.env` 不是 WorkGround2 控制变量的运行时来源。

`WorkGround2_MEMORY_COMPILER_LLM_CLASSIFICATION=true` 会为 Memory v5 启用可选的 LLM 任务/聊天分类器。
默认关闭，此时 WorkGround2 使用本地 heuristic classifier，不会产生额外 provider 调用。开启后，分类缓存未命中时，
WorkGround2 可能先通过已配置 provider 发送一个很小的分类请求，再决定用户输入是任务还是普通对话；这会增加少量延迟、
provider 用量和 token 成本。分类结果会在单个 session 内短时间缓存。只有去掉首尾空白后精确等于 `true`
才会启用；未设置、`false`、`1`、`TRUE` 都会保持默认 heuristic 路径。

```bash
WorkGround2_MEMORY_COMPILER_LLM_CLASSIFICATION=true WorkGround2
```

开发运行时，把变量放在启动进程的命令前，例如：

```bash
WorkGround2_MEMORY_COMPILER_LLM_CLASSIFICATION=true wails dev -forcebuild
```

从系统图形界面直接启动的打包桌面端通常不会继承交互式终端里的环境变量；如果确实要开启这个高级开关，
请从受环境变量管理的启动方式打开应用。

## Serve Web 前端

`WorkGround2 serve` 会用同一个本地 WorkGround2 引擎启动浏览器 UI。适合不安装桌面端但想用可视化界面、
在远程开发机上通过 tunnel 使用，或把当前会话临时共享给浏览器查看的场景。

```bash
cd your-project
WorkGround2 serve
# 打开 http://127.0.0.1:8787
```

默认监听 `127.0.0.1:8787`，认证模式是 `auth_mode = "none"`。这个默认值只适合本机使用。
如果要绑定到非 loopback 地址、通过 tunnel 暴露，或放到反向代理后面，请先开启认证再分享 URL：

```bash
WorkGround2 serve --auth token
WorkGround2 serve --addr 0.0.0.0:8787 --auth token
WorkGround2 serve --auth password --password 'temporary-password'
```

Token 模式会在终端打印带 `?token=...` 的分享链接；可通过 `--token` 或 `[serve].token`
复用固定 token。Password 模式必须在启动时传 `--password`，或在配置里保存 bcrypt hash：

```bash
WorkGround2 serve --hash-password --password 'strong-password'

# ~/.WorkGround2/config.toml
[serve]
auth_mode = "password" # none|token|password
password_hash = "$2a$12$..."
behind_proxy = true    # 仅可信反向代理后方使用
```

Web UI 提供聊天、工具审批、会话历史、rewind/fork/summarize、模型与 reasoning effort 控件、
Goal、由 `todo_write` 工具驱动的实时 Todo 面板，以及已配置 provider 的余额显示。临时启动可用
`--model`、`--max-steps` 或 `--resume`；不传 `--model` 时，`serve` 使用用户全局
`default_model`。

## 自定义 OpenAI-compatible provider

在桌面端打开 **设置 -> 模型 -> 接入 -> 添加模型服务 -> 自定义供应商**，用于接入代理、
聚合平台或自建 OpenAI-compatible chat API 服务。

**API 地址** 填写服务端点。默认模式下，WorkGround2 会预览并把聊天请求发送到：

```text
<API 地址>/chat/completions
```

如果服务商给的是完整请求 URL，例如 `https://gateway.example.com/v1/chat/completions`，
开启 **完整 URL**。开启后 WorkGround2 会直接使用该地址，不再追加 `/chat/completions`。
输入框下方的预览就是最终请求地址。

模型发现会基于 API 地址尝试 `/models`、`/v1/models` 等候选地址。如果网关要求单独的
模型列表端点，在 **高级设置** 中填写 `models_url`，例如
`https://gateway.example.com/v1/models`。如果接口不支持模型发现，也可以手动填写模型列表。

**完整 URL** 仍使用 OpenAI-compatible chat 请求体；它不会切换成 OpenAI Responses API
的请求 schema。

## 快捷键

这里按使用端来写，因为用户通常是先知道“我现在在桌面端/CLI”，再找对应按键。
核心模式规则很小：`Shift+Tab` 只管 Plan，`Ctrl/Cmd+Y` 只管 YOLO，粘贴继续走系统粘贴快捷键。

`[ui].shortcut_layout` 仍被接受以兼容旧配置，但下面的快捷键行为已经跨布局统一。

CLI/TUI 文本输入可通过 `[ui].cursor_shape` 设置光标形状，支持 `underline`、`block`
和 `bar`。默认值是 `underline`，因为部分终端中的 block 光标会在中英混排输入时覆盖
CJK 双宽字符，造成视觉错位。想保留旧的终端块状光标可设为 `block`，想使用细插入线可设为
`bar`。该设置不影响桌面端或 Web 输入框。

### 桌面端 GUI

桌面端快捷键在 **设置 → 快捷键** 中管理。选择一行后按下新的组合键，WorkGround2 会为桌面端保存该绑定。
如果新组合键和已有动作冲突，会拒绝保存，避免一个快捷键触发两个动作。按 `?` 或点击 topic bar
里的帮助按钮可打开快捷键帮助表；帮助表由同一份快捷键 registry 生成，因此会同步显示自定义后的绑定。

全局快捷键：

| 按键或控件 | 作用 | 说明 |
| --- | --- | --- |
| macOS `Cmd+K`，Windows/Linux `Ctrl+K` | 打开或关闭命令面板 | 打开时会聚焦搜索框；`Esc` 关闭命令面板。 |
| macOS `Cmd+,`，Windows/Linux `Ctrl+,` | 打开设置 | 在设置里的 **快捷键** 页可自定义桌面端绑定。 |
| macOS `Cmd+W`，Windows/Linux `Ctrl+W` | 关闭当前顶部标签页 | 最后一个标签页仍由原有关闭保护保留。 |
| `Cmd+B` / `Ctrl+B` | 显示或隐藏左侧边栏 | 和点击侧边栏开关是同一个动作。 |
| `Cmd+Shift+B` / `Ctrl+Shift+B` | 展开或收起最近的 shell 输出 | 和点击折叠 shell 输出提示是同一个动作。 |
| macOS `Cmd+1`-`Cmd+9`，其它平台 `Ctrl+1`-`Ctrl+9` | 跳转到侧边栏中对应编号的可见对话 | 短暂按住 `Cmd`/`Ctrl` 会显示编号标记；已有自定义快捷键占用相同按键时，自定义动作优先生效。 |
| macOS `Cmd++`、`Cmd+-`、`Cmd+0`；其它平台 `Ctrl++`、`Ctrl+-`、`Ctrl+0` | 放大、缩小或重置文字大小 | 对把加号上报为 `=` 的键盘也兼容。 |
| `?` | 打开键盘快捷键帮助表 | 帮助表显示当前实际生效的桌面端绑定。 |

输入框快捷键：

| 按键或控件 | 作用 | 说明 |
| --- | --- | --- |
| `Enter` | 发送当前消息 | IME 组合输入确认不会被截获。 |
| `Shift+Enter` | 插入换行 | 输入框保持焦点。 |
| `Shift+Tab` | 切换 Plan 开/关 | Plan 是只读规划，不会循环 Ask/Auto/YOLO。 |
| `Cmd+Y` / `Ctrl+Y` | 切换 YOLO 开/关 | 关闭 YOLO 时会尽量恢复之前的 Ask/Auto 基底。 |
| macOS `Cmd+V`，Windows/Linux `Ctrl+V` | 粘贴剪贴板内容 | 剪贴板图片会作为附件加入；图片也可以拖进输入框。 |
| 输入边界处的普通 `Up` / `Down` | 回放更旧或更新的已提交提示词 | 带修饰键的方向键和原生文本导航仍交给 textarea。 |
| 运行中按 `Esc` | 取消当前 turn | 如果后端尚未开始回复，会恢复草稿。 |

菜单与控件：

| 按键或控件 | 作用 | 说明 |
| --- | --- | --- |
| 斜杠、`@` 或 past-chat 菜单中的 `Up` / `Down` | 移动高亮项 | past-chat 搜索框使用同一套导航键。 |
| 这些菜单中的 `Enter` / `Tab` | 接受高亮项 | 类似目录的条目可能继续打开下一层菜单。 |
| 这些菜单中的 `Esc` | 关闭当前菜单或退出 past-chat 搜索 | 关闭后可继续正常输入。 |
| Ask / Auto / YOLO 审批控件 | 直接选择工具审批姿态 | 点击操作不受快捷键规则影响。 |
| 工具审批卡片 | `Left` / `Right`、`Enter`、`1`-`4`、`Esc` | 移动高亮动作、确认当前高亮、直接选择编号动作，或拒绝。默认高亮是“允许一次”。 |
| 计划审批卡片 | `Left` / `Right`、`Enter`、`1`-`3`、`Esc` | 在“修改计划 / 开始执行 / 退出计划”之间移动。默认高亮是“开始执行”。 |
| Plan 控件 | 切换 Plan 开/关 | 和 `Shift+Tab` 是同一个模式。 |
| 协作菜单里的 Goal | 启动、查看或清除 Goal | Goal 不进入任何快捷键循环。 |

### CLI / TUI

聊天与 transcript：

| 按键或命令 | 作用 | 说明 |
| --- | --- | --- |
| `Enter` | 发送当前消息 | turn 运行中输入非空内容时，会排队作为后续反馈。 |
| `Shift+Enter`、`Alt+Enter` 或 `Ctrl+J` | 插入换行 | 普通 `Enter` 保留给发送/确认。 |
| 空闲时普通 `Up` / `Down` | 回放更旧或更新的已提交提示词 | turn 运行中同一组按键用于导航排队反馈。 |
| `PageUp` / `PageDown` | 滚动 transcript | 不受当前聊天状态影响。 |
| `Ctrl+Home` / `Ctrl+End` | 跳到 transcript 顶部或底部 | 长工具输出后很有用。 |
| `Ctrl+L` 或 `/cls` | 只清空可见 transcript | LLM 上下文、session 文件、工具、记忆和插件都保持加载；想丢弃对话上下文时用 `/clear`。 |
| `Esc` | 退出当前最具体的动作 | 可在无回复前撤回刚提交的 turn、取消运行中的 turn，或清空非空输入。 |
| 空闲且输入为空时双击 `Esc` | 打开 rewind 选择器 | 和 `/rewind` 是同一个入口。 |
| 终端原生选择 | 复制 transcript 文本 | WorkGround2 默认不启用鼠标报告，因此终端自己的选择/复制仍可使用。 |
| `Ctrl+C` | 取消、清空或退出 | 取消运行中的 turn、清空非空输入；空输入下连按两次退出。 |
| `Ctrl+D` | 退出 TUI | 立即退出。 |
| `Ctrl+V`、`Ctrl+Shift+V`、`Meta+V` 或 `Super+V` | 粘贴剪贴板内容 | CLI 会先尝试图片，再回退到文本或文件引用。 |
| `/paste-image` | 粘贴剪贴板图片 | 适合只想贴图片，或终端应用自己接管文本粘贴的场景。 |
| 以 `!` 开头的一行 | 直接运行 shell 命令 | 命令在本地执行，不经过模型。 |

模式与显示：

| 按键或命令 | 作用 | 说明 |
| --- | --- | --- |
| `Shift+Tab` | 切换 Plan 开/关 | Plan 是只读规划，不会循环 Ask/Auto/YOLO。 |
| `Ctrl+Y` | 切换 YOLO 开/关 | 关闭 YOLO 时会尽量恢复之前的 Ask/Auto 基底。终端若能转发 Command/Super，也可能识别 `Cmd+Y`，但稳定可用的是 `Ctrl+Y`。 |
| `--yolo`、`--dangerously-skip-permissions` | 启动时进入 YOLO | 和 `Ctrl+Y` 是同一个运行时模式。 |
| `Ctrl+O` | 切换详细 reasoning 显示 | 也可通过 `/verbose` 使用。 |
| `Ctrl+B` | 展开或收起较长 shell 输出 | TUI 默认不启用鼠标报告，因此可和终端原生文本选择共存。 |
| Ask / Auto | 没有键盘循环 | Ask 是默认交互基底；Auto 不通过 `Shift+Tab` 进入，需要由暴露工具审批姿态的客户端或 API 直接设置。 |
| `/goal <目标>`、`/goal --research <目标>`、`/goal --simple <目标>`、`/goal status`、`/goal clear` | 启动、查看或清除 Goal | Goal 不进入任何快捷键循环；明显长周期目标会自动启用 AutoResearch。普通输入命中强 AutoResearch 信号时也会自动升级为 Goal。 |
| `/migrate`、`/migrate --from <旧目录>` | 重试旧数据迁移，或从指定 v0.x 来源导入 sessions | Windows v0.52 自定义安装/数据目录用 `--from`；该形式只导入 sessions。详见[配置路径](./CONFIG_PATHS.zh-CN.md)。 |

选择器与审批：

| 上下文 | 按键 | 作用 |
| --- | --- | --- |
| 斜杠或 `@` 补全 | `Up` / `Down`、`Tab` / `Enter`、`Esc` | 移动、接受或关闭补全菜单。 |
| 工具审批提示 | `y`/`1`、`a`/`2`、`p`/`3`、`n`/`4`、`Enter`、`Esc`、`Ctrl+C` | 允许一次、本会话允许、持久允许、拒绝、默认允许一次、拒绝，或取消当前 turn。 |
| Ask 问题卡 | `Up`/`Down` 或 `j`/`k`、`Left`/`Right` 或 `h`/`l`、`Space`、`Enter`、`1`-`9`、`Esc`、`Ctrl+C` | 导航答案/问题标签、切换多选、提交/激活、选择编号选项、关闭，或取消当前 turn。 |
| Rewind 选择器 | `Up`/`Down` 或 `j`/`k`、`Enter`、`b`、`c`、`d`、`f`、`s`、`u`、`Esc` | 选择 turn，应用 both/conversation/code/fork/summarize 动作，或返回/关闭。 |
| Resume 选择器 | `Up`/`Down` 或 `j`/`k`、`Enter`、`Esc` | 选择已保存 session 或关闭选择器。 |
| MCP 导入选择器 | `Up`/`Down` 或 `j`/`k`、`Space`、`Enter`、`Esc` / `Ctrl+C` | 移动、勾选服务器、导入勾选服务器，或取消。 |
| MCP 管理器 | `Up`/`Down` 或 `j`/`k`、`Enter`、`Left`/`Right` 或 `h`/`l`、`r`、数字键、`q` / `Ctrl+C` | 导航服务器列表/详情、刷新、选择动作，或关闭。 |
| `/clear` 确认 | 方向键或 `j`/`k` / `Tab`、`Enter`、`y`、`n`、`Esc` / `Ctrl+C` | 在 Clear/Cancel 间切换、确认清空，或取消。 |

模式含义：

| 模式 | 含义 |
| --- | --- |
| Ask | writer 兜底审批时询问。 |
| Auto | 自动放行兜底审批；显式 `ask` / `deny` 规则仍生效。 |
| YOLO | 跳过普通工具审批；`deny`、用户 `ask` 问题、计划批准提示、MCP 只读信任提示仍会等待。 |
| Plan | 下一轮保持只读规划，直到计划被批准或关闭 Plan。 |
| Goal | 持续追一个已保存目标，直到完成、阻塞或清除。 |

## 权限与沙盒

权限逐次调用把关：`deny` > `ask` > `allow` > 兜底。Bash 和文件修改都要审核；
只读工具一般不需要。审核规则不是按“按钮文案”存，而是按权限规则匹配，比如
`Bash(npm run build)`、`Bash(npm run test:*)`、`Edit(docs/**)` 这种形式。
`WorkGround2` 会在 writer 调用前征求同意（普通工具为 `1` 本次 · `2` 本会话允许此范围 · `3` 总是允许此范围（保存） · `4` 拒绝；Bash 可额外选择命令前缀授权）；
其中 Bash 默认按具体命令记，也可按安全推导出的命令前缀记（如 `Bash(go test:*)`）；文件编辑类工具的本会话授权按编辑能力记，持久授权则写入 `Edit(<path>)` 文件路径规则；
`WorkGround2 run` 保持自主运行但仍然遵守 `deny`。

权限是**策略**（哪些调用放行/询问），**沙盒**是**强制**：文件写工具
（`write_file` / `edit_file` / `multi_edit` / `move_file`）拒绝 `[sandbox] workspace_root`
之外的任何路径（默认当前目录，编辑不出项目），并解析符号链接与 `..`，使链接无法
打洞越界。`forbid_read` 可选地隐藏敏感目录，使 agent 的读文件、列目录和搜索工具不能读取或列出它们；
建议使用绝对路径或 `${HOME}` / `${VAR}`，不要写 `~`，因为配置只做环境变量展开。
`bash` 本身在 macOS 默认进沙盒（`[sandbox] bash`，Seatbelt）：命令只能写这些 root（外加临时目录与工具链缓存），
OS 沙盒生效时也不能读取配置的 `forbid_read` roots，`[sandbox] network` 为真时才能联网；
其它平台在没有可用 OS 沙盒时会回退为不沙盒运行（越界问一次与 Linux 支持见
[`SPEC.md` §9](./SPEC.md#9-roadmap-not-in-current-scope)）。

## 插件（MCP）

WorkGround2 是一个 MCP 客户端。`[[plugins]]` 的 `type` 选择传输：`stdio`（默认）启动本地子进
程（`command`/`args`/`env`）；`http`（Streamable HTTP）连接远程 `url`，可带静态
`headers`（`${VAR}` / `${VAR:-default}` 从环境展开，密钥不入文件）。工具以
`mcp__<server>__<tool>` 暴露给模型，与 Claude Code 一致；声明 MCP `readOnlyHint: true`
的工具会参与并行调度并命中权限层的只读默认放行，但 planner / read-only research 会先确认第三方
自报只读。交互式会话里，第一次需要时允许即可；选择持久允许会把 raw MCP tool name 记住。
这个信任提示属于用户决策，Auto/YOLO 工具审批不会代答；选择本会话允许或持久允许后，同一个 MCP
工具不会在本会话里重复弹。
高级用户也可以在 plugin 上预置审过的第三方读工具：

```toml
[[plugins]]
name = "github"
command = "github-mcp"
trusted_read_only_tools = ["issue_read", "pull_request_read"]
```

桌面端 MCP 面板保留为高级管理入口：展开已配置的服务器并打开工具列表；只有在想提前批准工具时，
才使用 **预先信任只读** 或单个工具旁的 **预先信任**。用 **取消信任** 可以移除已记住的读工具。
桌面端会把 raw MCP tool name 写入拥有该服务器的配置源：项目 `.mcp.json` 里的服务器会更新到
`mcpServers.<server>.trusted_read_only_tools`，普通 WorkGround2 plugin 会写入用户级 WorkGround2 config。
只信任无副作用的读取工具；create/update/delete 这类写工具应保持未信任。

服务器的 **prompts** 会暴露成 `/mcp__<server>__<prompt>` 斜杠命令（命令后空格分隔参
数）；**resources** 通过在消息里写 `@<server>:<uri>` 拉入；`/mcp` 列出已连接服务器及
各自暴露的内容。`make build` 还会产出 `bin/WorkGround2-plugin-example`——一个可直接运行的
stdio 参考实现（`echo`、`wordcount`、一个 `review` prompt、一个 style-guide 资源），
可照抄。

```toml
[[plugins]]                       # 本地 stdio 服务器
name    = "example"
command = "WorkGround2-plugin-example"
# call_timeout_seconds = 600       # 可选：单个 MCP server 的调用超时
# tool_timeout_seconds = { "generate_video" = 1800 }   # 可选：raw MCP tool 名称

[[plugins]]                       # 远程 Streamable HTTP 服务器
name    = "stripe"
type    = "http"
url     = "https://mcp.stripe.com"
headers = { Authorization = "Bearer ${STRIPE_KEY}" }
```

启用的 MCP 服务器会在会话开始后于后台自动连接，因此工具上线期间聊天仍可正常使用。
用 `/mcp` 或桌面端 MCP 面板可刷新状态、重连服务器、查看失败原因，或在当前会话内禁用某个服务器。

**已有 Claude Code 的 `.mcp.json`？** 直接放到项目根目录，WorkGround2 会原样读取——其
`mcpServers` 规范（`command`/`args`/`env`、`type`/`url`/`headers`、`${VAR}` 展开）
与 `[[plugins]]` 字段一一对应。两处来源会合并加载；同名时以 `WorkGround2.toml` 为准。

```json
{
  "mcpServers": {
    "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path"] },
    "stripe": { "type": "http", "url": "https://mcp.stripe.com", "headers": { "Authorization": "Bearer ${STRIPE_KEY}" } }
  }
}
```

**从 `0.x` 升级？** 旧的 `~/.WorkGround2/config.json` 仍会被读取（读其 `mcpServers`、并遵从
`mcpDisabled`），作为最低优先级来源——所以 MCP 服务器照常可用；方便时再把它们挪进
`WorkGround2.toml` 的 `[[plugins]]` 或 `.mcp.json`。

## 斜杠命令

交互式 `WorkGround2` 会话里，内置命令（`/compact`、`/new`、`/clear`、`/rewind`、`/tree`、`/branch`、`/switch`、`/todo`、`/model`、`/mcp`、`/skills`、`/hooks`、`/memory`、`/memory-v5`、`/goal`、`/output-style`、`/sandbox`、`/language`、`/auto-plan`、`/reasoning-language`、`/help`）在本地执行——`/help` 可列出全部。
`/new` 会开启新会话，同时保存之前的 transcript 供历史记录和恢复使用；`/clear` 会二次确认，确认后丢弃当前上下文且不保存。
`/tree` 查看已保存的对话分支，`/branch [name]` 从当前对话末端分支，`/branch <turn> [name]`
从较早的 checkpoint 轮次分支，`/switch <id|name>` 切换到另一个分支。**自定义命令**
是放在 `.WorkGround2/commands/`（项目）或 `~/.WorkGround2/commands/`（用户）下的 Markdown 文件——
`review.md` 即 `/review`，子目录构成命名空间（`git/commit.md` → `/git:commit`）。文件正文
是 prompt 模板，调用即作为一轮对话发出。

`/memory` 会同时列出记忆文档（`WorkGround2.md` / `AGENTS.md`）和已保存的 auto-memory 条目。
在 agent 回合中，只读的 `history` 和 `memory` 工具可以按需检索历史 session 决策、
compaction archive 和已保存事实；这些动态内容不会被塞进稳定的 system prompt 前缀。
`/forget <name>` 会把已保存事实归档而不是永久删除；CLI/TUI 和桌面记忆面板能显示归档文件用于追溯，
但它们不会作为 active memory 被检索。检索会保留 BM25 最强命中，同时裁掉弱的泛词命中；
agent 发起的 `remember` 和 `forget` 每次都会要求新的人工确认，并在执行前展示将保存或归档的记忆摘要。
0 结果会提示 agent 改用更少、更有区分度的词继续查。
Memory v5 在 CLI/TUI、`WorkGround2 serve` 和桌面端默认开启，因为这些入口共用同一套本地
controller。它会把本地、按项目隔离的执行轨迹和编译器状态写在 WorkGround2 home 下，并且只有
历史结果产生可行动约束时，才把下一轮用户输入编译成精简 execution contract。早期轮次可能
只写入轨迹而不注入任何内容。默认的 `verbosity = "observe"` 只做本地学习和内容无关指标，
不会把 `<memory-compiler-execution>` 发送到 provider 可见的用户轮次；只有显式切到
`verbosity = "compact"`（或旧的 `on` 命令别名）时才恢复精简 execution contract 注入，
并把选中的精简 memory reference 放进 provider 可见的用户轮次。Memory v5 不会绕过
memory 审批，也不会修改 cache-stable system prompt、Provider 前缀或工具 schema。

交互式会话里可用 `/memory-v5 off|observe|compact|on|status` 控制后续轮次，也可在 shell/脚本里用
`WorkGround2 config memory-v5 off|observe|compact|on|status`。桌面端还可以在设置 → 通用 → Memory v5 中控制。
设置 → 更新 → 共享聚合质量指标控制可选的聚合上报；开启后只会上报匿名计数/大小桶，例如是否
注入、编译后 token 大小桶、IR overhead 大小桶、memory reference 数量、constraint/risk/step
数量，以及记忆图规模桶。它不会包含记忆正文、提示词、工具输出、文件路径、ID、密钥、base URL
或文件内容。

CLI/TUI 和 `WorkGround2 serve` 使用同一个 user/global 配置。项目内的 `WorkGround2.toml` 不能覆盖
这个 user/global 设置。CLI 命令会更新底层配置；高级用户也可以手动编辑 WorkGround2 home 下的
用户配置：

```toml
[agent]
memory_compiler = { enabled = true, verbosity = "observe" }
```

CLI 可以在本地轮次使用 Memory v5，但不会运行桌面端的聚合指标上传管线。使用
`WorkGround2 run --metrics <path>` 时，JSON 还会输出内容无关的 `memory_compiler_*` 汇总字段，
以及 `memory_compiler_turn_details` 逐轮明细数组，包含是否注入、编译后 token 和 IR overhead
估算、引用记忆/constraint/risk/step 数量，以及当前记忆图计数。
技术实现细节见 [`SESSION_MEMORY_RETRIEVAL.md`](SESSION_MEMORY_RETRIEVAL.md)。

```markdown
---
description: Review the staged diff
argument-hint: [focus-area]
---
Review the staged diff. Focus on $ARGUMENTS, list bugs with file:line.
```

`$ARGUMENTS` 展开为全部空格分隔参数，`$1`…`$N` 为位置参数。MCP prompts 也以
`/mcp__<server>__<prompt>` 形式出现在这里。

## Goal 与 AutoResearch

Goal 是长期目标的统一运行机制。普通 `/goal` 继续走轻量 Goal：WorkGround2 会持续推进，直到
完成、阻塞或被清除。对于明显长周期的目标，Goal 会自动进入 AutoResearch 策略，而不是
要求用户单独运行 `/auto-research` skill；`auto-research` 也不会作为独立 builtin skill 出现在
Settings -> Skills 或斜杠菜单里。普通聊天输入如果命中很强的长周期信号，也会被 host 自动
升级为等价的 `/goal --research <原输入>`。

AutoResearch 会在这些目标里自动启用：包含“持续”“长期”“彻底”“直到根因明确”“多轮排查”
“不要原地打转”“完整方案”“跑实验”“反复验证”“系统性研究”等强信号；或者目标同时包含
研究/排查、实现/修复、验证/测试、优化/文档/发布等多个阶段；或者用户明确给出
`.WorkGround2/autoresearch/<task-id>/` 任务目录。高级用户可以用
`/goal --research <目标>` 强制启用，也可以用 `/goal --simple <目标>` 强制保持轻量 Goal。
普通聊天里的自动升级比 `/goal` 内部判断更保守：单独说“长期”“优化”“研究一下”或
“验证一下”不会自动创建 AutoResearch 任务。

进入 AutoResearch 后，agent 会把目标当成有状态的研究循环，而不是只靠聊天上下文续写。
它会创建或复用项目级 `.WorkGround2/autoresearch/<task-id>/` 目录。新任务默认使用
`YYYYMMDD-HHMMSS-slug` 作为 id，例如 `20260618-224530-cache-audit`；创建前会先检查
当前项目目录，只有同名已存在时才追加 `-2`、`-3` 等后缀。任务状态包括
`task_spec.md`、`progress.json`、`findings.jsonl`、`directions_tried.json` 和
`iteration_log.jsonl`，记录每轮方向、证据、验证结果和卡住原因，并用 `stale_count` 判断
是否在低质量重复。连续停滞时，它会要求结构性 pivot，例如换证据源、入口、测试 oracle、
拆解方式、benchmark 或 worker 策略，而不是继续重复同一种尝试。

worker/subagent 可以独立探索，但 canonical state 由 orchestrator 负责写入。完成前必须
对照 `task_spec.md` 的 success criteria 做逐项证据审计；窄范围检查通过不能证明宽范围需求
完成。动态运行态只写进 `.WorkGround2/autoresearch/...`，不写入 `WorkGround2.md`、`AGENTS.md`、
project memory、tool schema 或 cache-stable system prompt。公开发布、破坏性操作、凭证、
付款和外部通知仍然遵守正常的 approval、privacy 与 cache gate。

## @ 引用

在消息里写 `@` 引用，WorkGround2 会在发送前解析成带标签的上下文块：`@path/to/file`（或
`@dir`）注入本地文件内容（或目录清单），`@<server>:<uri>` 注入 MCP 资源。本地路径**只有
真实存在**时才当作引用，普通 `@mention` 保持原文。敲 `/` 或 `@` 会弹出补全菜单——斜杠
命令，或**逐层**的文件导航（一次只列当前一层目录、可下钻进子目录）外加 MCP 资源。

## 双模型协同

`WorkGround2 setup` 刻意保持首次体验极简：选 provider → 输入 key（所选 provider 的所有
SKU 都会启用）。若要让两个模型协同（执行器 + 规划器，各自独立、缓存稳定的
session），向导后手动在 `WorkGround2.toml` 加一行即可：

```toml
[agent]
planner_model = "deepseek-pro"   # 作为低频规划器
```

Planner 会看到已加载的 `WorkGround2.md` / `AGENTS.md` 记忆，并拿到一小组只读研究工具，
因此可以先检查相关文件再把计划交给执行器。写入类和流程类工具仍只给执行器使用。
`max_steps` 限制执行器；`planner_max_steps` 只限制规划器，两者都可设为 `0` 表示不限。

轮数上限请放在用户级配置。项目 `./WorkGround2.toml` 不会覆盖 `max_steps` 或
`planner_max_steps`。

Subagent skills 默认继承执行器模型。设置 `subagent_model` 可让它们统一走另一个已配置
模型；设置 `subagent_models` 则只覆盖 `review`、`security_review` 等指定 skill。

Subagent 默认允许再委派一层：根会话是 depth 0，第一层 subagent 是 depth 1，
`max_subagent_depth = 2` 表示 depth 1 的 workflow 可以再派 depth 2 的 reviewer
或 implementer；depth 2 不再拿到递归 agent/skill 工具。设
`agent.max_subagent_depth = 1` 可恢复旧的单层边界。这主要用于 Superpowers 这类
workflow skill 派发 reviewer subagent 的场景，同时避免无限递归和后台 fanout。

### 能力辅助（Capability Assist）

当模型缺少某种能力时——比如需要搜索的非搜索模型，或无法生成图片的模型——它可以调用
`request_help` 工具。宿主自动选择具备该能力的辅助模型，代为完成任务。

```toml
[agent]
# assist_mode = "off"     # auto（默认）启用 request_help；off 隐藏该工具
# assist_models = { web_search = ["provider/model"] }
#                          # 能力 → 有序辅助模型引用列表；为空则从 providers 自动发现
# assist_max_attempts = 3  # 每次 request_help 调用最多尝试的候选数量
```

`assist_models` 将能力名称（`web_search`、`image_generation`）映射到有序模型引用。
当某个能力的列表非空时，自动发现会被跳过。排除规则：当前模型、无法解析的引用、
未配置凭据或 CLI 命令的 provider，以及未声明该能力的 provider。运行时失败会尝试下一个候选，最多
`assist_max_attempts` 次。

`web_search` 失败可重试，成功答复必须包含至少一个 `http(s)` 来源 URL。
`image_generation` 启动后绝不自动重试——返回明确错误以避免重复产出。图片成功优先
来自真实 `draw_image` 工具结果，并通过任务状态、配置输出目录、文件存在、非空、MIME
和图片解码校验；若 `draw_image` 结果不存在，回退到 CLI provider 通过请求作用域收集器
报告的 Codex 副作用制品（`$CODEX_HOME/generated_images/<thread_id>/`），执行同等校验。
文字声称、伪路径和越界路径都会失败。

能力不会从模型品牌自动推断，但有两个受控例外：Google Gemini chat 模型
（`gemini-*`）从模型名推断 `web_search`，当前 Gemini 3 图片模型也识别搜索 grounding；
Google 图片模型（`imagen-*`、`nano-banana*`、已知 Gemini Image 模型家族）推断 `image_generation`。
所有 Gemini 模型推断 `vision`。显式 `capabilities`（含空数组）始终优先并关闭推断。
其他 Provider 通常需要显式声明：

```toml
[[providers]]
name         = "search-pro"
kind         = "openai"
base_url     = "https://api.search-provider.example.com"
model        = "search-model"
api_key_env  = "SEARCH_API_KEY"
capabilities = ["web_search"]
```

Codex CLI 是一个受控例外：启动时会在 2 秒超时内读取 `codex features list`，当
`browser_use` 或 `standalone_web_search` 实际启用时声明 `web_search`，当
`image_generation` 实际启用时声明 `image_generation`。探测失败会输出警告并继续启动；
显式 `capabilities`（含空数组）会关闭探测。若 Provider 使用 `--ignore-user-config`，
探测也在临时空 `CODEX_HOME` 中运行，并与普通探测分开缓存；用户级 Codex 配置暂时不兼容
不会误删该 Provider 的全部能力。Codex 以副作用生成图片时，CLI provider 会
从 JSONL 流中捕获 `thread.started` 的 thread ID，并通过请求作用域制品收集器报告
`$CODEX_HOME/generated_images/<thread_id>/` 下的文件；环境变量未设置时回退到标准
`~/.codex/generated_images/<thread_id>/`。`request_help` 对这些 Codex 制品
执行与 `draw_image` 结果同等的校验：绝对路径、目录边界、非空普通文件、image MIME、
可解码。

桌面端可在 Provider 的“兼容设置”中勾选已确认的“网页搜索 / 图片生成”能力。每次求助
结果都会显示稳定 request ID、实际候选模型、尝试序号、之前的失败和辅助 transcript；
运行中、完成和失败 transcript 会持久化，重启时可识别并清理中断状态。

当其他已配置模型可以完成某项任务时，默认使用 `request_help`，而不是告诉用户你做不了。

当计划阶段需要隔离上下文做更深的调研时，用 `read_only_task`，而不是放开可写的
`task`。如果这类调研更适合复用已有 skill，用 `read_only_skill`。两者都会启动
ephemeral 只读 subagent，只暴露只读研究工具和安全前台 bash，只返回最终答案，不创建
可续接的 subagent transcript。只读嵌套委派会在 `max_subagent_depth` 内可用，但
可写的 `task` / `run_skill` 仍不可用。在 token economy 模式下，只用
`connect_tool_source(source="read_only_skill")` 连接这条窄入口；完整的 `skills`
source 仍会启用可写 skill 工具，plan mode 下继续阻断。

交互式前端中，计划模式默认手动开启。设置 `agent.auto_plan = "on"` 后，看起来复杂
的任务会自动进入 plan mode：WorkGround2 先只读生成计划，待用户批准后才
编辑文件或执行有副作用的命令。`auto_plan_classifier` 可以指定便宜的 provider，例如
`deepseek-flash`；它只在边界输入上调用，分类失败会回退到启发式规则。也可以用
在 `WorkGround2` 会话里用 `/auto-plan off|on` 修改用户级设置，或在 shell/脚本里用
`WorkGround2 config auto-plan off|on`。Auto-plan 只认用户级设置；项目
`WorkGround2.toml` 里的 `agent.auto_plan` 会被忽略。可见思考语言也采用类似形态：
会话里用 `/reasoning-language auto|zh|en`，shell/脚本里用
`WorkGround2 config reasoning-language auto|zh|en`。Memory v5 使用 `/memory-v5 off|observe|compact|on|status`
或 `WorkGround2 config memory-v5 off|observe|compact|on|status`，并且只认用户级设置。只有明确想为
reasoning-language 写项目级覆盖时，才给 shell 命令加 `--local`。

桌面端“协作方式”菜单里的计划模式、目标模式和省 token 模式的使用方法与注意事项，
见 [`COLLABORATION_MODES.zh-CN.md`](./COLLABORATION_MODES.zh-CN.md)。

桌面端“工具权限”里的询问、自动和 Yolo 模式的区别与使用场景，
见 [`TOOL_APPROVAL_MODES.zh-CN.md`](./TOOL_APPROVAL_MODES.zh-CN.md)。

分离 session（让各模型前缀缓存稳定）背后的取舍见
[`SPEC.md` §3.5](./SPEC.md#35-two-model-collaboration-coordinator)。