feat: rename skills/skiff to pouch and move ACK state under .pouch

Use ~/.pouch, the pouch CLI, and .pouch.yaml as the SSOT container.
Keep the inner skills/ packages, and store ACK project state in
.pouch/ack instead of docs/ack.
This commit is contained in:
2026-08-25 15:20:02 +08:00
parent ee31278947
commit f3cd56b78e
83 changed files with 1265 additions and 1192 deletions
+22 -22
View File
@@ -9,7 +9,7 @@ ACK 是一个显式调用的 Agent Skill,用三种独立角色运行工程协
关键约束是验证者不等于实现者。每个任务最多修复三轮,仍未通过时记录为
`leftover`,然后继续处理其它任务。
项目还可以在同一份 `docs/ack/delivery.yaml` 里声明测试环境部署和版本发布。
项目还可以在同一份 `.pouch/ack/delivery.yaml` 里声明测试环境部署和版本发布。
用户告诉 ACK 这两件事怎么做之后,再说「重新布测试环境」或「发布一个版本」,
ACK 按对应 intent 执行。任务全部验证后仍可按 profile 做常规交付。配置默认关闭,
稳定发布与生产部署始终保留人工批准点。
@@ -19,13 +19,13 @@ ACK 按对应 intent 执行。任务全部验证后仍可按 profile 做常规
全局安装:
```bash
skiff add ack -g
pouch add ack -g
```
或只安装到当前项目:
```bash
skiff add ack
pouch add ack
```
ACK 只在用户显式调用 `/ack``$ack` 时运行。
@@ -33,14 +33,14 @@ ACK 只在用户显式调用 `/ack` 或 `$ack` 时运行。
## 初始化项目
```bash
skiff init ack
skiff init ack --project ~/code/my-app
pouch init ack
pouch init ack --project ~/code/my-app
```
初始化后,项目只保存自己的 ACK 状态:
```text
docs/ack/
.pouch/ack/
├── project.md
├── tasks.yaml
├── knowledge.yaml
@@ -50,7 +50,7 @@ docs/ack/
不会在项目中复制或链接 ACK Skill。通用规范、模板和脚本始终从已安装的 Skill
目录读取。
ACK 从当前命令指定的 `--project-root/docs/ack/` 定位项目状态,不要求在
ACK 从当前命令指定的 `--project-root/.pouch/ack/` 定位项目状态,不要求在
`tasks.yaml` 中持久化 `repoPath``devWorktree`。自动 worker 的实际工作目录由
`--worktree` 指定;默认在 `--project-root` 工作,v0.19 起不再配置 `allowedWorktrees` 白名单。
@@ -68,10 +68,10 @@ skills/ack/
```
`SKILL.md` 是 Agent 的工作流入口。`references/` 是按需读取的稳定规范;
`docs/ack/project.md` 只保存当前项目的命令、路径和权限差异;
`docs/ack/tasks.yaml` 保存当前任务状态;`docs/ack/knowledge.yaml` 保存跨任务复用、
`.pouch/ack/project.md` 只保存当前项目的命令、路径和权限差异;
`.pouch/ack/tasks.yaml` 保存当前任务状态;`.pouch/ack/knowledge.yaml` 保存跨任务复用、
已经独立验证的项目知识护栏。
`docs/ack/delivery.yaml` 是测试环境部署和版本发布的唯一契约,也声明常规构建、
`.pouch/ack/delivery.yaml` 是测试环境部署和版本发布的唯一契约,也声明常规构建、
发布和部署能力;每次执行结果另记在 `tasks.yaml.deliveryRuns`
## 检查项目状态
@@ -79,21 +79,21 @@ skills/ack/
Agent 会从当前 ACK Skill 目录解析校验脚本:
```bash
python3 <ack-skill-dir>/scripts/validate_tasks.py docs/ack/tasks.yaml
python3 <ack-skill-dir>/scripts/validate_knowledge.py docs/ack/knowledge.yaml \
--tasks docs/ack/tasks.yaml
python3 <ack-skill-dir>/scripts/validate_delivery.py docs/ack/delivery.yaml \
--tasks docs/ack/tasks.yaml --project-root <project-root>
python3 <ack-skill-dir>/scripts/validate_tasks.py .pouch/ack/tasks.yaml
python3 <ack-skill-dir>/scripts/validate_knowledge.py .pouch/ack/knowledge.yaml \
--tasks .pouch/ack/tasks.yaml
python3 <ack-skill-dir>/scripts/validate_delivery.py .pouch/ack/delivery.yaml \
--tasks .pouch/ack/tasks.yaml --project-root <project-root>
```
Coordinator 可以按当前任务上下文做确定性推荐:
```bash
python3 <ack-skill-dir>/scripts/select_tasks.py docs/ack/tasks.yaml
python3 <ack-skill-dir>/scripts/select_tasks.py docs/ack/tasks.yaml \
python3 <ack-skill-dir>/scripts/select_tasks.py .pouch/ack/tasks.yaml
python3 <ack-skill-dir>/scripts/select_tasks.py .pouch/ack/tasks.yaml \
--task-id BUG-001
python3 <ack-skill-dir>/scripts/select_knowledge.py docs/ack/knowledge.yaml \
python3 <ack-skill-dir>/scripts/select_knowledge.py .pouch/ack/knowledge.yaml \
--component web --path web/app.py --tag long-running-service --limit 10
```
@@ -110,7 +110,7 @@ run。默认最多 20 条,超过预算时显式失败;Agent 不应回退为
```bash
python3 <ack-skill-dir>/scripts/run_verification.py \
docs/ack/knowledge.yaml check-api-contract --project-root <project-root>
.pouch/ack/knowledge.yaml check-api-contract --project-root <project-root>
```
该入口会在执行前重新校验知识库,只打开一次项目根目录 fd,再从同一个 fd 逐段以
@@ -118,7 +118,7 @@ python3 <ack-skill-dir>/scripts/run_verification.py \
快照,再以结构化 argv 和 `shell=False` 启动。它不接受临时命令或额外参数。
选择器输出的 path/args 只用于审阅,不应由 Agent 自行拼接执行。Runner 只读取
项目内无 symlink 的权威
`docs/ack/knowledge.yaml`,不接受替代知识文件或放宽后的项目根。检查进程的 cwd
`.pouch/ack/knowledge.yaml`,不接受替代知识文件或放宽后的项目根。检查进程的 cwd
`ACK_PROJECT_ROOT` 都固定到该根 fd;后者是只在检查进程存活期间有效的
`/proc/self/fd/...``/dev/fd/...` 路径。原始可读路径另放在
`ACK_PROJECT_ROOT_DISPLAY`,只能用于日志,不能用于资源访问。Runner 还提供
@@ -132,7 +132,7 @@ python3 <ack-skill-dir>/scripts/run_verification.py \
旧项目只有 `project.md``tasks.yaml` 时,不要重跑初始化。由 `/ack` 检查现有
状态,获得用户授权后补一个空的 `knowledge.yaml`;如果任务板尚未声明知识库,
同时只补 `project.knowledgeFile: docs/ack/knowledge.yaml`,再运行跨文件校验。
同时只补 `project.knowledgeFile: .pouch/ack/knowledge.yaml`,再运行跨文件校验。
只有 Coordinator 写 `tasks.yaml``knowledge.yaml`。知识正文不能作为自由 shell
执行;关键约束应继续下沉到测试、lint、CI 或正式规范。ACK 不自动修改项目的
@@ -147,7 +147,7 @@ python3 <ack-skill-dir>/scripts/run_verification.py \
发版方式以后再告诉你。
```
ACK 把它维护成 `docs/ack/delivery.yaml``intents.testEnvironment` /
ACK 把它维护成 `.pouch/ack/delivery.yaml``intents.testEnvironment` /
`intents.release`、entrypoint、artifact、environment 和 profile。首次配置保持
关闭,确认后才启用。之后用户可以说: