diff --git a/docs/reference/cli.md b/docs/reference/cli.md index 893b4923..962f83e1 100644 --- a/docs/reference/cli.md +++ b/docs/reference/cli.md @@ -37,7 +37,7 @@ CLI 可以从 `master` 快速演进，但必须兼容 `deploy.json` 固定的 CI - `gh issue update --mode replace|append --body-file ` 是正文更新主入口，`edit` 保留为兼容别名。`replace` 用文件正文替换现有 body；`append` 先读取当前 body，再按 UTF-8 文件字节追加，保留真实换行、反引号和 Markdown 表格。更新默认拒绝字面量 `null`、空白正文和过短正文；只有真实需要写短正文时才允许显式加 `--allow-short-body`，返回 JSON 会报告该风险。#20 总看板和指挥简报类 issue 是长期 body-only issue，`--body-profile auto` 会按 issue number 自动启用 #20/#24 legacy guard：#20 必须包含 `## 看板（OPEN）`，#24 legacy 指挥简报必须包含 `## 常驻观察与长期建议`。显式 `--body-profile commander-brief` 不再固定 #24；#24 仍兼容，标题为 `YYYY-MM-DD 指挥简报（北京时间）` 或既有正文首行/关键 heading 表明为每日滚动指挥简报的 issue 也合法，并仍必须包含 `## 常驻观察与长期建议`。对非简报 issue 显式使用 `commander-brief` 会结构化失败为 `profile-issue-mismatch`。`--dry-run` 不 PATCH GitHub，输出新正文长度、SHA、关键标题检查结果、字面量 `\n`、反引号、Markdown 表格和 shell 污染信号；若环境里有 `GH_TOKEN` 或 `GITHUB_TOKEN`，dry-run 还会只读抓取旧正文长度、SHA 和 `updatedAt` 作为更新前对照。正式写入可带 `--expect-updated-at ` 或 `--expect-body-sha `，CLI 会先读当前 issue，匹配后才 PATCH，防止旧缓存覆盖新正文。 - #20 只允许承担长期总看板职责；每日进展必须写入当天滚动指挥简报 issue，并由 #20 顶部“指挥简报索引”引用。`gh issue read/view 20` 会返回 `codeQueueBoardHint`；`gh issue update/edit 20` 的 body guard 会拒绝 `## 更新 YYYY-MM-DD HH:mm 北京时间`、`## YYYY-MM-DD HH:mm 北京时间指挥更新` 和 `### YYYY-MM-DD HH:mm CST：...` 这类简报段落，并在 `codeQueueBoardHint` 中提示改写到每日简报 issue；`gh issue board-row list|get|update|add|move|delete|upsert --board-issue 20` 也会返回同一 hint，提醒不要把每日简报混入 #20。 - `gh issue edit 24 --body-file --notify-claudeqq-brief-diff [--dry-run]` 是 legacy #24 指挥简报的通知入口。正式执行会先读取 GitHub 上 #24 旧正文并通过 #24 body profile guard，再从 `--body-file` 读取新正文；随后先 PATCH issue 主体，再把本次新增的 `## 更新 YYYY-MM-DD HH:MM 北京时间` 段落发送给 ClaudeQQ，ClaudeQQ 失败不会回滚 issue 正文，失败只体现在返回 JSON 的 `claudeqq.ok=false` 和结构化 `degradedReason`。每日滚动简报 issue 可用普通 `gh issue update --body-profile commander-brief --dry-run` 和并发 guard 更新，但此通知 helper 仍只支持 #24。带通知 flag 的 `--dry-run` 不 PATCH、不发送；它按新正文做发送预览，并在输出中标明非 dry-run 才会读取旧正文做可靠 diff。默认 ClaudeQQ 目标是私聊 `645275593`，默认 base URL 是 UniDesk 受控入口 `http://backend-core:8080/api/microservices/claudeqq/proxy`，可用 `UNIDESK_COMMANDER_BRIEF_CLAUDEQQ_ENABLED`、`UNIDESK_COMMANDER_BRIEF_CLAUDEQQ_BASE_URL`、`UNIDESK_COMMANDER_BRIEF_CLAUDEQQ_TARGET_TYPE`、`UNIDESK_COMMANDER_BRIEF_CLAUDEQQ_USER_ID`、`UNIDESK_COMMANDER_BRIEF_CLAUDEQQ_GROUP_ID` 和 `UNIDESK_COMMANDER_BRIEF_CLAUDEQQ_TIMEOUT_MS` 覆盖。 -- `gh issue board-audit [--repo owner/name] [--board-issue 20] [--limit N] [--known-meta-issue N[,N...]] [--ignore-issue N[,N...]] [--dry-run]` 是 #20 长期总看板只读覆盖审计入口，默认 repo 为 `pikasTech/unidesk`、board issue 为 `20`、输出 JSON 且不 PATCH/POST/DELETE GitHub。它读取 board body、GitHub open issue 列表和 closed issue 列表，对比 OPEN/CLOSED Markdown 表格并输出 `missingOpenIssues`、`closedInOpenRows`、`missingClosedRows`、`openInClosedRows`、`rowValidationWarnings`、`ignoredIssues` 和 `recommendedActions`。当表格里存在 Issue 列时，row.issueNumber 优先取 Issue cell 中第一个指向 `/issues/` 的 Markdown link，找不到时取开头的 `#N`；同一 Issue cell 里主引用后面的标题说明引用（例如 `#20 总看板`、`基于 #4`）不触发 `multiple-issue-references`。没有 Issue 列的旧表格仍回退到整行 issue 提取，并保留多 issue 引用告警。`相关 Code Queue 任务`/`relatedTask` 列允许 `—`、`-`、`n/a`、`无任务` 等无关联任务占位表示 closed 历史/治理项没有 Code Queue task；这个放宽不适用于 branch、acceptance 或 progress。默认把 #20 和 #24 作为 `known-meta` 治理/简报 issue 忽略；标题匹配 `YYYY-MM-DD 指挥简报（北京时间）` 的每日滚动简报由 #20 顶部指挥简报索引管理，不进入 OPEN/CLOSED 覆盖审计，并在 `ignoredIssues` 中标记 `reason=brief-index-managed`。需要扩展治理项用 `--known-meta-issue`，临时排除业务 issue 用 `--ignore-issue`。指挥官发现总看板可能漏行时，应先跑 board audit 获取结构化结果，再决定是否人工编辑 #20，而不是只靠 grep。 +- `gh issue board-audit [--repo owner/name] [--board-issue 20] [--limit N] [--known-meta-issue N[,N...]] [--ignore-issue N[,N...]] [--dry-run]` 是总看板只读结构审计入口，默认 repo 为 `pikasTech/unidesk`、board issue 为 `20`、输出 JSON 且不 PATCH/POST/DELETE GitHub。它只读取目标 board issue 正文，返回正文长度、行数、body SHA、可解析 Markdown board sections、section 行数和 parser warnings；不再拉取 GitHub open/closed issue 列表，也不再校验 OPEN/CLOSED 表是否覆盖全部 issue。兼容字段 `missingOpenIssues`、`closedInOpenRows`、`missingClosedRows`、`openInClosedRows`、`rowValidationWarnings`、`ignoredIssues` 和 `recommendedActions` 仍保留，但固定为空数组或 0，用于避免旧调用方因字段缺失失败。需要维护旧式 OPEN/CLOSED 明细表时，继续使用 `gh issue board-row list|get|update|add|move|delete|upsert` 的行级结构化入口。 - `gh issue board-row list --board-issue 20 [--state open|closed|all] [--dry-run]`、`gh issue board-row get --board-issue 20` 和 `gh issue board-row update --board-issue 20 --field progress|status|validation|branch|tasks|focus --value [--dry-run] [--expect-updated-at ts|--expect-body-sha sha256]` 是 #20 看板表格单行结构化入口。list/get 复用 board-audit parser，只读返回 row、cells、fields、section、lineNumber、bodySha 和 rowValidationWarnings。update 只替换命中的一行里一个单元格，返回 old/new row、old/new body SHA、body guard、request plan 和 parser 结果；默认没有并发期望时即使不写 `--dry-run` 也只做 dry-run，正式 PATCH 必须带 `--expect-body-sha` 或 `--expect-updated-at`。字段映射固定为：`branch` -> Branch，`progress` -> 进度，`status`/`validation` -> 验收状态，`tasks` -> 相关 Code Queue 任务，`focus` -> 当前关注点。单元格值中的 Markdown 表格管道会转义为 `\|`，真实换行会折叠为空格，避免新增字面量 `\n` 污染。`gh issue board-row upsert --board-issue 20 --section open|closed [--category text] --branch --tasks --summary --focus --validation --progress [--status OPEN|CLOSED] [--dry-run] [--expect-body-sha|--expect-updated-at]` 是行级补齐入口：若 issue 已存在则只更新传入字段并返回 `operation=update`，未传字段保留原值；若不存在则按目标 section 表头生成完整行并返回 `operation=add`。新增时 `--section` 必需，且目标表头中的 category/branch/tasks/summary/focus/validation/progress 列都必须有对应值；若表没有独立 Summary/摘要列，`--summary` 会并入 Issue 单元格。upsert 不关闭、不删除、不重开 GitHub issue，也不做 OPEN/CLOSED 迁移；已存在行的 `--section` 或 `--status` 与当前 section 冲突时会结构化失败并提示使用 `board-row move`。`gh issue board-row add --board-issue 20 --section open|closed --row-file [--dry-run] [--expect-body-sha|--expect-updated-at]`、`move --board-issue 20 --to open|closed [--status OPEN|CLOSED] [--dry-run] [--expect-body-sha|--expect-updated-at]` 和 `delete --board-issue 20 [--dry-run] [--expect-body-sha|--expect-updated-at]` 是 row-scoped #20 结构化写入口。add 校验一行 `--row-file` 的 Issue 列、列数和 GitHub 状态列与目标 section 一致；move 允许跨 OPEN/CLOSED 表迁移并在需要时同步 GitHub 状态列；delete 仅删除匹配行。四类写入口默认 dry-run，非 dry-run 必须带 `--expect-body-sha` 或 `--expect-updated-at`，并返回 old/new row、body SHA、line/section 计划和 parser 结果；duplicate/ambiguous row、列数不匹配、缺少新增必填字段、section/status 冲突或 body SHA 不匹配都会结构化失败，不会 fallback 到整篇 body 手工替换。 - `gh issue scan-escape [--repo owner/name] [--limit N] [--dry-run]` 只读扫描 issue 主体和 comments 中的字面量 `\n`、可疑 `\t`、shell newline escape、escaped backtick、ANSI escape 字符串、短 body、blank body 和 null body。输出固定 JSON，`findings` 会带 `bodyKind=issue-body|comment-body`、`issueNumber`、`issueId`、`commentId`、`lineNumber`、`column`、`kind`、`snippet` 和 `classification=suspected-pollution|explanatory-mention|risk`，用于区分说明性提到 `\n` 和疑似污染；`cleanupSuggestions` 只给 dry-run 清理建议、body/comment 定位和 diff-like preview，不 PATCH、不 DELETE、不真实清理历史 comment。`gh issue cleanup-plan` 是同一只读能力的别名，默认 `dryRun=true`。`gh pr list [--state open|closed|all] [--json ...]` 提供 REST 列表，默认 `state=all` 以保持既有 UniDesk CLI 行为，字段白名单是 `body,title,state,number,url,author,head,base,draft,createdAt,updatedAt`；未知 state 或未知 `--json` 字段必须结构化失败并带 `runnerDisposition=business-failed`。`gh pr read|view [--json ...]` 继续稳定返回这些字段，并额外支持 `headRefName,baseRefName,mergeable,mergeStateStatus,statusCheckRollup`。`headRefName` 与 `baseRefName` 来自 REST `head.ref`/`base.ref`；`mergeable`、`mergeStateStatus` 和 `statusCheckRollup` 只在 read/view 明确请求这些字段时通过 GitHub GraphQL 查询，GraphQL 权限不足、网络失败或 GitHub 暂未计算完成时会结构化失败或返回 GitHub 原始 `UNKNOWN`/null 状态。此时收口人员应优先重试一次；若仍缺失、需要完整 `gh pr view --json` 等 GitHub 官方字段、或需要执行 merge/review 这类 UniDesk CLI 尚未开放的操作，回退到系统 `gh` 只读观察或人工 GitHub UI，不要把空字段当作可合并证据。`gh pr create --title --body-file <file>|--body <text> --base <branch> --head <branch> [--draft] [--dry-run]`、`gh pr update <number> --mode replace|append --body-file <file>|--body <text> [--title ...] [--dry-run]`、`gh pr comment create <number> --body-file <file>|--body <text> [--dry-run]`、`gh pr comment delete <commentId> [--dry-run]`、`gh pr close|reopen <number> [--dry-run]` 是 PR CRUD/生命周期入口。`pr create --dry-run` 只输出 planned operation，不访问 GitHub；非 dry-run 创建前会校验 repo、base、head 和 compare ahead 状态，成功时返回 PR number/url。`pr update --mode append` 会先读取当前 PR body 再追加正文。`gh pr delete <number>` 和 `gh pr merge` 本阶段不开放，始终结构化返回 `unsupported-command`；PR 生命周期删除语义请使用 `close`。 - PR dry-run/probe 的最小手动序列是：`bun scripts/cli.ts gh auth status --repo pikasTech/unidesk` 只读检查 token 来源、GitHub REST egress、repo 可见性和 issue read；`bun scripts/cli.ts gh pr create --repo pikasTech/unidesk --title <title> --body-file <file> --base master --head <head> --dry-run` 检查创建计划；`bun scripts/cli.ts gh pr list --repo pikasTech/unidesk --state open --limit 5 --json number,title,state,url,head,base` 和 `bun scripts/cli.ts gh pr view <number> --repo pikasTech/unidesk --json body,title,state,head,base,headRefName,baseRefName,mergeable,mergeStateStatus,statusCheckRollup` 做只读 PR 观察和收口元数据检查；`bun scripts/cli.ts gh pr comment <number> --repo pikasTech/unidesk --body-file <file> --dry-run` 检查评论计划；`bun scripts/cli.ts gh pr merge <number> --repo pikasTech/unidesk` 必须失败并返回结构化 `unsupported-command`。Code Queue runner 可用 `bun scripts/code-queue-pr-preflight-example.ts --repo pikasTech/unidesk --base master --head <head> --comment-pr <number>` 一次性跑只读 auth status 与 PR create/comment dry-run；该脚本不得输出 token 值，也不会创建、评论或 merge PR。 diff --git a/docs/reference/code-queue-supervision.md b/docs/reference/code-queue-supervision.md index 3f9c2e3f..3c63b3ce 100644 --- a/docs/reference/code-queue-supervision.md +++ b/docs/reference/code-queue-supervision.md @@ -120,7 +120,7 @@ issue 内容必须自包含，至少写清楚背景、外部收益、当前观 如果某个 worker 任务需要依赖 GitHub issue 内容，但 runner 的 issue 可达性尚未被单独验证，指挥官不能默认 worker 已能读取该 issue。此时 worker prompt 必须直接内嵌完整需求、约束和验收点，issue URL 只能作为辅助引用。若要把 issue 作为任务输入源，先单独做可达性探测，再决定是否把 issue 作为常规前置条件。 -GitHub issue/PR 操作应优先使用 UniDesk CLI 的安全入口：`bun scripts/cli.ts gh auth status`、`gh issue list/read/view/create/update/comment create/comment delete/close/reopen/scan-escape/cleanup-plan/board-audit/board-row list/board-row get/board-row update`、`gh pr list/read/view/create/update/comment create/comment delete/close/reopen`。该入口默认 repo 是 `pikasTech/unidesk`，支持 `--repo owner/name`，输出稳定 JSON，并把 `missing-binary`、`missing-token`、`auth-failed`、`network-proxy-failed`、`permission-denied`、`repo-not-found`、`repo-forbidden`、`issue-not-found`、`pr-not-found`、`scope-insufficient`、`validation-failed`、`invalid-response`、`unsupported-command` 等失败原因结构化。失败对象必须包含 `runnerDisposition=infra-blocked|business-failed`，runner 应用它区分基础设施阻塞和业务/参数失败。`gh issue list --state open --limit N --json number,title,state,url` 是有界 issue 发现入口，`--state` 只接受 `open|closed|all`，list 字段白名单是 `number,title,state,url,updatedAt,createdAt,author,labels`；未知 state 或未知字段必须失败，不能静默返回空数组。`gh issue read <number> --json body` 是 canonical 入口，正文仍应从 `.data.issue.body` 读取；`view` 只保留为兼容别名。未知 `--json` 字段必须失败，不得让调用方把空正文误判为读取成功。`gh issue scan-escape --limit N [--dry-run]` 与 `gh issue cleanup-plan` 只读扫描 issue body/comments 的字面量 `\n`、shell escape、短 body、blank/null body，输出 `classification=suspected-pollution|explanatory-mention|risk`、body/comment id、预览和清理建议；说明性提到 `\n` 不应被当成污染，cleanup-plan 永远不真实清理历史评论。`gh issue board-audit --board-issue 20 --limit N --dry-run` 只读对比 GitHub open/closed issue 列表与 #20 的 OPEN/CLOSED Markdown 表格，输出 `missingOpenIssues`、`closedInOpenRows`、`missingClosedRows`、`rowValidationWarnings`、`ignoredIssues` 和 `recommendedActions`。存在 Issue 列时，row key 优先来自 Issue cell 的主 Markdown issue link `/issues/<N>`，其次是开头 `#N`；主引用后的标题说明引用不触发多 issue 告警。没有 Issue 列的旧表格仍使用整行 fallback 并保留 `multiple-issue-references`。`相关 Code Queue 任务` 可用 `—`、`-` 或等价无任务占位表达无关联 task，但 branch、acceptance 和 progress 仍必须填写真实值；默认把 #20/#24 作为 known-meta 忽略，标题匹配 `YYYY-MM-DD 指挥简报（北京时间）` 的每日滚动简报由 #20 顶部指挥简报索引管理，并以 `reason=brief-index-managed` 进入 `ignoredIssues`，不进入 OPEN/CLOSED 覆盖审计。指挥官发现 #20 可能漏跟 open issue 或分表错误时，应先跑 board audit 取得结构化缺口，再人工审阅和编辑 #20，不要只靠 grep。显式 `gh issue update <number> --body-profile commander-brief` 可用于 #24 legacy 简报和每日滚动简报 issue；每日简报 issue 应用标题 `YYYY-MM-DD 指挥简报（北京时间）` 或在既有正文首行/关键 heading 中标明简报身份，且新正文必须包含 `## 常驻观察与长期建议`。对非简报 issue 使用该 profile 应失败为 `profile-issue-mismatch`。`gh issue board-row list --board-issue 20 --state open|closed|all` 和 `gh issue board-row get <issueNumber> --board-issue 20` 复用同一个 parser 读取表格行；`gh issue board-row update <issueNumber> --board-issue 20 --field progress|status|validation|branch|tasks|focus --value <text>` 只替换一行一个单元格，输出 old/new row、body SHA、body guard 和 request plan，且默认 dry-run，正式写入必须带 `--expect-body-sha` 或 `--expect-updated-at`。字段映射中 `status`/`validation` 都指向 `验收状态`，`tasks` 指向 `相关 Code Queue 任务`，`focus` 指向 `当前关注点`；单元格管道会转义、真实换行会折叠为空格，避免新增字面量 `\n`。`gh issue board-row upsert` 可更新既有行或按 section 生成完整新行；`board-row add/move/delete` 已支持行级新增、OPEN/CLOSED 迁移和删除，全部默认 dry-run，正式 PATCH 必须带 `--expect-body-sha` 或 `--expect-updated-at`。`gh pr list --json ...` 支持 `body,title,state,number,url,author,head,base,draft,createdAt,updatedAt` 字段白名单；`gh pr read|view --json ...` 还支持 `headRefName,baseRefName,mergeable,mergeStateStatus,statusCheckRollup`，其中 mergeability/check rollup 只在请求时通过 GitHub GraphQL 补取，适合 PR 收口前判断分支、可合并性和检查汇总。GraphQL 权限不足、网络失败、GitHub 仍返回 `UNKNOWN`/null、或需要 UniDesk CLI 尚未开放的官方字段、review/merge 操作时，回退系统 `gh` 只读观察或 GitHub UI；不要把缺失元数据当成已可合并。issue/PR 创建、更新、评论、评论删除、关闭和重开使用 GitHub REST API；只要有 `GH_TOKEN` 或 `GITHUB_TOKEN`，就不依赖系统 `gh` binary。`gh` binary 只作为状态探测和 `gh auth token` fallback，不是写操作的主路径。GitHub 不支持 issue/PR 硬删除，`gh issue delete` 和 `gh pr delete` 必须结构化返回 `unsupported-command`；生命周期删除语义使用 `close`。`gh pr merge` 仍然不开放。 +GitHub issue/PR 操作应优先使用 UniDesk CLI 的安全入口：`bun scripts/cli.ts gh auth status`、`gh issue list/read/view/create/update/comment create/comment delete/close/reopen/scan-escape/cleanup-plan/board-audit/board-row list/board-row get/board-row update`、`gh pr list/read/view/create/update/comment create/comment delete/close/reopen`。该入口默认 repo 是 `pikasTech/unidesk`，支持 `--repo owner/name`，输出稳定 JSON，并把 `missing-binary`、`missing-token`、`auth-failed`、`network-proxy-failed`、`permission-denied`、`repo-not-found`、`repo-forbidden`、`issue-not-found`、`pr-not-found`、`scope-insufficient`、`validation-failed`、`invalid-response`、`unsupported-command` 等失败原因结构化。失败对象必须包含 `runnerDisposition=infra-blocked|business-failed`，runner 应用它区分基础设施阻塞和业务/参数失败。`gh issue list --state open --limit N --json number,title,state,url` 是有界 issue 发现入口，`--state` 只接受 `open|closed|all`，list 字段白名单是 `number,title,state,url,updatedAt,createdAt,author,labels`；未知 state 或未知字段必须失败，不能静默返回空数组。`gh issue read <number> --json body` 是 canonical 入口，正文仍应从 `.data.issue.body` 读取；`view` 只保留为兼容别名。未知 `--json` 字段必须失败，不得让调用方把空正文误判为读取成功。`gh issue scan-escape --limit N [--dry-run]` 与 `gh issue cleanup-plan` 只读扫描 issue body/comments 的字面量 `\n`、shell escape、短 body、blank/null body，输出 `classification=suspected-pollution|explanatory-mention|risk`、body/comment id、预览和清理建议；说明性提到 `\n` 不应被当成污染，cleanup-plan 永远不真实清理历史评论。`gh issue board-audit --board-issue 20 --limit N --dry-run` 只读审计目标 board issue 正文结构，返回正文长度、行数、body SHA、可解析 Markdown board sections、section 行数和 parser warnings；它不再拉取 GitHub open/closed issue 列表，也不再校验 OPEN/CLOSED 表覆盖关系。兼容字段 `missingOpenIssues`、`closedInOpenRows`、`missingClosedRows`、`rowValidationWarnings`、`ignoredIssues` 和 `recommendedActions` 仍保留为空数组或 0。显式 `gh issue update <number> --body-profile commander-brief` 可用于 #24 legacy 简报和每日滚动简报 issue；每日简报 issue 应用标题 `YYYY-MM-DD 指挥简报（北京时间）` 或在既有正文首行/关键 heading 中标明简报身份，且新正文必须包含 `## 常驻观察与长期建议`。对非简报 issue 使用该 profile 应失败为 `profile-issue-mismatch`。需要维护旧式 OPEN/CLOSED 明细表时，继续使用 `gh issue board-row list --board-issue 20 --state open|closed|all`、`gh issue board-row get <issueNumber> --board-issue 20` 和 `gh issue board-row update <issueNumber> --board-issue 20 --field progress|status|validation|branch|tasks|focus --value <text>`；`board-row update` 只替换一行一个单元格，输出 old/new row、body SHA、body guard 和 request plan，且默认 dry-run，正式写入必须带 `--expect-body-sha` 或 `--expect-updated-at`。字段映射中 `status`/`validation` 都指向 `验收状态`，`tasks` 指向 `相关 Code Queue 任务`，`focus` 指向 `当前关注点`；单元格管道会转义、真实换行会折叠为空格，避免新增字面量 `\n`。`gh issue board-row upsert` 可更新既有行或按 section 生成完整新行；`board-row add/move/delete` 已支持行级新增、OPEN/CLOSED 迁移和删除，全部默认 dry-run，正式 PATCH 必须带 `--expect-body-sha` 或 `--expect-updated-at`。`gh pr list --json ...` 支持 `body,title,state,number,url,author,head,base,draft,createdAt,updatedAt` 字段白名单；`gh pr read|view --json ...` 还支持 `headRefName,baseRefName,mergeable,mergeStateStatus,statusCheckRollup`，其中 mergeability/check rollup 只在请求时通过 GitHub GraphQL 补取，适合 PR 收口前判断分支、可合并性和检查汇总。GraphQL 权限不足、网络失败、GitHub 仍返回 `UNKNOWN`/null、或需要 UniDesk CLI 尚未开放的官方字段、review/merge 操作时，回退系统 `gh` 只读观察或 GitHub UI；不要把缺失元数据当成已可合并。issue/PR 创建、更新、评论、评论删除、关闭和重开使用 GitHub REST API；只要有 `GH_TOKEN` 或 `GITHUB_TOKEN`，就不依赖系统 `gh` binary。`gh` binary 只作为状态探测和 `gh auth token` fallback，不是写操作的主路径。GitHub 不支持 issue/PR 硬删除，`gh issue delete` 和 `gh pr delete` 必须结构化返回 `unsupported-command`；生命周期删除语义使用 `close`。`gh pr merge` 仍然不开放。 CLI 是短 shout 的需求原语，不是长驻服务器进程。CLI 功能不好用、兼容性不足、安全 guard 不够或输出不利于 runner/指挥官使用时，应默认创建 GitHub issue 并用 Code Queue 推进；这类 CLI 问题走 `master`、remote commit、轻量 contract test 和文档更新，不套用 backend-core、Code Queue runtime 这类运行态服务的重部署门禁。若 CLI 缺陷已经阻塞当前指挥，可以先做最小安全绕行，同时把长期修复写入 issue 并派单。 diff --git a/scripts/gh-cli-issue-guard-contract-test.ts b/scripts/gh-cli-issue-guard-contract-test.ts index ad670db8..26fef355 100644 --- a/scripts/gh-cli-issue-guard-contract-test.ts +++ b/scripts/gh-cli-issue-guard-contract-test.ts @@ -654,29 +654,32 @@ export async function runGhCliIssueGuardContract(): Promise<JsonRecord> { assertCondition(boardAudit.status === 0, "issue board-audit should succeed as a read-only audit", boardAudit.json ?? { stdout: boardAudit.stdout, stderr: boardAudit.stderr }); const boardAuditData = dataOf(boardAudit.json ?? {}); assertCondition(boardAuditData.command === "issue board-audit" && boardAuditData.dryRun === true && boardAuditData.readOnly === true, "board-audit should be explicit read-only dry-run", boardAuditData); + const boardAuditIssue = boardAuditData.boardIssue as JsonRecord; + assertCondition(typeof boardAuditIssue.bodySha === "string" && String(boardAuditIssue.bodySha).length === 64, "board-audit should expose board body sha", boardAuditIssue); + const boardAuditSummary = boardAuditData.summary as JsonRecord; + assertCondition(boardAuditSummary.openIssues === null && boardAuditSummary.closedIssues === null, "board-audit should not fetch GitHub open/closed issue lists", boardAuditSummary); + assertCondition(boardAuditSummary.openRows === 4 && boardAuditSummary.closedRows === 3 && boardAuditSummary.parsedSections === 2, "board-audit should report parsed board structure", boardAuditSummary); + const boardAuditValidation = boardAuditData.validation as JsonRecord; + const openClosedCoverage = boardAuditValidation.openClosedCoverage as JsonRecord; + assertCondition(openClosedCoverage.enabled === false, "board-audit should disable OPEN/CLOSED coverage validation", boardAuditValidation); const missingOpenIssues = boardAuditData.missingOpenIssues as JsonRecord[]; - assertCondition(Array.isArray(missingOpenIssues) && missingOpenIssues.some((issue) => issue.number === 36), "board-audit should report open issue missing from OPEN table", missingOpenIssues); - assertCondition(!missingOpenIssues.some((issue) => issue.number === 45), "board-audit should use the primary markdown issue link as the Issue-column row key", missingOpenIssues); - assertCondition(!missingOpenIssues.some((issue) => issue.number === 46), "board-audit should not require daily commander briefs in the OPEN table", missingOpenIssues); + assertCondition(Array.isArray(missingOpenIssues) && missingOpenIssues.length === 0, "board-audit should not report missing OPEN rows", missingOpenIssues); const closedInOpenRows = boardAuditData.closedInOpenRows as JsonRecord[]; - assertCondition(Array.isArray(closedInOpenRows) && closedInOpenRows.some((issue) => issue.number === 40), "board-audit should report closed issue still in OPEN table", closedInOpenRows); + assertCondition(Array.isArray(closedInOpenRows) && closedInOpenRows.length === 0, "board-audit should not report closed issues in OPEN rows", closedInOpenRows); const missingClosedRows = boardAuditData.missingClosedRows as JsonRecord[]; - assertCondition(Array.isArray(missingClosedRows) && missingClosedRows.some((issue) => issue.number === 40) && missingClosedRows.some((issue) => issue.number === 41), "board-audit should report closed issues missing from CLOSED table", missingClosedRows); - assertCondition(!missingClosedRows.some((issue) => issue.number === 18), "board-audit should ignore explanatory issue references after the primary Issue-column markdown link", missingClosedRows); + assertCondition(Array.isArray(missingClosedRows) && missingClosedRows.length === 0, "board-audit should not report missing CLOSED rows", missingClosedRows); const openInClosedRows = boardAuditData.openInClosedRows as JsonRecord[]; - assertCondition(Array.isArray(openInClosedRows) && openInClosedRows.some((issue) => issue.number === 36), "board-audit should report open issue placed in CLOSED table", openInClosedRows); + assertCondition(Array.isArray(openInClosedRows) && openInClosedRows.length === 0, "board-audit should not report open issues in CLOSED rows", openInClosedRows); const rowValidationWarnings = boardAuditData.rowValidationWarnings as JsonRecord[]; - assertCondition(Array.isArray(rowValidationWarnings) && rowValidationWarnings.some((warning) => warning.issueNumber === 40 && Array.isArray(warning.missingColumns) && (warning.missingColumns as unknown[]).includes("branch") && (warning.missingColumns as unknown[]).includes("acceptance") && (warning.missingColumns as unknown[]).includes("progress")), "board-audit should report missing required board columns", rowValidationWarnings); - assertCondition(!rowValidationWarnings.some((warning) => warning.kind === "multiple-issue-references"), "board-audit should not treat explanatory issue references outside the Issue column as row-key conflicts", rowValidationWarnings); - assertCondition(!rowValidationWarnings.some((warning) => warning.kind === "multiple-issue-references" && String(warning.rowPreview ?? "").includes("#20 总看板")), "board-audit should not warn when an Issue-column title mentions #20 after primary #45 link", rowValidationWarnings); - assertCondition(!rowValidationWarnings.some((warning) => warning.kind === "multiple-issue-references" && String(warning.rowPreview ?? "").includes("基于 #4")), "board-audit should not warn when an Issue-column title mentions #4 after primary #18 link", rowValidationWarnings); - assertCondition(!rowValidationWarnings.some((warning) => Array.isArray(warning.missingColumns) && (warning.missingColumns as unknown[]).includes("relatedTask")), "board-audit should recognize relatedTask from the current header", rowValidationWarnings); + assertCondition(Array.isArray(rowValidationWarnings) && rowValidationWarnings.length === 0, "board-audit should not report required-column row warnings", rowValidationWarnings); + const parserWarnings = boardAuditData.parserWarnings as JsonRecord[]; + assertCondition(Array.isArray(parserWarnings), "board-audit should expose parser warnings separately", boardAuditData); const ignoredIssues = boardAuditData.ignoredIssues as JsonRecord[]; - assertCondition(Array.isArray(ignoredIssues) && ignoredIssues.some((issue) => issue.number === 20 && issue.reason === "known-meta") && ignoredIssues.some((issue) => issue.number === 24 && issue.reason === "known-meta"), "board-audit should ignore configured known meta issues", ignoredIssues); - assertCondition(ignoredIssues.some((issue) => issue.number === 46 && issue.reason === "brief-index-managed"), "board-audit should ignore daily commander briefs managed by the #20 brief index", ignoredIssues); + assertCondition(Array.isArray(ignoredIssues) && ignoredIssues.length === 0, "board-audit should not produce ignored issue coverage output", ignoredIssues); const recommendedActions = boardAuditData.recommendedActions as JsonRecord[]; - assertCondition(Array.isArray(recommendedActions) && recommendedActions.some((action) => action.action === "add-open-row" && action.issueNumber === 36) && recommendedActions.some((action) => action.action === "move-open-row-to-closed" && action.issueNumber === 40), "board-audit should emit machine-readable recommended actions", recommendedActions); - assertCondition(!recommendedActions.some((action) => action.action === "add-open-row" && action.issueNumber === 46), "board-audit should not recommend adding daily commander briefs to the OPEN table", recommendedActions); + assertCondition(Array.isArray(recommendedActions) && recommendedActions.length === 0, "board-audit should not emit OPEN/CLOSED coverage actions", recommendedActions); + const boardAuditGetRequests = mock.requests.slice(boardAuditRequestCountBefore).filter((request) => request.method === "GET"); + assertCondition(boardAuditGetRequests.length === 1 && boardAuditGetRequests[0]?.url === "/repos/pikasTech/unidesk/issues/20", "board-audit should only fetch the board issue body", boardAuditGetRequests); const boardAuditWriteCount = mock.requests.slice(boardAuditRequestCountBefore).filter((request) => request.method === "PATCH" || request.method === "DELETE" || request.method === "POST").length; assertCondition(boardAuditWriteCount === 0, "board-audit must not write GitHub", { requests: mock.requests.slice(boardAuditRequestCountBefore) }); @@ -684,8 +687,8 @@ export async function runGhCliIssueGuardContract(): Promise<JsonRecord> { const legacyBoardAudit = await runCli(["gh", "issue", "board-audit", "--repo", "pikasTech/unidesk", "--board-issue", "60", "--limit", "60", "--dry-run"], env); assertCondition(legacyBoardAudit.status === 0, "legacy board-audit fixture should succeed", legacyBoardAudit.json ?? { stdout: legacyBoardAudit.stdout, stderr: legacyBoardAudit.stderr }); const legacyBoardAuditData = dataOf(legacyBoardAudit.json ?? {}); - const legacyWarnings = legacyBoardAuditData.rowValidationWarnings as JsonRecord[]; - assertCondition(Array.isArray(legacyWarnings) && legacyWarnings.some((warning) => warning.kind === "multiple-issue-references" && warning.issueNumber === 101), "legacy board-audit fixture should keep whole-row fallback when no Issue column exists", legacyWarnings); + const legacyWarnings = legacyBoardAuditData.parserWarnings as JsonRecord[]; + assertCondition(Array.isArray(legacyWarnings) && legacyWarnings.some((warning) => warning.kind === "multiple-issue-references" && warning.issueNumber === 101), "legacy board-audit fixture should keep parser warnings when no Issue column exists", legacyWarnings); const legacyBoardWriteCount = mock.requests.slice(legacyBoardAuditRequestCountBefore).filter((request) => request.method === "PATCH" || request.method === "DELETE" || request.method === "POST").length; assertCondition(legacyBoardWriteCount === 0, "legacy board-audit must not write GitHub", { requests: mock.requests.slice(legacyBoardAuditRequestCountBefore) }); @@ -1326,7 +1329,7 @@ export async function runGhCliIssueGuardContract(): Promise<JsonRecord> { "issue list default fields include labels and filter pull requests", "issue scan-escape classifies pollution, explanatory mentions, and body risks", "issue cleanup-plan remains dry-run with body/comment cleanup suggestions", - "issue board-audit reports missing open rows, closed/open section mismatches, missing closed rows, meta/brief-index ignores, and row validation warnings without writes", + "issue board-audit returns read-only board structure, disables OPEN/CLOSED coverage validation, and keeps compatibility fields empty without writes", "issue board-row list/get expose parsed #20 rows without writes", "issue board-row upsert updates existing rows, adds missing rows, reports operation, preserves table trailers, rejects ambiguous rows, blocks stale body SHA writes, and stays dry-run without concurrency guards", "issue board-row add/delete without guard stay on dry-run and do not PATCH", diff --git a/scripts/src/gh.ts b/scripts/src/gh.ts index 9fa1f4b6..8795df04 100644 --- a/scripts/src/gh.ts +++ b/scripts/src/gh.ts @@ -3893,101 +3893,10 @@ async function issueBoardAudit(repo: string, token: string, options: GitHubOptio const commandName = "issue board-audit"; const boardIssue = await getIssue(token, repo, options.boardIssue); if (isGitHubError(boardIssue)) return commandError(commandName, repo, boardIssue, { boardIssue: options.boardIssue }); - const [rawOpenIssues, rawClosedIssues] = await Promise.all([ - listIssues(token, repo, "open", options.limit), - listIssues(token, repo, "closed", options.limit), - ]); - if (isGitHubError(rawOpenIssues)) return commandError(commandName, repo, rawOpenIssues, { phase: "list-open-issues", boardIssue: options.boardIssue, limit: options.limit }); - if (isGitHubError(rawClosedIssues)) return commandError(commandName, repo, rawClosedIssues, { phase: "list-closed-issues", boardIssue: options.boardIssue, limit: options.limit }); - - const openIssues = rawOpenIssues.filter((issue) => issue.pull_request === undefined).slice(0, options.limit).map(boardIssueEntry); - const closedIssues = rawClosedIssues.filter((issue) => issue.pull_request === undefined).slice(0, options.limit).map(boardIssueEntry); - const allListedIssues = [...openIssues, ...closedIssues]; - const issueMap = new Map<number, BoardIssueEntry>(allListedIssues.map((issue) => [issue.number, issue])); - const ignoreMap = boardIgnoreMap(options, allListedIssues); const parsed = parseBoardTables(boardIssue.body ?? ""); - const rowValidationWarnings = parsed.warnings.filter((warning) => warning.issueNumber === null || !ignoreMap.has(warning.issueNumber)); const openRows = parsed.sections.filter((section) => section.kind === "open").flatMap((section) => section.rows); const closedRows = parsed.sections.filter((section) => section.kind === "closed").flatMap((section) => section.rows); - const openRowMap = boardRowsByIssue(openRows); - const closedRowMap = boardRowsByIssue(closedRows); - const openIssueNumbers = new Set(openIssues.map((issue) => issue.number)); - const closedIssueNumbers = new Set(closedIssues.map((issue) => issue.number)); - const boardIssueNumbers = Array.from(new Set([...openRowMap.keys(), ...closedRowMap.keys()])); - - const missingOpenIssues = sortedIssueEntries(openIssues.filter((issue) => !ignoreMap.has(issue.number) && !openRowMap.has(issue.number))); - const closedInOpenRows = sortedIssueEntries(closedIssues.filter((issue) => !ignoreMap.has(issue.number) && openRowMap.has(issue.number))).map((issue) => ({ - ...issue, - rows: (openRowMap.get(issue.number) ?? []).map((row) => ({ lineNumber: row.lineNumber, rowPreview: preview(row.raw) })), - })); - const missingClosedRows = sortedIssueEntries(closedIssues.filter((issue) => !ignoreMap.has(issue.number) && !closedRowMap.has(issue.number))); - const openInClosedRows = sortedIssueEntries(openIssues.filter((issue) => !ignoreMap.has(issue.number) && closedRowMap.has(issue.number))).map((issue) => ({ - ...issue, - rows: (closedRowMap.get(issue.number) ?? []).map((row) => ({ lineNumber: row.lineNumber, rowPreview: preview(row.raw) })), - })); - const staleOpenRows = Array.from(openRowMap.entries()) - .filter(([issueNumber]) => !ignoreMap.has(issueNumber) && !openIssueNumbers.has(issueNumber)) - .map(([issueNumber, rows]) => ({ - issueNumber, - knownState: closedIssueNumbers.has(issueNumber) ? "closed" : "not-in-listed-window", - rows: rows.map((row) => ({ lineNumber: row.lineNumber, rowPreview: preview(row.raw) })), - })) - .sort((a, b) => a.issueNumber - b.issueNumber); - const boardOnlyRows = boardIssueNumbers - .filter((issueNumber) => !ignoreMap.has(issueNumber) && !issueMap.has(issueNumber)) - .sort((a, b) => a - b) - .map((issueNumber) => ({ - issueNumber, - sections: [ - ...(openRowMap.has(issueNumber) ? ["open"] : []), - ...(closedRowMap.has(issueNumber) ? ["closed"] : []), - ], - rows: [...(openRowMap.get(issueNumber) ?? []), ...(closedRowMap.get(issueNumber) ?? [])].map((row) => ({ - section: row.section, - lineNumber: row.lineNumber, - rowPreview: preview(row.raw), - })), - })); - const ignoredIssues = [ - ...ignoredIssueList(allListedIssues, ignoreMap), - ...ignoredBoardOnlyIssues(boardIssueNumbers, issueMap, ignoreMap), - ].sort((a, b) => a.number - b.number); - const recommendedActions = [ - ...missingOpenIssues.map((issue) => ({ - action: "add-open-row", - issueNumber: issue.number, - title: issue.title, - section: "open", - reason: "GitHub issue is open but no #20 OPEN table row was found.", - })), - ...closedInOpenRows.map((issue) => ({ - action: "move-open-row-to-closed", - issueNumber: issue.number, - title: issue.title, - reason: "GitHub issue is closed but still appears in the #20 OPEN table.", - })), - ...missingClosedRows.map((issue) => ({ - action: "add-closed-row", - issueNumber: issue.number, - title: issue.title, - section: "closed", - reason: "GitHub issue is closed but no #20 CLOSED table row was found.", - })), - ...openInClosedRows.map((issue) => ({ - action: "move-closed-row-to-open", - issueNumber: issue.number, - title: issue.title, - reason: "GitHub issue is open but appears in the #20 CLOSED table.", - })), - ...rowValidationWarnings.map((warning) => ({ - action: "fill-board-row-fields", - issueNumber: warning.issueNumber, - section: warning.section, - lineNumber: warning.lineNumber, - reason: warning.message, - missingColumns: warning.missingColumns ?? [], - })), - ]; + const body = boardIssue.body ?? ""; return { ok: true, @@ -4001,7 +3910,9 @@ async function issueBoardAudit(repo: string, token: string, options: GitHubOptio title: boardIssue.title, state: boardIssue.state, url: boardIssue.html_url, - bodyChars: (boardIssue.body ?? "").length, + bodyChars: body.length, + bodyLines: body.length === 0 ? 0 : normalizeNewlines(body).split("\n").length, + bodySha: bodySha(body), updatedAt: boardIssue.updated_at ?? null, }, config: { @@ -4009,21 +3920,36 @@ async function issueBoardAudit(repo: string, token: string, options: GitHubOptio knownMetaIssues: mergedKnownMetaIssues(options), ignoredIssues: options.ignoredIssues, briefIndexManagedIssuePattern: options.boardIssue === CODE_QUEUE_BOARD_TARGET_ISSUE ? "YYYY-MM-DD 指挥简报（北京时间）" : null, - requiredColumns: BOARD_AUDIT_REQUIRED_COLUMNS.slice(), + openClosedCoverageValidation: false, + requiredColumns: [], }, summary: { - openIssues: openIssues.length, - closedIssues: closedIssues.length, + openIssues: null, + closedIssues: null, openRows: openRows.length, closedRows: closedRows.length, - missingOpenIssues: missingOpenIssues.length, - closedInOpenRows: closedInOpenRows.length, - missingClosedRows: missingClosedRows.length, - openInClosedRows: openInClosedRows.length, - rowValidationWarnings: rowValidationWarnings.length, - ignoredIssues: ignoredIssues.length, - boardOnlyRows: boardOnlyRows.length, - staleOpenRows: staleOpenRows.length, + parsedSections: parsed.sections.length, + parsedRows: parsed.sections.reduce((sum, section) => sum + section.rows.length, 0), + parserWarnings: parsed.warnings.length, + missingOpenIssues: 0, + closedInOpenRows: 0, + missingClosedRows: 0, + openInClosedRows: 0, + rowValidationWarnings: 0, + ignoredIssues: 0, + boardOnlyRows: 0, + staleOpenRows: 0, + recommendedActions: 0, + }, + validation: { + openClosedCoverage: { + enabled: false, + reason: "OPEN/CLOSED table coverage validation has been disabled; this command no longer compares GitHub issue state against board rows.", + }, + rowRequiredColumns: { + enabled: false, + reason: "board-audit no longer reports missing required row columns; use board-row commands when intentionally maintaining a legacy OPEN/CLOSED table.", + }, }, sections: parsed.sections.map((section) => ({ kind: section.kind, @@ -4034,25 +3960,24 @@ async function issueBoardAudit(repo: string, token: string, options: GitHubOptio rows: section.rows.length, issueNumbers: section.rows.flatMap((row) => row.issueNumbers), })), - missingOpenIssues, - closedInOpenRows, - missingClosedRows, - openInClosedRows, - staleOpenRows, - boardOnlyRows, - rowValidationWarnings, - ignoredIssues, - recommendedActions, + parserWarnings: parsed.warnings, + missingOpenIssues: [], + closedInOpenRows: [], + missingClosedRows: [], + openInClosedRows: [], + staleOpenRows: [], + boardOnlyRows: [], + rowValidationWarnings: [], + ignoredIssues: [], + recommendedActions: [], request: { method: "GET", paths: [ `/repos/{owner}/{repo}/issues/${options.boardIssue}`, - "/repos/{owner}/{repo}/issues?state=open", - "/repos/{owner}/{repo}/issues?state=closed", ], - query: { per_page: options.limit }, + query: {}, }, - note: "Read-only board audit; no issue body was edited, no issue was closed, and no comments were written.", + note: "Read-only board structure audit; OPEN/CLOSED coverage validation is disabled, no issue body was edited, no issue was closed, and no comments were written.", }; } @@ -4830,7 +4755,7 @@ export function ghHelp(): unknown { "When staging a body file from a shell, use a quoted heredoc such as cat <<'EOF' > /tmp/body.md so backticks and backslashes are not expanded before --body-file reads the file.", "For JSON request bodies in other CLI namespaces, prefer --body-file or --body-stdin over long inline shell arguments; GitHub Markdown writes intentionally use --body-file only.", "issue scan-escape classifies literal \\n findings as suspected-pollution, explanatory-mention, or risk, and emits cleanupSuggestions with body/comment ids plus diff-like previews. cleanup-plan is an alias that remains dry-run/read-only.", - "issue board-audit is read-only and defaults to repo pikasTech/unidesk plus board issue #20. It compares GitHub open/closed issue lists with the board OPEN/CLOSED tables and reports missingOpenIssues, closedInOpenRows, missingClosedRows, rowValidationWarnings, ignoredIssues, and recommendedActions. When an Issue column exists, row.issueNumber is taken from that column; #20 and #24 are known meta issues by default. Daily rolling brief issues titled YYYY-MM-DD 指挥简报（北京时间） are managed by #20's brief index and appear in ignoredIssues with reason=brief-index-managed instead of missingOpenIssues.", + "issue board-audit is read-only and defaults to repo pikasTech/unidesk plus board issue #20. It reads only the board issue body, returns body size/SHA and parsed Markdown board sections, and no longer validates GitHub open/closed issue coverage against OPEN/CLOSED tables. The legacy coverage fields remain present as empty arrays/zero counts for compatibility.", "issue board-row list/get reuse the board-audit table parser and are read-only. board-row update changes one table cell by issue number, returns old/new row, body SHA, body guard and request plan, and defaults to dry-run unless --expect-updated-at or --expect-body-sha is supplied for the guarded PATCH. Field aliases map status and validation to the 验收状态 column, tasks to 相关 Code Queue 任务, and focus to 当前关注点.", "issue board-row upsert updates an existing row when the issue is already present, or generates a complete row in --section open|closed when missing. It returns operation=update or operation=add, defaults to dry-run, requires --expect-body-sha or --expect-updated-at before PATCH, and refuses section migration; use board-row move for OPEN/CLOSED migration.", "issue board-row add/move/delete are row-scoped #20 table mutations. add validates a one-line --row-file against the target table column count, Issue column, and GitHub 状态 column; move refuses duplicate/ambiguous rows and can update GitHub 状态 via --status; delete removes only the matched row. All three default to dry-run and require --expect-body-sha or --expect-updated-at before PATCH. add/move/delete return old/new row, body SHA, and line/section plan details for the parsed table mutation.",