Skip to content

Commit c4989c5

Browse files
huantest2024huantest2024
committed
docs(session-stats): reword description
1 parent 04b4715 commit c4989c5

4 files changed

Lines changed: 686 additions & 687 deletions

File tree

‎external_plugins/session-stats/.zcode-plugin/plugin.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
"version": "0.2.7",
44
"description": "Session statistics panel for ZCode: turns/steps, model vs tool time, TTFT, TPS, token usage and cache hit rate, read-only from the local session database.",
55
"description_i18n": {
6-
"zh-CN": "会话统计：轮次/步数、模型/工具耗时、TTFT、TPS、token 用量与缓存命中率。只读本地会话数据库（db.sqlite），灵感来自 DeepSeek Harness 的会话统计。",
6+
"zh-CN": "会话统计：轮次/步数、模型/工具耗时、TTFT、TPS、token 用量与缓存命中率。只读本地会话数据库（db.sqlite）。",
77
"en": "Session statistics panel for ZCode: turns/steps, model vs tool time, TTFT, TPS, token usage and cache hit rate, read-only from the local session database."
88
},
99
"author": {

‎external_plugins/session-stats/README.md‎

Lines changed: 66 additions & 67 deletions
Original file line numberDiff line numberDiff line change
@@ -1,67 +1,66 @@
1-
# session-stats
2-
3-
Session statistics for ZCode: turns/steps, model vs tool time, TTFT, TPS (average +
4-
latest request), token usage and cache hit rate — inspired by the DeepSeek Harness
5-
session stats. Zero third-party dependencies.
6-
7-
## Components
8-
9-
- **MCP tool `get_stats`** — statistics for the current session (including subagents,
10-
aggregated via `session.parent_id`) or today's aggregate across sessions.
11-
- **MCP App side panel** (`ui.surfaces`) — stat pills with a details popup
12-
(timings, token buckets, cache hit, per-model breakdown), auto-refresh every 5 s,
13-
follows session switching and the live theme.
14-
- **`/stats` command** — text card rendering of the same numbers.
15-
- **SessionStart hook** — writes the current session id into the plugin data dir so
16-
the server can resolve "current session" without extra round-trips.
17-
18-
## Data source and metric definitions
19-
20-
Everything is read **read-only** from the local session database
21-
`~/.zcode/cli/db/db.sqlite` (SQLite URI `mode=ro`, `busy_timeout=5000`, WAL-safe).
22-
Measured against ZCode 3.17.1:
23-
24-
| Metric | Definition |
25-
| --- | --- |
26-
| Turns | distinct `turn_id` of the main session |
27-
| Steps | distinct `logical_request_id` (retries excluded; failed/cancelled counted) |
28-
| Model time | Σ `duration_ms` |
29-
| Tool time | Σ `tool_usage.duration_ms` |
30-
| TTFT avg | AVG(`time_to_first_token_ms`) |
31-
| TPS | Σ output ÷ Σ(completed_at − first_token_at); "live" TPS = latest completed request |
32-
| Tokens | Σ input + Σ output (`input_tokens` already includes cache reads — measured) |
33-
| Cache hit | cache_read ÷ input |
34-
35-
The database schema is an implementation detail of the host (not a stable API) and
36-
usage rows are retained for 30 days; queries degrade gracefully when columns are
37-
missing.
38-
39-
## Side effects
40-
41-
- Reads the local session database (read-only).
42-
- Starts a loopback-only HTTP service (`127.0.0.1:31710`) that serves the statistics
43-
JSON and the panel's dynamic script to ZCode's renderer. It answers only requests
44-
without a cross-origin `Origin` header (i.e. the app's own `file://` pages); other
45-
origins get 403.
46-
- The SessionStart hook writes one small file (`current_session`) into the
47-
plugin-owned data directory.
48-
- No network access, no credentials, no telemetry.
49-
50-
## Install
51-
52-
ZCode Desktop → **Plugin Marketplace** → add the marketplace that carries this plugin
53-
(the official `zcode-plugins` marketplace after review, or a local directory) →
54-
**Install session-stats** → restart or open a new session → run `/stats` or open the
55-
"Session Stats" side panel.
56-
57-
## Optional composer pills (host patch, experimental)
58-
59-
A stats strip centered under the composer input can be enabled with a patch to the
60-
host `app.asar` (see the upstream project's `patches/` directory). The patch is
61-
idempotent, backs up the host file per version and supports restore; it must be
62-
re-applied after ZCode updates. This is **not** part of the marketplace plugin and
63-
is purely optional.
64-
65-
## License
66-
67-
MIT
1+
# session-stats
2+
3+
Session statistics for ZCode: turns/steps, model vs tool time, TTFT, TPS (average +
4+
latest request), token usage and cache hit rate. Zero third-party dependencies.
5+
6+
## Components
7+
8+
- **MCP tool `get_stats`** — statistics for the current session (including subagents,
9+
aggregated via `session.parent_id`) or today's aggregate across sessions.
10+
- **MCP App side panel** (`ui.surfaces`) — stat pills with a details popup
11+
(timings, token buckets, cache hit, per-model breakdown), auto-refresh every 5 s,
12+
follows session switching and the live theme.
13+
- **`/stats` command** — text card rendering of the same numbers.
14+
- **SessionStart hook** — writes the current session id into the plugin data dir so
15+
the server can resolve "current session" without extra round-trips.
16+
17+
## Data source and metric definitions
18+
19+
Everything is read **read-only** from the local session database
20+
`~/.zcode/cli/db/db.sqlite` (SQLite URI `mode=ro`, `busy_timeout=5000`, WAL-safe).
21+
Measured against ZCode 3.17.1:
22+
23+
| Metric | Definition |
24+
| --- | --- |
25+
| Turns | distinct `turn_id` of the main session |
26+
| Steps | distinct `logical_request_id` (retries excluded; failed/cancelled counted) |
27+
| Model time | Σ `duration_ms` |
28+
| Tool time | Σ `tool_usage.duration_ms` |
29+
| TTFT avg | AVG(`time_to_first_token_ms`) |
30+
| TPS | Σ output ÷ Σ(completed_at − first_token_at); "live" TPS = latest completed request |
31+
| Tokens | Σ input + Σ output (`input_tokens` already includes cache reads — measured) |
32+
| Cache hit | cache_read ÷ input |
33+
34+
The database schema is an implementation detail of the host (not a stable API) and
35+
usage rows are retained for 30 days; queries degrade gracefully when columns are
36+
missing.
37+
38+
## Side effects
39+
40+
- Reads the local session database (read-only).
41+
- Starts a loopback-only HTTP service (`127.0.0.1:31710`) that serves the statistics
42+
JSON and the panel's dynamic script to ZCode's renderer. It answers only requests
43+
without a cross-origin `Origin` header (i.e. the app's own `file://` pages); other
44+
origins get 403.
45+
- The SessionStart hook writes one small file (`current_session`) into the
46+
plugin-owned data directory.
47+
- No network access, no credentials, no telemetry.
48+
49+
## Install
50+
51+
ZCode Desktop → **Plugin Marketplace** → add the marketplace that carries this plugin
52+
(the official `zcode-plugins` marketplace after review, or a local directory) →
53+
**Install session-stats** → restart or open a new session → run `/stats` or open the
54+
"Session Stats" side panel.
55+
56+
## Optional composer pills (host patch, experimental)
57+
58+
A stats strip centered under the composer input can be enabled with a patch to the
59+
host `app.asar` (see the upstream project's `patches/` directory). The patch is
60+
idempotent, backs up the host file per version and supports restore; it must be
61+
re-applied after ZCode updates. This is **not** part of the marketplace plugin and
62+
is purely optional.
63+
64+
## License
65+
66+
MIT

‎external_plugins/session-stats/README_CN.md‎

Lines changed: 51 additions & 51 deletions
Original file line numberDiff line numberDiff line change
@@ -1,51 +1,51 @@
1-
# session-stats — ZCode 会话统计插件
2-
3-
在 ZCode 里复刻 DeepSeek Harness 的「会话统计」：轮次/步数、模型/工具耗时、
4-
TTFT、TPS（会话平均 + 最近请求）、token 用量与缓存命中率。零第三方依赖。
5-
6-
## 组件
7-
8-
- **MCP 工具 `get_stats`**：当前会话（含子代理，经 `session.parent_id` 聚合）
9-
或今日汇总的完整统计。
10-
- **MCP App 侧栏面板**（`ui.surfaces`）：统计卡片 + 明细弹窗（耗时、token 分桶、
11-
缓存命中、模型分布），5 秒轮询自动刷新，跟随会话切换与主题。
12-
- **`/stats` 命令**：同样数字的文字卡片输出。
13-
- **SessionStart hook**：把当前会话 id 写入插件数据目录，供服务端解析「当前会话」。
14-
15-
## 数据源与指标口径
16-
17-
全部**只读**读取本地会话数据库 `~/.zcode/cli/db/db.sqlite`（SQLite URI `mode=ro` +
18-
`busy_timeout=5000`，WAL 下并发安全）。口径对 ZCode 3.17.1 实测定案：
19-
20-
| 指标 | 定义 |
21-
|---|---|
22-
| 轮次 | 主会话 `model_usage.turn_id` 去重数 |
23-
| 步数 | `logical_request_id` 去重数（重试不计步；失败/取消计步） |
24-
| 模型用时 | Σ `duration_ms` |
25-
| 工具用时 | Σ `tool_usage.duration_ms` |
26-
| TTFT 均值 | AVG(`time_to_first_token_ms`) |
27-
| TPS | Σ output ÷ Σ(completed_at − first_token_at)；「实时」= 最近一次完成请求 |
28-
| token | Σ input + Σ output（实测 `input_tokens` 已含缓存读） |
29-
| 缓存命中率 | cache_read ÷ input |
30-
31-
数据库 schema 属宿主实现细节（非稳定 API），usage 行保留 30 天；查询对缺列做了
32-
优雅降级。
33-
34-
## 副作用说明
35-
36-
- 只读读取本地会话数据库。
37-
- 启动仅绑定回环地址的本地服务（`127.0.0.1:31710`），向 ZCode 渲染层提供统计
38-
JSON 与面板动态脚本；只响应无跨域 `Origin` 头的请求（即应用自身 `file://` 页面），
39-
其余 Origin 一律 403。
40-
- SessionStart hook 在插件数据目录写一个小文件（`current_session`）。
41-
- 无网络访问、无凭证、无遥测。
42-
43-
## 安装
44-
45-
ZCode Desktop → **插件市场** → 添加收录本插件的市场（审核通过后为官方
46-
`zcode-plugins` 市场，审核前可用本地目录）→ **安装 session-stats** → 重启或新开会话
47-
→ 输入 `/stats` 或打开「会话统计」侧栏面板。
48-
49-
## 许可
50-
51-
MIT
1+
# session-stats — ZCode 会话统计插件
2+
3+
ZCode 会话统计插件：轮次/步数、模型/工具耗时、
4+
TTFT、TPS（会话平均 + 最近请求）、token 用量与缓存命中率。零第三方依赖。
5+
6+
## 组件
7+
8+
- **MCP 工具 `get_stats`**：当前会话（含子代理，经 `session.parent_id` 聚合）
9+
或今日汇总的完整统计。
10+
- **MCP App 侧栏面板**（`ui.surfaces`）：统计卡片 + 明细弹窗（耗时、token 分桶、
11+
缓存命中、模型分布），5 秒轮询自动刷新，跟随会话切换与主题。
12+
- **`/stats` 命令**：同样数字的文字卡片输出。
13+
- **SessionStart hook**：把当前会话 id 写入插件数据目录，供服务端解析「当前会话」。
14+
15+
## 数据源与指标口径
16+
17+
全部**只读**读取本地会话数据库 `~/.zcode/cli/db/db.sqlite`（SQLite URI `mode=ro` +
18+
`busy_timeout=5000`，WAL 下并发安全）。口径对 ZCode 3.17.1 实测定案：
19+
20+
| 指标 | 定义 |
21+
|---|---|
22+
| 轮次 | 主会话 `model_usage.turn_id` 去重数 |
23+
| 步数 | `logical_request_id` 去重数（重试不计步；失败/取消计步） |
24+
| 模型用时 | Σ `duration_ms` |
25+
| 工具用时 | Σ `tool_usage.duration_ms` |
26+
| TTFT 均值 | AVG(`time_to_first_token_ms`) |
27+
| TPS | Σ output ÷ Σ(completed_at − first_token_at)；「实时」= 最近一次完成请求 |
28+
| token | Σ input + Σ output（实测 `input_tokens` 已含缓存读） |
29+
| 缓存命中率 | cache_read ÷ input |
30+
31+
数据库 schema 属宿主实现细节（非稳定 API），usage 行保留 30 天；查询对缺列做了
32+
优雅降级。
33+
34+
## 副作用说明
35+
36+
- 只读读取本地会话数据库。
37+
- 启动仅绑定回环地址的本地服务（`127.0.0.1:31710`），向 ZCode 渲染层提供统计
38+
JSON 与面板动态脚本；只响应无跨域 `Origin` 头的请求（即应用自身 `file://` 页面），
39+
其余 Origin 一律 403。
40+
- SessionStart hook 在插件数据目录写一个小文件（`current_session`）。
41+
- 无网络访问、无凭证、无遥测。
42+
43+
## 安装
44+
45+
ZCode Desktop → **插件市场** → 添加收录本插件的市场（审核通过后为官方
46+
`zcode-plugins` 市场，审核前可用本地目录）→ **安装 session-stats** → 重启或新开会话
47+
→ 输入 `/stats` 或打开「会话统计」侧栏面板。
48+
49+
## 许可
50+
51+
MIT

0 commit comments

Comments
 (0)