msdevflow 0.7.9 → 0.8.1

package/skill/msd/scripts/gitcode_review.py

@@ -0,0 +1,1653 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import argparse
+import base64
+import binascii
+import hashlib
+import json
+import os
+import re
+import shutil
+import subprocess
+import sys
+import tempfile
+import urllib.parse
+import uuid
+from dataclasses import dataclass
+from pathlib import Path, PurePosixPath
+from typing import Any, Callable, Iterable
+
+if os.name == "nt":
+    sys.stdout.reconfigure(encoding="utf-8")
+    sys.stderr.reconfigure(encoding="utf-8")
+
+TOOL_NAME = "msdevflow-gitcode-review"
+TOOL_VERSION = 1
+SIGNATURE = "——msdevflow"
+SNAPSHOT_MARKER = ".msdevflow-gitcode-review-snapshot"
+SNAPSHOT_MARKER_CONTENT = "managed-by=msdevflow\ntype=gitcode-review-snapshot\n"
+WRITE_RECEIPT_MARKER = ".msdevflow-gitcode-review-write-receipts"
+WRITE_RECEIPT_MARKER_CONTENT = "managed-by=msdevflow\ntype=gitcode-review-write-receipts\n"
+MAX_CONTENT_BYTES = 10 * 1024 * 1024
+MAX_JSON_BYTES = 16 * 1024 * 1024
+MAX_CONTEXT_FILES = 100
+REPOSITORY_PATTERN = re.compile(r"^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$")
+SHA_PATTERN = re.compile(r"^[0-9a-fA-F]{40}$")
+PR_URL_PATTERN = re.compile(
+    r"^https?://gitcode\.com/([^/]+)/([^/]+)/(?:pull|pulls|merge_requests)/(\d+)(?:[/?#].*)?$",
+    re.IGNORECASE,
+)
+
+
+class ReviewToolError(RuntimeError):
+    def __init__(self, error: str, message: str, exit_code: int = 4) -> None:
+        super().__init__(message)
+        self.error = error
+        self.exit_code = exit_code
+
+
+class GitCodeCommandError(ReviewToolError):
+    def __init__(self, operation: str, reason: str, return_code: int | None = None) -> None:
+        suffix = f"，退出码 {return_code}" if return_code is not None else ""
+        super().__init__("gitcode-command-failed", f"GitCode {operation} 失败：{reason}{suffix}", 3)
+        self.operation = operation
+        self.return_code = return_code
+
+
+@dataclass(frozen=True)
+class PullRequestTarget:
+    repository: str
+    number: int
+
+
+class GitCodeClient:
+    def __init__(
+        self,
+        command: str,
+        *,
+        runner: Callable[..., Any] = subprocess.run,
+        which: Callable[[str], str | None] = shutil.which,
+        platform: str | None = None,
+        timeout: int = 120,
+    ) -> None:
+        self.platform = platform or os.name
+        self.executable = resolve_gitcode_executable(command, which=which, platform=self.platform)
+        self.runner = runner
+        self.timeout = timeout
+
+    def _invocation(self, arguments: list[str]) -> list[str]:
+        if self.platform in {"nt", "win32"} and Path(self.executable).suffix.lower() in {".cmd", ".bat"}:
+            return [
+                "powershell.exe",
+                "-NoProfile",
+                "-Command",
+                "& { $exe = $args[0]; $rest = @($args | Select-Object -Skip 1); & $exe @rest; exit $LASTEXITCODE }",
+                self.executable,
+                *arguments,
+            ]
+        return [self.executable, *arguments]
+
+    def _run(
+        self,
+        arguments: list[str],
+        operation: str,
+        *,
+        stdout: Any = subprocess.PIPE,
+    ) -> Any:
+        try:
+            result = self.runner(
+                self._invocation(arguments),
+                stdin=subprocess.DEVNULL,
+                stdout=stdout,
+                stderr=subprocess.PIPE,
+                timeout=self.timeout,
+                check=False,
+            )
+        except FileNotFoundError as error:
+            raise GitCodeCommandError(operation, "命令不可用") from error
+        except subprocess.TimeoutExpired as error:
+            raise GitCodeCommandError(operation, "请求超时") from error
+        except OSError as error:
+            raise GitCodeCommandError(operation, "无法启动命令") from error
+        if result.returncode != 0:
+            raise GitCodeCommandError(operation, "远端或 CLI 返回错误", result.returncode)
+        return result
+
+    def check(self, arguments: list[str], operation: str) -> None:
+        self._run(arguments, operation, stdout=subprocess.DEVNULL)
+
+    def json(self, arguments: list[str], operation: str) -> Any:
+        with tempfile.TemporaryFile() as output_file:
+            result = self._run(arguments, operation, stdout=output_file)
+            output_file.seek(0, os.SEEK_END)
+            output_size = output_file.tell()
+            if not output_size and isinstance(result.stdout, (bytes, str)):
+                raw_output = result.stdout
+                output_size = len(raw_output.encode("utf-8") if isinstance(raw_output, str) else raw_output)
+            else:
+                output_file.seek(0)
+                raw_output = output_file.read()
+            if output_size > MAX_JSON_BYTES:
+                raise GitCodeCommandError(operation, "stdout JSON 超过 16 MiB 安全上限")
+        try:
+            output = decode_utf8(raw_output)
+            return json.loads(output)
+        except (UnicodeDecodeError, json.JSONDecodeError) as error:
+            raise GitCodeCommandError(operation, "stdout 不是有效 UTF-8 JSON") from error
+
+
+def resolve_gitcode_executable(
+    command: str,
+    *,
+    which: Callable[[str], str | None] = shutil.which,
+    platform: str | None = None,
+) -> str:
+    if command not in {"gitcode", "gitcode-npm"}:
+        raise ReviewToolError(
+            "invalid-gitcode-command",
+            "--gitcode-command 只允许本次环境已固定的 gitcode 或 gitcode-npm。",
+            2,
+        )
+    selected = which(command) or ""
+    if not selected:
+        raise ReviewToolError("gitcode-command-not-found", f"找不到 GitCode 命令：{command}", 3)
+    if (platform or os.name) in {"nt", "win32"}:
+        suffix = Path(selected).suffix.lower()
+        if suffix not in {".exe", ".com", ".cmd", ".bat"}:
+            raise ReviewToolError(
+                "gitcode-command-not-executable",
+                "Windows 下 GitCode 命令必须解析为 .exe、.com、.cmd 或 .bat，不能使用 PowerShell shim。",
+                3,
+            )
+    return selected
+
+
+def decode_utf8(value: bytes | str) -> str:
+    if isinstance(value, str):
+        return value.removeprefix("")
+    return value.decode("utf-8-sig")
+
+
+def is_strict_int(value: Any) -> bool:
+    return isinstance(value, int) and not isinstance(value, bool)
+
+
+def parse_pr_target(value: str, default_repository: str | None = None) -> PullRequestTarget:
+    candidate = value.strip()
+    match = PR_URL_PATTERN.fullmatch(candidate)
+    if match:
+        repository = f"{match.group(1)}/{match.group(2)}"
+        number = int(match.group(3))
+    elif candidate.isdigit():
+        if not default_repository:
+            raise ReviewToolError("repository-required", "纯 PR 编号必须同时提供 --repo owner/repo。", 2)
+        repository = default_repository
+        number = int(candidate)
+    else:
+        shorthand = re.fullmatch(r"([^#]+)#(\d+)", candidate)
+        if not shorthand:
+            raise ReviewToolError("invalid-pr-target", f"无法解析 PR 目标：{value}", 2)
+        repository = shorthand.group(1)
+        number = int(shorthand.group(2))
+    if not REPOSITORY_PATTERN.fullmatch(repository) or number <= 0:
+        raise ReviewToolError("invalid-pr-target", f"无效 PR 目标：{value}", 2)
+    if default_repository and candidate.isdigit() and repository != default_repository:
+        raise ReviewToolError("repository-mismatch", "PR 目标仓库与 --repo 不一致。", 2)
+    return PullRequestTarget(repository, number)
+
+
+def account_login(value: Any) -> str:
+    if isinstance(value, str):
+        return value
+    if not isinstance(value, dict):
+        return ""
+    for key in ("login", "username", "name"):
+        candidate = value.get(key)
+        if isinstance(candidate, str) and candidate:
+            return candidate
+    return ""
+
+
+def authentication_summary(payload: Any) -> dict[str, Any]:
+    if not isinstance(payload, dict):
+        raise ReviewToolError("authentication-invalid", "GitCode 认证状态不是预期 JSON。", 3)
+    username = account_login(payload) or account_login(payload.get("user"))
+    logged_in = payload.get("logged_in")
+    if logged_in is None:
+        logged_in = payload.get("authenticated")
+    summary = {"logged_in": bool(logged_in), "username": username}
+    if not summary["logged_in"] or not username:
+        raise ReviewToolError("authentication-required", "GitCode CLI 尚未认证或无法确定当前账号。", 3)
+    return summary
+
+
+def schema_flags(payload: Any) -> set[str]:
+    if not isinstance(payload, dict):
+        return set()
+    flags = payload.get("flags")
+    if not isinstance(flags, list):
+        return set()
+    return {
+        item.get("name")
+        for item in flags
+        if isinstance(item, dict) and isinstance(item.get("name"), str)
+    }
+
+
+def validate_capabilities(client: GitCodeClient, *, write: bool = False, inline: bool = False) -> None:
+    requirements = {
+        "issue view": {"repo", "json"},
+        "pr view": {"repo", "json"},
+        "pr comments": {"repo", "json"},
+    }
+    if write:
+        required = {"repo", "body-file", "json"}
+        if inline:
+            required.update({"path", "position"})
+        requirements["pr comment"] = required
+    for schema, required in requirements.items():
+        payload = client.json(["schema", schema], f"schema {schema}")
+        missing = required - schema_flags(payload)
+        if missing:
+            names = ", ".join(sorted(missing))
+            raise ReviewToolError(
+                "review-capability-required",
+                f"GitCode CLI 的 {schema} 缺少能力：{names}。请运行 npx msdevflow@latest setup。",
+                3,
+            )
+    try:
+        client.check(["api", "--help"], "check api capability")
+    except GitCodeCommandError as error:
+        raise ReviewToolError(
+            "review-capability-required",
+            "GitCode CLI 缺少固定 review helper 所需的 api 能力。请运行 npx msdevflow@latest setup。",
+            3,
+        ) from error
+
+
+def pull_request_summary(payload: Any, target: PullRequestTarget) -> dict[str, Any]:
+    if not isinstance(payload, dict):
+        raise ReviewToolError("pr-json-invalid", "PR JSON 不是对象。", 3)
+    head = payload.get("head") if isinstance(payload.get("head"), dict) else {}
+    base = payload.get("base") if isinstance(payload.get("base"), dict) else {}
+    head_repo = head.get("repo") if isinstance(head.get("repo"), dict) else {}
+    base_repo = base.get("repo") if isinstance(base.get("repo"), dict) else {}
+    number = payload.get("number")
+    if number != target.number:
+        raise ReviewToolError("pr-target-mismatch", "PR 回读编号与请求目标不一致。", 3)
+    canonical = base_repo.get("full_name") or target.repository
+    if canonical != target.repository:
+        raise ReviewToolError("pr-target-mismatch", "PR 回读 canonical repository 与请求目标不一致。", 3)
+    return {
+        "repository": target.repository,
+        "number": number,
+        "title": payload.get("title") if isinstance(payload.get("title"), str) else "",
+        "state": str(payload.get("state") or "").lower(),
+        "draft": bool(payload.get("draft") or payload.get("work_in_progress") or payload.get("wip")),
+        "author": account_login(payload.get("user") or payload.get("author")),
+        "head_sha": str(head.get("sha") or ""),
+        "head_ref": str(head.get("ref") or head.get("label") or ""),
+        "head_repository": str(head_repo.get("full_name") or ""),
+        "base_sha": str(base.get("sha") or ""),
+        "base_ref": str(base.get("ref") or base.get("label") or ""),
+        "base_repository": str(base_repo.get("full_name") or target.repository),
+        "changed_files": payload.get("changed_files"),
+        "additions": payload.get("additions"),
+        "deletions": payload.get("deletions"),
+        "html_url": str(payload.get("html_url") or ""),
+    }
+
+
+def unwrap_comments(payload: Any) -> list[dict[str, Any]]:
+    if isinstance(payload, dict):
+        payload = payload.get("comments")
+    if not isinstance(payload, list) or any(not isinstance(item, dict) for item in payload):
+        raise ReviewToolError("comments-json-invalid", "PR comments JSON 不是完整对象列表。", 3)
+    return payload
+
+
+def normalize_newlines(value: str) -> str:
+    return value.replace("\r\n", "\n").replace("\r", "\n")
+
+
+def normalize_comment(payload: dict[str, Any]) -> dict[str, Any]:
+    position = payload.get("diff_position")
+    if not isinstance(position, dict):
+        position = payload.get("position") if isinstance(payload.get("position"), dict) else {}
+    user = payload.get("user") or payload.get("author")
+    return {
+        "id": payload.get("id"),
+        "discussion_id": str(payload.get("discussion_id") or ""),
+        "body": normalize_newlines(str(payload.get("body") or "")),
+        "author": account_login(user),
+        "resolved": bool(payload.get("resolved")),
+        "comment_type": str(payload.get("comment_type") or ""),
+        "path": str(
+            payload.get("diff_file")
+            or position.get("new_path")
+            or position.get("old_path")
+            or ""
+        ),
+        "new_line": position.get("new_line") or position.get("start_new_line") or position.get("end_new_line"),
+        "head_sha": str(position.get("head_sha") or ""),
+        "created_at": payload.get("created_at"),
+    }
+
+
+def normalize_comment_detail(payload: Any) -> dict[str, Any]:
+    if not isinstance(payload, dict):
+        raise ReviewToolError("comment-detail-invalid", "PR comment detail JSON 不是对象。", 3)
+    position = payload.get("position") if isinstance(payload.get("position"), dict) else {}
+    return {
+        "id": payload.get("id"),
+        "discussion_id": str(payload.get("discussion_id") or ""),
+        "body": normalize_newlines(str(payload.get("body") or "")),
+        "author": account_login(payload.get("user") or payload.get("author")),
+        "resolved": bool(payload.get("resolved")),
+        "comment_type": str(payload.get("comment_type") or ""),
+        "outdated": payload.get("is_outdated") is True,
+        "path": str(position.get("new_path") or position.get("old_path") or ""),
+        "new_line": position.get("new_line"),
+        "head_sha": str(position.get("head_sha") or ""),
+    }
+
+
+def normalized_files(payload: Any) -> list[dict[str, Any]]:
+    if not isinstance(payload, list) or any(not isinstance(item, dict) for item in payload):
+        raise ReviewToolError("files-json-invalid", "PR changed-files JSON 不是完整对象列表。", 3)
+    result = []
+    for item in payload:
+        patch = item.get("patch") if isinstance(item.get("patch"), dict) else {}
+        filename = item.get("filename") or patch.get("new_path") or patch.get("old_path")
+        result.append({
+            "raw": item,
+            "filename": str(filename or ""),
+            "old_path": str(patch.get("old_path") or filename or ""),
+            "new_path": str(patch.get("new_path") or filename or ""),
+            "new_file": bool(patch.get("new_file")),
+            "deleted_file": bool(patch.get("deleted_file")),
+            "renamed_file": bool(patch.get("renamed_file")),
+            "too_large": bool(patch.get("too_large")),
+            "diff": patch.get("diff") if isinstance(patch.get("diff"), str) else None,
+            "additions": item.get("additions", patch.get("added_lines")),
+            "deletions": item.get("deletions", patch.get("removed_lines")),
+        })
+    return result
+
+
+def safe_remote_path(path: str) -> bool:
+    if not path or "\\" in path or "\x00" in path:
+        return False
+    candidate = PurePosixPath(path)
+    return not candidate.is_absolute() and all(part not in {"", ".", ".."} for part in candidate.parts)
+
+
+def artifact_name(index: int, label: str, remote_path: str, suffix: str = "") -> str:
+    basename = PurePosixPath(remote_path).name if remote_path else "artifact"
+    basename = re.sub(r"[^A-Za-z0-9_.-]", "_", basename)[:80] or "artifact"
+    return f"{index:04d}-{label}-{basename}{suffix}"
+
+
+def write_json(path: Path, payload: Any) -> None:
+    path.write_text(json.dumps(payload, ensure_ascii=False, indent=2) + "\n", encoding="utf-8", newline="\n")
+
+
+def api_endpoint(repository: str, tail: str) -> str:
+    return f"repos/{repository}/{tail}"
+
+
+def content_endpoint(repository: str, path: str, ref: str) -> str:
+    encoded_path = urllib.parse.quote(path, safe="/")
+    encoded_ref = urllib.parse.quote(ref, safe="")
+    return api_endpoint(repository, f"contents/{encoded_path}?ref={encoded_ref}")
+
+
+def decode_repository_content(payload: Any) -> tuple[bytes, dict[str, Any]]:
+    if not isinstance(payload, dict) or payload.get("type") != "file":
+        raise ReviewToolError("repository-content-invalid", "仓库 contents API 未返回文件。", 3)
+    size = payload.get("size")
+    if isinstance(size, int) and size > MAX_CONTENT_BYTES:
+        raise ReviewToolError("repository-content-too-large", "仓库文件超过 helper 的 10 MiB 安全上限。", 4)
+    if payload.get("encoding") != "base64" or not isinstance(payload.get("content"), str):
+        raise ReviewToolError("repository-content-invalid", "仓库文件不是完整 base64 内容。", 3)
+    try:
+        compact = re.sub(r"\s+", "", payload["content"])
+        data = base64.b64decode(compact, validate=True)
+    except (ValueError, binascii.Error) as error:
+        raise ReviewToolError("repository-content-invalid", "仓库文件 base64 内容无效。", 3) from error
+    if len(data) > MAX_CONTENT_BYTES:
+        raise ReviewToolError("repository-content-too-large", "仓库文件超过 helper 的 10 MiB 安全上限。", 4)
+    if isinstance(size, int) and size != len(data):
+        raise ReviewToolError("repository-content-incomplete", "仓库文件长度与 contents API 元数据不一致。", 3)
+    try:
+        data.decode("utf-8")
+        text_encoding = "utf-8"
+    except UnicodeDecodeError:
+        text_encoding = "binary"
+    return data, {
+        "sha": str(payload.get("sha") or ""),
+        "size": len(data),
+        "content_kind": text_encoding,
+    }
+
+
+def fetch_content(
+    client: GitCodeClient,
+    repository: str,
+    remote_path: str,
+    ref: str,
+    output_path: Path,
+) -> dict[str, Any]:
+    payload = client.json(
+        ["api", content_endpoint(repository, remote_path, ref)],
+        f"read repository content {remote_path}",
+    )
+    data, metadata = decode_repository_content(payload)
+    output_path.write_bytes(data)
+    return {
+        "remote_path": remote_path,
+        "ref": ref,
+        "artifact": output_path.name,
+        **metadata,
+    }
+
+
+def applicable_context_paths(tree: Iterable[dict[str, Any]], changed_paths: list[str]) -> list[str]:
+    selected: set[str] = set()
+    applicable_configs = {
+        ".pre-commit-config.yaml",
+        "cargo.toml",
+        "cmakelists.txt",
+        "go.mod",
+        "makefile",
+        "package.json",
+        "pyproject.toml",
+        "pytest.ini",
+        "tox.ini",
+    }
+    for item in tree:
+        if not isinstance(item, dict) or item.get("type") not in {"blob", "file"}:
+            continue
+        path = str(item.get("path") or "")
+        if not safe_remote_path(path):
+            continue
+        pure = PurePosixPath(path)
+        basename = pure.name.lower()
+        parent = "" if str(pure.parent) == "." else str(pure.parent)
+        applies = not parent or any(
+            changed == parent or changed.startswith(f"{parent}/") for changed in changed_paths
+        )
+        if basename in {"agents.md", "claude.md", "owners"} and applies:
+            selected.add(path)
+        elif basename == "codeowners" and (applies or parent in {".gitcode", ".github"}):
+            selected.add(path)
+        elif basename.startswith("contributing") and not parent:
+            selected.add(path)
+        elif basename.startswith("readme") and applies:
+            selected.add(path)
+        elif basename in applicable_configs and applies:
+            selected.add(path)
+    return sorted(selected)
+
+
+def issue_references(payload: dict[str, Any], repository: str) -> list[dict[str, Any]]:
+    body = str(payload.get("body") or payload.get("description") or "")
+    references: set[tuple[str, int]] = set()
+    for owner, repo, number in re.findall(
+        r"https?://gitcode\.com/([^/\s]+)/([^/\s]+)/issues/(\d+)", body, re.IGNORECASE
+    ):
+        candidate = f"{owner}/{repo}"
+        if REPOSITORY_PATTERN.fullmatch(candidate):
+            references.add((candidate, int(number)))
+    for number in re.findall(r"(?i)\bissue\s*#(\d+)\b", body):
+        references.add((repository, int(number)))
+    return [
+        {"repository": candidate, "number": number, "source": "pr-body-reference"}
+        for candidate, number in sorted(references)
+    ]
+
+
+def collect_issue_snapshots(
+    client: GitCodeClient,
+    references: list[dict[str, Any]],
+    directory: Path,
+) -> tuple[list[dict[str, Any]], list[str]]:
+    if not references:
+        return [], []
+    directory.mkdir()
+    artifacts = []
+    incomplete = []
+    for index, reference in enumerate(references, start=1):
+        repository = reference["repository"]
+        number = reference["number"]
+        try:
+            payload = client.json(
+                ["issue", "view", str(number), "-R", repository, "--json"],
+                f"read linked Issue {repository}#{number}",
+            )
+            artifact = directory / f"{index:04d}-{repository.replace('/', '--')}-{number}.json"
+            write_json(artifact, payload)
+            artifacts.append({**reference, "artifact": artifact.name})
+        except ReviewToolError as error:
+            incomplete.append(f"linked Issue unavailable: {repository}#{number} ({error.error})")
+    return artifacts, incomplete
+
+
+def create_snapshot_directory(output_root: Path | None = None) -> Path:
+    root = (output_root or Path(tempfile.gettempdir()) / "msdevflow-review-snapshots").expanduser().resolve()
+    root.mkdir(parents=True, exist_ok=True)
+    snapshot = root / f"review-{uuid.uuid4().hex}"
+    snapshot.mkdir(mode=0o700)
+    (snapshot / SNAPSHOT_MARKER).write_text(SNAPSHOT_MARKER_CONTENT, encoding="utf-8", newline="\n")
+    return snapshot
+
+
+def collect_comment_details(
+    client: GitCodeClient,
+    repository: str,
+    comments: list[dict[str, Any]],
+    directory: Path,
+) -> tuple[list[dict[str, Any]], list[str]]:
+    details = []
+    incomplete = []
+    directory.mkdir()
+    for index, comment in enumerate(comments, start=1):
+        normalized = normalize_comment(comment)
+        numeric_id = normalized["id"]
+        label = normalized["discussion_id"] or numeric_id or index
+        comment_type = normalized["comment_type"].lower()
+        numeric_id_valid = (
+            is_strict_int(numeric_id)
+            and numeric_id > 0
+        )
+        if not numeric_id_valid:
+            incomplete.append(f"comment {label} has no numeric ID")
+        if not normalized["discussion_id"]:
+            incomplete.append(f"comment {label} has no discussion ID")
+        if not normalized["author"]:
+            incomplete.append(f"comment {label} has no author")
+        if not isinstance(comment.get("body"), str):
+            incomplete.append(f"comment {label} body is unavailable")
+        if not isinstance(comment.get("resolved"), bool):
+            incomplete.append(f"comment {label} resolution is unavailable")
+        if comment_type not in {"pr_comment", "diff_comment"}:
+            incomplete.append(f"comment {label} has unsupported type {comment_type or 'unknown'}")
+        has_position = bool(
+            normalized["path"] or normalized["new_line"] or normalized["head_sha"]
+        )
+        if has_position and comment_type != "diff_comment":
+            incomplete.append(f"comment {label} has position but is not a diff comment")
+        requires_detail = comment_type == "diff_comment" or has_position
+        if not requires_detail:
+            details.append({"comment": normalized, "detail": None})
+            continue
+        if not numeric_id_valid:
+            details.append({"comment": normalized, "detail": None})
+            continue
+        try:
+            payload = client.json(
+                ["api", api_endpoint(repository, f"pulls/comments/{numeric_id}")],
+                f"read pull comment {numeric_id}",
+            )
+            detail = normalize_comment_detail(payload)
+            write_json(directory / f"{index:04d}-{numeric_id}.json", payload)
+            detail_type = detail["comment_type"].lower()
+            detail_line = detail["new_line"]
+            if (
+                not safe_remote_path(detail["path"])
+                or not is_strict_int(detail_line)
+                or detail_line <= 0
+                or not SHA_PATTERN.fullmatch(detail["head_sha"])
+            ):
+                incomplete.append(f"diff comment {numeric_id} detail lacks path, line, or head")
+            if not isinstance(payload.get("body"), str):
+                incomplete.append(f"diff comment {numeric_id} detail body is unavailable")
+            if not isinstance(payload.get("resolved"), bool):
+                incomplete.append(f"diff comment {numeric_id} detail resolution is unavailable")
+            if "is_outdated" in payload and not isinstance(payload.get("is_outdated"), bool):
+                incomplete.append(f"diff comment {numeric_id} detail outdated state is invalid")
+            if detail_type not in {"pr_comment", "diff_comment"}:
+                incomplete.append(
+                    f"diff comment {numeric_id} detail has unsupported type "
+                    f"{detail_type or 'unknown'}"
+                )
+            if detail_type != comment_type:
+                incomplete.append(f"diff comment {numeric_id} detail type mismatches")
+            if detail["id"] != numeric_id:
+                incomplete.append(f"diff comment {numeric_id} detail ID mismatches")
+            if detail["discussion_id"] != normalized["discussion_id"]:
+                incomplete.append(f"diff comment {numeric_id} discussion ID mismatches")
+            if detail["author"] != normalized["author"]:
+                incomplete.append(f"diff comment {numeric_id} author mismatches")
+            if detail["body"] != normalized["body"]:
+                incomplete.append(f"diff comment {numeric_id} body mismatches")
+            if detail["resolved"] != normalized["resolved"]:
+                incomplete.append(f"diff comment {numeric_id} resolution mismatches")
+            details.append({"comment": normalized, "detail": detail})
+        except ReviewToolError:
+            incomplete.append(f"diff comment {numeric_id} detail unavailable")
+            details.append({"comment": normalized, "detail": None})
+    return details, incomplete
+
+
+def collect_tree_context(
+    client: GitCodeClient,
+    repository: str,
+    base_ref: str,
+    changed_paths: list[str],
+    directory: Path,
+) -> tuple[dict[str, Any], list[str]]:
+    incomplete = []
+    directory.mkdir()
+    try:
+        encoded_ref = urllib.parse.quote(base_ref, safe="")
+        tree_payload = client.json(
+            ["api", api_endpoint(repository, f"git/trees/{encoded_ref}?recursive=1")],
+            "read repository tree",
+        )
+    except ReviewToolError:
+        return {"tree": None, "files": []}, ["repository tree unavailable"]
+    write_json(directory / "tree.json", tree_payload)
+    tree = tree_payload.get("tree") if isinstance(tree_payload, dict) else None
+    if not isinstance(tree, list):
+        return {"tree": "tree.json", "files": []}, ["repository tree response is incomplete"]
+    if tree_payload.get("truncated") is True:
+        incomplete.append("repository tree is truncated")
+    paths = applicable_context_paths(tree, changed_paths)
+    if len(paths) > MAX_CONTEXT_FILES:
+        incomplete.append("applicable repository context exceeds 100 files")
+        paths = paths[:MAX_CONTEXT_FILES]
+    artifacts = []
+    content_dir = directory / "files"
+    content_dir.mkdir()
+    for index, path in enumerate(paths, start=1):
+        artifact = content_dir / artifact_name(index, "base", path)
+        try:
+            metadata = fetch_content(client, repository, path, base_ref, artifact)
+            metadata["artifact"] = str(Path("files") / metadata["artifact"])
+            artifacts.append(metadata)
+        except ReviewToolError as error:
+            incomplete.append(f"repository context unavailable: {path} ({error.error})")
+    return {"tree": "tree.json", "tree_truncated": tree_payload.get("truncated"), "files": artifacts}, incomplete
+
+
+def collect_pull_request_snapshot(
+    client: GitCodeClient,
+    target: PullRequestTarget,
+    reviewer: str,
+    root: Path,
+) -> dict[str, Any]:
+    directory = root / f"pr-{target.repository.replace('/', '--')}-{target.number}"
+    directory.mkdir()
+    pr_payload = client.json(
+        ["pr", "view", str(target.number), "-R", target.repository, "--json"],
+        f"read PR {target.repository}#{target.number}",
+    )
+    pr = pull_request_summary(pr_payload, target)
+    write_json(directory / "pr.json", pr_payload)
+    write_json(directory / "pr-summary.json", pr)
+
+    files_payload = client.json(
+        ["api", api_endpoint(target.repository, f"pulls/{target.number}/files")],
+        f"read PR files {target.repository}#{target.number}",
+    )
+    write_json(directory / "files.json", files_payload)
+    files = normalized_files(files_payload)
+    incomplete: list[str] = []
+    expected_count = pr.get("changed_files")
+    if (
+        not is_strict_int(expected_count)
+        or expected_count < 0
+    ):
+        incomplete.append("PR changed-files count is unavailable")
+    elif expected_count != len(files):
+        incomplete.append(f"changed-files count mismatch: expected {expected_count}, got {len(files)}")
+
+    patch_dir = directory / "patches"
+    content_dir = directory / "contents"
+    patch_dir.mkdir()
+    content_dir.mkdir()
+    head_repository = pr["head_repository"]
+    head_repository_valid = bool(REPOSITORY_PATTERN.fullmatch(head_repository))
+    if not head_repository_valid:
+        incomplete.append("PR head repository is unavailable or invalid")
+    file_manifest = []
+    changed_paths = []
+    for index, item in enumerate(files, start=1):
+        filename = item["filename"]
+        changed_path = item["new_path"] or item["old_path"]
+        if safe_remote_path(changed_path):
+            changed_paths.append(changed_path)
+        entry = {
+            key: item[key]
+            for key in (
+                "filename", "old_path", "new_path", "new_file", "deleted_file", "renamed_file",
+                "too_large", "additions", "deletions",
+            )
+        }
+        if not safe_remote_path(filename) or not safe_remote_path(item["old_path"]) or not safe_remote_path(item["new_path"]):
+            incomplete.append(f"changed file {index} has an unsafe or empty path")
+            entry["complete"] = False
+            file_manifest.append(entry)
+            continue
+        diff = item["diff"]
+        if item["too_large"] or diff is None:
+            incomplete.append(f"patch unavailable: {filename}")
+            entry["patch"] = None
+        else:
+            patch_path = patch_dir / artifact_name(index, "patch", filename, ".diff")
+            patch_path.write_text(diff, encoding="utf-8", newline="\n")
+            entry["patch"] = str(Path("patches") / patch_path.name)
+        entry["contents"] = {}
+        if not item["new_file"]:
+            base_path = content_dir / artifact_name(index, "base", item["old_path"])
+            try:
+                content = fetch_content(
+                    client, target.repository, item["old_path"], pr["base_ref"], base_path
+                )
+                content["artifact"] = str(Path("contents") / content["artifact"])
+                entry["contents"]["base"] = content
+            except ReviewToolError as error:
+                incomplete.append(f"base content unavailable: {item['old_path']} ({error.error})")
+        if not item["deleted_file"] and head_repository_valid:
+            head_path = content_dir / artifact_name(index, "head", item["new_path"])
+            try:
+                content = fetch_content(
+                    client, head_repository, item["new_path"], pr["head_ref"], head_path
+                )
+                content["artifact"] = str(Path("contents") / content["artifact"])
+                entry["contents"]["head"] = content
+            except ReviewToolError as error:
+                incomplete.append(f"head content unavailable: {item['new_path']} ({error.error})")
+        entry["complete"] = bool(entry.get("patch")) and (
+            item["new_file"] or "base" in entry["contents"]
+        ) and (
+            item["deleted_file"] or "head" in entry["contents"]
+        )
+        file_manifest.append(entry)
+    write_json(directory / "files-manifest.json", file_manifest)
+
+    comments_payload = client.json(
+        ["pr", "comments", str(target.number), "-R", target.repository, "--json"],
+        f"read PR comments {target.repository}#{target.number}",
+    )
+    comments = unwrap_comments(comments_payload)
+    write_json(directory / "comments.json", comments_payload)
+    comment_details, comment_incomplete = collect_comment_details(
+        client, target.repository, comments, directory / "comment-details"
+    )
+    incomplete.extend(comment_incomplete)
+    write_json(directory / "comments-manifest.json", comment_details)
+
+    if pr["base_ref"]:
+        context, context_incomplete = collect_tree_context(
+            client,
+            target.repository,
+            pr["base_ref"],
+            [path for path in changed_paths if path],
+            directory / "repository-context",
+        )
+        incomplete.extend(context_incomplete)
+    else:
+        context = {"tree": None, "files": []}
+        incomplete.append("PR base ref is unavailable")
+    write_json(directory / "repository-context.json", context)
+
+    references = issue_references(pr_payload, target.repository)
+    linked_issues, issue_incomplete = collect_issue_snapshots(
+        client, references, directory / "linked-issues"
+    )
+    incomplete.extend(issue_incomplete)
+    write_json(directory / "linked-issues.json", linked_issues)
+
+    final_pr_payload = client.json(
+        ["pr", "view", str(target.number), "-R", target.repository, "--json"],
+        f"re-read PR {target.repository}#{target.number}",
+    )
+    final_pr = pull_request_summary(final_pr_payload, target)
+    if final_pr["head_sha"] != pr["head_sha"]:
+        incomplete.append("PR head changed while collecting snapshot")
+    if final_pr["base_sha"] != pr["base_sha"]:
+        incomplete.append("PR base changed while collecting snapshot")
+    if pr["state"] != "open":
+        incomplete.append(f"PR state is {pr['state'] or 'unknown'}")
+    if pr["draft"]:
+        incomplete.append("PR is draft")
+    if not pr["author"]:
+        incomplete.append("PR author is unavailable")
+    if not SHA_PATTERN.fullmatch(pr["head_sha"]):
+        incomplete.append("PR head SHA is unavailable or invalid")
+    if not SHA_PATTERN.fullmatch(pr["base_sha"]):
+        incomplete.append("PR base SHA is unavailable or invalid")
+    if pr["author"] == reviewer:
+        incomplete.append("current account is the PR author")
+    incomplete = list(dict.fromkeys(incomplete))
+    result = {
+        "repository": target.repository,
+        "number": target.number,
+        "reviewer": reviewer,
+        "author": pr["author"],
+        "head_sha": pr["head_sha"],
+        "base_sha": pr["base_sha"],
+        "base_ref": pr["base_ref"],
+        "state": pr["state"],
+        "draft": pr["draft"],
+        "directory": directory.name,
+        "files_count": len(files),
+        "comments_count": len(comments),
+        "linked_issues": linked_issues,
+        "snapshot_complete": not incomplete,
+        "incomplete_reasons": incomplete,
+    }
+    write_json(directory / "manifest.json", result)
+    return result
+
+
+def collect_additional_context(
+    client: GitCodeClient,
+    target: PullRequestTarget,
+    expected_head: str,
+    side: str,
+    paths: list[str],
+) -> dict[str, Any]:
+    if not SHA_PATTERN.fullmatch(expected_head):
+        raise ReviewToolError("invalid-head", "--expected-head 必须是完整 40 位 SHA。", 2)
+    for path in paths:
+        if not safe_remote_path(path):
+            raise ReviewToolError("context-path-invalid", f"无效仓库上下文路径：{path}", 2)
+    payload = client.json(
+        ["pr", "view", str(target.number), "-R", target.repository, "--json"],
+        f"read PR {target.repository}#{target.number}",
+    )
+    pr = pull_request_summary(payload, target)
+    if pr["head_sha"] != expected_head:
+        raise ReviewToolError("head-changed", "PR head 已变化，禁止读取旧 head 上下文。", 4)
+    head_repository = pr["head_repository"]
+    if not REPOSITORY_PATTERN.fullmatch(head_repository):
+        raise ReviewToolError("head-repository-invalid", "PR head repository 缺失或无效。", 4)
+    selections = []
+    if side in {"base", "both"}:
+        selections.append(("base", target.repository, pr["base_ref"]))
+    if side in {"head", "both"}:
+        selections.append(("head", head_repository, pr["head_ref"]))
+    if any(not ref for _, _, ref in selections):
+        raise ReviewToolError("context-ref-invalid", "PR base/head ref 不完整。", 4)
+    snapshot = create_snapshot_directory()
+    artifacts = []
+    try:
+        content_dir = snapshot / "contents"
+        content_dir.mkdir()
+        index = 0
+        for label, repository, ref in selections:
+            for path in paths:
+                index += 1
+                artifact = content_dir / artifact_name(index, label, path)
+                metadata = fetch_content(client, repository, path, ref, artifact)
+                metadata.update({
+                    "side": label,
+                    "repository": repository,
+                    "artifact": str(Path("contents") / metadata["artifact"]),
+                })
+                artifacts.append(metadata)
+        final_payload = client.json(
+            ["pr", "view", str(target.number), "-R", target.repository, "--json"],
+            f"re-read PR {target.repository}#{target.number}",
+        )
+        final_pr = pull_request_summary(final_payload, target)
+        if final_pr["head_sha"] != expected_head or final_pr["base_sha"] != pr["base_sha"]:
+            raise ReviewToolError("head-changed", "读取上下文期间 PR head/base 已变化。", 4)
+        manifest = {
+            "tool": TOOL_NAME,
+            "version": TOOL_VERSION,
+            "type": "additional-context",
+            "repository": target.repository,
+            "number": target.number,
+            "head_sha": expected_head,
+            "base_sha": pr["base_sha"],
+            "artifacts": artifacts,
+        }
+        write_json(snapshot / "manifest.json", manifest)
+    except Exception:
+        shutil.rmtree(snapshot)
+        raise
+    return {
+        "tool": TOOL_NAME,
+        "version": TOOL_VERSION,
+        "state": "context-ready",
+        "snapshot_dir": str(snapshot),
+        "manifest": str(snapshot / "manifest.json"),
+        "repository": target.repository,
+        "number": target.number,
+        "head_sha": expected_head,
+        "artifacts_count": len(artifacts),
+    }
+
+
+def create_snapshot(
+    client: GitCodeClient,
+    targets: list[PullRequestTarget],
+    output_root: Path | None = None,
+) -> dict[str, Any]:
+    auth = authentication_summary(client.json(["auth", "status", "--json"], "read authentication status"))
+    snapshot = create_snapshot_directory(output_root)
+    results = []
+    try:
+        for target in targets:
+            results.append(collect_pull_request_snapshot(client, target, auth["username"], snapshot))
+        manifest = {
+            "tool": TOOL_NAME,
+            "version": TOOL_VERSION,
+            "snapshot_id": snapshot.name,
+            "reviewer": auth["username"],
+            "prs": results,
+        }
+        write_json(snapshot / "manifest.json", manifest)
+    except Exception:
+        shutil.rmtree(snapshot)
+        raise
+    state = "snapshot-ready" if all(item["snapshot_complete"] for item in results) else "review-incomplete"
+    return {
+        "tool": TOOL_NAME,
+        "version": TOOL_VERSION,
+        "state": state,
+        "snapshot_dir": str(snapshot),
+        "manifest": str(snapshot / "manifest.json"),
+        "reviewer": auth["username"],
+        "prs": [
+            {
+                "repository": item["repository"],
+                "number": item["number"],
+                "head_sha": item["head_sha"],
+                "author": item["author"],
+                "snapshot_complete": item["snapshot_complete"],
+                "incomplete_reasons": item["incomplete_reasons"],
+                "manifest": str(snapshot / item["directory"] / "manifest.json"),
+            }
+            for item in results
+        ],
+    }
+
+
+def validate_finding_body(path: Path) -> str:
+    data = path.read_bytes()
+    if data.startswith(b"\xef\xbb\xbf"):
+        raise ReviewToolError("finding-body-invalid", "Finding 正文必须是 UTF-8 无 BOM。", 2)
+    try:
+        body = normalize_newlines(data.decode("utf-8"))
+    except UnicodeDecodeError as error:
+        raise ReviewToolError("finding-body-invalid", "Finding 正文不是有效 UTF-8。", 2) from error
+    if body.count(SIGNATURE) != 1 or not body.endswith(f"\n\n{SIGNATURE}"):
+        raise ReviewToolError(
+            "finding-signature-invalid",
+            f"Finding 正文必须以一个空行和唯一 {SIGNATURE} 结尾。",
+            2,
+        )
+    return body
+
+
+def ensure_review_write_target(
+    client: GitCodeClient,
+    target: PullRequestTarget,
+    expected_head: str,
+) -> tuple[str, dict[str, Any]]:
+    if not SHA_PATTERN.fullmatch(expected_head):
+        raise ReviewToolError("invalid-head", "--expected-head 必须是完整 40 位 SHA。", 2)
+    auth = authentication_summary(client.json(["auth", "status", "--json"], "read authentication status"))
+    payload = client.json(
+        ["pr", "view", str(target.number), "-R", target.repository, "--json"],
+        f"read PR {target.repository}#{target.number}",
+    )
+    pr = pull_request_summary(payload, target)
+    if pr["head_sha"] != expected_head:
+        raise ReviewToolError("head-changed", "PR head 已变化，禁止发布旧 head 的检视结论。", 4)
+    if pr["state"] != "open" or pr["draft"]:
+        raise ReviewToolError("pr-not-reviewable", "PR 当前不是 open 且非 Draft 的可检视状态。", 4)
+    if not pr["author"]:
+        raise ReviewToolError("author-unavailable", "无法确认 PR author。", 4)
+    if pr["author"] == auth["username"]:
+        raise ReviewToolError("self-review-forbidden", "当前账号是 PR author，禁止发布 reviewer 结论。", 4)
+    return auth["username"], pr
+
+
+def comment_identity(comment: dict[str, Any]) -> tuple[str, str]:
+    normalized = normalize_comment(comment)
+    return str(normalized["id"] or ""), normalized["discussion_id"]
+
+
+def write_comment_candidate(
+    comment: dict[str, Any],
+    normalized: dict[str, Any],
+    expected_type: str,
+) -> bool:
+    numeric_id = normalized["id"]
+    return (
+        is_strict_int(numeric_id)
+        and numeric_id > 0
+        and bool(normalized["discussion_id"])
+        and bool(normalized["author"])
+        and isinstance(comment.get("body"), str)
+        and isinstance(comment.get("resolved"), bool)
+        and normalized["comment_type"].lower() == expected_type
+    )
+
+
+def read_comments(client: GitCodeClient, target: PullRequestTarget) -> list[dict[str, Any]]:
+    payload = client.json(
+        ["pr", "comments", str(target.number), "-R", target.repository, "--json"],
+        f"read PR comments {target.repository}#{target.number}",
+    )
+    return unwrap_comments(payload)
+
+
+def read_comment_detail(client: GitCodeClient, repository: str, numeric_id: Any) -> dict[str, Any]:
+    if (
+        not is_strict_int(numeric_id)
+        or numeric_id <= 0
+    ):
+        raise ReviewToolError("comment-id-invalid", "评论缺少 numeric comment ID。", 4)
+    payload = client.json(
+        ["api", api_endpoint(repository, f"pulls/comments/{numeric_id}")],
+        f"read pull comment {numeric_id}",
+    )
+    detail = normalize_comment_detail(payload)
+    if (
+        detail["id"] != numeric_id
+        or not isinstance(payload.get("body"), str)
+        or not isinstance(payload.get("resolved"), bool)
+        or detail["comment_type"].lower() != "diff_comment"
+    ):
+        raise ReviewToolError("comment-detail-mismatch", "评论详情身份或结构与请求不一致。", 4)
+    return detail
+
+
+def verified_inline_comment(
+    client: GitCodeClient,
+    target: PullRequestTarget,
+    normalized: dict[str, Any],
+    reviewer: str,
+    body: str,
+    path: str,
+    position: int,
+    expected_head: str,
+) -> dict[str, Any] | None:
+    detail = read_comment_detail(client, target.repository, normalized["id"])
+    if (
+        detail["discussion_id"] != normalized["discussion_id"]
+        or detail["author"] != normalized["author"]
+        or detail["body"] != normalized["body"]
+        or detail["resolved"] != normalized["resolved"]
+        or detail["comment_type"].lower() != "diff_comment"
+        or detail["author"] != reviewer
+        or detail["body"] != body
+        or detail["path"] != path
+        or detail["new_line"] != position
+        or detail["head_sha"] != expected_head
+    ):
+        return None
+    return detail
+
+
+def find_existing_inline_comment(
+    client: GitCodeClient,
+    target: PullRequestTarget,
+    comments: list[dict[str, Any]],
+    reviewer: str,
+    body: str,
+    path: str,
+    position: int,
+    expected_head: str,
+) -> dict[str, Any] | None:
+    matches = []
+    for comment in comments:
+        normalized = normalize_comment(comment)
+        if (
+            not write_comment_candidate(comment, normalized, "diff_comment")
+            or normalized["author"] != reviewer
+            or normalized["body"] != body
+        ):
+            continue
+        detail = verified_inline_comment(
+            client,
+            target,
+            normalized,
+            reviewer,
+            body,
+            path,
+            position,
+            expected_head,
+        )
+        if detail:
+            matches.append(detail)
+    if len(matches) > 1:
+        raise ReviewToolError("comment-result-ambiguous", "找到多个等价 finding，无法证明唯一结果。", 4)
+    return matches[0] if matches else None
+
+
+def select_written_comment(
+    client: GitCodeClient,
+    target: PullRequestTarget,
+    comments: list[dict[str, Any]],
+    preexisting: set[tuple[str, str]],
+    reviewer: str,
+    body: str,
+    response_id: str,
+    path: str | None,
+    position: int | None,
+    expected_head: str,
+) -> dict[str, Any]:
+    candidates = []
+    expected_type = "diff_comment" if path is not None else "pr_comment"
+    for raw in comments:
+        normalized = normalize_comment(raw)
+        identity = comment_identity(raw)
+        response_match = bool(
+            response_id
+            and (response_id == identity[0] or response_id == identity[1])
+        )
+        if not response_match and identity in preexisting:
+            continue
+        if (
+            not write_comment_candidate(raw, normalized, expected_type)
+            or normalized["author"] != reviewer
+            or normalized["body"] != body
+        ):
+            continue
+        if path is not None:
+            detail = verified_inline_comment(
+                client,
+                target,
+                normalized,
+                reviewer,
+                body,
+                path,
+                position,
+                expected_head,
+            )
+            if not detail:
+                continue
+            normalized = {**normalized, **detail}
+        candidates.append(normalized)
+    if len(candidates) != 1:
+        raise ReviewToolError(
+            "comment-write-uncertain",
+            "写后无法按 discussion、正文、作者、位置和 head 唯一确认评论；禁止直接重试。",
+            4,
+        )
+    return candidates[0]
+
+
+def default_write_receipt_dir() -> Path:
+    configured = os.getenv("MSDEVFLOW_REVIEW_RECEIPT_DIR")
+    if configured:
+        selected = Path(configured).expanduser()
+        if not selected.is_absolute():
+            raise ReviewToolError(
+                "receipt-directory-invalid",
+                "MSDEVFLOW_REVIEW_RECEIPT_DIR 必须是绝对路径或以 ~ 开头。",
+                3,
+            )
+        return selected
+    if os.name == "nt":
+        root = Path(os.getenv("LOCALAPPDATA") or (Path.home() / "AppData" / "Local"))
+    else:
+        root = Path(os.getenv("XDG_STATE_HOME") or (Path.home() / ".local" / "state"))
+    return root / "msdevflow" / "gitcode-review-write-receipts"
+
+
+def prepare_write_receipt_dir(directory: Path | None = None) -> Path:
+    selected = (directory or default_write_receipt_dir()).expanduser().resolve()
+    marker = selected / WRITE_RECEIPT_MARKER
+    if selected.exists():
+        if (
+            not selected.is_dir()
+            or selected.is_symlink()
+            or not marker.is_file()
+            or marker.is_symlink()
+            or marker.read_text(encoding="utf-8") != WRITE_RECEIPT_MARKER_CONTENT
+        ):
+            raise ReviewToolError(
+                "receipt-directory-invalid",
+                "拒绝使用：write receipt 路径不是 msdevflow 受管目录。",
+                3,
+            )
+    else:
+        selected.mkdir(parents=True, mode=0o700)
+        marker.write_text(WRITE_RECEIPT_MARKER_CONTENT, encoding="utf-8", newline="\n")
+    return selected
+
+
+def write_receipt_key(
+    target: PullRequestTarget,
+    reviewer: str,
+    expected_head: str,
+    kind: str,
+    body: str,
+    path: str | None,
+    position: int | None,
+) -> str:
+    payload = json.dumps({
+        "repository": target.repository,
+        "number": target.number,
+        "reviewer": reviewer,
+        "expected_head": expected_head,
+        "kind": kind,
+        "body_sha256": hashlib.sha256(body.encode("utf-8")).hexdigest(),
+        "path": path,
+        "position": position,
+    }, ensure_ascii=False, sort_keys=True, separators=(",", ":"))
+    return hashlib.sha256(payload.encode("utf-8")).hexdigest()
+
+
+def write_receipt_path(directory: Path, key: str) -> Path:
+    return directory / f"{key}.json"
+
+
+def load_write_receipt(path: Path) -> dict[str, Any] | None:
+    if not path.is_file() or path.is_symlink():
+        return None
+    try:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        raise ReviewToolError("write-receipt-invalid", "Review write receipt 已损坏，禁止再次写入。", 4)
+    if not isinstance(payload, dict) or payload.get("tool") != TOOL_NAME:
+        raise ReviewToolError("write-receipt-invalid", "Review write receipt 内容无效，禁止再次写入。", 4)
+    return payload
+
+
+def save_write_receipt(path: Path, payload: dict[str, Any]) -> None:
+    descriptor, temporary_name = tempfile.mkstemp(prefix=".receipt-", suffix=".json", dir=str(path.parent))
+    os.close(descriptor)
+    temporary = Path(temporary_name)
+    try:
+        write_json(temporary, payload)
+        temporary.replace(path)
+    finally:
+        temporary.unlink(missing_ok=True)
+
+
+def validate_write_receipt(
+    receipt: dict[str, Any],
+    target: PullRequestTarget,
+    reviewer: str,
+    expected_head: str,
+    kind: str,
+    body: str,
+    path: str | None,
+    position: int | None,
+) -> None:
+    expected = {
+        "tool": TOOL_NAME,
+        "version": TOOL_VERSION,
+        "repository": target.repository,
+        "number": target.number,
+        "reviewer": reviewer,
+        "expected_head": expected_head,
+        "kind": kind,
+        "body_sha256": hashlib.sha256(body.encode("utf-8")).hexdigest(),
+        "path": path,
+        "position": position,
+    }
+    if any(receipt.get(key) != value for key, value in expected.items()):
+        raise ReviewToolError("write-receipt-invalid", "Review write receipt 与当前写入事务不匹配。", 4)
+    if "body" in receipt or "token" in receipt:
+        raise ReviewToolError("write-receipt-invalid", "Review write receipt 包含禁止持久化的字段。", 4)
+
+
+def receipt_identity_set(receipt: dict[str, Any]) -> set[tuple[str, str]]:
+    result = set()
+    for item in receipt.get("preexisting", []):
+        if not isinstance(item, list) or len(item) != 2:
+            raise ReviewToolError("write-receipt-invalid", "Review write receipt 的评论集合无效。", 4)
+        result.add((str(item[0]), str(item[1])))
+    return result
+
+
+def verify_receipt_comment(
+    client: GitCodeClient,
+    target: PullRequestTarget,
+    comments: list[dict[str, Any]],
+    receipt: dict[str, Any],
+    reviewer: str,
+    body: str,
+    path: str | None,
+    position: int | None,
+    expected_head: str,
+) -> dict[str, Any]:
+    response_id = str(receipt.get("response_id") or "")
+    return select_written_comment(
+        client,
+        target,
+        comments,
+        receipt_identity_set(receipt),
+        reviewer,
+        body,
+        response_id,
+        path,
+        position,
+        expected_head,
+    )
+
+
+def write_body_file(body: str) -> Path:
+    descriptor, name = tempfile.mkstemp(prefix="msdevflow-gitcode-review-", suffix=".md")
+    os.close(descriptor)
+    path = Path(name)
+    path.write_bytes(body.encode("utf-8"))
+    return path
+
+
+def publish_review_comment(
+    client: GitCodeClient,
+    target: PullRequestTarget,
+    expected_head: str,
+    body: str,
+    *,
+    path: str | None = None,
+    position: int | None = None,
+    kind: str,
+) -> dict[str, Any]:
+    if (path is None) != (position is None):
+        raise ReviewToolError("inline-location-invalid", "--path 与 --position 必须同时提供或同时省略。", 2)
+    if path is not None and (not safe_remote_path(path) or not is_strict_int(position) or position <= 0):
+        raise ReviewToolError("inline-location-invalid", "Finding 的 path/position 无效。", 2)
+    reviewer, _ = ensure_review_write_target(client, target, expected_head)
+    before = read_comments(client, target)
+    if path is not None:
+        existing = find_existing_inline_comment(
+            client, target, before, reviewer, body, path, position, expected_head
+        )
+        if existing:
+            return {
+                "tool": TOOL_NAME,
+                "state": "finding-present",
+                "repository": target.repository,
+                "number": target.number,
+                "reviewer": reviewer,
+                "head_sha": expected_head,
+                "comment": existing,
+                "idempotent": True,
+                "remote_write": False,
+            }
+    receipt_dir = prepare_write_receipt_dir()
+    receipt_file = write_receipt_path(
+        receipt_dir,
+        write_receipt_key(target, reviewer, expected_head, kind, body, path, position),
+    )
+    receipt = load_write_receipt(receipt_file)
+    if receipt:
+        validate_write_receipt(
+            receipt, target, reviewer, expected_head, kind, body, path, position
+        )
+        if receipt.get("stage") == "verified":
+            written = verify_receipt_comment(
+                client, target, before, receipt, reviewer, body, path, position, expected_head
+            )
+            ensure_review_write_target(client, target, expected_head)
+            return {
+                "tool": TOOL_NAME,
+                "state": "finding-present" if kind == "finding" else "review-passed",
+                "repository": target.repository,
+                "number": target.number,
+                "reviewer": reviewer,
+                "head_sha": expected_head,
+                "comment": written,
+                "idempotent": True,
+                "remote_write": False,
+            }
+        if receipt.get("stage") in {"attempting", "write-returned"}:
+            written = verify_receipt_comment(
+                client, target, before, receipt, reviewer, body, path, position, expected_head
+            )
+            ensure_review_write_target(client, target, expected_head)
+            receipt.update({
+                "stage": "verified",
+                "comment_id": written.get("id"),
+                "discussion_id": written.get("discussion_id"),
+            })
+            save_write_receipt(receipt_file, receipt)
+            return {
+                "tool": TOOL_NAME,
+                "state": "finding-published" if kind == "finding" else "review-passed",
+                "repository": target.repository,
+                "number": target.number,
+                "reviewer": reviewer,
+                "head_sha": expected_head,
+                "comment": written,
+                "idempotent": True,
+                "remote_write": False,
+                "recovered_from_receipt": True,
+            }
+        raise ReviewToolError("write-receipt-invalid", "Review write receipt 阶段无效，禁止再次写入。", 4)
+    preexisting = {comment_identity(comment) for comment in before}
+    receipt = {
+        "tool": TOOL_NAME,
+        "version": TOOL_VERSION,
+        "stage": "attempting",
+        "repository": target.repository,
+        "number": target.number,
+        "reviewer": reviewer,
+        "expected_head": expected_head,
+        "kind": kind,
+        "body_sha256": hashlib.sha256(body.encode("utf-8")).hexdigest(),
+        "path": path,
+        "position": position,
+        "preexisting": [list(item) for item in sorted(preexisting)],
+        "response_id": "",
+    }
+    save_write_receipt(receipt_file, receipt)
+    temporary = write_body_file(body)
+    arguments = [
+        "pr", "comment", str(target.number), "--body-file", str(temporary),
+        "-R", target.repository, "--json",
+    ]
+    if path is not None:
+        arguments.extend(["--path", path, "--position", str(position)])
+    response: Any = None
+    write_failed = False
+    try:
+        try:
+            response = client.json(arguments, f"publish {kind}")
+        except GitCodeCommandError:
+            write_failed = True
+    finally:
+        temporary.unlink(missing_ok=True)
+    response_id = str(response.get("id") or "") if isinstance(response, dict) else ""
+    receipt.update({"stage": "write-returned", "response_id": response_id})
+    save_write_receipt(receipt_file, receipt)
+    written = select_written_comment(
+        client,
+        target,
+        read_comments(client, target),
+        preexisting,
+        reviewer,
+        body,
+        response_id,
+        path,
+        position,
+        expected_head,
+    )
+    final_payload = client.json(
+        ["pr", "view", str(target.number), "-R", target.repository, "--json"],
+        f"re-read PR {target.repository}#{target.number}",
+    )
+    final_pr = pull_request_summary(final_payload, target)
+    if final_pr["head_sha"] != expected_head:
+        raise ReviewToolError(
+            "head-changed-after-write",
+            "评论写入后 PR head 已变化；评论只对应旧 head，禁止报告当前 head 通过。",
+            4,
+        )
+    if kind == "finding" and (written["body"].count(SIGNATURE) != 1):
+        raise ReviewToolError("finding-signature-invalid", "远端 finding 尾签校验失败。", 4)
+    receipt.update({
+        "stage": "verified",
+        "comment_id": written.get("id"),
+        "discussion_id": written.get("discussion_id"),
+    })
+    save_write_receipt(receipt_file, receipt)
+    return {
+        "tool": TOOL_NAME,
+        "state": "finding-published" if kind == "finding" else "review-passed",
+        "repository": target.repository,
+        "number": target.number,
+        "reviewer": reviewer,
+        "head_sha": expected_head,
+        "comment": written,
+        "idempotent": False,
+        "remote_write": True,
+        "recovered_after_write_error": write_failed,
+    }
+
+
+def publish_finding(
+    client: GitCodeClient,
+    target: PullRequestTarget,
+    expected_head: str,
+    body_file: Path,
+    path: str | None = None,
+    position: int | None = None,
+) -> dict[str, Any]:
+    body = validate_finding_body(body_file)
+    return publish_review_comment(
+        client,
+        target,
+        expected_head,
+        body,
+        path=path,
+        position=position,
+        kind="finding",
+    )
+
+
+def publish_lgtm(
+    client: GitCodeClient,
+    target: PullRequestTarget,
+    expected_head: str,
+) -> dict[str, Any]:
+    return publish_review_comment(
+        client,
+        target,
+        expected_head,
+        "/lgtm",
+        kind="lgtm",
+    )
+
+
+def cleanup_snapshot(directory: Path) -> dict[str, Any]:
+    selected = directory.expanduser().resolve()
+    marker = selected / SNAPSHOT_MARKER
+    if (
+        not selected.is_dir()
+        or selected.is_symlink()
+        or not selected.name.startswith("review-")
+        or not marker.is_file()
+        or marker.is_symlink()
+        or marker.read_text(encoding="utf-8") != SNAPSHOT_MARKER_CONTENT
+    ):
+        raise ReviewToolError(
+            "cleanup-refused",
+            "拒绝删除：目录不是由 gitcode_review.py 创建的受管 snapshot。",
+            4,
+        )
+    shutil.rmtree(selected)
+    return {"tool": TOOL_NAME, "state": "snapshot-removed", "snapshot_dir": str(selected)}
+
+
+def add_gitcode_argument(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--gitcode-command", required=True, help="Fixed gitcode or gitcode-npm command")
+
+
+def add_pr_arguments(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--pr", required=True, help="PR URL, owner/repo#number, or numeric PR")
+    parser.add_argument("--repo", help="Canonical owner/repo for a numeric PR")
+    parser.add_argument("--expected-head", required=True, help="Confirmed 40-character PR head SHA")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="Deterministic GitCode code-review transport")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    snapshot = subparsers.add_parser("snapshot", help="Collect one or more read-only PR snapshots")
+    add_gitcode_argument(snapshot)
+    snapshot.add_argument("--repo", help="Canonical owner/repo for numeric PR targets")
+    snapshot.add_argument("prs", nargs="+", help="PR URLs, owner/repo#numbers, or numeric PRs")
+
+    context = subparsers.add_parser("context", help="Collect explicitly selected base/head files")
+    add_gitcode_argument(context)
+    add_pr_arguments(context)
+    context.add_argument("--side", choices=("base", "head", "both"), default="both")
+    context.add_argument("paths", nargs="+", help="Exact repository-relative paths")
+
+    finding = subparsers.add_parser("finding", help="Publish and verify one authorized finding")
+    add_gitcode_argument(finding)
+    add_pr_arguments(finding)
+    finding.add_argument("--body-file", required=True, type=Path)
+    finding.add_argument("--path")
+    finding.add_argument("--position", type=int)
+    finding.add_argument("--confirmed-current-head", action="store_true", required=True)
+
+    lgtm = subparsers.add_parser("lgtm", help="Publish and verify exact /lgtm")
+    add_gitcode_argument(lgtm)
+    add_pr_arguments(lgtm)
+    lgtm.add_argument("--confirmed-current-head", action="store_true", required=True)
+    lgtm.add_argument("--confirm-exact-lgtm", action="store_true", required=True)
+
+    cleanup = subparsers.add_parser("cleanup", help="Remove one managed snapshot")
+    cleanup.add_argument("snapshot_dir", type=Path)
+    cleanup.add_argument("--yes", action="store_true", required=True)
+    return parser
+
+
+def main() -> int:
+    parser = build_parser()
+    arguments = parser.parse_args()
+    try:
+        if arguments.command == "cleanup":
+            result = cleanup_snapshot(arguments.snapshot_dir)
+        else:
+            client = GitCodeClient(arguments.gitcode_command)
+            if arguments.command == "snapshot":
+                validate_capabilities(client)
+                targets = [parse_pr_target(value, arguments.repo) for value in arguments.prs]
+                result = create_snapshot(client, targets)
+            elif arguments.command == "context":
+                validate_capabilities(client)
+                target = parse_pr_target(arguments.pr, arguments.repo)
+                result = collect_additional_context(
+                    client,
+                    target,
+                    arguments.expected_head,
+                    arguments.side,
+                    arguments.paths,
+                )
+            elif arguments.command == "finding":
+                inline = arguments.path is not None or arguments.position is not None
+                validate_capabilities(client, write=True, inline=inline)
+                target = parse_pr_target(arguments.pr, arguments.repo)
+                result = publish_finding(
+                    client,
+                    target,
+                    arguments.expected_head,
+                    arguments.body_file,
+                    arguments.path,
+                    arguments.position,
+                )
+            else:
+                validate_capabilities(client, write=True)
+                target = parse_pr_target(arguments.pr, arguments.repo)
+                result = publish_lgtm(client, target, arguments.expected_head)
+        print(json.dumps(result, ensure_ascii=False, indent=2))
+        return 0
+    except ReviewToolError as error:
+        print(json.dumps({
+            "tool": TOOL_NAME,
+            "state": "blocked",
+            "error": error.error,
+            "message": str(error),
+        }, ensure_ascii=False, indent=2))
+        return error.exit_code
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())