# 变量设计与更新规则

## meta

```meta
name: 变量设计与更新规则
id: variable-design
artifact: 设计.变量设计与更新规则
declaration: >
  定义必须跨轮保存的最少真值、合法更新条件、权限与派生映射，供程序选择简单状态工具或复杂维护副 Worker。
when: |
  某项状态若不持久保存，就会导致数值、阶段、资源、门控或已发生事实跨轮漂移时使用。
when_not: |
  状态只需从最近正文理解、无需查询或门控 → 不使用。
  节点与连接构成的地图、关系或路径 → 拓扑图谱。
  大段设定或同类对象合同 → 舞台骨架 / 生成规则。
boundary: |
  本能力定义什么是真值、什么事实允许它改变，以及改变后的约束；不决定 API 投递方式。
  少量简单变量由程序生成主世界层状态工具；复杂变量与拓扑等由维护合同编译工具汇总。
  变量控制上下文负责详细可见范围；正文组成负责展示。本能力不写隐藏段、正则、maintain 包或界面格式。
feeds: gm,auditor
```

## opening

```opening
说说哪些状态必须跨轮准确记住，以及什么已经发生的事实才能让它们改变。只列不保存就会出错的真值；临时描写不用变量化。
```

## task

```task
为本局定义跨轮真值及其更新规则，写入 `设计.变量设计与更新规则`。先做必要性检验，再为每个真值写稳定 id、类型、初始化要求、公开性、允许写入者、允许操作、范围和基于事实的更新规则。

区分两类判断：
- `deterministic`：程序能从明确指令、公式或工具结果直接计算。
- `narrative_inference`：必须结合本轮正文中已经成立的事实判断；须写证据要求，不能凭倾向猜测。

若真值只用于选择分档文本或实例切片，保存真值并引用映射来源，不把派生结果建立成第二个可写真值。若跨越阈值会触发一次性或边沿效果，写成触发规则。

最后根据变量数量、相互依赖、判断方式和触发复杂度给出维护复杂度事实，供程序选择 `none / inline_tool / inline_structured / auditor_bundle`；这是建议，不绑定 API 能力。

材料足够便直接成稿；真正会改变变量合同的缺口交给 `self_score.gap`。产物正文不放评分、诊断、追问或开放问题。
```

## principles

```principles
1. 承重才立真值：必须可查询、计算、门控或防止重复；仅为描写方便的状态不落库。
2. 字段不多不少且互不重叠。余额与存款只留一个；由好感推得的态度档不另设可写字段。
3. 更新规则以已发生事实为证据，写清条件、操作和边界。模型可以判断事实，程序负责校验与提交。
4. 类型决定操作：number/integer 可 `set|delta`；enum/string/boolean 可 `set`；set 可 `add|remove`。不用散文值绕过类型。
5. 公开性只区分用户可见与隐藏；更细的主世界层、转述、旁观投影交给变量控制上下文。
6. 阈值映射只保存引用和选取条件；长文内容仍在生成规则/具体实例中。
7. 维护复杂度按实际依赖判断，不机械按数量：一个简单余额可走 inline tool；一个可扩展关系图不属于简单变量。
8. 不在正文中设计隐藏标签、正则或维护 JSON；投递方式由程序根据 API 能力选择。
```

## probe

```probe
每轮 1～2 点。优先确认不保存会出什么错、变量类型与初值、哪些已成立事实允许更新，以及更新是程序可确定还是需要正文推断。
```

## output

```output
{
  "schema": "context-fragment.v1",
  "技能": "变量设计与更新规则",
  "brief": "一句话说明必须记住哪些真值，以及更新判断的复杂度",
  "mount": ["world-simulator", "auditor"],
  "稳变": "stable",
  "正文": {
    "真值": [
      {
        "id": "稳定安全 id",
        "名称": "用户可读名称",
        "用途": "不保存它会造成什么跨轮错误",
        "类型": "number|integer|enum|string|boolean|set",
        "初始化": {
          "默认值": 0,
          "开场确定规则": "开场可覆盖默认值时写条件；否则写固定"
        },
        "公开性": "public|hidden",
        "允许写入者": ["从 program|gm_tool|auditor|user 中选择实际允许项"],
        "允许操作": ["按类型从 set|delta|add|remove 中选择"],
        "约束": {
          "最小值": 0,
          "最大值": 100,
          "枚举值": [],
          "其它不变量": []
        },
        "更新规则": [
          {
            "当": "什么已发生事实允许更新",
            "判断方式": "deterministic|narrative_inference",
            "证据要求": "程序输入或正文中必须能指出什么",
            "操作": "set|delta|add|remove",
            "值规则": "固定值、公式或允许的推断范围",
            "时机": "pre_narrative|post_narrative"
          }
        ]
      }
    ],
    "派生映射": [
      {
        "id": "稳定映射 id",
        "用途": "真值变化后选择什么只读切片",
        "依据变量": ["变量 id"],
        "选取规则": "区间、枚举匹配或组合条件",
        "来源": {
          "规则名": "设计.生成规则#中文规则名；无则省略",
          "名称": "设计.具体实例#中文名；无则省略"
        },
        "读取字段": ["需要投影的摘要字段"]
      }
    ],
    "触发规则": [
      {
        "id": "稳定触发 id",
        "条件": {
          "变量": "变量 id",
          "比较": "eq|neq|gte|lte|gt|lt|changed",
          "值": 0
        },
        "模式": "once|every_edge",
        "action": {
          "类型": "project_mapping|write_memo|queue_generation",
          "目标": "映射 id、备忘录 id 或规则 id",
          "要求": "触发后程序应做什么"
        }
      }
    ],
    "维护复杂度": {
      "建议": "inline_tool|auditor_bundle",
      "依据": [
        "变量数量、交叉依赖、narrative_inference、触发规则与其它可变产物"
      ],
      "可合并更新": [
        "必须原子提交的一组变量 id；无则空数组"
      ]
    }
  }
}
```

硬规则：
1. 输出合法 JSON；每个真值必须有稳定 `id`、用途、类型、初始化、权限、操作、约束和更新规则。
2. 类型与允许操作必须相容；number/integer 的边界、enum 的枚举值必须明确；不适用的约束字段省略。
3. `narrative_inference` 必须写证据要求；正文没有该证据时不更新。
4. 派生映射与触发规则可为空；存在时必须引用已声明变量，且派生结果不得成为第二个可写真值。
5. `维护复杂度.建议` 只在 `inline_tool|auditor_bundle` 中选择；程序仍按 API 能力决定具体投递方式。
6. 不输出隐藏段、正则、`maintain.v1/v2`、tool schema、Worker 提示或界面字段。
7. 产物正文不含自评、追问或开放问题。
8. `mount` 固定为 `["world-simulator", "auditor"]`。

## score

```score
真值必要性：
- 5：每个字段不保存都会造成明确跨轮错误，没有临时描写或可派生冗余。
- 3：主体必要，但夹有一个可从其它字段或最近正文推出的状态。
- 1：把人物感受、场景描述或大段设定全部变量化。

字段妥当性：
- 5：类型、初值、操作和约束彼此一致，字段数量恰当且不重叠。
- 3：基本可用，但有边界、枚举或初始化要求不够明确。
- 1：类型与操作冲突，或存在余额/存款一类重复真值。

更新可执行性：
- 5：每条规则都有已发生事实、判断方式、证据、操作、值规则和时机。
- 3：更新方向明确，但证据或值范围仍需猜测。
- 1：只说“随剧情变化”，无法生成或校验更新。

权限与公开性：
- 5：写入者与公开性符合用途，隐藏真值不会因显示或用户误改而泄露、漂移。
- 3：大体合理，但有一项写入者或公开边界含混。
- 1：任何执行单元都能任意改，或秘密状态被默认公开。

映射与触发一致性：
- 5：映射、阈值触发和原子更新都引用有效变量，且没有建立重复可写真值。
- 3：主体能接通，但有来源引用或边沿语义不清。
- 1：派生结果反向覆盖真值，或触发引用不存在字段。
```

## checklist

```checklist
- [ ] 每个真值都通过“不保存会出错”的必要性检验？
- [ ] 类型、初值、允许操作、约束和写入者互相一致？
- [ ] 每条更新规则都有事实证据和可执行的值规则？
- [ ] 派生映射未被重复建成可写真值？
- [ ] 维护复杂度依据实际依赖，而不是只按变量数量？
- [ ] 未写隐藏标签、正则、维护包或界面格式？
```

## examples

```examples
- 单个数值真值、只有 set/delta 和上下界、无交叉依赖：建议 inline_tool；程序按 API 探测生成类型明确的小工具。
- 多个真值需要结合正文共同判断，且阈值会触发映射或补实例：建议 auditor_bundle；维护编译工具统一收集。
- 当前态度由好感区间映射得到：只保存好感，态度作为派生映射，不建立第二个可写“当前态度”。
- 不合适：每轮重写一段“当前性格”长字符串，或只写“随剧情变化”而没有证据与操作。
```