narrative-lion

Narrative Lion

所有 API 操作都使用 ${CLAUDE_PLUGIN_ROOT}/scripts/nl.py 中的 CLI。通过 Bash 运行：

python3 ${CLAUDE_PLUGIN_ROOT}/scripts/nl.py <command> [args...] [--json]

身份验证

export NLK_API_KEY=nlk_xxxxxxxx

在 https://narrativelion.com/settings/api-keys 创建一个（需要 Pro 计划）。

所有 API 调用都使用 Authorization: Bearer $NLK_API_KEY 标头。

CLI 参考

通用

命令	描述
nl.py search <query> [--collection ID]	语义搜索
nl.py fts <query> [--collection ID]	全文关键词搜索
nl.py collections	列出所有集合（含 ID 的两级文件夹树）
nl.py notes list [--collection ID] [--type T] [--uncategorized] [--starred]	浏览笔记
nl.py notes get <noteId>	笔记详情
nl.py transcript <noteId>	视频笔记文字稿（带时间戳的片段；使用 --json 获取原始片段）
nl.py notes create --type T --content C [--file path] [--skip-ai]	创建笔记
nl.py submit <video-url> [--wait] [--timeout SECONDS]	根据 YouTube/TikTok URL 创建视频笔记（消耗额度；具备幂等性）
nl.py job <jobId>	检查已提交任务的状态（完成后解析出笔记 ID）
nl.py jobs	列出待处理任务
nl.py export <noteId> [noteId2 ...]	导出为 Markdown 压缩包
nl.py usage	额度用量

电影导演

命令	描述
nl.py director <concept> [--type T] [--duration N] [--aspect R] [--style S]	根据概念生成分镜（消耗 1-2 个额度）
nl.py director-persist <threadId> --storyboard <md> --instruction <text>	将分镜保存为 filmwork 笔记（不消耗 LLM 额度）

Filmwork

命令	描述
nl.py overview <noteId>	项目概览：状态计数 + 所有镜头
nl.py shot <noteId> <label>	镜头详情：预检、素材、生成批次、提示词
nl.py shot-create <noteId> --label L [--duration N] [--after LABEL] [--status S]	在现有 filmwork 中创建镜头（0 点数）
nl.py shot-delete <shotId>	删除镜头（软删除，自动记录决策）
nl.py preflight <noteId> <label>	仅执行预检
nl.py upload <shotId> <assetType> <file> [--label L] [--method M --model M --prompt P --user-note N --parent JSON]	上传素材（处理 3 步流程，可选记录来源信息）
nl.py upload-roll <shotId> <file> [--seed N --model M --prompt-version N]	上传生成批次视频
nl.py shot-update <shotId> [--status S] [--blocker JSON] [--prompts JSON] [--dialogue JSON] [--direction JSON] [--model-config JSON] [--relations JSON] [--duration N]	更新镜头状态和/或字段
nl.py score <rollId> --face N --expr N --motion N --stability N --style N	为生成批次评分（自动计算加权总分）
nl.py verdict <rollId> <approved|rejected>	设置生成批次的审核结果
nl.py golden-roll <rollId>	设置黄金生成批次
nl.py decision <noteId> [--shot ID] --action A --reason R --outcome O	记录决策
nl.py insight <noteId> --category C --tags T1,T2 --title T --detail D [--source-shots JSON]	记录洞察
nl.py decisions <noteId> [--shot ID] [--limit N] [--offset N]	列出决策
nl.py insights [noteId] [--category C] [--tag T] [--limit N] [--offset N]	列出洞察（未指定 noteId 时跨笔记查询）
nl.py prompt <noteId> <shotLabel> [--version N]	列出提示词版本，或显示指定版本的完整提示词
nl.py prompt-diff <noteId> <shotLabel> --from N --to M	对比两个提示词版本的统一差异
nl.py roll-diff <rollId-A> <rollId-B>	对比两个生成批次：元数据、提示词、输入、评分
nl.py provenance <assetId>	查询素材的制作方式
nl.py lineage <assetId> [--depth N]	查询完整的溯源 DAG（显示 parent→child 方向）
nl.py roll-snapshot <rollId>	查看用于生成某个生成批次的素材版本
nl.py roll-context <rollId>	单次生成批次调试：提示词、输入、来源信息
nl.py set-provenance <assetId> --method M [--model M] [--prompt P] [--parent JSON ...]	事后设置/更新来源信息
nl.py download <assetId> <output_path>	将单个素材下载到本地文件
nl.py download-shot <noteId> <label> [--dir D] [--all]	下载镜头的黄金素材（--all 表示下载所有版本）

所有命令都支持使用 --json 输出原始 JSON。

注意： upload 和 upload-roll 接受的是镜头 UUID（即 id 字段），而不是标签。通过 nl.py shot <noteId> <label> 获取 UUID。

最佳实践

搜索

search 是语义搜索，即使标题不匹配也能找到结果。 fts 是精确关键词匹配。两者都接受 --collection。

集合

两级文件夹树。使用 collections 列出所有文件夹并获取其 ID，然后使用 notes list --collection ID 将范围限定到指定集合。 notes list --uncategorized 会返回不属于任何集合的笔记。

提交（视频 URL -> 笔记）

submit 会运行完整的视频转笔记流程（转录 + AI 笔记）。需要 API 密钥具备 jobs:submit 权限范围；每个新视频都会消耗点数。

• 幂等：如果笔记已存在（即使已软删除），也会返回现有笔记 ID，且不收取任何费用，因此可以安全地重新运行。
• 批量处理模式：先提交所有 URL（速度快，不使用 --wait），然后运行 nl.py jobs 轮询，直到结果为空，再通过 nl.py job <jobId> 或 notes list 获取 ID。
• 单个 URL：使用 --wait 阻塞等待笔记就绪（每 5 秒轮询一次，默认超时为 600 秒）。
• 速率限制：每个账户每分钟最多提交 10 次。

聊天 / SSE

电影导演笔记

每次调用 director 需花费 1–2 个积分。

会话管理：新对话时省略 --thread，继续对话时传入 --thread <id>。

完整文档： https://narrativelion.com/docs/film-director

短视频教练

根据用户的笔记库生成可直接投入制作的短视频脚本（TikTok / Reels / Shorts）。AI 会检索相关笔记，生成包含时间安排的逐镜头脚本，然后为草稿添加“教练笔记”，并引用确切的来源句子。

生成（1–2 个积分）：

curl -N https://narrativelion.com/api/chat/stream \
  -H "Authorization: Bearer $NLK_API_KEY" \
  -H "Content-Type: application/json" \
  -H "User-Agent: NLSkill/1.0" \
  -d '{
    "threadId": "'$(python3 -c 'import uuid; print(uuid.uuid4())')'",
    "actionId": "'$(python3 -c 'import uuid; print(uuid.uuid4())')'",
    "event": {
      "type": "user_text",
      "payload": {
        "text": "Generate a reel script",
        "activeTool": "reel_coach",
        "reelCoachTopic": "Topic or creative brief",
        "reelCoachTargetDurationSec": 30,
        "reelCoachPinnedNoteIds": ["note-id-1"],
        "reelCoachAutoRetrieve": true
      }
    }
  }'

载荷字段：

• reelCoachTopic（字符串）— 主题 / 简介，最多 2000 个字符。若省略，则使用 text。
• reelCoachTargetDurationSec（数字）— 目标时长，最长 120 秒，默认值为 30。
• reelCoachPinnedNoteIds（字符串数组）— 始终包含的笔记 ID（最多 20 个）。
• reelCoachAutoRetrieve（布尔值）— 自动检索相关笔记，默认值为 true。

SSE 流会先发出 token 事件，然后发出包含以下产物的 complete 事件：

• reelCoachSetup — 解析后的设置（可传回以进行优化 / 持久化）。
• reelCoachAnnotations — 教练笔记：{ draftExcerpt, rationale, confidence, references[] }。
• reelCoachStats — { totalBreakdownCount, usedSourceCount, validatedQuoteCount }。

finalMessage 是一份 JSON 草稿：

{
  "shots": [
    { "title": "Hook", "durationSec": 5, "script": "Spoken text..." },
    { "title": "Core insight", "durationSec": 10, "script": "..." }
  ],
  "coachOverview": "Strategy summary...",
  "sourceRelevance": [{ "noteTitle": "...", "relevanceScore": 0.9 }]
}

持久化为 Filmwork 项目（0 个积分）：

curl -X POST https://narrativelion.com/api/filmwork/director/persist \
  -H "Authorization: Bearer $NLK_API_KEY" \
  -H "Content-Type: application/json" \
  -H "User-Agent: NLSkill/1.0" \
  -d '{
    "shots": [{"title":"Hook","durationSec":5,"script":"..."}],
    "setup": {"topic":"...","targetDurationSec":30,"pinnedNoteIds":[],"autoRetrieve":true},
    "coachOverview": "..."
  }'

返回 { noteId, title }。持久化后，通过 nl.py overview / nl.py shot 管理项目。

优化（可选，每次 1 个积分）：

• 获取建议：使用 { draft, setup } 调用 POST /api/filmwork/coach/refine-suggestions → { suggestions: [{ label, prompt }] }
• 修订：使用 { currentDraft, setup, refinementPrompt, pinnedNoteIds? } 调用 POST /api/filmwork/coach/refine（SSE）

完整文档： https://narrativelion.com/docs/reel-coach

播客

播客笔记将 IR JSON 存储在 metadata 中。内容是 IR，而非 Markdown。

创建（0 点数）：

python3 ${CLAUDE_PLUGIN_ROOT}/scripts/nl.py notes create \
  --type podcast --skip-ai --content '<IR JSON>'

最简 IR 结构：

{
  "speakers": [
    {
      "id": "speaker_1",
      "name": "Eva",
      "role": "host",
      "gender": "female",
      "personality": "Professional, warm"
    }
  ],
  "segments": [
    {
      "id": "seg_ax",
      "speakerId": "speaker_1",
      "script": "[confident] Welcome to the show.",
      "pauseAfterMs": 300
    },
    {
      "id": "seg_bq",
      "speakerId": "speaker_1",
      "script": "Thanks for listening.",
      "pauseAfterMs": 0
    }
  ],
  "globalSettings": {
    "modelId": "eleven_v3",
    "outputFormat": "mp3_44100_128",
    "language": "en"
  }
}

IR 规则：

• speakers[].id：使用 speaker_1、speaker_2 等。
• segments[].id：seg_ + 2 个随机小写字母（例如 seg_ax、seg_bq）。必须唯一。
• segments[].speakerId：必须引用某个 speakers[].id。
• script：可选的 [tag] 前缀，用于标注语音指示——[whispering]、[excited]、[confident]、[pause]、[laughs]。使用 eleven_v3 时，用 ... 表示自然停顿。
• pauseAfterMs：必填。普通停顿为 200–500，主题转换为 500–800。
• 不要包含 audio、audioHistory 或 audioUnsynced——这些由系统管理。
• voiceId 是 speakers 中的可选字段。若省略，可通过 Studio UI 分配，或从预设目录中指定。
• 对于双人播客，添加第二位说话者，并设置 "role": "cohost"。

预设语音目录（无需自定义 ElevenLabs 密钥）：

女性：Rachel（21m00Tcm4TlvDq8ikWAM），平静/善于分析/温暖；Sarah（EXAVITQu4vr4xnSDxMaL），温暖/深思；Alice（Xb7hH8MSUJpSbSDYk0k2），兴奋/热情；Matilda（XrExE9yKIg1WjnnlVkGX），温暖/善于反思；Lily（pFZP5JQG7iQjIQuC4Bku），紧张/严肃；Emily（LcfcDJNUP1GQjkzn1xUU），平静/善于反思。

男性：Brian（nPczCjzI2devNBz1zQrb），平静/善于分析/深思；Daniel（onwK4e9ZLuTAKqWW03F9），严肃/深思；Chris（iP95p4xoKVk53GoZ742B），好奇/俏皮/随意；Charlie（IKne3meq5aSn9XLyUdCD），俏皮/随意；Bill（pqHfZKP75CvOlQylNhV4），热情/严肃；Josh（TxGEqnHWrfWFTfGW9XjX），兴奋/热情。

生成 TTS（需要 podcast 权限范围，会消耗点数）：

mutation {
  generateSegmentAudio(noteId: "...", segmentId: "seg_ax") {
    segmentId audioUrl durationMs
  }
}

AI 脚本编辑（1 点数）： 使用 { "noteId": "...", "prompt": "Make it more conversational" } 调用 POST /api/podcast/edit。添加 "segmentId": "seg_ax"，即可将范围限定为一个片段。响应为 { changes, summary }。不会自动应用——调用 updateNote(metadata: updatedIR) 以保存更改。

更新 IR：

mutation {
  updateNote(noteId: "...", metadata: "<stringified IR JSON>") { id updatedAt }
}

每次调用 updateNote(metadata: ...) 时，都会根据 IR 自动生成 noteMd。

导出音频：

mutation {
  exportPodcast(noteId: "...", format: "mp3", paddingMs: 200) {
    url durationMs
  }
}

format："mp3"（默认）会将所有片段合并为一个文件，并在片段间加入静音间隔；"zip" 会为每个片段生成一个 MP3，不含间隔。paddingMs（0-10000）会在每个片段后添加额外静音（仅适用于 mp3）。使用 GET /api/audio/<noteId>/export 下载。速度调整仅限 UI 使用（无法通过 API 使用）。

完整文档： https://narrativelion.com/docs/podcast

---

影视制作

创建项目

路径	适用场景	点数
直接创建（推荐）	Agent 直接管理镜头	0 点数
Film Director	已有概念，需要 AI 生成分镜脚本	1-2 点数
Reel Coach	根据笔记生成短视频脚本	1-2 点数

直接创建（0 点数）：

# 1. Create empty filmwork note
python3 ${CLAUDE_PLUGIN_ROOT}/scripts/nl.py notes create --type filmwork --skip-ai --content '# Project Title'

# 2. Add shots one by one
python3 ${CLAUDE_PLUGIN_ROOT}/scripts/nl.py shot-create <noteId> --label 01A --duration 3
python3 ${CLAUDE_PLUGIN_ROOT}/scripts/nl.py shot-create <noteId> --label 01B --duration 5
# --after is required once the note has any shot (first shot omits it):
python3 ${CLAUDE_PLUGIN_ROOT}/scripts/nl.py shot-create <noteId> --after 01A --duration 2

# 3. Set direction, prompts, etc. via shot-update
python3 ${CLAUDE_PLUGIN_ROOT}/scripts/nl.py shot-update <shotUUID> --direction '{"framing":"...","camera":"..."}' --duration 3

Film Director（1-2 点数）：

python3 ${CLAUDE_PLUGIN_ROOT}/scripts/nl.py director "concept description" --type animate --duration 30 --aspect 16:9
python3 ${CLAUDE_PLUGIN_ROOT}/scripts/nl.py director-persist <threadId> --storyboard <md> --instruction "concept" --type animate --duration 30 --aspect 16:9

Reel Coach（1-2 点数）： 使用 curl（没有 CLI 封装）。请参阅上文的 Reel Coach 部分。

标签必须符合 **01A** (Ns) — Title 格式。格式无效时会返回 INVALID_STORYBOARD_FORMAT。

注意事项

• shot-create --after：第一个镜头可选；笔记中已有镜头后则必填（否则会提示 afterLabel is required）。
• overview --json：shotId 字段是标签，而非 UUID——使用 nl.py shot <noteId> <label> 获取 UUID。
• --dialogue 是 JSON 数组，而非字符串：[{"speaker":"...","text":"...","type":"dialogue"|"os"|"sfx_cue","emotion"?:"..."}]。
• 能够渲染的 --direction 键：framing、camera、blocking、keyPose、editTiming、lighting、mood、compositeNote、notes。

Agent 暂停

shot 输出会用 [HOLD] 标记素材/拍摄条目。如果标有 [HOLD]，请跳过该条目。

扫描项目状态

python3 ${CLAUDE_PLUGIN_ROOT}/scripts/nl.py overview <noteId>

提供状态计数和逐镜头摘要（素材、拍摄条目、最佳分数、预检）。查看特定镜头的详细信息：

python3 ${CLAUDE_PLUGIN_ROOT}/scripts/nl.py shot <noteId> <label>

同步到本地工作室

将黄金资产下载到本地工作室目录：

python3 ${CLAUDE_PLUGIN_ROOT}/scripts/nl.py download-shot <noteId> <label> --dir studio/scene/season01/ep01/final/<label>_<scene>/

工作室目录约定：studio/scene/season01/ep01/final/{label}_{scene_name}/

文件命名：{label}_FINAL_start_frame.png、{label}_FINAL_end_frame.png、{label}_SFX_{name}.mp3 等。

开始处理镜头前

务必先检查现有知识：

python3 ${CLAUDE_PLUGIN_ROOT}/scripts/nl.py decisions <noteId> --shot <shotUUID>
python3 ${CLAUDE_PLUGIN_ROOT}/scripts/nl.py insights <noteId>

花 5 秒阅读，可以避免花 5 分钟重复过去的错误。

编写或更新提示词前

编写或修改视频提示词前，生成一个子 Agent（通过 Agent 工具）来审查相关见解。这样可以避免将原始见解数据加载到主上下文中。

子 Agent 指令：

1. 运行 nl.py insights --category video --json（跨笔记；或添加 <noteId>，将范围限定为单个项目）
2. 对于图像生成，改用 --category image
3. 阅读所有返回的见解
4. 返回与当前镜头内容（镜头运动、角色动作、场景类型）相关的简短项目符号列表
5. 如果没有相关见解，返回“No relevant prompt insights found”

已知主题时，使用 --tag 缩小结果范围（例如 --tag motion-direction、--tag start-end-pair）。

制作循环

Prepare → Preflight → Generate → Review → Act on verdict
                                    ↑               |
                                    └───────────────┘

准备

任何资产策略变更（交换起始帧↔结束帧、替换帧、重新生成、改变方法）= 继续操作前先记录一项 strategy_change 决策。

1. 上传参考资产并注明来源：

   python3 ${CLAUDE_PLUGIN_ROOT}/scripts/nl.py upload <shotUUID> start_frame /path/to/frame.png \
     --method ai_generated --model "gpt-image-2" --prompt "Winter city street..." \
     --parent '{"assetId":"<prev-asset-id>","role":"base"}' \
     --parent '{"externalRef":"claire_fullbody.png — LoRA tier-1","role":"reference"}'
   

2. 对于集合类型（keyframe、sfx、ref_image），使用 --label：

   python3 ${CLAUDE_PLUGIN_ROOT}/scripts/nl.py upload <shotUUID> sfx /path/to/city_ambience.mp3 --label "City ambience"
   

3. 对于用户上传的资产（无生成信息），使用 --method user_upload --user-note：

   python3 ${CLAUDE_PLUGIN_ROOT}/scripts/nl.py upload <shotUUID> ref_image /path/to/ref.png \
     --label "Character ref" --method user_upload --user-note "From LoRA training set"
   

上传后，询问自己：我刚才是否做出了重大决策（交换、替换、新方法）？ 如果是，继续操作前使用 nl.py decision 记录。

预检

python3 ${CLAUDE_PLUGIN_ROOT}/scripts/nl.py preflight <noteId> <label>

检查三项：start_frame 已就绪、audio 已就绪、active_prompt 存在。全部通过后才能生成。

生成并上传

在外部生成视频，然后上传：

python3 ${CLAUDE_PLUGIN_ROOT}/scripts/nl.py upload-roll <shotUUID> /path/to/video.mp4 --seed 42 --model "kling-2.6" --prompt-version 1

审查与评分

关于帧提取策略、评分标准、决策矩阵和报告格式，请遵循 nl-video-score 技能。以下是 CLI 集成。

按 5 个加权维度评分（最高 55 分）：

维度	标志	权重
面部一致性	--face	x3
表情还原度	--expr	x3
运动／变形	--motion	x2
稳定性	--stability	x2
风格匹配度	--style	x1

python3 ${CLAUDE_PLUGIN_ROOT}/scripts/nl.py score <rollId> --face 4 --expr 3 --motion 4 --stability 4 --style 4

根据判定采取行动

>= 45 — 黄金。锁定：

python3 ${CLAUDE_PLUGIN_ROOT}/scripts/nl.py verdict <rollId> approved
python3 ${CLAUDE_PLUGIN_ROOT}/scripts/nl.py golden-roll <rollId>
python3 ${CLAUDE_PLUGIN_ROOT}/scripts/nl.py decision <noteId> --shot <shotUUID> --action approve_golden --reason "scored 48, strong across all dimensions" --outcome "locked as golden, moving to next shot"
python3 ${CLAUDE_PLUGIN_ROOT}/scripts/nl.py shot-update <shotUUID> --status done

40-44 — 有保留地批准：

python3 ${CLAUDE_PLUGIN_ROOT}/scripts/nl.py verdict <rollId> approved
python3 ${CLAUDE_PLUGIN_ROOT}/scripts/nl.py golden-roll <rollId>
python3 ${CLAUDE_PLUGIN_ROOT}/scripts/nl.py decision <noteId> --shot <shotUUID> --action approve_with_reservation --reason "scored 42, minor hand drift at 6s" --outcome "approved, may revisit if stronger model becomes available"

30-39 — 拒绝并修改：

python3 ${CLAUDE_PLUGIN_ROOT}/scripts/nl.py verdict <rollId> rejected
python3 ${CLAUDE_PLUGIN_ROOT}/scripts/nl.py decision <noteId> --shot <shotUUID> --action plan_revision --reason "face morphing in last 2s" --outcome "adding negative prompt for morphing"

然后审查见解（见下方“编写或更新提示词前”），修正提示词并重新生成。不做任何修改，绝不重新生成。

< 30 — 拒绝并调试。不要重新生成。 按照下方操作手册执行。

记录决策与见解

决策 — 每次重大操作后记录：

操作：approve_golden、approve_with_reservation、plan_revision、switch_model、revise_prompt、block_shot、escalate_blocker、analyze_failure、strategy_change。

见解 — 发现可复用知识时记录：

类别（模态）：image、video、voice。

标签（必填，至少 1 个）：push-in、pull-out、pan、locked、timelapse、tracking、start-end-pair、single-frame、multi-keyframe、walking、talking、crowd、solo、reaction、insert、motion-direction、style-consistency、lip-sync、compositing、kling、wan、gpt-image、elevenlabs、scoring、review。

示例：nl.py insight <noteId> --category video --tags "motion-direction,walking" --title "..." --detail "..."

调试操作手册

评分低于 30 的生成

1. 不要重新生成。 先分析。
2. nl.py roll-context <rollId> — 查看全貌：提示词、输入素材、来源、评分。
3. nl.py decisions <noteId> --shot <shotUUID> — 已经尝试过什么？
4. nl.py insights <noteId> --tag kling（或相关模型标签）— 这个模型有哪些已知问题？
5. 查看评分卡 — 哪个维度的得分最低？这就是需要修复的目标。
6. nl.py overview <noteId> — 有已完成的镜头吗？对比黄金生成的提示词。
7. 记录：nl.py decision <noteId> --shot <shotUUID> --action analyze_failure --reason "..." --outcome "plan: ..."
8. 现在修复问题并重新生成。

同一镜头有 3 次或更多被拒的生成

停止。不要重新生成。

1. nl.py roll-diff <worst-rollId> <best-rollId> — 查看尝试之间的具体变化（提示词、输入、评分）。
2. 如果提示词版本不同：nl.py prompt-diff <noteId> <label> --from N --to M — 查看具体的文本改动。
3. nl.py decisions <noteId> --shot <shotUUID> — 到目前为止尝试过什么？
4. nl.py insights <noteId> — 是否记录过这种模式？
5. 考虑：切换模型、改写提示词、更换参考帧、简化镜头。
6. 记录：nl.py insight <noteId> --category video --tags "scoring,review" --title "..." --detail "Shot X required N attempts because..."
7. 记录：nl.py decision <noteId> --shot <shotUUID> --action strategy_change --reason "..." --outcome "new approach: ..."
8. 然后尝试新方法。

评分校准

• 55/55 = 完美，极其罕见。
• 45+ = 优秀。锁定结果。
• 首次生成的大多数输出得分为 35–42。正常。
• 根据简报评估模型，而不是评估简报本身。
• 起始帧与结束帧的 BG 不匹配 = 参考素材问题。标记，但不要扣分。
• 脚本台词对应的嘴部始终不动 = 预期情况（口型同步在后期处理）。不要扣分。
• 应该静止时嘴部却在动 = 模型故障（“活跃度偏差”）。在表情维度扣分。

素材来源

每项素材都应记录制作方式。来源信息始终可选，不会阻止上传。

上传时内联记录（首选 — 一次 API 调用）：

python3 ${CLAUDE_PLUGIN_ROOT}/scripts/nl.py upload <shotUUID> end_frame /path/to/end.png \
  --method ai_generated --model "gpt-image-2" \
  --prompt "Based on start_frame, generate end frame of 5s slow push-in..." \
  --parent '{"assetId":"<start-frame-id>","role":"base"}'

事后记录（适用于缺少来源信息的现有素材）：

python3 ${CLAUDE_PLUGIN_ROOT}/scripts/nl.py set-provenance <assetId> \
  --method user_upload --user-note "Downloaded from Midjourney, prompt: ..."

查询来源和沿袭关系：

python3 ${CLAUDE_PLUGIN_ROOT}/scripts/nl.py roll-context <rollId>         # best starting point — shows prompt, inputs, and provenance in one call
python3 ${CLAUDE_PLUGIN_ROOT}/scripts/nl.py provenance <assetId>          # how was this specific asset made?
python3 ${CLAUDE_PLUGIN_ROOT}/scripts/nl.py lineage <assetId> --depth 3   # full DAG with parent→child direction
python3 ${CLAUDE_PLUGIN_ROOT}/scripts/nl.py prompt <noteId> <label> --version 2  # view a specific prompt version

方法

• ai_generated — 由 AI 模型创建（记录模型和提示词）
• user_upload — 用户手动上传（记录 user_note）
• manual_edit — 基于现有素材手动编辑
• derived — 通过机械方式转换（例如，从对白生成填充音频）

父级角色

• base — 素材所衍生自的主要输入
• reference — 引导生成的视觉参考
• style — 风格参考
• mask — 遮罩或分割输入
• composition — 布局／构图参考
• audio — 音频输入（用于音频驱动的生成）

何时记录来源信息

• 始终在使用 AI 模型生成素材时记录 — 这是最有价值的沿袭数据。
• 用户上传素材时尽力记录 — 至少记录 method: user_upload。
• 对于不会增加信息的简单衍生素材，跳过。
• 上传生成结果时会自动记录 roll-snapshot — 无需操作。