项目概览与产品愿景

本章目标:

1. 说清 a-cdm 到底是什么、为谁解决什么问题,以及它和普通 ChatBot / RAG 的本质区别
2. 建立"一个完整独立系统 = 定制 deer-flow 引擎 + acdm-backend 控制面 + demoo_service"的整体心智
3. 理解为何选择"深度二开 + Monorepo"而不是"跟随上游 + 插件",这个决策如何贯穿全仓代码

TL;DR

a-cdm 是一个面向 allmeta 交付项目的智能引擎,目标是让"智能体成为项目上的同事"而不是被调用的工具。整个系统由三大自有部分构成:深度定制的 deer-flow LangGraph 引擎(Agent 大脑)、acdm-backend FastAPI 控制面(业务/鉴权/编排)、demoo_service(ERP 录屏分析与 PRD 流水线)。它放弃了对上游 deer-flow 的自动 merge,把源码整体纳入 monorepo 做深度改造。北极星是:"@产品 Agent 帮我对比一下 allmeta 财务模块在两个项目的实施差异"像 @同事 一样自然。

Overview(为什么有这个项目)

企业内做"AI + 项目交付"时,最容易掉进三个坑,a-cdm 的设计正是对这三个坑的回答:

1. 做成 ChatBot:Agent 只会被动应答,你不问它就不动。
2. 做成 RAG 工具:每次对话都是新开始,没有记忆、没有偏好、没有项目上下文延续。
3. 做成 SaaS 黑盒:知识、调用、上下文全绑在外部 LLM,公司没有自己的资产沉淀。

这三条不是抽象担忧,而是被写进规格、每个 Phase 末强制反向 review 的失败判据 —— openspec/specs/roadmap/spec.md 的 Requirement: Inversion Reflex 每 Phase 末必 review 明确列出"做成了 ChatBot / RAG / SaaS 黑盒"三条失败路径及其早期症状、根因和触发后的补救动作。

所以 a-cdm 不是"接一个大模型做问答",它要的是一个有记忆、有偏好、能主动贡献、按项目隔离的数字员工系统。北极星场景写在 README.md:35:一年后"@产品 Agent 帮我对比一下 allmeta 的财务模块在 129 和 112 项目的实施差异"这种请求,应该像"@某某同事帮我看看"一样自然。

要做到这一点,单靠一个 Agent 框架不够。a-cdm 把系统拆成职责清晰的三块,各自解决一类问题:

Architecture

a-cdm 在 openspec/specs/architecture/spec.md:30-46 把系统正式定义为 7 层。从开发者视角,可以收敛成"三大自有部分 + 共享基础设施"的心智模型:

组成部分	角色一句话	主代码目录	技术栈	Source
定制 deer-flow 前端	用户唯一入口,工作区/聊天/知识库 UI	deer-flow/frontend/	Next.js 16 + React 19 + Tailwind 4	deer-flow/frontend/package.json
定制 deer-flow 引擎	Agent 大脑:推理/工具/记忆/沙箱	deer-flow/backend/	LangGraph + Aegra 0.9.4 + MCP	deer-flow/config.yaml:37
acdm-backend 控制面	业务编排/鉴权授权/可逆操作/知识源	acdm-backend/	FastAPI + SQLAlchemy async	acdm-backend/app/main.py
demoo_service	ERP 录屏反编译 + PRD 自动生成	demoo_service/	Flask + LLM 流水线	demoo_service/server.py
共享基础设施	鉴权/数据/文件/规格治理	deploy/ openspec/	Keycloak·PostgreSQL·Nextcloud·OpenSpec	deploy/prod/Caddyfile.keycloak-v1

这里有一个关键定性贯穿全 wiki:deer-flow/ 子目录虽然源自字节 bytedance/deer-flow,但在 a-cdm 内它已经不是"一个被引用的第三方框架",而是被深度改造、与 acdm-backend 通过 config.yaml + service token 双向耦合的引擎内核。它带有 a-cdm 专属的 auth 注入(deer-flow/backend/packages/harness/deerflow/auth/acdm_auth.py)、Agent Tools BFF 回调、Aegra 运行时切换,以及 deer-flow/frontend/tests/unit/core/acdm/ 下的定制测试。本 wiki 把它当作 a-cdm 不可分割的一部分完整分析。

Components / 三大组成的存在理由

定制 deer-flow 引擎(Agent 大脑)

职责:跑 Lead Agent 的推理循环 —— 选模型、装工具、串中间件、调子代理、读写沙箱、注入记忆与技能。 为什么需要:"数字同事"的智能行为(规划、调用工具、长对话、主动产出)都在这一层。a-cdm 没有自己重写 Agent 框架,而是把 deer-flow 整体纳入并深度改造,因为它已经具备 LangGraph 状态机、中间件链、SKILL 系统、MCP、沙箱这些成熟基建。引擎配置集中在 deer-flow/config.yaml(模型矩阵见 :37,沙箱见 :666,记忆见 :883)。

acdm-backend 控制面(业务与编排)

职责:项目/会议/知识库/BA 报告的业务 CRUD;Keycloak 鉴权与三级授权;AI 可逆操作治理;把自己暴露成 MCP 知识源给引擎用。 为什么需要:Agent 引擎本身不懂"项目""成员""会议纪要"这些业务概念,也不该承担鉴权与数据治理。控制面是引擎和企业业务之间的适配层与安全边界。入口 acdm-backend/app/main.py,业务域分散在 acdm-backend/app/api/ 的 30+ router。

demoo_service(ERP 录屏分析)

职责:把 ERP 系统(金蝶云星瀚 / 华为 MetaERP)的录屏 JSON 反编译成结构化页面快照,跑四阶段流水线生成 PRD。 为什么独立:它是一个领域高度专门化的子系统(Chrome 扩展采集 + Playwright 录屏 + 页面元素识别),与 Agent 引擎职责正交,通过共享 platform-db 和 Nextcloud 与主系统集成,而不是耦合进 acdm-backend。入口 demoo_service/server.py,流水线 demoo_service/erp_flow/pipeline.py。

关键设计决策:为什么"深度二开 + Monorepo"

a-cdm 最重要的一个架构决策(2026-04-18 锁定,见 CLAUDE.md:13)不是技术选型,而是与上游 deer-flow 的关系。

直觉做法是"用 deer-flow 作依赖,自己写插件,定期 git merge upstream/main 拿上游更新"。a-cdm 明确放弃了这条路:

方案	优点	为什么 a-cdm 没选 / 选了
跟随上游 + 插件	自动拿上游更新	❌ 深度定制(auth 注入、Aegra、BFF 回调)穿透到框架内部,插件边界拦不住,merge 必冲突
深度二开 + Monorepo	改动无边界限制,一个仓一次部署	✅ 已锁定。源码整体复制入主仓,放弃 git merge,上游修复改手工 cherry-pick,分叉起点 snapshot 898f4e8

代价是上游更新不再自动,需手工 cherry-pick;收益是定制不再受插件边界束缚 —— 这正是 acdm_auth.py、Agent Tools BFF、Aegra 运行时切换这些深度改造能存在的前提。这个决策的直接后果你会在全仓看到:deer-flow/ 不是 node_modules 式的只读依赖,而是被 CI lint、被定制测试覆盖、被 cd-poll 自动部署的一等代码。红线 CLAUDE.md:26 同时约束:upstream 原生目录视为只读,改动限于扩展点,A-CDM 特定文档不写进 deer-flow/docs/,以降低手工 cherry-pick 的冲突面。

三仓拓扑(为什么知识层单独成仓)

a-cdm 主仓只是三仓之一。知识层(a-cdm/llm-wiki)被刻意拆成独立 git 仓,因为"git 是知识层唯一真源"是项目第三句心智(README.md:41):人类在 GitLab Web IDE 或前端 WikiEditor 直接编 markdown,多个 compiler 写入,Agent 通过 MCP filesystem 读 —— 全程不走 HTTP API,git 就是数据库。

仓库	作用	状态	Source
a-cdm/a-cdm	主仓 monorepo(本仓库)	日常开发	README.md:49
a-cdm/llm-wiki	LLM 知识库(Karpathy raw/+wiki/)	在用	README.md:50
a-cdm/deer-flow	上游分叉起点 898f4e8 冻结快照	只读参考	README.md:51

Configuration(本章相关)

配置/事实	值	含义	Source
分叉起点	snapshot 898f4e8	上游 cherry-pick 的基线	CLAUDE.md:13
当前快照 commit	07b3469	本 wiki 分析的代码版本	git 本地快照
Canonical 入口	https://acdm.r7.chinasoftinc.com/a-cdm/workspace/projects	生产唯一正式入口	CLAUDE.md:15
生产 VM	172.20.21.28,8GB ARM64	资源边界约束部署策略	CLAUDE.md:19

Common Pitfalls / 实战 Tips

• 不要把 deer-flow/ 当外部依赖:它是被定制、被测试、被部署的一等代码。把它略写或外引会漏掉 a-cdm 一半的机制。
• 不要往 deer-flow/docs/ 写 A-CDM 文档:红线明确(CLAUDE.md:26),会增加手工 cherry-pick 上游时的冲突面。
• 可变状态查命令不查文档:CLAUDE.md:3 规定数字/列表/roadmap 不在 CLAUDE.md 维护,查 openspec list 或 ls docs/...,否则必 drift。

References

• README.md:1-66 — 项目愿景、三仓拓扑、技术栈速览
• CLAUDE.md:11-30 — 5 条核心认知与项目结构(不变量)
• openspec/specs/architecture/spec.md:1-52 — 顶层架构规格,7 层定义
• openspec/specs/roadmap/spec.md:1-40 — Inversion Reflex 三条失败路径(ChatBot/RAG/黑盒)
• deer-flow/config.yaml:37 — 引擎模型矩阵配置,定制引擎的具体证据
• acdm-backend/app/main.py — 控制面 FastAPI 入口
• demoo_service/server.py — demoo_service Flask 入口

Related Pages

Page	Relationship
系统整体架构	本章的"三大组成"在该章展开为完整服务/数据流拓扑
仓库结构与代码地图	本章的边界定性在该章落到具体目录
Aegra 运行时与 LangGraph	本章提到的"Agent Runtime 切换"细节在该章
控制面与引擎的耦合契约	本章"深度二开"导致的 acdm-backend↔引擎耦合在该章详解
OpenSpec 规格治理与测试策略	本章引用的 roadmap/architecture 规格属于该章治理体系