IronClaw Reborn 配置契约解析：类型化 Settings 仓库、五层配置模型与文件投影机制-平芜编程栈

人工智能
AI 应用
交互助手
AI Agent

【免费下载链接】ironclaw

IronClaw is an Agent OS focused on privacy, security and extensibility

项目地址：https://gitcode.com/gh_mirrors/iro/ironclaw

本篇基于 IronClaw 仓库中的 Reborn 合同冻结草稿 settings-config.md 展开，系统讲解 IronClaw Agent OS 中"设置/配置"作为结构化控制面状态的设计契约。读完后，你将理解 IronClaw 如何用类型化配置仓库取代散落的 JSON 文件、配置的五层分层与优先级模型、Scope 作用域继承规则、文件投影（projection）的三种写回模式，以及配套的事件审计与验收测试清单。

1. 契约定位：设置是控制面状态，不是任意记忆

该契约（状态：Contract-freeze draft，日期 2026-04-25）开宗明义：

Settings/configuration is structured control-plane state, not arbitrary memory. （设置/配置是结构化的控制面状态，而不是任意记忆。）

生产环境 Reborn 的**唯一事实来源（source of truth）**是：

typed settings repositories

即类型化的设置仓库，而不是配置文件本身。文件形态的投影（projection）可以存在于：

/system/settings /system/extensions /system/skills

但这些投影不构成规范存储模式（canonical storage schema），除非某个领域契约明确说明。

该契约依赖同目录下的四份姊妹契约，阅读时可交叉参考：

storage-placement.md —— 存储放置规则
secrets.md —— 秘密材料存储规则
extensions.md —— 扩展契约
filesystem.md —— 文件系统契约

仓库中可以直接看到这份"类型化设置仓库取代 JSON 文件"原则的落地证据：数据库迁移 V8__settings.sql 的头部注释明确写道，该表取代了~/.ironclaw/settings.json、session.json和mcp-servers.json三个散落文件，键采用点分路径约定（如"agent.name"、"sandbox.enabled"、"mcp_servers"），与既有Settings.get()/set()约定保持一致，"每行一个设置"以便原子更新单个值：

CREATE TABLE IF NOT EXISTS settings ( user_id TEXT NOT NULL, key TEXT NOT NULL, value JSONB NOT NULL, updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(), PRIMARY KEY (user_id, key) );

注意其value列是JSONB类型——这正是契约第 4 节"values are JSON values validated by schema"在持久层的对应实现。

2. 配置分层：五个必须保持独立的层

契约第 2 节要求保持以下分层互不混淆，每层有各自的事实来源：

层	用途	事实来源
Bootstrap config	进程启动、DB URL、初始 provider 提示、部署模式	操作员控制的环境变量/文件
DB-backed settings	用户/管理员/运行时产品设置	类型化设置仓库
Secrets	凭据与秘密材料	类型化加密秘密仓库
Extension config	扩展专属的已校验配置	类型化扩展配置仓库
File projections	诊断/编辑/导入导出视图	基于类型化状态的生成投影

这四条硬性规则值得逐条强调：

秘密绝不存入设置值（secrets are never stored in settings values）；
设置只能引用SecretHandle，绝不直接携带SecretMaterial——这是设置层与 secrets.md 契约的接缝：设置里放的是句柄，材料在加密秘密仓库里；
Bootstrap 配置在 setup 完成后不会静默覆盖DB 中的运行时设置，除非优先级规则明确允许；
秘密就绪后的 LLM/provider 解析必须重新解析——即后补密钥的 LLM 供应商配置，必须在密钥可用后再次执行解析流程，而不能沿用启动期的降级状态。

从仓库结构看，Bootstrap 层对应操作员侧的部署文件：profiles/目录下的 local.toml、server.toml、server-multitenant.toml 等部署档案，以及 deploy/env.example 中的环境变量模板，都属于"操作员控制的环境/文件"这一层，而非产品设置。

3. Scope 模型：作用域与优先级

3.1 七种作用域

设置可以按以下维度定作用域：

system/global tenant user project agent extension skill

3.2 每个设置契约必须声明的五件事

契约要求每个设置项的契约文本都必须说明：

允许的作用域（allowed scopes）；
默认作用域（default scope）；
继承/覆盖顺序（inheritance/override order）；
管理员专属 vs 用户可写（admin-only vs user-writable）；
是否允许 project/agent 层覆盖。

3.3 推荐优先级链

运行时设置的推荐优先级从高到低为：

explicit invocation override # 显式调用级覆盖 agent/project setting # agent/project 层设置 user setting # 用户层设置 tenant setting # 租户层设置 system default # 系统默认 bootstrap fallback # 引导配置兜底

最后一条审计要求：每次设置写入必须记录 actor scope（执行者的作用域），用于审计与溯源（provenance）。

对照 V8__settings.sql 的表结构可以推断：当前 DB 实现以user_id作为第一主键维度承载作用域，tenant/project 等上层作用域的完整 scope chain 由上层契约（storage-placement）约束——契约文本也要求"PostgreSQL/libSQL repository parity where settings are DB-backed"，即 DB 支撑的设置必须在 PostgreSQL 与 libSQL 两种后端保持行为一致。

4. 类型化仓库契约：操作面与规则

4.1 仓库应暴露的操作

get(scope, key) set(scope, key, value, actor) delete(scope, key, actor) list(scope, prefix) resolve(scope_chain, key) watch/emit change event

注意set/delete都强制携带actor参数——这与第 3 节"写入必须记录 actor scope"的要求呼应：审计信息是写路径的一等输入，而非事后补记。

4.2 五条操作规则

键是校验过的路径相邻标识符（path-adjacent identifier）；
值是 JSON 值，在已知 schema 时按 schema 校验；
未知键仅允许在明确标记为可扩展（extensible）的命名空间中；
写入按元数据/脱敏值审计；
包含疑似秘密材料的值应被拒绝，或要求显式走秘密迁移流程。

其中"键校验"直接映射到验收测试中的"key validation rejects path traversal/control characters"——键的点分路径格式（如tool_permissions.shell）天然需要防止路径穿越与控制字符注入。

5. Schema 校验与 llm_config 产品视图

5.1 需要 JSON Schema 的已知设置键

llm_backend selected_model llm_custom_providers tool_permissions.shell workspace_search embedding_provider extension enabled/config state

5.2 校验规则

schema 校验发生在持久化之前；
尽可能一次性报告全部相关错误，而非遇到第一个就返回；
schema 错误信息必须稳定且可指导用户操作（user-actionable）；
schema 定义与所属领域一起版本化；
投影回写（projection write-back）使用同一套 schema——即文件投影写回时不能走"更宽松"的校验路径。

5.3 llm_config 是规范读入口

契约第 5 节末尾规定：LLM provider 设置快照以 descriptor 支撑的 ProductSurface 查询视图llm_config暴露；旧的get_llm_configfacade 方法只是该视图上的兼容包装，ProductSurface 视图才是规范读通道。

仓库中的实现印证了这一点：product_surface.rs 中，组合根在装配阶段构造llm_config服务并挂到 API 上：

// crates/app/ironclaw_composition/src/product_surface.rs（节选） if let Some(llm_config) = build_llm_config_service(runtime) { api = api.with_llm_config_service(llm_config); } pub(crate) fn compose_llm_config_service(/* boot, keys */) { // ... let mut llm_config = ironclaw_operator::RebornLlmConfigService::new(boot.clone(), keys.clone()) // ... 依 boot/keys 组装 provider 解析能力 Some(Arc::new(llm_config)) }

从源码结构看，RebornLlmConfigService接收 bootstrap（boot）与密钥句柄（keys）两个输入组装——恰好对应契约第 2 节"secret 就绪后重新解析 provider"的语义：服务持有句柄而非秘密材料，解析在读取时发生。

6. 文件投影契约：路径、模式与规则

6.1 投影路径约定

类型化设置可以投影到：

/system/settings/{scope}/{key}.json /system/extensions/{extension}/config.json /system/skills/{skill}/manifest.json

6.2 三种投影模式

模式	含义
read-only	文件读反映类型化仓库；写被拒绝
validated write-back	文件写先做 schema 校验，再调用类型化仓库
export-only	生成快照，不挂载为可写

每个投影必须声明自己的模式——不允许"默认即可写"这种模糊状态。

6.3 投影规则

投影路径绝不能绕过类型化仓库的授权检查；
投影写回必须调用类型化仓库，而不是直接改动投影存储本身；
投影不暴露秘密材料；
投影包含足够的元数据/溯源信息，便于调试来源作用域，同时不泄漏私有值。

仓库中/system/settings、/system/extensions、/system/skills这组投影路径大量出现在运行时装配源码里，例如 filesystem_assembly.rs、host_access_assembly.rs 以及 production.rs——这些装配点正是把投影文件系统挂载进运行时、并按模式决定读/写权限的位置。

7. 扩展与 Skill 配置

扩展/skill 配置的事实来源是扩展/skill 服务持有的类型化状态（而非文件）。

最小生命周期状态集：

discovered installed authentication_required authenticated configured active disabled removed upgrade_required failed

两条配置规则：

配置写入在扩展/skill声明了 schema 时必须按其校验；
扩展可以拥有私有的 state、config、cache 根目录，但绝不允许把跨扩展或全局设置存到自己的命名空间之外。

这套生命周期与 extensions.md 契约配合使用；仓库中扩展注册/生命周期实现位于 ironclaw_extension_registry 与 ironclaw_extension_manager。

8. 事件与审计：脱敏优先

设置变更必须发出**脱敏（redacted）**事件/审计记录，事件族包括：

settings.changed settings.deleted settings.validation_failed extension.configured skill.configured

审计规则：

事件载荷包含key、scope、actor、version/revision 以及脱敏摘要；
默认不发出完整的 old/new 值——避免把敏感配置内容写进事件流；
秘密句柄可以以 handle 形式发出，但绝不能发出材料本身；
投影回写事件必须同时记录投影路径与类型化键，使审计能双向关联文件视图与仓库状态。

9. 必需验收测试清单

契约最后给出 10 条必需验收测试，这是实现该契约的最低验证基线：

键校验拒绝路径穿越/控制字符；
schema 校验在持久化前拒绝畸形值；
优先级解析选择最近的允许作用域；
tenant/user/project/agent 隔离性；
投影读反映类型化仓库；
投影写回完成校验并更新类型化仓库；
投影不能绕过授权；
疑似秘密值按策略被拒绝或转换为句柄；
设置变更发出脱敏事件/审计元数据；
当设置为 DB 支撑时，PostgreSQL 与 libSQL 仓库行为一致（repository parity）。

小结：一条清晰的数据流

把九个章节串起来，IronClaw 的设置系统形成一条单向数据流：

操作员 bootstrap（profiles/*.toml、环境变量） ↓ 仅启动期 类型化设置仓库（DB-backed，schema 校验，actor 审计） ↓ 按声明模式 文件投影（/system/settings、/system/extensions、/system/skills） ↓ 事件流 脱敏审计事件（settings.changed / settings.validation_failed / ...）

核心不变量只有四条：秘密只走句柄、写路径必须带 actor、文件投影永不绕过仓库授权、schema 在持久化前生效。这四条不变量加上第 9 节的十项验收测试，构成了该契约从设计到实现的完整闭环。