# 项目图的源码依据 基线：Harness `80aef3fa5582d8508ecdd1afa206391940ce9502`；Worldbook `3a11e333afd335aeff165e0ccc3654af8e1897d1`。这些图解释仓库实现，不认定当前线上全部启用。 ## 阅读入口 - [PM 业务导读：用户输入后发生什么](rp-business-guide.html) - [交互阅读器](project-map.html) - [项目全景](project-overview.html)：architecture - [Emochi 正文与后台](emochi-map.html)：workflow - [Sumi 图文流程](sumi-map.html)：workflow - [世界书资料与召回](worldbook-map.html)：workflow - [世界书怎么选条目](project-map.html#worldbook-selection) - [虚构 RP 例子](project-map.html#worldbook-rp) - [世界书代码细节](worldbook-selection-notes.md) - [世界书跨仓库依据](worldbook-sources.md) ## 服务分流 - [根目录边界与两个 npm 包](https://github.com/FlowGPT/roleplay-harness/blob/80aef3fa5582d8508ecdd1afa206391940ce9502/README.md#L3) - [服务启动入口](https://github.com/FlowGPT/roleplay-harness/blob/80aef3fa5582d8508ecdd1afa206391940ce9502/apps/emochi/main.ts#L1) - [v1 / v2 协议分流](https://github.com/FlowGPT/roleplay-harness/blob/80aef3fa5582d8508ecdd1afa206391940ce9502/adapters/agent-router/dispatch.ts#L1256) - [Sumi 优先独立返回](https://github.com/FlowGPT/roleplay-harness/blob/80aef3fa5582d8508ecdd1afa206391940ce9502/adapters/agent-router/dispatch.ts#L747) - [Story / Agentic V2 的装配](https://github.com/FlowGPT/roleplay-harness/blob/80aef3fa5582d8508ecdd1afa206391940ce9502/adapters/agent-router/dispatch.ts#L1125) - [场景组合限制](https://github.com/FlowGPT/roleplay-harness/blob/80aef3fa5582d8508ecdd1afa206391940ce9502/apps/emochi/server.ts#L715) ## 触发与状态 ### Emochi 后台规划 普通 Agentic V2 规划路径中，Actor 开始生成就启动。 协调器先选要咨询的专家 → 专家并行分析 → 必要时再协调 → 可选 Director 汇总候选状态 → 先校验，版本仍匹配才保存（CAS），避免旧结果覆盖新结果。快慢以同一轮起始状态为来源，但各自组织不同的模型输入；规划不读取本轮刚生成的正文。保存成功后，之后的轮次才可能读到它。没有每隔 X 轮的开关。专家按需选择：analyze_plot（剧情）、judge_npc（NPC）、audit_knowledge（知识）、simulate_world（世界）、manage_callbacks（伏笔）、direct_scene（镜头）；update_director_state 生成待校验的候选状态。 [源码 / 当前文档](https://github.com/FlowGPT/roleplay-harness/blob/80aef3fa5582d8508ecdd1afa206391940ce9502/apps/emochi/planning/runtime.ts#L558) ### 日记与摘要 每轮检查；达到规则才调用模型生成。 在 axon_go 且启用 compassMemory 的服务路径上，正文生成后调用 memory.ingest，由它安排后台日记任务；主链等待的是调度，不是整篇日记保存。旧配置 min_rounds 的代码兜底是 20，free_rounds_per_diary 是 10；新配置 first-rounds / recurring-rounds 的兜底也是 20 / 10。配置可以覆盖，最后由 Axon 的 should_generate 决定；这些数字不是已核实的线上值。 [源码 / 当前文档](https://github.com/FlowGPT/roleplay-harness/blob/80aef3fa5582d8508ecdd1afa206391940ce9502/apps/emochi/memory/diary-orchestrator.ts#L91) ### Sumi 图片 主模型一次生成正文，可附带状态和图片描述。 先返回正文，后台等消息确实保存并核对内容，再解析段落位置、取得任务占位；启用 imageGeneration 时才请求生图，检查审核结果后补图并通知。未配生图的旧快照只展示参考图。不是每 X 轮，也不是一轮专家规划。初始化缓存未命中时，另有顺序两次 VLM 调用。 [源码 / 当前文档](https://github.com/FlowGPT/roleplay-harness/blob/80aef3fa5582d8508ecdd1afa206391940ce9502/apps/sumi/runtime.ts#L154) ### Emochi 工具与图片 前台可以是 Actor，也可以先走工具循环。 启用 preActorDirector 时，前台规划器可选择 actor、generate_image、schedule_dio、over。Actor 负责正文，图片技能处理生图步骤，DIO 负责长期指令。前台工具循环可以与普通 Agentic V2 的并行规划同时启用；所以快链路不总是一次 LLM 调用。 [源码 / 当前文档](https://github.com/FlowGPT/roleplay-harness/blob/80aef3fa5582d8508ecdd1afa206391940ce9502/apps/emochi/actor/roleplay-runtime.ts#L380) ### DIO 长期指令 前台规划器选中 schedule_dio 时提交任务。 用于用户明确提出的长期行为或偏好修改。工具返回任务已受理后，后台编译 activePrompt；后续请求读取已经完成的版本。任务受理不代表修改已经生效。 [源码 / 当前文档](https://github.com/FlowGPT/roleplay-harness/blob/80aef3fa5582d8508ecdd1afa206391940ce9502/adapters/agent-router/dispatch.ts#L938) ### Compact 压缩历史 预算或检查点边界要求压缩时才运行。 把旧历史整理成检查点，准备本轮 Actor 的输入。某些配置中的比例是 token 预算占比，保留若干组历史也不等于每若干轮触发。它会影响当前模型调用前的上下文准备。 [源码 / 当前文档](https://github.com/FlowGPT/roleplay-harness/blob/80aef3fa5582d8508ecdd1afa206391940ce9502/apps/emochi/memory/compact-runtime.ts#L959) ### Story V1 下一轮先核实上轮已接受的正文，再推进世界。 准备本轮时重放已接受的上轮结果，调用剧情工具推进状态，再生成本轮 Actor。本轮完成时保存待结算结果。Story V1 替换普通 Agentic V2 规划路径，不是再叠加同一套后台规划。 [源码 / 当前文档](https://github.com/FlowGPT/roleplay-harness/blob/80aef3fa5582d8508ecdd1afa206391940ce9502/apps/emochi/story/coordinator.ts#L190) ### Worldbook 世界书 按输入与场景召回条目，注入当前 Actor。 仅在指定 Worldbook 场景启用：先从 Axon 读取固定 book_id / revision 与当前状态，再经 worldbook.select 选条目。默认 hybrid、世界书预算 2400，可配置；输入包括本轮 query、公开场景和最近历史。服务返回 blocks，Harness 按位置插入 Actor，再检查完整 Prompt 的总预算。每轮准备一次，Actor 重试复用本轮选择；不直接注入后台 Planner，也不写剧情状态。 [源码 / 当前文档](https://github.com/FlowGPT/roleplay-harness/blob/80aef3fa5582d8508ecdd1afa206391940ce9502/apps/emochi/worldbook/runtime.ts#L39) ### 通用快慢编排 调用 FastSlowRuntime，才启动它自己的快慢组合。 默认 SimpleFastRuntime 是一次模型调用；自定义 FastTurnRuntime 可以接入业务链路。Workflow 的调度、重试和触发轮数由宿主负责。仓库不会看到一份 Workflow 就自动替所有产品接上快慢系统。SDK 自带的组合也没有每 X 轮触发字段。 [源码 / 当前文档](https://github.com/FlowGPT/roleplay-harness/blob/80aef3fa5582d8508ecdd1afa206391940ce9502/docs/sdk/fast-slow.md#L13) ## 目录职责 - **worldbook-service**：世界书的导入、原文版本、检索与可解释选择。Harness 在指定场景通过 Axon 调用它。 [依据](https://github.com/FlowGPT/worldbook-service/blob/3a11e333afd335aeff165e0ccc3654af8e1897d1/src/worldbook/app.py#L85) - **PostgreSQL + pgvector**：同一数据库保存不可变原文版本与向量。修改新增 revision；索引按指定版本显式构建，可重建。 [依据](https://github.com/FlowGPT/worldbook-service/blob/3a11e333afd335aeff165e0ccc3654af8e1897d1/src/worldbook/service.py#L150) - **rules / hybrid**：先按受众、状态等条件过滤；规则或混合检索提供候选，再按优先级、依赖与预算选出可插入的条目。 [依据](https://github.com/FlowGPT/worldbook-service/blob/3a11e333afd335aeff165e0ccc3654af8e1897d1/src/worldbook/service.py#L122) - **apps/emochi**：角色扮演的完整编排：正文、前台工具、后台规划、剧情、记忆、压缩。服务启动文件也在这里。 [依据](https://github.com/FlowGPT/roleplay-harness/blob/80aef3fa5582d8508ecdd1afa206391940ce9502/apps/emochi/main.ts#L1) - **apps/sumi**：独立的图文对话：状态协议、历史分支、快照、图片交付。 [依据](https://github.com/FlowGPT/roleplay-harness/blob/80aef3fa5582d8508ecdd1afa206391940ce9502/apps/sumi/runtime.ts#L1) - **packages/sdk**：@flowgpt/roleplay-harness：通用 Agent、可选快慢编排、注册、任务、观测。可在调用方环境独立嵌入。 [依据](https://github.com/FlowGPT/roleplay-harness/blob/80aef3fa5582d8508ecdd1afa206391940ce9502/packages/sdk/src/index.ts#L1) - **packages/tools**：@flowgpt/agent-core-tools：专家、剧情、记忆、图片等工具。业务选择和注册实际需要的工具。 [依据](https://github.com/FlowGPT/roleplay-harness/blob/80aef3fa5582d8508ecdd1afa206391940ce9502/packages/tools/src/index.ts#L1) - **adapters + packages/llm**：Agent Router 接请求；Axon 提供配置、数据与服务接口；Kaon 执行模型请求。LLM 目录不是第三个独立发布的 npm 包。 [依据](https://github.com/FlowGPT/roleplay-harness/blob/80aef3fa5582d8508ecdd1afa206391940ce9502/docs/sdk/architecture.md#L9) - **config/scenarios**：选择已实现的应用与能力。服务启动时加载场景；模型参数和 Prompt 还来自 ModelConfig。 [依据](https://github.com/FlowGPT/roleplay-harness/blob/80aef3fa5582d8508ecdd1afa206391940ce9502/apps/emochi/scenario-files.ts#L21) - **compat**：旧入口重导出及独立 Image MCP 服务。MCP 只是可选接法，不是所有工具或图片的必经路径。 [依据](https://github.com/FlowGPT/roleplay-harness/blob/80aef3fa5582d8508ecdd1afa206391940ce9502/compat/index.ts#L1) - **examples · test · evaluation · docs**：示例展示接线；测试和评估检查行为；文档说明服务、SDK 与实验。示例不等于线上配置。 [依据](https://github.com/FlowGPT/roleplay-harness/blob/80aef3fa5582d8508ecdd1afa206391940ce9502/README.md#L29) ## 图示取舍 全景图保留应用、入口与公共依赖，并加入独立 Worldbook 服务和其 PostgreSQL / pgvector。Emochi 到 Worldbook 的连接标明经 Axon，不表示直接 HTTP 调用；部分重复返回边省略。Emochi 图突出正文、并行规划和生成后记忆；Story、Worldbook、Compact、DIO 的独立条件在阅读器卡片中展开。Sumi 图合并初始化与历史恢复等步骤，独立画出后台图片交付。 外部服务与实际模型调用经适配器连接；图中的依赖组不表示每个包都直接依赖每个后端。SDK 快慢编排是可单独嵌入的公共能力，不是所有应用请求的必经入口。 ## 交付验证 各图的精确 SHA-256、字节数、9 项校验和视觉检查记录见下方交付回执（生成完成后追加）。 ## 当前交付回执 [精确哈希与验证记录](project-map-receipts.json)。五张图均为 showcase 9/9 校验、0 错误、0 警告；四种桌面尺寸 containment 通过，最小与最大尺寸的明暗截图已经人工查看。新增世界书选择图为 workflow；PNG 来自内置 canonical 导出。总阅读器只做静态 HTML、JavaScript 与本地链接检查，其交互导航未在浏览器实际测试。 [世界书如何选条目与进入 RP：详细代码说明](worldbook-selection-notes.md)。