diff --git a/README.md b/README.md index 5eeaa7c..c26a328 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,9 @@ -# DevOps Skills +![JUST FOR FUN - Linus Torvalds](https://kwize.com/pics/Linus-Torvalds-quote-about-fun-1a9823.jpg) -Issue-Driven DevOps 平台技能仓库，核心产品是 `gitea-issue-devops-agent`。 +# gitea-issue-devops-agent -它把交付流程固化为： - -`Issue -> Branch -> Preview Slot -> Test Loop -> Human-Confirmed Merge` +> **Issue-Driven DevOps 产品官网** +> 把 `Issue -> Branch -> Preview Slot -> Test Loop -> Human-Confirmed Merge` 变成标准交付引擎。 ## 公网产品页 @@ -13,21 +12,36 @@ Issue-Driven DevOps 平台技能仓库，核心产品是 `gitea-issue-devops-age - HTML 设计稿源码：`site/index.html` - SVG 官网文件：`site/index.svg` +## 核心价值 + +### 1) 分支隔离提测 + +每个 issue 固定独立分支和预览槽位，主干保持稳定回归，避免提测互相覆盖。 + +### 2) 智能节省资源 + +按改动自动识别部署策略：`skip / client_only / server_only / full_stack / infra_only`。 +**服务端未变更就不重启服务端**。 + +### 3) 证据化闭环 + +提测沉淀 commit、测试链接、环境 URL、验证步骤；最终合并必须工程师人工确认。 + ## 一键安装 -Linux: +### Linux ```bash curl -fsSL https://fun-md.com/Fun_MD/devops-skills/raw/branch/main/install/install.sh | bash ``` -macOS: +### macOS ```bash curl -fsSL https://fun-md.com/Fun_MD/devops-skills/raw/branch/main/install/install.sh | bash ``` -Windows (PowerShell): +### 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" @@ -37,25 +51,199 @@ powershell -NoProfile -ExecutionPolicy Bypass -Command "iwr -useb https://fun-md - `~/.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 \ + --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.md` +- 项目级：`.claude/skills//SKILL.md` + +唤起方式： + +- 显式调用：`/ [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: +mode: automatic +``` + +### OpenCode + +Skills 目录（Claude skill 兼容）： + +- 项目级：`.opencode/skills//SKILL.md` +- 全局级：`~/.config/opencode/skills//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= +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= \ +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: +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= +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` -## 核心能力 - -- 三种执行模式：`automatic` / `semi-automatic` / `manual` -- issue 图片证据抓取（含 attachments/assets 三路兜底） -- 按变更范围部署（`skip` / `client_only` / `server_only` / `full_stack` / `infra_only`） -- 预览槽位池分配与自动回收（TTL + 关闭释放） -- 最终代码合并必须人工确认 - ## 核心脚本 - `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` - -## .gitea/workflows 模板 - -- `.gitea/workflows/issue-branch-preview.yml` -- `.gitea/workflows/preview-slot-reclaim.yml`