460 lines
14 KiB
Markdown
460 lines
14 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、验证步骤；最终合并必须工程师人工确认。
|
||
|
||
## 新增运行时能力
|
||
|
||
仓库现在不再只有 skill 文档和辅助脚本，还新增了一个最小可执行控制平面：
|
||
|
||
- `workflows/*.md`
|
||
- agentic workflow spec 源文件
|
||
- `workflows/*.lock.json`
|
||
- 编译后的锁定执行产物
|
||
- `engine/devops_agent/*`
|
||
- spec loader、compiler、validator、runtime、policy、provider、evidence、CLI
|
||
|
||
当前已实装的真实 provider 是 `Gitea`，并保留了后续接 `GitHub` 的 provider 边界。
|
||
|
||
## 运行时命令
|
||
|
||
### Compile
|
||
|
||
```bash
|
||
python -m engine.devops_agent.cli compile workflows/gitea-issue-delivery.md --output workflows/gitea-issue-delivery.lock.json
|
||
```
|
||
|
||
### Validate
|
||
|
||
```bash
|
||
python -m engine.devops_agent.cli validate workflows/gitea-issue-delivery.md
|
||
```
|
||
|
||
### Run
|
||
|
||
```bash
|
||
python -m engine.devops_agent.cli run workflows/gitea-issue-delivery.md \
|
||
--event-payload tests/fixtures/gitea/comment_event.json \
|
||
--output-dir .tmp/runtime-run \
|
||
--base-url https://fun-md.com \
|
||
--token <TOKEN>
|
||
```
|
||
|
||
### Acceptance
|
||
|
||
```bash
|
||
python -m engine.devops_agent.cli acceptance workflows/gitea-issue-delivery.md \
|
||
--base-url https://fun-md.com \
|
||
--repo Fun_MD/devops-skills \
|
||
--token <TOKEN> \
|
||
--issue-number 48 \
|
||
--output-dir .tmp/acceptance/gitea
|
||
```
|
||
|
||
运行时输出：
|
||
|
||
- `run-artifact.json`
|
||
- 计划状态摘要
|
||
- evidence comment 回写结果
|
||
|
||
## Safe Outputs 与定位
|
||
|
||
这次整合没有把产品做成 GitHub Actions 克隆，而是把 `gh-aw` 最有价值的部分内化为你们自己的控制层：
|
||
|
||
- `workflow spec`
|
||
- `compile / validate`
|
||
- `safe outputs`
|
||
- `provider abstraction`
|
||
- `evidence artifacts`
|
||
|
||
对外仍然保持：
|
||
|
||
- `issue / git branch / PR / CI/CD / review apps`
|
||
|
||
对内则新增：
|
||
|
||
- 不允许未声明的写操作
|
||
- 不允许跳过 validation 直接执行
|
||
- 不允许没有 evidence 就宣称完成
|
||
|
||
## 一键安装
|
||
|
||
安装器现在会先安装 skill，再默认尝试安装 `jj`。
|
||
如果 `jj` 因本机环境、包管理器或网络原因安装失败，安装器不会失败，只会给出手动安装提示。
|
||
|
||
### 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`
|
||
|
||
默认 `jj` 安装顺序：
|
||
|
||
- Linux / macOS：`brew -> cargo-binstall -> cargo`
|
||
- Windows：`winget -> scoop -> cargo`
|
||
|
||
安装控制项：
|
||
|
||
### Bash
|
||
|
||
```bash
|
||
INSTALL_JJ=0
|
||
JJ_INSTALL_METHOD=auto|brew|binstall|cargo
|
||
JJ_CHANNEL=release|prerelease
|
||
```
|
||
|
||
### PowerShell
|
||
|
||
```powershell
|
||
$env:INSTALL_JJ='0'
|
||
$env:JJ_INSTALL_METHOD='auto' # 或 winget / scoop / cargo
|
||
$env:JJ_CHANNEL='release' # 或 prerelease
|
||
```
|
||
|
||
验证命令：
|
||
|
||
```bash
|
||
jj --version
|
||
jj config set --user user.name "Your Name"
|
||
jj config set --user user.email "you@example.com"
|
||
```
|
||
|
||
详细说明：
|
||
|
||
- `skills/gitea-issue-devops-agent/references/jj-default-usage.md`
|
||
|
||
## 运行时与工具使用说明
|
||
|
||
### workflow spec
|
||
|
||
- `workflows/gitea-issue-delivery.md`
|
||
- 当前样例 workflow spec
|
||
- `workflows/gitea-issue-delivery.lock.json`
|
||
- 编译后的锁定产物，建议与 spec 一起提交
|
||
|
||
### acceptance 环境变量
|
||
|
||
真实 Gitea 验收测试读取以下环境变量：
|
||
|
||
```bash
|
||
GITEA_BASE_URL=https://fun-md.com
|
||
GITEA_REPO=Fun_MD/devops-skills
|
||
GITEA_TOKEN=<TOKEN>
|
||
GITEA_ISSUE_NUMBER=48
|
||
```
|
||
|
||
执行：
|
||
|
||
```bash
|
||
python -m pytest tests/acceptance/test_gitea_acceptance.py -q
|
||
```
|
||
|
||
### 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`
|
||
- `workflows/gitea-issue-delivery.md`
|
||
- `workflows/gitea-issue-delivery.lock.json`
|
||
|
||
## 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`
|
||
|
||
推荐默认值：
|
||
|
||
- `jj_policy=optional-internal`
|
||
- 先固定 issue，再进入 `Plan -> Draft PR -> 提测 -> 人工确认合并`
|
||
|
||
### 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
|
||
```
|
||
|
||
## `jj` 在工作流中的定位
|
||
|
||
默认安装 `jj`，但不要求非工程角色理解 `jj`。
|
||
|
||
- 对外：继续使用 `issue / git branch / PR / CI/CD / review apps`
|
||
- 对内：用 `jj` 承担本地执行、回退、并行 workspace、变更重写
|
||
- 原则：`jj` 是内部可靠性增强层，不替代你们对外的 Git/Gitea 协作界面
|
||
|
||
## `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
|
||
```
|
||
|
||
适用：问题描述完整、团队希望最大化自动化吞吐。
|
||
|
||
典型流程：
|
||
|
||
1. 人工在 Gitea 选中 issue。
|
||
2. MajorAgent 生成 Plan 并创建分支、Draft PR。
|
||
3. SubAgent 只读取必要上下文并修改计划内路径。
|
||
4. TestAgent 跑单测、集成测试、issue 级 e2e。
|
||
5. 通过后进入 preview slot 和人工复核。
|
||
|
||
#### 场景 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
|
||
```
|
||
|
||
适用：高风险改动、强合规流程、需要逐步确认分支/提交/提测/关闭。
|
||
|
||
典型流程：
|
||
|
||
1. 先生成 Plan。
|
||
2. 每次代码改动前都确认允许范围。
|
||
3. 提测、回写 issue、关闭 issue、最终 merge 都要人工确认。
|
||
4. 如 AI 偏航，可用 `jj` 做本地回退而不破坏外部 PR。
|
||
|
||
#### 场景 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
|
||
```
|
||
|
||
适用：多人协作项目，需要评审人显式批准后再进入提测和环境分配。
|
||
|
||
典型流程：
|
||
|
||
1. AI 先产出初始 Draft PR。
|
||
2. 工程师在 AI 编码工具里继续白盒调整。
|
||
3. reviewer 回复 `review-approved` 后才进入提测。
|
||
4. maintainer 最后确认 merge。
|
||
|
||
#### 场景 4：仅文档改动或轻量改动，资源最省策略
|
||
|
||
```text
|
||
/gitea-issue-devops-agent repo_url=... api_key=... mode=automatic target_base=origin/main
|
||
```
|
||
|
||
配合 `change_scope.py` 可自动得到 `skip` 或 `client_only`，避免不必要的服务端重启和环境开销。
|
||
|
||
#### 场景 5：多 Agent 并行，但上下文不脑裂
|
||
|
||
```text
|
||
issue=48
|
||
mode=semi-automatic
|
||
jj_policy=optional-internal
|
||
plan_path=.tmp/devops-plans/devops-skills__issue-48.md
|
||
```
|
||
|
||
典型流程：
|
||
|
||
1. MajorAgent 只负责 issue 语义分析和 Plan。
|
||
2. SubAgent 只负责修改代码。
|
||
3. TestAgent 在独立 `jj workspace` 里验证。
|
||
4. 人工 reviewer 再决定是否继续迭代或合并。
|
||
|
||
适用：长流程、多角色协作、希望降低 token 消耗和上下文漂移。
|
||
|
||
## 技能路径
|
||
|
||
- `skills/gitea-issue-devops-agent/SKILL.md`
|
||
|
||
## 核心文档
|
||
|
||
- `skills/gitea-issue-devops-agent/references/issue-template-standard.md`
|
||
- `skills/gitea-issue-devops-agent/references/plan-template.md`
|
||
- `skills/gitea-issue-devops-agent/references/jj-default-usage.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`
|