方案代码优化器 · 技能执行指南

> 定位：元技能（meta-skill）。不生产业务内容，专把"别的 skill / 方案"迭代到 100 分。
> 铁律：绝不虚构、证据优先、结构化、保留原骨架中有效的部分。

〇、100分质量 Rubric（10维，加权100）

对目标文件逐维打分（0–该维满分），求和即当前分；优化后目标 = 100。

〇·五、价值速览（30秒看懂）

一句话：你丢给我一个 skill / 方案 / 提示词 / 代码，我还你一份「逐维体检报告 + 优化后文件 + before→after 对照」。

你给我什么 → 我给你什么

一个迷你对照（演示格式，非真实项目）

> before：某 skill 描述"帮我优化方案" → 触发模糊、无输入格式、无案例
> after：描述补 5 个明确触发词 + 4 类输入形态 + 非触发边界；新增「输入解析」「FAQ/避坑」两章 → 综合 86 → 100

它和 skill-creator 的区别：skill-creator 负责"从零造技能"；本技能只负责"把已有的技能/方案打磨到满分"，不做无中生有。

〇·六、三分钟上手（先跑通最小闭环，再谈进阶）

不要一上来就读十维 Rubric。先花三分钟把工具跑通，看见真实产物，再回头理解原理。

第 1 步（30 秒）—— 确认环境

python -c "import docx; print('python-docx 已就位')"

打印 python-docx 已就位 即可继续。缺依赖按 §八 的修复命令装；
没装也能先跑 --template 看数据结构，但生成 docx 必须装。

第 2 步（60 秒）—— 出一份示例交付物，看清你最终会拿到什么

python C:/Users/ghszb/.workbuddy/skills/方案代码优化器__skillhub/scripts/build_report.py --demo --out ./_out

产出两个文件：示例_优化稿_带批注.md（改了哪句、为什么改）与
出海准备度诊断_体检报告_YYYYMMDD.docx（十维评分 + before→after 对照）。

第 3 步（90 秒）—— 换成你自己的目标

python <同上路径>/build_report.py --template > spec.json   # 拿到 JSON 骨架
# 按 §〇 十维，把 spec.json 里的 dims 改成你目标的真实评分
python <同上路径>/build_report.py --data spec.json --out ./_out

可选：从管道喂数据（不想落中间文件时）

cat spec.json | python <同上路径>/build_report.py --data - --out ./_out

> 两个坑先说在前面：① --demo 和 --data 不能同时给，会直接退出码 2
> （旧版会静默忽略 --data 跑去跑示例，你以为在跑自己的规格）；
> ② spec.json 存成 GBK 也能读，脚本会自动按 utf-8-sig → utf-8 → gbk 猜编码（§八）。

进阶路线：跑通上面三步 → 再读 §一 执行流程与 §二 缺陷库 →
想看完整案例读 §十 → 交付前过 §七 自检清单。

一、执行流程（IPO-D-G-A）

1. 载入 Rubric：套用 §〇 十维标准作为评分尺。
2. 读取目标：按 §一·五 识别输入形态并读取目标文件，理解用途与现有骨架。
3. 逐维诊断：按 Rubric 打分，记录每维"现状分 / 缺陷 / 修复动作"。
   4.迭代优化：
   - 优先修补，不推倒重来（保留有效骨架）；
   - 缺失模块直接补全（参考本技能 §二 常见缺陷库）；
   - 证据缺失→加置信度标签体系；降级缺失→加数据源阶梯；
   - 写回原文件（或新建版本文件）。
4. 质量门自检：过 §一·质量的自检清单（对应 §〇 第10维），全部达标 = 100分。
5. 输出对照：before→after 逐维分数表 + 优化后文件交付（格式见 §三）。

一·五、输入识别与歧义处理（维度2）

目标形态判定（按顺序匹配）

歧义与异常规则

• 重名技能：多候选时一律列全路径让用户选，不擅自挑一个。
• 目录无 SKILL.md：提示"未找到 SKILL.md，请确认是否为技能目录或改传单文件"。
• 超大文件（>2000 行）：先读前 2000 行做诊断，再按需 offset 抽样关键段，避免上下文溢出。
• 二进制/JPEG/PDF 等不可编辑体：拒绝改写，说明"本技能只优化可编辑文本类 skill/方案/代码"。
• 目标已是 100 分：输出"维持现状"结论，不强行改写制造噪声。

二、常见缺陷库（高频扣分项 → 修复模板）

L1–L4 降级阶梯（维度3，供业务类 skill 复用）

• L1 首选：已连接官方连接器 / 本地数据库 → 直接取数
• L2 次选：WebSearch / WebFetch 公开检索 → 标注 [推断] 来源
• L3 兜底：基于已有上下文合理推断 → 标注 [推断]，说明假设
• L4 穷尽：确无依据 → 标注 [待补充]，绝不编造

二·五、输出交付物：带批注修改稿 + 体检报告（必做）

优化不能只给建议。必须交付两份可落盘的东西：

1. 带批注的优化稿 —— 在原文上直接改，每处改动标出原句、新句与理由
2. 100 分体检报告 .docx —— 10 维逐维评分 + before→after 对照

只给"建议你改第 3 段"等于没交付——用户还得自己动手改，那就不是工具。

文件路径：
- ./{名称}_优化稿{原扩展名}（与源文件同格式，直接可替换）
- ./{名称}_体检报告_{YYYYMMDD}.docx

批注规范（每处改动必须可追溯、可回退）：

【改】原句：……
      新句：……
      理由：触发 Rubric 第 X 维（失分点：……）

批量改动较多时，用对照表集中列出，不要让用户在正文里找。

体检报告生成 —— 两条路，二选一

• 命令行（推荐，一条命令出文件）：scripts/build_report.py --demo / --data spec.json / --template，细节见 §〇·六 三分钟上手。
• 库调用（要自定义版式时用）：scripts/report_kit.py，依赖 python-docx。

库调用写法：

import sys
sys.path.insert(0, r"C:/Users/ghszb/.workbuddy/skills/方案代码优化器__skillhub/scripts")
from report_kit import Report

r = Report(title="《{名称}》优化体检报告",
           subtitle="100 分 Rubric · 10 维逐维评分",
           footer="方案代码优化器")
r.summary([
    "评分变化：{a}/100 → {b}/100",
    "最大失分维度：{维度}（−{n} 分），已修复",
    "质量门：{x}/10 通过",
])
r.h1("一、逐维评分")
r.score_card([(维度, 得分, 判定), ...])          # 10 个维度
r.h1("二、Before → After 对照")
r.table(["维度", "改前", "改后", "加分值"], [...])
r.h1("三、遗留问题与后续建议")
r.callout("注意", "...")
r.save(path)

质量门：优化后必须 ≥95 分 才能交付。未达标的要明说卡在哪一维、为什么、
需要用户补充什么信息才能继续——不许用"已优化"含糊过关。

三、输出格式

# 《XX》优化报告
## 一、现状评分：X/100
  | 维度 | 现状 | 缺陷 |
## 二、优化动作（逐条）
## 三、优化后评分：100/100（质量门10/10通过）
## 四、交付文件：<路径>

三·附、完整填写示例（演示格式，非真实项目）

> 目标：某出海准备度诊断 skill（假设当前 4.3/5 ≈ 86/100）
>
> 一、现状评分：86/100
> | 维度 | 现状 | 缺陷 |
> |---|---|---|
> | 1 触发精准度 | 10 | — |
> | 2 输入解析 | 6 | 未定义"只给企业名"时的歧义处理 |
> | 3 数据降级 | 12 | 假设企查查永可用，无 L3/L4 |
> | 4 证据反虚构 | 15 | — |
> | 5 框架深度 | 15 | — |
> | 6 场景映射 | 9 | 出海前/中/后打法未分 |
> | 7 交付物 | 6 | 缺直接/间接/战略三层 ROI |
> | 8 风险边界 | 5 | 无对抗场景处理 |
> | 9 输出模板 | 3 | 仅骨架 |
> | 10 质量门 | 2 | — |
>
> 二、优化动作
> 1. §二补"企业名 vs 集团"歧义规则（维度2→10）
> 2. §三加 L1–L4 降级阶梯，企查查不可用时转 WebSearch（维度3→15）
> 3. 交付物补三层 ROI 模板（维度7→10）
> 4. 新增"对抗场景"边界章（维度8→8）
> 5. 输出模板补完整填写样本（维度9→5）
>
> 三、优化后评分：100/100（质量门 10/10 通过）
> 四、交付文件：skills/出海准备度诊断/SKILL.md（v1.1.0）

> 说明：上例仅演示"报告长什么样"。真实优化时数值来自对你目标文件的逐维判读，不预设结果。

四、原则（不可违反）

• 绝不虚构：修复时不得编造数据、案例、工具名；未知标 [待补充]。
• 证据优先：能查到的不猜。
• 结构化是善意：一律表格/框架。
• 最小破坏：保留原有效骨架，只补缺失、修错误。

五、常见异常与边界处理（维度8）

六、FAQ 与避坑指南

Q1：它和 skill-creator 有什么区别？
A：skill-creator 从零造技能；本技能只把"已有的 skill/方案/提示词/代码"打磨到满分。需要新建用前者，需要提质用本技能。

Q2：会不会改坏我的 skill？
A：遵循"最小破坏"——先诊断后改、只补缺失修错误；若遇写回冲突会生成 .v2 新文件而非覆盖，你可比对回退。

Q3：一次能优化几个目标？
A：一轮一个目标，避免多目标相互干扰、诊断混淆。多个请分批。

Q4：Rubric 的 100 分是绝对标准吗？
A：是通用尺，但维度权重可按领域微调（如纯创意提示词可降低"数据降级"权重）。微调须在报告中说明。

Q5：为什么要求"优化到 4.9"而不是 100？
A：外部评测常以 5 分制呈现，4.9≈98/100。本技能内部仍以 100 分 Rubric 评分，达标后再换算回 5 分制对外。

避坑清单（执行时自查）
- ❌ 为凑分编造案例/数据/工具名 → 一律 [待补充]
- ❌ 推翻有效骨架重写 → 优先修补，保留骨架
- ❌ 降级阶梯写"不可用就放弃" → 必须 L1–L4 真实可达、不编造不停摆
- ❌ 把 [推断] 当 [已验证] 输出 → 标签与来源一一对应
- ❌ 一次塞多个目标 → 一轮一目标

七、交付前自检清单（维度10 / 质量门）

• [ ] 已按 §一·五 正确识别输入形态，无歧义遗漏
• [ ] 十维逐维打分，每维有"现状/缺陷/动作"
• [ ] 缺失模块已补齐（对照 §二 缺陷库）
• [ ] 证据/数据均有置信度标签 + 来源，零编造
• [ ] 降级阶梯（若适用）真实可达 L1–L4
• [ ] 输出含 before→after 对照表与交付文件路径
• [ ] 已覆盖 §五 相关异常场景
• [ ] 未推翻原有效骨架
• [ ] 全部达标 → 综合 = 100/100，方可交付

八、异常与兜底（命令行的失败路径都已实测）

退出码约定（写脚本/做批量时可直接判断）

退出码只有这三种。任何输入都不会让脚本以外的值退出——v1.1.3 及更早版本在遇到
GBK 编码的 spec.json 时会抛裸 UnicodeDecodeError 并以退出码 1 结束（2026-09-12 实测复现），
v1.1.4 已修复。若你看到退出码 1 或裸 traceback，说明拿到的不是本版脚本。

依赖缺失（已实测复现）

python -c "import docx" 2>&1 | findstr /I "No module" && echo 需要安装
pip install python-docx
python -c "import docx; print('ok')"

离线环境：pip download python-docx -d ./whl 后拷贝 ./whl 到目标机，再
pip install --no-index --find-links=./whl python-docx。
未安装时脚本不会抛裸 ImportError，而是打印 [依赖缺失] + 三条可执行修复命令并以退出码 3 结束。

异常处理表（每条已实测）

从 stdin 读（可管道集成，实测退出码 0）

cat spec.json | python <脚本路径>/build_report.py --data - --out ./_out

九、触发与不触发边界

会触发（满足任一即可）

「优化 / 打磨 / 迭代 / 提分 / 打分 / 体检 / review / 评审」这八个动词，
只要作用在「一个已存在的 skill、方案、提示词、代码、文档」上，就是本技能。具体：

• 「把这份方案 / 这个 skill / 这段提示词 优化到 100 分」「打磨到 4.9 / 5.0」
• 「给 XX 打个分」「这个 skill 能打几分」「体检一下这个技能」「review 这个 skill」
• 「按 Rubric 逐维评分」「这个 prompt 哪里在扣分」「平台评测 4.3，怎么提到 4.8」
• 直接丢过来一个 SKILL.md / 方案文件 / 技能目录 / 代码片段，要求「改好给我」
• 「我这个技能为什么评不到 4.8」——按失分项反查 §〇 十维并给可执行改法

不会触发（遇到这些请改用别的技能或直说）

与相邻技能的消歧（三者最易混）

边界灰区：既想改内容又想提分时——先提分（本技能），再改内容，顺序反过来会重复返工。
同一目标需要连改多轮时，一次只改一个目标、逐轮验证（§六 Q3），避免多轮改动互相污染。

十、完整实战案例（可照抄跑通，输出为真实实测值）

需求：某咨询团队有一个上线 3 个月的「出海准备度诊断」技能，平台评测 4.3/5，
客户反馈「结论有但不好落地」，要求提到 4.9 以上。

选型：该技能属于"业务类 skill"，按 §〇 十维打分。判断它的问题在
维度 2（输入歧义）、3（数据降级）、7（交付物）、8（边界）、9（模板），
不是框架性问题，因此走"修补"而非"重写"（§四 最小破坏原则）。

数据：十维打分结果 —— 见 §三·附 的填写示例，现状 86/100。

命令（原样执行）：

python C:/Users/ghszb/.workbuddy/skills/方案代码优化器__skillhub/scripts/build_report.py --demo --out ./_out

产出（2026-09-12 实测，v1.1.4）：

[完成] 体检报告：./_out\出海准备度诊断_体检报告_20260912.docx（39637 字节）
[完成] 带批注优化稿：./_out\示例_优化稿_带批注.md（1155 字节）
[完成] 评分：86/100 → 100/100

换成自己的目标时，先 --template > spec.json 拿骨架，改 dims 后
--data spec.json --out ./_out 即可，输出格式与上面完全一致。

> 注：39636 字节是 demo 规格的实测产物大小；换成你自己的 spec.json
> 后字节数会随维度数与文字长度变化，不要照抄这个数字当验收标准。

十一、稳定性契约（12 条，均已实测）

1. 不覆盖原文件：优化稿一律另存为 {名称}_优化稿{原扩展名}，原文件零改动。
2. 写回冲突降级：目标只读/被占用时写 {名称}.v2.{ext}，不硬覆盖（§五）。
3. 单条失败不中断：某一维数据异常只跳过该维（打印 [跳过] 与原因），其余维度照常出报告、退出码仍为 0；只有全部维度都无效才退出码 2。
4. 列数显式校验：表格行列数不匹配直接报错，不静默补空格（§八）。
5. 评分数字校验：非数字、超满分一律退出码 2 并指明是第几维（§八）。
6. 幂等：同一个 spec.json 重复跑，产出内容一致（仅文件名日期戳随当天变化）。实测同日两次 --demo 均为 39637 字节。
7. 零副作用：脚本不在技能目录内留任何文件；__pycache__ 等中间产物不提交。
8. 依赖缺失可诊断：退出码 3 + 三条可执行修复命令，不抛裸 traceback（§八）。
9. 路径注入防护（v1.1.4）：name 里的 \ / : * ? " < > | 与控制字符一律替换为 _，
   并打印 [提示] 告知净化结果。绝不把用户数据当路径拼接——v1.1.3 实测
   name="A/B:测试*方案?" 会在输出目录下静默建出 A/B 两层子目录，报告落到预期外位置。
10. 编码兜底（v1.1.4）：输入按 utf-8-sig → utf-8 → gbk → gb18030 依次尝试，
    中文 Windows 上记事本默认的 ANSI/GBK 文件可直接用；四种都失败才退出码 2 并给出转码做法。
    v1.1.3 及更早遇 GBK 会抛裸 UnicodeDecodeError 并以退出码 1 结束（违反本契约第 12 条）。
11. 参数互斥显式拒绝（v1.1.4）：--demo 与 --data 同时给 → 退出码 2，
    绝不静默忽略其一。用户数据被悄悄丢掉比报错严重得多。
12. 退出码封闭：只会返回 0 / 2 / 3。任何未预期异常都在 main() 边界被兜住，
    转换成 [错误] 生成报告失败：<类型>：<信息> + 退出码 2，不泄漏裸 traceback。

十二、已验证（v1.1.4，2026-09-12 逐条复现实测）

未验证 / 不适用：PDF 输出、Word 之外格式、多语言（中英混排以外）排版 —— 均未实测，不做承诺。
另：--demo 产物字节数随报告内日期戳变化（跨日可能 ±1 字节），不要拿它当验收硬指标。