263 lines
8.7 KiB
Markdown
263 lines
8.7 KiB
Markdown
|
||
|
||
# gitea-issue-devops-agent
|
||
|
||
> **Issue-Driven DevOps 产品官网**
|
||
> 把 `Issue -> Plan -> Branch -> Draft PR -> Preview Slot -> Test Loop -> Human-Confirmed Merge` 变成标准交付引擎。
|
||
|
||
## 公网产品页
|
||
|
||
- 产品官网（独立前端渲染页，非 Wiki）：`https://fun-md.com/Fun_MD/devops-skills/raw/branch/main/site/index.svg`
|
||
- 仓库入口：`https://fun-md.com/Fun_MD/devops-skills`
|
||
- HTML 设计稿源码：`site/index.html`
|
||
- SVG 官网文件：`site/index.svg`
|
||
|
||
## 核心价值
|
||
|
||
### 1) 计划先行，避免 AI 脑裂
|
||
|
||
每个 issue 在编码前先生成可持久化 Plan，明确范围、验收、验证路径和 Agent 分工，避免多 Agent 或长流程中的上下文漂移。
|
||
|
||
### 2) 分支隔离提测
|
||
|
||
每个 issue 固定独立分支和预览槽位，主干保持稳定回归，避免提测互相覆盖。
|
||
|
||
### 3) 智能节省资源
|
||
|
||
按改动自动识别部署策略：`skip / client_only / server_only / full_stack / infra_only`。
|
||
**服务端未变更就不重启服务端**。
|
||
|
||
### 4) 证据化闭环
|
||
|
||
提测沉淀 commit、PR、测试链接、环境 URL、验证步骤；最终合并必须工程师人工确认。
|
||
|
||
## 一键安装
|
||
|
||
### Linux
|
||
|
||
```bash
|
||
curl -fsSL https://fun-md.com/Fun_MD/devops-skills/raw/branch/main/install/install.sh | bash
|
||
```
|
||
|
||
### macOS
|
||
|
||
```bash
|
||
curl -fsSL https://fun-md.com/Fun_MD/devops-skills/raw/branch/main/install/install.sh | bash
|
||
```
|
||
|
||
### Windows (PowerShell)
|
||
|
||
```powershell
|
||
powershell -NoProfile -ExecutionPolicy Bypass -Command "iwr -useb https://fun-md.com/Fun_MD/devops-skills/raw/branch/main/install/install.ps1 | iex"
|
||
```
|
||
|
||
安装目标目录：
|
||
|
||
- `~/.codex/skills/gitea-issue-devops-agent`
|
||
|
||
## 工具使用说明
|
||
|
||
### issue_audit.py
|
||
|
||
```bash
|
||
python skills/gitea-issue-devops-agent/scripts/issue_audit.py \
|
||
--base-url https://fun-md.com \
|
||
--repo FunMD/document-collab \
|
||
--token <TOKEN> \
|
||
--state all \
|
||
--download-attachments \
|
||
--output-dir .tmp/issue-audit
|
||
```
|
||
|
||
### change_scope.py
|
||
|
||
```bash
|
||
python skills/gitea-issue-devops-agent/scripts/change_scope.py --repo-path . --base-ref origin/main --head-ref HEAD
|
||
```
|
||
|
||
### preview_slot_allocator.py
|
||
|
||
```bash
|
||
python skills/gitea-issue-devops-agent/scripts/preview_slot_allocator.py --state-file .tmp/preview-slots.json --slots preview-a,preview-b --repo FunMD/document-collab --issue 48 --branch dev --ttl-hours 24 --url-template https://{slot}.qa.example.com --evict-oldest
|
||
```
|
||
|
||
## 工作流模板
|
||
|
||
- `.gitea/workflows/issue-branch-preview.yml`
|
||
- `.gitea/workflows/preview-slot-reclaim.yml`
|
||
- `.gitea/workflows/publish-site.yml`
|
||
|
||
## Skills 调用前置信息（Claude Code / Codex / OpenCode）
|
||
|
||
统一建议先准备这组参数：
|
||
|
||
- `repo_url`
|
||
- `api_key`（Gitea token，需 issue 读写权限）
|
||
- `mode`（`automatic` / `semi-automatic` / `manual`）
|
||
- `issue` 或固定 issue 触发来源
|
||
- 可选：`target_base`、`plan_path`、`reviewers`、`test_entry`、`deploy_env`、`health_endpoint`、`min_quality_score`、`jj_policy`
|
||
|
||
### Claude Code
|
||
|
||
Skills 目录（官方支持）：
|
||
|
||
- 用户级：`~/.claude/skills/<skill-name>/SKILL.md`
|
||
- 项目级：`.claude/skills/<skill-name>/SKILL.md`
|
||
|
||
唤起方式：
|
||
|
||
- 显式调用：`/<skill-name> [args]`
|
||
- 对话调用：直接说“使用某个 skill 处理任务”
|
||
|
||
示例：
|
||
|
||
```text
|
||
/gitea-issue-devops-agent repo_url=https://fun-md.com/FunMD/document-collab mode=automatic
|
||
```
|
||
|
||
```text
|
||
请使用 gitea-issue-devops-agent，连接 repo_url=...，api_key=...，以 semi-automatic 模式处理 issue #48
|
||
```
|
||
|
||
### Codex
|
||
|
||
Skills 安装目录（当前方案）：
|
||
|
||
- `~/.codex/skills/gitea-issue-devops-agent`
|
||
|
||
唤起方式：
|
||
|
||
- 对话显式点名：`$gitea-issue-devops-agent`
|
||
- 或自然语言明确要求：`使用 gitea-issue-devops-agent skill`
|
||
|
||
示例：
|
||
|
||
```text
|
||
$gitea-issue-devops-agent
|
||
repo_url: https://fun-md.com/FunMD/document-collab
|
||
api_key: <TOKEN>
|
||
mode: automatic
|
||
issue: 48
|
||
```
|
||
|
||
### OpenCode
|
||
|
||
Skills 目录（Claude skill 兼容）：
|
||
|
||
- 项目级：`.opencode/skills/<skill-name>/SKILL.md`
|
||
- 全局级：`~/.config/opencode/skills/<skill-name>/SKILL.md`
|
||
|
||
唤起方式：
|
||
|
||
- 对话里明确要求使用目标 skill（推荐）
|
||
- Agent 内部会通过原生 `skill` 工具加载（`skill({name: "..."})`）
|
||
|
||
示例：
|
||
|
||
```text
|
||
Use skill gitea-issue-devops-agent.
|
||
repo_url=https://fun-md.com/FunMD/document-collab
|
||
api_key=<TOKEN>
|
||
mode=manual
|
||
```
|
||
|
||
## `skills` 命令参数释义（重点补充）
|
||
|
||
> 本节把“`skills` 命令”统一理解为：在 Claude/Codex/OpenCode 中显式调用 `gitea-issue-devops-agent` 时提交的参数块。
|
||
> 建议参数名如下，便于团队协作时统一模板和自动化脚本对接。
|
||
|
||
### 必填参数
|
||
|
||
| 参数 | 说明 | 典型值 | 使用场景 |
|
||
| --- | --- | --- | --- |
|
||
| `repo_url` | 目标仓库完整地址。优先使用完整 URL。 | `https://fun-md.com/Fun_MD/devops-skills` | 常规接入，避免 `base_url + owner/repo` 组合歧义 |
|
||
| `api_key` | Gitea token，至少具备 issue 读写权限。 | `gta_xxx` | 需要读取 issue、评论、附件并回写提测证据 |
|
||
| `mode` | 执行模式：`automatic` / `semi-automatic` / `manual`。 | `automatic` | 决定自动化程度和人工审批点 |
|
||
| `issue` | 固定 issue 编号或触发来源。 | `48` | 将一次交付限定在一个可控 issue 上 |
|
||
|
||
### 重要可选参数
|
||
|
||
| 参数 | 说明 | 典型值 | 使用场景 |
|
||
| --- | --- | --- | --- |
|
||
| `reviewers` | 指定评审人列表（逗号分隔）。 | `alice,bob` | `semi-automatic` 模式下提交后等待人工评审 |
|
||
| `plan_path` | Plan 持久化路径。 | `.tmp/devops-plans/devops-skills__issue-48.md` | MajorAgent/SubAgent/TestAgent 共享状态 |
|
||
| `test_entry` | 分支提测入口（CI 命令或 job 名）。 | `gitea workflow run issue-branch-preview` | 多条流水线并存时明确提测入口 |
|
||
| `main_env_url` | 主干稳定环境 URL。 | `https://main.qa.example.com` | 回归对比、基线验证 |
|
||
| `shared_qa_url` | 共享 QA 环境 URL（可选）。 | `https://qa.example.com` | 需要跨分支集成验证 |
|
||
| `preview_slots` | 预览槽位池。 | `preview-a,preview-b` | 多 issue 并行时的环境隔离与复用 |
|
||
| `preview_url_template` | 槽位 URL 模板。 | `https://{slot}.qa.example.com` | 自动生成 issue 分支预览地址 |
|
||
| `deploy_env` | 部署环境标识。 | `k8s-staging` | 一套技能同时驱动多环境 |
|
||
| `health_endpoint` | 健康检查接口。 | `/healthz` | 提测后自动做可用性验证 |
|
||
| `min_quality_score` | issue 最低质量分（默认 70）。 | `70` | 低质量 issue 先补充信息再进入开发 |
|
||
| `skip_asset_endpoints` | 跳过 `/issues/*/assets` 端点抓图。 | `true` | 自建 Gitea 禁用了 assets API 时兜底 |
|
||
| `target_base` | 变更比较基线分支。 | `origin/main` | 用于 `change_scope` 判断部署范围 |
|
||
| `jj_policy` | `jj` 使用策略：`disabled` / `optional-internal` / `required-internal`。 | `optional-internal` | 仅作为内部执行与恢复层，不改变外部 Git/PR 流程 |
|
||
|
||
### 参数组合示例（按场景）
|
||
|
||
#### 场景 1：日常 bug 修复，端到端自动执行
|
||
|
||
```text
|
||
/gitea-issue-devops-agent \
|
||
repo_url=https://fun-md.com/Fun_MD/devops-skills \
|
||
api_key=<TOKEN> \
|
||
mode=automatic \
|
||
issue=48 \
|
||
plan_path=.tmp/devops-plans/devops-skills__issue-48.md \
|
||
test_entry="issue-branch-preview" \
|
||
main_env_url=https://main.qa.example.com \
|
||
preview_slots=preview-a,preview-b \
|
||
preview_url_template=https://{slot}.qa.example.com \
|
||
min_quality_score=70
|
||
```
|
||
|
||
适用：问题描述完整、团队希望最大化自动化吞吐。
|
||
|
||
#### 场景 2：生产敏感仓库，人工确认每一步
|
||
|
||
```text
|
||
$gitea-issue-devops-agent
|
||
repo_url: https://fun-md.com/Fun_MD/devops-skills
|
||
api_key: <TOKEN>
|
||
mode: manual
|
||
issue: 48
|
||
deploy_env: prod-like-staging
|
||
health_endpoint: /healthz
|
||
```
|
||
|
||
适用：高风险改动、强合规流程、需要逐步确认分支/提交/提测/关闭。
|
||
|
||
#### 场景 3：半自动协作，先评审后提测
|
||
|
||
```text
|
||
Use skill gitea-issue-devops-agent.
|
||
repo_url=https://fun-md.com/Fun_MD/devops-skills
|
||
api_key=<TOKEN>
|
||
mode=semi-automatic
|
||
issue=48
|
||
reviewers=alice,bob
|
||
test_entry=issue-branch-preview
|
||
shared_qa_url=https://qa.example.com
|
||
preview_slots=preview-a,preview-b,preview-c
|
||
```
|
||
|
||
适用：多人协作项目，需要评审人显式批准后再进入提测和环境分配。
|
||
|
||
#### 场景 4：仅文档改动或轻量改动，资源最省策略
|
||
|
||
```text
|
||
/gitea-issue-devops-agent repo_url=... api_key=... mode=automatic target_base=origin/main
|
||
```
|
||
|
||
配合 `change_scope.py` 可自动得到 `skip` 或 `client_only`，避免不必要的服务端重启和环境开销。
|
||
|
||
## 技能路径
|
||
|
||
- `skills/gitea-issue-devops-agent/SKILL.md`
|
||
|
||
## 核心脚本
|
||
|
||
- `skills/gitea-issue-devops-agent/scripts/issue_audit.py`
|
||
- `skills/gitea-issue-devops-agent/scripts/change_scope.py`
|
||
- `skills/gitea-issue-devops-agent/scripts/preview_slot_allocator.py`
|