# 原子能力：可以拿什么做二次开发

这里按“要完成的事情”找能力。每项都会说明它是独立包、服务接口、应用内模块，还是配置入口。**下载仓库、安装 SDK、接入已经部署的业务服务，是三种不同的接入动作。**安装 SDK 不会自动连到公司的模型、配置中心、世界书或数据库。

## 能力目录

| 要完成什么 | 能力与入口 | 现成提供的形态 | 接入者还要准备什么 |
| --- | --- | --- | --- |
| 写角色正文，或按段落配合图片 | [Actor 与前台工具循环](atoms-generation.md) | `apps/emochi` 内的正文运行时与工具接线 | 角色、历史、模型配置、Prompt 与 Axon 等应用依赖；不是 Core Tools 根入口导出的独立 Actor |
| 分析剧情、人物、知识、时间、伏笔、场面 | [六类分析工具](atoms-specialists.md) | `@flowgpt/agent-core-tools` 公共导出 | 提供真实材料、系统提示词和模型适配器；自己决定如何采用建议 |
| 让世界事件与剧情计划运转 | [Story 工具](atoms-story.md) | `@flowgpt/agent-core-tools/story` 子入口 | 世界/叙事状态、事件、模型与存储接法；完整产品的正文确认流程需要宿主编排 |
| 导入设定、选出本轮需要的内容 | [世界书服务](atoms-worldbook.md) | 独立 REST 服务＋仓内 Axon 适配；现成接线限专用 `agentic-v2-worldbook` 场景 | 租户与业务授权、书籍版本、索引、Prompt 关联、模型注入位置；Story、Sumi、前台工具循环当前不能直接同开，需另写适配 |
| 读写 JSON 记忆，或接入日记、记忆表及外部记忆 | [记忆与状态](atoms-memory.md) | `/memory` 子入口的 `get_memory`、`update_memory`；另有应用内 Axon / Hinos 适配 | JSON 工具需要绑定身份的存储、原子版本检查和字段校验；应用接法另需对应服务、来源配置及模板引用 |
| 在长对话里压缩历史、控制输入长度 | [历史压缩 Compact](atoms-compact.md) | 当前为应用运行时与 Scenario 配置 | 原始历史及消息锚点、计数服务、压缩模型、检查点持久化 |
| 把已取回的资料放到模型输入中 | [上下文组装](atoms-context.md) | SDK `placeContextBlocks`；分析工具自定义编译器 | 自己取资料、定义插入位置、控制预算；组装函数不检索也不保存 |
| 生成独立图片，或给聊天正文配图 | [图片与视觉状态](atoms-images.md) | `/image` 资产工具；另有应用内 Imagine 与图片 MCP 接线 | 图片后端、任务归属、审核结果、展示与保存；两种生图入口参数不同 |
| 持续改变角色后续行为 | [DIO 长期指令](atoms-instructions.md) | 应用内外部服务适配器与前台 `schedule_dio` 动作 | DIO 服务、授权、目标 Prompt、后续有效 Prompt 的读取链 |
| 做自己的 Agent、工具循环、快慢协作，或固定串联工具 | [编排与扩展](atoms-runtime.md) | SDK `Agent` / `SlowTurnRuntime` / `FastSlowRuntime` 与 Tool Hook；另有仓内 Profile＋Planner＋Executor 固定流程 | 自己的提示词、工具执行器、输入采用与保存规则；固定流程需仓内组装，当前 Router 的 Scenario JSON 不直接装载任意节点图 |
| 生成用户可以选择的下一句话 | [下一句建议](atoms-auto-reply.md) | V2 应用 `auto_reply` 请求入口 | 已保存的助手消息、独立模型配置、业务前端的选择与发送动作 |

## 包、源码与服务怎样对应

| 入口 | 这次固定源码中的版本或位置 | 使用方式 |
| --- | --- | --- |
| SDK | `@flowgpt/roleplay-harness`，包配置版本 `0.3.0` | 在调用方进程执行。提供通用 Agent、可选快慢运行时、注册表、上下文放置、观测等 |
| Core Tools | `@flowgpt/agent-core-tools`，包配置版本 `0.2.1` | 可直接调用分析工具；`/memory`、`/story`、`/image`、`/pi` 按子入口导入 |
| Agent V2 / Story 应用实现 | `apps/emochi`＋`adapters` | 仓内应用接线，需相应业务服务和配置。两个 npm 包没有整体导出这套产品 |
| Worldbook | `worldbook-service` 独立仓库 | 部署服务或接入已授权服务地址，经 REST / 业务适配调用 |

两个包配置的发布目标都是 `https://npm.pkg.github.com`，访问级别 `restricted`，要求 Node.js ≥22。实际安装先取得 registry 读取权限，再确认要用的功能已经进入所安装版本。**主干中新增的 Slow gate 不应仅凭 `package.json` 仍写 0.3.0 就认定 0.3.0 发布包包含它。**本页按固定源码说明能力；交付具体发布包时须对照该包版本与构建身份。

[仓库、包与应用的归属](https://github.com/FlowGPT/roleplay-harness/blob/fa41d220d48327e58d994f936517b23f2f15f658/README.md#L3) · [SDK 包入口](https://github.com/FlowGPT/roleplay-harness/blob/fa41d220d48327e58d994f936517b23f2f15f658/packages/sdk/package.json#L1) · [Core Tools 子入口与安装条件](https://github.com/FlowGPT/roleplay-harness/blob/fa41d220d48327e58d994f936517b23f2f15f658/packages/tools/package.json#L1) · [SDK 真实导出](https://github.com/FlowGPT/roleplay-harness/blob/fa41d220d48327e58d994f936517b23f2f15f658/packages/sdk/src/index.ts#L1)

## 开关写在它控制的能力下面

`preActorDirector` 控制前台工具编排，`compact` 控制历史压缩，`storyV1` 选择 Story 产品流程。它们不在“模型可以调用的工具名”里。每个能力页都列出对应字段、默认行为、开启条件、互斥限制和生效时机。

固定流程的 `executionGraph` 是仓内 `ScenarioProfile` 的程序契约；现有 Router 的场景配置表不是任意工具图编辑器。需要固定串联业务工具时，按 [编排与扩展](atoms-runtime.md) 的源码接法注册执行器、定义节点，并把结果送入实际模型输入。

二开前至少走通一次：提供实际输入 → 调用能力 → 检查返回 → 按业务规则采用或拒绝 → 保存 → 再发一轮读取验证。某项工具 `ok:true`，只证明该次工具返回成功，不自动证明正文被接受、图片已展示或状态已持久化。