YLT 智能助手(小岳)· 25|配置系统、架构契约测试与工程化

YLT 智能助手(小岳)· 25|配置系统、架构契约测试与工程化:让 389 个配置项和 29 条架构规则都可执行

摘要 :一个 300+ 配置项的桌面 Agent,最容易失控的不是功能,而是配置漂移、设置保存后不生效、架构在迭代中悄悄退化。本文拆解 YLT 的三段式配置体系:defaults 做单一事实源,settings_schema 声明式驱动设置页,settings.py 提供带缓存与类型收敛的只读视图;再讲清"保存配置 ≠ 配置生效"的 reload 链,以及如何用 29 项架构契约测试把循环依赖、端口、RuntimeAPI、UI 边界和异常纪律变成 CI 断言。读完你能得到一套可直接搬到自己项目的配置与架构防腐方案。


一、背景与问题:配置系统是架构退化的第一现场

项目早期,配置是"哪里用到哪里读":业务代码直接调 assistant_value,再手工 int()、手工把 "1" 当布尔。这样的写法能跑,但它同时埋了五颗雷:

  1. 默认值多处复制 :5、"1"、"deepseek-v4-flash" 散落在业务模块、设置页和测试里,改一处忘两处;
  2. 键名无校验 :assistant.llm.model 拼成 assistant.llm.models 不会报错,只会静默返回默认值;
  3. 类型转换靠手写 :"0"、"false"、""、None 在不同模块有不同解释,布尔配置尤其混乱;
  4. 设置页与默认值脱节:新增配置项忘了加字段,用户永远看不到;加了字段忘了默认值,保存后读不回来;
  5. 架构靠自觉 :UI 直接 import 存储层、except Exception: pass、Runtime 方法用 setattr 动态挂载------这些问题在 code review 里能发现,但挡不住下一次提交。

YLT 的应对不是"写一份配置规范文档",而是把规范变成可执行的结构与测试 。目前的数字是:ASSISTANT_DEFAULTS 391 个键,设置页声明 389 个字段(其中 2 个是密钥),settings.py 读取其中三百余个键,架构契约测试 29 项断言,全量回归 958 个用例。这些数字之间的一致性,全部由测试守住。


二、架构位置:配置在系统中的四条通路

#mermaid-svg-JHoVyddiVcPFww7S{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-JHoVyddiVcPFww7S .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-JHoVyddiVcPFww7S .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-JHoVyddiVcPFww7S .error-icon{fill:#552222;}#mermaid-svg-JHoVyddiVcPFww7S .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-JHoVyddiVcPFww7S .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-JHoVyddiVcPFww7S .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-JHoVyddiVcPFww7S .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-JHoVyddiVcPFww7S .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-JHoVyddiVcPFww7S .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-JHoVyddiVcPFww7S .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-JHoVyddiVcPFww7S .marker{fill:#333333;stroke:#333333;}#mermaid-svg-JHoVyddiVcPFww7S .marker.cross{stroke:#333333;}#mermaid-svg-JHoVyddiVcPFww7S svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-JHoVyddiVcPFww7S p{margin:0;}#mermaid-svg-JHoVyddiVcPFww7S .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-JHoVyddiVcPFww7S .cluster-label text{fill:#333;}#mermaid-svg-JHoVyddiVcPFww7S .cluster-label span{color:#333;}#mermaid-svg-JHoVyddiVcPFww7S .cluster-label span p{background-color:transparent;}#mermaid-svg-JHoVyddiVcPFww7S .label text,#mermaid-svg-JHoVyddiVcPFww7S span{fill:#333;color:#333;}#mermaid-svg-JHoVyddiVcPFww7S .node rect,#mermaid-svg-JHoVyddiVcPFww7S .node circle,#mermaid-svg-JHoVyddiVcPFww7S .node ellipse,#mermaid-svg-JHoVyddiVcPFww7S .node polygon,#mermaid-svg-JHoVyddiVcPFww7S .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-JHoVyddiVcPFww7S .rough-node .label text,#mermaid-svg-JHoVyddiVcPFww7S .node .label text,#mermaid-svg-JHoVyddiVcPFww7S .image-shape .label,#mermaid-svg-JHoVyddiVcPFww7S .icon-shape .label{text-anchor:middle;}#mermaid-svg-JHoVyddiVcPFww7S .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-JHoVyddiVcPFww7S .rough-node .label,#mermaid-svg-JHoVyddiVcPFww7S .node .label,#mermaid-svg-JHoVyddiVcPFww7S .image-shape .label,#mermaid-svg-JHoVyddiVcPFww7S .icon-shape .label{text-align:center;}#mermaid-svg-JHoVyddiVcPFww7S .node.clickable{cursor:pointer;}#mermaid-svg-JHoVyddiVcPFww7S .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-JHoVyddiVcPFww7S .arrowheadPath{fill:#333333;}#mermaid-svg-JHoVyddiVcPFww7S .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-JHoVyddiVcPFww7S .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-JHoVyddiVcPFww7S .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-JHoVyddiVcPFww7S .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-JHoVyddiVcPFww7S .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-JHoVyddiVcPFww7S .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-JHoVyddiVcPFww7S .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-JHoVyddiVcPFww7S .cluster text{fill:#333;}#mermaid-svg-JHoVyddiVcPFww7S .cluster span{color:#333;}#mermaid-svg-JHoVyddiVcPFww7S div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-JHoVyddiVcPFww7S .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-JHoVyddiVcPFww7S rect.text{fill:none;stroke-width:0;}#mermaid-svg-JHoVyddiVcPFww7S .icon-shape,#mermaid-svg-JHoVyddiVcPFww7S .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-JHoVyddiVcPFww7S .icon-shape p,#mermaid-svg-JHoVyddiVcPFww7S .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-JHoVyddiVcPFww7S .icon-shape .label rect,#mermaid-svg-JHoVyddiVcPFww7S .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-JHoVyddiVcPFww7S .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-JHoVyddiVcPFww7S .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-JHoVyddiVcPFww7S :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 保存 set_value + save
revision 递增
saved 信号
13 个 reload
守住
守住
守住
ylt/defaults.py

ASSISTANT_DEFAULTS

单一事实源
ylt/config.py

AssistantConfig

扁平点号键 + revision
ylt/settings.py

AssistantSettings

frozen dataclass 只读视图
ylt/settings_schema.py

CONFIG_SECTIONS

声明式字段
设置页

自动生成编辑器

_TAB_GROUPS 分组
Runtime / Engine / Tools

settings 属性按需读取
app._on_settings_saved
tests/test_assistant_settings.py

tests/test_architecture_contracts.py

四条通路各有明确职责:

通路 输入 输出 谁消费
默认值 ASSISTANT_DEFAULTS 任意键的兜底值 config / settings / schema 测试
读写 JSON 文件 扁平点号键、revision 设置页、Runtime
只读视图 任意带 assistant_value 的对象 类型化 AssistantSettings 业务模块
声明 CONFIG_SECTIONS 字段元数据 设置页自动生成 UI

关键点是:四者不是四份配置,而是一份配置的四种投影。默认值只有一份,读写只有一处,视图只读,声明只描述形状。


三、核心原理

3.1 单一事实源:先用模块拆分打断循环依赖

ylt/defaults.py 的模块 docstring 把设计意图写得很直白:ASSISTANT_DEFAULTS 同时被 AssistantConfig、settings 类型化视图、settings_schema 字段声明三处消费,单独成模块是为了打断 config ↔ settings 的延迟导入环。

这不是洁癖。AssistantConfig.settings() 需要延迟导入 settings_from 来避免循环;而 settings.py 又需要默认值。把默认值下沉到 defaults.py 后,依赖方向变成 config → defaults、settings → defaults,环自然消失。很多"循环导入"不是 import 写法问题,而是职责放错了层。

3.2 声明式 schema:设置页不再手写控件

设置页有 389 个字段。手写 389 个 QLineEdit/QCheckBox 不仅冗长,更致命的是"字段与默认值"会持续漂移。YLT 的做法是用字典声明字段,UI 按 type 生成编辑器:

  • type 决定控件与取值函数:bool、string、int、float、choice、password;
  • min/max/step 同时服务 UI 校验与类型视图收敛;
  • advanced 控制折叠,避免高级参数淹没普通用户;
  • secret: True 的字段不进 JSON 配置 ,保存时写入 SecretStore,空值表示删除;
  • section 是分组名,_TAB_GROUPS 负责把分组映射到标签页。

这里有一个容易忽略的工程点:schema 的键必须与默认值双向覆盖。测试 test_schema_coverage 同时检查"默认值都有字段"和"字段都有默认值",test_schema_sections_covered_by_tabs 再检查每个 section 都出现在某个标签页。新增一个配置项忘了登记,CI 直接红,而不是等用户报告"设置页没有这个开关"。

声明式字段对新增能力的价值,在最近一轮升级里体现得很直接:

新增配置 默认值 语义
assistant.autonomy.auto_generate True(总开关 enabled 仍默认 False) 允许从钢印使命自动生成候选目标
assistant.autonomy.max_pending 5 候选积压上限;0 表示停止生成新候选
assistant.autonomy.max_active 3 并行执行上限(原有)
assistant.perception.enabled False 感知总开关,默认不占用相机
assistant.voice.input_enabled / output_enabled False 语音输入/输出分别控制

这些键只改了两处:defaults 加一条、schema 加一个字段声明。设置页标签、类型视图、范围收敛、双向覆盖测试全部自动适配------这就是"字段声明即 UI 契约"的实际收益。

3.3 类型化只读视图:把字符串转型从业务层收走

业务模块不再关心原始值长什么样,只读 frozen dataclass。这里有三条约束:

  1. 视图不可变 :业务层只能读,写配置必须回到 AssistantConfig.set_value,避免"改了一个视图以为改了配置";
  2. 非法值退回默认而不是抛错:配置错误不应该让整个助手起不来,这符合项目"失败域隔离"的总体原则;
  3. 范围收敛在视图层做 :UI 的 min/max 只是提示,真正的边界在 _settings_runtime 等构造器里,例如 max_parallel 至少为 1、reflux_heldout_ratio 被限制在 0--0.5、max_parallel_sources 被限制在 1--4。

3.4 缓存:用 revision 而不是"猜配置变了"

每次读配置都重建 70 多个 dataclass 是浪费;但缓存最怕"配置改了,视图还是旧的"。YLT 用配置版本号做键:_cache_key 返回 (id(config), revision),revision 不可用(字典、假配置)时直接不缓存;save() 与 set_value 都会递增版本号,所以设置页逐个字段写入期间不会读到半新半旧的缓存。落盘用临时文件 + os.replace,避免写到一半崩溃留下损坏的 JSON。

_reader 的容错也值得注意:assistant_value 抛异常时退回默认值,而不是把异常抛给调用方。这让"配置文件损坏"降级为"用默认配置启动",而不是"应用打不开"。

3.5 保存之后:13 个 reload 才让配置真正生效

很多配置系统的 bug 不在读取,而在"保存成功但行为没变"。YLT 在 ylt/app.py 里维护一条显式的 reload 链,覆盖 13 个动作。为什么是这 13 个?因为只有它们持有长生命周期状态,不能靠"下次读配置"自动生效:

reload 动作 必须显式重载的原因
reload_life 心跳间隔、并发度、开关在启动时固化为调度器参数
reload_rag 索引是一次性构建的,语料根/权重变了必须重建
reload_embedder embedding 模型换了,旧向量空间已失效
reload_events 事件日志的文件路径与单文件上限在构造时确定
reload_control 自启动是操作系统状态,需要与配置对账
reload_drivers 设备网关是已注册对象,必须卸载后重注册
reload_proactive / reload_autonomy 后台调度器的 tick 周期与开关
reload_council / reload_external / reload_mcp / reload_strategy / reload_attachments 解析后的配置被缓存为对象/连接

reload_rag 里还有一个容易被忽略的细节:重建索引后必须清掉检索缓存,否则新配置仍然返回旧结果。

配置生效 = 值变了 + 依赖该值的缓存/对象也变了。 只做前者,就是"假热更新"。

3.6 架构契约测试:把"应该"变成"必须"

tests/test_architecture_contracts.py 用 AST 静态分析 + 反射,把 29 条架构规则变成断言。它们覆盖六类风险:

类别 检查项 防的是什么
依赖图 模块级无环、包级无环、器官层不反向依赖 循环导入、分层失效
端口 5 类 Protocol 齐全且成员完整 端口被悄悄删改
门面 RuntimeAPI 显式声明、签名完整类型化 setattr 动态挂载回归
边界 核心不依赖 UI、展示层不直连存储/Qt、UI 不直连实现层 分层被绕过
异常 无 except Exception: pass、关键边界必须 degrade() 故障不可观测
配置 settings_from 始终可用、缓存随 revision 失效 配置系统退化

注意配置相关的那条测试验证的不是"某个字段等于某个值",而是三条契约:无配置可用、坏配置可用、配置变更后缓存必须失效。这三条一旦破坏,整个系统的配置读取都会出问题。

3.7 质量门禁:契约测试只是其中一层

pyproject.toml 把工具链固定下来:pytest 收集 tests/,ruff 选 E/F/W/I 且忽略 E501,mypy 以 Python 3.10 为目标。README 里把门禁写成四层:compileall + ruff → pytest(核心五包覆盖率 ≥70%)→ 模块级覆盖率下限(executor ≥58 / mcp ≥32 / web_tools ≥15)→ mypy 核心阻塞、全包非阻塞。契约测试属于第二层,它不测业务行为,所以跑得很快,适合每次提交都跑。


四、关键代码

4.1 默认值:唯一事实源与模块拆分

python 复制代码
# ylt/defaults.py
"""配置默认值单一事实源。

``ASSISTANT_DEFAULTS`` 同时被三处消费:

- ``ylt.config.AssistantConfig`` 负责读写与迁移;
- ``ylt.settings`` 的类型化视图用同一份默认值;
- ``ylt.settings_schema`` 的字段声明需与键一一对应。

单独成模块是为了打断 ``config ↔ settings`` 的延迟导入环:
config 只依赖 defaults,settings 也只依赖 defaults。
"""

ASSISTANT_DEFAULTS = {
    "assistant.llm.provider": "openai_compatible",
    "assistant.llm.base_url": "https://api.deepseek.com/v1",
    "assistant.llm.model": "deepseek-v4-flash",
    "assistant.runtime.max_steps": 5,
    "assistant.runtime.max_tool_calls": 8,
    "assistant.runtime.max_parallel": 1,
    "assistant.events.persist": True,
    # ... 共 391 个键 ...
}

ASSISTANT_SECRET_KEYS = ("assistant.llm.api_key", "assistant.web.search_api_key")

这段代码的注释比代码更重要:它把"谁能消费默认值"写成了契约。读到这里的人不需要再猜"改默认值会不会影响设置页"------会影响,而且是刻意设计的。

4.2 schema:字段声明即 UI 契约

python 复制代码
# ylt/settings_schema.py
{'section': '模型连接',
 'key': 'assistant.llm.provider',
 'label': '模型供应商',
 'type': 'choice',
 'options': [('openai_compatible', 'OpenAI 兼容'),
             ('deepseek', 'DeepSeek'),
             ('qwen', '通义千问'),
             ('ark', '火山方舟(豆包)'),
             ('zhipu', '智谱 GLM'),
             ('moonshot', 'Moonshot Kimi'),
             ('ollama', 'Ollama 本地'),
             ('anthropic', 'Anthropic')],
 'help': '选择供应商后按预设填充默认接口地址;仍可手动修改。'},
{'section': '模型连接',
 'key': 'assistant.llm.api_key',
 'label': 'API Key',
 'type': 'password',
 'secret': True,
 'placeholder': 'sk-...',
 'help': '加密保存到 YLT/data/ylt_secret.json,不写入 app_config.json,日志脱敏。'},

secret: True 是一个"会改变存储路径"的声明:普通字段进 JSON,密钥进 SecretStore。如果把它做成 UI 层的特殊判断,任何新增密钥字段都可能漏掉;声明在 schema 里,保存逻辑统一读取 field.get("secret"),就不会漏。

4.3 类型化视图:容错转换 + 范围收敛

python 复制代码
# ylt/settings.py
def _bool(value: Any, default: bool) -> bool:
    if value is None:
        return default
    if isinstance(value, bool):
        return value
    if isinstance(value, (int, float)):
        return value != 0
    if isinstance(value, str):
        text = value.strip().lower()
        if text in ("1", "true", "yes", "on", "是", "开"):
            return True
        if text in ("0", "false", "no", "off", "否", "关", ""):
            return False
    return bool(value)

"runtime": RuntimeSettings(
    max_steps=max(1, _int(get("assistant.runtime.max_steps"), 5)),
    max_tool_calls=max(1, _int(get("assistant.runtime.max_tool_calls"), 8)),
    timeout_s=_float(get("assistant.runtime.timeout_s"), 180.0),
    # 只读工具并发度:1 表示完全串行(默认),>1 才启用并发批次
    max_parallel=max(1, _int(get("assistant.runtime.max_parallel"), 1)),
),

_bool 显式接受 "是"、"开"、"否"、"关",是因为设置页早期版本会把中文选项写回配置。兼容这些历史值,比要求用户手工改 JSON 更符合桌面产品的现实。代价是转换函数变长,但这属于"一次写对、处处受益"的复杂度。

4.4 读取器与缓存:正确性优先

python 复制代码
# ylt/settings.py
def _reader(config):
    """返回统一的取值函数:兼容真实配置、字典配置与测试假配置。"""
    if config is None:
        return lambda key: ASSISTANT_DEFAULTS.get(key)
    if isinstance(config, dict):
        return lambda key: config.get(key, ASSISTANT_DEFAULTS.get(key))
    if callable(getattr(config, "assistant_value", None)):
        def _get(key):
            try:
                return config.assistant_value(key, ASSISTANT_DEFAULTS.get(key))
            except Exception:
                return ASSISTANT_DEFAULTS.get(key)
        return _get
    return lambda key: ASSISTANT_DEFAULTS.get(key)

def _cache_key(config) -> tuple[int, Any] | None:
    if config is None:
        return (0, None)
    revision = getattr(config, "revision", None)
    if revision is None:
        return None          # 字典/假配置不缓存,优先保证正确性
    if callable(revision):
        try:
            revision = revision()
        except Exception:
            return None
    return (id(config), revision)

_reader 支持三种输入:真实 AssistantConfig、字典、任意实现 assistant_value 的对象(包括测试假配置和抛异常的坏配置)。这让配置系统在任何环境下都"有值可用",也让测试不需要构造完整配置对象。

4.5 写入与落盘:revision 驱动缓存失效

python 复制代码
# ylt/config.py
def set_value(self, key: str, value):
    self._data[key] = value
    self._touch()

def save(self):
    self._touch()
    self._data["config_version"] = CONFIG_VERSION
    self.path.parent.mkdir(parents=True, exist_ok=True)
    tmp = self.path.with_suffix(".tmp")
    with open(tmp, "w", encoding="utf-8", newline="\n") as f:
        json.dump(self._data, f, ensure_ascii=False, indent=2)
    os.replace(tmp, self.path)

set_value 和 save 都递增 revision,这是缓存正确性的唯一依据。os.replace 在 POSIX 与 Windows 上都是原子替换,避免"写到一半断电"留下半截 JSON。

4.6 保存后的 reload 链

python 复制代码
# ylt/app.py  _on_settings_saved
for action in ("reload_life", "reload_proactive", "reload_autonomy",
               "reload_external", "reload_drivers", "reload_council",
               "reload_strategy", "reload_rag", "reload_embedder",
               "reload_attachments", "reload_events", "reload_control",
               "reload_mcp"):
    try:
        getattr(self.controller, action)()
    except Exception:
        logger.warning("设置保存后执行 %s 失败(忽略)", action)

这段代码只证明了"保存后有人负责重载"。另外两条同样重要:reload_rag 在重建索引后调用 CacheDAO(self.db).clear_kind("rag"),证明"重载后缓存有人负责清理";tests/test_architecture_contracts.py::test_settings_view_always_available 验证无配置、坏配置、revision 变更三种情况,证明"配置系统自己有人负责守门"。三者合起来,才是配置工程化的完整链条。


五、设计权衡

决策 替代方案 为什么不用 代价
扁平点号键 + 单一 defaults 嵌套 dataclass 直接序列化 设置页按字段读写、迁移旧配置都需要扁平键;嵌套结构改一个字段要重写整棵树 键名靠字符串,需要测试防漂移
声明式 schema 驱动 UI 手写每个设置控件 389 个字段手写不可能保持一致 schema 本身成为一种 DSL,需要测试校验
frozen 只读视图 直接把 dataclass 当配置对象用 写入路径会分散,无法统一 revision 与落盘 每次读都可能重建,需要缓存
按 (id, revision) 缓存 全局单例缓存 / 不缓存 单例无法支持测试多配置;不缓存则每次读都重建 70+ 对象 依赖 config 暴露 revision,假配置不缓存
保存后显式 reload 每次读配置都重新构造依赖 索引、线程、网关等对象无法"读一下就好" 13 个 reload 要人工维护,漏一个就是假热更新
AST 契约测试 只靠 code review 人会忘,CI 不会 静态规则可能误报,需要白名单与例外说明

最值得说的是最后一条。契约测试是一种"用测试表达架构决策"的做法,它的成本不在写,而在维护规则的准确性:规则太松没意义,太严会逼着开发者写绕过代码。YLT 的选择是只守"一旦破坏就会导致系统性故障"的规则------循环依赖、分层反向依赖、动态门面、静默吞异常------而不去管命名风格、文件长度这类偏好问题。


六、常见坑与最佳实践

  1. 保存配置不等于配置生效。 任何在构造期固化的东西(线程周期、索引、连接、注册表)都必须在保存后显式 reload。判断标准很简单:问一句"这个值是在 __init__ 里读的,还是每次用时读的?"前者必须 reload。
  2. 新增配置项要过三道登记。 defaults.py 加默认值、settings_schema.py 加字段、settings.py 加读取。少任何一处,测试都会失败:少了 defaults,test_settings_reads_are_backed 红;少了 schema,test_schema_coverage 红;少了 settings,字段存在但没人消费。
  3. 密钥字段不要写进 JSON 配置。 secret: True 的字段走 SecretStore,保存空值表示删除。否则密钥会随配置文件被备份、同步、贴进 issue。
  4. 缓存必须可失效,且失效依据要显式。 用时间 TTL 会出现在"刚改完还没生效"的窗口;用 revision 这类单调版本号才能做到"改完立刻生效"。没有 revision 的对象宁可别缓存。
  5. 异常不能静默。 except Exception: pass 被契约测试直接禁止;边界上的异常至少要 degrade() 记入错误预算,否则"配置热更新失败"在监控里完全不可见。

七、可复用经验

  • 默认值单独成模块,既解决循环依赖,又给"三处消费"提供唯一锚点。
  • 配置声明与 UI 生成分离:schema 只描述字段,渲染逻辑集中在设置页,新增配置项不需要碰 UI 代码。
  • 只读视图 + 显式写入:读侧用 frozen dataclass,写侧只有一个入口,读写的责任边界非常清晰。
  • 用版本号而不是手工清缓存 :revision 是配置系统里最小、最可靠的一致性机制。
  • 架构规则要写成测试:能被 CI 执行的架构,才是真的架构;写在文档里的只是愿望。
  • 契约测试只守"系统性风险":范围越克制,越能长期留在流水线里。

八、本篇小结

  1. YLT 的配置是"一份数据、四种投影":defaults 单一事实源、config 唯一读写、settings 只读视图、schema 声明形状。
  2. 391 个默认值、389 个字段、三百余个读取键之间的一致性,由 test_assistant_settings.py 的双向覆盖测试守住。
  3. 类型化视图用 frozen dataclass + 容错转换 + 范围收敛,把"字符串配置"挡在业务层之外;缓存按 (id(config), revision) 失效。
  4. 保存配置后必须跑 13 个 reload,并清理依赖缓存(如 CacheDAO.clear_kind("rag")),否则就是假热更新。
  5. 29 项架构契约测试把循环依赖、端口、RuntimeAPI、UI 边界、异常纪律和配置契约变成 CI 断言,让架构退化在提交时就被拦住。

九、下一篇预告

YLT-26|创新点总结与未来演进:作为系列收官,把 12 项创新点逐一拆成"解决什么问题、怎么实现、代价是什么、证据在哪",给出能力边界与三条演进路线------多租户服务化、更强的原生工具调用、记忆与进化的度量闭环,最后用一张全局架构图收束整个系列。


十、增补(2026-11):质量门禁的第二步------行数棘轮、mypy strict 与 ruff 收敛

上一版把"架构规则测试化"讲到了 29 项 AST/反射断言。这一轮又补了三类门禁,把"结构约束"扩展到规模、类型、风格三个维度。

10.1 行数棘轮:只降不升

核心模块最容易在迭代中膨胀成"什么都往里塞"的上帝文件。YLT 的做法是给几个关键文件设上限,且只能降低、不能提高:

文件 上限
ylt/ui/theme_qss.py 766
ylt/ui/status_center.py 809
ylt/agents/orchestrator.py 666
ylt/ui/assistant_panel.py 500

规则写在 tests/test_architecture_contracts.py::test_module_size_ratchet。它的效果不是"禁止加功能",而是逼出抽象:想加 30 行样式,就必须先抽掉 30 行重复。这轮 UI 改造两次触顶,最后靠"合并单行规则 + 用 HTML 彩点替代控件 + 循环建标题"压回契约内------每一次都促成了真实的去重。

关键设计:棘轮值只能手改下调。 一旦允许"这次先加 5 行,下次再减",棘轮就失效了。

10.2 mypy:分批纳入 strict,而不是一次性全量

全量 mypy 在这个规模下有约 5900 个报错,一次性清零不现实,且会诱导开发者用 # type: ignore 堵口。YLT 走白名单分批:

toml 复制代码
[[tool.mypy.overrides]]
module = [
    "ylt.telemetry",
    "ylt.runtime.event_topics",
    "ylt.runtime.facades",
    "ylt.settings_schema",
    "ylt.settings_schema.parts.p1",
    # ... p2 ~ p6
    "ylt.attachment_spec",
    "ylt.defaults",
    "ylt.embedding",
    "ylt.errors",
    "ylt.paths",
    "ylt.prompts",
    "ylt.secrets",
    "ylt.text",
    "ylt.tools.video_tools",
    "ylt.vector_store",
]
strict = true
follow_imports = "skip"

四条选型与执行原则:

  1. 挑叶子模块:依赖少、报错少、被依赖简单的先上,避免一改就牵动半个系统;
  2. follow_imports = "skip":只校验名单内模块自身,不被未收录模块的历史报错污染;
  3. 只做真实注解 :函数签名、变量注解、cast、Protocol;禁止批量 type: ignore,禁止放宽全局配置;
  4. 每纳入一批就跑全量测试:类型修复不得改变运行时行为。

第一批 20 个模块落地后,总报错从 5931 降到 5893,有报错的文件从 287 降到 273。收益不只是数字 :defaults.py 给 CONFIG_SECTIONS 补上 list[dict[str, Any]] 注解后,顺带消除了 2 个下游报错------这说明很多"下游类型错误"的根因是上游缺注解。

10.3 ruff:131 处 import 排序用自动修复,风格项留手审

ruff check 从 141 项降到 4 项,其中 131 项是 I001(import 排序),直接 --fix 批量处理;剩下 4 项是 E731(lambda 赋值)、E702(分号)这类 unsafe fix------自动改写可能改变语义,必须人工确认,因此保留。

原则:机械问题交给工具,语义问题交给人。 不要为了"零告警"去强行 unsafe fix。

10.4 五层门禁的分工

维度 工具 拦截什么
结构 29 项架构契约测试 循环依赖、分层反向依赖、静默吞异常、UI 越界
规模 行数棘轮 上帝文件膨胀
类型 mypy strict 白名单 名单内模块的类型退化
风格 ruff import 顺序、未使用变量等机械问题
行为 958 个回归用例 功能回归

五层各管一段,互不替代。判断一条规则该不该进 CI,标准只有一个:它是否会随时间自然退化。 会退化的(依赖方向、文件长度、类型标注)必须自动化;不会退化的(命名偏好)不必。

10.5 增补小结

  1. 行数棘轮把"文件膨胀"变成 CI 失败,逼出真实抽象;上限只能下调。
  2. mypy 用白名单分批 strict + follow_imports=skip,先叶子后核心,禁止 type: ignore 堵口。
  3. 上游缺注解常常是下游报错的根因,补源头比补调用点收益更高。
  4. ruff 机械项自动修,unsafe fix 人工审;不追求"零告警"而牺牲语义安全。
  5. 五层门禁(结构/规模/类型/风格/行为)分工明确,判断标准是"该约束会不会自然退化"。
相关推荐
真上帝的左手4 小时前
7、网络安全-认证鉴权
web安全·架构·系统架构·系统安全
dahaihua3331 天前
用 SysML 表达航电系统架构(附建模示例)
设计模式·重构·系统架构·集成测试·需求分析·学习方法
جيون داد ناالام ميづ1 天前
RocketMQ 入门第二篇:吃透系统架构与核心组件(从角色到实战细节)
系统架构·rocketmq·java-rocketmq
艺杯羹3 天前
1Panel 装好后 ufw 仍是 inactive:一次服务器安全盲区复盘
服务器·数据库·安全·网络安全·系统架构·实战·1panel
装不满的克莱因瓶3 天前
设计模式之策略模式核心概念和应用场景
java·后端·设计模式·架构·系统架构·策略模式
真上帝的左手4 天前
30. 技术专题-‌应用框架组件-分布式架构
分布式·架构·系统架构·分布式架构
吴建旭 智宅焕6 天前
智能家居B端客户路径诊断的系统架构设计与实现:背景采集、经验分层与交付确定性
系统架构·智能家居
长不大的杨瑞杰9 天前
ChatGPT 广告技术栈架构拆解:多轮意图、LLM 工具编排、ANN 召回与拍卖闭环
人工智能·chatgpt·系统架构·推荐系统·广告
艺杯羹10 天前
Windows原生软件锁设计:从暴力杀进程丢数据到零轮询事件驱动架构
windows·系统架构·开源·开源软件·内存管理·开源协议