核心概念

Snow Cues 的使用体验围绕几个核心概念展开。理解它们，才能正确使用并避免数据丢失。

Snow Cues 不知道你在外部平台实际使用的明文密码，也不是一个服务商托管的加密密码库。它在本地使用空间主密码、关键密钥和规则链完成派生与查看，业务数据由你显式保存到 storageData。

`storageData`

storageData 是 Snow Cues 的业务数据文件夹。它是唯一业务数据源，不从旧 IndexedDB 或其他本地缓存自动恢复业务数据。

典型结构：

current.json：当前正式数据。
revisions/：历史快照。
drafts/：用户导出的草稿。
conflicts/：保存冲突时生成的候选文件。

你可以把这个文件夹放在自己信任的位置，也可以用 Syncthing、Git 等外部工具管理文件，但 Snow Cues 本身不做后台同步或自动合并。

空间

空间是 storageData 中的本地分区。一个 storageData 可以包含多个空间，你可以为不同用途创建不同空间。

空间 ID 用于分区和展示，不是密码派生输入。空间 ID 不支持修改。

空间主密码

空间主密码用于建立当前浏览器内存中的会话。Snow Cues 不保存空间主密码，也不保存密码校验材料。

如果需要更换空间主密码，应创建新空间并迁移条目——空间主密码不做原地修改。

关键密钥

关键密钥是每条密码单独需要的输入。创建密码和解密密码都必须输入关键密钥。

关键密钥不会被保存，也不会写入 URL、localStorage、sessionStorage 或 storageData。

关键密钥由你自己保管。Snow Cues 不保存可恢复关键密钥的材料，因此忘记关键密钥后无法找回。

规则链

规则链是空间级配置，决定密码材料如何生成。默认规则链为「稳定 HMAC → 增强 PBKDF2」。

规则链不是单条密码字段——单条密码不会保存自己的 ruleId。规则链是全局初始化配置，新建密码前需要先初始化。

Rule 是什么

Rule 是规则链中的一个处理步骤。每个 Rule 都声明自己使用哪一种内置算法模板，以及这一步需要的公开参数。

Snow Cues 当前允许的算法包括：

hmac-sha256：基于当前空间会话能力和单条关键密钥生成稳定材料。
pbkdf2-sha256：在已有材料基础上增加计算成本。

默认规则链先执行稳定 HMAC，再执行增强 PBKDF2。这样可以把空间主密码建立的会话能力、单条关键密钥和空间规则配置放在同一条本地派生流程中。

初始化规则链是什么意思

初始化规则链是为当前空间确认一组规则配置。新空间在初始化前没有可用于正式创建密码条目的规则链，因此新建密码前需要先完成这一步。

初始化后，规则链会作为空间 profile 的一部分保存到 storageData。之后进入同一空间时，应用会根据保存的规则链恢复同样的派生流程。

规则链会影响后续条目的生成和查看。不要把它当作临时 UI 设置随意修改；如果需要切换规则体系，通常应创建新空间并通过迁移流程处理旧条目。

自定义 Rule 如何工作

自定义 Rule 不是任意代码。Snow Cues 只接受声明式 JSON，并把它映射到允许的内置算法模板。

这意味着：

可以调整的是规则声明和公开参数。
不能导入或执行 JavaScript、远程脚本、正则脚本或任意插件代码。
导入的 Rule 需要能映射到允许的模板，例如 hmac-sha256 或 pbkdf2-sha256。
如果导入规则参与已确认的规则链，它的声明式 manifest 会随空间 profile 保存，用于后续恢复同一条规则链。

自定义 Rule 的作用是改变本地派生流程，而不是保存关键密钥、保存明文密码或增加找回能力。忘记空间主密码或关键密钥后，自定义 Rule 也不能帮助恢复。

如何配置自己的 Rule

配置自己的 Rule 时，先把它当作「声明一个内置算法，并给这个算法填写公开参数」来理解。不要把 Rule 当作脚本、插件或密码保存位置。

推荐流程：

打开或新建 storageData。
进入目标空间。
如果还没有设置空间主密码，先在空间主页完成设置。
如果已有密码并提示空间校验，先按页面提示完成校验。
在左侧菜单进入「规则管理」。
在「导入声明式规则或规则数组」中粘贴 Rule JSON。
点击「导入规则」，让应用校验 JSON。
在「规则链初始化」区域勾选要加入规则链的规则。
检查「待初始化规则链」，确认后点击「确认初始化」。
保存空间数据。

一个 Rule 通常需要表达这些信息：

字段	是否必填	说明
`id`	必填	规则标识，必须使用 `imported-` 前缀，只能包含小写字母、数字和连字符，并符合页面长度校验。
`name`	必填	页面中展示的规则名称，长度为 2 到 32 个字符。
`algorithm`	必填	只能是 `hmac-sha256` 或 `pbkdf2-sha256`。
`namespace`	可选	用于区分规则用途；不填写时默认使用 `id`。
`iterations`	可选	旧格式兼容字段，仅 `pbkdf2-sha256` 使用；系统会限制在 100000 到 600000 之间。
`params`	可选	新格式公开参数对象，由对应算法模板执行白名单校验、归一化和限幅。

不要在 Rule 中填写：

空间主密码。
单条关键密钥。
外部平台密码。
账号、恢复码或其他敏感秘密。
JavaScript 代码、远程脚本地址或需要执行的表达式。

HMAC 示例：

{
  "id": "imported-office",
  "name": "办公规则",
  "algorithm": "hmac-sha256",
  "namespace": "office"
}

PBKDF2 示例：

{
  "id": "imported-finance",
  "name": "财务规则",
  "algorithm": "pbkdf2-sha256",
  "namespace": "finance",
  "iterations": 260000
}

使用新格式时，PBKDF2 参数建议放在 params 中：

{
  "id": "imported-finance",
  "name": "财务规则",
  "algorithm": "pbkdf2-sha256",
  "namespace": "finance",
  "params": {
    "iterations": 320000,
    "materialLabel": "material-v2",
    "saltLabel": "salt-v2"
  }
}

批量导入时，可以粘贴由多个 Rule 对象组成的数组：

[
  {
    "id": "imported-office",
    "name": "办公规则",
    "algorithm": "hmac-sha256",
    "namespace": "office"
  },
  {
    "id": "imported-finance",
    "name": "财务规则",
    "algorithm": "pbkdf2-sha256",
    "namespace": "finance",
    "iterations": 260000
  }
]

导入成功后，页面会出现对应的导入规则卡片。初始化前，你可以修改规则名称、启用或停用导入规则、删除不需要的导入规则，并在规则链候选项中勾选或取消勾选规则。

常见导入失败原因包括：

JSON 格式不正确。
id 没有使用 imported- 前缀。
id 与已有规则重复。
algorithm 不是 hmac-sha256 或 pbkdf2-sha256。
name 太短或太长。
iterations 超出系统允许范围。
params 不是对象。
params 包含当前算法不支持的参数。

当前官方算法参数

官方构建只包含经过项目维护者审计的算法模板。导入规则会先解析 manifest，再检查 algorithm 是否存在于算法注册表，最后把 params 交给对应模板校验、归一化和限幅。

params 是公开、非秘密、可持久化的空间级规则配置。它不能包含代码、表达式、远程 URL、平台、账号、关键密钥或单条密码派生输入。

`hmac-sha256`

允许参数：

参数	类型	默认值	说明
`saltPrefix`	string	`namespace`	HMAC 输入前缀，只允许小写字母、数字和连字符。

如果不填写 params.saltPrefix，默认使用 namespace，旧版 HMAC manifest 会保持原行为。

示例：

{
  "id": "imported-office",
  "name": "办公规则",
  "algorithm": "hmac-sha256",
  "namespace": "office",
  "params": {
    "saltPrefix": "office-v1"
  }
}

`pbkdf2-sha256`

允许参数：

参数	类型	默认值	说明
`iterations`	integer	`210000`	PBKDF2 迭代次数，限制在 100000 到 600000。
`materialLabel`	string	`material`	HMAC material 标签，只允许小写字母、数字和连字符。
`saltLabel`	string	`salt`	PBKDF2 salt 标签，只允许小写字母、数字和连字符。

旧版顶层 iterations 仍然兼容，并会归一化为 params.iterations。只要不主动添加新的 params 配置，旧版 manifest 在新版本中应保持原行为。

如果某个空间规则使用了 params，请使用支持 params 的 Snow Cues 版本打开和维护该空间。旧版本可能忽略 params，导致派生结果不一致。

如何选择并初始化规则链

在「规则链初始化」区域勾选你要使用的规则。规则链的顺序就是页面中展示的顺序，规则会按从左到右执行，上一条规则的输出会进入下一条规则。

系统内置可用规则通常包括：

v1-hmac：稳定 HMAC。
v2-pbkdf2：增强 PBKDF2。

默认规则链是：

["v1-hmac", "v2-pbkdf2"]

普通用户建议保留默认内置规则链。如果加入自定义 Rule，应确保以后仍能理解这条 Rule 的用途，因为它会影响本空间后续生成和查看密码材料的方式。

确认初始化后：

当前空间会从临时状态变为持久空间。
本空间后续新建密码会使用这组已确认规则链。
本次会话内不能再导入、停用、重命名或删除规则。
单条密码仍不会保存 ruleId、场景、上下文或任何可重建派生输入。
如果某条导入 Rule 被加入已确认的规则链，它的声明式配置会随空间 profile 保存，用于以后重新进入该空间时恢复规则链。

记忆提示

记忆提示用于帮助用户回忆关键密钥，但它不是关键密钥本身。提示会加密保存，查看和编辑都需要用户显式操作。

记忆提示不参与密码生成、密码解密或自动恢复。不要把完整关键密钥、账号密码或其他敏感秘密写进记忆提示。

输出适配

输出适配只在本地查看结果后临时应用，用于满足某些平台的密码格式要求（长度、字符集等）。它不会覆盖已经保存的条目材料。

下一步

完整的日常流程：工作方式。
创建和解密密码：密码条目。
哪些数据会被保存：安全与隐私。