msdevflow 0.7.9 → 0.8.1

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) [year] [fullname]
+Copyright (c) 2025-2026 GitCode msdevflow contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/lib/bootstrap.js

@@ -1180,10 +1180,16 @@ function npmGitcodeDiagnosis(executable, doctor) {
         };
       }
     } catch {
-      // Fall through to the fail-closed ownership error.
+      // Fall through to coexist.
     }
   }
-  throw new BootstrapError(`Existing gitcode has unknown ownership: ${executable}. Refusing to overwrite it.`, 3);
+  // doctor failed: existing gitcode is not the npm official CLI.
+  // Coexist by installing npm CLI alongside and using gitcode-npm.
+  return {
+    classification: "python", // triggers coexist mode, installs npm CLI separately
+    existingExecutable: executable,
+    workflowCommand: "gitcode-npm",
+  };
 }
 
 export function diagnoseGitcode(run, platform) {
@@ -1562,6 +1568,32 @@ function writeWrapper(details, platform) {
   }
 }
 
+function removeNpmGitcodeShims(npmPrefix, platform) {
+  const pathApi = platform === "win32" ? path.win32 : path.posix;
+  const candidates = platform === "win32"
+    ? ["gitcode.cmd", "gitcode"]
+    : ["gitcode"];
+  for (const name of candidates) {
+    const file = pathApi.join(npmPrefix, name);
+    try {
+      const metadata = lstatSync(file);
+      if (metadata.isSymbolicLink() || !metadata.isFile()) {
+        continue;
+      }
+      const content = readFileSync(file, "utf8");
+      // Only remove if it looks like an npm shim for @gitcode-cli/cli.
+      if (!/@gitcode-cli|gitcode\.js/i.test(content)) {
+        continue;
+      }
+      unlinkSync(file);
+    } catch (error) {
+      if (error?.code !== "ENOENT") {
+        throw error;
+      }
+    }
+  }
+}
+
 async function installGitcode(plan, runLong, run, platform) {
   await runLong(plan.installInvocation);
   if (plan.gitcodeInstall.mode === "coexist") {
@@ -1570,6 +1602,8 @@ async function installGitcode(plan, runLong, run, platform) {
       `Installed GitCode npm CLI target not found: ${plan.gitcodeInstall.cliTarget}.`,
     );
     writeWrapper(plan.gitcodeInstall, platform);
+    // Remove any global npm gitcode shims so PATH falls through to Python gitcode.
+    removeNpmGitcodeShims(plan.gitcodeInstall.wrapperDir, platform);
     return {
       command: plan.gitcodeInstall.workflowCommand,
       executable: plan.gitcodeInstall.wrapper,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "msdevflow",
-  "version": "0.7.9",
+  "version": "0.8.1",
   "description": "Install the msdevflow GitCode skill and its runtime dependencies",
   "type": "module",
   "bin": {
@@ -11,6 +11,7 @@
     "lib/",
     "skill/",
     "!skill/**/scripts/test_openlibing_ci.py",
+    "!skill/**/scripts/test_gitcode_review.py",
     "!skill/**/__pycache__/**",
     "!skill/**/*.pyc"
   ],
@@ -26,5 +27,5 @@
     "gitcode",
     "setup"
   ],
-  "license": "UNLICENSED"
+  "license": "MIT"
 }

package/skill/msd/README.md

@@ -179,6 +179,8 @@ PR：https://gitcode.com/Ascend/example/pulls/789
 
 本 action 只检视当前账号之外的作者所提交的 open、非 Draft/WIP PR；自审返回 `blocked: self-review-forbidden`。它固定当前 head，读取完整权威 diff、全部 changed files、必要上下文、关联 Issue、仓库规范和结构化 discussions，默认不 checkout、不执行 PR head 脚本、不修改代码。
 
+GitCode 传输只通过内置 `scripts/gitcode_review.py`：一次 `snapshot` 聚合主要证据，需要未变更调用方时用 `context` 批量读取已知精确路径，发布只用 `finding` 或 `lgtm`，最后用 `cleanup` 删除受管 snapshot。Agent 不再现场拼接 Python/PowerShell JSON、grep 展示文本、raw URL、`curl` 或 API endpoint；helper 能力不足或响应不完整时直接阻断。允许客户端执行固定 helper 只用于减少重复网络权限提示，不代表批准任何 reviewer 结论。
+
 只发布由本 PR 引入或暴露、证据充分且可操作的 finding；已有 discussion 已覆盖的问题不重复发布。有 finding 或仍有效的未解决意见时不发送 `/lgtm`。完整覆盖且未发现需要作者修改的问题时，不发布检视摘要或其他前置评论；获得针对当前 PR/head 的明确确认后，只发送并回读正文恰好为 `/lgtm` 的评论。`/lgtm` 不加尾签，不代表 `/approve`、CI 通过或允许合入。本 action 不发送 `/approve`、`/merge`，也不替作者回复或 resolve discussion。
 
 ### 只核验并合入
@@ -417,4 +419,6 @@ typed CLI command
 - [references/command-capabilities.md](references/command-capabilities.md)：CLI 能力适配。
 - [references/ci-and-review.md](references/ci-and-review.md)：CI 和作者 discussion 深层规则。
 - [scripts/openlibing_ci.py](scripts/openlibing_ci.py)：openLiBing 只读诊断与交互 OAuth 客户端。
+- [scripts/gitcode_review.py](scripts/gitcode_review.py)：`code-review` 固定 snapshot/context/finding/lgtm/cleanup 适配器。
 - [scripts/test_openlibing_ci.py](scripts/test_openlibing_ci.py)：openLiBing 无凭证控制流测试。
+- [scripts/test_gitcode_review.py](scripts/test_gitcode_review.py)：GitCode review 适配器的无网络回归测试。

package/skill/msd/SKILL.md

@@ -54,6 +54,8 @@ msd-merge
 
 `code-review` 只能通过 `msd-code-review` 或兼容参数 `action=code-review` 独立调用，永不进入作者 E2E，不得检视或批准当前账号自己的 PR。它固定当前 head，完整检视权威 diff、必要上下文和既有 discussions：有高置信度问题时只发布经确认且逐字回读的 finding，不发送 `/lgtm`；没有问题、没有有效未解决意见且覆盖完整时，在针对当前 PR/head 明确确认后只发送正文恰好为 `/lgtm` 的评论，不发布检视摘要或其他前置评论。它不发送 `/approve`、`/merge`，不修改作者代码。
 
+`code-review` 对 GitCode 的唯一执行适配器是 Skill 随附的 `scripts/gitcode_review.py`：用一次 `snapshot` 聚合 PR 证据，必要时用 `context` 批量读取已知精确路径，发布时只用 `finding` 或经当前 PR/head 确认的 `lgtm`，结束后用 `cleanup` 删除受管 snapshot。不得现场拼接 `python -c`、PowerShell JSON、shell/grep 展示文本解析、raw URL、`curl` 或未知 API endpoint，也不得在 helper 失败时退回原始 CLI 试错。客户端对固定 helper 的网络执行授权只减少权限提示，不替代 finding 或精确 `/lgtm` 的 reviewer 结论确认。
+
 ## 显式 action 契约
 
 1. 只执行指定 action；达到完成条件后立即停止，只报告证据、当前 head、blocker 和建议的下一个 action。
@@ -120,7 +122,8 @@ discovered -> claimed -> verified -> analyzed -> designed
 - 作者不得冒充 reviewer/approver，不得自行制造 LGTM/approved 门禁。
 - 不读取、打印或转存 GitCode Token。openLiBing OAuth Token 只允许在当前认证进程内短暂使用，不打印、不落盘、不写入 URL、命令、记忆或对话。
 - 不跳过 hooks/测试/CI/review，不默认 force push、关闭 Issue、删除分支或重写共享历史。
-- 创建 Issue/PR、评论、触发 CI、resolve 和 merge 前检查幂等状态；`create-issue` 不做产品查重，只在写结果不确定时有界恢复；其他写结果不确定时也先回读。
+- 创建 Issue/PR、评论、触发 CI、resolve 和 merge 前检查幂等状态；`create-issue` 在最终预览确认前禁止远端写入，每个 run 最多执行一次已确认的真实创建，禁止测试 Issue、POST 探测、失败重试或替代 Issue，只在写结果不确定时有界只读恢复；其他写结果不确定时也先回读。
+- `code-review` 的 GitCode 网络访问只能由 `scripts/gitcode_review.py` 执行；helper 输出不完整或能力不足即阻断，不回退现场命令、文本解析或 endpoint 探测。受管 snapshot 必须结束时清理，受管 write receipt 只用于固定 head 上评论写入的幂等恢复。
 - Agent 写入 GitCode 的 PR 正文、Issue/PR 评论、discussion 回复和其他人类可读正文必须按 [references/state-and-safety.md](references/state-and-safety.md) 在末尾恰好附加一次 `——msdevflow`。
 - 所有人类可读远端文本必须通过 UTF-8 安全通道写入并逐字回读；发现乱码、`?`、截断或尾签损坏时阻断依赖动作，先原地修复。
 - 严格机器协议 payload 保持原样，不把尾签拼进 `compile`、`/lgtm`、`/merge` 等命令。除 `code-review` 检视通过时只发送精确 `/lgtm` 外，其他协议按 [references/state-and-safety.md](references/state-and-safety.md) 发布并验证带尾签的独立人类可读说明。

package/skill/msd/references/code-review.md

@@ -2,33 +2,70 @@
 
 显式 `action=code-review` 用于以独立 reviewer 身份检视他人的 GitCode PR。它只在用户明确指定本 action 时运行，永不进入作者 E2E，也不转入 `feedback`、`ci`、`merge` 或代码修改流程。
 
+## 唯一执行适配器
+
+本 action 的 GitCode 读取、归一化、UTF-8 落盘和评论写后回读必须通过 Skill 随附的 `scripts/gitcode_review.py`。不得在现场拼接 `python -c`/`python3 -c`、PowerShell `ConvertFrom-Json`、shell 管道或 grep 解析 GitCode 展示文本；不得直接执行 `pr diff`、`pr comments`、`pr comment`、网页 raw URL、`curl` 或自行试探 API endpoint。固定 helper 返回能力不足、响应不完整或未知 schema 时停止为 `blocked: review-capability-required`；不得绕开 helper 改用另一命令试错。
+
+同一次调用可聚合多个 PR，只执行一次固定 helper 入口，减少重复网络命令和客户端赋权：
+
+```bash
+python <skill-dir>/scripts/gitcode_review.py snapshot \
+  --gitcode-command <gitcode-command> \
+  [--repo <canonical>] \
+  <pr-url-or-number> [<pr-url-or-number> ...]
+```
+
+helper 只在 stdout 输出小型 JSON manifest；完整 PR 元数据、changed-files patch、base/head 文件、comments、行内 comment detail、关联 Issue 和仓库规范写入受管 snapshot 目录。Agent 用文件读取工具按 manifest 逐项读取，不把完整 snapshot 打印回终端。结束时清理：
+
+```bash
+python <skill-dir>/scripts/gitcode_review.py cleanup <snapshot-dir> --yes
+```
+
+`cleanup` 只接受带 msdevflow marker 的受管 snapshot，拒绝删除其他路径。客户端可对这个固定脚本入口授予所需网络执行权限；该权限只允许 helper 调用已固化的 GitCode 只读/写后校验路径，不等于用户已确认 finding、`/lgtm`、approve 或 merge。
+
 ## 前置条件与身份隔离
 
 至少需要 PR URL，或能与 canonical repository 唯一组合的 PR 编号。缺少目标时返回 `blocked: pr-required`，不得改为发现候选 PR。
 
-开始时只读确认：
+从 snapshot 只读确认：
 
 - 当前 GitCode 登录账号及 canonical operation target；
 - PR 存在、open 且处于可检视状态；Draft/WIP 或已关闭 PR 返回 `waiting`/`blocked`，不发布结论；
 - PR author 与当前账号不同；相同则返回 `blocked: self-review-forbidden`，不得发布 finding、`/lgtm`、approve 或任何可形成独立门禁的信号；
 - PR base/head、当前 head SHA、关联 Issue、描述、commits、changed files 和现有 comments/discussions；
-- 仓库最新默认分支中的适用 `AGENTS.md`、`CLAUDE.md`、`CONTRIBUTING*`、README、OWNERS/CODEOWNERS、测试与检视规范；
+- canonical 最新 base 分支中适用于 changed files 的 `AGENTS.md`、`CLAUDE.md`、`CONTRIBUTING*`、README、OWNERS/CODEOWNERS 和测试配置；
 - 当前账号具备发表评论的权限；仓库对 reviewer 资格另有要求时，无法证明资格不得发送 `/lgtm`。
 
-开始分析时固定 `review_head_sha`。任何检视结论只对该 head 有效。
+开始分析时固定 helper 返回的 `review_head_sha`。任何检视结论只对该 head 有效。snapshot 标记 `snapshot_complete=false`、changed-files 数量不一致、patch/文件/行内详情缺失、tree 截断、读取期间 head/base 改变或其他 `incomplete_reasons` 时只能停止为 `review-incomplete`，不得把未发现问题解释为通过。
 
-## CLI 能力
+## 固定数据路径
 
-使用前按 schema/help 探测：
+helper 只使用 setup 已验收且本 Skill 固定的路径，不在运行时改变策略：
+
+```text
+pr view <number> -R <canonical> --json
+api repos/<canonical>/pulls/<number>/files
+pr comments <number> -R <canonical> --json
+api repos/<canonical>/pulls/comments/<numeric-comment-id>
+api repos/<repository>/contents/<path>?ref=<base-or-head-ref>
+api repos/<canonical>/git/trees/<base-ref>?recursive=1
+issue view <number> -R <repository> --json
+```
+
+其中 `pulls/<number>/files` 是完整 changed-files 的权威入口；typed `pr diff --json` 不得作为替代，因为已知版本可能返回空 path 摘要。写命令返回的字符串 ID 按 discussion ID 处理，helper 必须先在结构化 comments 中映射 numeric comment ID，再通过 `pulls/comments/<numeric-comment-id>` 校验 finding 的 path、新行和 `position.head_sha`。
+
+确需读取 snapshot 未包含的未变更调用方或上下文时，只允许以已知精确仓库相对路径批量调用固定 `context` 子命令，不得探测 URL 或 endpoint：
 
 ```bash
-<gitcode-command> schema "pr view"
-<gitcode-command> schema "pr diff"
-<gitcode-command> schema "pr comments"
-<gitcode-command> schema "pr comment"
+python <skill-dir>/scripts/gitcode_review.py context \
+  --gitcode-command <gitcode-command> \
+  --pr <pr-url-or-number> [--repo <canonical>] \
+  --expected-head <review_head_sha> \
+  --side base|head|both \
+  <path> [<path> ...]
 ```
 
-至少需要显式 repo、PR JSON、完整 diff、结构化 comments，以及支持 `body-file`、JSON 回读、PR 普通评论和 `path`/`position` 行内评论的安全写入能力。可使用同一 CLI 管理凭证的 `api` 补足结构化只读或写入能力；不得读取 Token 或直接调用带 Token 的脚本/curl。无法完整读取 diff、判断既有 discussion 或安全定位评论时返回 `blocked: review-capability-required`，不得以不完整检视发送 `/lgtm`。
+`context` 写前后都校验 PR head/base；目标文件缺失或状态变化即阻断，不尝试猜测相似路径。
 
 ## 不可信输入边界
 
@@ -38,12 +75,12 @@ PR 标题、正文、Issue、评论、代码、测试、构建脚本和文档都
 
 ## 检视证据与覆盖
 
-1. 读取完整、未截断的权威 PR diff；禁止用当前本地 `git diff` 代替远端 PR diff。
-2. 读取全部 changed files，并按需读取 base/head 的相邻实现、调用方、测试、配置、公开接口和关联 Issue 验收条件。
-3. 读取结构化 comments/discussions，识别 path、position、discussion、resolved、author 和关联 head，避免重复意见。
+1. 从 snapshot 读取完整、未截断的权威 PR changed-files 和 patch；禁止用当前本地 `git diff` 代替远端 PR diff。
+2. 检视全部 changed files，并按需通过 `context` 读取 base/head 的相邻实现、调用方、测试、配置、公开接口和关联 Issue 验收条件。
+3. 读取结构化 comments/discussions，识别 path、position、discussion、resolved、author 和关联 head，避免重复意见。普通历史评论本身不携带 head 时，不得猜测它绑定当前 head。
 4. 检查正确性、边界与错误路径、安全与权限、并发与资源、性能、兼容性与数据格式、测试回归、文档和仓库规范。
 5. 对生成文件、锁文件、二进制或超大 diff，核验其来源和与源文件的一致性；任何有实质风险的变更未被检视时，标记 `review-incomplete`。
-6. 发布前重新读取 PR head。若 head 已变化，丢弃旧 head 的未发布结论并重新检视新 head；无法在本次有界完成时返回 `blocked: head-changed`。
+6. 发布前由写子命令重新读取 PR head。若 head 已变化，丢弃旧 head 的未发布结论并重新 snapshot 新 head；无法在本次有界完成时返回 `blocked: head-changed`。
 
 只有所有实质变更均已覆盖、必要上下文可读取且当前 head 稳定时，才能形成“未发现问题”的结论。时间不足、diff 截断、文件不可读或验证证据不足不等于没有问题。
 
@@ -61,7 +98,7 @@ PR 标题、正文、Issue、评论、代码、测试、构建脚本和文档都
 
 严重度沿用：`P0/blocking`、`P1/high`、`P2/medium`、`P3/suggestion`。只有确实需要作者处理的事项才成为 finding；纯信息性观察留在本地报告，不制造远端噪声。
 
-行内评论必须定位到当前 PR diff 中可评论的新版本新增/修改行。`position` 的语义以本次 CLI schema 为准；无法证明映射正确、问题位于删除行或涉及跨文件整体行为时，改用 PR 普通评论并在正文写明 `path:line`，不得猜位置。
+行内评论必须定位到当前 PR diff 中可评论的新版本新增/修改行。无法证明 path/position 映射正确、问题位于删除行或涉及跨文件整体行为时，改用 PR 普通评论并在正文写明精确 `path:line`，不得猜位置。
 
 ## 有 finding 的路径
 
@@ -79,9 +116,21 @@ PR 标题、正文、Issue、评论、代码、测试、构建脚本和文档都
 ——msdevflow
 ```
 
-通过 UTF-8 无 BOM 临时文件逐条发布，每条写后立即从结构化 comments 逐字回读正文、唯一尾签、path/position、reviewer 和 discussion ID。写入损坏时按安全契约原地修复；结果不确定时先按当前 reviewer、PR、head、path/position 和完整正文有界查询，不直接重试。
+确认后把最终正文写入 UTF-8 无 BOM 本地文件，并只调用固定写子命令：
 
-发布每条评论前再次确认 head 未变化；若中途变化，停止剩余写入并报告已发布评论对应的旧 head。reviewer 不替作者回复或 resolve 自己提出的 discussion，不修改代码，不发送 `/lgtm`。
+```bash
+python <skill-dir>/scripts/gitcode_review.py finding \
+  --gitcode-command <gitcode-command> \
+  --pr <pr-url-or-number> [--repo <canonical>] \
+  --expected-head <review_head_sha> \
+  --body-file <utf8-no-bom-finding-file> \
+  [--path <new-path> --position <new-line>] \
+  --confirmed-current-head
+```
+
+helper 校验唯一尾签，写前确认 head/author，使用内部唯一 UTF-8 无 BOM 临时文件发布，在 `finally` 中删除，并按 discussion ID → numeric comment ID → comment detail 逐字回读 reviewer、正文、path/new line 和 `position.head_sha`。它在受管目录中只持久化正文 SHA-256、固定 head、写前评论集合和写后 ID 的事务凭据，不保存正文或 Token；命令中断后只读恢复同一次尝试，不直接重试。
+
+发布每条评论前都重新调用写子命令确认 head；若中途变化，停止剩余写入并报告已发布评论对应的旧 head。reviewer 不替作者回复或 resolve 自己提出的 discussion，不修改代码，不发送 `/lgtm`。
 
 如果没有新 finding，但已有其他 reviewer 的有效未解决问题，按实质去重并报告这些问题，仍不得发送 `/lgtm`。
 
@@ -90,7 +139,7 @@ PR 标题、正文、Issue、评论、代码、测试、构建脚本和文档都
 同时满足以下条件才可进入通过路径：
 
 - 当前账号不是 PR author，且 reviewer 资格/权限满足仓库规则；
-- 所有实质 changed files 和必要上下文已完整检视；
+- snapshot 完整，所有实质 changed files 和必要上下文已完整检视；
 - 当前 `review_head_sha` 未变化；
 - 没有本次新 finding；
 - 没有已确认仍有效的未解决 discussion 或其他已知阻塞问题。
@@ -101,23 +150,30 @@ PR 标题、正文、Issue、评论、代码、测试、构建脚本和文档都
 /lgtm
 ```
 
-`/lgtm` 是会形成 reviewer 门禁的机器协议。无论 guided 或 autonomous，都必须获得用户针对当前 PR 和 `review_head_sha` 的明确确认；普通的 `action=code-review` 调用只授权只读检视，不等于提前批准该结论。
+`/lgtm` 是会形成 reviewer 门禁的机器协议。无论 guided 或 autonomous，都必须获得用户针对当前 PR 和 `review_head_sha` 的明确确认；普通的 `action=code-review` 调用以及客户端对 helper 的网络权限都不等于提前批准该结论。
+
+确认后只调用：
 
-确认后：
+```bash
+python <skill-dir>/scripts/gitcode_review.py lgtm \
+  --gitcode-command <gitcode-command> \
+  --pr <pr-url-or-number> [--repo <canonical>] \
+  --expected-head <review_head_sha> \
+  --confirmed-current-head \
+  --confirm-exact-lgtm
+```
 
-1. 再次回读 head，发生变化则停止，不发送 `/lgtm`；
-2. 以正文恰好为 `/lgtm` 的 PR 评论发送机器 payload，不添加尾签、空行、代码块或其他文字；
-3. 回读确认 comment author、正文和目标 PR，并有界观察仓库机器人产生的 lgtm label/check；机器人尚未处理时只报告 pending，不重复发送命令。
+helper 内部生成正文恰好为 `/lgtm` 的 UTF-8 无 BOM 临时文件，不接受任意正文，不添加尾签、空行、代码块或其他文字；写前回读 head/author，写后结构化回读 comment author、正文和目标 PR，再次确认 head，并在 `finally` 中删除临时文件。仓库机器人尚未产生 lgtm label/check 时只报告 pending，不重复发送命令。
 
 `/lgtm` 仅表示当前 reviewer 对固定 head 的代码检视通过，不等于 `/approve`、CI 通过或允许合入。本 action 不发送 `/approve`、`/merge`，也不调用 `merge`。
 
 ## 幂等与恢复
 
-检视通过的幂等键为：`canonical + PR + review_head_sha + current reviewer + 精确 /lgtm`。同一 reviewer 已存在可绑定当前 head 的精确 `/lgtm` 时，回读后直接报告 `review-passed`，不重复评论。
+检视通过的幂等键为：`canonical + PR + review_head_sha + current reviewer + 精确 /lgtm`。helper 的本地事务凭据能证明同一次尝试和固定 head 时，回读后直接报告 `review-passed`，不重复评论。
 
-只有旧 `/lgtm` 或无法绑定当前 head 的历史门禁时，不得当作当前检视完成。当前 head 缺少可验证的精确 `/lgtm` 时，不自动补发；恢复时重新确认当前 head、完整覆盖和无问题结论，并再次取得 `/lgtm` 确认。任何写操作超时都先查远端事实。
+只有旧 `/lgtm`、没有 helper 事务凭据或无法绑定当前 head 的历史门禁时，不得当作当前检视完成。当前 head 缺少可验证的精确 `/lgtm` 时，不自动补发；恢复时重新确认当前 head、完整覆盖和无问题结论，并再次取得 `/lgtm` 确认。任何写操作超时都由 helper 按写前评论集合、返回 discussion ID、reviewer 和完整正文哈希先查远端事实；无法唯一恢复时停止 `blocked: comment-write-uncertain`，禁止直接重试或改用 raw CLI。
 
-有 finding 的幂等键为：`canonical + PR + review_head_sha + reviewer + path/position + finding 完整正文`。既有等价 finding 直接复用，不重复发布。
+有 finding 的幂等键为：`canonical + PR + review_head_sha + reviewer + path/position + finding 完整正文`。既有等价 finding 经 comment detail 或 helper 事务凭据绑定当前 head 后直接复用，不重复发布。
 
 ## 完成输出
 
@@ -134,4 +190,4 @@ Suggested next action: none | wait for author and re-run code-review on new head
 Confirmation required: none | finding comments | /lgtm for current head
 ```
 
-只有精确 `/lgtm` 已被远端回读时才能报告 `review-passed`。仅仅“分析未发现问题”但尚未确认或写入时，状态为 `waiting: lgtm-confirmation`。
+只有精确 `/lgtm` 已被 helper 远端回读且写后 head 仍匹配时才能报告 `review-passed`。仅仅“分析未发现问题”但尚未确认或写入时，状态为 `waiting: lgtm-confirmation`。

package/skill/msd/references/command-capabilities.md

@@ -34,7 +34,9 @@ GitCode CLI 版本和命令集合可能不同。工作流必须探测能力，
 <gitcode-command> schema "pr merge"
 ```
 
-若无 schema，对应使用 `<command> --help`。只探测当前 action 所需命令；`create-issue` 至少需要 `milestone list` 的显式 repo、JSON 和分页，`issue create` 的显式 repo、title、body-file、milestone number、JSON 和 dry-run，以及 `issue view` 的 JSON 回读能力；非 ASCII 标题还需要同一 CLI `api --input <utf8-json-file>`。`pr` 至少需要读取关联 Issue 和 PR milestone 的 JSON 能力，以及 `pr edit` 的显式 repo、milestone number 和 JSON；typed `pr create` 不支持 milestone 时，必须在同一次已确认的 PR action 中以 `pr edit --milestone` 关联并回读。`openlibing-auth` 至少需要可有界列举 canonical PR、读取 PR head/labels/comments 的 JSON 能力。`code-review` 至少需要 `pr view`/`pr diff`/`pr comments` 的显式 repo 和 JSON 能力，以及 `pr comment` 的显式 repo、body-file、JSON、path 和 position；完整 diff 必须未截断，comments 必须能识别 discussion、resolved、author 和 path/position。若 typed CLI 无法补齐，可使用同一 CLI 管理凭证的 `api`；仍无法完整读取、去重或安全定位时返回 `blocked: review-capability-required`，不得发送 finding 或 `/lgtm`。完整作者 E2E 记录仓库参数（`-R`/`--repo`）、JSON、body-file/comment-file/stdin、dry-run、fork、assignee、discussion/resolve、正文 edit 和标题 edit 能力。涉及人类可读远端文本时，必须确认 [state-and-safety.md](state-and-safety.md) 要求的 UTF-8 文件、stdin 或 `api --input <utf8-json-file>` 安全通道；Windows PowerShell 5.1 下只有 `--body`/`--comment`/`--title` 等字符串参数而入口为 `.cmd` wrapper 时，不把非 ASCII 文本直接放进命令行参数。
+若无 schema，对应使用 `<command> --help`。只探测当前 action 所需命令；`create-issue` 至少需要 `milestone list` 的显式 repo、JSON 和分页，`issue create` 的显式 repo、title、body-file、JSON 和 dry-run，`issue view` 的 JSON 回读能力，以及 `issue edit` 的显式 repo、milestone number 和 JSON。官方 npm GitCode CLI 的 typed `issue create --title` 是 `create-issue` 唯一支持的非 ASCII 标题创建通道；不得调用 `api .../issues --method POST` 测试或创建 Issue。`pr` 至少需要读取关联 Issue 和 PR milestone 的 JSON 能力，以及 `pr edit` 的显式 repo、milestone number 和 JSON；typed `pr create` 不支持 milestone 时，必须在同一次已确认的 PR action 中以 `pr edit --milestone` 关联并回读。`openlibing-auth` 至少需要可有界列举 canonical PR、读取 PR head/labels/comments 的 JSON 能力。完整作者 E2E 记录仓库参数（`-R`/`--repo`）、JSON、body-file/comment-file/stdin、dry-run、fork、assignee、discussion/resolve、正文 edit 和标题 edit 能力。涉及人类可读远端文本时，必须确认 [state-and-safety.md](state-and-safety.md) 要求的 UTF-8 文件、stdin 或 `api --input <utf8-json-file>` 安全通道；Windows PowerShell 5.1 下只有 `--body`/`--comment`/`--title` 等字符串参数而入口为 `.cmd` wrapper 时，不把非 ASCII 文本直接放进命令行参数。
+
+`code-review` 是能力降级顺序的专用例外：Agent 不直接探测或组合 GitCode 命令，只调用 Skill 随附的 `scripts/gitcode_review.py`。setup 必须验收 `issue view`、`pr view`、`pr comments`、`pr comment` 和 `api`；helper 内部只使用 [code-review.md](code-review.md) 固定的数据路径，以 `pulls/<number>/files` 而不是 typed `pr diff --json` 读取完整 changed-files。helper 的 `snapshot`/`context`/`finding`/`lgtm` 返回能力不足、未知 schema 或不完整响应时，停止为 `blocked: review-capability-required` 或 `review-incomplete`；不得退回 raw CLI、网页 raw URL、`curl`、现场 `python -c`/PowerShell JSON、展示文本 grep 或其他 endpoint 试探。
 
 ## 安装/升级 handoff
 
@@ -48,6 +50,8 @@ npx msdevflow setup
 
 ## 能力降级顺序
 
+除 `code-review` 外：
+
 1. CLI 缺失或核心 capability 不足时，返回 `blocked: bootstrap-required`，由用户运行独立 setup 后恢复；
 2. typed CLI command；
 3. 同一 CLI 的其他 typed command/JSON 输出；
@@ -55,6 +59,8 @@ npx msdevflow setup
 5. 网页人工操作说明；
 6. blocked。
 
+`code-review` 不适用上述运行时降级；其唯一入口是固定 helper，helper 失败即阻断，不切换命令或数据路径。
+
 禁止：
 
 - 读取 CLI 配置获取 Token；
@@ -67,8 +73,8 @@ npx msdevflow setup
 ## 常见版本差异
 
 - 某些版本没有 `repo` 或 `api`；默认分支可从 `git remote show`、remote HEAD、PR base 或平台网页事实交叉确认。
-- 某些版本只有 `pr view --comments`，没有结构化 `pr comments`；此时能阅读评论但无法可靠获得 discussion/resolved 字段，作者 feedback 的逐条 reply/resolve 应降级为人工步骤，`code-review` 则因无法可靠去重而返回 `blocked: review-capability-required`。
-- 某些版本的 `pr comment` 不支持 `path`/`position` 或其 position 语义不清；`code-review` 不得猜测行内位置。问题无法安全改为带精确 `path:line` 的 PR 普通评论时返回 `blocked: review-capability-required`。
+- 某些版本只有 `pr view --comments`，没有结构化 `pr comments`；此时能阅读评论但无法可靠获得 discussion/resolved 字段，作者 feedback 的逐条 reply/resolve 应降级为人工步骤，`code-review` 固定 helper 则返回 `blocked: review-capability-required`。
+- 某些版本的 `pr comment` 不支持 `path`/`position` 或其 position 语义不清；`code-review` 固定 helper 不猜测行内位置。问题可由 helper 安全发布为带精确 `path:line` 的 PR 普通评论时使用普通评论，否则返回 `blocked: review-capability-required`。
 - 某些版本不支持 `--json`；不得用彩色展示文本做关键写操作的唯一确认，至少通过第二个只读命令回读。
 - 某些版本不支持 fork、body-file、里程碑分页、`issue create --milestone` 或 `pr edit --milestone`；应升级 CLI。不得因 PR 已创建就忽略里程碑关联失败或声称 `pr-open`。若 typed command 缺少 UTF-8 安全文本输入，优先使用同一 CLI 的 `api --input <utf8-json-file>`；仍无法安全表达时给出网页人工步骤或进入 `blocked`。
 - Windows PowerShell 5.1 的原生管道默认编码不是可靠的 UTF-8；不得把含中文的字符串裸管道到 CLI，也不得依赖 `Out-File`/`Set-Content` 默认编码生成正文文件。

package/skill/msd/references/create-issue.md

@@ -6,6 +6,12 @@
 
 至少需要目标 canonical repository 和待提交问题的自然语言描述。目标仓库可由用户明确给出，或按公共启动规则从当前工作区唯一识别；无法唯一确定时返回 `blocked: canonical-not-unique`。缺少问题描述时逐次只询问一个必要输入，不查询现有 Issue 或关联 PR。
 
+本 action 是一次性 Issue 创建事务。最终预览得到用户明确确认前，禁止任何会改变远端状态的操作，包括 Issue/PR 创建、编辑、关闭、删除、评论、标签或里程碑写入；只允许 schema/help、dry-run、本地序列化和只读查询。`POST` 到 Issue 集合永远是真实创建，不得用测试标题、最小 payload、权限探测、编码探测、字段探测或“dry-run API”名义调用。
+
+每个 action run 最多允许一次真实 Issue 创建请求，而且只能发送已确认预览中的完整 payload。发起请求前将本次 run 标记为 `create_attempted=true`；无论返回成功、400/403、超时、连接中断、进程失败、空响应还是结果无法解析，都不得重置该标记，也不得切换 CLI/API、修改标题/正文/类型/标签/里程碑后再次创建。创建尝试后只能按“回读、恢复与完成”执行有界只读查询和同一 Issue 回读；不能证明结果时返回 `blocked: create-result-uncertain`，不得重试。
+
+预览确认只授权一次完全匹配的最终创建，不授权测试写入、替代 payload、关闭旧 Issue 或在本 action 内创建第二个 Issue。确认前若标题、类型、正文或元数据变化，必须重新生成完整预览并重新确认；创建成功后本 action 立即结束，不在本 action 内把 Issue 改成另一类型、关闭它或创建替代 Issue。
+
 本 action 不执行重复或相似 Issue/PR 查找。只有创建命令超时、中断或结果不确定时，才允许为恢复本次写入而有界查询：限定当前账号、action 启动时间之后、目标仓库、标题和完整正文逐字一致；这不是产品查重，未找到唯一结果时停止，不直接重试。
 
 ## 模板发现
@@ -66,6 +72,8 @@ https://gitcode.com/Ascend/community/tree/master/.gitcode/.gitcode/ISSUE_TEMPLAT
 
 ## 预览和确认
 
+预览是唯一的远端写入闸门。展示预览前不得创建任何 Issue；预览确认后不得再做测试、权限、编码、字段或 API 形态探测，只能按确认内容执行一次真实创建。
+
 写入前展示：
 
 ```text
@@ -87,21 +95,42 @@ Duplicate search: not performed by design
 
 ## 创建和 UTF-8
 
-使用前探测：
+### 唯一支持的创建路径
+
+本 Skill 固定使用 setup 已验收的官方 npm GitCode CLI typed command，不通过 Issue collection API 创建。能力验证只能使用 `schema`、`--help` 和 typed command 自带的 `--dry-run`；`api .../issues --method POST` 没有 dry-run 语义，禁止用于创建、试错或验证。
+
+使用前只读探测：
 
 ```bash
 <gitcode-command> schema "milestone list"
 <gitcode-command> schema "issue create"
 <gitcode-command> schema "issue view"
+<gitcode-command> schema "issue edit"
+```
+
+将最终正文写入唯一的系统临时文件，编码固定为 UTF-8 无 BOM。官方 npm GitCode CLI 的 `issue create --title` 是本 Skill 已验收的中文标题通道；Windows `.cmd` wrapper 也直接使用 typed command，不得为中文标题切换到 API POST。预览确认后可以先用最终仓库、标题和正文文件执行一次本地 dry-run：
+
+```text
+<gitcode-command> issue create -R <canonical> --title <exact-title> --body-file <utf8-body-file> --dry-run --json
+```
+
+dry-run 的输出不得包含新 Issue number/URL；否则视为能力异常并停止。真实创建固定只携带仓库、最终标题、最终正文文件和 JSON 输出，不在创建命令中传 label、assignee、milestone 或其他可选元数据：
+
+```text
+<gitcode-command> issue create -R <canonical> --title <exact-title> --body-file <utf8-body-file> --json
 ```
 
-首选 typed command，要求 `milestone list` 支持显式 repo、JSON 和分页，`issue create` 至少支持显式 repo、title、`body-file`、milestone number、JSON 和 dry-run。使用 typed command 时，先用相同目标和字段运行 dry-run 并检查输出，再通过 UTF-8 无 BOM 临时正文文件创建；已选择里程碑时，dry-run 和真实创建都必须传递同一个 `--milestone <number>`，未选择时省略该参数。ASCII 标题可使用 `--title`；Windows `.cmd` wrapper 下的非 ASCII 标题不得为满足 dry-run 而进入字符串参数，改用同一 CLI 管理凭证的 UTF-8 JSON API 通道：
+执行真实命令前设置 `create_attempted=true`。该命令是本次 run 唯一允许的创建请求；禁止使用 `test-*`、`*-check`、`permission-*`、最小正文或其他替代 payload 探测权限、编码、标签、里程碑或字段组合。认证和权限只能通过 `auth status`、schema、dry-run 判断；最终创建仍失败时返回 `blocked`，不得发测试 Issue 或改用另一创建通道。
+
+创建成功并获得 Issue number 后，才可对同一个 Issue 应用预览确认过的元数据。里程碑固定使用：
 
 ```text
-<gitcode-command> api repos/<owner>/issues --method POST --input <utf8-json-file>
+<gitcode-command> issue edit <issue-number> -R <canonical> --milestone <milestone-number> --json --yes
 ```
 
-JSON 至少包含 `repo`、`title`、`body`，并按已验证 API 语义加入 labels、assignee、milestone 等已确认字段。JSON 文件使用唯一临时路径、UTF-8 无 BOM，命令结束后立即删除；不得读取 CLI 配置或自行提取 Token。typed command 或 API 的实际 endpoint/字段无法通过当前 CLI schema、help 或已验证能力确定时返回 `blocked: bootstrap-required` 或 `blocked: utf8-safe-create-unavailable`，不得猜测写入。
+未选择里程碑时不执行该命令。模板声明的 label/assignee 只有在创建前只读证明目标仓库接受、`issue edit` schema 明确支持且预览已列出时才可原地应用；否则预览必须明确为 `none`，不得把未经确认或不存在的元数据塞入创建请求。平台自动附加的系统类型标签在回读中单独披露，不得误报为 Agent 请求的 label。
+
+正文文件在 dry-run、唯一一次真实创建和必要回读完成后立即删除。typed command、UTF-8 文件输入或必要的同 Issue metadata edit 能力不足时返回 `blocked: bootstrap-required` 或 `blocked: utf8-safe-create-unavailable`；不得猜测 API 字段、发起 POST 实验或创建替代 Issue。
 
 ## 回读、恢复与完成
 

package/skill/msd/references/state-and-safety.md

@@ -19,11 +19,14 @@ pr_number: number-or-null
 work_branch: branch-or-null
 head_sha: sha-or-na
 review_head_sha: sha-or-null
+review_snapshot_dir: managed-path-or-null
+review_write_receipt: managed-key-or-null
 requested_action: discover | create-issue | issue | develop | pr | ci | openlibing-auth | feedback | code-review | merge | e2e
+create_attempted: false | true
 last_completed_state: state
 ```
 
-这些字段来自远端和本地探测，不能靠猜。`run_id` 的 `<scope>` 使用 Issue、PR、action 或 `e2e` 的稳定小写标识；无对应事实的 source、Issue、PR、branch 或 head 字段保持 `null`/`na`。不要把 Token 或本地绝对路径写入状态记录。
+这些字段来自远端和本地探测，不能靠猜。`run_id` 的 `<scope>` 使用 Issue、PR、action 或 `e2e` 的稳定小写标识；无对应事实的 source、Issue、PR、branch 或 head 字段保持 `null`/`na`。不要把 Token 或普通本地绝对路径写入状态记录；`review_snapshot_dir` 只保存 helper 返回的受管 snapshot 路径以便本次读取和清理，`review_write_receipt` 只引用 helper 的受管事务键，不保存正文或凭证。
 
 ## GitCode 远端文本 UTF-8 传输
 
@@ -120,6 +123,8 @@ Agent 创建或修改的 Issue/PR 正文，以及发布的 Issue 评论、PR 普
 
 `code-review` 完整检视未发现问题时，无论 guided 或 autonomous，都必须展示当前 PR、`review_head_sha` 和精确 `/lgtm`，明确说明不会发布检视摘要或前置评论，并取得一次明确确认；普通的 `action=code-review` 调用不构成该确认。
 
+`code-review` 对 GitCode 的所有读取、归一化、UTF-8 落盘、finding/`/lgtm` 写入和写后回读都只能通过 `scripts/gitcode_review.py`。客户端可以为这个固定脚本入口批准所需网络执行，以减少同一批只读调用的重复权限提示；这只授权执行 helper 固化的传输路径，不确认 finding 内容，也不批准 `/lgtm`、approve 或 merge。helper 报错、响应不完整或 schema 未知时不得改用 raw CLI、`curl`、现场 Python/PowerShell 解析或 endpoint 探测。
+
 本地只读探查、读取远端公开事实、运行测试和可逆代码编辑无需逐动作确认，但编辑前应已有用户确认的方案。
 
 ## 永久硬停止点
@@ -134,11 +139,12 @@ Agent 创建或修改的 Issue/PR 正文，以及发布的 Issue 评论、PR 普
 
 ## 写操作幂等规则
 
+- `create-issue` 的预览确认前远端写入次数必须为零；每个 run 最多执行一次真实 `issue create`，且只能使用最终确认的完整 payload。`create_attempted=true` 后不得以测试、权限、编码、字段、API、重试、更换类型或替代 Issue 为由再次创建；成功后只允许回读和原地补齐已确认元数据，失败或结果不确定时只允许有界只读恢复并停止；
 - `create-issue` 不执行产品查重；创建结果不确定时只按目标仓库、当前账号、action 启动时间之后、标题和完整正文逐字一致做有界恢复，找到多个或不能证明唯一时停止；
 - 修改 assignee 后回读 Issue；
 - 创建 PR 前后按 canonical + source + head + base 查询；
 - 评论前按目标 discussion、正文语义和唯一尾签检查是否已有等价回复；
-- `code-review` finding 按 canonical + PR + `review_head_sha` + reviewer + path/position + 完整正文检查；检视通过按 canonical + PR + `review_head_sha` + reviewer + 精确 `/lgtm` 检查，不查找或发布检视摘要，旧 head 证据不得复用；
+- `code-review` finding 按 canonical + PR + `review_head_sha` + reviewer + path/position + 完整正文检查；检视通过按 canonical + PR + `review_head_sha` + reviewer + 精确 `/lgtm` 检查，不查找或发布检视摘要，旧 head 证据不得复用。该检查和写入只由固定 helper 完成；helper 受管 write receipt 仅持久化正文 SHA-256、固定 head、位置、写前集合和写后 ID，不保存正文或 Token。`attempting`/`write-returned` 恢复时先复核当前 head 并按 receipt 只读定位唯一评论，无法唯一证明时停止 `blocked: comment-write-uncertain`，禁止直接重试；
 - 除 `code-review` 的精确 `/lgtm` 外，严格机器协议命令前检查同一目标和协议动作的带尾签独立说明评论与命令是否已分别存在；
 - CI 使用 PR + head SHA 作为运行键；
 - resolve 前检查 `resolved`；