kld-sdd 2.6.3 → 2.6.5

package/skywalk-sdd/ontology/traceability-validator.cjs

@@ -340,6 +340,161 @@ function validateInheritedReferences(facts, diagnostics, identityHistory) {
   }
 }
 
+function validateContinuityAndExternalRefs(facts, diagnostics, options = {}) {
+  const allowed = {
+    requirement: new Set(['Capability']),
+    scenario: new Set(['SpecificationStatement', 'AcceptanceCriterion']),
+    feature: new Set(['Capability']),
+  };
+  const continuity = facts.continuity || {};
+  const kind = String(continuity.kind || '').toLowerCase();
+  const resolutionPath = options.continuityResolutionPath
+    || (facts.change
+      ? require('path').join(
+        options.projectRoot || process.cwd(),
+        'openspec',
+        'changes',
+        facts.change,
+        'continuity-resolution.json',
+      )
+      : '');
+  let resolution = null;
+  if (resolutionPath) {
+    try {
+      const fs = require('fs');
+      if (fs.existsSync(resolutionPath)) {
+        resolution = JSON.parse(fs.readFileSync(resolutionPath, 'utf8'));
+      }
+    } catch {
+      resolution = null;
+    }
+  }
+
+  if (kind === 'iteration') {
+    const caps = (facts.entities || []).filter((entity) => entity.type === 'Capability');
+    for (const capability of caps) {
+      if (!capability.entity_id || !capability.version_id) {
+        diagnostics.push(diagnostic(
+          DIAGNOSTIC_CODES.CONTINUITY_IDENTITY_MISMATCH,
+          'error',
+          `Continuity=iteration 时 Capability 缺少 KB 回传身份: ${capability.id}`,
+          {
+            ...sourceContext(capability),
+            entity_id: capability.id,
+            suggestion: '在 propose 用 entities/resolve 回填 entity-id / version-id',
+          },
+        ));
+      }
+    }
+    if (!resolution || resolution.status === 'pending') {
+      diagnostics.push(diagnostic(
+        DIAGNOSTIC_CODES.CONTINUITY_DECISION_REQUIRED,
+        'error',
+        'Continuity=iteration 但 continuity-resolution.json 缺失或仍为 pending',
+        {
+          file: resolutionPath || 'continuity-resolution.json',
+          suggestion: '在 propose/spec 完成 A/B/C 决议后再 check',
+        },
+      ));
+    }
+  }
+
+  if (resolution && resolution.status && resolution.status !== 'pending') {
+    const decisions = [
+      ...(Array.isArray(resolution.capabilities) ? resolution.capabilities : []),
+      ...(Array.isArray(resolution.scenarios) ? resolution.scenarios : []),
+    ];
+    const entitiesByAnchor = new Map(
+      (facts.entities || []).map((entity) => [String(entity.anchor_id || entity.id || '').toUpperCase(), entity]),
+    );
+    for (const decision of decisions) {
+      const anchor = String(decision.anchor || '').toUpperCase();
+      if (!anchor) continue;
+      const entity = entitiesByAnchor.get(anchor);
+      if (!entity) continue;
+      const decisionCode = String(decision.decision || '').toLowerCase();
+      const decidedEntityId = String(decision.entityId || decision.entity_id || '').toLowerCase();
+      const actualEntityId = String(entity.entity_id || '').toLowerCase();
+      if (
+        (decisionCode === 'reuse-existing-identity' || decisionCode === 'reuse_existing' || decisionCode === 'a')
+        && decidedEntityId
+        && actualEntityId
+        && decidedEntityId !== actualEntityId
+      ) {
+        diagnostics.push(diagnostic(
+          DIAGNOSTIC_CODES.CONTINUITY_IDENTITY_MISMATCH,
+          'error',
+          `决议复用历史身份但产物仍使用新 entity_id: ${anchor}`,
+          {
+            ...sourceContext(entity),
+            entity_id: entity.id,
+            suggestion: '按 continuity-resolution 回填历史 entity-id / version-id',
+          },
+        ));
+      }
+      if (
+        (decisionCode === 'assign-new-anchor' || decisionCode === 'assign_new' || decisionCode === 'b')
+        && decidedEntityId
+        && actualEntityId
+        && decidedEntityId === actualEntityId
+        && String(decision.notes || '').toLowerCase().includes('new-anchor-required')
+      ) {
+        diagnostics.push(diagnostic(
+          DIAGNOSTIC_CODES.CONTINUITY_IDENTITY_MISMATCH,
+          'error',
+          `决议为新对象但仍共用旧锚点/身份: ${anchor}`,
+          {
+            ...sourceContext(entity),
+            entity_id: entity.id,
+            suggestion: '更换新锚点并分配新 entity_id 后重跑 check',
+          },
+        ));
+      }
+    }
+  }
+
+  const bindingKeys = new Map();
+  for (const entity of facts.entities || []) {
+    for (const ref of entity.external_refs || []) {
+      const objectType = String(ref.object_type || '').toLowerCase();
+      const allowedTypes = allowed[objectType];
+      if (!allowedTypes) {
+        diagnostics.push(diagnostic(
+          DIAGNOSTIC_CODES.EXTERNAL_REF_INVALID,
+          'error',
+          `未知 external object_type: ${objectType} (${entity.id})`,
+          { ...sourceContext(entity), entity_id: entity.id },
+        ));
+        continue;
+      }
+      if (!allowedTypes.has(entity.type)) {
+        diagnostics.push(diagnostic(
+          DIAGNOSTIC_CODES.EXTERNAL_REF_TYPE_MISMATCH,
+          'error',
+          `external object_type=${objectType} 与实体类型 ${entity.type} 不匹配: ${entity.id}`,
+          { ...sourceContext(entity), entity_id: entity.id },
+        ));
+      }
+      const key = `${ref.system}|${objectType}|${ref.external_id}|${entity.anchor_id || entity.id}`;
+      const prior = bindingKeys.get(key);
+      if (prior && prior !== entity.entity_id) {
+        diagnostics.push(diagnostic(
+          DIAGNOSTIC_CODES.EXTERNAL_REF_CONFLICT,
+          'error',
+          `同外部键+同锚点绑定了不同 entity_id: ${entity.id}`,
+          {
+            ...sourceContext(entity),
+            entity_id: entity.id,
+            suggestion: '复用历史身份或更换新锚点后重开 entity_id',
+          },
+        ));
+      } else if (entity.entity_id) {
+        bindingKeys.set(key, entity.entity_id);
+      }
+    }
+  }
+}
+
 function validateTraceability(facts, options = {}) {
   const profile = normalizeProfile(options.profile || 'auto', facts.profile || 'simple');
   const graphEntities = options.effectiveGraph && options.effectiveGraph.effective_entities
@@ -356,6 +511,7 @@ function validateTraceability(facts, options = {}) {
   const entitiesById = new Map();
 
   validateArtifactPresence(facts, profile, diagnostics);
+  validateContinuityAndExternalRefs(facts, diagnostics, options);
 
   if (profile === 'strict') {
     for (const artifact of facts.artifacts || []) {

package/templates/openspec/continuity-resolution.example.json

@@ -0,0 +1,32 @@
+{
+  "status": "resolved",
+  "updatedAt": "2026-07-23T00:00:00.000Z",
+  "capabilities": [
+    {
+      "anchor": "CAP-ORDER-CANCEL",
+      "externalKey": {
+        "system": "requirement-mgmt",
+        "objectType": "requirement",
+        "externalId": "REQ-FI-2024-001"
+      },
+      "decision": "reuse-existing-identity",
+      "entityId": "00000000-0000-4000-8000-000000000001",
+      "currentVersionId": "00000000-0000-4000-8000-000000000011",
+      "notes": "propose 阶段 A/B/C：复用历史能力"
+    }
+  ],
+  "scenarios": [
+    {
+      "anchor": "AC-ORDER-CANCEL-001",
+      "externalKey": {
+        "system": "requirement-mgmt",
+        "objectType": "scenario",
+        "externalId": "REQ-FI-2024-001:SCN-req-date-empty-002"
+      },
+      "decision": "reuse-existing-identity",
+      "entityId": "00000000-0000-4000-8000-000000000021",
+      "currentVersionId": "00000000-0000-4000-8000-000000000031",
+      "notes": "spec 阶段场景冲突决议"
+    }
+  ]
+}

package/templates/openspec/proposal.md

@@ -7,6 +7,24 @@ delta-state: "added"
 predecessor-version: "" # added 留空；modified/removed 指向直接前序版本
 mode: "" # full=分 Capability 产物，simple=根目录精简产物
 test-strategy: "" # tdd=测试先行, impl-first=实现优先, none=无测试
+# 外部需求键（首轮冷启动也建议写入，便于 ingest 种桥）
+requirement-refs:
+  - system: requirement-mgmt
+    object-type: requirement
+    external-id: REQ-<DOMAIN>-<NNN>
+# Continuity：字段一律来自知识库 resolve，禁止本地 archive 文件夹名
+continuity:
+  kind: new # iteration | similar-reference | new
+  kb-space-id: "" # KB space UUID（iteration 时必填）
+  kb-id: "" # KB UUID（iteration 时必填）
+  base-change-id: "" # 可选，来自 KB source/change_id
+  base-archive-id: "" # 可选溯源（KB archive_id），不是本地目录名
+  base-capabilities: []
+  # iteration 示例：
+  # base-capabilities:
+  #   - anchor: CAP-<CAPABILITY>
+  #     entity-id: <uuid>
+  #     current-version-id: <uuid>
 ---
 
 # proposal.md - 业务意图与上下文总览

package/templates/openspec/spec.md

@@ -34,6 +34,7 @@ capability-id: "CAP-<CAPABILITY>" # 必须与 proposal.md 中的 Capability ID
 - **version-id**: <UUID>
 - **delta-state**: added
 - **predecessor-version**: 无
+- **external-ref**: requirement-mgmt:scenario:REQ-<DOMAIN>-<NNN>:SCN-<slug>
 - **当** <!-- 触发条件 -->
 - **预期** <!-- 预期结果 -->
 
@@ -42,6 +43,7 @@ capability-id: "CAP-<CAPABILITY>" # 必须与 proposal.md 中的 Capability ID
 - **version-id**: <UUID>
 - **delta-state**: added
 - **predecessor-version**: 无
+- **external-ref**: requirement-mgmt:scenario:REQ-<DOMAIN>-<NNN>:SCN-<slug>
 - **当** <!-- 触发条件 -->
 - **预期** <!-- 预期结果 -->
 
@@ -61,6 +63,7 @@ capability-id: "CAP-<CAPABILITY>" # 必须与 proposal.md 中的 Capability ID
 - **version-id**: <新 UUID>
 - **delta-state**: <modified|added>
 - **predecessor-version**: <modified 时填写；added 为无>
+- **external-ref**: requirement-mgmt:scenario:REQ-<DOMAIN>-<NNN>:SCN-<slug>
 - **当** <!-- 触发条件 -->
 - **预期** <!-- 预期结果 -->
 

package/templates/skills/kld-sdd/opsx-archive/SKILL.md

@@ -3,10 +3,11 @@ name: opsx-archive
 description: "归档变更技能 - 将已结束的 SDD 变更真实移入 archive，并生成最终中文度量报告"
 argument-hint: "[change-name]"
 license: MIT
-compatibility: Requires skywalk-sdd/log.cjs.
+compatibility: Requires skywalk-sdd/log.cjs; depends on opsx-kb-ingest for KB upload.
 metadata:
   author: sdd-team
   version: "3.2"
+  depends-on: opsx-kb-ingest
 allowed-tools:
   - Bash
   - Read
@@ -16,6 +17,8 @@ allowed-tools:
 
 你是一个 SDD（Specification-Driven Development）变更归档专家。激活本技能后，你要安全地结束变更生命周期：真实归档文档、同步正式 specs、记录 archive telemetry，并生成最终中文度量报告。
 
+> **硬依赖（收尾入库）**：zip 生成后的上传依赖同级已部署的 **`opsx-kb-ingest`**。进入 §5.5 前必须先 `Read` 该技能的 `SKILL.md` 并完成其 Session 启动。缺失则提示用户重新 `kld-sdd-init`，**不要**自造另一套入库协议。
+
 > **跨平台执行规则**
 > - 先确认当前终端工作目录是项目根目录；若不是，先 `cd` 到项目根目录。
 > - Telemetry 命令默认使用 `--project=.`，兼容 Windows、macOS、Linux。
@@ -108,13 +111,19 @@ node skywalk-sdd/log.cjs archive-docs --project=. --change=<变更名称> --reas
 该命令成功后必须已经完成：
 - 活动目录 `openspec/changes/<name>/` 被移入 `openspec/changes/archive/<日期>-<name>/`。
 - 归档目录写入 `archive-ontology.json`、`canonical-facts.json`、`conversion-report.json` 和新版 `archive-manifest.json`。
-- 生成知识库可直接消费的 `openspec/changes/archive/<日期>-<name>.zip`，包内文件必须由 manifest 完整列举并通过 SHA-256 校验。
+- 生成知识库可直接消费的 `openspec/changes/archive/<日期>-<name>.zip`（canonical-facts **v2**，含 `external_refs`），包内文件必须由 manifest 完整列举并通过 SHA-256 校验。
 - Full Spec 的 `specs/<capability>/spec.md` 同步到 `openspec/specs/<capability>/spec.md`。
 - archive 阶段写入 `stage_end`。
 - 未勾选 tasks 被写入 `archive_result.task_completion`。
 - 最终中文报告生成到 `openspec/changes/archive/<日期>-<name>/reports/<name>-report.md` 及同名 `<name>-report.html`（默认同时生成 .md 与 .html 双产物，默认归档后 archive 目录，可用 --report-output 自定义）。
 - 执行日志 `openspec/changes/archive/<日期>-<name>/logs/execution-log.md` 随归档整目录迁移（人读审计层）。
 
+### 5.5 收尾入库（opsx-kb-ingest）
+
+1. 确认 `${AGENT_SKILL_DIR}/opsx-kb-ingest/SKILL.md` 存在并 Read；按该技能完成 API Key / targets。
+2. 归档 zip 生成后，**加载并执行** **`opsx-kb-ingest`** 上传（勿只口头提示而不走技能流程）；成功则写 `ingest-receipt.json`。
+3. 若返回 `EXTERNAL_REF_CONFLICT`，引导回 spec/check 修正后重入，**禁止**在 KB 内现场改绑。
+
 > 注意：`archive-docs` 成功执行后已经在内部写入 `stage_end`，因此**不要在成功的归档后再单独运行 `node skywalk-sdd/log.cjs end --command=archive ...`**。仅在第 5 步归档命令失败时，才需要运行下方的失败分支 `end`。
 
 如果该命令失败，以失败状态结束 telemetry：

package/templates/skills/kld-sdd/opsx-check/SKILL.md

@@ -216,6 +216,16 @@ node skywalk-sdd/log.cjs record --type=conformance_review --command=check --proj
 
 ---
 
+## Continuity / external_ref 确定性门禁
+
+`opsx-check` **不联网提问**。Agent 应在 propose/spec 已问完；本阶段只验证并入既有 apply 前门禁：
+
+- Continuity=`iteration` 时每个 CAP 具备 KB 回传 `entity-id` / `version-id`
+- 已写 spec 的 Capability：场景 `external-ref` 与 `continuity-resolution.json` 决议一致；同 key+同锚点未偷偷换 entity_id
+- 用户选「原对象」却仍用新 id、或选「新对象」却仍共用旧锚点 → 失败（`CONTINUITY_IDENTITY_MISMATCH` / `EXTERNAL_REF_CONFLICT`）
+- 决议缺失 / pending / 与产物不一致 → `CONTINUITY_DECISION_REQUIRED`
+- CI/非交互：失败即非零退出并打印修复说明，不挂起等待输入
+
 ## 本体语义关系门禁
 
 在其他质量检查前必须运行：

package/templates/skills/kld-sdd/opsx-kb-ingest/SKILL.md

@@ -0,0 +1,190 @@
+---
+name: opsx-kb-ingest
+description: >-
+  Uploads knowledge archive packages (zip) to the Engineering KB via API Key
+  (archive:ingest scope). Prompts for API key and multi-selects spaces/KBs into
+  local skill state. Supports upload, job status query, job list, and retry.
+  Use when ingesting new or updated knowledge archives into the ontology KB.
+argument-hint: "[path-to-archive.zip]"
+license: MIT
+compatibility: Requires Engineering KB API (API Key with archive:ingest).
+metadata:
+  author: sdd-team
+  version: "1.0"
+  source: "kb-sdd/skills/opsx-kb-ingest"
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+---
+
+# 本体知识库 · 入库
+
+> **部署说明**：本技能随 `kld-sdd-init` 安装到项目 skills 目录。权威源在工程知识库仓 `skills/opsx-kb-ingest`；`opsx-archive` **硬依赖**本技能完成收尾入库。
+
+只负责**入库**（zip 上传）。鉴权只用 **API Key**（`Authorization: Bearer sk_sdd_…`），**禁止**走手机号登录。
+
+> 控制台知识库页另有浮动 Ontology Agent（会话登录 + SSE）；本 Skill 仍走 API Key，二者分开。
+
+本地状态文件（含密钥，勿提交）：
+
+```text
+skills/opsx-kb-ingest/.local/state.json
+```
+
+字段说明 → [reference.md](reference.md)。
+
+## Session 启动（每次用本 Skill 必做）
+
+```
+Task Progress:
+- [ ] 1. 读 .local/state.json（没有则当空）
+- [ ] 2. 无 apiKey → 向用户索取并写入 state（勿把完整 key 打进聊天摘要）
+- [ ] 3. 无 targets 或用户要重置 → 拉空间/KB 列表，让用户多选后写入
+- [ ] 4. 按意图执行入库操作（上传 / 查状态 / 列表 / 重试）
+- [ ] 5. 按模板输出结果
+```
+
+### 1–2. API Key
+
+若 `state.apiKey` 为空或无效（401/403）：
+
+1. 请用户提供 API Key（控制台「API 密钥」创建，至少含 `archive:ingest`）。
+2. 可选：请用户确认 `api`（默认 `http://localhost:8090/api`）与 `tenantKey`（默认 `default`）。
+3. 写入 `.local/state.json`（创建目录若不存在）。
+4. 用 `GET $API/health` 探活；再用 `GET $API/v1/spaces?tenantKey=…` + Bearer 校验 key。
+
+用户说「换密钥 / 重置 API Key」→ 清空 `apiKey`（可保留 targets），回到本步。
+
+### 3. 选择空间与知识库（支持多选）
+
+若 `state.targets` 为空，或用户说「重新选择 / 重置空间 / 重置知识库」：
+
+1. `GET $API/v1/spaces?tenantKey=$TENANT_KEY`
+2. 对每个相关 space：`GET $API/v1/spaces/{spaceId}/knowledge-bases`
+3. 向用户展示「空间名 / spaceId → KB 名 / kbId」清单，**允许多选**。
+4. 写入 `targets: [{ spaceId, spaceName, spaceKey, kbId, kbName }, …]`。
+5. 仅清空 targets、保留 apiKey 即完成「重置空间和知识库」。
+
+入库时：用户指定目标 KB（从 `targets` 中选择），仅对选中的 KB 执行上传。
+
+### 4. 入库操作
+
+路径前缀：`/api/v1/spaces/{spaceId}/knowledge-bases/{kbId}/ingestions`
+所有请求：`-H "Authorization: Bearer $API_KEY"`
+
+| 意图 | 调用 |
+|------|------|
+| 上传 zip 包入库 | `POST …/ingestions`（multipart，字段名 `package`） |
+| 列出入库任务 | `GET …/ingestions` |
+| 查看任务状态 | `GET …/ingestions/{jobId}` |
+| 重试失败任务 | `POST …/ingestions/{jobId}/retry` |
+
+**上传入库**
+
+```bash
+curl -sS -X POST "$API/v1/spaces/$SPACE_ID/knowledge-bases/$KB_ID/ingestions" \
+  -H "Authorization: Bearer $API_KEY" \
+  -F "package=@/path/to/your-archive.zip;type=application/zip"
+```
+
+**查看任务状态**
+
+```bash
+curl -sS -X GET "$API/v1/spaces/$SPACE_ID/knowledge-bases/$KB_ID/ingestions/$JOB_ID" \
+  -H "Authorization: Bearer $API_KEY"
+```
+
+**列出入库任务**
+
+```bash
+curl -sS -X GET "$API/v1/spaces/$SPACE_ID/knowledge-bases/$KB_ID/ingestions" \
+  -H "Authorization: Bearer $API_KEY"
+```
+
+**重试失败任务**
+
+```bash
+curl -sS -X POST "$API/v1/spaces/$SPACE_ID/knowledge-bases/$KB_ID/ingestions/$JOB_ID/retry" \
+  -H "Authorization: Bearer $API_KEY"
+```
+
+### Archive Package 要求
+
+上传的 zip 包必须满足以下条件（否则入库会失败）：
+
+- 包含三个必需 JSON 文件：`archive-manifest.json`、`canonical-facts.json`、`conversion-report.json`
+- `canonical-facts.json` 支持 `kld-sdd-canonical-facts/v1` 与 **`v2`**（v2 可选实体级 `external_refs`）
+- 所有文件需通过 SHA-256 校验（manifest 中记录每个文件的 `content_hash`）
+- 允许的文件类型：`.md`、`.json`、`.jsonl`、`.yaml`、`.yml`
+- 大小限制：包 ≤ 50MB，条目 ≤ 2000 个，单文件 ≤ 10MB，解压后 ≤ 200MB
+- `archive-manifest.json` 中的 `project_id` 必须与目标 Space 的 `spaceKey` 一致
+
+**v2 本地预检（skill 侧，上传前）**
+
+- `external_refs[]` 每项含 `system` / `object_type` / `external_id`
+- object_type 与实体类型匹配：`requirement`/`feature`→Capability；`scenario`→SpecificationStatement|AcceptanceCriterion
+- 包内无重复 `(external key, entity_id)` 绑定对
+- `project_id` / `spaceKey` 既有规则保留
+
+详细字段说明 → [reference.md](reference.md)。
+
+### 5. 输出模板
+
+```markdown
+### 入库结果
+- 目标 KB：{spaceName}/{kbName}
+- 操作：{上传 | 查状态 | 列表 | 重试}
+- 状态：{succeeded | failed | running | idempotent}
+- Job ID：{jobId}
+
+### 详情
+- archiveId：{archiveId}
+- contentHash：{contentHash}
+- stage：{stage}
+- relationStatus：{relationStatus}
+- projectionStatus：{projectionStatus}
+- 外部引用写入数：{externalRefsWritten 或 0}
+- 幂等命中：{是 / 否}
+- 错误信息：{errorCode — errorMessage 或 无}
+```
+
+成功时展示 `report.externalRefsWritten`。冲突**不**出现在成功模板。
+
+若 `errorCode=EXTERNAL_REF_CONFLICT`（整包已回滚）：
+
+1. 展示 `report.details`（externalRef / anchor / existingEntityId / incomingEntityId）。
+2. 向用户给出两个修正选项：
+   - **复用历史身份**：回到 kld-sdd，复用 KB 中原有 entity_id / current version，重新 check → 归档 → 入库
+   - **改为新锚点**：回到 kld-sdd，分配新锚点与新 entity_id，重新 check → 归档 → 入库
+3. **禁止**在 KB 内现场改绑或解绑。
+
+**硬规则**
+
+- 无 `apiKey` 不得猜密钥、不得改走 login。
+- 无 `targets` 不得臆造 spaceId/kbId。
+- 上传前确认 zip 包路径存在且为有效 zip 文件。
+- 入库失败时展示 `errorCode` 和 `errorMessage`，不编造原因。
+- 完整 apiKey 只写 state 文件；聊天里最多显示前缀（如 `sk_sdd_****`）。
+- 401/403 时清掉 `apiKey`，请用户重贴；勿循环重试。
+
+## 用户口令
+
+| 用户说 | Agent 做 |
+|--------|----------|
+| （首次使用） | 要 key → 选 KB（多选）→ 再操作 |
+| 换密钥 / 重置 API Key | 清 apiKey，重走第 2 步 |
+| 重新选择 / 重置空间或知识库 | 清 targets，重走第 3 步 |
+| 上传 / 入库 | 用当前 targets 中选中的 KB 上传 zip |
+| 查状态 / 看任务 | 用 jobId 查询任务状态 |
+| 列任务 / 看历史 | 列出最近入库任务 |
+| 重试 | 对失败的 jobId 执行重试 |
+
+## 心智模型（简述）
+
+- 入库是同步操作：上传后后端立即解析 zip、校验、写入数据库，返回最终 job 状态。
+- 幂等机制：同一 `archive_id` + `content_hash` 重复上传会命中幂等，不重复写入。
+- `archive_id` 不可变：同一 `archive_id` 上传不同 `content_hash` 会被拒绝（`ARCHIVE_IMMUTABILITY_VIOLATION`）。
+- `project_id` 必须匹配：zip 包 manifest 中的 `project_id` 必须等于目标 Space 的 `spaceKey`。
+- 细节与 state schema → [reference.md](reference.md)。