Compare commits
6 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
| ccfdda4342 | |||
| acb77a821c | |||
| 2fcd4d093a | |||
| fcecce0595 | |||
| fbe92a4e7c | |||
| 4df29b70cd |
247
README.md
247
README.md
@@ -1,31 +1,51 @@
|
||||
# DevOps Skills
|
||||
|
||||
|
||||
Issue-Driven DevOps 平台技能仓库，核心产品是 `gitea-issue-devops-agent`。
|
||||
# gitea-issue-devops-agent
|
||||
|
||||
它把交付流程固化为：
|
||||
|
||||
`Issue -> Branch -> Preview Slot -> Test Loop -> Human-Confirmed Merge`
|
||||
> **Issue-Driven DevOps 产品官网**
|
||||
> 把 `Issue -> Plan -> Branch -> Draft PR -> Preview Slot -> Test Loop -> Human-Confirmed Merge` 变成标准交付引擎。
|
||||
|
||||
## 公网产品页
|
||||
|
||||
- 产品官网：`https://fun-md.com/Fun_MD/devops-skills/raw/branch/main/site/index.html`
|
||||
- 产品官网（独立前端渲染页，非 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、验证步骤；最终合并必须工程师人工确认。
|
||||
|
||||
## 一键安装
|
||||
|
||||
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"
|
||||
@@ -35,25 +55,208 @@ 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 <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`
|
||||
|
||||
### 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
|
||||
```
|
||||
|
||||
## `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
|
||||
```
|
||||
|
||||
适用：问题描述完整、团队希望最大化自动化吞吐。
|
||||
|
||||
#### 场景 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
|
||||
```
|
||||
|
||||
适用：高风险改动、强合规流程、需要逐步确认分支/提交/提测/关闭。
|
||||
|
||||
#### 场景 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
|
||||
```
|
||||
|
||||
适用：多人协作项目，需要评审人显式批准后再进入提测和环境分配。
|
||||
|
||||
#### 场景 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`
|
||||
|
||||
213
site/index.svg
Normal file
213
site/index.svg
Normal file
@@ -0,0 +1,213 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" width="1600" height="2500" viewBox="0 0 1600 2500">
|
||||
<defs>
|
||||
<linearGradient id="bgGrad" x1="0" y1="0" x2="1" y2="1">
|
||||
<stop offset="0%" stop-color="#070c19"/>
|
||||
<stop offset="55%" stop-color="#102347"/>
|
||||
<stop offset="100%" stop-color="#0a3a4f"/>
|
||||
</linearGradient>
|
||||
<linearGradient id="accentGrad" x1="0" y1="0" x2="1" y2="1">
|
||||
<stop offset="0%" stop-color="#29d8ff"/>
|
||||
<stop offset="100%" stop-color="#49f2c7"/>
|
||||
</linearGradient>
|
||||
<linearGradient id="cardGrad" x1="0" y1="0" x2="0" y2="1">
|
||||
<stop offset="0%" stop-color="#122445" stop-opacity="0.95"/>
|
||||
<stop offset="100%" stop-color="#0f1d38" stop-opacity="0.95"/>
|
||||
</linearGradient>
|
||||
<filter id="softGlow" x="-40%" y="-40%" width="180%" height="180%">
|
||||
<feGaussianBlur stdDeviation="18" result="blur"/>
|
||||
<feMerge>
|
||||
<feMergeNode in="blur"/>
|
||||
<feMergeNode in="SourceGraphic"/>
|
||||
</feMerge>
|
||||
</filter>
|
||||
<style>
|
||||
.title {
|
||||
font-family: "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif;
|
||||
fill: #ecf4ff;
|
||||
font-weight: 700;
|
||||
}
|
||||
.subtitle {
|
||||
font-family: "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif;
|
||||
fill: #b8c9e9;
|
||||
font-size: 30px;
|
||||
}
|
||||
.section-title {
|
||||
font-family: "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif;
|
||||
fill: #e7f1ff;
|
||||
font-size: 44px;
|
||||
font-weight: 700;
|
||||
}
|
||||
.card-title {
|
||||
font-family: "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif;
|
||||
fill: #def2ff;
|
||||
font-size: 32px;
|
||||
font-weight: 700;
|
||||
}
|
||||
.card-text {
|
||||
font-family: "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif;
|
||||
fill: #bad0ee;
|
||||
font-size: 24px;
|
||||
}
|
||||
.mono {
|
||||
font-family: "Cascadia Mono", Consolas, Menlo, monospace;
|
||||
fill: #d8f1ff;
|
||||
font-size: 21px;
|
||||
}
|
||||
.label {
|
||||
font-family: "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif;
|
||||
fill: #88a6d4;
|
||||
font-size: 20px;
|
||||
}
|
||||
.badge {
|
||||
font-family: "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif;
|
||||
fill: #0a2b3f;
|
||||
font-size: 21px;
|
||||
font-weight: 700;
|
||||
}
|
||||
.btn {
|
||||
font-family: "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif;
|
||||
fill: #06253a;
|
||||
font-size: 24px;
|
||||
font-weight: 700;
|
||||
}
|
||||
.btn-muted {
|
||||
font-family: "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif;
|
||||
fill: #d2e8ff;
|
||||
font-size: 22px;
|
||||
font-weight: 600;
|
||||
}
|
||||
</style>
|
||||
</defs>
|
||||
|
||||
<rect x="0" y="0" width="1600" height="2500" fill="url(#bgGrad)"/>
|
||||
<circle cx="1350" cy="240" r="260" fill="#29d8ff" opacity="0.13" filter="url(#softGlow)"/>
|
||||
<circle cx="180" cy="320" r="220" fill="#49f2c7" opacity="0.11" filter="url(#softGlow)"/>
|
||||
<circle cx="420" cy="2100" r="260" fill="#2fd8f0" opacity="0.10" filter="url(#softGlow)"/>
|
||||
|
||||
<rect x="70" y="70" width="1460" height="500" rx="32" fill="url(#cardGrad)" stroke="#345a90" stroke-width="2"/>
|
||||
<rect x="110" y="120" width="390" height="56" rx="28" fill="url(#accentGrad)"/>
|
||||
<text x="145" y="158" class="badge">Issue-Driven DevOps Platform</text>
|
||||
|
||||
<text x="110" y="255" class="title" font-size="74">gitea-issue-devops-agent</text>
|
||||
<text x="110" y="325" class="subtitle">把 Issue → Branch → Preview Slot → Test Loop → Human-Confirmed Merge 变成标准交付引擎</text>
|
||||
<text x="110" y="372" class="subtitle">不是临时脚本，而是可规模化的研发基础设施产品。</text>
|
||||
|
||||
<rect x="110" y="415" width="260" height="82" rx="14" fill="url(#accentGrad)"/>
|
||||
<text x="152" y="468" class="btn">访问仓库</text>
|
||||
<a href="https://fun-md.com/Fun_MD/devops-skills">
|
||||
<rect x="110" y="415" width="260" height="82" rx="14" fill="#ffffff" opacity="0.001"/>
|
||||
</a>
|
||||
|
||||
<rect x="390" y="415" width="330" height="82" rx="14" fill="#1b3157" stroke="#4068a5"/>
|
||||
<text x="445" y="468" class="btn-muted">SKILL 规范文档</text>
|
||||
<a href="https://fun-md.com/Fun_MD/devops-skills/raw/branch/main/skills/gitea-issue-devops-agent/SKILL.md">
|
||||
<rect x="390" y="415" width="330" height="82" rx="14" fill="#ffffff" opacity="0.001"/>
|
||||
</a>
|
||||
|
||||
<rect x="820" y="150" width="660" height="340" rx="22" fill="#0c1a34" stroke="#34598e"/>
|
||||
<text x="860" y="215" class="label">核心指标</text>
|
||||
<text x="860" y="285" class="title" font-size="58">3 Modes</text>
|
||||
<text x="860" y="325" class="label">automatic / semi-automatic / manual</text>
|
||||
<text x="1160" y="285" class="title" font-size="58">5 Scopes</text>
|
||||
<text x="1160" y="325" class="label">skip / client / server / full / infra</text>
|
||||
<text x="860" y="390" class="title" font-size="58">1 : 1 Binding</text>
|
||||
<text x="860" y="430" class="label">Issue - Branch - Preview Slot 精确绑定</text>
|
||||
<text x="1160" y="390" class="title" font-size="58">TTL Reclaim</text>
|
||||
<text x="1160" y="430" class="label">空闲槽位自动回收</text>
|
||||
|
||||
<text x="80" y="680" class="section-title">产品核心价值</text>
|
||||
<rect x="80" y="715" width="460" height="280" rx="20" fill="url(#cardGrad)" stroke="#35598f"/>
|
||||
<text x="110" y="785" class="card-title">1. 分支隔离提测</text>
|
||||
<text x="110" y="835" class="card-text">每个 issue 固定分支和预览环境，</text>
|
||||
<text x="110" y="872" class="card-text">主干环境稳定回归，提测互不覆盖。</text>
|
||||
<text x="110" y="909" class="card-text">团队并行效率显著提升。</text>
|
||||
|
||||
<rect x="570" y="715" width="460" height="280" rx="20" fill="url(#cardGrad)" stroke="#35598f"/>
|
||||
<text x="600" y="785" class="card-title">2. 资源智能节流</text>
|
||||
<text x="600" y="835" class="card-text">按改动自动识别部署范围，</text>
|
||||
<text x="600" y="872" class="card-text">前端-only 改动不重启服务端，</text>
|
||||
<text x="600" y="909" class="card-text">节省机器和运维成本。</text>
|
||||
|
||||
<rect x="1060" y="715" width="460" height="280" rx="20" fill="url(#cardGrad)" stroke="#35598f"/>
|
||||
<text x="1090" y="785" class="card-title">3. 证据化闭环</text>
|
||||
<text x="1090" y="835" class="card-text">提测结果、commit、环境链接、</text>
|
||||
<text x="1090" y="872" class="card-text">验证步骤统一沉淀，</text>
|
||||
<text x="1090" y="909" class="card-text">最终合并始终人工确认。</text>
|
||||
|
||||
<text x="80" y="1090" class="section-title">流程拓扑（Issue 到交付）</text>
|
||||
<rect x="80" y="1125" width="1440" height="220" rx="20" fill="url(#cardGrad)" stroke="#35598f"/>
|
||||
<rect x="112" y="1170" width="250" height="130" rx="14" fill="#13284b" stroke="#3d639b"/>
|
||||
<text x="138" y="1223" class="card-title" font-size="26">1. 引导连接</text>
|
||||
<text x="138" y="1263" class="card-text" font-size="20">repo_url + api_key + mode</text>
|
||||
<rect x="402" y="1170" width="250" height="130" rx="14" fill="#13284b" stroke="#3d639b"/>
|
||||
<text x="430" y="1223" class="card-title" font-size="26">2. 质量审计</text>
|
||||
<text x="430" y="1263" class="card-text" font-size="20">Issue + 图片附件 + 去重评分</text>
|
||||
<rect x="692" y="1170" width="250" height="130" rx="14" fill="#13284b" stroke="#3d639b"/>
|
||||
<text x="720" y="1223" class="card-title" font-size="26">3. 分支修复</text>
|
||||
<text x="720" y="1263" class="card-text" font-size="20">严格在 issue 分支迭代</text>
|
||||
<rect x="982" y="1170" width="250" height="130" rx="14" fill="#13284b" stroke="#3d639b"/>
|
||||
<text x="1007" y="1223" class="card-title" font-size="26">4. 按范围部署</text>
|
||||
<text x="1007" y="1263" class="card-text" font-size="20">skip/client/server/full/infra</text>
|
||||
<rect x="1272" y="1170" width="216" height="130" rx="14" fill="#13284b" stroke="#3d639b"/>
|
||||
<text x="1300" y="1223" class="card-title" font-size="26">5. 自动回收</text>
|
||||
<text x="1300" y="1263" class="card-text" font-size="20">TTL + Close Release</text>
|
||||
|
||||
<line x1="362" y1="1235" x2="402" y2="1235" stroke="#58d8ff" stroke-width="4"/>
|
||||
<line x1="652" y1="1235" x2="692" y2="1235" stroke="#58d8ff" stroke-width="4"/>
|
||||
<line x1="942" y1="1235" x2="982" y2="1235" stroke="#58d8ff" stroke-width="4"/>
|
||||
<line x1="1232" y1="1235" x2="1272" y2="1235" stroke="#58d8ff" stroke-width="4"/>
|
||||
|
||||
<text x="80" y="1440" class="section-title">一键安装命令（Windows / macOS / Linux）</text>
|
||||
|
||||
<rect x="80" y="1480" width="470" height="300" rx="18" fill="url(#cardGrad)" stroke="#35598f"/>
|
||||
<text x="110" y="1542" class="card-title">Linux</text>
|
||||
<rect x="110" y="1568" width="410" height="178" rx="12" fill="#091327" stroke="#406aa6"/>
|
||||
<text x="130" y="1620" class="mono">curl -fsSL https://fun-md.com/Fun_MD/</text>
|
||||
<text x="130" y="1656" class="mono">devops-skills/raw/branch/main/install/</text>
|
||||
<text x="130" y="1692" class="mono">install.sh | bash</text>
|
||||
|
||||
<rect x="565" y="1480" width="470" height="300" rx="18" fill="url(#cardGrad)" stroke="#35598f"/>
|
||||
<text x="595" y="1542" class="card-title">macOS</text>
|
||||
<rect x="595" y="1568" width="410" height="178" rx="12" fill="#091327" stroke="#406aa6"/>
|
||||
<text x="615" y="1620" class="mono">curl -fsSL https://fun-md.com/Fun_MD/</text>
|
||||
<text x="615" y="1656" class="mono">devops-skills/raw/branch/main/install/</text>
|
||||
<text x="615" y="1692" class="mono">install.sh | bash</text>
|
||||
|
||||
<rect x="1050" y="1480" width="470" height="300" rx="18" fill="url(#cardGrad)" stroke="#35598f"/>
|
||||
<text x="1080" y="1542" class="card-title">Windows PowerShell</text>
|
||||
<rect x="1080" y="1568" width="410" height="178" rx="12" fill="#091327" stroke="#406aa6"/>
|
||||
<text x="1100" y="1610" class="mono">powershell -NoProfile -ExecutionPolicy</text>
|
||||
<text x="1100" y="1646" class="mono">Bypass -Command "iwr -useb https://</text>
|
||||
<text x="1100" y="1682" class="mono">fun-md.com/Fun_MD/devops-skills/raw/</text>
|
||||
<text x="1100" y="1718" class="mono">branch/main/install/install.ps1 | iex"</text>
|
||||
|
||||
<text x="80" y="1878" class="section-title">核心工具</text>
|
||||
<rect x="80" y="1915" width="470" height="360" rx="18" fill="url(#cardGrad)" stroke="#35598f"/>
|
||||
<text x="110" y="1976" class="card-title">issue_audit.py</text>
|
||||
<text x="110" y="2014" class="card-text">拉取 issue / 评论 / 图片附件，去重并评分。</text>
|
||||
<rect x="110" y="2042" width="410" height="205" rx="12" fill="#091327" stroke="#406aa6"/>
|
||||
<text x="130" y="2091" class="mono">python .../issue_audit.py --base-url</text>
|
||||
<text x="130" y="2127" class="mono">https://fun-md.com --repo FunMD/</text>
|
||||
<text x="130" y="2163" class="mono">document-collab --token <TOKEN></text>
|
||||
<text x="130" y="2199" class="mono">--download-attachments</text>
|
||||
|
||||
<rect x="565" y="1915" width="470" height="360" rx="18" fill="url(#cardGrad)" stroke="#35598f"/>
|
||||
<text x="595" y="1976" class="card-title">change_scope.py</text>
|
||||
<text x="595" y="2014" class="card-text">识别部署范围，决定是否重启服务端。</text>
|
||||
<rect x="595" y="2042" width="410" height="205" rx="12" fill="#091327" stroke="#406aa6"/>
|
||||
<text x="615" y="2091" class="mono">python .../change_scope.py</text>
|
||||
<text x="615" y="2127" class="mono">--repo-path . --base-ref origin/main</text>
|
||||
<text x="615" y="2163" class="mono">--head-ref HEAD</text>
|
||||
|
||||
<rect x="1050" y="1915" width="470" height="360" rx="18" fill="url(#cardGrad)" stroke="#35598f"/>
|
||||
<text x="1080" y="1976" class="card-title">preview_slot_allocator.py</text>
|
||||
<text x="1080" y="2014" class="card-text">分配 / 复用 / 释放预览槽位。</text>
|
||||
<rect x="1080" y="2042" width="410" height="205" rx="12" fill="#091327" stroke="#406aa6"/>
|
||||
<text x="1100" y="2091" class="mono">python .../preview_slot_allocator.py</text>
|
||||
<text x="1100" y="2127" class="mono">--state-file .tmp/preview-slots.json</text>
|
||||
<text x="1100" y="2163" class="mono">--slots preview-a,preview-b --evict-oldest</text>
|
||||
|
||||
<rect x="80" y="2330" width="1440" height="110" rx="18" fill="#0b1730" stroke="#395d96"/>
|
||||
<text x="120" y="2383" class="label">官网入口: https://fun-md.com/Fun_MD/devops-skills/raw/branch/main/site/index.svg</text>
|
||||
<text x="120" y="2418" class="label">仓库地址: https://fun-md.com/Fun_MD/devops-skills</text>
|
||||
</svg>
|
||||
|
After Width: | Height: | Size: 12 KiB |
@@ -1,10 +1,25 @@
|
||||
---
|
||||
name: gitea-issue-devops-agent
|
||||
description: End-to-end Gitea issue delivery workflow with guided onboarding, branch-scoped preview environments, and resource-aware deployment decisions. Use when tasks involve connecting to Gitea, processing text/image issues, fixing code on issue-specified branches, allocating/reusing test environments per branch, running test submission loops, coordinating review approvals, and closing issues only after verified delivery and engineer-confirmed merge.
|
||||
description: Use when coordinating AI-assisted Gitea issue delivery where work must stay traceable across issue selection, branch or PR flow, CI/CD, preview environments, and human merge approval.
|
||||
---
|
||||
|
||||
# Gitea Issue DevOps Agent
|
||||
|
||||
## Overview
|
||||
|
||||
Treat AI as a fast but unstable engineer. The public workflow must remain `issue -> branch -> PR -> CI/CD -> human-confirmed merge`, while the internal execution model must narrow context, persist plans, require verification evidence, and keep humans in control of final merge decisions.
|
||||
|
||||
This skill is platform-aware for Gitea, but its delivery contract must stay portable across basic DevOps primitives: `git`, `issue`, `PR`, and `CI/CD`.
|
||||
|
||||
## Core Principles
|
||||
|
||||
- Start coding only from a selected issue, not from an unbounded issue queue, unless the user explicitly asks for triage-only queue scanning.
|
||||
- Every delivery issue must have a persisted plan before any code changes.
|
||||
- External collaboration stays Git-native: issue, branch, PR, pipeline, review app, merge.
|
||||
- AI output is provisional until tests, smoke paths, and review evidence exist.
|
||||
- Engineers stay in the loop from the initial PR onward and own white-box review.
|
||||
- Keep one active issue per branch and per execution agent unless the user explicitly approves batching.
|
||||
|
||||
## Mandatory Guided Start
|
||||
|
||||
Run this interaction before any coding or issue action:
|
||||
@@ -17,7 +32,16 @@ Run this interaction before any coding or issue action:
|
||||
- `automatic`
|
||||
- `semi-automatic`
|
||||
- `manual` (non-automatic)
|
||||
4. Ask optional defaults:
|
||||
4. Ask for the selected issue trigger source:
|
||||
- explicit issue number
|
||||
- issue comment / webhook trigger
|
||||
- app/CLI selection
|
||||
- triage-only queue scan without coding
|
||||
5. Ask optional defaults:
|
||||
- target base branch (for example `main`, `develop`, protected release branch)
|
||||
- branch naming convention for issue branches
|
||||
- plan storage path (default `.tmp/devops-plans/<repo>__issue-<number>.md`)
|
||||
- issue template policy (`required` or `recommended`) for `bug`, `enhancement`, and `feature`
|
||||
- designated reviewers (for semi-automatic mode)
|
||||
- branch test submission entrypoint (CI command/job)
|
||||
- environment policy:
|
||||
@@ -25,21 +49,102 @@ Run this interaction before any coding or issue action:
|
||||
- optional shared QA URL
|
||||
- preview slot pool (for issue branches), e.g. `preview-a,preview-b`
|
||||
- preview URL template, e.g. `https://{slot}.qa.example.com`
|
||||
- public routing mode: `port-based` or `virtual-host`
|
||||
- websocket public entry: explicit WS URL (`wss://...`) or same-origin path (`/ws`)
|
||||
- deployment environment + health endpoint
|
||||
- minimum issue quality score (default `70`)
|
||||
5. Validate connectivity by running:
|
||||
- `jj` policy:
|
||||
- `disabled`
|
||||
- `optional-internal`
|
||||
- `required-internal`
|
||||
6. Validate connectivity by running:
|
||||
- `python scripts/issue_audit.py --repo <owner/repo> --base-url <gitea_url> --token <token> --state all --download-attachments --output-dir .tmp/issue-audit`
|
||||
6. Initialize preview-slot state (if branch previews enabled):
|
||||
7. Initialize preview-slot state (if branch previews enabled):
|
||||
- `python scripts/preview_slot_allocator.py --state-file .tmp/preview-slots.json --slots <slot_csv> --list`
|
||||
7. Echo back the selected mode and all gate rules, then start work.
|
||||
8. Echo back the selected mode, selected issue trigger, target base branch, plan path, `jj` policy, and all gate rules, then start work.
|
||||
|
||||
If repository or token is missing/invalid, stop and request correction. Never start development without a successful connectivity check.
|
||||
|
||||
## Issue Intake Contract (Required)
|
||||
|
||||
- Require issue templates for `bug`, `enhancement`, and `feature`. See `references/issue-template-standard.md`.
|
||||
- A coding run must start from one fixed issue chosen by a human or an explicit trigger. Queue polling is for triage only unless the user explicitly enables unattended processing.
|
||||
- If the selected issue is too broad for one reviewable PR, split it into sub-issues before coding.
|
||||
- If issue quality is below threshold, request details and stop before branch creation.
|
||||
- For image/UI issues, attachment intake is mandatory before implementation.
|
||||
|
||||
## Plan-First Orchestration (Required)
|
||||
|
||||
Before any code change, the MajorAgent must create and persist a plan for the selected issue. Use `references/plan-template.md`.
|
||||
|
||||
Minimum plan fields:
|
||||
|
||||
- issue number and title
|
||||
- trigger source and current issue status
|
||||
- target base branch and working branch
|
||||
- current problem description
|
||||
- expected behavior and acceptance criteria
|
||||
- related interfaces, services, and directories
|
||||
- allowed file/path scope for edits
|
||||
- verification steps, including issue-level e2e coverage
|
||||
- assigned execution agent
|
||||
- risk notes and blockers
|
||||
- evidence links or placeholders for commit, PR, pipeline, and preview URL
|
||||
|
||||
Required status flow:
|
||||
|
||||
- `selected`
|
||||
- `planned`
|
||||
- `in_progress`
|
||||
- `pending_test`
|
||||
- `pending_review`
|
||||
- `merged`
|
||||
- `closed`
|
||||
- `needs_info`
|
||||
- `blocked`
|
||||
- `rejected`
|
||||
|
||||
Hard rules:
|
||||
|
||||
- No code changes before the plan exists.
|
||||
- No status promotion without evidence.
|
||||
- If scope changes materially, update the plan before continuing.
|
||||
|
||||
## Agent Role Separation (Required)
|
||||
|
||||
### MajorAgent
|
||||
|
||||
- Pull issues, comments, and attachments from Gitea.
|
||||
- Perform semantic triage and create the plan.
|
||||
- Select or create the issue branch and initialize the PR.
|
||||
- Decide whether work can proceed automatically or must pause for human input.
|
||||
|
||||
### SubAgent (Developer)
|
||||
|
||||
- Load only the plan and the minimal code context needed for the issue.
|
||||
- Modify code only within the allowed path scope unless explicit approval expands scope.
|
||||
- Keep patches small and reversible.
|
||||
- Update the plan to `pending_test` with a concise implementation summary.
|
||||
|
||||
### TestAgent
|
||||
|
||||
- Load the plan, diff, and verification steps.
|
||||
- Validate build, targeted tests, issue-level e2e path, and smoke path.
|
||||
- Update the plan to `pending_review` only when evidence is complete.
|
||||
- Reopen the plan to `in_progress` if failures or regressions appear.
|
||||
|
||||
### Human Reviewer / Maintainer
|
||||
|
||||
- Review the draft PR and the plan evidence.
|
||||
- Use the AI coding tool for follow-up adjustments if needed.
|
||||
- Approve or reject final merge.
|
||||
|
||||
## Mode Definitions
|
||||
|
||||
### 1) Automatic Mode
|
||||
|
||||
- Read issue-specified branch and work on that branch.
|
||||
- Start only after a fixed issue has been selected and a plan has been created.
|
||||
- Read or create the issue branch and open/update the draft PR automatically.
|
||||
- Implement fix, run checks, push branch, allocate/reuse branch preview env, and trigger branch test submission automatically.
|
||||
- Monitor test results and issue feedback, then iterate on the same branch until pass.
|
||||
- Close issue only after evidence is complete.
|
||||
@@ -47,7 +152,8 @@ If repository or token is missing/invalid, stop and request correction. Never st
|
||||
|
||||
### 2) Semi-Automatic Mode
|
||||
|
||||
- Read issue-specified branch and work on that branch.
|
||||
- Start only after a fixed issue has been selected and a plan has been created.
|
||||
- Read or create the issue branch and open/update the draft PR.
|
||||
- Implement and push fix.
|
||||
- Notify designated reviewer with change summary, risk, and test plan.
|
||||
- Wait for explicit human review approval.
|
||||
@@ -60,7 +166,9 @@ If repository or token is missing/invalid, stop and request correction. Never st
|
||||
Require explicit human confirmation before each major action:
|
||||
|
||||
- selecting issue
|
||||
- finalizing the plan
|
||||
- confirming target branch
|
||||
- creating or updating the PR
|
||||
- applying code changes
|
||||
- pushing commits
|
||||
- triggering tests/deploy
|
||||
@@ -71,11 +179,15 @@ No autonomous transition is allowed in manual mode.
|
||||
|
||||
## Branch-First Rules
|
||||
|
||||
- Treat issue-declared branch as the source of truth.
|
||||
- Treat issue-declared branch as the source of truth when provided.
|
||||
- If the issue does not declare a branch, create one from the configured protected base branch after the plan is approved.
|
||||
- Preferred naming pattern: `<type>/issue-<number>-<slug>` or `issue/<number>-<slug>`.
|
||||
- Accept branch hints from issue fields/body/comments (example: `branch: feat/login-fix`).
|
||||
- If branch is missing or ambiguous, ask user/reporter and pause that issue.
|
||||
- Do not silently switch branches.
|
||||
- Keep one active issue per branch unless user explicitly approves batching.
|
||||
- Open or update a draft PR immediately after branch selection so the review surface exists from the start.
|
||||
- Keep issue, branch, PR, preview env, and plan bound together for the full lifecycle.
|
||||
|
||||
## Environment Model (Required)
|
||||
|
||||
@@ -93,6 +205,14 @@ Always avoid `main` and issue branches overwriting each other.
|
||||
|
||||
Never deploy different branches to the same fixed URL unless user explicitly approves override.
|
||||
|
||||
### Routing Strategy (Recommended)
|
||||
|
||||
- Prefer `virtual-host` over raw ports for multi-branch testing:
|
||||
- `main.example.com`, `preview-a.example.com`, `preview-b.example.com`
|
||||
- Keep internal process ports private; expose only 80/443.
|
||||
- Use same-origin WS path for frontend (`VITE_WS_URL=/ws`) and route `/ws/*` to the slot server.
|
||||
- If `port-based` is used, every active env must have unique client/server ports; never reuse one public URL for two branches.
|
||||
|
||||
## Issue -> Branch -> Environment Binding
|
||||
|
||||
- Binding key: `<repo>#<issue>#<branch>`
|
||||
@@ -132,9 +252,14 @@ Hard rule:
|
||||
|
||||
## Standard Workflow (All Modes)
|
||||
|
||||
### 1) Intake and Prioritization
|
||||
### 1) Issue Selection and Trigger
|
||||
|
||||
- Pull issues, comments, and attachments from Gitea API.
|
||||
- Start from a fixed issue chosen through comment mention, webhook, app/CLI selection, or explicit human instruction.
|
||||
- Repo-wide polling may be used for triage reports, but not for autonomous coding unless the user explicitly enables queue processing.
|
||||
|
||||
### 2) Intake and Prioritization
|
||||
|
||||
- Pull the selected issue, comments, and attachments from Gitea API.
|
||||
- If issue text/comments indicate image evidence but `attachments_downloaded` is `0`, stop and report image-intake failure before coding.
|
||||
- Prioritize in this order:
|
||||
- `closed_but_unresolved`
|
||||
@@ -143,65 +268,93 @@ Hard rule:
|
||||
- `closed_open_reopen_candidates`
|
||||
- For issues with images, inspect attachments before coding.
|
||||
|
||||
### 2) Deduplication and Quality Gate
|
||||
### 3) Deduplication and Quality Gate
|
||||
|
||||
- Group issues by semantic intent, not literal wording.
|
||||
- Keep one parent issue for implementation.
|
||||
- Use `references/triage-standard.md` for score and comment templates.
|
||||
- For low-quality issues, request details and mark as `needs-info`.
|
||||
|
||||
### 3) Fix Execution
|
||||
### 4) Plan Generation
|
||||
|
||||
- MajorAgent must generate a plan before branch creation or code changes.
|
||||
- Persist the plan to the configured plan path and echo the summary back to the user.
|
||||
- Record the allowed file/path scope so later diffs can be checked against it.
|
||||
- Record the issue-level e2e scenario from the reporter's perspective.
|
||||
|
||||
### 5) Branch and PR Initialization
|
||||
|
||||
- Create or reuse the issue branch from the configured base branch.
|
||||
- Create or update the associated draft PR targeting the protected integration branch.
|
||||
- The PR body must include issue link, plan summary, intended file scope, and verification checklist.
|
||||
|
||||
### 6) Fix Execution
|
||||
|
||||
- Prefer small, reversible patches.
|
||||
- Link every code change to issue ID in commit or PR/MR notes.
|
||||
- Split cross-cutting work into incremental commits.
|
||||
- Do not modify files outside the allowed plan scope without explicit approval and a plan update.
|
||||
- Any new dependency, framework, SDK, or major library change must be checked against official docs, maintenance status, and local compatibility before merge.
|
||||
- Do not trust knowledge-base output as truth unless it has clear provenance and matches the current codebase.
|
||||
|
||||
### 4) Verification Gate
|
||||
### 7) Verification Gate
|
||||
|
||||
- Required:
|
||||
- build/compile passes
|
||||
- affected unit/integration tests pass
|
||||
- issue-level e2e test is added or updated and passes in the PR pipeline unless the user explicitly waives it
|
||||
- smoke path for reported scenario passes
|
||||
- For UI/image issues:
|
||||
- compare before/after screenshots
|
||||
- verify in at least one Chromium browser
|
||||
- If verification evidence is missing, do not claim the issue is fixed.
|
||||
|
||||
### 5) Branch Test Submission ("提测")
|
||||
### 8) Branch Test Submission ("提测")
|
||||
|
||||
- Submit testing on the issue branch (CI pipeline + branch preview env).
|
||||
- Allocate/reuse branch slot before submission.
|
||||
- Apply resource-aware deployment decision from change scope.
|
||||
- Verify websocket handshake is healthy on the published preview URL/path before asking QA to test.
|
||||
- Post evidence in issue comment:
|
||||
- commit SHA
|
||||
- PR URL
|
||||
- test run URL and result
|
||||
- environment/slot/URL
|
||||
- deployment scope (`skip`/`client_only`/`server_only`/`full_stack`/`infra_only`)
|
||||
- shared backend reused or dedicated backend started
|
||||
- e2e result
|
||||
- verification steps
|
||||
- If fail/reject, iterate on same branch and re-submit.
|
||||
|
||||
### 6) Loop Control
|
||||
### 9) Loop Control
|
||||
|
||||
- Continue `fix -> test submission -> feedback -> fix` until done.
|
||||
- Reopen immediately if verification fails or regression appears.
|
||||
- Do not close based on title-only or assumption-only validation.
|
||||
|
||||
### 7) Closure Rule
|
||||
### 10) Human Review and AI-Assisted Refinement
|
||||
|
||||
- From the initial PR onward, engineering review is the default path.
|
||||
- Engineers may continue refinement inside an AI coding tool, but all follow-up work must stay on the same issue branch and update the same plan.
|
||||
- Human review is the white-box gate between initial AI output and final merge readiness.
|
||||
|
||||
### 11) Closure Rule
|
||||
|
||||
Close issue only when all are true:
|
||||
|
||||
- root cause identified
|
||||
- fix verified with reproducible evidence
|
||||
- test submission passed
|
||||
- PR review state is recorded
|
||||
- closure comment includes commit/test/deploy evidence
|
||||
|
||||
### 8) Merge Rule (Always Human-Confirmed)
|
||||
### 12) Merge Rule (Always Human-Confirmed)
|
||||
|
||||
- Final merge must be approved by an engineer in all modes.
|
||||
- Agent can prepare merge notes/checklist, but must wait for explicit merge confirmation.
|
||||
- Merge only after confirmation, then post final release evidence.
|
||||
|
||||
### 9) Environment Cleanup
|
||||
### 13) Environment Cleanup
|
||||
|
||||
- On issue close/merge:
|
||||
- release preview slot
|
||||
@@ -210,6 +363,42 @@ Close issue only when all are true:
|
||||
- On TTL expiry:
|
||||
- reclaim idle slot automatically (automatic mode) or after confirmation (semi/manual)
|
||||
|
||||
## AI Reliability Guardrails
|
||||
|
||||
- Evidence before assertions: never claim “fixed”, “tested”, or “deployed” without command output, screenshots, or links proving it.
|
||||
- Diff-scope gate: compare the actual diff with the plan's allowed paths before PR update or merge request.
|
||||
- Dependency gate: do not add new packages or major version upgrades without checking official documentation, maintenance state, and environment compatibility.
|
||||
- Deprecated-tech gate: do not introduce deprecated or no-longer-recommended libraries/classes unless the user explicitly approves the trade-off.
|
||||
- Context minimization: every execution agent should load the issue, plan, diff, and only the code areas it needs.
|
||||
- No silent batching: do not mix unrelated fixes into one issue branch or PR.
|
||||
|
||||
## Knowledge Context Policy
|
||||
|
||||
- Do not blindly vectorize or load the entire repository as context for each issue.
|
||||
- Build a curated issue context pack consisting of:
|
||||
- issue body and comments
|
||||
- plan summary
|
||||
- touched directories and interfaces
|
||||
- related tests
|
||||
- relevant configuration and prior PR/commit references
|
||||
- Record the chosen context sources in the plan so later agents can reuse them.
|
||||
- Treat knowledge-base retrieval as a hint layer, not as a source of truth.
|
||||
|
||||
## Jujutsu (`jj`) Integration Strategy (Optional but Recommended Internally)
|
||||
|
||||
`jj` should improve internal execution reliability, not replace the external Git workflow.
|
||||
|
||||
Use `jj` only under these rules:
|
||||
|
||||
- Keep Git branches, PRs, and CI/CD as the public system of record.
|
||||
- Map the issue branch to a `jj` bookmark when `jj` is enabled.
|
||||
- Use `jj` change IDs to support iterative rewrites without losing traceability.
|
||||
- Use `jj` workspaces for parallel SubAgent/TestAgent/human adjustments on the same issue without sharing one mutable working copy.
|
||||
- Use the `jj` operation log for undo, recovery, and audit when AI changes diverge or go out of scope.
|
||||
- Prefer `jj` for local mutating history operations if enabled; avoid mixing arbitrary mutating `git` commands with `jj` in the same workspace.
|
||||
- If colocated workspaces are used, keep `git` mostly read-only except for explicit remote operations such as fetch/push handled by the workflow.
|
||||
- Do not require `jj` in CI or for non-engineer participants. `jj` is an internal accelerator, not the product front door.
|
||||
|
||||
## Script Usage
|
||||
|
||||
- `scripts/issue_audit.py`: collect issues/comments/attachments, detect duplicates, score quality, detect unresolved/closed-open links, extract issue branch hints, and generate reports.
|
||||
@@ -223,12 +412,21 @@ Close issue only when all are true:
|
||||
- `scripts/change_scope.py`: detect changed scope and recommend minimum deploy strategy.
|
||||
- `python scripts/change_scope.py --repo-path <repo> --base-ref origin/main --head-ref HEAD`
|
||||
- `references/triage-standard.md`: scoring rubric and templates for needs-info, review request, test submission, and merge approval.
|
||||
- `references/issue-template-standard.md`: standard issue templates for `bug`, `enhancement`, and `feature`.
|
||||
- `references/plan-template.md`: default plan structure and status machine for MajorAgent/SubAgent/TestAgent handoff.
|
||||
|
||||
## Operational Constraints
|
||||
|
||||
- Never start coding from an unselected issue unless the user explicitly enables autonomous queue mode.
|
||||
- Never skip plan creation for a delivery issue.
|
||||
- Never modify files outside the planned scope without an explicit plan update or user approval.
|
||||
- Never claim success without verification evidence.
|
||||
- Never introduce new dependencies or deprecated libraries without compatibility review.
|
||||
- Never bulk-close issues without per-issue verification evidence.
|
||||
- Never ignore attachment images for UI/interaction issues.
|
||||
- Never merge feature requests and bugfixes into one untraceable commit.
|
||||
- Never bypass engineer merge confirmation.
|
||||
- Never allow branch previews to overwrite main stable env.
|
||||
- Never start dedicated branch server when scope indicates client-only changes.
|
||||
- When changing public service ports under PM2, do not rely on `pm2 restart --update-env` alone; delete and recreate the process so CLI args (for example `--port`) actually change.
|
||||
- If a branch must be rebound to a specific preview slot (for example `preview-a`), release the existing issue allocation first, then redeploy; reuse logic otherwise keeps the previous slot by design.
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
interface:
|
||||
display_name: "Gitea Issue DevOps Agent"
|
||||
short_description: "Guided Gitea issue delivery with execution modes, branch preview slots, and resource-aware deployments"
|
||||
default_prompt: "Start with guided setup (repo URL, API key, mode, env policy), process issues on issue-specified branches, bind each branch to preview slots, decide deploy scope from git diff (skip/client-only/server-only/full-stack), avoid dedicated server restarts when backend is unchanged, run fix/test loops, and require engineer confirmation before final merge."
|
||||
short_description: "Plan-first Gitea issue delivery with fixed-issue triggers, draft PRs, preview slots, evidence gates, and optional jj-backed execution"
|
||||
default_prompt: "Start with guided setup (repo URL, API key, mode, selected issue trigger, target base branch, plan path, env policy, jj policy). Require a persisted plan before code changes, create or reuse the issue branch and draft PR, restrict edits to plan-scoped paths, decide deploy scope from git diff (skip/client-only/server-only/full-stack), add or update issue-level e2e coverage, bind preview slots, avoid dedicated server restarts when backend is unchanged, keep engineers in the loop from the initial PR onward, and require evidence plus explicit engineer confirmation before final merge."
|
||||
|
||||
@@ -0,0 +1,143 @@
|
||||
# Issue Template Standard
|
||||
|
||||
Use these templates to create AI-ready issues. The goal is to give both humans and agents enough context to produce a reviewable first PR instead of an ambiguous code dump.
|
||||
|
||||
## Global Rules
|
||||
|
||||
- Every issue should map to one reviewable outcome.
|
||||
- Prefer explicit issue selection to start delivery:
|
||||
- issue comment mention or webhook trigger
|
||||
- app/UI selection
|
||||
- CLI selection
|
||||
- Queue scans may suggest issues, but should not start coding until one issue is explicitly selected.
|
||||
- Always include acceptance criteria and affected area hints.
|
||||
- If screenshots, recordings, or logs exist, attach them in the issue instead of describing them vaguely.
|
||||
|
||||
## Common Required Fields
|
||||
|
||||
- summary
|
||||
- issue type: `bug`, `enhancement`, or `feature`
|
||||
- current behavior
|
||||
- expected behavior
|
||||
- affected user or business impact
|
||||
- related pages/modules/interfaces
|
||||
- acceptance criteria
|
||||
- attachments or logs
|
||||
|
||||
## Bug Template
|
||||
|
||||
```text
|
||||
[bug-template-v1]
|
||||
Summary:
|
||||
|
||||
Environment:
|
||||
- app version:
|
||||
- browser/device/os:
|
||||
- time window:
|
||||
|
||||
Current behavior:
|
||||
|
||||
Expected behavior:
|
||||
|
||||
Reproduction steps:
|
||||
1.
|
||||
2.
|
||||
3.
|
||||
|
||||
Affected area:
|
||||
- pages/routes:
|
||||
- services/apis:
|
||||
- files or modules if known:
|
||||
|
||||
Impact:
|
||||
|
||||
Evidence:
|
||||
- screenshot/video/log links:
|
||||
|
||||
Acceptance criteria:
|
||||
- [ ]
|
||||
- [ ]
|
||||
|
||||
Non-goals:
|
||||
```
|
||||
|
||||
## Enhancement Template
|
||||
|
||||
```text
|
||||
[enhancement-template-v1]
|
||||
Summary:
|
||||
|
||||
Background:
|
||||
|
||||
Current limitation:
|
||||
|
||||
Desired improvement:
|
||||
|
||||
Affected area:
|
||||
- pages/routes:
|
||||
- services/apis:
|
||||
- files or modules if known:
|
||||
|
||||
User value:
|
||||
|
||||
Constraints:
|
||||
- compatibility:
|
||||
- performance:
|
||||
- rollout/risk:
|
||||
|
||||
Acceptance criteria:
|
||||
- [ ]
|
||||
- [ ]
|
||||
|
||||
Evidence or references:
|
||||
```
|
||||
|
||||
## Feature Template
|
||||
|
||||
```text
|
||||
[feature-template-v1]
|
||||
Summary:
|
||||
|
||||
Business goal:
|
||||
|
||||
User story:
|
||||
As a <role>, I want <capability>, so that <outcome>.
|
||||
|
||||
Scope:
|
||||
- in scope:
|
||||
- out of scope:
|
||||
|
||||
Expected behavior:
|
||||
|
||||
Affected area:
|
||||
- pages/routes:
|
||||
- services/apis:
|
||||
- files or modules if known:
|
||||
|
||||
Dependencies or prerequisites:
|
||||
|
||||
Acceptance criteria:
|
||||
- [ ]
|
||||
- [ ]
|
||||
- [ ]
|
||||
|
||||
Validation path:
|
||||
- happy path:
|
||||
- edge cases:
|
||||
|
||||
Evidence, mockups, or references:
|
||||
```
|
||||
|
||||
## Selection Trigger Examples
|
||||
|
||||
```text
|
||||
@funmd-bot take issue #123
|
||||
```
|
||||
|
||||
```text
|
||||
CLI: devops-agent run --issue 123 --mode semi-automatic
|
||||
```
|
||||
|
||||
```text
|
||||
UI: Select issue #123 -> Generate plan -> Create branch and draft PR
|
||||
```
|
||||
98
skills/gitea-issue-devops-agent/references/plan-template.md
Normal file
98
skills/gitea-issue-devops-agent/references/plan-template.md
Normal file
@@ -0,0 +1,98 @@
|
||||
# Plan Template
|
||||
|
||||
Every delivery issue must have a persisted plan before code changes. Store it in a stable path such as:
|
||||
|
||||
```text
|
||||
.tmp/devops-plans/<repo>__issue-<number>.md
|
||||
```
|
||||
|
||||
## Plan Template
|
||||
|
||||
```text
|
||||
[issue-plan-v1]
|
||||
Issue:
|
||||
- repo:
|
||||
- number:
|
||||
- title:
|
||||
- type:
|
||||
- trigger source:
|
||||
|
||||
Status:
|
||||
- current: selected
|
||||
- owner agent:
|
||||
- reviewer:
|
||||
|
||||
Branching:
|
||||
- target base branch:
|
||||
- working branch:
|
||||
- PR:
|
||||
|
||||
Problem:
|
||||
|
||||
Expected behavior:
|
||||
|
||||
Acceptance criteria:
|
||||
- [ ]
|
||||
- [ ]
|
||||
|
||||
Related scope:
|
||||
- interfaces/apis:
|
||||
- directories/files:
|
||||
- tests:
|
||||
|
||||
Allowed path scope:
|
||||
- path/glob 1
|
||||
- path/glob 2
|
||||
|
||||
Curated context pack:
|
||||
- issue body/comments
|
||||
- attachments
|
||||
- code references
|
||||
- prior PRs/commits/docs
|
||||
|
||||
Implementation notes:
|
||||
|
||||
Verification plan:
|
||||
- build/compile:
|
||||
- unit/integration:
|
||||
- e2e:
|
||||
- smoke path:
|
||||
- screenshot/browser checks:
|
||||
|
||||
Evidence:
|
||||
- commit:
|
||||
- pipeline:
|
||||
- preview url:
|
||||
- screenshots:
|
||||
|
||||
Risk and blockers:
|
||||
|
||||
Handoff notes:
|
||||
```
|
||||
|
||||
## Required Status Flow
|
||||
|
||||
- `selected`
|
||||
- `planned`
|
||||
- `in_progress`
|
||||
- `pending_test`
|
||||
- `pending_review`
|
||||
- `merged`
|
||||
- `closed`
|
||||
- `needs_info`
|
||||
- `blocked`
|
||||
- `rejected`
|
||||
|
||||
## Ownership Rules
|
||||
|
||||
- MajorAgent creates and updates the plan before coding starts.
|
||||
- SubAgent reads only the plan plus minimal code context and updates implementation notes.
|
||||
- TestAgent updates verification results and may move the status back to `in_progress`.
|
||||
- Human reviewer confirms `pending_review` to merge readiness.
|
||||
|
||||
## Scope Rules
|
||||
|
||||
- If the diff touches files outside the allowed path scope, stop and either:
|
||||
- update the plan with justification, or
|
||||
- request human approval.
|
||||
- If a new dependency or deprecated technology is introduced, record the compatibility decision in `Risk and blockers`.
|
||||
@@ -53,10 +53,29 @@ Use this at session start before any implementation:
|
||||
- automatic：自动修复+提测循环，最终合并仍需工程师确认
|
||||
- semi-automatic：修复后先人工 review，再提测循环
|
||||
- manual：全流程人工确认
|
||||
可选：指定 reviewer、提测命令、部署环境、健康检查地址。
|
||||
4) 固定 issue 触发来源（issue 编号 / 评论触发 / app/CLI 选择 / 仅扫描不编码）
|
||||
可选：目标基线分支、分支命名规则、Plan 存储路径、指定 reviewer、提测命令、部署环境、健康检查地址、jj 策略。
|
||||
可选（推荐）：主环境 URL、共享 QA URL、预览槽位池（如 preview-a/preview-b）和预览 URL 模板。
|
||||
```
|
||||
|
||||
## Plan Summary Template
|
||||
|
||||
Use this comment or PR note after the MajorAgent has created the plan:
|
||||
|
||||
```text
|
||||
[issue-plan-summary-v1]
|
||||
已生成执行计划：
|
||||
- issue: #<number>
|
||||
- status: <selected|planned|...>
|
||||
- target base: <branch>
|
||||
- working branch: <branch>
|
||||
- allowed scope: <paths>
|
||||
- expected behavior: <summary>
|
||||
- verification: <unit/integration/e2e/smoke>
|
||||
- assigned agent: <major|sub|test>
|
||||
未完成前不会进入代码修改。
|
||||
```
|
||||
|
||||
## Review Request Template (Semi-Automatic)
|
||||
|
||||
```text
|
||||
@@ -65,6 +84,7 @@ Use this at session start before any implementation:
|
||||
- issue: #<number>
|
||||
- branch: <branch>
|
||||
- commit: <sha>
|
||||
- pr: <url>
|
||||
- change summary: <summary>
|
||||
- risk: <risk notes>
|
||||
- test plan: <plan>
|
||||
@@ -79,12 +99,14 @@ Use this at session start before any implementation:
|
||||
- issue: #<number>
|
||||
- branch: <branch>
|
||||
- commit: <sha>
|
||||
- pr: <url>
|
||||
- pipeline/test run: <url>
|
||||
- environment: <env/version>
|
||||
- preview slot: <slot>
|
||||
- preview url: <url>
|
||||
- deploy scope: <skip|client_only|server_only|full_stack|infra_only>
|
||||
- server strategy: <reused-shared|dedicated-branch-server>
|
||||
- e2e: <passed|failed|waived-with-approval>
|
||||
- verify steps: <steps>
|
||||
如失败或结果不符合预期，将继续同分支迭代修复。
|
||||
```
|
||||
@@ -121,6 +143,7 @@ Use this at session start before any implementation:
|
||||
- issue: #<number>
|
||||
- branch: <branch>
|
||||
- target: <target branch>
|
||||
- pr: <url>
|
||||
- review status: <approved/pending>
|
||||
- test status: <passed/failed>
|
||||
- release evidence: <links>
|
||||
@@ -133,6 +156,7 @@ Use this at session start before any implementation:
|
||||
[issue-verified-close-v1]
|
||||
已修复并发布。
|
||||
- commit: <sha>
|
||||
- pr: <url>
|
||||
- tests: <summary>
|
||||
- deploy: <pipeline/run url>
|
||||
- verify: <how verified>
|
||||
|
||||
Reference in New Issue
Block a user