devops-skills/README.md

![JUST FOR FUN - Linus Torvalds](https://kwize.com/pics/Linus-Torvalds-quote-about-fun-1a9823.jpg)

# 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，再默认尝试安装 `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`

## 工具使用说明

### 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`

推荐默认值：

- `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`