# pouch 上手：安装、打版本、构建

pouch 是团队自研 skill 的仓库和安装工具。Skill 是给 Agent 看的工作说明书。你对着 Cursor、Claude Code 或 Codex 说话，Agent 按说明书干活。这份仓库里还有 CLI，用来把 skill 装到各 Agent。

这篇只讲日常会碰到的三件事：把 pouch 装上、用 releaser 打正式版本、用 builder 构建 DEB 或 Docker 镜像。其它 skill 装上就能喊，需要时对 Agent 说「有哪些自研 skill」。

## pouch 怎么工作

Skill 的正文只存在一份，在 `~/.pouch/skills/<name>/`。装到 Cursor、Claude、Codex 时走软链，改一份全处生效。项目根的 `.pouch.yaml` 记录这个仓库启用了哪些 skill，类似 `package.json` 记依赖。

日常几乎不直接跑 skill 里的脚本。CLI 负责安装和维护，干活是对 Agent 说人话。授权写在请求里：没说 push、没说上传，Agent 就不做。


| 你想做的                | 对谁说            | 不要                      |
| ------------------- | -------------- | ----------------------- |
| 打正式版本、annotated tag | releaser | 让 builder 选下一个 SemVer   |
| 打 DEB 或 Docker 镜像   | builder        | 让 releaser 去构建或上传 |


releaser 选定正式 SemVer 并打 annotated tag。builder 只读当前 HEAD：HEAD 恰好落在 `vX.Y.Z` 上就打正式包，否则打测试包。

## 安装 pouch

需要 Python 3、git，以及至少一种兼容 Agent Skills 的 Agent。

```bash
git clone https://git.yumee.top/laily/pouch.git ~/.pouch
cd ~/.pouch && ./install.sh
export PATH="$HOME/.local/bin:$PATH"
pouch status
```

`install.sh` 会把 `pouch` 命令放到 `~/.local/bin`，并把 pouch 这一个 skill 全局装到所有 Agent。其它 skill 不会自动全装。当前 shell 找不到 `pouch` 时，重开终端，或 `source` 对应 rc。

也可以对 Agent 说「帮我安装 pouch」，或把仓库地址丢给它。不要覆盖已经存在的 `~/.pouch`。

从旧目录迁过来：

```bash
mv ~/.skills ~/.pouch
~/.pouch/install.sh
```

装完看一眼：

```bash
pouch list
pouch status
pouch doctor
```

软链异常就 `pouch doctor --fix`。日常用 pouch 命令时会按间隔自动更新自身和已拉取的外部 source；要立刻更新就 `pouch update`。

## 把要用的 skill 装上

发版本和构建这两个，全局装一次，所有项目都能喊：

```bash
pouch add releaser -g -y
pouch add builder -g -y
```

只想在当前仓库启用：

```bash
cd ~/code/my-app
pouch add releaser -y
pouch add builder -y
```

也可以对 Agent 说「把这个项目该用的 skill 接上」，它会按仓库信号建议，再 `pouch add`。builder 不要 `pouch init builder`，初始化是对 Agent 说「用 builder 初始化这个项目」。

交互多选：`pouch select -g`。取消勾选不会卸载，卸载用 `pouch remove`。

## 怎么对 Agent 说话

打开已安装目标的 Agent。项目级安装要打开那个项目再说话；全局安装任意项目都可以。请求里写清 skill 名、目标和授权范围。

```text
使用 releaser，为已经合并到 main 的 1.6.0 发布 v1.6.0 tag。不要创建 Forge Release。
用 builder 初始化这个项目。
用 builder 构建当前版本的 DEB，先不要上传。
```

人看各 skill 目录下的 `README.md`。`SKILL.md` 是给 Agent 的指令，不必通读。

## 用 releaser 打新版本

代码已经合进默认分支、测试过了，要打正式 tag 时用它。它不构建 DEB，也不推镜像。

### 还没决定版本号

```text
使用 releaser 检查当前版本和这次改动，建议下一个版本号。只分析，不修改文件。
```

Agent 会读项目版本规则、现有 tag 和实际改动，给出建议和依据。没有项目约定时，单一协调版本默认 SemVer，tag 形如 `v1.6.0`。用户输入 `v1.6.0` 时规范版本是 `1.6.0`，不要产生双前缀。

### 默认短路径：直接打 tag

项目以 Git tag 作为版本来源，且不需要改 VERSION 文件或把 CHANGELOG 写回仓库时，走这条：

```text
使用 releaser，为已经合并到 main 的 1.6.0 发布 v1.6.0 tag。根据上一个稳定 tag 到目标 commit 的实际变化生成更新说明，把说明写入 annotated tag，并验证远端 tag 的 commit 和说明。不要创建 Forge Release。
```

请求里写清目标版本、基线分支、打到哪一步。没写 push、没写创建平台 Release，Agent 就不会做。只发 Git tag 时不要求 GitHub / GitLab / Gitea CLI，但 Git remote 必须可读写。

Agent 会锁定远端目标 commit，生成带 Summary、Changes、Validation、Base commit 的更新说明，创建 annotated tag 并推送，再从远端核对。不会给未合并分支打正式 tag，也不会覆盖已有同名 tag。

### 需要改版本文件时走长路径

权威版本文件或仓库内 CHANGELOG 必须随发布改掉时，才创建 `release/v1.6.0` 这类分支和 PR。可以一次说完，也可以拆开授权：

```text
使用 releaser 完成 1.6.0 发布：从 main 创建分支，完成版本更新和验证，创建 PR，检查通过后合并，推送 v1.6.0 tag。不要创建 Forge Release。
```

中途停了，下次说「使用 releaser 检查 v1.6.0 当前发布状态，从尚未完成的步骤继续。不要重复创建分支、PR、tag 或 release。」

要在 Gitea / GitHub 上建平台 Release 时，在请求里写明。没写就不会建。Forge Release 复用 tag 里同一份说明。

### 判断打没打成

远端 tag 解引用后的 commit 就是目标 commit，tag object 里有完整更新说明。只分析时会返回建议版本和依据。卡在某步时会说明停在哪、下次怎么续，不会用「发布成功」盖住未完成的步骤。

## 用 builder 构建项目

builder 按统一契约打 DEB 和 Docker 镜像。项目根会多两个文件：`makefile.builder`（构建入口）和 `.env.builder`（发布凭据，不进 git）。它不改你已有的 `Makefile` 或 `.env`。

正式版本号仍由 releaser 打 tag。builder 只读当前 HEAD，不调用 releaser。

### 接入一个项目

需要 Python 3 和 `make`。打 DEB 还要 `dpkg-deb`，打镜像还要 Docker 和 buildx。在项目根对 Agent 说：

```text
用 builder 初始化这个项目。
```

Agent 会探测轨道、写出 `makefile.builder`，缺发布配置时列出来。然后在 `.env.builder` 填仓库地址和 token：

```text
DEB_SERVER_URL=https://deb.example.com
DEB_REPOSITORY=main
DEB_TOKEN=<token>
DOCKER_REGISTRY=registry.example.com
```

token 只放 `.env.builder` 或密钥系统，不要写进 `.env`，也不要进 git。检查契约：

```text
用 builder 检查这个项目的 makefile.builder 是否符合契约。
```

构建项通过就可以打本地包。缺发布键只挡住上传。

日常构建入口：

```bash
make -f makefile.builder help
make -f makefile.builder version
make -f makefile.builder build
make -f makefile.builder deb
```

### 版本从哪来

`make -f makefile.builder version` 输出一行规范版本，无 `v` 前缀。基线是 HEAD 祖先上最近的稳定 tag，稳定 tag 仅匹配 `v<major>.<minor>.<patch>`，不含 `-rc` 这类后缀。

HEAD 恰好是 `v1.6.0` 时，产物是正式的 `1.6.0`。其它 commit 打测试号：祖先最近稳定 tag 的 patch 机械 +1，再挂构建日、分支、距离、短 SHA。测试 DEB 用 `~`，于是 `1.6.0` &lt; `1.6.1~…` &lt; `1.6.1`。已装上一正式版的机器可以升到 bugfix 测试包；同号正式包仍盖住测试。

分支 `feat/login-v2`，相对 `v1.6.0` 第 7 个 commit，短 SHA `abc1234`，构建日 `20260908`：

```text
规范 / DEB   1.6.1~20260908.feat-login-v2.7+gabc1234
Docker       registry/ns/foo:1.6.1-20260908.feat-login-v2.7.gabc1234
```

不要自己 `git tag | sort -V | tail -1` 取全仓库最大号，也不要把 `git describe --dirty` 的原始字符串写进包名。

### 构建和发布

只构建：

```text
用 builder 构建当前版本的 DEB 和镜像，先不要上传。
```

确认后再上传：

```text
用 builder 把当前 commit 的产物发布到项目已配置的仓库。
```

自己跑也可以：

```bash
make -f makefile.builder deb
make -f makefile.builder push-deb
```

Docker 只有点名镜像时 Agent 才走。脏工作树默认拒绝发布。可能覆盖同版本时会先问你。token 不会出现在输出、提交或回复里。

## 一条完整发布链

代码合进 `main` 且检查通过之后，按这个顺序：

1. 对 Agent：`使用 releaser，为已经合并到 main 的 1.6.0 发布 v1.6.0 tag。不要创建 Forge Release。`
2. 确认远端 `v1.6.0` 指向那次 commit。
3. checkout 到该 tag，或确保当前 HEAD 就是它。
4. 对 Agent：`用 builder 构建当前版本的 DEB，先不要上传。`
5. 核对 `make -f makefile.builder version` 输出 `1.6.0`，再授权上传。

先构建再打 tag，得到的是测试包，版本号会变成下一 patch 的 `~` 形式，不是正式号。

## 常见卡住的地方

- 当前 shell 找不到 `pouch`：`~/.local/bin` 还没进 PATH，重开终端或 `source` 对应 rc。
- 在 `~/.cursor/skills/` 里直接改文件：改的是软链目标，应该改 `~/.pouch/skills/`。Claude Code 有时会把软链替换成普通文件，用 `pouch doctor --fix` 重建。
- `pouch init builder` 这条路径不存在：对 Agent 说「用 builder 初始化」。
- 请求里没写清授权：Agent 会分析或只做到本地，不会擅自 push tag 或上传包。
- 工作区有未提交修改：builder 默认拒绝发布；releaser 不会 stash 或覆盖你的文件。
- 同名 tag 已在远端指向别的 commit：releaser 会停，不会 force push。
- HEAD 不在稳定 tag 上却想打正式包：先打 tag，再构建。

## 还想看什么

- 仓库总览：[README.md](../README.md)
- CLI 命令：[pouch/README.md](../pouch/README.md)
- releaser：[skills/releaser/README.md](../skills/releaser/README.md)
- builder：[skills/builder/README.md](../skills/builder/README.md)
- 设计原则和编写规范：[AGENTS.md](../AGENTS.md)