server-side-tracking

tracklution-cli

用于 AI 编码 Agent 的 npm 包单体仓库，作为 Tracklution 品牌和类别入口发现的切入点：

• tracklution -- 正式包。发布的二进制文件会运行供 Agent 读取的安装说明。
• create-tracklution -- 别名，可让 npm create tracklution@latest 正常工作。
• @tracklution/cli -- 为作用域预留的别名。
• tracklution-mcp -- 当前为别名；未来版本将提供本地 stdio<->Streamable-HTTP MCP 代理。
• server-side-tracking -- 类别入口别名，适用于 npm view server-side-tracking / npx server-side-tracking。
• conversion-tracking -- 类别入口别名，适用于 npm view conversion-tracking / npx conversion-tracking。
• conversion-api -- 类别入口别名，适用于 npm view conversion-api / npx conversion-api。

这是什么

当用户向 AI 编码 Agent（Cursor、Claude Code、Codex、Windsurf、Cline、Lovable、Replit、Bolt 等）输入“安装 Tracklution”——或按类别输入“安装服务端跟踪” / “安装转化跟踪”——大多数 Agent 会本能地运行 npm view <name>，然后运行 npx <name>。这些包的存在，就是为了让这一流程顺利执行，并通过 Agent 通常读取 stdout 的工具循环，提供确定且可直接粘贴的安装说明，而不是转而进行网页搜索并自行编造跟踪代码。

实际安装通过 Tracklution MCP 服务 https://mcp.tracklution.com/mcp 进行。Agent 通过一次性 REST 引导接口 https://api.trlution.com/install/quick-setup 访问此 MCP（即“魔法安装”路径）——该接口会为用户创建账户，并返回一个 mcp.json 片段，其中已包含 Authorization: Bearer <jwt>。此 CLI 会发布该流程的机器可读描述。

User: "Install Tracklution"
   |
   v
Agent runs `npm view tracklution`         (finds the package)
Agent runs `npx tracklution`              (reads stdout + parses --json)
Agent POSTs to /install/quick-setup       (one HTTP call, REST bootstrap)
Agent merges data.mcp_config_snippet      (Authorization header included)
Agent calls get_status -> get_installation_scripts -> verify_and_score
            (every onboarding call carries container_hash for auth)

用户操作型宿主（Lovable、Replit、Bolt）无法在 Agent 内部执行 HTTP-POST + 文件编辑，因此会改用 OAuth“连接”按钮流程——CLI 的 install_methods 块会通过 magic_install_supported: true 告知 Agent 哪些宿主支持魔法安装。

目录结构

tracklution-cli/
  package.json                   workspace root (private, not published)
  packages/
    tracklution/                 canonical published package (the bin)
      bin/cli.js
      src/payload.js             single source of truth for the stdout payload
      package.json
    create-tracklution/          resolve-and-spawn shim
    at-tracklution-cli/          resolve-and-spawn shim (publishes as @tracklution/cli)
    tracklution-mcp/             resolve-and-spawn shim
    server-side-tracking/        resolve-and-spawn shim (category-surface)
    conversion-tracking/         resolve-and-spawn shim (category-surface)
    conversion-api/              resolve-and-spawn shim (category-surface)
  tests/
    cli.test.js                  default / --json / --version / --help
    parity.test.js               compare local payload to live install-recipes endpoint
    aliases.test.js              each alias produces the same stdout as the canonical
  plugins/
    claude/tracklution/          Claude plugin bundle (submitted from this repo path; skills are the single copy)
    openai/tracklution/          OpenAI plugin package source (plugin.json, mcp.json, assets/)
  scripts/build-openai-plugin.js builds the OpenAI ZIP: package source + the Claude skills
  server.json                    MCP Registry entry (remote only)
  .github/workflows/
    test.yml                     lint, tests, pack dry-run; uploads the OpenAI ZIP as a run artifact
    publish.yml                  npm publish on v* tags
    release.yml                  attaches the OpenAI ZIP to the GitHub release on v* tags (public link)
    mcp-registry.yml             manual: publish server.json to the MCP Registry

开发

npm install               # installs workspace deps, symlinks packages/* into each others node_modules
npm test                  # runs Vitest across all three test files
npm run lint              # syntax-checks every bin/cli.js
npm run pack:dry          # dry-run npm pack for all published packages

发布

在每个 packages/*/package.json 中更新版本号（保持一致），打上 vX.Y.Z 标签，然后推送到 GitHub。.github/workflows/publish.yml 中的发布工作流会验证版本号是否一致，然后按依赖顺序为每个包运行 npm publish --provenance（先发布正式包 tracklution，再发布所有别名垫片）。

推送同一标签时还会运行 .github/workflows/release.yml，构建 OpenAI 插件 ZIP，并将其附加到该标签对应的 GitHub 发布版本（若不存在则创建）。公开下载链接，无需登录 GitHub：

• https://github.com/tracklution/tracklution-cli/releases/download/vX.Y.Z/tracklution-openai-plugin-<plugin version>.zip
• https://github.com/tracklution/tracklution-cli/releases/latest/download/tracklution-openai-plugin.zip（始终指向最新发布版本）

若要将从 main 构建的 ZIP 附加到现有发布版本，而不创建新标签，请手动运行 release 工作流（Actions、release、Run workflow）并输入标签名称。运行摘要会显示下载链接。

目录列表

• ChatGPT（OpenAI）： 上方的 ZIP 文件就是要上传到 platform.openai.com/plugins 的文件。修改 plugins/openai/tracklution/ 下的内容或技能时，请更新 plugins/openai/tracklution/plugin.json 中的 version（OpenAI 会将每次上传视为新版本），并按上述说明发布。首次提交前，还需要在 plugin.json 中填写 review.demo_recording_url，并由 MCP 主机提供域名验证令牌（OPENAI_APPS_CHALLENGE_TOKEN）。
• Claude： 目录会直接从此仓库读取 plugins/claude/tracklution；无需上传。使用 claude plugin validate ./plugins/claude/tracklution --strict 在本地验证。
• 技能只维护一份，位于 plugins/claude/tracklution/skills/；构建 OpenAI 版本时会将其复制到 ZIP 文件中。
• MCP Registry： 更新 server.json 中的 version（每个版本只能发布一次），然后手动运行 mcp-registry 工作流。

单一事实来源

安装方式、MCP URL 和参考 URL 在以下位置都有副本：

• packages/tracklution/src/payload.js（此仓库）
• tracklution-app/src/config/install-recipes.json
• tracklution-app/public/.well-known/tracklution.json
• tracklution-app/public/agent-install.md（文字说明）

tests/parity.test.js 会检查这些内容是否一致：它会获取实时的 https://www.tracklution.com/api/install-recipes/ 端点，并对照检查 payload.js 中的 install_methods 区块。若设置了 PARITY_TEST_SKIP=1（离线 CI），或实时端点返回非 200 状态码，则会跳过测试。

许可证

MIT。