MCP for Unity 外部数据分析架构cookieless 聚合遥测、公开徽章与私有维护者看板【免费下载链接】unity-mcpUnity MCP acts as a bridge between AI assistants and your Unity Editor. Give your LLM tools to manage assets, control scenes, edit scripts, and automate tasks within Unity.项目地址: https://gitcode.com/GitHub_Trending/un/unity-mcp导读本文基于 external-analytics.md 展开深入解析 MCP for Unity 如何在不使用 Cookie、不采集个人数据的前提下用多路聚合信号度量项目采纳度adoption并回答一个关键工程问题如何在公开可验证与维护者私有之间划出清晰的边界。读完本文你将掌握五类采纳信号的采集口径与可信度排序、PyPI 下载数与真实活跃用户数之间的鸿沟、GitHub Actions 每日统计工作流.github/workflows/stats.yml与抓取脚本website/scripts/fetch-stats.mjs的完整数据流以及维护者为启用 GitHub 流量统计、GoatCounter 文档流量统计和产品内 DAU/WAU 所需的全部配置步骤。项目背景为什么需要外部分析MCP for Unity 是连接 AI 助手与 Unity Editor 的桥接层Server 侧为 Python 实现入口见 Server/src/main.py其采纳情况横跨多个公开平台Python 包mcpforunityserver发布在 PyPI仓库在 GitHub文档站点托管在 GitHub Pages构建配置见 .github/workflows/docs-deploy.yml同时产品内部还有一套运行在 Unity Editor 里的埋点遥测。不同的分发渠道、不同的可见性决定了到底有多少人在用这个问题无法用单一数字回答。外部分析External Analytics就是为回答这个问题而设计的用多条独立的数据源互相印证同时严格约束数据边界——聚合可见、个体不可见、维护者私有不外泄。跟踪什么、为什么跟踪五类信号的诚实度排序文档给出了一个非常工程化的视角按对真实用户数量的诚实程度从高到低排列所有信号而不是把所有数字都当成活跃用户数。1. 产品内 DAU / WAU最诚实的信号产品内遥测Server/src/core/telemetry.py按匿名安装 UUID 去重统计日活用户DAU与周活用户WAU是唯一能代表真实活跃用户的指标。它在 Unity Editor 内部运行用户可以通过 MCP for Unity 设置窗口控制开关。从源码看遥测系统以TelemetryCollector为核心telemetry.py使用有界队列queue.Queue(maxsize1000)加单一后台 worker 线程fire-and-forget 发送队列满时丢弃新事件而不是阻塞业务put_nowaitqueue.Full捕获匿名标识是持久化到本地的随机 UUIDcustomer_uuid.txt用于去重统计活跃用户关键里程事件MilestoneType包括FIRST_STARTUP、FIRST_TOOL_USAGE、FIRST_SCRIPT_CREATION、FIRST_SCENE_MODIFICATION、DAILY_ACTIVE_USER、WEEKLY_ACTIVE_USER等telemetry.py其中 DAU/WAU 正是外部分析文档提到的真实活跃用户数据来源工具调用通过装饰器自动埋点telemetry_tooltelemetry_decorator.py记录工具名、成功/失败、耗时毫秒和 sub-action并触发里程碑记录。2. 唯一克隆者 / 浏览者14 天强代理信号来自 GitHub 仓库流量 API代表真正把代码拉下来的人。注意它天然私有只有协作者持有 token能读取因此这部分数据只进私有看板不会公开。3. GitHub Stars / Forks兴趣信号真实账号的 star/fork 行为完全公开但语义是兴趣而非使用——有人 star 不代表他跑过这个项目。4. PyPI 安装量reach 信号明显虚高mcpforunityserver在 pypistats.org 上的日/周/月下载数。文档与代码都反复强调它被严重高估CI 构建、镜像站镜像、uvx重新拉取、Docker 重建都会产生下载事件。它是安装事件的触达数reach不是用户数。README 中展示的下载徽章即来源于此。5. 文档流量GoatCounter文档站点启用 GoatCounter 后提供聚合页面浏览量。它是 privacy-first 的统计服务承诺不出售数据。所有信号共同遵守三条底线无 Cookie、无指纹、无用户 ID不传输、不存储任何 PII对外只暴露聚合数据。公开 vs 私有一条明确的边界线可见性内容说明公开README 中的 PyPI 下载徽章PyPI 下载数本身就是公开数据无论项目方是否主动展示私有仅维护者统一安装量 文档流量看板发布在 GitHub Actions 运行摘要中只有仓库协作者可见没有公开的统计页面也不向站点发布任何统计文件这条边界背后的考量是公开可验证的数据下载徽章承担外部可见的信号职责而真正能反映质量的信号DAU/WAU、唯一克隆者因为需要更高权限读取刻意保持维护者私有避免把噪声大的数据公开误导社区。数据流每日一次、零提交、私有发布的自动化管线完整流程由 GitHub Actions 工作流驱动共四步定时触发stats.yml 每天 UTC 06:00 运行同时支持workflow_dispatch手动触发Actions → Adoption stats → Run workflow。工作流只申请contents: read权限——它只读仓库、写运行摘要从不提交任何文件。抓取数据fetch-stats.mjs 使用 Node 20 运行抓取三类数据PyPI 近程下载数https://pypistats.org/api/packages/mcpforunityserver/recent公开无需 tokenGitHub 仓库元数据与 14 天流量/repos/{repo}、/repos/{repo}/traffic/clones、/repos/{repo}/traffic/views克隆/浏览接口需要带Administration: read权限的 token见下文GoatCounter 总浏览量当 secrets 存在时https://{site}.goatcounter.com/api/v0/stats/total。渲染摘要脚本的renderSummary函数生成 Markdown 表格明确区分两个区块——Real-user signals (the honest ones)真实用户信号与 Reach proxy (inflated — NOT a user count)触达代理并在 PyPI 数据不可用时输出提示避免把抓取失败误读成零下载。发布到私有看板node website/scripts/fetch-stats.mjs $GITHUB_STEP_SUMMARY把摘要追加到 GitHub Actions 运行摘要页。协作者在Actions → Adoption stats运行页查看数字仓库本身没有任何提交文档站点也不发布任何统计文件。从buildStatsfetch-stats.mjs的代码可以看出数据的归并结构githubstars/forks/14 天唯一克隆者/浏览者、pypilast_day/last_week/last_month、web总浏览量。而renderSummary中有一处重要的防御性设计当克隆/浏览数据缺失时会自动追加一行说明提示维护者需要配置带Administration: read权限的 PATSTATS_GITHUB_TOKEN避免空白被误读为没有流量。维护者配置三个高价值信号的上线步骤Stars、Forks 和 PyPI 数字开箱即用默认的GITHUB_TOKEN即可读取公开仓库元数据与 PyPI 公开 API。需要额外配置的是以下三个最高价值信号配置一唯一仓库克隆者 / 浏览者GitHub 流量GitHub 流量 API 要求比默认 token 更高的权限——文档明确指出默认的GITHUB_TOKEN调用该接口会返回 401/403。配置步骤创建 fine-grained PAT作用域限定到CoplayDev/unity-mcp权限设置为Repository permissions → Administration: read将该 token 添加为仓库secretSTATS_GITHUB_TOKEN。工作流中同时传入GITHUB_TOKEN默认 token用于公开数据和STATS_GITHUB_TOKEN维护者 PAT用于流量数据而抓取脚本在构建请求头时优先使用STATS_GITHUB_TOKENfetch-stats.mjs。配置二产品内 DAU / WAU真实活跃用户数这是唯一需要后端配合的信号数据已被 telemetry.py 按匿名安装 UUID 去重采集并 POST 到 Coplay 遥测后端默认端点https://api-prod.coplay.dev/telemetry/eventstelemetry.py但要在看板上展示需要该后端提供一个只读/聚合 API加 token。这项工作由 Coplay 负责一旦可用只需添加COPLAY_STATS_TOKENsecret并在fetch-stats.mjs中增加对应的抓取逻辑。在renderSummary中DAU/WAU 行的值默认显示为_pending_并标注已被产品内遥测采集需要 Coplay 读取 API。配置三文档流量GoatCounterGoatCounter 的配置分成采集与读取两条线涉及三种不同的 GitHub 配置在 goatcounter.com 创建一个免费站点例如 code 取mcp-for-unity保持仪表盘私有生成一个具有 stats 读取权限的 API token配置SecretsGOATCOUNTER_TOKENAPI token、GOATCOUNTER_SITE站点 codeActions variableGOATCOUNTER_CODE同样的站点 code。为什么GOATCOUNTER_CODE必须是 Actionsvariable而不是 secret从 docs-deploy.yml 的注释可以确认文档构建代码通过process.env.GOATCOUNTER_CODE判断是否注入无 Cookie 的 GoatCounter beacon见 website/docusaurus.config.js 与 website/docusaurus.config.js 的条件配置而 Actions不会自动把 secrets 暴露为环境变量必须由工作流显式映射。设计意图是采集发生在公开站点beacon 面向公众数字却保持私有读取 API token 只在维护者工作流中可用。配置完成后运行Actions → Adoption stats → Run workflow即可生成首份看板。stats工作流只需contents: read权限——它只向运行摘要发帖永不提交。隐私立场与可验证的实现证据文档声明的隐私立场在源码中有直接对应无 Cookie、无指纹、无用户 IDGoatCounter beacon 是 cookieless 的website/docusaurus.config.js 仅在设置GOATCOUNTER_CODE时启用GitHub 流量与 PyPI 均为平台提供的聚合接口。遥测可一键关闭TelemetryConfig._is_disabledtelemetry.py识别DISABLE_TELEMETRY、UNITY_MCP_DISABLE_TELEMETRY、MCP_DISABLE_TELEMETRY三个环境变量true/1/yes/on也可以在 MCP 客户端配置的env中注入record方法在enabled为假时直接返回telemetry.py。遥测永不干扰主流程1.5 秒超时可通过UNITY_MCP_TELEMETRY_TIMEOUT覆盖、异常全部捕获降级、端点校验拒绝 localhosttelemetry.py错误信息截断工具错误 200 字符、故障错误 500 字符telemetry.py。错误信息匿名化错误文本被截断且不包含代码内容——遥测文档website/docs/architecture/telemetry.md明确声明不采集代码内容、项目名、文件名、路径或个人信息。测试套件也印证了这些行为test_telemetry_endpoint_validation.py验证端点校验逻辑Server/tests/integration/test_telemetry_endpoint_validation.pytest_telemetry_queue_worker.py验证队列背压与单 worker 行为Server/tests/integration/test_telemetry_queue_worker.py集成测试的conftest.py在测试期间整体禁用遥测避免文件 I/O 与网络副作用污染测试Server/tests/integration/conftest.py。维护者摘要的内容边界最终发布到 Actions 运行摘要的维护者摘要只包含计数与时间戳生成时间、GitHub 信号表、PyPI 三窗口下载表、文档流量行以及必要的提示信息如克隆/浏览缺失时建议配置STATS_GITHUB_TOKEN、PyPI 不可用时不视为零下载。没有任何用户级明细、没有任何 IP 或设备信息、没有任何提交到仓库的文件。这是聚合可见、个体不可见原则在输出端的最后一道把关。小结用信号分层替代单一虚荣指标MCP for Unity 的外部分析体系提供了一个可复用的工程范式不要用一个数字回答有多少人在用而是把公开可得的数字按可信度分层——产品内 DAU/WAU真相、GitHub 唯一克隆/浏览强代理、Stars/Forks兴趣、PyPI 下载触达、文档流量关注度每一层都有明确的语义说明和缺陷标注例如 PyPI 被 CI 与uvx拉高。数据采集端做到 cookieless、匿名、可关闭、非阻塞数据发布端做到公开徽章 私有看板双轨制且看板不落库、不发布、仅供协作者在 Actions 运行页查看。这套设计兼顾了开源项目的透明度诉求、维护者的数据质量诉求以及终端用户的隐私诉求。延伸阅读遥测采集细节与用户退出方式website/docs/architecture/telemetry.md统计工作流定义.github/workflows/stats.yml抓取与渲染脚本website/scripts/fetch-stats.mjs遥测核心实现Server/src/core/telemetry.py文档站点构建GoatCounter 注入.github/workflows/docs-deploy.yml【免费下载链接】unity-mcpUnity MCP acts as a bridge between AI assistants and your Unity Editor. Give your LLM tools to manage assets, control scenes, edit scripts, and automate tasks within Unity.项目地址: https://gitcode.com/GitHub_Trending/un/unity-mcp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考