YLT 智能助手(小岳)· 25|配置系统、架构契约测试与工程化:让 389 个配置项和 29 条架构规则都可执行
摘要 :一个 300+ 配置项的桌面 Agent,最容易失控的不是功能,而是配置漂移、设置保存后不生效、架构在迭代中悄悄退化。本文拆解 YLT 的三段式配置体系:
defaults做单一事实源,settings_schema声明式驱动设置页,settings.py提供带缓存与类型收敛的只读视图;再讲清"保存配置 ≠ 配置生效"的 reload 链,以及如何用 29 项架构契约测试把循环依赖、端口、RuntimeAPI、UI 边界和异常纪律变成 CI 断言。读完你能得到一套可直接搬到自己项目的配置与架构防腐方案。
一、背景与问题:配置系统是架构退化的第一现场
项目早期,配置是"哪里用到哪里读":业务代码直接调 assistant_value,再手工 int()、手工把 "1" 当布尔。这样的写法能跑,但它同时埋了五颗雷:
- 默认值多处复制 :
5、"1"、"deepseek-v4-flash"散落在业务模块、设置页和测试里,改一处忘两处; - 键名无校验 :
assistant.llm.model拼成assistant.llm.models不会报错,只会静默返回默认值; - 类型转换靠手写 :
"0"、"false"、""、None在不同模块有不同解释,布尔配置尤其混乱; - 设置页与默认值脱节:新增配置项忘了加字段,用户永远看不到;加了字段忘了默认值,保存后读不回来;
- 架构靠自觉 :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。这里有三条约束:
- 视图不可变 :业务层只能读,写配置必须回到
AssistantConfig.set_value,避免"改了一个视图以为改了配置"; - 非法值退回默认而不是抛错:配置错误不应该让整个助手起不来,这符合项目"失败域隔离"的总体原则;
- 范围收敛在视图层做 :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 的选择是只守"一旦破坏就会导致系统性故障"的规则------循环依赖、分层反向依赖、动态门面、静默吞异常------而不去管命名风格、文件长度这类偏好问题。
六、常见坑与最佳实践
- 保存配置不等于配置生效。 任何在构造期固化的东西(线程周期、索引、连接、注册表)都必须在保存后显式 reload。判断标准很简单:问一句"这个值是在
__init__里读的,还是每次用时读的?"前者必须 reload。 - 新增配置项要过三道登记。
defaults.py加默认值、settings_schema.py加字段、settings.py加读取。少任何一处,测试都会失败:少了 defaults,test_settings_reads_are_backed红;少了 schema,test_schema_coverage红;少了 settings,字段存在但没人消费。 - 密钥字段不要写进 JSON 配置。
secret: True的字段走SecretStore,保存空值表示删除。否则密钥会随配置文件被备份、同步、贴进 issue。 - 缓存必须可失效,且失效依据要显式。 用时间 TTL 会出现在"刚改完还没生效"的窗口;用
revision这类单调版本号才能做到"改完立刻生效"。没有revision的对象宁可别缓存。 - 异常不能静默。
except Exception: pass被契约测试直接禁止;边界上的异常至少要degrade()记入错误预算,否则"配置热更新失败"在监控里完全不可见。
七、可复用经验
- 默认值单独成模块,既解决循环依赖,又给"三处消费"提供唯一锚点。
- 配置声明与 UI 生成分离:schema 只描述字段,渲染逻辑集中在设置页,新增配置项不需要碰 UI 代码。
- 只读视图 + 显式写入:读侧用 frozen dataclass,写侧只有一个入口,读写的责任边界非常清晰。
- 用版本号而不是手工清缓存 :
revision是配置系统里最小、最可靠的一致性机制。 - 架构规则要写成测试:能被 CI 执行的架构,才是真的架构;写在文档里的只是愿望。
- 契约测试只守"系统性风险":范围越克制,越能长期留在流水线里。
八、本篇小结
- YLT 的配置是"一份数据、四种投影":
defaults单一事实源、config唯一读写、settings只读视图、schema声明形状。 - 391 个默认值、389 个字段、三百余个读取键之间的一致性,由
test_assistant_settings.py的双向覆盖测试守住。 - 类型化视图用 frozen dataclass + 容错转换 + 范围收敛,把"字符串配置"挡在业务层之外;缓存按
(id(config), revision)失效。 - 保存配置后必须跑 13 个 reload,并清理依赖缓存(如
CacheDAO.clear_kind("rag")),否则就是假热更新。 - 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"
四条选型与执行原则:
- 挑叶子模块:依赖少、报错少、被依赖简单的先上,避免一改就牵动半个系统;
follow_imports = "skip":只校验名单内模块自身,不被未收录模块的历史报错污染;- 只做真实注解 :函数签名、变量注解、
cast、Protocol;禁止批量type: ignore,禁止放宽全局配置; - 每纳入一批就跑全量测试:类型修复不得改变运行时行为。
第一批 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 增补小结
- 行数棘轮把"文件膨胀"变成 CI 失败,逼出真实抽象;上限只能下调。
- mypy 用白名单分批 strict +
follow_imports=skip,先叶子后核心,禁止type: ignore堵口。 - 上游缺注解常常是下游报错的根因,补源头比补调用点收益更高。
- ruff 机械项自动修,unsafe fix 人工审;不追求"零告警"而牺牲语义安全。
- 五层门禁(结构/规模/类型/风格/行为)分工明确,判断标准是"该约束会不会自然退化"。