# Agent Skills 仓库 ACK 协作协议（项目覆盖层）

> 本项目基于 ACK Skill v0.18.0。通用规范由 `/ack` 从 Skill 自身的
> `references/` 读取；本文件只保存当前仓库差异。

## 项目概览

- 项目：`skills`
- 技术栈：Python 3、Markdown、JSON Schema
- 运行命令：`python3 -m unittest discover -s tests -p 'test_*.py'`
- Base URL：`n/a`
- 任务板：`docs/ack/tasks.yaml`
- 项目知识：`docs/ack/knowledge.yaml`
- 覆盖层文件：`docs/ack/project.md`

## 通用规范（由 ACK Skill 按需读取）

- 开始需求：`references/kickoff.md`
- 角色、权限、状态机与完成定义：`references/roles-and-permissions.md`
- 模型档位与升级规则：`references/model-routing.md`
- 闭环流程与 worktree 对齐：`references/closed-loop.md`
- 验收信号与三轮策略：`references/optimization-method.md`
- 派发 prompt 模板：`references/prompt-templates.md`
- Orca 编排命令：`references/orca-adapter.md`

## Worker 路由

机器可校验的 worker profile、允许 worktree 和 receipt 只以
`docs/ack/tasks.yaml` 为准。本次 Developer 使用当前项目根 `/home/ace/.skills`；Test
必须使用 fresh worker，并在独立临时项目、独立假 CLI 配置目录中完成黑盒演练。

## 路径权限

| 路径 | Coordinator | Test | Developer | 说明 |
|------|:-----------:|:----:|:---------:|------|
| `docs/ack-feishu-bug-intake.md` | R/W | Read-only | Read-only | 本需求规格与验收契约 |
| `docs/ack/` | R/W | Read-only | Read-only | ACK 项目状态，只有 Coordinator 写 |
| `skills/ack/` | Read-only | Read-only | R/W | ACK Skill 实现、模板与通用规范 |
| `tests/test_ack_feishu_intake_unit.py` | Read-only | Read-only | R/W | Developer 白盒测试 |
| `tests/test_ack_feishu_intake_e2e.py` | Read-only | R/W | Read-only | Test 独立黑盒演练与回归测试 |
| 其它 `tests/test_ack*.py` | Read-only | Read-only | Read-only | 既有 ACK 回归测试 |
| 临时测试目录 | Read-only | R/W | R/W | 必须由 `tempfile`/`mktemp -d` 创建，不保存凭据 |
| `~/.lark-cli/` | Read-only | Read-only | Read-only | 不读取、不修改真实飞书 profile；测试只能使用假 CLI |

## 命令

Developer 白盒验证：

```bash
python3 -m unittest discover -s tests -p 'test_ack_feishu_intake_unit.py'
python3 -m unittest tests.test_ack_skill tests.test_ack_tasks_validation
python3 -m compileall -q skills/ack/scripts
```

Test 黑盒复测：

```bash
python3 -m unittest discover -s tests -p 'test_ack_feishu_intake_e2e.py'
python3 -m unittest discover -s tests -p 'test_ack*.py'
python3 skills/ack/scripts/validate_tasks.py docs/ack/tasks.yaml
python3 skills/ack/scripts/validate_knowledge.py docs/ack/knowledge.yaml --tasks docs/ack/tasks.yaml
```

## 本次任务硬规则

- 只支持官方 `lark-cli`，所有读取命令必须显式携带项目配置的 `--profile`，不能依赖当前 active profile。
- 项目只保存 profile 名称、Base/table/view 标识和字段映射；App Secret、token 与用户凭据不得进入仓库、任务板或日志。
- 飞书接入第一版只读，不更新或删除表格记录，不切换 CLI active profile。
- 外部 CLI 缺失、profile 不存在、返回结构异常、附件下载失败时 fail closed，不回退到网页抓取。
- 只有 `ACK Ready` 视图中的记录可进入整理；每条记录保留稳定 `record_id` 来源引用，重复读取不得制造重复 ACK 来源。
- 不修改 `AGENTS.md`、`CLAUDE.md`，不提交或推送。