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

python -m engine.devops_agent.cli compile workflows/gitea-issue-delivery.md --output workflows/gitea-issue-delivery.lock.json

Validate

python -m engine.devops_agent.cli validate workflows/gitea-issue-delivery.md

Run

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

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

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

默认 jj 安装顺序：

• Linux / macOS：brew -> cargo-binstall -> cargo
• Windows：winget -> scoop -> cargo

安装控制项：

Bash

INSTALL_JJ=0
JJ_INSTALL_METHOD=auto|brew|binstall|cargo
JJ_CHANNEL=release|prerelease

PowerShell

$env:INSTALL_JJ='0'
$env:JJ_INSTALL_METHOD='auto' # 或 winget / scoop / cargo
$env:JJ_CHANNEL='release'     # 或 prerelease

验证命令：

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 验收测试读取以下环境变量：

GITEA_BASE_URL=https://fun-md.com
GITEA_REPO=Fun_MD/devops-skills
GITEA_TOKEN=<TOKEN>
GITEA_ISSUE_NUMBER=48

执行：

python -m pytest tests/acceptance/test_gitea_acceptance.py -q

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

示例：

/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
issue: 48

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

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

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

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

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

/gitea-issue-devops-agent repo_url=... api_key=... mode=automatic target_base=origin/main

配合 change_scope.py 可自动得到 skip 或 client_only，避免不必要的服务端重启和环境开销。

场景 5：多 Agent 并行，但上下文不脑裂

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