插件与 profile 配置
全部配置字段：插件级、profile 级、引擎配置段
本文是配置字段的完整清单，以仓库当前源码为准（packages/koishi-plugin-ishiki/src/）。字段含义的展开见各指南。
插件级配置（koishi.yml 的 ishiki 段）
来源：src/index.ts 的 Ishiki.Config。
Prop
Type
扩展插件的配置见各包说明。profile 通过 extends.<名称>.config 传入实例配置。
profile 级配置（profile.yml）
来源：src/profile/config.ts 的 ProfileConfig。
Prop
Type
同目录 instructions 列出的文件：追加到系统提示词末尾；memory/（v3 上下文且 memoryBlocks: true 时）：记忆块；mcp.json（mcp-client 扩展）：见参考：mcp.json。
narrative 引擎配置
narrative 引擎来自独立插件 koishi-plugin-ishiki-narrative，安装并启用后在 profile 中同时设置 context.engine: narrative 与 toolcall.engine: narrative。完整用法见管理上下文窗口。
| 字段 | 类型 | 默认值 | 含义 |
|---|---|---|---|
context.narrative.maxTokens | number | 32000 | 剧本正文的估算 token 预算；非正数关闭自动压缩 |
context.narrative.refillRatio | number | 0.8 | 压缩后目标比例，范围 (0, 1] |
context.narrative.recentEntries | number | 12 | 近期原始证据条数；未读事件、当前轮次证据及关联附件额外保留 |
toolcall.narrative.decoderModel | string | 复用 model | Action Decoder 模型引用，可用模型组 |
toolcall.narrative.replyModel | string | 复用 model | Replyer 模型引用，可用模型组 |
toolcall.narrative.narratorInstructions | string | 无 | 追加作者续写指令 |
toolcall.narrative.decoderInstructions | string | 无 | 追加行动解码指令 |
toolcall.narrative.replyerInstructions | string | 无 | 追加可见表达指令 |
主 model 负责 Narrator 和历史压缩。每个内部阶段沿用取消信号、采样设置和输出 token 上限；停止序列、返回格式、请求头与 provider 私有选项不跨角色转发，角色使用自己的 JSON 或工具约定及模型网关配置。返回用量为各阶段用量之和，reasoning 只包含显式剧本，不包含底层模型的隐藏推理。
failover
Prop
Type
模型是组名、或 attempts > 1 时启用重试包装器；组候选按声明顺序尝试，熔断中的候选跳过。
codemode
开启后，业务工具通过 QuickJS 程序组合调用。direct 可以保留额外的模型直接调用入口；send_message 同时支持直接与程序调用，finish、wait 保持直接调用。
Prop
Type
脚本内用 searchTools(query, { limit }) 按名称和描述发现业务工具，再用 describeTool(name) 读取完整声明。工具目录在一次脚本执行期间固定。
pacing
一轮（一次唤醒）的步数预算。maxSteps 是硬上限：core 的循环走到这一步数就不再请求模型，这一轮到此结束。为免整轮没有任何回应，runtime 在每次请求前按剩余步数临时附一句提醒，提醒只进当次请求，不写进事实流。
Prop
Type
收尾提醒报出剩余步数，要求模型停止开新工作、把已完成与未完成的部分折成一条 send_message，并在同一步声明 wait 以便下次继续；收尾窗口内每步都给。进度提醒要求模型用一条 send_message 加 continue: true 报一句正在做什么，然后继续同一轮。两者互斥，收尾优先。
typing
Prop
Type
延迟按消息文本长度计算并带随机抖动，逐条消息之间等待。
attachment
Prop
Type
imageInput 控制主模型的图片输入总闸。messageImageInput 在这个总闸开启时决定平台消息图片是否自动进入上下文；该规则覆盖所有平台消息。visionModel 供 read({ url: "...?question=..." }) 独立识图，主模型无需支持图片输入，识图结果以文本返回。视觉模型或模型组里的每个候选都必须声明 input: [text, image]。
每个附件媒体项带 lifetime，默认 once，所有入口一致：平台图片、直接 MCP 返回、read 返回的媒体都只嵌入一次。imageInput: false 时不嵌入图片，生命周期一律按 once 处理，附件消息只说明未提供的原因。模型可用的覆盖路径只有两条：codemode 最终 attachments[] 里的媒体项可以带 lifetime；imageInput 开启时，直接调用的 read 接受 lifetime（codemode 内的 read 不提供）。
once：携带图片的模型响应成功持久化后才消耗展示机会；失败或中止的 step 不消耗展示机会，后续请求重试。recent：最近查看过的图片继续可见。每次请求投影前统计活动recent图片总数（含未查看），超出recentImageCount的差额按imagePruneBatchSize向下取整成批，从最旧的已查看图片开始移除；未查看的图片永远不会被移除。默认值3与2意味着出现第 5 张活动图片时才触发移除，至多移除 2 张最旧的已查看图片；已查看不足 2 张时只移除现有的。来源记录被移除时同样释放，包括交付状态已经持久化的图片。retain：来源记录仍在活动上下文时每轮都参与选择，由上下文引擎移除来源记录决定何时释放；本次请求预算不足时暂不携带，即使此前已持久化过交付状态。
其余配额是每请求一份，平台与工具附件共用；容量不足的图片本次请求不嵌入、不消耗展示机会。硬预算下未被选中的已查看 recent 图片会释放，不再参与后续选择；未查看的图片只等待容量，retain 本次暂不携带后仍可再试。未发生生命周期移除或选择变化时，投影结果保持消息顺序、ID 与时间戳不变，以复用 provider 的前缀缓存；字节层面的复用只对 immutable 资源成立。终止性判定（能力关闭、媒体类型或编码不支持、图片自身字节超过单图上限、图片自身字节超过单次请求累计上限、图片尺寸超限）只输出一次原因，并随成功响应持久化；资源不可用与请求剩余容量不足属于本次请求未提供，会在后续请求重试。
maxImageRenders 已移除，替换为生命周期机制与 recentImageCount / imagePruneBatchSize。profile 里仍写旧字段时，resolveProfile 直接报 attachment.maxImageRenders was removed; use image lifetimes (once, recent, retain) and attachment.recentImageCount/imagePruneBatchSize。
assets
Prop
Type
入站 platform 媒体先注册为 asset://<UUID v7>。符合条件的 HTTP 来源在注册后立即执行 HEAD 探测和有界 GET，下载后按实际字节识别媒体类型，并以 <uuid>.<扩展名> 保存字节、以 <uuid>.metadata.json 保存元数据。HEAD 或 GET 不满足条件时保留引用，模型显式调用 read 仍可使用独立读取上限下载。清理只删除过期的 asset 字节与元数据，正在读取的资源会推迟到读取结束；artifact 不受影响。
引擎配置段
三族引擎的 engine 字段取值与对应配置段：
context
| engine | 配置段 | 字段 |
|---|---|---|
standard | standard | maxTokens: number（默认 32000）、refillRatio?: number（0–1，默认 0.8） |
v3 | v3 | maxMessages: number（默认 50）、keepFullTurnCount: number（默认 2）、memoryBlocks: boolean |
wakeup
| engine | 配置段 | 字段 |
|---|---|---|
standard | standard | direct/atSelf/quoteSelf: boolean（均默认 true）、keywords: string[]（默认空） |
willingness | willingness | base: 12、atMention: 100、isQuote: 15、isDirectMessage: 40、imageGain: 8、keywords: []、keywordMultiplier: 1.2、defaultMultiplier: 1、maxWillingness: 100、initialWillingness: 0、decayHalfLifeSeconds: 600、hotWindowSeconds: 15、warmWindowSeconds: 60、hotDecayWeight: 0.3、warmDecayWeight: 0.7、probabilityThreshold: 55、probabilityAmplifier: 0.04、replyCost: 35、atMentionForce/quoteForce/directForce: false、participationWindowSeconds: 60、participationInfluence: 0.5 |
jev | jev | model（必填，models.yaml 中的 type: decision 模型引用）、threshold: 0.7、addressedThreshold: 0.7、cooldownMs: 30000、globalCooldownMs: 60000、channelStyles: {}、minIntervalMs: 2000、debounceMs: 800、maxWaitMs: 2500、conversationMs: 120000、contextMaxAgeMs: 900000、decisionMaxAgeMs: 10000、participationWindowMs: 300000、maxParticipation: 0.25、minParticipationTurns: 6、maxConsecutiveReplies: 4、historyMessages: 16、contextChars: 6000、instruction: ""、interests: []、botNames: []、style: natural、prefilter: safe、rules（默认 { direct: true, atSelf: true, quoteSelf: false, keywords: [] }） |
jev 的模型判定调用固定使用 8 秒超时，不提供 timeoutMs 配置。
toolcall
| engine | 说明 |
|---|---|
native | 模型原生 function call，无配置段 |
v3 | JSON OUTPUT 协议，每步输出 thoughts（observe/analyze_infer/plan 三段）+ actions |
hermes / qwen3coder / morph-xml / yaml-xml | 对应文本输出协议，由解析引擎从纯文本中提取调用，无需模型原生支持 |
协议引擎均无 profile 级配置段。
默认 profile 示例
仓库 packages/koishi-plugin-ishiki/resources/profile.example.yml 是带逐段注释的官方示例，提供 channel、cross、willingness、jev 的配置示例。实际字段与默认值以各引擎和 profile 的 Schema 为准。
旧字段迁移
早期版本（如 boilerplate 中的 Cat 示例）使用过 scenes、innerThoughts、description、context.standard.maxChars 等字段，当前 Schema 不再支持：场景拆分由 channels 认领承担，字符预算改为 maxTokens，innerThoughts 已移除（内心独白始终私有）。加载含未知字段的 profile 不报错（字段被忽略），但行为以当前默认值为准；建议迁移。