From 05bc8aab5a1ee1d46444df6a7b5e182af9483c84 Mon Sep 17 00:00:00 2001 From: Codex Date: Wed, 20 May 2026 14:31:57 +0000 Subject: [PATCH] fix: harden gh issue escape hygiene --- AGENTS.md | 2 +- TEST.md | 4 + docs/reference/cli.md | 4 +- docs/reference/code-queue-supervision.md | 4 +- scripts/gh-cli-issue-guard-contract-test.ts | 111 +++++ scripts/src/check.ts | 3 + scripts/src/gh.ts | 485 ++++++++++++++++++-- 7 files changed, 575 insertions(+), 38 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 77fcc941..32a0f2b3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -43,7 +43,7 @@ UniDesk 是一个以主 server 为统一入口的分布式工作平台；本文 - `bun scripts/cli.ts deploy check/plan/apply [--file deploy.json|--env dev|prod] [--service ]`：按根目录 `deploy.json` 或 `origin/master:deploy.json#environments.` 的服务 repo 和 commit 期望状态校验或更新用户服务；`--env dev` 开放 D601 `backend-core` rollout、reviewed registry artifact consumers 和 D601 direct consumer validation，`findjob`/`pipeline` 是 D601 direct pull-only 样板，`met-nonlinear` dry-run blocked，`k3sctl-adapter` supervisor-only，`code-queue` prod unsupported，规则见 `docs/reference/deploy.md` 与 `docs/reference/dev-environment.md`。 - `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 gh auth status|issue ...|pr list|view|create|comment` / `bun scripts/code-queue-pr-preflight-example.ts`：通过 REST 执行安全 GitHub issue 读写、脱敏 auth/status 诊断、body-file Markdown 写入、#24 指挥简报新增时间线 ClaudeQQ 通知、escape 扫描、PR 创建/评论 dry-run 和 runner PR preflight；`gh pr merge` 当前仍结构化拒绝，规则见 `docs/reference/cli.md` 和 `docs/reference/code-queue-supervision.md`。 +- `bun scripts/cli.ts gh auth status|issue ...|pr list|view|create|comment` / `bun scripts/code-queue-pr-preflight-example.ts`：通过 REST 执行安全 GitHub issue 读写、脱敏 auth/status 诊断、body-file Markdown 写入、#24 指挥简报新增时间线 ClaudeQQ 通知、escape 扫描与只读 cleanup-plan、PR 创建/评论 dry-run 和 runner PR preflight；`gh pr merge` 当前仍结构化拒绝，规则见 `docs/reference/cli.md` 和 `docs/reference/code-queue-supervision.md`。 - `bun scripts/cli.ts ci install/status/run/publish-backend-core/publish-user-service/run-dev-e2e/logs`：在 D601 原生 k3s 上安装和运行 Tekton CI，支持每 commit 检查、Code Queue 只读性能门禁、`CI.json` catalog 驱动的 backend-core 与 user-service commit-pinned 镜像发布和手动触发的 `origin/master:deploy.json#environments.dev` 临时 namespace e2e；catalog/producer/consumer 分工见 `docs/reference/cicd-standardization.md`，`run-dev-e2e` 的 Git 控制 runner、短 launcher 和 no-CD 边界见 `docs/reference/dev-ci-runner.md`，Tekton 规则见 `docs/reference/ci.md`。 - `bun scripts/cli.ts codex deploy `：旧 Code Queue 兼容部署入口已禁用，原因是它会绕过受控部署边界直连 D601 部署 Code Queue；规则见 `docs/reference/codex-deploy.md`。 - `bun scripts/cli.ts codex submit [prompt] [--prompt-file path|--prompt-stdin] [--queue ]`：通过 backend-core 私有代理提交 Code Queue 任务；控制面默认走主 server `code-queue-mgr` 写入 PostgreSQL，`--dry-run` 可只检查请求体不入队，规则见 `docs/reference/cli.md`。 diff --git a/TEST.md b/TEST.md index 39f2824d..6214a1c4 100644 --- a/TEST.md +++ b/TEST.md @@ -130,3 +130,7 @@ ## T26 GitHub CLI PR 安全写入口 阅读 `AGENTS.md` 和 `docs/reference/cli.md`，然后用 cli 手动测试以下内容：准备一份包含真实换行、反引号和 Markdown 表格的临时正文文件，运行 `bun scripts/cli.ts gh help`，确认 help 中包含 `gh pr create` 和 `gh pr comment`。运行 `bun scripts/cli.ts gh pr create --repo pikasTech/unidesk --title --body-file <file> --base master --head <branch> --draft --dry-run`，确认命令不访问 GitHub、不创建 PR，JSON 中包含 `dryRun=true`、`planned=true`、repo、title、base、head、draft、bodyChars、bodyPreviewLines、request plan，并且正文预览保留真实换行和反引号。运行 `bun scripts/cli.ts gh pr comment <number> --repo pikasTech/unidesk --body-file <file> --dry-run`，确认命令不写评论，JSON 中包含 PR number、bodyChars、bodySource 和 request plan，且没有把换行污染成字面量 `\n`。运行 `bun scripts/cli.ts gh pr merge <number> --repo pikasTech/unidesk`，确认返回非零状态和结构化 JSON，`degradedReason=unsupported-command`、`runnerDisposition=business-failed`，且不会真实 merge。需要测试真实创建或评论时，只允许使用明确的 throwaway 源分支和 PR，并在记录中写明 PR URL、number、源/目标分支和清理动作；默认验收只做 dry-run，不创建真实 PR。 + +## T27 GitHub Issue/Comment 换行转义卫生扫描 + +阅读 `AGENTS.md` 和 `docs/reference/cli.md`，然后用 cli 手动测试以下内容：运行 `bun scripts/cli.ts gh help`，确认 help 中包含 `gh issue scan-escape` 和 `gh issue cleanup-plan`，notes 中明确推荐 `--body-file`、quoted heredoc 和只读 cleanup-plan。运行 `bun scripts/gh-cli-issue-guard-contract-test.ts`，确认 mock GitHub 覆盖污染命中、说明性 `\n` 命中不误报、短 body/null body guard、body-file dry-run 写入路径、comment-id/body-id 定位和 cleanupSuggestions。对真实仓库只允许运行 `bun scripts/cli.ts gh issue scan-escape --repo pikasTech/unidesk --limit <N> --dry-run` 或 `bun scripts/cli.ts gh issue cleanup-plan --repo pikasTech/unidesk --limit <N>`，确认输出 JSON 中包含 `classification=suspected-pollution|explanatory-mention|risk`、`bodyKind`、`bodyId`、`issueNumber`、`issueId`、`commentId`、`cleanupSuggestions` 和 diff-like preview；不得运行真实历史评论清理、不得改写 #20/#24 正文，除非另有明确人工指令并先审阅 `--body-file` dry-run。 diff --git a/docs/reference/cli.md b/docs/reference/cli.md index 8aaf9b01..c428f425 100644 --- a/docs/reference/cli.md +++ b/docs/reference/cli.md @@ -34,7 +34,7 @@ CLI 可以从 `master` 快速演进，但必须兼容 `deploy.json` 固定的 CI - `gh issue view <number> [--repo owner/name] [--json body,title,state,comments]` 通过 GitHub REST 读取 issue title/body/state/url 和 comments，默认输出 JSON；兼容旧脚本的 `--json body` 和 `--json body,title,state,comments` 字段选择，且正文仍稳定暴露在 `.data.issue.body`，避免调用方因为 JSON 路径变化把空值当成正文。字段白名单是 `body,title,state,comments,number,url,author,createdAt,updatedAt`，未知字段必须结构化失败并带 `runnerDisposition=business-failed`。`gh issue create --title <title> --body-file <file> [--dry-run]`、`gh issue update <number> --mode replace|append --body-file <file> [--title ...] [--dry-run]`、`gh issue comment create <number> --body-file <file> [--dry-run]`、`gh issue comment delete <commentId> [--dry-run]`、`gh issue close|reopen <number> [--dry-run]` 都走 REST，不依赖 `gh` binary。`gh issue delete <number>` 是结构化 `unsupported-command`，因为 GitHub REST 不支持 issue 硬删除；生命周期删除语义请使用 `close`。 - `gh issue update <number> --mode replace|append --body-file <file>` 是正文更新主入口，`edit` 保留为兼容别名。`replace` 用文件正文替换现有 body；`append` 先读取当前 body，再按 UTF-8 文件字节追加，保留真实换行、反引号和 Markdown 表格。更新默认拒绝字面量 `null`、空白正文和过短正文；只有真实需要写短正文时才允许显式加 `--allow-short-body`，返回 JSON 会报告该风险。#20 总看板和 #24 指挥简报是长期 body-only issue，`--body-profile auto` 会按 issue number 自动启用结构 guard：#20 必须包含 `## 看板（OPEN）`，#24 必须包含 `## 常驻观察与长期建议`；也可显式使用 `--body-profile code-queue-board|commander-brief`。`--dry-run` 不 PATCH GitHub，输出新正文长度、SHA、关键标题检查结果、字面量 `\n`、反引号、Markdown 表格和 shell 污染信号；若环境里有 `GH_TOKEN` 或 `GITHUB_TOKEN`，dry-run 还会只读抓取旧正文长度、SHA 和 `updatedAt` 作为更新前对照。正式写入可带 `--expect-updated-at <updated_at>` 或 `--expect-body-sha <sha256>`，CLI 会先读当前 issue，匹配后才 PATCH，防止旧缓存覆盖新正文。 - `gh issue edit 24 --body-file <file> --notify-claudeqq-brief-diff [--dry-run]` 是指挥简报 #24 的通知入口。正式执行会先读取 GitHub 上 #24 旧正文并通过 #24 body profile guard，再从 `--body-file` 读取新正文；随后先 PATCH issue 主体，再把本次新增的 `## 更新 YYYY-MM-DD HH:MM 北京时间` 段落发送给 ClaudeQQ，ClaudeQQ 失败不会回滚 issue 正文，失败只体现在返回 JSON 的 `claudeqq.ok=false` 和结构化 `degradedReason`。带通知 flag 的 `--dry-run` 不 PATCH、不发送；它按新正文做发送预览，并在输出中标明非 dry-run 才会读取旧正文做可靠 diff。默认 ClaudeQQ 目标是私聊 `645275593`，默认 base URL 是 UniDesk 受控入口 `http://backend-core:8080/api/microservices/claudeqq/proxy`，可用 `UNIDESK_COMMANDER_BRIEF_CLAUDEQQ_ENABLED`、`UNIDESK_COMMANDER_BRIEF_CLAUDEQQ_BASE_URL`、`UNIDESK_COMMANDER_BRIEF_CLAUDEQQ_TARGET_TYPE`、`UNIDESK_COMMANDER_BRIEF_CLAUDEQQ_USER_ID`、`UNIDESK_COMMANDER_BRIEF_CLAUDEQQ_GROUP_ID` 和 `UNIDESK_COMMANDER_BRIEF_CLAUDEQQ_TIMEOUT_MS` 覆盖。 -- `gh issue scan-escape [--repo owner/name] [--limit N]` 只读扫描 issue 主体和 comments 中的字面量 `\n`、可疑 `\t`、shell newline escape 和 ANSI escape 字符串，输出 issue/comment id、url、kind、snippet，不自动修复。`gh pr list|view [--json ...]` 提供 REST 列表和详情，PR 字段白名单是 `body,title,state,number,url,author,head,base,draft,createdAt,updatedAt`。`gh pr create --title <title> --body-file <file>|--body <text> --base <branch> --head <branch> [--draft] [--dry-run]`、`gh pr update <number> --mode replace|append --body-file <file>|--body <text> [--title ...] [--dry-run]`、`gh pr comment create <number> --body-file <file>|--body <text> [--dry-run]`、`gh pr comment delete <commentId> [--dry-run]`、`gh pr close|reopen <number> [--dry-run]` 是 PR CRUD/生命周期入口。`pr create --dry-run` 只输出 planned operation，不访问 GitHub；非 dry-run 创建前会校验 repo、base、head 和 compare ahead 状态，成功时返回 PR number/url。`pr update --mode append` 会先读取当前 PR body 再追加正文。`gh pr delete <number>` 和 `gh pr merge` 本阶段不开放，始终结构化返回 `unsupported-command`；PR 生命周期删除语义请使用 `close`。 +- `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|view [--json ...]` 提供 REST 列表和详情，PR 字段白名单是 `body,title,state,number,url,author,head,base,draft,createdAt,updatedAt`。`gh pr create --title <title> --body-file <file>|--body <text> --base <branch> --head <branch> [--draft] [--dry-run]`、`gh pr update <number> --mode replace|append --body-file <file>|--body <text> [--title ...] [--dry-run]`、`gh pr comment create <number> --body-file <file>|--body <text> [--dry-run]`、`gh pr comment delete <commentId> [--dry-run]`、`gh pr close|reopen <number> [--dry-run]` 是 PR CRUD/生命周期入口。`pr create --dry-run` 只输出 planned operation，不访问 GitHub；非 dry-run 创建前会校验 repo、base、head 和 compare ahead 状态，成功时返回 PR number/url。`pr update --mode append` 会先读取当前 PR body 再追加正文。`gh pr delete <number>` 和 `gh pr merge` 本阶段不开放，始终结构化返回 `unsupported-command`；PR 生命周期删除语义请使用 `close`。 - PR dry-run/probe 的最小手动序列是：`bun scripts/cli.ts gh auth status --repo pikasTech/unidesk` 只读检查 token 来源、GitHub REST egress、repo 可见性和 issue read；`bun scripts/cli.ts gh pr create --repo pikasTech/unidesk --title <title> --body-file <file> --base master --head <head> --dry-run` 检查创建计划；`bun scripts/cli.ts gh pr list --repo pikasTech/unidesk --limit 5 --json number,title,state,url,head,base` 和 `bun scripts/cli.ts gh pr view <number> --repo pikasTech/unidesk --json body,title,state,head,base` 做只读 PR 观察；`bun scripts/cli.ts gh pr comment <number> --repo pikasTech/unidesk --body-file <file> --dry-run` 检查评论计划；`bun scripts/cli.ts gh pr merge <number> --repo pikasTech/unidesk` 必须失败并返回结构化 `unsupported-command`。Code Queue runner 可用 `bun scripts/code-queue-pr-preflight-example.ts --repo pikasTech/unidesk --base master --head <head> --comment-pr <number>` 一次性跑只读 auth status 与 PR create/comment dry-run；该脚本不得输出 token 值，也不会创建、评论或 merge PR。 - `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 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`。 @@ -71,7 +71,7 @@ CLI 可以从 `master` 快速演进，但必须兼容 `deploy.json` 固定的 CI `microservice proxy` 是面向人工验证和受控调试的私有后端入口。默认 method 为 GET；使用 `--body-json JSON`、`--body-file path` 或 `--body-stdin` 时默认 method 切换为 POST，也可显式加 `--method POST|PUT|PATCH|DELETE`，但 GET/HEAD 不允许携带请求体。所有请求仍受 config 中的 `allowedMethods` 和 `allowedPathPrefixes` 限制。为了避免 Pipeline snapshot 这类超大业务 JSON 造成 CLI 输出爆炸，响应 body 超过默认阈值时会返回 `bodyOmitted=true`、`bodyPreview`、`bodyBytes` 和 `rawHint`；`--raw` 仍受默认硬限额保护，需要完整 body 时显式添加 `--raw --full`，或用 `--max-body-bytes <N>` 调整预览阈值。正式 frontend 展示仍应优先使用业务控件和 `__unideskArrayLimit` 这类展示级裁剪参数，而不是默认倾倒完整 JSON。 -GitHub issue/PR 写操作必须优先使用 `bun scripts/cli.ts gh issue|pr ... --body-file <file>`。不要把 Markdown 正文拼进 shell 参数、`gh issue comment --body` 或 `gh api -f body=...`；这些路径容易把真实换行污染成字面量 `\n`。`gh issue` 写命令第一阶段不接受 stdin 正文；需要从生成内容写入 issue 时，先落到临时 Markdown 文件或已审阅的工作文件，再把该文件路径传给 `--body-file`。PR 安全写入口同样优先 `--body-file`，`--body` 只适合短单行内容；`update --mode append` 用 REST 读取旧正文后追加文件字节，不引入 shell 拼接正文路径。`gh pr merge` 暂不开放，不存在 `--confirm` 可绕过的真实 merge 路径。CLI 会按 UTF-8 原样读取文件内容并用 JSON body 调用 REST API。 +GitHub issue/PR 写操作必须优先使用 `bun scripts/cli.ts gh issue|pr ... --body-file <file>`。不要把 Markdown 正文拼进 shell 参数、`gh issue comment --body` 或 `gh api -f body=...`；这些路径容易把真实换行污染成字面量 `\n`。从 shell 生成正文文件时使用 quoted heredoc，例如 `cat <<'EOF' > /tmp/body.md`，保证反引号、反斜杠和 Markdown 表格不被 shell 展开；之后再把文件交给 `--body-file`。`gh issue` 写命令不接受 stdin 正文；需要从生成内容写入 issue 时，先落到临时 Markdown 文件或已审阅的工作文件，再传给 `--body-file`。PR 安全写入口同样优先 `--body-file`，`--body` 只适合短单行内容。JSON 请求体场景使用各命名空间自己的 `--body-file` 或 `--body-stdin`，避免长 JSON 直接塞进 shell 参数；GitHub Markdown 写入仍只走 `--body-file`。`update --mode append` 用 REST 读取旧正文后追加文件字节，不引入 shell 拼接正文路径。`gh pr merge` 暂不开放，不存在 `--confirm` 可绕过的真实 merge 路径。CLI 会按 UTF-8 原样读取文件内容并用 JSON body 调用 REST API。 `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/docs/reference/code-queue-supervision.md b/docs/reference/code-queue-supervision.md index d3c68905..38fd4a97 100644 --- a/docs/reference/code-queue-supervision.md +++ b/docs/reference/code-queue-supervision.md @@ -70,11 +70,11 @@ issue 内容必须自包含，至少写清楚背景、外部收益、当前观 如果某个 worker 任务需要依赖 GitHub issue 内容，但 runner 的 issue 可达性尚未被单独验证，指挥官不能默认 worker 已能读取该 issue。此时 worker prompt 必须直接内嵌完整需求、约束和验收点，issue URL 只能作为辅助引用。若要把 issue 作为任务输入源，先单独做可达性探测，再决定是否把 issue 作为常规前置条件。 -GitHub issue/PR 操作应优先使用 UniDesk CLI 的安全入口：`bun scripts/cli.ts gh auth status`、`gh issue list/view/create/update/comment create/comment delete/close/reopen/scan-escape`、`gh pr list/view/create/update/comment create/comment delete/close/reopen`。该入口默认 repo 是 `pikasTech/unidesk`，支持 `--repo owner/name`，输出稳定 JSON，并把 `missing-binary`、`missing-token`、`auth-failed`、`network-proxy-failed`、`permission-denied`、`repo-not-found`、`repo-forbidden`、`issue-not-found`、`pr-not-found`、`scope-insufficient`、`validation-failed`、`invalid-response`、`unsupported-command` 等失败原因结构化。失败对象必须包含 `runnerDisposition=infra-blocked|business-failed`，runner 应用它区分基础设施阻塞和业务/参数失败。`gh issue list --state open --limit N --json number,title,state,url` 是有界 issue 发现入口，`--state` 只接受 `open|closed|all`，list 字段白名单是 `number,title,state,url,updatedAt,createdAt,author,labels`；未知 state 或未知字段必须失败，不能静默返回空数组。`gh issue view <number> --json body` 是兼容入口，正文仍应从 `.data.issue.body` 读取；未知 `--json` 字段必须失败，不得让调用方把空正文误判为读取成功。`gh pr list|view --json ...` 支持 `body,title,state,number,url,author,head,base,draft,createdAt,updatedAt` 字段白名单。issue/PR 创建、更新、评论、评论删除、关闭和重开使用 GitHub REST API；只要有 `GH_TOKEN` 或 `GITHUB_TOKEN`，就不依赖系统 `gh` binary。`gh` binary 只作为状态探测和 `gh auth token` fallback，不是写操作的主路径。GitHub 不支持 issue/PR 硬删除，`gh issue delete` 和 `gh pr delete` 必须结构化返回 `unsupported-command`；生命周期删除语义使用 `close`。`gh pr merge` 仍然不开放。 +GitHub issue/PR 操作应优先使用 UniDesk CLI 的安全入口：`bun scripts/cli.ts gh auth status`、`gh issue list/view/create/update/comment create/comment delete/close/reopen/scan-escape/cleanup-plan`、`gh pr list/view/create/update/comment create/comment delete/close/reopen`。该入口默认 repo 是 `pikasTech/unidesk`，支持 `--repo owner/name`，输出稳定 JSON，并把 `missing-binary`、`missing-token`、`auth-failed`、`network-proxy-failed`、`permission-denied`、`repo-not-found`、`repo-forbidden`、`issue-not-found`、`pr-not-found`、`scope-insufficient`、`validation-failed`、`invalid-response`、`unsupported-command` 等失败原因结构化。失败对象必须包含 `runnerDisposition=infra-blocked|business-failed`，runner 应用它区分基础设施阻塞和业务/参数失败。`gh issue list --state open --limit N --json number,title,state,url` 是有界 issue 发现入口，`--state` 只接受 `open|closed|all`，list 字段白名单是 `number,title,state,url,updatedAt,createdAt,author,labels`；未知 state 或未知字段必须失败，不能静默返回空数组。`gh issue view <number> --json body` 是兼容入口，正文仍应从 `.data.issue.body` 读取；未知 `--json` 字段必须失败，不得让调用方把空正文误判为读取成功。`gh issue scan-escape --limit N [--dry-run]` 与 `gh issue cleanup-plan` 只读扫描 issue body/comments 的字面量 `\n`、shell escape、短 body、blank/null body，输出 `classification=suspected-pollution|explanatory-mention|risk`、body/comment id、预览和清理建议；说明性提到 `\n` 不应被当成污染，cleanup-plan 永远不真实清理历史评论。`gh pr list|view --json ...` 支持 `body,title,state,number,url,author,head,base,draft,createdAt,updatedAt` 字段白名单。issue/PR 创建、更新、评论、评论删除、关闭和重开使用 GitHub REST API；只要有 `GH_TOKEN` 或 `GITHUB_TOKEN`，就不依赖系统 `gh` binary。`gh` binary 只作为状态探测和 `gh auth token` fallback，不是写操作的主路径。GitHub 不支持 issue/PR 硬删除，`gh issue delete` 和 `gh pr delete` 必须结构化返回 `unsupported-command`；生命周期删除语义使用 `close`。`gh pr merge` 仍然不开放。 CLI 是短 shout 的需求原语，不是长驻服务器进程。CLI 功能不好用、兼容性不足、安全 guard 不够或输出不利于 runner/指挥官使用时，应默认创建 GitHub issue 并用 Code Queue 推进；这类 CLI 问题走 `master`、remote commit、轻量 contract test 和文档更新，不套用 backend-core、Code Queue runtime 这类运行态服务的重部署门禁。若 CLI 缺陷已经阻塞当前指挥，可以先做最小安全绕行，同时把长期修复写入 issue 并派单。 -所有 GitHub Markdown 正文写入必须来自 `--body-file <file>`。不要使用 `gh issue comment --body`、`gh api -f body=...` 或把多行正文直接拼进 shell 参数；这些路径容易把真实换行、反引号和 Markdown 表格污染成字面量 `\n` 或 shell escape。`gh issue` 写命令第一阶段不接受 stdin 正文；需要更新 #20 总看板或创建新 issue/comment 时，先把正文写入 Markdown 文件，再运行 `bun scripts/cli.ts gh issue update|comment create|create ... --body-file <file>`。`gh issue update --mode replace|append --body-file` 是主更新入口，`edit` 只是兼容别名；`append` 会先读取当前正文再追加文件字节，保留真实换行、反引号和 Markdown 表格，不走 shell 拼接。`gh issue update --body-file` 默认拒绝 `null`、空白和过短正文；#20 自动要求 `## 看板（OPEN）`，#24 自动要求 `## 常驻观察与长期建议`。更新 body-only issue 前优先跑 `--dry-run`，查看旧/新正文长度、body SHA、关键标题、字面量 `\n` 和 shell 污染信号；正式写入长期正文时优先带上 `--expect-updated-at` 或 `--expect-body-sha`，避免旧缓存覆盖新正文。更新 #24 指挥简报主体时仍可使用兼容命令 `bun scripts/cli.ts gh issue edit 24 --body-file <file> --notify-claudeqq-brief-diff`，命令会先读取旧正文并只把本次新增的 `## 更新 ... 北京时间` 时间线段落推送给 ClaudeQQ；头部“常驻观察与长期建议”等非时间线修改不会单独通知。发送失败只体现在返回 JSON 的 `claudeqq.ok=false`，不回滚已经写入的 GitHub issue。提交前或巡检时可用 `gh issue scan-escape --limit N` 只读扫描污染，不自动修复。 +所有 GitHub Markdown 正文写入必须来自 `--body-file <file>`。不要使用 `gh issue comment --body`、`gh api -f body=...` 或把多行正文直接拼进 shell 参数；这些路径容易把真实换行、反引号和 Markdown 表格污染成字面量 `\n` 或 shell escape。从 shell 生成正文文件时使用 quoted heredoc，例如 `cat <<'EOF' > /tmp/body.md`，保证反引号和反斜杠不被展开；JSON 请求体场景优先使用对应 CLI 的 `--body-file` 或 `--body-stdin`，不要把长 JSON 塞进命令行参数。`gh issue` 写命令不接受 stdin 正文；需要更新 #20 总看板或创建新 issue/comment 时，先把正文写入 Markdown 文件，再运行 `bun scripts/cli.ts gh issue update|comment create|create ... --body-file <file>`。`gh issue update --mode replace|append --body-file` 是主更新入口，`edit` 只是兼容别名；`append` 会先读取当前正文再追加文件字节，保留真实换行、反引号和 Markdown 表格，不走 shell 拼接。`gh issue update --body-file` 默认拒绝 `null`、空白和过短正文；#20 自动要求 `## 看板（OPEN）`，#24 自动要求 `## 常驻观察与长期建议`。更新 body-only issue 前优先跑 `--dry-run`，查看旧/新正文长度、body SHA、关键标题、字面量 `\n` 和 shell 污染信号；正式写入长期正文时优先带上 `--expect-updated-at` 或 `--expect-body-sha`，避免旧缓存覆盖新正文。更新 #24 指挥简报主体时仍可使用兼容命令 `bun scripts/cli.ts gh issue edit 24 --body-file <file> --notify-claudeqq-brief-diff`，命令会先读取旧正文并只把本次新增的 `## 更新 ... 北京时间` 时间线段落推送给 ClaudeQQ；头部“常驻观察与长期建议”等非时间线修改不会单独通知。发送失败只体现在返回 JSON 的 `claudeqq.ok=false`，不回滚已经写入的 GitHub issue。提交前或巡检时可用 `gh issue scan-escape --limit N --dry-run` 或 `gh issue cleanup-plan --limit N` 只读扫描污染并生成建议，不自动修复。 PR 是审查型交付入口，不是所有 Code Queue 任务的默认出口。默认 master-only 交付仍按项目 Git 规则执行；当变更风险高、跨模块、需要人工审查、或任务目标明确要求 PR 交付时，worker 可以创建 PR。PR 型任务必须报告源分支、目标分支、PR URL、关联 issue、测试证据和未完成风险。禁止把 PR 当成隐藏分支仓库；PR 分支必须来自最新目标线，保持小而可审查，并在合并后确认目标分支远端 commit 可 fetch。 diff --git a/scripts/gh-cli-issue-guard-contract-test.ts b/scripts/gh-cli-issue-guard-contract-test.ts index 01e2ade7..dee0d269 100644 --- a/scripts/gh-cli-issue-guard-contract-test.ts +++ b/scripts/gh-cli-issue-guard-contract-test.ts @@ -128,6 +128,47 @@ async function startMockGitHub(): Promise<{ baseUrl: string; requests: MockReque updated_at: "2026-05-20T03:10:00Z", }, ]; + const scanIssues = [ + { + id: 2501, + number: 51, + title: "polluted issue", + body: "## Update\\n- item with `code`\\n| a | b |\\n", + state: "open", + html_url: "https://github.com/pikasTech/unidesk/issues/51", + comments: 1, + user: { login: "runner" }, + labels: [], + created_at: "2026-05-20T04:00:00Z", + updated_at: "2026-05-20T04:30:00Z", + }, + { + id: 2502, + number: 52, + title: "explanatory issue", + body: "文档说明：字面量 `\\n` 只是在示例中提到，不代表正文污染。\n", + state: "open", + html_url: "https://github.com/pikasTech/unidesk/issues/52", + comments: 1, + user: { login: "runner" }, + labels: [], + created_at: "2026-05-20T04:05:00Z", + updated_at: "2026-05-20T04:35:00Z", + }, + { + id: 2503, + number: 53, + title: "null body issue", + body: null, + state: "open", + html_url: "https://github.com/pikasTech/unidesk/issues/53", + comments: 0, + user: { login: "runner" }, + labels: [], + created_at: "2026-05-20T04:10:00Z", + updated_at: "2026-05-20T04:40:00Z", + }, + ]; const comments = [ { id: 1, @@ -138,6 +179,29 @@ async function startMockGitHub(): Promise<{ baseUrl: string; requests: MockReque updated_at: "2026-05-20T00:30:00Z", }, ]; + const scanComments: Record<number, JsonRecord[]> = { + 51: [ + { + id: 5101, + body: "comment line 1\\ncomment line 2\\twith tab", + html_url: "https://github.com/pikasTech/unidesk/issues/51#issuecomment-5101", + user: { login: "runner" }, + created_at: "2026-05-20T04:40:00Z", + updated_at: "2026-05-20T04:40:00Z", + }, + ], + 52: [ + { + id: 5201, + body: "说明性提到字面量 `\\n`，用于描述问题本身。", + html_url: "https://github.com/pikasTech/unidesk/issues/52#issuecomment-5201", + user: { login: "runner" }, + created_at: "2026-05-20T04:45:00Z", + updated_at: "2026-05-20T04:45:00Z", + }, + ], + 53: [], + }; const server = createServer(async (req, res) => { const body = await collectBody(req); requests.push({ method: req.method ?? "", url: req.url ?? "", body }); @@ -161,6 +225,16 @@ async function startMockGitHub(): Promise<{ baseUrl: string; requests: MockReque sendJson(res, 200, issueList); return; } + if (req.method === "GET" && req.url === "/repos/pikasTech/unidesk/issues?state=all&per_page=4") { + sendJson(res, 200, scanIssues); + return; + } + for (const [issueNumber, issueComments] of Object.entries(scanComments)) { + if (req.method === "GET" && req.url === `/repos/pikasTech/unidesk/issues/${issueNumber}/comments?per_page=100`) { + sendJson(res, 200, issueComments); + return; + } + } if (req.method === "PATCH" && req.url === "/repos/pikasTech/unidesk/issues/20") { const parsed = JSON.parse(body) as JsonRecord; sendJson(res, 200, { ...issue, body: String(parsed.body ?? issue.body), updated_at: "2026-05-20T01:05:00Z" }); @@ -225,6 +299,33 @@ export async function runGhCliIssueGuardContract(): Promise<JsonRecord> { assertCondition(Array.isArray(firstLabels) && firstLabels[0]?.name === "cli", "issue list default fields should include labels", listDefaultData); assertCondition(defaultIssues.every((item) => typeof item.number === "number" && typeof item.url === "string"), "issue list default fields should expose stable JSON", listDefaultData); + const scanEscape = await runCli(["gh", "issue", "scan-escape", "--repo", "pikasTech/unidesk", "--limit", "4", "--dry-run"], env); + assertCondition(scanEscape.status === 0, "issue scan-escape dry-run should succeed", scanEscape.json ?? { stdout: scanEscape.stdout }); + const scanData = dataOf(scanEscape.json ?? {}); + assertCondition(scanData.dryRun === true && scanData.planned === true, "scan-escape dry-run should be explicit", scanData); + const scanSummary = scanData.summary as JsonRecord; + assertCondition(Number(scanSummary.suspectedPollution ?? 0) >= 2, "scan should find suspected pollution in body/comment", scanSummary); + assertCondition(Number(scanSummary.explanatoryMention ?? 0) >= 1, "scan should classify explanatory literal backslash-n separately", scanSummary); + assertCondition(Number(scanSummary.bodyRisks ?? 0) >= 1, "scan should report null/short body risks", scanSummary); + const scanFindings = scanData.findings as JsonRecord[]; + assertCondition(Array.isArray(scanFindings), "scan should expose findings array", scanData); + assertCondition(scanFindings.some((finding) => finding.issueNumber === 51 && finding.classification === "suspected-pollution" && finding.bodyKind === "issue-body" && typeof finding.bodyId === "string"), "polluted issue body should be suspected with body id", scanFindings); + assertCondition(scanFindings.some((finding) => finding.commentId === 5101 && finding.classification === "suspected-pollution" && finding.bodyKind === "comment-body" && String(finding.bodyId ?? "").includes("comment:5101")), "polluted comment should include comment id and body id", scanFindings); + assertCondition(scanFindings.some((finding) => finding.issueNumber === 52 && finding.classification === "explanatory-mention"), "explanatory literal backslash-n should not be pollution", scanFindings); + 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.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; + assertCondition(scanPatchCount === 0, "scan-escape must not write GitHub", { requests: mock.requests }); + + const cleanupPlan = await runCli(["gh", "issue", "cleanup-plan", "--repo", "pikasTech/unidesk", "--limit", "4"], env); + assertCondition(cleanupPlan.status === 0, "issue cleanup-plan should succeed as read-only alias", cleanupPlan.json ?? { stdout: cleanupPlan.stdout }); + const cleanupPlanData = dataOf(cleanupPlan.json ?? {}); + assertCondition(cleanupPlanData.command === "issue cleanup-plan" && cleanupPlanData.dryRun === true, "cleanup-plan should remain dry-run", cleanupPlanData); + const badListField = await runCli(["gh", "issue", "list", "--repo", "pikasTech/unidesk", "--json", "number,body"], env); assertCondition(badListField.status !== 0, "issue list unsupported --json field should fail", badListField.json ?? { stdout: badListField.stdout }); const badListFieldData = failedDataOf(badListField.json ?? {}); @@ -314,6 +415,13 @@ export async function runGhCliIssueGuardContract(): Promise<JsonRecord> { const appendFile = join(tmp, "append.md"); writeFileSync(appendFile, "\n- appended `code`\n| c | d |\n| --- | --- |\n| 3 | 4 |\n", "utf8"); + const issueCreateDryRun = await runCli(["gh", "issue", "create", "--repo", "pikasTech/unidesk", "--title", "body file dry-run", "--body-file", appendFile, "--dry-run"], env); + assertCondition(issueCreateDryRun.status === 0, "issue create dry-run should succeed", issueCreateDryRun.json ?? { stdout: issueCreateDryRun.stdout }); + const issueCreateDryRunData = dataOf(issueCreateDryRun.json ?? {}); + const issueCreateBodySource = issueCreateDryRunData.bodySource as JsonRecord; + assertCondition(issueCreateDryRunData.planned === true && issueCreateBodySource.kind === "body-file" && issueCreateBodySource.path === appendFile, "issue create dry-run should expose body-file source", issueCreateDryRunData); + assertCondition(issueCreateDryRunData.request && typeof issueCreateDryRunData.request === "object", "issue create dry-run should expose request plan", issueCreateDryRunData); + const appendDryRun = await runCli(["gh", "issue", "update", "20", "--repo", "pikasTech/unidesk", "--mode", "append", "--body-file", appendFile, "--dry-run"], env); assertCondition(appendDryRun.status === 0, "issue update append dry-run should succeed", appendDryRun.json ?? { stdout: appendDryRun.stdout }); const appendData = dataOf(appendDryRun.json ?? {}); @@ -354,6 +462,9 @@ export async function runGhCliIssueGuardContract(): Promise<JsonRecord> { "issue list supports state/limit/json with stable selected fields", "acceptance issue list command succeeds under mock GitHub", "issue list default fields include labels and filter pull requests", + "issue scan-escape classifies pollution, explanatory mentions, and body risks", + "issue cleanup-plan remains dry-run with body/comment cleanup suggestions", + "issue create dry-run exposes body-file source and request plan", "issue list unsupported fields and states fail structurally", "issue view supports body,title,state,comments selection", "unsupported --json fields fail structurally", diff --git a/scripts/src/check.ts b/scripts/src/check.ts index 4835be32..0ace5492 100644 --- a/scripts/src/check.ts +++ b/scripts/src/check.ts @@ -284,6 +284,7 @@ export function runChecks(config: UniDeskConfig, options: CheckOptions = default fileItem("scripts/src/ci.ts"), fileItem("scripts/src/e2e.ts"), fileItem("scripts/code-queue-prompt-observation-test.ts"), + fileItem("scripts/gh-cli-issue-guard-contract-test.ts"), fileItem("scripts/gh-cli-pr-contract-test.ts"), fileItem("scripts/code-queue-pr-preflight-example.ts"), fileItem("scripts/schedule-cli-contract-test.ts"), @@ -305,6 +306,7 @@ export function runChecks(config: UniDeskConfig, options: CheckOptions = default items.push(commandItem("code-queue:oa-publisher-degraded-visible", ["bun", "scripts/code-queue-liveness-diagnostics-test.ts", "--only", "code-queue:oa-publisher-degraded-visible"], 30_000)); items.push(commandItem("baidu-netdisk:artifact-guard-contract", ["bun", "scripts/baidu-netdisk-artifact-guard-contract-test.ts"], 30_000)); items.push(commandItem("schedule:cli-contract", ["bun", "scripts/schedule-cli-contract-test.ts"], 30_000)); + items.push(commandItem("gh:issue-guard-contract", ["bun", "scripts/gh-cli-issue-guard-contract-test.ts"], 30_000)); items.push(commandItem("gh:pr-contract", ["bun", "scripts/gh-cli-pr-contract-test.ts"], 30_000)); } else { items.push(skippedItem("typescript:scripts", "scripts TypeScript typecheck is opt-in", "--scripts-typecheck or --full")); @@ -314,6 +316,7 @@ export function runChecks(config: UniDeskConfig, options: CheckOptions = default items.push(skippedItem("code-queue:liveness-diagnostics-fixtures", "Code Queue liveness diagnostics fixtures are opt-in with script checks", "--scripts-typecheck or --full")); items.push(skippedItem("baidu-netdisk:artifact-guard-contract", "Baidu Netdisk artifact guard contract is opt-in with script checks", "--scripts-typecheck or --full")); items.push(skippedItem("schedule:cli-contract", "Schedule CLI contract is opt-in with script checks", "--scripts-typecheck or --full")); + items.push(skippedItem("gh:issue-guard-contract", "GitHub issue CLI contract is opt-in with script checks", "--scripts-typecheck or --full")); items.push(skippedItem("gh:pr-contract", "GitHub PR CLI contract is opt-in with script checks", "--scripts-typecheck or --full")); } if (options.logs) { diff --git a/scripts/src/gh.ts b/scripts/src/gh.ts index c0514eff..9b0685ac 100644 --- a/scripts/src/gh.ts +++ b/scripts/src/gh.ts @@ -18,6 +18,8 @@ const ISSUE_LIST_JSON_FIELDS = ["number", "title", "state", "url", "updatedAt", const PR_JSON_FIELDS = ["body", "title", "state", "number", "url", "author", "head", "base", "draft", "createdAt", "updatedAt"] as const; const ISSUE_LIST_STATES = ["open", "closed", "all"] as const; const BODY_UPDATE_MODES = ["replace", "append"] as const; +const MIN_SAFE_BODY_SCAN_CHARS = MIN_SAFE_ISSUE_BODY_CHARS; +const ISSUE_SCAN_MAX_FINDINGS = 60; const ISSUE_BODY_PROFILES = { "code-queue-board": { label: "Code Queue long board issue #20", @@ -38,6 +40,10 @@ type IssueListState = typeof ISSUE_LIST_STATES[number]; type BodyUpdateMode = typeof BODY_UPDATE_MODES[number]; type IssueBodyProfileName = keyof typeof ISSUE_BODY_PROFILES; 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 GitHubDegradedReason = | "missing-binary" @@ -106,6 +112,69 @@ interface CommanderBriefSection { startLine: number; } +interface EscapePatternDefinition { + kind: string; + pattern: RegExp; + description: string; +} + +interface EscapeMatchFinding { + type: "issue" | "comment"; + bodyKind: EscapeBodyKind; + bodyId: string; + issueNumber: number; + issueId: number; + commentId?: number; + url: string; + kind: string; + classification: EscapeFindingClassification; + severity: EscapeFindingSeverity; + reason: string; + snippet: string; + lineNumber: number; + column: number; + match: string; + bodyChars: number | null; + bodyTrimmedChars: number | null; + cleanupPreview?: { + before: string; + after: string; + }; +} + +interface EscapeCleanupSuggestion { + type: EscapeBodyKind; + bodyId: string; + issueNumber: number; + issueId: number; + commentId?: number; + url: string; + classification: EscapeFindingClassification; + action: CleanupSuggestionAction; + reason: string; + findings: Array<Pick<EscapeMatchFinding, "kind" | "classification" | "severity" | "lineNumber" | "column" | "snippet" | "match">>; + plannedCommand?: string; + bodyFileHint?: string; + preview?: { + before: string; + after: string; + }; +} + +interface EscapeScanErrorFinding { + type: "comment-scan-error"; + bodyKind: EscapeBodyKind; + bodyId: string; + issueNumber: number; + issueId: number; + url: string; + degradedReason: GitHubDegradedReason; + runnerDisposition: RunnerDisposition; + details: GitHubErrorPayload; +} + +type EscapeScanEntry = EscapeMatchFinding | EscapeScanErrorFinding; + interface GitHubCommandResult { ok: boolean; repo: string; @@ -788,6 +857,32 @@ function commanderBriefNotificationPlan(issueNumber: number, body: string, diff: }; } +function writeBodyPlan(command: "issue create" | "issue comment create" | "pr create" | "pr comment", repo: string, body: string, bodySource: Record<string, unknown>, extra: Record<string, unknown> = {}): Record<string, unknown> { + const isIssueWrite = command === "issue create" || command === "issue comment create"; + return { + repo, + bodySource, + bodyPreview: preview(body), + bodyPreviewLines: previewLines(body), + ...bodySafetySignals(body), + request: { + method: "POST", + path: isIssueWrite + ? (command === "issue create" ? "/repos/{owner}/{repo}/issues" : "/repos/{owner}/{repo}/issues/{issue_number}/comments") + : (command === "pr create" ? "/repos/{owner}/{repo}/pulls" : "/repos/{owner}/{repo}/issues/{issue_number}/comments"), + body: { + bodyChars: body.length, + bodySource, + }, + }, + validation: { + source: String(bodySource.kind ?? "unknown"), + rawText: "read from file bytes without shell interpolation", + }, + ...extra, + }; +} + function runnerDisposition(reason: GitHubDegradedReason): RunnerDisposition { if (reason === "unsupported-command" || reason === "validation-failed" || reason === "issue-not-found" || reason === "pr-not-found") return "business-failed"; return "infra-blocked"; @@ -1523,11 +1618,22 @@ async function issueList(repo: string, token: string, state: IssueListState, lim async function issueCreate(repo: string, token: string, options: GitHubOptions): Promise<GitHubCommandResult> { if (options.title === undefined) throw new Error("issue create requires --title <title>"); const body = readBodyFile(options.bodyFile, "issue create"); - if (options.dryRun) return { ok: true, command: "issue create", repo, dryRun: true, ...dryRunBody(repo, options.title, body) }; + const bodySource = { kind: "body-file", path: options.bodyFile ?? null }; + if (options.dryRun) { + return { + ok: true, + command: "issue create", + repo, + dryRun: true, + planned: true, + title: options.title, + ...writeBodyPlan("issue create", repo, body, bodySource, { title: options.title }), + }; + } const { owner, name } = repoParts(repo); const issue = await githubRequest<GitHubIssue>(token, "POST", `/repos/${owner}/${name}/issues`, { title: options.title, body }); if (isGitHubError(issue)) return commandError("issue create", repo, issue); - return { ok: true, command: "issue create", repo, issue: issueSummary(issue), rest: true }; + return { ok: true, command: "issue create", repo, issue: issueSummary(issue), bodySource, rest: true }; } async function issueEdit(repo: string, token: string, issueNumber: number, options: GitHubOptions, commandName = "issue edit"): Promise<GitHubCommandResult> { @@ -1679,11 +1785,22 @@ async function issueEdit(repo: string, token: string, issueNumber: number, optio async function issueComment(repo: string, token: string, issueNumber: number, options: GitHubOptions): Promise<GitHubCommandResult> { const body = readBodyFile(options.bodyFile, "issue comment"); - if (options.dryRun) return { ok: true, command: "issue comment create", repo, dryRun: true, issueNumber, ...dryRunBody(repo, undefined, body) }; + const bodySource = { kind: "body-file", path: options.bodyFile ?? null }; + if (options.dryRun) { + return { + ok: true, + command: "issue comment create", + repo, + dryRun: true, + planned: true, + issueNumber, + ...writeBodyPlan("issue comment create", repo, body, bodySource, { issueNumber }), + }; + } const { owner, name } = repoParts(repo); const comment = await githubRequest<GitHubComment>(token, "POST", `/repos/${owner}/${name}/issues/${issueNumber}/comments`, { body }); if (isGitHubError(comment)) return commandError("issue comment", repo, comment, { issueNumber }); - return { ok: true, command: "issue comment create", repo, comment: commentSummary(comment), rest: true }; + return { ok: true, command: "issue comment create", repo, issueNumber, comment: commentSummary(comment), bodySource, rest: true }; } async function commentDelete(repo: string, token: string, ownerKind: "issue" | "pr", commentId: number, dryRun: boolean): Promise<GitHubCommandResult> { @@ -1721,48 +1838,316 @@ async function issueState(repo: string, token: string, issueNumber: number, stat return { ok: true, command: state === "closed" ? "issue close" : "issue reopen", repo, issue: issueSummary(issue), rest: true }; } -function escapeSnippet(text: string, index: number): string { - const start = Math.max(0, index - 80); - const end = Math.min(text.length, index + 120); +function escapeSnippet(text: string, index: number, radius = 80): string { + const start = Math.max(0, index - radius); + const end = Math.min(text.length, index + radius + 40); return text.slice(start, end).replace(/\n/g, "\\n"); } -function scanText(text: string, patterns: Array<{ kind: string; pattern: RegExp }>): Array<{ kind: string; snippet: string }> { - const findings: Array<{ kind: string; snippet: string }> = []; +function lineColumnAt(text: string, index: number): { lineNumber: number; column: number } { + let lineNumber = 1; + let column = 1; + for (let cursor = 0; cursor < index && cursor < text.length; cursor += 1) { + if (text[cursor] === "\n") { + lineNumber += 1; + column = 1; + } else { + column += 1; + } + } + return { lineNumber, column }; +} + +function lineTextAt(text: string, lineNumber: number): string { + const lines = text.split(/\r?\n/); + return lines[lineNumber - 1] ?? ""; +} + +function isInsideFencedCodeBlock(text: string, index: number): boolean { + const lines = text.slice(0, index).split(/\r?\n/); + let openFence = false; + for (const line of lines) { + const trimmed = line.trimStart(); + if (trimmed.startsWith("```") || trimmed.startsWith("~~~")) openFence = !openFence; + } + return openFence; +} + +function isInsideInlineCode(text: string, index: number): boolean { + const { lineNumber, column } = lineColumnAt(text, index); + const line = lineTextAt(text, lineNumber); + const before = line.slice(0, Math.max(0, column - 1)); + const after = line.slice(Math.max(0, column - 1)); + return (before.match(/`/g)?.length ?? 0) % 2 === 1 && (after.match(/`/g)?.length ?? 0) > 0; +} + +function isExplanatoryLiteralBackslashN(text: string, index: number): boolean { + if (isInsideFencedCodeBlock(text, index) || isInsideInlineCode(text, index)) return true; + const window = text.slice(Math.max(0, index - 90), Math.min(text.length, index + 90)).toLowerCase(); + return [ + "字面量", + "说明", + "示例", + "举例", + "提到", + "引用", + "文本", + "字符串", + "escape", + "literal", + "example", + "mention", + "quoted", + "反斜杠", + ].some((keyword) => window.includes(keyword)); +} + +function cleanupEscapedText(text: string): string { + return text + .replace(/\\r\\n/g, "\n") + .replace(/\\n/g, "\n") + .replace(/\\t/g, "\t") + .replace(/\\x0a/gi, "\n") + .replace(/\\x1b/gi, "") + .replace(/\\u001b/gi, "") + .replace(/\\033/g, "") + .replace(/\\`/g, "`"); +} + +function escapeBodyId(bodyKind: EscapeBodyKind, issueNumber: number, issueId: number, commentId?: number): string { + return bodyKind === "issue-body" + ? `issue:${issueNumber}:body:${issueId}` + : `issue:${issueNumber}:comment:${commentId ?? "unknown"}`; +} + +function textFindingPatterns(): EscapePatternDefinition[] { + return [ + { + kind: "literal-backslash-n", + pattern: /\\n/g, + description: "literal backslash-n", + }, + { + kind: "literal-backslash-t", + pattern: /\\t/g, + description: "literal backslash-t", + }, + { + kind: "escaped-backtick", + pattern: /\\`/g, + description: "escaped backtick", + }, + { + kind: "shell-escaped-newline", + pattern: /\\r\\n|\\012|\\x0a/gi, + description: "shell escaped newline", + }, + { + kind: "ansi-escape-literal", + pattern: /\\x1b|\\u001b|\\033/gi, + description: "ANSI escape literal", + }, + ]; +} + +function bodyRiskFindings(kind: EscapeBodyKind, issueNumber: number, issueId: number, body: string | null, url: string, commentId?: number): EscapeMatchFinding[] { + const bodyChars = body === null ? null : body.length; + const bodyTrimmedChars = body === null ? null : body.trim().length; + const location = { + type: kind === "issue-body" ? "issue" as const : "comment" as const, + bodyKind: kind, + bodyId: escapeBodyId(kind, issueNumber, issueId, commentId), + issueNumber, + issueId, + ...(commentId === undefined ? {} : { commentId }), + url, + bodyChars, + bodyTrimmedChars, + }; + if (body === null) { + return [{ + ...location, + kind: "null-body", + classification: "risk", + severity: "high", + reason: "GitHub returned a null body", + snippet: "", + lineNumber: 0, + column: 0, + match: "", + }]; + } + const trimmed = body.trim(); + if (trimmed.toLowerCase() === "null") { + return [{ + ...location, + kind: "literal-null-body", + classification: "risk", + severity: "high", + reason: "body text is the literal string null", + snippet: escapeSnippet(body, 0), + lineNumber: 1, + column: 1, + match: "null", + }]; + } + if (trimmed.length === 0) { + return [{ + ...location, + kind: "blank-body", + classification: "risk", + severity: "medium", + reason: "body is blank after trimming", + snippet: "", + lineNumber: 0, + column: 0, + match: "", + }]; + } + if (trimmed.length < MIN_SAFE_BODY_SCAN_CHARS) { + return [{ + ...location, + kind: "short-body", + classification: "risk", + severity: "medium", + reason: `body is shorter than the safe guard threshold (${MIN_SAFE_BODY_SCAN_CHARS} chars)`, + snippet: escapeSnippet(body, 0), + lineNumber: 1, + column: 1, + match: "", + }]; + } + return []; +} + +function scanText(text: string, patterns: EscapePatternDefinition[], issueNumber: number, issueId: number, bodyKind: EscapeBodyKind, url: string, commentId?: number): EscapeMatchFinding[] { + const findings: EscapeMatchFinding[] = []; + const counts = new Map<string, number>(); + for (const item of patterns) { + item.pattern.lastIndex = 0; + const matches = text.match(item.pattern); + counts.set(item.kind, matches === null ? 0 : matches.length); + } for (const item of patterns) { item.pattern.lastIndex = 0; let match = item.pattern.exec(text); while (match !== null) { - findings.push({ kind: item.kind, snippet: escapeSnippet(text, match.index) }); - if (findings.length >= 5) return findings; + const { lineNumber, column } = lineColumnAt(text, match.index); + const explanatory = item.kind === "literal-backslash-n" && counts.get(item.kind) === 1 && isExplanatoryLiteralBackslashN(text, match.index); + const classification: EscapeFindingClassification = explanatory ? "explanatory-mention" : "suspected-pollution"; + const severity: EscapeFindingSeverity = explanatory ? "low" : item.kind === "ansi-escape-literal" ? "high" : "medium"; + findings.push({ + type: bodyKind === "issue-body" ? "issue" : "comment", + bodyKind, + bodyId: escapeBodyId(bodyKind, issueNumber, issueId, commentId), + issueNumber, + issueId, + ...(commentId === undefined ? {} : { commentId }), + url, + kind: item.kind, + classification, + severity, + reason: explanatory + ? "literal backslash-n appears in explanatory context" + : `matched ${item.description}`, + snippet: escapeSnippet(text, match.index), + lineNumber, + column, + match: match[0], + bodyChars: text.length, + bodyTrimmedChars: text.trim().length, + ...(classification === "suspected-pollution" + ? { cleanupPreview: { before: escapeSnippet(text, match.index), after: escapeSnippet(cleanupEscapedText(text), match.index) } } + : {}), + }); + if (findings.length >= ISSUE_SCAN_MAX_FINDINGS) return findings; match = item.pattern.exec(text); } } return findings; } -async function issueScanEscape(repo: string, token: string, limit: number): Promise<GitHubCommandResult> { +function summarizeCleanupSuggestion(findings: EscapeScanEntry[]): EscapeCleanupSuggestion[] { + const groups = new Map<string, EscapeMatchFinding[]>(); + for (const finding of findings) { + if (finding.type === "comment-scan-error") continue; + if (finding.classification !== "suspected-pollution" && finding.kind !== "short-body" && finding.kind !== "null-body" && finding.kind !== "blank-body" && finding.kind !== "literal-null-body") continue; + const locatorKey = `${finding.bodyKind}:${finding.issueNumber}:${finding.issueId}:${finding.commentId ?? ""}`; + const list = groups.get(locatorKey); + if (list === undefined) groups.set(locatorKey, [finding]); + else list.push(finding); + } + + const suggestions: EscapeCleanupSuggestion[] = []; + for (const group of groups.values()) { + const first = group[0]; + const suspected = group.some((finding) => finding.classification === "suspected-pollution"); + const bodyRisk = group.some((finding) => finding.classification === "risk"); + suggestions.push({ + type: first.bodyKind, + bodyId: first.bodyId, + issueNumber: first.issueNumber, + issueId: first.issueId, + ...(first.commentId === undefined ? {} : { commentId: first.commentId }), + url: first.url, + classification: suspected ? "suspected-pollution" : "risk", + action: first.bodyKind === "issue-body" + ? (suspected ? "rewrite-issue-body-with-body-file" : "review-body-length") + : "review-comment-manually", + reason: suspected + ? "suspected shell escape pollution should be rewritten from a body file" + : bodyRisk + ? "body length/null risk should be reviewed before any write" + : "no cleanup needed", + findings: group.map((finding) => ({ + kind: finding.kind, + classification: finding.classification, + severity: finding.severity, + lineNumber: finding.lineNumber, + column: finding.column, + snippet: finding.snippet, + match: finding.match, + })), + ...(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", + preview: { + before: first.cleanupPreview?.before ?? first.snippet, + after: first.cleanupPreview?.after ?? first.snippet, + }, + } + : { + preview: { + before: first.cleanupPreview?.before ?? first.snippet, + after: first.cleanupPreview?.after ?? first.snippet, + }, + }), + }); + } + return suggestions; +} + +async function issueScanEscape(repo: string, token: string, limit: number, dryRun: boolean, commandName = "issue scan-escape"): Promise<GitHubCommandResult> { const { owner, name } = repoParts(repo); const issues = await githubRequest<GitHubIssue[]>(token, "GET", `/repos/${owner}/${name}/issues?state=all&per_page=${limit}`); - if (isGitHubError(issues)) return commandError("issue scan-escape", repo, issues); + if (isGitHubError(issues)) return commandError(commandName, repo, issues); + const issueOnly = issues.filter((issue) => issue.pull_request === undefined).slice(0, limit); - const patterns = [ - { kind: "literal-backslash-n", pattern: /\\n/g }, - { kind: "literal-backslash-t", pattern: /\\t/g }, - { kind: "shell-escaped-newline", pattern: /\\r\\n|\\012|\\x0a/g }, - { kind: "ansi-escape-literal", pattern: /\\u001b|\\033/g }, - ]; - - const findings: Array<Record<string, unknown>> = []; - for (const issue of issues) { - for (const finding of scanText(issue.body ?? "", patterns)) { - findings.push({ type: "issue", issueNumber: issue.number, id: issue.id, url: issue.html_url, ...finding }); - } + const patterns = textFindingPatterns(); + const findings: EscapeScanEntry[] = []; + let scannedComments = 0; + for (const issue of issueOnly) { + findings.push(...bodyRiskFindings("issue-body", issue.number, issue.id, issue.body, issue.html_url)); + findings.push(...scanText(issue.body ?? "", patterns, issue.number, issue.id, "issue-body", issue.html_url)); const comments = await listIssueComments(token, repo, issue.number); if (isGitHubError(comments)) { findings.push({ type: "comment-scan-error", + bodyKind: "comment-body", + bodyId: escapeBodyId("comment-body", issue.number, issue.id), issueNumber: issue.number, + issueId: issue.id, url: issue.html_url, degradedReason: comments.degradedReason, runnerDisposition: comments.runnerDisposition ?? runnerDisposition(comments.degradedReason), @@ -1771,18 +2156,42 @@ async function issueScanEscape(repo: string, token: string, limit: number): Prom continue; } for (const comment of comments) { - for (const finding of scanText(comment.body ?? "", patterns)) { - findings.push({ type: "comment", issueNumber: issue.number, id: comment.id, url: comment.html_url, ...finding }); - } + scannedComments += 1; + findings.push(...bodyRiskFindings("comment-body", issue.number, issue.id, comment.body, comment.html_url, comment.id)); + findings.push(...scanText(comment.body ?? "", patterns, issue.number, issue.id, "comment-body", comment.html_url, comment.id)); } } + const cleanupSuggestions = summarizeCleanupSuggestion(findings); + const summary = findings.reduce((acc, finding) => { + if (finding.type === "comment-scan-error") { + acc.commentScanErrors += 1; + return acc; + } + if (finding.classification === "suspected-pollution") acc.suspectedPollution += 1; + if (finding.classification === "explanatory-mention") acc.explanatoryMention += 1; + if (finding.classification === "risk") acc.risk += 1; + if (finding.kind === "null-body" || finding.kind === "literal-null-body" || finding.kind === "blank-body" || finding.kind === "short-body") acc.bodyRisks += 1; + return acc; + }, { suspectedPollution: 0, explanatoryMention: 0, risk: 0, bodyRisks: 0, commentScanErrors: 0 }); return { ok: true, - command: "issue scan-escape", + command: commandName, repo, - scannedIssues: issues.length, + dryRun, + planned: true, + scannedIssues: issueOnly.length, + rawIssues: issues.length, + scannedComments, findings, - note: "Read-only scan; no issue or comment content was modified.", + cleanupSuggestions, + summary: { + findings: findings.length, + suggestions: cleanupSuggestions.length, + ...summary, + }, + note: dryRun + ? "Dry-run cleanup planning only; no issue or comment content was modified." + : "Read-only scan; no issue or comment content was modified.", }; } @@ -1906,7 +2315,8 @@ export function ghHelp(): unknown { "bun scripts/cli.ts gh issue comment delete <commentId> [--repo owner/name] [--dry-run]", "bun scripts/cli.ts gh issue close|reopen <number> [--repo owner/name] [--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]", + "bun scripts/cli.ts gh issue scan-escape [--repo owner/name] [--limit N] [--dry-run]", + "bun scripts/cli.ts gh issue cleanup-plan [--repo owner/name] [--limit N] [--dry-run]", "bun scripts/cli.ts gh pr list [--repo owner/name] [--limit N] [--json number,title,state,url,updatedAt,createdAt,author,head,base,draft]", "bun scripts/cli.ts gh pr view <number> [--repo owner/name] [--json body,title,state,head,base,draft]", "bun scripts/cli.ts gh pr create --title <title> --body-file <file>|--body <text> --base <branch> --head <branch> [--repo owner/name] [--draft] [--dry-run]", @@ -1928,6 +2338,9 @@ export function ghHelp(): unknown { "issue update --body-file refuses literal null, blank, and too-short bodies by default. Use --allow-short-body only for intentional short writes; #20 and #24 body-only profiles require their stable headings.", "issue update dry-run reports old/new body length slots, body SHA, required heading checks, literal \\n detection, and shell-pollution signals. Non-dry-run can use --expect-updated-at or --expect-body-sha for stale-cache protection.", "Issue body stdin is intentionally unsupported in this CLI; write generated Markdown to a file and pass --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 Markdown writes intentionally use --body-file only.", + "issue scan-escape classifies literal \\n findings as suspected-pollution, explanatory-mention, or risk, and emits cleanupSuggestions with body/comment ids plus diff-like previews. cleanup-plan is an alias that remains dry-run/read-only.", "issue edit 24 --notify-claudeqq-brief-diff reads the old issue body, PATCHes the new body, and sends only newly added '## 更新 ... 北京时间' sections to ClaudeQQ; ClaudeQQ failure does not roll back GitHub.", "Commander brief ClaudeQQ defaults to private target 645275593 through backend-core /api/microservices/claudeqq/proxy; UNIDESK_COMMANDER_BRIEF_CLAUDEQQ_* env vars can override target, base URL, timeout, and enabled state.", "comment delete is supported because GitHub supports deleting issue comments; issue/pr hard delete is unsupported and close is the lifecycle alternative.", @@ -1995,6 +2408,13 @@ export async function runGhCommand(args: string[]): Promise<GitHubCommandResult if (missing !== null || token === null) return missing ?? authRequired(options.repo, "issue comment create", { present: false, source: null, ghFallbackAttempted: true }); return issueComment(options.repo, token, issueNumber, options); } + if (sub === "scan-escape" || sub === "cleanup-plan") { + const { token, probe } = resolveToken(true); + const commandName = sub === "cleanup-plan" ? "issue cleanup-plan" : "issue scan-escape"; + const missing = authRequired(options.repo, commandName, probe); + if (missing !== null || token === null) return missing ?? authRequired(options.repo, commandName, { present: false, source: null, ghFallbackAttempted: true }); + return issueScanEscape(options.repo, token, options.limit, options.dryRun || sub === "cleanup-plan", commandName); + } if (options.dryRun) { if (sub === "create") return issueCreate(options.repo, "", options); if (sub === "edit") { @@ -2024,7 +2444,6 @@ export async function runGhCommand(args: string[]): Promise<GitHubCommandResult if (sub === "close") return issueState(options.repo, token, parseNumber(third, "issue close"), "closed", options.dryRun); if (sub === "reopen") return issueState(options.repo, token, parseNumber(third, "issue reopen"), "open", options.dryRun); if (sub === "delete") return unsupportedCommand("issue delete", options.repo, "GitHub REST does not support hard-deleting issues; use gh issue close for lifecycle deletion semantics."); - if (sub === "scan-escape") return issueScanEscape(options.repo, token, options.limit); } if (top === "pr") {