@liuchen64/pi-config-sync

Pi 扩展 - 把 ~/.pi/agent 配置双向同步到 git 仓库（菜单驱动：绑定 / 同步 / 状态 / 快照回滚）

Packages

Package details

extension

Install @liuchen64/pi-config-sync from npm and Pi will load the resources declared by the package manifest.

npm report

$ pi install npm:@liuchen64/pi-config-sync

Package: @liuchen64/pi-config-sync
Version: 0.4.1
Published: Nov 4, 2026
Downloads: 1,079/mo · 1,079/wk
Author: liuchen64
License: MIT
Types: extension
Size: 95.3 KB
Dependencies: 0 dependencies · 1 peer

Pi manifest JSON

{
  "extensions": [
    "./src/index.ts"
  ]
}

Security note

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

README

@liuchen64/pi-config-sync

把 pi 的个人配置在 ~/.pi/agent 与 git 仓库之间双向同步。默认对应 pi-config 仓库（src/ 为配置源，deploy.sh 的 git 版）。

操作以选择菜单为主：输入 /config-sync 打开菜单，结果用 toast 提示。

安装

pi install npm:@liuchen64/pi-config-sync

快速开始

# 输入命令后按菜单操作
/config-sync

菜单项：绑定 / 更换配置仓库、同步、查看状态、检查仓库访问、快照与回滚、帮助。日常只需「同步」——方向由插件判断。

首次使用选「绑定 / 更换配置仓库…」，填 git 地址即可：

git@gitee.com:folding-fan/pi-config.git

仓库会克隆到 ~/.pi/agent/.config-sync/repos/<仓库名>/，作为插件唯一的同步副本；也支持填本地工作副本路径（D:/Code/me/pi-config）。

首次绑定一个已有内容的仓库（有提交且含 src/）时，会立即把仓库的 src/ 部署到运行目录（覆盖前自动快照），即以远端为准；此后「同步」里出现的运行配置差异才是本机改动，不会再把手头配置反推远端。再次绑定同一副本不会重复部署，本机改动保留。

如果绑定的是空仓库（没有提交，或没有 src/ 目录），会弹出确认「仓库为空，是否推送本地配置到仓库？」：

推送本地配置：把本机 settings.json、mcp.json、AGENTS.md、skills/、prompts/ 写进 src/，生成首个提交并推送
暂不推送：只保留绑定，之后执行一次「同步」即可把本地配置回写、提交并推送

本地不存在的文件（如没有 mcp.json）会跳过，不影响初始化。

远端访问排查

菜单「检查仓库访问…」（doctor）只跑 git ls-remote，不修改本地状态：

HTTPS：Gitee 需要「账号 + 私人令牌」。先在终端手动执行一次 git ls-remote <仓库地址> 把凭据存进 Windows 凭据管理器，插件后续复用；凭据过期时删除 gitee 条目重新认证
SSH：插件非交互调用 git，带口令的密钥无法弹输入，需先启动 ssh-agent 并 ssh-add

长操作与输入

每个操作（含查看状态、回写、部署、快照）都会立即弹出进度面板（spinner + 当前步骤 + 已用时），无需等到 git 返回才知道命令已被接收；期间输入不会进入会话，避免等待时误输入：

操作完成或失败后面板自动关闭
按 Esc 可隐藏面板，操作仍在后台继续，完成后照常 toast 结果
同一时间只允许一个操作，进行中再执行命令会提示等待

同步范围

与 pi-config 的 deploy.sh 保持一致：

`~/.pi/agent`	仓库
`settings.json`	`src/settings.json`
`mcp.json`	`src/mcp.json`
`AGENTS.md`	`src/global_agents.md`
`skills/`、`prompts/`	`src/` 下同名目录

不在表内的文件（themes/、extensions/、sessions/、state/、auth.json 等）一律不同步。 auth*、.env*、*token*、*secret*、*credential* 等敏感文件名在同步与比对时跳过； settings.json 的 lastChangelogVersion 属于机器本地键，不参与漂移判定。

菜单操作

/config-sync 只提供菜单，没有子命令（需在交互界面里使用）：

菜单项	说明
绑定 / 更换配置仓库…	填 git 地址或本地路径，写入 `~/.pi/agent/config-sync.json`；首次绑定已有内容的仓库会立即部署到运行目录（先快照），空仓库会提示初始化
同步（自动判断方向）	仅远端有更新 → 拉取部署；仅本地有改动 → 回写提交并推送；两边都有改动 → 弹菜单选强拉 / 强推
查看状态	远端提交、仓库改动、运行配置差异、快照数量
检查仓库访问…	用 `git ls-remote` 验证远端地址与凭据，失败时给出 HTTPS / SSH 排查方向
自动同步设置…	开关与三项策略（启动拉取 / 对话结束后 / 退出前）、提示强度、查看最近日志
快照与回滚…	列出快照、回滚最近一份或指定快照

强推使用 push --force-with-lease 覆盖远端；拉取只做快进，遇到分叉会提示改用强拉。

自动同步

默认关闭，在「自动同步设置…」里打开后按三段策略工作：

触发	默认行为	说明
会话启动（延迟 3 秒）	拉取	仅当远端有新提交且本地无改动时快进并部署，部署前自动快照；新配置需 `/reload` 生效
一轮对话结束（防抖 30 秒）	提交并推送	有漂移才动作，无变化不联网
会话关闭前	仅提交	不联网，避免退出时被截断

约束：

永不强拉强推：远端有新提交但本地也有改动时只提示，不做任何改动，由你在菜单里决定
提示强度三档：只提示有变更时（默认，失败静默但「需要你处理」仍提示）/ 总是提示 / 不提示
结果与失败都写 ~/.pi/agent/.config-sync/auto-sync.log，菜单「自动同步设置…」里可看最近 10 条
自动同步与菜单操作共用 ~/.pi/agent/.config-sync/sync.lock，两个 pi 实例不会同时写仓库

配置写在 ~/.pi/agent/config-sync.json 的 autoSync 字段：

空仓库初始化

绑定空仓库时菜单会直接询问是否推送本地配置；选「推送本地配置」即把本机配置写进 src/、生成首个提交并推送。仓库没有 origin 远端时只做本地初始化，不推送。

"autoSync": {
  "enabled": true,
  "onStart": "pull",
  "onSettle": "push",
  "onShutdown": "commit",
  "notify": "changes"
}

快照

部署或强拉前，运行配置会整份快照到：

~/.pi/agent/.config-sync/backups/<时间戳>-<原因>/

原因包括 deploy、pull、force-pull、pre-restore，只保留最近 10 份。快照目录不进仓库，菜单里的「快照与回滚」可列快照、回滚最近一份或指定快照。

冲突处理

sync 检测到「远端有新提交」且「本地有改动」时不执行任何操作，弹出选择菜单：

强拉：远端覆盖本地（先快照）
强推：本地覆盖远端

配置

~/.pi/agent/config-sync.json（仅本机，不入仓库）：

{
  "repoUrl": "git@gitee.com:folding-fan/pi-config.git",
  "repoPath": "C:/Users/<user>/.pi/agent/.config-sync/repos/pi-config",
  "branch": "master"
}

repoUrl：绑定时填写的 git 地址
repoPath：实际执行 git 操作的同步副本；bind 传 git 地址时固定克隆到 ~/.pi/agent/.config-sync/repos/<仓库名>/，已存在则复用
省略 bind 入参时只展示当前绑定，不会猜测路径；未绑定会直接提示尚未绑定

注意

部署后运行中的 pi 需要 /reload 重新加载配置
拉取 / 强拉会整体替换 skills/、prompts/ 目录，仓库中不存在的文件会被清除（可从快照恢复）
回写方向只写不删，仓库里多出来的文件不会因为本地删除而消失，需要手动在仓库删除