knowledge-layered-configuration-and-runtime-settings

## Module Structure 配置系统将启动读盘、内存投影和磁盘持久化拆成三个边界，并为非启动 workspace 提供按 source project 重建执行配置的专用入口。 ### Directory Layout - `packages/cli/src/config/ConfigManager.ts` — 多层读取、信任过滤、归一化、验证和 workspace 定向解析 - `packages/cli/src/config/ConfigService.ts` — 字段/作用域路由、防抖、原子写和并发协调 - `packages/cli/src/config/defaults.ts` — 完整默认配置与默认权限 - `packages/cli/src/config/types.ts` — `BladeConfig`、`RuntimeConfig` 和 Provider/权限类型 - `packages/cli/src/config/runtimeEnvironment.ts` — Session 环境变量名称和值校验 - `packages/cli/src/store/slices/configSlice.ts` — 启动进程内存配置投影 - `packages/cli/src/store/vanilla.ts` — 面向 TUI、Server 和命令的配置动作 - `packages/cli/src/server/routes/config.ts` — Web 公开配置投影与更新 API - `packages/cli/web/src/store/ConfigStore.ts` — workspace 模型选择与权限模式状态 - `packages/cli/web/src/store/SettingsStore.ts` — 通用设置的乐观更新与失败回滚 ### Key Entry Points - `ConfigManager.initialize()` — 合并默认、用户、可信项目、local 和调用级设置 - `ConfigManager.loadWorkspaceModelConfig()` — 为目标 source project 重建模型与 Provider 配置 - `ConfigManager.loadWorkspaceRuntimeSettings()` — 为目标 source project 解析 env、Hook 开关、轮次和权限模式 - `ConfigService.save()` — 按字段元数据选择文件、scope 和合并策略 - `configActions().updateConfig()` — 先更新 Store，再持久化，失败时回滚内存 ## API Surface ### ConfigManager - `initialize(additionalSettings?)` — 生成启动进程的完整 `RuntimeConfig` - `reload()` — 使用上次显式运行时覆盖重新读取配置 - `loadWorkspacePermissions(workspaceRoot, base)` — 去除启动项目私有规则并叠加目标 workspace 规则 - `loadWorkspaceModelConfig(workspaceRoot, base)` — 重建目标 workspace 的模型、Provider 与准入配置 - `loadWorkspaceRuntimeSettings(workspaceRoot, base)` — 重建目标 workspace 的执行环境和行为设置 - `loadWorkspaceMcpServers()` / `loadWorkspaceLspServers()` — 按目标 workspace 隔离可执行服务配置 ### ConfigService - `save(updates, options)` — 校验可持久化字段并路由到目标文件 - `flush()` — 立即提交所有防抖写入 - `appendLocalPermissionRule()` / `appendLocalPermissionDenyRule()` — 对目标 workspace 做原子追加去重 - `removePluginSetting()` — 从指定 scope 删除插件覆盖而非写入相反值 ### Store Actions - `configActions().updateConfig()` — 内存先行并在持久化失败时恢复快照 - `configActions().setPermissionMode()` — 仅更新本次运行状态 - `configActions().addModelWithProvider()` — 原子更新 catalog、模型和 Provider 配置 ## Usage Examples ### 为 Session 重建目标 workspace 配置 ```typescript const modelResources = await resolveWorkspaceModelResources(hookConfigRoot, config); const runtimeConfig: BladeConfig = { ...modelResources.config, permissions: await configManager.loadWorkspacePermissions( hookConfigRoot, modelResources.config.permissions ), }; ``` ### 通过共享动作持久化 Web 配置 ```typescript const { updates, options } = parsed.data; await configActions().updateConfig(updates, options); ``` ## Gotchas - `ConfigManager.initialize()` 捕获任意加载或验证错误后会重置全局模型目录并返回 `DEFAULT_CONFIG`；调用方看到的可能是“没有模型”而不是原始坏配置，诊断时必须检查启动日志 (`packages/cli/src/config/ConfigManager.ts`) - 进程 Store 不是多 workspace 执行配置的权威来源；目标目录与启动 cwd 不同时，模型、MCP、LSP、权限和运行时设置必须分别从用户层与该目标项目重建 (`packages/cli/src/config/ConfigManager.ts`, `git:3549bb1e`) - 跨 workspace 权限解析会先从传入 base 中剔除启动项目独有规则，再叠加目标项目规则；直接在 base 上追加会把服务器启动目录的本地授权泄漏给其他 Session (`packages/cli/src/config/ConfigManager.ts`, `packages/cli/tests/integration/config.test.ts`, `git:7b34bd7e`) - `config.json` 与 `settings.json` 不共享统一的深合并语义：模型数组整体替换，Provider/MCP/LSP 和插件映射按键合并，permissions 数组追加去重，Hook/env 深合并 (`packages/cli/src/config/ConfigManager.ts`) - `permissionMode` 可以从启动参数或可信 settings 进入运行时，但 `ConfigService` 明确拒绝持久化该字段；会话恢复依赖 Session metadata，不依赖写回配置文件 (`packages/cli/src/config/ConfigService.ts`, `packages/cli/src/store/vanilla.ts`) - `ConfigService.save()` 对未知更新字段直接报错，但写现有文件时保留磁盘中的未知字段；这是输入契约严格、旧版本数据向前兼容的刻意组合 (`packages/cli/src/config/ConfigService.ts`) - 防抖保存发生在 timer 回调内，失败只记录到 `lastSaveError` 而不会回抛到早先的 `save()` 调用；需要事务语义的权限决策和模型生命周期必须使用 `immediate: true` 或专用原子动作 (`packages/cli/src/config/ConfigService.ts`) - 项目未信任时，项目层只能暴露 Hook 摘要并可设置 `disableAllHooks=true` 收紧行为；env、模型、MCP、permissionMode 和 allow 规则全部忽略 (`packages/cli/src/config/ConfigManager.ts`, `packages/cli/tests/unit/services/workspace-model-resources.test.ts`) - Web 对指定 `workspacePath` 调用 `setCurrentModel()` 时只更新当前客户端选择，不写入启动项目全局配置；无 workspace 参数时才通过 `/configs` 持久化 (`packages/cli/web/src/store/ConfigStore.ts`) - Web 模型发现使用递增 sequence 丢弃迟到响应；移除该保护会让项目 A 的慢响应覆盖已切换到项目 B 的模型列表 (`packages/cli/web/src/store/ConfigStore.ts`, `packages/cli/web/tests/store/ConfigStore.test.ts`) ## Architecture - `ConfigManager` 只负责 bootstrap/read/normalize/validate，Zustand Store 是启动表面的内存状态，`ConfigService` 是唯一磁盘写入路由；业务代码不应直接修改 JSON 配置 (`packages/cli/src/config/ConfigManager.ts`, `packages/cli/src/config/ConfigService.ts`, `packages/cli/src/store/slices/configSlice.ts`) - 配置优先级是默认值 < 用户 config/settings < 可信项目 config/settings < local settings < 显式 invocation/CLI；环境变量插值在合并和字符串清理后递归执行 (`packages/cli/src/config/ConfigManager.ts`) - `resolveWorkspaceModelResources()` 在深复制配置后创建 Session 私有 `PiModelCatalog`；CredentialStore 可共享，但 Provider definitions、endpoint 和 fallback 注册不共享可变状态 (`packages/cli/src/agent/resources/WorkspaceModelResources.ts`) ## Decisions - 模型凭据从 `models` 和 `modelProviders` 分离到 `auth.json`，旧字段会被验证器主动拒绝而不是静默迁移，避免 endpoint 与 credential 身份混淆 (`packages/cli/src/config/ConfigManager.ts`, `packages/cli/src/config/modelProviders.ts`, `git:311ba368`) - 配置文件写入统一使用 per-file mutex、read-modify-write 和 `0600` 原子替换，既保留未知字段，也避免并发 UI、CLI 与审批写入互相覆盖 (`packages/cli/src/config/ConfigService.ts`) - 插件来源策略采用 tighten-only 合并：项目层只能开启更严格布尔限制或缩小 allowlist，不能覆盖用户级限制 (`packages/cli/src/config/ConfigManager.ts`, `packages/cli/src/config/pluginSettings.ts`) ## Patterns - 新增持久化字段时，以 `FIELD_ROUTING_TABLE` 为单一写入路由源，并同步 `BladeConfig`、`DEFAULT_CONFIG`、`validateConfig()` 和公开 API 投影 (`packages/cli/src/config/ConfigService.ts`, `packages/cli/src/config/types.ts`, `packages/cli/src/config/defaults.ts`) - 涉及多个磁盘字段和运行时 catalog 的动作先保存完整内存快照，任何持久化失败都同时恢复 Store 与 catalog (`packages/cli/src/store/vanilla.ts`, `packages/cli/src/server/routes/provider.ts`) - 配置中的字符串会递归 trim 并移除包裹反引号，随后 `$VAR`、`${VAR}` 和 `${VAR:-default}` 在嵌套对象与数组中统一展开 (`packages/cli/src/config/ConfigManager.ts`, `git:9513f0d2`) ## Consumer Analysis - SessionRuntime 是最大消费者，按 source project 组合模型、MCP、LSP、权限和 Hook，再冻结到 Runtime (`packages/cli/src/agent/runtime/SessionRuntime.ts`) - Server 路由通过 `configActions` 更新设置，并为多项目请求传入精确 workspace 身份 (`packages/cli/src/server/routes/`) - 插件系统读取 workspace 启用状态与 tighten-only 来源策略，生命周期写入必须指定 scope (`packages/cli/src/plugins/`) - MCP 与 LSP 不复用启动 Store 的项目层，分别调用 workspace 定向解析器 (`packages/cli/src/mcp/`, `packages/cli/src/lsp/`) - Web Store 维护乐观 UI 状态、请求去重和失败回滚，但服务端配置仍是持久化权威 (`packages/cli/web/src/store/`)