Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Python agent-contextagent-memoryagent-pluginsagentic-ragcontext-databasedsh-pluginknowledge-basememorymemory-managementself-evolvingvector-database
docs: improve bilingual onboarding with end-to-end guides and Studio walkthrough (#6772)
Cui Wenzheng557eed123d03
diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.tsindex b74bb0f1f..0a8e6b604 100644--- a/docs/.vitepress/config.ts+++ b/docs/.vitepress/config.ts@@ -135,13 +135,13 @@ function buildLlmsTxt(siteConfig: any) {const allFiles = collectAllMdFiles(srcDir)const files = documentationSections('en').flatMap(section =>- section.groups.flatMap(group => group.pages.map(page => ({+ section.groups.flatMap(group => group.pages.filter(page => !page.reference).map(page => ({relativePath: `en/${page.path}.md`, absPath: path.join(srcDir, `en/${page.path}.md`)}))))const sections = new Map<string, { title: string; url: string }[]>()for (const section of documentationSections('en')) {- sections.set(section.en, section.groups.flatMap(group => group.pages.map(page => ({+ sections.set(section.en, section.groups.flatMap(group => group.pages.filter(page => !page.reference).map(page => ({title: `${group.en} — ${docPageTitle('en', page.path)}`, url: `${siteUrl}${base}/en/${page.path}`}))))}diff --git a/docs/.vitepress/docs-navigation.ts b/docs/.vitepress/docs-navigation.tsindex 831cf4068..9871db94c 100644--- a/docs/.vitepress/docs-navigation.ts+++ b/docs/.vitepress/docs-navigation.ts@@ -21,7 +21,7 @@ export function sectionSidebar(locale: Locale, section: DocSection, includeNextSreturn groups.map(group => ({text: group[locale],items: group.pages.map(page => {- const title = docPageTitle(locale, page.path)+ const title = page[locale] ?? docPageTitle(locale, page.path)const crossSection = sectionForPage(`${locale}/${page.path}.md`)?.id !== section.idconst hint = locale === 'zh' ? '跳转到其他章节' : 'Go to another section'const icon = `<span class="ov-sidebar-cross-link" role="img" aria-label="${hint}" title="${hint}"><svg width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M14 3h7v7m0-7L10 14M10 3H5a2 2 0 0 0-2 2v14a2 2 0 0 0 2 2h14a2 2 0 0 0 2-2v-5"/></svg></span>`@@ -37,7 +37,7 @@ export function documentationSections(locale: Locale) {export function documentationNav(locale: Locale): DefaultTheme.NavItem[] {return sections.map(section => {const paths = [- ...section.groups.flatMap(group => group.pages.map(page => page.path)),+ ...section.groups.flatMap(group => group.pages.filter(page => !page.reference).map(page => page.path)),...Object.keys(legacyPages).filter(page => legacyPages[page] === section.id)]const escaped = paths.map(page => page.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'))@@ -54,7 +54,7 @@ export function documentationSidebars(locale: Locale): DefaultTheme.SidebarMultifor (const section of sections) {const items = sectionSidebar(locale, section)for (const group of section.groups) {- for (const page of group.pages) sidebar[`/${locale}/${page.path}`] = items+ for (const page of group.pages.filter(page => !page.reference)) sidebar[`/${locale}/${page.path}`] = items}for (const [page, owner] of Object.entries(legacyPages)) {if (owner === section.id) sidebar[`/${locale}/${page}`] = itemsdiff --git a/docs/.vitepress/theme/docs-catalog.data.ts b/docs/.vitepress/theme/docs-catalog.data.tsindex bbb0d16ef..f153de2d2 100644--- a/docs/.vitepress/theme/docs-catalog.data.ts+++ b/docs/.vitepress/theme/docs-catalog.data.ts@@ -1,6 +1,7 @@import path from 'node:path'import type { DefaultTheme } from 'vitepress'import { documentationSections } from '../docs-navigation.ts'+import { sectionForPage } from './docs-sections.ts'type CatalogPage = { title: string; href: string; file: string; group: string }@@ -22,6 +23,7 @@ export default {return Object.fromEntries(['en', 'zh'].map((locale: 'en' | 'zh') => [locale,documentationSections(locale).map(section => {const pages = collectPages(section.items || [])+ .filter(page => sectionForPage(`${page.href.slice(1)}.md`)?.id === section.id)const { items, text, groups, nextSteps, ...metadata } = sectionreturn { ...metadata, pages }})diff --git a/docs/.vitepress/theme/docs-catalog.test.ts b/docs/.vitepress/theme/docs-catalog.test.tsindex bbdbabbdc..eb4665632 100644--- a/docs/.vitepress/theme/docs-catalog.test.ts+++ b/docs/.vitepress/theme/docs-catalog.test.ts@@ -41,27 +41,42 @@ for (const locale of ['en', 'zh'] as Locale[]) {assert.equal(conceptPages[0].href, `/${locale}/concepts/00-overview`)})- test(`${locale}: onboarding exits use article titles without duplicating ownership`, () => {+ test(`${locale}: onboarding groups tutorials and references existing integration guides`, () => {const start = sections.find(section => section.id === 'getting-started')!+ assert.equal(start.entry, 'getting-started/02-quickstart')+ assert.deepEqual(start.groups[0].pages.map(page => page.path), [+ 'getting-started/02-quickstart', 'getting-started/01-introduction',+ 'getting-started/07-agent-onboarding',+ 'getting-started/05-cli-setup', 'getting-started/07-options'+ ])const sidebar = documentationSidebars(locale)[`/${locale}/${start.entry}`]assert.ok(Array.isArray(sidebar))const links = sidebar.flatMap(group => group.items ?? [])const owned = data[locale].find(section => section.id === start.id)!.pages- for (const page of owned) {- assert.equal(links.find(item => item.link === page.href)?.text, page.title)+ assert.deepEqual(start.groups.map(group => group.pages.length), [5, 1, 5, 4, 3, 6])+ assert.equal(owned.length, 22)+ assert.equal(links.length, owned.length + 2)+ assert.deepEqual(start.groups.map(group => group.zh), ['开始', 'Studio', '功能', '集成', '数据管理', '团队管理'])+ assert.deepEqual(start.groups[1].pages.map(page => page.path), ['getting-started/23-studio'])+ assert.deepEqual(start.groups[3].pages.map(page => page.path), [+ 'agent-integrations/01-overview', 'workflows/01-overview',+ 'getting-started/11-vikingbot', 'getting-started/12-gateway'+ ])+ for (const [path, title, owner] of [+ ['agent-integrations/01-overview', locale === 'zh' ? 'Agent 接入' : 'Agent integration', 'agent-integrations'],+ ['workflows/01-overview', locale === 'zh' ? '应用开发' : 'Application development', 'build']+ ]) {+ const item = links.find(item => item.link === `/${locale}/${path}`)!+ assert.ok(item.text?.startsWith(title))+ assert.match(item.text!, /ov-sidebar-cross-link/)+ assert.equal(sectionForPage(`${locale}/${path}.md`)?.id, owner)}- const exits = start.nextSteps!.flatMap(group => group.pages)- assert.ok(exits.length > 0)- for (const exit of exits) {- const href = `/${locale}/${exit.path}`- const article = data[locale].flatMap(section => section.pages).find(page => page.href === href)- assert.ok(article, `Exit has no owner: ${href}`)- assert.notEqual(sectionForPage(`${locale}/${exit.path}.md`)?.id, start.id)- assert.ok(!owned.some(page => page.href === href), `Exit duplicated in discovery: ${href}`)- const item = links.find(item => item.link === href)!- assert.equal(item.text?.split('<span')[0], article.title)- assert.match(item.text!, /class="ov-sidebar-cross-link"/)- assert.equal(item.target, undefined)+ for (const page of owned) {+ const item = links.find(item => item.link === page.href)!+ assert.equal(item.text, page.title)+ assert.ok(page.title.length <= (locale === 'zh' ? 12 : 24), page.title)+ assert.equal(sectionForPage(`${page.href.slice(1)}.md`)?.id, start.id)+ assert.doesNotMatch(item.text!, /ov-sidebar-cross-link/)}})diff --git a/docs/.vitepress/theme/docs-sections.ts b/docs/.vitepress/theme/docs-sections.tsindex 510fd74a6..d02f25a1f 100644--- a/docs/.vitepress/theme/docs-sections.ts+++ b/docs/.vitepress/theme/docs-sections.ts@@ -2,7 +2,7 @@// This manifest owns grouping and order; article labels come from Markdown H1.// Top navigation, sidebars, breadcrumbs, the homepage and llms.txt share this structure.export type Locale = 'en' | 'zh'-export type DocPage = { path: string }+export type DocPage = { path: string; reference?: boolean; en?: string; zh?: string }export type DocGroup = { en: string; zh: string; pages: DocPage[] }export type DocSection = {id: string; en: string; zh: string; enNote: string; zhNote: string@@ -10,37 +10,50 @@ export type DocSection = {nextSteps?: DocGroup[]}const p = (path: string): DocPage => ({ path })+const reference = (path: string, en: string, zh: string): DocPage => ({ path, reference: true, en, zh })const g = (en: string, zh: string, pages: DocPage[]): DocGroup => ({ en, zh, pages })export const sections: DocSection[] = [{id: 'getting-started', en: 'Quickstart', zh: '开始使用',enNote: 'Get a first result, evaluate it on your tasks, and choose what to connect.', zhNote: '完成首次体验,用自己的任务验证效果,再选择接入路径。',- entry: 'getting-started/01-introduction', aliases: [],+ entry: 'getting-started/02-quickstart', aliases: [],groups: [- g('Get your first result', '先完成一次体验', [- p('getting-started/01-introduction'),+ g('Start', '开始', [p('getting-started/02-quickstart'),+ p('getting-started/01-introduction'),p('getting-started/07-agent-onboarding'),- p('getting-started/05-cli-setup')+ p('getting-started/05-cli-setup'),+ p('getting-started/07-options')]),- g('Evaluate the result', '验证实际效果', [+ g('Studio', 'Studio', [+ p('getting-started/23-studio')+ ]),+ g('Features', '功能', [+ p('getting-started/08-resources'),+ p('getting-started/09-memory'),+ p('getting-started/10-skills'),+ p('getting-started/16-rules'),p('getting-started/06-evaluate')- ])- ],- // Cross-section exits aid onboarding without changing article ownership.- nextSteps: [- g('Use it in your work', '接入你的工作', [- p('agent-integrations/01-overview'),- p('workflows/01-overview'),- p('context-compilation/01-overview'),- p('guides/17-vikingbot'),- p('guides/15-gateway')]),- g('Learn, deploy and troubleshoot', '深入与排障', [- p('concepts/00-overview'),- p('guides/00-overview'),- p('guides/05-observability')+ g('Integrations', '集成', [+ reference('agent-integrations/01-overview', 'Agent integration', 'Agent 接入'),+ reference('workflows/01-overview', 'Application development', '应用开发'),+ p('getting-started/11-vikingbot'),+ p('getting-started/12-gateway')+ ]),+ g('Data management', '数据管理', [+ p('getting-started/13-compile'),+ p('getting-started/14-versions'),+ p('getting-started/15-transfer')+ ]),+ g('Team management', '团队管理', [+ p('getting-started/17-authentication'),+ p('getting-started/18-accounts'),+ p('getting-started/19-users'),+ p('getting-started/20-peers'),+ p('getting-started/21-access-control'),+ p('getting-started/22-sharing')])]},@@ -307,6 +320,6 @@ export const legacyPages: Record<string, string> = {export function sectionForPage(relativePath: string): DocSection | undefined {const path = relativePath.replace(/^(en|zh)\//, '').replace(/\.md$/, '')- return sections.find(section => section.groups.some(group => group.pages.some(page => page.path === path)))+ return sections.find(section => section.groups.some(group => group.pages.some(page => !page.reference && page.path === path)))|| sections.find(section => section.id === legacyPages[path])}diff --git a/docs/en/agent-integrations/02-claude-code.md b/docs/en/agent-integrations/02-claude-code.mdindex e5b96b47a..fa99899d4 100644--- a/docs/en/agent-integrations/02-claude-code.md+++ b/docs/en/agent-integrations/02-claude-code.md@@ -45,7 +45,7 @@ If you prefer to set it up manually:</details>-Once installed, start a new Claude Code session and ask it to follow https://docs.openviking.ai/agents/en/onboarding.md. It checks the connection and walks you through the first use; see [Connect your agent with one prompt](../getting-started/07-agent-onboarding.md).+Once installed, start a new Claude Code session and ask it to follow https://docs.openviking.ai/agents/en/onboarding.md. It checks the connection and walks you through the first use; see [One-click setup](../getting-started/07-agent-onboarding.md).## Verifydiff --git a/docs/en/agent-integrations/04-codex.md b/docs/en/agent-integrations/04-codex.mdindex 6ace5f59a..4d986e5bd 100644--- a/docs/en/agent-integrations/04-codex.md+++ b/docs/en/agent-integrations/04-codex.md@@ -57,7 +57,7 @@ Prerequisites: Node.js >= 22, Codex >= 0.130.0, and the `plugin_hooks` feature e</details>-Once installed, start a new Codex session and ask it to follow https://docs.openviking.ai/agents/en/onboarding.md. It checks the connection and walks you through the first use; see [Connect your agent with one prompt](../getting-started/07-agent-onboarding.md).+Once installed, start a new Codex session and ask it to follow https://docs.openviking.ai/agents/en/onboarding.md. It checks the connection and walks you through the first use; see [One-click setup](../getting-started/07-agent-onboarding.md).## Verifydiff --git a/docs/en/agent-integrations/08-community-plugins.md b/docs/en/agent-integrations/08-community-plugins.mdindex 726e9a040..bd54e282c 100644--- a/docs/en/agent-integrations/08-community-plugins.md+++ b/docs/en/agent-integrations/08-community-plugins.md@@ -40,7 +40,7 @@ After restarting ZCode, verify that:Implementation details and currently verified ZCode assumptions are documented in the plugin's [README](https://github.com/volcengine/OpenViking/tree/main/examples/agent-hook-plugin) and [DESIGN.md](https://github.com/volcengine/OpenViking/blob/main/examples/agent-hook-plugin/DESIGN.md).-Once installed, start a new ZCode session and ask it to follow https://docs.openviking.ai/agents/en/onboarding.md. It checks the connection and walks you through the first use; see [Connect your agent with one prompt](../getting-started/07-agent-onboarding.md).+Once installed, start a new ZCode session and ask it to follow https://docs.openviking.ai/agents/en/onboarding.md. It checks the connection and walks you through the first use; see [One-click setup](../getting-started/07-agent-onboarding.md).## Kimi Code memory integration@@ -77,7 +77,7 @@ curl -fsSL https://openviking.ai/install | bash -s -- --uninstall --yes --harnesThe verified host contract and version are recorded in[`hosts/kimicode/DESIGN.md`](https://github.com/volcengine/OpenViking/blob/main/examples/agent-hook-plugin/hosts/kimicode/DESIGN.md).-Once installed, start a new Kimi Code session and ask it to follow https://docs.openviking.ai/agents/en/onboarding.md. It checks the connection and walks you through the first use; see [Connect your agent with one prompt](../getting-started/07-agent-onboarding.md).+Once installed, start a new Kimi Code session and ask it to follow https://docs.openviking.ai/agents/en/onboarding.md. It checks the connection and walks you through the first use; see [One-click setup](../getting-started/07-agent-onboarding.md).## CodeBuddy Code memory integrationdiff --git a/docs/en/agent-integrations/10-opencode.md b/docs/en/agent-integrations/10-opencode.mdindex 0bf328353..0bc591634 100644--- a/docs/en/agent-integrations/10-opencode.md+++ b/docs/en/agent-integrations/10-opencode.md@@ -19,7 +19,7 @@ curl -fsSL https://openviking.ai/install | bashThe installer copies the plugin into `~/.config/opencode/plugins/` as a local file plugin, writes the `openviking` MCP server entry into `~/.config/opencode/opencode.json`, and configures `~/.openviking/ovcli.conf`.-Once installed, start a new OpenCode session and ask it to follow https://docs.openviking.ai/agents/en/onboarding.md. It checks the connection and walks you through the first use; see [Connect your agent with one prompt](../getting-started/07-agent-onboarding.md).+Once installed, start a new OpenCode session and ask it to follow https://docs.openviking.ai/agents/en/onboarding.md. It checks the connection and walks you through the first use; see [One-click setup](../getting-started/07-agent-onboarding.md).### Manual npm installdiff --git a/docs/en/agent-integrations/11-pi.md b/docs/en/agent-integrations/11-pi.mdindex e1d640246..53388469a 100644--- a/docs/en/agent-integrations/11-pi.md+++ b/docs/en/agent-integrations/11-pi.md@@ -30,7 +30,7 @@ npm ci --prefix ~/.pi/agent/extensions/openviking --omit=dev --ignore-scriptsThe extension imports its shared modules from a `shared/` directory that is not in git; `sync.mjs` generates it, so run it before copying. After a `git pull`, run `sync.mjs` again before copying the update.-Once installed, start a new pi session and ask it to follow https://docs.openviking.ai/agents/en/onboarding.md. It checks the connection and walks you through the first use; see [Connect your agent with one prompt](../getting-started/07-agent-onboarding.md).+Once installed, start a new pi session and ask it to follow https://docs.openviking.ai/agents/en/onboarding.md. It checks the connection and walks you through the first use; see [One-click setup](../getting-started/07-agent-onboarding.md).## How it worksdiff --git a/docs/en/agent-integrations/12-cursor.md b/docs/en/agent-integrations/12-cursor.mdindex ebaba2eba..eefab35ec 100644--- a/docs/en/agent-integrations/12-cursor.md+++ b/docs/en/agent-integrations/12-cursor.md@@ -15,7 +15,7 @@ curl -fsSL https://openviking.ai/install | bashQuit Cursor completely and restart it after installation.-Once installed, start a new Cursor session and ask it to follow https://docs.openviking.ai/agents/en/onboarding.md. It checks the connection and walks you through the first use; see [Connect your agent with one prompt](../getting-started/07-agent-onboarding.md).+Once installed, start a new Cursor session and ask it to follow https://docs.openviking.ai/agents/en/onboarding.md. It checks the connection and walks you through the first use; see [One-click setup](../getting-started/07-agent-onboarding.md).## What gets installeddiff --git a/docs/en/agent-integrations/13-trae.md b/docs/en/agent-integrations/13-trae.mdindex 8aa5feb0f..96577837c 100644--- a/docs/en/agent-integrations/13-trae.md+++ b/docs/en/agent-integrations/13-trae.md@@ -33,7 +33,7 @@ You can also use `/hooks` to review the OpenViking commands and trust and enableTRAE and TRAE CN use the installed `hooks.json` and need no hook approval; restart the corresponding client after installation.-Once installed, start a new TRAE session and ask it to follow https://docs.openviking.ai/agents/en/onboarding.md. It checks the connection and walks you through the first use; see [Connect your agent with one prompt](../getting-started/07-agent-onboarding.md).+Once installed, start a new TRAE session and ask it to follow https://docs.openviking.ai/agents/en/onboarding.md. It checks the connection and walks you through the first use; see [One-click setup](../getting-started/07-agent-onboarding.md).## What gets installeddiff --git a/docs/en/agent-integrations/17-dsh.md b/docs/en/agent-integrations/17-dsh.mdindex a1fb1cb45..ced76ad33 100644--- a/docs/en/agent-integrations/17-dsh.md+++ b/docs/en/agent-integrations/17-dsh.md@@ -44,7 +44,7 @@ After installation, use the verification steps below to check tool access and cr</details>-Once installed, start a new DSH session and ask it to follow https://docs.openviking.ai/agents/en/onboarding.md. It checks the connection and walks you through the first use; see [Connect your agent with one prompt](../getting-started/07-agent-onboarding.md).+Once installed, start a new DSH session and ask it to follow https://docs.openviking.ai/agents/en/onboarding.md. It checks the connection and walks you through the first use; see [One-click setup](../getting-started/07-agent-onboarding.md).## Verifydiff --git a/docs/en/getting-started/01-introduction.md b/docs/en/getting-started/01-introduction.mdindex 96922f77b..7bce5bd9a 100644--- a/docs/en/getting-started/01-introduction.md+++ b/docs/en/getting-started/01-introduction.md@@ -1,46 +1,62 @@-# What OpenViking does+# Feature overview-OpenViking is an open-source context database for AI agents. It organizes sources, memories and skills in one virtual file system so agents can find relevant content and reuse it in later tasks.+OpenViking is a context database for AI agents. It organizes resources, memories, skills, and rules as browsable, searchable files. OpenViking supplies context; an agent reads that context to answer questions or carry out tasks.-If your sources are hard to find, you keep repeating background in new conversations, or useful experience is difficult to reuse, choose a path below.+Start with the [quickstart](02-quickstart.md) to get an answer you can check against its source. Then choose a task below. You do not need to read every page in sequence.-## Start with your task+## Start with a task-| What you want to do | First step | Then continue to |+| Your task | What OpenViking provides | Start here || --- | --- | --- |-| Help an agent find evidence in project sources | [Import and retrieve your first document](02-quickstart.md) | Replace the sample with your sources and [evaluate the result](06-evaluate.md) |-| Add cross-session memory to an existing agent | [Choose an agent integration](../agent-integrations/01-overview.md) | Follow its installation guide, then [check memory across two sessions](06-evaluate.md#check-memory-across-two-sessions) |-| Use context in your own application | [Application workflows](../workflows/01-overview.md) | Choose a resource, session or skill workflow, then look up its APIs |-| Turn sources into a wiki, graph or report | [Context Compilation Overview](../context-compilation/01-overview.md) | Choose an output and check it against familiar sources |+| Answer questions using project sources | Import, retrieve, and read source content | [Resource retrieval](08-resources.md) |+| Carry background into a new session | Record sessions, extract memory, and recall it for relevant tasks | [Memory use](09-memory.md) |+| Reuse a working method | Store and retrieve a Skill for an agent to read and apply | [Skill use](10-skills.md) |+| Check tasks and actions against requirements | Compile mandatory constraints and recall rules for an agent to check against the current task | [Rules (Beta)](16-rules.md) |+| Organize sources into readable knowledge | Compile sources into a wiki or another Skill-defined output | [Context compilation](13-compile.md) |-**Not sure where to start?** [Import and retrieve your first document](02-quickstart.md). This path uses a small document to connect, import, retrieve and read the source, without requiring you to study the architecture first.+<a id="three-kinds-of-context"></a>-If you already have a service URL and API key, [install and use the CLI](05-cli-setup.md). To provide a service yourself, choose a [deployment path](../guides/00-overview.md). To use the agent included with OpenViking, see [VikingBot Installation and Configuration](../guides/17-vikingbot.md).+## Context types-## Turn a first result into a working habit+| Type | What it stores | How to check its value |+| --- | --- | --- |+| **Resource** | External documents, web pages, and code | Key conclusions in an answer can be verified against sources |+| **Memory** | Background, preferences, and experience extracted from sessions | A new session uses relevant background without you repeating it |+| **Skill** | Workflow instructions and supporting files | After reading the Skill, the agent produces an output that meets its requirements |+| **Rule (Beta)** | Mandatory requirements under specific conditions, including obligations, prohibitions, and exceptions | The agent checks applicable rules against task evidence and adjusts its actions or answer |++A `viking://` URI identifies content. Read it directly when you know the location; otherwise retrieve matches and open the source. Directory abstracts and overviews support progressive loading; their generation depends on the processing method and configuration.-1. **Get a first result.** Confirm that you can read imported content, beyond checking service health.-2. **Try your own task.** Use sources with known answers or context needed across sessions. Check what is found and used through [Evaluate OpenViking on your tasks](06-evaluate.md).-3. **Connect it to your work.** Choose an agent, application or compilation workflow. Add deployment and access controls when you need to share the service.+**Rules:** For example, “A repository that declares itself open source must provide a locatable license text.” Explicitly compile mandatory requirements from a policy into Rules, then recall them for a specific task. OpenViking supplies the rules and their applicability conditions; the agent uses current evidence to check whether the requirements are met. Rules are in Beta. See [Rules](../concepts/17-rule-scenarios.md) for concepts and usage.-If something fails, use [observability and diagnostics](../guides/05-observability.md) to distinguish connection, processing and retrieval problems.+## Choose an entry point-## How context is organized+-| Context | What it stores |+| Entry point | Use it for || --- | --- |-| Resources | Documents, code repositories and other external sources |-| Memories | Preferences, facts and experience extracted from sessions |-| Skills | Instructions and supporting files for reusable workflows |+| **CLI** | Browse, import, retrieve, and read from a terminal; use `ov chat` with an enabled VikingBot. See [CLI basics](05-cli-setup.md). |+| **Existing agent** | Add context and memory to your daily tool. Capture, commit, and recall behavior varies by plugin; verify behavior in a new session after installation. |+| **VikingBot** | Use the built-in agent for answers and tool-based tasks. The [quickstart](02-quickstart.md) follows this route. |+| **Gateway** | Connect a compatible client's model requests to context and memory. Verify the integration through capture, extraction, and recall results. |+| **SDK / HTTP** | Control import, retrieval, sessions, and data management from your own application. |++OpenViking manages and supplies context. The CLI, plugins, gateway, and agents have distinct responsibilities. For deeper integration, see [Agent integrations](../agent-integrations/01-overview.md), [Gateway setup](12-gateway.md), or [SDK and HTTP conventions](../api/01-overview.md).-Content is addressed by a `viking://` URI. Browse a known path, or retrieve a match and then read it. [Context Types](../concepts/02-context-types.md) and [Viking URI](../concepts/04-viking-uri.md) explain the objects and their scope.+## Try skills and knowledge organization-## Load context in layers+**Skills:** Choose a workflow with a concrete output, install its Skill, confirm the agent can discover and read it, then run a task and inspect the result. OpenViking stores and retrieves the Skill; the agent activates it, manages tool permissions, and executes the task. See [Skills](10-skills.md) for the operations.-During semantic processing, OpenViking can generate directory abstracts (L0) and overviews (L1), then load source content (L2) when needed. L0 and L1 are directory sidecars; availability depends on processing state and configuration. They are not a fixed pair of summaries for every file. See [Context Layers](../concepts/03-context-layers.md).+**Knowledge organization:** Prepare sources, compile them with the Wiki Skill, wait for completion, and open an output page to check its evidence and omissions. Skill-based compilation needs a configured Compile Runtime. Compare the output with the original sources to check its accuracy. Continue with the [Wiki example](13-compile.md).-## Build memory from sessions+## Next steps-Applications record messages and commit sessions for asynchronous extraction under a memory policy. Plugins can automate some of these steps; check the [capability comparison](../agent-integrations/16-capability-reference.md) for their scope. Inspect the actual output and recall behavior to learn what was retained and used.+Once you have a result, [evaluate your own tasks](06-evaluate.md). If you do not have a service endpoint, compare [deployment modes](07-options.md).-For a reading path through these mechanisms, start with [Concepts and principles](../concepts/00-overview.md). To continue with a task, choose a link under “Use it in your work” in the sidebar.+<!-- Keep incoming links to the previous headings working. -->+<a id="what-openviking-does"></a>+<a id="start-with-your-task"></a>+<a id="turn-a-first-result-into-a-working-habit"></a>+<a id="how-context-is-organized"></a>+<a id="load-context-in-layers"></a>+<a id="build-memory-from-sessions"></a>diff --git a/docs/en/getting-started/02-quickstart.md b/docs/en/getting-started/02-quickstart.mdindex b0e9b9f59..3b1e53c2b 100644--- a/docs/en/getting-started/02-quickstart.md+++ b/docs/en/getting-started/02-quickstart.md@@ -1,106 +1,243 @@-# Import and retrieve your first document+<a id="import-and-retrieve-your-first-document"></a>-OpenViking runs as a server. Connect to it with the standalone `ov` CLI, import a small document, and retrieve its content. If you use a managed service or someone else's deployment, you only need the CLI.+# Quickstart-## 1. Choose a service+To answer questions about your project, an AI agent first needs to find relevant material and read the source. OpenViking is a context database for agents: it stores and retrieves that material so the agent can ground its answers in your sources.-**Already have an endpoint?** Keep its URL and API key ready and skip to step 2. For a server using API key authentication, use a user/admin key for data access; a root key is for administration. See [Authentication](../guides/04-authentication.md).+In this walkthrough, you will import fictional Lighthouse project notes, ask an agent about feedback collection, and open its citations to check the answer. Choose Volcengine's cloud service or run OpenViking locally. Both paths take you through **import → retrieve and read → generate an answer → verify its sources**.-Otherwise, choose one:+## Prerequisites-### Managed service on Volcengine+Choose where to run OpenViking, then prepare the corresponding tools:-Open the [OpenViking console](https://console.volcengine.com/vikingdb/openviking/region:openviking+cn-beijing?utm_source=opensource_docs&utm_medium=referral&utm_campaign=getting-started_02-quickstart) and obtain your key from **User Management → API Key**. The service endpoint is:+| Option | When to choose it | What to prepare |+| --- | --- | --- |+| **Volcengine cloud service** | Use a managed service and ask questions through an existing agent | Node.js/npm, a Volcengine account, and an agent that can run terminal commands on your machine |+| **Local service** | Run OpenViking on your computer with its built-in agent, VikingBot | Node.js/npm, uv, Python, and model credentials |-```text-https://api.vikingdb.cn-beijing.volces.com/openviking+### Install Node.js++Both paths use the `ov` CLI to work with your sources. Open the [Node.js download page](https://nodejs.org/en/download), select an **LTS** release for your operating system, and follow its installer or command instructions. npm is included with Node.js.++Reopen your terminal after installation and confirm that both commands print a version:++```bash+node --version+npm --version+```++For the cloud service, continue to [Set up the service](#set-up-the-service).++### Prepare the local runtime++The local service uses uv to install OpenViking and Python to run it. The commands below use a macOS / Linux terminal. For other systems, see the [uv installation guide](https://docs.astral.sh/uv/getting-started/installation/) and [server deployment](../guides/03-deployment.md).++Install uv first:++```bash+curl -LsSf https://astral.sh/uv/install.sh | sh+```++Reopen your terminal and confirm that uv is available:++```bash+uv --version+```++Then install Python 3.13 for the service:++```bash+uv python install 3.13```-No server installation or local model configuration is needed. See the [product page](https://www.volcengine.com/product/openviking-service?utm_source=opensource_docs&utm_medium=referral&utm_campaign=getting-started_02-quickstart) and [service documentation](https://docs.volcengine.com/docs/84313/2374478) for managed-service usage and limits. Continue to step 2.+You can use an existing Python 3.13 installation. Other installation options are available on the [Python download page](https://www.python.org/downloads/) and in the [uv Python guide](https://docs.astral.sh/uv/guides/install-python/).++Prepare credentials for two models: an **embedding model** for indexing and retrieval, and a **VLM with tool-call support** for content understanding and VikingBot answers. For each, you need a model name, endpoint, and API key. Follow the [Volcengine model activation guide](../guides/02-volcengine-purchase-guide.md) to obtain these details. With Agent Plan, choose a model and endpoint supported by your plan. Importing sources and generating answers invoke models and incur charges according to your provider's pricing.++<a id="_1-start-the-server"></a>++<a id="_1-choose-a-service"></a>++<a id="_1-set-up-the-service"></a>++## Set up the service++Complete one of the following paths, then continue to [Connect the CLI](#connect-the-cli).++<a id="managed-service-on-volcengine"></a>-### Self-host a server+### Volcengine cloud service++The cloud service runs OpenViking and processes your sources. Your computer only needs the client tools.++1. Open the [OpenViking console](https://console.volcengine.com/vikingdb/openviking/region:openviking+cn-beijing), sign in to Volcengine, and follow the console's activation steps. See the [service description](https://docs.volcengine.com/docs/84313/2374478) for plans and quotas.+2. Obtain an **OpenViking API key** from the console for the CLI connection in the next step.+3. Prepare an agent that can run terminal commands on your machine. In “Ask and verify,” it will use `ov` to retrieve cloud-hosted sources and generate an answer. See [CLI basics](05-cli-setup.md) for agent access.++Once you have the API key, continue to [Connect the CLI](#connect-the-cli).++<a id="self-host-a-server"></a>++### Local service++Install OpenViking with VikingBot to manage sources and answer questions on your machine:++```bash+uv tool install --python 3.13 "openviking[bot]" --upgrade+```-[Install uv](https://docs.astral.sh/uv/getting-started/installation/) on the server machine, then install OpenViking:+Run the setup wizard. Choose local access and enter the embedding and VLM settings you prepared. VikingBot uses this VLM configuration by default.```bash-uv tool install openviking --upgradeopenviking-server init+```++Check the model and service configuration. If the check reports an error, correct the indicated setting and run it again:++```bashopenviking-server doctor-openviking-server```-The setup wizard configures the server's models and writes `~/.openviking/ov.conf`. Prepare access to an embedding model and a VLM — Volcengine (Doubao) models are recommended; see the [Volcengine Purchase Guide](../guides/02-volcengine-purchase-guide.md) for purchase and activation — then check the configuration with `doctor`. Keep the server running and use another terminal for the remaining steps.+Once the checks pass, start the service with VikingBot. Keep this terminal running and use another terminal for the remaining commands.-A single curl confirms the server is up — no client required:+```bash+openviking-server --with-bot+```++In the new terminal, check that both the data service and agent are ready:```bash-curl http://127.0.0.1:1933/health-# {"status":"ok","healthy":true,...}+curl -f http://127.0.0.1:1933/health+curl -f http://127.0.0.1:1933/bot/v1/health```-The local endpoint is `http://127.0.0.1:1933`; the default local setup needs no API key. Web Studio is available at `/studio`. For Docker, persistent storage, and remote access, see [Deployment](../guides/03-deployment.md), [Model Configuration](../guides/01-configuration.md), and [Authentication](../guides/04-authentication.md).+Continue when the first response reports `healthy: true` and the Bot response reports `status: healthy`.++<a id="_2-install-and-connect-the-cli"></a>++<a id="_2-connect-the-cli"></a>-## 2. Install and connect the CLI+## Connect the CLI-On your client machine, with Node.js and npm installed:+Install the CLI to import, retrieve, and read sources from your terminal. Skip installation if `ov` is already available.```bashnpm install -g @openviking/cli+```++Set the interface language and open the connection wizard:++```bashov language enov config```-In the interactive configuration, choose **OpenViking Service** for Volcengine or **Custom** for a self-hosted endpoint. Enter the API key and, for a custom service, its URL. Leave the key empty for the default local server. Save and activate the configuration.+Add a connection using the settings for your chosen path, then save and activate it:++| Option | Connection type | Settings |+| --- | --- | --- |+| Volcengine cloud service | **OpenViking Service** | Use the service address provided by the wizard and enter the API key from the console |+| Local service | **Custom** | Set the URL to `http://127.0.0.1:1933`; leave the key empty for default local mode |-The CLI stores the active connection in `~/.openviking/ovcli.conf`. This is separate from the server's `ov.conf`. For multiple endpoints or agent-assisted setup, see [CLI Setup](05-cli-setup.md).+If your local service already has authentication configured, use its User/Admin key. See [Authentication](../guides/04-authentication.md) for setup details.-Verify the connection:+Check the active connection before importing:```bashov health```-This checks that the server responds; the import below also exercises model processing and data access.+<a id="_3-import-a-document"></a>-## 3. Import a document+<a id="_3-import-the-sample"></a>-This example imports a real team fact: the four GitHub users who take turns owning the weekly OpenViking release. Save the following as `ov-release-rotation.md` in your current directory:+## Import the sample-```markdown-# OpenViking release rotation+<a href="/quickstart/lighthouse.en.txt" download="lighthouse.en.md">Download the Lighthouse notes</a>, save them as `lighthouse.en.md`, and open your terminal in that directory. The notes describe the pilot's network constraints, feedback collection, and open questions.-OpenViking ships a new release every Friday.-Release owners rotate in this order: qin-ctx, zhoujh01, ZaynJarvis, t0saki.+Import the file into a separate demo directory. `--wait` waits for processing to finish. For a repeat run, replace `lighthouse-demo` with a new directory name and use that same name in subsequent commands.++```bash+ov add-resource ./lighthouse.en.md --to viking://resources/lighthouse-demo --wait```-Import it into a new resource directory:+Once processing succeeds, inspect the imported files:```bash-ov add-resource ./ov-release-rotation.md --to viking://resources/ov-release-rotation --wait+ov tree viking://resources/lighthouse-demo```-The CLI uploads the local file automatically. `--wait` waits for processing; continue after the command succeeds. Without it, save the returned `task_id` and use `ov task status <task_id>` until the task is `completed`. See [Background Tasks](../api/17-tasks.md).+If waiting times out, run `ov task status <task_id>` with the returned task ID to check progress. Continue after completion. If the task fails, correct the model or connection settings indicated by the error before retrying. See [Background tasks](../api/17-tasks.md) for task states.++<a id="_4-browse-and-search"></a>++<a id="_4-ask-and-verify"></a>-## 4. Browse and search+## Ask and verify++### Retrieve and read a source++Find the material about feedback collection:```bash-ov tree viking://resources/ov-release-rotation-ov overview viking://resources/ov-release-rotation-ov find "Who owns the weekly OpenViking release?" --uri viking://resources/ov-release-rotation+ov find "How does the first version of Lighthouse collect feedback?" --uri viking://resources/lighthouse-demo```-`tree` lists the imported structure; `overview` reads its generated summary. `find` returns relevant context with URIs and scores. The imported file answers the question, so it is the top match. To read a match, pass its returned URI to `ov read`:+The results include URIs for matching content. Copy a source file URI, replace the placeholder below, and read the original text:```bash-ov read "<returned-file-uri>"+ov read "<source-file-uri>"```-Replace `<returned-file-uri>` with a file URI from the results, without the angle brackets. For more resource types and retrieval options, see [Resources](../api/02-resources.md) and [Retrieval](../api/06-retrieval.md).+Once you can read sections such as "Pilot environment" and "Feedback collection," ask an agent to use those sources.++### Generate an answer++**Cloud service:** Send the following task to an agent that can run local terminal commands. It should use the CLI connection you just configured. If the agent runs on another machine or in a separate container, [connect the CLI](#connect-the-cli) in that environment first.++```text+Use the locally configured ov CLI to answer a question from project sources in OpenViking.+Run ov health to check the connection, then run:+ov find "How does the first version of Lighthouse collect feedback?" --uri viking://resources/lighthouse-demo+Use ov read to open the relevant original text from the results, then answer:+How should the first version of Lighthouse collect user feedback, and what must be prepared?+Use only sources in that directory. Cite the full source file viking:// URI for each+key conclusion, and identify anything the sources do not specify.+```++**Local service:** Use `ov chat` to ask the running VikingBot the same question. It will use its retrieval and reading tools:++```bash+ov chat -m "Use only the sources under viking://resources/lighthouse-demo. Run a semantic search for the question, then read the relevant original text and answer: How should the first version of Lighthouse collect user feedback, and what must be prepared? Cite the full source file viking:// URI for each key conclusion. Explicitly identify anything the sources do not specify."+```++### Check the supporting evidence++Open the source files cited in the answer and compare the following facts. Wording can vary; check that each conclusion agrees with the original text.++| Expected conclusion | Supporting section |+| --- | --- |+| Save feedback locally; the pilot administrator exports it weekly to the project owner | Feedback collection |+| Prepare an offline installation package and a local storage directory | Pilot environment |+| No cloud synchronization in the first version; future support is undecided | Feedback collection |++If a conclusion lacks a citation, ask the agent to add it and check the source again. Then ask when the pilot ends and check that the answer identifies the date as undecided.++You have now imported sources, retrieved and read them, and checked an answer against its citations. Try the same workflow with your own material next.++## Troubleshooting-## Use an SDK+| Symptom | Next step |+| --- | --- |+| `uv`, `node`, or `ov` is not found after installation | Reopen the terminal. If needed, follow the relevant installation guide to check the command path. |+| `ov health` cannot connect | Check the active connection, service URL, and API key in `ov config`. For a local service, also check its running terminal. |+| Bot health returns `503` | Confirm the service started with `--with-bot`; inspect the service terminal and [VikingBot logs](../guides/17-vikingbot.md). |+| Import fails or retrieval is empty | Inspect the returned task, model availability, processing completion, and target URI. |+| A model returns `UnsupportedModel` | Check that the model, endpoint, and plan match; see the [model activation guide](../guides/02-volcengine-purchase-guide.md). |+| The agent cannot run `ov` | Check `ov --version` and `ov health` in the agent's terminal, then complete installation and connection setup there. |-OpenViking also provides Python, TypeScript/JavaScript, and Go SDKs that connect to the same server. See the [API Overview](../api/01-overview.md) for client examples.+<a id="use-an-sdk"></a>## Next steps-First confirm that you can read the sample source, then [evaluate OpenViking on your tasks](06-evaluate.md) using your own sources or conversations. To use it in a daily tool, [choose an agent integration](../agent-integrations/01-overview.md). To write your own application, follow the [application workflows](../workflows/01-overview.md).+Continue to [Resource retrieval](08-resources.md) to try questions requiring multiple sources or information missing from the material. Use [Evaluation](06-evaluate.md) to record results on your own tasks.diff --git a/docs/en/getting-started/05-cli-setup.md b/docs/en/getting-started/05-cli-setup.mdindex 7d0ae5edb..e017970ed 100644--- a/docs/en/getting-started/05-cli-setup.md+++ b/docs/en/getting-started/05-cli-setup.md@@ -1,286 +1,249 @@-# Install and use the CLI+# CLI basics-`ov` is the command-line client for OpenViking. OpenViking stores the context of your agents as a file system: resources, memories, and skills are directories and files under `viking://`. With `ov`, you can browse, read, search, and write this content. Agents use the same commands.+`ov` is the command-line client for OpenViking. Use it to import sources, retrieve content, and read original files from a terminal. An agent with terminal access can also run these commands to ground its answers in your sources.-`ov` connects to an existing OpenViking server. If you do not have a server yet, do step 1 of the [Quick Start](02-quickstart.md) first.+This page walks through installation, connection setup, browsing a source, and retrieving and reading relevant content. You can then use the same OpenViking connection from your terminal or agent.-## Set up with an agent+## Prerequisites-Click **Copy** below and paste the prompt into your coding agent, for example Claude Code, Codex, or Cursor. The agent installs `ov`, asks you which server to use, and then saves the config and checks the connection.+Prepare the following tools and connection details:-<AgentPrompt>--````markdown-# openviking-cli+| Requirement | How to obtain it |+| --- | --- |+| Node.js and npm | Install an LTS release from the [Node.js website](https://nodejs.org/en/download); npm is included. If `ov` already works, proceed to [Connect](#connect). |+| An OpenViking service | Use a provisioned Volcengine service or a running self-hosted service. To set one up, follow [Set up the service](02-quickstart.md#set-up-the-service). |+| Access credentials | Use the cloud console's API key, or a User/Admin key from your self-hosted service administrator. Default local mode without authentication can leave the key empty. |+| An accessible source | Use existing content, or [import the Lighthouse sample](02-quickstart.md#import-the-sample) after connecting. |-> `ov` is the command-line client for OpenViking, a context database for AI agents. It connects to an existing OpenViking server or to OpenViking Service on Volcengine.+After installing Node.js, open a new terminal and check that Node.js and npm are available:-I want you to install and configure the OpenViking CLI (`ov`) for me. Execute all the steps below autonomously. Stop and ask me only where a step says ASK.--OBJECTIVE: Install `ov`, save a named connection to my OpenViking server, and make it the active config.+```bash+node --version+npm --version+```-DONE WHEN: `ov config validate` shows every check as passed (config file valid, server reachable, auth accepted, healthy), and `ov health -o json` returns `"healthy": true`.+The CLI connects over HTTP. Installing only the CLI requires no local Python installation or model configuration; source processing uses the server's models.-## TODO+## Install-- [ ] Install `ov` and set its display language-- [ ] Find out which server to connect to-- [ ] Save and activate a named config-- [ ] Verify the connection+Install `ov` with npm:-## Rules+```bash+npm install -g @openviking/cli+```-- You must not guess the target. Existing configs, local files, open ports, and running services are not my consent.-- You must ASK before you switch, replace, or delete a config, probe or start a local server, or write data.-- You must keep API keys out of command text, shell history, logs, memory, and printed config files. Pass a key only through stdin or through an environment variable that already exists.-- If you cannot pass a key that way, ASK me to run `ov config` and type the key myself.-- You must pass `--name` to `ov config add`, so that a retry updates the same config.-- You must add `-o json` to `ov config add|edit|list|switch|delete`. Branch on the exit code and `error.code`, not on prose.-- If the installed `ov --help` differs from this file, follow the installed help and tell me the difference.+Save a display language for subsequent interactive and agent commands. Use `en` for English or `zh-CN` for Chinese:-## Step 1: Install ov+```bash+ov language en+```-You need Node.js and npm.+Confirm that the terminal can find the CLI and display its version:```bash-command -v ov || npm i -g @openviking/cli-ov language enov --version```-Use `ov language zh-CN` instead if I write to you in Chinese. Most `ov` commands exit with code 2 in a non-interactive shell until a display language is saved.+If your server installation already provides `ov`, you can use that command.-If `ov` is not found after the install, add `$(npm prefix -g)/bin` to `PATH`. Do not use `sudo npm`. If npm is not available, ASK me before you build from source with `cargo install --git https://github.com/volcengine/OpenViking ov_cli`.+## Connect-Read the help for the commands you will use:+Open the connection wizard and add a named connection for the service you want to access:```bash-ov config add ov-service --help-ov config add custom --help+ov config```-## Step 2: Find out the target--Run `ov config list -o json`. If a saved config already matches the target, ASK me before you activate it with `ov config switch <NAME> -o json`.+Enter the details for your service, save the connection, and activate it. If a matching connection already exists, select it.-Otherwise ASK me which target to use, unless I already told you:+| Service | Connection type | Details |+| --- | --- | --- |+| Default local service | Custom | URL: `http://127.0.0.1:1933`; leave the key empty in default local mode without authentication. |+| Remote self-hosted service | Custom | Use the service URL and User/Admin key provided by the administrator. |+| Volcengine managed service | OpenViking Service | Use the wizard's service address and enter the API key from the console. |-| Target | URL | API key |-|---|---|---|-| OpenViking Service (Volcengine) | Fixed. Do not pass `--url`. | Required. I get it in the [console](https://console.volcengine.com/vikingdb/openviking/region:openviking+cn-beijing?utm_source=opensource_docs&utm_medium=referral&utm_campaign=getting-started_05-cli-setup) under User Management → API Key. |-| Remote custom server | ASK me. | ASK me. |-| Local custom server | `http://127.0.0.1:1933` | Usually none. |+Choose a recognizable connection name, such as `local` or `cloud`. The service URL points to the OpenViking data service; model API endpoints are configured on the server.-For a local custom server only, check that it runs: `curl -fsS http://127.0.0.1:1933/health`. If the check fails, ASK me to start the server. See https://docs.openviking.ai/en/guides/03-deployment.+Entering keys through the wizard keeps them out of command history. With API key authentication, use a User/Admin key for ordinary data access and a Root key for administration. See [Authentication](../guides/04-authentication.md) for other identity configurations.-Do not ask for `--account` or `--user` unless my administrator gave me these values.+## Check the connection-## Step 3: Save and activate the config--Replace `<NAME>`, `<URL>`, and `<ENV_VAR>` with confirmed values. Remove the angle brackets. `$OV_API_KEY` stands for a trusted runtime source of the key, not the literal key.--OpenViking Service:+Inspect the active connection and verify its service address. This command masks keys:```bash-printf '%s' "$OV_API_KEY" | ov config add ov-service --name <NAME> --api-key-stdin --activate -o json+ov config show```-Remote custom server with an API key:+Validate the configuration, connection, and authentication:```bash-printf '%s' "$OV_API_KEY" | ov config add custom --name <NAME> --url <URL> --api-key-stdin --activate -o json+ov config validate```-Local custom server without authentication:+Once the checks pass, check the service health:```bash-ov config add custom --name <NAME> --url http://127.0.0.1:1933 --activate -o json+ov health```-Special key cases:--- If the key is already in an environment variable, use `--api-key-env <ENV_VAR>` instead of `--api-key-stdin`.-- Root key only, on a server in `trusted` mode: use `--root-api-key-stdin --account <ACCOUNT> --user <USER>`. On a server in `api_key` mode, a root key cannot read data. ASK me for a user or admin key.-- User key and root key together: use `--api-key-stdin --root-api-key-env <ENV_VAR>`. A command has only one stdin, so the second key must come from an existing environment variable.--Exit codes of `ov config` subcommands:--| Code | Meaning | Your action |-|---|---|---|-| `0` | Success, or already in the target state | Continue. |-| `2` | Bad input, missing argument, or no display language | Fix the input, or run `ov language <code>`. |-| `3` | A config with this name exists with different content | ASK me before you add `--force`. |-| `4` | Server unreachable, or validation failed | ASK me to confirm the URL and that the server runs. |-| `5` | Authentication failed, or wrong key role | ASK me to confirm the key and key type. |-| `6` | Operation refused, for example deleting the active config | ASK me how to continue. |+A result of `healthy: true` indicates a healthy service. Next, read a source to confirm that your identity can access the required content. Models used for imports and VikingBot's ability to answer questions are checked in their respective workflows.-Do not retry with guessed values.+## Browse and read-## Step 4: Verify+List the accessible shared source directories in the current service:```bash-ov config validate-ov health -o json+ov ls viking://resources```-Read the output. Exit code 0 alone does not prove that the server is healthy. To inspect the config, use `ov config show`, which hides secrets. Do not print `~/.openviking/ovcli.conf`.--Do not import data as a demo unless I ask.--After setup, I may ask you to browse, search, add, or organize content with `ov`. OpenViking content is a directory tree under `viking://`. To read, first use `ov abstract` or `ov overview` to read the directory summary. Then use `ov read` to read only the files you need. Run `ov --help` to see the command groups. Run `ov <command> --help` before you use a command.--EXECUTE NOW: Complete the above TODO list to achieve: `ov config validate` shows every check as passed, and `ov health -o json` returns `"healthy": true`.--For more context, read https://docs.openviking.ai/llms.txt.-````--</AgentPrompt>--The rest of this page describes manual setup.--## Before you start--You need Node.js and npm.+If no sources are available, [import the Lighthouse sample](02-quickstart.md#import-the-sample) and wait for processing to finish before returning here. The following commands use its directory, `viking://resources/lighthouse-demo`. Substitute your actual directory URI when using your own content.-You also need connection details. They depend on the server type:--| Server type | Server URL | API key |-|---|---|---|-| OpenViking Service (Volcengine) | Fixed. You do not enter it. | Required. Get it in the [OpenViking console](https://console.volcengine.com/vikingdb/openviking/region:openviking+cn-beijing?utm_source=opensource_docs&utm_medium=referral&utm_campaign=getting-started_05-cli-setup) under **User Management → API Key**. |-| Remote self-hosted server | Get it from your administrator. | Get it from your administrator. |-| Self-hosted server on this machine | `http://127.0.0.1:1933` | Not needed for the default setup. |--## 1. Install `ov`+Expand the directory to find the source file URI:```bash-npm i -g @openviking/cli-ov language en-ov --version+ov tree viking://resources/lighthouse-demo```-`ov language` sets the display language. Use `zh-CN` for Chinese. Most commands do not run until you set a language.--A machine that runs the OpenViking server already has `ov`. On that machine, skip `npm i` and only set the language.--## 2. Add a connection+Copy a file URI from the output, replace the placeholder below, and read the original text:```bash-ov config+ov read "<file-uri>"```-Follow the prompts:+The sample includes sections on the pilot environment and feedback collection. Reading the original text confirms that the connection and file access work.-1. Select **Add Config**.-2. Select the server type. For OpenViking Service, select **OpenViking Service (VolcEngine Cloud)**. For a self-hosted server, select **Custom**.-3. Enter a name for the config. If you leave it empty, `ov` generates a name.-4. Enter the server URL and the API key that the prompts ask for.-5. After validation passes, select **Save and activate**.+## Retrieve sources-## 3. Check the connection+For a specific question, retrieve relevant content before reading the matching files. Retrieval uses the server's model configuration and may incur model usage charges.```bash-ov config validate+ov find "How should the first version of the Lighthouse project collect user feedback?" --uri viking://resources/lighthouse-demo```-The connection works when all items under **Checks** pass: Config file `valid`, Server `reachable`, Auth `accepted`, and Health `healthy`.--Setup is complete. Next, you can [import and retrieve your first document](02-quickstart.md#_3-import-a-document). To learn more, read on.+Results include matching content and its URI. Use `ov read` to read a relevant result and check who collects feedback and how it is delivered. An agent can use this retrieved content as evidence for its answer.-## What you can do with `ov`+## Use from an agent-OpenViking content is a directory tree. Run `ov ls` to list the root, `viking://`:+Send the following task to an agent with terminal access. It can use the configured CLI to retrieve sources, read them, and answer:-- `viking://resources/`: imported documents, code repositories, and web pages. Shared in the account.-- `viking://user/<user-id>/`: your memories, private resources, skills, and sessions. `viking://~/` points to this directory.-- `viking://agent/`: skills and agent configuration, shared in the account.+```text+Use the configured ov CLI to query sources under viking://resources/lighthouse-demo.+First use ov find for this question:+How should the first version of Lighthouse collect user feedback, and what should be prepared?+Read the relevant original files with ov read, then answer the question.+Cite the full viking:// source URI for key conclusions and identify details the sources do not specify.+```-Each directory has an L0 abstract and an L1 overview. The full text of a file is L2. Read the L0 and L1 of a directory first to decide if it is relevant. Then read only the L2 files that you need. For details, see [Viking URI](../concepts/04-viking-uri.md) and [Context Layers](../concepts/03-context-layers.md).+The agent needs access to both the `ov` command and its connection configuration. If it runs on another computer, in a container, or under a different operating-system user, install and configure the CLI in that environment first.-| Task | Commands |-|---|---|-| Browse | `ov ls`, `ov tree`, `ov stat`. `ov tui` opens an interactive browser. |-| Read by layer | `ov abstract` (L0), `ov overview` (L1), `ov read` (L2). `ov get` downloads a file to your machine. |-| Search | `ov find` (semantic search), `ov grep` (match content), `ov glob` (match paths) |-| Import documents and skills | `ov add-resource`, `ov add-skill`, `ov skills` |-| Write and organize | `ov write`, `ov mkdir`, `ov mv`, `ov cp`, `ov rm` |-| Extract memories from a conversation | `ov session new`, `ov session add-message`, `ov session commit`. `ov add-memory` does these three steps in one command. |-| Wait for background processing | `ov task list`, `ov task status`, `ov wait` |-| Save and roll back versions | `ov snapshot` |-| Back up and move data | `ov export`, `ov import`, `ov backup`, `ov restore` |-| Rebuild indexes (`viking://resources` needs an admin key) | `ov reindex` |-| Manage users (admin or root key) | `ov admin list-users`, `ov admin register-user`, `ov admin regenerate-key` |-| Check the server | `ov health`, `ov status` |+`ov chat` sends a question to server-side **VikingBot**. The target service must have VikingBot enabled. For a local service, follow [VikingBot](11-vikingbot.md) to start it with `openviking-server --with-bot`. The Volcengine managed-service workflow uses the agent approach above. `ov health` checks the data service; check Bot availability separately.-After you import content or commit a session, the server processes it in the background: it parses content, extracts memories, generates L0 and L1, and builds indexes. Until processing is complete, `ov find` does not return the new content.+## Switch connections-Run `ov <command> --help` to see the options of a command. You can also ask your agent to do any of these tasks.+When using both cloud and local services, list your saved connections:-::: warning Caution-`ov rm -r` deletes a directory and all of its content. The delete runs on the server, so other agents that use the same server also lose this content. Before you delete, use `ov ls` to check the URI.-:::+```bash+ov config list+```-## Manage several connections+Open the selector and switch to the intended connection:```bash-ov config list # list saved configs-ov config switch # select the active config-ov config show # show the active config, with secrets hidden+ov config switch```-To edit or delete a config, run `ov config` and select the action. To add a config from a script, use `ov config add`. Run `ov config add --help` for the options.+Check the active address and service health after switching:-The active config is `~/.openviking/ovcli.conf`. Each saved config is `~/.openviking/ovcli.conf.<name>`. If you set `OPENVIKING_CLI_CONFIG_FILE`, `ov` uses that file as the active config, and saved configs are in the same directory as that file. For all fields, see [Client Configuration](../configuration/02-client.md).+```bash+ov config show+ov health+```-## API keys+Commands now access content in the selected service under the current identity. Sources imported into the cloud remain there; import the sample into the local service to try it locally. To migrate existing content, see [Import and export](15-transfer.md#migrate-between-services).-When the server uses API key authentication, a key has one of three roles:+The two configuration files serve different purposes:-- **User key**: for data commands, such as `ov add-resource` and `ov find`. Most users need only this key.-- **Admin key**: for data commands, and for managing the users of its account.-- **Root key**: for managing the whole server, for example to create accounts. In `api_key` mode, a root key cannot read or write account data.+| Configuration file | Purpose |+| --- | --- |+| `~/.openviking/ovcli.conf` | Active CLI connection, access credentials, and command defaults |+| `~/.openviking/ov.conf` | Models, storage, and server settings for a self-hosted service |-One config can hold a user key and a root key. Normal commands use the user key. `ov admin`, `ov system`, `ov reindex`, `ov task status`, and `ov task list` use the root key when you add `--sudo`. For details, see [Authentication](../guides/04-authentication.md).+For alternate configuration paths or scripted profile management, see [Client configuration](../configuration/02-client.md) and `ov config --help`.-To keep API keys safe:+## Common commands-- Type the key in the `ov config` prompt. Do not put a key in a command, because the shell history keeps it.-- Use `ov config show` to look at a config. It hides secrets. Do not share the content or screenshots of `~/.openviking/ovcli.conf`.-- For demos and trials, use a temporary key that you can revoke.-- If an agent sets up `ov` for you, do not paste the key into the chat. Put the key in an environment variable, or run `ov config` yourself and type the key when the agent asks.+| Purpose | Command |+| --- | --- |+| Browse directories | `ov ls "<directory-uri>"`, `ov tree "<directory-uri>"` |+| Retrieve by question | `ov find "question" --uri "<directory-uri>"` |+| Read original content | `ov read "<file-uri>"` |+| Read a generated directory overview | `ov overview "<directory-uri>"` |+| Inspect a background task | `ov task status <task_id>` |+| Look up options | `ov --help`, `ov <command> --help` |## Troubleshooting-### `ov` is not found+| Symptom | Next step |+| --- | --- |+| `npm` or `ov` not found | Open a new terminal after installing Node.js. If npm works but `ov` does not, check that npm's global executable directory is in `PATH`. |+| npm permission error | Follow the [npm guide](https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally) to fix global installation permissions. |+| A command asks for a language | Run `ov language en` or `ov language zh-CN` to save a display language. |+| Connection fails | Check the active URL with `ov config show`, keep the local service running, and run `ov config validate`. |+| Authentication or read denied | Check the key type and content permissions. See [Authentication](../guides/04-authentication.md). |+| Sources disappear after switching | Check the target service and identity; import the sample into that service or migrate the existing sources. |+| `ov chat` returns `404 page not found` | Check whether the active address provides VikingBot endpoints. For cloud services, use an existing agent to call the CLI. For local services, start and check the Bot as described in [VikingBot](11-vikingbot.md). |+| An import reports `UnsupportedModel` | Check that the model name, endpoint, and plan match in the server's `ov.conf`. See [Model setup](../guides/02-volcengine-purchase-guide.md). |+| Directory overview missing | Check source processing status. Overview generation depends on processing mode and configuration; see [Context layers](../concepts/03-context-layers.md). |-Open a new terminal. If `ov` is still not found, add the npm global binary directory to `PATH`. On macOS and Linux, this directory is usually `$(npm prefix -g)/bin`.+## Let an agent configure it-### npm reports a permission error+An agent can also help with installation and connection setup. Copy this prompt and supply the service type, connection name, and self-hosted service URL. Enter API keys through the interactive wizard or provide them through an existing trusted environment variable.-Fix the permissions in the way you usually manage Node.js, for example with nvm. Do not run `sudo npm i -g` unless you always manage global packages that way.+<AgentPrompt>-### A command asks for a display language+```text+Help me install and configure the OpenViking CLI (ov) for the service I specify.-Run `ov language en` or `ov language zh-CN`. Then run the command again.+Check whether ov is installed; if needed, install it with npm install -g @openviking/cli.+If Node.js/npm is missing, explain how to install it. Set the CLI language to en.-### The local server does not respond+Use my target details and ov config list -o json to reuse a matching named connection.+Before adding one, read ov config add ov-service --help or ov config add custom --help.+Save it with an explicit --name and activate the confirmed target.+Ask for any missing service type, URL, or credential source.+If the name already exists with different settings, explain the difference and ask before replacing it.-Check the server:+Read an API key from an existing environment variable with --api-key-env, or pass it via --api-key-stdin.+If no secure input method is available, guide me to run ov config in my terminal to enter the key.+Use ov config show to display settings without exposing credentials.-```bash-curl http://127.0.0.1:1933/health+Run ov config validate and ov health, and inspect their actual results.+Report the active service address, check results, and any remaining issues.+This task covers installation and connection; source imports will be specified in a later task.```-If this fails, start the server first. See [Deployment](../guides/03-deployment.md).--### API key validation fails--Run `ov config`, select **Edit Config**, and enter the key again. For OpenViking Service, copy the key from the console. For a self-hosted server, ask your administrator for the correct key and key type. In `api_key` mode, data commands need a user key or an admin key.--### The wrong config is active--Run `ov config list` to see which config is active. Run `ov config switch` to select another one.+</AgentPrompt>## Next steps-- Import and retrieve your first document: [Quick Start](02-quickstart.md).-- Connect OpenViking to the agent you use every day: [Agent integrations](../agent-integrations/01-overview.md).+Continue with [Ask and verify](02-quickstart.md#ask-and-verify) to produce source-based answers. To import your own project content, see [Resource search](08-resources.md).++<!-- Preserve incoming links to previous section titles. -->+<a id="_1-install"></a>+<a id="_2-connect"></a>+<a id="_4-browse-and-read"></a>+<a id="install-and-use-the-cli"></a>+<a id="set-up-with-an-agent"></a>+<a id="before-you-start"></a>+<a id="_1-install-ov"></a>+<a id="_2-add-a-connection"></a>+<a id="_3-check-the-connection"></a>+<a id="what-you-can-do-with-ov"></a>+<a id="manage-several-connections"></a>+<a id="api-keys"></a>+<a id="ov-is-not-found"></a>+<a id="npm-reports-a-permission-error"></a>+<a id="a-command-asks-for-a-display-language"></a>+<a id="the-local-server-does-not-respond"></a>+<a id="api-key-validation-fails"></a>+<a id="the-wrong-config-is-active"></a>diff --git a/docs/en/getting-started/06-evaluate.md b/docs/en/getting-started/06-evaluate.mdindex 637b2f753..2f8bf01a2 100644--- a/docs/en/getting-started/06-evaluate.md+++ b/docs/en/getting-started/06-evaluate.md@@ -1,50 +1,65 @@-# Evaluate OpenViking on your tasks+# Evaluation-After your [first import and retrieval](02-quickstart.md), try documents or conversations from your own work. Check whether OpenViking helps you find evidence, reuse context or produce useful content. Start with one scenario, then expand after you have a result.+Choose a small task you understand, record expected results, and check actual behavior with fixed inputs. Download the [evaluation CSV](/quickstart/evaluation-v1.csv) for initial trials, configuration changes, and upgrade checks.-| What you want to improve | Start here | What to check |-| --- | --- | --- |-| Spend less time looking through project files | [Import and retrieve documents](02-quickstart.md) | Find the source needed to answer the question, beyond words that merely look similar |-| Reuse background in a new agent session | [Choose an agent integration](../agent-integrations/01-overview.md) | Confirm that memory is stored and recalled for a relevant task without entering the same background again |-| Organize scattered sources into readable content | [Context compilation](../context-compilation/01-overview.md) | Check which sources the output uses, whether its structure helps the reader, and what it omits or gets wrong |+The v1 samples were verified on isolated local services with OpenViking, CLI, and VikingBot 0.5.2. See the [verification record](/quickstart/verification-v1.txt) for models, date, executed scope, observed issues, and unverified cases.-## Check retrieval with your own sources+## Fix the conditions-Choose a small set of sources you know, such as project notes, an operating manual or an incident review. Import them using the [quick start](02-quickstart.md). Prepare questions with known answers, recording the expected source for each. After retrieval, read the returned URI and compare it with the original text.+Record server, CLI, agent or plugin versions, models, deployment mode, identity, and project scope. Preserve inputs and expected sources in isolated demo directories. For comparisons, keep questions, sources, and models consistent where possible, noting differences.-Include a direct-answer question, one that requires two pieces of information, and one the sources cannot answer. Record whether the evidence was found, whether anything essential was missed, and whether a subsequent agent answer follows the source. `find` returns URIs and scores; your agent or application still needs to read and use the content to generate an answer.+Start with the four files in [Resource retrieval](08-resources.md), then substitute your own sources. Record preparation time, time to the first useful result, help requests, and pages left along the way to assess onboarding usability.-Add more sources after this first check. If results change, you can distinguish ingestion, retrieval and answer-generation problems. Use [observability and diagnostics](../guides/05-observability.md) to inspect processing state and request behavior.+## Check retrieval with your sources-## Check memory across two sessions+| Case | Question type | Check |+| --- | --- | --- |+| R1 | Direct answer in one source | Accurate answer with an accessible citation |+| R2 | Evidence across sources | Complete evidence and faithful conclusions |+| R3 | No answer in the sources | Missing information clearly identified |-Use the [capability comparison](../agent-integrations/16-capability-reference.md) to check which capture, commit and recall steps your plugin automates. Then follow that plugin's verification instructions.+Record import tasks, retrieval results, read URIs, final answers, and citations. For failures, identify the earliest stage that diverged and inspect its logs.-1. In the first session, provide a non-sensitive preference or piece of project context that a later task will need.-2. End or commit the session using the plugin's mechanism. Check processing state, the actual memory output and its user or Peer ownership. A successful commit does not guarantee a particular memory will be created.-3. Start a new session with the same identity. Ask for a task that needs the earlier context without entering that context again. Inspect recall records and the final answer to confirm the stored information was used.-4. Ask an unrelated question and check whether old context is carried into the answer inappropriately.+## Check memory across two sessions-Installing a plugin is only part of verifying memory. If no memory was produced, inspect [sessions and extraction](../concepts/08-session.md). If memory exists but is not recalled, inspect identity, retrieval scope and plugin behavior. For applications that manage their own sessions, follow the [application workflows](../workflows/01-overview.md) to the relevant APIs.+Follow [Memory use](09-memory.md) to save a test convention, then start a new session with the same identity. Ask for the task without repeating the convention. Record the artifact, recall evidence, and how the answer uses it. Add an unrelated question to check relevance.-## Check one compiled output+| Case | Task | Check |+| --- | --- | --- |+| M1 | A new session needs prior background | Saved conventions are applied |+| M2 | A new session is unrelated | The answer stays focused on the current question |-Choose a [knowledge wiki](../context-compilation/02-llm-wiki.md), [knowledge graph](../context-compilation/03-knowledge-graph.md) or [daily report](../context-compilation/04-daily-report.md). Follow the tutorial to prepare sources and run the task. Confirm completion and the output location, then review the content:+## Inspect Skill and compiled output-- Can you verify key facts against their sources?-- What is missing, repeated or unsupported?-- Can you use the output for the reading or organizing task you intended?+[Skill use](10-skills.md) compares two inputs for output structure, fact preservation, and unknowns, with evidence that the agent read the Skill. For [Context compilation](13-compile.md), open at least one body page and check citations, omissions, and unsupported claims.-Start with familiar sources so you can recognize mistakes. Task completion and generated files show that processing finished; the output still needs review before you rely on it.+Use [Version management](14-versions.md) and [Import and export](15-transfer.md) to check restore scope, file content, metadata, and retrieval readiness.-## Choose what to do next+## Fill in the record-| Your result | Next step |+| Field | What to record || --- | --- |-| Retrieval meets your needs and you want it in a daily tool | [Connect an existing agent](../agent-integrations/01-overview.md) |-| You have verified the capability and want it in your application | [Application workflows](../workflows/01-overview.md) |-| You want to use the agent included with OpenViking | [VikingBot Installation and Configuration](../guides/17-vikingbot.md) |-| You are ready to share a service with your team | [Choose a deployment path](../guides/00-overview.md), then verify identity and access control |-| You want to understand why the system behaves this way | [Concepts and principles](../concepts/00-overview.md) |+| Question and input | Complete prompt, source version, or test session |+| Expected facts and sources | Known answers and evidence URIs, recorded before execution |+| Actual answer and sources | Original response and citations |+| Stage and outcome | Import, processing, retrieval, reading, answering, capture, or recall; passed, failed, or unverified |+| Duration | Actual time from submission to a verifiable result |+| Environment and notes | Versions, models, identity, configuration differences, and manual revisions |++Sample rows in the sheet are blank for your results. Define quality criteria beforehand, such as evidence for every key fact, explicit unknowns, and whether the output supports the intended task.++## Diagnose and repeat++For missing files, inspect import. For empty search with existing files, inspect indexing and scope. For poor answers with correct matches, inspect agent reads and generation. For memory, follow capture, extraction, recall, and use in order. See [Observability and troubleshooting](../guides/05-observability.md).++Keep each evaluation and repeat the same tasks after changes. Technical validation records describe what was checked. Whether users can finish independently, explain the evidence, and substitute their own inputs is assessed during review and user trials.++<a id="check-context-compilation-with-one-output"></a>+<a id="choose-a-path-after-getting-a-result"></a>+<a id="evaluate-on-your-own-tasks"></a>-Keep your questions, expected sources and observed results. Reuse them when changing configuration or upgrading. When comparing results before and after a change, keep tasks, models and inputs consistent; a retrieval score or one successful run does not establish an improvement.+<!-- Keep incoming links to previous evaluation headings working. -->+<a id="evaluate-openviking-on-your-tasks"></a>+<a id="check-retrieval-with-your-own-sources"></a>+<a id="check-one-compiled-output"></a>+<a id="choose-what-to-do-next"></a>diff --git a/docs/en/getting-started/07-agent-onboarding.md b/docs/en/getting-started/07-agent-onboarding.mdindex 5e8b87118..2b38615e9 100644--- a/docs/en/getting-started/07-agent-onboarding.md+++ b/docs/en/getting-started/07-agent-onboarding.md@@ -1,6 +1,10 @@-# Connect your agent with one prompt+<a id="connect-your-agent-with-one-prompt"></a>-Paste one prompt into the coding agent you already use. The agent installs the OpenViking memory plugin into the agents it finds on your machine, checks the connection, offers to bring in your recent work, and tells you how to restart. After the restart, your first question shows OpenViking at work.+<a id="one-click-agent-setup"></a>++# One-click setup++Connect OpenViking to your coding agent with a single prompt. The agent installs the OpenViking memory plugin into the agents it finds on your machine, checks the connection, offers to bring in your recent work, and tells you how to restart. After the restart, your first question shows OpenViking at work.The agent follows a short guide published as plain Markdown, so any agent can fetch it:diff --git a/docs/en/getting-started/07-options.md b/docs/en/getting-started/07-options.mdnew file mode 100644index 000000000..7a8adf8c1--- /dev/null+++ b/docs/en/getting-started/07-options.md@@ -0,0 +1,41 @@+# Deployment modes++<a id="service-options"></a>++Run OpenViking yourself, connect to Volcengine's managed service, or request an enterprise deployment. Choose based on where data lives, who operates the system, and the support you need.++If you already have an endpoint and API key, go straight to [CLI basics](05-cli-setup.md). To try a complete local question-answering workflow, follow the [quickstart](02-quickstart.md).++## Choose a path++| Option | Data and environment | Operations and support | Prepare |+| ---------------------------- | ----------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------- |+| **Open-source self-hosting** | Your machine, servers, or cloud environment, with storage you configure | You deploy, upgrade, back up, and configure access control; help is available through the community | Runtime environment, model credentials, and storage |+| **Managed service** | Volcengine's hosted environment; consult the service terms for region and data conditions | The provider operates infrastructure; you manage access, data, and authorization | Service activation, connection details, and an API key |+| **Enterprise deployment** | Your cloud account, VPC, or offline environment under the agreed deployment plan | Operational responsibilities, support, and acceptance scope follow the delivery agreement | Deployment materials, a License, and environment checks |++Open-source/commercial describes software and support arrangements; self-hosted/managed describes operational responsibility. Open-source deployments can also serve teams. Consider your access-control needs, deployment environment, and support preferences when choosing an option. Version and service documentation describes the available capabilities and limits.++## Open-source self-hosting++Choose this to control the environment, debug locally, or build an application. The open-source server uses AGPLv3; local trials do not need enterprise deployment materials. The [quickstart](02-quickstart.md) walks through model setup, starting the server and VikingBot, and asking about a sample source.++Before sharing a service, configure authentication, persistence, backup, and operations. See [Server deployment](../guides/03-deployment.md) for Docker and open-source Helm options, and [LICENSE](https://github.com/volcengine/OpenViking/blob/main/LICENSE) for the license text.++## Managed service++Volcengine's OpenViking Context is a managed service built on the open-source core. After activation, obtain an API key from the [OpenViking console](https://console.volcengine.com/vikingdb/openviking/region:openviking+cn-beijing). Choose **OpenViking Service** in `ov config` and save the connection. You do not need to start the data service locally.++See the [official service documentation](https://docs.volcengine.com/docs/84313/2374478) for plans, quotas, regions, and support. VikingBot and Compile Runtime availability depends on the service configuration; your provider can help confirm support for these capabilities. You can also connect your own agent to the data service.++## Enterprise deployment++This option is for teams seeking private delivery, deployment materials, and official support. Use the [official inquiry form](https://my.feishu.cn/share/base/form/shrcnMFqymCd9sq77sLk34Krxoc) to agree on a plan and obtain the required materials and License.++The current [enterprise deployment guide](../guides/20-private-deployment.md) uses VikingDB and OpenViking on Kubernetes. As you prepare the deployment materials, use the [deployment checklist](../guides/19-deployment-checklist.md) to prepare images, storage, and dependencies as well.++## After choosing++With an endpoint and data-access credentials, continue to [CLI basics](05-cli-setup.md). For a complete local trial, use the [quickstart](02-quickstart.md).++Sources: [project commercial options](https://github.com/volcengine/OpenViking/blob/main/docs/repository/README_CN.md#商业版本), [managed-service introduction](https://docs.volcengine.com/docs/84313/2374478), and [enterprise deployment guide](../guides/20-private-deployment.md). Reviewed on 2026-10-27.diff --git a/docs/en/getting-started/08-resources.md b/docs/en/getting-started/08-resources.mdnew file mode 100644index 000000000..ea66fdfeb--- /dev/null+++ b/docs/en/getting-started/08-resources.md@@ -0,0 +1,120 @@+# Resource retrieval++Project descriptions, meeting notes, and feedback procedures often live in separate documents. After importing them into OpenViking, you can search by meaning, then have an agent read the originals, combine the information, and cite its sources.++This guide uses four fictional Lighthouse project files to walk through **importing → searching → reading originals → generating answers → verifying sources**. You will check questions answered by a single source, questions requiring multiple sources, and questions the sources leave unanswered.++## Prerequisites++Before you begin, prepare the following:++- **OpenViking service and CLI**: Configure your connection using the [quickstart](02-quickstart.md). Your account needs permission to import and read files in the target directory.+- **VikingBot**: This guide uses `ov chat` to generate answers. Enable VikingBot and configure its model using the [VikingBot guide](11-vikingbot.md). The CLI and VikingBot should connect to the same service and have access to the same sources.+- **Model configuration**: Processing sources, semantic retrieval, and answer generation use your configured models and incur model usage costs.++If you use your own agent, connect it to the service as described in the [quickstart](02-quickstart.md), then use the questions and verification criteria below.++## Prepare the sources++Download the [Lighthouse source pack](/quickstart/lighthouse-en-v1.zip), open a terminal in the download directory, and extract it:++```bash+unzip lighthouse-en-v1.zip+```++The resulting `lighthouse-en/` directory contains these files:++| File | Content |+| --- | --- |+| `project.md` | Network conditions, offline installer, and local storage preparation |+| `feedback.md` | Feedback export schedule, responsibility, and handoff |+| `meeting.md` | Feedback registration template, export rehearsal, and open questions |+| `limits.md` | The scope of the sources and information they do not provide |++## Import the sources++Import the directory into a dedicated demo path. The `--wait` option waits for processing to finish before you search. For a repeat run, replace `onboarding-en-v1` with a new directory name and update the URIs in subsequent commands.++```bash+ov add-resource ./lighthouse-en --to viking://resources/onboarding-en-v1 --wait+```++After processing succeeds, inspect the imported files:++```bash+ov tree viking://resources/onboarding-en-v1+```++Each Markdown file in this sample is processed into a directory with the same base name. Check that the following files are present before searching:++```text+viking://resources/onboarding-en-v1/+├── project/project.md+├── feedback/feedback.md+├── meeting/meeting.md+└── limits/limits.md+```++If waiting times out, use the returned task ID with `ov task status <task_id>` to check progress. Continue when the task completes. If it fails, use the error message to check model or connection settings. See [Task management](../api/17-tasks.md) for task status details.++<a id="retrieve-and-answer"></a>++## Search the sources++Start with a question that requires both the project description and meeting notes. Limit the search to the directory you imported:++```bash+ov find "How does Lighthouse collect feedback, and what must be ready before the pilot?" --uri viking://resources/onboarding-en-v1+```++The results list matching content and its URIs. Check whether the matches cover feedback collection and pilot preparation, then read the relevant originals. `ov find` locates relevant sources; reading them lets you check the supporting details.++## Read the originals++Open the source files using their URIs from the search results. For this sample, the relevant files include the project description, meeting notes, and feedback procedure:++```bash+ov read viking://resources/onboarding-en-v1/project/project.md+ov read viking://resources/onboarding-en-v1/meeting/meeting.md+ov read viking://resources/onboarding-en-v1/feedback/feedback.md+```++Notice that the project description specifies the installer and local directory, while the meeting notes specify the registration template and export rehearsal. A complete answer about pilot preparation needs both sources.++## Generate answers++Have VikingBot search, read, and answer in a new conversation. The following prompt asks three questions and requests citations and explicit handling of unknown information. When repeating the walkthrough, use a new session name.++```bash+ov chat --session lighthouse-resources-v1 -m "Use only viking://resources/onboarding-en-v1. Run semantic searches, read relevant originals, then answer: Who exports feedback and when? What must be ready before the pilot? When does the pilot end and what is its budget? Cite full source URIs for each conclusion and mark unspecified information as undecided."+```++The answer should cover the feedback export arrangements, pilot preparation, and open questions, with full `viking://` source URIs supporting its conclusions.++## Verify the sources++Open the cited files with `ov read` and compare the answer with the table below. Wording can vary; facts and citations should match the originals.++| Question type | Question | Expected facts | Sources |+| --- | --- | --- | --- |+| Single source | Who exports feedback and when? | The pilot administrator exports it every Friday and passes it to the project owner | `feedback/feedback.md` |+| Multiple sources | What must be ready before the pilot? | Offline installer, local storage directory, registration template, and one offline export rehearsal | `project/project.md`, `meeting/meeting.md` |+| Unanswered | When does the pilot end, and what is its budget? | Both are undecided | `meeting/meeting.md` |++Use tool output from `ov chat` or Bot logs to check that the agent searched the relevant sources, read the files, and used their content in its answer. For the multi-source question, check for requirements omitted from either file. For undecided matters, check that the answer preserves the uncertainty in the source.++## Troubleshooting++| Symptom | What to check |+| --- | --- |+| Files are missing from the imported directory | Confirm the extracted directory contains all four files, then inspect the import result and task errors |+| Search returns no relevant matches | Confirm processing is complete and the search URI matches the import directory, then try a more specific question |+| The CLI can read sources but the agent cannot | Check the service connection, accounts, and directory access permissions for both |+| Search finds relevant content but the answer omits it | Inspect the files the agent actually read, then ask it to read the missing source and complete the answer |+| The answer gives a specific end date or budget | Compare with the meeting notes and ask the agent to mark unsupported conclusions as undecided |++## Try your own sources++Choose a set of project documents you know well. Prepare single-source, multi-source, and unanswered questions, then repeat the search and verification steps. Use the record sheet in [Evaluation](06-evaluate.md) to compare retrieval, source reading, and answer quality. See [Resource management](../api/02-resources.md) for supported formats, import options, and incremental updates.++You can keep the demo directory for [Context compilation](13-compile.md) and [Import and export](15-transfer.md). To clean up later, confirm the directory URI in Studio and delete that demo directory.diff --git a/docs/en/getting-started/09-memory.md b/docs/en/getting-started/09-memory.mdnew file mode 100644index 000000000..b5f20fe2d--- /dev/null+++ b/docs/en/getting-started/09-memory.md@@ -0,0 +1,119 @@+# Memory use++Memory lets an agent reuse preferences, project context, and working experience in a new session, reducing repeated explanations. After a session is committed, OpenViking can extract information worth retaining for agents to retrieve and use in later tasks.++This walkthrough uses the fictional Cape project. Save its review conventions, then start a new session and ask VikingBot to prepare a review outline using those memories. You will inspect the memory text, check retrieval sources, and confirm that the answer follows the conventions.++## Use cases++| Scenario | Information to retain | Later use |+| --- | --- | --- |+| Personalized answers | Preferred language, summary format, and writing style | Organize answers in the user's preferred form |+| Project collaboration | Project context, prior decisions, and file-naming conventions | Continue project work in a new session |+| Reusing experience | Effective approaches and considerations from past work | Retrieve experience when a similar problem arises |++Memory extraction and organization depend on the input and server configuration. One conversation may produce several memories or update existing ones. See [Memory types](../api/16-memory.md#built-in-memory-types) for the categories.++<a id="prepare-an-isolated-experiment"></a>++## Prepare the environment++Follow the [Quickstart](02-quickstart.md) to connect to the service and enable and configure [VikingBot](11-vikingbot.md). The server needs working memory-extraction and Embedding models, and VikingBot needs access to OpenViking retrieval tools.++You will save a session through the CLI and recall its memories through VikingBot. Connect both to the same service with the same user identity so the new session can access the saved memories. This example uses the user's self memory space; see the [integration capability comparison](../agent-integrations/16-capability-reference.md) for identity and Peer scope in project plugins.++These operations call models and write fictional project information into the current user's memory. A dedicated demo account makes cleanup easier. Use the session names below, or choose new names and update the subsequent commands if you have used them before.++<a id="session-a-save-conventions"></a>++## Save project context++Create a session to record the Cape review conventions. `--no-auto-commit` leaves submission to the manual commit below:++```bash+ov session new --session-id cape-docs-a --no-auto-commit+```++Add a user message describing the context to reuse in future reviews:++```bash+ov session add-message cape-docs-a --role user --content "This is the fictional Cape project. Each review covers exactly two risks. Summaries use three bullet points in Chinese, and the delivery file is named cape-review.csv. Please follow these conventions when preparing future Cape reviews."+```++Commit the session to archive the message and start memory extraction:++```bash+ov session commit cape-docs-a+```++Record the returned `task_id` and `archive_uri`. `accepted` means the messages have been archived and memory extraction is processing in the background. Next, check the task to confirm that memories have been generated.++## Inspect the memories++Replace `<task_id>` with the task ID returned by the commit:++```bash+ov task status <task_id>+```++Read the results after the status becomes `completed`. Check every 5 seconds for an initial 2 minutes; if processing continues, keep the task ID and check later. For `failed` or `cancelled`, inspect the task error or cancellation reason before deciding how to proceed.++Replace `<archive_uri>` with the returned archive URI to read the memory changes from this commit:++```bash+ov read "<archive_uri>/memory_diff.json"+```++Find a `uri` in `operations.adds` or `operations.updates`, then copy it to read the memory text:++```bash+ov read "<memory-uri>"+```++Check for all three conventions: two risks per review, three summary bullet points in Chinese, and the delivery filename `cape-review.csv`. Memory filenames and categories can vary; use the returned URI.++<a id="session-b-use-the-background"></a>++## Use memory in a new session++Use a new VikingBot session ID and provide only the project name and new task. The agent retrieves the risk count, summary format, and filename from saved memory:++```bash+ov chat --session cape-docs-b -m "Search saved Cape project memories. Prepare the next review outline following the project conventions and suggest the delivery filename. Cite the memory URIs used."+```++Check that the answer has space for two risks, three Chinese summary bullet points, and the filename `cape-review.csv`. No specific risks were supplied, so the outline can mark their content as needing input.++Use tool-call output or Bot logs to check saving, retrieval, and use:++| Stage | What to check |+| --- | --- |+| Saved | `memory_diff.json` records changes, and the memory text contains the conventions |+| Retrieved | Retrieval tool results contain the corresponding memory URI and content |+| Used | The new answer follows the conventions, and its memory citations match the retrieval results |++Start another session to check that the answer stays relevant to the current task:++```bash+ov chat --session cape-docs-c -m "What is 17 plus 25?"+```++The answer should be 42, with no need to include the Cape review format or filename.++<a id="locate-a-problem"></a>++## Troubleshooting++| Observation | What to check |+| --- | --- |+| Commit returns `skipped` | No messages were available to archive; use `ov session get cape-docs-a` to check whether messages were added or already committed |+| Task fails or remains incomplete | Inspect task status and errors, model connectivity, and server memory settings |+| Expected memories are missing | Check the original message, `memory_diff.json`, and effective extraction policies; the same information may already exist in memory |+| Saved memory is not retrieved in the new session | Compare the CLI and VikingBot service URLs, user identities, memory scope, and retrieval-tool availability |+| Retrieved memory is not used in the answer | Inspect tool results and agent instructions, then ask the agent to revise the answer using the retrieved memory |++## Continue++Try your own project context or answer preferences and use [Evaluation](06-evaluate.md) to record results for related and unrelated tasks. For existing agents, see the [integration capability comparison](../agent-integrations/16-capability-reference.md) for session capture, commit, and retrieval behavior. See the [Sessions API](../api/05-sessions.md) for parameters and the change-record format.++When finished, use this commit's `memory_diff.json` to identify the demo memories in Studio, then clean up sessions and memories as needed. If the commit updated existing memories, review the changes first and preserve information you still need.diff --git a/docs/en/getting-started/10-skills.md b/docs/en/getting-started/10-skills.mdnew file mode 100644index 000000000..82401135b--- /dev/null+++ b/docs/en/getting-started/10-skills.md@@ -0,0 +1,107 @@+# Skill use++A Skill describes a reusable way to perform a task, including its steps, output format, and checks. For recurring tasks such as organizing feedback, writing reports, or reviewing code, an agent can read the Skill and apply its instructions to different inputs.++OpenViking stores and retrieves Skills; the agent reads the instructions and carries out the task. In this guide, you will add a feedback-brief Skill and use VikingBot to process two sets of feedback, then compare how the same workflow applies across conversations.++## Prerequisites++Before you begin, prepare the following:++- **OpenViking service and CLI**: Configure your connection using the [quickstart](02-quickstart.md).+- **VikingBot**: Enable VikingBot on the service and configure its model. See [VikingBot](11-vikingbot.md) for setup instructions. This guide uses `ov chat` to generate briefs, which incurs model usage costs.+- **Skill directory permissions**: This guide adds the Skill to the shared directory `viking://agent/skills/`. Your account needs write access to that directory. The CLI and VikingBot should connect to the same service with accounts that can access the Skill.++Download the [feedback-brief Skill package](/quickstart/feedback-brief-v1.zip) and open a terminal in the download directory. The package includes `SKILL.md` and sample inputs in English and Chinese.++## Add the sample Skill++Extract the package to create the `feedback-brief` directory:++```bash+unzip feedback-brief-v1.zip+```++Add the directory to OpenViking. The `--wait` option waits for Skill processing to finish so you can inspect the content next.++```bash+ov add-skill ./feedback-brief -p viking://agent/skills --wait+```++List the Skills and check that `feedback-brief` appears:++```bash+ov skills list+```++Read `SKILL.md` to see the instructions the agent will follow:++```bash+ov read viking://agent/skills/feedback-brief/SKILL.md+```++This Skill asks the agent to use only the supplied input and produce the following content in the input language:++| Content | Requirements |+| --- | --- |+| Facts | Preserve supplied facts and numbers, and cite input IDs |+| Actions | Use a table with action, owner, and evidence columns; distinguish suggestions from facts and mark missing owners as Unspecified |+| Open questions | List missing information and mark missing dates as Undecided |++The Skill asks the agent to return the brief in the conversation. After importing it, use a conversation to have the agent read and apply it. If you have already added this sample, check its content and continue.++<a id="try-the-first-input"></a>++## Generate a brief++The first input contains a duration, a suggested improvement, and an undecided date. Provide the feedback in a new conversation and specify the Skill path so VikingBot can follow its instructions:++```bash+ov chat --session feedback-skill-a -m "First discover and read viking://agent/skills/feedback-brief/SKILL.md. Follow that Skill for this input and return the result only in the conversation: Feedback A: Offline export takes 8 minutes. The pilot administrator suggests a progress indicator. The release date is undecided."+```++The brief should contain Facts, Actions, and Open questions. Compare it with the input:++- Facts preserve the 8-minute export duration and cite input ID A.+- Adding a progress indicator appears as a suggested action, with the owner marked Unspecified.+- The release date remains Undecided and appears under Open questions.++You can also check tool call records or service logs to confirm that VikingBot read `SKILL.md`. This helps verify that the brief was generated using the specified Skill.++## Reuse with another input++Provide a second input in another conversation to see whether the agent applies the same workflow. A new conversation keeps the previous feedback out of this task's conversation history. When repeating the walkthrough, replace the sample session names with new ones.++```bash+ov chat --session feedback-skill-b -m "First discover and read viking://agent/skills/feedback-brief/SKILL.md. Follow that Skill for this input and return the result only in the conversation: Feedback B: The registration template lacks an issue category field. There are 3 duplicate reports. No owner is specified."+```++This brief should preserve the missing category field and the 3 duplicate reports, cite input ID B, and mark the owner as Unspecified. Suggested actions might include adding the category field and merging duplicate reports, clearly labeled as suggestions based on the input.++Compare the briefs: their content should reflect the different inputs, while the three-section structure, action table, and evidence references remain consistent. See the [sample briefs and Skill read records](/quickstart/skill-output-en-v1.txt) for examples of the output format.++## Check the result++| Check | Expected result |+| --- | --- |+| Skill added | `feedback-brief` appears in the Skill list and `SKILL.md` is readable |+| Agent read the Skill | Tool call records or logs include a read of `SKILL.md` |+| Workflow reused | Both briefs contain the three required sections, an action table, and input IDs |+| Content matches the input | Numbers and facts remain accurate, suggestions are labeled, and missing information remains open |++Model-generated wording can vary. Use the input facts and Skill requirements to evaluate the result.++## Troubleshooting++| Symptom | What to check |+| --- | --- |+| The Skill does not appear in the list | Check the import result. If it reports an error, use the message to check the service connection, directory permissions, or model configuration |+| The CLI can read the Skill but VikingBot cannot | Check that both use the intended service and accounts, and that VikingBot's identity can read the directory |+| The conversation has no Skill read record | Confirm that the Skill path in the prompt is readable and check VikingBot's OpenViking tool configuration |+| The brief does not follow the required structure or content rules | Confirm that the agent read the Skill, then identify the differences and ask it to revise the brief against the instructions |++## Next steps++To reuse your own workflow, write its instructions in `SKILL.md` and add it to OpenViking. See the [Skills reference](../api/04-skills.md) for the format, update options, and integration with other clients.++To have an agent use a Skill to produce maintainable knowledge-base files, continue to [Context compilation](13-compile.md). To remove the sample afterward, identify `feedback-brief` in Studio and confirm it is the Skill you added before deleting it.diff --git a/docs/en/getting-started/11-vikingbot.md b/docs/en/getting-started/11-vikingbot.mdnew file mode 100644index 000000000..9ef81aaad--- /dev/null+++ b/docs/en/getting-started/11-vikingbot.md@@ -0,0 +1,143 @@+# VikingBot++VikingBot is OpenViking's built-in AI agent. It accepts tasks, calls models and tools, and uses resources, memories, and Skills stored in OpenViking to generate answers. You can chat with it from the command line to organize tasks, query project documents, or follow a reusable workflow.++This guide runs locally. You will start VikingBot, organize a task list, and ask a follow-up in the same session. By the end, you can check that the service is reachable, the model responds, and subsequent messages use the conversation context.++## Prerequisites++Prepare the following before you begin:++| Requirement | Purpose and setup |+| --- | --- |+| uv and Python | Install and run OpenViking and VikingBot. The commands below use Python 3.13; see [Prepare the local runtime](02-quickstart.md#prepare-the-local-runtime) |+| Node.js/npm | Install the `ov` CLI; see [Install Node.js](02-quickstart.md#install-node-js) |+| Model credentials | Prepare model names, endpoints, and API keys for an embedding model and a VLM that supports tool calling; see the [model setup guide](../guides/02-volcengine-purchase-guide.md) |++VikingBot uses the VLM in your OpenViking configuration by default. The embedding model supports later resource retrieval. For Agent Plan, select supported models and endpoints. Model calls incur charges from your chosen service.++If you already started a local service with VikingBot through the quickstart, go to [Connect the CLI](#connect-the-cli).++<a id="start-and-connect"></a>++## Start the service++Install OpenViking and VikingBot to enable resource management and agent conversations locally:++```bash+uv tool install --python 3.13 "openviking[bot]" --upgrade+```++For a first-time setup, run the initialization wizard, choose local access, and enter your model settings. If you already have a configuration, proceed to the configuration check.++```bash+openviking-server init+```++Check the model and service configuration. If the check reports errors, correct the indicated settings and check again:++```bash+openviking-server doctor+```++If your existing service uses API key authentication, first follow [Authentication](../guides/04-authentication.md) to configure the Bot connection identity and prepare the appropriate User/Admin Key for the CLI.++After the check passes, start OpenViking and VikingBot together. The `--with-bot` flag enables the agent conversation endpoint. Keep this terminal running and use another terminal for subsequent commands. If a local service is already running without Bot, stop it in its original terminal before starting it with the command below.++```bash+openviking-server --with-bot+```++The remaining commands use the default address, `http://127.0.0.1:1933`.++## Connect the CLI++Install the CLI in a new terminal. If `ov` is already available, proceed to connection setup.++```bash+npm install -g @openviking/cli+```++Set the interface language to English and open the connection wizard:++```bash+ov language en+ov config+```++Choose a Custom connection and enter `http://127.0.0.1:1933` as the URL. Leave the key empty for the default local mode, or enter your User/Admin Key if authentication is enabled. Save and select this configuration; if the connection already exists, select it directly. See [CLI basics](05-cli-setup.md) for other connection options.++First, check that the CLI can reach the data service:++```bash+ov health+```++The result should include `healthy: true`. Next, check the Bot endpoint:++```bash+curl -f http://127.0.0.1:1933/bot/v1/health+```++Once it returns `status: healthy`, you can start a conversation. The next task also checks that the model can generate a response.++<a id="complete-a-task-and-follow-up"></a>++## Complete a task++Give VikingBot a fictional task list to organize by completion status. The `--session` option names the conversation so you can continue discussing the list later. When repeating the walkthrough, choose a new session name.++```bash+ov chat --session bot-review-v1 -m "Fictional task list: source import is complete; citation verification and demo rehearsal are pending. Organize a brief completed and pending list."+```++The response should list source import as complete, with citation verification and demo rehearsal pending. Compare the states with the input; wording and formatting can vary.++## Ask a follow-up++Keep the same `--session` and ask VikingBot to suggest the next step based on the list:++```bash+ov chat --session bot-review-v1 -m "Using that list, suggest what to complete first and explain why in one sentence."+```++You do not need to repeat the list. The response should discuss citation verification or demo rehearsal. For example, it might recommend checking citations first to confirm accuracy before the demo. The suggested order can vary, but its reasoning should use the pending items from the previous turn.++Follow-ups in the same session use the existing conversation context. A new session name starts another conversation. To reuse project background or preferences across sessions, continue to [Memory use](09-memory.md) for memory storage and recall.++## Check the result++| Check | Expected result |+| --- | --- |+| Service connection | Both `ov health` and the Bot health check succeed |+| Single task | The response preserves all three tasks and their completion states |+| Continued conversation | The follow-up uses the previous pending items and explains its recommendation |++If the response omits a task or changes its state, point out the difference and ask VikingBot to revise it against the original list.++## Troubleshooting++| Symptom | What to check |+| --- | --- |+| `openviking-server` or `ov` is unavailable after installation | Open a new terminal; if the command is still unavailable, check executable paths using the uv or npm installation instructions |+| The port is already in use | Check for an existing local service; to enable Bot, stop it in its original terminal and restart with `--with-bot` |+| `ov health` cannot connect | Check the current address in `ov config` and confirm that the service terminal is still running |+| Bot health returns `503` | Confirm that startup included `--with-bot` and inspect the Bot startup messages in the service logs |+| Health checks pass but model calls fail | Use the error message to check the model name, endpoint, credentials, and plan support |+| The follow-up does not use the list | Confirm that both commands use the same `--session` and CLI identity, and that the first turn returned a complete response |++## Next steps++Once connection and conversation work, use OpenViking context in your tasks:++| Goal | Next step |+| --- | --- |+| Answer questions from project documents and verify sources | [Resource retrieval](08-resources.md) |+| Reuse background and preferences in a new session | [Memory use](09-memory.md) |+| Apply a consistent workflow to different inputs | [Skill use](10-skills.md) |++See the [VikingBot guide](../guides/17-vikingbot.md) for chat platforms such as Feishu, standalone debugging, and model configuration. See [Bot API](../api/24-vikingbot.md) to send messages from an application. VikingBot Gateway handles Bot messages and chat channels; the [OpenViking gateway](12-gateway.md) provides a model request endpoint for compatible clients.++## Finish the trial++Keep the session name to continue the conversation later. Stop the local service with Ctrl+C in its terminal; the CLI conversation endpoint closes with it. To clean up test sessions, identify the corresponding sessions in Studio before deleting them.diff --git a/docs/en/getting-started/12-gateway.md b/docs/en/getting-started/12-gateway.mdnew file mode 100644index 000000000..5f8e8e2d8--- /dev/null+++ b/docs/en/getting-started/12-gateway.md@@ -0,0 +1,201 @@+# Gateway setup++The OpenViking gateway connects a client to a model service, adds relevant memories to forwarded requests, and saves conversations to OpenViking for later extraction and reuse. Compatible clients that support a custom Base URL and API key can access memory through their connection settings.++This guide uses a Python sample to **connect → send a conversation → inspect memory → use it in a new conversation**. You will provide review conventions for the fictional Mist project, then start another conversation and check whether the answer follows those conventions.++::: info Beta+The OpenViking gateway is currently in Beta. Interfaces and configuration may change in future releases. When upgrading, review the release notes and check your existing connection settings.+:::++## Prerequisites++This guide uses a local service. Prepare the following:++- **OpenViking service**: Install and configure it using the [quickstart](02-quickstart.md#local-service), with working embedding and VLM models. The gateway is included in OpenViking and shares the data service's port when enabled.+- **Python 3**: Used to run the sample; see [Prepare the local runtime](02-quickstart.md#prepare-the-local-runtime). The sample uses only the Python standard library.+- **CLI connection**: Connect to the local service using [CLI basics](05-cli-setup.md) to inspect sessions and memories later. The CLI and gateway key should use the same OpenViking user; the default local mode uses the `default` user.+- **Upstream model**: Prepare an endpoint, model name, and API key for a model service that supports **OpenAI Chat Completions**.++These steps call the upstream model and write fictional project conventions to the current user's memory. Memory extraction also calls the models configured on the service, incurring provider charges. For remote service identities and permissions, see [Gateway quickstart](../gateway/02-quickstart.md#remote-server-api-keys).++## Enable the local gateway++Run the initialization wizard, choose **Update gateway** from the existing-configuration menu, and enable the gateway:++```bash+openviking-server init+```++Save the configuration, stop the service in its original terminal, and restart it using your usual command. For example:++```bash+openviking-server+```++If the service also runs VikingBot, retain existing flags such as `--with-bot`.++Open [Studio](http://127.0.0.1:1933/studio/) and select **OpenViking Gateway** in the sidebar. The local gateway address is `http://127.0.0.1:1933/gateway`, which the sample uses below.++Use the gateway address displayed in Studio. The screenshots below use local port `1934`; if your service uses a different port, update the addresses in the subsequent commands accordingly. Select a screenshot to open it at full size.++## Configure models and memory++In Studio, prepare an upstream, a context profile, and a gateway key in that order.++### Configure an upstream++An upstream is the model service to which the gateway forwards requests. In the **Upstreams** tab, select or add an upstream that supports **Chat Completions**, enter its endpoint and credentials, and use the test action to confirm connection or model availability.++The gateway may have imported an upstream from the service's VLM configuration. Check and use it if it matches your requirements; for imported Coding Plan upstreams, complete the confirmation shown by the UI. The gateway forwards requests using their original protocol, so this sample requires a Chat Completions upstream.++In the upstream editor, select **Chat Completions**, enter the **Base URL** supplied by your model service, and check the full request address displayed below it.++[](/quickstart/gateway/upstream-en.jpg)++### Set up a context profile++A context profile controls memory recall and conversation capture. In the **Profiles** tab, create a profile such as “Mist walkthrough” with these settings:++| Setting | Value for this guide | Purpose |+| --- | --- | --- |+| Memory recall | Enabled | Add relevant memories to new messages |+| Search scope | Memory | Use saved project conventions |+| Conversation capture | Enabled | Save conversations to OpenViking for memory extraction |+| Latest-response wait | 30 seconds | Save the final turn and submit the session after idle time |+| Retained recent messages | 0 | Include this short conversation's messages in archiving and memory extraction |+| Recall summary | Enabled | Show a summary of added memories in the response |+| OpenViking tools | Disabled | Complete this workflow through automatic recall and capture |++In the profile editor, select **Recall memory**, enable **Show recall summary**, and select **Memories** under **Sources**.++[](/quickstart/gateway/recall-en.jpg)++Next, select **Save conversations**, set **Save the latest reply after** to **30 seconds**, and set **Keep recent messages** to **0**. Then turn off tools in the **OpenViking tools** section and save the profile.++[](/quickstart/gateway/capture-en.jpg)++Save the profile, issue a key using it, and start a new conversation below. Profile changes apply to conversations started afterward. For everyday use, adjust waiting and retention to your tasks; see [Context profiles](../gateway/08-context-profiles.md).++### Issue a key++In the **Keys** tab, issue a gateway key for this walkthrough, selecting the profile and upstream you prepared. Copy the full `ovgw_…` value from the dialog for the sample connection; the complete key is shown only when issued.++In the issue-key form, enter a name, check **Who is this for?**, and select your context profile and upstream. If the upstream shows **Blocked**, return to its settings and follow the prompts to check credentials and plan eligibility before sending requests.++[](/quickstart/gateway/key-en.jpg)++The client uses this gateway key to access the model, while the provider API key stays in the upstream configuration. The `ov` CLI continues to use its existing OpenViking connection to inspect sessions and memories.++## Send two turns++Download the [Python sample](/quickstart/gateway-demo-v1.zip), open a terminal in the download directory, and extract it:++```bash+unzip gateway-demo-v1.zip+```++The package contains `gateway-demo.py`. The following commands use a macOS / Linux terminal. Set the gateway address and replace `<upstream-model-id>` with an available model name from your upstream:++```bash+export GATEWAY_URL=http://127.0.0.1:1933/gateway+export GATEWAY_MODEL='<upstream-model-id>'+```++Run the following command, enter the gateway key, and press Enter. Key characters are hidden as you type:++```bash+read -r -s GATEWAY_KEY+export GATEWAY_KEY+```++Send two turns that introduce the Mist project conventions: check four risks, use Markdown for reports, and name the file `mist-review.md`.++```bash+python3 gateway-demo.py capture --language en --run v1+```++The sample first sends the conventions, then sends “Thank you” with the complete first-turn history. The terminal should show two responses. History in the second request lets the gateway save the first turn; the final turn is saved and submitted after the configured idle wait.++Confirm both requests succeeded in Studio's request log. Then find the `gateway-…` session containing the Mist project conventions in the **Sessions** page. Use the actual service-generated session ID for the CLI checks below.++<a id="wait-for-memory-and-start-a-new-session"></a>++## Inspect the memory++After messages stop, the gateway waits the configured 30 seconds before submitting the final turn. Background extraction takes additional time. Check every 10 seconds for up to 5 minutes initially. If processing continues, keep the session and task IDs and check again later. For failed or cancelled tasks, inspect the error or cancellation reason.++List sessions, then replace `<gateway-session-id>` with the ID found in Studio to inspect its commit information:++```bash+ov session list+ov session get <gateway-session-id>+```++List memory extraction tasks. Find the task whose `resource_id` matches that session ID and use its `task_id` in the next command:++```bash+ov task list --task-type session_commit+ov task status <task_id>+```++When the task status is `completed`, copy `archive_uri` from the task result and inspect the memory changes:++```bash+ov read "<archive_uri>/memory_diff.json"+```++Copy a memory `uri` from `operations.adds` or `operations.updates` and read its content:++```bash+ov read "<memory-uri>"+```++Confirm that the memory preserves all three conventions—four risks, Markdown format, and `mist-review.md`—before starting a new conversation. Memory names and categories depend on the actual extraction result.++## Use a new conversation++Run the recall phase in the same terminal, keeping the gateway address, key, and model settings:++```bash+python3 gateway-demo.py recall --language en --run v1+```++This command starts a new Python process and uses a different conversation identifier. It sends only a request to prepare a review checklist using the saved Mist conventions and give the delivery filename. The gateway supplies the specific conventions from memory.++Check that the response includes places for four risk checks, uses Markdown, and names `mist-review.md`. The sample does not provide specific risks, so the answer can leave them to be filled in or label proposed risks as suggestions.++<a id="check-and-finish"></a>++## Check the result++Use the memory text, response recall summary, and Studio request log to check each stage:++| Stage | Expected result |+| --- | --- |+| Request | Both model requests succeed and the terminal receives responses |+| Capture | The corresponding session and its archive contain the project conventions |+| Extraction | The task completes and the memory preserves all three conventions |+| Recall and use | The new conversation has recall evidence and its answer follows the conventions |++Wording can vary. Check both whether the memory was recalled and whether the answer used its information.++## Troubleshooting++| Symptom | What to check |+| --- | --- |+| Requests fail or the model is unavailable | Check the gateway address, the key's upstream binding, model name, and Chat Completions protocol; inspect the request log |+| No session appears in Studio | Check conversation capture, confirm that the current user matches the gateway key's user, and inspect the request's capture status |+| A session exists but no memory is generated | Check idle waiting, retained recent messages, and the `session_commit` task status |+| Memory exists but is not recalled | Check the key's user, context profile, and search scope; after changing the profile, retry in a new conversation |+| Recall is recorded but the answer omits conventions | Compare memory text with the response and ask the model to revise using the saved conventions |++For more issues, see [Gateway troubleshooting](../gateway/12-troubleshooting.md).++## Next steps++Connect your own application using [Client connections](../gateway/03-connect-clients.md). For remote services and team configuration, see [Gateway quickstart](../gateway/02-quickstart.md).++To repeat the walkthrough, use the same new `--run` value in both sample commands to create a fresh pair of conversations. Existing memories for the same user remain available for recall. To start with empty memory, use a separate demo user.++When finished, revoke the walkthrough's gateway key in Studio and use the session records and `memory_diff.json` to identify demo data for cleanup. If this run updated existing memories, review the changes and retain information you still need.diff --git a/docs/en/getting-started/13-compile.md b/docs/en/getting-started/13-compile.mdnew file mode 100644index 000000000..a86d8ce0b--- /dev/null+++ b/docs/en/getting-started/13-compile.md@@ -0,0 +1,61 @@+# Context compilation++Turn the four Lighthouse sources into a small wiki, then open its body page to verify evidence and unknowns.++## About LLM Wiki++LLM Wiki uses a language model to organize information scattered across documents, meeting notes, and feedback into an interlinked Markdown knowledge base. Related information about a project or concept can be brought together on one page, reached through an index, and linked back to its original sources for readers and agents to inspect, verify, and reuse.++For example, the Lighthouse project's goals, feedback process, and preparation tasks are spread across four sources. Compilation can bring them together on a project page, identify undecided dates and budget, and cite the sources for key facts. Readers can start with that page and follow its references for details.++In OpenViking, the LLM Wiki Skill defines how to organize the material, and the Compile Runtime reads the sources and generates pages. The wiki remains available for reading and retrieval; check key conclusions against the original sources. The following walkthrough compiles the Lighthouse materials.++## Prepare sources and a Skill++Use a service with a configured Compile Runtime. The local default is VikingBot installed with `openviking[bot]` and enabled with `--with-bot`; see the [quickstart](02-quickstart.md) for model and connection setup.++Complete the source-import step in [Resource retrieval](08-resources.md#prepare-the-sources), and confirm `viking://resources/onboarding-en-v1` is readable. Download [Wiki Skill v1](/quickstart/llm-wiki-v1.zip) and install it into a shared skills directory you can write:++```bash+ov add-skill ./llm-wiki-v1.zip -p viking://agent/skills --wait+ov read viking://agent/skills/llm-wiki/SKILL.md+```++The package contains the project's LLM Wiki Skill. Compilation calls the model and writes output into a new directory. Use another target name for repeat runs.++## Submit compilation++```bash+ov compile --from viking://resources/onboarding-en-v1 \+ --to viking://resources/onboarding-wiki-en-v1 \+ --skill viking://agent/skills/llm-wiki \+ --instruction "Generate index.md and entity/lighthouse.md in English. Explain the isolated-network feedback pilot using the project, feedback, and meeting sources. Preserve full viking:// source URIs and identify undecided dates. Write only inside the target directory."+```++Record the returned `cmp_...` task ID and inspect progress:++```bash+ov task status <cmp_task_id>+```++Check every 5 seconds for up to 5 minutes initially. Read outputs after `completed`. If still running, check later or request cancellation with `ov task cancel <cmp_task_id>`. On failure, inspect the task error and Compile Runtime configuration.++After compilation, the target directory should contain an index and a project page. See the [sample Wiki page](/quickstart/wiki-output-en-v1.txt) for content organization and source citations, then follow the checks below to review your output.++## Open the body page++```bash+ov tree viking://resources/onboarding-wiki-en-v1+ov read viking://resources/onboarding-wiki-en-v1/index.md+ov read viking://resources/onboarding-wiki-en-v1/entity/lighthouse.md+```++If filenames differ, use the tree and index to locate the body page. Check the isolated network, offline installer and local directory, Friday feedback exports, template and rehearsal, and undecided dates and budget. Open cited sources to verify each conclusion.++| Observation | Check |+| --- | --- |+| Runtime unavailable | Bot dependencies and the server's compile runtime configuration |+| Source or Skill missing | URI, read permissions, and processing results |+| Evidence missing | Actual read records and citations; refine the instruction and retry with a new target |++Completion means a readable, navigable body page with evidence for key facts. See the [LLM Wiki example](../context-compilation/02-llm-wiki.md) for structures, page types, and visualization. To clean up, identify the demo target in Studio, preserve any needed output, and delete the directory.diff --git a/docs/en/getting-started/14-versions.md b/docs/en/getting-started/14-versions.mdnew file mode 100644index 000000000..6d59d1f75--- /dev/null+++ b/docs/en/getting-started/14-versions.md@@ -0,0 +1,58 @@+# Version management++Save two versions in an isolated demo directory, inspect the difference, and restore the first version. Connect using [CLI basics](05-cli-setup.md). Processing uses the server's configured models and index.++## Save version one++```bash+ov mkdir viking://resources/onboarding-versions-v1+ov write viking://resources/onboarding-versions-v1/plan.md --mode create --content "Feedback is exported every Friday." --wait+ov snapshot commit -m "onboarding v1" --paths viking://resources/onboarding-versions-v1 -o json+```++Record `commit_oid` as `<v1>`. This tutorial operates only on the demo directory; use a new name for repeat runs. `snapshot commit` explicitly saves a snapshot. `session commit` archives conversation messages and starts memory extraction.++## Edit and compare++```bash+ov write viking://resources/onboarding-versions-v1/plan.md --content "Feedback is exported every Monday." --wait+ov snapshot commit -m "onboarding v2" --paths viking://resources/onboarding-versions-v1 -o json+```++Record the second `commit_oid` as `<v2>`. Replace the placeholders below with actual IDs:++```bash+ov snapshot show <v1> --path viking://resources/onboarding-versions-v1/plan.md+ov snapshot diff viking://resources/onboarding-versions-v1/plan.md --from <v1> --to <v2>+```++The old version should say Friday; the diff should show the change to Monday.++## Preview and restore++```bash+ov snapshot restore <v1> viking://resources/onboarding-versions-v1 --dry-run -o json+```++Inspect planned additions, changes, and deletions, confirming they belong to the demo directory. Restore writes changes back to that scope; preserve any newer work you need before applying it. Once the plan is confirmed:++```bash+ov snapshot restore <v1> viking://resources/onboarding-versions-v1 -m "restore onboarding v1" -o json+ov read viking://resources/onboarding-versions-v1/plan.md+ov snapshot log --paths viking://resources/onboarding-versions-v1 -o json+```++The content should say Friday again, with a new restore commit in history. `applied` means changes were applied; `noop` means the selected source tree matches HEAD. Read the file to confirm the working content.++## Check retrieval readiness++Restore schedules semantic and vector rebuilding as needed. Replace `<task_id>` with the ID returned by restore, then check retrieval after completion:++```bash+ov task status <task_id>+ov find "When is feedback exported?" --uri viking://resources/onboarding-versions-v1+```++If processing is ongoing, inspect its task and retry retrieval after completion. Use an initial 2-minute observation window and keep pending task IDs for later checks.++Snapshots store the selected source-file tree. Operations use current ACLs, and vectors are rebuilt from restored content. Account ignore rules and system pruning affect saved scope. See [Snapshot reference](../api/11-snapshot.md) and the [snapshot guide](../guides/15-snapshot.md). Identify the demo directory in Studio before cleaning it up; see the guide for history retention.diff --git a/docs/en/getting-started/15-transfer.md b/docs/en/getting-started/15-transfer.mdnew file mode 100644index 000000000..6d19c96f6--- /dev/null+++ b/docs/en/getting-started/15-transfer.md@@ -0,0 +1,153 @@+# Import and export++Export a source directory as an OVPack, import it under a new parent or into another OpenViking service, and verify files, metadata, and retrieval.++<a id="connect-a-test-account"></a>++## Connect to the service++Configure the CLI with a user or admin API key supplied by your administrator to connect to OpenViking. OVPack import and export require API Key authentication with `server.root_api_key` configured on the server.++To set up a local service, use a separate configuration file and storage directory, configure the models, set `server.auth_mode` to `api_key`, and configure `server.root_api_key`. Start the service, create an account, and add the returned `user_key` to the CLI configuration. See [API Key setup](../guides/04-authentication.md) and [CLI basics](05-cli-setup.md) for the steps. When using a new account, import the sample sources below into that account first.++## Prepare a source++Connect to the service and complete the import step in [Resource retrieval](08-resources.md#prepare-the-sources). This example uses `viking://resources/onboarding-en-v1`. You need read access to the source and write access to the target parent.++```bash+ov tree viking://resources/onboarding-en-v1+ov export viking://resources/onboarding-en-v1 ./lighthouse.ovpack+```++The package contains the selected directory's source files, semantic sidecars, and portable index scalars. This tutorial uses the default export and recomputes vectors on import, calling the destination's embedding model. See [OVPack reference](../api/14-ovpack.md) for full-account backup and restore.++## Import into a new location++```bash+ov mkdir viking://resources/onboarding-transfer-v1+ov import ./lighthouse.ovpack viking://resources/onboarding-transfer-v1 --vector-mode recompute+```++The second argument is the **target parent**. Save the actual root URI returned by import and use it below. This example normally produces `viking://resources/onboarding-transfer-v1/onboarding-en-v1`.++The default conflict policy is `fail`. If the target root exists, choose a new demo parent. `overwrite` replaces an existing root; `skip` preserves it. A new directory makes repeat runs easy to compare.++## Verify content and indexing++```bash+ov tree viking://resources/onboarding-transfer-v1/onboarding-en-v1+ov read viking://resources/onboarding-transfer-v1/onboarding-en-v1/project/project.md+ov read viking://resources/onboarding-transfer-v1/onboarding-en-v1/meeting/meeting.md+ov wait+```++Compare the four relative source paths, their text, and preserved abstracts and overviews. Vector processing may continue after import returns. Use `ov wait` to wait for queued processing; it may also wait for other queued work on the service. If the request times out, check `ov status` and retry later. Search once processing completes without related errors.++```bash+ov find "What must be prepared before the Lighthouse pilot?" --uri viking://resources/onboarding-transfer-v1/onboarding-en-v1+```++Completion means source content matches, required metadata is readable, and relevant material can be retrieved from the new directory. Ranking and scores may vary with destination models and indexing; check whether retrieved sources support the question.++<a id="migrate-from-service-a-to-service-b"></a>++## Migrate between services++For example, move the Lighthouse sources from development service A to test service B. The computer running the CLI transfers the data: download an `.ovpack` from A, then upload it to B. The two services do not need a direct connection.++This example transfers a selected resource directory and keeps the original data in A. Configure B's models, accounts, and credentials separately. See [OVPack reference](../api/14-ovpack.md) for full-account backup and restore.++### Configure both connections++Prepare two services with OVPack support and the authentication setup described above. The account on A needs source read access; the account on B needs target-parent write access. B also needs a working Embedding model. Confirm that B supports the package format exported by A, and pause edits to the sample directory during export so its contents can be compared.++Create two CLI configuration files in one local working directory. Enter each service's actual URL and its account's API key. The following addresses are examples:++`ov-a.conf`:++```json+{+ "url": "https://openviking-a.example.com",+ "api_key": "your-service-a-user-key"+}+```++`ov-b.conf`:++```json+{+ "url": "https://openviking-b.example.com",+ "api_key": "your-service-b-user-key"+}+```++In a macOS / Linux terminal, use `OPENVIKING_CLI_CONFIG_FILE` to select the connection for each command. Restrict access to the configuration files, then check connectivity to both services:++```bash+chmod 600 ./ov-a.conf ./ov-b.conf+OPENVIKING_CLI_CONFIG_FILE=./ov-a.conf ov health+OPENVIKING_CLI_CONFIG_FILE=./ov-b.conf ov health+```++Run the remaining commands from this working directory. Keep these files in a controlled local location because they contain access credentials.++### Export from A++Confirm that A contains the [Lighthouse sources](08-resources.md#prepare-the-sources), then download the directory to your computer:++```bash+OPENVIKING_CLI_CONFIG_FILE=./ov-a.conf ov tree viking://resources/onboarding-en-v1+OPENVIKING_CLI_CONFIG_FILE=./ov-a.conf ov export viking://resources/onboarding-en-v1 ./lighthouse-a-to-b.ovpack+```++On success, `lighthouse-a-to-b.ovpack` appears in the current directory. If you use a different computer to connect to B, transfer this file to it; keep A's credentials on the original computer.++### Import into B++Create a new migration parent in B and import the local package:++```bash+OPENVIKING_CLI_CONFIG_FILE=./ov-b.conf ov mkdir viking://resources/from-a-v1+OPENVIKING_CLI_CONFIG_FILE=./ov-b.conf ov import ./lighthouse-a-to-b.ovpack viking://resources/from-a-v1 --on-conflict fail --vector-mode recompute+```++With `recompute`, B generates vectors using its own Embedding model, accommodating different model configurations across environments. Import calls B's model and incurs its associated costs. If the target root already exists, choose a new parent and retry.++Record the actual root URI returned by import. This example normally produces `viking://resources/from-a-v1/onboarding-en-v1`, which the commands below use.++### Verify in B++Inspect the directory and source text, then wait for background vector processing on B:++```bash+OPENVIKING_CLI_CONFIG_FILE=./ov-b.conf ov tree viking://resources/from-a-v1/onboarding-en-v1+OPENVIKING_CLI_CONFIG_FILE=./ov-b.conf ov read viking://resources/from-a-v1/onboarding-en-v1/project/project.md+OPENVIKING_CLI_CONFIG_FILE=./ov-b.conf ov wait+```++`ov wait` waits for queued processing and may also be affected by other queued work on B. If the request times out, inspect B's status:++```bash+OPENVIKING_CLI_CONFIG_FILE=./ov-b.conf ov status+```++Wait again later if processing continues. For errors, inspect B's model and storage configuration and server logs. Once processing completes without related errors, search in B:++```bash+OPENVIKING_CLI_CONFIG_FILE=./ov-b.conf ov find "What must be prepared before the Lighthouse pilot?" --uri viking://resources/from-a-v1/onboarding-en-v1+```++| Check | Success criterion |+| --- | --- |+| Files and text | The four source files in B have the same relative paths and text as in A |+| Abstracts and overviews | Semantic sidecars preserved in the package are readable in B |+| Retrieval | Relevant preparation material is found, and the source at each result URI can be read |+| References and integration | Absolute URIs, service addresses in the text, and the agent's search scope have been checked against their actual locations in B |++After verification, update the application or agent with B's service URL, credentials, and resource search scope. Ask the same question and check the answer and citations to confirm that the application uses B's data. Keep the original directory in A for comparison and any later cutover arrangements.++## Package and conflict checks++The manifest records files, sizes, and checksums. Missing files, checksum mismatches, or unsupported format versions cause import to fail. Export again and check the transfer if needed. See [OVPack reference](../api/14-ovpack.md) for vector compatibility, `auto`/`require` modes, and archive validation.++Keep the package for comparison if useful. To clean up, identify the imported root under the new parent in Studio and delete the demo content. The original source remains available.diff --git a/docs/en/getting-started/16-rules.md b/docs/en/getting-started/16-rules.mdnew file mode 100644index 000000000..7438b90ba--- /dev/null+++ b/docs/en/getting-started/16-rules.md@@ -0,0 +1,144 @@+# Rules (Beta)++::: warning Beta notice+Rules are currently in Beta. The interfaces, parameters, and workflows described here may introduce breaking changes in future releases. Before upgrading, review the release notes and current documentation, and validate your existing integration in a test environment.+:::++A Rule stores an explicit requirement an agent should follow under specific conditions, such as a release check or a prohibition in a coding standard. OpenViking compiles these requirements into rules and retrieves them for a task. The agent then checks its actions or answers against the rules and source evidence.++In this walkthrough, save a release requirement for the Lighthouse demo project, then review two release notes. You will inspect the stored rule, retrieve it, and compare the review before and after the missing information is added.++## Use cases++| Scenario | Example rule | How the agent uses it |+| --- | --- | --- |+| Release review | Project release notes must include rollback steps | Check the notes before release and identify missing information |+| Code review | Team policy prohibits logging access keys in application code | Check changes and cite relevant code |+| Agreement review | User-provided obligations, conditions, and exceptions | Check evidence and distinguish satisfied, violated, and undetermined requirements |++A Skill describes how to do something; a Rule describes which requirements apply under which conditions. Explicit obligations and prohibitions belong in Rules. Personal preferences and ordinary suggestions can remain in memory.++## Prepare the environment++Prepare an OpenViking service with Rule support and a Python environment; see the [Quickstart](02-quickstart.md#prerequisites) for setup. The server needs working Embedding and Compiler models. The Compiler defaults to the VLM; see [Rules configuration](../configuration/01-server.md#rules). Compilation and retrieval call models and persist the demo rule in the current user's rule library, so a test user is suitable for this exercise.++Install the SDK in your Python environment:++```bash+python -m pip install --upgrade openviking-sdk+```++This example uses a Python HTTP SDK with `rule_compile()` and `rule_search()`. Both the server and SDK need Rule (Beta) support. For a managed service, confirm availability with the provider. See [API conventions](../api/01-overview.md) for connection and identity settings.++Put the following Python snippets into one `rule_demo.py` file in order. Set the service URL and current user's API key; omit `api_key` for a local service with authentication disabled.++## Save a rule++Use a requirement scoped to the demo project, with an explicit trigger and obligation:++```python+from openviking_sdk import SyncHTTPClient++client = SyncHTTPClient(url="http://localhost:1933", api_key="your-key")+task = client.rule_compile(+ instruction=(+ "When reviewing release notes for the Lighthouse demo project, "+ "the release notes must include rollback steps."+ ),+)+print("Compile task:", task["task_id"])+```++The service returns a background task ID. Wait for compilation and its associated indexing task, then read the generated rule:++```python+import time+++def wait_for_task(task_id, timeout=300):+ deadline = time.monotonic() + timeout+ while time.monotonic() < deadline:+ current = client.get_task(task_id)+ if current is None:+ raise RuntimeError(f"Task not found: {task_id}")+ if current["status"] == "completed":+ return current+ if current["status"] in {"failed", "cancelled"}:+ raise RuntimeError(current)+ time.sleep(1)+ raise TimeoutError(f"Task still running: {task_id}")+++result = wait_for_task(task["task_id"])["result"]+print("Operations:", result["operations"])+write_task_id = result.get("write_result", {}).get("task_id")+if write_task_id:+ wait_for_task(write_task_id)+for uri in result["written_uris"]:+ print(uri)+ print(client.read(uri))+```++Check that the rule retains the Lighthouse demo project scope, the release-note review condition, and the requirement to include rollback steps. A repeated submission may return `NOOP`, meaning an existing rule covers the input; continue to retrieval. `UNCERTAIN` or `REJECT` explains why no rule was written; address that reason first. After a timeout, use the printed task ID to check progress again.++## Retrieve for a task++Use this fixed fictional input: the complete release note for the Lighthouse demo project is “This release adds export progress indicators.” Submit that evidence together with the review goal:++```python+matches = client.rule_search(+ task_context=(+ "Review release notes for the Lighthouse demo project. "+ "The complete release note has been read: "+ "This release adds export progress indicators. "+ "Next, check release requirements and list missing information."+ ),+)+print(matches["rendered"])+print("Warning:", matches.get("warning"))+print("Scenario selection:", matches.get("scenario_selection"))+```++Save the file and run it:++```bash+python rule_demo.py+```++Find the rule text and URI in the output and check that it contains the rollback requirement. `rendered` contains the full rule text to give to an agent. Search retrieves potentially applicable rules; the agent checks whether the evidence satisfies them.++## Check the review++Append the complete `rendered` output to this prompt and give it to your agent. Both notes are demo materials; the agent only needs to read them and return a review:++```text+Using the rules below, review these two release notes for the Lighthouse demo project.++Version A, complete text: This release adds export progress indicators.+Version B, complete text: This release adds export progress indicators.+Rollback steps: Stop the new service, switch to the previous image, start it+with the previous configuration, and check the health endpoint.++Check each rule's conditions and exceptions. Cite its URI and the release-note+evidence. For each version, report whether the requirement is satisfied,+violated, or undetermined, and list any information to add.+Perform a text review only.++Complete retrieved rules:+(Paste the rendered output here.)+```++| Check | Expected observation |+| --- | --- |+| Applicability | Both notes belong to the Lighthouse demo project |+| Version A | Rollback steps are missing; the agent asks for them to be added |+| Version B | Rollback steps are present, satisfying this rule; their operational validity still needs deployment testing |+| Traceability | The answer cites the rule URI and the relevant release-note text |++These are acceptance criteria for the example; actual results depend on your model output. If retrieval returns no rules, check the compilation and indexing tasks, user identity, and task description. If a `warning` appears, inspect the indicated model configuration and have the agent check each condition. Empty results and pass-through scores still require an evidence review.++## Continue++After connecting [VikingBot](11-vikingbot.md), you can ask it to call `openviking_rule_search` for retrieval. In the current Beta, users or agents explicitly trigger compilation and search. Ordinary session commits do not automatically create Rules.++For batch imports or connecting your own agent, continue with [Rule validation](../workflows/02-rule-validation.md). See the [Rule lifecycle](../concepts/17-rule-scenarios.md#lifecycle) for pausing, updating, and archiving rules.diff --git a/docs/en/getting-started/17-authentication.md b/docs/en/getting-started/17-authentication.mdnew file mode 100644index 000000000..a0fd50864--- /dev/null+++ b/docs/en/getting-started/17-authentication.md@@ -0,0 +1,121 @@+# Authentication++An API key identifies the caller and determines which operations they can perform. For team use, a platform administrator configures a Root key, then creates separate credentials for team administrators and ordinary users.++This walkthrough enables API key authentication, creates the `acme` account with `team-admin` as its first administrator, and registers Alice and Bob as ordinary users. The other team management pages reuse these identities.++## Prerequisites++Use a self-hosted service whose configuration you can edit and restart. Prepare the `ov` CLI, curl, and an existing server configuration. Keep the model and storage settings from the [quickstart](02-quickstart.md); the JSON below shows only fields to merge into that configuration.++Volcengine manages authentication and accounts for its cloud service. Obtain credentials through its console; the Root key setup below applies to self-hosted services.++| Identity | Credential | Purpose |+| --- | --- | --- |+| Platform administrator, ROOT | `server.root_api_key` | Platform operations such as creating and managing accounts |+| Account administrator, ADMIN | `user_key` returned when creating the administrator | Manage users in that account, the administrator's own data, and shared sources |+| Ordinary user, USER | `user_key` returned when creating the user | Access personal data and authorized shared sources |++In API key mode, the server derives the account, user, and role from the credential. A Root key has no tenant user binding; use a User/Admin key for ordinary source, memory, and session operations.++## Configure a Root key++The platform administrator first backs up the active `ov.conf`. Generate a random key in a local terminal, for example:++```bash+python3 -c 'import secrets; print(secrets.token_urlsafe(32))'+```++Store the generated value securely and enter it in the server configuration. Keep the existing model, storage, and other server settings:++```json+{+ "server": {+ "host": "127.0.0.1",+ "auth_mode": "api_key",+ "root_api_key": "<random-root-key>"+ }+}+```++Restart using the original configuration path and startup options. A local service using the default path can run:++```bash+openviking-server --config ~/.openviking/ov.conf+```++Retain `--with-bot` if you also use VikingBot. See [Deployment](../guides/03-deployment.md) for network addresses, HTTPS, and reverse proxies.++After authentication is enabled, clients need the appropriate credentials. Existing data stays in its original storage and account; creating a team does not migrate data from the previous default account.++## Create an administrator++The platform administrator runs this step. The examples use bash or zsh on macOS / Linux. Set `OV_URL` to your service address. After running `read`, paste the Root key configured above and press Enter; input is hidden:++```bash+export OV_URL="http://127.0.0.1:1933"+read -r -s ROOT_KEY+export ROOT_KEY+```++Create `acme` and its first administrator, `team-admin`:++```bash+curl -sS -X POST "$OV_URL/api/v1/admin/accounts" \+ -H "X-API-Key: $ROOT_KEY" \+ -H "Content-Type: application/json" \+ -d '{"account_id":"acme","admin_user_id":"team-admin"}'+```++Check that the response has `status: ok` and save `result.user_key`. This is **team-admin's Admin key**, separate from the Root key. Deliver it securely to that administrator. The response contains credentials; restrict saved or forwarded copies to the intended user.++If `acme` already exists, continue with it. For a separate walkthrough, choose a new account name and replace the Account ID in subsequent commands.++## Create ordinary users++The team administrator opens the CLI connection wizard:++```bash+ov config+```++Add a Custom connection named `acme-admin`, using the service address and team-admin's Admin key. Save and activate it, check the connection, and register two ordinary users:++```bash+ov health+ov admin register-user acme alice --role user+ov admin register-user acme bob --role user+```++Each registration returns that user's `user_key`. Deliver the corresponding credential to Alice or Bob. They save their own connections as `acme-alice` and `acme-bob`. See [CLI basics](05-cli-setup.md) for connection setup.++To add another administrator, register a user with `--role admin`. See [Admin API](../api/08-admin.md) for role management. An account administrator can manage their team's members without a Root key.++## Verify the identity++In Alice's terminal, activate her connection:++```bash+ov config switch acme-alice+ov health -o json+ov ls viking://~/+```++The health response should report `account_id: acme`, `user_id: alice`, and `role: user`; listing Alice's home directory should succeed. With team-admin's connection, the identity should be `team-admin` with role `admin`.++Each person can use these connection names on their own computer. If one operator checks several identities, save the corresponding profiles and switch before each group of operations. Changing `--user` or `--account` does not change the identity bound to an API key.++## Troubleshooting++| Symptom | Next step |+| --- | --- |+| An old connection fails after enabling authentication | Add that user's User/Admin key through `ov config`. |+| Root can create an account but cannot read sources | Use a User/Admin key belonging to the account for data operations. |+| A user cannot register members | Switch to that account's administrator connection. |+| A new team cannot see previous data | Check the original account and choose publishing or migration in [Knowledge sharing](22-sharing.md). |++After platform operations, run `unset ROOT_KEY` to clear the variable from the current terminal. See [Authentication](../guides/04-authentication.md) for key rotation and other authentication modes.++## Next steps++Continue to [Account](18-accounts.md) to create a second team and verify isolation.diff --git a/docs/en/getting-started/18-accounts.md b/docs/en/getting-started/18-accounts.mdnew file mode 100644index 000000000..ce7973a5c--- /dev/null+++ b/docs/en/getting-started/18-accounts.md@@ -0,0 +1,89 @@+# Account++An Account is a team or tenant space in OpenViking. One service can host multiple accounts, each with its own users, sources, memories, and sessions.++Use separate accounts for teams, customers, or businesses that need distinct data boundaries. Members of one team collaborate within an account; use [ACL](21-access-control.md) for finer source permissions within that team.++## Understand the boundary++| Scope | Content | Sharing |+| --- | --- | --- |+| Account | Team users and data | Isolated from other accounts |+| User | Personal memories, sources, and sessions | Accessed by the user; selected knowledge can be published as shared sources |+| Shared sources | `viking://resources/...` | Shared within the current account, with optional ACL restrictions |++Two accounts can use the same URI, such as `viking://resources/team-check`. The request credential selects the account; there is no need to add an Account ID to the URI. This is logical data isolation. See [Account configuration](../api/08-admin.md) for dedicated storage or model settings.++## Prerequisites++Complete [Authentication](17-authentication.md) to create `acme`, `team-admin`, Alice, and Bob. The platform administrator has a Root key and has set `OV_URL` and `ROOT_KEY` in their terminal. This walkthrough adds a `beta` account.++Platform administrators create accounts; account administrators manage their own members. The checks below create empty directories without calling a generation model.++## Create another account++The platform administrator creates `beta` and its first administrator:++```bash+curl -sS -X POST "$OV_URL/api/v1/admin/accounts" \+ -H "X-API-Key: $ROOT_KEY" \+ -H "Content-Type: application/json" \+ -d '{"account_id":"beta","admin_user_id":"beta-admin"}'+```++Save `result.user_key` and deliver it to beta-admin. That administrator uses `ov config` to save a connection named `beta-admin`, with the same service address and their own Admin key.++## Create content in acme++Alice creates a new shared directory using her acme connection:++```bash+ov config switch acme-alice+ov health -o json+ov mkdir viking://resources/team-check+ov ls viking://resources+```++Check that the identity belongs to `acme` and `team-check` appears in the directory listing. Choose a fresh name if it already exists.++## Check from beta++Beta-admin uses their own connection to inspect the same URI:++```bash+ov config switch beta-admin+ov health -o json+ov stat viking://resources/team-check+```++Confirm that the active account is `beta`. If beta has no directory with that name, the command should report it as missing; the directory created in acme is not visible here.++Beta-admin can then create a directory with the same name:++```bash+ov mkdir viking://resources/team-check+ov ls viking://resources+```++Creation should succeed. Each account now has its own `team-check`, and subsequent changes apply within the respective account.++## Select a team connection++In API key mode, each user credential is bound to an Account and User. To access another team, obtain an identity and credential from that team's administrator and save a separate connection.++Applications should map each signed-in user to the appropriate OpenViking connection. Passing `--account` cannot turn an existing user key into another team's identity. See [Authentication](../guides/04-authentication.md) for deployments that pass identity through a trusted upstream.++## Check the result++| Check | Expected result |+| --- | --- |+| Alice's health response | `account_id` is `acme` |+| Beta-admin's health response | `account_id` is `beta` |+| Before creating the directory in beta | Acme's `team-check` is not visible |+| After creating it in beta | Each account has an independent directory |++If results differ, use `ov config show` and `ov health -o json` to check the active service, user, and account. Default local mode without authentication is not suitable for verifying multiple-user identity isolation.++## Next steps++Continue to [User](19-users.md) to check personal data boundaries within one account. See [Knowledge sharing](22-sharing.md) to deliver sources across accounts.diff --git a/docs/en/getting-started/19-users.md b/docs/en/getting-started/19-users.mdnew file mode 100644index 000000000..c02339460--- /dev/null+++ b/docs/en/getting-started/19-users.md@@ -0,0 +1,83 @@+# User++A User is a data-owning identity within an Account. OpenViking uses it to separate personal memories, private sources, and sessions. Alice and Bob can each retain long-term context while using shared team sources.++A User is the identity accessing the service. An application can map it to a person or a separate application identity. Multiple agents using one User key share that user's space; use different users when their personal data needs to remain separate.++## Understand user space++Alice's directory looks like this:++```text+viking://user/alice/+├── memories/ # Alice's long-term memories+├── resources/ # Alice's private sources+├── skills/ # Alice's private skills+├── peers/ # Alice's interaction counterparts+└── sessions/ # Alice's conversations+```++`viking://~/` aliases the current user's home directory. It expands to `viking://user/alice/` for Alice and `viking://user/bob/` for Bob. Shared sources live under `viking://resources/` in the same account.++## Prerequisites++Complete [Authentication](17-authentication.md), creating Alice and Bob as ordinary users in `acme` and saving `acme-alice` and `acme-bob` connections. This example creates an empty private directory and a session without triggering memory extraction.++## Create private content++Alice activates her connection, checks her identity, and creates a directory:++```bash+ov config switch acme-alice+ov health -o json+ov mkdir viking://~/resources/personal-check+ov ls viking://~/resources+```++The listing should include `personal-check`. Create a session owned by Alice with automatic commits disabled:++```bash+ov session new --session-id alice-user-check --no-auto-commit+ov session add-message alice-user-check --role user --content "This is Alice's personal project discussion."+ov session get alice-user-check+```++Check that the session contains the message. This saves conversation content; committing starts memory extraction. See [Memory usage](09-memory.md) for that workflow.++## Check as Bob++Bob lists his home directory with his own connection:++```bash+ov config switch acme-bob+ov ls viking://~/resources+```++This lists Bob's private sources. Try accessing the directory Alice just created:++```bash+ov ls viking://user/alice/resources/personal-check+```++Access should be denied. Account membership enables collaboration while personal spaces remain separated by User. To share selected knowledge, Alice publishes it as shared sources, as described in [Knowledge sharing](22-sharing.md).++## Users and roles++The User identifies the data owner; the role determines management capabilities:++| User role | Main capabilities |+| --- | --- |+| USER | Personal data operations and authorized shared-source access |+| ADMIN | Their own user space, account member management, and management of shared sources in the account |++An administrator's ordinary data requests still use their own User identity. In API key mode, changing identity headers cannot switch an administrator into Alice or Bob. Platform ROOT manages accounts and other platform operations; its key is not used to read ordinary tenant data.++Applications can reuse a user identity across conversations to accumulate long-term memory. Session IDs distinguish conversations; Peers distinguish stable interaction counterparts under that user.++## Check the result++Alice can access her directory and session. Bob's home alias resolves to his own space, and he cannot read Alice's private directory. If both see the same personal space, check whether they are sharing a key.++## Next steps++Read [Peer](20-peers.md) to organize sources and memories for different counterparts under one user. See [Admin API](../api/08-admin.md) for registration, roles, and key rotation.diff --git a/docs/en/getting-started/20-peers.md b/docs/en/getting-started/20-peers.mdnew file mode 100644index 000000000..901732f6a--- /dev/null+++ b/docs/en/getting-started/20-peers.md@@ -0,0 +1,129 @@+# Peer++A Peer is a stable interaction counterpart under the current user, such as a person or another agent. A consistent `peer_id` groups related sources and memories so later conversations can reuse them.++For example, Alice's assistant often collaborates with `review-agent`. Alice's own preferences belong in user memory; preferences associated with review-agent can be stored in that Peer's memory.++## Identity and counterpart++| Concept | Meaning in this example |+| --- | --- |+| Account: `acme` | Alice's team |+| User: `alice` | Data owner and service-access identity |+| Peer: `review-agent` | Alice's stable counterpart |+| Session | One conversation with that counterpart |++Review-agent's content lives under `viking://user/alice/peers/review-agent/`. A Peer ID does not create a separate User or issue credentials. Even a Peer named `bob` remains a counterpart in Alice's space, separate from the real user Bob's personal space.++## Prerequisites++Complete [Authentication](17-authentication.md) and use the `acme-alice` connection. This example first checks Peer source scoping, then demonstrates memory extraction. Source writes and extraction require working server models and incur model calls.++Keep a stable ID for the same counterpart, such as `review-agent`. Use a single path segment without `/`. When repeating the walkthrough, choose a new session ID while keeping the Peer ID to retain continuity.++## Save counterpart sources++Alice creates source directories for two counterparts:++```bash+ov config switch acme-alice+ov mkdir viking://~/peers/review-agent/resources+ov mkdir viking://~/peers/research-agent/resources+```++Write a collaboration note for review-agent:++```bash+ov write viking://~/peers/review-agent/resources/brief.md \+ --mode create --content "review-agent handles reviews. Organize recommendations into Issue, Impact, and Recommendation columns." --wait+```++After processing finishes, read the source to check its content:++```bash+ov read viking://~/peers/review-agent/resources/brief.md+```++If waiting times out, retain the returned task ID and check it with `ov task status <task_id>`. Continue after completion.++## Scope requests to a Peer++With Alice's connection, use `actor_peer_id` to restrict a request's Peer collection to review-agent:++```bash+ov --actor-peer-id review-agent ls viking://~/peers+ov --actor-peer-id review-agent read viking://~/peers/review-agent/resources/brief.md+```++The listing should contain only the allowed Peer, and reading its note should succeed. Try accessing the other Peer:++```bash+ov --actor-peer-id review-agent ls viking://~/peers/research-agent/resources+```++Access should be denied. To retrieve review-agent's sources by question, target its directory:++```bash+ov --actor-peer-id review-agent find "What format should review recommendations use?" \+ --uri viking://~/peers/review-agent/resources+```++Actor Peer restricts only the current user's Peer collection. User-level memories, sources, and accessible shared sources retain their existing visibility, and sessions remain owned by Alice. For external participants, a trusted entry point should select the Peer scope; a client holding Alice's full key can change or omit it. Use distinct User identities for independent user permissions.++## Save Peer memory++A message's `peer_id` identifies its counterpart; `actor_peer_id` scopes request access. Set them separately. This example extracts only the counterpart's preferences, creating a session through HTTP with an explicit memory policy.++In Alice's terminal, set the service address and enter her User key with hidden input:++```bash+export OV_URL="http://127.0.0.1:1933"+read -r -s ALICE_KEY+export ALICE_KEY+```++Create a session with Peer memory enabled, Self extraction disabled for this session, and manual commits:++```bash+curl -sS -X POST "$OV_URL/api/v1/sessions" \+ -H "X-API-Key: $ALICE_KEY" \+ -H "Content-Type: application/json" \+ -d '{"session_id":"peer-review-a","auto_commit_policy":null,"memory_policy":{"self":{"enabled":false},"peer":{"enabled":true},"memory_types":["preferences"]}}'+```++After confirming success, record and commit a message using Alice's CLI connection:++```bash+ov session add-message peer-review-a --role user --peer-id review-agent \+ --content "I am review-agent. I prefer review recommendations in a table with Issue, Impact, and Recommendation columns. Please use this format in future reviews with me."+ov session commit peer-review-a+```++Retain the returned `task_id` and `archive_uri`. Check every five seconds for up to two minutes initially; if still running, retain the ID and check later. Inspect the cause if the task is `failed` or `cancelled`:++```bash+ov task status <task_id>+```++Once `completed`, read the change record:++```bash+ov read "<archive_uri>/memory_diff.json"+```++Find the memory URI in `operations.adds` or `operations.updates` and read it with `ov read`. Expect a record under `viking://user/alice/peers/review-agent/memories/` retaining the three-column preference. Filenames depend on extraction. If nothing was added, check for an existing memory update and whether the active template supports Peer preferences.++## Use it in later tasks++In a new conversation, have an agent using Alice's connection retrieve the Peer's memory first:++```bash+ov --actor-peer-id review-agent find "review-agent's preferred review format" \+ --uri viking://~/peers/review-agent/memories+```++Read the matching memory, then ask the agent to produce a review table following the preference and cite the memory URI. Keep tagging relevant messages with `review-agent` in new sessions so later commits can accumulate its memories.++## Next steps++Peer content belongs to the current user. Continue to [Knowledge sharing](22-sharing.md) to make selected knowledge available to teammates. See [Multi-tenancy](../concepts/11-multi-tenant.md#peer-restricted-view) for complete filtering rules.diff --git a/docs/en/getting-started/21-access-control.md b/docs/en/getting-started/21-access-control.mdnew file mode 100644index 000000000..442d37aa9--- /dev/null+++ b/docs/en/getting-started/21-access-control.md@@ -0,0 +1,118 @@+# Access control++ACL determines who can read, edit, or manage shared sources within one account. Use it for project collaboration, selected readers, and group-based maintenance.++This page creates a shared directory managed by Alice and readable by Bob, then checks reading, denied writes, and revocation. Account administrators retain implicit management access to shared sources.++## Prerequisites++Complete [Authentication](17-authentication.md) and prepare `acme-admin`, `acme-alice`, and `acme-bob` connections. Alice and Bob are ordinary users so that the checks exercise their grants.++ACL applies to `viking://resources/...`. Personal memories, private sources, and Peer spaces retain their User boundary. See [Knowledge sharing](22-sharing.md) to share selected content from those spaces.++## Enable ACL++Acme's administrator sets the service address and enters team-admin's Admin key with hidden input:++```bash+export OV_URL="http://127.0.0.1:1933"+read -r -s ADMIN_KEY+export ADMIN_KEY+```++Enable ACL checks for the account:++```bash+curl -sS -X PATCH "$OV_URL/api/v1/admin/accounts/acme/configuration" \+ -H "X-API-Key: $ADMIN_KEY" \+ -H "Content-Type: application/json" \+ -d '{"settings":{"acl":{"enabled":true}}}'+```++Check that `result.settings.acl.enabled` is `true`. This switch defaults to off; shared sources are not ACL-filtered while it is off. Writing grants does not enable the switch automatically.++## Create a restricted directory++The shared root grants `manage` to everyone in the account, and descendants inherit parent permissions. Use `restricted` to cut off inheritance and assign direct grants when limiting access to selected members.++The administrator creates a new example directory:++```bash+ov config switch acme-admin+ov mkdir viking://resources/team-knowledge \+ --acl '{"acl_mode":"restricted","entries":[{"principal":"user:alice","level":"manage"},{"principal":"user:bob","level":"read"}]}'+```++If it already exists, inspect its grants with `ov acl get`. Choose a fresh name for this walkthrough to preserve existing grants.++| Level | Allowed operations |+| --- | --- |+| `read` | Read, list, and retrieve |+| `write` | Includes read, plus writing, creating, deleting, or moving files |+| `manage` | Includes write, plus managing ACL and deleting or moving directories |++## Write a source++Alice publishes a note. Writing triggers semantic and vector processing, requiring available models and incurring model calls:++```bash+ov config switch acme-alice+ov write viking://resources/team-knowledge/access-check.md \+ --mode create --content "Team agreement: summarize project feedback every Friday." --wait+```++The new file inherits the directory grants. Inspect the directory ACL and original content:++```bash+ov acl get viking://resources/team-knowledge+ov read viking://resources/team-knowledge/access-check.md+```++If waiting times out, check the returned task ID and continue after processing completes.++## Verify as Bob++Bob uses his own connection to read and retrieve:++```bash+ov config switch acme-bob+ov read viking://resources/team-knowledge/access-check.md+ov find "When is project feedback summarized?" --uri viking://resources/team-knowledge+```++Reading should succeed and retrieval should include the note. Try creating a file:++```bash+ov write viking://resources/team-knowledge/bob-check.md \+ --mode create --content "Bob's write check."+```++Bob has only `read`, so the write should be denied. If it succeeds, check whether the active identity is an administrator, whether account ACL is enabled, and whether other effective grants permit writing.++## Change grants++Alice has `manage` and can grant Bob editing access:++```bash+ov config switch acme-alice+ov acl grant viking://resources/team-knowledge --principal user:bob --level write+```++Bob can rerun the preceding write command; it should now succeed. To return to reading only, set the level back to `read`. To end access, revoke the direct grant:++```bash+ov acl grant viking://resources/team-knowledge --principal user:bob --level read+ov acl revoke viking://resources/team-knowledge --principal user:bob+```++Alice runs these two commands. Switch to Bob afterward; reading `access-check.md` should be denied. Permission indexing can have a short delay. Check every two seconds for up to 30 seconds initially; if access continues, inspect effective permissions and other grant sources.++`revoke` removes the direct entry on this node. Access from a parent or group remains effective. Revocation also does not remove already downloaded copies. To continue with the next sharing walkthrough, Alice restores Bob's `read` grant.++## Grant to a group++For larger teams, an administrator can create an account-local group and manage its members, then grant access to `group:<group_id>`. Membership changes apply to subsequent requests. This is useful for project subteams; see [Admin API](../api/08-admin.md) for group and membership operations.++## Next steps++Continue to [Knowledge sharing](22-sharing.md) to publish accumulated project knowledge into this controlled directory. See [ACL concepts](../concepts/15-acl.md) for inheritance and directory-move behavior.diff --git a/docs/en/getting-started/22-sharing.md b/docs/en/getting-started/22-sharing.mdnew file mode 100644index 000000000..daeb49a68--- /dev/null+++ b/docs/en/getting-started/22-sharing.md@@ -0,0 +1,197 @@+# Knowledge sharing++Personal memories help agents retain a user's working context. When colleagues need project agreements or reusable experience, the memory owner can select the relevant knowledge, publish it as shared sources, and let other members' agents retrieve, read, and cite it.++This walkthrough follows Alice sharing Cape project review conventions with Bob: **select memories → prepare content → publish with permissions → retrieve and use as Bob → maintain updates**. It also covers delivery across teams.++## Choose a sharing method++| Scenario | Method |+| --- | --- |+| Share sources within an account | Publish under `viking://resources/...` and grant users or groups access through ACL. |+| Share personal experience within an account | The owner selects memory content and publishes it as shared sources. |+| Deliver knowledge between accounts | The source owner prepares deliverable content; the recipient imports it with their own credentials and assigns destination permissions. |+| Accumulate a team memory across users | The application coordinates knowledge selection, publishing, and updates; there is no switch that automatically merges private memories across users. |++Personal and Peer memory directories do not accept shared-source ACL. Published content is maintained as shared sources, separately from the original memories.++## Prerequisites++Complete [Authentication](17-authentication.md), preparing ordinary users Alice and Bob and their connections. Follow [Access control](21-access-control.md) to enable ACL for `acme` and create `viking://resources/team-knowledge`, with Alice as `manage` and Bob as `read`. If you tried revocation, Alice first restores Bob's `read` grant.++Alice needs a project memory to share. For a first walkthrough, use Alice's connection to complete the save-background and inspect-memory steps in [Memory usage](09-memory.md), producing the Cape conventions. This page does not require VikingBot; an agent with CLI access can perform the final question-answering step.++Imports, retrieval, and agent answers use the corresponding models. Each member uses their own credentials, with responsibilities divided as follows:++| Role | Responsibility |+| --- | --- |+| Account administrator | Enable ACL, create the shared directory, and assign initial grants. |+| Alice or her agent | Read Alice's memories, prepare a draft, publish, and maintain it. |+| Bob or his agent | Retrieve authorized sources, read the originals, and use them in tasks. |++## Alice selects memories++Use Alice's own connection in her terminal or agent:++```bash+ov config switch acme-alice+ov find "Cape project review conventions" --uri viking://~/memories+```++Read relevant results and identify what to share:++```bash+ov read "<memory-uri>"+```++Alice can give her agent this task:++```text+Prepare Cape project review conventions that I can share with Bob from my memories.+Read the originals, distinguish confirmed requirements from open questions, and draft Markdown.+Include sources for my review. Let me confirm the draft before publishing it to shared sources.+```++Alice confirms the content to publish. The shared document should contain understandable facts or cite sources Bob can read. Alice can retain private memory URIs in her personal review notes.++## Alice prepares a draft++For the Cape example, verify the memories and create `cape-review.md` locally:++```markdown+# Cape project review conventions++## Review requirements++- Discuss two risks in each review.+- Use three Chinese bullet points for the summary.+- Name the deliverable cape-review.csv.++## Open information++- The specific risks for this review have not been provided.++## Maintenance++- Maintainer: Alice+- Scope: Cape project reviews+```++This document corresponds to the sample input. For a real project, replace it with facts from the memories that Alice has confirmed, retaining the scope and open questions.++## Alice publishes sources++Choose a publishing method based on where the content is stored. Copy existing sources directly on the server, or import a newly prepared local draft with `add-resource`. Both methods use Alice's connection and publish to the directory already authorized for Bob.++### Copy existing sources++If the content is already in Alice's personal source directory, confirm that its text and references are suitable for sharing, then copy it without downloading it. This example assumes the source is `viking://~/resources/cape-review/cape-review.md`; replace it with the actual URI.++Alice needs read access to the source and `write` or `manage` permission on the target directory. Create a new publication directory under `team-knowledge`, then copy the file:++```bash+ov config switch acme-alice+ov read viking://~/resources/cape-review/cape-review.md+ov mkdir viking://resources/team-knowledge/cape-review+ov cp viking://~/resources/cape-review/cape-review.md \+ viking://resources/team-knowledge/cape-review/cape-review.md -o json+ov read viking://resources/team-knowledge/cape-review/cape-review.md+```++Here, `~` resolves to Alice, the current connection's user. The new shared source inherits target directory permissions, allowing Bob to retrieve and read it as described below. Alice's original remains in her personal directory.++If the entire source directory is suitable for sharing, use the following command instead of `mkdir` and the single-file copy above. The target parent `team-knowledge` must already exist; the target URI is the resulting directory location:++```bash+ov cp -r viking://~/resources/cape-review \+ viking://resources/team-knowledge/cape-review -o json+ov tree viking://resources/team-knowledge/cape-review+```++Copying includes existing vector records. Target parent summaries may refresh asynchronously: `semantic_status: queued` means the refresh is queued; `failed` indicates that `semantic_error` needs attention. Have Bob retrieve and read the published content to confirm access. See the [filesystem API](../api/03-filesystem.md#cp) for details.++The result is an independent copy; later source edits do not synchronize automatically. Copying to an existing file replaces its content. Directory copies merge into existing directories and retain files unique to the target. Use a new path for the first publication. Before updating, review the target content and any private URIs in the body that need replacing.++### Import a local draft++For the local Markdown draft prepared above, publish from its directory to a new path:++```bash+ov add-resource ./cape-review.md \+ --to viking://resources/team-knowledge/cape-review --wait+```++The publication inherits `team-knowledge` permissions. After processing completes, expand the directory and read the actual source URI:++```bash+ov tree viking://resources/team-knowledge/cape-review+ov read "<shared-source-uri>"+```++Retain that URI for Bob and future updates. If waiting times out, check the returned task ID with `ov task status <task_id>`. Confirm completion before Bob uses it.++## Bob retrieves and uses it++Bob retrieves with his own connection:++```bash+ov config switch acme-bob+ov find "What review format and deliverable filename does the Cape project use?" \+ --uri viking://resources/team-knowledge/cape-review+```++Read the shared source URI from the results and check the content. Then give Bob's agent this task:++```text+Use my ov CLI connection to retrieve sources under viking://resources/team-knowledge/cape-review.+Read the relevant originals and prepare a review outline following Cape conventions.+State the summary format, number of risks, and deliverable filename, citing full shared-source URIs.+Leave placeholders for specific risks that have not been provided.+```++The agent needs CLI access and must include the shared directory in its retrieval workflow. Access grants allow reading; the agent still needs to retrieve and read the content to use it in an answer.++| Check | Expected result |+| --- | --- |+| Identity | Bob's `ov health -o json` reports `acme` / `bob`. |+| Source | Results come from shared sources under `team-knowledge/cape-review`. |+| Answer | Two risks, three Chinese summary bullets, and `cape-review.csv`. |+| Unknown details | Specific risks remain placeholders or are identified as unspecified. |+| Private boundary | Bob still cannot read Alice's original private memory directory. |++## Maintain the publication++Alice maintains the content by default. For sources published by server-side copy, review the updated source and repeat the same file copy command. This replaces the shared copy's content while preserving target permissions.++For a publication from a local draft, edit `cape-review.md`, then update the source URI recorded earlier:++```bash+ov config switch acme-alice+ov write "<shared-source-uri>" --from-file ./cape-review.md --mode replace --wait+```++This replaces the complete file and reprocesses it. Check that the local file includes all content to retain before publishing. After completion, Bob retrieves and reads again to verify the updated conventions.++Changes to Alice's personal memories do not automatically update the publication. For joint editing, Alice can grant Bob `write`; revoke access when collaboration ends, as described in [Access control](21-access-control.md). Copies Bob already downloaded or saved require separate handling.++## Deliver across accounts++If Bob belongs to another account, such as `beta`, acme's ACL cannot grant access directly to beta's users. `user:bob` identifies Bob only within the current account.++Alice can deliver the approved `cape-review.md` to beta's source maintainer through an agreed channel. Beta's administrator follows [Access control](21-access-control.md) to enable ACL **in beta**, create a restricted shared directory, and authorize its intended members. Replace the example Account ID and user IDs with beta's actual members.++With destination write access, beta's maintainer imports the received file using their own connection:++```bash+ov config switch beta-admin+ov add-resource ./cape-review.md \+ --to viking://resources/team-knowledge/cape-review --wait+```++`beta-admin` is the destination connection created in [Account](18-accounts.md). Beta independently manages its directory, members, and grants. After import, destination members retrieve and verify the content. Each account retains its own copy; later updates require another delivery or application-managed synchronization.++For bulk migration, see [Import and export](15-transfer.md). Verify destination identities, permissions, and source links afterward. If subteams need to maintain one shared copy over time, put collaborators in the same account and use groups and ACL to separate access scopes.++## Next steps++Repeat the workflow with a real project agreement and check that Bob's agent finds and uses the shared content. See [Resource search](08-resources.md) for a broader source-based answering workflow.diff --git a/docs/en/getting-started/23-studio.md b/docs/en/getting-started/23-studio.mdnew file mode 100644index 000000000..14a016fe0--- /dev/null+++ b/docs/en/getting-started/23-studio.md@@ -0,0 +1,93 @@+# Studio basics++OpenViking Studio is the web interface included with the service. Use it to browse imported resources, retrieve relevant content, inspect memories and skills, and track background tasks. Studio connects the `viking://` URIs returned by the CLI to their contents, so you can check the context an Agent uses.++This guide walks through connecting to a service, checking the dashboard, opening a resource, running a query, and inspecting a task. By the end, you can confirm that a resource is readable, appears in retrieval results, and has finished processing.++## Prepare a service++Have a running OpenViking service and its address ready. For a first installation, follow the [quickstart](02-quickstart.md) to install the tools, configure models, and start the service. If initialization is complete but your local service is stopped, run:++```bash+openviking-server+```++Keep the terminal open and visit [Studio](http://127.0.0.1:1933/studio/). The default local port is `1933`. For another port or a remote deployment, use the actual service address followed by `/studio/`.++For a service with API Key authentication, prepare a User Key. Users with administrative responsibilities can also use an Admin Key. An administrator creates these keys as described in [Authentication](17-authentication.md). A local development service with authentication disabled accepts an empty key.++The screenshots use an isolated local demo service on port `1940` with fictional Lighthouse project resources. A new service may have no data yet; complete the resource import in the quickstart before following the content examples below.++## Connect to the service++On your first visit, choose the service type in the connection wizard. For a local deployment, select **Open source**, enter the service address, such as `http://127.0.0.1:1933`, choose your interface language, and continue.++On the identity screen, enter your user API key and click **Verify connection**. After verification, check the displayed Account and User, then enter Studio. Browsing and retrieval use the data scope of this identity.++The Root/Admin Key field is an optional management credential; configure it when needed. Routine resource access uses a user identity. See [Authentication](17-authentication.md) for details. To change an existing connection, use the connection name in the upper-left corner or open **Connection Settings**.++## Check the dashboard++Home shows context data volume, tokens consumed today, retrieval calls today, and usage and submission trends. Return here after importing resources or running queries to understand usage. A newly started service may have empty charts or zero counts.++++The sidebar groups pages into Workspace, Activity, and Settings. Start with **Filesystem** and **Retrieval** to inspect content, use **Task Center** to check processing progress, and open **Monitoring** for service status.++## Browse resources++Open **Filesystem**, expand `resources`, locate an imported directory, and select a file. Its contents appear in the center panel. For Markdown, switch between **Preview** and **Source**. Copy the full `viking://` URI from the toolbar to use it in a query or pass it to an Agent.++++The Lighthouse source states that feedback is stored in local files, exported weekly by the pilot administrator to the project owner, and has no cloud synchronization in the first version. Checking these concrete facts helps you assess whether an Agent's answer is grounded in the resource.++The filesystem also exposes other context: `user` contains user memories, while `agent` contains Agent skills and experience. Visible directories and available operations depend on the active identity and its permissions.++To import another resource, click **Add resource** and choose the source and destination in the form. Check its processing result in Task Center, then open the file to inspect its contents. See [Resource retrieval](08-resources.md) for directories and import methods. The version history and OVPack toolbar entries lead to the operations covered in [Version management](14-versions.md) and [Import and export](15-transfer.md).++## Retrieve content++Open **Retrieval**, select `find`, and enter a concrete question, such as “How should Lighthouse collect feedback in its first version, and what must be prepared?”. Choose **Custom URI** as the scope and enter the resource directory URI. Click the search button or press Enter.++If you used the quickstart directory, enter `viking://resources/lighthouse-demo`. The screenshot uses `viking://resources/lighthouse-demo-en`; use the URI copied from your own filesystem.++++Results show the URI, a description, the context layer, and a relevance score. Click a file result to inspect its contents. If a result is a directory abstract, continue into the directory to read the source. Scores compare how closely results match the query; check factual claims against the original text.++| Method | When to use it |+| --- | --- |+| `find` | Find context by meaning for a standalone query |+| `search` | Use enhanced retrieval that can incorporate session context to interpret intent |+| `grep` | Match text or regular expressions inside file contents |+| `glob` | Find files using path patterns |++To generate an answer from the retrieved resources, continue with [VikingBot](11-vikingbot.md) or [connect your own Agent](../agent-integrations/01-overview.md).++## Track tasks++Resource imports, session commits, and index rebuilds create background tasks. Open **Task Center**, filter by task type or status, and select a task to inspect its resource URI, pipeline progress, duration, and execution log.++++After a task shows **Completed**, return to Filesystem and Retrieval to check the output. For a failed task, inspect its error and execution log to identify the affected stage, then check the relevant configuration or input.++**Sessions** lets you browse conversation records and inspect memory changes from session commits. Follow [Memory usage](09-memory.md) to extract memories from a conversation and recall them in a later task.++## Explore other pages++| Page | Purpose | Learn more |+| --- | --- | --- |+| VikingBot | Chat with the built-in Agent and complete tasks using resources; requires Bot to be enabled | [VikingBot](11-vikingbot.md) |+| Skills | Browse and manage instructions that Agents can use | [Skill usage](10-skills.md) |+| Compile | Organize source material into reusable content such as a Wiki; requires an available Compile Runtime | [Context compilation](13-compile.md) |+| Agent Experience | Inspect experience context accumulated by Agents | [Memory usage](09-memory.md) |+| Request Logs | Inspect request records to investigate call failures | [Observability and troubleshooting](../guides/05-observability.md) |+| Scheduled Sync | View and manage configured resource synchronization tasks | [Watch API](../api/15-watches.md) |+| Monitoring | Check service health and components such as queues, models, and storage | [Observability and troubleshooting](../guides/05-observability.md) |+| Gateway | Manage model upstreams, context policies, and gateway credentials | [Gateway integration](12-gateway.md) |++Available capabilities depend on the service configuration and your permissions. For team data boundaries and sharing permissions, see [Account](18-accounts.md) and [Access control](21-access-control.md).++Next, run a query relevant to your own work, open the source, and compare it with the Agent's answer. Use [Evaluation](06-evaluate.md) to record whether resource coverage and answer quality meet your task's needs.diff --git a/docs/images/quickstart/evaluation-v1.csv b/docs/images/quickstart/evaluation-v1.csvnew file mode 100644index 000000000..6640f3a5e--- /dev/null+++ b/docs/images/quickstart/evaluation-v1.csv@@ -0,0 +1,6 @@+case_id,task,input,expected_facts,expected_sources,actual_answer,actual_sources,stage,result,seconds,versions,notes+R1,direct,,,,,,,,,,,+R2,multi-source,,,,,,,,,,,+R3,no-answer,,,,,,,,,,,+M1,related-memory,,,,,,,,,,,+M2,unrelated-memory,,,,,,,,,,,diff --git a/docs/images/quickstart/feedback-brief-v1.zip b/docs/images/quickstart/feedback-brief-v1.zipnew file mode 100644index 000000000..ecf3fc30cBinary files /dev/null and b/docs/images/quickstart/feedback-brief-v1.zip differdiff --git a/docs/images/quickstart/gateway-demo-v1.zip b/docs/images/quickstart/gateway-demo-v1.zipnew file mode 100644index 000000000..4ff6fade6Binary files /dev/null and b/docs/images/quickstart/gateway-demo-v1.zip differdiff --git a/docs/images/quickstart/gateway-demo.py b/docs/images/quickstart/gateway-demo.pynew file mode 100644index 000000000..266b8b5df--- /dev/null+++ b/docs/images/quickstart/gateway-demo.py@@ -0,0 +1,50 @@+"""Fictional OpenViking gateway trial. Uses Python 3 standard library only."""+import argparse+import json+import os+import urllib.error+import urllib.request++parser = argparse.ArgumentParser(description=__doc__)+parser.add_argument('phase', choices=['capture', 'recall'])+parser.add_argument('--language', choices=['zh', 'en'], default='zh')+parser.add_argument('--run', default='v1', help='Use a fresh value for another experiment')+args = parser.parse_args()+base = os.environ.get('GATEWAY_URL', 'http://127.0.0.1:1933/gateway').rstrip('/')+key = os.environ.get('GATEWAY_KEY')+model = os.environ.get('GATEWAY_MODEL')+if not key or not model:+ parser.error('Set GATEWAY_KEY and GATEWAY_MODEL first.')++def ask(messages, session):+ request = urllib.request.Request(+ base + '/v1/chat/completions',+ data=json.dumps({'model': model, 'messages': messages}).encode(),+ headers={'Authorization': 'Bearer ' + key, 'Content-Type': 'application/json',+ 'X-OpenViking-Session': session},+ )+ try:+ with urllib.request.urlopen(request, timeout=120) as response:+ result = json.load(response)+ except urllib.error.HTTPError as exc:+ raise SystemExit(f'Gateway returned HTTP {exc.code}; inspect its request log.') from None+ except (urllib.error.URLError, TimeoutError):+ raise SystemExit('Gateway request could not complete; check the URL and service log.') from None+ message = result['choices'][0]['message']+ print(message.get('content', ''))+ return {k: v for k, v in message.items() if k in {'role', 'content', 'reasoning_content'}}++if args.phase == 'capture':+ fact = ('请记住虚构山岚项目的约定:项目评审固定检查四项风险,所有报告使用 Markdown 格式,文件名为 mist-review.md。以后准备该项目的评审时请沿用。'+ if args.language == 'zh' else+ 'Remember the fictional Mist project conventions: reviews check exactly four risks, all reports use Markdown, and the filename is mist-review.md. Follow these conventions for future project reviews.')+ messages = [{'role': 'user', 'content': fact}]+ session = 'gateway-mist-a-' + args.run+ messages.append(ask(messages, session))+ messages.append({'role': 'user', 'content': '谢谢。' if args.language == 'zh' else 'Thank you.'})+ ask(messages, session)+else:+ question = ('请按已保存的山岚项目约定,准备下次评审的检查清单,并给出交付文件名。'+ if args.language == 'zh' else+ 'Use the saved Mist project conventions to prepare the next review checklist and give the delivery filename.')+ ask([{'role': 'user', 'content': question}], 'gateway-mist-b-' + args.run)diff --git a/docs/images/quickstart/gateway/capture-en.jpg b/docs/images/quickstart/gateway/capture-en.jpgnew file mode 100644index 000000000..b00779f6aBinary files /dev/null and b/docs/images/quickstart/gateway/capture-en.jpg differdiff --git a/docs/images/quickstart/gateway/capture-zh.jpg b/docs/images/quickstart/gateway/capture-zh.jpgnew file mode 100644index 000000000..96bd9e51cBinary files /dev/null and b/docs/images/quickstart/gateway/capture-zh.jpg differdiff --git a/docs/images/quickstart/gateway/key-en.jpg b/docs/images/quickstart/gateway/key-en.jpgnew file mode 100644index 000000000..47fb48c61Binary files /dev/null and b/docs/images/quickstart/gateway/key-en.jpg differdiff --git a/docs/images/quickstart/gateway/key-zh.jpg b/docs/images/quickstart/gateway/key-zh.jpgnew file mode 100644index 000000000..c08a0af0fBinary files /dev/null and b/docs/images/quickstart/gateway/key-zh.jpg differdiff --git a/docs/images/quickstart/gateway/recall-en.jpg b/docs/images/quickstart/gateway/recall-en.jpgnew file mode 100644index 000000000..fda02b9dfBinary files /dev/null and b/docs/images/quickstart/gateway/recall-en.jpg differdiff --git a/docs/images/quickstart/gateway/recall-zh.jpg b/docs/images/quickstart/gateway/recall-zh.jpgnew file mode 100644index 000000000..a8f46f8e6Binary files /dev/null and b/docs/images/quickstart/gateway/recall-zh.jpg differdiff --git a/docs/images/quickstart/gateway/upstream-en.jpg b/docs/images/quickstart/gateway/upstream-en.jpgnew file mode 100644index 000000000..12104af64Binary files /dev/null and b/docs/images/quickstart/gateway/upstream-en.jpg differdiff --git a/docs/images/quickstart/gateway/upstream-zh.jpg b/docs/images/quickstart/gateway/upstream-zh.jpgnew file mode 100644index 000000000..c6270deffBinary files /dev/null and b/docs/images/quickstart/gateway/upstream-zh.jpg differdiff --git a/docs/images/quickstart/lighthouse-en-v1.zip b/docs/images/quickstart/lighthouse-en-v1.zipnew file mode 100644index 000000000..a8cf55324Binary files /dev/null and b/docs/images/quickstart/lighthouse-en-v1.zip differdiff --git a/docs/images/quickstart/lighthouse-zh-v1.zip b/docs/images/quickstart/lighthouse-zh-v1.zipnew file mode 100644index 000000000..d2f2257a1Binary files /dev/null and b/docs/images/quickstart/lighthouse-zh-v1.zip differdiff --git a/docs/images/quickstart/lighthouse.en.txt b/docs/images/quickstart/lighthouse.en.txtnew file mode 100644index 000000000..480c61819--- /dev/null+++ b/docs/images/quickstart/lighthouse.en.txt@@ -0,0 +1,17 @@+# Lighthouse pilot notes++This is a fictional sample for the OpenViking quickstart, not a real customer deployment.++## Pilot environment++The first version of Lighthouse runs in an isolated network without internet access.+The pilot administrator must prepare an offline installation package and a local storage directory.++## Feedback collection++User feedback is saved to local files. Each week, the pilot administrator exports the files and passes them to the project owner.+The first version does not provide cloud synchronization. Whether a later version will add it has not been decided.++## Open questions++The pilot end date and the release date of the next version have not been decided.diff --git a/docs/images/quickstart/lighthouse.zh.txt b/docs/images/quickstart/lighthouse.zh.txtnew file mode 100644index 000000000..95e2a36a4--- /dev/null+++ b/docs/images/quickstart/lighthouse.zh.txt@@ -0,0 +1,17 @@+# 灯塔项目试点说明++本文是 OpenViking 快速开始的虚构样例,不描述真实客户。++## 试点环境++灯塔项目第一版部署在隔离网络中,运行时不能访问外网。+试点管理员需提前准备离线安装包和本地存储目录。++## 反馈收集++用户反馈先保存到本地文件,每周由试点管理员导出并交给项目负责人。+第一版不提供云端同步。云端同步是否进入后续版本尚未决定。++## 未确定事项++试点结束日期和后续版本发布时间尚未确定。diff --git a/docs/images/quickstart/llm-wiki-v1.zip b/docs/images/quickstart/llm-wiki-v1.zipnew file mode 100644index 000000000..2b0c404deBinary files /dev/null and b/docs/images/quickstart/llm-wiki-v1.zip differdiff --git a/docs/images/quickstart/overview.en.svg b/docs/images/quickstart/overview.en.svgnew file mode 100644index 000000000..54a943b45--- /dev/null+++ b/docs/images/quickstart/overview.en.svg@@ -0,0 +1 @@+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 820 290" role="img"><title>OpenViking entry points</title><defs><marker id="arrow" markerWidth="8" markerHeight="8" refX="7" refY="4" orient="auto"><path d="M0 0L8 4L0 8" fill="#64748b"/></marker></defs><rect width="820" height="290" rx="14" fill="#f8fafc"/><g font-family="system-ui, sans-serif" font-size="16" text-anchor="middle" fill="#0f172a"><rect x="24" y="20" width="155" height="45" rx="8" fill="white" stroke="#94a3b8"/><text x="101.5" y="48.5">CLI / SDK</text><rect x="24" y="80" width="155" height="45" rx="8" fill="white" stroke="#94a3b8"/><text x="101.5" y="108.5">Your agent</text><rect x="24" y="140" width="155" height="45" rx="8" fill="white" stroke="#94a3b8"/><text x="101.5" y="168.5">VikingBot</text><rect x="24" y="225" width="155" height="45" rx="8" fill="white" stroke="#94a3b8"/><text x="101.5" y="253.5">Compatible client</text><rect x="245" y="225" width="205" height="45" rx="8" fill="white" stroke="#94a3b8"/><text x="347.5" y="253.5">OpenViking Gateway</text><rect x="520" y="65" width="275" height="130" rx="12" fill="#ecfdf5" stroke="#059669"/><text x="657" y="99" font-weight="700">OpenViking</text><text x="657" y="128">Context service</text><text x="657" y="155" font-size="15">Resources · Memory</text><text x="657" y="178" font-size="15">Skills · Rules (Beta)</text></g><g stroke="#64748b" stroke-width="2" fill="none" marker-end="url(#arrow)"><path d="M179 42H215V103H520"/><path d="M179 103H520"/><path d="M179 162H215V103"/><path d="M179 247H245"/><path d="M450 247H485V165H520"/></g><g font-family="system-ui, sans-serif" font-size="13" fill="#475569"><text x="268" y="91">Import / retrieve / read</text><text x="183" y="213">Model requests</text><text x="491" y="226">Context access</text></g></svg>\ No newline at end of filediff --git a/docs/images/quickstart/overview.zh.svg b/docs/images/quickstart/overview.zh.svgnew file mode 100644index 000000000..79440659f--- /dev/null+++ b/docs/images/quickstart/overview.zh.svg@@ -0,0 +1 @@+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 820 290" role="img"><title>OpenViking 使用入口</title><defs><marker id="arrow" markerWidth="8" markerHeight="8" refX="7" refY="4" orient="auto"><path d="M0 0L8 4L0 8" fill="#64748b"/></marker></defs><rect width="820" height="290" rx="14" fill="#f8fafc"/><g font-family="system-ui, sans-serif" font-size="16" text-anchor="middle" fill="#0f172a"><rect x="24" y="20" width="155" height="45" rx="8" fill="white" stroke="#94a3b8"/><text x="101.5" y="48.5">CLI / SDK</text><rect x="24" y="80" width="155" height="45" rx="8" fill="white" stroke="#94a3b8"/><text x="101.5" y="108.5">已有 Agent</text><rect x="24" y="140" width="155" height="45" rx="8" fill="white" stroke="#94a3b8"/><text x="101.5" y="168.5">VikingBot</text><rect x="24" y="225" width="155" height="45" rx="8" fill="white" stroke="#94a3b8"/><text x="101.5" y="253.5">兼容客户端</text><rect x="245" y="225" width="205" height="45" rx="8" fill="white" stroke="#94a3b8"/><text x="347.5" y="253.5">OpenViking 网关</text><rect x="520" y="65" width="275" height="130" rx="12" fill="#ecfdf5" stroke="#059669"/><text x="657" y="99" font-weight="700">OpenViking</text><text x="657" y="128">上下文服务</text><text x="657" y="155" font-size="15">资料 · 记忆</text><text x="657" y="178" font-size="15">技能 · 规则(Beta)</text></g><g stroke="#64748b" stroke-width="2" fill="none" marker-end="url(#arrow)"><path d="M179 42H215V103H520"/><path d="M179 103H520"/><path d="M179 162H215V103"/><path d="M179 247H245"/><path d="M450 247H485V165H520"/></g><g font-family="system-ui, sans-serif" font-size="13" fill="#475569"><text x="268" y="91">导入 / 检索 / 读取</text><text x="183" y="213">模型请求</text><text x="491" y="226">上下文访问</text></g></svg>\ No newline at end of filediff --git a/docs/images/quickstart/skill-output-en-v1.txt b/docs/images/quickstart/skill-output-en-v1.txtnew file mode 100644index 000000000..de928a3a7--- /dev/null+++ b/docs/images/quickstart/skill-output-en-v1.txt@@ -0,0 +1,44 @@+OpenViking 0.5.2 / VikingBot 0.5.2 / doubao-seed-2.1-lite+Verified 2026-10-28. Real example output; wording can vary.++Input 1+Tool evidence: openviking_multi_read({"uris": ["viking://agent/skills/feedback-brief/SKILL.md"]})++# Feedback Brief++## 1. Facts+- Offline export takes 8 minutes. (Feedback A)+- The pilot administrator suggests a progress indicator. (Feedback A)+- The release date is undecided. (Feedback A)++## 2. Suggested Actions++| Action | Owner | Evidence |+|--------|-------|----------|+| Add a progress indicator to the offline export flow | Unspecified | Feedback A — pilot administrator suggests a progress indicator |++## 3. Open Questions+- Release date: Undecided (Feedback A)+- No owner is specified for implementing the suggested progress indicator (Feedback A)++---++Input 2+Tool evidence: openviking_multi_read({"uris": ["viking://agent/skills/feedback-brief/SKILL.md"]})++## Facts+- The registration template lacks an issue category field. (Feedback B)+- There are 3 duplicate reports. (Feedback B)+- No owner is specified. (Feedback B)++## Actions+| Action | Owner | Evidence |+|---|---|---|+| Suggestion: Add an issue category field to the registration template | Unspecified | Feedback B — template lacks an issue category field |+| Suggestion: Investigate and resolve the 3 duplicate reports | Unspecified | Feedback B — 3 duplicate reports |+| Suggestion: Assign an owner to the registration process | Unspecified | Feedback B — no owner is specified |++## Open questions+- Who should own the registration template and the duplicate-report cleanup? (Undecided)+- What deadline applies to adding the issue category field and resolving the duplicates? (Undecided)+- What caused the 3 duplicate reports, and should the category field help prevent them? (Undecided)diff --git a/docs/images/quickstart/skill-output-zh-v1.txt b/docs/images/quickstart/skill-output-zh-v1.txtnew file mode 100644index 000000000..db942d7ff--- /dev/null+++ b/docs/images/quickstart/skill-output-zh-v1.txt@@ -0,0 +1,50 @@+OpenViking 0.5.2 / VikingBot 0.5.2 / doubao-seed-2.1-lite+Verified 2026-10-28. Real example output; wording can vary.++Input 1+Tool evidence: openviking_multi_read({"uris": ["viking://agent/skills/feedback-brief/SKILL.md"]})++## 已知事实++- 离线导出耗时 8 分钟(反馈 A)。+- 试点管理员建议增加进度提示(反馈 A)。+- 上线日期尚未确定(反馈 A)。++## 建议行动++| 行动 | 负责人 | 证据 |+|------|--------|------|+| (建议)为离线导出功能增加进度提示 | 未指定 | 反馈 A:试点管理员建议增加进度提示 |+| (建议)评估离线导出耗时 8 分钟的性能表现 | 未指定 | 反馈 A:离线导出耗时 8 分钟 |++## 待确认++- 上线日期:尚未确定。+- 进度提示功能的具体实现范围与排期:未指定。+- 离线导出耗时 8 分钟是否在可接受范围内:未指定。++---++Input 2+Tool evidence: openviking_multi_read({"uris": ["viking://agent/skills/feedback-brief/SKILL.md"]})++# 反馈行动简报++## 1. 已知事实+- 登记模板缺少"问题分类"字段(反馈 B)。+- 存在 3 条重复反馈(反馈 B)。+- 该事项的负责人尚未指定(反馈 B)。++## 2. 建议行动++| 行动 | 负责人 | 依据 |+|------|--------|------|+| 建议:在登记模板中补充"问题分类"字段 | 未指定 | 反馈 B |+| 建议:对 3 条重复反馈进行去重合并处理 | 未指定 | 反馈 B |+| 建议:为该事项指定负责人 | 未指定 | 反馈 B |++## 3. 待确认+- 各项行动的完成期限:尚未确定。+- "问题分类"字段的具体取值范围与填写规范:尚未确定。+- 3 条重复反馈的具体内容及来源:尚未确定。+- 负责人人选:尚未确定。diff --git a/docs/images/quickstart/studio/connect-zh.jpg b/docs/images/quickstart/studio/connect-zh.jpgnew file mode 100644index 000000000..61b8a6f0dBinary files /dev/null and b/docs/images/quickstart/studio/connect-zh.jpg differdiff --git a/docs/images/quickstart/studio/files-en.jpg b/docs/images/quickstart/studio/files-en.jpgnew file mode 100644index 000000000..723a0e12eBinary files /dev/null and b/docs/images/quickstart/studio/files-en.jpg differdiff --git a/docs/images/quickstart/studio/files-zh.jpg b/docs/images/quickstart/studio/files-zh.jpgnew file mode 100644index 000000000..f2a66b3e4Binary files /dev/null and b/docs/images/quickstart/studio/files-zh.jpg differdiff --git a/docs/images/quickstart/studio/home-en.jpg b/docs/images/quickstart/studio/home-en.jpgnew file mode 100644index 000000000..5b842decdBinary files /dev/null and b/docs/images/quickstart/studio/home-en.jpg differdiff --git a/docs/images/quickstart/studio/home-zh.jpg b/docs/images/quickstart/studio/home-zh.jpgnew file mode 100644index 000000000..5be2f84deBinary files /dev/null and b/docs/images/quickstart/studio/home-zh.jpg differdiff --git a/docs/images/quickstart/studio/identity-zh.jpg b/docs/images/quickstart/studio/identity-zh.jpgnew file mode 100644index 000000000..ab3695483Binary files /dev/null and b/docs/images/quickstart/studio/identity-zh.jpg differdiff --git a/docs/images/quickstart/studio/retrieval-en.jpg b/docs/images/quickstart/studio/retrieval-en.jpgnew file mode 100644index 000000000..6787fe752Binary files /dev/null and b/docs/images/quickstart/studio/retrieval-en.jpg differdiff --git a/docs/images/quickstart/studio/retrieval-zh.jpg b/docs/images/quickstart/studio/retrieval-zh.jpgnew file mode 100644index 000000000..c486e42d1Binary files /dev/null and b/docs/images/quickstart/studio/retrieval-zh.jpg differdiff --git a/docs/images/quickstart/studio/task-en.jpg b/docs/images/quickstart/studio/task-en.jpgnew file mode 100644index 000000000..0b1a6bc5cBinary files /dev/null and b/docs/images/quickstart/studio/task-en.jpg differdiff --git a/docs/images/quickstart/studio/task-zh.jpg b/docs/images/quickstart/studio/task-zh.jpgnew file mode 100644index 000000000..77c507306Binary files /dev/null and b/docs/images/quickstart/studio/task-zh.jpg differdiff --git a/docs/images/quickstart/verification-v1.txt b/docs/images/quickstart/verification-v1.txtnew file mode 100644index 000000000..d3d01b6ba--- /dev/null+++ b/docs/images/quickstart/verification-v1.txt@@ -0,0 +1,27 @@+Onboarding sample verification / 入门样例验证+Date / 日期: 2026-10-28+Samples / 样例: v1 (fictional / 虚构)+Server, CLI, VikingBot: OpenViking 0.5.2, ov 0.5.2, VikingBot 0.5.2+Mode: isolated localhost service and storage; a separate API Key account for OVPack.+模型 / Models: volcengine doubao-seed-2.1-lite (Agent/VLM), doubao-embedding-vision (1024-dimensional embedding), Agent Plan endpoint.++Verified / 已实测:+- Resource: Chinese and English four-file packs imported. Agent semantic search, source reads and answers checked for direct, combined and unknown facts.+- Memory: Chinese Cape session explicitly committed; memory_diff and memory body checked. A new VikingBot session searched/read the memory and used its conventions. Unrelated arithmetic answered 42 without using Cape background.+- Skill: two inputs in each language; actual SKILL.md read traces and both generated briefs checked. Read/text-only tool scope.+- VikingBot: initial task and follow-up in one session preserved the task statuses.+- Gateway: two chat/completions requests, capture, idle submission, completed extraction, memory_diff and new-session recall checked. Public Python client's recall phase executed separately.+- Compile: Chinese and English source packs compiled into index.md and entity/lighthouse.md; actual body and source URIs checked. Chinese compile completed in about 61 seconds.+- Snapshot: two explicit commits, old content, diff, dry-run, restore, new commit and completed reindex task checked. Scope: onboarding-versions-v1 only; 1 file written, 0 deleted.+- OVPack: separate test account; export then import under a new parent; all 4 source texts and root abstract/overview matched; 14 manifest file checksums/sizes matched; scoped retrieval succeeded; duplicate import was rejected with default conflict policy.++Observed conditions / 实测条件:+- English resource embedding initially returned UnsupportedModel at the provider. Rebuilding only vectors later succeeded with the same configured model; subsequent retrieval worked.+- OVPack on a dev-mode 0.5.2 service returned 403. The API Key account path passed and is now the tutorial prerequisite.+- Gateway recalled another fictional project's memory as well as the requested project. The answer used the requested conventions but included unnecessary cross-project explanation. Evaluate relevance as well as successful recall; use a fresh identity or isolated storage for repeat trials.+- Asynchronous observation windows in tutorials are initial check periods, not completion-time guarantees.++Limits / 未验证项:+- No cloud/enterprise environment was used. No production site was published.+- Memory, Bot conversation, Gateway and data-management execution used Chinese examples; their English tutorial text was synchronized and checked, not every translated command was replayed.+- Human independent-use review and before/after usability comparison are pending.diff --git a/docs/images/quickstart/wiki-output-en-v1.txt b/docs/images/quickstart/wiki-output-en-v1.txtnew file mode 100644index 000000000..605a36c7b--- /dev/null+++ b/docs/images/quickstart/wiki-output-en-v1.txt@@ -0,0 +1,39 @@+OpenViking 0.5.2 / VikingBot 0.5.2 / doubao-seed-2.1-lite+Verified 2026-10-28. Real example output; wording can vary.++---+type: entity+title: Lighthouse+description: The fictional v1 pilot project running on an isolated network without internet access, including its offline installation, local feedback workflow, and undecided items.+tags: [lighthouse, pilot, isolated-network]+---++# Lighthouse++Lighthouse is a fictional tutorial sample (version 1) that runs as a pilot on an isolated network without internet access. It is the central project of this Wiki: its offline setup, weekly feedback loop, and preparation steps are documented below, while several dates and scope items remain unknown or undecided in the sources.++## Identity and setup++- Fictional tutorial sample v1; the first version runs in a pilot on an isolated network without internet access ([Lighthouse project](viking://resources/onboarding-en-v1/project/project.md)).+- The pilot administrator prepares an offline installation package and a local storage directory ([Lighthouse project](viking://resources/onboarding-en-v1/project/project.md)).++## Feedback workflow++- User feedback is saved to local files; version one has no cloud synchronization, and support for it in a later version is undecided ([Feedback collection](viking://resources/onboarding-en-v1/feedback/feedback.md)).+- Every Friday, the pilot administrator exports the feedback and gives it to the project owner ([Feedback collection](viking://resources/onboarding-en-v1/feedback/feedback.md)).++## Preparation and undecided items++- The project owner confirmed that a feedback registration template must be prepared before the pilot, and the administrator will rehearse an offline export once ([Pilot preparation meeting](viking://resources/onboarding-en-v1/meeting/meeting.md)).+- The pilot end date, budget, and next release date are undecided ([Pilot preparation meeting](viking://resources/onboarding-en-v1/meeting/meeting.md)). No start date is stated in the sources; it is unknown.++## Scope limits++- The sample covers only the first pilot version. The sources provide no production capacity, security certification conclusions, or performance test results ([Scope limits](viking://resources/onboarding-en-v1/limits/limits.md)).++## Sources++- [Lighthouse project](viking://resources/onboarding-en-v1/project/project.md)+- [Feedback collection](viking://resources/onboarding-en-v1/feedback/feedback.md)+- [Pilot preparation meeting](viking://resources/onboarding-en-v1/meeting/meeting.md)+- [Scope limits](viking://resources/onboarding-en-v1/limits/limits.md)diff --git a/docs/images/quickstart/wiki-output-zh-v1.txt b/docs/images/quickstart/wiki-output-zh-v1.txtnew file mode 100644index 000000000..b51ba268a--- /dev/null+++ b/docs/images/quickstart/wiki-output-zh-v1.txt@@ -0,0 +1,35 @@+OpenViking 0.5.2 / VikingBot 0.5.2 / doubao-seed-2.1-lite+Verified 2026-10-28. Real example output; wording can vary.++---+type: entity+title: 灯塔项目+description: 灯塔项目第一版是在隔离网络中运行的反馈试点,反馈以本地文件形式每周五离线导出。+tags: [灯塔项目, 隔离网络, 反馈试点, v1]+---++# 灯塔项目++灯塔项目是一个虚构教学样例(v1),其第一版用于隔离网络中的反馈试点,运行时无法访问外网。试点的核心机制是:用户反馈保存为本地文件,由试点管理员每周五导出并交给项目负责人;第一版不支持云端同步,是否在后续版本提供尚未决定。++## 试点准备++- 试点管理员需提前准备离线安装包和本地存储目录,以保证在无法访问外网的环境中运行。[灯塔项目](viking://resources/onboarding-zh-v1/project/project.md)+- 试点开始前要准备反馈登记模板,并安排管理员演练一次离线导出(项目负责人在试点准备会议上确认)。[试点准备会议](viking://resources/onboarding-zh-v1/meeting/meeting.md)++## 反馈流程++- 用户反馈保存为本地文件;试点管理员每周五导出反馈并交给项目负责人。[反馈收集](viking://resources/onboarding-zh-v1/feedback/feedback.md)+- 第一版不支持云端同步;是否在后续版本提供云端同步尚未决定。[反馈收集](viking://resources/onboarding-zh-v1/feedback/feedback.md)++## 使用边界与未知事项++- 本样例只覆盖第一版试点,资料未给出生产部署容量、安全认证结论或性能测试结果。[使用边界](viking://resources/onboarding-zh-v1/limits/limits.md)+- 试点结束日期、预算和下一版本发布时间尚未确定;资料中也未给出试点开始日期。[试点准备会议](viking://resources/onboarding-zh-v1/meeting/meeting.md)++## 来源++- [灯塔项目](viking://resources/onboarding-zh-v1/project/project.md)+- [反馈收集](viking://resources/onboarding-zh-v1/feedback/feedback.md)+- [试点准备会议](viking://resources/onboarding-zh-v1/meeting/meeting.md)+- [使用边界](viking://resources/onboarding-zh-v1/limits/limits.md)diff --git a/docs/zh/agent-integrations/02-claude-code.md b/docs/zh/agent-integrations/02-claude-code.mdindex 74c303d0e..cb2f138cb 100644--- a/docs/zh/agent-integrations/02-claude-code.md+++ b/docs/zh/agent-integrations/02-claude-code.md@@ -45,7 +45,7 @@ curl -fsSL https://openviking.ai/install | bash</details>-安装完成后,在 Claude Code 中新开一个会话,让它按 https://docs.openviking.net/agents/zh/onboarding.md 执行。它会检查连接,并带你完成首次使用,详见[一条提示词接入 Agent](../getting-started/07-agent-onboarding.md)。+安装完成后,在 Claude Code 中新开一个会话,让它按 https://docs.openviking.net/agents/zh/onboarding.md 执行。它会检查连接,并带你完成首次使用,详见[一键接入](../getting-started/07-agent-onboarding.md)。## 验证diff --git a/docs/zh/agent-integrations/04-codex.md b/docs/zh/agent-integrations/04-codex.mdindex 6c20f04cb..530c6b228 100644--- a/docs/zh/agent-integrations/04-codex.md+++ b/docs/zh/agent-integrations/04-codex.md@@ -57,7 +57,7 @@ Hook 关闭时,MCP 工具仍可能正常使用。自动召回需要 `UserPromp</details>-安装完成后,在 Codex 中新开一个会话,让它按 https://docs.openviking.net/agents/zh/onboarding.md 执行。它会检查连接,并带你完成首次使用,详见[一条提示词接入 Agent](../getting-started/07-agent-onboarding.md)。+安装完成后,在 Codex 中新开一个会话,让它按 https://docs.openviking.net/agents/zh/onboarding.md 执行。它会检查连接,并带你完成首次使用,详见[一键接入](../getting-started/07-agent-onboarding.md)。## 验证diff --git a/docs/zh/agent-integrations/08-community-plugins.md b/docs/zh/agent-integrations/08-community-plugins.mdindex 5e3ab8b0c..3cc5eeab7 100644--- a/docs/zh/agent-integrations/08-community-plugins.md+++ b/docs/zh/agent-integrations/08-community-plugins.md@@ -40,7 +40,7 @@ curl -fsSL https://openviking.ai/install | bash实现细节与当前已验证的 ZCode 假设见插件目录中的 [README](https://github.com/volcengine/OpenViking/tree/main/examples/agent-hook-plugin) 和 [DESIGN.md](https://github.com/volcengine/OpenViking/blob/main/examples/agent-hook-plugin/DESIGN.md)。-安装完成后,在 ZCode 中新开一个会话,让它按 https://docs.openviking.net/agents/zh/onboarding.md 执行。它会检查连接,并带你完成首次使用,详见[一条提示词接入 Agent](../getting-started/07-agent-onboarding.md)。+安装完成后,在 ZCode 中新开一个会话,让它按 https://docs.openviking.net/agents/zh/onboarding.md 执行。它会检查连接,并带你完成首次使用,详见[一键接入](../getting-started/07-agent-onboarding.md)。## Kimi Code 记忆集成@@ -74,7 +74,7 @@ curl -fsSL https://openviking.ai/install | bash -s -- --uninstall --yes --harnes已验证的宿主契约和版本见[`hosts/kimicode/DESIGN.md`](https://github.com/volcengine/OpenViking/blob/main/examples/agent-hook-plugin/hosts/kimicode/DESIGN.md)。-安装完成后,在 Kimi Code 中新开一个会话,让它按 https://docs.openviking.net/agents/zh/onboarding.md 执行。它会检查连接,并带你完成首次使用,详见[一条提示词接入 Agent](../getting-started/07-agent-onboarding.md)。+安装完成后,在 Kimi Code 中新开一个会话,让它按 https://docs.openviking.net/agents/zh/onboarding.md 执行。它会检查连接,并带你完成首次使用,详见[一键接入](../getting-started/07-agent-onboarding.md)。## CodeBuddy Code 记忆集成diff --git a/docs/zh/agent-integrations/10-opencode.md b/docs/zh/agent-integrations/10-opencode.mdindex 8243f02c8..24f5c3bae 100644--- a/docs/zh/agent-integrations/10-opencode.md+++ b/docs/zh/agent-integrations/10-opencode.md@@ -19,7 +19,7 @@ curl -fsSL https://openviking.ai/install | bash安装器会把插件作为本地文件插件复制到 `~/.config/opencode/plugins/`,把 `openviking` MCP server 条目写进 `~/.config/opencode/opencode.json`,并配置 `~/.openviking/ovcli.conf`。-安装完成后,在 OpenCode 中新开一个会话,让它按 https://docs.openviking.net/agents/zh/onboarding.md 执行。它会检查连接,并带你完成首次使用,详见[一条提示词接入 Agent](../getting-started/07-agent-onboarding.md)。+安装完成后,在 OpenCode 中新开一个会话,让它按 https://docs.openviking.net/agents/zh/onboarding.md 执行。它会检查连接,并带你完成首次使用,详见[一键接入](../getting-started/07-agent-onboarding.md)。### 手动 npm 安装diff --git a/docs/zh/agent-integrations/11-pi.md b/docs/zh/agent-integrations/11-pi.mdindex 85454ed52..82254166c 100644--- a/docs/zh/agent-integrations/11-pi.md+++ b/docs/zh/agent-integrations/11-pi.md@@ -30,7 +30,7 @@ npm ci --prefix ~/.pi/agent/extensions/openviking --omit=dev --ignore-scripts扩展从 `shared/` 目录 import 共享模块,这个目录不在 git 里,由 `sync.mjs` 生成,所以复制前必须先运行它。之后 `git pull` 更新时,也要先重新运行 `sync.mjs` 再复制。-安装完成后,在 pi 中新开一个会话,让它按 https://docs.openviking.net/agents/zh/onboarding.md 执行。它会检查连接,并带你完成首次使用,详见[一条提示词接入 Agent](../getting-started/07-agent-onboarding.md)。+安装完成后,在 pi 中新开一个会话,让它按 https://docs.openviking.net/agents/zh/onboarding.md 执行。它会检查连接,并带你完成首次使用,详见[一键接入](../getting-started/07-agent-onboarding.md)。## 工作方式diff --git a/docs/zh/agent-integrations/12-cursor.md b/docs/zh/agent-integrations/12-cursor.mdindex 255dbe665..84b818705 100644--- a/docs/zh/agent-integrations/12-cursor.md+++ b/docs/zh/agent-integrations/12-cursor.md@@ -15,7 +15,7 @@ curl -fsSL https://openviking.ai/install | bash安装完成后完全退出并重新启动 Cursor。-安装完成后,在 Cursor 中新开一个会话,让它按 https://docs.openviking.net/agents/zh/onboarding.md 执行。它会检查连接,并带你完成首次使用,详见[一条提示词接入 Agent](../getting-started/07-agent-onboarding.md)。+安装完成后,在 Cursor 中新开一个会话,让它按 https://docs.openviking.net/agents/zh/onboarding.md 执行。它会检查连接,并带你完成首次使用,详见[一键接入](../getting-started/07-agent-onboarding.md)。## 安装内容diff --git a/docs/zh/agent-integrations/13-trae.md b/docs/zh/agent-integrations/13-trae.mdindex cfdf4ab18..85a16cb7c 100644--- a/docs/zh/agent-integrations/13-trae.md+++ b/docs/zh/agent-integrations/13-trae.md@@ -33,7 +33,7 @@ Hooks can run outside the sandbox after you trust them.TRAE 和 TRAE CN 使用安装后的 `hooks.json`,不需要审阅 hook,安装后重启对应客户端。-安装完成后,在 TRAE 中新开一个会话,让它按 https://docs.openviking.net/agents/zh/onboarding.md 执行。它会检查连接,并带你完成首次使用,详见[一条提示词接入 Agent](../getting-started/07-agent-onboarding.md)。+安装完成后,在 TRAE 中新开一个会话,让它按 https://docs.openviking.net/agents/zh/onboarding.md 执行。它会检查连接,并带你完成首次使用,详见[一键接入](../getting-started/07-agent-onboarding.md)。## 安装内容diff --git a/docs/zh/agent-integrations/17-dsh.md b/docs/zh/agent-integrations/17-dsh.mdindex ed1602c4c..6fe5414a8 100644--- a/docs/zh/agent-integrations/17-dsh.md+++ b/docs/zh/agent-integrations/17-dsh.md@@ -44,7 +44,7 @@ curl -fsSL https://openviking.ai/install | bash</details>-安装完成后,在 DSH 中新开一个会话,让它按 https://docs.openviking.net/agents/zh/onboarding.md 执行。它会检查连接,并带你完成首次使用,详见[一条提示词接入 Agent](../getting-started/07-agent-onboarding.md)。+安装完成后,在 DSH 中新开一个会话,让它按 https://docs.openviking.net/agents/zh/onboarding.md 执行。它会检查连接,并带你完成首次使用,详见[一键接入](../getting-started/07-agent-onboarding.md)。## 验证diff --git a/docs/zh/getting-started/01-introduction.md b/docs/zh/getting-started/01-introduction.mdindex c7c2fd8a2..b34626659 100644--- a/docs/zh/getting-started/01-introduction.md+++ b/docs/zh/getting-started/01-introduction.md@@ -1,46 +1,62 @@-# OpenViking 能做什么+# 功能概览-OpenViking 是面向 AI Agent 的开源上下文数据库。它把资料、记忆和技能组织在同一个虚拟文件系统里,让 Agent 能找到相关内容,并在后续任务中继续使用。+OpenViking 是面向 AI Agent 的上下文数据库,将资料、记忆、技能和规则组织成可浏览、可检索的文件。它为 Agent 提供上下文;Agent 读取这些内容后,再生成回答或执行任务。-如果你正在解决“资料散落不好找”“每次会话都要重述背景”或“已有经验难以复用”,可以从下面选一条路径。+第一次使用,先完成[快速开始](02-quickstart.md),看到一份能够核对来源的回答。之后按下面的任务选择体验,不必按顺序读完全部文档。-## 从你的任务开始+## 从任务出发-| 你想做到什么 | 先做什么 | 再往哪里走 |+| 你的任务 | OpenViking 提供什么 | 从哪里开始 || --- | --- | --- |-| 让 Agent 找到项目资料中的依据 | [导入并检索第一份文档](02-quickstart.md) | 换成你的资料,[验证实际效果](06-evaluate.md) |-| 给正在使用的 Agent 加入跨会话记忆 | [选择 Agent 接入方式](../agent-integrations/01-overview.md) | 按插件说明安装,再[用两次会话检查记忆](06-evaluate.md#用两次会话检查记忆) |-| 在自己的应用中使用上下文 | [应用开发路径](../workflows/01-overview.md) | 选资源、会话或技能流程,再查对应 API |-| 将资料整理成 Wiki、图谱或日报 | [上下文编译概览](../context-compilation/01-overview.md) | 选一种产物,用熟悉的来源核对结果 |+| 根据项目资料回答问题 | 导入资料、查找相关内容、读取原文 | [资料检索](08-resources.md) |+| 新会话继续使用已有背景 | 保存会话并提取记忆,在相关任务中召回 | [记忆使用](09-memory.md) |+| 复用一套工作方法 | 存储与检索 Skill,由 Agent 读取并应用 | [技能使用](10-skills.md) |+| 按规范检查任务与行动 | 编译强约束,按当前任务召回规则,供 Agent 核验 | [规则(Beta)](16-rules.md) |+| 把资料整理成可阅读的知识 | 按 Skill 编译为 Wiki 等产物 | [上下文编译](13-compile.md) |-**还没决定从哪条开始?** 先完成[第一次导入与检索](02-quickstart.md)。这条路径用一份小文档走完连接、导入、检索和读取原文,不要求先读完原理。+<a id="三类上下文"></a>-已有服务地址和 API Key,可直接[安装与使用 CLI](05-cli-setup.md)。需要自己提供服务,查看[部署路径](../guides/00-overview.md);想使用 OpenViking 自带的 Agent,查看[VikingBot 安装与配置](../guides/17-vikingbot.md)。+## 上下文类型-## 怎样把第一次体验用起来+| 类型 | 保存什么 | 用户怎样确认它有用 |+| --- | --- | --- |+| **资料(Resource)** | 文档、网页、代码等外部资料 | 回答中的关键结论能回到来源核对 |+| **记忆(Memory)** | 从会话提取的背景、偏好与经验 | 新会话不必重复交代,Agent 的新任务确实用到了背景 |+| **技能(Skill)** | 工作流程的指令与配套文件 | Agent 读取技能后,产物符合该流程的要求 |+| **规则(Rule,Beta)** | 特定条件下必须遵守的要求,包括义务、禁止项和例外 | Agent 根据任务证据核对适用规则,并据此调整行动或回答 |++这些内容通过 `viking://` URI 定位。知道位置时可以直接读取;不知道位置时先检索,再打开原文。目录摘要和概览的生成取决于处理方式与配置,可帮助 Agent 按需加载内容。-1. **取得第一个结果。** 不只确认服务健康,还要能读到导入的原文。-2. **换成自己的任务。** 用你知道答案的资料或跨会话背景,检查命中内容和实际使用情况,见[用你的任务验证效果](06-evaluate.md)。-3. **接进日常工作。** 选择一个 Agent、应用或编译流程继续使用。需要多人共享时,再完善部署和访问控制。+**规则:** 例如,“仓库声明开源时,必须提供可定位的许可证文本”。你可以将规范中的强约束主动编译为 Rule,再按具体任务召回。OpenViking 提供规则及其适用条件,Agent 结合当前证据核验是否满足要求。规则目前处于 Beta,概念与使用方式见[规则介绍](../concepts/17-rule-scenarios.md)。-出现问题时,从[观测与排障](../guides/05-observability.md)区分连接、处理与检索问题。+## 选择使用入口-## 上下文如何组织+-| 上下文 | 用来存什么 |+| 入口 | 适合怎样使用 || --- | --- |-| 资源 | 文档、代码仓库等外部资料 |-| 记忆 | 从会话提取的偏好、事实与经验 |-| 技能 | 可复用工作流程的指令与配套文件 |+| **CLI** | 在终端中浏览、导入、检索与读取;通过 `ov chat` 使用已启用的 VikingBot。见 [CLI 入门](05-cli-setup.md) |+| **已有 Agent** | 为日常工具加入上下文与记忆。各插件的自动捕获、提交和召回能力不同,安装后还需验证新会话行为 |+| **VikingBot** | 使用 OpenViking 内置 Agent 完成问答与工具任务;[快速开始](02-quickstart.md)使用这条路线 |+| **网关** | 将兼容客户端的模型请求接入上下文与记忆流程;可通过保存、提取和召回结果验证接入效果 |+| **SDK / HTTP** | 在自己的应用中控制导入、检索、会话和数据管理流程 |++OpenViking 负责管理和提供上下文,CLI、插件、网关和 Agent 的行为各有边界。深度接入时再查看[Agent 集成](../agent-integrations/01-overview.md)、[网关接入](12-gateway.md)或 [SDK 与 HTTP](../api/01-overview.md)。-内容通过 `viking://` URI 定位,可以按路径浏览,也可以先检索再读取。[上下文类型](../concepts/02-context-types.md)和 [Viking URI](../concepts/04-viking-uri.md)解释对象与空间的边界。+## 体验技能与知识整理-## 按层读取内容+**技能:** 选择一个有明确产物的工作流程,安装 Skill,确认 Agent 能发现并读取它,再提交一项任务并检查结果。OpenViking 负责存储和检索技能,Agent 负责激活技能、管理工具权限并执行任务。跟随[技能使用](10-skills.md)完成两组输入的体验。-OpenViking 可在语义处理时生成目录摘要(L0)和概览(L1),再按需读取原文(L2)。L0、L1 是目录级附属文件,是否生成取决于处理状态和配置;它们不是每个文件都固定具备的一对摘要。详见[上下文层级](../concepts/03-context-layers.md)。+**整理知识:** 准备来源资料,使用 Wiki Skill 执行编译,等待完成后打开一篇正文,核对来源和遗漏。使用 Skill 编译需要已配置的 Compile Runtime,编译结果可结合原始资料核对。可继续[上下文编译](13-compile.md),生成并阅读一篇 Wiki。-## 从会话生成记忆+## 下一步-应用记录消息,提交会话后按策略异步提取记忆。插件可以自动执行其中部分步骤,支持范围见[集成能力对照](../agent-integrations/16-capability-reference.md)。生成了哪些记忆、后续是否召回,需要检查实际结果。+已经得到第一个结果,就用[效果评估](06-evaluate.md)验证自己的任务。还没有服务地址时,先看[部署模式](07-options.md)。-想系统理解这套流程,从[概念与原理](../concepts/00-overview.md)开始;想直接完成任务,用左侧“接入你的工作”选择下一步。+<!-- Keep incoming links to the previous headings working. -->+<a id="openviking-能做什么"></a>+<a id="从你的任务开始"></a>+<a id="怎样把第一次体验用起来"></a>+<a id="上下文如何组织"></a>+<a id="按层读取内容"></a>+<a id="从会话生成记忆"></a>diff --git a/docs/zh/getting-started/02-quickstart.md b/docs/zh/getting-started/02-quickstart.mdindex 83b8e07e5..d5fad9f4f 100644--- a/docs/zh/getting-started/02-quickstart.md+++ b/docs/zh/getting-started/02-quickstart.md@@ -1,106 +1,243 @@-# 导入并检索第一份文档+<a id="导入并检索第一份文档"></a>-OpenViking 以服务端运行。用独立的 `ov` CLI 连接服务,导入一份小文档,再检索其中的内容。使用托管服务或他人部署的服务时,只需安装 CLI。+# 快速开始-## 1. 选择服务+当你希望 AI Agent 根据项目资料回答问题时,需要先让它找到相关内容,再读取原文。OpenViking 是面向 Agent 的上下文数据库,负责保存和检索这些资料,让 Agent 能够根据来源生成回答。-**已有服务地址?** 准备好 URL 和 API Key,直接跳到第 2 步。服务采用 API Key 认证时,数据访问使用 user/admin key,root key 用于管理操作。详见[认证](../guides/04-authentication.md)。+接下来,你会导入一份虚构的“灯塔项目”说明,让 Agent 回答反馈收集的问题,并打开它引用的原文核对结果。你可以使用火山引擎云服务,也可以在本机运行 OpenViking:两条路径都会完成 **导入资料 → 检索与读取 → 生成回答 → 核对来源**。-还没有服务时,选择以下一种方式:+## 准备工作-### 火山引擎托管服务+先选择运行方式,再安装对应的工具:-打开 [OpenViking 控制台](https://console.volcengine.com/vikingdb/openviking/region:openviking+cn-beijing?utm_source=opensource_docs&utm_medium=referral&utm_campaign=getting-started_02-quickstart),从**用户管理 → API Key** 获取密钥。服务地址为:+| 运行方式 | 适合的情况 | 需要准备 |+| --- | --- | --- |+| **火山引擎云服务** | 希望使用托管服务,并在已有 Agent 中提问 | Node.js/npm、火山引擎账号,以及能在本机执行终端命令的 Agent |+| **本地服务** | 希望在自己的电脑上运行,并直接使用内置 Agent VikingBot | Node.js/npm、uv、Python,以及模型访问凭据 |-```text-https://api.vikingdb.cn-beijing.volces.com/openviking+### 安装 Node.js++两条路径都通过 `ov` CLI 操作资料。打开 [Node.js 下载页](https://nodejs.org/en/download),选择与你的系统匹配的 **LTS** 版本,按页面提供的安装程序或命令完成安装;npm 会随 Node.js 一同安装。++安装后重新打开终端,确认两个命令都能输出版本号:++```bash+node --version+npm --version+```++使用云服务时,可以直接进入[开通或启动服务](#开通或启动服务)。++### 准备本地运行环境++本地服务使用 uv 安装 OpenViking,并使用 Python 运行。下面以 macOS / Linux 终端为例;其他系统的安装方式可查看 [uv 安装指南](https://docs.astral.sh/uv/getting-started/installation/)和[服务端部署](../guides/03-deployment.md)。++先安装 uv:++```bash+curl -LsSf https://astral.sh/uv/install.sh | sh+```++重新打开终端,确认 uv 可用:++```bash+uv --version+```++再用 uv 安装 Python 3.13,供后续服务使用:++```bash+uv python install 3.13```-无需安装服务端,也无需在本机配置模型。[产品介绍](https://www.volcengine.com/product/openviking-service?utm_source=opensource_docs&utm_medium=referral&utm_campaign=getting-started_02-quickstart)和[服务文档](https://docs.volcengine.com/docs/84313/2374478)说明托管服务的使用方式与额度。继续第 2 步。+已有 Python 3.13 时可直接使用。其他安装方式见 [Python 下载页](https://www.python.org/downloads/)和 [uv 的 Python 管理指南](https://docs.astral.sh/uv/guides/install-python/)。++最后,准备两个模型的调用信息:**Embedding 模型**用于资料向量化和检索,**支持工具调用的 VLM**用于内容理解和 VikingBot 回答。每个模型需要模型名、调用端点及 API Key;可按[火山引擎模型开通指南](../guides/02-volcengine-purchase-guide.md)取得这些信息。使用 Agent Plan 时,选择套餐支持的模型与端点。导入资料和生成回答会产生模型调用,按所选服务计费。++<a id="_1-启动服务"></a>++<a id="_1-选择服务"></a>++<a id="_1-开通或启动服务"></a>++## 开通或启动服务++选择下面的一条路径,完成后继续[连接 CLI](#连接-cli)。++<a id="火山引擎托管服务"></a>-### 自建服务+### 火山引擎云服务++云服务负责运行 OpenViking 和处理资料,你的电脑只需安装客户端。++1. 打开 [OpenViking 控制台](https://console.volcengine.com/vikingdb/openviking/region:openviking+cn-beijing),登录火山引擎账号,并按控制台提示开通服务。套餐与额度可在[服务说明](https://docs.volcengine.com/docs/84313/2374478)中查看。+2. 在控制台取得用于访问 OpenViking 的 **API Key**,供下一步配置 CLI 使用。+3. 准备一个能在本机执行终端命令的 Agent。在“提问并核对”中,通过它调用 `ov` 检索云端资料并生成回答;接入方式可查看 [CLI 入门](05-cli-setup.md)。++取得 API Key 后,继续[连接 CLI](#连接-cli)。++<a id="自建服务"></a>++### 本地服务++先安装 OpenViking 和 VikingBot,让本机同时具备资料管理和问答能力:++```bash+uv tool install --python 3.13 "openviking[bot]" --upgrade+```-在运行服务端的机器上[安装 uv](https://docs.astral.sh/uv/getting-started/installation/),再安装 OpenViking:+接着运行初始化向导。选择本机访问,并填写准备好的 Embedding 和 VLM 模型信息;VikingBot 默认使用这里配置的 VLM。```bash-uv tool install openviking --upgradeopenviking-server init+```++配置完成后,检查模型和服务配置。若检查报告错误,按提示修正对应项目后再次检查:++```bashopenviking-server doctor-openviking-server```-配置向导用于设置服务端模型并写入 `~/.openviking/ov.conf`。准备好 Embedding 模型和 VLM 的访问凭据——推荐使用火山引擎(豆包)模型,购买和开通见[火山引擎购买指南](../guides/02-volcengine-purchase-guide.md)——再用 `doctor` 检查配置。保持服务运行,另开终端完成后续步骤。+检查通过后,启动服务和 VikingBot。保持这个终端运行,后续操作在另一个终端中进行。-服务是否在运行,用一条 curl 即可确认,不依赖任何客户端:+```bash+openviking-server --with-bot+```++在新终端中确认资料服务和 Agent 都已就绪:```bash-curl http://127.0.0.1:1933/health-# {"status":"ok","healthy":true,...}+curl -f http://127.0.0.1:1933/health+curl -f http://127.0.0.1:1933/bot/v1/health```-本地地址为 `http://127.0.0.1:1933`,默认本地配置不需要 API Key;Web Studio 位于 `/studio`。Docker、持久化存储和远程访问配置见[部署](../guides/03-deployment.md)、[模型配置](../guides/01-configuration.md)和[认证](../guides/04-authentication.md)。+分别看到 `healthy: true` 和 Bot 的 `status: healthy` 后,继续连接 CLI。++<a id="_2-安装并连接-cli"></a>++<a id="_2-连接-cli"></a>-## 2. 安装并连接 CLI+## 连接 CLI-在客户端机器上安装好 Node.js 和 npm 后,运行:+安装 CLI,以便在终端中导入、检索和读取资料。已有 `ov` 时可以跳过安装命令。```bashnpm install -g @openviking/cli+```++将界面语言设为中文,再打开连接向导:++```bashov language zh-CNov config```-在交互配置中,火山托管服务选择 **OpenViking Service**,自建服务选择 **自定义(Custom)**。填写 API Key,自建服务还需填写 URL。默认本地服务的密钥留空。保存并激活配置。+在向导中添加连接,按所选路径填写,然后保存并设为当前配置:++| 运行方式 | 连接类型 | 填写内容 |+| --- | --- | --- |+| 火山引擎云服务 | **OpenViking Service** | 按向导使用服务地址,输入控制台取得的 API Key |+| 本地服务 | **自定义(Custom)** | URL 填写 `http://127.0.0.1:1933`;默认本机模式的密钥留空 |-CLI 将当前连接保存到 `~/.openviking/ovcli.conf`,它与服务端的 `ov.conf` 是两个文件。多服务切换和让 Agent 配置见 [CLI 配置](05-cli-setup.md)。+如果本地服务已有认证配置,使用对应的 User/Admin Key;配置方式见[身份认证](../guides/04-authentication.md)。-检查连接:+检查当前连接,成功后即可开始导入:```bashov health```-这一步确认服务能响应;下面的导入还会验证模型处理和数据访问。+<a id="_3-导入文档"></a>-## 3. 导入文档+<a id="_3-导入样例"></a>-本例导入一条真实的团队信息:OpenViking 每周发布由哪四位 GitHub 用户轮流负责。在当前目录创建 `ov-release-rotation.md`,内容如下:+## 导入样例-```markdown-# OpenViking 发布轮值+<a href="/quickstart/lighthouse.zh.txt" download="lighthouse.zh.md">下载灯塔项目资料</a>,保存为 `lighthouse.zh.md`,然后在终端中进入该文件所在目录。资料包含试点的网络条件、反馈收集方式和未确定事项。-OpenViking 每周五发布一个新版本。-发布负责人按顺序轮换:qin-ctx、zhoujh01、ZaynJarvis、t0saki。+将它导入独立的演示目录,并通过 `--wait` 等待处理完成。再次体验时,可将 `lighthouse-demo` 换成一个新的目录名,并在后续命令中使用相同名称。++```bash+ov add-resource ./lighthouse.zh.md --to viking://resources/lighthouse-demo --wait```-将它导入新的资源目录:+处理成功后,查看导入的文件:```bash-ov add-resource ./ov-release-rotation.md --to viking://resources/ov-release-rotation --wait+ov tree viking://resources/lighthouse-demo```-CLI 会自动上传本地文件。`--wait` 等待处理完成,命令成功后再继续。若省略该参数,保存返回的 `task_id`,用 `ov task status <task_id>` 查询到 `completed` 后再使用结果。详见[后台任务](../api/17-tasks.md)。+如果等待超时,使用返回的任务 ID 执行 `ov task status <task_id>` 查看进度。任务完成后继续;任务失败时,先根据错误信息修正模型或连接配置,再重试。任务状态说明见[任务管理](../api/17-tasks.md)。++<a id="_4-浏览与检索"></a>++<a id="_4-提问并核对"></a>-## 4. 浏览与检索+## 提问并核对++### 检索并读取资料++先查找与反馈收集相关的内容:```bash-ov tree viking://resources/ov-release-rotation-ov overview viking://resources/ov-release-rotation-ov find "谁负责 OpenViking 的每周发布?" --uri viking://resources/ov-release-rotation+ov find "灯塔项目第一版怎样收集用户反馈?" --uri viking://resources/lighthouse-demo```-`tree` 列出导入后的结构,`overview` 读取生成的概览,`find` 返回相关上下文的 URI 和分数。这个问题的答案就在导入的文件中,所以该文件排在结果第一位。读取某条命中时,把返回的 URI 传给 `ov read`:+结果中会包含匹配内容的 URI。复制其中的来源文件 URI,替换下面的占位值,打开原文:```bash-ov read "<returned-file-uri>"+ov read "<来源文件 URI>"```-将 `<returned-file-uri>` 替换为结果中的文件 URI,不保留尖括号。更多资源类型和检索参数见[资源管理](../api/02-resources.md)与[检索](../api/06-retrieval.md)。+能读到“试点环境”和“反馈收集”等内容后,就可以让 Agent 使用这些资料回答问题。++### 让 Agent 生成回答++**使用云服务:** 在能够执行本机终端命令的 Agent 中发送下面的任务。让它使用刚才配置好的 CLI 连接;如果 Agent 运行在另一台机器或独立容器中,先在那里完成[CLI 连接配置](#连接-cli)。++```text+请使用本机已配置的 ov CLI,根据 OpenViking 中的项目资料回答问题。+先执行 ov health 确认连接,再执行:+ov find "灯塔项目第一版怎样收集用户反馈?" --uri viking://resources/lighthouse-demo+用 ov read 读取检索结果中的相关原文,然后回答:+灯塔项目第一版应怎样收集用户反馈,需要提前准备什么?+请只依据该目录中的资料,为关键结论列出来源文件的完整 viking:// URI,+并明确指出资料未说明的内容。+```++**使用本地服务:** 通过 `ov chat` 把同一个问题交给已启动的 VikingBot,它会调用检索和读取工具:++```bash+ov chat -m "请只使用 viking://resources/lighthouse-demo 中的资料,先按问题进行语义检索,再读取相关原文并回答:灯塔项目第一版应怎样收集用户反馈,需要提前准备什么?为关键结论列出来源文件的完整 viking:// URI;资料没有说明的部分请明确指出。"+```++### 核对回答的依据++打开回答引用的来源文件,逐项比较下面的事实。回答可以采用不同措辞,关键是结论与原文一致。++| 应包含的结论 | 原文依据 |+| --- | --- |+| 反馈保存在本地,由试点管理员每周导出并交给项目负责人 | “反馈收集” |+| 提前准备离线安装包和本地存储目录 | “试点环境” |+| 第一版没有云端同步,后续是否支持尚未决定 | “反馈收集” |++如果某项结论缺少来源,可以请 Agent 补充引用并重新核对。再问一次“试点何时结束?”,查看它是否根据资料说明该日期尚未确定。++至此,你已经完成了资料导入、检索、原文读取和带来源的问答。接下来可以换成自己的资料,重复这个流程。++## 常见问题-## 使用 SDK+| 现象 | 下一步 |+| --- | --- |+| 安装后找不到 `uv`、`node` 或 `ov` | 重新打开终端;仍不可用时,按对应安装指南检查命令路径 |+| `ov health` 连接失败 | 在 `ov config` 中检查当前连接、服务地址和 API Key;本地服务同时检查运行终端 |+| Bot 健康检查返回 `503` | 确认已使用 `--with-bot` 启动,查看服务终端及 [VikingBot 日志](../guides/17-vikingbot.md) |+| 导入失败或检索无结果 | 查看返回的任务状态,确认模型可用、处理完成且查询 URI 与导入目标一致 |+| 模型返回 `UnsupportedModel` | 核对模型名、端点和套餐是否匹配,参见[模型开通指南](../guides/02-volcengine-purchase-guide.md) |+| Agent 无法调用 `ov` | 在 Agent 使用的终端中检查 `ov --version` 和 `ov health`,完成安装及连接配置 |-OpenViking 也提供 Python、TypeScript/JavaScript 和 Go SDK,均连接同一个服务端。客户端示例见 [API 概览](../api/01-overview.md)。+<a id="使用-sdk"></a>## 下一步-先确认你已经读到示例原文,再按[用你的任务验证效果](06-evaluate.md)换成自己的资料或会话。接入日常工具时,选择[Agent 接入方式](../agent-integrations/01-overview.md);自己写应用时,进入[应用开发路径](../workflows/01-overview.md)。+继续[资料检索](08-resources.md),用多份资料体验需要综合来源和资料未覆盖的问题,再用[效果评估](06-evaluate.md)记录自己的任务结果。diff --git a/docs/zh/getting-started/05-cli-setup.md b/docs/zh/getting-started/05-cli-setup.mdindex 60ec281a3..0878d68d4 100644--- a/docs/zh/getting-started/05-cli-setup.md+++ b/docs/zh/getting-started/05-cli-setup.md@@ -1,286 +1,247 @@-# 安装与使用 CLI+# CLI 入门-`ov` 是 OpenViking 的命令行客户端。OpenViking 把 Agent 的上下文存成一个文件系统:资源、记忆和技能都是 `viking://` 下的目录和文件。用 `ov` 可以浏览、读取、检索和写入这些内容。Agent 也用同样的命令操作这些内容。+`ov` 是 OpenViking 的命令行客户端。你可以在终端中用它导入资料、检索内容和读取原文,也可以让能够执行终端命令的 Agent 调用它,为回答提供依据。-`ov` 连接一个已有的 OpenViking 服务。还没有服务时,先完成[快速开始](02-quickstart.md)的第 1 步。+本页从安装和连接开始,带你浏览一份资料、按问题检索并读取结果。完成后,你就可以在自己的终端或 Agent 中使用同一个 OpenViking 连接。-## 让 Agent 配置--点击下方的**复制**,把提示词粘贴给你使用的编程 Agent,例如 Claude Code、Codex 或 Cursor。Agent 会安装 `ov`,向你确认要连接的服务,然后保存配置并检查连接。--<AgentPrompt>+## 准备工作-````markdown-# openviking-cli+准备以下工具和连接信息:-> `ov` 是 OpenViking 的命令行客户端。OpenViking 是面向 AI Agent 的上下文数据库。`ov` 连接已有的 OpenViking 服务端,或连接火山引擎上的 OpenViking 服务。+| 准备项 | 获取方式 |+| --- | --- |+| Node.js 和 npm | 从 [Node.js 官网](https://nodejs.org/en/download)安装 LTS 版本,npm 随安装包提供;已有可用的 `ov` 时可直接进入[连接](#连接) |+| OpenViking 服务 | 使用已开通的火山引擎云服务或正在运行的自建服务;还没有服务时,先完成[快速开始](02-quickstart.md#开通或启动服务)中的开通或启动步骤 |+| 访问凭据 | 云服务使用控制台提供的 API Key;开启认证的自建服务使用管理员提供的 User/Admin Key;默认无鉴权的本机服务可留空 |+| 一份可访问的资料 | 使用服务中已有的资料;首次体验可在连接成功后[导入灯塔样例](02-quickstart.md#导入样例) |-我希望你为我安装并配置 OpenViking CLI(`ov`)。自主执行下面的全部步骤。只在步骤标注 ASK 的地方停下来问我。+安装 Node.js 后,重新打开终端,确认 Node.js 和 npm 可用:-OBJECTIVE:安装 `ov`,为我的 OpenViking 服务保存一个命名配置,并把它设为当前配置。+```bash+node --version+npm --version+```-DONE WHEN:`ov config validate` 的检查项全部通过(配置文件有效、服务器可连接、认证已通过、健康),并且 `ov health -o json` 返回 `"healthy": true`。+CLI 通过 HTTP 连接服务。仅安装 CLI 时,无需在本机安装 Python 或配置模型;资料处理使用服务端配置的模型。-## TODO+## 安装-- [ ] 安装 `ov` 并设置显示语言-- [ ] 确认要连接的服务-- [ ] 保存并激活命名配置-- [ ] 验证连接+使用 npm 安装 `ov`:-## 规则+```bash+npm install -g @openviking/cli+```-- 你不能猜测连接目标。已有配置、本地文件、开放端口和正在运行的服务都不代表我的同意。-- 切换、替换或删除配置,探测或启动本地服务,或写入数据之前,你必须先 ASK 我。-- API Key 不能出现在命令文本、shell 历史、日志、记忆或打印出的配置文件中。只能通过 stdin 或已经存在的环境变量传入 key。-- 如果你无法用这两种方式传入 key,ASK 我自己运行 `ov config` 并输入 key。-- 运行 `ov config add` 时必须传 `--name`,这样重试会更新同一个配置。-- `ov config add|edit|list|switch|delete` 必须加 `-o json`。根据退出码和 `error.code` 判断结果,不要解析说明文字。-- 如果本机 `ov --help` 与本文不一致,以本机帮助为准,并告诉我差异。+安装后设置显示语言,便于后续交互和 Agent 调用。中文使用 `zh-CN`,英文使用 `en`:-## 第 1 步:安装 ov+```bash+ov language zh-CN+```-需要 Node.js 和 npm。+确认终端可以找到 CLI 并输出版本号:```bash-command -v ov || npm i -g @openviking/cli-ov language zh-CNov --version```-如果我用英文和你交流,改用 `ov language en`。未保存显示语言时,大多数 `ov` 命令在非交互式 shell 中以退出码 2 退出。+如果安装服务端时已提供 `ov`,可以直接使用已有命令。-安装后仍找不到 `ov` 时,把 `$(npm prefix -g)/bin` 加入 `PATH`。不要使用 `sudo npm`。没有 npm 时,先 ASK 我,再用 `cargo install --git https://github.com/volcengine/OpenViking ov_cli` 从源码构建。+## 连接-查看要用到的命令帮助:+打开连接向导,为要访问的服务添加一个命名连接:```bash-ov config add ov-service --help-ov config add custom --help+ov config```-## 第 2 步:确认连接目标+按所选服务填写连接信息,保存后设为当前配置。已有对应连接时,直接选中它即可。-运行 `ov config list -o json`。如果已有配置与目标一致,先 ASK 我,再用 `ov config switch <NAME> -o json` 激活它。+| 服务 | 连接类型 | 填写内容 |+| --- | --- | --- |+| 本机默认服务 | 自定义(Custom) | URL 为 `http://127.0.0.1:1933`;默认无鉴权模式下密钥留空 |+| 远程自建服务 | 自定义(Custom) | 使用管理员提供的服务 URL 和 User/Admin Key |+| 火山引擎云服务 | OpenViking Service | 使用向导提供的服务地址,输入控制台取得的 API Key |-否则,除非我已经说明,ASK 我要连接哪种目标:+可以将连接命名为 `local`、`cloud` 等便于识别的名称。服务 URL 指向 OpenViking 数据服务;模型的 API 地址配置在服务端。-| 目标 | 服务地址 | API Key |-|---|---|---|-| OpenViking 服务(火山引擎云) | 固定地址,不要传 `--url`。 | 必填。我在[控制台](https://console.volcengine.com/vikingdb/openviking/region:openviking+cn-beijing?utm_source=opensource_docs&utm_medium=referral&utm_campaign=getting-started_05-cli-setup)的“用户管理 → API Key”中获取。 |-| 远程自建服务 | ASK 我。 | ASK 我。 |-| 本机自建服务 | `http://127.0.0.1:1933` | 通常不需要。 |+通过向导输入密钥,可以避免把密钥明文写入命令历史。在 API Key 认证模式下,普通数据访问使用 User/Admin Key,Root Key 用于服务管理。更多身份配置见[身份认证](../guides/04-authentication.md)。-只有目标是本机自建服务时,才检查服务是否运行:`curl -fsS http://127.0.0.1:1933/health`。检查失败时,ASK 我启动服务端。参见 https://docs.openviking.ai/zh/guides/03-deployment 。+## 检查连接-除非我的管理员提供了 `--account` 和 `--user` 的值,否则不要询问这两项。--## 第 3 步:保存并激活配置--把 `<NAME>`、`<URL>` 和 `<ENV_VAR>` 替换为确认过的值,不保留尖括号。`$OV_API_KEY` 表示可信的运行时密钥来源,不是字面量 key。--OpenViking 服务:+先查看当前连接,核对服务地址。该命令会隐藏密钥:```bash-printf '%s' "$OV_API_KEY" | ov config add ov-service --name <NAME> --api-key-stdin --activate -o json+ov config show```-使用 API Key 的远程自建服务:+再验证配置、连接和认证:```bash-printf '%s' "$OV_API_KEY" | ov config add custom --name <NAME> --url <URL> --api-key-stdin --activate -o json+ov config validate```-无鉴权的本机自建服务:+检查通过后,查看服务健康状态:```bash-ov config add custom --name <NAME> --url http://127.0.0.1:1933 --activate -o json+ov health```-特殊密钥情况:--- key 已经在环境变量中时,用 `--api-key-env <ENV_VAR>` 代替 `--api-key-stdin`。-- 只有 root key,且服务端为 `trusted` 模式:使用 `--root-api-key-stdin --account <ACCOUNT> --user <USER>`。服务端为 `api_key` 模式时,root key 不能读取数据,ASK 我提供 user 或 admin key。-- 同时有 user key 和 root key:使用 `--api-key-stdin --root-api-key-env <ENV_VAR>`。一条命令只有一个 stdin,所以第二个 key 必须来自已存在的环境变量。--`ov config` 子命令的退出码:--| 退出码 | 含义 | 你的操作 |-|---|---|---|-| `0` | 成功,或已经处于目标状态 | 继续。 |-| `2` | 输入错误、缺少参数,或未设置显示语言 | 修正输入,或运行 `ov language <code>`。 |-| `3` | 同名配置已存在且内容不同 | 先 ASK 我,再加 `--force`。 |-| `4` | 服务端不可达,或配置校验失败 | ASK 我确认 URL,以及服务是否运行。 |-| `5` | 鉴权失败,或 key 角色不匹配 | ASK 我确认 key 和 key 类型。 |-| `6` | 操作被拒绝,例如删除当前配置 | ASK 我如何继续。 |+结果中的 `healthy: true` 表示服务健康。接下来读取一份资料,确认当前身份可以访问所需内容。资料导入所用的模型,以及 VikingBot 的问答能力,在各自的使用步骤中验证。-不要用猜测的值重试。+## 浏览与读取-## 第 4 步:验证+列出当前服务中可访问的共享资料目录:```bash-ov config validate-ov health -o json+ov ls viking://resources```-读取输出内容。退出码为 0 不代表服务健康。查看配置时使用 `ov config show`,它会隐藏密钥。不要打印 `~/.openviking/ovcli.conf`。--除非我要求,不要导入数据做演示。--配置完成后,我可能会让你用 `ov` 浏览、检索、添加或整理内容。OpenViking 的内容是 `viking://` 下的目录树。读取时,先用 `ov abstract` 或 `ov overview` 读目录摘要,再用 `ov read` 读需要的文件。运行 `ov --help` 查看命令分组。使用某条命令前,先运行 `ov <命令> --help`。--EXECUTE NOW:完成上面的 TODO 列表,达到:`ov config validate` 的检查项全部通过,并且 `ov health -o json` 返回 `"healthy": true`。--需要更多上下文时,阅读 https://docs.openviking.ai/llms.txt 。-````--</AgentPrompt>--下文是手动配置步骤。--## 准备--需要 Node.js 和 npm。+如果还没有资料,先[导入灯塔样例](02-quickstart.md#导入样例),等待处理完成后回到这里。以下使用样例目录 `viking://resources/lighthouse-demo`;使用自己的资料时,将命令中的目录 URI 换成实际路径。-还需要连接信息。连接信息取决于服务类型:--| 服务类型 | 服务地址 | API Key |-|---|---|---|-| OpenViking 服务(火山引擎云) | 固定地址,无需填写。 | 必填。在 [OpenViking 控制台](https://console.volcengine.com/vikingdb/openviking/region:openviking+cn-beijing?utm_source=opensource_docs&utm_medium=referral&utm_campaign=getting-started_05-cli-setup)的**用户管理 → API Key** 中获取。 |-| 远程自建服务 | 向管理员获取。 | 向管理员获取。 |-| 本机自建服务 | `http://127.0.0.1:1933` | 默认配置不需要。 |--## 1. 安装 `ov`+展开目录,找到资料正文对应的文件 URI:```bash-npm i -g @openviking/cli-ov language zh-CN-ov --version+ov tree viking://resources/lighthouse-demo```-`ov language` 设置显示语言。英文界面使用 `en`。未设置语言时,大多数命令不能运行。--在运行 OpenViking 服务端的机器上,`ov` 已随服务端安装。跳过 `npm i`,只设置语言。--## 2. 添加连接+复制输出中的文件 URI,替换下面的占位值,读取正文:```bash-ov config+ov read "<文件 URI>"```-按提示操作:+样例正文包含“试点环境”和“反馈收集”等内容。能够读到正文,说明连接和文件访问已完成。-1. 选择**添加配置**。-2. 选择服务类型。OpenViking 服务选择 **OpenViking 服务(火山引擎云)**;自建服务选择**自定义**。-3. 输入配置名称。留空时,`ov` 自动生成名称。-4. 按提示输入服务地址和 API Key。-5. 校验通过后,选择**保存并设为当前配置**。+## 检索资料-## 3. 检查连接+当你有具体问题时,可以先检索相关内容,再读取命中的原文。检索使用服务端的模型配置,可能产生模型调用费用。```bash-ov config validate+ov find "灯塔项目第一版怎样收集用户反馈?" --uri viking://resources/lighthouse-demo```-输出的**检查项**全部通过时,连接可用:配置文件“有效”,服务器“可连接”,认证“已通过”,健康状态“健康”。--配置到此完成。接下来可以[导入并检索第一份文档](02-quickstart.md#_3-导入文档)。想了解更多,可以继续往下看。+结果会列出匹配内容及其 URI。选择与问题相关的结果,用 `ov read` 读取正文,核对反馈由谁收集、如何交付。CLI 返回的检索结果可以作为 Agent 生成回答的依据。-## `ov` 能做什么+## 交给 Agent 使用-OpenViking 的内容是一棵目录树。运行 `ov ls` 查看根目录 `viking://`:+在能够执行终端命令的 Agent 中发送下面的任务,让它使用已配置的 CLI 完成检索、阅读和回答:-- `viking://resources/`:导入的文档、代码仓库和网页。同一账号内共享。-- `viking://user/<用户 ID>/`:你的记忆、私有资源、技能和会话。`viking://~/` 指向这个目录。-- `viking://agent/`:同一账号内共享的技能和 Agent 配置。+```text+请使用已配置的 ov CLI,查询 viking://resources/lighthouse-demo 中的资料。+先按“灯塔项目第一版怎样收集用户反馈,需要提前准备什么?”进行 ov find 检索,+再用 ov read 读取相关结果的原文,然后回答这个问题。+为关键结论列出来源文件的完整 viking:// URI;资料未说明的内容请明确指出。+```-每个目录有 L0 摘要和 L1 概览。文件全文是 L2。先读目录的 L0 和 L1,判断内容是否相关,再读需要的 L2 文件。详见 [Viking URI](../concepts/04-viking-uri.md) 和[上下文层级](../concepts/03-context-layers.md)。+Agent 需要能访问 `ov` 命令及其连接配置。如果 Agent 运行在另一台电脑、容器或不同系统用户下,在该环境中完成安装和连接,再执行任务。-| 任务 | 命令 |-|---|---|-| 浏览目录 | `ov ls`、`ov tree`、`ov stat`。`ov tui` 打开交互式浏览界面。 |-| 按层读取 | `ov abstract`(L0)、`ov overview`(L1)、`ov read`(L2)。`ov get` 把文件下载到本地。 |-| 检索 | `ov find`(语义检索)、`ov grep`(匹配内容)、`ov glob`(匹配路径) |-| 导入资料和技能 | `ov add-resource`、`ov add-skill`、`ov skills` |-| 写入和整理 | `ov write`、`ov mkdir`、`ov mv`、`ov cp`、`ov rm` |-| 从对话中提取记忆 | `ov session new`、`ov session add-message`、`ov session commit`。`ov add-memory` 一步完成这三步。 |-| 等待后台处理 | `ov task list`、`ov task status`、`ov wait` |-| 保存和回滚版本 | `ov snapshot` |-| 备份与迁移 | `ov export`、`ov import`、`ov backup`、`ov restore` |-| 重建索引(`viking://resources` 需要 admin key) | `ov reindex` |-| 管理用户(需要 admin 或 root key) | `ov admin list-users`、`ov admin register-user`、`ov admin regenerate-key` |-| 检查服务 | `ov health`、`ov status` |+`ov chat` 则将问题发送给服务端的 **VikingBot**。使用它需要目标服务已启用 VikingBot;本机可按 [VikingBot](11-vikingbot.md) 章节使用 `openviking-server --with-bot` 启动。火山引擎云服务路径使用上面的 Agent 调用方式完成问答。`ov health` 检查的是数据服务,Bot 的可用状态需另外检查。-导入资料和提交会话后,服务端在后台处理:解析内容,提取记忆,生成 L0 和 L1,建立索引。处理完成前,`ov find` 检索不到新内容。+## 切换连接-用 `ov <命令> --help` 查看命令的参数。这些操作也可以直接交给 Agent 完成。+同时使用云端和本地服务时,先列出已保存的连接:-::: warning 注意-`ov rm -r` 会删除目录及其中的全部内容。删除在服务端执行,使用同一服务的其他 Agent 也会失去这些内容。删除前,先用 `ov ls` 确认 URI。-:::+```bash+ov config list+```-## 管理多个连接+打开选择器,切换到目标连接:```bash-ov config list # 列出已保存的配置-ov config switch # 选择当前配置-ov config show # 查看当前配置,密钥会被隐藏+ov config switch```-编辑或删除配置时,运行 `ov config` 并选择对应操作。在脚本中添加配置时,使用 `ov config add`,参数见 `ov config add --help`。+切换后查看当前地址,并重新检查连接:-当前配置是 `~/.openviking/ovcli.conf`。每个已保存的配置是 `~/.openviking/ovcli.conf.<名称>`。设置 `OPENVIKING_CLI_CONFIG_FILE` 后,`ov` 改用该文件作为当前配置,已保存的配置位于该文件所在目录。全部字段见[客户端配置](../configuration/02-client.md)。+```bash+ov config show+ov health+```-## API Key+切换连接后,命令访问的是目标服务及当前身份下的内容。云端导入的资料会保留在云端;在本地体验同一样例时,需要向本地服务导入。迁移已有资料可参考[导入导出](15-transfer.md#数据服务间迁移)。-服务使用 API Key 认证时,key 有三种角色:+两类配置文件分别负责连接和服务运行:-- **User key**:用于数据命令,例如 `ov add-resource` 和 `ov find`。大多数用户只需要这种 key。-- **Admin key**:可以执行数据命令,也可以管理本账号的用户。-- **Root key**:管理整个服务,例如创建账号。在 `api_key` 模式下,root key 不能读写账号数据。+| 配置文件 | 用途 |+| --- | --- |+| `~/.openviking/ovcli.conf` | CLI 当前连接、访问凭据和命令默认行为 |+| `~/.openviking/ov.conf` | 自建服务的模型、存储和服务参数 |-一个配置可以同时保存 user key 和 root key。普通命令使用 user key。`ov admin`、`ov system`、`ov reindex`、`ov task status` 和 `ov task list` 加 `--sudo` 时使用 root key。详见[认证](../guides/04-authentication.md)。+需要指定其他配置路径或在脚本中管理命名连接时,查看[客户端配置](../configuration/02-client.md)和 `ov config --help`。-保护 API Key:+## 常用命令-- 在 `ov config` 的输入框中输入 key。不要把 key 写进命令,shell 历史会保存命令。-- 用 `ov config show` 查看配置,它会隐藏密钥。不要分享 `~/.openviking/ovcli.conf` 的内容或截图。-- 演示和试用时,使用可以撤销的临时 key。-- 让 Agent 配置时,不要把 key 粘贴到对话中。把 key 放进环境变量,或在 Agent 请求时自己运行 `ov config` 输入 key。+| 目的 | 命令 |+| --- | --- |+| 查看目录 | `ov ls "<目录 URI>"`、`ov tree "<目录 URI>"` |+| 按问题检索 | `ov find "问题" --uri "<目录 URI>"` |+| 读取原文 | `ov read "<文件 URI>"` |+| 查看已生成的目录概览 | `ov overview "<目录 URI>"` |+| 查看后台任务 | `ov task status <task_id>` |+| 查询参数 | `ov --help`、`ov <命令> --help` |## 常见问题-### 找不到 `ov`+| 现象 | 下一步 |+| --- | --- |+| 找不到 `npm` 或 `ov` | 安装 Node.js 后重新打开终端;若 npm 已可用而 `ov` 不可用,检查 npm 全局可执行文件目录是否在 `PATH` 中 |+| npm 安装权限错误 | 按 [npm 官方指南](https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally)调整全局安装权限 |+| 命令提示设置语言 | 运行 `ov language zh-CN` 或 `ov language en`,保存显示语言 |+| 连接失败 | 用 `ov config show` 核对当前 URL;本机服务需保持运行,再用 `ov config validate` 检查 |+| 认证失败或读取被拒绝 | 核对 Key 类型和资料访问权限,见[身份认证](../guides/04-authentication.md) |+| 切换连接后找不到原资料 | 核对目标服务和身份;向该服务导入样例,或迁移原资料 |+| `ov chat` 返回 `404 page not found` | 核对当前地址是否提供 VikingBot 接口;云服务可由已有 Agent 调用 CLI 完成问答,本地服务按 [VikingBot](11-vikingbot.md) 章节启动并检查 Bot |+| 导入时模型返回 `UnsupportedModel` | 核对服务端 `ov.conf` 中模型名称、端点和套餐是否匹配,参见[模型开通指南](../guides/02-volcengine-purchase-guide.md) |+| 找不到目录概览 | 查看资料处理状态;概览是否生成取决于处理方式与配置,见[上下文层级](../concepts/03-context-layers.md) |-打开一个新终端。仍然找不到时,把 npm 全局 binary 目录加入 `PATH`。在 macOS 和 Linux 上,该目录通常是 `$(npm prefix -g)/bin`。+## 让 Agent 配置-### npm 报权限错误+也可以让 Agent 帮你完成安装和连接。复制下面的提示词,并补充要连接的服务类型、连接名称和自建服务地址。API Key 通过交互向导输入,或由已有的可信环境变量提供。-按你平时管理 Node.js 的方式修复权限,例如使用 nvm。除非你一直用 sudo 管理全局包,否则不要运行 `sudo npm i -g`。+<AgentPrompt>-### 命令提示需要显示语言+```text+请帮我安装并配置 OpenViking CLI(ov),连接我指定的 OpenViking 服务。-运行 `ov language zh-CN` 或 `ov language en`,然后重新运行命令。+先检查 ov 是否已安装;需要安装时使用 npm install -g @openviking/cli。+如果缺少 Node.js/npm,请说明安装方式。将 CLI 显示语言设为 zh-CN。-### 本机服务没有响应+根据我提供的目标,查看 ov config list -o json,复用匹配的命名连接;+新建连接前查看 ov config add ov-service --help 或 ov config add custom --help。+使用明确的 --name 保存连接,并将已确认的目标设为当前配置。+如果服务类型、URL 或凭据来源缺失,请向我询问缺失项。+遇到同名但内容不同的配置,先说明差异,再询问是否替换。-检查服务:+API Key 使用 --api-key-env 从已有环境变量读取,或通过 --api-key-stdin 传入。+如果没有可用的安全输入方式,引导我在终端运行 ov config 输入密钥。+展示配置时使用 ov config show,避免输出凭据。-```bash-curl http://127.0.0.1:1933/health+完成后运行 ov config validate 和 ov health,检查实际返回结果。+告诉我当前连接的服务地址、检查结果,以及仍需处理的问题。+本次任务完成安装和连接,资料导入由后续任务指定。```-检查失败时,先启动服务端。参见[部署](../guides/03-deployment.md)。--### API Key 校验失败--运行 `ov config`,选择**编辑配置**,重新输入 key。OpenViking 服务的 key 从控制台复制。自建服务的 key 和 key 类型向管理员确认。在 `api_key` 模式下,数据命令需要 user key 或 admin key。--### 当前配置不对--运行 `ov config list` 查看当前配置。运行 `ov config switch` 选择其他配置。+</AgentPrompt>## 下一步-- 导入并检索第一份文档:[快速开始](02-quickstart.md)。-- 把 OpenViking 接入你日常使用的 Agent:[Agent 接入方式](../agent-integrations/01-overview.md)。+继续[快速开始](02-quickstart.md#提问并核对),完成带来源的资料问答;准备导入自己的项目资料时,查看[资料检索](08-resources.md)。++<!-- Preserve incoming links to previous section titles. -->+<a id="_1-安装"></a>+<a id="_2-连接"></a>+<a id="_4-浏览与读取"></a>+<a id="安装与使用-cli"></a>+<a id="准备"></a>+<a id="_1-安装-ov"></a>+<a id="_2-添加连接"></a>+<a id="_3-检查连接"></a>+<a id="ov-能做什么"></a>+<a id="管理多个连接"></a>+<a id="api-key"></a>+<a id="找不到-ov"></a>+<a id="npm-报权限错误"></a>+<a id="命令提示需要显示语言"></a>+<a id="本机服务没有响应"></a>+<a id="api-key-校验失败"></a>+<a id="当前配置不对"></a>diff --git a/docs/zh/getting-started/06-evaluate.md b/docs/zh/getting-started/06-evaluate.mdindex 24fa46c38..0e79ae48d 100644--- a/docs/zh/getting-started/06-evaluate.md+++ b/docs/zh/getting-started/06-evaluate.md@@ -1,50 +1,62 @@-# 用你的任务验证效果+# 效果评估-[第一次导入与检索](02-quickstart.md)跑通后,换成你工作中的资料或会话,验证它能否帮你找到依据、复用经验或产出内容。先选一个场景,得到结果后再扩展。+选择你熟悉的小任务,记录预期结果,再用相同输入检查实际表现。本页提供可填写的[评估表 CSV](/quickstart/evaluation-v1.csv),用于首次体验、调整配置和升级后的复查。-| 你希望改善什么 | 从哪里开始 | 看什么结果 |-| --- | --- | --- |-| 查项目资料时少翻文件 | [资源导入与检索](02-quickstart.md) | 能找到回答问题所需的原文,而不只是返回相似词 |-| Agent 在新会话里复用已有背景 | [选择 Agent 接入方式](../agent-integrations/01-overview.md) | 记忆确实被保存,并在相关任务中召回;用户不必再次输入相同背景 |-| 把散落资料整理成可读的内容 | [上下文编译](../context-compilation/01-overview.md) | 产物引用或使用了哪些来源,结构是否适合后续阅读,是否仍有遗漏或错误 |+本轮 v1 样例已在隔离本机服务中验证,服务端、CLI 和 VikingBot 均为 0.5.2。模型、日期、执行范围及遇到的问题见[样例验证记录](/quickstart/verification-v1.txt),可据此选择与你环境相符的测试条件。-## 用自己的资料检查检索+## 固定评估条件-选一小组你熟悉的资料,例如项目说明、操作手册或一次问题复盘。按[快速开始](02-quickstart.md)导入,再准备几个你知道答案的问题。每个问题记下预期来源,检索后读取返回的 URI,核对原文。+记录服务端、CLI、Agent 或插件版本、模型、部署方式、身份及项目范围。保留原始输入和预期来源,使用独立演示目录。比较不同配置时,尽量保持问题、资料和模型相同;条件变化可写入备注。-至少覆盖三种情况:资料中有直接答案;答案需要结合两处内容;资料中没有答案。记录是否找到依据、是否漏掉关键内容,以及后续 Agent 回答是否忠于原文。`find` 返回 URI 和分数,生成回答还需要你的 Agent 或应用读取并使用这些内容。+首次使用可以采用[资料检索](08-resources.md)的四份资料,之后替换为自己的文档。每组任务记录环境准备时间、首次有效结果时间、求助次数和跳出页面,便于判断入门流程是否顺畅。-首次成功后,再逐步加入其他来源。这样发现问题时,可以判断是资料处理、检索还是回答生成出了偏差。结果不符合预期时,使用[观测与排障](../guides/05-observability.md)检查处理状态和请求行为。+## 用自己的资料检查检索-## 用两次会话检查记忆+| 用例 | 问题类型 | 核对重点 |+| --- | --- | --- |+| R1 | 单一来源有直接答案 | 回答准确,引用能打开 |+| R2 | 需要多份来源 | 关键依据齐全,结论忠于原文 |+| R3 | 资料中没有答案 | 清楚说明缺失信息 |-先查看[集成能力对照](../agent-integrations/16-capability-reference.md),确认你选的插件支持哪些自动捕获、提交和召回行为,再按该插件的验证步骤操作。+依次记录导入任务、检索结果、读取 URI、最终答案及来源。若失败,标注最早出现偏差的阶段,再查看该阶段日志。-1. 在第一次会话中提供一条无敏感信息、后续确实会用到的偏好或项目背景。-2. 按插件的提交机制结束或提交会话。检查处理状态、实际生成的记忆及其用户或 Peer 归属;提交成功不保证产生某条记忆。-3. 用同一身份开启新会话,提出需要该背景的任务,不再次输入那条信息。检查召回记录与最终回答,确认 Agent 使用了保存的内容。-4. 再问一个无关问题,观察旧背景是否被不恰当地带入回答。+## 用两次会话检查记忆-插件安装成功不等于记忆验证完成。若没有产物,检查[会话与记忆提取](../concepts/08-session.md);已有产物却没有召回时,检查身份、检索范围和插件行为。应用自己管理会话时,从[应用开发路径](../workflows/01-overview.md)进入对应 API。+按[记忆使用](09-memory.md)先保存一条测试约定,再用同一身份开启新的会话。新问题只给任务,不重复约定,记录产物、召回记录和答案中的实际使用情况。增加一个无关问题,检查相关性。-## 用一份产物检查上下文编译+| 用例 | 任务 | 核对重点 |+| --- | --- | --- |+| M1 | 新会话需要原有背景 | 能使用已保存的约定 |+| M2 | 新会话与原背景无关 | 回答保持聚焦当前问题 |-选择[知识 Wiki](../context-compilation/02-llm-wiki.md)、[知识图谱](../context-compilation/03-knowledge-graph.md)或[日报](../context-compilation/04-daily-report.md)中的一种,按教程准备来源并执行。先确认任务完成和产物位置,再检查内容:+## 检查技能与编译产物-- 关键事实是否能回到来源核对?-- 有哪些遗漏、重复或没有依据的表述?-- 你能否用产物完成原本的阅读或整理任务?+[技能使用](10-skills.md)采用两组输入,比较输出结构、事实保留和未知信息处理。检查 Agent 读取技能的记录。[上下文编译](13-compile.md)需要打开至少一篇正文,逐条核对来源、遗漏和无依据表述。-第一次选你熟悉的来源,便于识别错误。任务成功或文件生成,只说明处理完成;产物是否可用仍需要核对。+版本与迁移任务可分别按[版本管理](14-versions.md)、[导入导出](15-transfer.md)检查恢复范围、文件内容、元数据与检索就绪情况。-## 有结果后,选择一条继续路径+## 填写记录-| 当前结果 | 下一步 |+| 字段 | 记录方式 || --- | --- |-| 文档检索满足需要,想在日常工具里使用 | [接入已有 Agent](../agent-integrations/01-overview.md) |-| 已验证能力,准备写入自己的应用 | [应用开发路径](../workflows/01-overview.md) |-| 想使用 OpenViking 自带的 Agent | [VikingBot 安装与配置](../guides/17-vikingbot.md) |-| 准备让团队共享服务 | [选择部署路径](../guides/00-overview.md),再核对身份与访问控制 |-| 想理解结果背后的机制 | [概念与原理](../concepts/00-overview.md) |+| 问题与输入 | 保留本次完整问题、资料版本或测试会话 |+| 预期事实与来源 | 执行前填写已知答案及依据 URI |+| 实际答案与来源 | 保存原始回复和实际引用 |+| 阶段与结果 | 导入、处理、检索、读取、回答、保存或召回;通过、失败或待验证 |+| 耗时 | 从提交到可核对结果的实际时间 |+| 环境与备注 | 版本、模型、身份、配置差异及人工修订 |++评估表中的示例行留空,供你填写实际结果。对主观质量可事先约定标准,例如关键事实全部有依据、未覆盖信息明确标注、产物能支持目标任务。++## 定位问题并复查++文件缺失先看导入;文件存在但查询无结果时看索引和范围;命中正确但回答偏差时看 Agent 读取与生成;记忆问题按保存、提取、召回、使用依次定位。具体诊断见[观测与排障](../guides/05-observability.md)。++保留每次评估记录,用同一组任务复查修订。文档和样例的技术验证记录用于说明已检查的范围;实际用户能否独立完成、能否解释依据和替换自己的输入,需要在审核与试用中观察。++<a id="用一份产物检查上下文编译"></a>+<a id="有结果后选择一条继续路径"></a>+<a id="用你的任务验证效果"></a>-保留试用中的问题、预期来源和实际结果,后续改配置或升级时用同一组任务复查。若要比较使用前后的变化,保持任务、模型与输入条件一致;检索分数和单次成功不能代替效果比较。+<!-- Keep incoming links to previous evaluation headings working. -->+<a id="有结果后-选择一条继续路径"></a>diff --git a/docs/zh/getting-started/07-agent-onboarding.md b/docs/zh/getting-started/07-agent-onboarding.mdindex b0a4384e9..7dce61ddb 100644--- a/docs/zh/getting-started/07-agent-onboarding.md+++ b/docs/zh/getting-started/07-agent-onboarding.md@@ -1,6 +1,10 @@-# 一条提示词接入 Agent+<a id="一条提示词接入-agent"></a>-把一条提示词粘贴给你正在用的编程 Agent。Agent 会在本机检测到的各个 Agent 里安装 OpenViking 记忆插件,检查连接,问你要不要导入近期工作,再告诉你怎么重启。重启后,你问的第一个问题就能用上 OpenViking。+<a id="一键集成-agent"></a>++# 一键接入++通过一条提示词,将 OpenViking 接入你正在使用的编程 Agent。Agent 会在本机检测到的各个 Agent 里安装 OpenViking 记忆插件,检查连接,问你要不要导入近期工作,再告诉你怎么重启。重启后,你问的第一个问题就能用上 OpenViking。Agent 按一份简短的指南执行。指南以纯 Markdown 发布,任何 Agent 都能直接获取:diff --git a/docs/zh/getting-started/07-options.md b/docs/zh/getting-started/07-options.mdnew file mode 100644index 000000000..dfc7fd010--- /dev/null+++ b/docs/zh/getting-started/07-options.md@@ -0,0 +1,41 @@+# 部署模式++<a id="使用方式"></a>++你可以自行运行 OpenViking,连接火山引擎托管服务,或申请企业私有化交付。选择时先看数据放在哪里、谁负责运行和需要怎样的支持。++已有服务地址与 API Key 的用户无需重新部署,直接进入 [CLI 入门](05-cli-setup.md)。想在本机跑一次完整问答,按[快速开始](02-quickstart.md)操作。++## 选择一条路径++| 方式 | 数据与运行环境 | 运维与支持 | 需要准备 |+| --- | --- | --- | --- |+| **开源自建** | 自己的本机、服务器或云环境,存储由自己配置 | 自行部署、升级、备份与配置访问控制;通过开源社区获取帮助 | 运行环境、模型访问凭据和存储 |+| **云服务** | 火山引擎托管的服务环境,区域与数据使用条件以服务说明为准 | 服务方运行基础设施;用户管理自己的接入、数据与授权 | 开通服务,获取连接信息和 API Key |+| **企业部署** | 按交付方案部署到自己的云账号、VPC 或离线环境 | 运维分工、技术支持及验收范围按实际交付约定 | 申请部署物料与 License,完成环境检查 |++“开源/商业”描述软件与支持方式,“自建/托管”描述部署责任。开源自建也可用于团队环境,选择时可以结合访问控制需求、部署条件和支持方式综合考虑。各版本的具体能力与限制见相应版本和服务说明。++## 开源自建++适合需要控制环境、自己调试或接入应用的用户。开源服务器采用 AGPLv3;本机体验不需要企业部署物料。按照[快速开始](02-quickstart.md)准备模型、启动服务和 VikingBot,再导入样例问答。++团队共享前,需要完善身份认证、持久化、备份和运维。Docker、开源 Helm 等路径见[服务端部署](../guides/03-deployment.md);许可文本见 [LICENSE](https://github.com/volcengine/OpenViking/blob/main/LICENSE)。++## 云服务++火山引擎的 OpenViking Context 是基于开源 OpenViking 内核的托管服务。开通后,在 [OpenViking 控制台](https://console.volcengine.com/vikingdb/openviking/region:openviking+cn-beijing)获取 API Key,在 `ov config` 中选择 **OpenViking Service** 并保存连接,无需在本机启动数据服务。++套餐、额度、可用区域与支持范围见[官方服务说明](https://docs.volcengine.com/docs/84313/2374478)。VikingBot 和 Compile Runtime 的可用性取决于所选服务的配置;如需使用,可以向服务提供方了解支持情况。数据服务也支持通过自己的 Agent 接入。++## 企业部署++适合需要私有化交付、部署物料和官方支持的团队。通过[官方咨询入口](https://my.feishu.cn/share/base/form/shrcnMFqymCd9sq77sLk34Krxoc)确认方案,按实际交付要求申请物料与 License。++当前[企业部署指南](../guides/20-private-deployment.md)使用 Kubernetes 环境中的 VikingDB 和 OpenViking。准备部署物料时,可以按照[部署前检查](../guides/19-deployment-checklist.md)一并准备镜像、存储和依赖环境。++## 选好之后++取得 URL 和数据访问凭据后,进入 [CLI 入门](05-cli-setup.md)。如果想先验证完整本地体验,使用[快速开始](02-quickstart.md)。++依据:[项目商业版本说明](https://github.com/volcengine/OpenViking/blob/main/docs/repository/README_CN.md#商业版本)、[云服务产品介绍](https://docs.volcengine.com/docs/84313/2374478)、[企业部署指南](../guides/20-private-deployment.md)。核对日期:2026-10-27。diff --git a/docs/zh/getting-started/08-resources.md b/docs/zh/getting-started/08-resources.mdnew file mode 100644index 000000000..a738ae546--- /dev/null+++ b/docs/zh/getting-started/08-resources.md@@ -0,0 +1,122 @@+<a id="资源检索"></a>++# 资料检索++项目说明、会议记录和反馈流程往往分散在多份文档中。将这些资料导入 OpenViking 后,可以按问题的含义检索相关内容,再让 Agent 读取原文,综合回答并标注来源。++本节使用四份虚构的“灯塔项目”资料,带你完成 **导入资料 → 检索 → 读取原文 → 生成回答 → 核对来源**。你会分别查看只需一份资料就能回答、需要综合多份资料,以及资料尚未给出答案的三类问题。++## 准备环境++开始前,请准备以下环境:++- **OpenViking 服务和 CLI**:按照[快速开始](02-quickstart.md)完成连接配置,当前账号需要具备目标目录的导入和读取权限。+- **VikingBot**:本节通过 `ov chat` 生成回答。请确认服务已启用 VikingBot,并完成模型配置,具体方法见 [VikingBot](11-vikingbot.md)。CLI 和 VikingBot 应连接同一服务,并能访问同一份资料。+- **模型配置**:资料处理、语义检索和生成回答会使用已配置的模型,并产生相应的模型调用费用。++如果使用自己的 Agent,可以按[快速开始中的接入方式](02-quickstart.md#让-agent-生成回答)连接资料服务,再使用下文的问题和核对标准。++## 准备资料++下载[灯塔项目资料包](/quickstart/lighthouse-zh-v1.zip),在终端中进入下载文件所在的目录,再解压:++```bash+unzip lighthouse-zh-v1.zip+```++解压后得到 `lighthouse-zh/` 目录,其中包含以下文件:++| 文件 | 内容 |+| --- | --- |+| `project.md` | 试点的网络条件、离线安装包和本地存储准备 |+| `feedback.md` | 反馈导出时间、责任人和交付方式 |+| `meeting.md` | 反馈登记模板、导出演练和待确认事项 |+| `limits.md` | 资料覆盖范围及尚未提供的信息 |++## 导入资料++将整个目录导入独立的演示路径。`--wait` 会等待资料处理完成,便于后续检索。再次体验时,可将 `onboarding-zh-v1` 换成新的目录名,并同步修改后续命令中的 URI。++```bash+ov add-resource ./lighthouse-zh --to viking://resources/onboarding-zh-v1 --wait+```++处理成功后,查看导入结果:++```bash+ov tree viking://resources/onboarding-zh-v1+```++这组 Markdown 文件处理后会分别放入同名目录。确认目录中包含以下文件,再继续检索:++```text+viking://resources/onboarding-zh-v1/+├── project/project.md+├── feedback/feedback.md+├── meeting/meeting.md+└── limits/limits.md+```++如果等待超时,可用返回的任务 ID 执行 `ov task status <task_id>` 查看进度。任务完成后继续;任务失败时,根据错误信息检查模型或连接配置。任务状态说明见[任务管理](../api/17-tasks.md)。++<a id="检索与回答"></a>++## 检索资料++先提出一个需要综合项目说明和会议记录的问题,将检索范围限定在刚才导入的目录:++```bash+ov find "灯塔项目怎样收集反馈,开始试点前要准备什么?" --uri viking://resources/onboarding-zh-v1+```++检索结果会列出匹配内容及其 URI。查看命中内容是否涉及反馈收集和试点准备,再读取相关原文。`ov find` 用于找到相关资料,下一步的原文读取用于确认具体依据。++## 读取原文++根据检索结果中的 URI 打开来源文件。这组样例中,与问题相关的文件包括项目说明、会议记录和反馈流程:++```bash+ov read viking://resources/onboarding-zh-v1/project/project.md+ov read viking://resources/onboarding-zh-v1/meeting/meeting.md+ov read viking://resources/onboarding-zh-v1/feedback/feedback.md+```++阅读时可以留意:安装包和本地目录写在项目说明中,登记模板和导出演练写在会议记录中。要回答完整的试点准备要求,需要结合这两份资料。++## 生成回答++把检索、读取和回答交给 VikingBot。在新会话中提出下面三个问题,并要求它为结论提供来源、明确标注未知信息。重复体验时,可以将会话名换成新的名称。++```bash+ov chat --session lighthouse-resources-v1 -m "请只使用 viking://resources/onboarding-zh-v1 的资料,先进行语义检索,再读取相关原文,依次回答:反馈由谁在什么时候导出?试点开始前要准备什么?试点何时结束、预算多少?每项结论列出完整来源 URI,资料未说明的内容请标为尚未确定。"+```++回答应包含反馈导出安排、试点准备事项和待确认信息,并为相关结论附上完整的 `viking://` 来源 URI。++## 核对来源++使用 `ov read` 打开回答引用的文件,逐项核对下表。回答措辞可以不同,事实和来源应与原文一致。++| 问题类型 | 问题 | 预期事实 | 来源 |+| --- | --- | --- | --- |+| 单份资料 | 谁在什么时候导出反馈? | 试点管理员每周五导出,并交给项目负责人 | `feedback/feedback.md` |+| 多份资料 | 试点开始前要准备什么? | 离线安装包、本地存储目录、反馈登记模板、一次离线导出演练 | `project/project.md`、`meeting/meeting.md` |+| 尚无答案 | 试点何时结束、预算多少? | 两项均尚未确定 | `meeting/meeting.md` |++结合 `ov chat` 的工具调用输出或 Bot 日志,确认 Agent 检索了相关资料、读取了来源文件,并在回答中使用了这些内容。对于多份资料的问题,检查回答是否遗漏其中一份的要求;对于尚未确定的事项,检查是否保留了原文中的未知状态。++## 常见问题++| 现象 | 处理方法 |+| --- | --- |+| 导入目录中缺少文件 | 检查解压目录是否包含四份资料,并查看导入结果和任务错误 |+| 检索没有相关结果 | 确认处理已完成、查询 URI 与导入目录一致,再尝试用更具体的问题检索 |+| CLI 可以读取,Agent 无法访问 | 核对两者连接的服务、账号和目录访问权限 |+| 检索已命中,但回答遗漏内容 | 查看 Agent 实际读取的文件,请它补读相关来源并完善回答 |+| 回答给出具体结束日期或预算 | 对照会议记录,请 Agent 将缺少依据的结论修正为“尚未确定” |++## 换成自己的资料++选择一组你熟悉的项目资料,分别准备单份资料、多份资料和资料未覆盖的问题,按同样的流程检索与核对。可以使用[效果评估](06-evaluate.md)中的记录表,比较检索结果、原文读取和回答质量。支持的格式、导入选项和增量处理方式见[资料管理](../api/02-resources.md)。++样例目录还可用于后续的[上下文编译](13-compile.md)和[导入导出](15-transfer.md)。如需清理,可在 Studio 中确认目录 URI 后删除该演示目录。diff --git a/docs/zh/getting-started/09-memory.md b/docs/zh/getting-started/09-memory.mdnew file mode 100644index 000000000..cf8cd5308--- /dev/null+++ b/docs/zh/getting-started/09-memory.md@@ -0,0 +1,119 @@+# 记忆使用++记忆让 Agent 在新的会话中继续使用已经了解的偏好、项目背景和工作经验,减少重复说明。OpenViking 可以在会话提交后提取值得保留的信息,供 Agent 在后续任务中检索和使用。++下面以虚构的海岬项目为例:先保存评审习惯,再开启一个新会话,让 VikingBot 根据这些记忆准备评审提纲。完成后,你可以查看记忆正文、核对召回来源,并确认回答是否沿用了项目约定。++## 适用场景++| 场景 | 可以保留的信息 | 后续如何使用 |+| --- | --- | --- |+| 个性化回答 | 常用语言、摘要格式、表达偏好 | 按用户熟悉的方式组织回答 |+| 项目协作 | 项目背景、已有决定、文件命名约定 | 开启新会话后继续处理项目任务 |+| 经验复用 | 解决问题时有效的方法和注意事项 | 遇到类似问题时检索已有经验 |++记忆会根据输入内容和服务端配置提取、整理。同一段对话可能产生多条记忆,也可能更新已有记忆;具体分类见[记忆类型](../api/16-memory.md#内置记忆类型)。++<a id="准备独立实验"></a>++## 准备环境++先按[快速开始](02-quickstart.md)连接服务,完成 [VikingBot](11-vikingbot.md) 的启用与连接配置。服务端需要可用的记忆提取和 Embedding 模型,VikingBot 需要能够调用 OpenViking 检索工具。++本流程通过 CLI 保存会话,再由 VikingBot 召回。两者应连接同一服务、使用同一用户身份,让新会话能够访问前面保存的记忆。本例使用用户自身的记忆空间,项目插件的身份与 Peer 范围可参考[集成能力对照](../agent-integrations/16-capability-reference.md)。++以下操作会调用模型,并将虚构项目的信息写入当前用户的记忆。可使用专门的演示账号体验,便于之后清理。会话名称使用下方示例值即可;若已经使用过这些名称,请更换名称并同步修改后续命令。++<a id="会话-a-保存约定"></a>++## 保存项目背景++先创建一个会话,用于记录海岬项目的评审约定。`--no-auto-commit` 将提交时机交给后面的手动操作:++```bash+ov session new --session-id cape-docs-a --no-auto-commit+```++向这个会话写入一条用户消息,说明希望在后续评审中复用的背景:++```bash+ov session add-message cape-docs-a --role user --content "这是虚构的海岬项目。我们每次评审只讨论两项风险,摘要使用中文三条要点,交付文件统一命名为 cape-review.csv。以后准备海岬评审时请遵循这些约定。"+```++提交会话,让服务归档消息并开始提取记忆:++```bash+ov session commit cape-docs-a+```++记录返回的 `task_id` 和 `archive_uri`。`accepted` 表示消息已归档、记忆提取已进入后台处理;接下来查询任务,确认记忆是否生成。++## 查看生成的记忆++将 `<task_id>` 替换为提交时返回的任务 ID:++```bash+ov task status <task_id>+```++状态为 `completed` 后读取结果。可以每隔 5 秒检查一次,先观察最多 2 分钟;仍在运行时保留任务 ID,稍后继续。若状态为 `failed` 或 `cancelled`,先查看任务错误或取消原因,再决定后续操作。++将 `<archive_uri>` 替换为提交时返回的归档 URI,读取本次记忆变更:++```bash+ov read "<archive_uri>/memory_diff.json"+```++在 `operations.adds` 或 `operations.updates` 中找到 `uri`,复制该值读取记忆正文:++```bash+ov read "<记忆 URI>"+```++核对正文是否保留了三个要点:每次评审讨论两项风险、摘要使用三条中文要点、交付文件名为 `cape-review.csv`。记忆的文件名和分类可能不同,以实际返回的 URI 为准。++<a id="会话-b-使用背景"></a>++## 在新会话中使用++使用新的 VikingBot 会话 ID,只提供项目名称和新任务。具体的风险数量、摘要格式和文件名由 Agent 从已保存的记忆中获取:++```bash+ov chat --session cape-docs-b -m "请检索已保存的海岬项目记忆,按项目约定准备下一次评审提纲,并说明建议的交付文件名。请引用使用的记忆 URI。"+```++核对回答是否包含两项风险的讨论位置、三条中文摘要要点,以及文件名 `cape-review.csv`。本次输入没有提供具体风险,提纲可将风险内容标为待补充。++结合工具调用输出或 Bot 日志,检查保存、召回和使用三个环节:++| 环节 | 核对内容 |+| --- | --- |+| 保存 | `memory_diff.json` 记录了变更,记忆正文包含项目约定 |+| 召回 | 检索工具结果包含对应的记忆 URI 和内容 |+| 使用 | 新回答遵循约定,引用的记忆 URI 与检索结果一致 |++再开启一个新会话,查看回答是否能保持与当前任务相关:++```bash+ov chat --session cape-docs-c -m "17 加 25 等于多少?"+```++这个问题的答案应为 42,回答无需加入海岬项目的评审格式或文件名。++<a id="定位问题"></a>++## 常见问题++| 遇到的情况 | 检查方式 |+| --- | --- |+| 提交返回 `skipped` | 本次没有可归档消息;用 `ov session get cape-docs-a` 检查消息是否已添加或已提交 |+| 任务失败或一直未完成 | 查看任务状态和错误信息,检查模型连接及服务端记忆配置 |+| 没有生成预期记忆 | 核对原消息、`memory_diff.json` 和生效的提取策略;相同信息也可能已保存在已有记忆中 |+| 已保存但新会话没有召回 | 检查 CLI 与 VikingBot 的服务地址、用户身份、记忆范围和检索工具是否可用 |+| 已召回但回答没有使用 | 查看工具返回内容和 Agent 指令,让 Agent 依据召回的记忆修订回答 |++## 继续使用++换成自己的项目背景或回答偏好后,可以用[效果评估](06-evaluate.md)记录相关任务和无关任务的表现。接入已有 Agent 时,各插件的会话捕获、提交与召回方式见[集成能力对照](../agent-integrations/16-capability-reference.md);会话参数和变更记录格式见[会话 API](../api/05-sessions.md)。++体验结束后,可在 Studio 中根据本次 `memory_diff.json` 确认演示记忆,再按需清理会话和记忆。若本次更新了已有记忆,先核对修改内容,保留仍需使用的信息。diff --git a/docs/zh/getting-started/10-skills.md b/docs/zh/getting-started/10-skills.mdnew file mode 100644index 000000000..db2eacbb1--- /dev/null+++ b/docs/zh/getting-started/10-skills.md@@ -0,0 +1,107 @@+# 技能使用++技能(Skill)将一项任务的操作方法、输出格式和检查要求整理成可复用的说明。对于反馈整理、报告撰写、代码审查等重复任务,Agent 可以读取技能,按照其中的要求处理不同输入。++OpenViking 负责保存和检索技能,Agent 负责读取说明并执行任务。本节以“反馈简报”为例,带你添加一个技能,再通过 VikingBot 处理两组反馈,查看同一套工作方法如何在不同会话中复用。++## 准备环境++开始前,请准备以下环境:++- **OpenViking 服务和 CLI**:按照[快速开始](02-quickstart.md)完成连接配置。+- **VikingBot**:确认服务已启用 VikingBot,并完成模型配置。安装与配置方法见 [VikingBot](11-vikingbot.md)。本节通过 `ov chat` 调用模型生成简报,会产生相应的模型调用费用。+- **技能目录权限**:本节将技能添加到共享目录 `viking://agent/skills/`,当前账号需要具备写入权限。CLI 和 VikingBot 应连接同一服务,并使用能够访问该技能的账号。++下载[反馈简报技能包](/quickstart/feedback-brief-v1.zip),在终端中进入下载文件所在的目录。包内包含 `SKILL.md` 和中英文示例输入,可以直接用于后续操作。++## 添加样例技能++解压技能包,得到 `feedback-brief` 目录:++```bash+unzip feedback-brief-v1.zip+```++将整个目录添加到 OpenViking。`--wait` 会等待技能处理完成,便于接下来查看内容。++```bash+ov add-skill ./feedback-brief -p viking://agent/skills --wait+```++查看技能列表,确认其中包含 `feedback-brief`:++```bash+ov skills list+```++读取 `SKILL.md`,了解 Agent 将遵循的要求:++```bash+ov read viking://agent/skills/feedback-brief/SKILL.md+```++这个技能要求 Agent 只使用当前输入中的信息,并按输入语言生成以下内容:++| 内容 | 要求 |+| --- | --- |+| 已知事实 | 保留输入中的事实和数字,标注输入编号 |+| 建议行动 | 用表格列出行动、负责人和依据,将建议与事实区分开;负责人缺失时标为“未指定” |+| 待确认 | 列出缺失的信息,日期缺失时标为“尚未确定” |++技能会让 Agent 在对话中返回简报。完成导入后,接下来通过对话让 Agent 读取并使用它。如果已添加过这个样例,可以确认技能内容后直接继续。++<a id="用第一组输入"></a>++## 生成反馈简报++第一组反馈包含一个耗时数据、一项改进建议和一个待确认的日期。在新会话中提供反馈,并指定技能路径,让 VikingBot 按照技能要求整理:++```bash+ov chat --session feedback-skill-a -m "请先发现并读取 viking://agent/skills/feedback-brief/SKILL.md,按技能整理以下输入,只在对话中返回结果:反馈 A:离线导出耗时 8 分钟,试点管理员建议增加进度提示;上线日期未确定。"+```++简报应包含“已知事实”“建议行动”“待确认”三部分。结合输入核对以下内容:++- “离线导出耗时 8 分钟”保留在事实中,并标注输入编号 A。+- “增加进度提示”作为建议行动呈现,负责人标为“未指定”。+- 上线日期保持为“尚未确定”,列入待确认事项。++通过工具调用记录或服务日志,还可以确认 VikingBot 是否读取了 `SKILL.md`。这一步用于核对简报是否基于指定技能生成。++## 换一组输入++在另一个会话中提供第二组反馈,观察 Agent 能否复用同样的整理方法。使用新的会话可以避免上一组反馈影响本次结果;重复体验时,可以将示例中的会话名换成新的名称。++```bash+ov chat --session feedback-skill-b -m "请先发现并读取 viking://agent/skills/feedback-brief/SKILL.md,按技能整理以下输入,只在对话中返回结果:反馈 B:登记模板缺少问题分类字段;有 3 条重复反馈,负责人未指定。"+```++这份简报应保留“缺少问题分类字段”和“3 条重复反馈”,标注输入编号 B,并将负责人标为“未指定”。建议行动可以包括补充分类字段、合并重复反馈,同时注明它们是基于输入提出的建议。++对照两份结果:内容应随输入变化,三部分结构、行动表和依据标注应保持一致。你也可以查看[简报示例与技能读取记录](/quickstart/skill-output-zh-v1.txt),了解输出形式。++## 检查结果++| 检查项 | 预期结果 |+| --- | --- |+| 技能已添加 | 技能列表中存在 `feedback-brief`,且 `SKILL.md` 可读取 |+| Agent 已读取技能 | 工具调用记录或日志中包含对 `SKILL.md` 的读取 |+| 工作方法可复用 | 两份简报都包含约定的三部分结构、行动表和输入编号 |+| 内容符合输入 | 数字与事实保持准确,建议有明确标注,缺失信息保持为待确认 |++模型生成的措辞可能有所不同,核对时以输入事实和技能要求为准。++## 常见问题++| 现象 | 处理方法 |+| --- | --- |+| 技能未出现在列表中 | 查看导入命令的处理结果;如果导入报错,按错误信息检查服务连接、目录权限或模型配置 |+| CLI 能读取技能,VikingBot 无法访问 | 核对两者连接的服务和账号,并确认 VikingBot 使用的身份能够读取该目录 |+| 对话中没有技能读取记录 | 确认提示词中的技能路径可读取,并检查 VikingBot 的 OpenViking 工具配置 |+| 简报结构或内容不符合要求 | 先确认 Agent 已读取技能,再指出具体差异,请它按技能要求修订 |++## 继续使用++你可以把自己的工作方法整理为 `SKILL.md`,添加到 OpenViking 后供 Agent 复用。技能格式、更新方式以及其他客户端的接入方法,见[技能参考](../api/04-skills.md)。++如果希望让 Agent 使用技能生成可持续维护的知识库文件,可以继续阅读[上下文编译](13-compile.md)。体验结束后,如需清理样例,可在 Studio 中确认 `feedback-brief` 是本次添加的技能后删除。diff --git a/docs/zh/getting-started/11-vikingbot.md b/docs/zh/getting-started/11-vikingbot.mdnew file mode 100644index 000000000..3c555baf7--- /dev/null+++ b/docs/zh/getting-started/11-vikingbot.md@@ -0,0 +1,143 @@+# VikingBot++VikingBot 是 OpenViking 内置的 AI Agent,可以接收任务、调用模型和工具,并结合 OpenViking 中的资料、记忆和技能生成回答。你可以通过命令行与它对话,整理任务、查询项目资料,或按照技能完成重复工作。++本节采用本机运行方式,带你启动 VikingBot、整理一份任务清单,再在同一会话中继续追问。完成后,你可以确认服务连接正常、模型能够回复,以及后续对话能沿用已有上下文。++## 准备环境++开始前,请准备以下环境:++| 准备项 | 用途与准备方式 |+| --- | --- |+| uv 和 Python | 安装并运行 OpenViking 与 VikingBot。以下命令使用 Python 3.13,安装方法见[准备本地运行环境](02-quickstart.md#准备本地运行环境) |+| Node.js/npm | 安装 `ov` CLI,安装方法见[安装 Node.js](02-quickstart.md#安装-node-js) |+| 模型访问凭据 | 准备 Embedding 模型和支持工具调用的 VLM 的模型名、端点及 API Key,开通方法见[模型开通指南](../guides/02-volcengine-purchase-guide.md) |++VikingBot 默认使用 OpenViking 配置中的 VLM,Embedding 模型用于后续资料检索。使用 Agent Plan 时,选择套餐支持的模型与端点;模型调用按所选服务计费。++如果已经按快速开始启动了带 VikingBot 的本机服务,可以直接进入[连接 CLI](#连接-cli)。++<a id="启动与连接"></a>++## 启动服务++安装 OpenViking 和 VikingBot,让本机具备资料管理和 Agent 对话能力:++```bash+uv tool install --python 3.13 "openviking[bot]" --upgrade+```++首次使用时,运行初始化向导,选择本机访问并填写准备好的模型信息。已有配置时,可以直接进行配置检查。++```bash+openviking-server init+```++检查模型和服务配置。如果报告错误,按提示修正对应项目后再次检查:++```bash+openviking-server doctor+```++已有服务启用了 API Key 认证时,可先按[身份认证](../guides/04-authentication.md)为 Bot 配置连接身份,并为 CLI 准备相应的 User/Admin Key。++检查通过后,一起启动 OpenViking 和 VikingBot。`--with-bot` 会启用 Agent 对话入口;保持这个终端运行,后续命令在另一个终端中执行。如果本机服务已在运行但尚未启用 Bot,可先在原终端停止服务,再使用下面的命令启动。++```bash+openviking-server --with-bot+```++本节后续命令使用默认地址 `http://127.0.0.1:1933`。++## 连接 CLI++在新终端中安装 CLI。已有可用的 `ov` 时,可以直接配置连接。++```bash+npm install -g @openviking/cli+```++将界面语言设为中文,再打开连接向导:++```bash+ov language zh-CN+ov config+```++选择自定义(Custom)连接,URL 填写 `http://127.0.0.1:1933`,默认本机模式的密钥留空;已启用认证时,填写准备好的 User/Admin Key。保存并设为当前配置;已有对应连接时,直接选择它即可。更多连接方式见 [CLI 入门](05-cli-setup.md)。++先确认 CLI 能连接资料服务:++```bash+ov health+```++结果中应包含 `healthy: true`。接着检查 Bot 对话入口:++```bash+curl -f http://127.0.0.1:1933/bot/v1/health+```++返回 `status: healthy` 后,可以开始对话。接下来的任务会进一步确认模型能否正常生成回复。++<a id="完成任务并追问"></a>++## 完成一次任务++将一份虚构的任务清单交给 VikingBot,让它按完成状态整理。`--session` 指定本次会话,后续使用同一名称可以继续讨论这份清单。重复体验时,可将示例中的会话名换成新的名称。++```bash+ov chat --session bot-review-v1 -m "以下是虚构任务清单:资料导入已完成,来源核对待完成,演示排练待完成。请整理为简短的已完成和待完成清单。"+```++回复应将“资料导入”列为已完成,将“来源核对”和“演示排练”列为待完成。你可以对照输入检查状态是否保留准确;具体措辞和排版可以不同。++## 继续追问++保持同一个 `--session`,请 VikingBot 根据已有清单建议下一步:++```bash+ov chat --session bot-review-v1 -m "沿用刚才的清单,建议先完成哪一步,并用一句话说明理由。"+```++这次无需重新提供任务清单,回复应围绕“来源核对”和“演示排练”提出建议。例如,可以建议先核对来源,以便在演示前确认内容准确。建议顺序可以不同,依据应来自前一轮的待办事项。++同一会话中的追问会使用已有对话上下文。使用新的会话名称可以开始另一段对话;希望在不同会话中复用项目背景或偏好时,可继续[记忆使用](09-memory.md),了解记忆的保存与召回。++## 检查结果++| 检查项 | 预期结果 |+| --- | --- |+| 服务连接 | `ov health` 和 Bot 健康检查均成功 |+| 单次任务 | 回复准确保留三项任务及其完成状态 |+| 连续对话 | 追问回复使用前一轮的待办信息,并说明建议理由 |++如果回复遗漏了某项任务或改变了完成状态,可以指出差异,请 VikingBot 根据原始清单修订。++## 常见问题++| 现象 | 处理方法 |+| --- | --- |+| 安装后找不到 `openviking-server` 或 `ov` | 重新打开终端;仍不可用时,按 uv 或 npm 的安装说明检查命令路径 |+| 提示端口已被占用 | 确认是否已有本机服务;需要启用 Bot 时,在原服务终端停止后再带 `--with-bot` 启动 |+| `ov health` 连接失败 | 在 `ov config` 中确认当前连接地址,并检查服务终端是否仍在运行 |+| Bot 健康检查返回 `503` | 确认启动时启用了 `--with-bot`,并查看服务日志中的 Bot 启动信息 |+| 健康检查成功,但模型调用失败 | 根据错误信息检查模型名、端点、凭据和套餐支持情况 |+| 追问没有沿用清单 | 确认两次命令使用相同的 `--session` 和 CLI 连接身份,并确认第一轮已返回完整回复 |++## 继续使用++连接和对话正常后,可以让 VikingBot 使用 OpenViking 中的上下文完成任务:++| 目标 | 下一步 |+| --- | --- |+| 根据项目资料回答,并核对来源 | [资料检索](08-resources.md) |+| 在新会话中复用背景和偏好 | [记忆使用](09-memory.md) |+| 按固定工作方法处理不同输入 | [技能使用](10-skills.md) |++接入飞书等聊天平台、独立调试或配置模型时,可查看 [VikingBot 指南](../guides/17-vikingbot.md);在程序中发送消息可查看 [Bot API](../api/24-vikingbot.md)。VikingBot Gateway 承接 Bot 消息和聊天渠道;为兼容客户端提供模型请求入口的能力见 [OpenViking 网关](12-gateway.md)。++## 结束体验++保留会话名称,便于之后继续讨论。本机服务可在运行终端按 Ctrl+C 停止,停止后 CLI 对话入口也会随之关闭。需要清理测试会话时,可在 Studio 中确认对应会话后删除。diff --git a/docs/zh/getting-started/12-gateway.md b/docs/zh/getting-started/12-gateway.mdnew file mode 100644index 000000000..2cd94645d--- /dev/null+++ b/docs/zh/getting-started/12-gateway.md@@ -0,0 +1,201 @@+# 网关接入++OpenViking 网关连接客户端与模型服务,在转发请求时补充相关记忆,并将对话保存到 OpenViking,供后续提取和复用。对于支持自定义 Base URL 和 API Key 的兼容客户端,可以通过修改连接配置接入记忆能力。++本节使用一个 Python 样例完成 **连接网关 → 发送对话 → 查看记忆 → 在新会话中使用**:先告诉模型虚构“山岚项目”的评审约定,再开启另一段对话,查看回答是否沿用这些约定。++::: info Beta+OpenViking 网关目前处于 Beta 阶段,后续可能调整接口和配置方式。升级时,请结合更新说明核对现有接入配置。+:::++## 准备环境++本节采用本机服务,开始前请准备:++- **OpenViking 服务**:按[快速开始](02-quickstart.md#本地服务)完成安装和模型配置,确保 Embedding 和 VLM 可用。网关包含在 OpenViking 中,启用后与资料服务共用端口。+- **Python 3**:用于运行样例,安装方法见[准备本地运行环境](02-quickstart.md#准备本地运行环境)。样例只使用 Python 标准库。+- **CLI 连接**:按 [CLI 入门](05-cli-setup.md)连接本机服务,供后续查看会话和记忆。CLI 与网关密钥应对应同一 OpenViking 用户;默认本机模式使用 `default` 用户。+- **上游模型**:准备支持 **OpenAI Chat Completions** 协议的模型服务地址、模型名和 API Key,供本节样例发送请求。++以下操作会调用上游模型,并把虚构项目约定写入当前用户的记忆;记忆提取也会调用服务端配置的模型,按所选服务计费。远程服务的身份与权限配置见[网关快速上手](../gateway/02-quickstart.md#remote-server-api-keys)。++## 开启本机网关++运行初始化向导,在已有配置的菜单中选择 **Update gateway**,启用网关:++```bash+openviking-server init+```++保存配置后,在原服务终端停止服务,再使用原来的启动命令启动。例如:++```bash+openviking-server+```++如果原服务还启用了 VikingBot,启动时保留 `--with-bot` 等已有参数。++打开 [Studio](http://127.0.0.1:1933/studio/),在侧边栏选择 **OpenViking 网关**。本机网关地址为 `http://127.0.0.1:1933/gateway`,后续样例会使用这个地址。++以 Studio 显示的网关地址为准。下方截图使用本机端口 `1934`;如果你的服务也使用其他端口,请同步替换后续命令中的地址。点击截图可查看原图。++## 配置模型与记忆++在 Studio 中依次准备上游、上下文配置和网关密钥:++### 配置上游++上游是网关转发请求时使用的模型服务。在“上游”标签页,选择或添加支持 **Chat Completions** 的上游,填写模型服务地址和凭据,并通过页面的测试功能确认连接或模型可用。++网关可能已从服务端 VLM 配置导入上游。可以直接检查并使用匹配的配置;导入的 Coding Plan 上游按页面提示完成确认。网关按请求协议转发,本节样例使用 Chat Completions,所选上游也需要支持该协议。++在上游编辑页选择 **Chat Completions**,根据模型服务提供的信息填写 **Base URL**,并核对下方显示的完整请求地址。++[](/quickstart/gateway/upstream-zh.jpg)++### 设置上下文++上下文配置决定如何召回记忆和保存对话。在“上下文配置”标签页新建一份配置,例如命名为“山岚项目体验”,使用以下设置:++| 设置 | 本节取值 | 作用 |+| --- | --- | --- |+| 召回记忆 | 开启 | 为新消息补充相关记忆 |+| 检索范围 | 记忆 | 使用已保存的项目约定 |+| 保存对话 | 开启 | 将对话写入 OpenViking,供后续提取记忆 |+| 最新回复等待时长 | 30 秒 | 对话空闲后保存最后一轮并提交会话 |+| 保留最近消息 | 0 | 让这段短对话的消息参与本次归档与记忆提取 |+| 显示召回摘要 | 开启 | 在回复中查看补充记忆的摘要 |+| OpenViking 工具 | 关闭 | 通过自动召回和保存完成本次流程 |++在配置编辑页选择“召回记忆”,开启“显示召回摘要”,并在“检索范围”中勾选“记忆”。++[](/quickstart/gateway/recall-zh.jpg)++接着选择“保存对话”,将“最新回复等待时长”设为 **30 秒**,“保留最近消息”设为 **0**。完成后,在“OpenViking 工具”分组关闭工具并保存配置。++[](/quickstart/gateway/capture-zh.jpg)++保存配置后,用它签发下面的密钥并开始新对话。配置修改对之后开始的对话生效;日常使用时,可以按任务需要调整等待时间和消息保留策略,详见[上下文配置](../gateway/08-context-profiles.md)。++### 签发密钥++在“密钥”标签页签发一把用于本次体验的网关密钥,选择刚才的上下文配置和上游。复制弹窗显示的完整 `ovgw_…` 值,供样例连接使用;完整密钥仅在签发时显示一次。++在签发表单中填写名称,核对“给谁用”,并选择已准备的上下文配置与上游。如果上游显示“已拦截”,先返回上游页按提示核对凭据和套餐适用条件,确认可用后再发送请求。++[](/quickstart/gateway/key-zh.jpg)++客户端使用这把网关密钥访问模型,模型服务商的 API Key 保存在上游配置中。查看会话和记忆的 `ov` CLI 继续使用原有的 OpenViking 连接配置。++## 发送两轮对话++下载 [Python 样例](/quickstart/gateway-demo-v1.zip),在终端中进入下载目录并解压:++```bash+unzip gateway-demo-v1.zip+```++解压后得到 `gateway-demo.py`。下面的命令适用于 macOS / Linux 终端,先设置网关地址和模型名。将 `<上游模型 ID>` 替换为刚才上游中可用的模型名:++```bash+export GATEWAY_URL=http://127.0.0.1:1933/gateway+export GATEWAY_MODEL='<上游模型 ID>'+```++运行下面的命令后输入网关密钥并回车,输入过程不会显示密钥字符:++```bash+read -r -s GATEWAY_KEY+export GATEWAY_KEY+```++发送两轮对话,向模型提供山岚项目的约定:评审固定检查四项风险、报告使用 Markdown、文件名为 `mist-review.md`。++```bash+python3 gateway-demo.py capture --language zh --run v1+```++样例先发送约定,再携带完整的第一轮消息发送“谢谢”。终端应依次显示两次回复。第二次请求中的历史用于保存第一轮;最后一轮会在对话空闲达到配置的等待时长后保存并提交。++在 Studio 的“请求日志”中确认两次请求成功,再到“会话”页面找到包含山岚项目约定的 `gateway-…` 会话。以服务实际生成的会话 ID 为准,后续 CLI 检查使用这个 ID。++<a id="等待记忆并开启新会话"></a>++## 查看生成的记忆++停止发送消息后,网关会按配置等待 30 秒再提交最后一轮,后台记忆提取还需要额外时间。可以每隔 10 秒查看一次,先等待最多 5 分钟。仍在处理时保留会话和任务 ID,稍后继续检查;出现失败或取消状态时,查看对应错误或原因。++先列出会话,并将 `<gateway-session-id>` 替换为 Studio 中找到的会话 ID,查看提交情况:++```bash+ov session list+ov session get <gateway-session-id>+```++再查看记忆提取任务。找到 `resource_id` 与该会话 ID 对应的任务,将其 `task_id` 填入下一条命令:++```bash+ov task list --task-type session_commit+ov task status <task_id>+```++任务状态为 `completed` 后,从任务结果中复制 `archive_uri`,查看记忆变更:++```bash+ov read "<archive_uri>/memory_diff.json"+```++从 `operations.adds` 或 `operations.updates` 中复制记忆的 `uri`,读取正文:++```bash+ov read "<记忆 URI>"+```++确认正文包含四项风险、Markdown 格式和 `mist-review.md` 三项约定后,再开启新会话。记忆的名称和分类以实际生成结果为准。++## 在新会话中使用++在同一终端中运行召回阶段,沿用网关地址、密钥和模型设置:++```bash+python3 gateway-demo.py recall --language zh --run v1+```++这条命令启动新的 Python 进程,并使用不同的会话标识。它只发送“按已保存的山岚项目约定准备评审清单,并给出交付文件名”的任务,具体约定由网关从记忆中补充。++查看回复是否包含四项风险的检查位置、使用 Markdown,并给出文件名 `mist-review.md`。样例没有提供具体风险内容,回答可以列为待补充,或明确标注为建议。++<a id="检查与收尾"></a>++## 检查结果++结合记忆正文、回复中的召回摘要和 Studio 请求日志,分别核对以下结果:++| 环节 | 预期结果 |+| --- | --- |+| 请求 | 两次模型请求成功,终端收到回复 |+| 保存 | 对应会话及其归档中包含项目约定 |+| 提取 | 任务完成,记忆正文保留三项约定 |+| 召回与使用 | 新会话有召回记录,回答遵循约定 |++回复措辞可以不同。核对时既要看记忆是否被召回,也要看回答是否使用了其中的信息。++## 常见问题++| 现象 | 处理方法 |+| --- | --- |+| 请求失败或模型不可用 | 检查网关地址、密钥绑定的上游、模型名和 Chat Completions 协议,并查看请求日志 |+| Studio 中找不到会话 | 检查保存对话开关,确认当前用户与网关密钥绑定用户一致,并查看请求的保存状态 |+| 有会话但没有生成记忆 | 检查空闲等待时间、保留最近消息数和 `session_commit` 任务状态 |+| 已生成记忆但没有召回 | 核对密钥绑定的用户、上下文配置和检索范围;修改配置后用新会话重试 |+| 有召回记录但回答遗漏约定 | 对照记忆正文和回复,请模型根据已保存约定修订 |++更多问题见[网关排障](../gateway/12-troubleshooting.md)。++## 继续使用++完成后,可以按[客户端接入](../gateway/03-connect-clients.md)将自己的应用连接到网关。远程服务和团队配置见[网关快速上手](../gateway/02-quickstart.md)。++再次体验时,为两条样例命令使用相同的新 `--run` 值,以创建新的一组会话。相同用户的已有记忆仍可被召回;如需从空白记忆开始,可使用单独的演示用户。++体验结束后,可在 Studio 中撤销本次网关密钥,并根据会话和 `memory_diff.json` 按需清理演示数据。若本次更新了已有记忆,先核对修改内容,保留仍需使用的信息。diff --git a/docs/zh/getting-started/13-compile.md b/docs/zh/getting-started/13-compile.mdnew file mode 100644index 000000000..003d6f909--- /dev/null+++ b/docs/zh/getting-started/13-compile.md@@ -0,0 +1,61 @@+# 上下文编译++将灯塔项目的四份资料整理成一份小型 Wiki,打开正文核对来源和未知事项。++## 认识 LLM Wiki++LLM Wiki 利用大模型,将分散在文档、会议记录和反馈中的信息,整理成按主题组织、相互链接的 Markdown 知识库。同一项目或概念的相关内容可以汇集到一页,通过导航页浏览,并保留指向原始资料的引用,方便读者和 Agent 查阅、核对与复用。++例如,灯塔项目的目标、反馈流程和准备事项分布在四份资料中。编译后,一篇项目页面就可以串起这些信息,标明尚未确定的日期和预算,并为关键事实附上来源。后续了解项目时,可以先阅读这篇页面,再沿引用查看细节。++OpenViking 通过 LLM Wiki Skill 定义整理方式,由 Compile Runtime 读取来源并生成页面。生成的 Wiki 可继续用于阅读和检索;关键结论仍需结合原始资料核对。下面用灯塔资料完成一次编译。++## 准备来源与技能++本页需要已配置 Compile Runtime 的服务。本机默认使用已安装 `openviking[bot]` 并以 `--with-bot` 启动的 VikingBot,模型和连接配置见[快速开始](02-quickstart.md)。++先完成[资料检索](08-resources.md#准备资料)的资料导入,确认 `viking://resources/onboarding-zh-v1` 可读取。下载 [Wiki Skill v1](/quickstart/llm-wiki-v1.zip),安装到有写权限的共享技能目录:++```bash+ov add-skill ./llm-wiki-v1.zip -p viking://agent/skills --wait+ov read viking://agent/skills/llm-wiki/SKILL.md+```++这个样例包包含项目自带的 LLM Wiki Skill。编译将调用模型并在下面的新目录中写入产物;重复体验时使用新的目标目录名。++## 提交编译++```bash+ov compile --from viking://resources/onboarding-zh-v1 \+ --to viking://resources/onboarding-wiki-v1 \+ --skill viking://agent/skills/llm-wiki \+ --instruction "请用中文生成一个 index.md 和一篇 entity/lighthouse.md。正文围绕隔离网络中的反馈试点,综合项目、反馈和会议资料,保留完整来源 viking:// URI,明确未知日期。仅在目标目录写入。"+```++记录返回的 `cmp_...` 任务 ID,查询进度:++```bash+ov task status <cmp_task_id>+```++每隔 5 秒查看一次,先观察最多 5 分钟。状态为 `completed` 后读取产物;仍在运行时可稍后再查,或用 `ov task cancel <cmp_task_id>` 请求取消。失败时查看任务错误和 Compile Runtime 配置。++编译完成后,目标目录中应包含导航页和项目正文。你可以参考 [Wiki 正文示例](/quickstart/wiki-output-zh-v1.txt),了解内容组织和来源引用方式,再按下文核对生成结果。++## 打开正文++```bash+ov tree viking://resources/onboarding-wiki-v1+ov read viking://resources/onboarding-wiki-v1/index.md+ov read viking://resources/onboarding-wiki-v1/entity/lighthouse.md+```++如果实际文件名与指令不同,可从 `tree` 和导航页找到正文 URI。核对以下内容:隔离网络条件、离线安装包与本地目录、每周五导出反馈、模板与演练准备,以及尚未确定的日期和预算。打开正文引用的来源,逐项确认依据。++| 情况 | 检查方向 |+| --- | --- |+| Runtime 不可用 | 服务端是否安装 Bot 依赖并启用编译执行端 |+| 找不到来源或 Skill | URI、读权限与前置处理结果 |+| 正文缺少依据 | 检查实际读取记录和来源引用,补充编译指令后使用新目标重试 |++完成标志是一篇可阅读、可导航且关键事实有来源支持的正文。文件结构、页面类型和可视化见 [LLM Wiki 示例](../context-compilation/02-llm-wiki.md)。清理时确认演示目标目录,保留需要的产物后在 Studio 中删除。diff --git a/docs/zh/getting-started/14-versions.md b/docs/zh/getting-started/14-versions.mdnew file mode 100644index 000000000..589db865c--- /dev/null+++ b/docs/zh/getting-started/14-versions.md@@ -0,0 +1,58 @@+# 版本管理++在独立演示目录中保存两个版本、查看差异,并将文件恢复为第一版。连接准备见 [CLI 入门](05-cli-setup.md),模型和索引处理会沿用服务端配置。++## 保存第一版++```bash+ov mkdir viking://resources/onboarding-versions-v1+ov write viking://resources/onboarding-versions-v1/plan.md --mode create --content "反馈每周五导出。" --wait+ov snapshot commit -m "onboarding v1" --paths viking://resources/onboarding-versions-v1 -o json+```++记录返回的 `commit_oid` 为 `<v1>`。本页只操作该演示目录;重复体验时可以换一个新目录名。快照由 `snapshot commit` 显式保存,`session commit` 用于会话归档与记忆提取。++## 修改并比较++```bash+ov write viking://resources/onboarding-versions-v1/plan.md --content "反馈每周一导出。" --wait+ov snapshot commit -m "onboarding v2" --paths viking://resources/onboarding-versions-v1 -o json+```++记录第二个 `commit_oid` 为 `<v2>`,将下面的占位符替换为实际 ID:++```bash+ov snapshot show <v1> --path viking://resources/onboarding-versions-v1/plan.md+ov snapshot diff viking://resources/onboarding-versions-v1/plan.md --from <v1> --to <v2>+```++旧版应为“每周五”,差异应显示改为“每周一”。++## 预览并恢复++```bash+ov snapshot restore <v1> viking://resources/onboarding-versions-v1 --dry-run -o json+```++核对计划中的新增、修改和删除范围,确认都属于本次演示目录。恢复会将范围内的差异写回工作区;有需要保留的新修改时,先另行保存。确认计划后执行:++```bash+ov snapshot restore <v1> viking://resources/onboarding-versions-v1 -m "restore onboarding v1" -o json+ov read viking://resources/onboarding-versions-v1/plan.md+ov snapshot log --paths viking://resources/onboarding-versions-v1 -o json+```++正文应恢复为“每周五”,历史中可看到恢复产生的新提交。`applied` 表示已应用,`noop` 表示选定源文件树与当前 HEAD 相同;可结合正文读取核对工作区状态。++## 检查检索状态++恢复会按需要安排语义和向量重建。将恢复结果中的 `task_id` 填入下方命令,任务完成后验证检索:++```bash+ov task status <task_id>+ov find "反馈什么时候导出?" --uri viking://resources/onboarding-versions-v1+```++如果相关处理尚未完成,继续查询对应任务,完成后再验证。先以 2 分钟为观察窗口,保留仍在运行的任务 ID 供稍后查看。++快照保存选定范围内的源文件树,权限使用当前 ACL,向量索引按恢复后的内容重建。账号排除规则与系统剪枝会影响保存范围,详见[版本参考](../api/11-snapshot.md)和[快照指南](../guides/15-snapshot.md)。演示目录可在 Studio 中确认后清理;历史保留规则见快照指南。diff --git a/docs/zh/getting-started/15-transfer.md b/docs/zh/getting-started/15-transfer.mdnew file mode 100644index 000000000..f29653b76--- /dev/null+++ b/docs/zh/getting-started/15-transfer.md@@ -0,0 +1,153 @@+# 导入导出++将一份资料目录导出为 OVPack,再导入到新的父目录或另一套 OpenViking 服务,核对文件、元数据和检索结果。++<a id="连接实验账号"></a>++## 连接服务++使用管理员提供的用户或管理员 API Key 配置 CLI,连接 OpenViking 服务。OVPack 导入导出要求服务端启用 API Key 认证,并配置 `server.root_api_key`。++如需在本机搭建服务,可使用独立的配置文件和存储目录,配置模型,将 `server.auth_mode` 设为 `api_key`,并设置 `server.root_api_key`。启动服务并创建账号后,将返回的 `user_key` 填入 CLI 连接配置。具体步骤见[API Key 配置](../guides/04-authentication.md#方案一-api-key)和 [CLI 入门](05-cli-setup.md)。使用新账号时,先在该账号下导入下方样例资料。++## 准备来源++连接服务后,先完成[资料检索](08-resources.md#准备资料)中的导入步骤。本例来源为 `viking://resources/onboarding-zh-v1`,需要来源读权限和目标父目录写权限。++```bash+ov tree viking://resources/onboarding-zh-v1+ov export viking://resources/onboarding-zh-v1 ./lighthouse.ovpack+```++`lighthouse.ovpack` 是所选目录的内容包,包含源文件、语义侧边文件和可迁移索引标量。本页使用默认导出方式,导入时重新生成向量,会调用目标服务的 Embedding 模型。全账号备份与恢复见 [OVPack 参考](../api/14-ovpack.md)。++## 导入新位置++```bash+ov mkdir viking://resources/onboarding-transfer-v1+ov import ./lighthouse.ovpack viking://resources/onboarding-transfer-v1 --vector-mode recompute+```++第二个参数是**目标父目录**。保存返回的实际 root URI,并用它执行下一步。本例通常得到 `viking://resources/onboarding-transfer-v1/onboarding-zh-v1`。++默认冲突策略为 `fail`。若目标 root 已存在,可以选择新的演示父目录;`overwrite` 会替换已有 root,`skip` 会保留已有 root。使用重复演示时的新目录,便于比较前后结果。++## 核对内容和索引++```bash+ov tree viking://resources/onboarding-transfer-v1/onboarding-zh-v1+ov read viking://resources/onboarding-transfer-v1/onboarding-zh-v1/project/project.md+ov read viking://resources/onboarding-transfer-v1/onboarding-zh-v1/meeting/meeting.md+ov wait+```++核对四份源文件的相对路径、正文,以及包内保留的摘要和概览。导入返回后向量处理可能仍在进行,使用 `ov wait` 等待队列处理。它也可能等待服务中的其他排队工作;如果请求超时,可用 `ov status` 检查状态后稍后再试。确认处理完成且无相关错误后,再检索资料。++```bash+ov find "灯塔试点开始前要准备什么?" --uri viking://resources/onboarding-transfer-v1/onboarding-zh-v1+```++完成标志是文件内容一致、必要元数据可读取,并能在新目录检索到相关资料。检索排名与分数会受目标模型及索引配置影响,核对重点是返回内容能否支持问题。++<a id="从-a-服务迁移到-b-服务"></a>++## 数据服务间迁移++例如,将开发环境 A 中的灯塔资料迁移到测试环境 B。数据通过运行 CLI 的电脑中转:从 A 下载 `.ovpack` 文件,再将该文件上传到 B,两套服务之间无需直接连通。++本例迁移选定的资料目录,A 中的原资料会保留。B 的模型、账号和访问凭据需要单独配置;整账号备份与恢复见 [OVPack 参考](../api/14-ovpack.md)。++### 配置两个连接++准备两套支持 OVPack 的服务,认证要求与上文一致。A 的账号需要来源读权限,B 的账号需要目标父目录写权限,B 还需配置可用的 Embedding 模型。迁移前确认 B 支持 A 导出的包格式;导出期间暂停对该样例目录的修改,便于核对内容。++在本机同一个工作目录中创建两个 CLI 配置文件,分别填写实际服务地址和对应账号的 API Key。下面的地址仅作示例:++`ov-a.conf`:++```json+{+ "url": "https://openviking-a.example.com",+ "api_key": "your-service-a-user-key"+}+```++`ov-b.conf`:++```json+{+ "url": "https://openviking-b.example.com",+ "api_key": "your-service-b-user-key"+}+```++在 macOS / Linux 终端中,通过 `OPENVIKING_CLI_CONFIG_FILE` 为每条命令指定连接。先限制配置文件的读取权限,再检查两套服务是否可访问:++```bash+chmod 600 ./ov-a.conf ./ov-b.conf+OPENVIKING_CLI_CONFIG_FILE=./ov-a.conf ov health+OPENVIKING_CLI_CONFIG_FILE=./ov-b.conf ov health+```++后续命令都在这个工作目录中执行。配置文件包含访问凭据,请保存在本机受控位置。++### 从 A 导出++确认 A 中已导入[灯塔资料](08-resources.md#准备资料),然后将目录下载到本机:++```bash+OPENVIKING_CLI_CONFIG_FILE=./ov-a.conf ov tree viking://resources/onboarding-zh-v1+OPENVIKING_CLI_CONFIG_FILE=./ov-a.conf ov export viking://resources/onboarding-zh-v1 ./lighthouse-a-to-b.ovpack+```++命令成功后,当前目录中会生成 `lighthouse-a-to-b.ovpack`。如果改用另一台电脑连接 B,将这个文件传到该电脑即可;A 的连接凭据留在原电脑上。++### 导入到 B++在 B 中创建一个新的迁移父目录,再导入本地包:++```bash+OPENVIKING_CLI_CONFIG_FILE=./ov-b.conf ov mkdir viking://resources/from-a-v1+OPENVIKING_CLI_CONFIG_FILE=./ov-b.conf ov import ./lighthouse-a-to-b.ovpack viking://resources/from-a-v1 --on-conflict fail --vector-mode recompute+```++这里使用 `recompute`,由 B 的 Embedding 模型重新生成向量,适用于两套环境模型配置不同的情况。导入会调用 B 的模型并产生相应开销。若目标 root 已存在,选择新的父目录后重试。++记录返回的实际 root URI;本例通常为 `viking://resources/from-a-v1/onboarding-zh-v1`。下方命令以这个 URI 为例。++### 在 B 核对结果++先检查目录与正文,再等待 B 的后台向量处理:++```bash+OPENVIKING_CLI_CONFIG_FILE=./ov-b.conf ov tree viking://resources/from-a-v1/onboarding-zh-v1+OPENVIKING_CLI_CONFIG_FILE=./ov-b.conf ov read viking://resources/from-a-v1/onboarding-zh-v1/project/project.md+OPENVIKING_CLI_CONFIG_FILE=./ov-b.conf ov wait+```++`ov wait` 等待队列处理,也可能受 B 中其他排队工作的影响。如果请求超时,查看 B 的状态:++```bash+OPENVIKING_CLI_CONFIG_FILE=./ov-b.conf ov status+```++仍在处理时稍后再次等待;出现错误时检查 B 的模型与存储配置及服务端日志。确认处理完成且无相关错误后,在 B 中检索:++```bash+OPENVIKING_CLI_CONFIG_FILE=./ov-b.conf ov find "灯塔试点开始前要准备什么?" --uri viking://resources/from-a-v1/onboarding-zh-v1+```++| 核对项 | 通过条件 |+| --- | --- |+| 文件与正文 | B 中四份源文件的相对路径和正文与 A 一致 |+| 摘要与概览 | 包内保留的语义侧边文件在 B 中可读取 |+| 检索结果 | 能找到试点准备相关资料,并读取结果 URI 对应的原文 |+| 引用与接入 | 正文中的绝对 URI、服务地址及 Agent 的检索范围已按 B 的实际位置核对 |++核对完成后,将应用或 Agent 的服务地址、凭据和资料检索范围改为 B 的配置,再用同一个问题验证回答及来源。这样可以确认应用已经使用 B 中的资料。A 的原目录可继续保留,用于比对和后续切换安排。++## 包与冲突检查++OVPack 的 manifest 记录文件集合、大小和校验信息。缺失文件、校验不符或不支持的格式版本会使导入失败,此时可以重新导出并核对包的传输过程。向量兼容性、`auto`/`require` 模式及归档校验规则见 [OVPack 参考](../api/14-ovpack.md)。++实验完成后,可保留包作比对;清理时在 Studio 中确认新父目录下的导入 root,再删除演示内容,原来源目录继续可用。diff --git a/docs/zh/getting-started/16-rules.md b/docs/zh/getting-started/16-rules.mdnew file mode 100644index 000000000..ea7492bc9--- /dev/null+++ b/docs/zh/getting-started/16-rules.md@@ -0,0 +1,138 @@+# 规则(Beta)++::: warning Beta 提示+规则功能目前处于 Beta 阶段,本页介绍的接口、参数和使用流程在后续版本中可能发生不兼容调整。升级前,请查阅版本说明和最新文档,并在测试环境中验证现有接入流程。+:::++Rule 用来保存 Agent 在特定条件下需要遵守的明确要求,例如发布前的检查项、代码规范中的禁止项。OpenViking 将这些要求编译为规则,按当前任务召回;Agent 再结合原文证据,检查行动或回答是否满足要求。++本次体验为 Lighthouse 演示项目保存一条发布规则,再检查两份发布说明。完成后,你可以看到规则原文、召回结果,以及补齐材料前后的检查差异。++## 适用场景++| 场景 | 可以保存的规则 | Agent 如何使用 |+| --- | --- | --- |+| 发布检查 | 项目发布说明必须包含回滚步骤 | 发布前核对说明,指出缺少的内容 |+| 代码审查 | 团队禁止在业务代码中记录访问密钥 | 对照变更内容检查,并标注相关代码 |+| 协议核查 | 用户提供的协议义务、适用条件与例外 | 逐条核对材料,区分已满足、违反和证据不足 |++Skill 说明“怎样做”,Rule 说明“在什么条件下需要遵守哪些要求”。明确的义务和禁止项适合保存为 Rule;个人偏好和普通建议可以继续放在记忆中。++## 准备环境++准备已启用 Rule 功能的 OpenViking 服务,以及 Python 环境;安装入口见[快速开始](02-quickstart.md#准备工作)。服务端需要可用的 Embedding 和 Compiler 模型,Compiler 默认复用 VLM,配置见 [Rules 配置](../configuration/01-server.md#rules)。编译和检索会调用模型,并将演示规则保存在当前用户的规则库中,适合使用测试用户体验。++在 Python 环境中安装 SDK:++```bash+python -m pip install --upgrade openviking-sdk+```++本例使用支持 `rule_compile()` 和 `rule_search()` 的 Python HTTP SDK;服务端与 SDK 都需要包含 Rule(Beta)能力。使用托管服务时,可先向服务提供方确认支持情况。连接与身份配置见 [API 约定](../api/01-overview.md)。++将下面的 Python 片段依次放入同一个 `rule_demo.py` 文件,填写服务地址和当前用户的 API Key;本地未启用鉴权时可省略 `api_key`。++## 保存规则++使用一条仅针对演示项目的要求,明确触发条件和需要完成的检查:++```python+from openviking_sdk import SyncHTTPClient++client = SyncHTTPClient(url="http://localhost:1933", api_key="your-key")+task = client.rule_compile(+ instruction="检查 Lighthouse 演示项目的发布说明时,发布说明必须包含回滚步骤。",+)+print("Compile task:", task["task_id"])+```++服务会返回后台任务 ID。接下来等待编译和关联索引任务完成,再读取实际生成的规则:++```python+import time+++def wait_for_task(task_id, timeout=300):+ deadline = time.monotonic() + timeout+ while time.monotonic() < deadline:+ current = client.get_task(task_id)+ if current is None:+ raise RuntimeError(f"Task not found: {task_id}")+ if current["status"] == "completed":+ return current+ if current["status"] in {"failed", "cancelled"}:+ raise RuntimeError(current)+ time.sleep(1)+ raise TimeoutError(f"Task still running: {task_id}")+++result = wait_for_task(task["task_id"])["result"]+print("Operations:", result["operations"])+write_task_id = result.get("write_result", {}).get("task_id")+if write_task_id:+ wait_for_task(write_task_id)+for uri in result["written_uris"]:+ print(uri)+ print(client.read(uri))+```++检查规则是否保留了“Lighthouse 演示项目”“检查发布说明时”和“必须包含回滚步骤”。重复提交可能得到 `NOOP`,表示已有规则覆盖输入,可以继续检索;`UNCERTAIN` 或 `REJECT` 会给出未写入原因,先按原因调整输入。等待超时后,可用已打印的任务 ID 继续查询进度。++## 按任务召回++以下是固定的虚构样例:Lighthouse 演示项目的发布说明全文为“本次发布新增导出进度提示。”将这段证据和检查目标一起提交:++```python+matches = client.rule_search(+ task_context=(+ "检查 Lighthouse 演示项目的发布说明。"+ "已读取发布说明全文:本次发布新增导出进度提示。"+ "计划核对发布要求,并列出需要补充的内容。"+ ),+)+print(matches["rendered"])+print("Warning:", matches.get("warning"))+print("Scenario selection:", matches.get("scenario_selection"))+```++保存文件后运行:++```bash+python rule_demo.py+```++在输出中找到规则正文及 URI,核对它是否包含刚才的回滚要求。`rendered` 是可交给 Agent 的完整规则文本;搜索负责找到可能适用的规则,具体是否满足要求由 Agent 对照材料检查。++## 核对检查结果++把上一步完整的 `rendered` 输出附在下面的提示词后,交给你的 Agent。两份说明均为演示材料,Agent 只需阅读并返回检查结果:++```text+请依据附后的规则,分别检查 Lighthouse 演示项目的两份发布说明。++版本 A 全文:本次发布新增导出进度提示。+版本 B 全文:本次发布新增导出进度提示。回滚步骤:停止新版本服务,+切换到上一版本镜像,使用上一版本配置启动服务,并检查健康接口。++请逐条核对规则的适用条件和例外,引用规则 URI 与发布说明原文,+分别说明要求是已满足、违反还是证据不足,并列出需要补充的内容。+本次只做文本检查。++以下是检索得到的完整规则:+(粘贴 rendered 输出)+```++| 核对项 | 预期观察 |+| --- | --- |+| 规则适用 | 两份材料都属于 Lighthouse 演示项目的发布说明 |+| 版本 A | 缺少回滚步骤,Agent 指出需要补充 |+| 版本 B | 包含回滚步骤,满足这条规则;步骤是否实际可行还需部署验证 |+| 结论可追溯 | 回答引用了规则 URI 和对应的说明原文 |++这张表是样例的验收标准,实际运行结果以你的模型输出为准。没有召回规则时,可先检查编译与索引任务、用户身份和任务描述。出现 `warning` 时,结合提示检查模型配置,并让 Agent 逐条核对条件;空结果或放行分数都需要结合材料继续检查。++## 继续使用++接入 [VikingBot](11-vikingbot.md) 后,可以让它主动调用 `openviking_rule_search` 工具完成召回。当前 Beta 由用户或 Agent 主动触发编译与搜索,普通会话提交不会自动生成 Rule。++需要批量导入规范或接入自己的 Agent 时,继续阅读[规则校验](../workflows/02-rule-validation.md);暂停、更新和归档规则的方法见[规则生命周期](../concepts/17-rule-scenarios.md#生命周期)。diff --git a/docs/zh/getting-started/17-authentication.md b/docs/zh/getting-started/17-authentication.mdnew file mode 100644index 000000000..a047ce859--- /dev/null+++ b/docs/zh/getting-started/17-authentication.md@@ -0,0 +1,121 @@+# 认证++API Key 用于确认请求来自谁,以及可以执行哪些操作。团队使用 OpenViking 时,可以由平台管理员配置 Root Key,再为团队管理员和普通用户创建各自的访问凭据。++本页完成一个最小流程:启用 API Key 认证,创建 `acme` 团队及管理员 `team-admin`,再创建普通用户 Alice 和 Bob。后续团队管理文档沿用这些身份。++## 准备工作++本例适用于可以修改配置并重启的自建服务。准备已安装的 `ov` CLI、curl,以及已有的服务端配置。模型和存储的配置沿用[快速开始](02-quickstart.md);本文的 JSON 只展示需要合并的字段。++火山引擎云服务由平台管理认证和账号,按控制台提供的流程获取凭据。以下 Root Key 配置用于自建服务。++| 身份 | 凭据 | 用途 |+| --- | --- | --- |+| 平台管理员 ROOT | `server.root_api_key` | 创建和管理 Account 等平台操作 |+| 团队管理员 ADMIN | 创建管理员时返回的 `user_key` | 管理本 Account 的用户,以及该管理员自己的数据和团队共享资料 |+| 普通用户 USER | 创建用户时返回的 `user_key` | 访问个人数据和已授权的共享资料 |++API Key 模式下,服务端从凭据解析 Account、User 和角色。Root Key 没有绑定租户用户,日常资料、记忆和会话操作使用 User/Admin Key。++## 配置 Root Key++由平台管理员先备份当前使用的 `ov.conf`。生成一个随机密钥,例如在本机终端运行:++```bash+python3 -c 'import secrets; print(secrets.token_urlsafe(32))'+```++将生成的值保存在受控位置,并填入服务端配置的 `server` 段。保留原有的模型、存储和其他服务参数:++```json+{+ "server": {+ "host": "127.0.0.1",+ "auth_mode": "api_key",+ "root_api_key": "<随机生成的 Root Key>"+ }+}+```++用原配置路径和启动参数重启服务。默认路径的本机服务可以使用:++```bash+openviking-server --config ~/.openviking/ov.conf+```++如需同时使用 VikingBot,在原启动命令中保留 `--with-bot`。网络部署的地址、HTTPS 和反向代理配置见[服务部署](../guides/03-deployment.md)。++认证启用后,客户端需要使用对应凭据。原有数据仍保留在原存储位置和 Account 下,创建新团队不会自动迁移此前的默认账号数据。++## 创建团队管理员++由平台管理员执行。本例使用 macOS / Linux 的 bash 或 zsh;将 `OV_URL` 换成实际服务地址。执行 `read` 后粘贴刚才设置的 Root Key,再按回车,输入时不会回显:++```bash+export OV_URL="http://127.0.0.1:1933"+read -r -s ROOT_KEY+export ROOT_KEY+```++创建 `acme` 团队,并同时创建第一个管理员 `team-admin`:++```bash+curl -sS -X POST "$OV_URL/api/v1/admin/accounts" \+ -H "X-API-Key: $ROOT_KEY" \+ -H "Content-Type: application/json" \+ -d '{"account_id":"acme","admin_user_id":"team-admin"}'+```++检查响应的 `status` 为 `ok`,并保存 `result.user_key`。这是 **team-admin 的 Admin Key**,与 Root Key 不同。通过安全渠道将它交给该团队管理员。响应包含凭据,保存和转发时仅提供给对应用户。++如果 `acme` 已存在,使用已有账号继续;需要独立体验时,选择新名称并同步替换后续命令中的 Account ID。++## 创建普通用户++由团队管理员打开 CLI 连接向导:++```bash+ov config+```++添加名为 `acme-admin` 的自定义连接,填写上述服务地址和 team-admin 的 Admin Key,保存并激活。检查连接后,创建两个普通用户:++```bash+ov health+ov admin register-user acme alice --role user+ov admin register-user acme bob --role user+```++两次注册分别返回各自的 `user_key`。管理员将对应凭据交给 Alice 和 Bob;两人使用自己的凭据分别保存 `acme-alice`、`acme-bob` 命名连接。详细连接步骤见 [CLI 入门](05-cli-setup.md)。++需要增加另一位管理员时,可以注册 `--role admin` 的用户;角色管理接口见 [Admin API](../api/08-admin.md)。团队管理员无需持有 Root Key 即可管理本团队成员。++## 核对身份++在 Alice 的终端中选中她的连接:++```bash+ov config switch acme-alice+ov health -o json+ov ls viking://~/+```++健康响应应显示 `account_id: acme`、`user_id: alice`、`role: user`,并且能够列出 Alice 的家目录。用 team-admin 的连接检查时,身份应为 `team-admin`、角色为 `admin`。++每个人可以在自己的电脑上使用这些连接名称。如果由同一位操作者验证多个身份,先保存相应命名连接,再在每组操作前切换。修改 `--user` 或 `--account` 不会改变 API Key 绑定的身份。++## 常见问题++| 现象 | 下一步 |+| --- | --- |+| 启用认证后旧连接失败 | 在 `ov config` 中补充该用户的 User/Admin Key |+| Root Key 可以创建团队,但不能读取资料 | 使用团队内的 User/Admin Key 执行数据操作 |+| 普通用户创建成员被拒绝 | 切换到该 Account 的管理员连接 |+| 新团队看不到之前的数据 | 核对原数据所属 Account,按[知识共享](22-sharing.md)选择发布或迁移 |++平台管理员完成操作后,可用 `unset ROOT_KEY` 清除当前终端的变量。密钥轮换和其他认证模式见[身份认证](../guides/04-authentication.md)。++## 下一步++继续阅读 [Account](18-accounts.md),创建第二个团队并验证数据隔离。diff --git a/docs/zh/getting-started/18-accounts.md b/docs/zh/getting-started/18-accounts.mdnew file mode 100644index 000000000..8c59240e5--- /dev/null+++ b/docs/zh/getting-started/18-accounts.md@@ -0,0 +1,89 @@+# Account++Account 是 OpenViking 的团队或租户空间。一个服务可以承载多个 Account,每个 Account 拥有自己的用户、资料、记忆和会话。++适合为不同团队、客户或独立业务建立数据边界。同一团队的成员放在同一个 Account 中协作;需要在团队内进一步限制资料访问时,使用 [ACL](21-access-control.md)。++## 理解边界++| 范围 | 内容 | 共享方式 |+| --- | --- | --- |+| Account | 团队的用户与数据 | 与其他 Account 隔离 |+| User | 个人记忆、资料和会话 | 用户自身访问;适合分享的知识可发布到共享资料区 |+| 共享资料区 | `viking://resources/...` | 当前 Account 内共享,可通过 ACL 细分授权 |++两个 Account 可以使用相同的 URI,例如 `viking://resources/team-check`。请求凭据决定实际访问哪个 Account,URI 中不需要拼接 Account ID。这是逻辑数据隔离;独立存储或模型配置见 [Account 配置参考](../api/08-admin.md)。++## 准备工作++先完成[认证](17-authentication.md),已有 `acme`、管理员 `team-admin` 和 Alice、Bob。平台管理员持有 Root Key,并已在终端中设置 `OV_URL`、`ROOT_KEY`。本例再创建 `beta` 团队。++创建 Account 由平台管理员执行,团队管理员负责本 Account 的成员管理。以下验证只创建空目录,不调用生成模型。++## 创建第二个团队++平台管理员创建 `beta` 及其首个管理员:++```bash+curl -sS -X POST "$OV_URL/api/v1/admin/accounts" \+ -H "X-API-Key: $ROOT_KEY" \+ -H "Content-Type: application/json" \+ -d '{"account_id":"beta","admin_user_id":"beta-admin"}'+```++保存返回的 `result.user_key` 并交给 beta-admin。由 beta-admin 通过 `ov config` 保存名为 `beta-admin` 的连接,使用相同服务地址和自己的 Admin Key。++## 在 acme 创建内容++由 acme 的 Alice 执行。在她的连接下创建一个新的共享目录:++```bash+ov config switch acme-alice+ov health -o json+ov mkdir viking://resources/team-check+ov ls viking://resources+```++确认身份属于 `acme`,并且目录列表中出现 `team-check`。如果目录已存在,选择新名称进行验证。++## 从 beta 核对隔离++由 beta-admin 使用自己的连接检查同一 URI:++```bash+ov config switch beta-admin+ov health -o json+ov stat viking://resources/team-check+```++确认当前 Account 是 `beta`。如果 beta 内还没有同名目录,应返回未找到;acme 中刚创建的目录不会出现在这里。++再由 beta-admin 创建同名目录:++```bash+ov mkdir viking://resources/team-check+ov ls viking://resources+```++创建应成功。现在两个团队各自拥有一个 `team-check`,后续内容变更也各自在所属 Account 内生效。++## 选择团队连接++API Key 模式下,每个用户凭据绑定一个 Account 和 User。需要访问另一团队时,由该团队管理员创建对应身份并提供凭据,再保存新的连接。++业务应用应按登录用户映射到相应的 OpenViking 连接。一个请求的 `--account` 参数无法把已有用户 Key 变成其他团队的身份;上游统一传递身份的部署方式见[身份认证](../guides/04-authentication.md)。++## 检查结果++| 检查项 | 预期结果 |+| --- | --- |+| Alice 的健康响应 | `account_id` 为 `acme` |+| beta-admin 的健康响应 | `account_id` 为 `beta` |+| beta 创建目录前 | 看不到 acme 的 `team-check` |+| beta 创建同名目录后 | 两个 Account 各自保有独立目录 |++如果结果不符,先用 `ov config show` 和 `ov health -o json` 核对当前服务、用户和 Account。默认无鉴权的本机模式不适合作为多用户身份隔离的验证环境。++## 下一步++继续 [User](19-users.md) 验证同一 Account 下的个人数据边界;跨 Account 交付资料时,查看[知识共享](22-sharing.md)。diff --git a/docs/zh/getting-started/19-users.md b/docs/zh/getting-started/19-users.mdnew file mode 100644index 000000000..d1ef946e1--- /dev/null+++ b/docs/zh/getting-started/19-users.md@@ -0,0 +1,83 @@+# User++User 是 Account 内的数据归属身份。OpenViking 用它区分个人记忆、私有资料和会话,让同一团队中的 Alice 和 Bob 各自保留长期上下文,同时使用团队共享资料。++这里的 User 是访问服务时的身份,可以由应用映射到一个真实用户或独立的应用身份。多个 Agent 如果使用同一 User Key,就会使用同一个用户空间;需要各自独立的个人数据时,使用不同 User。++## 理解用户空间++Alice 的目录如下:++```text+viking://user/alice/+├── memories/ # Alice 的长期记忆+├── resources/ # Alice 的私有资料+├── skills/ # Alice 的私有技能+├── peers/ # Alice 的交互对象+└── sessions/ # Alice 的会话+```++`viking://~/` 是当前用户家目录的别名。Alice 使用时展开为 `viking://user/alice/`,Bob 使用时展开为 `viking://user/bob/`。共享资料位于同一 Account 的 `viking://resources/`。++## 准备工作++先完成[认证](17-authentication.md),创建同属 `acme` 的普通用户 Alice 和 Bob,并保存 `acme-alice`、`acme-bob` 连接。本例创建一个空的私有目录和一个会话,不触发记忆提取。++## 创建私有内容++Alice 切换到自己的连接,核对身份并创建目录:++```bash+ov config switch acme-alice+ov health -o json+ov mkdir viking://~/resources/personal-check+ov ls viking://~/resources+```++目录列表中应出现 `personal-check`。再创建一个由 Alice 持有的会话,并关闭自动提交:++```bash+ov session new --session-id alice-user-check --no-auto-commit+ov session add-message alice-user-check --role user --content "这是 Alice 的个人项目讨论。"+ov session get alice-user-check+```++确认会话中能读到这条消息。会话消息已保存;提交后才进入记忆提取流程,后续操作见[记忆使用](09-memory.md)。++## 用 Bob 核对边界++Bob 使用自己的连接列出家目录:++```bash+ov config switch acme-bob+ov ls viking://~/resources+```++这里展示 Bob 的私有资料目录。继续尝试访问 Alice 刚创建的目录:++```bash+ov ls viking://user/alice/resources/personal-check+```++这次访问应被拒绝。相同 Account 允许团队协作,但个人空间仍按 User 划分。需要分享其中的知识时,由 Alice 将选定内容发布到共享资料区,见[知识共享](22-sharing.md)。++## User 与角色++User 决定数据属于谁,角色决定允许执行哪些管理操作:++| 用户角色 | 主要能力 |+| --- | --- |+| USER | 个人数据操作和已授权共享资料的访问 |+| ADMIN | 自己的用户空间、团队成员管理、当前 Account 共享资料的管理 |++管理员的日常数据请求仍使用自己的 User 身份。API Key 模式下,管理员不能通过修改身份请求头切换为 Alice 或 Bob。平台 ROOT 负责 Account 等平台操作,其 Root Key 不用于普通租户数据读取。++应用可以在多个会话中复用同一个用户身份,使长期记忆持续积累;会话 ID 用来区分对话,Peer 用来区分该用户下的稳定交互对象。++## 检查结果++Alice 能访问自己的目录和会话,Bob 的家目录解析到自己,并且不能读取 Alice 的私有目录。如果两人看到了同一个个人空间,先核对是否共用了同一个 Key。++## 下一步++阅读 [Peer](20-peers.md),为同一用户面对的不同交互对象分别组织资料和记忆。用户注册、角色调整和密钥轮换见 [Admin API](../api/08-admin.md)。diff --git a/docs/zh/getting-started/20-peers.md b/docs/zh/getting-started/20-peers.mdnew file mode 100644index 000000000..9df05fcd4--- /dev/null+++ b/docs/zh/getting-started/20-peers.md@@ -0,0 +1,129 @@+# Peer++Peer 是当前用户空间中的稳定交互对象,可以代表一个人或另一个 Agent。为对象使用固定的 `peer_id`,可以把相关资料和记忆组织在一起,并在后续会话中继续使用。++例如,Alice 的助手经常与 `review-agent` 协作评审。Alice 自己的偏好保存在用户记忆中,与 review-agent 有关的评审偏好则可以保存在对应的 Peer 记忆中。++## 区分身份与对象++| 概念 | 本例中的含义 |+| --- | --- |+| Account:`acme` | Alice 所属团队 |+| User:`alice` | 数据所有者和访问服务的身份 |+| Peer:`review-agent` | Alice 的稳定交互对象 |+| Session | Alice 与对象的一次对话 |++`review-agent` 的内容位于 `viking://user/alice/peers/review-agent/`。Peer ID 不会创建一个独立 User,也不会为该对象签发访问凭据。即使把 Peer 命名为 `bob`,它也仍然是 Alice 空间中的对象,与真实用户 Bob 的个人空间分别管理。++## 准备工作++先完成[认证](17-authentication.md),使用 `acme-alice` 连接。以下例子先验证 Peer 资料范围,再演示记忆提取;写入资料和提取记忆需要可用的服务端模型,会产生模型调用。++为同一个对象保持稳定 ID,例如 `review-agent`;使用单段标识,避免在 ID 中使用 `/`。重复体验时更换会话 ID,保留同一个 Peer ID 即可延续该对象的上下文。++## 保存对象资料++Alice 为两个协作对象分别建立资料目录:++```bash+ov config switch acme-alice+ov mkdir viking://~/peers/review-agent/resources+ov mkdir viking://~/peers/research-agent/resources+```++为 review-agent 写入一份协作说明:++```bash+ov write viking://~/peers/review-agent/resources/brief.md \+ --mode create --content "review-agent 负责评审,评审建议按问题、影响、建议三列组织。" --wait+```++处理完成后,读取原文,确认内容:++```bash+ov read viking://~/peers/review-agent/resources/brief.md+```++如果写入等待超时,保存返回的任务 ID,用 `ov task status <task_id>` 查询状态;完成后再继续。++## 限定 Peer 范围++在 Alice 的同一连接上,使用 `actor_peer_id` 将一次请求的 Peer 集合限制到 review-agent:++```bash+ov --actor-peer-id review-agent ls viking://~/peers+ov --actor-peer-id review-agent read viking://~/peers/review-agent/resources/brief.md+```++列表只应包含允许的 Peer,读取说明文件应成功。再尝试访问另一个 Peer:++```bash+ov --actor-peer-id review-agent ls viking://~/peers/research-agent/resources+```++这次访问应被拒绝。需要按问题查找 review-agent 的资料时,可以限定具体目录:++```bash+ov --actor-peer-id review-agent find "评审建议使用什么格式?" \+ --uri viking://~/peers/review-agent/resources+```++Actor Peer 只限制当前用户下的 Peer 集合。用户自身的记忆、资料和可访问的团队共享资料仍按原权限可见,会话也仍属于 Alice。应用面向外部参与者时,应由可信入口决定 Peer 范围;持有 Alice 完整 Key 的客户端可以改变或省略这个范围。独立用户权限使用不同 User 身份。++## 保存 Peer 记忆++消息中的 `peer_id` 用来标识交互对象,`actor_peer_id` 用于请求的访问范围,两者分别设置。本例只提取该对象的偏好,通过 HTTP 创建会话并显式配置记忆策略。++在 Alice 的终端设置服务地址,通过隐藏输入提供她自己的 User Key:++```bash+export OV_URL="http://127.0.0.1:1933"+read -r -s ALICE_KEY+export ALICE_KEY+```++创建会话,开启 Peer 记忆、关闭本次会话的 Self 记忆提取,并使用手动提交:++```bash+curl -sS -X POST "$OV_URL/api/v1/sessions" \+ -H "X-API-Key: $ALICE_KEY" \+ -H "Content-Type: application/json" \+ -d '{"session_id":"peer-review-a","auto_commit_policy":null,"memory_policy":{"self":{"enabled":false},"peer":{"enabled":true},"memory_types":["preferences"]}}'+```++检查响应成功后,仍使用 Alice 的 CLI 连接记录消息并提交:++```bash+ov session add-message peer-review-a --role user --peer-id review-agent \+ --content "我是 review-agent。我偏好将评审建议整理为问题、影响、建议三列的表格;后续与我协作评审时请沿用这个格式。"+ov session commit peer-review-a+```++记录返回的 `task_id` 和 `archive_uri`。每隔 5 秒查询一次任务,先观察最多 2 分钟;仍在运行时保留任务 ID,稍后继续。状态为 `failed` 或 `cancelled` 时查看原因:++```bash+ov task status <task_id>+```++状态为 `completed` 后读取变更记录:++```bash+ov read "<archive_uri>/memory_diff.json"+```++在 `operations.adds` 或 `operations.updates` 中查找对应记忆 URI,再用 `ov read` 读取。预期记录位于 `viking://user/alice/peers/review-agent/memories/` 下,正文保留三列表格的偏好。文件名由提取结果决定;若没有新增记录,检查是否更新了已有记忆,以及当前模板是否支持 Peer 和 preferences 类型。++## 在后续任务中使用++在新的对话中,让使用 Alice 连接的 Agent 先检索该 Peer 的记忆:++```bash+ov --actor-peer-id review-agent find "review-agent 的评审格式偏好" \+ --uri viking://~/peers/review-agent/memories+```++读取命中的记忆,再让 Agent 按该偏好生成评审表格并引用记忆 URI。新会话继续使用 `review-agent` 标记相关消息,后续提交可持续积累该对象的记忆。++## 下一步++Peer 内容属于当前用户。需要让团队其他用户使用选定知识时,继续[知识共享](22-sharing.md);完整过滤规则见[多租户](../concepts/11-multi-tenant.md#peer-restricted-view)。diff --git a/docs/zh/getting-started/21-access-control.md b/docs/zh/getting-started/21-access-control.mdnew file mode 100644index 000000000..c5f52bb5c--- /dev/null+++ b/docs/zh/getting-started/21-access-control.md@@ -0,0 +1,118 @@+# 访问控制++ACL 用于决定同一个 Account 内,哪些用户可以读取、修改或管理共享资料。适合项目协作、指定成员可读和分组维护等场景。++本页创建一个仅 Alice 可管理、Bob 可读的共享目录,再验证读取、拒绝写入和撤销授权。Account 管理员保留共享资料的隐式管理权。++## 准备工作++先完成[认证](17-authentication.md),准备 `acme-admin`、`acme-alice` 和 `acme-bob` 三个连接。Alice 与 Bob 均为普通用户,便于验证授权效果。++ACL 适用于 `viking://resources/...`。个人记忆、个人资料和 Peer 空间保持 User 边界;分享其中的内容可参考[知识共享](22-sharing.md)。++## 开启 ACL++由 acme 的团队管理员执行。在终端设置服务地址,并通过隐藏输入提供 team-admin 的 Admin Key:++```bash+export OV_URL="http://127.0.0.1:1933"+read -r -s ADMIN_KEY+export ADMIN_KEY+```++开启当前 Account 的 ACL 检查:++```bash+curl -sS -X PATCH "$OV_URL/api/v1/admin/accounts/acme/configuration" \+ -H "X-API-Key: $ADMIN_KEY" \+ -H "Content-Type: application/json" \+ -d '{"settings":{"acl":{"enabled":true}}}'+```++检查返回的 `result.settings.acl.enabled` 为 `true`。该开关默认关闭,关闭时共享资料不执行 ACL 过滤;单独写入授权条目不会自动打开开关。++## 创建受限目录++共享根目录默认授予当前 Account 全员 `manage`,下级目录继承父目录权限。要限定到指定成员,使用 `restricted` 截断继承,并在创建时设置直接授权。++由团队管理员创建一个新的示例目录:++```bash+ov config switch acme-admin+ov mkdir viking://resources/team-knowledge \+ --acl '{"acl_mode":"restricted","entries":[{"principal":"user:alice","level":"manage"},{"principal":"user:bob","level":"read"}]}'+```++目录已存在时先用 `ov acl get` 检查其权限;本次体验可换一个新名称,避免覆盖原有授权。++| 权限 | 可以执行的操作 |+| --- | --- |+| `read` | 读取、列目录和检索 |+| `write` | 包含 read,并允许写入、创建、删除或移动文件 |+| `manage` | 包含 write,并允许管理 ACL、删除或移动目录 |++## 写入一份资料++由 Alice 发布一份说明。写入会触发语义与向量处理,需要可用模型,并产生模型调用:++```bash+ov config switch acme-alice+ov write viking://resources/team-knowledge/access-check.md \+ --mode create --content "团队约定:每周五汇总项目反馈。" --wait+```++新文件继承目录权限。查看目录授权与文件正文:++```bash+ov acl get viking://resources/team-knowledge+ov read viking://resources/team-knowledge/access-check.md+```++如果等待超时,使用返回的任务 ID 查询处理状态,完成后继续。++## 用 Bob 验证++Bob 使用自己的连接读取并检索:++```bash+ov config switch acme-bob+ov read viking://resources/team-knowledge/access-check.md+ov find "什么时候汇总项目反馈?" --uri viking://resources/team-knowledge+```++预期能读到正文,检索结果包含这份资料。再尝试创建一个文件:++```bash+ov write viking://resources/team-knowledge/bob-check.md \+ --mode create --content "Bob 的写入检查。"+```++由于 Bob 只有 `read`,写入应被拒绝。如果成功,检查当前身份是否为管理员、账号 ACL 是否已开启,以及目录的有效权限中是否还有其他授权。++## 调整授权++Alice 拥有 `manage`,可以授予 Bob 编辑权限:++```bash+ov config switch acme-alice+ov acl grant viking://resources/team-knowledge --principal user:bob --level write+```++Bob 重新执行刚才的写入命令应成功。后续只需阅读时,将权限设置回 `read`;合作结束时撤销直接授权:++```bash+ov acl grant viking://resources/team-knowledge --principal user:bob --level read+ov acl revoke viking://resources/team-knowledge --principal user:bob+```++以上两条由 Alice 执行。撤销后切换到 Bob,再读取 `access-check.md` 应被拒绝。权限索引更新可能有短暂延迟,可每隔 2 秒检查,先观察最多 30 秒;持续可读时检查有效权限和其他授权来源。++`revoke` 删除当前节点的直接条目。若用户还通过父目录或用户组获得权限,相应访问仍然有效。撤销也不会删除用户已下载的副本。需要继续下一篇共享体验时,由 Alice 恢复 Bob 的 `read` 权限。++## 授权给用户组++成员较多时,可以由管理员创建 Account 内的用户组,维护成员后,把目录授权给 `group:<group_id>`。组内成员变更从后续请求生效,适合为多个项目小组管理访问。创建组与成员的完整步骤见 [Admin API](../api/08-admin.md#用户组)。++## 下一步++继续[知识共享](22-sharing.md),将个人积累的项目知识发布到这个受控目录。权限继承和移动目录的完整规则见 [ACL 概念](../concepts/15-acl.md)。diff --git a/docs/zh/getting-started/22-sharing.md b/docs/zh/getting-started/22-sharing.mdnew file mode 100644index 000000000..107adae42--- /dev/null+++ b/docs/zh/getting-started/22-sharing.md@@ -0,0 +1,197 @@+# 知识共享++个人记忆帮助 Agent 延续用户的工作背景。项目约定和可复用经验需要被同事使用时,可以由记忆所有者整理出共享内容,发布到团队资料目录,再由其他成员的 Agent 检索、阅读和引用。++本页以 Alice 向 Bob 分享海岬项目评审约定为例,完成 **选择记忆 → 整理内容 → 授权发布 → Bob 检索并使用 → 后续更新**,并说明跨团队的处理方式。++## 选择共享方式++| 场景 | 操作方式 |+| --- | --- |+| 同一 Account 内共享资料 | 发布到 `viking://resources/...`,通过 ACL 授权用户或用户组 |+| 同一 Account 内共享个人经验 | 所有者选择记忆内容,整理成共享资料,再授权发布 |+| 不同 Account 之间交付知识 | 来源方整理可交付内容,目标方使用自己的凭据导入,并配置目标权限 |+| 多人共同积累长期团队记忆 | 由应用编排知识选择、发布和更新;当前没有跨 User 私有记忆自动合并的共享开关 |++个人记忆目录和 Peer 记忆目录不接受共享资料 ACL。发布后的内容作为共享资料维护,与原始记忆分别保存。++## 准备工作++先完成[认证](17-authentication.md),准备普通用户 Alice、Bob,以及各自的 CLI 连接。按[访问控制](21-access-control.md)开启 `acme` 的 ACL,并创建 `viking://resources/team-knowledge`:Alice 为 `manage`,Bob 为 `read`。如果已体验撤销授权,由 Alice 先恢复 Bob 的 `read`。++Alice 应已有一份准备分享的项目记忆。首次体验可在 Alice 连接下完成[记忆使用](09-memory.md)中的“保存项目背景”和“查看生成的记忆”,获得海岬项目约定;本页不依赖 VikingBot,能执行 CLI 的 Agent 即可完成最后的问答。++导入、检索和 Agent 回答会使用相应模型。每位成员使用自己的凭据;共享流程由以下角色分工完成:++| 角色 | 负责的操作 |+| --- | --- |+| 团队管理员 | 开启 ACL、准备共享目录和初始权限 |+| Alice 或她的 Agent | 读取 Alice 的记忆、整理草稿、发布和维护 |+| Bob 或他的 Agent | 检索已授权资料、读取原文并用于任务 |++## Alice 选择记忆++在 Alice 的终端或 Agent 中使用她自己的连接:++```bash+ov config switch acme-alice+ov find "海岬项目的评审约定" --uri viking://~/memories+```++读取相关结果,确认哪些内容适合分享:++```bash+ov read "<记忆 URI>"+```++可以把下面的任务交给 Alice 的 Agent:++```text+请从我的海岬项目记忆中整理可以共享给 Bob 的评审约定。+读取原文,区分已确认的要求和待确定事项,生成 Markdown 草稿。+草稿附上供我核对的来源,先让我确认,再发布到团队资料目录。+```++由 Alice 确认要共享的内容。对外发布的正文应包含可理解的事实,或引用 Bob 有权读取的来源;Alice 的私有记忆 URI 可以留在个人核对记录中。++## Alice 整理草稿++如果使用前述海岬样例,核对记忆后,在本机创建 `cape-review.md`:++```markdown+# 海岬项目评审约定++## 评审要求++- 每次评审讨论两项风险。+- 摘要使用中文三条要点。+- 交付文件统一命名为 cape-review.csv。++## 待补充信息++- 本次评审的具体风险尚未提供。++## 维护信息++- 维护人:Alice+- 适用范围:海岬项目评审+```++这是与样例输入对应的共享正文。使用真实项目时,以读到的记忆和 Alice 确认的内容替换,并保留适用范围与待确定事项。++## Alice 发布资料++根据资料所在位置选择一种发布方式:已有资料可以在服务端直接复制;本机新整理的草稿可以使用 `add-resource` 导入。两种方式都使用 Alice 的连接,并发布到已为 Bob 授权的目录。++### 复制已有资料++如果待分享的内容已保存在 Alice 的个人资料目录,确认正文和引用适合共享后,可以直接复制,无需下载到本地。以下示例假设源文件为 `viking://~/resources/cape-review/cape-review.md`;执行时替换为实际 URI。++Alice 需要能够读取源资料,并对目标目录拥有 `write` 或 `manage` 权限。先在 `team-knowledge` 下创建一个新的发布目录,再复制文件:++```bash+ov config switch acme-alice+ov read viking://~/resources/cape-review/cape-review.md+ov mkdir viking://resources/team-knowledge/cape-review+ov cp viking://~/resources/cape-review/cape-review.md \+ viking://resources/team-knowledge/cape-review/cape-review.md -o json+ov read viking://resources/team-knowledge/cape-review/cape-review.md+```++这里的 `~` 指向当前连接用户 Alice。新建的共享资料继承目标目录权限,Bob 可以按后文步骤检索和读取;Alice 的原始资料仍保存在个人目录中。++如果整个源目录都适合共享,可以用下面的命令替代上面的 `mkdir` 和单文件 `cp`。目标父目录 `team-knowledge` 需已存在,目标 URI 就是复制后的目录位置:++```bash+ov cp -r viking://~/resources/cape-review \+ viking://resources/team-knowledge/cape-review -o json+ov tree viking://resources/team-knowledge/cape-review+```++复制会同时复制已有向量记录;目标父目录的摘要可能异步刷新。响应中的 `semantic_status: queued` 表示摘要刷新已入队,`failed` 表示需要查看 `semantic_error`。发布后由 Bob 检索并读取正文,确认可用。完整行为见[文件系统 API](../api/03-filesystem.md#cp)。++复制生成独立副本,源资料后续修改不会自动同步。再次复制同名文件会覆盖目标正文,目录复制会合并到已有目录并保留目标独有文件。首次发布使用新路径;后续更新前核对目标内容,并检查正文中引用的私有 URI 是否需要替换。++### 导入本地草稿++如果使用前面整理的本地 Markdown 草稿,在文件所在目录执行,使用一个新的发布路径:++```bash+ov add-resource ./cape-review.md \+ --to viking://resources/team-knowledge/cape-review --wait+```++发布目录继承 `team-knowledge` 的权限。处理完成后,展开目录并读取实际正文 URI:++```bash+ov tree viking://resources/team-knowledge/cape-review+ov read "<共享正文 URI>"+```++记录共享正文 URI,供 Bob 阅读及后续更新。若等待超时,保存返回的任务 ID,通过 `ov task status <task_id>` 检查;确认完成后再让 Bob 使用。++## Bob 检索并使用++Bob 使用自己的连接检索:++```bash+ov config switch acme-bob+ov find "海岬项目评审应采用什么格式和交付文件名?" \+ --uri viking://resources/team-knowledge/cape-review+```++读取结果中的共享正文 URI,核对内容。随后在 Bob 的 Agent 中发送:++```text+请使用我的 ov CLI 连接,检索 viking://resources/team-knowledge/cape-review,+读取相关原文,按海岬项目约定准备一份评审提纲。+列出摘要格式、风险讨论数量和交付文件名,并引用共享资料的完整 URI。+具体风险未提供时,请保留待填写项。+```++Agent 需要能够执行 CLI,并在检索流程中包含这个共享目录。资料授权成功后,仍需由 Agent 检索和读取,才能把内容用于回答。++| 核对项 | 预期结果 |+| --- | --- |+| 访问身份 | Bob 的 `ov health -o json` 显示 `acme` / `bob` |+| 来源 | 命中 `team-knowledge/cape-review` 下的共享资料 |+| 回答 | 两项风险、三条中文摘要、`cape-review.csv` |+| 未知信息 | 具体风险保留待填写,或明确说明未提供 |+| 私有边界 | Bob 仍不能读取 Alice 原始的私有记忆目录 |++## 维护共享内容++默认由 Alice 维护。通过服务端复制发布的资料,可以在源文件更新并确认后,再次执行同一条文件复制命令;这会覆盖共享副本的正文,并保留目标权限。++通过本地草稿发布时,修改本机 `cape-review.md` 后,可以更新前面记录的共享正文 URI:++```bash+ov config switch acme-alice+ov write "<共享正文 URI>" --from-file ./cape-review.md --mode replace --wait+```++这会替换该文件的完整正文,并重新处理;发布前核对本地文件包含需要保留的全部内容。完成后,Bob 重新检索、读取,确认使用的是更新后的约定。++Alice 的个人记忆后续发生变化时,共享资料不会自动同步。需要共同维护时,Alice 可以授予 Bob `write`;合作结束时可撤销授权,方法见[访问控制](21-access-control.md)。Bob 已经下载或复制的内容需要另外管理。++## 跨团队交付++如果 Bob 属于另一个 Account,例如 `beta`,acme 的 ACL 无法直接授权 beta 的用户。`user:bob` 只表示当前 Account 内的 Bob。++可由 Alice 将已确认的 `cape-review.md` 通过团队认可的渠道交给 beta 的资料维护人。beta 管理员先按[访问控制](21-access-control.md)在 **beta** 内开启 ACL,创建受限共享目录并授予目标成员权限;把示例 Account ID 和用户 ID 换成 beta 的实际成员。++获得目标目录写权限后,beta 的维护人使用自己的连接,在收到文件的目录中导入:++```bash+ov config switch beta-admin+ov add-resource ./cape-review.md \+ --to viking://resources/team-knowledge/cape-review --wait+```++这里的 `beta-admin` 是 [Account](18-accounts.md) 中创建的目标团队连接。目标目录、权限和成员由 beta 独立管理;导入后由目标成员检索并核对原文。来源与目标各自保存一份资料,后续更新需要再次交付或由应用同步。++批量迁移可参考[导入导出](15-transfer.md),完成后重新核对目标身份、目录权限和正文中的来源链接。如果多个小组需要长期共同维护同一份资料,可以把协作成员放在同一 Account 下,通过用户组与 ACL 管理不同范围。++## 下一步++用一份真实项目约定重复这个流程,确认 Bob 的 Agent 能找到共享内容并用于任务。更完整的多资料问答流程见[资料检索](08-resources.md)。diff --git a/docs/zh/getting-started/23-studio.md b/docs/zh/getting-started/23-studio.mdnew file mode 100644index 000000000..3c7988b95--- /dev/null+++ b/docs/zh/getting-started/23-studio.md@@ -0,0 +1,99 @@+# Studio 入门++OpenViking Studio 是服务自带的 Web 界面。你可以在浏览器中查看已导入的资料、检索相关内容、浏览记忆和技能,并跟踪后台任务的处理情况。通过 Studio,可以把命令行返回的 `viking://` URI 与实际内容对应起来,核对 Agent 使用的上下文。++本节从连接服务开始,带你浏览首页、打开资料原文、执行一次检索,再查看任务状态。完成后,你可以在页面中确认资料是否可读、能否被检索到,以及处理任务是否完成。++## 准备服务++准备一个正在运行的 OpenViking 服务,以及对应的访问地址。首次使用时,可按[快速开始](02-quickstart.md)完成安装、模型配置和启动;已完成初始化但尚未启动本地服务时,在终端运行:++```bash+openviking-server+```++保持终端运行,在浏览器中打开 [Studio](http://127.0.0.1:1933/studio/)。默认本地端口为 `1933`;使用其他端口或远程服务时,将地址替换为实际服务地址,并在末尾加上 `/studio/`。++启用 API Key 认证的服务需要准备 User Key;具有管理职责的用户也可以使用 Admin Key。密钥由管理员创建,操作方法见[认证](17-authentication.md)。本地开发模式未启用认证时,密钥可以留空。++下方截图使用端口为 `1940` 的独立本地演示服务,包含虚构的灯塔项目资料。首次启动的服务可能尚无数据,可以先完成快速开始中的资料导入,再跟随本文浏览。++## 连接服务++首次打开 Studio 时,在连接向导中选择服务类型。本地部署选择**开源服务**,填写服务地址,例如 `http://127.0.0.1:1933`,然后选择界面语言并进入下一步。++++在身份页面填写用户 API Key,点击**验证连接**。验证成功后,核对页面显示的 Account 和 User,再点击**进入 Studio**。后续浏览和检索使用这个身份对应的数据范围。++++Root/Admin Key 是可选的管理凭据,按需要配置;日常资料访问使用用户身份。身份和权限的详细说明见[认证](17-authentication.md)。已有连接时,可通过左上角的连接名称切换,也可以在**连接设置**中调整连接信息。++## 查看首页++首页展示上下文数据量、今日 Token 用量、今日检索次数,以及用量和提交趋势。导入资料或执行检索后,可以回到这里了解使用情况;刚启动且尚未使用的服务,部分统计可能为空或为零。++++左侧导航分为工作区、活动和设置。日常查看内容从**文件系统**和**检索**开始,处理进度在**任务中心**查看,服务状态在**监控**中查看。++## 浏览资料++打开**文件系统**,展开 `resources`,找到已导入的资料目录,再点击文件名。中间区域显示文件内容;Markdown 文件可以切换**预览**和**源码**,顶部可以复制完整的 `viking://` URI,供后续检索或交给 Agent 引用。++++以灯塔项目为例,打开原文后可以确认:反馈保存到本地文件,每周由试点管理员导出并交给项目负责人,第一版不提供云端同步。核对这些具体事实,能够帮助你判断 Agent 的回答是否忠于资料。++文件系统也提供其他上下文的入口:`user` 用于查看用户记忆,`agent` 用于查看 Agent 的技能和经验。页面中可见的目录和可执行操作取决于当前身份及授权范围。++需要导入新资料时,点击界面中的**添加资源**,按表单选择来源和目标位置。导入后先到任务中心确认处理结果,再打开文件核对内容。目录和导入方式见[资料检索](08-resources.md);顶部的历史版本和 OVPack 入口分别对应[版本管理](14-versions.md)与[导入导出](15-transfer.md)。++## 检索内容++打开**检索**,选择 `find`,输入一个具体问题,例如“灯塔项目第一版应怎样收集用户反馈,需要提前准备什么?”。在检索范围中选择**自定义 URI**,填写刚才资料所在目录的 URI,然后点击检索按钮或按 Enter。++如果沿用快速开始的目录,填写 `viking://resources/lighthouse-demo`。截图中的演示目录是 `viking://resources/lighthouse-demo-zh`,实际操作时以文件系统中复制的 URI 为准。++++结果展示 URI、内容描述、上下文层级和相关度。点击文件结果可以查看内容;如果命中的是目录摘要,可以继续进入对应目录阅读原文。相关度用于比较检索结果与问题的匹配程度,回答中的事实仍需结合原文核对。++页面中的几种检索方式适用于不同目的:++| 方式 | 适用场景 |+| --- | --- |+| `find` | 按语义查找与单次问题相关的上下文 |+| `search` | 使用增强检索,结合会话等上下文理解查询意图 |+| `grep` | 在文件内容中匹配文本或正则表达式 |+| `glob` | 按路径模式查找文件 |++需要让 Agent 综合资料生成回答时,可继续使用 [VikingBot](11-vikingbot.md) 或[接入自己的 Agent](../agent-integrations/01-overview.md)。++## 跟踪任务++资料导入、会话提交和索引重建等操作会产生后台任务。打开**任务中心**,按任务类型或状态筛选,再点击对应任务,查看关联 URI、工序进度、耗时和执行日志。++++任务显示**已完成**后,回到文件系统和检索页面检查产物。任务出现异常时,先查看详情中的错误和执行日志,确认问题发生在哪个环节,再按提示检查配置或输入内容。++**会话**页面用于浏览对话记录,并查看会话提交带来的记忆变化。要体验从对话中提取记忆、在后续任务中召回的完整流程,可以继续阅读[记忆使用](09-memory.md)。++## 使用其他页面++| 页面 | 可以完成的工作 | 后续阅读 |+| --- | --- | --- |+| VikingBot | 与内置 Agent 对话,结合资料完成任务;需要服务启用 Bot | [VikingBot](11-vikingbot.md) |+| 技能 | 浏览和管理技能,查看可供 Agent 使用的操作说明 | [技能使用](10-skills.md) |+| 编译 | 将源资料整理为 Wiki 等可复用内容;需要可用的 Compile Runtime | [上下文编译](13-compile.md) |+| Agent 经验 | 查看 Agent 积累的经验上下文 | [记忆使用](09-memory.md) |+| 请求日志 | 查看请求记录,辅助排查调用问题 | [可观测性与排障](../guides/05-observability.md) |+| 定时同步 | 查看和管理已配置的资料同步任务 | [定时同步 API](../api/15-watches.md) |+| 监控 | 查看服务健康状态及队列、模型、存储等组件状态 | [可观测性与排障](../guides/05-observability.md) |+| OpenViking 网关 | 管理模型上游、上下文策略和网关接入凭据 | [网关接入](12-gateway.md) |++页面中可用的能力随服务配置和当前权限变化。需要为团队划分数据范围或授权共享时,从 [Account](18-accounts.md) 和[访问控制](21-access-control.md)了解配置方法。++完成浏览后,建议用自己的一个问题执行检索,打开结果原文,再与 Agent 的回答逐条对照。可以按[效果评估](06-evaluate.md)记录结果,判断资料覆盖和回答质量是否满足任务需要。