feat: update readme

2026-09-08 15:25:58 +08:00
parent 06865939e1
commit 9b3e16cb63
12 changed files with 676 additions and 86 deletions
@@ -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 <name>` 输出校验通过。
 - 正式 skill 同时包含 `SKILL.md` 和 `README.md`。
 - `pouch status` 或 `pouch doctor` 显示目标软链接正常。
+- 代装完成后 CLI 可用，且介绍了 builtin skill 的一句话和示例请求。
+- 项目接入后，建议的 skill 已 `pouch add`；ack / builder / deployer 要么已初始化，要么明确问过。
 - 优化结构时：审计报告有前后体积，安全限制仍在 `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/<name>/`。内容通过 **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 <pouch-skill-dir>/scripts/catalog.py
+```
+
+把表格里的「做什么」和「可以这么说」原样告诉用户。用户点名再 `pouch add`。
+
+## 在项目中使用 skill
+
+已点名则直接安装；没点名或要按仓库判断：读 [onboard.md](references/onboard.md)。

 ```bash
-pouch add --list
 pouch add <name> -a cursor -a claude -a codex -a agents -y
 ```

-`pouch add <name>` 默认安装到当前项目；只有用户明确需要所有项目使用时才加 `-g`。安装结果是指向 `~/.pouch/skills/<name>/` 的软链，不要在 Agent 目录创建副本。
+默认当前项目；只有用户明确需要所有项目使用时才加 `-g`。只建指向
+`~/.pouch/skills/<name>/` 的软链，不要在 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
@@ -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 <URL> ~/.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 <name> -g -y     # 全局，所有项目都能用
+pouch add <name> -y        # 仅当前项目
+```
+
+默认 `pouch add` 装到当前工作目录。cwd 是 pouch 仓库本身时用 `-g`，除非用户就在维护 pouch。
+用户是在自己的应用仓库里请你代装，才做项目级安装。
+
+## 5. 验收
+
+```bash
+pouch status
+pouch doctor
+```
+
+软链异常则 `pouch doctor --fix`。已经装好时只汇报状态，问还要不要加 skill，不要重新 clone。
+
+当前目录是业务仓库（不是 pouch 仓库）时，回到 SKILL.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 <pouch-skill-dir>/scripts/suggest_skills.py
+```
+
+只根据脚本输出建议，不要为了「可能有用」推荐 eli5、note-style、host-sec-check 这类无仓库信号的 skill。
+用户点名的除外。
+
+## 2. 安装
+
+把 `suggested` 和 `already` 都列为应安装的 skill（`already` 表示项目里已有状态，
+软链仍要 `pouch add`，除非已经装上）。用户说「接上该用的」时只装这两类，不要全装 builtin。
+只对 `init` 列问要不要初始化。
+
+默认当前项目：
+
+```bash
+pouch add <name> -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`，只念本次装上的那几行「可以这么说」。
@@ -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())
@@ -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())