From 36824d33b75f3e84c994b966013d3b2c110305f1 Mon Sep 17 00:00:00 2001 From: XiaoSeS <87064762+XiaoSeS@users.noreply.github.com> Date: Mon, 2 Nov 2026 15:38:30 +0800 Subject: [PATCH 1/5] docs: complete remaining deployment and navigation gaps in issue 1042 Signed-off-by: XiaoSeS <87064762+XiaoSeS@users.noreply.github.com> --- README.md | 19 ++++++++++++++++- README_zh.md | 16 +++++++++++++- docs/06-api-design.md | 17 +++++++++++++++ docs/README.md | 1 + docs/frontend-analytics-integration.md | 22 ++++++++++++++++++-- docs/security-scanning.md | 9 ++++++++ docs/skillhub/.vitepress/config.ts | 2 ++ docs/skillhub/en/guide/frontend-analytics.md | 10 +++++++++ docs/skillhub/en/guide/index.md | 1 + docs/skillhub/guide/frontend-analytics.md | 10 +++++++++ docs/skillhub/guide/index.md | 1 + weekly/scripts/validate_site.py | 11 ++++++++++ weekly/site/reports/2026-W44/index.html | 2 +- weekly/source.json | 2 +- 14 files changed, 117 insertions(+), 6 deletions(-) create mode 100644 docs/skillhub/en/guide/frontend-analytics.md create mode 100644 docs/skillhub/guide/frontend-analytics.md diff --git a/README.md b/README.md index 73b300d97..13b973023 100644 --- a/README.md +++ b/README.md @@ -282,11 +282,28 @@ curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- u | Parameter | Description | Example | |-----------|-------------|---------| | `--public-url ` | Public access URL (recommended) | `--public-url https://skill.example.com` | -| `--version ` | Specific image tag | `--version v0.2.0` | +| `--version ` | Specific image tag | `--version v0.2.25` | +| `--ref ` | Git ref for deployment files (GitHub raw mode) | `--ref v0.2.25` | | `--aliyun` | Use Aliyun mirror (China) | `--aliyun` | | `--home ` | Runtime directory | `--home /opt/skillhub` | | `--no-scanner` | Disable security scanner | `--no-scanner` | +`--version` selects image tags; it does not pin the deployment files. By default, +those files come from `main`. To pin the installer, Compose file, environment +template and application image tag together, use a released Git ref and tag: + +```bash +curl -fsSL https://raw.githubusercontent.com/iflytek/skillhub/v0.2.25/scripts/runtime.sh | sh -s -- up --ref v0.2.25 --version v0.2.25 --home /opt/skillhub --public-url https://skillhub.your-company.com +``` + +This example uses GitHub raw and requires access to it. `--aliyun` switches runtime +file downloads to the OSS root, where `--ref` does not select a versioned directory. +Likewise, a custom `SKILLHUB_RAW_BASE` takes precedence over the Git-ref URL. +Neither should be described as pinning deployment files with `--ref`. +The script preserves an existing `.env.release`; record its settings and explicit +image overrides separately. Pinning the application tag does not freeze every +dependency image or replace a database backup. + > **Important**: Configure `--public-url` for production deployments to ensure CLI install commands and Agent setup instructions display the correct URLs. For sub-path deployments, keep the public URL and runtime base path aligned in diff --git a/README_zh.md b/README_zh.md index cf1305862..875de021b 100644 --- a/README_zh.md +++ b/README_zh.md @@ -249,11 +249,25 @@ curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- u | 参数 | 说明 | 示例 | |------|------|------| | `--public-url ` | 公网访问地址(推荐配置) | `--public-url https://skill.example.com` | -| `--version ` | 指定镜像版本 | `--version v0.2.0` | +| `--version ` | 指定镜像版本 | `--version v0.2.25` | +| `--ref ` | 指定部署文件的 Git ref(GitHub raw 模式) | `--ref v0.2.25` | | `--aliyun` | 使用阿里云镜像(国内推荐) | `--aliyun` | | `--home ` | 指定运行时目录 | `--home /opt/skillhub` | | `--no-scanner` | 禁用安全扫描服务 | `--no-scanner` | +`--version` 选择镜像标签,不固定部署文件;部署文件默认取自 `main`。 +如需同时固定安装脚本、Compose 清单、环境模板及应用镜像标签,可使用已发布的 ref 和标签: + +```bash +curl -fsSL https://raw.githubusercontent.com/iflytek/skillhub/v0.2.25/scripts/runtime.sh | sh -s -- up --ref v0.2.25 --version v0.2.25 --home /opt/skillhub --public-url https://skillhub.your-company.com +``` + +此例需要能访问 GitHub raw。`--aliyun` 会改用 OSS 根目录下载部署文件, +此时 `--ref` 不会选择版本子目录;自定义 `SKILLHUB_RAW_BASE` 也优先于按 Git ref 生成的地址, +不能把这两种情况称为已通过 `--ref` 固定部署文件。 +脚本保留已有 `.env.release`,请另行记录其中配置及显式镜像覆盖值。 +固定应用镜像标签不等于冻结全部依赖镜像,也不能代替数据库备份。 + > **重要**:生产环境请务必配置 `--public-url`,确保 CLI 安装命令和 Agent 设置指引显示正确的地址。 如果通过 `/skillhub/` 这类子路径对外发布,需要让公网地址和前端基础路径保持一致。 diff --git a/docs/06-api-design.md b/docs/06-api-design.md index 92b48f7df..5ac2e4889 100644 --- a/docs/06-api-design.md +++ b/docs/06-api-design.md @@ -95,6 +95,23 @@ Public API 的可见性规则: - 若 `latest_version_id = null`,即使 `visibility=PUBLIC`,skill 也不会对外公开,只有 owner 可访问 - `hidden=true` 时,普通访客不可访问;仅 owner 或该 namespace 的 `ADMIN` / `OWNER` 可访问 +### 技能详情的公共页面地址 + +`GET /api/v1/skills/{namespace}/{slug}` 的 `data.webUrl` 是可空的 URI 字符串, +指向该技能的 SkillHub 网页详情,而非作者自定义外站地址,也不是 CLI `resolve` 响应字段。 +它只取自部署配置 `skillhub.public.base-url`(环境变量 `SKILLHUB_PUBLIC_BASE_URL`), +不根据请求的 Host 或转发头推测地址,不改变技能原有访问权限。 + +- 有效配置须为带主机的 HTTP(S) 地址,不能包含用户凭据、查询参数或片段。 +- 配置缺省、空白或不符合上述校验时返回 `null`;客户端应隐藏该跳转入口,不拼造链接。 +- 保留公开地址中的子路径,去掉结尾斜杠,再追加 `/space/{namespace}/{slug}`。 + 两个路径段分别按 UTF-8 URL 编码,空格为 `%20`,段内斜杠为 `%2F`。 +- 例如公开地址 `https://skills.example.com/portal/` 和技能 `team/demo`, + 返回 `https://skills.example.com/portal/space/team/demo`。 + +实现与边界测试:[SkillWebUrls](../server/skillhub-app/src/main/java/com/iflytek/skillhub/service/SkillWebUrls.java)、 +[SkillWebUrlsTest](../server/skillhub-app/src/test/java/com/iflytek/skillhub/service/SkillWebUrlsTest.java)。 + `GET /api/v1/skills/{namespace}/{slug}/versions/{version}` 的 `data` 字段除版本基础信息外,还必须包含: - `parsedMetadataJson`:`SKILL.md` frontmatter 的完整 JSON 序列化结果 diff --git a/docs/README.md b/docs/README.md index e0c505c0f..c437494ca 100644 --- a/docs/README.md +++ b/docs/README.md @@ -18,6 +18,7 @@ Use the documentation site for user workflows, repository guides for engineering - [Docker deployment and upgrades](skillhub/en/guide/deployment.md) / [中文](skillhub/guide/deployment.md) - [Kubernetes](skillhub/en/guide/kubernetes.md) / [中文](skillhub/guide/kubernetes.md) +- [Optional frontend analytics](skillhub/en/guide/frontend-analytics.md) / [前端动作统计](skillhub/guide/frontend-analytics.md) - [Deployment reference](09-deployment.md), [object storage](object-storage.md), [SMTP and password reset](19-smtp-password-reset-email-setup.md) - [Security scanning](security-scanning.md), [observability](observability-developer-guide.md), [private SSO integration](12-private-sso-integration-playbook.md) diff --git a/docs/frontend-analytics-integration.md b/docs/frontend-analytics-integration.md index ad1c5e942..183a39df9 100644 --- a/docs/frontend-analytics-integration.md +++ b/docs/frontend-analytics-integration.md @@ -160,13 +160,31 @@ window.skillhubAnalytics.stop() stop 不能撤回已开始的 fetch。重新获准后才可调用 start();同一个 root 重复初始化保留第一次规则和回调,修改规则需要先 stop 再初始化。 -7. 将入口恢复 `enabled: false`,重新创建 edge。保持「Disable cache」勾选(或换一个新的无痕窗口),刷新页面后再搜索:不得加载 script.js、产生采集回调或 send。完全不注入时也应零采集。最后在隔离演示中停止 Umami,再打开新页面搜索和打开技能卡片,应仍正常,无统计依赖导致的页面错误: +7. **关闭态独立验收**:将入口恢复 `enabled: false`,重新创建 edge: + +```sh +docker compose -f docs/examples/analytics/compose.yaml up -d --no-deps --force-recreate edge +``` + +保持「Disable cache」勾选(或换一个新的无痕窗口),刷新页面后搜索:不得加载 script.js、产生采集回调或 send,搜索与技能卡片仍正常。完全不注入时也应零采集。这一步不验证启用态的故障隔离。 + +8. **启用态依赖故障验收**:仅在上述隔离演示中,将入口重新设为 `enabled: true`,保留第 2 节创建的有效网站 UUID,并确认当前授权允许采集;按第 7 步重新创建 edge,禁用缓存并刷新。先重复第 3~5 步,确认一次测试动作确实入库,作为故障前对照。不要为了测试停止共享平台或生产服务。 + +保持入口启用和授权有效,仅停止演示 Umami: ```sh docker compose -f docs/examples/analytics/compose.yaml stop umami ``` -验收后如需继续演示,使用上面的 up 命令恢复。不要为了测试停止共享平台或生产服务。 +在已加载 SDK 的页面再次搜索,应观察到采集请求失败,同时搜索结果和技能卡片仍正常。再新开一个禁用缓存的页面:SDK 请求应失败,但业务仍可用,不能出现统计异常导致的未捕获页面错误。记录失败请求和业务结果;不要把关闭态的零请求当成故障隔离通过,也不要把失败请求当作成功入库。 + +9. **恢复或清理**:继续演示时执行: + +```sh +docker compose -f docs/examples/analytics/compose.yaml start umami +``` + +等待 `http://localhost:8300` 恢复可用后,禁用缓存并刷新 edge 页面,再执行一次新动作,确认请求成功且新事件入库。原页面的 SDK 初始化失败不会保证自动恢复,故障期间丢失的事件也不保证补发。结束演示则按第 7 节关闭采集、恢复入口文件,并仅清理该演示项目;不要删除现有 SkillHub 或共享平台的数据。 ## 6. 故障排查 diff --git a/docs/security-scanning.md b/docs/security-scanning.md index 536ce465a..ae3723c7e 100644 --- a/docs/security-scanning.md +++ b/docs/security-scanning.md @@ -81,6 +81,15 @@ Scanner-side optional environment variables: - `SKILLHUB_SCANNER_HARD_TIMEOUT_SECONDS` (default `930`) - `SKILLHUB_SCANNER_MAX_UPLOAD_SIZE_BYTES` (default `110100480`, or 105 MiB) +For `SKILLHUB_SCANNER_MAX_UPLOAD_SIZE_BYTES`, prefer an integer byte value such as +`110100480` (105 MiB). The scanner also accepts scientific notation when the value +is an exact finite integer, for example `1.1010048e+08`; this accommodates Helm +serialization. Fractional values, non-finite values and invalid text are rejected +at scanner startup rather than silently rounded. Zero and negative integer values +are clamped to `1` byte, not interpreted as unlimited. Scientific-notation values +must also fit the platform's supported integer range. This scanner-side limit does +not override separate proxy or server upload limits. + If the LLM variables are absent, the scanner should still run with non-LLM analyzers. The default timeout ordering is server read timeout (900 seconds), scanner hard timeout (930 seconds), then pending-message reclaim (960 seconds). A hard timeout exits the scanner process diff --git a/docs/skillhub/.vitepress/config.ts b/docs/skillhub/.vitepress/config.ts index 59bbd3cd4..169c1fae4 100644 --- a/docs/skillhub/.vitepress/config.ts +++ b/docs/skillhub/.vitepress/config.ts @@ -70,6 +70,7 @@ export default defineConfig({ items: [ { text: 'Docker 部署', link: '/guide/deployment' }, { text: 'Kubernetes 部署', link: '/guide/kubernetes' }, + { text: '前端动作统计', link: '/guide/frontend-analytics' }, { text: '技能头像与审核', link: '/guide/skill-avatars' }, ], }, @@ -144,6 +145,7 @@ export default defineConfig({ items: [ { text: 'Deploy with Docker', link: '/en/guide/deployment' }, { text: 'Deploy on Kubernetes', link: '/en/guide/kubernetes' }, + { text: 'Frontend analytics', link: '/en/guide/frontend-analytics' }, { text: 'Skill avatars and moderation', link: '/en/guide/skill-avatars' }, ], }, diff --git a/docs/skillhub/en/guide/frontend-analytics.md b/docs/skillhub/en/guide/frontend-analytics.md new file mode 100644 index 000000000..3fb30cf95 --- /dev/null +++ b/docs/skillhub/en/guide/frontend-analytics.md @@ -0,0 +1,10 @@ +# Frontend analytics + +SkillHub does not collect frontend actions or load an analytics SDK by default. Pages expose passive semantic attributes; deployment owners choose an integration under their consent and privacy policies. + +The delivered example is a manual integration: the deployment owner maintains the collector entry, adapter, and proxy configuration. Configuration-only activation and lazy loading through Docker/Compose or Helm remain follow-up work, not current deployment instructions. + +- [English interface and privacy contract](https://github.com/iflytek/skillhub/blob/main/docs/frontend-analytics.md): event meaning, adapter boundaries, transport fields, and sub-path mapping. +- [Step-by-step integration guide (Chinese)](https://github.com/iflytek/skillhub/blob/main/docs/frontend-analytics-integration.md): reuse a platform or run an isolated Umami demo, configure rules, verify stored events, separately test disabled collection and enabled dependency failure, then recover or clean up. + +A download click expresses intent, not successful download, installation, or execution. Keep administration secrets out of the browser. Platform retention, access control, and compliance belong to the deployment owner. These links follow repository main; pinned deployments should use documentation and examples from the matching tag. diff --git a/docs/skillhub/en/guide/index.md b/docs/skillhub/en/guide/index.md index 6b4dcdb35..753d1bc61 100644 --- a/docs/skillhub/en/guide/index.md +++ b/docs/skillhub/en/guide/index.md @@ -37,6 +37,7 @@ Read these guides when you need to run your own registry. Choose a deployment me - [Deploy with Docker](./deployment.md): installation, configuration, upgrades, and backups. - [Deploy on Kubernetes](./kubernetes.md): cluster and Helm deployment. +- [Frontend analytics](./frontend-analytics.md): optional manual integration, consent, and failure acceptance. - [Skill avatars and moderation](./skill-avatars.md): administrator configuration for image moderation providers. ## Develop and integrate diff --git a/docs/skillhub/guide/frontend-analytics.md b/docs/skillhub/guide/frontend-analytics.md new file mode 100644 index 000000000..d2e5949b2 --- /dev/null +++ b/docs/skillhub/guide/frontend-analytics.md @@ -0,0 +1,10 @@ +# 前端动作统计 + +SkillHub 默认不采集前端动作、不加载统计 SDK。页面提供被动的语义标签,部署方可按自身授权和隐私策略选择接入。 + +当前已交付的是手动接入示例:部署方维护采集入口、适配器及代理配置。Docker/Compose 或 Helm 配置化开启、按需加载的能力仍在后续 PR 中推进,不能将其作为当前部署步骤。 + +- [中文接入指南](https://github.com/iflytek/skillhub/blob/main/docs/frontend-analytics-integration.md):复用已有平台或在隔离环境运行 Umami 演示,配置规则、检查真实入库、分别验证关闭态和启用态故障,最后恢复或清理。 +- [英文接口与隐私契约](https://github.com/iflytek/skillhub/blob/main/docs/frontend-analytics.md):事件含义、适配器边界、传输字段及子路径映射。 + +点击下载只表示下载意图,不证明下载、安装或执行成功。不要把管理密钥放到浏览器;平台数据保留、访问控制和合规由部署方负责。指南对应仓库 main;固定版本部署应阅读相同 tag 的文档与示例。 diff --git a/docs/skillhub/guide/index.md b/docs/skillhub/guide/index.md index b6ef57dd7..57247860c 100644 --- a/docs/skillhub/guide/index.md +++ b/docs/skillhub/guide/index.md @@ -37,6 +37,7 @@ - [Docker 部署](./deployment.md):安装、配置、升级和备份。 - [Kubernetes 部署](./kubernetes.md):集群和 Helm 部署。 +- [前端动作统计](./frontend-analytics.md):可选手动接入、授权与故障验收。 - [技能头像与审核](./skill-avatars.md):管理员配置图片审核服务。 ## 开发与集成 diff --git a/weekly/scripts/validate_site.py b/weekly/scripts/validate_site.py index 64e4d1dfe..aef060c9e 100755 --- a/weekly/scripts/validate_site.py +++ b/weekly/scripts/validate_site.py @@ -50,6 +50,8 @@ class PageParser(HTMLParser): self.empty_table_count = 0 self.ids: set[str] = set() self.duplicate_ids: set[str] = set() + self.skip_targets: set[str] = set() + self.main_ids: set[str] = set() self.external_assets: list[str] = [] self.non_content_depth = 0 @@ -70,6 +72,12 @@ class PageParser(HTMLParser): if element_id in self.ids: self.duplicate_ids.add(element_id) self.ids.add(element_id) + if tag == "main" and element_id: + self.main_ids.add(element_id) + if tag == "a" and "skip-link" in (values.get("class") or "").split(): + href = values.get("href") or "" + if href.startswith("#"): + self.skip_targets.add(href[1:]) if tag == "h1": self.h1_count += 1 if values.get("role") == "tab": @@ -237,6 +245,9 @@ def validate(root: Path) -> list[str]: ) if empty_panels: errors.append(f"{index_path}: panels without modules: {empty_panels}") + for target in sorted(parser.skip_targets): + if target not in parser.main_ids: + errors.append(f"{index_path}: skip link target #{target} must identify main") if parser.duplicate_ids: errors.append(f"{index_path}: duplicate ids: {sorted(parser.duplicate_ids)}") if parser.external_assets: diff --git a/weekly/site/reports/2026-W44/index.html b/weekly/site/reports/2026-W44/index.html index 4ec336fe8..5c4568e70 100644 --- a/weekly/site/reports/2026-W44/index.html +++ b/weekly/site/reports/2026-W44/index.html @@ -1246,7 +1246,7 @@ footer { -
+

先看仓库规模和协作流转,再看已经交付与仍待验证的内容。

事件统计覆盖完整的 7 天周期;库存与开放队列取采集快照。

一、仓库关键信息

diff --git a/weekly/source.json b/weekly/source.json index 14f613550..d5b2d87b5 100644 --- a/weekly/source.json +++ b/weekly/source.json @@ -1,4 +1,4 @@ { "repository": "https://github.com/XiaoSeS/skillhub-weekly.git", - "commit": "6c1e530394585fa11ac9ccab370c6b1b28dc0563" + "commit": "13a95bb287e341150e5bd95461a2284a7daf6576" } From 4334b34ec1994aad5563164131ac78a13bcd5d34 Mon Sep 17 00:00:00 2001 From: XiaoSeS <87064762+XiaoSeS@users.noreply.github.com> Date: Mon, 2 Nov 2026 15:40:41 +0800 Subject: [PATCH 2/5] docs(scanner): clarify positive scientific notation range Signed-off-by: XiaoSeS <87064762+XiaoSeS@users.noreply.github.com> --- docs/security-scanning.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/security-scanning.md b/docs/security-scanning.md index ae3723c7e..f96d4ffa7 100644 --- a/docs/security-scanning.md +++ b/docs/security-scanning.md @@ -86,8 +86,8 @@ For `SKILLHUB_SCANNER_MAX_UPLOAD_SIZE_BYTES`, prefer an integer byte value such is an exact finite integer, for example `1.1010048e+08`; this accommodates Helm serialization. Fractional values, non-finite values and invalid text are rejected at scanner startup rather than silently rounded. Zero and negative integer values -are clamped to `1` byte, not interpreted as unlimited. Scientific-notation values -must also fit the platform's supported integer range. This scanner-side limit does +are clamped to `1` byte, not interpreted as unlimited. Positive scientific-notation +values must also fit the platform's supported integer range. This scanner-side limit does not override separate proxy or server upload limits. If the LLM variables are absent, the scanner should still run with non-LLM analyzers. From 00a7b8679c4362910115906b8254fb7d7370bd2d Mon Sep 17 00:00:00 2001 From: XiaoSeS <87064762+XiaoSeS@users.noreply.github.com> Date: Mon, 2 Nov 2026 15:58:35 +0800 Subject: [PATCH 3/5] docs(analytics): provide concise in-site integration reading Signed-off-by: XiaoSeS <87064762+XiaoSeS@users.noreply.github.com> --- docs/frontend-analytics-integration.md | 18 +++++++---- docs/frontend-analytics.md | 20 ++++++++----- .../en/guide/frontend-analytics-guide.md | 12 ++++++++ .../en/guide/frontend-analytics-reference.md | 12 ++++++++ docs/skillhub/en/guide/frontend-analytics.md | 30 +++++++++++++++---- .../guide/frontend-analytics-guide.md | 12 ++++++++ .../guide/frontend-analytics-reference.md | 12 ++++++++ docs/skillhub/guide/frontend-analytics.md | 30 +++++++++++++++---- 8 files changed, 122 insertions(+), 24 deletions(-) create mode 100644 docs/skillhub/en/guide/frontend-analytics-guide.md create mode 100644 docs/skillhub/en/guide/frontend-analytics-reference.md create mode 100644 docs/skillhub/guide/frontend-analytics-guide.md create mode 100644 docs/skillhub/guide/frontend-analytics-reference.md diff --git a/docs/frontend-analytics-integration.md b/docs/frontend-analytics-integration.md index 183a39df9..00c69021e 100644 --- a/docs/frontend-analytics-integration.md +++ b/docs/frontend-analytics-integration.md @@ -1,10 +1,11 @@ # 前端动作统计接入指南 + ## 1. 先了解边界 SkillHub 页面只提供被动的 `data-analytics-id` 标签,默认不采集、不加载统计 SDK、不发送事件。可选 helper 把允许的原生交互转换成 `{ id, event }`,再交给部署方选择的 adapter。点击下载只表示下载意图,不表示下载、安装成功;提交发布也不表示发布成功。部署方负责授权、隐私合规、保留期限和平台安全。 -本文对应 PR-1(#1010)的手工接入示例,不是产品内置开关。仅通过 Docker/Compose 或 Helm 配置开启、默认关闭和按需加载的能力计划在 PR-2 交付,见 [OpenSpec 变更](../openspec/changes/add-configurable-frontend-analytics/proposal.md)。Issue #989 要等 PR-2 完成并验证后才关闭。精确接口、事件边界和隐私约束以[英文契约](frontend-analytics.md)为准。 +本文对应 PR-1(#1010)的手工接入示例,不是产品内置开关。仅通过 Docker/Compose 或 Helm 配置开启、默认关闭和按需加载的能力计划在 PR-2 交付,见 [OpenSpec 变更](https://github.com/iflytek/skillhub/blob/main/openspec/changes/add-configurable-frontend-analytics/proposal.md)。Issue #989 要等 PR-2 完成并验证后才关闭。精确接口、事件边界和隐私约束以[英文契约][analytics-reference]为准。 ## 2. 选择接入路径 @@ -12,8 +13,8 @@ SkillHub 页面只提供被动的 `data-analytics-id` 标签,默认不采集 先确认平台接收地址、公开站点标识、授权策略和 CSP。不要把平台管理密钥放到浏览器。平台不受支持时,需要部署方编写自己的 adapter;当前版本不能只填平台名字就接入任意平台。 -1. 复用 [helper](examples/analytics/observe/v1/skillhub-intents.mjs),不要修改业务页面或引入厂商 SDK。 -2. 参照 [Umami adapter](examples/analytics/observe/v1/umami-adapter.mjs)实现 `send(intent) -> Promise` 和 `stop()`。send 必须消化同步异常和异步拒绝,不向页面抛错;stop 后不能再派发请求,已经开始的 fetch 无法撤回。 +1. 复用 [helper](https://github.com/iflytek/skillhub/blob/main/docs/examples/analytics/observe/v1/skillhub-intents.mjs),不要修改业务页面或引入厂商 SDK。 +2. 参照 [Umami adapter](https://github.com/iflytek/skillhub/blob/main/docs/examples/analytics/observe/v1/umami-adapter.mjs)实现 `send(intent) -> Promise` 和 `stop()`。send 必须消化同步异常和异步拒绝,不向页面抛错;stop 后不能再派发请求,已经开始的 fetch 无法撤回。 3. 由 adapter 验证平台参数、清洗最终发送字段、管理 SDK 加载和超时。不要只清洗 helper 回调后就信任 SDK 自动附加的 URL、标题或身份字段。 4. 在部署方入口中连接 helper 与 adapter,只有策略允许时才初始化: @@ -122,7 +123,7 @@ node web/scripts/analytics-manifest.mjs --write node web/scripts/analytics-manifest.mjs ``` -审核生成的 [manifest](frontend-analytics-manifest.json) 差异和原生交互测试。部署方再加一条规则即可。ID 必须匹配 `^[a-z]+(?:\.[a-z]+){2,}$`:至少三段小写字母,不含数字、下划线或资源信息。已有 ID 含义冻结,不能把用户、技能名、版本、路径拼进去。manifest 是版本清单,不是运行时封闭枚举。 +审核生成的 [manifest](https://github.com/iflytek/skillhub/blob/main/docs/frontend-analytics-manifest.json) 差异和原生交互测试。部署方再加一条规则即可。ID 必须匹配 `^[a-z]+(?:\.[a-z]+){2,}$`:至少三段小写字母,不含数字、下划线或资源信息。已有 ID 含义冻结,不能把用户、技能名、版本、路径拼进去。manifest 是版本清单,不是运行时封闭枚举。 ## 4. 部署、子路径和 CSP @@ -132,7 +133,7 @@ edge 仅在 UI HTML 注入一个延迟执行的 module,不改变 API、登录 根路径演示的 CSP 需要允许同源外部 module 和同源连接。保留原有 CSP;nonce-only 或 strict-dynamic 策略不能只靠同源满足。需要部署方协调每响应 nonce 或已批准的 hash/SRI;做不到就不要启用。不要加 unsafe-inline、unsafe-eval 或通配符。还要保留原安全头,注意 Nginx add_header 的 location 继承规则。 -`/skillhub/` 等子路径不是只改一个 URL。先按正常部署方式配置 `SKILLHUB_WEB_BASE_PATH=/skillhub/` 和匹配的同源 API base,再同时调整 UI location、无尾斜线重定向、旁路正则、模块目录/注入 src、两个 Umami 精确端点和 adapter prefix。edge 到 Web 的 proxy_pass 不带尾斜线,保留原 URI,不能再次重写。逐项配置见[英文契约的子路径映射](frontend-analytics.md#supported-sub-path-mapping)。OAuth、公网 HTTPS 和资源地址仍遵守原部署要求。 +`/skillhub/` 等子路径不是只改一个 URL。先按正常部署方式配置 `SKILLHUB_WEB_BASE_PATH=/skillhub/` 和匹配的同源 API base,再同时调整 UI location、无尾斜线重定向、旁路正则、模块目录/注入 src、两个 Umami 精确端点和 adapter prefix。edge 到 Web 的 proxy_pass 不带尾斜线,保留原 URI,不能再次重写。逐项配置见[英文契约的子路径映射][analytics-subpaths]。OAuth、公网 HTTPS 和资源地址仍遵守原部署要求。 ## 5. 验收:照这个顺序检查 @@ -215,4 +216,9 @@ docker compose -f docs/examples/analytics/compose.yaml down -v - 尽力发送,无重试、无持久队列,可能少计。SDK 加载期最多在内存暂存 20 条,默认最多等三秒;超额、失败、超时或 stop 都丢弃。已就绪发送彼此独立,不因一个请求挂起而阻塞后续动作。 - 示例固定 Umami 3.4.1。stop 的派发保护依赖此版本在 fetch 前同步序列化的顺序,升级必须重跑适配器测试和真实浏览器验收;不要同时加载第二个 Umami tracker。 - JSON 字段少不等于匿名传输。IP、User-Agent、Origin 仍到平台;SDK 还带网站、实际 hostname 和后续会话 cache 头。edge 去掉采集代理的 Cookie、Authorization、Referer,并使用 no-referrer。Umami 仍可能据传输元数据推导浏览器、系统、设备、地域和会话。 -- SDK 在清洗前仍会在页面内读取标题、URL、referrer 和自身 localStorage 开关;通用 helper 不读取这些内容。平台日志、数据保留和权限需另审计,详见[隐私契约](frontend-analytics.md#privacy-and-integration-modes)。 +- SDK 在清洗前仍会在页面内读取标题、URL、referrer 和自身 localStorage 开关;通用 helper 不读取这些内容。平台日志、数据保留和权限需另审计,详见[隐私契约][analytics-privacy]。 + + +[analytics-reference]: frontend-analytics.md +[analytics-subpaths]: frontend-analytics.md#supported-sub-path-mapping +[analytics-privacy]: frontend-analytics.md#privacy-and-integration-modes diff --git a/docs/frontend-analytics.md b/docs/frontend-analytics.md index 621b6d0d6..6be1b6162 100644 --- a/docs/frontend-analytics.md +++ b/docs/frontend-analytics.md @@ -1,8 +1,9 @@ # Passive frontend analytics attributes -For step-by-step setup, see the [Chinese integration guide](frontend-analytics-integration.md). + +For step-by-step setup, see the [Chinese integration guide][analytics-guide]. This document is the English contract reference. Configuration-only deployment is -planned in [PR-2](../openspec/changes/add-configurable-frontend-analytics/proposal.md); +planned in [PR-2](https://github.com/iflytek/skillhub/blob/main/openspec/changes/add-configurable-frontend-analytics/proposal.md); the current examples remain deployment-owned and opt-in. SkillHub exposes semantic HTML attributes for separately maintained, optional @@ -57,7 +58,7 @@ The source inventory covers these domains: - Notifications/preferences, account/profile/security/token flows, login, registration/reset/device/CLI authorization, administration and global navigation. -[The generated manifest](frontend-analytics-manifest.json) is the authoritative +[The generated manifest](https://github.com/iflytek/skillhub/blob/main/docs/frontend-analytics-manifest.json) is the authoritative source index: registered routes and their implementations, literal JSX sites, conditional values, static navigation definitions and forwarding sites. Counts are recomputed from the TypeScript AST; they are not quotas. Unique IDs are @@ -166,7 +167,7 @@ incident. Vendor credentials and ingestion endpoints belong outside core. ## Configure rules and add tags -[The vendor-neutral helper](examples/analytics/observe/v1/skillhub-intents.mjs) +[The vendor-neutral helper](https://github.com/iflytek/skillhub/blob/main/docs/examples/analytics/observe/v1/skillhub-intents.mjs) exports `observeSkillhubIntents({ root, rules, onIntent })`, frozen `DEFAULT_RULES` (the original 12 categories), and pure `resolveRules(rules)`: @@ -220,7 +221,7 @@ example is not present in the `web/` Docker build context. ## Connect a platform: local Umami v3.4.1 demo -[The Compose example](examples/analytics/compose.yaml) runs Umami v3.4.1 (MIT), +[The Compose example](https://github.com/iflytek/skillhub/blob/main/docs/examples/analytics/compose.yaml) runs Umami v3.4.1 (MIT), Postgres 16 and an optional edge; SkillHub remains your existing web upstream. From the repository root: @@ -242,13 +243,13 @@ an isolated local Docker environment with available network pools. Open `http://localhost:8300` for local setup only. Umami's default `admin` / `umami` credentials, the public DB password and app secret are DEMO ONLY: change them. Create a synthetic website in Umami, copy its UUID into -[`observer.mjs`](examples/analytics/observe/v1/observer.mjs), then explicitly change +[`observer.mjs`](https://github.com/iflytek/skillhub/blob/main/docs/examples/analytics/observe/v1/observer.mjs), then explicitly change `enabled` and the consent hook for your local policy. Open SkillHub through `http://localhost:8081` and exercise an enabled action; inspect the request to `/_skillhub-umami/api/send` and Umami's event view. Tear down the local demo with `docker compose -f docs/examples/analytics/compose.yaml down -v` (demo data is removed). -[`umami-adapter.mjs`](examples/analytics/observe/v1/umami-adapter.mjs) is the only +[`umami-adapter.mjs`](https://github.com/iflytek/skillhub/blob/main/docs/examples/analytics/observe/v1/umami-adapter.mjs) is the only vendor-specific code. It loads `/script.js` with `data-auto-track="false"`, so v3.4.1 installs no pageview, history hook, click listener or performance observer. `data-host-url` is the same-origin `/_skillhub-umami` prefix, and @@ -315,7 +316,7 @@ HTML is the deployment rollback; default SkillHub never loads any of this. Prefer a separately maintained same-origin HTTPS module, optionally inserted by Nginx `sub_filter`, not an app entrypoint modification. Start with -[the opt-in edge template](examples/analytics/nginx.conf). It is not loaded by the +[the opt-in edge template](https://github.com/iflytek/skillhub/blob/main/docs/examples/analytics/nginx.conf). It is not loaded by the product. Compose substitutes only the two upstream host:port variables. Publish its HTTP listener on loopback behind your HTTPS terminator. Serve the supplied `observer.mjs`, helper and adapter outside the app bundle; only enable the entry @@ -390,3 +391,6 @@ configuration, reload through the normal deployment procedure, and purge cached HTML. Existing cached versioned JS can remain temporarily but must not be referenced or initialized. Verify new HTML has no script, no callback/reporting occurs and SkillHub remains usable. This document does not authorize production changes. + + +[analytics-guide]: frontend-analytics-integration.md diff --git a/docs/skillhub/en/guide/frontend-analytics-guide.md b/docs/skillhub/en/guide/frontend-analytics-guide.md new file mode 100644 index 000000000..093e6aafa --- /dev/null +++ b/docs/skillhub/en/guide/frontend-analytics-guide.md @@ -0,0 +1,12 @@ +# Detailed setup (Chinese) + +The detailed setup instructions below are currently available in Chinese. Validate the example in an isolated environment first. + +[← Back to overview](./frontend-analytics.md) + + + +[analytics-guide]: ./frontend-analytics-guide.md +[analytics-reference]: ./frontend-analytics-reference.md +[analytics-subpaths]: ./frontend-analytics-reference.md#supported-sub-path-mapping +[analytics-privacy]: ./frontend-analytics-reference.md#privacy-and-integration-modes diff --git a/docs/skillhub/en/guide/frontend-analytics-reference.md b/docs/skillhub/en/guide/frontend-analytics-reference.md new file mode 100644 index 000000000..c2736f8ed --- /dev/null +++ b/docs/skillhub/en/guide/frontend-analytics-reference.md @@ -0,0 +1,12 @@ +# Interface and privacy contract + +This contract is in English. Detailed setup instructions are currently available in Chinese. + +[← Back to overview](./frontend-analytics.md) + + + +[analytics-guide]: ./frontend-analytics-guide.md +[analytics-reference]: ./frontend-analytics-reference.md +[analytics-subpaths]: ./frontend-analytics-reference.md#supported-sub-path-mapping +[analytics-privacy]: ./frontend-analytics-reference.md#privacy-and-integration-modes diff --git a/docs/skillhub/en/guide/frontend-analytics.md b/docs/skillhub/en/guide/frontend-analytics.md index 3fb30cf95..8e21802a3 100644 --- a/docs/skillhub/en/guide/frontend-analytics.md +++ b/docs/skillhub/en/guide/frontend-analytics.md @@ -1,10 +1,30 @@ # Frontend analytics -SkillHub does not collect frontend actions or load an analytics SDK by default. Pages expose passive semantic attributes; deployment owners choose an integration under their consent and privacy policies. +Collection and SDK loading are off by default. The delivered example is a **manual integration**; configuration-only activation through Docker/Compose or Helm has not been merged. Click events express intent, not successful downloads, publishing, or execution. -The delivered example is a manual integration: the deployment owner maintains the collector entry, adapter, and proxy configuration. Configuration-only activation and lazy loading through Docker/Compose or Helm remain follow-up work, not current deployment instructions. +## Connect a platform -- [English interface and privacy contract](https://github.com/iflytek/skillhub/blob/main/docs/frontend-analytics.md): event meaning, adapter boundaries, transport fields, and sub-path mapping. -- [Step-by-step integration guide (Chinese)](https://github.com/iflytek/skillhub/blob/main/docs/frontend-analytics-integration.md): reuse a platform or run an isolated Umami demo, configure rules, verify stored events, separately test disabled collection and enabled dependency failure, then recover or clean up. +1. **Choose a platform**: reuse one or run the isolated Umami demo. Never use demo credentials in production. +2. **Configure collection**: provide a valid website UUID, selected actions, and an explicit consent check. Deployment owners maintain the entry module, adapter, and proxy. +3. **Verify before enabling access**: check outgoing fields and stored events, then confirm disabled collection and platform failure leave normal business flows working. -A download click expresses intent, not successful download, installation, or execution. Keep administration secrets out of the browser. Platform retention, access control, and compliance belong to the deployment owner. These links follow repository main; pinned deployments should use documentation and examples from the matching tag. +The [detailed setup guide (Chinese)](./frontend-analytics-guide.md) contains commands, rules, sub-paths, and recovery steps. The [interface and privacy contract (English)](./frontend-analytics-reference.md) defines event and adapter boundaries. + +## Acceptance checks + +| Scenario | Expected result | +| --- | --- | +| Disabled by default | No analytics SDK or events; business flows work | +| Enabled with consent | One corresponding event per action, actually stored; no search terms or identity fields | +| Platform fails while enabled | Collection fails, but search and skill pages still work | +| Platform recovers | Refresh to verify new stored events; lost events are not guaranteed to replay | + +## Common questions + +- **No data?** Check the demo edge entry, consent, website UUID, rules, and cache. HTTP 200 alone does not prove storage. +- **Can any platform work by setting its URL?** No. Other platforms need an adapter and reviewed proxy endpoints. +- **Is collection anonymous?** A small JSON payload is not anonymous transport. IP and User-Agent may still reach the platform. Deployment owners handle access control, retention, and compliance. + +## Disable collection + +Use `window.skillhubAnalytics.stop()` to stop future dispatch in the current page; already dispatched requests cannot be recalled. For persistent disabling, restore `enabled: false`, recreate edge, and refresh with cache disabled. Remove the injection/edge and return to the original Web entry to remove the integration entirely. Follow the detailed guide to clean up only the isolated demo, never shared platform or business data. diff --git a/docs/skillhub/guide/frontend-analytics-guide.md b/docs/skillhub/guide/frontend-analytics-guide.md new file mode 100644 index 000000000..378c4e9ef --- /dev/null +++ b/docs/skillhub/guide/frontend-analytics-guide.md @@ -0,0 +1,12 @@ +# 详细接入操作(中文) + +以下步骤适用于当前手动接入示例,请先在隔离环境验证。 + +[← 返回接入概览](./frontend-analytics.md) + + + +[analytics-guide]: ./frontend-analytics-guide.md +[analytics-reference]: ./frontend-analytics-reference.md +[analytics-subpaths]: ./frontend-analytics-reference.md#supported-sub-path-mapping +[analytics-privacy]: ./frontend-analytics-reference.md#privacy-and-integration-modes diff --git a/docs/skillhub/guide/frontend-analytics-reference.md b/docs/skillhub/guide/frontend-analytics-reference.md new file mode 100644 index 000000000..d8b2de725 --- /dev/null +++ b/docs/skillhub/guide/frontend-analytics-reference.md @@ -0,0 +1,12 @@ +# 接口与隐私契约(英文) + +本页契约正文为英文,详细操作步骤见中文指南。 + +[← 返回接入概览](./frontend-analytics.md) + + + +[analytics-guide]: ./frontend-analytics-guide.md +[analytics-reference]: ./frontend-analytics-reference.md +[analytics-subpaths]: ./frontend-analytics-reference.md#supported-sub-path-mapping +[analytics-privacy]: ./frontend-analytics-reference.md#privacy-and-integration-modes diff --git a/docs/skillhub/guide/frontend-analytics.md b/docs/skillhub/guide/frontend-analytics.md index d2e5949b2..d5337fcc2 100644 --- a/docs/skillhub/guide/frontend-analytics.md +++ b/docs/skillhub/guide/frontend-analytics.md @@ -1,10 +1,30 @@ # 前端动作统计 -SkillHub 默认不采集前端动作、不加载统计 SDK。页面提供被动的语义标签,部署方可按自身授权和隐私策略选择接入。 +默认不采集、不加载统计 SDK。当前提供**手动接入示例**;通过 Docker/Compose 或 Helm 配置直接开启的能力尚未合并。点击事件只表示操作意图,不证明下载、发布或执行成功。 -当前已交付的是手动接入示例:部署方维护采集入口、适配器及代理配置。Docker/Compose 或 Helm 配置化开启、按需加载的能力仍在后续 PR 中推进,不能将其作为当前部署步骤。 +## 如何接入 -- [中文接入指南](https://github.com/iflytek/skillhub/blob/main/docs/frontend-analytics-integration.md):复用已有平台或在隔离环境运行 Umami 演示,配置规则、检查真实入库、分别验证关闭态和启用态故障,最后恢复或清理。 -- [英文接口与隐私契约](https://github.com/iflytek/skillhub/blob/main/docs/frontend-analytics.md):事件含义、适配器边界、传输字段及子路径映射。 +1. **选平台**:已有平台可复用;没有平台可先运行隔离的 Umami 演示。不要把演示密码用于生产。 +2. **配置采集**:准备有效网站 UUID、需要采集的动作与明确授权判断;部署方维护采集入口、适配器和代理。 +3. **验收再开放**:检查请求字段和真实入库,并验证关闭与平台故障不影响正常业务。 -点击下载只表示下载意图,不证明下载、安装或执行成功。不要把管理密钥放到浏览器;平台数据保留、访问控制和合规由部署方负责。指南对应仓库 main;固定版本部署应阅读相同 tag 的文档与示例。 +[详细操作指南(中文)](./frontend-analytics-guide.md)提供命令、规则、子路径与恢复步骤;[接口与隐私契约(英文)](./frontend-analytics-reference.md)定义事件及适配器边界。 + +## 验收看什么 + +| 场景 | 应观察到什么 | +| --- | --- | +| 默认关闭 | 不加载统计 SDK、不发送事件,业务正常 | +| 已启用且获得授权 | 一次动作一条对应事件,平台确实入库;不传搜索词或身份字段 | +| 启用后平台故障 | 请求失败但搜索、技能页面仍可用 | +| 平台恢复 | 刷新页面后新事件能入库,丢失事件不保证补发 | + +## 常见问题 + +- **没有数据?** 核对是否走了示例 edge 入口、授权、网站 UUID、规则和缓存;HTTP 200 不等于已入库。 +- **任意平台都能只填地址吗?** 不能。其他平台还需适配器和经过审核的代理端点。 +- **算匿名采集吗?** 精简 JSON 不等于匿名;平台仍可能收到 IP、User-Agent 等传输信息。部署方负责访问控制、保留期限与合规。 + +## 如何关闭 + +当前页可用 `window.skillhubAnalytics.stop()` 停止后续派发,已发出的请求不能撤回。持续关闭需将入口恢复为 `enabled: false`、重新创建 edge 并禁用缓存刷新;完全撤掉接入则移除注入/edge,回到原 Web 入口。隔离演示的清理步骤见详细指南,不要清理共享平台或业务数据。 From 525f741914ea2f4270b1574ef14eccf41e28d725 Mon Sep 17 00:00:00 2001 From: XiaoSeS <87064762+XiaoSeS@users.noreply.github.com> Date: Mon, 2 Nov 2026 16:07:35 +0800 Subject: [PATCH 4/5] docs(analytics): document actionable first-time local setup Signed-off-by: XiaoSeS <87064762+XiaoSeS@users.noreply.github.com> --- docs/frontend-analytics-integration.md | 22 +-- docs/frontend-analytics.md | 8 +- docs/skillhub/en/guide/frontend-analytics.md | 133 ++++++++++++++++--- docs/skillhub/guide/frontend-analytics.md | 132 +++++++++++++++--- 4 files changed, 240 insertions(+), 55 deletions(-) diff --git a/docs/frontend-analytics-integration.md b/docs/frontend-analytics-integration.md index 00c69021e..9d77b1ca2 100644 --- a/docs/frontend-analytics-integration.md +++ b/docs/frontend-analytics-integration.md @@ -34,18 +34,20 @@ function stop() { stopObserver(); adapter.stop() } 前提:已有能正常使用的 SkillHub Web;已安装 Docker 和 Compose;能使用示例指定的 Umami 3.4.1、Postgres 16、Nginx 1.30.6 镜像;本机 8300 和 8081 端口空闲。所有 shell 命令从仓库根目录运行。示例会创建独立演示网络和临时数据库,不用于生产持久化。请在隔离环境运行。 +启动前先执行 `docker compose ls --all`,确认专用项目名 `skillhub-analytics-demo` 未被其他项目占用。若已占用,选择一个未使用的新名字,并在本文所有命令中一致替换。所有演示命令显式使用 `-p`,防止继承终端已有的 `COMPOSE_PROJECT_NAME` 而误操作其他部署;换一个克隆目录本身不能隔离 Compose 项目。 + 先检查配置,再启动: ```sh -docker compose -f docs/examples/analytics/compose.yaml config -docker compose -f docs/examples/analytics/compose.yaml up -d +docker compose -p skillhub-analytics-demo -f docs/examples/analytics/compose.yaml config +docker compose -p skillhub-analytics-demo -f docs/examples/analytics/compose.yaml up -d ``` 默认上游是 `host.docker.internal:80`,对应 release Compose 的 `WEB_PORT` 默认 80。这里是容器访问宿主机的 Web 入口,不是后端端口,也不是 edge 自己的 8081。若 Web 实际发布在其他端口(比如 18080),先在当前终端导出,再启动。后面所有 compose 命令都要在这个终端里执行,否则重建 edge 时会回到默认的 80: ```sh export SKILLHUB_WEB_UPSTREAM=host.docker.internal:18080 -docker compose -f docs/examples/analytics/compose.yaml up -d +docker compose -p skillhub-analytics-demo -f docs/examples/analytics/compose.yaml up -d ``` 原生 Linux Docker 需要 `host.docker.internal` 映射,示例 edge 已包含 `extra_hosts: ["host.docker.internal:host-gateway"]`。Docker Desktop/OrbStack 已提供这个名字。宿主机 Web 必须监听容器可达的地址;如果防火墙或仅回环监听阻止访问,先调整可达性,或填写容器可以访问的其他 `host:port`。不要填写 `http://` 或 URL 路径。 @@ -62,9 +64,9 @@ docker compose -f docs/examples/analytics/compose.yaml up -d 然后重建 edge,使单文件挂载更新可靠生效: ```sh -docker compose -f docs/examples/analytics/compose.yaml up -d --force-recreate edge -docker compose -f docs/examples/analytics/compose.yaml exec edge nginx -t -docker compose -f docs/examples/analytics/compose.yaml exec edge nginx -T +docker compose -p skillhub-analytics-demo -f docs/examples/analytics/compose.yaml up -d --force-recreate edge +docker compose -p skillhub-analytics-demo -f docs/examples/analytics/compose.yaml exec edge nginx -t +docker compose -p skillhub-analytics-demo -f docs/examples/analytics/compose.yaml exec edge nginx -T ``` 打开 `http://localhost:8081`,不要从原 Web 入口验收注入。 @@ -164,7 +166,7 @@ stop 不能撤回已开始的 fetch。重新获准后才可调用 start();同 7. **关闭态独立验收**:将入口恢复 `enabled: false`,重新创建 edge: ```sh -docker compose -f docs/examples/analytics/compose.yaml up -d --no-deps --force-recreate edge +docker compose -p skillhub-analytics-demo -f docs/examples/analytics/compose.yaml up -d --no-deps --force-recreate edge ``` 保持「Disable cache」勾选(或换一个新的无痕窗口),刷新页面后搜索:不得加载 script.js、产生采集回调或 send,搜索与技能卡片仍正常。完全不注入时也应零采集。这一步不验证启用态的故障隔离。 @@ -174,7 +176,7 @@ docker compose -f docs/examples/analytics/compose.yaml up -d --no-deps --force-r 保持入口启用和授权有效,仅停止演示 Umami: ```sh -docker compose -f docs/examples/analytics/compose.yaml stop umami +docker compose -p skillhub-analytics-demo -f docs/examples/analytics/compose.yaml stop umami ``` 在已加载 SDK 的页面再次搜索,应观察到采集请求失败,同时搜索结果和技能卡片仍正常。再新开一个禁用缓存的页面:SDK 请求应失败,但业务仍可用,不能出现统计异常导致的未捕获页面错误。记录失败请求和业务结果;不要把关闭态的零请求当成故障隔离通过,也不要把失败请求当作成功入库。 @@ -182,7 +184,7 @@ docker compose -f docs/examples/analytics/compose.yaml stop umami 9. **恢复或清理**:继续演示时执行: ```sh -docker compose -f docs/examples/analytics/compose.yaml start umami +docker compose -p skillhub-analytics-demo -f docs/examples/analytics/compose.yaml start umami ``` 等待 `http://localhost:8300` 恢复可用后,禁用缓存并刷新 edge 页面,再执行一次新动作,确认请求成功且新事件入库。原页面的 SDK 初始化失败不会保证自动恢复,故障期间丢失的事件也不保证补发。结束演示则按第 7 节关闭采集、恢复入口文件,并仅清理该演示项目;不要删除现有 SkillHub 或共享平台的数据。 @@ -208,7 +210,7 @@ docker compose -f docs/examples/analytics/compose.yaml start umami 结束本地演示(会删除演示数据库,先确认无需要保留的数据): ```sh -docker compose -f docs/examples/analytics/compose.yaml down -v +docker compose -p skillhub-analytics-demo -f docs/examples/analytics/compose.yaml down -v ``` 限制必须一起评估: diff --git a/docs/frontend-analytics.md b/docs/frontend-analytics.md index 6be1b6162..5156ac485 100644 --- a/docs/frontend-analytics.md +++ b/docs/frontend-analytics.md @@ -225,9 +225,11 @@ example is not present in the `web/` Docker build context. Postgres 16 and an optional edge; SkillHub remains your existing web upstream. From the repository root: +Before starting, run `docker compose ls --all` and confirm the dedicated project name `skillhub-analytics-demo` is not used by another project. If occupied, choose an unused name and replace it consistently in every command. Explicit `-p` prevents inheriting an existing terminal `COMPOSE_PROJECT_NAME` and targeting another deployment; cloning into a different directory does not itself isolate the Compose project. + ```sh -docker compose -f docs/examples/analytics/compose.yaml config -docker compose -f docs/examples/analytics/compose.yaml up -d +docker compose -p skillhub-analytics-demo -f docs/examples/analytics/compose.yaml config +docker compose -p skillhub-analytics-demo -f docs/examples/analytics/compose.yaml up -d ``` The default Web upstream is `host.docker.internal:80`, matching the release @@ -247,7 +249,7 @@ Create a synthetic website in Umami, copy its UUID into `enabled` and the consent hook for your local policy. Open SkillHub through `http://localhost:8081` and exercise an enabled action; inspect the request to `/_skillhub-umami/api/send` and Umami's event view. Tear down the local demo with -`docker compose -f docs/examples/analytics/compose.yaml down -v` (demo data is removed). +`docker compose -p skillhub-analytics-demo -f docs/examples/analytics/compose.yaml down -v` (demo data is removed). [`umami-adapter.mjs`](https://github.com/iflytek/skillhub/blob/main/docs/examples/analytics/observe/v1/umami-adapter.mjs) is the only vendor-specific code. It loads `/script.js` with `data-auto-track="false"`, so diff --git a/docs/skillhub/en/guide/frontend-analytics.md b/docs/skillhub/en/guide/frontend-analytics.md index 8e21802a3..e344cb864 100644 --- a/docs/skillhub/en/guide/frontend-analytics.md +++ b/docs/skillhub/en/guide/frontend-analytics.md @@ -1,30 +1,121 @@ -# Frontend analytics +# Frontend analytics: first local setup -Collection and SDK loading are off by default. The delivered example is a **manual integration**; configuration-only activation through Docker/Compose or Helm has not been merged. Click events express intent, not successful downloads, publishing, or execution. +This walkthrough adds a local demo entry in front of an existing SkillHub Web and verifies events stored in Umami. Collection is off by default. This is a **manual integration example**; configuration-only activation through Docker/Compose or Helm has not been merged. -## Connect a platform +## 1. Prepare Web and the example files -1. **Choose a platform**: reuse one or run the isolated Umami demo. Never use demo credentials in production. -2. **Configure collection**: provide a valid website UUID, selected actions, and an explicit consent check. Deployment owners maintain the entry module, adapter, and proxy. -3. **Verify before enabling access**: check outgoing fields and stored events, then confirm disabled collection and platform failure leave normal business flows working. +Confirm your existing SkillHub Web opens and search works. Not deployed yet? Complete [Docker deployment](./deployment.md) first. This example assumes a local root-path deployment; use the [detailed guide](./frontend-analytics-guide.md) for sub-paths, production proxies, and CSP. Docker, Compose, Git, and unused local ports 8300 and 8081 are required. -The [detailed setup guide (Chinese)](./frontend-analytics-guide.md) contains commands, rules, sub-paths, and recovery steps. The [interface and privacy contract (English)](./frontend-analytics-reference.md) defines event and adapter boundaries. - -## Acceptance checks - -| Scenario | Expected result | +| Address / port | Purpose | | --- | --- | -| Disabled by default | No analytics SDK or events; business flows work | -| Enabled with consent | One corresponding event per action, actually stored; no search terms or identity fields | -| Platform fails while enabled | Collection fails, but search and skill pages still work | -| Platform recovers | Refresh to verify new stored events; lost events are not guaranteed to replay | +| Original SkillHub Web (default 80) | Existing application; this demo does not redeploy it | +| `http://localhost:8300` | Umami administration: create a website and inspect events | +| `http://localhost:8081` | New demo SkillHub entry: edge injects the collector script | -## Common questions +One-click installation directories do not contain the example sources. Get the demo files from the fixed `v0.2.25` tag in a separate working directory: -- **No data?** Check the demo edge entry, consent, website UUID, rules, and cache. HTTP 200 alone does not prove storage. -- **Can any platform work by setting its URL?** No. Other platforms need an adapter and reviewed proxy endpoints. -- **Is collection anonymous?** A small JSON payload is not anonymous transport. IP and User-Agent may still reach the platform. Deployment owners handle access control, retention, and compliance. +```sh +git clone --depth 1 --branch v0.2.25 https://github.com/iflytek/skillhub.git skillhub-analytics-demo +cd skillhub-analytics-demo +``` -## Disable collection +Use an unused destination if that directory exists. This fetches demo assets, not a replacement SkillHub deployment; do not reinstall your existing application. If using an existing checkout, confirm it contains `docs/examples/analytics/compose.yaml`. Run every following shell command from the **repository root in the same terminal**, not the runtime installation directory. -Use `window.skillhubAnalytics.stop()` to stop future dispatch in the current page; already dispatched requests cannot be recalled. For persistent disabling, restore `enabled: false`, recreate edge, and refresh with cache disabled. Remove the injection/edge and return to the original Web entry to remove the integration entirely. Follow the detailed guide to clean up only the isolated demo, never shared platform or business data. +The example connects to the original Web on host port 80 by default. If its actual port is 18080, first set: + +```sh +export SKILLHUB_WEB_UPSTREAM=host.docker.internal:18080 +``` + +Replace `18080` with the actual **Web** port, not the backend port. Do not include `http://` or a path. Web must listen on an address reachable by containers; loopback-only binding or firewall rules can block edge. The example includes the `host-gateway` mapping for native Linux. + +## 2. Start Umami and obtain a website UUID + +Before starting, run `docker compose ls --all` and confirm the dedicated project name `skillhub-analytics-demo` is not used by another project. If occupied, choose an unused name and replace it consistently in every command. Explicit `-p` prevents inheriting an existing terminal `COMPOSE_PROJECT_NAME` and targeting another deployment; cloning into a different directory does not itself isolate the Compose project. + +Check the example configuration, then start only its database and Umami: + +```sh +docker compose -p skillhub-analytics-demo -f docs/examples/analytics/compose.yaml config +docker compose -p skillhub-analytics-demo -f docs/examples/analytics/compose.yaml up -d postgres umami +``` + +Wait for `http://localhost:8300`, sign in with demo credentials **`admin` / `umami`**, and change the password immediately. Create a demo website in website management and copy its **UUID**, not its name, URL, or your password. + +This Compose uses public demo secrets and a temporary database. It does not provide a production persistence, backup, or access-control solution; do not deploy it unchanged in production. + +## 3. Configure the demo actions + +Open `docs/examples/analytics/observe/v1/observer.mjs` in the repository. Preserve the imports, `start()`, `stop()`, and other code; replace only `const config` and `hasConsent()` with: + +```js +const config = Object.freeze({ + enabled: true, + website: 'REPLACE_WITH_YOUR_WEBSITE_UUID', + prefix: '/_skillhub-umami', + rules: DEFAULT_RULES, +}) + +// Only for an isolated demo where you explicitly consent to collection. +// Production integrations must read the actual consent state. +function hasConsent() { return true } +``` + +`DEFAULT_RULES` is already imported and covers existing actions such as search submission and skill cards. The original `skill.example.open` has no corresponding product element, so it is omitted here. Never put administration secrets or personal data in this file, and do not use a fixed `true` for other users. + +## 4. Start the demo entry and verify stored events + +```sh +docker compose -p skillhub-analytics-demo -f docs/examples/analytics/compose.yaml up -d --force-recreate edge +docker compose -p skillhub-analytics-demo -f docs/examples/analytics/compose.yaml exec edge nginx -t +``` + +Expect a successful Nginx check. Open **`http://localhost:8081`**, rather than the original Web URL, to test collection. + +1. In developer tools Network, enable **Disable cache** and **Preserve log**, refresh, and filter `/_skillhub-umami/`. Expect `script.js` to load successfully, without an automatic pageview. +2. Enter test text and click Search: expect one `api/send` POST. Search again with Enter: expect one additional event. +3. Inspect the payload: `name` is `search.query.submit`, and `data.event` is `submit`. Search terms and identity fields must be absent. Open a skill card to check `skill.card.open`. +4. In Umami on port 8300, open the website events view and select the current time range. Confirm matching events and counts. **HTTP 200 alone does not prove storage.** Click events express intent, not successful downloads, publishing, or execution. + +| Additional acceptance check | Expected result | +| --- | --- | +| Disable collection and refresh | No SDK / event requests; application still works | +| Stop demo Umami while collection is enabled | Collection fails; search and skill pages still work | +| Start Umami and refresh | New events are stored; lost events are not guaranteed to replay | + +The [detailed guide](./frontend-analytics-guide.md) provides fault-test controls and recovery steps. Operate only this demo, never stop a shared platform. + +## 5. Disable and clean up + +Run `window.skillhubAnalytics.stop()` in the current page to stop future dispatch; already dispatched requests cannot be recalled. For persistent disabling, restore `enabled: false` and make `hasConsent()` return `false`, then recreate edge and refresh with cache disabled. + + +```sh +docker compose -p skillhub-analytics-demo -f docs/examples/analytics/compose.yaml up -d --no-deps --force-recreate edge +``` + +To pause the demo while keeping its containers for continued use: + +```sh +docker compose -p skillhub-analytics-demo -f docs/examples/analytics/compose.yaml stop +``` + +The demo database is not a production persistence solution. Back up required data first; stopping is not a durability guarantee. Only when demo data is no longer needed, run: + +```sh +docker compose -p skillhub-analytics-demo -f docs/examples/analytics/compose.yaml down -v +``` + +This removes the example containers and volumes; treat demo data as deleted. Do not run cleanup against the existing SkillHub deployment. Return to the original Web URL afterward. + +## Common problems + +| Symptom | Check first | +| --- | --- | +| Compose file not found | Work from the cloned repository root, not the runtime installation directory | +| Ports 8300 / 8081 cannot start | Local port conflicts; inspect `docker compose -p skillhub-analytics-demo -f docs/examples/analytics/compose.yaml logs` | +| 8081 returns 502 | Web port, container-reachable binding, and firewall; do not use the backend port | +| No collection requests | Visit 8081, verify enabled / consent, recreate after editing, and refresh with cache disabled | +| Requests fail or no stored events | Correct UUID, Umami readiness, matching time range, and the actual Network response | + +Further reading: [complete setup guide (Chinese)](./frontend-analytics-guide.md) · [interface and privacy contract](./frontend-analytics-reference.md). Minimal fields do not mean anonymous transport: IP and User-Agent may still reach the platform. Deployment owners handle retention, access control, and compliance. diff --git a/docs/skillhub/guide/frontend-analytics.md b/docs/skillhub/guide/frontend-analytics.md index d5337fcc2..16d95e83d 100644 --- a/docs/skillhub/guide/frontend-analytics.md +++ b/docs/skillhub/guide/frontend-analytics.md @@ -1,30 +1,120 @@ -# 前端动作统计 +# 前端动作统计:首次本地接入 -默认不采集、不加载统计 SDK。当前提供**手动接入示例**;通过 Docker/Compose 或 Helm 配置直接开启的能力尚未合并。点击事件只表示操作意图,不证明下载、发布或执行成功。 +本文带你在已有 SkillHub 前增加一个本地演示入口,连接 Umami 并确认事件入库。默认不采集;当前是**手动接入示例**,通过 Docker/Compose 或 Helm 配置直接开启的方案尚未合并。 -## 如何接入 +## 1. 准备已有 Web 和示例文件 -1. **选平台**:已有平台可复用;没有平台可先运行隔离的 Umami 演示。不要把演示密码用于生产。 -2. **配置采集**:准备有效网站 UUID、需要采集的动作与明确授权判断;部署方维护采集入口、适配器和代理。 -3. **验收再开放**:检查请求字段和真实入库,并验证关闭与平台故障不影响正常业务。 +先确认 SkillHub Web 可以正常打开、搜索。尚未部署?先完成 [Docker 部署](./deployment.md),再回来继续。本例适用于本机根路径部署;子路径、生产代理与 CSP 请用[详细指南](./frontend-analytics-guide.md)。需要 Docker、Compose 和 Git,且 8300、8081 未被占用。 -[详细操作指南(中文)](./frontend-analytics-guide.md)提供命令、规则、子路径与恢复步骤;[接口与隐私契约(英文)](./frontend-analytics-reference.md)定义事件及适配器边界。 - -## 验收看什么 - -| 场景 | 应观察到什么 | +| 地址/端口 | 用途 | | --- | --- | -| 默认关闭 | 不加载统计 SDK、不发送事件,业务正常 | -| 已启用且获得授权 | 一次动作一条对应事件,平台确实入库;不传搜索词或身份字段 | -| 启用后平台故障 | 请求失败但搜索、技能页面仍可用 | -| 平台恢复 | 刷新页面后新事件能入库,丢失事件不保证补发 | +| 原 SkillHub Web(默认 80) | 已有业务服务,本例不会重新部署它 | +| `http://localhost:8300` | Umami 管理界面,创建网站和查看事件 | +| `http://localhost:8081` | 本例新增的 SkillHub 访问入口,经过 edge 注入采集脚本 | + +一键安装目录只有部署文件,没有本例源码。从固定的 `v0.2.25` tag 获取演示配套,在另一个工作目录执行: + +```sh +git clone --depth 1 --branch v0.2.25 https://github.com/iflytek/skillhub.git skillhub-analytics-demo +cd skillhub-analytics-demo +``` + +目标目录已存在时换用空目录。这只是获取演示配套,不会替换现有 SkillHub,也不要求重装它。使用已有仓库时先确认包含 `docs/examples/analytics/compose.yaml`。以下所有 shell 命令都在**仓库根目录、同一终端**执行,不能在一键安装目录直接运行。 + +示例默认连接原 Web 的宿主机 80 端口。如果实际是 18080,先设置: + +```sh +export SKILLHUB_WEB_UPSTREAM=host.docker.internal:18080 +``` + +将 `18080` 换成实际 **Web** 端口,不是后端端口;不要填写 `http://` 或路径。Web 必须监听容器可达的地址,仅回环监听或防火墙限制可能阻止 edge 访问。示例已为原生 Linux 配置 `host-gateway` 映射。 + +## 2. 启动 Umami,取得网站 UUID + +启动前先执行 `docker compose ls --all`,确认专用项目名 `skillhub-analytics-demo` 未被其他项目占用。若已占用,选择一个未使用的新名字,并在本文所有命令中一致替换。所有演示命令显式使用 `-p`,防止继承终端已有的 `COMPOSE_PROJECT_NAME` 而误操作其他部署;换一个克隆目录本身不能隔离 Compose 项目。 + +先检查示例,再只启动统计数据库和 Umami: + +```sh +docker compose -p skillhub-analytics-demo -f docs/examples/analytics/compose.yaml config +docker compose -p skillhub-analytics-demo -f docs/examples/analytics/compose.yaml up -d postgres umami +``` + +等待 `http://localhost:8300` 可访问,用演示账号 **`admin` / `umami`** 登录并立即修改密码。在网站管理中创建一个演示网站,复制它的 **UUID**(不是网站名称、网址或登录密码)。 + +此 Compose 使用公开演示密钥和临时数据库,不具备生产持久化、备份与访问控制方案,不要直接用作生产部署。 + +## 3. 配置本次演示要采集的动作 + +打开仓库中的 `docs/examples/analytics/observe/v1/observer.mjs`,保留现有 imports、`start()`、`stop()` 等代码,仅将 `const config` 和 `hasConsent()` 替换为下列内容: + +```js +const config = Object.freeze({ + enabled: true, + website: '替换为上一步的网站 UUID', + prefix: '/_skillhub-umami', + rules: DEFAULT_RULES, +}) + +// 仅用于本人明确同意采集的隔离演示;正式接入必须读取真实授权状态。 +function hasConsent() { return true } +``` + +`DEFAULT_RULES` 已由文件开头导入,包含搜索提交、技能卡片等现有动作。示例原有的 `skill.example.open` 不对应产品元素,这里不使用它。不要将真实管理密钥或个人信息放进该文件,也不要对其他用户直接使用固定的 `true`。 + +## 4. 启动演示入口,检查真实事件 + +```sh +docker compose -p skillhub-analytics-demo -f docs/examples/analytics/compose.yaml up -d --force-recreate edge +docker compose -p skillhub-analytics-demo -f docs/examples/analytics/compose.yaml exec edge nginx -t +``` + +`nginx -t` 应成功。打开 **`http://localhost:8081`**,不要继续使用原 Web 地址验收采集。 + +1. 开发者工具 Network 勾选 **Disable cache** 和 **Preserve log**,刷新页面,筛选 `/_skillhub-umami/`。应成功加载 `script.js`,但不自动发送 pageview。 +2. 搜索框输入测试文字并点击搜索,应有一条 `api/send` POST;再按 Enter 搜索一次,应再增加一条。 +3. 检查 Payload:事件名为 `search.query.submit`,`data.event` 为 `submit`;不得包含搜索词或身份字段。点击技能卡片可检查 `skill.card.open`。 +4. 在 8300 的 Umami 网站事件页选择当前时间范围,确认对应事件及次数。**HTTP 200 本身不能证明已入库**。点击事件只代表意图,不代表下载、发布或执行成功。 + +| 还需验收 | 预期 | +| --- | --- | +| 关闭采集、刷新 | 无 SDK/事件请求,业务正常 | +| 已启用时停止演示 Umami | 采集失败,搜索与技能页面仍可用 | +| 启动 Umami、刷新 | 新事件可入库;不保证补发丢失事件 | + +上述故障测试的完整对照、恢复步骤见[详细指南](./frontend-analytics-guide.md)。只操作本例统计服务,不要停止共享平台。 + +## 5. 关闭与清理 + +当前页执行 `window.skillhubAnalytics.stop()` 可阻止后续派发,已发出的请求不能撤回。持续关闭时,将文件恢复为 `enabled: false`、`hasConsent()` 返回 `false`,再重建 edge 并禁用缓存刷新。 + + +```sh +docker compose -p skillhub-analytics-demo -f docs/examples/analytics/compose.yaml up -d --no-deps --force-recreate edge +``` + +暂时停止演示、保留容器以便继续: + +```sh +docker compose -p skillhub-analytics-demo -f docs/examples/analytics/compose.yaml stop +``` + +演示数据库不是生产持久化方案;需要数据请先备份,不要把停止等同持久化保证。确定不再需要演示数据时才执行: + +```sh +docker compose -p skillhub-analytics-demo -f docs/examples/analytics/compose.yaml down -v +``` + +该命令删除本示例的容器和卷,演示数据应视为删除;不对现有 SkillHub 部署执行清理。关闭后回到原 Web 地址。 ## 常见问题 -- **没有数据?** 核对是否走了示例 edge 入口、授权、网站 UUID、规则和缓存;HTTP 200 不等于已入库。 -- **任意平台都能只填地址吗?** 不能。其他平台还需适配器和经过审核的代理端点。 -- **算匿名采集吗?** 精简 JSON 不等于匿名;平台仍可能收到 IP、User-Agent 等传输信息。部署方负责访问控制、保留期限与合规。 +| 现象 | 先检查 | +| --- | --- | +| 找不到 Compose 文件 | 当前目录应是克隆仓库根目录,而非 runtime 安装目录 | +| 8300/8081 无法启动 | 本机端口占用;看 `docker compose -p skillhub-analytics-demo -f docs/examples/analytics/compose.yaml logs` | +| 8081 返回 502 | Web 端口、容器可达监听和防火墙;不要填后端端口 | +| 没有采集请求 | 是否访问 8081,入口是否启用/获得授权,修改后是否重建及禁用缓存刷新 | +| 请求失败或平台无数据 | UUID 是否正确、Umami 是否就绪、时间范围是否匹配;检查 Network 响应 | -## 如何关闭 - -当前页可用 `window.skillhubAnalytics.stop()` 停止后续派发,已发出的请求不能撤回。持续关闭需将入口恢复为 `enabled: false`、重新创建 edge 并禁用缓存刷新;完全撤掉接入则移除注入/edge,回到原 Web 入口。隔离演示的清理步骤见详细指南,不要清理共享平台或业务数据。 +进阶:[完整操作指南](./frontend-analytics-guide.md) · [接口与隐私契约(英文)](./frontend-analytics-reference.md)。字段精简不等于匿名传输:IP、User-Agent 等仍可能到达平台,保留期限、访问控制和合规由部署方负责。 From d8d20c403389ce92e5c5e659e586ebfb045a02d2 Mon Sep 17 00:00:00 2001 From: XiaoSeS <87064762+XiaoSeS@users.noreply.github.com> Date: Mon, 2 Nov 2026 16:13:31 +0800 Subject: [PATCH 5/5] docs(analytics): explicitly state one-click production deployment is pending Signed-off-by: XiaoSeS <87064762+XiaoSeS@users.noreply.github.com> --- docs/frontend-analytics-integration.md | 2 ++ docs/frontend-analytics.md | 4 +++- docs/skillhub/en/guide/frontend-analytics.md | 6 +++++- docs/skillhub/guide/frontend-analytics.md | 6 +++++- 4 files changed, 15 insertions(+), 3 deletions(-) diff --git a/docs/frontend-analytics-integration.md b/docs/frontend-analytics-integration.md index 9d77b1ca2..594e624b0 100644 --- a/docs/frontend-analytics-integration.md +++ b/docs/frontend-analytics-integration.md @@ -3,6 +3,8 @@ ## 1. 先了解边界 +当前是手动、本地演示接入,生产一键配置尚未交付;新方案合并并验证后再更新本指南。 + SkillHub 页面只提供被动的 `data-analytics-id` 标签,默认不采集、不加载统计 SDK、不发送事件。可选 helper 把允许的原生交互转换成 `{ id, event }`,再交给部署方选择的 adapter。点击下载只表示下载意图,不表示下载、安装成功;提交发布也不表示发布成功。部署方负责授权、隐私合规、保留期限和平台安全。 本文对应 PR-1(#1010)的手工接入示例,不是产品内置开关。仅通过 Docker/Compose 或 Helm 配置开启、默认关闭和按需加载的能力计划在 PR-2 交付,见 [OpenSpec 变更](https://github.com/iflytek/skillhub/blob/main/openspec/changes/add-configurable-frontend-analytics/proposal.md)。Issue #989 要等 PR-2 完成并验证后才关闭。精确接口、事件边界和隐私约束以[英文契约][analytics-reference]为准。 diff --git a/docs/frontend-analytics.md b/docs/frontend-analytics.md index 5156ac485..fdf4b321a 100644 --- a/docs/frontend-analytics.md +++ b/docs/frontend-analytics.md @@ -4,7 +4,9 @@ For step-by-step setup, see the [Chinese integration guide][analytics-guide]. This document is the English contract reference. Configuration-only deployment is planned in [PR-2](https://github.com/iflytek/skillhub/blob/main/openspec/changes/add-configurable-frontend-analytics/proposal.md); -the current examples remain deployment-owned and opt-in. +the current examples remain deployment-owned and opt-in. They describe a manual, +local demo integration; production one-click configuration has not been delivered. +The guide will be updated after the new flow is merged and validated. SkillHub exposes semantic HTML attributes for separately maintained, optional collectors. It does not collect or send analytics by default. There is no SDK, diff --git a/docs/skillhub/en/guide/frontend-analytics.md b/docs/skillhub/en/guide/frontend-analytics.md index e344cb864..eaf48ebc4 100644 --- a/docs/skillhub/en/guide/frontend-analytics.md +++ b/docs/skillhub/en/guide/frontend-analytics.md @@ -1,6 +1,10 @@ # Frontend analytics: first local setup -This walkthrough adds a local demo entry in front of an existing SkillHub Web and verifies events stored in Umami. Collection is off by default. This is a **manual integration example**; configuration-only activation through Docker/Compose or Helm has not been merged. +This walkthrough adds a local demo entry in front of an existing SkillHub Web and verifies events stored in Umami. Collection is off by default. + +::: warning Current support scope +This page covers the delivered manual, local demo integration, not a production one-click deployment. **Production one-click configuration has not been delivered.** The new Docker/Compose and Helm configuration flow is still in progress; this page will be updated after it is merged and validated. +::: ## 1. Prepare Web and the example files diff --git a/docs/skillhub/guide/frontend-analytics.md b/docs/skillhub/guide/frontend-analytics.md index 16d95e83d..a7389dbcf 100644 --- a/docs/skillhub/guide/frontend-analytics.md +++ b/docs/skillhub/guide/frontend-analytics.md @@ -1,6 +1,10 @@ # 前端动作统计:首次本地接入 -本文带你在已有 SkillHub 前增加一个本地演示入口,连接 Umami 并确认事件入库。默认不采集;当前是**手动接入示例**,通过 Docker/Compose 或 Helm 配置直接开启的方案尚未合并。 +本文带你在已有 SkillHub 前增加一个本地演示入口,连接 Umami 并确认事件入库。SkillHub 默认不采集。 + +::: warning 当前支持范围 +本文介绍已交付的手动、本地演示接入,不是生产一键部署指南。**生产一键配置接入尚未交付**;通过 Docker/Compose 或 Helm 配置开启的新方案仍在推进,合并并完成验证后再更新本页。 +::: ## 1. 准备已有 Web 和示例文件