msdevflow 0.8.5 → 0.8.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "msdevflow",
-  "version": "0.8.5",
+  "version": "0.8.6",
   "description": "Install the msdevflow GitCode skill and its runtime dependencies",
   "type": "module",
   "bin": {

package/skill/msd/README.md

@@ -421,5 +421,6 @@ typed CLI command
 - [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/gitcode_verify.py](scripts/gitcode_verify.py)：`pr`/`ci` 的 PR 回读、评论回读、CI 轮询和监控 helper。
+- [scripts/gitcode_issue.py](scripts/gitcode_issue.py)：`create-issue` 的 schema/标签/里程碑/模板批量只读探测和 Issue 回读 helper。
 
 测试文件（`scripts/test_openlibing_ci.py`、`scripts/test_gitcode_review.py`）只存在于 [源仓库](https://gitcode.com/msbuilder/msdevflow)，不随 npm 包或 skill 安装产物分发；安装目录中没有这两个文件是预期行为。

package/skill/msd/SKILL.md

@@ -127,6 +127,7 @@ discovered -> claimed -> verified -> analyzed -> designed
 - 创建 Issue/PR、评论、触发 CI、resolve 和 merge 前检查幂等状态；`create-issue` 在最终预览确认前禁止远端写入，每个 run 最多执行一次已确认的真实创建，禁止测试 Issue、POST 探测、失败重试或替代 Issue，只在写结果不确定时有界只读恢复；其他写结果不确定时也先回读。
 - `code-review` 的 GitCode 网络访问只能由 `scripts/gitcode_review.py` 执行；helper 输出不完整或能力不足即阻断，不回退现场命令、文本解析或 endpoint 探测。受管 snapshot 必须结束时清理，受管 write receipt 只用于固定 head 上评论写入的幂等恢复。
 - `pr`/`ci` 的 PR 回读、评论回读和 CI 轮询固定使用 `scripts/gitcode_verify.py`，不每轮现场生成 python/PowerShell 内联 JSON 解析；脚本报告 FAIL 或退出码非 0 时按验证失败阻断，先原地修复再回读。
+- `create-issue` 的 schema 探测、标签/里程碑分页和创建后回读固定使用 `scripts/gitcode_issue.py prepare` / `inspect`，不逐条现场调用只读 CLI 命令；批量只读探测走单次 `python` 调用，避免每条命令单独触发权限确认。
 - 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/command-capabilities.md

@@ -35,7 +35,7 @@ GitCode CLI 版本和命令集合可能不同。工作流必须探测能力，
 <gitcode-command> schema "pr merge"
 ```
 
-若无 schema，对应使用 `<command> --help`。只探测当前 action 所需命令；`create-issue` 至少需要 `milestone list` 的显式 repo、JSON 和分页，`label list` 的显式 repo、JSON 和完整分页，`issue create` 的显式 repo、title、body-file、issue-type、JSON 和 dry-run，`issue view` 的 JSON 回读能力，以及 `issue edit` 的显式 repo、label、title、body-file、milestone number、yes 和 JSON。平台 `issue_type` 不在 typed view 输出时须用已验证的同 CLI 单 Issue GET JSON 回读；类型枚举和名称/ID 映射只采用当前官方文档、CLI 实现或仓库类型配置支持的只读路径，不猜 endpoint。`--issue-type` 的 enterprise 标注不是目标仓库支持证据；类型无法明确设置或回读时在创建前阻断，不能省略参数创建默认 Bug。标签完整分页证明必需标签缺失时也必须阻断，不降级为 `none`。官方 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 文本直接放进命令行参数。
+若无 schema，对应使用 `<command> --help`。只探测当前 action 所需命令；`create-issue` 至少需要 `milestone list` 的显式 repo、JSON 和分页，`label list` 的显式 repo、JSON 和完整分页，`issue create` 的显式 repo、title、body-file、issue-type、JSON 和 dry-run，`issue view` 的 JSON 回读能力，以及 `issue edit` 的显式 repo、label、title、body-file、milestone number、yes 和 JSON。这些只读探测和回读固定通过 `scripts/gitcode_issue.py prepare` / `inspect` 一次完成，不逐条现场调用 schema 和分页命令，避免每条命令单独触发权限确认。平台 `issue_type` 不在 typed view 输出时须用已验证的同 CLI 单 Issue GET JSON 回读；类型枚举和名称/ID 映射只采用当前官方文档、CLI 实现或仓库类型配置支持的只读路径，不猜 endpoint。`--issue-type` 的 enterprise 标注不是目标仓库支持证据；类型无法明确设置或回读时在创建前阻断，不能省略参数创建默认 Bug。标签完整分页证明必需标签缺失时也必须阻断，不降级为 `none`。官方 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 试探。
 

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

@@ -135,17 +135,22 @@ Duplicate search: not performed by design
 
 本 Skill 固定使用 setup 已验收的官方 npm GitCode CLI typed command，不通过 Issue collection API 创建。能力验证只能使用 `schema`、`--help` 和 typed command 自带的 `--dry-run`；`api .../issues --method POST` 没有 dry-run 语义，禁止用于创建、试错或验证。
 
-使用前只读探测：
+使用前只读探测固定使用 Skill 随附脚本一次完成，不逐条现场调用 schema 和分页命令：
 
 ```bash
-<gitcode-command> schema "label list"
-<gitcode-command> schema "milestone list"
-<gitcode-command> schema "issue create"
-<gitcode-command> schema "issue view"
-<gitcode-command> schema "issue edit"
+MSDEVFLOW_GITCODE_COMMAND=<gitcode-command> python <skill-scripts-dir>/gitcode_issue.py prepare <canonical> --template-ref <canonical-remote>/<default-branch>
 ```
 
-必须具备 `issue create --issue-type`、完整的标签分页、同 Issue 标签/里程碑编辑和平台类型 JSON 回读能力；具体类型的适用性仍按“平台类型”核验，不能只看 flag 是否存在。
+该命令一次返回：`issue create`/`issue view`/`issue edit`/`label list`/`milestone list` 的 schema flags、全部分页标签（含精确数量，避免把第一页截断误判为“标签不存在”）、开放里程碑列表，以及 `.gitcode` 模板树。缺少 `issue create --issue-type`、完整标签分页或同 Issue 编辑能力时在创建前阻断；具体类型的适用性仍按“平台类型”核验，不能只看 flag 是否存在。
+
+创建后的权威回读同样固定使用脚本一次完成：
+
+```bash
+MSDEVFLOW_GITCODE_COMMAND=<gitcode-command> python <skill-scripts-dir>/gitcode_issue.py inspect <canonical> <issue-number> \
+  --expect-type <platform-issue-type> --expect-label <required-label> --expect-milestone <milestone-number> --expect-title "<exact-title>"
+```
+
+脚本用 typed `issue view` 加单 Issue GET API 读取平台类型、标签、里程碑和正文，逐项输出 PASS/FAIL，退出码非 0 即回读失败。命令本身不创建、编辑或删除任何远端对象；只有脚本报告全部 PASS 才能继续。
 
 将最终正文写入唯一的系统临时文件，编码固定为 UTF-8 无 BOM。官方 npm GitCode CLI 的 `issue create --title` 是本 Skill 已验收的中文标题通道；Windows `.cmd` wrapper 也直接使用 typed command，不得为中文标题切换到 API POST。最终预览前必须用固定仓库、带前缀标题、正文文件和已验证的平台类型执行本地 dry-run：
 
@@ -175,7 +180,7 @@ dry-run 不得产生新 Issue number/URL；否则视为能力异常并停止。
 
 ## 回读、恢复与完成
 
-创建返回 Issue number/URL 后立即回读目标与类型；仅在该门禁通过后应用已确认元数据，随后再次用权威 JSON 完整验证：
+创建返回 Issue number/URL 后，先用 `gitcode_issue.py inspect` 回读目标与类型；仅在该门禁通过后应用已确认元数据，随后再次运行带 `--expect-*` 的 `inspect` 完整验证：
 
 - repository 和 Issue number/URL；
 - state 为 open；

package/skill/msd/scripts/gitcode_issue.py

@@ -0,0 +1,235 @@
+#!/usr/bin/env python3
+"""Fixed read-only helpers for msd create-issue.
+
+Batches the read-only probes that create-issue otherwise issues as dozens of
+separate CLI calls (schema, full label/milestone pagination, Issue readback),
+so the workflow can invoke one `python` script instead of many gitcode
+commands. Read-only: never creates, edits or deletes anything.
+
+Subcommands:
+  prepare  schema flags + all label pages + all milestone pages + template tree
+  inspect  read back one Issue via typed view and authoritative GET API
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+if os.name == "nt":
+    sys.stdout.reconfigure(encoding="utf-8")
+    sys.stderr.reconfigure(encoding="utf-8")
+
+DEFAULT_PAGE_SIZE = 100
+GITCODE_COMMAND = os.environ.get("MSDEVFLOW_GITCODE_COMMAND", "gitcode")
+
+
+def resolve_command() -> str:
+    selected = shutil.which(GITCODE_COMMAND)
+    if not selected:
+        print(f"gitcode command not found: {GITCODE_COMMAND}", file=sys.stderr)
+        raise SystemExit(3)
+    return selected
+
+
+def invocation(arguments: list[str]) -> list[str]:
+    exe = resolve_command()
+    if os.name == "nt" and Path(exe).suffix.lower() in {".cmd", ".bat"}:
+        # .cmd wrappers cannot be exec'd directly by subprocess.
+        return [
+            "powershell.exe", "-NoProfile", "-Command",
+            "& { $exe = $args[0]; $rest = @($args | Select-Object -Skip 1); & $exe @rest; exit $LASTEXITCODE }",
+            exe, *arguments,
+        ]
+    return [exe, *arguments]
+
+
+def run(args: list[str], allow_failure: bool = False) -> str:
+    result = subprocess.run(
+        invocation(args),
+        capture_output=True,
+        text=True,
+        encoding="utf-8",
+        timeout=180,
+    )
+    if result.returncode != 0:
+        if allow_failure:
+            return ""
+        print(f"{GITCODE_COMMAND} {' '.join(args)} failed: exit {result.returncode}", file=sys.stderr)
+        print(result.stderr[-2000:], file=sys.stderr)
+        raise SystemExit(3)
+    return result.stdout
+
+
+def run_json(args: list[str], allow_failure: bool = False):
+    text = run(args, allow_failure=allow_failure)
+    if not text.strip():
+        return None
+    return json.loads(text)
+
+
+def json_list(value) -> list:
+    if isinstance(value, list):
+        return value
+    if isinstance(value, dict):
+        for key in ("items", "data", "labels", "milestones", "comments"):
+            if isinstance(value.get(key), list):
+                return value[key]
+    return []
+
+
+def page_all(kind: str, repo: str, page_size: int, max_pages: int) -> list:
+    """Read every page of a list command. Stops on empty page, short page
+    (< page_size), repeated page, or max_pages."""
+    seen_page_signatures: set[str] = set()
+    items: list = []
+    for page in range(1, max_pages + 1):
+        payload = run_json(
+            [
+                kind, "list", "-R", repo,
+                "--limit", str(page_size),
+                "--per-page", str(page_size),
+                "--page", str(page),
+                "--json",
+            ]
+        )
+        batch = json_list(payload)
+        signature = json.dumps(sorted(str(item.get("id") or item.get("number")) for item in batch))
+        if not batch:
+            break
+        if signature in seen_page_signatures:
+            print(f"warning: {kind} list page {page} repeats page {page - 1}; stopping", file=sys.stderr)
+            break
+        seen_page_signatures.add(signature)
+        items.extend(batch)
+        if len(batch) < page_size:
+            break
+    return items
+
+
+def cmd_prepare(args: argparse.Namespace) -> int:
+    report: dict = {"repository": args.repo}
+
+    # schema flags for the commands create-issue needs
+    schemas: dict[str, list[str]] = {}
+    for name in ("issue create", "issue view", "issue edit", "label list", "milestone list"):
+        payload = run_json(["schema", name], allow_failure=True)
+        flags = []
+        if isinstance(payload, dict) and isinstance(payload.get("flags"), list):
+            flags = [flag.get("name") for flag in payload["flags"] if isinstance(flag, dict)]
+        schemas[name] = flags
+    report["schemas"] = schemas
+
+    labels = page_all("label", args.repo, args.page_size, args.max_pages)
+    report["labels"] = [item.get("name") for item in labels]
+    report["label_count"] = len(labels)
+
+    milestones = page_all("milestone", args.repo, args.page_size, args.max_pages)
+    report["open_milestones"] = [
+        {
+            "number": item.get("number") or item.get("id"),
+            "title": item.get("title"),
+            "state": item.get("state"),
+            "due_on": item.get("due_on") or item.get("due_date") or "",
+        }
+        for item in milestones
+        if str(item.get("state", "")).lower() in ("active", "open", "")
+    ]
+    report["milestone_count"] = len(milestones)
+
+    if args.template_ref:
+        result = subprocess.run(
+            ["git", "ls-tree", "-r", "--name-only", args.template_ref, "--", ".gitcode"],
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            timeout=120,
+        )
+        report["gitcode_tree"] = (
+            [line for line in result.stdout.splitlines() if line.strip()]
+            if result.returncode == 0
+            else None
+        )
+    else:
+        report["gitcode_tree"] = None
+
+    print(json.dumps(report, ensure_ascii=False, indent=2))
+    return 0
+
+
+def cmd_inspect(args: argparse.Namespace) -> int:
+    view = run_json(["issue", "view", str(args.number), "-R", args.repo, "--json"]) or {}
+    api = run_json(["api", f"repos/{args.repo}/issues/{args.number}"]) or {}
+
+    labels = [l.get("name") if isinstance(l, dict) else l for l in (api.get("labels") or view.get("labels") or [])]
+    type_detail = api.get("issue_type_detail") or {}
+    platform_type = api.get("issue_type") or type_detail.get("title") or ""
+    milestone = api.get("milestone") or view.get("milestone") or {}
+    body = view.get("body") or api.get("body") or ""
+    title = view.get("title") or api.get("title") or ""
+
+    report = {
+        "number": view.get("number") or api.get("number"),
+        "state": view.get("state") or api.get("state"),
+        "title": title,
+        "platform_issue_type": platform_type,
+        "labels": labels,
+        "milestone_number": milestone.get("number"),
+        "milestone_title": milestone.get("title"),
+        "signature_count": body.count("——msdevflow"),
+        "body": body,
+    }
+    print(json.dumps(report, ensure_ascii=False, indent=2))
+
+    ok = True
+
+    def check(condition: bool, label: str) -> None:
+        nonlocal ok
+        ok = ok and condition
+        print(f"{'PASS' if condition else 'FAIL'} {label}")
+
+    check(bool(platform_type), f"platform type present ({platform_type or 'empty'})")
+    check(len(labels) == len(set(labels)), "labels unique")
+    check(report["signature_count"] == 1, f"signature exactly once ({report['signature_count']})")
+    if args.expect_type:
+        check(platform_type == args.expect_type, f"platform type == {args.expect_type}")
+    if args.expect_label:
+        for name in args.expect_label:
+            check(name in labels, f"label present: {name}")
+    if args.expect_milestone is not None:
+        check(milestone.get("number") == args.expect_milestone, f"milestone number == {args.expect_milestone}")
+    if args.expect_title:
+        check(title == args.expect_title, "title verbatim")
+    return 0 if ok else 3
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p = sub.add_parser("prepare", help="batch schema + labels + milestones + template tree")
+    p.add_argument("repo")
+    p.add_argument("--page-size", type=int, default=DEFAULT_PAGE_SIZE)
+    p.add_argument("--max-pages", type=int, default=50)
+    p.add_argument("--template-ref", help="git ref to list .gitcode template tree from, e.g. upstream/HEAD")
+
+    p = sub.add_parser("inspect", help="read back one Issue via view + GET API")
+    p.add_argument("repo")
+    p.add_argument("number", type=int)
+    p.add_argument("--expect-type", help="expected platform issue_type")
+    p.add_argument("--expect-label", action="append", default=[], help="expected label (repeatable)")
+    p.add_argument("--expect-milestone", type=int, help="expected milestone number")
+    p.add_argument("--expect-title", help="expected exact title")
+
+    args = parser.parse_args()
+    if args.command == "prepare":
+        return cmd_prepare(args)
+    return cmd_inspect(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())