@liziy/session-queue 0.2.0
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.
- package/README.md +149 -0
- package/index.ts +1873 -0
- package/package.json +29 -0
package/README.md
ADDED
|
@@ -0,0 +1,149 @@
|
|
|
1
|
+
# @liziy/session-queue
|
|
2
|
+
|
|
3
|
+
> **Switch UI language:** `/rollback zh` · `/rollback en` (zh = 中文, en = English)
|
|
4
|
+
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
## English
|
|
8
|
+
|
|
9
|
+
Convert pi's session tree into a linear rollback queue. Every turn auto-records modified files; rollback restores them in one click.
|
|
10
|
+
|
|
11
|
+
### Features
|
|
12
|
+
|
|
13
|
+
- **JIT capture** — snapshots before/after `edit`/`write`/`bash` tool calls (zero startup overhead)
|
|
14
|
+
- **Content-addressed storage** — dedup by sha256
|
|
15
|
+
- **Dirty check** — refuses to overwrite externally modified files
|
|
16
|
+
- **Workspace whitelist** — opt-in per directory; nothing recorded by default
|
|
17
|
+
- **Snapshot GC** — mark-sweep keeps disk usage bounded
|
|
18
|
+
- **bash tracking** — `rm`/`del`/`mv`/`>`/`>>` (multi-file, simple globs)
|
|
19
|
+
- **Session Tree sync** — navigating to an older point auto-rolls back the queue
|
|
20
|
+
- **Zero dependencies** · **i18n: zh / en**
|
|
21
|
+
|
|
22
|
+
### Install
|
|
23
|
+
|
|
24
|
+
```bash
|
|
25
|
+
pi install npm:@liziy/session-queue
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
### Commands
|
|
29
|
+
|
|
30
|
+
| Command | Action |
|
|
31
|
+
|---|---|
|
|
32
|
+
| `/rollback` | Open main menu (rollback / workspace / GC / settings) |
|
|
33
|
+
| `/rollback enable` | Start tracking current directory |
|
|
34
|
+
| `/rollback disable` | Pause tracking |
|
|
35
|
+
| `/rollback list` | List enabled workspaces |
|
|
36
|
+
| `/rollback gc` | Manually run snapshot GC |
|
|
37
|
+
| `/rollback zh` | Switch UI to Chinese |
|
|
38
|
+
| `/rollback en` | Switch UI to English |
|
|
39
|
+
|
|
40
|
+
### Quick Start
|
|
41
|
+
|
|
42
|
+
1. `/rollback enable` — start tracking
|
|
43
|
+
2. Work normally; each `turn_end` writes a checkpoint
|
|
44
|
+
3. `/rollback` → select a checkpoint → confirm → files restored
|
|
45
|
+
4. Optional: open Session Tree, click an older message, type a new question — queue auto-syncs
|
|
46
|
+
|
|
47
|
+
### Status Bar
|
|
48
|
+
|
|
49
|
+
| Indicator | Meaning |
|
|
50
|
+
|---|---|
|
|
51
|
+
| (hidden) | No workspace active |
|
|
52
|
+
| `● 记录` (cyan) | Workspace tracking only |
|
|
53
|
+
| `● 同步` (green) | Tracking + Session Tree auto-sync |
|
|
54
|
+
|
|
55
|
+
### Rollback Semantics
|
|
56
|
+
|
|
57
|
+
- **Files**: each file's `beforeHash` from the **earliest** discarded turn is restored — reverts to the state right before the first modification, not an intermediate snapshot
|
|
58
|
+
- **Queue**: `entries.slice(0, targetIdx)` — drops target and all later entries
|
|
59
|
+
- **Conflicts**: skipped files are kept as a `residual` entry (re-tryable)
|
|
60
|
+
- **Safety**: missing snapshot = skip + warn, never delete blindly
|
|
61
|
+
|
|
62
|
+
### Storage
|
|
63
|
+
|
|
64
|
+
```
|
|
65
|
+
~/.pi/agent/extensions/session-queue/
|
|
66
|
+
├── config.json # workspaces, followSessionTree, lang
|
|
67
|
+
├── queue-{sessionId}.json # last 10 entries + changes
|
|
68
|
+
└── snapshots/{hash}.content # content-addressed
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
### Limits
|
|
72
|
+
|
|
73
|
+
- Tracks `edit` / `write` / partial `bash` only (no `sed -i`, `npm install`, subshells)
|
|
74
|
+
- 10-entry rolling window; older turns are not recorded or restorable
|
|
75
|
+
- Doesn't undo pi's tree; use `/tree` for that
|
|
76
|
+
- Directory create/remove are not reverted
|
|
77
|
+
|
|
78
|
+
---
|
|
79
|
+
|
|
80
|
+
## 中文
|
|
81
|
+
|
|
82
|
+
把 pi 的会话从「树」改为「队列」：每个 turn 自动记录修改的文件，回滚时一键还原。
|
|
83
|
+
|
|
84
|
+
### 特性
|
|
85
|
+
|
|
86
|
+
- **JIT 拦截**：工具执行前后拍照存证（0 启动开销）
|
|
87
|
+
- **内容寻址**：相同内容只存一次（sha256）
|
|
88
|
+
- **脏检查**：拒绝覆盖外部已修改的文件
|
|
89
|
+
- **工作区白名单**：按目录启用，默认不记录
|
|
90
|
+
- **snapshot GC**：标记-扫描回收，控制磁盘占用
|
|
91
|
+
- **bash 追踪**：`rm`/`del`/`mv`/`>`/`>>`（多文件、简单 glob）
|
|
92
|
+
- **Session Tree 同步**：导航到旧对话点时队列自动回滚
|
|
93
|
+
- **零依赖** · **i18n: zh / en**
|
|
94
|
+
|
|
95
|
+
### 安装
|
|
96
|
+
|
|
97
|
+
```bash
|
|
98
|
+
pi install npm:@liziy/session-queue
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
### 命令
|
|
102
|
+
|
|
103
|
+
| 命令 | 作用 |
|
|
104
|
+
|---|---|
|
|
105
|
+
| `/rollback` | 唤起主菜单（回滚 / 工作区 / GC / 设置） |
|
|
106
|
+
| `/rollback enable` | 启用当前目录的记录 |
|
|
107
|
+
| `/rollback disable` | 暂停记录 |
|
|
108
|
+
| `/rollback list` | 列出已启用工作区 |
|
|
109
|
+
| `/rollback gc` | 手动执行 GC |
|
|
110
|
+
| `/rollback zh` | 切换界面为中文 |
|
|
111
|
+
| `/rollback en` | 切换界面为英文 |
|
|
112
|
+
|
|
113
|
+
### 快速上手
|
|
114
|
+
|
|
115
|
+
1. `/rollback enable` — 开始记录
|
|
116
|
+
2. 正常使用；每个 `turn_end` 写入一个检查点
|
|
117
|
+
3. `/rollback` → 选检查点 → 确认 → 文件还原
|
|
118
|
+
4. 可选：Session Tree 选旧消息 + 输入新问题 → 队列自动同步
|
|
119
|
+
|
|
120
|
+
### 状态栏
|
|
121
|
+
|
|
122
|
+
| 指示 | 含义 |
|
|
123
|
+
|---|---|
|
|
124
|
+
| （隐藏） | 未启用工作区 |
|
|
125
|
+
| `● 记录`（青色） | 仅记录 |
|
|
126
|
+
| `● 同步`（绿色） | 记录 + 跟随 Session Tree |
|
|
127
|
+
|
|
128
|
+
### 回滚语义
|
|
129
|
+
|
|
130
|
+
- **文件**：取被丢弃 turn 中**最早**那条修改的 `beforeHash` 还原（不是中间快照）
|
|
131
|
+
- **队列**：`entries.slice(0, targetIdx)` — 丢弃目标及之后
|
|
132
|
+
- **冲突**：被跳过的文件保留为 `residual` entry（可重试）
|
|
133
|
+
- **安全**：快照丢失 = 跳过 + 告警，绝不盲目删除
|
|
134
|
+
|
|
135
|
+
### 存储
|
|
136
|
+
|
|
137
|
+
```
|
|
138
|
+
~/.pi/agent/extensions/session-queue/
|
|
139
|
+
├── config.json # 工作区、followSessionTree、lang
|
|
140
|
+
├── queue-{sessionId}.json # 最近 10 条 entry + changes
|
|
141
|
+
└── snapshots/{hash}.content # 内容寻址
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
### 限制
|
|
145
|
+
|
|
146
|
+
- 仅追踪 `edit` / `write` / 部分 `bash`（`sed -i`、`npm install`、子 shell 不可）
|
|
147
|
+
- 10 轮滚动窗口；超出的 turn 不被记录也不可回滚
|
|
148
|
+
- 不撤销 pi 的会话树，用 `/tree` 查看完整历史
|
|
149
|
+
- 目录的创建/删除无法还原
|