feat(deployer): skip sync on localhost and complete skill READMEs

Redeploy locally with docker compose when the node is 127.0.0.1 and the image already exists. Make list/sync/remote/deb importable under python3 -I -S. Add human README.md for every builtin skill, slim ack's user-facing docs, and drop unused OpenSpec config.
2026-09-04 00:07:15 +08:00
parent ef22c6829e
commit c2d6a5a0d7
22 changed files with 517 additions and 372 deletions
@@ -2,15 +2,26 @@

 自研 [Agent Skills](https://agentskills.io) 的单一事实来源（SSOT）。仓库、家目录 `~/.pouch` 和 CLI 都叫 **pouch**。Skill 内容与 CLI 在本仓库一并维护。

+人类用法看各 skill 的 `README.md`；`SKILL.md` 是给 Agent 的指令。用户要你代装时，按 [让 Agent 代装](#让-agent-代装) 自己执行，不要只把命令贴回去。
+
+## 前置
+
+- Python 3、git
+- Cursor、Claude Code、Codex，或其它兼容 Agent Skills 的 Agent
+- `~/.local/bin` 需要在 `PATH` 里（`install.sh` 会写入 bash / zsh / fish 的 rc，当前 shell 要重开或 `source` 一次才生效）
+
 ## 快速开始

 ```bash
 git clone https://git.yumee.top/laily/pouch.git ~/.pouch
 cd ~/.pouch
-./install.sh  # 安装 CLI，并将 pouch 项目 skill 安装到所有 Agent
+./install.sh

-pouch add declarative-openspec-loop -g
-pouch select  # 交互式选择并批量安装
+# install.sh 会安装 pouch 命令，并把 pouch 这一个 skill 装到所有 Agent
+# 若当前 shell 找不到 pouch：重开终端，或 source 对应 rc
+
+pouch select          # 交互选择要装的 skill（默认当前项目）
+pouch select -g       # 或装到全局，所有项目都能用
 pouch list
 pouch status
 ```
@@ -24,10 +35,77 @@ mv ~/.skills ~/.pouch

 `install.sh` 会安装 `pouch` 命令，并保留 `pouch` 作为旧命令别名。项目里已有的 `.skills.yaml` 仍可读取；新写入使用 `.pouch.yaml`。

+## 让 Agent 代装
+
+用户说「帮我安装 pouch」「把 skill 装上」时按本节做。CLI 只认 `~/.pouch`。不要用 `pouch select`（必须交互式 TTY）。不要在未确认时覆盖已有的 `~/.pouch`。
+
+### 1. 确认本机
+
+需要 `python3` 和 `git`。缺了先说明怎么装，不要继续。
+
+### 2. 让 `~/.pouch` 指向本仓库
+
+按现状只走一条：
+
+| 现状 | 动作 |
+| --- | --- |
+| 当前目录就是这份仓库（有 `install.sh` 和 `skills/`），且没有 `~/.pouch` | `ln -sfn "$(pwd)" "$HOME/.pouch"` |
+| `~/.pouch` 已在且含 `skills/`、`install.sh` | 沿用 |
+| 只有 `~/.skills` | `mv ~/.skills ~/.pouch` |
+| 都没有 | `git clone https://git.yumee.top/laily/pouch.git ~/.pouch`。失败则问用户本地路径或可用 remote |
+| `~/.pouch` 在，但不是这份仓库 | 停下问用户，不要删、不要覆盖 |
+
+### 3. 装 CLI 和 `pouch` skill
+
+```bash
+"$HOME/.pouch/install.sh"
+export PATH="$HOME/.local/bin:$PATH"
+command -v pouch
+pouch status
+```
+
+`install.sh` 会改 rc，当前会话仍要 `export PATH`。不要让用户重开终端才继续。
+
+### 4. 安装用户要的其它 skill
+
+先 `pouch add --list`。用户没点名就问一次：装哪些、全局还是当前项目。能判断就不要追问。
+
+```bash
+pouch add <name> -g -y     # 全局，所有项目都能用
+pouch add <name> -y        # 仅当前项目
+```
+
+默认 `pouch add` 装到当前工作目录。cwd 是 pouch 仓库本身时用 `-g`，除非用户就在维护 pouch。用户是在自己的应用仓库里请你代装，才做项目级安装。
+
+`install.sh` 已经全局装好 `pouch` skill。其它 skill 不要默认全装。
+
+### 5. 验收并告诉用户下一步
+
+```bash
+pouch status
+pouch doctor
+```
+
+说明：打开 Cursor / Claude Code / Codex 后，按各 skill README 里的示例说话即可。软链异常则 `pouch doctor --fix`。已经装好时只汇报状态，问还要不要加 skill，不要重新 clone。
+
+## 装完之后怎么用
+
+1. 打开已安装目标的 Agent（Cursor / Claude Code / Codex 等）。
+2. 项目级安装：打开那个项目再说话。全局安装（`-g`）：任意项目都可以。
+3. 按对应 skill 的 README，把示例请求发给 Agent。
+
+`./install.sh` 只全局安装 `pouch`。其它 skill 都要 `pouch add` 或 `pouch select`。
+
+```bash
+cd ~/code/my-app
+pouch add ack                    # 当前项目
+pouch add discussion-notes -g    # 全局
+```
+
 ## 仓库结构

 ```
-skills/           # 自研 skill（SSOT）：每个子目录必须有 SKILL.md
+skills/           # 自研 skill（SSOT）：每个子目录含 SKILL.md 和 README.md
 pouch/            # CLI 源码（Python 3）
 bin/pouch         # CLI 入口
 catalog.yaml      # pouch 预置 Skill 来源目录
@@ -36,7 +114,7 @@ AGENTS.md         # 详细规范与架构说明

 | 路径 | 说明 |
 |------|------|
-| [skills/](skills/) | 自研 skill，每个子目录含 `SKILL.md`，可附带 references、templates 和 scripts |
+| [skills/](skills/) | 自研 skill，每个子目录含给人看的 `README.md` 和给 Agent 的 `SKILL.md` |
 | [pouch/](pouch/README.md) | 安装、软链、健康检查 CLI |
 | [catalog.yaml](catalog.yaml) | pouch 预置 Skill 来源目录 |
 | [AGENTS.md](AGENTS.md) | 设计原则、编写规范、架构详解 |
@@ -44,14 +122,19 @@ AGENTS.md         # 详细规范与架构说明
 ## 自研 Skill

 | Skill | 说明 |
-|-------|------|
-| [orc](skills/orc/SKILL.md) | 显式编排开发、版本发布和产物任务，支持 low/mid/high Agent 档位 |
-| [ack](skills/ack/SKILL.md) | 显式初始化、检查并运行 ACK 三角色协作及可选交付闭环 |
-| [pouch](skills/pouch/SKILL.md) | 在项目中创建、安装、反馈和维护 builtin skill |
-| [declarative-openspec-loop](skills/declarative-openspec-loop/SKILL.md) | 声明式编程循环：用户提供校验方式，Agent 自动迭代直到通过 |
-| [discussion-notes](skills/discussion-notes/SKILL.md) | 讨论沉淀：边讨论边维护 Markdown 笔记 |
+| --- | --- |
+| [ack](skills/ack/README.md) | 显式初始化、检查并运行三角色闭环：需求 / bug、测试环境、发版与回归 |
+| [builder](skills/builder/README.md) | 按统一契约构建和发布 DEB / Docker 镜像 |
+| [declarative-openspec-loop](skills/declarative-openspec-loop/README.md) | 你给校验方式，Agent 自动 propose / apply / 校验直到通过 |
+| [deployer](skills/deployer/README.md) | 用 Git 里的 Compose 或 Argo CD 清单部署服务 |
+| [discussion-notes](skills/discussion-notes/README.md) | 边讨论边维护 Markdown 笔记 |
+| [draw-prototype-flow](skills/draw-prototype-flow/README.md) | 把产品想法画成可编辑的 Draw.io 低保真原型和用户动线 |
+| [manage-release](skills/manage-release/README.md) | 给已准备好的 commit 发版本：更新说明、tag、可选 Forge Release |
+| [memory-distill](skills/memory-distill/README.md) | 任务结束后把可复用结论写入通用记忆和项目记忆 |
+| [orc](skills/orc/README.md) | 把开发、发版、DEB / Docker 意图编排成阶段，按档位分发给对应 skill |
+| [pouch](skills/pouch/README.md) | 创建、校验、安装和维护 builtin skill |

-ACK 是包含规范、模板与校验脚本的完整 Skill。安装 Skill 后可初始化当前项目状态：
+ACK 是包含规范、模板与校验脚本的完整 Skill。安装后可初始化当前项目状态：

 ```bash
 pouch init ack
@@ -62,11 +145,13 @@ pouch init ack --project ~/app
 项目可用自然语言让 `/ack` 把测试环境绑到 deployer、维护发版 profile，并在任务
 验证通过后收获回归用例。

+builder 与 deployer 的项目接入走各自 skill 的「初始化」模式，不要 `pouch init builder` 或 `pouch init deployer`。
+
 新建 skill：

 ```bash
 pouch create my-skill --idea "描述要解决的重复问题" --from-project .
-# 由 Agent 完善 ~/.pouch/.drafts/my-skill/SKILL.md
+# 由 Agent 完善 ~/.pouch/.drafts/my-skill/SKILL.md 和 README.md
 pouch check my-skill
 pouch finalize my-skill
 pouch add my-skill -g   # 全局安装验证
@@ -89,7 +174,7 @@ pouch add <name> -g -a cursor

 ```yaml
 skills:
-  - name: declarative-openspec-loop
+  - name: ack
    source: builtin
  - name: think
    source: catalog:waza
@@ -101,9 +186,9 @@ targets:          # 可选，默认 all
 ```

 ```bash
-pouch add declarative-openspec-loop
+pouch add ack
 pouch sync
-pouch remove declarative-openspec-loop
+pouch remove ack
 ```

 ## Catalog 与 Custom Source
@@ -133,7 +218,7 @@ npx skills find typescript

 ```
 本仓库
-├── skills/<name>/     ←── pouch install / enable
+├── skills/<name>/     ←── pouch add / select
 ├── catalog.yaml       ←── 预置来源发现与 fetch
 └── pouch/             ←── python3 -m pouch
         ↑
@@ -159,6 +244,7 @@ npx skills find typescript

 - [AGENTS.md](AGENTS.md) — 完整规范、多 Agent 路径、编写约定
 - [pouch/README.md](pouch/README.md) — CLI 命令参考与开发说明
+- 各 skill 的人类说明见上表 `README.md`

 ## 参考