Skip to content

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

docs: align capabilities and roadmap with current implementation (#5187)

Zayn Jarvis891bb72095b8
diff --git a/docs/en/about/03-roadmap.md b/docs/en/about/03-roadmap.md
index 1f7f6931c..0bd0c6d85 100644
--- a/docs/en/about/03-roadmap.md
+++ b/docs/en/about/03-roadmap.md
@@ -1,114 +1,19 @@
# Roadmap
-This document outlines the development roadmap for OpenViking.
+This page describes the current `main` branch and future directions, without committing to release dates or priorities. For packaged versions, check [release notes](https://github.com/volcengine/OpenViking/releases).
-## Completed Features
+## Implemented on main
-### Core Infrastructure
-- Three-layer information model (L0/L1/L2)
-- Viking URI addressing system
-- Dual-layer storage (AGFS + Vector Index)
-- Async/Sync client support
-- QueueFS with SQLite backend
+- **Context and retrieval:** L0/L1/L2 context layers, Viking URIs, semantic search, and context-aware retrieval. [Concepts](../concepts/03-context-layers.md)
+- **Resources:** document, code, web, and media imports; scheduled refreshes for re-readable sources. Audio/video files can be stored; understanding requires an enabled, compatible VLM. [Resources](../api/02-resources.md)
+- **Updates and history:** freshness-aware parent-summary refreshes and Git-backed snapshot commit, history, and restore. Parent refreshes can be deferred; snapshots require explicit commits and restore file content, not historical ACLs or vector indexes. [Context layers](../concepts/03-context-layers.md) · [Snapshots](../guides/15-snapshot.md)
+- **Sessions and memory:** conversation tracking, memory extraction, and session archival. [Sessions](../concepts/08-session.md)
+- **Access and integration:** HTTP API, SDKs, CLI, MCP, and agent plugins. [API overview](../api/01-overview.md) · [MCP guide](../guides/06-mcp-integration.md)
+- **Operations:** JSON configuration (`ov.conf`), multiple model providers, tenant isolation, encryption, observability, and local/S3 storage. [Configuration](../guides/01-configuration.md) · [Deployment](../guides/03-deployment.md)
-### Resource Management
-- Text resource management (Markdown, HTML, PDF)
-- Automatic L0/L1 generation
-- Semantic search with vector indexing
-- Content write API
-- Agent namespace management
+## Future directions
-### Multi-modal Parsing
-- Image OCR and parsing
-- Audio transcription (Whisper ASR)
-- Video parsing
-- PDF with bookmark extraction
-- Word, PowerPoint, Excel, EPub, ZIP parsers
-- Code file parsing
-- Feishu/Lark document parser
+- Further distributed-storage development.
+- More agent-framework adapters.
-### Retrieval
-- Basic semantic search (`find`)
-- Context-aware search with intent analysis (`search`)
-- Session-based query expansion
-- Reranking pipeline with multiple providers (OpenAI, LiteLLM, Cohere, Volcengine)
-
-### Session & Memory
-- Conversation state tracking
-- Context and skill usage tracking
-- Automatic memory extraction
-- Memory deduplication with LLM
-- Session archiving and compression
-- Working Memory V2 with cold-storage archival
-
-### Skills
-- Skill definition and storage
-- MCP tool auto-conversion
-- Skill search and retrieval
-
-### Multi-tenant & Security
-- Multi-tenant support with account isolation
-- File and document encryption
-- User-level privacy configs API
-- API Key authentication
-
-### Configuration & Providers
-- Pluggable embedding providers (OpenAI, Gemini, Volcengine, MiniMax, LiteLLM, Jina, Cohere, DashScope, Voyage, local)
-- Pluggable LLM providers
-- Pluggable rerank providers
-- YAML-based configuration
-- Setup wizard (`openviking-server init`)
-
-### Server & Client Architecture
-- HTTP Server (FastAPI)
-- Native MCP endpoint built into openviking-server
-- Python HTTP Client
-- Python HTTP client SDK
-- Web Console
-
-### CLI
-- Rust CLI (`ov` command)
-- TUI filesystem navigator
-- Privacy, search, session, resource, and admin commands
-
-### Bot Integration
-- VikingBot framework
-- Feishu/Lark channel
-- Telegram channel
-
-### Ecosystem & Plugins
-- OpenClaw plugin (context engine for coding agents)
-- Claude Code memory plugin
-- Codex memory plugin
-
-### Observability
-- Prometheus metrics
-- OpenTelemetry tracing
-- HTTP observability middleware
-
-### Deployment
-- Docker image and Docker Compose
-- Helm Chart for Kubernetes
-- Cloud VikingDB support
-
----
-
-## Future Plans
-
-### Context Management
-- Propagation updates when context is modified
-- Version management and rollback for context (git-like)
-
-### Distributed Storage
-- Distributed storage backend
-
-### Ecosystem
-- Additional Agent framework adapters
-
-We welcome suggestions and feedback in issues.
-
----
-
-## Contributing
-
-We welcome contributions to help achieve these goals. See [Contributing](https://github.com/volcengine/OpenViking/blob/main/CONTRIBUTING.md) for guidelines.
+Track proposals and discuss scope in [GitHub issues](https://github.com/volcengine/OpenViking/issues). To contribute, see the [contribution guide](https://github.com/volcengine/OpenViking/blob/main/CONTRIBUTING.md).
diff --git a/docs/en/api/01-overview.md b/docs/en/api/01-overview.md
index b3280a6f8..1003e123e 100644
--- a/docs/en/api/01-overview.md
+++ b/docs/en/api/01-overview.md
@@ -302,12 +302,13 @@ JSON output - error:
**Note**: Exit codes are return codes from the CLI (command line tool), not HTTP API status codes.
-| Code | Meaning |
-|------|---------|
-| 0 | Success |
-| 1 | General error |
-| 2 | Configuration error |
-| 3 | Connection error |
+| Code | Meaning | Trigger |
+|------|---------|---------|
+| 0 | Success | Command completed successfully |
+| 1 | Runtime error | Command execution failed, including API or connection errors |
+| 2 | Arguments or configuration error | Invalid command-line arguments, configuration loading failed, missing required credentials, or `--sudo` used with an unsupported command |
+
+The current Rust CLI reports connection failures with exit code `1`; it does not use a separate connection-error exit code `3`.
## Error Codes
diff --git a/docs/en/api/02-resources.md b/docs/en/api/02-resources.md
index 88a175e66..459bd899a 100644
--- a/docs/en/api/02-resources.md
+++ b/docs/en/api/02-resources.md
@@ -40,8 +40,10 @@ OpenViking supports various resource types, categorized by functionality:
| Type | Resource Name | Description |
|------|---------------|-------------|
| Images | `*.jpg`, `*.jpeg`, `*.png`, `*.gif` ... | Various image formats, descriptions generated via VLM (Experimental) |
-| Video | `*.mp4`, `*.avi`, `*.mov` ... | Extracts keyframes and analyzes with VLM (Planning) |
-| Audio | `*.mp3`, `*.wav`, `*.m4a` ... | Performs speech transcription (Planning) |
+| Video | `*.mp4`, `*.avi`, `*.mov` ... | Stores the original file; optional VLM understanding requires compatible media configuration |
+| Audio | `*.mp3`, `*.wav`, `*.m4a` ... | Stores the original file; optional VLM understanding requires compatible media configuration |
+
+Audio/video parsers validate and store the original files. Content understanding runs later during semantic processing and is disabled by default (`vlm.media.enabled=false`). Enable it with a compatible provider/model; understanding formats and size limits differ from import formats. This is not a built-in Whisper transcription or local keyframe-extraction pipeline. See [audio/video configuration](../guides/01-configuration.md).
**Cloud Documents**
@@ -112,7 +114,7 @@ Resource incremental updates are implemented via the **Watch Task** mechanism:
#### Watch Task Creation
- 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 a static snapshot and cannot be watched; re-add it when the local source changes
+- Uploaded content referenced by `temp_file_id` is a static snapshot and cannot be watched. The Python HTTP SDK also uploads local files/directories as snapshots, so do not combine a local path with `watch_interval > 0`; 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
@@ -395,9 +397,9 @@ result = client.add_resource(
# Check the latest import task; use its results after it reaches completed
print(client.get_task(result["task_id"]))
-# Enable scheduled updates
+# Enable scheduled updates for a re-readable URL
client.add_resource(
- path="./documents/guide.md",
+ path="https://example.com/guide.md",
to="viking://resources/guide.md",
options={
"watch_interval": 60, # Update every 60 minutes
diff --git a/docs/en/api/06-retrieval.md b/docs/en/api/06-retrieval.md
index bd0b01ebf..7fc6f07bb 100644
--- a/docs/en/api/06-retrieval.md
+++ b/docs/en/api/06-retrieval.md
@@ -59,7 +59,7 @@ The `find()` method performs pure vector similarity search for simple query scen
| target_uri | str \| List[str] | No | "" | Limit search to specific URI prefix |
| context_type | str \| List[str] | No | None | Limit results to one or more `ContextType` values: `memory`, `resource`, or `skill` |
| tags | List[str] | No | None | Explicit retrieval tags in strict `k=v` form. Multiple tags are combined with AND; a result must contain every requested tag |
-| node_limit | int | No | None | Maximum number of results |
+| node_limit | int | No | None | Optional HTTP alias; overrides `limit` when provided |
| score_threshold | float | No | None | Minimum relevance score threshold |
| filter | Dict | No | None | Metadata filter |
| since | str | No | None | Lower time bound, accepts `2h` or ISO 8601 / `YYYY-MM-DD`. Timezone-less values are interpreted as UTC. CLI `--after` maps to this field |
@@ -397,7 +397,7 @@ The `search()` method adds session context understanding and intent analysis cap
| session_id | str | No | None | Session ID for context-aware search (HTTP) |
| context_type | str \| List[str] | No | None | Limit results to one or more `ContextType` values: `memory`, `resource`, or `skill` |
| tags | List[str] | No | None | Explicit retrieval tags in strict `k=v` form. Multiple tags are combined with AND; a result must contain every requested tag |
-| node_limit | int | No | None | Maximum number of results |
+| node_limit | int | No | None | Optional HTTP alias; overrides `limit` when provided |
| score_threshold | float | No | None | Minimum relevance score threshold |
| filter | Dict | No | None | Metadata filter |
| since | str | No | None | Lower time bound, accepts `2h` or ISO 8601 / `YYYY-MM-DD`. Timezone-less values are interpreted as UTC. CLI `--after` maps to this field |
diff --git a/docs/en/concepts/03-context-layers.md b/docs/en/concepts/03-context-layers.md
index 50c1f280b..d8ea0f56d 100644
--- a/docs/en/concepts/03-context-layers.md
+++ b/docs/en/concepts/03-context-layers.md
@@ -144,17 +144,13 @@ API authentication guide covering OAuth 2.0, JWT tokens, and API keys.
- `total_entries`: total direct files and direct subdirectories contributing to directory semantics.
- `sampled_entries`: direct entries used for this summary.
- `unsampled_entries`: direct entries not sampled, with `sampled + unsampled = total`.
-- `pending_child_changes`: known changed direct entries not yet reflected in the current body.
+- `pending_child_changes`: direct-child change events not yet reflected in the current body (repeated changes to one child count separately).
When the direct-entry count exceeds `semantic.overview_sample_limit` (32 by default), OpenViking uses deterministic, order-preserving stable sampling. Repeated refreshes of an unchanged tree choose the same sample, avoiding noisy body rewrites and Git diffs.
`pending_child_changes > 0` means the body is still readable but is known to lag behind lower-level changes. A successful parent refresh resets the value to 0 as part of the new coverage metadata.
-Currently, every successful resource/skill semantic task schedules the next parent refresh and marks the parent pending before enqueue, continuing to the namespace-root boundary.
-
-> **TODO: control bubbling frequency with freshness**
->
-> The current implementation attempts to bubble after every successful resource/skill semantic task, even when the newly generated child summary is unchanged. This is not the intended final scheduling policy. A future implementation should use `freshness` to coalesce, threshold, or time-window parent refreshes—for example by considering `pending_child_changes`, sampling coverage, direct-child change volume, and recent refresh state. The goal is to reduce repeated refreshes and upward write amplification in hot directories while preserving eventual consistency.
+Resource/skill parent refreshes are freshness-aware. An unchanged child L0 body does not trigger propagation. A changed body triggers an immediate refresh when the parent has no freshness baseline, or its direct-entry count is at most `semantic.overview_sample_limit`. Larger directories accumulate `pending_child_changes` and refresh when its ratio to `total_entries` reaches `semantic.freshness_refresh_ratio` (default `0.10`). Manual refresh/import bypasses the threshold for its requested root, not every ancestor. Propagation stops at the namespace-root boundary. Below the threshold, the parent stays readable but pending; the threshold policy does not promise a timed refresh.
## Write Protection
diff --git a/docs/en/concepts/06-extraction.md b/docs/en/concepts/06-extraction.md
index 05f3e7d5d..ac46e334b 100644
--- a/docs/en/concepts/06-extraction.md
+++ b/docs/en/concepts/06-extraction.md
@@ -126,13 +126,7 @@ L0/L1 are directory sidecars, not per-file sidecars. Parent-summary generation c
### Freshness, Sampling, and Parent Refresh
-Each generation records direct-child `total_entries`, `sampled_entries`, and `unsampled_entries`. When the direct-child count exceeds `semantic.overview_sample_limit` (32 by default), OpenViking uses deterministic stable sampling. `pending_child_changes` increases when a known child change is not yet reflected in the parent body and resets to 0 after a successful refresh.
-
-Currently, each successful resource/skill semantic task schedules the next parent refresh and marks that parent pending before enqueue, continuing to the namespace-root boundary.
-
-> **TODO: control bubbling frequency with freshness**
->
-> Bubbling after every successful task can create repeated refreshes and upward write amplification in hot, deeply nested directories. A future scheduler should use `pending_child_changes`, sampling coverage, direct-child change volume, and recent refresh state to coalesce, threshold, or time-window parent refreshes while preserving eventual consistency.
+Each generation records direct-child coverage and uses stable sampling above `semantic.overview_sample_limit` (default 32). Resource/skill parent refreshes depend on child L0 body changes and freshness thresholds; unchanged L0 bodies do not propagate. `pending_child_changes` counts change events awaiting refresh, including repeated changes to the same child. See [Context Layers](03-context-layers.md#freshness-and-stable-sampling) for thresholds, manual refresh behavior, and deferred updates.
### Processing Limits
diff --git a/docs/zh/about/03-roadmap.md b/docs/zh/about/03-roadmap.md
index d2193d02b..3719a5681 100644
--- a/docs/zh/about/03-roadmap.md
+++ b/docs/zh/about/03-roadmap.md
@@ -1,115 +1,19 @@
# 路线图
-本文档概述 OpenViking 的开发路线图。
+本页区分当前 `main` 分支的实现与后续方向,不承诺发布时间或优先级。已发布版本请查阅 [release notes](https://github.com/volcengine/OpenViking/releases)。
-## 已完成功能
+## main 已实现
-### 核心基础设施
-- 三层信息模型(L0/L1/L2)
-- Viking URI 寻址系统
-- 双层存储(AGFS + 向量索引)
-- 异步/同步客户端支持
-- QueueFS SQLite 存储后端
+- **上下文与检索:** L0/L1/L2 分层、Viking URI、语义搜索和上下文感知检索。[概念说明](../concepts/03-context-layers.md)
+- **资源:** 文档、代码、网页和媒体导入,可重复读取来源的定时更新。音视频文件可保存;内容理解需要启用兼容的 VLM。[资源管理](../api/02-resources.md)
+- **更新与历史:** 根据 freshness 刷新父目录摘要,以及基于 Git 的快照提交、历史查询和恢复。父目录刷新可能延后;快照需显式提交,恢复的是文件内容,不含历史 ACL 或向量索引。[上下文分层](../concepts/03-context-layers.md) · [快照指南](../guides/15-snapshot.md)
+- **会话与记忆:** 对话追踪、记忆提取和会话归档。[会话说明](../concepts/08-session.md)
+- **接入与集成:** HTTP API、SDK、CLI、MCP 和 Agent 插件。[API 概览](../api/01-overview.md) · [MCP 指南](../guides/06-mcp-integration.md)
+- **运维:** JSON 配置(`ov.conf`)、多模型供应商、租户隔离、加密、可观测性和本地/S3 存储。[配置指南](../guides/01-configuration.md) · [部署指南](../guides/03-deployment.md)
-### 资源管理
-- 文本资源管理(Markdown、HTML、PDF)
-- 自动 L0/L1 生成
-- 带向量索引的语义搜索
-- 资源关联和链接
-- 内容写入 API
-- Agent 命名空间管理
+## 后续方向
-### 多模态解析
-- 图像 OCR 和解析
-- 音频转写(Whisper ASR)
-- 视频解析
-- PDF 书签提取
-- Word、PowerPoint、Excel、EPub、ZIP 解析器
-- 代码文件解析
-- 飞书/Lark 文档解析器
+- 继续完善分布式存储。
+- 接入更多 Agent 框架。
-### 检索
-- 基本语义搜索(`find`)
-- 带意图分析的上下文感知搜索(`search`)
-- 基于会话的查询扩展
-- 多供应商重排序流水线(OpenAI、LiteLLM、Cohere、Volcengine)
-
-### 会话与记忆
-- 对话状态追踪
-- 上下文和技能使用追踪
-- 自动记忆提取
-- 使用 LLM 的记忆去重
-- 会话归档和压缩
-- Working Memory V2 及冷存储归档
-
-### 技能
-- 技能定义和存储
-- MCP 工具自动转换
-- 技能搜索和检索
-
-### 多租户与安全
-- 多租户支持与账户隔离
-- 文件和文档加密
-- 用户级隐私配置 API
-- API Key 认证
-
-### 配置与供应商
-- 可插拔的 Embedding 提供者(OpenAI、Gemini、Volcengine、MiniMax、LiteLLM、Jina、Cohere、DashScope、Voyage、本地)
-- 可插拔的 LLM 提供者
-- 可插拔的重排序提供者
-- 基于 YAML 的配置
-- 安装向导(`openviking-server init`)
-
-### Server 与 Client 架构
-- HTTP Server(FastAPI)
-- 内置 MCP 端点
-- Python HTTP Client
-- Python HTTP Client SDK
-- Web 控制台
-
-### CLI
-- Rust CLI(`ov` 命令)
-- TUI 文件系统浏览器
-- 隐私、搜索、会话、资源及管理命令
-
-### Bot 集成
-- VikingBot 框架
-- 飞书/Lark 频道
-- Telegram 频道
-
-### 生态与插件
-- OpenClaw 插件(编程 Agent 上下文引擎)
-- Claude Code 记忆插件
-- Codex 记忆插件
-
-### 可观测性
-- Prometheus 指标
-- OpenTelemetry 链路追踪
-- HTTP 可观测性中间件
-
-### 部署
-- Docker 镜像和 Docker Compose
-- Kubernetes Helm Chart
-- 云端 VikingDB 支持
-
----
-
-## 未来计划
-
-### 上下文管理
-- 上下文修改对上层的传导更新
-- 支持对上下文的版本管理和回滚(参考 git)
-
-### 分布式存储
-- 分布式存储后端
-
-### 生态
-- 更多 Agent 框架适配器
-
-欢迎在 issue 中提出建议和反馈。
-
----
-
-## 贡献
-
-我们欢迎贡献以帮助实现这些目标。请参阅 [贡献指南](https://github.com/volcengine/OpenViking/blob/main/CONTRIBUTING_CN.md)。
+提案与范围讨论见 [GitHub issues](https://github.com/volcengine/OpenViking/issues),参与开发见[贡献指南](https://github.com/volcengine/OpenViking/blob/main/CONTRIBUTING_CN.md)。
diff --git a/docs/zh/api/01-overview.md b/docs/zh/api/01-overview.md
index 758129eef..98df1aa4f 100644
--- a/docs/zh/api/01-overview.md
+++ b/docs/zh/api/01-overview.md
@@ -300,9 +300,10 @@ JSON 输出 - 错误:
| 退出码 | 说明 | 触发场景 |
|--------|------|----------|
| 0 | 成功 | 命令执行成功 |
-| 1 | 一般错误 | 命令执行失败(如 API 调用失败、网络错误、找不到二进制文件等) |
-| 2 | 配置错误 | 无法加载 `ovcli.conf` 配置文件、`--sudo` 需要 `root_api_key` 但未配置、`--sudo` 用于非管理员命令 |
-| 3 | 连接错误 | 无法连接到服务器 |
+| 1 | 运行错误 | 命令执行失败,包括 API 调用错误或连接错误 |
+| 2 | 参数或配置错误 | 命令行参数无效、配置加载失败、缺少必要凭据,或将 `--sudo` 用于不支持的命令 |
+
+当前 Rust CLI 的连接失败返回退出码 `1`,不使用单独的连接错误退出码 `3`。
## 错误码
diff --git a/docs/zh/api/02-resources.md b/docs/zh/api/02-resources.md
index 433d32f9d..351f28224 100644
--- a/docs/zh/api/02-resources.md
+++ b/docs/zh/api/02-resources.md
@@ -36,8 +36,10 @@ OpenViking 支持多种资源类型,按照功能分类如下:
| 类型 | 资源名 | 说明 |
|------|--------|------|
| 图片 | `*.jpg`, `*.jpeg`, `*.png`, `*.gif` ... | 多种图片格式,通过 VLM 生成描述(实验特性) |
-| 视频 | `*.mp4`, `*.avi`, `*.mov` ... | 提取关键帧后使用 VLM 分析(规划) |
-| 音频 | `*.mp3`, `*.wav`, `*.m4a` ... | 进行语音转录处理(规划) |
+| 视频 | `*.mp4`, `*.avi`, `*.mov` ... | 保存原文件;可选 VLM 内容理解需要兼容的媒体配置 |
+| 音频 | `*.mp3`, `*.wav`, `*.m4a` ... | 保存原文件;可选 VLM 内容理解需要兼容的媒体配置 |
+
+音视频解析器负责校验并保存原文件。内容理解在后续语义处理阶段执行,默认关闭(`vlm.media.enabled=false`),需启用兼容的供应商和模型;理解支持的格式与大小限制和导入格式不同。这不代表内置了 Whisper 转写或本地关键帧提取流程。详见[音视频配置](../guides/01-configuration.md)。
云文档类
| 类型 | 说明 |
@@ -105,7 +107,7 @@ URL/文件 Parser TreeBuilder AGFS Summarizer/Vector
#### 监控任务创建
- 调用 `add_resource` 时,为 URL、sitemap、RSS 等可重新读取的来源设置 `watch_interval > 0`(单位:分钟),即可创建监控任务
-- `temp_file_id` 引用的上传内容只会作为一次性快照处理,不能创建监控任务;本地来源变化后请重新添加
+- `temp_file_id` 引用的上传内容是一次性快照,不能创建监控任务。Python HTTP SDK 也会将本地文件/目录上传为快照,因此本地路径不能与 `watch_interval > 0` 组合使用;本地来源变化后请重新添加
- 可指定 `to` 参数确定目标 URI;未指定时,系统会使用本次导入返回的 `root_uri` 作为监控目标
- 把监控对象设为 sitemap/RSS/Atom URL,即可让**整站**保持同步:每次刷新重新读取 feed 并重建资源树,新发布的页面自动入库、已删除的页面自动移除
- `WatchManager` 负责任务持久化存储
@@ -400,9 +402,9 @@ result = client.add_resource(
## 查询最近一次导入任务;状态为 completed 后再使用处理结果
print(client.get_task(result["task_id"]))
-## 开启定时更新
+## 为可重复读取的 URL 开启定时更新
client.add_resource(
- path="./documents/guide.md",
+ path="https://example.com/guide.md",
to="viking://resources/guide.md",
options={
"watch_interval": 60, # 每60分钟更新一次
diff --git a/docs/zh/api/03-filesystem.md b/docs/zh/api/03-filesystem.md
index 39e696a49..069093990 100644
--- a/docs/zh/api/03-filesystem.md
+++ b/docs/zh/api/03-filesystem.md
@@ -27,9 +27,10 @@ OpenViking 提供类 Unix 的文件系统操作来管理上下文。
| limit | int | 否 | None | `node_limit` 的别名 |
| sort_by | str | 否 | None | 在分页前,分别按 `name` 或 `mtime` 排序目录组和文件组;目录仍优先 |
| sort_order | str | 否 | `asc` | 排序方向:`asc` 或 `desc` |
+| extra_fields | list[str] | 否 | None | 额外返回的字段:`locked`、`id`、`count` |
| tags | string[] | 否 | 未设置 | 仅返回同时匹配全部 `k=v` 检索标签的条目 |
-`tags` 使用 AND 语义,并在 `offset` 和 `limit` 前应用。带 tags 过滤的响应会返回 `tags`;未过滤时需传 `include_tags=true`(CLI:`-f tags`)才返回它们。`simple=true` 保持仅返回路径。
+`tags` 使用 AND 语义,并在 `offset` 和 `limit` 前应用。带 tags 过滤的响应会返回 `tags`;未过滤时需传 `include_tags=true`(CLI:`-f tags`)才返回它们。HTTP 的 `simple=true` 保持仅返回路径;CLI 同时指定 `--simple` 和 `--fields` 时会获取条目对象,再按指定列输出。
**条目结构**
@@ -139,13 +140,21 @@ curl -G "http://localhost:1933/api/v1/fs/ls" \
**CLI**
```bash
-openviking ls viking://resources/ [--simple] [--recursive] [--tags team=search,env=prod] [-f tags]
-openviking glob "**/*.md" [--uri viking://resources/] [--simple] [--tags team=search,env=prod] [-f tags]
+openviking ls viking://resources/ [--simple] [--recursive] [--tags team=search,env=prod] [-f FIELDS]
+openviking tree viking://resources/my-project/ [--simple] [--tags team=search,env=prod] [-f FIELDS]
+openviking glob "**/*.md" [--uri viking://resources/] [--simple] [--tags team=search,env=prod] [-f FIELDS]
-# 在人类可读列表中显示 tags;不能与 --simple 一起使用
-openviking ls viking://resources/ --fields tags
+# 在对齐的表格中显示名称和 tags
+openviking ls viking://resources/ --fields name,tags
+
+# 无表头,每行输出逗号分隔的 URI 和 tags
+openviking ls viking://resources/ --simple --fields uri,tags
```
+`-f` / `--fields` 接受逗号分隔的列名。在默认的 table 输出模式下,结果为带表头、按列对齐的表格。支持的字段为 `name`、`uri`、`path`、`type`、`size`、`mode`、`mtime`、`locked`、`id`、`count`、`abstract`、`tags`。同时指定 `--simple` 和 `-f` 时,每行输出逗号分隔的字段值,不带表头或树缩进;仅使用 `--simple` 时仍每行输出一个 URI。若未选择 `name`、`uri` 或 `path`,列表会自动补充 `name` 列,树会补充 `path` 列。
+
+CLI 会按所选列请求 `extra_fields`(`locked`、`id`、`count`);选择 `tags` 列时会请求 `include_tags=true`。这些列选择不改变 `tags` 的 AND 过滤语义。
+
**响应**
@@ -185,6 +194,7 @@ openviking ls viking://resources/ --fields tags
| offset | int | 否 | 0 | 跳过的可见节点数 |
| limit | int | 否 | None | `node_limit` 的别名 |
| level_limit | int | 否 | 3 | 最大目录遍历深度 |
+| extra_fields | list[str] | 否 | None | 额外返回的字段:`locked`、`id`、`count` |
| tags | string[] | 否 | 未设置 | 仅保留同时匹配全部 `k=v` 检索标签的节点 |
`tags` 使用 AND 语义,并在 `offset` 和 `limit` 前应用。带 tags 过滤的响应会返回 `tags`;未过滤时需传 `include_tags=true` 才返回它们,否则会省略 tags 以避免额外的向量库读取。
@@ -249,7 +259,10 @@ curl -G "http://localhost:1933/api/v1/fs/tree" \
**CLI**
```bash
-openviking tree viking://resources/my-project/ --fields tags
+openviking tree viking://resources/my-project/ --fields path,type,tags
+
+# 与 ls、glob 一样支持 --simple 和列选择组合
+openviking tree viking://resources/my-project/ --simple --fields path,tags
```
diff --git a/docs/zh/concepts/03-context-layers.md b/docs/zh/concepts/03-context-layers.md
index a38083c14..b82e420bc 100644
--- a/docs/zh/concepts/03-context-layers.md
+++ b/docs/zh/concepts/03-context-layers.md
@@ -144,17 +144,13 @@ API 认证指南,涵盖 OAuth 2.0、JWT 令牌和 API 密钥。
- `total_entries`:参与目录语义的直接文件和直接子目录总数。
- `sampled_entries`:本轮实际用于总结的直接子项数。
- `unsampled_entries`:未采样的直接子项数,满足 `sampled + unsampled = total`。
-- `pending_child_changes`:已知发生变化、但尚未反映到当前正文中的直接子项数。
+- `pending_child_changes`:尚未反映到当前正文中的直接子项变化事件数(同一子项重复变化会分别计数)。
当直接子项超过 `semantic.overview_sample_limit`(默认 32)时,系统使用确定性、保序的稳定采样。相同目录树重复刷新会选择相同样本,避免无意义的正文和 Git diff 抖动。
`pending_child_changes > 0` 表示正文仍然可读,但已知落后于下层变化。父目录刷新成功后,该值会随新的覆盖率元数据重置为 0。
-当前 resource/skill 语义任务成功后会逐级安排父目录刷新,并在入队前将父目录标记为 pending,直到 namespace 根边界。
-
-> **TODO:基于 freshness 控制冒泡频率**
->
-> 当前实现会在每次成功的 resource/skill 语义任务后尝试向父级冒泡,即使新生成的子目录摘要与旧值相同。这不是最终期望的调度策略。后续应利用 `freshness` 数据实现合并、阈值或时间窗口节流,例如综合 `pending_child_changes`、采样覆盖率、直接子项变化规模和最近刷新状态,降低热点目录的重复刷新与向上写放大,同时保证最终一致性。
+resource/skill 的父目录刷新已使用 freshness 决策。子目录 L0 正文不变时,不触发向上传播。正文变化后,若父目录没有 freshness 基线,或直接子项数不超过 `semantic.overview_sample_limit`,则立即安排刷新。更大的目录会累计 `pending_child_changes`,其与 `total_entries` 的比值达到 `semantic.freshness_refresh_ratio`(默认 `0.10`)时才刷新。手动刷新或导入仅对请求的根目录跳过阈值,不会强制刷新所有祖先。传播止于 namespace 根边界。未达阈值时父目录仍可读,但保留 pending 状态;阈值策略不承诺定时刷新。
## 写保护
diff --git a/docs/zh/concepts/06-extraction.md b/docs/zh/concepts/06-extraction.md
index fed7f8b6f..b0713f8d7 100644
--- a/docs/zh/concepts/06-extraction.md
+++ b/docs/zh/concepts/06-extraction.md
@@ -125,13 +125,7 @@ L0/L1 是目录级 sidecar,不是 per-file sidecar。生成父目录摘要时
### Freshness、采样与父级刷新
-每次生成都会记录直接子项的 `total_entries`、`sampled_entries` 和 `unsampled_entries`。直接子项超过 `semantic.overview_sample_limit`(默认 32)时,系统使用确定性稳定采样。已知子项发生变化但父正文尚未刷新时,`pending_child_changes` 会递增;刷新成功后重置为 0。
-
-当前每个成功的 resource/skill 语义任务都会继续安排父目录刷新,并在入队前将父目录标记为 pending。该行为会一直传播到 namespace 根边界。
-
-> **TODO:使用 freshness 控制冒泡频率**
->
-> 当前按每次成功任务冒泡会使热点深层目录产生重复刷新和向上写放大。后续应基于 `pending_child_changes`、采样覆盖率、直接子项变化规模和最近刷新状态进行合并、阈值控制或时间窗口节流,同时保持最终一致性。
+每次生成都会记录直接子项覆盖情况,超过 `semantic.overview_sample_limit`(默认 32)时使用稳定采样。resource/skill 的父级刷新取决于子目录 L0 正文变化和 freshness 阈值,L0 正文不变时不向上传播。`pending_child_changes` 统计等待刷新的变化事件,同一子项重复变化也会分别计数。阈值、手动刷新和延后更新的规则见[上下文层级](03-context-layers.md)。
### 处理限制