docs(v3): T25 文档收口（工作区选择 + harness 工具，274 测试全绿）

实现方案_v4_模型池与工具智能体.md

@@ -14,9 +14,14 @@
   architect / worker / agent 三个角色；留空 = 沿用经典单模型设置（向后兼容）。
   `build_v2_pipeline` 池指派优先；`V2Stats` 新增按模型 token/成本分账（`by_model`）。
 - **工具智能体**：`router_system/tools.py`（纯标准库）提供 WorkspaceTools
-  （list_dir / read_file / write_file，路径关押在根目录内）与 ToolLoop（通用工具循环，
-  轮数 + token 双护栏，逐事件回调）；`gateway/agent.py` 提供 OpenAI 兼容工具调用客户端与
-  运行服务（事件落盘 `agent_runs/{id}/events.jsonl`），`/agent` 端点 + SSE 实时推送。
+  （list_dir / read_file / write_file / **edit_file / search_files / run_command**，
+  路径关押在根目录内）与 ToolLoop（通用工具循环，轮数 + token 双护栏，逐事件回调）；
+  `gateway/agent.py` 提供 OpenAI 兼容工具调用客户端与运行服务
+  （事件落盘 `agent_runs/{id}/events.jsonl`），`/agent` 端点 + SSE 实时推送。
+- **可选择工作目录**（参考 deepseek-harness 的"打开文件夹"体验）：智能体可作用于
+  用户从磁盘上选择的任意项目目录（`/agent/fs` 目录浏览 + `/agent/workspaces` 最近列表），
+  运行记录所用目录；`run_command` 默认关闭（allow_shell 开关），开启后在工作区内执行命令
+  （超时熔断 + 输出截断 + Windows CREATE_NO_WINDOW）。
 - **工程约束不变**：`router_system` 零第三方依赖；测试全部封闭（httpx 注入/假实现）；
   不上分布式中间件；金额护栏沿用 api_token_cap 思想（agent 有独立 token_cap）。
 
@@ -30,9 +35,12 @@
 - **D3 角色指派可热切换**：`PUT /pool/roles` 后 `rebuild_pipeline()` 立即生效；
   测试注入 `worker_cfg_override` 优先级最高（保测试封闭）。
 - **D4 工具被关押在根目录**：所有路径 join 后 resolve，必须仍位于工作区根内
-  （防 `../` 与绝对路径逃逸）；读取/写入/列表均有长度上限。
-- **D5 智能体双护栏**：轮数上限（settings.agent.max_rounds，默认 8）+
-  token 熔断（settings.agent.token_cap，默认 20000）；触顶强制总结，不再给工具。
+  （防 `../` 与绝对路径逃逸）；读取/写入/编辑均有长度与唯一性约束
+  （edit_file 的 old_string 必须唯一命中，歧义即拒绝）；search_files 跳过依赖/构建目录与
+  二进制大文件。工作区根本身可由用户选择（"打开文件夹"），关押相对所选根生效。
+- **D5 智能体双护栏 + shell 默认关**：轮数上限（agent.max_rounds，默认 8）+
+  token 熔断（agent.token_cap，默认 20000）；`run_command` 受 allow_shell 开关（默认关），
+  开启后有 shell_timeout_s 超时与输出截断；触顶强制总结，不再给工具。
 - **D6 事件文件为单一事实源**：智能体过程逐条追加 events.jsonl，SSE 生成器轮询增量推送
   （晚加入者从头回放）；前端收到 final 即关闭连接并忽略后续回放，防止重复渲染。
 
@@ -45,9 +53,11 @@
 | `DELETE /pool/{id}` | 删除条目（角色指派联动清空） |
 | `PUT /pool/roles` | 角色指派（architect/worker/agent → 条目 id 或空串） |
 | `POST /pool/{id}/test`、`GET /pool/{id}/models` | 条目连通测试 / 模型列表探测 |
-| `POST /agent` | 提交智能体任务 `{task, pool_id?}`，立即返回 request_id |
-| `GET /agent/{id}/status` `/events` `/stream`(SSE) | 状态 / 全量事件 / 实时流 |
-| `GET /agent/workspace?path=`、`GET /agent/file?path=` | 工作区浏览/读取（越界 400） |
+| `POST /agent` | 提交任务 `{task, pool_id?, workspace?}`，workspace 为所选工作目录 |
+| `GET /agent/{id}/status` `/events` `/stream`(SSE) | 状态（含所用工作目录）/ 全量事件 / 实时流 |
+| `GET /agent/workspace?path=&root=`、`GET /agent/file?path=&root=` | 工作区浏览/读取（root 指定所选目录） |
+| `GET /agent/fs?path=` | 目录选择器：浏览本地目录（只列子目录，空 path 列盘符） |
+| `GET /agent/workspaces`、`POST /agent/workspaces` | 当前+最近工作区 / 打开（可 create 新建）并设为当前 |
 
 `/config/models`、`/config/ping` 抽出共用 `_list_backend_models` / `_probe_backend`。
 
@@ -69,6 +79,10 @@
 | T19 | 前端 API 层 + 设置页模型池 UI | ✅ |
 | T20 | 智能体页 AgentView + 指标页分账卡 + SSE 终态去重 | ✅ |
 | T21 | 集成验证：真跑 3 轮工具任务（写/列/读）+ 全量 262 测试 + 浏览器实测 | ✅ |
+| T22 | 工具扩展（harness 风格）：edit_file 唯一替换 / search_files 跨文件搜索 / run_command（opt-in） | ✅ |
+| T23 | 工作区选择：/agent/fs 目录浏览 + 最近工作区 + /agent 带 workspace + 状态记录目录 | ✅ |
+| T24 | 前端：工作区选择栏（目录浏览器模态/最近/shell 开关）+ edit diff 卡 + 命令卡 | ✅ |
+| T25 | 集成验证：选定真实目录跑"读→精确编辑→运行验证"全链路 + 274 测试全绿 | ✅ |
 
 ## 5. 实验设计建议（论文用）