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 -> Branch -> 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) 分支隔离提测

每个 issue 固定独立分支和预览槽位，主干保持稳定回归，避免提测互相覆盖。

### 2) 智能节省资源

按改动自动识别部署策略：`skip / client_only / server_only / full_stack / infra_only`。  
**服务端未变更就不重启服务端**。

### 3) 证据化闭环

提测沉淀 commit、测试链接、环境 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`）
- 可选：`reviewers`、`test_entry`、`deploy_env`、`health_endpoint`、`min_quality_score`

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

### 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` | 决定自动化程度和人工审批点 |

### 重要可选参数

| 参数 | 说明 | 典型值 | 使用场景 |
| --- | --- | --- | --- |
| `reviewers` | 指定评审人列表（逗号分隔）。 | `alice,bob` | `semi-automatic` 模式下提交后等待人工评审 |
| `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` 判断部署范围 |

### 参数组合示例（按场景）

#### 场景 1：日常 bug 修复，端到端自动执行

```text
/gitea-issue-devops-agent \
repo_url=https://fun-md.com/Fun_MD/devops-skills \
api_key=<TOKEN> \
mode=automatic \
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
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
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`