@lingjingai/scriptctl

剧本阶段统一 CLI：把 txt/md/docx 或视频素材转为结构化 Script v4，同时继续原样读写和发布线上 Script v3；在本地工作副本上查询、校验、完整块批量写作或原子精修，并通过 revision CAS 发布。

安装

npm install -g @lingjingai/scriptctl

E2B agent-sandbox 镜像在 template_bundle.py 的 NPM_GLOBAL_PACKAGES 中已声明，无需手动安装。

随包安装的 skill

安装或更新本包时，postinstall 会把 skills/scriptctl（agent 使用约定）装到用户根目录下三处：~/.claude/skills、~/.agents/skills、~/.codex/skills，并把本次安装对应的 scriptctl 版本号戳进每份 SKILL.md 的 frontmatter（scriptctl_version）与 .scriptctl-version 标记文件。skill 自身版本号在 SKILL.md 的 version 字段。

• 源码检出（存在 src/）会跳过，不覆盖本地手改。
• 关闭：SCRIPTCTL_SKIP_SKILL_INSTALL=1。
• 手动补装：npm run install-skill（或 node scripts/install-skill.mjs）。
• pnpm 全局安装若未自动跑 postinstall，手动补装即可。

用法

scriptctl --help                    # 顶层帮助
scriptctl doctor                    # 环境自检
scriptctl update                    # 更新全局安装的 scriptctl
scriptctl changelog                 # 查看当前版本功能变更
scriptctl migrate -p <source.json> -o <target.json> --to <version>
scriptctl ingest --source-path <file|dir>
scriptctl checkout --script-path workspace/script.json
scriptctl actions --in '@ep:2/scn:1' --script-path workspace/script.json
scriptctl export episodes --in epA3kP9x..epQ7mN2v --output rewrite.scriptctl
scriptctl write rewrite.scriptctl --replace
scriptctl write rewrite.scriptctl --replace --apply --plan sha256:...
scriptctl audit-assets --script-path workspace/script.json  # 全剧资产一致性审计（不自动修改）
scriptctl validate
scriptctl publish

详细子命令、参数与退出码以 scriptctl <cmd> --help 为准，agent 行为约定见 agent-sandbox-runtime 中的 SKILL.md。

Script v4 的新节点使用类型前缀加 6 位 Bitcoin Base58 的 NanoID。查询可用 1-based @ 序号定位，修改使用查询返回的正式 ID。已有 Script v3 按显式 version: 3 继续走原有查询、写入、authoring 和 publish 实现，不改写旧 ID。

退出码

| 码 | 含义 | |---|---| | 0 | success | | 64 | usage / 参数错误 | | 66 | input file unavailable | | 70 | LLM transport / runtime failure | | 78 | validation failed; agent repair needed |

环境变量

| 变量 | 作用 | |---|---| | PROJECT_LITELLM_GATEWAY_API_KEY | 内置 LLM 配置引用的 gateway key | | PROJECT_LITELLM_GATEWAY_BASE_URL | 内置配置的 gateway endpoint；OpenAI-compatible synopsis 必须配置 | | SCRIPTCTL_LLM_CONFIG | LLM 路由 YAML；优先级低于 --llm-config | | AWB_BASE_URL | script-output gateway URL | | LINGJING_AWB_ACCESS_KEY | gateway 访问凭证 | | SANDBOX_PROJECT_GROUP_NO | 项目组号（也可用 --project-group-no） | | SCRIPTCTL_NO_DOTENV | 设为 1 跳过 .env 加载 |

LLM 配置按 --llm-config → SCRIPTCTL_LLM_CONFIG → $XDG_CONFIG_HOME/scriptctl/llm.yaml → ~/.config/scriptctl/llm.yaml 解析。固定位置文件不存在时使用类型化内置配置；显式文件缺失或任一已选文件非法时直接失败，不做合并或运行时 provider 切换。YAML 只允许通过 apiKey.env 引用密钥，路由格式如下：

version: 1
providers:
  gateway:
    protocol: anthropic
    baseUrl: https://gateway.example
    apiKey: { env: PROJECT_LITELLM_GATEWAY_API_KEY }
    timeoutMs: 240000
    maxAttempts: 3
models:
  default: { provider: gateway, model: claude-sonnet-4-6-aihubmix }
tasks:
  direct.episode-titles: default

开发

pnpm install
pnpm run build        # tsc → dist/
pnpm test             # vitest run，含端到端 mock-flow（pretest 自动跑 build）
pnpm run test:coverage  # 全量 + 输出 coverage/index.html
pnpm run typecheck    # tsc --noEmit

Changelog

功能变更记录在 changes/：

• 开发中改动写入 changes/unreleased.md
• 发版时把 unreleased.md 固化为 changes/<version>.md
• scriptctl changelog 查询当前版本
• scriptctl changelog --unreleased 查询开发中变更
• scriptctl changelog --from <version> [--to <version>] 查询版本区间

发布

# 改版本
pnpm version patch    # 或 minor / major
# 把 changes/unreleased.md 固化为 changes/<新版本>.md，并重置 unreleased 模板
pnpm publish          # access=public，会自动跑 prepublishOnly
# 同步更新 agent-sandbox-runtime/template_bundle.py 里的 @lingjingai/scriptctl@<新版本>

License

MIT