72 lines
3.5 KiB
Markdown
72 lines
3.5 KiB
Markdown
# Agent Skills 仓库 ACK 协作协议（项目覆盖层）
|
||
|
||
> 本项目基于 ACK Skill v0.12.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 使用当前 `record-bug` worktree；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`，不提交或推送。
|