npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@forgeax-extension/narrative

v0.2.12

Published

AI-driven narrative content generation pipeline for game development

Readme

叙事工坊 · narrative

TypeScript Node Extension Status

AI 驱动的游戏叙事生成模块。把「一句话需求」或「一部已有 IP 作品」变成可被下游玩法、美术、视频管线直接消费的结构化叙事资产:世界观 → 角色 → 道具 → 场景 → 大纲 → 剧情树 → 情节 → 任务 / 分镜。

四种运行形态,都是一等公民:

| 形态 | 入口 | 说明 | |:--|:--|:--| | 天工引擎平台扩展 | 平台活动栏「叙事设计」 | 以 @forgeax-extension/narrative 装配进天工引擎平台,能力同时暴露给平台对话 agent。契约 = forgeax-extension.json(schemaVersion: 2) | | 独立项目 | 自带后端 API + 前端画布,或 CLI | manifest 的 entry.standalone 声明了独立启动方式(embeddedAlso: true,形态并存不互斥)。节点视图保留完整的入口节点,脱离平台也能从需求输入一路跑到产物 | | Game 宿主扩展 | @forgeax/game 的扩展机制 | 薄壳 extension/ 接入,契约 = extension/extension.json(schemaVersion: 1 + requiresHostApi: 1 + executionMode: segmented)。地址与模型取宿主启用时写的 config.json,服务随宿主会话起停 | | agent 市场插件 | Codex 等 CLI agent 的插件市场 | 同一个薄壳经 extension/.codex-plugin/plugin.json 装载,没有宿主会话时服务由薄壳自起并常驻 |

薄壳两种形态的完整契约(配置来源、返回形状、生命周期归属、交付白名单)见 extension/CONTRACT.md。

两条输入路径,同一套生成内核:

| 路径 | 入口 | 说明 | |:--|:--|:--| | 从需求生成(主路径) | 用户需求文本 / 标签选择 | 三轴路由 + 席位管线组装,从零创作 | | IP 改编生成 | 上传小说 / 漫画 / 视频 / 压缩包 | 标准化建树 → 分层提取叙事 DNA → 改编裁剪 → 复用同一套生成管线 |

三层角色,同一批席位:

| 层 | 名称 | 本质 | 现状 | |:--|:--|:--|:--| | 编排层 | 叙事策划专家组 | 按游戏品类预制的多 agent 工作流 | 117 品类 → 4 条席位管线 | | 工具层 | 叙事单品助手团队 | 一个生成环节一席,可单独调用 | 23 席(全部已实现) | | 用户层 | 自定义专属团队 | 单本书模板助手 / 作家创作顾问 | 已实现(2 席蒸馏专家) |

目录


快速开始

前置条件

  • Node.js 20+
  • GEMINI_API_KEY(Google AI Studio 申请),或平台侧统一代理 LLM_PROXY_URL

方式一:在天工引擎平台内运行(主路径)

本仓库以扩展形式被平台装配。它不是主仓的 git submodule,而是一份独立 clone 的 浮动 checkout,位置 packages/ex-narrative,由主仓根的 .packages 清单声明 (旧布局 packages/marketplace/{plugins,extensions}/wb-narrative 已废弃)。

# 在主仓根目录
bun install
bun fx restart

# 前端构建产物是平台加载的入口,改完前端必须重建
npm --prefix packages/ex-narrative/viz run build

[!IMPORTANT] 平台的启动器不会拉起也不会停止本扩展的 sidecar:bun fx start 只起平台三服务, /api/narrative/* 的反代目标 :8900 需要自己起;bun fx stop 的停止名单里也没有它。 内嵌形态下手动起停见 §部署。

这个结论只适用于平台形态,别套到薄壳上:Game 宿主形态下服务由宿主起停(随会话走,停用与卸载都会回收), agent 市场形态下由薄壳自起并常驻。三种归属的判定规则与所有权保护见 extension/CONTRACT.md。

平台 UI 打开后从左侧活动栏进入「叙事设计」即可。平台会读取 forgeax-extension.json,把 viz/dist/index.html 挂成两块面板(左侧 320px 项目/任务管理 + 中间创作空间),并把 server/tool-handlers.ts 暴露的工具注册给平台对话 agent。

[!IMPORTANT] 前端改动不会被热更新自动带进平台——平台加载的是 viz/dist,不重新构建就看不到任何变化。

方式二:独立运行(后端 API + 前端 dev server)

叙事仓不是只能寄生在平台里——它同时是一个能独立运行的完整项目,manifest 中的 entry.standalone 就是这条路径的正式声明(embeddedAlso: true 表示两种形态并存,不是二选一):

npm install
echo "GEMINI_API_KEY=your_key_here" > .env   # npm start 经 --env-file 读取,文件缺失会直接报错

# 终端 1:后端 API
npm start                       # → http://localhost:8900,健康检查 /api/health

# 终端 2:前端 dev server
cd viz && npm install && npm run dev   # → http://localhost:5176

独立形态下没有平台对话栏兜底,所以节点视图里保留了完整的开始节点与相关入口:需求入口 input.entry 一枚节点就承载三类输入(直接输入 / 标签选择 / 文件上传)与三轴路由(类型 / 题材 / 体量),加上 routing 类目的两个路由入口,脱离平台也能从需求一路点到产物。详见 入口节点:独立运行的起点。

[!NOTE] 独立形态不共享平台的项目库与资产总线,产物只落在本仓 output/<run>/。要让产物被玩法 / 美术 / 视频管线消费,仍走平台形态。

方式三:CLI

# 自动识别品类生成
npx tsx src/cli.ts "做一个像原神的开放世界RPG"

# 指定 Tier(休闲游戏一步生成)
npx tsx src/cli.ts --tier=tier4 "做个贪食蛇"

# 指定 Mode(只生成到小说深度)
npx tsx src/cli.ts --tier=tier1 --mode=novel "赛博朋克复仇故事"

# 查看所有可用 Tier/Mode
npx tsx src/cli.ts --list-modes

生成结果保存在 output/<时间戳>/。

方式四:作为库引用

发布名是 @forgeax-extension/narrative(历史名 narrative-studio 只剩 docker 服务名还在用,npm 上没有这个包):

npm i @forgeax-extension/narrative
import { NarrativePipeline } from "@forgeax-extension/narrative";

const pipeline = new NarrativePipeline({
  apiKey: process.env.GEMINI_API_KEY!,
  tier: "tier4",
  onProgress: (p) => console.log(`[${p.step}/${p.totalSteps}] ${p.message}`),
});

const result = await pipeline.run("做个贪食蛇");
console.log(result.narrative_card?.game_name);

环境变量

GEMINI_API_KEY=your_key             # 必须(或改用 LLM_PROXY_URL)
LLM_PROXY_URL=http://...:10007      # 可选 — 内部 LLM 代理地址
LITELLM_PROXY_KEY=...               # 可选 — 代理鉴权
NARRATIVE_MODEL=gemini-2.5-pro      # 可选,默认 gemini-2.5-pro
SMALL_MODEL=...                     # 可选 — 轻量步骤用小模型
NARRATIVE_PORT=8900                 # 可选,API 端口
NARRATIVE_AGENT_DEBUG=1             # 可选,打印 agent plan/eval 详情
NARRATIVE_AUTO_DEBUG=1              # 可选,打印动态选步详情
NARRATIVE_DISABLE_EVAL=1            # 可选,关闭 evaluate 段

IP 改编的算子检索默认走 knowledge_base/(embeddings.npy + methods_3_converted.jsonl + retrieval_config.json)。查询向量化器按优先级解析:HTTP 端点 > 本地 e5(transformers.js) > ONNX;都未配置时静默降级为 scope+tag 关键词检索(corpus 仍可用,不抛错)。CLI 与后端 API 经同一 helper(resolveIpDnaRuntimeAdapters)注入,行为一致。

NARRATIVE_EMBED_URL=http://...:9100/embed             # 首选 — 本地嵌入 HTTP 端点
NARRATIVE_EMBED_MODEL=intfloat/multilingual-e5-small  # 可选 — HTTP 端点用模型名
NARRATIVE_EMBED_DIM=384                               # 可选 — 向量维度校验
NARRATIVE_EMBED_MODEL_DIR=/path/to/e5                 # 本地 e5 模型目录
NARRATIVE_EMBED_ONNX=/path/to/model.onnx              # ONNX 备选(onnxruntime-node)
FFMPEG_PATH=ffmpeg                                    # 可选 — 视频抽帧/压缩
ASR_ENDPOINT=http://127.0.0.1:9000/asr                # 可选 — 视频音轨转写
PDFTOPPM_PATH=pdftoppm                                # 可选 — PDF 拆页(poppler)

本地 e5 模型目录缺省取 knowledge_base/retrieval_config.json 的 model_path_local,开箱即用。


架构总览

四层收敛关系

flowchart TD
    contract["Agent 契约 · agent-contract.ts(4 原型 + 连接能力 + 生命周期)"]
    seats["二十三席助手 · assistant-seats.ts + seat-spec.ts(产品契约 + 形态配置表)"]
    pipes["四条席位管线 · narrative-pipelines.ts"]
    experts["117 品类专家 · expert-agents.ts(品类 → 四条之一的映射)"]
    axes["三轴路由 · knowledge/narrative-axes(品类 / 类型 / 题材 → 派生结构)"]
    manifest["RunManifest · run-manifest-builder.ts(步序 + 生命周期的运行事实)"]
    canvas["创作空间 · viz(节点视图自由编排 / 文本视图)"]
    kotone["平台对话 agent · server/tool-handlers.ts 暴露的工具"]

    contract --> seats
    seats --> pipes
    pipes --> experts
    axes --> manifest
    experts --> manifest
    manifest --> canvas
    manifest --> kotone

一句话概括这条链:席位是产品,step 只是它在某条管线下的实现;专家不自带步序,只是「品类 → 四条席位管线之一」的映射;运行时的唯一事实是 RunManifest。

核心抽象

| 抽象 | 实现位置 | 作用 | |:--|:--|:--| | Agent 契约 | pipeline/core/agent-contract.ts | Agent = 带类型的函数结构体。声明 4 原型(atomic / serial / parallel / nested)、数据契约、连接能力、执行原语绑定、生命周期 | | 统一注册表门面 | pipeline/core/agent-registry.ts | 把 AgentDef(纯数据)与 StepDescriptor(含 legacy 函数)两条查询路径收敛成一个入口,避免双事实源分叉 | | 席位注册表 | pipeline/routing/assistant-seats.ts | 23 席产品契约:职责原文、五类 kind、硬前置席位、产物类别、按作用域的实现绑定 | | 席位配置表 | pipeline/routing/seat-spec.ts | 每席的执行原语、八段提示词槽位填法、IP DNA 消费范围,以及形态落差登记 | | 席位管线 | pipeline/routing/narrative-pipelines.ts | 4 条按叙事层级切的席位序列(pl-narrative / pl-film-game / pl-codex / pl-card) | | 品类专家 | pipeline/routing/expert-agents.ts | 117 品类各注册一个 composite AgentDef,children 与席位管线同源 | | RunManifest | pipeline/runtime/run-manifest-builder.ts + pipeline/runtime/run-manifest-runtime.ts | 步序 + 每席生命周期的运行事实。算法只在后端,前端「未运行」预览也经此入口,禁止客户端重算步序 | | 三轴路由 | knowledge/narrative-axes/ | 叙事类型(13 + 其他)/ 叙事题材(19 + 其他)/ 游戏品类(117),综合推导叙事结构(12 种) | | 策略卡库 | knowledge/strategy/ | 按轴分目录的策略卡 md + strategy-loader.ts,构建时经 scripts/copy-strategy.ts 落到 dist | | Planner 引擎 | pipeline/_archive/planner/index.ts | legacy 路由的管线组装:narrativeSteps → pipelineTemplate 预置 → needs 规则 三级优先级。已归档,按「不迁移 legacy 管线」只封存不重写 | | Blueprint 执行内核 | pipeline/blueprint/ | 声明式 AgentDef + 5 种结构 Runner(single-turn / chunked / sequence / conditional / deterministic)+ composite | | PromptComposer | pipeline/runtime/prompt-composer.ts + pipeline/prompt/ | 骨架 + 槽位 + 叙事技法段(分支纪律 / 正文写法 / 镜头语言)组装成最终 system/user prompt | | 截断保护 | pipeline/runtime/llm-client.ts | responseFormat="json" 调用自动检测括号配平,截断时由 callWithRetry 自动重试并回灌错误 |

[!NOTE] pipeline/ 下已按职责分成 core/(契约与注册表)、routing/(席位与品类路由)、runtime/(执行与提示词组装)、blueprint/(结构 Runner)、qa/、graph/、steps/、_archive/(封存的 legacy)。

二十三席助手

coordinator 常驻入口总起全局;retriever 检索资料供其余席引用;generator 产出新产物写主字段;validator 出检查报告可选自动修正;polisher 另存打磨分支、主产物不动。

| # | 席位 | id | 类型 | 状态 | |--:|:--|:--|:--|:--| | 2.5.0 | 叙事生成配置助手 | entry_config | coordinator | 已实现 | | 2.5.1 | 百科娘 | encyclopedia | retriever | 已实现 | | 2.5.2 | 需求清单助手 | req_list | generator | 已实现 | | 2.5.3 | 策划文档助手 | design_doc | generator | 已实现 | | 2.5.4 | 世界观设定助手 | worldview | generator | 已实现 | | 2.5.5 | 角色档案助手 | character | generator | 已实现 | | 2.5.6 | 道具清单助手 | item | generator | 已实现 | | 2.5.7 | 场景列表助手 | scene_list | generator | 已实现 | | 2.5.8 | 故事大纲助手 | outline | generator | 已实现 | | 2.5.9 | 故事结构助手 | structure | generator | 已实现 | | 2.5.10 | 故事情节助手 | plot | generator | 已实现 | | 2.5.11 | 任务助手 | quest | generator | 已实现 | | 2.5.12 | 分镜助手 | storyboard | generator | 已实现 | | 2.5.13 | 叙事卡助手 | narrative_card | generator | 已实现 | | 2.5.14 | 设定集助手 | codex | generator | 已实现 | | 2.5.15 | 结构检查助手 | structure_check | validator | 已实现 | | 2.5.16 | 内容检查助手 | content_check | validator | 已实现 | | 2.5.17 | 去 AI 味助手 | deai | polisher | 已实现 | | 2.5.18 | 结构优化助手 | structure_optimize | generator | 已实现 | | 2.5.19 | 情节优化助手 | plot_refine | polisher | 已实现 | | 2.5.20 | 玩法适配助手 | playability | polisher | 已实现 | | 2.5.21 | 旁白解说助手 | narration | polisher | 已实现 | | 2.5.22 | 游戏循环设计助手 | game_loop_design | generator | 已实现 |

测试守着三条硬不变量:23 席与上表 2.5.0–2.5.22 编号一一对应;每个已注册 step 必须且只能归属一个席位(不允许孤儿 step);全部 23 席均为 active 且至少有一条执行绑定。

[!NOTE] 这张表的唯一事实源是 pipeline/routing/assistant-seats.ts,上面的编号、类型、状态都从那里逐字读出。席位增删后这张表必须跟着改——它曾经停在 20 席 2.3.x 的旧编号上,现已对齐到 23 席 2.5.x。

四条席位管线

按叙事层级切分,而非按品类家族。四条都以百科娘开场,前六席是共用设定层地基,叙事层三席产出剧情树,末尾是交付席 + 质检段。

| 管线 | 展示名 | 席位序列 | 覆盖 | 品类数 | |:--|:--|:--|:--|--:| | pl-narrative | 叙事管线(任务) | 入口 → 百科娘 → 设定六席 → 大纲 → 结构 → 情节 → 任务 → 质检 | tier1 / tier2 | 62 | | pl-film-game | 叙事管线(分镜) | 入口 → 百科娘 → 设定六席 → 大纲 → 结构 → 情节 → 任务 → 分镜 → 质检 | 影游 / 视觉小说 / 恐怖视觉小说 | 3 | | pl-codex | 叙事管线(设定集) | 入口 → 百科娘 → 设定六席 → 叙事卡 → 设定集 | tier3 | 34 | | pl-card | 叙事管线(叙事卡) | 入口 → 百科娘 → 需求清单 → 策划文档 → 世界观 → 叙事卡 | tier4 | 18 |

[!NOTE] 影游单列一条不是因为它的叙事骨架不同,而是因为它的下游多一个生图/生视频模型:任务树之后还要再出一份分镜,两样都是交付物。新架构里不管 RPG 还是影游都不再有「幕」:大纲定叙事单元、结构展开为剧情树、情节填节点内容,三层职责对所有品类同构;剧情树的形态差异(线性 / 树状 / 碎片化 / 涌现 / 多线交织 / 多视角交织)由结构轴的策略卡决定。

[!IMPORTANT] 四条管线共同的第一席是叙事生成配置助手(席位 2.5.0,2026-10-13 转 active)。它的产物是一份任务配置表(ctx.task_config → T2_任务配置.json):四轴、层级、体量、管线各占一格,每格标明来路(user / tags / vote / derived / llm / default)。

两条路径 + 两种输入模式,一份表。 支持直接输入(direct)与文件上传(file_upload)双模式承接:用户在入口把参数选齐,本席机械收录且一次模型都不调(整表 resolution: "declared");用户只给一句话或上传材料,本席拆解补全缺口(resolution: "inferred"),并在文件上传模式下产出改编策略(adaptationStrategy)、章节数预算(targetChapterCount)与 (0, 1) 开区间连续改编程度规格(fidelitySpec),供下游大纲/结构与算子注入做 if-else 分流。两条路径的表结构完全一致,下游不需要知道这次走的是哪条。

它与 tier-router 不重不漏:detectTier 做的是路由所需的最小识别(品类与层级,必须在步序开跑前定下来),本席做的是给用户看、也给下游取用的完整配置表,所以不重新判定品类。结构轴不问模型 —— 那是三轴加权投票的确定性结论。详见 pipeline/steps/entry-config.ts 的文件头。

RunManifest 与生命周期

每席在一次运行中的状态被显式建模并落盘,这是「改一处不必全线重跑」的基础:

stateDiagram-v2
    [*] --> pending
    pending --> running
    running --> completed
    running --> failed
    pending --> skipped
    failed --> running
    completed --> [*]
    skipped --> [*]
  • POST /api/narrative/plan 只做步序预演,把 agents[].lifecycle 全填 pending,供前端在未运行时预览完整管线
  • POST /api/narrative/agent/:id/run 单独跑一席,不牵动整条管线
  • 单跑与管线内跑拿到的提示词一致:run-agent.ts 自己 side-effect import 品类技能注册表,并在执行前走与 pipeline.run 同一句 prepareInjection(专属团队片段 + IP DNA 算子/关系/账本)。这两件事此前只在 pipeline.ts 里做,于是同一席单跑时会静默少掉几段提示词 —— 照跑、不报错,只是变差。由 single-seat-parity.test.ts 守着
  • completed 与 skipped 都算「无需重跑」,续跑时由 shouldSkipAgent 判定
  • 历史 checkpoint 经 lifecycleFromCheckpoint 反解为生命周期,旧数据可直接续跑

执行内核迁移现状

新旧两条执行路径并存,按席位逐个切换:

| 路径 | 入口 | 现状 | |:--|:--|:--| | legacy step 函数 | pipeline.run() → STEP_REGISTRY | 绝大多数席位仍走这条 | | 声明式 Runner | runWithBlueprint() → AgentDef + Runner | 已切 narrative_card 一席(useNewRunner: true) |

八席的声明形态(画布连接能力、平台看到的形态)与今天真能跑的执行原语存在落差,全部显式登记在 seat-spec.ts:SHAPE_DIVERGENCES,由测试盯着不许悄悄消失:

| 席位 | 声明形态 | 今天实跑 | 阻塞 | |:--|:--|:--|:--| | character / item | chunked | single-turn | 分批并发写在 character-enrichment 内部 | | scene_list | chunked | single-turn | L1/L2 分轮与并发写在 scene-generation 内部 | | outline | sequence | single-turn | 逐单元展开在 story-framework 内部成环 | | structure | sequence | single-turn | 由两个 agent 串成,席位级 sequence 未建模 | | plot / quest / storyboard | chunked | single-turn | 逐节点填充循环在各自 step 内部 |

病根统一:分批参数还写在 step 函数体里,没上移到 ChunkedConfig / SequenceStage。在参数上移之前打开 useNewRunner 只会跑进一个不认识我们数据的 runner。

LLM 调用约束

  • MODEL_OUTPUT_MAX_TOKENS = 65536 — Gemini 2.5 Flash/Pro 单次输出物理硬顶,全代码库统一引用
  • callWithRetry — 自动 3 次重试 + 指数退避 + 单次 300s 超时
  • JSON 截断保护 — 括号配平检测,截断时自动重试并把错误回灌给模型
  • 内容语言 — content_locale(zh / en)经 pipeline/runtime/content-locale.ts 注入指令,控制产出语言

平台集成

forgeax-extension.json(schemaVersion: 2)是平台侧的唯一契约,README 之外改动它必须同步 docs/manifest-schema-version.md。

仓里另有一份清单 extension/extension.json(schemaVersion: 1),那是薄壳给 Game 宿主与 agent 市场用的,两份互不相认也互不覆盖:平台只读前者、从不进 extension/;Game 宿主只读后者、从不读 forgeax-extension.json。薄壳侧的字段含义见 extension/CONTRACT.md,版本号由 npm run gen:catalog 从 package.json 单点派生,npm run check:release 会拦住漂移。

换宿主前先看 docs/platform-capability-tiers.md:它把能力分成纯本地、需宿主接口、深度绑定天工引擎三层,逐项写明不接会退化成什么,并记录平台侧尚未补上的三项欠账。

| 字段 | 值 | 说明 | |:--|:--|:--| | id | @forgeax-extension/narrative | 扩展标识 | | entry.frontend | ./viz/dist/index.html | 平台 iframe 加载入口 | | entry.backend | ./server/tool-handlers.ts | 工具实现 | | entry.standalone | npm run start @ 8900 | 可独立起服务,embeddedAlso: true | | contributes.pages | narrative(layout v2) | 左侧 320px sidebar + 中间 workspace,同一个 panelType 传不同 pane | | contributes.activities | narrative.launcher | 平台活动栏入口,order 140 | | contributes.skills | narrative:author-guide → SKILL.md | 触发词 /narrative | | contributes.tools | 51 个 narrative:* | 全部 exposedToAI + defaultAgentAllow | | contributes.surfaces | narrative.control / narrative.pipeline | 前端可被 agent 驱动的动作面 | | permissions | fs:*、model:text:reasoning、net:generativelanguage、emit:narrative.* | 平台沙箱授权 |

| 用途 | 工具 | |:--|:--| | 管线运行与预演 | start-pipeline / plan-pipeline / create-entry / run-seat / get-run-status / cancel-run / resume-pipeline(需确认)/ regenerate-step | | 路由与席位查询 | list-genres / list-modes / list-axes / list-seats | | 产物读取与改稿 | list-runs / list-files / read-file / get-story-tree / get-pipeline-nodes / load-history / export-result / save-step-edit / restore-original / tree-node / get-edits | | 改动预判与质保 | get-stale-steps / analyze-impact / qa-apply / qa-dismiss | | 评审、定稿、项目库与专属团队 | get-review / set-review / list-assets / confirm-asset / list-projects / save-project / delete-project / list-teams / get-team / create-team / distil-team / delete-team | | IP 改编 | ip-dna-start(需确认)/ ip-dna-ingest / ip-dna-get-hierarchy / ip-dna-decompose / ip-dna-confirm-scope / ip-dna-confirm-units / ip-dna-extract / ip-dna-generate(需确认)/ ip-dna-get-job / ip-dna-cancel / get-ip-dna / ip-dna-analyze-impact |

参数与返回的 JSON Schema 在 schemas/,与 manifest 里的 args / returns 引用一一对应。

设计原则是能力全量暴露、界面只是入口之一:产物与工具在前端都带 @ 引用,点击即把引用送进平台对话框;人可以在画布上精细编排,也可以整体脱手交给平台 agent —— 两条路改的是同一份后端数据。

双模式产物根

同一份代码既能独立跑也能作平台扩展跑,差别只在产物落哪。判定与切换只发生在 src/runtime/artifact-root.ts 一个文件里,其余 40+ 处调用点只管 outputDir() / resolveNarrativeRoot(),不关心自己被谁托管。

| 模式 | 判定 | 产物根 | |:--|:--|:--| | 独立 | 没有 FORGEAX_PROJECT_ROOT(或本次请求解不出 slug) | process.cwd()/{output,input} —— 与接入平台前逐字节一致 | | 插件 | 平台把 FORGEAX_PROJECT_ROOT 注入进程 且 本次请求解出了 slug | <projectRoot>/.forgeax/games/<slug>/narrative/{output,input} |

slug 的解析顺序(narrativeArtifactContextMiddleware,按请求存进 AsyncLocalStorage): 请求头 X-Forgeax-Slug → 查询参数 slug → 平台磁盘 SSOT .forgeax/active-game.json。 前端不必逐个改造 ~20 处裸 fetch,viz/src/lib/pane.ts 装了一次全局拦截统一补头。

[!WARNING] 两种模式是两份独立磁盘目录。内嵌形态下任务列表是空的通常不是 bug,而是插件模式 的 output/ 本来就没有东西 —— 独立模式跑的历史产物不会自动出现在平台项目里。

另外:进程一旦带着 FORGEAX_PROJECT_ROOT,即使请求不带 slug 也会被 active-game.json 兜底成插件模式。要验独立行为必须 env -u FORGEAX_PROJECT_ROOT 另起进程,并确认端口 没有被残留的旧进程占着。

与平台「系统文件区」的联动

平台的系统文件区是宿主 dock 的 footer 面板 ep:assets(中文「文件资源管理器」/ 英文 Content Browser),由 editor 注册。按插件产品规范,扩展不得自带文件资源管理器, 所以本扩展只负责两件事:产物落进文件区看得见的位置(上面的双模式映射已兑现), 以及提供「定位」把某份产物指出来。

viz 里点「定位」
  └─ GET /api/narrative/locate/:runId?path=<group>/<rel>   → 拿相对游戏根路径
       └─ postMessage FORGEAX_CONTENT_BROWSER_REVEAL { target:{ path, pathKind:'file', name } }
            └─ 宿主展开 ep:assets → 导航到父目录 + 选中

路径折算只能由后端做:<group> 是环节标签不是磁盘目录名(真实目录在 artifactRootsForAddress()),叠加双模式映射,这两张表都只存在于后端,前端复刻必然漂移。 按钮由 canLocateInContentBrowser()(= 被平台挂成分栏 iframe)决定渲不渲染, 独立形态下不给这个按钮,而不是给一个点了没反应的死键。

[!NOTE] 已知平台侧限制:宿主 DockRegion 会按活跃 page 的 panel 集合裁剪并门控面板 id, 而扩展 page 的集合里不可能有 ep:assets(page 布局树只收 page-platform panelType, ep:assets 属于另一套 DockShell 注册表)。后果是本次页面加载里若从未手动打开过文件区, 程序化「定位」只能补出底栏标签、展不开面板;手动开过一次之后,这一整个加载周期内 「定位」都正常。已排除的自救路线:改 manifest 布局树(两套注册表不互通)、重发消息 (连发 4 次无效,不是竞态)。等宿主放开门控,本扩展零改动即生效。


管线模板与模式

[!NOTE] 本节描述的是 legacy 路由层(Tier + Mode + Planner + 11 个模板)。它仍是当前实际跑起来的执行路径,但已不再是路由目标的终态——新架构的路由目标是四条席位管线。两者的解析差异由 narrative-pipelines.test.ts 显式登记,不做静默切换。

双层路由

| 层 | 作用 | 决策方式 | |:--|:--|:--| | Tier 路由 | 识别游戏品类,确定叙事强度等级 | 自动品类识别(LLM / 关键词)或用户指定 | | Mode 路由 | 在 Tier 内选择生成深度 / 范围 | 用户选择或 Tier 默认值 |

Tier 分级

所有 Tier 均先执行 D0-D4 策划管线,再按叙事强度执行不同深度的叙事管线。默认模式 design_auto(策划完成后按需求矩阵动态选步)。

| Tier | 名称 | 叙事占比 | 叙事深度 | 典型品类 | |:--|:--|:--|:--|:--| | Tier 1 | 叙事驱动型 | 70-95% | L0-L5 全量 + 道具 + 任务 + 场景 | JRPG, CRPG, AVG, 互动影游, 开放世界 RPG | | Tier 2 | 叙事增强型 | 40-70% | L0-L2 故事结构 + 角色 + 道具 | ARPG, 抽卡 RPG, 战棋, 生活模拟 | | Tier 3 | 叙事点缀型 | 15-40% | 世界观 + 角色 | 塔防, RTS, MOBA, 竞速, 卡牌 | | Tier 4 | 无叙事型 | 0-15% | 叙事卡(一步生成) | 三消, 跑酷, IO, 超休闲 |

关于 Lore:Lore 已集成进通用叙事 agent 内部,按 needs.L 维度在世界观 / 角色 / 道具 / 剧情等步骤中内嵌产出,不再独立成 step。

关于层级编号方向:代码 tier1 最重叙事、tier4 最简;产品侧叙事策划专家组的 T4 最重、T1 最简。两套编号方向相反但语义一致,映射写在 narrative-pipelines.ts 头部注释。

管线模板(11 个注册项)

src/pipeline/routing/templates.ts 定义。Genre → Template 经 genre-taxonomy.ts:GENRE_TEMPLATE_OVERRIDES 显式映射,未列出的按 tier 默认(tier4 → narrative-card / tier3 → light / tier1-2 → jrpg 系)。

| Template ID | 展示名 | 定位 | 默认 step 序列 | |:--|:--|:--|:--| | tpl-jrpg | tpl-jrpg | 新架构 JRPG 预制管线(V1),提示词从三轴槽位库按需组装 | 偏好 → 初步方案 → 世界观 → 角色 → 道具 → L0 → L1 → L2 → L3 → L4 → [L5 ∥ 场景] | | tpl-jrpg-v2 | tpl-jrpg-v2 | 归档精调管线(V2),原 tpl-rpg 整体提示词,作为 legacy 与对照基线保留可跑 | 同上 | | tpl-rpg | tpl-jrpg-v2 | 已弃用别名 → tpl-jrpg-v2,仅供历史 checkpoint / genre 映射兼容 | 同上 | | tpl-vn-v2 | 互动影游(专属管线) | 影游专属,展示层已去掉 v2 后缀,底层 id 保留以兼容历史数据 | 见下方折叠 | | tpl-vn | [已废弃] 视觉小说 v1 | 仅兼容历史数据 | 偏好 → 初步方案 → 世界观 → 角色 → 分支树 → 对话脚本 | | tpl-open-world | 开放世界 RPG | rpg-open-world | 偏好 → 初步方案 → 世界观 → 区域设计 → 角色 → 涌现事件 | | tpl-card-game | 卡牌游戏叙事 | card-ccg / card-narrative / card-dbg / card-boardgame | 偏好 → 初步方案 → 世界观 → 卡牌 Lore → 事件池 | | tpl-fragmented | 碎片化叙事 | Souls-like / Metroidvania / 心理恐怖 | 偏好 → 初步方案 → 世界观 → 角色 → 道具 → 场景 | | tpl-emergent | 涌现性叙事 | 4X / 沙盒 / 模拟经营 | 偏好 → 初步方案 → 世界观 → 角色 → 涌现事件 | | tpl-narrative-card | 叙事卡(Tier4) | 全部 tier4 品类 | narrative_card(一步生成) | | tpl-light | 轻量管线(Tier3) | tier3 大部分品类 | 偏好 → 初步方案 → 世界观 → 角色 |

[!WARNING] 新代码不要再引用 tpl-rpg:它已经是指向 tpl-jrpg-v2 的弃用别名,只为读旧 checkpoint 而存在。要新架构写 tpl-jrpg,要归档基线写 tpl-jrpg-v2。

Skill 可通过 frontmatter 的 enableSteps 激活模板的 optionalSteps。

src/pipeline/modes.ts:MODE_CONFIGS 完整定义。每个 Mode 是 (pipeline_template, target_endpoint) 二元组,实现「模板形态 × 停止点」的正交分解。

纯叙事模式(按 RPG 链路深度递进)

| Mode | 标签 | 适用 Tier | 截断点 | |:--|:--|:--|:--| | initial_outline | 初步方案 | tier1-3 | initial_plan | | worldview | 世界观 | tier1-3 | worldview | | character | 角色档案 | tier1-2 | character_enrichment | | item_lore | 道具 | tier1-2 | item_database | | story_framework | 故事框架 (L0) | tier1-2 | story_framework | | story_outline | 故事大纲 (L1) | tier1-2 | outline_batch | | detailed_outline | 故事细纲 (L2) | tier1-2 | detailed_outline | | novel | 情节 (L3) | tier1-2 | plot_generation | | script | 剧本 (L4) | tier1 | script_generation | | quest | 任务 (L5) | tier1 | quest_generation | | scene | 场景生成 | tier1-2 | scene_generation | | full | 全量生成 | tier1 | 含 quest ∥ scene |

风格化叙事模式

| Mode | 标签 | 模板 | |:--|:--|:--| | vn_full / vn_script / vn_storyboard_mode | 影游全量 / 止于剧本 / 含分镜 | tpl-vn-v2 | | fragmented | 碎片化叙事 | tpl-fragmented | | emergent | 涌现叙事 | tpl-emergent | | card_narrative | 卡牌叙事单品 | tpl-card-game | | open_world_narrative | 开放世界叙事单品 | tpl-open-world | | narrative_auto | 自动(Planner 按 needs/genre 动态决定) | 动态 |

Tier 直通模式:tier2_enhanced(tpl-jrpg 系)/ tier3_basic(tpl-light)/ narrative_card(tpl-narrative-card)

策划 + 叙事联合模式(design_* 前缀,UI 默认入口)

| Mode | 说明 | |:--|:--| | design_auto | 默认:D0-D4 策划 → 按 narrative_requirements.needs + genreCode 动态选择叙事步骤 | | design_full_narrative | D0-D4 → 全量叙事 | | design_vn_full | D0-D4 → 影游全量 | | design_fragmented / design_emergent | D0-D4 → 碎片化 / 涌现叙事 | | design_only | 仅 D0-D4 策划,不进叙事管线 |

品类知识库

内置 117 个游戏品类,定义在 src/knowledge/genre-taxonomy.ts:GENRE_TAXONOMY,按 15 个大类折叠分组。

interface GenreEntry {
  code: string;              // e.g. "rpg-jrpg"
  name: string;              // 中文显示名
  tier: TierId;              // 品类自带的只读派生属性,用户不再直接选层级
  category: GenreCategory;   // 15 大类之一(前端折叠分组用)
  narrative_ratio: string;   // e.g. "60-85%"
  needs: Record<string, 0 | 1 | 2 | 3>;   // W/C/S/D/Q/E/I/U/L 9 维需求评级
  keywords: string[];        // 关键词识别(LLM / 正则双路径)
  narrative_type: NarrativeType;          // 管线形态族,非文艺类型
  pipelineTemplate: PipelineTemplateId;
}
  • needs 9 维:W=世界观, C=角色, S=剧情结构, D=对话, Q=任务, E=环境叙事, I=物品, U=UI 文案, L=Lore;3=核心必需,2=重要推荐,1=可选点缀,0=不需要
  • narrative_type(5 值):linear / branching / fragmented / emergent / minimal —— 指的是管线形态族,与三轴里的「叙事类型」(剧情 / 喜剧 / 悲剧…13 项)是两回事,不可混用
  • Tier4 预设:22 个休闲品类预设 + 1 个通用兜底(knowledge/game-narrative/tier4-presets.ts)

管线步骤详解

策划管线(D0-D4,所有 Tier 共用)

| # | 步骤 | 输出 | 说明 | |:--|:--|:--|:--| | D0 | 核心概念 | core_concept | 游戏核心玩法循环 + 品类定位 | | D1 | 系统架构 | system_architecture | 6 个一批并行生成系统模块 | | D2 | 玩法设计 | system_detail | 各系统模块细化(6 个一批) | | D3 | 数值框架 | value_framework | 经济 / 成长 / 难度曲线 | | D4 | 策划案整合 | design_doc + narrative_requirements | 完整策划案 + 叙事需求矩阵 |

叙事管线 — 通用前置(所有非 Tier4 模板共用)

| # | 步骤 | 输出字段 | 说明 | |:--|:--|:--|:--| | 1 | preference_summary | user_preference_summary | 故事主题 / 风格基调 / 核心要素提取 | | 2 | preference_analysis | user_preference_analysis + global_control_params | 42 维度槽位映射 + 全局控制参数 | | 3 | initial_plan | initial_story_outline + core_settings + plot_synopsis | 单步一次性产出三个子字段 | | 4 | worldview | worldview_structure | 基础架构层 + 交互叙事层(W ≥ 1 启用) |

叙事管线 — tpl-jrpg 系(L0-L5 完整链路)

| # | 步骤 | 输出字段 | 核心机制 | |:--|:--|:--|:--| | 5 | character_enrichment | detailed_character_sheets | 角色丰化与弧光设计(C ≥ 2 启用) | | 6 | item_database | item_database | 资源型道具数据库(I ≥ 2 启用) | | 7 | story_framework | story_framework | L0 两步走(规划 → 修复 → 填充)+ 命运必然论 | | 8 | outline_batch | outlines_generated + l1_validation | L1 四步走 + 六步连接修复链,结构验证已内嵌 | | 9 | detailed_outline | detailed_outlines_generated + l2_validation | L2 四步走(同 L1),验证内嵌 | | 10 | plot_generation | plots_generated + l3_validation | L3 拓扑分层执行 + 三重约束 + 角色连续性验证 | | 11 | script_generation | jrpg_script | L4 拓扑分层 + 滑动窗口上下文 + 7 种 content 类型 | | 12 ∥ 13 | quest_generation ∥ scene_generation | quest_graph + scene_map | L5 任务(6 节点一批)∥ 场景(三阶段:骨架 → 展开 → 合并) |

E1 主路径(无上传剧本,从零创作)

| # | 步骤 | 输出字段 | 说明 | |:--|:--|:--|:--| | 1 | vn_logline | vn_logline | E1-01 一句话故事梗概 | | 2 | vn_outline_acts | vn_outline_acts + vn_character_bios + vn_key_items | E1-02 骨架扩写 + 全员人物小传 + 贯穿关键道具(单步三输出) | | 3 | worldview(借用) | worldview_structure | 已注入 logline / 骨架 / 人物小传上下文 | | 4 | vn_scenes | vn_scenes | E1-03 场搭建(三维状态变化 / H-B-O 结局分类) | | 5 | vn_beats | vn_beats | E1-04 情节点黄金线(线性,每场内按顺序排列) |

G 路径(剧本游戏化改造)

| # | 步骤 | 输出字段 | 说明 | |:--|:--|:--|:--| | 6 | vn_branched_beats | vn_branched_beats | G-01 剧情树改造:分支拓扑 + 双轨 QTE + 场号导出 | | 7 | vn_state_ledger | 状态账本 | G-01.5 跨节点状态账本,供剧本与分镜消费 | | 8 | vn_screenplay | vn_screenplay | G-02 剧本创作:按场分块调用 | | 9 | vn_storyboard | vn_storyboard + vn_video_prompts | G-03 分镜设计:镜头参数 / 景别 / 运镜 / AI 视频提示词 |

E2 旁路(上传剧本时自动替换 E1 中下层)

| # | 步骤 | 输出字段 | 说明 | |:--|:--|:--|:--| | E2-01 | vn_script_normalize | vn_script_normalized | 格式规范化 + 幕 / 场 / 情节点推断 | | E2-02 | vn_segment_confirm | vn_segment_confirmed + vn_character_bios | 分段验证 + 人物小传抽取 |

has_uploaded_script=true 时 pipeline.ts 把 E1 中下层替换为 E2,之后从 vn_branched_beats 汇合,两条路径互斥。影游线上角色档案席与道具清单席标记为 coveredBy——产物由 vn_outline_acts 单步顺带产出,不是缺失而是实现层合并。

| 模板 | 专属步骤 | 输出字段 | |:--|:--|:--| | tpl-open-world | region_design → emergent_event | regions / emergent_events | | tpl-card-game | card_lore → event_pool | card_lore / event_pool | | tpl-fragmented | character_enrichment → item_database → scene_generation | 同名输出 | | tpl-emergent | character_enrichment → emergent_event | emergent_events | | tpl-narrative-card | narrative_card | narrative_card | | tpl-light | character_enrichment | 同名输出 | | tpl-vn(已废弃) | branch_tree → dialogue_script → cinematic_storyboard(可选) | 同名输出 |

| 步骤 ID | 中文标签 | 层级 | 磁盘序号 | |:--|:--|:--|:--| | preference_summary | 偏好总结 | 前置 | 00 | | preference_analysis | 偏好分析 | 前置 | 01 | | initial_plan | 初步方案 | 前置 | 02-05 | | worldview | 世界观构建 | 前置 | 04 | | character_enrichment | 角色档案 | L0 | 09 | | item_database | 道具清单 | L0 | 10 | | story_framework | L0 故事框架 | L0 | 06 | | outline_batch | L1 故事大纲 | L1 | 07 | | detailed_outline | L2 故事细纲 | L2 | 08 | | plot_generation | L3 情节生成 | L3 | 11 | | script_generation | L4 剧本生成 | L4 | 12 | | quest_generation | L5 任务生成 | L5 | 13 | | scene_generation | 场景生成 | L5 | 14 | | narrative_card | 叙事卡 | T4 | 17 |

quest_generation 与 scene_generation 在 full 模式下并行执行;structure_validation_l1/l2 已合并进父步骤内部;scene_generation Phase 1 为 L0→L1→L2 串行增量提取;COMPLEXITY_NODE_BUDGET 控制 L0/L1/L2 每层硬上限,前端选择优先于模型输出。


IP DNA 改编生成

定位:与「从需求生成」平行的第二条输入路径。用户上传已有 IP 作品(小说 / 漫画 / 视频 / 压缩包 / 混合模态),系统把它标准化为层级化的「最小叙事单元树」,逐层提取结构化的叙事 DNA(角色 / 场景 / 事件 + 叙事方法「三件套」),经改编范围裁剪后复用同一套生成管线产出可玩叙事。全程以同一 story_timestamp 为主键,input/ 与 output/ 同名关联,落盘可续跑。

实现位于 src/ip-dna/,编排入口 orchestrator.ts:runIpDnaPipeline。LLM 均以「接缝(seam)」注入——无 API key 时走确定性兜底,离线 dry-run 也能跑通整链而不抛错。

提取与注入是一对镜像

每层产出三件套(模板 + 算子 + 元数据):模板是组成当前层级故事的基础信息,算子是当前层级提取出的方法,元数据用于配置。提炼自底向上,注入自顶向下:

flowchart LR
    subgraph EX["提炼(自底向上)"]
        e1["故事单元"]
        e2["游戏单元"]
        e3["完整游戏"]
        e1 --> e2
        e2 --> e3
    end
    subgraph IN["注入(自顶向下)"]
        i1["需求清单 / 策划文档 · top 层算子"]
        i2["故事大纲 · mid 层算子"]
        i3["故事结构 / 情节 · leaf 层算子"]
        i1 --> i2
        i2 --> i3
    end
    e3 --> i1
    e2 --> i2
    e1 --> i3

注入是显式声明的,不是隐式全量灌入:ip-dna/injection/slot-registry.ts:OPERATOR_SLOT_REGISTRY 逐 step 声明消费哪些槽位(结构 / 情节 / 对白 / 风格 / 情感算子)、取哪一提取层(top / mid / leaf)、是否要 KAG 关系子图与长记忆账本。未列入该表的 step 一律不注入,保持零额外开销;AgentDef.io.consumesIpDna 可覆盖默认值。

相位总览

| 相位 | 实现 | 职责 | |:--|:--|:--| | Phase 0 · 输入地基 | phase0-foundation.ts / phase0-compress.ts | 多模态分家归档到各媒体 *_original、生成《用户资产参考清单》;压缩包 / PDF 展开、媒体压缩(720p / 抽帧) | | Phase 1 · 标准化 | phase1-understanding.ts / phase1-multimodal.ts / noise-filter.ts / unit-identity.ts | 建轻量层级树(部/卷 → 章 → 最小单元)、多模态转写为叙事文本、干扰项过滤、体量水准线评估与超长章节默认拆解(decomposeOversizedChapters) | | Phase 2 · 3+2 阶浓缩提炼 | phase2-extract.ts / three-layer-taxonomy.ts / custom-team/ip-dna-bridge.ts | 内容三层架构(上层=游戏内容、中层=叙事信息、下层=叙事手法)× 3+2 阶自底向上浓缩(Step 1 最小单元 → Step 1.5 故事弧 story_arc → Step 2 游戏单元 → Step 2.5 叙事线 narrative_thread → Step 3 完整游戏),统一时空编码(SpaceTimeEncoding)与实体多版本切片(EntityVersionSlice),并内化产出单书专属 Skill | | Phase 2b/2c · 改编规划 | phase2b-adapt.ts / phase2c-gen-adapt.ts / fidelity.ts | 改编范围裁剪(全量 / 局部)、(0, 1) 开区间连续改编程度(滑动变阻器 ContinuousFidelitySpec)、游戏单元划分(超体量成系列)、A→B 映射到目标生成管线;系列多部按部串行、跨部经长记忆账本承接、每部结局收束 | | Phase 3 · 29 子类三层算子装备 | phase3-rag.ts / phase3-vector.ts / phase3b-kag.ts / three-layer-taxonomy.ts | 29 个叙事手法子类按 top / global / bottom 三层路由检索(vector / scope+tag / KAG),显式装备到生成输入 | | Phase 4/5 · 精修 | phase4-rewrite.ts / phase5-polish.ts | 忠实改写与产物润色 |

标准化的几条硬规则

  • 层级建树:多文件 / 卷目录按结构建多层树(打包目录自动剥离),单文件散文扫标记或整篇成一单元。「看结构不看名字」——文件名只决定标题,层级抽象由结构决定
  • 真实叙事序号 + 去重(unit-identity.ts):从标题 / 文件名提取真实序号(第八章_一场戏 → 8_《第八章_一场戏》,支持中文简繁体 / S01E03 / 第 N 话 / 页码),同序号重复单元保留末次
  • 干扰项过滤(noise-filter.ts):剔除引言 / 序 / 作者感言 / 求月票 / 公告等非正文,保留后记 / 番外等特殊章节
  • 体量水准线:按媒体维度(小说字数 / 漫画页数 / 视频时长)评估是否需拆解 / 系列化

半自动阶段门

前端 IpStageFlow 逐步驱动,每步落盘、可中断续跑:

上传(input/package 落包)→ ingest(标准化 + 建树)→ [体量抉择] → (decompose 再标准化) →
confirm-scope / confirm-units(改编范围 + 游戏单元)→ extract(scoped IP DNA)→ generate(下游生成)

上传的压缩包先落 input/package/,再解压到各媒体的 *_original 与 *_processing(POST /api/narrative/ip-dna/package)。自动模式 /ip-dna/start 一路走默认(全量改编 + 按体量定档),无逐步确认。

[!WARNING] 已知口径分歧:phase2c-gen-adapt.ts 仍保留「章→幕锚定」(开放幕数 = 裁剪范围内源单元数),这是影游 v2 管线的遗留假设。新架构里不管 RPG 还是影游都不再有「幕」——大纲定叙事单元、结构展开为剧情树。IP 改编路径接入新席位管线时这段需要一并收敛。


设计思想

适用范围:本节描述 tpl-jrpg 系 L0-L5 流程的核心设计原则。其它管线有各自的工作模式,不全部适用。

核心定位

不是「讲故事」,而是「创造可玩的游戏叙事体验」。输出必须满足下游管线(任务 / 场景 / NPC / 物品)的数据需求——角色、道具、场景、剧本、故事线都是可执行的游戏资产,而非纯文学产物。node_id(结构定位)与 content_id(内容标识)双轨并行,确保结构层可视化与内容层下游兼容。

牵一发而动全身

修改任一节点时,模型分析其影响面(同层后续节点 + 所有子层级后代),自动标记需要级联重跑的范围。例如修改 L0 节点 1,会触发所有以 1_ 开头的 L1/L2 节点及其下游 L3/L4/L5 重新生成。这也映射了叙事本身的规律——突如其来的变故会沿因果链向下扩散。

命运必然论 + 有限突变论

| 原则 | 内容 | |:--|:--| | 命运必然论 | L0 框架层预设所有可能的命运分支与结局;下层不能动态创建新结局;「大命运」在 L0 就已确定;最优路径优先选 a 分支(主线) | | 有限突变论 | 每层可产生独立新分支(Y 轴细化);新分支要么在本层聚合、要么路由到 L0 预设分支;细节变化不影响整体命运;突变路由不受三重约束管控 | | 双维度嵌套细化 | X 轴(顺序维度)把上层 1 个节点拆为 N 个连续子节点;Y 轴(可能性维度)在层内独立产生新分支;L1 与 L2 共用完全相同的细化逻辑 |

两步走与多步走

结构层(L0/L1/L2)把生成分为多个阶段,确保结构先行、内容后填。核心约束:代码保持骨架不变,模型只能在骨架结构内填充内容。

| 层级 | 机制 | 步骤 | |:--|:--|:--| | L0 | 两步走 | 规划结构骨架 → 连接修复 + 拓扑验证 → 填充内容 | | L1 | 四步走 | 规划子节点数 + 分支决策 → 代码构建骨架 → 六步连接修复链 → 按父节点分组填充 → 全局补漏 | | L2 | 四步走 | 同 L1,以 L1 节点为父节点 |

  1. 跨父连接推断(inferCrossParentConnections)— 基于 extractFullBranchPath + areBranchesCompatible 按分支路径路由
  2. 组内结构修复(repairGroupConnections)— 同父节点组内的顺序 / 分支连接修复
  3. 悬挂分支修复(fixDanglingBranches)— 无 next 的非末位分支节点路由到兼容框架分支或标记 ENDING
  4. NvN 路由精炼(fixNvNRouting)— 多出口 → 多入口精确匹配(1×N / N×1 / N×N)
  5. 跨分支过滤(filterCrossBranchConnections)— 清理不兼容的跨分支连接
  6. 双向一致性(ensureBidirectionalConsistency)— 确保 next_node ↔ prev_node 对称

质量保证体系

结构验证(L1 后 + L2 后各一次):环路检测(DFS 三色标记)+ 分支合并验证(并行分支必须有合并点或后继)。验证报告注入 NarrativeContext 供下游感知。

客观世界状态模型 $\Omega(t) \times$ 角色认知子集 $\mathcal{E}_c(t) \times$ 三视角创作联动(pipeline/world-model/):

| 维度 | 核心机制 | 作用 | |:--|:--|:--| | 客观世界状态 $\Omega(t)$ | 按时空坐标推进全局事实快照與因果不变量 | 维护世界观、角色状态、关键道具流转与场景变迁的单一客观真相 | | 角色认知子集 $\mathcal{E}_c(t) \subseteq \Omega(t)$ | 逐角色追踪已观测事实、信念偏差与信息盲区 | 严防角色"全知视角串戏"(未在场或未获知的信息不得出现在角色决策与对白中) | | 三视角联动(作者 / 角色 / 读者) | 作者全知布线 × 角色受限行动 × 读者体验预期(悬念/反差/戏剧反讽) | 通过双轨合流注入 L0–L3 与下游任务/分镜,兼顾逻辑自洽与戏剧张力 |

拓扑感知双预算动态分桶器(pipeline/graph/adaptive-batcher.ts):按 DAG 拓扑层级与复杂度同时约束每批「字符预算」与「节点数上限」(planAdaptiveBatches),在分支/汇合关口自动切分批次;L2 detailed_outline 一步定型并内嵌产出分支问题与选项(branch_question / branch_options),L3 plot_generation 承接连续渲染。

内容检查三路专精并行取证 × 多版本切片回写(pipeline/steps/content-check-reconcile.ts):2.5.16 内容检查先按动态分桶并行运行「角色取证 ∥ 道具取证 ∥ 场景取证」三路专精提取器,确定性去重合并后将新增状态回写为实体多版本切片(保留初始快照 _initial_snapshot),再执行八维主审;修复或合并节点(node-merge.ts)时自动按影响面级联重算下游。

三重约束 + 角色连续性(L3 情节生成时,utils/constraint-validator.ts):

| 约束 | 来源 | 作用 | |:--|:--|:--| | 边界约束 | L2 plot.cause / result | 确保情节不超出起止状态 | | 范围约束 | L2 content | 确保内容不脱离父节点主题 | | 边界校验 | L2 前后邻居 story_elements | 确保不与相邻节点内容越界 | | 角色连续性 | detailed_character_sheets + L3 content | 确保主要角色在场景中被引用,防止角色断层 |

上下文传递(L3/L4 拓扑分层执行)

  • 拓扑分层(topologicalLayers):按 DAG 依赖分层,同层并行、层间串行
  • 滑动窗口摘要(buildSlidingWindowSummary):把前驱节点实际生成内容的尾部 N 字符作为「上文回顾」注入
  • 祖先链上下文(buildAncestorChainContext):从 L2 → L1 → L0 逐级回溯,注入结构定位
  • 全局摘要(buildCharacterDigest / buildItemDigest / buildStoryArcDigest):精简的角色 / 道具 / 故事弧信息
  • 相邻分组摘要(buildAdjacentGroupDigest):同级兄弟节点摘要,帮助感知前后衔接
  • 策划上下文注入(buildDesignContextSnippet):D0-D4 结果摘要

逐层收束与叙事熵

complexity(1-5)唯一主控结构复杂度,派生 entropy 作为每层结构预算并逐层衰减;deviation(-1 ~ +1)独立调节内容风格,两者职责分离:

complexity (1-5, 前端选择或由模型在偏好分析步骤输出,前端优先)
  └─→ entropy = COMPLEXITY_ENTROPY[complexity]        // 结构复杂度总预算
        ├─→ layer_entropy = entropy × LAYER_DECAY[L]  // 逐层衰减(L0=1.0, L1=0.85, L2=0.72)
        │     ├─→ gross_target = lerp(profile.min, max)  // 该层分支事件频率区间
        │     ├─→ merge_tendency                         // 该层聚合倾向
        │     └─→ enforceBranchInPlan()                  // 强制最低分支率 + 聚合平衡
        ├─→ deviation_bound = clamp(entropy × 1.3, 0.2, 1.0)
        └─→ node_count = calculateNodeCount(entropy)

deviation (-1 ~ +1, 模型输出, clamp 到 ±deviation_bound)
  └─→ 纯内容层:-1 极度套路化,+1 极度反套路

| 复杂度 | 名称 | L0 根节点 | L1 每 L0 扩展 | L2 每 L1 扩展 | 预期总节点 | |--:|:--|:--|:--|:--|:--| | 1 | 极简 | 5-7 | 1(继承 L0) | 1(继承 L0) | 5-10 | | 2 | 短篇 | 4-5 | 2-3(克制) | 1(继承 L1) | 15-25 | | 3 | 标准 | 5-6 | 2-3(克制) | 1-2(克制) | 35-50 | | 4 | 丰富 | 6-8 | 3-4(正常) | 2-3(正常) | 75-100 | | 5 | 史诗 | 7-10 | 3-5 | 2-4 | 100+ |

三层防线:偏好分析钳位(clampLayerToBudget)→ 子节点裁剪(clampChildCount)→ L0 总量截断(先裁主干再硬截断)。

分支机制优先级:决定性参数(entropy 预算、L0 已定分支结构、层级继承规则)> 模型决策(has_branch / should_merge / branch_position)> 参考性参数(entropy 派生阈值)> 后处理矫正(只修连接不改结构)。

内容继承原则

剧本和故事线的值直接继承自情节层,不重新生成内容:

情节节点 (plots)
  ├─ .content[:200]                    → narration_point.summary
  ├─ .jrpg_elements.scene_location     → narration_point.scenes
  ├─ .jrpg_elements.scene_characters   → narration_point.characters
  ├─ .jrpg_elements.key_items          → narration_point.items
  ├─ .jrpg_elements.narration_hints    → narration_point.key_events
  └─ .jrpg_elements.dialogue_segments  → script.scenes.content[type=dialogue]

场景设计原则

核心理念:叙事用来创世,场景用于真正把这个世界渲染出来。

  • 又全又准:全(不遗漏任何叙事出现的场景与物品)、准(层级与归属正确,uid 稳定可对齐)
  • 六层结构:L0 世界 → L1 区域 → L2 地域 → L3 地标点 → L4 房间区域 → L5 物品
  • 三阶段生成:Phase 1 串行增量提取骨架(L0→L1→L2,每层把已有骨架作上下文)→ Phase 2 各故事单元并行展开 L3/L4/L5 → Phase 3 算法合并去重 + uid 分配
  • 世界观驱动 fallback:L0/L1/L2 数据为空时(如碎片化管线)回退到基于世界观、角色、道具生成场景骨架

规划目标与路线图

[!IMPORTANT] 本节写的是目标形态,不是现状清单。凡与前文冲突处,前文(现状)为准、本节为方向。写在这里的意义是:任何改动都该往这个形态收敛,而不是给现状再打一个补丁。

目标形态一览

| 主题 | 目标形态 | 现状 | |:--|:--|:--| | Agent 体系 | 四原型 × 二十三席 × 117 专家自由组装成任意管线,模板只是常用组合的快照 | 契约(pipeline/core/agent-contract.ts)与配置表(pipeline/routing/seat-spec.ts / pipeline/routing/expert-agents.ts)已立;23 席全部 active、设定层子步骤已显式拆分为独立子 Agent(SHAPE_DIVERGENCES 清零)、21 个 step 实现已迁到 AgentRunner(登记在 pipeline/core/runner-migration.ts) | | 单步与跳过 | 任意一席可单独跑、单独重跑,改一处不必全线重跑 | 单席 API + RunManifest 生命周期 + shouldSkipAgent + narrative:run-seat 已全量打通 | | 两台状态机 | 项目管理侧「运行状态机」+ 质保侧「质量状态机」双轨,产物既有跑到哪也有信不信 | 运行侧 = RunManifest;质量侧结构检查(2.5.15)与三路并行内容检查(2.5.16)+ qa-apply / qa-dismiss 闭环已落地 | | 三轴策略卡 | 品类 / 类型 / 题材 / 结构四类策略卡齐备,综合出叙事结构与提示词槽位 | 轴与结构推导已通;51 张卡落地,类型 / 题材 / 结构三轴已全覆盖,品类轴仍缺(见下方缺口公式) | | IP DNA | 分层提炼(逆转录)与显式注入(正向表达)一对镜像,槽位口径统一挂在席位上 | 内容三层架构、3+2 阶浓缩提炼(含 1.5 故事弧 / 2.5 叙事线)、29 子类 top/global/bottom 三层算子映射、统一时空编码与多版本切片已落地 | | 自定义专属团队 | 《书名》模板创作助手 / 作家创作顾问——把一部作品或一位作家蒸馏成可复用的团队 | 前后端全链路已打通(/api/narrative/teams*、/distil 及平台工具 create-team / distil-team / delete-team) | | 双入口等价 | 画布自由编排与平台对话栏两条入口能力对等,独立形态下画布自足 | 入口节点与编排已有;给了 requestedSteps 或画布拓扑时后端按 composition 驱动;23 席全部 active 可执行,对话栏可经 plan-pipeline + create-entry + start-pipeline 对等驱动 | | 能力暴露 | 产物与工具全量 @ 给平台 agent,叙事域对平台是白盒 | 51 个 narrative:* 工具(全量 exposedToAI: true + defaultAgentAllow: true)+ 双 surface 已实现 | | 库解耦 | 任务库 = 系统的账(会话产物),项目库 = 用户的柜子(跨任务挑选) | 已实现(含平台工具 list-projects / save-project / delete-project) | | 前端交互 | 就地展开、图标动态挤出、弹窗贴近触发源 | Detroit/Codex 暗色视觉统一、四原型容器(atomic/serial/parallel/nested)逐步全展开与收起/展开几何契约、剧情树分支四级拓扑投影(主节点→问题→选项→结果)已实现 |

策略卡缺口

缺口只剩品类一轴,另外三轴已经补齐:

| 轴 | 词表 | 已有卡 | 缺 | |:--|--:|--:|--:| | 品类 | 117 | 5 | 112 | | 类型 | 14 | 14 | 0 | | 题材 | 20 | 20 | 0 | | 结构 | 12 | 12 | 0 |

$$\text{缺口} = \underbrace{117}{\text{品类词表}} - \underbrace{5}{\text{已有品类卡}} = 112$$

knowledge/strategy/{genre,type,theme,structure}/ 按轴分目录批量补 md 即可,strategy-loader.ts 已能加载,注入链路有端到端测试守着——内容缺口,不是机制缺口。

[!NOTE] 补卡的收益面比缺口数字看起来小:seat-spec 里只有需求清单 / 策划文档 / 故事大纲 / 故事结构四席声明吃四轴策略,其余 18 席是 NO_STRATEGY。缺卡时对应子槽静默渲染为空,不报错也不留空标题。

明确不做的事

  • 不迁移 legacy 管线:老模板只封存不重写,新席位管线跑通后由数据决定谁退场
  • 不恢复写死的幕:幕数是按复杂度反推的软约束,最终锚定的是情节(情节描写 + 对话的剧本形式)。ip-dna/phase2c-gen-adapt.ts 里「章→幕锚定」是影游 v2 遗留,接新席位管线时一并收敛
  • 不在打开 useNewRunner 前抢跑:分批参数上移到 ChunkedConfig / SequenceStage 之前打开开关,只会跑进一个不认识我们数据的 runner

前端创作空间

天工引擎统一设计规范:深色主题采用纯净黑白色系(#232323 / #EDEDED),浅色主题采用天工橙白色系(#FC7027 主橙 / #FC9558 沙橙 / #FDD597 暖杏)。全链路支持中英文双语自适应与一键切换(viz/src/i18n 与 src/pipeline/runtime/content-locale.ts,仅 zh / en 二元结果态):

  • 初始默认跟随上级/回退中文:初始化时读取上级宿主语言信号(?locale= / window.parent.localStorage / postMessage),无明确信号时默认回退为中文 zh;
  • 用户/Agent 语言自动识别适配:用户发送需求或修改指令(或本地 Agent 发起任务)时,detectTextLocale 与 resolveRunLocale 自动从用户原话识别中文(zh)或英文(en),全链路 Agent 提示词、确定性产物与前端状态自动关联对齐;
  • 底部工具条最前方 中 / En 按钮:直观展示当前生效语言(中 或 En),点击一次即可在中英文之间立即互切,并通过 BroadcastChannel 实时同步左侧创作档案与右侧创作空间。

两栏分工

| 栏 | 组件 | 职责 | |:--|:--|:--| | 左栏 · 任务管理 | sidebar/TaskPanel.tsx + TaskFiles.tsx | 系统的账:一次对话开启的生成,产物按助手花名册自动归类,用户改不了。即资源库 | | 左栏 · 项目管理 | sidebar/ProjectVault.tsx | 用户的柜子:自建标题、标签、类别,条目可从多个任务里挑。即资产库 | | 右栏 · 创作空间 | NarrativeCanvas.tsx / panels/TextViewPanel.tsx | 节点视图(默认)与文本视图 |

左栏最左是一条竖图标条切换两块(sidebar/LeftPane.tsx)——左栏本来就窄,横向标签页一占就是一整行,竖条只吃掉最左一列。资源库与资产库解耦后,一个项目的资产可以来自多个任务。

工具栏与操作条

  • 顶栏工具栏(controls/CenterToolbar.tsx)三组:叙事策划专家组(按游戏类型两级展开:15 个类型 → 该类型下的品类专家)、叙事单品助手团队(全量二十三席,读 composer/seats.generated.ts)、自定义专属团队(lib/customTeams.ts)
  • 底部操作条(controls/CenterOverlay.tsx + controls/RunActionBar.tsx):最前方为语言切换键(中 / En),其后依次为视图切换、开始生成 / 取消 / 断点续跑 / 重新生成、放大缩小复原与清空画布,纯图标键排成一条居中工具条。按钮只往 store 的命令槽写一条,执行在 runtime/NarrativeRuntimeProvider.tsx
  • @ 引用:产物与工具项前的 @ 点击即把引用送进平台对话框,交给平台 agent 做增删改查

节点视图与自由编排

components/composer/ 承载无限画布编排:从工具栏拖一个角色进画布即成节点,连线是活连接,编排结果经 lib/composerRun.ts 提交。节点接点未连线时空心、连线后实心,颜色随节点;开始节点无左接点、结尾节点无右接点。自由编排的管线与预设冲突时以自由编排为准。

入口节点:独立运行的起点

节点模式始终保留开始节点(composer/composerCatalog.ts 的 ENTRY_CATALOG_ID = "input.entry")。这不是历史包留:平台形态下用户可以从对话栏起跑,独立形态下画布就是唯一入口,去掉开始节点等于砸掉独立运行的门。

一枚需求入口节点同时是管线锚点(category: "input")和路由配置的载体:

| 装什么 | 内容 | |:--|:--| | 三类需求输入 | 直接输入 input.text / 标签选择 input.tags / 文件上传 input.file(三者也可作独立节点单独拖出,入口节点内完全复刻其编辑面板) | | 三轴路由 | 叙事类型 / 叙事题材 / 叙事体量。第四轴「叙事结构」由后端按类型 + 题材推导,不出面 |

另外两组参数刻意不放进入口节点——放进去就是让入口替别人做决定:游戏品类(含其只读派生的层级)归顶栏「叙事策划专家组」,选专家即选品类;叙事单品归「叙事单品助手团队」,拖哪一席就是跑哪一件。routing 类目另有两个路由入口(叙事全量 / 叙事单品)。

入口节点两态不同人格,由 hooks/useEntryCard.ts 分开:编排态是可编辑节点(读写 store),生成态收敛成一张只读卡。两态共用一个组件会让人在跑的过程中还能改配置、改了又不影响这一轮——比看不见更糟。卡上取值优先级是「本次运行的 ctx > 编排态 config」:跑起来之后 user_input / narrative_axes / tier_detection 才是实际按什么跑的。

布局与几何契约

hooks/useDetroitLayout.ts 是布局引擎,几条规则是硬约束,改动前务必先读它的注释:

| 规则 | 含义 | |:--|:--| | 结构由数据推导 | 没有产物的步骤只画一张普通卡,不渲染空壳容器 | | 容器尺寸 = 子节点包围盒 | resolveContainerGeometry 自底向上递归;公式尺寸只作「未拖动时的初始摆放」,不是事实源 | | 四向扩张 + 标题栏上墙 | 子节点拖动可把外层容器向右、向下、向左顶开(向左时容器原点左移并重基子坐标);唯一硬墙是父容器标题栏高度 | | 邻居让位 | spreadTopLevelOverlaps 双向推开顶层邻居,维持最小间距 | | 场景树按深度分列 | sceneTreeToStoryNodes 消费 uid / parent_uid / scene_level,同深度共享列 | | 包含关系 ≠ 叙事分叉 | StoryNode.is_fork 显式声明,不用 next_node.length > 1 反推 | | 镜头指纹不含尺寸 | 布局缓存键只跟结构 / 折叠状态相关;含宽度会导致用户每拖一下都被 fitView 弹回全景 | | X 轴 = 拓扑深度,Y 轴 = 分支偏移 | 多层级节点 ID 以 _ 分隔(如 5_3c_2b),数字表顺序、字母表分支 |

单一权威源:pipelineOrder

后端 SSE 帧 pipeline_steps_announce 下发的步骤序列存入 narrativeStore.pipelineOrder,是前端渲染节点序的唯一权威源(管线状态栏、画布、文本视图三处共用)。步序算法只在后端,前端不重算。

动画与摄像机

  • 生成过程中伪实时节点生长动画(按下一步预估时间分配间隔),每个节点独立进度环
  • 自动跟随当前正在生成的节点;用户手动交互后切为手动模式,不再抢镜头
  • 生成完成、折叠 / 展开切换时重新取景;手动拖动不触发重新取景

API 参考

后端 60 个 REST handler / 54 条唯一路径(src/api/server.ts,其中 6 条路径注册了两个方法),基地址默认 http://localhost:8900。

| 方法 | 路径 | 说明 | |:--|:--|:--| | GET | /api/health | 健康检查(manifest 的 readyProbe) | | GET | /api/narrative/modes | 可用 Tier / Mode 列表 | | GET | /api/narrative/genres | 全部 117 个品类(按大类分组) | | GET | /api/narrative/axes | 三轴路由目录:叙事类型 / 题材 / 结构 |

| 方法 | 路径 | 说明 | |:--|:--|:--| | POST | /api/narrative/plan | 步序预演:只算 RunManifest,lifecycle 全为 pending,供未运行时预览 | | POST | /api/narrative/start | 从零启动生成 | | POST | /api/narrative/resume | 断点续传 | | POST | /api/narrative/regenerate | fork:按 modifications 仅重跑受影响 step | | POST | /api/narrative/agent/:id/run | 单席独立运行,不牵动整条管线 | | POST | /api/narrative/entry / /entry/start | 入口节点:需求 + 路由参数确认与启动 | | POST | /api/narrative/cancel/:id | 取消正在运行的 pipeline |

| 方法 | 路径 | 说明 | |:--|:--|:--| | POST | /api/narrative/ip-dna/package | 上传包落 input/package/,再解压到各媒体目录 | | POST | /api/narrative/ip-dna/start | 全自动:上传 → 标准化 → 提取 → 生成一路直跑(支持 async 返回 jobId) | | POST | /api/narrative/ip-dna/ingest | 半自动:仅摄入 + 标准化建树,停在层级确认 | | GET | /api/narrative/ip-dna/:runId/hierarchy | 层级树 + 体量 + 默认改编范围 | | POST | /api/narrative/ip-dna/:runId/decompose | 超体量再标准化(按标记边界拆块) | | POST | /api/narrative/ip-dna/:runId/confirm-scope | 确认改编范围(全量 / 裁剪) | | POST | /api/narrative/ip-dna/:runId/confirm-units | 确认游戏单元划分 + 改编维度 | | POST | /api/narrative/ip-dna/:runId/extract | 生成 scoped IP DNA(三件套) | | POST | /api/narrative/ip-dna/:runId/generate | 用 scoped IP DNA 驱动下游生成 | | GET | /api/narrative/ip-dna/:runId | 某次 IP DNA 运行的汇总信息 | | GET / POST | /api/narrative/ip-dna/job/:jobId · /cancel | 异步任务状态查询 / 取消 | | POST | /api/narrative/ip-dna/analyze-impact | IP DNA 编辑影响面分析 |

| 方法 | 路径 | 说明 | |:--|:--|:--| | POST | /api/narrative/analyze-impact | 影响面分析 | | POST | /api/narrative/save-step-edit | 保存某 step 的编辑草稿 | | GET | /api/narrative/edits/:dir | 某次 run 的编辑历史 | | POST | /api/narrative/restore-original | 撤销编辑回到原始 | | GET | /api/narrative/stale-steps | 列出受编辑影响的下游 step | | GET / POST | /api/narrative/review/:dir | 读取 / 提交人工评审 |

| 方法 | 路径 | 说明 | |:--|:--|:--| | GET | /api/narrative/status/:id | 运行状态 | | GET | /api/narrative/result/:id | 完整 NarrativeContext | | GET | /api/narrative/stream/:id | SSE 实时进度流 | | GET | /api/narrative/history | 历史记录列表(时间倒序) | | GET | /api/narrative/history/:key/load | 加载某次 run 的完整结果 | | GET | /api/narrative/pipeline-nodes/:id | 管线节点(PipelineState 格式) | | GET | /api/narrative/story-tree/:dir | 仅取剧情树(轻量) | | POST | /api/narrative/export/:id | 导出结构化资产到指定目录 | | GET | /api/narrative/files/:runId | 列某次 run 的全部输出文件 | | GET | /api/narrative/file/:runId/{*filePath} | 取某个文件原始内容 | | GET | /api/narrative/locate/:runId?path= | 把 <group>/<相对路径> 折成相对游戏根的路径,供平台文件区定位(仅插件模式有答案,独立模式回 standalone) |

调用示例

# 自动识别品类
curl -X POST http://localhost:8900/api/narrative/start \
  -H "Content-Type: application/json" \
  -d '{"user_input": "做一个像原神的开放世界RPG"}'

# 只做步序预演(不消耗模型额度)
curl -X POST http://localhost:8900/api/narrative/plan \
  -H "Content-Type: application/json" \
  -d '{"config": {"tier": "tier1", "genreCode": "rpg-jrpg"}}'

# 单独跑一席
curl -X POST http://localhost:8900/api/narrative/agent/worldview/run \
  -H "Content-Type: application/json" \
  -d '{"entry_key": "2026-08-11_10-00-00-000"}'

# 断点续传
curl -X POST http://localhost:8900/api/narrative/resume \
  -H "Content-Type: application/json" \
  -d '{"entry_key": "2026-08-11_10-00-00-000"}'

# SSE 实时进度流
curl http://localhost:8900/api/narrative/stream/{run_id}

目录结构

forgeax-extension.json        # ★ 平台契约:页面 / 工具 / surfaces / 权限(schemaVersion 2)
marketplace-card.json         # 市场卡片元信息(规范见 MARKETPLACE-CARD-SPEC.md)
SKILL.md                      # 平台对话 agent 的调用指南(触发词 /narrative)
schemas/                      # 各工具的 args / returns JSON Schema
server/tool-handlers.ts       # ★ manifest 声明的工具实现
scripts/                      # gen-seats / gen-catalog / build-extension / sync-game-extension /
                              # build-skills / lint-strategy / check-release
docs/                         # 专题设计说明(manifest 版本、任务与项目后端、legacy 打捞等)

extension/                    # 薄壳:给 Game 宿主与 agent 市场用,不随 npm 包发布
├── extension.json            # ★ Game 宿主契约(schemaVersion 1 / requiresHostApi / executionMode)
├── .codex-plugin/plugin.json # agent 市场清单
├── CONTRACT.md               # ★ 薄壳唯一契约说明(配置来源 / 返回形状 / 生命周期 / 交付白名单)
├── CAPABILITY.md             # 能力自述(给宿主侧的 AI 读)
├── cli.ts                    # 薄壳源码入口
├── cli.mjs                   # ★ 由 cli.ts 打包产出,宿主实际执行的就是它(check:release 校验新鲜度)
├── skills/narrative-workshop/     # 宿主侧 AI 的调用指南
├── codex-skills/narrative-workshop/  # 同上,agent 市场格式
└── src/
    ├── config.ts             # ★ 读宿主启用时写的 stateDir/config.json(地址与模型的来源)
    ├── verbs.ts              # ★ doctor / start / stop / open / tools 的实现
    ├── service.ts            # 服务进程起停(前台会话 vs 自起常驻)
    ├── credentials.ts        # 凭证三级回退:叙事自带 → 引擎 → 宿主 agent
    └── locate.ts             # 定位服务命令与宿主 agent

src/                          # 后端
├── types/
│   ├── index.ts                        # NarrativeContext + Tier/Mode + 9 维 needs
│   ├── run-manifest.ts                 # ★ RunManifest / 生命周期 / 组合图
│   ├── game-design.ts                  # D0-D4 策划数据类型
│   └── narrative-ip-dna.ts             # IP DNA 三件套与提取层类型
│
├── knowledge/
│   ├── genre-taxonomy.ts               # ★ 117 品类 + 15 大类 + 模板映射
│   ├── genre-narrative-type.ts         # 品类 → 管线形态族
│   ├── narrative-axes/                 # ★ 三轴:类型 13 / 题材 19 / 结构 12 + 派生推导
│   ├── strategy/                       # ★ 策略卡库(genre / type / theme / structure)+ loader
│   ├── game-design/                    # 策划侧知识
│   └── game-narrative/                 # Skill 体系(tier × genre)+ 6 种叙事原型基底
│
├── pipeline/                           # 按职责分四层 + 专题目录,根下不放散文件
│   ├── core/                           # 契约与注册表
│   │   ├── agent-contract.ts           # ★ Agent = 带类型的函数结构体(4 原型 / 连接能力 / 生命周期)
│   │   ├── agent-registry.ts           # ★ 注册表门面(AgentDef + StepDescriptor 收敛)
│   │   ├── runner-migration.ts         # ★ 哪些 step 实现已交给 AgentRunner(只增不改)
│   │   ├── pipeline.ts                 # ★ 主流程(start / resume / fork)
│   │   ├── seat-agents.ts              # 按配置表批量派生席位 AgentDef
│   │   ├── agent-exec.ts / run-agent.ts            # 单席执行
│   │   ├── step-registry.ts / step-registrations.ts  # legacy step 注册
│   │   └── needs.ts / step-skip.ts / action-guards.ts  # 9 维 needs / 跳过判定 / 动作守卫
│   ├── routing/                        # 席位与品类路由
│   │   ├── assistant-seats.ts          # ★ 二十三席产品契约
│   │   ├── seat-spec.ts                # ★ 席位配置表 + 形态落差登记
│   │   ├── narrative-pipelines.ts      # ★ 四条席位管线(新架构 SSOT)
│   │   ├── expert-agents.ts            # ★ 117 品类专家 = 席位管线的 composite 外壳
│   │   ├── modes.ts                    # ★ STEP_IDS(40) / MODE_CONFIGS(21) / 输出字段映射
│   │   ├── templates.ts                # ★ 管线模板(含弃用别名)
│   │   ├── tier-router.ts              # 品类识别 + Tier 判定
│   │   └── seat-attribution.ts / seats-projection.ts  # step → 席位归属 / 前端投影
│   ├── runtime/                        # 执行期
│   │   ├── run-manifest-builder.ts     # ★ config → RunManifest(步序算法只在后端)
│   │   ├── run-manifest-runtime.ts     # 生命周期跃迁 / checkpoint 互转
│   │   ├── llm-client.ts               # ★ 输出硬顶 + 重试 + JSON 截断保护
│   │   ├── prompt-composer.ts          # 骨架 + skill 注入 + 槽位填充
│   │   ├── content-locale.ts           # 产出语言指令(zh / en)
│   │   └── host-agent.ts / parallel-runner.ts / narrative-scale.ts  # 借宿主模型 / 并发 / 体量推断
│   ├── blueprint/                      # ★ 声明式执行内核(AgentDef + 5 种 Runner + composite)
│   ├── prompt/                         # ★ 骨架 / 槽位 / 叙事技法段(narrative-craft)
│   ├── graph/                          # 大纲与剧情树结构、拓扑排序、场景聚合与编号
│   ├── steps/                          # 叙事步骤实现
│   ├── design-steps/                   # 策划管线 D0-D4
│   ├── qa/                             # 质保发现与修复
│   └── _archive/                       # 封存的 legacy:planner / universal-agent / vn-v1 / vn-v2 / jrpg / scene 等
│
├── ip-dna/                             # ★ IP 改编子系统
│   ├── orchestrator.ts                 # 端到端编排
│   ├── phase0-*.ts … phase5-polish.ts  # 六相位实现
│   ├── injection/                      # ★ 算子显式注入(slot-registry + operator-injection)
│   ├── unit-identity.ts / noise-filter.ts   # 真实序号去重 / 干扰项过滤
│   ├── data-atlas.ts                   # 字段影响面图谱
│   └── filesystem.ts                   # input/output 布局与续跑
│
├── custom-team/                        # ★ 自定义专属创作团队(单书模板助手 / 作家创作顾问蒸馏与按席注入)
├── prompts/                            # 提示词资源(genres / ip-dna / _archive)
├── utils/                              # 连接修复 / 三重约束 / 图质检 / 剧本格式识别
├── runtime/artifact-root.ts            # ★ 双模式产物根:独立 cwd ↔ 插件游戏目录,判定只在这一个文件
├── integration/                        # 平台桥接客户端
├── api/server.ts                       # ★ HTTP API + SSE(60 handler / 54 路径)
├── cli.ts                              # CLI 入口
└── index.ts                            # 库入口

viz/                                    # 前端
├── src/
│   ├── components/
│   │   ├── NarrativeCanvas.tsx         # ★ React Flow 画布
│   │   ├── composer/                   # 无限画布自由编排
│   │   ├── controls/                   # 顶栏工具栏 / 底部操作条 / IP 阶段门
│   │   ├── sidebar/                    # 任务管理 + 项目管理
│   │   ├── panels/                     # 文本视图 / 文件预览 / 重生成面板
│   │   ├── runtime/                  # 命令槽执行 owner
│   │   └── nodes/ · edges/ · shared/
│   ├── composer/                       # 工具目录 + seats.generated.ts(构建生成物)
│   ├── hooks/useDetroitLayout.ts       # ★ 布局引擎(几何契约见前文)
│   ├── hooks/useNarrativeStream.ts     # SSE 通信
│   ├── store/narrativeStore.ts         # ★ Zustand 状态(含 pipelineOrder)
│   ├── lib/                            # 桥接 / 上传 / 资产库 / 三轴与品类缓存
│   ├── i18n/                           # zh / en
│   └── styles/
└── vite.config.ts                      # dev server :5176

knowledge_base/                         # IP DNA 算子语料 + 向量索引
input/                                  # 用户上传:package / book / picture / video / user_input
output/                                 # 生成结果(每次 run 一个目录)

★ = 关键文件,修改前先读注释与测试。


开发与测试

常用脚本

| 命令 | 作用 | |:--|:--| | npm run lint | 后端类型检查 + 表述噪声校验 | | npm test | vitest 全量(含席位不变量、管线解析、契约一致性、薄壳宿主契约、发布流程契约) | | npm run gen:seats | 由 assistant-seats.ts 生成前端 viz/src/composer/seats.generated.ts | | npm run lint:strategy | 校验策略卡 frontmatter 与命名 | | npm run lint:wording | 拦住只有开发现场才懂的指代(内部功能清单编号、阶段代号、评审轮次) | | npm run build:backend | 生成席位 → tsc → 拷贝策略卡到 dist | | npm run build | 后端构建 + viz 构建(平台加载的是 viz/dist) | | npm run build:skills | 重建 skill 索引 | | npm run gen:catalog | 由 package.json + 工具清单生成薄壳的 catalog.generated.ts / extension.json / plugin.json | | npm run build:extension | 由 extension/cli.ts 打包出宿主实际执行的 extension/cli.mjs;加 -- --check 只校验新鲜度不写盘 | | npm run sync:game-extension <目标目录> | 把薄壳按白名单(extension.json / cli.mjs / skills)交付给 Game 宿主,多余入口会被拦 | | npm run check:release | 发布前总闸:版本单点一致、薄壳产物新鲜、清单字段合法 |

生成物与单一事实源

flowchart LR
    seats["assistant-seats.ts(席位 SSOT)"]
    gen["scripts/gen-seats.ts"]
    fe["viz/src/composer/seats.generated.ts"]
    cards["knowledge/strategy/**.md"]
    copy["scripts/copy-strategy.ts"]
    dist["dist 内策略卡"]

    pkg["package.json(版本 SSOT)"]
    catalog["scripts/gen-tool-catalog.mjs"]
    manifests["extension.json / plugin.json / catalog.generated.ts"]
    cli["extension/cli.ts(薄壳源码)"]
    bundle["scripts/build-extension.mjs"]
    mjs["extension/cli.mjs(宿主执行的就是它)"]

    seats --> gen
    gen --> fe
    cards --> copy
    copy --> dist
    pkg --> catalog
    catalog --> manifests
    cli --> bundle
    bundle --> mjs

[!CAUTION] seats.generated.ts 是生成物,不要手改——改 assistant-seats.ts 后跑 npm run gen:seats。同理,步序算法只在后端,前端不得重算;要预览未运行的管线请调 /api/narrative/plan。

[!CAUTION] extension/cli.mjs 同样是生成物,但它比别的生成物更危险:宿主执行的是它,不是 cli.ts。改完薄壳源码不跑 npm run build:extension,宿主就会继续跑上一版代码,而源码读起来是新的——这种漂移曾真实发生过(打包产物停在旧版本号,导致宿主去取了上一版服务)。npm run check:release 现在会重建到临时目录逐字节比对,把这种漂移拦在发布前。

前端类型检查

npx tsc --noEmit -p viz/tsconfig.json

提交与远程

本仓库配置了多个远程(git remote -v 查看),改动要推到全部远程,否则下次有人从另一个远程拉取时会拿到旧版本。它作为子仓被主仓以固定版本指针装配,先推本仓再更新主仓,否则主仓的落后指针会把本地未推的改动覆盖掉。


部署

平台内(主路径)

扩展随主仓装配,但后端 sidecar 要自己起:平台只把 /api/narrative/* 反代到 :8900,谁去起 :8900 无人负责(bun fx start 不 spawn 它,bun fx stop 也不停它)。

# 终端 1:平台三服务(server :18900 / interface :18920 / engine :15173)
cd <主仓根> && bun fx start

# 终端 2:叙事 sidecar —— FORGEAX_PROJECT_ROOT 指向主仓根,即切到插件模式产物根
cd <主仓根>/packages/ex-narrative
NARRATIVE_PORT=8900 FORGEAX_PROJECT_ROOT=<主仓根> npm start

# 停:bun fx stop 只收平台三服务,sidecar 另外单独收
kill -TERM $(ss -ltnp | grep ':8900 ' | grep -oP 'pid=\K[0-9]+')

改动后:后端改了要 npm run build:backend(npm start 跑的是 dist/),前端改了要 npm --prefix viz run build,然后在平台活动栏进入「叙事设计」。

Docker

主仓 docker-compose.yml 内置 narrative-studio 服务:

docker compose up -d narrative-studio                 # 启动
docker exec narrative-studio curl -s http://localhost:8900/api/health   # 验证
docker compose build narrative-studio && docker compose up -d narrative-studio   # 代码改动后重建

容器把宿主 10019 映射到容器内 5176(viz dev server),API 8900 仅容器网络内可达。

[!WARNING] 容器服务的是 compose 里挂载的那份源码目录。确认挂载指向你当前正在改的工作副本——挂到另一份检出上时,页面会正常打开却完全不含你的改动,很容易在错误的代码上排查半天。

注意事项

  1. 密钥安全:GEMINI_API_KEY 放 .env(已 gitignore),切勿提交
  2. 数据持久化:独立模式生成结果在 output/,插件模式在 <projectRoot>/.forgeax/games/<slug>/narrative/output/(见双模式产物根);容器内未挂载卷时重建会丢历史
  3. 热更新:dev 模式挂载源码卷,src/ 改动自动重载;但平台加载的是 viz/dist,前端仍需构建

跨模块数据访问

其他模块(美术 / 逻辑 / 视频管线)取叙事产物有三种方式。

方式 1:平台工具调用(推荐)

平台对话 agent 与其他扩展经 manifest 声明的 narrative:* 工具访问,参数与返回有 JSON Schema 约束,不必关心内部实现。

方式 2:HTTP API

Docker 内网 http://narrative-studio:8900 可达:

const resp = await fetch("http://narrative-studio:8900/api/narrative/history");
const items = await resp.json();
if (items.length > 0) {
  const latest = await fetch(
    `http://narrative-studio:8900/api/narrative/history/${items[0].key}/load`,
  );
  const { result } = await latest.json();
  // result.worldview_structure      — 世界观
  // result.detailed_character_sheets — 角色档案
  // result.plots_generated          — 情节节点树
  // result.jrpg_script              — 剧本
  // result.quest_graph              — 任务图
  // result.scene_map                — 场景数据
}

定向导出到指定目录:

await fetch("http://narrative-studio:8900/api/narrative/export/run-id", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ target_dir: "/app/shared/game-project-1" }),
});
// → target_dir/assets/narrative/ 下生成所有资产文件

方式 3:文件系统

目录名为 <时间戳>[_标题](左栏发起)或 draft-<epoch>(画布编排发起):

output/2026-08-03_13-05-08-181/
├── manifest.json            ← 元信息(runId, tier, mode, 文件列表)
├── _run_manifest.json       ← RunManifest:步序 + 每席生命周期
├── _checkpoint.json         ← 断点续传数据
├── full_result.json         ← NarrativeContext 完整快照
├── T0_品类识别.json / T1_需求分析.json
├── 00_偏好总结.md
├── 01_偏好分析.json / 01a_全局控制参数.json
├── 02_初步方案.json
├── 04_世界观.json
├── 06_故事框架.json  + 06_故事框架/
├── 07_故事大纲.json  + 07_故事大纲/  + 07a_L1结构验证.json
├── 08_故事细纲.json  + 08_故事细纲/  + 08a_L2结构验证.json
├── 09_角色档案.json / 10_道具清单.json
├── 11_情节节点.json  + 11_情节节点/  + 11a_L3结构验证.json
├── 12_剧本节点.json  + 12_剧本节点/
├── 13_任务节点.json  + 13_任务节点/
├── 14_场景节点.json  + 14_场景节点/
│   ├── skeleton_fw_*.json    ← P1 L0 骨架提取
│   ├── skeleton_ol_*.json    ← P1 L1 增量提取
│   ├── skeleton_do_*.json    ← P1 L2 增量提取
│   ├── skeleton_merged.json  ← P1 合并骨架
│   ├── *_场景.json           ← P2 按节点展开
│   └── merged_场景.json      ← P3 最终合并
└── 17_叙事卡.json           ← 仅 tier4

同名 .json 与目录并存时,目录是按节点拆分的原子文件,便于单节点重生成与前端按需加载。

NarrativeContext 关键字段

| 字段 | 对应步骤 | 说明 | |:--|:--|:--| | user_preference_summary / user_preference_analysis | 偏好总结 / 分析 | 需求侧结构化结果 | | initial_story_outline / core_settings / plot_synopsis | initial_plan | 初步方案三件 | | worldview_structure | worldview | 世界观架构 | | story_framework | story_framework | L0 故事框架(含节点树) | | outlines_generated / detailed_outlines_generated | outline_batch / detailed_outline | L1 / L2 | | detailed_character_sheets | character_enrichment | 角色档案(属性 / 关系 / 台词风格) | | item_database | item_database | 道具清单(类别 / 稀有度 / 效果 / 归属) | | plots_generated | plot_generation | L3 情节节点树 | | jrpg_script | script_generation | L4 剧本 | | quest_graph | quest_generation | L5 任务图 | | scene_map | scene_generation | 场景数据(六层结构) | | narrative_card | narrative_card | 叙事卡 |

| 字段 | 对应步骤 | |:--|:--| | vn_logline | E1-01 | | vn_outline_acts / vn_character_bios / vn_key_items | E1-02(单步三输出) | | vn_scenes / vn_beats | E1-03 / E1-04 | | vn_script_normalized / vn_segment_confirmed | E2 上传剧本旁路 | | vn_branched_beats / vn_screenplay / vn_storyboard / vn_video_prompts | G-01 / G-02 / G-03 |

postMessage 桥接

平台内经 iframe postMessage 接收实时状态事件:

narrative-viz → narrative:step-changed → useNarrativeFeature
  ├─→ narrativeFeatureStore.updateStep() → externalNodes → PipelineBoard / EntityCard
  └─→ sendToHost(narrative runtime:node-status-changed)

管线节点映射为标准 PipelineState.nodes 格式:pipelineId: "narrative"、entityId: "main_story"、phaseId: <step_id>、status: not_started | ai_producing | done | needs_rework。


技术栈

  • TypeScript + ESM,Node 20.3+(薄壳合并取消信号用 AbortSignal.any)
  • Google Gemini API(@google/genai,默认 gemini-2.5-pro),可经内部代理
  • Express 5(HTTP API / CORS / SSE)
  • React 18 + React Flow(画布)、Zustand(状态)、Vite(构建)、lucide-react(图标)
  • Vitest(测试)、@xenova/transformers(本地嵌入)、mammoth(docx 解析)、zod(校验)

常见坑

| 坑 | 规避 | |:--|:--| | 改了前端却看不到变化 | 平台加载 viz/dist,必须 npm --prefix viz run build | | 改了席位却没同步到工具栏 | seats.generated.ts 是生成物,跑 npm run gen:seats | | 新代码引用了 tpl-rpg | 它已是指向 tpl-jrpg-v2 的弃用别名;新架构用 tpl-jrpg | | 打开 useNewRunner 后跑挂 | 先把该席的分批参数从 step 函数体上移到 ChunkedConfig / SequenceStage,并删掉 SHAPE_DIVERGENCES 里对应那条 | | 前端自己算步序导致与后端不一致 | 一律走 /api/narrative/plan;pipelineOrder 是唯一权威源 | | 画布容器被子节点捅破 / 拖动后回弹全景 | 几何事实源是子节点包围盒,不是尺寸公式;布局缓存键不得含尺寸 | | 给有子节点的场景挂上了分叉徽标 | 包含关系不是叙事分叉,用 is_fork 显式声明 | | 硬编码步序 / 管线名 / 幕数 | 全部走配置表与三轴推导;幕数不再写死,剧情树形态由结构轴策略卡决定 | | 在容器里验证却查不出问题 | 确认容器挂载的源码目录就是当前工作副本 | | 内嵌形态下任务列表空的 | 双模式是两份磁盘目录,插件模式 output/ 本来就是空的,不是 bug(见双模式产物根) | | 想验独立模式,产物却写进了插件路径 | 进程带着 FORGEAX_PROJECT_ROOT 就会被 active-game.json 兜底;用 env -u FORGEAX_PROJECT_ROOT 另起,并确认端口没被旧进程占着 | | /api/narrative/* 全 503 | sidecar 没起,且平台启动器里没有拉起它的代码,必须手动起 :8900 | | 点「定位」文件区不展开 | 本次加载先手动打开一次文件区;根因是宿主 pageScope 门控(见与平台「系统文件区」的联动) |