From 996123caf5b48e79126b7bbf16bdeb9af9d2a2eb Mon Sep 17 00:00:00 2001
From: DiceFrame Bot <noreply@github.com>
Date: Mon, 17 Aug 2026 02:45:03 +0800
Subject: [PATCH] =?UTF-8?q?docs(plugin):=20=E8=A1=A5=E5=85=85=E8=A7=84?=
 =?UTF-8?q?=E5=88=99=E6=A8=A1=E6=9D=BF=E7=9A=84=20special=5Fstats=20initia?=
 =?UTF-8?q?l=20=E4=B8=8E=E6=8A=80=E8=83=BD=E5=8A=A0=E5=80=BC=E8=A1=A8?=
 =?UTF-8?q?=E8=A7=84=E8=8C=83?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 新增 7.2.2 节（中英文）：说明特殊属性不写 initial 时引擎默认初始化为满值，
  资源池型与进度条型的区别及取值建议；d20 规则技能值需通过 skill_value_to_bonus
  参与检定，并给出 base_d20 参考表；sanity/luck 豁免说明
- 附发布前自检命令 scripts/audit_rules.py --strict
---
 docs/en/plugin-development.md | 40 +++++++++++++++++++++++++++++++++++
 docs/zh/plugin-development.md | 40 +++++++++++++++++++++++++++++++++++
 2 files changed, 80 insertions(+)

diff --git a/docs/en/plugin-development.md b/docs/en/plugin-development.md
index 7a2c435..bbd26e7 100644
--- a/docs/en/plugin-development.md
+++ b/docs/en/plugin-development.md
@@ -344,6 +344,46 @@ The normal path no longer triggers a check from keywords in a player's message.
 
 **Multi-language extension**: vocabularies are data-driven. Adding a language only requires adding keys (such as `ja`) to `aliases` / `skill_candidates` and registering the language suffix in `engine/language.py`. New languages do not pollute other languages.
 
+#### 7.2.2 Special-stat initial values and the skill bonus table
+
+Two numeric fields in a rule template fail silently when omitted. Check both before publishing:
+
+**`special_stats[].initial`**
+
+Every `special_stats` entry should declare `initial` explicitly. Without it, the engine initializes the stat to its maximum (`max`):
+
+- Resource pools (mana, qi, stamina) legitimately start full - write `"initial": <max>` to pin that intent.
+- Progress bars (KPI, mystery progress, danger meters, countdown starts) **must** declare `initial`. If omitted, the character starts with the progress already full - endings meant to trigger at 100 (promotion, collapse, truth reveal) should fire on round one, and GMs typically won't, leaving the game running from a corrupted initial state.
+
+```json
+"special_stats": [
+  {"key": "mana", "name": "Mana", "max": 100, "initial": 100, "description": "Spent on spells, restored by meditation"},
+  {"key": "kpi",  "name": "KPI",  "max": 100, "initial": 42,  "description": "Work progress; reaching 100 triggers the ending"}
+]
+```
+
+`sanity` and `luck` receive dedicated CoC-style initialization from the engine and may omit `initial`.
+
+**`skill_value_to_bonus`**
+
+In d20 rules, skill values only affect checks (`d20 + attribute modifier + skill bonus vs DC`) through this table. Without it the skill bonus is always zero: skill values never change any check result and only inform narration. If skills are a numeric mechanism in your rule, provide the table explicitly or `"extends": "base_d20"` to inherit the built-in default:
+
+```json
+"skill_value_to_bonus": {"20": 1, "40": 2, "60": 3, "80": 4}
+```
+
+- d100 rules (CoC-style): the skill value itself is the success chance; this table is not used.
+- `dice_system: "none"` narrative-only rules have no checks and do not need it.
+- Keeping skills purely narrative is a valid design; in that case omit the table on purpose.
+
+**Self-check**: the DiceFrame main repository ships an audit script. Run it over your rule files before publishing:
+
+```bash
+python scripts/audit_rules.py --strict
+```
+
+Missing `initial` or a missing skill bonus table surface as warnings (advisory by default, failures under `--strict`).
+
 ### 7.3 Themes
 
 Themes register JSON through `contributes.theme` or `contributes.themes`. Only theme contract v2 is supported; themes without `"schema_version": 2` are ignored and legacy variables are not mapped.
diff --git a/docs/zh/plugin-development.md b/docs/zh/plugin-development.md
index 043c51f..c56f25c 100644
--- a/docs/zh/plugin-development.md
+++ b/docs/zh/plugin-development.md
@@ -471,6 +471,46 @@ content/
 
 **多语言扩展**：词表是数据驱动的，加语言只需给 `aliases` / `skill_candidates` 增加对应语言键（如 `ja`），并保证 `engine/language.py` 登记了该语言后缀。新增语言不会污染其他语言场景。
 
+#### 7.2.2 特殊属性起点与技能加值表
+
+规则模板里有两个数值字段缺省时不会报错，但会让数值机制静默失效。发布前请逐项确认：
+
+**`special_stats[].initial`（特殊属性初始值）**
+
+`special_stats` 的每个条目都建议显式写 `initial`。不写时引擎会把该属性初始化为满值（`max`）：
+
+- 资源池型属性（魔力、内力、体力）开局满值是合理的，写 `"initial": <max>` 把意图固化即可。
+- 进度条型属性（KPI、谜团进度、危险度、倒计时起点）**必须**显式写 `initial`。漏写会让角色开局就处于"进度已满"状态--本应到 100 才触发的结局（转正、猝死、真相揭示）在第一轮就该发生，而 GM 往往不会执行，游戏从此带着损坏的初始状态运行。
+
+```json
+"special_stats": [
+  {"key": "mana", "name": "魔力", "max": 100, "initial": 100, "description": "施法消耗，冥想恢复"},
+  {"key": "kpi",  "name": "KPI",  "max": 100, "initial": 42,  "description": "业绩进度，满 100 触发转正结局"}
+]
+```
+
+理智（`sanity`）与幸运（`luck`）由引擎按 CoC 规则专门初始化，可不写 `initial`。
+
+**`skill_value_to_bonus`（技能加值表）**
+
+d20 规则中，技能值只有通过这张表才参与检定（`d20 + 属性修正 + 技能加值 vs DC`）。不提供此表时技能加值恒为 0：玩家分配的技能值高低不影响任何检定结果，只影响叙事。如果技能在你的规则里是数值机制的一部分，请显式提供加值表，或 `"extends": "base_d20"` 继承内置默认表：
+
+```json
+"skill_value_to_bonus": {"20": 1, "40": 2, "60": 3, "80": 4}
+```
+
+- d100 规则（CoC 系）技能值本身就是成功率，不需要此表。
+- `dice_system: "none"` 的纯叙事规则没有检定，不需要此表。
+- 刻意让技能保持纯叙事也是合法设计，此时无需配置。
+
+**自检**：DiceFrame 主仓库提供规则审计脚本，发布内容包前可对规则文件跑一遍：
+
+```bash
+python scripts/audit_rules.py --strict
+```
+
+缺少 `initial` 或技能加值表会以警告形式列出（默认不拦截，`--strict` 时视为失败），用于发布前自查。
+
 ### 7.3 主题插件
 
 主题插件是声明型插件，适用于色板、字体、圆角和阴影。当前只支持主题契约 v2；未声明 `"schema_version": 2` 的旧主题不会被加载，也不会进行旧变量映射。