Skip to content

feat(turn-lens): add TurnLens session statistics plugin - #205

Open
MorganWsy wants to merge 1 commit into
zai-org:mainfrom
MorganWsy:turn-lens-0.11.0
Open

MorganWsy wants to merge 1 commit into
zai-org:mainfrom
MorganWsy:turn-lens-0.11.0

Conversation

@MorganWsy

Copy link
Copy Markdown

Plugin type (required) / 插件类型(必填)

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

Affected plugin name(s) / 涉及的插件名称:turn-lens

What / 改动内容

Adds TurnLens (turn-lens), a session statistics plugin for ZCode. It reads the local ZCode session database read-only and exposes three ways to inspect usage:

  • On demand — /turn-lens prints a Markdown card with turns, steps, model/tool time, TTFT, TPS, context, cache and request metrics.
  • Optional Stop hook — after each turn, prints a single-turn card. This adds one short model request per turn and can be disabled from the panel.
  • MCP Apps side panel — a live themed panel with session totals, a time-share bar, and a per-turn table. Refresh interval is selectable from 5 / 10 / 30 / 60 seconds; default is 10 seconds. The panel calls the plugin's local MCP server directly and does not consume model tokens.

Notable behavior:

  • Reads ~/.zcode/cli/db/db.sqlite read-only; no network requests, no database writes.
  • Follows the ZCode theme, with light / dark / high-contrast overrides.
  • Handles guided inputs: a guided turn stays one row, gets a 引导 badge, and the user-input estimate includes the guided text.
  • Shows context length/delta, cache hit rate, requests, tool errors and model/tool time per turn.
  • Turn and status columns are configurable; columns can be resized and aligned.
  • Large values use 万 / 亿 with thousands separators.
  • The optional Stop hook is the only feature that adds a model request; it is off-switchable and documented.

Test plan / 测试

  • Installed through the local dev marketplace and opened the side panel.
  • Verified the refresh dropdown: 5 / 10 / 30 / 60 seconds, default 10 seconds, opens upward, persists locally.
  • Verified light, dark and high-contrast themes.
  • Verified guided-input badge and latest-segment model-time tooltip.
  • Verified the single-turn card switch and the no-loop guard.
  • Ran python -I scripts/validate.py: OK: 60 plugin(s) validated.
  • Verified MCP initialize reports turn-lens 0.11.0 and resources/read returns the panel containing the refresh dropdown.

Side effects and privacy / 副作用与隐私

  • Database is opened read-only; ZCode can keep running while the panel reads it.
  • No network access and no uploads.
  • The Stop hook is optional and adds one short model request per turn; disable it at the bottom of the panel.
  • dist/ is generated by the build and is not committed.

Screenshots / 截图

Light

screenshot-light

Dark

screenshot-dark

Refresh dropdown

screenshot-refresh

Self-check / 自查清单

  • Plugin name is unique kebab-case; new external plugin directory is external_plugins/turn-lens/
  • Usage category is set independently of publisher ownership (developer-tools)
  • Plugin type and affected names are declared above
  • version is 0.11.0 in both external_plugins/turn-lens/.zcode-plugin/plugin.json and root marketplace.json
  • README.md (EN) and README_CN.md (中文) are 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 (OK: 60 plugin(s) validated)
  • python3 scripts/build_dist.py was not run end-to-end locally: the full Windows pnpm build currently fails in the upstream Excalidraw build script's path handling. The TurnLens artifact itself packages successfully with build_dist.build_zip; the repository CI runs the full build on Linux.

@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