| name | github |
| description | Prepare GitHub issues, pull requests, reviews, and release notes for Zhin projects. Use when asked to write an issue, PR description, changelog entry, or review comment. Triggers: 写 issue, PR 描述, 提 PR, release notes, gh pr. |
| keywords | ["github","issue","pull request","pr","release notes","写 issue"] |
| tags | ["github","collaboration","documentation"] |
GitHub
为 Zhin 生态仓库生成可直接粘贴的 GitHub 文案（Issue / PR / Review / Release），不代替 gh 执行发布。
何时使用
- 写 Bug 报告、功能请求、PR 说明、Review 意见、版本发布说明
- 需要把本地验证结果整理成「Test plan」
- 不要用来改代码逻辑（除非用户明确要求附带补丁说明）
工作流
Issue
- 标题：
[area] 简短问题陈述（area 如 agent / adapter-icqq / cli）
- 输出完整 Markdown（可直接贴 GitHub）：
## 环境
- Node: v24.x
- zhin.js / @zhin.js/*: （版本或 commit）
- 适配器: icqq / telegram / ...
- OS: macOS / Linux
## 复现步骤
1. ...
2. ...
## 期望行为
...
## 实际行为
...
## 日志 / 截图
（脱敏；无 token）
Pull Request
- 输出完整 Markdown：
## Summary
- ...
## Test plan
- [x] `pnpm --filter @zhin.js/core test`
- [x] `pnpm type-check`
- [ ] `pnpm test`（如未跑则写原因）
## Risk
- Breaking: `zhin.config` `bots` → `endpoints`（如适用）
- DB: 自动迁移 `bot_id` → `endpoint_id`（如适用）
## Changeset
- [ ] 已添加 changeset（monorepo 发布包时必填）
- monorepo 常用验证命令（按改动范围选子集）：
pnpm --filter <pkg> build
pnpm --filter <pkg> test
pnpm type-check
pnpm check:architecture
Review
- 按文件或主题分组
- 区分 blocking vs nit
- 给出具体修改建议，避免空泛「建议优化」
Release notes
- 按 Keep a Changelog：
Added / Changed / Fixed / Breaking
- Breaking 必须写迁移步骤（如
bots: → endpoints:）
失败与兜底
| 触发条件 | 一线处理 | 仍失败 |
|---|
| 信息不足 | 列出缺失项（版本、配置、日志），🔴 暂停生成 | 用户补充后再写 |
| 含 token/密钥 | 删除敏感字段，用 <REDACTED> 占位 | 提醒用户轮换已泄漏凭证 |
gh 不可用 | 只输出 Markdown；给出 gh issue create / gh pr create 示例命令 | 用户手动在网页创建 |
🔴 CHECKPOINT · 敏感信息
生成前扫描：API token、.env 内容、私聊 ID、内网 URL。命中则不得写入 Issue/PR 正文。
不要做什么
- 不要在 Issue/PR 里贴完整
zhin.config.yml 密钥
- 不要编造未运行的测试结果为「已通过」
- 不要把内部机器 hostname/IP 写进公开 issue
- 不要用 PR 描述代替 Changeset（monorepo 发布流程）
- 不要对非 Zhin 仓库套用
packages/im 分层术语
工具
用户要求代发时，在项目根用 gh（需已 gh auth login）：
gh issue create --title "..." --body-file /tmp/issue.md
gh pr create --title "..." --body-file /tmp/pr.md
延伸阅读
| 文档 | 路径 |
|---|
| 贡献与 PR 流程 | docs/agents/issue-tracker.md |
| Changeset | 根目录 pnpm changeset |
| 架构约束 | AGENTS.md |
