Skip to content

feat(zcode-usage-panel): add live usage panel UI plugin - #93

Open
taohouchao-new wants to merge 1 commit into
zai-org:mainfrom
taohouchao-new:feat/zcode-usage-panel
Open

taohouchao-new wants to merge 1 commit into
zai-org:mainfrom
taohouchao-new:feat/zcode-usage-panel

Conversation

@taohouchao-new

Copy link
Copy Markdown

Plugin type / 插件类型(必填)

  • UI Plugin / 是 UI 插件 — provides MCP Apps interactive pages / 提供 MCP Apps 交互页面
  • Standard plugin / 普通插件(非 UI)
  • Not applicable / 不适用

Affected plugin name(s) / 涉及的插件名称:zcode-usage-panel

声明依据:清单声明 ui.surfaces 会话侧栏面板(ui://zcode-usage-panel/index.html,availability: session),由插件自带 MCP server(stdio)提供资源与订阅。

What / 改动内容

新增社区插件 zcode-usage-panel v0.2.1(external_plugins/zcode-usage-panel/),并在根 marketplace.json 注册(category: developer-tools,componentTypes: ["ui"])。

解决的用户问题:ZCode 会话中缺少实时用量可见性——用户看不到一次任务里 token 花在哪、哪些工具/MCP 被调用多少次、TPS 表现如何、系统提示词的构成规模。

用户可见行为:

  • 会话右侧边栏"+"菜单打开「用量面板」,实时展示:总 tokens(输入/输出/缓存拆分)、模型/工具调用次数、平均与当前 TPS、正在运行的工具
  • TPS sparkline(最近 40 次模型调用,生成段口径)
  • 提示词构成:AGENTS.md 指令、记忆项目、三源技能清单(清单常驻估算 + 全文字符两口径)、MCP 声明与实际调用、子代理定义,JSONL 头部未滚动时展示真实注入记录
  • 可折叠明细:工具(内置/MCP/Skill,次数/耗时占比/输出量/错误数)、模型(model × agent × 来源 token 细分)、最近轮次
  • 子代理调用并入会话统计;支持固定最近 20 个会话之一
  • resources/subscribe 推送约 1s,无订阅能力回退 2s 轮询

测试方式(本地已验证):

  • npm run typecheck(tsc 严格模式)通过
  • npm run build 产物输出 payload/dist/(server.mjs 825KB + index.html 610KB,低于宿主 4MiB 上限)
  • NODE_BIN=$(which node) npm run smoke:系统 Node v26 对发布产物跑完整 MCP JSON-RPC 链路(initialize → resources/list/read → subscribe → 确定性 DB 变更通知 → unsubscribe → 子会话统计),全部通过
  • python3 scripts/validate.py:44 plugins OK
  • 单插件 zip 打包验证(调用 build_dist.py 的 build_zip,含 validate_local_mcp_paths):17 个文件,MCP 路径齐全。说明:全量 build_dist.py 本地未跑完——官方 blender 等 UI 插件的 dist 需要 CI 环境构建(pnpm build),与本次提交无关
  • ZCode Desktop 0.16.x 中以本地市场方式实机运行数周(每日使用),功能与降级路径(db schema 不匹配时显示错误而非白屏)均验证过

版本与注册:新插件首发 0.2.1,plugin.json 与 marketplace.json 的 name/version/description/description_i18n 逐字一致。

依赖/权限/副作用:

  • MCP server 以 command: "node" 启动,要求 Node.js ≥ 24(内置 node:sqlite);运行时零 npm 依赖(产物为自包含 bundle)
  • 只读访问 ~/.zcode/cli/db/db.sqlite(mode=ro),不写任何文件、无网络访问、无 Hook、无命令执行
  • 已知边界:db.sqlite 为 ZCode 内部 schema(0.16.x 验证),宿主升级后查询可能失效,面板显示降级错误

第三方材料与许可证:插件代码 MIT(LICENSE 随附);构建期依赖 esbuild/TypeScript/@modelcontextprotocol SDK(MIT/Apache-2.0),不进入安装产物;无第三方素材或服务。

Self-check / 自查清单

  • Plugin name is unique kebab-case; new external plugin directory is external_plugins/<name>/
  • Usage category is set independently of publisher ownership
  • Plugin type and affected names are declared above
  • version bumped in BOTH plugin.json and marketplace.json (new plugin, first release 0.2.1)
  • README.md (EN) and README_CN.md (中文) both updated and equivalent
  • description_i18n has both en and zh-CN
  • No secrets, machine-specific paths, or private dependencies
  • Model/API/network dependencies documented
  • python3 scripts/validate.py passes locally; plugin zip packaging verified via build_dist.py logic (full run requires CI-built official plugin dists, see note above)

Session-sidebar MCP App showing per-tool/MCP/Skill call stats, token
shares, TPS sparkline and prompt composition in real time. Read-only
access to ~/.zcode/cli/db/db.sqlite; no network, no writes. Bundled
payload under payload/dist, built with esbuild; requires Node.js >= 24.
@panda920

Copy link
Copy Markdown
Collaborator

✅ Internal validation passed. A ZCode maintainer will review the change next; after acceptance, release checks run separately and this PR is closed automatically.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants