@zieglar/pi-chat-exchange 0.2.0 → 0.2.2
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 +41 -61
- package/dist/bin/ce-native.js +119 -0
- package/dist/control/mcp/server.js +1 -1
- package/dist/host/mcp-binding-config.js +1 -1
- package/dist/runtime/diagnostics.js +3 -3
- package/dist/runtime/executables.js +37 -30
- package/dist/runtime/native-readiness.js +131 -0
- package/dist/runtime/wrapper-identity.js +53 -0
- package/dist/storage/connection.js +4 -3
- package/dist/storage/filesystem.js +58 -3
- package/dist/storage/native-artifact.js +234 -0
- package/dist/storage/native-compat.js +65 -0
- package/dist/storage/runtime.js +201 -58
- package/dist/storage/sqlite-driver-node.js +66 -0
- package/dist/storage/sqlite-driver-rust.js +121 -0
- package/dist/storage/sqlite-driver-selection.js +86 -0
- package/dist/storage/sqlite-driver.js +4 -0
- package/dist/storage/store.js +3 -3
- package/dist/storage/transaction.js +20 -23
- package/dist/tunnel/background-manager.js +5 -52
- package/dist/tunnel/codes.js +1 -1
- package/dist/tunnel/keychain.js +1 -1
- package/dist/tunnel/managed-binding.js +1 -1
- package/dist/tunnel/manager-panel.js +1 -1
- package/dist/tunnel/profile.js +4 -2
- package/dist/tunnel/setup-ui.js +3 -3
- package/dist/tunnel/tunnel-id.js +4 -0
- package/package.json +8 -20
- package/pi-extension/index.ts +34 -0
- package/CHANGELOG.md +0 -70
- package/docs/architecture.md +0 -170
- package/docs/chatgpt-installation.md +0 -149
- package/docs/delivery-ack-contract.md +0 -86
- package/docs/independent-install.md +0 -156
- package/docs/multi-session-usage.md +0 -77
- package/docs/ownership-contract.md +0 -429
- package/docs/protocol-v2.md +0 -269
- package/docs/releases/0.2.0.md +0 -59
- package/docs/storage-contract.md +0 -1241
- package/docs/storage-security.md +0 -138
- package/docs/tunnel-manager-background.md +0 -169
- package/docs/tunnel-setup.md +0 -214
- package/pi-extension/README.md +0 -125
package/docs/architecture.md
DELETED
|
@@ -1,170 +0,0 @@
|
|
|
1
|
-
# pi-chat-exchange 开发者架构指南
|
|
2
|
-
|
|
3
|
-
本文说明消息、Endpoint/Session authority、transport 与 Pi 适配器的边界。用户入口见[快速开始](tunnel-setup.md),多项目操作见[多 Session 使用](multi-session-usage.md)。精确约束仍以协议、Storage 与 Ownership 契约及源码 gate 为准。
|
|
4
|
-
|
|
5
|
-
## 分层与依赖方向
|
|
6
|
-
|
|
7
|
-
```text
|
|
8
|
-
ChatGPT (Tunnel MCP / Desktop stdio) Pi runtime
|
|
9
|
-
| |
|
|
10
|
-
src/bin + src/control/mcp pi-extension/index.ts
|
|
11
|
-
| |
|
|
12
|
-
| src/endpoints/pi
|
|
13
|
-
+---------- src/host ---------------+
|
|
14
|
-
|
|
|
15
|
-
src/storage
|
|
16
|
-
|
|
|
17
|
-
src/core
|
|
18
|
-
|
|
|
19
|
-
src/protocol
|
|
20
|
-
|
|
21
|
-
src/tunnel: transport/profile/setup/Manager;不替代 CE Host authority
|
|
22
|
-
```
|
|
23
|
-
|
|
24
|
-
| 层 | 职责 | 不应做什么 |
|
|
25
|
-
|---|---|---|
|
|
26
|
-
| `src/protocol/` | 中立实体、lifecycle、action grants、support declarations | 不依赖 Pi、MCP、网络或数据库 |
|
|
27
|
-
| `src/core/` | 纯证据/授权规则,reference in-memory 行为 | 不读 env、文件或真实调用 endpoint |
|
|
28
|
-
| `src/storage/` | 私有 SQLite、事务、schema/migrations、Ownership/fencing、最终数据授权 | 不把 private SQL/migration/evidence 类型暴露到 public barrel |
|
|
29
|
-
| `src/host/` | adapter-neutral durable Endpoint Host,可信 binding、Session、幂等消息与 receipt 操作 | 不从 tool 参数接受 sender/capability,不替代外层工作流完成权威 |
|
|
30
|
-
| `src/control/mcp/` | MCP schema/输出;默认 ping,注入 bound port 后提供 messaging | 不读任意 env、不直接 import Pi integration,不凭工具调用识别 ChatGPT 对话身份 |
|
|
31
|
-
| `src/endpoints/pi/` | Pi Session host 的薄适配 | 不 import MCP SDK 或其他 endpoint integration |
|
|
32
|
-
| `src/bin/` | stdio 组合根、可信绝对路径 `--config`、进程生命周期 | 不另造消息 broker 或平行 authority |
|
|
33
|
-
| `pi-extension/` | 运行时 Session lookup、工具/命令、生命周期、UI、mapping identifiers | 不持久化 capability,不代替 Storage 决定可见性 |
|
|
34
|
-
| `src/tunnel/` | client 生命周期、健康测量、私有配置事务、masked 输入与显式激活 UI | 不把 CONNECTED 当消息 Gate,不隐式读取/ACK/重试消息 |
|
|
35
|
-
|
|
36
|
-
核心依赖向内:`bin → control/endpoints/host → storage → core → protocol`,具体许可由 `scripts/check-contract.mjs` 的 TypeScript AST gates 决定。protocol/core 不可 reach 外层;control 与 endpoints 不互相 import;禁止借 barrel、dynamic import 或 require 绕开。tunnel 属外层组合,不提升协议权威。共享行为优先下沉已有 Host/Storage seam,不让 ChatGPT/Pi 各实现第二套 Message 系统。
|
|
37
|
-
|
|
38
|
-
## 身份模型与注册权威
|
|
39
|
-
|
|
40
|
-
- **Exchange**:关联聚合,不是一个对话或 transport 连接;namespace/idempotencyKey 只负责确定性 bootstrap。
|
|
41
|
-
- **EndpointRef**:`{adapter, endpointId}` 是非秘密身份。初始配对为 `chatgpt/main` 与 `pi/main`;多 Session 时每个 Pi Session 显式注册独立稳定 Endpoint(如 `pi/project-B`)。各 Endpoint 是独立 Authority,不共享 Owner;共享 ChatGPT inbox 不是对话隔离。
|
|
42
|
-
- **Participant**:Store/Exchange 中注册的参与者;与当前具体 Session/incarnation 分开。
|
|
43
|
-
- **CE Session / Ownership / fencing**:活跃执行权威与 incarnation,需 membership、lease、current owner、fencing 和精确作用域 capability 一起校验。
|
|
44
|
-
- **Pi runtime Session ID**:从可信 Pi API 取得,作为 operator allowlist lookup。不是 CE Session ID,也不是凭自身能发消息的凭据。
|
|
45
|
-
- **Recipient label**:工具 `to` 使用精确 endpointId,不是认证。labels、support declarations、工具存在和 UI 选择都不直接发 authority。
|
|
46
|
-
- **Capability**:Host 内存中的 scoped authority;不写 mapping/日志/配置,不让模型自选。
|
|
47
|
-
|
|
48
|
-
MCP 身份固定于 operator-owned `--config`,不是由一次 MCP invocation 或 ChatGPT 当前文字声明认证。Pi 身份固定于可信 allowlist 与当前 context。两边共享 Store directory/file 与 Exchange namespace/key;任一不同都没有自动路由补偿。`managed`/`managedBy` 是 provenance,不是替代 recipients 或 Storage 检查的许可。
|
|
49
|
-
|
|
50
|
-
### 多 Session:配置准入不取代 durable authority
|
|
51
|
-
|
|
52
|
-
`src/tunnel/{multi-session-policy,multi-session-admission}.ts` 管理 profile 选中的不可变 registration 策略;`pi-extension/multi-session-runtime.ts` 管理当前进程 guard。注册绑定可信 native Pi Session、稳定 Endpoint、active/revoked 状态与 epoch,payload/ACK 独立 opt-in;不从项目路径或模型参数推导身份。
|
|
53
|
-
|
|
54
|
-
- convert/register/revoke 需人工确认、配置 revision 校验与 verified STOPPED transport lock;不自动启停,也不能约束仍在运行的旧二进制。
|
|
55
|
-
- Pi factory grants 在 reload 前不变;MCP child 在显式 Stop/Start 前不能宣称已加载新 generation。selected configured、loaded、bound、connected 分开报告。
|
|
56
|
-
- deny-only gates 约束后续准入,包括 read/renew;已经准入的操作可能完成。正常 end/release 不被撤销门禁阻挡;撤销不删除 Owner、Participant、历史消息或 Receipt。
|
|
57
|
-
- process mutex 是本地 exclusion,不是 CE authority/recovery。runtime/epoch/Store/Exchange 与 guard 均须一致,最终权限仍由原 Host/Storage 校验;不增加 takeover 或跨 Exchange router。
|
|
58
|
-
- `/ce-tunnel sessions` 仅在当前 runtime 经 admission 后投影所选 active Endpoint IDs;不读取 Inbox,不证明运行中的 MCP 已加载。
|
|
59
|
-
|
|
60
|
-
## Message、DeliveryAttempt、Receipt、Result 的分离
|
|
61
|
-
|
|
62
|
-
1. `ce_send` 将一次逻辑发送持久化为独立 Message;Message、幂等记录与创建 Audit 在本地 Store 同一事务提交,不证明云端传输或对端接收。key 在 Exchange 内作用域化,相同 key/请求重放原记录,改变正文或 Endpoint 则冲突;这不授予未知结果重试许可,也不承诺 exactly-once delivery/execution。反向回复/后续追问也是新 Message,不是 Result 的变形。
|
|
63
|
-
2. Inbox 按 creation Audit 有界扫描并应用 recipient/membership/join boundary,不 ACK、不消费、不推进 delivery cursor。
|
|
64
|
-
3. metadata read 与 payload read 是不同权限;后者在 materialize bytes 前完成 Storage 授权。
|
|
65
|
-
4. ACK 追加 immutable reception receipt,第一次 CREATED、已有则 REPLAYED。Message 创建 Audit sequence 与 receipt Audit sequence 是不同证据。
|
|
66
|
-
5. Result 是 immutable processing evidence,发布不自动回复、关闭 Exchange 或赋予 Wayforge completion authority。
|
|
67
|
-
|
|
68
|
-
纯 core 的完整 delivery lifecycle 仍约束 claim、dispatch intent、attempt、runtime evidence、settlement、quarantine。不能因为当前工具提供持久消息/ACK,就宣称所有远端 delivery/execution/result 流程均已落地。
|
|
69
|
-
|
|
70
|
-
**冻结安全语义:** intent 先于 effect;需相关 Message/Attempt/Endpoint/incarnation/lease/fencing 证据。模糊 delivery 进入 `DELIVERY_UNKNOWN`,不 retry/requeue,不将它改成 `CANCELLED`。已知送达但执行未知也不能合成 acceptance/settlement/Result。普通 close 需所有 Message 完结;独立授权的 `ABANDONED_UNRESOLVED` 保留未知事实,不代表 cancellation/normal close/success。
|
|
71
|
-
|
|
72
|
-
CE Receipt、Pi UI 通知、Tunnel health、runtime 执行事实和 Wayforge 工作流裁决是不同平面。任何外部完成动作仍须其本身的显式授权和证据,不能从 ACK 或模型断言推导。
|
|
73
|
-
|
|
74
|
-
## 生命周期、并发与恢复边界
|
|
75
|
-
|
|
76
|
-
- MCP startup bind 使用 `requireUnowned`;独立 heartbeat 续租。SIGINT/SIGTERM/stdio-close 走一次 release/end,不自动接管 crashed Owner。
|
|
77
|
-
- Pi `session_start` 按可信 runtime lookup 选择 Endpoint;有 mapping 的 startup/reload/resume 校验恢复。reload 缺 mapping 拒绝,新/fork 不继承旧 authority。
|
|
78
|
-
- Pi reload 结束旧内存 generation/timer,不结束有效 durable Ownership;正常退出/Session replacement 尝试 end/release/detach。renew/end 未知或 diagnostic persistence 失败锁住后续路径。
|
|
79
|
-
- `ce-mapping`、`ce-messaging-released`、`ce-lifecycle-blocked` 仅存 identifiers/拒绝证据,不携带 capability。释放标记不能独立授予新权威,需验证旧 mapping 的 exact released+detached proof。
|
|
80
|
-
- 显式 activation 在 profile lock 下核实当前配置/环境/runtime,只有 requireUnowned 可绑定。匹配已有有效 binding 为 no-op;未知释放、映射写入失败或旧 Exchange 证据不符拒绝,不自动 takeover。
|
|
81
|
-
- `/ce-tunnel deactivate` 在确认与当前 generation/Session fence 后复用 `shutdownCe()` 正常结束路径;仅释放本地 CE binding,保留 registration/history/transport。未知 end 或证据持久化失败仍关闭操作;已释放 mapping 不在 reload 时自动重绑,只有显式 activate 可重新申请。
|
|
82
|
-
- Tunnel 管理的是 detached client 的进程所有权,不是 CE Owner。跨进程 directory lock、PID+exact command+start key、write-ahead termination ledger 共同避免误杀/双启动;UNKNOWN 不等于进程消失。
|
|
83
|
-
- 每个 record-backed run 最多一次 SIGTERM,不 SIGKILL、不 name-based bulk kill。intent 持久后信号丢失允许零次实际 signal;不能删除 ledger 以便重发。client MCP child 属 client,不由 Manager 擅自终止。
|
|
84
|
-
|
|
85
|
-
恢复 CLI 是另行授权的 operator-only 路径,既不注册为 MCP tool 也不由模型自动调用。进程恢复、CE Owner 恢复、消息未知结果调查是三个不同问题。
|
|
86
|
-
|
|
87
|
-
`/ce-tunnel doctor` 是独立只读安装诊断:host qualification、child executable qualification 与 client metadata trust 分开;复用现有 executable admission,不启动 Manager/client、不读取 credential 或 Store、不发布配置。它不证明 profile 当前 child 命令、client schema 兼容、云端权限或网络健康;对应证据仍由配置/真实兼容测试和 Manager 提供。
|
|
88
|
-
|
|
89
|
-
## 配置 generation 与原子迁移
|
|
90
|
-
|
|
91
|
-
源码定位:`src/tunnel/{profile,managed-binding,messaging-config,setup}.ts`,UI 在 `setup-ui.ts` / `secure-input.ts`,加载/激活在 `pi-extension/index.ts`。
|
|
92
|
-
|
|
93
|
-
- Profile 是唯一 activation pointer。普通 binding 由完整 Tunnel/Organization/adapter 身份生成,文件名短尾只显示,不承担完整 identity 比较。
|
|
94
|
-
- Advanced Messaging 发布完整 binding 与 Pi allowlist sidecar,名称 `messaging-<full SHA-256>.yaml` 及其 `.pi-allowlist.json`。digest 同时覆盖两份 bytes;generation 使用 no-overwrite link,loader 拒绝不完整/不符 pair。
|
|
95
|
-
- 两个文件发布不是跨文件 crash-atomic;最终 profile temp+rename 才是逻辑提交点。失败可能保留未选中的私有 staging/generation,不回滚或删除不确定属于谁的文件。
|
|
96
|
-
- Credential 替换先创建 0700 目录与 0600 exclusive generation,同步目录/内容,再提交引用;macOS 先清 inherited ACL。Keep 不读取内容,旧代保留,无自动 GC。
|
|
97
|
-
- postcommit sync 失败只能报 durability uncertain,不能说 rollback。ACTIVE/UNKNOWN 不能被 UI 文字绕过为可编辑。
|
|
98
|
-
- `/ce-tunnel migrate` 仅修 canonical generated YAML:移除 client 0.0.16 拒绝的 admin_ui 项并修批准 Node command,保留 identity/credential reference/binding/Store/recipient bytes;不是任意 YAML formatter。
|
|
99
|
-
|
|
100
|
-
## Storage 运行契约
|
|
101
|
-
|
|
102
|
-
精确批准 Node **24.21.0 或 24.22.1**,不接受其他 patch、25.x 或范围匹配。每个 registry tuple 绑定 SQLite **3.53.4**、source identity `2026-07-24 19:02:57 bf7c7f30031888f4e796e429ab3978879485813aaca6f641c7b33e4e09459bcc`、必要编译选项(`THREADSAFE=1`、`MUTEX_PTHREADS`;禁止 `OMIT_WAL`、`OMIT_FOREIGN_KEY`、`OMIT_TRIGGER`、`OMIT_CHECK`、`OMIT_COMPILEOPTION_DIAGS`)及实际 defensive/statement/transaction-state API 检查。Store 路径准备前即拒绝不合格 runtime;环境版本标签不是资格证据;实测矩阵与原始证据记录为 `docs/runtime-qualification.md`(作者侧证据记录,仅仓库保留、不随 tarball 分发)。平台 allowlist 仍为 macOS arm64 / Linux x64;此次双版本实测仅 macOS arm64,不等于 Linux 新增验收。还需 approved detectable local filesystem、当前用户 ownership、目录 0700、DB/WAL/SHM 0600、非 symlink final artifacts。writers 使用 defensive mode、WAL、synchronous FULL、foreign keys、trusted-schema OFF、有界 busy wait;macOS 另有 fullfsync/checkpoint_fullfsync。
|
|
103
|
-
|
|
104
|
-
migration ledger/checksum、application/store identity、integrity 与 restore hold 会拒绝 foreign/newer/corrupt Store,不自动 reset。Node 25 即使能执行 Pi UI,也不代表可以打开 CE Store。精确 gate 以 `src/storage/runtime.ts` 与 [Storage contract](storage-contract.md) 为准;受限文件权限并不能消除所有 TOCTOU、mount substitution、OS crash/power loss 风险。
|
|
105
|
-
|
|
106
|
-
## 验证层次
|
|
107
|
-
|
|
108
|
-
从包目录、批准 Node 运行:
|
|
109
|
-
|
|
110
|
-
```bash
|
|
111
|
-
pnpm run check
|
|
112
|
-
pnpm run typecheck
|
|
113
|
-
pnpm run build
|
|
114
|
-
pnpm test
|
|
115
|
-
pnpm run test:plugin-package
|
|
116
|
-
# 可选(需本机已安装 tunnel-client;不属于默认门禁)
|
|
117
|
-
pnpm run test:installed-client
|
|
118
|
-
# 可选(真实 Pi CLI + PTY 的 crash/resume 回归;数分钟,不属于默认门禁)
|
|
119
|
-
CE_HOST_REGRESSION_KEEP=1 pnpm run test:host-regression
|
|
120
|
-
# 完整串行门禁(build 在 test 前)
|
|
121
|
-
pnpm run verify
|
|
122
|
-
```
|
|
123
|
-
|
|
124
|
-
| 层次 | 证据范围 | 不能替代 |
|
|
125
|
-
|---|---|---|
|
|
126
|
-
| AST/type/compile-negative | 依赖方向、封闭 schema、类型拒绝 | 真实 runtime/客户端行为 |
|
|
127
|
-
| core/protocol unit | 纯状态转移、scope、quarantine/authority | 文件事务/远端结果 |
|
|
128
|
-
| Storage 事务/故障/多进程 | identity、lease/fencing、crash、并发、read/ACK privacy | ChatGPT UI 或云端连接 |
|
|
129
|
-
| Host/MCP/Pi isolated harness | 参数、工具发现、mapping、activation、payload/ACK、生命周期 | 实体终端和端到端用户 Gate |
|
|
130
|
-
| Tunnel offline / TUI harness | 合成 health、取消/在途/通知/屏幕契约 | 真实 client schema、认证、计费连接、终端物理表现 |
|
|
131
|
-
| `test/tunnel/real-client-compat.test.ts` | 真实 client doctor 与本地 schema 兼容;可选 lane(`pnpm run test:installed-client`),需本机已安装 tunnel-client,未安装时按可用性跳过;已排除出 `pnpm test` 与 `pnpm run verify` | 真实网络 readiness 或双向消息 |
|
|
132
|
-
| `test/tunnel/offline.integration.test.ts` | 真实 client 的离线集成;同一可选 lane,需本机已安装 tunnel-client,未安装时大声失败而非静默跳过;已排除出 `pnpm test` 与 `pnpm run verify` | 真实网络 readiness 或双向消息 |
|
|
133
|
-
| `test/host-regression/real-host-recovery.test.ts` | 真实 Pi 1.3.0 CLI + 真实 PTY 的 crash→mutex 拒绝→离线 reconcile→resume→租约续期→授权路由完成→策略收窄拒绝→expired Owner 拒绝(含 reason/hint、fencing、slot 计数)回归;可选 lane(`CE_HOST_REGRESSION_TEST=1 pnpm run test:host-regression`),先以 `git archive HEAD` 出树编译并比对 blob 身份,全合成 Store/loopback provider,零 tunnel-client 执行;前置缺失或未设 opt-in 时大声失败而非跳过;已排除出 `pnpm test` 与 `pnpm run verify` | 真实 Tunnel/Exchange、真实凭据/网络、ChatGPT UI、installed client、Operator Recovery 执行 |
|
|
134
|
-
| packaged plugin tests | 可移植包内容、stdio 启动、tool discovery | Desktop 安装菜单/资格/对话更新 |
|
|
135
|
-
| 人工 real Gate | 当前 ChatGPT 对话与 Pi 的实际 send/list/read/ACK、Tunnel 启停 | 冷启动、所有平台、所有客户端或正式发布资格 |
|
|
136
|
-
|
|
137
|
-
真实 Host lane 的证据留在原始临时根目录,不复制到另一处。`CE_HOST_REGRESSION_KEEP=1` 保留成功运行的证据;测试、进程/provider 清理(含本地超时)或清理记录写入失败时不启动删除,并尽力打印原始路径。仅在所有测试成功、驱动已等待并回收其自有子进程、合成 provider 已关闭、清理记录写入成功且未设 KEEP 时删除根目录。递归删除本身失败可能已部分移除证据;此时聚合错误以 `possibly-partially-removed` 标明状态并尽力打印原始路径,不承诺完整保留。两次离线 reconcile 均由驱动确认并记录**当前启动实例**的退出/回收身份,且在串行离线窗口前后再确认无存活自有 Store-capable 进程;未确认退出即拒绝执行,不以 `/quit` 加固定等待代替。默认收集的 `test/host-regression/*-cleanup.test.ts`、`failure-path.test.ts` 与 `refusal-comparator.test.ts` 只验证合成进程清理、离线屏障、故障证据状态和拒绝前后完整 message/audit 数组比较,不启动真实 Pi/client 或业务恢复。
|
|
138
|
-
|
|
139
|
-
本地测试只对其实际执行的固定版本与环境提供证据,跳过项和平台限制必须明示。人工消息验收与隔离回归互不替代;不要将历史报告的测试数当作当前变更的新鲜执行证据。公共验收边界见[README](../README.md)。
|
|
140
|
-
|
|
141
|
-
### 高价值回归入口
|
|
142
|
-
|
|
143
|
-
- `test/tunnel/{setup-messaging,messaging-config,messaging-config-security,messaging-binding}.test.ts`:配对、immutable publication、权限/文件与失败路径。
|
|
144
|
-
- `test/endpoints/pi/extension-messaging-activation.test.ts`:旧映射释放、reload、显式 activation、deny paths。
|
|
145
|
-
- `test/endpoints/pi/extension-ack.test.ts` 与 `test/control/mcp/messaging-ack-tool.test.ts`:独立 opt-in、四字段与模型可见 metadata。
|
|
146
|
-
- `test/tunnel/{background-manager,extension-deferred-start,real-client-compat}.test.ts`:进程证据、异步启动和真实 schema。
|
|
147
|
-
- `test/storage/delivery-ack*.test.ts`、`inbox-*.test.ts`:receipt、privacy、事务/进程边界与分页。
|
|
148
|
-
|
|
149
|
-
## 扩展点与已知债务
|
|
150
|
-
|
|
151
|
-
- 新 ControlSurface 必须使用既有 Host port、封闭请求 schema 与 adapter-neutral 规则;不能从不可信 label 自授权。
|
|
152
|
-
- 新 endpoint integration 声明独立 support,不假设 peer capabilities 对称;unsupported/unknown 保持明确,需真实 evidence 才能声称实现。
|
|
153
|
-
- 新 client 版本要真实 schema/doctor 回归,不能仅用 offline fixture;新 Node/SQLite/平台先独立资格验证,不能放松 runtime guard。
|
|
154
|
-
- UI/异步任务要保留 draft/commit 边界、Session generation、在途合并、取消/teardown 的权限分离;不以通知成功当显示/送达成功。
|
|
155
|
-
- 仍待后续:credential/generation 的显式安全 GC、机器冷启动与部分实体终端交互、受控 client 安装/升级流程。Desktop 已支持对私有副本显式配置本机批准 Node;这不是自动跨机安装或 Desktop UI 验收。
|
|
156
|
-
- 不在当前范围:自动 Inbox draining/idle wake、自动业务重试/Owner takeover、自动远端执行、任意 Store 合并或跨 Exchange router、以 ACK 代替任务完成。
|
|
157
|
-
|
|
158
|
-
## 文档事实溯源与维护
|
|
159
|
-
|
|
160
|
-
| 事实 | 首要源码/证据 |
|
|
161
|
-
|---|---|
|
|
162
|
-
| 版本与 scripts | `../package.json`、仓库根 `package.json`、`src/storage/runtime.ts` |
|
|
163
|
-
| Pi 加载与 session_start/reload | Pi 1.3.0 CLI help / extensions 文档与运行时 `AgentSession.reload`;本包 `pi-extension/index.ts` |
|
|
164
|
-
| Tunnel 字段/格式/child env | `src/tunnel/profile.ts`、`setup-ui.ts`、`background-manager.ts` |
|
|
165
|
-
| binding closed schema / opt-in | `src/host/mcp-binding-config.ts`、`src/control/mcp/` |
|
|
166
|
-
| generation/Store/Exchange 一致性 | `src/tunnel/{managed-binding,messaging-config,setup}.ts` |
|
|
167
|
-
| 工具参数/ACK metadata/状态 | `pi-extension/index.ts`、Host port、对应 extension-ack / messaging-ack tests |
|
|
168
|
-
| 当前支持与验收边界 | [README](../README.md)、对应隔离测试与独立人工验收;公共文档不复制原始消息/Session/日志 |
|
|
169
|
-
|
|
170
|
-
历史 plans/audits/validation 报告保留其时间截面,不应机械改写为“今日已全部完成”。发现代码/配置与文档目标冲突时记录限制、另开实现任务;文档提交不偷偷改 runtime 或冻结契约。
|
|
@@ -1,149 +0,0 @@
|
|
|
1
|
-
# ChatGPT 安装:Tunnel 与 Desktop 本地插件
|
|
2
|
-
|
|
3
|
-
有两条不同的部署路径,不要同时让它们占用同一个 CE Endpoint:
|
|
4
|
-
|
|
5
|
-
| 路径 | 连接方式 | 配置入口 |
|
|
6
|
-
|---|---|---|
|
|
7
|
-
| Secure MCP Tunnel | ChatGPT 自定义 MCP 插件选择 Tunnel,client 启动本机 MCP | [完整 Tunnel 快速开始](tunnel-setup.md),无需本地 marketplace |
|
|
8
|
-
| Desktop 本地插件(本页后续) | ChatGPT Desktop 启动 bundled MCP,stdio | 外置 `mcp-binding.json`;操作者配置互补 Pi allowlist |
|
|
9
|
-
|
|
10
|
-
**不要**给 Tunnel generation 再复制一个 Desktop binding 当作同一客户端,也不要把 Desktop 默认路径误当成 Tunnel 使用的 `--config` 路径。两个模式共用 CE Host/Storage 契约,不共用进程所有权。
|
|
11
|
-
|
|
12
|
-
## Tunnel:ChatGPT 自定义 MCP
|
|
13
|
-
|
|
14
|
-
先按 [Tunnel 指南](tunnel-setup.md)完成 `/ce-tunnel doctor`、Setup / Advanced Messaging、显式 reload/activate 与单独 Start。在 [ChatGPT Plugins](https://chatgpt.com/plugins)选择 **+ → Add custom MCP server → Connection: Tunnel**,选择相同 Tunnel,按目标配置认证,审阅风险后创建并安装插件;当前对话用 `@` 选择它。工具变更在插件详情刷新;不能只凭 CONNECTED 判断当前对话权限。资格及具体入口以[官方自定义 MCP 指南](https://developers.openai.com/api/docs/guides/custom-mcp-server)为准。下面仅适用于 Desktop 本地 stdio,不要混做。
|
|
15
|
-
|
|
16
|
-
## Desktop 适用条件与打包
|
|
17
|
-
|
|
18
|
-
要求:支持 local plugins 的 ChatGPT Desktop、macOS 或 Linux、Store-approved 精确 **Node.js 24.21.0 或 24.22.1**(还须满足完整 SQLite tuple/API 门槛)、仓库 pnpm 12.9.1。双版本此次实测为 macOS arm64,未新增 Linux/Desktop UI 验收。Desktop 插件使用 `plugin.json`、根 `mcp.json`、`${PLUGIN_ROOT}` 与本地 stdio;不要求公网 URL 或 Secure MCP Tunnel。
|
|
19
|
-
|
|
20
|
-
官方格式参考(客户端入口与组织资格以其当前文档为准):
|
|
21
|
-
|
|
22
|
-
- <https://developers.openai.com/plugins/deploy/desktop-only>
|
|
23
|
-
- <https://developers.openai.com/plugins/build/plugins>
|
|
24
|
-
|
|
25
|
-
在已选中批准 Node 的 shell,从仓库根目录安装依赖,然后打包(无需 mise):
|
|
26
|
-
|
|
27
|
-
```sh
|
|
28
|
-
node --version
|
|
29
|
-
pnpm install --frozen-lockfile
|
|
30
|
-
cd packages/pi-chat-exchange
|
|
31
|
-
pnpm run package:desktop-plugin
|
|
32
|
-
```
|
|
33
|
-
|
|
34
|
-
生成的 ignored artifacts:
|
|
35
|
-
|
|
36
|
-
- `.plugin-build/pi-chat-exchange-0.2.0.zip`:单根 ZIP。
|
|
37
|
-
- `.plugin-build/marketplace/`:可注册的本地 marketplace。
|
|
38
|
-
- `.plugin-build/pi-chat-exchange/`:解包检查副本。
|
|
39
|
-
|
|
40
|
-
包内含 compiled server 与生产依赖,不含 live Endpoint、Store、token、capability 或密钥。public directory 发布是独立流程,不能把本地 marketplace 安装解释成公开发布。
|
|
41
|
-
|
|
42
|
-
**本机运行时配置:** 分发 ZIP 和 marketplace 的 `mcp.json` 默认为空 server 集合,不包含机器路径,也不会执行未验证的 `node`。以下将完整 marketplace 复制到仓库外的新私有目录;已存在时应停止,不覆盖旧配置。将 Node 路径替换为本机可信批准 executable:
|
|
43
|
-
|
|
44
|
-
```sh
|
|
45
|
-
umask 077
|
|
46
|
-
mkdir -p "$HOME/.local/share"
|
|
47
|
-
MARKETPLACE="$HOME/.local/share/ce-marketplace-local"
|
|
48
|
-
mkdir -m 700 "$MARKETPLACE" && \
|
|
49
|
-
cp -R .plugin-build/marketplace/. "$MARKETPLACE/" && \
|
|
50
|
-
chmod 700 "$MARKETPLACE/plugins/pi-chat-exchange" && \
|
|
51
|
-
"/trusted/absolute/node" "$MARKETPLACE/plugins/pi-chat-exchange/server/configure.mjs" --node "/trusted/absolute/node"
|
|
52
|
-
```
|
|
53
|
-
|
|
54
|
-
插件根目录必须由当前操作者拥有且权限恰为 `0700`;根目录、祖先及 Node 的路径/ACL 全链都须通过信任门槛。配置器不自动修复权限或清 ACL。它验证完整 Node/SQLite 资格后只生成该副本的绝对 stdio command,不安装/注册/启动、不读取 binding 或 Store。目录可含空格;生成的 manifest 属本机配置,不可重新分发。仓库、ZIP、原始 marketplace 保持未配置;配置与注册必须使用同一副本。Secure Tunnel 用户无需此流程。
|
|
55
|
-
|
|
56
|
-
## 创建外置 binding
|
|
57
|
-
|
|
58
|
-
binding 留在插件安装/cache 之外,默认由系统账户 home 定位:
|
|
59
|
-
|
|
60
|
-
```bash
|
|
61
|
-
umask 077
|
|
62
|
-
mkdir -p "$HOME/.config/pi-chat-exchange"
|
|
63
|
-
# 目标已存在则停止,先核实原配置,不覆盖
|
|
64
|
-
test ! -e "$HOME/.config/pi-chat-exchange/mcp-binding.json" && \
|
|
65
|
-
test ! -L "$HOME/.config/pi-chat-exchange/mcp-binding.json" && \
|
|
66
|
-
cp plugin/pi-chat-exchange/config/binding.example.json \
|
|
67
|
-
"$HOME/.config/pi-chat-exchange/mcp-binding.json" && \
|
|
68
|
-
chmod 600 "$HOME/.config/pi-chat-exchange/mcp-binding.json"
|
|
69
|
-
```
|
|
70
|
-
|
|
71
|
-
下面是可解析的完整虚构示例,与 [Pi 指南](../pi-extension/README.md)的手工示例互补。路径与 Session placeholder 必须按本机授权替换;不要将示例当作已生效设置。payload/ACK 若未授权,分别保持 false。
|
|
72
|
-
|
|
73
|
-
```json
|
|
74
|
-
{
|
|
75
|
-
"version": 1,
|
|
76
|
-
"store": { "directory": "/srv/example-ce-store", "file": "ce-store.sqlite" },
|
|
77
|
-
"exchange": { "namespace": "example-local", "idempotencyKey": "example-chatgpt-pi" },
|
|
78
|
-
"endpoint": { "adapter": "chatgpt", "endpointId": "chatgpt/main" },
|
|
79
|
-
"recipients": [{ "adapter": "pi", "endpointId": "pi/main" }],
|
|
80
|
-
"lease": { "ttlSeconds": 120, "renewIntervalSeconds": 30 },
|
|
81
|
-
"payloadRead": { "enabled": false },
|
|
82
|
-
"ack": { "enabled": false },
|
|
83
|
-
"debugExecutionGuard": { "enabled": false }
|
|
84
|
-
}
|
|
85
|
-
```
|
|
86
|
-
|
|
87
|
-
Store directory 必须为规范化绝对 POSIX 路径且不是 `/`,本地文件系统与权限门槛见[Storage security](storage-security.md)(仅仓库,不随 tarball 分发)。lease renewal interval 不超过 TTL 一半。双方 Store directory/file、Exchange namespace/idempotencyKey 四项必须一致;Endpoint 与 Ownership 各自独立。模板中的旧标签不是强制名称。
|
|
88
|
-
|
|
89
|
-
launcher 固定读取 `~/.config/pi-chat-exchange/mcp-binding.json`,不从模型参数或环境变量选身份。仅本地包诊断支持 strict normalized absolute `--config`;shipped `mcp.json` 不传这个 override。缺失/非法配置为 `CE_MCP_CONFIG_INVALID`,不降级成任意身份。
|
|
90
|
-
|
|
91
|
-
## 注册与使用
|
|
92
|
-
|
|
93
|
-
按[官方本地 marketplace 流程](https://developers.openai.com/plugins/build/plugins),用支持该命令的 Codex CLI 注册上面已配置的同一私有目录(此处 `MARKETPLACE` 沿用前文同一 shell):
|
|
94
|
-
|
|
95
|
-
```sh
|
|
96
|
-
codex plugin marketplace add "$MARKETPLACE"
|
|
97
|
-
codex plugin marketplace list
|
|
98
|
-
```
|
|
99
|
-
|
|
100
|
-
重启支持本地插件的 ChatGPT Desktop,在 Plugins Directory 选择 **Pi Chat Exchange Local**,安装 **Pi Chat Exchange**,新建对话核对工具。客户端可能从 plugin cache 的安装副本加载;目录权限和本机 Node 在实际安装环境中仍须合格,不能用打包测试替代 UI 验收。
|
|
101
|
-
|
|
102
|
-
更新时重新打包,复制到新的私有目录、收紧嵌套 plugin 根目录为 `0700`、配置后再注册;刷新/重装并新建对话,旧对话不保证重载。缺少资格或菜单不同时按官方说明核实,不绕过组织限制,也不要改用 Tunnel 来证明 Desktop 安装成功。
|
|
103
|
-
|
|
104
|
-
## 针对性验收与结果边界
|
|
105
|
-
|
|
106
|
-
在独立授权、两端先加入同一 Exchange 后验证:
|
|
107
|
-
|
|
108
|
-
1. 新对话启用 Pi Chat Exchange,`ping` 得到 `status: "reachable"`。
|
|
109
|
-
2. 发现 base tools:`ping`、`ce_send`、`ce_inbox_list`、`ce_read_payload`。即使 payload read 关闭,MCP 仍广告该工具,但实际读取拒绝;这不同于 Pi 按 opt-in 注册工具。
|
|
110
|
-
3. `ack.enabled` exact true 时额外提供 `ce_ack`,否则不广告并拒绝调用;ACK 不顺带开启 payload read。
|
|
111
|
-
4. 按[消息流程](tunnel-setup.md#4-双向-send--inbox--read--ack)双向 send → 独立 list → 授权 read → 单独授权 ACK,明确每一步证据。
|
|
112
|
-
|
|
113
|
-
packaged artifact 测试验证 stdio/tool discovery,不证明 Desktop UI 安装成功。当前已完成的实际 ChatGPT↔Pi 消息及 Tunnel 启停验收见[README](../README.md);不能把 Tunnel 验收外推成每条 Desktop 安装路径都重新跑过。ACK 永远仅 reception,非 task completion。
|
|
114
|
-
|
|
115
|
-
## 显式 stale-ownership 恢复
|
|
116
|
-
|
|
117
|
-
正常 MCP/Pi 启动不接管已有 Owner。崩溃后 lease 到期也不自动接管;先由操作者核实进程确已丢失,再以只读连接检查准确 durable owner evidence。这是独立授权的恢复操作,**不是**通用启动前置步骤,也不是模型可调用工具。
|
|
118
|
-
|
|
119
|
-
CLI 在包目录,先 build;以下只是模板,不可直接执行,所有 `<...>` 都必须由操作者从已核实证据替换,不能猜测:
|
|
120
|
-
|
|
121
|
-
```bash
|
|
122
|
-
node scripts/recover-stale-ownership.mjs \
|
|
123
|
-
--config /absolute/path/to/operator-binding.json \
|
|
124
|
-
--confirm-endpoint '<adapter>/<endpointId>' \
|
|
125
|
-
--expect-owner-session '<exact-owner-session>' \
|
|
126
|
-
--expect-fencing-token '<exact-fencing-token>' \
|
|
127
|
-
--expect-lease-started-at '<exact-lease-start-or-null>' \
|
|
128
|
-
--expect-expires-at '<exact-expiry>' \
|
|
129
|
-
> /operator-controlled/path/recovery-receipt.json
|
|
130
|
-
```
|
|
131
|
-
|
|
132
|
-
直接调用批准 Node,避免 `pnpm run` 的 banner 污染重定向 receipt。六个 flags 必须匹配 durable row;`--confirm-endpoint` 是 `<adapter>/<endpointId>`,**不是** `ce_send.to` 的 label 用法。历史无 lease start 的迁移行才用 literal `null`。该 CLI 使用 MCP binding 选择恢复目标,不支持拿 Pi allowlist 文件替代;Pi Endpoint 的事故恢复需另行核实目标与授权。
|
|
133
|
-
|
|
134
|
-
CLI 拒绝 live lease、缺失/不符证据和并发 loser;成功时绑定 recovery Session,执行现有原子 takeover,再 release/detach,fencing 单调增加。receipt 不含 capability/host secret,但内部标识符仍不应公开。
|
|
135
|
-
|
|
136
|
-
| 固定码 | 意义与操作边界 |
|
|
137
|
-
|---|---|
|
|
138
|
-
| `CE_RECOVERY_LAUNCH_INVALID` / `INVALID_REQUEST` / `CONFIG_INVALID`(后两项同 `CE_RECOVERY_` 前缀) | flags、配置、目标路径或字段非法;核实输入,不猜值 |
|
|
139
|
-
| `CE_RECOVERY_TARGET_MISMATCH` / `OWNER_ABSENT` / `OWNER_MISMATCH`(同前缀) | 无目标 Participant、无 Owner 或证据不符;重新核实,不能放宽确认 |
|
|
140
|
-
| `CE_RECOVERY_OWNER_ACTIVE` / `CLOCK_REGRESSION`(同前缀) | lease 仍活跃或时钟先于持久 term;拒绝恢复 |
|
|
141
|
-
| `CE_RECOVERY_RACE_LOST` / `BUSY`(同前缀) | 并发赢家或事务冲突;本次未据此取得 authority |
|
|
142
|
-
| `CE_RECOVERY_FAILED` | 写入前 fail closed |
|
|
143
|
-
| `CE_RECOVERY_OUTCOME_UNKNOWN` | durable outcome 未知,停止并核实,绝不盲重试 |
|
|
144
|
-
|
|
145
|
-
exit 0 表示恢复成功,exit 1 仅向 stderr 输出固定拒绝码;不是消息或工作流完成。Tunnel process ownership 的恢复是另一套边界,不能用这个 CLI 清理 Manager 锁。
|
|
146
|
-
|
|
147
|
-
## 支持限制
|
|
148
|
-
|
|
149
|
-
Windows 不满足当前绝对 POSIX path contract。缺失批准 Node、权限不符、Store identity/版本不符均 fail closed,不自动初始化替代 Store。诊断不应输出 key、capability、正文、完整日志或真实 Session 信息。其他常见问题统一见[排障](tunnel-setup.md#故障排查先定位层再进行最小修复)。
|
|
@@ -1,86 +0,0 @@
|
|
|
1
|
-
# Private delivery ACK storage contract (E2-A)
|
|
2
|
-
|
|
3
|
-
The private storage contract was implemented in HANDOFF-CE-P3B-02 (E2-A). HANDOFF-CE-E2B-01 adds the operator-opt-in MCP/host surface described below without changing that storage contract. This document is not evidence of real ChatGPT dogfood or release.
|
|
4
|
-
|
|
5
|
-
## Meaning and authority
|
|
6
|
-
|
|
7
|
-
An ACK is an immutable recipient reception statement: one receipt plus one `receipt_recorded` audit. It is not proof of reading, understanding, processing, exactly-once delivery/execution, task recovery, or task completion. Wayforge retains governed task authority; Pi retains runtime/transport authority. `DELIVERY_UNKNOWN` does not become `CANCELLED`.
|
|
8
|
-
|
|
9
|
-
Private `recordDeliveryAck(store, input, seams?)` accepts exactly the host fields `participantId`, `sessionId`, `fencingToken`, `capability`, `exchangeId`, and copied Message metadata `messageId`, `payloadDigest`, `payloadLength`, `messageCreatedAuditSequence`. Inputs are captured once; unknown fields and invalid scalar types are refused without echoing values. These host authority fields are not a proposed public caller input.
|
|
10
|
-
|
|
11
|
-
Order within the existing owned transaction:
|
|
12
|
-
|
|
13
|
-
1. `BEGIN IMMEDIATE` acquires the SQLite writer lock.
|
|
14
|
-
2. Trusted post-lock time tA is sampled once.
|
|
15
|
-
3. Exact independent Session-bound `ack` capability and current Owner/Session/fence/lease authorize. Revocation, detached/unbound Session, wrong scope, expiry equality, and clock regression fail closed before Message/receipt/audit lookup.
|
|
16
|
-
4. Membership, stable recipient binding, immutable join boundary, exact creation audit, raw body SHA-256 and byte length are checked.
|
|
17
|
-
5. Natural key `(exchangeId, messageId, recipientParticipantId)` evidence is checked.
|
|
18
|
-
6. Equivalent evidence replays with zero writes. A first ACK requires OPEN Exchange without administrative disposition, and inserts the receipt/audit pair atomically.
|
|
19
|
-
7. Confirmed COMMIT precedes publication.
|
|
20
|
-
|
|
21
|
-
An operation valid at tA may commit after lease expiry; there is no commit-time reauthorization or renewal. The next expired call refuses even if a receipt exists.
|
|
22
|
-
|
|
23
|
-
## Evidence and projection
|
|
24
|
-
|
|
25
|
-
`CREATED` or `REPLAYED` returns `{disposition, receipt, receiptAuditSequence}`. The frozen public Receipt contains only `receiptId`, `exchangeId`, `messageId`, stable recipient `endpoint`, `kind: 'delivery_ack'`, `createdAt`. The actual protocol receipt prefix is **`rcpt_`**, not `rcp_`.
|
|
26
|
-
|
|
27
|
-
Private rows retain original acknowledging Session/fence/trust-generation, digest/length, exact Message creation sequence, time and revision=1. The audit subject is the receipt ID, outcome `delivery_ack`, with matching original digest/length/time. Receipt audit sequence is distinct from Message creation sequence. A new authorized Owner can replay original evidence; provenance is never rewritten. CLOSED existing receipt replay/query is allowed with current authorization/eligibility; CLOSED first ACK is refused.
|
|
28
|
-
|
|
29
|
-
Partial, duplicate or inconsistent evidence refuses; there is no repair, IGNORE or REPLACE. An orphan receipt audit cannot identify a Message by itself: an absent natural key conservatively refuses any orphan receipt audit in that Exchange. That additional integrity scan uses the existing correlation index but is not claimed constant-cost as receipt volume grows. No additional index is introduced.
|
|
30
|
-
|
|
31
|
-
## Uncertain outcome and read-only reconciliation
|
|
32
|
-
|
|
33
|
-
Private `reconcileDeliveryAck` has identical closed input, current authorization and eligibility. It returns original `{disposition:'COMMITTED', receipt, receiptAuditSequence}` or `{disposition:'NO_TRACE'}` with zero durable changes. It does not issue credentials, renew leases, restore ownership, retry ACK, send, cancel, or declare completion.
|
|
34
|
-
|
|
35
|
-
`NO_TRACE` is absence in that serialized snapshot only. A live original paused before BEGIN can later commit. Even proven original quiescence does not grant retry approval. There is no upper-layer retry orchestration in this implementation.
|
|
36
|
-
|
|
37
|
-
Proven rollback and `INDETERMINATE` remain distinct. Busy does not authorize retry. Uncertain COMMIT/rollback invalidates the old connection and withholds success. Fresh exact-authorized diagnosis after original quiescence examines durable evidence; it never manufactures missing evidence. A lost caller response can coexist with a complete committed pair.
|
|
38
|
-
|
|
39
|
-
## Isolation, pagination and privacy
|
|
40
|
-
|
|
41
|
-
ACK never changes Message/state/body/revision, attempt, claim, cursor, result, ownership, membership, task or transport state. Reads/discovery never implicitly ACK; ACK does not hide Messages. Receipt audits occupy raw inbox scan budget. Continuation remains the last raw sequence actually examined, not an ACK watermark or prefetch tail. Empty receipt-only pages can advance continuation without returning Messages; callers explicitly request subsequent pages.
|
|
42
|
-
|
|
43
|
-
No bodies, credentials, host secrets or arbitrary causes enter receipt/audit results, logs or errors. Private hooks are synchronous, value-free, capture defensively, reject unsupported results without inspecting them, and replace caller exceptions before domain-error translation. Test instrumentation is privileged, not a sandbox.
|
|
44
|
-
|
|
45
|
-
## MCP surface (HANDOFF-CE-E2B-01)
|
|
46
|
-
|
|
47
|
-
One opt-in MCP tool now exposes this committed storage contract. The private
|
|
48
|
-
storage functions, their ordering, and their guarantees above are unchanged.
|
|
49
|
-
|
|
50
|
-
- The tool is named `ce_ack`. Its closed input is exactly `{messageId,
|
|
51
|
-
payloadDigest, payloadLength, messageCreatedAuditSequence}`; unknown fields
|
|
52
|
-
and any authority-bearing field are rejected as JSON-RPC invalid params
|
|
53
|
-
before any port call. The digest, length, and creation sequence must be
|
|
54
|
-
copied from an authorized read (`ce_read_payload` returns exactly
|
|
55
|
-
`payloadDigest`, `payloadLength`, and the creation `auditSequence`) — never
|
|
56
|
-
computed or transformed by the caller or model.
|
|
57
|
-
- The host injects Participant, Session, fencing token, the Session-bound `ack`
|
|
58
|
-
capability, and the Exchange. The caller supplies no authority field, and the
|
|
59
|
-
capability is issued only while the operator opt-in is enabled (at
|
|
60
|
-
provisioning and at a validated `resume`); it is memory-only.
|
|
61
|
-
- Advertisement is operator opt-in only: the MCP binding configuration gains an
|
|
62
|
-
optional `"ack": { "enabled": boolean }` section, disabled by default. A
|
|
63
|
-
deployment without the opt-in advertises exactly `ping`, `ce_send`,
|
|
64
|
-
`ce_inbox_list`, `ce_read_payload`, and a `ce_ack` call there fails closed
|
|
65
|
-
(MethodNotFound). With the opt-in, `ce_ack` is listed last.
|
|
66
|
-
- A disabled policy refuses `CE_HOST_ACK_DISABLED` before registration state.
|
|
67
|
-
Storage refusals map through the existing sanitized host refusal set
|
|
68
|
-
(`CE_HOST_AUTHORITY_ABSENT`, `CE_HOST_INVALID_REQUEST`, `CE_HOST_BUSY`,
|
|
69
|
-
`CE_HOST_UNCERTAIN`, `CE_HOST_UNAVAILABLE`); `CE_HOST_UNCERTAIN` is never
|
|
70
|
-
retryable and must not be retried by the caller.
|
|
71
|
-
For ACK only, `CE_HOST_BUSY` preserves the original safe storage reason and
|
|
72
|
-
proven rollback classification, but both host and MCP report `retryable: false`
|
|
73
|
-
as caller policy: rollback does not authorize retry. Another ACK invocation
|
|
74
|
-
requires explicit operator or upper-layer approval; no retry is orchestrated.
|
|
75
|
-
Existing send/read refusal behavior is unchanged.
|
|
76
|
-
- The tool response is the frozen public Receipt projection plus `disposition`
|
|
77
|
-
and `receiptAuditSequence`: `CREATED` for the first ACK, `REPLAYED` with the
|
|
78
|
-
identical original receipt for an equivalent repeat. The acknowledging
|
|
79
|
-
Session, fencing token, trust generation, and capability never appear in any
|
|
80
|
-
result, refusal, or log.
|
|
81
|
-
- Recording an ACK still changes no Message delivery state, cursor, inbox
|
|
82
|
-
visibility, or task state, and remains a recipient reception statement
|
|
83
|
-
only — not proof of delivery, reading, understanding, processing, or task
|
|
84
|
-
completion.
|
|
85
|
-
|
|
86
|
-
See `storage-contract.md` for current-only v7 bootstrap/gates. Existing historical migration code remains immutable and is not an E2-A upgrade or normal-open path. Volume traversal tests establish bounded work/index use, not a production latency SLO or release authorization.
|
|
@@ -1,156 +0,0 @@
|
|
|
1
|
-
# 独立安装 Pi 扩展(0.2.0:managed npm 与 tarball 回退)
|
|
2
|
-
|
|
3
|
-
本指南是 **`@zieglar/pi-chat-exchange` 的正式独立分发方式**:消费者拿到一个预先构建的 npm tarball,物理安装后用 Pi 注册。它与两条旧路径互不替代:
|
|
4
|
-
|
|
5
|
-
| 路径 | 用途 | 区别 |
|
|
6
|
-
|---|---|---|
|
|
7
|
-
| **本文(tarball)** | 正式安装给日常使用 | 预构建运行时闭包;消费者**不需要**仓库、TypeScript、pnpm、tsconfig 或任何 build |
|
|
8
|
-
| 仓库源码 build + `pi install <目录>` | 开发者/Dogfood | 引用开发树目录,见 [README](../README.md) |
|
|
9
|
-
| Desktop 插件 ZIP | ChatGPT Desktop stdio MCP | 另一个打包脚本,见 [ChatGPT 安装](chatgpt-installation.md) |
|
|
10
|
-
|
|
11
|
-
本包版本为 **0.2.0**。CE 自有代码已获所有者 MIT 授权(Copyright (c) 2026 zieglar,见包内 LICENSE);第三方许可证证据已闭合,manifest 已按所有者条件移除 `private: true`。
|
|
12
|
-
|
|
13
|
-
原生 managed npm 路径为:先按下面步骤安装独立 Pi 1.3.0、设置批准 Node 与 npm,再执行 `"$CE_APPROVED_NODE" "$CE_PI_CLI" install npm:@zieglar/pi-chat-exchange@0.2.0`。Pi 将依赖物理安装到其作用域内的 npm 根;不要另装 consumer 目录或叠加 `-e`。0.2.0 的此命令证据是在隔离 loopback 测试 registry 上取得的,不是公共 npm 证据;依赖前先自行确认该精确版本在你信任的 registry 上确实可解析。
|
|
14
|
-
|
|
15
|
-
下文 tarball 是独立的资产回退:从发布方提供的 GitHub release asset 或私有安全交付取得预构建 `.tgz`,先核对 SHA256 再物理安装。不要把 asset URL 直接传给 Pi(URL 是 Git source),也不要将 monorepo Git source 当作本包 npm 安装。源码开发路径仍引用开发树。
|
|
16
|
-
|
|
17
|
-
## 0. 消费者前提
|
|
18
|
-
|
|
19
|
-
| 组件 | 要求 |
|
|
20
|
-
|---|---|
|
|
21
|
-
| Node | 精确 **24.21.0 或 24.22.1**(用户本地安装即可;mise 不是要求)。Pi host 与 MCP child 分别过 SQLite/运行时资格门槛 |
|
|
22
|
-
| npm | 11.x(随批准 Node 分发) |
|
|
23
|
-
| Pi | **1.3.0**,`pi` 可执行(全局安装或本地前缀均可) |
|
|
24
|
-
| 平台 | macOS arm64(Store allowlist;Linux x64 未在本路径验收) |
|
|
25
|
-
| Tunnel client | 可选。未安装时 `/ce-tunnel doctor` 会给出安全拒绝诊断(如 `CE_EXECUTABLE_UNTRUSTED`/缺失),这是预期行为,**不是**安装失败或兼容性证据 |
|
|
26
|
-
|
|
27
|
-
不需要:仓库 clone、pnpm、TypeScript、任何 consumer 侧 build/lifecycle 脚本(包内没有 install hooks;全程 `--ignore-scripts`)。
|
|
28
|
-
|
|
29
|
-
0.2.0 的认证目标仅 **Node 24.21.0 + Pi 1.3.0 + macOS arm64**;24.22.1 是已有运行时批准版本,不属于 0.2.0 的认证范围;Linux 未验证,cloud NOT_VERIFIED。
|
|
30
|
-
|
|
31
|
-
包管理器也必须使用批准 Node:将其 bin 目录置于 PATH 首位,先核对 `node --version` 为 v24.21.0、`npm --version` 为随该 Node 分发的 11.x;不要借用另一个全局 npm/Node。使用自己控制的 npm userconfig/globalconfig/cache,设置 `npm_config_ignore_scripts=true`,不要继承其他 registry 的 token;安装阶段才允许明确的 registry 下载,运行时不需要 registry 网络。本包无消费者 build 或 lifecycle hooks。
|
|
32
|
-
|
|
33
|
-
## 1. 生产者(作者侧,仅作者执行一次)
|
|
34
|
-
|
|
35
|
-
在完整 workspace 中构建并打包。作者必须已按 [README](../README.md) 冻结安装依赖。
|
|
36
|
-
|
|
37
|
-
```sh
|
|
38
|
-
# 仓库根目录,批准 Node 24.21.0/24.22.1 + pnpm 12.9.1
|
|
39
|
-
node --version
|
|
40
|
-
pnpm install --frozen-lockfile --ignore-scripts
|
|
41
|
-
pnpm --dir packages/pi-chat-exchange run package:pi-extension
|
|
42
|
-
# 产物:packages/pi-chat-exchange/.pi-artifacts/zieglar-pi-chat-exchange-0.2.0.tgz
|
|
43
|
-
# 可选自定义输出目录:node packages/pi-chat-exchange/scripts/package-pi-extension.mjs /path/to/out
|
|
44
|
-
```
|
|
45
|
-
|
|
46
|
-
该命令依次执行:`tsc` 构建 → 载荷校验(本地运行时 import 闭包、`new URL` 运行时资产、必需 native/运维脚本、无消费者 lifecycle hook)→ `npm pack --ignore-scripts` 前再校验原生清单,任何缺项都会 fail closed。**裸 `npm pack` 不是受支持的作者命令**:现在 `files` 白名单已覆盖,裸 pack 会包含 `dist/`,但它跳过上述全部载荷/闭包/清单校验,也无法产出可追溯的制品 SHA。
|
|
47
|
-
|
|
48
|
-
记录并随私有渠道交付:
|
|
49
|
-
|
|
50
|
-
```sh
|
|
51
|
-
shasum -a 256 packages/pi-chat-exchange/.pi-artifacts/zieglar-pi-chat-exchange-0.2.0.tgz
|
|
52
|
-
```
|
|
53
|
-
|
|
54
|
-
消费者**不要**重新构建或修改 tarball;如果需要新版本,请回到生产者步骤。
|
|
55
|
-
|
|
56
|
-
## 2. 消费者:物理安装 tarball 与 Pi 本体
|
|
57
|
-
|
|
58
|
-
把 tarball 放到消费者控制的目录(示例用 `~/ce-install`;路径可含空格与 scoped `node_modules/@scope` 形式,产品均已支持):
|
|
59
|
-
|
|
60
|
-
```sh
|
|
61
|
-
# 本地 consumer 根:安装私有包及其运行时依赖(全部物理落盘,无 symlink 外链)
|
|
62
|
-
npm install --prefix ~/ce-install/consumer --omit=dev --ignore-scripts --save-exact \
|
|
63
|
-
~/ce-install/zieglar-pi-chat-exchange-0.2.0.tgz
|
|
64
|
-
|
|
65
|
-
# 独立 Pi 本体(本指南必需,即使已有全局 Pi;同样禁用 lifecycle scripts)
|
|
66
|
-
npm install --prefix ~/ce-install/host --ignore-scripts --save-exact \
|
|
67
|
-
@earendil-works/pi-coding-agent@1.3.0
|
|
68
|
-
```
|
|
69
|
-
|
|
70
|
-
(可选)核对安装产物确实包含编译运行时与本地入口:
|
|
71
|
-
|
|
72
|
-
```sh
|
|
73
|
-
tar tzf ~/ce-install/zieglar-pi-chat-exchange-0.2.0.tgz | sort
|
|
74
|
-
# 必须看到 package/LICENSE、package/pi-extension/index.ts、package/dist/bin/mcp-stdio.js、
|
|
75
|
-
# package/dist/tunnel/multi-session-policy.js、package/native/tunnel-keychain.swift、
|
|
76
|
-
# package/scripts/recover-stale-ownership.mjs、package/scripts/reconcile-session-process-mutex.mjs
|
|
77
|
-
```
|
|
78
|
-
|
|
79
|
-
## 3. 消费者:注册到 Pi 并验证
|
|
80
|
-
|
|
81
|
-
```sh
|
|
82
|
-
# 填入本机批准 Node 的绝对路径(不是任意 PATH 中的 node)
|
|
83
|
-
CE_APPROVED_NODE=/absolute/path/to/approved/node
|
|
84
|
-
CE_PI_CLI="$HOME/ce-install/host/node_modules/@earendil-works/pi-coding-agent/dist/cli.js"
|
|
85
|
-
"$CE_APPROVED_NODE" --version # 必须精确为 v24.21.0 或 v24.22.1
|
|
86
|
-
"$CE_APPROVED_NODE" "$CE_PI_CLI" install ~/ce-install/consumer/node_modules/@zieglar/pi-chat-exchange
|
|
87
|
-
"$CE_APPROVED_NODE" "$CE_PI_CLI" list # 应列出上述物理安装目录
|
|
88
|
-
```
|
|
89
|
-
|
|
90
|
-
`pi install` 只登记已物理安装的本地包(Pi 不会替你安装依赖);不要对同一包再叠 `-e` 加载第二份。本地 `npm install --prefix` 的 bin 链接在 `host/node_modules/.bin/pi`,不是 `host/bin/pi`。下文所有 `pi` 命令统一使用 `"$CE_APPROVED_NODE" "$CE_PI_CLI"`(无子命令即启动 TUI),避免 shebang 误用 PATH 中未批准的 Node 或另一个全局 Pi。Host 与 MCP child 均须分别通过运行时资格诊断;本路径实测 Node 24.21.0,24.22.1 是批准版本但不在此次安装实测范围。
|
|
91
|
-
|
|
92
|
-
首次运行(在工作目录启动 `pi`,交互 TUI 中按顺序执行;每步都有显式确认):
|
|
93
|
-
|
|
94
|
-
```text
|
|
95
|
-
/ce-tunnel doctor # 只读资格诊断;client 未装 → 安全拒绝是预期,不算失败
|
|
96
|
-
/ce-tunnel setup # Tunnel ID → Organization(可空) → masked API key → Advanced ·
|
|
97
|
-
# Messaging 授权本 Session → Review → Confirm → Save
|
|
98
|
-
/ce-tunnel convert # 转为 multi-session;保留当前 native Session 的原 endpoint
|
|
99
|
-
/new # 若要登记不同 endpoint,必须先新建 native Session
|
|
100
|
-
/ce-tunnel register pi/distribution # 为新 Session 登记不同的稳定 endpoint;不启动传输
|
|
101
|
-
/reload # 载入新 policy(首 reload 可能报 mapping 拒绝,随后显式 activate)
|
|
102
|
-
/ce-tunnel activate # 确认框默认 Cancel,必须下移选择 "Activate current session"
|
|
103
|
-
/ce-status
|
|
104
|
-
/ce-tunnel deactivate # 正常释放本 Session 绑定;登记与历史保留
|
|
105
|
-
```
|
|
106
|
-
|
|
107
|
-
最后的 `/ce-tunnel deactivate` 是验证正常解绑的演示,不是发消息前置步骤。若接下来要做首次消息验证,暂不执行该行、保持已授权 binding;若已停用则重新显式 activate。安装本身不证明云端可用:另行获准后按 [Tunnel 双向消息验证](tunnel-setup.md#4-双向-send--inbox--read--ack)完成 client/ChatGPT 连接、显式 Start 与独立 read/ACK;不得把离线合成流程当作真实云端验收。
|
|
108
|
-
|
|
109
|
-
`convert` 不会清空或重命名原登记:若复用原 Session 和原 endpoint,省略 `/new` 与不同 endpoint 的 `register`,继续 reload/activate 即可;同一 native Session 尝试登记另一个 endpoint 会被拒绝。上列实测流程选择 `/new` 后为新 Session 登记 `pi/distribution`,原登记保留。
|
|
110
|
-
|
|
111
|
-
`CE_TUNNEL_PROFILE` 指定 profile 文件的规范化绝对路径(不是目录);Setup 将凭据保存在该文件所在目录的 `.credentials/` 下(默认见 [Tunnel 指南](tunnel-setup.md#配置模型与生成文件));凭据以 owner-only 文件(0600,0700 目录)落盘,绝不明文进 profile。Configured ≠ Pi-bound ≠ Connected;启动真实 Tunnel 仍需 `CE_TUNNEL_BACKGROUND_ALLOW=1` 与显式 `/ce-tunnel start`,见 [Tunnel 用户指南](tunnel-setup.md)。
|
|
112
|
-
|
|
113
|
-
多 Endpoint / 多 Session 的注册、解绑与撤销语义见 [多 Session 使用指南](multi-session-usage.md)。
|
|
114
|
-
|
|
115
|
-
### 本指南已验证的范围与未验证项
|
|
116
|
-
|
|
117
|
-
上述首次运行序列已在真实安装 + 独立 Pi 1.3.0 + 真实 PTY 上验证到:安装、Host 加载、首次保存、转换、注册、激活、停用,以及磁盘持久状态(profile/凭据权限、策略登记、互斥释放、合成 Store 模式)。验证环境为**离线合成模式**:`PI_OFFLINE=1`、未安装真实 Tunnel client(doctor 会给出 `CE_EXECUTABLE_UNTRUSTED` 安全拒绝,这是预期诊断,不是兼容性或就绪证据)。**真实云传输(CLOUD_TRANSPORT)未验证**:需要单独安装可信 client、`CE_TUNNEL_BACKGROUND_ALLOW=1` 与显式 `/ce-tunnel start`,不属于本指南的验证范围。
|
|
118
|
-
|
|
119
|
-
## 4. 信任与安全注意
|
|
120
|
-
|
|
121
|
-
- Pi 扩展以你的完整用户权限运行;安装前审查源码与制品来源。`--ignore-scripts` 只限制安装脚本,不会隔离扩展运行时权限。
|
|
122
|
-
- tarball 为私有交付;安装前核对 SHA256,必要时 `tar tzf` 抽查(上面的必需文件清单即核对锚点)。
|
|
123
|
-
- 全程 `--ignore-scripts`:本包没有也不需要任何 install/prepack/prepare hook。
|
|
124
|
-
- 安装后的依赖树全部物理存在于 consumer 前缀内(内部 bin symlink 属正常;不应出现指向外部/开发树的链接)。
|
|
125
|
-
- Desktop ZIP 与本路径不通用;不要混装同一 Endpoint。
|
|
126
|
-
- 卸载、升级、回滚必须遵守下方安全步骤;退出 Pi 不等于停止后台 transport。
|
|
127
|
-
|
|
128
|
-
### 依赖与 Host 提供的运行时包
|
|
129
|
-
|
|
130
|
-
本包声明 `peerDependencies: { "@earendil-works/pi-coding-agent": "1.3.0" }`:tarball 前缀安装时 npm 会把该精确版本装入 consumer 树(原生 managed npm 使用 `--legacy-peer-deps` 抑制 peer 自动安装;Host 从独立 1.3.0 树提供),满足 `pi-tui-kit` 的 `"*"` peer,避免自动拉入与 Host 不同代的完整 Pi 运行时(例如 1.4.x)。`@earendil-works/pi-tui` 与 `@sinclair/typebox` 保留为**锁定版本的 dependencies**(不是 peer):编译后的 ESM(TUI 键序、TypeBox 运行时校验)在本地包模式下必须能从安装树物理解析,盲改为 `"*"` peer 会让 npm 拉最新版本、引入与 1.3.0 Host 的代差。代价是 Pi 启动时会提示“Host 提供的包应声明为 peerDependencies”的警告——这是当前分发架构的已知权衡(两份同版本运行时代码副本),不影响加载与首次运行;重新设计 host 映射不属于本指南范围。
|
|
131
|
-
|
|
132
|
-
## 5. 安全卸载、升级与回滚
|
|
133
|
-
|
|
134
|
-
以下是人工前置条件,不是新增卸载 CLI,也不是全机 Session 扫描授权。先用 `pi list` 记录精确 source 及 personal/project 作用域、实际包根、批准 Node/Pi/npm、profile、Store/Exchange 与有关 Session/进程。不要依据历史 PID 或文件名发信号。
|
|
135
|
-
|
|
136
|
-
1. 在可证明拥有目标实例的 Manager 中显式 `/ce-tunnel stop`;再独立 `/ce-tunnel status`,必须确认退出完成且 **STOPPED**。`/ce-tunnel doctor` 仅是资格诊断,不是退出证明。外部 Owner、UNKNOWN、STOP_UNCONFIRMED、未知 lease/lock 一律停止操作,不删目录、不 bulk kill、不重试未知结果。没有启动过 transport 也要核实 STOPPED;不要为卸载启动它。
|
|
137
|
-
2. 对每个受影响的、自己拥有的本地绑定,执行 `/ce-tunnel deactivate` 并确认正常 release/detach;用 `/ce-status` 核对。不使用 revoke 或 Recovery 替代正常释放。未确认释放、证据写入失败或 UNKNOWN 都停止。
|
|
138
|
-
3. 与其他使用者确认目标包/Node 前缀、profile、Store、后台实例及共享资源不再被依赖;其他独立 Session 或其他安装仍依赖时,必须在原生 remove 前 STOP:不得卸载、取消注册或删除相关目录。现有命令**不能自动证明**全机/其他用户均不再使用;不能确认就 STOP,保留现场,不擅自停止他们的 Session。
|
|
139
|
-
4. 正常退出所有相关、自己拥有的 Pi Hosts(包括仍能加载旧代码者),确认退出完成;退出本身不替代前述 transport Stop。保持其他无关 Session 不变。
|
|
140
|
-
5. 使用记录的原生 Pi source 和同一作用域移除:
|
|
141
|
-
|
|
142
|
-
```sh
|
|
143
|
-
# 仅适用于原生 managed npm 安装(0.2.0 的安装证据来自私有 loopback registry)
|
|
144
|
-
"$CE_APPROVED_NODE" "$CE_PI_CLI" remove "npm:@zieglar/pi-chat-exchange@0.2.0"
|
|
145
|
-
"$CE_APPROVED_NODE" "$CE_PI_CLI" list
|
|
146
|
-
# 若原来是 --local 安装,remove 同样加 --local,勿扩大到其他作用域。
|
|
147
|
-
# tarball/源码目录路线:remove 后面的参数必须改为 pi list 中原始绝对目录 source。
|
|
148
|
-
```
|
|
149
|
-
|
|
150
|
-
Pi 1.3.0 的 `removeAndPersist` 先执行原生 remove 再取消声明;npm source 由 `uninstallNpm` 调用 npm uninstall,**已删除** managed 包文件。不要再对 Pi managed 根执行 rm/npm uninstall;该根可承载其他扩展。local-directory source 仅取消注册,不删除其原目录。remove 部分失败或登记持久化未确认时同样 STOP,保留证据,不盲重试或手工删目录。
|
|
151
|
-
|
|
152
|
-
6. 只有对独占、自己拥有、已证实无其他依赖的 **tarball consumer 或专用 host 前缀**,才可以另行人工删除该前缀;不要删除共享 Node、Pi managed 根、其他安装或源代码树。任何归属/依赖不明均不删。默认保留 Store(含 WAL/SHM/host-secret)、profile、凭据、bindings、history 及状态/日志证据,勿 purge、删锁、清理 Owner 或重发未 ACK 消息。
|
|
153
|
-
|
|
154
|
-
升级:先记录并保留原精确版本制品、SHA256、安装 source、锁文件与配置位置,按上述停止/释放/退出流程,再用原生 Pi remove 旧精确 source、install 新精确版本;tarball 路线物理安装到新的独占 consumer 前缀再注册,避免覆盖仍使用的目录。重新启动 Host 后 doctor/status,核对选中配置和 Store,再显式 activate,不自动 Start。
|
|
155
|
-
|
|
156
|
-
回滚/重装:先确认目标版本的 Store/schema/运行时兼容性;未知即 STOP,不降级、覆盖或删除 Store。兼容且获准后按同一停止/释放/退出流程移除当前版本、重装留存的精确旧制品/版本、核对真实加载路径与配置。重装 0.2.0 使用相同精确 npm source;保留配置不等于自动重新授权,仍须显式 activate。缺 ACK、超时或 DELIVERY_UNKNOWN 不是重试许可。
|