pi-wechat-session-hub 0.1.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 +661 -0
- package/README.md +365 -0
- package/docs/decisions/0001-ilink-context-token-queue.md +41 -0
- package/docs/handoff-next-session.md +134 -0
- package/docs/implementation-spec.md +147 -0
- package/extensions/wechat-session-hub.ts +589 -0
- package/package.json +67 -0
- package/scripts/pi-rpc-smoke.mjs +150 -0
- package/scripts/probe-wt-capability.mjs +27 -0
- package/scripts/start-ui-worker.ps1 +37 -0
- package/src/commands/ilink-qr-login-component.ts +148 -0
- package/src/commands/project-command-parser.ts +108 -0
- package/src/commands/tokenizer.ts +71 -0
- package/src/commands/wechat-manager-command-parser.ts +143 -0
- package/src/config/defaults.ts +30 -0
- package/src/config/paths.ts +56 -0
- package/src/config/store.ts +311 -0
- package/src/config/types.ts +33 -0
- package/src/config/validation.ts +221 -0
- package/src/gateway/channel-types.ts +47 -0
- package/src/gateway/command-parser.ts +291 -0
- package/src/gateway/command-router.ts +1449 -0
- package/src/gateway/credential-store.ts +611 -0
- package/src/gateway/durable-message-queue.ts +1043 -0
- package/src/gateway/gateway-control-ipc.ts +687 -0
- package/src/gateway/gateway-runtime.ts +726 -0
- package/src/gateway/ui-worker-extension-bridge.ts +1070 -0
- package/src/gateway/ui-worker-ipc.ts +1483 -0
- package/src/gateway/ui-worker-types.ts +50 -0
- package/src/gateway/wechat-ilink/api-client.ts +390 -0
- package/src/gateway/wechat-ilink/channel-adapter.ts +320 -0
- package/src/gateway/wechat-ilink/cursor-store.ts +134 -0
- package/src/gateway/wechat-ilink/qr-login.ts +612 -0
- package/src/gateway/wechat-ilink/typing-indicator.ts +133 -0
- package/src/gateway/windows-terminal-launcher.ts +247 -0
- package/src/projects/project-service.ts +483 -0
- package/src/registry/gateway-lease.ts +348 -0
- package/src/registry/manager-registry.ts +466 -0
- package/src/registry/types.ts +61 -0
- package/src/runtime/background-pi-worker.ts +309 -0
- package/src/runtime/background-worker-manager.ts +594 -0
- package/src/runtime/gateway-daemon.ts +281 -0
- package/src/runtime/gateway-lifecycle-operation.ts +308 -0
- package/src/runtime/gateway-service-controller.ts +339 -0
- package/src/runtime/gateway-worker-manager.ts +181 -0
- package/src/runtime/pi-cli.ts +56 -0
- package/src/runtime/pi-rpc-client.ts +427 -0
- package/src/runtime/ui-worker-manager.ts +1186 -0
- package/src/runtime/windows-logon-task-manager.ts +212 -0
- package/src/system/process-liveness.ts +88 -0
- package/tsconfig.json +19 -0
package/README.md
ADDED
|
@@ -0,0 +1,365 @@
|
|
|
1
|
+
# Pi 微信会话枢纽
|
|
2
|
+
|
|
3
|
+
[](https://www.npmjs.com/package/pi-wechat-session-hub)
|
|
4
|
+
[](LICENSE)
|
|
5
|
+
[](package.json)
|
|
6
|
+
[](https://github.com/yangfeng20/pi-wechat-session-hub/actions/workflows/pi-compat.yml)
|
|
7
|
+
|
|
8
|
+
Pi WeChat Session Hub 是一个 Pi 扩展, 用微信管理本机多个 Pi 会话. Gateway 在独立后台进程中运行, 不依赖启动命令所在的 Pi TUI.
|
|
9
|
+
|
|
10
|
+
关闭所有 Pi TUI 后, 后台服务仍可通过微信收发消息; 在 Pi TUI 中用 `/resume` 恢复受管会话时, 会自动完成前后台 owner 交接, 微信消息随即进入可见终端.
|
|
11
|
+
|
|
12
|
+
## 目录
|
|
13
|
+
|
|
14
|
+
- [特性](#特性)
|
|
15
|
+
- [系统要求](#系统要求)
|
|
16
|
+
- [安装](#安装)
|
|
17
|
+
- [首次使用](#首次使用)
|
|
18
|
+
- [架构与会话行为](#架构与会话行为)
|
|
19
|
+
- [本机命令](#本机命令)
|
|
20
|
+
- [微信端命令](#微信端命令)
|
|
21
|
+
- [在微信端找回上下文](#在微信端找回上下文)
|
|
22
|
+
- [配置](#配置)
|
|
23
|
+
- [安全与运行边界](#安全与运行边界)
|
|
24
|
+
- [常见问题](#常见问题)
|
|
25
|
+
- [开发与验证](#开发与验证)
|
|
26
|
+
- [许可证](#许可证)
|
|
27
|
+
|
|
28
|
+
## 特性
|
|
29
|
+
|
|
30
|
+
- 微信远程下发任务, 由本机 Pi 执行, 结果回到微信
|
|
31
|
+
- 会话常驻: Pi TUI 全部关闭后仍可在微信继续对话
|
|
32
|
+
- 前后台自动交接: TUI 打开即接管, TUI 关闭即交回后台, 始终只有一个 writer
|
|
33
|
+
- 多项目多会话: 每个项目可开多个会话, 稳定数字索引 + 会话名即可切换
|
|
34
|
+
- 恢复上下文: `/last` 只读回顾最近一轮对话, 不调模型不耗 token
|
|
35
|
+
- 严格安全边界: 授权根目录白名单, 未知命令 fail-closed, 审计不记录正文与凭证
|
|
36
|
+
|
|
37
|
+
## 系统要求
|
|
38
|
+
|
|
39
|
+
| 项 | 要求 | 说明 |
|
|
40
|
+
|---|---|---|
|
|
41
|
+
| 操作系统 | **Windows** | 可见 UI 模式依赖 Windows Terminal 与 Windows 登录计划任务 |
|
|
42
|
+
| Node.js | `>= 22.19.0` | 与 `package.json` 的 `engines` 一致 |
|
|
43
|
+
| Pi | `>= 0.85.1 < 2.0.0` | CI 矩阵覆盖 `0.85.1` / `1.0.0` / `1.3.0` |
|
|
44
|
+
| Windows Terminal | 建议安装 | 缺少 `wt.exe` 时阻塞可见 UI 操作, 后台模式仍可用 |
|
|
45
|
+
| PowerShell 7 | 建议安装 | 可见 UI tab 通过 `pwsh.exe` 启动固定脚本 |
|
|
46
|
+
| 微信 | iLink 能力账号 | 需能通过 `/wx login` 扫码授权 |
|
|
47
|
+
|
|
48
|
+
CI 在 `ubuntu-latest` 上跑 Pi 三版本兼容矩阵, 在 `windows-latest` 上额外覆盖 `0.85.1` 与 `1.3.0` 并验证真实平台的 `wt.exe` 探测逻辑.
|
|
49
|
+
|
|
50
|
+
### 平台限制的实际影响
|
|
51
|
+
|
|
52
|
+
非 Windows 平台, 或 Windows 上找不到 `wt.exe` 时:
|
|
53
|
+
|
|
54
|
+
- 扩展本身可以加载, `/wx login`、`/wx start`、`/wx status` 等本机命令可用
|
|
55
|
+
- 后台模式会话(`/new` 默认模式)完全可用
|
|
56
|
+
- **可见 UI 模式会被阻塞**: 微信端 `/new --mode ui`、`/resume` 到 UI 会话、`/wx autostart on` 都会返回明确原因并拒绝执行, 不会静默降级或产生半启动状态
|
|
57
|
+
- `/wx status` 与微信端 `/status` 会单独显示 `可见 UI 模式: 不可用 (原因)`, 便于提前判断
|
|
58
|
+
|
|
59
|
+
阻塞点位于 UI worker 启动前的平台与 `wt.exe` 能力校验, 因此不会留下孤儿窗口或双 writer. 失败结果不缓存, 安装 Windows Terminal 后无需重启 daemon 即可重试.
|
|
60
|
+
|
|
61
|
+
## 安装
|
|
62
|
+
|
|
63
|
+
### 方式一: 从官方渠道安装(推荐普通用户)
|
|
64
|
+
|
|
65
|
+
Pi 会从 npm 或 git 拉取包并自动安装依赖, 扩展注册到用户级配置.
|
|
66
|
+
|
|
67
|
+
```bash
|
|
68
|
+
# 从 npm 安装, 最省事, 版本可追
|
|
69
|
+
pi install npm:pi-wechat-session-hub
|
|
70
|
+
|
|
71
|
+
# 固定版本, 避免升级带来的行为差异
|
|
72
|
+
pi install npm:pi-wechat-session-hub@0.1.0
|
|
73
|
+
|
|
74
|
+
# 从 GitHub 安装, 跟随默认分支, 适合追最新提交
|
|
75
|
+
pi install git:github.com/yangfeng20/pi-wechat-session-hub
|
|
76
|
+
|
|
77
|
+
# 固定到 tag 或 commit
|
|
78
|
+
pi install git:github.com/yangfeng20/pi-wechat-session-hub@v0.1.0
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
安装后:
|
|
82
|
+
|
|
83
|
+
```bash
|
|
84
|
+
pi list # 确认已在已安装包列表中
|
|
85
|
+
pi update --all # 升级 Pi 与该包
|
|
86
|
+
pi remove npm:pi-wechat-session-hub # 卸载 npm 版本
|
|
87
|
+
pi remove git:github.com/yangfeng20/pi-wechat-session-hub # 卸载 git 版本
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
> 只装到当前项目而非全局时, 在任意命令后加 `-l`, 包会写入 `.pi/settings.json`.
|
|
91
|
+
|
|
92
|
+
想临时试听不落盘, 用 `-e` 单次加载:
|
|
93
|
+
|
|
94
|
+
```bash
|
|
95
|
+
pi -e npm:pi-wechat-session-hub
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
### 方式二: 从源码本地开发安装
|
|
99
|
+
|
|
100
|
+
适合二次开发、调试与提交 PR.
|
|
101
|
+
|
|
102
|
+
```bash
|
|
103
|
+
git clone https://github.com/yangfeng20/pi-wechat-session-hub.git
|
|
104
|
+
cd pi-wechat-session-hub
|
|
105
|
+
npm install
|
|
106
|
+
npm run typecheck
|
|
107
|
+
npm test
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
三种加载方式, 按调试需求选择:
|
|
111
|
+
|
|
112
|
+
```bash
|
|
113
|
+
# A. 单次加载, 不改动任何设置, 最轻量
|
|
114
|
+
pi --extension ./extensions/wechat-session-hub.ts
|
|
115
|
+
|
|
116
|
+
# B. 把当前目录注册为本地包, 之后启动即生效(路径不会被复制)
|
|
117
|
+
pi install /absolute/path/to/pi-wechat-session-hub
|
|
118
|
+
|
|
119
|
+
# C. 项目级注册, 只对当前仓库生效
|
|
120
|
+
pi install -l .
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
方式 B/C 下修改源码后需要 `/reload` 或重启 Pi TUI; 若修改的是后台 daemon 代码, 还需 `/wx restart` 让新 daemon 生效.
|
|
124
|
+
|
|
125
|
+
## 首次使用
|
|
126
|
+
|
|
127
|
+
Node.js 需满足 `package.json` 中的最低版本. 首次使用顺序:
|
|
128
|
+
|
|
129
|
+
1. 在 Pi TUI 执行 `/wx login` 扫码授权.
|
|
130
|
+
2. 在 Pi TUI 执行 `/wx start` 启动后台服务. 如果 `allowedProjectRoots` 为空, Hub 会将当前 session 的 cwd 设为初始授权根, 并自动建立项目记录和默认项目.
|
|
131
|
+
3. 授权根内打开的 Pi session 会按当前文件夹名自动识别, 不需要逐个 `/projects add`. 如果后续要授权其他目录, 在本机 TUI 执行 `/wx roots add-current`, 或用 `/wx roots add <绝对路径>` 添加工作区根目录.
|
|
132
|
+
|
|
133
|
+
盘符根目录和用户主目录等过宽范围会要求本机确认. 授权根外的 Pi session 仍可在本机使用, 但不会接入 Hub; TUI 会提示如何添加授权根. Hub 不会扫描其他 session 文件.
|
|
134
|
+
|
|
135
|
+
配置和授权凭证保存在用户专属 Hub 目录, 仓库不包含账号凭证或授权 ID.
|
|
136
|
+
|
|
137
|
+
## 架构与会话行为
|
|
138
|
+
|
|
139
|
+
```text
|
|
140
|
+
任意 Pi TUI
|
|
141
|
+
/wx start|status|stop|restart
|
|
142
|
+
│ 本机 HMAC IPC
|
|
143
|
+
▼
|
|
144
|
+
独立 Hub daemon
|
|
145
|
+
├─ 微信 iLink 长轮询、鉴权、route、持久队列
|
|
146
|
+
└─ 每个会话唯一 writer
|
|
147
|
+
├─ Pi TUI 正在打开该会话: 消息进入前台并回显
|
|
148
|
+
└─ 没有活跃 TUI owner: Pi RPC 后台处理
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
- `/wx start` 启动共享 daemon, 不绑定当前 Pi session. 关闭所有 Pi TUI 后, daemon 仍可通过微信收发消息.
|
|
152
|
+
- 每条微信 route 指向同一 Pi session. 在 Pi TUI 中 `/resume` 恢复 Hub 管理的会话时, 扩展通过 IPC 将 owner 从后台 RPC 安全切换到前台 TUI; 同一会话的微信消息和回复会在该 TUI 中显示. TUI 关闭后, route 返回后台 RPC.
|
|
153
|
+
- 新建微信会话默认在后台, 不自动打开 Windows Terminal tab. route、session JSONL 和稳定会话索引保留.
|
|
154
|
+
- 同一 session 同一时刻只允许一个 runtime writer. Pi TUI session 的 cwd 位于 `allowedProjectRoots` 内时会自动登记并纳入 Hub; 授权根外的会话仍可在本机使用, 但不接入微信管理.
|
|
155
|
+
- 当前 Pi TUI 已成功接入 Hub 时, footer 的扩展状态行会在 MCP 状态后显示 `🟢 微信: 已接入`; Gateway 重启或连接恢复期间显示 `🟡 微信: 连接中`, 确认未接入时显示 `⚪ 未接入`.
|
|
156
|
+
- Gateway 进程在线不代表当前 TUI 已接入. `/wx status` 会单独展示当前终端的接入状态、实例 ID、上次接入时间、重连失败次数和断开原因, 便于区分是全局服务问题还是本终端连接问题. 会话切换导致 owner 释放后, bridge 会自动重建 registration 并恢复接入, 不需要重启 TUI.
|
|
157
|
+
|
|
158
|
+
## 本机命令
|
|
159
|
+
|
|
160
|
+
输入 `/wx` 并回车会打开交互式操作菜单; 输入 `/wx ` 可补全子命令. `/wechat-manager` 是兼容别名. Pi 本机的 Hub 命令统一位于 `/wx` 下, 不会注册全局 `/help`、`/projects` 或 `/status`.
|
|
161
|
+
|
|
162
|
+
| 命令 | 行为 |
|
|
163
|
+
|---|---|
|
|
164
|
+
| `/wx login` | 在本地 TUI 扫码, create-only 写入 Hub 自己的凭证 |
|
|
165
|
+
| `/wx start` | 幂等启动独立后台 Gateway; 首次使用时初始化当前目录授权 |
|
|
166
|
+
| `/wx status` | 查询后台连接、PID、会话数、项目和授权根目录, 当前终端自身的接入状态, 以及可见 UI 模式可用性 |
|
|
167
|
+
| `/wx roots` | 查看本机授权根目录 |
|
|
168
|
+
| `/wx roots add-current` | 授权当前 Pi session 目录及其子目录, 并接入当前会话 |
|
|
169
|
+
| `/wx roots add <绝对路径>` | 在本地 TUI 授权一个工作区根目录 |
|
|
170
|
+
| `/wx projects` | 查看自动识别和手动登记的项目 |
|
|
171
|
+
| `/wx stop` | 弹出二次确认; 确认后停止接收新消息并安全收尾 |
|
|
172
|
+
| `/wx restart` | 安全重启后台 Gateway, 等待新服务就绪; 服务已停止时启动服务 |
|
|
173
|
+
| `/wx autostart on` | 开启 Windows 当前用户登录后自动连接 |
|
|
174
|
+
| `/wx autostart off` | 关闭并移除 Windows 登录任务 |
|
|
175
|
+
| `/wx help` | 查看本机命令帮助 |
|
|
176
|
+
|
|
177
|
+
停止时, Gateway 先停止接收新微信消息, 再 drain 已入队 route 工作并等待正在处理的 Pi turn 收尾. `/wx stop` 在后台收尾期间提示"正在停止", 完成后再通知最终状态. `/wx restart` 会安全停止旧后台进程并启动新进程, 等待新服务就绪或报告失败; 它不会启动新旧并行 poller. 如果 daemon 非正常退出, durable queue 会保留未完成项并阻断后续 FIFO, 需要显式 `/retry <message-id> --confirm`.
|
|
178
|
+
|
|
179
|
+
Windows 自动启动默认关闭; 开启后在当前用户登录 Windows 时使用已保存授权连接. 它不在 Windows 登录桌面前运行, 也不会在启动时弹出扫码窗口. 如果尚未完成微信授权或授权失效, 需要先在 Pi TUI 执行 `/wx login`. 非 Windows 平台执行 `/wx autostart on` 会被明确拒绝.
|
|
180
|
+
|
|
181
|
+
## 微信端命令
|
|
182
|
+
|
|
183
|
+
未知 slash command fail-closed, 不会任意透传 Pi 内置命令, 也不接受用户提供的 shell 或文件路径.
|
|
184
|
+
|
|
185
|
+
```text
|
|
186
|
+
/new [--mode background|ui] [--project <alias>] [--name <名称>]
|
|
187
|
+
/sessions [--project <alias>] [--state active|saved|pending|all] [--page <n>]
|
|
188
|
+
/resume <会话索引|名称>
|
|
189
|
+
/last [会话索引|名称]
|
|
190
|
+
/stop [会话索引|名称]
|
|
191
|
+
/retry <message-id> --confirm
|
|
192
|
+
/status
|
|
193
|
+
/projects
|
|
194
|
+
/help
|
|
195
|
+
```
|
|
196
|
+
|
|
197
|
+
| 命令 | 是否改变状态 | 作用 |
|
|
198
|
+
|---|---|---|
|
|
199
|
+
| `/new` | 是 | 新建会话并绑定当前微信 route |
|
|
200
|
+
| `/sessions` | 否 | 分页列出 Hub 管理的会话 |
|
|
201
|
+
| `/resume` | 是 | 把当前微信 route 切到目标会话 |
|
|
202
|
+
| `/last` | **否** | 只读回顾目标会话最近一轮对话 |
|
|
203
|
+
| `/stop` | 是 | 停止目标会话的 Pi worker |
|
|
204
|
+
| `/retry` | 是 | 重新执行指定消息, 可能产生副作用 |
|
|
205
|
+
| `/status` | 否 | 展示 Hub、当前会话与 UI 模式可用性 |
|
|
206
|
+
| `/projects` | 否 | 列出已登记项目 |
|
|
207
|
+
| `/help` | 否 | 查看命令帮助 |
|
|
208
|
+
|
|
209
|
+
`/new` 默认在后台创建会话, 也可显式使用 `/new --mode ui` 在新 Windows Terminal tab 中创建可见 UI 会话. `/sessions` 默认列出 Hub 管理的全部活跃前台和后台会话, 每页 5 条, 每个会话单独展示标题、项目、模式和状态, 当前微信路由会明确标记. 标题优先显示 session name; 未命名时使用 Pi `/resume` 同样采用的首条用户文本, 最长 32 个 Unicode 字符, 超出以 `...` 省略. `/resume 3` 把微信 route 切换到索引为 `3` 的会话. 如果切换目标的 agent 已处于 idle, 回复会附带最近一次回复预览; 超过 800 个 Unicode 字符时只显示开头并提示完整内容仍在会话中. 如果 agent 正在运行, 只确认切换, 不发送旧回复. 索引在会话排序变化后保持不变, 不因列表重排而复用.
|
|
210
|
+
|
|
211
|
+
`/status` 会额外输出 `可见 UI 模式` 一行; 平台不支持或缺少 `wt.exe` 时显示 `不可用` 及具体原因.
|
|
212
|
+
|
|
213
|
+
## 在微信端找回上下文
|
|
214
|
+
|
|
215
|
+
从 PC TUI 切换到手机微信时, 往往不知道会话进行到哪里了. 补一条消息又可能让 agent 白跑一轮, 因此 `/last` 提供纯只读的上下文回顾:
|
|
216
|
+
|
|
217
|
+
```text
|
|
218
|
+
/last 查看当前微信路由会话的最近一轮对话
|
|
219
|
+
/last 3 查看索引为 3 的会话最近一轮对话
|
|
220
|
+
/last "调查错误" 按唯一会话名称查看
|
|
221
|
+
```
|
|
222
|
+
|
|
223
|
+
### 输出内容
|
|
224
|
+
|
|
225
|
+
```text
|
|
226
|
+
会话 #3 修复登录态失效 · 项目展示名
|
|
227
|
+
最后活动:10-29 14:04 · 后台
|
|
228
|
+
|
|
229
|
+
最近一轮对话
|
|
230
|
+
你:
|
|
231
|
+
<最近一条 user 提问, 最多 600 字符>
|
|
232
|
+
AI:
|
|
233
|
+
<最近一条 assistant 回复, 最多 600 字符>
|
|
234
|
+
|
|
235
|
+
发送 /resume 3 可切换到此会话。
|
|
236
|
+
```
|
|
237
|
+
|
|
238
|
+
- 带选择器时未复现有会内固定尾行改为提示 `发送 /resume <索引> 可切换到此会话`; 无选择器时提示 `发送任意内容可继续对话`
|
|
239
|
+
- 单段超过 600 个 Unicode 字符时截断, 并附 `[提问较长, 已截断。]` 或 `[回复较长, 完整内容仍在会话记录中。]`
|
|
240
|
+
- 工具输出与 thinking 推理 **不会** 进入摘要, 只展示用户提问与最终回复
|
|
241
|
+
- 会话正在运行时, 在 header 与正文之间插入 `⚠️ 该会话正在运行, 以下为目前已落盘的内容。`, 避免把中间步骤误读为最终结论
|
|
242
|
+
- assistant 尚未产生回复时显式输出 `AI:尚未产生回复。`
|
|
243
|
+
|
|
244
|
+
### 无记录与未绑定会话
|
|
245
|
+
|
|
246
|
+
| 场景 | 回复 |
|
|
247
|
+
|---|---|
|
|
248
|
+
| 当前 route 未绑定会话且未传选择器 | `当前微信路由没有绑定会话。使用 /sessions 查看列表, 或 /last <索引> 查看指定会话。` |
|
|
249
|
+
| 会话状态为 `pending` 且无任何 transcript | `该会话尚未写入任何对话记录。` |
|
|
250
|
+
| transcript 存在但读取失败 | `未能读取该会话的对话记录。` |
|
|
251
|
+
|
|
252
|
+
### 无副作用保证
|
|
253
|
+
|
|
254
|
+
`/last` 的读取策略是按需增窗, 不是固定只读末尾:
|
|
255
|
+
|
|
256
|
+
```text
|
|
257
|
+
初始读末尾 256 KB
|
|
258
|
+
↓ 窗口内已找到完整一轮 (user + assistant)
|
|
259
|
+
↓ 否则倍数扩大窗口重试
|
|
260
|
+
上限 8 MB
|
|
261
|
+
↓ 仍不命中(单条消息超大)
|
|
262
|
+
流式全文件扫描兜底, 保证结果正确
|
|
263
|
+
```
|
|
264
|
+
|
|
265
|
+
无论走哪条路径, `/last` 都不改变 route 绑定、不写入 transcript、不调用模型、不产生 durable queue 项, 因此无副作用且无额外 token 消耗. 尾部首行可能是半行, 总是丢弃以避免解析到截断的 JSON. 看完后可直接发送新指令, 或用 `/resume <索引>` 切换过去继续工作.
|
|
266
|
+
|
|
267
|
+
Pi TUI 的内置 `/resume` 仍使用 Pi 自己的会话选择器. 如果目标是 Hub 会话, extension 会安全完成前后台 owner 交接. 未登记 session 不再因缺少 Hub 记录而阻止 Pi 原生恢复; 恢复后仅当 cwd 位于授权根内才自动接入 Hub.
|
|
268
|
+
|
|
269
|
+
## 配置
|
|
270
|
+
|
|
271
|
+
默认配置位置:
|
|
272
|
+
|
|
273
|
+
```text
|
|
274
|
+
%USERPROFILE%\.pi\agent\wechat-session-manager.json
|
|
275
|
+
```
|
|
276
|
+
|
|
277
|
+
如果设置了 `PI_CODING_AGENT_DIR`, 配置保存在该目录下的 `wechat-session-manager.json`. 首次在 Pi TUI 执行 `/wx start` 时, Hub 会自动创建缺省配置并初始化当前 session 的授权根和项目记录. `allowedProjectRoots` 是安全边界, 一个根目录覆盖其子目录. 授权范围内的当前 Pi session 会按 cwd 文件夹名自动登记, 不需要逐个添加项目 alias, 也不会扫描其他目录或 Pi session 文件. 后续授权新工作区时, 可在本机 TUI 执行 `/wx roots add-current` 或 `/wx roots add <绝对路径>`. 示例:
|
|
278
|
+
|
|
279
|
+
```json
|
|
280
|
+
{
|
|
281
|
+
"schemaVersion": 1,
|
|
282
|
+
"autoStartOnWindowsLogon": false,
|
|
283
|
+
"allowedProjectRoots": [],
|
|
284
|
+
"projects": {},
|
|
285
|
+
"wechat": {
|
|
286
|
+
"authorizedUserId": ""
|
|
287
|
+
}
|
|
288
|
+
}
|
|
289
|
+
```
|
|
290
|
+
|
|
291
|
+
缺省字段会使用安全默认值. 历史配置中的 `defaultMode` 字段为兼容旧配置保留, 不决定微信端 `/new` 的运行模式; `/new` 默认创建后台会话, 也可通过 `--mode ui` 显式创建可见 UI 会话. `wechat.credentialFile` 固定指向 manager 数据目录中的 `credentials.json`; reader 拒绝目录外路径、符号链接、未知 schema 或授权用户不匹配. QR 凭证只在文件不存在时 create-only 写入, 不读取或覆盖其他应用数据.
|
|
292
|
+
|
|
293
|
+
Windows 首次创建空 manager 目录时会关闭继承 ACL, 仅授权当前用户、SYSTEM 和 Administrators; 已有非空目录不会自动修改权限, 登录和启动时会验证目录树. POSIX 要求 manager 目录和凭证文件无 group/other 权限, 且父目录不能被 group/other 写入. 权限无法验证时 fail-closed.
|
|
294
|
+
|
|
295
|
+
## 安全与运行边界
|
|
296
|
+
|
|
297
|
+
- Pi session JSONL 是对话历史事实源; Gateway 不直接编辑 transcript.
|
|
298
|
+
- Gateway 通过 `manager.lock` 保证单实例. control IPC 使用当前 lease token 完成 HMAC challenge, UI attach 使用 manager 目录 ACL 保护的稳定随机 key; 在线状态由活跃 IPC 校验, 不依赖过期 `gateway.json`.
|
|
299
|
+
- route 绑定、会话索引和 worker owner 持久保存; session 恢复前重新验证项目路径是否仍位于 `allowedProjectRoots`.
|
|
300
|
+
- 审计事件不记录消息正文、模型输出或凭证. 队列只在未完成期间保存原消息及 `replyContext`; 完成后压缩移除 payload, 并保留最近 1000 个 messageId 的 SHA-256 摘要用于去重.
|
|
301
|
+
- iLink `sendtyping` 仅提供 best-effort "正在输入"提示. Pi turn settled 后 Hub 发送一条完整最终回复, 不做 token 级微信流式回传.
|
|
302
|
+
- 关闭服务后不会自动登录或生成 QR. 自动启动仅由 `autoStartOnWindowsLogon` 和当前用户登录计划任务控制.
|
|
303
|
+
- 可见 UI 模式在执行前校验平台和 `wt.exe`, 校验不通过即阻塞, 不产生半启动进程.
|
|
304
|
+
|
|
305
|
+
## 常见问题
|
|
306
|
+
|
|
307
|
+
**Q: 非 Windows 系统能用吗?**
|
|
308
|
+
能装能用后台模式, 但不能创建可见 UI 会话. `/new` 用默认后台模式正常; `/new --mode ui`、`/wx autostart on` 会返回"仅支持 Windows"并拒绝执行.
|
|
309
|
+
|
|
310
|
+
**Q: 提示"未找到 Windows Terminal (wt.exe)"怎么办?**
|
|
311
|
+
从 Microsoft Store 安装 Windows Terminal, 或确认 `%LOCALAPPDATA%\Microsoft\WindowsApps\wt.exe` 存在且在 PATH 中. 安装后不必重启 daemon, 直接重试即可(失败结果不缓存). 也可一直使用后台模式, 不依赖 `wt.exe`.
|
|
312
|
+
|
|
313
|
+
> Windows Terminal 常以 App Execution Alias 形式存在. 该目录权限受限, 对它执行 `Test-Path` / `existsSync` 会返回 false, 因此探测逻辑不依赖文件存在性, 而以 `where.exe` 解析结果与路径归属为准.
|
|
314
|
+
|
|
315
|
+
**Q: 扫码后 `/wx start` 报需要重新授权?**
|
|
316
|
+
凭证文件只在不存在时 create-only 写入, 不会覆盖. 若授权失效, 重新执行 `/wx login` 覆盖 Hub 自己的凭证文件即可.
|
|
317
|
+
|
|
318
|
+
**Q: 微信消息一直没回复?**
|
|
319
|
+
先 `/wx status` 看当前终端接入状态与未完成消息数. 若队列被非正常退出留下的失败项阻断, 需要 `/retry <message-id> --confirm` 重新执行, 该操作可能产生副作用.
|
|
320
|
+
|
|
321
|
+
**Q: 为什么 `/sessions` 看不到我在别的目录开的会话?**
|
|
322
|
+
Hub 只管理 `allowedProjectRoots` 内的会话, 且不扫描本机其他 session 文件. 用 `/wx roots add <绝对路径>` 授权该目录后重新打开会话即可接入.
|
|
323
|
+
|
|
324
|
+
**Q: 安装时 npm 拉依赖失败?**
|
|
325
|
+
`pi install git:` 与 `npm install` 需要访问 npm registry. 可配置 npm 镜像, 或在 `settings.json` 中用 `npmCommand` 指定包装命令(如 `mise`、`asdf`).
|
|
326
|
+
|
|
327
|
+
**Q: `/last` 和 `/resume` 区别?**
|
|
328
|
+
`/last` 纯只读, 看完不动 route, 适合先确认上下文再决定下一步; `/resume` 会真实切换当前微信 route 并可能重启 Pi worker. 两者都支持索引和唯一名称选择器.
|
|
329
|
+
|
|
330
|
+
**Q: 升级后行为异常?**
|
|
331
|
+
执行 `pi update --all` 拉齐 Pi 与包版本, 然后 `/wx restart`. 版本兼容范围见 `package.json` 的 `piCompatibility`.
|
|
332
|
+
|
|
333
|
+
**Q: 二次开发后我的修改需要公开吗?**
|
|
334
|
+
本仓库使用 AGPL-3.0-or-later. 分发修改后的版本, 或将其作为网络服务提供给他人在线使用, 都需要以同等许可开放对应源码. 详见下方许可证章节.
|
|
335
|
+
|
|
336
|
+
## 开发与验证
|
|
337
|
+
|
|
338
|
+
```bash
|
|
339
|
+
npm install
|
|
340
|
+
npm run typecheck
|
|
341
|
+
npm test
|
|
342
|
+
npm run test:pi-runtime
|
|
343
|
+
```
|
|
344
|
+
|
|
345
|
+
当前自动化测试覆盖配置/索引迁移、Gateway IPC 和 detached daemon 启动失败保护、Windows 登录任务参数、前后台 session handoff、durable queue、iLink fake transport、typing indicator、凭证隔离、UI 模式平台阻塞和 worker 生命周期. `npm test` 使用 fake Pi/iLink, 不访问真实微信服务、不启动真实 Windows Terminal, 也不调用模型. 条件 ACL 集成测试默认跳过, 可单独启用:
|
|
346
|
+
|
|
347
|
+
```bash
|
|
348
|
+
PI_WECHAT_VERIFY_WINDOWS_ACL=1 node --experimental-transform-types --test --test-name-pattern="Windows manager ACL integration" tests/credential-store.test.ts
|
|
349
|
+
```
|
|
350
|
+
|
|
351
|
+
Pi RPC smoke 使用隔离配置检查扩展命令注册, 不访问真实账号凭证. 版本兼容范围和 CI 矩阵见 `package.json` 的 `piCompatibility` 与 `.github/workflows/pi-compat.yml`.
|
|
352
|
+
|
|
353
|
+
设计背景见 `docs/implementation-spec.md` 与 `docs/decisions/`.
|
|
354
|
+
|
|
355
|
+
## 许可证
|
|
356
|
+
|
|
357
|
+
本项目以 [GNU Affero General Public License v3.0 or later](LICENSE) 发布, SPDX 标识为 `AGPL-3.0-or-later`.
|
|
358
|
+
|
|
359
|
+
选择 AGPL 而非宽松许可, 是为了保证基于本项目的二次开发也持续开源:
|
|
360
|
+
|
|
361
|
+
- 修改并分发本项目或其衍生作品, 必须公开对应源码
|
|
362
|
+
- 将修改后的版本作为网络服务提供给他人使用, 同样必须提供源码
|
|
363
|
+
- 必须保留版权声明与许可证, 并用相同许可证发布衍生作品
|
|
364
|
+
|
|
365
|
+
若你的组织无法接受 AGPL 的传染性条款, 需要单独的商业授权, 请通过仓库 Issue 联系维护者.
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
# ADR 0001: 持久化 iLink 单条消息的 context_token
|
|
2
|
+
|
|
3
|
+
## 状态
|
|
4
|
+
|
|
5
|
+
已接受. 选择 A 方案作为首版实现.
|
|
6
|
+
|
|
7
|
+
## 背景
|
|
8
|
+
|
|
9
|
+
iLink 回复需要回传对应入站消息的 `context_token`. Gateway 可能在 Pi worker 执行期间重启, 因此待处理消息需要携带可恢复的回复上下文. `context_token` 是会话级敏感数据, 不能写入普通 `events.jsonl` 或日志.
|
|
10
|
+
|
|
11
|
+
## 决策
|
|
12
|
+
|
|
13
|
+
将 `recipientId` 和 `contextToken` 作为可选 `replyContext` 与入站消息正文一起保存在 route 专属 durable queue JSONL 中:
|
|
14
|
+
|
|
15
|
+
```text
|
|
16
|
+
queue/<route-hash>.jsonl
|
|
17
|
+
pending entry: messageId + text + replyContext + state
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
成功投递后压缩 queue 文件, 移除该消息正文和回复上下文. 幂等索引仅保留最近 1000 个 `messageId` 的 SHA-256 摘要, 不保存 token 或正文. `events.jsonl` 不记录 `replyContext`.
|
|
21
|
+
|
|
22
|
+
Bot 登录 token 仍只允许放在独立 `credentialFile` 中; 本决策不会读取或迁移其他客户端凭证.
|
|
23
|
+
|
|
24
|
+
## 理由
|
|
25
|
+
|
|
26
|
+
- 保持 Node.js 核心跨 Windows、macOS 和 Linux, 不把 DPAPI 或原生密钥库绑定进主流程.
|
|
27
|
+
- 支持 Gateway 重启后继续处理 pending queue, 并用原始 `context_token` 正确回复.
|
|
28
|
+
- 与已有 durable queue 中保存 pending message text 的生命周期一致, 完成后通过压缩删除敏感 payload.
|
|
29
|
+
|
|
30
|
+
## 风险与缓解
|
|
31
|
+
|
|
32
|
+
- Pending、failed 或 interrupted queue item 会在本地文件中保存明文消息和 `context_token`.
|
|
33
|
+
- POSIX 启动检查 manager 目录和凭证文件无 group/other 权限, 并要求其父目录不可被 group/other 写入.
|
|
34
|
+
- Windows 新建或空 manager 目录时关闭继承 ACL, 仅授予当前用户、SYSTEM 和 Administrators; 已有非空目录不自动改权限。启动时递归检查 manager 数据树仅这些主体可访问, agent 父目录允许只读 ACE 但不允许不可信主体写入; PowerShell 7/ACL 校验失败时 fail-closed.
|
|
35
|
+
- 设备备份、管理员权限进程或同一 OS 用户下的恶意进程仍可能读取 pending queue.
|
|
36
|
+
- `context_token` 不会进入普通审计日志; 完成消息正文被移除, 去重索引只保留哈希.
|
|
37
|
+
- 若后续要求防范同一 OS 用户进程或离线磁盘读取, 可将 `replyContext` 迁移到 DPAPI/Keychain/Secret Service 抽象, queue 只保存 opaque reference.
|
|
38
|
+
|
|
39
|
+
## 实施边界
|
|
40
|
+
|
|
41
|
+
当前代码实现了 `replyContext` 的 pending queue 持久化和完成后清理、注入凭证的 iLink API/poller adapter、固定路径只读 credential provider、独立 `/wx login` QR 授权和 detached Gateway daemon. `/wx start|status|stop|restart` 通过本机 HMAC control IPC 操作共享 daemon; 普通 Pi TUI 通过稳定 attach key 注册可见 session owner, TUI 关闭后 route 切回 background RPC. `/sessions` 使用持久会话索引, Windows 登录自动启动默认关闭并由 `/wx autostart on|off` 管理当前用户计划任务. QR 登录只提交空 `local_token_list`, 并以 create-only 写入 Hub 自有 `credentials.json`; 不读取、复制、覆盖或删除其他客户端凭证. 自动化测试使用 fake QR/credentials/transport 和 fake scheduler; 真实计划任务、账号和设备验收由使用者在本机完成.
|
|
@@ -0,0 +1,134 @@
|
|
|
1
|
+
# Pi WeChat Session Hub 新会话交接说明
|
|
2
|
+
|
|
3
|
+
本文件为下一次 Pi 会话提供当前实现、最近讨论和待决策事项的快速上下文. 代码与测试是行为事实源; 本文件是交接摘要, 与实现不一致时以代码和最新测试为准.
|
|
4
|
+
|
|
5
|
+
## 当前仓库状态
|
|
6
|
+
|
|
7
|
+
- 分支: `main`.
|
|
8
|
+
- 最近提交: `009fecb docs: 更新会话恢复与 Hub 状态说明`.
|
|
9
|
+
- 最近相关提交:
|
|
10
|
+
- `a706580 fix: 修复旧 owner 阻塞会话恢复`.
|
|
11
|
+
- `2f7d7c8 feat: 恢复会话后回显最近回复`.
|
|
12
|
+
- `de9b13c fix: 优化微信帮助命令换行`.
|
|
13
|
+
- 上述提交均为本地提交, 尚未 push.
|
|
14
|
+
- 本交接文档已提交; 当前工作区包含尚未提交的微信命令回复可读性和 Gateway 生命周期完成通知优化.
|
|
15
|
+
|
|
16
|
+
## 产品目标与重要约束
|
|
17
|
+
|
|
18
|
+
Pi WeChat Session Hub 让用户通过微信管理已登记项目中的多个 Pi 会话. Gateway 是脱离 Pi TUI 的独立后台 daemon; Pi session JSONL 仍是对话历史事实源.
|
|
19
|
+
|
|
20
|
+
必须保持的约束:
|
|
21
|
+
|
|
22
|
+
- 一个 Pi session 同一时刻只能有一个 runtime writer.
|
|
23
|
+
- 微信只能操作 Hub registry 中的 session, 不扫描或暴露所有本机 Pi session 文件.
|
|
24
|
+
- TUI session 只有在 cwd 与已登记项目路径匹配, 且位于 `allowedProjectRoots` 内时才接入 Hub.
|
|
25
|
+
- 微信命令不接受任意 shell、路径或 Pi slash command. 未知 slash command fail-closed.
|
|
26
|
+
- 不读取、复制、覆盖或删除其他应用凭证. Hub 凭证只写 Hub 自己的专属目录, create-only.
|
|
27
|
+
- 面向用户的交流、提示、文档和注释使用中文; 避免不必要地提及其他产品.
|
|
28
|
+
|
|
29
|
+
## 当前架构与命令行为
|
|
30
|
+
|
|
31
|
+
```text
|
|
32
|
+
Pi TUI: /wx start|status|stop|restart|autostart
|
|
33
|
+
│ 本机 HMAC IPC
|
|
34
|
+
▼
|
|
35
|
+
独立 Hub daemon / Gateway
|
|
36
|
+
├─ iLink poller + durable queue
|
|
37
|
+
├─ route/session registry + 稳定索引
|
|
38
|
+
└─ 每个 session 唯一 Pi writer
|
|
39
|
+
├─ TUI owner: 消息进入可见会话
|
|
40
|
+
└─ 无 TUI owner: 后台 Pi RPC worker
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
- `/wx` 打开本机控制菜单. `/wechat-manager` 保留兼容.
|
|
44
|
+
- `/wx start` 启动独立 daemon; `/wx status|stop|restart` 控制服务. `/wx stop` 需要 TUI 二次确认.
|
|
45
|
+
- Windows 当前用户登录自动启动配置默认关闭. 用户登录任务尚未在本机实际启用或创建.
|
|
46
|
+
- `/new` 默认创建后台会话; 显式 `/new --mode ui` 会启动可见 Windows Terminal UI. 默认不打开新 tab.
|
|
47
|
+
- `/sessions` 默认列出 Hub 管理的活跃前台/后台会话, 每页 5 条, 每个会话单独展示标题、项目、模式和状态; 当前微信 route 在列表摘要和对应会话项中标记. 标题优先使用会话名; 没有名称时仅读取 Pi `/resume` 同样采用的首条用户文本. 标题最长 32 个 Unicode code point, 超出以 `...` 省略; 暂无用户消息时显示“尚无用户消息”.
|
|
48
|
+
- 微信 `/resume <索引|名称>` 将该微信 sender 的 route 切换到目标 session. 空闲会话恢复后附带最多 800 个 Unicode 字符的最近回复预览; 内容过长时提示完整回复仍保留在会话记录中. 本机 TUI `/resume` 会进行 UI/background owner 交接.
|
|
49
|
+
|
|
50
|
+
## 最近讨论: 活跃 turn 中切换 route
|
|
51
|
+
|
|
52
|
+
用户询问: 微信当前会话正在处理消息时, 发送 `/resume` 或 `/new` 会不会立刻切换并让旧会话继续运行.
|
|
53
|
+
|
|
54
|
+
**当前实现是同一个 route 的 durable FIFO.** `/resume`、`/new` 和普通 prompt 都进入同一 route 队列. 若旧 turn 正在运行:
|
|
55
|
+
|
|
56
|
+
1. 新命令会持久入队, poller 可继续接收消息.
|
|
57
|
+
2. 旧 turn 先完成, 最终回复先发回微信.
|
|
58
|
+
3. 队列再处理切换命令并更新 route.
|
|
59
|
+
4. 后续消息发给新 session. 旧 session 不会被删除或停止, 但旧 turn 已完成; 它不再接收此 route 的后续消息.
|
|
60
|
+
|
|
61
|
+
因此命令不是立即切换. 若旧 turn 长时间不结束, 切换也会延迟. 目前没有确定要改变此行为.
|
|
62
|
+
|
|
63
|
+
下一次讨论可比较两种语义:
|
|
64
|
+
|
|
65
|
+
- 保持严格 FIFO. 优点是入站顺序容易理解, 切换不越过已发 prompt. 缺点是长 turn 会延迟切换.
|
|
66
|
+
- 为 `/resume`/`/new` 增加优先控制通道, 让 route 可在旧 turn 运行期间切换. 旧 worker 可以继续原 turn, 后续消息发往新 route. 这需要明确排队中的普通消息归属、回执顺序、停止/重试交互, 并验证 writer 与 route generation 无竞态.
|
|
67
|
+
|
|
68
|
+
不要在未与用户确认语义前直接改成优先切换.
|
|
69
|
+
|
|
70
|
+
## 项目 allowlist 与会话注册
|
|
71
|
+
|
|
72
|
+
- 默认 Hub 配置: `%USERPROFILE%\.pi\agent\wechat-session-manager.json`.
|
|
73
|
+
- 如果设置了 `PI_CODING_AGENT_DIR`, 配置位于该目录下的 `wechat-session-manager.json`.
|
|
74
|
+
- `allowedProjectRoots` 只能在配置文件中修改, 当前没有 `/projects roots` 命令. 不支持 glob; 一个 root 覆盖它本身和所有子目录.
|
|
75
|
+
- `/projects add <alias> --name <名称> --path <绝对路径>` 只登记项目 alias, 不会改 `allowedProjectRoots`.
|
|
76
|
+
- UI bridge 要求 Pi session 的 cwd 与某个 `projects.<alias>.path` 精确匹配. 仅把路径放进允许根目录仍不够.
|
|
77
|
+
- 曾诊断到一条当前 Pi session 因 cwd 未登记/不在允许根内而没有进入 Hub registry; `session_start` 中的 `project_not_registered` 会静默跳过. 之后用户询问过修改 root 和登记 alias 的步骤, 但交接时不应假定本机配置的最终状态, 应先用 `/projects` 和微信 `/sessions` 复核.
|
|
78
|
+
- 把父目录加入 `allowedProjectRoots` 会扩大 Hub 可登记范围; 优先授权具体项目目录, 避免直接授权过宽的父目录.
|
|
79
|
+
|
|
80
|
+
## 本机安装与更新
|
|
81
|
+
|
|
82
|
+
用户执行过 Pi local-path package 安装. Pi 的 local path package 默认写入用户级 settings, 不复制源码; 后续修改对应目录会被新的进程读取.
|
|
83
|
+
|
|
84
|
+
Gateway 是常驻 daemon, 已运行进程不会自动加载磁盘上的新代码. 修改 Gateway 代码后在已加载扩展的 Pi TUI 执行 `/wx restart`, 再从微信验证. 大多数情况下不需重新 `pi install` 或重启所有 Pi TUI.
|
|
85
|
+
|
|
86
|
+
若出现旧的 `/help`/`/new` 输出, 先确认 daemon 已 restart, 再考虑 package path 或运行中的旧进程.
|
|
87
|
+
|
|
88
|
+
## 近期已完成的相关改动
|
|
89
|
+
|
|
90
|
+
- `/sessions` 改为每页 5 条的窄屏文本卡片, 每项独立显示索引/标题和项目/模式/状态; 当前 route 显示“当前微信路由”和“【当前】”标记. 标题优先取会话名, 否则读取 Pi `/resume` 使用的首条用户文本; 清理控制字符并在 32 个 Unicode code point 后追加 `...`.
|
|
91
|
+
- 微信 `/help` 按会话、项目、Hub 状态分组并缩短长语法行.
|
|
92
|
+
- 微信 `/status` 使用中文状态摘要, 不暴露 PID 或内部技术字段.
|
|
93
|
+
- 空闲会话 `/resume` 回复最多 800 个 Unicode 字符的最近回复预览, 超长时显示开头并说明完整内容仍在 transcript.
|
|
94
|
+
- `/wx start`、`/wx stop`、`/wx restart` 先显示进度, 完成后再通知最终状态. `/wx stop` 的控制请求等待 runtime 安全收尾; `/wx restart` 通过 operationId 和 lifecycle receipt 等待新 daemon ready, Pi 端用本地文件事件唤醒, 不循环轮询网络.
|
|
95
|
+
- `tests/gateway-service-controller.test.ts` 覆盖异步 lifecycle receipt 和 final status; `tests/wechat-session-hub-command.test.ts` 覆盖 restart 进度与完成通知.
|
|
96
|
+
- `tests/gateway-command-router.test.ts` 增加会话卡片、稳定索引、当前 route 标记、分页、状态摘要、帮助分组和恢复预览截断回归测试.
|
|
97
|
+
|
|
98
|
+
**文档不一致提醒:** README 配置说明中仍有旧句子称微信 `/new` 固定创建后台会话; 实现现在支持显式 `--mode ui`. 后续可顺手修正文案.
|
|
99
|
+
|
|
100
|
+
## 验证状态
|
|
101
|
+
|
|
102
|
+
最近一次验证, 在本机 Pi 开发依赖 `0.85.1` 下:
|
|
103
|
+
|
|
104
|
+
- `npm run typecheck`: 通过.
|
|
105
|
+
- `npm test`: 92 项, 91 pass, 1 项条件 Windows ACL 测试 skip.
|
|
106
|
+
- `git diff --check`: 通过.
|
|
107
|
+
- Gateway restart 的完成通知通过隔离控制 IPC、异步 lifecycle receipt 和 fake TUI notification 测试; 未对真实微信连接执行 `/wx restart`.
|
|
108
|
+
|
|
109
|
+
Pi `0.85.1`、`1.0.0`、`1.3.0` 完整兼容矩阵在较早的实现阶段已跑通; 最近的微信回复和生命周期通知优化只在 `0.85.1` 完整验证, 尚未重新跑全部版本矩阵. Windows ACL 专项测试在较早验证时通过. 最近一次 `npm audit --omit=dev` 遇 npm registry `503`; 依赖锁文件未变, 但该次未完成新审计.
|
|
110
|
+
|
|
111
|
+
## 建议下一会话优先确认
|
|
112
|
+
|
|
113
|
+
1. 用户希望 `/resume`/`/new` 在旧 turn 未完成时立即切换, 还是继续保持 FIFO 等待.
|
|
114
|
+
2. 当前 Pi TUI session 的实际 cwd 是否已精确登记, `allowedProjectRoots` 是否过宽.
|
|
115
|
+
3. 对未登记 cwd 是否应从静默跳过改为给本机 TUI 明确提示, 同时继续 fail-closed.
|
|
116
|
+
4. 在 `/wx restart` 后实测微信 `/help` 分组、`/status` 中文摘要、`/sessions` 卡片/分页和 `/resume` 长回复预览, 以及 `/new --mode ui` 是否打开可见 tab.
|
|
117
|
+
5. 是否需要修 README 中旧 `/new` 描述, 并在合并更多改动后重跑 Pi `1.0.0` / `1.3.0` 矩阵.
|
|
118
|
+
|
|
119
|
+
## 常用验证命令
|
|
120
|
+
|
|
121
|
+
```bash
|
|
122
|
+
npm run typecheck
|
|
123
|
+
npm test
|
|
124
|
+
npm run test:pi-runtime
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
在运行常驻 Gateway 的环境中, 修改代码后执行:
|
|
128
|
+
|
|
129
|
+
```text
|
|
130
|
+
/wx restart
|
|
131
|
+
/wx status
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
再通过微信发送相应命令验证.
|