OpenFlare/docs/superpowers/specs/2026-08-29-cordis-config-extension-design.md

Cordis 配置扩展点设计 (Config Extension Point)

• 文档状态: 已敲定 (Approved)
• 版本: v1.0.0 (2026-08-29)
• 适用范围: backend/core/(微内核)、backend/plugins/(自包含插件)、backend/cmd/(组合根)、backend/pkg/(无状态基础库)

---

0. 背景与动机

backend/pkg/config 同时承担了三件事：viper 装载 config.yaml、环境变量覆盖、以及以全局单例 config.Config 暴露全量配置模型。它与架构文档对 backend/pkg/ 的定位（"Stateless utilities and algorithm libraries"）冲突，并且带来两个结构性问题：

1. 配置所有权倒挂：任何包都能读到全量配置，因此 cmd 直接替 cache 插件判断 Redis 是否启用、risk_control 直接判断 clickhouse.enabled。配置的"读者"与"所有者"没有关系约束。
2. 隐式全局状态：init() 内完成文件搜索、解析与 log.Fatalf，并以 isTest() 猜测执行上下文来禁用数据库/Redis/ClickHouse；测试通过改写全局单例驱动生产代码路径。

本设计把"配置的读取框架"下沉为内核扩展点，把"读哪些字段"的所有权交给各插件自己声明，并一次性迁移全部 27 个消费文件（109 处引用），彻底删除全局单例。

AGENTS.md 与 new-setting skill 中早已写明插件应通过 ctx.Config().Bind(...) 绑定静态配置，但该 API 在代码中从未存在——本设计同时修正这一文档漂移。

---

1. 决策记录

#	决策	理由与取舍
D1	预声明阶段 + 配置门禁	内核在 Apply 之前收集声明并求值门禁，使组合根不再跨插件读配置选实现。代价是给 Fiber 增加"被门禁跳过"语义。
D2	混合读取形态：结构体 Bind + 泛型 Get	redis/database 等 14+ 字段结构体整体消费，逐 key 声明不可读；app.session_secret 等单字段不值得为它绑一个结构体。
D3	共享声明 + 内核冲突校验	配置是进程级只读事实，不存在数据表那种写竞争，因此允许读者各自声明同一 key；由内核强制"重复声明必须一致"兜底。放弃严格单所有权（需为若干配置值另造契约接口，且 driver_http 需 session store 连接参数是真实底层依赖）。
D4	一次性全量迁移	不留双轨，架构一次到位；接受较大的 diff。
D5	显式测试缝	删除 isTest() 魔法，测试通过 core.WithConfigValues(...) 注入。放弃"测试环境自动禁用中间件"的安全网，换取语义透明与可并行。
D6	内核持抽象，viper 归 infra 适配器	微内核防线规定 core/ 严禁 import 具体运行时依赖。core 只依赖 ConfigSource 接口，viper/yaml 装载放 plugins/infra/config。放弃"全放 core/config"（污染内核纯净性）与"完全插件化 + contracts.ConfigService"（门禁求值在 core，而 config 插件 Apply 尚未运行，存在鸡生蛋时序问题）。
D7	顺带解耦 pkg/idgen	其 init() 读全局配置，导致 pkg 反向依赖配置单例。

---

2. 分层与物理结构

backend/core/extpoints/config.go     # 配置引擎（仅 stdlib + reflect）：
                                     #   ConfigSource 接口、声明注册、解析、冲突校验、脱敏 dump
backend/core/config.go               # 泛型读取入口与 App 装配选项（Go 方法不支持类型参数）
backend/core/fiber.go                # 新增 FiberSkipped 状态与门禁求值
backend/core/types.go                # 新增 ConfigExtension / ConfigBinding / ConfigView 别名
backend/plugins/infra/config/        # viper + yaml 适配器，实现 core.ConfigSource（非 core.Plugin）
backend/cmd/                         # 组合根：host 声明集 + app.Prepare()
backend/pkg/idgen/                   # 移除 config 依赖，改为显式 Init(nodeID)
删除 backend/pkg/config/              # 全局单例 config.Config 一并消失

职责边界：

单元	做什么	不做什么
core/extpoints 配置引擎	维护 key 注册表、按优先级解析、类型转换、冲突校验、脱敏输出	不知道任何具体 key 的名字，不读文件，不 import viper
plugins/infra/config	定位 config.yaml（CONFIG_PATH → 向上查找）、解析成 raw map、代理 env 查询	不含 schema、不含业务字段语义
各插件	声明自己读哪些字段（tag 结构体）、声明门禁谓词	不读未声明的 key、不访问他插件的声明类型
cmd	声明 host 级 key、注入 ConfigSource、按已解析值初始化 logger/trace/banner	不做 if redis.enabled { ... } 这类跨插件判断

plugins/infra/config 不实现 core.Plugin，不出现在 app.Use() 列表里：它只向内核提供一个 ConfigSource 实例，没有服务、路由或任务可注册。它归 plugins/infra/ 而非 pkg/，是因为它封装了具体运行时依赖（viper、文件系统）并持有装载状态，不符合 pkg/ 的无状态定位。

pkg/idgen 解耦后，backend/pkg/ 恢复"不依赖配置源"的无状态定位。

---

3. 核心类型与 API

3.1 声明形态：带 tag 的结构体

唯一的批量作者形态是结构体 tag，一个字段同时表达 yaml 路径、env 覆盖名、默认值与敏感标记：

// plugins/infra/cache/redis_config.go —— redis 配置由 redis 插件自己声明
type redisConfig struct {
    Enabled            bool     `config:"enabled"             env:"REDIS_ENABLED"            default:"false"      autoEnable:"REDIS_ADDR"`
    Addrs              []string `config:"addrs"               env:"REDIS_ADDR"`
    Username           string   `config:"username"            env:"REDIS_USERNAME"`
    Password           string   `config:"password"            env:"REDIS_PASSWORD"           secret:"true"`
    DB                 int      `config:"db"                  env:"REDIS_DB"`
    ClusterMode        bool     `config:"cluster_mode"        env:"REDIS_CLUSTER_MODE"`
    MasterName         string   `config:"master_name"         env:"REDIS_MASTER_NAME"`
    KeyPrefix          string   `config:"key_prefix"          env:"REDIS_KEY_PREFIX"`
    MaintNotifications bool     `config:"maint_notifications" env:"REDIS_MAINT_NOTIFICATIONS" default:"false"`
    // ...pool/timeout 字段略
}

支持的 tag：config（yaml 相对路径，必填）、env（覆盖用环境变量名）、default（字符串形式，缺省时视为未设置）、autoEnable（该 env 一旦存在即把本布尔字段置 true）、secret（dump 时脱敏）。

3.2 内核接口

// ConfigSource 抽象了"原始值从哪来"，由 infra 适配器实现，使内核不绑定 viper。
type ConfigSource interface {
    Lookup(path string) (any, bool)   // config.yaml 中的点分路径
    LookupEnv(name string) (string, bool)
    Describe() string                 // 用于日志，如 "config.yaml" 或 "<env only>"
}

// ConfigBinding 把一个结构体绑定到某个 yaml 前缀上，是插件的声明单元。
type ConfigBinding struct {
    Prefix string // "redis"；空串表示字段 key 即完整路径
    Target any    // 指向带 tag 的结构体的指针
}

// ConfigView 是只读的已解析视图，供门禁与零散取值使用。
type ConfigView interface {
    String(key, fallback string) string
    Bool(key string, fallback bool) bool
    Int(key string, fallback int) int
    Duration(key string, fallback time.Duration) time.Duration
    Strings(key string) []string
    WasSet(envName string) bool
    Source(key string) string // "env" | "yaml" | "default"，用于诊断
}

// ConfigExtension 是挂载在 Context 上的扩展点，根 Context 与所有 Fork 共享。
type ConfigExtension interface {
    ConfigView
    Declare(pluginID string, bindings ...ConfigBinding) error
    Bind(prefix string, target any) error
    Entries() []ConfigEntry   // 有效配置的脱敏视图
}

core 侧导出别名与泛型入口（沿用仓库既有 core.Provide[T] / core.Inject[T] 风格）：

func ConfigGet[T any](v extpoints.ConfigView, key string) (T, error)

3.3 插件侧用法

// 批量绑定（Apply 内）
var cfg redisConfig
if err := ctx.Config().Bind("redis", &cfg); err != nil {
    return err
}

// 单字段读取：带 fallback 的访问器（门禁使用）
secret := ctx.Config().String("app.session_secret", "")

// 单字段读取：需要区分"未设置"与"设置为零值"时用泛型入口
rate, err := core.ConfigGet[float64](ctx.Config(), "otel.sampling_rate")

ConfigEntry 是 Entries() 返回的诊断单元，只含元数据与脱敏后的值：

type ConfigEntry struct {
    Key      string // "redis.password"
    PluginID string // 首次声明者，用于冲突报错点名
    Env      string
    Source   string // "env" | "yaml" | "default"
    Value    string // secret key 输出 "******"
}

Bind 的双重语义：若该 prefix 尚未声明，则按 Target 的 tag 自登记；若已声明，则是纯读取。登记时提供的 env/default/secret 元数据一律参与冲突校验（依 D3），因此自登记不会绕过校验。只有需要早于 Apply 求值的插件才必须显式 DeclareConfig()。

3.4 门禁接口与 Fiber 跳过态

// ConfigGatedPlugin 是可选接口：让内核在 Apply 之前决定插件是否激活。
type ConfigGatedPlugin interface {
    Plugin
    DeclareConfig() []extpoints.ConfigBinding     // 门禁所需 key 必须提前声明
    ConfigEnabled(v extpoints.ConfigView) bool
}

FiberState 新增 FiberSkipped。App.reconcileLocked() 在 Load() 前求值门禁：门禁为 false 的 Fiber 置 FiberSkipped，不计入依赖 satisfied 判定，也不参与 driver 启动。App.Stop() 对 skipped 与 active 一视同仁地按 LIFO 卸载其 scoped Context。

受门禁的插件对（现状仅三对，均为 Redis 存在与否的互斥实现）：

启用	跳过	门禁谓词
infra/cache	infra/cache_memory	redis.enabled
drivers/driver_asynq_worker	drivers/driver_inproc_worker	redis.enabled
drivers/driver_asynq_cron	drivers/driver_inproc_cron	redis.enabled

3.5 组合根

src := config.NewSource()                      // plugins/infra/config：仅定位与 raw 解析
app := core.NewApp(
    core.WithProfile(profile),
    core.WithConfigSource(src),
    core.WithConfigDecl(hostBinding...),       // app.* / log.* / otel.*
)
app.Use(
    infradb.New(), logger.New(), storage.New(),
    cache.New(), cache_memory.New(),            // 不再 if/else，门禁决定
    driver_asynq_worker.New(), driver_inproc_worker.New(),
    driver_asynq_cron.New(), driver_inproc_cron.New(),
    admin.New(), user.New(), auth.New(), /* ... */
    driver_http.New(),                          // addr 由插件自己声明读取
)
if err := app.Prepare(); err != nil { return err }   // 解析屏障 + 门禁求值

timeout, _ := app.Context().Config().Duration("app.graceful_shutdown_timeout", 30)
app.SetShutdownTimeout(timeout)

WithShutdownTimeout(d) 保留为显式覆盖入口（测试与非标准装配使用），生产路径改为 Prepare() 之后由已解析视图经 SetShutdownTimeout 设定。driver_http.New(WithAddr(...)) 选项删除，addr 归 driver_http 在 Apply 内声明读取。

---

4. 解析语义与启动时序

4.1 单 key 优先级链

1. 显式 env 命中          env:"DB_ENABLED"        → 最高优先级
2. autoEnable env 命中    autoEnable:"DB_HOST"     → true（被 1 覆盖）
3. config.yaml 命中       config:"enabled"
4. default tag 兜底

需要保留的既有特殊语义：

• 标量 env 填充切片字段：REDIS_ADDR=redis:6379 → redis.addrs = ["redis:6379"]；CLICKHOUSE_HOST 同理。
• 隐式启用：DB_HOST → database.enabled=true、REDIS_ADDR → redis.enabled=true、CLICKHOUSE_HOST → clickhouse.enabled=true；显式 *_ENABLED 始终优先于隐式推导。
• 同一 env 的双重角色：REDIS_ADDR 既是 redis.addrs 的值来源，又是 redis.enabled 的 autoEnable 触发器。引擎按 key 独立解析、允许一个 env 名服务多个 key，实现时不可把它建模成"env → 单一 key"的一对一映射。
• 时长字段：slow_threshold: 200ms 解析为 time.Duration。
• 文件定位：CONFIG_PATH 优先；否则从工作目录向上最多 5 层查找 config.yaml（该文件位于仓库根，backend/ 为其子目录）。

4.2 时序

config.NewSource()            # 读 yaml → raw map；零 schema 知识
  ↓
core.NewApp(WithConfigSource) # 记录 host 声明
  ↓
app.Use(...)                  # 遇 DeclareConfig() 立即登记 binding（叶子 key + env + default + secret）
  ↓
app.Prepare()                 # ① 冲突校验 ② 逐 key 解析 ③ 脱敏 dump ④ 门禁求值 → FiberSkipped
  ↓
app.Run() → Reconcile/Apply   # 插件内 Bind/Get 读取已解析值

App.Start() 在未显式调用 Prepare() 时幂等补做，防止遗漏。冲突校验规则：同一 key 的多份声明必须 env 名、default、secret 三项一致，否则 Prepare() 返回错误并点名两个声明者。

4.3 有意的行为变更

#	变更	现状	变更后
C1	default 生效条件	applyDefaults 对零值二次回落（session_age<=0 → 86400）	仅当 env 与 yaml 均缺失时生效；app.session_age<=0 在 Prepare() 判为配置错误（fail fast 优于静默改写）
C2	测试上下文	isTest() 自动禁用 DB/Redis/ClickHouse 并把 sqlite 指向 :memory:	删除该魔法；测试用 core.WithConfigValues(...) 显式声明。未声明 database.enabled 时按 default false 落 sqlite 后备，其路径沿用 postgres.go 既有的 ./data/wavelet.db 回落——需要内存库的用例必须显式注入 database.sqlite_path = ":memory:"
C3	配置 dump	printConfig 明文打印全量结构体，含 DB_PASSWORD、APP_SESSION_SECRET	按 secret:"true" 脱敏后输出，并标注每个 key 的来源（env/yaml/default）
C4	队列默认值	硬编码在 pkg/config 的 applyEnvOverrides	移入唯一消费者 driver_asynq_worker 的声明（webhook/whitelist_only/default 三级优先级不变）
C5	非法 env 值	envInt/envBool/envFloat64 在 strconv 失败时静默丢弃 env 值、回落 yaml/default	Prepare() 返回 ErrConfigType 并点名 key 与非法值

除此之外，解析结果与现状逐 key 等价（由 §7.1 第 4 条的对拍测试证明）。

---

5. 声明归属映射

声明方	key 前缀	消费者（含跨插件读）
cmd host 声明集	app.{env,app_name,addr,node_id,graceful_shutdown_timeout}、log.*、otel.*	cmd/root.go、cmd/banner.go、core.App
plugins/infra/cache	redis.*（含 enabled 门禁、autoEnable: REDIS_ADDR）	infra/cache、driver_http(session store)、driver_asynq_worker、driver_asynq_cron
plugins/infra/database	database.*、clickhouse.*	infra/database、admin、risk_control
plugins/domain/auth	app.session_*（cookie/secret/age/domain/secure/http_only）	auth、cap、message_gateway、driver_http
plugins/drivers/driver_asynq_worker	worker.*（并发、strict_priority、queues 默认值）	自身
其余	按需就近声明	—

跨插件读同一 key（如 cap 读 auth 声明的 app.session_secret）依 D3 走共享声明：cap 也声明该 key，三份元数据必须与 auth 一致，否则启动失败。

Key 命名约定：既有 infra key 保持顶层（redis.*、database.*），以兼容线上 config.yaml；新增插件的私有配置归 plugins.<name>.* 命名空间，与 new-setting skill 的描述对齐。

5.1 pkg/idgen 解耦

• 删除 init() 中对 config.Config.App.NodeID 的读取。
• 新增 idgen.Init(nodeID int64) error，由 host 在 Prepare() 之后显式调用（值来自 host 声明的 app.node_id）。
• 未初始化时 NextUint64ID() panic 并点名"未调用 idgen.Init"，而非静默使用 nodeID=0 生成可能与集群冲突的 ID。
• 11 个调用点的 idgen.NextUint64ID() 签名保持不变；依赖 ID 生成的测试需显式 idgen.Init。这是本次迁移唯一会触及既有测试文件之处。

5.2 明确不在范围内

本设计只改变配置的来源与所有权，不动这些既有全局变量：cache.Redis、driver_asynq_worker.RedisOpt/AsynqClient、infra/database.db。它们各自的收敛属于独立议题。

---

6. 错误处理

• Prepare() 以 errors.Join 聚合全部配置错误，哨兵错误：ErrConfigConflict（重复声明不一致）、ErrConfigType（env 值无法转为目标类型）、ErrConfigInvalid（值域校验失败，如 session_age<=0）、ErrConfigNotResolved（Prepare() 之前调用 Bind/Get，错误信息点名正确调用顺序）。
• 所有配置错误经 error 返回，由 cmd 决定终止方式；core 与 extpoints 内不再有 log.Fatalf。
• config.yaml 缺失不是错误（沿用"仅用 env"路径，记一条 info 日志）；CONFIG_PATH 显式指定但读不到或解析失败 → 返回 error。
• 门禁 ConfigEnabled(v ConfigView) bool 只读已解析值、用带 fallback 的访问器，配置错误已在 Prepare() 阶段暴露，因此门禁不引入新的错误源。
• Declare 与 Bind 校验 Target 必须是非 nil 结构体指针，否则返回 error（不 panic）。

---

7. 测试与验收

7.1 测试分层

1. 引擎单测（core/extpoints）：内存 fake ConfigSource，表驱动覆盖优先级四档、标量 env→切片、autoEnable 与显式 env 的优先关系、冲突校验、脱敏 dump、time.Duration 与嵌套结构体 tag 解析、Prepare() 前访问的错误路径。
2. 门禁单测（core）：互斥插件对恰好激活一个、被跳过插件不计入依赖 satisfied、FiberSkipped 参与 Stop 的 LIFO 卸载。
3. 适配器单测（plugins/infra/config）：t.TempDir() 写 yaml + t.Setenv，禁止相对路径。
4. 新旧对拍：迁移期间保留一份临时对拍测试，用仓库现网 config.yaml 与 .env 逐 key 比较旧 pkg/config 与新引擎的输出，证明除 C1–C5 外完全等价；验证通过后随旧包一并删除。
5. 迁移后插件测试：改用 core.WithConfigValues(...) 显式注入；依赖 ID 生成的测试显式 idgen.Init。

7.2 验收标准

1. backend/pkg/config 不存在，grep -rn "pkg/config\|config\.Config" backend/ 零命中。
2. core/ 无 viper import；backend/pkg/ 内不出现任何配置源 import。
3. cmd/app.go 中不存在跨插件配置判断，驱动选型完全由门禁产生。
4. .env、config.yaml、docker-compose 零改动即可启动，行为等价（除已登记的 C1–C5）。
5. 同时挂载 cache 与 cache_memory 而仅激活其一——"预声明 + 门禁"的端到端可验证证据；两条路径（Redis 启用 → asynq；禁用 → inproc）各实跑一次。
6. make code-check、make format、go test ./backend/... 全绿；go run main.go all 实跑通过，覆盖 banner、迁移与门禁。
7. AGENTS.md、new-setting skill 与白皮书中 ctx.Config().Bind(...) 的签名与 key 命名约定更新为已实现的真实 API。

7.3 实施顺序建议

每阶段独立可验证，供实施计划拆分参考：

阶段	内容	验证
P1	配置引擎（core/extpoints/config.go）+ plugins/infra/config 适配器 + 新旧对拍测试	go test ./backend/core/...；对拍输出等价性报告
P2	门禁与 FiberSkipped、App.Prepare() 解析屏障	core 门禁单测；现有测试全绿（此时旧单例仍在，未迁移）
P3	按 infra → drivers → domain → cmd 顺序迁移 27 个文件；idgen.Init 解耦	每层迁移后 go build ./... + 该层测试；最后实跑两条门禁路径
P4	删除 backend/pkg/config 与对拍测试；更新 AGENTS.md/skill/白皮书 API	§7.2 全部验收项逐条复核

---

附录 A：迁移清单

删除：backend/pkg/config/{config.go,model.go,config_test.go}

新增：backend/core/extpoints/config.go、backend/core/config.go、backend/plugins/infra/config/*、各插件内 <name>_config.go 声明文件

需改写的 27 个文件：

分组	文件
组合根	cmd/app.go、cmd/root.go、cmd/banner.go、cmd/app_test.go、cmd/banner_test.go、cmd/redis_plug_test.go
基础库	pkg/idgen/snowflake.go（连带 pkg/idgen/snowflake_test.go）
infra	plugins/infra/cache/redis.go、plugins/infra/database/postgres.go、plugins/infra/database/clickhouse.go
drivers	plugins/drivers/driver_http/engine.go、plugins/drivers/driver_http/middlewares.go、plugins/drivers/driver_asynq_worker/utils.go、plugins/drivers/driver_asynq_worker/utils_test.go、plugins/drivers/driver_asynq_cron/plugin.go
domain/admin	plugins/domain/admin/handler/db.go、plugins/domain/admin/repository/db.go、plugins/domain/admin/service/db.go、plugins/domain/admin/service/status.go、plugins/domain/admin/service/log_switch.go
domain/其他	plugins/domain/auth/session.go、plugins/domain/cap/service.go、plugins/domain/message_gateway/service/service.go、plugins/domain/system/plugin.go、plugins/domain/risk_control/middleware.go、plugins/domain/risk_control/middleware_test.go、plugins/domain/risk_control/logstore/provider.go

注：risk_control/middleware.go、cap/service.go、message_gateway/service/service.go 等处以 config.Config != nil 做存在性判断的分支，在注入式配置模型下不再可能，迁移时一并消除。

---

8. 落地回写（P1 + P2 已实施）

实施结果与本设计原述的差异，均已按下列口径落地：

#	设计原述	落地结果	缘由
R1	§4.3 C1、§6 把 app.session_age<=0 列为内核解析错误	引擎不做值域校验，ErrConfigInvalid 保留但未在内核使用；值域由声明者在 Bind 之后校验（P3 由 auth 承担）	引擎被设计成不认识任何业务 key 的语义，把业务规则塞进内核会破坏该不变式
R2	§3.2 ConfigView.Source(key)	更名 Origin(key)；新增 Value(key) (any, bool)；ConfigExtension 增加 SetSource、Resolved	Source 与类型名 ConfigSource 同文件易混淆；Value 支撑 core.ConfigGet[T]（Go 方法不能带类型参数）；SetSource 进接口以免运行时类型断言
R3	§3.5 仅有 WithShutdownTimeout	新增 App.ShutdownTimeout() 与 SetShutdownTimeout(d) *App	组合根需在 Prepare() 之后把已解析预算写回内核，构造期选项无法表达该顺序
R4	§4.2 时序图把门禁求值画在 Prepare() 内	Prepare() 只建立解析屏障，门禁在 reconcileLocked 每轮调和中求值	App.Use 可在 Prepare() 之后继续挂载插件；只在 Prepare 求值会留下一批永不判定的门禁
R5	未涉及	App 未注入 ConfigSource 时配置能力视为未启用，解析屏障直接放行；实现了 ConfigGatedPlugin 却无配置源的插件 fail fast 点名原因	内核存在大量不使用配置的装配路径（既有测试与嵌入式用法），不能强制要求配置源；但门禁无数据可依时必须报错，而非静默全激活
R6	§4.1 隐含"每个 key 都有 env 覆盖"	env 覆盖面完全由声明决定。旧装载器只对部分 key 提供 env（slow_threshold、conn_max_lifetime 等从未有 env 覆盖），对拍镜像必须精确复刻该覆盖面	否则对拍出现假漂移；放宽某 key 的 env 覆盖是 P3 的声明选择，不构成引擎行为变更
R7	§4.1 "向上最多 5 层查找 config.yaml"	该向上查找会越出 git worktree 边界：从 backend/pkg/config 出发第 5 层可命中父级检出的 config.yaml	属既有行为、非本次引入，但在 worktree 中开发会静默使用另一份检出的配置。对拍测试已改为以入库的 config.example.yaml 所在目录为锚；config.yaml 本身被 gitignore，干净克隆中不存在

分期口径：本设计 §7.3 的 P1 + P2 已实施完成；P3（27 个消费文件迁移、pkg/idgen 解耦）与 P4（删除 backend/pkg/config、移除对拍夹具）由后续计划承接。