Project Structure — 仓库结构

本页是根 README.md 的目录拆分页，说明顶层目录职责与 backend/app/ 场域包结构。 设计文档体系自身的目录树见 docs/README.md。

---

一、顶层目录

agent_hub/
├── README.md              项目入口（全貌 + 导航）
├── AGENTS.md              Cursor Cloud Agent 启动入口
├── CLAUDE.md              Claude Code 启动入口
├── LICENSE                MIT
├── Makefile               顶层任务（install / lint / typecheck / test / dev / compose-*）
│
├── backend/               后端：FastAPI 模块化单体（业务实现集中地）
├── frontend/              前端：pnpm workspace（web-builder / web-ops / web-starter / miniprogram / shared / ui / web-saas-template / docs-site 已实现）
├── configs/              环境配置样例（local / staging / production .env.example）
├── deploy/               部署：compose（本地/CI）+ helm（Phase 2+）
├── scripts/              运维与自检脚本（白名单远程操作三件套 + cloud-agent-* + verify_*）
├── tests/               仓库级测试（unit / integration / e2e）
├── docs/                设计文档体系 + 本 README 分册（docs/readme/）+ 用户手册（docs/user-manual/）
│
├── .github/             GitHub Actions（ci.yml / branch-flow-guard.yml）
├── .cursor/             Cursor 规则、命令、环境与 Dockerfile
├── .claude/             Claude Code agents 与 skills（被 Cursor 兼容扫描）
└── .trae/              Trae IDE 规则（remote-ops 事实源）与 skills

---

二、backend/ 结构

backend/
├── app/                  应用代码（按 7 场域分包）
├── alembic/             数据库迁移脚本
├── alembic.ini
├── tests/               后端测试套件
├── conftest.py
├── Dockerfile           多阶段生产镜像
├── pyproject.toml       依赖 + ruff / mypy / pytest / import-linter 配置
└── uv.lock              依赖锁文件（uv）

backend/app/ 场域包

包	场域	角色
builder/	D-A	项目与资源建模
orchestrator/	D-B	流程编排与发布
delivery/	D-C	应用交付与前端契约
ops/	D-D	运营监控与系统自治
runtime/	D-E	用户任务执行
billing/	D-F	商业化与账务
core/	D-H	基础设施与平台内核
identity/ security/ audit/ storage/ workers/	—	横向支撑子包（鉴权 / 安全 / 审计 / 文件 / Celery worker）
main.py	—	FastAPI 应用装配入口

场域 → 模块的完整映射见 domain_and_module_division.md；场域职责摘要见 architecture.md。

---

三、deploy/ 结构

deploy/
├── compose/
│   ├── docker-compose.yml      本地 / CI / 测试床依赖编排
│   └── initdb/                 PG 初始化 SQL（扩展 + RLS 角色）
├── brand-edge/                 品牌自托管边缘 nginx 模板（默认部署形态）
└── helm/agenthub/              Helm Chart（Phase 2+ deferred）

---

四、docs/ 结构（摘要）

docs/
├── README.md                设计文档体系总览
├── guides/                  **对外指南树**（SaaS 开发者 + AI agent；含 llms.txt）
├── readme/                  本 README 的分册（getting-started / architecture / 本页 / development）
├── ops/                     运维 runbook（对外站点只导出精选）
├── user-manual/             面向使用者的操作手册（index.html，冻结快照）
├── design/                  产品 / 技术 / 任务（过程资产，结构性不对外）
└── seminar/                 研讨决议（不对外）

---

五、相关页

• 用户手册 → ../user-manual/index.html
• 架构总览 → architecture.md
• 环境与运行 → getting-started.md
• 开发流程 → development.md