AI 短剧工作区 · `dsh-plugin-ai-drama`

DeepSeek Harness（DSH）插件：把 AI 短剧的 立项 → 总纲 → 人物 → 世界观 → 剧本 → 分镜 → 生成 → 导出 收进侧栏工作区，并附带「短剧模式」Agent 预设——35 个 drama_* 工具、10 个随包技能、72 个宿主路由、13 页签面板，以及与 LibTV / NeoWoW 画布 CLI 对接的生成编排适配层。

English: An AI short-drama workspace plugin for DeepSeek Harness. Sidebar + main-panel workspace covering the full short-drama pipeline, a dedicated drama agent preset with 35 agent tools, 10 bundled skills, a /drama slash command, criteria/quality gates, an asset & style system, safe local media access, asset import / cross-project reuse / multi-round review, shot-prompt import / VCS export, and adapters that drive external canvas CLIs (LibTV / NeoWoW). UI and docs are in Chinese.

它解决什么问题

写一部短剧，真正麻烦的不是「让模型写一段」，而是让几十集内容彼此一致、可查、可交付：人物设定散在聊天记录里、伏笔写完就忘、分镜表和剧本对不上、改一集要翻十处、导出还要手工拼；接上生成之后，又要管成本、管资产编号、管批量任务与失败重试。

这个插件把短剧创作当成一个有状态的项目来做：

单一事实源：结构化数据落在 .aidrama/*.json，.md 由它渲染，避免「两边同时改」的双写冲突；
落盘可恢复：所有写入走「临时文件 → rename」原子替换，覆盖前留 history/ 快照；
写入口安全：所有写路径统一校验（禁项目外/../UNC/设备路径/控制字符），非法输入不写盘、错误不泄露绝对路径；
确定性判据：一致性检查与创作质量判据（可观测性 / 景别接续 / 体态承接 / 光影 / 现场声等）不依赖模型，随时可跑；
生成物先入草稿区：AI 产出先进草稿，用户采纳后才进正式稿；
生成编排不内建生成能力：出图 / 出视频 / 出配音交给外部画布 CLI，插件只做适配、编排、回流、预算与门禁。

能力一览

模块	能力
工作区	侧栏「AI 短剧」入口 + 中央面板（13 页签 / 4 组：创作、资料、交付、高级），不遮蔽内置工作区浏览器，可与其它工作区插件共存
项目	新建 / 打开 / 重命名 / 删除；固定中文目录结构；全文检索；目录树子节点展开折叠并持久化
内容	剧集契约（含八大基本设定）、分集总纲、人物设定卡、世界观、分集剧本、分镜表、本剧记忆（伏笔/已用桥段/时间线/待回收）
分镜增强	情绪与强度、光影、现场声、禁令、起止体态、衔接、自然语言段、焦段、主体、分组；情绪总控分组 sidecar（不改分镜数组形状）
台词与音效	台词视图并入「剧本」、配音稿迁至「交付 / 导出」；角色卡音频（`media.audio`）与 `<audio>` 试听；旧 `dialogue` 深链自动重定向
素材与媒体	本地安全只读媒体通道（`media-read`）；素材登记仅项目内；素材目录扫描 + 批量登记；一键导入（≤50MB/件、SHA 去重）；跨项目资产复用与跨对象复制（资产卡/场景卡/风格 DNA）；素材库 2.0 统一卡片视图、视觉圣经专区（图墙按类型分组、定向/冻结）
资产审核	资产多轮审核状态机（`asset-save`，轮次上限 20）、场景卡审核、审核哈希、导出仅 `final` 状态带最终提示词
AI 能力	35 个 `drama_*` Agent 工具（仅在「短剧模式」会话注册）；检索增强；一致性检查；草稿区与采纳/丢弃
质量体系	创作判据（写作侧 + 结构侧，默认 WARN 不阻断）、判据规则单一源 `presets/rules/*.json`、评测门禁、资产质量门禁
资产与风格	9 类资产编号（CHR/SPC/PRP/SHT/CST/EXP/SFX/VOX/MUS）、资产卡与 `{{Asset_*}}` 占位符、场景卡、五维风格 DNA、风格定向 / 冻结 / 解冻（`style-save`）
成本与路由	成本预估 + 三级闸门；按任务选择 `fast / standard / strong` 成本档位；预算台账，同一任务只计费一次
批量生成	多集批量：规划 → 提交（可部分失败）→ 收敛；幂等提交、断点 resume、漂移检测；产物入库 URL/本地文件安全硬化
导入导出	剧本导入（预览 → 落盘）；分镜提示词 MD 导入桥（`format=shot-prompt`）；导出 Markdown / JSON / CSV / VCS 视图；导入导出互通
预设	「短剧模式」Agent 预设：短剧编剧/制片/分镜导演/合规顾问人格，移除 shell 类工具（工具白名单）
技能	10 个随包技能：立项、总纲、人物、剧本、分镜、导演/镜头语言、润色、审读、导出、分镜提示词兜底
命令	`/drama`（项目 / 进度 / 检查 / 草稿 / 导出 / 定稿 / 大纲 / 人物 / 世界观 / 剧本 / 分镜 / 润色）
交付	导出 Markdown 全本 / JSON 结构化包 / CSV 拍摄用分镜表（UTF-8 with BOM）/ VCS 视图；定稿快照与回滚

安装

要求：

DeepSeek Harness ≥ 0.2.0-rc.2（0.2.x 线；已验证 0.2.0-rc.2 与 0.2.1-rc.2，见「Harness 兼容性」）
Node.js ^22.19.0 || ^24.0.0
Web 界面（插件含客户端半，需要 dsh web / 桌面端的 Web 面）

插件是纯 JavaScript、无构建步骤（不需要 prepare / allowBuilds），三种安装方式任选。

方式一：直接从 GitHub 安装（推荐）

dsh plugin --profile <profile> add github:HengryLiang/dsh-plugin-ai-drama#v0.16.10

<profile> 换成你的 profile 名（dsh web 对应 web，桌面端通常是 desktop）。首次使用 dsh plugin 会自动创建 profile。

方式二：从 GitHub Release 的预打包 tarball 安装

curl -L -o dsh-plugin-ai-drama.tgz \
  https://github.com/HengryLiang/dsh-plugin-ai-drama/releases/latest/download/dsh-plugin-ai-drama.tgz
dsh plugin --profile <profile> add ./dsh-plugin-ai-drama.tgz

方式三：本地开发目录

git clone https://github.com/HengryLiang/dsh-plugin-ai-drama.git
dsh plugin --profile <profile> add ./dsh-plugin-ai-drama

验证安装

dsh --profile <profile> --dump-config    # 应出现 "# == dsh-plugin-ai-drama" 层

重启 DSH（或桌面端）后，侧栏出现 「AI 短剧」 图标；新建会话时预设选择器里出现 「短剧模式」。

卸载：dsh plugin --profile <profile> remove dsh-plugin-ai-drama。卸载不会删除你工作区里的 AI短剧/ 数据。

快速开始

重启后新建一个会话，在预设选择器里选 「短剧模式」；
点侧栏「AI 短剧」→ 新建项目，输入剧名（会生成固定目录结构）；
用对话驱动，或直接敲斜杠命令：

/drama 大纲 都市悬疑，12 集，每集 90 秒，强钩子
/drama 人物 补全主角与反派，给出形象提示词
/drama 进度                  # 看当前阶段与关键事实
/drama 检查                  # 跑一致性检查，直接返回问题清单
/drama 草稿                  # 查看待处理的 AI 草稿
/drama 导出 csv              # 导出拍摄用分镜表
/drama 定稿 3                # 冻结第 3 集剧本与分镜为快照，可回滚

面板 13 个页签 / 4 组：
- 创作：世界观（含八大基本设定）、总纲、人物、剧本、分镜；
- 资料：素材库、本剧记忆、草稿、账本；
- 交付：生成、检查 / 导出；
- 高级：目录、工具卡片。

「短剧模式」预设

预设以 Cordis YAML 声明（presets/drama.patch.yml），基于 DSH 随包标准预设改写：

persona 换成短剧编剧 / 制片 / 分镜导演 / 合规顾问；
去掉 shell 命令类工具（工具白名单）；
收敛子代理编排组，工具面聚焦创作；
追加隔离服务插件 dsh-plugin-ai-drama/preset：在该预设作用域内标记 dramaMode，主插件据此只对处于短剧模式的 Agent 注册 drama_* 工具，预设未启用时工具不出现，切走自动回收。

预设同时通过 @deepseek-ai/dsh-skill-filesystem 的 bundledSkillDir 随包挂载 skills/，所以「短剧模式」会话里 10 个技能自动可用。

模板变量只使用跨版本保守变量（provider / model），不使用 cwd 等段落局部变量（原因见「Harness 兼容性」）。

`drama_*` 工具（35 个）

分组	工具
项目	`drama_list_projects` / `drama_create_project` / `drama_get_project`
文档写入	`drama_save_contract`（含八大基本设定）/ `drama_save_outline` / `drama_save_characters` / `drama_save_world` / `drama_save_memory` / `drama_read_episode`
进度与检索	`drama_get_progress` / `drama_search_context` / `drama_get_ledger`
台词与素材	`drama_get_dialogue` / `drama_export_voice_script` / `drama_list_assets` / `drama_add_asset` / `drama_asset_save`（资产多轮审核）
草稿与定稿	`drama_save_draft` / `drama_list_drafts` / `drama_resolve_draft` / `drama_finalize_episode` / `drama_list_finalized`
导入 / 导出 / 质检	`drama_import_script`（剧本、`format=shot-prompt` 分镜提示词）/ `drama_check_consistency` / `drama_export`（markdown / json / csv / vcs）
生成编排	`drama_budget` / `drama_bind_canvas` / `drama_canvas_status` / `drama_reconcile_canvas` / `drama_plan_generation` / `drama_record_generation` / `drama_intake_artifact` / `drama_plan_batch` / `drama_submit_batch` / `drama_collect_batch`

工具全部是确定性实现（读写文件、结构化校验、检索、渲染、编排），生成类操作交给 Agent 调模型，插件只负责把结果安全落盘。测试用工具（drama_test_*）只在 DSH_AI_DRAMA_TEST_TOOLS=1 时注册，生产工具面保持 35 个。

随包技能（10 个）

drama-setup（立项）、drama-outline（总纲）、drama-characters（人物）、drama-episode（剧本）、 drama-storyboard（分镜）、drama-director（导演 / 镜头语言）、drama-polish（润色）、 drama-review（审读）、drama-export（导出）、drama-shot-prompt（分镜提示词兜底写作）。

斜杠命令 `/drama`

输入	行为
`/drama`	用法 + 当前工作区项目与进度
`/drama 项目`	列出短剧项目
`/drama 进度 [剧名]`	阶段与关键事实
`/drama 检查 [剧名]`	一致性检查，直接返回问题清单
`/drama 草稿 [剧名]`	待处理草稿
`/drama 导出 <markdown\|json\|csv\|vcs> [剧名]`	导出交付物
`/drama 定稿 <集数> [剧名]`	定稿某一集
`/drama 大纲\|人物\|世界观\|剧本\|分镜\|润色 [要求]`	交给 Agent 生成（会产生一次模型回复）

两条纪律：只在「短剧模式」会话生效（其它会话返回明确错误）；确定性操作不产生模型轮次。

内容模型（add-only，旧项目字节级不变）

八大基本设定（v0.16.3，contract.json 可选 8 字段，各有长度上限，缺省不落键）：地理与空间、时间与历史、力量体系、种族与生态、社会与势力、资源与经济、文化与信仰、灵魂/生死/因果；每字段在 剧集契约.md 按固定顺序渲染为条件段，context-card 摘要 ≤200 字/字段；
分镜可选字段：情绪与强度、光影、现场声、禁令、起止体态、衔接、自然语言段、焦段、主体、分组；情绪总控分组存 .aidrama/storyboard-groups/<集>.json sidecar，与分镜同事务、定稿快照一并保留；
视觉圣经：场景卡（.aidrama/scenes/cards.json，零相机锁合）、五维风格 DNA（.aidrama/style.json）；风格支持 定向 → 冻结 → 解冻 状态机（style-save：423 硬锁、409 expectedHash 冲突检测、解冻审计）。

素材与媒体（v0.15.8 – v0.16.10）

登记仅项目内：新登记只接受项目内路径；项目外绝对路径 / .. / UNC / symlink 逃逸一律拒绝且不写盘；历史外部登记在迁移期只读兼容（客户端标注「外部路径（待迁移）」，并提供扫描/一键导入迁移路径）；
media-read 安全只读通道（72 个宿主路由之一）：项目内相对路径、realpath 防 symlink 逃逸、图片/音频 MIME 白名单、≤8MB；错误码 invalid-args | forbidden | not-found | too-large，错误不泄露绝对路径；
扫描素材目录 + 批量登记：递归扫描 素材/，排除隐藏文件 / .aidrama / 清单文件 / symlink，未登记列表上限 1000（truncated 标记），批量登记串行、失败汇总；
一键导入 assets-import：5 类文件落 素材/<分类>/，≤50MB/件，SHA256 去重（409 conflict 不写盘）、同名自动 (2)、登记失败删除文件回滚；跨项目复用（sourceProjectId + sourceAssetIds[]，源项目只读、逐项 imported/skipped/failed）与跨对象复制（资产卡 / 场景卡 / 风格 DNA，ID 冲突跳过或分配空闲编号）；
素材库 2.0 / 视觉圣经：统一卡片视图、assetId 安全预览（data URL）、kind 筛选 / 搜索 / 排序 / 自动刷新 / 文件缺失占位；图墙按资产类型分组（场景 / 角色 / 道具 / 其他）+ lazy + lightbox；
产物入库安全硬化：intake-artifact 本地文件仅项目内；远端 URL 仅 http(s)、禁本机/内网/元数据地址、重定向 ≤5 跳且每跳复核、流式 ≤64MB、sourceUrl 清洗去凭据；
写路径安全审计：覆盖全部 HTTP / 工具写入口的路径负例矩阵（..、绝对项目外、UNC、设备路径、控制字符、%2e%2e 编码、.aidrama、保留名/尾随点空格、symlink 逃逸），非法输入零写盘。

资产多轮审核（v0.16.9）

asset-save 维护资产卡审核状态机（rounds ≤ 20），默认响应不变、旧卡零写回；
支持按需返回审核哈希（includeReviewHashes）；场景卡同链路；
导出时仅 final 状态附带最终提示词；跨项目复制会重置审核状态并给出 warning。

导入桥与 VCS 视图

分镜提示词 MD 导入：drama_import_script 的 format=shot-prompt 支持「草帽」式分镜提示词（镜头NN｜时间码｜景别｜焦段 + 光影： / 现场声： / 台词：）与分镜表 Markdown；固定 preview（只读，不写盘）→ apply（事务写盘，失败回滚）。未识别内容不会被静默丢弃。
VCS 视图导出：drama_export format=vcs 输出「全组情绪总控 + 逐镜 VCS 块」，确定性渲染（同输入同字节，无时间戳），可被导入桥回读（往返断言）。

质量体系（判据 / 门禁 / 评测）

判据规则单一事实源：presets/rules/*.json（judges / thresholds / lexicon / assets）， JS 侧与验收侧共用同一 loader，不在代码里维护规则镜像；
判据覆盖写作侧与结构侧；默认 WARN、不阻断 strict，旧项目缺字段自动 SKIP，零噪声；
资产门禁、评测门禁同样默认只提示；导出 / 定稿不被误拦。

成本与生成编排

	LibTV（主选）	NeoWoW（备选）
形态	本地 CLI `libtv` 子进程（默认 `~/.libtv/libtv.exe`，可用 `LIBTV_CLI_PATH` 覆盖）	本地 CLI `neowow` 子进程
登录	CLI 内完成	API Key
能力	画布 / 节点 / 上传 / 生成 / 下载	画布 / 节点 / 生成 / 轮询

成本档位路由：settings.taskModels.<task>.costTier 可选 fast / standard / strong；
成本预估 + 三级闸门：任务级 / 批次级 / 预算级上限，超限拦截并说明；
预算台账 .aidrama/budget.json，同一任务只计费一次；
两阶段编排：planGeneration → submitBatch（可部分失败、幂等）→ collectBatch （可反复调用直到全部产出；支持断点 resume 与漂移检测）；
护栏：绑定检查 + 写入前指纹 + 写入后漂移判定；双主防护只报告差异、不自动改画布；
不假装：账号状态来自 CLI 实测，产物状态必须见到真实文件。

数据落盘

<工作区>/AI短剧/
  <短剧名>/
    AI短剧/剧集契约.md / 总纲/分集大纲.md / 人物/人物设定卡.md /
    分集剧本/第001集.md / 分镜/第001集.分镜.md
    构想/ 世界观/ 台词与音效/ 素材/ 草稿区/ 定稿/ 账本/ 本剧记忆/ 导出/
    .aidrama/                       ← 机读源数据 + history/ 历史快照
      contract.json  outline.json  characters.json  world.json  memory.json
      storyboard/  storyboard-groups/  finalized.json  drafts/
      budget.json  tasks.json  assets.json  assets/cards.json
      scenes/cards.json  style.json  reviews/  audit/
  共享资料/                         ← 跨项目共享资料

结构化数据以 .aidrama/*.json 为唯一事实源；可见的 .md 由它渲染，不存在双写。所有写入原子替换，覆盖前留 history/ 快照（保留最近 20 份）。

架构

dsh-plugin-ai-drama/
  package.json            # dsh.manifestVersion / dsh.bundle.patch[2] / dsh.client
  cordis.patch.yml        # 把主插件插入组合树
  index.js                # 宿主半：72 个 POST /api/ai-drama/<method> 路由 + 工具白名单挂载 + /drama
  preset.js               # 预设伴生入口：provide('dramaMode') + 挂载随包技能
  presets/drama.patch.yml # 「短剧模式」Agent 预设声明
  presets/rules/*.json    # 判据 / 阈值 / 词表 / 资产规则（单一事实源）
  lib/store.js            # 项目仓储：原子写入、快照、结构化文档、检索、条目管理
  lib/media.js            # 本地图片 / 音频安全只读通道（路径与 MIME 白名单、≤8MB）
  lib/contract-world.js   # 八大基本设定（8 字段 schema / 校验 / MD 段 / context 摘要）
  lib/import-assets.js    # 素材导入 / 跨项目复用 / 跨对象复制
  lib/tools.js            # 35 个 drama_* Agent 工具
  lib/checks.js           # 确定性检查（分级 schema：pass/fail/warn/skipped）
  lib/consistency.js      # 一致性检查
  lib/retrieval.js        # 本地词法检索（中文单字 + 二元组 + BM25 风格打分）
  lib/import-bridge.js    # 分镜提示词 MD → 分镜 JSON 导入桥
  lib/video-prompt.js     # 草帽式 video prompt 渲染（确定性、限长）
  lib/criteria-rules.js   # 判据规则 loader（与 presets/rules 同源）
  lib/prompt-discipline.js / lib/shot-continuity.js  # 写作侧 / 结构侧判据
  lib/assets.js / lib/asset-gates.js                 # 资产编号 / 资产卡 / 资产门禁
  lib/scenes.js / lib/style-dna.js                   # 场景卡 / 风格 DNA
  lib/model-routing.js    # 成本档位路由（fast / standard / strong）
  lib/generation.js       # 任务台账 / 预算台账与闸门 / 产物回流（URL/本地文件安全硬化）
  lib/guard.js            # 上游冲突保护与双主防护
  lib/orchestrator.js     # 生成编排：规划 → 提交 → 收敛
  lib/backends/           # LibTV / NeoWoW CLI 适配层
  lib/exporter.js         # 导出 Markdown / JSON / CSV / VCS
  skills/drama-*/SKILL.md # 10 个随包技能
  client.js               # 客户端半：侧栏入口 + 13 页签面板（4 组）
  test/                   # 53 个测试套件，纯 Node 运行，无外部依赖

宿主半提供 POST /api/ai-drama/<method> 精确路由（请求头 x-ai-drama-request: 1），客户端半只用浏览器模块表提供的 React，不引入额外运行时依赖。

Harness 兼容性

原则：插件不因 Harness 升级而失效；只有真实契约变化才允许不兼容，且必须被测试门禁提前发现。

项	约定
已验证 Harness	0.2.0-rc.2（历史验收基线）、0.2.1-rc.2（兼容修复后实测）
preset 模板变量	只允许跨版本保守变量 `provider` / `model`；不得使用 `cwd` 等段落局部变量
peer 依赖	声明允许升级的范围（`>=0.2.0-rc.2 <0.3.0`），不锁死单个 rc 版本
升级 Harness 后	跑 `node test/all.mjs`（含 `preset-vars.mjs` 兼容套件）→ 在短剧模式发一条消息冒烟 → 记录版本与结果

开发与测试

npm run check     # node --check 三个入口
npm test          # 53 个测试套件

测试全部是纯 Node 脚本，使用假 CLI / 假 React，不需要 API Key、不消耗任何生成积分。依赖本机样例数据 / 夹具 / 历史基线包的套件在数据缺失时会自动 SKIP（例如部分基线对比套件），不影响公共 CI：CI 上 53 个套件全部通过（其中 1 个基线对比套件在无该基线包的环境打印 SKIP）。 CI：GitHub Actions 上跑 Node 22 / 24 × Windows / Ubuntu 组合（见 .github/workflows/ci.yml）。

兼容性

DSH 0.2.0-rc.2 及以上（0.2.x 线；已验证 0.2.0-rc.2、0.2.1-rc.2）；
Node.js ^22.19.0 || ^24.0.0；
宿主半跨平台；主要开发 / 验证环境为 Windows 11 + Node 24（macOS / Linux 欢迎反馈）。

已知边界（刻意保留的「不」）

不按任务覆盖模型参数：DSH 工具契约没有按调用覆盖模型参数的入口；成本档位只做「选模型」路由，不改推理参数；
不内建生成能力：不做模型接入与推理资源管理；
不猜测价格：外部平台只给文字计价规则时如实返回原文；
不自动改外部画布：对账只报告差异，写画布由用户确认；
判据默认不阻断：默认 WARN，是否升级为 FAIL 由用户 / 评测门禁决定；
媒体只读且仅项目内：media-read 只读项目内文件，不写盘、不缓存、不接受绝对路径；
历史上传的外部登记：迁移期只读兼容，新登记一律要求项目内路径。

dsh-plugin-ai-drama

Installation

README

AI 短剧工作区 · `dsh-plugin-ai-drama`

它解决什么问题

能力一览

安装

方式一：直接从 GitHub 安装（推荐）

方式二：从 GitHub Release 的预打包 tarball 安装

方式三：本地开发目录

验证安装

快速开始

「短剧模式」预设

`drama_*` 工具（35 个）

随包技能（10 个）

斜杠命令 `/drama`

内容模型（add-only，旧项目字节级不变）

素材与媒体（v0.15.8 – v0.16.10）

资产多轮审核（v0.16.9）

导入桥与 VCS 视图

质量体系（判据 / 门禁 / 评测）

成本与生成编排

数据落盘

架构

Harness 兼容性

开发与测试

兼容性

已知边界（刻意保留的「不」）

许可

Ähnliche Plugins

dsh-web (dsh-task-board)

dsh-web (dsh-web-all)

dsh-web-ui (dsh-task-board)

dsh-web-ui (dsh-web-ui-all)

Installation

README

AI 短剧工作区 · dsh-plugin-ai-drama

它解决什么问题

能力一览

安装

方式一：直接从 GitHub 安装（推荐）

方式二：从 GitHub Release 的预打包 tarball 安装

方式三：本地开发目录

验证安装

快速开始

「短剧模式」预设

drama_* 工具（35 个）

随包技能（10 个）

斜杠命令 /drama

内容模型（add-only，旧项目字节级不变）

素材与媒体（v0.15.8 – v0.16.10）

资产多轮审核（v0.16.9）

导入桥与 VCS 视图

质量体系（判据 / 门禁 / 评测）

成本与生成编排

数据落盘

架构

Harness 兼容性

开发与测试

兼容性

已知边界（刻意保留的「不」）

许可

Ähnliche Plugins

dsh-web (dsh-task-board)

dsh-web (dsh-web-all)

dsh-web-ui (dsh-task-board)

dsh-web-ui (dsh-web-ui-all)

AI 短剧工作区 · `dsh-plugin-ai-drama`

`drama_*` 工具（35 个）

斜杠命令 `/drama`