# 全量走查报告（2026-06-28）

> 范围：全栈 Rust 12 crate + Tauri 命令层 + Vue 3 前端 + 文档体系
> 方法：3 路并行（Rust 后端/Vue 前端/文档体系），主代理综合整理
> 原则：dry — 仅审查 + 文档，不改代码

---

## 🔴 安全

### ① relay.rs — 硬编码默认 Token

**文件**: `crates/df-relay/src/relay.rs:36-37`

中继服务使用硬编码 `DEFAULT_TOKEN = "devflow-relay-default-token"`，所有未设环境变量的部署均使用同一静态 token。通过 `strings` 即可从二进制提取。

**建议**：启动时要求必须设置 `DF_RELAY_TOKEN` 环境变量，移除默认值。

### ② models.rs — `AiProviderRecord` Debug 未脱敏 api_key，日志泄漏风险

**文件**: `crates/df-storage/src/models.rs:288`

`AiProviderRecord` 未实现自定义 `Debug` 对 `api_key` 脱敏。若上层代码意外 `{:?}` 打印（如 `tracing::debug!`），明文 API key 会写入日志。`model_configs`（L296）与 `config`（L298）等 JSON 字段同样不安全。

**建议**：为 `AiProviderRecord` 实现自定义 `Debug`，将 `api_key` 输出为 `"sk-****"`。

### ③ ScriptNode — 命令无白名单/沙箱

**文件**: `crates/df-nodes/src/script_node.rs:15-19` + `crates/df-execute/src/shell.rs:92-117`

ScriptNode 从 config 取 `command` 字符串透传给 shell（`cmd /C` / `sh -c`），无任何命令白名单或参数校验。工作流定义来自 AI 生成或外部导入时，恶意命令可通过 AINode 写入 ScriptNode config 注入执行。

**建议**：添加危险命令关键词告警（`rm -rf`/`DROP TABLE`/`Format`），可选白名单/环境变量隔离配置。

### ④ bind_directory — 原始路径入库未规范化 + 无沙箱校验

**文件**: `crates/df-mcp/src/tools.rs:314-342`

`bind_directory` 接收用户传入 `path`，`normalize_path` 仅用于去重检测，**原始 `path` 值直接存储**。同一目录可用两种写法绑定两次绕过冲突检测。且未校验规范化后路径在项目沙箱允许范围内。

**建议**：存储前 `normalize_path()` + 校验在沙箱目录内 + 拒绝含 `..` 的原始路径。

### ⑤ state.rs — `std::sync::Mutex` 在 async 上下文中持锁风险

**文件**: `crates/df-workflow/src/state.rs:34-36, 55, 97, 104`

`StateMachine` 使用 `std::sync::Mutex` 保护 HashMap，在 `get()` 等同步方法中直接 `lock().expect()`。`DagExecutor` 在 `futures::future::join_all` 同层并发时，若某节点持有引用后 `.await` 另一操作间接尝试锁 `states`，会死锁。通篇 4 处 `expect`——某节点 panic 导致锁中毒，连锁 fatal。

**建议**：改用 `tokio::sync::Mutex`，或在文档中明确标注「state_machine 方法不得在 `.await` 期间持锁」。

### ⑥ eventbus.rs — 错误静默吞噬

**文件**: `crates/df-workflow/src/eventbus.rs:16, 32`

`DEFAULT_CAPACITY: usize = 256`，`EventBus::send` 调用处 `let _` 吞噬所有错误。当并发节点多且事件消费慢时，256 溢出导致最早接收者 Lagged 错误。

**建议**：`send` 处 `tracing::warn!` 记录 Lagged 错误。

### ⑦ shell.rs — `probe_pwsh` 同步阻塞 tokio 运行时

**文件**: `crates/df-execute/src/shell.rs:53-66`

`probe_pwsh()` 在 `Default::default()` 中调用，`Default` 在 `execute()` 异步函数内调用。在 tokio 异步函数中同步阻塞 `cmd.status()` 违反最佳实践。

**建议**：惰性异步探测（`OnceLock` 配 `tokio::task::spawn_blocking`）。

### ⑧ retry.rs — backoff jitter 随机性弱

**文件**: `crates/df-ai/src/retry.rs:77-81`

jitter 使用 `SystemTime::now().duration_since().subsec_nanos() % 2000` 映射到 `[-1.0, 1.0)`。纳秒级退化到 1ms 粒度时多个请求可能拿到同一值，重试碰撞风险。

**建议**：改用 `fastrand`，jitter 范围扩大到 ±50%（当前 ±20%）。

---

## 🔴 文档

### ⑨ AI对话引擎-2026-06-14.md — 工具清单严重过时

**文件**: `docs/03-模块文档/AI对话引擎-2026-06-14.md §四`

标题自称"12 个"工具，表格实际列出 **13 行**（自相矛盾）；与 `df-ai-AI集成模块-2026-06-12.md` 声称的 **22 个工具**严重对不齐；缺失 `run_command`/`patch_file`/`list_trash`/`file_info`/`search_files`/`delete_task`/`restore_project`/`purge_project` 等工具。

**建议**：全文同步至当前实际 22 个工具的最新清单。

### ⑩ 02-架构设计/INDEX.md — 漏索引 9 个已有文档

**文件**: `docs/02-架构设计/INDEX.md`

| 子目录 | 漏列数 | 典型遗漏 |
|-------|-------|---------|
| 专项设计 | 7 | `AI原生上下文地图`、`AST符号解析`、`插件机制`、`查询能力补全方案`、`项目知识图谱` 等 |
| 已编号方案 | 2 | `F-260622-01-跨端AIChat-Phase3联调设计`、`消息级溯源P2-切读方案`（今天新增） |
| 构想审查 | 1 | `跑题改进试验记录` |
| 根目录 | 2 | `单对话并行多轮-Phase0落地路线图`、`单对话并行多轮-设计` |

**建议**：批量补齐，建立「新增文档 → 立即更新 INDEX」的提交习惯。

### ⑪ Agent架构说明 — 死链

**文件**: `docs/02-架构设计/专项设计/Agent架构说明-2026-06-14.md:4`

```markdown
> 关联: [任务推进设计](任务推进构想-2026-06-14.md)
```
目标文件在 `构想审查/` 下，当前路径解析到 `专项设计/` 下不存在。

**建议**：改为 `[任务推进设计](../构想审查/任务推进构想-2026-06-14.md)`。

### ⑫ ARCHITECTURE.md §七 + 新设计文档 — 大段逐字重复

**文件**: `ARCHITECTURE.md:538-665` / `docs/02-架构设计/专项设计/三层模型-流程模板与人设体系-2026-06-28.md`

YAML 模板示例（52行）、`AgentPersona` struct 定义（11行）、三层定义表、实例化流程——**大段逐字重复**，违反文档记录规范 SSOT 原则。

**建议**：`ARCHITECTURE.md §七` 保留概要（三层定义 + 关系图 + 关键原则），YAML 全文和 struct 定义仅在专项设计文档展开，ARCH 以引用链接替代。

### ⑬ ARCHITECTURE.md 仍保留 ~100 行已移除模块细节

**文件**: `ARCHITECTURE.md:210-318`（`df-task` / `df-traceability` 章节）

保留 Task 生命周期图、分支策略、标注系统、需求-功能-测试映射、Decision struct 等已移除模块的详细设计。造成认知负担。

**建议**：将已移除模块的详细历史移至 `功能决策记录-归档`，ARCHITECTURE.md 仅保留「已移除，见归档」。

### ⑭ 模块文档更新停滞（最长 16 天）

| 文档 | 最后更新 | 距今天数 |
|-----|---------|---------|
| `df-workflow-工作流引擎-2026-06-12.md` | 06-15 | 13 天 |
| `df-ai-AI集成模块-2026-06-12.md` | 06-14 | 14 天 |
| `df-storage-存储层-2026-06-12.md` | 06-15 | 13 天 |
| `想法探索-对抗式评估-2026-06-12.md` | 无更新 | 16 天 |

**建议**：对上述文档做一次「代码对齐」检查。

### ⑮ ARCHITECTURE.md 版本状态过时

**文件**: `ARCHITECTURE.md:3`

当前 `状态: 设计阶段`。工程处于 **Phase 2 验证阶段**（df-workflow 核心完成、AI ReAct 循环运行中、审批机制就绪），状态标签与实际不符。

**建议**：改为 `状态: Phase 2 本地优先开发流程验证`（与 `docs/INDEX.md` 一致）。

### ⑯ 新设计文档与现有文档缺失交叉引用

**文件**: `docs/02-架构设计/专项设计/三层模型-流程模板与人设体系-2026-06-28.md`

应当引用但未引用：`全局事件数据总线`、`df-nodes-节点集合`、`任务推进构想`。

**建议**：补充上述交叉引用。

### ⑰ AI对话引擎文档边界归属模糊

**文件**: `docs/03-模块文档/AI对话引擎-2026-06-14.md`

位于 `03-模块文档/`，但内容大量描述 `src-tauri/commands/ai/` 下的 Tauri 层代码，而非 `crates/df-ai` crate 内部。按文档记录规范职责矩阵，`03-模块文档/` 应记录各 crate 实现细节。

**建议**：移入 `02-架构设计/` 适当子目录，或明确标注为跨层交互设计文档。

---

## 🟡 代码质量

### ⑱ dag.rs — `deep_merge` 收到 null 返回 null，覆盖全局配置

**文件**: `crates/df-workflow/src/dag.rs:174-192`

`deep_merge(global, null)` 返回 `null`。若某节点定义写了 `"config": null`（JSON 显式 null），该节点 `ctx.config = Value::Null`，原本期望继承全局 config 的节点拿到空配置。

**建议**：`DagExecutor.run()` 中对 `deep_merge` 结果做 `if result.is_null() { initial_config.clone() }` 兜底。

### ⑲ dag.rs — `_` 通配 match 掩盖未覆盖变体

**文件**: `crates/df-workflow/src/dag.rs:191`

`deep_merge` 的 match 最后分支 `_ => node.clone()` 过于宽泛。若未来新增 `serde_json::Value` 变体，不会被编译器捕获。

**建议**：显式列出所有剩余变体并 `bail!`，迫使维护者在修改时意识到影响。

### ⑳ shell.rs — `String::from_utf8_lossy` 编码错误被静默替换

**文件**: `crates/df-execute/src/shell.rs:155-156`

shell 输出使用 `String::from_utf8_lossy`，将非 UTF-8 字节替换为 `�`。对于中文/日文环境（如 `chcp 65001` 前的 GBK 输出），用户看到乱码替代符，诊断困难。

**建议**：添加 `tracing::debug!` 记录损失性替换的字节数，或提供 `encoding_rs` 转码选项。

### ㉑ query LIKE 搜索 — SQL 通配符未转义

**文件**: `crates/df-storage/src/crud/project_repo.rs:245-246`

`LIKE ?` 使用 `%{trimmed}%` 拼接，`keyword` 中的 `%`/`_` 会被字面匹配。用户搜索 `100%` 匹配所有行，搜索 `error_404` 匹配 `errorX404`。

**建议**：对 keyword 中的 `%`/`_` 做 `replace` 转义，加 `ESCAPE '\'` 子句。

### ㉒ coordinator.rs — 空壳仅用注释声明"勿删"，应加编译期守卫

**文件**: `crates/df-ai/src/coordinator.rs:1-24`

注释声明「B 路线占位，有意保留空壳，勿删」，但无 `#[deprecated]` 或 `#[doc(hidden)]` 编译期标记。调用方引入 `AgentCoordinator::new().run()` 只能运行时发现返回 `"TODO"`。

**建议**：加 `#[deprecated(note = "B 路线占位，勿用于生产")]`。

### ㉓ secret.rs — 密钥迁移 sidecar 文件写入无原子性

**文件**: `crates/df-storage/src/secret.rs:75-81`

`record_migration_fail` 每次调用同步读文件 → 改 map → 写文件，迁移时 10+ provider 逐条失败时每条 2 次文件 I/O。无原子写入保障，异常中断可能产生半写文件。

**建议**：积累内存中的失败计数，迁移循环结束后一次性持久化。

### ㉔ Intent/planner/plan_hint — 纯函数模块无单测覆盖

**文件**: `crates/df-ai/src/intent.rs` / `planner.rs` / `plan_hint.rs`

注释声称「纯函数、零 IO」，均无 `#[cfg(test)]` 覆盖。Phase 1 接入主 loop 前应补充。

**建议**：为这些纯函数模块补充输入输出确定性匹配测试。

---

## 🟡 前端

### ㉕ Settings.vue — 内联 confirm 弹层重复实现

**文件**: `src/views/Settings.vue:7-16`

Settings.vue 内联了完整 confirm 弹层模板，完全复制了 `ConfirmDialog.vue` 的 UI/逻辑，自身维护 `confirmState`/`answerConfirm`。全项目已有 `useConfirm` composable。

**建议**：用 `useConfirm` + `ConfirmDialog` 替换内联实现。

### ㉖ 多视图 — 按钮 CSS 重复定义

**文件**: `Dashboard.vue:126-162` / `Projects.vue:445-458` / `Ideas.vue:421-432` / `Knowledge.vue:449-458`

四处视图各自定义 scoped 按钮样式。项目已通过 `main.ts` 导入全局 `styles/components.css`。

**建议**：删除视图内按钮样式，统一走全局 CSS。

### ㉗ Ideas.vue + Knowledge.vue — tags 解析逻辑重复

**文件**: `src/views/Ideas.vue:302` / `src/views/Knowledge.vue:321`

```ts
tags.split(',').map(t => t.trim()).filter(Boolean)
```

**建议**：提取为工具函数 `parseTagsInput` 放进 `src/utils/`。

### ㉘ Ideas.vue — Arco Design `Message` 残留

**文件**: `src/views/Ideas.vue:144`

全项目仅在 Ideas.vue 使用了 Arco 的 `Message` 组件（3 处），其余使用自建 toast。混用。

**建议**：用自建 `showToast` 替换后删除 Arco 依赖。

### ㉙ stores/ai.ts — 两个 watch 监听同一 `.messages.length`

**文件**: `src/stores/ai.ts:204, 241`

两个 `watch(() => state.messages.length, ...)` 分别处理条数上限和 parts 体积上限。每次 length 变化触发两个 watch，第二个还要遍历 messages 求和。

**建议**：合并为一个 watch。

### ㉚ AiChat.vue — `initDrainQueueListener` 每次 `useAiStore()` 调用都执行

**文件**: `src/stores/ai.ts:304`

```ts
void initDrainQueueListener()
```
每次调用 `useAiStore()` 都执行。需确认内部做了幂等守卫。

**建议**：确保只初始化一次（如外层 `initOnce` 布尔守卫）。

### ㉛ AiChat.vue — 空值传播无告警

**文件**: `src/components/AiChat.vue:238`

```ts
const conv = store.state.conversations.find(c => c.id === id)
const title = conv?.title || t('aiChat.newConversation')
```
`find` 返回 `undefined` 时静默回退默认标题。非预期 ID 进入时不告警。

**建议**：至少 `console.warn` 记录 ID 不在列表中的情况。

### ㉜ 多视图 — `catch (e: any)` 类型退化

**文件**: 几乎所有 Vue 视图

```ts
catch (e: any) {
  state.error = e?.toString() ?? t('xxx.failed')
}
```

**建议**：统一改为 `catch (e: unknown)`。

### ㉝ AiChat.vue — 体积仍偏大

**文件**: `src/components/AiChat.vue`（模板 128 行 + script ~200+ 行）

仍承载全局快捷键处理、编辑态管理、队列编辑态管理、Toast 共享状态等。

**建议**：将键盘快捷键抽离为 `useAiShortcuts` composable。

### ㉞ Ideas.vue — `searchQuery.trim()` 重复调用

**文件**: `src/views/Ideas.vue:219-220`

```ts
if (searchQuery.value.trim()) {
  q.keyword = searchQuery.value.trim()
}
```

**建议**：提取 `const trimmed = searchQuery.value.trim()`。

### ㉟ Projects.vue — 冗余 `as string` 断言

**文件**: `src/views/Projects.vue:217-218, 222`

`selected` 已被类型收窄为 `string`，后续 `as string` 多余。

### ㊱ MCP tools/list — `unwrap_or(Value::Null)` 在数组中混入 null

**文件**: `crates/df-mcp/src/server.rs:140-142`

```rust
serde_json::to_value(&t.tool).unwrap_or(Value::Null)
```
若某个 tool schema 序列化失败，tools 数组中混入 `null`。

**建议**：`.filter_map(|t| serde_json::to_value(&t.tool).ok())`。

### ㊲ Ideas.vue — `IdeaQuery` 类型未充分对齐

**文件**: `src/views/Ideas.vue:146, 214-217`

`order_by` 字段类型为 `string | null`，后端若收窄为联合类型白名单，前端不会报错。

**建议**：前端 `order_by` 使用 `'score' | 'created_at' | null`。

---

## ✅ 亮点

### ① 密钥管理分层设计（secret.rs）
`resolve_provider_secret` 三阶段回落：DB 明文（向前兼容）→ OS keyring → 空字符串。迁移非阻断、幂等、失败计数告警。单测通过 `cfg` gate 仅桌面 OS 跑 keyring 测试。

### ② SQL 注入防护体系
列名白名单（`validate_column_name` + `impl_repo!` 宏统一调用），`build_order_clause` 对排序方向也做白名单校验。软删除/恢复/清空全部参数化 SQL。

### ③ 前端竞态保护（knowledge.ts）
递增序列号丢弃过期响应。`ai.ts` watch 双重守卫（`oldLen > 0 && newLen - oldLen <= 2`）精确区分局部增长和整体替换。

### ④ `useConfirm` 统一确认弹层
从 4 个视图中提取重复 Promise+resolve 模式，正确处理并发覆盖场景（前一个 Promise 先 resolve false）。

### ⑤ Store 内部分拆 4 子 store
`stores/project/` 拆分为 projects/tasks/ideas/workflow，共享 `state.ts` 单例，对外 `useProjectStore()` 不变——「内部拆分，外部零改动」。

### ⑥ 取消路径 TOCTOU 三层防护
`state.rs:86-100` + `executor.rs:180-232`：Ok 后检查、Err 分支检查、阻塞节点轮询。注释详细记录了 TOCTOU 时序窗口。

### ⑦ MCP 多层防御
三级过滤：`visible()` 读模式仅 Low 工具、`tools/list` 剔除 High、`dispatch` 再拦截 read-only + Medium 拒 + High 兜底拒。

### ⑧ V21 大版本迁移谨慎
`BATCH_SIZE=50` 分页、空库跳过、解析失败 skip 而非崩溃、`column_exists` 守卫 ALTER TABLE 防重复执行。

### ⑨ 子进程清理 + Windows 黑窗抑制
`kill_on_drop(true)` 超时后子进程不残留；`creation_flags(0x08000000)` 抑制 Windows 黑窗闪现。

---

## 📊 汇总

| 分类 | 🔴 | 🟡 | ✅ |
|------|----|----|----|
| 安全 | 8 | — | — |
| 文档 | 9 | — | — |
| 代码质量 | — | 7 | — |
| 前端 | — | 13 | — |
| 亮点 | — | — | 9 |
| **合计** | **17** | **20** | **9** |

**总体评价**：核心安全架构扎实（SQL 注入防护、密钥管理、MCP 多层防御、取消 TOCTOU）。主要风险集中在 `state.rs` 同步锁在 async 上下文中的潜在死锁、文档与代码脱节（AI对话引擎工具数过时、INDEX 漏列 9 文档、~100 行已移除模块残留）。前端整体质量高，但需清理少量遗留（Arco 残留、内联 confirm 重复）。