@zieglar/pi-chat-exchange 0.2.0 → 0.2.1

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.
@@ -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 不是重试许可。
@@ -1,77 +0,0 @@
1
- # 一个 Tunnel,多个项目与 Pi Session
2
-
3
- 每个真实 Pi Session 使用独立、稳定的 Endpoint,例如 `pi/project-A` 与 `pi/project-B`。项目目录不是身份;同一个项目也可有多个 Session,必须分别注册。ChatGPT 侧 `chatgpt/main` 是明确共享的 inbox,**不是 ChatGPT 对话隔离**。
4
-
5
- 先完成 [Tunnel 首次设置](tunnel-setup.md)。下面的配置操作不发送/读取/ACK 消息,也不会自动启停 Tunnel。
6
-
7
- ## 1. 从单 Session 显式转换
8
-
9
- 已有 single-session 配置可以继续使用,不必强制转换。需要多 Session 时:
10
-
11
- 1. 显式 `/ce-tunnel stop`,核实 transport **STOPPED**。ACTIVE/UNKNOWN 均拒绝转换,不自动 Stop。
12
- 2. 关闭所有旧 legacy Pi binding/runtime,或先更新并正常释放其 binding。旧二进制不能被新 revocation gates 约束,不能仅凭新配置就认为它们被撤销。
13
- 3. 当前旧 Session 可用 `/ce-tunnel deactivate` 确认正常解绑,不退出 Pi、不删历史、不停止 transport。未知释放停止操作,不“清理” Owner。
14
- 4. 从**未绑定**的交互 TUI 运行 `/ce-tunnel convert`;明确承认旧 runtime 限制并核对保留原 registration、Store、Exchange 与 grants。仍本地持有 legacy binding 时拒绝。
15
-
16
- 转换不创建新的默认宽权限,也不自动绑定保留的 legacy registration。
17
-
18
- ## 2. 在每个真实 Session 注册 Endpoint
19
-
20
- 从需要授权的那个 Pi Session 执行,Endpoint 必须与其他 Session 不同:
21
-
22
- ```text
23
- /ce-tunnel register pi/project-B --payload-read --ack
24
- ```
25
-
26
- - 仅注册当前可信 native Pi Session,不接受手填别的 Session ID;实际绑定仍需 reload 后显式 activate。
27
- - `--payload-read` 与 `--ack` 独立可选,默认都 **off**;不要为了照抄示例就开启。
28
- - 在确认前核对 Endpoint、当前 Session、Store、Exchange 与权限。
29
- - register/revoke/convert 需 verified STOPPED transport;不会替你 Stop/Start,不要求重输原 credential。
30
-
31
- 使用不同项目时加载同一份扩展和同一所选 profile;不要在各项目初始化独立 Store 后期待自动路由。显式非空 `CE_ALLOWLIST` 保留 legacy 优先级,并阻止生成策略注册/转换。
32
-
33
- ## 3. 分别加载与激活
34
-
35
- ```text
36
- /reload
37
- /ce-tunnel activate
38
- /ce-status
39
- ```
40
-
41
- 首次注册没有 CE mapping,reload 拒绝 `CE_HOST_MAPPING_INVALID` 可以是预期行为;随后显式 activate 并确认,以 requireUnowned 创建该 Session 的绑定。它不是 recovery,不接管已有 Owner,包括 expired Owner。
42
-
43
- Pi grants 在 factory 加载时捕获,Save/register 不自动扩大旧运行时权限。MCP child 也需单独显式 `/ce-tunnel start`(此前已 Stop)读取所选 generation;不要把 Pi reload 视为远端 MCP reload。
44
-
45
- `/ce-status` 中 native Pi Session 是 lookup,CE Session 是 Owner incarnation;Endpoint 是稳定消息 label,Participant 是 Exchange 中的参与者。lease/fencing 描述当前权威,不是 transport health。**Configured ≠ Pi-bound ≠ Connected ≠ 消息实证。**
46
-
47
- ## 4. 找到可用收件人
48
-
49
- 在当前已绑定、经授权的 multi-session runtime:
50
-
51
- ```text
52
- /ce-tunnel sessions
53
- ```
54
-
55
- 它列出所选配置中 active 的精确 Endpoint IDs,可复制为 `ce_send.to`。它仍需当前 runtime、所载 registration epoch、current policy 与 process mutex 全部准入。未绑定、未加载、revoked、stale 或 uncertain 均拒绝,不列出其他目标。
56
-
57
- 该列表不读 Inbox,不证明 MCP child 已加载,也不证明消息已被接收;`to` 不使用 native/CE Session ID,不额外拼 adapter。ChatGPT 仍共享自己的历史/inbox,需操作者明确选择每次消息的收件 Endpoint。
58
-
59
- ## 5. 区分解绑、撤销、停止与 reload
60
-
61
- | 操作 | 改变什么 | 不做什么 |
62
- |---|---|---|
63
- | `/ce-tunnel deactivate` | 确认后正常释放当前本地 CE Owner、detach 并停续租 | 不撤销 registration、不删历史、不 Stop Tunnel、不结束其他 Session |
64
- | `/ce-tunnel revoke pi/project-B` | 确认后撤销一个确切稳定 registration 的后续准入,需 STOPPED | 不回滚已准入操作、不自动释放 durable Owner、不删消息 |
65
- | `/ce-tunnel stop` | 停止可证明属于 Manager 的 transport 实例 | 不代表 Pi Owner 已释放或 registration 已撤销 |
66
- | 有效 binding 的 `/reload` | 停旧 generation/drain,重验并 resume 原 durable mapping | 不创建额外 Owner、不自动 takeover |
67
- | 已释放/未绑定 Session 的 `/reload` | 加载策略,仍不自动重绑 | 重新绑定须显式 activate;不能靠 reload 复活已结束 CE Session |
68
-
69
- 取消 deactivate 保留绑定;重复调用不重复 end。release/end 或证据持久化未知时保持 fail-closed,不把“无本地 handle”说成安全释放。正常退出/Session replacement 也走正常 end;正常 end/release 绕过 deny-only revocation 检查,便于安全归还权威。
70
-
71
- 撤销只挡之后新准入的操作(包括 reads/renew);已准入操作可能完成。其他 registrations 和共享 ChatGPT 历史保留。重新授权使用 fresh epoch,旧 handle 仍拒绝。不要删旧注册/Owner/Store 来“重置”。
72
-
73
- ## 安全与恢复限制
74
-
75
- process guard 只做本地 exclusion,不是 CE authority 或 crash recovery。旧 registration epoch 不能复用 reload handoff;不确定清理保留 marker 与 failure latch。append-only records 可累积,没有自动回收,即使进程已死也不自动接管。需要恢复时另行授权、核实精确 durable evidence。
76
-
77
- 本页不启用自动 Inbox polling、payload execution、ACK、重试或 Wake Bridge。真实消息与 ACK 每次仍需授权;本地配置/隔离测试不替代真实用户验收。更多见 [Pi 工具指南](../pi-extension/README.md)与[排障](tunnel-setup.md#故障排查先定位层再进行最小修复)。