deerflow2/.planning/codebase/CONCERNS.md

# Codebase Concerns

**Analysis Date:** 2026-04-07

## 简短结论

当前代码库后端能力完整、测试数量较多，但在“生产安全基线”和“运行时一致性”上存在高优先级缺口：API 鉴权缺失、回滚语义未闭环、流式事件链路缺少可恢复能力。前端主要问题是关键模块体量偏大与测试覆盖不均衡，短期会拖慢迭代速度，中期会放大回归风险。

## 优先级建议（面向规划）

- P0（立即）：补齐网关鉴权与访问控制；补全 rollback 真回滚语义。
- P1（近期）：修复消息角色归一化错误；完善 SSE 可恢复性与丢事件观测。
- P2（排期）：拆分超大前端组件、收敛 demo 静态资源体积、减少“声明支持但未实现”的 API 选项。

## Tech Debt

**运行时回滚语义未实现（高优先级）:**
- Issue: 取消 run 时支持 `action=rollback`，但实际未执行 checkpoint 回滚，仅记录日志并 `pass`。
- Files: `backend/packages/harness/deerflow/runtime/runs/worker.py`
- Impact: 前端/调用方会认为“已回滚”，但线程状态可能仍保留部分中间写入，导致状态一致性问题。
- Fix approach: 在 `rollback` 分支接入 checkpointer 的真实回退 API（按 `pre_run_checkpoint_id` 恢复），并补充回滚前后状态断言测试（成功、失败、并发取消三类）。

**后端代码布局存在“空 src + 实际实现在 packages”认知负债（中优先级）:**
- Issue: 业务实现集中在 `backend/packages/harness/deerflow/`，而 `backend/src/` 仅有缓存产物目录结构，容易误导新贡献者。
- Files: `backend/packages/harness/deerflow/`, `backend/src/`
- Impact: 新代码落点不稳定、审查成本上升、重构时容易出现重复实现。
- Fix approach: 在贡献文档和目录说明中明确“单一真实源码根”；清理或显式标注 `backend/src/` 的用途，避免“影子目录”持续存在。

**前端关键组件体量过大（中优先级）:**
- Issue: 交互核心组件单文件体量偏大，状态/视图/副作用耦合。
- Files: `frontend/src/components/ai-elements/prompt-input.tsx`, `frontend/src/components/workspace/input-box.tsx`, `frontend/src/components/workspace/artifacts/artifact-file-detail.tsx`
- Impact: 修改单一功能易触发连带回归，评审与测试成本高。
- Fix approach: 以“状态管理、上传/附件、动作菜单、发送流程”拆分子模块；每次拆分同步补充组件级测试。

## Known Bugs

**消息角色被错误归一化为 HumanMessage（高优先级）:**
- Symptoms: 非 `user/human` 的消息（如 system/ai/tool）在输入归一化中被降级为 `HumanMessage`。
- Files: `backend/app/gateway/services.py`
- Trigger: `normalize_input()` 处理 `messages` 列表时遇到非用户角色。
- Workaround: 调用端仅传用户消息；系统消息改走其他配置通道。

**artifact 文本判定后仍可能触发 UTF-8 解码异常（中优先级）:**
- Symptoms: 文件被判定为“文本”后直接 `read_text(encoding="utf-8")`，遇到非 UTF-8 内容可能返回 500。
- Files: `backend/app/gateway/routers/artifacts.py`
- Trigger: `is_text_file_by_content()` 返回 true，但实际编码非 UTF-8。
- Workaround: 使用 `download=true` 强制下载，避免 inline 文本解码路径。

**API 声明支持 `enqueue` 但运行时不支持（中优先级）:**
- Symptoms: 请求模型允许 `multitask_strategy="enqueue"`，但运行时抛 `UnsupportedStrategyError`（501）。
- Files: `backend/app/gateway/routers/thread_runs.py`, `backend/packages/harness/deerflow/runtime/runs/manager.py`
- Trigger: 客户端按 schema 传入 `enqueue`。
- Workaround: 客户端仅使用 `reject|interrupt|rollback`。

## Security Considerations

**网关缺少统一鉴权/鉴别层（高优先级）:**
- Risk: 线程、上传、技能、memory、run 控制等接口可被未授权调用（取决于外围网络暴露）。
- Files: `backend/app/gateway/app.py`, `backend/app/gateway/routers/*.py`
- Current mitigation: 注释说明依赖外层 nginx；代码内无显式 `Depends` 鉴权依赖。
- Recommendations: 在网关层增加统一认证中间件（JWT/API Key/Session 任一），并对高风险写操作路由做细粒度授权。

**本地 host bash 仅“尽力防护”，非强隔离（中高优先级）:**
- Risk: 启用 `allow_host_bash` 后，命令路径校验强调 best-effort，且对 bash 写入限制不等同于读写工具限制。
- Files: `backend/packages/harness/deerflow/sandbox/tools.py`
- Current mitigation: 绝对路径校验、路径遍历检查、file:// 阻断、虚拟路径替换。
- Recommendations: 将 host bash 默认硬禁用；在生产配置强制容器沙箱；增加审计日志与策略开关（按工具/命令白名单）。

## Performance Bottlenecks

**流式桥接队列容量有限且存在丢事件（中优先级）:**
- Problem: 单 run 队列默认上限 256；发布超时会丢事件，且仅日志告警。
- Files: `backend/packages/harness/deerflow/runtime/stream_bridge/memory.py`
- Cause: 内存队列 + 固定容量 + 没有持久化重放。
- Improvement path: 引入可重放后端（Redis/持久队列）或增大可配置容量；将 dropped_count 暴露为指标并设置告警阈值。

**前端仓库包含较大 demo 资产，影响构建/分发体积（中优先级）:**
- Problem: `frontend/public/demo/` 包含较多图片/视频与线程快照。
- Files: `frontend/public/demo/threads/**`
- Cause: demo 内容直接入仓并随静态资源参与交付。
- Improvement path: 将大型 demo 资产迁移到对象存储/CDN 或按环境开关构建；保留最小样例集。

## Fragile Areas

**Run 生命周期与 SSE 消费链路耦合（中高优先级）:**
- Files: `backend/app/gateway/services.py`, `backend/app/gateway/routers/thread_runs.py`, `backend/packages/harness/deerflow/runtime/runs/manager.py`, `backend/packages/harness/deerflow/runtime/stream_bridge/memory.py`
- Why fragile: 断线策略、取消语义、状态迁移、队列清理分散在多处，边界行为（断线+取消+重连）容易退化。
- Safe modification: 先补“状态机契约测试”再改逻辑；对 `cancel/rollback/interrupt` 统一建表驱动测试。
- Test coverage: 后端测试较多，但“断线重连 + 事件重放 + 回滚一致性”端到端场景仍有缺口。

**前端输入与工件详情模块变更风险高（中优先级）:**
- Files: `frontend/src/components/workspace/input-box.tsx`, `frontend/src/components/ai-elements/prompt-input.tsx`, `frontend/src/components/workspace/artifacts/artifact-file-detail.tsx`
- Why fragile: 单文件承担过多职责，状态路径复杂。
- Safe modification: 采用“先抽 hooks/子组件，后迁移调用点”的两阶段改造；每步保留行为快照测试。
- Test coverage: `frontend/src/` 下单元测试文件较少（仅少量），复杂交互主要依赖 E2E。

## Scaling Limits

**Run/Stream 元数据以内存为中心，重启后状态不连续（中高优先级）:**
- Current capacity: 单进程内存字典 + 队列；run 记录会延迟清理，stream 事件不支持回放。
- Limit: 进程重启或横向扩容后，`Last-Event-ID` 无法恢复历史事件；跨实例一致性弱。
- Files: `backend/packages/harness/deerflow/runtime/runs/manager.py`, `backend/packages/harness/deerflow/runtime/stream_bridge/memory.py`
- Scaling path: 引入跨实例共享存储（持久 run registry + 可回放事件流），并将 `last_event_id` 变为可用恢复机制。

## Dependencies at Risk

**前端依赖面较宽，升级波动风险上升（中优先级）:**
- Risk: UI/渲染/动画/编辑器与 AI SDK 依赖较多，任一主版本变化可能触发连锁适配。
- Impact: 构建稳定性与行为一致性风险上升。
- Files: `frontend/package.json`
- Migration plan: 建立“核心依赖分层升级策略”（渲染内核、AI SDK、UI 库分批升级）与最小回归清单。

## Missing Critical Features

**后端 API 层缺少内建访问控制能力（高优先级）:**
- Problem: 关键写操作接口缺少统一认证与授权依赖。
- Blocks: 无法安全对公网或多租户环境直接暴露网关。
- Files: `backend/app/gateway/app.py`, `backend/app/gateway/routers/*.py`

**SSE 可恢复协议未形成闭环（中高优先级）:**
- Problem: 桥接层注明接受 `last_event_id` 但忽略重放。
- Blocks: 客户端断线恢复体验与长任务稳定性。
- Files: `backend/packages/harness/deerflow/runtime/stream_bridge/memory.py`

## Test Coverage Gaps

**前端复杂交互缺少充分单元/组件测试（中优先级）:**
- What's not tested: 输入框状态机、附件生命周期、artifact 详情多分支渲染的细粒度行为。
- Files: `frontend/src/components/workspace/input-box.tsx`, `frontend/src/components/ai-elements/prompt-input.tsx`, `frontend/src/components/workspace/artifacts/artifact-file-detail.tsx`
- Risk: 小改动引发 UI 行为回归且难快速定位。
- Priority: High

**安全基线测试缺少“未认证访问”负向用例（高优先级）:**
- What's not tested: 未携带认证凭据访问关键 API 的拒绝路径（当前实现层面未内建）。
- Files: `backend/app/gateway/routers/*.py`, `backend/tests/`
- Risk: 安全能力依赖部署外部组件，环境漂移即暴露风险。
- Priority: High

---

*Concerns audit: 2026-04-07*