shuohao-skills

shuohao-skills 是一套专为 AI 编码 Agent（如 Claude Code、Codex）设计的技能包，将小说自动化转化为可直接投入生成管线的短剧制作素材。它覆盖了从大纲改编、角色设定、美术资产、剧本撰写到分镜生成的完整工作流，通过严格的“质量门”脚本检查，确保产出物的结构化和一致性。

核心工作流：五步闭环

该套件包含五个独立的 Skill，它们按顺序协作，数据通过 JSON 文件流转：

特点：所有报告均支持中英双语界面（默认中文，render --lang en 切换）。

可视化报告合成器

为了方便审阅，项目提供了一个组装器脚本，能将五个阶段的报告合并为一个单页 HTML：

node scripts/report.mjs --from <demo目录> --out report.html

• 智能拼装：自动发现目录下的 JSON 产物，只渲染已存在的阶段面板。
• 隔离机制：通过作用域前缀解决样式串味，通过代理解决脚本全局查询冲突，并自动重算图片相对路径。
• 交互体验：支持左侧导航切换、数字键 1-5 快速跳转、Cmd+F 全局搜索及“平铺全部”模式。

安装与使用

1. 快速安装

脚本会自动检测本机环境并建立软链，支持增量更新：

git clone https://github.com/eternityspring/shuohao-skills.git
cd shuohao-skills
./scripts/install.sh

• ./scripts/install.sh novel-characters：仅安装特定 Skill。
• ./scripts/install.sh --codex：仅链接到 Codex。
• ./scripts/install.sh --uninstall：取消链接。

2. 前置条件

• Node.js：≥ 18（Skill 脚本零依赖，无需 npm install）。
• 模型额度：使用当前会话的额度，无需额外 API Key。
• Codex CLI（可选）：若需出图功能，需安装 Codex CLI；否则跳过出图步骤。

3. 自测与开发规范

每个 Skill 必须包含 SKILL.md（给 Agent 读）和 scripts/selftest.mjs（给人/CI 读）。自测不调用模型，覆盖所有确定性逻辑：

# 运行全部自测
for f in skills/*/scripts/selftest.mjs; do node "$f"; done

目录结构与约定

为了保持仓库轻量和可维护性，建议遵循以下端到端 Demo 目录约定：

<demo>/
├── outline/       # novel-outline 产出 (.json, .md, -report.html)
├── characters/    # novel-characters 产出
├── art/           # novel-art 产出
├── script/        # novel-script 产出
├── storyboard/    # novel-storyboard 产出
│   ├── manifest.json
│   ├── E01-01/    # 分镜投产包 (prompt.md + f1..fN.png)
│   └── ...
├── docs/          # 人工编写的文档，与机器产物解耦
└── scripts/       # 辅助脚本

重要提示：分镜报告中的图片路径依赖于 storyboard/ 与段文件夹（如 E01-01/）的相对位置。切勿在段文件夹外再嵌套一层目录（如 segments/），否则会导致报告内图片静默失效。

为什么选择 shuohao-skills？

1. 标准化输出：通过数十道“质量门”脚本检查，确保 AI 产出的 JSON 和 Markdown 符合管线要求，减少人工清洗成本。
2. 模块化设计：五个 Skill 完全独立，可单独拷走或组合使用，互不侵入。
3. 零依赖运行：脚本仅使用 Node 标准库，无需复杂的 npm 依赖管理，启动极快。
4. 可追溯性：所有产出物均有对应的 JSON 中间态，便于版本控制和问题排查。

对于希望利用 AI 加速短剧创作、实现从文本到视觉资产自动化转化的团队或个人开发者而言，shuohao-skills 提供了一套严谨且高效的工程化解决方案。