主题
a-cdm 技术债与整改路线图(顶层 · 单一入口)
生成 2026-05-18。这是行动入口;下面四份是支撑证据,有疑问回溯对应文件:
- 结构差异 →
a-cdm-vs-deer-flow-差异报告.md- 二开实现合理性 →
二开实现合理性审计.md- 上游 fix 甄别 →
上游安全fix-backport清单.md- 整改 how-to →
二开整改-细节方案.md落地一律走 a-cdm MR 流程(红线:禁直接maincommit)。
1. 一句话总评
a-cdm 是一次架构纪律罕见地好的深度二开(审计:能力复用 9/10、实现合理性 9/10、弯路严重度仅 2/10)。"落后上游 199 提交"听着吓人,但其中约 50 条结构性 N/A —— 正是它"用 Aegra 替换 Runtime + 自建 acdm_auth + 无 persistence 层 + 外挂不侵入"的纪律,让绝大多数上游 churn 与它无关。真正要做的事很少且很具体:1 道 CI 护栏 + 6 个 P0 backport + 几个低冲突 P1 + 1 处死代码清理。
三处早期判断已被实证更正(对 a-cdm 更有利)
| 早期说法(差异报告/初判) | 实证更正(审计 + backport) |
|---|---|
| a-cdm 自建鉴权疑似执行扣分 | 合理自建:fork 冻结点上游根本无鉴权能力(langgraph_auth.py 晚 9 天才出现) |
acdm_thread_auth.py 侵入上游 router 是"该消除的小弯路" | 必要补丁,无法消除;它是 cherry-pick 冲突点(运维注意项),非设计缺陷 |
| 差异报告建议 #3(消除该侵入) | 推翻,不应作为整改项 |
2. ⚠️ 四份独立分析一致认定的头号风险(先做这个)
langgraph.json/aegra.json 的 auth.path 无 CI 防护,cherry-pick 上游同名文件会静默把鉴权回退到上游 langgraph_auth.py → owner_sub 多租户隔离失效 → 跨用户数据越权。
差异报告【紧急#1】、审计【最严重 2 之一】、backport 清单【§4.4 最高优先非-backport 风险】、整改方案【整改1】—— 四份分析独立收敛到同一结论。这不是 backport,是一道护栏,优先级高于任何单条 fix。
how-to(脚本 + CI job + 标记文件)已在 二开整改-细节方案.md §整改1 写好,可直接落地。
3. 整改清单(按优先级 + 冲突面排序)
| 优先级 | 事项 | 来源 | 冲突面 | 性质 |
|---|---|---|---|---|
| P0-a 立即 | 加 auth.path/checkpointer.path CI 断言 + 标记文件 | 整改方案§1 | 无(纯新增) | 堵越权雷,秒级 CI |
| P0-b 高 | backport 6 条 P0,顺序:#2254→#2560/#2558/#2557→#2561→#2332 | backport§1 | 全 PRE-#2153,低(#2332 留最后人工核 acdm_thread_auth) | 沙箱逃逸/主机攻击面/数据丢失 |
| P1-a 高(随 P0 同批) | #2987(配 #2561)、#2317、#2252、#2449 | backport§2 | 低,单文件 | 安全扫描健壮性/路径脱敏/MCP稳定/API400 |
| P1-b 中(第二批) | #2941、#2867、#2784(记忆/agent 隔离与数据正确性) | backport§2 | 中-高,需人工移植(依赖 ABSENT 文件) | 多租户隔离,价值高 |
| P2 中 | 清理 BA 遗留死代码(8 模块 + 2 死测试),先过 4 道安全闸 | 整改方案§2 | a-cdm 自有代码,低 | 收尾唯一造轮子残留 |
| 持续 | 把每月甄别 SOP 固化进 docs/runbooks/vendored-sync.md + 评估账本 | backport§4 | — | 防债重新累积 |
| 不做 | P1-5/6/10/17(高冲突或暴露存疑)先评估再定;P2 的 174 条按桶 N/A | backport§2-3 | — | 明确不盲补 |
P0 六条速查(全部 PRE-#2153,基本可干净 cherry-pick)
| 序 | commit | 修什么 | a-cdm 实锤暴露点 |
|---|---|---|---|
| 1 | fc94e90f #2254 | setup-agent 失败误删 SOUL.md/config.yaml | project/user agent provision 重复触发 |
| 2 | 6bd88fe1 #2560 | 本地沙箱 bash .. 遍历逃逸 | config.yaml 启用 local sandbox,lead_agent 默认带 bash |
| 3 | 39c5da94 #2558 | 沙箱自定义挂载 symlink 逃逸 | 同上,local 沙箱 |
| 4 | af8c0cfb #2557 | view_image 未约束到 thread 路径(任意主机文件读出) | view_image 是 lead_agent 默认工具 |
| 5 | 707ed328 #2561 | skill 归档安装前不扫描(恶意包即代码执行) | skills/installer.py + Gateway routers/skills.py |
| 6 | 80e210f5 #2332 [security] | 主机侧文档转换默认开(上传即触发解析攻击面) | uploads.py:183 默认调用(冲突面最高,留最后) |
4. 建议执行节奏
- 第 1 个 MR(紧急,半天):P0-a CI 护栏。独立、零风险、收益最高,先合。
- 第 2 个 MR(1-2 天):P0-b 六条 + P1-a 四条(都 PRE-#2153 低冲突,同批 cherry-pick;#2332 单独 commit 人工核对 acdm_thread_auth);配套补 #2987 让 #2561 的扫描真生效。
- 第 3 个 MR(收尾,半天):BA 死代码清理(先跑整改方案§2 的 4 道闸)。
- 第 4 步(机制):vendored-sync.md 固化每月 SOP + 账本,
LAST_EVALUATED=39f901d3起算。 - 第二批(评估后):P1-b 隔离类(#2941/#2867/#2784)需人工移植,单独排期。
5. 结论
a-cdm 的二开质量是优等生,没什么弯路;技术债集中在"跟上游脱节"这一可控维度,且因架构纪律好,真正要补的面比"落后 199 提交"小一个数量级。最该立刻做的是那道 auth CI 护栏(四份分析一致、非 backport、堵越权雷),其次是 6 条低冲突 P0 安全补丁。把每月甄别机制建起来后,这套二开是可长期维护的。