# 六类分析工具：给出建议，由业务决定采用

**用途：**当你的产品已经有角色、对话或故事材料，需要额外检查“人物有没有突然知道秘密”“承诺有没有忘记”“场面是否该转换”等问题，可以直接调用对应分析工具，不必先接完整 Agent V2。

**交付形态：**`@flowgpt/agent-core-tools` 的公共工具。它们调用宿主提供的模型，产出文本建议和使用信息；全部标记 `advisory: true`，不会自行修改聊天、人物卡、世界书或数据库。

这里的“公共”指包的可复用导出 API。仓库发布配置是 GitHub Packages、`restricted` 访问，接入发布包需要相应读取权限，并不代表公共 npm 可匿名安装。

## 每个工具具体干什么

| 工具与导出类 | 检查什么 | 业务输入例子 | 结果怎样采用 |
| --- | --- | --- | --- |
| `analyze_plot` / `PlotTool` | 主线、当前情节和分支是否需要变化 | “用户拒绝了原定任务，接下来怎么办？” | 返回推进建议；产品决定是否写入剧情计划或下一轮约束 |
| `judge_npc` / `CharacterTool` | 人物身份、数量、动机、知识、位置、出入场与连续性 | “一个新守卫出现，他凭什么认识用户？” | 给人物连续性建议；不自动生成独立 NPC ID 或完整卡片 |
| `audit_knowledge` / `KnowledgeTool` | 事实、秘密、谎言、猜测、证据，以及谁知道什么 | “信封没打开，Mira 能否知道信里内容？” | 明确信息边界，供写作或状态整理采用；不会自动搜索世界书 |
| `simulate_world` / `WorldTool` | 时间经过、位置、期限与镜头外活动 | “用户离开酒馆三天，约定是否过期？” | 给出需要考虑的世界变化建议；不等于 Story 的事件状态引擎 |
| `manage_callbacks` / `CallbackTool` | 承诺、线索、物件、伤势、义务、伏笔和延迟影响 | “借的钥匙还没还，要记住哪件事？” | 提醒持续追踪，不强制马上让伏笔发生 |
| `direct_scene` / `SceneTool` | 视角、镜头、场面与角色自主行动尺度 | “守卫能主动拦路，但能替用户作决定吗？” | 输出场面建议，提示词要求保留用户行动自主权 |

[六工具定义](https://github.com/FlowGPT/roleplay-harness/blob/fa41d220d48327e58d994f936517b23f2f15f658/packages/tools/src/modules/memory/advisory.ts#L18) · [公共导出与工厂](https://github.com/FlowGPT/roleplay-harness/blob/fa41d220d48327e58d994f936517b23f2f15f658/packages/tools/src/modules/memory/index.ts#L1)

## 调用前究竟要准备什么

模型可见参数是 `reason`（为什么咨询）和可选 `focus`（这次重点）。角色资料、历史、已有状态、用户身份等由宿主提供，不能指望专家名称自动带来数据库访问。

默认 RP 上下文包含目标角色、开场白、当前用户输入、用户 Persona、已有状态、压缩摘要与最近可见对话。默认历史投影只取过滤后的最后 9 条 user/assistant 消息；Persona 最多 4,000 字符；状态投影使用 6,500 字符预算。这些是字符投影规则，不是模型完整上下文窗口。

如果你的业务需要完整世界书条目、外部事实或更长历史，先由宿主取回，再通过 `compileContext` 自定义 user message。系统岗位提示词由调用者另行传入。编译器是同步格式化函数，本身不做网络检索。

[上下文与模型适配接口](https://github.com/FlowGPT/roleplay-harness/blob/fa41d220d48327e58d994f936517b23f2f15f658/packages/tools/src/contracts.ts#L79) · [默认输入投影](https://github.com/FlowGPT/roleplay-harness/blob/fa41d220d48327e58d994f936517b23f2f15f658/packages/tools/src/modules/memory/advisory.ts#L169)

## 最小接线片段

下面是**宿主接线片段**，`context`、`model`、`systemPrompt` 必须由业务准备，不是安装包自动提供。

```ts
import { createAgentCoreTool } from '@flowgpt/agent-core-tools';

const tool = createAgentCoreTool({
  name: 'audit_knowledge',
  modelConfigId: 'your-knowledge-model',
  modelCallTimeoutMs: 15_000,
});

const result = await tool.execute({
  context, model, prompt: systemPrompt,
  arguments: { reason: '核查信息边界', focus: 'Mira 是否看过未打开的信' },
  signal,
});
if (!result.ok) throw new Error(result.error);
// result.result 是分析文本。这里交给业务采用，不会自动写数据库。
```

需要让自己的 Agent 选择工具时，用 `/pi` 的 `toPiTool(tool, prepare)` 包装，再加入 Pi 的工具列表。`prepare` 负责绑定真实业务上下文、模型和提示词；包装层校验 `{reason, focus}` 参数并把失败转换为工具异常。直接调用适合固定流程，注册后由模型选择适合动态流程。

参数校验由 `toPiTool` 包装执行，`prepare` 负责准备业务材料；如果绕过包装直接调用 `.execute`，应由宿主检查工具参数，不要把暴露给模型的 JSON Schema 当作该直调入口已自动执行的校验。

[完整假模型直调示例](https://github.com/FlowGPT/roleplay-harness/blob/fa41d220d48327e58d994f936517b23f2f15f658/examples/sdk/02-direct-tools.ts#L1) · [模型选择工具的完整示例](https://github.com/FlowGPT/roleplay-harness/blob/fa41d220d48327e58d994f936517b23f2f15f658/examples/sdk/03-agent-tools.ts#L1) · [Pi 工具适配](https://github.com/FlowGPT/roleplay-harness/blob/fa41d220d48327e58d994f936517b23f2f15f658/packages/tools/src/pi.ts#L9)

## 配置、保存和失败边界

| 项 | 实际行为 |
| --- | --- |
| 调哪个模型 | `modelConfigId` 由宿主模型适配器解释；SDK 不自动查公司配置中心 |
| 岗位提示词 | 每次调用的 `prompt`；不是六工具包内自带完整产品提示词 |
| 模型重试 | 通常最多初次＋2次重试；取消、内容过滤、已发生恢复或特定上下文错误可提前停止 |
| 结果长度 | 默认整理为最多 5,000 字符。`contextGovernance` 的 `enforce` 下超出结果额度会返回失败，而非照常采用 |
| 返回 | `{ok, tool, result?, error?, usage?}`；Promise 正常 resolve 仍可能 `ok:false`。`contextGovernance: enforce` 的计数不可用／上下文溢出错误会向上抛出，宿主还需要处理 Promise reject |
| 何时保存 | 工具不保存。产品可以把建议给 Director、给下一步工具、给人工，或自行校验后写库 |
| 何时生效 | 取决于宿主把建议放到哪个后续输入或存储里；不会自动影响正在并行生成的回复 |

**具体闭环：**业务提交“未打开的信”及现有记录 → `audit_knowledge` 返回“没有依据得知信中秘密” → 业务把它作为下一次写作约束 → 下一次生成遵守该信息边界。如果只调用工具而丢弃结果，就不会改变产品行为。

[重试与失败](https://github.com/FlowGPT/roleplay-harness/blob/fa41d220d48327e58d994f936517b23f2f15f658/packages/tools/src/modules/memory/advisory.ts#L127) · [输出、长度与保存边界](https://github.com/FlowGPT/roleplay-harness/blob/fa41d220d48327e58d994f936517b23f2f15f658/packages/tools/src/modules/memory/advisory.ts#L244)

<details>
<summary>独立工具配置的必填项与治理边界</summary>

`name`、`modelConfigId`、`modelCallTimeoutMs` 都是 `AgentCoreToolConfig` 的必填项。这里没有独立工具默认 180 秒的构造规则；180 秒是普通 V2 应用配置的默认值，客户直调用多少必须自己提供。`compileContext`、`contextGovernance`、`onDiagnostic`、`shouldStopRetries`、`isContextGovernanceFailure` 可选。

`contextGovernance` 若启用，需给出 `mode: "shadow" | "enforce"`、`safetyMarginTokens`、`maxToolResultChars`。工具把输入窗口预算要求传给宿主 `model.complete`；宿主模型适配器需要实际实现计数与拦截，不能因为传了对象就认定第三方模型端已经受控。工具自己会检查返回文本长度：shadow 仅记录诊断，仍按默认最多 5,000 字符整理；enforce 超配额返回 `tool_result_oversized`，未超限则保留完整结果。

类导出分别为 `PlotTool`、`CharacterTool`、`KnowledgeTool`、`WorldTool`、`CallbackTool`、`SceneTool`，根入口同时导出 `createAgentCoreTool`；`createAgentCoreToolWithContext` 要求提供 `compileContext`。角色型默认 context 的限制是材料投影，并不限制客户自定义编译器可提供的全部业务字段。

[独立工具必填配置](https://github.com/FlowGPT/roleplay-harness/blob/fa41d220d48327e58d994f936517b23f2f15f658/packages/tools/src/modules/memory/advisory.ts#L43) · [enforce和shadow输出处理](https://github.com/FlowGPT/roleplay-harness/blob/fa41d220d48327e58d994f936517b23f2f15f658/packages/tools/src/modules/memory/advisory.ts#L291) · [类与工厂导出](https://github.com/FlowGPT/roleplay-harness/blob/fa41d220d48327e58d994f936517b23f2f15f658/packages/tools/src/modules/memory/index.ts#L1) · [根入口、Pi适配与发布边界](https://github.com/FlowGPT/roleplay-harness/blob/fa41d220d48327e58d994f936517b23f2f15f658/packages/tools/package.json#L12)

</details>