deferred-capture

延迟捕获规范

适用场景

• 构建新的插件延迟捕获封装器
• 根据规范验证现有封装器
• 添加新的来源标签或模板字段

不适用场景

• 在运行时捕获延迟项目（直接使用插件 封装器，例如 plugins/<plugin>/scripts/deferred_capture.py）
• 手动创建 GitHub issue

所有插件延迟捕获封装器都必须实现的规范。 不是运行时依赖，只是一种约定。

CLI 接口

必需参数：

• --title (str)：简洁描述。添加 [Deferred] 前缀后成为 issue 标题
• --source (str)：来源技能。可选值：war-room、brainstorm、 scope-guard、feature-review、review、regression、egregore
• --context (str)：提出原因以及延迟处理的原因

可选参数：

• --labels (str)：除 deferred 和来源标签外的其他标签，以逗号分隔
• --session-id (str)：会话 ID。规范来源： hook payload stdin 中的 session_id (jq -r '.session_id')，回退值：UTC 时间戳 YYYYMMDD-HHMMSS
• --artifact-path (str)：源文件的绝对路径或基于 $HOME 的 路径
• --captured-by (str)：explicit（默认）或 safety-net
• --dry-run (flag)：输出 JSON，但不创建 issue

Issue 模板

标题：[Deferred] <title>

标签：deferred 和 <source>

正文：

## 延迟项目

**来源：** <source>（会话 <session-id>）
**捕获日期：** <YYYY-MM-DD>
**分支：** <当前 git 分支>
**捕获方式：** <explicit|safety-net>

### 背景

<原样使用 context 参数>

### 原始资料

<如提供则为 artifact-path，否则为 "N/A">

### 后续步骤

- [ ] 在未来周期评估可行性
- [ ] 如适用，关联相关工作

标签分类

标签	颜色	用途
deferred	#7B61FF	通用查询标识
war-room	#B60205	来源：war-room 讨论
brainstorm	#1D76DB	来源：头脑风暴会议
scope-guard	#FBCA04	来源：scope-guard 延迟处理
feature-review	#F9A825	来源：feature-review
review	#0E8A16	来源：代码/PR 审查
regression	#D73A4A	来源：技能回归
egregore	#5319E7	来源：自主 Agent

重复项检测

搜索：gh issue list --search "<title> in:title" --state open --json number,title

比较：去除 [Deferred] 前缀并转换为小写后，检查标题是否完全匹配。

仅检查未关闭的 issue。重新提交已关闭的延迟项目是有意为之。

输出（JSON 写入 stdout）

已创建：{"status": "created", "issue_url": "...", "number": 42} 重复项：{"status": "duplicate", "existing_url": "...", "number": 17} 错误：{"status": "error", "message": "..."}

合规性测试

任何封装器都可以通过以下命令验证是否符合规范：

python3 scripts/deferred_capture.py \
  --title "Test: compliance check" \
  --source test \
  --context "Automated compliance verification" \
  --dry-run

必须输出包含 status 字段的有效 JSON。

验收标准

• 合规性测试通过：对于任何符合规范的封装器，deferred_capture.py --dry-run 都会输出包含 status 字段（created、duplicate 或 error）的有效 JSON
• 创建的 issue 标题带有 [Deferred] 前缀，包含 deferred 标签和来源标签，且正文符合必需模板（来源、捕获日期、分支、捕获方式、 背景、原始资料、后续步骤）
• 创建前执行重复项检测：调用 gh issue list --search "<title> in:title"，若标题完全匹配（去除前缀并转换为小写），则不创建新 issue
• 每次调用都将 JSON 写入 stdout；成功时输出 {"status": "created", "issue_url": "...", "number": N}，重复项时输出 {"status": "duplicate", ...}，失败时输出 {"status": "error", "message": "..."}