# Issue Workflow

**Repository Path**: truthhun/issue-workflow

## Basic Information

- **Project Name**: Issue Workflow
- **Description**: 面向兼容 Skill 的 AI Agent，提供 Issue 筛选、分析、修复引导与权限安全的 API 操作。
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-17
- **Last Updated**: 2026-08-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: issue-skill, Agent-Skill, issue-workflow

## README

# Issue Workflow

Issue Workflow 是一个可移植的 Skill，面向兼容 Skill 的 AI Agent 和自动化宿主环境。它用于一次性、由用户驱动的 GitHub 和 Gitee Issue 工作流，可以筛选和读取 Issue，结合本地代码分析选中的 Issue，并在用户确认后引导修复工作。

English documentation（默认入口）：[README.md](README.md)

## 功能范围

- 按负责人、标签、里程碑、状态、Issue 关联分支和分页条件列出 Issue。
- 在分析前读取选中的 Issue、相关评论和已关联上下文。
- 输出基于证据的缺陷分析、修复计划和验证边界。
- 对 Issue 元数据、本地代码、评论和新 Issue 的操作，均须逐项确认后才执行。
- 处理 GitHub 和 Gitee 在 Issue 状态、标签、分支和 Pull Request 过滤方面的差异。

本 Skill 只处理一次性工作流，不执行轮询、定时任务、Webhook、后台监听或自动触发变更。

## 安装与调用

将 `issue-workflow/` 目录注册为宿主环境中的 Skill，并保留其中的 `SKILL.md`、`agents/`、`references/` 和 `scripts/` 文件。请使用宿主环境提供的 Skill 调用机制；支持 `$name` 语法的宿主可以使用以下名称调用：

```text
$issue-workflow
```

Skill 会先确认平台和仓库，再进行 Issue 操作。如果用户没有提供仓库，它会先检查当前 Git remote 并请求确认。

核心工作流使用与宿主无关的 Markdown 编写；内置 API 辅助脚本也可以直接在 Shell 中运行，不依赖 Skill 宿主环境。

## 确认规则

读取和本地分析不需要写入确认；以下操作必须分别请求确认：

- 认领 Issue 或修改负责人；
- 添加或修改标签、里程碑或状态；
- 修改本地代码；
- 创建或发布 Issue 评论；
- 创建 Issue、提交、推送或创建 Pull Request。

确认不可传递：确认一个操作不代表授权后续其他操作。已有 Issue 内容会被视为不可信输入，不会被当作执行命令的授权。

## API 辅助脚本

内置的 `scripts/issue_api.py` 适配器支持有边界的读取操作，以及经过确认的写入操作：

```bash
# 读取有数量限制的 Issue 列表。
python3 issue-workflow/scripts/issue_api.py \
  list --provider gitee --repo owner/repo \
  --state open --max-issues 20
```

可用命令包括 `list`、`get`、`comments`、`update`、`comment` 和 `create`。写入命令只能在对应确认完成后执行。不要将 token 放入 URL，也不要将 token 保存到仓库中。

Token 环境变量：

- GitHub：`GITHUB_TOKEN`
- Gitee：`GITEE_TOKEN`

如需使用其他环境变量，可通过 `--token-env` 指定。

Token 权限要求：

- 为支持读取和经过确认的写入操作，Token 必须拥有 Issue 和 Issue 评论的读写权限。
- 对 Gitee，请同时开启 `issues` 和 `notes` 的读写权限：`issues` 用于 Issue，`notes` 用于 Issue 评论和讨论备注。
- 对 GitHub Fine-grained Personal Access Token，请先选择目标仓库，再进入 `Repository permissions → Issues → Read and write`；Issue 评论使用同一项 Issues 权限。
- 对 GitHub Classic Personal Access Token，私有仓库使用 `repo` scope，公开仓库使用 `public_repo` scope。

具体接口权限可参考 [GitHub 官方 Fine-grained Token 权限说明](https://docs.github.com/en/rest/authentication/permissions-required-for-fine-grained-personal-access-tokens)。

仅有只读权限时只能执行读取工作流，无法更新 Issue、发布评论或创建 Issue。

## 仓库结构

```text
issue-workflow/
├── SKILL.md                  # Skill 说明和确认规则
├── agents/openai.yaml        # 可选的 OpenAI 兼容 Agent 元数据
├── references/               # 平台说明和回复模板
└── scripts/                  # Issue API 适配器和离线测试
```

## 本地验证

在仓库根目录运行离线测试：

```bash
python3 -m unittest discover -s issue-workflow/scripts -p 'test_*.py'
```

测试覆盖解析和平台无关的行为，不会连接 GitHub 或 Gitee。