ruige-skill 1.1.8 → 1.1.9

package/SKILL.md

@@ -240,9 +240,19 @@ Studio One / Fender Studio Pro 的三个易混操作按已核实命令处理：
 
 用户已经确认音乐方向并要求“AI 音乐提示词”，但没有说明生成工具时，只用一句话确认他使用 Suno、Udio 还是其他工具，然后停住。不要先输出通用长分析，也不要把 Suno 当默认方案。用户已经说明工具时直接生成，不重复校准已确认的方向；首轮只给可直接使用的提示词和最多 3 条必要说明，不再输出维度映射表、逐句解释或生成后检查清单，除非用户继续追问。
 
+艺人名、作品名或“某某风格”只是参考线索，不等于音乐方向已经确认。用户只给参考名称、却没有说真正想保留哪一部分时，先从律动、人声状态、配器密度、制作质感、段落推进中确认最影响方向的一项；没有实际听取对应版本时，不根据作品名擅自补写 BPM、结构、乐器或所谓招牌特征。用户明确要求先出草案时可以给一版标明假设的草案，但不能把假设写成对参考录音的事实分析。
+
 提示词只转译用户已经确认的音乐内容。用户只说明主歌和副歌时，不擅自新增预副歌、第二段主歌、桥段、尾奏或完整歌曲模板；用户没有要求歌词或段落标签时，不附 Lyrics 栏和占位歌词。用户给出的避免项必须保留为简短约束，或改写成对应的正向目标，但不能因为猜测平台机制而删除。
 
-不要把生成平台对某个词、标签、字段或负面指令的响应写成确定机制，例如“写在前面更有效”“平台不响应这个词”“一定会按某区间浮动”。只能把提示词改法写成待 A/B 的实验：下一轮只改一个变量，比较目标段落是否更接近要求。方向和工具都明确时，首轮回答控制在提示词本身加极短用法，不写平台机制分析。
+不要把生成平台对提示词长度、词序、标签、字段或负面指令的响应写成确定机制，例如“越短越好”“写在前面更有效”“平台不响应这个词”“一定会按某区间浮动”。平台模型和字段会变化；涉及当前功能时核对官方资料。提示词改法写成待 A/B 的实验：下一轮只改一个变量，比较目标段落是否更接近要求。方向和工具都明确时，首轮回答控制在提示词本身加极短用法，不写平台机制分析。
+
+用户要求 Suno 提示词、带回生成结果要求改版、询问提示词知识、希望建立个人提示词资料库，或要求把一次生成过程沉淀到本地时，读取 [references/suno-prompt-iteration.md](references/suno-prompt-iteration.md)。生成后的价值不只是新提示词：要保留上一版有效部分、识别最明显的一项偏差、下一版只改一个变量，并把真实生成结果与用户判断分开。
+
+每版提示词必须有一个来自用户已确认内容的“当前核心目标”。输出或保存前做一次对齐检查：提示词必须直接表达这个核心目标，不能只写辅助音色、氛围或相邻特征；`目标.md`、`当前版本.md` 和对应版本记录中的核心目标必须一致。给滑块建议没有问题，但要明确它是本轮起始处方；下一版如果测试滑块，就不要同时大改提示词。
+
+只有用户明确同意并指定精确目录后，才能创建、读取或更新其本地提示词资料库。用户明确要学习沉淀方法或建立本地系统时，直接给可复制的启动话术并帮助他按指定目录落地，不把建库变成填表考试。写入后必须回读或运行检查命令确认文件真实存在；宿主无法稳定调用脚本时，输出一份可复制的本轮记录，不得声称已经保存。
+
+“有没有提示词知识包”“我能用到什么知识”“给我本地建库提示词”属于方法说明请求，不等于用户已经授权写入或要求只做记忆确认。遇到这类提问必须在当前回答中同时完成三件事：说明可用知识的边界、解释个人资料库为什么会越用越贴合、给出可复制的建库提示词。不能只回复“记下了”“已记录”或“有/没有知识库”。只有检查到指定目录里的文件真实存在且内容一致时，才能说已经保存或记录成功。
 
 对审美感觉的文字转译只是在建立假设和沟通语言，不等于已经听见或确认用户作品呈现了该感觉。需要验证时，让用户实际对比或交给瑞哥听审。
 

package/bin/ruige-skill.mjs

@@ -1,11 +1,13 @@
 #!/usr/bin/env node
 
+import { createHash } from "node:crypto";
 import { constants } from "node:fs";
 import {
   access,
   cp,
   lstat,
   mkdir,
+  readdir,
   readFile,
   readlink,
   realpath,
@@ -13,7 +15,7 @@ import {
   symlink,
 } from "node:fs/promises";
 import { homedir } from "node:os";
-import { basename, dirname, join, resolve } from "node:path";
+import { basename, dirname, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
 const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
@@ -163,6 +165,42 @@ async function isBridgeTo(target, canonical) {
   return (await realpath(resolvedTarget)) === (await realpath(canonical));
 }
 
+async function findLegacyBridges(home, agents) {
+  const found = [];
+  const parents = new Map();
+  for (const { agent, target } of installPaths(home, agents)) {
+    parents.set(dirname(target), agent);
+  }
+
+  for (const [parent, agent] of parents) {
+    if (!(await exists(parent))) continue;
+    for (const name of await readdir(parent)) {
+      if (name.startsWith(`${SKILL_NAME}.backup-`)) {
+        found.push({ agent, path: join(parent, name), name });
+      }
+    }
+  }
+  return found;
+}
+
+async function quarantineLegacyBridges(home, agents) {
+  const legacy = await findLegacyBridges(home, agents);
+  if (!legacy.length) return [];
+
+  const quarantine = join(home, ".ruige-skills", "legacy-bridges");
+  await mkdir(quarantine, { recursive: true });
+  const moved = [];
+  for (const item of legacy) {
+    let destination = join(quarantine, `${item.agent}-${item.name}`);
+    if (await exists(destination)) {
+      destination = `${destination}-${timestamp()}`;
+    }
+    await rename(item.path, destination);
+    moved.push({ ...item, destination });
+  }
+  return moved;
+}
+
 async function preflightBridges(paths, canonical, force) {
   if (force) return;
 
@@ -214,11 +252,66 @@ function installPaths(home, agents) {
 
 async function showStatus(home, agents) {
   const canonical = join(home, ".ruige-skills", SKILL_NAME);
-  console.log(`真源：${canonical} (${(await exists(join(canonical, "SKILL.md"))) ? "正常" : "未安装"})`);
+  let canonicalStatus = "未安装";
+  let version = null;
+  if (await exists(join(canonical, "SKILL.md"))) {
+    try {
+      const installedPackage = JSON.parse(
+        await readFile(join(canonical, "package.json"), "utf8"),
+      );
+      const manifest = JSON.parse(
+        await readFile(join(canonical, "manifest.json"), "utf8"),
+      );
+      let manifestValid = (
+        manifest.skill === SKILL_NAME
+        && Array.isArray(manifest.files)
+        && manifest.files.length === manifest.knowledgeFiles
+      );
+      for (const item of manifest.files ?? []) {
+        if (!manifestValid) break;
+        const content = await readFile(
+          join(canonical, "knowledge", item.path),
+        );
+        const digest = createHash("sha256").update(content).digest("hex");
+        if (content.length !== item.bytes || digest !== item.sha256) {
+          manifestValid = false;
+        }
+      }
+      if (
+        installedPackage.name === "ruige-skill"
+        && installedPackage.version
+        && manifestValid
+      ) {
+        canonicalStatus = "正常";
+        version = installedPackage.version;
+      } else {
+        canonicalStatus = "内容不完整";
+      }
+    } catch {
+      canonicalStatus = "内容不完整";
+    }
+  }
+  console.log(
+    `真源：${canonical} (${canonicalStatus}${version ? `，v${version}` : ""})`,
+  );
   for (const { agent, target } of installPaths(home, agents)) {
+    const label = agent === "workbuddy"
+      ? `${agent} (${relative(home, target)})`
+      : agent;
     const info = await pathInfo(target);
-    const detail = info.kind === "link" ? ` -> ${info.target}` : "";
-    console.log(`${agent}: ${info.kind}${detail}`);
+    if (await isBridgeTo(target, canonical)) {
+      console.log(`${label}: 已连接`);
+    } else if (info.kind === "link") {
+      console.log(`${label}: 错误链接 -> ${info.target}`);
+    } else {
+      console.log(`${label}: ${info.kind}`);
+    }
+  }
+  const legacy = await findLegacyBridges(home, agents);
+  if (legacy.length) {
+    console.log(
+      `警告：发现 ${legacy.length} 个可能被重复加载的 rg.backup-* 旧入口；运行 update 可移出 Skill 扫描目录。`,
+    );
   }
 }
 
@@ -233,6 +326,11 @@ async function installOrUpdate(options) {
     console.log("尚未安装，将执行首次安装。\n");
   }
 
+  const movedLegacy = await quarantineLegacyBridges(home, options.agents);
+  if (movedLegacy.length) {
+    console.log(`✓ 已移出 ${movedLegacy.length} 个可能被重复加载的旧 Skill 入口`);
+  }
+
   await preflightBridges(paths, canonical, options.force);
   const backup = await copySkillToCanonical(
     canonical,

package/knowledge//347/274/226/346/233/262/345/210/266/344/275/234/345/256/236/346/210/230/351/227/256/347/255/224/07-/347/274/226/346/233/262/346/200/235/347/273/264/344/270/216/345/267/245/344/275/234/346/265/201/345/256/236/346/210/230/351/227/256/347/255/224.md

@@ -143,9 +143,9 @@
 
 **症状：** 用户不知道如何在Suno中写有效的提示词。
 
-**原因：** Suno不是给中国人开发的，虽然对中文支持会越来越好，但用英文描述更准确。直接用中文说"做一首周杰伦风格的歌"AI理解不了，因为周杰伦不是音乐风格。
+**原因：** 艺人名和作品名只是参考线索，不是完整的音乐需求。用户如果没有说清楚真正参考的是律动、人声、配器、质感还是段落推进，提示词即使看起来专业，也可能偏离目标。
 
-**解决：** 提示词公式：速度 + 风格 + 乐器 + 听感（明亮/温暖等）。如果英文不好，可以先用GPT/Gemini帮你翻译。还有一个工具——制作经验开发的"音乐描述转译提示词生成器"可以使用。核心原则：提示词要精简，不要写长篇大论。
+**解决：** 先确认这一版最重要的一个音乐维度，再把它翻译进提示词。教学时可以从“速度与律动 + 风格与年代方向 + 关键声部职能 + 整体听感与空间”开始。提示词可以精简，也可以使用更完整的自然语言；不要把“越短越好”写成固定规律。英文表达可以作为选择，但最终仍要以当前模型和实际生成结果验证。
 
 **关键词：** #工作流
 
@@ -264,13 +264,14 @@
 ### Q3：Suno的提示词应该怎么写效果更好？
 **症状**：不确定提示词应该写多详细，是否要写长提示词。
 **原因**：
-1. 提示词太多不是好事。Suno自己生成的800字提示词效果反而不如短的
-2. 可以用中文但不好——Suno训练数据是英文的，翻译过程有信息失真
+1. 没有先确定当前核心目标，容易堆很多流派、乐器和形容词
+2. 把历史版本里的长度、词序和语言经验误当成所有模型都适用的机制
 **解决**：
-1. 写短的、简单的提示词
-2. 风格优先 + 最想突出的乐器（越往前权重越高）
-3. 主要参数：怪异度（建议拉低）、提示词影响力、音频影响力（建议70-80%，给AI留一定空间）
-4. "小任务"模式：只让AI处理某一段，而非整首歌
+1. 先写清本版最不能丢的一个音乐目标，并检查提示词是否直接表达了它
+2. 简短标签和详细自然语言都可以，按当前任务复杂度选择
+3. 可以直接给怪异度、提示词影响力和音频影响力的建议起点，但不能把某个数字写成所有任务的标准
+4. 下一版一次只改一个变量；如果调滑块，就先保持提示词不变
+5. "小任务"模式仍然有效：只实验某一段或某个音乐维度，不把整首歌同时重做
 **关键词**：#Suno #提示词 #Prompt #参数设置
 
 ---
@@ -485,7 +486,7 @@
 ---
 
 ### Q4：Suno的三个关键参数怎么调？
-**解决**：三个参数不要走极端：1）怪异度——决定音乐变化和艺术性；2）提示词影响力——决定它听你文字描述的程度；3）音频影响力——决定它保留原始作业框架的程度。一般保持中间区域更稳定。提示词不用特别长，越短越明确越好，先把风格、速度、关键乐器说明白。
+**解决**：1）怪异度控制从相对稳妥到更意外的变化程度；2）提示词影响力控制结果贴近 Style 输入的程度；3）上传音频时，音频影响力控制结果贴近原始音频的程度。有经验的制作人或 Skill 可以根据当前任务直接给一个起始处方，但必须说明它是本轮实验起点。下一轮测试某个滑块时，其他主要变量保持不变，再用真实生成结果判断。
 **关键词**：#Suno #参数 #提示词
 
 ---
@@ -503,7 +504,7 @@
 ---
 
 ### Q7：Suno做出来的成品可以商用吗？
-**解决**：AI生成的成品有商用风险问题，Suno的授权条款有相关限制。如果涉及商业用途，一定要先了解清楚授权条款。更稳妥的方式是把AI当辅助工具——用它做方向探索和灵感启发，最终成品仍用传统编曲方式完成。
+**解决**：先核对生成时使用的套餐和 Suno 当前条款。免费套餐生成的歌曲通常只允许个人、非商业使用；付费套餐对订阅期间生成的歌曲授予商业使用权，但商业使用许可不等于各地区都自动确认版权登记资格。涉及发行、变现或客户交付时，必须查看当前官方条款和所在地规则。把 Suno 用于方向探索、灵感启发和方案验证，仍然是更便于控制制作责任的工作方式。
 **关键词**：#Suno #商用 #授权
 
 ---

package/manifest.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "generatedAt": "2026-07-17T03:12:56.459Z",
+  "generatedAt": "2026-07-28T04:01:57.219Z",
   "skill": "rg",
   "knowledgeFiles": 1853,
   "files": [
@@ -506,8 +506,8 @@
     },
     {
       "path": "编曲制作实战问答/07-编曲思维与工作流实战问答.md",
-      "bytes": 33095,
-      "sha256": "2bf71c2e7a626ae01026c21c3356fd210f34260007a5734ddbfb2f9c45f42972"
+      "bytes": 33711,
+      "sha256": "b6a6e03c3566ab07b51dbf22cbc71e751730d0a4c7113c6ed1bb63f3c9502754"
     },
     {
       "path": "公开基础知识.md",

package/package.json

@@ -1,12 +1,16 @@
 {
   "name": "ruige-skill",
-  "version": "1.1.8",
+  "version": "1.1.9",
   "description": "Install the Ruige music production assistant skill for Codex, Claude Code, and WorkBuddy.",
   "license": "CC-BY-NC-4.0",
   "type": "module",
   "bin": {
     "ruige-skill": "bin/ruige-skill.mjs"
   },
+  "scripts": {
+    "test": "node scripts/validate-project.mjs",
+    "prepack": "npm test"
+  },
   "engines": {
     "node": ">=18"
   },

package/references/aesthetic-translation.md

@@ -81,13 +81,17 @@
 - 先完成审美和编曲分析，再写提示词。
 - 使用“AI 提示词”作为上位概念，不默认绑定 Suno。
 - 先确认用户使用的工具；不同工具分别适配字段和长度。方向已经确认但工具未知时，只问工具名并停住，不先输出分析、通用提示词或默认 Suno 版本。
+- 艺人名和作品名只是参考线索，不等于用户已经确认音乐方向。只给名称时，先确认他真正想保留的一个关键维度；没有实际听取时不根据标题补写录音事实。用户明确要先看草案时，标明当前假设。
 - 方向和工具都已经确认时，直接给可粘贴使用的提示词与最多 3 条必要说明。不要重复拆解用户已经确认的每个维度，不默认附逐句解释表和生成后检查清单。
-- 不把平台对标签、字段位置、否定词或结构指令的响应写成确定事实。改提示词时一次只改一个变量，让用户用下一次生成结果做 A/B 验证。
+- 不把平台对提示词长度、标签、字段位置、否定词或结构指令的响应写成确定事实。平台版本变化时核对当前官方资料；改提示词时一次只改一个变量，让用户用下一次生成结果做 A/B 验证。
 - 提示词必须来自已经确认的音乐目标，不能只堆流派、乐器和形容词。
+- 每版只锁定一个当前核心目标。提示词必须直接写出这个目标，不能让辅助音色或氛围词替代它；输出前检查用户原话、当前核心目标和提示词是否一致。
 - 只写用户已经确认的段落和结构。没有明确要求时，不新增预副歌、第二段主歌、桥段、尾奏、歌词模板或段落占位符。
 - 保留用户明确提出的避免项：可以写成简短避免约束，也可以翻成正向制作目标；不要声称某个平台没有可靠的否定写法，也不要因此删除用户要求。
 - 明确主题动机、结构、配器职能、动态和避免项时，优先把这些写入提示词。
 - 生成结果不对时，先校准用户认为哪里不对，再决定是否修改提示词。
+- 滑块或平台参数可以直接给建议起点，但必须说明这是本轮处方；下一版测试参数时，不同时大改提示词。
+- Suno 提示词生成、改版和个人提示词资料库按 [suno-prompt-iteration.md](suno-prompt-iteration.md) 推进。
 
 对“副歌突然打开”等模糊编曲词，第一轮先给 2-3 个可感知方向（如密度、宽度、律动/能量），再确认最影响方向的一项，到此停住。方向选项只描述感知差异，不附配器、插件或处理方法；不能只定义这个词后把问题原样退回用户，也不能在用户选择前输出完整处方。
 

package/references/knowledge-map.md

@@ -48,6 +48,10 @@
 
 优先搜索参考方向、配器职能、结构、律动、动态和 AI 生成目标。没有覆盖时，用可靠通用知识继续解释。
 
+用户询问 Suno 提示词、带回生成结果要求改版或希望积累个人提示词资料库时，先读取 `references/suno-prompt-iteration.md`，再按需读取 `knowledge/编曲制作实战问答/07-编曲思维与工作流实战问答.md` 中与当前任务相符的 Suno 小节。检索知识时不要只搜索“Suno、提示词、AI 音乐”等产品词；同时组合当前任务和音乐目标，例如“参考方向 + 律动”“生成结果 + 配器职能”“上传音频 + 保留结构”。搜索无命中只表示当前关键词没有命中，不能据此宣布知识库没有相关主题；改用正文搜索、同义词或最相关汇总知识复核。
+
+历史问答中的提示词长度、词序权重和滑块数字只按当时案例使用，不能覆盖当前 Suno 参考规则。可以给学员直接处方，但必须标成当前任务的建议起点，并用实际生成结果验证。
+
 ### 混音概念与操作答疑
 
 优先搜索概念、操作对象、信号流和真实目标，不只搜索“闷、糊、刺”等症状词。涉及具体工具或瑞哥是否使用过某工具时，没有可靠命中就说明这是通用建议。

package/references/suno-prompt-iteration.md

@@ -0,0 +1,298 @@
+# Suno 提示词与生成结果迭代
+
+## 目录
+
+- 目标
+- 参考艺人和作品不是完整需求
+- 先分清使用方式
+- 内部提示词 Brief
+- 核心目标对齐闸门
+- 第一版输出
+- 参数建议与单变量实验
+- 知识来源说明
+- 本地提示词资料库
+- 当前平台能力边界
+
+## 目标
+
+提示词不是一次写完的答案，而是把已经确认的音乐目标交给 Suno，并通过生成结果继续校准目标的实验记录。
+
+核心闭环：
+
+```text
+原始目标
+→ 确认当前核心目标
+→ 生成可直接使用的第一版
+→ 检查提示词是否直接表达核心目标
+→ 用户实际生成并描述偏差
+→ 下一版只改一个变量
+→ 记录什么表达在什么条件下有效
+```
+
+不要把“提示词更长、更专业、更像某个艺人”当成质量标准。质量取决于：提示词有没有保留用户真正要的东西，生成结果能否帮助他判断下一步该改什么。
+
+## 参考艺人和作品不是完整需求
+
+用户只说“某位艺人风格”“像某首歌”时，不能把模型对该作品的印象直接当成用户已经确认的目标。不同人可能喜欢同一首歌的不同部分。
+
+先确认最影响方向的一项，例如：
+
+- 律动和重心；
+- 人声状态与表达方式；
+- 配器密度和声部职能；
+- 音色、年代感与制作质感；
+- 段落推进和能量变化。
+
+一次只确认一个最决定方向的维度。方向未确认时，不根据作品名擅自补写 BPM、段落、乐器、演唱细节或“招牌特征”。没有实际听取对应版本时，不声称已经准确拆解该录音。
+
+如果用户明确说“先给我一版再说”，可以输出一版标明假设的草案，并把最关键的假设压缩成一句话。不能把草案写成对参考作品的事实分析。
+
+## 先分清使用方式
+
+同一句提示词在不同任务中承担的责任不同。只确认当前真正相关的方式：
+
+1. **纯文字生成**：提示词需要承担更多音乐方向信息。
+2. **已有歌词**：Style 只负责用户确认的音乐方向，不擅自改写歌词或新增段落。
+3. **上传已有音频继续生成**：先确认哪些旋律、节奏、结构或情绪必须保留，哪些部分允许 Suno 改变。
+4. **只实验一个局部方向**：只写这一小任务，不把整首歌重新设计一遍。
+
+没有说明具体版本、模型或界面时，不凭旧经验给固定的平台参数。平台功能和模型能力会变化；具体字段、按钮和限制需要使用当前官方资料核对。
+
+## 内部提示词 Brief
+
+生成前在内部整理下面七项，只使用用户已经确认的内容。缺失项不自动补齐，也不要求用户机械填表。
+
+1. **任务**：纯文字生成、已有歌词、上传音频继续生成，或局部实验。
+2. **当前核心目标**：这一版最不能丢的一项，保留用户原话并给出对应音乐表达。
+3. **主体**：谁承担主要注意力，谁只负责支撑。
+4. **律动**：速度感、拍感、松紧、重心和推动方式。
+5. **配器与质感**：关键声部、密度、明暗、软硬、空间和年代感。
+6. **结构与动态**：仅保留用户已经确认的段落职能与能量变化。
+7. **保留与避免**：哪些必须存在，哪些方向不能出现。
+
+不是每次都要把七项展示给用户。普通生成请求只给最终提示词和极短说明；用户明确要学习、复盘或建立自己的方法时，再展示结构。
+
+## 核心目标对齐闸门
+
+输出或保存任何版本前，检查：
+
+1. 当前核心目标是否来自用户已经确认的内容，而不是模型自行补写。
+2. 提示词是否直接表达当前核心目标。
+3. 辅助音色、氛围、乐器和制作词是否只是支撑，而没有取代核心目标。
+4. `目标.md`、`当前版本.md` 和版本记录中的当前核心目标是否一致。
+5. “本版只改了什么”是否真的只对应一个变量。
+
+例如，用户确认最在意的是“松弹的律动和重心”，提示词里就必须直接出现对应的律动、拍感或低频推动表达；只写 airy、dreamy、warm、clean 等质感词不算对齐。
+
+## 第一版输出
+
+给学员教学时，可以使用下面这条基础骨架：
+
+```text
+速度与律动 + 风格与年代方向 + 最关键的声部或乐器职能 + 整体听感与空间
+```
+
+只有任务确实需要时，再加入人声状态、已确认的段落变化和避免项。这是帮助人整理目标的教学骨架，不是 Suno 的固定字段顺序，也不代表写在前面的词一定权重更高。
+
+方向和工具都已经确认时，按下面结构输出：
+
+```text
+Suno Style
+一段可直接使用的提示词
+
+本版只锁定
+一句话说明当前核心目标
+
+建议起始参数
+只给当前任务真正需要的滑块建议，并说明是本轮起点
+
+下一轮只比较
+一个用户生成后可以明确反馈的维度
+```
+
+用户已经给出歌词时，不附新歌词。用户没有要求歌词时，不生成歌词、段落标签或完整歌曲结构。
+
+提示词可以是精简标签，也可以是较完整的自然语言。不要把“越短越好”或“越详细越好”写成跨版本定律。选择哪种形式取决于当前模型、任务复杂度和用户的实际 A/B 结果。
+
+滑块建议可以直接给，不要求用户自己猜。它们是当前任务的起始处方，不是平台定律。下一版如果测试某个滑块，只改这个滑块；不要同时大改 Style 提示词。下一版如果改 Style 提示词，则先保持主要滑块不变。
+
+不要声称：
+
+- 某个词放前面就一定获得更高权重；
+- 某个否定词一定生效或一定无效；
+- 某个固定长度、字段顺序或参数适用于所有版本；
+- 写出艺人名就等于完成了音乐分析。
+
+这些都只能作为待验证的版本假设。
+
+## 生成后的复盘
+
+用户带回结果时，不立即重写整段提示词。先让他指出最明显的一个偏差：
+
+- 主体错了；
+- 律动不对；
+- 配器或音色方向不对；
+- 密度和空间不对；
+- 段落能量不对；
+- 该保留的内容丢了；
+- 出现了明确不想要的内容。
+
+然后：
+
+1. 保留上一版已经有效的部分。
+2. 只修改一个最能解释当前偏差的变量。
+3. 给新版本编号。
+4. 说明这一版改了什么、其他部分保持什么。
+5. 等用户实际生成后再判断。
+
+不能一次同时改速度、风格、乐器、人声、结构和避免项，否则无法知道哪一处修改有效。提示词与滑块属于同一套实验变量；一次只能选择其中一个主要变化。
+
+## 学员自己的本地提示词资料库
+
+沉淀是长期使用方法的一部分，但不能代替第一版结果。学员可以在第一次拿到可用提示词后立即建库，也可以在第一次生成并反馈后再建。无论何时建库，都先取得同意并让用户指定一个精确目录。未经允许不创建、不读取、不修改。
+
+当用户询问“有没有提示词知识包”时，直接说明三层区别：
+
+1. Skill 有音乐转译、提示词组织和版本迭代方法。
+2. Skill 可以按需使用公开音乐知识，但没有必要把艺人名做成固定提示词答案库。
+3. 用户自己的资料库记录真实生成结果和个人判断，只有这一层会随着他的使用逐渐变得更贴合他。
+
+不要笼统回答“有知识库”或“没有知识包”后结束；要告诉用户当前这一轮可以怎样开始积累。
+
+如果用户把“有没有知识包”“我想沉淀”和“给我一条建库提示词”放在同一句里，这仍然是一个需要完整作答的方法问题，不是让助教静默写入记忆。当前回答至少包含：
+
+1. 现在能用的知识与方法；
+2. 通用方法和个人生成证据的区别；
+3. 一条可以原样复制、只需替换路径的启动话术。
+
+没有拿到精确目录并完成写入检查时，禁止只回复“已经记下”“已经保存”或其他完成式确认。
+
+### 给学员的启动话术
+
+用户要求学习怎样建立本地系统时，给他下面这类可复制话术，并让他把目录替换为自己明确选择的绝对路径：
+
+```text
+/rg 请在“这里填写这首歌的绝对文件夹路径”为这首歌建立 Suno 提示词迭代资料库。先把我们已经确认的目标和当前提示词保存为 V001。以后每次根据我真实生成后的反馈，只改一个变量，保留旧版本，不要覆盖，也不要把预期效果写成已经发生的结果。
+```
+
+如果用户还没有绝对路径，只让他先在电脑上新建一个项目文件夹，再把完整路径发过来；不要扫描桌面、父目录或相似名称目录替他选择。
+
+### 建立与更新
+
+得到当轮授权和精确目录后，首次建立必须先运行：
+
+```bash
+node scripts/manage-prompt-library.mjs init --dir '/用户明确指定的绝对路径'
+```
+
+然后把当前对话里已经确认的目标、提示词和参数填写进脚本返回的文件，不留下空壳。首次尚未生成时，把结果状态明确写成“等待生成”，不能把预期写成事实。
+
+用户实际生成、反馈结果并同意记录后，先运行：
+
+```bash
+node scripts/manage-prompt-library.mjs revision --dir '/用户明确指定的绝对路径'
+```
+
+然后只填写脚本返回的文件。旧版本记录只追加、不覆盖；不得自行创造另一套文件名或扫描父目录寻找其他资料库。
+
+写入后必须运行：
+
+```bash
+node scripts/manage-prompt-library.mjs check --dir '/用户明确指定的绝对路径'
+```
+
+并回读本轮改动的文件，确认核心目标、版本号、提示词和记录状态一致。检查失败时说明没有完成，不得把“准备保存”说成“已经保存”。
+
+旧项目缺少新版栏目时，在用户已经授权更新该精确目录的前提下运行：
+
+```bash
+node scripts/manage-prompt-library.mjs upgrade --dir '/用户明确指定的绝对路径'
+```
+
+这个动作只追加缺失栏目，不覆盖旧内容。升级后仍要运行 `check` 并由用户或助教填写新增的当前核心目标和对齐检查，脚本不替用户猜。
+
+推荐的用户可见结构：
+
+```text
+项目名/
+├── 目标.md
+├── 当前版本.md
+└── 生成记录/
+    ├── V001.md
+    └── V002.md
+```
+
+`目标.md` 只保存相对稳定的内容：
+
+```markdown
+# 目标
+
+## 使用方式
+## 当前核心目标
+## 想保留的音乐特征
+## 明确避免项
+## 当前参考及真正参考的维度
+```
+
+`当前版本.md` 保存当前正在验证的版本：
+
+```markdown
+# 当前版本
+
+## 版本号
+## 当前核心目标
+## 本版提示词
+## 建议起始参数
+## 本版只改了什么
+## 当前已经验证有效的部分
+## 等待验证的问题
+```
+
+每份生成记录保存：
+
+```markdown
+# V001
+
+## 当前核心目标
+## 本版提示词
+## 参数设置
+## 核心目标对齐检查
+## 本版只改了什么
+## 生成结果中的可见事实
+## 用户认为符合的部分
+## 用户认为偏离的部分
+## 下一版只改什么
+```
+
+只记录用户实际生成和反馈后的结果，不把模型预期写成实验结论。艺人名可以作为用户的检索线索，但真正可复用的是被验证过的音乐维度、表达方式和适用条件。
+
+### WorkBuddy 降级路径
+
+纯 Skill 在不同 WorkBuddy 环境中不一定能稳定调用脚本。无法运行脚本或无法写入时：
+
+1. 不声称已经建立资料库。
+2. 按 `目标.md`、`当前版本.md` 和 `生成记录/V001.md` 三个标题输出可复制内容。
+3. 告诉用户把这些内容保存到他刚才指定的项目文件夹。
+4. 后续仍可以在同一任务中继续版本迭代。
+
+只有实际检查到文件存在且内容一致时，才报告保存成功。
+
+## 当前官方能力边界
+
+Suno 的模型和界面会更新。需要说明当前字段、模型或功能时，优先核对官方帮助中心，不沿用旧课程中的固定结论。
+
+截至本参考更新时，官方资料已经说明：
+
+- 较新的模型能够理解更详细的自然语言 Style 描述，不再只有简短标签一种写法；
+- 可以通过 Reuse Prompt 修改 Style、歌词和标题后继续生成；
+- Creative Sliders 中的 Weirdness、Style Influence 和 Audio Influence 分别控制变化程度、贴近 Style 的程度和贴近上传音频的程度，但官方没有给所有任务统一的最佳数值；
+- Suno 也在提供基于用户使用习惯的个性化功能，但本地资料库仍用于保留用户自己的目标、判断依据和跨工具可迁移的实验记录。
+
+这些是平台能力，不代表某个具体词序一定产生固定结果。最终仍以用户当次模型和生成结果为准。
+
+官方资料：
+
+- https://help.suno.com/en/articles/5782849
+- https://help.suno.com/en/articles/2417409
+- https://help.suno.com/en/articles/6141377
+- https://help.suno.com/en/articles/11362561

package/scripts/manage-prompt-library.mjs

@@ -0,0 +1,257 @@
+#!/usr/bin/env node
+
+import { access, appendFile, mkdir, readFile, readdir, writeFile } from "node:fs/promises";
+import { isAbsolute, resolve, sep } from "node:path";
+
+const command = process.argv[2];
+const args = new Map();
+for (let index = 3; index < process.argv.length; index += 2) {
+  const key = process.argv[index];
+  const value = process.argv[index + 1];
+  if (!key?.startsWith("--") || value === undefined) {
+    throw new Error(`Invalid argument near: ${key ?? "(missing)"}`);
+  }
+  args.set(key.slice(2), value);
+}
+
+const requestedDir = args.get("dir");
+if (!requestedDir || !isAbsolute(requestedDir)) {
+  throw new Error("--dir must be an absolute path explicitly selected by the user");
+}
+
+const libraryDir = resolve(requestedDir);
+const skillDir = resolve(import.meta.dirname, "..");
+if (libraryDir === skillDir || libraryDir.startsWith(`${skillDir}${sep}`)) {
+  throw new Error("Prompt libraries must stay outside the Skill directory");
+}
+
+const goalPath = resolve(libraryDir, "目标.md");
+const currentPath = resolve(libraryDir, "当前版本.md");
+const recordsDir = resolve(libraryDir, "生成记录");
+
+const goalTemplate = `# 目标
+
+## 使用方式
+
+## 当前核心目标
+
+## 想保留的音乐特征
+
+## 明确避免项
+
+## 当前参考及真正参考的维度
+`;
+
+const currentTemplate = `# 当前版本
+
+## 版本号
+
+## 当前核心目标
+
+## 本版提示词
+
+## 建议起始参数
+
+## 本版只改了什么
+
+## 当前已经验证有效的部分
+
+## 等待验证的问题
+`;
+
+const recordTemplate = (version) => `# ${version}
+
+## 当前核心目标
+
+## 本版提示词
+
+## 参数设置
+
+## 核心目标对齐检查
+
+## 本版只改了什么
+
+## 生成结果中的可见事实
+
+## 用户认为符合的部分
+
+## 用户认为偏离的部分
+
+## 下一版只改什么
+`;
+
+const requiredHeadings = {
+  "目标.md": [
+    "## 使用方式",
+    "## 当前核心目标",
+    "## 想保留的音乐特征",
+    "## 明确避免项",
+    "## 当前参考及真正参考的维度",
+  ],
+  "当前版本.md": [
+    "## 版本号",
+    "## 当前核心目标",
+    "## 本版提示词",
+    "## 建议起始参数",
+    "## 本版只改了什么",
+    "## 当前已经验证有效的部分",
+    "## 等待验证的问题",
+  ],
+};
+
+async function exists(path) {
+  try {
+    await access(path);
+    return true;
+  } catch (error) {
+    if (error.code === "ENOENT") return false;
+    throw error;
+  }
+}
+
+async function writeIfMissing(path, content) {
+  try {
+    await writeFile(path, content, { encoding: "utf8", flag: "wx" });
+    return "created";
+  } catch (error) {
+    if (error.code === "EEXIST") return "kept";
+    throw error;
+  }
+}
+
+async function inspectHeadings(path, headings) {
+  if (!(await exists(path))) {
+    return { exists: false, missingHeadings: headings };
+  }
+  const content = await readFile(path, "utf8");
+  return {
+    exists: true,
+    missingHeadings: headings.filter((heading) => !content.includes(heading)),
+  };
+}
+
+async function appendMissingHeadings(path, headings) {
+  const inspection = await inspectHeadings(path, headings);
+  if (!inspection.exists) return inspection;
+  if (inspection.missingHeadings.length) {
+    const addition = inspection.missingHeadings
+      .map((heading) => `\n${heading}\n\n`)
+      .join("");
+    await appendFile(path, addition, "utf8");
+  }
+  return {
+    exists: true,
+    addedHeadings: inspection.missingHeadings,
+  };
+}
+
+async function init() {
+  await mkdir(recordsDir, { recursive: true });
+  process.stdout.write(`${JSON.stringify({
+    libraryDir,
+    files: {
+      "目标.md": await writeIfMissing(goalPath, goalTemplate),
+      "当前版本.md": await writeIfMissing(currentPath, currentTemplate),
+    },
+    recordsDir: "生成记录",
+  }, null, 2)}\n`);
+}
+
+async function nextVersion() {
+  const records = (await exists(recordsDir))
+    ? await readdir(recordsDir)
+    : [];
+  const numbers = records
+    .map((name) => /^V(\d{3})\.md$/.exec(name))
+    .filter(Boolean)
+    .map((match) => Number(match[1]));
+  return `V${String((numbers.length ? Math.max(...numbers) : 0) + 1).padStart(3, "0")}`;
+}
+
+async function revision() {
+  if (!(await exists(goalPath)) || !(await exists(currentPath))) {
+    throw new Error("Prompt library is missing 目标.md or 当前版本.md; run init first with user permission");
+  }
+  await mkdir(recordsDir, { recursive: true });
+  const version = args.get("version") ?? await nextVersion();
+  if (!/^V\d{3}$/.test(version)) {
+    throw new Error("--version must use V001 format");
+  }
+  const path = resolve(recordsDir, `${version}.md`);
+  await writeFile(path, recordTemplate(version), { encoding: "utf8", flag: "wx" });
+  process.stdout.write(`${JSON.stringify({
+    libraryDir,
+    version,
+    record: `生成记录/${version}.md`,
+  }, null, 2)}\n`);
+}
+
+async function check() {
+  const records = (await exists(recordsDir))
+    ? (await readdir(recordsDir)).filter((name) => /^V\d{3}\.md$/.test(name)).sort()
+    : [];
+  const goal = await inspectHeadings(goalPath, requiredHeadings["目标.md"]);
+  const current = await inspectHeadings(currentPath, requiredHeadings["当前版本.md"]);
+  const recordChecks = {};
+  for (const record of records) {
+    recordChecks[record] = await inspectHeadings(resolve(recordsDir, record), [
+      "## 当前核心目标",
+      "## 本版提示词",
+      "## 参数设置",
+      "## 核心目标对齐检查",
+      "## 本版只改了什么",
+      "## 生成结果中的可见事实",
+      "## 用户认为符合的部分",
+      "## 用户认为偏离的部分",
+      "## 下一版只改什么",
+    ]);
+  }
+  const valid = goal.exists
+    && current.exists
+    && goal.missingHeadings.length === 0
+    && current.missingHeadings.length === 0
+    && Object.values(recordChecks).every((item) => item.missingHeadings.length === 0);
+  process.stdout.write(`${JSON.stringify({
+    libraryDir,
+    valid,
+    goal,
+    current,
+    records,
+    recordChecks,
+  }, null, 2)}\n`);
+  if (!valid) process.exitCode = 1;
+}
+
+async function upgrade() {
+  if (!(await exists(goalPath)) || !(await exists(currentPath))) {
+    throw new Error("Prompt library is missing 目标.md or 当前版本.md; run init first with user permission");
+  }
+  const records = (await exists(recordsDir))
+    ? (await readdir(recordsDir)).filter((name) => /^V\d{3}\.md$/.test(name)).sort()
+    : [];
+  const upgraded = {
+    "目标.md": await appendMissingHeadings(goalPath, requiredHeadings["目标.md"]),
+    "当前版本.md": await appendMissingHeadings(currentPath, requiredHeadings["当前版本.md"]),
+    records: {},
+  };
+  for (const record of records) {
+    upgraded.records[record] = await appendMissingHeadings(resolve(recordsDir, record), [
+      "## 当前核心目标",
+      "## 本版提示词",
+      "## 参数设置",
+      "## 核心目标对齐检查",
+      "## 本版只改了什么",
+      "## 生成结果中的可见事实",
+      "## 用户认为符合的部分",
+      "## 用户认为偏离的部分",
+      "## 下一版只改什么",
+    ]);
+  }
+  process.stdout.write(`${JSON.stringify({ libraryDir, upgraded }, null, 2)}\n`);
+}
+
+if (command === "init") await init();
+else if (command === "revision") await revision();
+else if (command === "check") await check();
+else if (command === "upgrade") await upgrade();
+else throw new Error("Usage: manage-prompt-library.mjs <init|revision|check|upgrade> --dir /absolute/path [--version V001]");

package/scripts/search-knowledge.sh

@@ -16,6 +16,16 @@ fi
 
 script_dir=$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)
 skill_dir=$(cd -- "$script_dir/.." && pwd)
-knowledge_root=$(cd -- "$skill_dir/knowledge" && pwd)
+if [[ -d $skill_dir/knowledge ]]; then
+  knowledge_root=$(cd -- "$skill_dir/knowledge" && pwd)
+else
+  knowledge_root=$(cd -- "$skill_dir/../knowledge" && pwd)
+fi
+
+matches=$(rg -l -i --glob '*.md' -- "$pattern" "$knowledge_root" || true)
+if [[ -z $matches ]]; then
+  printf '未找到匹配内容\n'
+  exit 0
+fi
 
-rg -l -i --glob '*.md' -- "$pattern" "$knowledge_root" | sed -n "1,${limit}p"
+printf '%s\n' "$matches" | sed -n "1,${limit}p"

package/scripts/validate-project.mjs

@@ -0,0 +1,217 @@
+#!/usr/bin/env node
+
+import { createHash } from "node:crypto";
+import {
+  mkdtemp,
+  mkdir,
+  readFile,
+  readdir,
+  rm,
+  stat,
+  symlink,
+} from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, join, relative, resolve } from "node:path";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const failures = [];
+
+function check(condition, message) {
+  if (!condition) failures.push(message);
+}
+
+async function readJson(path) {
+  return JSON.parse(await readFile(path, "utf8"));
+}
+
+async function markdownFiles(directory) {
+  const files = [];
+  for (const entry of await readdir(directory, { withFileTypes: true })) {
+    const path = join(directory, entry.name);
+    if (entry.isDirectory()) files.push(...await markdownFiles(path));
+    else if (entry.name.endsWith(".md")) files.push(path);
+  }
+  return files;
+}
+
+async function validateManifest() {
+  const manifest = await readJson(join(root, "manifest.json"));
+  const knowledgeRoot = join(root, "knowledge");
+  const disk = await markdownFiles(knowledgeRoot);
+  const listed = new Map(manifest.files.map((item) => [item.path, item]));
+
+  check(manifest.skill === "rg", "manifest.skill 必须是 rg");
+  check(
+    manifest.knowledgeFiles === manifest.files.length,
+    "manifest.knowledgeFiles 与 files 数量不一致",
+  );
+  check(
+    disk.length === manifest.files.length,
+    `知识文件数量不一致：磁盘 ${disk.length}，manifest ${manifest.files.length}`,
+  );
+
+  for (const path of disk) {
+    const name = relative(knowledgeRoot, path);
+    const item = listed.get(name);
+    if (!item) {
+      failures.push(`manifest 缺少：${name}`);
+      continue;
+    }
+    const content = await readFile(path);
+    const digest = createHash("sha256").update(content).digest("hex");
+    check(item.bytes === content.length, `文件大小不一致：${name}`);
+    check(item.sha256 === digest, `文件哈希不一致：${name}`);
+  }
+}
+
+async function validateMarkdownLinks() {
+  const files = [
+    join(root, "SKILL.md"),
+    join(root, "README.md"),
+    ...await markdownFiles(join(root, "references")),
+  ];
+  for (const file of files) {
+    const content = await readFile(file, "utf8");
+    for (const match of content.matchAll(/\[[^\]]*]\(([^)]+)\)/g)) {
+      const target = match[1].split("#")[0];
+      if (!target || /^[a-z]+:/i.test(target)) continue;
+      const destination = resolve(dirname(file), target);
+      try {
+        await stat(destination);
+      } catch {
+        failures.push(
+          `Markdown 链接不存在：${relative(root, file)} -> ${target}`,
+        );
+      }
+    }
+  }
+}
+
+async function validateRegressions() {
+  const suite = await readJson(join(root, "tests", "logic-regressions.json"));
+  check(Array.isArray(suite.cases), "回归测试 cases 必须是数组");
+  const ids = new Set();
+  for (const item of suite.cases ?? []) {
+    check(typeof item.id === "string" && item.id.length > 0, "回归案例缺少 id");
+    check(!ids.has(item.id), `回归案例 id 重复：${item.id}`);
+    ids.add(item.id);
+    check(
+      typeof item.prompt === "string"
+      || typeof item.task === "string"
+      || Array.isArray(item.turns),
+      `回归案例缺少输入：${item.id}`,
+    );
+    check(
+      Array.isArray(item.expect) && item.expect.length > 0,
+      `回归案例缺少 expect：${item.id}`,
+    );
+    check(
+      Array.isArray(item.reject) && item.reject.length > 0,
+      `回归案例缺少 reject：${item.id}`,
+    );
+  }
+}
+
+function run(command, args, options = {}) {
+  return spawnSync(command, args, {
+    cwd: root,
+    encoding: "utf8",
+    ...options,
+  });
+}
+
+async function validateRuntime() {
+  for (const file of [
+    "bin/ruige-skill.mjs",
+    "scripts/manage-career-archive.mjs",
+    "scripts/manage-prompt-library.mjs",
+    "scripts/validate-project.mjs",
+  ]) {
+    const result = run(process.execPath, ["--check", file]);
+    check(result.status === 0, `语法检查失败：${file}\n${result.stderr}`);
+  }
+
+  const noHit = run("bash", [
+    "scripts/search-knowledge.sh",
+    "肯定不存在的检索词_RG_TEST_987654321",
+    "3",
+  ]);
+  check(noHit.status === 0, "知识检索无命中时不应返回脚本错误");
+  check(noHit.stdout.includes("未找到匹配内容"), "知识检索无命中缺少明确提示");
+
+  const sandbox = await mkdtemp(join(tmpdir(), "ruige-skill-test-"));
+  try {
+    const env = { ...process.env, RUIGE_SKILL_HOME: sandbox };
+    const codexSkills = join(sandbox, ".codex", "skills");
+    await mkdir(codexSkills, { recursive: true });
+    await symlink(root, join(codexSkills, "rg.backup-test"), "dir");
+    const install = run(
+      process.execPath,
+      ["bin/ruige-skill.mjs", "install", "--agent", "codex"],
+      { env },
+    );
+    check(install.status === 0, `安装沙箱失败：${install.stderr}`);
+    check(
+      install.stdout.includes("已移出 1 个"),
+      "安装器没有移出可能被重复加载的旧 Skill 入口",
+    );
+
+    const statusResult = run(
+      process.execPath,
+      ["bin/ruige-skill.mjs", "status", "--agent", "codex"],
+      { env },
+    );
+    check(statusResult.status === 0, `状态检查失败：${statusResult.stderr}`);
+    check(statusResult.stdout.includes("正常，v"), "状态没有报告有效版本");
+    check(statusResult.stdout.includes("codex: 已连接"), "状态没有验证正确桥接");
+
+    const codexBridge = join(codexSkills, "rg");
+    const wrongTarget = join(sandbox, "wrong-skill");
+    await mkdir(wrongTarget, { recursive: true });
+    await rm(codexBridge);
+    await symlink(wrongTarget, codexBridge, "dir");
+    const wrongStatus = run(
+      process.execPath,
+      ["bin/ruige-skill.mjs", "status", "--agent", "codex"],
+      { env },
+    );
+    check(
+      wrongStatus.stdout.includes("codex: 错误链接"),
+      "状态检查没有识别指向错误位置的 Skill 链接",
+    );
+
+    const promptLibrary = join(sandbox, "prompt-library");
+    const initLibrary = run(
+      process.execPath,
+      ["scripts/manage-prompt-library.mjs", "init", "--dir", promptLibrary],
+    );
+    check(initLibrary.status === 0, `提示词资料库初始化失败：${initLibrary.stderr}`);
+    const addRevision = run(
+      process.execPath,
+      ["scripts/manage-prompt-library.mjs", "revision", "--dir", promptLibrary],
+    );
+    check(addRevision.status === 0, `提示词版本创建失败：${addRevision.stderr}`);
+    const checkLibrary = run(
+      process.execPath,
+      ["scripts/manage-prompt-library.mjs", "check", "--dir", promptLibrary],
+    );
+    check(checkLibrary.status === 0, `提示词资料库检查失败：${checkLibrary.stderr}`);
+    check(checkLibrary.stdout.includes("V001.md"), "提示词资料库没有保留第一版记录");
+  } finally {
+    await rm(sandbox, { recursive: true, force: true });
+  }
+}
+
+await validateManifest();
+await validateMarkdownLinks();
+await validateRegressions();
+await validateRuntime();
+
+if (failures.length) {
+  for (const failure of failures) console.error(`✗ ${failure}`);
+  process.exitCode = 1;
+} else {
+  console.error("✓ 项目结构、知识清单、引用、回归定义和安装沙箱验证通过");
+}