SuperAPI AI 工具集

schema-author

通用与其它

查看项目

更新于 10-27 23:48

技能介绍

Schema Author 是 Open Second Brain 提供的一项技能,适用于需要添加、重命名、审查或解释 Brain schema 令牌、别名、前缀、链接类型、可提取性或专家路由的场景。当任务会改变 Brain/_brain.yaml 中的活动 Brain schema 包,或需要依据该 schema 审查内容时,应使用此技能。

用途 该技能面向 schema 的维护与审查工作,帮助用户在不破坏现有配置的前提下,对 schema 包进行受控的修改与验证。

主要能力

  • 检查活动 schema 包:可通过 schema_inspect(view="active_pack")或 o2b brain schema --json 查看当前活动包。
  • 查看使用情况与发现项:通过 schema_inspect 的 stats、lint 和 orphans 视图检查当前使用情况与问题。
  • 解释候选令牌:在重命名或删除令牌之前,使用 schema_inspect(view="explain_type")解释候选令牌。
  • 预览批量变更:使用 schema_apply_mutations(dry_run=true)或 o2b brain schema apply --dry-run --mutation ... 预览批量变更,返回将生成的包及其差异,且不写入任何内容——不写配置、不记录审计、不生成锁文件。
  • 应用 schema 变更:仅通过 schema_apply_mutations 或 o2b brain schema apply --mutation ... 应用变更,以确保写入是加锁、原子且可审计的。
  • 变更后复查:在变更后重新运行 lint/stats,并报告已更改的令牌及任何剩余发现项。

使用方式

  1. 使用 schema_inspect(view="active_pack")或 o2b brain schema --json 检查活动 schema 包。
  2. 使用 schema_inspect 的 stats、lint 和 orphans 视图检查当前使用情况与发现项。
  3. 在重命名或删除之前,使用 schema_inspect(view="explain_type")解释候选令牌。
  4. 使用 schema_apply_mutations(dry_run=true)或 o2b brain schema apply --dry-run --mutation ... 预览批量变更。预览会运行与 apply 相同的包验证器,因此被验证器拒绝的批量在两者中会以相同方式报错。但预览不会运行仅因 apply 写入而存在的两项检查:vault-identity 写入守卫,以及原子写入器对渲染后 YAML 的重新解析。因此,渲染为不可解析 YAML 的批量可能预览通过但在 apply 时失败,所以应将干净的预览视为“变更有效”,而非“apply 一定会成功”。
  5. 仅通过 schema_apply_mutations 或 o2b brain schema apply --mutation ... 应用 schema 变更。
  6. 变更后重新运行 lint/stats,并报告已更改的令牌及任何剩余发现项。

变更说明 支持的操作包括 add_type、remove_type、update_type、add_alias、remove_alias、add_prefix、remove_prefix、add_link_type、remove_link_type、set_extractable 和 set_expert_routing。Schema 令牌必须是通过 Open Second Brain schema 验证的小写规范化令牌。除非 schema 包明确限定为项目范围,否则应优先使用小型、持久的令牌,而非项目特定的措辞。

适用场景 适用于需要维护或审查 Open Second Brain 的 Brain schema 包、调整令牌与别名、管理前缀与链接类型、设置可提取性或专家路由,以及依据 schema 审查内容的场景。

限制 预览(dry_run)不会执行 vault-identity 写入守卫和原子写入器对渲染后 YAML 的重新解析,因此干净的预览不代表 apply 一定成功。所有写入应通过 schema_apply_mutations 或 o2b brain schema apply --mutation ... 进行,以保证加锁、原子与审计。