skills
/
deerflow2
3
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
deerflow2/.planning/codebase/CONCERNS.md

9.3 KiB
Raw Blame History

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