模型工具与资源协议

内置工具Copy Anchor Link

send_messageCopy Anchor Link

发送可见消息，模型对用户说话的唯一通道。

输出：成功 { ok: true, ids: string[] }；失败 { ok: false, error: { name, message }, sent, failedAt }（failedAt 是第几条失败的，从 0 计）。

行为要点：

• 消息里的媒体 src 支持 asset://、artifact://、local://、workspace://，解析为内联数据发送；解析失败的媒体被剔除并报告，不阻塞消息。
• cross 模式必须带 target，且目标必须在 profile 认领范围内。
• 打字延迟按 typing 配置逐条计算（中文按 charPerSecond、拉丁按其 1.5 倍，带抖动）。
• 模型直接调用 send_message 成功且未设置 continue: true 时，本轮结束；显式调用 finish 或 wait 也会结束本轮。

readCopy Anchor Link

读取资源，输入 { url }；imageInput 开启且在 codemode 之外直接调用时，还可带 lifetime。文件型 URL 支持行范围和元数据视图。图片 URL 可带 question 查询参数，交给 attachment.visionModel 独立识图：

read({ url: "artifact://bash/output.txt:1-200" })
read({ url: "asset://0190f9f3-3ff8-7000-8000-000000000001" })
read({ url: "asset://0190f9f3-3ff8-7000-8000-000000000001?question=图里写了什么？" })
read({ url: "workspace:///home/workspace/report.txt" })
read({ url: "local://notes.txt?view=meta" })

原始返回值是可序列化的判别联合：

• FileScheme 的行选择器为 :N、:start-end 或 :start+count，位于 query 之前。?view=meta 只读取元数据，不会拉取 asset 字节。
• question 只由 read 消费，其他 query 参数仍属于资源 URL。问题为空、未配置 attachment.visionModel、资源不是图片或视觉模型请求失败时，工具返回对应的结构化错误。识图结果是一条 text 结果，原图不会附加到主模型上下文。
• FileScheme 文本的 source 包含 { url, offset, line, column }，记录来源与位置；正文不混入展示尾注。
• codemode 内取得完整结果，不受模型展示预算截断；仍受 SDK 的传输、结果大小和执行限制约束。
• 传给其他工具时按其输入契约取 result.text 或 result.data；只有明确支持该 scheme 的工具才能直接接收资源 URL。最终的 attachments 可携带媒体节点。
• imageInput 开启时，模型直调 read 可传 lifetime（once / recent / retain）选择返回媒体的生命周期；未知值报 invalid_attachment_lifetime，不会静默退回默认值。codemode 内的 read 不接受该参数，沙箱里请把 lifetime 写进最终 attachments[] 的媒体项。其他直接返回图片的工具使用默认 once。
• 模型可见的文件页使用原来源续读；普通 handler 返回的超长内容先固化为 artifact。按结果里的完整 Continue URL 再 read，即可继续读取，包括超长单行的剩余部分。其他 scheme 自行解释完整 URL，不继承文件语法。

waitCopy Anchor Link

声明下一次自动醒来的条件。它与 finish、send_message 同属收尾动作：调用它即结束当前轮次（和 send_message 一起调用时同样结束，模型不必为声明条件多跑一步）。常驻工具，只留模型目录，不受 codemode 的 direct 名单影响，也不进沙箱。

两个窗口中先满足的条件生效，每轮采用最后一次调用的声明。条件在轮次结束时启用，触发一次后清除；返回值回显当前声明，空调用返回 none: true。条件保存在内存中，重启后清除。持续的调度策略可以由自定义唤醒引擎管理，显式 wake 也可以独立触发运行。完整语义见调整唤醒行为。

codemodeCopy Anchor Link

启用后，模型可以编写 JS 程序，在 QuickJS 沙箱中组合调用业务工具。codemode 默认关闭，开关与配额见插件与 profile 配置。

• 程序内 await tools.name(input) / await tools["server_tool"](input) 返回工具的原始 JSON 安全值。中间数据由程序处理，最终返回值进入后续模型上下文。
• direct 名单内的工具保留模型直接调用入口，其余业务工具由程序调用；send_message 同时支持直接与程序调用，finish、wait 保持直接调用。
• 传媒体出沙箱的唯一方式：返回值顶层带 attachments 数组，元素是媒体块（MCP 的 image/audio 块、read 的 file 节点、内嵌 MCP resource）。数组外的一切按普通 JSON 处理。媒体项可带 lifetime（once 默认、recent、retain）；沙箱内部工具返回的原始媒体不开始计算生命周期，只有最终 return 中的 attachments[] 项进入图片生命周期管理。
• 每次调用是一个独立程序；需要分步传递的数据放进返回值，下一步以观察形式看到。

finishCopy Anchor Link

结束当前轮次：输入 { reason? }，输出 { ok: true }。收尾动作应由模型直调发起。

资源 URL 方案Copy Anchor Link

每个 runtime 拥有独立资源中心，URL 在该中心已注册的 scheme 中解析。asset / artifact / local 是内置保留方案，表中其余方案由对应扩展提供。扩展可以注册 HTTP(S) 等新 handler，继续通过 read 访问资源。

FileScheme 自行解析行选择器、?view=meta 与续读 offset；资源中心只按 scheme 路由完整 URL。文件名中的字面冒号使用 %3A。native 后端的 workspace URL 使用实际宿主路径；Windows 可写为 workspace:///d/work/report.txt，盘符段的字面冒号也需编码为 %3A。

普通 URL 可以表示当前资源；artifact 表示已固化内容快照。原来源续读不承诺跨次读取一致性。

文本预算Copy Anchor Link

模型可见的文本共用 2000 行 / 30,000 个 UTF-16 code unit 的预算，正文与所有续读说明一起计入。截断不拆开 Unicode 代理对，不丢弃单行余文。

Continue URL 中的 offset 是请求范围内已消费的 UTF-16 code unit 数；URL 保留原来的行范围和 view。继续读取时使用返回的完整 URL，以保留范围与精确续读位置。读到范围末尾后不再生成 Continue。

read 返回请求范围内的完整内容，传输与执行仍受现有 SDK 限制约束。

工具结果的统一出口Copy Anchor Link

工具原生 toModelOutput 先转换结果，再由统一资源出口处理：

• 普通超长内容：完整表示归档为 artifact，模型看到前缀与续读 URL。归档包含媒体替换后的完整展示内容，不另外保存 execute 原始对象。
• FileScheme 文本：使用已有来源分页，不把读取页面重新归档。
• 媒体：固化新数据或复用已固化引用，替换为 [attachment: <url>; <mediaType>; …]，另写附件消息，下一 step 按能力、生命周期与预算投影。媒体项默认 once，携带它的模型响应成功持久化后才消耗展示机会；实时文件引用作为历史附件时保存快照。
• codemode 内部工具：不经过这条统一出口；只有最终返回值进入处理，显式媒体字段为 attachments。