Playground 工具

开启工具后，Playground 的回复就成了一个智能体循环：模型可以使用内置工具；每一轮它先流式输出文字，它调用的工具依次运行（需要批准的先等你批准），结果返回给模型，如此往复，直到某一轮不再调用工具为止。回复中的每次调用都显示为一张可以展开的卡片。

开启工具复制锚点链接

对话只保存它与设置的差别（自己开启了哪些工具、关闭了哪些工具）。新对话会重新按设置开始。

六个工具复制锚点链接

相对路径从工作区开始解析（见下文的“工作区”）。不论工具返回什么，发给模型的最多 32,000 个字符；更长的输出会截去中间部分，保留开头和结尾。

读取文件（read）复制锚点链接

• 返回带行号的文本（L12: …）。默认从开头读取 2000 行，模型可以指定 offset（从 1 开始）和 limit（最多 10,000）分段读取。
• 超过 500 个字符的行会被截断；一次读取最多返回 60,000 个字符，并说明从哪里继续。
• 路径是文件夹时返回其内容列表：文件夹在前，最多 500 项。
• 二进制文件（开头部分含有 NUL 字节）会被拒绝。

编辑文件（apply_patch）复制锚点链接

接受 Codex apply_patch 格式的补丁，在 Codex 中会用这个工具的模型在这里也会用：

*** Begin Patch
*** Add File: hello.txt
+Hello world
*** Update File: src/app.py
*** Move to: src/main.py
@@ def greet():
-print("Hi")
+print("Hello, world!")
*** Delete File: obsolete.txt
*** End Patch

• 写入任何内容之前，会先对照现有文件算出整个补丁的结果：只要有一处无法应用，就不会修改任何文件。
• 文件必须是 UTF-8 文本。换行符保持原样（CRLF 文件仍是 CRLF），文件末尾总有换行。
• 结果列出新增（A）、修改（M）和删除（D）的文件。
• 补丁涉及工作区外的文件（或把文件移到工作区外）时，需要针对工作区外文件的批准：更改工作区外的文件？

运行命令（shell）复制锚点链接

• 用 bash -c 运行命令（没有 bash 时用 sh -c，Windows 上用 PowerShell），默认在工作区中运行，模型可以用 workdir 指定其他目录。
• 等待命令结束：默认 60 秒，最长 10 分钟。超时的命令连同它启动的所有进程一起被停止，并报告超时（退出码 -1）。
• 返回退出码、耗时和输出（包含标准错误）。命令没有输入（标准输入已关闭），分页器和颜色都已关闭（PAGER=cat、NO_COLOR=1、TERM=dumb、GIT_TERMINAL_PROMPT=0）。
• 对于持续运行或需要输入的命令，模型会被告知改用后台命令。

后台命令（exec_command、write_stdin、kill_session）复制锚点链接

• exec_command 启动命令并等待一会儿（默认 10 秒，范围 0.25–30 秒）。如果命令已结束，返回退出码和输出；否则命令作为一个会话继续运行，并返回目前为止的输出和会话 ID。
• write_stdin 向会话输入内容（用 \n 表示回车），并返回新的输出，写入后默认等待 0.25 秒；不输入任何内容时只等待新输出（默认 5 秒，最长 2 分钟）。它会说明命令是否仍在运行，或给出退出码。
• kill_session 停止会话及其启动的所有进程，并返回最后的输出。
• 每个会话最多保留 1,000,000 个字符的未读输出（超出部分丢弃中间）；颜色控制码会被去掉。
• 整个服务端同时最多运行 16 个后台命令。会话属于启动它的对话，该对话被删除或服务停止时会随之停止。

只有 exec_command 可能需要先询问；write_stdin 和 kill_session 作用于已经批准过的命令。

网页搜索（web_search）复制锚点链接

• 使用 DuckDuckGo 的轻量页面（无需密钥），或使用 SearXNG 地址（playground.search_url）中设置的 SearXNG 实例，该实例需要开启 JSON 格式。
• 默认返回 8 条结果（最多 20 条），每条包括标题、地址和摘要。
• DuckDuckGo 会限制请求频率；不再响应时稍等片刻，或改用 SearXNG。

读取网页（web_fetch）复制锚点链接

• 读取公开的 http:// 或 https:// 地址（未写协议时补上 https://），返回最终地址、标题和内容。HTML 会转换为 Markdown，保留标题、段落、链接、列表、代码和表格，去掉脚本、样式、导航和表单，并优先取页面的主要内容。
• 只读取文本（HTML、纯文本、JSON、XML、RSS 等）；最多下载 5 MB，返回 60,000 个字符。
• 本地和私有地址会被拒绝：localhost、以 .localhost、.local 或 .internal 结尾的名称，以及解析到回环、私有、链路本地、保留或多播地址的任何名称。每次重定向（最多 5 次）都会重新检查。包含用户名或密码的地址也会被拒绝。这样模型就读不到保存着你账号凭据的网关本身，也读不到你网络中的其他设备。

两个网页工具都按网关的网络设置（包括代理）访问外网（见网络）。

工具何时先询问复制锚点链接

审批模式决定哪些调用要等你批准。新对话按 设置 › 工具 › 工具如何运行 › 工具何时先询问 开始；每个对话可以单独选择。

搜索和读取网页从不询问，读取工作区内的文件也不询问。

输入框中的盾牌菜单复制锚点链接

对话至少开启了一个工具时，输入框中 工具 旁会出现一个盾牌。它显示该对话的模式（询问、自动，或红色的 完全访问），点开 工具何时先询问 可以只为这个对话更改模式。回复进行中也可以更改：新模式从下一次工具调用起生效。新对话会重新按设置开始。在手机上，盾牌只显示图标。

批准调用复制锚点链接

需要询问的调用会停在 等待批准 状态并自动展开，显示它将要做什么（命令，或标出增删行的补丁）以及一个问题：

可以选择：

• 允许：运行这一次调用。
• 始终允许：运行这次调用，并且在此对话中运行同类调用时不再询问。“同类”指同一个工具开关，且工作区内和工作区外分开计算：始终允许工作区内的编辑，并不允许工作区外的编辑。这一许可持续到服务重启，删除对话时也会被清除。
• 拒绝：跳过这次调用。模型会被告知你拒绝了它，除非你要求否则不要再试；卡片显示 已拒绝。

调用最多等待 10 分钟，没有答复视为拒绝。停止回复会同时取消正在等待的调用。

工具卡片复制锚点链接

每次调用在回复中占一行：图标、动词和作用对象（读取 路径、编辑 文件、运行 命令、启动 命令、查看 或 输入到 会话 n、停止 会话 n、搜索“关键词”、打开 地址），然后是状态：

点击卡片可以展开：发送的命令、补丁或参数，以及返回的结果。两轮之间，回复处显示 处理中…。

在回复进行中补充说明复制锚点链接

开启了工具的回复运行期间，你可以在不停止它的情况下补充内容。输入框提示“补充说明，模型会在下一步读到…”；输入后按 Enter（或点按钮，此时为 发送给正在进行的回复）。

• 你的消息以淡色显示在回复下方，并标注 当前步骤完成后读取。模型在下一轮开始时（当前调用完成后）读取它，之后它会出现在回复中被读取的位置。
• 在模型刚好收尾时发送的消息，会让回复再继续一轮来回应它。
• 如果回复已经结束，消息会放回输入框（“回复已经结束，你的消息已放回输入框。”），你可以把它作为新消息发送。如果回复在读取之前被停止或失败，文字同样会回到输入框。
• 输入框为空时，按钮仍是 停止；Esc 总是停止回复。

输入框上方的后台命令复制锚点链接

对话的工具通过 exec_command 启动、仍在运行的命令列在输入框上方（后台命令）：显示命令、运行中 和一个停止按钮（停止 命令），它会停止该命令及其启动的所有进程。这些命令在两次回复之间持续运行，直到模型或你停止它们、对话被删除或服务停止。

工作区复制锚点链接

工作区是工具的起点：相对路径在这里解析，shell 和后台命令默认在这里运行（除非模型指定了其他目录）。它在 设置 › 工具 › 工具如何运行 › 工作区 中设置（playground.workspace，支持 ~）；留空时使用数据目录中的 workspace 文件夹（见数据目录与路径）。开启工具的回复第一次运行时自动创建。

工作区是审批模式的分界线：在 先询问 和 仅在工作区外询问 下，读取或更改工作区外的文件都会询问。但它不是命令的边界：命令可以 cd 到任何地方，操作运行 Hoshimi 的用户能操作的一切。

轮数上限复制锚点链接

每条回复的工具调用轮数（playground.max_steps，1–500，默认 50）限制一条回复最多进行多少轮工具调用。达到上限后，会再请模型回答一次，但不再提供工具，让它用已有信息作答。如果它仍然调用工具，这些调用不会运行（卡片显示 已停止），回复中注明“此回复已达到 n 轮工具调用的上限。”

停止复制锚点链接

停止（或 Esc）立即结束回复。正在运行的 shell 命令会连同其启动的进程一起停止；等待批准的调用被取消；尚未运行的调用标记为 已停止。回复到此为止说过和做过的内容都会保留。后台命令会继续运行：请在输入框上方停止它们。

安全复制锚点链接

没有沙箱。工具以运行 Hoshimi 的用户身份在那台机器上运行，能访问它的文件、凭据和网络。

• 只有在 先询问 模式下，你才能在每条命令、每次文件更改发生前看到它。批准前请逐一看清楚。
• 仅在工作区外询问 会不经询问运行任何命令。命令并不局限于工作区，所以在这个模式下，模型可以修改或删除该用户能访问的任何文件，也可以访问你的网络。只在你信任模型和任务时使用。
• 完全访问 不经询问运行所有调用，包括对工作区外文件的编辑。
• 始终允许 会在此对话的剩余时间里（直到服务重启）不再询问。需要每次检查的操作，请选择 允许。
• web_fetch 会拒绝本地和私有地址，但 shell 和后台命令不会：命令可以访问这台机器能访问的一切，包括网关自己的 API。
• 模型读到的内容（网页、文件、命令输出）可能包含试图操纵它的指令。工具会读取不可信内容时，请保持批准开启。
• 如果其他机器可以访问这个服务，任何能登录网页界面的人都能使用这些工具。请设置访问密钥并限制可连接的来源（见访问与安全）。

设置参考复制锚点链接

terminal 是三个后台命令工具共用的开关。

{
  "playground": {
    "tools": ["read", "apply_patch", "shell", "web_search", "web_fetch"],
    "approval": "ask",
    "workspace": "~/hoshimi-work",
    "max_steps": 50,
    "search_url": ""
  }
}