dsh-plugin-ai-drama

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，插件只做适配、编排、回流、预算与门禁。

能力一览

安装

要求：

• 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短剧/ 数据。

快速开始

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

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

4. 面板 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 个）

工具全部是确定性实现（读写文件、结构化校验、检索、渲染、编排），生成类操作交给 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

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

内容模型（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，零噪声；
• 资产门禁、评测门禁同样默认只提示；导出 / 定稿不被误拦。

成本与生成编排

• 成本档位路由：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 升级而失效；只有真实契约变化才允许不兼容，且必须被测试门禁提前发现。

开发与测试

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 只读项目内文件，不写盘、不缓存、不接受绝对路径；
• 历史上传的外部登记：迁移期只读兼容，新登记一律要求项目内路径。

许可

MIT © 2026 HengryLiang