ruige-skill 1.1.7 → 1.1.9

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"