@marshal/pi-turn-stats 0.1.0 → 0.1.2

package/README.md

@@ -1,37 +1,61 @@
 # @marshal/pi-turn-stats
 
-pi extension: conversation statistics (对话统计). For every exchange, records duration, token usage (input / output / cache read / cache write), and cost.
+pi 扩展：对话统计（Turn Stats）。每次对话交换后，自动记录耗时、token 用量（input / output / cache read / cache write）和费用。
 
-## Features
+## 功能特性
 
-- **对话流统计卡片** — after each reply, appends a stats card to the conversation stream (not sent to the LLM context).
-- **状态栏实时显示** — bottom status bar shows the previous exchange's duration / output speed / tokens / cost.
-- **`/turnstats` 命令** — appends a session-cumulative stats card (total exchanges, turns, tokens, cost).
+- **对话流统计卡片** — 每次回复后，在对话流中追加统计卡片（不会进入 LLM 上下文）。
+- **状态栏实时显示** — 底部状态栏显示上一轮对话的耗时 / 输出速度 / token 数 / 费用。
+- **`/turnstats` 命令** — 追加会话累计统计卡片（总交换次数、总轮次、总 token、总费用）。
 
-## Installation
+## 效果截图
 
-Install project-locally (recommended, supports per-project version pinning):
+![Turn Stats](turn-stats.jpg)
+
+## 安装
+
+**推荐方式**：从 npm 安装，国内访问稳定，且可查看安装统计。
 
 ```bash
-# From the GitHub repo, pinned to a git tag (SSH)
-pi install -l git:git@github.com:MarshalW/pi-turn-stats@v0.1.0
+# pi 直接安装 npm 包
+pi install -l npm:@marshal/pi-turn-stats
 ```
 
-## Note
+或使用标准 npm 安装：
 
-Generated stats are **local-only** — nothing is uploaded anywhere. Reads `turn_end` event usage data and wall-clock timing inside the running pi process.
+```bash
+npm install @marshal/pi-turn-stats
+```
 
-## Development
+> 注意：`pi install -l npm:...` 是 pi 推荐的本地安装方式，会将扩展安装到当前项目；普通 `npm install` 仅下载包，不自动注册为 pi 扩展。
+
+**备选方式**：从 GitHub 安装（适合需要源码或自定义修改的场景）。
+
+```bash
+# 从 GitHub 仓库安装，指定 tag（SSH）
+pi install -l git:git@github.com:MarshalW/pi-turn-stats@v0.1.1
+```
+
+> 国内用户建议优先使用 npm 方式，GitHub 访问可能不稳定。
+
+## 说明
+
+生成的统计数据**仅本地存储**，不会上传到任何服务器。读取运行中 pi 进程内的 `turn_end` 事件数据和实际耗时。
+
+## 开发
 
 ```bash
 git clone git@github.com:MarshalW/pi-turn-stats.git
 cd pi-turn-stats
-pi install ./        # local install for testing
+pi install ./        # 本地安装，用于测试
 ```
 
-## Release flow
+## 发布流程
 
 ```bash
 git tag vX.Y.Z && git push origin main --tags
-# then on each consumer machine: pi install -l git:...@vX.Y.Z
-```
+# 发布到 npm：npm version patch && npm publish --access public
+# 消费端安装：
+#   npm 方式（推荐）：pi install -l npm:@marshal/pi-turn-stats
+#   git 方式（备选）：pi install -l git:git@github.com:MarshalW/pi-turn-stats@vX.Y.Z
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@marshal/pi-turn-stats",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "pi extension: per-exchange duration, token & cost stats for conversations (stream card + status bar + /turnstats command)",
   "keywords": [
     "pi-package"
@@ -9,11 +9,12 @@
   "license": "MIT",
   "files": [
     "extensions",
-    "README.md"
+    "README.md",
+    "turn-stats.jpg"
   ],
   "pi": {
     "extensions": [
       "./extensions/turn-stats.ts"
     ]
   }
-}
+}