235 lines
10 KiB
Markdown
235 lines
10 KiB
Markdown
# pouch 上手：安装、打版本、构建
|
||
|
||
pouch 是团队自研 skill 的仓库和安装工具。Skill 是给 Agent 看的工作说明书。你对着 Cursor、Claude Code 或 Codex 说话，Agent 按说明书干活。这份仓库里还有 CLI，用来把 skill 装到各 Agent。
|
||
|
||
这篇只讲日常会碰到的三件事：把 pouch 装上、用 manage-release 打正式版本、用 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 | manage-release | 让 builder 选下一个 SemVer |
|
||
| 打 DEB 或 Docker 镜像 | builder | 让 manage-release 去构建或上传 |
|
||
|
||
|
||
manage-release 选定正式 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 自身：`pouch update`（在 `~/.pouch` 里 `git pull`）。
|
||
|
||
## 把要用的 skill 装上
|
||
|
||
发版本和构建这两个，全局装一次，所有项目都能喊：
|
||
|
||
```bash
|
||
pouch add manage-release -g -y
|
||
pouch add builder -g -y
|
||
```
|
||
|
||
只想在当前仓库启用：
|
||
|
||
```bash
|
||
cd ~/code/my-app
|
||
pouch add manage-release -y
|
||
pouch add builder -y
|
||
```
|
||
|
||
也可以对 Agent 说「把这个项目该用的 skill 接上」，它会按仓库信号建议，再 `pouch add`。builder 不要 `pouch init builder`，初始化是对 Agent 说「用 builder 初始化这个项目」。
|
||
|
||
交互多选：`pouch select -g`。取消勾选不会卸载，卸载用 `pouch remove`。
|
||
|
||
## 怎么对 Agent 说话
|
||
|
||
打开已安装目标的 Agent。项目级安装要打开那个项目再说话；全局安装任意项目都可以。请求里写清 skill 名、目标和授权范围。
|
||
|
||
```text
|
||
使用 manage-release，为已经合并到 main 的 1.6.0 发布 v1.6.0 tag。不要创建 Forge Release。
|
||
用 builder 初始化这个项目。
|
||
用 builder 构建当前版本的 DEB，先不要上传。
|
||
```
|
||
|
||
人看各 skill 目录下的 `README.md`。`SKILL.md` 是给 Agent 的指令，不必通读。
|
||
|
||
## 用 manage-release 打新版本
|
||
|
||
代码已经合进默认分支、测试过了，要打正式 tag 时用它。它不构建 DEB，也不推镜像。
|
||
|
||
### 还没决定版本号
|
||
|
||
```text
|
||
使用 manage-release 检查当前版本和这次改动，建议下一个版本号。只分析，不修改文件。
|
||
```
|
||
|
||
Agent 会读项目版本规则、现有 tag 和实际改动，给出建议和依据。没有项目约定时，单一协调版本默认 SemVer，tag 形如 `v1.6.0`。用户输入 `v1.6.0` 时规范版本是 `1.6.0`，不要产生双前缀。
|
||
|
||
### 默认短路径：直接打 tag
|
||
|
||
项目以 Git tag 作为版本来源，且不需要改 VERSION 文件或把 CHANGELOG 写回仓库时，走这条：
|
||
|
||
```text
|
||
使用 manage-release，为已经合并到 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
|
||
使用 manage-release 完成 1.6.0 发布：从 main 创建分支，完成版本更新和验证，创建 PR，检查通过后合并，推送 v1.6.0 tag。不要创建 Forge Release。
|
||
```
|
||
|
||
中途停了，下次说「使用 manage-release 检查 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`。
|
||
|
||
正式版本号仍由 manage-release 打 tag。builder 只读当前 HEAD，不调用 manage-release。
|
||
|
||
### 接入一个项目
|
||
|
||
需要 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` < `1.6.1~…` < `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：`使用 manage-release，为已经合并到 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 默认拒绝发布；manage-release 不会 stash 或覆盖你的文件。
|
||
- 同名 tag 已在远端指向别的 commit：manage-release 会停，不会 force push。
|
||
- HEAD 不在稳定 tag 上却想打正式包：先打 tag，再构建。
|
||
|
||
## 还想看什么
|
||
|
||
- 仓库总览：[README.md](../README.md)
|
||
- CLI 命令：[pouch/README.md](../pouch/README.md)
|
||
- manage-release：[skills/manage-release/README.md](../skills/manage-release/README.md)
|
||
- builder：[skills/builder/README.md](../skills/builder/README.md)
|
||
- 设计原则和编写规范：[AGENTS.md](../AGENTS.md)
|
||
|