技能包打包与治理（yonyou-js-djw-package）

本技能分两大职责：打包（把技能目录打成合规 zip + 发布前核对）与治理（管辖一切技能文件的增删改）。SKILL.md 只留路由、红线、触发与决策路径；各类细则下沉 references/ 按需检索——遇具体问题先查对应 reference，不要凭印象行事。

零、加载后必做（preflight）

本技能的全部纪律只有加载后才可见，存在「不加载就不知道要加载」的自举缺口；用户级记忆的「技能类任务·第一动作铁律」为该缺口兜底，二者互补。加载后按序执行：

1. 动手前先确认授权范围（见 §2.2）：改哪个技能、改哪一处、改成什么；指令模糊则先列拟改项请用户拍板，不直接重写大段。
2. 改前全量定位（见 §2.3）：grep 全技能目录找目标规则的所有出现（含 .md 与 .py 注释），一次性全改，避免多副本漂移。
3. 收尾必跑检查（两道必跑 + 两类口径审计按需）：先跑技能自检（结构 + 自洽，见 §2.8），再跑发布前核对（发布合规）；凡改动涉及共享口径 / 共享能力 / 同类技能分组，额外必跑口径一致性审计——① 规则驱动（scripts/consistency_check.py --cross <口径词> 或发布前 --all，抓 consistency_rules.json 枚举的已知异写）；② 无规则全量（scripts/literal_check.py --mode all，按归一化槽位后逐字比对抓未预料到的漂移，见 §三）。两者互补：前者防已知、后者兜未知；已拍板为合理分化的组登记 .literal_audit_whitelist.txt 后不再重复报。

确保同类技能未被带出新漂移；零 ❌FAIL、每项 🔶WARN 经人工确认后才算收尾，未跑检查不得交付或上传。
4. 交付前回报：说明「改了什么、为什么」，必要时记入工作日志（见 §2.2 可追溯）。

> 若本次是「新建 / 提炼技能」，除上述外还须：建「文件清单」章节（代码块 ASCII 树、必须沉底）；写 version: "Vx.y.z"，初始值须由用户指定，不得自行决定。细则见 references/writing-conventions.md 与 references/packaging.md。

隐私与安全（第一要义）

打包工具的首要责任是不把任何敏感数据带进发布包，此条优先级高于一切打包便利：

• 不内嵌客户 / 项目敏感数据：凭证（CLIENT_SECRET / SIGNATURE / BASE_HOST 等）、PII、密码一律不进发布包，由使用者本地配置或客户现场提供。
• 打包前扫描敏感硬编码：对进包文件做「疑似密钥 / PII」扫描（对应核对清单「无敏感硬编码外发」项）。命中真实赋值型密钥即 🔶WARN，由人判断是否脱敏 / 排除，不直接 ❌FAIL。
• 占位符与运行时代码不告警：引号内值被 < > 包裹的占位符、以及引号内含代码拼接痕迹的值，均自动豁免；真实硬编码密钥是纯字面量，仍会 🔶WARN。豁免判定的精确规则以脚本为准。
• 重型数据须先脱敏：设计为「首次调用自动拉取」的扩展包若含客户信息，须先脱敏再托管分享。
• 本地产物不外发：.package_allowlist.txt、本地缓存、临时文件均不进包。
• 本机数据文件一律打包置空：跨技能引用白名单（scripts/.cross_ref_whitelist.txt）、客户 / 项目专名清单（scripts/.known_customers.txt）、技能展示名台账（scripts/.skill_names.txt）、同类技能专项台账（scripts/.peer_skill_groups.txt）、同名文件台账（scripts/.dupe_files.txt）、治理范围台账（scripts/.governance_scope.txt）、逐字审计豁免台账（scripts/.literal_audit_whitelist.txt）、出包落点台账（scripts/.pack_output_dir.txt）均属本机台账——不硬编码进脚本、不写进 SKILL.md，打包时一律清为占位符，避免把内部台账（跨技能耦合、客户群、技能清单、技能分组、豁免指纹、本机固定出包目录）随包外发；运行期读取安装目录下的真实文件。置空清单只维护一处：scripts/package_skill.py 的 LEDGER_MASKS 注册表（新增台账只加一行，不在打包逻辑里再枚举文件名）。两侧各有一道对应闸口，都是 ❌FAIL：磁盘上有台账而注册表没登记 → 技能自检 A7 报出；注册表登记了但包内未置空 → 发布前核对「包内本机台账须为占位符」报出。清单未配置时，相关核对如实提示「已跳过」，不静默冒充「已扫描且干净」。唯一例外是自用姿态（--pack-mode private，见 §1.1）：私用包的定位就是把本机状态整体搬到使用者自己的另一台机器，故本机台账按定义要原样带入，不置空、不脱敏——该例外由「姿态」这一个开关统一控制，不在各处分散判断。
• 机器态内容一律不进包：① 机器态目录——浏览器 profile 与运行产物目录（.playwright / .playwright-cli / _chrome_profile / dsp_out / api_out）整目录硬排除，登记在 scripts/dir_exclusions.py 的 MACHINE_STATE_DIRS（该模块是目录排除面的单一权威源，打包侧与各审计脚本共用同一份），与发布前核对「运行产物误入包」一项共用同一张表（排除侧与验收侧同源，避免两处漂移）；② 散落的具体值——进包文本里的本机路径一律在打包时中性化，只留四种形态：WorkBuddy 数据目录（<盘>:/Users/<用户名>/.workbuddy）→ %USERPROFILE%/.workbuddy；本机用户名路径 → C:/Users/xxx/…；本机 home 镜像（<盘>:/workbuddy/home/<环境标记>）→ <工作空间>/home/<env-tag>-<version>；其它带盘符且含 workbuddy 的落点（含工作空间根 <盘>:/workbuddy/…）→ <工作空间>/…。已显式标注为反例 / 规则说明的行豁免不改（与 references/consistency_rules.json 的 benign_line_regex 同一口径）。兜底闸口：发布前核对「进包文本不得含本机盘符路径」读成品包实际内容，脱敏漏掉的（含不可脱敏的文件类型）一律 FAIL；该闸口的判据与脱敏规则表末条兜底规则共用同一个正则对象——「闸口判什么、脱敏就兜什么」由同一份定义保证，不靠两处人工同步。两类在收件人机器上均物理不可用、且无法提前预生成，只能由命令行与运行位置决定，故一律不进包。
• 时间戳 / 编号类数值的 PII 误报防护：技能内若需写时间戳 / 编号等数值（如 _user_meta.json 的 installedAt），统一用规范化占位值 1700000000000，不写真实时刻 / 真实手机号形态。

> 宁可多一次人工确认，也不让一份密钥随技能包流出。

一、技能打包管理

把技能目录打成合规 zip，并执行标准口径与自动核对。本技能不参与技能内容设计、不内嵌项目数据、不决定哪些文件该进包——进包范围由被打包技能的 .package_allowlist.txt（白名单）或工具硬排除规则（排除）决定。

1.1 打包口径

打包前必须先问清姿态：同一份技能有两种出包用途——公开分享（--pack-mode public：台账置空 + 本机路径脱敏 + 客户 / 项目专名门禁，用于对外发布或上传平台）与自用移植（--pack-mode private：敏感信息原样带入，用于使用者把自己的技能整体搬到另一台机器）。两者对台账 / 本机路径 / 专名门禁 / config/ 真实配置的处置恰好相反，不得靠猜：动手前先说明两者差异、问明这一次要哪一种，再按回答走对应姿态；对方若要固定落点，用 --out-dir-set 登记进其本机台账（登记一次即长期复用；未登记时公开姿态回落当前工作目录、自用姿态拒绝出包）。缺省 public——外发口径必须落在安全侧；私用包名带 -私用 后缀且不得上传平台。

必须用 Python zipfile 写包（禁 Compress-Archive，否则 SKILL.md 不在 zip 根、平台识别失败）；进包分白名单 / 排除两种模式，技能目录自带 .package_allowlist.txt 时白名单默认自动生效（fail-closed——「本机文件不外发」是本工具的职责，不依赖操作者记得补参数）；含本机文件却未声明白名单的技能直接拒绝出包。出包前先清空落点里本技能的历史技能包（口径：每次都重新出，不保留旧包）——只在本机台账登记的固定出包目录内执行，按 <技能名>-技能包- 前缀匹配、其它技能的包不动，--out 与回落工作目录时不清空，不设绕过开关，删除失败即拒绝出包。完整口径（姿态差异表、白名单防呆、输出落点与出包前清理、白名单文件写法示例）见 references/packaging.md。

1.2 发布前核对清单（脚本自动）

scripts/package_skill.py 打包后自动打印核对报告：任一项 ❌FAIL 即以非 0 退出，🔶WARN 不阻断上传、由人确认。项数、扫描规则与阈值一律以脚本为准，文档不重复声明计数，以免项数增删时多处漂移。完整清单（核对什么 + 结果等级 + 判定要点）见 references/packaging.md。

1.3 文件清单规范

每个技能 SKILL.md 必须含「文件清单」章节，固定沉底，写成 text 代码块包裹的 ASCII 目录树，须与磁盘、成品包双向一致（漏列由核对硬阻断，可用 --sync-tree 同步）。样式逐条约束见 references/writing-conventions.md。

1.4 FAQ 题库文件规范

题库一律命名 faq.md（默认 references/faq.md；已有 references/common/ 通用层时放其下），首部须有引用块承载「用法句 / 结构约定 / 定位句（引用块首句）」，条目题号两段式 ## Q<章>.<序>. 标题、五段标签齐全，自包含（不跨技能引用、须登记文件清单）。完整体例见 references/writing-conventions.md；题库结构由 self_check.py 的 A9 项检查，新建 / 改写题库或新增题号后该项必须过。

1.5 版本号管理

version 统一为带引号的带 V 三段式 "Vx.y.z"（全技能一致，上架要求三段式）；严禁擅自变更——它是技能对外发布版本，须与平台已发布版本一致，改动须用户明确指令；不写本机版本变更说明。细则见 references/packaging.md。

1.6 说明写作风格

SKILL.md 只写提炼后的规范与边界、不嵌实现细节；description 必须精简（只写「能力 + 触发 + 红线本质」）；描述只写结论、试错归 FAQ；红线只写一次（单源）；不引用同类其它技能包的信息。各条判据与理由见 references/style-rules.md。

1.7 包内内容的分类处置（A / B / C）

技能包内的内容按「收件人拿到有没有用」分三类，处置各不相同。判据与落点如下，实现细节见 references/packaging.md：

三类各有验收闸口，且排除侧与验收侧同源（同一张表两处共用），任一失守即 ❌FAIL：A → 「骨架与单一权威源一致」；B → 「包内本机台账须为占位符」+ 技能自检 A7；C → 「无重型数据 / 运行产物 / 字节码缓存 / VCS 元数据目录误入包」。

1.8 骨架单一权威源

A 类的三处骨架（FAQ 题库头部块 / 技能维护边界红线单源声明 / frontmatter metadata 块）过去是「每个技能各存一份手工副本」，改一处要手动同步 N 处、漏同步即漂移。现收敛为唯一一份放在 references/skeletons/（faq_head.txt / redline.txt / metadata.txt），其余技能由 scripts/render_skeletons.py 渲染生成。

• 槽位：{{skill}}（FAQ 头部块内的技能包名）、{{extra}}（红线句后可选的尾接指针）、以及 metadata 的 {{display_name}} / {{version}} / {{author}} / {{category_list}} / {{tags_list}}。槽位值一律取自该技能现有内容——渲染器只统一骨架、不产生新值。
• 无侵入定位：不往技能正文插锚点注释（A 类随包外发，锚点会污染文档），改按精确锚点行定位；定位失败 / 槽位抽取不全一律报出、不猜、不写。
• 两条轨道同源：--check / --dry-run / --apply 三档由脚本承担，发布前核对「骨架与单一权威源一致」一项复用同一套文本级核心复核成品包，避免「生成器改了、验收照旧放行」。
• 改骨架的唯一正确路径：只改 references/skeletons/ 里那一份 → --dry-run 看影响面 → --apply → 跑核对闭环。

二、技能治理中枢

任何对技能文件（SKILL.md 的 frontmatter description / 章节正文 / 规则清单，以及 references/、scripts/ 及其注释）的增 / 删 / 改，均归治理中枢管辖，不得以「顺手优化」名义绕过。完整工作流纪律、验证门禁、自检与范围约束见 references/governance-ops.md。

2.1 管辖范围

凡涉及技能文件（SKILL.md 的 frontmatter description、章节正文、规则清单，以及 references/、scripts/ 及其注释等）的增 / 删 / 改，均须过治理中枢，不得以「顺手优化」名义绕过。

2.2 治理红线（最高优先）

• 未经明确许可，不得擅自修改：没有用户的明确、具体许可，一律不改动任意技能的描述 / 正文；即便认为「应该优化 / 精简 / 修正」，也须先说明意图与拟改动范围，等用户确认后再执行。
• 例外（标准授权）：同类技能同步修正＝默认动作，不必逐次征询（用户 2026-09-23 拍板：「这是最基本的工作步骤，后续涉及到同类问题修改的，你不用单独问，直接保持一致就行」）。凡同一根因 / 同一共享口径的修复，一旦在某个成员上确认（实测复现或用户拍板），直接同步到该组全部成员、一次写完，不再单独提问「要不要改兄弟技能」。授权边界四条：① 只覆盖同步既有修复——不含给兄弟技能新增功能、改写其独有内容、变更版本号；② 组内关系以 .peer_skill_groups.txt / .dupe_files.txt 为准，跨组、或某文件是否同源尚不明确时仍须先问；③ 同步文本一律按「自包含」口径写（不指名兄弟技能、不引用其专属文件——把对方的专属引用换成本技能自有的等价表述）；④ 涉及删除技能文件仍按 §2.5 逐文件确认、不适用本条。同步完按 §2.3 走核对闭环。
• 许可须具体：用户说「改一下」不等于许可改任意内容——要确认改的是哪一处、改成什么；模糊指令下先列出拟改项请用户拍板，不要直接重写大段。
• 版本号属对外承诺，变更须用户明确指令：version 的修改不在「顺手优化」之列；未获用户明确说「改版本 / 升版本」绝不自行 bump。
• 版本号写法须统一为带 V 的三段式：全技能统一带 V、带双引号、必须三段式。发现写法不一致（缺 V 前缀 / 缺三段 / 未加引号）须修正——属格式统一、不改版本值，允许直接做。
• 改了实现必须同步描述：修改 scripts/ / references/ 后，描述 / 清单 / 项数声明须同步更新，不得遗留「实现已变、描述滞后」。
• 技能描述独立·不得互相引用：可分享技能之间完全独立部署，描述（SKILL.md 正文 / 脚本注释 / references 文档）不得指名其它技能，亦不得写「机制与 X 相同」等需读者持有其它技能才能理解的表述；每个技能须自给自足。发现一处越界即全类扫描清零（见 references/governance-ops.md §2.3）。白名单机制见 references/style-rules.md。
• 可追溯：每次对技能文件的实质修改，应在会话中明确回报「改了什么、为什么」，必要时记入项目工作日志。

2.3 修改工作流纪律（收尾必做）

适用于一切技能描述 / 说明的增删改。核心是五条：改前全量定位（grep 全目录，一次性全改）→ 变更前影响面预扫（涉共享口径先列同组成员）→ 同类技能同步修正（发现一处即全类清零、统一按自包含口径写；属标准授权、默认直接做完、不逐次征询，边界见 §2.2）→ 收尾 grep 验证旧表述零残留 + 关键处 Read 二次确认 → 新增 / 重大改写收尾必须跑核对闭环（零 ❌FAIL、WARN 全确认）。批量改写须「单试点 + 逐技能复核」；新增内容按逻辑优先级编排、不无脑末尾追加。完整纪律（含执行口径、统一口径取严细则、编号顺序）见 references/governance-ops.md。

2.4 技能内文件彻底删除标准做法

治理中枢对技能文件执行「删」动作时，普通删除不可信——os.remove / rm / del 作用于普通工作区路径会被沙箱安全层重定向进 $Recycle.Bin，命令返回 success 但文件只进了回收站。绝不以命令返回值当作删除成功的证据；判定「已彻底删除」的唯一标准是回收站条目归零。可靠通道是直接对 $Recycle.Bin\<SID>\$Rxxxx 调 os.remove。完整流程（按扩展名 + 体积定位、禁止依赖 $I 解析、五步标准流程）见 references/governance-ops.md。

2.5 技能目录审查与孤儿文件清理（安全准则）

• 权威清单 = SKILL.md「文件清单」+ .package_allowlist.txt：某文件是否该常驻技能，唯一判据是它在权威清单（或白名单）中、或被技能文本广泛引用；禁止用命名特征猜垃圾。
• 删除前强制引用回扫（必做）：拟清理任一文件前，先 grep 全技能目录该文件名；凡被引用即排除出清理名单并提示用户。
• 审查即只读、逐文件显式确认（仅限技能正式文件）：审查只产出候选清单，绝不顺手删除；技能正式文件的删除须用户对每个具体路径明确确认——用户说「清理掉这些」而未点名具体文件，视为未授权。运行时副产物与自创临时产物例外：__pycache__/、*.pyc、*.tmp 等工具运行产物（.gitignore 已兜底、删后自动重建），以及本次自创的中间脚本 / 中间 .txt，属可直接清理项、不必询问——判据三条同时满足即可：不在「文件清单 / 白名单」内、不被任何技能文本引用、删除后不影响技能可用性。

> 完整准则（两个方向的完整性校验、描述层 / 数据层分层、示例文件名的人工过滤、配套 --audit 只读工具）见 references/governance-ops.md。

2.6 临时文件 / 临时目录清理纪律

任何「审查 / 诊断 / 验证 / 解包比对」动作都会产出临时文件或目录，须与 §2.4「可靠删除」、§2.5「审查即只读」配合：隔离存放不污染（放 ~/.workbuddy/tmp_<任务名>/ 或系统临时目录，不混入技能目录、不混入用户个人目录）→ 只读分析、结束清理 → 清理前必扫确认（确为本次自创产物，绝不通配删）→ 自创的临时产物与运行时副产物直接清理、不必询问（含技能树内的 __pycache__/、*.pyc、中间脚本与中间 .txt；每日定时清理任务的白名单明确排除 skills/，这类产物不在其覆盖内，故由执行方自行清掉并继续推进）。仅三类对象仍需用户拍板：① 技能正式文件（按 §2.5）、② 用户个人目录下的任何文件、③ 已交付的成果物。完整纪律见 references/governance-ops.md。

> 跑检查脚本须禁写字节码：执行本技能任一 scripts/*.py（打包 / 核对 / 自检 / 一致性审计）时，一律前缀 PYTHONDONTWRITEBYTECODE=1，避免在技能树里留下 __pycache__/ 副产物——它属运行时生成物，混入技能目录会被误当正式文件（触发漏列 / 孤儿审查噪音），本不该产生。此为执行纪律，与各技能 .gitignore 的 __pycache__/ 兜底互为双保险：前者从源头不产生，后者兜住偶发漏网。

2.7 脚本修改验证门禁（py 与非 py 脚本）

涉及技能 scripts/ 下脚本文件的实质性修改，须经「先临时文件验证、后落盘技能包」门禁：在技能目录外生成 _tmp_ 前缀的同扩展名临时件并实际运行核对，验证无误后才写回正式脚本。适用范围按「是否直接影响产物」判定、不按扩展名（生成类 / 取数类 / 核对类脚本，含 .js / .mjs / .sh 及其加载的流程体）；纯说明文件（.md）不适用。检查器脚本须加缺陷探针（注入已知缺陷确认逐类报出 + 全量重跑无新增误报）；生成类 / 取数类须实际重跑并读回产物量化核对。完整门禁（适用范围、探针要求、配套项、门禁强度）见 references/governance-ops.md。

2.8 技能自检（结构 + 自洽全量体检）

发布前核对覆盖的是发布合规（这个包能不能上传）；scripts/self_check.py 补的是另一面内容自洽与演进一致性（内容对不对、有没有随演进漂移）。二者互补，改完技能后两道都跑。自检分 A 组（机器判定：章节层级 / 编号体系 / 悬空引用 / 硬编码计数 / 复盘叙述与验证状态自述 / 描述精简度 / 台账外发 / 软跨技能指称 / FAQ 题库结构 / 常驻段配比 / 引用政策自述 / references 检索关键词节 / 行尾一致性）与 B 组（机器报、人工判：红线重复声明、声明与实现一致），退出码非 0 表示存在 ❌FAIL。项数与判定细则以脚本为准，本节不重复声明计数。

> 行尾约定：技能正式文本文件一律 LF（.bat / .cmd 例外），不得文件内混用、不得余留 CR。行尾不是内容、却是假差异的头号来源——落盘丢了行尾，治理 diff 会假成「整文件重写」；改写脚本时须保持既有行尾，写回后跑一次自检的行尾项。细则见 references/governance-ops.md。

> 「常驻段配比」量的是 SKILL.md 的常驻成本——SKILL.md 加载即常驻、每次工具往返都要重付，应只留路由 / 红线 / 触发 / 决策路径，重内容下沉 references/。它量两个独立维度：① 常驻段体量；② 与 references/ 的原样重复（重复即「分层未删源文」，同一内容付两遍）。体量维度按「是否已做 references 路由」分档——正文有 references/*.md 指针＝已分层、体量属该技能不可再切的净承载（不报）；无指针且超 WARN 阈值＝尚未分层（报 WARN）。此分档是为让 WARN 收敛成「还没动手的」待办信号，避免已做完分层的技能被反复报回、进而把仍有用的执行规则也误切走。超硬上限仍一律 FAIL。完整说明与各检查项精确规则见 references/governance-ops.md 与 self_check.py 源码。

2.9 治理范围（scope）｜跨技能审计的范围约束

跨技能审计（--all / --cross / --grep、同名文件巡检）默认扫全部技能；本机用 scripts/.governance_scope.txt 限定只治理部分系列（如 yonyou-js-djw-*）。范围未配置（占位态）时工具警告后仍按全量跑；首次运行纪律：跑任何跨技能审计前先检查该台账是否已配置，未配置须先向用户确认范围、写回后再跑，禁止静默全量扫。该台账打包时清为占位符。完整约束见 references/governance-ops.md。

三、口径一致性审计（同技能 / 跨技能）

把「某能力在不同技能里描述不一、或单技能内同类表述漂移」做成可复用、可重扫的审计能力，避免每次靠人工逐篇比对。两个互补引擎：

> 二者分工原因：规则枚举只能发现「枚举表里列过的异写」；逐字比对要检的是「同一句口径句在 N 个技能里是否字节级相同」——故新增第二引擎兜底，避免「规则没写就检不出」。

• 扫描面：SKILL.md + references/**/*.md + scripts/**/*.py + scripts/**/*.sh，仅依赖 Python 标准库。
• 何时用：怀疑某共享能力多技能写法不一；单技能内出现互斥写法；发布前做全量口径重扫；跨技能同名文件疑似「改一处忘一处」；改动涉及共享描述后收尾必跑 literal_check.py。
• literal_check 两种模式：--mode line（行级：归一化槽位后按行精确比对，产出「逐字一致 / 槽位差异」双档，槽位差异属正常）；--mode para（段落级：连续非空行组成段落，字符 3-gram + Jaccard 模糊聚类，MinHash 分桶 + 并查集归并提速；标题行作切分边界天然不参与比对）；--mode all 跑全量。
• literal_check 的目录级排除（决定成本的头号变量）：只比对技能口径文本——默认排除两类目录：① 自动拉取 / 生成型数据目录；② 机器态目录（两类名单与判定取自 scripts/dir_exclusions.py，详见「隐私与安全（第一要义）」；审计侧额外启用生成型后缀兜底，本文不复述名单）。二者不是口径文本，却会把大量超长段落灌进聚类、成为耗时的主要来源。排除项在报告中如实列明（目录名 + 文件数 + 字节数），绝不静默缩小扫描面；--no-exclude 关闭排除（恢复全量扫）、--exclude-dir 追加。
• literal_check 另有两项提速且不改变判定口径：单遍读盘（行级与段落由同一次遍历产出）；内容寻址解析缓存（按文件内容命中即跳过解析，缓存落本机临时目录、不进技能包，--no-cache 关闭）。
• 合理分化豁免：已拍板为合理分化的组，按「组指纹」登记 scripts/.literal_audit_whitelist.txt（格式 <mode> | <指纹> | <备注>），命中即从「真差异」降为「已豁免」，不再重复报。
• 方法论五步：全量定位 → 建一致性矩阵（行=技能、列=能力各维度）→ 分级（🔴必修 / 🟡建议 / 🟢已一致）→ 条件一致性双透镜（姿态：分享 / 自用分组；语境：同一术语不同语境合法并存不算漂移）→ 共享口径固化 + 登记权威源。修订口径顺序固定：先改权威源技能与规则 note，再按台账同组技能逐处同步。
• 规则字段：benign_line_regex（反例引用豁免，只作用于非优选变体）、member_file / member_regex / member_scope（缺失检测）。
• 逐字一致口径：除章节标题外，描述文本须逐字一致；技能特有变量（URL / 章节号 / 技能名 / 配置文件名 / 本机路径 / 产出物名）保留为槽位，骨架文本必须逐字一致。

> 完整方法论、规则字段说明、同名文件巡检分档口径（含「异名同源」档位）见 references/consistency-audit.md。

四、用法

> 下列命令一律以 PYTHONDONTWRITEBYTECODE=1 前缀执行（见 §2.6：不在技能树留下 __pycache__/ 副产物），示例中为简洁省略。
> 路径一律写中性占位：<技能目录> = 本机技能根下的 yonyou-js-djw-<技能名>（Windows %USERPROFILE%/.workbuddy/skills/...、macOS / Linux ~/.workbuddy/skills/...），<输出目录> = 由你决定，<固定出包目录> = 使用者在本机台账里自行登记的落点；路径参数支持 ~ 展开，也接受 Git Bash 的 POSIX 形式（/c/...）——各脚本经 scripts/path_util.py 自动转成 C:/...（不转的话会被 Windows 版 Python 当成「当前盘根下的相对路径」→ 报告落到错位目录 / 扫描目录找不到）。不写具体盘符或本机目录名——那些在收件人机器上不存在（属 §1.7 的 C 类机器态），照抄只会落空。

# 打包（落点优先级：--out > 本机台账登记的固定出包目录 > 当前工作目录[仅公开姿态]）
# 公开分享：先问清姿态再执行，缺省 public（本机台账置空 + 本机路径脱敏 + 专名门禁）
python scripts/package_skill.py --skill-dir "<技能目录>" --pack-mode public
# 自用移植：敏感信息原样带入，包名带 -私用 后缀，落点必须已在台账登记（未登记即拒绝出包）
python scripts/package_skill.py --skill-dir "<技能目录>" --pack-mode private
# 登记 / 查看固定出包目录（本机运维约定，只写本机台账，不碰技能内容）
python scripts/package_skill.py --pack-mode public  --out-dir-set "<公开分享出包目录>"
python scripts/package_skill.py --pack-mode private --out-dir-set "<自用移植出包目录>"
python scripts/package_skill.py --out-dir-show
# 指定输出路径（覆盖台账落点）
python scripts/package_skill.py --skill-dir "<技能目录>" --out "<输出目录>/<技能名>-技能包-<version>.zip"
# 白名单模式（技能目录含 .package_allowlist.txt 时**默认自动生效**，无需传参；本行仅为显式写法）
python scripts/package_skill.py --skill-dir "<技能目录>" --allow-only .package_allowlist.txt

# 发布前核对：仅检查已存在的包 / 检查技能目录源码（收尾闭环推荐，零 FAIL、WARN 全确认才完成）
python scripts/package_skill.py --check-only "<包路径>"
python scripts/package_skill.py --check-only "<技能目录>"
python scripts/package_skill.py --check-only "<技能目录>" --allow-only .package_allowlist.txt

# 技能自检（结构 + 自洽体检，改完技能先跑，与发布前核对互补）
python scripts/self_check.py --skill-dir "<技能目录>"
python scripts/self_check.py --skill-dir "<技能目录>" --json

# 口径一致性审计（全部技能 / 单技能 / 自由文本跨技能检索）
python scripts/consistency_check.py --all
python scripts/consistency_check.py --skill "<技能目录>"
python scripts/consistency_check.py --cross playwright

# 逐字一致性审计（无规则全量：归一化槽位后逐字比对，抓规则枚举外的未知漂移）
python scripts/literal_check.py --mode all --out literal_report.txt
python scripts/literal_check.py --mode para --json
python scripts/literal_check.py --mode line
# 扫描面默认已排除生成型数据目录与机器态目录（见 §三），报告首部会列明排除项与缓存命中
python scripts/literal_check.py --mode all --exclude-dir "<目录名通配>"   # 追加排除
python scripts/literal_check.py --mode all --no-exclude                  # 关闭排除（恢复全量扫）
python scripts/literal_check.py --mode all --no-cache                    # 关闭解析缓存

# 同名文件巡检（按台账分档比对跨技能同名脚本 / 数据文件，含「异名同源」档）
python scripts/shared_scripts_check.py

# 只读审计技能目录：孤儿候选 + 反向完整性校验（不删任何文件）
python scripts/package_skill.py --audit "<技能目录>"
# 以磁盘为权威源同步文件清单树（保留注释、补入漏列文件，重渲染 ASCII 树）
python scripts/package_skill.py --sync-tree "<技能目录>"
# 统一补全技能 frontmatter 的 metadata 展示信息（上架平台市场必检；支持 --dry-run 预览）
python scripts/ensure_metadata.py --skill-dir "<技能目录>" --dry-run

# 骨架单一权威源渲染（A 类骨架：FAQ 头部块 / 红线单源声明 / metadata 块；改骨架只改 references/skeletons/）
python scripts/render_skeletons.py --check                    # 只比对（有待统一项时退出码非 0）
python scripts/render_skeletons.py --dry-run                  # 打印将变更的 diff，不写盘
python scripts/render_skeletons.py --apply                    # 渲染写入
python scripts/render_skeletons.py --check --skill-dir <技能目录>   # 只查单个技能

仅依赖 Python 标准库（zipfile / argparse / re），无需 pip 安装任何包。

文件清单

yonyou-js-djw-package/
├── SKILL.md                          本技能说明：职责定位、preflight、隐私安全、打包与治理路由、口径审计路由、用法
├── references/
│   ├── faq.md                         技能问题题库：治理踩坑结构化沉淀为可检索问答（试错归此，正文不重述）
│   ├── packaging.md                  打包管理细则：打包口径 + 出包姿态（公开分享 / 自用移植）+ 发布前核对清单 + 版本号管理（见 §1.1 / 1.2 / 1.5）
│   ├── style-rules.md                说明写作风格规范：不写实现细节 / 描述精简 / 单源红线 / 跨技能隔离等（见 §1.3）
│   ├── consistency-audit.md          口径一致性审计细则：方法论五步 + 规则字段 + 同名文件巡检分工（见 §3）
│   ├── writing-conventions.md        写作与结构规范：文件清单样式细则 + FAQ 题库体例细则 + references 检索关键词节体例（见 §1）
│   ├── governance-ops.md             治理细则：管辖范围 + 修改工作流纪律 + 可靠删除 / 目录审查 / 临时文件 + 验证门禁 + 自检 + 范围（见 §2）
│   ├── consistency_rules.json        口径一致性审计规则（数据驱动、可扩展；一致性审计脚本读取）
│   └── skeletons/                    A 类骨架单一权威源：由 render_skeletons.py 渲染进各技能（见 §1.8）
│       ├── faq_head.txt              FAQ 题库头部块骨架（槽位 {{skill}}）
│       ├── redline.txt               技能维护边界红线单源声明骨架（槽位 {{extra}} 可选尾接指针）
│       └── metadata.txt              frontmatter metadata 块骨架（字段顺序统一 + 5 个槽位）
└── scripts/
    ├── dir_exclusions.py            目录排除面单一权威源（机器态目录 / 生成型数据目录的名单与判定，打包侧与各审计脚本共用）
    ├── path_util.py                 路径参数规范化（把 Git Bash 的 `/c/...` 转成 `C:/...`，供各脚本统一调用；见 §四）
    ├── package_skill.py              打包与发布前核对脚本，仅依赖 Python 标准库
    ├── render_skeletons.py           骨架渲染器（单一权威源 → 各技能；--check / --dry-run / --apply）
    ├── ensure_metadata.py           统一补全技能 frontmatter 的 metadata 展示信息（上架市场必检）
    ├── consistency_check.py         同技能/跨技能口径一致性审计（规则驱动）+ 逐文件定位检索 --grep（仅依赖 Python 标准库）
    ├── literal_check.py             逐字一致性审计（无规则全量：行级 + 段落级，归一化槽位后逐字比对；含目录级排除与解析缓存；仅依赖 Python 标准库）
    ├── shared_scripts_check.py      同名文件巡检：按台账分档比对跨技能同名文件，报出漂移
    ├── self_check.py                技能自检：结构 + 自洽体检（A 组机器判定 / B 组人工判；明细项以脚本为准）
    ├── .cross_ref_whitelist.txt     跨技能引用校验白名单（来源技能跳过清单）；本机治理产物，随包时清为占位符
    ├── .known_customers.txt         已知客户 / 项目专名清单；本机数据文件，打包时置空（客户群不随包外发）
    ├── .skill_names.txt             技能展示名台账（后缀 → 展示名 + 分类）；本机数据文件，打包时置空
    ├── .peer_skill_groups.txt       同类技能专项台账（分组 + 组内技能清单）；本机数据文件，打包时置空
    ├── .governance_scope.txt        治理范围台账（每行一个技能名 glob）；本机数据文件，打包时置空
    ├── .literal_audit_whitelist.txt 逐字一致性审计豁免台账（已拍板合理分化的组指纹）；本机数据文件，打包时置空
    ├── .dupe_files.txt              同名文件台账（档位 + 文件名 + 成员技能）；本机数据文件，打包时置空
    └── .pack_output_dir.txt         出包落点台账（每行「<姿态> = <固定出包目录>」）；本机数据文件，打包时置空