Local Issue Skill

Everything is a file.

Issue 即 Markdown 文件，存于版本控制之中。无服务、无网络、无 API——每一条 issue 都是可被 grep、cat、git log 直接操作的纯文本。这让 agent 能像处理代码一样处理任务上下文：跨 issue 全文搜索、批量提取状态、在同一次 commit 中同时更新代码与 issue 进展，一切工具链天然适配。

更深层的意义在于：每个独立的 issue 文件本质上是一个事件（event）。项目由此从线性的任务列表，演变为事件驱动的结构——多个 agent 可以各自认领不同的 issue 并行推进，CI/CD 流水线可以监听 issue 状态变更并自动触发，代码与任务的边界在 git 历史中完全透明。这或许正是 AI 原生开发的新范式：不是 AI 辅助人类写代码，而是以 issue 为协议，人与 agent 协同驱动一个持续演进的系统。

CLI 工具

本 skill 提供统一的 local-issue CLI 工具，设计遵循 agent-friendly 原则：

非交互式优先：所有输入通过参数传递，无需交互式菜单
管道友好：支持 --quiet 模式输出机器可读格式
分层帮助：每个子命令有独立的 --help 和示例
明确的错误信息：失败时提供可操作的提示
幂等性：重复执行相同命令是安全的

安装：

# 将 CLI 工具链接到系统路径
ln -s ~/.claude/skills/local-issue/local-issue ~/.local/bin/local-issue
# 或直接使用完整路径
alias local-issue='python3 ~/.claude/skills/local-issue/local-issue'

可用命令：

local-issue create - 从模板创建新 issue
local-issue close - 关闭 issue 并移动到 closed/
local-issue progress - 追加进展记录
local-issue next - 预留下一个可用的 issue 编号
local-issue list - 列出 issues
local-issue status - 显示详细状态汇总
local-issue log - 显示 issue 相关的 git commit 历史

每个命令都支持 --help 查看详细用法和示例。

Issue 系统位置

.issues/
├── open/        # 待处理 issue（文件名格式：NNN-type-description.md）
├── closed/      # 已完成 issue
└── templates/   # 模板（bug.md / feature.md / refactor.md）

执行步骤

1. 确定下一个 Issue 编号并创建占位文件

使用 local-issue next 命令，默认行为会创建占位文件以避免序号竞争。

基本用法：

local-issue next

输出示例：

047
placeholder_path=.issues/open/047-placeholder.md
# Next: Rename to 047-{type}-{description}.md

在指定项目中使用：

local-issue next /path/to/project/.issues

可用选项：

| 选项 | 说明 | 使用场景 | |------|------|----------| | --query-only | 仅查询下一个编号，不创建占位文件 | 统计、预览 | | --dry-run | 预览将创建的占位文件，但不实际创建 | 测试、验证 | | --quiet / -q | 仅输出编号（机器可读模式） | 管道、脚本集成 |

管道友好的用法：

# 在脚本中使用
ISSUE_ID=$(local-issue next --quiet)
mv .issues/open/$ISSUE_ID-placeholder.md .issues/open/$ISSUE_ID-bug-fix.md

# 提取占位文件路径
OUTPUT=$(local-issue next)
ISSUE_ID=$(echo "$OUTPUT" | head -1)
PLACEHOLDER=$(echo "$OUTPUT" | grep "placeholder_path=" | cut -d= -f2)

错误处理：

如果占位文件已存在（序号竞争），命令会报错并提示重新运行：

Error: Placeholder already exists: .issues/open/047-placeholder.md
Hint: Run 'local-issue next' again to get the next available ID.

2. 选择 Issue 类型

根据用户描述选择类型标签：

| 类型 | 标签 | 文件头 | 使用场景 | |------|------|--------|----------| | bug | bug | [Bug] | 功能异常、错误行为 | | feature | feature | [Feature] | 新功能需求 | | refactor | refactor | [Refactor] | 代码重构、技术债务 |

3. 选择模板

优先使用项目自带模板：

# 检查项目是否有对应模板
ls .issues/templates/

若存在 .issues/templates/{type}.md → 以该文件为模板
若不存在 → 使用 skill 内置模板（见 templates/ 目录）

推荐创建方式：`create`

create 会自动完成编号分配、文件命名、模板选择和常见占位符替换，是创建 issue 的首选方式。

local-issue create bug "PDF 连续模式缩放错位"
local-issue create feature "支持视频 mov/mkv 转码" --priority High
local-issue create refactor "拆分 AnnotationCanvas" --assignee claude
local-issue create bug "渲染回归" --label pdf --label regression

行为：

自动选择下一个编号
文件名格式：.issues/open/{NNN}-{type}-{title}.md
优先使用项目模板 .issues/templates/{type}.md，否则使用 skill 内置模板
自动替换 #XXX、YYYY-MM-DD、Issue Title、{简短标题}
自动维护 Status、Priority、Type、Created、Updated、Assignee、Labels 等常见元信息

输出示例：

Created .issues/open/047-bug-PDF连续模式缩放错位.md

手动创建流程

以下 next + mv 流程保留给需要精确控制文件名或模板内容的场景。

4. 重命名占位文件并填充内容

由于步骤 1 已经创建了占位文件（如 .issues/open/047-placeholder.md），现在需要：

4.1 确定最终文件名

文件名格式：.issues/open/{NNN}-{type}-{short-description}.md

{NNN} = 三位数字编号，不足补零（已由脚本生成）
{type} = 类型标签（小写）
{short-description} = 简短描述（用连字符，英文或中文均可）

示例：047-bug-websocket-timeout.md、048-feature-历史推文拉取.md

4.2 重命名占位文件

mv .issues/open/047-placeholder.md .issues/open/047-bug-websocket-timeout.md

4.3 填充 Issue 内容

将模板内容写入重命名后的文件，填写以下占位字段：

#XXX → 实际编号
YYYY-MM-DD → 今日日期
标题、描述、相关章节内容

注意：如果在重命名前发现占位文件已不存在，说明发生了序号竞争。此时应重新运行步骤 1 获取新的序号。

5. 提交 Issue 文件到 Git

首先检查项目的 commit 规范，优先级从高到低：

CLAUDE.md / AGENTS.md — AI agent 专属规范
CONTRIBUTING.md — 项目贡献规范
git log --oneline — 从历史提交归纳风格

在没有任何规范的情况下，才使用以下格式作为兜底：

git add .issues/open/{filename}.md
git commit -m "docs: add issue #{NNN} - {简短描述}"

6. 开始处理

创建 issue 后立即着手解决：

分析问题根源
制定实现计划
更新 issue 中的"进展记录"
实现时在代码注释中引用：// Fix: #{NNN}

更新进展

使用 progress 为指定 issue 追加进展记录，并同步更新 Updated 日期：

local-issue progress 047 "完成根因定位：canvasZoom 被重复应用"

如果 issue 中已有当天的 ### YYYY-MM-DD 小节，会直接追加 bullet；否则会在 ## 进展记录 下创建当天小节。

关闭 Issue

推荐使用 close 关闭 issue：

local-issue close 047
local-issue close 047 --summary "修复 canvasZoom 重复换算"

行为：

查找 .issues/open/047-*.md
更新：
- Status: Closed ✅
- Updated: {YYYY-MM-DD}
- Closed: {YYYY-MM-DD}
如传入 --summary，追加 ## 解决总结
移动到 .issues/closed/

参考文档记录规范

当 issue 涉及第三方库、框架、API 或版本特定行为时，应在 issue 中记录参考来源，避免只凭记忆实现。

Context7 特例

如果项目安装了 /context7 skill，且 issue 涉及第三方库 API，应优先使用 Context7 查询官方文档。

推荐流程：

搜索库 ID：

scripts/context7.sh search "library-name"

查询相关主题：

scripts/context7.sh docs "/library-id" "topic" "code"

在 issue 的 参考资料 或 技术方案 中记录：

## 参考资料

- Context7: `/library-id` — topic: `xxx`
- 结论：……

适用场景：

新增或修改第三方库调用
不确定 API 参数、返回值、生命周期、版本差异
需要示例代码辅助实现
依赖升级或替换

查询命令

`list` — 列出 Issues

按 type 分组，组内按 Priority 降序（High 在前）。

语法

local-issue list [issues-dir] [--state open|closed|all] [--type bug|feature|refactor] [--priority high|medium|low] [--limit N] [--quiet]

默认行为：--state open，不限 type / priority，--limit 30

示例

# 列出所有 open issues（默认）
local-issue list

# 列出所有状态的 issues
local-issue list --state all

# 只列出 bug 类型的 issues
local-issue list --type bug

# 只列出高优先级的 issues
local-issue list --priority high

# 限制显示数量
local-issue list --limit 10

# 机器可读模式（仅输出 ID）
local-issue list --quiet

# 在指定项目中使用
local-issue list /path/to/project/.issues

输出格式

Open Issues (26)

[bug] 12
  #034  High      websocket-reconnect-on-reset-without-closing-handshake
  #075  High      decay-sell-missing-reverse-constraint
  #040  -         tweet_storage_plugin-chartjs-cdn-url-不存在

[feature] 10
  #064  High      polymarket-order-entry-plugin
  #051  Medium    纸面交易页面显示当前选项价格挂单数量
  #031  -         迁移-liquidity-rewards-plugin

[refactor] 4
  #055  -         统一polymarket-ws服务注册

- 表示 Priority 字段缺失或为 Unassigned。

机器可读输出 (--quiet)：

`status` — 详细状态汇总

显示 issue 系统的整体状态，包括统计、分布和最近活动。

语法

local-issue status [issues-dir]

示例

# 显示当前项目的状态
local-issue status

# 显示指定项目的状态
local-issue status /path/to/project/.issues

输出格式

─────────────────────────────────────────────
Issue Status                  2026-04-12
─────────────────────────────────────────────
Open: 26    Closed: 95    Total: 121

By Type (open)
  bug          12  ████████████░░░░░░░░  46%
  feature      10  ██████████░░░░░░░░░░  38%
  refactor      4  ████░░░░░░░░░░░░░░░░  15%

By Priority (open)
  High          8  ████████░░░░░░░░░░░░  31%
  Medium       12  ████████████░░░░░░░░  46%
  Low           0  ░░░░░░░░░░░░░░░░░░░░   0%
  (unset)       6  ██████░░░░░░░░░░░░░░  23%

Recently Updated (open)
  #117  feature   持仓空缺自动诊断 POC                        2026-04-12
  #114  bug       实盘下单三类精度与金额校验                   2026-04-11
  #116  bug       SELL size 超出实际持仓                      2026-04-10
  #091  bug       current-count-shows-2                      2026-04-09
  #082  bug       rest-price-fallback-not-applied            2026-04-08

Recent Issue Commits
  30a940a  #114  docs: close issue #114 - 实盘下单三类精度
  eb422a7  #116  docs: close issue #116 - SELL size 超出实际持仓
  389109f  #116  fix: #116 - SELL size 截断到 1 位小数
  8da1b3d  #116  docs: add issue #116 - 实盘下单 SELL size 超出
  c2d62cb  #117  feat: logger_factory auto_issue watcher POC
─────────────────────────────────────────────

`log` — Issue 关联的 Git Commit 历史

查询哪些 commit 引用了 issue。

语法

local-issue log [issue-id] [issues-dir] [--limit N] [--quiet]

示例

# 列出最近所有引用任意 issue 编号的 commits
local-issue log

# 查询特定 issue 的 commit 历史
local-issue log 064

# 限制显示数量
local-issue log --limit 10

# 机器可读模式（仅输出 commit hash）
local-issue log --quiet
local-issue log 064 --quiet

# 在指定项目中使用
local-issue log 064 /path/to/project/.issues

输出（无参数）

Recent issue-related commits (20)
  30a940a  #114    docs: close issue #114 - 实盘下单三类精度
  eb422a7  #116    docs: close issue #116 - SELL size 超出实际持仓
  389109f  #116    fix: #116 - SELL size 截断到 1 位小数
  8da1b3d  #116    docs: add issue #116 - 实盘下单 SELL size 超出
  ...

输出（带 issue 编号）

Commits referencing #064 (3)
  abc1234  2026-02-20  feat: #064 - add order entry plugin base structure
  def5678  2026-02-21  feat: #064 - implement order form UI
  ghi9012  2026-02-22  docs: close issue #064

── Issue ──────────────────────────────
  File:    .issues/closed/064-feature-polymarket-order-entry-plugin.md
  Status:  Closed ✅
  Created: 2026-02-19

机器可读输出 (--quiet)：

abc1234
def5678
ghi9012

Git Commit 引用规范

以下为通用参考，项目自有规范优先：

Issue 创建：docs: add issue #{NNN} - {描述}
功能提交：feat: #{NNN} - {描述} 或 fix: #{NNN} - {描述}
关闭 Issue：在 commit body 中写 Closes #{NNN}

示例

用户输入：/local-issue 记录 WebSocket 断线重连的 bug

执行（推荐）：

运行 local-issue create bug "WebSocket 断线重连"
根据输出文件补充问题细节
git add .issues/open/047-bug-WebSocket断线重连.md
git commit -m "docs: add issue #047 - WebSocket断线重连bug"
开始分析代码，在进展记录中更新状态

手动流程：

运行 local-issue next
- 扫描得最大编号为 046，新建 047
- 创建占位文件 .issues/open/047-placeholder.md
- 输出：047 和 placeholder_path=.issues/open/047-placeholder.md
类型：bug
检查 .issues/templates/bug.md → 存在，使用项目模板
重命名占位文件：mv .issues/open/047-placeholder.md .issues/open/047-bug-websocket-reconnect.md
填写模板内容，描述断线重连问题
git add .issues/open/047-bug-websocket-reconnect.md
git commit -m "docs: add issue #047 - WebSocket断线重连bug"
开始分析代码，在进展记录中更新状态

序号竞争说明

问题场景：多个 agent 或用户同时创建 issue 时，可能读取到相同的"下一个序号"，导致文件名冲突。

解决方案：

默认行为：local-issue next 在返回序号的同时创建占位文件（如 047-placeholder.md）
占位文件作为"锁"，确保该序号被当前操作独占
后续操作通过重命名占位文件完成 issue 创建
如果占位文件已存在，命令会报错退出，提示序号已被占用

仅查询模式：

使用 --query-only 参数可以只查询序号而不创建占位文件
适用于统计、预览等场景
不应在实际创建 issue 时使用此模式

CLI 工具快速参考

# 获取帮助
local-issue help
local-issue help next

# 创建新 issue（推荐）
local-issue create bug "PDF 连续模式缩放错位"
local-issue create feature "支持视频 mov/mkv 转码" --priority High

# 追加进展
local-issue progress 047 "完成根因定位"

# 关闭 issue
local-issue close 047 --summary "修复完成"

# 预留编号（手动流程）
local-issue next
local-issue next --quiet  # 仅输出编号

# 列出 issues
local-issue list
local-issue list --state all
local-issue list --type bug --priority high
local-issue list --quiet  # 仅输出 ID

# 查看状态汇总
local-issue status

# 查看 commit 历史
local-issue log
local-issue log 047
local-issue log --quiet  # 仅输出 commit hash