新增: 文档(任务推进链实施路径+任务模块分析+审查报告+patch_file指南)

docs/08-用户指南/patch_file使用指南.md

@@ -0,0 +1,107 @@
+# patch_file 使用指南
+
+> 创建: 2026-06-15
+> 关联设计: docs/02-架构设计/patch_file工具设计-2026-06-15.md
+
+## 使用场景
+
+局部更新文件（替代 read-merge-write 多步流程），精确定位 `old_text` 并替换为 `new_text`。
+
+适用于只改文件中某几行的场景：大文件改 3 行无需重发全部内容，避免 `write_file` 全量覆盖的事故风险（参见 FR-S7 记录：762 行文件被覆盖为 248 字节）。
+
+## API 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `path` | 是 | 目标文件路径（workspace 内，走 `validate_path` 校验 + 黑名单） |
+| `old_text` | 是 | 要替换的精确文本（必须与文件内容完全匹配，含空格/缩进；充当乐观锁） |
+| `new_text` | 是 | 替换后的新文本 |
+| `line` | 否 | 行号辅助定位（快速跳转 + 去歧增强；有值时优先跳到该行检查 `old_text`，不匹配则降级全文扫描） |
+| `expected_hash` | 否 | 文件指纹防脏写，格式 `"{unix_timestamp}_{size}"`（如 `"1718400000_12345"`），由 `read_file` 返回的 `file_hash` 字段携带 |
+
+补充去歧参数（可选）：`before_text` / `after_text` —— 当 `old_text` 多处匹配时，作为上下文锚精确锁定目标位置。
+
+## 返回值
+
+```json
+{
+  "success": true,
+  "patches_applied": 1,
+  "total_matches": 1,
+  "lines_changed": 2,
+  "warnings": [],
+  "file_hash": "1718400000_12400"
+}
+```
+
+| 字段 | 含义 |
+|------|------|
+| `success` | 是否成功 |
+| `patches_applied` | 成功替换的 patch 数 |
+| `total_matches` | 每个 patch 的总命中数（含未替换的） |
+| `lines_changed` | 总行数变化（正=增加，负=减少） |
+| `warnings` | 警告信息，如 `["匹配到 3 处，仅替换第 1 处"]` |
+| `file_hash` | 操作后的新指纹（下次操作传入 `expected_hash` 用） |
+
+## 安全边界
+
+- **RiskLevel Medium**：修改已有文件，需人工审批
+- **自动 `.bak` 备份**：复用 FR-S7 已有逻辑，误操作可恢复
+- **old_text 不匹配 → 报错**（不修改文件，避免盲替换）
+- **expected_hash 不匹配 → 报错**（防并发脏写，提示「文件已被外部修改，请重新读取」）
+- **三层防御**：L1 文件级 Mutex（防时机冲突）+ L2 old_text 精确匹配（防内容错配）+ L3 expected_hash 指纹校验（防版本漂移），底层兜底 `.bak` 备份
+
+## 最佳实践
+
+- **old_text 取足够上下文确保唯一**：避免短串多处匹配，收到「匹配到 N 处」warning 时用 `before_text`/`after_text` 锚定或加长 `old_text` 重试
+- **大段修改用多个小 patch 而非一个巨大 patch**：每个 patch 独立校验，失败可定位
+- **危险操作前先 `file_info` 确认**：核对路径、大小、是否二进制（含 `\0` 的文件会被拒绝）
+- **read → patch 链路带上 hash**：`read_file` 返回 `file_hash`，传入 `patch_file` 的 `expected_hash` 形成乐观锁闭环
+- **多 patch 从文件末尾往前排**：避免行号偏移（工具内部已按此执行）
+- **old_text 必须完全匹配**：含空格、缩进、换行，复制粘贴原文最稳妥
+
+## 示例
+
+### 基础替换
+
+```json
+{
+  "path": "src/main.rs",
+  "old_text": "fn old()",
+  "new_text": "fn new()"
+}
+```
+
+### 带 hash 乐观锁
+
+```json
+{
+  "path": "src/main.rs",
+  "expected_hash": "1718400000_12345",
+  "patches": [
+    { "old_text": "fn old()", "new_text": "fn new()" }
+  ]
+}
+```
+
+### 多处匹配用 line 锚定
+
+```json
+{
+  "path": "src/main.rs",
+  "old_text": "return Ok(())",
+  "new_text": "return Ok(value)",
+  "line": 42
+}
+```
+
+## 边界情况
+
+| 情况 | 行为 |
+|------|------|
+| 文件不存在 | 报错「文件不存在」 |
+| 二进制文件（含 `\0`） | 报错「不支持二进制文件」 |
+| `old_text` 为空串 | 报错「old_text 不能为空」 |
+| `new_text` == `old_text` | 成功 + warning「无实际更改」 |
+| 路径含 `..` | `validate_path` 黑名单拦截 |
+| 目标是 `.bak`/`.tmp` | 拒绝（CR-03 噪声文件过滤） |

docs/08-用户指南/使用手册-2026-06-12.md

@@ -123,8 +123,11 @@ npm run tauri build
 
 #### 工具调用
 - **生成代码**：根据描述生成完整实现
-- **文件操作**：读取、编辑项目文件
-- **Git 操作**：提交、推送、合并
+- **文件操作**：读取、写入（write_file）、局部编辑（patch_file）、追加（append_file）、搜索（search_files）项目文件
+- **项目管理**：创建/更新/删除项目、绑定目录
+- **任务管理**：创建/更新/删除任务
+- **Shell 执行**：在项目目录运行命令（run_command，需人工审批）
+- **知识库**：自动提炼对话经验到知识库
 
 ## 💡 想法池功能
 
@@ -138,9 +141,19 @@ npm run tauri build
 ```
 
 ### 状态管理
-- **草稿**：初始想法
-- **活跃**：正在考虑
-- **已完成**：已实现或放弃
+
+想法共 6 个状态（对齐 `crates/df-core/src/types.rs` 的 `IdeaStatus` 枚举）：
+
+| 状态值 | 含义 | 说明 |
+|--------|------|------|
+| `draft` | 草稿 | 初始创建 |
+| `pending_review` | 待评估 | 已提交，等待 AI/人工评估 |
+| `approved` | 已批准 | 评估通过，可晋升为项目 |
+| `rejected` | 已拒绝 | 评估未通过 |
+| `promoted` | 已晋升 | 已转为项目（`promoted_to` 写入目标 project_id）|
+| `archived` | 已归档 | 历史归档 |
+
+典型流转：`draft → pending_review → approved → promoted`（正向）/ `→ rejected → archived`（淘汰）。
 
 ### 未来升级
 - **对抗式评估**：正方+反方+分析师
@@ -175,7 +188,6 @@ npm run tauri build
 ### 个人效能
 - **任务完成率**：按时完成任务比例
 - **分支管理**：活跃分支数量
-- **工作流成功率**：自动执行成功率
 
 ### 项目进度
 - **阶段分布**：规划/开发/测试/上线
@@ -241,7 +253,6 @@ npm run tauri build
 
 - 问题反馈：创建 Issue
 - 功能建议：想法池提交
-- 使用交流：Discord 社区
 
 ---