universal-dev-standards 5.17.0 → 6.1.0

package/bundled/locales/zh-CN/core/license-compliance.md

@@ -0,0 +1,131 @@
+---
+source: ../../../core/license-compliance.md
+source_version: 2.1.0
+translation_version: 2.1.0
+last_synced: 2026-06-10
+source_hash: 8ac1763bd1a1
+status: current
+---
+
+# 许可证合规标准
+
+> **语言**: [English](../../../core/license-compliance.md) | [繁體中文](../../zh-TW/core/license-compliance.md) | 简体中文
+
+> **版本**: 2.1.0 | **状态**: Active | **更新日期**: 2026-05-16
+> **AI 优化版本**: `ai/standards/license-compliance.ai.yaml`
+> **Agent Spec**: ASPEC-001 (cross-project/aspec/ASPEC-001-license-compliance-agent.md)
+
+**Scope**: universal
+
+## 概述
+
+面向 AI 增强开发的完整许可证合规标准，涵盖通用 OSS 实践（Tier 1）以及针对 AI 生成代码的 AI 专属规则（Tier 2）。
+
+## Tier 1 — 通用 OSS 合规实践
+
+适用于所有项目，无论是否使用 AI。
+
+| ID | 规则 | 级别 |
+|----|------|------|
+| REQ-001 | 许可证分类与允许列表（allowlist） | MUST |
+| REQ-002 | CI 中的自动化许可证扫描 | MUST |
+| REQ-003 | SBOM 生成（CycloneDX 1.5 或 SPDX 2.3） | MUST |
+| REQ-004 | 许可证署名与 NOTICES 文件 | MUST |
+| REQ-005 | 许可证违规整改（5 个工作日） | MUST |
+| REQ-006 | 采用新技术时的许可证评审 | SHOULD |
+
+### 许可证分级
+
+| 分级 | 许可证 | 动作 |
+|------|--------|------|
+| APPROVED | MIT, Apache 2.0, BSD-2/3-Clause, ISC, CC0 | 自动批准 |
+| REVIEW-REQUIRED | LGPL-2.1/3.0, MPL-2.0, CDDL | 采用前须法务评审 |
+| PROHIBITED | GPL-2.0/3.0, AGPL-3.0, SSPL-1.0, BUSL-1.1 | 立即阻断 PR |
+
+## Tier 2 — AI 专属规则
+
+对生成代码的 AI Agent（VibeOps Generator Agent 及同等者）具有约束力。
+
+| ID | 规则 | 严重度 |
+|----|------|--------|
+| LC-001 | 必须查询 SPDX ID | Blocking |
+| LC-002 | 阻止列表（blocklist）自动阻断 | Blocking |
+| LC-003 | 允许列表（allowlist）自动批准 | Informational |
+| LC-004 | 灰名单（greylist）人工评审 | Review required |
+| LC-005 | SBOM 强制生成 | Blocking |
+| LC-006 | 版权相似度阈值（≥0.85 阻断） | Blocking |
+| LC-007 | PII 模式检测 | Review required |
+| LC-008 | EU AI Act 透明度标记 | Blocking |
+| LC-009 | 客户策略上限 | Informational |
+
+## v2.1.0 增强（XSPEC-193 Phase 2）
+
+### ClearlyDefined API（LC-001）
+
+- 主要许可证查询来源：`https://api.clearlydefined.io/definitions/{type}/{provider}/{namespace}/{name}/{revision}`
+- 知名包的置信度 ≥ 0.95（score.total ≥ 80）
+- 24h TTL LRU 缓存（cap=500）+ 404 negative cache
+- Token bucket：10 req/s，burst 20
+- 重试策略：5xx → exponential backoff × 3（200ms/1s/3s）；429 → batch fallback
+- DEC-064 缓存键隔离：`sha256(client_salt + ':' + purl)`
+
+### AST PII 分析（LC-007）
+
+- Tree-sitter 支持：TypeScript、JavaScript、Python
+- 上下文分类：
+  - `hardcoded_value` → 严重度升级为 `critical`
+  - `comment` → 严重度降级为 `info`
+  - `schema_field` → 加注，严重度不变
+- `// pii:ignore` pragma：抑制同一行的发现
+- 可选字段：`PIIPattern.confidence`、`PIIPattern.ast_context`
+- tree-sitter 不可用时优雅降级（graceful fallback）为 regex
+
+### EmbeddingProvider 策略（LC-006）
+
+- `provider='onnx-minilm'`：ONNX 本地推理（all-MiniLM-L6-v2）
+- `provider='ollama-bge-m3'`：Ollama 本地 API（localhost:11434）
+- `provider='jaccard'`：Jaccard token 相似度（Phase 1 基线，默认）
+- 内存中的 snippet 索引（`buildSnippetIndex()`）按客户隔离（DEC-064 salt）
+- 外部搜索：通过 `enableExternalSearch=true` opt-in（默认=false）
+
+## 原则
+
+| ID | 原则 |
+|----|------|
+| P-1 | SPDX 优先 — 所有许可证 ID 必须是 SPDX 标准 |
+| P-2 | 独立评估者 — 与 Generator 使用不同的模型类别 |
+| P-3 | 证据导向决策 — 每个阻断都附带可追溯的证据 |
+| P-4 | 默认透明 — 必须有 EU AI Act Article 50 标记 |
+| P-5 | 客户主权 — 策略可在 EULA §9 限制内定制 |
+
+## 工具序列（XSPEC-193 §2）
+
+```
+1. dependency_reader
+2. license_lookup         ← ClearlyDefined API (v2.1.0)
+3. license_blocklist_check
+4. sbom_generator
+5. pii_pattern_detector   ← AST-enhanced (v2.1.0)
+6. copyright_similarity_check ← EmbeddingProvider (v2.1.0)
+7. eu_ai_act_classifier
+8. transparency_marker
+9. block_pr
+10. suggest_alternative
+11. escalate_to_human
+```
+
+## 相关规格
+
+- XSPEC-193 — License Compliance Agent 完整规格
+- XSPEC-066 — Wave 3 Compliance Pack（v1.0.0 基线）
+- DEC-063 — VibeOps 法务与合规策略
+- DEC-064 — 客户 IP 隔离（cache salt）
+- ASPEC-001 — License Compliance Agent SPEC（XSPEC-205 §REQ-2 格式）
+
+## 变更记录
+
+| 版本 | 日期 | 变更 |
+|------|------|------|
+| v1.0.0 | 2026-04-30 | 初版 — REQ-001~006 通用 OSS 实践 |
+| v2.0.0 | 2026-05-14 | 新增 Tier 2 LC-001~009 AI 专属规则 |
+| v2.1.0 | 2026-05-16 | ClearlyDefined API + AST PII + EmbeddingProvider + ASPEC-001 引用 |

package/bundled/locales/zh-CN/core/llm-output-validation.md

@@ -0,0 +1,192 @@
+---
+source: ../../../core/llm-output-validation.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2026-06-10
+source_hash: 8b7fc8543760
+status: current
+---
+
+# LLM 输出验证标准
+
+> **语言**: [English](../../../core/llm-output-validation.md) | [繁體中文](../../zh-TW/core/llm-output-validation.md) | 简体中文
+
+> 标准 ID：`llm-output-validation`
+> 版本：v1.0.0
+> 最后更新：2026-05-05
+
+---
+
+## 为什么需要 LLM 输出验证？
+
+LLM 输出具有**不确定性**：同一个 prompt 在不同时间、不同模型版本下可能产生格式不一致的输出。如果不加以验证，这些输出可能在下游管线中造成静默失败（silent failure）——不是报错，而是用了一个错误的默认值或 `undefined`。
+
+LLM 输出验证包含三个层次：
+
+| 层次 | 问题 | 工具 |
+|------|------|------|
+| 结构验证 | 输出格式是否正确？ | JSON Schema、Zod、Pydantic |
+| 语义验证 | 声称的事实是否有依据？ | NLI probe、Grounding check |
+| 行为验证 | Agent 是否正确拒绝越界请求？ | 红队语料库、拒绝评估 |
+
+---
+
+## 一、Schema Contract Test（结构验证）
+
+### 核心概念
+
+每个 AI Agent 应声明一份 `output-schema.json`（JSON Schema 格式），并提供对应的 contract test。
+
+**Contract test 的目的**：
+- 确认 schema 本身是合法的 JSON Schema
+- 确认 valid fixtures 通过验证
+- 确认 invalid fixtures（缺少必填字段、类型错误、enum 违规）被拒绝
+
+### 推荐目录结构
+
+```
+agents/<agent-name>/
+  output-schema.json       ← JSON Schema 定義
+  __tests__/
+    contract.test.ts       ← Contract test suite
+  __fixtures__/
+    valid.json             ← 真實 LLM 輸出 golden fixture
+    invalid-missing-id.json ← 缺少必填欄位的 fixture
+```
+
+### TypeScript 示例（使用 Ajv）
+
+```typescript
+import Ajv from "ajv"
+import schema from "../output-schema.json"
+import validFixture from "../__fixtures__/valid.json"
+
+const ajv = new Ajv({ strict: false })
+const validate = ajv.compile(schema)
+
+// 測試 1：Schema 本身是合法的 JSON Schema
+it("schema is valid JSON Schema", () => {
+  expect(ajv.validateSchema(schema)).toBe(true)
+})
+
+// 測試 2：Valid fixture 通過驗證
+it("valid fixture passes schema", () => {
+  expect(validate(validFixture)).toBe(true)
+})
+
+// 測試 3：空 object 被拒絕
+it("empty object is rejected", () => {
+  expect(validate({})).toBe(false)
+})
+
+// 測試 4：缺少 source_agent 被拒絕
+it("object missing source_agent is rejected", () => {
+  const { source_agent, ...without } = validFixture
+  expect(validate(without)).toBe(false)
+})
+```
+
+### Python 示例（使用 Pydantic）
+
+```python
+from pydantic import ValidationError
+from your_module import AgentOutput
+
+# 測試 valid fixture
+valid_data = { "version": "1.0.0", "source_agent": "planner", ... }
+output = AgentOutput(**valid_data)  # 不拋出 exception
+
+# 測試 invalid fixture
+try:
+    AgentOutput(version="bad-format", source_agent="planner")
+    assert False, "Should have raised"
+except ValidationError:
+    pass  # 預期行為
+```
+
+---
+
+## 二、幻觉检测（Semantic Validation）
+
+### 什么是幻觉？
+
+LLM 产生「听起来正确但实际上没有依据」的内容。例如：
+- 虚构的 API 文档 URL
+- 不存在的数据库字段名称
+- 未在 context 中出现的 dependency 版本
+
+### 检测策略
+
+| 策略 | 适用场景 | 自动化程度 |
+|------|---------|-----------|
+| **Schema 结构化输出** | Agent 输出 JSON，enum 限制可能值 | 高（自动） |
+| **Grounding Check** | RAG 系统，回答需引用 context | 中（需 NLI 模型） |
+| **置信度标记** | Agent 在输出中包含 `confidence` 分数 | 中（需 prompt 设计） |
+| **红队语料库** | 主动测试越界请求的拒绝行为 | 高（自动） |
+
+### 幻觉率目标
+
+| Agent 类型 | Schema 合规率 | 事实幻觉率 |
+|-----------|-------------|----------|
+| 结构化 JSON Agent | ≥ 99% | ≤ 5% |
+| RAG Agent | ≥ 95% | ≤ 5% |
+| 对话 Agent | ≥ 90% | ≤ 10% |
+
+---
+
+## 三、Prompt 回归测试
+
+### 何时需要跑 Prompt 回归测试？
+
+- 修改任何 `agents/*/prompt.md`
+- 模型版本升级（相同 prompt，不同 model）
+- Schema 新增 required field
+
+### 回归测试流程
+
+```bash
+# 1. 修改前：用 temperature=0 記錄 golden output
+ai-agent run planner --input fixtures/planner-input.json --temp 0 > golden.json
+
+# 2. 修改後：重跑並比對
+ai-agent run planner --input fixtures/planner-input.json --temp 0 > after.json
+
+# 3. 用 contract test 驗證 after.json 仍符合 schema
+npx vitest run agents/__tests__/contract.test.ts
+```
+
+---
+
+## 四、质量门禁（Quality Gates）
+
+| 门禁 | 阈值 | 强制程度 |
+|------|------|---------|
+| Schema 合规（CI） | 100% | Block merge |
+| 空 object 拒绝（CI）| 100% | Block merge |
+| Prompt 修改后回归（CI）| schema 合规维持 | Block merge |
+| 幻觉率（pre-release）| ≤ 5% | Advisory |
+
+---
+
+## 五、工具推荐
+
+| 工具 | 语言 | 用途 |
+|------|------|------|
+| [Ajv](https://ajv.js.org/) | TypeScript/JS | JSON Schema contract test |
+| [Zod](https://zod.dev/) | TypeScript | Runtime type validation |
+| [Pydantic](https://docs.pydantic.dev/) | Python | Schema + type validation |
+| [DeepEval](https://deepeval.com/) | Python | LLM 幻觉率、faithfulness 评分 |
+| [Ragas](https://docs.ragas.io/) | Python | RAG grounded answer rate |
+
+---
+
+## 参考标准
+
+- NIST AI RMF (AI 100-1, 2023) — AI 风险管理框架
+- OWASP Top 10 for LLM Applications v1.1 — LLM01: Prompt Injection
+- ISO/IEC 42001:2023 — AI 管理体系
+- [UDS `security-testing.ai.yaml`](../../../core/security-testing.md) — SAST + DAST 集成
+- [UDS `adversarial-test.ai.yaml`](../../../core/adversarial-test.md) — Prompt injection 红队标准
+
+
+**Scope**: universal

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

@@ -1,18 +1,22 @@
 ---
 source: ../../../core/logging-standards.md
-source_version: 1.2.0
-translation_version: 1.2.0
-last_synced: 2026-01-24
+source_version: 1.4.0
+translation_version: 1.4.0
+last_synced: 2026-07-08
+source_hash: 732277ef939f
 status: current
 ---
 
-> **语言**: [English](../../../core/logging-standards.md) | [简体中文](../../zh-TW/core/logging-standards.md) | 简体中文
+> **语言**: [English](../../../core/logging-standards.md) | 简体中文
 
 # 日志标准
 
-**版本**: 1.0.0
-**最后更新**: 2025-12-30
-**适用范围**: 所有需要日志记录的应用程序
+**版本**: 1.4.0
+**最后更新**: 2026-06-17
+**适用范围**: 所有软件项目
+**范围**: universal
+**行业标准**: RFC 5424, OpenTelemetry, W3C Trace Context
+**参考**: [opentelemetry.io](https://opentelemetry.io/)
 
 ---
 
@@ -20,6 +24,81 @@ status: current
 
 本标准定义日志记录的最佳实践，确保日志的一致性、结构化和可操作性。
 
+## 强制事件（Mandatory Events）
+
+> **关闭** UDS issue [#108](https://github.com/AsiaOstrich/universal-dev-standards/issues/108)（XSPEC-234）。本标准其余部分定义**如何**写一条日志（级别／字段／PII 脱敏／轮转）；本节定义**何时必须写**——把「格式合规但实质沉默」的日志排除在外。
+
+遵守所有格式规则、却**在关键时刻从不触发**的日志比没有日志还糟：它在事故发生时给人一种虚假的安全感。以下事件是**必须**写日志的 canonical 时机，每项声明 `when`／`must_log`／`must_NOT_log`／`level`／`rationale`。
+
+### 为何需要（真实事故）
+
+某次 PHP→.NET 迁移耗费 2 天诊断「发送失败、没有日志」，原因是**四层全部沉默**：
+
+1. **负载均衡器将后端标记为 DOWN**（503）——health probe 超时；后端只记录了 probe 噪音，零业务事件。
+2. **框架验证 reject**（如 ModelState／DTO 501）——校验框架在任何 handler 执行前就返回，**payload 从未被记录**。
+3. **认证失败**只记录了「Account or password error」——**无 uid、无 source IP** → 无法排查。
+4. **后台 worker 仍存活，但日志文件 0 字节**——没有机制检测到这种沉默。
+
+以上都无法仅靠格式规则捕捉，强制事件补上这一缺口。
+
+### 类目（9 个 canonical 事件）
+
+| id | when（时机） | level | 核心必填字段（`must_log`） | `must_NOT_log` |
+|----|------|-------|-----------------------------------|----------------|
+| `application_startup` | 进程启动后、**接受请求前** | INFO | app_name, version, git_sha, environment, hostname, pid, listening_endpoints | secrets、完整连接字符串 |
+| `request_received` | HTTP 中间件首次看到请求 | INFO / DEBUG | method, path, source_ip, request_id | request body、auth headers |
+| `validation_failure` | schema / ModelState / DTO 验证被拒绝 | WARN | request_id, path, missing_fields[], payload_shape（仅字段名） | 字段**值**、PII |
+| `authentication_failure` | 登录 / token 校验失败 | WARN | uid（尝试值）, source_ip, failure_reason | password、token 值 |
+| `outbound_call_start` | 发起对外 HTTP/RPC 调用 | INFO | target_url（host+path）, request_id propagated, timeout_ms | credentials、bearer token |
+| `outbound_call_complete` | 外部调用返回或失败 | INFO / WARN / ERROR | status_code **或** failure_phase（dns/tcp/tls/http）, elapsed_ms, retries | 含 PII 的 response body |
+| `business_event` | 状态变更类业务操作完成 | INFO | operation_name, actor, target ids, outcome | 完整 record payload、PII |
+| `heartbeat` | 长时间运行的后台服务，≥ 1 次 / 60 秒 | INFO | service_name, queue_depth, items_processed_since_last_heartbeat | — |
+| `shutdown` | 进程退出（正常或致命） | INFO / ERROR | app_name, signal/reason, uptime_seconds, pending_work_count | — |
+
+每个事件的 `rationale` 都对应一个真实失效模式：`validation_failure` ⇒ 事故 #2（payload 未记录）；`authentication_failure` 字段要求 ⇒ 事故 #3（无 uid/IP）；`heartbeat` + 沉默检测 ⇒ 事故 #4（0 字节日志）；`application_startup`/`shutdown` ⇒ 生命周期盲区；`outbound_call_*` ⇒「发送失败」却查不到调用痕迹。
+
+### 场景
+
+#### 场景：验证失败必须产生日志
+
+- **GIVEN** API 端点收到缺少 `[Required]` 字段的 payload
+- **WHEN** 框架在 handler 执行前自动 reject（如 400/501）
+- **THEN** 必须写一条 WARN 日志，包含 `request_id`、`path`、`missing_fields[]`、`payload_shape`（仅字段名）
+- **AND** 事后复盘可直接从日志重建失败原因
+
+#### 场景：后台服务必须心跳（heartbeat）
+
+- **GIVEN** worker 进程正在运行
+- **WHEN** 60 秒内没有写入任何 INFO/WARN/ERROR
+- **THEN** 必须写一条 `heartbeat` 日志，包含当前 queue depth 与自上次心跳以来的处理量
+- **AND** 若连续 ≥ 2 倍心跳间隔（≥ 120 秒）未出现心跳，沉默检测器必须告警
+
+### Compliant startup log 示例
+
+```json
+{
+  "timestamp": "2026-06-17T08:00:00.000Z",
+  "level": "INFO",
+  "message": "application_startup",
+  "event": "application_startup",
+  "app_name": "payment-service",
+  "version": "2.3.1",
+  "git_sha": "a1b2c3d",
+  "environment": "production",
+  "hostname": "pod-abc123",
+  "pid": 4711,
+  "listening_endpoints": ["0.0.0.0:8080", "0.0.0.0:9090/metrics"]
+}
+```
+
+### 后续规则
+
+1. **访问日志分离**——health probe／liveness 流量不得污染业务事件日志。将 probe 路由至独立 sink／文件，避免其淹没或轮转掉业务事件（见事故 #1）。
+2. **日志沉默检测 SLA**——服务应在连续 N 分钟无事件时告警，N ≤ 2 × `heartbeat` 间隔。缺少预期日志本身就是一种可告警条件（参见下方「Absence of Expected Logs」告警模式）。
+3. **面向运维的日志可发现性**——返回给客户端的错误响应应携带 `request_id`，以便支持人员将用户报告的故障对应到后端日志，无需为查日志来回沟通。
+
+> **交叉引用**：`heartbeat`／沉默检测与[日志文件轮转策略](#日志文件轮转策略)互补（0 字节／静默丢弃的日志是同一盲区的两个方向），并与 migration-assistant 的后台任务／副作用完整性互补（这些事件即是可观测的「已触发」证据）。
+
 ---
 
 ## 日志级别
@@ -311,6 +390,123 @@ tracestate: vendor=value
 - [ ] 永不记录信用卡
 - [ ] 已配置保留策略
 
+### 轮转检查清单
+
+- [ ] 已设置时间轮转（`rollingInterval: Day` 或同等配置）
+- [ ] 已设置大小轮转，`rollOnFileSizeLimit: true`（或同等配置）
+- [ ] 已显式配置 `fileSizeLimitBytes`（默认上限会造成危害）
+- [ ] `retainedFileCountLimit` ≥ N×7，以覆盖窗口内的轮转文件
+- [ ] 已定义 90% 大小 SOP：调查噪声根因，不要盲目提高上限
+
+---
+
+## 日志文件轮转策略
+
+### 轮转策略——必须同时设置两者
+
+基于文件的日志接收器配置**必须**包含**两个**触发器：
+
+1. **基于时间的轮转**（`rollingInterval: Day` 或同等配置）——按时间分区
+2. **基于大小的轮转**，`rollOnFileSizeLimit: true`（或同等配置）——应对流量峰值
+
+> **为何必须：** 大多数日志库默认带有静默的大小上限。当文件达到上限时，后续的日志写入会被**静默丢弃**——无任何警告或错误提示。应用程序继续运行，而半天的日志就此消失。同时显式设置两个触发器可避开这个陷阱。
+
+### 生产环境中的默认上限危害
+
+| 库 | 默认大小上限 | 达到上限时的行为 |
+|---|---|---|
+| Serilog File sink (.NET) | 1 GB | **静默停止写入**（`RollOnFileSizeLimit = false` 为默认值） |
+| log4j RollingFileAppender | 未设置则无上限 | 同上——不轮转即丢弃 |
+| Python `RotatingFileHandler` | 未设置 `maxBytes` 则无限 | 无限增长 |
+| Winston `winston-daily-rotate-file` | 未设置 `maxSize` 则无上限 | 同上——不轮转即丢弃 |
+
+若未显式配置基于大小的轮转，即是接受上述某种失败模式。
+
+### 推荐初始值
+
+| 参数 | 取值 | 说明 |
+|---|---|---|
+| `fileSizeLimitBytes` | 100 MB | 平衡：足够小以便编辑器打开，足够大以避免过多轮转 |
+| `rollOnFileSizeLimit` | `true` | 达到上限时创建 `*-001.txt`、`*-002.txt`；**不要**丢弃 |
+| `retainedFileCountLimit` | ≥ N×7（N = 每天最大预期轮转次数） | 避免过早删除窗口内的日志 |
+
+### 各语言配置示例
+
+**.NET / Serilog**（`appsettings.json`）：
+
+```json
+{
+  "Serilog": {
+    "WriteTo": [{
+      "Name": "File",
+      "Args": {
+        "path": "logs/app-.txt",
+        "rollingInterval": "Day",
+        "fileSizeLimitBytes": 104857600,
+        "rollOnFileSizeLimit": true,
+        "retainedFileCountLimit": 90
+      }
+    }]
+  }
+}
+```
+
+**Python**（`logging.handlers`）：
+
+```python
+from logging.handlers import RotatingFileHandler
+
+handler = RotatingFileHandler(
+    filename="logs/app.log",
+    maxBytes=104857600,   # 100 MB
+    backupCount=90        # 低基数时约保留 3 个月的轮转文件
+)
+# 如需时间+大小组合轮转，可组合使用 TimedRotatingFileHandler 并检查大小，
+# 或使用第三方库如 concurrent-log-handler。
+```
+
+**Java / log4j2**（`log4j2.xml`）：
+
+```xml
+<RollingFile name="App" fileName="logs/app.log"
+             filePattern="logs/app-%d{yyyy-MM-dd}-%i.log.gz">
+  <PatternLayout pattern="%d %-5p %c{1.} - %m%n"/>
+  <Policies>
+    <TimeBasedTriggeringPolicy interval="1"/>
+    <SizeBasedTriggeringPolicy size="100 MB"/>
+  </Policies>
+  <DefaultRolloverStrategy max="90"/>
+</RollingFile>
+```
+
+**Node / Winston**（`winston-daily-rotate-file`）：
+
+```javascript
+import DailyRotateFile from "winston-daily-rotate-file";
+
+new DailyRotateFile({
+  filename: "logs/app-%DATE%.log",
+  datePattern: "YYYY-MM-DD",
+  maxSize: "100m",
+  maxFiles: "90d"
+});
+```
+
+### 运营 SOP——调查根因，不要仅提高上限
+
+若日志文件大小在预计当天结束时达到 `fileSizeLimitBytes` 的 ≥ 90%，**在提高上限之前先调查原因**。典型根因：
+
+- 在 INFO 级别记录每次重试的嘈杂重试循环（应改为 WARN 摘要）
+- 意外在生产环境启用的无限制 debug 日志
+- 单个上游故障引发的堆栈跟踪洪流
+- 健康探针 / sidecar 污染业务日志
+
+提高上限只会掩盖底层噪声问题，并将下一次故障推迟到更远的未来。
+
+### 失败模式参考（真实事故）
+
+某生产 .NET Worker 仅使用 `rollingInterval: Day`（未设置大小限制，Serilog 默认 1 GB 上限），在 07:31 触达上限后静默丢弃了所有日志条目，直到 13:00+ 运维人员发现日志尾部已停止更新。连续 5 个日志文件均显示 `~1,073,741,8XX 字节`（= 1 GiB，Serilog 默认值）。半天的生产诊断数据就此丢失。同时设置 `fileSizeLimitBytes` 和 `rollOnFileSizeLimit: true` 本可在保留所有事件的情况下将文件轮转为 `worker-YYYYMMDD_001.txt`。
+
 ---
 
 ## 相关标准
@@ -324,6 +520,8 @@ tracestate: vendor=value
 
 | 版本 | 日期 | 变更 |
 |-----|------|------|
+| 1.4.0 | 2026-06-17 | 新增：强制事件类目——9 个 canonical「何时必须写日志」事件（when/must_log/must_NOT_log/level/rationale）、验证失败 + heartbeat 场景、compliant startup 示例、后续规则（访问日志分离、沉默检测 SLA、request_id 可发现性）（XSPEC-234 / 关闭 issue #108） |
+| 1.3.0 | 2026-05-26 | 新增：日志文件轮转策略——强制双触发器（时间 + 大小）轮转，含默认上限危害警告、各语言（.NET/Python/Java/Node）配置示例、运营 SOP（XSPEC-232 / 关闭 issue #111） |
 | 1.2.0 | 2026-01-24 | 新增：OpenTelemetry 语义规范、可观测性三支柱整合、基于日志的告警、进阶关联模式 |
 | 1.1.0 | 2026-01-05 | 新增：参考标准章节，包含 OWASP、RFC 5424、OpenTelemetry 和 12 Factor App |
 | 1.0.0 | 2025-12-30 | 初始日志标准 |