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
feat(docs): preserve UTM attribution across documentation links (#5870)
LaamGinghong107cf0dc79e2
diff --git a/README.md b/README.mdindex ff6dfd305..cdf77f4f3 100644--- a/README.md+++ b/README.md@@ -160,7 +160,7 @@ uv tool install openviking --upgrade && openviking-server init<details><summary><strong>Use OpenViking Service (hosted by Volcengine)</strong></summary>-The same OpenViking service, run for you by Volcengine. The first 50 files are free. Activate it on the [Volcengine product page](https://www.volcengine.com/product/openviking-service), then create an API key in the console under User Management → API Key. The server address is `https://api.vikingdb.cn-beijing.volces.com/openviking`; you'll need it and the API key when you connect your agent.+The same OpenViking service, run for you by Volcengine. The first 50 files are free. Activate it on the [Volcengine product page](https://www.volcengine.com/product/openviking-service?utm_source=github&utm_medium=referral&utm_campaign=readme), then create an API key in the console under User Management → API Key. The server address is `https://api.vikingdb.cn-beijing.volces.com/openviking`; you'll need it and the API key when you connect your agent.</details>@@ -353,7 +353,7 @@ The server supports [accounts and user isolation](https://docs.openviking.ai/en/<img src="docs/images/commercial-saas.png" alt="Managed SaaS" width="100%" /><h3>☁️ Managed SaaS</h3>-<p><a href="https://www.volcengine.com/product/openviking-service">Volcano Engine</a> hosts and operates OpenViking. Personal and Enterprise plans cover individual and team use, with migration tooling for open-source deployments. See the <a href="https://docs.volcengine.com/docs/84313/2374478">service documentation</a> for plans and limits. Hosting outside China is planned on <a href="https://www.byteplus.com">BytePlus</a>.</p>+<p><a href="https://www.volcengine.com/product/openviking-service?utm_source=github&utm_medium=referral&utm_campaign=readme">Volcano Engine</a> hosts and operates OpenViking. Personal and Enterprise plans cover individual and team use, with migration tooling for open-source deployments. See the <a href="https://docs.volcengine.com/docs/84313/2374478">service documentation</a> for plans and limits. Hosting outside China is planned on <a href="https://www.byteplus.com">BytePlus</a>.</p></td><td width="50%" valign="top">diff --git a/docs/.vitepress/theme/attribution.test.ts b/docs/.vitepress/theme/attribution.test.tsnew file mode 100644index 000000000..275355472--- /dev/null+++ b/docs/.vitepress/theme/attribution.test.ts@@ -0,0 +1,80 @@+import assert from 'node:assert/strict'+import test from 'node:test'+import { attributionUrl, docsCampaign, readUtm } from './attribution.ts'++const docs = 'https://docs.openviking.ai/zh/getting-started/02-quickstart'+const product = 'https://www.volcengine.com/product/openviking-service'+const consoleUrl = 'https://console.volcengine.com/vikingdb/openviking/region:openviking+cn-beijing'+const incoming = { utm_source: 'wechat_bytetech', utm_medium: 'social', utm_campaign: '验收_20261010', utm_content: '图文 & 位置=首屏' }+const tagged = docs + '?' + new URLSearchParams(incoming)++test('原始 UTM 整组覆盖默认参数,缺省 term 不被补入', () => {+ const fallback = product + '?plan=enterprise&utm_source=opensource_docs&utm_medium=referral&utm_campaign=quickstart&utm_term=old#plans'+ const result = new URL(attributionUrl(fallback, tagged)!)+ assert.deepEqual(readUtm(result.href), incoming)+ assert.equal(result.searchParams.get('plan'), 'enterprise')+ assert.equal(result.hash, '#plans')+ assert.equal(result.searchParams.has('utm_term'), false)+})++test('控制台区域路径的加号保持不变,站内链接继承来源', () => {+ assert.equal(new URL(attributionUrl(consoleUrl, tagged)!).pathname, '/vikingdb/openviking/region:openviking+cn-beijing')+ const next = attributionUrl('/zh/guides/03-deployment?lang=zh#cloud', tagged)!+ assert.deepEqual(readUtm(next), incoming)+ assert.equal(new URL(next).searchParams.get('lang'), 'zh')+ assert.equal(new URL(next).hash, '#cloud')+})++test('显式的新入口不和当前触点混组', () => {+ const next = '/en/?utm_source=rednote_volc_agent_community&utm_medium=social&utm_campaign=new'+ assert.equal(attributionUrl(next, tagged), undefined)+})++test('无参数的直接访问只生成文档默认来源,不向站内导航添加默认触点', () => {+ assert.deepEqual(readUtm(attributionUrl(product, docs)!), {+ utm_source: 'opensource_docs', utm_medium: 'referral', utm_campaign: 'getting-started_02-quickstart'+ })+ assert.equal(attributionUrl('/zh/guides/03-deployment', docs), undefined)+ assert.equal(attributionUrl(product + '?utm_source=opensource_docs&utm_medium=referral&utm_campaign=static', docs), undefined)+})++test('文档默认 campaign 在语言、扩展名和部署 base 下保持一致', () => {+ assert.equal(docsCampaign('/zh/getting-started/02-quickstart'), docsCampaign('/en/getting-started/02-quickstart.html'))+ assert.equal(docsCampaign('/guide/en/guides/03-deployment.html', '/guide/'), 'guides_03-deployment')+ assert.equal(docsCampaign('/guide/zh/index.html', '/guide/'), 'main')+ assert.equal(docsCampaign('/zh/'), 'main')+ assert.deepEqual(readUtm(attributionUrl('/guide/en/guides/03-deployment', 'https://docs.openviking.ai/guide/zh/?' + new URLSearchParams(incoming), '/guide/')!), incoming)+})++test('GitHub、非 OV 路径、第三方、下载资源及 API 不透传', () => {+ for (const target of [+ 'https://github.com/volcengine/OpenViking?utm_source=docs',+ 'https://blog.openviking.ai/', 'https://www.volcengine.com/product/other',+ 'https://www.volcengine.com.evil.example/product/openviking-service',+ 'https://console.volcengine.com/vikingdb/openviking-other',+ 'https://api.vikingdb.cn-beijing.volces.com/openviking',+ '/zh/llms.txt', '/agents/zh/hermes.md', '/brand.svg',+ 'mailto:[email protected]', 'javascript:void(0)'+ ]) assert.equal(attributionUrl(target, tagged), undefined, target)+ assert.deepEqual(readUtm(attributionUrl('https://www.openviking.ai/enterprise', tagged)!), incoming)+})++test('重复、缺失和超长字段整体无效,不产生混合来源', () => {+ for (const query of [+ 'utm_source=wechat&utm_medium=social',+ 'utm_source=wechat&utm_medium=social&utm_campaign=a&utm_source=rednote',+ 'utm_source=wechat&utm_campaign=a',+ 'utm_source=%20&utm_medium=referral',+ 'utm_source=wechat&utm_medium=social&utm_campaign=' + 'a'.repeat(2049)+ ]) {+ const entry = docs + '?' + query+ assert.equal(readUtm(entry), undefined)+ assert.equal(readUtm(attributionUrl(product, entry)!)?.utm_source, 'opensource_docs')+ }+ assert.equal(readUtm('not a URL'), undefined)+})++test('付费搜索保留 term,空的可选字段保留原值', () => {+ const params = { utm_source: 'search_mock', utm_medium: 'cpc', utm_campaign: 'campaign', utm_term: 'agent memory', utm_content: '' }+ assert.deepEqual(readUtm(attributionUrl(product, docs + '?' + new URLSearchParams(params))!), params)+})diff --git a/docs/.vitepress/theme/attribution.ts b/docs/.vitepress/theme/attribution.tsnew file mode 100644index 000000000..3a4798110--- /dev/null+++ b/docs/.vitepress/theme/attribution.ts@@ -0,0 +1,174 @@+export const UTM_KEYS = [+ 'utm_source', 'utm_medium', 'utm_campaign', 'utm_content', 'utm_term'+] as const++export type Utm = Partial<Record<typeof UTM_KEYS[number], string>>++const SESSION_KEY = 'openviking-docs-utm'+const MARKETING_MEDIA = new Set(['social', 'paid_social', 'cpc'])+const WEBSITE_ORIGINS = new Set([+ 'https://openviking.ai', 'https://www.openviking.ai',+ 'https://openviking.net', 'https://www.openviking.net'+])++export function readUtm(href: string): Utm | undefined {+ try {+ const params = new URL(href).searchParams+ const utm: Utm = {}+ for (const key of UTM_KEYS) {+ const values = params.getAll(key)+ if (values.length > 1 || values.some(value => value.length > 2048)) return+ if (values.length) utm[key] = values[0]+ }+ if (!utm.utm_source?.trim() || !utm.utm_medium?.trim()) return+ if (MARKETING_MEDIA.has(utm.utm_medium) && !utm.utm_campaign?.trim()) return+ return utm+ } catch {+ return undefined+ }+}++function relativePath(pathname: string, base: string): string | undefined {+ const prefix = '/' + base.split('/').filter(Boolean).join('/')+ if (pathname === prefix) return ''+ const directory = prefix === '/' ? '/' : prefix + '/'+ return pathname.startsWith(directory) ? pathname.slice(directory.length) : undefined+}++export function docsCampaign(pathname: string, base = '/'): string {+ return (relativePath(pathname, base) ?? '')+ .replace(/^(en|zh)(\/|$)/, '')+ .replace(/(?:^|\/)index(?:\.html)?$/, '')+ .replace(/\.html$/, '')+ .split('/').filter(Boolean).join('_') || 'main'+}++function isDocsPage(url: URL, current: URL, base: string): boolean {+ if (url.origin !== current.origin) return false+ const path = relativePath(url.pathname, base)+ if (path === undefined) return false+ if (path === '' || path === 'index.html') return true+ return /^(en|zh)(\/|$)/.test(path) && !/\.(?!html$)[^/]+$/.test(path)+}++function isConversionTarget(url: URL): boolean {+ if (url.origin === 'https://www.volcengine.com') {+ return /^\/product\/openviking-service\/?$/.test(url.pathname)+ }+ if (url.origin === 'https://console.volcengine.com') {+ return /^\/vikingdb\/openviking(?:\/|$)/.test(url.pathname)+ }+ return WEBSITE_ORIGINS.has(url.origin) && /^\/(?:enterprise\/?)?$/.test(url.pathname)+}++/** 只传标准 UTM,业务 query、区域路径及锚点保持不变。 */+export function attributionUrl(href: string, currentHref: string, base = '/'): string | undefined {+ try {+ const current = new URL(currentHref)+ const target = new URL(href, current)+ if (!['http:', 'https:'].includes(target.protocol)) return+ const incoming = readUtm(current.href)+ let utm: Utm+ if (isDocsPage(target, current, base)) {+ // 显式带参的目标是独立入口,不混入当前链路参数。+ if (!incoming || UTM_KEYS.some(key => target.searchParams.has(key))) return+ utm = incoming+ } else {+ if (!isConversionTarget(target)) return+ if (!incoming && readUtm(target.href)) return+ utm = incoming ?? {+ utm_source: 'opensource_docs', utm_medium: 'referral',+ utm_campaign: docsCampaign(current.pathname, base)+ }+ }+ const original = target.href+ for (const key of UTM_KEYS) {+ target.searchParams.delete(key)+ if (utm[key] !== undefined) target.searchParams.set(key, utm[key]!)+ }+ return target.href === original ? undefined : target.href+ } catch {+ return undefined+ }+}++export function startDocsAttribution(base = '/') {+ const originals = new WeakMap<HTMLAnchorElement, { original: string; applied: string }>()+ let refreshedHref: string | undefined++ function persist() {+ // URL 是本次来源的依据;无参数的新入站清理缓存,不恢复历史渠道。+ try {+ const utm = readUtm(location.href)+ if (!utm) sessionStorage.removeItem(SESSION_KEY)+ else {+ const serialized = JSON.stringify(utm)+ if (sessionStorage.getItem(SESSION_KEY) !== serialized) sessionStorage.setItem(SESSION_KEY, serialized)+ }+ } catch { /* 存储不可用不影响链接透传。 */ }+ }++ function refreshLink(link: HTMLAnchorElement) {+ if (link.hasAttribute('download')) return+ const href = link.getAttribute('href')+ if (href === null) return+ let entry = originals.get(link)+ if (!entry || href !== entry.applied) {+ entry = { original: href, applied: href }+ originals.set(link, entry)+ }+ const next = attributionUrl(entry.original, location.href, base) ?? entry.original+ entry.applied = next+ if (href !== next) link.setAttribute('href', next)+ }++ function refresh() {+ const href = location.href.split('#')[0]+ if (href === refreshedHref) return+ refreshedHref = href+ persist()+ document.querySelectorAll<HTMLAnchorElement>('a[href]').forEach(refreshLink)+ }++ const observer = new MutationObserver(records => {+ // 每批只处理新增或被外部改写的链接,自身补参不再触发链接计算。+ const links = new Set<HTMLAnchorElement>()+ for (const record of records) {+ if (record.type === 'attributes') {+ const link = record.target+ if (link instanceof HTMLAnchorElement && link.getAttribute('href') !== originals.get(link)?.applied) {+ links.add(link)+ }+ } else {+ for (const node of record.addedNodes) {+ if (!(node instanceof Element)) continue+ if (node instanceof HTMLAnchorElement && node.hasAttribute('href')) links.add(node)+ node.querySelectorAll<HTMLAnchorElement>('a[href]').forEach(link => {+ if (link instanceof HTMLAnchorElement) links.add(link)+ })+ }+ }+ }+ for (const link of links) {+ if (link.isConnected && link.ownerDocument === document) refreshLink(link)+ }+ })+ observer.observe(document.documentElement, { subtree: true, childList: true, attributes: true, attributeFilter: ['href'] })+ const controller = new AbortController()+ document.addEventListener('click', event => {+ const link = event.target instanceof Element ? event.target.closest('a') : null+ if (link instanceof HTMLAnchorElement) refreshLink(link)+ }, { capture: true, signal: controller.signal })+ window.addEventListener('pageshow', refresh, { signal: controller.signal })+ refresh()++ return {+ refresh,+ routeTarget(to: string) {+ const target = new URL(to, location.href)+ return isDocsPage(target, new URL(location.href), base)+ ? attributionUrl(to, location.href, base) : undefined+ },+ dispose() { observer.disconnect(); controller.abort() }+ }+}diff --git a/docs/.vitepress/theme/index.ts b/docs/.vitepress/theme/index.tsindex c99b68389..99d410c54 100644--- a/docs/.vitepress/theme/index.ts+++ b/docs/.vitepress/theme/index.ts@@ -1,6 +1,6 @@import { docsLanguageEntry } from './language-entry.js'import { createLanguagePreference } from './language-preference.js'-import { h, defineAsyncComponent } from 'vue'+import { h, defineAsyncComponent, nextTick } from 'vue'import DefaultTheme, { VPButton } from 'vitepress/theme-without-fonts'import DocBreadcrumb from './components/DocBreadcrumb.vue'import AgentPrompt from './components/AgentPrompt.vue'@@ -21,6 +21,7 @@ import OpenVikingSearch from './OpenVikingSearch.vue'import ApiExampleTabsEnhancer from './ApiExampleTabsEnhancer.vue'import { initVikingBotWidget, syncVikingBotLocale } from './vikingbot-widget'import { trackPageView } from './track'+import { startDocsAttribution } from './attribution'import './custom.css'import './reading.css'import './header.css'@@ -280,11 +281,14 @@ export default {app.component('DocsHome', defineAsyncComponent(() => import('./components/DocsHome.vue')))if (import.meta.env.SSR || typeof window === 'undefined') return+ const attribution = startDocsAttribution(withBase('/'))+ import.meta.hot?.dispose(attribution.dispose)const policy = createLanguagePreference()const previousBeforeHook = router.onBeforeRouteChangerouter.onBeforeRouteChange = async (to: string) => {if (await previousBeforeHook?.(to) === false) return false- const target = docsLanguageEntry(new URL(to, location.href).href, withBase('/'), policy)+ const languageTarget = docsLanguageEntry(new URL(to, location.href).href, withBase('/'), policy)+ const target = attribution.routeTarget(languageTarget ?? to) ?? languageTargetif (target) {void router.go(target)return false@@ -299,6 +303,7 @@ export default {trackPageView(to.split('?')[0].split('#')[0])// Update the existing widget after VitePress applies the page language.syncVikingBotLocale()+ void nextTick().then(attribution.refresh)}}}diff --git a/docs/en/agent-integrations/05-hermes.md b/docs/en/agent-integrations/05-hermes.mdindex 485bc0d91..da4bc0318 100644--- a/docs/en/agent-integrations/05-hermes.md+++ b/docs/en/agent-integrations/05-hermes.md@@ -30,7 +30,7 @@ Then choose a connection:- **Quick Local** installs a local server and embedding model. It reuses yoursupported Hermes language model for extraction, which can use a remote API.- **OpenViking Service (VolcEngine Cloud)** connects to VolcEngine's- [managed OpenViking cloud service](https://www.volcengine.com/product/openviking-service)+ [managed OpenViking cloud service](https://www.volcengine.com/product/openviking-service?utm_source=opensource_docs&utm_medium=referral&utm_campaign=agent-integrations_05-hermes)with a service API key. You do not need to install a server or configurelocal models.- **Custom** connects to your own server with its URL and credentials. Setupdiff --git a/docs/en/getting-started/02-quickstart.md b/docs/en/getting-started/02-quickstart.mdindex 2712b7a49..240a064d8 100644--- a/docs/en/getting-started/02-quickstart.md+++ b/docs/en/getting-started/02-quickstart.md@@ -10,13 +10,13 @@ Otherwise, choose one:### Managed service on Volcengine-Open the [OpenViking console](https://console.volcengine.com/vikingdb/openviking/region:openviking+cn-beijing) and obtain your key from **User Management → API Key**. The service endpoint is:+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:```texthttps://api.vikingdb.cn-beijing.volces.com/openviking```-No server installation or local model configuration is needed. See the [product page](https://www.volcengine.com/product/openviking-service) and [service documentation](https://docs.volcengine.com/docs/84313/2374478) for managed-service usage and limits. Continue to step 2.+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.### Self-host a serverdiff --git a/docs/en/getting-started/05-cli-setup.md b/docs/en/getting-started/05-cli-setup.mdindex b8b276abb..7d0ae5edb 100644--- a/docs/en/getting-started/05-cli-setup.md+++ b/docs/en/getting-started/05-cli-setup.md@@ -67,7 +67,7 @@ Otherwise ASK me which target to use, unless I already told you:| 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) under User Management → 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. |@@ -146,7 +146,7 @@ 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) under **User Management → 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. |diff --git a/docs/en/guides/03-deployment.md b/docs/en/guides/03-deployment.mdindex 4e31b4ae3..af22b5dad 100644--- a/docs/en/guides/03-deployment.md+++ b/docs/en/guides/03-deployment.md@@ -6,7 +6,7 @@ OpenViking runs as an HTTP service. Choose who operates it before installing a s| Service | What you need || --- | --- |-| [Volcano Engine managed OpenViking](https://www.volcengine.com/product/openviking-service) | Obtain an API key in the [console](https://console.volcengine.com/vikingdb/openviking/region:openviking+cn-beijing), then connect with the independent CLI. No local server or model configuration is needed. |+| [Volcano Engine managed OpenViking](https://www.volcengine.com/product/openviking-service?utm_source=opensource_docs&utm_medium=referral&utm_campaign=guides_03-deployment) | Obtain an API key in the [console](https://console.volcengine.com/vikingdb/openviking/region:openviking+cn-beijing?utm_source=opensource_docs&utm_medium=referral&utm_campaign=guides_03-deployment), then connect with the independent CLI. No local server or model configuration is needed. || An existing team or remote deployment | Obtain the service URL and a user/admin key from its administrator. || Self-hosted OpenViking | Install and configure the server using the instructions below. |diff --git a/docs/repository/README_CN.md b/docs/repository/README_CN.mdindex 149eca222..e9b82bb27 100644--- a/docs/repository/README_CN.md+++ b/docs/repository/README_CN.md@@ -159,7 +159,7 @@ uv tool install openviking --upgrade && openviking-server init<details><summary><strong>使用 OpenViking Service(火山引擎托管)</strong></summary>-同一个 OpenViking 服务,由火山引擎替你运行。前 50 个文件免费。在[火山引擎产品页](https://www.volcengine.com/product/openviking-service)开通后,到控制台的「用户管理 → API Key」创建一个 API key。服务地址是 `https://api.vikingdb.cn-beijing.volces.com/openviking`,接入 agent 时要用到它和 API key。+同一个 OpenViking 服务,由火山引擎替你运行。前 50 个文件免费。在[火山引擎产品页](https://www.volcengine.com/product/openviking-service?utm_source=github&utm_medium=referral&utm_campaign=readme)开通后,到控制台的「用户管理 → API Key」创建一个 API key。服务地址是 `https://api.vikingdb.cn-beijing.volces.com/openviking`,接入 agent 时要用到它和 API key。</details>@@ -348,7 +348,7 @@ ov chat # 在另一个终端运行<img src="../images/commercial-saas.png" alt="商业化 SaaS 版" width="100%" /><h3>☁️ 商业化 SaaS 版</h3>-<p>由<a href="https://www.volcengine.com/product/openviking-service">火山引擎</a>托管和运维,提供个人版、企业版,以及开源部署的迁移工具。套餐与额度见<a href="https://docs.volcengine.com/docs/84313/2374478">服务文档</a>。中国以外地区的托管服务计划在 <a href="https://www.byteplus.com">BytePlus</a> 上线。</p>+<p>由<a href="https://www.volcengine.com/product/openviking-service?utm_source=github&utm_medium=referral&utm_campaign=readme">火山引擎</a>托管和运维,提供个人版、企业版,以及开源部署的迁移工具。套餐与额度见<a href="https://docs.volcengine.com/docs/84313/2374478">服务文档</a>。中国以外地区的托管服务计划在 <a href="https://www.byteplus.com">BytePlus</a> 上线。</p></td><td width="50%" valign="top">diff --git a/docs/repository/README_JA.md b/docs/repository/README_JA.mdindex 7982ad862..8f10ea8d9 100644--- a/docs/repository/README_JA.md+++ b/docs/repository/README_JA.md@@ -160,7 +160,7 @@ uv tool install openviking --upgrade && openviking-server init<details><summary><strong>OpenViking Service を使う(Volcengine がホスト)</strong></summary>-同じ OpenViking サービスを Volcengine が代わりに運用します。最初の 50 ファイルは無料です。[Volcengine の製品ページ](https://www.volcengine.com/product/openviking-service)で利用を開始したら、コンソールの「User Management → API Key」で API キーを作成してください。サーバーのアドレスは `https://api.vikingdb.cn-beijing.volces.com/openviking` です。エージェントを接続するときに、このアドレスと API キーを使います。+同じ OpenViking サービスを Volcengine が代わりに運用します。最初の 50 ファイルは無料です。[Volcengine の製品ページ](https://www.volcengine.com/product/openviking-service?utm_source=github&utm_medium=referral&utm_campaign=readme)で利用を開始したら、コンソールの「User Management → API Key」で API キーを作成してください。サーバーのアドレスは `https://api.vikingdb.cn-beijing.volces.com/openviking` です。エージェントを接続するときに、このアドレスと API キーを使います。</details>@@ -355,7 +355,7 @@ ov chat # 別のターミナルで実行<img src="../images/commercial-saas.png" alt="マネージド SaaS 版" width="100%" /><h3>☁️ マネージド SaaS 版</h3>-<p><a href="https://www.volcengine.com/product/openviking-service">Volcano Engine</a> がホスティングと運用を担当します。個人向けと企業向けのプラン、オープンソース環境からの移行ツールを提供します。プランと制限は<a href="https://docs.volcengine.com/docs/84313/2374478">サービス文書</a>を参照してください。中国以外でのホスティングは <a href="https://www.byteplus.com">BytePlus</a> で予定されています。</p>+<p><a href="https://www.volcengine.com/product/openviking-service?utm_source=github&utm_medium=referral&utm_campaign=readme">Volcano Engine</a> がホスティングと運用を担当します。個人向けと企業向けのプラン、オープンソース環境からの移行ツールを提供します。プランと制限は<a href="https://docs.volcengine.com/docs/84313/2374478">サービス文書</a>を参照してください。中国以外でのホスティングは <a href="https://www.byteplus.com">BytePlus</a> で予定されています。</p></td><td width="50%" valign="top">diff --git a/docs/scripts/test-utm-browser.mjs b/docs/scripts/test-utm-browser.mjsnew file mode 100644index 000000000..5f589555e--- /dev/null+++ b/docs/scripts/test-utm-browser.mjs@@ -0,0 +1,300 @@+import assert from 'node:assert/strict'+import { mkdir, readFile, writeFile } from 'node:fs/promises'+import path from 'node:path'+import { channels, mockUtm, githubMockHtml, receiverMockHtml } from './utm-mock-server.mjs'++// 从仓库根目录分别启动两个终端:+// pnpm -C docs run docs:dev --port 5173 --strictPort+// pnpm -C docs exec node scripts/utm-mock-server.mjs+// 独立工具目录安装 Playwright 后,以 OV_UTM_PLAYWRIGHT 指向其 index.mjs:+// OV_UTM_PLAYWRIGHT=/绝对路径/node_modules/playwright/index.mjs pnpm -C docs exec node scripts/test-utm-browser.mjs+// 浏览器须与 Playwright 版本匹配;报告和截图默认写入 /tmp/openviking-utm-artifacts。+// Playwright 可安装在独立工具目录,通过环境变量提供,避免改变文档构建依赖。+const { chromium } = await import(process.env.OV_UTM_PLAYWRIGHT ?? 'playwright')+const docsOrigin = process.env.OV_UTM_DOCS_ORIGIN ?? 'http://127.0.0.1:5173'+const mockOrigin = process.env.OV_UTM_MOCK_ORIGIN ?? 'http://127.0.0.1:5174'+const docsUrl = docsOrigin + '/zh/getting-started/02-quickstart'+const output = process.env.OV_UTM_ARTIFACT_DIR ?? '/tmp/openviking-utm-artifacts'+await mkdir(output, { recursive: true })+const browser = await chromium.launch({ headless: true, executablePath: process.env.OV_UTM_CHROMIUM_PATH, args: ['--no-sandbox'] })+const results = []+const keys = ['utm_source', 'utm_medium', 'utm_campaign', 'utm_content', 'utm_term']+const utm = href => Object.fromEntries([...new URL(href).searchParams].filter(([key]) => keys.includes(key)))+const fallback = { utm_source: 'opensource_docs', utm_medium: 'referral', utm_campaign: 'getting-started_02-quickstart' }++async function check(name, run) {+ try { await run(); results.push({ name, passed: true }); console.log('通过:' + name) }+ catch (error) { results.push({ name, passed: false, error: error.stack }); console.error('失败:' + name + '\n' + error.stack) }+}++async function fixture(blockStorage = false) {+ const context = await browser.newContext({ locale: 'zh-CN', viewport: { width: 1360, height: 940 } })+ context.setDefaultTimeout(15000)+ const errors = []+ context.on('page', page => page.on('pageerror', error => errors.push(error.message)))+ if (blockStorage) await context.addInitScript(() => {+ Object.defineProperty(window, 'sessionStorage', { get() { throw new Error('Mock 禁用会话存储') } })+ })+ await context.route('**/*', async route => {+ const url = new URL(route.request().url())+ if ([new URL(docsOrigin).origin, new URL(mockOrigin).origin].includes(url.origin)) return route.continue()+ if (url.pathname.endsWith('/docs/search')) return route.fulfill({+ contentType: 'application/json', headers: { 'Access-Control-Allow-Origin': '*', 'Access-Control-Allow-Headers': '*', 'Access-Control-Allow-Methods': 'POST, OPTIONS' },+ body: JSON.stringify({ results: [{ title: '部署指南', url: '/en/guides/03-deployment', relativePath: 'en/guides/03-deployment.md', snippet: 'Mock 搜索结果' }] })+ })+ if (url.origin === 'https://github.com') return route.fulfill({ contentType: 'text/html', body: githubMockHtml(docsUrl) })+ if (['https://www.volcengine.com', 'https://console.volcengine.com', 'https://www.openviking.ai', 'http://localhost:8080'].includes(url.origin)) {+ return route.fulfill({ contentType: 'text/html', body: receiverMockHtml(url.href) })+ }+ return route.abort()+ })+ const page = await context.newPage()+ return { context, page, errors }+}++async function ready(page, expected) {+ // SPA 会先更新地址栏;等待新页面标题,避免对上一页 DOM 继续操作。+ const pathname = new URL(page.url()).pathname.replace(/\.html$/, '')+ const markdown = await readFile(new URL(`..${pathname}.md`, import.meta.url), 'utf8')+ const title = markdown.match(/^#\s+(.+)$/m)[1]+ await page.locator('.vp-doc h1').filter({ hasText: title }).waitFor()+ await page.waitForFunction(source => {+ const link = document.querySelector('.vp-doc a[href*="console.volcengine.com"]')+ return link && new URL(link.href).searchParams.get('utm_source') === source+ }, expected.utm_source)+ for (const href of await page.locator('.vp-doc a[href*="openviking-service"], .vp-doc a[href*="console.volcengine.com"]').evaluateAll(links => links.map(link => link.href))) {+ assert.deepEqual(utm(href), expected)+ }+}++async function clickReceiver(context, page, link, expected, method = 'click') {+ const next = context.waitForEvent('page')+ if (method === 'keyboard') { await link.focus(); await link.press('Enter') }+ else await link.click(method === 'middle' ? { button: 'middle' } : {})+ const receiver = await next+ await receiver.bringToFront()+ await receiver.waitForSelector('#received')+ assert.deepEqual(utm(receiver.url()), expected)+ assert.deepEqual(JSON.parse(await receiver.locator('#received').innerText()), expected)+ await receiver.close()+}++try {+ for (const [source, label, medium] of channels) await check(label + ' 实际入口和出站接收', async () => {+ const { context, page, errors } = await fixture()+ try {+ const expected = mockUtm(source, medium)+ await page.goto(`${mockOrigin}/channel/${source}`, { waitUntil: 'domcontentloaded' })+ if (source === 'rednote_volc_agent_community') await page.screenshot({ path: path.join(output, 'utm-rednote-entry.png') })+ await page.locator('#enter-docs').click()+ await ready(page, expected)+ assert.deepEqual(utm(page.url()), expected)+ assert.deepEqual(JSON.parse(await page.evaluate(() => sessionStorage.getItem('openviking-docs-utm'))), expected)+ await clickReceiver(context, page, page.locator('.vp-doc a[href*="console.volcengine.com"]').first(), expected)+ assert.deepEqual(errors, [])+ if (source === 'rednote_volc_agent_community') await page.screenshot({ path: path.join(output, 'utm-rednote-docs.png') })+ } finally { await context.close() }+ })++ await check('动态链接增量处理,无关 DOM 和自身补参不重复扫描', async () => {+ const { context, page, errors } = await fixture()+ try {+ await context.addInitScript(() => {+ const metrics = window.__utmObserverMetrics = { fullScans: 0, targetParses: 0 }+ const query = Document.prototype.querySelectorAll+ Document.prototype.querySelectorAll = function(selector) {+ if (this === document && selector === 'a[href]') metrics.fullScans+++ return query.call(this, selector)+ }+ const NativeURL = window.URL+ window.URL = class extends NativeURL {+ constructor(href, base) {+ super(href, base)+ if (String(href).includes('observer_probe=')) metrics.targetParses+++ }+ }+ })+ const expected = mockUtm('wechat_bytetech', 'social')+ await page.goto(docsUrl + '?' + new URLSearchParams(expected), { waitUntil: 'domcontentloaded' })+ await ready(page, expected)+ const measurements = await page.evaluate(async () => {+ const settle = () => new Promise(resolve => setTimeout(resolve, 0))+ const reset = () => Object.assign(window.__utmObserverMetrics, { fullScans: 0, targetParses: 0 })+ const sample = () => ({ ...window.__utmObserverMetrics })+ const root = document.createElement('section')+ document.querySelector('.vp-doc').append(root)+ await settle()+ try {+ reset()+ const text = document.createElement('p')+ root.append(text)+ for (let index = 0; index < 20; index++) { text.textContent = String(index); await settle() }+ const unrelated = sample()++ reset()+ const wrapper = document.createElement('div')+ root.append(wrapper)+ const link = document.createElement('a')+ link.href = 'https://www.volcengine.com/product/openviking-service?observer_probe=added#plans'+ wrapper.append(link)+ await settle()+ const added = { ...sample(), href: link.href }++ reset()+ link.href = 'https://console.volcengine.com/vikingdb/openviking/region:openviking+cn-beijing?observer_probe=changed'+ await settle()+ const changed = { ...sample(), href: link.href }++ reset()+ const removedLink = document.createElement('a')+ removedLink.href = 'https://www.volcengine.com/product/openviking-service?observer_probe=removed'+ root.append(removedLink)+ removedLink.remove()+ await settle()+ const removed = sample()+ window.dispatchEvent(new PageTransitionEvent('pageshow'))+ await settle()+ const samePage = sample()+ return { unrelated, added, changed, removed, samePage }+ } finally { root.remove() }+ })+ assert.deepEqual(measurements.unrelated, { fullScans: 0, targetParses: 0 })+ assert.equal(measurements.added.fullScans, 0)+ assert.equal(measurements.added.targetParses, 1)+ assert.deepEqual(utm(measurements.added.href), expected)+ assert.equal(new URL(measurements.added.href).hash, '#plans')+ assert.equal(measurements.changed.fullScans, 0)+ assert.equal(measurements.changed.targetParses, 1)+ assert.deepEqual(utm(measurements.changed.href), expected)+ assert.equal(new URL(measurements.changed.href).pathname, '/vikingdb/openviking/region:openviking+cn-beijing')+ assert.deepEqual(measurements.removed, { fullScans: 0, targetParses: 0 })+ assert.deepEqual(measurements.samePage, { fullScans: 0, targetParses: 0 })+ assert.deepEqual(errors, [])+ } finally { await context.close() }+ })++ await check('侧栏、语言切换、搜索动态链接、刷新及浏览器返回', async () => {+ const { context, page, errors } = await fixture()+ const expected = mockUtm('wechat_bytetech', 'social')+ try {+ await page.goto(docsUrl + '?' + new URLSearchParams(expected), { waitUntil: 'domcontentloaded' })+ await ready(page, expected)+ await page.locator('.VPSidebar a[href*="/zh/getting-started/05-cli-setup"]').first().click()+ await page.waitForURL('**/zh/getting-started/05-cli-setup?**')+ await ready(page, expected)+ await page.locator('.ov-locale-switch summary').click()+ await page.locator('.ov-locale-switch button[lang="en"]').click()+ await page.waitForURL('**/en/getting-started/05-cli-setup?**')+ await ready(page, expected)+ await page.locator('.ov-docs-search-trigger').click()+ await page.locator('.ov-docs-search-input').fill('CLI')+ const search = page.locator('.ov-docs-search-result').first()+ await search.waitFor()+ assert.deepEqual(utm(await search.getAttribute('href')), expected)+ await search.click()+ await page.waitForURL('**/en/guides/03-deployment?**')+ await ready(page, expected)+ await page.reload({ waitUntil: 'domcontentloaded' })+ await ready(page, expected)+ await page.goBack({ waitUntil: 'domcontentloaded' })+ await ready(page, expected)+ assert.deepEqual(utm(page.url()), expected)+ assert.deepEqual(errors, [])+ } finally { await context.close() }+ })++ for (const method of ['keyboard', 'middle']) await check(method === 'keyboard' ? '键盘打开产品页' : '中键新标签页打开产品页', async () => {+ const { context, page } = await fixture()+ try {+ const expected = mockUtm('rednote_volc_agent_community', 'social')+ await page.goto(docsUrl + '?' + new URLSearchParams(expected), { waitUntil: 'domcontentloaded' })+ await ready(page, expected)+ const link = page.locator('.vp-doc a[href*="openviking-service"]').first()+ assert.deepEqual(utm(await link.getAttribute('href')), expected)+ await clickReceiver(context, page, link, expected, method)+ } finally { await context.close() }+ })++ await check('站内新标签页通过目标 href 继承,不依赖共享缓存', async () => {+ const { context, page } = await fixture()+ try {+ const expected = mockUtm('wechat_byte_opensource', 'social')+ await page.goto(docsUrl + '?' + new URLSearchParams(expected), { waitUntil: 'domcontentloaded' })+ await ready(page, expected)+ const link = page.locator('.VPSidebar a[href*="/zh/getting-started/05-cli-setup"]').first()+ assert.deepEqual(utm(await link.getAttribute('href')), expected)+ const next = context.waitForEvent('page')+ await link.click({ button: 'middle' })+ const tab = await next+ await tab.bringToFront()+ await ready(tab, expected)+ assert.deepEqual(utm(tab.url()), expected)+ } finally { await context.close() }+ })++ await check('公众号历史后直接访问和 GitHub 入站均不恢复历史来源', async () => {+ const { context, page } = await fixture()+ try {+ await page.goto(docsUrl + '?' + new URLSearchParams(mockUtm('wechat_bytetech', 'social')), { waitUntil: 'domcontentloaded' })+ await ready(page, mockUtm('wechat_bytetech', 'social'))+ await page.goto(docsUrl, { waitUntil: 'domcontentloaded' })+ await ready(page, fallback)+ assert.equal(await page.evaluate(() => sessionStorage.getItem('openviking-docs-utm')), null)+ await page.goto(docsUrl + '?' + new URLSearchParams(mockUtm('wechat_bytetech', 'social')), { waitUntil: 'domcontentloaded' })+ await ready(page, mockUtm('wechat_bytetech', 'social'))+ await page.goto('https://github.com/volcengine/OpenViking', { waitUntil: 'domcontentloaded' })+ assert.deepEqual(utm(await page.locator('#github-product').getAttribute('href')), { utm_source: 'github', utm_medium: 'referral', utm_campaign: 'readme' })+ await page.locator('#enter-docs').click()+ await ready(page, fallback)+ assert.deepEqual(utm(page.url()), {})+ assert.equal(await page.evaluate(() => sessionStorage.getItem('openviking-docs-utm')), null)+ } finally { await context.close() }+ })++ await check('新的第三方入口替换旧来源,缺省字段不残留', async () => {+ const { context, page } = await fixture()+ try {+ await page.goto(docsUrl + '?' + new URLSearchParams(mockUtm('wechat_bytetech', 'social')), { waitUntil: 'domcontentloaded' })+ await ready(page, mockUtm('wechat_bytetech', 'social'))+ const expected = { utm_source: 'rednote_volc_agent_community', utm_medium: 'social', utm_campaign: 'new_mock_20261010' }+ await page.goto(docsUrl + '?' + new URLSearchParams(expected), { waitUntil: 'domcontentloaded' })+ await ready(page, expected)+ } finally { await context.close() }+ })++ await check('语言首页入口重定向保留 UTM,GitHub 出口不继承', async () => {+ const { context, page } = await fixture()+ try {+ const expected = mockUtm('rednote_volc_agent_community', 'social')+ await page.goto(docsOrigin + '/?' + new URLSearchParams(expected), { waitUntil: 'domcontentloaded' })+ await page.waitForURL('**/zh/?**')+ await page.waitForFunction(source => new URL(document.querySelector('.ov-site-option[href*="www.openviking.ai"]').href).searchParams.get('utm_source') === source, expected.utm_source)+ assert.deepEqual(utm(page.url()), expected)+ for (const href of await page.locator('a[href*="github.com"]').evaluateAll(links => links.map(link => link.href))) assert.notEqual(new URL(href).searchParams.get('utm_source'), expected.utm_source)+ } finally { await context.close() }+ })++ await check('UTM 会话存储禁用时继续透传且页面无异常', async () => {+ const { context, page, errors } = await fixture(true)+ try {+ const expected = mockUtm('wechat_volce_agent_community', 'social')+ await page.goto(docsUrl + '?' + new URLSearchParams(expected), { waitUntil: 'domcontentloaded' })+ await ready(page, expected)+ assert.deepEqual(errors, [])+ } finally { await context.close() }+ })++ await check('重复 UTM 整组降级为文档来源', async () => {+ const { context, page } = await fixture()+ try {+ await page.goto(docsUrl + '?utm_source=wechat&utm_source=rednote&utm_medium=social&utm_campaign=duplicate', { waitUntil: 'domcontentloaded' })+ await ready(page, fallback)+ } finally { await context.close() }+ })+} finally {+ await browser.close()+ const report = { scope: '本地文档参数传递与 Mock 接收;不代表真实官网、登录或订单归因已验收', docsOrigin, mockOrigin, passed: results.filter(result => result.passed).length, failed: results.filter(result => !result.passed).length, results }+ await writeFile(path.join(output, 'utm-browser-report.json'), JSON.stringify(report, null, 2))+ console.log(`浏览器验收:${report.passed} 项通过,${report.failed} 项失败;报告 ${output}/utm-browser-report.json`)+ if (report.failed) process.exitCode = 1+}diff --git a/docs/scripts/utm-mock-server.mjs b/docs/scripts/utm-mock-server.mjsnew file mode 100644index 000000000..e5270cadc--- /dev/null+++ b/docs/scripts/utm-mock-server.mjs@@ -0,0 +1,61 @@+import { createServer } from 'node:http'+import { readFileSync } from 'node:fs'+import { fileURLToPath } from 'node:url'++export const channels = [+ ['wechat_bytetech', '微信公众号 字节技术团队', 'social'],+ ['wechat_byte_opensource', '微信公众号 字节开源', 'social'],+ ['wechat_volce_agent_community', '微信公众号 火山 Agent 社区', 'social'],+ ['rednote_volc_agent_community', '小红书 火山 Agent 社区', 'social'],+ ['mock_newsletter', '其他第三方 邮件推荐', 'referral'],+ ['mock_search', '其他第三方 付费搜索', 'cpc']+]++export function mockUtm(source, medium) {+ const params = { utm_source: source, utm_medium: medium, utm_campaign: `mock_${source}_20261010` }+ if (medium === 'cpc') params.utm_term = 'Agent memory 搜索词'+ else params.utm_content = '验收图文_中文 空格&位置=首屏'+ return params+}++export const githubProductUrl = readFileSync(new URL('../../README.md', import.meta.url), 'utf8')+ .match(/\]\((https:\/\/www\.volcengine\.com\/product\/openviking-service[^)]+)\)/)[1]++const escape = value => String(value).replace(/[&<>"']/g, char => ({ '&': '&', '<': '<', '>': '>', '"': '"', "'": ''' }[char]))+function html(title, content) {+ return `<!doctype html><html lang="zh-CN"><meta charset="utf-8"><title>${title}</title><style>body{font:16px/1.7 system-ui;max-width:960px;margin:48px auto;padding:0 24px;color:#17233b;background:#f5f7fb}h1{font-size:30px}article{background:white;border:1px solid #dce3ed;border-radius:12px;padding:20px;margin:16px 0}a{color:#165dff}code,pre{overflow-wrap:anywhere;white-space:pre-wrap;font-size:13px}small{color:#61718a}</style><h1>${title}</h1>${content}</html>`+}++export function githubMockHtml(docsUrl) {+ return html('Mock GitHub README', `<p>本页只验证 GitHub 自身来源;上游公众号、小红书 UTM 不透传。</p><article><a id="enter-docs" href="${escape(docsUrl)}">进入无上游 UTM 的开源文档</a></article><article><a id="github-product" href="${escape(githubProductUrl)}">README 的 SaaS 入口</a><pre>${escape(githubProductUrl)}</pre></article>`)+}++export function receiverMockHtml(href) {+ const url = new URL(href)+ const received = Object.fromEntries([...url.searchParams].filter(([key]) => /^utm_(source|medium|campaign|content|term)$/.test(key)))+ return html('Mock 出站接收页', `<p>本页由浏览器验收脚本拦截生成,用于核对文档出口参数。它不代表真实官网或控制台的采集能力。</p><pre id="received">${escape(JSON.stringify(received, null, 2))}</pre><pre>${escape(href)}</pre>`)+}++export function createMockServer(docsOrigin = 'http://127.0.0.1:5173') {+ const docsUrl = new URL('/zh/getting-started/02-quickstart', docsOrigin).href+ return createServer((request, response) => {+ const url = new URL(request.url, 'http://localhost')+ let body+ if (url.pathname === '/github') body = githubMockHtml(docsUrl)+ else {+ const selected = channels.find(([source]) => url.pathname === `/channel/${source}`)+ const cards = (selected ? [selected] : channels).map(([source, label, medium]) => {+ const target = docsUrl + '?' + new URLSearchParams(mockUtm(source, medium))+ return `<article><h2>${label}</h2><a ${selected ? 'id="enter-docs"' : ''} href="${escape(target)}">携带 UTM 进入文档</a><pre>${escape(target)}</pre>${selected ? '' : `<a href="/channel/${source}">打开独立 Mock 渠道页</a>`}</article>`+ }).join('')+ body = html(selected ? selected[1] : 'OpenViking UTM 本地验收入口', `<p>这些入口模拟第三方携带标准 UTM 访问文档。自动化验收会拦截产品页和控制台为 Mock;手动点击文档出口会进入实际站点。</p>${cards}<article><a href="${escape(docsUrl)}">直接访问 无 UTM</a> · <a href="/github">Mock GitHub 不透传上游 UTM</a></article>`)+ }+ response.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8', 'Cache-Control': 'no-store' })+ response.end(body)+ })+}++if (process.argv[1] === fileURLToPath(import.meta.url)) {+ const port = Number(process.env.OV_UTM_MOCK_PORT ?? 5174)+ createMockServer(process.env.OV_UTM_DOCS_ORIGIN).listen(port, '0.0.0.0', () => console.log(`UTM Mock 入口:http://127.0.0.1:${port}/`))+}diff --git a/docs/zh/agent-integrations/05-hermes.md b/docs/zh/agent-integrations/05-hermes.mdindex 47d6927e4..1cdf594e3 100644--- a/docs/zh/agent-integrations/05-hermes.md+++ b/docs/zh/agent-integrations/05-hermes.md@@ -27,7 +27,7 @@ hermes- **Quick Local** 安装本地服务和 embedding 模型,复用受支持的 Hermes LLM 抽取记忆。LLM 仍可使用远程 API。- **OpenViking Service (VolcEngine Cloud)** 通过服务 API Key 连接火山引擎的- [OpenViking 托管云服务](https://www.volcengine.com/product/openviking-service),+ [OpenViking 托管云服务](https://www.volcengine.com/product/openviking-service?utm_source=opensource_docs&utm_medium=referral&utm_campaign=agent-integrations_05-hermes),无需安装服务端或配置本地模型。- **Custom** 使用 URL 和凭据连接自己的服务,也可以复用已保存的 `ovcli.conf`。diff --git a/docs/zh/getting-started/02-quickstart.md b/docs/zh/getting-started/02-quickstart.mdindex 46de4ead5..60f13eb18 100644--- a/docs/zh/getting-started/02-quickstart.md+++ b/docs/zh/getting-started/02-quickstart.md@@ -10,13 +10,13 @@ OpenViking 以服务端运行。用独立的 `ov` CLI 连接服务,导入一### 火山引擎托管服务-打开 [OpenViking 控制台](https://console.volcengine.com/vikingdb/openviking/region:openviking+cn-beijing),从**用户管理 → API Key** 获取密钥。服务地址为:+打开 [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** 获取密钥。服务地址为:```texthttps://api.vikingdb.cn-beijing.volces.com/openviking```-无需安装服务端,也无需在本机配置模型。[产品介绍](https://www.volcengine.com/product/openviking-service)和[服务文档](https://docs.volcengine.com/docs/84313/2374478)说明托管服务的使用方式与额度。继续第 2 步。+无需安装服务端,也无需在本机配置模型。[产品介绍](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 步。### 自建服务diff --git a/docs/zh/getting-started/05-cli-setup.md b/docs/zh/getting-started/05-cli-setup.mdindex 01b85b99a..60ec281a3 100644--- a/docs/zh/getting-started/05-cli-setup.md+++ b/docs/zh/getting-started/05-cli-setup.md@@ -67,7 +67,7 @@ ov config add custom --help| 目标 | 服务地址 | API Key ||---|---|---|-| OpenViking 服务(火山引擎云) | 固定地址,不要传 `--url`。 | 必填。我在[控制台](https://console.volcengine.com/vikingdb/openviking/region:openviking+cn-beijing)的“用户管理 → 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` | 通常不需要。 |@@ -146,7 +146,7 @@ EXECUTE NOW:完成上面的 TODO 列表,达到:`ov config validate` 的检| 服务类型 | 服务地址 | API Key ||---|---|---|-| OpenViking 服务(火山引擎云) | 固定地址,无需填写。 | 必填。在 [OpenViking 控制台](https://console.volcengine.com/vikingdb/openviking/region:openviking+cn-beijing)的**用户管理 → 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` | 默认配置不需要。 |diff --git a/docs/zh/guides/03-deployment.md b/docs/zh/guides/03-deployment.mdindex 7d3703387..da5e56fad 100644--- a/docs/zh/guides/03-deployment.md+++ b/docs/zh/guides/03-deployment.md@@ -6,7 +6,7 @@ OpenViking 以 HTTP 服务运行。安装服务端之前,先选择由谁运行| 服务方式 | 你需要准备什么 || --- | --- |-| [火山引擎托管 OpenViking](https://www.volcengine.com/product/openviking-service) | 在[控制台](https://console.volcengine.com/vikingdb/openviking/region:openviking+cn-beijing)获取 API Key,用独立 CLI 连接,无需本地服务端或模型配置。 |+| [火山引擎托管 OpenViking](https://www.volcengine.com/product/openviking-service?utm_source=opensource_docs&utm_medium=referral&utm_campaign=guides_03-deployment) | 在[控制台](https://console.volcengine.com/vikingdb/openviking/region:openviking+cn-beijing?utm_source=opensource_docs&utm_medium=referral&utm_campaign=guides_03-deployment)获取 API Key,用独立 CLI 连接,无需本地服务端或模型配置。 || 团队已有服务或他人部署 | 向管理员获取服务地址和 user/admin key。 || 自建 OpenViking | 按下文安装、配置和运行服务端。 |diff --git a/examples/hermes-plugin/README.md b/examples/hermes-plugin/README.mdindex 782231288..eca0dfb9f 100644--- a/examples/hermes-plugin/README.md+++ b/examples/hermes-plugin/README.md@@ -46,11 +46,11 @@ separate access.| Connection | What you need ||------------|---------------|| **Quick Local** | A language model already configured in Hermes. Setup installs a local server and embedding model. |-| **OpenViking Service (VolcEngine Cloud)** | A service API key for VolcEngine's [managed OpenViking cloud service](https://www.volcengine.com/product/openviking-service). |+| **OpenViking Service (VolcEngine Cloud)** | A service API key for VolcEngine's [managed OpenViking cloud service](https://www.volcengine.com/product/openviking-service?utm_source=github&utm_medium=referral&utm_campaign=readme). || **Custom** | Your server URL and credentials. Setup can also reuse a saved `ovcli.conf`. |For the cloud service, activate it and create an API key in the-[OpenViking console](https://console.volcengine.com/vikingdb/openviking/region:openviking+cn-beijing).+[OpenViking console](https://console.volcengine.com/vikingdb/openviking/region:openviking+cn-beijing?utm_source=github&utm_medium=referral&utm_campaign=readme).Open **User Management**, then **API Key**. You do not need to install a serveror configure local models.diff --git a/scripts/build_support/readme.py b/scripts/build_support/readme.pyindex 4a6136dde..4528a466c 100644--- a/scripts/build_support/readme.py+++ b/scripts/build_support/readme.py@@ -7,7 +7,9 @@ time so README.md itself can stay relative.import posixpathimport re+from html import escape, unescapefrom pathlib import Path+from urllib.parse import parse_qsl, urlencode, urlsplit, urlunsplitREPO = "volcengine/OpenViking"DEFAULT_REF = "main"@@ -56,4 +58,43 @@ def rewrite_relative_urls(markdown: str, ref: str = DEFAULT_REF) -> str:def pypi_long_description(readme_path: Path, ref: str = DEFAULT_REF) -> str:- return rewrite_relative_urls(readme_path.read_text(encoding="utf-8"), ref)+ """PyPI 复用 README 时移除仅适用于 GitHub 展示的云服务 UTM。"""++ def without_github_utm(target: str) -> str:+ try:+ url = urlsplit(unescape(target))+ except ValueError:+ return target+ managed_service = (+ url.netloc == "www.volcengine.com"+ and url.path.rstrip("/") == "/product/openviking-service"+ ) or (+ url.netloc == "console.volcengine.com"+ and (url.path == "/vikingdb/openviking" or url.path.startswith("/vikingdb/openviking/"))+ )+ if url.scheme != "https" or not managed_service:+ return target+ params = parse_qsl(url.query, keep_blank_values=True)+ if ("utm_source", "github") not in params:+ return target+ utm_keys = {"utm_source", "utm_medium", "utm_campaign", "utm_content", "utm_term"}+ query = urlencode([(key, value) for key, value in params if key not in utm_keys])+ return urlunsplit(url._replace(query=query))++ def html_attr(match: re.Match) -> str:+ attr, target = match.groups()+ if attr != "href":+ return match.group(0)+ next_target = without_github_utm(target)+ return (+ match.group(0) if next_target == target else f'href="{escape(next_target, quote=True)}"'+ )++ def md_link(match: re.Match) -> str:+ bang, text, target, title = match.groups()+ if bang:+ return match.group(0)+ return f"[{text}]({without_github_utm(target)}{title})"++ markdown = rewrite_relative_urls(readme_path.read_text(encoding="utf-8"), ref)+ return _MD_LINK.sub(md_link, _HTML_ATTR.sub(html_attr, markdown))diff --git a/tests/misc/test_readme_long_description.py b/tests/misc/test_readme_long_description.pyindex b98b17ce7..b023d7e4e 100644--- a/tests/misc/test_readme_long_description.py+++ b/tests/misc/test_readme_long_description.py@@ -37,3 +37,24 @@ def test_repository_readme_has_no_relative_targets():targets += re.findall(r"\]\(([^)\s]+)", description)relative = [t for t in targets if not re.match(r"^(?:https?:|mailto:|#)", t)]assert relative == []+++def test_pypi_removes_github_utm_from_cloud_links_only(tmp_path):+ """复用渠道不误标为 GitHub,业务参数、锚点和其他来源保持不变。"""+ readme = tmp_path / "README.md"+ product = "https://www.volcengine.com/product/openviking-service"+ console = "https://console.volcengine.com/vikingdb/openviking/region:openviking+cn-beijing"+ text = (+ f"[云服务]({product}?plan=personal&utm_medium=referral&utm_source=github&utm_campaign=readme#plans) "+ f'<a href="{console}?utm_source=github&utm_content=card&lang=zh&utm_term=agent">控制台</a> '+ f"[文档来源]({product}?utm_source=opensource_docs&utm_medium=referral) "+ "[其他链接](https://example.com/?utm_source=github)"+ )+ readme.write_text(text, encoding="utf-8")+ assert pypi_long_description(readme) == (+ f"[云服务]({product}?plan=personal#plans) "+ f'<a href="{console}?lang=zh">控制台</a> '+ f"[文档来源]({product}?utm_source=opensource_docs&utm_medium=referral) "+ "[其他链接](https://example.com/?utm_source=github)"+ )+ assert readme.read_text(encoding="utf-8") == text