docs: bilingual config-plane documentation, regenerated catalogs, and the web-config-plane Agent Note

This commit is contained in:
Yichen Jiang
2026-07-30 10:53:39 +08:00
parent 353f5c0a39
commit 51415debe5
50 changed files with 396 additions and 84 deletions

View File

@@ -2,5 +2,5 @@
# side as of the last confirmed-consistent state. Both languages carry equal authority;
# after editing either side, bring the other along and re-record with:
# pnpm run verify-translation-pairing --write packages/settings/settings/README.md
README.md: ff6cdeb57a265dbaa9d5f50de1d558f1e3cb581f
README.zh.md: d820a5c1fa804455c439f1a155e7628f5118a49b
README.md: de04c1260c03112b6e48cfdfa7d1aec1c1421df5
README.zh.md: ab20c07e39a6ed4b74efc5656637b4ba977435d2

View File

@@ -7,7 +7,7 @@
## 服务 API
- `register(ns, schema, { base?, applies? })` — 返回 owner 的 `SettingsScope``get`/`watch`/`update`)。注册是调用方插件 fiber 上的 effectdispose 该 fiber 即移除 namespace 及其观察者。schema 拒绝的存量分节会使注册本身失败;重复 namespace 立即报错。
- `describe()` — 每个 namespace 一条描述(`schema.toJSON()` 信封、解析值、`applies`),供配置界面使用。
- `describe(options?)` — 每个 namespace 一条描述(`schema.toJSON()` 信封、解析值、分离出的 `base`/`user` 层、`applies`),供配置界面使用;字段出现在 `user` 中即标记其被用户覆盖。`describe({ redactSecrets: true })` 从每一层剥离 `role('secret')` 字段,并附加 `secrets` 槽位列表(`{ path, set }`);每个 wire 面都必须传入它,纯遍历器 `redactSecrets(schema, value)` 已导出,供其他 wire 使用。
- `get(ns)` — 解析值;未注册时为 `undefined`
- `update(ns, patch)` — 把普通对象 patch 深合并进用户分节(绝不合并进 `base`),校验解析候选值,经 provider 持久化后提交。校验失败在持久化前拒绝;只读 provider`writable: false`)拒绝一切写入。同一 namespace 的写入按调用顺序串行。
- `replace(ns, section)` — 整体替换用户分节merge 表达不了的删除/重置路径(`replace({})` 重新继承 `base` 与 schema 默认值)。
@@ -34,4 +34,3 @@
- **单一用户层** — 解析只认识 schema 默认值、一个组合 `base` 与一个用户文档;尚无 project/managed 分层或按值溯源。
- **跨进程并发由 provider 定义** — seam 仅在进程内按 namespace 串行化写入;跨进程并发按 provider 行为收敛(本地文件 provider 为后写胜出)。
- **无 secret 字段脱敏** — `describe()` 原样返回解析值wire 面RPC/UI在暴露前必须对 `role('secret')` 字段脱敏。