universal-dev-standards 5.17.0 → 6.1.0

package/bundled/locales/zh-CN/core/mock-boundary.md

@@ -0,0 +1,161 @@
+---
+source: ../../../core/mock-boundary.md
+source_version: 1.1.0
+translation_version: 1.1.0
+last_synced: 2026-07-08
+source_hash: fe4715991a4c
+status: current
+---
+
+# Mock 边界标准
+
+> **语言**: [English](../../../core/mock-boundary.md) | [繁體中文](../../zh-TW/core/mock-boundary.md) | 简体中文
+
+**版本**: 1.1.0
+**最后更新**: 2026-07-01
+**适用性**: 所有具备单元测试与集成测试的软件项目
+**范围**: universal
+**行业标准**: ISTQB Foundation（Test Doubles）, xUnit Patterns（Gerard Meszaros）
+**参考**: "Working Effectively with Legacy Code"（Feathers）, "Growing Object-Oriented Software"（Freeman & Pryce）
+
+---
+
+## 目的
+
+本文档定义测试中哪些东西可以 mock、哪些不可以。其目标是防止**空心测试（hollow tests）**——永远通过却无法检测真实 bug 的测试，因为它们用 stub 取代了系统的逻辑。
+
+---
+
+## 空心测试问题
+
+空心测试 mock 掉系统的大部分内容，使测试变成 mock 接线的规格说明，而非系统行为的规格说明。经典症状：你可以删掉实现文件，测试仍然通过。
+
+**真实案例（Multi-agent pipeline SPEC-002.test.ts）**:
+
+```typescript
+vi.mock('../../src/runner/agent-runner.js')      // Core logic replaced
+vi.mock('../../src/runner/guardian-hooks.js')     // Core logic replaced
+vi.mock('../../src/runner/prototyper.js')         // Core logic replaced
+vi.mock('../../src/runner/iteration-report.js')   // Core logic replaced
+vi.mock('../../src/memory/memory-store.js')       // Core logic replaced
+vi.mock('node:fs/promises', ...)                  // I/O replaced
+
+// All assertions verify mock call counts — not actual outputs.
+// runPipeline() touches zero real code.
+```
+
+---
+
+## 可以 Mock 的项目
+
+| 类别 | 示例 | 理由 |
+|------|------|------|
+| 外部 HTTP 服务 | LLM API、支付网关、email 服务 | 防止不稳定（flaky）测试；可控制响应场景 |
+| 时间函数 | `Date.now()`、`new Date()`、`setTimeout` | 使测试具确定性 |
+| 环境变量 | `process.env.NODE_ENV`、`process.env.LICENSE_KEY` | 支持配置变化 |
+| 文件系统（仅限单元测试） | `fs.readFile`、`fs.writeFile` | 让快速单元测试避免 I/O |
+| 跨模块边界（须有对应 IT） | 其他模块的 public API | 隔离被测单元 |
+| 进程内后台执行（通过可注入 runner） | `Task.Run`、unawaited promise、`setTimeout`、goroutine、thread-pool dispatch | 注入 runner seam 让测试能 await 到确定完成，消除 race |
+
+---
+
+## 不可 Mock 的项目
+
+| 类别 | 违规示例 | 禁止原因 |
+|------|---------|---------|
+| 自身模块的核心逻辑 | 在 pipeline-runner 测试中 `vi.mock('./pipeline-runner.js')` | 使测试形同虚设 |
+| IT/flow/E2E 测试中的数据库 | 在集成测试中 `vi.mock('./db/client.js')` | 隐藏查询 bug、schema 问题 |
+| HTTP 框架内部 | `vi.mock('express')` | 真实路由可能已坏 |
+| 安全控制 | 永远通过的 auth middleware stub | 安全性回归不可见 |
+
+---
+
+## 可注入的后台执行（Injectable Background Execution）
+
+fire-and-forget 的后台工作（`Task.Run`、unawaited promise、`setTimeout`、goroutine、`java.util.concurrent` executor 提交，或 `asyncio.create_task`）是一个 **seam**，就跟系统时钟一样。正如你注入 clock 而非直接读取 wall-clock 时间，你也应该注入后台 dispatcher，而非直接生成后台工作。这样测试就能把工作驱动到**确定、可被 await 的完成**，并对其结果（成功、异常或 retry）进行断言——不用 poll、不用 sleep、没有 race。
+
+将 dispatch 抽象成一个小接口（例如 `IBackgroundTaskRunner` / `BackgroundDispatcher`），再提供两种实现：
+
+- **Production**：保留真正的 fire-and-forget 语义——dispatch 立即返回，工作以 detached 方式运行。
+- **Test**：以 **inline** 方式执行工作并**追踪底层 Task/promise**，对外暴露一个 handle 供测试 `await`，使完成（及任何失败）可被观察。
+
+语言中立示意（TypeScript 伪代码）：
+
+```typescript
+// Seam — 在任何 dispatch 后台工作处注入
+interface BackgroundDispatcher {
+  dispatch(work: () => Promise<void>): void
+}
+
+// Production：真正的 fire-and-forget——立即返回，工作以 detached 方式运行
+class FireAndForgetDispatcher implements BackgroundDispatcher {
+  dispatch(work: () => Promise<void>): void {
+    void work() // 刻意不 await
+  }
+}
+
+// Test：inline 执行 + 追踪 task，让测试能 await 到完成
+class DeterministicDispatcher implements BackgroundDispatcher {
+  private readonly tasks: Promise<void>[] = []
+  dispatch(work: () => Promise<void>): void {
+    this.tasks.push(work()) // inline 启动并保留 handle
+  }
+  async settle(): Promise<void> {
+    await Promise.all(this.tasks) // 测试 await 到确定完成
+  }
+}
+```
+
+测试注入 `DeterministicDispatcher`，执行被测代码，再在断言结果前 `await dispatcher.settle()`——后台副作用此时已完全可观察且具确定性。
+
+---
+
+## 空心测试检测
+
+提交测试文件之前，请检查：
+
+1. **Mock 数量 ≥ import 数量** → 评审：至少要有一个断言验证实际输出
+2. **所有断言都是 `.toHaveBeenCalled()` 系列** → 加入输出值断言
+3. **Mock 路径与被测对象目录相同** → 自我引用 mock；移除之
+4. **Mock 设置行数多于断言行数** → 很可能是空心测试
+
+---
+
+## 反模式
+
+- **Total Mock Isolation**：所有 import 都被 mock；只断言 mock 交互
+- **Mock the World**：外部 + 内部 + DB + FS 在同一个测试中全部 mock
+- **Orphan Mock**：跨模块 mock 却没有对应的集成测试
+- **Security Bypass Mock**：auth/权限逻辑被换成直接放行的 stub
+- **Database Mock Cascade**：DB 返回硬编码的数据，隐藏真实查询错误
+- **Poll/Sleep for Background Result**：用 sleep 或 poll 等待 fire-and-forget 后台工作完成。race 依然存在——timeout 只是多数时候把它掩盖住，同时拖慢整个测试套件；在共享 runner 上还会把 flakiness 泄漏到其他 MR 的 CI 中。应改为注入 deterministic runner 并 await 被追踪的 task。
+
+---
+
+## 规则摘要
+
+| 规则 | 触发条件 | 动作 |
+|------|---------|------|
+| 禁止 self-mock | 测试文件 mock 自己的模块 | 移除 mock；让真实代码运行 |
+| IT/flow 用真实 DB | 编写 IT 或 flow 测试 | 使用 in-memory SQLite 或测试 schema |
+| IT 对应测试 | mock 跨模块边界 | 确保有对应的 IT 存在 |
+| 禁止 mock 安全机制 | 测试涉及 auth/权限 | 使用真实测试用户 + 真实 token |
+| 空心评审 | Mock 数量 ≥ import 数量 | 加入输出值断言 |
+| 后台工作禁止 poll/sleep | 测试断言某个 fire-and-forget 副作用 | 注入 deterministic runner；await 被追踪的 task |
+
+---
+
+## 与其他标准的关系
+
+- **testing**：Mock 边界规则适用于测试金字塔的所有测试级别
+- **test-completeness-dimensions**：维度 8（AI 测试质量）引用了这些规则
+- **flow-based-testing**：Flow 测试必须遵循 mock 边界规则
+
+---
+
+## 版本历史
+
+| 版本 | 日期 | 变更 |
+|------|------|------|
+| 1.0.0 | 2026-05-04 | 初始标准：空心测试问题、可／不可 Mock 表格、检测、反模式、规则摘要 |
+| 1.1.0 | 2026-07-01 | 新增可注入的后台执行作为 seam（平行于 clock injection）：可 Mock 表格新增行、`可注入的后台执行` 章节、`Poll/Sleep for Background Result` 反模式，以及后台工作禁止 poll/sleep 规则（issue #143） |

package/bundled/locales/zh-CN/core/model-selection.md

@@ -1,8 +1,8 @@
 ---
 source: ../../../core/model-selection.md
-source_version: 1.0.0
-translation_version: 1.0.0
-last_synced: 2026-03-24
+source_version: 1.0.1
+translation_version: 1.0.1
+last_synced: 2026-06-10
 status: current
 ---
 
@@ -10,8 +10,8 @@ status: current
 
 # AI 模型选择策略
 
-**版本**: 1.0.0
-**最后更新**: 2026-03-20
+**版本**: 1.0.1
+**最后更新**: 2026-06-10
 **适用范围**: 使用多层级模型的 AI 辅助开发
 **范围**: universal
 **灵感来源**: [Superpowers](https://github.com/obra/superpowers) — subagent-driven-development (MIT)
@@ -100,6 +100,20 @@ status: current
 
 ---
 
+## 与下一步建议整合
+
+[ai-response-navigation](ai-response-navigation.md) 标准（规则 R6，可选）允许每个「建议下一步」选项携带级别标注。本标准的复杂度信号即为判断依据。
+
+**与厂商无关原则**：级别名称（Fast／Standard／Capable）是工具无关的泛称。各平台自行将级别映射到可用模型。
+
+| 级别 | 典型能力定位 |
+|------|-------------|
+| Fast | 轻量级 / 指令遵循 |
+| Standard | 均衡推理 + 代码生成 |
+| Capable | 高级推理、架构分析 |
+
+---
+
 ## 相关标准
 
 - [代理派遣与并行协调](agent-dispatch.md)
@@ -107,6 +121,15 @@ status: current
 
 ---
 
+## 版本历史
+
+| 版本 | 日期 | 变更 |
+|------|------|------|
+| 1.0.1 | 2026-06-10 | 新增「与下一步建议整合」节（R6 交叉引用；与厂商无关原则） |
+| 1.0.0 | 2026-03-20 | 初始版本 |
+
+---
+
 ## 许可证
 
 本标准采用 [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) 发布。

package/bundled/locales/zh-CN/core/mutation-testing.md

@@ -0,0 +1,106 @@
+---
+source: ../../../core/mutation-testing.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2026-06-10
+source_hash: 6a5286d76274
+status: current
+---
+
+# 变异测试标准
+
+> **语言**: [English](../../../core/mutation-testing.md) | [繁體中文](../../zh-TW/core/mutation-testing.md) | 简体中文
+
+**版本**: 1.0.0
+**最后更新**: 2026-05-04
+**适用性**: 所有具备单元/集成测试的软件项目
+**范围**: universal
+**行业标准**: ISTQB Foundation Syllabus（测试有效性指标）
+**参考**: "Introduction to Software Testing"（Ammann & Offutt）, Stryker Mutator 文档
+
+---
+
+## 目的
+
+变异测试（mutation testing）通过注入人工 bug 并检查测试是否能检测到它们，来评估测试套件的有效性。它回答了行覆盖率无法回答的问题：**「我的测试真的在验证正确行为吗？」**
+
+---
+
+## 核心概念：Mutation Score
+
+```
+Mutation Score = Killed Mutants / (Killed + Survived) × 100%
+```
+
+- **Killed**：测试套件检测到人工 bug（测试失败）✅
+- **Survived**：测试套件漏掉了 bug（测试仍通过）❌
+
+一个只有 `expect(x).toBeDefined()` 的测试可以达到 100% 行覆盖率，却会让许多变异存活（因为 `x` 是 `null`、`0` 或 `"wrong"` 都满足 `.toBeDefined()`）。
+
+---
+
+## 工具
+
+| 语言 | 工具 | 命令 |
+|------|------|------|
+| TypeScript/JS | Stryker Mutator | `npx stryker run` |
+| Python | mutmut | `mutmut run` |
+| Java | PIT (Pitest) | `mvn pitest:mutationCoverage` |
+
+---
+
+## 阈值
+
+| 模块类型 | 最低分数 | 强制程度 |
+|---------|---------|---------|
+| Auth/License/Payment/Security | 80% | 阻断 release |
+| 标准业务逻辑 | 70% | 警告；下次 release 前解决 |
+| AI 生成的测试 | 50% | 必需；低于即拒绝 |
+| 整体项目 | 60% | 跟踪趋势；回归时告警 |
+
+---
+
+## 何时运行
+
+| 触发条件 | 命令 | 强制程度 |
+|---------|------|---------|
+| Pre-release 门禁 | `npm run test:mutation` | 整体 ≥ 60% |
+| 关键模块变更 | `npx stryker run --mutate 'src/auth/**'` | ≥ 80% |
+| AI 生成测试评审 | `npx stryker run` | ≥ 50% |
+
+**绝不**把变异测试加入 commit hook——它太慢了（10-60 分钟）。
+
+---
+
+## Stryker 快速上手（TypeScript + Vitest）
+
+```bash
+npm install --save-dev @stryker-mutator/core @stryker-mutator/vitest-runner
+```
+
+```json
+// stryker.config.json
+{
+  "testRunner": "vitest",
+  "coverageAnalysis": "perTest",
+  "mutate": ["src/license/**/*.ts", "!src/**/*.test.ts"],
+  "thresholds": { "high": 80, "low": 60, "break": 50 }
+}
+```
+
+---
+
+## 反模式
+
+- 把行覆盖率当作测试有效性的替代指标
+- 在每个 PR 的 CI 中都加入变异测试（太慢）
+- 未经 mutation score 验证就接受 AI 生成的测试
+- 靠加 `toBeDefined()` 断言来杀死变异
+
+---
+
+## 与其他标准的关系
+
+- `test-completeness-dimensions`：维度 8（AI 测试质量）引用 mutation score
+- `mock-boundary`：空心测试会让许多变异存活；mock 边界规则防止空心测试
+- `testing`：变异测试是测试金字塔顶端的质量门禁

package/bundled/locales/zh-CN/core/no-cicd-deployment.md

@@ -0,0 +1,219 @@
+---
+source: ../../../core/no-cicd-deployment.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2026-06-10
+source_hash: dbe8c04bf6a4
+status: current
+---
+
+# No-CI/CD Deployment Strategy
+
+> **Language**: [English](../../../core/no-cicd-deployment.md) | [繁體中文](../../zh-TW/core/no-cicd-deployment.md) | 简体中文
+
+> **补充**: 本文档补充 `deployment-standards.md`，专注于无 CI/CD 平台（GitHub Actions / GitLab CI）环境下的可靠部署设计。
+
+## 核心三层架构
+
+```
+Layer 1: 防止错误部署
+  └─ set -euo pipefail、版本 tag 强制、deploy.lock
+
+Layer 2: 验证部署正确
+  └─ Smoke Test、健康检查、版本号比对、自动 rollback
+
+Layer 3: 快速恢复能力
+  └─ Blue-Green 切换、< 30 秒 rollback
+```
+
+## Layer 1：防止错误部署
+
+### Shell 脚本强制执行
+
+所有部署脚本必须以下列标头开始：
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+```
+
+- `set -e`：任何命令失败立即退出
+- `set -u`：引用未定义变量视为错误
+- `set -o pipefail`：管线中任何命令失败都会传播错误
+
+### 强制部署顺序
+
+```bash
+echo "[1/4] 执行测试..."
+npm test
+
+echo "[2/4] 构建产物..."
+npm run build
+
+echo "[3/4] 推送到服务器..."
+rsync -avz --delete ./dist/ user@server:/app/
+
+echo "[4/4] 验证部署..."
+./verify.sh || { echo "验证失败，执行 rollback..."; ./rollback.sh; exit 1; }
+```
+
+### deploy.lock 防并发
+
+```bash
+LOCK_FILE="/tmp/deploy.lock"
+trap "rm -f $LOCK_FILE" EXIT
+
+if [ -f "$LOCK_FILE" ]; then
+  echo "❌ 部署进行中（PID: $(cat $LOCK_FILE)），请等待完成"
+  exit 1
+fi
+
+echo $$ > "$LOCK_FILE"
+```
+
+### 版本 Tag 强制
+
+```bash
+CURRENT_TAG=$(git describe --exact-match --tags HEAD 2>/dev/null || echo "")
+if [ -z "$CURRENT_TAG" ]; then
+  echo "❌ 当前 commit 没有版本 tag，请先执行："
+  echo "   git tag v$(cat VERSION) && git push --tags"
+  exit 1
+fi
+```
+
+## Layer 2：验证部署正确
+
+### Smoke Test 脚本 (verify.sh)
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+
+HEALTH_URL="${HEALTH_URL:-https://example.com/health}"
+EXPECTED_VERSION=$(cat VERSION)
+MAX_RETRIES=3
+RETRY_INTERVAL=5
+
+for i in $(seq 1 $MAX_RETRIES); do
+  RESPONSE=$(curl -sf --max-time 10 "$HEALTH_URL" 2>/dev/null) && break
+  echo "健康检查失败 ($i/$MAX_RETRIES)，等待 ${RETRY_INTERVAL}s..."
+  sleep $RETRY_INTERVAL
+done
+
+ACTUAL_VERSION=$(echo "$RESPONSE" | python3 -c "import json,sys; print(json.load(sys.stdin)['version'])")
+
+if [ "$ACTUAL_VERSION" != "$EXPECTED_VERSION" ]; then
+  echo "❌ 版本不符！预期 $EXPECTED_VERSION，实际 $ACTUAL_VERSION"
+  exit 1
+fi
+
+echo "✅ 版本验证通过：$ACTUAL_VERSION"
+```
+
+### 健康检查端点规格
+
+应用程序必须提供 `/health` 端点，响应格式：
+
+```json
+{
+  "status": "ok",
+  "version": "1.2.3",
+  "timestamp": "2026-04-26T10:00:00Z"
+}
+```
+
+## Layer 3：快速恢复能力
+
+### Blue-Green 架构
+
+```
+[Nginx]
+  │
+  ├─── Blue (port 3001) ← 稳定版（当前 active）
+  └─── Green (port 3002) ← 新版（部署目标）
+```
+
+**Nginx 配置**：
+
+```nginx
+upstream app {
+  server 127.0.0.1:3001;  # blue
+  # server 127.0.0.1:3002;  # green（切换时启用此行并停用上一行）
+}
+
+server {
+  listen 80;
+  location / {
+    proxy_pass http://app;
+  }
+}
+```
+
+### Rollback 脚本 (rollback.sh)
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+
+CURRENT=$(readlink /app/current)
+if [[ "$CURRENT" == *"green"* ]]; then
+  TARGET="/app/blue"
+else
+  TARGET="/app/green"
+fi
+
+ln -sfn "$TARGET" /app/current
+nginx -s reload
+
+echo "✅ 已切回 $TARGET（$(date -u +%Y-%m-%dT%H:%M:%SZ)）"
+
+# 记录 rollback 事件
+echo "{\"timestamp\":\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\",\"event\":\"rollback\",\"from\":\"$CURRENT\",\"to\":\"$TARGET\",\"operator\":\"$(whoami)\"}" >> /var/log/deployments.jsonl
+```
+
+### 完整 Makefile
+
+```makefile
+.PHONY: deploy rollback verify
+
+deploy:
+	@./deploy.sh
+
+rollback:
+	@./rollback.sh
+
+verify:
+	@./verify.sh
+
+status:
+	@echo "Current: $$(readlink /app/current)"
+	@curl -s $${HEALTH_URL:-http://localhost/health} | python3 -m json.tool
+```
+
+## Deployment Log 格式
+
+每次部署（成功或失败）都必须写入 JSON Lines 格式的日志：
+
+```json
+{"timestamp":"2026-04-26T10:00:00Z","version":"1.2.3","git_commit":"abc1234","operator":"albert","result":"success","duration_seconds":45,"slot":"green"}
+{"timestamp":"2026-04-26T11:30:00Z","version":"1.2.4","git_commit":"def5678","operator":"albert","result":"failure","duration_seconds":12,"slot":"green","error":"version_mismatch"}
+```
+
+## 适用场景
+
+| 场景 | 建议 |
+|------|------|
+| 个人 VPS / 小型项目 | Layer 1 + Layer 2（无需 Blue-Green） |
+| 自架服务器（多人团队） | 三层全套 + deploy.lock |
+| Air-gapped 环境 | 三层全套 + 本地 artifact registry |
+| 容器化部署 | 搭配 `docker compose` 执行 |
+
+## 相关标准
+
+- `deployment-standards.ai.yaml` — 有 CI/CD 平台的部署策略（本文档的补充前提）
+- `health-check-standards.ai.yaml` — /health 端点设计规范
+- `circuit-breaker.ai.yaml` — 断路器集成（进阶场景）
+
+
+**Scope**: universal

package/bundled/locales/zh-CN/core/packaging-standards.md

@@ -1,8 +1,9 @@
 ---
 source: ../../../core/packaging-standards.md
-source_version: 1.0.0
-translation_version: 1.0.0
-last_synced: 2026-04-20
+source_version: 1.1.0
+translation_version: 1.1.0
+last_synced: 2026-06-10
+source_hash: 69ff3afd3c1e
 status: current
 ---
 
@@ -10,8 +11,8 @@ status: current
 
 > **语言**: [English](../../../core/packaging-standards.md) | 简体中文
 
-**版本**: 1.0.0
-**最后更新**: 2026-04-15
+**版本**: 1.1.0
+**最后更新**: 2026-05-26
 **适用性**: 使用 UDS-aware 工具链的项目
 **范围**: 通用 (Universal)
 
@@ -202,12 +203,82 @@ targets:
 
 ---
 
+## 归档格式完整性
+
+当打包步骤生成将被部署脚本使用的归档（`.zip`、`.tar.gz`、`.tar.bz2` 等）时，**真实的二进制格式必须与文件扩展名一致**。命名为 `.zip` 的文件必须是真正的 ZIP 归档（PKZip 魔数 `PK\x03\x04`），而不是改名后的 tar 归档。
+
+> **为何必须：** 格式不匹配的归档会触发下游静默失败。PowerShell 的 `Expand-Archive` 和 `[System.IO.Compression.ZipFile]::ExtractToDirectory()` 会**不抛出任何错误地**接受 tar 改名为 `.zip` 的文件——文件被读取，但什么都不会被解压，且没有任何异常。若部署脚本的下一步是破坏性操作（例如"删除当前安装目录"），则运行中的安装将被销毁而无任何内容可替换。
+
+### 发布前验证
+
+每个生成归档的打包步骤**必须**在声明成功前包含格式验证。最低验证要求：
+
+| 格式 | 验证单行命令 |
+|---|---|
+| `.zip` | `python -c "import zipfile; zipfile.ZipFile('out.zip').namelist()"` 必须成功 |
+| `.zip`（Unix） | `file out.zip` 必须报告 `Zip archive data`，**不得**为 `POSIX tar archive` |
+| `.tar.gz` | `tar -tzf out.tar.gz >/dev/null` 必须成功 |
+| 任意格式 | 可选：对预期文件清单进行哈希比对 |
+
+验证失败必须在发布前终止打包流水线。
+
+### 各平台配置示例
+
+**Windows — 应当使用：**
+
+```powershell
+# 选项 A：PowerShell 内置（生成真正的 ZIP）
+Compress-Archive -Path "publish\*" -DestinationPath "dist\patch.zip" -Force
+
+# 选项 B：.NET API（生成真正的 ZIP）
+Add-Type -Assembly System.IO.Compression.FileSystem
+[System.IO.Compression.ZipFile]::CreateFromDirectory(
+    "publish", "dist\patch.zip", "Optimal", $false
+)
+```
+
+**Windows — 不应使用：**
+
+```bash
+# ❌ git-bash / busybox 的 tar -a -cf 在 Windows 上不可靠
+# -a "按扩展名自动选择格式" 标志会生成带 .zip 扩展名的 POSIX tar 归档。
+# `file patch.zip` → "POSIX tar archive (GNU)"（而非 "Zip archive data"）
+cd publish && tar -a -cf "../dist/patch.zip" api/
+```
+
+**类 Unix 系统 — 应当使用：**
+
+```bash
+# 使用 'zip' 生成 ZIP 归档（BSD/Linux）
+zip -r dist/patch.zip publish/
+
+# 使用 'tar -czf'（不加 -a）生成 tar.gz 归档——明确、确定
+tar -czf dist/patch.tar.gz publish/
+
+# 发布前验证
+file dist/patch.zip            # 期望 "Zip archive data"
+python -c "import zipfile; zipfile.ZipFile('dist/patch.zip').namelist()"
+```
+
+### 消费者侧防御
+
+生产者无法保证消费者会进行验证。消费者（部署脚本）**必须**在任何破坏性操作前验证归档完整性。消费者侧要求参见[部署标准 — 防御性部署排序](deployment-standards.md#防御性部署排序)。
+
+### 失败模式参考（真实事故）
+
+某 Windows IIS 生产部署脚本（2026-05-24）在 git-bash 中使用 `tar -a -cf patch.zip api/` 生成发布归档。消费者侧的 PowerShell 部署脚本随后执行了 `Expand-Archive`（对该 tar 改名文件静默无操作），继续对运行中的 `apiDir` 执行 `Remove-Item -Recurse`，然后从根本不存在的源路径执行 `Copy-Item`（因为什么都没有被解压）。运行中的安装被清空，AppPool 停止，生产环境中断了约 3 分钟，直到基于备份的回滚完成。
+
+（a）生产者使用自动扩展名 tar，（b）消费者未验证解压输出——这两个因素共同造成了运行中的安装被销毁，且整个过程无任何错误被报告。
+
+---
+
 ## 相关标准
 
 - [部署标准](deployment-standards.md) — 打包后的部署阶段
 - [Pipeline 整合标准](pipeline-integration-standards.md) — CI/CD pipeline 配置
 - [Check-in 标准](checkin-standards.md) — 打包前的质量关卡
 - [版本控制标准](versioning.md) — 包产出物使用的版本号
+- [供应链证明标准](supply-chain-attestation.md) — 打包产出物的 SBOM / SLSA 溯源 / 签名（此处的格式完整性属于归档层级；证明则补充了从源码到产出物的溯源）
 
 ---
 
@@ -215,6 +286,7 @@ targets:
 
 | 版本 | 日期 | 变更 |
 |------|------|------|
+| 1.1.0 | 2026-05-26 | 新增：归档格式完整性章节——真实格式必须与扩展名一致的规则、验证单行命令、Windows 配置 DO/DON'T 列表、真实事故参考（XSPEC-231 / 关闭 issue #113） |
 | 1.0.0 | 2026-04-15 | 初始发行 — XSPEC-034 Phase 1 |
 
 ---