Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。
插件调用统计与个人记录保存方案
状态:2026-10-12 历史方案草案,不作为当前实现或上线事实;最新范围见 客户端实施说明。其中成功安装回执、任务列表与接口建议尚有未采纳内容。 整理日期:2026-10-12。 范围:个人工具调用记录、插件生命周期、共享统计及安装回执机制复用。 分工:产品方向由用户确定;第 7 节记录已提出的两种安装状态及个人数据卡片要求, Token 展示仍属可选项,具体视觉稿与界面实现尚未交付。 工程约束:沿用现有客户端和服务端技术栈,不新增依赖、数据库类型或独立统计服务。
1. 目标与方案结论
用户需要了解插件的使用情况,同时保留自己的调用记录供未来使用。实现优先简单、 准确、易维护,并适配 Cindy 已有的插件来源、账号隔离、安装和卸载机制。
采用以下设计:
- 个人调用明细存入现有账号本地数据库,作为个人统计的事实来源。
- 时间范围是查询条件;7 天不是保存期限,不随时间窗口清除原始记录。
- 插件历史身份与当前安装状态分离,卸载、失效、升级不会自动删除个人历史。
- 公开市场及企业插件可向服务端上报最小调用回执;本地、自定义来源默认只记个人记录。
- 调用记录本身保存上报状态,不另建文件队列或第二套个人计数器。
- 复用现有来源校验、账号边界及旧安装回执方案的发送约束,不建设通用埋点平台。
第一版不包含跨设备个人历史同步、完整调用参数与结果归档、业务操作审计、计费、 排名反作弊系统或插件行为分析平台。
2. 调研事实与证据边界
客户端调研基线为 47da2a9c98f17d9bb008e0663a53418e8bda4009;服务端调研基线为
xindong/cindy-server@2f78a0d72d9bebf42465c0bea31bc30a65336da9。
以下是这些版本的源码事实,不代表生产部署状态;实施前须对照届时主干复核。
2026-10-12 工程补查以本方案 worktree 的客户端
37f012cd70d601e3b06ed67a18f0e60e46677cb5 为固定基线,服务端仍为上述版本。
重点核对实际 SQL worker、账号关闭、安装换源、API 封装、Prisma schema、路由鉴权与限流。
第 10—13 节记录工程收口;不将多账号架构文档里的未来 Profile 设计当作当前实现。
| 已核实事实 | 对方案的约束 |
|---|---|
| 插件共用 Ghost runtime,一个插件可以组合 tools、Skill、面板、卡片、订阅等能力 | 工具调用量不能代表所有插件使用行为 |
| 展示来源有 public、organization、local、custom;官方信任与发布范围是不同维度 | 不能仅按“官方/企业/本地”三个标签归属数据 |
| 自定义市场内部也可能使用 public scope | 必须先判断来源类型,不能据 scope 上报公共统计 |
| 安装账本记录 pluginId、ghostId、releaseId、来源、sourceKey 和清单摘要 | 复用账本与已安装包匹配判据,不能只用名称或 ghostId |
| 集中工具派发已有 callId、账号边界和结果收口 | 计数在宿主派发边界完成,无需插件自行埋点 |
| 最近使用列表、卡片记录、媒体台账均不能覆盖完整工具调用历史 | 不从这些数据反推历史次数 |
| 卸载会删除包、凭证、KV、私有目录及缓存,但保留个人作品库并标记 orphaned | 个人调用历史同样独立于插件运行数据保存 |
| 企业 purge 复用卸载路径 | 当前 purge 不能被解释为清除全部个人历史 |
| 服务端 PluginDownload 记录下载请求 | 下载量不能当作成功安装量或调用量 |
| 企业可见性还有成员、角色、部门等限制 | 共享统计沿用插件可见性权限,不能只检查属于同一企业 |
历史方案:
- PR #2310:已关闭、未合入;按本地日期保存 调用日汇总,查询近 7 日并保留 90 日。它不能提供本方案要求的个人逐次历史。
- PR #2337:已关闭、未合入;成功安装公共 市场插件后发送安装回执,同一路由升级不增加安装次数。可复用其设计与适用代码, 不能当作主干现成的上报能力。
- 所检查的服务端客户端插件路由未提供本方案的调用回执接收接口;共享统计需另行实现。
3. 计数口径
3.1 什么算一次
指标为“工具调用次数”。通过宿主检查且成功派发给插件的工具调用计一次:
- 通过可见性、启用状态、工具声明、权限和账号检查。
- 插件运行时可用,宿主
sendToGhost接受派发。 - 使用已有 callId 记录一次;后续更新结果不增加次数。
派发后失败、超时或取消仍属于一次调用,结果单独记录。权限拒绝、未安装、未启用、 启动失败和派发失败不计。调用重试若产生新 callId,是新的一次调用;网络补发同一回执 不增加次数。调试入口不进入正式个人或共享统计。
打开面板、查看说明、执行 Skill、卡片操作和订阅事件不自动算工具调用。插件内部 一次工具调用触发多个业务操作,仍计一次;例如通用工具内部选择不同子命令, 不在宿主侧解析参数拆分计数。
3.2 时间与准确性
- 记录 UTC 时间;查询使用明确的半开区间
[from, to)。 - 建议默认近 7 日统一采用最近 168 小时。若以后提供自然日筛选,明确其时区并单独命名。
- 累计指本机保存的记录累计;新启用或清除过历史时显示记录起点。
- 宿主派发与 SQLite 写入不具备跨系统原子性。统计不阻塞插件执行,强退或磁盘故障 可能留下缺口;不宣称完整审计或计费级准确。
- 正常退出、账号切换应有限等待已接受写入;不得把完成调用写进后来登录账号的数据库。
- 结果回调与异步插入必须按 callId 有序处理;未收到确定结果的记录保持“未知”, 不能把崩溃或断开自动记成成功。
4. 个人数据模型
在现有账号独立 SQLite 中增加两张表。以下为逻辑字段,实际名称与 migration 在实现时 遵循仓库约定;不修改任何已合入历史 migration。
4.1 插件历史身份
| 字段 | 用途 |
|---|---|
| id | 宿主生成的历史身份 ID,供调用记录关联 |
| sourceKind | server / git-market / local-market / manual 等已核验来源 |
| pluginId、organizationId | 已核实的市场身份;非市场来源可为空 |
| sourceKey | 自定义来源的现有规范化指纹,仅本地保存 |
| ghostId | 插件运行时标识,不单独承担全局身份含义 |
| displayName | 最后已知名称;卸载或市场失联仍可展示 |
| recordingStartedAt | 开始记录时间;全部清除该身份明细后重置 |
| bindingRevision | 记录最后核验的 Host receipt revision,作为连续安装关联证据;不是插件身份 |
| historyGeneration | 清除记录时递增,拒绝旧采集句柄晚到的写入 |
当前是否安装、启用或失效由现有安装投影提供,不再建立一套独立安装状态机。 历史身份行不参与授权,不代替 Host receipt、安装账本或 manifest 校验。
4.2 调用记录
| 字段 | 用途 |
|---|---|
| callId | 唯一键,复用宿主调用 ID |
| subjectId | 关联历史身份;不能与安装记录级联删除 |
| occurredAt | 成功派发时的 UTC 时间 |
| toolName | 当时调用的顶层工具名 |
| sessionId | 宿主提供的 Cindy 业务任务 ID,可为空;用于查询最近参与任务,不建立级联删除外键 |
| version、releaseId | 当时的版本快照;未知保持为空,不猜测 |
| outcome | 成功 / 失败 / 超时 / 取消 / 未知;仅依据宿主结果更新 |
| reportTarget | 当时核验的服务根/区域、认证方式、插件、版本、范围和企业身份快照;无需上报则为空 |
| reportState | 不适用 / 待发送 / 已确认 / 已停止 |
| nextAttemptAt、attemptCount | 有界重试调度信息,不保存原始服务端错误正文 |
reportTarget 必须是独立于当前安装记录的不可变快照,禁止补发时根据新装插件重新归属。 调用内容不出现在这里:不保存参数、返回正文、密钥、附件或消息正文。 第一版保存可空 sessionId,但不绑定任务外键;删除任务不触发调用历史级联删除。 任务标题按读取时的现有任务数据解析,不额外保存标题或消息快照。
索引按实际查询建立,优先覆盖 (subjectId, occurredAt)、时间筛选与待发送记录。
个人 7 日、指定时段及累计数字直接查询明细;暂不加日汇总表或累计计数器。
确有性能证据后再增加可重建的汇总,不提前维护多个事实来源。
默认不按 7 天或 90 天自动清理明细。提供用户清除入口;容量优化不静默缩短承诺。 记录和索引占用应在实现验收中测量,未来保留策略另行决定。
5. 身份延续与生命周期
市场来源复用安装账本及已安装清单匹配逻辑。市场名称可复用,ghostId 也可能被本地包 占用;任何自动合并历史都需要对应来源证据。
| 事件 | 个人数据处理 |
|---|---|
| 首次启用记录 | 为当前已核实身份建立记录起点;不从卡片、日志或最近使用列表补造明细 |
| 正常升级、降级、回滚 | 同一历史身份;新调用使用新版本,旧记录保持原版本 |
| 升级失败或回滚安装事务 | 不提前切换历史归属;原记录保持不变 |
| 停用、授权过期、熔断、包损坏或批准状态失效 | 保留历史;新的未派发请求不计数 |
| 用户卸载 | 保留历史身份和明细;记录页可查看已卸载插件 |
| 重装同一服务端市场插件 | 核验稳定市场身份后接回历史,不仅匹配 ghostId |
| 重装自定义市场插件 | sourceKey 与 ghostId 均匹配,且安装来源有效,才接回历史 |
| 手工本地插件正常原位升级 | 在同一连续安装身份下保留历史,不因版本或包哈希变化自动拆分 |
| 手工本地插件卸载后重装 | 无可靠同源证据时新建历史身份;旧记录仍可查看 |
| 明确换来源或同名异源替换 | 新建或匹配目标来源身份,不把原来源记录迁给新来源 |
| 安装来源证据不足或账本与包不匹配 | 不认领公共或企业身份,不事后将不确定记录补传为该市场插件用量 |
| 市场断网、列表缺项或来源暂不可用 | 不推断卸载,不删除历史,不擅自重新归属 |
| 企业普通下架 / 当前 purge | 沿用卸载行为,个人历史保留;后续共享发送遵守当前权限 |
| 切号或退出登录 | 数据留在原账号范围,停止借用当前账号发送旧账号事件 |
| 用户明确清除某插件或全部调用记录 | 删除相应明细及待发状态,保留仍需使用的身份映射并更新记录起点 |
| 明确清理本机账号数据 | 将两张表纳入该账号的清理范围,不保留旁路副本 |
“服务端账号注销”与“本机账号数据删除”不是同义词。实现时必须核对账号删除的实际 清理链路,不能仅凭本地退出登录回调就宣称本机明细已删除。
普通卸载不取消已经发生且仍符合上报条件的调用。用户清除记录则停止未发送事件; 清除须与发送选取、晚到结果回调协调,防止删除后重新插入。已发出的请求可能已被服务端 接收,本地清除不承诺撤回共享累计,也不为此引入反向扣减协议。
企业若未来需要“撤回企业数据”,应明确数据范围与清除指令,再同时清理历史身份快照、 明细和待发记录。当前方案不把此语义附加到普通 purge,也不宣称已满足企业数据撤回。
6. 复用安装回执机制
复用 #2337 的适用设计和实现片段,移植时对照新主干复核,不整包恢复旧分支:
| 可复用 | 本方案的应用 |
|---|---|
| 本地事实成立后产生回执 | 成功派发后记录,而非打开页面或模型计划调用时记录 |
| 稳定 eventId 与幂等接收 | 使用 callId;超时重发同一回执,不生成新 ID |
| owner 绑定和发送前复核 | 补发不能使用新账号凭证;匿名记录不能自动归给后来登录的人 |
| 有限重试、批量补发 | 固定一批候选、后台发送、退避,离线不忙循环 |
| 禁止认证副作用和接口超时 | 主干已有 skipAutoRefresh、skipSessionInvalidation;直接复用,不恢复旧 PR 的 suppressAuthSideEffects 改动 |
| 永久拒绝与暂时失败分开 | 暂时失败保留;明确永久拒绝停止上报但保留个人明细 |
不照搬旧回执的“一事件一个 JSON 文件”及低容量丢弃策略。调用高频且已有明细库, 写入明细时在同一行初始化 reportState,就完成待发登记,避免双写和额外队列。 安装事件保留原有含义;升级不因此变成新安装。暂不抽象通用遥测框架。
共享发送流程:
- 从原账号数据库选择到期的待发记录,固定其目标快照与 callId。
- 使用现有服务端客户端封装,发送最小回执批次。
- 服务端验证身份、插件与版本关系、权限,并按事件 ID 幂等接收。
- 客户端只将逐项确认成功或已存在的记录标为已确认;部分成功、断网、响应丢失可重试。
- 401/403 不能一概永久丢弃:区分临时认证状态与明确权限撤销,依服务端契约处理。
服务端批量协议和去重方案见第 12 节。它们是拟新增协议,不假定 #2337 的安装接口已经 部署;需在服务端实现与契约测试中确认,不在本客户端文档中生成服务端 migration。 事件去重信息的保留期必须覆盖客户端允许的补发期。
上传仅需事件 ID、市场插件/版本身份和必要时间。工具名、个人来源路径、名称快照和 调用结果明细留在本地。统计回执不是完整个人历史云备份。
7. 共享范围与展示
| 插件来源 | 个人记录 | 共享统计 |
|---|---|---|
| 服务端公开市场插件,包括官方及其他公开发布者 | 保存 | 可向有权查看该插件的公众展示汇总 |
| 服务端企业插件 | 保存 | 受现有插件 visibilityAudience 等权限约束,不自动向全企业开放 |
| 服务端 personal scope | 若实际启用则保存 | 第一版不扩展共享口径 |
| Git / 本地目录自定义市场 | 保存 | 默认不上报公共市场 |
| 手工本地插件 | 保存 | 仅个人记录 |
7.1 用户提出的产品方向(2026-10-12)
详情页按当前真实安装状态分两块:
| 状态 | 展示重点 | 位置 |
|---|---|---|
| 未安装 | 共享安装次数、共享工具调用次数 | 头部副标题,在版本后追加紧凑的 icon + 文本 + 数字;提供口径说明 |
| 已安装 | 本地个人记录:最近使用时间、近 7 天次数、最近三个参与任务;Token 预估视可行性加入 | 在头部之后增加个人数据 card,现有配置与功能区域沿用 |
“参与会话”按 Cindy 现有术语在界面称为“参与任务”,对应业务 session。 数字、图标与排版使用既有语义 token 和已安装的图标库,兼容 Light/Dark 与窄宽度, 不为本功能新增图表或图标依赖。下面是信息顺序示意,不是已验收视觉稿:
未安装 · 头部副标题
版本 · [图标] 安装次数 N · [图标] 工具调用 M
(口径说明按需查看)
已安装 · 个人数据卡片
最近使用 近 7 天调用
相对时间 N 次
参与任务
任务 A 最近调用时间
任务 B 最近调用时间
任务 C 最近调用时间
推荐用一张紧凑卡片,上部并列最近使用与 7 日次数,下部为三条任务记录;窄屏自然换行, 不拆成四张大卡。Token 项首版暂缓的理由见 7.4。已安装页面如果保留共享头部指标, 仍必须使用共享口径,不能在安装后悄悄将同一数字替换为个人数据。
7.2 共享头部的数字与说明
- 安装次数按已接收的成功安装回执累计,不是当前安装人数或独立用户数;正常升级不 增加,卸载后重新成功安装可增加。本地卸载不会反向扣减累计安装次数。
- 工具调用次数按本方案定义的派发口径累计,不代表所有面板、Skill 或业务操作。
- 企业插件数字只对当前有权查看插件的人展示。手工本地和自定义来源没有共享数据时, 不展示伪造的公共数字。
- 服务端未支持、暂时加载失败与真实 0 必须可区分;数据说明提供范围、记录起点和 统计时间。大数可以缩写,但说明中能查看精确数字。
- 当前服务端只有下载请求统计;落地“安装次数”还必须接通 #2337 的客户端成功安装 回执及服务端幂等接收/查询。不能将 PluginDownload 改名后当作安装次数交付。
7.3 个人卡片的数据合同
| 内容 | 计算与行为 |
|---|---|
| 最近使用时间 | 当前历史身份全部保留调用的 MAX(occurredAt),按成功派发口径;打开面板不更新 |
| 近 7 天调用 | 同一身份 [until - 168h, until) 的 COUNT;与后台查询共用口径 |
| 最近三个参与任务 | 以调用记录关联的 sessionId 去重,按该插件在任务内最后一次调用时间降序排列,最多三条 |
| 点击任务 | 使用现有打开任务入口,进入原任务;不创建新任务,不跳向 SDK 原生线程 |
sessionId 已由 mcp-integrations/ghost.ts 从可信宿主上下文传给 dispatcher,直接保存这个
业务 ID,不接受插件参数中自报的任务 ID。缺少 sessionId 的调用仍计数,只是不进入任务
列表。不新增关系表或扫描历史 transcript 来补造关联。
查询先限定当前 owner、目标插件历史身份及当前可访问/未删除的任务,再取每个任务的
MAX(occurredAt) 并排序取三条;不能先截取三条调用再去重,也不能按任务整体 updatedAt
排序。标题使用现有任务标题;归档任务沿用现有可访问/打开规则。删除任务后不再列出,
调用次数和最近使用时间仍保留,避免普通任务清理使个人统计倒退。
按查询计划需要增加 (subjectId, sessionId, occurredAt) 普通索引即可。
无调用时最近使用为空、7 日次数为真实 0;少于三个任务按实际数量展示,关联不可用时不 填造标题。不以安装时间冒充最近使用。已卸载历史仍在记录查询中保留;重新安装按第 5 节 身份规则接续。未安装状态的详情页不因此展示个人 card。
个人统计明确来自哪台执行设备及哪段记录。手机经 device-link 使用桌面插件时,仅在 实际执行宿主记录,控制端不重复计数。任务链接也必须指向该执行设备对应的原任务。
7.4 Token 预估的可行性结论
本次检查的 sessions.totalTokenUsage、daily_model_usage 与 daily_session_usage
记录任务、轮次或模型用量;Ghost 派发/结果协议没有可直接归属到单次插件调用的模型
token 字段。同一轮可调用多个插件,也包含系统提示、历史上下文、推理与其他工具内容。
插件内部自行调用模型的用量还可能完全不经过 Cindy 的 Agent 计量链路。
因此首版建议不展示 Token 项,也不显示没有来源的 0 或占位估值。不能采用以下捷径: 把参与任务全部 token 相加、按调用次数平均分摊,或把参数/结果字符数除以常数。 这些数字都不能合理表示“该插件的 Token 消耗”。
未来若有可验证的调用级用量归属,再明确估算覆盖面与方法后加入;不为可选展示新增 tokenizer、依赖、调用正文落盘或另一套计量系统。此项是工程建议,用户尚未最终裁决。
8. 实施顺序与验收
第一阶段:个人记录
实现两张表、集中派发记录、结果更新、来源映射、保留及清除行为,并提供最小查询能力。 不改 manifest、批准凭据、插件包格式或插件作者接口。
第二阶段:共享回执
复用安装回执发送约束,补齐服务端幂等批量接口与权限过滤,再接入共享数字展示。 未安装详情页要求的安装次数也在本阶段接通成功安装回执的接收、持久化与查询;调用事件 不能替代安装事件,安装回执仍保持其独立低频生命周期,使用现有 PostgreSQL 普通表。 服务端变更在独立仓库实施。共享回执的启用策略、告知方式及历史补发起点须在启用前 确认;第一阶段不能默认授权未来上传全部个人历史。
核心验收场景
- 同一 callId 重复通知、补发或确认丢失只计一次;业务重试的新 callId 分别计数。
- 成功派发后失败仍记一次;权限拒绝、启动失败和调试调用不进入正式统计。
- 升级前后累计连续,版本可区分;失败升级不改变历史归属。
- 卸载后能查历史;市场重装正确接回;同名换源不串账。
- 自定义来源内部 public scope 不导致公共上报。
- 写入及发送中切号,所有数据仍归原账号;不会借用新 token。
- 清除记录与结果回调、发送并发时,不重新生成已删除明细或重新排队。
- 企业可见性撤销后不继续泄露统计;普通下架与明确数据撤回语义分开。
- 时间边界、跨时区、记录起点与无数据状态展示正确。
- 断网、批次部分成功、响应丢失、磁盘写入失败和强退行为有针对性验证。
- 在代表性调用量下测量数据库体积、查询时延与后台写入开销,再决定是否需要汇总缓存。
- 已安装 card 的任务列表去重后最多三条,按该插件最近调用排序;删除、改名、归档及 缺失关联正确处理;任务删除不影响调用统计,sessionId/任务标题不上报共享接口。
- 未安装头部安装次数只来自成功安装回执;未知、无权限、暂不可用和真实 0 不混淆。
上述工程问题的推荐实现与限制见第 10—13 节。源码调研不替代实现验证;其中列明的 并发、故障及兼容场景在开发阶段需要真实测试,不能以文档自查代替。
9. 代码依据与相关规则
固定调研版本的客户端依据:
服务端证据路径(上述固定版本):plugin-server/prisma/schema.prisma、
plugin-server/src/services/downloadStatistics.ts、plugin-server/src/routes/clientPlugins.ts、
plugin-server/src/services/plugins.ts。未进行生产接口或生产数据库验收。
实施遵循现行 核心产品原则、 数据库与 migration、 多账号数据库边界、 插件安全与兼容及 本地存储规则。
10. 工程架构收口:使用现成的数据库与调用边界
| 层 | 已有实现 | 本次最小增量 |
|---|---|---|
| 客户端持久化 | Drizzle + better-sqlite3,账号独立 DB,异步 DbClient/SQL worker | 两张普通表、索引和命名事务;不新建 DB 文件,不引入 ORM 或驱动 |
| 本地调用采集 | GhostPipeDispatcher.dispatchCall / settle,现有 callId | 宿主内部接受/结果观察回调;不修改插件 wire、manifest 或权限契约 |
| 账号绑定 | getCurrentDbClientSnapshot 的 client/userId/clientEpoch,加 ActiveAppSession generation | 一个数据库代际对应一个统计 service,闭包绑定该 DB;晚到回调不重新 getDbClient |
| 写入顺序 | pluginTaskService 的 Promise tail、drain 范式 | 统计 service 使用同类短串行队列;不把统计塞入插件任务服务,也不抽通用消息系统 |
| 客户端请求 | PluginMarketApi → serverApiFetch → Electron net.fetch | 增加插件调用回执方法,复用超时、错误码白名单和日志脱敏 |
| 服务端入口 | plugin-server 的 Express Router、普通客户端鉴权、现有 Redis 限流 | 在同一服务增加回执路由,不新增采集服务、MQ 或 Redis 用量计数器 |
| 服务端存储 | plugin-server 自己的 Prisma/PostgreSQL 与 PluginDownload 明细模式 | 调用量新增 PluginUsageEvent 普通表;头部安装量另接成功安装回执存储;均使用唯一约束去重和批量查询 |
| 跨端协议 | 两仓各自维护 packages/plugin-protocol | 只增加本功能 DTO/parser/测试,不引入新协议包或共享仓 |
已有 Redis 只复用限流能力,不承担事实存储或可靠队列。无需新增 ClickHouse、时序库、 向量库、SQLite 扩展或新的基础设施环境变量。个人历史默认留在现有账号 DB;不借机 迁移到多账号架构文档规划中的未来目录,也不批量给业务表增加 owner_id。
10.1 身份关联落点
- 服务端市场身份使用“服务根/区域 + pluginId”,通过现有安装账本与清单匹配判据核验。 服务端 pluginId 是资源身份,releaseId 和包哈希仅用于版本归属,不能成为历史主键。
- 自定义市场使用已有 sourceKey + ghostId,不使用可复用的市场显示名。来源 URL/路径 只留本地;这类记录不进入平台上报。
- 手工本地插件使用宿主生成的连续安装身份。首次观察生成 ID,重启从历史身份表恢复。 当前 Host receipt revision 只用于判断绑定是否仍有效,不直接作为历史 ID。
updateLocalGhostPackageLocked已明确区分原位更新与解绑市场来源;原市场包改成本地包 视为换源。对原本就是手工本地的同 ID 原位更新,按现有更新语义延续历史,不推断作者 是否相同,不新增作者验证或额外确认。installAndDockLocked、市场afterCommitInLock、自定义安装写账本点及卸载路径提供 成功事实。在现有 owner lease / ghostId 锁内捕获旧身份、新来源和提交结果,更新统计 绑定;不新建包事务,不在包提交前覆盖绑定,不因统计写入失败回滚已成功安装。- 不认识的 receipt 变化、升级期间统计绑定写入失败或外部替换,无法证明连续性时保留 旧历史并建立新的本地身份;不凭同名恢复市场来源。正常已观察到的升级走连续关联。 这是异常恢复边界,不承诺在未记录的安装变动后还原完整安装谱系。
历史身份表仅保存关联信息,不维护另一套 installed/enabled/status。安装失败且旧包恢复, 旧绑定继续生效;已提交包后的通知失败则以现有安装事务恢复事实为准。 新建、更新与来源不明时的关联需有定向用例,不能借统计功能要求存量插件重装、重批权限。
10.2 采集时机与 SQL 操作
- 在实际派发前冻结宿主已核验的来源、版本、账号、服务根及统计句柄;成功 sendToGhost 后立即登记采集操作,不等待工具执行结束才读取可能已变更的安装账本。
- 接受调用的命名事务原子地定位/建立历史身份、验证 historyGeneration、插入事件, callId 唯一冲突执行不重复插入。首次插入同时设置上报状态。
- settle 只更新已存在事件的结果,不使用 UPSERT。分类取宿主收口原因,不解析插件返回 的错误文案来猜测取消或超时;没有可靠原因时保留未知。
- 通过同一 service 的顺序队列保证接受写入早于结果更新,捕获观察回调异常,不改变插件 返回值。数据库故障不转为工具失败,不在异常分支补造成功记录。
- 开始采集前先完成当前已装插件的身份行与代际初始化;来源变更后重新取得有效句柄。 初始化未就绪的调用不进入可跨清除边界重放的缓存。接受事务不得遇到旧代际拒绝后 自动创建新身份重试;这会绕过用户清除。
- 复用 DbClient.tx 运行 worker 内短事务。file worker、现有 inline fallback 和 inproc 路径须保持一致;优先沿用现有 taskTagsTx 类共享纯事务 helper 的接线方式。
- 后台发送选取与统计查询使用现有 runAsBackgroundDbRpc,避免抢占交互 DB 配额。 队列只存短数据库操作,不把网络请求或等待插件结果放进串行临界区。
11. 清除、切号与退出的具体处理
11.1 清除不使晚到记录复活
清除保留历史身份行,只在一个 SQLite 事务中递增目标 historyGeneration、删除目标事件、 重置记录起点。采集句柄携带派发时的代际,旧句柄的插入不得跨代重试;结果回调只 UPDATE, 影响 0 行即结束。失败重试不得自动取得新代际重建旧记录。
当前主进程内,接受写入、结果更新、绑定修改和清除复用该账号 service 的短串行队列。 清除入口先暂停目标身份的新统计入队,排空此前已接受的短操作,再提交清除事务并更新 内存句柄;插件执行继续,极短边界中的未采集调用不能事后补回。 如果存在共享 DB 的另一实例,代际条件必须在 SQL 内检查;陈旧实例被拒后刷新绑定, 只给后续调用使用新代际。不能仅凭架构文档假定已经有单活 writer。
sender 从 DB 取出候选后,在真正调用 HTTP 前通过同一 service 再核验记录仍存在、 代际仍匹配且 owner 当前有效,并立即发起请求,不留下额外异步间隙。 不持有数据库事务等待网络。已发出的请求无法保证撤回:服务端确认晚到时只更新仍存在的 事件,不恢复已清除行。清除个人历史不引入平台累计反向扣减。 跨实例已发送或已取出即将发送的请求属于同一不可撤回边界,不能承诺原子取消网络。
11.2 账号和 DB 生命周期
源码已有 flushPluginTaskLifecycle 在切号和退出前排空,再调用
lifecycleDbClientManager.dispose。统计沿用这个明确顺序,在相同的 DB 关闭入口附近
增加统计 drain;不另造全局生命周期框架,不等待后台 HTTP 才允许退出。
统计 service 停止新采集和发送,有限等待本代际已接受的短数据库写入,然后释放其引用。
收口前必须阻止新回调入队;关闭后的结果保持未知,不能回退为新账号写入。
WorkerThreadTransport.close() 有 backlog 时会拒绝遗留操作并 terminate,不能把
close 当作自动排空。等待预算沿用账号/退出编排的现有上限;超时记录非敏感诊断,
不绕开生命周期另开数据库连接重试。inproc fallback 每次操作也须检查原快照仍有效,
因为它内部访问的是当前主进程 DB,单纯保存 DbClient 引用不足以保证账号隔离。
11.3 注销与保留
已核实 clearLocalSessionAfterAccountDeletion 删除已保存账号凭据并进入
withAccountFreeOwnerCommit;相应 teardown 关闭 DB,并对部分模块做专属清理,
未发现该链路统一删除整个账号 SQLite 文件。因此本功能不声称注销即物理擦除历史,
也不借此需求改造整个账号删除系统。
本期保持现有账号数据生命周期,提供本功能的显式清除事务;若后续产品要求注销时清除 调用历史,可在既有 account-deletion 边界、DB dispose 前调用同一清除能力,单独验证。 退出登录和普通切号不执行清除。企业 purge 继续按普通卸载保留个人记录;额外数据撤回 属于单独的产品政策,不由计数模块自行扩大。
12. 服务端回执与兼容方案
12.1 数据与接收
建议在现有 plugin-server 中新增 POST /api/plugins/:pluginId/usage-events,每批只含
一个插件,减少权限查询与错误隔离复杂度。路径与以下字段均是待实施的建议契约:
{
"events": [
{ "eventId": "<callId UUID>", "releaseId": "<release ID>", "occurredAt": "<UTC ISO timestamp>" }
]
}
服务端使用已有 Express、参数解析和错误体 { error: { code, message } }。
复用 IP/身份限流构造器,以独立业务 key 计数;JSON parser 放在限流及鉴权之后,
限定 body 大小与批次长度。建议从每批最多 100 条、请求超时 5 秒起步,经定向测试调整;
这些是代码常量,不新增配置面或环境变量。
新增一张 PluginUsageEvent,保存 eventId、pluginId、releaseId、occurredAt、receivedAt。
eventId 唯一,复用 PluginDownload 的 (pluginId, releaseId) 组合外键约束和 Restrict
删除语义,避免将某插件的 release 记到另一插件。不存用户身份、工具名或调用内容。
在现有 Prisma 事务中幂等插入;同 eventId 同事实返回 duplicate,不覆盖原行;同 ID
不同内容返回 conflict。确认必须在 DB 提交后返回,数据库失败返回可重试错误。
不能照搬下载统计吞写入错误后继续成功的做法,否则客户端会错误确认已上报。
响应按 eventId 返回 accepted / duplicate / rejected(附明确原因)。结构不合法整批 拒绝,合法批次内可逐项拒绝;客户端只确认实际返回且与请求匹配的项,缺项保持待发。 事件去重依赖 PostgreSQL 唯一约束,不另建 Redis 去重表或累计计数器。
12.2 权限和历史版本
- 路由属于普通客户端能力面,复用 optionalAuth 与 requireOrgCapabilityUse;不混用 Platform token 或插件 OAuth broker token。公开插件沿用可匿名访问边界,企业插件 必须有当前有效企业身份,并复用现有 visibilityAudience/部门解析判断。
- 回执目标的 scope、organizationId 由服务端插件事实决定,不信任客户端自报。
- 从
plugins.ts提取最小可复用权限 helper。不能复用下载签名函数:它还要求 releaseId 等于当前兼容版本,会错误拒绝正常升级前产生的离线记录。 - 版本必须属于目标插件且有既往发布/上架事实;允许历史版本,不仅限 currentRelease。 已撤销版本的迟到记录仅在其事件时间早于撤销时间时考虑接收。插件当前不可见或企业 权限已撤销时不接收新回执,不借历史身份绕过现行访问控制。
- occurredAt 保留客户端事件时间,receivedAt 由服务端产生;不能将补发时间当作调用 时间。时间格式、既往发布边界及明显未来时间校验是本端协议的一部分。 建议未来时钟容差 5 分钟,超过时拒绝该项;不静默改写时间。客户端自报不提供防造假 保证,平台数字仍是已接收客户端回执的统计。
匿名公共事件也可能被伪造。沿用身份和限流边界即可,不为展示统计新增设备证明、 签名基础设施或反作弊系统;若将来用于结算,必须另做可信计量设计。
12.3 客户端发送与错误处理
- 使用现有
skipAutoRefresh: true、skipSessionInvalidation: true、timeoutMs、 redactErrorDetails 和无身份日志模板,不需要修改 serverApiClient 的通用行为。 - 从已绑定账号取得本次请求的 token 和对应服务根,发送前复核 owner;不落盘 token。 local 模式事件显式 token:null,不能在后来登录后借用新账号身份。跨服务根或区域 的积压不自动转投当前端点,沿用来源边界处理。
- 一个活跃账号使用一个 sender,批次串行;DB 中只保存待发和重试信息。避免为每个 插件、每个事件创建定时器,不建立跨账号后台发送器。
- 网络错误、超时、429、5xx 保留并退避;401 或普通权限/不可见结果暂停本目标,等待 登录或市场状态变化再触发,不把 403/404 一律当作永久删除事件。
- 只有明确的逐项无效事件、不可接受版本或 eventId 内容冲突标为已停止;个人明细保留。 旧服务端通用 NOT_FOUND/不支持接口只暂停上报,不能批量销毁历史待发记录。
- 应用启动且 DB/账号就绪、合法新事件以及既有市场同步可触发检查;重试使用一条有界 后台调度链。上线前未启用上报的个人记录维持“不适用”,不得自动全量回填。
12.4 查询和发布顺序
沿用 downloadStatistics 的明细查询方式,按一页已授权 pluginIds 批量 groupBy,返回
累计和 [until - 168h, until) 次数。按事件时间查询,保留历史 release 的计数;不逐插件
发查询,不先加缓存或定时汇总。对大数据量先做查询计划/索引验收再决定优化。
服务端事件表暂不自动过期,避免客户端长期补发遇到去重凭证已删除而重复计数。
统计可作为现有列表/详情的可选字段,计数沿用字符串表示,附统计时间。老服务端不返回
该字段时,新端解释为“不支持”,不是 0;老端忽略新增字段。不为可选字段提升现有
PLUGIN_API_SCHEMA_VERSION = 2,否则当前严格版本 parser 会拒绝整个市场响应。
列表必须先完成现有权限过滤,再取对应统计。部门权限解析保持现有服务端路径,不复制
一套只校验 organizationId 的简化权限。
两仓本地维护协议与相同 fixtures:服务端先发布普通 Prisma 增量迁移和新增接口,再上线 能识别可选统计与上报能力的客户端。新客户端对旧服务端暂停发送,个人记录继续工作; 客户端回退仍可使用原插件,新增表和列不改变旧插件批准状态。发布与生产数据规模的 验证按服务端既有部署规则完成;本次只有源码调研,没有生产演练。
13. 开发交付边界与剩余验证
工程采用上述现有组件即可推进个人记录实现;无需等待页面设计,也无需新增依赖。 建议先提交个人存储/采集与生命周期的实现和定向测试,再提交共享回执;客户端查询入口 随产品呈现需要接入现有 IPC/device-link,不预先扩展全套 UI 或远程订阅能力。
| 开发时必须验证 | 已有测试入口/参考 |
|---|---|
| 两表 migration、唯一约束、清除事务、历史代际拒绝 | migration replay、DbClient worker/inproc 测试 |
| 派发成功/失败、结果过快、重复 callId、取消/超时与未知结果 | pipeDispatcher 测试;内部观察回调不改变原工具结果 |
| 本地连续更新、市场转本地、同名异源、失败安装恢复、崩溃恢复 | plugin-market service 与安装/卸载现有测试 |
| 队列写入、清除和发送交错;多实例陈旧句柄 | 临时 SQLite 数据库及独立连接;不使用用户真实库 |
| 切号、worker backlog 关闭、inproc fallback 旧句柄 | lifecycleDbClient、account boundary、WorkerThreadTransport 测试 |
| 服务端去重、同 ID 冲突、版本归属、部分拒绝、权限收回 | plugin-server 路由/统计单测及安全环境 PostgreSQL 集成测试 |
| 新旧两端组合、未知字段、未支持接口、旧版本离线补发 | 两仓 protocol fixtures 与 API adapter 测试 |
第 7 节已经记录用户给定的头部指标与个人卡片方向。尚待确认的是具体视觉/交互细节、 可选 Token 项、共享上报的启用/告知及历史补发范围,以及是否额外改变账号注销或企业 数据撤回政策。它们不要求重新选择技术栈;个人记录后端可以先行。 插件运行时相关 PR 仍遵守现有基座白名单 Approve 门槛,数据库变更遵守现有迁移验收。
本次补查的客户端入口还包括:localDb/client/{DbClient,current,lifecycleDbClient, WorkerThreadTransport,rpcAdmission}.ts、maker-ipc/pluginTaskService.ts、
maker-ipc/register.ts、bootstrap-electron.ts、authManager.ts、serverApiClient.ts、
cindy-brain/mobilePluginUsage.ts 和 packages/plugin-protocol/src/delivery.ts。
其中 mobilePluginUsage 是配置/可用性投影,不是调用明细或次数来源。
产品方向补查还覆盖 renderer/features/plugin/{MarketPluginDetailView,GhostPluginDetailView}.tsx、
mcp-integrations/ghost.ts 的 callSessionContext,以及 localDb/schema.ts 中的 sessions、
daily_model_usage 和 daily_session_usage。当前头部副标题已有版本信息,可在现有位置
追加共享指标;最近任务直接使用已传递的 sessionId,无需第三张客户端关系表。
服务端补查了 plugin-server/package.json、src/lib/prisma.ts、src/auth.ts、
src/middleware/{orgAuth,rateLimit}.ts、src/app.ts 与下载统计测试。
本次研究验证记录
2026-10-12 使用系统 Python sqlite3,在任务专属临时数据库中以两个独立连接验证了 最小两表模型:重复 callId 不重复插入/覆盖版本、升级事件保留不同版本、不同插件独立、 清除后的结果 UPDATE 不恢复行、陈旧代际 INSERT 被拒、更新代际后的新调用可写入、 晚到上报确认不恢复已删除事件,以及定向清除不影响其他插件。检查全部通过,临时文件 已清理,未访问用户数据库。
该实验只验证所建议 SQL 的基本约束与先后顺序,不等于真实线程竞争、Cindy worker、 完整安装生命周期或 PostgreSQL 集成验收。未安装依赖、未修改运行时代码和服务端源码, 未执行生产请求或性能基准。文档的相对链接、代码围栏、冲突标记及空白检查通过。