# enterprise_agent_platform

**Repository Path**: XzcGroup/enterprise_agent_platform

## Basic Information

- **Project Name**: enterprise_agent_platform
- **Description**: 软件公司Agent落地 实现业务需求自动迭代升级 可私有化部署
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-27
- **Last Updated**: 2026-06-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Enterprise Agent Platform

一个企业级 Agent DevOps 闭环平台，覆盖 BUG / 需求工单、自动分析、真实代码修改、测试执行、Git commit、Agent 审计、人工 PR 审批、人工测试验收、状态更新、管理员通知和 Skill 扩展。

当前版本使用 Python 标准库实现后端服务，前端是原生 HTML / CSS / JavaScript，数据默认存储在本地 JSON 文件中，适合快速验证企业级研发 Agent 的完整闭环。

## 功能

- BUG 与需求两类工单
- Agent 编排工作流
- 根因分析 / 需求分析
- 分层 Skill Registry，可视化 CRUD 管理
- 系统配置：应用类型、技术分层、工单类型、特殊要求受控字典
- 分支、commit、PR 的 Git Provider 抽象
- Agent 方案审计与代码修改审计
- 状态流转与审计事件留痕
- JSON 文件存储，便于本地演示
- 可视化操作面板
- 项目配置：项目标识、仓库、默认分支、reviewer、测试命令、可修改范围
- 模型库：可配置多个 Mock / 国产大模型 / 自定义中转站模型
- 项目级模型关联：每个项目只关联一个模型 ID，模型参数集中在模型库维护
- 项目级代码定位：配置本地项目文件夹后，Agent 会读取真实代码文件作为上下文
- CodingAgent 可生成结构化 patch、应用 patch 并提交真实 commit
- TestAgent 可执行项目配置的真实测试命令，未配置测试命令时只生成测试建议并明确标记未运行真实测试
- 测试或 Agent 审计不通过时，平台会记录原因并自动打回 CodingAgent 返工；只有测试和审计都通过的工单才进入人工 PR 审批
- 人工 PR 审批与人工测试验收分阶段留痕，验收通过后再合并主线
- CLI demo 与单元测试

## 架构概览

```text
浏览器可视化面板
  ├─ 工单控制台
  ├─ 项目管理
  ├─ 模型管理
  ├─ Skill 管理
  ├─ 系统配置
  └─ 管理员通知
        │
        ▼
Python Web App / API
  ├─ /api/tasks
  ├─ /api/projects
  ├─ /api/models
  ├─ /api/skills
  └─ /api/notifications
        │
        ▼
Agent Workflow
  ├─ IntakeAgent        工单分诊和 Skill 匹配
  ├─ ContextAgent       读取项目代码上下文
  ├─ AnalysisAgent      BUG 根因或需求分析
  ├─ PlanningAgent      生成实现计划
  ├─ CodingAgent        生成 patch、应用 patch、提交代码
  ├─ TestAgent          执行项目测试命令
  ├─ ReviewAgent        Agent 方案审计和修改审计
  └─ NotifyAgent        发送管理员通知
        │
        ├─ ModelGateway            Mock / 国产模型 / 自定义中转站
        ├─ LocalGitProvider        本地 Git 分支、commit、PR 记录
        ├─ JsonStore               .agent_data/*.json
        └─ Project Runtime         真实项目目录、可修改范围、测试命令
```

## 快速运行

```bash
git clone git@gitee.com:XzcGroup/enterprise_agent_platform.git
cd enterprise_agent_platform
python3 -m enterprise_agent.web_app
```

然后打开：

```text
http://127.0.0.1:8765
```

CLI 仍然保留给开发调试：

```bash
python3 -m enterprise_agent.cli demo-bug
python3 -m enterprise_agent.cli demo-requirement
python3 -m unittest discover -s tests -v
```

运行后默认使用项目根目录下的 `.agent_data/`，里面包含工单、事件、commit、PR、通知和 Skill 数据。这个目录是本地持久化目录，不会因为从其他目录启动服务而漂移到临时路径。

也可以显式指定端口和数据目录。生产或长期调试时建议使用项目内或固定磁盘目录，不要使用 `/tmp` 这类临时目录：

```bash
python3 -m enterprise_agent.web_app --port 8765 --data-dir /path/to/persistent-agent-data
```

## 管理页面

左侧提供独立管理入口：

- 项目管理：项目列表、创建、编辑、删除、刷新。
- 模型管理：模型列表、创建、编辑、删除、刷新。
- Skill 管理：Skill 列表、创建、编辑、删除、启停、刷新。
- 系统配置：固定四类配置，分别维护应用类型、技术分层、工单类型、特殊要求下的配置项。
- 项目管理、模型管理和 Skill 管理采用左侧列表、右侧详情编辑的主从布局；系统配置采用左侧固定类别、右侧配置项列表、弹窗新增和编辑。
- 项目会出现在新建工单的项目下拉中，并自动带出仓库地址。
- 模型管理可以创建多个模型配置，例如 `deepseek-main`、`qwen-coder`、`custom-relay`、`mock-default`。
- 每个项目可以配置本地项目文件夹、Git 仓库、主线分支，并关联一个模型 ID。
- 每个项目可以配置可修改路径、测试命令和测试超时时间。
- 创建 BUG / 需求时会按项目读取本地代码上下文，匹配相关文件后再进入根因分析和方案生成。
- 模型配置可以选择 `Mock 本地演示模型`、国产模型供应商或 `自定义 / 中转站`。
- 模型如果正在被项目引用，删除会被拒绝。

## 系统配置

系统配置用于维护 Skill 表单中的受控选项，避免自由输入造成分类不可控。

当前包含四类配置：

```text
application_types       应用类型，例如 Web 应用、后台服务、管理后台、SaaS
technical_layers        技术分层，例如前端、后端、数据库、测试、安全
task_types              工单类型，目前对应 BUG 和需求
special_requirements    特殊要求，例如必须补测试、不能改表、兼容旧版本
```

这四类是平台固定分类，不能由用户新增或删除。用户只能维护某一类下面的配置项，例如新增一个应用类型、编辑一个技术分层名称、停用某个特殊要求。

应用类型和技术分层是独立维度，不做强绑定。应用类型可以配置 `recommended_technical_layers`，用于在 Skill 配置时推荐常见技术分层，但仍允许管理员按实际情况调整。

内置模型供应商：

```text
deepseek              DeepSeek
qwen                  阿里云百炼 / 通义千问
zhipu                 智谱 GLM
kimi                  Kimi / Moonshot
minimax               MiniMax
baidu-qianfan         百度千帆 / 文心
tencent-hunyuan       腾讯混元
volcengine-doubao     火山方舟 / 豆包
iflytek-spark         讯飞星火
custom                自定义 / 中转站
```

这些配置默认按 OpenAI-compatible Chat Completions 协议调用。内置供应商会自动填入一组可编辑的默认 `Base URL` 和 `Model`；实际接入时请以你账号控制台开通的模型名和网关地址为准。

DeepSeek 示例配置：

```text
Provider: DeepSeek
Base URL: https://api.deepseek.com
Model: deepseek-v4-flash
API Key: 你的 DeepSeek API Key
```

自定义中转站示例配置：

```text
Provider: 自定义 / 中转站
Base URL: https://relay.example.com/v1
Model: relay-model-name
API Key: 中转站分配的 API Key
```

模型配置保存在本地 `.agent_data/models.json`。API Key 不会返回给前端，接口只暴露 `api_key_set`。

项目只保存 `model_id` 关联，不保存模型 API Key。多个项目可以复用同一个模型配置。

## 项目配置

每个项目用于告诉 Agent 去哪里找代码、哪些文件可以改、如何测试、使用哪个模型。

关键字段：

```text
project_key       项目标识，例如 ORDER、CRM、PAY
local_path        本地项目文件夹地址
git_repository    Git 仓库地址或仓库标识
main_branch       主线分支，例如 main、master、develop
editable_paths    允许 Agent 修改的路径，例如 src,tests
test_command      测试命令，例如 pytest、npm test、mvn test
test_timeout      测试超时时间
model_id          关联的模型配置 ID
reviewers         人工 PR 审计人
```

项目自己的业务事实、架构说明、目录规则、接口约束和特殊注意事项，建议继续放在项目仓库内：

```text
AGENTS.md
README.md
docs/architecture.md
docs/domain.md
docs/testing.md
```

平台 Skill 只描述 Agent 的通用做事方法，项目文档才描述某个项目的真实业务知识。

## 真实代码修改流程

当前 Git 处理策略：

- 如果项目配置了本地文件夹，Agent 会读取其中的代码文件作为上下文。
- 如果该文件夹是干净的 Git 仓库，Agent 会创建任务分支。
- CodingAgent 会要求模型返回结构化 JSON 文件修改，只允许写入项目配置的可修改路径。
- 文件修改成功后会提交真实 Git commit，commit message 绑定工单号。
- 如果配置了测试命令，TestAgent 会在项目目录执行真实测试命令；测试失败或超时会阻断后续 PR 审计。
- 如果仓库存在未提交改动，系统不会强行切分支、写文件或提交，避免覆盖你的工作区。

端到端状态大致如下：

```text
新建工单
  -> 已分诊
  -> 读取项目上下文
  -> 根因分析 / 需求分析
  -> 生成实现计划
  -> 生成并应用代码修改
  -> 创建工单 commit
  -> 运行测试
  -> 测试不通过则带原因自动返工
  -> Agent 审计
  -> 审计不通过则带原因自动返工
  -> 待人工 PR 审计
  -> 待人工测试验收
  -> 合并主线
```

自动返工默认最多 2 次，项目配置可通过 `max_rework_attempts` 覆盖，平台会限制在 0 到 5 次之间。返工次数耗尽或遇到无法自动处理的代码阻塞时，工单才会转为需人工介入。

模型生成代码修改时必须返回：

```json
{
  "changes": [
    {
      "path": "src/example.py",
      "content": "修改后的完整文件内容"
    }
  ],
  "summary": "修改摘要"
}
```

## API 概览

```text
GET    /api/tasks
POST   /api/tasks
GET    /api/tasks/{task_id}
POST   /api/tasks/{task_id}/run

GET    /api/projects
POST   /api/projects
GET    /api/projects/{project_key}
PUT    /api/projects/{project_key}
DELETE /api/projects/{project_key}

GET    /api/models
POST   /api/models
GET    /api/models/{model_id}
PUT    /api/models/{model_id}
DELETE /api/models/{model_id}

GET    /api/skills
POST   /api/skills
GET    /api/skills/{skill_name}
PUT    /api/skills/{skill_name}
DELETE /api/skills/{skill_name}

GET    /api/notifications

GET    /api/system-options
GET    /api/system-options/{category}
POST   /api/system-options/{category}
GET    /api/system-options/{category}/{option_id}
PUT    /api/system-options/{category}/{option_id}
DELETE /api/system-options/{category}/{option_id}
```

## 目录

```text
enterprise_agent/
  agents.py          # Triage / Context / RootCause / Requirement / Coding / Test / Review / PR Agent
  cli.py             # 命令行入口
  git_provider.py    # Git/PR 抽象与本地模拟实现
  model_gateway.py   # 模型网关与 Mock 模型
  models.py          # 核心领域模型
  notifications.py   # 管理员通知
  skills.py          # 自定义 Skill 注册与检索
  storage.py         # JSON 存储
  web_app.py         # Web 可视化操作面板与 API
  workflow.py        # BUG / 需求工作流
static/
  index.html         # 操作面板
  styles.css         # 面板样式
  app.js             # 前端交互
examples/
  order_domain_skill.json
tests/
  test_real_execution.py
  test_workflow.py
```

## Skill 示例

Skill 是平台级 Agent 方法论，不承载某个项目的事实。项目目录结构、业务规则、接口约束等信息仍建议放在项目自己的 `AGENTS.md`、`README.md` 或 `docs/` 中。

当前 Skill 支持四类分层字段，这些字段从系统配置读取：

```text
layer: application | technical | task | special
application_types: web, backend, app, saas, admin 等
technical_layers: frontend, backend, database, test, devops, security 等
task_types: bug, requirement
special_requirements: must-test, no-db-change, compatible 等
```

Agent 匹配 Skill 时会综合触发词、应用类型、技术分层、工单类型和特殊要求，并按 `priority` 从高到低注入模型上下文。

说明：代码内部字段暂时仍叫 `task_types`，但产品概念上它表示“工单类型”，与新建工单里的 BUG / 需求保持一致。

```json
{
  "name": "order-domain-debug-skill",
  "description": "订单领域 BUG 分析规则",
  "version": "1.0.0",
  "layer": "task",
  "application_types": ["backend", "service"],
  "technical_layers": ["backend", "database", "test"],
  "task_types": ["bug", "requirement"],
  "special_requirements": ["must-test", "human-review-for-payment"],
  "enabled": true,
  "priority": 80,
  "triggers": ["订单", "支付", "库存", "状态流转"],
  "instructions": [
    "优先检查 OrderService、PaymentService、InventoryService",
    "并发问题需要检查幂等逻辑和事务边界",
    "修复订单状态流转时必须补充集成测试"
  ],
  "tools": ["query_logs", "search_commits", "run_order_tests"],
  "constraints": [
    "禁止直接修改数据库表结构，除非需求明确要求",
    "不得绕过订单状态机"
  ]
}
```

## 开发验证

提交前建议运行：

```bash
python3 -m py_compile enterprise_agent/*.py
python3 -m unittest discover -s tests -v
node --check static/app.js
```

`tests/test_real_execution.py` 会创建临时 Git 仓库，验证 Agent 能够应用 patch、运行测试并创建真实 commit。

## Git 管理

当前仓库远端：

```bash
git@gitee.com:XzcGroup/enterprise_agent_platform.git
```

`.agent_data/` 是本地运行数据，已经通过 `.gitignore` 排除，不会提交到远端。

## 后续可扩展方向

- 将 `LocalGitProvider` 替换成 GitHub / GitLab Provider
- 将 JSON 存储替换成 PostgreSQL
- 将同步工作流替换成 Temporal / Celery / Argo Workflows
- 加入代码执行沙箱、容器隔离和权限审计
- 接入企业 IM、邮件、飞书、钉钉通知
- 增加人工审批页面、PR 合并回调和测试环境发布流水线