gitdev-github-issue

name	gitdev (GitHub Issue 自动化全日制管线)
description	完整的 GitHub Issue 全自动提报与执行框架。包含需求智能拆解、自动打标分发，以及沙盒化无人值守编码消费。
when_to_use	当用户希望借助 AI 自动化提报、拆解并创建 Github Issue，或者希望唤醒后台 Agent 根据 Issue 列表去对应的代码仓库自动修 Bug / 敲代码时触发。通用触发语境包括但不限于："帮我建个工单"、"将这个方案提成 issue"、"整理一下给对应的库抛个 bug"、"去消费排队的 issue"、"开启自动干活模式"。
what_it_does	提供了一套相互完全解耦的异步架构。前端(Producer)负责将结构化需求进行云端上报，后端(Consumer)在特定的工作目录进行 Agent 挂载并实弹化解决这些 Github Issue。

🤖 GitDev: 自动化开发执行闭环技能 (Issue 生产者与消费者框架)

这是一个基于开源基础设施构建的 Issue 自动管线技能，它被设定为明确的**“生产者-消费者” 模型**。

在面对涉及跨系统或耗时较长的复杂需求时，本体系创造性地将整个工程周期在逻辑上严格拆分为了两个完全解耦的闭环：

1. 纯云端、无状态的生成链路 (Producer / Issue 生产)：这是一种轻量级的随机触发模式。创建 Issue 的过程完全依托于跟 GitHub 的云端交互。你在任何时刻产生了灵感、发现了问题，都可以随时唤醒该组件向远端上报请求。且由于其本身是无状态的，它无需被死死绑定或者依赖某个特定的本地开发目录。
2. 强状态、本地落盘的编码工作流 (Consumer / Issue 消费)：当系统转入去“消费和实现”这些 Issue 单时，则必须被明确挂载投递到特定且真实的宿主机工作目录中。这是因为底层代码 Agent 产生的文件变更必须被安全落盘，强迫指定真实工作区，既能在故障时保留完整现场，更极大方便了人类工程师在中途介入进行代码审计、Code Review 甚至人机同屏协作结对编程。

⚙️ 依赖前提条件与环境配置

执行本 Skill 需要依赖如下系统工具：

1. GitHub CLI (gh): 必须已登录，带有 repo 和 issue 的读写全权限 token (gh auth login)。
2. AI Agents:
   • Claude Code: 默认执行引擎，命令名为 claude。
   • Antigravity CLI (agy): 可选引擎（需自行通过 -a agy 激活），命令名为 agy。
3. jq: 必须已部署在系统上，用于处理所有的 JSON 数据交互栈。
4. tmux: 必须已经安装在系统中（用于给每个长执行消费者提供无干扰隔离会话）。
5. 系统架构: Linux/bash 环境。

🔑 初始化 .env 与系统运行路径提取机制

绝大部分私有凭证（如远端 Telegram 通知 Key）及**绝对环境变量路径（重要！）**都被统归于当前技能包根目录的 .env 配置文件下管理。

针对于环境变量跨 cron/tmux 丢失的现象，我们在该技能包下集成了一个自动探测工具。这往往是你获取技能后的首要执行步骤：

# 请在当前技能的根目录下执行此命令：
bash scripts/setup-env.sh

完成提取后，你可以使用 vim .env 自行完善里面的私域 Token 账密内容。

🚀 组件 1: 生产者 (Issue 生成 - Producer)

使用场景: 明确要开发一个大需求、提出 Feature 或提报 Bug 时使用。要求利用专门结构化的格式生成符合 AI 执行标准的 Issue。

基本命令:

bash scripts/producer.sh -r "仓库名称" -c "(bug|feature|architecture)" -f "相关的代码文件或工作目录" "需求与诉求"

• 核心参数:
  • -r | --repo: 指定 GitHub 提交源仓库，如 leoshan/deepdive。（必填/必须指定）
  • -c | --category: 当前 Issue 类型，支持 feature, bug, architecture, task。若不填则默认为 auto。
  • -a | --agent: (新功能) 指定执行该任务的 AI Agent 类型（目前支持 claude, agy）。默认为 claude。选择后会同步为 Issue 增加 agent:xxx 标签以透传给执行端。
  • -p | --priority: high/medium/low
  • -f | --files: 对上下文中涉及到的文件，将其送入 Agent 提示词供初步检阅。

🚀 组件 2: 消费者 (Issue 编码实现 - Consumer)

使用场景: 被激活的 Issue 需要正式处理。它将隔离并在 tmux 开启一个 60 分钟进程实现 Issue 并随后利用 gh 接口关单。 消费者模式分两种执行状态：

1. 单起 (一次性执行) 指定仓库，在某个独立的工作目录开启 Agent 执行池。支持通过 -a 参数强制指定 Agent。

# 默认使用 Issue 标签指定的 Agent，或回落到 claude
bash scripts/consumer.sh "leoshan/deepdive" "/root/ai_infra"

# 强制使用指定 Agent 覆盖（不管 Issue 上的标签是什么）
bash scripts/consumer.sh --agent=agy "leoshan/deepdive" "/root/ai_infra"

2. Cron 定时自动消费 (完全自治) 将消费配置为 Linux 定时任务（例如每 30 分钟拉一次并实现最小序号 issue）：

# 将下述内容添加到 crontab -e:
*/30 * * * * bash /root/.gemini/antigravity/skills/gitdev/scripts/consumer.sh "leoshan/deepdive" "/root/ai_infra" >> /tmp/gitdev-cron.log 2>&1

🚀 组件 3: 推送与告警 (通知 - Notifier)

使用场景: 每当一个处于 tmux 或独立子进程中的 Consumer 执行成功或阻塞挂掉时，需要向外发送通知（当前是发送到telegram bot）。 配置文件说明: 该能力已完全解耦私有参数。在使用前，系统需要具备一个包含 Token、Chat ID 基本信息的文件 .env：

# 在 /root/.gemini/antigravity/skills/gitdev 目录下创建 .env
TELEGRAM_BOT_TOKEN="xxx"
TELEGRAM_CHAT_ID="xxx"

事件驱动通知机制: 系统采用即时事件驱动架构。每当 producer.sh 创建成功或 consumer.sh 任务结束时，脚本会自动触发 scripts/notify.sh 发送战报。无需配置 Crontab 轮询，确保通知零延迟且无额外算力损耗。

🚀 组件 4: 监控看板与逃逸打断 (Manager 面板)

使用场景: 你的 GitDev 跑载在后台充当无情的执行机器时，你难免需要探查它的排队情况或者是打断它。或者偶尔处理 Agent 过度拉跨无法自拔的情况。 基本命令:

# 查看所有库被挤压/熔断任务的大图
bash scripts/manager.sh status

# 展示目前正在运作的独立沙盒 Agent 消费进程
bash scripts/manager.sh sessions

# [极其重要] 如果你发现某个进程挂死，可直接强制销毁这个端点
bash scripts/manager.sh kill 12  # 打断隔离执行 12 号 Issue 的后台进程

# 赦免由于连续处理失败被熔断锁定（Failed 3次的任务）令其复活加入调度
bash scripts/manager.sh reset leoshan/deepdive 12

---

📂 技能内部结构与目录

所有的参数源配置、产生的中间件、运行日志、会话堆栈、以及状态映射 JSON 文件，均被严格限制落地于此技能包的本地边界内。杜绝了对全局主工作区的代码污染。

gitdev/
├── SKILL.md               # 技能完整使用说明文档（当前文档）
├── .env.example           # 默认环境变量、超时与重试配置及私有凭据参考模板
├── .env                   # [运行时生成] 脱机保存实际使用的各类密钥和系统底层路径
├── templates/             # 存放根据不同问题定制下发的提问大模型约束模板
│   ├── feature.md         # 需求功能业务建模大纲
│   ├── bug.md             # 故障复现重捕获排错指南
│   ├── architecture.md    # 基础架构改造契约
│   ├── task.md            # 执行、调研或报告生成日常操作类任务（新增）
│   └── issue-template.md  # 回退使用的预备模板
├── scripts/               # 核心执行引擎套件包：
│   ├── setup-env.sh       # [首次必用] 自动寻访本地环境可执行文件构建底层 PATH 拼接脚本
│   ├── producer.sh        # <纯云端无状态请求> 生成者组件，负责梳理开发上下文远端派发工单
│   ├── consumer.sh        # <强工作区挂载依赖> 消费者组件，使用 Tmux 沙盒投毒拉取解决工单
│   ├── manager.sh         # 管理大盘监控探针及执行环境越权管控(Kill/Status)
│   └── notify.sh          # 分布式信使组件，依据执行结果中转推送（如Telegram）反馈战报
└── logs/                  # [运行态内部全自动生成] 后台透明工作追踪台
    ├── producer-*.log     # 请求发送历史留痕
    ├── issue-notify.json  # 通讯信使提取执行参数用的中转暂存档
    └── <repo_name>/       # 依据隔离项目拆分的消费者数据沙盘
        ├── issue-state.json        # Manager 大盘追踪重发次数、判定死锁挂起的底层 JSON 数据库
        └── issue-implement-*.log   # Agent 每一步的动作拆解、代码执行崩溃和输出堆栈日志