@gitruck/cli 0.2.4 → 0.2.6

package/package.json

@@ -1,61 +1,62 @@
-{
-  "name": "@gitruck/cli",
-  "version": "0.2.4",
-  "description": "同合云成片流水线 CLI —— agent 驱动云端任务、产物拉回本地、三方工程文件（客户端/剪映/PR）互通。",
-  "license": "MIT",
-  "author": "Gitruck (同合云)",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/Gitruck/cli.git"
-  },
-  "homepage": "https://github.com/Gitruck/cli#readme",
-  "bugs": {
-    "url": "https://github.com/Gitruck/cli/issues"
-  },
-  "type": "module",
-  "bin": {
-    "gtrk": "dist/index.js"
-  },
-  "files": [
-    "dist",
-    "assets",
-    "skills",
-    "AGENT.md",
-    "README.md",
-    "LICENSE"
-  ],
-  "engines": {
-    "node": ">=20.6"
-  },
-  "publishConfig": {
-    "access": "public",
-    "registry": "https://registry.npmjs.org/"
-  },
-  "keywords": [
-    "gitruck",
-    "同合云",
-    "video",
-    "oral-cut",
-    "口播剪辑",
-    "cli",
-    "jianying",
-    "剪映",
-    "agent"
-  ],
-  "scripts": {
-    "gtrk": "bun run src/index.ts",
-    "build": "bun build ./src/index.ts --target=node --outfile dist/index.js",
-    "typecheck": "tsc --noEmit",
-    "prepublishOnly": "bun run build",
-    "test": "esbuild src/lib/chunk-upload.ts src/lib/render.ts src/lib/cloud.ts src/lib/materialize.ts src/lib/projection.ts src/lib/splitdoc.ts src/lib/gtrk-writeback.ts --bundle --platform=node --format=esm --outdir=.test-build --out-extension:.js=.mjs && esbuild src/commands/split.ts --bundle --platform=node --format=esm --outdir=.test-build --out-extension:.js=.mjs && node --test \"test/*.test.mjs\""
-  },
-  "devDependencies": {
-    "bun-types": "^1.1.0",
-    "commander": "^12.1.0",
-    "esbuild": "^0.28.1",
-    "typescript": "^5.6.0"
-  },
-  "dependencies": {
-    "hash-wasm": "^4.12.0"
-  }
-}
+{
+  "name": "@gitruck/cli",
+  "version": "0.2.6",
+  "description": "同合云成片流水线 CLI —— agent 驱动云端任务、产物拉回本地、三方工程文件（客户端/剪映/PR）互通。",
+  "license": "MIT",
+  "author": "Gitruck (同合云)",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Gitruck/cli.git"
+  },
+  "homepage": "https://github.com/Gitruck/cli#readme",
+  "bugs": {
+    "url": "https://github.com/Gitruck/cli/issues"
+  },
+  "type": "module",
+  "bin": {
+    "gtrk": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "assets",
+    "skills",
+    "contracts",
+    "AGENT.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20.6"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "keywords": [
+    "gitruck",
+    "同合云",
+    "video",
+    "oral-cut",
+    "口播剪辑",
+    "cli",
+    "jianying",
+    "剪映",
+    "agent"
+  ],
+  "scripts": {
+    "gtrk": "bun run src/index.ts",
+    "build": "bun build ./src/index.ts --target=node --outfile dist/index.js",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "bun run build",
+    "test": "esbuild src/lib/chunk-upload.ts src/lib/render.ts src/lib/cloud.ts src/lib/materialize.ts src/lib/projection.ts src/lib/splitdoc.ts src/lib/gtrk-writeback.ts src/lib/column-config.ts src/lib/matrix.ts src/lib/matrix-lay.ts --bundle --platform=node --format=esm --outdir=.test-build --out-extension:.js=.mjs && esbuild src/commands/split.ts --bundle --platform=node --format=esm --outdir=.test-build --out-extension:.js=.mjs && esbuild src/commands/matrix.ts --bundle --platform=node --format=esm --outfile=.test-build/matrix-cmd.mjs && node --test \"test/*.test.mjs\""
+  },
+  "devDependencies": {
+    "bun-types": "^1.1.0",
+    "commander": "^12.1.0",
+    "esbuild": "^0.28.1",
+    "typescript": "^5.6.0"
+  },
+  "dependencies": {
+    "hash-wasm": "^4.12.0"
+  }
+}

package/skills/gtrk-splitter/SKILL.md

@@ -73,7 +73,7 @@ gtrk split --project "<oralcut产物目录>" --json
 - `lane` 四选一 `A_ROLL | RRV_MG | AI_DRAMA | FILM_BROLL`；`base_track` 三选一 `真人出镜 | 口播继续 | 旁白主导`。
 - **handoff 按 lane 分型**（校验器会硬查）：
   - `RRV_MG` → `handoff:{slug_hint?, theme?, bg?, duration_hint}`，**`duration_hint`（秒）必填**。
-  - `FILM_BROLL` → `handoff:{queries:[...非空], shots?, per_shot_sec?, exclude?}`，**`queries` 非空必填**。
+  - `FILM_BROLL` → `handoff:{queries:[...非空], shots?, per_shot_sec?, exclude?}`，**`queries` 非空必填**；queries 写**英文长句场景描述**（一条一个意象，避多义动词），**exclude 保持中文**（细则见 field-schema）。
   - `AI_DRAMA` → `handoff:{narrative?, theme?, emotion_stage?, platform?, shot_count?}`，全可选（下游 ai-drama-prompter 有推断默认）。
   - `A_ROLL` → **无 handoff**（写了会被警告忽略）。
 
@@ -109,6 +109,8 @@ gtrk split "<拆分稿.json>" --project "<oralcut产物目录>" --md --json
 
 ## 拆分方法论（沿《实在界漫游指南》视觉语法精华）
 
+> **词表随栏目配置**：下文的叙事功能（narrative）与容器阶段（container_stage）枚举、底轨三态，是**默认栏目《实在界漫游指南》的词表**，不是固定枚举。`gtrk split` 的校验源 = 有效栏目配置的 vocab（`--column <id>` 或 config `defaultColumn` 选取，配置文件在 `~/.gitruck/columns/<id>.json`）；别的栏目可自定义自己的叙事语法（科普=论点/论据/结论、带货=痛点/卖点/促单……），配置 `fallback.unknown_narrative="allow"` 时甚至可用纯自由串。零配置 = 默认栏目，行为与下文完全一致。lane 四车道仍是硬枚举（管线承重面），不随 vocab 放宽。
+
 ### 四车道语义（lane 四选一）
 
 - **`A_ROLL`（真人出镜）**：信任感来自「观众看见真人正在说」。优先给：体验式钩子、立场转换、关键悬念、情绪抱持、理论升华、结尾发问。
@@ -143,6 +145,6 @@ gtrk split "<拆分稿.json>" --project "<oralcut产物目录>" --md --json
 - 有没有把本该真人承接的段落全交给 b-roll？
 - span 里有没有混进 `dropped:true` 的句子？（会被跳过/收缩）
 - beat 之间有没有重叠？id 区间有没有倒序？
-- FILM_BROLL 有没有 queries？RRV_MG 有没有 duration_hint？
+- FILM_BROLL 有没有 queries？是不是英文长句场景描述（不是中文/关键词堆叠）？exclude 是不是中文？RRV_MG 有没有 duration_hint？
 - `transcript_hash` 是不是原样透传自视图？
 - 拆分稿里有没有混进任何秒级时码字段？（必须零时码）

package/skills/gtrk-splitter/references/example-visual-split.json

@@ -43,9 +43,9 @@
       "irreplaceability": "可被 B-roll 替代",
       "handoff": {
         "queries": [
-          "都市独处 夜晚",
-          "地铁 疲惫 通勤",
-          "关系破裂 争吵"
+          "lonely person in a city apartment at night",
+          "exhausted commuter on a crowded subway train",
+          "couple arguing as their relationship falls apart"
         ],
         "shots": 6,
         "per_shot_sec": 2,
@@ -70,8 +70,8 @@
       "irreplaceability": "可被 B-roll 替代",
       "handoff": {
         "queries": [
-          "深夜 失眠 闪回",
-          "伴侣 争吵 冷战"
+          "sleepless person lying awake in bed late at night",
+          "couple giving each other the silent treatment after a fight"
         ],
         "shots": 4,
         "per_shot_sec": 2.5
@@ -178,7 +178,7 @@
         "narrative": "trauma-repetition",
         "theme": "freud-fort-da",
         "emotion_stage": "abyssal",
-        "platform": "kling",
+        "platform": "video-gen",
         "shot_count": 5
       },
       "aux_layers": [
@@ -210,8 +210,8 @@
       "irreplaceability": "可被 B-roll 替代",
       "handoff": {
         "queries": [
-          "社交媒体 评论区 对骂",
-          "手机屏幕 戾气 弹幕"
+          "hostile social media comment threads on a phone screen",
+          "aggressive messages flooding a glowing phone screen in the dark"
         ],
         "shots": 5,
         "per_shot_sec": 1.8,
@@ -244,8 +244,8 @@
       "irreplaceability": "可被 B-roll 替代",
       "handoff": {
         "queries": [
-          "荒野 草丛 风声",
-          "都市 人群 疏离"
+          "tall grass swaying in the wind on an empty plain",
+          "anonymous crowd walking past each other in a city street"
         ],
         "shots": 4,
         "per_shot_sec": 2.2
@@ -291,8 +291,8 @@
       "irreplaceability": "可被 B-roll 替代",
       "handoff": {
         "queries": [
-          "心理疗愈 商品 广告感",
-          "打枕头 发泄 房间"
+          "glossy commercial for self-help therapy products",
+          "person venting anger by hitting a pillow in a bedroom"
         ],
         "shots": 5,
         "per_shot_sec": 1.8,
@@ -325,8 +325,8 @@
       "irreplaceability": "可被 B-roll 替代",
       "handoff": {
         "queries": [
-          "亲密关系 反复 争执",
-          "童年 阴影 家庭"
+          "couple stuck in the same recurring argument at home",
+          "child overshadowed by tension in a family living room"
         ],
         "shots": 4,
         "per_shot_sec": 2.5

package/skills/gtrk-splitter/references/field-schema.md

@@ -53,11 +53,16 @@
 //   duration_hint（秒）必填；slug_hint / theme / bg 可选（bg 底色可由底轨态推导）
 
 // lane === "FILM_BROLL"
-"handoff": { "queries": ["都市独处 夜晚", "地铁 疲惫"], "shots": 6, "per_shot_sec": 2, "exclude": ["卡通", "水印"] }
+"handoff": { "queries": ["lonely person in a city apartment at night", "exhausted commuter on a crowded subway train"], "shots": 6, "per_shot_sec": 2, "exclude": ["卡通", "水印"] }
 //   queries（非空字符串数组）必填；shots / per_shot_sec / exclude 可选
+//   queries 语言规范（经真机中英 A/B 校准）：
+//   - 用**英文长句场景描述**（5-12 词，谁+在哪+做什么），不是关键词堆叠——检索后端向量模型英文场景级命中明显更准
+//   - 每条 query 只装一个场景意象，多意象拆成多条
+//   - **避多义/字面义强的动词**（"pointing" 会召回手指特写、"hunting" 召回猎人——改用 "giving suggestions in a meeting" 这类场景语义）
+//   - **exclude 保持中文**：负向过滤匹配的是服务端返回的中文 note，写英文会失效
 
 // lane === "AI_DRAMA"  —— 全可选（下游 ai-drama-prompter 有推断默认）
-"handoff": { "narrative": "trauma-repetition", "theme": "freud-fort-da", "emotion_stage": "abyssal", "platform": "kling", "shot_count": 5 }
+"handoff": { "narrative": "trauma-repetition", "theme": "freud-fort-da", "emotion_stage": "abyssal", "platform": "video-gen", "shot_count": 5 }
 
 // lane === "A_ROLL"  —— 无 handoff
 ```
@@ -82,7 +87,9 @@
 
 ## 落地产物（CLI 写，供参照）
 
-- **`.gtrk` 的 `struct_meta.split`**：`{contract_version, transcript_hash, projected_at, beats:[{id, lane, span, track_st, track_ed, shrunk?, handoff}]}`——投影时刻快照。**消费方要新鲜时码就重新投影**（`gtrk split --project`）。
+- **`.gtrk` 的 `struct_meta.split`**：`{contract_version, transcript_hash, projected_at, material_id, beats:[{id, lane, span, track_st, track_ed, source_ranges, narrative, container_stage, visual_task, shrunk?, handoff}]}`——投影时刻快照。**消费方要新鲜时码就重新投影**（`gtrk split --project`）。
+  - `material_id`：口播素材 id（= transcript.material_id），消费方脱离 transcript 文件即可定位素材。
+  - `beats[].source_ranges`：`[{st, ed}]` 源时基秒（v1 恒单元素 = span 源包络，含句间静默与被剪词）——**源时基不随时间线编辑漂移**，消费方以「源区间 ∩ 当刻颗粒源窗口」投影可得实时覆盖（客户端色带跟随模式即此）。
 - **`split/dispatch.json`**：`{rrv_mg:[{beat, composition_id, duration, theme, bg, slug_hint, track_st, track_ed}], film_broll:[{beat, queries, shots, per_shot_sec, exclude, track_st, track_ed}], ai_drama:[{beat, ...handoff, track_st, track_ed}]}`。`composition_id` = `<工程slug>-<beatId>`（rrv 颗粒 `data-composition-id` 直接用它，打通 beat↔颗粒命名）。
 - **`split/visual-split.md`**（`--md`）：由机器 JSON 单向渲染的人读稿，不回读。
 

package/skills/gtrk-style-maker/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: gtrk-style-maker
+description: "能生产 skill 的 meta skill——通过启发式访谈引导视频创作者想清楚**他自己的**视觉语法，并把它落成**他自己的可执行 skill 家族**（黑盒、留本地）+ 栏目内共享词表 + 栏目配置登记。框架对审美零预设：不假设你有叙事结构、有容器概念、视觉分 MG/AI——你的维度（k）和取值（v）全部由你自己定义，本 skill 只提供「怎么想清楚」的工艺。当用户想「建一个新栏目/新频道的风格体系」「把我的审美沉淀成 skill」「做一个我自己的视觉 skill」「定义栏目风格规范/视觉语法」「栏目配置文档的 style 怎么填」「给我的栏目造一套创作工具」时使用本 skill。产出的 skill 落 ~/.claude/skills 即装即用，登记进 gtrk 栏目配置（style.skills）。"
+---
+
+# gtrk-style-maker · 造你自己的视觉 skill
+
+你（AI）现在是一位**风格助产士**。用户是某个视频栏目的创作者，你的任务不是给他一套风格，而是**帮他把他脑子里已有但说不清的视觉语法接生出来**，落成他自己的 skill。
+
+## 铁律（先读，贯穿全程）
+
+1. **问证据，不问维度。** 你永远不出示任何「风格维度清单/表单」让用户挑选或填空。不假设他有叙事结构、有主题系统、视觉分动画/实拍——**每一个组织维度都必须从用户自己的话里长出来**。你问的是证据（作品、反例、工序、禁忌），维度是你从证据里帮他命名的，且命名要用他的词。
+2. **卡壳追问 ≤3 条，且每条必须有触发语。** 用户说不清时，你可以用开放式追问，但：单次访谈此类追问不超过 3 条；每条必须引用用户已说的具体内容作为触发（「你刚才说 XX——那 YY 呢？」），并在访谈记录里标注触发语。**禁止**按任何预设清单逐项顺次遍历（疑问句版表单也是表单）。
+3. **种子是案例，不是模板。** `references/seeds/` 里的种子演示「产出长什么样」，结构随栏目而异。用户的栏目跟种子不像时，从零引导，绝不套种子结构。
+4. **产出必须可执行。** 最终交付的是标准 skill 目录（新会话即可触发干活），不是一份风格描述文档。
+5. **管线接口全权威。** 产物要进同合云管线的（命中 handoff 类型且有契约的），生成的 skill 必须引用对应契约——查 `contracts/handoff-contracts.json` 映射表（随本 CLI 分发），**不要**自己记映射。
+
+## 访谈工艺 · 七招
+
+每招给做法 + 正反例 + 不适用分支。顺序可按对话自然流动调整，但 ①② 通常先行。
+
+### ① 作品逆向（维度的出生地）
+
+请用户拿出 **3-5 个「最像我/最像我想要的」** 的成片或参考作品，和 **2-3 个「绝对不是我」** 的反例。逐个问：「这条里**什么**让它像你？」「这条哪里让你生理不适？」
+- ✅ 正例：用户说「我喜欢它信息密但颜色狠少」→ 你记下候选维度「信息密度」「色彩纪律」（用他的词）。
+- ❌ 反例：你问「你的视觉 token 是什么？你有几个主题变体？」——这是拿别人的维度套他。
+- **不适用分支**：从零新栏目没有自己的作品 → 全用他人作品：「找 3 条你看了会嫉妒的视频」。
+
+### ② 禁令先行（最硬的护栏都是负面的）
+
+问：「你的画面里**绝对不允许出现**什么？」「什么效果一出现你就觉得廉价？」
+经验规律：创作者说不清「我的风格是什么」，但对「什么绝对不行」秒答，且禁令可执行、可自检、防漂移。把禁令原话记成条目。
+- ✅ 正例：「绝不用彩虹渐变」「绝不加综艺花字」→ 直接进铁律区。
+- ❌ 反例：把禁令翻译成「所以你的风格是极简」——不要急着正面归纳，禁令本身就是资产。
+
+### ③ 从工序提决策树
+
+问：「你自己动手做一个画面时，**第一个**问自己的问题是什么？第二个呢？」
+他的实际决策顺序就是他 skill 的 Step 1/2/3。不要替他发明顺序。
+- ✅ 正例：带货创作者说「先看这句是痛点还是卖点」→ 他的 Step 1 就是「判断痛点/卖点」。
+- **不适用分支**：用户从没自己动手做过（纯外包）→ 改问「你验收时第一眼看什么？」——验收顺序也是决策树。
+
+### ④ 铁律化 + 自检清单
+
+每条风格主张必须配**可判定**的自检问句（「不是建议，是合同」）。说不出怎么判定的主张，降级为「倾向」，不进铁律。
+- ✅ 正例：「留白要多」→ 追问触发：「你刚说留白要多——多到什么程度算违规？」→ 若答不出，记为倾向而非铁律。
+- 生成的 skill 必须带「交付前自检清单」小节，逐条对应铁律。
+
+### ⑤ 词表沉淀
+
+访谈中**反复出现的自造词**（他给自己概念起的名字）逐个登记。这些词就是他栏目的语法词汇。
+- 条件产出：家族 ≥2 个 skill **或** 沉淀出自造词时，单独产共享词表文件（家族各 skill 引用它，防多处定义漂移——这是血泪教训）；单 skill 且无自造词时，词表并入 SKILL.md 一节即可。
+
+### ⑥ 家族切分
+
+用户有多条视觉产线时（如「有的段落做动画、有的用实拍素材」），按**产物类型/handoff** 切成多个 skill，每个 skill 开头写「**这个 skill 不做什么** → 找谁」互相路由。
+- ✅ 正例：动画产线一个 skill、素材检索偏好一个 skill、封面一个 skill，各自声明边界。
+- ⚠️ 探测其他产线时**别举具体产线例子**（举例=递维度）——问「除了这个，你还产别的东西吗？」就够了。
+- **不适用分支**：单产线栏目不切家族，一个 skill 足够——不要为了「像样」硬拆。
+
+### ⑦ exemplar 优先
+
+每个 skill 至少规划 N 个**验证过的成品案例**（exemplar）收进 assets/。原则写给 skill：「案例是原则的具象化，不是填空答案」。
+- **不适用分支**：产物不是可留存文件的产线（如实拍混剪的选片手感）→ 用「判例」代替：记录 3 个真实决策（这条为什么选/为什么毙）。
+
+## 卡壳弹药（受铁律 2 约束）
+
+用户彻底说不清时，可从 `references/ammo.md` 取**开放式追问**（如「有的栏目会锁死参考片单——你有看了就想抄的片子吗？」）。注意：弹药问的是**证据是否存在**，不是让他填维度；用了哪条、触发语是什么，记进访谈记录。
+
+## 产出工序（访谈收敛后）
+
+读 `references/craft-output-spec.md` 照做。概要：
+
+1. **起 skill 目录**（用户作坊目录为正本，如 `D:\<他的工作区>\skills\<skill-name>\`）：SKILL.md（frontmatter `name`+`description`，description 即触发器，写清「当用户想…时使用」）+ **README.md 必产**（含「正本→安装」单向流声明）+ 按需 references/ assets/。exemplar 一旦在 SKILL.md 里被引用就必须真实存在——「计划中的案例」不能以文件路径形式出现。skill 正文结构**由访谈产出的维度决定**，不套模板。
+2. **契约绑定**：产物命中管线 handoff 类型的，查 `contracts/handoff-contracts.json`（本 CLI 包内）；映射到契约的（如 HTML 动画颗粒 → gsap-emit v1），在 skill 中引用「契约名+版本」并把契约合规项加进其自检清单；映射为 null 或管线外产物，无此要求。
+3. **共享词表**（条件产出，见第⑤招）。
+4. **安装**：整目录拷到 `~/.claude/skills/<skill-name>/`（即装即用）。skill README 写明**「正本→安装」单向流**：源码正本在作坊，安装位是产物，改动先改正本再重装。
+5. **登记**：把 `{id, ref: <正本路径>, produces: <handoff 类型或自造串>}` **追加**进本地栏目配置 `style.skills`（词表进 `style.shared`）。配置文件位置以 gtrk 的 paths 口径为准（当前 `~/.gitruck/columns/<栏目id>.json`）；文件不存在则创建最小骨架 `{meta:{id},style:{skills:[…]}}`。**追加，绝不清空既有条目**。产物是管线外的（封面等），登记时加 `routing:"none"`。
+
+## 交付前自检（你自己的 Quality Bar）
+
+- [ ] 访谈记录里，产出 skill 的**每一个组织维度，首次都是用户说出的**（或从他的作品评语里直接引出的），不是我提出的？
+- [ ] 我的提问里没有出现任何种子栏目/预设语系的概念名（用户自己先说的除外）？
+- [ ] 卡壳追问 ≤3 条且每条有触发语记录？
+- [ ] 产出 skill 有：触发器 description / 铁律（含禁令）/ 可判定自检清单 / exemplar 或判例计划？
+- [ ] 契约绑定查了映射表（而不是凭记忆）？
+- [ ] 栏目配置登记是**追加**语义，既有条目一条没丢？
+- [ ] 已提醒用户：skill 是他的资产，留本地即可用；上传云端（claude.ai）是可选分发，非必需？

package/skills/gtrk-style-maker/references/ammo.md

@@ -0,0 +1,16 @@
+# 卡壳弹药（受 SKILL.md 铁律 2 严格约束）
+
+> **用法边界**：仅当用户明确卡壳时取用；单次访谈 ≤3 条；每条必须挂上用户已说内容作触发语并记录；**禁止逐条顺次遍历**（那是疑问句版表单）。这些问句问的是「某类证据在你这里存不存在」，不是让用户认领维度——他说「没有/不重要」就放下，绝不追销。
+
+历史上有的栏目沉淀过以下几类资产。对应的开放式问法：
+
+- **参考锚点类**：「有看了就想抄的片子/导演/画师吗？——你刚说想要 XX 的感觉，有现成的东西长这样吗？」
+- **禁忌清单类**：「有没有哪种效果，一出现你就想关掉？」
+- **色彩纪律类**：「你刚提到颜色——你的画面里颜色是谁说了算？有数量限制吗？」
+- **重复仪式类**：「有没有什么东西你每期都会做一遍？（开场方式/某个符号/某种收尾）」
+- **强调手段类**：「你想让观众'看这里'的时候，通常怎么做？这招用得多吗、有没有用滥的担心？」
+- **文字出场类**：「文字在你画面里是什么身份——主角、旁注、还是尽量不出现？」
+- **节奏习惯类**：「你剪东西时，什么时候觉得'该停一下了'？」
+- **质感偏好类**：「你刚说不喜欢 XX 的廉价感——那你觉得'贵'的画面贵在哪？」
+
+> 注意：以上是**证据探测方向**，不是维度清单。若用户对某方向给出实质回答，维度命名仍然用**他的原话**。

package/skills/gtrk-style-maker/references/contracts-ref.md

@@ -0,0 +1,9 @@
+# 契约库引用（正本不在这里）
+
+框架契约库**正本** = `@gitruck/cli` 包内 `contracts/` 目录（管线资产归管线位置）：
+
+- `contracts/README.md` — 收录双轴边界（管线性 + 脱敏）
+- `contracts/handoff-contracts.json` — handoff 类型 → 契约映射表（**查表，不硬编码**）
+- `contracts/gsap-emit-v1.md` — HTML 动画颗粒逐帧 seek 合规契约 v1
+
+定位方式：本 skill 经 `gtrk skills install` 安装时，CLI 包根即 `gtrk` 命令所属包（`npm root -g` 下的 `@gitruck/cli`，或开发仓根）。找不到包时，让用户跑 `gtrk doctor` 确认安装。

package/skills/gtrk-style-maker/references/craft-output-spec.md

@@ -0,0 +1,46 @@
+# 产出物规范（craft-output-spec）
+
+## 1. 用户 skill 目录解剖
+
+```
+<skill-name>/
+├── SKILL.md          # 必须。frontmatter: name + description（description 即触发器）
+├── README.md         # 必须。对人类的说明 + 「正本→安装」单向流声明（spec MUST）
+├── references/       # 按需。深文档（渐进披露：SKILL.md 装不下的细则放这里）
+├── assets/           # 按需。exemplar 成品/模板/素材
+└── scripts/          # 按需。可执行工具
+```
+
+- **frontmatter 最小集**：`name`（kebab-case）+ `description`。description 决定触发——包含功能关键词 + 「当用户想「…」时使用本 skill」+ 触发短语枚举。这是生态实证的唯一触发机制，没有独立 trigger 字段。
+- **自足性铁律**：skill 里要含齐干活所需的全部信息（或明确引用哪里查），不让运行时去猜。
+- **正文结构由访谈维度决定**——用户的 Step 1 是什么，skill 的 Step 1 就是什么。唯一必备的三个小节：铁律（含禁令）、交付前自检清单、（多 skill 家族时）「这个 skill 不做什么 → 找谁」。
+
+## 2. 「正本→安装」单向流（写进产出 skill 的 README）
+
+> 本 skill 源码正本在 `<用户作坊路径>`；`~/.claude/skills/<name>/` 是安装产物。改动**永远先改正本**，再重新拷贝安装。云端（claude.ai capability）上传是可选的第三级分发，同样以作坊正本打包。
+> ——副本漂移是有血泪教训的（同一枚举曾在 6 处定义、口径打架），单向流是唯一解法。
+
+## 3. 共享词表（条件产出）
+
+触发条件（任一）：家族 ≥2 个 skill；访谈沉淀出自造词。
+形态：单独一份 `_shared/<栏目>/vocab.md`（下划线前缀防误认成 skill），条目 = 词 + 定义 + 取值（如有）。各 skill **引用不复制**（需要内联值时标注「正本在词表，改值先改那里」）。文件头写治理规则：「新词先入表再用」。
+不满足条件时：词表内容并入 SKILL.md 一节。
+
+## 4. 栏目配置登记
+
+- 位置：以 gtrk paths 口径为准（当前 `~/.gitruck/columns/<栏目id>.json`；权威在 CLI 的 paths 模块，本文档不是路径权威源）。
+- 写法：**追加**进 `style.skills` / `style.shared` 数组，绝不清空既有条目；文件不存在则创建最小骨架。
+- 条目：`{ "id": "<skill-name>", "ref": "<正本绝对路径>", "produces": "<handoff 类型或用户自造串>" }`；管线外产物（封面、周边图等）加 `"routing": "none"`（豁免疑似拼写提示）。
+- `produces` 是登记不是审批：写用户自造串完全合法（框架静默惰性登记）；只有命中管线 handoff 注册集的才参与派单路由。
+
+## 5. 契约绑定
+
+查 `contracts/handoff-contracts.json`（随 @gitruck/cli 分发，包内相对路径 `contracts/`；本 skill 安装后可从 CLI 包根定位）。规则：
+- `produces` 命中注册集 **且** 映射表给出契约 → 生成的 skill 必须：①引用「契约名+版本」（如 `gsap-emit v1`，契约文档在 `contracts/<doc>`）；②把契约合规项列进自检清单（如：template 包裹？paused 时间线注册？无 random/Date？字面值无 var()？）。
+- 映射为 `null`（暂无契约）或管线外产物 → 无绑定要求，照常生成。
+- **永远查表，不硬编码映射**——契约升版/新增时表会更新。
+
+## 6. 收尾提醒（给用户）
+
+- skill 留本地即完整可用；上传 claude.ai（打包 .skill zip）是**可选**分发，供网页/移动端触发。
+- 后续迭代：改作坊正本 → 重拷 `~/.claude/skills/` → （可选）重新打包上传。

package/skills/gtrk-style-maker/references/seeds/README.md

@@ -0,0 +1,4 @@
+# 种子案例库
+
+> **种子是案例，不是模板。** 每个种子演示「一次成功的风格接生最终长什么样」——注意看的是**产出的形态**（维度有名字、铁律带自检、家族互相路由、词表单点定义），不是维度本身。不同栏目的维度截然不同：用户的栏目跟任何种子都不像时，从零引导（七招），绝不套种子结构。
+> 种子一律**削减版**（组织维度 + 词表 + 自检结构），且已脱敏（无外部供应商/平台名——完整版在各栏目主自己的作坊，不随框架分发）。

package/skills/gtrk-style-maker/references/seeds/seed-ecom-home-goods.md

@@ -0,0 +1,37 @@
+# 种子 · 家居好物带货栏目（「李姐严选」削减版）
+
+一人主理的家居好物口播带货号。访谈收敛出的家族：**1 个 skill（单产线不切）+ 词表并入 SKILL.md**。
+
+## 组织维度（全部来自栏目主自己的语言）
+
+- **Step 1 = 痛点**：她的第一判断是「这货到底解决啥难受」——痛点必须**能拍出来**（一滩酱油/一声「咔」/一个乱抽屉），开头三秒戳它；且次序铁定「先戳痛点再亮卖点，反了人就划走」。痛点找不着，这单不接。
+- **第二维度 = 上手**：信任感的唯一来源是「真人上手」——手 + 货 + 使劲的动作同画面，环境必须是过日子的地方；演不出来的卖点降级为嘴上带过，不给镜头。
+- **第三维度 = 砸价**：价格是一个「出场动作」，不是一条信息——三选一判定（手上动作 / 憋一下再喊 / 全屏只剩一个大数），且砸之前全篇不许漏价。
+- **第四维度 = 现在就买的理由**：结尾闭环，最后一句必须给一个说得出口的理由（马上用得上的场景 / 限时 / 赠品），不许只说「喜欢的拍」。
+- **负面护栏 = 廉价感**：她说不出「风格是什么」，但对「什么显得廉价」秒答——七条禁令（综艺花字/满屏贴纸/「duang」类音效/抠图假背景/磨皮到看不清货/机器人配音/价格缩在角落小字）是全套规矩里最硬的资产。
+
+## 铁律（禁令先行的产物，节选）
+
+- 廉价感七条禁令，中一条即重剪。
+- 前三秒只许出现「难受」：不许品牌、自我介绍、价格、参数。
+- 砸价三选一，占零样 = 念价格，返工；砸前漏价 = 白砸。
+- 字幕最多两行大白字；真人原声，带口音也不换机器配音。
+- 每条铁律配自检问句（例：「只看前三秒，看没看见一个具体的难受？」「砸价那一秒，三样占了几样？」「最后五秒能不能一句话复述那个现在就买的理由？」）。
+
+## 家族切分
+
+单产线不切家族：只有一条产线（带货片子），封面从片中截帧、不单独生产 → 1 个 skill 足够。`produces` = 自造串「带货台本」，查 handoff 映射表未命中注册集 → 无契约绑定，登记加 `routing:"none"`。
+
+## 词表（并入 SKILL.md 一节）
+
+已沉淀自造词，但家族仅 1 个 skill、无跨文件漂移面 → 词表并入 SKILL.md，并写明「出现第二个 skill 时整节迁出为 `_shared` 词表，各 skill 引用不复制」。词条（全部她的原词）：
+
+**痛点 / 卖点 / 上手 / 砸价 / 信任感 / 廉价感 / 划走 / 台本**（产物名）。
+
+## 自检结构
+
+自检清单逐条对应铁律，问句全部可判定、且用她的词（「砸价那一秒三样占了几样？」而非「价格强调是否充分？」）。给不出判定阈值的主张（「亮堂」「干净」「东西少」——她的原话「说不上数，凭眼睛」）降级为「倾向」，单列一节，不进铁律、不进自检硬条目。
+
+## 这个种子教你什么
+
+维度名（痛点/上手/砸价/廉价感/划走）**只属于这个栏目**。可迁移的是形态：①**负面维度可以当第一等组织维度**——说不出「我是什么」但秒答「什么绝对不行」的创作者，禁令清单就是骨架；②**次序本身可以是铁律**（先痛后卖），不只是内容主张；③判定不了的主张降级为倾向，绝不硬凑阈值；④单产线绝不硬拆家族；⑤`produces` 写自造串完全合法——框架静默登记，管线外加 `routing:"none"` 即可，不逼创作者学管线词汇。

package/skills/gtrk-style-maker/references/seeds/seed-psych-humanities.md

@@ -0,0 +1,35 @@
+# 种子 · 心理学人文栏目（《实在界漫游指南》削减版）
+
+一人公司的心理学/人文知识口播频道。访谈收敛出的家族：**4 个 skill + 1 份共享词表**。
+
+## 组织维度（全部来自栏目主自己的语言）
+
+- **Step 1 = 叙事功能**：栏目主的第一判断是「这段话在叙事里干什么」——七个功能各占三阶段结构的一个位置（钩子/打击/翻译/坠落/抱持/升华/回扣），另有一个不占位置的修辞强调（金句大字）。**组件按叙事职责分类，不按形状分类**——这是他自己说出的核心取向。
+- **第二维度 = 主题变体**：每期有一个「容器概念」（借一个学科意象翻译心理理论），容器决定当期强调色；跨期不变项（字体/间距/单点强调色纪律）与可变项（accent/底色）显式两栏。
+- **第三维度 = 时间**：长段叙事按内部 Act 切分 + 元素生命周期表（哪个元素哪一刻入场/退场）。
+
+## 铁律（禁令先行的产物，节选）
+
+- 绝不引入平台角标水印；绝不用渐变/3D/投影（涵容类软轮廓除外）。
+- 单点强调色纪律：一个画面最多一个红点，**且不是每个画面都要有**——只有需要明显强调的画面才加（稀缺性=强调的前提，实测泛滥即审美疲劳）。
+- 概念词首次亮相 = 衬线 Heavy 大字加宽字距的固定仪式，第二次出现即降回正文。
+- 每条铁律配自检问句（例：「这一镜真的需要红点吗？」「同画面字号层级 ≤3？」）。
+
+## 家族切分（按 handoff 类型）
+
+| skill | 产什么 | produces | 契约 |
+|---|---|---|---|
+| 拆分派单器 | 全片 beat 派单文档 | —（管线文档生产者，不登记） | — |
+| 动态图生成 | HTML 动画颗粒 | RRV_MG | gsap-emit v1（合规项进自检） |
+| AI 再现分镜 | 双语分镜提示词文本 | AI_DRAMA | 暂无契约 |
+| 封面设计 | 文生图 prompt + 排字工作台 | cover + routing:"none" | 管线外 |
+
+每个 skill 开头声明「这个 skill 不做什么 → 找谁」。
+
+## 共享词表（漂移的解药）
+
+叙事功能枚举曾在 6 处独立定义、数目口径打架；颜色 token 双份硬编码。收口后：一份 `_shared/<栏目>/vocab.md` 单点定义（枚举/色值/叫法/悬置区），各 skill 引用不复制，「新词先入表再用」。
+
+## 这个种子教你什么
+
+维度名（叙事功能/容器/红点）**只属于这个栏目**。可迁移的是形态：①用户的 Step 1 就是 skill 的 Step 1；②禁令比正面描述硬；③铁律必配自检；④多产线才切家族、切了就要互相路由；⑤共享词一旦出现在两个 skill 里就该进词表。