Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

docs(resources): clarify uploaded snapshot watch limits (#3363)

Evodd31e3a05a07
diff --git a/docs/en/api/02-resources.md b/docs/en/api/02-resources.md
index f68138145..cd086c2db 100644
--- a/docs/en/api/02-resources.md
+++ b/docs/en/api/02-resources.md
@@ -111,7 +111,8 @@ Source Input -> Parse -> Resource Tree Build -> Persistence -> Semantic Processi
Resource incremental updates are implemented via the **Watch Task** mechanism:
#### Watch Task Creation
-- Set `watch_interval > 0` (in minutes) when calling `add_resource` to create a watch task
+- Set `watch_interval > 0` (in minutes) when calling `add_resource` with a re-readable source, such as a URL, sitemap, or RSS feed, to create a watch task
+- Uploaded content referenced by `temp_file_id` is consumed as a one-time snapshot and cannot be watched; re-add it when the local source changes
- You may specify `to` to define the target URI; if omitted, the task binds to the `root_uri` returned by this import
- Pointing a watch at a sitemap/RSS/Atom URL keeps the **whole site** in sync: each refresh re-reads the feed and rebuilds the tree, so newly published pages are added and removed pages drop automatically
- `WatchManager` handles task persistence
@@ -133,7 +134,7 @@ Resource incremental updates are implemented via the **Watch Task** mechanism:
### add_resource
-Add a resource to the knowledge base. The SDK supports local files/directories, URLs, and other sources. Raw HTTP calls accept remote URLs through `path` or uploaded local files through `temp_file_id`.
+Add a resource to the knowledge base. The SDK supports local files/directories, URLs, and other sources. Raw HTTP calls accept remote URLs through `path` or uploaded local files through `temp_file_id`. Uploaded content is a one-time snapshot, so it cannot be combined with `watch_interval > 0`.
#### 1. API Implementation Overview
@@ -177,7 +178,7 @@ This endpoint is the core entry point for resource management, supporting adding
| directly_upload_media | bool | No | True | Whether to directly upload media files |
| preserve_structure | bool | No | None | Whether to preserve directory structure |
| args | object | No | `{}` | Parser-specific import options forwarded to the source parser/accessor. E.g. `args.site=true/false` forces/opts out of whole-site (sitemap/RSS) ingestion, `args.max_pages` etc. override the `webfeed` config; the recursive web crawler accepts `args.depth`, `args.max_pages`, `args.include_paths`, `args.exclude_paths`, `args.allow_external_links`, `args.skip_download_links`; Feishu user-token imports pass `args.feishu_access_token`. Core `add_resource` fields such as `path`, `to`, `watch_interval`, `include`, and `exclude` are not allowed inside `args` |
-| watch_interval | float | No | 0 | Scheduled update interval (minutes). >0 creates task; <=0 cancels task; explicit `to` wins, otherwise binds to the imported `root_uri` |
+| watch_interval | float | No | 0 | Scheduled update interval (minutes). >0 creates a task for a re-readable URL/sitemap/RSS source; uploaded `temp_file_id` content is a one-time snapshot and must be re-added when it changes. <=0 cancels a task; explicit `to` wins, otherwise binds to the imported `root_uri` |
| telemetry | TelemetryRequest | No | False | Whether to return telemetry data |
**Additional Notes**:
diff --git a/docs/zh/api/02-resources.md b/docs/zh/api/02-resources.md
index 9b7a2445a..be41bf2d2 100644
--- a/docs/zh/api/02-resources.md
+++ b/docs/zh/api/02-resources.md
@@ -104,7 +104,8 @@ URL/文件 Parser TreeBuilder AGFS Summarizer/Vector
资源增量更新通过**监控任务 (Watch Task)** 机制实现:
#### 监控任务创建
-- 调用 `add_resource` 时设置 `watch_interval > 0` (单位:分钟)创建监控任务
+- 调用 `add_resource` 时,为 URL、sitemap、RSS 等可重新读取的来源设置 `watch_interval > 0`(单位:分钟),即可创建监控任务
+- `temp_file_id` 引用的上传内容只会作为一次性快照处理,不能创建监控任务;本地来源变化后请重新添加
- 可指定 `to` 参数确定目标 URI;未指定时,系统会使用本次导入返回的 `root_uri` 作为监控目标
- 把监控对象设为 sitemap/RSS/Atom URL,即可让**整站**保持同步:每次刷新重新读取 feed 并重建资源树,新发布的页面自动入库、已删除的页面自动移除
- `WatchManager` 负责任务持久化存储
@@ -126,7 +127,7 @@ URL/文件 Parser TreeBuilder AGFS Summarizer/Vector
### add_resource
-向知识库添加资源,支持本地文件/目录、URL 等多种来源。
+向知识库添加资源,支持本地文件/目录、URL 等多种来源。通过 `temp_file_id` 引用的上传内容是一次性快照,因此不能与 `watch_interval > 0` 组合使用。
#### 1. API 实现介绍
@@ -170,7 +171,7 @@ URL/文件 Parser TreeBuilder AGFS Summarizer/Vector
| directly_upload_media | bool | 否 | True | 是否直接上传媒体文件 |
| preserve_structure | bool | 否 | None | 是否保留目录结构 |
| args | object | 否 | `{}` | 传给特定 parser/accessor 的导入参数。例如 `args.site=true/false` 强制/禁用整站(sitemap/RSS)导入,`args.max_pages` 等可覆盖 `webfeed` 配置;递归网页爬虫支持 `args.depth`、`args.max_pages`、`args.include_paths`、`args.exclude_paths`、`args.allow_external_links`、`args.skip_download_links`;飞书用户 token 导入传 `args.feishu_access_token`。`path`、`to`、`watch_interval`、`include`、`exclude` 等 `add_resource` 核心字段不能放入 `args` |
-| watch_interval | float | 否 | 0 | 定时更新间隔(分钟)。>0 创建任务;≤0 取消任务;显式 `to` 优先,否则绑定本次导入的 `root_uri` |
+| watch_interval | float | 否 | 0 | 定时更新间隔(分钟)。>0 为 URL/sitemap/RSS 等可重新读取的来源创建任务;通过 `temp_file_id` 上传的内容是一次性快照,变化后需重新添加。≤0 取消任务;显式 `to` 优先,否则绑定本次导入的 `root_uri` |
| telemetry | TelemetryRequest | 否 | False | 是否返回遥测数据 |
**补充说明**: