From 199acda84b28752d8fbc93e2202a4e9be3fb28b1 Mon Sep 17 00:00:00 2001 From: Jacobinwwey Date: Wed, 27 May 2026 05:13:29 -0500 Subject: [PATCH] docs(progress): sync provider settings implementation lane truth --- ...026-05-20-unified-follow-through-matrix.md | 5 +- ...-20-unified-follow-through-matrix.zh-CN.md | 5 +- ...recovery-audit-and-next-level-direction.md | 25 +++++--- ...ry-audit-and-next-level-direction.zh-CN.md | 25 +++++--- ...simplification-and-model-discovery-plan.md | 61 +++++++++++++++++++ ...fication-and-model-discovery-plan.zh-CN.md | 61 +++++++++++++++++++ 6 files changed, 160 insertions(+), 22 deletions(-) diff --git a/docs/brainstorms/2026-05-20-unified-follow-through-matrix.md b/docs/brainstorms/2026-05-20-unified-follow-through-matrix.md index 6fe4f74d..ce1dd4d5 100644 --- a/docs/brainstorms/2026-05-20-unified-follow-through-matrix.md +++ b/docs/brainstorms/2026-05-20-unified-follow-through-matrix.md @@ -38,7 +38,7 @@ This matrix is grounded in: | B. CLI / automation surface | Current main now has registry-backed config/profile export/import, redacted provider export, public-surface export, registry-backed typed `content.split-note-by-chapters`, and repo-local maintainer help/invoke scripts for bounded path-based operations plus exports, including maintainer-only `local-knowledge.inspect` retrieval introspection | Backup branch also carried broader maintainer-bridge aspirations, but the current reintegration keeps the surface intentionally narrow | Keep maintainer helper scope explicit and only promote path-based operations to broader/public CLI status with same-batch contract/test/doc proof | Do not describe the current surface as a general-purpose public CLI or a free-form maintainer mutation API | P1 | | C. User-facing settings / preview / onboarding | Current main now has preview flows, preview history, release-note digest in onboarding, provider diagnostics, settings reset, concept-note prerequisite guidance, API liveness/activity UI, saved-artifact-aware preview recovery, and `1.9.0` release-facing version truth resynced | Backup branch carried additional UX closure work, but the recovered slice is now re-proved on current main | Keep sidebar/preview/settings wording, i18n, saved-artifact behavior, and release-facing version truth aligned as the user-facing truth source | Do not regress to “these UX guardrails are missing on current main,” but also do not overclaim unrecovered UX ideas | P1 | | D. Regex / file selection / local-KB / chapter split | Current main now has file-selection profiles, folder regex/glob filtering, `relativePath` / `basename` matching, optional subfolder inclusion control, local-KB retrieval for `Generate from title`, `Batch generate from titles`, `Research & Summarize`, and `Generate diagram`, mixed vault-relative file/folder knowledge-base path support, per-task knowledge-base override lists with default fallback semantics, chapter split, repeated-heading-safe TOC block refs, deterministic TOC front-matter metadata, manifest-backed guarded rerun overwrite semantics, their regression tests, machine-readable retrieval summaries plus timing/size telemetry on the title-generation, research, and artifact-mode diagram result paths, a maintainer-only retrieval inspect seam for effective path/query/context debugging, temporary `knowledgePaths` override arrays for ad hoc task-scoped retrieval inspection, and a broader dedicated offline fixture via `npm run verify:local-kb-fixtures` that also covers mixed file/folder task-scoped inspect cases | Backup branch provided the original recovery evidence; current main now carries the bounded product slice directly plus later Stage C follow-through work | Treat the next step as broader mixed-note/query corpus coverage plus maintainer example alignment, not existence re-proof | Do not keep writing these capabilities as backup-only or absent from live mainline, do not drop the single-title/task-scoped retrieval contract from docs, and do not flatten retrieval back down to boolean-only signaling in docs or contracts | P1 | -| E. Provider settings / model discovery | Current main has a broad transport-driven provider registry, provider-specific validation/test metadata, manual `model` as the persisted source-of-truth string, and a functional provider settings panel; however, field rendering is still hardcoded in `src/ui/NotemdSettingTab.ts`, there is no shared core/advanced/developer field taxonomy in `src/llmProviders.ts`, and there is no first-class settings-surface model discovery helper yet | There is no meaningful backup-branch shipped implementation to restore here; the relevant evidence is the live current-main code plus the Cherry Studio comparison work recorded under `.trellis/tasks/05-27-provider-settings-model-discovery/` | Converge provider settings on shared metadata, auto-expand advanced when persisted advanced values exist, and add lightweight model discovery as an optional helper without introducing a second persisted provider-state subsystem | Do not claim schema-driven provider settings, advanced disclosure, or in-plugin model picker/catalog UX already exist on current main | P1 | +| E. Provider settings / model discovery | Current main has a broad transport-driven provider registry, provider-specific validation/test metadata, manual `model` as the persisted source-of-truth string, and a functional provider settings panel; however, field rendering is still hardcoded in `src/ui/NotemdSettingTab.ts`, there is no shared core/advanced/developer field taxonomy in `src/llmProviders.ts`, and there is no first-class settings-surface model discovery helper yet. A separate isolated worktree/branch now carries an unmerged implementation probe for this lane, but that does not change current-main truth until it is verified and merged. | There is no meaningful backup-branch shipped implementation to restore here; the relevant evidence is the live current-main code, the Cherry Studio comparison work recorded under `.trellis/tasks/05-27-provider-settings-model-discovery/`, and the current isolated implementation lane | Bootstrap and verify the isolated lane, finish the metadata-driven provider-panel convergence there, close CSS/UI polish, and merge only after targeted plus full verification passes without introducing a second persisted provider-state subsystem | Do not claim schema-driven provider settings, advanced disclosure, the isolated lane's transient discovery helper, or in-plugin model picker/catalog UX already exist on current main | P1 | | F. Release / repo-saga / clean-state hygiene | Current main now has release/repo-saga scripts plus shared repo-saga execution lock, tests, docs, and local-artifact ignore guardrails | Backup branch motivated the guardrails; the bounded serial-safety slice is now back on current main | Preserve serial execution discipline for repo-saga refresh flows and keep clean-state proof as part of finish criteria | Do not confuse “script still exists” with permission to run repo-saga refresh paths in parallel | P0 | ## 4. Reconfirmed Current-Main Register @@ -65,6 +65,7 @@ These items must currently be described as **not proven on rewritten main**: 3. any dedicated-runtime claim that bypasses the current single-entry `main.js` + inline `srcdoc` truth; 4. schema-driven provider-settings field grouping on current main; 5. a first-class in-plugin provider model discovery / picker UX on current main. +6. the isolated implementation lane's partial metadata/discovery refactor as shipped current-main behavior. ## 5. Single Execution Order @@ -74,7 +75,7 @@ Unless a regression interrupts the order: 2. **P0**: restore clean-state and repo-saga serial guardrails 3. **P0/P1**: resolve the current source/build ambiguity around latent render-host runtime sources before widening packaging claims 4. **P1**: keep the bounded CLI / maintainer-surface truth narrow and well-tested, then decide whether any path-based operation merits bounded public promotion -5. **P1**: finish provider-settings control-plane convergence with metadata-driven field grouping and lightweight model discovery in an isolated implementation lane +5. **P1**: bootstrap, verify, and then finish provider-settings control-plane convergence with metadata-driven field grouping and lightweight model discovery in the isolated implementation lane 6. **P1**: keep recovered user-facing settings / preview guardrails aligned across code, i18n, docs, and `1.9.0` release-facing version truth 7. **P1/P2**: deepen file-selection, local-KB, and chapter-split quality only as bounded current-main work diff --git a/docs/brainstorms/2026-05-20-unified-follow-through-matrix.zh-CN.md b/docs/brainstorms/2026-05-20-unified-follow-through-matrix.zh-CN.md index 436b7d7f..7650fa91 100644 --- a/docs/brainstorms/2026-05-20-unified-follow-through-matrix.zh-CN.md +++ b/docs/brainstorms/2026-05-20-unified-follow-through-matrix.zh-CN.md @@ -38,7 +38,7 @@ canonical: true | B. CLI / automation surface | 当前主线现已具备 registry-backed 的 config/profile export/import、脱敏 provider 导出、public-surface 导出、已进入 registry-backed typed contract 的 `content.split-note-by-chapters`，以及覆盖有界 path-based 操作与 export 操作的 repo-local maintainer help/invoke 脚本，其中也包含 maintainer-only 的 `local-knowledge.inspect` retrieval introspection | 备份分支还承载过更宽的 maintainer-bridge 设想，但当前 reintegration 刻意保持在窄边界内 | 继续把 maintainer helper 的边界写清楚；若任何 path-based operation 要提升为更广或更公共的 CLI 面，必须同批补齐契约/测试/文档 | 不要把当前能力面写成通用 public CLI，或无边界的 maintainer mutation API | P1 | | C. 用户可见 settings / preview / onboarding | 当前主线现已具备 preview flows、preview history、欢迎弹窗 release digest、provider diagnostics、settings reset、concept-note 前置配置提示、API liveness/activity UI、面向已保存工件的 preview 恢复链路，并已重新同步 `1.9.0` 的 release-facing version truth | 备份分支还有更多 UX 收口尝试，但目前已恢复切片已在当前主线上重新证明 | 继续保持 sidebar / preview / settings 的文案、i18n、已保存工件行为与 release-facing version truth 一致 | 不要再把这些 UX guardrail 写成“当前主线缺失”，但也不要顺手高估尚未恢复的 UX 想法 | P1 | | D. Regex / 文件筛选 / local-KB / chapter split | 当前主线现已具备 file-selection profiles、文件夹 regex/glob 筛选、`relativePath` / `basename` 匹配、可选子目录范围控制、覆盖 `从标题生成`、`从标题批量生成`、`研究与总结`、`生成图形` 的 local-KB retrieval、混合的 Vault 相对文件/文件夹知识库路径、带默认回退语义的按任务知识库覆盖列表、chapter split、面向重复标题的稳定 TOC block ref、确定性的 TOC front-matter metadata、manifest-backed 的 guarded rerun overwrite 语义、对应回归测试、面向标题生成/研究总结/artifact-mode 图形结果路径的 machine-readable retrieval 摘要与 timing/size telemetry、用于检查 effective path/query/context 的 maintainer-only retrieval inspect seam、支持临时 `knowledgePaths` override 数组做 ad hoc task-scoped retrieval 检查，以及通过 `npm run verify:local-kb-fixtures` 暴露、且已覆盖 mixed file/folder task-scoped inspect case 的更宽离线夹具 | 备份分支提供了最初恢复证据；当前主线现在已直接携带该有界产品切片与后续 Stage C 收口结果 | 下一步应转向 mixed-note/query corpus 覆盖扩充与 maintainer example 对齐，而不是继续证明这些能力“是否存在” | 不要继续把这些能力写成只存在于 backup、或 live mainline 尚未具备；不要把 single-title / task-scoped retrieval 契约从文档里漏掉；也不要在文档或契约里把 retrieval 再压回 boolean-only signaling | P1 | -| E. Provider settings / model discovery | 当前主线已有较宽的 transport-driven provider registry、provider-specific validation/test metadata、作为持久化 source-of-truth 的手动 `model` 字符串，以及可工作的 provider settings panel；但字段渲染仍硬编码在 `src/ui/NotemdSettingTab.ts` 中，`src/llmProviders.ts` 里没有共享的 core/advanced/developer 字段 taxonomy，设置页中也还没有一等公民的模型发现辅助能力 | 这里没有值得“恢复”的 backup-branch 已发货实现；当前真正证据来自 current-main 代码，以及 `.trellis/tasks/05-27-provider-settings-model-discovery/` 下的 Cherry Studio 对照研究 | 把 provider settings 收敛到共享元数据上；当已有持久化 advanced 值时默认展开 advanced；并以不引入第二套持久化 provider-state subsystem 的方式补一条轻量 model discovery helper | 不要把 schema-driven provider settings、advanced disclosure、或设置页内的 model picker/catalog UX 误写成当前主线已存在 | P1 | +| E. Provider settings / model discovery | 当前主线已有较宽的 transport-driven provider registry、provider-specific validation/test metadata、作为持久化 source-of-truth 的手动 `model` 字符串，以及可工作的 provider settings panel；但字段渲染仍硬编码在 `src/ui/NotemdSettingTab.ts` 中，`src/llmProviders.ts` 里没有共享的 core/advanced/developer 字段 taxonomy，设置页中也还没有一等公民的模型发现辅助能力。当前另有一条隔离 worktree/branch 正在做这条线的实现探针，但在验证并合回前，它不改变 current-main 真值。 | 这里没有值得“恢复”的 backup-branch 已发货实现；当前真正证据来自 current-main 代码、`.trellis/tasks/05-27-provider-settings-model-discovery/` 下的 Cherry Studio 对照研究，以及当前隔离实现通道中的未合并进展 | 先把隔离实现通道 bootstrap 并完成验证，在那里面收口 metadata-driven provider panel、补齐 CSS/UI polish，并且只有在 targeted + full verification 全绿后才允许合并；同时不要引入第二套持久化 provider-state subsystem | 不要把 schema-driven provider settings、advanced disclosure、隔离通道里的 transient discovery helper、或设置页内的 model picker/catalog UX 误写成当前主线已存在 | P1 | | F. Release / repo-saga / clean-state hygiene | 当前主线现已具备 release/repo-saga 脚本，以及 repo-saga 执行锁、测试、文档与本地工件忽略 guardrail | 备份分支推动了这些 guardrail；当前主线已恢复有界串行安全切片 | 保持 repo-saga 刷新流程的串行纪律，并把 clean-state 证明保留为收尾要求 | 不要把“脚本还在”误读为“可以并行跑 repo-saga 刷新路径” | P0 | ## 4. 当前主线已确认 register @@ -65,6 +65,7 @@ canonical: true 3. 任何绕开当前单入口 `main.js` + inline `srcdoc` 真值的 dedicated-runtime 叙述； 4. 当前主线已存在的 schema-driven provider-settings field grouping； 5. 当前主线已存在的一等公民 in-plugin provider model discovery / picker UX。 +6. 隔离实现通道里那套部分完成的 metadata/discovery 重构，已经作为当前主线发货行为存在。 ## 5. 单一执行顺序 @@ -74,7 +75,7 @@ canonical: true 2. **P0**：恢复 clean-state 与 repo-saga 串行 guardrails 3. **P0/P1**：先解决当前 latent render-host runtime source 与实际 shipping build 之间的歧义，再决定是否拓宽 packaging 叙述 4. **P1**：保持有界 CLI / maintainer-surface 真值收敛且测试充分，再决定是否有 path-based operation 适合做有界 public 提升 -5. **P1**：在隔离实现通道里完成 provider-settings control-plane convergence，包括 metadata-driven field grouping 与 lightweight model discovery +5. **P1**：先 bootstrap 并验证隔离实现通道，再在其中完成 provider-settings control-plane convergence，包括 metadata-driven field grouping 与 lightweight model discovery 6. **P1**：持续保持已恢复的用户可见 settings / preview guardrails 在代码、i18n、文档与 `1.9.0` release-facing version truth 之间一致 7. **P1/P2**：以有界 current-main 工作继续深化 file-selection、local-KB、chapter split 的质量 diff --git a/docs/brainstorms/2026-05-25-post-bounded-recovery-audit-and-next-level-direction.md b/docs/brainstorms/2026-05-25-post-bounded-recovery-audit-and-next-level-direction.md index 40fbdf26..e34fc936 100644 --- a/docs/brainstorms/2026-05-25-post-bounded-recovery-audit-and-next-level-direction.md +++ b/docs/brainstorms/2026-05-25-post-bounded-recovery-audit-and-next-level-direction.md @@ -144,11 +144,14 @@ This lane is now the clearest example of “runtime breadth advanced faster than 7. Cherry Studio analysis now gives a concrete comparison target: - the strategy-registry and parser/fallback separation are worth reusing - the persisted `provider.models[]` lifecycle and heavier provider-domain state are too heavy for Notemd's current architecture +8. an isolated implementation lane now exists at `feat/provider-settings-model-discovery` in a separate worktree. Based on its current diff, that lane adds provider-field taxonomy metadata plus discovery metadata in `src/llmProviders.ts`, a new transient `src/providerModelDiscovery.ts` helper for OpenAI-compatible / Ollama / Google discovery, a metadata-driven provider-panel refactor attempt in `src/ui/NotemdSettingTab.ts`, matching locale keys, and focused regression tests. +9. that isolated lane is still outside current-main truth. When checked on 2026-05-27, the worktree did not have a bootstrapped `node_modules`, so verification there has not completed yet; CSS/polish and final quality gates remain open. Interpretation: - provider/runtime support is materially ahead of provider settings UX architecture; -- the next product-facing control-plane work is not more providers first, but schema and discoverability convergence for the providers that already exist. +- the next product-facing control-plane work is not more providers first, but schema and discoverability convergence for the providers that already exist; +- this lane has moved beyond pure planning into bounded isolated implementation, but current-main truth does not move until that lane is bootstrapped, verified, and merged. ## 3. Deep Comparison Against Prior Requirement Tracks @@ -203,16 +206,16 @@ Current requirement status: | Requirement | Status | Notes | |---|---|---| -| R1 provider settings must distinguish required/core from advanced fields | Not landed | Current UI shows a flat provider panel without shared grouping metadata | -| R2 distinction must come from shared provider metadata | Not landed | `LLMProviderDefinition` is not yet field-taxonomy aware | +| R1 provider settings must distinguish required/core from advanced fields | Not landed on current main; isolated implementation in progress | Current UI on main still shows a flat provider panel, while the isolated lane has an unmerged metadata-driven grouping attempt | +| R2 distinction must come from shared provider metadata | Not landed on current main; isolated implementation in progress | `LLMProviderDefinition` on main is not field-taxonomy aware yet, but the isolated lane adds `settingFields` metadata | | R3 preserve runtime behavior and import/export compatibility | Already aligned in the current data model | The flat persisted provider config keeps compatibility pressure low for the future refactor | -| R4 support Azure-specific required fields without forcing them onto others | Partially aligned | `apiVersion` exists today, but only through hardcoded UI branching | -| R5 keep common setup fast and visible | Partially aligned | Current UI is simple but noisy; it has not yet converged to a core/advanced split | +| R4 support Azure-specific required fields without forcing them onto others | Partially aligned on main; isolated metadata path exists | `apiVersion` exists today through hardcoded UI branching; the isolated lane starts moving that visibility into provider metadata without changing persisted shape | +| R5 keep common setup fast and visible | Partially aligned on main; isolated renderer refactor in progress | Current UI is simple but noisy; the isolated lane starts a core/contextual/advanced split, but it is not verified or merged yet | | R6 deeply analyze Cherry Studio model fetch design | Landed as research | `.trellis/tasks/05-27-provider-settings-model-discovery/research/cherry-studio-model-discovery.md` | -| R7 degrade gracefully to manual model entry | Operationally true today | Manual entry is the only path today, but there is no optional discovery helper yet | +| R7 degrade gracefully to manual model entry | Operationally true on main; isolated discovery helper in progress | Main still relies entirely on manual entry; the isolated lane adds transient discovery while intentionally keeping manual `model` entry as the persisted truth path | | R8 `model` must remain core/default-visible | Landed in current behavior | `model` is already a first-class visible field | -| R9 auto-expand advanced if persisted advanced values already exist | Not landed | No advanced disclosure state exists yet | -| R10 reuse Cherry Studio selectively rather than cloning its whole architecture | Planned, not implemented | The research now makes this direction concrete enough to implement | +| R9 auto-expand advanced if persisted advanced values already exist | Not landed on current main; isolated helper exists | Main has no advanced disclosure state yet; the isolated lane adds an unmerged derived helper for persisted advanced-value expansion | +| R10 reuse Cherry Studio selectively rather than cloning its whole architecture | Research landed; isolated implementation follows that direction | The isolated lane uses transient discovery metadata/service rather than a persisted `provider.models[]` subsystem | Interpretation: @@ -238,6 +241,8 @@ What has changed since the earlier matrix wording: local-KB, chapter split, preview history, and saved-artifact reopening came back without forcing docs to pretend packaged runtime isolation already exists. 3. **Cherry Studio comparison removed a large planning blind spot** the repo now has a concrete answer for what to reuse, what to reject, and why. +4. **The provider-settings lane now has an isolated execution probe** + the work is no longer blocked on architecture ambiguity; it is now blocked on finishing, bootstrapping, and verifying the implementation lane without overclaiming mainline truth. ### 4.2 What is structurally tense right now @@ -249,6 +254,8 @@ What has changed since the earlier matrix wording: copying Cherry Studio wholesale would create a second provider-state subsystem that Notemd does not need. 4. **The flat config shape is both a strength and a constraint** it preserves import/export and `data.json` compatibility, but it gives the UI no field taxonomy by itself. +5. **The next blocker is now execution discipline, not planning ambiguity** + the isolated lane already carries a bounded implementation attempt, but it must be bootstrapped, verified, and polished before it can change current-main truth. ### 4.3 Correct interpretation @@ -256,7 +263,7 @@ Current main is best described as: 1. past the “recovery existence proof” stage for the bounded product slice; 2. still before true Stage-C packaged runtime convergence; -3. still before provider-settings control-plane convergence; +3. still before provider-settings control-plane convergence on current main, even though a bounded isolated implementation lane is now underway; 4. still before any broad public CLI promotion. ## 5. Concrete Next-Level Plan diff --git a/docs/brainstorms/2026-05-25-post-bounded-recovery-audit-and-next-level-direction.zh-CN.md b/docs/brainstorms/2026-05-25-post-bounded-recovery-audit-and-next-level-direction.zh-CN.md index c77e8ea1..8b85b04d 100644 --- a/docs/brainstorms/2026-05-25-post-bounded-recovery-audit-and-next-level-direction.zh-CN.md +++ b/docs/brainstorms/2026-05-25-post-bounded-recovery-audit-and-next-level-direction.zh-CN.md @@ -144,11 +144,14 @@ release-facing 真值已重新对齐到当前主线： 7. 对 Cherry Studio 的分析已经给出明确对照方向： - strategy-registry 与 parser/fallback 分层值得复用 - 持久化 `provider.models[]` 生命周期和更重的 provider-domain 状态，对 Notemd 当前架构来说过重 +8. 当前已有一条隔离实现通道：单独 worktree 中的 `feat/provider-settings-model-discovery`。从其当前 diff 来看，这条通道已经增加了 `src/llmProviders.ts` 里的 provider-field taxonomy metadata 与 discovery metadata、一个新的瞬时 `src/providerModelDiscovery.ts`（首批覆盖 OpenAI-compatible / Ollama / Google）、`src/ui/NotemdSettingTab.ts` 中一版 metadata-driven provider panel 重构尝试、对应 locale keys，以及聚焦的回归测试。 +9. 但这条隔离通道仍然不属于 current-main 真值。2026-05-27 检查时，该 worktree 还没有 bootstrapped 的 `node_modules`，因此那里的验证尚未完成；CSS/polish 与最终质量门禁也都还没收口。 正确解释： - provider/runtime 支持面已经实质领先于 provider settings UX 架构； -- 下一阶段真正该做的，不是先继续堆 provider 数量，而是把已存在 provider 的 control plane 收敛到可扩展的 schema 与 discoverability 设计上。 +- 下一阶段真正该做的，不是先继续堆 provider 数量，而是把已存在 provider 的 control plane 收敛到可扩展的 schema 与 discoverability 设计上； +- 这条线已经从纯规划进入了有界隔离实现，但在完成 bootstrap、验证并合回之前，current-main 真值不发生变化。 ## 3. 相对先前方案要求的深度对比 @@ -202,16 +205,16 @@ release-facing 真值已重新对齐到当前主线： | Requirement | 状态 | 说明 | |---|---|---| -| R1 provider settings 需要区分 required/core 与 advanced 字段 | 未落地 | 当前 UI 仍是单层 provider panel，没有共享分组元数据 | -| R2 这一区分必须来自共享 provider metadata | 未落地 | `LLMProviderDefinition` 还不具备字段 taxonomy 能力 | +| R1 provider settings 需要区分 required/core 与 advanced 字段 | 当前主线未落地；隔离实现进行中 | 当前 main 上的 UI 仍是单层 provider panel，而隔离通道里已经有一版未合并的 metadata-driven 分组尝试 | +| R2 这一区分必须来自共享 provider metadata | 当前主线未落地；隔离实现进行中 | main 上的 `LLMProviderDefinition` 还没有字段 taxonomy 能力，但隔离通道已新增 `settingFields` 元数据 | | R3 保持 runtime 行为与 import/export 兼容 | 当前数据模型已天然有利于此 | 扁平 provider config 让未来重构的兼容性压力较低 | -| R4 支持 Azure 专属 required 字段而不污染其他 provider | 部分对齐 | `apiVersion` 已存在，但仍通过硬编码 UI 分支注入 | -| R5 常见配置流程需要更快更聚焦 | 部分对齐 | 当前 UI 简单但噪声偏高，尚未收敛出 core/advanced split | +| R4 支持 Azure 专属 required 字段而不污染其他 provider | main 上部分对齐；隔离元数据路径已出现 | `apiVersion` 现在仍靠硬编码 UI 分支注入；隔离通道已开始把这类可见性往 provider metadata 上迁移，同时不改持久化结构 | +| R5 常见配置流程需要更快更聚焦 | main 上部分对齐；隔离 renderer 重构进行中 | 当前 UI 简单但噪声偏高；隔离通道已开始做 core/contextual/advanced split，但还没有验证并合并 | | R6 深度分析 Cherry Studio 模型获取链路 | 研究已落地 | `.trellis/tasks/05-27-provider-settings-model-discovery/research/cherry-studio-model-discovery.md` | -| R7 发现失败时必须平滑回退到手动 model 输入 | 目前行为上成立 | 现在唯一方式就是手动输入，但还没有 discovery helper | +| R7 发现失败时必须平滑回退到手动 model 输入 | 当前 main 行为上成立；隔离 discovery helper 进行中 | main 目前仍完全依赖手动输入；隔离通道则补了一条 transient discovery，同时刻意保留手动 `model` 输入作为持久化真值路径 | | R8 `model` 必须保持 core/default-visible | 当前行为已满足 | `model` 现在就是一等可见字段 | -| R9 若已有持久化 advanced 值则默认展开 advanced | 未落地 | 目前根本没有 advanced disclosure state | -| R10 Cherry 方案只做 selective reuse，不整体照搬 | 已规划但未实现 | 研究结论已足以指导实现 | +| R9 若已有持久化 advanced 值则默认展开 advanced | 当前主线未落地；隔离 helper 已出现 | main 目前还没有 advanced disclosure state；隔离通道已增加一条未合并的基于持久化 advanced 值的展开 helper | +| R10 Cherry 方案只做 selective reuse，不整体照搬 | 研究已落地；隔离实现遵循该方向 | 隔离通道使用的是 transient discovery metadata/service，而不是持久化 `provider.models[]` 子系统 | 正确解释： @@ -237,6 +240,8 @@ release-facing 真值已重新对齐到当前主线： local-KB、chapter split、preview history 与 saved-artifact reopening 的回归，没有逼着文档去假装 packaged runtime isolation 已经完成。 3. **Cherry Studio 对照研究消除了大的规划盲区** 仓库现在已经明确知道该复用什么、不该复用什么，以及原因是什么。 +4. **Provider-settings 轨道已经出现隔离执行探针** + 当前已不再被架构方向不明所阻塞，真正的阻塞点变成了如何在不过度声明主线真值的前提下，把隔离通道 bootstrap、补完并验证通过。 ### 4.2 当前最大的结构性张力 @@ -248,6 +253,8 @@ release-facing 真值已重新对齐到当前主线： 如果整体照搬 Cherry Studio，就会平白引入第二套 provider-state subsystem。 4. **扁平配置结构既是优势也是约束** 它保住了 import/export 与 `data.json` 兼容性，但也意味着 UI 自身拿不到字段 taxonomy。 +5. **当前下一个 blocker 已经变成执行纪律，而不是规划模糊** + 隔离通道已经有一版有界实现，但在它 bootstrap、验证、polish 完成前，不能改变 current-main 真值。 ### 4.3 正确解释 @@ -255,7 +262,7 @@ release-facing 真值已重新对齐到当前主线： 1. 已经跨过“bounded product slice 是否恢复存在”的阶段； 2. 但还没有进入真正的 Stage-C packaged runtime convergence； -3. 也还没有完成 provider-settings control-plane convergence； +3. 也还没有完成 current main 上的 provider-settings control-plane convergence，尽管隔离实现通道已经启动； 4. 更没有进入宽口径 public CLI promotion。 ## 5. 具体 next-level 方案 diff --git a/docs/brainstorms/2026-05-27-provider-settings-simplification-and-model-discovery-plan.md b/docs/brainstorms/2026-05-27-provider-settings-simplification-and-model-discovery-plan.md index fd31fdbd..6264018e 100644 --- a/docs/brainstorms/2026-05-27-provider-settings-simplification-and-model-discovery-plan.md +++ b/docs/brainstorms/2026-05-27-provider-settings-simplification-and-model-discovery-plan.md @@ -111,6 +111,31 @@ What is still missing: | Reuse Cherry Studio selectively | Planned with concrete research | Safe to implement without copying the whole architecture | | Support optional model discovery without blocking manual setup | Not landed | Discovery must be additive and ephemeral | +## 3.5 Current isolated implementation-lane checkpoint + +As of the 2026-05-27 audit, the isolated worktree/branch `feat/provider-settings-model-discovery` has moved this lane beyond pure planning, but not into current-main truth yet. + +What is already present there: + +1. `src/llmProviders.ts` now carries draft provider-field taxonomy metadata (`core`, `contextual`, `advanced`, `developer`) and per-provider model-discovery metadata. +2. a new `src/providerModelDiscovery.ts` implements transient discovery for: + - OpenAI-compatible `GET /models` + - Ollama tag listing + - Google model listing +3. `src/ui/NotemdSettingTab.ts` has a draft metadata-driven provider-panel refactor, including: + - default/core field rendering + - contextual field rendering + - advanced disclosure + - derived auto-expand when persisted advanced values exist + - optional fetch-models UI wiring +4. matching locale keys and focused tests were added for the new control-plane behavior. + +What is still not done there: + +1. the isolated worktree has not finished verification yet and was not bootstrapped with local dependencies when checked; +2. CSS/layout polish for the new provider-panel surfaces is still incomplete; +3. current-main truth remains unchanged until that lane passes verification and merges. + ## 4. Cherry Studio Comparison Reference repo: `/home/jacob/ref/cherry-studio` @@ -196,6 +221,11 @@ Mitigation: 1. keep metadata declarative and field-scoped; 2. do not move rendering code into the provider registry. +Current checkpoint: + +1. implemented in the isolated lane, not merged; +2. the metadata shape stays declarative and field-scoped so far. + ### Phase 2: settings renderer refactor Files: @@ -218,6 +248,12 @@ Mitigation: 1. derive advanced expansion from current config presence; 2. preserve all existing field values and save semantics. +Current checkpoint: + +1. a metadata-driven renderer attempt now exists in the isolated lane; +2. default/core, contextual, and advanced sections are partially wired there; +3. verification, CSS polish, and merge gating remain open. + ### Phase 3: lightweight discovery service Suggested new file: @@ -243,6 +279,12 @@ Mitigation: 2. keep manual model input always available; 3. never persist remote catalogs. +Current checkpoint: + +1. a transient discovery helper exists in the isolated lane for the planned first batch; +2. it keeps manual `model` entry as the persisted source of truth; +3. it is still unmerged and unverified. + ### Phase 4: UI integration Deliverables: @@ -251,6 +293,12 @@ Deliverables: 2. no blocking dependency between discovery and save flow; 3. if discovery fails, keep the exact current manual workflow usable. +Current checkpoint: + +1. fetch-models UI wiring and transient suggestion state exist in the isolated lane; +2. styling and user-surface validation are still open; +3. this is not yet current-main behavior. + ### Phase 5: tests and documentation Required test coverage: @@ -267,6 +315,12 @@ Required docs: 3. this document 4. current canonical matrix/audit docs if status meaning changes during implementation +Current checkpoint: + +1. focused i18n/test updates already exist in the isolated lane; +2. current-main canonical docs are now being updated to reflect the real split between mainline truth and isolated implementation progress; +3. the merge gate still requires isolated-lane bootstrap plus targeted and full verification. + ## 7. Explicit Non-Goals Do not do these in the first batch: @@ -285,4 +339,11 @@ Execution should follow this split: 2. implementation proceeds in the isolated worktree/branch lane created for this task; 3. only a verified, bounded implementation is merged back. +Concrete merge gate for the isolated lane: + +1. bootstrap the isolated worktree so build/test tooling actually resolves project dependencies; +2. run targeted provider-settings/model-discovery tests there first, then full `npm run build`, `npm test -- --runInBand`, `npm run audit:i18n-ui`, and `git diff --check`; +3. close the remaining CSS/layout gaps in the provider settings surface; +4. merge back only after the lane is green and current-main docs can truthfully switch from “isolated implementation in progress” to “landed”. + That keeps the planning truth honest while avoiding half-landed control-plane changes on current main. diff --git a/docs/brainstorms/2026-05-27-provider-settings-simplification-and-model-discovery-plan.zh-CN.md b/docs/brainstorms/2026-05-27-provider-settings-simplification-and-model-discovery-plan.zh-CN.md index 2ba5e58a..59758080 100644 --- a/docs/brainstorms/2026-05-27-provider-settings-simplification-and-model-discovery-plan.zh-CN.md +++ b/docs/brainstorms/2026-05-27-provider-settings-simplification-and-model-discovery-plan.zh-CN.md @@ -111,6 +111,31 @@ canonical: true | selective reuse Cherry Studio | 已形成具体研究结论 | 可以安全进入实现，不需要整体照搬 | | 模型发现不能阻断手动配置 | 未落地 | discovery 必须是 additive 且 transient 的 | +## 3.5 当前隔离实现通道检查点 + +截至 2026-05-27 审计，隔离 worktree/branch `feat/provider-settings-model-discovery` 已经把这条线从纯规划推进到了有界实现，但还没有推进成 current-main 真值。 + +那里已经存在的内容： + +1. `src/llmProviders.ts` 已加入一版 provider-field taxonomy metadata（`core`、`contextual`、`advanced`、`developer`）与按 provider 的 model-discovery metadata。 +2. 新增了一个瞬时 `src/providerModelDiscovery.ts`，首批覆盖： + - OpenAI-compatible `GET /models` + - Ollama tag listing + - Google model listing +3. `src/ui/NotemdSettingTab.ts` 中已有一版 metadata-driven provider panel 重构尝试，包含： + - 默认/core 字段渲染 + - contextual 字段渲染 + - advanced disclosure + - 基于持久化 advanced 值的派生 auto-expand + - 可选的 fetch-models UI wiring +4. 对应 locale keys 与聚焦测试也已经补入。 + +那里还没有完成的内容： + +1. 该隔离 worktree 在检查时还没有完成验证，且本地依赖没有 bootstrap 好； +2. 新 provider-panel surface 的 CSS/layout polish 还没收口； +3. 在这条通道验证通过并合回之前，current-main 真值不变。 + ## 4. Cherry Studio 对照结论 参考仓库：`/home/jacob/ref/cherry-studio` @@ -196,6 +221,11 @@ Cherry Studio 值得复用的点： 1. metadata 保持 declarative 与 field-scoped； 2. 不把渲染逻辑搬进 provider registry。 +当前检查点： + +1. 已在隔离通道里实现，但尚未合回； +2. 当前 metadata 形态仍保持 declarative、field-scoped。 + ### Phase 2：settings renderer 重构 涉及文件： @@ -218,6 +248,12 @@ Cherry Studio 值得复用的点： 1. advanced 展开逻辑从当前配置实时推导； 2. 保留现有字段值与保存语义。 +当前检查点： + +1. 隔离通道里已经有一版 metadata-driven renderer 尝试； +2. default/core、contextual 与 advanced 分区已部分接线； +3. 验证、CSS polish 与 merge gate 仍未完成。 + ### Phase 3：lightweight discovery service 建议新增文件： @@ -243,6 +279,12 @@ Cherry Studio 值得复用的点： 2. 始终保留手动 model 输入； 3. 永不持久化远程 catalog。 +当前检查点： + +1. 隔离通道中已存在面向首批 family 的 transient discovery helper； +2. 它仍保持手动 `model` 输入为持久化 source of truth； +3. 但目前还没有合并，也还没完成验证。 + ### Phase 4：UI 接入 产物： @@ -251,6 +293,12 @@ Cherry Studio 值得复用的点： 2. discovery 与保存流程之间不能形成阻塞依赖； 3. 一旦 discovery 失败，当前手动工作流必须完整可用。 +当前检查点： + +1. 隔离通道里已经有 fetch-models UI wiring 与瞬时 suggestion state； +2. styling 与用户面验证仍未完成； +3. 这还不是 current-main 行为。 + ### Phase 5：测试与文档 必须补齐的测试覆盖： @@ -267,6 +315,12 @@ Cherry Studio 值得复用的点： 3. 本文 4. 如果实现状态变化，则同步更新 canonical matrix/audit 文档 +当前检查点： + +1. 聚焦的 i18n/test 更新已经出现在隔离通道里； +2. 当前 main 的 canonical 文档现在正在同步更新，以反映“主线真值”和“隔离实现进展”的真实分离； +3. 最终 merge gate 仍要求隔离通道先 bootstrap，再跑 targeted + full verification。 + ## 7. 显式非目标 首批不要做这些事： @@ -285,4 +339,11 @@ Cherry Studio 值得复用的点： 2. 实现工作在为该任务创建的 isolated worktree/branch 中推进； 3. 只有经过验证的、有界实现才合回主线。 +隔离通道的具体 merge gate： + +1. 先把 isolated worktree bootstrap 好，让 build/test tooling 真正能解析到项目依赖； +2. 先跑 provider-settings/model-discovery 的 targeted tests，再跑完整的 `npm run build`、`npm test -- --runInBand`、`npm run audit:i18n-ui` 与 `git diff --check`； +3. 收掉 provider settings surface 剩余的 CSS/layout 缺口； +4. 只有在整条通道变绿后，才能把当前 main 文档从“隔离实现进行中”切换为“已落地”。 + 这样才能在保持规划真值诚实的同时，避免把半落地的 control-plane 改动直接摊在当前 main 上。