.pouch/docs/getting-started.md

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。

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。

从旧目录迁过来：

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

装完看一眼：

pouch list
pouch status
pouch doctor

软链异常就 pouch doctor --fix。更新 pouch 自身：pouch update（在 ~/.pouch 里 git pull）。

把要用的 skill 装上

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

pouch add releaser -g -y
pouch add builder -g -y

只想在当前仓库启用：

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 名、目标和授权范围。

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

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

用 releaser 打新版本

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

还没决定版本号

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

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

默认短路径：直接打 tag

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

使用 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。可以一次说完，也可以拆开授权：

使用 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 说：

用 builder 初始化这个项目。

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

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

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

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

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

日常构建入口：

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：

规范 / 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 的原始字符串写进包名。

构建和发布

只构建：

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

确认后再上传：

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

自己跑也可以：

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
• CLI 命令：pouch/README.md
• releaser：skills/releaser/README.md
• builder：skills/builder/README.md
• 设计原则和编写规范：AGENTS.md