@hex4c59/pi-ext-config-sync 0.1.0 → 0.1.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/CHANGELOG.md CHANGED
@@ -1,5 +1,34 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.1.2 - 2026-11-19
4
+
5
+ ### Fixed
6
+
7
+ - `/sync login` 及所有联网命令在 GitHub 间歇不可达时只报 `Error: fetch failed`。根因是原来使用全局 `fetch`:它只接受约 10 秒的固定连接超时,不重试,也不读取系统代理。实测同一直连条件下 40 次请求有 30 次连接超时。
8
+ - 改用扩展自带的 HTTP 传输层:连接超时 20 秒,网络类失败最多重试 4 次,HTTP 状态码错误不重试。
9
+ - 设备码登录期间单次轮询失败会继续等待,连续 6 次失败才停止并说明原因。
10
+ - 失败提示不再只有 `fetch failed`,会区分 DNS 失败、连接被拒和超时,并说明当前代理与设置方式。
11
+
12
+ ### Added
13
+
14
+ - 代理选择顺序为 `config.json` 的 `proxy`、`HTTPS_PROXY` / `HTTP_PROXY` 环境变量、Windows 系统代理,最后直连;`NO_PROXY` 中的主机跳过代理。
15
+ - `/sync proxy <url>`、`/sync proxy default` 和 `/sync ping`;`/sync status` 增加当前代理来源。
16
+ - 指定或探测到的代理端口没有监听时,命令立即报告该代理不可用,而不是等待请求超时。
17
+ - `transport.ts` 与 `proxy.ts` 及对应测试。
18
+
19
+ ### Notes
20
+
21
+ - 每次 `/sync` 命令开始时重新读取代理设置,修改代理程序或系统设置后不需要重启 Pi。
22
+ - 只支持 HTTP / HTTPS 代理,不支持 SOCKS。
23
+
24
+ ## 0.1.1 - 2026-11-17
25
+
26
+ ### Changed
27
+
28
+ - 内置设备码登录的 OAuth App Client ID,新设备直接运行 `/sync login`,无需逐台执行 `/sync setup`。
29
+ - 已保存的自定义 Client ID 继续优先;`config.json` 中为空或只有空白时回退到内置值。
30
+ - README 更正 npm 包加载方式:`settings.json` 中的 `packages` 由 Pi 在启动或 `/reload` 时安装。
31
+
3
32
  ## 0.1.0 - 2026-11-17
4
33
 
5
34
  ### Added
package/README.md CHANGED
@@ -1,224 +1,247 @@
1
- # config-sync
2
-
3
- 把选定范围的 Pi 配置和加密后的 API 密钥同步到一个私有 GitHub 仓库。每台设备登录同一个 GitHub 账号后,用 `/sync pull` 拉取配置,用 `/sync push` 上传改动。
4
-
5
- ## 登录方式
6
-
7
- 这个扩展使用 GitHub 设备码登录,不需要 Google 账号。Google 登录只能证明“你是谁”,不能授权写入某个 GitHub 仓库;要访问仓库,仍然必须由 GitHub 发放令牌。
8
-
9
- 设备码流程适合没有浏览器的场景:Pi 显示一个网址和一次性代码,在任意浏览器里输入代码并授权即可。扩展只保存 GitHub 返回的访问令牌,不接触 GitHub 密码。
10
-
11
- ## 安装
12
-
13
- 正式安装:
14
-
15
- ```bash
16
- pi install npm:@hex4c59/pi-ext-config-sync
17
- ```
18
-
19
- 从源码开发时,在仓库根目录临时加载:
20
-
21
- ```bash
22
- pi -e ./config-sync
23
- ```
24
-
25
- ## 准备 GitHub OAuth App
26
-
27
- 每个使用者需要自己的 OAuth App,扩展不内置客户端凭据。
28
-
29
- 1. 打开 GitHub 的 `Settings` → `Developer settings` → `OAuth Apps` → `New OAuth App`。
30
- 2. 填写名称、主页地址和 `Authorization callback URL`。设备码流程不使用回调地址,填一个可访问的地址即可,例如 `https://github.com`。
31
- 3. 创建后在应用设置里勾选 `Enable Device Flow`。
32
- 4. 复制 `Client ID`。不需要 `Client Secret`。
33
-
34
- 然后在 Pi 中保存客户端 ID:
35
-
36
- ```text
37
- /sync setup <client-id>
38
- ```
39
-
40
- 客户端 ID 不是密钥,会写入本机的 `~/.pi/agent/config-sync/config.json`。
41
-
42
- ## 第一次使用
43
-
44
- 第一台设备:
45
-
46
- ```text
47
- /sync setup <client-id>
48
- /sync login
49
- /sync push
50
- ```
51
-
52
- `/sync login` 会显示 `https://github.com/login/device` 和一次性代码,并把代码复制到剪贴板。授权完成后,令牌保存在 `auth.json` 中。
53
-
54
- `/sync push` 默认使用 `<GitHub 登录名>/pi-config`。仓库不存在时,会在确认后创建为私有仓库。第一次推送凭据时,需要设置一个至少 8 个字符的口令;仓库里保存的是用该口令加密的 `secrets.enc`,不保存口令本身。
55
-
56
- 第二台设备:
57
-
58
- ```text
59
- /sync setup <client-id>
60
- /sync login
61
- /sync pull
62
- ```
63
-
64
- 拉取完成后,按提示重载 Pi。
65
-
66
- 也可以显式指定仓库和分支:
67
-
68
- ```text
69
- /sync repo <owner/name>
70
- /sync branch <name>
71
- /sync repo default
72
- /sync branch default
73
- ```
74
-
75
- 回退到默认值会清除本机记录的上次同步基准,下一次拉取或推送会重新比较全部文件。
76
-
77
- ## 命令
78
-
79
- | 命令 | 作用 |
80
- | --- | --- |
81
- | `/sync help` | 显示命令列表 |
82
- | `/sync setup <client-id>` | 保存 GitHub OAuth App 的 Client ID |
83
- | `/sync login` | 开始 GitHub 设备码登录 |
84
- | `/sync logout` | 删除 `auth.json` 中的 GitHub 令牌 |
85
- | `/sync status` | 显示登录、仓库、分支、自动拉取和上次同步信息,不联网 |
86
- | `/sync pull [--force]` | 从 GitHub 下载配置;`--force` 用远端覆盖所有冲突文件 |
87
- | `/sync push [--force] [--yes]` | 上传配置;`--force` 覆盖远端冲突,`--yes` 跳过推送前确认 |
88
- | `/sync repo <owner/name>` | 设置仓库 |
89
- | `/sync branch <name>` | 设置分支 |
90
- | `/sync auto on` | 启动时自动拉取,不弹确认 |
91
- | `/sync auto off` | 关闭自动拉取 |
92
-
93
- ## 同步范围
94
-
95
- | 路径 | 内容 |
96
- | --- | --- |
97
- | `settings.json` | Pi 设置;同步前去掉本机专用字段 |
98
- | `models.json` | 自定义模型与 provider 定义 |
99
- | `mcp.json` | MCP 服务器定义 |
100
- | `keybindings.json` | 按键绑定 |
101
- | `AGENTS.md` | 全局项目说明 |
102
- | `SYSTEM.md`、`APPEND_SYSTEM.md` | 系统提示词 |
103
- | `themes/` | 主题 |
104
- | `prompts/` | 提示词模板 |
105
- | `skills/` | Skill 源文件 |
106
-
107
- `settings.json` 中的 `shellPath`、`lsp`、`lastChangelogVersion`、`extensionChangelogVersions` 和 `sessionDir` 默认保留为本机值,不参与同步。这个列表可以在 `config.json` 的 `localSettingsKeys` 中修改。
108
-
109
- 不参与同步的内容:
110
-
111
- - 以 `.` 开头的文件和目录,以及 `.DS_Store`、`Thumbs.db`、`.git`、`node_modules`
112
- - 符号链接
113
- - 超过 10 MB 的单个文件
114
- - 总计超过 2000 个文件或 50 MB 的内容
115
- - `auth.json` 中的 OAuth 凭据和未列入范围的 provider
116
-
117
- ## 凭据同步
118
-
119
- 只同步 `auth.json` 中形如 `{"type":"api_key","key":"..."}` 的条目。默认排除使用设备登录或本机客户端凭据的 provider:`github-copilot`、`qoder`、`qoder-cn`、`trae-cn`、`workbuddy`、`workbuddy-ai`,以及本扩展自己的 `config-sync` 令牌。
120
-
121
- `config.json` 中的过滤字段:
122
-
123
- ```json
124
- {
125
- "includeAuthProviders": [],
126
- "excludeAuthProviders": ["config-sync", "github-copilot", "qoder", "qoder-cn", "trae-cn", "workbuddy", "workbuddy-ai"]
127
- }
128
- ```
129
-
130
- - `includeAuthProviders` 非空时,只同步其中的 provider。
131
- - 显式包含可以覆盖排除,但条目仍必须是合法的 `api_key` 形状。
132
- - 不支持同步 OAuth、设备码或其他非 `api_key` 条目。
133
-
134
- 加密格式:
135
-
136
- - 口令经 scrypt 派生密钥,参数 `N=32768, r=8, p=1`,16 字节随机盐。
137
- - 数据用 AES-256-GCM 加密,12 字节随机 IV,16 字节认证标签。
138
- - 加密文件为 `secrets.enc`,明文只在内存中出现。
139
-
140
- 口令不会写入磁盘、仓库或日志。口令丢失后无法解密仓库中的旧凭据;此时删除仓库里的 `secrets.enc`,再推送一次即可设置新口令。
141
-
142
- `models.json` 和 `mcp.json` 在推送前会做明文检查:
143
-
144
- - `models.json` 中值为明文的 `apiKey` / `api_key` 会阻止推送;`$ENV_NAME` 和 `!command` 引用允许通过。
145
- - `mcp.json` 中 URL 自带的用户名密码、以及 `headers` / `env` 中名称像密钥的明文值会阻止推送;`${VAR}` 和 `!command` 引用允许通过。
146
-
147
- 这是启发式检查,不能证明文件里没有其他形式的密钥。推送前仍应自行确认。
148
-
149
- ## 冲突处理
150
-
151
- 扩展在本机记录上次同步的提交和文件哈希,用“上次基准 / 本机 / 远端”三方比较:
152
-
153
- - 只有远端变化:拉取时写入远端版本。
154
- - 只有本机变化:拉取时保留本机版本,推送时上传本机版本。
155
- - 两边都变化:拉取时询问“全部用远端”“全部保留本机”或逐文件选择;推送时默认拒绝,需要先拉取,或用 `--force` 覆盖远端。
156
- - 新设备没有基准:远端独有文件直接写入,本机独有文件保留。
157
- - 远端删除且本机未改动:拉取时删除本机文件;本机删除且远端未改动:推送时删除远端文件。
158
-
159
- 除 `settings.json` 外,文本和二进制文件都按整文件覆盖,不做行级合并。`settings.json` 拉取时会把远端内容与本机专用字段合并后再写入。
160
-
161
- 推送会用完整的文件列表创建提交,因此仓库必须专门用于 config-sync。向已有其他文件的仓库推送会替换整个文件树;首次遇到不是 config-sync 创建的仓库时,扩展会要求确认。
162
-
163
- ## 自动拉取
164
-
165
- `/sync auto on` 后,Pi 以 TUI 模式启动时会在后台拉取一次:
166
-
167
- - 不弹冲突确认,遇到冲突会跳过并提示手动运行 `/sync pull`。
168
- - 不处理凭据;`secrets.enc` 有变化时只提示手动拉取。
169
- - 有文件更新时提示 `/reload`。
170
-
171
- 自动拉取不会推送,也不会在 `session_start` 以外的时机运行。
172
-
173
- ## 本机文件与备份
174
-
175
- | 路径 | 内容 |
176
- | --- | --- |
177
- | `~/.pi/agent/auth.json` | GitHub 令牌,provider ID 为 `config-sync` |
178
- | `~/.pi/agent/config-sync/config.json` | 客户端 ID、仓库、分支和过滤设置 |
179
- | `~/.pi/agent/config-sync/state.json` | 设备 ID、登录名、上次同步提交与文件哈希 |
180
- | `~/.pi/agent/config-sync/backups/<时间>/agent/` | 拉取覆盖或删除前的本机文件 |
181
-
182
- 备份最多保留 10 份,只复制实际存在且会被覆盖或删除的普通文件。需要回滚时,把备份目录中的文件复制回 `~/.pi/agent/` 对应位置。
183
-
184
- `state.json` 损坏时会被重命名为 `state.json.corrupt-<时间>`,然后生成新的设备 ID 和空基准。下一次拉取会按新设备处理。
185
-
186
- ## 网络请求
187
-
188
- 扩展只访问以下域名:
189
-
190
- | 域名 | 用途 |
191
- | --- | --- |
192
- | `github.com` | 设备码申请、令牌轮询 |
193
- | `api.github.com` | 用户信息、仓库、Git tree / blob / commit / ref |
194
-
195
- 请求使用固定的 `User-Agent: pi-config-sync`,单次超时 30 秒。GitHub 令牌通过 `Authorization: Bearer` 头发送,不写入日志或错误信息。除 GitHub 外不发送配置内容。
196
-
197
- ## 安全边界
198
-
199
- - GitHub 令牌拥有 `repo` 范围,能读写该账号的私有仓库。令牌保存在 `auth.json`,卸载扩展不会自动删除;需要清除时先运行 `/sync logout`。
200
- - 仓库默认必须是私有仓库。只有手动把 `allowPublicRepo` 设为 `true` 才允许推送公开仓库;公开仓库中的 `secrets.enc` 仍受口令保护,但配置文件本身是明文。
201
- - 口令只在 TUI 模式下输入,其他模式会拒绝读取,避免明文回显。
202
- - 扩展能读取 Pi 会话、配置和凭据,权限与 Pi 进程相同。只应安装可信来源的构建产物。
203
- - 推送前的明文检查只覆盖 `models.json` 和 `mcp.json` 的已知字段,不扫描 `AGENTS.md`、`prompts/`、`skills/` 等自由文本。
204
-
205
- ## 已知限制
206
-
207
- - 只支持 GitHub,不支持 Google 登录或其他代码托管服务。
208
- - 没有后台定时同步;推送需要手动执行,自动拉取只在启动时运行一次。
209
- - 不同设备的 `settings.json` 中如果包含本机包路径或其他设备相关字段,需要自行加入 `localSettingsKeys`,否则会互相覆盖。
210
- - 同步的是配置内容,不安装 npm 包;`settings.json` 里的 `packages` 记录会随配置同步,但对应包仍需在每台设备上安装。
211
- - 不合并非 JSON 文件,不处理符号链接,不保留远端文件的历史版本。
212
- - 目前没有用于多个配置档案或多个 GitHub 账号的切换功能。
213
-
214
- ## 验证状态
215
-
216
- 已在 Node.js v24 上通过 TypeScript 类型检查和 59 个单元测试,覆盖路径校验、冲突计划、加密往返、错误口令、KDF 参数边界、凭据过滤、明文审计、配置读写、令牌存储和备份。
217
-
218
- 已在真实 GitHub 私有仓库 `Hex4C59/pi-config-e2e` 上完成端到端联调。测试使用两个隔离的 agent 目录,覆盖空仓库初始化和推送、第二设备拉取、`settings.json` 本机字段保留、两种冲突处理、凭据轮换和错误口令重试;仓库内容中没有出现明文 API key 或 GitHub 令牌。联调同时修正了空仓库首次推送和 `manifest.json` 推送路径校验的问题。先用 `gh` 令牌验证,随后用 OAuth App 设备码登录得到的 `gho_` 令牌重跑,结果一致。
219
-
220
- 口令输入界面已用真实 `InteractiveMode` 录制对比证据,GIF 保存在 `config-sync/quality/ui/`,不随 npm 包分发。config-sync 是新增包,没有旧版本源码,因此“改动前”取 Pi 自带的同类输入框作为基线;两侧在同一会话、同一终端尺寸和主题下采集,逐字输入同一示例口令。该证据只验证对话框本身,不覆盖 `/sync push` 的完整调用链。
221
-
222
- 设备码登录已用真实 GitHub OAuth App 完成:`GET /user` 返回 `Hex4C59`,令牌作用域为 `repo`。登录后的令牌已用于上述隔离联调,临时目录中的令牌副本已删除。
223
-
224
- 长期使用前,仍建议保留一份独立的凭据备份。
1
+ # config-sync
2
+
3
+ 把选定范围的 Pi 配置和加密后的 API 密钥同步到一个私有 GitHub 仓库。每台设备登录同一个 GitHub 账号后,用 `/sync pull` 拉取配置,用 `/sync push` 上传改动。
4
+
5
+ ## 登录方式
6
+
7
+ 这个扩展使用 GitHub 设备码登录,不需要 Google 账号。Google 登录只能证明“你是谁”,不能授权写入某个 GitHub 仓库;要访问仓库,仍然必须由 GitHub 发放令牌。
8
+
9
+ 设备码流程适合没有浏览器的场景:Pi 显示一个网址和一次性代码,在任意浏览器里输入代码并授权即可。扩展只保存 GitHub 返回的访问令牌,不接触 GitHub 密码。
10
+
11
+ ## 安装
12
+
13
+ 正式安装:
14
+
15
+ ```bash
16
+ pi install npm:@hex4c59/pi-ext-config-sync
17
+ ```
18
+
19
+ 从源码开发时,在仓库根目录临时加载:
20
+
21
+ ```bash
22
+ pi -e ./config-sync
23
+ ```
24
+
25
+ ## GitHub 登录与 OAuth App
26
+
27
+ 扩展内置了设备码登录使用的 OAuth App Client ID,安装后直接登录即可,不需要逐台配置。
28
+
29
+ Client ID 是公开标识,不是密钥,只用于向 GitHub 发起设备码申请;设备码流程不需要 Client Secret。所有使用本扩展的设备共用同一个 OAuth App,因此每台设备只需登录,不需要再次设置。
30
+
31
+ 如需改用自己创建的 OAuth App:
32
+
33
+ 1. 打开 GitHub 的 `Settings` → `Developer settings` → `OAuth Apps` → `New OAuth App`。
34
+ 2. 填写名称、主页地址和 `Authorization callback URL`。设备码流程不使用回调地址,填一个可访问的地址即可,例如 `https://github.com`。
35
+ 3. 创建后在应用设置里勾选 `Enable Device Flow`。
36
+ 4. 复制 `Client ID`,在 Pi 中运行 `/sync setup <client-id>`。
37
+
38
+ 自定义值写入本机的 `~/.pi/agent/config-sync/config.json`,优先于内置默认值。`config.json` 中留空时回退到内置值。
39
+
40
+ ## 第一次使用
41
+
42
+ 第一台设备:
43
+
44
+ ```text
45
+ /sync login
46
+ /sync push
47
+ ```
48
+
49
+ `/sync login` 会显示 `https://github.com/login/device` 和一次性代码,并把代码复制到剪贴板。授权完成后,令牌保存在 `auth.json` 中。
50
+
51
+ `/sync push` 默认使用 `<GitHub 登录名>/pi-config`。仓库不存在时,会在确认后创建为私有仓库。第一次推送凭据时,需要设置一个至少 8 个字符的口令;仓库里保存的是用该口令加密的 `secrets.enc`,不保存口令本身。
52
+
53
+ 第二台设备:
54
+
55
+ ```text
56
+ /sync login
57
+ /sync pull
58
+ ```
59
+
60
+ 拉取完成后,按提示重载 Pi。
61
+
62
+ 也可以显式指定仓库和分支:
63
+
64
+ ```text
65
+ /sync repo <owner/name>
66
+ /sync branch <name>
67
+ /sync repo default
68
+ /sync branch default
69
+ ```
70
+
71
+ 回退到默认值会清除本机记录的上次同步基准,下一次拉取或推送会重新比较全部文件。
72
+
73
+ ## 命令
74
+
75
+ | 命令 | 作用 |
76
+ | --- | --- |
77
+ | `/sync help` | 显示命令列表 |
78
+ | `/sync setup <client-id>` | 可选:保存自建 GitHub OAuth App 的 Client ID,覆盖内置值 |
79
+ | `/sync login` | 开始 GitHub 设备码登录 |
80
+ | `/sync logout` | 删除 `auth.json` 中的 GitHub 令牌 |
81
+ | `/sync status` | 显示登录、仓库、分支、自动拉取和上次同步信息,不联网 |
82
+ | `/sync pull [--force]` | 从 GitHub 下载配置;`--force` 用远端覆盖所有冲突文件 |
83
+ | `/sync push [--force] [--yes]` | 上传配置;`--force` 覆盖远端冲突,`--yes` 跳过推送前确认 |
84
+ | `/sync repo <owner/name>` | 设置仓库 |
85
+ | `/sync branch <name>` | 设置分支 |
86
+ | `/sync auto on` | 启动时自动拉取,不弹确认 |
87
+ | `/sync auto off` | 关闭自动拉取 |
88
+ | `/sync proxy <url>` | 指定 GitHub 请求使用的代理,例如 `http://127.0.0.1:7897` |
89
+ | `/sync proxy system` | 清除指定值,只使用 Windows 系统代理 |
90
+ | `/sync proxy default` | 清除指定值,改回自动探测(环境变量 → 系统代理 → 直连) |
91
+ | `/sync ping` | 测试到 GitHub 的连通性,不走登录流程 |
92
+
93
+ ## 同步范围
94
+
95
+ | 路径 | 内容 |
96
+ | --- | --- |
97
+ | `settings.json` | Pi 设置;同步前去掉本机专用字段 |
98
+ | `models.json` | 自定义模型与 provider 定义 |
99
+ | `mcp.json` | MCP 服务器定义 |
100
+ | `keybindings.json` | 按键绑定 |
101
+ | `AGENTS.md` | 全局项目说明 |
102
+ | `SYSTEM.md`、`APPEND_SYSTEM.md` | 系统提示词 |
103
+ | `themes/` | 主题 |
104
+ | `prompts/` | 提示词模板 |
105
+ | `skills/` | Skill 源文件 |
106
+
107
+ `settings.json` 中的 `shellPath`、`lsp`、`lastChangelogVersion`、`extensionChangelogVersions` 和 `sessionDir` 默认保留为本机值,不参与同步。这个列表可以在 `config.json` 的 `localSettingsKeys` 中修改。
108
+
109
+ 不参与同步的内容:
110
+
111
+ - 以 `.` 开头的文件和目录,以及 `.DS_Store`、`Thumbs.db`、`.git`、`node_modules`
112
+ - 符号链接
113
+ - 超过 10 MB 的单个文件
114
+ - 总计超过 2000 个文件或 50 MB 的内容
115
+ - `auth.json` 中的 OAuth 凭据和未列入范围的 provider
116
+
117
+ ## 凭据同步
118
+
119
+ 只同步 `auth.json` 中形如 `{"type":"api_key","key":"..."}` 的条目。默认排除使用设备登录或本机客户端凭据的 provider:`github-copilot`、`qoder`、`qoder-cn`、`trae-cn`、`workbuddy`、`workbuddy-ai`,以及本扩展自己的 `config-sync` 令牌。
120
+
121
+ `config.json` 中的过滤字段:
122
+
123
+ ```json
124
+ {
125
+ "includeAuthProviders": [],
126
+ "excludeAuthProviders": ["config-sync", "github-copilot", "qoder", "qoder-cn", "trae-cn", "workbuddy", "workbuddy-ai"]
127
+ }
128
+ ```
129
+
130
+ - `includeAuthProviders` 非空时,只同步其中的 provider。
131
+ - 显式包含可以覆盖排除,但条目仍必须是合法的 `api_key` 形状。
132
+ - 不支持同步 OAuth、设备码或其他非 `api_key` 条目。
133
+
134
+ 加密格式:
135
+
136
+ - 口令经 scrypt 派生密钥,参数 `N=32768, r=8, p=1`,16 字节随机盐。
137
+ - 数据用 AES-256-GCM 加密,12 字节随机 IV,16 字节认证标签。
138
+ - 加密文件为 `secrets.enc`,明文只在内存中出现。
139
+
140
+ 口令不会写入磁盘、仓库或日志。口令丢失后无法解密仓库中的旧凭据;此时删除仓库里的 `secrets.enc`,再推送一次即可设置新口令。
141
+
142
+ `models.json` 和 `mcp.json` 在推送前会做明文检查:
143
+
144
+ - `models.json` 中值为明文的 `apiKey` / `api_key` 会阻止推送;`$ENV_NAME` 和 `!command` 引用允许通过。
145
+ - `mcp.json` 中 URL 自带的用户名密码、以及 `headers` / `env` 中名称像密钥的明文值会阻止推送;`${VAR}` 和 `!command` 引用允许通过。
146
+
147
+ 这是启发式检查,不能证明文件里没有其他形式的密钥。推送前仍应自行确认。
148
+
149
+ ## 冲突处理
150
+
151
+ 扩展在本机记录上次同步的提交和文件哈希,用“上次基准 / 本机 / 远端”三方比较:
152
+
153
+ - 只有远端变化:拉取时写入远端版本。
154
+ - 只有本机变化:拉取时保留本机版本,推送时上传本机版本。
155
+ - 两边都变化:拉取时询问“全部用远端”“全部保留本机”或逐文件选择;推送时默认拒绝,需要先拉取,或用 `--force` 覆盖远端。
156
+ - 新设备没有基准:远端独有文件直接写入,本机独有文件保留。
157
+ - 远端删除且本机未改动:拉取时删除本机文件;本机删除且远端未改动:推送时删除远端文件。
158
+
159
+ 除 `settings.json` 外,文本和二进制文件都按整文件覆盖,不做行级合并。`settings.json` 拉取时会把远端内容与本机专用字段合并后再写入。
160
+
161
+ 推送会用完整的文件列表创建提交,因此仓库必须专门用于 config-sync。向已有其他文件的仓库推送会替换整个文件树;首次遇到不是 config-sync 创建的仓库时,扩展会要求确认。
162
+
163
+ ## 自动拉取
164
+
165
+ `/sync auto on` 后,Pi 以 TUI 模式启动时会在后台拉取一次:
166
+
167
+ - 不弹冲突确认,遇到冲突会跳过并提示手动运行 `/sync pull`。
168
+ - 不处理凭据;`secrets.enc` 有变化时只提示手动拉取。
169
+ - 有文件更新时提示 `/reload`。
170
+
171
+ 自动拉取不会推送,也不会在 `session_start` 以外的时机运行。
172
+
173
+ ## 本机文件与备份
174
+
175
+ | 路径 | 内容 |
176
+ | --- | --- |
177
+ | `~/.pi/agent/auth.json` | GitHub 令牌,provider ID 为 `config-sync` |
178
+ | `~/.pi/agent/config-sync/config.json` | 客户端 ID(可省略,回退内置值)、仓库、分支和过滤设置 || `~/.pi/agent/config-sync/state.json` | 设备 ID、登录名、上次同步提交与文件哈希 |
179
+ | `~/.pi/agent/config-sync/backups/<时间>/agent/` | 拉取覆盖或删除前的本机文件 |
180
+
181
+ 备份最多保留 10 份,只复制实际存在且会被覆盖或删除的普通文件。需要回滚时,把备份目录中的文件复制回 `~/.pi/agent/` 对应位置。
182
+
183
+ `state.json` 损坏时会被重命名为 `state.json.corrupt-<时间>`,然后生成新的设备 ID 和空基准。下一次拉取会按新设备处理。
184
+
185
+ ## 网络请求
186
+
187
+ 扩展只访问以下域名:
188
+
189
+ | 域名 | 用途 |
190
+ | --- | --- |
191
+ | `github.com` | 设备码申请、令牌轮询 |
192
+ | `api.github.com` | 用户信息、仓库、Git tree / blob / commit / ref |
193
+
194
+ 请求使用固定的 `User-Agent: pi-config-sync`。GitHub 令牌通过 `Authorization: Bearer` 头发送,不写入日志或错误信息。除 GitHub 外不发送配置内容。
195
+
196
+ ### 代理
197
+
198
+ 请求不经过 Node.js 自带的 `fetch`,而是由扩展自己的 HTTP 传输层发出。代理按以下顺序选择,先命中的生效:
199
+
200
+ 1. `config.json` 中的 `proxy`,或 `/sync proxy <url>`。
201
+ 2. 环境变量 `HTTPS_PROXY` / `HTTP_PROXY`。
202
+ 3. Windows 系统代理(`Internet 选项` → `连接` → `局域网设置`)。
203
+ 4. 以上都没有时直连。
204
+
205
+ 代理走 HTTP `CONNECT` 隧道,TLS 仍由本进程与 GitHub 直接协商,因此证书校验和 SNI 保持原样。`NO_PROXY` 中的主机及其子域名会跳过代理。
206
+
207
+ 代理地址在每次 `/sync` 命令开始时重新读取,修改代理程序或系统设置后不需要重启 Pi。若指定的代理端口没有在监听,命令会直接说明这一点,而不是只报一句 `fetch failed`。
208
+
209
+ ### 超时与重试
210
+
211
+ 单次请求连接超时 20 秒。网络抖动、DNS 被污染到不可达地址、连接被重置时,会自动重试,最多 4 次,间隔逐次增加。HTTP 状态码错误(例如 401、404、限流)不重试。
212
+
213
+ 设备码登录期间,单次轮询失败不会结束登录;连续 6 次失败才会停止,并给出失败原因。
214
+
215
+ 排查连通性时运行 `/sync ping`;确认代理地址用 `/sync status`。
216
+
217
+ ## 安全边界
218
+
219
+ - GitHub 令牌拥有 `repo` 范围,能读写该账号的私有仓库。令牌保存在 `auth.json`,卸载扩展不会自动删除;需要清除时先运行 `/sync logout`。
220
+ - 仓库默认必须是私有仓库。只有手动把 `allowPublicRepo` 设为 `true` 才允许推送公开仓库;公开仓库中的 `secrets.enc` 仍受口令保护,但配置文件本身是明文。
221
+ - 口令只在 TUI 模式下输入,其他模式会拒绝读取,避免明文回显。
222
+ - 扩展能读取 Pi 会话、配置和凭据,权限与 Pi 进程相同。只应安装可信来源的构建产物。
223
+ - 推送前的明文检查只覆盖 `models.json` 和 `mcp.json` 的已知字段,不扫描 `AGENTS.md`、`prompts/`、`skills/` 等自由文本。
224
+
225
+ ## 已知限制
226
+
227
+ - 只支持 GitHub,不支持 Google 登录或其他代码托管服务。
228
+ - 没有后台定时同步;推送需要手动执行,自动拉取只在启动时运行一次。
229
+ - 不支持 SOCKS 代理,只支持 HTTP / HTTPS 代理。
230
+ - 不同设备的 `settings.json` 中如果包含本机包路径或其他设备相关字段,需要自行加入 `localSettingsKeys`,否则会互相覆盖。
231
+ - `settings.json` 里的 `packages` 记录会随配置同步,Pi 在启动或 `/reload` 时安装其中的 npm 包。若旧设备推送时 `packages` 里还没有 config-sync 自己,新设备拉取后会在下次重启时丢失本扩展;推送前先在旧设备执行 `pi install npm:@hex4c59/pi-ext-config-sync`,让这条记录进入远端。
232
+ - 不合并非 JSON 文件,不处理符号链接,不保留远端文件的历史版本。
233
+ - 目前没有用于多个配置档案或多个 GitHub 账号的切换功能。
234
+
235
+ ## 验证状态
236
+
237
+ 已在 Node.js v24 上通过 TypeScript 类型检查和 78 个单元测试,覆盖路径校验、冲突计划、加密往返、错误口令、KDF 参数边界、凭据过滤、明文审计、配置读写、令牌存储、备份、代理选择、`NO_PROXY` 匹配和传输层重试。
238
+
239
+ 网络传输层已在本机实测:单次直连 40 次请求中 30 次因 DNS 返回不可达地址而连接超时(耗时约 10 秒后报 `fetch failed`);同样的条件下开启 4 次重试后 15 次调用全部成功。配置 Windows 系统代理后连续 12 次请求全部成功。代理端口未监听时会直接报告该代理不可用,`/sync proxy default` 可恢复直连。`/sync ping` 与 `/sync status` 已用真实配置运行。
240
+
241
+ 已在真实 GitHub 私有仓库 `Hex4C59/pi-config-e2e` 上完成端到端联调。测试使用两个隔离的 agent 目录,覆盖空仓库初始化和推送、第二设备拉取、`settings.json` 本机字段保留、两种冲突处理、凭据轮换和错误口令重试;仓库内容中没有出现明文 API key 或 GitHub 令牌。联调同时修正了空仓库首次推送和 `manifest.json` 推送路径校验的问题。先用 `gh` 令牌验证,随后用 OAuth App 设备码登录得到的 `gho_` 令牌重跑,结果一致。
242
+
243
+ 口令输入界面已用真实 `InteractiveMode` 录制对比证据,GIF 保存在维护者工作副本的 `config-sync/quality/ui/`,不入库、不随 npm 包分发。config-sync 是新增包,没有旧版本源码,因此“改动前”取 Pi 自带的同类输入框作为基线;两侧在同一会话、同一终端尺寸和主题下采集,逐字输入同一示例口令。该证据只验证对话框本身,不覆盖 `/sync push` 的完整调用链。
244
+
245
+ 设备码登录已用真实 GitHub OAuth App 完成:`GET /user` 返回 `Hex4C59`,令牌作用域为 `repo`。登录后的令牌已用于上述隔离联调,临时目录中的令牌副本已删除。
246
+
247
+ 长期使用前,仍建议保留一份独立的凭据备份。
@@ -8,10 +8,12 @@ import {
8
8
  runAutoPull,
9
9
  runLogin,
10
10
  runLogout,
11
+ runPing,
11
12
  runPull,
12
13
  runPush,
13
14
  runSetAuto,
14
15
  runSetBranch,
16
+ runSetProxy,
15
17
  runSetRepo,
16
18
  runSetup,
17
19
  runStatus,
@@ -28,6 +30,8 @@ const SUBCOMMANDS = [
28
30
  { value: "repo", label: "repo", description: "Set the repository as owner/name" },
29
31
  { value: "branch", label: "branch", description: "Set the branch name" },
30
32
  { value: "auto", label: "auto", description: "Toggle pull on startup" },
33
+ { value: "proxy", label: "proxy", description: "Set the proxy used for GitHub requests" },
34
+ { value: "ping", label: "ping", description: "Test the connection to GitHub" },
31
35
  { value: "help", label: "help", description: "Show commands" },
32
36
  ];
33
37
 
@@ -42,6 +46,8 @@ const HELP = [
42
46
  "/sync repo <owner/name|default> Set the repository",
43
47
  "/sync branch <name|default> Set the branch",
44
48
  "/sync auto on|off Toggle automatic pull on startup",
49
+ "/sync proxy <url|system|default> Set the proxy used for GitHub requests",
50
+ "/sync ping Test the connection to GitHub",
45
51
  ].join("\n");
46
52
 
47
53
  export default function configSyncExtension(pi: ExtensionAPI): void {
@@ -57,6 +63,12 @@ export default function configSyncExtension(pi: ExtensionAPI): void {
57
63
  ? options.map((option) => ({ value: option, label: option }))
58
64
  : null;
59
65
  }
66
+ if (command === "proxy") {
67
+ const options = ["system", "default"].filter((option) => option.startsWith(value));
68
+ return options.length > 0
69
+ ? options.map((option) => ({ value: option, label: option }))
70
+ : null;
71
+ }
60
72
  return null;
61
73
  }
62
74
  const matches = SUBCOMMANDS.filter((item) => item.value.startsWith(trimmed));
@@ -116,6 +128,12 @@ export default function configSyncExtension(pi: ExtensionAPI): void {
116
128
  case "auto":
117
129
  await runSetAuto(ui, getAgentDir(), rest.join(" "));
118
130
  return;
131
+ case "proxy":
132
+ await runSetProxy(ui, getAgentDir(), rest.join(" "));
133
+ return;
134
+ case "ping":
135
+ await runPing(ui, getAgentDir());
136
+ return;
119
137
  default:
120
138
  throw new SyncError(`Unknown /sync subcommand: ${subcommand}. Run /sync help.`);
121
139
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@hex4c59/pi-ext-config-sync",
3
- "version": "0.1.0",
3
+ "version": "0.1.2",
4
4
  "description": "Sync Pi configuration and encrypted credentials through a private GitHub repository.",
5
5
  "license": "MIT",
6
6
  "repository": {
package/src/files.ts CHANGED
@@ -7,6 +7,7 @@ import {
7
7
  AGENT_PATH_PREFIX,
8
8
  AUTH_PROVIDER_ID,
9
9
  CONFIG_SYNC_DIR,
10
+ DEFAULT_CLIENT_ID,
10
11
  DEFAULT_EXCLUDE_AUTH_PROVIDERS,
11
12
  DEFAULT_LOCAL_SETTINGS_KEYS,
12
13
  SyncError,
@@ -151,10 +152,11 @@ export function authPath(agentDir: string): string {
151
152
  export function defaultConfig(): SyncConfig {
152
153
  return {
153
154
  version: 1,
154
- clientId: "",
155
+ clientId: DEFAULT_CLIENT_ID,
155
156
  repo: "",
156
157
  branch: "",
157
158
  autoPull: false,
159
+ proxy: "",
158
160
  allowPublicRepo: false,
159
161
  localSettingsKeys: [...DEFAULT_LOCAL_SETTINGS_KEYS],
160
162
  includeAuthProviders: [],
@@ -172,10 +174,12 @@ export async function loadConfig(agentDir: string): Promise<SyncConfig> {
172
174
  }
173
175
  return {
174
176
  version: 1,
175
- clientId: readString(raw.clientId, defaults.clientId, "clientId"),
177
+ clientId: readString(raw.clientId, defaults.clientId, "clientId").trim()
178
+ || defaults.clientId,
176
179
  repo: readString(raw.repo, defaults.repo, "repo"),
177
180
  branch: readString(raw.branch, defaults.branch, "branch"),
178
181
  autoPull: readBoolean(raw.autoPull, defaults.autoPull, "autoPull"),
182
+ proxy: readString(raw.proxy, defaults.proxy, "proxy"),
179
183
  allowPublicRepo: readBoolean(raw.allowPublicRepo, defaults.allowPublicRepo, "allowPublicRepo"),
180
184
  localSettingsKeys: readStringArray(
181
185
  raw.localSettingsKeys,