From 9b3e16cb63613cd7de58a35959a925a89bc7e57a Mon Sep 17 00:00:00 2001 From: laily Date: Tue, 8 Sep 2026 15:25:58 +0800 Subject: [PATCH] feat: update readme --- AGENTS.md | 6 +- README.md | 103 +++++---------- skills/manage-release/README.md | 6 + skills/note-style/README.md | 40 ++++++ skills/pouch/README.md | 19 ++- skills/pouch/SKILL.md | 36 ++++-- skills/pouch/references/install.md | 65 ++++++++++ skills/pouch/references/onboard.md | 49 ++++++++ skills/pouch/scripts/catalog.py | 168 +++++++++++++++++++++++++ skills/pouch/scripts/suggest_skills.py | 144 +++++++++++++++++++++ tests/test_pouch_catalog.py | 123 ++++++++++++++++++ tests/test_project_skill.py | 3 + 12 files changed, 676 insertions(+), 86 deletions(-) create mode 100644 skills/note-style/README.md create mode 100644 skills/pouch/references/install.md create mode 100644 skills/pouch/references/onboard.md create mode 100644 skills/pouch/scripts/catalog.py create mode 100644 skills/pouch/scripts/suggest_skills.py create mode 100644 tests/test_pouch_catalog.py diff --git a/AGENTS.md b/AGENTS.md index e1556ac..8251bbd 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -12,7 +12,7 @@ ## 快速开始 -需要 Python 3、git，以及 Cursor / Claude Code / Codex 或其它兼容 Agent Skills 的 Agent。人类用法见根 [README.md](README.md) 和各 skill 的 `README.md`。用户要代装时按 README 的 [让 Agent 代装](README.md#让-agent-代装) 执行，不要只用 `pouch select`。 +需要 Python 3、git，以及 Cursor / Claude Code / Codex 或其它兼容 Agent Skills 的 Agent。人类用法见根 [README.md](README.md) 和各 skill 的 `README.md`。用户要代装时：pouch skill 已安装则走其「安装 pouch」模式；否则读 [skills/pouch/references/install.md](skills/pouch/references/install.md) 并执行。不要只用 `pouch select`。 ```bash git clone https://git.yumee.top/laily/pouch.git ~/.pouch @@ -55,8 +55,10 @@ AGENTS.md # 本文档 | [discussion-notes](skills/discussion-notes/README.md) | 边讨论边维护 Markdown 笔记 | | [draw-prototype-flow](skills/draw-prototype-flow/README.md) | 把产品想法画成可编辑的 Draw.io 低保真原型和用户动线 | | [eli5](skills/eli5/README.md) | 用大图少字的单页 HTML 把话题讲给完全没背景的人听 | +| [host-sec-check](skills/host-sec-check/README.md) | 对 Linux/VPS 做入侵取向的安全检查，默认只出报告 | | [manage-release](skills/manage-release/README.md) | 给已准备好的 commit 发版本：更新说明、tag、可选 Forge Release | | [memory-distill](skills/memory-distill/README.md) | 任务结束后把可复用结论写入通用记忆和项目记忆 | +| [note-style](skills/note-style/README.md) | 把材料整理成可长期查阅的知识笔记 | | [orc](skills/orc/README.md) | 把开发、发版、DEB / Docker 意图编排成阶段，按档位分发给对应 skill | | [pouch](skills/pouch/README.md) | 创建、校验、安装和维护 builtin skill | @@ -331,6 +333,8 @@ Claude Code 对 symlink 支持不稳定：可能无法发现 skill，或写入 | 我要… | 命令 | 在哪 | | ---------- | --------------------------------- | ---- | | 首次安装 | `git clone ~/.pouch && ~/.pouch/install.sh` | 任意 | +| 让 Agent 代装 | 说「帮我安装 pouch」或丢仓库 URL | 任意 | +| 介绍 / 接入 skill | 说「有哪些 skill」或「把这个项目该用的 skill 接上」 | 项目目录 | | 新建 skill | `pouch create` → Agent 完善 → `check/finalize` | 任意项目 | | 全局启用 | `pouch add -g` | 任意 | | 项目启用 | `pouch add ` 或 `pouch enable ` | 项目目录 | diff --git a/README.md b/README.md index 058b880..842274c 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,9 @@ 自研 [Agent Skills](https://agentskills.io) 的单一事实来源（SSOT）。仓库、家目录 `~/.pouch` 和 CLI 都叫 **pouch**。Skill 内容与 CLI 在本仓库一并维护。 -人类用法看各 skill 的 `README.md`；`SKILL.md` 是给 Agent 的指令。用户要你代装时，按 [让 Agent 代装](#让-agent-代装) 自己执行，不要只把命令贴回去。 +pouch 本义是小袋子，这里取做锦囊妙计的锦囊：skill 就是里面的妙计。 + +人类用法看各 skill 的 `README.md`；`SKILL.md` 是给 Agent 的指令。用户要你代装时，读 [skills/pouch/references/install.md](skills/pouch/references/install.md) 并执行，不要只把命令贴回去，也不要用 `pouch select`。 ## 前置 @@ -37,56 +39,12 @@ mv ~/.skills ~/.pouch ## 让 Agent 代装 -用户说「帮我安装 pouch」「把 skill 装上」时按本节做。CLI 只认 `~/.pouch`。不要用 `pouch select`（必须交互式 TTY）。不要在未确认时覆盖已有的 `~/.pouch`。 +对 Agent 说「帮我安装 pouch」，或把仓库地址丢给它。步骤只维护在 +[skills/pouch/references/install.md](skills/pouch/references/install.md)： +确认 python3/git → 处理 `~/.pouch` → `install.sh` → 用短清单介绍 skill → 问要装哪些。 +不要用 `pouch select`。不要在未确认时覆盖已有的 `~/.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 -g -y # 全局，所有项目都能用 -pouch add -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。 +自己装仍看上面的「快速开始」。 ## 装完之后怎么用 @@ -112,28 +70,34 @@ catalog.yaml # pouch 预置 Skill 来源目录 AGENTS.md # 详细规范与架构说明 ``` -| 路径 | 说明 | -|------|------| -| [skills/](skills/) | 自研 skill，每个子目录含给人看的 `README.md` 和给 Agent 的 `SKILL.md` | -| [pouch/](pouch/README.md) | 安装、软链、健康检查 CLI | -| [catalog.yaml](catalog.yaml) | pouch 预置 Skill 来源目录 | -| [AGENTS.md](AGENTS.md) | 设计原则、编写规范、架构详解 | + +| 路径 | 说明 | +| ---------------------------- | ----------------------------------------------------- | +| [skills/](skills/) | 自研 skill，每个子目录含给人看的 `README.md` 和给 Agent 的 `SKILL.md` | +| [pouch/](pouch/README.md) | 安装、软链、健康检查 CLI | +| [catalog.yaml](catalog.yaml) | pouch 预置 Skill 来源目录 | +| [AGENTS.md](AGENTS.md) | 设计原则、编写规范、架构详解 | + ## 自研 Skill -| 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 低保真原型和用户动线 | -| [eli5](skills/eli5/README.md) | 用大图少字的单页 HTML 把话题讲给完全没背景的人听 | -| [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 | 说明 | +| ----------------------------------------------------------------------- | ------------------------------------------- | +| [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 低保真原型和用户动线 | +| [eli5](skills/eli5/README.md) | 用大图少字的单页 HTML 把话题讲给完全没背景的人听 | +| [host-sec-check](skills/host-sec-check/README.md) | 对 Linux/VPS 做入侵取向的安全检查，默认只出报告 | +| [manage-release](skills/manage-release/README.md) | 给已准备好的 commit 发版本：更新说明、tag、可选 Forge Release | +| [memory-distill](skills/memory-distill/README.md) | 任务结束后把可复用结论写入通用记忆和项目记忆 | +| [note-style](skills/note-style/README.md) | 把材料整理成可长期查阅的知识笔记 | +| [orc](skills/orc/README.md) | 把开发、发版、DEB / Docker 意图编排成阶段，按档位分发给对应 skill | +| [pouch](skills/pouch/README.md) | 创建、校验、安装和维护 builtin skill | + ACK 是包含规范、模板与校验脚本的完整 Skill。安装后可初始化当前项目状态： @@ -253,3 +217,4 @@ npx skills find typescript - [Vercel skills CLI](https://github.com/vercel-labs/skills) - [skills.sh](https://skills.sh) - [Cursor Skills 文档](https://cursor.com/docs/context/skills) + diff --git a/skills/manage-release/README.md b/skills/manage-release/README.md index 00a519d..41ee313 100644 --- a/skills/manage-release/README.md +++ b/skills/manage-release/README.md @@ -20,6 +20,12 @@ pouch add manage-release -g # 全局 - 请求里写清目标版本、基线分支，以及允许执行到哪一步。没有明确授权的远端写操作 不会执行。 +## 使用示例 + +```text +使用 manage-release，为已经合并到 main 的 1.6.0 发布 v1.6.0 tag。不要创建 Forge Release。 +``` + ## 常见用法 ### 确定下一个版本号 diff --git a/skills/note-style/README.md b/skills/note-style/README.md new file mode 100644 index 0000000..52f5733 --- /dev/null +++ b/skills/note-style/README.md @@ -0,0 +1,40 @@ +# note-style + +把已有材料整理成可长期查阅的知识笔记：压缩空话、统一术语，保留事实、公式、条件和参考。 + +## 什么时候使用 + +- 要把聊天稿、草稿或 AI 生成的长文改成能放进知识库的笔记。 +- 要整理 Obsidian 笔记，去掉重复和口语。 +- 要把技术原理或操作方案写成教科书 / 手册口吻。 + +不适合：还在讨论、还没有可依据的材料，或需要 Agent 发明新结论。 + +## 使用前准备 + +- 给出要整理的材料（文件路径、粘贴正文，或当前对话里的那一段）。 +- 可选：目标读者、篇幅要求、笔记路径。不说则在原材料风格上压缩约三成。 + +## 使用示例 + +```text +用 note-style 把这篇对话整理成可放进 Obsidian 的技术笔记，保留公式和适用条件。 +``` + +```text +把 docs/draft-auth.md 改写成手册口吻，删掉空话，有疑点列待核实项。 +``` + +## Agent 会做什么 + +1. 抽出事实、定义、步骤、条件和参考，删掉铺垫和重复。 +2. 按材料类型选结构（原理或操作），用中性书面语重写全文。 +3. 先给你完整笔记；只有事实或技术疑点时才追加「待核实项」。 + +不会补没有依据的结论，也不会为缩短篇幅删掉必要条件。 + +## 如何判断完成 + +- 得到一份完整笔记，而不是改写说明。 +- 原文里的公式、条件、安全警告和参考还在。 +- 没有聊天式过渡或段末复述。 diff --git a/skills/pouch/README.md b/skills/pouch/README.md index 2ef59c7..ffc489a 100644 --- a/skills/pouch/README.md +++ b/skills/pouch/README.md @@ -7,6 +7,7 @@ - 想把项目里的重复工作沉淀成一个 skill。 - 想完善、校验、转正或发布已有 skill。 - 想把自研 skill 安装到当前项目或全局 Agent。 +- 想让 Agent 代装 pouch，或介绍有哪些 skill、在当前项目接入。 - 想检查并修复 skill 软链接。 - 想优化某个已有 skill 的结构，减少点中后灌进上下文的内容。 @@ -22,6 +23,10 @@ CLI 命令细节见仓库里的 [pouch/README.md](../../pouch/README.md)。 ## 使用示例 ```text +帮我安装 pouch。 +帮我装 https://git.yumee.top/laily/pouch +有哪些自研 skill，各用一句话介绍。 +把这个项目该用的 skill 接上。 帮我把「评审 PR 时按这份清单走」做成一个自研 skill。 pouch 帮我检查 discussion-notes 这个 skill。 pouch 帮忙优化 ack 这个 skill 结构，减少 token 浪费。 @@ -107,15 +112,19 @@ pouch doctor --fix ## Agent 会做什么 -1. 创建草稿到 `~/.pouch/.drafts/`，按你的想法完善 `SKILL.md` 和给人看的 `README.md`。 -2. 跑 `pouch check`；你确认后再 `finalize` 到 `skills/`。 -3. 安装只建指向 SSOT 的软链，不复制文件。默认装当前项目；只有你明确要求时才加 `-g`。 -4. 优化结构时先测量再改 SSOT，不删发版、部署类安全限制。 -5. 未要求时不 commit、不 push、不全局安装。 +1. 本机还没有 `~/.pouch` 时，按安装剧本 clone 或链接，跑 `install.sh`，再介绍 builtin skill。 +2. 在业务仓库里按文件信号建议 skill，`pouch add` 之后问一句要不要初始化 ack / builder / deployer。 +3. 创建草稿到 `~/.pouch/.drafts/`，按你的想法完善 `SKILL.md` 和给人看的 `README.md`。 +4. 跑 `pouch check`；你确认后再 `finalize` 到 `skills/`。 +5. 安装只建指向 SSOT 的软链，不复制文件。默认装当前项目；只有你明确要求时才加 `-g`。 +6. 优化结构时先测量再改 SSOT，不删发版、部署类安全限制。 +7. 未要求时不 commit、不 push、不全局安装。 ## 如何判断完成 - `pouch check ` 输出校验通过。 - 正式 skill 同时包含 `SKILL.md` 和 `README.md`。 - `pouch status` 或 `pouch doctor` 显示目标软链接正常。 +- 代装完成后 CLI 可用，且介绍了 builtin skill 的一句话和示例请求。 +- 项目接入后，建议的 skill 已 `pouch add`；ack / builder / deployer 要么已初始化，要么明确问过。 - 优化结构时：审计报告有前后体积，安全限制仍在 `SKILL.md`，没有为缩字删掉模式。 diff --git a/skills/pouch/SKILL.md b/skills/pouch/SKILL.md index 606c5aa..60f8c95 100644 --- a/skills/pouch/SKILL.md +++ b/skills/pouch/SKILL.md @@ -1,10 +1,10 @@ --- name: pouch description: >- - 创建、校验、转正、安装或发布 ~/.pouch 自研 skill，初始化 skill 项目状态， - 或优化 skill 分层加载结构以减少 token 浪费。 - 触发词：pouch、skiff、自研 skill、创建 skill、publish skill、安装自研 skill、 - 初始化 skill、优化 skill 结构、减少 token 浪费、skill 太长、分层加载。 + 创建、校验、转正、安装或发布 ~/.pouch 自研 skill；代装 pouch、介绍 builtin + skill、在项目里接入并引导初始化；或优化 skill 分层结构以减少 token 浪费。 + 触发词：pouch、skiff、帮我装 pouch、有哪些 skill、skill 怎么用、接入当前项目、 + 初始化 skill、创建 skill、publish skill、优化 skill 结构、分层加载。 --- # pouch 自研 Skill 工作流 @@ -15,24 +15,38 @@ SSOT 固定在 `~/.pouch/skills//`。内容通过 **symlink** 分发到各 ## 选择模式 +- 安装 pouch、帮我装 pouch、代装、丢仓库 URL、`~/.pouch` 还不存在：读 + [install.md](references/install.md) 并执行。 +- 有哪些 skill、skill 怎么用、介绍 skill：执行「介绍 builtin skill」。 +- 在这个项目接入、把 skill 接上、引导初始化：读 + [onboard.md](references/onboard.md) 并执行。 - 创建、完善、转正草稿：执行「创建新的 skill」。 - 行为不对、触发不准、校验失败、可复用优化回流：执行「问题或优化回流」。 -- 优化结构、减少 token 浪费、skill 太长、分层加载：执行「优化 skill 结构」。先读 - [token-structure.md](references/token-structure.md)。 +- 优化结构、减少 token 浪费、skill 太长、分层加载：执行「优化 skill 结构」。 - 安装、卸载、浏览、init、status：执行「安装与维护」。 --- -## 在项目中使用 skill +## 介绍 builtin skill -先浏览可用的 builtin skill，再安装到当前项目： +不要通读各 README，不要把 `pouch add --list` 的 description 念给用户。跑： + +```bash +python3 /scripts/catalog.py +``` + +把表格里的「做什么」和「可以这么说」原样告诉用户。用户点名再 `pouch add`。 + +## 在项目中使用 skill + +已点名则直接安装；没点名或要按仓库判断：读 [onboard.md](references/onboard.md)。 ```bash -pouch add --list pouch add -a cursor -a claude -a codex -a agents -y ``` -`pouch add ` 默认安装到当前项目；只有用户明确需要所有项目使用时才加 `-g`。安装结果是指向 `~/.pouch/skills//` 的软链，不要在 Agent 目录创建副本。 +默认当前项目；只有用户明确需要所有项目使用时才加 `-g`。只建指向 +`~/.pouch/skills//` 的软链，不要在 Agent 目录创建副本。 ## 创建新的 skill @@ -159,7 +173,7 @@ pouch remove discussion-notes -g -a cursor -y # 全局 pouch rm discussion-notes -g -y # rm 别名 ``` -浏览可用自研 skill： +浏览可用自研 skill（给 Agent 匹配用，不要念给用户）： ```bash pouch add --list diff --git a/skills/pouch/references/install.md b/skills/pouch/references/install.md new file mode 100644 index 0000000..5e8fd80 --- /dev/null +++ b/skills/pouch/references/install.md @@ -0,0 +1,65 @@ +# 安装 pouch + +用户说「帮我安装 pouch」「把 skill 装上」，或丢来仓库 URL / 本地路径时执行。 +本文件是代装步骤的唯一详细来源。不要用 `pouch select`（必须交互式 TTY）。 +不要在未确认时覆盖已有的 `~/.pouch`。CLI 只认 `~/.pouch`。 + +默认 remote：`https://git.yumee.top/laily/pouch.git`。用户给了 URL 或本地路径则用用户的。 + +## 1. 确认本机 + +需要 `python3` 和 `git`。缺了先说明怎么装，不要继续。 + +## 2. 让 `~/.pouch` 指向本仓库 + +按现状只走一条： + +| 现状 | 动作 | +| --- | --- | +| 当前目录就是这份仓库（有 `install.sh` 和 `skills/`），且没有 `~/.pouch` | `ln -sfn "$(pwd)" "$HOME/.pouch"` | +| `~/.pouch` 已在且含 `skills/`、`install.sh` | 沿用 | +| 只有 `~/.skills` | `mv ~/.skills ~/.pouch` | +| 都没有 | `git clone ~/.pouch`。失败则问用户本地路径或可用 remote | +| `~/.pouch` 在，但不是这份仓库 | 停下问用户，不要删、不要覆盖 | + +clone 私有 Git 失败时停下来问路径或认证，不要改 remote、不要改用交互式 `pouch select`。 + +## 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`。不要让用户重开终端才继续。 +它只全局安装 **pouch** 这一个 skill。其它 skill 不要默认全装。 + +## 4. 介绍 builtin skill，再问要装哪些 + +```bash +python3 "$HOME/.pouch/skills/pouch/scripts/catalog.py" +``` + +把表格里的「做什么」和「可以这么说」告诉用户。不要念 frontmatter `description`， +不要通读各 README。用户没点名就问一次：装哪些、全局还是当前项目。能判断就不要追问。 + +```bash +pouch add -g -y # 全局，所有项目都能用 +pouch add -y # 仅当前项目 +``` + +默认 `pouch add` 装到当前工作目录。cwd 是 pouch 仓库本身时用 `-g`，除非用户就在维护 pouch。 +用户是在自己的应用仓库里请你代装，才做项目级安装。 + +## 5. 验收 + +```bash +pouch status +pouch doctor +``` + +软链异常则 `pouch doctor --fix`。已经装好时只汇报状态，问还要不要加 skill，不要重新 clone。 + +当前目录是业务仓库（不是 pouch 仓库）时，回到 SKILL.md，走「接入当前项目」。 diff --git a/skills/pouch/references/onboard.md b/skills/pouch/references/onboard.md new file mode 100644 index 0000000..5e99a42 --- /dev/null +++ b/skills/pouch/references/onboard.md @@ -0,0 +1,49 @@ +# 在当前项目接入 skill + +用户说「把 skill 接上」「在这个项目初始化 skill」「这个仓库该用哪些 pouch skill」时执行。 +安装和初始化是两步，不要只 `pouch add` 就当接入完成。 + +当前目录是 pouch 仓库本身（有 `install.sh`、`skills/pouch/SKILL.md`、`bin/pouch`）时停： +这是维护 SSOT 的仓库，不要按业务项目接入。改 skill 走「创建」或「问题或优化回流」。 + +## 1. 看仓库信号 + +```bash +python3 /scripts/suggest_skills.py +``` + +只根据脚本输出建议，不要为了「可能有用」推荐 eli5、note-style、host-sec-check 这类无仓库信号的 skill。 +用户点名的除外。 + +## 2. 安装 + +把 `suggested` 和 `already` 都列为应安装的 skill（`already` 表示项目里已有状态， +软链仍要 `pouch add`，除非已经装上）。用户说「接上该用的」时只装这两类，不要全装 builtin。 +只对 `init` 列问要不要初始化。 + +默认当前项目： + +```bash +pouch add -a cursor -a claude -a codex -a agents -y +``` + +只有用户明确要所有项目都能用时才加 `-g`。cwd 是 pouch 仓库时不要走到这一步。 + +## 3. 问一句要不要初始化 + +对已经装上、或本来就在的 ack / builder / deployer，看脚本的 `init` 列： + +| Skill | 尚未初始化时对用户说 | 不要 | +| --- | --- | --- | +| ack | `/ack 初始化` 或 `pouch init ack` | 静默 `pouch init` | +| builder | 「用 builder 初始化」 | `pouch init builder` | +| deployer | 「用 deployer 初始化」 | `pouch init deployer` | + +一次问清要初始化哪些。用户没点名不要自己跑初始化。ACK 初始化**不会**自动初始化 +deployer / builder，需要的话要另说。 + +orc、manage-release 和其余 builtin 装上就能用，不必项目初始化。 + +## 4. 介绍怎么喊 + +装完后跑 `catalog.py`，只念本次装上的那几行「可以这么说」。 diff --git a/skills/pouch/scripts/catalog.py b/skills/pouch/scripts/catalog.py new file mode 100644 index 0000000..19f828f --- /dev/null +++ b/skills/pouch/scripts/catalog.py @@ -0,0 +1,168 @@ +#!/usr/bin/env python3 +"""Print a human-facing builtin skill list: one-liner + copy-paste example. + +Reads each skill's README.md. Do not substitute SKILL.md descriptions. +""" + +from __future__ import annotations + +import argparse +import re +import sys +from pathlib import Path + +_HEADING_RE = re.compile(r"^#{1,6}\s+") +_FENCE_RE = re.compile(r"^```(\w+)?\s*$") + + +def skills_dir() -> Path: + here = Path(__file__).resolve() + repo_skills = here.parents[2] + if (repo_skills / "pouch" / "SKILL.md").is_file(): + return repo_skills + return Path.home() / ".pouch" / "skills" + + +def _strip_md(text: str) -> str: + text = re.sub(r"\[([^\]]+)\]\([^)]+\)", r"\1", text) + text = re.sub(r"`([^`]+)`", r"\1", text) + return " ".join(text.split()) + + +def _first_sentence(text: str) -> str: + text = _strip_md(text).strip() + for sep in ("。", "！", "？"): + idx = text.find(sep) + if idx != -1: + return text[: idx + 1] + return text.rstrip("：:") + ("。" if text else "") + + +def _lede(readme: str) -> str: + lines = readme.splitlines() + i = 0 + while i < len(lines) and ( + not lines[i].strip() or _HEADING_RE.match(lines[i]) + ): + i += 1 + chunk: list[str] = [] + while i < len(lines): + raw = lines[i] + stripped = raw.strip() + if not stripped: + break + if _HEADING_RE.match(raw) or stripped.startswith(("- ", "* ", "> ")): + break + chunk.append(stripped) + i += 1 + return _first_sentence(" ".join(chunk)) + + +def _section_body(readme: str, titles: tuple[str, ...]) -> str | None: + lines = readme.splitlines() + start = None + for i, line in enumerate(lines): + if line.startswith("## ") and line[3:].strip() in titles: + start = i + 1 + break + if start is None: + return None + end = len(lines) + for j in range(start, len(lines)): + if lines[j].startswith("## "): + end = j + break + return "\n".join(lines[start:end]) + + +def _first_example(readme: str) -> str: + body = _section_body(readme, ("使用示例", "常见用法")) + search = body if body is not None else readme + lines = search.splitlines() + i = 0 + while i < len(lines): + fence = _FENCE_RE.match(lines[i].strip()) + if not fence: + i += 1 + continue + i += 1 + block: list[str] = [] + while i < len(lines) and not lines[i].strip().startswith("```"): + block.append(lines[i]) + i += 1 + for raw in block: + stripped = raw.strip() + if not stripped or stripped.startswith("#"): + continue + return stripped + i += 1 + return "" + + +def iter_skills(root: Path) -> list[Path]: + skills: list[Path] = [] + if not root.is_dir(): + return skills + for entry in sorted(root.iterdir()): + if not entry.is_dir() or entry.name.startswith("_"): + continue + if (entry / "SKILL.md").is_file(): + skills.append(entry) + return skills + + +def catalog_rows(root: Path) -> list[tuple[str, str, str]]: + rows: list[tuple[str, str, str]] = [] + errors: list[str] = [] + for skill in iter_skills(root): + readme_path = skill / "README.md" + if not readme_path.is_file(): + errors.append(f"{skill.name}: 缺少 README.md") + continue + text = readme_path.read_text(encoding="utf-8") + lede = _lede(text) + example = _first_example(text) + if not lede: + errors.append(f"{skill.name}: README 缺少一句话说明") + if not example: + errors.append(f"{skill.name}: README 缺少可复制的使用示例") + if lede and example: + rows.append((skill.name, lede, example)) + if errors: + raise SystemExit("catalog 失败:\n " + "\n ".join(errors)) + return rows + + +def format_table(rows: list[tuple[str, str, str]]) -> str: + lines = [ + "| Skill | 做什么 | 可以这么说 |", + "| --- | --- | --- |", + ] + for name, lede, example in rows: + example = example.replace("|", "\\|") + lede = lede.replace("|", "\\|") + lines.append(f"| {name} | {lede} | `{example}` |") + return "\n".join(lines) + "\n" + + +def main() -> int: + parser = argparse.ArgumentParser( + description="列出 builtin skill 的一句话说明和可复制示例" + ) + parser.add_argument( + "--skills-dir", + type=Path, + default=None, + help="skill 根目录（默认本仓库 skills/ 或 ~/.pouch/skills）", + ) + args = parser.parse_args() + root = args.skills_dir.resolve() if args.skills_dir else skills_dir() + if not root.is_dir(): + print(f"找不到 skills 目录: {root}", file=sys.stderr) + return 2 + sys.stdout.write(format_table(catalog_rows(root))) + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/skills/pouch/scripts/suggest_skills.py b/skills/pouch/scripts/suggest_skills.py new file mode 100644 index 0000000..c3ab5ba --- /dev/null +++ b/skills/pouch/scripts/suggest_skills.py @@ -0,0 +1,144 @@ +#!/usr/bin/env python3 +"""Suggest pouch skills from well-known files in a project root.""" + +from __future__ import annotations + +import argparse +import sys +from pathlib import Path + +INIT = { + "ack": "说「/ack 初始化」或 `pouch init ack`；不要静默初始化", + "builder": "说「用 builder 初始化」；不要 `pouch init builder`", + "deployer": "说「用 deployer 初始化」；不要 `pouch init deployer`", +} + +FILE_SIGNALS: dict[str, tuple[str, ...]] = { + "ack": (".pouch/ack",), + "builder": ( + "makefile.builder", + "debian", + "Dockerfile", + "Containerfile", + ".env.builder", + ), + "deployer": ( + ".pouch/deployer", + "compose.yaml", + "compose.yml", + "docker-compose.yaml", + "docker-compose.yml", + "argocd.yaml", + "k8s", + "helm", + ), + "manage-release": ("CHANGELOG.md", "CHANGELOG", "VERSION"), + "declarative-openspec-loop": ("openspec", ".openspec"), + "discussion-notes": ("000inbox",), +} + +INITED_MARKERS = { + "ack": (".pouch/ack",), + "builder": ("makefile.builder",), + "deployer": (".pouch/deployer",), +} + + +def project_root(start: Path) -> Path: + cur = start.resolve() + if cur.is_file(): + cur = cur.parent + for candidate in (cur, *cur.parents): + if (candidate / ".git").exists(): + return candidate + return cur + + +def is_pouch_repo(root: Path) -> bool: + return ( + (root / "install.sh").is_file() + and (root / "bin" / "pouch").is_file() + and (root / "skills" / "pouch" / "SKILL.md").is_file() + ) + + +def existing(root: Path, rel: str) -> bool: + return (root / rel).exists() + + +def hits(root: Path, names: tuple[str, ...]) -> list[str]: + return [name for name in names if existing(root, name)] + + +def suggest(root: Path) -> dict[str, object]: + suggested: list[tuple[str, list[str]]] = [] + already: list[tuple[str, list[str]]] = [] + init: list[tuple[str, str]] = [] + for name, names in FILE_SIGNALS.items(): + found = hits(root, names) + if not found: + continue + inited = hits(root, INITED_MARKERS.get(name, ())) + if inited: + already.append((name, inited)) + else: + suggested.append((name, found)) + if name in INIT and not inited: + init.append((name, INIT[name])) + return { + "root": str(root), + "this_is_pouch_repo": is_pouch_repo(root), + "suggested": suggested, + "already": already, + "init": init, + } + + +def format_report(data: dict[str, object]) -> str: + lines = [f"project: {data['root']}"] + if data["this_is_pouch_repo"]: + lines.append("this_is_pouch_repo: true") + lines.append("不要按业务项目接入。维护 skill 走 pouch 的创建或回流模式。") + return "\n".join(lines) + "\n" + + lines.append("this_is_pouch_repo: false") + suggested = data["suggested"] + already = data["already"] + init = data["init"] + if suggested: + lines.append("suggested:") + for name, why in suggested: + lines.append(f" {name}\twhy: {', '.join(why)}") + else: + lines.append("suggested: (none)") + if already: + lines.append("already:") + for name, why in already: + lines.append(f" {name}\t{', '.join(why)}") + else: + lines.append("already: (none)") + if init: + lines.append("init:") + for name, how in init: + lines.append(f" {name}\t{how}") + else: + lines.append("init: (none)") + return "\n".join(lines) + "\n" + + +def main() -> int: + parser = argparse.ArgumentParser(description="根据仓库信号建议 pouch skill") + parser.add_argument( + "path", + nargs="?", + default=".", + help="项目目录（默认 cwd；向上找 .git）", + ) + args = parser.parse_args() + root = project_root(Path(args.path)) + sys.stdout.write(format_report(suggest(root))) + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/tests/test_pouch_catalog.py b/tests/test_pouch_catalog.py new file mode 100644 index 0000000..18628cf --- /dev/null +++ b/tests/test_pouch_catalog.py @@ -0,0 +1,123 @@ +from __future__ import annotations + +import subprocess +import sys +import tempfile +import unittest +from pathlib import Path + +REPO_ROOT = Path(__file__).resolve().parents[1] +CATALOG = REPO_ROOT / "skills" / "pouch" / "scripts" / "catalog.py" +SUGGEST = REPO_ROOT / "skills" / "pouch" / "scripts" / "suggest_skills.py" + + +def _run(script: Path, *args: str) -> subprocess.CompletedProcess[str]: + return subprocess.run( + [sys.executable, str(script), *args], + check=False, + capture_output=True, + text=True, + ) + + +class CatalogTests(unittest.TestCase): + def test_repo_skills_have_lede_and_example(self) -> None: + result = _run(CATALOG, "--skills-dir", str(REPO_ROOT / "skills")) + self.assertEqual(result.returncode, 0, result.stderr) + for name in ( + "ack", + "builder", + "deployer", + "host-sec-check", + "manage-release", + "note-style", + "pouch", + ): + self.assertIn(f"| {name} |", result.stdout) + self.assertIn("/ack 初始化", result.stdout) + self.assertIn("用 builder 初始化这个项目", result.stdout) + self.assertNotIn("触发词", result.stdout) + + def test_missing_readme_fails(self) -> None: + with tempfile.TemporaryDirectory() as tmp: + skill = Path(tmp) / "demo" + skill.mkdir() + (skill / "SKILL.md").write_text( + "---\nname: demo\ndescription: d\n---\n# demo\n", + encoding="utf-8", + ) + result = _run(CATALOG, "--skills-dir", tmp) + self.assertEqual(result.returncode, 1) + self.assertIn("缺少 README.md", result.stderr) + + def test_extracts_first_sentence_and_skips_hash_comments(self) -> None: + with tempfile.TemporaryDirectory() as tmp: + skill = Path(tmp) / "demo" + skill.mkdir() + (skill / "SKILL.md").write_text( + "---\nname: demo\ndescription: d\n---\n# demo\n", + encoding="utf-8", + ) + (skill / "README.md").write_text( + "# demo\n\n" + "这是一句话说明。后面还有一句不该进短清单。\n\n" + "## 使用示例\n\n" + "```text\n" + "# 注释\n" + "用 demo 做这件事。\n" + "```\n", + encoding="utf-8", + ) + result = _run(CATALOG, "--skills-dir", tmp) + self.assertEqual(result.returncode, 0, result.stderr) + self.assertIn("这是一句话说明。", result.stdout) + self.assertNotIn("不该进短清单", result.stdout) + self.assertIn("用 demo 做这件事。", result.stdout) + + +class SuggestSkillsTests(unittest.TestCase): + def test_pouch_repo_is_not_an_app(self) -> None: + result = _run(SUGGEST, str(REPO_ROOT)) + self.assertEqual(result.returncode, 0, result.stderr) + self.assertIn("this_is_pouch_repo: true", result.stdout) + self.assertNotIn("suggested:", result.stdout) + + def test_dockerfile_suggests_builder(self) -> None: + with tempfile.TemporaryDirectory() as tmp: + root = Path(tmp) + (root / "Dockerfile").write_text("FROM scratch\n", encoding="utf-8") + result = _run(SUGGEST, str(root)) + self.assertEqual(result.returncode, 0, result.stderr) + self.assertIn("this_is_pouch_repo: false", result.stdout) + self.assertIn("builder", result.stdout) + self.assertIn("Dockerfile", result.stdout) + self.assertIn("用 builder 初始化", result.stdout) + self.assertIn("不要 `pouch init builder`", result.stdout) + + def test_existing_makefile_builder_is_already(self) -> None: + with tempfile.TemporaryDirectory() as tmp: + root = Path(tmp) + (root / "makefile.builder").write_text("build:\n", encoding="utf-8") + result = _run(SUGGEST, str(root)) + self.assertEqual(result.returncode, 0, result.stderr) + self.assertIn("already:", result.stdout) + self.assertIn("builder", result.stdout) + self.assertIn("init: (none)", result.stdout) + + def test_compose_and_ack_dir(self) -> None: + with tempfile.TemporaryDirectory() as tmp: + root = Path(tmp) + (root / "compose.yaml").write_text("services: {}\n", encoding="utf-8") + (root / ".pouch" / "ack").mkdir(parents=True) + result = _run(SUGGEST, str(root)) + self.assertEqual(result.returncode, 0, result.stderr) + self.assertIn("deployer", result.stdout) + self.assertIn("compose.yaml", result.stdout) + self.assertIn("ack", result.stdout) + self.assertIn(".pouch/ack", result.stdout) + self.assertIn("用 deployer 初始化", result.stdout) + self.assertNotIn("/ack 初始化", result.stdout) + + +if __name__ == "__main__": + unittest.main() diff --git a/tests/test_project_skill.py b/tests/test_project_skill.py index 1953177..000f6cc 100644 --- a/tests/test_project_skill.py +++ b/tests/test_project_skill.py @@ -21,6 +21,9 @@ class ProjectSkillContentTests(unittest.TestCase): "第三方 skill", "pouch init ack", "显式调用全局 `/ack` skill", + "references/install.md", + "scripts/catalog.py", + "references/onboard.md", ): self.assertIn(expected, content)