| configSchemaRef | 生成文件内 $schema URL（jsDelivr 缓存 GitHub 上的公开 Schema）。 from 仅作调用点语义标注，便于日后若布局分叉再按位置扩展（OCP）。 |
| withConfigSchema | 在对象根写入 $schema（不覆盖已有）；数组根勿调用。 |
| isConfigMetaKey | 配置元数据键`$schema 与 _ / _comment* 前缀，加载时跳过 |
| stripConfigMeta | 浅剥离对象上的元数据键（不递归数组元素内的对象以外的深层——调用方可再 strip） |
| findMonorepoRoot | 从 startDir 向上查找 monorepo 根（package.json#name === sfmc-monorepo）。 找不到则返回 null（例如从 npm 装到 node_modules 的独立包）。 |
| resolveRuntimeRoot | 解析运行时根目录（SFMC_ROOT）。 |
| resolveRuntimePath | 将配置项中的相对路径解析为基于工作目录的绝对路径。 若本身已是绝对路径则直接返回；相对路径则相对于 runtimeRoot 进行解析。 |
| configDir | 获取配置文件存放目录路径（<runtimeRoot>/configs）。 |
| configPath | 获取指定配置文件的完整绝对路径（<runtimeRoot>/configs/<name>）。 |
| stateDir | 运行态临时状态与缓存目录路径（<runtimeRoot>/.sfmc）。 PID 文件、探活缓存与运行时产物的唯一权威存储目录。 |
| logsDir | 运行态日志输出目录路径（<runtimeRoot>/.sfmc/logs）。 各服务的持久化落盘日志统一存放在此处。 |
| logFile | 获取指定服务的持久化日志文件路径（<runtimeRoot>/.sfmc/logs/<name>.log）。 |
| qqRuntimeStatusPath | qq-bridge 运行态心跳文件:/.sfmc/qq.runtime.json CLI Tab/status 用它探测「外部」qq 是否仍活着（与 db /api/health 对称）。 |
| moduleDir | 模块目录路径：<ROOT>/modules。 |
| modulePath | 模块系统文件路径（catalog / module-lock）。 |
| readJson | 同步读取 JSON 文件；失败时返回 fallback 或 undefined。 |
| writeJson | 原子写 JSON:写到临时文件再 rename,避免半写状态。 自动创建父目录。 |
| patchJson | 浅合并:读出现有 JSON,与 partial 合并,原子写回。 文件不存在视为 {}。 |
| ensureJson | 确保 JSON 文件存在。 - 存在 → 不动,返回现有内容(或 fallback) - 不存在 → 写入 seed(默认 {}),返回 seed |
| ensureJsonConfig | 仓顶 config JSON 的 ensure 便捷版:拼接 configPath + ensureJson。 |
| ensureSchemaConfig | ensure 带 $schema 的配置对象（DRY：禁止各服务手写 ensureJsonConfig+withConfigSchema）。 返回磁盘内容（可能含元数据键）；运行时业务请用 loadEnsuredConfig。 |
| loadEnsuredConfig | ensure 后剥离元数据，返回可交给业务逻辑的纯配置（LSP：与无 $schema 的契约一致）。 |
| ensureCoreConfigs | 按需 ensure 平台核心配置。新种类加到 CoreConfigKind + switch 即可（OCP）。 permissions 根为数组，不能走 withConfigSchema。 |