pi-profile-archive（中文）

pi coding agent 的 profile 管理器 — 切换、保存、归档、git 版本化你的 settings.json profile。 围绕一个简单的不变量：永不丢失历史。

属于 pi coding agent 扩展生态。 受 Eddie0521/pi-profile 启发，但独立项目。

语言: English · 中文

为什么做这个

pi 启动时读 ~/.pi/agent/settings.json。一旦你开始折腾 profile（测试新模型、切换 provider、调整 packages），每次改动都是破坏性的 — 旧配置直接被覆盖。

上游 pi-profile 解决了 runtime identity 这边的问题（agent 启动时注入 profile prompt），但不保护底层的 settings.json 文件不被覆盖。

pi-profile-archive 专注于 settings preservation：

• 每次 /profile use <name> 把当前 settings.json 写到 profiles/archive/<timestamp>-<previous>.json 再换新
• 每次变更可 git commit（自动检测；~/.pi/agent/profiles/ 不是 git repo 时静默跳过）
• Archive 文件不可变 — /profile rm 拒绝删除它们

安装

# npm
pi install npm:pi-profile-archive

# git
pi install git:github.com/cv588888888888888888888ju/pi-profile-archive

# 本地路径
pi install /path/to/pi-profile-archive

# 临时试用（不安装）
pi -e /path/to/pi-profile-archive

快速上手

1. 把当前 settings 保存为 profile

/profile save stable
# → Saved current settings.json → profiles/stable.json

2. 试不同的配置

手动改 settings（或用别的 extension 改），换 model / packages / inlineImageRead 配置，然后保存：

/profile save testing

3. 切换 profile

/profile use stable
# → Switched to profile "stable"
# → Previous settings.json archived → profiles/archive/2026-08-07-153012-stable.json
# → git: committed "profile: switch to stable"
# → Restart pi to load the new settings.json

/profile list
# → Active profile: stable
# → Profiles (3):
# →   testing
# →   stable  [ACTIVE]

4. 可选：git 版本化 profiles

cd ~/.pi/agent/profiles
git init
git add -A && git commit -m "initial profiles"

extension 自动 commit 每次 save / use / archive / rename / delete。

命令

所有命令在 pi session 内，前缀 /profile：

| 命令 | 干什么 | |---|---| | /profile | 显示当前激活 profile + 列出所有 | | /profile list | 同上 | | /profile show <name> | 打印 profile JSON | | /profile save <name> | 快照当前 settings.json 到 profiles/<name>.json | | /profile use <name> | 切换（自动归档当前 + 应用） | | /profile archive [name] | 快照当前（或指定）到 archive/ | | /profile diff <a> <b> | 两个 profile 之间的行 diff | | /profile rm <name> | 删除 profile（拒绝动 archive） | | /profile rename <old> <new> | 重命名 profile 文件 |

文件布局

~/.pi/agent/
├── settings.json                  # 当前激活 profile（pi 读这个）
└── profiles/
    ├── stable.json                # 你保存的 profile
    ├── testing.json
    └── archive/
        ├── 2026-08-07-153012-prev.json    # 每次 /profile use 自动生成
        ├── 2026-08-07-154000-prev.json
        └── ...

何时归档

每次 /profile use <name>：

1. 读当前 settings.json
2. 查 settings.json 的 piProfile.active 字段（默认 "unknown"）
3. 复制当前 settings.json → profiles/archive/YYYY-MM-DD-HHMMSS-<prev-name>.json
4. 读目标 profile，加 piProfile.active = <name>
5. 写入合并后的 JSON 到 settings.json
6. 如果 profiles/ 是 git repo 自动 commit
7. 提示你重启 pi

何时不归档

/profile use 失败时不归档（profile 找不到、写权限拒绝等）。失败的切换保持当前 settings.json 不动。

安全模型

路径安全由用户负责 — 与 pi 生态其余部分一致。本 extension：

• 只从 ~/.pi/agent/settings.json 和 ~/.pi/agent/profiles/ 读文件
• 只写到 ~/.pi/agent/settings.json、~/.pi/agent/profiles/ 和 ~/.pi/agent/profiles/archive/
• 不启动 shell — 只用 node:fs 和 node:child_process.execFileSync 调 git
• execFileSync("git", [...]) 用硬编码参数列表（无 shell 注入），但需要 git 在 $PATH 上。如果没有 git 或 profiles 目录不是 git repo，静默跳过 commit。

已知限制

• /profile use 之后需要重启 pi。插件写 settings.json，但 pi 在启动时只读一次 settings.json。没有 "mid-session 重新加载" 的 API。
• 不能 diff 当前 settings。/profile diff 比较两个保存的 profile；要和 live settings.json 比需要先把 settings 转成 profile 格式（这个 extension 不做）。
• archive 无限累积。文件越积越多。如果磁盘敏感，配 git gc 或周期性手动清理。

灵感来源

这个插件是调研 Eddie0521/pi-profile 之后做的。上游解决了 runtime identity 问题（同 session 内切 model + skills + prompt）。pi-profile-archive 解决 history preservation 问题（换 settings.json 文件不丢旧的）。两者互补不竞争。

许可证

MIT