@sion10032/pi-sessions 0.0.0-stage → 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/LICENSE +21 -0
- package/README.md +261 -2
- package/THIRD_PARTY_NOTICES.md +51 -0
- package/package.json +21 -5
- package/src/archive.ts +356 -0
- package/src/commands.ts +401 -0
- package/src/delete.ts +166 -0
- package/src/index.ts +101 -0
- package/src/paths.ts +235 -0
- package/src/picker-state.ts +377 -0
- package/src/picker.ts +526 -0
- package/src/rename.ts +23 -0
- package/src/search.ts +258 -0
- package/src/sessions.ts +492 -0
- package/src/state.ts +115 -0
- package/src/types.ts +47 -0
- package/src/undo.ts +183 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 sion10032
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,262 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @sion10032/pi-sessions
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
用 `/sessions` 浏览、搜索、恢复、归档与取消归档 pi 会话;归档父会话时,它的子代理会话与 fork 会一起移动。
|
|
4
|
+
|
|
5
|
+
## 功能概览
|
|
6
|
+
|
|
7
|
+
- **统一浏览**:一个 `/sessions` 界面里同时看活跃会话与归档会话,支持模糊搜索、`"整段短语"`、`re:<pattern>` 正则、三段式展开、`current`/`all` 作用域、命名过滤、路径显示与三种排序。
|
|
8
|
+
- **picker 内归档**:`ctrl+a` 归档/取消归档选中会话,所有动作都先显示确认行。归档父会话时,整棵 `parentSession` 子树(子代理会话、fork 及其后代)一起移动。
|
|
9
|
+
- **整棵子树恢复**:`enter` 恢复归档会话;归档文件先移回活跃目录,再切换过去。根会话与全部派生会话一起回来。
|
|
10
|
+
- **当前会话延迟归档**:pi 正在写入的文件不能移动,所以 `/archive`、`archive_session` 工具和 picker 对当前会话的 `ctrl+a` 只记录“关闭后归档”,等会话关闭时才移动;`/reload` 不移动。
|
|
11
|
+
- **物理移动,不靠索引**:归档状态由“文件在 `sessions/` 还是 `sessions-archive/`”决定,因此原生 `/resume` 始终干净,索引丢失也不会丢归档。
|
|
12
|
+
- **不改写会话**:归档不改 header、不调用 `setSessionName`,未命名会话继续显示首条消息;只会在恢复时剥除旧插件留下的 `[ARCHIVE] ` 名称标签。
|
|
13
|
+
- **无网络**:所有操作都是本地文件移动与本地搜索。
|
|
14
|
+
|
|
15
|
+
## 安装
|
|
16
|
+
|
|
17
|
+
发布后从 npm 安装:
|
|
18
|
+
|
|
19
|
+
```bash
|
|
20
|
+
pi install npm:@sion10032/pi-sessions
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
从本仓库的本地路径安装(写入 `~/.pi/agent/settings.json`):
|
|
24
|
+
|
|
25
|
+
```bash
|
|
26
|
+
pi install ./packages/pi-sessions
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
只想试一次、不写入设置:
|
|
30
|
+
|
|
31
|
+
```bash
|
|
32
|
+
pi -e ./packages/pi-sessions
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
包在 `package.json` 的 `pi.extensions` 里声明入口 `./src/index.ts`,pi 直接加载 TypeScript 源码。依赖 `@earendil-works/pi-coding-agent`、`@earendil-works/pi-tui`、`typebox` 由 pi 自身提供(peer dependency),不需要单独安装。
|
|
36
|
+
|
|
37
|
+
## 命令与工具
|
|
38
|
+
|
|
39
|
+
| 名称 | 用法 | 说明 |
|
|
40
|
+
| --- | --- | --- |
|
|
41
|
+
| `/sessions` | `/sessions [active\|archived\|all]` | 打开会话列表;可选参数只决定初始的归档筛选,打开后仍可切换 |
|
|
42
|
+
| `/undo` | `/undo` | 回滚到最新一条用户消息之前:原文回到输入框,尾部从会话文件里真正删掉,不新建子树 |
|
|
43
|
+
| `/archive` | `/archive` | 把当前会话标记为“关闭后归档” |
|
|
44
|
+
| `archive_session` | 工具调用,无参数 | 同上,供 agent 在用户说“工作完成了”时调用 |
|
|
45
|
+
| `/resume` | 原生命令 | 仍可正常使用,只看活跃会话(归档会话不在其中) |
|
|
46
|
+
|
|
47
|
+
`/archives` 已移除。旧操作在新界面里的对应关系:
|
|
48
|
+
|
|
49
|
+
| 旧插件 | 现在 |
|
|
50
|
+
| --- | --- |
|
|
51
|
+
| `/archives` 浏览归档 | `/sessions` 后按 `ctrl+t` 切到 `archived` |
|
|
52
|
+
| `Restore and resume` | 在归档行上按 `enter` |
|
|
53
|
+
| `Restore only` | 在归档行上按 `ctrl+a` |
|
|
54
|
+
| `Resume, keep archived` | 不再提供:恢复后再归档即可 |
|
|
55
|
+
|
|
56
|
+
在非 TUI 模式(例如没有自定义组件的界面)下,`/sessions` 退化为 `ctx.ui.select` 的扁平编号列表,只支持恢复;归档请用 `/archive` 或 `archive_session` 工具。那里没有 `ctrl+t`,所以列表默认同时显示活跃与归档会话(归档行带 `[archived]` 标记);用 `/sessions active` 或 `/sessions archived` 可以只看其中一种。
|
|
57
|
+
|
|
58
|
+
## `/sessions` 键位
|
|
59
|
+
|
|
60
|
+
| 键 | 行为 |
|
|
61
|
+
| --- | --- |
|
|
62
|
+
| `tab` | 切换作用域:`current`(当前目录)↔ `all`(所有目录) |
|
|
63
|
+
| `ctrl+e` | 循环切换统一展开预设:`Collapsed` → `Children` → `All` → `Collapsed`(搜索框有文字时也可用) |
|
|
64
|
+
| `←` / `→` | 移动搜索框光标;当前不绑定单行展开/收起 |
|
|
65
|
+
| `ctrl+s` | 切换排序:`threaded` → `recent` → `relevance`;只在树内重排,展开由预设控制 |
|
|
66
|
+
| `ctrl+n` | 只看命名会话,再按一次显示全部 |
|
|
67
|
+
| `ctrl+p` | 显示/隐藏会话文件路径 |
|
|
68
|
+
| `ctrl+r` | 重命名选中会话(`enter` 保存、`esc` 取消);只写 `session_info`,不移动文件 |
|
|
69
|
+
| `ctrl+d` | 删除选中会话(先确认);连子树、伴生文件与另一棵树的孪生副本一起删 |
|
|
70
|
+
| `ctrl+backspace` | 搜索框为空时等同 `ctrl+d`,否则删除一个字符 |
|
|
71
|
+
| `ctrl+t` | 切换归档筛选:`active` → `archived` → `all` |
|
|
72
|
+
| `ctrl+a` | 归档/取消归档选中会话(先确认);当前会话为延迟归档,已归档的当前会话不做任何操作 |
|
|
73
|
+
| `enter` | 恢复选中会话(归档会话会先移回活跃目录) |
|
|
74
|
+
| `esc` | 取消(确认状态下取消确认) |
|
|
75
|
+
| `↑` / `↓`、`pgup` / `pgdn` | 上下移动、翻页 |
|
|
76
|
+
| 鼠标滚轮 / 左键单击 | 滚动列表 / 选中行 |
|
|
77
|
+
| 其他输入 | 进入过滤框:空格分词(模糊匹配)、`"整段短语"`、`re:<pattern>` |
|
|
78
|
+
|
|
79
|
+
说明:
|
|
80
|
+
|
|
81
|
+
- 默认状态为 `scope: current`、`sort: threaded`、`expand: Collapsed`、归档筛选 `active`、`named: All`、`path: off`;当前会话高亮,归档行带暗色 `[archived]`。
|
|
82
|
+
- 标题栏与原生会话选择器一致:左侧 `Sessions (Current Folder)` / `Sessions (All)`,右侧 `◉ Current Folder | ○ All Expand: Collapsed Name: All Sort: Threaded Filter: Active`(窄终端会保留左侧标题并截断右侧);`> ` 过滤框,选中行高亮,命名会话用 warning 色,当前会话用 accent 色。
|
|
83
|
+
- 三段式展开是**统一预设**:按 `ctrl+e` 循环 `Collapsed` → `Children` → `All` → `Collapsed`。`Collapsed` 全部收起;`Children` 自动展开 fork/clone 子树并隐藏 subagent 行;`All` 展开所有层级并显示 subagent。默认和 Children 下都不会露出 subagent,只有 All 会。当前版本单行展开/收起暂未绑定按键,先用三段式预设(内部实现保留,选定键位后可恢复)。
|
|
84
|
+
- 有过滤词时,列表退化为扁平结果列表(与原生 picker 一致);subagent 行跟随展开预设:默认/Children 不出现,只有 All 才会被搜出来。
|
|
85
|
+
- 折叠时父行消息后显示 `↳N` 后代数;这个数字包含当前预设隐藏的 subagent(即使标题很长也不会被截掉)。展开后子行使用原生 `├─` / `└─` 树形前缀。
|
|
86
|
+
- `ctrl+a` 的所有动作都会先显示确认行;确认行位于标题下方、使用 error 红色,且不显示标题(长标题不会把动作文字挤掉):`Archive this session?`、`Archive this session and N child sessions?`、`Unarchive this session?`、`Archive the current session when it closes?`;`enter` 确认,`esc` 或 `ctrl+c` 取消。
|
|
87
|
+
- `tab` 切换作用域时,列表会立即清空并显示 `Loading… 已加载/总数`,live 会话按 `SessionManager.listAll` 的进度分批出现,归档目录随后逐个合并;再次切换或关闭 picker 会中止上一次加载。
|
|
88
|
+
- `tab`、`ctrl+s`、`ctrl+n`、`ctrl+p`、`ctrl+r`、`ctrl+d`、`ctrl+backspace` 使用 pi 的键位名 `tui.input.tab`、`app.session.toggleSort`、`app.session.toggleNamedFilter`、`app.session.togglePath`、`app.session.rename`、`app.session.delete`、`app.session.deleteNoninvasive`,可在 `~/.pi/agent/keybindings.json` 里改;`ctrl+t`、`ctrl+e`、`ctrl+a` 是本插件直接读取的按键,不可改。
|
|
89
|
+
|
|
90
|
+
## `/undo` 语义
|
|
91
|
+
|
|
92
|
+
**落点。** `/undo` 取当前分支上离 leaf 最近的一条用户消息,把 leaf 退回到它的上一条,并把这句原文放回输入框(编辑器里已经有草稿时不覆盖,只提示未写回)。分支优先级按 `getBranch()`,不是文件里最后一条:早前用 `/tree` 切过分支时,被放弃的那条线上的用户消息不会被选中。注入的 `custom_message`、bash 结果、压缩摘要都不算“用户消息”。
|
|
93
|
+
|
|
94
|
+
**真删,不是旁支。** 该条及其之后的行会从会话 JSONL 里删掉(`header` 保留),随后用 `ctx.switchSession(同一文件)` 让宿主从文件重建会话。所以 `/tree` 里不会多出一条旁支,`/sessions` 里也不会多出一棵子树 —— 这正是它与 `/fork` 的区别:`/fork` 是新建子会话文件,`/undo` 是同一个文件往回退。
|
|
95
|
+
|
|
96
|
+
**限制。** 只在空闲时可用:正在生成回复、或还有排队的 steering/follow-up 消息时会直接拒绝并提示等待。回滚到第一条用户消息会让会话变成空会话(只剩 header),之后可以照常开始新的对话。被删的内容**不可恢复**,写盘顺序在保留点之后的兄弟分支(早前 `/tree` 留下的那条线)以及它们携带的改名、label 也会一并消失。
|
|
97
|
+
|
|
98
|
+
## 归档语义
|
|
99
|
+
|
|
100
|
+
**物理移动。** 归档把 `<agent>/sessions/<cwd-slug>/x.jsonl` 移到 `<agent>/sessions-archive/<cwd-slug>/x.jsonl`,取消归档做反向移动。归档状态只由目录位置推导,不写进会话文件,也不依赖索引。
|
|
101
|
+
|
|
102
|
+
**整棵子树。** 递归按会话 header 里的 `parentSession` 进行:父会话所在目录中,凡是 `parentSession` 指向该会话或其后代的 `.jsonl`,都属于这棵子树,归档时一律一起移动,避免在原生 `/resume` 里留下孤儿根节点。header 本身只有 `parentSession`,但文件内容能区分:fork/clone 复制父会话的 entry,所以首条非 header entry 的 `id` 与父会话相同;subagent 是全新 entry,`id` 不同(`inherit_context` 只是把父文本拼进 prompt,resume 复用 subagent 自己的文件,都不复制父 entry)。picker 用这个区别控制展开、搜索和 `Children` 预设,归档语义不受影响。恢复同样整棵移回;只恢复某个子会话时,父会话仍留在归档里,树形视图会按“孪生路径”继续把它挂在归档父节点下。**正在写入的会话除外**:当前会话的文件,以及它自己的派生会话,永远不随着祖先会话的归档而移动(连同伴生文件一起留在原地),否则 pi 会继续往旧路径写,会话就从 `/resume` 里消失了。
|
|
103
|
+
|
|
104
|
+
**当前会话延迟归档。** pi 还在写当前会话的文件,移动它会丢内容,因此:
|
|
105
|
+
|
|
106
|
+
- `/archive`、`archive_session` 工具、picker 里对当前会话按 `ctrl+a`,都只往 `<agent>/pi-sessions-state.json` 的 `pendingArchive[<sessionId>]` 写一条请求,并提示 `Session will be archived when it closes`。
|
|
107
|
+
- 真正移动发生在 `session_shutdown`:退出 pi、`/new`、切换到别的会话、`/fork` 都会触发;`/reload` 不移动(会话马上回来),切换目标恰好是同一个会话文件也不移动。切换或 `/fork` 的目标是当前会话的派生会话时,那个目标文件同样不移动(pi 正要继续写它),只移动当前会话本身。文件已归档或已不存在时只清掉请求;移动失败会通知错误并保留请求,便于下次重试。
|
|
108
|
+
- 移动成功后清掉请求。下次启动时若请求还在、而文件仍在活跃树,会继续武装(崩溃自愈);若文件已在归档树,则丢弃请求。
|
|
109
|
+
|
|
110
|
+
**目标文件已存在。** 归档时若归档位置已有同名文件,先判断它是否只是“尾巴”(没有 session header,且条目通过 `parentId` 接到归档副本上):是则把尾巴追加到归档副本并删除;否则把旧文件改名成 `<file>.superseded-<timestamp>` 保留,绝不覆盖。
|
|
111
|
+
|
|
112
|
+
**伴生文件。** 会话除了 `.jsonl` 还带有:同名目录(子代理运行、fork 等)、`.pi-agent-browser-artifacts/<sessionId>/`、`subagent-artifacts/` 下 `_meta.json` 的 `parentSessionId` 指向该会话的运行产物。它们随会话一起移动;某个伴生文件移动失败只会被跳过,目标已存在时保留原处。
|
|
113
|
+
|
|
114
|
+
**活跃副本优先。** 取消归档时若活跃树里已经有同名文件(归档后 pi 又写了活跃副本),不会移动任何东西,只提示 `A live copy already exists`,归档副本原样保留;用 `enter` 恢复则直接切到活跃副本。
|
|
115
|
+
|
|
116
|
+
**重命名与删除。** 重命名只往会话文件追加一条 `session_info`(当前会话走 `pi.setSessionName`),不改 header、不移动文件,归档会话同样可改。删除以选中行为根:整棵 `parentSession` 子树、它们的伴生文件、以及另一棵树里的同名孪生副本一起删,并清掉 `index.json` 与 `pendingArchive` 里对应的条目;当前会话拒绝删除,子树含当前会话时整体拒绝。整个集合(会话文件、伴生目录、截图、子代理产物)一次交给系统 `trash`;`trash` 不可用或失败时逐个回退为永久删除,所以伴生文件和会话一样可恢复。
|
|
117
|
+
|
|
118
|
+
**不做的事。** 不改写 `parentSession` 路径:父子链接在读取时按“孪生路径”解析。
|
|
119
|
+
|
|
120
|
+
## 归档布局
|
|
121
|
+
|
|
122
|
+
`<agent>` 默认是 `~/.pi/agent`,可用 `PI_CODING_AGENT_DIR` 覆盖;归档根目录始终是 `<agent>/sessions-archive/`。
|
|
123
|
+
|
|
124
|
+
```text
|
|
125
|
+
~/.pi/agent/
|
|
126
|
+
├─ sessions/<cwd-slug>/ # 活跃会话(pi 自己维护)
|
|
127
|
+
│ ├─ <timestamp>_<id>.jsonl
|
|
128
|
+
│ ├─ <timestamp>_<id>/ # 伴生目录(子代理运行、fork 等)
|
|
129
|
+
│ ├─ .pi-agent-browser-artifacts/<id>/ # agent-browser 截图,按会话 id
|
|
130
|
+
│ └─ subagent-artifacts/<run>_* # pi-subagents 运行产物
|
|
131
|
+
├─ sessions-archive/
|
|
132
|
+
│ ├─ <cwd-slug>/ # 与活跃目录一一对应
|
|
133
|
+
│ │ ├─ <timestamp>_<id>.jsonl
|
|
134
|
+
│ │ ├─ <timestamp>_<id>/
|
|
135
|
+
│ │ ├─ .pi-agent-browser-artifacts/<id>/
|
|
136
|
+
│ │ └─ subagent-artifacts/<run>_*
|
|
137
|
+
│ └─ index.json # 归档元数据(不是归档状态的依据)
|
|
138
|
+
└─ pi-sessions-state.json # 延迟归档队列
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
`<cwd-slug>` 与 pi 的会话目录命名一致:`--` + 工作目录去掉开头的 `/`、把 `/` 和 `:` 换成 `-` + `--`。例如 `/home/sion/dev/pi-extensions` → `--home-sion-dev-pi-extensions--`。
|
|
142
|
+
|
|
143
|
+
`index.json` 以会话文件相对 `sessions-archive/` 的路径为键:
|
|
144
|
+
|
|
145
|
+
```json
|
|
146
|
+
{
|
|
147
|
+
"--home-sion-dev-pi-extensions--/2026-11-16T15-43-01-628Z_<id>.jsonl": {
|
|
148
|
+
"name": "会话名",
|
|
149
|
+
"cwd": "/home/sion/dev/pi-extensions",
|
|
150
|
+
"archivedAt": "2026-11-16T15:50:00.000Z",
|
|
151
|
+
"id": "<id>"
|
|
152
|
+
}
|
|
153
|
+
}
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
| 字段 | 类型 | 说明 |
|
|
157
|
+
| --- | --- | --- |
|
|
158
|
+
| 键 | string | `<cwd-slug>/<file>.jsonl`,相对归档根目录 |
|
|
159
|
+
| `name` | string | 归档时的会话名;未命名为 `""`;派生会话条目固定为 `""` |
|
|
160
|
+
| `cwd` | string | header 里的 `cwd`,缺失为 `""` |
|
|
161
|
+
| `archivedAt` | string | ISO 时间戳,`/sessions` 用它显示归档时间 |
|
|
162
|
+
| `id` | string? | header 里的会话 id,可选(旧数据可能没有) |
|
|
163
|
+
|
|
164
|
+
`/sessions` 只用到 `archivedAt`,缺失或索引损坏时回退到 `SessionInfo.modified`(最后消息时间);`name`、`cwd`、`id` 仅作记录(标题始终取自会话文件本身)。
|
|
165
|
+
|
|
166
|
+
`pi-sessions-state.json` 只保存延迟归档请求:
|
|
167
|
+
|
|
168
|
+
```json
|
|
169
|
+
{
|
|
170
|
+
"pendingArchive": {
|
|
171
|
+
"<session-id>": {
|
|
172
|
+
"path": "/home/sion/.pi/agent/sessions/--x--/<file>.jsonl",
|
|
173
|
+
"cwd": "/x",
|
|
174
|
+
"requestedAt": "2026-11-16T15:50:00.000Z"
|
|
175
|
+
}
|
|
176
|
+
}
|
|
177
|
+
}
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
## 限制
|
|
181
|
+
|
|
182
|
+
- **自定义会话目录不参与**:用 `--session-dir`、`PI_CODING_AGENT_SESSION_DIR` 或 `sessionDir` 设置把会话放到 `<agent>/sessions/` 之外的,不会出现在 `/sessions`,也不能被归档或恢复(原生 `/resume` 仍可见);`/archive` 与 `archive_session` 工具会提示该会话无法归档,不会留下永远执行不了的延迟请求。归档根目录始终是 `<agent>/sessions-archive/`。
|
|
183
|
+
- **跨目录派生会话不会递归带走**:递归只扫描父会话所在目录的 `*.jsonl`。若子代理会话写到了别的工作目录,它不会被一起归档,会继续以孤儿根节点出现在原生 `/resume` 里。
|
|
184
|
+
- **另一个 pi 实例正在使用的会话不要归档**:插件不检测会话是否被其他实例占用。归档一个正在被写入的会话可能丢掉尚未落盘的内容。
|
|
185
|
+
- **多实例并发写**:`index.json` 与 `pi-sessions-state.json` 都是读-改-写加原子替换,并发时是 last-write-wins,后写的一方会覆盖先写条目的修改。同一时段最好只用一实例执行归档。
|
|
186
|
+
- **同 id 的重复副本只显示一行**:会话既在活跃树又有归档副本时(归档后 pi 仍写了活跃文件),活跃副本优先,归档副本暂时隐藏,活跃副本消失后重新出现。
|
|
187
|
+
- **`.superseded-*` 不自动清理**:被替换下来的旧归档文件需要手动删除。
|
|
188
|
+
- **删除不可撤销**:插件没有自己的回收站,整批路径(会话文件、孪生副本、伴生目录、截图、子代理产物)一次交给系统 `trash`;`trash` 不存在或返回失败时全部回退为永久删除,此时无法恢复。删除同样不检测其他 pi 实例是否正在使用该会话。
|
|
189
|
+
- **非 TUI 模式没有重命名与删除**:`ctx.ui.select` 的扁平列表只能选择恢复;需要在列表里改名或删除请用原生 `/resume`,本插件不提供 `/rename`、`/delete` 命令。
|
|
190
|
+
- **`/undo` 会真的删掉尾部**:它是物理截断而不是 `/tree` 式旁支,被回滚的那一轮(以及写盘顺序在保留点之后的其它分支、改名、label)不可恢复;编辑器里已有草稿时不写回原文。请在空闲时使用。
|
|
191
|
+
|
|
192
|
+
## 隐私
|
|
193
|
+
|
|
194
|
+
插件不发起任何网络请求,也没有遥测。它只读写本机 `<agent>` 下的会话文件、`sessions-archive/` 与 `pi-sessions-state.json`;搜索完全在本地进行。归档/恢复是本地文件移动,不会上传或复制会话内容到别处。
|
|
195
|
+
|
|
196
|
+
## 从 `pi-session-archive` 迁移
|
|
197
|
+
|
|
198
|
+
1. **先移除旧包**,避免两个插件同时移动同一批文件(双重归档):
|
|
199
|
+
|
|
200
|
+
```bash
|
|
201
|
+
pi remove npm:@clementprevot/pi-session-archive
|
|
202
|
+
```
|
|
203
|
+
|
|
204
|
+
若当初是用本地路径或 git 来源安装的,把来源换成当初写入设置的那一个。
|
|
205
|
+
|
|
206
|
+
2. **旧归档无需转换**:目录布局相同(都是 `sessions-archive/<cwd-slug>/`),`index.json` 字段兼容;新插件只读取 `archivedAt`,缺字段或损坏时回退到 `SessionInfo.modified`(最后消息时间)。
|
|
207
|
+
3. **旧标签展示时清理**:旧插件给未命名会话写过 `[ARCHIVE] ` 前缀名称,甚至只写一个裸的 `[ARCHIVE]`。新插件展示时会去掉名称开头的一个或多个 `[ARCHIVE]` 标签,结果为空则显示首条消息(在“只看命名会话”过滤下,这类只剩标签的会话被视为未命名)。
|
|
208
|
+
4. **恢复时剥除标签**:恢复归档会话时,如果文件里最后一个 `session_info` 的名称以 `[ARCHIVE]` 开头(可带空白、可重复),会把开头这些标签去掉后再写回(临时文件 + rename),免得下次关闭又被当成旧归档重复处理;没有标签的名称保持原样。
|
|
209
|
+
5. **旧插件已打标签但未移动的会话**:这些文件仍留在活跃树里,新插件不会因为看到标签就把它们当已归档。请在 `/sessions` 里对它们重新归档一次(`ctrl+a`)。
|
|
210
|
+
6. **命令兼容**:`archive_session` 工具名与 `/archive` 命令保持不变,agent 侧提示词无需修改;`/archives` 不再存在,改用 `/sessions`。
|
|
211
|
+
|
|
212
|
+
## 开发
|
|
213
|
+
|
|
214
|
+
```bash
|
|
215
|
+
nix develop # Node.js 24 + git 的 devShell
|
|
216
|
+
npm ci # 安装依赖
|
|
217
|
+
npm test # node --test,运行所有包的测试
|
|
218
|
+
npm run typecheck # tsc --noEmit
|
|
219
|
+
```
|
|
220
|
+
|
|
221
|
+
也可以不进入 shell 直接执行:`nix develop -c npm test`。
|
|
222
|
+
|
|
223
|
+
若宿主导出了 `NODE_ENV=production`,`npm install` 会跳过 devDependencies,导致 `tsc` 与测试缺失,去掉该变量即可:
|
|
224
|
+
|
|
225
|
+
```bash
|
|
226
|
+
nix develop -c env -u NODE_ENV npm install
|
|
227
|
+
```
|
|
228
|
+
|
|
229
|
+
源码结构:
|
|
230
|
+
|
|
231
|
+
| 文件 | 职责 |
|
|
232
|
+
| --- | --- |
|
|
233
|
+
| `src/index.ts` | 扩展入口:注册命令、工具与 `session_start` / `session_shutdown` 钩子 |
|
|
234
|
+
| `src/commands.ts` | `/sessions` 命令、picker 接线、归档/恢复动作与提示文案 |
|
|
235
|
+
| `src/picker.ts` | TUI picker 组件:渲染与按键映射,不碰文件系统 |
|
|
236
|
+
| `src/picker-state.ts` | 与界面无关的选择状态机:筛选、排序、作用域、展开、归档动作判定 |
|
|
237
|
+
| `src/sessions.ts` | 加载活跃与归档会话、合并去重、按 `parentSession` 建树 |
|
|
238
|
+
| `src/archive.ts` | 文件级原语:子树发现、伴生文件、尾部续写、标签剥除、整树归档/恢复 |
|
|
239
|
+
| `src/paths.ts` | 路径、目录名、标题与 session header 读取 |
|
|
240
|
+
| `src/state.ts` | `index.json` 与 `pi-sessions-state.json` 的读写 |
|
|
241
|
+
| `src/search.ts` | 查询解析与相关性排序 |
|
|
242
|
+
| `src/undo.ts` | `/undo` 的目标选择、会话文件截断与重载 |
|
|
243
|
+
| `src/types.ts` | 共享类型 |
|
|
244
|
+
|
|
245
|
+
## 手动验收清单
|
|
246
|
+
|
|
247
|
+
自动化测试覆盖了纯逻辑、文件移动与命令层;以下交互步骤需要真实终端与模型会话,发布前请手动确认:
|
|
248
|
+
|
|
249
|
+
1. `nix develop -c pi -e ./packages/pi-sessions` 启动后,`/sessions` 能打开 picker,原生 `/resume` 仍可用。
|
|
250
|
+
2. 在一个测试项目里新建会话并对话,`/sessions` 选中它按 `ctrl+a` → 提示 `Session will be archived when it closes`;退出 pi 后文件从 `~/.pi/agent/sessions/<cwd-slug>/` 移到 `~/.pi/agent/sessions-archive/<cwd-slug>/`,`index.json` 出现该条目且 `archivedAt` 为当前时间。
|
|
251
|
+
3. 在同一目录重新启动 pi,`/sessions` 按 `ctrl+t` 切到 `archived` 能看到该行(带 `[archived]`);按 `enter` 后文件回到 `sessions/<cwd-slug>/`,界面切到该会话。
|
|
252
|
+
4. 归档当前会话后执行 `/reload`:文件不移动,`pi-sessions-state.json` 里的 `pendingArchive` 仍在;之后退出 pi(或 `/new`、切换到别的会话)才移动。
|
|
253
|
+
5. 未命名会话:不带 `/name` 建会话,从 picker 归档并退出;归档文件与 `index.json` 中不出现 `[ARCHIVE]`,picker 与原生 `/resume` 里显示的首条消息为标题。
|
|
254
|
+
6. 派生会话:用 `pi-subagents` 跑一个子代理会话或执行 `/fork`,再对父会话 `ctrl+a` → 确认框显示派生会话数;归档后父与子的 `.jsonl` 都在 `sessions-archive/<cwd-slug>/`,原生 `/resume` 里不再出现孤立子会话。
|
|
255
|
+
7. 重命名:在归档行按 `ctrl+r` 改名并 `enter`,列表标题立即更新;`enter` 恢复后标题仍是新名字(`session_info` 追加在归档文件里,文件没有移动)。
|
|
256
|
+
8. 删除:选中一个带 fork / subagent 子会话的父会话按 `ctrl+d` → 确认行显示 `Delete this session and N child sessions?`;确认后父与子的 `.jsonl`、伴生目录一并消失,同目录的兄弟会话仍在,`index.json` 里对应条目被摘掉。
|
|
257
|
+
|
|
258
|
+
## License
|
|
259
|
+
|
|
260
|
+
MIT,见 [`LICENSE`](LICENSE)。
|
|
261
|
+
|
|
262
|
+
归档目录布局、伴生文件处理、尾部续写合并与旧标签剥除改编自 [`@clementprevot/pi-session-archive`](https://github.com/clementprevot/pi-session-archive)(MIT,Copyright (c) 2026 Clément Prévot),完整声明见包内 [`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md)。本项目与上游作者没有隶属或背书关系。
|
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
# 第三方声明
|
|
2
|
+
|
|
3
|
+
> 本文件是仓库根目录同名 `THIRD_PARTY_NOTICES.md` 的包内副本:随 npm 包发布,确保改编代码在分发时一并带上上游的版权与许可声明。两份内容保持一致,修改时请同步。
|
|
4
|
+
|
|
5
|
+
本项目(`@sion10032/pi-sessions`)的部分实现改编自下列作品。
|
|
6
|
+
|
|
7
|
+
## pi-session-archive
|
|
8
|
+
|
|
9
|
+
| 项目 | 内容 |
|
|
10
|
+
| --- | --- |
|
|
11
|
+
| 名称 | `pi-session-archive`(npm:`@clementprevot/pi-session-archive`) |
|
|
12
|
+
| 作者 / 版权 | Copyright (c) 2026 Clément Prévot |
|
|
13
|
+
| 许可证 | MIT |
|
|
14
|
+
| 来源 | https://github.com/clementprevot/pi-session-archive |
|
|
15
|
+
|
|
16
|
+
改编自该作品的部分:
|
|
17
|
+
|
|
18
|
+
- 归档目录布局:`~/.pi/agent/sessions-archive/<cwd-slug>/` 下按 cwd 分组的会话文件,以及 `index.json` 元数据格式。
|
|
19
|
+
- 会话伴生文件的查找与移动:`<session>/` 目录、`.pi-agent-browser-artifacts/<id>`、`subagent-artifacts/` 下的运行产物。
|
|
20
|
+
- 归档目标文件已存在时的处理:能接上的“尾部续写”(tail continuation)合并,以及否则改名为 `.superseded-<timestamp>` 保留旧文件。
|
|
21
|
+
- 旧版 `[ARCHIVE] ` 名称标签的处理:展示时清理,恢复时从会话文件中剥除。
|
|
22
|
+
|
|
23
|
+
本项目在此基础上增加了整棵 `parentSession` 子树(子代理会话与 fork)的递归归档与恢复、`/sessions` 统一浏览界面,以及当前会话的延迟归档;这些为新增实现,不来自上游。
|
|
24
|
+
|
|
25
|
+
本项目为独立项目,与上述作品的作者没有隶属、赞助或背书关系。上游作者不对本项目的使用或缺陷承担任何责任。
|
|
26
|
+
|
|
27
|
+
以下为该作品的 MIT 许可证全文,作为署名与许可声明保留。
|
|
28
|
+
|
|
29
|
+
---
|
|
30
|
+
|
|
31
|
+
MIT License
|
|
32
|
+
|
|
33
|
+
Copyright (c) 2026 Clément Prévot
|
|
34
|
+
|
|
35
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
36
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
37
|
+
in the Software without restriction, including without limitation the rights
|
|
38
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
39
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
40
|
+
furnished to do so, subject to the following conditions:
|
|
41
|
+
|
|
42
|
+
The above copyright notice and this permission notice shall be included in all
|
|
43
|
+
copies or substantial portions of the Software.
|
|
44
|
+
|
|
45
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
46
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
47
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
48
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
49
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
50
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
51
|
+
SOFTWARE.
|
package/package.json
CHANGED
|
@@ -1,6 +1,22 @@
|
|
|
1
1
|
{
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
2
|
+
"name": "@sion10032/pi-sessions",
|
|
3
|
+
"version": "0.2.0",
|
|
4
|
+
"description": "Browse, archive, restore and resume pi sessions, including their subagent sessions",
|
|
5
|
+
"keywords": ["pi-package", "pi-extension", "session", "archive", "resume"],
|
|
6
|
+
"license": "MIT",
|
|
7
|
+
"repository": {
|
|
8
|
+
"type": "git",
|
|
9
|
+
"url": "git+https://github.com/Sion10032/pi-extensions.git",
|
|
10
|
+
"directory": "packages/pi-sessions"
|
|
11
|
+
},
|
|
12
|
+
"type": "module",
|
|
13
|
+
"engines": { "node": ">=22.19" },
|
|
14
|
+
"files": ["src", "THIRD_PARTY_NOTICES.md"],
|
|
15
|
+
"pi": { "extensions": ["./src/index.ts"] },
|
|
16
|
+
"peerDependencies": {
|
|
17
|
+
"@earendil-works/pi-coding-agent": "*",
|
|
18
|
+
"@earendil-works/pi-tui": "*",
|
|
19
|
+
"typebox": "*"
|
|
20
|
+
},
|
|
21
|
+
"publishConfig": { "access": "public" }
|
|
22
|
+
}
|