🧩 积木·施工总工（skill-auto-improve）
在 skill-check（体检医生 + 处方单）之上，补齐「确认 → 动手改 → 升级 → 复盘」的执行闭环。
本技能本身即"积木哲学"的示范：先有蓝图再选积木——输出的是施工蓝图，不是改进清单。
30 秒上手（首次三步）：
1. python scripts/run_check.py —— 检查（未装 skill-check 自动降级内置 8 维）；
2. python scripts/plan_improvements.py —— 生成三层施工蓝图；
3. python scripts/render_blueprint.py —— 可视化蓝图（暗色+红涨绿跌），浏览器打开。
→ 然后：图纸会审（选改哪些）→ 施工许可 → execute_improvements.py 施工 → evaluate.py 验收。
0. 使用方式
| 模式 | 触发 | 流程 |
|---|---|---|
| 改进模式 | "改进我的技能" / "按体检结果修一下" | 块 A→B→C→D→E→F→G（改进闭环） |
| 维护模式 | "更新一下我的技能" | 块 A + 块 H（升级检查/执行）+ 块 F 精简 |
未装 skill-check 时自动降级到内置完整 8 维检查（bundled_check，复用 skill-check 方法论），
流程不卡死；同时提示可安装 skill-check 获取完整可视化仪表板与生态分析（工作流健康度/分类覆盖度）。
0.1 适用性契约（能力边界 + 触发方式）
能力之内：已有技能的 改进 / 升级 / 复盘 / 下线（三层体系 L1/L2/L3）。
边界之外（不做什么）：
- 不创建新技能（从零开发 → 用 skill-creator）；
- 不调试运行时行为（只改静态文件；运行时问题用调试类技能）；
- 不替代 skill-check 做纯体检（只要体检/看报告 → 用 skill-check）；
- 不自动写：所有写/升级必经两轮确认；
- 单次施工范围：默认 focus 强推（≤5）+ 用户指定，避免全量空转。
触发方式：
- 默认 user-invoked（"改进/升级我的技能"才触发；写操作属性决定）；
- 自动化链路可跑只读子流程（自动检查+方案+升级检查，写仍人工确认）；
- 触发差异化：description 已声明"不替代 skill-check 体检"；"检查/体检/看报告"类词不触发本技能（防误触写操作技能）。
1. 八块流程（积木式）
- 块 A 复用检查
scripts/run_check.py：定位 skill-check →audit_engine.py --json
拿audit_latest.json，并加载eco_report.json（工作流/覆盖/重叠/大体积） upgrade_report.json（升级建议）。三份产物 = skill-check 积木式输出的完整数据源；
缺失仅告警不阻塞。产出state/check_output.json。- 块 B 画像适配：读运行用户自己的
~/.workbuddy/USER.md/SOUL.md（若有）加权；
无则回落通用画像。绝不硬编码任何个人画像。 - 块 C 制定方案：三层改进体系——L1 单技能 issue→
repair_strategies.json映射 - 9 积木块→分类矩阵（§4）；L2 8 维评分逐维处理（§4.1，v0.1.0 支持 profile weight_map 调整阈值）；
L3 兜底清单（references/layer3-checklist.md，清单 v1.2 12 条带地基/框架/装修优先级权重）。
已实现：scripts/plan_improvements.py（L1/L2/L3 蓝图生成 + delta_calibration 闭环校准） scripts/layer3_scan.py（L3 机械扫描 9 项）+scripts/layer3_semantic.py（L3 语义扫描 6 项，v0.1.0 新增）scripts/profile_adapter.py（通用画像，v0.1.0 支持域→维度权重映射）。
输出施工蓝图（phase/depends_on/order/opinion，layer=L1|L2|L3，
render_mode 按 §1.6 自动选择 linear/topo）。- 块 D 确认互动：第一轮=图纸会审（审蓝图+提意见）→ 第二轮=施工许可（最终执行确认，含升级项）。
状态机与话术见references/interaction-contract.md（含"只修强推"快捷选项）。 - 块 E 执行修改：
scripts/execute_improvements.py施工管理器
（备份/验证/回滚/标记/施工指引 + v0.1.0 L2 确定性修复）；L1 委托auto_repair.py；
L2 确定性修复（frontmatter 字段补全/pycache 清理）由auto_fix_l2.py脚本化执行；
L2/L3 语义类 agent 按施工指引用 Edit/Write 动手。按蓝图 order 施工，base_kind决定叠加/替换/修补；
每项备份+定向验证+失败回滚。 - 块 F 评估复盘：
scripts/evaluate.py重跑体检算 before/after Δ - 积木自体检（用了哪些块/哪些陈旧）+ 工程档案（
improvement_history.json） - v0.1.0
delta_calibration.json（expected_delta 闭环校准，EMA α=0.3）。 - 块 G 最佳实践库：
references/best-practices/（wiki 46 篇 + plans + cases），bp_lookup检索 + 组合方案包 + 复盘归档。 - 块 H 升级维护：
scripts/upgrade_manager.py封装
skillhub upgrade --check-only/--dir/--slug，确认后执行；前记版本到upgrade_state.json。
2. 交互契约（两轮确认，缺一不可）
- 图纸会审：展示施工蓝图（分阶段/依赖/观点/改前→改后预估 + 升级项），问：① 选哪些改；② 对蓝图有其他想法？→ 修订后重审。
- 施工许可：展示最终施工单（将动手的文件、备份位置、施工顺序），请用户明确"执行确认"。
原则：无确认不写文件、不升级；单 issue 走 linear 简化（只省拓扑，不省观点）。
程序化门禁（v0.1.0）：除对话两轮确认外，scripts/confirm_blueprint.py 提供状态机化的硬门禁——
init → record-round1（图纸会审）→ grant-permit（施工许可）推进 confirmation_state.json 的状态
（BLUEPRINT_READY → ROUND_1_DONE → PERMIT_GRANTED → EXECUTION_STARTED）；execute_improvements.py
施工前经 check_permit() 校验许可状态，未授权则拒绝写文件。向后兼容：当 confirmation_state.json
不存在时 check_permit() 放行（允许纯对话流程），不卡死旧会话。状态枚举与 CLI 详见
references/interaction-contract.md。
3. 安全护栏（核心两条不可破）
- 先备份后改：任何写操作前备份到
state/backups/（L1 复用 auto_repair 备份约定）；升级前记录当前版本。 - 失败回滚：验证失败立即回滚并标记，不静默。
- 全面修改/升级允许，但必经两轮确认；改非
agent_created技能提示"可能被下次 upgrade 覆盖"。 - 对个人目录（Desktop/Downloads 等）的
rm -rf/shutil.rmtree危险命令禁止（content_policy 底线）。 - 环境安全单源原则：⑦ 环境安全块主消费 skill-check 的 dim7 结果；降级/自检用
references/security-rules.json（与 audit_engine.py 同步）。
4. 三层改进体系
L1 · 积木块分类处理（skill-check 输出级，9 块 → 策略）：
| # | skill-check 积木块 | 处理策略 | 预期效果 |
|---|---|---|---|
| ① | 工作流健康度 | 定向修复链（补 missing/升级 lagging/补 profile 空链） | broken→ok |
| ② | 等级分布 | ≤B 档进改进池，A 档仅记录 | avg_score Δ>0 |
| ③ | 技能覆盖度/能力空白 | 安装建议（find-skill-skillhub 可插拔，skillhub 优先） | 空白 0→≥1 |
| ④ | 疑似功能重叠 | 合并/删冗余（备份）/标注 | 重叠归零 |
| ⑤ | 升级建议 | 块 H 确认后 skillhub upgrade |
本地=远端 |
| ⑥ | 大体积技能 | 瘦身（移 assets/清 pycache/压缩） | 体积↓ |
| ⑦ | 环境安全 | 高危优先（危险命令加确认/移除） | P0 归零 |
| ⑧ | 最需要关注 | 强推修复 + 修复指引（opinion=强推） | 分↑ |
| ⑨ | 低质量技能 | L1→L2/L3 重建→无效建议 retire 下线 | 无僵尸 |
L2 · 8 维评分分类处理（单技能维度级）：results[].dims 8 维
（完整性/准确性/可用性/性能/安全性/维护性/兼容性/体验）逐维 <4.5（安全性 <5.0）进改进；
<3.0 强推。生态弱维 → 统一模板"补课"。
L3 · 兜底改进机制（skill-check 之外）：references/layer3-checklist.md 12 条
（清单 v1.2：地基/框架/装修三级优先级权重）——description 触发质量/渐进式披露/讲理 vs 命令/防 overfit/
脚本化/验证闭环/上下文预算/资源直说/结构化/经验资产化/治理字段/组合性；机械类（9 项）
由 layer3_scan.py 脚本扫描；语义类（6 项，标 ★）由 layer3_semantic.py（v0.1.0 新增）
启发式代理 + needs_agent 标记附结构化判定指引；命中带 wiki 佐证，layer=L3。清单自增长：
每轮复盘（块 F）核对新模式→新增条目+归档 cases/→更新版本；连续 3 轮无命中降级清理（见清单"迭代与自增长"）。
三层命中项合并进同一蓝图，统一走图纸会审→施工许可。
4.2 语义类 L3 判定指引（agent 执行，补齐机械扫描覆盖不到的项）
机械扫描（layer3_scan.py）覆盖 9 项；以下语义类由 agent 读 SKILL.md 逐条判定（对照 references/layer3-checklist.md 第 1/8/9/10/11/12 条）：
| 语义项 | 判定方法（agent 检查 SKILL.md） | 命中 → 措施 | wiki 佐证 |
|---|---|---|---|
| ① description 触发质量（深判） | 描述是否同时回答 WHAT+WHEN？是否用用户真实说法？是否有"勿触发"边界句？ | 重写描述（≤1024 字符） | 11/12 |
| ⑧ 资源直说+确认 | 含 scripts/ 时，读写/网络/凭据接触是否显式声明？删除/覆盖/外发是否要求确认？ | 补资源声明与确认点 | 14 |
| ⑨ 结构化可检索性 | 触发意图/输入输出/阶段是否结构化字段（SSL 思想），还是埋没在长文？ | 补结构化字段 | 14 |
| ⑩ 经验资产化 | 内容是"一次性问答"还是"可复用方法/SOP"？ | 方法化沉淀 | 10 |
| ⑪ 治理字段 | 缺 owner/version/scope/tools/never/review/retire 中哪些？ | 补治理字段 | 19 |
| ⑫ 组合性/重复 | 能力是否孤立？与生态内既有技能是否重复（联动 L1④）？ | 组合或合并建议 | 20/21 |
判定结果以 layer=L3、issue_type=semantic_xxx 追加进蓝图（与机械项同走确认流程）。
4.3 自我进化双闭环（动态策略排名 + 知识库反哺）
除基础三层体系外，本技能实装了两套数据驱动的自进化机制（此前未写入文档，本次补齐）：
① 动态策略排名 scripts/strategy_registry.py（块 C/F 调用）
- 为每个 issue_type（如 missing_frontmatter / low_description / overlap …）
维护一套 EMA 收敛的成功率/Δ 增益统计，get_ranking() 据此动态排序改进项优先级，而非写死权重。
- update_outcomes(executed, deltas) 在块 F 复盘时回写实测结果；冷启动用 repair_strategies.json 自举。
- tune_thresholds()（Phase C 阈值自适应）——实测低于预期的 issue_type 自动下调检出门槛，让" noisy 但有效"的项浮上来。默认每 N 轮复盘触发一次（见 evaluate.py）。
② 知识库自进化 scripts/kb_manager.py（块 G/F 调用）
- 双闭环：案例蒸馏（块 F 把正 Δ 的技能归档到 best-practices/cases/，distill_patterns()
按 issue_type 聚类提炼可复用模式）→ wiki 反哺（提炼出的新模式写回 best-practices/wiki/，
下次块 C 经 bp_lookup 懒加载为动态检索层）。
- 与 layer3-checklist.md 的"清单自增长"联动：新模式稳定命中 3 轮后沉淀为正式清单条目（带版本号）。
> 两套机制的数据契约：state/strategy_registry.json（排名矩阵）+ state/improvement_history.json（执行历史，供蒸馏与校准）→ 均不随包发布，首次运行冷启动自举。
5. 升级维护（块 H，必备）
SkillHub 不会自动更新已安装技能；是否升得动取决于该 skill 的 config.json 是否声明 update_url（未声明打印 "missing update URL" 跳过）。
skillhub upgrade --check-only --dir ~/.workbuddy/skills # 只读检查
skillhub upgrade --dir ~/.workbuddy/skills # 升级全部（确认后）
skillhub upgrade --slug <slug> --dir ~/.workbuddy/skills # 升级单个
升级前记录版本到 state/upgrade_state.json；--force 在受限环境可能因 rmtree 失败，捕获并提示手工处理。
6. IMA 最佳实践同步（可选，块 G 增强）
当运行环境已配置 IMA（~/.config/ima/ 凭证有效）且用户授权时，可调 ima-skills
从用户指定知识库（默认「神圣凯莎知识宝库」）拉取 skill 最佳实践，生成/更新
references/best-practices/wiki/*.md。每个 wiki 头部标注来源（v0 本地播种 / v1 IMA 同步）可追溯。
7. 目录结构
skill-auto-improve/
├── SKILL.md # 本文件（入口）
├── _meta.json # 发布元数据
├── scripts/
│ ├── _common.py # 稳定性加固共享（原子写/错误信封/运行锁/安全读）
│ ├── locate_skillcheck.py # 定位+校验 skill-check
│ ├── run_check.py # 复用检查（三源加载 / 降级）；抽出 run_check_core() 无锁核心供 evaluate 调用
│ ├── bundled_check.py # 内置完整 8 维检查（复用 skill-check 方法，无 skill-check 时兜底）
│ ├── plan_improvements.py # 制定方案+蓝图化（L1/L2/L3 + delta 校准 + profile 阈值）
│ ├── layer3_scan.py # L3 机械扫描（9 项可脚本化兜底检查）
│ ├── layer3_semantic.py # L3 语义扫描（6 项：description/资源/结构化/经验/治理/组合性）
│ ├── bp_lookup.py # 最佳实践检索 + 组合方案包（含 kb_manager 动态层懒加载）
│ ├── auto_fix_l2.py # L2 确定性修复（frontmatter 补全 / __pycache__ 清理，须经外层备份）
│ ├── execute_improvements.py # 施工管理器（备份/验证/回滚 + L2 自动修复 + confirm 门禁）
│ ├── upgrade_manager.py # 升级维护
│ ├── evaluate.py # 复盘评估 + delta_calibration 闭环 + 案例归档
│ ├── doc_fmt_check.py # 文档格式规范自检（只读，发布前跑：标题/代码块/索引/树对齐）
│ ├── confirm_blueprint.py # ★确认状态机门禁（图纸会审→施工许可；confirm / check_permit 子命令）
│ ├── strategy_registry.py # ★动态策略排名（EMA 收敛 + tune_thresholds 阈值自适应）
│ ├── kb_manager.py # ★知识库自进化（案例蒸馏 → wiki 反哺，双闭环）
│ ├── profile_adapter.py # profile → weight_map 适配（域→L2 维度权重）
│ └── render_blueprint.py # 蓝图渲染（终端树状图，30 秒上手调用）
├── references/
│ ├── best-practices/ # wiki 46 篇（00-INDEX 索引）+ plans/ + cases/
│ ├── security-rules.json # 环境安全自检快照
│ ├── interaction-contract.md # ✅ 确认互动状态机（图纸会审→施工许可）
│ ├── layer3-checklist.md # ✅ L3 兜底清单（12 条，清单 v1.2 地基/框架/装修优先级 + 自增长）
│ └── faq.md # ✅ 避坑（12 问）
└── state/ # 运行时（不随包发布）
├── check_output.json # 块 A 产物（三源+9 积木块）
├── improvement_plan.json # 施工蓝图（可续跑）
├── delta_calibration.json # expected_delta 闭环校准（EMA α=0.3）
├── confirmation_state.json # 确认状态机快照（图纸会审/施工许可状态）
├── strategy_registry.json # 动态策略排名矩阵
├── improvement_history.json # 施工执行历史（供复盘/校准）
├── upgrade_state.json # 升级维护状态
└── backups/ # 改动前备份
8. FAQ / 避坑
- 未装 skill-check：自动降级 bundled_check（内置完整 8 维检查，复用 skill-check 方法论），不崩；提示可安装获取完整生态分析。
- 稳定性（v0.1.0 加固）：所有脚本带 错误信封（友好提示）、state 原子写（防半写损坏）、
运行锁（防自动化+手动并发）、超大目录/文件防护（5000 文件/1MB 截断）、备份保留 3 份、回滚前校验。
异常时提示"可重试/删除 state 重跑"。 - 升级块空：无可用升级（都声明 update_url 且最新）或 skillhub 未装——优雅跳过并提示。
- 改了非自建技能：提示可能被下次
skillhub upgrade覆盖，由用户权衡。 - 个人目录危险命令：一律禁止（content_policy 底线），建议项沿用 DANGER_PATTERNS 检测。
> 符号约定（全文档统一）：★ = 核心机制（未文档化过的关键能力）；✅ = 已实现；🧩 = 品牌标识；
> ①②③…⑫ = 枚举项编号（L1 积木块 / L3 清单条目）。README 与 references 同步遵守。
