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 配置

const modelResources = await resolveWorkspaceModelResources(hookConfigRoot, config);
const runtimeConfig: BladeConfig = {
  ...modelResources.config,
  permissions: await configManager.loadWorkspacePermissions(
    hookConfigRoot,
    modelResources.config.permissions
  ),
};

通过共享动作持久化 Web 配置

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)