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

任务拆解与执行计划.md

@@ -113,3 +113,8 @@ P0 完成后的能力：干净的后端抽象 + 可量化的评测 + 可追溯
 | T19 | 前端：API 层 + 设置页模型池 UI（角色指派/条目 CRUD/连通测试） | ✅ 完成 | T19-T20 |
 | T20 | 前端：智能体页 AgentView + 指标页分账卡 + SSE 终态去重 | ✅ 完成 | T19-T20 |
 | T21 | 集成验证：真跑 3 轮工具任务（write/list/read）+ 浏览器实测 + 262 测试全绿 | ✅ 完成 | T21 |
+
+| T22 | 工具扩展：edit_file（唯一替换）/ search_files（跳过依赖目录）/ run_command（allow_shell 默认关） | ✅ 完成 | T22 |
+| T23 | 工作区选择：/agent/fs 目录浏览 + /agent/workspaces 最近列表 + /agent 带 workspace | ✅ 完成 | T23 |
+| T24 | 前端：工作区选择栏（目录浏览器/最近/shell 开关）+ edit diff 卡 + 命令卡 | ✅ 完成 | T24-T25 |
+| T25 | 集成验证：选定真实目录"读→精确编辑→运行验证"全链路 + 274 测试全绿 | ✅ 完成 | T24-T25 |

实现方案_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. 实验设计建议（论文用）
 

毕业设计_进度记录.md

@@ -106,3 +106,19 @@
 4. 中文文献知网核对仍待完成（定稿前必做）。
 
 *记录人：DSH Agent（2026）。*
+
+### 5.4 增补（同日）：工作区选择 + harness 级工具（T22–T25）
+
+- **需求来源**：智能体原先只能固定操作 `agent_workspace/`，"不能选择工作区"。
+  参考 `deepseek-harness/`（DeepSeek 开源 agent harness）的"打开文件夹"体验与工具集设计。
+- **落地**：① 工作目录可选——`/agent/fs` 磁盘目录浏览（Windows 盘符枚举）+
+  最近工作区列表（持久化），运行记录所用目录，左侧文件面板跟随切换；
+  ② 工具升级到 harness 级——`edit_file`（old_string 唯一命中才替换，防误改）、
+  `search_files`（跨文件内容搜索，跳过 .git/node_modules 等）、
+  `run_command`（**默认关闭**，UI 开关 allow_shell，超时+输出截断+Windows 无窗口）；
+  ③ 前端 edit_file 渲染为红/绿 diff 卡，命令卡展示 `$ 命令` 与退出码输出。
+- **实测**：选定 `E:\agent_demo\greet_app`，模型完成"读文件 → edit_file 加参数校验 →
+  运行 python greet.py 验证"，磁盘文件真实变更（出现 __pycache__ 证明命令在工作区内执行）。
+- **测试**：全量 274 passed（新增 12：tools 扩展 7 + 工作区选择 5）。
+- **安全边界（论文可写）**：文件操作相对所选根关押；shell 独立开关默认关；
+  唯一性约束防覆盖式误编辑——"能力开放 + 边界收窄"的设计权衡可作一节。