| name | observability-publish |
| description | 从 omni-execution-log.json 聚合生成 omni-observability-result.json，并调用 ssd_step_insert 写入 ssd_step_info。当 changes 下已有执行日志时使用。 |
| argument-hint | [--dry-run] [--default-branch 分支名] [FEATURE_DIR 或 omni-execution-log.json 路径] |
observability-publish（执行日志 → 可观测性 JSON → 入库）
适用场景
- 某特性目录下已经存在
omni-execution-log.json（根为步骤对象数组）。
- 需要生成
omni-observability-result.json（按 sdd_step / step_name 取最后一次执行），并写入数据库（或仅校验）。
用户如何触发（调用本 Skill）
在 Cursor / Claude Code 中任选一种即可：
- @ Skill：在对话里引用本技能（
observability-publish），并说明特性目录或 omni-execution-log.json 的完整路径；若仅校验数据库，写明 --dry-run（仅对入库步骤生效）。
- 斜杠命令（若已加载仓库命令）：执行
/observability-publish，并按提示补充路径或 FEATURE_DIR。
- 自然语言：例如：「对
changes/002-xxx 执行 observability-publish：生成可观测性 JSON 并入库」。
由 Agent 读取本文件后，在终端执行下方脚本，禁止只口述不执行（除非用户环境禁网禁库）。
路径约定
- 仓库内脚本目录：
.claude/skills/observability-publish/scripts/python/（相对仓库根目录）。
- 默认输入：
{FEATURE_DIR}/omni-execution-log.json。
- 默认输出：
{FEATURE_DIR}/omni-observability-result.json（由聚合脚本写在与输入同目录）。
FEATURE_DIR 可为环境变量，或用户给出的 changes/<feature-id>-... 绝对/相对路径。
执行步骤（必须按序）
1. 聚合（清洗 / 按步骤取最后一次）
在仓库根目录执行（按实际路径替换）：
python .claude/skills/observability-publish/scripts/python/omni_build_observability_result.py -i "<FEATURE_DIR>/omni-execution-log.json"
可选：
- 指定输出文件：
-o "<FEATURE_DIR>/omni-observability-result.json"（通常省略，默认即此名）。
- 日志里完全没有
branch 时补足根级分支：
--default-branch "<特性目录名或分支名>"。
成功后应得到 omni-observability-result.json，且含 step_results、summary、invalid_records（若有无效行）。
2. 入库
未要求试跑时执行：
python .claude/skills/observability-publish/scripts/python/ssd_step_insert.py -i "<FEATURE_DIR>/omni-observability-result.json"
若步骤数据中可能缺 branch，且根对象也无 branch / feature_desc，需传入与上一步相同的
--default-branch。
用户要求不写库、只校验时，在本命令上加 --dry-run：
python .claude/skills/observability-publish/scripts/python/ssd_step_insert.py -i "<FEATURE_DIR>/omni-observability-result.json" --dry-run
注意：--dry-run 仅作用于 ssd_step_insert；聚合脚本仍会写出 omni-observability-result.json。若用户希望连 JSON 都不覆盖，应先备份或改用 -o 写到临时路径，再对该路径 dry-run 入库。
产出核对
- 终端输出：
已写入: ... 与 插入成功，条数: N 或 [dry-run] 将插入 N 条。
- 打开
omni-observability-result.json 查看 summary 与 step_results 是否符合预期。
依赖与失败处理
- 聚合脚本仅依赖 Python 标准库。
- 入库依赖
pymysql 与 ssd_step_insert.py 内 DB_CONFIG；连接失败应向用户说明并保留已生成的 JSON。
相关文档
- 设计约定：
changes/<feature>/execution-observability-skill-plan.md（若存在）。
