@chenlongapps/opencode-token-usage 0.2.2 → 0.2.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/README.md +55 -61
  2. package/README.zh-CN.md +94 -0
  3. package/docs/verification.md +23 -0
  4. package/package.json +5 -5
package/README.md CHANGED
@@ -1,40 +1,30 @@
1
- # opencode-token-usage
2
-
3
- [![npm version](https://img.shields.io/npm/v/%40chenlongapps%2Fopencode-token-usage?logo=npm)](https://www.npmjs.com/package/@chenlongapps/opencode-token-usage)
4
- [![OpenCode 2](https://img.shields.io/badge/OpenCode-2-5A67D8)](https://opencode.ai/)
5
- [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
6
-
7
- 面向 **OpenCode 2** 的 token 用量插件。在原生 TUI 中显示整棵会话树（含子代理）的 token、估算费用与性能指标，以及当前会话的上下文占用。
8
-
9
- ## 预览
10
-
11
- ```text
12
- Token Usage
13
- Context 9,810 / 128,000 (7.7%)
14
- Input 54,200
15
- Output 6,800
16
- Reasoning 4,100
17
- Cache Read 31,700
18
- Cache Write 1,300
19
- Cache Rate 36.4%
20
- Total 98,100
21
- Cost $0.21
22
-
23
- TPS 48.7 tok/s
24
- TTFT 2.7s
25
- ```
1
+ <h1 align="center">opencode-token-usage</h1>
2
+
3
+ <p align="center">A session-tree token usage monitor for OpenCode 2.</p>
4
+
5
+ <p align="center">
6
+ <a href="https://www.npmjs.com/package/@chenlongapps/opencode-token-usage"><img alt="npm" src="https://img.shields.io/npm/v/%40chenlongapps%2Fopencode-token-usage?style=flat-square&logo=npm" /></a>
7
+ <a href="https://opencode.ai/"><img alt="OpenCode 2" src="https://img.shields.io/badge/OpenCode-2-5A67D8?style=flat-square" /></a>
8
+ <a href="https://github.com/chenlongapps/opencode-token-usage/actions/workflows/ci.yml"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/chenlongapps/opencode-token-usage/ci.yml?style=flat-square&branch=main&label=ci" /></a>
9
+ <a href="LICENSE"><img alt="MIT License" src="https://img.shields.io/badge/license-MIT-yellow?style=flat-square" /></a>
10
+ </p>
11
+
12
+ <p align="center">
13
+ <strong>English</strong> |
14
+ <a href="https://github.com/chenlongapps/opencode-token-usage/blob/main/README.zh-CN.md">简体中文</a>
15
+ </p>
26
16
 
27
- 实际价格与上下文上限取自当前会话的活动模型。
17
+ [![OpenCode Token Usage plugin preview](https://raw.githubusercontent.com/chenlongapps/opencode-token-usage/main/docs/assets/opencode-token-usage-preview.webp)](https://www.npmjs.com/package/@chenlongapps/opencode-token-usage)
28
18
 
29
- ## 安装
19
+ ---
30
20
 
31
- 推荐使用 OpenCode 安装：
21
+ ### Installation
32
22
 
33
23
  ```bash
34
24
  opencode plugin add @chenlongapps/opencode-token-usage
35
25
  ```
36
26
 
37
- 也可以在项目的 `opencode.json` 或 `opencode.jsonc` 中配置：
27
+ Alternatively, add the package to your project's `opencode.json` or `opencode.jsonc`:
38
28
 
39
29
  ```json
40
30
  {
@@ -42,33 +32,36 @@ opencode plugin add @chenlongapps/opencode-token-usage
42
32
  }
43
33
  ```
44
34
 
45
- 安装后重启 OpenCode。主会话中的面板位于原生侧边栏；终端需要足够宽，且 `session.sidebar` 应设为 `auto`。宿主在子代理视图中隐藏侧边栏，因此插件会在输入区上方显示同一面板。
35
+ > [!NOTE]
36
+ > Requires Node.js 22+. OpenCode 2.0.9, 2.0.10, and 2.0.11 have been verified across project releases. The current SDK 2.0.11 build has been reverified on OpenCode 2.0.11.
46
37
 
47
- 连接远程服务器时，可将包名加入本机 `~/.config/opencode/cli.json` 的 `plugins`，仅加载终端入口；配置路径遵循 `XDG_CONFIG_HOME`。
38
+ Restart OpenCode after installation. The panel appears in the native sidebar when `session.sidebar` is set to `auto` and the terminal is wide enough. OpenCode hides the sidebar in subagent views, so the plugin renders the same panel above the composer instead.
48
39
 
49
- ## 指标口径
40
+ For remote sessions, add the package name to `plugins` in your local `~/.config/opencode/cli.json` to load only the terminal entry point. The configuration path follows `XDG_CONFIG_HOME`.
50
41
 
51
- | 指标 | 定义 |
42
+ ### Metrics
43
+
44
+ | Metric | Definition |
52
45
  | --- | --- |
53
- | `Input` | 输入 token，不含缓存读取和写入 |
54
- | `Output` | 输出 token，不含推理 token |
55
- | `Reasoning` | 推理 token |
46
+ | `Input` | Input tokens, excluding cache reads and writes |
47
+ | `Output` | Output tokens, excluding reasoning tokens |
48
+ | `Reasoning` | Reasoning tokens |
56
49
  | `Cache Rate` | `Cache Read ÷ (Input + Cache Read + Cache Write)` |
57
- | `Total` | 五类 token 之和 |
58
- | `Context` | 当前会话最后一次已完成压缩后的最新上下文用量，不随子树累计 |
59
- | `Cost` | 按当前会话活动模型重新估算的全树费用，不代表提供商账单 |
60
- | `TPS` | 全树 `Output + Reasoning` 的生成速度；生成中显示 `~` 估算值，完成后显示精确值 |
61
- | `TTFT` | 全树中可测 assistant step 的平均首 token 时间 |
50
+ | `Total` | Sum of all five token categories |
51
+ | `Context` | Latest context usage after the most recent completed compaction in the viewed session; not aggregated across the subtree |
52
+ | `Cost` | Estimated cost for the entire tree, recalculated using the viewed session's active model; not a provider bill |
53
+ | `TPS` | Generation throughput for `Output + Reasoning` across the tree; live estimates are marked with `~` |
54
+ | `TTFT` | Average time to first token across measurable assistant steps in the tree |
62
55
 
63
- 补充说明：
56
+ #### Behavior
64
57
 
65
- - 用量覆盖当前会话树中的 assistant 与 compaction 消息，包括未打开的子代理；只使用服务端上报值，不按文本长度估算。
66
- - 分叉会话是独立会话树。继承消息副本只归原始来源，避免重复计费。
67
- - `Context` 仅搜索最后一次 `status === "completed"` 的 compaction 之后；没有可靠用量或模型上限时隐藏。
68
- - `Cost` 使用每条消息的传入 token 选择价格档位，`Output` 与 `Reasoning` 使用输出价格。缺失适用价格时按 OpenCode 官方行为回退为 0。
69
- - 首次读取失败显示 `Unavailable`；后续刷新失败保留上次完整快照、标注 `Not updated` 并自动重试。
58
+ - Usage includes server-reported assistant and compaction messages throughout the session tree, including unopened subagents. Token counts are never inferred from text length.
59
+ - A fork is a separate session tree. Inherited message copies are attributed only to their original source to prevent double counting.
60
+ - `Context` only searches messages after the most recent compaction with `status === "completed"` and is hidden when reliable usage or a model context limit is unavailable.
61
+ - `Cost` applies the viewed session's active model to the whole tree. Missing applicable prices fall back to 0, matching OpenCode's behavior.
62
+ - Initial read failures display `Unavailable`. Later failures retain the last complete snapshot, display `Not updated`, and retry automatically.
70
63
 
71
- ## 开发
64
+ ### Development
72
65
 
73
66
  ```bash
74
67
  npm ci
@@ -78,23 +71,24 @@ npm run build
78
71
  npm run test:smoke
79
72
  ```
80
73
 
81
- `test:smoke` 会打包真实产物，并在隔离的 OpenCode 与本地模拟提供商中验证加载、刷新、子代理累计、模型切换、TPS 和 TTFT。它需要 Python 3、可用的本地端口和 npm 网络访问，不会修改现有 OpenCode 配置或调用付费模型。
74
+ `test:smoke` packages the real artifact and validates loading, refreshes, subagent aggregation, model switching, TPS, and TTFT against an isolated OpenCode instance and a local mock provider. It requires Python 3, an available local port, and npm network access. It never modifies your existing OpenCode configuration or calls paid models.
75
+
76
+ To load the plugin from source, build the project and add the repository's absolute path to `plugins` in the target project.
77
+
78
+ ### Documentation
82
79
 
83
- 从源码加载时，先构建项目，再将仓库绝对路径加入目标项目的 `plugins`。根目录入口会转发到已编译的 ESM 产物。
80
+ - [Roadmap](ROADMAP.md)
81
+ - [Verification record](docs/verification.md)
82
+ - [Release guide](docs/releasing.md)
83
+ - [OpenCode 2 plugin documentation](https://opencode.ai/v2/docs/build/plugins/)
84
+ - [OpenCode 2 CLI plugin API](https://opencode.ai/v2/docs/build/plugins/cli/)
84
85
 
85
- - [路线图](ROADMAP.md)
86
- - [验证记录](docs/verification.md)
87
- - [发布说明](docs/releasing.md)
86
+ The implementation follows OpenCode's [TokenUsage schema](https://github.com/anomalyco/opencode/blob/v2/packages/schema/src/token-usage.ts), [cost calculation](https://github.com/anomalyco/opencode/blob/v2/packages/core/src/session/usage.ts), and [fork history projection](https://github.com/anomalyco/opencode/blob/v2/packages/core/src/session/projector.ts).
88
87
 
89
- ## 接口依据
88
+ ### Disclaimer
90
89
 
91
- - [OpenCode 2 插件开发](https://opencode.ai/v2/docs/build/plugins/)
92
- - [OpenCode 2 CLI 插件接口](https://opencode.ai/v2/docs/build/plugins/cli/)
93
- - [CLI 设置](https://opencode.ai/v2/docs/cli/config/)
94
- - [TokenUsage 定义](https://github.com/anomalyco/opencode/blob/v2/packages/schema/src/token-usage.ts)
95
- - [官方计费实现](https://github.com/anomalyco/opencode/blob/v2/packages/core/src/session/usage.ts)
96
- - [分叉历史投影](https://github.com/anomalyco/opencode/blob/v2/packages/core/src/session/projector.ts)
90
+ This is an independent community plugin. It is not built, maintained, or endorsed by the OpenCode team.
97
91
 
98
- ## 许可证
92
+ ### License
99
93
 
100
94
  [MIT](LICENSE)
package/README.zh-CN.md ADDED
@@ -0,0 +1,94 @@
1
+ <h1 align="center">opencode-token-usage</h1>
2
+
3
+ <p align="center">面向 OpenCode 2 的会话树 token 用量监视器。</p>
4
+
5
+ <p align="center">
6
+ <a href="https://www.npmjs.com/package/@chenlongapps/opencode-token-usage"><img alt="npm" src="https://img.shields.io/npm/v/%40chenlongapps%2Fopencode-token-usage?style=flat-square&logo=npm" /></a>
7
+ <a href="https://opencode.ai/"><img alt="OpenCode 2" src="https://img.shields.io/badge/OpenCode-2-5A67D8?style=flat-square" /></a>
8
+ <a href="https://github.com/chenlongapps/opencode-token-usage/actions/workflows/ci.yml"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/chenlongapps/opencode-token-usage/ci.yml?style=flat-square&branch=main&label=ci" /></a>
9
+ <a href="LICENSE"><img alt="MIT License" src="https://img.shields.io/badge/license-MIT-yellow?style=flat-square" /></a>
10
+ </p>
11
+
12
+ <p align="center">
13
+ <a href="README.md">English</a> |
14
+ <strong>简体中文</strong>
15
+ </p>
16
+
17
+ [![OpenCode Token Usage 插件预览](https://raw.githubusercontent.com/chenlongapps/opencode-token-usage/main/docs/assets/opencode-token-usage-preview.webp)](https://www.npmjs.com/package/@chenlongapps/opencode-token-usage)
18
+
19
+ ---
20
+
21
+ ### 安装
22
+
23
+ ```bash
24
+ opencode plugin add @chenlongapps/opencode-token-usage
25
+ ```
26
+
27
+ 也可以在项目的 `opencode.json` 或 `opencode.jsonc` 中配置：
28
+
29
+ ```json
30
+ {
31
+ "plugins": ["@chenlongapps/opencode-token-usage"]
32
+ }
33
+ ```
34
+
35
+ > [!NOTE]
36
+ > 需要 Node.js 22+。项目历次发布已验证 OpenCode 2.0.9、2.0.10 和 2.0.11；当前 SDK 2.0.11 构建已在 OpenCode 2.0.11 上重新验证。
37
+
38
+ 安装后重启 OpenCode。终端足够宽且 `session.sidebar` 设为 `auto` 时，面板会显示在原生侧边栏中。OpenCode 在子代理视图中隐藏侧边栏，因此插件会在输入区上方显示同一面板。
39
+
40
+ 连接远程服务器时，可将包名加入本机 `~/.config/opencode/cli.json` 的 `plugins`，仅加载终端入口；配置路径遵循 `XDG_CONFIG_HOME`。
41
+
42
+ ### 指标
43
+
44
+ | 指标 | 定义 |
45
+ | --- | --- |
46
+ | `Input` | 输入 token，不含缓存读取和写入 |
47
+ | `Output` | 输出 token，不含推理 token |
48
+ | `Reasoning` | 推理 token |
49
+ | `Cache Rate` | `Cache Read ÷ (Input + Cache Read + Cache Write)` |
50
+ | `Total` | 五类 token 之和 |
51
+ | `Context` | 当前会话最后一次已完成压缩后的最新上下文用量，不随子树累计 |
52
+ | `Cost` | 按当前会话活动模型重新估算的全树费用，不代表提供商账单 |
53
+ | `TPS` | 全树 `Output + Reasoning` 的生成速度；生成中的估算值带 `~` 标记 |
54
+ | `TTFT` | 全树中可测 assistant step 的平均首 token 时间 |
55
+
56
+ #### 行为
57
+
58
+ - 用量覆盖会话树中服务端上报的 assistant 与 compaction 消息，包括未打开的子代理；不按文本长度估算 token。
59
+ - 分叉会话是独立会话树。继承消息副本只归原始来源，避免重复计费。
60
+ - `Context` 仅搜索最后一次 `status === "completed"` 的 compaction 之后；没有可靠用量或模型上限时隐藏。
61
+ - `Cost` 使用当前查看会话的活动模型重算整棵树；缺失适用价格时按 OpenCode 行为回退为 0。
62
+ - 首次读取失败显示 `Unavailable`；后续失败保留上次完整快照、标注 `Not updated` 并自动重试。
63
+
64
+ ### 开发
65
+
66
+ ```bash
67
+ npm ci
68
+ npm run typecheck
69
+ npm test
70
+ npm run build
71
+ npm run test:smoke
72
+ ```
73
+
74
+ `test:smoke` 会打包真实产物，并在隔离的 OpenCode 与本地模拟提供商中验证加载、刷新、子代理累计、模型切换、TPS 和 TTFT。它需要 Python 3、可用的本地端口和 npm 网络访问，不会修改现有 OpenCode 配置或调用付费模型。
75
+
76
+ 从源码加载时，先构建项目，再将仓库绝对路径加入目标项目的 `plugins`。
77
+
78
+ ### 文档
79
+
80
+ - [路线图](ROADMAP.md)
81
+ - [验证记录](docs/verification.md)
82
+ - [发布说明](docs/releasing.md)
83
+ - [OpenCode 2 插件开发文档](https://opencode.ai/v2/docs/build/plugins/)
84
+ - [OpenCode 2 CLI 插件接口](https://opencode.ai/v2/docs/build/plugins/cli/)
85
+
86
+ 实现遵循 OpenCode 的 [TokenUsage 定义](https://github.com/anomalyco/opencode/blob/v2/packages/schema/src/token-usage.ts)、[官方计费实现](https://github.com/anomalyco/opencode/blob/v2/packages/core/src/session/usage.ts)和[分叉历史投影](https://github.com/anomalyco/opencode/blob/v2/packages/core/src/session/projector.ts)。
87
+
88
+ ### 声明
89
+
90
+ 这是一个独立的社区插件，并非由 OpenCode 团队构建、维护或认可。
91
+
92
+ ### 许可证
93
+
94
+ [MIT](LICENSE)
package/docs/verification.md CHANGED
@@ -1,5 +1,28 @@
1
1
  # 验证记录
2
2
 
3
+ ## 未发布（SDK 2.0.11）
4
+
5
+ 验证日期：2026-09-20。环境：macOS、Node.js v22.23.2、npm 10.9.8、OpenCode v2.0.11；`@opencode/plugin`、`@opencode/client`、`@opencode/schema` 和 `@opencode/theme` 均精确锁定为 2.0.11。
6
+
7
+ ### 自动化检查
8
+
9
+ | 检查 | 结果 |
10
+ | --- | --- |
11
+ | `npm run typecheck` | 通过 |
12
+ | `npm test` | 29 项通过 |
13
+ | `npm run build` | 通过，输出 ESM 与类型声明 |
14
+ | `npm run test:smoke` | 通过，使用实际 `.tgz` 安装产物和真实 OpenCode 2.0.11 |
15
+
16
+ SDK 从 2.0.9 升级到 2.0.11 后，四个顶层 OpenCode 包及锁文件中的传递依赖均已统一到 2.0.11。`@opencode/plugin` 两版的导出结构一致；包内容差异除依赖版本外，仅为 `ToastOptions` 新增可选的 `sessionID` 类型字段。
17
+
18
+ ### 真实 OpenCode 集成
19
+
20
+ 隔离 smoke 测试确认打包插件可加载；空会话隐藏无数据行；活动 TPS 估算会收敛为精确值；TTFT、token、上下文与费用正常刷新；真实子代理用量可从父子视图累计且上下文保持会话局部；切换活动模型会同步更新价格选择与上下文上限。测试产物保存在 `/var/folders/rw/bmx6c8hd737brl55m0_ff_b80000gn/T/token-usage-smoke-JXe1KG`。
21
+
22
+ ### 验证边界
23
+
24
+ 当前 SDK 2.0.11 与宿主 2.0.11 的组合已完整验证。2.0.9 和 2.0.10 宿主的历史验证记录保留在下方，但升级 SDK 后未重新执行这两个旧宿主的打包矩阵：本地仅有 2.0.11，官方 GitHub Releases 也没有可获取的对应旧版本资产。后续升级 SDK 或宿主时，仍需重新核对分叉副本、compaction 排序及 step/delta 事件语义。
25
+
3
26
  ## v0.2.1（TPS 与 TTFT）
4
27
 
5
28
  验证日期：2026-09-20。环境：macOS、Node.js v22.23.2、npm 10.9.8、OpenCode v2.0.11；插件 SDK 依赖为 2.0.9。
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@chenlongapps/opencode-token-usage",
3
- "version": "0.2.2",
3
+ "version": "0.2.3",
4
4
  "description": "Session-tree token usage, live performance, context window and estimated cost for OpenCode 2",
5
5
  "keywords": [
6
6
  "opencode",
@@ -57,7 +57,7 @@
57
57
  "registry": "https://registry.npmjs.org/"
58
58
  },
59
59
  "dependencies": {
60
- "@opencode/plugin": "2.0.9"
60
+ "@opencode/plugin": "2.0.11"
61
61
  },
62
62
  "peerDependencies": {
63
63
  "@opentui/core": "0.5.10",
@@ -66,9 +66,9 @@
66
66
  },
67
67
  "devDependencies": {
68
68
  "@babel/core": "^7.28.0",
69
- "@opencode/client": "2.0.9",
70
- "@opencode/schema": "2.0.9",
71
- "@opencode/theme": "2.0.9",
69
+ "@opencode/client": "2.0.11",
70
+ "@opencode/schema": "2.0.11",
71
+ "@opencode/theme": "2.0.11",
72
72
  "@opentui/core": "0.5.10",
73
73
  "@opentui/solid": "0.5.10",
74
74
  "@types/node": "^22.0.0",