Skip to content

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

fix(resources): 明确等待超时语义并改用任务轮询示例 (#4888)

Qin Haojiea386269d38e0
diff --git a/README.md b/README.md
index 4d52d14ec..d0f484691 100644
--- a/README.md
+++ b/README.md
@@ -123,10 +123,11 @@ The install already includes the `ov` client CLI. With the server running:
```bash
ov status
-ov add-resource https://github.com/volcengine/OpenViking # --wait
+ov add-resource https://github.com/volcengine/OpenViking
+# Replace TASK_ID with the returned task_id; continue after status is completed
+ov task status TASK_ID
ov ls viking://resources/
ov tree viking://resources/volcengine -L 2
-# wait some time for semantic processing if not --wait
ov find "what is openviking"
ov grep "openviking" --uri viking://resources/volcengine/OpenViking/docs/en
```
diff --git a/README_CN.md b/README_CN.md
index 7214e5212..0cdf825b6 100644
--- a/README_CN.md
+++ b/README_CN.md
@@ -131,10 +131,11 @@ nohup openviking-server > /data/log/openviking.log 2>&1 &
```bash
ov status
-ov add-resource https://github.com/volcengine/OpenViking # --wait
+ov add-resource https://github.com/volcengine/OpenViking
+# 将 TASK_ID 替换为提交时返回的任务 ID;状态为 completed 后再执行后续命令
+ov task status TASK_ID
ov ls viking://resources/
ov tree viking://resources/volcengine -L 2
-# 没加 --wait 的话,语义处理需要等一段时间
ov find "what is openviking"
ov grep "openviking" --uri viking://resources/volcengine/OpenViking/docs/zh
```
diff --git a/README_JA.md b/README_JA.md
index 5c3aa4428..9fc4923eb 100644
--- a/README_JA.md
+++ b/README_JA.md
@@ -131,10 +131,11 @@ nohup openviking-server > /data/log/openviking.log 2>&1 &
```bash
ov status
-ov add-resource https://github.com/volcengine/OpenViking # --wait
+ov add-resource https://github.com/volcengine/OpenViking
+# TASK_ID を返されたタスク ID に置き換え、completed を確認してから後続のコマンドを実行します
+ov task status TASK_ID
ov ls viking://resources/
ov tree viking://resources/volcengine -L 2
-# --wait を付けない場合は、セマンティック処理の完了までしばらく待ちます
ov find "what is openviking"
ov grep "openviking" --uri viking://resources/volcengine/OpenViking/docs/en
```
diff --git a/docs/en/api/02-resources.md b/docs/en/api/02-resources.md
index a8d125016..33c6bed96 100644
--- a/docs/en/api/02-resources.md
+++ b/docs/en/api/02-resources.md
@@ -98,7 +98,7 @@ Source Input -> Parse -> Resource Tree Build -> Persistence -> Semantic Processi
#### Stage 4: Semantic Processing
- **Summary Generation**: `Summarizer` generates L0 (abstract) and L1 (overview)
- **Vector Index**: Vectorizes content for semantic search
-- Processed asynchronously via `SemanticQueue`, can wait for completion with `wait=True`
+- Processed asynchronously via `SemanticQueue`; use the returned `task_id` to check completion
#### Non-Wait Git Repository Imports
- For Git repository sources with `wait=false`, OpenViking validates the repository, resolves the target URI, reserves the final `root_uri`, and returns before clone/parse/finalize completes.
@@ -144,7 +144,7 @@ Add a resource to the knowledge base. The SDK supports local files/directories,
#### 1. API Implementation Overview
-This endpoint is the core entry point for resource management, supporting adding resources from various sources with optional waiting for semantic processing and vectorization completion.
+This endpoint is the core entry point for resource management. It supports various resource sources and returns a `task_id` by default so callers can query processing status.
**Processing Flow**:
1. Identify and validate the resource source (URL or uploaded temporary file)
@@ -152,7 +152,7 @@ This endpoint is the core entry point for resource management, supporting adding
3. Call the corresponding format Parser; `args.parse_mode` controls whether the converted Markdown body may be split
4. Build the directory tree and write to AGFS
5. Run post-ingest processing according to `processing_mode`: `semantic_and_vectors` generates semantic artifacts and vectors; `vectors_only` skips semantic understanding and only enqueues file vectorization
-6. Wait for semantic processing/vectorization completion when `wait=true`; with `wait=false`, return a `task_id` for queue tracking
+6. Return a `task_id` by default; callers confirm completion through the Task API
7. If `reason` is non-empty, append it to the fixed resource reason session and commit through the normal memory extraction pipeline so suitable user memories can reference the resource URI
8. Set up scheduled update task if `watch_interval` is specified
@@ -222,6 +222,8 @@ This endpoint is the core entry point for resource management, supporting adding
#### 3. Usage Examples
+These examples use the default asynchronous mode without waiting parameters. Save the returned `task_id` and query the [Task API](17-tasks.md). Read summaries or search the imported content only after the task reaches `completed`.
+
**HTTP API**
```
@@ -236,8 +238,7 @@ curl -X POST http://localhost:1933/api/v1/resources \
-H "X-API-Key: your-key" \
-d '{
"path": "https://example.com/guide.md",
- "reason": "User guide documentation",
- "wait": true
+ "reason": "User guide documentation"
}'
# Import and watch a private HTTPS Git repository
@@ -264,8 +265,7 @@ curl -X POST http://localhost:1933/api/v1/resources \
-d '{
"path": "https://example.com/guide.md",
"to": "viking://resources/guide",
- "processing_mode": "vectors_only",
- "wait": true
+ "processing_mode": "vectors_only"
}'
# Recursively crawl a site: expand along same-host links; depth bounds
@@ -275,8 +275,6 @@ curl -X POST http://localhost:1933/api/v1/resources \
-H "X-API-Key: your-key" \
-d '{
"path": "https://docs.openviking.ai/getting-started/01-introduction",
- "wait": true,
- "timeout": 60,
"args": { "depth": 1, "max_pages": 10 }
}'
@@ -348,7 +346,7 @@ result = client.add_resource(
path="./documents/guide.md",
options={"reason": "User guide documentation"},
)
-print(f"Added: {result['root_uri']}")
+print(f"Task ID: {result['task_id']}")
# Parse each document to Markdown without splitting its body
result = client.add_resource(
@@ -366,8 +364,6 @@ result = client.add_resource(
# Recursively crawl a site (same-host BFS; depth levels, max_pages cap)
result = client.add_resource(
path="https://docs.openviking.ai/getting-started/01-introduction",
- wait=True,
- timeout=180,
options={
"args": {"depth": 1, "max_pages": 10},
},
@@ -396,8 +392,8 @@ result = client.add_resource(
},
)
-# Wait for processing to complete
-client.wait_processed()
+# Check the latest import task; use its results after it reaches completed
+print(client.get_task(result["task_id"]))
# Enable scheduled updates
client.add_resource(
@@ -435,10 +431,9 @@ client.add_resource(
```typescript
const task = await client.addResource("https://example.com/docs", {
to: "viking://resources/docs/",
- wait: true,
args: { parse_mode: "no_split" },
});
-console.log(task);
+console.log(task.task_id);
```
**Go SDK**
@@ -446,13 +441,12 @@ console.log(task);
```go
result, err := client.AddResource(ctx, "./documents/guide.md", &openviking.AddResourceOptions{
Reason: "User guide documentation",
- Wait: true,
Args: map[string]any{"parse_mode": "no_split"},
})
if err != nil {
return err
}
-fmt.Println(result["root_uri"])
+fmt.Println(result["task_id"])
```
**CLI**
@@ -479,8 +473,8 @@ ov add-resource "https://docs.openviking.ai/" \
ov add-resource "https://example.com/docs" \
--args="depth:1,max_pages:20,skip_download_links:false"
-# Wait for processing to complete
-ov add-resource ./documents/guide.md --wait
+# Check progress using the task_id returned by submission
+ov task status TASK_ID
# Enable scheduled updates (check every 60 minutes)
ov add-resource https://github.com/example/repo.git --to viking://resources/guide.md --watch-interval 60
@@ -525,31 +519,7 @@ ov add-resource ./documents/guide.md -p viking://resources/docs/{calendar:today}
**Response Example**
-**HTTP API Response (JSON, `wait=true`)**
-
-```json
-{
- "status": "ok",
- "result": {
- "status": "success",
- "root_uri": "viking://resources/guide.md",
- "temp_uri": "viking://temp/username/04291108_b62dc7/guide.md",
- "source_path": "./documents/guide.md",
- "meta": {},
- "errors": [],
- "queue_status": {
- "pending": 5,
- "processing": 2,
- "completed": 10
- }
- },
- "telemetry": {
- "operation_id": "550e8400-e29b-41d4-a716-446655440000"
- }
-}
-```
-
-**HTTP API Response (JSON, non-Git `wait=false`)**
+**HTTP API Response (default asynchronous mode)**
```json
{
@@ -568,7 +538,7 @@ Use the returned `task_id` to poll `/api/v1/tasks/{task_id}` for queue completio
```
Note: Resource is being processed in the background.
-Use 'ov wait' to wait for completion, or 'ov observer queue' to check status.
+Use 'ov task status <task_id>' to check progress, or 'ov task list' to see all tasks.
status accepted
root_uri viking://resources/01-overview
task_id uuid-xxx
diff --git a/docs/en/api/04-skills.md b/docs/en/api/04-skills.md
index 801f49d9e..fdd6e62cb 100644
--- a/docs/en/api/04-skills.md
+++ b/docs/en/api/04-skills.md
@@ -156,7 +156,7 @@ Skills are a special type of resource that define actions or tools agents can pe
2. Detect data format (structured data, SKILL.md content, MCP format)
3. Parse skill definition
4. Store to the current user's `viking://user/{user_id}/skills/` path
-5. If `wait=true`, wait for vectorization to complete
+5. Return a `task_id` by default for tracking background vectorization
**Code Entry Points**:
- `sdk/python/openviking_sdk/client.py:AsyncHTTPClient.add_skill` - Python SDK entry point
@@ -200,6 +200,8 @@ Skills are a special type of resource that define actions or tools agents can pe
#### 3. Usage Examples
+Imports return a `task_id` by default. Query the [Task API](17-tasks.md) and search the skill after the task reaches `completed`.
+
**HTTP API**
```
@@ -217,8 +219,7 @@ curl -X POST http://localhost:1933/api/v1/skills \
"name": "search-web",
"description": "Search the web for current information",
"content": "# search-web\n\nSearch the web for current information.\n\n## Parameters\n- **query** (string, required): Search query\n- **limit** (integer, optional): Max results, default 10"
- },
- "wait": true
+ }
}'
# Using inline SKILL.md content
@@ -317,27 +318,25 @@ result = client.add_skill(data="./skills/code-runner/")
print(f"Added: {result['uri']}")
print(f"Auxiliary files: {result['auxiliary_files']}")
-# Wait for processing completion
-result = client.add_skill(data="./skills/my-skill/", wait=True)
-client.wait_processed()
+# Check the status of the previous import task
+print(client.get_task(result["task_id"]))
```
**TypeScript SDK**
```typescript
-await client.addSkill("./my-skill", { wait: true });
+const result = await client.addSkill("./my-skill");
+console.log(result.task_id);
```
**Go SDK**
```go
-result, err := client.AddSkill(ctx, "./skills/my-skill/", &openviking.AddSkillOptions{
- Wait: true,
-})
+result, err := client.AddSkill(ctx, "./skills/my-skill/", nil)
if err != nil {
return err
}
-fmt.Println(result["uri"])
+fmt.Println(result["task_id"])
```
**CLI**
@@ -348,8 +347,8 @@ ov add-skill ./skills/my-skill.json
ov add-skill ./skills/search-web/SKILL.md
ov add-skill ./skills/code-runner/
-# Wait for processing completion
-ov add-skill ./skills/my-skill/ --wait
+# Check progress using the task_id returned by submission
+ov task status TASK_ID
# Use JSON output format
ov add-skill ./skills/my-skill/ -o json
@@ -367,11 +366,7 @@ ov add-skill ./skills/my-skill/ -o json
"uri": "viking://user/alice/skills/my-skill",
"name": "my-skill",
"auxiliary_files": 2,
- "queue_status": {
- "pending": 0,
- "processing": 0,
- "completed": 1
- }
+ "task_id": "uuid-xxx"
},
"telemetry": {
"operation_id": "550e8400-e29b-41d4-a716-446655440000"
@@ -383,12 +378,13 @@ ov add-skill ./skills/my-skill/ -o json
**CLI response (default table format)**:
```
Note: Skill is being processed in the background.
-Use 'ov wait' to wait for completion, or 'ov observer queue' to check status.
+Use 'ov task status <task_id>' to check progress, or 'ov task list' to see all tasks.
status success
root_uri viking://user/alice/skills/my-skill
uri viking://user/alice/skills/my-skill
name my-skill
auxiliary_files 2
+task_id uuid-xxx
```
**CLI response (JSON format, using -o json)**:
@@ -398,7 +394,8 @@ auxiliary_files 2
"root_uri": "viking://user/alice/skills/my-skill",
"uri": "viking://user/alice/skills/my-skill",
"name": "my-skill",
- "auxiliary_files": 2
+ "auxiliary_files": 2,
+ "task_id": "uuid-xxx"
}
```
@@ -411,6 +408,7 @@ auxiliary_files 2
| `uri` | string | Canonical final URI of the skill in OpenViking (same as `root_uri`) |
| `name` | string | Skill name |
| `auxiliary_files` | number | Number of auxiliary files included with the skill |
+| `task_id` | string | Returned in the default asynchronous mode; query the Task API for the background processing task's final status |
| `queue_status` | object | (Optional, only when `wait=true`) Queue processing status with `pending`, `processing`, `completed` counts |
#### 4. Error Handling
@@ -553,7 +551,6 @@ validated = client.validate_skill(data={"name": "search-web", "description": "..
updated = client.update_skill(
skill_name="search-web",
data="./skills/search-web",
- wait=True,
)
```
@@ -574,9 +571,7 @@ validated, err := client.ValidateSkill(ctx, map[string]any{
"name": "search-web",
"description": "...",
}, nil)
-updated, err := client.UpdateSkill(ctx, "search-web", "./skills/search-web", &openviking.UpdateSkillOptions{
- Wait: true,
-})
+updated, err := client.UpdateSkill(ctx, "search-web", "./skills/search-web", nil)
_, _ = validated, updated
```
@@ -598,8 +593,7 @@ curl -X PUT http://localhost:1933/api/v1/skills/search-web \
"name": "search-web",
"description": "Search the web for current information",
"content": "# search-web\n\nUpdated instructions."
- },
- "wait": true
+ }
}'
```
diff --git a/docs/en/api/17-tasks.md b/docs/en/api/17-tasks.md
index c577b3159..2021e7d18 100644
--- a/docs/en/api/17-tasks.md
+++ b/docs/en/api/17-tasks.md
@@ -2,6 +2,8 @@
The Task API tracks asynchronous resource imports, session commits, reindexing, snapshot restores, and similar operations.
+Submit an operation, save its `task_id`, and check status with separate requests. Receiving a task ID means the task was submitted; only `completed` means processing succeeded. `pending`, `running`, and `cancelling` are not terminal states. Stopping polling does not cancel the background task.
+
## API Reference
### get_task()
@@ -47,14 +49,29 @@ curl -X GET http://localhost:1933/api/v1/tasks/uuid-xxx \
**Python SDK**
```python
+import asyncio
+
from openviking_sdk import AsyncHTTPClient
client = AsyncHTTPClient(url="http://localhost:1933", api_key="your-key")
await client.initialize()
-task = await client.get_task(task_id="uuid-xxx")
-print(f"Status: {task['status']}")
-await client.close()
+try:
+ submitted = await client.add_resource("https://example.com/guide.md")
+ task_id = submitted["task_id"]
+ print(f"Import task: {task_id}")
+ while True:
+ task = await client.get_task(task_id)
+ if task is None:
+ raise RuntimeError(f"Task {task_id} is no longer available")
+ if task["status"] == "completed":
+ break
+ if task["status"] in {"failed", "cancelled"}:
+ raise RuntimeError(f"Import task {task_id}: {task['status']} ({task.get('error')})")
+ await asyncio.sleep(2)
+ print(task["result"])
+finally:
+ await client.close()
```
**TypeScript SDK**
diff --git a/docs/en/api/99-api-doc-writing-guide.md b/docs/en/api/99-api-doc-writing-guide.md
index c450615dd..79d8dce46 100644
--- a/docs/en/api/99-api-doc-writing-guide.md
+++ b/docs/en/api/99-api-doc-writing-guide.md
@@ -136,6 +136,8 @@ Each API is organized in the following three parts:
#### 3. Usage Examples
+For operations that return background tasks, default examples should submit a task and query its status. Avoid explicitly setting `wait` or `timeout`, and do not use global `wait_processed()` as a substitute for task status. Keep supported parameters and their actual defaults in the full reference. When later operations depend on asynchronous output, show polling by `task_id` until `completed` and handle `failed` and `cancelled`; do not just remove waiting parameters and immediately read the result.
+
When an operation presents all transports together, prefer this order:
- Python SDK example
- TypeScript SDK example
@@ -216,8 +218,7 @@ curl -X POST http://localhost:1933/api/v1/resources \
-H "X-API-Key: your-key" \
-d '{
"path": "https://example.com/guide.md",
- "reason": "User guide documentation",
- "wait": true
+ "reason": "User guide documentation"
}'
```
@@ -232,15 +233,15 @@ result = client.add_resource(
path="./documents/guide.md",
options={"reason": "User guide documentation"},
)
-print(f"Added: {result['root_uri']}")
+print(f"Task ID: {result['task_id']}")
-client.wait_processed()
+print(client.get_task(result["task_id"]))
```
**CLI**
```bash
-openviking add-resource ./documents/guide.md --reason "User guide documentation" --wait
+openviking add-resource ./documents/guide.md --reason "User guide documentation"
```
**Response Example**
@@ -251,7 +252,7 @@ openviking add-resource ./documents/guide.md --reason "User guide documentation"
"result": {
"status": "success",
"root_uri": "viking://resources/documents/guide.md",
- "source_path": "./documents/guide.md",
+ "task_id": "uuid-xxx",
"errors": []
},
"time": 0.123
diff --git a/docs/en/getting-started/02-quickstart.md b/docs/en/getting-started/02-quickstart.md
index cfa5c4b9f..76152b9d3 100644
--- a/docs/en/getting-started/02-quickstart.md
+++ b/docs/en/getting-started/02-quickstart.md
@@ -174,6 +174,8 @@ The default local setup does not require an API key. For an authenticated server
Create `example.py`:
```python
+import time
+
from openviking_sdk import SyncHTTPClient
# Connect to the local OpenViking Server
@@ -185,13 +187,22 @@ try:
# Add resource (supports URL, file, or directory)
# Local directory scans respect .gitignore by default.
- # Wait until semantic processing completes before inspecting the resource.
- print("Wait for semantic processing...")
add_result = client.add_resource(
path="https://raw.githubusercontent.com/volcengine/OpenViking/refs/heads/main/README.md",
- wait=True,
)
- root_uri = add_result['root_uri']
+
+ task_id = add_result["task_id"]
+ print(f"Import task: {task_id}")
+ while True:
+ task = client.get_task(task_id)
+ if task is None:
+ raise RuntimeError(f"Task {task_id} is no longer available")
+ if task["status"] == "completed":
+ break
+ if task["status"] in {"failed", "cancelled"}:
+ raise RuntimeError(f"Import task {task_id}: {task['status']} ({task.get('error')})")
+ time.sleep(2)
+ root_uri = task["result"]["root_uri"]
# Explore the resource tree structure
ls_result = client.ls(uri=root_uri)
diff --git a/docs/en/getting-started/03-quickstart-server.md b/docs/en/getting-started/03-quickstart-server.md
index a7c73003d..38d45dd4d 100644
--- a/docs/en/getting-started/03-quickstart-server.md
+++ b/docs/en/getting-started/03-quickstart-server.md
@@ -104,6 +104,8 @@ See [Authentication](../guides/04-authentication.md) for details (trusted mode,
**Full example (using `user_key`):**
```python
+import time
+
import openviking as ov
client = ov.SyncHTTPClient(url="http://localhost:1933")
@@ -115,10 +117,19 @@ try:
result = client.add_resource(
path="https://raw.githubusercontent.com/volcengine/OpenViking/refs/heads/main/README.md",
)
- root_uri = result["root_uri"]
- # Wait for processing
- client.wait_processed()
+ task_id = result["task_id"]
+ print(f"Import task: {task_id}")
+ while True:
+ task = client.get_task(task_id)
+ if task is None:
+ raise RuntimeError(f"Task {task_id} is no longer available")
+ if task["status"] == "completed":
+ break
+ if task["status"] in {"failed", "cancelled"}:
+ raise RuntimeError(f"Import task {task_id}: {task['status']} ({task.get('error')})")
+ time.sleep(2)
+ root_uri = task["result"]["root_uri"]
# Search
results = client.find(
diff --git a/docs/en/getting-started/05-cli-setup.md b/docs/en/getting-started/05-cli-setup.md
index faae8f5b1..becc3b9fc 100644
--- a/docs/en/getting-started/05-cli-setup.md
+++ b/docs/en/getting-started/05-cli-setup.md
@@ -478,7 +478,9 @@ Once the CLI is configured, use `ov --help` and `ov <command> --help` to learn t
Adding a resource writes data into the active OpenViking server. If you want a small demo, use a resource you are comfortable storing. Agents must ask the user for permission before running this kind of demo command.
```bash
-ov add-resource https://github.com/volcengine/OpenViking --wait
+ov add-resource https://github.com/volcengine/OpenViking
+# Use the returned task_id; search after its status reaches completed
+ov task status TASK_ID
ov find "what is OpenViking"
ov tree viking://resources/ -L 2
```
diff --git a/docs/zh/api/02-resources.md b/docs/zh/api/02-resources.md
index ebaef342c..eb409fccc 100644
--- a/docs/zh/api/02-resources.md
+++ b/docs/zh/api/02-resources.md
@@ -91,7 +91,7 @@ URL/文件 Parser TreeBuilder AGFS Summarizer/Vector
#### 阶段 4:语义处理 (Semantic Processing)
- **摘要生成**:`Summarizer` 生成 L0(摘要)和 L1(概述)
- **向量索引**:将内容向量化用于语义搜索
-- 通过 `SemanticQueue` 异步处理,可通过 `wait=True` 等待完成
+- 通过 `SemanticQueue` 异步处理,使用返回的 `task_id` 查询完成状态
#### 非等待 Git 仓库导入
- 对 Git 仓库来源使用 `wait=false` 时,OpenViking 会先校验仓库、解析目标 URI、预占最终 `root_uri`,然后在 clone/parse/finalize 完成前返回。
@@ -137,7 +137,7 @@ URL/文件 Parser TreeBuilder AGFS Summarizer/Vector
#### 1. API 实现介绍
-此接口是资源管理的核心入口,支持多种来源的资源添加,并可选择等待语义处理完成。SDK 可直接处理本地文件/目录、URL 等来源;直接 HTTP 调用只通过 `path` 接受远程 URL,或通过 `temp_file_id` 引用先上传的本地文件。
+此接口是资源管理的核心入口,支持多种来源的资源添加,默认返回 `task_id` 供调用方查询处理状态。SDK 可直接处理本地文件/目录、URL 等来源;直接 HTTP 调用只通过 `path` 接受远程 URL,或通过 `temp_file_id` 引用先上传的本地文件。
**处理流程**:
1. 识别并校验资源来源(URL 或上传的临时文件)
@@ -145,7 +145,7 @@ URL/文件 Parser TreeBuilder AGFS Summarizer/Vector
3. 调用对应格式 Parser;`args.parse_mode` 控制转换后的 Markdown 正文是否允许拆分
4. 构建目录树并写入 AGFS
5. 按 `processing_mode` 执行入库后的处理:`semantic_and_vectors` 生成语义产物和向量;`vectors_only` 跳过语义理解,只提交文件向量化
-6. `wait=true` 时等待语义处理/向量化完成;`wait=false` 时返回 `task_id` 用于队列跟踪
+6. 默认返回 `task_id`;调用方通过任务 API 确认处理完成
7. 如果 `reason` 非空,将其追加到固定的资源 reason session 并 commit,复用常规记忆抽取链路,让合适的用户记忆引用该资源 URI
8. 如指定 `--watch-interval`,设置定时更新任务
@@ -217,6 +217,8 @@ URL/文件 Parser TreeBuilder AGFS Summarizer/Vector
#### 3. 使用示例
+以下示例使用默认异步模式,不设置等待参数。提交后保存 `task_id`,通过 [任务 API](17-tasks.md) 查询状态;只有任务为 `completed` 时,才读取摘要或检索本次导入的内容。
+
**HTTP API**
```
@@ -231,8 +233,7 @@ curl -X POST http://localhost:1933/api/v1/resources \
-H "X-API-Key: your-key" \
-d '{
"path": "https://example.com/guide.md",
- "reason": "User guide documentation",
- "wait": true
+ "reason": "User guide documentation"
}'
# 导入并定时同步 HTTPS 私有 Git 仓库
@@ -259,8 +260,7 @@ curl -X POST http://localhost:1933/api/v1/resources \
-d '{
"path": "https://example.com/guide.md",
"to": "viking://resources/guide",
- "processing_mode": "vectors_only",
- "wait": true
+ "processing_mode": "vectors_only"
}'
# 递归抓取网页:从入口页沿同域链接展开,depth 控制层数,max_pages 限制页数
@@ -269,8 +269,6 @@ curl -X POST http://localhost:1933/api/v1/resources \
-H "X-API-Key: your-key" \
-d '{
"path": "https://docs.openviking.ai/zh/getting-started/01-introduction",
- "wait": true,
- "timeout": 60,
"args": { "depth": 1, "max_pages": 10 }
}'
@@ -308,7 +306,6 @@ curl -X POST http://localhost:1933/api/v1/resources \
-d "{
\"temp_file_id\": \"$TEMP_FILE_ID\",
\"to\": \"viking://resources/tagged-guide.md\",
- \"wait\": true,
\"tags\": [\"team=search\", \"env=test\"],
\"tag_mode\": \"replace\"
}"
@@ -354,7 +351,7 @@ result = client.add_resource(
path="./documents/guide.md",
options={"reason": "User guide documentation"},
)
-print(f"Added: {result['root_uri']}")
+print(f"Task ID: {result['task_id']}")
## 正常解析并转换为 Markdown,但每个文档正文不拆分
result = client.add_resource(
@@ -372,8 +369,6 @@ result = client.add_resource(
## 递归抓取网页(同域 BFS,depth 层数、max_pages 页数上限)
result = client.add_resource(
path="https://docs.openviking.ai/zh/getting-started/01-introduction",
- wait=True,
- timeout=180,
options={
"args": {"depth": 1, "max_pages": 10},
},
@@ -402,8 +397,8 @@ result = client.add_resource(
},
)
-## 等待处理完成
-client.wait_processed()
+## 查询最近一次导入任务;状态为 completed 后再使用处理结果
+print(client.get_task(result["task_id"]))
## 开启定时更新
client.add_resource(
@@ -441,10 +436,9 @@ client.add_resource(
```typescript
const task = await client.addResource("https://example.com/docs", {
to: "viking://resources/docs/",
- wait: true,
args: { parse_mode: "no_split" },
});
-console.log(task);
+console.log(task.task_id);
```
**Go SDK**
@@ -452,13 +446,12 @@ console.log(task);
```go
result, err := client.AddResource(ctx, "./documents/guide.md", &openviking.AddResourceOptions{
Reason: "User guide documentation",
- Wait: true,
Args: map[string]any{"parse_mode": "no_split"},
})
if err != nil {
return err
}
-fmt.Println(result["root_uri"])
+fmt.Println(result["task_id"])
```
**CLI**
@@ -485,8 +478,8 @@ ov add-resource "https://docs.openviking.ai/" \
ov add-resource "https://example.com/docs" \
--args="depth:1,max_pages:20,skip_download_links:false"
-# 等待处理完成
-ov add-resource ./documents/guide.md --wait
+# 使用提交时返回的 task_id 查询进度
+ov task status TASK_ID
# 开启定时更新(每60分钟检测一次)
ov add-resource https://github.com/example/repo.git --to viking://resources/my_repo --watch-interval 60
@@ -531,31 +524,7 @@ ov add-resource ./documents/guide.md -p viking://resources/docs/{calendar:today}
#### 4. 响应示例
-**HTTP API 响应 (JSON, `wait=true`)**
-
-```json
-{
- "status": "ok",
- "result": {
- "status": "success",
- "root_uri": "viking://resources/guide.md",
- "temp_uri": "viking://temp/username/04291108_b62dc7/guide.md",
- "source_path": "./documents/guide.md",
- "meta": {},
- "errors": [],
- "queue_status": {
- "pending": 5,
- "processing": 2,
- "completed": 10
- }
- },
- "telemetry": {
- "operation_id": "550e8400-e29b-41d4-a716-446655440000"
- }
-}
-```
-
-**HTTP API 响应 (JSON, 非 Git `wait=false`)**
+**HTTP API 响应(默认异步模式)**
```json
{
@@ -574,7 +543,7 @@ ov add-resource ./documents/guide.md -p viking://resources/docs/{calendar:today}
```
Note: Resource is being processed in the background.
-Use 'ov wait' to wait for completion, or 'ov observer queue' to check status.
+Use 'ov task status <task_id>' to check progress, or 'ov task list' to see all tasks.
status accepted
root_uri viking://resources/01-overview
task_id uuid-xxx
diff --git a/docs/zh/api/04-skills.md b/docs/zh/api/04-skills.md
index 17561e05b..e2dcef6f3 100644
--- a/docs/zh/api/04-skills.md
+++ b/docs/zh/api/04-skills.md
@@ -154,7 +154,7 @@ This tool wraps the MCP tool `search-web`. Call this when the user needs functio
2. 检测数据格式(结构化数据、SKILL.md 内容、MCP 格式)
3. 解析技能定义
4. 存储到当前用户的 `viking://user/{user_id}/skills/` 路径下
-5. 如指定 `wait=True`,等待向量化完成
+5. 默认返回 `task_id`,用于查询后台向量化任务
**代码入口**:
- `sdk/python/openviking_sdk/client.py:AsyncHTTPClient.add_skill` - Python SDK 入口
@@ -199,10 +199,13 @@ This tool wraps the MCP tool `search-web`. Call this when the user needs functio
#### 3. 使用示例
+导入默认返回 `task_id`。通过 [任务 API](17-tasks.md) 查询状态,任务为 `completed` 后再检索该技能。
+
**TypeScript SDK**
```typescript
-await client.addSkill("./my-skill", { wait: true });
+const result = await client.addSkill("./my-skill");
+console.log(result.task_id);
```
**HTTP API**:
@@ -222,8 +225,7 @@ curl -X POST http://localhost:1933/api/v1/skills \
"name": "search-web",
"description": "Search the web for current information",
"content": "# search-web\n\nSearch the web for current information.\n\n## Parameters\n- **query** (string, required): Search query\n- **limit** (integer, optional): Max results, default 10"
- },
- "wait": true
+ }
}'
# 使用内联 SKILL.md 内容
@@ -322,21 +324,18 @@ result = client.add_skill(data="./skills/code-runner/")
print(f"Added: {result['uri']}")
print(f"Auxiliary files: {result['auxiliary_files']}")
-# 等待处理完成
-result = client.add_skill(data="./skills/my-skill/", wait=True)
-client.wait_processed()
+# 查询上一次导入任务的状态
+print(client.get_task(result["task_id"]))
```
**Go SDK**
```go
-result, err := client.AddSkill(ctx, "./skills/my-skill/", &openviking.AddSkillOptions{
- Wait: true,
-})
+result, err := client.AddSkill(ctx, "./skills/my-skill/", nil)
if err != nil {
return err
}
-fmt.Println(result["uri"])
+fmt.Println(result["task_id"])
```
**CLI**:
@@ -347,8 +346,8 @@ ov add-skill ./skills/my-skill.json
ov add-skill ./skills/search-web/SKILL.md
ov add-skill ./skills/code-runner/
-# 等待处理完成
-ov add-skill ./skills/my-skill/ --wait
+# 使用提交时返回的 task_id 查询进度
+ov task status TASK_ID
# 使用 JSON 输出格式
ov add-skill ./skills/my-skill/ -o json
@@ -366,11 +365,7 @@ ov add-skill ./skills/my-skill/ -o json
"uri": "viking://user/alice/skills/my-skill",
"name": "my-skill",
"auxiliary_files": 2,
- "queue_status": {
- "pending": 0,
- "processing": 0,
- "completed": 1
- }
+ "task_id": "uuid-xxx"
},
"telemetry": {
"operation_id": "550e8400-e29b-41d4-a716-446655440000"
@@ -382,12 +377,13 @@ ov add-skill ./skills/my-skill/ -o json
**CLI 响应(默认表格格式)**:
```
Note: Skill is being processed in the background.
-Use 'ov wait' to wait for completion, or 'ov observer queue' to check status.
+Use 'ov task status <task_id>' to check progress, or 'ov task list' to see all tasks.
status success
root_uri viking://user/alice/skills/my-skill
uri viking://user/alice/skills/my-skill
name my-skill
auxiliary_files 2
+task_id uuid-xxx
```
**CLI 响应(JSON 格式,使用 -o json)**:
@@ -397,7 +393,8 @@ auxiliary_files 2
"root_uri": "viking://user/alice/skills/my-skill",
"uri": "viking://user/alice/skills/my-skill",
"name": "my-skill",
- "auxiliary_files": 2
+ "auxiliary_files": 2,
+ "task_id": "uuid-xxx"
}
```
@@ -410,6 +407,7 @@ auxiliary_files 2
| `uri` | string | 技能在 OpenViking 中的 canonical 最终 URI(同 `root_uri`)|
| `name` | string | 技能名称 |
| `auxiliary_files` | number | 技能附带的辅助文件数量 |
+| `task_id` | string | 默认异步模式下返回的后台处理任务 ID;通过任务 API 查询最终状态 |
| `queue_status` | object | (可选,仅当 `wait=True` 时)队列处理状态,包含 `pending`、`processing`、`completed` 计数 |
#### 4. 错误处理
@@ -554,7 +552,6 @@ validated = client.validate_skill(data={"name": "search-web", "description": "..
updated = client.update_skill(
skill_name="search-web",
data="./skills/search-web",
- wait=True,
)
```
@@ -576,9 +573,7 @@ validated, err := client.ValidateSkill(ctx, map[string]any{
"name": "search-web",
"description": "...",
}, nil)
-updated, err := client.UpdateSkill(ctx, "search-web", "./skills/search-web", &openviking.UpdateSkillOptions{
- Wait: true,
-})
+updated, err := client.UpdateSkill(ctx, "search-web", "./skills/search-web", nil)
_, _ = validated, updated
```
@@ -600,8 +595,7 @@ curl -X PUT http://localhost:1933/api/v1/skills/search-web \
"name": "search-web",
"description": "Search the web for current information",
"content": "# search-web\n\nUpdated instructions."
- },
- "wait": true
+ }
}'
```
diff --git a/docs/zh/api/17-tasks.md b/docs/zh/api/17-tasks.md
index 5476f1f60..ea7bb9b9b 100644
--- a/docs/zh/api/17-tasks.md
+++ b/docs/zh/api/17-tasks.md
@@ -2,6 +2,8 @@
任务 API 用于跟踪资源导入、会话提交、索引维护和快照恢复等异步操作。
+推荐先提交操作、保存返回的 `task_id`,再通过独立请求查询状态。收到任务 ID 只表示任务已提交;状态为 `completed` 才表示处理成功。`pending`、`running`、`cancelling` 都不是终态。停止轮询不会取消后台任务。
+
## API 参考
### get_task()
@@ -47,14 +49,29 @@ curl -X GET http://localhost:1933/api/v1/tasks/uuid-xxx \
**Python SDK**
```python
+import asyncio
+
from openviking_sdk import AsyncHTTPClient
client = AsyncHTTPClient(url="http://localhost:1933", api_key="your-key")
await client.initialize()
-task = await client.get_task(task_id="uuid-xxx")
-print(f"Status: {task['status']}")
-await client.close()
+try:
+ submitted = await client.add_resource("https://example.com/guide.md")
+ task_id = submitted["task_id"]
+ print(f"Import task: {task_id}")
+ while True:
+ task = await client.get_task(task_id)
+ if task is None:
+ raise RuntimeError(f"Task {task_id} is no longer available")
+ if task["status"] == "completed":
+ break
+ if task["status"] in {"failed", "cancelled"}:
+ raise RuntimeError(f"Import task {task_id}: {task['status']} ({task.get('error')})")
+ await asyncio.sleep(2)
+ print(task["result"])
+finally:
+ await client.close()
```
**TypeScript SDK**
diff --git a/docs/zh/api/99-api-doc-writing-guide.md b/docs/zh/api/99-api-doc-writing-guide.md
index 88e88fd98..740291abc 100644
--- a/docs/zh/api/99-api-doc-writing-guide.md
+++ b/docs/zh/api/99-api-doc-writing-guide.md
@@ -135,6 +135,8 @@ API 文档按模块组织,每个模块一个文件,使用两位数字序号
#### 3. 使用示例
+对于返回后台任务的操作,默认示例优先使用“提交任务 → 查询状态”,尽量不主动设置 `wait`、`timeout`,也不使用全局 `wait_processed()` 代替任务状态。完整参数参考应保留受支持参数及其真实默认值。后续操作依赖异步产物时,应展示按 `task_id` 轮询至 `completed`,并处理 `failed`、`cancelled`;不能仅删除等待参数后立即读取结果。
+
当一个接口并列展示所有调用方式时,建议按以下顺序提供:
- Python SDK 示例
- TypeScript SDK 示例
@@ -210,8 +212,7 @@ curl -X POST http://localhost:1933/api/v1/resources \
-H "X-API-Key: your-key" \
-d '{
"path": "https://example.com/guide.md",
- "reason": "User guide documentation",
- "wait": true
+ "reason": "User guide documentation"
}'
```
@@ -226,15 +227,15 @@ result = client.add_resource(
path="./documents/guide.md",
options={"reason": "User guide documentation"},
)
-print(f"Added: {result['root_uri']}")
+print(f"Task ID: {result['task_id']}")
-client.wait_processed()
+print(client.get_task(result["task_id"]))
```
**CLI**
```bash
-openviking add-resource ./documents/guide.md --reason "User guide documentation" --wait
+openviking add-resource ./documents/guide.md --reason "User guide documentation"
```
**响应示例**
@@ -245,7 +246,7 @@ openviking add-resource ./documents/guide.md --reason "User guide documentation"
"result": {
"status": "success",
"root_uri": "viking://resources/documents/guide.md",
- "source_path": "./documents/guide.md",
+ "task_id": "uuid-xxx",
"errors": []
},
"time": 0.123
diff --git a/docs/zh/getting-started/02-quickstart.md b/docs/zh/getting-started/02-quickstart.md
index 77ace076b..35bcd0de4 100644
--- a/docs/zh/getting-started/02-quickstart.md
+++ b/docs/zh/getting-started/02-quickstart.md
@@ -174,6 +174,8 @@ openviking-server
创建 `example.py`:
```python
+import time
+
from openviking_sdk import SyncHTTPClient
# 连接本地 OpenViking Server
@@ -185,13 +187,22 @@ try:
# Add resource (supports URL, file, or directory)
# Local directory scans respect .gitignore by default.
- # Wait until semantic processing completes before inspecting the resource.
- print("Wait for semantic processing...")
add_result = client.add_resource(
path="https://raw.githubusercontent.com/volcengine/OpenViking/refs/heads/main/README.md",
- wait=True,
)
- root_uri = add_result['root_uri']
+
+ task_id = add_result["task_id"]
+ print(f"Import task: {task_id}")
+ while True:
+ task = client.get_task(task_id)
+ if task is None:
+ raise RuntimeError(f"Task {task_id} is no longer available")
+ if task["status"] == "completed":
+ break
+ if task["status"] in {"failed", "cancelled"}:
+ raise RuntimeError(f"Import task {task_id}: {task['status']} ({task.get('error')})")
+ time.sleep(2)
+ root_uri = task["result"]["root_uri"]
# Explore the resource tree structure
ls_result = client.ls(uri=root_uri)
diff --git a/docs/zh/getting-started/03-quickstart-server.md b/docs/zh/getting-started/03-quickstart-server.md
index 81eb7b23a..ec7ceb6c4 100644
--- a/docs/zh/getting-started/03-quickstart-server.md
+++ b/docs/zh/getting-started/03-quickstart-server.md
@@ -100,6 +100,8 @@ client = ov.SyncHTTPClient(
**完整示例(使用 `user_key`):**
```python
+import time
+
import openviking as ov
client = ov.SyncHTTPClient(url="http://localhost:1933")
@@ -111,10 +113,19 @@ try:
result = client.add_resource(
path="https://raw.githubusercontent.com/volcengine/OpenViking/refs/heads/main/README.md",
)
- root_uri = result["root_uri"]
- # Wait for processing
- client.wait_processed()
+ task_id = result["task_id"]
+ print(f"Import task: {task_id}")
+ while True:
+ task = client.get_task(task_id)
+ if task is None:
+ raise RuntimeError(f"Task {task_id} is no longer available")
+ if task["status"] == "completed":
+ break
+ if task["status"] in {"failed", "cancelled"}:
+ raise RuntimeError(f"Import task {task_id}: {task['status']} ({task.get('error')})")
+ time.sleep(2)
+ root_uri = task["result"]["root_uri"]
# Search
results = client.find(
diff --git a/docs/zh/getting-started/05-cli-setup.md b/docs/zh/getting-started/05-cli-setup.md
index 6b1c9d4cc..ffe7acf53 100644
--- a/docs/zh/getting-started/05-cli-setup.md
+++ b/docs/zh/getting-started/05-cli-setup.md
@@ -478,7 +478,9 @@ CLI 配置完成后,使用 `ov --help` 和 `ov <command> --help` 继续了解
添加资源会把数据写入 active OpenViking 服务端。如果你想做一个小演示,请选择你愿意存入服务端的资源。Agent 运行这类演示命令前,必须先征得用户同意。
```bash
-ov add-resource https://github.com/volcengine/OpenViking --wait
+ov add-resource https://github.com/volcengine/OpenViking
+# 使用返回的 task_id 查询状态;completed 后再检索
+ov task status TASK_ID
ov find "what is OpenViking"
ov tree viking://resources/ -L 2
```
diff --git a/examples/basic-usage/README.md b/examples/basic-usage/README.md
index df3ca3b35..076cd8132 100644
--- a/examples/basic-usage/README.md
+++ b/examples/basic-usage/README.md
@@ -104,7 +104,6 @@ Add a URL, local file, or directory:
```python
result = client.add_resource(
path="https://example.com/docs",
- options={"wait": False},
)
result = client.add_resource(path="/path/to/manual.pdf")
@@ -115,8 +114,7 @@ result = client.add_resource(
)
```
-For scripts and demos, `wait=True` is fine. In long-running applications, it is often better to ingest
-asynchronously and call `wait_processed()` when you actually need the indexed result.
+Imports return a `task_id` by default. Query `client.get_task(result["task_id"])` and read summaries or search the imported content only after the task reaches `completed`. See [Background Tasks](../../docs/en/api/17-tasks.md) for polling examples.
### Filesystem Access
@@ -250,7 +248,7 @@ You can also use Volcengine or Azure OpenAI. For current provider-specific examp
| `ImportError` or local extension issues | Reinstall `openviking`; if developing from source, ensure local build dependencies are available. |
| `Connection refused` in HTTP mode | Start `openviking-server` and verify `http://localhost:1933/health`. |
| Tenant/auth errors | Prefer `user_key` for normal data APIs; use `root_key` only with explicit tenant headers. |
-| Slow or empty search results right after ingestion | Wait for `wait_processed()` or ingest with `wait=True`. |
+| Slow or empty search results right after ingestion | Query the import task by `task_id` and search after its status reaches `completed`. |
| Multiple clients or sessions competing for local storage | Use HTTP server mode instead of spinning up separate local processes. |
## License
diff --git a/examples/basic-usage/README_CN.md b/examples/basic-usage/README_CN.md
index b89f2f94c..f632d879e 100644
--- a/examples/basic-usage/README_CN.md
+++ b/examples/basic-usage/README_CN.md
@@ -105,7 +105,6 @@ client = SyncHTTPClient(
```python
result = client.add_resource(
path="https://example.com/docs",
- options={"wait": False},
)
result = client.add_resource(path="/path/to/manual.pdf")
@@ -116,8 +115,7 @@ result = client.add_resource(
)
```
-脚本和 demo 可以直接用 `wait=True`。
-真正的服务里更常见的做法是异步导入,等到你确实需要结果时再调用 `wait_processed()`。
+导入默认返回 `task_id`。通过 `client.get_task(result["task_id"])` 查询状态,只有任务为 `completed` 时才读取摘要或检索本次导入的内容。轮询示例见 [后台任务](../../docs/zh/api/17-tasks.md)。
### 文件系统访问
@@ -251,7 +249,7 @@ memories = client.find(
| `ImportError` 或本地扩展问题 | 重新安装 `openviking`;如果是源码开发,确认本地构建依赖齐全。 |
| HTTP 模式下 `Connection refused` | 启动 `openviking-server`,并检查 `http://localhost:1933/health`。 |
| 租户或认证报错 | 普通数据接口优先使用 `user_key`;`root_key` 仅在显式传入租户信息时使用。 |
-| 刚导入后检索慢或搜不到 | 等待 `wait_processed()`,或在导入时直接用 `wait=True`。 |
+| 刚导入后检索慢或搜不到 | 查询本次导入的 `task_id`,确认任务状态为 `completed` 后再检索。 |
| 多个客户端或会话争用本地存储 | 不要反复起独立本地进程,改用 HTTP 服务端模式。 |
## 许可证
diff --git a/examples/basic-usage/basic_usage.py b/examples/basic-usage/basic_usage.py
index 29ca3beba..767278aa5 100644
--- a/examples/basic-usage/basic_usage.py
+++ b/examples/basic-usage/basic_usage.py
@@ -17,6 +17,7 @@ Requirements:
import os
import sys
+import time
# Add parent directory to path for local development
sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__)))))
@@ -70,26 +71,48 @@ def main():
# Add a URL resource
result = client.add_resource(
path="https://raw.githubusercontent.com/volcengine/OpenViking/refs/heads/main/README.md",
- wait=False, # Non-blocking, process in background
)
- root_uri = result.get("root_uri", "")
- print(f" Root URI: {root_uri}")
-
- # Get the file count
- files = client.ls(uri=root_uri)
- print(f" Files indexed: {len(files)}")
+ task_id = result["task_id"]
+ print(f" Import task: {task_id}")
except Exception as e:
print(f" Error adding resource: {e}")
- root_uri = ""
+ task_id = None
+
+ print()
+
+ # ============================================================
+ # 3. Tracking the Import Task
+ # ============================================================
+ print("3. Checking import progress...")
+ print("-" * 40)
+
+ root_uri = ""
+ if task_id:
+ try:
+ while True:
+ task = client.get_task(task_id)
+ if task is None:
+ raise RuntimeError(f"Task {task_id} is no longer available")
+ if task["status"] == "completed":
+ break
+ if task["status"] in {"failed", "cancelled"}:
+ raise RuntimeError(
+ f"Import task {task_id}: {task['status']} ({task.get('error')})"
+ )
+ time.sleep(2)
+ root_uri = task["result"]["root_uri"]
+ print(f" Processing complete: {root_uri}")
+ except Exception as e:
+ print(f" Import task {task_id}: {e}")
print()
# ============================================================
- # 3. Browsing the Virtual Filesystem
+ # 4. Browsing the Virtual Filesystem
# ============================================================
- print("3. Browsing the virtual filesystem...")
+ print("4. Browsing the virtual filesystem...")
print("-" * 40)
if root_uri:
@@ -110,22 +133,6 @@ def main():
print()
- # ============================================================
- # 4. Waiting for Semantic Processing
- # ============================================================
- print("4. Waiting for semantic processing...")
- print("-" * 40)
-
- try:
- # Wait for all async operations to complete
- status = client.wait_processed(timeout=60)
- print(f" Processing complete: {status}")
- except Exception as e:
- print(f" Note: {e}")
- print(" Continuing without waiting...")
-
- print()
-
# ============================================================
# 5. Tiered Context Loading
# ============================================================
diff --git a/examples/quick_start.py b/examples/quick_start.py
index 976557d1d..bf5769c87 100644
--- a/examples/quick_start.py
+++ b/examples/quick_start.py
@@ -10,6 +10,8 @@ Then, in another terminal:
python examples/quick_start.py
"""
+import time
+
from openviking_sdk import SyncHTTPClient
client = SyncHTTPClient(url="http://localhost:1933")
@@ -17,13 +19,23 @@ client = SyncHTTPClient(url="http://localhost:1933")
try:
client.initialize()
- # Add resource (URL, file, or directory) and wait until it is ready to inspect
- print("Wait for semantic processing...")
+ # Submit an import, then check its task with separate status requests
res = client.add_resource(
path="https://raw.githubusercontent.com/volcengine/OpenViking/refs/heads/main/README.md",
- wait=True,
)
- root_uri = res["root_uri"]
+
+ task_id = res["task_id"]
+ print(f"Import task: {task_id}")
+ while True:
+ task = client.get_task(task_id)
+ if task is None:
+ raise RuntimeError(f"Task {task_id} is no longer available")
+ if task["status"] == "completed":
+ break
+ if task["status"] in {"failed", "cancelled"}:
+ raise RuntimeError(f"Import task {task_id}: {task['status']} ({task.get('error')})")
+ time.sleep(2)
+ root_uri = task["result"]["root_uri"]
res = client.ls(uri=root_uri) # Explore resource tree
print(f"Directory structure:\n{res}\n")
diff --git a/openviking/service/resource_service.py b/openviking/service/resource_service.py
index 7cca717e2..9055cd9bb 100644
--- a/openviking/service/resource_service.py
+++ b/openviking/service/resource_service.py
@@ -1870,7 +1870,9 @@ class ResourceService:
timeout=timeout,
)
except TimeoutError as exc:
- raise DeadlineExceededError("add resource task", timeout) from exc
+ raise DeadlineExceededError(
+ "waiting for resource import", timeout, task_id=task_id
+ ) from exc
if task.status == TaskStatus.COMPLETED:
completed = dict(task.result)
diff --git a/openviking_cli/exceptions.py b/openviking_cli/exceptions.py
index 68b934e3d..133ae1300 100644
--- a/openviking_cli/exceptions.py
+++ b/openviking_cli/exceptions.py
@@ -155,13 +155,24 @@ class InternalError(OpenVikingError):
class DeadlineExceededError(OpenVikingError):
"""Operation timed out."""
- def __init__(self, operation: str = "operation", timeout: Optional[float] = None):
+ def __init__(
+ self,
+ operation: str = "operation",
+ timeout: Optional[float] = None,
+ *,
+ task_id: Optional[str] = None,
+ ):
message = f"{operation.capitalize()} timed out"
if timeout:
message += f" after {timeout}s"
- super().__init__(
- message, code="DEADLINE_EXCEEDED", details={"operation": operation, "timeout": timeout}
- )
+ details = {"operation": operation, "timeout": timeout}
+ if task_id is not None:
+ message += (
+ ". This timeout only stops waiting; it does not cancel or fail the background task. "
+ f"Check its status with 'ov task status {task_id}'."
+ )
+ details["task_id"] = task_id
+ super().__init__(message, code="DEADLINE_EXCEEDED", details=details)
class UnimplementedError(OpenVikingError):
diff --git a/sdk/go/README.md b/sdk/go/README.md
index 9385872ac..7d868b60f 100644
--- a/sdk/go/README.md
+++ b/sdk/go/README.md
@@ -60,13 +60,22 @@ This SDK does not implement legacy `agent_id` compatibility.
## Common Operations
+Imports return a `task_id` by default. Query `client.GetTask(ctx, taskID)` to check progress.
+
```go
// Add a local file or remote URL. Local files/directories are uploaded first.
resource, err := client.AddResource(ctx, "./docs/readme.md", &openviking.AddResourceOptions{
- To: "viking://resources/docs",
- Wait: true,
+ To: "viking://resources/docs",
})
+if err != nil {
+ return err
+}
+fmt.Println(resource["task_id"])
+```
+
+After the import task reaches `completed`, read or search the imported content:
+```go
// Read and update content.
content, err := client.Read(ctx, "viking://resources/docs/readme.md", 0, -1)
updated, err := client.Write(ctx, "viking://resources/docs/readme.md", content+"\n\nUpdated.", &openviking.WriteOptions{
@@ -195,10 +204,16 @@ uploads are zipped by the SDK, symlinks are skipped, and the resulting archive
is uploaded to `/api/v1/resources/temp_upload` before the final API call.
```go
-_, err := client.AddSkill(ctx, "./skills/search-web", &openviking.AddSkillOptions{
- Wait: true,
-})
+skill, err := client.AddSkill(ctx, "./skills/search-web", nil)
+if err != nil {
+ return err
+}
+fmt.Println(skill["task_id"])
+```
+
+After the skill task reaches `completed`:
+```go
skills, err := client.ListSkills(ctx, nil)
found, err := client.FindSkills(ctx, "search the web", &openviking.FindSkillsOptions{
Limit: 5,
diff --git a/sdk/go/README_CN.md b/sdk/go/README_CN.md
index 04bc19f2a..526e8bf2b 100644
--- a/sdk/go/README_CN.md
+++ b/sdk/go/README_CN.md
@@ -113,11 +113,19 @@ _, err = client.AdminRegenerateKeyWithOptions(ctx, "acme", "alice", &openviking.
## 技能和 Watch 示例
+导入默认返回 `task_id`。通过 `client.GetTask(ctx, taskID)` 查询状态。
+
```go
-_, err := client.AddSkill(ctx, "./skills/search-web", &openviking.AddSkillOptions{
- Wait: true,
-})
+skill, err := client.AddSkill(ctx, "./skills/search-web", nil)
+if err != nil {
+ return err
+}
+fmt.Println(skill["task_id"])
+```
+
+任务为 `completed` 后再检索导入的技能:
+```go
skills, err := client.ListSkills(ctx, nil)
found, err := client.FindSkills(ctx, "search the web", &openviking.FindSkillsOptions{
Limit: 5,
diff --git a/sdk/python/README.md b/sdk/python/README.md
index 5ae94476c..5eac9eea3 100644
--- a/sdk/python/README.md
+++ b/sdk/python/README.md
@@ -225,6 +225,8 @@ print(result)
### Add a Resource from a Local File
+`add_resource` returns a `task_id` by default. Query `client.get_task(result["task_id"])` and use the processed output after the task reaches `completed`.
+
`add_resource` handles file upload for local paths automatically.
```python
@@ -236,7 +238,6 @@ client.initialize()
result = client.add_resource(
path="/path/to/notes.md",
to="viking://resources/demo-notes",
- wait=True,
options={
"reason": "knowledge import",
},
@@ -252,7 +253,6 @@ or refresh `.abstract.md` / `.overview.md`.
result = client.add_resource(
path="/path/to/notes.md",
to="viking://resources/demo-notes",
- wait=True,
options={
"processing_mode": "vectors_only",
},
diff --git a/sdk/python/README_CN.md b/sdk/python/README_CN.md
index 3dfbf46d4..4ab814f54 100644
--- a/sdk/python/README_CN.md
+++ b/sdk/python/README_CN.md
@@ -222,6 +222,8 @@ print(result)
### 从本地文件添加资源
+`add_resource` 默认返回 `task_id`。通过 `client.get_task(result["task_id"])` 查询状态,任务为 `completed` 后再使用处理结果。
+
`add_resource` 会自动处理本地路径对应的文件上传。
```python
@@ -233,7 +235,6 @@ client.initialize()
result = client.add_resource(
path="/path/to/notes.md",
to="viking://resources/demo-notes",
- wait=True,
options={
"reason": "knowledge import",
},
@@ -248,7 +249,6 @@ print(result)
result = client.add_resource(
path="/path/to/notes.md",
to="viking://resources/demo-notes",
- wait=True,
options={
"processing_mode": "vectors_only",
},
diff --git a/sdk/typescript/README.md b/sdk/typescript/README.md
index 3350e3543..d4ed8ada7 100644
--- a/sdk/typescript/README.md
+++ b/sdk/typescript/README.md
@@ -27,13 +27,15 @@ Existing local file paths are uploaded automatically, and local directories are
To ingest content without VLM semantic understanding, pass `processingMode: "vectors_only"` to `addResource`. This writes or syncs the resource tree and vectorizes current files, but does not generate or refresh `.abstract.md` / `.overview.md`.
```ts
-await client.addResource("./docs/guide.md", {
+const task = await client.addResource("./docs/guide.md", {
to: "viking://resources/guide",
processingMode: "vectors_only",
- wait: true,
});
+console.log(task.task_id);
```
+Query `client.getTask(task.task_id as string)` for import status and search the imported content after the task reaches `completed`.
+
Event-memory tags can be configured as session defaults, updated later, or overridden per commit. Passing `[]` to `commitSession` explicitly skips the session defaults for that commit.
```ts
diff --git a/sdk/typescript/README_CN.md b/sdk/typescript/README_CN.md
index 17d0e3bef..a293a403f 100644
--- a/sdk/typescript/README_CN.md
+++ b/sdk/typescript/README_CN.md
@@ -27,13 +27,15 @@ Node.js 中存在的本地文件路径会自动上传,目录会先压缩后上
如果只希望入库并生成向量、不走 VLM 语义理解,可以给 `addResource` 传 `processingMode: "vectors_only"`。该模式会写入/同步资源树并向量化当前文件,但不会生成或刷新 `.abstract.md` / `.overview.md`。
```ts
-await client.addResource("./docs/guide.md", {
+const task = await client.addResource("./docs/guide.md", {
to: "viking://resources/guide",
processingMode: "vectors_only",
- wait: true,
});
+console.log(task.task_id);
```
+通过 `client.getTask(task.task_id as string)` 查询导入状态,任务为 `completed` 后再检索导入内容。
+
事件记忆 tags 可设置为 session 默认值、后续更新,也可在单次 commit 时覆盖。向 `commitSession` 传 `[]` 表示本次显式跳过 session 默认 tags。
```ts
diff --git a/tests/server/test_api_resources.py b/tests/server/test_api_resources.py
index 1bd330753..7c7b7a5a0 100644
--- a/tests/server/test_api_resources.py
+++ b/tests/server/test_api_resources.py
@@ -161,10 +161,12 @@ async def test_add_resource_success(
assert body["result"]["task_id"]
[email protected]("timeout", [None, 0.0])
async def test_add_resource_with_wait(
client: httpx.AsyncClient,
sample_markdown_file,
upload_temp_dir,
+ timeout,
):
resp = await client.post(
"/api/v1/resources",
@@ -172,8 +174,23 @@ async def test_add_resource_with_wait(
"temp_file_id": sample_markdown_file.name,
"reason": "test resource",
"wait": True,
+ "timeout": timeout,
},
)
+ if timeout == 0.0:
+ assert resp.status_code == 504
+ error = resp.json()["error"]
+ assert error["code"] == "DEADLINE_EXCEEDED"
+ task_id = error["details"]["task_id"]
+ assert error["details"]["timeout"] == timeout
+ assert "Waiting for resource import timed out" in error["message"]
+ assert "does not cancel or fail the background task" in error["message"]
+ assert f"ov task status {task_id}" in error["message"]
+ task = await _wait_task_terminal(client, task_id)
+ assert task["status"] == "completed"
+ assert "root_uri" in task["result"]
+ return
+
assert resp.status_code == 200
body = resp.json()
assert body["status"] == "ok"