diff --git a/AGENTS.md b/AGENTS.md index f9985b5b..7c801522 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -122,7 +122,7 @@ UniDesk 是一个以主 server 为统一入口的分布式工作平台；本文 - P0: 对 GitHub issue/PR 做正式写入时必须优先使用 `bun scripts/cli.ts gh ...`；禁止用原生 `gh issue edit/create/comment` 直接写 UniDesk/HWLAB 长期看板、指挥简报或用户反馈 issue。事故和 CLI 补强需求见 [pikasTech/unidesk#142](https://github.com/pikasTech/unidesk/issues/142)。 - P0: GitHub PR/issue 读写、PR 合并、评论、状态观察和收口动作必须走 UniDesk `gh` 子命令；禁止绕过为原生 `gh`、手写 `curl`/GraphQL/REST 请求或临时脚本直连 GitHub。若 `bun scripts/cli.ts gh ...` 不顺手、字段不够、merge 不支持或可见性不足，必须先改进 UniDesk `gh` 子命令并用它完成任务，不能跳过该入口。 -- #20、HWLAB #7 和指挥简报类正文不得使用原生 `gh issue edit --body-file -`、手写 GitHub API 或无 guard 的整篇替换；需要管道化写入时使用 UniDesk `gh issue update|comment create --body-file -`，由 CLI 读取 stdin、执行 body guard、自动读取当前 issue 元数据并输出 old/new body SHA。 +- #20、HWLAB #7 和指挥简报类正文不得使用原生 `gh issue edit --body-file -`、手写 GitHub API 或无 guard 的整篇替换；需要多行写入时优先使用 UniDesk `gh issue update|comment create --body-stdin <<'EOF'` 形式，由 CLI 读取 heredoc/stdin、执行 body guard、自动读取当前 issue 元数据并输出 old/new body SHA；`--body-file` 只作为复用已有文件的兼容入口。 - 长任务和跨回合排障应把专题 issue 评论区作为进展锚点；调查、计划、rollout、阻塞、复测 trace 和最终验收结论都追加到同一个 issue 评论中，细则见 `docs/reference/code-queue-supervision.md`。 ## Critical Git / Multi-Repo Sync Rule @@ -213,7 +213,7 @@ UniDesk 是一个以主 server 为统一入口的分布式工作平台；本文 - `bun scripts/cli.ts dev-env validate [--manifest path] [--kubectl-dry-run]` / `dev-env prewarm-images`：离线校验 D601 `unidesk-dev` 生产隔离护栏和 dev workload manifests，或把开发底座基础镜像预热到 D601 原生 k3s containerd，规则见 `docs/reference/deploy.md` 与 `docs/reference/microservices.md`。 - `bun scripts/cli.ts artifact-registry plan|render|status|health|install|deploy-backend-core|deploy-service`：管理 D601 host-managed CNCF Distribution registry，并通过短生命周期 relay 或 D601 pull/import 做 commit-pinned pull-only artifact CD；`deploy-backend-core` 是 deprecated 兼容名，`findjob`/`pipeline` 支持 D601 direct dev/prod，`met-nonlinear` 和 `k3sctl-adapter` 只给受限计划路径，`code-queue` 只支持 dev，规则见 `docs/reference/artifact-registry.md`。 - `bun scripts/cli.ts auth-broker contract|health --dry-run|credential-request --dry-run|pr-preflight --dry-run`：查看 Auth Broker P0 Rust skeleton 与 CLI adapter contract，runner 无 `GH_TOKEN`/`GITHUB_TOKEN` 时返回结构化 `auth-missing`/`broker-needed`，不读取或打印 token 值，规则见 `docs/reference/auth-broker.md`。 -- `bun scripts/cli.ts gh preflight|auth status|issue ...|pr list|files|diff --stat|read|view|preflight|closeout|create|edit|update|comment|merge` / `bun scripts/code-queue-pr-preflight-example.ts`：通过 REST 执行安全 GitHub issue 读写、分页 issue list、inactive issue stale-close、脱敏 auth/status 诊断、body-file Markdown 写入、当日滚动简报时间线 ClaudeQQ 通知、escape 扫描、只读 cleanup-plan 和 #20 board-audit、PR changed-file/stat summary、PR 创建/评论 dry-run、REST-only 低噪声 PR title/body 编辑、PR 收口元数据观察（含 merged/closed 区分与 merge commit）、低噪声 PR 收口 preflight、guarded PR merge 与 runner PR preflight；`gh issue/pr read|view` 支持 `owner/repo#number` shorthand，`--raw|--full` 是显式完整披露别名，`gh pr diff` 仅支持 `--stat` 紧凑 JSON，`gh pr merge` 会先执行 closeout 预检并拒绝非 open、draft、冲突、非 CLEAN、失败或 pending checks 的 PR，规则见 `docs/reference/cli.md` 和 `docs/reference/code-queue-supervision.md`。 +- `bun scripts/cli.ts gh preflight|auth status|issue ...|pr list|files|diff --stat|read|view|preflight|closeout|create|edit|update|comment|merge` / `bun scripts/code-queue-pr-preflight-example.ts`：通过 REST 执行安全 GitHub issue 读写、分页 issue list、inactive issue stale-close、脱敏 auth/status 诊断、heredoc/stdin Markdown 写入、当日滚动简报时间线 ClaudeQQ 通知、escape 扫描、只读 cleanup-plan 和 #20 board-audit、PR changed-file/stat summary、PR 创建/评论 dry-run、REST-only 低噪声 PR title/body 编辑、PR 收口元数据观察（含 merged/closed 区分与 merge commit）、低噪声 PR 收口 preflight、guarded PR merge 与 runner PR preflight；`gh issue/pr read|view` 支持 `owner/repo#number` shorthand，`--raw|--full` 是显式完整披露别名，`gh pr diff` 仅支持 `--stat` 紧凑 JSON，`gh pr merge` 会先执行 closeout 预检并拒绝非 open、draft、冲突、非 CLEAN、失败或 pending checks 的 PR，规则见 `docs/reference/cli.md` 和 `docs/reference/code-queue-supervision.md`。 - `bun scripts/cli.ts commander contract|plan --dry-run|smoke --dry-run|approval request --dry-run|prompt-lint --kind gpt55-pr`：查看 host Codex 指挥官直管微服务 skeleton 的 source/contract、无 daemon smoke 验证计划、.state/commander/ 状态模型、trace summary 聚合、ClaudeQQ 高风险请示草案和 GPT-5.5 PR prompt 边界辅助 lint；当前只返回 dry-run 计划和 backend-core `microservice proxy claudeqq` 授权后候选命令，不接 live bridge、不接管人工指挥官，不发送消息，`prompt-lint` 不作为业务 PR 门禁也不改变 `codex submit` 默认行为，规则见 `docs/reference/host-codex-commander.md`。 - `bun scripts/cli.ts hwlab g14 monitor-prs [--lane g14|v02]`：一行启动异步监控 HWLAB PR；默认 base=G14 合并后滚动 G14 DEV 并写每日简报，`--lane v02` 监控 base=v0.2，CI/preflight 通过后自动合并、触发 v0.2 CD，并在 PR 下评论 pending/冲突/成功/失败/超时状态，规则见 `docs/reference/g14.md` 与 `docs/reference/cli.md`。 - `bun scripts/cli.ts agentrun v01 control-plane status|trigger-current [--dry-run|--confirm]`：通过 G14 route 只读观察或手动触发 AgentRun `v0.1` commit-pinned Tekton/Argo PipelineRun，规则见 `docs/reference/agentrun.md` 与 `docs/reference/cli.md`。 diff --git a/docs/reference/cli.md b/docs/reference/cli.md index ac3a083f..66826eb3 100644 --- a/docs/reference/cli.md +++ b/docs/reference/cli.md @@ -47,7 +47,7 @@ CI/CD、GitOps、rollout、artifact 发布、PR 合并后的 DEV/PROD 滚动、P - `artifact-registry plan|render|status|health|install|deploy-backend-core|deploy-service` 管理 D601 host-managed CNCF Distribution registry 的声明、安装、只读检查和 pull-only artifact CD。该 registry 固定为 D601 loopback `127.0.0.1:5000`，由 systemd + Docker Compose 管理，位于 native k3s 故障域外；`deploy-service` 只拉取 CI 已发布的 commit-pinned 镜像、retag/recreate 或导入 native k3s，并做 live commit 验证，不构建 runtime source。`deploy-backend-core` 是 deprecated 兼容名，标准 backend-core prod CD 入口是 `deploy apply --env prod --service backend-core`。长期规则见 `docs/reference/artifact-registry.md`。 - `commander contract|plan --dry-run|smoke --dry-run|approval request --dry-run|prompt-lint --kind gpt55-pr` 是 host Codex 指挥官直管微服务 skeleton 入口。当前命令返回 `phase=source-contract`、service/API/state/bridge/prompt/trace/#20/#46/ClaudeQQ 审批边界、.state/commander/ 状态模型、dev 无 daemon smoke contract、dry-run 计划和 GPT-5.5 PR prompt 边界辅助 lint，不接 live bridge、不注入 prompt、不发送 ClaudeQQ。`approval request --dry-run` 会生成 200 字以内中文纯文本 ClaudeQQ 审批草案、`notification-path-unavailable` blocker 和授权后唯一可用的 `bun scripts/cli.ts microservice proxy claudeqq /api/push/text --method POST --body-json '' --raw` 命令；不得提示使用本机 ClaudeQQ skill、powershell 或本地 server。`prompt-lint` 支持 `--prompt-file` 与 `--stdin`，输出 `ok`、`missingClauses`、`riskLevel`、`suggestedPatchSnippet` 且不回显完整 prompt；它是 commander 辅助检查，不是业务 PR 门禁，也不改变 `codex submit` 默认行为。`plan`、`smoke` 与 `approval request` 必须带 `--dry-run`；缺少时返回 `error=dry-run-required`。长期规则见 `docs/reference/host-codex-commander.md`。 - `hwlab g14 monitor-prs [--lane g14|v02] [--once] [--dry-run] [--interval-seconds N] [--max-cycles N] [--timeout-seconds N]` 是当前 HWLAB G14 PR -> CI/CD -> DEV rollout 的一行式入口。普通调用创建 `.state/jobs/` 异步 job 并立刻返回 `job.id`、`statusCommand` 和 stdout/stderr 路径；后台 worker 每轮通过 UniDesk `gh pr list/preflight/merge` 监控 `pikasTech/HWLAB` base=`G14` 的 open PR，ready 时合并，然后通过 UniDesk `trans G14:k3s` 观察 `hwlab-g14-ci-poll-`、Argo `hwlab-g14-dev` 和 DEV `/health/live`，直到 DEV `Synced/Healthy` 且 Deployment/StatefulSet ready；历史 `Completed` smoke/debug pod 不作为 rollout blocker。每次成功 DEV rollout 后，worker 会定位或创建 #7“指挥简报索引”中的北京日期每日简报 issue，并追加 CI/CD 耗时、CI/CD 关键指标、语义化上线 changelog、自动 diff 摘要、PipelineRun、GitOps revision 和 DEV 验证摘要；关键指标来自 G14 Tekton TaskRun results，固定包含 `lazy build reused: x/y`、reused services、rebuild services 和每个 service 的独立耗时/状态/backend，用于观察 lazy build 机制效果。语义化 changelog 优先从 PR body 的 `## 修改`/`## 变更`/`## Changelog` 等段落提取，diff 摘要只作为文件和统计证据保留，不替代 changelog。也可用 `hwlab g14 record-rollout --pr --source-commit ` 手动补记，手动补记同样会按 PipelineRun 采集 TaskRun 指标。G14 状态指针按用途分离：长期监控只写 `.state/hwlab-g14/latest-monitor-job.json`，`--once` 写 `latest-once-job.json`，`--dry-run` 写 `latest-dry-run-job.json`，`--once --dry-run` 写 `latest-once-dry-run-job.json`，避免一次性收口覆盖持续监控入口。`--once --dry-run` 只做单轮监控和 merge plan，不写 GitHub、不等待 rollout。该命令禁止使用原生 `gh` 或手拼 GitHub 请求；如果 UniDesk `gh` 子命令字段或行为不够，必须先改进 `scripts/src/gh.ts` 后再使用。 -- `hwlab g14 monitor-prs --lane v02` 是 HWLAB `v0.2` 的 PR -> CI -> CD 自动化入口。它只监控 base=`v0.2` 的 open PR：每轮先用 UniDesk `gh pr preflight` 读取 GitHub CI/checks、mergeability 和冲突状态；pending 时在 PR 下写等待评论，blocked/conflict 时写阻塞评论；ready 时直接用 UniDesk `gh pr merge` 合并，不因为其他 commit 的运行中 PipelineRun 阻塞 merge 或 CI 启动。合并后执行受控 `control-plane trigger-current --lane v02 --confirm --wait`、轮询定点 `control-plane status --lane v02 --source-commit `，必要时执行 `git-mirror flush --confirm --wait`。v0.2 CD 采用 latest-only：旧 PipelineRun 不取消、不等待，但 promotion 写 `v0.2-gitops` 前必须重新确认 source head，stale commit 只能以 superseded/no-op 收口，不能回滚 runtime。不管 CD 成功、superseded、失败或超时，都在原 PR 下用 `gh pr comment create --body-file` 追加语义化状态，正文固定包含起止时间、总耗时、冲突状态、CI/preflight conclusion、source commit、PipelineRun、targetValidation、Argo/webAssets 和 git mirror pendingFlush/githubInSync。评论去重状态写入 `.state/hwlab-g14/v02-pr-comment-signatures.json`，同一状态签名不会重复刷评论；v0.2 monitor 指针使用 `.state/hwlab-g14/latest-v02-monitor-job.json`、`latest-v02-once-job.json`、`latest-v02-dry-run-job.json` 和 `latest-v02-once-dry-run-job.json`，不会覆盖默认 G14 monitor 指针。`--lane v02 --once --dry-run` 只做单轮 preflight/merge/CD/comment plan，不写 GitHub、不触发 CD。 +- `hwlab g14 monitor-prs --lane v02` 是 HWLAB `v0.2` 的 PR -> CI -> CD 自动化入口。它只监控 base=`v0.2` 的 open PR：每轮先用 UniDesk `gh pr preflight` 读取 GitHub CI/checks、mergeability 和冲突状态；pending 时在 PR 下写等待评论，blocked/conflict 时写阻塞评论；ready 时直接用 UniDesk `gh pr merge` 合并，不因为其他 commit 的运行中 PipelineRun 阻塞 merge 或 CI 启动。合并后执行受控 `control-plane trigger-current --lane v02 --confirm --wait`、轮询定点 `control-plane status --lane v02 --source-commit `，必要时执行 `git-mirror flush --confirm --wait`。v0.2 CD 采用 latest-only：旧 PipelineRun 不取消、不等待，但 promotion 写 `v0.2-gitops` 前必须重新确认 source head，stale commit 只能以 superseded/no-op 收口，不能回滚 runtime。不管 CD 成功、superseded、失败或超时，都在原 PR 下用 `gh pr comment create --body-stdin <<'EOF'` 追加语义化状态，正文固定包含起止时间、总耗时、冲突状态、CI/preflight conclusion、source commit、PipelineRun、targetValidation、Argo/webAssets 和 git mirror pendingFlush/githubInSync。评论去重状态写入 `.state/hwlab-g14/v02-pr-comment-signatures.json`，同一状态签名不会重复刷评论；v0.2 monitor 指针使用 `.state/hwlab-g14/latest-v02-monitor-job.json`、`latest-v02-once-job.json`、`latest-v02-dry-run-job.json` 和 `latest-v02-once-dry-run-job.json`，不会覆盖默认 G14 monitor 指针。`--lane v02 --once --dry-run` 只做单轮 preflight/merge/CD/comment plan，不写 GitHub、不触发 CD。 - `agentrun v01 control-plane status|trigger-current|refresh [--dry-run|--confirm]` 是 AgentRun `v0.1` 在 G14 k3s 的受控 Tekton/Argo 入口。`status` 只读汇总固定 source worktree commit、对应 commit-pinned PipelineRun、GitOps latest、Argo Application、`agentrun-v01` manager source commit、`planArtifacts.summary`、env image result 和 git mirror 摘要，并报告 manager/Argo/GitOps 是否对齐当前 source commit。默认输出是 compact commander 视图：`summary` 给出 source、PipelineRun、Argo、manager image、git mirror 和 `aligned` 结论；`timings` 给出 `sourceMs`、`runtimeMs`、`gitMirrorMs` 和 `totalMs`；远端 stdout/stderr tail 默认省略，失败时仍展开必要 tail，完整 tail 用 `--full`，原始 git mirror cache 用 `--raw`。`status` 聚合 source 后会并行读取 runtime 和 git mirror，并向 stderr 输出 `agentrun.control-plane.status.progress` JSON 事件，覆盖 `source`、`runtime`、`git-mirror` 的 started/succeeded/failed 和 elapsedMs，避免 10s 以上状态聚合期间无可见进展；`trigger-current` 先快进 `G14:/root/agentrun-v01` 到 `origin/v0.1`，检查 `devops-infra` mirror 的 `localV01` 是否等于目标 source commit，必要时先执行受控 mirror sync，再创建 `agentrun-v01-ci-` PipelineRun。confirmed trigger 只提交 CI/CD 工作并返回后续 `status` 命令，不等待完整 PipelineRun；同名 PipelineRun 运行中或已成功时拒绝重复触发，只允许失败态重建或首次创建。`refresh` 只对 `argocd/agentrun-g14-v01` 执行 hard refresh，用于 GitOps promotion 已完成但 Argo 仍停留旧 revision 时的受控同步入口；它不直接 patch runtime workload。AgentRun 运行时和 SPEC 事实来源仍在 AgentRun 仓库，UniDesk 只维护受控运维入口。 - `agentrun v01 git-mirror status|sync|flush [--dry-run|--confirm]` 是 AgentRun `v0.1` 使用 `devops-infra` git mirror/relay 的受控维护入口。`status` 默认返回 read/write URL、`localV01`、`githubV01`、`localGitops`、`githubGitops`、`pendingFlush`、`githubInSync` 和 exact full-SHA shallow fetch 摘要，不默认展开完整 cache stdout；需要探测 tail 时用 `--full`，需要原始 cache 输出时用 `--raw`。`sync` 创建 manual Job，把 GitHub `v0.1` 和 `v0.1-gitops` refs 拉入 `/cache/pikasTech/agentrun.git`；`flush` 把本地 `v0.1-gitops` 快进推回 GitHub。confirmed `sync`/`flush` 默认创建 `.state/jobs/` 异步 job 并立刻返回 `job.id`、`statusCommand` 和日志路径；只有现场同步调试才显式加 `--wait`。该入口与 HWLAB v0.2 mirror 共用 `devops-infra` 服务和 cache PVC，但 repo path、refs、status 文件和 CLI 命令彼此独立。 - `hwlab g14 control-plane status|apply --lane v02 [--dry-run|--confirm]` 是 HWLAB `v0.2` 加法 lane 的受控 Tekton/Argo 控制面维护入口，source commit 只来自 G14 专用 bare repo `/root/hwlab-v02-cicd.git` 的 `refs/remotes/origin/v0.2`；`/root/hwlab-v02` 只作为人工开发和短连接源码工具 workspace 被观测，dirty/stale 状态必须输出为 isolated warning 而不能阻塞 CI/CD。该入口面向 branch `v0.2`、namespace `hwlab-ci` 和 Argo application `hwlab-g14-v02`；默认 `status` 只读汇总最新 source head 的 pipeline、RBAC/ServiceAccount、Argo、当前 commit PipelineRun、当前 PipelineRun 的 TaskRun 条件摘要、最近 PipelineRun 摘要、活跃 PipelineRun、遗留 v02 CronJob 清理状态、commit alignment，以及 19666/19667 的 Cloud Web 静态资源和 API live 探针。分支被后续提交推进后，要复查已完成 run 时使用 `status --lane v02 --pipeline-run hwlab-v02-ci-poll-`；已知完整 source SHA 但不想依赖最新 head 时使用 `status --lane v02 --source-commit `。定点 `status` 输出 `statusTarget.mode` 和 `targetValidation`，只检查指定 PipelineRun/source commit 的证据；`targetValidation.state=passed` 表示该目标已满足 PipelineRun succeeded、Argo `Synced/Healthy`、19666/19667 探针、Git mirror flushed，并且该 run 的 `planArtifacts.rolloutServices` 运行时 source commit 对齐；`planArtifacts.reusedServices` 作为 runtime/provenance 证据呈现，但不能被强制要求等于目标 source commit。`targetValidation.state=superseded` 表示该目标已成功且 runtime 已被同一分支后续成功 PipelineRun 取代，`falseGreenGuard` 在该状态下应标为 superseded/not-applicable。两种状态都不得因为 `origin/v0.2` 后续推进而把历史 run 判为失败；默认不带定点参数时仍严格判定最新 source head alignment。TaskRun 摘要的 `performance` 字段会把超过 120s 的 build TaskRun 标为慢任务、超过 180s 标为 critical warning，用于暴露 env reuse/git mirror 命中率回归，但不作为阻断门禁；CI/CD 性能验收应同时看 `planArtifacts.summary`、`taskRuns.performance.warningCount` 和 PipelineRun duration，纯 CLI/文档或无 runtime 重建需求的后续提交应稳定表现为 `build=0 reuse=` 且无 build TaskRun warning，首次引入或切换 env image 时允许只构建必要 env image 一次。`webAssets` 必须直接给出 `readonly-rpc` 删除、sidebar/workspace/event panel 关键 CSS、`/app.js` 是否可读取和字节数、`/health/live` 与 API revision；`apiRevision` 是 cloud-api 服务自身 revision，Cloud Web 静态资源变更时允许它与 source commit 不同，不能把这种差异误判成 Cloud Web 未发布。默认只读取必要字段，禁止把完整 PipelineRun spec、Tekton 内联脚本、历史大对象或整份 CSS/HTML/JS 展开到默认输出；`apply` 先自动 fetch `/root/hwlab-v02-cicd.git` 并从 commit-pinned detached worktree 执行 render check，再经 `G14:k3s` server-side apply `tekton-v02/rbac.yaml`、`pipeline.yaml`、`argocd/project.yaml` 和 `argocd/application-v02.yaml`，confirmed apply 会删除遗留 v02 CronJob，但不会应用 runtime-v02 workload、Secret 或数据迁移。 @@ -67,20 +67,20 @@ CI/CD、GitOps、rollout、artifact 发布、PR 合并后的 DEV/PROD 滚动、P - `gh auth status [--repo owner/name]` 探测 GitHub 操作前置条件并输出脱敏 JSON：是否存在 `gh` binary、是否存在 `GH_TOKEN`/`GITHUB_TOKEN` 或可用 `gh auth token` fallback、REST API 是否可达、目标 repo 是否可见、issue 是否可读。degraded reason 必须归类为 `missing-binary`、`missing-token`、`auth-failed`、`github-transient`、`network-proxy-failed`、`permission-denied`、`repo-not-found`、`repo-forbidden`、`issue-not-found`、`pr-not-found`、`scope-insufficient`、`validation-failed`、`invalid-response` 或 `unsupported-command`，不得打印 token；失败对象必须包含 `runnerDisposition=infra-blocked|business-failed`，runner 应优先用该字段分流。`github-transient` 表示 GitHub DNS/API 连接在收到 HTTP 状态前失败，输出应带 `retryable=true` 或等价 commander action；这不是缺 token、认证失败、权限不足或 PR 语义失败。 - `codex prompt-lint [prompt|--prompt-file path|--prompt-stdin]` 是派发/steer 前的本地 dry-run prompt lint。它只读取 prompt 文本，返回 `dryRun=true`、`mutation=false`、`declaredClass`、`effectiveClass`、`requiredClass`、`dispatchDisposition`、缺失或矛盾项和有界 evidence，不访问 live service、不提交任务、不打印完整 prompt。分级固定为 `read-only`、`live-read`、`live-mutating`；未声明时按 `read-only` 处理。`codex submit --dry-run` 与 `codex steer --dry-run` 会嵌入同一 `promptLint` 结果，帮助指挥官在 dispatch/steer 前发现缺失或矛盾的 live mutation 授权。长期规则见 `docs/reference/code-queue-supervision.md` 的 DEV 测试授权分级。 - `gh issue list [owner/repo] [--state open|closed|all] [--limit N] [--search text] [--label label[,label...]]... [--repo owner/name] [--json number,title,state,url,updatedAt,createdAt,author,labels] [--raw|--full]` 通过 GitHub REST 列出 issue，默认 `state=open`、`limit=30`，输出稳定 JSON 且不依赖系统 `gh` binary。`owner/repo` 位置参数是 `--repo owner/repo` 的兼容别名；若位置 repo 与 `--repo` 冲突，或位置参数不是 `owner/repo`，必须结构化失败，禁止静默 fallback 到默认 repo。`--limit` 是 CLI 返回上限，不等同 GitHub 单页 `per_page`：当 `--limit > 100` 或默认页中混入 PR 时，CLI 必须分页抓取 GitHub REST/Search page，过滤 PR 后再返回 issue，并在输出中披露 `pagination.fetchedPages/rawCount/hasMore`；`hasMore=true` 时只能说明当前有界扫描未穷尽，禁止把它当作“仓库没有更多 issue”。`--search` 使用 GitHub Search Issues API，并自动追加 `repo:/`、`type:issue` 和 state qualifier，用于创建新 issue 前做低摩擦查重；未知 state 或未知 `--json` 字段必须结构化失败并带 `runnerDisposition=business-failed`。`--label` 是 GitHub REST `labels=label1,label2` 或 Search `label:` 服务端过滤，支持重复 `--label` 和逗号分隔；filter 不在本命令上下文中使用（如 `issue read`、`pr list`）必须结构化失败并指明 `gh issue create/list/stale-close` 才是合法作用域。GitHub issues API 可能混入 PR，CLI 会从 `.data.issues` 中过滤 pull request。`--raw|--full` 在 `gh issue list` 上是绕过 20 KiB stdout 截断的显式开关：响应结果会带 `noDump=true`，`output.ts` 据此跳过 head/tail 替换并把完整数据 inline 输出；当响应未超阈值时 `--raw|--full` 行为等价默认。 -- `gh issue lifecycle`：`--state` 只能作为 `gh issue list` / `gh issue board-row list` / `gh pr list` 的过滤参数；`gh issue update` / `gh issue edit` 只写 body/title，**不接受** `--state` 改 open/closed。把 `gh issue update --state closed` 落到错命令上时，CLI 必须返回 `validation-failed` 并显式提示 `gh issue close ` / `gh issue reopen `（PR 用 `gh pr close|reopen `），并把 5 条受支持命令放进 `supportedCommands`，禁止把"无 `--state` 改 issue 状态"的命令升级为"接受 `--state`"。`gh issue close|reopen` 成功输出默认是 compact issue 摘要，不得回显完整 `issue.body`；需要正文时后续使用返回的 `readCommands` 或 `gh issue view --json body|--full|--raw`。生命周期 close/reopen 的评论只接受短 `--comment`（或无评论），不接受 `--comment-file` 或 `--body-file`；需要附长篇 CLI 验收证据时，先用 `gh issue comment create --body-file ` 写证据评论，再用 `gh issue close --comment <短引用>` 关闭。issue 硬删除走 `close`，PR 硬删除走 `close`，两者都没有"delete"语义。 -- `gh issue comment create --repo owner/name|--body-file `、`gh issue comment delete --repo owner/name`、`gh issue close --repo owner/name [--comment ]`、`gh issue reopen --repo owner/name [--comment ]`、`gh issue update --repo owner/name [--title ...] [--body-file ]`、`gh issue edit ...`、`gh issue board-row get|update|add|move|delete|upsert --repo owner/name ...` 都接受与 `gh issue view|read`、`gh pr *` 一致的 `owner/repo#number` 位置 shorthand；shorthand 与显式 `--repo` 冲突时结构化失败并把两者都回显到错误对象里，避免静默改写目标 repo。`gh issue view|read`、`gh pr view|read|files|diff|preflight|closeout|comment create|comment delete|close|reopen|merge|edit|update` 已长期支持该 shorthand，issue 写命令对齐后整个 `gh` 子命令在 shorthand 行为上保持一致，不再需要把 `pikasTech/HWLAB#621` 拆成 `621 --repo pikasTech/HWLAB`。来源：HWLAB #621 CLI 验收 `gh issue comment create pikasTech/HWLAB#621` 摩擦改进。 +- `gh issue lifecycle`：`--state` 只能作为 `gh issue list` / `gh issue board-row list` / `gh pr list` 的过滤参数；`gh issue update` / `gh issue edit` 只写 body/title，**不接受** `--state` 改 open/closed。把 `gh issue update --state closed` 落到错命令上时，CLI 必须返回 `validation-failed` 并显式提示 `gh issue close ` / `gh issue reopen `（PR 用 `gh pr close|reopen `），并把 5 条受支持命令放进 `supportedCommands`，禁止把"无 `--state` 改 issue 状态"的命令升级为"接受 `--state`"。`gh issue close|reopen` 成功输出默认是 compact issue 摘要，不得回显完整 `issue.body`；需要正文时后续使用返回的 `readCommands` 或 `gh issue view --json body|--full|--raw`。生命周期 close/reopen 的评论推荐用 `--comment-stdin <<'EOF'` 直接写 heredoc/stdin；短单行可用 `--comment`，已有复用文件才用 `--comment-file`。需要附长篇 CLI 验收证据时，先用 `gh issue comment create --body-stdin <<'EOF'` 写证据评论，再用 `gh issue close --comment <短引用>` 关闭。issue 硬删除走 `close`，PR 硬删除走 `close`，两者都没有"delete"语义。 +- `gh issue comment create --repo owner/name --body-stdin`、`gh issue comment delete --repo owner/name`、`gh issue close --repo owner/name [--comment |--comment-stdin]`、`gh issue reopen --repo owner/name [--comment |--comment-stdin]`、`gh issue update --repo owner/name [--title ...] [--body-stdin]`、`gh issue edit ...`、`gh issue board-row get|update|add|move|delete|upsert --repo owner/name ...` 都接受与 `gh issue view|read`、`gh pr *` 一致的 `owner/repo#number` 位置 shorthand；shorthand 与显式 `--repo` 冲突时结构化失败并把两者都回显到错误对象里，避免静默改写目标 repo。`gh issue view|read`、`gh pr view|read|files|diff|preflight|closeout|comment create|comment delete|close|reopen|merge|edit|update` 已长期支持该 shorthand，issue 写命令对齐后整个 `gh` 子命令在 shorthand 行为上保持一致，不再需要把 `pikasTech/HWLAB#621` 拆成 `621 --repo pikasTech/HWLAB`。来源：HWLAB #621 CLI 验收 `gh issue comment create pikasTech/HWLAB#621` 摩擦改进。 - `gh issue stale-close [--repo owner/name] [--inactive-hours N] [--limit N] [--label label[,label...]]... [--dry-run]` 是可复用批量生命周期清理入口，用于“超过 N 小时无回复或修改的 open issue 一律关闭”这类策略。判定基准固定为 GitHub `updatedAt < observedAt - inactiveHours`，issue comment、body/title 修改和 state 变化都会刷新 `updatedAt` 并视为活跃；PR 必须过滤，不参与 issue 关闭。默认 `inactive-hours=48`，默认扫描预算为 issue list 上限，输出必须包含 `observedAt`、`cutoffAt`、`scannedCount`、`staleCount`、`pagination.hasMore`、候选/关闭 issue 的 compact 摘要和失败列表，不得打印完整正文。正式关闭前建议先跑 `--dry-run`；真实执行后用同一命令加 `--dry-run` 验证 `staleCount=0`，且只有 `hasMore=false` 才能把当前扫描视为完整穷尽。HWLAB 当前长期策略使用 `bun scripts/cli.ts gh issue stale-close --repo pikasTech/HWLAB --inactive-hours 48 --dry-run` 观察，再移除 `--dry-run` 关闭。 -- `gh issue view [--repo owner/name] [--json body,title,state,comments] [--raw|--full]` 通过 GitHub REST 读取 issue title/body/state/url 和 comments，默认输出 JSON；`read` 只保留为 UniDesk 兼容别名。`view` 对齐 GitHub CLI 标准位置参数：接受正整数、`https://github.com/owner/repo/issues/` URL 或 `owner/repo#number` shorthand。`--number N` 也作为低摩擦兼容别名用于单 issue/comment 数字目标命令，并在成功响应里返回 `standardSyntaxHint` 提示标准位置参数写法；comment delete 中的 `--number` 表示 commentId，不是 issue number；`list/create/scan-escape/cleanup-plan/board-audit/board-row list` 这类没有单数字目标的命令仍拒绝 `--number`。URL 和 shorthand 会自动派生 `--repo owner/repo` 与 issue number；若同时提供冲突的显式 `--repo`，CLI 必须结构化失败并给出 `gh issue view --repo owner/repo --json body,title,state,comments` 与 shorthand raw 的可执行命令。兼容旧脚本的 `--json body` 和 `--json body,title,state,comments` 字段选择，且正文仍稳定暴露在 `.data.issue.body`，避免调用方因为 JSON 路径变化把空值当成正文。字段白名单是 `body,title,state,comments,number,url,author,createdAt,updatedAt`，未知字段必须结构化失败并带 `runnerDisposition=business-failed`。`--raw` 与 `--full` 是显式完整披露别名：view/read 会选择完整支持字段集；issue update/edit 只有显式传入时才在成功响应里包含完整 `.data.issue.body`。当最终 `gh` JSON 超过 20 KiB 时，CLI 必须把完整 JSON 写入 `/tmp/unidesk-cli-output/*.json`，stdout 只返回 `outputTruncated=true`、dump path、总 bytes/lines 和 head/tail 预览。默认 list/view 输出仍不得扩散到无界非 JSON 文本。`gh issue create --title --body-file <file|-> [--label label[,label...]]... [--dry-run]`、`gh issue update <number> --mode replace|append --body-file <file|-> [--title ...] [--dry-run] [--full|--raw]`、`gh issue comment create <number> (--body-file <file|->|--body <short-text>) [--dry-run]`、`gh issue comment delete <commentId> [--dry-run]`、`gh issue close|reopen <number> [--comment <short-text>] [--dry-run]`、`gh issue stale-close [--inactive-hours N] [--dry-run]` 都走 REST，不依赖 `gh` binary。`--body` 仅用于 issue comment 的短单行文本；空白、多行、疑似 shell 污染、secret-like 或过长 inline body 必须结构化失败，Markdown/生成内容/长评论继续用 `--body-file <file|->`。`--label` 用于 `issue create`、`issue list` 和 `issue stale-close`，支持重复传入和逗号分隔；`issue create --dry-run` 会展示解析后的 labels 与 request plan，正式创建时把 labels 放入 GitHub REST create-issue payload，GitHub 返回不存在 label 等 422 校验失败时 CLI 结构化返回 `validation-failed`，不静默成功。`gh issue delete <number>` 是结构化 `unsupported-command`，因为 GitHub REST 不支持 issue 硬删除；生命周期删除语义请使用 `close`。 -- `gh issue update <number> --mode replace|append --body-file <file|->` 是正文更新主入口，`edit` 保留为兼容别名。`replace` 用文件或 stdin 正文替换现有 body；`append` 先读取当前 body，再按 UTF-8 文件或 stdin 字节追加，保留真实换行、反引号和 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，输出有界 `bodyPreview`/`bodyPreviewLines`、新正文长度、SHA、关键标题检查结果、字面量 `\n`、反引号、Markdown 表格、shell 污染信号、`guard`、`concurrency`、`bodyOnlySafety` 和 `wouldPatch`；若环境里有 `GH_TOKEN` 或 `GITHUB_TOKEN`，dry-run 还会只读抓取旧正文长度、SHA 和 `updatedAt` 作为更新前对照。正式写入默认先读取当前 issue，执行 guard 和显式 `--expect-*` 并发校验，再 PATCH；成功输出 compact issue 摘要、old/new body SHA、updatedAt、bodySource 和 drill-down `readCommands`，不包含完整 `issue.body`。完整正文必须显式 `--full|--raw` 或后续执行 `readCommands.body/full/raw` 获取。 +- `gh issue view <number|url|owner/repo#number> [--repo owner/name] [--json body,title,state,comments] [--raw|--full]` 通过 GitHub REST 读取 issue title/body/state/url 和 comments，默认输出 JSON；`read` 只保留为 UniDesk 兼容别名。`view` 对齐 GitHub CLI 标准位置参数：接受正整数、`https://github.com/owner/repo/issues/<number>` URL 或 `owner/repo#number` shorthand。`--number N` 也作为低摩擦兼容别名用于单 issue/comment 数字目标命令，并在成功响应里返回 `standardSyntaxHint` 提示标准位置参数写法；comment delete 中的 `--number` 表示 commentId，不是 issue number；`list/create/scan-escape/cleanup-plan/board-audit/board-row list` 这类没有单数字目标的命令仍拒绝 `--number`。URL 和 shorthand 会自动派生 `--repo owner/repo` 与 issue number；若同时提供冲突的显式 `--repo`，CLI 必须结构化失败并给出 `gh issue view <number> --repo owner/repo --json body,title,state,comments` 与 shorthand raw 的可执行命令。兼容旧脚本的 `--json body` 和 `--json body,title,state,comments` 字段选择，且正文仍稳定暴露在 `.data.issue.body`，避免调用方因为 JSON 路径变化把空值当成正文。字段白名单是 `body,title,state,comments,number,url,author,createdAt,updatedAt`，未知字段必须结构化失败并带 `runnerDisposition=business-failed`。`--raw` 与 `--full` 是显式完整披露别名：view/read 会选择完整支持字段集；issue update/edit 只有显式传入时才在成功响应里包含完整 `.data.issue.body`。当最终 `gh` JSON 超过 20 KiB 时，CLI 必须把完整 JSON 写入 `/tmp/unidesk-cli-output/*.json`，stdout 只返回 `outputTruncated=true`、dump path、总 bytes/lines 和 head/tail 预览。默认 list/view 输出仍不得扩散到无界非 JSON 文本。`gh issue create --title <title> --body-stdin [--label label[,label...]]... [--dry-run]`、`gh issue update <number> --mode replace|append --body-stdin [--title ...] [--dry-run] [--full|--raw]`、`gh issue comment create <number> (--body-stdin|--body <short-text>) [--dry-run]`、`gh issue comment delete <commentId> [--dry-run]`、`gh issue close|reopen <number> [--comment <short-text>|--comment-stdin] [--dry-run]`、`gh issue stale-close [--inactive-hours N] [--dry-run]` 都走 REST，不依赖 `gh` binary。`--body-stdin` 和 `--comment-stdin` 是多行 Markdown 的第一等 heredoc/stdin 入口；`--body-file` / `--comment-file` 只在已有复用文件时使用。`--body` 仅用于 issue comment 的短单行文本；空白、多行、疑似 shell 污染、secret-like 或过长 inline body 必须结构化失败。`--label` 用于 `issue create`、`issue list` 和 `issue stale-close`，支持重复传入和逗号分隔；`issue create --dry-run` 会展示解析后的 labels 与 request plan，正式创建时把 labels 放入 GitHub REST create-issue payload，GitHub 返回不存在 label 等 422 校验失败时 CLI 结构化返回 `validation-failed`，不静默成功。`gh issue delete <number>` 是结构化 `unsupported-command`，因为 GitHub REST 不支持 issue 硬删除；生命周期删除语义请使用 `close`。 +- `gh issue update <number> --mode replace|append --body-stdin` 是正文更新主入口，`edit` 保留为兼容别名。`replace` 用 heredoc/stdin 正文替换现有 body；`append` 先读取当前 body，再按 UTF-8 stdin 字节追加，保留真实换行、反引号和 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，输出有界 `bodyPreview`/`bodyPreviewLines`、新正文长度、SHA、关键标题检查结果、字面量 `\n`、反引号、Markdown 表格、shell 污染信号、`guard`、`concurrency`、`bodyOnlySafety` 和 `wouldPatch`；若环境里有 `GH_TOKEN` 或 `GITHUB_TOKEN`，dry-run 还会只读抓取旧正文长度、SHA 和 `updatedAt` 作为更新前对照。正式写入默认先读取当前 issue，执行 guard 和显式 `--expect-*` 并发校验，再 PATCH；成功输出 compact issue 摘要、old/new body SHA、updatedAt、bodySource 和 drill-down `readCommands`，不包含完整 `issue.body`。完整正文必须显式 `--full|--raw` 或后续执行 `readCommands.body/full/raw` 获取。 - #20 只允许承担长期 UniDesk 指挥官 / Code Queue / CLI / infra 治理总看板职责；每日进展必须写入当天滚动指挥简报 issue，并由 #20 顶部“指挥简报索引”引用。HWLAB 用户反馈、Cloud Workbench、DEV-LIVE、M3 虚拟硬件可信闭环等产品 issue 必须写到 `pikasTech/HWLAB`；#20 只可记录 UniDesk 侧 commander/Code Queue/CLI/infra 支撑工作。`gh issue view/read 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：...` 这类简报段落；把 `pikasTech/HWLAB#N`、`HWLAB#N` 或 HWLAB 产品/live 验证行写入 #20 时只返回 warning 和 `codeQueueBoardHint`，不再拒绝正文 replace，以避免历史正文或治理交叉引用造成次生阻塞；`gh issue board-row list|get|update|add|move|delete|upsert --board-issue 20` 也会返回同一 hint，提醒不要把每日简报或 HWLAB 产品看板混入 #20。 -- `gh issue edit 24 --body-file <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 <number> --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_BASE_URL` 只接受 backend-core `/api/microservices/claudeqq/proxy` 等价路径，非 proxy URL 会结构化为 `notification-path-unavailable`。可用 `UNIDESK_COMMANDER_BRIEF_CLAUDEQQ_ENABLED`、`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 edit 24 --body-stdin --notify-claudeqq-brief-diff [--dry-run] <<'EOF'` 是 legacy #24 指挥简报的通知入口。正式执行会先读取 GitHub 上 #24 旧正文并通过 #24 body profile guard，再从 heredoc/stdin 读取新正文；随后先 PATCH issue 主体，再把本次新增的 `## 更新 YYYY-MM-DD HH:MM 北京时间` 段落发送给 ClaudeQQ，ClaudeQQ 失败不会回滚 issue 正文，失败只体现在返回 JSON 的 `claudeqq.ok=false` 和结构化 `degradedReason`。每日滚动简报 issue 可用普通 `gh issue update <number> --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_BASE_URL` 只接受 backend-core `/api/microservices/claudeqq/proxy` 等价路径，非 proxy URL 会结构化为 `notification-path-unavailable`。可用 `UNIDESK_COMMANDER_BRIEF_CLAUDEQQ_ENABLED`、`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]` 是总看板只读结构审计入口，默认 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 <issueNumber> --board-issue 20` 和 `gh issue board-row update <issueNumber> --board-issue 20 --field progress|status|validation|branch|tasks|focus --value <text> [--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 <issueNumber> --board-issue 20 --section open|closed [--category text] --branch <branch> --tasks <task> --summary <text> --focus <text> --validation <text> --progress <text> [--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 <issueNumber> --board-issue 20 --section open|closed --row-file <file> [--dry-run] [--expect-body-sha|--expect-updated-at]`、`move <issueNumber> --board-issue 20 --to open|closed [--status OPEN|CLOSED] [--dry-run] [--expect-body-sha|--expect-updated-at]` 和 `delete <issueNumber> --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 ...] [--raw|--full]` 提供 REST 列表，默认 `state=all` 以保持既有 UniDesk CLI 行为，字段白名单是 `body,title,state,number,url,author,head,base,draft,createdAt,updatedAt,headRefName,baseRefName`；未知 state 或未知 `--json` 字段必须结构化失败并带 `runnerDisposition=business-failed`。`--raw|--full` 在 `gh pr list` 上等价 `gh issue list --raw|--full`：响应带 `noDump=true`，inline 输出完整数据，绕开 20 KiB stdout 截断。`mergeable`、`mergeStateStatus` 和 `statusCheckRollup` 不属于 list 字段，请对具体 PR 使用 `gh pr view <number> --json headRefName,baseRefName,mergeable,mergeStateStatus,statusCheckRollup`，避免列表默认拉取 noisy/raw 状态汇总。`gh pr files <number> [--limit N]` 是 PR changed-file/stat summary 的稳定 REST 入口，返回 bounded `files`、`filesReturned`、`summary.files/additions/deletions/changes/commits`、`truncation` 和 `next.command`，默认不输出 raw diff 或 patch；`gh pr diff <number> --stat` 是兼容别名，返回同一 JSON，未带 `--stat` 的 raw diff 请求会结构化拒绝。`gh pr view|read <number|url|owner/repo#number> [--json ...] [--raw|--full]` 继续稳定返回这些字段，并额外支持 `stateDetail,closed,closedAt,merged,mergedAt,mergeCommit,headRefName,baseRefName,mergeable,mergeStateStatus,statusCheckRollup`。`owner/repo#number` shorthand 和冲突 `--repo` 规则与 issue view/read 相同。`stateDetail` 是 UniDesk 归一化生命周期值 `open|closed|merged`，用于区分 REST `state=closed` 中的普通关闭和已合并；`closed`、`closedAt`、`merged`、`mergedAt`、`mergeCommit`、`headRefName` 与 `baseRefName` 都来自 REST，不需要 GraphQL。`mergeable`、`mergeStateStatus` 和 `statusCheckRollup` 只在 view/read 明确请求这些字段或用 `--raw|--full` 显式完整披露时通过 GitHub GraphQL 查询，GraphQL 权限不足或网络失败会结构化失败；GitHub 暂未计算完成时仍保留原始 `UNKNOWN`/null，并额外返回 `closeoutMetadata.ok=false`、`missingOrUnknownFields`、advice 和 `mergeBoundary.unideskCliMergeSupported=true`。此时收口人员应优先重试一次；若仍缺失，应继续改进 UniDesk `gh` 子命令或使用人工 GitHub UI 做最终交叉确认，禁止原生 `gh` 或手拼 GitHub API 绕过。`gh pr preflight <number|owner/repo#number> [--repo owner/name] [--full|--raw]` 是低噪声 PR 收口入口，`gh preflight <number|owner/repo#number>` 和 `gh pr closeout <number|owner/repo#number>` 是兼容别名；shorthand 与 `gh pr view` 一致，已规范化为 `pikasTech/HWLAB#624` 这类形式时不需要再重复 `--repo`。它先输出脱敏 auth capability，再读取 PR state/draft/head/base、mergeable、mergeStateStatus 和 statusCheckRollup，默认只给 status check 计数与失败/等待预览，完整 contexts 和原始读取摘要必须显式加 `--full` 或 `--raw`。该命令固定 `readOnly=true`、`writesRemote=false`、`policy.mergesPr=false`，不会创建、评论、更新或 merge PR。`gh pr create --title <title> --body-file <file>|--body <text> --base <branch> --head <branch> [--draft] [--dry-run]`、`gh pr edit <number> [--title ...] [--body-file <file>|--body-file -|--body <text>] [--dry-run]`、`gh pr update <number> --mode replace|append [--body-file <file>|--body-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]` 和 `gh pr merge <number> [--merge|--squash|--rebase] [--delete-branch] [--dry-run]` 是 PR CRUD/生命周期入口。`pr create --dry-run` 只输出 planned operation，不访问 GitHub；非 dry-run 创建前会校验 repo、base、head 和 compare ahead 状态，成功时返回 PR number/url。`pr edit/update` 使用 REST `PATCH /repos/{owner}/{repo}/pulls/{number}`，只发送显式提供的 `title` 和/或 `body` 字段，完全避开 GitHub Projects Classic GraphQL/projectCards；输出低噪声 JSON：`ok`、`repo`、PR number、`changedFields`、`url`、body 长度/SHA/source 元数据和 request plan，不默认回显完整正文。`pr update --mode append` 会先读取当前 PR body 再追加正文。`pr merge` 会先执行同源 closeout 预检，拒绝非 open、draft、冲突、非 CLEAN、失败或 pending checks 的 PR，只有 ready 时才调用 GitHub REST merge；`--delete-branch` 只删除同 repo head ref。`gh pr delete <number>` 不开放，PR 生命周期删除语义请使用 `close`。 +- `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 ...] [--raw|--full]` 提供 REST 列表，默认 `state=all` 以保持既有 UniDesk CLI 行为，字段白名单是 `body,title,state,number,url,author,head,base,draft,createdAt,updatedAt,headRefName,baseRefName`；未知 state 或未知 `--json` 字段必须结构化失败并带 `runnerDisposition=business-failed`。`--raw|--full` 在 `gh pr list` 上等价 `gh issue list --raw|--full`：响应带 `noDump=true`，inline 输出完整数据，绕开 20 KiB stdout 截断。`mergeable`、`mergeStateStatus` 和 `statusCheckRollup` 不属于 list 字段，请对具体 PR 使用 `gh pr view <number> --json headRefName,baseRefName,mergeable,mergeStateStatus,statusCheckRollup`，避免列表默认拉取 noisy/raw 状态汇总。`gh pr files <number> [--limit N]` 是 PR changed-file/stat summary 的稳定 REST 入口，返回 bounded `files`、`filesReturned`、`summary.files/additions/deletions/changes/commits`、`truncation` 和 `next.command`，默认不输出 raw diff 或 patch；`gh pr diff <number> --stat` 是兼容别名，返回同一 JSON，未带 `--stat` 的 raw diff 请求会结构化拒绝。`gh pr view|read <number|url|owner/repo#number> [--json ...] [--raw|--full]` 继续稳定返回这些字段，并额外支持 `stateDetail,closed,closedAt,merged,mergedAt,mergeCommit,headRefName,baseRefName,mergeable,mergeStateStatus,statusCheckRollup`。`owner/repo#number` shorthand 和冲突 `--repo` 规则与 issue view/read 相同。`stateDetail` 是 UniDesk 归一化生命周期值 `open|closed|merged`，用于区分 REST `state=closed` 中的普通关闭和已合并；`closed`、`closedAt`、`merged`、`mergedAt`、`mergeCommit`、`headRefName` 与 `baseRefName` 都来自 REST，不需要 GraphQL。`mergeable`、`mergeStateStatus` 和 `statusCheckRollup` 只在 view/read 明确请求这些字段或用 `--raw|--full` 显式完整披露时通过 GitHub GraphQL 查询，GraphQL 权限不足或网络失败会结构化失败；GitHub 暂未计算完成时仍保留原始 `UNKNOWN`/null，并额外返回 `closeoutMetadata.ok=false`、`missingOrUnknownFields`、advice 和 `mergeBoundary.unideskCliMergeSupported=true`。此时收口人员应优先重试一次；若仍缺失，应继续改进 UniDesk `gh` 子命令或使用人工 GitHub UI 做最终交叉确认，禁止原生 `gh` 或手拼 GitHub API 绕过。`gh pr preflight <number|owner/repo#number> [--repo owner/name] [--full|--raw]` 是低噪声 PR 收口入口，`gh preflight <number|owner/repo#number>` 和 `gh pr closeout <number|owner/repo#number>` 是兼容别名；shorthand 与 `gh pr view` 一致，已规范化为 `pikasTech/HWLAB#624` 这类形式时不需要再重复 `--repo`。它先输出脱敏 auth capability，再读取 PR state/draft/head/base、mergeable、mergeStateStatus 和 statusCheckRollup，默认只给 status check 计数与失败/等待预览，完整 contexts 和原始读取摘要必须显式加 `--full` 或 `--raw`。该命令固定 `readOnly=true`、`writesRemote=false`、`policy.mergesPr=false`，不会创建、评论、更新或 merge PR。`gh pr create --title <title> --body-stdin --base <branch> --head <branch> [--draft] [--dry-run]`、`gh pr edit <number> [--title ...] [--body-stdin|--body <text>] [--dry-run]`、`gh pr update <number> --mode replace|append [--body-stdin|--body <text>] [--title ...] [--dry-run]`、`gh pr comment create <number> (--body-stdin|--body <text>) [--dry-run]`、`gh pr comment delete <commentId> [--dry-run]`、`gh pr close|reopen <number> [--dry-run]` 和 `gh pr merge <number> [--merge|--squash|--rebase] [--delete-branch] [--dry-run]` 是 PR CRUD/生命周期入口。多行 PR 正文和评论推荐 `--body-stdin <<'EOF'`；`--body-file` 只在已有复用文件时使用，`--body` 只适合短单行内容。`pr create --dry-run` 只输出 planned operation，不访问 GitHub；非 dry-run 创建前会校验 repo、base、head 和 compare ahead 状态，成功时返回 PR number/url。`pr edit/update` 使用 REST `PATCH /repos/{owner}/{repo}/pulls/{number}`，只发送显式提供的 `title` 和/或 `body` 字段，完全避开 GitHub Projects Classic GraphQL/projectCards；输出低噪声 JSON：`ok`、`repo`、PR number、`changedFields`、`url`、body 长度/SHA/source 元数据和 request plan，不默认回显完整正文。`pr update --mode append` 会先读取当前 PR body 再追加正文。`pr merge` 会先执行同源 closeout 预检，拒绝非 open、draft、冲突、非 CLEAN、失败或 pending checks 的 PR，只有 ready 时才调用 GitHub REST merge；`--delete-branch` 只删除同 repo head ref。`gh pr delete <number>` 不开放，PR 生命周期删除语义请使用 `close`。 - `gh pr merge` 的 already-merged 终态是 guarded merge 的幂等成功例外：当目标 PR 已经处于 `merged` 状态时，命令返回 `ok=true`、`alreadyMerged=true`、`pullRequest.merged=true` 和 merge commit 摘要，不再把并发 monitor、GitHub UI 或人工合并后的 `closed` 状态误报为 validation-failed。 - `gh pr list` 与 `gh issue list` 一样接受单个位置参数 `owner/repo` 作为 `--repo owner/repo` 兼容别名；位置 repo 与显式 `--repo` 冲突时会结构化失败，输出里的 `repo` 始终反映真实请求目标。`--number N --repo owner/repo` 是单 PR/comment 数字目标命令的位置参数兼容别名，适用于 `view/read/files/diff/preflight/closeout/edit/update/comment create/comment delete/close/reopen/merge`，成功输出必须带 `standardSyntaxHint`；comment delete 中的 `--number` 表示 commentId，不是 PR number；`list/create` 不能静默忽略 `--number`。 -- 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 files <number> --repo pikasTech/unidesk --limit 30`、`bun scripts/cli.ts gh pr view <number> --repo pikasTech/unidesk --json body,title,state,stateDetail,closed,closedAt,merged,mergedAt,mergeCommit,head,base,headRefName,baseRefName,mergeable,mergeStateStatus,statusCheckRollup` 和 `bun scripts/cli.ts gh pr preflight <number> --repo pikasTech/unidesk` 做只读 PR 观察、文件统计和收口元数据检查；`bun scripts/cli.ts gh pr edit <number> --repo pikasTech/unidesk --title <title> --body-file <file> --dry-run` 或 `cat <file> | bun scripts/cli.ts gh pr edit <number> --repo pikasTech/unidesk --body-file - --dry-run` 检查低噪声 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 --dry-run` 检查 guarded merge plan，真实 merge 只能在任务边界明确允许且 preflight ready 后执行。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。 +- 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-stdin --base master --head <head> --dry-run <<'EOF' ... EOF` 检查创建计划；`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 files <number> --repo pikasTech/unidesk --limit 30`、`bun scripts/cli.ts gh pr view <number> --repo pikasTech/unidesk --json body,title,state,stateDetail,closed,closedAt,merged,mergedAt,mergeCommit,head,base,headRefName,baseRefName,mergeable,mergeStateStatus,statusCheckRollup` 和 `bun scripts/cli.ts gh pr preflight <number> --repo pikasTech/unidesk` 做只读 PR 观察、文件统计和收口元数据检查；`bun scripts/cli.ts gh pr edit <number> --repo pikasTech/unidesk --title <title> --body-stdin --dry-run <<'EOF' ... EOF` 检查低噪声 PR 标题/正文编辑计划；`bun scripts/cli.ts gh pr comment create <number> --repo pikasTech/unidesk --body-stdin --dry-run <<'EOF' ... EOF` 检查评论计划；`bun scripts/cli.ts gh pr merge <number> --repo pikasTech/unidesk --dry-run` 检查 guarded merge plan，真实 merge 只能在任务边界明确允许且 preflight ready 后执行。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。 - `ci install|status|run|publish-backend-core|publish-user-service|run-dev-e2e|logs` 管理 D601 原生 k3s 上的 Tekton CI。`run` 手动创建每 commit 检查和 Code Queue 只读性能门禁；`publish-backend-core` 与 `publish-user-service` 从 pushed Git commit 构建并发布 `127.0.0.1:5000/unidesk/<service>:<commit>` commit-pinned artifacts，输出 `artifactSummary`（含 `serviceId`、`sourceCommit`、`sourceRepo`、`dockerfile`、`imageRef`、`tag`、`digest`、`digestRef`），但不部署生产；`run-dev-e2e` 的 Git 控制 runner、短 launcher、host fetch 边界、临时 smoke namespace 和 no-CD 规则只在 `docs/reference/dev-ci-runner.md` 定义；Tekton CI 通用规则见 `docs/reference/ci.md`。 - `schedule list|get|runs|run|retry-run|delete|upsert-pgdata-backup` 管理 backend-core 定时任务和运行历史。`schedule list`、`schedule get`、`schedule runs --limit N` 和 `schedule runs <scheduleId> --limit N` 是只读观察入口；`schedule run`、`schedule retry-run`、`schedule delete` 和 `schedule upsert-pgdata-backup` 会触发运行或写入配置，生产恢复时必须有明确授权。`schedule runs --limit N` 是全局历史视图，返回 `scope=global` 和 `scheduleId=null`；`schedule runs <scheduleId> --limit N` 是指定 schedule 历史视图，返回 `scope=schedule` 和对应 `scheduleId`。CLI 必须拒绝 `schedule runs 50` 这类纯数字位置参数，并提示使用 `schedule runs --limit 50`，避免把空数组误判成“没有历史 run”。`schedule run <id> --wait-ms N` 触发同一 schedule，并且即使 wait 超时也必须返回 `newRunId` 和 `observeCommand`；`schedule retry-run <failedRunId>` 只接受 failed run，从原 run 反查 `scheduleId` 后重触发同一 schedule，并输出 `originalRunId`、`scheduleId`、`newRunId` 和 `observeCommand`。当 backend-core 目标容器缺失或只观察到 verify-only 容器时，schedule/microservice 命令必须以非零退出并返回 `failureKind=target-stack-not-running`、`runnerDisposition=infra-blocked`、`readOnlyCommands` 和 `authorizationRequiredForRecovery`，不得把 Docker 的 `No such container` 当成成功的空历史。 - `codex deploy <commitId>` 是旧 Code Queue 兼容部署入口，已禁用以防止维护通道直连 D601 部署 Code Queue；当前 dev 自动化只做 `ci run-dev-e2e` smoke，不提供 Code Queue CD，详细规则见 `docs/reference/codex-deploy.md`。 @@ -204,7 +204,7 @@ bun scripts/cli.ts microservice proxy code-queue /api/foo --method GET --check-p **复杂 JSON body 优先 `--body-file <path>` 而非 `--body-json '<inline>'`**（2026-06-01 摩擦改进验证）。`--body-json` 在 shell 里要把双引号 escape 成 `\"`，遇到 action 对象里有嵌套字段或中英文混排标题几乎必坏；`--body-file` 走文件直读，反引号、反斜杠、中文、嵌套 JSON 都安全，且支持 stdin（`--body-file -`）。推荐做法：先 `cat > /tmp/x.json <<'EOF' ... EOF`（heredoc quoted 防 shell 展开），再 `bun scripts/cli.ts microservice proxy todo-note .../actions --method POST --body-file /tmp/x.json`。已交互验证 200 OK 全套 write actions（addTodo / toggleTodoCompleted / deleteTodo），probe 写入 + 删除完整 lifecycle 通。 -GitHub issue/PR 写操作必须优先使用 `bun scripts/cli.ts gh issue|pr ... --body-file <file|->`。不要把 Markdown 正文拼进 shell 参数或 `gh api -f body=...`；这些路径容易把真实换行污染成字面量 `\n`。从 shell 生成正文文件时使用 quoted heredoc，例如 `cat <<'EOF' > /tmp/body.md`，保证反引号、反斜杠和 Markdown 表格不被 shell 展开；一次性写入可直接走 stdin，例如 `cat /tmp/body.md | bun scripts/cli.ts gh issue update <number> --repo owner/name --body-file -` 或 `cat /tmp/body.md | bun scripts/cli.ts gh issue comment create <number|owner/repo#number> --repo owner/name|--body-file -`（issue 写命令支持 `owner/repo#number` shorthand，详见 `gh` 子命令条目）。`gh issue update/edit` 正式写入默认先读取当前 issue 元数据，执行 body guard 并在结果里返回旧 `bodySha`/`updatedAt` 与新正文摘要；一般看板和评论写入不需要人工先 `read` 再手填 `--expect-body-sha`。对高风险整篇替换仍可显式加 `--expect-body-sha` 或 `--expect-updated-at`，CLI 会在 PATCH 前校验，不匹配则结构化失败。`gh issue comment create --body <short-text>` 只适合人工短单行评论，默认输出只给 bounded preview、bodyChars、bodySha、source 和 readCommands，不回显长正文；同时传 `--body` 与 `--body-file` 必须结构化失败。PR 安全写入口同样支持 `--body-file <file|->`；`--body` 只适合短单行内容。JSON 请求体场景使用各命名空间自己的 `--body-file` 或 `--body-stdin`，避免长 JSON 直接塞进 shell 参数。`update --mode append` 用 REST 读取旧正文后追加文件或 stdin 字节，不引入 shell 拼接正文路径。`gh pr merge` 是 guarded write：先读 closeout metadata 并拒绝非 ready PR，`--dry-run` 只输出计划不写远端；没有 `--confirm` 之类绕过 preflight 的路径。CLI 会按 UTF-8 原样读取文件或 stdin 内容并用 JSON body 调用 REST API；issue/PR 写入输出不会默认回显完整正文。 +GitHub issue/PR 写操作必须优先使用 `bun scripts/cli.ts gh issue|pr ... --body-stdin <<'EOF'` 或生命周期评论的 `--comment-stdin <<'EOF'`。不要把 Markdown 正文拼进 shell 参数或 `gh api -f body=...`；这些路径容易把真实换行污染成字面量 `\n`。推荐形态是 quoted heredoc，例如 `bun scripts/cli.ts gh issue comment create <number|owner/repo#number> --repo owner/name --body-stdin <<'EOF' ... EOF`，保证反引号、反斜杠和 Markdown 表格不被 shell 展开，也不需要临时正文文件；已有可复用正文文件时才使用 `--body-file <file|->`。`gh issue update/edit` 正式写入默认先读取当前 issue 元数据，执行 body guard 并在结果里返回旧 `bodySha`/`updatedAt` 与新正文摘要；一般看板和评论写入不需要人工先 `read` 再手填 `--expect-body-sha`。对高风险整篇替换仍可显式加 `--expect-body-sha` 或 `--expect-updated-at`，CLI 会在 PATCH 前校验，不匹配则结构化失败。`gh issue comment create --body <short-text>` 只适合人工短单行评论，默认输出只给 bounded preview、bodyChars、bodySha、source 和 readCommands，不回显长正文；同时传 `--body` 与 `--body-stdin` / `--body-file` 必须结构化失败。PR 安全写入口同样优先使用 `--body-stdin` heredoc；`--body` 只适合短单行内容。JSON 请求体场景使用各命名空间自己的 `--body-stdin` 或 `--body-file`，避免长 JSON 直接塞进 shell 参数。`update --mode append` 用 REST 读取旧正文后追加 stdin 字节，不引入 shell 拼接正文路径。`gh pr merge` 是 guarded write：先读 closeout metadata 并拒绝非 ready PR，`--dry-run` 只输出计划不写远端；没有 `--confirm` 之类绕过 preflight 的路径。CLI 会按 UTF-8 原样读取 stdin 或文件内容并用 JSON body 调用 REST API；issue/PR 写入输出不会默认回显完整正文。 `network perf` 用于生成组网性能前后对比数据。标准 Code Queue overview 读路径基准命令是 `bun scripts/cli.ts network perf --service code-queue --path /api/tasks/overview?limit=30 --count 30 --concurrency 1 --label before`，远程主 server 可用 `bun scripts/cli.ts --main-server-ip 74.48.78.17 network perf ...`。输出包含成功/失败数、状态码分布、`x-unidesk-cache`、`x-unidesk-proxy-mode`、`x-unidesk-upstream-proxy-mode` 分布和 min/p50/p90/p95/max；provider-gateway 长连接数据面验收应看到 `proxyModeCounts.provider-ws-http-tunnel`，adapter native Service 数据面验收应看到 upstream proxy mode 为 `kubernetes-native-service`，若出现 `kubernetes-api-service-proxy` 必须结合 `/api/control-plane.nativeServiceProxy.failedServices` 解释 fallback 原因。 diff --git a/scripts/gh-cli-issue-guard-contract-test.ts b/scripts/gh-cli-issue-guard-contract-test.ts index 56df45e5..7718894b 100644 --- a/scripts/gh-cli-issue-guard-contract-test.ts +++ b/scripts/gh-cli-issue-guard-contract-test.ts @@ -665,7 +665,7 @@ export async function runGhCliIssueGuardContract(): Promise<JsonRecord> { assertCondition(notes.some((line) => line.includes("GitHub issue URLs") && line.includes("owner/repo#number shorthand")), "gh help should explain issue view/read URL and shorthand targets", { notes }); assertCondition(notes.some((line) => line.includes("--number is accepted on single issue/comment numeric target commands") && line.includes("Comment delete treats --number as commentId")), "gh help should document issue --number compatibility scope", { notes }); assertCondition(notes.some((line) => line.includes("--raw and --full are explicit full-disclosure aliases")), "gh help should explain raw/full read disclosure", { notes }); - assertCondition(notes.some((line) => line.includes("issue comment create accepts --body-file <file|->") && line.includes("--body only for short single-line text")), "gh help should document issue comment stdin and inline safety limits", { notes }); + assertCondition(notes.some((line) => line.includes("issue comment create accepts --body-stdin") && line.includes("--body only for short single-line text")), "gh help should document issue comment heredoc stdin and inline safety limits", { notes }); assertCondition(notes.some((line) => line.includes("board-row update changes one table cell")), "gh help should describe board-row update safety", { notes }); assertCondition(notes.some((line) => line.includes("board-row upsert updates an existing row")), "gh help should describe board-row upsert safety", { notes }); assertCondition(notes.some((line) => line.includes("board-row add/move/delete are row-scoped")), "gh help should describe board-row row mutation safety", { notes }); @@ -785,7 +785,7 @@ export async function runGhCliIssueGuardContract(): Promise<JsonRecord> { assertCondition(scanFindings.some((finding) => finding.issueNumber === 53 && finding.kind === "null-body" && finding.classification === "risk"), "null body should be guarded as risk", scanFindings); const cleanupSuggestions = scanData.cleanupSuggestions as JsonRecord[]; assertCondition(Array.isArray(cleanupSuggestions), "scan should expose cleanupSuggestions", scanData); - assertCondition(cleanupSuggestions.some((suggestion) => suggestion.issueNumber === 51 && suggestion.type === "issue-body" && typeof suggestion.bodyId === "string" && suggestion.action === "rewrite-issue-body-with-body-file"), "issue body cleanup suggestion should use body-file rewrite with body id", cleanupSuggestions); + assertCondition(cleanupSuggestions.some((suggestion) => suggestion.issueNumber === 51 && suggestion.type === "issue-body" && typeof suggestion.bodyId === "string" && suggestion.action === "rewrite-issue-body-with-body-stdin"), "issue body cleanup suggestion should use heredoc/stdin rewrite with body id", cleanupSuggestions); assertCondition(cleanupSuggestions.some((suggestion) => suggestion.commentId === 5101 && suggestion.type === "comment-body" && String(suggestion.bodyId ?? "").includes("comment:5101") && suggestion.action === "review-comment-manually"), "comment cleanup suggestion should be manual review with body id", cleanupSuggestions); assertCondition(cleanupSuggestions.every((suggestion) => suggestion.issueNumber !== 52), "explanatory mention should not create cleanup suggestion", cleanupSuggestions); const scanPatchCount = mock.requests.filter((request) => request.method === "PATCH" || request.method === "DELETE" || request.method === "POST").length; @@ -1471,7 +1471,7 @@ export async function runGhCliIssueGuardContract(): Promise<JsonRecord> { "", "## 常驻观察与长期建议", "", - "- 保持滚动简报正文只通过 body-file 更新。", + "- 保持滚动简报正文只通过 heredoc/stdin 更新。", "", "## 更新 2026-05-21 15:18 北京时间", "", @@ -1570,10 +1570,16 @@ export async function runGhCliIssueGuardContract(): Promise<JsonRecord> { const issueCreateStdinWriteCount = mock.requests.slice(issueCreateStdinRequestCountBefore).filter((request) => request.method === "POST" && request.url === "/repos/pikasTech/unidesk/issues").length; assertCondition(issueCreateStdinWriteCount === 0, "issue create stdin dry-run must not POST GitHub", { requests: mock.requests.slice(issueCreateStdinRequestCountBefore) }); + const issueCreateBodyStdin = await runCli(["gh", "issue", "create", "--repo", "pikasTech/unidesk", "--title", "body-stdin issue create", "--body-stdin", "--dry-run"], env, issueCreateStdinBody); + assertCondition(issueCreateBodyStdin.status === 0, "issue create dry-run should accept --body-stdin", issueCreateBodyStdin.json ?? { stdout: issueCreateBodyStdin.stdout }); + const issueCreateBodyStdinData = dataOf(issueCreateBodyStdin.json ?? {}); + const issueCreateBodyStdinSource = issueCreateBodyStdinData.bodySource as JsonRecord; + assertCondition(issueCreateBodyStdinSource.kind === "stdin" && issueCreateBodyStdinSource.path === "-", "issue create --body-stdin should expose stdin source", issueCreateBodyStdinData); + const issueCreateInline = await runCli(["gh", "issue", "create", "--repo", "pikasTech/unidesk", "--title", "inline rejected", "--body", "inline body", "--dry-run"], env); assertCondition(issueCreateInline.status !== 0, "issue create inline --body should fail", issueCreateInline.json ?? { stdout: issueCreateInline.stdout }); const issueCreateInlineData = failedDataOf(issueCreateInline.json ?? {}); - assertCondition(failureMessageOf(issueCreateInlineData).includes("does not support --body"), "issue create inline --body should point to body-file", issueCreateInlineData); + assertCondition(failureMessageOf(issueCreateInlineData).includes("does not support --body"), "issue create inline --body should point to body-stdin", issueCreateInlineData); const issueCreateMissingLabel = await runCli(["gh", "issue", "create", "--repo", "pikasTech/unidesk", "--title", "bad label", "--body-file", appendFile, "--label", "missing-label"], env); assertCondition(issueCreateMissingLabel.status !== 0, "issue create missing label should fail structurally", issueCreateMissingLabel.json ?? { stdout: issueCreateMissingLabel.stdout }); @@ -1729,6 +1735,17 @@ export async function runGhCliIssueGuardContract(): Promise<JsonRecord> { const closePatchPayload = JSON.parse(closeWriteRequests[1]?.body ?? "{}") as JsonRecord; assertCondition(closeCommentPayload.body === closeComment && closePatchPayload.state === "closed", "issue close --comment payloads should preserve comment and state", { closeCommentPayload, closePatchPayload }); + const reopenCommentStdinBody = "reopen heredoc comment\n\n- keeps `code`\n"; + const reopenStdinRequestCountBefore = mock.requests.length; + const reopenStdin = await runCli(["gh", "issue", "reopen", "20", "--repo", "pikasTech/unidesk", "--comment-stdin", "--dry-run"], env, reopenCommentStdinBody); + assertCondition(reopenStdin.status === 0, "issue reopen --comment-stdin dry-run should succeed", reopenStdin.json ?? { stdout: reopenStdin.stdout }); + const reopenStdinData = dataOf(reopenStdin.json ?? {}); + const reopenStdinComment = reopenStdinData.comment as JsonRecord; + const reopenStdinCommentSource = (reopenStdinComment.bodySource ?? {}) as JsonRecord; + assertCondition(reopenStdinCommentSource.kind === "stdin" && reopenStdinCommentSource.path === "-", "issue reopen --comment-stdin should expose stdin source", reopenStdinComment); + const reopenStdinWriteCount = mock.requests.slice(reopenStdinRequestCountBefore).filter((request) => request.method === "POST" || request.method === "PATCH").length; + assertCondition(reopenStdinWriteCount === 0, "issue reopen --comment-stdin dry-run must not write GitHub", { requests: mock.requests.slice(reopenStdinRequestCountBefore) }); + const closeCommentWrongCommand = await runCli(["gh", "issue", "comment", "create", "36", "--repo", "pikasTech/unidesk", "--comment", closeComment, "--dry-run"], env); assertCondition(closeCommentWrongCommand.status !== 0, "--comment outside issue close/reopen should fail structurally", closeCommentWrongCommand.json ?? { stdout: closeCommentWrongCommand.stdout }); const closeCommentWrongData = failedDataOf(closeCommentWrongCommand.json ?? {}); @@ -1737,7 +1754,7 @@ export async function runGhCliIssueGuardContract(): Promise<JsonRecord> { const missingCommentBody = await runCli(["gh", "issue", "comment", "create", "36", "--repo", "pikasTech/unidesk", "--dry-run"], env); assertCondition(missingCommentBody.status !== 0, "issue comment create without body source should fail", missingCommentBody.json ?? { stdout: missingCommentBody.stdout }); const missingCommentBodyData = failedDataOf(missingCommentBody.json ?? {}); - assertCondition(missingCommentBodyData.degradedReason === "validation-failed" && failureMessageOf(missingCommentBodyData).includes("requires --body-file <file> or --body <text>"), "missing issue comment body should be structured validation failure", missingCommentBodyData); + assertCondition(missingCommentBodyData.degradedReason === "validation-failed" && failureMessageOf(missingCommentBodyData).includes("requires --body-stdin"), "missing issue comment body should be structured validation failure", missingCommentBodyData); const mutualCommentBody = await runCli(["gh", "issue", "comment", "create", "36", "--repo", "pikasTech/unidesk", "--body", "inline", "--body-file", appendFile, "--dry-run"], env); assertCondition(mutualCommentBody.status !== 0, "issue comment create with body and body-file should fail", mutualCommentBody.json ?? { stdout: mutualCommentBody.stdout }); @@ -1752,7 +1769,7 @@ export async function runGhCliIssueGuardContract(): Promise<JsonRecord> { const multilineInlineComment = await runCli(["gh", "issue", "comment", "create", "36", "--repo", "pikasTech/unidesk", "--body", "line1\nline2", "--dry-run"], env); assertCondition(multilineInlineComment.status !== 0, "multiline inline issue comment body should fail", multilineInlineComment.json ?? { stdout: multilineInlineComment.stdout }); const multilineInlineCommentData = failedDataOf(multilineInlineComment.json ?? {}); - assertCondition(failureMessageOf(multilineInlineCommentData).includes("single-line text only"), "multiline inline issue comment body should point to body-file", multilineInlineCommentData); + assertCondition(failureMessageOf(multilineInlineCommentData).includes("single-line text only"), "multiline inline issue comment body should point to body-stdin", multilineInlineCommentData); const pollutedInlineComment = await runCli(["gh", "issue", "comment", "create", "36", "--repo", "pikasTech/unidesk", "--body", "literal \\n pollution", "--dry-run"], env); assertCondition(pollutedInlineComment.status !== 0, "polluted inline issue comment body should fail", pollutedInlineComment.json ?? { stdout: pollutedInlineComment.stdout }); @@ -1774,6 +1791,12 @@ export async function runGhCliIssueGuardContract(): Promise<JsonRecord> { assertCondition(stdinCommentSource.kind === "stdin" && stdinCommentSource.path === "-" && stdinCommentData.source === "stdin", "stdin issue comment dry-run should expose stdin source", stdinCommentData); assertCondition(stdinCommentData.containsBackticks === true && stdinCommentData.containsLiteralBackslashN === false, "stdin issue comment should preserve Markdown signals", stdinCommentData); + const bodyStdinComment = await runCli(["gh", "issue", "comment", "create", "36", "--repo", "pikasTech/unidesk", "--body-stdin", "--dry-run"], env, stdinCommentBody); + assertCondition(bodyStdinComment.status === 0, "issue comment --body-stdin should be supported", bodyStdinComment.json ?? { stdout: bodyStdinComment.stdout }); + const bodyStdinCommentData = dataOf(bodyStdinComment.json ?? {}); + const bodyStdinCommentSource = bodyStdinCommentData.bodySource as JsonRecord; + assertCondition(bodyStdinCommentSource.kind === "stdin" && bodyStdinCommentSource.path === "-" && bodyStdinCommentData.source === "stdin", "issue comment --body-stdin should expose stdin source", bodyStdinCommentData); + const commentDeleteDryRun = await runCli(["gh", "issue", "comment", "delete", "9001", "--repo", "pikasTech/unidesk", "--dry-run"], env); assertCondition(commentDeleteDryRun.status === 0, "issue comment delete dry-run should succeed", commentDeleteDryRun.json ?? { stdout: commentDeleteDryRun.stdout }); const commentDeleteDryRunData = dataOf(commentDeleteDryRun.json ?? {}); @@ -1819,7 +1842,7 @@ export async function runGhCliIssueGuardContract(): Promise<JsonRecord> { "issue board-row update rejects literal backslash-n cell values", "issue board-row update escapes markdown table pipes and performs guarded PATCH with --expect-body-sha", "issue board-row move is supported, defaults to dry-run, and can migrate OPEN rows into CLOSED", - "issue create dry-run parses repeated/comma labels, supports stdin, rejects inline --body, and exposes request plan", + "issue create dry-run parses repeated/comma labels, supports --body-stdin and compatible --body-file -, rejects inline --body, and exposes request plan", "issue create sends labels through REST and preserves GitHub validation errors for missing labels", "issue list unsupported fields and states fail structurally", "issue read supports body,title,state,closed,closedAt,comments selection", @@ -1838,8 +1861,9 @@ export async function runGhCliIssueGuardContract(): Promise<JsonRecord> { "issue update replace/append modes preserve Markdown and support stdin with automatic current issue metadata checks", "issue update non-dry-run success defaults to compact output without full issue.body and exposes bodySha plus drill-down commands", "issue update --full explicitly includes full issue.body", + "issue close/reopen supports --comment-stdin dry-run without writes", "issue comment create supports short inline --body dry-run and write with bounded output", - "issue comment create supports stdin and still rejects missing, blank, multiline inline, polluted inline, secret-like inline, and mixed body sources", + "issue comment create supports --body-stdin and compatible --body-file -, and still rejects missing, blank, multiline inline, polluted inline, secret-like inline, and mixed body sources", "issue comment create/delete follows CRUD shape", "issue hard delete is structurally unsupported", ], diff --git a/scripts/gh-cli-pr-contract-test.ts b/scripts/gh-cli-pr-contract-test.ts index d9ad24bf..ed751751 100644 --- a/scripts/gh-cli-pr-contract-test.ts +++ b/scripts/gh-cli-pr-contract-test.ts @@ -684,7 +684,7 @@ export async function runGhCliPrContract(): Promise<JsonRecord> { const editStdinBody = "stdin line\n`stdin code`\n| c | d |\n"; const beforeEditRequests = mock2.requests.length; - const editStdin = await runCli(["gh", "pr", "edit", "42", "--repo", "pikasTech/unidesk", "--title", "stdin title", "--body-file", "-"], env2, editStdinBody); + const editStdin = await runCli(["gh", "pr", "edit", "42", "--repo", "pikasTech/unidesk", "--title", "stdin title", "--body-stdin"], env2, editStdinBody); assertCondition(editStdin.status === 0, "pr edit stdin should succeed", editStdin.json ?? { stdout: editStdin.stdout }); const editStdinData = dataOf(editStdin.json ?? {}); assertCondition(editStdinData.command === "pr edit" && editStdinData.pr === 42 && editStdinData.url === "https://github.com/pikasTech/unidesk/pull/42", "pr edit stdin should return low-noise summary", editStdinData); @@ -720,6 +720,16 @@ export async function runGhCliPrContract(): Promise<JsonRecord> { const commentCreateData = dataOf(commentCreate.json ?? {}); assertCondition(commentCreateData.command === "pr comment create", "pr comment create should use CRUD command name", commentCreateData); + const prBodyStdinCommentBody = "PR heredoc comment line\n\n- keeps `code`\n"; + const prBodyStdinComment = await runCli(["gh", "pr", "comment", "create", "42", "--repo", "pikasTech/unidesk", "--body-stdin"], env2, prBodyStdinCommentBody); + assertCondition(prBodyStdinComment.status === 0, "pr comment create --body-stdin should succeed", prBodyStdinComment.json ?? { stdout: prBodyStdinComment.stdout }); + const prBodyStdinCommentData = dataOf(prBodyStdinComment.json ?? {}); + const prBodyStdinSource = prBodyStdinCommentData.bodySource as JsonRecord; + assertCondition(prBodyStdinSource.kind === "stdin" && prBodyStdinSource.path === "-", "pr comment create --body-stdin should expose stdin source", prBodyStdinCommentData); + const prBodyStdinRequest = mock2.requests.filter((request) => request.method === "POST" && request.url === "/repos/pikasTech/unidesk/issues/42/comments").at(-1); + const prBodyStdinPayload = JSON.parse(prBodyStdinRequest?.body ?? "{}") as JsonRecord; + assertCondition(prBodyStdinPayload.body === prBodyStdinCommentBody, "pr comment --body-stdin payload should preserve stdin markdown", prBodyStdinPayload); + const prInlineCommentBody = "short PR inline comment remains supported"; const prInlineComment = await runCli(["gh", "pr", "comment", "create", "42", "--repo", "pikasTech/unidesk", "--body", prInlineCommentBody], env2); assertCondition(prInlineComment.status === 0, "pr comment create --body should remain supported", prInlineComment.json ?? { stdout: prInlineComment.stdout }); @@ -787,9 +797,9 @@ export async function runGhCliPrContract(): Promise<JsonRecord> { "pr create dry-run exposes planned operation", "pr comment dry-run preserves markdown text", "pr update/edit use low-noise REST PATCH without GraphQL projectCards", - "pr edit supports --body-file - stdin without echoing full body", + "pr edit supports --body-stdin without echoing full body", "pr update append and close/reopen are available", - "pr comment create/delete follows CRUD shape and --body remains supported", + "pr comment create/delete follows CRUD shape, --body-stdin, and --body remains supported", "pr merge is guarded by preflight and uses REST", "pr hard delete is blocked", "pr create validation failures are structured", diff --git a/scripts/src/gh.ts b/scripts/src/gh.ts index d9721da9..96af1b34 100644 --- a/scripts/src/gh.ts +++ b/scripts/src/gh.ts @@ -60,7 +60,7 @@ const GH_VALUE_OPTIONS = new Set([ "--tasks", "--summary", "--focus", "--validation", "--progress", "--number", "--pr", "--search", "--inactive-hours", "--comment", "--comment-file", "--description", ]); -const GH_FLAG_OPTIONS = new Set(["--dry-run", "--draft", "--notify-claudeqq-brief-diff", "--allow-short-body", "--raw", "--full", "--stat", "--merge", "--squash", "--rebase", "--delete-branch", "--private", "--public", "--auto-init"]); +const GH_FLAG_OPTIONS = new Set(["--dry-run", "--draft", "--notify-claudeqq-brief-diff", "--allow-short-body", "--body-stdin", "--comment-stdin", "--raw", "--full", "--stat", "--merge", "--squash", "--rebase", "--delete-branch", "--private", "--public", "--auto-init"]); const MIN_SAFE_BODY_SCAN_CHARS = MIN_SAFE_ISSUE_BODY_CHARS; const ISSUE_SCAN_MAX_FINDINGS = 60; const ISSUE_BODY_PROFILES = { @@ -100,7 +100,7 @@ type IssueBodyProfileOption = "auto" | IssueBodyProfileName; type EscapeFindingClassification = "suspected-pollution" | "explanatory-mention" | "risk"; type EscapeFindingSeverity = "low" | "medium" | "high"; type EscapeBodyKind = "issue-body" | "comment-body"; -type CleanupSuggestionAction = "rewrite-issue-body-with-body-file" | "review-comment-manually" | "review-body-length" | "no-cleanup-needed"; +type CleanupSuggestionAction = "rewrite-issue-body-with-body-stdin" | "review-comment-manually" | "review-body-length" | "no-cleanup-needed"; type BoardSectionKind = "open" | "closed"; type BoardRequiredColumn = typeof BOARD_AUDIT_REQUIRED_COLUMNS[number]; type BoardColumnKind = BoardRequiredColumn | "focus" | "githubStatus" | "category" | "summary"; @@ -219,7 +219,7 @@ interface EscapeCleanupSuggestion { reason: string; findings: Array<Pick<EscapeMatchFinding, "kind" | "classification" | "severity" | "lineNumber" | "column" | "snippet" | "match">>; plannedCommand?: string; - bodyFileHint?: string; + bodyInputHint?: string; preview?: { before: string; after: string; @@ -868,6 +868,15 @@ function resolveRepoOption(args: string[]): string { return explicitRepo ?? DEFAULT_REPO; } +function stdinAliasFileOption(args: string[], fileOption: string, stdinFlag: string): string | undefined { + const file = optionValue(args, fileOption); + const stdin = hasFlag(args, stdinFlag); + if (file !== undefined && stdin) { + throw new Error(`${fileOption} and ${stdinFlag} are mutually exclusive; use one body source`); + } + return stdin ? "-" : file; +} + function parseOptions(args: string[]): GitHubOptions { validateKnownOptions(args); const [top, sub] = args; @@ -894,9 +903,9 @@ function parseOptions(args: string[]): GitHubOptions { search: optionValue(args, "--search"), title: optionValue(args, "--title"), body: optionValue(args, "--body"), - bodyFile: optionValue(args, "--body-file"), + bodyFile: stdinAliasFileOption(args, "--body-file", "--body-stdin"), comment: optionValue(args, "--comment"), - commentFile: optionValue(args, "--comment-file"), + commentFile: stdinAliasFileOption(args, "--comment-file", "--comment-stdin"), repoDescription: optionValue(args, "--description"), repoVisibility: parseRepoVisibility(args), repoAutoInit: hasFlag(args, "--auto-init"), @@ -1299,7 +1308,7 @@ function readMarkdownBodyFileOrStdin(path: string): { body: string; bodySource: } function readOptionalMarkdownBody(options: GitHubOptions, command: string): { body: string; bodySource: Record<string, unknown> } | null { - if (options.bodyFile !== undefined && options.body !== undefined) throw new Error(`${command} accepts only one body source: --body-file or --body`); + if (options.bodyFile !== undefined && options.body !== undefined) throw new Error(`${command} accepts only one body source: --body-file/--body-stdin or --body`); if (options.bodyFile !== undefined) { return readMarkdownBodyFileOrStdin(options.bodyFile); } @@ -1308,7 +1317,7 @@ function readOptionalMarkdownBody(options: GitHubOptions, command: string): { bo body: options.body, bodySource: { kind: "inline", - warning: options.body.includes("\n") ? "inline body contains real newlines; --body-file is safer for generated Markdown" : "inline body is intended only for short single-line text", + warning: options.body.includes("\n") ? "inline body contains real newlines; --body-stdin with a quoted heredoc is safer for generated Markdown" : "inline body is intended only for short single-line text", }, }; } @@ -1318,7 +1327,7 @@ function readOptionalMarkdownBody(options: GitHubOptions, command: string): { bo function readMarkdownBody(options: GitHubOptions, command: string): { body: string; bodySource: Record<string, unknown> } { const body = readOptionalMarkdownBody(options, command); if (body !== null) return body; - throw new Error(`${command} requires --body-file <file> or --body <text>`); + throw new Error(`${command} requires --body-stdin, --body-file <file|->, or --body <text>`); } function secretLikeInlineFindings(body: string): string[] { @@ -1332,27 +1341,27 @@ function secretLikeInlineFindings(body: string): string[] { function readIssueCommentBody(options: GitHubOptions): { body: string; bodySource: Record<string, unknown> } { if (options.bodyFile !== undefined && options.body !== undefined) { - throw new Error("issue comment create accepts only one body source: --body-file or --body"); + throw new Error("issue comment create accepts only one body source: --body-file/--body-stdin or --body"); } if (options.bodyFile !== undefined) { return readMarkdownBodyFileOrStdin(options.bodyFile); } - if (options.body === undefined) throw new Error("issue comment create requires --body-file <file> or --body <text>"); + if (options.body === undefined) throw new Error("issue comment create requires --body-stdin, --body-file <file|->, or --body <text>"); const body = options.body; const trimmed = body.trim(); const shellPollution = shellPollutionEvidence(body); const secretLike = secretLikeInlineFindings(body); if (trimmed.length === 0) { - throw new Error("issue comment create --body must not be blank; use --body-file for reviewed Markdown"); + throw new Error("issue comment create --body must not be blank; use --body-stdin with a quoted heredoc for reviewed Markdown"); } if (body.length > MAX_INLINE_ISSUE_COMMENT_BODY_CHARS) { - throw new Error(`issue comment create --body is limited to ${MAX_INLINE_ISSUE_COMMENT_BODY_CHARS} characters; use --body-file for long Markdown`); + throw new Error(`issue comment create --body is limited to ${MAX_INLINE_ISSUE_COMMENT_BODY_CHARS} characters; use --body-stdin with a quoted heredoc for long Markdown`); } if (body.includes("\n") || body.includes("\r")) { - throw new Error("issue comment create --body supports short single-line text only; use --body-file for multiline Markdown"); + throw new Error("issue comment create --body supports short single-line text only; use --body-stdin with a quoted heredoc for multiline Markdown"); } if (shellPollution.length > 0) { - throw new Error(`issue comment create --body contains shell-pollution signals (${shellPollution.join(",")}); use --body-file with reviewed Markdown bytes`); + throw new Error(`issue comment create --body contains shell-pollution signals (${shellPollution.join(",")}); use --body-stdin with a quoted heredoc for reviewed Markdown bytes`); } if (secretLike.length > 0) { throw new Error(`issue comment create --body appears to contain secret-like text (${secretLike.join(",")}); refusing to print or submit it`); @@ -1362,7 +1371,7 @@ function readIssueCommentBody(options: GitHubOptions): { body: string; bodySourc bodySource: { kind: "inline", maxInlineBodyChars: MAX_INLINE_ISSUE_COMMENT_BODY_CHARS, - warning: "inline issue comments are intended only for short single-line text; use --body-file for Markdown or generated content", + warning: "inline issue comments are intended only for short single-line text; use --body-stdin with a quoted heredoc for Markdown or generated content", }, }; } @@ -1370,10 +1379,10 @@ function readIssueCommentBody(options: GitHubOptions): { body: string; bodySourc function readIssueLifecycleCommentBody(options: GitHubOptions, command: string): { body: string; bodySource: Record<string, unknown> } | null { if (options.comment === undefined && options.commentFile === undefined) return null; if (options.comment !== undefined && options.commentFile !== undefined) { - throw new Error(`${command} --comment and --comment-file are mutually exclusive`); + throw new Error(`${command} --comment and --comment-file/--comment-stdin are mutually exclusive`); } if (options.body !== undefined || options.bodyFile !== undefined) { - throw new Error(`${command} --comment or --comment-file cannot be combined with --body or --body-file`); + throw new Error(`${command} --comment/--comment-file/--comment-stdin cannot be combined with --body/--body-file/--body-stdin`); } if (options.commentFile !== undefined) { return readIssueCommentBody({ ...options, body: undefined, bodyFile: options.commentFile }); @@ -1593,7 +1602,7 @@ function codeQueueBoardCommanderBriefHint(boardIssueNumber: number, body?: strin ? "Move HWLAB product/user issue tracking to pikasTech/HWLAB; keep #20 limited to UniDesk commander/Code Queue/CLI/infra governance." : "Use #20 only for UniDesk commander/Code Queue/CLI/infra governance rows.", forbiddenHeadings: ["## 更新 YYYY-MM-DD HH:mm 北京时间", "## YYYY-MM-DD HH:mm 北京时间指挥更新", "### YYYY-MM-DD HH:mm CST：..."], - suggestedCommand: "bun scripts/cli.ts gh issue update <daily-brief-issue> --mode replace --body-file <file> --body-profile commander-brief --expect-body-sha <sha>", + suggestedCommand: "bun scripts/cli.ts gh issue update <daily-brief-issue> --mode replace --body-stdin --body-profile commander-brief --expect-body-sha <sha> <<'EOF'\n<reviewed body>\nEOF", detected: commanderBriefDetected || hwlabProductDetected, detectedHeadings: headings, commanderBrief: { @@ -5275,6 +5284,11 @@ async function prComment(repo: string, token: string, issueNumber: number, optio issueNumber, pr: prSummary(prResult), comment: commentSummary(comment), + bodySource: bodySource.bodySource, + source: String(bodySource.bodySource.kind ?? "unknown"), + bodyChars: body.length, + bodySha: bodySha(body), + bodyPreview: preview(body), request: { method: "POST", path: `/repos/${owner}/${name}/issues/${issueNumber}/comments`, @@ -5297,7 +5311,7 @@ async function prUpdate(repo: string, token: string, number: number, options: Gi return validationError(commandName, repo, error instanceof Error ? error.message : String(error), { number }); } if (bodySource === null && options.title === undefined) { - return validationError(commandName, repo, `${commandName} requires --title <title>, --body-file <file|->, or --body <text>`, { number }); + return validationError(commandName, repo, `${commandName} requires --title <title>, --body-stdin, --body-file <file|->, or --body <text>`, { number }); } if (options.mode === "append" && bodySource === null) { return validationError(commandName, repo, `${commandName} --mode append requires a body source`, { number }); @@ -5657,7 +5671,7 @@ async function issueBoardAudit(repo: string, token: string, options: GitHubOptio async function issueCreate(repo: string, token: string, options: GitHubOptions): Promise<GitHubCommandResult> { if (options.title === undefined) throw new Error("issue create requires --title <title>"); if (options.body !== undefined) { - return validationError("issue create", repo, "issue create does not support --body; use --body-file <file|-> for Markdown", { + return validationError("issue create", repo, "issue create does not support --body; use --body-stdin with a quoted heredoc for Markdown", { title: options.title, bodySource: "inline", }); @@ -5699,7 +5713,7 @@ async function issueCreate(repo: string, token: string, options: GitHubOptions): async function issueEdit(repo: string, token: string, issueNumber: number, options: GitHubOptions, commandName = "issue edit"): Promise<GitHubCommandResult> { if (options.bodyFile === undefined) { - return validationError(commandName, repo, `${commandName} requires --body-file <file|->`, { issueNumber }); + return validationError(commandName, repo, `${commandName} requires --body-stdin or --body-file <file|->`, { issueNumber }); } let bodyInput: { body: string; bodySource: Record<string, unknown> }; try { @@ -6401,10 +6415,10 @@ function summarizeCleanupSuggestion(findings: EscapeScanEntry[]): EscapeCleanupS url: first.url, classification: suspected ? "suspected-pollution" : "risk", action: first.bodyKind === "issue-body" - ? (suspected ? "rewrite-issue-body-with-body-file" : "review-body-length") + ? (suspected ? "rewrite-issue-body-with-body-stdin" : "review-body-length") : "review-comment-manually", reason: suspected - ? "suspected shell escape pollution should be rewritten from a body file" + ? "suspected shell escape pollution should be rewritten from heredoc/stdin" : bodyRisk ? "body length/null risk should be reviewed before any write" : "no cleanup needed", @@ -6419,8 +6433,8 @@ function summarizeCleanupSuggestion(findings: EscapeScanEntry[]): EscapeCleanupS })), ...(first.bodyKind === "issue-body" ? { - plannedCommand: `bun scripts/cli.ts gh issue update ${first.issueNumber} --mode replace --body-file <file> --dry-run`, - bodyFileHint: "write a cleaned Markdown body to a file, then pass it with --body-file; use a quoted heredoc to stage the file instead of inline shell text", + plannedCommand: `bun scripts/cli.ts gh issue update ${first.issueNumber} --mode replace --body-stdin --dry-run <<'EOF'\n<cleaned body>\nEOF`, + bodyInputHint: "pass cleaned Markdown through --body-stdin with a quoted heredoc; --body-file is only for reusable files", preview: { before: first.cleanupPreview?.before ?? first.snippet, after: first.cleanupPreview?.after ?? first.snippet, @@ -6700,13 +6714,13 @@ export function ghHelp(): unknown { "bun scripts/cli.ts gh issue list [owner/repo] [--state open|closed|all] [--limit N] [--search text] [--label label[,label...]]... [--repo owner/name] [--json number,title,state,closed,closedAt,url,updatedAt,createdAt,author,labels] [--raw|--full]", "bun scripts/cli.ts gh issue view <number|url|owner/repo#number> [--repo owner/name] [--number N compat] [--json body,title,state,closed,closedAt,comments] [--raw|--full]", "bun scripts/cli.ts gh issue read <number|url|owner/repo#number> [--repo owner/name] [--number N compat] [--raw|--full] [compatibility alias for issue view]", - "bun scripts/cli.ts gh issue create --title <title> --body-file <file|-> [--label label[,label...]]... [--repo owner/name] [--dry-run]", - "bun scripts/cli.ts gh issue update <number> --mode replace|append --body-file <file|-> [--title title] [--repo owner/name] [--number N compat] [--dry-run] [--expect-updated-at ts|--expect-body-sha sha256] [--body-profile auto|code-queue-board|commander-brief] [--allow-short-body] [--full|--raw]", - "bun scripts/cli.ts gh issue edit <number> --body-file <file|-> [--repo owner/name] [--number N compat] [--full|--raw] [compat alias for issue update --mode replace]", - "bun scripts/cli.ts gh issue edit 24 --body-file <file> --notify-claudeqq-brief-diff [--dry-run]", - "bun scripts/cli.ts gh issue comment create <number> --body-file <file|->|--body <short-text> [--repo owner/name] [--number N compat] [--dry-run]", + "bun scripts/cli.ts gh issue create --title <title> (--body-stdin|--body-file <file|->) [--label label[,label...]]... [--repo owner/name] [--dry-run]", + "bun scripts/cli.ts gh issue update <number> --mode replace|append (--body-stdin|--body-file <file|->) [--title title] [--repo owner/name] [--number N compat] [--dry-run] [--expect-updated-at ts|--expect-body-sha sha256] [--body-profile auto|code-queue-board|commander-brief] [--allow-short-body] [--full|--raw]", + "bun scripts/cli.ts gh issue edit <number> (--body-stdin|--body-file <file|->) [--repo owner/name] [--number N compat] [--full|--raw] [compat alias for issue update --mode replace]", + "bun scripts/cli.ts gh issue edit 24 --body-stdin --notify-claudeqq-brief-diff [--dry-run]", + "bun scripts/cli.ts gh issue comment create <number> (--body-stdin|--body-file <file|->|--body <short-text>) [--repo owner/name] [--number N compat] [--dry-run]", "bun scripts/cli.ts gh issue comment delete <commentId> [--repo owner/name] [--number N compat] [--dry-run]", - "bun scripts/cli.ts gh issue close|reopen <number> [--repo owner/name] [--number N compat] [--comment <short-text>|--comment-file <file|->] [--dry-run]", + "bun scripts/cli.ts gh issue close|reopen <number> [--repo owner/name] [--number N compat] [--comment <short-text>|--comment-stdin|--comment-file <file|->] [--dry-run]", "bun scripts/cli.ts gh issue stale-close [--repo owner/name] [--inactive-hours N] [--limit N] [--label label[,label...]]... [--dry-run]", "bun scripts/cli.ts gh issue delete <number> [unsupported: use close]", "bun scripts/cli.ts gh issue scan-escape [--repo owner/name] [--limit N] [--dry-run]", @@ -6727,10 +6741,10 @@ export function ghHelp(): unknown { "bun scripts/cli.ts gh pr read <number|url|owner/repo#number> [--repo owner/name] [--number N compat] [--raw|--full] [compatibility alias for pr view]", "bun scripts/cli.ts gh pr preflight <number|owner/repo#number> [--repo owner/name] [--number N compat] [--full|--raw] [number may appear before or after options]", "bun scripts/cli.ts gh pr closeout <number|owner/repo#number> [--repo owner/name] [--number N compat] [--full|--raw] [number may appear before or after options; compatibility alias for pr preflight]", - "bun scripts/cli.ts gh pr create --title <title> --body-file <file>|--body <text> --base <branch> --head <branch> [--repo owner/name] [--draft] [--dry-run]", - "bun scripts/cli.ts gh pr edit <number> [--title title] [--body-file <file>|--body-file -|--body <text>] [--repo owner/name] [--number N compat] [--dry-run]", - "bun scripts/cli.ts gh pr update <number> --mode replace|append [--body-file <file>|--body-file -|--body <text>] [--title title] [--repo owner/name] [--number N compat] [--dry-run]", - "bun scripts/cli.ts gh pr comment create <number> --body-file <file>|--body <text> [--repo owner/name] [--number N compat] [--dry-run]", + "bun scripts/cli.ts gh pr create --title <title> (--body-stdin|--body-file <file|->|--body <text>) --base <branch> --head <branch> [--repo owner/name] [--draft] [--dry-run]", + "bun scripts/cli.ts gh pr edit <number> [--title title] [--body-stdin|--body-file <file|->|--body <text>] [--repo owner/name] [--number N compat] [--dry-run]", + "bun scripts/cli.ts gh pr update <number> --mode replace|append [--body-stdin|--body-file <file|->|--body <text>] [--title title] [--repo owner/name] [--number N compat] [--dry-run]", + "bun scripts/cli.ts gh pr comment create <number> (--body-stdin|--body-file <file|->|--body <text>) [--repo owner/name] [--number N compat] [--dry-run]", "bun scripts/cli.ts gh pr comment delete <commentId> [--repo owner/name] [--number N compat] [--dry-run]", "bun scripts/cli.ts gh pr close|reopen <number> [--repo owner/name] [--number N compat] [--dry-run]", "bun scripts/cli.ts gh pr merge <number> [--repo owner/name] [--number N compat] [--merge|--squash|--rebase] [--delete-branch] [--dry-run]", @@ -6747,17 +6761,17 @@ export function ghHelp(): unknown { "issue view is the canonical GitHub CLI-compatible read path; read remains a UniDesk compatibility alias. View/read accept positional numbers, GitHub issue URLs, and owner/repo#number shorthand, deriving --repo unless an explicit conflicting --repo is supplied. --number is accepted on single issue/comment numeric target commands for low-friction compatibility and returns a standard syntax hint; list/create/scan-escape/cleanup-plan/board-audit/board-row list do not accept it. Comment delete treats --number as commentId, not an issue number. View supports lifecycle fields closed/closedAt plus legacy --json field selection such as --json body and still exposes .data.issue.body for compatibility; unsupported fields fail structurally.", "--raw and --full are explicit full-disclosure aliases for gh issue list/read/view/update/edit and gh pr list/read/view. For issue writes, default success output omits full issue.body and returns bodyChars/bodySha/bodyPreview plus readCommands; --full|--raw includes the full returned issue body only on commands that explicitly support full disclosure.", "GitHub CLI output larger than 20 KiB is automatically written to /tmp/unidesk-cli-output/*.json; stdout stays bounded JSON with outputTruncated=true, the dump path, total bytes/lines, and head/tail previews.", - "issue create accepts --body-file <file|-> plus repeatable --label values and comma-separated labels; inline --body is intentionally unsupported for issue creation. Dry-run prints the parsed labels and non-dry-run sends them in the GitHub REST create-issue payload.", - "--body-file is the recommended source for Markdown bodies so real newlines, backticks, and tables are read as file bytes instead of shell arguments.", + "issue create accepts --body-stdin or --body-file <file|-> plus repeatable --label values and comma-separated labels; inline --body is intentionally unsupported for issue creation. Dry-run prints the parsed labels and non-dry-run sends them in the GitHub REST create-issue payload.", + "--body-stdin is the first-class heredoc/stdin source for Markdown bodies. Use quoted heredoc syntax such as bun scripts/cli.ts gh issue comment create 1 --body-stdin <<'EOF' so real newlines, backticks, and tables are read as stdin bytes instead of shell arguments.", "update defaults to --mode replace; --mode append reads the current body and appends file bytes so real newlines, backticks, and Markdown tables are preserved.", "issue edit is a compatibility alias for issue update --mode replace.", - "issue update --body-file accepts files or - for stdin, refuses literal null, blank, and too-short bodies by default. Use --allow-short-body only for intentional short writes; #20 requires its board heading, warns when HWLAB product/user issue routing appears in favor of pikasTech/HWLAB, and still rejects commander brief update sections; commander-brief requires its stable heading on legacy #24 plus daily rolling brief issues titled YYYY-MM-DD 指挥简报（北京时间）.", + "issue update accepts --body-stdin or --body-file <file|->, refuses literal null, blank, and too-short bodies by default. Use --allow-short-body only for intentional short writes; #20 requires its board heading, warns when HWLAB product/user issue routing appears in favor of pikasTech/HWLAB, and still rejects commander brief update sections; commander-brief requires its stable heading on legacy #24 plus daily rolling brief issues titled YYYY-MM-DD 指挥简报（北京时间）.", "issue update dry-run reports bounded bodyPreview/bodyPreviewLines, old/new body length slots, body SHA, required heading checks, literal \\n detection, shell-pollution signals, guard/concurrency summary, wouldPatch, and readCommands without printing an unbounded full body. Non-dry-run automatically reads current issue metadata before PATCH and returns oldBodySha/updatedAt; --expect-updated-at or --expect-body-sha remain available for explicit stale-cache protection.", - "issue comment create accepts --body-file <file|-> for Markdown/generated content and --body only for short single-line text. Blank, multiline, shell-polluted, secret-like, and overlong inline bodies fail structurally.", - "issue close/reopen default success output is compact and omits full issue.body. Optional --comment <short-text> or --comment-file <file|-> posts a bounded lifecycle comment before the state change and aborts the state change if the comment POST fails. --comment-file is the recommended path for generated Markdown closeout evidence; --comment remains the short inline form. Use gh issue view <number> --json body or --full/--raw on view when full text is needed.", + "issue comment create accepts --body-stdin or --body-file <file|-> for Markdown/generated content and --body only for short single-line text. Blank, multiline, shell-polluted, secret-like, and overlong inline bodies fail structurally.", + "issue close/reopen default success output is compact and omits full issue.body. Optional --comment <short-text>, --comment-stdin, or --comment-file <file|-> posts a bounded lifecycle comment before the state change and aborts the state change if the comment POST fails. --comment-stdin is the first-class heredoc path for generated Markdown closeout evidence; --comment remains the short inline form. Use gh issue view <number> --json body or --full/--raw on view when full text is needed.", "issue stale-close is the reusable lifecycle cleanup path for policies such as closing open issues inactive for more than 48 hours. It selects open issues by GitHub updatedAt older than observedAt - --inactive-hours, treats comments and state changes as activity, filters pull requests, supports --dry-run, and returns bounded candidate/closed/failure summaries without echoing full bodies.", - "For one-shot issue writes, pipe reviewed Markdown through stdin: cat body.md | bun scripts/cli.ts gh issue update <number> --repo owner/name --body-file - or gh issue comment create <number> --body-file -. 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 issue/PR Markdown writes use --body-file <file|-> for long or multiline content.", + "For one-shot issue writes, prefer quoted heredoc stdin: bun scripts/cli.ts gh issue update <number> --repo owner/name --body-stdin <<'EOF' ... EOF or gh issue comment create <number> --body-stdin <<'EOF' ... EOF. --body-file <file|-> remains available for reusable files and pipes.", + "For JSON request bodies in other CLI namespaces, prefer --body-file or --body-stdin over long inline shell arguments. GitHub issue/PR Markdown writes use --body-stdin for heredoc/stdin or --body-file <file|-> for reusable files.", "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 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 当前关注点.", @@ -6813,7 +6827,7 @@ export async function runGhCommand(args: string[]): Promise<GitHubCommandResult "bun scripts/cli.ts gh issue list --repo owner/name --limit 200 --full", "bun scripts/cli.ts gh issue view owner/name#<number> --raw", "bun scripts/cli.ts gh issue view <number> --repo owner/name --json body,title,state,comments", - "cat body.md | bun scripts/cli.ts gh issue update <number> --repo owner/name --body-file - --full", + "bun scripts/cli.ts gh issue update <number> --repo owner/name --body-stdin --full <<'EOF'\n<reviewed body>\nEOF", "bun scripts/cli.ts gh pr list --repo owner/name --limit 100 --full", "bun scripts/cli.ts gh pr view owner/name#<number> --raw", `bun scripts/cli.ts gh pr view <number> --repo owner/name --json ${readViewSupportedJsonFields("pr")}`,