工具、审批与 sandbox

OpenSquilla 工具为 agent 提供有用的能力。策略层、审批入口、工作区约束和 sandbox 姿态控制着这些工具被允许执行的方式。

在运行无人值守自动化、文件编辑、shell 命令或连接 channel 的 agent 之前，请先阅读本页。

如需聚焦权限的指南，参见 approvals-and-permissions.md。

内置工具领域

领域	示例
文件系统	`read_file`、`write_file`、`edit_file`、`list_dir`、`glob_search`、`grep_search`、电子表格读取。
Shell 与代码	`exec_command`、`background_process`、`process`、`execute_code`。
Git	`git_status`、`git_diff`、`git_log`、`git_commit`、`apply_patch`。
Web	`web_search`、`web_discover`、`web_fetch`、`http_request`。
记忆	`memory_search`、`memory_save`、`memory_get`、`memory_delete`。
Session	`sessions_send`、`sessions_spawn`、`sessions_list`、`sessions_history`、`session_status`。
Artifact	`publish_artifact`。
媒体	图像生成、PDF、TTS 及媒体辅助工具。
Skill	`skill_list`、`skill_view`、`skill_create`、`skill_edit`、`install_skill_deps`、`meta_invoke`。
管理	cron 与 gateway 管理。
Channel/平台	消息以及 Feishu/Lark 的文档、聊天、云盘、知识库、媒体和权限辅助工具。

权限模式

无人值守运行时使用更严格的模式：

opensquilla agent --permissions restricted -m "Inspect this repo"

仅在你信任该任务和工作区时使用更宽松的模式：

opensquilla agent --permissions full --workspace /path/to/project -m "Run tests and fix failures"

对于交互式工作，Web UI 的审批入口可暂停敏感工具调用以供审查。对于自动化，在运行开始前选择权限模式和工作区策略。

阅读：approvals-and-permissions.md

审批流程

敏感操作可能会暂停以等待人工审批，具体取决于权限模式、工具策略、channel 入口和 runtime 配置。

审批对以下场景最为重要：

文件系统写入；
shell 命令；
外部 channel 或 Webhook 投递；
将要发布的生成 artifact；
影响其他服务的操作。

当你希望在聊天回滚之外进行可靠审查时，使用 Web UI 的审批页面。

工作区控制

读侧限制：

opensquilla agent --workspace /path/to/project --workspace-strict -m "Summarize this repo"

写入约束：

opensquilla agent \
  --workspace /path/to/project \
  --workspace-lockdown \
  --scratch-dir /path/to/project/.scratch \
  -m "Investigate and prepare a minimal patch"

--workspace-lockdown 适用于写入必须保持在工作区或临时目录内的自动化场景。

Sandbox 命令

opensquilla sandbox status
opensquilla sandbox on
opensquilla sandbox full
opensquilla sandbox bypass
opensquilla sandbox reset

Sandbox 行为与平台相关。请以 sandbox status 和 doctor 作为当前机器的事实来源。

任务	推荐姿态
只读仓库摘要	`--workspace` 加 `--workspace-strict`
本地补丁附带测试	`--workspace`、`--workspace-lockdown` 以及临时目录
可能涉及写入的聊天	Web UI 并保持审批可见
连接 channel 的 agent	保守权限与显式 channel 配置
Provider/调试排查	开启诊断，最小化工具权限

Web 安全

OpenSquilla 的 Web 工具使用 provider 配置和护栏。当 Web 搜索行为异常时，使用 provider 诊断：

opensquilla search status
opensquilla search query "test query"
opensquilla diagnostics on

搜索结果和抓取页面是外部数据。它们应作为回答的参考，而不应覆盖工具策略或用户指令。

对于有来源支撑的回答，web_search 是默认的高层 Web 工具。web_discover 是轻量的链接发现，web_fetch 读取特定页面，而 http_request 保留用于原始 HTTP/API 请求。

工具压缩

较大的工具结果在展示给模型之前可能会被压缩。这是正常现象，可保护活跃上下文窗口。参见 features/tool-compression.md。

Artifact 与媒体

工具调用可发布 artifact 并生成媒体。参见 artifacts-and-media.md 了解面向用户的 artifact、文档、图像、PDF 和 TTS 工作流。

排障

如果工具无法运行：

检查权限姿态：

opensquilla sandbox status
opensquilla doctor

检查 gateway 或 channel 入口是否需要审批。
确认工作区路径是否正确。
对反复失败使用诊断：
```
opensquilla diagnostics on
```

文档索引 · 产品指南 · 改进此页面 · 报告文档问题