主题
03 · 平台积木与扩展点(以 deer-flow 原生杠杆为序)
贯穿 00 §B.3 原则:先问"deer-flow 原生有没有现成的",再问"扩展点能不能薄接",最后才 acdm-backend 自建。 每个积木标注:原生层级(★★★ 纯原生复用 / ★★ 原生扩展点接入 / ★ 必须 acdm-backend 自建)+ 不碰 vendored 只读层的接入证明。
1. ★★★ deer-flow 原生 · 直接复用(零/极少二开)
| 积木 | 关键出处 | 为 PDCA 承担什么 | 接入点(不碰只读层) |
|---|---|---|---|
| 技能系统 | deerflow/skills/{parser,validation,installer,tool_policy}.py;现有 skills/custom/weekly-report|monthly-report|pmo-report|team-lead-report|weekly-report-reviewer|meeting-minutes-generator|meeting-aggregator-realtime | PDCA 复盘 / 周月报 / 风险简报 = 新增 SKILL.md,LLM 按 description 自选 | 新建 deer-flow/skills/custom/<name>/SKILL.md + extensions_config.json 启用——纯新增目录 |
| 确定性 Pipeline | langgraph.json/aegra.json graphs;pipelines/{weekly_report(5节点线性),meeting_aggregator(6节点DAG),meeting_aggregator_realtime(9节点),ba_report(3步)} | ASR→纪要→抽取→待办派生 = 固定步骤 pipeline;复盘批处理 = pipeline | 新建 pipelines/<name>/{state,nodes,pipeline}.py + 在 langgraph.json&aegra.json 注册——纯新增 + 配置追加 |
| 子代理委派 | tools/builtins/task_tool.py、subagents/executor.py(线程池硬限 3)、subagents/registry.py | 探索式/并行子任务(如多文档归并调研);非确定链路 | config.yaml: subagents.custom_agents 声明——纯配置 |
| 上下文工程 | middlewares/summarization_middleware.py(技能抢救/token 驱动)、loop_detection_middleware.py | 跨多场会议聚合时上下文爆炸的原生解 | config.yaml: summarization.{trigger,keep,preserve_recent_skill_*}——纯配置 |
| 文档转换 | utils/file_conversion.py(markitdown/pymupdf4llm、extract_outline)、UploadsMiddleware | transcript/docx→md + 提纲驱动读取(省 token) | 已 live,复用即可 |
含义:PDCA 复盘、周/月/风险报告、跨会上下文管理——这些都不该在 acdm-backend 写代码,应是 deer-flow 原生 skill/pipeline/config。这是最大的"事半功倍"区。
2. ★★ deer-flow 原生 · 扩展点薄接入(少量二开)
| 积木 | 关键出处 | 为 PDCA 承担什么 | 扩展点(不碰只读层) |
|---|---|---|---|
| 中间件链 / before_agent 注入 | middlewares/dynamic_context_middleware.py(首条 HumanMessage 前注入日期+记忆)、agent.py 的 custom_middlewares 注入位(LoopDetection 后、Clarification 前)、thread_state.py | Check 自动注入"上次待办进度 + 偏差扫描"的原生最优解——一个 before_agent 中间件 | make_lead_agent(custom_middlewares=[...]);a-cdm 在自己装配处传入自定义中间件,不改 vendored 中间件文件 |
| 长期记忆底座 | agents/memory/{queue,updater,storage}.py;namespace users/{uid}/[{agent}/]memory.json;MemoryMiddleware 条件挂载 | InsightTree / 跨会事实的候选持久层(项目级 namespace) | a-cdm 应用层做聚合层调 get_memory_storage(),不改上游存储实现;或经 project-{slug} agent 记忆 namespace |
| AI 角色注册表(引擎侧) | deer-flow/config.yaml roles;前端切模型 /api/models | 抽取/凝练/复盘各自模型选择 | 改 config.yaml(deer-flow 配置文件,非只读源码)+ 部署 force-recreate |
3. ★ acdm-backend 必须自建(原生确实不承载,但走既有框架)
这些是"原生杠杆"原则的例外——05 每处都显式回答"为什么不能纯原生"。共性:需要强一致结构化持久 + 事务 + 复杂查询 + 权限,deer-flow 原生(临时 ThreadState / 文件态记忆)无法承载。
| 积木 | 现有可复用框架(file:line) | 为 PDCA 承担什么 | "为什么不能纯原生" |
|---|---|---|---|
| 待办池(新表+服务) | 复用 substrate:storage/reversible/transaction.py business_transaction、软删范式 models.py 各表 deleted_at、状态机先例 OpenSpec archive/2026-04-30-meeting-status-state-machine、链式权限 auth/resource_deps.py | 一等公民待办:状态机/归并/人审/同步 | deer-flow ThreadState.todos 是单线程临时 plan-mode,无跨会持久/无项目权限/无事务回滚——结构上无法做项目待办池 |
| L1/L2 洞察缓存(已存在,需扩展) | models.py:668 MeetingInsightCache/:720 MeetingAtomCache;EXTRACT_VERSION;insights_router.py:254 regenerate;admin_meeting_router.py backfill | 原子类型扩容后的缓存失效与 backfill | 已是 a-cdm 自建且成熟,扩展即可(非新建) |
| InsightTree 规范化表(候选) | 同 substrate + 缓存框架 | 报告/Check 需"按 kind/owner/时间"快查与聚合统计 | 见 05:若选"PG 规范化"则自建;若选"原生记忆+缓存"则归入 §2——这是关键架构岔路 |
| Agent Tools BFF(已存在,需加端点) | api/agent_tools_{project,business,nc}/router.py;identity_override;MCP mcp/tools/wiki.py | 让 skill/pipeline/项目管家读到待办/InsightTree | 已是 a-cdm 自建 BFF,加端点即可 |
| 项目管家 provision(已存在) | services/project_agent_service.py:123 provision_manager;models.py:242 ProjectAgentMount;auth/scope.py resolve_project_id | 承载"Check 注入 + 复盘 skill"的人格载体 | 已 live,挂能力即可 |
| 可逆 substrate(已存在) | storage/reversible/*;admin_trash_router.py | 待办/纪要/mount/报告全可逆 | 已 live,新对象接入即可 |
4. 关键扩展点速查(落地时直接对照)
| 要做的事 | 首选层级 | 具体挂载点 | 反模式(别这么干) |
|---|---|---|---|
| 补 atom 类型(risk/blocker/action_item/...) | ★★ | deer-flow/skills/custom/meeting-aggregator-realtime/extract_prompt.md + acdm-backend/app/prompts/atom_extract_prompt.md + schemas/insights.py + EXTRACT_VERSION bump + admin backfill | 不要新写一套抽取服务(对抗 substrate) |
| PDCA 复盘 / 周月报 / 风险简报 | ★★★ | 新 skills/custom/<name>/SKILL.md(参 weekly-report)或新 pipeline 注册 langgraph.json+aegra.json | 不要在 acdm-backend 写报告 endpoint(绕开原生 skill) |
| Check 开场自动注入 | ★★ | 自定义 before_agent 中间件,经 make_lead_agent(custom_middlewares=...) 注入;读 a-cdm 待办进度 BFF | 不要在前端/Caddy/BFF 拼字符串塞 prompt(绕开中间件链) |
| 待办池(表/状态机/归并/人审) | ★ | 新 model/models.py 表 + repository/ + services/(全包 business_transaction)+ api/todo_router.py(require_project_access/owner) | 不要复用 deer-flow ThreadState.todos(语义错位) |
| 待办从分析派生 | ★★★/★ | pipeline 节点(原生)调 a-cdm BFF 写待办(自建持久) | 不要让前端轮询拼装 |
| InsightTree 持久化 | 见 05 | PG 规范化表 ⟷ 原生记忆 namespace 二选一(架构岔路) | 不要"部分 cache 部分表"继续漂(现状痛点) |
| 跨会聚合不撑爆上下文 | ★★★ | config.yaml: summarization.* 调参 + skill 内分 pass | 不要把 N 场会议全文塞进单次 LLM |
| 报告/Check 回写知识库 | ★★ | pipeline 末节点调 services/ba_report/wiki.py 范式 commit_file(自动 [ai-assist] 前缀) | 不要直接写 deer-flow/docs/(只读层,会冲突) |
5. 红线复述(接入时必须遵守)
- vendored 原生目录(
deer-flow/backend/packages/.../deerflow/**等)只读;扩展只走skills/custom/、config.yaml、langgraph.json/aegra.json、custom_middlewares入参、acdm-backend BFF。 - 新增
xxx_API_KEY必须先 ssh prod 改 .env → 再 merge → 再 force-recreate(否则 ai_registry fail-fast 停摆,L94 教训)。 - 不在
main直接 commit;Caddyfile 切换用restart不能reload;改 basePath 必重 build。 - 详见 07 风险与反模式登记册。
下一步(04):目标(01 DoD)− 现状(02 基线)= 差距,分类与量级。