pi-dpi — dπ：拆解 π

English: README.md | 中文: 本文件

dπ = 拆解 π = 解耦分发。 pi-dpi 是 pi coding agent 的一个扩展插件（纯引擎，不含任何 agent 内容）：它把「agent 世界」从 pi 包中拆出来——人格、技能、提示词、会话存档 全部放进一个独立的内容仓库（你自己的 git 仓库），pi-dpi 只负责绑定、加载与同步。 引擎与内容解耦：引擎升级不动内容，内容迭代不动引擎，同一份内容仓库可以在多台机器、 多个团队成员之间分发。

安装

推荐——从 npm 安装（版本化发布、安装有缓存）：

pi install npm:@myka2003/pi-dpi

备选——GitHub 最新版（无版本号，始终最新）：

pi install git:github.com/oc101363-creator/pi-dpi

使用：/dpi-agent-login

安装后第一次使用，在 pi 中执行：

/dpi-agent-login

完整流程：

1. 仓库地址：直接 /dpi-agent-login <地址> 或交互输入。地址格式自动决定远端类型 （见下方「远端类型矩阵」）：GitHub 写法（user/repo、github.com/user/repo、 https://…）归一化为 https://github.com/user/repo.git；git@…/ssh://… 走 SSH、https://<自托管>/… 走通用 HTTPS、本地路径/file:// 走本地协议， 地址均按原样使用。
2. 代理选择（仅 GitHub / 通用 HTTPS）：不需要代理 / 使用 127.0.0.1:7890 / 自定义输入。
3. 认证：GitHub 走设备授权——终端显示 user_code 与验证地址，浏览器打开 https://github.com/login/device 输入代码完成授权（OAuth device flow）； 通用 HTTPS 改为交互输入「用户名 + 访问令牌/密码」；SSH 与本地仓库零凭证。
4. 克隆内容仓库：认证通过后自动 git clone 到 ~/.pi/agent/dpi/repo（token 不落 remote URL，走一次性 credential helper）。 克隆后会校验 agents/*/SYSTEM.md 存在——不是 dpi 内容仓库会响亮报错且不写配置。
5. 声明式注册：把内容仓库的本地路径写进 settings.json 的 packages—— 内容仓库本身是标准 pi 包（package.json 里 pi 清单声明 prompts/themes）， 提示词与主题由 pi 原生加载。
6. 技能按声明发现：引擎在 resources_discover 时读取当前 agent 的 agent.json，只把声明的技能（仓库根 skills/ 注册表条目）返回给 pi—— 未声明的技能不进会话，这是 dpi 的技能隔离机制。
7. 立即生效：自动 /reload，agent 卡片、技能、提示词即刻可用。

远端类型矩阵

/dpi-agent-login 根据地址格式自动识别远端类型，无需手动选择：

| 地址写法 | 类型 | 认证方式 | | --- | --- | --- | | user/repo、github.com/user/repo、https://github.com/user/repo(.git) | GitHub | OAuth device flow，token 单行存本机 | | git@host:path、user@host:path、ssh://…（含 [email protected]:…） | SSH 远端 | 零凭证，用本机 ssh key（绑定前先 ls-remote 探测） | | https://<非 GitHub 托管>/…、http://… | 通用 HTTPS | 交互输入用户名 + 访问令牌/密码，token 文件存两行（用户名 + 令牌） | | /abs/path、~/path、file://… | 本地仓库 | 零认证，走 git 本地协议（~ 自动展开） |

配置示例：

/dpi-agent-login [email protected]:user/agents.git        # SSH 远端
/dpi-agent-login https://gitea.example.com/user/agents.git  # 通用 HTTPS
/dpi-agent-login ~/srv/agents.git                           # 本地仓库

SSH 与本地仓库无需令牌；通用 HTTPS 适用于 Gitea / Forgejo / GitLab / Codeberg 等任意 git 托管。自动同步对四类远端一视同仁：SSH/本地不注入 credential helper、 不走 HTTP 代理；GitHub/通用 HTTPS 维持 token + 按需代理。

其它命令：

| 命令 | 作用 | | --- | --- | | /dpi-agent-login [仓库地址] | 绑定/重新绑定内容仓库 | | /dpi-agent-logout | 清除本机 token（本地仓库与配置保留） | | /dpi-agent [名字] | 查看/切换当前 agent | | /dpi-skills | 管理当前 agent 的技能组合：勾选/取消、删除注册表技能 | | /dpi-extensions | 管理当前 agent 的扩展组合：勾选/取消、删除注册表扩展 | | /dpi-sync | 手动同步内容仓库（pull --rebase → 清扫提交 → push） | | /dpi-record on\|off\|status | 会话存档开关 | | /dpi-save [名字] | 立即保存当前会话；带名字即命名保存点 | | /dpi-sessions | 浏览仓库存档会话（vim 导航：j/k、gg/G、/过滤），一键恢复/重命名/删除 | | /dpi-session-repair | 手动清理当前会话文件中的坏消息（重进会话生效） | | /dpi-save-status | 查看保存状态：最近归档/推送、未推送提交数 |

自动同步：3 秒远端监听 fetch GitHub 并自动拉取声明变更；15 分钟定时归档把当前会话 写入 git 对象库（另有手动 /dpi-save）并带认证推送。恢复时对会话结构做通用健壮化 （compaction 导致的孤儿/连续 tool 结果、尾部元数据），任何归档会话都能正确加载—— 不需要逐个修会话。保存状态在底栏（sync: ✓）与 /dpi-save-status。

会话自愈：网关 400/429 失败或用户中断会把空 assistant 消息写进会话文件，此后每轮 请求都被协议拒绝、会话"死亡"。引擎在退出时（归档前）与切换会话时自动清理坏消息， 归档进仓库的永远是干净版；日常无感，中招时也可 /dpi-session-repair 手动修复。

内容仓库结构约定

内容仓库就是一个普通 git 仓库（务必保持 Private——会话存档都在里面）：

<内容仓库>/
├── agents/                 # 多 agent 平行世界，一个目录一个完整人格
│   └── <name>/
│       ├── SYSTEM.md       # 人格定义（每轮对话注入系统提示词）
│       ├── agent.json      # 能力组合声明：{ "description": "…", "skills": […], "extensions": […] }
│       └── prompts/        # 该 agent 专属提示词模板（xxx.md → /xxx）
├── skills/                 # 技能注册表：平铺的技能库（<skill>/SKILL.md），
│                           #   不直接属于任何 agent，由 agent.json 按名组合
├── extensions/             # 扩展注册表：平铺的扩展库（<name>.ts），
│                           #   不直接属于任何 agent，由 agent.json 按名组合
├── machines/               # 机器层配置：<hostname>.json 覆写白名单字段
│                           #   （proxy、recordSessions），随仓库同步，新机器自动获配
├── sessions/<agent>/       # 会话存档按 agent 归档（_legacy/ 为旧平铺档迁移区）
├── docs/plans|specs/       # 工作流文档：大改先 spec（设计）后 plan（执行计划）
└── themes/                 # 可选，pi 主题

新增 agent = 新增 agents/<name>/{SYSTEM.md,agent.json} + 在 skills/ 注册表挑技能 填进 skills 数组，无需改任何代码。新增技能 = 在 skills/ 下加一个目录，然后由需要的 agent 在各自的 agent.json 里声明。日常增删技能、调整组合不需要手编文件，用 /dpi-skills 交互完成（勾选/取消即写回 agent.json，也可删除注册表技能）。扩展同理：新增扩展 = 在 extensions/ 下加一个 .ts 文件，由需要的 agent 在 agent.json 的 extensions 数组里声明，日常管理用 /dpi-extensions 交互完成。

per-agent 扩展

内容仓库根 extensions/ 是平铺的扩展注册表（一个 .ts 文件一个扩展），不直接属于 任何 agent。机制一句话：切换 agent 时引擎把内容包 settings 条目的 extensions 过滤器改写为当前 agent 声明的白名单，过滤发生在 import 之前 = 真隔离（未声明的 扩展文件根本不会被 jiti 执行）；代价是切换即全量 reload。启动时引擎还会自动对齐 一次过滤器（启动自愈），agent.json 被外部编辑或 /dpi-sync 拉取后，下一次重载即收敛。

superpowers 支持

superpowers 自 v0.5.0 起作为内容仓库 extensions/ 注册表中的普通扩展，经 agent.json 声明 + settings 白名单按 agent 加载（引擎内置注入器已退役）。

机器层配置（machines/）

引擎加载配置时，会在全局 config.json 之上叠加内容仓库的 machines/<hostname>.json（hostname 归一化为小写 [a-z0-9-]，如 MacBook-Air → macbook-air）。白名单字段：proxy、recordSessions——机器相关的 设置随仓库同步，换新机器时写一次机器文件即自动获配，无需逐台重设。

配置与数据位置

全部存于 ~/.pi/agent/dpi/（目录 0700）：

• config.json：repoUrl / remoteKind / repoPath / branch / proxy / currentAgent / recordSessions
• token：访问令牌（0600；GitHub 为单行，通用 HTTPS 为「用户名 + 令牌」两行，SSH/本地仓库无此文件）
• repo/：内容仓库本地克隆

若设置了 PI_CODING_AGENT_DIR 环境变量，则以 $PI_CODING_AGENT_DIR/dpi/ 替代。

⚠️ 隐私提醒

• 内容仓库必须保持 Private。会话存档都在仓库里，仓库公开等于公开你的 聊天记录。
• token 仅以 0600 权限存于本机 ~/.pi/agent/dpi/token，绝不写进 remote URL 或任何配置。