feat: update readme

2026-09-08 15:40:22 +08:00
parent 9b3e16cb63
commit c248c3f0e3
2 changed files with 236 additions and 1 deletions
@@ -4,7 +4,7 @@

 pouch 本义是小袋子，这里取做锦囊妙计的锦囊：skill 就是里面的妙计。

-人类用法看各 skill 的 `README.md`；`SKILL.md` 是给 Agent 的指令。用户要你代装时，读 [skills/pouch/references/install.md](skills/pouch/references/install.md) 并执行，不要只把命令贴回去，也不要用 `pouch select`。
+给同事看怎么装、怎么打版本、怎么构建，读 [docs/getting-started.md](docs/getting-started.md)。人类用法看各 skill 的 `README.md`；`SKILL.md` 是给 Agent 的指令。用户要你代装时，读 [skills/pouch/references/install.md](skills/pouch/references/install.md) 并执行，不要只把命令贴回去，也不要用 `pouch select`。

 ## 前置

@@ -207,6 +207,7 @@ npx skills find typescript

 ## 文档

+- [docs/getting-started.md](docs/getting-started.md)：给同事的安装、打版本、构建教程
 - [AGENTS.md](AGENTS.md) — 完整规范、多 Agent 路径、编写约定
 - [pouch/README.md](pouch/README.md) — CLI 命令参考与开发说明
 - 各 skill 的人类说明见上表 `README.md`
@@ -0,0 +1,234 @@
+# 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` &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：`使用 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)
+