语义层开发者维护手册

本手册面向维护 semantic-plane/ 的开发者、Data Steward、DPO。
目标是让你能稳定完成：编写资产 → 校验 → 发布 → 回归验证。

1. 快速开始

uv sync
task sp:validate

建议每次修改后至少执行：

task sp:validate
task sp:check:version
task sp:diff

2. 资产类型与路径

类型	路径模式	顶层键
表资产	domains/{domain}/*.yaml	table_asset
指标资产	domains/{domain}/metrics/*.yaml	metric_asset
术语	terms/*.yaml	business_terms
术语关系	term_relationships/*.yaml	term_relationships
Few-shot	few_shots/*.yaml	few_shot_examples
关联规则	join_rules/*.yaml	join_rules
业务规则	business_rules/*.yaml	business_rules（或 singular）
业务上下文	business_contexts/*.yaml	business_contexts（或 singular）

3. 命名与版本规则

ID 命名前缀

• tbl_、col_、met_、jr_、term_、tr_、br_、bc_、fs_

版本号（SemVer）

• PATCH：文案修正、不改变业务语义
• MINOR：增强说明/同义词/消歧矩阵等
• MAJOR：指标逻辑、规则表达、绑定关系等语义变化

所有修改必须提升版本，CI 会执行版本递增检查。

4. 编写时必须满足的约束

1. 双语字段成对出现（*_zh 与 *_en）。
2. 描述写业务语义，不写“技术空话”。
3. 敏感字段设置 sensitivity_level 与 llm_exposure_policy。
4. 引用型字段（bound_*、replacement）必须能跨层解析到真实资产。
5. 反模式（anti_patterns）要写“禁止做什么”。

5. 校验工具详解（当前仓库）

命令	脚本	作用
task sp:validate:yaml	validate_all_yaml.py	JSON Schema 校验
task sp:validate:sql	validate_sql_definitions.py	SQL 文本语法检查
task sp:validate:refs	validate_cross_layer_refs.py	跨层引用与替代链检查
task sp:check:version	check_version_bump.py	变更文件版本递增检查
task sp:diff	analyze_metadata_diff.py	PR 变更摘要

6. 变更发布链路

1. 开发分支修改 YAML。
2. 本地校验全部通过。
3. 提交 PR，等待 CI。
4. 合并后执行 task dp:publish-sp 发布到 S3。
5. Admin Backend 自动检测 S3 变更，执行 R+V+G pipeline。
6. 新规则在运行时立即参与检索与提示注入。

7. 全量与增量发布

增量（按 git diff）

uv run python scripts/build_changeset.py --base origin/main -o changeset.json

全量（重建）

uv run python scripts/build_full_changeset.py -o full_changeset.json

发布到 S3

task dp:publish-sp

8. 常见问题

Q1: 规则写了但运行时没生效？

排查顺序：

1. task sp:validate 是否通过
2. 是否执行了 task dp:publish-sp（Backend 自动同步后生效）
3. 规则是否被 bound_assets / bound_terms 正确绑定
4. 规则表达是否能被 guardrails/prompt 实际消费

Q2: 新术语无法召回？

1. 检查 business_terms 文本是否具备可检索描述
2. 检查生命周期状态是否可用（非 retired）
3. 检查是否已通过 task dp:publish-sp 发布并等待 Backend 自动同步完成

Q3: PR 报 version bump 错误？

说明你修改了 YAML 但没增版本，按变更级别提升 version 后重提。