Fiction Forge Skill

AI 短篇小说创作 Skill — 负责调度 Sub-Agent、编排 6 阶段 pipeline。

与 CLI 的关系

skill/   ← 本包：调度层（提示词 + 编排逻辑）
cli/     ← 工具层（校验、状态管理、参考注入）

• Skill 告诉 Agent "做什么"、"按什么顺序做"、"切换到哪个 Sub-Agent"
• CLI 提供 fiction-forge <command> 命令，处理输入输出校验、工作目录、Pipeline 状态机

Skill 不含任何代码，所有工具能力通过 fiction-forge CLI 提供。

执行模型

当前版本不再要求 Controller 手工读取 agents/*.md 并自己拼上下文，而是统一走：

orchestrate:prepare-run
  -> 运行阶段预处理
  -> 组装 input_artifacts
  -> 注入 references / automated checks / proofread / revise context
  -> 渲染出 rendered_prompt
  -> 交给对应 Sub-Agent
  -> orchestrate:complete-run

核心原则：

• prepare-run 是唯一合法的阶段上下文装配入口
• Sub-Agent 默认消费 rendered_prompt
• input_artifacts 用于需要回看原始文件时的补充读取
• Controller 不应直接手工解析 Mustache prompt、partials 或引用文件

前置依赖

npm install -g fiction-forge
# 或者在项目中
npm install fiction-forge

运行时依赖 bun。验证：

fiction-forge --help
bun --version

快速上手

1. 安装技能到项目

你可以使用 init 命令将该技能注册到当前项目中，支持 Trae、OpenCode、Cursor、Windsurf 和 Claude。

# 对于 OpenCode
fiction-forge init --type opencode

# 对于 Trae
fiction-forge init --type trae

2. 验证技能目录

cd .opencode/skills/fiction-forge/cli
./run.js workspace:list --cwd /path/to/project

如果当前环境不能直接执行 ./run.js，改用：

bun run.js workspace:list --cwd /path/to/project

3. 创建 / 进入一条创作流水线

./run.js workspace:parse --input "帮我写一篇《花火杂志》第2期青春短篇"
./run.js workspace:build --publisher 花火杂志 --episode 2 --cwd /path/to/project
./run.js pipeline:init --publisher 花火杂志 --episode 2 --episode-dir /path/to/project/workspace/花火杂志/第002期

4. 获取阶段交接上下文

推荐先看当前状态：

./run.js orchestrate:status --episode-dir /path/to/project/workspace/花火杂志/第002期 --format summary

推荐先看摘要：

./run.js orchestrate:prepare-run --episode-dir /path/to/project/workspace/花火杂志/第002期 --format summary

需要直接拿 Prompt 时：

./run.js orchestrate:prepare-run --episode-dir /path/to/project/workspace/花火杂志/第002期 --format prompt

默认 json 模式会返回完整结构，其中最重要的是：

• target.full_path：本阶段产物写入位置
• input_artifacts：可直接读取的原始依赖文件
• rendered_prompt：已完成注入和渲染的 Sub-Agent Prompt
• suggested_commands：当前阶段最值得执行的下一批命令

文件结构

skill/
├── SKILL.md                      # 主控提示词（Controller Instructions）
├── stages/
│   ├── prepare.yaml              # 需求采集（Screenwriter）
│   ├── outline.yaml              # 故事骨架（Screenwriter）
│   ├── draft.yaml                # 初稿生成（Writer）
│   ├── review.yaml               # 结构化审核（Editor）
│   ├── revise.yaml               # 定向修订（Writer-Revise）
│   └── finalize.yaml             # 终稿校对（Finalizer）
├── agents/
│   ├── screenwriter-prepare.md   # 编剧 Prompt（prepare）
│   ├── screenwriter-outline.md   # 编剧 Prompt（outline）
│   ├── writer-draft.md           # 作家 Prompt（draft）
│   ├── editor-review.md          # 编辑 Prompt（review）
│   ├── writer-revise.md          # 修订作家 Prompt（revise）
│   └── finalizer.md              # 校对员 Prompt（finalize）
├── references/
│   ├── golden-rules.md           # 弗兰克黄金法则
│   ├── opening-hooks.md          # 开头钩子模板
│   ├── plot-bank.md              # 题材灵感库
│   ├── review-standards.md       # 审核标准参考手册
│   └── style-guide.md            # 类型风格指南
└── contracts/
    └── artifacts/

部署

skill/ 目录是完整的技能模板；fiction-forge init 会复制它的内容，并补齐 cli/run.js。

Pipeline 流程

prepare → outline → draft → review ⇄ revise → finalize → done
                              ↓ PASS
                           finalize → done

• prepare — 交互式需求采集（auto-mode 也需确认）
• outline — 生成故事骨架（auto-mode 自动推进）
• draft — 全文一次性生成
• review — 结构化评分审核
• revise — 按 issue 定向修订
• finalize — 仅修技术性错误

常用命令

fiction-forge workspace:parse --input "帮我写一篇《花火杂志》第2期青春短篇"
fiction-forge workspace:list --cwd .
fiction-forge workspace:next --publisher 花火杂志 --cwd .
fiction-forge orchestrate:status --episode-dir ./workspace/花火杂志/第002期 --format summary
fiction-forge orchestrate:prepare-run --episode-dir ./workspace/花火杂志/第002期 --format summary
fiction-forge proofread --file ./workspace/花火杂志/第002期/v1/正文.md --format markdown
fiction-forge extract-context --file ./workspace/花火杂志/第002期/v1/审核.json --format markdown

体验提示

• 想快速交接给 Sub-Agent：优先用 orchestrate:prepare-run --format prompt
• 想先判断当前卡在哪一步：优先用 orchestrate:status --format summary
• 想先看阶段信息是否完整：优先用 --format summary
• review 阶段会自动补 automated_checks、review_references、style_fingerprint
• revise 阶段会自动补 revision_context 和 revise_references
• finalize 阶段会自动先生成 纠错报告.md

常见问题

1. 为什么 node run.js 跑不起来？

当前 runtime 走 Bun 打包链路，应使用：

./run.js <command>
# 或
bun run.js <command>

2. 为什么 Prompt 里还有 {{...}} 占位符？

这通常说明你直接读取了 agents/*.md，而不是使用 prepare-run 的 rendered_prompt。

3. 为什么 review / revise / finalize 看起来信息不全？

这几个阶段依赖预处理。请确保不是手工拼上下文，而是使用 prepare-run 的输出。

4. 为什么 Agent 跑去写 Python 脚本检查字数或验证 JSON？

说明 Agent 没有意识到可以直接调用内置 CLI。 规则：绝不要让 Agent 自己写 Python、Bash 或 Node.js 脚本来执行字数统计、格式校验等任务。请始终引导 Agent 使用 fiction-forge check:draft、fiction-forge proofread 等内置命令，并通过 --help 查看用法。

为什么 Fiction Forge 是一个优秀的 Skill 示例？

Fiction Forge 不仅仅是一个写小说的提示词集合，它完整展示了如何将一个复杂的、开放式的生成任务，转化为高可用、工程化、可复现的 AI 生产流水线。如果你想学习如何编写高质量的 Skill，本项目提供了以下教科书级别的示范：

1. 架构解耦与流水线设计 (Pipeline Architecture)

写小说是一个极度的长文本生成任务，直接让大模型“写一篇8000字的小说”往往会导致逻辑崩塌或流水账。本项目通过 stages/ 目录，将创作过程拆解为 6 个标准阶段（准备 → 大纲 → 初稿 → 审核 → 修订 → 终稿）。

• 示范价值：展示了如何通过状态机（State Machine）管理复杂的长线 AI 任务，避免模型在单一长 Prompt 中迷失，保障每一步都有明确的输入和输出。

2. 角色分离与职责单一 (Role-Based Agents)

项目中没有一个全能的“AI 助手”，而是划分了明确的 Sub-Agent（如 screenwriter 编剧、writer 作家、editor 编辑、finalizer 校对）。

• 示范价值：每个 Agent 拥有独立的 Prompt（在 agents/ 下），只做自己最擅长的事，完美践行了软件工程中的单一职责原则 (SRP)。

3. 严格的数据契约 (Strict Data Contracts)

为了让阶段之间能稳定交接，本项目在 contracts/ 中定义了严格的 JSON Schema。例如，Review（审核）阶段的产出必须是严格的 JSON 格式（包含评分、修改建议等）。

• 示范价值：展示了如何利用结构化输出（Structured Output）将 LLM 节点化，使其能够像普通代码函数一样返回确定性的数据结构，从而驱动后续逻辑流转。

4. 动态上下文隔离 (Context Isolation)

超长对话极易导致“上下文污染”和指令遗忘。本项目严格规定 Agent 不能直接读取历史聊天记录，而是通过 Controller (orchestrate:prepare-run) 为每个阶段按需组装 input_artifacts。

• 示范价值：教你如何精准控制大模型的上下文窗口（Context Window），只喂给它当前任务真正需要的依赖文件，极大降低了幻觉率。

5. 领域知识的动态注入 (RAG & Domain Knowledge)

项目并非单纯依赖大模型的预训练知识，而是在 references/ 中维护了“黄金法则”、“风格指南”、“开头钩子模板”等专业领域知识。

• 示范价值：展示了如何在特定阶段（如 Draft 或 Review）动态注入具体的知识库内容，让 AI 的输出具有真正的专业水准和行业深度。

6. Prompt 模块化设计 (Modular Prompts)

在 agents/_partials/ 目录下，剥离了可复用的提示词片段（如禁止使用列表、风格指纹等）。

• 示范价值：像写代码（DRY 原则）一样写 Prompt，通过模板引擎在运行时渲染，极大地提升了复杂提示词的可读性和可维护性。

7. AI 与传统 CLI 工具链的深度融合 (Toolchain Integration)

Skill 并没有让大模型自己去写脚本统计字数或校验格式，而是提供了原生的 fiction-forge CLI 命令集。

• 示范价值：展示了“Agentic Workflow”的最佳实践——将创造性工作（如剧情生成）交给大模型，将确定性工作（如文件 I/O、状态流转、JSON 校验）交给传统代码，两者优势互补，坚如磐石。

License

MIT