仓库结构与代码地图

本章目标:

1. 拿到一张"哪个目录干什么、改某功能该去哪"的导航地图,15 分钟内能在 monorepo 里找对位置
2. 看清定制 deer-flow 引擎内核(packages/harness/deerflow)的 package 划分与各自职责
3. 知道哪些目录是冻结/只读、哪些是真源、哪些是噪声,避免改错地方

TL;DR

a-cdm 是一个 monorepo:顶层四个代码部分(acdm-backend/ 控制面、deer-flow/ 定制引擎+前端、demoo_service/ ERP 服务),加上 deploy/(部署)、openspec/(规格真源)、docs/(运维文档)。引擎内核在 deer-flow/backend/packages/harness/deerflow/ 下按 agents/sandbox/skills/memory/mcp/tools/pipelines 等 package 组织。规格真源在 openspec/specs/,可变状态查命令不查文档。

Overview(为什么需要一张代码地图)

monorepo 把四个本可独立的系统塞进一个仓,好处是一次部署、一致版本、跨边界改动原子化;代价是目录密度极高,新人很容易在 deer-flow/backend/app/ 和 deer-flow/backend/packages/harness/deerflow/ 之间迷路,或者把 A-CDM 文档错写进 vendored 只读区。这一章就是那张地图:不讲机制(机制在各专章),只回答"我要改 X,该去哪个目录,哪些地方碰不得"。

顶层目录职责

顶层目录	职责	性质	对应章节
acdm-backend/	业务/鉴权/编排控制面(FastAPI,Python 3.11,pip)	自有源码	10、20–27
deer-flow/backend/	定制 AI 引擎(LangGraph/Aegra)	定制源码(原生只读)	11、13–19
deer-flow/frontend/	定制前端(Next.js 16)	定制源码	28–31
deer-flow/skills/	SKILL 技能(public/ + custom/)	自研 + 上游	16
demoo_service/	ERP 录屏分析与 PRD 流水线(Flask)	自有源码	32
deploy/	Caddyfile / compose / CI base image / CD 脚本	部署	33、34
openspec/	规格真源:specs/(capability)+ changes/(生命周期)	真源	35
docs/	runbooks/ 运维 · reports/ 时点事件 · _legacy_raw/ 冻结真相	文档	35
reference/	只读归档(PRD / v0.2.1 SOP / 源码分析)	只读	—
tmp/ .gstack/	临时 / 工具元数据	噪声(不分析)	—

性质栏的"原生只读"含义:deer-flow/backend 的 upstream 原生文件视为只读,改动限于扩展点(CLAUDE.md:26),目的是降低手工 cherry-pick 上游的冲突面。这不影响本 wiki 把它当 a-cdm 一部分完整分析 —— "只读"是协作纪律,不是"不重要"。

定制引擎内核:packages/harness/deerflow/

这是 a-cdm 智能行为的发动机,作为 deerflow-harness 包发布。18 个 package,各自职责:

package	职责	详见章节
agents/	Lead Agent 工厂、中间件链、记忆、checkpointer	13、14、17
auth/	A-CDM 定制 owner_sub 隔离(acdm_auth.py)	9、12
sandbox/	LocalSandbox / AioSandbox + 文件工具	15
skills/	SKILL.md 发现/加载/解析	16
memory/(在 agents 下)	事实抽取/注入	17
mcp/	MCP client / 缓存 / OAuth	18
tools/	工具装配总线 + A-CDM business/nc/project BFF client	12、18、26
subagents/	子代理委派(executor/registry)	19
pipelines/	确定性工作流(weekly_report/meeting_aggregator/ba_report)	19、22、23
models/	模型工厂 + patched provider	6
guardrails/	工具调用授权检查	14、18
config/	配置系统(app.yaml/extensions_config.json)	5
runtime/	Gateway 模式嵌入式 agent 运行时	11
reflection/	动态类加载(use: 字段反射)	5、6
community/	社区工具(web 搜索/爬虫/AioSandbox)	18
uploads/ tracing/ utils/	文件转换 / 追踪 / 通用工具	5、15

引擎对外的 HTTP 面不在 packages 里而在 deer-flow/backend/app/:app/gateway/(FastAPI Gateway,端口 8001)和 app/channels/(IM 通道)。Aegra/LangGraph 的图工厂注册在 deer-flow/backend/aegra_graphs/(lead_agent.py、weekly_report.py、meeting_aggregator.py、meeting_aggregator_realtime.py、ba_report.py),由 aegra.json / langgraph.json 指向。

控制面与前端的代码分区

acdm-backend 是标准 FastAPI 分层(详见控制面章):

acdm-backend/app/
  main.py        — create_app() 工厂 + lifespan
  config.py      — Pydantic 配置
  database.py    — async SQLAlchemy 引擎
  api/           — 30+ router(业务 + admin + agent-tools BFF)
  auth/          — Keycloak OAuth2 + forward_auth verify + 三级授权
  services/      — 业务逻辑层
  repository/    — 数据访问层
  model/         — ORM 表定义
  schemas/       — Pydantic DTO
  storage/       — Nextcloud + reversible 可逆操作框架
  mcp/           — FastMCP 知识源 server
  util/          — ai_registry / llm_client / gitlab_client 等
  alembic/       — 数据库迁移(40 个 version)

deer-flow/frontend 是 Next.js App Router 结构(详见前端章):

deer-flow/frontend/src/
  proxy.ts       — Next.js 16 鉴权守卫(原 middleware.ts)
  app/           — App Router 路由(/workspace/* 等)
  components/    — UI(含 workspace/acdm/ 定制组件)
  core/          — 业务逻辑;core/acdm/ 是 A-CDM 定制(28 模块)
  hooks/ lib/ styles/ — 通用 hooks / 工具 / 样式
  env.js         — 环境变量 schema

真源与冻结区(改之前必看)

a-cdm 对"什么是真相、改哪里"有强约束(红线见 CLAUDE.md:6 段):

• 真源:openspec/specs/ 是规格唯一真源;代码是实现真源。两者冲突以哪边为准取决于改动类型(规格变更走 OpenSpec 流程)。
• 冻结只读:docs/_legacy_raw/(历史真相,禁改)、reference/(只读归档)、docs/specs/ 与 docs/plans/(已冻结,禁新建)。
• vendored 只读:deer-flow/ upstream 原生文件改动限扩展点;不往 deer-flow/docs/ 写 A-CDM 文档。
• 可变状态不入文档:数字/列表/roadmap 不写进 CLAUDE.md 或 runbook,查 openspec list --specs、ls openspec/changes/、ls docs/reports/(CLAUDE.md:3)。

Common Pitfalls / 实战 Tips

• deer-flow/backend/app/ ≠ 引擎内核:HTTP 面在 app/,真正的 Agent 机制在 packages/harness/deerflow/。找 Agent 逻辑别在 app/ 里翻。
• 不在 main 直接 commit(红线):违反 2 次会被 rescue 到补救 MR。永远 checkout -b <type>/<desc> 走 MR。
• 本 wiki 排除的噪声:.git/、.gstack/、*.xlsx、**/screenshots/、reference/ 纯资料 —— 这些不是分析对象。
• worktree 必须建在 <repo>/.claude/worktrees/<name>/(红线):建在项目根之外会被 sandbox 拦导致清理失败。

References

• CLAUDE.md:23-30 — 项目结构(tracked 顶层)与文档分层
• CLAUDE.md:3 — 可变状态不入文档原则
• deer-flow/backend/packages/harness/deerflow/ — 引擎内核 18 package 根目录
• deer-flow/backend/aegra_graphs/ — Aegra/LangGraph 图工厂 wrapper(5 个)
• acdm-backend/app/ — 控制面分层目录
• deer-flow/frontend/src/ — 前端 App Router 结构
• openspec/specs/ — 规格真源根目录

Related Pages

Page	Relationship
项目概览与产品愿景	本章是该章边界定性在目录层的落地
acdm-backend 控制面架构	本章 acdm-backend 分区在该章展开为机制
Lead Agent 设计与图构建	本章 packages/harness/deerflow/agents 在该章详解
前端技术栈与架构	本章前端分区在该章展开
OpenSpec 规格治理与测试策略	本章"真源/冻结区"规则在该章治理体系中定义