安装管理与创建发布

把包真正发布出去

前两节我们把 Pi Package 的结构搭好了。这一节是模块 02 的收口：怎么安装、管理、更新、最终发布。这也是 md-tools 从「本地目录」变成「别人能装的包」的临门一脚。

---

安装、移除、更新一条龙

先看一套完整的包管理命令：

pi install npm:@foo/bar@1.0.0
pi install git:github.com/user/repo@v1
pi remove npm:@foo/bar
pi list                 # 列出已装包
pi update --all         # 更新 pi + 所有包
pi update --extensions  # 只更新包、对齐 git ref
pi update --models      # 只刷新模型目录
pi update --self        # 只更新 pi 本身
pi update npm:@foo/bar  # 只更新一个包

几个要点：

• pi list 读的是 settings 里的包
• pi update 既能更新包，也能更新 pi CLI 本身
• pi remove npm:@foo/bar 卸载某个包

---

临时试用：-e / --extension

不想正式安装、只想试一下？用 -e，它装到临时目录，只对本次运行有效：

pi -e npm:@foo/bar
pi -e git:github.com/user/repo

这对评估第三方包特别合适——先试用，满意了再正式装。

---

三种源的决定性差异：git ref 的坑

前面提过三种源。这里重点讲 git 源的 @ref，这是生产级最容易出错的地方：

# SSH 简写（必须带 git: 前缀）
pi install git:git@github.com:user/repo
pi install git:git@github.com:user/repo@v1.0.0

# 协议格式
pi install ssh://git@github.com/user/repo@v1

• 没有 git: 前缀时，只接受协议 URL（https/http/ssh/git）
• ref 是固定的 tag 或 commit。pi update --extensions 和 --all 不会把包挪到更新的 ref，但会把已克隆的仓库对齐到配置的 ref
• 想换新 ref，用 pi install git:host/user/repo@new-ref
• SSH URL 自动用你配置的 SSH 密钥（尊重 ~/.ssh/config）

CI 里非交互运行，记得禁用凭据提示、快速失败：

export GIT_TERMINAL_PROMPT=0
export GIT_SSH_COMMAND="ssh -o BatchMode=yes -o ConnectTimeout=5"

---

过滤：只加载包的一部分

一个包装了，但只想用它的一部分资源？在 settings 的对象形式里过滤：

{
  "packages": [
    "npm:simple-pkg",
    {
      "source": "npm:my-package",
      "extensions": ["extensions/*.ts", "!extensions/legacy.ts"],
      "skills": [],
      "prompts": ["prompts/review.md"],
      "themes": ["+themes/legacy.json"]
    }
  ]
}

规则：省略某键 = 全加载；[] = 全不加载；!pattern = 排除；+path / -path = 精确强制包含/排除。过滤是在包清单之上再收窄，不会扩大它允许的。

---

启用/禁用：pi config

用 pi config 可以启用或禁用已装包里的扩展、技能、提示词模板、主题。它默认从全局设置 ~/.pi/agent/settings.json 开始，按 Tab 在全局和项目本地之间切换；pi config -l 从项目覆盖 .pi/settings.json 开始，继承的全局资源会变暗。

---

落地练习：从 git 源安装并验证

走一遍完整的「发布 → 安装」回路：

1. 把 md-tools 推到一个 git 仓库（本地裸仓库也行），打个 tag v0.1.0
2. 在另一个空目录，运行 pi install git:<你的仓库>@v0.1.0
3. 跑 pi list 和 pi config，确认资源加载，并试用其中一个技能或命令

怎么判断做对了？——pi list 能看到来自 git 的 md-tools，且包里的技能/命令确实可用；换个目录再 pi install 一次，能稳定复现。

卡住了怎么办？ git 源拉不下来？先确认 ref 正确、SSH 密钥能通。资源没加载？回到上一节检查 pi 键或目录结构。

---

常见坑：git 源不固定 ref，更新把你「搬走」

很多人发布 git 包时写 git:github.com/user/repo，不带 @ref。结果某次 pi update --all 后，别人的包被挪到了一个不可预期的 commit，行为变化、甚至坏掉。

正确姿势：分发时一定固定 ref（tag 或 commit），并写清楚 pi install git:...@v1.0.0 的用法。生产环境最怕「不确定」。给包一个明确的版本锚点，比什么都重要。

---

小结

1. pi install / remove / list / update 覆盖包管理的完整闭环
2. -e 临时试用，装到临时目录只对本次运行有效
3. git 源必须固定 @ref，更新不会自动搬走
4. 过滤用对象形式，[] 全不加载、! 排除、+/- 精确控制
5. pi config 启用/禁用包内资源，可在全局/项目间切换

下一节，进入模块 03：主题与界面。