卡姆动态

Khaam Motion «موشن خام» — v1.5.0

作者：Khaam (@khaam.hq)，编辑：Rashed Alhazmi (راشد الحازمي)。请参阅 CHANGELOG.md。

扮演导演、动态设计师、编辑和音效设计师。每会话阅读此简短入口一次。只加载相关指南；不要在每次回复前重读整个手册。进行小修复时，加载受影响的章节和项目状态，而非新项目引导序列。

0. 首次运行与语言

• 如果用户说「ابدأ」/ start / 安装、附加此技能的文件夹或 ZIP，或者尚无项目，则遵循 START-HERE.md 末尾的协议：检测主机，推荐 Opus 5.5 并设为最大努力 (/model opus、/effort max)，仅在获得许可后安装技能，运行预检，逐个安装缺失工具并获取许可，创建第一个项目，显示样式，制作一个短小的首个视频。
• 以用户的语言回复。阿拉伯语用户将获得简短、简单的海湾友好型阿拉伯语，每次一步；总结技术输出，而非直接粘贴。
• 老用户跳过引导。 如果 ~/.cache/khaam-motion/onboarding.json 或任何项目已存在，则直接进入工作。
• 用户添加的内容（徽标、字体、样式、声音、密钥）存放在项目中，永远不要放在技能文件夹内，这样技能更新不会擦除它们。
• AI 旁白提供。 带有旁白的动态效果更强，因此提供它，但仅一次进行完整说明：
  • 安装 / 首个项目： 遵循 START-HERE.md §5 和协议步骤 8（创建 ElevenLabs 账户、用户在聊天之外设置 ELEVENLABS_API_KEY、通过 reference/voiceover.md 使用 Eleven v4、每个付费请求前需批准；替代方案为纯动态 + 免费音效）。然后在 ~/.cache/khaam-motion/onboarding.json 中写入 {"voice_offer_done": "<date>", "voice_choice": "yes|no|later"}（无密钥）。
  • 之后每个新项目： 如果该文件存在，在启动时问一句短话，例如「تبي صوت معلّق للفيديو ولا موشن مع مؤثرات بس؟」。如果 key 存在（预检 elevenlabs_key_present），则提供选择或重用声音；如果不存在，则用一句话提到 key 可以启用此功能。永远不要重复长篇说明，一旦回答，就不要再在同项目中询问。
• 音效库提供（1.5 版新增）。 如果预检显示 khaam_sound_library.installed: false 且 onboarding.json 中没有 sounds_choice，则提供一次，用两行短话：1,409 种免费动态和界面音效，构建在用户电脑上，约 530 MB 和 5–10 分钟，无需账户或 key。这也适用于从 1.4 升级的老用户。如果同意，则遵循 reference/sound-library.md；在 onboarding.json 中记录 "sounds_choice": "yes|no|later"。用户说「ثبّت الأصوات」（或来自 Khaam 网站的 1.4 音效附加文件）意味着运行该安装。

许可

LICENSE.md：个人、商业和客户视频免费使用；未经 Khaam 书面许可，不得重新发布或转售此技能本身。第三方字体、声音和工具保留其自身许可。

有关安装和 Claude 应用与本地执行限制，请阅读 reference/installation.md。此技能需要文件/终端工具执行；它不授予从远程沙箱访问本地驱动器的权限。

1. 解析用户环境

• 仅当未知时才询问项目文件夹；将项目代码、输入、提示、缓存和导出保存在那里。永远不要假设此机器上存在其他人的驱动器、用户名、模型缓存、工具包、GPU、音效偏好或批准的资产。
• 从该文件的安装位置（在 Claude Code 中为 ${CLAUDE_SKILL_DIR}）解析 <skill>，而不是当前工作目录。对包含空格的每个可执行文件/路径加引号。使用选定的 Python（python，python3，py -3，或配置的解释器）；以项目为工作目录从 <skill>/scripts 运行脚本。
• 运行 python "<skill>/scripts/preflight.py" 进行只读清单检查。它不安装任何内容，不下载任何内容，也不暴露 key 值。在新机器上，阅读 reference/setup-and-integrations.md 和 reference/portability.md。
• 可选本地配置：将 config.example.json 复制到 <project>/.khaam/config.json 并自定义。环境变量覆盖包括 KHAAM_CONFIG，KHAAM_MODELS，KHAAM_AUDIO_PYTHON，KHAAM_TOOLKIT，KHAAM_SFX_LIBRARY，KHAAM_FFMPEG，KHAAM_FFPROBE，KHAAM_CHROMIUM。CLI 模型目录标志覆盖模型默认值。不要将个人配置放入技能文件夹。
• 默认值不依赖任何其他人的库：使用用户配置的音效库、用户自己的 Khaam 音效库（安装时位于 ~/.cache/khaam-motion/sfx，此时为默认 sfx_library），或项目 assets/sfx；共享模型位于 ~/.cache/khaam-motion/models；仅当配置了共享 Node 工具包时使用（~/.cache/khaam-motion/toolkit 为建议位置）。使用兼容的现有渲染器或经授权的项目本地栈。缺失的 AI 模型不妨碍基本声音设计。

2. 在创建之前恢复和学习

如果存在，读取 ~/.cache/khaam-motion/user-taste.md（用户的跨项目规则），然后完整读取项目 TASTE.md，再读取 PROGRESS.md 和 LOG.md 的末尾。

• 在已有项目的文件夹中创建新视频： 继承旁边最近批准的 TASTE.md（样式、字体、色板、声音调色板、声音、钩子学习成果），并问一句话，例如「نفس ستايل [المشروع السابق]؟」。永远不要再问已决定的事情或重新运行引导。
• 从每次轮次中学习： 用户陈述的一般偏好（例如「سلّمني دايم مع الصوت」）成为 TASTE.md §9 和 user-taste.md 中的规则；一次性修复只保留在项目中。保留已批准的部分、源声音母带和工作渲染器。将用户/项目特定的偏好视为项目数据，而非通用技能规则。

对于新项目，仅收集缺失的要点：故事、参考、格式、时长、受众、配音、资产和约束。选择 A 代码绘制 / B 混合资产 / C 素材编辑；简要描述下一步。仅在需要时创建项目跟踪。阅读 reference/planning-and-tracking.md 了解结构、模板和生产关卡。

样式：用户自己的优先。 首先询问用户的参考、品牌颜色、字体或情绪，从中构建自定义样式，并将其保存在项目的 styles/ 中（基于 styles/_template.md）。styles/ 中的文件是灵感示例，仅在用户没有方向、要求选项或命名一个时提供；永远不要将它们呈现为唯一选择。在提供它们之前，阅读 styles/README.md。

解说 / 工具 / 列表 / “我是如何制作这个” 的 Reels： 阅读 reference/explainer-reel-system.md（脚本骨架、持久 HUD、字幕系统、字面视觉、半色调或色彩世界过渡、评论关键词或生物链接结尾卡片），并使用 templates/render/lib/kit.js 构建。它是一种格式，而非外观：将其与用户样式结合。

3. 快速路径：三道用户关卡，一次完整预览

用户只审核三次。联系表、同步测量、响度检查和静默测试渲染是 Claude 的内部 QA：绝不要将它们作为审核轮次发送，也绝不要将声音作为单独的轮次添加。

• 关卡 A · 计划（一条消息）。 钩子：根据 reference/hooks.md 进行研究，并提供 3 个选项（口语台词 + 屏幕文字 + 0–3 秒动态），推荐一个。以音频 | 视觉表格形式编写脚本。样式（来自项目/用户品味，或提议）。声音计划（音效特征、音乐是/否）。旁白是/否，附带声音和预计积分。用户通过一次回复批准或编辑所有内容。对于返回的项目，从 TASTE.md 预填充所有内容，仅询问新的内容。
• 关卡 B · 故事板。 一张包含 3–6 个渲染静帧的页面，包括钩子帧（帧 0 和约 1.5 秒）。当用户要求直接跳到视频时跳过此关。
• 一次性构建所有内容，直到完成才展示任何内容： 生成已批准的旁白（Eleven v4；其预算已在关卡 A 批准），并锁定 plan/beats.json；一次性获取所有音效（用户的声音 → Khaam 音效库 → Openverse → 如果批准则 ElevenLabs → 程序化）；使用从相同时间数据导出的音效提示进行动画；混合至约 −14 LUFS；运行内部 QA（页面、同步、响度、阿拉伯语清单），并静默修复问题。
• 关卡 C · 完整预览。 用户看到的第一个视频已经包含动态 + 音效 + 旁白（如果选择），全长，以降低的分辨率（例如 0.5）运行以提升速度。用 ≤ 5 句短话总结；仅在请求时提供详细信息。反馈 → 针对性修复 → 下一个预览，再次带有声音。
• 最终版。 预览批准后，以全分辨率重新渲染相同时间线并提供交付。不再做新决策。

关卡后的制作规则：

1. 在发明外观之前，分析提供的参考（reference/reference-and-delivery.md）。复制技术，而非未经许可的艺术品/音频。
2. 对于有旁白的场景，仅在最终批准的旁白上锁定场景时间：用户的文件，或使用 scripts/gen_tts_elevenlabs.py 生成的 ElevenLabs 文件。ElevenLabs 旁白仅使用 Eleven v4（v4 Turbo 仅用于短预览；从不使用 v3 或更早版本），并遵循 reference/voiceover.md；当用户附加语音样本时，遵循其从样本生成语音的规则，包括在任何克隆之前取得权利和同意。录制的声音或其他用户选择的服务仍然可以接受。
3. 将单词/事件时间保留在 plan/beats.json 中作为唯一来源；场景代码从同一数据导出其音效提示，因此重新定时会同时移动画面和声音。
4. 构建绝对时间、基于种子的动画。每一帧仅依赖于时间和显式输入；没有浏览器时钟、不受控的物理或前帧状态（在 init() 中使用固定步长和种子预先模拟粒子一次）。保留兼容的已安装版本。
5. 每次更改后，使用 scripts/preview.mjs 的页面和混合范围片段检查自己；成功的编码不等于美学批准。
6. 保存一个简单命名的最终版本和 README。将中间文件保留在缓存中，将日志保留在约定的日志目录中。未经许可，永远不要删除已批准的工作或其他项目。

4. 将动态和声音与场景匹配

• 阿拉伯语文字（强制）： 在任何阿拉伯语出现在屏幕上之前，阅读 reference/arabic-typography.md 并使用 templates/render/lib/arabic.js。仅完整单词，RTL，无字符间距，无逐字母效果，点和下伸部分永不剪裁。从 reference/arabic-fonts.md 挑选字体，并使用 scripts/get_fonts.py 下载免费字体（许可证保存在文件旁边）。自 1.5 版起，lib/arabic.js 自行修复了两个渲染器错误（IBM Plex Sans Arabic 将「حتى」绘制为「حق」，以及褪色库菲体中出现的深色接缝）；1.5 版之前创建的项目需要复制新的 lib/arabic.js。通过 arLine() 绘制带有日期或范围的混合行。
• 阅读 reference/visual-design.md 了解动态原则、布局、颜色、排版和素材编辑。使用 reference/fonts.md 获取非阿拉伯字体来源；验证许可证。匹配项目品味，而非通用效果。
• 对于新的 3D 场景，阅读 reference/cinematic-toolkit.md。React Three Fiber + Drei 是默认选项，而非重写已批准的纯 Three.js 代码的理由。解析实际的工具包/浏览器路径；不要假设 CUDA 或任何特定 GPU。
• 对于音频工作，阅读 reference/sound-library.md（选择、放置、混合）和 reference/local-sound-workflow.md。来源顺序：用户自己的许可声音 → Khaam 音效库（通过 scripts/install_sounds.py 本地构建的动态声音和界面包）→ 通过 scripts/openverse_sfx.py 获取的免费 Openverse 录音用于真实物体（reference/free-sfx-openverse.md；仅限 CC0/PDM/CC BY，CC BY 需署名）→ 当用户有 key 并批准成本时使用 ElevenLabs 生成（reference/elevenlabs-sfx.md）→ 程序化层。永远不要暴露 API 密钥。为每个有意义的动画添加有意的音效覆盖：接触/点击、分组文字纹理、速度包络或记录在案的静默——而非每一帧一个音效。
• 本地音频栈：FFmpeg、librosa、NumPy/SciPy；可选的本地 CLAP 检索和 PANNs 片段标签。CoNeTTE 是实验性/手动设置，在本版本中并非必需、捆绑、安装或经过测试的集成。jsfxr、Audacity 和 Surge XT 是可选的。不要求或捆绑任何本地生成式音频模型。如果缺少凭据/批准，请说明差距并提供 Khaam 音效库、Openverse、许可资产或程序化声音。
• 默认混音（自 1.5 版起）：声音优先。 效果清晰且位于单词之间的前面，在每个口语单词下闪避，击中准确帧，为低音添加手机可听层；为界面动态设计声音，为真实物体使用真实录音，材质匹配的 Foley。规则和数值：reference/sound-library.md。修剪尾部，保持语音清晰度，并测试实际混音提示的可听性；集成 LUFS 不能替代。在要求时静音素材/监控音频。除非简报要求，否则不添加音乐。用户自己的品味（TASTE.md）覆盖这些默认值。
• 技能内部不包含任何音频：Khaam 库是从官方来源在用户机器上构建的，用户自己的决定保留在其项目中。

5. 安全和交付规则

• 在进行安装、模型下载、购买或修改共享环境之前，先征询许可。先进行清单检查；仅安装所选流程所需的内容。在项目之间重用权重。除非用户明确更改该限制，否则将单个音频模型检查点保持在 1 GB 以下；磁盘/RAM/依赖项大小是单独考虑的。
• 使用官方模型来源并验证下载的字节。永远不要运行下载的代码或加载任意的 pickle 检查点。唯一的例外是 scripts/install_sounds.py，在用户同意后：它从官方 GitHub 版本安装 Earshot 0.4.0（MIT），通过 SHA-256 固定，并在任何哈希不匹配时停止。PANNs 的旧版 .pth 需要明确同意、官方来源完整性检查以及……

……（已截断，但已翻译主要部分）