diff --git a/.agents/skills/unidesk-gh/SKILL.md b/.agents/skills/unidesk-gh/SKILL.md index 2b5751fe..59899b67 100644 --- a/.agents/skills/unidesk-gh/SKILL.md +++ b/.agents/skills/unidesk-gh/SKILL.md @@ -9,6 +9,12 @@ UniDesk 受控 GitHub 操作入口，所有 issue/PR 读写走 `bun scripts/cli. **固定入口前缀**: `cd /root/unidesk && bun scripts/cli.ts gh ...` +## 写入语言 + +- Issue/PR 的正式写入一律使用中文，包括标题、正文、评论、关闭/重开说明、PR 描述、PR 评论和 merge closeout 说明。 +- 命令、路径、trace/session/job id、API path、代码标识符、英文专有名词、原始日志摘录和外部错误原文可以保留原样；解释性文字、结论、风险、计划和验收说明必须中文。 +- 除非用户明确要求外文，不要用英文撰写 issue/PR closeout、进展评论或阻塞说明。 + --- ## 认证探测 diff --git a/docs/reference/cli.md b/docs/reference/cli.md index 88c10f3c..e8ec1a59 100644 --- a/docs/reference/cli.md +++ b/docs/reference/cli.md @@ -212,7 +212,7 @@ bun scripts/cli.ts microservice proxy code-queue /api/foo --method GET --check-p **复杂 JSON body 优先 `--body-file ` 而非 `--body-json ''`**（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-stdin <<'EOF'` 或生命周期评论的 `--comment-stdin <<'EOF'`。不要把 Markdown 正文拼进 shell 参数或 `gh api -f body=...`；这些路径容易把真实换行污染成字面量 `\n`。推荐形态是 quoted heredoc，例如 `bun scripts/cli.ts gh issue comment create --repo owner/name --body-stdin <<'EOF' ... EOF`，保证反引号、反斜杠和 Markdown 表格不被 shell 展开，也不需要临时正文文件；已有可复用正文文件时才使用 `--body-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 ` 只适合人工短单行评论，默认输出只给 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 写入输出不会默认回显完整正文。 +GitHub issue/PR 写操作必须优先使用 `bun scripts/cli.ts gh issue|pr ... --body-stdin <<'EOF'` 或生命周期评论的 `--comment-stdin <<'EOF'`。Issue/PR 的正式写入一律使用中文，包括标题、正文、评论、关闭/重开说明、PR 描述、PR 评论和 merge closeout 说明；命令、路径、trace/session/job id、API path、代码标识符、英文专有名词、原始日志摘录和外部错误原文可以保留原样，但解释性文字、结论、风险、计划和验收说明必须中文。不要把 Markdown 正文拼进 shell 参数或 `gh api -f body=...`；这些路径容易把真实换行污染成字面量 `\n`。推荐形态是 quoted heredoc，例如 `bun scripts/cli.ts gh issue comment create --repo owner/name --body-stdin <<'EOF' ... EOF`，保证反引号、反斜杠和 Markdown 表格不被 shell 展开，也不需要临时正文文件；已有可复用正文文件时才使用 `--body-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 ` 只适合人工短单行评论，默认输出只给 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 原因。