营造 yingzao · Skill 打磨工坊

Overview

被打磨的 skill 是一座建筑：查勘出报告，大修做工程，完工挂落成匾，之后进入岁修周期。营造管"从能用到能交付"的最后一公里——它不从零生成 skill（那是 skill-creator 的分工），只把已有的毛坯打磨成可信赖的资产。

术语双标表（全流程报告标题一律「营造词 · 白话词」并列）

营造词	白话词	干什么
查勘	快检档	只读体检，不动任何文件，一页报告
大修	精装档	完整七步打磨
相地	立项审查	这个 skill 该不该存在、值不值得打磨
访例	同类调研	并行搜同类，分析别人凭什么被安装
定式	生态定位	纵横交叉，一句话独特定位
勘验	质量评测	九维评分，按形态加权（细则见 references/scoring.md）
画样	差距规划	P0/P1/P2 清单 + 三方向择一推荐
细作	定向改写	每轮只改一个变量 + 过验证门
落成	验收交付	报告 + 落成匾（结果卡）
岁修	持续跟进	对标观察 + 满 5 个 skill 触发自打磨
禁例	红线清单	反模式黑名单（references/anti-patterns.md）
比样	多候选对比	细作可选模式：每轮 3 候选取优（best-of-3）
落架	推倒重写	细作卡死时的保险路径：整体重构后同台对比，优者胜出

何时使用

• 自己或同事的 skill 写完了，想知道"行不行、差在哪"→ 查勘
• skill 要交付团队 / 准备开源，发布前完整打磨 → 大修
• "这个 skill 和别人的比怎么样" → 大修中的访例+定式
• 团队 skill 质量看齐：用统一九维标准互检

何时不用

• ❌ 从零创建新 skill → skill-creator / 生成器系（毛坯生成后再交营造打磨）
• ❌ 只优化一段 prompt / 一个文档（非 skill 形态）→ 直接改，不必动用工坊
• ❌ 想绕过测试快速"美化"README → 营造的验证门不接受无实测的"变好"

三个可选输入（开工时确认，缺省有默认）

1. 岗位画像（PM / 研发 / 设计 / 运营）：决定访例搜索源与报告受众语言。缺省时从 skill 内容推断，推断不出问一句。详见 references/roles.md。
2. 团队内部源：roles.local.md 配置的私有仓库/内网目录（本地扩展层，使用者可写、升级保留）。配置后访例优先扫内部源（对标自家同事比对标外网更贴近团队看齐）。未配置自动跳过。
3. 发布目标（内部=默认 / 开源）：影响规则预检传播段定级、访例对标重心、验证门②③的检查口径、落成报告的出门清单。

查勘 · 快检档（默认档，约 10 分钟，绝对只读）

铁律：查勘对目标绝对只读，收尾零自迭代写入。 发现的新模式只进报告"建议沉淀"附注。

1. 读料（边界规则，与大修通用）：读目标文本文件（SKILL.md / references / templates / scripts / tests——测试资产是第 9 维取证依据），排除 .git、node_modules、构建产物、二进制与媒体、疑似密钥文件（.env / *.pem / id_rsa / token——只记录存在性，绝不读内容进上下文或报告）；单文件 >100KB 截断头尾抽样；总量超预算按 SKILL.md > references > templates > scripts 优先级抽样并在报告标注「抽样查勘」。
2. 规则预检：运行 tools/inspect-skill.sh <目标路径> --target <internal|opensource>（零 token 确定性检查，双段式输出按严重度分级）。脚本不可用时降级为人工逐项对照（项目清单见脚本头注释），报告标注「人工预检」。
3. 形态判定：工具型 / 方法论型 / 工作流型 / 风格型，多形态取主形态（判定特征见 references/scoring.md）。
4. 相地三问（精简版）：解决谁的什么真实问题？用户为什么安装而不是临时问 Agent？有没有一句话传播钩子？
5. 勘验：九维评分（references/scoring.md），静态检查为主——无法实测的维度一律如实标「估分」；无测试 prompt 的 skill 总分上限 70/100。优先扫四大高频病种（台账 5 场归因，命中率从高到低）：① 测试资产缺失（4/5）② 文档间一致性漂移（4/5）③ 真相源矛盾 / 双源并存（3/5）④ 死链与资源孤儿（3/5）——先扫这四类再进九维细评，命中即录证据。
6. 出报告：按 templates/quick-report.md 产出一页——九维分表（实测/估分标注）+ 规则预检违规清单 + P0/P1 + 一句话最优先建议。

大修 · 精装档（触发词：完整打磨 / 大修 / 出师 / 发布前打磨）

开工播报（一次性知情）：本次工作区位置、发布目标、岗位画像、是否启用比样、自身核心完整性（哨兵比对 baseline.lock 的结果）。

七步产出物逐步累积成最终报告：每步交付一节，落成时合为 templates/full-report.md 的 10 节（相地→§1 ／ 访例→§2 ／ 定式→§3 ／ 勘验→§4 ／ 画样→§5-6 ／ 细作→§7 ／ 落成→§8-10）。每步下方「→ 本步产出」标明交付物与格式要点；照模板填，不要自创结构。

第一步 相地 · 立项审查

前提挑战：真实问题成立吗？独特性来自方法论 / 脚本资产 / 私有经验 / 数据 / 工作流 / 展示效果中的哪个？没有独特性直接指出同质化风险。判「地基不可建」→ 强制停手等使用者，不得擅自继续改写。
→ 本步产出（报告 §1）：一段相地结论——真实问题是否成立 / 独特性属哪一类 / 是否判「地基不可建」（是则在此终止并列原因）。

第二步 访例 · 同类调研

并行子 Agent 搜同类。搜索词两组：①目标自报词（name/description/核心任务的功能/人群/形态词）+ ②功能本质反推词——不用目标专有命名、用通用词反查目标视野外、专搜它没参考过的同类（破确认偏误，R1）。四类源逐类尝试 + timebox：官方/权威 → 社区开源(GitHub) → 商业产品(市场站读网页) → 学术；internal 默认 / 无网 / 该类对本岗位明显无意义时标「未访得（原因）」，不硬搜（R2）。同行分类 + 候选下限〔吸收 luban 访行〕：每对标标 直接 / 间接 / 手艺同行，合计 ≥5；找不够说明用了哪些词、哪些渠道没结果（R3）。每对标带 URL/路径 + 相关性分级（直接同类/部分重叠/表面像）；禁编造，搜不到标「未访得」。 top 2–3 最相关对标主线亲自读原始页面/仓库——curl/gh api 等通用 CLI 优先（避免 runtime 专有抓取工具名、且其可能触发静默权限挂起）；后台子 Agent 产出长时间不增长视为卡死，叫停捞回（R5，吸收 luban 工具纪律+心跳）。收尾召回自检：按 功能/人群/形态词 × 四类源反查有无明显该有却漏的（R4）。

二阶盲区（Y-014 召回实测）：① 对标可能是目标自身的镜像/fork（异作者但内容雷同）——核实作者+内容后剔除，否则「召回它=召回自己」污染对比；② 但剔除须逐个核内容实质，不可按「来源/同名」一锅端——内容实质不同的独立同类（即使同领域、同市场、被一堆镜像包围）严禁误剔（实测教训：过度剔除曾把真独立同类 propane-ai 连镜像群一起误杀，召回 2/3 未过门）。
→ 本步产出（报告 §2 两张表）：① 对标记录表「对标ID｜对标｜类型(直接/间接/手艺)｜URL｜相关性｜凭什么被安装｜可学的手艺｜不能照搬的点」+ ② 启示清单「启示ID｜来源对标ID｜启示内容｜初判九维ID(1-9)」（格式见 full-report.md §2）。

第三步 定式 · 生态定位

纵向（从什么痛点长出来、下一版往哪走）× 横向双层对比（C1）：传播层（命名钩子 / 一句话定位 / 安装摩擦 / 首屏信任 / 生态兼容 / 故事感）+ 能力层（逐项映射 scoring.md 完整九维①–⑨：①触发条件质量 ②工作流清晰度 ③失败模式覆盖 ④检查点设计 ⑤可执行具体性 ⑥资源整合度 ⑦整体架构 ⑧安全边界 ⑨实测表现）——让对标结论能直接定位「我第 N 维该提」，对标强于我的维即候选差距。可验证产物维按使用者岗位锚点比（C3，roles.md：运营→文案/SOP、研发→CLI/diff、设计→组件/对比图、PM→PRD/原型）。→ 交叉得出一句话生态位 + 逐维强弱结论 + 每条启示初判落到九维 ID。
→ 本步产出（报告 §3）：一句话生态位 + 纵横交叉分析 + 能力层逐九维①–⑨强弱子表（full-report.md §3）。这句直接用作落成匾的「定式」栏与 README 定位句。

第四步 勘验 · 质量评测

活体检查（文档命令实跑、产物真实渲染——经安全闸约束）+ 九维评分按形态加权。评分必须附证据；评分优先由独立子 Agent 执行，宿主不支持时按盲评降级链处理并标注「非严格盲评」。
→ 本步产出（报告 §4）：九维评分表——每行「维度 ｜ 得分/满分 ｜ 实测/估分 ｜ 证据（文件:行号）」+ 总分 + 评级（格式见 templates/quick-report.md 的九维表，大修与查勘同表）。

第五步 画样 · 差距规划

差距清单 = 两源合并：① 勘验驱动（九维体检低分项）+ ② 对标驱动（访例 §2 启示每条经转化桥 T1 强制映射）。对标差距转化桥（T1）：§2 启示清单每条「启示ID」→ 映射九维 ID → {P0 | P1 | P2 | 不采纳+理由} + 预期提分，落入 §5a 对标启示转化表，无一启示可悬空——机器校验 §2 启示ID 全集 ≡ §5a 启示ID 全集（tools/validate-report-contract.sh <报告>，不相等即断流、不得过门）。再与勘验项合并成 §5b 总差距清单（标来源 对标/勘验）。分级 P0（不补无法交付/公开）/ P1（补上显著提升安装率与信任）/ P2（锦上添花）+ 三个改进方向：细修现有 / 精雕可见产物 / 升级套件——择一推荐。建议升级套件 → 强制停手等确认。
→ 本步产出（报告 §5a 对标启示转化表 + §5b 总差距清单，每条带预期提分 + 来源）。P0 清单即下一步细作的循环驱动表。

第六步 细作 · 定向改写（SkillOpt 式受控迭代，核心纪律最多）

写入授权唯一语义：营造对目标项目的一切写入（改写 / 测试 prompt / 工具脚本）默认只产出候选（patch / 副本，置于营造工作区），使用者祈使句授权后才写目标文件。授权两档：单轮授权（「应用这轮」）只覆盖当轮；批量授权（「本次细作连续应用」）覆盖本循环全部过门改写——每轮仍独立落 patch 可逐轮回退。

备样前置：目标无测试 prompt 时先生成 2-3 个候选测试 prompt（同授权门交付，不静默落盘）。每个必须带四件套：成功判据 / 失败判据 / 诱饵意图 / 不可接受输出黑名单；至少 1 个对抗性诱饵题。无四件套不得进验证门计分。 生成后跑裸基线对照（每 prompt 多跑 1 次）：裸基线实例也能完美通过的=永真断言，当场剔除重写；裸基线结果存为增益参照。

执行 harness（管裸基线 / 原版 / 改写版三类运行）：打磨 Agent 已读过目标全文，不得自己「假装」裸 Agent 或模拟版本差异。宿主支持隔离上下文 → 三类各起隔离实例：裸基线零注入——且必须与被测 skill 隔离 cwd / 禁读 skill 目录 / 剥离全局注入（CLAUDE.md、memory、skills 列表），否则子实例会自己找到 skill 照着执行（禁例 17，Y-009 两案实测全污染）；做不到隔离 → 该轮增益按裸基线预期表估分；原版 / 改写版各挂完整 bundle 快照（三步组装：① 解析文内引用 ② 白名单补齐 references/templates/scripts|tools/assets/tests（沿用读料排除表，二进制/媒体/密钥只记 manifest 不复制）③ 生成 bundle manifest 存档）。manifest 缺项 / 组装不全 / 宿主无隔离 → 该轮按估分处理，不计实测分。

harness 安全闸：测试运行默认只读 / dry-run——被测 skill 试图执行命令、访问网络、写文件、调用发布/删除类工具时，副作用动作改为「列出执行计划」记入测试输出；确需真实执行才能验证的，先呈计划、等祈使授权单独放行；未授权 → 该 prompt 仅静态分析/估分，报告标注「因安全闸未实测」。硬规则：dry-run 是提示词约束、非硬隔离——宿主无法在工具层硬限制实例能力（禁执行/禁网络/写入拦截/只读沙箱）时，含副作用风险的测试 prompt 一律按估分处理，不得实测运行（与「实测分只认隔离运行」同源：硬保证缺位就降级，不赌实例自觉）。

显式循环：P0 清单驱动，每轮只改一个变量（单候选改写 → 盲评 → 验证门 → 产出 patch → 按授权档应用 → 下一轮）。终止条件：P0 清空 / 连续两轮过不了门 / 单轮总分涨幅 <1 分（早停防凑分）/ 使用者喊停。

棘轮纪律（run-owned 纯 hash，git / 非 git 统一）：分数只升不降，不过门直接丢弃。run 启动时记录全部候选待改文件 baseline hash；每轮应用存 forward patch + reverse patch + applied manifest（路径+应用后哈希）。动笔前检查：当前哈希 == last_applied_hash 或 baseline → 放行；为其他值（使用者 run 期间改了同文件）→ 停手。git 状态仅辅助提示。应用 = 备份（git 记基线 commit / 非 git 快照 .yingzao-backups/，备份位置在应用授权播报中明示）+ patch apply。营造不执行 git commit / revert / reset，版本操作权归使用者。 估分维度占比 >30% 时报告显著告警。

盲评分离（降级链）：改写者与评分者必须分离（LLM 自评准确率仅 46.4%，SkillLens 2026）。支持子 Agent → 独立子 Agent 盲评+轮换评委防锚定；不支持 → 全新上下文评分 prompt，报告标注「非严格盲评」。

验证门（三条全过才应用）：① ≥2 个测试 prompt 输出优于原版；② 可理解性按发布目标——内部：触发方式+使用边界+最小示例 10 秒可懂（载体不限）；开源：README 首屏 10 秒讲清价值；③ 摩擦零新增按发布目标——内部：触发/依赖/权限/运行入口；开源：安装路径。边际复测：「优于原版」若优势微弱（盲评分差 <5 或评委含糊）加跑 1 次复测，仍微弱判未过门——宁缺毋滥。

比样 · 多候选对比（可选，默认关；触发词「比样 / 多候选 / best-of-3」）：本轮生成 3 个候选改写，在测试 prompt 上 Pareto 对比——不只比总分，逐实例比胜负面，总分高但单实例明显崩坏的不得入选。耗时约 ×2。进入细作前播报当前模式与切换话术（三处可见原则之运行时播报）。

落架 · 探索性重写（卡死保险，强制停手确认；触发词「落架 / 推倒重写」）：单变量爬山有局部最优——细作连续两轮过不了门、或 P0 未清但已无单变量可下手时，营造提议落架：保存当前最优版 → 整体重构 SKILL.md（重组结构与表达，不改 skill 的核心功能与用途）→ 同套测试 prompt + 盲评同台对比。重写版严格优于现版才采用，否则弃稿恢复现版——落架不破棘轮。 必须祈使授权后才执行（停手点⑦）；采用与否都在报告标注「本轮经落架（采用/弃稿）」。耗时约 ×1.5-2。

验证资产沉淀：一次性对比脚本固化为目标项目工具（同走候选+授权门）；一次性判断标准立为明文规矩。
→ 本步产出（报告 §7）：逐轮验证门记录表——每行「轮次 ｜ 改的变量 ｜ 测试结果（vs 原版/裸基线）｜ 门①②③ ｜ 边际复测 ｜ 结论 ｜ patch 路径」（full-report.md §7）+ 落盘到目标项目的 patch 与 tests/ 资产。

第七步 落成 · 验收交付

按 templates/full-report.md 出 10 节大修报告 + 落成匾（结果卡，打磨后分数如实标「实测/估分」）+ 岁修清单（对标观察点 / 迭代纪律 / 下一轮入口）+ 待使用者确认问题（≤3 个，必须是影响方向的）。报告第 8 节的 README 与展示升级建议按 references/readme-standards.md 的出门标准给（开源目标逐项给差距，内部目标用其轻量版条款）。报告默认内部版（含内部路径）；使用者声明外发时生成脱敏版（内部路径换代号，映射仅存内部版）。

营造工作区与版本保护

• 工作区：目录名用脱敏 ID，~/.yingzao/runs/<脱敏ID>-<时间戳>/（candidates / patches / report）。写入降级链：使用者指定目录 → ~/.yingzao/runs/ → $TMPDIR → 全不可写：大修自动降档为查勘+方案报告（不进细作），建议提供可写目录后重跑。绝不默认写入目标项目；使用者显式选「随项目留痕」才用 目标项目/.yingzao-runs/，且 .gitignore 只提示不自改（授权后出 patch）。
• 可外发版报告不出现真实内部路径。
• 非 git 目标零门槛：备份+patch+人话版《变更说明》+一句话恢复指引，全程无需 git 知识。
• 分层架构（v1.4 · 防静默漂移）：营造自身分两层——主线只读层（SKILL.md / references 非 .local / templates / tools，作者维护、升级直接覆盖）与本地扩展层（*.local.md，使用者可写、升级保留）。岁修写入只落本地层（轨 1），安装态禁改主线（轨 2 锁死）——核心永不静默漂移。
• 核心完整性哨兵：开工自检比对主线核心 hash vs tools/baseline.lock（tools/self-integrity.sh）——全匹配报「核心 = 官方 vX.Y.Z + 本地扩展 N 条」，偏离报「核心被外部改动、非主线行为、结果可能不可复现，建议恢复主线或显式 fork」。哨兵防无意漂移（drift），不防铁了心连 baseline.lock 一起改的 fork（那是自愿放弃官方身份）。

强制停手点与授权语义

以下节点必须停手等使用者：① 相地判「地基不可建」；② 建议升级套件；③ 改写会大幅改变 skill 定位；④ 新增高风险脚本 / 外部调用；⑤ 安全闸拦截的真实副作用执行；⑥ 对目标的任何文件写入（候选→授权）；⑦ 落架（探索性重写）执行前；⑧ 安装态下任何改营造自身主线核心的企图（默认拒绝，引导 fork 源仓或导出贡献包）。

授权判定：祈使句（「应用吧」「连续打磨」）才构成授权；疑问句（「可以了吗？」）只是问状态，照实回答。一次授权只覆盖声明的范围，不延续。

自迭代双轨（岁修机制）

• 轨 1 · 增量自改（分级写入 · v1.4 分层路由，对象是营造自身仓库）：查勘收尾零写入；大修收尾 30 秒自检（新打磨模式 / 新反模式 / 使用者纠正？）。写入一律落本地扩展层 *.local.md，永不改主线核心：打磨台账→case-log.local.md能写则直接追加（只读安装/写入失败不阻塞，台账项入报告）；新反模式→anti-patterns.local.md 生成候选 diff（L-N 编号，只增不改主线条目），使用者祈使授权后写入；评分权重（scoring.md）校准仅开发态做、安装态只读。自检不询问用户。ID→真实路径映射存 case-map.local.md（.gitignore 出厂预置忽略，营造运行时永不修改自身 .gitignore）。
• 轨 2 · 岁修自打磨（v1.5 按态分流）：以「装载副本是否含 install.sh / .github」判运行态（安装副本经 manifest 只含 skill 核心、不带工程文件）。安装态（无这些工程文件）——计数满 5 个不打磨自身核心，改为提示「已积累 N 条本地反模式 + M 场台账，导出贡献包回馈主线？」，营造完全锁死、拒绝改自身主线 SKILL.md/references（防静默漂移，见禁例 18）。开发态（作者源仓，含 install.sh/.github）——计数满 5 提示岁修，经同意用大修档打磨营造自身（发布目标按「开源」自检，验收视角强制切换陌生用户——改与评不得同一视角）。

三处可见原则（杜绝暗开关）

任何可选能力（如比样）必须同时出现在：① README 触发方式清单；② 运行时播报（进入相关步骤前告知当前模式与切换话术，不阻塞）；③ 报告固定位（标注本轮模式；结果提示该模式可能更优时场景化建议）。岁修新增的可选能力自动适用。

交活自检单（每次收工前过一遍）

• 开工跑了核心完整性自检（哨兵 vs baseline.lock）、结果记入播报？
• 查勘是否全程只读、零自迭代写入？
• 报告里每个分数都标了「实测 / 估分」？估分占比 >30% 告警了？
• 所有对标带 URL / 内部路径？没有编造同行？
• 对目标的每次写入都有祈使授权（单轮或批量）？
• 测试 prompt 都有四件套？裸基线对照跑了？
• harness 用了隔离实例 + 完整 bundle？做不到的都标了估分？
• 安全闸默认 dry-run？真实副作用都单独授权了？
• 改写者和评分者不是同一视角？
• 报告外发版脱敏了内部路径？
• 大修收尾自检做了？台账记进 case-log.local.md（或入报告）、写入只落本地扩展层没碰主线核心？
• 没有触犯 references/anti-patterns.md 任何一条？

Changelog

完整版本历史见 references/changelog.md。最近两版：

• 2026-06-14 · v1.7 — 竞品驱动改进链系统大修（访例 R1–R5 去锚定+四源+召回自检、定式双层映射九维、画样 T1 转化桥 + tools/validate-report-contract.sh 机器校验 §2≡§5a、full-report 拆表、roles 对标重心）。
• 2026-06-14 · v1.6 — 形态分流判据（给第 9/8/4 维补「同维度按形态认定判法」+ 纯形态判定特征，仅纯形态触发、不改权重、不破历史口径）。