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

2026-07-30 10:53:39 +08:00
parent 353f5c0a39
commit 51415debe5
50 changed files with 396 additions and 84 deletions
@@ -1,6 +1,6 @@
 # Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
 # 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
-README.md: 13f51d5338affd65d0705cec6a3b4ef78a534f0f
-README.zh.md: 466505beb27c729246afe04e6378235b91d072cf
+#   pnpm run verify-translation-pairing --write packages/client/ui-models/README.md
+README.md: 5bcfdcdbfe31ada89f787cd4d193e9763dba94d3
+README.zh.md: 84b4b2187851506697de635d56691ca7e988ea00
@@ -2,11 +2,15 @@

 English | [中文](README.zh.md)

-Models settings section plugin: registers the `models` nav entry into `settings.section` with an intentionally empty content column — model management lands in a later phase.
+Models settings section plugin: the provider configuration page. It joins three wire domains into one surface — `llm.providers` (the configurable-provider directory with each route's live/dormant state), `settings.describe` (serialized schemas, layered redacted values, secret slots), and `credentials.describe` (value-free configured/source/writable badges) — and renders provider rows with one editor card at a time.
+
+Rows are the *configured* providers (their profile resolves in the owning namespace); the add select's vocabulary is every dormant directory entry, so a bare-mounted `llm-pi-ai` offers its whole installed catalog before any route exists. The editor renders the provider's profile subtree through [`@deepseek-ai/dsh-client-schema-form`](../schema-form); the `credential-ref` role mounts the credential control, which shows the reference's live state and stores key values **write-only** through `credentials.set` — no value ever renders back. A row is deletable only when the user layer alone carries it (removal restores the composition base).
+
+Apply semantics mirror the settings seam: an edit without removals lands as a minimal `settings.update` merge patch (stored secrets outside the patch survive), while a field reset or row deletion lands through `settings.replace` of the whole user section so removals actually take effect. The page refetches on the pushed invalidations (`settings/changed`, `credentials/changed`, `models/changed`, and `connection/reset`) once it has loaded, so an external `settings.yaml` edit, a second tab, or a settings-born route converges without polling.

 ## Model Experience

-None, as the section renders an empty browser UI column; nothing here reaches a model request.
+None, as the section renders a browser configuration UI; nothing here reaches a model request.

 #### KV Cache effect

@@ -14,4 +18,6 @@ None; this package neither assembles nor sends a provider request.

 ## Known Limitations and Deferred Work

- **Content column is empty by design** — provider list, editing form, and activation flow are deferred until the model-management service exists.
+- **A reset can drop a stored literal secret in the same subtree** — a replace-carried removal cannot re-supply secrets the wire never returned; store keys behind `credentials.*` references (the product default) and the case cannot arise.
+- **No per-provider model listing on the page** — the picker surfaces models; this page shows route state only. A models preview per row is deferred until a consumer needs it.
+- **Undeclared live routes render nowhere** — a route registered without a configurable-provider declaration has no settings address; it stays visible in pickers but not on this page's rows.
@@ -2,11 +2,15 @@

 [English](README.md) | 中文

-模型设置分区插件：注册 `models` 导航项，使其进入 `settings.section`；内容栏有意留空，模型管理将在后续阶段实现。
+模型设置分区插件：提供方配置页。它把三个协议领域汇聚为一个界面——`llm.providers`（可配置提供方目录，含每条路由的存活／休眠状态）、`settings.describe`（序列化 schema、分层脱敏值、secret 槽位）与 `credentials.describe`（不含值的 configured/source/writable 徽标）——并渲染提供方行，一次只展开一张编辑卡片。
+
+行是*已配置*的提供方（其 profile 在所属 namespace 中解析得出）；新增选择框的词汇是全部休眠目录条目，因此裸挂载的 `llm-pi-ai` 在任何路由存在之前就能提供其完整的已安装 catalog。编辑器经 [`@deepseek-ai/dsh-client-schema-form`](../schema-form) 渲染该提供方的 profile 子树；`credential-ref` 角色会挂载凭据控件，它展示该引用的实时状态，并经 `credentials.set` 以**只写**方式存入密钥值——任何值都绝不回显。只有当某行仅由用户层承载时它才可删除（删除会还原组合 base）。
+
+「应用」语义与 settings seam 呈镜像：不含删除的编辑以最小的 `settings.update` 合并 patch 落地（patch 之外已存储的 secret 得以保留），字段重置或整行删除则经对整个用户分节的 `settings.replace` 落地，使删除真正生效。页面加载完成后会在推送的失效事件（`settings/changed`、`credentials/changed`、`models/changed` 与 `connection/reset`）上重拉，因此外部的 `settings.yaml` 编辑、第二个标签页或 settings 新生的路由都无需轮询即可收敛。

 ## 模型体验

-无。该分区渲染空白的浏览器 UI 内容栏；这里没有任何内容进入模型请求。
+无。该分区渲染浏览器配置 UI；这里没有任何内容进入模型请求。

 #### KV Cache 影响

@@ -14,4 +18,6 @@

 ## 已知限制与暂缓事项

- **内容栏按设计留空**：提供方列表、编辑表单和激活流程均暂缓，待模型管理服务就绪后实现。
+- **重置可能丢弃同一子树中已存储的字面 secret**：经 replace 承载的删除无法重新提供协议从未返回过的 secret；把密钥放在 `credentials.*` 引用背后（产品默认做法），该情形便不会出现。
+- **页面上没有逐提供方的模型列表**：模型由选择器呈现；本页只展示路由状态。逐行的模型预览暂缓，待有消费方需要时再实现。
+- **未声明的存活路由无处渲染**：未附带可配置提供方声明即注册的路由没有 settings 地址；它在各选择器中仍然可见，但不会出现在本页的行里。