diff --git a/docs/08-用户指南/AI文件操作工具手册.md b/docs/08-用户指南/AI文件操作工具手册.md new file mode 100644 index 0000000..4e4f75e --- /dev/null +++ b/docs/08-用户指南/AI文件操作工具手册.md @@ -0,0 +1,360 @@ +# AI 文件操作工具手册 + +> 最后更新：2026-06-16 | 基于代码核对（`src-tauri/src/commands/ai/tool_registry.rs`） +> +> 本文档覆盖 AI 助手可调用的全部文件系统工具。项目/任务/灵感等 CRUD 工具见使用手册。 + +--- + +## 工具总览 + +| 工具 | 用途 | 风险等级 | 需审批 | +|------|------|----------|--------| +| `read_file` | 读取文件内容（全文/分页/搜索） | Low | 否 | +| `write_file` | 创建/覆盖写入文件（文本 + base64 二进制） | Medium | 是 | +| `patch_file` | 局部更新文件（精确匹配替换） | Medium | 是 | +| `append_file` | 向文件末尾追加内容 | Medium | 是 | +| `file_info` | 获取文件元信息（不读内容） | Low | 否 | +| `list_directory` | 列出目录内容（含递归/深度控制） | Low | 否 | +| `search_files` | 按文件名模式搜索文件 | Low | 否 | +| `rename_file` | 重命名/移动文件（Rust 原生，中文路径无障碍） | Medium | 是 | +| `delete_file` | 删除文件（默认软删除可恢复） | High | 是 | +| `run_command` | 执行 shell 命令 | High | 是 | + +> **路径安全**：所有文件工具走 `validate_path` 黑名单（禁止 `..` 路径遍历 + 敏感系统目录 `.ssh`/`.aws`/`.gnupg`）+ `resolve_workspace_path` 双层校验（词法 `starts_with` + `canonicalize` 防 symlink 逃逸）。文件操作限制在 workspace 目录内。 + +--- + +## read_file + +读取文件内容，支持分页和行内搜索。 + +### 参数 + +| 参数 | 类型 | 必填 | 说明 | +|------|------|------|------| +| `path` | string | ✅ | 文件路径（workspace 内） | +| `offset` | number | ❌ | 起始行（0 基索引），默认 0 | +| `limit` | number | ❌ | 读取行数，默认 200，硬上限 2000 | +| `search` | string | ❌ | 搜索模式：按行过滤含该子串的行（大小写敏感） | + +### 行为规则 + +- `offset` 是 **0 基索引**：offset=0 → 第 1 行，offset=10 → 第 11 行 +- `offset` 超出总行数 → 返回空内容，**不报错** +- 文件大小上限 **1MB**，超出报错 +- 二进制文件 → 返回 `{ binary: true, content: null }` +- 不存在的文件 → 报错 + +### search 模式返回结构 + +```json +{ + "path": "...", + "size": 145, + "search": "keyword", + "matches": [{ "line": 12, "content": "匹配行内容" }], + "total": 3, + "has_more": false +} +``` + +> `line` 为 **1 基行号**（与 offset 的 0 基不同）。最多返回 50 条匹配。 + +### 默认（分页）返回结构 + +```json +{ + "path": "...", + "content": "文件文本内容", + "size": 145, + "lines": 30 +} +``` + +> `lines` 和 `size` 始终返回**全量值**，不受 offset/limit 影响。 + +--- + +## write_file + +创建或覆盖写入文件。 + +### 参数 + +| 参数 | 类型 | 必填 | 说明 | +|------|------|------|------| +| `path` | string | ✅ | 文件路径 | +| `content` | string | ✅ | 内容（UTF-8 文本 或 base64 编码） | +| `encoding` | string | ❌ | `"utf-8"`（默认）或 `"base64"`（写二进制：图片/PDF/Excel） | + +### 行为规则 + +- **自动创建多级父目录** +- **覆盖已有文件**：覆盖前自动 `.bak` 备份（非空文件），原子写（tmp→rename），成功后清理 `.bak` +- **疑似误覆盖检测**：新内容 < 旧内容 10% 时 warn 提示（防全量覆盖事故） +- 写入大小上限 **1MB** +- `encoding="base64"`：解码后写字节，支持二进制文件 +- 返回 `old_size`（覆盖前大小，新建时为 null）和 `bytes_written` + +### ⚠️ 局部修改请用 patch_file + +write_file 是全量覆盖。局部修改用 `patch_file`（精确匹配替换，无需重发整个文件）。 + +--- + +## patch_file + +局部更新文件，精确匹配 `old_text` 并替换为 `new_text`。 + +### 参数 + +| 参数 | 类型 | 必填 | 说明 | +|------|------|------|------| +| `path` | string | ✅ | 目标文件路径 | +| `old_text` | string | ✅ | 要替换的精确文本（必须完全匹配含空格/缩进） | +| `new_text` | string | ✅ | 替换后的新文本 | +| `line` | number | ❌ | 行号辅助定位（快速跳转 + 去歧） | +| `expected_hash` | string | ❌ | 文件指纹防脏写（`"{mtime_secs}_{size}"`） | + +### 安全机制（三层防御） + +| 层 | 机制 | 作用 | +|----|------|------| +| L1 | 文件级 Mutex | 防同文件并发写冲突 | +| L2 | old_text 精确匹配 | 防内容错配（不匹配则报错，不修改） | +| L3 | expected_hash 指纹 | 防版本漂移（文件被外部修改则拒绝） | +| 兜底 | .bak 备份 | 误操作可恢复 | + +### 返回结构 + +```json +{ + "path": "...", + "changed": true, + "size_diff": -42, + "matches_found": 1, + "diff": " context line\n-old line\n+new line\n", + "warning": "匹配到 3 处，仅替换第 1 处" +} +``` + +> `diff` 为行级 unified diff，供审批卡展示。多处匹配时仅替换第 1 处并返回 warning。 + +> 详见 [patch_file 使用指南](./patch_file使用指南.md) + +--- + +## append_file + +向文件末尾追加内容，文件不存在则自动创建。 + +### 参数 + +| 参数 | 类型 | 必填 | 说明 | +|------|------|------|------| +| `path` | string | ✅ | 文件路径 | +| `content` | string | ✅ | 追加的文本内容 | + +### 返回结构 + +```json +{ "path": "...", "bytes_written": 128, "new_size": 1024 } +``` + +> 避免 read-merge-write 竞态：日志追加/增量写入直接用此工具。 + +--- + +## file_info + +获取文件或目录的元信息，**不读取文件内容**。 + +### 参数 + +| 参数 | 类型 | 必填 | 说明 | +|------|------|------|------| +| `path` | string | ✅ | 文件/目录路径 | + +### 返回结构 + +```json +{ + "path": "...", + "exists": true, + "size": 145, + "lines": 30, + "modified": 1718400000000, + "is_binary": false, + "is_dir": false +} +``` + +- `exists: false` 时其余字段不返回 +- `lines`：文本文件 `\n` 计数（>2MB 跳过，二进制不返回） +- `is_binary`：读前 8KB 检测 `\x00` + +--- + +## list_directory + +列出目录内容，支持递归和深度控制。 + +### 参数 + +| 参数 | 类型 | 必填 | 说明 | +|------|------|------|------| +| `path` | string | ✅ | 目录路径 | +| `recursive` | boolean | ❌ | 是否递归，默认 false | +| `max_depth` | number | ❌ | 递归最大深度，默认 3 | +| `skip_noise_dirs` | boolean | ❌ | 跳过 node_modules/.git/target，默认 **true** | + +### 返回结构 + +```json +{ + "path": "...", + "entries": [ + { "name": "src", "type": "directory", "size": 0, "depth": 0 }, + { "name": "main.ts", "type": "file", "size": 466, "depth": 0 } + ], + "truncated": false +} +``` + +--- + +## search_files + +按文件名模式搜索文件（字符串包含匹配，非 glob）。 + +### 参数 + +| 参数 | 类型 | 必填 | 说明 | +|------|------|------|------| +| `path` | string | ✅ | 搜索根目录 | +| `pattern` | string | ✅ | 文件名匹配模式（子串包含） | +| `recursive` | boolean | ❌ | 是否递归，默认 true | + +### 返回结构 + +```json +{ + "path": "...", + "pattern": ".ts", + "results": [{ "path": "src/main.ts", "size": 466 }], + "total": 5 +} +``` + +> 最多返回 50 条。结构化 JSON 输出，比 parse `find` 命令更可靠。 + +--- + +## rename_file + +重命名或移动文件（一个工具覆盖 rename + move）。 + +### 参数 + +| 参数 | 类型 | 必填 | 说明 | +|------|------|------|------| +| `from` | string | ✅ | 源文件路径 | +| `to` | string | ✅ | 目标路径 | +| `overwrite` | boolean | ❌ | 目标存在时是否覆盖，默认 false（拒绝） | + +### 行为规则 + +- **同卷**：`tokio::fs::rename`（原子操作，Windows 走 `MoveFileExW` UTF-16 API，**中文路径零字符集问题**） +- **跨卷**：自动降级 `copy + remove`（非原子，失败回滚删 to 保 from 完整） +- 仅支持文件（不支持目录，目录操作用 `run_command`） +- 返回 `{ renamed, bytes_moved, cross_volume }` + +> **为什么不用 run_command mv**：run_command 走 shell.rs 的 PS/cmd 链，中文路径经 GBK 解码 UTF-8 会 mojibake → exit 0 静默失败。此工具 Rust 原生 std::fs 绕开整个 shell 层。 + +--- + +## delete_file + +删除文件，默认软删除（移入回收站可恢复）。 + +### 参数 + +| 参数 | 类型 | 必填 | 说明 | +|------|------|------|------| +| `path` | string | ✅ | 文件路径 | +| `permanent` | boolean | ❌ | true=硬删除不可恢复，false（默认）=软删除移入 `.trash/` | + +### 返回结构 + +```json +// 软删除 +{ "path": "...", "deleted": true, "permanent": false, "backed_up": true, "backup_path": ".trash/abc-file.md" } +// 硬删除 +{ "path": "...", "deleted": true, "permanent": true, "backed_up": false } +``` + +- 仅支持文件（不支持目录） +- 软删除文件移到 `workspace/.trash/-`，对齐 `list_trash` 机制 + +--- + +## run_command + +在指定工作目录执行 shell 命令。 + +### 参数 + +| 参数 | 类型 | 必填 | 说明 | +|------|------|------|------| +| `command` | string | ✅ | shell 命令（非交互式） | +| `working_dir` | string | ❌ | 工作目录（默认 workspace 根） | +| `timeout_secs` | number | ❌ | 超时秒数，默认 60 | + +### 返回结构 + +```json +{ + "command": "npm test", + "working_dir": "...", + "exit_code": 0, + "duration_ms": 3200, + "stdout": "测试输出...", + "stderr": "", + "truncated": false +} +``` + +- stdout/stderr 各截断 10KB（尾部保留，报错堆栈在末尾） +- `truncated: true` 表示输出被截断 + +### 安全边界 + +- **High 风险**，强制人工审批（审批卡显示 command + working_dir） +- 唯一防线：人审 + `validate_path` 黑名单 +- 未做命令黑名单/网络检测/资源限制 + +### ⚠️ 已知限制 + +- **中文路径**：shell.rs 在 Windows 走 PS/cmd 链，中文路径经 GBK 解码可能 mojibake → exit 0 静默失败。涉及中文路径的文件操作请用原生工具（`rename_file`/`delete_file` 等） +- 非交互式：避免需要用户输入的程序 + +--- + +## 快速参考：常见操作怎么做 + +| 我想要... | 推荐工具 | +|-----------|---------| +| 读文件全文 | `read_file(path)` | +| 读第 10~15 行 | `read_file(path, offset=9, limit=6)` | +| 搜索文件内关键词 | `read_file(path, search="keyword")` | +| 创建新文件 | `write_file(path, content)` | +| 修改文件中某几行 | `patch_file(path, old_text, new_text)` | +| 追加内容到文件末尾 | `append_file(path, content)` | +| 写入二进制文件（图片/PDF） | `write_file(path, base64_content, encoding="base64")` | +| 重命名/移动文件 | `rename_file(from, to)` | +| 删除文件 | `delete_file(path)` | +| 获取文件大小/行数/类型 | `file_info(path)` | +| 列出项目结构 | `list_directory(path, recursive=true, max_depth=3)` | +| 搜索文件名 | `search_files(path, pattern=".ts")` | +| 跑测试/构建 | `run_command("npm test")` | diff --git a/docs/INDEX.md b/docs/INDEX.md index 319fc3f..84b5e16 100644 --- a/docs/INDEX.md +++ b/docs/INDEX.md @@ -1,7 +1,7 @@ # DevFlow 文档索引 > 创建: 2026-06-10 | 当前阶段: Phase 2 本地优先开发流程验证 -> 更新: 2026-06-14 | 新增功能创意池（5 个架构创意：演化/时效/回溯/债务/契约，待评估） +> 更新: 2026-06-16 | 文件操作工具手册更新（10 工具全量）；任务推进链决策定稿；06-15/16 审查文档补录 --- @@ -12,6 +12,7 @@ docs/ ├── README.md # 快速开始与文档导航 ├── INDEX.md # 本文件 — 文档导航 ├── todo.md # 工作看板（任务/bug 跟踪） +├── 待决策论证-2026-06-16.md # 7 项决策论证（D-01~04 已定 / DEC-01~03 已闭环） ├── 01-技术文档/ │ ├── SQLite-CRUD模式-2026-06-12.md │ └── Tauri-IPC模式-2026-06-12.md @@ -31,9 +32,13 @@ docs/ │ ├── B-03-人工审批响应机制-2026-06-14.md │ ├── aichat审查报告-2026-06-14.md # AI Chat 模块代码审查 │ ├── aichat异步审批构想-2026-06-14.md +│ ├── aichat交互体验改进方案-2026-06-14.md +│ ├── aichat授权体验改进方案-2026-06-14.md │ ├── aichat信息密度构想-2026-06-14.md │ ├── 任务推进构想-2026-06-14.md +│ ├── 任务推进链实施路径-2026-06-16.md # 4 阶段实施路径（阶段1决策已定） │ ├── aichat流式Markdown渲染调研-2026-06-15.md # 流式渲染优化方案（rAF节流/块级diff/换库） +│ ├── patch_file工具设计-2026-06-15.md # patch_file 完整设计（API/三层防御/边界情况） │ ├── 工作流审批审查报告-2026-06-14.md │ ├── F-07-df-ai-core-trait下沉设计-2026-06-14.md │ ├── 密钥迁移健壮性-2026-06-15.md @@ -61,23 +66,27 @@ docs/ │ ├── 架构审查-2026-06-15.md # 纯架构层（边界/依赖/抽象/扩展性），8 crate + 前端（2 路并行） │ ├── 自研块级memo流式渲染审查-2026-06-15.md # ARC-260615-08 实施走查（splitBlocks/parseBlock/rAF） │ ├── 工作区多角度走查-2026-06-15.md # 工作区22文件547行4路并行（selectType/队列收尾/骨架屏/i18n/DRY） -│ ├── 定时走查-2026-06-15-P0复核.md # 定时走查第1轮：B-34已修（B-32·33结论后被第2轮纠正为已修）/B-35 broadcast Lagged新P0/aiShared破环亮点 -│ ├── 定时走查-2026-06-15-第2轮.md # 定时走查第2轮：B-32·33·34全修确认（第3次纠正过时）/AR-11前端listener永不attach新P0/ARC-05 store拆分优/CR-11健壮性✅ -│ ├── 定时走查-2026-06-15-第3轮.md # 定时走查第3轮：走查价值闭环(AR-11/B-35/CR-18·19全修确认+CR-20撤销误判)/前端P0全闭环/CR-21 App.vue try/catch轻量 -│ ├── 定时走查-2026-06-15-第4轮.md # 定时走查第4轮：i18n垂直切片(key树466全对齐优秀)/硬编码40+处(CR-08扩展)/P1-1 useAiEvents:182 i18n破坏bug改一行最高ROI -│ ├── 定时走查-2026-06-15-第5轮.md # 定时走查第5轮：api垂直切片/Tauri v2默认转camelCase权威裁决(代理A 6处IPC遗漏假阳性纠正)/B-34错误注释传播误导(CR-23)/types对齐良好 -│ ├── 定时走查-2026-06-15-第6轮.md # 定时走查第6轮：列表页+Dashboard+AI窗口垂直切片/分离窗口生命周期P1(listener双注册+永不清理CR-24)/状态机缺口(CR-25)/列表页契约(CR-26)/Dashboard(CR-27) -│ ├── 定时走查-2026-06-15-第7轮.md # 定时走查第7轮：stores垂直切片/CR-24·26·27三修确认(价值第6闭环)/knowledge error通道断P1(CR-28,CR-08深化)/ai.ts状态机完整亮点(验证修复质量) -│ ├── 定时走查-2026-06-15-第8轮.md # 定时走查第8轮(前端收尾)：CR-25·28·30三修确认(价值第7闭环)/CR-30污染修复/收尾小区域无必修(CR-31 useConfirm/ToolCardList)+5亮点(XSS防护链/useConfirm DRY)/8轮总结+停止cron建议 +│ ├── 定时走查-2026-06-15-P0复核.md # 定时走查第1轮 +│ ├── 定时走查-2026-06-15-第2轮.md # 定时走查第2轮 +│ ├── 定时走查-2026-06-15-第3轮.md # 定时走查第3轮 +│ ├── 定时走查-2026-06-15-第4轮.md # 定时走查第4轮 +│ ├── 定时走查-2026-06-15-第5轮.md # 定时走查第5轮 +│ ├── 定时走查-2026-06-15-第6轮.md # 定时走查第6轮 +│ ├── 定时走查-2026-06-15-第7轮.md # 定时走查第7轮 +│ ├── 定时走查-2026-06-15-第8轮.md # 定时走查第8轮（前端收尾） │ ├── 全局代码review-2026-06-15.md # 7维度并行（DRY/架构/bug/安全/AI可靠/工作流），P1×6+P2×13全闭环 -│ └── 文档全量核对报告-2026-06-15.md # docs全量+根目录4路核对（ARCHITECTURE漂移/模块文档过期/审查状态断层） +│ ├── 文档全量核对报告-2026-06-15.md # docs全量+根目录4路核对（ARCHITECTURE漂移/模块文档过期/审查状态断层） +│ ├── 任务模块问题分析-2026-06-16.md # 任务模块18项核对（真bug 7+增强5+假3+去重3） +│ └── 任务执行与推进能力分析-2026-06-16.md # 推进能力实现度0%，4阶段路径+决策点 ├── 06-前端开发/ │ └── View改造指南-2026-06-12.md ├── 07-项目管理/ │ ├── Phase1任务清单-2026-06-12.md │ └── Phase2计划-2026-06-12.md ├── 08-用户指南/ -│ └── 使用手册-2026-06-12.md +│ ├── 使用手册-2026-06-12.md # 用户手册（对齐 06-15 代码基线） +│ ├── AI文件操作工具手册.md # AI 工具 API 全量参考（10 工具，2026-06-16 更新） +│ └── patch_file使用指南.md # patch_file 专项使用指南 └── 09-问题排查/ └── aichat-apikey-401排查-2026-06-15.md ``` @@ -90,6 +99,7 @@ docs/ |------|------|------| | 🚀 快速开始 | [README.md](./README.md) | 安装、启动、快速上手 | | 📖 使用手册 | [使用手册-2026-06-12.md](./08-用户指南/使用手册-2026-06-12.md) | 用户手册 | +| 🔧 AI 工具手册 | [AI文件操作工具手册.md](./08-用户指南/AI文件操作工具手册.md) | 10 个文件操作工具 API 参考 | | 📋 项目进度 | [PROGRESS.md](../PROGRESS.md) | 实时项目进展与状态 | | ⚙️ 技术文档 | [01-技术文档/](./01-技术文档/) | SQLite CRUD、Tauri IPC 等技术专题 | | 🏗️ 架构设计 | [02-架构设计/](./02-架构设计/) | 架构方案、设计决策、产品定位调整 | @@ -98,7 +108,7 @@ docs/ | 🔍 代码审查 | [05-代码审查/](./05-代码审查/) | 审查报告、代码质量分析 | | 🎨 前端开发 | [06-前端开发/](./06-前端开发/) | Vue 3 前端分析、优化、迁移指南 | | 📊 项目管理 | [07-项目管理/](./07-项目管理/) | 任务清单、开发计划、进度跟踪 | -| 📚 用户指南 | [08-用户指南/](./08-用户指南/) | 快速上手、配置指南、FAQ | +| 📚 用户指南 | [08-用户指南/](./08-用户指南/) | 使用手册、工具指南、FAQ | | 🐛 问题排查 | [09-问题排查/](./09-问题排查/) | 排查记录、根因分析 | --- @@ -122,8 +132,9 @@ docs/ | 文档 | 路径 | 说明 | |------|------|------| -| 架构设计 | `../ARCHITECTURE.md` | 22,745 字完整架构文档 | +| 架构设计 | `../ARCHITECTURE.md` | 完整架构文档 | | 项目进展 | `../PROGRESS.md` | 工作进展与交接 | +| 工作看板 | `./todo.md` | 任务/bug 跟踪（含决策记录） | | Crate 结构 | `../ARCHITECTURE.md#四crate-结构` | 8 个 Crate 概览 | | 数据模型 | `../ARCHITECTURE.md#六数据模型` | SQLite 表结构定义 | | Phase 规划 | `../ARCHITECTURE.md#八phase-规划` | 5 个 Phase 路线图 | @@ -139,4 +150,4 @@ docs/ | Engine | Rust Workspace (8 crate) | 多 crate 架构 | | Storage | SQLite (rusqlite) | 本地优先，零运维 | | AI | Multi-Provider | Claude/GLM/DeepSeek/OpenAI 兼容 | -| Build | Bun + Vite | 前端构建 | +| Build | npm + Vite | 前端构建（不要使用 bun） | diff --git a/docs/ai-file-ops-manual.md b/docs/ai-file-ops-manual.md deleted file mode 100644 index d10653f..0000000 --- a/docs/ai-file-ops-manual.md +++ /dev/null @@ -1,189 +0,0 @@ -# AI 文件操作工具能力手册 - -> 最后更新：2026-06-15 | 基于全量测试验证 - ---- - -## 工具总览 - -| 工具 | 用途 | 可靠性 | -|------|------|--------| -| `read_file` | 读取文件内容（全文/分页） | ✅ 高 | -| `write_file` | 创建/覆盖写入文件（纯文本） | ✅ 高 | -| `list_directory` | 列出目录内容（含递归/深度控制） | ✅ 高 | -| `run_command` | 执行 shell 命令 | ⚠️ 可执行，但 stdout 不可用 | - ---- - -## read_file - -读取文件内容，支持分页。 - -### 参数 - -| 参数 | 类型 | 必填 | 说明 | -|------|------|------|------| -| `path` | string | ✅ | 文件路径，支持 `/` 和 `\` | -| `offset` | number | ❌ | 起始行（0 基索引），默认 0 | -| `limit` | number | ❌ | 读取行数，默认全部 | - -### 行为规则 - -- `offset` 是 **0 基索引**：offset=0 → 第 1 行，offset=10 → 第 11 行 -- `offset` 超出总行数 → 返回空内容，**不报错** -- `limit` 超出剩余行数 → 返回到末尾，**不报错** -- 空文件 → 返回 `{ content: "", lines: 0, size: 0 }` -- 不存在的文件 → 报错 `os error 2` -- 二进制文件 → 返回 `{ binary: true, content: null, error: "文件非 UTF-8 文本" }` -- 路径越界（项目目录外）→ 被拦截 - -### 返回结构 - -```json -{ - "content": "文件文本内容", - "lines": 30, // 总行数（始终是全量值，非当前页行数） - "size": 145, // 总字节数（始终是全量值） - "path": "..." -} -``` - -> ⚠️ `lines` 和 `size` 始终返回**全量值**，不受 offset/limit 影响。 - ---- - -## write_file - -创建或覆盖写入文件，纯文本模式。 - -### 参数 - -| 参数 | 类型 | 必填 | 说明 | -|------|------|------|------| -| `path` | string | ✅ | 文件路径 | -| `content` | string | ✅ | 文本内容（UTF-8） | - -### 行为规则 - -- **自动创建多级父目录**：路径中不存在的目录会自动创建 -- **覆盖已有文件**：直接覆盖，无确认机制（⚠️ 注意安全） -- 返回 `old_size`（覆盖前大小，新建时为 null）和 `bytes_written`（写入大小） -- 支持 emoji、引号、反斜杠、中文等特殊字符 -- 路径分隔符 `/` 和 `\` 均可 -- 中文路径/文件名含空格 → 正常工作 -- 空内容（`content=""`）→ 创建 0 字节文件 -- **无法写入二进制数据**（NULL 字节等会被当文本处理） -- 路径越界（项目目录外）→ 被拦截 - -### 局部修改的正确做法 - -write_file 是全量覆盖，局部修改需三步： - -``` -1. read_file 获取完整内容 -2. AI 在内存中替换目标行/文本 -3. write_file 写回完整内容 -``` - ---- - -## list_directory - -列出目录内容，支持递归和深度控制。 - -### 参数 - -| 参数 | 类型 | 必填 | 说明 | -|------|------|------|------| -| `path` | string | ✅ | 目录路径 | -| `recursive` | boolean | ❌ | 是否递归，默认 false | -| `max_depth` | number | ❌ | 递归最大深度（配合 recursive） | -| `skip_noise_dirs` | boolean | ❌ | 跳过 node_modules/.git 等，默认 false | - -### 返回结构 - -```json -{ - "entries": [ - { "name": "src", "type": "directory", "size": 0, "depth": 0 }, - { "name": "main.ts", "type": "file", "size": 466, "depth": 0 } - ], - "truncated": false -} -``` - -### 行为规则 - -- `type` 取值：`"directory"` | `"file"` -- `depth`：0 = 根层级，1 = 一级子目录，以此类推 -- 不存在的目录 → 报错 `os error 3` -- `truncated: false` 表示结果完整未截断 - ---- - -## run_command - -执行 shell 命令。 - -### 参数 - -| 参数 | 类型 | 必填 | 说明 | -|------|------|------|------| -| `command` | string | ✅ | shell 命令（非交互式） | -| `working_dir` | string | ❌ | 工作目录 | -| `timeout_secs` | number | ❌ | 超时秒数，默认 60 | - -### ⚠️ 已知问题 - -**stdout 始终返回空字符串**（已确认是普遍问题）： -- `echo`、`Write-Output` 等输出无法被捕获 -- 命令本身**能正常执行**（cp/mv/rm/重定向写文件均验证通过） -- stderr 大部分场景也为空 - -### 可靠使用的场景 - -| 场景 | 可靠性 | 示例 | -|------|--------|------| -| 删除文件 `rm` | ✅ | `rm -f path/to/file` | -| 复制文件 `cp` | ✅ | `cp src.txt dst.txt` | -| 移动/重命名 `mv` | ✅ | `mv old.txt new.txt` | -| 创建目录 `mkdir` | ✅ | `mkdir -p deep/nested/dir` | -| 写入文件（重定向） | ✅ | `echo content > file.txt` | -| 二进制写入 `printf` | ✅ | `printf '\x89PNG' > file.png` | -| 超时控制 | ✅ | `timeout_secs=3` 正确中断 | -| 工作目录切换 | ✅ | `working_dir` 生效，相对路径可用 | -| 获取命令输出 | ❌ | stdout/stderr 不可用 | - ---- - -## 快速参考：常见操作怎么做 - -| 我想要... | 工具调用 | -|-----------|---------| -| 读文件全文 | `read_file(path)` | -| 读第 10~15 行 | `read_file(path, offset=9, limit=6)` | -| 创建新文件 | `write_file(path, content)` | -| 修改文件中某几行 | `read_file` → AI 替换 → `write_file` | -| 追加内容到文件末尾 | `read_file` → 拼接 → `write_file` | -| 删除文件 | `run_command("rm -f path")` | -| 重命名文件 | `run_command("mv old new")` | -| 列出项目结构 | `list_directory(path, recursive=true, max_depth=3)` | -| 搜索文件内容 | 分页 `read_file` 逐段扫描（无原生搜索） | -| 搜索文件名 | `list_directory` 递归 + AI 过滤（无原生 glob） | -| 写入二进制文件 | `run_command("printf '\x89...' > file")` | -| 获取文件大小/行数 | `read_file`（必须读内容，无轻量元信息工具） | - ---- - -## 待实现能力（已建任务） - -| 能力 | 任务 ID | 优先级 | -|------|---------|--------| -| 文件内容搜索 `search_in_file` | F-FILE-01 | P1 | -| 文件局部更新 `patch_file` | F-FILE-02 | P1 | -| 文件元信息 `file_info` | F-FILE-03 | P1 | -| run_command stdout 修复 | F-FILE-07 | P1 | -| 追加写入 `append_file` | F-FILE-04 | P2 | -| 文件名搜索 `search_files` | F-FILE-05 | P2 | -| Base64 二进制写入 | F-FILE-06 | P2 | -| 文件差异对比 `diff_file` | F-FILE-08 | P3 |