用途:deferred-capture 是一份所有插件延迟捕获包装器都应实现的规范,属于约定而非运行时依赖。它定义了把被推迟的事项记录为 GitHub issue 时应遵循的接口、模板与标签体系。
适用场景:构建新的插件 deferred-capture 包装器;校验已有包装器是否符合规范;新增来源标签或模板字段。不适用场景:在运行时实际捕获延迟项(应直接使用插件包装器,例如 plugins/<plugin>/scripts/deferred_capture.py);手动创建 GitHub issue。
CLI 接口:必需参数包括 --title(简洁描述,最终成为加 [Deferred] 前缀的 issue 标题)、--source(来源技能,取值之一:war-room、brainstorm、scope-guard、feature-review、review、regression、egregore)、--context(提出原因与推迟原因)。可选参数包括 --labels(除 deferred 与来源标签外的逗号分隔附加标签)、--session-id(会话 ID,来源为 hook 载荷 stdin 的 session_id,即 jq -r '.session_id',回退为 UTC 时间戳 YYYYMMDD-HHMMSS)、--artifact-path(源产物路径)、--captured-by(explicit 默认或 safety-net)、--dry-run(仅打印 JSON 而不创建 issue)。
Issue 模板:标题为 [Deferred] <title>;标签含 deferred 与 <source>;正文包含来源、捕获时间、分支、捕获方式、上下文、原始产物与后续步骤。标签体系各来源配有指定颜色。
去重:创建前调用 gh issue list --search "<title> in:title" --state open --json number,title,去除 [Deferred] 前缀并小写归一后做精确标题比对,仅检查打开的 issue;对已关闭延迟项重新提交属于有意行为。
输出:成功为 {"status": "created", "issue_url": "...", "number": 42};重复为 {"status": "duplicate", ...};失败为 {"status": "error", "message": "..."}。
合规测试:可用 python3 scripts/deferred_capture.py --title "Test: compliance check" --source test --context "Automated compliance verification" --dry-run 验证,须输出带 status 字段的有效 JSON。退出标准覆盖合规测试、issue 标题与标签及正文模板、创建前去重、以及每次调用输出 JSON。