# devops-agent

**Repository Path**: vnimy/devops-agent

## Basic Information

- **Project Name**: devops-agent
- **Description**: AI 驱动的多框架项目开发-测试-上线全流程工具 —— Skill 驱动架构。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-02
- **Last Updated**: 2026-07-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🔧 DevOps Agent

AI 驱动的多框架项目开发-测试-上线全流程工具 —— Skill 驱动架构。

| 指标 | 值 |
|------|-----|
| Python | 3.11+ |
| 测试 | pytest + ruff clean |
| 命名空间 | `devops_agent` |
| 架构 | Skill 驱动 → MCP 工具 → tools/ 执行层 |
| 安装方式 | `pip install devops-agent` 或本地运行 |
| 看板 | http://devops.internal.mediad.cn |

---

## 快速开始

DevOps Agent 通过 **OpenCode Skill 文件** 驱动部署工作流。AI 客户端按照 Skill 中的指引调用 MCP 工具，MCP 工具再调用 `tools/` 层执行实际操作。

### 1. 接入 OpenCode

在项目或全局 `opencode.json` 中添加 MCP 服务配置：

```json
{
  "mcp_servers": {
    "devops-agent": {
      "command": "python",
      "args": ["-m", "devops_agent.mcp.server"]
    }
  }
}
```

### 2. 安装 Skill 文件

将 `skills/` 目录下的 6 个 Skill 文件复制到 OpenCode skills 目录：

```bash
cp skills/devops-*.md ~/.config/opencode/skills/
```

### 3. 使用

在 OpenCode 中直接用自然语言发起部署：

```
> 帮我部署物流模块到测试环境
> 快速验证一下新功能
> 生成项目文档
```

AI 会根据关键词自动加载对应 Skill（devops-deploy / devops-validate / devops-docs），Skill 指引 AI 按正确顺序调用 MCP 工具。

---

## 初始化项目

通过 MCP 工具的 `devops_init_new` 创建新项目：

```bash
# AI 侧：加载 devops-init Skill 后调用 MCP 工具
# 或直接通过 Python：
python -c "
from devops_agent.mcp.server import init_new
print(init_new(template='frappe', project_name='my-erp'))
"
```

**可用模板**: `frappe`（含外部 Skill 包引用）、`django`、`nodejs`、`generic`

---

## 项目配置 `.devops.yml`

在每个项目根目录放一份配置，Agent 自动读取：

```yaml
project:
  name: my-erp
  tags: [frappe, erpnext]

framework:
  type: frappe          # frappe | django | nodejs | generic
  version: "15"
  frappe:
    develop:
      apps: []
    build:
      build_dir: ""
      erpnext:
        version: version-15
      custom:
        version: version-15
        image_name: erp
        tag: ""
        suffix: ""
        fast: true
        apps: []

infrastructure:
  target: dev           # dev | staging | production
  docker:
    registry: docker.io
    namespace: myteam

sync:
  hub_url: ""           # Hub 地址，为空不启用同步
  enabled: false

team:
  ssh_mode: restricted  # restricted | agent
  maintainers: []
```

完整参考见 [`.devops.yml.sample`](.devops.yml.sample)。敏感信息通过 `DEVOPS_*` 环境变量传入，不写入配置文件。

---

## 架构总览

```
┌─ AI 客户端 (OpenCode) ───────────────────────────────────┐
│  用户自然语言 → AI 按关键词选择 Skill  → 调用 MCP 工具     │
└──────────────────────┬──────────────────────────────────┘
                       ▼
┌─ Skill 层 ───────────────────────────────────────────────┐
│  skills/devops-detect.md     frameworks → 工具选择        │
│  skills/devops-deploy.md     部署 → devops_deploy         │
│  skills/devops-validate.md   快速验证 → quick_validate     │
│  skills/devops-approve.md    审批 → devops_status          │
│  skills/devops-init.md       脚手架 → devops_init_new      │
│  skills/devops-docs.md       文档 → devops_generate_docs   │
└──────────────────────┬──────────────────────────────────┘
                       ▼
┌─ MCP 工具层 (server.py, 1418 行) ────────────────────────┐
│  devops_process_message    自然语言 → 自动分场景          │
│  devops_deploy             完整部署管线                    │
│  devops_quick_validate     快速验证管线                    │
│  devops_detect_framework   框架检测                        │
│  devops_health_check       健康检查                        │
│  devops_generate_docs      文档生成                        │
│  devops_init_list / _new   项目脚手架                      │
│  devops_status / _cancel   任务管理                        │
│  devops_version / _config  系统信息                        │
│  → 所有工具为自包含轻量封装，直接调用 tools/ 层            │
└──────────────────────┬──────────────────────────────────┘
          ┌────────────┼────────────┐
          ▼            ▼            ▼
┌─ Tools ────┐ ┌─ Framework ─┐ ┌─ Hub ───────────────┐
│ docker.py  │ │ adapter.py  │ │ client.py — Hub HTTP │
│ deploy.py  │ │ frappe.py   │ └─────────────────────┘
│ health.py  │ │ django.py   │
│ audit.py   │ │ nodejs.py   │ ┌─ Hub Server ────────┐
│ gate.py    │ └─────────────┘ │ auth/sync/knowledge  │
│ repo.py    │                 │ collab/vhost/ws      │
│ code_gate  │                 │ web/ — FastAPI 管理   │
│ docs.py    │                 └──────────────────────┘
└────────────┘
```

### 架构变更说明

**已废弃并删除的模块**（原先的编排逻辑已迁移到 Skill 文件）：
- `agent/`（含 `engine.py`） — AI 需求解析（现由 devops-deploy Skill 替代）
- `workflows/`（含 `pipeline.py`、`scenarios.py`） — 可插拔 Stage 链（现由 server.py 内联 + Skill 编排）
- `cli/main.py` / `cli/deploy_cmds.py` — CLI 入口已废弃
- `chat/`（含 `openchat.py`、`webhook.py`、`adapter.py`） — 交互入口已废弃

### 模块详解

| 模块 | 关键文件 | 职责 |
|------|---------|------|
| **skills/** | `devops-detect.md` 等 6 个 | Skill 文件：AI 工作流指引，替代原先 engine/scenarios/pipeline 的编排逻辑 |
| **mcp/** | `server.py` (1418 行) | MCP 工具服务器：12 个自包含工具，直接调用 tools/ 层执行 |
| **tools/** | `docker.py` | Docker 构建/推送/compose 操作 |
| **tools/** | `deploy.py` | ComposeBackend — 部署/回滚/状态查询 |
| **tools/** | `deploy_frappe.py` | Frappe 专用部署流程（bench build / migrate） |
| **tools/** | `deploy_ssh.py` | SSH 直连部署后端 |
| **tools/** | `deploy_agent/` | Agent 转发部署后端（远程 agent 通信） |
| **tools/** | `health.py` | HTTP 健康检查 + 重试 + 回滚触发 |
| **tools/** | `code_gate.py` | 安全路径检查 + ruff lint |
| **tools/** | `gate.py` | ApprovalGate — 生产部署人工审批门禁 |
| **tools/** | `audit.py` | 审计日志（JSON Lines）+ 部署记录本地 SQLite |
| **tools/** | `repo.py` | Monorepo 变更检测 + 拓扑排序 |
| **tools/** | `docs.py` | MkDocs 构建 + 部署 |
| **framework/** | `adapter.py` | FrameworkAdapter 抽象基类 |
| **framework/** | `frappe.py` | Frappe 适配器（bench path / build.sh / migrate） |
| **framework/** | `django.py` / `nodejs.py` | Django / Node.js 适配器存根 |
| **hub/** | `client.py` | Hub HTTP 客户端（注册 / 推送部署记录 / 知识库） |
| **init/** | `templates.py` | 4 框架模板生成器（注册表模式） |
| **config/** | `settings.py` | Pydantic BaseSettings + 环境变量覆盖 |
| **types.py** | — | Pydantic 数据模型 |
| **cli/** | `hub_cmds.py` | Hub 管理 CLI（login/logout/push/heartbeat） |

**Hub Server**（独立服务，可选部署）：

| 模块 | 关键文件 | 职责 |
|------|---------|------|
| **server/** | `auth.py` | 设备注册/认证/吊销 |
| **server/** | `sync.py` | 跨设备同步（差量同步） |
| **server/** | `knowledge.py` | 团队知识库 CRUD |
| **server/** | `vhost.py` | 虚拟主机管理 |
| **server/** | `collab.py` | 团队协同（4 种模式 + 环境锁） |
| **server/** | `ws.py` | In-memory pub/sub 通知 |
| **server/web/** | `app.py` | FastAPI 管理面板（20+ REST 端点） |

---

## 六大场景

所有场景现通过 **Skill 文件路由**，AI 自动选择正确的 Skill 和 MCP 工具。

### 场景 1：快速验证

```
用户说 "快速验证" → AI 加载 devops-validate Skill →
devops_quick_validate → lint → build → push → deploy → 返回 URL
```

- **耗时**: < 5 分钟
- **特点**: 跳过测试和数据库迁移，只做 lint + 容器构建
- **触发**: 用户提及 "快速"、"验证"、"quick"、"demo"
- **Skill**: `devops-validate`

### 场景 2：标准迭代

```
用户说 "部署" → AI 加载 devops-deploy Skill →
devops_deploy → lint → test → dry-run migrate → build →
push → deploy → 健康检查 → [人工审批] → 部署生产环境
```

- **特点**: 全量门禁，生产环境需审批
- **触发**: 用户提及 "部署"、"上线"、"deploy"、"发布"
- **Skill**: `devops-deploy`

### 场景 3：需求梳理与文档发布

```
用户说 "生成文档" → AI 加载 devops-docs Skill →
devops_generate_docs → LLM 生成 5 类文档 → 写入 docs/ → mkdocs build
```

- **输出**: 概览、架构、API 规格、部署指南、路线图
- **触发**: 用户提及 "文档"、"docs"、"mkdocs"
- **Skill**: `devops-docs`

### 场景 4：跨设备同步

Hub 服务同步 Agent 状态（会话/记忆/配置/Skill），差量同步（`updated_at` 比较），冲突策略：last-wins。

### 场景 5：团队协同

| 模式 | 说明 |
|------|------|
| `app_partition` | 按 App 划分，各团队互不干扰 |
| `env_partition` | 按环境划分，测试/生产隔离 |
| `free_collab` | 自由协作，无锁 |
| `approval_flow` | 所有部署走审批 |

互斥环境锁 + FIFO 部署队列 + 实时通知。

### 场景 6：知识共享

团队知识库（规范/流程/心得），支持 CRUD、关键词搜索、项目过滤，AI 在代码生成时自动引用知识条目。

---

## Hub 管理后台

FastAPI Web 面板，可选部署：

```bash
# 启动 Hub 管理后台
uvicorn devops_agent_hub.web.app:app --host 127.0.0.1 --port 8020
```

| 端点 | 功能 |
|------|------|
| `GET /dashboard` | 聚合统计（设备/知识库/虚拟主机/审批） |
| `GET /team` | 设备列表 |
| `GET /knowledge` | 知识库搜索 |
| `CRUD /vhosts` | 虚拟主机管理 |
| `GET /deployments` | 部署审计日志 |
| `POST /approvals/{id}/approve\|reject` | 审批操作 |

认证：`X-API-Token` Header（通过 `DEVOPS_API_TOKEN` 环境变量配置）。

---

## Skill 文件详解

| Skill | 文件 | 触发关键词 | 对应 MCP 工具 |
|-------|------|-----------|--------------|
| **devops-detect** | `skills/devops-detect.md` | 检测框架, 读取配置 | `devops_detect_framework` |
| **devops-deploy** | `skills/devops-deploy.md` | 部署, deploy, 上线, 发布 | `devops_deploy`, `devops_process_message` |
| **devops-validate** | `skills/devops-validate.md` | 快速部署, quick, 验证, demo | `devops_quick_validate` |
| **devops-approve** | `skills/devops-approve.md` | 审批, approve, 放行 | `devops_status` |
| **devops-init** | `skills/devops-init.md` | 创建项目, 初始化, 脚手架 | `devops_init_list`, `devops_init_new` |
| **devops-docs** | `skills/devops-docs.md` | 生成文档, docs, mkdocs | `devops_generate_docs` |

Skill 文件包含完整的工作流指引：何时调用哪个 MCP 工具、传入什么参数、如何处理返回结果。AI 严格遵循 Skill 中的步骤，**不会**自行决定绕过 MCP 工具直接执行 SSH/docker compose 等操作。

---

## 配置项

| 配置段 | 环境变量前缀 | 关键字段 |
|--------|-------------|---------|
| LLM | `DEVOPS_LLM_*` | provider, model, temperature |
| Deploy | `DEVOPS_DEPLOY_*` | registry, namespace, default_target |
| Audit | `DEVOPS_AUDIT_*` | dir, retention_days |
| Hub | `DEVOPS_HUB_*` | url, token, sync_enabled |
| SSH | `DEVOPS_SSH_*` | key_path, mode |

---

## 安全设计

1. **不硬编码凭证** — API Key / Token / Password 全部走环境变量
2. **生产部署人工门禁** — ApprovalTicket → 人工 approve/reject → 超时自动驳回
3. **代码生成安全路径** — 禁止修改 `frappe/core`、`erpnext` 核心代码
4. **SSH 限制模式** — `restricted` 模式通过 `authorized_keys command=` 限制命令
5. **审计全覆盖** — 每次操作写入 JSON Lines 审计日志，敏感字段自动遮蔽
6. **凭证不落地** — 登录 registry 使用 `--password-stdin`

---

## CI/CD

两个 GitHub Actions Workflow：

### test.yml — CI

| 触发 | Python 版本 | 步骤 |
|------|------------|------|
| push/PR → main | 3.11 / 3.12 / 3.13 | ruff check → pytest |

### docs.yml — 看板发布

| 触发 | 步骤 |
|------|------|
| push main + 手动 | mkdocs build --strict → GitHub Pages |

---

## 测试

```bash
# Client 测试
pytest client/tests/ -v

# Server 测试
pytest server/tests/ -v

# 运行全部测试
pytest client/tests/ server/tests/ -v
```

测试覆盖 tools/（docker / deploy / health / gate / audit / code_gate / repo / docs）、framework/、init/、config/、deploy_agent/、以及 Hub Server 的 auth / sync / knowledge / vhost / collab / web。

---

## 开发

```bash
# 安装开发依赖
uv sync --group dev

# 运行 lint
ruff check .

# 运行测试
pytest client/tests/ server/tests/ -v --tb=short
```

**修改 MCP 代码后**需要重启 OpenCode 服务才能生效：

```bash
systemctl --user restart opencode-web
```

---

## 文档与看板

| 文档 | 在线地址 |
|------|---------|
| 项目看板 | http://devops.internal.mediad.cn |
| 需求文档 | http://devops.internal.mediad.cn/requirements.html |
| 实施计划 | http://devops.internal.mediad.cn/plan.html |
| Hub 原型 | http://devops.internal.mediad.cn/hub-proto.html |

```bash
# 本地预览 MkDocs
mkdocs serve

# 构建并发布看板
mkdocs build
```

本地文档：`.omo/memory.md`（项目记忆） · `.omo/plans/devops-agent.md`（工作规划） · `.omo/drafts/`（需求/计划原始稿）

---

## 项目变更记录

记录在 `.omo/memory.md`，包括架构决策、使用方法、状态快照。新会话开始时加载该文件即可恢复完整上下文。