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
@@ -12,16 +12,14 @@

 ## 快速开始

+需要 Python 3、git，以及 Cursor / Claude Code / Codex 或其它兼容 Agent Skills 的 Agent。人类用法见根 [README.md](README.md) 和各 skill 的 `README.md`。用户要代装时按 README 的 [让 Agent 代装](README.md#让-agent-代装) 执行，不要只用 `pouch select`。
+
 ```bash
-# 1. 克隆并关联
 git clone https://git.yumee.top/laily/pouch.git ~/.pouch
 cd ~/.pouch && ./install.sh

-# install.sh 会自动把 pouch 项目 skill 安装到所有 Agent
-# 2. 安装其他 skill
-pouch add declarative-openspec-loop -g
-
-# 3. 查看状态
+# install.sh 只把 pouch skill 装到所有 Agent；其它 skill 用 select / add
+pouch select -g
 pouch list
 pouch status
 ```
@@ -31,19 +29,11 @@ pouch status
 ## 仓库结构

 ```
-skills/
-├── _template/                  # 新建 skill 的脚手架
-├── ack/                        # 完整 ACK skill，含 references/templates/scripts
-├── declarative-openspec-loop/  # 自研 skill，必须含 SKILL.md
-│   ├── SKILL.md
-│   └── reference.md
-├── discussion-notes/           # 讨论沉淀笔记
-│   ├── SKILL.md
-│   └── reference.md
-pouch/                          # CLI 源码（Python 3）
-bin/pouch                       # CLI 入口
-catalog.yaml                   # pouch 预置 Skill 来源目录
-AGENTS.md                       # 本文档
+skills/           # 自研 skill（SSOT）：每个子目录含 SKILL.md（Agent）和 README.md（人类）
+pouch/            # CLI 源码（Python 3）
+bin/pouch         # CLI 入口
+catalog.yaml      # pouch 预置 Skill 来源目录
+AGENTS.md         # 本文档
 ```

 **本仓库包含**：`skills/`、`pouch/`、`bin/pouch`、`catalog.yaml`、`AGENTS.md`
@@ -56,16 +46,21 @@ AGENTS.md                       # 本文档
 ### 内置（Builtin）


-| Skill                                                                  | 说明                                                |
-| ---------------------------------------------------------------------- | ------------------------------------------------- |
-| [orc](skills/orc/SKILL.md)                                             | ORC 入口：显式编排开发、版本发布与产物任务，支持 Agent 分档         |
-| [ack](skills/ack/SKILL.md)                                             | ACK 入口：显式初始化、检查并运行三角色闭环、测试环境、发版与回归     |
-| [pouch](skills/pouch/SKILL.md)                                         | 本项目工作流：创建、使用、反馈与更新 builtin skill               |
-| [declarative-openspec-loop](skills/declarative-openspec-loop/SKILL.md) | 声明式编程循环：用户提供校验方式，Agent 自动 propose/apply/校验并迭代直到通过 |
-| [discussion-notes](skills/discussion-notes/SKILL.md)                   | 讨论沉淀：边讨论边维护 Markdown 笔记，无 .raw.md                 |
+| Skill | 说明 |
+| --- | --- |
+| [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 |


-新建 skill：复制 `skills/_template/` → `skills/<name>/`，编辑 `SKILL.md`，在本仓库 commit。
+新建 skill：优先 `pouch create`；或复制 `skills/_template/` → `skills/<name>/`，编辑 `SKILL.md` 和 `README.md`，在本仓库 commit。

 Skill 需要的稳定规范、模板、示例和脚本直接放在自己的目录中，例如
 `skills/ack/references/`、`templates/`、`examples/` 和 `scripts/`。项目初始化只生成
@@ -164,12 +159,6 @@ catalog.yaml               ←──   pouch add / fetch
 | **Custom Source** | `~/.local/share/pouch/sources/` 或本地路径 | `pouch source add/fetch` |
 | **External NPM** | `node_modules/`                    | `npx skills add` / `skills-npm` |

-### 非 Skill 资料分类
-
-| 类型 | 位置 | 维护方式 |
-| --- | --- | --- |
-| **OpenSpec 配置** | `openspec/` | 本仓库 commit；服务于本仓库自身的规格流程 |
-

 ### 多 Agent 路径

@@ -260,7 +249,8 @@ pouch sync

 ```
 skill-name/
-├── SKILL.md          # 必需
+├── SKILL.md          # 必需，给 Agent
+├── README.md         # 必需，给人类
 ├── reference.md      # 可选
 ├── examples.md       # 可选
 └── scripts/          # 可选
@@ -285,7 +275,7 @@ description: >-
 ### 新建流程

 1. `pouch create my-skill --idea "..." --from-project .`
-2. Agent 编辑 `~/.pouch/.drafts/my-skill/SKILL.md`
+2. Agent 编辑 `~/.pouch/.drafts/my-skill/SKILL.md` 和 `README.md`
 3. `pouch check my-skill`
 4. 用户确认后执行 `pouch finalize my-skill`
 5. `pouch add my-skill -a cursor -g -y` 验证
@@ -341,8 +331,8 @@ Claude Code 对 symlink 支持不稳定：可能无法发现 skill，或写入
 | ---------- | --------------------------------- | ---- |
 | 首次安装       | `git clone <repo> ~/.pouch && ~/.pouch/install.sh` | 任意   |
 | 新建 skill   | `pouch create` → Agent 完善 → `check/finalize` | 任意项目 |
-| 全局启用       | `pouch install <name>`            | 任意   |
-| 项目启用       | `pouch enable <name>`             | 项目目录 |
+| 全局启用       | `pouch add <name> -g`             | 任意   |
+| 项目启用       | `pouch add <name>` 或 `pouch enable <name>` | 项目目录 |
 | 看状态        | `pouch status`                    | 任意   |
 | 装社区 skill  | `npx skills add owner/repo -g -y` | 任意   |
 | 更新外部 skill | `pouch fetch <name>`              | 任意   |