npm - @prismer/runtime - Versions diffs - 2.0.7 → 2.2.55 - Mend

@prismer/runtime 2.0.7 → 2.2.55

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (291) hide show

package/apc/skills/doc-sync/SKILL.md ADDED Viewed

@@ -0,0 +1,168 @@
+---
+name: doc-sync
+description: Before merge, mechanize Documentation-First — derive the code delta from git diff, then verify required docs are in sync (CHANGELOG, docs/api, CLAUDE.md/ROADMAP). Any SDK-package change must carry a matching CHANGELOG entry + aligned version files. A change that skipped a required doc is flagged as a gap; a fully-synced change passes.
+license: MIT
+scope: coding
+compatibility:
+  - claude-code
+allowed-tools:
+  - Bash
+metadata:
+  category: documentation
+---
+# doc-sync
+合入前把 **Documentation-First** 机械化：从 `git diff` 派生**代码 delta**，逐项核对**该 delta 触发的文档义务**是否已同步——CHANGELOG / `docs/api/<domain>` / CLAUDE.md / ROADMAP；**SDK 包改动必须带对应 CHANGELOG + 版本文件对齐**（`apc/05` §2 S12 · `apc/12` doc-sync 行）。
+**什么时候用**：一个改动进合入门前，需要机械核对"该改的文档是不是都改了"，把"改了代码忘了 changelog / 忘了 api doc"这类漏挡在合入前。
+铁律：**代码 delta 来自真 `git diff`，不是假设**。义务表的每条义务要写清"是 delta 的哪一部分触发的"——义务不是凭空列的清单，是 delta 推出来的。
+## 工具契约（签名以此为准，先核后用）
+| 命令 | 作用 | 备注 |
+| --- | --- | --- |
+| `git diff --name-only [<base>..<head>]` | 派生 delta：改了哪些文件 | 不带 range = working tree；分类的输入 |
+| `git diff [-- <paths>]` | 看具体改动内容（判 CHANGELOG 是否含本次条目） | — |
+| `rg <stale-ref> docs/ CLAUDE.md` | 猎 stale 引用（doc 里引了已删/改名的东西） | 出 path:line |
+| `npx tsx scripts/apc-doc-sync.ts <taskId>` | 机械门：改了 docs/sdk 但 diff 里不提 taskId → 非零 | exit 0 ok · 1 无 doc diff 或未提及 taskId · 2 用法错 |
+| `sdk/build/version.sh --scope <s> <version>` | 版本文件对齐（14 文件同步） | **写操作**，只在真要 bump 时跑；核对用只读比对 |
+| `cloud task verify-criterion <task-id> <criterion-id> --outcome <passed\|failed\|n/a\|waived>` | 上报 criterion | `--outcome` 恰好四值 |
+- `apc-doc-sync.ts` 是**机械门**：它只校验"改动的 docs/sdk diff 里提到了 taskId"，是义务的**必要非充分**条件——它挡不住"改了 sdk 但没改 CHANGELOG"这种**缺文件**的漏，那要靠下面的义务表逐项核。两者叠加用。
+## 义务表（delta → 必须同步的文档）
+按 `git diff --name-only` 的命中，逐类推导文档义务：
+| delta 命中 | 触发的文档义务 | 怎么核（satisfied 判据） |
+| --- | --- | --- |
+| `sdk/<pkg>/src/**`（SDK 包源码改） | 该包 `sdk/<pkg>/CHANGELOG.md` 有本次条目 + 14 版本文件对齐 | changed 文件集里**含**该包 CHANGELOG；`version.sh` 只读比对版本一致 |
+| 新增/改 endpoint（`src/im/api/**` / 路由） | `docs/api/<domain>.md` 更新 + `Last updated` 日期 | changed 含对应 domain doc |
+| `prisma/schema*.prisma` / `src/im/sql/NNN_*.sql`（schema/migration） | `docs/ARCHITECTURE.md` / 相关 design doc + migration 编号连续 | changed 含架构/design doc |
+| 架构级行为变化（层/flag/大重构） | `CLAUDE.md` / `docs/ROADMAP.md` / `docs/TODO.md` | changed 含对应文件 |
+**核心不变量（S12 唯一有意义的判据）**：**改了 SDK 包源码却没改该包 CHANGELOG = gap（缺义务）**。这正是 `apc/12` 的正控/负控——缺 CHANGELOG 必须判缺，同步完整必须放行。
+## Procedure
+### 1. 派生 delta（真 git diff，不假设）
+```bash
+git diff --name-only > /tmp/delta.txt      # 或 <base>..<head>
+```
+把 changed 文件分类：`sdk pkg src / endpoint / schema-migration / docs / other`。分类是义务推导的输入。
+### 2. 逐类推导义务 + 核 satisfied
+对每一类命中，按义务表列一行 `{ obligation, requiredBecause, satisfied }`：
+```bash
+# 例：SDK 包改了没改 CHANGELOG？
+# 找 delta 里的 sdk 包源码目录
+rg '^sdk/([^/]+/[^/]+)/src/' /tmp/delta.txt -or '$1' | sort -u   # 改了哪些包
+# 对每个包，看 CHANGELOG 在不在 changed 集里：
+grep -q 'sdk/<pkg>/CHANGELOG.md' /tmp/delta.txt && echo "CHANGELOG ✓" || echo "CHANGELOG ✗ GAP"
+```
+`satisfied` 判据是**副作用**（该 doc 文件在 changed 集里 / 版本号真对齐），不是"我觉得应该改了"。
+### 3. 跑机械门（叠加，非替代）
+```bash
+npx tsx scripts/apc-doc-sync.ts "$PRISMER_TASK_ID"; echo "gate exit=$?"
+```
+exit 1 = 改了 docs/sdk 但 diff 不提 taskId（可追溯性缺失）。机械门过 ≠ 义务全满——义务表的缺文件项要另判。
+### 4. 汇总 gap + 上报
+- **有 gap**（任一义务 unsatisfied）→ `--outcome failed`，列出缺哪些。
+- **无 gap**（义务全满 + 机械门 0）→ `--outcome passed`。
+```bash
+cloud task verify-criterion "$PRISMER_TASK_ID" "<criterion-id>" --outcome failed \
+  --note "gap: sdk/prismer-cloud/typescript/src changed but CHANGELOG not updated"
+```
+## 输出契约（机器判据按这个复算，别自由发挥格式）
+本 skill 的验收判据不是「报告里出现了 changelog 这个词」，而是**判据自己从 delta 重新推导义务集和 gap 集，再跟你报的比对**（`structured-criteria.ts` 的 `doc-sync-obligations`），并且**把每个声明的 delta 文件读回磁盘**。所以报告必须带下面三类**可机器解析的行**：
+```
+DELTA: <path> | class: <sdk-package-source|endpoint-doc|schema-migration|other>
+OBLIGATION: <doc path> | required-because: <理由，指回 delta 的哪一部分> | satisfied: yes|no
+GAP: <doc path>
+```
+判据会判红的情况（任一）：
+- 声明的 delta 与本次真实 diff **不等**（漏报 / 多报），或声明的文件**在磁盘上不存在**；
+- 义务集与判据从 delta 重算的结果**不等**——**漏一条**（比如不提该包 CHANGELOG）跟**编一条**（delta 推不出来的义务）都判红；
+- `satisfied` 与事实不符（**义务满足 ⟺ 该 doc 文件本身在 delta 里**）；
+- `required-because` 空或过短（去空白 <20 字符）——「凭空清单」正是本 skill 要挡的；
+- `GAP` 集与重算出的 unsatisfied 集**不等**（漏报 gap / 虚报 gap 都红）。
+写 `GAP: <path>` 是**结构化断言**，不是修辞——判据只认这些行，不认 "❌"、"missing" 之类的措辞。
+## 产出（副作用 oracle，报告里必须给）
+1. **delta 分类**：`git diff --name-only` 的真实命中，按类归组。
+2. **义务表**：每行 `{obligation, requiredBecause, satisfied}`——`requiredBecause` 指回 delta 的哪一部分。
+3. **gap 列表**：required 但 unsatisfied 的义务。
+4.（挂 task 时）**criterion 上报行** + 机械门退出码。
+**两个承重 oracle**：
+- **正控**：改了 SDK 包源码但**没改** CHANGELOG → **必须判 gap**（`--outcome failed`）。
+- **负控**：文档全同步的改动（CHANGELOG/api doc 都改了）→ **必须放行**（`--outcome passed`），不虚报缺失。
+**不许**：把义务当凭空清单列而不指回 delta；只跑机械门就宣称"文档已同步"（机械门挡不住缺文件）；断言聊天文本而非 changed-file 集/退出码。
+## 诚实边界
+- 本 skill 核的是**"该改的文档改了没"（存在性 + 可追溯性）**，**不核文档内容是否正确**——CHANGELOG 写了一行但内容是错的，机械门和义务表都放行。内容正确性靠人/评审兜。
+- 义务表覆盖的是可从 `git diff --name-only` 机械推导的类别；"架构级行为变化"这类需要语义判断的义务，本 skill 只能提示"delta 涉及 X，考虑是否要更 CLAUDE.md/ROADMAP"，不能机械断定必须改——这一维标注为需人工确认，不硬判 gap。
+- `apc-doc-sync.ts` 机械门只看 taskId 出现性，是可追溯性的下限，不是文档完整性的证明。
+## PKF 双投影（研发回环 · doc07 §B2 写入点③）
+**产出时机**：义务全满、SPEC/docs/CHANGELOG 的 **markdown 真源落 git 之后**，把同内容**投影成一张 PKF 记忆页**（pageType=`reference`）——markdown 真源仍是 git diff/review/grep 的工程权威，PKF 是补了 typed link 的**可召回投影**。投影必带 typed link（`derived-from`/`supports`/`contradicts`），否则投影没有增量、白写（doc07 §B1）。这一步是义务核对**之后**的投影，不改 delta 派生 / 义务核对 / 机械门任何一步。
+**语法照 `pkf-writing` skill**——本 skill 不再内嵌语法骨架（frontmatter / typed link / 数据块写法都在那边）。写入面**不新造**：code agent 走 `prismer memory write`（SS-14 §4.3 appendix；hermes 侧是 native `memory_write`）。
+**声明**（doc10 §2.5 格式，报告末尾一行）：
+```
+PKF: prismer://workspace/<ws>/memory/<path>
+```
+写入面不可达时如实声明 `PKF: none — 写入面不可达（<哪一条>）`，**绝不允许**为了满足规则而假装写了。
+**回读**：声明后必须回读该页（`pkf_read` / memory read），确认**真实存在、正文非空**且与 git 真源同内容；typed link 的 `prismer://` 目标必须**真实存在**，无对应页就删该 link 行、宁缺勿造伪目标；**先 git 落地再投影**，不倒过来。写入自动挂 INDEX 反孤儿锚（SS-14 §4.2），优先 edit 既有投影页而非 dump 新叶（PLACE 治理照走）。
+<!-- APC-ACK:v1 -->
+## 调用回执（APC 平台方运营纪律 · 自动注入，勿手改）
+执行本 skill 的**第一步**，先落一条调用回执：
+```bash
+cloud skill ack doc-sync --task "$PRISMER_TASK_ID"
+```
+**按退出码分流**（这条命令的退出码是承重信息，禁止用 `||` 兜底、`; true`、
+`set +e` 或重定向把它抹掉）：
+| exit | 含义 | 你要做的 |
+| --- | --- | --- |
+| `0` | 回执已落库（`im_task_logs.action='skill_ack'`） | 继续执行本 skill |
+| `3` | **无 task 上下文**——本次运行没有 task，产不出回执 | 继续执行本 skill；但本次运行**没有回执**，任何报告里都不得声称已 ack |
+| `4` | 你不是该 task 的 assignee，服务端拒绝 | 停下并上报：回执只能由执行该 task 的 agent 产生 |
+| `1` | 其它失败（网络 / 服务端） | 重试一次；仍失败则继续执行，并在结果里显式标注「回执缺失」 |
+回执只证明本 skill **被调度**，不证明**执行正确**——效果证明由本 skill 自己的
+acceptanceCriteria 副作用断言承担（apc/04 §2 层 1 诚实标注）。
+<!-- /APC-ACK:v1 -->

package/apc/skills/doc-sync/skill.json ADDED Viewed

@@ -0,0 +1,81 @@
+{
+  "schemaVersion": 1,
+  "slug": "doc-sync",
+  "name": "Doc Sync",
+  "description": "Before a change merges, mechanize Documentation-First: derive the code delta from git diff, then verify that the required docs are in sync — CHANGELOG, docs/api/<domain>, CLAUDE.md/ROADMAP. Any SDK-package change must carry a matching CHANGELOG entry (+ version files aligned). A change that touched an SDK package but skipped its CHANGELOG must be flagged as a gap; a fully-synced change is released.",
+  "category": "documentation",
+  "version": "1.1.0",
+  "license": "MIT",
+  "compatibility": ["claude-code"],
+  "runtime": {
+    "kind": "text-workflow",
+    "requires": {
+      "env": [],
+      "bins": ["git", "rg"],
+      "capabilities": ["prismer.task.verify-criterion"]
+    }
+  },
+  "sampleTasks": [
+    {
+      "title": "Verify doc sync for a change that edits an SDK package but skips its CHANGELOG",
+      "prompt": "Run the doc-sync skill on this change delta. Mechanize Documentation-First: derive the code delta, classify it, then check each documentation obligation the delta triggers, and flag any required-but-missing doc as a GAP. --- CHANGE DELTA (the `git diff --name-only` for this change is exactly these two files):\n```\nsdk/cloud/src/commands/code-grep.ts\ndocs/api/im-tasks.md\n```\nNote what is NOT in the delta: there is NO `sdk/cloud/CHANGELOG.md` entry. --- Your steps: (1) treat the two lines above as the real `git diff --name-only` output and classify each file (sdk-package source / endpoint doc / schema / other). (2) Derive the documentation obligations THIS delta triggers, and for each name WHY it is required (which part of the delta triggered it): a change to `sdk/<org>/<pkg>/src/**` requires a matching CHANGELOG entry in that package's `CHANGELOG.md` PLUS aligned version files (per CLAUDE.md 'SDK CHANGELOG' rule); a `docs/api/<domain>.md` change carries its own doc obligation. (3) Check each obligation's satisfied? state against the changed-file set (an obligation is satisfied iff its doc file is ITSELF in the delta). (4) Produce the gap list. THE LOAD-BEARING ORACLE: the SDK package `sdk/cloud` had its source (code-grep.ts) changed but its `CHANGELOG.md` was NOT updated → you MUST flag this as a GAP, not pass it.\n\n--- YOUR REPORT MUST USE THIS MACHINE-CHECKED OUTPUT CONTRACT. The checker RECOMPUTES the obligation set and the gap set from the delta and compares them with yours, and it re-reads every declared delta file off disk — so keyword-shaped prose is worth nothing and an invented file is caught.\n\nOne line per changed file (both must appear, and only these two):\n```\nDELTA: sdk/cloud/src/commands/code-grep.ts | class: sdk-package-source\nDELTA: docs/api/im-tasks.md | class: endpoint-doc\n```\n\nOne line per obligation — `required-because` must be real prose (≥20 chars) tracing back to the delta, and `satisfied` must be yes only when that doc file is itself in the delta:\n```\nOBLIGATION: <doc path> | required-because: <why, traced to the delta> | satisfied: yes|no\n```\n\nOne line per gap — exactly the unsatisfied obligations, no more, no fewer:\n```\nGAP: <doc path>\n```\n\nThen your prose summary (classification, obligation table, gap list) as usual.",
+      "expectedArtifacts": [
+        "`DELTA:` lines classifying every changed file of the given diff (and no invented ones)",
+        "`OBLIGATION:` lines covering exactly the obligations derivable from that delta, each with a required-because tracing to the delta and a satisfied flag consistent with the changed-file set",
+        "`GAP:` lines equal to the unsatisfied obligation set — the missing sdk/cloud CHANGELOG must be among them",
+        "prose summary of the classified delta, the obligation table and the gap list"
+      ],
+      "acceptanceCriteria": [
+        {
+          "label": "delta / obligations / gaps recomputed from the real diff and matched — declared delta files re-read off disk, obligation set and gap set recomputed by the checker (missing, invented or mis-flagged obligations all fail)",
+          "type": "structured",
+          "checker": "doc-sync-obligations",
+          "args": {
+            "deltaFiles": ["sdk/cloud/src/commands/code-grep.ts", "docs/api/im-tasks.md"],
+            "minReasonChars": 20
+          },
+          "match": "<structured:doc-sync-obligations>",
+          "required": true
+        },
+        {
+          "label": "delta derived from git diff --name-only and classified",
+          "match": "(git\\s+diff|--name-only|\\bdelta\\b|变更文件|改动文件|classif|分类|归类)",
+          "type": "regex",
+          "flags": "is",
+          "required": true
+        },
+        {
+          "label": "names the real changed SDK package / file",
+          "match": "(sdk/cloud|typescript/src/commands|code-grep\\.ts|prismer-cloud/typescript)",
+          "type": "regex",
+          "flags": "is",
+          "required": true
+        },
+        {
+          "label": "obligation names WHY it is required (traceable to the delta)",
+          "match": "(because|required[- ]?because|triggered\\s+by|触发|obligation|义务|satisfied|因为|由于|所以)",
+          "type": "regex",
+          "flags": "is",
+          "required": true
+        }
+      ]
+    }
+  ],
+  "security": {
+    "dataAccess": ["local-filesystem", "workspace-tasks"],
+    "humanApprovalRequiredFor": []
+  },
+  "provenance": {
+    "sourceKind": "inline-spec",
+    "sourceRefs": [
+      "docs/apc/12-skill-acceptance-tasks.md",
+      "docs/apc/05-devchain-gaps-and-skills.md",
+      "scripts/apc-doc-sync.ts",
+      "sdk/build/version.sh",
+      "sdk/cloud/src/commands/task.ts",
+      "sdk/prismer/src/bundle/structured-criteria.ts"
+    ],
+    "authoredBy": "prismer-platform",
+    "authoredAt": "2026-07-24T00:00:00Z"
+  }
+}

package/apc/skills/env-doctor/SKILL.md ADDED Viewed

@@ -0,0 +1,194 @@
+---
+name: env-doctor
+description: Diagnose the local dev machine before any APC loop step — run apc env doctor, classify each failure into a fault domain, apc env up to auto-fix what is safe, then fingerprint. Keeps env faults out of SUT verdicts.
+license: MIT
+scope: common
+compatibility:
+  - claude-code
+  - prismer-sdk
+allowed-tools:
+  - Bash
+metadata:
+  category: environment
+---
+# env-doctor
+诊断本机开发环境，把**环境故障**与**被测代码红（SUT red）**彻底分域——这是 APC 一切循环步骤的地基（`apc/06` 环境脚手架 · `apc/00` §3 不变量 5）。
+**什么时候用**：任何 APC 循环步骤开工前；或 test-runner 报出 `env_blocked`、dispatch 失败、诊断"为什么这台机器跑不起来"时。
+铁律：`apc env doctor` 判红是**环境红**，不是产品 bug。你的产出是一份逐项 pass/fail 的诊断 + 每个红项的**故障域分类** + 可自动化项已拉起的证据。绝不把环境红说成"代码坏了"。
+## 工具契约（先记死，签名以此为准）
+> **命令形态（承重，别猜）**：`apc` 不在 PATH——它是 `package.json` 的 npm script（`tsx sdk/apc/bin/apc.ts`）。
+> 在 agent 的 cwd（仓库根）里，**一律用 `npx tsx sdk/apc/bin/apc.ts <sub>` 直接跑**（stdout 是纯 JSON，不被 npm banner 污染）。下表用 `apc` 作简写，实跑请替换成 `npx tsx sdk/apc/bin/apc.ts`。
+| 命令 | 作用 | stdout | 退出码 |
+| --- | --- | --- | --- |
+| `apc env doctor` | 只读跑完 env-manifest 四段，逐项 pass/fail + fix-hint | **结构化 JSON**（消费者契约） | `0` 全绿 · `78` env_blocked（存在环境红） |
+| `apc env up --safe [--dry-run] [--only=a,b]` | 幂等拉起**可自动化的轻量项**；`--safe` 下 heavy 步（colima / dev-stack / kind / npm ci / prisma / migrations）**不自动跑**，只归 `manual[]` 出 fix-hint | JSON 报告 | `0` ok · `1` 有步骤 failed |
+| `apc env fingerprint` | 环境指纹（机器等价性证明） | JSON 指纹 | `0` |
+- **`apc env doctor` 的 exit 78 是承重信息**：它表示"存在环境红"，不是崩溃。一项探针崩了也不塌全轮——doctor 逐项 `try/catch`，其它项照常给结论。
+- **stdout 是纯 JSON**，人读摘要走 stderr。解析结果一律从 stdout 的 JSON 取，**不要**从人读摘要正则抠。
+- **dispatch 语境铁律（apc/11 §0.17 缺口1）**：你是被一次 dispatch 拉起跑诊断的，**不是人坐在终端做环境自举**。**绝不跑不带 `--safe` 的 `apc env up`**——它的 docker 步会 `colima start`（可耗时数分钟），在非交互 agent 环境里会 block 直到被 reaper abort，本次运行就白跑了。要拉起环境只用 `apc env up --safe`（heavy 步只出 fix-hint 不执行）。
+## Procedure
+### 1. 诊断（doctor）
+```bash
+npx tsx sdk/apc/bin/apc.ts env doctor > /tmp/apc-doctor.json
+echo "doctor exit=$?"
+```
+从 `/tmp/apc-doctor.json` 读结构化结果，真实 schema（**字段名以此为准**）：
+- 顶层：`{ envStatus, exitCode, summary:{pass,fail,skip,total}, failed:[<itemId>...], undetected:[<itemId>...], items:[...] }`。
+- 每个 `items[]` 元素：`{ item(id,如 "toolchain.node"), label, section(infra|toolchain|secrets), status(pass|fail|skip), detail, fixHint, strength }`。
+- `failed[]` = 所有 `status:fail` 的 item id；`undetected[]` = 所有 `status:skip` 的 item id。
+判据：`summary.total == summary.pass + summary.fail + summary.skip == items.length`——一项崩不塌全轮。
+- `exit 0` → 环境全绿，产出"逐项 pass"的诊断，收工。
+- `exit 78` → 存在环境红（`failed[]` 非空），进第 2 步分类。
+### 2. 分类（故障域）
+**故障域 = item 的 `section` 字段**（不是另算的）。把每个 `status:fail` 的 item 按 `section` 归组，逐项列出 `{ item, section, detail, fixHint }`：
+| 故障域（section） | 典型 item | 处置 |
+| --- | --- | --- |
+| `infra`（本机基础设施） | `infra.mysql-3307` / `infra.redis-6380` / `infra.nacos` / `infra.kind-<cluster>` / `infra.cloud-dev-server` 未起 | `apc env up` 可拉起 |
+| `toolchain`（工具链版本） | `toolchain.node` major / 锁定 claude binary 版本不符 / 网关口径 | `apc env up` 装锁定 binary；node 需人手 |
+| `secrets`（凭据/密钥） | `secrets.env-local-required-keys` 缺 `SKILL_CONFIG_ENC_KEY` / `IDENTITY_KMS_KEY` 等 | **不代办**——只报 `fixHint`，等人按提示补 |
+| `project`（工程态） | `project.node-modules-lockfile` / `project.prisma-clients` / `project.mysql-migrations-pending` / `project.version-alignment` | 多数是 heavy 步，`--safe` 下归 `manual[]` 出 fix-hint |
+> **段是四段不是三段**：`sdk/apc/env/manifest.ts` 的四段清单是 `infra` / `toolchain` / `secrets` / `project`（`ENV_MANIFEST` 由这四组拼成）。分类只认 item 的 `section` 字段，别把 `project` 项硬塞进前三域。
+**判据**：`secrets` 域的红**永远不自动修**（`apc env up` 只出 fix-hint，凭据不代办，`apc/00` §3）。别声称已修一个 secrets 项。
+### 3. 拉起可自动化项（up，**dispatch 语境用 `--safe`**）
+```bash
+npx tsx sdk/apc/bin/apc.ts env up --safe
+echo "up exit=$?"
+```
+- `--safe` 是 dispatch 语境的强制形态：heavy 步（colima / dev-stack / kind / npm ci / prisma / migrations）**不自动跑**，只归 `manual[]` 出 fix-hint。轻量幂等步（配置目录 / bare 替身）照跑。**这样本步永不 block。**
+- `apc env up` 是**幂等**的：第二次跑对已就绪项全 `skip`。
+- 只对 `infra` / `toolchain` 里可自动化的项生效；`secrets` 域只出 fix-hint。
+- 修完回到第 1 步重跑 `apc env doctor` 确认红项减少（红→绿可逆才算真修，恒红是没修）。heavy 步落在 `manual[]` 属预期——它们要人在交互终端跑不带 `--safe` 的 up，不由本次 dispatch 代办。
+### 4. 指纹（fingerprint）
+```bash
+npx tsx sdk/apc/bin/apc.ts env fingerprint > /tmp/apc-fingerprint.json
+echo "fingerprint exit=$?"
+```
+指纹是机器等价性证明——同一环境两台机器指纹应等价。收工时附上它。
+## 输出契约（机器判据按这个复验，别自由发挥格式）
+本 skill 的验收判据不再是「报告里出现了 `infra` / `fail: 2` 这些词」——旧判据里 `\b(infra|toolchain|secrets?)\b` 一个词就能让「故障域已分类」变绿，`(pass|fail|skip)…\d+` 一个数字就能冒充「逐项报告」。现在判据找的是**每一个 item 自己那一行**，并把该行的引用**读回磁盘复核**（`structured-criteria.ts` 的 `dimension-coverage`）。
+**逐项作答**（每个 item **独占一行 + 用它的 item id 当 key**，值给：真实 status → 故障域 → 关键 detail/fixHint → 该 item 在 manifest 里的**声明行**）：
+```
+- infra.docker-daemon: pass | domain=infra | sdk/apc/env/manifest.ts:165
+- infra.mysql-3307: pass | domain=infra | MySQL 8.0.46 真握手 | sdk/apc/env/manifest.ts:178
+- toolchain.node: fail | domain=toolchain | node 23.9.0 major 23 ≠ pin 20 | fixHint: nvm use 20 | sdk/apc/env/manifest.ts:318
+- toolchain.hermes-gateway-models: skip | domain=toolchain | 未检测（无凭据）| sdk/apc/env/manifest.ts:408
+- secrets.env-local-required-keys: fail | domain=secrets | 本地凭据缺失，只出 fixHint 不代办 | sdk/apc/env/manifest.ts:449
+- project.mysql-migrations-pending: fail | domain=project | 1 条 pending | fixHint: npm run db:migrate | sdk/apc/env/manifest.ts:603
+```
+**判据钉住的 21 个 item id**（= `ENV_MANIFEST` 除 `infra.kind-<cluster>`）：`infra.docker-daemon` · `infra.mysql-3307` · `infra.mysql-migration-ledger` · `infra.redis-6380` · `infra.nacos` · `infra.cloud-dev-server` · `toolchain.node` · `toolchain.docker-compose` · `toolchain.kubectl` · `toolchain.kind-cli` · `toolchain.claude-code-binary-pin` · `toolchain.hermes-binary` · `toolchain.hermes-gateway-models` · `secrets.env-local-required-keys` · `secrets.ota-ui-signing-key` · `project.node-modules-lockfile` · `project.prisma-clients` · `project.mysql-migrations-pending` · `project.version-alignment` · `project.claude-config-dir` · `project.bare-repo-mirror`。
+> `infra.kind-<cluster>` 的 id 由 `CLUSTER_NAME` 拼（manifest.ts:249），**不进固定判据**（否则改环境变量会让如实报告变红）——但它照样要出现在你的逐项表里。
+**故障域汇总**（四段各独占一行，引用该段清单在 manifest 里的起始行）：
+```
+- domain-infra: 7 项 → pass 7 / fail 0 / skip 0 | sdk/apc/env/manifest.ts:163
+- domain-toolchain: 7 项 → pass 5 / fail 1 / skip 1 | sdk/apc/env/manifest.ts:316
+- domain-secrets: 2 项 → pass 1 / fail 1（凭据永不自动修，只出 fixHint）| sdk/apc/env/manifest.ts:447
+- domain-project: 6 项 → pass 5 / fail 1 | sdk/apc/env/manifest.ts:569
+```
+判据强制三条：
+1. 每个 key **必须有自己那一行**——「报告里别处提过 `toolchain.node`」不算作答（漏一项判红）。
+2. 每行的值**必须带至少一条能在磁盘上复核的 `path:line`**（文件存在、行号在范围内、该行非空）——`rg -n "id: 'toolchain.node'" sdk/apc/env/manifest.ts` 出来的行号，**别猜**。
+3. 只有真不适用的行才写 `N/A — <理由 ≥20 字符>`；**真 item 不许以 `无` / `N/A` 开头**（会被当成"这项不适用"），一律以真实 `pass`/`fail`/`skip` 开头。
+引用写法：**必须 repo-root-relative**（`sdk/apc/env/manifest.ts:318`，不要简写、不要绝对路径）；`rg -c` 出的 `path:12` 是**命中计数不是行号**，要写就写 `count=12`。
+**诚实边界（`dimension-coverage` 这条判据管到哪）**：它复核的是「每项都作答了 + 引用真实存在」，**不复核 status 本身**。~~把 `fail` 写成 `pass` 骗不过重跑 doctor 的人，但骗得过这条判据。~~ ← **已由下面的 ③ 收窄**（2026-07-26）。
+**③ 原始产物 + 七行判定声明**（`json-claim` 复核；**这条是本 skill 的承重判据**）
+把 `apc env doctor` 的 stdout **原样贴进一个 fenced JSON 块**（别摘录、别改写），并给出七行：
+```
+DOCTOR-EXIT: 78
+DOCTOR-VERDICT: env-blocked
+DOCTOR-PASS: 16
+DOCTOR-FAIL: 5
+DOCTOR-SKIP: 1
+DOCTOR-TOTAL: 22
+DOCTOR-FAILED-IDS: toolchain.node,secrets.env-local-required-keys,project.mysql-migrations-pending
+DOCTOR-UNDETECTED-IDS: toolchain.hermes-gateway-models
+```
+checker 重新解析产物并核对：
+- **五个计数与退出码必须逐字等于产物字段**（`exitCode` / `summary.pass|fail|skip|total`）。**这条直接管住了本文档自己犯过两次的错**：apc/12 §0 的 doctor 计数先写「20 pass / 2 fail」、更正为「18 pass / 3 fail / 1 skip」、今天实测又是 `16/5/1` —— 报计数而不报全、且不与产物对账，账就会漂。
+- **`DOCTOR-VERDICT` 由 `exitCode` 派生**，只有两个合法值：`0 ⇒ all-green`、`78 ⇒ env-blocked`。
+- **`exitCode` 只允许 `0|78`** —— 任何别的值意味着 doctor 自己崩了（"一项崩不塌全轮"这条不变量的机器化）。
+- **`DOCTOR-FAILED-IDS` / `DOCTOR-UNDETECTED-IDS` 必须逐字列出产物里的真实 id 集合**（逗号分隔、保持产物顺序）。把某一项的 `fail` 写成 `pass` 会与这份清单直接冲突。
+- 三条 implication：`exitCode=78 ⇒ envStatus='env_blocked'`；`exitCode=0 ⇒ failed 为空`；`envStatus='ok' ⇒ failed 为空`。
+> **仍未被判据覆盖的（诚实）**：**逐项 status 与汇总计数之间的自洽性**没有自动交叉验证 —— checker 能确认 `DOCTOR-FAIL: 5` 等于产物，也能确认 failed 清单，但不会去数你上面那 22 行里有几行写了 `fail`。一个同时篡改逐项行、汇总行与清单的伪造者仍能自洽。**skip 不是 pass**：`total == pass+fail+skip` 要自己核，别把 skip 并进 pass 报。
+## 产出（副作用 oracle，报告里必须给）
+1. **逐项 pass/fail 诊断**：从 `apc env doctor` 的 stdout JSON 逐个 item 列 `{item, status, section}` + `summary`；证明"一项崩不塌全轮"（`summary.total == pass+fail+skip == items.length`）。
+2. **故障域分类**：每个 `failed[]` 项按其 `section` 归到 `infra|toolchain|secrets`，带 `detail`+`fixHint`。
+3. **up 幂等证据**：`apc env up --safe` 退出码 + 已就绪项全 skip（heavy 未修项归 `manual[]`，属预期）。
+4. **fingerprint JSON**：`apc env fingerprint` 产物。
+**不许**：把 `secrets` 红当作已修；把 doctor 的 exit 78 当作 SUT 红上报；从人读摘要抠结论而非读 stdout JSON。
+## 诚实边界
+- `apc env doctor` 无 task 上下文（它不在一次 dispatch 的 task 里跑），所以下方调用回执的 `cloud skill ack` 会 **exit 3（无 task 上下文）**——这是契约限制，不是失败。本次运行**没有回执**，报告里不得声称已 ack。
+- `secrets` 域缺 key 读作"这台机的 `.env.local` 缺"，不读作"运行时一定拿不到"（Nacos 可能有）——按 `fixHint` 交人。
+<!-- APC-ACK:v1 -->
+## 调用回执（APC 平台方运营纪律 · 自动注入，勿手改）
+执行本 skill 的**第一步**，先落一条调用回执：
+```bash
+cloud skill ack env-doctor --task "$PRISMER_TASK_ID"
+```
+**按退出码分流**（这条命令的退出码是承重信息，禁止用 `||` 兜底、`; true`、
+`set +e` 或重定向把它抹掉）：
+| exit | 含义 | 你要做的 |
+| --- | --- | --- |
+| `0` | 回执已落库（`im_task_logs.action='skill_ack'`） | 继续执行本 skill |
+| `3` | **无 task 上下文**——本次运行没有 task，产不出回执 | 继续执行本 skill；但本次运行**没有回执**，任何报告里都不得声称已 ack |
+| `4` | 你不是该 task 的 assignee，服务端拒绝 | 停下并上报：回执只能由执行该 task 的 agent 产生 |
+| `1` | 其它失败（网络 / 服务端） | 重试一次；仍失败则继续执行，并在结果里显式标注「回执缺失」 |
+回执只证明本 skill **被调度**，不证明**执行正确**——效果证明由本 skill 自己的
+acceptanceCriteria 副作用断言承担（apc/04 §2 层 1 诚实标注）。
+<!-- /APC-ACK:v1 -->