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。

42.0 KB
Raw Blame

插件调用统计与个人记录保存方案

状态: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 什么算一次

指标为“工具调用次数”。通过宿主检查且成功派发给插件的工具调用计一次:

  1. 通过可见性、启用状态、工具声明、权限和账号检查。
  2. 插件运行时可用,宿主 sendToGhost 接受派发。
  3. 使用已有 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,就完成待发登记,避免双写和额外队列。 安装事件保留原有含义;升级不因此变成新安装。暂不抽象通用遥测框架。

共享发送流程:

  1. 从原账号数据库选择到期的待发记录,固定其目标快照与 callId。
  2. 使用现有服务端客户端封装,发送最小回执批次。
  3. 服务端验证身份、插件与版本关系、权限,并按事件 ID 幂等接收。
  4. 客户端只将逐项确认成功或已存在的记录标为已确认;部分成功、断网、响应丢失可重试。
  5. 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 身份关联落点

  1. 服务端市场身份使用“服务根/区域 + pluginId”,通过现有安装账本与清单匹配判据核验。 服务端 pluginId 是资源身份,releaseId 和包哈希仅用于版本归属,不能成为历史主键。
  2. 自定义市场使用已有 sourceKey + ghostId,不使用可复用的市场显示名。来源 URL/路径 只留本地;这类记录不进入平台上报。
  3. 手工本地插件使用宿主生成的连续安装身份。首次观察生成 ID,重启从历史身份表恢复。 当前 Host receipt revision 只用于判断绑定是否仍有效,不直接作为历史 ID。
  4. updateLocalGhostPackageLocked 已明确区分原位更新与解绑市场来源;原市场包改成本地包 视为换源。对原本就是手工本地的同 ID 原位更新,按现有更新语义延续历史,不推断作者 是否相同,不新增作者验证或额外确认。
  5. installAndDockLocked、市场 afterCommitInLock、自定义安装写账本点及卸载路径提供 成功事实。在现有 owner lease / ghostId 锁内捕获旧身份、新来源和提交结果,更新统计 绑定;不新建包事务,不在包提交前覆盖绑定,不因统计写入失败回滚已成功安装。
  6. 不认识的 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 集成验收。未安装依赖、未修改运行时代码和服务端源码, 未执行生产请求或性能基准。文档的相对链接、代码围栏、冲突标记及空白检查通过。