Skip to content

armgit / cindy

Public Imported from GitHub
0

Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。

docs(plugins): 整理统计功能交付说明与真实验收截图

nanac4aae2ad9aba
diff --git a/docs/acceptance/plugin-statistics-pr/README.md b/docs/acceptance/plugin-statistics-pr/README.md
new file mode 100644
index 0000000000..5ee278595d
--- /dev/null
+++ b/docs/acceptance/plugin-statistics-pr/README.md
@@ -0,0 +1,30 @@
+# 插件统计客户端验收摘要
+
+本目录只公开必要真实截图与核对摘要,不包含原始日志、凭证、用户路径、测试启动脚本或隐藏宿主补丁。用户已确认设计、实现截图与列表/个人卡样式。
+
+## 真实页面与版本
+
+| 页面 | 截图 |
+| --- | --- |
+| 列表深色 | [列表](screenshots/list-dark.png) |
+| 个人详情浅色 | [详情](screenshots/personal-light.png) |
+| 个人详情深色 | [详情](screenshots/personal-dark.png) |
+
+三图 renderer 完整源码为 46f937a39117ded3ef0fac4874d6e37a276c81ac;初始 main/preload/协议由 97b9ff46cad27a76689928d1b088a16a2412d419 完整冷构建并 ready。46f 仅删失效文案与注释,main/preload/协议不变,通过正常 HMR/reload 拍图,不声称 46f 冷启动。TypeScript 去注释 emitted JS、CSS 规则与除四个删除键外的五种语言资源等价;截图 SHA256 见 [screenshots.json](screenshots.json)。测试壳仅限制验收窗口可见性、焦点和原生 dialog,没有进入产品提交。完整验收源码与测试壳差异独立核对,不能把实际壳 SHA 误作产品 SHA。
+
+列表只有一个真实联调插件,fixture 没有作者;列表浅色在更早的 73b7 UI 基线已目检,本次清理只重拍深色。截图中共享调用 6、滚动 168h 调用 6、下载 URL 请求 3、个人调用 3,来自隔离业务源,不是设计数字。后端使用冻结历史版本的隔离联调资源,不代表 PR #887 已部署。
+
+## 已验证
+
+- 列表展示范围与下载,详情版本旁下载与累计使用;个人无分割线、标题右侧清除,双主题无溢出。
+- 97b9 卡片样式冷启动 computed style:标题 14/500/20、时间/次数 14/400/20、标签 12/400/16;padding 16、border 1、radius 12、间距 12/4/16;跟随父内容区,标准/800/700 窗口卡宽 760/451/367,当前内容自然高 114。
+- 正常打开清除确认并取消,完整个人 summary 不变;没有清除真实历史。成功清除的事务与代际语义由隔离 fixture 回归覆盖。
+- 更早 UI 基线覆盖已安装/市场已安装预览、700/800 窄宽及共享头部 hover;真实未安装、作者、零/缺失与大整数以组件测试覆盖,不冒称实机数据验证。
+- 定向 namespace 回归覆盖同 ghostId 不同实例的读取、清除和来源回填隔离;不冒称真实多 namespace 插件 E2E。
+- 46f 清理 103 项 UI/排版测试、类型检查、renderer lint/i18n 通过,三图逐张目检;原始本地证据与索引保留。
+
+## 发布整合与限制
+
+发布准备在 46f 上合入 canonical main c950b504649f2c64668c618320c352d159370961。主干未改变 migration/schema/锁文件,0126/0127 无撞号,三处测试 mock 合并保留双方新增接口。发布前已运行 52 文件 1072 项 Desktop 定向测试、协议包 165 项测试/类型构建、Desktop 类型检查、迁移静态校验及 14 项回放;当前截图不冒称整合后冷启动截图,统计组件/样式与 46f 相同。
+
+本地全量门禁未执行,等待 PR CI。此次按已授权的影响面验证,未重跑无关整仓;独立 review、评分及插件基座指定 Approve 仍为合并前门禁。真实键盘激活、其他字号档位和长外语布局未验证;本轮未操作正式 profile、宿主、生产服务或数据。
diff --git a/docs/acceptance/plugin-statistics-pr/checks.json b/docs/acceptance/plugin-statistics-pr/checks.json
new file mode 100644
index 0000000000..e2e67ab7bf
--- /dev/null
+++ b/docs/acceptance/plugin-statistics-pr/checks.json
@@ -0,0 +1,59 @@
+{
+ "acceptedSource": "46f937a39117ded3ef0fac4874d6e37a276c81ac",
+ "integrationSource": "c2041018d21ab18f55e9ee0881abfdb50eca436a",
+ "canonicalBase": "c950b504649f2c64668c618320c352d159370961",
+ "checks": {
+ "desktopTargeted": {
+ "files": 52,
+ "passed": 1072,
+ "exitCode": 0
+ },
+ "desktopTypecheck": {
+ "exitCode": 0
+ },
+ "protocolTest": {
+ "files": 11,
+ "passed": 165,
+ "exitCode": 0
+ },
+ "protocolBuild": {
+ "exitCode": 0
+ },
+ "migrationStatic": {
+ "range": "0000..0127",
+ "exitCode": 0
+ },
+ "migrationReplay": {
+ "passed": 14,
+ "exitCode": 0
+ },
+ "i18n": {
+ "exitCode": 0,
+ "existingWarnings": true
+ },
+ "glossary": {
+ "exitCode": 0
+ },
+ "publicTrackedDocs": {
+ "passed": 10,
+ "exitCode": 0
+ },
+ "desktopChangedFilesESLint": {
+ "files": 43,
+ "exitCode": 1,
+ "errors": 33,
+ "introducedErrors": 0,
+ "baseline": "c950b504649f2c64668c618320c352d159370961",
+ "comparison": "ruleId/message/source-line equality"
+ },
+ "diffCheck": {
+ "exitCode": 0
+ }
+ },
+ "limitations": [
+ "Local full suite not run; full CI pending",
+ "Root docs check fails on existing untracked local evidence-copy links; public tracked-file snapshot passes without modifying local originals",
+ "No independent review or numerical score yet",
+ "Screenshot renderer source 46f; initial main ready 97b; no claim of integration-source cold start"
+ ]
+}
diff --git a/docs/acceptance/plugin-statistics-pr/screenshots.json b/docs/acceptance/plugin-statistics-pr/screenshots.json
new file mode 100644
index 0000000000..240213f7f0
--- /dev/null
+++ b/docs/acceptance/plugin-statistics-pr/screenshots.json
@@ -0,0 +1,19 @@
+{
+ "rendererSource": "46f937a39117ded3ef0fac4874d6e37a276c81ac",
+ "initialMainReadySource": "97b9ff46cad27a76689928d1b088a16a2412d419",
+ "coldStartAtRendererSource": false,
+ "files": [
+ {
+ "path": "screenshots/list-dark.png",
+ "sha256": "d2f1ddfd96c161f58772934e6401f365fc8d0f634f600fc49929fbfa2b3e3460"
+ },
+ {
+ "path": "screenshots/personal-light.png",
+ "sha256": "5bd40f60f174d579b5d78c6795de2168fcdbf5d9117a318ca5ff7419bb17ff85"
+ },
+ {
+ "path": "screenshots/personal-dark.png",
+ "sha256": "aa172d921333bff3b06cc22eab4c7507d8f57f4b4046e8b2890f66531ee8deeb"
+ }
+ ]
+}
diff --git a/docs/acceptance/plugin-statistics-pr/screenshots/list-dark.png b/docs/acceptance/plugin-statistics-pr/screenshots/list-dark.png
new file mode 100644
index 0000000000..b6a793f7a4
Binary files /dev/null and b/docs/acceptance/plugin-statistics-pr/screenshots/list-dark.png differ
diff --git a/docs/acceptance/plugin-statistics-pr/screenshots/personal-dark.png b/docs/acceptance/plugin-statistics-pr/screenshots/personal-dark.png
new file mode 100644
index 0000000000..dce6ba0d7e
Binary files /dev/null and b/docs/acceptance/plugin-statistics-pr/screenshots/personal-dark.png differ
diff --git a/docs/acceptance/plugin-statistics-pr/screenshots/personal-light.png b/docs/acceptance/plugin-statistics-pr/screenshots/personal-light.png
new file mode 100644
index 0000000000..87edc415ea
Binary files /dev/null and b/docs/acceptance/plugin-statistics-pr/screenshots/personal-light.png differ
diff --git a/docs/plugin-usage-statistics-implementation.md b/docs/plugin-usage-statistics-implementation.md
index 81b4412844..9779f3f033 100644
--- a/docs/plugin-usage-statistics-implementation.md
+++ b/docs/plugin-usage-statistics-implementation.md
@@ -1,111 +1,41 @@
-# 插件调用统计:客户端实施记录
+# 插件调用统计:客户端实施说明
-2026-10-12,基于客户端 `fa3fc88d37d205ea993a67d85612fa9a5436fae5`,在隔离任务分支本地实施。
-原方案见 [plugin-usage-statistics-plan.md](plugin-usage-statistics-plan.md)。原交接文档保持原样,SHA256 为
-`bbc7a3dd07d530ff2d443dfa6752c328a4106c85df15200e8c3040c26b4c0184`。
+本功能保留当前电脑、当前账户的个人调用记录,并在插件目录提供授权共享统计时展示下载和使用次数。设计与真实 UI 已由用户确认;服务端独立交付见 [cindy-server PR #887](https://github.com/xindong/cindy-server/pull/887),此说明不代表生产服务已部署。
-## 本次完成
+## 个人记录
-- 账户 SQLite 的历史身份与调用事件两张表;Drizzle 增量迁移 `0126_dazzling_pyro.sql`。
-- 在 `GhostPipeDispatcher` 校验通过、`sendToGhost` 成功返回后异步记录,使用现有 callId 去重。
- 失败、超时和明确取消保存独立 outcome。调试调用明确排除;参数和结果正文不进入统计。
-- 安装落位后、市场账本提交后、启动和稳定账户切换时验证并绑定来源。派发热路径使用已绑定的
- 身份快照,不读取插件文件。普通升级与回滚保留本地连续安装的主体;本地卸载重装分开,
- 可验证市场来源重装延续。禁用、卸载及任务删除保留历史事件。
-- 主进程短队列与每步 owner/clientEpoch 核验;切号和退出在关闭数据库前有界排空。
- 清除以一个 worker 事务递增持久代际并删除明细,旧句柄不重放,迟到结果只 UPDATE。
-- 安装详情中的单个个人卡片:最近使用、滚动 168 小时调用数、三个参与任务、刷新和确认清除。
- 最近任务先过滤删除,再去重排序 LIMIT 3,标题实时读取。跳转复用现有伙伴/普通/Orca 任务入口。
- 卡片以账户代际为 key,避免切号后保留旧账户的显示结果。
-- 未安装详情在版本后展示带图标的共享安装/使用指标及口径说明;公共与企业插件只使用服务端
- 已授权响应,custom/public 标记不扩大共享范围。缺失统计时整段隐藏(含分隔点),真实字符串
- `"0"` 才显示 0;使用次数采用用户选定的 `Tally5` 计数刻度图标。Light/Dark 均走语义 token,五种语言同步。
+- GhostPipeDispatcher 通过可见性、启用、工具声明、权限及账户检查,且 sendToGhost 接受派发后计一次;已有 callId 去重。派发后的失败、超时或取消只更新 outcome,不增加次数;调试入口不计。
+- 账户 SQLite 追加 plugin_usage_subjects 与 plugin_usage_events。0126_dazzling_pyro 建表,0127_thin_midnight 添加待上报索引。历史 migration 不修改;7 日窗口是滚动 168 小时的查询条件,不是记录保存期限。
+- 参数、结果正文和凭证不进入记录。个人明细保留宿主工具名、任务引用、版本/发布身份与结果状态,不作为计费级审计。
+- 普通升级/回滚保留连续安装主体;本地卸载重装分开,来源可验证的市场重装延续主体。禁用、卸载及任务删除不删除历史。
+- 绑定、派发和查询使用实际实例键;市场账本按真实 namespace 精确查来源。同名根/组织实例不能借用另一份记录或来源。旧无 namespace 安装继续沿既有 helper 的兼容路径工作,不要求重装、重新批准或配置。
+- owner/clientEpoch 与 historyGeneration 隔离切号和清除。清除在一个 worker 事务中递增代际并删除明细,迟到结果只 UPDATE;旧句柄不重放。
-## 服务端依赖与协议
+## 可选共享统计与上报
-现有 `PluginDownload` 是获取下载地址次数,不是安装回执。没有重新使用已关闭的
-#2310/#2337 分支。初次个人记录实施未修改服务端;后续累计下载接入见下节。
+- 下载来自 downloadStatistics.requestCount:成功取得下载 URL 的次数,包含升级、重装和再次取票,**不是成功安装量**。没有成功安装字段或估算。
+- 使用来自 usageStatistics={usageCount,usageCountLast7Days,asOf};非负十进制字符串按 BigInt 显示,缺失/非法指标独立隐藏,真实 0 显示。schemaVersion 仍为 2,旧服务省略字段不会破坏目录或安装功能。
+- public/organization 只消费原有授权目录响应;组织的成员、角色、部门门禁不扩大。local/custom 不因为显示 public 标签而进入共享范围。共享读取缓存 60 秒,不缓存个人查询。
+- 仅在当前账户、非 local 模式、允许分析数据且来源账本与安装字节身份验证通过时,为新派发冻结 reportTarget。发送前再次核对 owner、服务根和来源;不跨服务根重试、不借用后来登录账户。
+- wire 回执仅发送 eventId、releaseId、occurredAt;不发送工具名、任务 ID、参数/结果正文或凭证。SQLite 原记录保存 pending/sent/rejected 状态,批量 ACK/duplicate 去重、退避重试;不开文件 outbox,不补传未取得合法目标的旧记录。
+- 关闭分析数据后暂停发送;切号/退出在数据库关闭前有界收尾。崩溃、磁盘故障或尚未绑定的派发可能漏记,不承诺 exactly-once。
+- 旧服务未实现回执端点时退避保留 pending;共享字段缺失时 UI 隐藏。个人清除不撤销已被服务端接收的聚合记录。
-现有 v2 列表和详情可选扩展 `usageStatistics`,不提升 `PLUGIN_API_SCHEMA_VERSION`:
+## 已确认 UI
-```json
-{
- "usageStatistics": {
- "installationCount": "12",
- "usageCount": "345",
- "usageCountLast7Days": "67",
- "asOf": "2026-10-12T00:00:00.000Z"
- }
-}
-```
+- 列表灰字保留范围、作者(存在时)与累计下载,移出版本和机器 ID。
+- 已安装和市场详情的版本旁显示累计共享下载与使用;内容区不超过 520px 时 metadata 放到 hero 下一整行。
+- 个人卡只展示最近调用、近 7 日调用,没有任务列表、图标、分割线、更多菜单或正常态刷新;清除直接放标题右侧,保留确认与取消,失败态仍可重试。
+- 使用既有语义 token,双主题实现。标题 14/500/20,时间与次数 14/400/20,标签 12/400/16;padding 16、容器圆角 12、描边 1、间距 12/4/16。卡片跟随父内容宽度、自然高度,字号和行高随既有设置缩放。
-计数是非负十进制字符串;非法或缺失的可选统计隐藏,不让整个市场响应失败。
-安装次数必须来自成功安装回执:普通升级不增加,成功重装新增,卸载不倒扣。
-使用次数为已接收的派发事件。企业响应必须沿原有 visibilityAudience/部门/角色授权过滤。
-服务端仍需实现成功安装回执、幂等调用批量接收和授权聚合查询,接口建议见原方案第 12 节。
+真实截图及受测版本边界见 [公开验收摘要](acceptance/plugin-statistics-pr/README.md)。图片为隔离 Electron 中真实页面,不是生成稿或伪造统计。
-**客户端本次不上报。** 事件 `report_target` 为 NULL、`report_state` 为 `not-applicable`;没有
-outbox 文件、定时发送器、联网重试或对历史个人记录的补传。预留列不等于已完成发送能力。
-服务端完成并明确上线范围后,再单独实现上传和 ACK/重试/来源隔离验收。
-没有可靠插件级 token 来源,本次不显示 token 估算。
+## 验证与交付边界
-## 已验证
+发布准备基于用户验收的 46f937a39117ded3ef0fac4874d6e37a276c81ac,合入 canonical main c950b504649f2c64668c618320c352d159370961。主干没有 migration/schema/锁文件变化,0126/0127 未撞号;三个测试 mock 的合并保留统计绑定与旧作品库接回两套接口,产品代码自动合并后复核。
-- Desktop 15 个定向测试文件,共 408 项通过:派发资格与结果、身份、重复 callId、清除交错、
- 真实 SQLite 双连接、inline/file worker、inproc DbClient、账户与退出边界、市场回归、卡片和跳转。
- 本地升级/回滚/重装的版本快照另按最新用例复核。
-- 协议包 127 项测试通过;Desktop 与协议包类型检查通过。
-- 迁移校验六步通过;迁移回放 14 项通过。原来三项末尾序号断言已增加 0126,并检查新表存在,
- 未更改任何历史 migration。
-- 新模块与组件 ESLint、i18n 完整性、术语检查以及 `git diff --check` 通过。扩大到全部修改文件的
- ESLint 仍有 25 条既有错误:bootstrap 6 条、cindy-brain/index 11 条、WorkerThreadTransport 8 条。
- 对三个文件分别用相同 ESLint 配置检查原 HEAD 内容,并按规则、消息与源码行对比,新增错误为 0。
-- 独立 `--isolated=@worktree` Global 开发版启动返回 `DESKTOP_DEV_VERDICT=ready`。
- 安装仅在这个沙箱中的本地验收插件,主进程正常 IPC 查询读取真实 SQLite 的空历史;调试工具
- 成功执行前后正式调用数均为 0;实际确认清除后记录起点更新。个人卡片与公开市场缺失统计的
- Light/Dark 真实页面截图另存本地验收目录,不把示意数据写入截图或生产数据库。
+整合后的定向测试包括个人记录/回执、市场/账本、派发器、实例/namespace 与旧作品库边界、DbClient 和插件 UI;协议包全测试/类型构建、Desktop 类型检查、migration 静态校验和真实回放另列在 PR。针对修改文件执行 lint/i18n/术语与 DCO 检查,既有失败需披露,不能称整仓全绿。
-## 未验证或未实施
+未提供跨设备个人历史同步、Mobile 统计页、token 估算、成功安装回执或排名反作弊。真实键盘激活、替代字号档位和所有语言的实机布局未验证;零/缺失/大整数及无作者以定向测试覆盖。插件基座变更仍需指定放行人明确 Approve;CI/独立 review/评分未完成前不能宣称可合并。
-- 没有执行真实模型发起 MCP 调用、产生非零记录并点击参与任务的完整端到端流程;这些边界
- 当前由真实派发器、数据库与组件定向测试覆盖,不能将其表述为模型端到端验收完成。
-- 共享回执/统计没有服务端联调,未实现上传。Mobile 没有新增统计页面;个人数据属于实际执行
- 插件的 Desktop 宿主,不合并其他电脑的数据。
-- 异步数据库写入在崩溃、磁盘故障或绑定尚未就绪时可能漏记,未承诺计费级 exactly-once。
-- 普通退出、切号和企业下架沿原有生命周期;未扩展账户删除系统,未声称注销已物理擦除数据库。
-- 本次仅本地交付;没有 push、创建 PR、合并或部署。插件基座变更仍需指定维护者 Approve 才能合并。
-
-## 2026-10-12 展示修订
-
-- 根据用户反馈,市场头部无统计数据时隐藏整段指标和分隔点;已有明确的 0 仍正常显示。
- 用户选择 `Tally5` 替换快速模式已使用的 `Zap`。不改变个人卡片的空记录呈现。
-- 两个相关组件测试文件共 12 项通过,Desktop 类型检查、相关文件 ESLint 和 diff 检查通过。
-- 在本 worktree 独立 Electron 开发版中通过前端热更新查看真实 TapTap Maker 详情,Light/Dark
- 均已目检无统计时的头部;截图位于 `apps/desktop/logs/plugin-usage-acceptance/shared-usage-followup/`。
- 服务端当前未提供统计,带数字与新图标的真实市场状态尚未实机验证;没有伪造市场数字。
-
-## 2026-10-12 接入累计下载
-
-用户要求接入 Platform 已有的累计数字。实际核对服务端 main `8e0ae149` 和 release 后,
-确认后台统计为下载地址签发次数:`downloadStatistics.requestCount`(累计)和
-`downloadStatistics.last7DaysRequestCount`(滚动 168 小时)。客户端头部只显示累计“下载”,
-使用 `ArrowDownToLine`,提示说明包括更新、重装和重新请求地址的重试,不代表安装成功。
-
-- 客户端沿 `PluginMarketApi` → v2 协议解析 → 市场服务投影 → 详情组件传递同名字段。
- 精确字符串用 BigInt 格式化,无 Number 精度损失;缺失或无效字段隐藏,明确的 0 正常显示。
- 不合成成功安装或使用次数;个人/custom 插件不展示共享下载数。
-- 服务端独立本地分支 `/Users/huangxiaowen/Developer/cindy-server` 的
- `feat/plugin-client-download-statistics`,给 `/api/plugins` 列表和详情加可选字段,
- 复用已有 `pluginDownloadStatistics` 批量聚合,不新增表、上报或 Platform 凭证。
- 企业统计在原可见性/部门/角色门禁通过后查询;统计读取失败省略字段,不伪造 0。
-- 服务端契约与客户端一致,schemaVersion 仍为 2;旧服务不发字段时客户端继续正常工作。
- 两仓均只在本地实现,未推送、创建 PR 或部署。线上数字显示仍取决于服务端发布此扩展。
-
-验证:客户端协议包 128 项、三个受影响 Desktop 测试文件 192 项通过;服务端协议包
-145 项、plugin-server 609 项通过(41 项数据库集成测试未配置安全数据库而跳过)。
-两仓协议类型检查、plugin-server 与 Desktop 类型检查、相关 ESLint、五语完整性、术语与 diff 检查通过。
-独立 Global Electron 沙箱启动返回 `DESKTOP_DEV_VERDICT=ready`,当前代码下真实 TapTap Maker
-详情的缺失指标隐藏在 Light/Dark 均已目检,截图在
-`apps/desktop/logs/plugin-usage-acceptance/cumulative-download/market-{light,dark}.png`。
-线上服务尚未返回下载统计,带数字的生产数据联调未完成,不将测试中的 123 当成实际累计数。
-本次未运行客户端整仓全量测试;按影响面完成协议包与市场/详情定向验证,完整门禁待后续 PR CI。
+原 [方案草案](plugin-usage-statistics-plan.md) 仅作历史设计参考;其安装回执、任务列表和接口建议不作为当前实现事实。
diff --git a/docs/plugin-usage-statistics-plan.md b/docs/plugin-usage-statistics-plan.md
index 9a10841192..cda2b3b2c8 100644
--- a/docs/plugin-usage-statistics-plan.md
+++ b/docs/plugin-usage-statistics-plan.md
@@ -1,6 +1,6 @@
# 插件调用统计与个人记录保存方案
-> 状态:方案草案,供实现与评审使用;不代表功能已上线或服务端接口已存在。
+> 状态:2026-10-12 历史方案草案,不作为当前实现或上线事实;最新范围见 [客户端实施说明](plugin-usage-statistics-implementation.md)。其中成功安装回执、任务列表与接口建议尚有未采纳内容。
> 整理日期:2026-10-12。
> 范围:个人工具调用记录、插件生命周期、共享统计及安装回执机制复用。
> 分工:产品方向由用户确定;第 7 节记录已提出的两种安装状态及个人数据卡片要求,