DevAgentX

全栈 AI 驱动需求交付平台，面向组织内多个项目和多个代码仓库的需求协同与交付自动化。

当前状态

• 正式产品蓝图已收口到 docs/全栈AI驱动需求交付平台方案.md
• 阶段1 平台底座已完成
• 阶段2 仓库接入已完成首轮实现与验收
• 阶段3 需求协同已完成首轮实现与验收
• 阶段4 AI开发首轮主链路已完成
• 阶段5 测试闭环专项文档已补齐
• 当前下一正式工作为阶段5测试闭环实现与阶段4生成质量增强

截至 2026-03-17，平台层验证结果为：

• powershell -ExecutionPolicy Bypass -File scripts/test_dax.ps1 通过，138 passed
• 阶段4增强定向回归 pytest -o addopts='' --confcutdir=tests/dax tests/dax/test_ai_delivery_models.py tests/dax/test_ai_delivery_context_service.py tests/dax/test_ai_delivery_service.py tests/dax/test_ai_delivery_api.py tests/dax/test_metagpt_adapter.py tests/dax/test_config.py -v 通过，23 passed
• 阶段3相关回归 pytest -o addopts='' --confcutdir=tests/dax tests/dax/test_requirement_models.py tests/dax/test_platform_models.py tests/dax/test_requirement_service.py tests/dax/test_requirements_api.py -v 通过，27 passed
• Alembic 阶段4迁移 upgrade head 与 downgrade -1 已验证通过

当前已实现

平台底座

• FastAPI + SQLAlchemy + Alembic 平台后端骨架
• 组织、项目、仓库主业务边界
• 员工按项目可见性授权
• 平台任务与审计基础模型
• Fernet 凭证加密存储与基础安全配置
• 开发期种子数据初始化方案

仓库接入

• GitHub / GitLab Provider 接入与错误翻译
• Token / SSH 凭证类型管理
• 凭证连通性校验、远端仓库列表、显式禁用
• 仓库双凭证模型：
  • api_credential_id
  • git_credential_id
  • transport_protocol
• RepositoryWorkspace 工作区模型
• 工作区主链路：
  • prepare
  • pull
  • checkout
  • commit
  • push
• 仓库接入与工作区 API 路由

需求协同

• RequirementSession 扩展为正式需求协同聚合根
• RequirementMessage、RequirementClarificationItem、RequirementSRSVersion 已落库
• 项目可见范围内的需求会话创建、历史派生、消息时间线、澄清问答
• 规则驱动的 SRS 版本生成与当前版本标记
• 需求确认后自动创建 DeliveryRecord 草稿
• 需求协同 API 已接入：
  • sessions
  • messages
  • clarifications
  • srs
  • confirm

AI开发

• AIDeliveryRun、AIDeliveryRunRepository、AICodeChange、AIReviewNote、AIContextArtifact 已落库
• 已确认需求可基于 DeliveryRecord 发起 AI 开发运行
• 已打通需求上下文、仓库上下文、代码图谱摘要装配
• 候选代码变更、仓库级结果、审阅摘要与失败原因可结构化查询
• 项目到仓库维度的阶段4 API 已接入：
  • POST /api/v1/deliveries/{delivery_record_id}/ai-runs
  • GET /api/v1/deliveries/{delivery_record_id}/ai-runs
  • GET /api/v1/ai-runs/{run_id}
  • GET /api/v1/ai-runs/{run_id}/repositories
  • GET /api/v1/ai-runs/{run_id}/changes
  • GET /api/v1/ai-runs/{run_id}/review-notes
• 标记为 is_applied_to_workspace=true 的候选变更会写回工作区文件
• 已支持通过 DEVAGENTX_METAGPT_* 配置接入真实 MetaGPT 运行时 LLM

尚未开始或未完成

• 阶段5 测试闭环
• 阶段6 平台化收口

当前实现边界

当前代码已经具备阶段4首轮主链路，但以下能力仍是后续补强项：

• 真实 SSH 私钥注入与外部 SSH 远端联调尚未完整闭环
• Gitea 与自托管仓库仍未进入正式实现范围
• 阶段4首轮边界已收口为“候选代码变更与审阅结果”，自动 push 不纳入首轮验收
• MetaGPTAdapter 已支持真实运行时配置接入，后续重点转向模型输出质量和代码图谱增强
• 测试闭环、多渠道接入与平台化部署运维尚未接入平台主流程

项目结构

DevAgentX/
├── dax/                  # 平台业务后端
├── metagpt/              # MetaGPT 引擎基础
├── alembic/              # 数据库迁移
├── docs/                 # 正式产品蓝图与阶段文档
├── docs-metagpt/         # MetaGPT 原始文档
├── scripts/              # 平台测试与辅助脚本
├── tests/                # 测试用例
└── README.md

开发启动

环境要求

• Python 3.9+ 且 < 3.12
• Node.js 20+

安装

git clone https://github.com/YourOrg/DevAgentX.git
cd DevAgentX
pip install -e .

数据库迁移

alembic upgrade head

本地启动

uvicorn dax.main:app --reload

本地联调启动

1. 初始化后端环境变量

copy .env.example .env

将 .env 中的 DEVAGENTX_SECRET_KEY 填为合法 Fernet key。 可通过以下命令生成：

python -m dax.core.security generate-key

本地最小开发配置示例：

DEVAGENTX_SECRET_KEY=<replace-with-generated-key>
DEVAGENTX_METAGPT_API_TYPE=openai
DEVAGENTX_METAGPT_API_KEY=mock-openai-key
DEVAGENTX_METAGPT_BASE_URL=https://api.openai.com/v1
DEVAGENTX_METAGPT_MODEL=gpt-4o-mini

2. 启动后端

alembic upgrade head
uvicorn dax.main:app --reload --host 127.0.0.1 --port 8000

3. 启动前端

cd apps/web
npm install
npm run dev

4. 打开验收工作台

http://localhost:6001/workbench

验证命令

平台层推荐入口：

powershell -ExecutionPolicy Bypass -File scripts/test_dax.ps1

直接运行平台层 pytest：

pytest -o addopts='' --confcutdir=tests/dax tests/dax -v --tb=short

文档索引

• 全栈AI驱动需求交付平台方案
• 平台级总览里程碑实施方案
• 阶段1平台底座设计方案
• 阶段1平台底座实施计划
• 阶段2仓库接入设计方案
• 阶段2仓库接入实施计划
• 阶段2仓库接入验收标准
• 阶段3需求协同设计方案
• 阶段3需求协同实施计划
• 阶段3需求协同验收标准
• 阶段4AI开发设计方案
• 阶段4AI开发实施计划
• 阶段4AI开发验收标准
• 阶段5测试闭环设计方案
• 阶段5测试闭环实施计划
• 阶段5测试闭环验收标准
• 阶段4前最小UI设计方案
• 阶段4前最小UI实施计划
• 阶段4前最小UI验收手册
• MetaGPT 原始文档

最小UI

当前仓库已新增 apps/web 作为阶段4前最小 UI 工作台，技术栈为 Next.js + React + TypeScript。

本地启动前端：

cd apps/web
npm install
npm run dev

默认访问地址：

http://localhost:6001

说明：前端通过自定义 Next server 固定监听 6001。6000 属于浏览器受限端口，不再作为 UI 验收端口使用。

当前已落地页面：

• /workbench
• /organizations
• /projects
• /repositories
• /requirements
• /requirements/[sessionId]
• /deliveries
• /deliveries/[deliveryId]
• /ai-runs/[runId]

当前已落地前端能力：

• 验收模式操作人切换与 cookie 持久化
• /api/acceptance/actor 会话接口
• /api/devagentx/[...path] BFF 代理与后端身份头注入
• 阶段1到阶段4页面化入口、首页最近动态聚合、最近AI运行与高风险摘要、工作台联动分析检索、状态风险筛选、按项目聚合卡片、接口快照卡片
• 项目创建 仓库凭证创建 远端仓库候选读取 仓库绑定 当前仓库概览 工作区状态读取 工作区时间线 相关审计信号检索与 pull checkout commit push 的最小表单
• 需求会话创建 项目和状态筛选 历史会话派生 消息追加 澄清项创建与回答 SRS 生成 需求确认的最小交互
• 交付草稿列表查看 项目筛选 交付关键字筛选 跨交付AI结果检索 交付上下文展示 当前选中交付摘要卡 上一个下一个交付切换 需求回跳 交付详情页结构化展示 项目展示名 需求跳转 仓库级诊断卡 工作区时间线 关联审计信号 AI 运行查询 发起与运行状态筛选
• AI 运行详情页对运行详情 仓库结果 候选代码变更 审阅结论的结构化 UI 视图，并支持交付回跳、需求会话回跳、跨仓库联动检索、仓库结果统计、状态筛选、文件级检索、审阅严重级别筛选和失败原因展示

License

MIT