devops-skills/README.md

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

curl -fsSL https://fun-md.com/Fun_MD/devops-skills/raw/branch/main/install/install.sh | bash

macOS

curl -fsSL https://fun-md.com/Fun_MD/devops-skills/raw/branch/main/install/install.sh | bash

Windows (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

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

python skills/gitea-issue-devops-agent/scripts/change_scope.py --repo-path . --base-ref origin/main --head-ref HEAD

preview_slot_allocator.py

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 处理任务”

示例：

/gitea-issue-devops-agent repo_url=https://fun-md.com/FunMD/document-collab mode=automatic

请使用 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

示例：

$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: "..."})）

示例：

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 修复，端到端自动执行

/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：生产敏感仓库，人工确认每一步

$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：半自动协作，先评审后提测

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：仅文档改动或轻量改动，资源最省策略

/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