@forgeax-extension/narrative
v0.2.12
Published
AI-driven narrative content generation pipeline for game development
Readme
叙事工坊 · narrative
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/narrativeimport { 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 节点为父节点 |
- 跨父连接推断(
inferCrossParentConnections)— 基于extractFullBranchPath+areBranchesCompatible按分支路径路由 - 组内结构修复(
repairGroupConnections)— 同父节点组内的顺序 / 分支连接修复 - 悬挂分支修复(
fixDanglingBranches)— 无 next 的非末位分支节点路由到兼容框架分支或标记 ENDING - NvN 路由精炼(
fixNvNRouting)— 多出口 → 多入口精确匹配(1×N / N×1 / N×N) - 跨分支过滤(
filterCrossBranchConnections)— 清理不兼容的跨分支连接 - 双向一致性(
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 里挂载的那份源码目录。确认挂载指向你当前正在改的工作副本——挂到另一份检出上时,页面会正常打开却完全不含你的改动,很容易在错误的代码上排查半天。
注意事项
- 密钥安全:
GEMINI_API_KEY放.env(已 gitignore),切勿提交 - 数据持久化:独立模式生成结果在
output/,插件模式在<projectRoot>/.forgeax/games/<slug>/narrative/output/(见双模式产物根);容器内未挂载卷时重建会丢历史 - 热更新: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 门控(见与平台「系统文件区」的联动) |
