# 智能体工作规范

本文记录 VOTX Agent 在本地执行任务时的操作约定，重点覆盖工具选择、文件落点、知识库维护和当前已收口的插件边界。

更新时间：2026-06-12

## 工具选择

硬性原则：**能用 Skill 或专用工具完成的，不使用 shell。**

优先级：

```text
专用 Skill/工具 > 文件/知识库/文档类 Skill > 受控基础工具 > shell
```

shell 只用于没有等价 Skill 的诊断、测试、构建、git 状态查看、进程/环境检查，或专用工具失败后的最小范围排查。

## 默认路径

本文面向开源仓库，不写死个人部署路径。真实路径以运行时项目根目录、当前用户和配置文件为准：

```text
项目根目录: <project-root>
临时文件:   <project-root>/tmp
输出文件:   <project-root>/users/<name>/download
上传文件:   <project-root>/users/<name>/history/file
用户知识库: <project-root>/users/<name>/knowledge
全局知识库: <project-root>/knowledge
```

规则：

- `tmp/` 只放临时脚本、中间缓存、测试样本，用完清理。
- `users/<name>/download/` 是智能体生成、导出、下载的默认产物目录。
- `users/<name>/history/file/` 是用户上传文件、外部消息附件、用户原始材料目录。
- `users/<name>/knowledge/` 是默认写入的用户私有知识库。
- `knowledge/` 是全局共享知识库，只在用户明确要求时写入。

## 知识库索引

知识库发生新增、修改、删除、重命名、移动时，索引更新是完成条件：

- 用户知识库变动后更新 `users/<name>/knowledge/data_structure.md`。
- 全局知识库变动后更新 `knowledge/data_structure.md`。
- 有子目录索引时，先更新最近的 `data_structure.md`，再更新根索引。
- 索引记录目录结构、文件用途、格式、来源、更新时间和检索关键词，不复制大段正文。
- 删除或移动知识文件时，索引中旧路径必须同步移除或改名。

## 当前插件边界

| 旧能力/插件 | 当前归属 |
|-------------|----------|
| `file_search` | 已并入 `file.search_files` |
| `video_download` | 已并入 `download_anything.download_video` |
| `web_content_fetcher` | 已并入 `network.web_read` |

当前重点工具：

| Skill | 主要工具 |
|-------|----------|
| `file` | `read_file`, `read_file_range`, `write_file`, `append_file`, `edit_file`, `list_dir`, `tree_dir`, `stat_file`, `search_files`, `copy_file`, `move_file`, `make_dir`, `delete_file` |
| `download_anything` | `inspect_download_url`, `download_direct_file`, `download_video`, `list_downloads` |
| `network` | `http_get`, `http_post`, `web_read` |
| `tavily_search` | `tavily_search`, `tavily_extract`, `tavily_crawl`, `tavily_map`, `tavily_research` |
| `pdf_tools` | PDF 信息、提取、拆分、合并、旋转、盖字、水印、预览、OCR、脱敏、视觉对比、依赖检查 |

`time.sleep` 的单次上限是 30 分钟，并通过工具 meta 跳过全局 `tool_timeout` 截断。

## 沙箱和网络范围

文件沙箱放开变量：

```text
VOTX_FILE_OUTSIDE_SANDBOX=1
VOTX_FILE_READ_OUTSIDE_SANDBOX=1
VOTX_FILE_EDIT_OUTSIDE_SANDBOX=1
VOTX_FILE_DELETE_OUTSIDE_SANDBOX=1
VOTX_DOWNLOAD_ANYTHING_OUTSIDE_SANDBOX=1
```

网络范围：

```text
network_scope: public / local / private / all
VOTX_NETWORK_SCOPE=public|local|private|all
HTTP_NETWORK_SCOPE=public|local|private|all
NETWORK_SCOPE=public|local|private|all
```

云元数据地址始终应硬拦截。
