mirror of
https://github.com/iflytek/skillhub.git
synced 2026-11-18 09:41:56 +00:00
docs(analytics): add Chinese guide and split delivery scope
Refs #989 Signed-off-by: 千乘妍 (Xiaoyaner) <258399167+xiaoyaner0201@users.noreply.github.com>
This commit is contained in:
parent
238b784110
commit
688b7ce18e
6 changed files with 364 additions and 23 deletions
197
docs/frontend-analytics-integration.md
Normal file
197
docs/frontend-analytics-integration.md
Normal file
|
|
@ -0,0 +1,197 @@
|
|||
# 前端动作统计接入指南
|
||||
|
||||
## 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)为准。
|
||||
|
||||
## 2. 选择接入路径
|
||||
|
||||
### 路径 A:复用已有统计平台
|
||||
|
||||
先确认平台接收地址、公开站点标识、授权策略和 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<void>` 和 `stop()`。send 必须消化同步异常和异步拒绝,不向页面抛错;stop 后不能再派发请求,已经开始的 fetch 无法撤回。
|
||||
3. 由 adapter 验证平台参数、清洗最终发送字段、管理 SDK 加载和超时。不要只清洗 helper 回调后就信任 SDK 自动附加的 URL、标题或身份字段。
|
||||
4. 在部署方入口中连接 helper 与 adapter,只有策略允许时才初始化:
|
||||
|
||||
```js
|
||||
import { observeSkillhubIntents } from './skillhub-intents.mjs'
|
||||
// adapter 由部署方创建;必须先确认当前授权。
|
||||
const stopObserver = observeSkillhubIntents({
|
||||
root: document,
|
||||
onIntent: intent => adapter.send(intent),
|
||||
})
|
||||
function stop() { stopObserver(); adapter.stop() }
|
||||
```
|
||||
|
||||
入口交付、同源代理、授权回调和 CSP 由部署方维护。下面的 edge 仅演示 Umami 两个端点;使用其他平台时,需要自行审核并替换 adapter 和代理端点。不要把平台管理界面代理到公开采集前缀。
|
||||
|
||||
### 路径 B:本地自托管 Umami 演示
|
||||
|
||||
前提:已有能正常使用的 SkillHub Web;已安装 Docker 和 Compose;能使用示例指定的 Umami 3.4.1、Postgres 16、Nginx 1.30.6 镜像;本机 8300 和 8081 端口空闲。所有 shell 命令从仓库根目录运行。示例会创建独立演示网络和临时数据库,不用于生产持久化。请在隔离环境运行。
|
||||
|
||||
先检查配置,再启动:
|
||||
|
||||
```sh
|
||||
docker compose -f docs/examples/analytics/compose.yaml config
|
||||
docker compose -f docs/examples/analytics/compose.yaml up -d
|
||||
```
|
||||
|
||||
默认上游是 `host.docker.internal:80`,对应 release Compose 的 `WEB_PORT` 默认 80。这里是容器访问宿主机的 Web 入口,不是后端端口,也不是 edge 自己的 8081。若 Web 实际发布在 18080,使用:
|
||||
|
||||
```sh
|
||||
SKILLHUB_WEB_UPSTREAM=host.docker.internal:18080 docker compose -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 路径。
|
||||
|
||||
打开 `http://localhost:8300`。首次演示登录是 `admin` / `umami`,立即改密码。示例公开的数据库口令和 APP_SECRET 也只能用于演示;生产需要独立密钥、持久化、备份和访问控制。
|
||||
|
||||
在 Umami 创建一个演示网站,记录网站 UUID。打开 `docs/examples/analytics/observe/v1/observer.mjs`:
|
||||
|
||||
1. 将全零 `website` 改为刚创建的网站 UUID。
|
||||
2. 将 `enabled: false` 改为 `enabled: true`。
|
||||
3. 将 `hasConsent()` 接入自己的当前授权判断。仅在隔离演示、明确允许采集时可暂改为返回 true;正式接入不能把它当作用户同意。
|
||||
4. 按下一节配置 rules。示例额外的 `skill.example.open` 没有对应产品元素,不会凭空产生事件。
|
||||
|
||||
然后重建 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
|
||||
```
|
||||
|
||||
打开 `http://localhost:8081`,不要从原 Web 入口验收注入。本地演示可以修改 v1 文件;正式交付中同一路径的模块是 immutable 缓存,修改内容必须发布到新的版本目录并同步注入路径,不能覆盖旧版本字节。
|
||||
|
||||
## 3. 配置规则和增加动作
|
||||
|
||||
省略 `rules` 使用冻结的 `DEFAULT_RULES`,共 12 条:
|
||||
|
||||
| ID | 规则 |
|
||||
| --- | --- |
|
||||
| search.query.submit | submit |
|
||||
| skill.card.open | card |
|
||||
| suite.card.open | card |
|
||||
| skill.download.request | click |
|
||||
| skill.file.download | click |
|
||||
| skill.command.copy | click |
|
||||
| skill.prompt.copy | click |
|
||||
| skill.publish.request | click |
|
||||
| skill.publish.confirm | click |
|
||||
| skill.publish.cancel | click |
|
||||
| skill.delete.confirm | click |
|
||||
| skill.delete.cancel | click |
|
||||
|
||||
显式传入 rules 会替换默认值,空对象表示没有动作。要保留默认值再增加已存在的动作,先合并:
|
||||
|
||||
```js
|
||||
import { DEFAULT_RULES, resolveRules } from './skillhub-intents.mjs'
|
||||
const rules = { ...DEFAULT_RULES, 'navigation.home.open': 'click' }
|
||||
const { active, skipped } = resolveRules(rules)
|
||||
console.table(skipped) // 只在本地检查,不发送这些诊断。
|
||||
```
|
||||
|
||||
把 `active` 传给 helper 的 `rules`。也可在浏览器开发者工具 Console 中直接执行以下代码,无需编辑源码,就能查看无效项:
|
||||
|
||||
```js
|
||||
const { resolveRules } = await import('/_skillhub-observe/v1/skillhub-intents.mjs')
|
||||
console.table(resolveRules({ 'skill.example.open': 'drop' }).skipped)
|
||||
```
|
||||
|
||||
应看到 `id: skill.example.open`、`reason: unknown rule type`。非法 ID、非字符串规则也会跳过;非法容器返回 `id: null` 的诊断和空 active。该检查只验证配置,不能证明 DOM 元素支持某类事件。
|
||||
|
||||
仅支持三种规则:
|
||||
|
||||
- `click`:普通按钮、链接;忽略 FORM、SELECT、TEXTAREA、非按钮 INPUT(包括文件选择器)。
|
||||
- `submit`:只用于 FORM。点击提交和按 Enter 都归一到原生 submit;原生校验失败可能没有事件。
|
||||
- `card`:已有 Enter/Space 处理的 DIV role=link,观察 click 和对应 keydown。helper 不会替应用增加键盘行为。
|
||||
|
||||
不支持的选择器、拖放、文件和裁剪行为不要硬填 click。未配置的动作不采集。`skill.detail.render` 是结构标签,不是自动页面访问量。
|
||||
|
||||
新增产品动作时,开发者在正确的现有元素上增加静态字面量 ID,再从仓库根目录运行:
|
||||
|
||||
```sh
|
||||
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 是版本清单,不是运行时封闭枚举。
|
||||
|
||||
## 4. 部署、子路径和 CSP
|
||||
|
||||
edge 仅在 UI HTML 注入一个延迟执行的 module,不改变 API、登录、下载、静态资源或 runtime-config。server 级 `client_max_body_size 100M` 保留标准 Web 的 100 MiB 请求体上限;实际业务校验仍可能拒绝上传。不要在应用代理 location 覆盖成更小值。
|
||||
|
||||
正式启用前检查 Nginx 含 http_sub_module、`nginx -t` 成功,并审核 `nginx -T`。HTML 输入不能仍被上游 gzip/Brotli 压缩。示例禁用 HTML 缓存和旧校验器;启用或回退都应清理 CDN/浏览器旧 HTML。不要修改 API 或 immutable 资源的缓存规则。
|
||||
|
||||
根路径演示的 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 和资源地址仍遵守原部署要求。
|
||||
|
||||
## 5. 验收:照这个顺序检查
|
||||
|
||||
下面命令假定根路径和默认 edge 端口。子路径时为所有采集 URL 加相同前缀;自定义端口时统一替换地址。
|
||||
|
||||
1. 检查模块确实由 edge 提供,不是 SPA 返回的 HTML:
|
||||
|
||||
```sh
|
||||
curl -i http://localhost:8081/_skillhub-observe/v1/skillhub-intents.mjs
|
||||
curl -i http://localhost:8081/_skillhub-observe/v1/missing.mjs
|
||||
curl -I http://localhost:8081/skills
|
||||
```
|
||||
|
||||
第一个应为 200、JavaScript MIME、nosniff 和 immutable。第二个应为非 HTML 的 404。第三个应为 200、Cache-Control: no-store,并保留原 CSP(若原部署配置了 CSP)。
|
||||
|
||||
2. 打开 edge 的 SkillHub 页面,在开发者工具 Network 勾选保留日志,筛选 `/_skillhub-umami/`。刷新后应加载 script.js,但没有自动 pageview 或 send。
|
||||
3. 搜索框输入任意本地测试文字,点击搜索。应恰好有一条 `/_skillhub-umami/api/send` POST,响应 200。再按 Enter 搜索一次,应新增一条,不是两条。切换 Network 的 Payload 查看真正出站 JSON,不要只看回调。
|
||||
4. JSON 只能包含 `{ type: 'event', payload: { website, name, data: { event } } }`。website 是配置的 UUID;搜索 name 为 search.query.submit,event 为 submit。不得出现搜索词、完整 URL、标题、referrer、身份或额外 data 字段。
|
||||
5. 打开 Umami 网站事件页,选择当前时间范围,应看到 search.query.submit 和对应数量。平台处理可能稍有延迟;不能把 HTTP 200 单独当作入库证明。
|
||||
6. 执行下面的 Console 命令后再搜索,页面仍能使用,但 Network 不得新增 send:
|
||||
|
||||
```js
|
||||
window.skillhubAnalytics.stop()
|
||||
```
|
||||
|
||||
stop 不能撤回已开始的 fetch。重新获准后才可调用 start();同一个 root 重复初始化保留第一次规则和回调,修改规则需要先 stop 再初始化。
|
||||
|
||||
7. 将入口恢复 `enabled: false`,重新创建 edge 并刷新新页面,再搜索:不得加载 script.js、产生采集回调或 send。完全不注入时也应零采集。最后在隔离演示中停止 Umami,再打开新页面搜索和打开技能卡片,应仍正常,无统计依赖导致的页面错误:
|
||||
|
||||
```sh
|
||||
docker compose -f docs/examples/analytics/compose.yaml stop umami
|
||||
```
|
||||
|
||||
验收后如需继续演示,使用上面的 up 命令恢复。不要为了测试停止共享平台或生产服务。
|
||||
|
||||
## 6. 故障排查
|
||||
|
||||
| 现象 | 常见原因 | 处理 |
|
||||
| --- | --- | --- |
|
||||
| module 404 | 未挂载模块,版本目录或子路径不一致 | 对照 nginx -T、挂载路径、注入 src 和相对 import,三份 mjs 都要可访问;不要回退到 index.html |
|
||||
| MIME 报错或返回 HTML | 模块误入 SPA fallback,缺少 mjs MIME | 使用示例独立前缀、try_files 404 和 JavaScript MIME,保留 nosniff |
|
||||
| CSP 拦截 | script-src/connect-src 不允许,或 nonce-only 策略 | 按原 CSP 的授权机制交付;不要删除 CSP 或放宽为通配符 |
|
||||
| 上传 413 | 外层代理仍默认 1 MiB,或请求超过 100 MiB | 用 nginx -T 检查整条代理链;应用代理继承 100M,超过标准上限仍应拒绝 |
|
||||
| 没有事件 | 走了原 Web 而非 edge,enabled/授权未开,UUID 错,规则未配置或宿主不支持 | 按第 5 节从模块、skipped、Network 到平台事件页逐步确认;检查时间范围;不要把结构标签当 pageview |
|
||||
| edge 502 | Web 上游地址/端口错误,宿主不可达 | 核对 WEB_PORT、host-gateway、防火墙和监听地址;不要把后端或 edge 端口填成 Web 上游 |
|
||||
| Umami 不可用 | SDK 404、超时、平台停止或网络故障 | 页面应继续正常;检查平台和代理日志,恢复后重新打开页面;没有重试补发保证 |
|
||||
|
||||
## 7. 升级、关闭和已知限制
|
||||
|
||||
升级时先比较新旧 manifest。已有 ID 语义不变;含义变化需要新 ID,重命名/删除必须有发布说明。消失的 ID 不再触发,新 ID 默认不自动加入规则。模块/SDK 升级要重新验证真实出站字段、stop 派发边界、并发发送、根/子路径和业务行为,不能只看构建成功。
|
||||
|
||||
临时关闭当前页用 stop();持久关闭把入口改回 enabled:false,并按版本发布规则更新、清理 HTML 缓存和刷新。彻底关闭则撤掉注入/edge,让访问回到正常 Web 入口,确认新 HTML 不引用模块、Network 无采集。关闭平台网站或封锁采集路由是额外控制,不能代替授权撤回。
|
||||
|
||||
结束本地演示(会删除演示数据库,先确认无需要保留的数据):
|
||||
|
||||
```sh
|
||||
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)。
|
||||
|
|
@ -1,8 +1,13 @@
|
|||
# Passive frontend analytics attributes
|
||||
|
||||
For step-by-step setup, see the [Chinese integration guide](frontend-analytics-integration.md).
|
||||
This document is the English contract reference. Configuration-only deployment is
|
||||
planned in [PR-2](../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
|
||||
collectors. It does not collect or send analytics by default. There is no SDK,
|
||||
DataFinder dependency, vendor token, network reporter, app script loader or
|
||||
vendor dependency, vendor token, network reporter, app script loader or
|
||||
telemetry configuration switch. The application entrypoint and production Nginx
|
||||
configuration are unchanged. Deployment owners control consent, script delivery,
|
||||
retention, transport and compliance; this is not an official vendor integration
|
||||
|
|
@ -221,9 +226,17 @@ From the repository root:
|
|||
|
||||
```sh
|
||||
docker compose -f docs/examples/analytics/compose.yaml config
|
||||
SKILLHUB_WEB_UPSTREAM=host.docker.internal:8080 docker compose -f docs/examples/analytics/compose.yaml up -d
|
||||
docker compose -f docs/examples/analytics/compose.yaml up -d
|
||||
```
|
||||
|
||||
The default Web upstream is `host.docker.internal:80`, matching the release
|
||||
Compose `WEB_PORT` default of 80. Override `SKILLHUB_WEB_UPSTREAM` with the actual
|
||||
reachable host:port if different. The edge's `extra_hosts` maps this hostname to
|
||||
`host-gateway` on native Linux; Docker Desktop/OrbStack already provide it. The
|
||||
host Web listener must be reachable from containers. The edge inherits the standard
|
||||
server-level `client_max_body_size 100M` for application proxying (100 MiB); it does
|
||||
not reduce uploads to Nginx's default 1 MiB.
|
||||
|
||||
This creates a demo network and ephemeral database, not production storage. Use
|
||||
an isolated local Docker environment with available network pools. Open
|
||||
`http://localhost:8300` for local setup only. Umami's default `admin` / `umami`
|
||||
|
|
|
|||
|
|
@ -2,6 +2,29 @@
|
|||
|
||||
本变更在 PR #1010 上保留原贡献历史并合入最新 main,保留 footer 翻译及 Trans 登录协议。使用已有运行时配置比 Nginx HTML 注入更易自动交付;完整标签管理平台增加额外服务与权限体系,本期不采用。
|
||||
|
||||
## 分阶段交付与接口对齐
|
||||
|
||||
PR-1(#1010)仅完成被动标签、厂商中立 helper 与示例 adapter、edge 示例问题修正和中文接入指南。它不修改产品入口或部署开关,手工接入方式继续明确标为可选示例。PR-2 独立交付配置化加载、产品模块、runtime-config、同源代理和 Compose/Helm。两者可分别合并,Issue #989 仅在 PR-2 完成并验证后关闭。
|
||||
|
||||
PR-2 必须采用 PR-1 实际交付的接口,不能另起一套不兼容协议:
|
||||
|
||||
| PR-1 接口 | PR-2 采用方式 |
|
||||
| --- | --- |
|
||||
| `data-analytics-id` 匹配 `^[a-z]+(?:\.[a-z]+){2,}$`,由 manifest 索引 | 保持已发布 ID 含义冻结;manifest 不是运行时封闭枚举,不插值资源/身份信息 |
|
||||
| `observeSkillhubIntents({ root, rules, onIntent }) -> stop` | controller 按授权安装委托观察;不改变页面原生事件和业务处理 |
|
||||
| 冻结的 `DEFAULT_RULES`(12 条) | rules 省略用默认值,显式提供为替换,空对象不采集;增加默认规则需显式合并 |
|
||||
| `resolveRules(rules) -> { active, skipped: [{ id, reason }] }` | 使用相同纯校验;非法容器的 id 为 null;诊断只留本地,不发送原配置 |
|
||||
| 有限类型 `click`/`submit`/`card` | 保持宿主限制和原生事件边界;未知类型/ID 格式/不支持宿主跳过,不猜测选择、文件、拖放或裁剪事件 |
|
||||
| intent 仅 `{ id, event }` | event 为原生 click/submit/keydown,不表示业务成功;同版本只允许增加可选的静态白名单字段,消费者忽略未知字段;破坏性变更另版本 |
|
||||
| adapter `send(intent) -> Promise<void>`、`stop()` | send 消化异常、永不 reject;平台参数只归 adapter;停止后不得派发新请求,已开始 fetch 不可撤回 |
|
||||
| 同 root 重复初始化保留第一次 config/callback 并返回相同 stop | 改配置先 stop 再初始化;旧 stop 不得撤掉新安装,stop 可重复调用;嵌套观察共享事件去重 |
|
||||
|
||||
配置映射:enabled=false 不安装观察、不加载 SDK;consent=denied 同样禁止初始化。enabled 与 consent 的联合判断由通用 controller 管理,不放进业务组件。rules 原样通过 resolveRules,保留 active/skipped 语义。adapter 仅选择静态注册 factory;adapterConfig 只交给所选适配层校验,不把 websiteId 等厂商字段提升到通用配置。PR-1 示例的 website/prefix 对应 PR-2 Umami 的 adapterConfig.websiteId/部署生成的同源前缀;PR-1 的 hasConsent hook 对应 PR-2 consent 和动态 start/stop。PR-2 新增默认关闭的模块加载边界,不能声称 PR-1 示例已具备产品配置化加载。
|
||||
|
||||
PR-2 将 helper 迁入 `web/src/features/analytics` 的单一产品源码,迁移而非复制,保留 PR-1 测试的全部断言,包括 grammar、有限规则、生命周期、隐私和 dispatch 边界。示例 adapter 仍不是任意远程 JS 插件机制。
|
||||
|
||||
## PR-2 产品设计(下列能力尚未在 PR-1 实现)
|
||||
|
||||
### 1. Stable configuration contract
|
||||
|
||||
- `SKILLHUB_WEB_ANALYTICS_CONFIG`:可选 JSON 对象,空值等同关闭。字段为 enabled(boolean,默认 false)、adapter(注册适配器名)、consent(`denied`/`granted`,默认 denied)、rules(可选动作→有限规则对象,省略沿用默认规则,显式空对象不采集)、adapterConfig(平台自有公开参数对象)。
|
||||
|
|
|
|||
|
|
@ -2,8 +2,16 @@
|
|||
|
||||
Issue #989 / PR #1010 已提供被动动作标签、通用 helper 和独立平台适配示例,但部署方仍需修改 JS、提供文件和手工接入 Nginx。维护者确认新的交付目标:部署只填配置、尽量一次启动、文档可独立复现,同时控制对原业务的影响。此目标是原评审之后新增的正式产品能力,不将其描述为原贡献者返修遗漏。
|
||||
|
||||
## 分两次交付
|
||||
|
||||
- PR-1(#1010):完成被动标签、厂商中立 helper、示例 adapter、edge 上传上限与默认 Web 上游修正,以及可独立照做的中文接入指南。示例仍由部署方手工接入,不增加产品运行时开关。
|
||||
- PR-2(后续 PR):交付下述配置化产品能力,包括 `web/src/features/analytics` 单一产品源码、runtime-config 可选加载、同源代理路由及 Docker/Compose/Helm 配置。Umami 是首个注册 adapter,通用配置和加载入口不绑定平台。
|
||||
- 两个 PR 分别合并。Issue #989 保留到 PR-2 完成并验证后才关闭;PR-1 不自动关闭该 Issue。
|
||||
|
||||
## What Changes
|
||||
|
||||
以下产品加载和部署变更由 PR-2 交付;PR-1 的稳定接口与验收边界见 design 和 specs。
|
||||
|
||||
- 保留原作者的被动标签及协议,增加默认关闭的通用可选加载入口。
|
||||
- 复用现有 runtime-config;采集参数通过部署 JSON 配置提供,平台参数放在 adapterConfig,不编辑源码。
|
||||
- 模块随 Web 发布,平台适配器按需加载;第一版以 Umami 作为一个注册实现,不把厂商 SDK 或字段耦合进业务页面。
|
||||
|
|
@ -23,6 +31,6 @@ Issue #989 / PR #1010 已提供被动动作标签、通用 helper 和独立平
|
|||
|
||||
## Impact
|
||||
|
||||
影响 Web 可选模块、运行时配置、容器启动、Compose/Helm、部署测试和文档。新增小型 jq 镜像依赖用于标准 JSON 校验与安全转义,避免用 envsubst 拼接任意配置。默认部署不启动统计服务、不加载采集模块、不外发事件。
|
||||
影响按阶段区分:PR-1 仅涉及被动标签契约、示例、测试和接入文档;以下产品部署影响属于 PR-2。影响 Web 可选模块、运行时配置、容器启动、Compose/Helm、部署测试和文档。新增小型 jq 镜像依赖用于标准 JSON 校验与安全转义,避免用 envsubst 拼接任意配置。默认部署不启动统计服务、不加载采集模块、不外发事件。
|
||||
|
||||
范围外:后台采集配置页、SkillHub 分析数据库、通用远程代码插件平台、用户级同意弹窗、可靠消息/重试队列、服务端业务成功事件、生产环境部署和自动合并。统计平台自己的数据库属于可选外部服务,不修改 SkillHub schema。
|
||||
|
|
|
|||
|
|
@ -1,62 +1,152 @@
|
|||
## ADDED Requirements
|
||||
|
||||
### Requirement: Preserve passive business semantics
|
||||
Delivered by: PR-1 (passive markers and examples); PR-2 (product integration regression).
|
||||
|
||||
The system SHALL preserve existing static action categories and business interactions without introducing analytics dependencies into business components.
|
||||
|
||||
#### Scenario: Existing business operation
|
||||
Delivered by: PR-1 (marker/helper assertions); PR-2 (full business regression).
|
||||
|
||||
- **WHEN** a user logs in, publishes, uploads, downloads or navigates with analytics disabled or unavailable
|
||||
- **THEN** existing permissions, requests, keyboard behavior and business outcomes remain unchanged
|
||||
|
||||
### Requirement: Deploy using configuration only
|
||||
Delivered by: PR-2.
|
||||
|
||||
The system SHALL deliver optional analytics modules with the Web artifact and accept deployment configuration without source edits or hand-written Nginx rules.
|
||||
|
||||
#### Scenario: Connect an existing supported platform
|
||||
Delivered by: PR-2.
|
||||
|
||||
- **WHEN** the operator supplies valid analytics JSON, a supported adapter configuration and internal upstream origin
|
||||
- **THEN** the Web startup generates safe runtime configuration and the required isolated proxy routes without an additional Nginx service
|
||||
|
||||
### Requirement: Default closed and fail isolated
|
||||
Delivered by: PR-2 (product loader); PR-1 examples SHALL remain opt-in and inert by default.
|
||||
|
||||
The system SHALL default to analytics disabled and consent denied, and SHALL isolate invalid configuration and runtime analytics failures from Web and business availability.
|
||||
|
||||
#### Scenario: Disabled or denied collection
|
||||
Delivered by: PR-2.
|
||||
|
||||
- **WHEN** configuration is omitted, enabled is false, or consent is denied
|
||||
- **THEN** the browser does not load analytics modules or SDKs and does not send analytics requests
|
||||
|
||||
#### Scenario: Disabled example
|
||||
Delivered by: PR-1.
|
||||
|
||||
- **WHEN** the deployment-owned entry remains enabled:false or consent is not approved, or no entry is injected
|
||||
- **THEN** no observer is installed, no tracker is loaded and no intent is sent; importing the helper alone has no collection side effects
|
||||
|
||||
#### Scenario: Invalid configuration
|
||||
Delivered by: PR-2.
|
||||
|
||||
- **WHEN** analytics JSON, adapter or upstream is invalid
|
||||
- **THEN** only analytics is disabled with a diagnostic that does not echo raw values, while existing Web configuration remains usable
|
||||
|
||||
#### Scenario: Statistics service unavailable
|
||||
Delivered by: PR-2 (including request-time DNS); PR-1 covers an unavailable example tracker without making a product DNS-startup guarantee.
|
||||
|
||||
- **WHEN** the upstream is unreachable or its hostname cannot resolve
|
||||
- **THEN** the Web still starts and business remains usable without waiting for the statistics service
|
||||
|
||||
### Requirement: Vendor-neutral module contract
|
||||
The system SHALL separate generic configuration, rules and lifecycle from adapter-specific parameters and SDK calls.
|
||||
Delivered by: PR-1 (helper and example adapter); PR-2 (registered product factories and configuration).
|
||||
|
||||
The system SHALL separate generic configuration, rules and lifecycle from adapter-specific parameters and SDK calls. PR-2 SHALL migrate the helper to one product source under web/src/features/analytics and retain every PR-1 test assertion rather than maintaining duplicate implementations.
|
||||
|
||||
#### Scenario: Registered adapter
|
||||
Delivered by: PR-2.
|
||||
|
||||
- **WHEN** a supported adapter is selected
|
||||
- **THEN** its factory validates its own adapterConfig and exposes send and stop while generic code does not depend on vendor fields
|
||||
|
||||
#### Scenario: Stable helper and adapter boundary
|
||||
Delivered by: PR-1; adopted unchanged by PR-2.
|
||||
|
||||
- **WHEN** a deployment connects a collector to passive markers
|
||||
- **THEN** IDs follow `^[a-z]+(?:\.[a-z]+){2,}$` and the manifest lifecycle; observeSkillhubIntents({ root, rules, onIntent }) returns stop; frozen DEFAULT_RULES contains the original 12 rules; resolveRules(rules) returns active and skipped entries with id and reason
|
||||
- **AND** only click, submit and card rule types are supported with their documented host restrictions; invalid or unknown entries are skipped without affecting the page
|
||||
- **AND** the intent is { id, event }, describes native intent rather than business success, and evolves additive-only within its version
|
||||
- **AND** adapter send(intent) returns Promise<void> and never rejects, stop prevents new dispatch, and vendor parameters belong only to the adapter
|
||||
|
||||
#### Scenario: Configuration maps to the existing contract
|
||||
Delivered by: PR-2.
|
||||
|
||||
- **WHEN** enabled, adapter, consent, rules and adapterConfig are supplied
|
||||
- **THEN** enabled and consent gate optional loading and observation, adapter selects a static registered factory, rules use the existing resolver (omitted means defaults, explicit object replaces them), and adapterConfig is validated only by the selected adapter
|
||||
|
||||
### Requirement: Safe event lifecycle
|
||||
Delivered by: PR-1 (example lifecycle); PR-2 (product controller and asynchronous module loading).
|
||||
|
||||
The system SHALL preserve finite configured rules, field allowlists, duplicate prevention, bounded loading waits and failure isolation.
|
||||
|
||||
#### Scenario: Stop races with asynchronous initialization
|
||||
Delivered by: PR-1 (SDK wait/dispatch); PR-2 (module/controller races as well).
|
||||
|
||||
- **WHEN** collection is stopped while a module or SDK is loading
|
||||
- **THEN** late initialization does not restart collection and no new request dispatches after stop returns, excluding requests already started
|
||||
|
||||
#### Scenario: Repeated initialization and rule changes
|
||||
Delivered by: PR-1; preserved by PR-2.
|
||||
|
||||
- **WHEN** the same root is initialized repeatedly before stop
|
||||
- **THEN** it returns the same stop and retains the first configuration and callback without duplicate events
|
||||
- **AND** stop is idempotent, configuration changes require stop then reinitialization, and an old stop does not remove a new installation
|
||||
|
||||
### Requirement: Compatible deployment paths
|
||||
Delivered by: PR-2 (normal deployment); PR-1 (opt-in edge example and mapping guide).
|
||||
|
||||
The system SHALL support root and supported sub-path deployments while preserving existing API, auth, upload, cache and security behavior.
|
||||
|
||||
#### Scenario: Large valid upload through normal Web
|
||||
Delivered by: PR-2.
|
||||
|
||||
- **WHEN** a user uploads a business-valid package larger than 1 MiB through the standard Web entry with analytics enabled
|
||||
- **THEN** optional analytics routes do not reduce the existing upload limit or alter the upload request
|
||||
|
||||
#### Scenario: Example edge preserves upload boundaries
|
||||
Delivered by: PR-1.
|
||||
|
||||
- **WHEN** an operator uses the opt-in edge in front of the Web
|
||||
- **THEN** client_max_body_size 100M applies at server level and is not lowered on application proxy locations; a 5 MiB API/upload probe reaches the upstream rather than returning edge 413, while a body larger than 100 MiB is rejected with 413
|
||||
- **AND** any tighter collector-only limit does not change application uploads
|
||||
|
||||
#### Scenario: Example defaults match release Web
|
||||
Delivered by: PR-1.
|
||||
|
||||
- **WHEN** SKILLHUB_WEB_UPSTREAM is omitted from the example Compose configuration
|
||||
- **THEN** the edge targets host.docker.internal:80, matching the release WEB_PORT default of 80, and its extra_hosts provides host.docker.internal:host-gateway on native Linux
|
||||
- **AND** the guide explains overrides and container-to-host reachability, while Docker Desktop/OrbStack already provide the hostname
|
||||
|
||||
#### Scenario: Optional endpoint boundary
|
||||
Delivered by: PR-1 (example routes); PR-2 (generated product routes).
|
||||
|
||||
- **WHEN** a browser requests an unregistered analytics route
|
||||
- **THEN** the route is rejected and does not expose the statistics platform administration or arbitrary upstream paths
|
||||
|
||||
### Requirement: Reproducible deployment documentation
|
||||
Delivered by: PR-1 (manual example guide); PR-2 (configuration-only production guide).
|
||||
|
||||
The system SHALL document configuration fields, existing-platform and optional self-hosted deployment, required initialization, verification, troubleshooting, upgrade, disable and rollback.
|
||||
|
||||
#### Scenario: Operator follows the guide
|
||||
Delivered by: PR-2.
|
||||
|
||||
- **WHEN** an operator deploys the supported integration using the published guide
|
||||
- **THEN** no JS or Nginx source file edits are required, all manual platform prerequisites are explicit, and enabled, disabled and failure behavior can be independently verified
|
||||
|
||||
#### Scenario: Operator follows the PR-1 Chinese example guide
|
||||
Delivered by: PR-1.
|
||||
|
||||
- **WHEN** an operator follows the Chinese integration guide without reading implementation source
|
||||
- **THEN** the guide explicitly identifies the required entry configuration edits and platform initialization, explains both a custom send/stop adapter and self-hosted Umami, and provides copyable deployment and acceptance commands
|
||||
- **AND** it explains the 12 defaults, finite rules and skipped diagnostics, upstream/host-gateway, supported sub-path mapping, CSP, actual Network payload and platform event checks, zero collection when disabled, troubleshooting, manifest/ID upgrades and shutdown
|
||||
- **AND** best-effort/no retry, the 20-intent loading cap, pinned Umami version and remaining transport metadata are disclosed, with configuration-only deployment clearly deferred to PR-2
|
||||
|
||||
#### Scenario: Separate merges keep the issue open
|
||||
Delivered by: PR-1 (scope declaration); PR-2 (completion gate).
|
||||
|
||||
- **WHEN** PR-1 merges independently
|
||||
- **THEN** Issue #989 remains open until PR-2 configuration-only deployment is complete and verified
|
||||
|
|
|
|||
|
|
@ -1,26 +1,36 @@
|
|||
## 1. Scope and integration
|
||||
- [x] 1.1 Confirm maintainer authorization, preserve contributor history and resolve latest-main translation conflicts.
|
||||
- [x] 1.2 Define runtime configuration, adapter boundary, failure behavior and production deployment scope.
|
||||
- [ ] 1.3 Validate this OpenSpec change and bind the existing PR/task.
|
||||
|
||||
## 2. Optional frontend capability
|
||||
- [ ] 2.1 Move helper/adapter to a single product source and preserve existing tests.
|
||||
- [ ] 2.2 Add default-closed runtime loader and vendor-neutral controller/registry.
|
||||
- [ ] 2.3 Cover consent, validation, duplicate init, async stop races and adapter failures.
|
||||
## 2. PR-1 (#1010)
|
||||
- [x] 2.1 Verify passive markers, frozen published IDs and manifest drift against the current base.
|
||||
- [x] 2.2 Verify the vendor-neutral helper, frozen defaults, finite rules, skipped diagnostics, repeat-init/stop and example adapter assertions.
|
||||
- [x] 2.3 Fix and regression-test the example edge's server-level 100M application upload limit, release Web upstream default and native Linux host-gateway mapping.
|
||||
- [x] 2.4 Provide an independently followable Chinese guide for existing-platform adapters and the local Umami demo, including configuration, deployment, acceptance, troubleshooting, upgrade and shutdown; link the English contract.
|
||||
- [x] 2.5 Align the two-PR interfaces and manually check OpenSpec structure against add-skill-suites (CLI unavailable; not CLI validation).
|
||||
- [x] 2.6 Run focused/full tests, typecheck, lint, build, manifest, Compose rendering and diff checks; repeat built-frontend/real-collector browser acceptance and the guide walkthrough, including upload boundaries.
|
||||
- [ ] 2.7 Independent parent review and publication; keep Issue #989 open.
|
||||
|
||||
## 3. Deployment
|
||||
- [ ] 3.1 Safely serialize and validate configuration without breaking existing runtime config.
|
||||
- [ ] 3.2 Add isolated proxy snippets with request-time DNS, certificate validation and exact endpoints.
|
||||
- [ ] 3.3 Wire Compose/Helm defaults and reserved sub-path validation.
|
||||
- [ ] 3.4 Provide optional persistent self-hosted Compose combination without another Nginx.
|
||||
## 3. PR-2 (follow-up): optional frontend capability
|
||||
- [ ] 3.1 Move helper/adapter to a single product source under web/src/features/analytics and preserve all PR-1 assertions.
|
||||
- [ ] 3.2 Add default-closed runtime loader and vendor-neutral controller/registry; register Umami as the first adapter.
|
||||
- [ ] 3.3 Cover consent, validation, duplicate init, async stop races and adapter failures.
|
||||
- [ ] 3.4 Validate this OpenSpec change with the CLI when available and bind the follow-up PR/task.
|
||||
|
||||
## 4. Documentation
|
||||
- [ ] 4.1 Replace source-editing quickstart with configuration-only production paths.
|
||||
- [ ] 4.2 Document fields, platform prerequisites, initialization, verification, upgrade and shutdown.
|
||||
- [ ] 4.3 Link deployment entry points and document adapter extension and actual privacy boundaries.
|
||||
## 4. PR-2 (follow-up): deployment
|
||||
- [ ] 4.1 Safely serialize and validate configuration without breaking existing runtime config.
|
||||
- [ ] 4.2 Add isolated proxy snippets with request-time DNS, certificate validation and exact endpoints.
|
||||
- [ ] 4.3 Wire Docker/Compose/Helm defaults and reserved sub-path validation.
|
||||
- [ ] 4.4 Provide optional persistent self-hosted Compose combination without another Nginx.
|
||||
|
||||
## 5. Quality gates
|
||||
- [ ] 5.1 Consolidated independent implementation review, fixes and final base checkpoint.
|
||||
- [ ] 5.2 Reviewed requirement/scenario/test matrix and targeted source/deployment checks.
|
||||
- [ ] 5.3 Exact-SHA release Compose S3/auth smoke and Chromium normal/changed/failure scenarios.
|
||||
- [ ] 5.4 CI/privacy/readiness, one validation report and retained preview for human acceptance.
|
||||
## 5. PR-2 (follow-up): documentation
|
||||
- [ ] 5.1 Replace source-editing quickstart with configuration-only production paths for supported platforms; distinguish custom adapter development.
|
||||
- [ ] 5.2 Document fields, platform prerequisites, initialization, verification, troubleshooting, upgrade and shutdown.
|
||||
- [ ] 5.3 Link deployment entry points and document adapter extension and actual privacy boundaries.
|
||||
|
||||
## 6. PR-2 (follow-up): quality gates
|
||||
- [ ] 6.1 Consolidated independent implementation review, fixes and final base checkpoint.
|
||||
- [ ] 6.2 Reviewed requirement/scenario/test matrix and targeted source/deployment checks.
|
||||
- [ ] 6.3 Exact-SHA release Compose S3/auth smoke and Chromium normal/changed/failure scenarios, including default zero module/SDK/request and root/sub-path upload/login/download/CSP/cache compatibility.
|
||||
- [ ] 6.4 CI/privacy/readiness, one validation report and retained preview for human acceptance.
|
||||
- [ ] 6.5 Close Issue #989 only after configuration-only deployment is complete and verified, not when PR-1 merges.
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue