Skip to content

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

feat(docs): preserve UTM attribution across documentation links (#5870)

LaamGinghong107cf0dc79e2
diff --git a/README.md b/README.md
index 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&amp;utm_medium=referral&amp;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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.onBeforeRouteChange
router.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) ?? languageTarget
if (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.md
index 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 your
supported 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 configure
local models.
- **Custom** connects to your own server with its URL and credentials. Setup
diff --git a/docs/en/getting-started/02-quickstart.md b/docs/en/getting-started/02-quickstart.md
index 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:
```text
https://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 server
diff --git a/docs/en/getting-started/05-cli-setup.md b/docs/en/getting-started/05-cli-setup.md
index 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.md
index 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.md
index 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&amp;utm_medium=referral&amp;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.md
index 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&amp;utm_medium=referral&amp;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.mjs
new file mode 100644
index 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.mjs
new file mode 100644
index 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 => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[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.md
index 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.md
index 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** 获取密钥。服务地址为:
```text
https://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.md
index 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.md
index 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.md
index 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 server
or configure local models.
diff --git a/scripts/build_support/readme.py b/scripts/build_support/readme.py
index 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 posixpath
import re
+from html import escape, unescape
from pathlib import Path
+from urllib.parse import parse_qsl, urlencode, urlsplit, urlunsplit
REPO = "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.py
index 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&amp;utm_content=card&amp;lang=zh&amp;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