Compare commits
25 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 laily
|
0954ad542a | ||
|
laily
|
4d078e8258 | ||
|
laily
|
6855ac7078 | ||
|
laily
|
e9b34747cc | ||
|
laily
|
f5bf35c722 | ||
|
laily
|
34bbb97406 | ||
|
laily
|
337f1a9098 | ||
|
laily
|
f02a34e751 | ||
|
laily
|
e7f42e835a | ||
|
laily
|
a0f1c15b85 | ||
|
laily
|
f8d03fad4d | ||
|
laily
|
5b0e41199d | ||
|
laily
|
2c3d91c75c | ||
|
laily
|
f08edb6452 | ||
|
laily
|
d7997091bd | ||
|
laily
|
ae3bce7b5d | ||
|
laily
|
ee66dbe9ce | ||
|
laily
|
7d1994cf93 | ||
|
laily
|
076d87e303 | ||
|
laily
|
e308d6a04c | ||
|
laily
|
e667f58bf1 | ||
|
laily
|
262c138bee | ||
|
laily
|
18ebb70911 | ||
|
laily
|
afbdde157f | ||
|
laily
|
5f90758e22 |
@@ -34,67 +34,61 @@ skiff status
|
||||
```
|
||||
skills/
|
||||
├── _template/ # 新建 skill 的脚手架
|
||||
├── ack/ # 完整 ACK skill，含 references/templates/scripts
|
||||
├── declarative-openspec-loop/ # 自研 skill，必须含 SKILL.md
|
||||
│ ├── SKILL.md
|
||||
│ └── reference.md
|
||||
├── discussion-notes/ # 讨论沉淀笔记
|
||||
│ ├── SKILL.md
|
||||
│ └── reference.md
|
||||
kits/
|
||||
└── agent-collaboration-kit/ # 可复制到项目的协作规范包，不是 skill
|
||||
skiff/ # CLI 源码（Python 3）
|
||||
bin/skiff # CLI 入口
|
||||
registry.yaml # 外部 Git skill 来源目录
|
||||
catalog.yaml # skiff 预置 Skill 来源目录
|
||||
AGENTS.md # 本文档
|
||||
```
|
||||
|
||||
**本仓库包含**：`skills/`、`kits/`、`skiff/`、`bin/skiff`、`registry.yaml`、`AGENTS.md`
|
||||
**本仓库包含**：`skills/`、`skiff/`、`bin/skiff`、`catalog.yaml`、`AGENTS.md`
|
||||
**本仓库不包含**：各项目的 skill 启用清单
|
||||
|
||||
---
|
||||
|
||||
## Skill 目录
|
||||
|
||||
### 自研（Owned）
|
||||
### 内置（Builtin）
|
||||
|
||||
|
||||
| Skill | 说明 |
|
||||
| ---------------------------------------------------------------------- | ------------------------------------------------- |
|
||||
| [skiff](skills/skiff/SKILL.md) | 本项目工作流：创建、使用、反馈与更新 owned skill |
|
||||
| [orc](skills/orc/SKILL.md) | ORC 入口：显式编排开发、版本发布与产物任务，支持 Agent 分档 |
|
||||
| [ack](skills/ack/SKILL.md) | ACK 入口：显式初始化、检查并运行项目三角色协作闭环 |
|
||||
| [skiff](skills/skiff/SKILL.md) | 本项目工作流：创建、使用、反馈与更新 builtin skill |
|
||||
| [declarative-openspec-loop](skills/declarative-openspec-loop/SKILL.md) | 声明式编程循环：用户提供校验方式，Agent 自动 propose/apply/校验并迭代直到通过 |
|
||||
| [discussion-notes](skills/discussion-notes/SKILL.md) | 讨论沉淀：边讨论边维护 Markdown 笔记，无 .raw.md |
|
||||
|
||||
|
||||
新建 skill：复制 `skills/_template/` → `skills/<name>/`，编辑 `SKILL.md`，在本仓库 commit。
|
||||
|
||||
### 规范包（Kits，不是 Skill）
|
||||
Skill 需要的稳定规范、模板、示例和脚本直接放在自己的目录中，例如
|
||||
`skills/ack/references/`、`templates/`、`examples/` 和 `scripts/`。项目初始化只生成
|
||||
项目状态，不复制或链接 Skill 内容：
|
||||
|
||||
`kits/` 放可复制到项目的流程规范、模板、检查清单和示例资料。它们不是 Agent Skill：
|
||||
```bash
|
||||
skiff init ack
|
||||
```
|
||||
|
||||
- 不放 `SKILL.md` frontmatter
|
||||
- 不由 `skiff install` / `skiff add` 安装
|
||||
- 不会被 Agent 自动触发加载
|
||||
- 使用方式是复制到目标项目文档目录，或在目标项目 `AGENTS.md` 中引用
|
||||
### 预置目录（Catalog）
|
||||
|
||||
| Kit | 说明 | 推荐落地位置 |
|
||||
| --- | --- | --- |
|
||||
| [agent-collaboration-kit](kits/agent-collaboration-kit/README.md) | 多 Agent 协作闭环规范包 | `docs/agent-collaboration-kit/` |
|
||||
|
||||
新建规范包：创建 `kits/<name>/README.md`，写清适用场景、复制到项目后的推荐目录、需要项目填充的占位符，并在本仓库 commit。
|
||||
|
||||
### 外部（External Git）
|
||||
|
||||
在 `registry.yaml` 中注册，通过 skiff 拉取安装：
|
||||
在 `catalog.yaml` 中预置，通过 skiff 拉取安装：
|
||||
|
||||
|
||||
| Skill | 来源 |
|
||||
| ----------- | -------------------------------------------------------------------------- |
|
||||
| superpowers | [https://github.com/obra/superpowers](https://github.com/obra/superpowers) |
|
||||
| Source | 来源 |
|
||||
| --- | --- |
|
||||
| waza | [https://github.com/tw93/Waza](https://github.com/tw93/Waza) |
|
||||
|
||||
|
||||
```bash
|
||||
skiff fetch superpowers
|
||||
skiff install-external superpowers
|
||||
skiff fetch waza
|
||||
skiff add waza/think -g
|
||||
```
|
||||
|
||||
### 自定义仓库（Custom Sources）
|
||||
@@ -135,8 +129,8 @@ npx skills find typescript
|
||||
1. **SSOT** — 自研 skill 只存在于 `skills/<name>/`，不在 Agent 目录直接创建
|
||||
2. **项目自治** — 每个项目自己维护 `.skills.yaml`，本仓库不维护项目清单
|
||||
3. **软链优先** — 通过 symlink 映射到 Agent 目录，改 skill 即改 SSOT
|
||||
4. **类型分离** — `skills/` 只放可安装 skill；非 skill 的规范包、模板包放 `kits/`
|
||||
5. **一体维护** — skill、规范包与 CLI 同仓库维护；需要时再与独立 skiff 仓库同步
|
||||
4. **能力内聚** — Skill 使用的规范、模板和脚本与 `SKILL.md` 同目录维护
|
||||
5. **一体维护** — skill 与 CLI 同仓库维护；需要时再与独立 skiff 仓库同步
|
||||
|
||||
---
|
||||
|
||||
@@ -145,9 +139,8 @@ npx skills find typescript
|
||||
```
|
||||
skills 仓库（本仓库） skiff CLI
|
||||
skills/<name>/ ←── skiff install / enable
|
||||
kits/<name>/ ←── 手动复制 / 项目文档引用
|
||||
skiff/ ←── python3 -m skiff
|
||||
registry.yaml ←── skiff add / fetch
|
||||
catalog.yaml ←── skiff add / fetch
|
||||
↑
|
||||
~/.skills（symlink）
|
||||
│
|
||||
@@ -163,8 +156,8 @@ registry.yaml ←── skiff add / fetch
|
||||
|
||||
| 层级 | 位置 | 维护方式 |
|
||||
| ---------------- | ---------------------------------- | ------------------------------- |
|
||||
| **Owned** | `skills/<name>/` | 本仓库 commit |
|
||||
| **External Git** | `~/.local/share/skills/externals/` | `skiff fetch` |
|
||||
| **Builtin** | `skills/<name>/` | 本仓库 commit |
|
||||
| **Catalog** | `catalog.yaml` + checkout 缓存 | `skiff catalog add / fetch` |
|
||||
| **Custom Source** | `~/.local/share/skiff/sources/` 或本地路径 | `skiff source add/fetch` |
|
||||
| **External NPM** | `node_modules/` | `npx skills add` / `skills-npm` |
|
||||
|
||||
@@ -172,7 +165,6 @@ registry.yaml ←── skiff add / fetch
|
||||
|
||||
| 类型 | 位置 | 维护方式 |
|
||||
| --- | --- | --- |
|
||||
| **Kit** | `kits/<name>/` | 本仓库 commit；复制到目标项目 `docs/` 或由项目 `AGENTS.md` 引用 |
|
||||
| **OpenSpec 配置** | `openspec/` | 本仓库 commit；服务于本仓库自身的规格流程 |
|
||||
|
||||
|
||||
@@ -195,10 +187,10 @@ registry.yaml ←── skiff add / fetch
|
||||
```yaml
|
||||
# .skills.yaml（在项目根目录）
|
||||
skills:
|
||||
- declarative-openspec-loop
|
||||
- name: superpowers
|
||||
source: registry
|
||||
ref: main
|
||||
- name: declarative-openspec-loop
|
||||
source: builtin
|
||||
- name: think
|
||||
source: catalog:waza
|
||||
- name: internal-review
|
||||
source: company
|
||||
|
||||
@@ -240,9 +232,9 @@ skiff sync
|
||||
| `skiff bootstrap` | 将 skiff 项目 skill 全局安装到所有 Agent |
|
||||
| `skiff list` | 列出所有 skill |
|
||||
| `skiff status` | 安装状态总览 |
|
||||
| `skiff install <name>` | 全局安装（symlink） |
|
||||
| `skiff uninstall <name>` | 移除 symlink |
|
||||
| `skiff add / fetch / install-external` | 外部 Git skill |
|
||||
| `skiff add <name> [-g]` | 项目或全局安装（symlink） |
|
||||
| `skiff remove <name> [-g]` | 移除 symlink |
|
||||
| `skiff catalog add` / `skiff fetch` | 管理和拉取 catalog source |
|
||||
|
||||
|
||||
### 草稿与健康检查
|
||||
|
||||
@@ -9,7 +9,7 @@ git clone https://git.yumee.top/laily/skills.git ~/.skills
|
||||
cd ~/.skills
|
||||
./install.sh # 安装 CLI，并将 skiff 项目 skill 安装到所有 Agent
|
||||
|
||||
skiff install declarative-openspec-loop
|
||||
skiff add declarative-openspec-loop -g
|
||||
skiff select # 交互式选择并批量安装
|
||||
skiff list
|
||||
skiff status
|
||||
@@ -19,36 +19,38 @@ skiff status
|
||||
|
||||
```
|
||||
skills/ # 自研 skill（SSOT）：每个子目录必须有 SKILL.md
|
||||
kits/ # 可复制到项目的规范包 / 模板包，不是 Agent Skill
|
||||
skiff/ # CLI 源码（Python 3）
|
||||
bin/skiff # CLI 入口
|
||||
registry.yaml # 外部 Git skill 目录
|
||||
catalog.yaml # skiff 预置 Skill 来源目录
|
||||
AGENTS.md # 详细规范与架构说明
|
||||
```
|
||||
|
||||
| 路径 | 说明 |
|
||||
|------|------|
|
||||
| [skills/](skills/) | 自研 skill，每个子目录含 `SKILL.md` |
|
||||
| [kits/](kits/) | 项目规范包、协作模板、可复制资料，不由 skiff 安装 |
|
||||
| [skills/](skills/) | 自研 skill，每个子目录含 `SKILL.md`，可附带 references、templates 和 scripts |
|
||||
| [skiff/](skiff/README.md) | 安装、软链、健康检查 CLI |
|
||||
| [registry.yaml](registry.yaml) | 外部 Git skill 注册表 |
|
||||
| [catalog.yaml](catalog.yaml) | skiff 预置 Skill 来源目录 |
|
||||
| [AGENTS.md](AGENTS.md) | 设计原则、编写规范、架构详解 |
|
||||
|
||||
## 自研 Skill
|
||||
|
||||
| Skill | 说明 |
|
||||
|-------|------|
|
||||
| [skiff](skills/skiff/SKILL.md) | 在项目中创建、安装、反馈和维护 owned skill |
|
||||
| [orc](skills/orc/SKILL.md) | 显式编排开发、版本发布和产物任务，支持 low/mid/high Agent 档位 |
|
||||
| [ack](skills/ack/SKILL.md) | 显式初始化、检查并运行 ACK 三角色协作及可选交付闭环 |
|
||||
| [skiff](skills/skiff/SKILL.md) | 在项目中创建、安装、反馈和维护 builtin skill |
|
||||
| [declarative-openspec-loop](skills/declarative-openspec-loop/SKILL.md) | 声明式编程循环：用户提供校验方式，Agent 自动迭代直到通过 |
|
||||
| [discussion-notes](skills/discussion-notes/SKILL.md) | 讨论沉淀：边讨论边维护 Markdown 笔记 |
|
||||
|
||||
## 规范包（不是 Skill）
|
||||
ACK 是包含规范、模板与校验脚本的完整 Skill。安装 Skill 后可初始化当前项目状态：
|
||||
|
||||
`kits/` 用来维护可复制到项目里的规范说明、模板和检查清单。它们没有 `SKILL.md`，不会被 `skiff install`、`skiff add` 或 Agent 自动加载。
|
||||
```bash
|
||||
skiff init ack
|
||||
skiff init ack --project ~/app
|
||||
```
|
||||
|
||||
| Kit | 说明 |
|
||||
|-----|------|
|
||||
| [agent-collaboration-kit](kits/agent-collaboration-kit/README.md) | 多 Agent 协作闭环规范包，复制到项目 `docs/agent-collaboration-kit/` 后按项目情况填写 |
|
||||
初始化会生成默认关闭的 `docs/ack/delivery.yaml`；项目可用自然语言让 `/ack` 维护
|
||||
DEB、镜像、PR、发布与部署 profile，任务验证通过后再按已确认计划执行。
|
||||
|
||||
新建 skill：
|
||||
|
||||
@@ -67,8 +69,8 @@ skiff add my-skill -g # 全局安装验证
|
||||
### 全局（用户级）
|
||||
|
||||
```bash
|
||||
skiff install <name> # 安装到 ~/.cursor/skills/ 等
|
||||
skiff install <name> --target cursor
|
||||
skiff add <name> -g # 安装到 ~/.cursor/skills/ 等
|
||||
skiff add <name> -g -a cursor
|
||||
```
|
||||
|
||||
### 项目级
|
||||
@@ -77,10 +79,10 @@ skiff install <name> --target cursor
|
||||
|
||||
```yaml
|
||||
skills:
|
||||
- declarative-openspec-loop
|
||||
- name: superpowers
|
||||
source: registry
|
||||
ref: main
|
||||
- name: declarative-openspec-loop
|
||||
source: builtin
|
||||
- name: think
|
||||
source: catalog:waza
|
||||
|
||||
targets: # 可选，默认 all
|
||||
- cursor
|
||||
@@ -89,18 +91,25 @@ targets: # 可选，默认 all
|
||||
```
|
||||
|
||||
```bash
|
||||
skiff enable declarative-openspec-loop
|
||||
skiff add declarative-openspec-loop
|
||||
skiff sync
|
||||
skiff disable declarative-openspec-loop
|
||||
skiff remove declarative-openspec-loop
|
||||
```
|
||||
|
||||
## 外部 Skill
|
||||
## Catalog 与 Custom Source
|
||||
|
||||
**Git 来源**（经 skiff 管理）：
|
||||
安装 catalog 中预置的来源：
|
||||
|
||||
```bash
|
||||
skiff fetch superpowers
|
||||
skiff install-external superpowers
|
||||
skiff fetch waza
|
||||
skiff add waza/think -g
|
||||
```
|
||||
|
||||
接入团队自己的本地目录或 Git 仓库：
|
||||
|
||||
```bash
|
||||
skiff source add company --local ~/code/company-skills --skills-path skills
|
||||
skiff add company/internal-review -g
|
||||
```
|
||||
|
||||
**社区来源**（Vercel CLI）：
|
||||
@@ -115,8 +124,7 @@ npx skills find typescript
|
||||
```
|
||||
本仓库
|
||||
├── skills/<name>/ ←── skiff install / enable
|
||||
├── kits/<name>/ ←── 手动复制 / 项目文档引用
|
||||
├── registry.yaml ←── skiff add / fetch
|
||||
├── catalog.yaml ←── 预置来源发现与 fetch
|
||||
└── skiff/ ←── python3 -m skiff
|
||||
↑
|
||||
~/.skills（symlink）
|
||||
@@ -133,7 +141,7 @@ npx skills find typescript
|
||||
1. **SSOT** — 自研 skill 只存在于 `skills/<name>/`
|
||||
2. **项目自治** — 各项目自行维护 `.skills.yaml`
|
||||
3. **软链优先** — 通过 symlink 映射到 Agent 目录，改 skill 即改 SSOT
|
||||
4. **规范包分离** — 非 skill 的流程规范、模板包放在 `kits/<name>/`，不混入 `skills/`
|
||||
4. **能力内聚** — Skill 所需规范、模板和脚本与 `SKILL.md` 放在同一目录
|
||||
5. **一体维护** — skill 与 CLI 同仓库，Python 3 直接运行，无需编译
|
||||
|
||||
## 文档
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
# External skills registry
|
||||
# Preconfigured Skill source catalog
|
||||
# Format:
|
||||
# <name>:
|
||||
# repo: <git-url>
|
||||
@@ -0,0 +1,752 @@
|
||||
---
|
||||
title: ACK 设计评审记录
|
||||
date: "2026-07-31T17:15:37+08:00"
|
||||
updated: "2026-07-31T23:31:48+08:00"
|
||||
---
|
||||
|
||||
# ACK 设计评审记录
|
||||
|
||||
> 这是对 ACK v0.8.1 的设计评审快照，用于推动后续版本改进。文中的文件行号对应
|
||||
> 2026-07-31 的仓库状态，不作为 ACK 的运行规范。
|
||||
|
||||
本文同时记录后续方案和实施结果。带“建议”“目标”或“待验证”的内容默认是设计
|
||||
方向，不代表当前版本已经具备；实际运行契约仍以 `skills/ack/SKILL.md`、schema、
|
||||
校验器和测试为准。知识护栏方案的 v0.9.0 落地边界、model-routing v0.10.0 的
|
||||
实施结论见下文状态表。
|
||||
|
||||
## 背景
|
||||
|
||||
本轮评审覆盖 `skills/ack/` 的入口、角色规范、闭环流程、项目模板、任务板
|
||||
schema、校验脚本、Orca 适配器，以及 `skiff init ack` 的真实运行路径。
|
||||
|
||||
评审主要回答两个问题：
|
||||
|
||||
- ACK 的三角色协作方向是否合理。
|
||||
- 当前实现是否已经能稳定完成初始化、派发、独立复测、状态恢复和结果审计。
|
||||
|
||||
## 结论
|
||||
|
||||
ACK 的核心方向合理。显式触发、三角色分权、可观测验收、用户确认、Test 独立
|
||||
复测、Coordinator 单写任务板和三轮止损都值得保留。
|
||||
|
||||
当前版本适合描述为“任务级受监督验收闭环”。它可以组织单个工作空间里的实现和
|
||||
复测，但还没有覆盖批准状态持久化、跨 worktree 交接、编排状态恢复、目标分支集成
|
||||
和交付状态，因此暂时不应把 `verified` 等同于“已集成”或“已交付”。
|
||||
|
||||
概念设计约为 8/10，当前可操作性约为 5 至 6/10。下一阶段应该补齐控制面契约，
|
||||
不需要推翻三角色模型。
|
||||
|
||||
## 值得保留的设计
|
||||
|
||||
- Coordinator、Developer 和 Test 的职责分开，Developer 不能给自己的实现做最终
|
||||
判定。
|
||||
- 新需求先写产品文档、任务拆分和可观测验收信号，用户确认后再派发。
|
||||
- `tasks.yaml` 由 Coordinator 单写，worker 消息只负责传递证据。
|
||||
- Test 在复测前核对 worktree、服务实例和构建产物，减少测错代码和旧进程造成的
|
||||
假通过。
|
||||
- 每个任务最多三轮，失败后进入 `leftover`，不会无限消耗同一个 worker。
|
||||
- 通用规范留在 Skill，项目只保存覆盖层与任务状态。
|
||||
- 闭环核心不依赖 Orca，手动模式仍能保留相同的角色与验收逻辑。
|
||||
|
||||
## P0：状态和证据必须先成为可验证协议
|
||||
|
||||
### `verified` 目前可以没有证据
|
||||
|
||||
`roles-and-permissions.md` 定义的完成条件包括 Developer 白盒证据、Test 独立证据、
|
||||
环境对齐和 Coordinator 终检，但任务 schema 只强制 `id`、`title` 和 `status`。
|
||||
内置校验器同样没有检查 `verified` 所需的证据。
|
||||
|
||||
本轮探针确认，下面这种任务可以通过内置校验：
|
||||
|
||||
```yaml
|
||||
version: 1
|
||||
project:
|
||||
name: demo
|
||||
tasks:
|
||||
- id: T-1
|
||||
title: hollow green
|
||||
status: verified
|
||||
```
|
||||
|
||||
相关位置：
|
||||
|
||||
- `skills/ack/templates/tasks.schema.json:76`
|
||||
- `skills/ack/scripts/validate_tasks.py:70`
|
||||
- `skills/ack/references/roles-and-permissions.md:140`
|
||||
|
||||
建议为不同状态定义语义约束。`verified` 至少要求：
|
||||
|
||||
- Developer 的修改文件、验证命令和结果。
|
||||
- 独立 Test 的身份、逐条验收结果和原始证据。
|
||||
- 被测代码或构建产物的不可变指纹。
|
||||
- worktree、服务进程、Base URL 和测试时间。
|
||||
- Coordinator 的 gate 结果与写入时间。
|
||||
|
||||
### 用户确认没有持久化
|
||||
|
||||
Skill 要求用户确认后再派发，但状态机从 `open` 直接进入 `dispatched`。会话在确认前
|
||||
中断后，新的 Coordinator 无法知道任务是待确认，还是已经批准。
|
||||
|
||||
建议增加 `proposed` 和 `approved`，并记录 `approvedAt`、`approvedBy` 与验收版本。
|
||||
|
||||
### 推荐状态流
|
||||
|
||||
```text
|
||||
proposed
|
||||
-> approved
|
||||
-> implementing
|
||||
-> retesting
|
||||
-> verified_in_workspace
|
||||
-> integrated
|
||||
-> verified
|
||||
|
||||
blocked
|
||||
-> approved
|
||||
-> cancelled
|
||||
|
||||
product_failed x 3
|
||||
-> leftover
|
||||
```
|
||||
|
||||
`verified_in_workspace` 只说明指定工作空间中的代码已经通过独立复测。只有目标分支
|
||||
集成并完成集成后验证，才能进入最终 `verified`。
|
||||
|
||||
## P0：Orca 适配器需要改成双任务模型
|
||||
|
||||
当前文档让 Developer 对一个 Orca task 发送 `worker_done`，然后把同一个 task 再次
|
||||
派给 Test。截至评审日期，当前 Orca 的 orchestration 规则会在收到有效
|
||||
`worker_done` 后自动把 task 和 dispatch 标记为 completed。第二次派发同一个 task
|
||||
缺少可靠的生命周期语义。
|
||||
|
||||
相关位置：
|
||||
|
||||
- `skills/ack/references/orca-adapter.md:144`
|
||||
- `skills/ack/references/orca-adapter.md:164`
|
||||
- `skills/ack/references/orca-adapter.md:199`
|
||||
|
||||
建议每个 ACK attempt 创建两个 Orca 子任务：
|
||||
|
||||
```text
|
||||
ACK task
|
||||
Developer task
|
||||
Test task, depends on Developer task
|
||||
```
|
||||
|
||||
任务板分别保存：
|
||||
|
||||
```yaml
|
||||
devTaskId: null
|
||||
devDispatchId: null
|
||||
testTaskId: null
|
||||
testDispatchId: null
|
||||
```
|
||||
|
||||
Developer 和 Test 都对自己的 dispatch 发送 `worker_done`，Coordinator 最后只读
|
||||
证据并执行 gate。
|
||||
|
||||
## P0：明确 worktree 和代码交接方式
|
||||
|
||||
当前流程先在 Coordinator worktree 写 PRD 和 `tasks.yaml`，随后才决定是否创建隔离
|
||||
worktree。权威任务板只保留在 Coordinator worktree，但 worker prompt 又要求在自己
|
||||
的 worktree 读取相对路径。Developer 的未提交代码如何传给独立的 Test worktree
|
||||
也没有定义。
|
||||
|
||||
相关位置：
|
||||
|
||||
- `skills/ack/references/kickoff.md:30`
|
||||
- `skills/ack/references/closed-loop.md:65`
|
||||
- `skills/ack/references/closed-loop.md:87`
|
||||
- `skills/ack/references/prompt-templates.md:31`
|
||||
- `skills/ack/references/orca-adapter.md:74`
|
||||
|
||||
建议默认让 Developer 和 Test 串行使用同一个 worktree。必须隔离时，在 attempt 中
|
||||
明确：
|
||||
|
||||
```yaml
|
||||
transfer:
|
||||
type: commit | patch | artifact
|
||||
source: "<immutable reference>"
|
||||
digest: "<sha256 or diff hash>"
|
||||
```
|
||||
|
||||
派发内容应携带验收快照和规范的绝对路径，不能假设每个 worktree 都有同一份未提交
|
||||
文档。
|
||||
|
||||
## P0：Worker 启动策略改为安全默认
|
||||
|
||||
> v0.10 已以结构化 profile 和可信 launcher 取代本节描述的自由 command。下方是
|
||||
> 当时的评审记录，不再代表当前实现；其中“full-access 写入任务板授权”的建议已被
|
||||
> v0.10 决策取代，当前明确为 Deferred。
|
||||
|
||||
当前校验器强制 Codex 使用 bypass、Cursor 使用 YOLO，并写死模型和 CLI。项目文档
|
||||
允许收紧权限或替换模型，但合法的安全覆盖会被校验器拒绝。
|
||||
|
||||
校验器还只检查自由 shell 字符串里的部分 token。本轮探针确认，带有 shell 控制符
|
||||
和额外命令的字符串仍可通过校验。这样的结果会给调用方错误的安全感。
|
||||
|
||||
相关位置：
|
||||
|
||||
- `skills/ack/scripts/validate_worker_command.py:49`
|
||||
- `skills/ack/references/model-routing.md:98`
|
||||
- `skills/ack/templates/project.template.md:31`
|
||||
|
||||
建议把项目覆盖层改成结构化配置：
|
||||
|
||||
```yaml
|
||||
orchestration:
|
||||
mode: orca
|
||||
|
||||
workers:
|
||||
developer:
|
||||
cli: codex
|
||||
model: "<project-approved-model>"
|
||||
effort: medium
|
||||
permissionMode: sandbox
|
||||
test:
|
||||
cli: codex
|
||||
model: "<project-approved-model>"
|
||||
effort: low
|
||||
permissionMode: sandbox
|
||||
```
|
||||
|
||||
可信代码根据这些字段构造 argv，不接受自由 shell 拼接。安全模式默认通过。
|
||||
原建议设想 full-access 由用户单独授权并写入任务板；v0.10 没有实现这条授权通道，
|
||||
项目文件也不能充当授权证据。full-access 的可信授权、期限、撤销和外层隔离均为
|
||||
Deferred，当前 launcher 必须 fail closed。
|
||||
|
||||
## P0：初始化需要原子化
|
||||
|
||||
`skiff init ack` 会先写 `project.md` 和 `tasks.yaml`，再运行任务板校验。缺少 PyYAML
|
||||
时，命令会失败但保留两个文件。再次运行又会因为拒绝覆盖而失败。
|
||||
|
||||
相关位置：
|
||||
|
||||
- `requirements.txt:1`
|
||||
- `skills/ack/scripts/validate_tasks.py:37`
|
||||
- `skiff/cli.py:1144`
|
||||
- `skiff/cli.py:1156`
|
||||
|
||||
本轮在不含第三方包的隔离 Python 环境中复现了这个状态。
|
||||
|
||||
建议：
|
||||
|
||||
- 在临时目录渲染和校验，全部通过后再原子 rename。
|
||||
- 失败时只清理由本次调用创建的临时文件。
|
||||
- 提供 `skiff init ack --repair` 或等价恢复路径。
|
||||
- 默认模板使用 `tasks: []`，完整示例继续放在 `examples/`。
|
||||
- CLI 输出“脚手架已创建，待配置”，检查通过后再称为“初始化完成”。
|
||||
|
||||
## P1：任务板改成追加式 attempts
|
||||
|
||||
当前 `dispatch.rounds` 只记录轮次、结果和一段证据，无法支持恢复、并发和审计。
|
||||
建议改成追加式 `attempts[]`：
|
||||
|
||||
```yaml
|
||||
attempts:
|
||||
- id: "T-1-A1"
|
||||
round: 1
|
||||
idempotencyKey: "<stable key>"
|
||||
startedAt: "<timestamp>"
|
||||
workspace:
|
||||
path: "<worktree>"
|
||||
baseCommit: "<sha>"
|
||||
diffHash: "<hash>"
|
||||
developer:
|
||||
worker: "<identity>"
|
||||
taskId: "<runtime task id>"
|
||||
dispatchId: "<runtime dispatch id>"
|
||||
evidence: {}
|
||||
test:
|
||||
worker: "<independent identity>"
|
||||
taskId: "<runtime task id>"
|
||||
dispatchId: "<runtime dispatch id>"
|
||||
evidence: {}
|
||||
gate:
|
||||
result: pending | passed | failed
|
||||
failureKind: null
|
||||
```
|
||||
|
||||
`failureKind` 建议区分：
|
||||
|
||||
- `product_failed`：实现不满足验收，消耗三轮预算。
|
||||
- `environment_blocked`：环境或服务不可用，不消耗轮次。
|
||||
- `needs_decision`：需要用户决定范围，不消耗轮次。
|
||||
- `acceptance_invalid`：验收标准有误，返回 `proposed`。
|
||||
- `worker_lost`：worker 消失，由 Coordinator 重新派发。
|
||||
|
||||
外部 dispatch 前先持久化 intent。Coordinator 重启后，用 `idempotencyKey` 和 runtime
|
||||
ID 查询 Orca，再决定继续等待、恢复状态或重新派发。
|
||||
|
||||
## P1：统一 schema 和语义校验
|
||||
|
||||
安装 `jsonschema` 时，`validate_tasks.py` 只运行 schema；未安装时只运行内置规则。
|
||||
两条路径的约束不同。schema 会放过重复 ID、四轮 dispatch 和空
|
||||
`leftoverReason`，内置规则也会放过部分错误结构。
|
||||
|
||||
建议：
|
||||
|
||||
- 始终先执行 schema，再无条件执行语义 invariant。
|
||||
- 为 `structural` 和 `ready` 提供两个显式模式。
|
||||
- `ready` 模式检查状态对应的证据、环境、批准和轮次。
|
||||
- 显式传入的 schema 路径不存在时直接失败，不能静默降级。
|
||||
- `summary` 从 `tasks` 派生，避免双写。
|
||||
- 收紧 `additionalProperties`，扩展字段统一放入 `extensions`。
|
||||
|
||||
## P1：补齐完成边界和批次验证
|
||||
|
||||
ACK 默认不提交、不推送。隔离 worktree 中的任务即使复测通过，也可能尚未进入目标
|
||||
分支。最终报告需要明确区分：
|
||||
|
||||
- 已在指定工作空间验证。
|
||||
- 已集成到目标分支。
|
||||
- 已完成集成后回归。
|
||||
- 已提交、已推送或已发布。
|
||||
|
||||
多个任务分别通过后，还需要一次批次级集成回归，避免组合后出现冲突或行为变化。
|
||||
|
||||
## P2：减少规范重复和模型漂移
|
||||
|
||||
- 保留一份权威状态机、一份角色权限表和一份模型档位规则。
|
||||
- `kickoff.md` 只做一页运行手册，adapter 只保存工具命令。
|
||||
- 具体模型名称放到可更新的映射或项目覆盖层，稳定核心只描述能力档位和升级条件。
|
||||
- `ackVersion` 不能只记录旧版本。需要独立的 `schemaVersion`、兼容范围和迁移命令。
|
||||
- 用真实运行数据观察首轮通过率、环境失败率、平均轮次、`leftover` 原因、耗时和
|
||||
token，再决定三轮规则是否需要按任务风险调整。
|
||||
- 为低风险文档或机械改动提供轻量模式，高风险和用户可见行为继续使用完整三角色
|
||||
闭环。
|
||||
|
||||
## 低成本清理
|
||||
|
||||
- `skills/ack/SKILL.md:66` 的旧字段应为 `kitVersion`。
|
||||
- `skills/ack/templates/project.template.md:8` 建议修改或替换 `AGENTS.md`，与 Skill
|
||||
的禁止规则冲突。
|
||||
- `skills/ack/references/orca-adapter.md:201` 应引用 prompt §4。
|
||||
- `skills/ack/scripts/validate_worker_command.py:2` 残留 “Music Pilot”。
|
||||
- `skills/ack/examples/tasks.example.yaml` 缺少 checklist 要求的 `overlayFile`。
|
||||
- Test 负责黑盒与集成测试，Developer 负责单元测试；当前优化文档对单元测试所有权
|
||||
的表述需要统一。
|
||||
|
||||
## 建议实施顺序
|
||||
|
||||
1. 收紧任务状态、批准状态和 `verified` 证据门。
|
||||
2. 把 Orca adapter 改成每轮 Developer/Test 双任务。
|
||||
3. 定义同 worktree 默认策略和跨 worktree transfer。
|
||||
4. 改造 worker launcher 与安全授权。
|
||||
5. 原子化 `skiff init ack`，空任务板作为默认模板。
|
||||
6. 引入追加式 attempts、幂等恢复和失败分类。
|
||||
7. 统一 schema 与语义校验，补齐对抗性 fixture。
|
||||
8. 区分工作空间验证、集成验证和发布状态。
|
||||
9. 去重文档，补版本迁移和运行指标。
|
||||
|
||||
## 验证记录
|
||||
|
||||
本轮执行了：
|
||||
|
||||
- `skiff check ack`：通过。这个命令只证明 Skill 的元数据和基础结构有效。
|
||||
- `validate_tasks.py examples/tasks.example.yaml`：通过，当前机器使用内置规则。
|
||||
- `validate_worker_command.py --self-test`：7 项通过。
|
||||
- `python3 -m unittest discover -s tests -v`：58 项通过。
|
||||
- 隔离全局安装 smoke：通过，安装结果为指向 ACK SSOT 的 symlink。
|
||||
- 隔离初始化探针：缺少 PyYAML 时失败，留下半初始化文件，重试被拒绝。
|
||||
- 对抗性任务板探针：无证据的 `verified` 可以通过。
|
||||
- 对抗性 worker 命令探针：附加 shell 控制符的命令字符串可以通过。
|
||||
- 当前 Orca orchestration 指南复核：有效 `worker_done` 会自动完成对应 task 和
|
||||
dispatch。
|
||||
|
||||
现有 ACK 测试主要覆盖字符串、Skill 元数据和初始化冒烟，没有覆盖状态机语义、
|
||||
schema 与 fallback 一致性、Orca 双阶段生命周期、Coordinator 崩溃恢复和跨 worktree
|
||||
代码交接。
|
||||
|
||||
## 待验证
|
||||
|
||||
- [ ] 用真实项目跑一轮同 worktree 的 Developer/Test 闭环。
|
||||
- [ ] 用独立 worktree 验证 commit、patch 和 artifact 三种交接方式。
|
||||
- [ ] 验证 Coordinator 在 task-create、dispatch 和 Test 完成三个时间点崩溃后的
|
||||
恢复行为。
|
||||
- [ ] 为安全 worker profile、路径 containment 和 shell 注入增加对抗性测试。
|
||||
- [ ] 定义 ACK v0.9 的 schema 迁移策略，再决定是否保留旧状态名称。
|
||||
|
||||
## 扩展方案：项目知识护栏库
|
||||
|
||||
### v0.9.0 落地边界
|
||||
|
||||
| 能力 | v0.9.0 状态 |
|
||||
|------|-------------|
|
||||
| `knowledge.yaml` 模板、schema、初始化和跨文件校验 | 已实现 |
|
||||
| active/stale/superseded/archived、作用域、冲突、复查时间和来源校验 | 已实现 |
|
||||
| 确定性选择、全项目规则优先、固定 revision 引用 | 已实现 |
|
||||
| registry ID + 结构化 argv + fd 固定根目录的安全检查入口 | 已实现 |
|
||||
| Developer candidate、Test check、Coordinator 单写的协作约定 | 已实现为协议和校验字段 |
|
||||
| 不同 revision 的历史内容不可篡改或可独立恢复 | 延后；v0.9.0 没有外部不可变账本 |
|
||||
| 依赖或路径变化后自动转 stale | 延后；当前由 `reviewAfter` 和人工复核驱动 |
|
||||
| 在运行时强制只有获授权身份能写入或激活知识 | 延后；当前依赖 Coordinator 单写边界 |
|
||||
| 自动识别任意提示注入、PII 或所有秘密 | 延后；当前只有结构禁区和常见秘密模式 |
|
||||
| `approved`、追加式 attempts、崩溃恢复和最终集成 gate | 延后到控制面改造 |
|
||||
|
||||
### 定位
|
||||
|
||||
ACK 需要增加第三类项目事实，用来保存跨任务复用、会改变后续开发或验证行为的已
|
||||
验证知识。它不保存聊天记忆，也不承担项目 Wiki 的职责。
|
||||
|
||||
| 项目事实 | 保存内容 | 写入者 |
|
||||
|----------|----------|--------|
|
||||
| `project.md` | 相对稳定的项目配置、路径和命令 | Coordinator 或项目维护者 |
|
||||
| `tasks.yaml` | 当前任务状态、attempt 和执行证据 | Coordinator |
|
||||
| `knowledge.yaml` | 跨任务复用的已验证经验 | Coordinator |
|
||||
|
||||
建议新增项目级 SSOT：`docs/ack/knowledge.yaml`。知识归项目所有，与 Orca 等编排
|
||||
工具无关；ACK 负责在任务闭环中生产、选择和消费这些知识。
|
||||
|
||||
这项设计会修改当前“`docs/ack/` 只保存 `project.md` 与 `tasks.yaml`”的边界。
|
||||
新增文件保存项目事实，不复制 ACK Skill 的通用规范，因此不违反 Skill 内容仍以
|
||||
`skills/ack/` 为 SSOT 的原则。
|
||||
|
||||
### 知识类型
|
||||
|
||||
第一版只支持三类知识：
|
||||
|
||||
| 类型 | 含义 | 例子 |
|
||||
|------|------|------|
|
||||
| `guardrail` | 必须执行或明确禁止的项目约束 | 修改数据库迁移时必须验证回滚 |
|
||||
| `pitfall` | 已证实的失败模式、触发条件和避免方法 | Test 连到了另一个 worktree 的旧服务 |
|
||||
| `verification` | 特定条件下必须增加的检查 | 修改缓存键后执行跨版本兼容测试 |
|
||||
|
||||
架构决策正文继续写入 ADR 或正式规格，知识项只引用决策及其适用条件。任务进度和
|
||||
单次失败证据继续留在 `tasks.yaml`。通用且可跨项目复用的规则应回流 ACK Skill，
|
||||
不能作为某个项目的知识长期保存。
|
||||
|
||||
### 生命周期
|
||||
|
||||
```text
|
||||
Developer / Test 发现经验
|
||||
-> candidate
|
||||
-> Test 独立验证 + Coordinator gate
|
||||
-> active
|
||||
-> stale
|
||||
-> superseded | archived
|
||||
```
|
||||
|
||||
- Developer 和 Test 只能提交 candidate，不能直接写入或激活知识。
|
||||
- candidate 保存在当前 task 或 attempt 的证据中，不参与后续任务的自动选择。
|
||||
- 根因得到证实、修复通过独立 Test、Coordinator 完成 gate 后，candidate 才能转为
|
||||
`active`。
|
||||
- 全项目范围的 `must`、`never` 或权限类规则需要 User 或 Decision Owner 确认。
|
||||
- 依赖、配置、路径或适用版本发生变化后，相关知识转为 `stale`，默认不再派发。
|
||||
- 新知识替代旧知识时必须记录 `supersedes`，不能静默改写历史。
|
||||
- 临时 workaround 必须有复查时间和移除条件，不能无限期保持 `active`。
|
||||
|
||||
同一 Agent 不能把自己读到的旧知识直接作为新证据再次激活。新的 candidate 必须
|
||||
包含当前任务产生的独立观测，避免形成自我强化的错误闭环。
|
||||
|
||||
### 最小数据结构
|
||||
|
||||
每条知识至少包含：
|
||||
|
||||
```yaml
|
||||
id: K-001
|
||||
revision: 1
|
||||
kind: pitfall
|
||||
status: active
|
||||
title: "复测前确认服务来自当前 worktree"
|
||||
|
||||
scope:
|
||||
components: [web]
|
||||
paths: ["web/**"]
|
||||
dependencies: []
|
||||
versions: []
|
||||
tags: [long-running-service]
|
||||
|
||||
appliesWhen: "修改常驻 Web 服务或前端构建产物"
|
||||
directive: "复测前重启服务，并核对服务实例对应的 commit"
|
||||
rationale: "曾因复测旧进程产生假通过"
|
||||
|
||||
verification:
|
||||
ref: service-worktree-alignment
|
||||
expected: "服务实例、worktree 和 commit 一致"
|
||||
|
||||
provenance:
|
||||
taskId: BUG-017
|
||||
attemptId: BUG-017-A2
|
||||
codeRef: "<commit or tree hash>"
|
||||
evidenceRef: "tasks.yaml#BUG-017"
|
||||
|
||||
owner: "<owner>"
|
||||
author: "<candidate author>"
|
||||
reviewer: "<independent reviewer>"
|
||||
createdAt: "<timestamp>"
|
||||
lastValidatedAt: "<timestamp>"
|
||||
reviewAfter: "<timestamp or null>"
|
||||
removalCondition: null
|
||||
supersedes: []
|
||||
conflictsWith: []
|
||||
```
|
||||
|
||||
`revision` 是逻辑版本标识。修改知识的约束含义时必须新增 revision，并保留被引用
|
||||
的旧条目；任务引用 `K-001@1` 后，可以说明当时选择的逻辑版本。v0.9.0 尚未用
|
||||
content hash、签名或外部账本封存条目内容，因此不能只凭这个字符串证明历史字节
|
||||
不可变；项目需要把状态纳入版本控制，强不可变审计留待后续实现。
|
||||
|
||||
`directive` 只能描述应采取的动作。需要执行命令时，`verification.ref` 应引用项目中
|
||||
已审查的测试或检查 ID，由可信配置解析成结构化 argv。知识库不保存可自动执行的
|
||||
自由 shell 命令。
|
||||
|
||||
### 与三角色闭环的集成
|
||||
|
||||
| 角色 | 权限和职责 |
|
||||
|------|------------|
|
||||
| Coordinator | 单写 `knowledge.yaml`；选择本轮适用知识；激活、废弃和处理冲突 |
|
||||
| Developer | 只读本轮知识；回报遵守情况；提交 `knowledgeCandidates` |
|
||||
| Test | 只读本轮知识；执行额外检查；独立验证 candidate |
|
||||
| User / Decision Owner | 批准全项目强制规则、权限规则和无法通过测试证明的政策 |
|
||||
|
||||
`prepare(task)` 时，Coordinator 按 component、path、dependency、version、tag 和失败
|
||||
特征筛选 `active` 知识。匹配结果只作为候选，Coordinator 确认后把固定版本引用
|
||||
写入本轮上下文：
|
||||
|
||||
```yaml
|
||||
knowledgeRefs:
|
||||
- K-001@1
|
||||
- K-014@2
|
||||
```
|
||||
|
||||
引入前文建议的追加式 `attempts[]` 后，引用和回报建议放在：
|
||||
|
||||
```text
|
||||
attempts[].context.knowledgeRefs
|
||||
attempts[].developer.knowledgeApplied
|
||||
attempts[].developer.knowledgeCandidates
|
||||
attempts[].test.knowledgeChecks
|
||||
```
|
||||
|
||||
派发时把已引用知识的必要内容内联到 Developer 和 Test 的 prompt，避免 worker 因
|
||||
worktree 不同而读不到 Coordinator worktree 中未提交的知识文件。每次只派发当前
|
||||
任务命中的少量条目，不全量注入知识库。
|
||||
|
||||
Developer 回报实际遵守了哪些知识，以及新发现的 candidate。Test 对每条适用的
|
||||
`verification` 回报 pass、fail 和证据。要求执行的知识检查没有覆盖时，
|
||||
Coordinator 不得把任务写成 `verified_in_workspace` 或 `verified`。
|
||||
|
||||
### 检索和冲突规则
|
||||
|
||||
第一版使用确定性匹配，不引入向量数据库、Embedding 或语义 RAG：
|
||||
|
||||
- 先按 path、component、dependency、version 和 tag 选择条目。
|
||||
- 失败排查时可以额外匹配错误签名和相关 symbol。
|
||||
- 只返回 `active` 且适用条件成立的条目。
|
||||
- 设置条目数和上下文预算，详情按需读取。`scope.all=true` 的全项目规则优先占用
|
||||
预算；全项目规则本身超过预算时显式失败，不能静默丢弃。
|
||||
- `stale`、`superseded` 和 `archived` 默认不返回。
|
||||
- 没有匹配结果只表示本轮没有找到知识，不能据此声称项目没有相关约束。
|
||||
|
||||
同一 subject 和 scope 不能存在互相矛盾的 `active` 条目。校验器发现冲突时应阻止
|
||||
进入 ready 状态，由 Coordinator 或 Decision Owner 选择保留项并记录
|
||||
`supersedes`。运行时不能使用“最后写入者获胜”解决冲突。
|
||||
|
||||
自动匹配只负责推荐。Coordinator 写入当前 attempt 的显式 `knowledgeRefs` 才是
|
||||
本轮权威上下文。这个边界可以降低作用域标注不准造成的漏选和误选。
|
||||
|
||||
### 知识晋升后的去向
|
||||
|
||||
知识库不是所有经验的最终归宿。不同内容应继续进入对应的权威载体：
|
||||
|
||||
| 内容 | 最终位置 |
|
||||
|------|----------|
|
||||
| 当前任务状态和单次验证证据 | `tasks.yaml` |
|
||||
| 稳定项目路径、命令和运行配置 | `project.md` |
|
||||
| 架构或产品决策及其取舍 | ADR 或正式规格 |
|
||||
| 安全、正确性和兼容性约束 | 测试、lint、CI 或正式规范 |
|
||||
| 原始日志、截图和构建产物 | 受控 artifact 存储 |
|
||||
| 跨项目通用规则 | ACK Skill |
|
||||
| 项目特有且跨任务复用的经验 | `knowledge.yaml` |
|
||||
|
||||
关键 `verification` 应逐步转成可执行测试或 CI gate。知识项继续保存触发条件、原因
|
||||
和证据引用，不能用自然语言规则替代可执行控制。
|
||||
|
||||
### 禁止写入的内容
|
||||
|
||||
- Token、密钥、Cookie、含凭据 URL、生产数据、PII、客户内容和未脱敏日志。
|
||||
- 系统提示、开发者提示、角色或权限覆盖，以及绕过审批、测试和安全限制的指令。
|
||||
- 可自动执行的破坏性命令或生产命令。
|
||||
- 原始聊天、整段 issue 或网页内容、巨量日志、截图和构建产物。
|
||||
- 未复现猜测、LLM 单方推断、一次性巧合和个人评价。
|
||||
- PID、临时端口、个人 worktree 绝对路径等短命机器状态。
|
||||
- 对代码、配置和正式文档的重复抄写。
|
||||
- 没有作用域、证据和失效条件的 `always`、`never` 或 workaround。
|
||||
- 需要权限隔离的漏洞 PoC、敏感内部拓扑和安全调查材料。
|
||||
|
||||
issue、日志和外部网页只能作为不可信 evidence。进入知识库前必须提炼为可审查的
|
||||
项目结论，不能原样晋升，也不能获得高于用户指令、批准规格、当前代码、配置和测试
|
||||
的优先级。
|
||||
|
||||
### 第一版范围
|
||||
|
||||
第一版只实现一个 `docs/ack/knowledge.yaml`，不拆目录。活跃条目达到几十条、单文件
|
||||
开始影响审阅和选择时，再平滑迁移为 `docs/ack/knowledge/index.yaml` 加独立知识卡，
|
||||
条目 schema 和引用格式保持不变。
|
||||
|
||||
第一版包括：
|
||||
|
||||
1. `knowledge.yaml` schema 与语义校验。
|
||||
2. task 或 attempt 的 `knowledgeRefs`。
|
||||
3. Developer 的 `knowledgeApplied` 与 `knowledgeCandidates`。
|
||||
4. Test 的 `knowledgeChecks`。
|
||||
5. Coordinator 在 prepare、gate 和任务收尾三个节点处理知识。
|
||||
6. 基于 scope 的确定性匹配。
|
||||
7. stale、冲突、revision 和 supersedes 校验。
|
||||
|
||||
第一版不包括：
|
||||
|
||||
- 自动抓取或总结全部对话。
|
||||
- Agent 自动激活、删除或提交知识。
|
||||
- 向量数据库、Embedding 和语义 RAG。
|
||||
- 自动改写 `AGENTS.md`、`CLAUDE.md` 或其它 Agent 指令文件。
|
||||
- 从知识正文直接执行 shell 命令。
|
||||
- 组织级、跨仓库知识同步。
|
||||
|
||||
### 目标验收与当前状态
|
||||
|
||||
| 目标 | v0.9.0 状态 |
|
||||
|------|-------------|
|
||||
| candidate 不会作为 active 派发 | 已实现 |
|
||||
| 未授权 worker 不能激活、废弃或删除知识 | 协议约束；运行时身份授权延后 |
|
||||
| path、component、version 只返回匹配条目 | 已实现确定性匹配；准确率仍取决于 scope 标注 |
|
||||
| 非 active 条目默认不返回 | 已实现 |
|
||||
| 冲突 active 规则被拒绝 | 已实现显式冲突和相同 subject/scope 检查 |
|
||||
| 历史 attempt 的知识内容不可变 | 延后；当前只有 revision 约定，没有不可变账本 |
|
||||
| `verification.ref` 无法解析时校验失败 | 已实现 |
|
||||
| evidence 中的提示注入不会变成命令 | 部分实现；禁止自由执行字段，语义晋升仍需人工 gate |
|
||||
| 秘密和生产数据不能进入知识库 | 部分实现；常见秘密模式会阻断，不能替代完整 DLP |
|
||||
| 依赖、路径变化后自动转 stale | 延后；当前依赖复查日期和 Coordinator |
|
||||
| 增长后仍在预算内且不漏全项目规则 | 已实现；全项目规则超预算时显式失败 |
|
||||
|
||||
### 与 ACK 改造顺序的关系
|
||||
|
||||
知识护栏库最终仍依赖可信的任务状态、attempt、证据来源和 ready 校验。v0.9.0 先
|
||||
落地存储、选择和基础 gate，不能据此声称前述控制面问题已经解决。后续应继续：
|
||||
|
||||
1. 确定知识 schema、生命周期和角色权限。
|
||||
2. 在 attempt 中固定 `knowledgeRefs` 和 candidate 证据。
|
||||
3. 接入 Coordinator 的匹配、派发和晋升流程。
|
||||
4. 增加 stale、冲突、权限、注入和敏感信息的对抗性 fixture。
|
||||
5. 选一个真实项目试运行，再根据活跃条目数量决定是否拆分存储。
|
||||
|
||||
这套方案最依赖 scope 标注的质量。项目知识如果很难用组件、路径、依赖、版本或
|
||||
触发条件限定，自动匹配会漏掉关键项或产生大量噪声。这类知识应继续由人维护在 ADR
|
||||
或项目文档中，不能强行进入自动派发流程。
|
||||
|
||||
## v0.10.0 实施结论：结构化 model-routing
|
||||
|
||||
### 当前决策
|
||||
|
||||
旧的 `validate_worker_command.py --command '<shell>'` 只能检查少量 token，无法证明
|
||||
整段 shell 没有追加命令、重复参数、环境注入或 cwd 漂移。v0.10 删除这条自由命令
|
||||
配置面：旧脚本只保留 fail-closed 迁移提示；自动 worker 的唯一入口是
|
||||
`launch_worker.py profile-hash|plan|launch`。
|
||||
|
||||
机器 SSOT 固定为 `tasks.yaml.project.orchestration`。profile 只声明 role、CLI、
|
||||
tier、model、reasoning effort 和 permission mode；model 必须命中按
|
||||
CLI/role/tier 分组的 allowlist。自动权限只允许 `read-only` 与
|
||||
`workspace-write`，full-access、Codex bypass、Cursor YOLO/force 和关闭 sandbox
|
||||
全部 fail closed。
|
||||
|
||||
### 已落地约束
|
||||
|
||||
| 控制面 | v0.10.0 实现 |
|
||||
|--------|--------------|
|
||||
| 自由 command / extra argv / env / cwd | schema 与语义校验拒绝；旧 validator fail closed |
|
||||
| Agent argv | 由 `worker_profiles.py` 按 profile 生成唯一 argv；子进程 `shell=False` |
|
||||
| plan → launch 漂移 | `launch` 强制接收刚审阅的 `--expected-launch-fingerprint`，slot 也纳入 hash |
|
||||
| PATH / loader / 凭据串用 | 不按调用者 PATH 找可执行文件；固定可信目录；控制进程无供应商凭据，worker 使用 `per-cli-allowlist-v1` |
|
||||
| worktree 冒充 | 绝对规范路径、无 symlink、同 Git common-dir，并命中 `git worktree list -z` |
|
||||
| Orca command 注入 | `--command` 只含固定 bootstrap 和随机 launch ID |
|
||||
| bootstrap 抢跑 | 先绑定 runtime/handle/incarnation/worktree，再用 terminal stdin nonce/proof 授权 |
|
||||
| cleanup / bootstrap 竞态 | Popen 前在同一 record lock 内复核 awaiting 状态；cleanup 先发生则拒绝启动 Agent |
|
||||
| create 部分失败 | 取得确定 handle 前的超时、transport/解码异常、中断、非零、畸形/缺字段响应均记为 indeterminate，禁止自动重试 |
|
||||
| handle 后失败清理 | record 写失败不阻断 close；只有 `terminal close --tab --json` 完整匹配且最终 failed 状态可靠落盘才记普通失败，否则保持 indeterminate/reconcile-required |
|
||||
| receipt 漂移 | 规范化 profileHash、argvHash、slot、launchFingerprint 与 receiptHash 交叉校验 |
|
||||
| dispatch 旧 receipt 改挂 | 每个角色显式记录 attemptId；receipt 必须绑定当前 ACK task.id、同 role/profile/attempt，receiptId/attemptId 同空同填 |
|
||||
| 配置兼容 | ackVersion 必须是合法 SemVer；v0.10+ 的 orchestration/workerReceipts 必须同时存在，v0.9 旧板仍可只读校验和手动协作 |
|
||||
|
||||
### 不能被弱证明掩盖的边界
|
||||
|
||||
`receiptHash` 是无密钥 checksum，不是签名。项目内可写方能修改 receipt 后重算
|
||||
hash；而当前 Orca terminal metadata 不提供原始 Agent argv、模型或权限
|
||||
attestation。因此 v0.10 **不根据持久化 receipt 自动复用旧终端**。每次自动派发都
|
||||
重新执行 plan，并用 expected fingerprint 启动 fresh worker；持久化 receipt 只作
|
||||
审计和 dispatch 关联。
|
||||
|
||||
`launchFingerprint` 只证明完整计划没有漂移，不是一次性授权或幂等键；同一计划重复
|
||||
执行仍会创建新的 fresh terminal。成功后不得重放，结果不确定时必须先 reconcile。
|
||||
自动防重放要依赖后端原子 idempotency/claim 或项目外可信 launch intent，不能由
|
||||
checksum 伪装提供。
|
||||
|
||||
任务板里的 dispatch 关联也不是宽松的历史索引。`dispatch.<role>` 显式记录
|
||||
`profileId`、`receiptId` 和 `attemptId`，校验器要求 receipt 的 `createdFor` 精确绑定
|
||||
当前 ACK `tasks[].id`、同一角色和同一 attempt，并要求 profile 一致。该约束阻止把
|
||||
旧任务、旧角色或旧轮次 receipt 改挂到当前 dispatch，但不会把无密钥 receipt 升级成
|
||||
可信 attestation。
|
||||
|
||||
同样，receipt 证明的是 launcher 请求和本地 CLI/runtime 绑定，不证明模型供应商最终
|
||||
执行的模型。开放自动复用需要 Orca/ACP 提供启动参数 attestation，或项目外可信签发
|
||||
与校验通道。开放 full-access 还需要不可由项目文本伪造的用户授权、期限、撤销和外层
|
||||
隔离。这两项均留待后续版本。
|
||||
|
||||
威胁模型也明确到 Coordinator 账户边界：v0.10 防止任务板、任务内容、普通环境和
|
||||
受限 worker 把数据变成第二个启动命令入口；不抵御已经完全控制 Coordinator OS
|
||||
账户、Orca runtime、受信 Agent/Orca 可执行文件或用户级 Agent 配置/插件/MCP 的
|
||||
攻击者。`permissionMode` 也不是模型供应商或外部工具能力 attestation；后者必须依赖
|
||||
独立 OS 身份、受控 Agent 配置或平台能力。
|
||||
|
||||
## 后续版本提案：ACP 与可替换编排后端
|
||||
|
||||
### 当前决策
|
||||
|
||||
ACK 当前版本继续以 **Orca** 作为唯一自动编排后端。闭环语义保持工具无关，但
|
||||
worker 创建、终端身份绑定、dispatch 和 wait 的可执行适配仍由 Orca 完成。
|
||||
|
||||
ACP（Agent Client Protocol）作为后续版本的优先候选，当前只记录方案，不加入运行
|
||||
时依赖、不新增半成品 adapter，也不让现有流程在 Orca 与 ACP 之间自动猜测。
|
||||
|
||||
| 能力 | 当前版本 | 后续方向 |
|
||||
|------|----------|----------|
|
||||
| 自动创建并监督 worker | Orca | ACP capability negotiation 后可增加 ACP adapter |
|
||||
| 结构化模型与权限 profile | ACK 自己定义，Orca 只承载启动 | 保持为 ACK 稳定契约，不交给后端自由解释 |
|
||||
| dispatch / wait / terminal identity | Orca runtime handle | 映射到 ACP session / request / event identity |
|
||||
| 无自动后端时运行闭环 | 手动模式 | 可增加 PTY / Zellij 类低层 fallback，但不冒充语义协议 |
|
||||
| 后端选择 | 项目显式配置 | 未来仍需显式配置，不按已安装命令静默切换 |
|
||||
|
||||
### 后端无关的最小语义
|
||||
|
||||
未来 adapter 只应实现以下能力，不应接管 ACK 的角色、状态机或安全策略：
|
||||
|
||||
1. `createWorker(profile, worktree)`：按 ACK 已验证的结构化 profile 创建 worker。
|
||||
2. `inspectWorker(identity)`：返回可绑定的 runtime、session/incarnation 和活性。
|
||||
3. `dispatch(identity, taskContext)`：把一个明确任务投递给已验证 worker。
|
||||
4. `wait(identity, eventTypes)`：等待完成、复测、升级或 decision gate 事件。
|
||||
5. `closeWorker(identity)`：只关闭本次创建且身份仍匹配的 worker。
|
||||
|
||||
模型、reasoning effort、权限模式、worktree 和 receipt hash 仍由 ACK 校验。adapter
|
||||
不能重新开放自由 shell、任意 argv、任意环境变量或“后端默认模型”作为旁路。
|
||||
|
||||
### ACP 采用门槛
|
||||
|
||||
满足以下条件后再实现 ACP adapter：
|
||||
|
||||
- 目标 Agent CLI 对 ACP 的启动、会话身份、取消和事件语义足够稳定。
|
||||
- 能把 Developer/Test 的独立身份、worktree 和结构化 profile 映射到可核对字段。
|
||||
- 能区分“已请求的模型/权限”和“运行时可观测事实”，不把客户端请求冒充供应商证明。
|
||||
- 超时、重连、重复 dispatch 和 runtime 重启具有明确的幂等或恢复语义。
|
||||
- 与 Orca adapter 使用同一组 ACK conformance tests，且不会降低安全默认。
|
||||
|
||||
在这些门槛满足前，ACP 保持 **Deferred**。PTY 或 Zellij 一类方案只能作为较低层的
|
||||
进程/终端承载，不提供 session 语义、模型证明或任务状态机；如果以后加入，也必须
|
||||
经过独立 adapter，不能散落为文档中的自由命令。
|
||||
|
||||
### 参考依据
|
||||
|
||||
- [GitHub 仓库自定义指令](https://docs.github.com/en/copilot/how-tos/copilot-on-github/customize-copilot/add-custom-instructions/add-repository-instructions)
|
||||
区分仓库级、路径级和就近生效的 Agent 指令。
|
||||
- [Claude Code 项目记忆](https://code.claude.com/docs/zh-CN/memory)区分持久指令与
|
||||
自动记忆，并建议把较大的内容按作用域拆分、按需加载。
|
||||
- [Architectural Decision Records](https://adr.github.io/)用于保存单个重要决策的
|
||||
理由、取舍和后果，适合承载不应混入项目知识库的决策正文。
|
||||
@@ -0,0 +1,106 @@
|
||||
# ACK 飞书多维表格 Bug 收件箱
|
||||
|
||||
## 目标
|
||||
|
||||
让用户在飞书多维表格中跨设备记录文字和截图，由 ACK Coordinator 在同一记录补全并
|
||||
反复修订修复逻辑与验收标准。用户明确审核通过后，才将批准版本整理为独立、可验收、
|
||||
可幂等追踪的 ACK 任务并启动三角色闭环。
|
||||
|
||||
## 非目标
|
||||
|
||||
- 不用 Skill 承担人工记录入口。
|
||||
- 不抓取公开网页或依赖浏览器登录态。
|
||||
- 不把 App Secret、access token 或飞书用户凭据写入项目。
|
||||
- 不在审核前把草案写入 `tasks.yaml`，也不把 ACK 执行状态持续双向同步到飞书。
|
||||
- 不把多条互不相关的 Bug 合成一次 Developer 派发。
|
||||
|
||||
## 项目配置契约
|
||||
|
||||
可选配置位于 `docs/ack/tasks.yaml` 的 `project.bugIntake`。未配置时 ACK 保持现有行为。
|
||||
配置存在时必须包含：
|
||||
|
||||
| 字段 | 约束 |
|
||||
|------|------|
|
||||
| `provider` | 固定为 `feishu-base` |
|
||||
| `workflow` | 审核前协作固定为 `reviewed-writeback-v1`；缺省表示旧只读模式 |
|
||||
| `profile` | `lark-cli` profile 名称；每次命令显式传入 |
|
||||
| `baseToken` | 飞书 Base token |
|
||||
| `tableId` | 数据表 ID |
|
||||
| `viewId` | 只包含可导入记录的 `ACK Ready` 视图 ID |
|
||||
| `fields` | 逻辑字段到飞书字段 ID/名称的映射 |
|
||||
|
||||
`fields` 必须映射 `title`、`actual`、`expected`、`stepsToReproduce`、
|
||||
`acceptance`、`priority`、`attachments`、`updatedAt`。启用审核前协作时还必须映射
|
||||
`fixLogic`。字段值只作为单个 argv 传给 `lark-cli`，不经过 shell。
|
||||
|
||||
## CLI 契约
|
||||
|
||||
- 可执行文件固定为可信路径中的 `lark-cli`。
|
||||
- 允许官方 npm 包生成且 package/bin 映射校验通过的 `run.js` wrapper，并解析到包内
|
||||
native binary 执行；拒绝缺少 native binary 或其它同名软链接目标。
|
||||
- profile 由项目显式选择；不得执行 `profile use` 或读取 active profile作为回退。
|
||||
- 子进程使用最小环境，不继承可能覆盖 profile/config/凭据或注入运行时的环境变量。
|
||||
- 记录读取使用 `base +record-list`、JSON 输出、指定 Base/table/view 和投影字段。
|
||||
- 草案写回只通过读取器的 `write-draft` 子命令调用 `base +record-upsert`，并且只允许修改
|
||||
配置映射的 `fixLogic` 与 `acceptance`。
|
||||
- 批准后只通过 `import-approved` 生成规范任务字段和可重算的 `approvedPayloadHash`；任务
|
||||
校验器拒绝审核字段与该 hash 不一致的 reviewed task。
|
||||
- 记录超过一页时按 offset/limit 继续读取，并设置总页数/记录数上限。
|
||||
- 附件仅通过 `base +record-download-attachment` 下载到调用者显式提供的临时目录。
|
||||
- 附件数量、单文件大小、批次总大小和子进程文件写入均有硬上限；落盘大小必须与
|
||||
元数据一致。
|
||||
- 标准输出必须是单一 JSON；CLI stderr 只作为错误摘要，不把可能的凭据写入结果。
|
||||
|
||||
## 标准化结果
|
||||
|
||||
读取器输出批次元数据和 `records`。每条记录至少包含：
|
||||
|
||||
- `sourceRef`：对 provider、profile、Base、table、record ID 做域隔离 SHA-256
|
||||
后得到的稳定匿名引用；原始 profile、Base token 与 record ID 不拼入引用文本；
|
||||
- `recordId` 与 `updatedAt`；
|
||||
- 绑定来源事实、附件元数据和审核字段的 `draftRevision`；
|
||||
- title、actual、expected、steps、可选 fixLogic、acceptance、priority；
|
||||
- `enrichmentRequired`：缺失但允许 Coordinator 整理的 steps、fixLogic、acceptance、priority；
|
||||
- 附件的 name/type/size 与可选本地临时路径；附件 token 只在下载命令内部使用；
|
||||
- 原始字段中无法映射但不影响导入的警告。
|
||||
|
||||
输出不得包含 App ID、App Secret、Base token、附件 file token、tenant/user access
|
||||
token 或 CLI 配置文件内容。
|
||||
|
||||
## Coordinator 整理规则
|
||||
|
||||
1. 先运行读取器 `check` 确认 `lark-cli` 和项目 profile，再单独核对 app 已获得所需读写
|
||||
scope；`check` 不把用户 token 状态当作 app/bot scope 证明。
|
||||
2. 运行读取器 `plan` 读取 `ACK Ready` 视图并生成 create/refresh/unchanged/drift
|
||||
整理动作；需要看截图时使用临时下载目录。
|
||||
3. 将记录分类并在飞书补全 `fixLogic` 与 `acceptance`；用户反馈时继续写回同一记录。
|
||||
4. 用户必须明确批准当前 `draftRevision`；通过前不写 `tasks.yaml`、不派发角色、不修改
|
||||
应用代码。通过后每条导入任务保存 `source.kind=feishu-base`、`source.ref`、
|
||||
`source.recordId`、`source.updatedAt`、`source.workflow`、`source.approvedRevision`、
|
||||
`source.approvedPayloadHash`，并把截图观察转成文字证据。
|
||||
5. 导入前扫描已有任务的 `source.ref`。相同来源不得新建第二条任务。
|
||||
6. 来源更新但任务尚为 `open` 时可由 Coordinator刷新描述；任务已派发或进入终态时只报告漂移，由用户决定是否新开任务。
|
||||
7. 飞书记录删除、不可访问或 CLI 暂时失败时保留已有 ACK 任务，不反向删除。
|
||||
8. title、actual、expected、updatedAt 是不可推断的来源事实，部分缺失时 fail closed；
|
||||
steps、fixLogic、acceptance、priority 缺失时由 Coordinator 根据来源事实和项目上下文
|
||||
补齐并写回飞书。只有批准后的最终版本才导入任务板。
|
||||
9. 没有附件且所有 Bug 内容字段均为空的误建行跳过并输出 `blank_record_skipped`；带部分
|
||||
来源事实的残缺行不得静默跳过。
|
||||
|
||||
## 可观测验收信号
|
||||
|
||||
1. 两个假租户 profile 同时存在时，项目指定 `tenant-b`，所有记录和附件命令都显式包含 `--profile tenant-b`，不会读取 active 的 `tenant-a`。
|
||||
2. 只读取配置的 `ACK Ready` view ID，并投影配置字段；不查询整张表或其它视图。
|
||||
3. 一条含截图附件的假记录被标准化为稳定 `sourceRef`、完整文字字段和本地附件路径，输出中不存在任何 secret/token 凭据。
|
||||
4. CLI 缺失、profile 缺失、畸形 JSON、错位矩阵、分页越界、路径穿越或附件下载失败均返回非零退出码且不输出伪成功结果。
|
||||
5. ACK 文档明确要求按 `source.ref` 幂等整理；同一读取结果重复提交不会生成第二个来源任务。
|
||||
6. 现有无 `bugIntake` 的 ACK 项目仍能通过任务板校验并按原流程工作。
|
||||
7. 缺少 steps、acceptance、priority 的记录仍生成 create/refresh 计划并列出
|
||||
`enrichmentRequired`；全空误建行被跳过，缺 title/actual/expected 的部分记录失败。
|
||||
|
||||
## 最脆弱假设与降级
|
||||
|
||||
本设计假设官方 `lark-cli` 的 Base JSON 输出保持 `fields`、`record_id_list` 与行矩阵
|
||||
对应关系。读取器必须校验三者长度和字段映射；若上游输出契约变化，立即失败并提示
|
||||
升级适配器，不能错列生成 Bug。飞书或 CLI 不可用时，只停止新的同步，已经进入
|
||||
`tasks.yaml` 的任务继续按 ACK 闭环执行。
|
||||
@@ -0,0 +1,9 @@
|
||||
# 复制为 docs/ack/knowledge.yaml，替换占位符。结构见 templates/knowledge.schema.json。
|
||||
# Developer/Test 只能在任务证据中提出 candidate；只有 Coordinator 写入这里。
|
||||
version: 1
|
||||
updatedAt: "2026-08-01T12:43:06+08:00"
|
||||
project:
|
||||
name: "skills"
|
||||
# 检查 ID 映射到仓库内相对 path 和结构化 args；这里的内容不会被校验器执行。
|
||||
verificationRegistry: {}
|
||||
entries: []
|
||||
@@ -0,0 +1,71 @@
|
||||
# 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`，不提交或推送。
|
||||
@@ -0,0 +1,533 @@
|
||||
version: 1
|
||||
updatedAt: "2026-08-01T13:34:00+08:00"
|
||||
source: "Coordinator (PM) Agent"
|
||||
ackVersion: "0.12.0"
|
||||
project:
|
||||
name: "skills"
|
||||
repoPath: "/home/ace/orca/workspaces/.skills/record-bug"
|
||||
baseUrl: "n/a"
|
||||
devWorktree: "/home/ace/orca/workspaces/.skills/record-bug"
|
||||
overlayFile: "docs/ack/project.md"
|
||||
knowledgeFile: "docs/ack/knowledge.yaml"
|
||||
orchestration:
|
||||
profileVersion: 1
|
||||
mode: "orca"
|
||||
allowedWorktrees:
|
||||
- "/home/ace/orca/workspaces/.skills/record-bug"
|
||||
modelAllowlist:
|
||||
codex:
|
||||
developer:
|
||||
standard: ["gpt-5.6-terra"]
|
||||
strong: ["gpt-5.6-sol"]
|
||||
test:
|
||||
standard: ["gpt-5.6-luna"]
|
||||
profiles:
|
||||
codex-dev-standard:
|
||||
role: "developer"
|
||||
cli: "codex"
|
||||
tier: "standard"
|
||||
model: "gpt-5.6-terra"
|
||||
reasoningEffort: "medium"
|
||||
permissionMode: "workspace-write"
|
||||
codex-test-standard:
|
||||
role: "test"
|
||||
cli: "codex"
|
||||
tier: "standard"
|
||||
model: "gpt-5.6-luna"
|
||||
reasoningEffort: "low"
|
||||
permissionMode: "workspace-write"
|
||||
codex-dev-strong:
|
||||
role: "developer"
|
||||
cli: "codex"
|
||||
tier: "strong"
|
||||
model: "gpt-5.6-sol"
|
||||
reasoningEffort: "high"
|
||||
permissionMode: "workspace-write"
|
||||
defaults:
|
||||
developer: "codex-dev-standard"
|
||||
test: "codex-test-standard"
|
||||
developerUpgraded: "codex-dev-strong"
|
||||
|
||||
workerReceipts:
|
||||
- receiptVersion: 1
|
||||
id: "WR-1c9755604c0de98ce5ccc5913faa4984e9d975879250095b3553a796bccb261d"
|
||||
launchId: "1c9755604c0de98ce5ccc5913faa4984e9d975879250095b3553a796bccb261d"
|
||||
profileId: "codex-dev-standard"
|
||||
profileHash: "sha256:fd5bc08d5d8a154175675a2de3b29cabbf016fdae0ed5f76167c63bced0bc47b"
|
||||
launchFingerprint: "sha256:7de2f9ebf3065e7c044150fa87aed39582a8018b63a0dabac22194bf52ad52b7"
|
||||
slot: 1
|
||||
createdFor:
|
||||
taskId: "FEISHU-001"
|
||||
attemptId: "FEISHU-001-A1"
|
||||
role: "developer"
|
||||
worktree:
|
||||
path: "/home/ace/orca/workspaces/.skills/record-bug"
|
||||
device: 2049
|
||||
inode: 1705498
|
||||
gitCommonDir: "/home/ace/.skills/.git"
|
||||
gitCommonDevice: 2049
|
||||
gitCommonInode: 558841
|
||||
requested:
|
||||
cli: "codex"
|
||||
tier: "standard"
|
||||
model: "gpt-5.6-terra"
|
||||
reasoningEffort: "medium"
|
||||
permissionMode: "workspace-write"
|
||||
executable: "/home/ace/.codex/packages/standalone/releases/0.146.0-x86_64-unknown-linux-musl/bin/codex"
|
||||
executableDevice: 2049
|
||||
executableInode: 1453403
|
||||
cliVersion: "codex-cli 0.146.0"
|
||||
argv:
|
||||
- "/home/ace/.codex/packages/standalone/releases/0.146.0-x86_64-unknown-linux-musl/bin/codex"
|
||||
- "--strict-config"
|
||||
- "--model"
|
||||
- "gpt-5.6-terra"
|
||||
- "--config"
|
||||
- "model_reasoning_effort=medium"
|
||||
- "--sandbox"
|
||||
- "workspace-write"
|
||||
- "--ask-for-approval"
|
||||
- "never"
|
||||
- "--cd"
|
||||
- "/home/ace/orca/workspaces/.skills/record-bug"
|
||||
argvHash: "sha256:a17f4a56e4324a6c170773dffdf0b986c4f070e04fe404ba8395135c686182ee"
|
||||
environmentPolicy: "per-cli-allowlist-v1"
|
||||
binding:
|
||||
orchestrator: "orca"
|
||||
runtimeId: "30613bea-9f1e-4d6b-949f-58e43f77688a"
|
||||
handle: "term_4d6278c9-83ac-4876-a29d-022adc346e6c"
|
||||
incarnationId: "6daffb4c-e705-47f3-b7c2-d1ee1fb16c56"
|
||||
observedWorktreePath: "/home/ace/orca/workspaces/.skills/record-bug"
|
||||
connected: true
|
||||
writable: true
|
||||
boundAt: "2026-08-01T04:46:51.629061Z"
|
||||
createdAt: "2026-08-01T04:46:42.869861Z"
|
||||
receiptHash: "sha256:93e7e4454438a4d1c9a64eb7429563bb4b71348715cc4cb3e42c96cb9ca75fa4"
|
||||
- receiptVersion: 1
|
||||
id: "WR-035285dde990c7f59be5842a6c98eab8f715dd9c4400fba79aba341fab53ffc3"
|
||||
launchId: "035285dde990c7f59be5842a6c98eab8f715dd9c4400fba79aba341fab53ffc3"
|
||||
profileId: "codex-test-standard"
|
||||
profileHash: "sha256:30a1cf4d0f1b180ca1aebd759cf8a9425047ed9563f4cf3eb3fe8b3935ca2078"
|
||||
launchFingerprint: "sha256:981fe3c23594573f564de9ab321e724324962958ed689ad3c0c98d7d165c1aa9"
|
||||
slot: 2
|
||||
createdFor:
|
||||
taskId: "FEISHU-001"
|
||||
attemptId: "FEISHU-001-A1"
|
||||
role: "test"
|
||||
worktree:
|
||||
path: "/home/ace/orca/workspaces/.skills/record-bug"
|
||||
device: 2049
|
||||
inode: 1705498
|
||||
gitCommonDir: "/home/ace/.skills/.git"
|
||||
gitCommonDevice: 2049
|
||||
gitCommonInode: 558841
|
||||
requested:
|
||||
cli: "codex"
|
||||
tier: "standard"
|
||||
model: "gpt-5.6-luna"
|
||||
reasoningEffort: "low"
|
||||
permissionMode: "workspace-write"
|
||||
executable: "/home/ace/.codex/packages/standalone/releases/0.146.0-x86_64-unknown-linux-musl/bin/codex"
|
||||
executableDevice: 2049
|
||||
executableInode: 1453403
|
||||
cliVersion: "codex-cli 0.146.0"
|
||||
argv:
|
||||
- "/home/ace/.codex/packages/standalone/releases/0.146.0-x86_64-unknown-linux-musl/bin/codex"
|
||||
- "--strict-config"
|
||||
- "--model"
|
||||
- "gpt-5.6-luna"
|
||||
- "--config"
|
||||
- "model_reasoning_effort=low"
|
||||
- "--sandbox"
|
||||
- "workspace-write"
|
||||
- "--ask-for-approval"
|
||||
- "never"
|
||||
- "--cd"
|
||||
- "/home/ace/orca/workspaces/.skills/record-bug"
|
||||
argvHash: "sha256:ad1991c9d70fc574c856a2f7cb51a7e93eca5d286dfc689b09b414f7144f6369"
|
||||
environmentPolicy: "per-cli-allowlist-v1"
|
||||
binding:
|
||||
orchestrator: "orca"
|
||||
runtimeId: "30613bea-9f1e-4d6b-949f-58e43f77688a"
|
||||
handle: "term_ab858ba7-b972-45fb-bf50-61e96ced2830"
|
||||
incarnationId: "9e20c158-7ac3-4a18-8dca-f9fec50126d6"
|
||||
observedWorktreePath: "/home/ace/orca/workspaces/.skills/record-bug"
|
||||
connected: true
|
||||
writable: true
|
||||
boundAt: "2026-08-01T04:57:33.909375Z"
|
||||
createdAt: "2026-08-01T04:57:25.086609Z"
|
||||
receiptHash: "sha256:1245532d66814f5d3b2a6a3b22293ead597f04390e628333569a7ba8763d0a84"
|
||||
- receiptVersion: 1
|
||||
id: "WR-3202fbd30c60dfc6614787e82d0f8e10701f811fdc3d43af54b8cc269d8165f1"
|
||||
launchId: "3202fbd30c60dfc6614787e82d0f8e10701f811fdc3d43af54b8cc269d8165f1"
|
||||
profileId: "codex-dev-standard"
|
||||
profileHash: "sha256:fd5bc08d5d8a154175675a2de3b29cabbf016fdae0ed5f76167c63bced0bc47b"
|
||||
launchFingerprint: "sha256:8264af6531e9828c0f994845b3a24931e22abea72d8a1d54a7c764577e544873"
|
||||
slot: 3
|
||||
createdFor:
|
||||
taskId: "FEISHU-001"
|
||||
attemptId: "FEISHU-001-A2"
|
||||
role: "developer"
|
||||
worktree:
|
||||
path: "/home/ace/orca/workspaces/.skills/record-bug"
|
||||
device: 2049
|
||||
inode: 1705498
|
||||
gitCommonDir: "/home/ace/.skills/.git"
|
||||
gitCommonDevice: 2049
|
||||
gitCommonInode: 558841
|
||||
requested:
|
||||
cli: "codex"
|
||||
tier: "standard"
|
||||
model: "gpt-5.6-terra"
|
||||
reasoningEffort: "medium"
|
||||
permissionMode: "workspace-write"
|
||||
executable: "/home/ace/.codex/packages/standalone/releases/0.146.0-x86_64-unknown-linux-musl/bin/codex"
|
||||
executableDevice: 2049
|
||||
executableInode: 1453403
|
||||
cliVersion: "codex-cli 0.146.0"
|
||||
argv:
|
||||
- "/home/ace/.codex/packages/standalone/releases/0.146.0-x86_64-unknown-linux-musl/bin/codex"
|
||||
- "--strict-config"
|
||||
- "--model"
|
||||
- "gpt-5.6-terra"
|
||||
- "--config"
|
||||
- "model_reasoning_effort=medium"
|
||||
- "--sandbox"
|
||||
- "workspace-write"
|
||||
- "--ask-for-approval"
|
||||
- "never"
|
||||
- "--cd"
|
||||
- "/home/ace/orca/workspaces/.skills/record-bug"
|
||||
argvHash: "sha256:a17f4a56e4324a6c170773dffdf0b986c4f070e04fe404ba8395135c686182ee"
|
||||
environmentPolicy: "per-cli-allowlist-v1"
|
||||
binding:
|
||||
orchestrator: "orca"
|
||||
runtimeId: "30613bea-9f1e-4d6b-949f-58e43f77688a"
|
||||
handle: "term_d1b02227-6bd6-4bd3-a432-bb50f64fca8c"
|
||||
incarnationId: "f77f05ff-fb2b-4099-ab03-070f61671673"
|
||||
observedWorktreePath: "/home/ace/orca/workspaces/.skills/record-bug"
|
||||
connected: true
|
||||
writable: true
|
||||
boundAt: "2026-08-01T05:01:26.824435Z"
|
||||
createdAt: "2026-08-01T05:01:17.965038Z"
|
||||
receiptHash: "sha256:c20c47c7491b5b399d2c29fce67a7035b432969bda0ccb74948eb03c3d085380"
|
||||
- receiptVersion: 1
|
||||
id: "WR-12c3784e1719302b77728917b913c3233ef022f811a94050d1842e2d54971ebd"
|
||||
launchId: "12c3784e1719302b77728917b913c3233ef022f811a94050d1842e2d54971ebd"
|
||||
profileId: "codex-test-standard"
|
||||
profileHash: "sha256:30a1cf4d0f1b180ca1aebd759cf8a9425047ed9563f4cf3eb3fe8b3935ca2078"
|
||||
launchFingerprint: "sha256:621c7d5d6b7182d9a1ebf211fa11a80d7b100a3b682f8800f61031a651f5bf2a"
|
||||
slot: 4
|
||||
createdFor:
|
||||
taskId: "FEISHU-001"
|
||||
attemptId: "FEISHU-001-A2"
|
||||
role: "test"
|
||||
worktree:
|
||||
path: "/home/ace/orca/workspaces/.skills/record-bug"
|
||||
device: 2049
|
||||
inode: 1705498
|
||||
gitCommonDir: "/home/ace/.skills/.git"
|
||||
gitCommonDevice: 2049
|
||||
gitCommonInode: 558841
|
||||
requested:
|
||||
cli: "codex"
|
||||
tier: "standard"
|
||||
model: "gpt-5.6-luna"
|
||||
reasoningEffort: "low"
|
||||
permissionMode: "workspace-write"
|
||||
executable: "/home/ace/.codex/packages/standalone/releases/0.146.0-x86_64-unknown-linux-musl/bin/codex"
|
||||
executableDevice: 2049
|
||||
executableInode: 1453403
|
||||
cliVersion: "codex-cli 0.146.0"
|
||||
argv:
|
||||
- "/home/ace/.codex/packages/standalone/releases/0.146.0-x86_64-unknown-linux-musl/bin/codex"
|
||||
- "--strict-config"
|
||||
- "--model"
|
||||
- "gpt-5.6-luna"
|
||||
- "--config"
|
||||
- "model_reasoning_effort=low"
|
||||
- "--sandbox"
|
||||
- "workspace-write"
|
||||
- "--ask-for-approval"
|
||||
- "never"
|
||||
- "--cd"
|
||||
- "/home/ace/orca/workspaces/.skills/record-bug"
|
||||
argvHash: "sha256:ad1991c9d70fc574c856a2f7cb51a7e93eca5d286dfc689b09b414f7144f6369"
|
||||
environmentPolicy: "per-cli-allowlist-v1"
|
||||
binding:
|
||||
orchestrator: "orca"
|
||||
runtimeId: "30613bea-9f1e-4d6b-949f-58e43f77688a"
|
||||
handle: "term_1ec9d2e1-a1b6-45db-8477-097e39a93ee4"
|
||||
incarnationId: "a6f79ac3-9cc6-40a1-a38a-e7b7c2a49b02"
|
||||
observedWorktreePath: "/home/ace/orca/workspaces/.skills/record-bug"
|
||||
connected: true
|
||||
writable: true
|
||||
boundAt: "2026-08-01T05:05:36.189001Z"
|
||||
createdAt: "2026-08-01T05:05:27.500696Z"
|
||||
receiptHash: "sha256:824227bda0e78558807e10da9d89ec32ee4d7f37d782b866bca4629c5ac9e8fb"
|
||||
- receiptVersion: 1
|
||||
id: "WR-90c5c8a69173ce07d1db3f6065eaf956ca6cacbdc5396ac3a224e04a7fe8ed21"
|
||||
launchId: "90c5c8a69173ce07d1db3f6065eaf956ca6cacbdc5396ac3a224e04a7fe8ed21"
|
||||
profileId: "codex-dev-standard"
|
||||
profileHash: "sha256:fd5bc08d5d8a154175675a2de3b29cabbf016fdae0ed5f76167c63bced0bc47b"
|
||||
launchFingerprint: "sha256:97ef498caf4a5f0d48fef22773c942a5065dfcf5cecefa22a6ad21df8d04bcd1"
|
||||
slot: 5
|
||||
createdFor:
|
||||
taskId: "FEISHU-001"
|
||||
attemptId: "FEISHU-001-A3"
|
||||
role: "developer"
|
||||
worktree:
|
||||
path: "/home/ace/orca/workspaces/.skills/record-bug"
|
||||
device: 2049
|
||||
inode: 1705498
|
||||
gitCommonDir: "/home/ace/.skills/.git"
|
||||
gitCommonDevice: 2049
|
||||
gitCommonInode: 558841
|
||||
requested:
|
||||
cli: "codex"
|
||||
tier: "standard"
|
||||
model: "gpt-5.6-terra"
|
||||
reasoningEffort: "medium"
|
||||
permissionMode: "workspace-write"
|
||||
executable: "/home/ace/.codex/packages/standalone/releases/0.146.0-x86_64-unknown-linux-musl/bin/codex"
|
||||
executableDevice: 2049
|
||||
executableInode: 1453403
|
||||
cliVersion: "codex-cli 0.146.0"
|
||||
argv:
|
||||
- "/home/ace/.codex/packages/standalone/releases/0.146.0-x86_64-unknown-linux-musl/bin/codex"
|
||||
- "--strict-config"
|
||||
- "--model"
|
||||
- "gpt-5.6-terra"
|
||||
- "--config"
|
||||
- "model_reasoning_effort=medium"
|
||||
- "--sandbox"
|
||||
- "workspace-write"
|
||||
- "--ask-for-approval"
|
||||
- "never"
|
||||
- "--cd"
|
||||
- "/home/ace/orca/workspaces/.skills/record-bug"
|
||||
argvHash: "sha256:a17f4a56e4324a6c170773dffdf0b986c4f070e04fe404ba8395135c686182ee"
|
||||
environmentPolicy: "per-cli-allowlist-v1"
|
||||
binding:
|
||||
orchestrator: "orca"
|
||||
runtimeId: "30613bea-9f1e-4d6b-949f-58e43f77688a"
|
||||
handle: "term_88079d90-29a3-48ac-9b97-bec011abc249"
|
||||
incarnationId: "5d4f785f-e0b5-4ab3-9de3-72ebc2da3b06"
|
||||
observedWorktreePath: "/home/ace/orca/workspaces/.skills/record-bug"
|
||||
connected: true
|
||||
writable: true
|
||||
boundAt: "2026-08-01T05:16:40.565911Z"
|
||||
createdAt: "2026-08-01T05:16:31.788668Z"
|
||||
receiptHash: "sha256:c62417b2ee8e9815228a18b2ee1be84b2844dada50eb9703a061e08e51e57eb7"
|
||||
- receiptVersion: 1
|
||||
id: "WR-8d81f78e66ba7c82c7a6a734b35e5941ef0aa3f03f8ef694baae75eeaf9ebfd7"
|
||||
launchId: "8d81f78e66ba7c82c7a6a734b35e5941ef0aa3f03f8ef694baae75eeaf9ebfd7"
|
||||
profileId: "codex-test-standard"
|
||||
profileHash: "sha256:30a1cf4d0f1b180ca1aebd759cf8a9425047ed9563f4cf3eb3fe8b3935ca2078"
|
||||
launchFingerprint: "sha256:6c7a45f7dd119bb6ef3bfaed7961c30f257285d940f248e0b16678dcad1bd19d"
|
||||
slot: 6
|
||||
createdFor:
|
||||
taskId: "FEISHU-001"
|
||||
attemptId: "FEISHU-001-A3"
|
||||
role: "test"
|
||||
worktree:
|
||||
path: "/home/ace/orca/workspaces/.skills/record-bug"
|
||||
device: 2049
|
||||
inode: 1705498
|
||||
gitCommonDir: "/home/ace/.skills/.git"
|
||||
gitCommonDevice: 2049
|
||||
gitCommonInode: 558841
|
||||
requested:
|
||||
cli: "codex"
|
||||
tier: "standard"
|
||||
model: "gpt-5.6-luna"
|
||||
reasoningEffort: "low"
|
||||
permissionMode: "workspace-write"
|
||||
executable: "/home/ace/.codex/packages/standalone/releases/0.146.0-x86_64-unknown-linux-musl/bin/codex"
|
||||
executableDevice: 2049
|
||||
executableInode: 1453403
|
||||
cliVersion: "codex-cli 0.146.0"
|
||||
argv:
|
||||
- "/home/ace/.codex/packages/standalone/releases/0.146.0-x86_64-unknown-linux-musl/bin/codex"
|
||||
- "--strict-config"
|
||||
- "--model"
|
||||
- "gpt-5.6-luna"
|
||||
- "--config"
|
||||
- "model_reasoning_effort=low"
|
||||
- "--sandbox"
|
||||
- "workspace-write"
|
||||
- "--ask-for-approval"
|
||||
- "never"
|
||||
- "--cd"
|
||||
- "/home/ace/orca/workspaces/.skills/record-bug"
|
||||
argvHash: "sha256:ad1991c9d70fc574c856a2f7cb51a7e93eca5d286dfc689b09b414f7144f6369"
|
||||
environmentPolicy: "per-cli-allowlist-v1"
|
||||
binding:
|
||||
orchestrator: "orca"
|
||||
runtimeId: "30613bea-9f1e-4d6b-949f-58e43f77688a"
|
||||
handle: "term_44ab2675-445a-4f51-a0f5-83960bc1ca3b"
|
||||
incarnationId: "6e37ac75-5725-410c-87af-63f8bb42a911"
|
||||
observedWorktreePath: "/home/ace/orca/workspaces/.skills/record-bug"
|
||||
connected: true
|
||||
writable: true
|
||||
boundAt: "2026-08-01T05:25:08.564556Z"
|
||||
createdAt: "2026-08-01T05:24:59.720042Z"
|
||||
receiptHash: "sha256:dcbed5b2a3fa99312deba61951253992741eca885068e8f649613bd97eb3f59f"
|
||||
|
||||
summary:
|
||||
verified: ["FEISHU-001"]
|
||||
open: []
|
||||
failedRetest: []
|
||||
leftovers: []
|
||||
|
||||
tasks:
|
||||
- id: "FEISHU-001"
|
||||
type: "feature"
|
||||
title: "ACK 从飞书多维表格按项目 profile 读取并整理 Bug"
|
||||
priority: "P1"
|
||||
status: "verified"
|
||||
assignee: "test"
|
||||
component: "skills/ack"
|
||||
specRefs:
|
||||
- "docs/ack-feishu-bug-intake.md"
|
||||
testRefs:
|
||||
- "tests/test_ack_feishu_intake_unit.py"
|
||||
- "tests/test_ack_feishu_intake_e2e.py"
|
||||
knowledgeRefs: []
|
||||
knowledgeApplied: []
|
||||
knowledgeCandidates: []
|
||||
knowledgeChecks: []
|
||||
|
||||
description: >
|
||||
扩展完整 ACK Skill，使项目可以在 tasks.yaml 中声明飞书多维表格 Bug 收件箱和
|
||||
lark-cli profile。ACK 通过可信、无 shell 的读取器读取 ACK Ready 视图、按需
|
||||
下载截图并输出可幂等整理的标准化记录；不同项目不会串用飞书租户。
|
||||
|
||||
stepsToReproduce:
|
||||
- "创建两个假 lark-cli profile：tenant-a 为 active，项目配置 tenant-b"
|
||||
- "在 tenant-b 的 ACK Ready 视图返回一条带截图附件的 Bug 记录"
|
||||
- "运行 ACK 飞书读取器 check/fetch，并重复提交同一标准化结果"
|
||||
|
||||
expected: >
|
||||
读取器每次显式使用 tenant-b，仅读取配置 view，正确标准化文字与截图附件，
|
||||
对所有错误 fail closed；ACK 按稳定 source.ref 整理，重复来源不产生新任务，
|
||||
未配置飞书的旧项目保持兼容。
|
||||
|
||||
actual: >
|
||||
当前 ACK 没有飞书 Bug 数据源、CLI profile 配置、附件读取或来源幂等规则。
|
||||
|
||||
evidence:
|
||||
browser: "飞书多维表格记录可包含文字字段和截图附件；本次使用假 CLI 离线复现"
|
||||
api: "官方 lark-cli base +record-list 与 +record-download-attachment"
|
||||
logs: "本机当前没有 lark-cli，验证必须通过隔离假 CLI 完成"
|
||||
|
||||
verification:
|
||||
commands:
|
||||
- "python3 -m unittest discover -s tests -p 'test_ack_feishu_intake_unit.py'"
|
||||
- "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"
|
||||
browser:
|
||||
page: "n/a"
|
||||
checks:
|
||||
- "假 CLI 记录证明所有数据命令显式使用 tenant-b profile"
|
||||
- "标准化输出包含唯一 sourceRef 与本地截图路径"
|
||||
- "重复来源整理结果只对应一个 ACK 任务"
|
||||
|
||||
dispatch:
|
||||
developer:
|
||||
profileId: "codex-dev-standard"
|
||||
receiptId: "WR-90c5c8a69173ce07d1db3f6065eaf956ca6cacbdc5396ac3a224e04a7fe8ed21"
|
||||
attemptId: "FEISHU-001-A3"
|
||||
taskId: "task_9bc1dba1e21a"
|
||||
dispatchId: "ctx_0791582a526f"
|
||||
test:
|
||||
profileId: "codex-test-standard"
|
||||
receiptId: "WR-8d81f78e66ba7c82c7a6a734b35e5941ef0aa3f03f8ef694baae75eeaf9ebfd7"
|
||||
attemptId: "FEISHU-001-A3"
|
||||
taskId: "task_4f70d2496d13"
|
||||
dispatchId: "ctx_66ab3460dda2"
|
||||
rounds:
|
||||
- round: 1
|
||||
attemptId: "FEISHU-001-A1"
|
||||
result: failed
|
||||
evidence: >
|
||||
Isolated fake tenant and screenshot intake passed profile isolation,
|
||||
download containment, fail-closed behavior, organization rules and
|
||||
legacy validation, but normalized output leaked baseToken inside
|
||||
sourceRef and exposed the attachment file token.
|
||||
- round: 2
|
||||
attemptId: "FEISHU-001-A2"
|
||||
result: failed
|
||||
evidence: >
|
||||
Strengthened isolated E2E passed after the secret-output fix, but
|
||||
Coordinator final gate compared the adapter with official lark-cli
|
||||
source: profile list returns a raw JSON array and has no --format
|
||||
flag, while the adapter requires an object and sends --format.
|
||||
Executable lookup also trusts arbitrary PATH instead of the fixed
|
||||
trusted directories required by the product spec; template source
|
||||
reference still documents the obsolete raw form.
|
||||
- round: 3
|
||||
attemptId: "FEISHU-001-A3"
|
||||
result: passed
|
||||
evidence: >
|
||||
Fresh Test ran a file-backed fake Feishu submission containing all
|
||||
Bug text fields and a screenshot through the production check/fetch
|
||||
entry points. Six focused E2E tests and five unit tests passed. The
|
||||
run verified the official raw profile array and data.data matrix,
|
||||
explicit tenant-b selection, trusted executable resolution,
|
||||
screenshot containment, stable opaque sourceRef deduplication and
|
||||
fail-closed handling for malformed, ambiguous, non-progressing and
|
||||
over-limit responses. Validators, skiff check, compileall and diff
|
||||
checks also passed.
|
||||
|
||||
resolution:
|
||||
fixedBy: "term_88079d90-29a3-48ac-9b97-bec011abc249"
|
||||
verifiedBy: "term_44ab2675-445a-4f51-a0f5-83960bc1ca3b"
|
||||
verifiedAt: "2026-08-01T13:31:40+08:00"
|
||||
leftoverReason: null
|
||||
evidence:
|
||||
developer: >
|
||||
FEISHU-001-A1 implemented ACK 0.12.0 Feishu Base intake. Focused unit
|
||||
tests, ACK contract tests, compileall, task validation and diff check
|
||||
passed. The fresh worker could not deliver worker_done through its
|
||||
workspace-write sandbox because Orca relay/FUSE was unavailable;
|
||||
Coordinator preserved the terminal evidence in Orca task
|
||||
task_ed87b3386a80 and did not treat it as final verification.
|
||||
testRound1: >
|
||||
Fresh Test term_ab858ba7-b972-45fb-bf50-61e96ced2830 created the
|
||||
isolated E2E fixture and found secret-safe output failing while all
|
||||
other targeted signals passed. Evidence is retained in Orca task
|
||||
task_251a9b5265cd; Test relay was unavailable for the same sandbox
|
||||
reason, so this remains a failed retest rather than verification.
|
||||
developerRound2: >
|
||||
Fresh Developer term_d1b02227-6bd6-4bd3-a432-bb50f64fca8c changed
|
||||
sourceRef to a domain-separated SHA-256 digest and kept file tokens
|
||||
internal to download calls. Focused unit, ACK contract, read-only E2E,
|
||||
compileall and diff checks passed; independent round-2 Test is still
|
||||
required.
|
||||
coordinatorGateRound2: >
|
||||
Targeted Test evidence was green, but final source-contract review
|
||||
against official larksuite/cli cmd/profile/list.go rejected the round:
|
||||
actual profile list output is a JSON array, the command exposes no
|
||||
format flag, and the current reader resolves lark-cli through caller
|
||||
PATH rather than fixed trusted directories.
|
||||
developerRound3: >
|
||||
Fresh Developer term_88079d90-29a3-48ac-9b97-bec011abc249 added the
|
||||
trusted resolver, official raw profile-list and data.data parsing,
|
||||
strict envelopes, sanitized execution PATH, revised unit coverage and
|
||||
complete setup/source examples. Five focused unit tests, 34 ACK
|
||||
contracts (one skipped), compileall, task validation and diff check
|
||||
passed; final independent Test remains required.
|
||||
testRound3: >
|
||||
Fresh Test term_44ab2675-445a-4f51-a0f5-83960bc1ca3b passed six
|
||||
isolated E2E cases and all five Feishu unit tests. It exercised the
|
||||
production entry points with a real fake-CLI subprocess and a separate
|
||||
submitted-bug JSON file, downloaded a screenshot into a temporary
|
||||
directory, repeated the fetch to prove a stable opaque sourceRef, and
|
||||
simulated ACK source.ref organization without duplicates. The four
|
||||
failures in the wider legacy suite reproduce unchanged on base commit
|
||||
f08edb6 and are classified as existing environment/layout failures.
|
||||
Orca worker_done transport was unavailable inside the worker sandbox
|
||||
because FUSE was absent; the full fresh-terminal evidence is retained
|
||||
in Orca task task_4f70d2496d13.
|
||||
@@ -1,175 +0,0 @@
|
||||
# ack — Agent Collaboration Kit
|
||||
|
||||
`ack`（Agent Collaboration Kit）是一套可复用到其它项目的多 Agent 协作规范，默认三个独立角色：**Coordinator (PM) 拆解需求并调度闭环，Developer 实现与白盒验证，Test 独立黑盒复测**。关键属性是验证者 ≠ 实现者。角色默认按成本分层：Coordinator 用强模型（且不亲自跑测试），Test/Developer 用中低模型（见 `core/model-routing.md`）。
|
||||
|
||||
当前版本见 `VERSION`。这不是 Agent Skill（无 `SKILL.md`），不由 skiff 安装，而是复制/引用到目标项目。
|
||||
|
||||
---
|
||||
|
||||
## 适用场景
|
||||
|
||||
- 多个 Agent 分工协作，而非单个 Agent 从需求写到代码。
|
||||
- 需要区分规格、测试、实现、复测的责任边界（Coordinator / Test / Developer 三角色）。
|
||||
- 需要把失败项派发给 Developer，`worker_done` 后由独立的 Test 复测、Coordinator 终检。
|
||||
- 需要连续修复多个问题，并把三轮仍未修好的问题留档。
|
||||
|
||||
---
|
||||
|
||||
## 目录结构
|
||||
|
||||
```text
|
||||
ack/
|
||||
VERSION # kit 版本，接入时记入项目
|
||||
README.md
|
||||
init-new-project.md # 给 Agent 的新项目初始化手册
|
||||
adoption-checklist.md
|
||||
core/ # 稳定核心：跨项目通用，随 kit 升级，尽量别改
|
||||
kickoff.md # 如何开始一个需求（启动手册 + 开场指令模板）
|
||||
roles-and-permissions.md # 角色/权限/状态机/完成定义（SSOT）
|
||||
model-routing.md # 三角色默认模型档位 + 升级规则（SSOT）
|
||||
closed-loop.md # 编排无关闭环 + 手动模式 + worktree 对齐
|
||||
optimization-method.md # 验收信号 + 三轮失败策略（SSOT）
|
||||
prompt-templates.md # 派发 prompt 模板
|
||||
orca-adapter.md # Orca 具体命令（一种编排实现，可选）
|
||||
templates/ # 项目覆盖层：复制一次并填空
|
||||
project.template.md # 项目覆盖层模板（文件名可配置，默认不占用 AGENTS.md）
|
||||
tasks.template.yaml
|
||||
tasks.schema.json # 任务板权威结构（跨语言）
|
||||
examples/ # 填好的最小可跑示例
|
||||
project.example.md
|
||||
tasks.example.yaml
|
||||
scripts/
|
||||
validate_tasks.py # 校验 tasks.yaml（参考实现）
|
||||
```
|
||||
|
||||
**核心原则**：`core/` 是稳定核心，每个概念只定义一次；`templates/` 是项目覆盖层。二者分离，让 kit 升级和项目定制互不干扰。
|
||||
|
||||
---
|
||||
|
||||
## 项目目录布局（推荐）
|
||||
|
||||
每个项目在 `docs/ack/` 下只放**一个软链接**加两个项目文件，稳定核心全部走软链接：
|
||||
|
||||
```text
|
||||
<project>/docs/ack/
|
||||
kit -> <此框架目录> # 唯一软链接：core/templates/examples/scripts 全在里面
|
||||
project.md # 项目覆盖层（差异），可改名，见下
|
||||
tasks.yaml # 项目任务板
|
||||
```
|
||||
|
||||
引用稳定核心时统一走 `kit/` 前缀，例如 `docs/ack/kit/core/roles-and-permissions.md`。
|
||||
这样「一个项目一个软链接」，kit 升级自动生效，项目定制（`project.md` + `tasks.yaml`）互不干扰。
|
||||
|
||||
## 分发方式（二选一）
|
||||
|
||||
### 方式 A：单软链接引用（推荐，可升级）
|
||||
|
||||
把本框架目录整体 symlink 成项目的 `docs/ack/kit`：
|
||||
|
||||
```bash
|
||||
mkdir -p <project>/docs/ack
|
||||
ln -s <此框架绝对路径> <project>/docs/ack/kit
|
||||
```
|
||||
|
||||
也可用 git submodule / sparse checkout 达到同样效果。项目只维护 `project.md` 与 `tasks.yaml`。
|
||||
|
||||
### 方式 B：整份复制（简单，手动升级）
|
||||
|
||||
把本框架整目录复制成 `docs/ack/kit/`（或直接铺平到 `docs/ack/`，此时引用去掉 `kit/` 前缀）。**务必**在 `project.md` 与 `tasks.yaml` 的 `kitVersion` 记录来源版本，日后照 `VERSION` diff 升级。
|
||||
|
||||
### 覆盖层文件名（重要）
|
||||
|
||||
项目差异（路径、命令、handle、模型档位）写在**项目覆盖层文件**里，**默认 `docs/ack/project.md`，不占用 `AGENTS.md`**，以免与团队已有的 `AGENTS.md` 约定冲突。文件名可配置：想让 Agent 自动加载，可在 `AGENTS.md` 加一行指向它，或直接命名为 `AGENTS.md`。无论叫什么，都在 `tasks.yaml` 的 `project.overlayFile` 记录实际路径。覆盖层只填差异，不复制 `core/` 内容。
|
||||
|
||||
---
|
||||
|
||||
## 快速接入
|
||||
|
||||
让 Agent 在新项目执行初始化时，优先给它 `init-new-project.md`。
|
||||
|
||||
1. 建 `docs/ack/`，按方式 A 建单软链接 `kit`。
|
||||
2. 复制 `kit/templates/project.template.md` → `docs/ack/project.md`，填项目差异与模型档位，记 `kitVersion`。
|
||||
3. 复制 `kit/templates/tasks.template.yaml` → `docs/ack/tasks.yaml`，填 `project`（含 `overlayFile`）与首个任务。
|
||||
4. 跑 `python3 docs/ack/kit/scripts/validate_tasks.py docs/ack/tasks.yaml` 确认结构。
|
||||
5. 按 `kit/core/closed-loop.md` 跑闭环（Orca 见 `kit/core/orca-adapter.md`，无 Orca 用手动模式）。
|
||||
6. 逐项对照 `kit/adoption-checklist.md`。
|
||||
|
||||
参考 `examples/` 里填好的 `project.example.md` 与 `tasks.example.yaml`。
|
||||
|
||||
---
|
||||
|
||||
## 常用使用方法
|
||||
|
||||
### 开一个新需求（最常用）
|
||||
|
||||
你（强模型会话）就是 Coordinator(PM)。完整手册见 `core/kickoff.md`，开场指令：
|
||||
|
||||
```text
|
||||
我要做一个新需求：<一句话需求>。你作为 ack 的 Coordinator(PM)，按 docs/ack/kit/core 规范：
|
||||
先读 project.md 与 core/*；写产品文档到 docs/ 并把需求拆成带可观测验收信号的任务写进 docs/ack/tasks.yaml；
|
||||
先给我确认产品文档+任务拆分，再按 project.md 优先复用空闲 DEV/TEST worker，没有时才校验并创建，核对实际模型后循环派发/复测/终检；
|
||||
每个任务最多三轮，三轮不过记 leftover。
|
||||
```
|
||||
|
||||
### 复用或启动 worker
|
||||
|
||||
先按 `core/orca-adapter.md` §「解析并复用 worker」运行 `terminal list` 和活跃任务查询。只有没有同 worktree、同角色、配置兼容的空闲 worker 时，才执行下面的创建命令：
|
||||
|
||||
```bash
|
||||
DEV_CMD='codex --dangerously-bypass-approvals-and-sandbox -m gpt-5.6-terra -c model_reasoning_effort=medium'
|
||||
TEST_CMD='codex --dangerously-bypass-approvals-and-sandbox -m gpt-5.6-luna -c model_reasoning_effort=low'
|
||||
python3 docs/ack/validate_worker_command.py --role developer --command "$DEV_CMD"
|
||||
python3 docs/ack/validate_worker_command.py --role test --command "$TEST_CMD"
|
||||
orca terminal create --worktree active --command "$DEV_CMD" --title "ACK-DEV-CODEX-TERRA-1" --json
|
||||
orca terminal create --worktree active --command "$TEST_CMD" --title "ACK-TEST-CODEX-LUNA-1" --json
|
||||
|
||||
# Cursor worker 使用同一项目校验器
|
||||
CURSOR_CMD='cursor-agent --yolo --model auto'
|
||||
python3 docs/ack/validate_worker_command.py --role developer --command "$CURSOR_CMD"
|
||||
```
|
||||
|
||||
派发成功后把实际 handle 写入任务的 `dispatch.worker`，下次优先复用。需要隔离/并行时先建 worktree：`orca worktree create --name <feature> --base-branch <base> --json`（选择依据见 `core/closed-loop.md`）。
|
||||
|
||||
### 派发与等待（Orca）
|
||||
|
||||
```bash
|
||||
orca orchestration task-create --spec "<任务与验收>" --json
|
||||
orca orchestration dispatch --task <task_id> --to <dev_handle> --json
|
||||
orca orchestration check --terminal <coordinator_handle> --wait \
|
||||
--types worker_done,retest_result,escalation,decision_gate --timeout-ms 900000 --json
|
||||
```
|
||||
|
||||
不能 `--inject` 时手动投递 `core/prompt-templates.md` 的模板；命令细节见 `core/orca-adapter.md`。
|
||||
|
||||
### 校验任务板结构
|
||||
|
||||
```bash
|
||||
python3 docs/ack/kit/scripts/validate_tasks.py docs/ack/tasks.yaml
|
||||
```
|
||||
|
||||
### 只处理已有未通过项
|
||||
|
||||
用「默认口令」（见下）让 Coordinator 直接扫 `tasks.yaml` 里的 `open` / `failed_retest` 继续闭环。
|
||||
|
||||
### 速查：想做什么 → 看哪个文件
|
||||
|
||||
| 想做的事 | 文件 |
|
||||
|----------|------|
|
||||
| 开一个新需求怎么起步 | `core/kickoff.md` |
|
||||
| 角色/权限/状态机/完成定义 | `core/roles-and-permissions.md` |
|
||||
| 三角色各自该怎么做（规划/写测试/复测能力清单） | `core/roles-and-permissions.md` §三角色能力清单 |
|
||||
| 用哪个模型、怎么固定、何时升级 | `core/model-routing.md` |
|
||||
| 闭环步骤、手动模式、worktree 决策与对齐 | `core/closed-loop.md` |
|
||||
| 验收信号写法、三轮失败策略 | `core/optimization-method.md` |
|
||||
| 派发/复测/回报的 prompt 文案 | `core/prompt-templates.md` |
|
||||
| Orca 具体命令 | `core/orca-adapter.md` |
|
||||
| 让 Agent 在新项目初始化 ack | `init-new-project.md` |
|
||||
| 新项目接入步骤 | `adoption-checklist.md` |
|
||||
|
||||
---
|
||||
|
||||
## 默认口令
|
||||
|
||||
```text
|
||||
用三角色协作闭环处理 docs/ack/tasks.yaml 里的未通过项：Coordinator 派发给 Developer 修复，再交给 Test 独立复测并终检；每个问题最多修三轮，三轮仍不过就记录为遗留，然后继续下一个。
|
||||
```
|
||||
@@ -1 +0,0 @@
|
||||
0.8.1
|
||||
@@ -1,71 +0,0 @@
|
||||
# 接入清单
|
||||
|
||||
把本工具包引用/复制到新项目后，按此清单接入。术语与规则详见 `core/`。
|
||||
|
||||
## 1. 分发与版本
|
||||
|
||||
- [ ] 选定分发方式（README §「分发方式」A 单软链接 / B 复制）。
|
||||
- [ ] 在 `docs/ack/` 下建单软链接 `kit`（指向本框架）。
|
||||
- [ ] 覆盖层文件与 `tasks.yaml` 记录 `kitVersion`（对齐 `kit/VERSION`）。
|
||||
|
||||
## 2. 项目级规范（覆盖层）
|
||||
|
||||
- [ ] 由 `kit/templates/project.template.md` 生成覆盖层文件（默认 `docs/ack/project.md`，**不占用 `AGENTS.md`**）。
|
||||
- [ ] 在 `tasks.yaml` 的 `project.overlayFile` 记录覆盖层实际路径。
|
||||
- [ ] 覆盖层引用 `docs/ack/kit/core/`，不复制其内容。
|
||||
- [ ] 填清项目简介、技术栈、运行/构建/单测/集成测试命令。
|
||||
- [ ] 若要 Agent 自动加载覆盖层：在 `AGENTS.md` 加一行指向它，或直接命名为 `AGENTS.md`（可选）。
|
||||
|
||||
## 2b. 模型档位
|
||||
|
||||
- [ ] Coordinator 默认强模型且不亲自跑测试。
|
||||
- [ ] Test、Developer 默认中低模型。
|
||||
- [ ] 记录升级规则：三轮失败升级 Coordinator 复盘；复杂实现升级 Developer 档位（见 `kit/core/model-routing.md`）。
|
||||
|
||||
## 3. 路径权限
|
||||
|
||||
- [ ] 填实际的 Coordinator (PM) 可写路径（规格）。
|
||||
- [ ] 填实际的 Test 可写路径（集成测试、复测记录）。
|
||||
- [ ] 填实际的 Developer 可写路径（源码、单元测试、配置模板）。
|
||||
- [ ] 本地私有配置标记只读或不提交。
|
||||
- [ ] 确认 `tasks.yaml` 只有 Coordinator 写（见 `kit/core/roles-and-permissions.md`）。
|
||||
|
||||
## 4. 任务板
|
||||
|
||||
- [ ] 由 `kit/templates/tasks.template.yaml` 生成 `docs/ack/tasks.yaml`。
|
||||
- [ ] 替换 `<project_name>`、`<repo_path>`、`<base_url>`、`<dev_worktree>`、`overlayFile`。
|
||||
- [ ] 至少加一个真实任务，验收写成可观测信号（见 `kit/core/optimization-method.md` §1）。
|
||||
- [ ] 跑 `python3 docs/ack/kit/scripts/validate_tasks.py docs/ack/tasks.yaml` 通过。
|
||||
|
||||
## 5. 编排
|
||||
|
||||
- [ ] 决定用 Orca（`kit/core/orca-adapter.md`）还是手动模式（`kit/core/closed-loop.md`）。
|
||||
- [ ] Orca：`orca status`、`terminal list` 可用，Coordinator / Developer / Test 三个终端都在，回报能发回 Coordinator。
|
||||
- [ ] 派发前会先查空闲 worker：按 `ACK-<ROLE>-<CLI>-<TIER>-<N>` 复用同 worktree、同角色、同配置终端；仅在不存在或都 busy 时新建，并把实际 handle 写入 `dispatch.worker`。
|
||||
- [ ] 决定子任务放当前 worktree 起子 agent，还是新建隔离 worktree（决策速查见 `kit/core/closed-loop.md` §「子任务放哪」）。
|
||||
- [ ] 多 worktree 时确认 `tasks.yaml`（SSOT）只保留一个权威副本，由 Coordinator 单写。
|
||||
|
||||
## 6. 验证命令
|
||||
|
||||
- [ ] Test 有黑盒复测命令，Developer 有白盒验证命令。
|
||||
- [ ] 构建产物与服务启动命令写清。
|
||||
- [ ] 浏览器测试 `BASE_URL` 写清，复测前能确认服务来自正确 worktree。
|
||||
|
||||
## 7. 三轮失败策略
|
||||
|
||||
- [ ] 每个任务记录 `dispatch.rounds`。
|
||||
- [ ] 三轮失败标记 `leftover` 并填 `resolution.leftoverReason`。
|
||||
- [ ] `leftover` 不阻塞其它任务；最终报告列出所有 `leftover` 与最后失败证据。
|
||||
|
||||
## 8. 第一次试运行
|
||||
|
||||
选一个低风险 bug 跑完整闭环，结束后检查是否出现：
|
||||
|
||||
- Developer 修改了越权路径，或 Test 改了源码。
|
||||
- worker_done 或复测报告没有验证证据。
|
||||
- Test 复测到了旧服务。
|
||||
- Coordinator 没做终检就直接 verified。
|
||||
- 任务板字段不够记录失败原因。
|
||||
- 三轮失败策略没被执行。
|
||||
|
||||
把发现的问题回写到项目覆盖层文件；若属通用问题，回流到 kit 的 `kit/core/` 并升 `VERSION`。
|
||||
@@ -1,198 +0,0 @@
|
||||
# 闭环流程（稳定核心，编排无关）
|
||||
|
||||
本文件定义**与具体编排工具无关**的三角色协作闭环。运行时调度可以用 Orca（见 `orca-adapter.md`），也可以手动跑（见下方「手动模式」）。
|
||||
|
||||
原则：调度消息只是运行时载体，**所有结论都必须回写到 `tasks.yaml`**（事实源），不要把消息当最终记录。角色定义见 `roles-and-permissions.md`：Coordinator 只编排、Test 只验证、Developer 只实现。
|
||||
|
||||
---
|
||||
|
||||
## 编排抽象
|
||||
|
||||
无论用什么工具，闭环都由这几个能力组成。注意 `dispatch` 有两个目标（Developer 与 Test）：
|
||||
|
||||
| 抽象动作 | 含义 | Orca 实现 | 手动实现 |
|
||||
|----------|------|-----------|----------|
|
||||
| `prepare(task)` | Coordinator 把任务和验收信号写进 `tasks.yaml` | 同左 | 同左 |
|
||||
| `dispatch(task, developer)` | 把修复任务连同上下文交给 Developer | `orca orchestration dispatch` | 复制 prompt 到 Developer 终端/会话 |
|
||||
| `dispatch(task, test)` | 把复测任务连同验收信号交给 Test | `orca orchestration dispatch` | 复制 prompt 到 Test 终端/会话 |
|
||||
| `wait()` | 等待 `worker_done` / `retest_result` / `escalation` / `decision_gate` | `orca orchestration check --wait` | 人工等待回报 |
|
||||
| `gate(task)` | Coordinator 读 Test 证据并对齐原始意图（不重测） | 同左 | 同左 |
|
||||
| `writeback(task, result)` | Coordinator 把结果写回 `tasks.yaml` | 同左 | 同左 |
|
||||
|
||||
派发用的 prompt 见 `prompt-templates.md`。状态流转见 `roles-and-permissions.md` §「任务状态机」。**独立复测由 Test 执行，不是 Coordinator**；Coordinator 只做读证据的终检。
|
||||
|
||||
---
|
||||
|
||||
## 标准闭环
|
||||
|
||||
```text
|
||||
Coordinator 发现或读取 open 任务
|
||||
-> prepare：写/补全 tasks.yaml 验收信号
|
||||
-> 决定 worktree：当前 worktree 起子 agent，还是新建隔离 worktree（见下节「子任务放哪」）
|
||||
-> 解析 worker：先复用同 worktree、同角色的空闲 worker；没有可复用项时才校验命令并新建（见 orca-adapter.md）
|
||||
-> dispatch 给 Developer（--to <worker handle>）
|
||||
-> wait：Developer 的 worker_done / escalation
|
||||
-> writeback fixed_by_dev
|
||||
-> dispatch 给 Test（retesting）
|
||||
-> wait：Test 的 retest_result
|
||||
-> Test 通过：gate（Coordinator 读证据对齐意图）
|
||||
-> 通过 gate：writeback verified
|
||||
-> gate 不满足意图：writeback failed_retest，带意图差异再派发 Developer
|
||||
-> Test 失败：writeback failed_retest，追加证据，再派发 Developer（最多累计三轮）
|
||||
-> 累计三轮失败：writeback leftover，继续下一个任务
|
||||
```
|
||||
|
||||
一次派发只修一个明确问题（细则见 `optimization-method.md` §「每轮派发只修一个明确问题」）。
|
||||
「决定 worktree」「解析 worker」两步的决策见下节与 `model-routing.md` / `orca-adapter.md`。
|
||||
|
||||
---
|
||||
|
||||
## 子任务放哪：新 worktree 还是当前 worktree
|
||||
|
||||
Coordinator 派发前先决定 Developer/Test 在哪工作。两种方式：
|
||||
|
||||
**方式 1：当前 worktree 复用或起子 agent（终端）**
|
||||
|
||||
```bash
|
||||
# 先按 orca-adapter.md 的 worker 复用流程查找空闲终端；没有时才创建
|
||||
orca terminal create --worktree active --command "cursor-agent --yolo --model auto" --title "ACK-DEV-CURSOR-AUTO-1" --json
|
||||
```
|
||||
|
||||
- 适合：串行闭环、一次一个 Developer 任务、小改动、Test 要复测的正是 Developer 改的那棵树。
|
||||
- 优点：单一服务实例、无跨 worktree 对齐困扰、开销小。
|
||||
- 风险：多个 agent 同时改同一棵树会互相踩（半构建状态、git 冲突）。
|
||||
|
||||
**方式 2：新建隔离 worktree，再在其中起子 agent**
|
||||
|
||||
```bash
|
||||
orca worktree create --name <feature> --base-branch <base> --json
|
||||
# 然后先查该 worktree 的同角色空闲终端；没有时才创建
|
||||
orca terminal create --worktree path:<new> --command "cursor-agent --yolo --model auto" --title "ACK-DEV-CURSOR-AUTO-1"
|
||||
```
|
||||
|
||||
- 适合：并行多个互不依赖的子任务、大/高风险/实验性改动、要保持基线分支干净（如 prod 不动、feature 走独立分支）、要独立 build 或跑独立服务实例、best-of-N 尝试。
|
||||
- 优点：隔离 + 并行 + 易回滚（删 worktree 即可）。
|
||||
- 成本：各自 build/依赖、服务要用不同端口、必须处理下节的 worktree/服务对齐。
|
||||
|
||||
**决策速查：**
|
||||
|
||||
| 情况 | 选择 |
|
||||
|------|------|
|
||||
| 一次一个任务、串行修复 | 当前 worktree 子 agent |
|
||||
| 多个任务并行、互不依赖 | 每个任务一个新 worktree |
|
||||
| 高风险 / 实验 / 可能整体丢弃 | 新 worktree |
|
||||
| 要保持基线分支干净 | 新 worktree（feature 分支）|
|
||||
| 小改动、追求快 | 当前 worktree |
|
||||
|
||||
**任务板（SSOT）只落一处**：无论开几个 worktree，`tasks.yaml` 只认一个权威副本（通常在基线/协调所在 worktree），由 Coordinator 单写。不要每个 worktree 各留一份会分叉的任务板。模型固定方式见 `model-routing.md` 与 `orca-adapter.md`。
|
||||
|
||||
---
|
||||
|
||||
## 手动模式（无 Orca）
|
||||
|
||||
没有编排工具时，闭环不变，只是 `dispatch` / `wait` 由人工承担：
|
||||
|
||||
1. Coordinator 在 `tasks.yaml` 写好任务和验收信号。
|
||||
2. 用 `prompt-templates.md` §1 的初始派发模板生成 prompt，手动发给 Developer（另一个会话/终端/人）。
|
||||
3. Developer 完成后按 worker_done 模板回报。
|
||||
4. Coordinator 写回 `fixed_by_dev`，用 `prompt-templates.md` §3 的复测派发模板把任务发给 Test。
|
||||
5. Test 独立复测后按复测报告模板回报证据。
|
||||
6. Coordinator 做终检并回写 `tasks.yaml`：通过 `verified`，不过 `failed_retest`。
|
||||
7. 失败则用「复测失败再派发模板」重新发给 Developer，最多累计三轮。
|
||||
|
||||
手动模式下同样遵守：worker_done / 复测报告都不等于最终结论、只有 Coordinator 写 `tasks.yaml`、三轮失败留档。
|
||||
|
||||
---
|
||||
|
||||
## Test 复测（编排无关）
|
||||
|
||||
即使 Developer 的 worker_done 写了"全部通过"，Test 仍必须独立复测：
|
||||
|
||||
```bash
|
||||
git status --short
|
||||
<test_commands>
|
||||
curl -s <base_url>/health-or-summary
|
||||
```
|
||||
|
||||
浏览器复测建议记录：
|
||||
|
||||
```text
|
||||
BASE_URL:
|
||||
page:
|
||||
steps:
|
||||
expected:
|
||||
actual:
|
||||
snapshot evidence:
|
||||
```
|
||||
|
||||
Test 只回传证据，不写 `tasks.yaml`；由 Coordinator 落盘。
|
||||
|
||||
---
|
||||
|
||||
## Coordinator 终检（gate）
|
||||
|
||||
Test 报通过后，Coordinator 不重测，而是做一次读证据的终检：
|
||||
|
||||
- Test 证据是否覆盖了任务的**每一条**验收信号（见 `optimization-method.md` §1）。
|
||||
- 结果是否符合任务的**原始意图**，而不只是通过了字面文案。
|
||||
- 运行环境是否对齐（见下方「服务与 worktree 对齐」）。
|
||||
|
||||
终检不通过（例如意图漂移、验收信号写漏）时，回写 `failed_retest` 并把意图差异带给下一轮 Developer，必要时先补全验收信号。
|
||||
|
||||
---
|
||||
|
||||
## 服务与 worktree 对齐（防假通过/假失败）
|
||||
|
||||
Test 复测前记录运行环境：
|
||||
|
||||
```bash
|
||||
pwd
|
||||
git rev-parse --abbrev-ref HEAD
|
||||
git rev-parse --short HEAD
|
||||
```
|
||||
|
||||
```text
|
||||
serverPid:
|
||||
serverCommand:
|
||||
BASE_URL:
|
||||
frontendDir:
|
||||
worktreePath:
|
||||
```
|
||||
|
||||
如果开发在 `<dev_worktree>` 修复，但服务跑的是另一个 worktree，必须**停止并重启正确服务**后再测。长跑服务或静态前端尤其要确认加载的是最新构建产物。
|
||||
|
||||
---
|
||||
|
||||
## 结果回写
|
||||
|
||||
Coordinator 回写 `tasks.yaml` 时按状态填写（字段结构见 `templates/tasks.schema.json`）：
|
||||
|
||||
```yaml
|
||||
# 通过（Test 复测 + Coordinator 终检）
|
||||
status: verified
|
||||
resolution:
|
||||
verifiedAt: "<timestamp>"
|
||||
verifiedBy: "test"
|
||||
evidence:
|
||||
verification: "<commands passed>"
|
||||
browser: "<snapshot or API evidence>"
|
||||
```
|
||||
|
||||
```yaml
|
||||
# 失败但未满三轮
|
||||
status: failed_retest
|
||||
dispatch:
|
||||
rounds:
|
||||
- round: 1
|
||||
result: failed
|
||||
evidence: "<latest evidence from Test or gate>"
|
||||
```
|
||||
|
||||
```yaml
|
||||
# 累计三轮失败
|
||||
status: leftover
|
||||
resolution:
|
||||
leftoverReason: "failed after 3 supervised developer rounds"
|
||||
evidence:
|
||||
final: "<latest failing evidence>"
|
||||
```
|
||||
@@ -1,97 +0,0 @@
|
||||
# 如何开始一个需求（Kickoff）
|
||||
|
||||
从零开一个需求的启动手册。角色/权限见 `roles-and-permissions.md`，闭环见 `closed-loop.md`，模型见 `model-routing.md`。
|
||||
|
||||
---
|
||||
|
||||
## 前提：谁是 Coordinator
|
||||
|
||||
**你（发起编排的强模型会话）就是 Coordinator (PM) / 产品。** 你负责写文档、拆任务、编排、终检，**不亲自写代码、不亲自跑测试**。开发和测试是另起的 worker agent；具体 CLI、模型、reasoning effort 和执行模式必须先读项目覆盖层 `docs/ack/project.md`，禁止照抄未核对的默认命令。
|
||||
|
||||
---
|
||||
|
||||
## 第 0 步：给 Coordinator 的开场指令（复制改需求）
|
||||
|
||||
```text
|
||||
我要做一个新需求：<一句话需求>。
|
||||
你作为 ack 的 Coordinator(PM)，按 docs/ack/kit/core 的规范执行：
|
||||
|
||||
1. 先读 docs/ack/project.md、docs/ack/kit/core/roles-and-permissions.md、closed-loop.md、optimization-method.md。
|
||||
2. 写产品文档到 docs/（PRD / 交互 / 验收），把需求拆成任务，每个任务的验收写成可观测信号（可见文本 / API 结果 / 交互结果）。
|
||||
3. 把任务写进 docs/ack/tasks.yaml（只有你写），跑 validate 校验结构。
|
||||
4. 先把「产品文档 + 任务拆分 + 验收信号」给我确认，不要急着派发。
|
||||
5. 我确认后，按 ack 闭环循环：先按 docs/ack/project.md 校验 Developer/Test worker 启动命令，
|
||||
dispatch 开发 → worker_done → dispatch 测试独立复测 → 你读证据终检 → 回写 tasks.yaml；
|
||||
每个任务最多三轮，三轮不过记 leftover 并升级我复盘。
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 第 1 步：Coordinator 产出（确认前）
|
||||
|
||||
1. 产品文档 → `docs/PRD-<feature>.md` 等（Coordinator R/W）。
|
||||
2. 任务板 → `docs/ack/tasks.yaml`，每条任务带 `expected` + `verification`，验收写成可观测信号（见 `optimization-method.md` §1）。
|
||||
3. 校验结构：
|
||||
|
||||
```bash
|
||||
python3 docs/ack/kit/scripts/validate_tasks.py docs/ack/tasks.yaml
|
||||
```
|
||||
|
||||
4. **停下来给人确认**——这是强模型该花时间的地方，不要跳过。
|
||||
|
||||
---
|
||||
|
||||
## 第 2 步：决定 worktree
|
||||
|
||||
见 `closed-loop.md` §「子任务放哪」：
|
||||
|
||||
- 需求大 / 要并行 / 要保基线分支干净 → 新建隔离 worktree。
|
||||
- 小改动 / 串行修复 → 当前 worktree 起子 agent。
|
||||
|
||||
---
|
||||
|
||||
## 第 3 步：复用或启动 worker
|
||||
|
||||
先读 `docs/ack/project.md` 的项目覆盖规则，再按 `orca-adapter.md` §「解析并复用 worker」执行：先列出现有终端和活跃任务，优先复用同 worktree、同角色、配置兼容且空闲的 worker。只有没有可复用项时才创建新终端；如果项目提供 `validate_worker_command.py`，校验未通过时不得创建。
|
||||
|
||||
```bash
|
||||
# Codex 示例（模型与执行模式以项目覆盖层为准）
|
||||
DEV_CMD='codex --dangerously-bypass-approvals-and-sandbox -m gpt-5.6-terra -c model_reasoning_effort=medium'
|
||||
TEST_CMD='codex --dangerously-bypass-approvals-and-sandbox -m gpt-5.6-luna -c model_reasoning_effort=low'
|
||||
python3 docs/ack/validate_worker_command.py --role developer --command "$DEV_CMD"
|
||||
python3 docs/ack/validate_worker_command.py --role test --command "$TEST_CMD"
|
||||
orca terminal create --worktree active --command "$DEV_CMD" --title "ACK-DEV-CODEX-TERRA-1" --json
|
||||
orca terminal create --worktree active --command "$TEST_CMD" --title "ACK-TEST-CODEX-LUNA-1" --json
|
||||
|
||||
# Cursor 示例
|
||||
CURSOR_CMD='cursor-agent --yolo --model auto'
|
||||
python3 docs/ack/validate_worker_command.py --role developer --command "$CURSOR_CMD"
|
||||
orca terminal create --worktree active --command "$CURSOR_CMD" --title "ACK-DEV-CURSOR-AUTO-1" --json
|
||||
```
|
||||
|
||||
上面的 `terminal create` 都是“没有空闲兼容 worker”时的兜底，不是每次 kickoff 的固定动作。新 worktree 时先 `orca worktree create --name <feature> --base-branch <base>`，再解析该 worktree 的 worker。选型与升级见 `model-routing.md`。新建终端后、dispatch 前必须读取启动信息，确认实际 CLI、模型和 reasoning effort；派发后把实际 handle 写入对应任务的 `dispatch.worker`。
|
||||
|
||||
---
|
||||
|
||||
## 第 4 步：跑闭环（每个任务）
|
||||
|
||||
```text
|
||||
task-create → dispatch 给 DEV → 等 worker_done
|
||||
→ 回写 fixed_by_dev → dispatch 给 TEST 复测 → 等 retest_result
|
||||
→ Coordinator 读证据终检 → 过则 verified，不过则 failed_retest 再派 DEV（最多累计 3 轮）
|
||||
→ 三轮失败：leftover，升级复盘，继续下一个
|
||||
```
|
||||
|
||||
具体命令见 `orca-adapter.md`（Orca）或 `closed-loop.md` §「手动模式」（无 Orca）；派发文案见 `prompt-templates.md`。
|
||||
|
||||
---
|
||||
|
||||
## 第 5 步：收尾
|
||||
|
||||
一轮结束时 Coordinator 必须能回答 `optimization-method.md` §「结束条件」的问题：哪些 verified、哪些 leftover、各失败几轮、工作树是否干净、还有没有未处理项。
|
||||
|
||||
---
|
||||
|
||||
## 一句话
|
||||
|
||||
产品文档 + 验收信号写在前（你，强模型）→ 按项目覆盖层校验并启动 DEV/TEST → 核对实际模型 → dispatch / 复测 / 终检循环 → 结论只落 `tasks.yaml`。
|
||||
@@ -1,122 +0,0 @@
|
||||
# 模型路由（稳定核心）
|
||||
|
||||
本文件是**三角色默认模型档位**和**升级规则**的单一事实源（SSOT）。目标：在不牺牲质量的前提下降低 token 和模型成本——把昂贵的强模型留给需要判断的工作，把机械执行交给较弱模型。
|
||||
|
||||
角色定义见 `roles-and-permissions.md`（Coordinator 编排 / Test 验证 / Developer 实现）。本文件只补一层正交的「用哪个档位的模型」。
|
||||
|
||||
---
|
||||
|
||||
## 默认档位
|
||||
|
||||
| 角色 | 默认模型档位 | 理由 |
|
||||
|------|--------------|------|
|
||||
| Coordinator (PM) | 强模型 | 需求拆解、验收信号设计、优先级、终检对齐意图、三轮失败复盘都需要高质量推理 |
|
||||
| Test | 中低模型 | 按既定验收信号执行浏览器/API/脚本，主要做观察、记录、逐条 pass/fail |
|
||||
| Developer | 中低模型（按任务升级） | 多数实现可照规格执行；跨系统、数据迁移、重复失败时再升级 |
|
||||
|
||||
关键点：Coordinator 用强模型但**不亲自跑测试**（测试由 Test 承担），所以强模型的 token 花在思考和终检上，而不是反复点击页面、跑 smoke、复制日志。这一分工天然省 token，同时保持「验证者 ≠ 实现者」。
|
||||
|
||||
---
|
||||
|
||||
## 什么时候用强模型
|
||||
|
||||
- 新需求理解、产品取舍、范围决策。
|
||||
- 架构与数据模型决策。
|
||||
- 把验收写成可观测信号（见 `optimization-method.md` §1）。
|
||||
- 需求含糊、规格与实现/测试冲突时的裁决。
|
||||
- Coordinator 终检：读证据、对齐原始意图。
|
||||
- 重复失败后的根因复盘与重新拆分。
|
||||
|
||||
## 什么时候用中低模型
|
||||
|
||||
- Test：跑浏览器用例、API smoke、逐条比对期望与实际、产出证据。
|
||||
- Developer：从清晰规格实现范围明确的任务、跑构建与单测、回报 worker_done。
|
||||
|
||||
---
|
||||
|
||||
## 升级规则
|
||||
|
||||
**升级到 Coordinator（强模型）复盘**，当：
|
||||
|
||||
- 同一验收路径 Developer 连续失败三轮（见 `optimization-method.md` §4）。
|
||||
- Test 两次仍无法给出清晰失败证据。
|
||||
- 任务需要改动产品范围或验收标准。
|
||||
- 修复涉及持久化数据、破坏性文件操作、安全或回滚。
|
||||
- 规格、测试、实现三者出现冲突。
|
||||
|
||||
**升级 Developer 模型档位**，当：
|
||||
|
||||
- 任务横跨多个子系统。
|
||||
- 改动涉及数据模型或迁移。
|
||||
- 需要设计新的抽象。
|
||||
- 低档位反复产出表面修复。
|
||||
|
||||
升级动作本身由 Coordinator 判断并记录（可写进 `tasks.yaml` 的 `dispatch` 备注或 `resolution`）。
|
||||
|
||||
---
|
||||
|
||||
## 如何给 worker 指定模型（编排相关）
|
||||
|
||||
**模型不由编排层设置。** Orca 的 `orchestration task-create` / `dispatch` 没有 `--model` 参数——`dispatch` 只是把任务投递给一个已存在的终端 handle。**模型在创建 worker 终端、启动 agent CLI 时用 CLI 自带的 flag 固定**，之后该终端的所有 dispatch 都用这个模型。
|
||||
|
||||
**默认不跨 Agent CLI 创建 worker。** Coordinator 应按自己所在的运行环境选择同类 worker：Cursor 会话创建 `cursor-agent` worker，Codex 会话创建 `codex` worker。不要依赖 Coordinator 凭模型回答来猜测运行环境或精确模型名；以实际 CLI / 终端环境为准。只有项目 overlay 或用户明确指定跨 Agent 时，才混用不同 CLI，并记录原因。
|
||||
|
||||
因此「档位 → 具体模型」的映射是 **agent 相关** 的，落地方式见 `orca-adapter.md` §「给 worker 终端固定模型」。常见 CLI：
|
||||
|
||||
| Agent CLI | 指定模型的方式 |
|
||||
|-----------|----------------|
|
||||
| Cursor (`cursor-agent`) | `cursor-agent --model <model>`；`--model auto` 让 Cursor 自动选（推荐给 Test/Developer worker） |
|
||||
| Codex (`codex`) | `codex -m <model> -c model_reasoning_effort=<effort>` |
|
||||
| 其它（opencode 等） | 用各自 CLI 的模型参数或配置 |
|
||||
|
||||
执行模式也必须在创建 worker 时固定，并服从项目覆盖层或用户的明确要求。Cursor 的 YOLO 参数是 `--yolo`；Codex 的等价参数是 `--dangerously-bypass-approvals-and-sandbox`。不要把 Cursor 的 `--yolo` 原样传给 Codex，也不要把裸启动 `codex` 当作“自动选择了正确角色模型”。如果项目提供 worker 命令校验脚本，校验通过是 `terminal create` 的前置条件。
|
||||
|
||||
**本 kit 对 Cursor 的默认建议**：Test 与 Developer worker 用 `cursor-agent --yolo --model auto`（自动选型，天然偏向高效模型，符合"中低档位"意图，并按当前项目授权启用 YOLO）；需要更强时改成具体强模型并保留 `--yolo`。Coordinator 作为强模型脑，通常就是发起编排的那个会话本身。
|
||||
|
||||
### Codex 默认映射
|
||||
|
||||
| 角色 | 模型 | reasoning effort |
|
||||
|------|------|------------------|
|
||||
| Coordinator (PM) | `gpt-5.6-sol` | `high` |
|
||||
| Developer | `gpt-5.6-terra` | `medium` |
|
||||
| Test | `gpt-5.6-luna` | `low` |
|
||||
| Developer 升级 | `gpt-5.6-sol` | `high`；极复杂任务可用 `xhigh` |
|
||||
|
||||
Codex worker 应明确指定模型和 reasoning effort，不把“未指定模型”当作 Cursor `auto` 的等价物。Codex 未指定模型时使用产品推荐模型，但推荐值可能随版本更新，也不保证符合 Test / Developer 的成本档位。具体模型若失效或被弃用，应保持上面的角色档位不变，只更新本映射；项目也可在 overlay 中覆盖映射。
|
||||
|
||||
### Worker 固定启动命令
|
||||
|
||||
以下是 core 的默认完整命令。Developer/Test worker 禁止裸启动；必须同时固定 Agent CLI、角色模型和执行模式。
|
||||
|
||||
| Agent CLI | 角色 | 完整启动命令 |
|
||||
|-----------|------|--------------|
|
||||
| Codex | Developer | `codex --dangerously-bypass-approvals-and-sandbox -m gpt-5.6-terra -c model_reasoning_effort=medium` |
|
||||
| Codex | Test | `codex --dangerously-bypass-approvals-and-sandbox -m gpt-5.6-luna -c model_reasoning_effort=low` |
|
||||
| Codex | Developer 升级 | `codex --dangerously-bypass-approvals-and-sandbox -m gpt-5.6-sol -c model_reasoning_effort=high` |
|
||||
| Cursor | Developer / Test | `cursor-agent --yolo --model auto` |
|
||||
|
||||
硬规则：
|
||||
|
||||
1. Codex worker 必须带 `--dangerously-bypass-approvals-and-sandbox`；Cursor worker 必须带 `--yolo`。
|
||||
2. 禁止用裸 `codex`、裸 `cursor-agent` 或只指定 CLI 而不指定角色模型。
|
||||
3. 创建终端前先运行项目提供的 worker 命令校验器；校验失败时不得执行 `orca terminal create`。
|
||||
4. 创建终端后、dispatch 前读取启动信息，确认实际 CLI、模型和 reasoning effort 与命令一致。
|
||||
5. Developer 升级到强模型必须由 Coordinator 记录原因；Test 不得复用 Developer 的强模型终端。
|
||||
6. YOLO 会跳过确认和沙箱，只能在用户已明确授权、外层运行环境受控时启用；项目覆盖层可以收紧执行模式，不能静默放宽。
|
||||
|
||||
项目可以覆盖模型名称或收紧权限，但必须在 `project.md` 中写出完整替代命令，不能只写“auto”“默认模型”或依赖当前 CLI 的隐式默认值。
|
||||
|
||||
---
|
||||
|
||||
## 成本原则
|
||||
|
||||
强模型产出高密度、可复用的产物：需求、架构决策、验收信号、任务拆分、失败复盘。
|
||||
中低模型消费这些产物，产出可核对的执行证据：测试结果、快照、API 响应、构建日志、改动文件清单。
|
||||
|
||||
这样把昂贵推理挡在重复执行之外。
|
||||
|
||||
---
|
||||
|
||||
## 一句话
|
||||
|
||||
Coordinator 是脑，Test 是眼，Developer 是手。脑用最强的模型且不做机械测试，眼和手用便宜模型，只有常规闭环卡住时才升级。
|
||||
@@ -1,243 +0,0 @@
|
||||
# Orca 适配器（稳定核心，一种编排实现）
|
||||
|
||||
Orca orchestration 是运行时调度层的一种实现。闭环流程本身与工具无关（见 `closed-loop.md`）；本文件只提供 Orca 的具体命令。没有 Orca 时用 `closed-loop.md` §「手动模式」。
|
||||
|
||||
所有结论仍以 `tasks.yaml` 为准，Orca 消息不是最终记录。
|
||||
|
||||
---
|
||||
|
||||
## 何时用 Orca 编排
|
||||
|
||||
用：需要监督、等待结果、闭环修复、三轮重试；有多个可独立派发的任务；需要 `worker_done` 后再复测。
|
||||
|
||||
不用：单次问答；用户只要求完整 handoff 不需监督；不需要复测的小改动。
|
||||
|
||||
---
|
||||
|
||||
## 运行前检查
|
||||
|
||||
```bash
|
||||
orca status --json
|
||||
orca terminal list --json
|
||||
orca orchestration task-list --json
|
||||
orca orchestration inbox --limit 20 --json
|
||||
```
|
||||
|
||||
确认：Orca runtime 可达；Coordinator、Developer、Test 三个终端都存在；Developer 在正确 worktree；当前没有冲突的活跃编排任务。
|
||||
|
||||
---
|
||||
|
||||
## 解析并复用 worker
|
||||
|
||||
**默认复用，创建是兜底。** 每次向 Developer 或 Test 派发前都先解析 worker，不能直接照后文示例执行 `terminal create`：
|
||||
|
||||
1. 运行 `orca terminal list --json`，筛选 `connected=true`、`writable=true`、目标 `worktreePath` 一致、标题角色和配置一致的终端。稳定标题使用 `ACK-<ROLE>-<CLI>-<TIER>-<N>`，例如 `ACK-DEV-CODEX-TERRA-1`、`ACK-TEST-CODEX-LUNA-1`、`ACK-DEV-CURSOR-AUTO-1`；强档示例为 `ACK-DEV-CODEX-SOL-1`。
|
||||
2. 运行 `orca orchestration task-list --status dispatched --json`。若候选 handle 出现在活跃任务的 `assignee_handle`，视为 busy，不复用；不要仅凭终端预览文本或最近输出时间猜忙闲。
|
||||
3. 对空闲候选运行 `orca terminal show --terminal <handle> --json`，确认仍存活且 worktree、角色和 Agent CLI / 模型档位符合本次要求。符合就直接把该 handle 作为 `dispatch --to` 的目标。
|
||||
4. 只有不存在兼容的空闲候选时才创建。若同角色同配置已有 busy worker，使用下一个未占用序号，例如 `ACK-DEV-CODEX-TERRA-2`；不要创建另一个同名终端。
|
||||
5. dispatch 成功后，把实际 handle 写入对应 `tasks.yaml` 条目的 `dispatch.worker`。下一轮先尝试该 handle；若它已消失、断开、不可写、worktree/角色/档位不兼容或正忙，再回到第 1 步选择其它 worker。
|
||||
|
||||
`tasks.yaml.dispatch.worker` 记录“这个任务实际用了谁”，便于续跑和审计；`orca terminal list` 记录“谁现在还活着”，是运行时存活状态的事实源。不要另建一份永久 worker 池，因为终端关闭后其中的 handle 会过期。
|
||||
|
||||
复用决策：
|
||||
|
||||
| 情况 | 动作 |
|
||||
|------|------|
|
||||
| 任务已记录 worker，且该 handle 存活、兼容、空闲 | 优先复用原 handle |
|
||||
| 有其它同 worktree、同角色、兼容的空闲 worker | 复用该 handle |
|
||||
| 同角色 worker 存在但都 busy | 创建下一编号的临时并发 worker |
|
||||
| worker 已关闭、断开或不存在 | 创建新 worker |
|
||||
| 模型升级或 worktree 不同 | 不复用不兼容 worker，创建对应档位/路径的新 worker |
|
||||
|
||||
---
|
||||
|
||||
## 给 worker 终端固定模型
|
||||
|
||||
**编排层不设模型。** `task-create` / `dispatch` 都没有 `--model`；`dispatch --to <handle>` 只是把任务投给一个已存在的终端，用的是那个终端里 agent 会话启动时的模型。要固定模型，就在 **创建 worker 终端** 时用 agent CLI 的模型参数：
|
||||
|
||||
默认沿用 Coordinator 当前所在的 Agent CLI：Cursor Coordinator 创建 Cursor worker，Codex Coordinator 创建 Codex worker。不要通过询问模型来猜运行环境；以当前 CLI / 终端环境为准。除非项目 overlay 或用户明确指定，否则不跨 Agent CLI 创建 worker。
|
||||
|
||||
```bash
|
||||
# Cursor：Test / Developer worker 用 auto 模型，并按项目要求启用 YOLO
|
||||
orca terminal create --worktree path:<dev_worktree> \
|
||||
--command "cursor-agent --yolo --model auto" --title "ACK-DEV-CURSOR-AUTO-1" --json
|
||||
|
||||
# 需要更强模型时改成具体模型
|
||||
orca terminal create --worktree path:<dev_worktree> \
|
||||
--command "cursor-agent --yolo --model claude-opus-4-8-thinking-high" --title "ACK-DEV-CURSOR-STRONG-1" --json
|
||||
|
||||
# Codex：Developer worker
|
||||
orca terminal create --worktree path:<dev_worktree> \
|
||||
--command "codex --dangerously-bypass-approvals-and-sandbox -m gpt-5.6-terra -c model_reasoning_effort=medium" \
|
||||
--title "ACK-DEV-CODEX-TERRA-1" --json
|
||||
|
||||
# Codex：Test worker
|
||||
orca terminal create --worktree path:<test_worktree> \
|
||||
--command "codex --dangerously-bypass-approvals-and-sandbox -m gpt-5.6-luna -c model_reasoning_effort=low" \
|
||||
--title "ACK-TEST-CODEX-LUNA-1" --json
|
||||
|
||||
# Codex：复杂 Developer 任务升级
|
||||
orca terminal create --worktree path:<dev_worktree> \
|
||||
--command "codex --dangerously-bypass-approvals-and-sandbox -m gpt-5.6-sol -c model_reasoning_effort=high" \
|
||||
--title "ACK-DEV-CODEX-SOL-1" --json
|
||||
```
|
||||
|
||||
这些创建命令只在复用流程找不到空闲兼容 worker 时执行。拿到返回的 handle 后再 `task-create` + `dispatch --to <handle>`，并把 handle 写入 `tasks.yaml` 的 `dispatch.worker`。模型档位与选型策略见 `model-routing.md`。
|
||||
|
||||
需要隔离/并行时，先建新 worktree 再在其中起 worker（是否新建见 `closed-loop.md` §「子任务放哪」）：
|
||||
|
||||
```bash
|
||||
orca worktree create --name <feature> --base-branch <base> --json
|
||||
orca terminal create --worktree path:<new_worktree> --command "cursor-agent --yolo --model auto" --title "ACK-DEV-CURSOR-AUTO-1" --json
|
||||
```
|
||||
|
||||
- `cursor-agent --list-models` 可列出合法模型；`auto` 表示由 Cursor 自动选型。
|
||||
- Codex 用 `-m / --model` 指定模型，用 `-c model_reasoning_effort=<effort>` 固定推理档位；不要把省略 `-m` 当作 Cursor `auto` 的等价物。
|
||||
- 本项目要求 Cursor worker 带 `--yolo`，Codex worker 带 `--dangerously-bypass-approvals-and-sandbox`；创建前先运行项目覆盖层指定的校验器。
|
||||
- 其它 CLI（opencode 等）用各自的模型参数或配置，`--command` 相应替换。
|
||||
- 若 worker 是已在跑的会话（用 `--inject` 投递），模型已由该会话启动时决定，无法在 dispatch 时改；要换模型需新建终端。
|
||||
|
||||
---
|
||||
|
||||
## 创建父任务
|
||||
|
||||
```bash
|
||||
orca orchestration task-create --spec "$(cat <<'EOF'
|
||||
Goal: Complete <release_or_feature> with supervised Coordinator -> Developer -> Test loop.
|
||||
|
||||
Coordinator (PM): owns task board, decomposition, dispatch, and final gate (reads Test evidence, does not test).
|
||||
Developer: owns implementation and white-box verification.
|
||||
Test: owns independent black-box retest and evidence (verifier != implementer).
|
||||
|
||||
Policy:
|
||||
- Each issue can be dispatched at most 3 rounds.
|
||||
- If still failing after 3 rounds, record as leftover and continue next issue.
|
||||
- worker_done and retest reports are not final completion; only Coordinator writes tasks.yaml.
|
||||
EOF
|
||||
)" --json
|
||||
```
|
||||
|
||||
## 创建子任务
|
||||
|
||||
```bash
|
||||
orca orchestration task-create --parent <parent_task_id> --spec "$(cat <<'EOF'
|
||||
Fix <task_id>: <title>
|
||||
|
||||
Repository:
|
||||
- Path: <repo_path>
|
||||
- Worktree: <dev_worktree>
|
||||
|
||||
Read: <overlay_file> (project overlay), tasks.yaml, <relevant_spec_or_test_doc>
|
||||
Failure evidence: <copy latest Test evidence>
|
||||
Acceptance: <copy expected behavior + verification commands>
|
||||
|
||||
Constraints:
|
||||
- Follow the overlay file path scope.
|
||||
- Do not write tasks.yaml, do not mark verified.
|
||||
- Do not commit or push unless user asks.
|
||||
EOF
|
||||
)" --json
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 派发给 Developer Worker
|
||||
|
||||
终端是 Orca 可识别的 Agent CLI 时：
|
||||
|
||||
```bash
|
||||
orca orchestration dispatch --task <task_id> --to <developer_handle> --inject --json
|
||||
```
|
||||
|
||||
不能 `--inject` 时，先登记 dispatch，再手动投递 `prompt-templates.md` §1 的初始派发 prompt：
|
||||
|
||||
```bash
|
||||
orca orchestration dispatch --task <task_id> --to <developer_handle> --json
|
||||
orca terminal send --terminal <developer_handle> --text "$(cat <<'EOF'
|
||||
<粘贴 prompt-templates.md §1 初始派发模板，已填占位符>
|
||||
EOF
|
||||
)" --enter --json
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 派发给 Test 复测
|
||||
|
||||
Developer 回报 worker_done、Coordinator 写回 `fixed_by_dev` 后，把复测任务发给 Test：
|
||||
|
||||
```bash
|
||||
orca orchestration dispatch --task <task_id> --to <test_handle> --inject --json
|
||||
```
|
||||
|
||||
不能 `--inject` 时，先登记再手动投递 `prompt-templates.md` §3 的复测派发 prompt：
|
||||
|
||||
```bash
|
||||
orca orchestration dispatch --task <task_id> --to <test_handle> --json
|
||||
orca terminal send --terminal <test_handle> --text "$(cat <<'EOF'
|
||||
<粘贴 prompt-templates.md §3 复测派发模板，已填占位符>
|
||||
EOF
|
||||
)" --enter --json
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 等待结果
|
||||
|
||||
```bash
|
||||
orca orchestration check \
|
||||
--terminal <coordinator_handle> \
|
||||
--wait \
|
||||
--types worker_done,retest_result,escalation,decision_gate \
|
||||
--timeout-ms 900000 \
|
||||
--json
|
||||
```
|
||||
|
||||
等待超时不等于失败。长任务可继续等待，或检查 worker 终端活性。`worker_done` 来自 Developer，`retest_result`（无该类型时用 `worker_done` + subject 区分）来自 Test。
|
||||
|
||||
---
|
||||
|
||||
## Developer 回报 worker_done
|
||||
|
||||
字段含义见 `prompt-templates.md` §3：
|
||||
|
||||
```bash
|
||||
orca orchestration send \
|
||||
--to <coordinator_handle> \
|
||||
--type worker_done \
|
||||
--subject "<task_id> fix ready round <n>" \
|
||||
--body "<修了什么。跑了哪些验证。如何复现。还有什么风险。>" \
|
||||
--payload '{
|
||||
"taskId": "<orca_task_id>",
|
||||
"dispatchId": "<orca_dispatch_id>",
|
||||
"filesModified": ["<file_a>", "<file_b>"],
|
||||
"verification": ["<command_a>: passed", "<command_b>: passed"],
|
||||
"risk": "<remaining risk or none>"
|
||||
}' \
|
||||
--json
|
||||
```
|
||||
|
||||
收到 worker_done 后，Coordinator 写回 `fixed_by_dev`，再按上文派发给 Test 复测。
|
||||
|
||||
---
|
||||
|
||||
## Test 回报复测结果
|
||||
|
||||
字段含义见 `prompt-templates.md` §5：
|
||||
|
||||
```bash
|
||||
orca orchestration send \
|
||||
--to <coordinator_handle> \
|
||||
--type retest_result \
|
||||
--subject "<task_id> retest round <n>" \
|
||||
--body "<逐条验收信号结论 + 实际观察 + 证据>" \
|
||||
--payload '{
|
||||
"taskId": "<orca_task_id>",
|
||||
"dispatchId": "<orca_dispatch_id>",
|
||||
"env": {"worktree": "<path>", "branch": "<branch>", "commit": "<sha>", "baseUrl": "<base_url>"},
|
||||
"signals": ["<signal 1>: pass", "<signal 2>: fail (<evidence>)"],
|
||||
"conclusion": "all-signals-pass | signals-failed"
|
||||
}' \
|
||||
--json
|
||||
```
|
||||
|
||||
无 `retest_result` 类型时用 `--type worker_done`，靠 subject `retest round <n>` 区分。收到复测结果后，Coordinator 按 `closed-loop.md` 做终检并回写 `tasks.yaml`：通过 `verified`，不过 `failed_retest`。
|
||||
@@ -1,79 +0,0 @@
|
||||
# notes-web Agent 协作协议（示例，项目覆盖层）
|
||||
|
||||
> 本项目基于 ack v0.8.1。
|
||||
> 稳定规范引用 `docs/ack/kit/core/`，本文件只填项目差异。
|
||||
> 覆盖层文件放在 `docs/ack/project.md`，不占用 `AGENTS.md`。
|
||||
> 目录下只有一个软链接 `kit/` + `project.md` + `tasks.yaml`。
|
||||
|
||||
## 项目概览
|
||||
|
||||
- 项目：`notes-web`
|
||||
- 技术栈：`TypeScript + React (Vite) + Go`
|
||||
- 运行命令：`npm run dev`（前端）、`go run ./server`（后端）
|
||||
- Base URL：`http://localhost:5173`
|
||||
- 任务板：`docs/ack/tasks.yaml`
|
||||
- 覆盖层文件：`docs/ack/project.md`
|
||||
|
||||
## 稳定规范（引用，不重复）
|
||||
|
||||
- 开始一个需求（启动手册）：`docs/ack/kit/core/kickoff.md`
|
||||
- 角色 / 权限 / 状态机 / 完成定义：`docs/ack/kit/core/roles-and-permissions.md`
|
||||
- 模型档位与升级规则：`docs/ack/kit/core/model-routing.md`
|
||||
- 闭环流程（含手动模式、worktree 对齐）：`docs/ack/kit/core/closed-loop.md`
|
||||
- 优化方法（验收信号、三轮策略）：`docs/ack/kit/core/optimization-method.md`
|
||||
- 派发 prompt 模板：`docs/ack/kit/core/prompt-templates.md`
|
||||
- Orca 编排命令：`docs/ack/kit/core/orca-adapter.md`
|
||||
|
||||
## 模型档位
|
||||
|
||||
| 角色 | 默认档位 | 本项目实际 |
|
||||
|------|----------|------------|
|
||||
| Coordinator (PM) | 强模型 | claude-sonnet-5-thinking-high |
|
||||
| Test | 中低模型 | 默认（中低） |
|
||||
| Developer | 中低模型 | 默认（中低），架构任务临时升级 |
|
||||
|
||||
## 路径权限
|
||||
|
||||
| 路径 | Coordinator | Test | Developer | 说明 |
|
||||
|------|:-----------:|:----:|:---------:|------|
|
||||
| `docs/spec/**` | R/W | Read-only | Read-only | 产品规格（PM 拥有） |
|
||||
| `tests/browser/**` | Read-only | R/W | Read-only | 浏览器回归用例（Test 拥有） |
|
||||
| `.qa-records/**` | Read-only | R/W | Read-only | 复测记录（gitignore） |
|
||||
| `web/**`、`server/**` | Read-only | Read-only | R/W | 应用源码 |
|
||||
| `**/*_test.go`、`web/**/*.test.tsx` | Read-only | Read-only | R/W | 单元测试 |
|
||||
| `config/*.example.*` | Read-only | Read-only | R/W | 可提交配置模板 |
|
||||
| `.env`、`config/local.*` | Read-only | Read-only | Read-only | 本地私有配置 |
|
||||
| `tasks.yaml` | R/W | Read-only | Read-only | 只有 Coordinator 写 |
|
||||
|
||||
## 命令
|
||||
|
||||
Developer 白盒验证：
|
||||
|
||||
```bash
|
||||
npm run build
|
||||
go test ./...
|
||||
npm run dev # 本地起前端
|
||||
```
|
||||
|
||||
Test 黑盒复测：
|
||||
|
||||
```bash
|
||||
curl -s http://localhost:5173/api/health
|
||||
curl -s -X POST http://localhost:5173/api/fix/preview -d @fixtures/preview.json
|
||||
# 浏览器回归：tests/browser/cases/*.md
|
||||
```
|
||||
|
||||
任务板校验：
|
||||
|
||||
```bash
|
||||
python3 docs/ack/kit/scripts/validate_tasks.py docs/ack/tasks.yaml
|
||||
```
|
||||
|
||||
## 硬规则（其余见 kit/core/）
|
||||
|
||||
- 三角色独立：Coordinator 只编排、Test 只验证、Developer 只实现。
|
||||
- 模型分层：Coordinator 强模型不跑测试，Test/Developer 中低模型（见 kit/core/model-routing.md）。
|
||||
- `worker_done` 与复测报告都不等于完成，必须 Test 独立复测 + Coordinator 终检后才能 `verified`。
|
||||
- 只有 Coordinator 写 `tasks.yaml`；Test 与 Developer 只读。
|
||||
- 每个任务最多派发 3 轮，仍不过标记 `leftover` 并继续。
|
||||
- 不提交或推送，除非用户明确要求。
|
||||
@@ -1,115 +0,0 @@
|
||||
# 填好的最小示例（虚构的 notes-web 项目）。可用 scripts/validate_tasks.py 校验通过。
|
||||
version: 1
|
||||
updatedAt: "2026-07-06T09:40:00+08:00"
|
||||
source: "Coordinator (PM) Agent"
|
||||
kitVersion: "0.3.0"
|
||||
project:
|
||||
name: "notes-web"
|
||||
repoPath: "/home/dev/notes-web"
|
||||
baseUrl: "http://localhost:5173"
|
||||
devWorktree: "/home/dev/notes-web-wt/fix-preview"
|
||||
|
||||
summary:
|
||||
verified: ["BUG-002"]
|
||||
open: []
|
||||
failedRetest: []
|
||||
leftovers: ["BUG-003"]
|
||||
|
||||
tasks:
|
||||
- id: "BUG-002"
|
||||
type: "bug"
|
||||
title: "预览变更点击后不显示 diff 行"
|
||||
priority: "P0"
|
||||
status: "verified"
|
||||
assignee: "developer"
|
||||
component: "web/app/fix/page.tsx"
|
||||
specRefs:
|
||||
- "docs/spec/fix-preview.md#preview"
|
||||
testRefs:
|
||||
- "tests/browser/cases/01-preview.md"
|
||||
description: >
|
||||
用户在 /fix 页点击“预览变更”后，确认区不渲染 API 返回的 diff。
|
||||
stepsToReproduce:
|
||||
- "打开 /fix?fileId=1"
|
||||
- "搜索并选择候选项"
|
||||
- "点击“预览变更”"
|
||||
expected: >
|
||||
确认区出现 title、修改前值、修改后值、coverChanged 提示四行。
|
||||
actual: >
|
||||
API 返回 code=0，但页面确认区为空。
|
||||
evidence:
|
||||
browser: "确认区 DOM 为空，无 diff 行"
|
||||
api: "POST /api/fix/preview -> code=0, 含 diff 字段"
|
||||
logs: "无报错"
|
||||
verification:
|
||||
commands:
|
||||
- "npm run build"
|
||||
- "curl -s -X POST localhost:5173/api/fix/preview -d @fixtures/preview.json"
|
||||
browser:
|
||||
page: "/fix?fileId=1"
|
||||
checks:
|
||||
- "预览后出现 4 行 diff：title/before/after/coverChanged"
|
||||
dispatch:
|
||||
taskId: "orca-task-88"
|
||||
dispatchId: "orca-disp-91"
|
||||
worker: "dev-worker-1"
|
||||
rounds:
|
||||
- round: 1
|
||||
result: failed
|
||||
evidence: "只渲染了 title，缺少 before/after/coverChanged"
|
||||
- round: 2
|
||||
result: passed
|
||||
evidence: "复测 4 行 diff 全部出现，取消不触发写入"
|
||||
resolution:
|
||||
fixedBy: "dev-worker-1"
|
||||
verifiedBy: "test-worker-1"
|
||||
verifiedAt: "2026-07-06T09:38:00+08:00"
|
||||
leftoverReason: null
|
||||
|
||||
- id: "BUG-003"
|
||||
type: "bug"
|
||||
title: "并发保存偶发覆盖他人修改"
|
||||
priority: "P1"
|
||||
status: "leftover"
|
||||
assignee: "developer"
|
||||
component: "server/store/notes.go"
|
||||
specRefs:
|
||||
- "docs/spec/concurrency.md"
|
||||
testRefs: []
|
||||
description: >
|
||||
两个会话同时保存同一条 note 时，后写覆盖先写，无冲突提示。
|
||||
stepsToReproduce:
|
||||
- "会话 A、B 同时打开 note 42"
|
||||
- "A 保存，B 保存"
|
||||
expected: >
|
||||
B 保存时应检测到版本变化并提示冲突，而非静默覆盖。
|
||||
actual: >
|
||||
B 直接覆盖 A 的修改，无提示。
|
||||
evidence:
|
||||
api: "两次 PUT /api/notes/42 均返回 200，无版本校验"
|
||||
verification:
|
||||
commands:
|
||||
- "go test ./server/store/..."
|
||||
browser:
|
||||
page: "/notes/42"
|
||||
checks:
|
||||
- "并发保存时后写方收到冲突提示"
|
||||
dispatch:
|
||||
taskId: "orca-task-90"
|
||||
dispatchId: "orca-disp-95"
|
||||
worker: "dev-worker-1"
|
||||
rounds:
|
||||
- round: 1
|
||||
result: failed
|
||||
evidence: "加了版本号但未在写入路径校验"
|
||||
- round: 2
|
||||
result: failed
|
||||
evidence: "校验只覆盖 API，未覆盖批量导入路径"
|
||||
- round: 3
|
||||
result: failed
|
||||
evidence: "乐观锁与前端重试逻辑冲突，需重新设计"
|
||||
resolution:
|
||||
fixedBy: null
|
||||
verifiedBy: null
|
||||
verifiedAt: null
|
||||
leftoverReason: "failed after 3 supervised developer rounds; 需重新设计并发模型"
|
||||
@@ -1,183 +0,0 @@
|
||||
# 在新项目初始化 ack（给 Agent 的操作手册）
|
||||
|
||||
本文件指导 Agent 把 `ack` 接入一个目标项目。它是**执行手册**：按步骤在目标项目创建 `docs/ack/`、挂载 kit、生成项目覆盖层和任务板，并完成一次结构校验。
|
||||
|
||||
若只想人工核对是否接入完整，看 `adoption-checklist.md`。若要开始一个真实需求，看 `core/kickoff.md`。
|
||||
|
||||
---
|
||||
|
||||
## 0. 前提与安全边界
|
||||
|
||||
开始前先确认三件事：
|
||||
|
||||
1. 目标项目根目录：运行或读取当前环境的项目根，不要假设路径。
|
||||
2. ack kit 目录：本框架目录的绝对路径，例如 `<ack_kit_path>`。
|
||||
3. 分发方式：默认用**单软链接引用**，只有用户明确要求时才整份复制。
|
||||
|
||||
硬规则：
|
||||
|
||||
- 不要覆盖已有 `docs/ack/project.md`、`docs/ack/tasks.yaml` 或团队现有 `AGENTS.md`。如果文件已存在，先读内容并向用户说明差异，再询问是否合并。
|
||||
- 不要把 `core/` 内容复制进项目覆盖层。项目覆盖层只写项目差异。
|
||||
- 不要提交、推送或改 git 配置，除非用户明确要求。
|
||||
- 不要把私有配置、token、`.env` 内容写进 `tasks.yaml` 或 `project.md`。
|
||||
|
||||
---
|
||||
|
||||
## 1. 建目录并挂载 kit
|
||||
|
||||
在目标项目根目录下创建推荐布局：
|
||||
|
||||
```text
|
||||
docs/ack/
|
||||
kit -> <ack_kit_path>
|
||||
project.md
|
||||
tasks.yaml
|
||||
```
|
||||
|
||||
默认方式（推荐，可升级）：
|
||||
|
||||
```bash
|
||||
mkdir -p docs/ack
|
||||
ln -s <ack_kit_path> docs/ack/kit
|
||||
```
|
||||
|
||||
如果 `docs/ack/kit` 已存在：
|
||||
|
||||
- 是指向同一个 ack 目录的软链接：继续。
|
||||
- 是指向旧版本的软链接：报告当前指向与目标指向，询问是否更新。
|
||||
- 是普通目录：不要删除；询问用户是保留、备份还是改用复制模式。
|
||||
|
||||
复制模式（仅用户明确要求）：
|
||||
|
||||
```bash
|
||||
mkdir -p docs/ack
|
||||
cp -R <ack_kit_path> docs/ack/kit
|
||||
```
|
||||
|
||||
复制模式接入后，后续升级需要人工对比 `docs/ack/kit/VERSION`。
|
||||
|
||||
---
|
||||
|
||||
## 2. 生成项目覆盖层 `project.md`
|
||||
|
||||
从模板生成：
|
||||
|
||||
```bash
|
||||
cp docs/ack/kit/templates/project.template.md docs/ack/project.md
|
||||
```
|
||||
|
||||
然后填实际项目差异：
|
||||
|
||||
- 项目名、技术栈、运行命令、Base URL。
|
||||
- 覆盖层文件路径：默认 `docs/ack/project.md`。
|
||||
- 三角色模型档位：默认 Coordinator 强模型，Developer/Test 中低模型。
|
||||
- 路径权限：规格文档、集成测试、复测记录、源码、单元测试、配置模板、本地私有配置。
|
||||
- Developer 白盒验证命令：单测、构建、服务启动或重启。
|
||||
- Test 黑盒复测命令：preflight、API smoke、浏览器回归。
|
||||
|
||||
如果是网站项目，务必在命令里写清：
|
||||
|
||||
- Developer 改完后如何重启服务或确认热更新生效。
|
||||
- Test 使用哪个 Base URL。
|
||||
- Test 浏览器复测入口、用例目录或手工检查路径。
|
||||
|
||||
可选：若希望 Agent 自动加载覆盖层，在目标项目 `AGENTS.md` 加一行指向它：
|
||||
|
||||
```markdown
|
||||
本项目使用 ack 三角色协作协议，项目覆盖层见 `docs/ack/project.md`。
|
||||
```
|
||||
|
||||
如果目标项目已有 `AGENTS.md`，只追加这一行或一个短小段落；不要重写原文件。
|
||||
|
||||
---
|
||||
|
||||
## 3. 生成任务板 `tasks.yaml`
|
||||
|
||||
从模板生成：
|
||||
|
||||
```bash
|
||||
cp docs/ack/kit/templates/tasks.template.yaml docs/ack/tasks.yaml
|
||||
```
|
||||
|
||||
至少替换这些字段：
|
||||
|
||||
- `updatedAt`：当前时间，带时区。
|
||||
- `kitVersion`：读取 `docs/ack/kit/VERSION`。
|
||||
- `project.name`：项目名。
|
||||
- `project.repoPath`：目标项目根目录绝对路径。
|
||||
- `project.baseUrl`：网站或 API 的默认访问地址；非服务项目可写 `n/a`。
|
||||
- `project.devWorktree`：默认当前 worktree；如果会用独立 worktree，写实际路径。
|
||||
- `project.overlayFile`：默认 `docs/ack/project.md`。
|
||||
|
||||
任务可以先保留一个低风险示例任务，但更推荐写入真实首个任务。每个任务的验收必须是可观测信号：
|
||||
|
||||
- 可见文本：页面或 CLI 输出出现什么。
|
||||
- API 结果：状态码、字段、响应值。
|
||||
- 交互结果：点击、跳转、提交、取消后的真实状态。
|
||||
|
||||
不要只写“功能正常”“体验更好”。
|
||||
|
||||
---
|
||||
|
||||
## 4. 校验结构
|
||||
|
||||
在目标项目根目录运行：
|
||||
|
||||
```bash
|
||||
python3 docs/ack/kit/scripts/validate_tasks.py docs/ack/tasks.yaml
|
||||
```
|
||||
|
||||
通过后继续；失败则按错误修正 `tasks.yaml`，不要绕过校验。
|
||||
|
||||
同时人工检查：
|
||||
|
||||
- `docs/ack/kit` 是否能访问 `core/`、`templates/`、`scripts/`。
|
||||
- `docs/ack/project.md` 是否只写项目差异，没有复制大段 core 文本。
|
||||
- `docs/ack/tasks.yaml` 的 `project.overlayFile` 是否指向真实文件。
|
||||
- 路径权限是否能防止 Developer 改规格、Test 改源码、多人写 `tasks.yaml`。
|
||||
- 网站项目是否写清服务重启和浏览器复测方式。
|
||||
|
||||
---
|
||||
|
||||
## 5. 给用户的初始化报告
|
||||
|
||||
初始化完成后，Agent 应给用户一段短报告：
|
||||
|
||||
```text
|
||||
ack 初始化完成。
|
||||
|
||||
创建/确认：
|
||||
- docs/ack/kit -> <ack_kit_path>
|
||||
- docs/ack/project.md
|
||||
- docs/ack/tasks.yaml
|
||||
|
||||
已填项目差异：
|
||||
- 技术栈：<...>
|
||||
- Developer 验证命令：<...>
|
||||
- Test 复测命令：<...>
|
||||
- Base URL：<...>
|
||||
|
||||
校验：
|
||||
- python3 docs/ack/kit/scripts/validate_tasks.py docs/ack/tasks.yaml: passed
|
||||
|
||||
下一步：
|
||||
- 用 docs/ack/kit/core/kickoff.md 开一个真实需求；或
|
||||
- 选一个低风险 bug 跑一次完整三角色闭环。
|
||||
```
|
||||
|
||||
如果有未完成项，不要说“初始化完成”。改用：
|
||||
|
||||
```text
|
||||
ack 初始化已部分完成，阻塞在：<具体原因>。
|
||||
需要用户决定：<选项或缺失信息>。
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. 一句话口令
|
||||
|
||||
当用户在新项目里说“初始化 ack”时，Agent 可以按下面执行：
|
||||
|
||||
```text
|
||||
请在当前项目初始化 ack：确认项目根和 ack kit 路径；创建 docs/ack/kit 软链接；由 kit/templates 生成 docs/ack/project.md 与 docs/ack/tasks.yaml；填入项目实际路径、命令、Base URL、模型档位和首个任务；运行 validate_tasks.py；不要覆盖已有文件，不要提交或推送，完成后报告创建文件、校验结果和下一步。
|
||||
```
|
||||
@@ -1,167 +0,0 @@
|
||||
#!/usr/bin/env python3
|
||||
"""校验 tasks.yaml 是否符合 ack 任务板结构。
|
||||
|
||||
权威结构是同目录上层的 templates/tasks.schema.json（跨语言可用）。
|
||||
本脚本是参考实现：
|
||||
- 若安装了 jsonschema，则用 schema 做完整校验；
|
||||
- 否则回退到内置的关键规则校验（必填字段、状态枚举、三轮上限、leftover 留档）。
|
||||
YAML 解析优先用 pyyaml；未安装时给出提示而非崩溃。
|
||||
|
||||
用法:
|
||||
python3 validate_tasks.py [tasks.yaml]
|
||||
python3 validate_tasks.py --schema path/to/tasks.schema.json tasks.yaml
|
||||
|
||||
退出码: 0 通过 / 1 校验失败 / 2 环境或用法错误。
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import argparse
|
||||
import json
|
||||
import sys
|
||||
from pathlib import Path
|
||||
|
||||
STATUS_ENUM = {
|
||||
"open",
|
||||
"dispatched",
|
||||
"fixed_by_dev",
|
||||
"retesting",
|
||||
"failed_retest",
|
||||
"verified",
|
||||
"blocked",
|
||||
"leftover",
|
||||
}
|
||||
MAX_ROUNDS = 3
|
||||
|
||||
|
||||
def load_yaml(path: Path) -> dict:
|
||||
try:
|
||||
import yaml # type: ignore
|
||||
except ImportError:
|
||||
sys.stderr.write(
|
||||
"需要 PyYAML 才能解析 YAML：pip install pyyaml\n"
|
||||
"（或把任务板导出为 JSON 后再校验）\n"
|
||||
)
|
||||
raise SystemExit(2)
|
||||
try:
|
||||
with path.open(encoding="utf-8") as fh:
|
||||
data = yaml.safe_load(fh)
|
||||
except yaml.YAMLError as exc: # type: ignore
|
||||
sys.stderr.write(f"YAML 解析失败: {exc}\n")
|
||||
raise SystemExit(1)
|
||||
if not isinstance(data, dict):
|
||||
sys.stderr.write("任务板顶层必须是对象（mapping）\n")
|
||||
raise SystemExit(1)
|
||||
return data
|
||||
|
||||
|
||||
def validate_with_schema(data: dict, schema_path: Path) -> list[str]:
|
||||
import jsonschema # type: ignore
|
||||
|
||||
schema = json.loads(schema_path.read_text(encoding="utf-8"))
|
||||
validator = jsonschema.Draft7Validator(schema)
|
||||
errors = []
|
||||
for err in sorted(validator.iter_errors(data), key=lambda e: list(e.path)):
|
||||
loc = "/".join(str(p) for p in err.path) or "<root>"
|
||||
errors.append(f"[schema] {loc}: {err.message}")
|
||||
return errors
|
||||
|
||||
|
||||
def validate_builtin(data: dict) -> list[str]:
|
||||
errors: list[str] = []
|
||||
|
||||
if not isinstance(data.get("version"), int) or data.get("version", 0) < 1:
|
||||
errors.append("version 必须是 >=1 的整数")
|
||||
project = data.get("project")
|
||||
if not isinstance(project, dict) or not project.get("name"):
|
||||
errors.append("project.name 必填")
|
||||
|
||||
tasks = data.get("tasks")
|
||||
if not isinstance(tasks, list):
|
||||
errors.append("tasks 必须是列表")
|
||||
return errors
|
||||
|
||||
seen_ids: set[str] = set()
|
||||
for i, task in enumerate(tasks):
|
||||
where = f"tasks[{i}]"
|
||||
if not isinstance(task, dict):
|
||||
errors.append(f"{where}: 必须是对象")
|
||||
continue
|
||||
tid = task.get("id")
|
||||
title = task.get("title")
|
||||
status = task.get("status")
|
||||
if not tid:
|
||||
errors.append(f"{where}: id 必填")
|
||||
else:
|
||||
where = f"tasks[{i}] {tid}"
|
||||
if tid in seen_ids:
|
||||
errors.append(f"{where}: id 重复")
|
||||
seen_ids.add(tid)
|
||||
if not title:
|
||||
errors.append(f"{where}: title 必填")
|
||||
if status not in STATUS_ENUM:
|
||||
errors.append(
|
||||
f"{where}: status={status!r} 非法，应为 {sorted(STATUS_ENUM)}"
|
||||
)
|
||||
|
||||
dispatch = task.get("dispatch") or {}
|
||||
rounds = dispatch.get("rounds") or []
|
||||
if isinstance(rounds, list):
|
||||
if len(rounds) > MAX_ROUNDS:
|
||||
errors.append(
|
||||
f"{where}: 派发轮次 {len(rounds)} 超过上限 {MAX_ROUNDS}"
|
||||
)
|
||||
for r in rounds:
|
||||
if isinstance(r, dict) and r.get("result") not in {"passed", "failed"}:
|
||||
errors.append(f"{where}: round.result 必须是 passed/failed")
|
||||
|
||||
if status == "leftover":
|
||||
resolution = task.get("resolution") or {}
|
||||
if not resolution.get("leftoverReason"):
|
||||
errors.append(f"{where}: leftover 必须填 resolution.leftoverReason")
|
||||
|
||||
return errors
|
||||
|
||||
|
||||
def main(argv: list[str] | None = None) -> int:
|
||||
parser = argparse.ArgumentParser(description="校验 tasks.yaml 结构")
|
||||
parser.add_argument("tasks", nargs="?", default="tasks.yaml", help="任务板路径")
|
||||
parser.add_argument("--schema", help="tasks.schema.json 路径（默认自动探测）")
|
||||
args = parser.parse_args(argv)
|
||||
|
||||
tasks_path = Path(args.tasks)
|
||||
if not tasks_path.is_file():
|
||||
sys.stderr.write(f"找不到任务板文件: {tasks_path}\n")
|
||||
return 2
|
||||
|
||||
data = load_yaml(tasks_path)
|
||||
|
||||
schema_path = Path(args.schema) if args.schema else (
|
||||
Path(__file__).resolve().parent.parent / "templates" / "tasks.schema.json"
|
||||
)
|
||||
|
||||
mode = "内置规则"
|
||||
try:
|
||||
import jsonschema # type: ignore # noqa: F401
|
||||
|
||||
if schema_path.is_file():
|
||||
errors = validate_with_schema(data, schema_path)
|
||||
mode = f"schema ({schema_path.name})"
|
||||
else:
|
||||
errors = validate_builtin(data)
|
||||
mode = "内置规则（未找到 schema 文件）"
|
||||
except ImportError:
|
||||
errors = validate_builtin(data)
|
||||
|
||||
if errors:
|
||||
sys.stderr.write(f"任务板校验失败（{mode}），共 {len(errors)} 项：\n")
|
||||
for e in errors:
|
||||
sys.stderr.write(f" - {e}\n")
|
||||
return 1
|
||||
|
||||
sys.stdout.write(f"任务板校验通过（{mode}）：{tasks_path}\n")
|
||||
return 0
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
raise SystemExit(main())
|
||||
@@ -1,172 +0,0 @@
|
||||
#!/usr/bin/env python3
|
||||
"""校验 Music Pilot 的 Developer/Test worker 启动命令。
|
||||
|
||||
用法：
|
||||
python3 validate_worker_command.py --role developer --command '<command>'
|
||||
python3 validate_worker_command.py --role test --command '<command>'
|
||||
python3 validate_worker_command.py --role developer --upgraded --command '<command>'
|
||||
python3 validate_worker_command.py --self-test
|
||||
|
||||
退出码：0 通过 / 1 规则不通过 / 2 用法或命令解析错误。
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import argparse
|
||||
import shlex
|
||||
import sys
|
||||
from pathlib import Path
|
||||
|
||||
|
||||
CODEX_YOLO = "--dangerously-bypass-approvals-and-sandbox"
|
||||
CURSOR_YOLO = "--yolo"
|
||||
|
||||
|
||||
def option_value(tokens: list[str], *names: str) -> str | None:
|
||||
for index, token in enumerate(tokens):
|
||||
for name in names:
|
||||
if token == name and index + 1 < len(tokens):
|
||||
return tokens[index + 1]
|
||||
prefix = f"{name}="
|
||||
if token.startswith(prefix):
|
||||
return token[len(prefix) :]
|
||||
return None
|
||||
|
||||
|
||||
def codex_effort(tokens: list[str]) -> str | None:
|
||||
configs: list[str] = []
|
||||
for index, token in enumerate(tokens):
|
||||
if token in {"-c", "--config"} and index + 1 < len(tokens):
|
||||
configs.append(tokens[index + 1])
|
||||
elif token.startswith("--config="):
|
||||
configs.append(token.split("=", 1)[1])
|
||||
for config in configs:
|
||||
if config.startswith("model_reasoning_effort="):
|
||||
return config.split("=", 1)[1].strip('"\'')
|
||||
return None
|
||||
|
||||
|
||||
def validate(role: str, command: str, upgraded: bool = False) -> list[str]:
|
||||
try:
|
||||
tokens = shlex.split(command)
|
||||
except ValueError as exc:
|
||||
return [f"命令无法解析：{exc}"]
|
||||
if not tokens:
|
||||
return ["启动命令不能为空"]
|
||||
|
||||
executable = Path(tokens[0]).name
|
||||
errors: list[str] = []
|
||||
|
||||
if upgraded and role != "developer":
|
||||
errors.append("只有 Developer 可以使用 --upgraded")
|
||||
|
||||
if executable == "codex":
|
||||
if CODEX_YOLO not in tokens:
|
||||
errors.append(f"Codex worker 必须包含 {CODEX_YOLO}")
|
||||
|
||||
model = option_value(tokens, "-m", "--model")
|
||||
effort = codex_effort(tokens)
|
||||
if upgraded:
|
||||
expected_model = "gpt-5.6-sol"
|
||||
allowed_efforts = {"high", "xhigh"}
|
||||
elif role == "developer":
|
||||
expected_model = "gpt-5.6-terra"
|
||||
allowed_efforts = {"medium"}
|
||||
else:
|
||||
expected_model = "gpt-5.6-luna"
|
||||
allowed_efforts = {"low"}
|
||||
|
||||
if model != expected_model:
|
||||
errors.append(
|
||||
f"Codex {role} 模型应为 {expected_model}，实际为 {model or '未指定'}"
|
||||
)
|
||||
if effort not in allowed_efforts:
|
||||
expected = "/".join(sorted(allowed_efforts))
|
||||
errors.append(
|
||||
f"Codex {role} reasoning effort 应为 {expected}，实际为 {effort or '未指定'}"
|
||||
)
|
||||
elif executable == "cursor-agent":
|
||||
if upgraded:
|
||||
errors.append("Cursor worker 不使用 Codex --upgraded 映射")
|
||||
if CURSOR_YOLO not in tokens:
|
||||
errors.append(f"Cursor worker 必须显式包含 {CURSOR_YOLO}")
|
||||
model = option_value(tokens, "--model")
|
||||
if model != "auto":
|
||||
errors.append(f"Cursor {role} 模型应为 auto，实际为 {model or '未指定'}")
|
||||
else:
|
||||
errors.append(f"不支持的 worker CLI：{executable}；只允许 codex 或 cursor-agent")
|
||||
|
||||
return errors
|
||||
|
||||
|
||||
def run_self_test() -> int:
|
||||
cases = [
|
||||
(
|
||||
"codex developer",
|
||||
"developer",
|
||||
f"codex {CODEX_YOLO} -m gpt-5.6-terra -c model_reasoning_effort=medium",
|
||||
False,
|
||||
True,
|
||||
),
|
||||
(
|
||||
"codex test",
|
||||
"test",
|
||||
f"codex {CODEX_YOLO} -m gpt-5.6-luna -c model_reasoning_effort=low",
|
||||
False,
|
||||
True,
|
||||
),
|
||||
(
|
||||
"codex upgraded developer",
|
||||
"developer",
|
||||
f"codex {CODEX_YOLO} -m gpt-5.6-sol -c model_reasoning_effort=high",
|
||||
True,
|
||||
True,
|
||||
),
|
||||
("cursor worker", "test", "cursor-agent --yolo --model auto", False, True),
|
||||
("naked codex", "developer", "codex", False, False),
|
||||
(
|
||||
"wrong codex role model",
|
||||
"test",
|
||||
f"codex {CODEX_YOLO} -m gpt-5.6-terra -c model_reasoning_effort=medium",
|
||||
False,
|
||||
False,
|
||||
),
|
||||
("cursor without yolo", "developer", "cursor-agent --model auto", False, False),
|
||||
]
|
||||
failures: list[str] = []
|
||||
for name, role, command, upgraded, expected_pass in cases:
|
||||
passed = not validate(role, command, upgraded)
|
||||
if passed != expected_pass:
|
||||
failures.append(name)
|
||||
if failures:
|
||||
sys.stderr.write("worker 命令校验器自测失败：" + ", ".join(failures) + "\n")
|
||||
return 1
|
||||
print(f"worker 命令校验器自测通过：{len(cases)} 项")
|
||||
return 0
|
||||
|
||||
|
||||
def main(argv: list[str] | None = None) -> int:
|
||||
parser = argparse.ArgumentParser(description="校验 Developer/Test worker 启动命令")
|
||||
parser.add_argument("--role", choices=("developer", "test"))
|
||||
parser.add_argument("--command")
|
||||
parser.add_argument("--upgraded", action="store_true", help="校验升级后的 Codex Developer")
|
||||
parser.add_argument("--self-test", action="store_true")
|
||||
args = parser.parse_args(argv)
|
||||
|
||||
if args.self_test:
|
||||
return run_self_test()
|
||||
if not args.role or not args.command:
|
||||
parser.error("非自测模式必须同时提供 --role 和 --command")
|
||||
|
||||
errors = validate(args.role, args.command, args.upgraded)
|
||||
if errors:
|
||||
sys.stderr.write("worker 启动命令校验失败：\n")
|
||||
for error in errors:
|
||||
sys.stderr.write(f" - {error}\n")
|
||||
return 1
|
||||
print(f"worker 启动命令校验通过：role={args.role}")
|
||||
return 0
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
raise SystemExit(main())
|
||||
@@ -1,84 +0,0 @@
|
||||
# <项目名> Agent 协作协议（项目覆盖层）
|
||||
|
||||
> 本项目基于 ack v<kit_version>（见 `docs/ack/kit/VERSION`）。
|
||||
> 稳定规范引用 `docs/ack/kit/core/`，不复制其内容；本文件只填项目自己的差异。
|
||||
>
|
||||
> **本文件是「项目覆盖层」，文件名可配置。** 默认放 `docs/ack/project.md`，
|
||||
> 不占用 `AGENTS.md`，避免与团队已有的 `AGENTS.md` 约定冲突。
|
||||
> 若希望 Agent 自动加载，可在项目 `AGENTS.md` 里加一行指向本文件，或直接把本文件命名为 `AGENTS.md`。
|
||||
> 无论叫什么，都在 `tasks.yaml` 的 `project.overlayFile` 记录实际路径。
|
||||
>
|
||||
> 目录约定：`docs/ack/` 下只有一个软链接 `kit/`（指向共享框架），加本项目 `project.md` + `tasks.yaml`。
|
||||
|
||||
## 项目概览
|
||||
|
||||
- 项目：`<project_name>`
|
||||
- 技术栈：`<tech_stack>`
|
||||
- 运行命令：`<run_command>`
|
||||
- Base URL：`<base_url>`
|
||||
- 任务板：`docs/ack/tasks.yaml`
|
||||
- 覆盖层文件：`<overlay_file_path>`（默认 `docs/ack/project.md`）
|
||||
|
||||
## 稳定规范（不在此重复，直接引用）
|
||||
|
||||
- 开始一个需求（启动手册）：`docs/ack/kit/core/kickoff.md`
|
||||
- 角色模型 / 权限 / 状态机 / 完成定义：`docs/ack/kit/core/roles-and-permissions.md`
|
||||
- 模型档位与升级规则：`docs/ack/kit/core/model-routing.md`
|
||||
- 闭环流程（含手动模式、worktree 对齐）：`docs/ack/kit/core/closed-loop.md`
|
||||
- 优化方法（验收信号、三轮策略）：`docs/ack/kit/core/optimization-method.md`
|
||||
- 派发 prompt 模板：`docs/ack/kit/core/prompt-templates.md`
|
||||
- Orca 编排命令（可选）：`docs/ack/kit/core/orca-adapter.md`
|
||||
|
||||
## 模型档位（项目可覆盖，默认见 core/model-routing.md）
|
||||
|
||||
| 角色 | 默认档位 | 本项目实际 |
|
||||
|------|----------|------------|
|
||||
| Coordinator (PM) | 强模型 | `<model_or_default>` |
|
||||
| Test | 中低模型 | `<model_or_default>` |
|
||||
| Developer | 中低模型 | `<model_or_default>` |
|
||||
|
||||
## 路径权限（项目覆盖层，必须填实际路径）
|
||||
|
||||
| 路径 | Coordinator | Test | Developer | 说明 |
|
||||
|------|:-----------:|:----:|:---------:|------|
|
||||
| `<spec_paths>` | R/W | Read-only | Read-only | 产品规格、API 文档、计划（PM 拥有） |
|
||||
| `<integration_test_paths>` | Read-only | R/W | Read-only | 浏览器/API 回归（Test 拥有） |
|
||||
| `<test_records_path>` | Read-only | R/W | Read-only | 复测记录 |
|
||||
| `<source_paths>` | Read-only | Read-only | R/W | 应用源码 |
|
||||
| `<unit_test_paths>` | Read-only | Read-only | R/W | 单元测试 |
|
||||
| `<shared_config_templates>` | Read-only | Read-only | R/W | 可提交配置模板 |
|
||||
| `<local_config_paths>` | Read-only | Read-only | Read-only | 本地私有配置 |
|
||||
| `tasks.yaml` | R/W | Read-only | Read-only | 只有 Coordinator 写 |
|
||||
|
||||
## 命令（项目覆盖层）
|
||||
|
||||
Developer 白盒验证：
|
||||
|
||||
```bash
|
||||
<unit_test_command>
|
||||
<build_command>
|
||||
<local_run_command>
|
||||
```
|
||||
|
||||
Test 黑盒复测：
|
||||
|
||||
```bash
|
||||
<preflight_command>
|
||||
<api_smoke_command>
|
||||
<browser_regression_command>
|
||||
```
|
||||
|
||||
任务板校验：
|
||||
|
||||
```bash
|
||||
python3 docs/ack/kit/scripts/validate_tasks.py docs/ack/tasks.yaml
|
||||
```
|
||||
|
||||
## 硬规则（其余见 kit/core/）
|
||||
|
||||
- 三角色独立：Coordinator 只编排、Test 只验证、Developer 只实现（验证者 ≠ 实现者）。
|
||||
- 模型分层：Coordinator 用强模型且不亲自跑测试，Test/Developer 用中低模型，必要时升级（见 kit/core/model-routing.md）。
|
||||
- `worker_done` 与复测报告都不等于完成。必须 Test 独立复测 + Coordinator 终检后才能 `verified`。
|
||||
- 只有 Coordinator 写 `tasks.yaml`；Developer 与 Test 都只读，通过消息回报。
|
||||
- 每个任务最多派发 3 轮，仍不过标记 `leftover` 并继续下一个。
|
||||
- 不提交或推送，除非用户明确要求。
|
||||
@@ -1,132 +0,0 @@
|
||||
{
|
||||
"$schema": "http://json-schema.org/draft-07/schema#",
|
||||
"$id": "https://git.yumee.top/laily/skills/kits/ack/tasks.schema.json",
|
||||
"title": "Agent Collaboration Kit task board",
|
||||
"description": "tasks.yaml 的权威结构。跨语言可用；参考校验实现见 scripts/validate_tasks.py。",
|
||||
"type": "object",
|
||||
"required": ["version", "project", "tasks"],
|
||||
"additionalProperties": true,
|
||||
"properties": {
|
||||
"version": { "type": "integer", "minimum": 1 },
|
||||
"updatedAt": { "type": "string" },
|
||||
"source": { "type": "string" },
|
||||
"kitVersion": {
|
||||
"type": "string",
|
||||
"description": "接入时所基于的 ack 版本，便于日后 diff 升级"
|
||||
},
|
||||
"project": {
|
||||
"type": "object",
|
||||
"required": ["name"],
|
||||
"additionalProperties": true,
|
||||
"properties": {
|
||||
"name": { "type": "string" },
|
||||
"repoPath": { "type": "string" },
|
||||
"baseUrl": { "type": "string" },
|
||||
"devWorktree": { "type": "string" },
|
||||
"overlayFile": {
|
||||
"type": "string",
|
||||
"description": "项目覆盖层文件路径，默认 docs/ack/project.md，可自定义"
|
||||
}
|
||||
}
|
||||
},
|
||||
"summary": {
|
||||
"type": "object",
|
||||
"additionalProperties": true,
|
||||
"properties": {
|
||||
"verified": { "type": "array", "items": { "type": "string" } },
|
||||
"open": { "type": "array", "items": { "type": "string" } },
|
||||
"failedRetest": { "type": "array", "items": { "type": "string" } },
|
||||
"leftovers": { "type": "array", "items": { "type": "string" } }
|
||||
}
|
||||
},
|
||||
"statusReference": { "type": "object" },
|
||||
"tasks": {
|
||||
"type": "array",
|
||||
"items": { "$ref": "#/definitions/task" }
|
||||
}
|
||||
},
|
||||
"definitions": {
|
||||
"status": {
|
||||
"type": "string",
|
||||
"enum": [
|
||||
"open",
|
||||
"dispatched",
|
||||
"fixed_by_dev",
|
||||
"retesting",
|
||||
"failed_retest",
|
||||
"verified",
|
||||
"blocked",
|
||||
"leftover"
|
||||
]
|
||||
},
|
||||
"round": {
|
||||
"type": "object",
|
||||
"required": ["round", "result"],
|
||||
"additionalProperties": true,
|
||||
"properties": {
|
||||
"round": { "type": "integer", "minimum": 1 },
|
||||
"result": { "type": "string", "enum": ["passed", "failed"] },
|
||||
"evidence": { "type": "string" }
|
||||
}
|
||||
},
|
||||
"task": {
|
||||
"type": "object",
|
||||
"required": ["id", "title", "status"],
|
||||
"additionalProperties": true,
|
||||
"properties": {
|
||||
"id": { "type": "string", "minLength": 1 },
|
||||
"type": { "type": "string" },
|
||||
"title": { "type": "string", "minLength": 1 },
|
||||
"priority": { "type": "string" },
|
||||
"status": { "$ref": "#/definitions/status" },
|
||||
"assignee": { "type": "string" },
|
||||
"component": { "type": "string" },
|
||||
"specRefs": { "type": "array", "items": { "type": "string" } },
|
||||
"testRefs": { "type": "array", "items": { "type": "string" } },
|
||||
"description": { "type": "string" },
|
||||
"stepsToReproduce": { "type": "array", "items": { "type": "string" } },
|
||||
"expected": { "type": "string" },
|
||||
"actual": { "type": "string" },
|
||||
"evidence": { "type": "object" },
|
||||
"verification": { "type": "object" },
|
||||
"dispatch": {
|
||||
"type": "object",
|
||||
"additionalProperties": true,
|
||||
"properties": {
|
||||
"taskId": { "type": ["string", "null"] },
|
||||
"dispatchId": { "type": ["string", "null"] },
|
||||
"worker": { "type": ["string", "null"] },
|
||||
"rounds": {
|
||||
"type": "array",
|
||||
"items": { "$ref": "#/definitions/round" }
|
||||
}
|
||||
}
|
||||
},
|
||||
"resolution": {
|
||||
"type": "object",
|
||||
"additionalProperties": true,
|
||||
"properties": {
|
||||
"fixedBy": { "type": ["string", "null"] },
|
||||
"verifiedBy": { "type": ["string", "null"] },
|
||||
"verifiedAt": { "type": ["string", "null"] },
|
||||
"leftoverReason": { "type": ["string", "null"] },
|
||||
"evidence": { "type": "object" }
|
||||
}
|
||||
}
|
||||
},
|
||||
"allOf": [
|
||||
{
|
||||
"if": { "properties": { "status": { "const": "leftover" } } },
|
||||
"then": {
|
||||
"properties": {
|
||||
"resolution": {
|
||||
"required": ["leftoverReason"]
|
||||
}
|
||||
},
|
||||
"required": ["resolution"]
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -1,69 +0,0 @@
|
||||
# 复制为 docs/ack/tasks.yaml，替换占位符。结构见 templates/tasks.schema.json。
|
||||
version: 1
|
||||
updatedAt: "<YYYY-MM-DDTHH:mm:ss+TZ>"
|
||||
source: "Coordinator (PM) Agent"
|
||||
kitVersion: "<接入时的 ack 版本，见 kit 根 VERSION>"
|
||||
project:
|
||||
name: "<project_name>"
|
||||
repoPath: "<repo_path>"
|
||||
baseUrl: "<base_url>"
|
||||
devWorktree: "<dev_worktree>"
|
||||
overlayFile: "docs/ack/project.md"
|
||||
|
||||
summary:
|
||||
verified: []
|
||||
open: []
|
||||
failedRetest: []
|
||||
leftovers: []
|
||||
|
||||
tasks:
|
||||
- id: "BUG-001"
|
||||
type: "bug"
|
||||
title: "<short title>"
|
||||
priority: "P0"
|
||||
status: "open"
|
||||
assignee: "developer"
|
||||
component: "<source file or module>"
|
||||
specRefs:
|
||||
- "<docs/spec.md#section>"
|
||||
testRefs:
|
||||
- "<tests/browser/cases/01-case.md>"
|
||||
|
||||
description: >
|
||||
<What is wrong, in user-visible terms.>
|
||||
|
||||
stepsToReproduce:
|
||||
- "<step 1>"
|
||||
- "<step 2>"
|
||||
|
||||
expected: >
|
||||
<Expected behavior.>
|
||||
|
||||
actual: >
|
||||
<Actual behavior observed by Test.>
|
||||
|
||||
evidence:
|
||||
browser: "<snapshot text, screenshot path, or UI finding>"
|
||||
api: "<curl result or API mismatch>"
|
||||
logs: "<relevant log line if any>"
|
||||
|
||||
verification:
|
||||
commands:
|
||||
- "<unit/build command>"
|
||||
- "<browser/API smoke command>"
|
||||
browser:
|
||||
page: "<page path>"
|
||||
checks:
|
||||
- "<visible text or interaction expected>"
|
||||
|
||||
dispatch:
|
||||
taskId: null
|
||||
dispatchId: null
|
||||
worker: null
|
||||
rounds: []
|
||||
|
||||
resolution:
|
||||
fixedBy: null
|
||||
verifiedBy: null
|
||||
verifiedAt: null
|
||||
leftoverReason: null
|
||||
+25
-20
@@ -14,7 +14,7 @@ cd /path/to/skills # 本仓库根目录
|
||||
## 命令风格
|
||||
|
||||
接口对齐 [Vercel skills CLI](https://github.com/vercel-labs/skills) 的 `add` / `remove`，
|
||||
统一管理 **~/.skills 自研 skill**、命名 custom source 和 registry 外部 skill。
|
||||
统一管理 builtin skill、预置 catalog source 和用户命名的 custom source。
|
||||
|
||||
```bash
|
||||
# 浏览可用自研 skill
|
||||
@@ -65,15 +65,17 @@ skiff bootstrap
|
||||
| 命令 | 说明 |
|
||||
|------|------|
|
||||
| `skiff bootstrap` | 将本项目的 `skiff` skill 全局安装到所有 Agent |
|
||||
| `skiff update` | 在 `~/.skills` 执行 `git pull`，更新 skiff 自身 |
|
||||
| `skiff init <name> [--project DIR]` | 使用 builtin skill 自带模板初始化项目状态 |
|
||||
|
||||
### 全局安装（自研 skill）
|
||||
### Skill 安装
|
||||
|
||||
| 命令 | 说明 |
|
||||
|------|------|
|
||||
| `skiff add <name> [--global] [-a AGENT...] [-y]` | 安装到 Agent 目录（软链） |
|
||||
| `skiff select [--global] [-a AGENT...]` | 打开终端多选界面，批量安装 skill |
|
||||
| `skiff remove <name> [--global] [-a AGENT...] [-y]` | 移除软链（`rm` / `r` 别名） |
|
||||
| `skiff add --list` | 列出可用自研 skill |
|
||||
| `skiff add --list` | 列出可用 builtin skill |
|
||||
| `skiff publish [paths] -m MSG [--push]` | 在 ~/.skills 内 git add/commit/push |
|
||||
|
||||
旧命令 `install` / `uninstall` 已移除，请改用 `add` / `remove`。
|
||||
@@ -86,16 +88,16 @@ skiff bootstrap
|
||||
| claude | `~/.claude/skills/` |
|
||||
| codex | `~/.codex/skills/` |
|
||||
|
||||
### 外部 Git skill
|
||||
### 预置 Catalog Source
|
||||
|
||||
| 命令 | 说明 |
|
||||
|------|------|
|
||||
| `skiff registry add <name> <repo-url> [--ref main] [--path .]` | 写入 `registry.yaml` |
|
||||
| `skiff fetch <name>` | 克隆或更新外部仓库缓存 |
|
||||
| `skiff add <name> [-g] [-a AGENT...]` | 安装 registry 中的单个 skill 或完整 collection（缺失时自动 fetch） |
|
||||
| `skiff catalog add <name> <repo-url> [--ref main] [--path .]` | 写入 `catalog.yaml` |
|
||||
| `skiff fetch <name>` | 克隆或更新 catalog source checkout |
|
||||
| `skiff add <name> [-g] [-a AGENT...]` | 安装 catalog 中的单个 skill 或完整 collection（缺失时自动 fetch） |
|
||||
| `skiff add <collection>/<skill> [...]` | 只安装 collection 中指定的 skill |
|
||||
|
||||
`registry.yaml` 条目可额外提供 `description` 和 `tags`。`description`
|
||||
`catalog.yaml` 条目可额外提供 `description` 和 `tags`。`description`
|
||||
会显示在 `skiff select` 的候选列表中。`path` 可以直接指向含
|
||||
`SKILL.md` 的单个 skill，也可以指向由多个 skill 目录组成的 collection。
|
||||
collection 会自动发现下一层所有含 `SKILL.md` 的目录；`skiff add <name>`
|
||||
@@ -112,7 +114,10 @@ skiff select --project ~/code/app # 指定项目
|
||||
```
|
||||
|
||||
使用方向键移动、空格勾选、`/` 搜索、Enter 安装，按 `q` 或 Esc
|
||||
取消。已经安装到目标范围的 skill 默认勾选；取消勾选不会卸载已有 skill。
|
||||
取消。普通 `skiff select` 只安装到项目，并在每一项旁只读显示各 Agent 的
|
||||
全局安装状态；`skiff select -g` 只安装到全局。已经安装到目标范围的 skill
|
||||
默认勾选；取消勾选不会卸载已有 skill，卸载请使用 `skiff remove`。如果全局
|
||||
存在同名但指向其它来源的 skill，项目选择器会显示“全局同名冲突”。
|
||||
项目模式会把成功选择的项目写入 `.skills.yaml`。非交互环境请使用
|
||||
`skiff add <name>...`。使用 `-a` 限定 Agent 时，该范围会记录在对应的
|
||||
skill 条目中，后续 `skiff sync` 不会扩散到其他 Agent。
|
||||
@@ -171,8 +176,8 @@ skiff 不保存 token。可以使用 `company/code-review`，也可以使用
|
||||
|
||||
| 命令 | 说明 |
|
||||
|------|------|
|
||||
| `skiff create <name> [--idea TEXT] [--from-project PATH]` | 从模板创建草稿到 `~/.skills/.drafts/` |
|
||||
| `skiff check <name>` | 校验草稿或正式 skill |
|
||||
| `skiff create <name> [--idea TEXT] [--from-project PATH]` | 从模板创建含 `SKILL.md`、`README.md` 的草稿 |
|
||||
| `skiff check <name>` | 校验草稿或正式 skill，包括人类使用说明 |
|
||||
| `skiff finalize <name>` | 校验草稿并移动到正式 `skills/` |
|
||||
| `skiff doctor [--target all] [--fix]` | 检查软链健康状态，`--fix` 自动修复 |
|
||||
|
||||
@@ -182,7 +187,7 @@ skiff 不保存 token。可以使用 `company/code-review`，也可以使用
|
||||
|
||||
```bash
|
||||
skiff create my-skill --idea "描述要解决的重复问题" --from-project .
|
||||
# 由 Agent 完善 ~/.skills/.drafts/my-skill/SKILL.md
|
||||
# 由 Agent 完善草稿中的 SKILL.md 和 README.md
|
||||
skiff check my-skill
|
||||
skiff finalize my-skill
|
||||
skiff publish skills/my-skill -m "add my-skill" --push
|
||||
@@ -197,12 +202,12 @@ cd ~/code/my-app
|
||||
skiff add declarative-openspec-loop -a cursor -y
|
||||
```
|
||||
|
||||
### 安装外部 Git skill
|
||||
### 添加 Catalog Source
|
||||
|
||||
```bash
|
||||
skiff add my-ext https://github.com/org/repo --ref main
|
||||
skiff catalog add my-ext https://github.com/org/repo --ref main
|
||||
skiff fetch my-ext
|
||||
skiff install-external my-ext
|
||||
skiff add my-ext -g
|
||||
```
|
||||
|
||||
## 源码结构
|
||||
@@ -213,8 +218,8 @@ skiff/
|
||||
├── __main__.py # python3 -m skiff 入口
|
||||
├── cli.py # 命令定义与调度
|
||||
├── paths.py # 路径常量与 Agent 目标
|
||||
├── skills.py # 自研 skill 发现
|
||||
├── registry.py # registry.yaml 读写
|
||||
├── skills.py # builtin/catalog/custom 统一解析
|
||||
├── catalog.py # catalog.yaml 读写与 Skill 发现
|
||||
├── sources.py # custom source 配置、发现与 Git 管理
|
||||
├── project.py # .skills.yaml 管理
|
||||
├── symlinks.py # 软链创建/检查/修复
|
||||
@@ -228,9 +233,9 @@ skiff/
|
||||
| 变量 | 路径 | 说明 |
|
||||
|------|------|------|
|
||||
| `SKILLS_HOME` | `~/.skills` | skills 仓库（软链） |
|
||||
| `SKILLS_DIR` | `~/.skills/skills/` | 自研 skill 目录 |
|
||||
| `REGISTRY_FILE` | `~/.skills/registry.yaml` | 外部 skill 注册表 |
|
||||
| `EXTERNALS_DIR` | `~/.local/share/skills/externals/` | 已 fetch 的外部仓库；新条目按 repo/ref 共享缓存 |
|
||||
| `SKILLS_DIR` | `~/.skills/skills/` | builtin skill 目录 |
|
||||
| `CATALOG_FILE` | `~/.skills/catalog.yaml` | 预置 Skill 来源目录 |
|
||||
| `CATALOG_CACHE_DIR` | `~/.local/share/skills/externals/` | catalog checkout 兼容缓存；按 repo/ref 共享 |
|
||||
| `CONFIG_FILE` | `~/.config/skiff/config.yaml` | custom source 配置 |
|
||||
| `SOURCES_DIR` | `~/.local/share/skiff/sources/` | custom Git source 默认 checkout |
|
||||
|
||||
|
||||
+1
-1
@@ -1,3 +1,3 @@
|
||||
"""skiff — Agent Skills 安装与管理 CLI。"""
|
||||
|
||||
__version__ = "0.5.0"
|
||||
__version__ = "0.6.0"
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
"""registry.yaml 读写。"""
|
||||
"""预置 Skill catalog 的配置、发现与本地 checkout 路径。"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
@@ -7,64 +7,77 @@ from pathlib import Path
|
||||
from typing import Any
|
||||
|
||||
from skiff import yaml_io
|
||||
from skiff.paths import REGISTRY_FILE
|
||||
from skiff.paths import CATALOG_FILE, LEGACY_REGISTRY_FILE
|
||||
|
||||
|
||||
def load_registry(path: Path | None = None) -> dict[str, dict[str, Any]]:
|
||||
path = path or REGISTRY_FILE
|
||||
def load_catalog(path: Path | None = None) -> dict[str, dict[str, Any]]:
|
||||
path = path or (
|
||||
CATALOG_FILE if CATALOG_FILE.is_file() else LEGACY_REGISTRY_FILE
|
||||
)
|
||||
if not path.is_file():
|
||||
return {}
|
||||
data = yaml_io.safe_load(path.read_text(encoding="utf-8")) or {}
|
||||
if not isinstance(data, dict):
|
||||
raise SystemExit(f"registry 格式错误: {path}")
|
||||
raise SystemExit(f"catalog 格式错误: {path}")
|
||||
return {k: v for k, v in data.items() if isinstance(v, dict) and not k.startswith("#")}
|
||||
|
||||
|
||||
def save_registry(data: dict[str, dict[str, Any]], path: Path | None = None) -> None:
|
||||
path = path or REGISTRY_FILE
|
||||
def save_catalog(data: dict[str, dict[str, Any]], path: Path | None = None) -> None:
|
||||
path = path or CATALOG_FILE
|
||||
path.parent.mkdir(parents=True, exist_ok=True)
|
||||
path.write_text(yaml_io.safe_dump(data, allow_unicode=True, sort_keys=False), encoding="utf-8")
|
||||
|
||||
|
||||
def external_repo_path(entry: dict[str, Any]) -> Path:
|
||||
def catalog_repo(entry: dict[str, Any]) -> str:
|
||||
"""Expand a local home-relative repo while leaving remote URLs unchanged."""
|
||||
repo = str(entry.get("repo", ""))
|
||||
return str(Path(repo).expanduser()) if repo.startswith("~") else repo
|
||||
|
||||
|
||||
def catalog_repo_path(entry: dict[str, Any]) -> Path:
|
||||
"""Return the shared checkout path for a repo/ref pair."""
|
||||
from skiff.paths import EXTERNALS_DIR
|
||||
from skiff.paths import CATALOG_CACHE_DIR
|
||||
|
||||
repo = str(entry.get("repo", ""))
|
||||
ref = str(entry.get("ref", "main"))
|
||||
digest = hashlib.sha256(f"{repo}\0{ref}".encode()).hexdigest()[:16]
|
||||
return EXTERNALS_DIR / "_repos" / digest
|
||||
return CATALOG_CACHE_DIR / "_repos" / digest
|
||||
|
||||
|
||||
def external_checkout_path(name: str, entry: dict[str, Any]) -> Path:
|
||||
"""Prefer an existing pre-shared-cache checkout for compatibility."""
|
||||
from skiff.paths import EXTERNALS_DIR
|
||||
def catalog_checkout_path(name: str, entry: dict[str, Any]) -> Path:
|
||||
"""Use a local repo directly, otherwise return its external checkout."""
|
||||
from skiff.paths import CATALOG_CACHE_DIR
|
||||
|
||||
legacy = EXTERNALS_DIR / name
|
||||
return legacy if legacy.is_dir() else external_repo_path(entry)
|
||||
configured_repo = str(entry.get("repo", ""))
|
||||
local_repo = Path(catalog_repo(entry))
|
||||
if configured_repo.startswith("~") and local_repo.is_dir():
|
||||
return local_repo.resolve()
|
||||
|
||||
legacy = CATALOG_CACHE_DIR / name
|
||||
return legacy if legacy.is_dir() else catalog_repo_path(entry)
|
||||
|
||||
|
||||
def external_skill_path(name: str, entry: dict[str, Any] | None = None) -> Path:
|
||||
entry = entry or load_registry().get(name, {})
|
||||
def catalog_skill_path(name: str, entry: dict[str, Any] | None = None) -> Path:
|
||||
entry = entry or load_catalog().get(name, {})
|
||||
subpath = entry.get("path", ".") or "."
|
||||
checkout = external_checkout_path(name, entry).resolve()
|
||||
checkout = catalog_checkout_path(name, entry).resolve()
|
||||
skill_path = (checkout / subpath).resolve()
|
||||
try:
|
||||
skill_path.relative_to(checkout)
|
||||
except ValueError as exc:
|
||||
raise SystemExit(
|
||||
f"registry 条目 {name!r} 的 path 超出外部仓库: {subpath!r}"
|
||||
f"catalog 条目 {name!r} 的 path 超出来源仓库: {subpath!r}"
|
||||
) from exc
|
||||
return skill_path
|
||||
|
||||
|
||||
def discover_external_skills(
|
||||
def discover_catalog_skills(
|
||||
name: str,
|
||||
entry: dict[str, Any] | None = None,
|
||||
) -> dict[str, Path]:
|
||||
"""Discover a single registry skill or a collection of sibling skills."""
|
||||
entry = entry or load_registry().get(name, {})
|
||||
root = external_skill_path(name, entry)
|
||||
"""Discover a catalog provider containing one or more skills."""
|
||||
entry = entry or load_catalog().get(name, {})
|
||||
root = catalog_skill_path(name, entry)
|
||||
if (root / "SKILL.md").is_file():
|
||||
return {name: root}
|
||||
if not root.is_dir():
|
||||
@@ -90,18 +103,3 @@ def discover_external_skills(
|
||||
continue
|
||||
skills[item.name] = item
|
||||
return skills
|
||||
|
||||
|
||||
def external_collection_skill_path(
|
||||
collection: str,
|
||||
skill_name: str,
|
||||
entry: dict[str, Any] | None = None,
|
||||
) -> Path:
|
||||
skills = discover_external_skills(collection, entry)
|
||||
if skill_name not in skills:
|
||||
available = ", ".join(skills) or "(无)"
|
||||
raise SystemExit(
|
||||
f"registry collection {collection!r} 中找不到 skill {skill_name!r}。"
|
||||
f"可用: {available}"
|
||||
)
|
||||
return skills[skill_name]
|
||||
+866
-262
File diff suppressed because it is too large
Load Diff
+3
-2
@@ -9,8 +9,9 @@ SKILLS_HOME = HOME / ".skills"
|
||||
SKILLS_DIR = SKILLS_HOME / "skills"
|
||||
TEMPLATE_DIR = SKILLS_DIR / "_template"
|
||||
DRAFTS_DIR = SKILLS_HOME / ".drafts"
|
||||
REGISTRY_FILE = SKILLS_HOME / "registry.yaml"
|
||||
EXTERNALS_DIR = HOME / ".local" / "share" / "skills" / "externals"
|
||||
CATALOG_FILE = SKILLS_HOME / "catalog.yaml"
|
||||
LEGACY_REGISTRY_FILE = SKILLS_HOME / "registry.yaml"
|
||||
CATALOG_CACHE_DIR = HOME / ".local" / "share" / "skills" / "externals"
|
||||
CONFIG_FILE = HOME / ".config" / "skiff" / "config.yaml"
|
||||
SOURCES_DIR = HOME / ".local" / "share" / "skiff" / "sources"
|
||||
PROJECT_MANIFEST = ".skills.yaml"
|
||||
|
||||
+9
-9
@@ -7,7 +7,7 @@ from typing import Any
|
||||
|
||||
from skiff import yaml_io
|
||||
from skiff.paths import PROJECT_MANIFEST
|
||||
from skiff.skills import resolve_skill_source
|
||||
from skiff.skills import normalize_source, resolve_skill_source
|
||||
|
||||
|
||||
def load_manifest(path: Path | None = None) -> tuple[Path, dict[str, Any]]:
|
||||
@@ -31,11 +31,13 @@ def save_manifest(path: Path, data: dict[str, Any]) -> None:
|
||||
|
||||
def normalize_skill_entry(entry: str | dict[str, Any]) -> dict[str, Any]:
|
||||
if isinstance(entry, str):
|
||||
return {"name": entry, "source": "owned"}
|
||||
return {"name": entry, "source": "builtin"}
|
||||
name = entry.get("name")
|
||||
if not name:
|
||||
raise SystemExit(f".skills.yaml 条目缺少 name: {entry}")
|
||||
source = entry.get("source", "owned")
|
||||
source = normalize_source(str(entry.get("source", "builtin")))
|
||||
if source == "catalog" and entry.get("registry"):
|
||||
source = f"catalog:{entry['registry']}"
|
||||
return {"name": name, "source": source, **{k: v for k, v in entry.items() if k not in ("name", "source")}}
|
||||
|
||||
|
||||
@@ -44,8 +46,6 @@ def manifest_skill_names(data: dict[str, Any]) -> list[str]:
|
||||
|
||||
|
||||
def _entry_to_yaml(entry: dict[str, Any]) -> str | dict[str, Any]:
|
||||
if entry.get("source", "owned") == "owned" and set(entry.keys()) <= {"name", "source"}:
|
||||
return entry["name"]
|
||||
return entry
|
||||
|
||||
|
||||
@@ -53,7 +53,7 @@ def add_skill_to_manifest(
|
||||
manifest_path: Path,
|
||||
name: str,
|
||||
*,
|
||||
source: str = "owned",
|
||||
source: str = "builtin",
|
||||
extra: dict[str, Any] | None = None,
|
||||
) -> None:
|
||||
path = manifest_path
|
||||
@@ -100,7 +100,7 @@ def iter_manifest_skills(data: dict[str, Any]) -> list[dict[str, Any]]:
|
||||
|
||||
def resolve_manifest_skill(entry: dict[str, Any]) -> tuple[Path, str]:
|
||||
name = entry["name"]
|
||||
source = entry.get("source", "owned")
|
||||
if source == "registry" and entry.get("registry"):
|
||||
source = f"registry:{entry['registry']}"
|
||||
source = normalize_source(entry.get("source", "builtin"))
|
||||
if source == "catalog" and entry.get("registry"):
|
||||
source = f"catalog:{entry['registry']}"
|
||||
return resolve_skill_source(name, source=source)
|
||||
|
||||
+136
-21
@@ -2,6 +2,7 @@
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import unicodedata
|
||||
from dataclasses import dataclass
|
||||
from typing import Callable, Iterable
|
||||
|
||||
@@ -12,6 +13,38 @@ class SkillChoice:
|
||||
kind: str
|
||||
description: str = ""
|
||||
installed: bool = False
|
||||
readonly_status: str = ""
|
||||
children: tuple[str, ...] = ()
|
||||
indent: int = 0
|
||||
|
||||
|
||||
def fit_to_width(text: str, width: int) -> str:
|
||||
"""Trim text to terminal display width without splitting wide characters."""
|
||||
if width <= 0:
|
||||
return ""
|
||||
result: list[str] = []
|
||||
used = 0
|
||||
for char in text:
|
||||
if unicodedata.combining(char):
|
||||
char_width = 0
|
||||
else:
|
||||
char_width = 2 if unicodedata.east_asian_width(char) in {"W", "F"} else 1
|
||||
if used + char_width > width:
|
||||
break
|
||||
result.append(char)
|
||||
used += char_width
|
||||
return "".join(result)
|
||||
|
||||
|
||||
def display_width(text: str) -> int:
|
||||
return sum(
|
||||
0
|
||||
if unicodedata.combining(char)
|
||||
else 2
|
||||
if unicodedata.east_asian_width(char) in {"W", "F"}
|
||||
else 1
|
||||
for char in text
|
||||
)
|
||||
|
||||
|
||||
def filter_choices(choices: Iterable[SkillChoice], query: str) -> list[SkillChoice]:
|
||||
@@ -24,12 +57,14 @@ def filter_choices(choices: Iterable[SkillChoice], query: str) -> list[SkillChoi
|
||||
if needle in choice.name.casefold()
|
||||
or needle in choice.kind.casefold()
|
||||
or needle in choice.description.casefold()
|
||||
or needle in choice.readonly_status.casefold()
|
||||
]
|
||||
|
||||
|
||||
def select_skills(
|
||||
choices: list[SkillChoice],
|
||||
*,
|
||||
scope_label: str = "当前作用域",
|
||||
wrapper: Callable[..., set[str] | None] | None = None,
|
||||
) -> set[str] | None:
|
||||
"""Open the selector. Return names, or None when cancelled."""
|
||||
@@ -41,36 +76,103 @@ def select_skills(
|
||||
except ImportError as exc:
|
||||
raise RuntimeError("当前 Python 环境不支持 curses，无法打开交互界面") from exc
|
||||
|
||||
selected = {choice.name for choice in choices if choice.installed}
|
||||
selected = {
|
||||
choice.name
|
||||
for choice in choices
|
||||
if choice.installed and not choice.children
|
||||
}
|
||||
|
||||
def mark_for(choice: SkillChoice) -> str:
|
||||
if not choice.children:
|
||||
return "x" if choice.name in selected else " "
|
||||
selected_children = selected.intersection(choice.children)
|
||||
if len(selected_children) == len(choice.children):
|
||||
return "x"
|
||||
return "-" if selected_children else " "
|
||||
|
||||
def draw(stdscr: object) -> set[str] | None:
|
||||
curses.curs_set(0)
|
||||
stdscr.keypad(True)
|
||||
current = 0
|
||||
query = ""
|
||||
source_attr = curses.A_NORMAL
|
||||
status_attr = curses.A_NORMAL
|
||||
description_attr = curses.A_DIM
|
||||
try:
|
||||
if curses.has_colors():
|
||||
curses.start_color()
|
||||
curses.use_default_colors()
|
||||
curses.init_pair(1, curses.COLOR_CYAN, -1)
|
||||
curses.init_pair(2, curses.COLOR_GREEN, -1)
|
||||
source_attr = curses.color_pair(1)
|
||||
status_attr = curses.color_pair(2)
|
||||
except curses.error:
|
||||
pass
|
||||
|
||||
while True:
|
||||
visible = filter_choices(choices, query)
|
||||
current = min(current, max(0, len(visible) - 1))
|
||||
stdscr.erase()
|
||||
height, width = stdscr.getmaxyx()
|
||||
header = "↑/↓ 移动 Space 勾选 / 搜索 Enter 安装 q 取消"
|
||||
stdscr.addnstr(0, 0, header, max(0, width - 1))
|
||||
text_width = max(0, width - 1)
|
||||
stdscr.addnstr(
|
||||
0,
|
||||
0,
|
||||
fit_to_width(f"安装目标: {scope_label}", text_width),
|
||||
text_width,
|
||||
)
|
||||
header = "↑↓ 移动 Space 选择 / 搜索 Enter 安装 q 退出"
|
||||
stdscr.addnstr(1, 0, fit_to_width(header, text_width), text_width)
|
||||
if query:
|
||||
stdscr.addnstr(1, 0, f"搜索: {query}", max(0, width - 1))
|
||||
stdscr.addnstr(
|
||||
2,
|
||||
0,
|
||||
fit_to_width(f"搜索: {query}", text_width),
|
||||
text_width,
|
||||
)
|
||||
|
||||
rows = max(1, height - 4)
|
||||
start = max(0, current - rows + 1)
|
||||
for row, choice in enumerate(visible[start : start + rows], start=2):
|
||||
index = start + row - 2
|
||||
mark = "x" if choice.name in selected else " "
|
||||
suffix = f" · {choice.description}" if choice.description else ""
|
||||
line = f"[{mark}] {choice.name} {choice.kind}{suffix}"
|
||||
attr = curses.A_REVERSE if index == current else curses.A_NORMAL
|
||||
stdscr.addnstr(row, 0, line, max(0, width - 1), attr)
|
||||
item_capacity = max(1, (height - 4) // 3)
|
||||
start = max(0, current - item_capacity + 1)
|
||||
for offset, choice in enumerate(visible[start : start + item_capacity]):
|
||||
index = start + offset
|
||||
row = 3 + offset * 3
|
||||
mark = mark_for(choice)
|
||||
description = f" {choice.description}" if choice.description else ""
|
||||
focus_attr = curses.A_REVERSE if index == current else curses.A_NORMAL
|
||||
parts = [
|
||||
(f"{' ' * choice.indent}[{mark}] ", focus_attr),
|
||||
(choice.name, focus_attr | curses.A_BOLD),
|
||||
(f" {choice.kind}", focus_attr | source_attr),
|
||||
]
|
||||
if choice.readonly_status:
|
||||
parts.append(
|
||||
(f" {choice.readonly_status}", focus_attr | status_attr)
|
||||
)
|
||||
column = 0
|
||||
for text, attr in parts:
|
||||
available = text_width - column
|
||||
if available <= 0:
|
||||
break
|
||||
fitted = fit_to_width(text, available)
|
||||
stdscr.addnstr(row, column, fitted, available, attr)
|
||||
column += display_width(fitted)
|
||||
stdscr.addnstr(
|
||||
row + 1,
|
||||
0,
|
||||
fit_to_width(description, text_width),
|
||||
text_width,
|
||||
focus_attr | description_attr,
|
||||
)
|
||||
|
||||
footer = f"已选择 {len(selected)} 项"
|
||||
stdscr.addnstr(height - 1, 0, footer, max(0, width - 1))
|
||||
footer = (
|
||||
f"已选择 {len(selected)} 项 · 取消选择不卸载，卸载用 skiff remove"
|
||||
)
|
||||
stdscr.addnstr(
|
||||
height - 1,
|
||||
0,
|
||||
fit_to_width(footer, text_width),
|
||||
text_width,
|
||||
)
|
||||
stdscr.refresh()
|
||||
key = stdscr.get_wch()
|
||||
|
||||
@@ -83,11 +185,18 @@ def select_skills(
|
||||
elif key == curses.KEY_DOWN and visible:
|
||||
current = (current + 1) % len(visible)
|
||||
elif key == " " and visible:
|
||||
name = visible[current].name
|
||||
selected.symmetric_difference_update({name})
|
||||
choice = visible[current]
|
||||
if choice.children:
|
||||
children = set(choice.children)
|
||||
if children.issubset(selected):
|
||||
selected.difference_update(children)
|
||||
else:
|
||||
selected.update(children)
|
||||
else:
|
||||
selected.symmetric_difference_update({choice.name})
|
||||
elif key == "/":
|
||||
curses.curs_set(1)
|
||||
query = _read_query(stdscr, curses, width)
|
||||
query = _read_query(stdscr, curses, width, row=2)
|
||||
curses.curs_set(0)
|
||||
current = 0
|
||||
|
||||
@@ -95,12 +204,18 @@ def select_skills(
|
||||
return runner(draw)
|
||||
|
||||
|
||||
def _read_query(stdscr: object, curses: object, width: int) -> str:
|
||||
def _read_query(stdscr: object, curses: object, width: int, *, row: int = 1) -> str:
|
||||
query = ""
|
||||
while True:
|
||||
stdscr.move(1, 0)
|
||||
stdscr.move(row, 0)
|
||||
stdscr.clrtoeol()
|
||||
stdscr.addnstr(1, 0, f"搜索: {query}", max(0, width - 1))
|
||||
text_width = max(0, width - 1)
|
||||
stdscr.addnstr(
|
||||
row,
|
||||
0,
|
||||
fit_to_width(f"搜索: {query}", text_width),
|
||||
text_width,
|
||||
)
|
||||
stdscr.refresh()
|
||||
key = stdscr.get_wch()
|
||||
if key in ("\n", "\r") or key == curses.KEY_ENTER:
|
||||
|
||||
+95
-50
@@ -6,15 +6,19 @@ import re
|
||||
from pathlib import Path
|
||||
|
||||
from skiff.paths import SKILLS_DIR, TEMPLATE_DIR, ensure_skills_home
|
||||
from skiff.registry import (
|
||||
external_collection_skill_path,
|
||||
external_skill_path,
|
||||
load_registry,
|
||||
from skiff.catalog import (
|
||||
catalog_skill_path,
|
||||
discover_catalog_skills,
|
||||
load_catalog,
|
||||
)
|
||||
from skiff.sources import (
|
||||
discover_source_skills,
|
||||
list_source_skills,
|
||||
load_sources,
|
||||
)
|
||||
from skiff.sources import list_source_skills, load_sources, source_skills_root
|
||||
|
||||
|
||||
def list_owned_skills() -> list[str]:
|
||||
def list_builtin_skills() -> list[str]:
|
||||
ensure_skills_home()
|
||||
if not SKILLS_DIR.is_dir():
|
||||
return []
|
||||
@@ -29,19 +33,31 @@ def list_owned_skills() -> list[str]:
|
||||
return names
|
||||
|
||||
|
||||
def owned_skill_path(name: str) -> Path:
|
||||
def builtin_skill_path(name: str) -> Path:
|
||||
path = SKILLS_DIR / name
|
||||
if not (path / "SKILL.md").is_file():
|
||||
raise SystemExit(f"自研 skill 不存在: {name}")
|
||||
raise SystemExit(f"builtin skill 不存在: {name}")
|
||||
return path
|
||||
|
||||
|
||||
def normalize_source(source: str | None) -> str | None:
|
||||
if source == "owned":
|
||||
return "builtin"
|
||||
if source == "registry":
|
||||
return "catalog"
|
||||
if source and source.startswith("registry:"):
|
||||
return f"catalog:{source.split(':', 1)[1]}"
|
||||
return source
|
||||
|
||||
|
||||
def split_skill_spec(spec: str, source: str | None = None) -> tuple[str, str | None]:
|
||||
if "/" not in spec:
|
||||
return spec, source
|
||||
return spec, normalize_source(source)
|
||||
qualified_source, name = spec.split("/", 1)
|
||||
if not qualified_source or not name or "/" in name:
|
||||
raise SystemExit(f"skill 限定名称无效: {spec!r}（应为 source/name）")
|
||||
qualified_source = normalize_source(qualified_source)
|
||||
source = normalize_source(source)
|
||||
if source and source != qualified_source:
|
||||
raise SystemExit(
|
||||
f"skill 来源冲突: {spec!r} 与 --source {source!r} 不一致"
|
||||
@@ -63,42 +79,36 @@ def resolve_skill_source(name: str, *, source: str | None = None) -> tuple[Path,
|
||||
ensure_skills_home()
|
||||
name, source = split_skill_spec(name, source)
|
||||
|
||||
owned = SKILLS_DIR / name
|
||||
if source == "owned":
|
||||
if not (owned / "SKILL.md").is_file():
|
||||
raise SystemExit(f"owned source 中找不到 skill: {name}")
|
||||
return owned, "owned"
|
||||
builtin = SKILLS_DIR / name
|
||||
if source == "builtin":
|
||||
if not (builtin / "SKILL.md").is_file():
|
||||
raise SystemExit(f"builtin source 中找不到 skill: {name}")
|
||||
return builtin, "builtin"
|
||||
|
||||
registry = load_registry()
|
||||
catalog = load_catalog()
|
||||
sources = load_sources()
|
||||
registry_collection = None
|
||||
if source and source.startswith("registry:"):
|
||||
registry_collection = source.split(":", 1)[1]
|
||||
elif (
|
||||
source
|
||||
and source not in ("owned", "registry")
|
||||
and source in registry
|
||||
and source not in sources
|
||||
):
|
||||
registry_collection = source
|
||||
if registry_collection:
|
||||
path = external_collection_skill_path(
|
||||
registry_collection,
|
||||
name,
|
||||
registry[registry_collection],
|
||||
)
|
||||
return path, f"registry:{registry_collection}"
|
||||
if source and source.startswith("catalog:"):
|
||||
provider = source.split(":", 1)[1]
|
||||
if provider not in catalog:
|
||||
raise SystemExit(f"catalog 中找不到 source: {provider}")
|
||||
skills = discover_catalog_skills(provider, catalog[provider])
|
||||
if name not in skills:
|
||||
available = ", ".join(skills) or "(无)"
|
||||
raise SystemExit(
|
||||
f"catalog source {provider!r} 中找不到 skill {name!r}。可用: {available}"
|
||||
)
|
||||
return skills[name], f"catalog:{provider}"
|
||||
|
||||
if source == "registry":
|
||||
if name not in registry:
|
||||
raise SystemExit(f"registry 中找不到 skill: {name}")
|
||||
path = external_skill_path(name, registry[name])
|
||||
if source == "catalog":
|
||||
if name not in catalog:
|
||||
raise SystemExit(f"catalog 中找不到 skill source: {name}")
|
||||
path = catalog_skill_path(name, catalog[name])
|
||||
if not (path / "SKILL.md").is_file():
|
||||
raise SystemExit(
|
||||
f"外部 skill {name!r} 尚未 fetch 或 path 中缺少 SKILL.md。"
|
||||
f"catalog skill {name!r} 尚未 fetch 或 path 中缺少 SKILL.md。"
|
||||
f"请运行: skiff fetch {name}"
|
||||
)
|
||||
return path, "registry"
|
||||
return path, f"catalog:{name}"
|
||||
|
||||
if source:
|
||||
if source not in sources:
|
||||
@@ -106,28 +116,47 @@ def resolve_skill_source(name: str, *, source: str | None = None) -> tuple[Path,
|
||||
f"项目依赖 source {source!r}，但本机尚未配置。"
|
||||
f"请运行: skiff source add {source} <repo>"
|
||||
)
|
||||
path = source_skills_root(source, sources[source]) / name
|
||||
if not (path / "SKILL.md").is_file():
|
||||
skills = discover_source_skills(source, sources[source])
|
||||
if name not in skills:
|
||||
raise SystemExit(f"source {source!r} 中找不到 skill: {name}")
|
||||
return path, source
|
||||
return skills[name], source
|
||||
|
||||
candidates: list[tuple[Path, str]] = []
|
||||
if (owned / "SKILL.md").is_file():
|
||||
candidates.append((owned, "owned"))
|
||||
if name in registry:
|
||||
candidates.append((external_skill_path(name, registry[name]), "registry"))
|
||||
if (builtin / "SKILL.md").is_file():
|
||||
candidates.append((builtin, "builtin"))
|
||||
if name in catalog:
|
||||
path = catalog_skill_path(name, catalog[name])
|
||||
if (path / "SKILL.md").is_file() or not path.exists():
|
||||
candidates.append((path, f"catalog:{name}"))
|
||||
for provider, entry in catalog.items():
|
||||
if provider == name:
|
||||
continue
|
||||
skills = discover_catalog_skills(provider, entry)
|
||||
if name in skills:
|
||||
candidates.append((skills[name], f"catalog:{provider}"))
|
||||
for source_name, entry in sources.items():
|
||||
path = source_skills_root(source_name, entry) / name
|
||||
if (path / "SKILL.md").is_file():
|
||||
candidates.append((path, source_name))
|
||||
skills = discover_source_skills(source_name, entry)
|
||||
if name in skills:
|
||||
candidates.append((skills[name], source_name))
|
||||
|
||||
unique_candidates: list[tuple[Path, str]] = []
|
||||
seen_paths: set[Path] = set()
|
||||
for path, candidate_source in candidates:
|
||||
resolved = path.resolve()
|
||||
if resolved in seen_paths:
|
||||
continue
|
||||
seen_paths.add(resolved)
|
||||
unique_candidates.append((path, candidate_source))
|
||||
candidates = unique_candidates
|
||||
|
||||
if len(candidates) > 1:
|
||||
choices = ", ".join(f"{candidate_source}/{name}" for _, candidate_source in candidates)
|
||||
raise SystemExit(f"skill 名称存在多个来源，请明确指定: {choices}")
|
||||
if candidates:
|
||||
path, resolved_source = candidates[0]
|
||||
if resolved_source == "registry" and not path.exists():
|
||||
raise SystemExit(f"外部 skill {name!r} 尚未 fetch。请先运行: skiff fetch {name}")
|
||||
if resolved_source.startswith("catalog:") and not path.exists():
|
||||
provider = resolved_source.split(":", 1)[1]
|
||||
raise SystemExit(f"catalog source {provider!r} 尚未 fetch。请先运行: skiff fetch {provider}")
|
||||
return path, resolved_source
|
||||
|
||||
raise SystemExit(f"找不到 skill: {name}")
|
||||
@@ -196,8 +225,24 @@ def validate_skill_dir(skill_dir: Path, expected_name: str) -> list[str]:
|
||||
"""返回 skill 目录中的校验问题；空列表表示通过。"""
|
||||
issues: list[str] = []
|
||||
skill_md = skill_dir / "SKILL.md"
|
||||
readme = skill_dir / "README.md"
|
||||
if not skill_md.is_file():
|
||||
return ["缺少 SKILL.md"]
|
||||
if not readme.is_file():
|
||||
issues.append("缺少 README.md（面向人类的使用说明）")
|
||||
else:
|
||||
readme_text = readme.read_text(encoding="utf-8")
|
||||
if not readme_text.strip():
|
||||
issues.append("README.md 为空")
|
||||
if re.search(r"^#\s+skill-name\s*$", readme_text, re.MULTILINE):
|
||||
issues.append("README.md 存在模板占位内容: skill-name")
|
||||
for placeholder in (
|
||||
"用一句话告诉使用者这个 skill 能解决什么问题",
|
||||
"给出用户可以直接说出的典型请求",
|
||||
"给出一条可以直接交给 Agent 的示例请求",
|
||||
):
|
||||
if placeholder in readme_text:
|
||||
issues.append(f"README.md 存在模板占位内容: {placeholder}")
|
||||
|
||||
text = skill_md.read_text(encoding="utf-8")
|
||||
if not text.strip():
|
||||
|
||||
@@ -0,0 +1,217 @@
|
||||
# Skill 来源模型
|
||||
|
||||
## 背景
|
||||
|
||||
skiff 当前使用 `owned` 表示本仓库 `skills/` 中维护的 Skill，同时还支持
|
||||
`registry` 外部仓库和用户配置的 custom source。
|
||||
|
||||
这些名称混合了不同维度：
|
||||
|
||||
- `owned` 表示所有权。
|
||||
- `registry` 表示来源配置存放在哪里。
|
||||
- `external` 表示内容不在当前仓库。
|
||||
- `collection` 表示一个来源中包含多个 Skill。
|
||||
|
||||
它们不能作为同一层级的互斥类型。例如 custom source 既可能来自外部 Git 仓库，
|
||||
也可能是 collection；因此 `custom` 与 `external` 并不互斥。
|
||||
|
||||
本文建议将用户可见的来源注册方式统一为三类：
|
||||
|
||||
- `builtin`：随当前 skiff 仓库提供的 Skill。
|
||||
- `catalog:<name>`：由 skiff 自带目录预先登记的来源。
|
||||
- `custom:<name>`：用户在本机显式配置的命名来源。
|
||||
|
||||
来源注册方式与获取方式、仓库布局相互独立。builtin、catalog 和 custom 中的任意
|
||||
来源都可以包含一个或多个 Skill；除 builtin 外，catalog 和 custom 都可以使用
|
||||
Git 仓库或本地目录。
|
||||
|
||||
## 迁移前模型
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
S[skiff 可发现的 Skills]
|
||||
|
||||
S --> O["owned<br/>~/.skills/skills/*"]
|
||||
S --> C["custom source<br/>~/.config/skiff/config.yaml"]
|
||||
S --> R["registry<br/>registry.yaml"]
|
||||
|
||||
O --> O1["本仓库维护<br/>随 skiff 一起分发"]
|
||||
|
||||
C --> C1["本地目录<br/>--local PATH"]
|
||||
C --> C2["指定 Git 仓库<br/>repo + skills_path"]
|
||||
|
||||
R --> R1["外部单 Skill 仓库"]
|
||||
R --> R2["外部 Skill Collection"]
|
||||
R1 --> E["~/.local/share/skills/externals/"]
|
||||
R2 --> E
|
||||
```
|
||||
|
||||
迁移前实现中：
|
||||
|
||||
- `list` 和 `status` 支持 owned、registry 和 custom source。
|
||||
- `resolve_skill_source` 可以解析三种来源并处理同名歧义。
|
||||
- `select` 只组装 owned 和 registry 条目，尚未展示 custom source。
|
||||
- `.skills.yaml` 默认将未声明来源的 Skill 解释为 `owned`。
|
||||
- custom source 的 `skills_path` 已经可以包含多个 Skill，本质上也是 collection。
|
||||
|
||||
## 现行模型
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[Skill Provider]
|
||||
|
||||
A --> B["builtin<br/>仓库内隐式注册"]
|
||||
A --> C["catalog:waza<br/>skiff 预置目录"]
|
||||
A --> D["custom:company<br/>用户本机配置"]
|
||||
|
||||
B --> B1["skills/ack"]
|
||||
B --> B2["skills/skiff"]
|
||||
B --> B3["skills/deb-publisher"]
|
||||
|
||||
C --> C1["Git 或本地目录"]
|
||||
C1 --> C2["单 Skill"]
|
||||
C1 --> C3["Collection"]
|
||||
C3 --> C4["waza/think"]
|
||||
C3 --> C5["waza/check"]
|
||||
|
||||
D --> D1["Git 或本地目录"]
|
||||
D1 --> D2["单 Skill"]
|
||||
D1 --> D3["Collection"]
|
||||
D3 --> D4["company/security-review"]
|
||||
D3 --> D5["company/release"]
|
||||
```
|
||||
|
||||
### 来源注册方式
|
||||
|
||||
| 类型 | 含义 | 配置来源 | 用户界面展示 |
|
||||
| --- | --- | --- | --- |
|
||||
| `builtin` | 随当前 skiff 仓库提供 | `skills/` | `builtin` |
|
||||
| `catalog` | skiff 预先登记、所有用户可发现的来源 | `catalog.yaml` | `catalog:<name>` |
|
||||
| `custom` | 用户在本机显式注册的命名来源 | `~/.config/skiff/config.yaml` | `custom:<name>` |
|
||||
|
||||
`builtin` 比 `owned` 更适合作为用户可见名称，因为它表达 Skill 的分发位置和可用
|
||||
方式，而不是仓库的所有权关系。
|
||||
|
||||
`catalog` 比 `registry` 更准确：当前文件只是 skiff 随仓库维护的预置来源目录，
|
||||
并不是远程注册中心，也不是一种 Skill 来源协议。
|
||||
|
||||
### 三个正交维度
|
||||
|
||||
每个 provider 应由三个维度描述：
|
||||
|
||||
```text
|
||||
registration: builtin | catalog | custom
|
||||
transport: bundled | local | git
|
||||
layout: single | collection
|
||||
```
|
||||
|
||||
custom source 示例：
|
||||
|
||||
```text
|
||||
registration: custom
|
||||
name: company
|
||||
transport: local | git
|
||||
layout: single | collection
|
||||
```
|
||||
|
||||
catalog entry 示例：
|
||||
|
||||
```text
|
||||
registration: catalog
|
||||
name: waza
|
||||
transport: local | git
|
||||
layout: single | collection
|
||||
```
|
||||
|
||||
`external` 只适合描述物理位置，可作为 catalog 和部分 custom provider 的统称，
|
||||
不应成为与 builtin、custom 并列的持久化类型。
|
||||
|
||||
## `select` 展示
|
||||
|
||||
`skiff select` 应同时展示 builtin、catalog 和 custom Skill：
|
||||
|
||||
```text
|
||||
[ ] ack builtin
|
||||
[ ] deb-publisher builtin
|
||||
[-] company custom source
|
||||
[ ] company/release custom:company
|
||||
[ ] company/security-review custom:company
|
||||
[-] waza catalog source
|
||||
[ ] waza/check catalog:waza
|
||||
[ ] waza/think catalog:waza
|
||||
```
|
||||
|
||||
建议遵循以下规则：
|
||||
|
||||
- builtin Skill 直接显示 Skill 名称。
|
||||
- catalog 和 custom collection 都使用来源名称作为父节点。
|
||||
- catalog 和 custom Skill 都使用 `<source>/<skill>` 作为选择器键。
|
||||
- 单 Skill 来源可以省略父节点，但仍显示注册方式和来源名称。
|
||||
- 不同来源安装后名称相同时，继续拒绝同时选择，避免覆盖同一安装路径。
|
||||
|
||||
## 配置表示
|
||||
|
||||
新写入的 `.skills.yaml` 使用以下形式：
|
||||
|
||||
```yaml
|
||||
skills:
|
||||
- name: ack
|
||||
source: builtin
|
||||
- name: security-review
|
||||
source: company
|
||||
- name: think
|
||||
source: catalog:waza
|
||||
```
|
||||
|
||||
custom source 在 manifest 中继续保存其逻辑名称，例如 `company`。这样不同机器可以
|
||||
独立配置仓库地址，而项目只依赖稳定的来源名称。
|
||||
|
||||
## 兼容策略
|
||||
|
||||
用户可见术语已经调整，并保留以下读取兼容，避免已有项目立即失效：
|
||||
|
||||
1. 对外文档、CLI 输出和 selector 统一使用 `builtin`、`catalog:<name>` 和
|
||||
`custom:<name>`。
|
||||
2. 新生成的 `.skills.yaml` 对内置 Skill 写入 `source: builtin`。
|
||||
3. 读取旧 manifest 时继续接受 `source: owned`，并在解析时归一化为 `builtin`。
|
||||
4. CLI 参数在过渡期继续接受 `--source owned`，但帮助和输出只推荐 `builtin`。
|
||||
5. 读取旧 manifest 中的 `source: registry` 和 `registry: <name>`，归一化为
|
||||
`catalog:<name>`。
|
||||
6. 主文件使用 `catalog.yaml`；不存在时兼容读取旧 `registry.yaml`。
|
||||
7. custom source 的逻辑名称和现有 `config.yaml` 结构保持不变。
|
||||
8. 将 `builtin`、`catalog` 和兼容别名 `owned`、`registry` 设为 custom source
|
||||
保留字。
|
||||
9. `select` 同步接入 custom Skill，并让 custom collection 与 catalog collection
|
||||
使用相同的父子展示逻辑。
|
||||
|
||||
## 实现范围
|
||||
|
||||
当前实现覆盖：
|
||||
|
||||
- `skiff/skills.py`：来源解析、归一化和 builtin 命名。
|
||||
- `skiff/project.py`：manifest 默认值、序列化与旧值兼容。
|
||||
- `skiff/sources.py`：来源保留字。
|
||||
- `skiff/catalog.py`：catalog 配置、checkout 与 Skill 发现。
|
||||
- `skiff/cli.py`：`list`、`status`、`add`、`select` 和输出文案。
|
||||
- `skiff/selector.py`：统一 catalog/custom collection 的父子展示。
|
||||
- CLI 与来源解析测试。
|
||||
- 根 README、`skiff/README.md`、`skills/skiff/SKILL.md` 和相关示例。
|
||||
|
||||
## 验证要求
|
||||
|
||||
实施完成后至少覆盖：
|
||||
|
||||
- builtin Skill 可以通过新名称列出、选择、安装和写入 manifest。
|
||||
- 旧的 `source: owned` manifest 仍可同步。
|
||||
- custom local source 和 custom Git source 都出现在 selector 中。
|
||||
- catalog 单 Skill 和 Collection 都保持可选择。
|
||||
- custom 单 Skill 和 Collection 都保持可选择。
|
||||
- 多来源同名 Skill 必须显式指定来源。
|
||||
- 两个选择最终安装为同一个名称时，selector 拒绝冲突。
|
||||
- `list`、`status`、`select` 对同一来源使用一致术语。
|
||||
|
||||
## 设计前提
|
||||
|
||||
迁移前 `registry.yaml` 的真实职责只是维护 skiff 预置的来源目录，而不是提供远程
|
||||
发布、版本解析或可信签名等注册中心能力，因此现已改为 `catalog.yaml`。如果未来
|
||||
实现真正的远程 registry，应单独定义其协议和与 catalog 的同步关系，不复用旧名称。
|
||||
+26
-8
@@ -9,7 +9,7 @@ from typing import Any
|
||||
from skiff import yaml_io
|
||||
from skiff.paths import CONFIG_FILE, SOURCES_DIR
|
||||
|
||||
RESERVED_SOURCES = {"owned", "registry"}
|
||||
RESERVED_SOURCES = {"builtin", "catalog", "owned", "registry"}
|
||||
|
||||
|
||||
def validate_source_name(name: str) -> None:
|
||||
@@ -68,15 +68,23 @@ def source_skills_root(name: str, entry: dict[str, Any]) -> Path:
|
||||
return root
|
||||
|
||||
|
||||
def list_source_skills(name: str, entry: dict[str, Any]) -> list[str]:
|
||||
def discover_source_skills(name: str, entry: dict[str, Any]) -> dict[str, Path]:
|
||||
root = source_skills_root(name, entry)
|
||||
if (root / "SKILL.md").is_file():
|
||||
return {name: root}
|
||||
if not root.is_dir():
|
||||
return []
|
||||
return [
|
||||
item.name
|
||||
return {}
|
||||
return {
|
||||
item.name: item
|
||||
for item in sorted(root.iterdir())
|
||||
if item.is_dir() and not item.name.startswith("_") and (item / "SKILL.md").is_file()
|
||||
]
|
||||
if item.is_dir()
|
||||
and not item.name.startswith("_")
|
||||
and (item / "SKILL.md").is_file()
|
||||
}
|
||||
|
||||
|
||||
def list_source_skills(name: str, entry: dict[str, Any]) -> list[str]:
|
||||
return list(discover_source_skills(name, entry))
|
||||
|
||||
|
||||
def fetch_source(name: str, entry: dict[str, Any]) -> Path:
|
||||
@@ -100,7 +108,17 @@ def fetch_source(name: str, entry: dict[str, Any]) -> Path:
|
||||
else:
|
||||
checkout.parent.mkdir(parents=True, exist_ok=True)
|
||||
subprocess.run(
|
||||
["git", "clone", "--branch", ref, "--", str(repo), str(checkout)],
|
||||
[
|
||||
"git",
|
||||
"clone",
|
||||
"--depth",
|
||||
"1",
|
||||
"--branch",
|
||||
ref,
|
||||
"--",
|
||||
str(repo),
|
||||
str(checkout),
|
||||
],
|
||||
check=True,
|
||||
)
|
||||
return checkout
|
||||
|
||||
+4
-1
@@ -68,6 +68,9 @@ def find_repo_root(start: Path | None = None) -> Path | None:
|
||||
for directory in [start, *start.parents]:
|
||||
if (directory / ".skills.yaml").is_file():
|
||||
return directory
|
||||
if (directory / "skills").is_dir() and (directory / "registry.yaml").is_file():
|
||||
if (directory / "skills").is_dir() and (
|
||||
(directory / "catalog.yaml").is_file()
|
||||
or (directory / "registry.yaml").is_file()
|
||||
):
|
||||
return directory
|
||||
return None
|
||||
|
||||
@@ -0,0 +1,28 @@
|
||||
# skill-name
|
||||
|
||||
用一句话告诉使用者这个 skill 能解决什么问题。
|
||||
|
||||
## 什么时候使用
|
||||
|
||||
- 给出用户可以直接说出的典型请求。
|
||||
- 说明适用范围。
|
||||
|
||||
## 使用前准备
|
||||
|
||||
- 列出需要用户提前提供或确认的信息、权限和依赖。
|
||||
|
||||
## 使用示例
|
||||
|
||||
```text
|
||||
给出一条可以直接交给 Agent 的示例请求。
|
||||
```
|
||||
|
||||
## Agent 会做什么
|
||||
|
||||
1. 用面向使用者的语言概括主要步骤。
|
||||
2. 说明可能发生的外部写操作或重要边界。
|
||||
|
||||
## 如何判断完成
|
||||
|
||||
- 说明使用者最终会得到什么，以及如何确认结果正确。
|
||||
|
||||
@@ -0,0 +1,237 @@
|
||||
# ACK
|
||||
|
||||
ACK 是一个显式调用的 Agent Skill，用三种独立角色运行工程协作闭环：
|
||||
|
||||
- Coordinator 拆解需求、派发任务并终检。
|
||||
- Developer 实现并执行白盒验证。
|
||||
- Test 独立执行黑盒复测。
|
||||
|
||||
关键约束是验证者不等于实现者。每个任务最多修复三轮，仍未通过时记录为
|
||||
`leftover`，然后继续处理其它任务。
|
||||
|
||||
项目还可以声明一个可选的交付阶段：任务全部验证后，ACK 按项目维护的 profile
|
||||
构建 DEB 或镜像、发布产物、创建 PR，并在授权范围内部署。交付配置默认关闭，
|
||||
稳定发布与生产部署始终保留人工批准点。
|
||||
|
||||
## 安装
|
||||
|
||||
全局安装：
|
||||
|
||||
```bash
|
||||
skiff add ack -g
|
||||
```
|
||||
|
||||
或只安装到当前项目：
|
||||
|
||||
```bash
|
||||
skiff add ack
|
||||
```
|
||||
|
||||
ACK 只在用户显式调用 `/ack` 或 `$ack` 时运行。
|
||||
|
||||
## 初始化项目
|
||||
|
||||
```bash
|
||||
skiff init ack
|
||||
skiff init ack --project ~/code/my-app
|
||||
```
|
||||
|
||||
初始化后，项目只保存自己的 ACK 状态：
|
||||
|
||||
```text
|
||||
docs/ack/
|
||||
├── project.md
|
||||
├── tasks.yaml
|
||||
├── knowledge.yaml
|
||||
└── delivery.yaml # 默认 enabled: false
|
||||
```
|
||||
|
||||
不会在项目中复制或链接 ACK Skill。通用规范、模板和脚本始终从已安装的 Skill
|
||||
目录读取。
|
||||
|
||||
## Skill 结构
|
||||
|
||||
```text
|
||||
skills/ack/
|
||||
├── SKILL.md
|
||||
├── README.md
|
||||
├── VERSION
|
||||
├── references/ # 三角色规范、闭环流程和初始化说明
|
||||
├── templates/ # project.md、tasks.yaml、knowledge.yaml、delivery.yaml 模板和 schema
|
||||
├── examples/ # 完整示例
|
||||
└── scripts/ # 状态校验、任务/知识选择、安全验证执行与结构化 worker launcher
|
||||
```
|
||||
|
||||
`SKILL.md` 是 Agent 的工作流入口。`references/` 是按需读取的稳定规范；
|
||||
`docs/ack/project.md` 只保存当前项目的命令、路径和权限差异；
|
||||
`docs/ack/tasks.yaml` 保存当前任务状态；`docs/ack/knowledge.yaml` 保存跨任务复用、
|
||||
已经独立验证的项目知识护栏。
|
||||
`docs/ack/delivery.yaml` 声明项目特有的构建、发布和部署能力；每次执行结果另记在
|
||||
`tasks.yaml.deliveryRuns`，配置与运行状态不会混在一起。
|
||||
|
||||
## 检查项目状态
|
||||
|
||||
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>
|
||||
```
|
||||
|
||||
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 \
|
||||
--task-id BUG-001
|
||||
|
||||
python3 <ack-skill-dir>/scripts/select_knowledge.py docs/ack/knowledge.yaml \
|
||||
--component web --path web/app.py --tag long-running-service --limit 10
|
||||
```
|
||||
|
||||
任务选择器会解析并执行完整任务板的内置语义校验，但只输出 `project`、`summary`、
|
||||
默认可工作状态或显式 `--task-id` 命中的任务，以及这些任务引用的 receipt 和 delivery
|
||||
run。默认最多 20 条，超过预算时显式失败；Agent 不应回退为把完整 `tasks.yaml` 注入
|
||||
上下文。
|
||||
|
||||
默认 JSON 输出会同时给出固定知识引用和已解析的 `verificationTarget.path/args`；
|
||||
选择器只输出数据，不执行检查。`scope.all=true` 的全项目 active 规则优先占用
|
||||
`--limit`；如果全项目规则本身超过预算，选择器会显式失败，不会静默漏派。
|
||||
|
||||
需要执行知识项引用的检查时，只传 registry ID 给 ACK 的安全执行入口：
|
||||
|
||||
```bash
|
||||
python3 <ack-skill-dir>/scripts/run_verification.py \
|
||||
docs/ack/knowledge.yaml check-api-contract --project-root <project-root>
|
||||
```
|
||||
|
||||
该入口会在执行前重新校验知识库，只打开一次项目根目录 fd，再从同一个 fd 逐段以
|
||||
`O_NOFOLLOW` 打开知识库和检查文件；检查内容复制到匿名、尽可能 sealed 的稳定
|
||||
快照，再以结构化 argv 和 `shell=False` 启动。它不接受临时命令或额外参数。
|
||||
选择器输出的 path/args 只用于审阅，不应由 Agent 自行拼接执行。Runner 只读取
|
||||
项目内无 symlink 的权威
|
||||
`docs/ack/knowledge.yaml`，不接受替代知识文件或放宽后的项目根。检查进程的 cwd
|
||||
和 `ACK_PROJECT_ROOT` 都固定到该根 fd；后者是只在检查进程存活期间有效的
|
||||
`/proc/self/fd/...` 或 `/dev/fd/...` 路径。原始可读路径另放在
|
||||
`ACK_PROJECT_ROOT_DISPLAY`，只能用于日志，不能用于资源访问。Runner 还提供
|
||||
`ACK_VERIFICATION_REF` 和 `ACK_VERIFICATION_PATH`；检查脚本必须据此定位资源，
|
||||
不能依赖 `$0` 或 `__file__` 所在目录，因为实际执行的是匿名快照。
|
||||
|
||||
知识先由 Developer 或 Test 作为 `candidate` 提名，经独立验证和 Coordinator gate
|
||||
后才能成为 `active`。Coordinator 按路径、组件、依赖、版本和标签推荐相关知识，
|
||||
确认后将固定 revision 的 `knowledgeRefs` 写入任务上下文；每轮只派发命中的少量
|
||||
条目，不全量注入知识库。
|
||||
|
||||
旧项目只有 `project.md` 和 `tasks.yaml` 时，不要重跑初始化。由 `/ack` 检查现有
|
||||
状态，获得用户授权后补一个空的 `knowledge.yaml`；如果任务板尚未声明知识库，
|
||||
同时只补 `project.knowledgeFile: docs/ack/knowledge.yaml`，再运行跨文件校验。
|
||||
|
||||
只有 Coordinator 写 `tasks.yaml` 和 `knowledge.yaml`。知识正文不能作为自由 shell
|
||||
执行；关键约束应继续下沉到测试、lint、CI 或正式规范。ACK 不自动修改项目的
|
||||
`AGENTS.md`、`CLAUDE.md` 或其它 Agent 指令文件。
|
||||
|
||||
## 配置与运行交付
|
||||
|
||||
用户可以直接向 `/ack` 描述项目差异，例如“这个项目用 `make deb` 构建 DEB，推到
|
||||
preview APT 源，再部署到开发机”。ACK 会把它维护成
|
||||
`docs/ack/delivery.yaml` 中的声明式 entrypoint、artifact、destination、environment
|
||||
和 profile，校验后展示 diff；首次配置保持关闭，确认后才启用。
|
||||
|
||||
交付配置只允许声明式工具 target 或仓库内可执行脚本，不接受自由 shell，也不保存
|
||||
凭据值。ACK 在任务进入 `verified` 后，按用户确认的 profile 执行，并把 revision、
|
||||
PR、产物摘要、部署目标、健康检查和日志引用写入 `tasks.yaml.deliveryRuns`。默认
|
||||
profile 只能停在 `review_ready`；稳定发布或生产部署必须经过对应 approval 步骤。
|
||||
具体契约见 `references/delivery.md`。
|
||||
|
||||
## 启动 Worker
|
||||
|
||||
worker 的机器配置位于 `tasks.yaml.project.orchestration`：项目显式维护模型
|
||||
allowlist、结构化 profile、默认 profile 和允许的 worktree。不得在 `project.md`
|
||||
或任务里保存完整启动命令、额外 argv 或环境变量。
|
||||
|
||||
先审阅计划，不产生终端：
|
||||
|
||||
```bash
|
||||
python3 <ack-skill-dir>/scripts/launch_worker.py plan \
|
||||
--project-root <project-root> \
|
||||
--task-id <task-id> \
|
||||
--attempt-id <task-id>-A<round> \
|
||||
--role developer \
|
||||
--profile-id codex-dev-standard \
|
||||
--worktree <allowed-worktree>
|
||||
```
|
||||
|
||||
确认后执行 `launch`，并显式绑定刚审阅的 fingerprint：
|
||||
|
||||
```bash
|
||||
python3 <ack-skill-dir>/scripts/launch_worker.py launch \
|
||||
--project-root <project-root> \
|
||||
--task-id <task-id> \
|
||||
--attempt-id <task-id>-A<round> \
|
||||
--role developer \
|
||||
--profile-id codex-dev-standard \
|
||||
--worktree <allowed-worktree> \
|
||||
--expected-launch-fingerprint <plan 中的 sha256:...>
|
||||
```
|
||||
|
||||
launcher 是自动创建 worker 的唯一入口：它从权威任务板重读 profile，构造固定
|
||||
argv，忽略调用者 PATH、使用环境 allowlist，并验证真实 Git worktree 注册；然后
|
||||
通过仓库外的单次启动记录、terminal-bound nonce/proof 和受限 bootstrap 调用 Orca。
|
||||
返回的 receipt 含 `runtimeId`、handle、incarnation、profile hash、slot 和 worktree
|
||||
identity。Coordinator 将 receipt 追加到顶层 `workerReceipts`，再把 receipt ID
|
||||
写入任务的 `dispatch.developer` 或 `dispatch.test`，并同步写入本轮 `attemptId`。
|
||||
校验器要求 receipt 与当前 ACK task、角色、profile 和 attempt 完全一致；历史 receipt
|
||||
不能跨任务或跨轮次改挂。
|
||||
|
||||
v0.10 自动 launcher 仅支持 `read-only` 与 `workspace-write`。full-access、
|
||||
Codex bypass、Cursor YOLO/force 和关闭 sandbox 都会 fail closed；在有可信平台
|
||||
审批或独立签发通道之前，不用项目文件伪装成用户授权。旧任务板没有结构化
|
||||
`project.orchestration` 时仍可读取和手动协作，但不得自动创建 worker。
|
||||
|
||||
持久化 `receiptHash` 是无密钥 checksum，不是 launcher 身份证明。由于 Orca 当前
|
||||
不能证明旧终端的原始 argv/模型/权限，v0.10 不自动复用既有 worker；每次自动派发
|
||||
都重新 `plan` 并用 expected fingerprint 启动 fresh worker。
|
||||
fingerprint 只校验完整计划没有漂移，不是一次性令牌；成功后不得用同一 fingerprint
|
||||
重复启动，结果不确定时必须先 reconcile。
|
||||
若创建或关闭回执不完整，或外部 launch record 状态无法可靠持久化，launcher 会返回
|
||||
`indeterminate/reconcile-required`；必须先核对 record 与 Orca live state，不能
|
||||
直接重试。
|
||||
|
||||
## 开始一个需求
|
||||
|
||||
初始化完成后可以直接说：
|
||||
|
||||
```text
|
||||
/ack 处理这个需求：<一句话需求>
|
||||
```
|
||||
|
||||
Coordinator 会先读取项目状态和 `references/kickoff.md`，生成产品文档、任务拆分与
|
||||
可观测验收信号；用户确认后才派发实现和复测。
|
||||
|
||||
首次配置交付可以说：
|
||||
|
||||
```text
|
||||
/ack 更新项目交付配置：用 make build-deb 构建 DEB，发布到 preview APT 仓库，
|
||||
部署到 test-server 并跑健康检查；完成后创建 PR，停在 review_ready 给我审核。
|
||||
```
|
||||
|
||||
之后处理需求时只需在确认计划中选择 profile：
|
||||
|
||||
```text
|
||||
/ack 处理这个需求：<一句话需求>。任务验证通过后执行 review profile。
|
||||
```
|
||||
|
||||
ACK 会自动读取 `delivery.yaml`，无需再逐步提醒它构建、上传、部署或开 PR；目标或
|
||||
权限发生漂移、缺少凭据、进入 stable/production approval 时才停下来请求决策。
|
||||
|
||||
## 版本
|
||||
|
||||
当前 Skill 版本见 `VERSION`。新项目在 `tasks.yaml` 中以合法 SemVer 记录
|
||||
`ackVersion`。从 `0.10.0` 起，`project.orchestration` 与顶层 `workerReceipts` 必须
|
||||
同时存在；从 `0.11.0` 起，新项目还会生成默认关闭的 `delivery.yaml`，并在任务板声明
|
||||
`project.deliveryFile` 与 `deliveryRuns`；从 `0.13.0` 起，Coordinator 使用
|
||||
`select_tasks.py` 获取有预算的任务上下文，不再把完整任务板注入模型。旧项目可以不迁移
|
||||
而继续使用原闭环。旧项目的 `kitVersion` 可以继续读取，但建议迁移为 `ackVersion`。
|
||||
@@ -0,0 +1,214 @@
|
||||
---
|
||||
name: ack
|
||||
description: >-
|
||||
初始化、检查并运行 ACK 三角色协作闭环。仅在用户显式调用 /ack 或 $ack，并要求
|
||||
初始化 ACK、检查 docs/ack 配置、按 ACK 规划需求、指挥 Coordinator/Developer/Test
|
||||
工作，或配置并执行任务验证后的项目交付流程时使用。
|
||||
---
|
||||
|
||||
# ACK 项目协作入口
|
||||
|
||||
本 Skill 是 ACK 的完整能力包：`references/` 保存通用规范，`templates/` 保存项目
|
||||
状态模板，`scripts/` 保存校验工具。目标项目只在 `docs/ack/` 保存 `project.md`、
|
||||
`tasks.yaml`、`knowledge.yaml` 和默认关闭的 `delivery.yaml`，不要复制或链接 Skill
|
||||
内容。
|
||||
|
||||
开始时解析当前 `SKILL.md` 所在目录，记为 `<ack-skill-dir>`。所有通用规范、模板和
|
||||
脚本都相对此目录访问，不依赖固定的全局安装路径。
|
||||
|
||||
## 选择模式
|
||||
|
||||
- 用户要求初始化、接入或安装 ACK：执行“初始化”。
|
||||
- 用户要求检查 ACK 是否可用、配置是否完整：执行“检查”。
|
||||
- 用户要求用 ACK 做需求、修复问题或继续任务：执行“工作”。
|
||||
- 用户用自然语言要求增加、修改或关闭项目交付流程：执行“交付配置维护”。
|
||||
|
||||
始终先解析真实项目根目录。优先使用 `git rev-parse --show-toplevel`；不是 Git
|
||||
项目时使用用户指定目录或当前目录。不要修改项目的 `AGENTS.md`、`CLAUDE.md`
|
||||
或其它 Agent 指令文件。
|
||||
|
||||
## 初始化
|
||||
|
||||
1. 确认 `skiff` 可执行，并检查 `<project>/docs/ack` 是否存在。
|
||||
2. 不存在时执行：
|
||||
|
||||
```bash
|
||||
skiff init ack --project <project-root>
|
||||
```
|
||||
|
||||
该命令从本 Skill 的 `templates/` 生成项目状态，不会在项目中创建 Skill
|
||||
软链接或资源副本。
|
||||
3. 如果 `docs/ack` 已存在，不重复初始化、不覆盖文件；转入“检查”。旧项目只有
|
||||
`project.md` 与 `tasks.yaml` 时，先报告缺少 `knowledge.yaml`。用户授权后，
|
||||
从 `templates/knowledge.template.yaml` 生成这个缺失文件并替换项目名和时间；若
|
||||
`tasks.yaml` 尚无 `project.knowledgeFile`，同时只补
|
||||
`docs/ack/knowledge.yaml` 这一项。不要重跑 `skiff init`，也不要改写其它已有
|
||||
项目状态。
|
||||
4. 读取项目的公开配置和文档，例如 README、语言清单、包管理清单、测试配置与
|
||||
CI，确定项目名、技术栈、源码/规格/测试路径及真实可执行命令。
|
||||
5. 完善 `docs/ack/project.md`：
|
||||
- 用实际项目值替换全部占位符。
|
||||
- 无服务地址时把 Base URL 写为 `n/a`，不要虚构端口。
|
||||
- 无法从项目证据确定的命令写为 `n/a`，并在结果中列为待配置项。
|
||||
- 只写项目差异，不复制 `references/` 中的通用规范。
|
||||
6. 完善 `docs/ack/tasks.yaml` 的项目信息。纯初始化且用户没有提供真实任务时，
|
||||
删除模板示例任务并保留 `tasks: []`；不要虚构需求或缺陷。
|
||||
7. 检查 `docs/ack/knowledge.yaml`。新项目没有已验证的项目经验时保留
|
||||
`verificationRegistry: {}` 与 `entries: []`，不从聊天、README 或单次失败中
|
||||
猜测并激活知识。
|
||||
8. 检查 `docs/ack/delivery.yaml`。新项目保留 `enabled: false`、空能力表和空 profile；
|
||||
不从 README 或 CI 猜测、启用交付。旧项目没有该文件时仍可继续使用原 ACK
|
||||
闭环；只有用户明确要求配置交付时，才按“交付配置维护”补齐。
|
||||
9. 更新 `updatedAt`，并运行：
|
||||
|
||||
```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>
|
||||
```
|
||||
|
||||
10. 检查 `project.md`、`tasks.yaml`、`knowledge.yaml` 与 `delivery.yaml` 是否仍有
|
||||
`<...>` 占位符。
|
||||
结构校验通过且必填项目事实完整时才称“初始化完成”；否则称“部分完成”并列出
|
||||
缺失值。
|
||||
11. 报告创建的路径、检测到的命令、校验结果和下一步。除非用户明确要求，不提交、
|
||||
不推送。
|
||||
|
||||
## 检查
|
||||
|
||||
1. 检查以下路径：
|
||||
- `docs/ack/project.md`
|
||||
- `docs/ack/tasks.yaml`
|
||||
- `docs/ack/knowledge.yaml`
|
||||
- `docs/ack/delivery.yaml`（旧项目可无；存在或被任务板引用时必须校验）
|
||||
需要查看任务内容时，使用 `<ack-skill-dir>/scripts/select_tasks.py` 解析完整任务板并
|
||||
只输出项目配置、摘要和可工作任务；不要用 `cat`、整文件 `sed` 或等价方式把完整
|
||||
`tasks.yaml` 注入上下文。完整性仍由校验器检查。
|
||||
2. 读取 `<ack-skill-dir>/VERSION`，对比 `tasks.yaml` 的 `ackVersion`。旧项目只有
|
||||
`kitVersion` 时仍可读取，但建议迁移为 `ackVersion`。`ackVersion` 必须是合法
|
||||
SemVer；从 `0.10.0` 起 `project.orchestration` 与顶层 `workerReceipts` 必须同时
|
||||
存在。
|
||||
3. 查找未替换占位符，并核对项目路径、覆盖层路径、Developer 白盒命令、Test
|
||||
黑盒命令和 Base URL。
|
||||
4. 使用 `<ack-skill-dir>/scripts/validate_tasks.py` 校验任务板，使用
|
||||
`<ack-skill-dir>/scripts/validate_knowledge.py docs/ack/knowledge.yaml --tasks
|
||||
docs/ack/tasks.yaml` 校验项目知识和跨文件引用。如果存在交付配置或任务板声明了
|
||||
`project.deliveryFile`，再使用 `<ack-skill-dir>/scripts/validate_delivery.py
|
||||
docs/ack/delivery.yaml --tasks docs/ack/tasks.yaml --project-root <project-root>`
|
||||
校验交付能力、顺序、安全边界和跨文件引用。只报告证据明确的问题，不因旧项目
|
||||
缺少可选交付配置而宣称失败。
|
||||
5. 若存在 `project.bugIntake`，运行
|
||||
`python3 <ack-skill-dir>/scripts/feishu_bug_intake.py check docs/ack/tasks.yaml`。
|
||||
它只接受 `feishu-base` 和显式 profile；详细的飞书配置、凭据初始化和读取方式见
|
||||
`references/feishu-bug-intake.md`。
|
||||
6. 检查知识引用能解析到固定 revision，candidate 仍留在任务证据中，且
|
||||
`stale`、`superseded` 和 `archived` 不会被当作可派发的 `active` 知识。
|
||||
7. 若存在 `project.orchestration`，检查 profile、model allowlist、默认 profile、
|
||||
允许 worktree、顶层 `workerReceipts` 与 `dispatch.developer/test` 的引用；receipt
|
||||
必须绑定当前 ACK task、同一 role/profile/attempt，`receiptId` 与 `attemptId`
|
||||
必须同时为空或同时填写。
|
||||
缺少结构化路由的旧任务板只能使用手动模式，不能自动创建 worker。
|
||||
8. 检查不会自动修复或覆盖现有配置；用户明确要求修复后再修改。
|
||||
|
||||
## 工作
|
||||
|
||||
1. 若 `docs/ack` 不存在，停止并建议先用 `/ack` 初始化；不要静默初始化。
|
||||
2. 依次读取：
|
||||
- `docs/ack/project.md`
|
||||
- 运行 `python3 <ack-skill-dir>/scripts/select_tasks.py docs/ack/tasks.yaml`，只读取
|
||||
`project`、`summary` 和默认可工作状态的任务；已知当前任务时传
|
||||
`--task-id <ack-task-id>`。选择器会解析并校验完整任务板，并只附带选中任务引用的
|
||||
receipt 与 delivery run。命中超过默认预算时用 `--task-id` / `--status` 缩小，
|
||||
不直接回退为输出完整 `tasks.yaml`。
|
||||
- 通过 `<ack-skill-dir>/scripts/select_knowledge.py` 从
|
||||
`docs/ack/knowledge.yaml` 选择的当前任务相关 `active` 条目
|
||||
- `<ack-skill-dir>/references/kickoff.md`
|
||||
- kickoff 指定且与当前任务相关的 references 文件
|
||||
- 若 `tasks.yaml.project.deliveryFile` 存在，再读取该 `delivery.yaml` 和
|
||||
`<ack-skill-dir>/references/delivery.md`
|
||||
3. 当前会话担任 Coordinator，遵守项目覆盖层中的命令、路径权限、模型路由和
|
||||
worker 启动规则。项目覆盖层优先于通用示例命令。按 scope 推荐相关 `active`
|
||||
知识，经确认后把固定 revision 的显式 `knowledgeRefs` 写入当前任务上下文；
|
||||
不全量注入知识库。
|
||||
`project.bugIntake.workflow` 为 `reviewed-writeback-v1` 时，按
|
||||
`references/feishu-bug-intake.md` 把飞书作为审核前的唯一协作区：先运行 check/plan，
|
||||
读取用户填写的 Bug；Coordinator 根据来源事实与项目上下文补全修复逻辑和可观测验收
|
||||
标准，只通过安全适配器写回同一飞书记录并回读确认。用户反馈后继续只在飞书修订。
|
||||
用户针对当前 `draftRevision` 明确审核通过前，不创建或刷新 `tasks.yaml` 任务、不启动
|
||||
worker、不派发 Developer/Test，也不修改应用代码。审核通过后重新读取，要求 revision
|
||||
与批准值完全一致，才通过 `import-approved` 生成规范 `taskDraft`，原样写入最终版本、
|
||||
`source.workflow`、`source.approvedRevision` 与 `source.approvedPayloadHash`；校验器重算
|
||||
payload hash 通过后才进入三角色闭环。未声明 workflow 的旧八字段配置只按
|
||||
`read-only-v1` 兼容，不得写回；
|
||||
标题、实际表现和预期结果不可推断；整行空白记录按批次 warning 跳过。
|
||||
按每条记录的 `sourceRef` 去重：仅 `open` 任务可刷新描述；
|
||||
`dispatched`、`fixed_by_dev`、`retesting`、`failed_retest`、`verified`、`blocked` 和
|
||||
`leftover` 只报告来源漂移，绝不覆盖；来源消失或读取失败时绝不删除已有任务。
|
||||
4. 新需求先写产品文档、任务拆分与可观测验收信号，更新 `tasks.yaml` 并校验，
|
||||
然后交给用户确认；若启用了交付，还要把本次 profile、目标、停止点和需要审批的
|
||||
步骤放入同一份计划。确认前不派发实现，也不执行交付。
|
||||
5. 创建或更换 worker 时，只使用
|
||||
`<ack-skill-dir>/scripts/launch_worker.py plan|launch` 读取
|
||||
`tasks.yaml.project.orchestration` 的 profile。不得直接执行
|
||||
`orca terminal create --command`，不得接受或拼接自由 command、额外 argv、
|
||||
executable、env 或 cwd。必须先审阅 `plan.launchFingerprint`，再把它作为
|
||||
`launch --expected-launch-fingerprint` 传入。v0.10 不根据持久化 receipt 自动
|
||||
复用旧终端；每次自动派发都创建 fresh worker，receipt 只作审计与 dispatch
|
||||
关联。
|
||||
6. 用户已确认的任务按 ACK 闭环执行：Developer 实现与白盒验证，Test 独立黑盒
|
||||
复测，Coordinator 读取证据终检并唯一写入 `tasks.yaml`。Developer 回报
|
||||
`knowledgeApplied` 和 `knowledgeCandidates`，Test 回报 `knowledgeChecks`；
|
||||
`candidate` 只有在独立验证和 gate 后才能由 Coordinator 写入或激活。
|
||||
7. 执行知识项的 `verification.ref` 时，只调用
|
||||
`<ack-skill-dir>/scripts/run_verification.py docs/ack/knowledge.yaml
|
||||
<verification-ref> --project-root <project-root>`。不要直接执行选择器返回的 path/args，
|
||||
也不要给 runner 注入额外命令或参数。
|
||||
8. 不把 `worker_done` 或 Test 自报成功直接当作完成。每项最多三轮，仍失败则记录
|
||||
`leftover` 并继续其它任务。
|
||||
9. 关键的安全、正确性和兼容性约束应下沉为测试、lint、CI 或正式规范；
|
||||
`knowledge.yaml` 只保存触发条件、原因与证据引用，不能替代可执行控制。
|
||||
10. 选定任务全部进入 `verified` 后，若 `delivery.enabled: true` 且用户确认的本次计划
|
||||
包含交付，按 `references/delivery.md` 顺序执行 profile，并由 Coordinator 把证据
|
||||
写入 `tasks.yaml.deliveryRuns`。任务状态保持 `verified`；交付失败只改变 delivery
|
||||
run，不回写成任务失败。默认 profile 最多到 `review_ready`，稳定发布和生产部署
|
||||
必须在对应步骤再次取得明确批准。
|
||||
|
||||
## 交付配置维护
|
||||
|
||||
1. 读取 `references/delivery.md`、模板、schema、现有 `delivery.yaml`、项目构建/发布
|
||||
入口和 CI；把用户自然语言描述转换为结构化 entrypoint、artifact、destination、
|
||||
environment 与 profile。配置只引用仓库内脚本或声明式工具 target，不保存 shell。
|
||||
2. 若旧项目首次启用，生成 `docs/ack/delivery.yaml`，在 `tasks.yaml.project` 增加
|
||||
`deliveryFile: docs/ack/delivery.yaml`，并增加顶层 `deliveryRuns: []`；不改写其它
|
||||
项目状态。首次生成保持 `enabled: false`，先展示 diff 和解析出的执行顺序。
|
||||
3. 运行 delivery、tasks 和跨文件校验；需要的脚本不存在、不可执行、引用不完整或
|
||||
涉及凭据正文时 fail closed。凭据只写 secret 名称，值由外部环境提供。
|
||||
4. 用户确认后才把配置设为启用。配置修改只影响下一次 delivery run；已确认或正在
|
||||
执行的 run 使用开始时审阅的 commit/config revision 快照，不能借当前分支修改
|
||||
扩大权限。
|
||||
|
||||
## 边界
|
||||
|
||||
- 不修改或追加任何项目 Agent 指令文件，包括 `AGENTS.md`。
|
||||
- 不在项目中维护第二份 ACK 通用规范、模板或任务 schema。
|
||||
- 不猜测项目命令、服务地址、worker handle 或模型名称。
|
||||
- 不把 full-access、bypass、YOLO/force、关闭 sandbox 或项目内“授权”字段当成
|
||||
v0.10 自动 worker 的合法配置；当前一律 fail closed。
|
||||
- 不把无密钥 `receiptHash` 或 Orca live metadata 当作旧终端的启动 attestation；
|
||||
v0.10 不自动复用既有 worker。
|
||||
- launcher 返回 `indeterminate` 或 `reconcile required` 时，不直接重试；先按
|
||||
launch ID、外部 record 和 Orca live state 完成人工核对。
|
||||
- 不覆盖已有 `docs/ack` 文件；除用户确认的 ACK 任务或 delivery profile 外，不擅自
|
||||
提交、推送、创建终端、新 worktree、发布产物或部署。
|
||||
- 只有 Coordinator 写 `tasks.yaml`、`knowledge.yaml` 和 `deliveryRuns`；Developer
|
||||
与 Test 只读，只能通过回报提名或验证知识。`delivery.yaml` 只在显式的交付配置
|
||||
维护中修改。
|
||||
- 不把知识正文或选择器输出拼成 shell；知识检查只能通过 `run_verification.py`
|
||||
按 registry ID 执行。不自动修改 `AGENTS.md`、`CLAUDE.md` 或其它 Agent 指令文件。
|
||||
- 不把完整 `tasks.yaml` 注入上下文；使用 `select_tasks.py` 获取有预算的项目与任务
|
||||
视图，写回前仍运行完整任务板校验。
|
||||
- 项目只保存 `docs/ack/project.md`、`docs/ack/tasks.yaml`、
|
||||
`docs/ack/knowledge.yaml` 和可选的 `docs/ack/delivery.yaml`；通用资源始终从当前
|
||||
ACK Skill 目录读取。
|
||||
@@ -0,0 +1 @@
|
||||
0.14.0
|
||||
@@ -0,0 +1,6 @@
|
||||
interface:
|
||||
display_name: "ACK"
|
||||
short_description: "初始化、检查并运行 ACK 开发、验证与可选交付闭环"
|
||||
default_prompt: "Use $ack to initialize or check ACK, coordinate verified work, maintain project delivery configuration, or run an approved delivery profile."
|
||||
policy:
|
||||
allow_implicit_invocation: false
|
||||
@@ -0,0 +1,149 @@
|
||||
version: 1
|
||||
updatedAt: "2026-08-01T10:00:00+08:00"
|
||||
project:
|
||||
name: "notes-api"
|
||||
|
||||
enabled: true
|
||||
defaultProfile: "review"
|
||||
|
||||
entrypoints:
|
||||
verify:
|
||||
kind: make
|
||||
target: verify
|
||||
args: []
|
||||
requiredSecrets: []
|
||||
workingDirectory: "."
|
||||
timeoutSeconds: 1800
|
||||
build-deb:
|
||||
kind: make
|
||||
target: build-deb
|
||||
args: []
|
||||
requiredSecrets: []
|
||||
workingDirectory: "."
|
||||
timeoutSeconds: 3600
|
||||
build-image:
|
||||
kind: make
|
||||
target: build-image
|
||||
args: []
|
||||
requiredSecrets: []
|
||||
workingDirectory: "."
|
||||
timeoutSeconds: 3600
|
||||
upload-deb:
|
||||
kind: script
|
||||
path: "scripts/upload-preview-deb.sh"
|
||||
args: []
|
||||
requiredSecrets: ["DEB_TOKEN"]
|
||||
workingDirectory: "."
|
||||
timeoutSeconds: 900
|
||||
upload-image:
|
||||
kind: script
|
||||
path: "scripts/publish-preview-image.sh"
|
||||
args: []
|
||||
requiredSecrets: ["REGISTRY_TOKEN"]
|
||||
workingDirectory: "."
|
||||
timeoutSeconds: 1800
|
||||
deploy-test:
|
||||
kind: script
|
||||
path: "scripts/deploy-test.sh"
|
||||
args: []
|
||||
requiredSecrets: []
|
||||
workingDirectory: "."
|
||||
timeoutSeconds: 900
|
||||
health-test:
|
||||
kind: script
|
||||
path: "scripts/check-test.sh"
|
||||
args: []
|
||||
requiredSecrets: []
|
||||
workingDirectory: "."
|
||||
timeoutSeconds: 300
|
||||
rollback-test:
|
||||
kind: script
|
||||
path: "scripts/rollback-test.sh"
|
||||
args: []
|
||||
requiredSecrets: []
|
||||
workingDirectory: "."
|
||||
timeoutSeconds: 900
|
||||
|
||||
artifacts:
|
||||
service-deb:
|
||||
type: deb
|
||||
build: build-deb
|
||||
outputs: ["dist/*.deb"]
|
||||
service-image:
|
||||
type: oci-image
|
||||
build: build-image
|
||||
image: "registry.example.com/notes/service"
|
||||
platforms: ["linux/amd64", "linux/arm64"]
|
||||
|
||||
destinations:
|
||||
preview-apt:
|
||||
type: apt-repository
|
||||
channel: preview
|
||||
endpoint: "https://packages.example.com"
|
||||
repository: "testing"
|
||||
upload: upload-deb
|
||||
preview-registry:
|
||||
type: oci-registry
|
||||
channel: preview
|
||||
registry: "registry.example.com"
|
||||
repository: "notes/service"
|
||||
upload: upload-image
|
||||
|
||||
environments:
|
||||
test-server:
|
||||
type: ssh-host
|
||||
classification: development
|
||||
target: "notes-test"
|
||||
deploy: deploy-test
|
||||
healthCheck: health-test
|
||||
rollback: rollback-test
|
||||
mutex: "notes-test-deploy"
|
||||
|
||||
profiles:
|
||||
review:
|
||||
stopAt: review_ready
|
||||
steps:
|
||||
- id: verify
|
||||
action: verify
|
||||
entrypoint: verify
|
||||
- id: open-pr
|
||||
action: pull-request
|
||||
draft: true
|
||||
remote: origin
|
||||
baseBranch: main
|
||||
- id: build-deb
|
||||
action: build
|
||||
artifact: service-deb
|
||||
- id: publish-deb
|
||||
action: publish
|
||||
artifact: service-deb
|
||||
destination: preview-apt
|
||||
- id: deploy-test
|
||||
action: deploy
|
||||
artifact: service-deb
|
||||
environment: test-server
|
||||
- id: smoke-test
|
||||
action: health-check
|
||||
environment: test-server
|
||||
- id: ready
|
||||
action: mark-ready
|
||||
review-image:
|
||||
stopAt: review_ready
|
||||
steps:
|
||||
- id: verify
|
||||
action: verify
|
||||
entrypoint: verify
|
||||
- id: open-pr
|
||||
action: pull-request
|
||||
draft: true
|
||||
remote: origin
|
||||
baseBranch: main
|
||||
- id: build-image
|
||||
action: build
|
||||
artifact: service-image
|
||||
- id: publish-image
|
||||
action: publish
|
||||
artifact: service-image
|
||||
destination: preview-registry
|
||||
- id: ready
|
||||
action: mark-ready
|
||||
@@ -0,0 +1,47 @@
|
||||
version: 1
|
||||
updatedAt: "2026-07-31T12:00:00+08:00"
|
||||
project:
|
||||
name: "notes-web"
|
||||
verificationRegistry:
|
||||
service-worktree-alignment:
|
||||
path: "tests/ack/check_service_worktree.py"
|
||||
args: ["--require-current-commit"]
|
||||
entries:
|
||||
- id: "K-001"
|
||||
revision: 1
|
||||
kind: "verification"
|
||||
status: "active"
|
||||
title: "复测前确认服务与 worktree/commit 对齐"
|
||||
subject: "service-worktree-alignment"
|
||||
scope:
|
||||
all: false
|
||||
components: ["web"]
|
||||
paths: ["web/**"]
|
||||
dependencies: []
|
||||
versions: []
|
||||
tags: ["long-running-service"]
|
||||
symbols: []
|
||||
errorSignatures: []
|
||||
appliesWhen: "修改常驻 Web 服务或前端构建产物"
|
||||
directive: "复测前重启服务，并核对服务实例对应的 worktree 与 commit"
|
||||
rationale: "历史任务曾因 Test 连接旧进程而产生假通过"
|
||||
verification:
|
||||
ref: "service-worktree-alignment"
|
||||
expected: "服务实例、worktree 和 commit 一致"
|
||||
provenance:
|
||||
taskId: "BUG-002"
|
||||
attemptId: "BUG-002-A2"
|
||||
codeRef: "abc1234"
|
||||
evidenceRef: "tasks.yaml#BUG-002"
|
||||
owner: "web-team"
|
||||
author: "developer"
|
||||
reviewer: "test"
|
||||
approval: null
|
||||
createdAt: "2026-07-30T10:00:00+08:00"
|
||||
lastValidatedAt: "2026-07-31T11:00:00+08:00"
|
||||
reviewAfter: "2099-10-31T11:00:00+08:00"
|
||||
temporary: false
|
||||
removalCondition: null
|
||||
statusReason: null
|
||||
supersedes: []
|
||||
conflictsWith: []
|
||||
@@ -0,0 +1,103 @@
|
||||
# notes-web Agent 协作协议（示例，项目覆盖层）
|
||||
|
||||
> 本项目基于 ack v0.14.0。
|
||||
> 通用规范由 `/ack` 从 Skill 自身的 `references/` 读取，本文件只填项目差异。
|
||||
> 覆盖层文件放在 `docs/ack/project.md`，不占用 `AGENTS.md`。
|
||||
> ACK 不会自动修改 `AGENTS.md`、`CLAUDE.md` 或其它 Agent 指令文件。
|
||||
> `docs/ack/` 只保存 `project.md`、`tasks.yaml`、`knowledge.yaml` 与 `delivery.yaml`。
|
||||
|
||||
## 项目概览
|
||||
|
||||
- 项目：`notes-web`
|
||||
- 技术栈：`TypeScript + React (Vite) + Go`
|
||||
- 运行命令：`npm run dev`（前端）、`go run ./server`（后端）
|
||||
- Base URL：`http://localhost:5173`
|
||||
- 任务板：`docs/ack/tasks.yaml`
|
||||
- 项目知识：`docs/ack/knowledge.yaml`
|
||||
- 交付契约：`docs/ack/delivery.yaml`
|
||||
- 覆盖层文件：`docs/ack/project.md`
|
||||
|
||||
## 稳定规范（引用，不重复）
|
||||
|
||||
- 开始一个需求（启动手册）：`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`
|
||||
- 验证后交付：`references/delivery.md`
|
||||
|
||||
## Worker 路由
|
||||
|
||||
结构化配置位于 `docs/ack/tasks.yaml` 的 `project.orchestration`，启动记录位于顶层
|
||||
`workerReceipts`。本项目默认使用：
|
||||
|
||||
| 角色 | profile ID | 档位 |
|
||||
|------|------------|------|
|
||||
| Developer | `codex-dev-standard` | standard |
|
||||
| Test | `codex-test-standard` | standard |
|
||||
| Developer 升级 | `codex-dev-strong` | strong |
|
||||
|
||||
本文件不保存或拼接 worker shell 命令。
|
||||
|
||||
## 路径权限
|
||||
|
||||
| 路径 | Coordinator | Test | Developer | 说明 |
|
||||
|------|:-----------:|:----:|:---------:|------|
|
||||
| `docs/spec/**` | R/W | Read-only | Read-only | 产品规格（PM 拥有） |
|
||||
| `tests/browser/**` | Read-only | R/W | Read-only | 浏览器回归用例（Test 拥有） |
|
||||
| `.qa-records/**` | Read-only | R/W | Read-only | 复测记录（gitignore） |
|
||||
| `web/**`、`server/**` | Read-only | Read-only | R/W | 应用源码 |
|
||||
| `**/*_test.go`、`web/**/*.test.tsx` | Read-only | Read-only | R/W | 单元测试 |
|
||||
| `config/*.example.*` | Read-only | Read-only | R/W | 可提交配置模板 |
|
||||
| `.env`、`config/local.*` | Read-only | Read-only | Read-only | 本地私有配置 |
|
||||
| `tasks.yaml` | R/W | Read-only | Read-only | 只有 Coordinator 写 |
|
||||
| `knowledge.yaml` | R/W | Read-only | Read-only | 只有 Coordinator 写；Developer/Test 通过回报提名或验证 |
|
||||
| `delivery.yaml` | 仅显式维护时 R/W | Read-only | Read-only | 项目交付能力，不是执行授权 |
|
||||
|
||||
## 命令
|
||||
|
||||
Developer 白盒验证：
|
||||
|
||||
```bash
|
||||
npm run build
|
||||
go test ./...
|
||||
npm run dev # 本地起前端
|
||||
```
|
||||
|
||||
Test 黑盒复测：
|
||||
|
||||
```bash
|
||||
curl -s http://localhost:5173/api/health
|
||||
curl -s -X POST http://localhost:5173/api/fix/preview -d @fixtures/preview.json
|
||||
# 浏览器回归：tests/browser/cases/*.md
|
||||
```
|
||||
|
||||
项目已审查的知识检查入口保存在 `knowledge.yaml.verificationRegistry`，格式为检查
|
||||
ID 对应仓库内相对 path 和结构化 args。知识正文不保存或自动执行自由 shell 命令。
|
||||
执行时只把检查 ID 交给 Skill 的 `scripts/run_verification.py`，不直接拼接
|
||||
path/args。
|
||||
项目状态校验由 `/ack` 使用 Skill 自带的 `scripts/validate_tasks.py`、
|
||||
`scripts/validate_knowledge.py` 和 `scripts/validate_delivery.py` 执行。
|
||||
交付机器入口以 `delivery.yaml` 为准，本覆盖层不维护第二套发布或部署命令。
|
||||
|
||||
## 硬规则（其余见 references/）
|
||||
|
||||
- 三角色独立：Coordinator 只编排、Test 只验证、Developer 只实现。
|
||||
- 模型分层：Coordinator 强模型不跑测试，Test/Developer 中低模型（见 references/model-routing.md）。
|
||||
- 自动 worker 只通过 ACK 的 `scripts/launch_worker.py` 启动；不直接执行自由
|
||||
`orca --command`。v0.10 的自动 profile 只允许 `read-only` 或
|
||||
`workspace-write`，不允许 full-access、bypass、YOLO/force 或关闭 sandbox。
|
||||
- 每次自动派发都先审阅 plan，再用 `--expected-launch-fingerprint` 启动 fresh
|
||||
worker；持久化 receipt 只作审计，不授权自动复用旧终端。
|
||||
- `worker_done` 与复测报告都不等于完成，必须 Test 独立复测 + Coordinator 终检后才能 `verified`。
|
||||
- 只有 Coordinator 写 `tasks.yaml` 和 `knowledge.yaml`；Test 与 Developer 只读。
|
||||
- Coordinator 只派发按 scope 命中并显式写入 `knowledgeRefs` 的 `active` 知识；
|
||||
`candidate` 不派发，知识库不全量注入。
|
||||
- Developer 回报 `knowledgeApplied` 与 `knowledgeCandidates`，Test 回报
|
||||
`knowledgeChecks`；关键约束应继续下沉到测试、lint、CI 或正式规范。
|
||||
- 交付只在任务 `verified` 后运行；默认 profile 停在 `review_ready`。stable 发布与
|
||||
production 部署保留显式 approval，配置变更只影响下一次 run。
|
||||
- 每个任务最多派发 3 轮，仍不过标记 `leftover` 并继续。
|
||||
- 不提交、推送、发布或部署，除非用户确认的 ACK 任务或 delivery profile 明确包含。
|
||||
@@ -0,0 +1,245 @@
|
||||
# 填好的手动闭环示例（虚构的 notes-web 项目）。历史轮次没有自动 launcher receipt；
|
||||
# 因此使用 manual 模式。可用 scripts/validate_tasks.py 校验通过。
|
||||
version: 1
|
||||
updatedAt: "2026-07-06T09:40:00+08:00"
|
||||
source: "Coordinator (PM) Agent"
|
||||
ackVersion: "0.14.0"
|
||||
project:
|
||||
name: "notes-web"
|
||||
repoPath: "/home/dev/notes-web"
|
||||
baseUrl: "http://localhost:5173"
|
||||
devWorktree: "/home/dev/notes-web-wt/fix-preview"
|
||||
overlayFile: "docs/ack/project.md"
|
||||
knowledgeFile: "docs/ack/knowledge.yaml"
|
||||
deliveryFile: "docs/ack/delivery.yaml"
|
||||
orchestration:
|
||||
profileVersion: 1
|
||||
mode: "manual"
|
||||
allowedWorktrees:
|
||||
- "/home/dev/notes-web-wt/fix-preview"
|
||||
modelAllowlist:
|
||||
codex:
|
||||
developer:
|
||||
standard: ["gpt-5.6-terra"]
|
||||
strong: ["gpt-5.6-sol"]
|
||||
test:
|
||||
standard: ["gpt-5.6-luna"]
|
||||
cursor-agent:
|
||||
developer:
|
||||
standard: ["auto"]
|
||||
test:
|
||||
standard: ["auto"]
|
||||
profiles:
|
||||
codex-dev-standard:
|
||||
role: "developer"
|
||||
cli: "codex"
|
||||
tier: "standard"
|
||||
model: "gpt-5.6-terra"
|
||||
reasoningEffort: "medium"
|
||||
permissionMode: "workspace-write"
|
||||
codex-test-standard:
|
||||
role: "test"
|
||||
cli: "codex"
|
||||
tier: "standard"
|
||||
model: "gpt-5.6-luna"
|
||||
reasoningEffort: "low"
|
||||
permissionMode: "workspace-write"
|
||||
codex-dev-strong:
|
||||
role: "developer"
|
||||
cli: "codex"
|
||||
tier: "strong"
|
||||
model: "gpt-5.6-sol"
|
||||
reasoningEffort: "high"
|
||||
permissionMode: "workspace-write"
|
||||
cursor-dev-standard:
|
||||
role: "developer"
|
||||
cli: "cursor-agent"
|
||||
tier: "standard"
|
||||
model: "auto"
|
||||
reasoningEffort: null
|
||||
permissionMode: "workspace-write"
|
||||
cursor-test-standard:
|
||||
role: "test"
|
||||
cli: "cursor-agent"
|
||||
tier: "standard"
|
||||
model: "auto"
|
||||
reasoningEffort: null
|
||||
permissionMode: "workspace-write"
|
||||
defaults:
|
||||
developer: "codex-dev-standard"
|
||||
test: "codex-test-standard"
|
||||
developerUpgraded: "codex-dev-strong"
|
||||
|
||||
workerReceipts: []
|
||||
deliveryRuns: []
|
||||
|
||||
summary:
|
||||
verified: ["BUG-002"]
|
||||
open: []
|
||||
failedRetest: []
|
||||
leftovers: ["BUG-003"]
|
||||
|
||||
tasks:
|
||||
- id: "BUG-002"
|
||||
type: "bug"
|
||||
title: "预览变更点击后不显示 diff 行"
|
||||
priority: "P0"
|
||||
status: "verified"
|
||||
assignee: "developer"
|
||||
component: "web/app/fix/page.tsx"
|
||||
specRefs:
|
||||
- "docs/spec/fix-preview.md#preview"
|
||||
testRefs:
|
||||
- "tests/browser/cases/01-preview.md"
|
||||
knowledgeRefs:
|
||||
- "K-001@1"
|
||||
knowledgeApplied:
|
||||
- ref: "K-001@1"
|
||||
result: "applied"
|
||||
evidence: "重启服务并核对 commit 后再交给 Test"
|
||||
knowledgeCandidates: []
|
||||
knowledgeChecks:
|
||||
- ref: "K-001@1"
|
||||
result: "passed"
|
||||
evidence: "服务实例、worktree 与 commit 9f8e7d6 一致"
|
||||
checkedBy: "test-worker-1"
|
||||
checkedAt: "2026-07-06T09:36:00+08:00"
|
||||
# 飞书导入时使用不透明 digest；不要在 source.ref 中放 profile、Base、table 或 record ID。
|
||||
source:
|
||||
kind: "feishu-base"
|
||||
ref: "feishu-base:sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
|
||||
recordId: "recExample"
|
||||
updatedAt: "2026-07-06T09:00:00Z"
|
||||
description: >
|
||||
用户在 /fix 页点击“预览变更”后，确认区不渲染 API 返回的 diff。
|
||||
fixLogic: >
|
||||
修正确认区对预览响应的字段映射，完整渲染四类 diff，同时保持取消操作不触发写入。
|
||||
acceptanceCriteria:
|
||||
- "预览后确认区显示 title、修改前值、修改后值和 coverChanged"
|
||||
- "取消预览不会产生保存请求"
|
||||
- "原先确认区为空的问题不再出现"
|
||||
stepsToReproduce:
|
||||
- "打开 /fix?fileId=1"
|
||||
- "搜索并选择候选项"
|
||||
- "点击“预览变更”"
|
||||
expected: >
|
||||
确认区出现 title、修改前值、修改后值、coverChanged 提示四行。
|
||||
actual: >
|
||||
API 返回 code=0，但页面确认区为空。
|
||||
evidence:
|
||||
browser: "确认区 DOM 为空，无 diff 行"
|
||||
api: "POST /api/fix/preview -> code=0, 含 diff 字段"
|
||||
logs: "无报错"
|
||||
verification:
|
||||
commands:
|
||||
- "npm run build"
|
||||
- "curl -s -X POST localhost:5173/api/fix/preview -d @fixtures/preview.json"
|
||||
browser:
|
||||
page: "/fix?fileId=1"
|
||||
checks:
|
||||
- "预览后出现 4 行 diff：title/before/after/coverChanged"
|
||||
dispatch:
|
||||
developer:
|
||||
profileId: "codex-dev-standard"
|
||||
receiptId: null
|
||||
attemptId: null
|
||||
taskId: null
|
||||
dispatchId: null
|
||||
test:
|
||||
profileId: "codex-test-standard"
|
||||
receiptId: null
|
||||
attemptId: null
|
||||
taskId: null
|
||||
dispatchId: null
|
||||
rounds:
|
||||
- round: 1
|
||||
attemptId: "BUG-002-A1"
|
||||
result: failed
|
||||
evidence: "只渲染了 title，缺少 before/after/coverChanged"
|
||||
- round: 2
|
||||
attemptId: "BUG-002-A2"
|
||||
result: passed
|
||||
evidence: "复测 4 行 diff 全部出现，取消不触发写入"
|
||||
resolution:
|
||||
fixedBy: "dev-worker-1"
|
||||
verifiedBy: "test-worker-1"
|
||||
verifiedAt: "2026-07-06T09:38:00+08:00"
|
||||
leftoverReason: null
|
||||
|
||||
- id: "BUG-003"
|
||||
type: "bug"
|
||||
title: "并发保存偶发覆盖他人修改"
|
||||
priority: "P1"
|
||||
status: "leftover"
|
||||
assignee: "developer"
|
||||
component: "server/store/notes.go"
|
||||
specRefs:
|
||||
- "docs/spec/concurrency.md"
|
||||
testRefs: []
|
||||
knowledgeRefs: []
|
||||
knowledgeApplied: []
|
||||
knowledgeCandidates:
|
||||
- kind: "pitfall"
|
||||
title: "乐观锁检查必须覆盖批量导入路径"
|
||||
claim: "只在 API 写入路径检查版本号会漏掉批量导入"
|
||||
scope:
|
||||
components: ["server-store"]
|
||||
paths: ["server/store/**"]
|
||||
tags: ["concurrency"]
|
||||
appliesWhen: "修改 note 的并发写入或批量导入逻辑"
|
||||
directive: "同时验证 API 与批量导入的版本冲突处理"
|
||||
rationale: "第二轮修复只覆盖 API，批量导入仍可静默覆盖"
|
||||
evidenceRefs:
|
||||
- "tasks.yaml#BUG-003-round-2"
|
||||
proposedBy: "test-worker-1"
|
||||
proposedAt: "2026-07-06T09:32:00+08:00"
|
||||
knowledgeChecks: []
|
||||
description: >
|
||||
两个会话同时保存同一条 note 时，后写覆盖先写，无冲突提示。
|
||||
stepsToReproduce:
|
||||
- "会话 A、B 同时打开 note 42"
|
||||
- "A 保存，B 保存"
|
||||
expected: >
|
||||
B 保存时应检测到版本变化并提示冲突，而非静默覆盖。
|
||||
actual: >
|
||||
B 直接覆盖 A 的修改，无提示。
|
||||
evidence:
|
||||
api: "两次 PUT /api/notes/42 均返回 200，无版本校验"
|
||||
verification:
|
||||
commands:
|
||||
- "go test ./server/store/..."
|
||||
browser:
|
||||
page: "/notes/42"
|
||||
checks:
|
||||
- "并发保存时后写方收到冲突提示"
|
||||
dispatch:
|
||||
developer:
|
||||
profileId: "codex-dev-standard"
|
||||
receiptId: null
|
||||
attemptId: null
|
||||
taskId: null
|
||||
dispatchId: null
|
||||
test:
|
||||
profileId: "codex-test-standard"
|
||||
receiptId: null
|
||||
attemptId: null
|
||||
taskId: null
|
||||
dispatchId: null
|
||||
rounds:
|
||||
- round: 1
|
||||
attemptId: "BUG-003-A1"
|
||||
result: failed
|
||||
evidence: "加了版本号但未在写入路径校验"
|
||||
- round: 2
|
||||
attemptId: "BUG-003-A2"
|
||||
result: failed
|
||||
evidence: "校验只覆盖 API，未覆盖批量导入路径"
|
||||
- round: 3
|
||||
attemptId: "BUG-003-A3"
|
||||
result: failed
|
||||
evidence: "乐观锁与前端重试逻辑冲突，需重新设计"
|
||||
resolution:
|
||||
fixedBy: null
|
||||
verifiedBy: null
|
||||
verifiedAt: null
|
||||
leftoverReason: "failed after 3 supervised developer rounds; 需重新设计并发模型"
|
||||
@@ -0,0 +1,107 @@
|
||||
# ACK 接入清单
|
||||
|
||||
## 安装与初始化
|
||||
|
||||
- [ ] ACK Skill 已全局安装或安装到当前项目。
|
||||
- [ ] 已运行 `skiff init ack --project <project-root>`。
|
||||
- [ ] `docs/ack/` 只包含项目自己的 `project.md`、`tasks.yaml`、`knowledge.yaml` 与
|
||||
默认关闭的 `delivery.yaml`。
|
||||
- [ ] 旧项目缺少 `knowledge.yaml` 时，只补空文件及缺失的
|
||||
`project.knowledgeFile` 指针，没有重跑初始化或覆盖其它项目状态。
|
||||
- [ ] 项目中没有 ACK Skill 的复制目录或 `kit`、`framework` 软链接。
|
||||
- [ ] `tasks.yaml` 使用 `ackVersion` 记录 ACK Skill 版本。
|
||||
|
||||
## 项目覆盖层
|
||||
|
||||
- [ ] `project.md` 只保存项目差异，不复制 Skill 的通用规范。
|
||||
- [ ] `tasks.yaml` 的 `project.overlayFile` 指向实际覆盖层。
|
||||
- [ ] `tasks.yaml` 的 `project.knowledgeFile` 固定为
|
||||
`docs/ack/knowledge.yaml`。
|
||||
- [ ] 新项目的 `project.deliveryFile` 固定为 `docs/ack/delivery.yaml`，顶层有
|
||||
`deliveryRuns: []`；旧项目未采用交付能力时可无这两项。
|
||||
- [ ] 技术栈、运行、构建、单测和集成测试命令均来自项目证据。
|
||||
- [ ] Coordinator、Developer、Test 的模型档位和升级规则已明确。
|
||||
- [ ] `project.orchestration` 使用受支持的 profileVersion，模型都命中项目
|
||||
allowlist，默认 profile 与角色/档位一致。
|
||||
- [ ] `allowedWorktrees` 只列出同一 Git common-dir 下已经核对的绝对 worktree。
|
||||
|
||||
## 路径权限
|
||||
|
||||
- [ ] Coordinator 可写规格和任务板。
|
||||
- [ ] Test 可写集成测试与复测记录，但不能改源码。
|
||||
- [ ] Developer 可写源码与单元测试，但不能改规格或黑盒验收。
|
||||
- [ ] 私有配置只读且不提交。
|
||||
- [ ] `tasks.yaml` 只有 Coordinator 写。
|
||||
- [ ] `knowledge.yaml` 只有 Coordinator 写；Developer 与 Test 只通过回报提名或验证。
|
||||
- [ ] `delivery.yaml` 只在用户显式维护配置时修改；Developer 与 Test 只读。
|
||||
|
||||
## 任务板
|
||||
|
||||
- [ ] 已替换项目名、仓库路径、Base URL、worktree 和覆盖层路径。
|
||||
- [ ] 没有真实任务时使用 `tasks: []`。
|
||||
- [ ] 真实任务的验收是可观测信号。
|
||||
- [ ] 已运行 `<ack-skill-dir>/scripts/validate_tasks.py` 并通过。
|
||||
|
||||
## 可选交付
|
||||
|
||||
- [ ] `delivery.yaml` 首次生成保持 `enabled: false`，没有根据 README/CI 自动启用。
|
||||
- [ ] entrypoint 只使用声明式工具 target 或仓库内无 symlink 的可执行脚本；没有
|
||||
shell、自由 command、凭据值或环境变量值。
|
||||
- [ ] artifact、destination、environment 和 profile 引用均通过
|
||||
`validate_delivery.py --tasks ... --project-root ...` 校验。
|
||||
- [ ] 默认 profile 只使用 preview/staging 与非 production 环境，停止在
|
||||
`review_ready`。
|
||||
- [ ] stable 发布和 production 部署之前存在 approval 步骤；production 环境有
|
||||
rollback 入口。
|
||||
- [ ] 本次 ACK 计划明确 profile、task IDs、目标、停止点和审批步骤；配置本身没有
|
||||
被当作提交、推送、发布或部署授权。
|
||||
- [ ] 每次运行固定 commit/config revision，证据写入 `tasks.yaml.deliveryRuns`；
|
||||
失败不会把已验证任务回退为失败。
|
||||
|
||||
## 项目知识
|
||||
|
||||
- [ ] 新项目没有已验证知识时使用 `verificationRegistry: {}` 与 `entries: []`，
|
||||
不虚构 active 条目。
|
||||
- [ ] 已运行 `<ack-skill-dir>/scripts/validate_knowledge.py` 并通过；同时校验任务引用。
|
||||
- [ ] Coordinator 只从 `active` 条目按 scope 推荐知识，并显式确认固定 revision 的
|
||||
`knowledgeRefs`。
|
||||
- [ ] `candidate` 留在任务证据中，不派发；`stale`、`superseded`、`archived`
|
||||
不默认选择。
|
||||
- [ ] 每轮只内联命中的少量知识，不全量注入 `knowledge.yaml`。
|
||||
- [ ] Developer 回报 `knowledgeApplied` 与 `knowledgeCandidates`，Test 回报
|
||||
`knowledgeChecks`。
|
||||
- [ ] `verification.ref` 只引用 `verificationRegistry` 中已审查的仓库内相对 path
|
||||
和结构化 args；执行时只把 registry ID 交给 `run_verification.py`，不从
|
||||
知识正文或选择器输出拼接 shell。
|
||||
- [ ] 关键约束已规划下沉到测试、lint、CI 或正式规范。
|
||||
- [ ] ACK 不自动修改 `AGENTS.md`、`CLAUDE.md` 或其它 Agent 指令文件。
|
||||
|
||||
## 编排
|
||||
|
||||
- [ ] 已选择 Orca 或手动模式。
|
||||
- [ ] 自动创建只调用 `launch_worker.py plan|launch`，没有直接拼接
|
||||
`orca terminal create --command` 或自由 worker 命令。
|
||||
- [ ] `launch` 使用刚审阅的 `plan.launchFingerprint` 作为
|
||||
`--expected-launch-fingerprint`；漂移时重新 plan。
|
||||
- [ ] Developer/Test 只使用 `read-only` 或 `workspace-write` profile；
|
||||
v0.10 没有 full-access、bypass、YOLO/force 或关闭 sandbox。
|
||||
- [ ] v0.10 每次自动派发都启动 fresh worker；没有把历史 receipt checksum 或
|
||||
Orca live metadata 当作自动复用授权。
|
||||
- [ ] launcher receipt 已追加到顶层 `workerReceipts`，任务分别引用
|
||||
`dispatch.developer` 与 `dispatch.test`；每个引用的 task/role/profile/attempt
|
||||
都与当前任务、本轮 receipt 完全一致，没有用单一 handle 混淆两个角色。
|
||||
- [ ] 多 worktree 场景只有一个权威 `tasks.yaml` 和 `knowledge.yaml`。
|
||||
- [ ] Test 使用的服务来自正确 worktree。
|
||||
|
||||
## 闭环
|
||||
|
||||
- [ ] `worker_done` 不直接视为完成。
|
||||
- [ ] Test 独立复测后由 Coordinator 读取证据终检。
|
||||
- [ ] 每轮写入 `dispatch.rounds`。
|
||||
- [ ] 三轮失败后标记 `leftover` 并填写原因。
|
||||
- [ ] `leftover` 不阻塞其它任务。
|
||||
|
||||
首次接入建议选择一个低风险问题跑完整闭环。项目差异写回
|
||||
`docs/ack/project.md`；通用问题回流到 ACK Skill 的 `references/`、`templates/`
|
||||
或 `scripts/`，并更新 `VERSION`。项目特有、跨任务复用且已经验证的经验才写入
|
||||
`docs/ack/knowledge.yaml`。
|
||||
@@ -0,0 +1,299 @@
|
||||
# 闭环流程（稳定核心，编排无关）
|
||||
|
||||
本文件定义**与具体编排工具无关**的三角色协作闭环。运行时调度可以用 Orca（见 `orca-adapter.md`），也可以手动跑（见下方「手动模式」）。
|
||||
|
||||
原则：调度消息只是运行时载体，任务结论必须回写到 `tasks.yaml`；已经验证且可跨
|
||||
任务使用的项目经验必须由 Coordinator 回写到 `knowledge.yaml`。不要把消息当最终记录。
|
||||
角色定义见 `roles-and-permissions.md`：Coordinator 只编排、Test 只验证、
|
||||
Developer 只实现。
|
||||
|
||||
---
|
||||
|
||||
## 编排抽象
|
||||
|
||||
无论用什么工具，闭环都由这几个能力组成。注意 `dispatch` 有两个目标（Developer 与 Test）：
|
||||
|
||||
| 抽象动作 | 含义 | Orca 实现 | 手动实现 |
|
||||
|----------|------|-----------|----------|
|
||||
| `prepare(task)` | Coordinator 把任务和验收信号写进 `tasks.yaml`，按 scope 推荐知识并确认显式 `knowledgeRefs` | 同左 | 同左 |
|
||||
| `dispatch(task, developer)` | 把修复任务连同上下文交给 Developer | `orca orchestration dispatch` | 复制 prompt 到 Developer 终端/会话 |
|
||||
| `dispatch(task, test)` | 把复测任务连同验收信号交给 Test | `orca orchestration dispatch` | 复制 prompt 到 Test 终端/会话 |
|
||||
| `wait()` | 等待 `worker_done` / `retest_result` / `escalation` / `decision_gate` | `orca orchestration check --wait` | 人工等待回报 |
|
||||
| `gate(task)` | Coordinator 读 Test 证据、`knowledgeChecks` 并对齐原始意图（不重测） | 同左 | 同左 |
|
||||
| `writeback(task, result)` | Coordinator 把任务结果写回 `tasks.yaml`，把验证通过的跨任务经验按权限写入 `knowledge.yaml` | 同左 | 同左 |
|
||||
|
||||
派发用的 prompt 见 `prompt-templates.md`。状态流转见 `roles-and-permissions.md` §「任务状态机」。**独立复测由 Test 执行，不是 Coordinator**；Coordinator 只做读证据的终检。
|
||||
|
||||
---
|
||||
|
||||
## 标准闭环
|
||||
|
||||
```text
|
||||
Coordinator 发现或读取 open 任务
|
||||
-> prepare：写/补全 tasks.yaml 验收信号
|
||||
-> 从 knowledge.yaml 按 scope 推荐 active 知识，Coordinator 确认固定 revision 的 knowledgeRefs
|
||||
-> 为新轮次生成稳定 attemptId（<task-id>-A<round>），Developer 与 Test 共用
|
||||
-> 决定 worktree：当前 worktree 起子 agent，还是新建隔离 worktree（见下节「子任务放哪」）
|
||||
-> 解析安全 profile：机器配置只读 tasks.yaml.project.orchestration
|
||||
-> 运行 launcher plan 并审阅 launchFingerprint
|
||||
-> 带 expected fingerprint 启动 fresh worker，把 receipt 写回 tasks.yaml（见 orca-adapter.md）
|
||||
-> dispatch 给 Developer（--to <worker handle>）
|
||||
-> wait：Developer 的 worker_done / escalation（含 knowledgeApplied / knowledgeCandidates）
|
||||
-> writeback fixed_by_dev
|
||||
-> 为 Test 独立解析安全 profile，重新 plan/launch fresh worker 并写回 receipt
|
||||
-> dispatch 给 Test（retesting）
|
||||
-> wait：Test 的 retest_result（含 knowledgeChecks 和 candidate 独立证据）
|
||||
-> Test 通过：gate（Coordinator 读证据对齐意图）
|
||||
-> 通过 gate：writeback verified
|
||||
-> gate 不满足意图：writeback failed_retest，带意图差异再派发 Developer
|
||||
-> Test 失败：writeback failed_retest，追加证据，再派发 Developer（最多累计三轮）
|
||||
-> 累计三轮失败：writeback leftover，继续下一个任务
|
||||
```
|
||||
|
||||
一次派发只修一个明确问题（细则见 `optimization-method.md` §「每轮派发只修一个明确问题」）。
|
||||
「决定 worktree」「解析 profile/receipt」几步的决策见下节与 `model-routing.md` /
|
||||
`orca-adapter.md`。v0.10 不自动复用历史 receipt 或既有终端；标题、preview、分支名、
|
||||
worker 自报和无密钥 receipt checksum 都不能代替可信启动 attestation。
|
||||
Coordinator 默认给新逻辑轮次生成 `<task-id>-A<round>`，并在记录轮次结果时写入
|
||||
`tasks[].dispatch.rounds[].attemptId`。它独立于编排工具产生的 `taskId` 和
|
||||
`dispatchId`：前者用于知识来源追溯，后两者只用于查询运行时。0.9.0 之前的历史
|
||||
轮次允许暂时缺省；但要把该轮证据晋升为知识前，必须按确定性格式补齐。晋升时，
|
||||
`provenance.taskId` 和 `provenance.attemptId` 必须能精确回到该任务及轮次。
|
||||
|
||||
### 知识选择与晋升
|
||||
|
||||
`prepare(task)` 时可以使用 Skill 自带的 `scripts/select_knowledge.py` 按
|
||||
component、path、dependency、version 和 tag 确定性推荐条目。选择器只返回
|
||||
`active`，并受条目数限制；`stale`、`superseded` 和 `archived` 不默认派发。自动
|
||||
匹配只是推荐。条目中每个非空 scope 维度都必须被任务上下文命中，因此调用时应
|
||||
提供当前任务已知的全部 component、path、dependency、version、tag、symbol 和错误
|
||||
特征。Coordinator 确认并写入当前任务的显式 `knowledgeRefs` 后才成为本轮权威
|
||||
上下文。
|
||||
|
||||
`scope.paths` 使用 POSIX 路径 glob：`*` 不跨目录分隔符，`**` 才能跨目录。多个
|
||||
pattern 是同一维度内的 OR，候选越多表示范围越宽；超过选择预算时，选择器优先保留
|
||||
命中维度更多、OR 候选更少、字面约束更多且通配符更少的条目。
|
||||
|
||||
派发时只内联本轮引用的少量知识，不要求 worker 全量读取 `knowledge.yaml`。这也
|
||||
避免隔离 worktree 读不到 Coordinator 工作树中尚未提交的项目状态。
|
||||
|
||||
进行中的任务只能引用 `active` 条目。已经进入 `verified` 或 `leftover` 的终态任务
|
||||
可以继续保留固定 revision 的历史引用，即使对应知识后来变成 `stale`、
|
||||
`superseded` 或 `archived`；这些旧条目不会再次被选择器派发。
|
||||
|
||||
Developer 或 Test 发现经验时只能通过 `knowledgeCandidates` 提名，并带上当前任务
|
||||
的独立观测、scope、触发条件和证据。candidate 留在任务证据中，不进入知识选择器，
|
||||
也不能被下一轮当作 active 指令。只有 Test 独立验证、Coordinator gate 通过后，
|
||||
Coordinator 才能写入或更新 `knowledge.yaml`；全项目强制或权限类规则还需
|
||||
User / Decision Owner 确认。
|
||||
|
||||
Test 对显式引用回报 `not_applicable` 时，说明 Coordinator 的选择需要纠正。该引用
|
||||
仍在 `knowledgeRefs` 中就不能把任务标为 `verified`；Coordinator 应记录原因、移除
|
||||
误选引用并重新校验，或继续补充验证。
|
||||
|
||||
知识中的 `verification.ref` 只能引用
|
||||
`knowledge.yaml.verificationRegistry` 里已审查的仓库内相对 path 和结构化 args，
|
||||
不能从知识正文拼接或执行自由 shell。Developer/Test 只把 `verification.ref` 交给
|
||||
`<ack-skill-dir>/scripts/run_verification.py`；该入口从项目根目录逐段安全打开检查
|
||||
文件，拒绝 symlink 路径，并从匿名稳定快照执行。关键约束应下沉为测试、lint、CI
|
||||
或正式规范。检查进程从固定的项目根 fd cwd 运行；检查脚本应使用 cwd 或
|
||||
`ACK_PROJECT_ROOT` 定位资源。后者是 fd 路径，原始展示路径只在
|
||||
`ACK_PROJECT_ROOT_DISPLAY` 中用于日志；不能依赖 `$0` / `__file__` 的目录。
|
||||
|
||||
---
|
||||
|
||||
## 子任务放哪：新 worktree 还是当前 worktree
|
||||
|
||||
Coordinator 派发前先决定 Developer/Test 在哪工作。两种方式：
|
||||
|
||||
**方式 1：当前 worktree 起 fresh 子 agent（终端）**
|
||||
|
||||
```bash
|
||||
# v0.10 不自动复用既有终端；先审阅 plan：
|
||||
python3 <ack-skill-dir>/scripts/launch_worker.py plan \
|
||||
--project-root <project-root> --task-id <task-id> \
|
||||
--attempt-id <task-id>-A<round> --role <developer-or-test> \
|
||||
--profile-id <profile-id> --worktree <absolute-current-worktree> --slot <1..99>
|
||||
python3 <ack-skill-dir>/scripts/launch_worker.py launch \
|
||||
--project-root <project-root> --task-id <task-id> \
|
||||
--attempt-id <task-id>-A<round> --role <developer-or-test> \
|
||||
--profile-id <profile-id> --worktree <absolute-current-worktree> --slot <1..99> \
|
||||
--expected-launch-fingerprint <plan 中的 sha256:...>
|
||||
```
|
||||
|
||||
- 适合：串行闭环、一次一个 Developer 任务、小改动、Test 要复测的正是 Developer 改的那棵树。
|
||||
- 优点：单一服务实例、无跨 worktree 对齐困扰、开销小。
|
||||
- 风险：多个 agent 同时改同一棵树会互相踩（半构建状态、git 冲突）。
|
||||
- 记录：`launch` 成功后把 receipt 追加到权威 `tasks.yaml.workerReceipts`，并把
|
||||
`receipt.id` 写入 `dispatch.<role>.receiptId`、把 `profileId` 写入
|
||||
`dispatch.<role>.profileId`、把本轮稳定 ID 写入 `dispatch.<role>.attemptId`；
|
||||
receipt 的 task/role/profile/attempt 必须与当前 dispatch 完全一致，不能只记录
|
||||
一个裸 handle，也不能引用旧任务或旧轮次 receipt。
|
||||
|
||||
**方式 2：新建隔离 worktree，再在其中起子 agent**
|
||||
|
||||
创建成功后，先把 Orca 返回的绝对路径加入权威任务板的
|
||||
`project.orchestration.allowedWorktrees` 并重新运行 `validate_tasks.py`；未进入
|
||||
allowlist 的路径不能交给 launcher。
|
||||
|
||||
```bash
|
||||
orca worktree create --name <feature> --base-branch <base> --json
|
||||
# 对返回的绝对路径调用 ACK launcher
|
||||
python3 <ack-skill-dir>/scripts/launch_worker.py plan \
|
||||
--project-root <project-root> --task-id <task-id> \
|
||||
--attempt-id <task-id>-A<round> --role <developer-or-test> \
|
||||
--profile-id <profile-id> --worktree <absolute-new-worktree> --slot <1..99>
|
||||
python3 <ack-skill-dir>/scripts/launch_worker.py launch \
|
||||
--project-root <project-root> --task-id <task-id> \
|
||||
--attempt-id <task-id>-A<round> --role <developer-or-test> \
|
||||
--profile-id <profile-id> --worktree <absolute-new-worktree> --slot <1..99> \
|
||||
--expected-launch-fingerprint <plan 中的 sha256:...>
|
||||
```
|
||||
|
||||
- 适合：并行多个互不依赖的子任务、大/高风险/实验性改动、要保持基线分支干净（如 prod 不动、feature 走独立分支）、要独立 build 或跑独立服务实例、best-of-N 尝试。
|
||||
- 优点：隔离 + 并行 + 易回滚（删 worktree 即可）。
|
||||
- 成本：各自 build/依赖、服务要用不同端口、必须处理下节的 worktree/服务对齐。
|
||||
|
||||
**决策速查：**
|
||||
|
||||
| 情况 | 选择 |
|
||||
|------|------|
|
||||
| 一次一个任务、串行修复 | 当前 worktree 子 agent |
|
||||
| 多个任务并行、互不依赖 | 每个任务一个新 worktree |
|
||||
| 高风险 / 实验 / 可能整体丢弃 | 新 worktree |
|
||||
| 要保持基线分支干净 | 新 worktree（feature 分支）|
|
||||
| 小改动、追求快 | 当前 worktree |
|
||||
|
||||
**项目状态（SSOT）只落一处**：无论开几个 worktree，`tasks.yaml`、
|
||||
`knowledge.yaml` 和可选 `delivery.yaml` 都只认一个权威副本（通常在基线/协调所在
|
||||
worktree）。Coordinator 单写任务、知识与 `deliveryRuns`；交付能力只在显式配置维护
|
||||
时修改。`project.orchestration`、顶层 `workerReceipts` 和任务 dispatch 也只写入这个
|
||||
副本；不要每个 worktree 各留一份会分叉的项目状态。profile 解析、launcher 与
|
||||
receipt 规则见 `model-routing.md` 和 `orca-adapter.md`。
|
||||
|
||||
两种 worktree 方式都只允许 profile 中的 `read-only` / `workspace-write` 安全权限。
|
||||
v0.10 的 full-access 授权与撤销机制仍是 Deferred；launcher 遇到 full-access 或等价
|
||||
的 sandbox 绕过请求必须 fail closed。
|
||||
|
||||
---
|
||||
|
||||
## 手动模式（无 Orca）
|
||||
|
||||
没有编排工具时，闭环不变，只是 `dispatch` / `wait` 由人工承担：
|
||||
|
||||
1. Coordinator 在 `tasks.yaml` 写好任务和验收信号。
|
||||
2. 从 `knowledge.yaml` 推荐相关 active 知识，Coordinator 确认固定 revision 的
|
||||
`knowledgeRefs`；用 `prompt-templates.md` §1 的初始派发模板生成 prompt，
|
||||
手动发给 Developer（另一个会话/终端/人）。
|
||||
3. Developer 完成后按 worker_done 模板回报。
|
||||
4. Coordinator 写回 `fixed_by_dev`，用 `prompt-templates.md` §3 的复测派发模板把任务发给 Test。
|
||||
5. Test 独立复测后按复测报告模板回报证据和 `knowledgeChecks`。
|
||||
6. Coordinator 做终检并回写 `tasks.yaml`：通过 `verified`，不过 `failed_retest`。
|
||||
7. 失败则用「复测失败再派发模板」重新发给 Developer，最多累计三轮。
|
||||
|
||||
手动模式下同样遵守：worker_done / 复测报告都不等于最终结论、只有 Coordinator
|
||||
写 `tasks.yaml` 和 `knowledge.yaml`、三轮失败留档。若本次确认计划还包含交付，所有
|
||||
选中任务 `verified` 后由 Coordinator 继续按 `delivery.md` 执行并写 `deliveryRuns`。
|
||||
|
||||
手动交给用户已打开的会话不等于产生 ACK receipt。该会话可以完成本次显式 handoff，
|
||||
但不能因此进入 Orca 自动派发信任路径；后续自动派发仍需重新通过 ACK launcher
|
||||
创建 fresh worker。
|
||||
|
||||
---
|
||||
|
||||
## Test 复测（编排无关）
|
||||
|
||||
即使 Developer 的 worker_done 写了"全部通过"，Test 仍必须独立复测：
|
||||
|
||||
```bash
|
||||
git status --short
|
||||
<test_commands>
|
||||
curl -s <base_url>/health-or-summary
|
||||
```
|
||||
|
||||
浏览器复测建议记录：
|
||||
|
||||
```text
|
||||
BASE_URL:
|
||||
page:
|
||||
steps:
|
||||
expected:
|
||||
actual:
|
||||
snapshot evidence:
|
||||
```
|
||||
|
||||
Test 只回传证据，不写 `tasks.yaml` 或 `knowledge.yaml`；由 Coordinator 落盘。
|
||||
每条适用的显式 `knowledgeRef` 还应报告 `passed`、`failed` 或
|
||||
`not_applicable` 及证据。
|
||||
|
||||
---
|
||||
|
||||
## Coordinator 终检（gate）
|
||||
|
||||
Test 报通过后，Coordinator 不重测，而是做一次读证据的终检：
|
||||
|
||||
- Test 证据是否覆盖了任务的**每一条**验收信号（见 `optimization-method.md` §1）。
|
||||
- 当前任务显式 `knowledgeRefs` 的必需 `knowledgeChecks` 是否全部覆盖，检查引用
|
||||
是否能解析到项目已审查的入口。
|
||||
- 结果是否符合任务的**原始意图**，而不只是通过了字面文案。
|
||||
- 运行环境是否对齐（见下方「服务与 worktree 对齐」）。
|
||||
|
||||
终检不通过（例如意图漂移、验收信号写漏）时，回写 `failed_retest` 并把意图差异带给下一轮 Developer，必要时先补全验收信号。
|
||||
|
||||
---
|
||||
|
||||
## 服务与 worktree 对齐（防假通过/假失败）
|
||||
|
||||
Test 复测前记录运行环境：
|
||||
|
||||
```bash
|
||||
pwd
|
||||
git rev-parse --abbrev-ref HEAD
|
||||
git rev-parse --short HEAD
|
||||
```
|
||||
|
||||
```text
|
||||
serverPid:
|
||||
serverCommand:
|
||||
BASE_URL:
|
||||
frontendDir:
|
||||
worktreePath:
|
||||
```
|
||||
|
||||
如果开发在 `<dev_worktree>` 修复，但服务跑的是另一个 worktree，必须**停止并重启正确服务**后再测。长跑服务或静态前端尤其要确认加载的是最新构建产物。
|
||||
|
||||
---
|
||||
|
||||
## 结果回写
|
||||
|
||||
Coordinator 回写 `tasks.yaml` 时按状态填写（字段结构见 `templates/tasks.schema.json`）：
|
||||
|
||||
```yaml
|
||||
# 通过（Test 复测 + Coordinator 终检）
|
||||
status: verified
|
||||
resolution:
|
||||
verifiedAt: "<timestamp>"
|
||||
verifiedBy: "test"
|
||||
evidence:
|
||||
verification: "<commands passed>"
|
||||
browser: "<snapshot or API evidence>"
|
||||
```
|
||||
|
||||
```yaml
|
||||
# 失败但未满三轮
|
||||
status: failed_retest
|
||||
dispatch:
|
||||
rounds:
|
||||
- round: 1
|
||||
result: failed
|
||||
evidence: "<latest evidence from Test or gate>"
|
||||
```
|
||||
|
||||
```yaml
|
||||
# 累计三轮失败
|
||||
status: leftover
|
||||
resolution:
|
||||
leftoverReason: "failed after 3 supervised developer rounds"
|
||||
evidence:
|
||||
final: "<latest failing evidence>"
|
||||
```
|
||||
@@ -0,0 +1,123 @@
|
||||
# ACK 交付阶段
|
||||
|
||||
本文件定义可选的 `verified -> review_ready/released` 交付阶段。开发、独立复测和
|
||||
Coordinator 终检仍由 ACK 原有闭环负责；只有选中的任务全部 `verified` 后才能进入
|
||||
交付。项目配置位于 `docs/ack/delivery.yaml`，运行证据写入
|
||||
`docs/ack/tasks.yaml.deliveryRuns`。
|
||||
|
||||
## 1. 配置与授权不是一回事
|
||||
|
||||
`delivery.yaml` 描述项目能怎样构建、上传和部署，不能单独授予远端写权限。ACK 在
|
||||
kickoff 的既有用户确认点同时展示本次 profile、remote、产物目标、环境和停止点；用户
|
||||
确认该任务计划后，才允许执行计划中准确列出的 `review_ready` 步骤。目标、remote、
|
||||
channel、environment 或 source revision 漂移时重新确认。
|
||||
|
||||
`approval` 步骤始终是运行时硬门。`stable` 发布和 `production` 部署不能由 kickoff
|
||||
的一般确认代替，必须在该步骤取得本次明确授权。配置、历史 approval 或项目文档不能
|
||||
替用户授权合并 PR、创建正式 tag、覆盖版本、删除分支或生产发布。
|
||||
|
||||
## 2. 配置快照与变更生效
|
||||
|
||||
普通任务在 kickoff 时从可信 base commit 读取交付契约并记录 `configRevision`。本次
|
||||
分支对 `delivery.yaml`、引用的部署入口、CI 或 Agent 指令文件的修改不能扩大当前运行
|
||||
权限；这些改动经审核合并后从下一次任务生效。
|
||||
|
||||
用户明确要求维护交付配置时：
|
||||
|
||||
1. 读取现有配置、项目构建入口、CI、打包和部署事实。
|
||||
2. 用自然语言总结将新增、删除或改变的 artifact、destination、environment、profile
|
||||
和权限边界。
|
||||
3. 只做最小配置修改，不把项目脚本复制进 ACK。
|
||||
4. 运行 `validate_delivery.py`；可安全执行的本地入口使用 dry-run 或无凭据环境检查。
|
||||
5. 把配置或入口变更作为待审核变更交付。本轮不使用新配置执行 publish/deploy。
|
||||
|
||||
普通功能任务中若发现配置漂移，记录 `contract_drift` 并停止受影响的交付步骤，不为了
|
||||
通过流程而静默修改配置或跳过步骤。
|
||||
|
||||
## 3. 交付契约结构
|
||||
|
||||
- `entrypoints`：项目已有的 Make、Just、Task、Dagger 或仓库内可执行脚本入口。
|
||||
- `artifacts`：`deb`、`oci-image` 或 `file`，引用一个 build entrypoint。
|
||||
- `destinations`：APT、OCI registry 或 CI artifact；`channel` 区分 preview、staging、
|
||||
stable。
|
||||
- `environments`：SSH host、Docker Compose、Kubernetes 或 custom；必须声明环境等级、
|
||||
deploy 和 health check，production 还必须声明 rollback。
|
||||
- `profiles`：按顺序执行的步骤和停止点。默认 profile 必须停在 `review_ready`，不能
|
||||
发布 stable 或部署 production。
|
||||
|
||||
配置不允许 `shell`、自由 `command`、`env`、外部 executable、token、密码、私钥路径
|
||||
或凭据 URL。entrypoint 的 `requiredSecrets` 只能列大写 secret 名称，值必须由外部
|
||||
凭据系统或执行环境注入。复杂逻辑放在受版本控制的项目入口中。entrypoint 使用 argv
|
||||
语义执行，不能拼成 `sh -c` 字符串。
|
||||
|
||||
## 4. 运行前检查
|
||||
|
||||
1. 从 `tasks.yaml.project.deliveryFile` 解析文件；未引用或 `enabled=false` 时保持旧 ACK
|
||||
行为，收尾停在 `verified`。
|
||||
2. 运行：
|
||||
|
||||
```bash
|
||||
python3 <ack-skill-dir>/scripts/validate_delivery.py \
|
||||
docs/ack/delivery.yaml --tasks docs/ack/tasks.yaml \
|
||||
--project-root <project-root>
|
||||
```
|
||||
|
||||
3. 确认选中 profile 是 kickoff 已确认的 profile，所有 task 已是 `verified`，工作区与
|
||||
服务对应正确 source revision。
|
||||
4. 检查 referenced entrypoint、delivery config、CI 和凭据边界是否在本次变更中被
|
||||
修改；被修改时禁止用它们执行带远端写权限或 secret 的步骤。
|
||||
5. 检查本次步骤引用的 `requiredSecrets` 是否由外部环境提供，只报告名称和是否存在，
|
||||
不读取、打印或持久化值。缺失时在第一次相关写操作前标记 blocked。
|
||||
6. 将已确认工作树固化为本地 source revision，再创建 `deliveryRuns` 的 `planned`
|
||||
记录，绑定 task IDs、profile、source revision 和 config revision；推送仍等到对应
|
||||
`pull-request` 步骤。
|
||||
|
||||
## 5. 步骤语义
|
||||
|
||||
按 profile 中的顺序执行，不自行插入或省略步骤：
|
||||
|
||||
- `verify`：运行指定 entrypoint，失败即停止。
|
||||
- `pull-request`：在精确 source revision 上提交、推送任务分支并创建或复用 Draft
|
||||
PR/MR。普通任务使用项目已确认的 Forge 流程；只有本次是版本发布生命周期且用户
|
||||
明确要求时才调用独立的 `manage-release`。没有对应能力或认证时标记 blocked，不用
|
||||
带 token 的临时 curl 兜底。remote 与 base branch 必须来自该步骤，不能临时猜测。
|
||||
- `build`：调用 artifact 的 build entrypoint。DEB 必须记录包名、版本、架构和
|
||||
SHA-256；OCI image 必须记录完整引用、platform 和 digest。产物必须绑定当前 source
|
||||
revision，不能在目标机器重新拉源码构建。
|
||||
- `publish`：验证 artifact/destination 类型兼容，上传精确产物。DEB 可使用已安装的
|
||||
`deb-publisher`；Docker 只有在用户明确指定 `$publish-docker-image` 时才加载该
|
||||
explicit-only skill，否则必须走契约中已审查的 upload entrypoint。项目入口只接受
|
||||
刚校验的精确 artifact。preview/staging 使用不可覆盖的 commit/PR 标识，不隐式使用
|
||||
`latest`。既没有可用 skill 也没有 upload 入口时标记 blocked。
|
||||
- `deploy`：把同一不可变 artifact 交给 environment 的 deploy entrypoint；获取目标
|
||||
mutex 后执行，不能并发部署同一目标。
|
||||
- `health-check`：在对应 deploy 成功后运行环境 health check，记录可观测证据。失败时
|
||||
按项目入口执行 rollback；rollback 未证明成功时不得声称恢复。
|
||||
- `approval`：停止并展示准确 artifact、destination/environment、source revision 和
|
||||
回滚计划，等待用户本次确认。
|
||||
- `mark-ready`：所有前序步骤成功后将 Draft PR/MR 标为 ready，并写入最终证据。
|
||||
|
||||
## 6. 状态与恢复
|
||||
|
||||
`task.status=verified` 表示代码正确性通过；交付状态单独记录为 `planned`、`running`、
|
||||
`blocked`、`failed`、`review_ready`、`released` 或 `skipped`。部署或 Forge 暂时失败不把
|
||||
任务改回 `failed_retest`。
|
||||
|
||||
重复运行先核对已有 branch、PR/MR、artifact 和部署目标，复用身份匹配的资源。相同
|
||||
ID 指向不同 commit、digest 或目标时停止，不覆盖或另建伪装成同一运行的资源。
|
||||
|
||||
若恢复过程中修改了任何 tracked file，原 source revision 和交付证据失效：回到 ACK
|
||||
验证闭环，Test 重新复测后才能创建新的 delivery run。只有外部瞬时失败且 Git 内容未变
|
||||
时，才可从失败步骤继续。
|
||||
|
||||
`review_ready` 至少记录：source/config revision、PR/MR URL、所有产物引用与 digest、
|
||||
部署环境和健康检查证据。最终回复分别报告代码验证、PR、产物、部署和未完成项，不能用
|
||||
“完成”掩盖其中某一阶段失败或待审批。
|
||||
|
||||
## 7. 与低层 Skill 的边界
|
||||
|
||||
ACK 只负责读取项目交付契约、编排顺序、守住审批点并汇总证据，不复制低层 skill 的
|
||||
上传、镜像或 Git 发布实现。`deb-publisher`、`publish-docker-image` 和
|
||||
`manage-release` 仍是可独立使用、独立安装的能力；缺失时 ACK 使用契约中已审查的
|
||||
项目 entrypoint，二者都不可用时把对应步骤标为 `blocked`。低层 skill 自身要求显式
|
||||
调用时，ACK 不能绕过它的触发与授权边界。
|
||||
@@ -0,0 +1,141 @@
|
||||
# 飞书 Base Bug 整理与审核
|
||||
|
||||
飞书 Base 是 Bug 在**审核通过前的唯一协作区**。用户先在飞书记录 Bug 描述，
|
||||
Coordinator 读取记录和项目现状，补全或修改修复逻辑、验收标准，再写回同一条飞书
|
||||
记录。用户可以继续在飞书反馈，Coordinator 按反馈反复修订。只有用户明确表示审核
|
||||
通过后，Coordinator 才把最终版本写入 `docs/ack/tasks.yaml`，随后启动 ACK 三角色闭环。
|
||||
|
||||
审核前不创建或刷新 `tasks.yaml` 中的 ACK 任务，不得启动 worker，不得派发
|
||||
Developer/Test，也不得修改应用代码。飞书字段已填满、记录进入某个 view、用户暂时没有
|
||||
回复，都不等于审核通过。
|
||||
|
||||
## 项目配置
|
||||
|
||||
项目在 `docs/ack/tasks.yaml` 的 `project.bugIntake` 声明 `provider: feishu-base`、
|
||||
`workflow: reviewed-writeback-v1`、显式 `profile`、`baseToken`、`tableId`、用于候选 Bug
|
||||
的 `viewId` 和字段映射；不要保存 App Secret、access token 或任何 profile 凭据。
|
||||
|
||||
原有八字段配置在未声明 `workflow` 时按 `read-only-v1` 兼容读取，不得写回或进入本节
|
||||
流程。启用审核前协作必须显式选择 `reviewed-writeback-v1`，并在 `title`、`actual`、
|
||||
`expected`、`stepsToReproduce`、`acceptance`、`priority`、`attachments`、`updatedAt`
|
||||
之外配置可写文本字段 `fixLogic`。其中 `fixLogic` 和 `acceptance` 由 Coordinator 维护；
|
||||
用户提供的标题、实际表现、预期结果和附件属于来源事实，Coordinator 不得覆盖。
|
||||
|
||||
## 一次性安装与 profile 设置
|
||||
|
||||
在账号级可信工具目录安装官方 CLI；ACK 读取器只会搜索账号的 `~/.local/bin`、mise/cargo
|
||||
shim 目录和固定系统目录，绝不会采用项目 `PATH` 中的同名文件。它同时识别官方 npm
|
||||
包生成的 `lark-cli -> @larksuite/cli/scripts/run.js` wrapper，并校验 package 名与 bin
|
||||
映射，然后直接执行该官方包下载的 native binary：
|
||||
|
||||
```bash
|
||||
npm install --global --prefix "$HOME/.local" @larksuite/cli@latest
|
||||
```
|
||||
|
||||
随后在受控终端中用 stdin 提供 App Secret，选择 Feishu brand，避免 secret 进入 shell
|
||||
history、进程参数或项目文件：
|
||||
|
||||
```bash
|
||||
printf '%s' "$FEISHU_APP_SECRET" | lark-cli profile add \
|
||||
--name project-feishu --app-id "$FEISHU_APP_ID" \
|
||||
--app-secret-stdin --brand feishu
|
||||
```
|
||||
|
||||
项目配置只填写 `profile: project-feishu`。不要执行 `profile use`，也不要依赖 active
|
||||
profile；读取、附件下载和写回都必须显式传 `--profile project-feishu`。profile 至少需要
|
||||
`base:record:read`、`base:record:write` 和 `docs:document.media:download`。
|
||||
不要把 `lark-cli auth check` 当作 app/bot scope 的证明，因为它检查的是当前用户的
|
||||
stored user token。
|
||||
|
||||
## 读取与整理计划
|
||||
|
||||
```bash
|
||||
python3 <ack-skill-dir>/scripts/feishu_bug_intake.py check docs/ack/tasks.yaml
|
||||
tmpdir=$(mktemp -d)
|
||||
python3 <ack-skill-dir>/scripts/feishu_bug_intake.py fetch docs/ack/tasks.yaml \
|
||||
--output-dir "$tmpdir"
|
||||
python3 <ack-skill-dir>/scripts/feishu_bug_intake.py plan docs/ack/tasks.yaml \
|
||||
--output-dir "$tmpdir"
|
||||
```
|
||||
|
||||
`fetch` 只调用官方 `base +record-list` 和附件下载命令，输出标准化 JSON，并为每条记录
|
||||
计算覆盖来源事实、附件元数据和审核字段的 `draftRevision`。`plan` 只生成
|
||||
`create` / `refresh` / `unchanged` / `drift` 候选动作，不修改飞书或任务板。**审核通过前
|
||||
不得执行这些候选动作**；它们只用于查重和预览最终导入结果。
|
||||
|
||||
标题、实际表现、预期结果和更新时间属于来源事实，任一缺失时读取失败。复现步骤、
|
||||
修复逻辑、验收标准和优先级属于 Coordinator 可整理字段；缺失时记录与 action 返回
|
||||
`enrichmentRequired`。没有附件且所有 Bug 内容字段都为空的误建行会跳过，并在批次
|
||||
`warnings` 中返回 `blank_record_skipped`。
|
||||
|
||||
子进程只收到实际账号 HOME、可信 PATH 和基础 locale；调用者环境中的
|
||||
`LARKSUITE_CLI_*`、`FEISHU_*`、`NODE_OPTIONS` 等变量不会传入。每条记录最多 10 个
|
||||
附件、单批最多 100 个，单个附件最多 20 MiB、合计最多 200 MiB，整批下载最多 5 分钟；
|
||||
始终使用新的临时目录作为 `--output-dir`。
|
||||
|
||||
## 审核前协作循环
|
||||
|
||||
对每条候选 Bug，Coordinator 按以下顺序工作：
|
||||
|
||||
1. 读取用户填写的来源事实、附件和项目代码/测试，确认问题边界；证据不足时把不确定点
|
||||
明确写成假设，不伪装成用户原文。
|
||||
2. 整理复现步骤和优先级，并生成：
|
||||
- `fixLogic`：说明根因判断、计划修改的位置与行为、需要保持的不变量，以及回归风险；
|
||||
它是待审核的实现方向，不宣称代码已经修改。
|
||||
- `acceptance`：写成可观测、可独立复测的标准，至少覆盖用户可见结果、真实状态或 API
|
||||
结果，以及原失败不再出现；不扩张用户没有表达的产品范围。
|
||||
3. 把本轮草案保存为不超过 64 KiB 的临时 JSON：只包含非空字符串 `fixLogic` 和非空
|
||||
字符串数组 `acceptance`。通过安全适配器写回当前飞书记录：
|
||||
|
||||
```bash
|
||||
python3 <ack-skill-dir>/scripts/feishu_bug_intake.py write-draft \
|
||||
docs/ack/tasks.yaml --record-id <record-id> \
|
||||
--expected-source-ref <sourceRef> \
|
||||
--expected-draft-revision <draftRevision> --input <draft.json>
|
||||
```
|
||||
|
||||
`write-draft` 会在写前确认 record 属于配置 view，且 `sourceRef`、`draftRevision` 与调用者
|
||||
看到的版本一致；它只允许覆盖配置映射的 `fixLogic` 和 `acceptance`，拒绝 symlink、超限
|
||||
或多余字段输入，并复用读取器的可信 CLI、显式 profile、最小环境和成功 envelope 校验。
|
||||
不得绕过适配器直接调用 PATH 中的 CLI，也不得改标题、实际表现、预期结果、附件或其它
|
||||
用户字段。
|
||||
4. `write-draft` 会回读同一记录、确认落盘值一致并返回当前 `draftRevision`。把这个 revision
|
||||
连同记录交给用户审核；不能只展示没有 revision 的自由文本。
|
||||
5. 用户提出意见时，重新读取最新记录和反馈，修订后再次写回、回读、等待审核；不要在
|
||||
本地或聊天中维护一份与飞书分叉的“最终草案”。
|
||||
|
||||
任一写回、回读或字段校验失败时停止本轮并报告，不能转入任务板或三角色处理。
|
||||
|
||||
## 审核门禁与导入
|
||||
|
||||
只有用户针对当前飞书记录的明确 `draftRevision` 表示“审核通过”“可以执行”或等价授权，
|
||||
才解除门禁。授权必须发生在最后一次草案写回和回读之后；之后若用户字段、附件、
|
||||
`fixLogic` 或 `acceptance` 再次变化，revision 会变化，原授权失效，必须重新审核。
|
||||
|
||||
审核通过后，Coordinator 才执行以下动作：
|
||||
|
||||
1. 通过适配器重新读取并生成规范任务草案；命令会要求当前 `sourceRef` 和
|
||||
`draftRevision` 精确等于用户批准值：
|
||||
|
||||
```bash
|
||||
python3 <ack-skill-dir>/scripts/feishu_bug_intake.py import-approved \
|
||||
docs/ack/tasks.yaml --record-id <record-id> \
|
||||
--expected-source-ref <approved-sourceRef> \
|
||||
--expected-draft-revision <approved-draftRevision>
|
||||
```
|
||||
|
||||
不一致时停止并重新审核。输出的 `taskDraft` 包含批准后的规范字段以及
|
||||
`source.workflow`、`source.approvedRevision`、`source.approvedPayloadHash`。
|
||||
2. 按 `source.ref` 查重，把 `taskDraft` 原样合并到新的 ACK task，只补任务 ID、状态、
|
||||
dispatch 等 ACK 运行字段；不得手工改写 `fixLogic`、`acceptanceCriteria` 或其它审核字段。
|
||||
可在 `evidence.intakeEnrichment` 标明 Coordinator 推断依据，但它不替代规范字段。
|
||||
3. 运行 `validate_tasks.py`。校验器会重算 `approvedPayloadHash`；只有写入和校验都成功，
|
||||
任务才可作为已确认的 `open` 任务
|
||||
进入 ACK 闭环。
|
||||
4. 按 Coordinator → Developer → Test 的标准流程派发、实现和独立复测。
|
||||
|
||||
相同来源只更新尚未派发的 `open` 任务；`dispatched`、`fixed_by_dev`、`retesting`、
|
||||
`failed_retest`、`verified`、`blocked` 和 `leftover` 任务只告警来源漂移，由用户决定是否
|
||||
新建任务。项目启用 reviewed workflow 后，历史 `verified` / `leftover` 只读来源继续保留；
|
||||
其它仍可执行的 legacy 飞书任务必须先按当前流程重新整理和审核，不能通过省略或降级
|
||||
`source.workflow` 绕过门禁。飞书记录消失、不可访问或同步失败时，已有 ACK 任务一律保留。
|
||||
@@ -0,0 +1,160 @@
|
||||
# 在新项目初始化 ACK
|
||||
|
||||
本文件说明如何把 ACK 的项目状态初始化到目标项目。ACK Skill 自身已经通过 Agent
|
||||
的 Skill 机制安装；项目不复制、不链接 Skill 内容。
|
||||
|
||||
## 前提与边界
|
||||
|
||||
开始前确认：
|
||||
|
||||
1. 目标项目根目录。
|
||||
2. ACK Skill 已全局安装或安装到当前项目。
|
||||
3. `skiff` 命令可用。
|
||||
|
||||
不要覆盖已有的 `docs/ack/project.md`、`docs/ack/tasks.yaml`、
|
||||
`docs/ack/knowledge.yaml`、`docs/ack/delivery.yaml`、`AGENTS.md` 或其它 Agent
|
||||
指令文件。ACK 不会自动
|
||||
修改 `AGENTS.md`、`CLAUDE.md` 或其它 Agent 指令文件。不要把 token、`.env`
|
||||
内容或其它私有配置写入 ACK 项目状态。
|
||||
|
||||
## 初始化
|
||||
|
||||
在目标项目执行：
|
||||
|
||||
```bash
|
||||
skiff init ack
|
||||
```
|
||||
|
||||
或显式指定项目：
|
||||
|
||||
```bash
|
||||
skiff init ack --project <project-root>
|
||||
```
|
||||
|
||||
命令从 ACK Skill 自带的 `templates/` 生成：
|
||||
|
||||
```text
|
||||
docs/ack/
|
||||
├── project.md
|
||||
├── tasks.yaml
|
||||
├── knowledge.yaml
|
||||
└── delivery.yaml # 默认 enabled: false
|
||||
```
|
||||
|
||||
如果任一目标文件已经存在，命令会拒绝覆盖。初始化过程不会创建 `kit`、
|
||||
`framework` 或其它指向 Skill 的软链接。
|
||||
|
||||
### 旧项目补充知识库
|
||||
|
||||
旧项目已经有 `project.md` 和 `tasks.yaml`、但没有 `knowledge.yaml` 时，不要重跑
|
||||
`skiff init ack`。先检查现有文件并向用户报告缺失项；用户授权后，只从
|
||||
`templates/knowledge.template.yaml` 生成 `docs/ack/knowledge.yaml`，替换项目名和
|
||||
当前时间，保留 `entries: []`。如果现有任务板缺少
|
||||
`project.knowledgeFile`，同一次授权只补
|
||||
`knowledgeFile: docs/ack/knowledge.yaml`，不改写其它项目状态。生成后运行任务板、
|
||||
知识库和跨文件引用校验。
|
||||
|
||||
### 旧项目补充交付配置
|
||||
|
||||
`delivery.yaml` 对旧项目是可选能力；缺少它不会影响三角色开发与验证闭环。只有用户
|
||||
明确要求配置项目交付时，才从 `templates/delivery.template.yaml` 生成文件，同时在
|
||||
任务板补 `project.deliveryFile: docs/ack/delivery.yaml` 与顶层
|
||||
`deliveryRuns: []`。首次生成保持 `enabled: false`，按 `delivery.md` 展示并确认
|
||||
解析结果后才启用。不要重跑 `skiff init ack`，也不要改写已有任务或知识。
|
||||
|
||||
## 完善项目覆盖层
|
||||
|
||||
编辑 `docs/ack/project.md`，填入：
|
||||
|
||||
- 项目名、技术栈、运行命令和 Base URL。
|
||||
- Coordinator、Developer、Test 的实际模型档位。
|
||||
- 规格、集成测试、源码、单元测试和私有配置的路径权限。
|
||||
- Developer 白盒验证命令。
|
||||
- Test 黑盒复测命令。
|
||||
|
||||
无法从项目证据确定的值写为 `n/a`，不要猜测。
|
||||
|
||||
## 完善任务板
|
||||
|
||||
编辑 `docs/ack/tasks.yaml`：
|
||||
|
||||
- `ackVersion` 使用 ACK Skill 的合法 SemVer `VERSION`；从 `0.10.0` 起
|
||||
`project.orchestration` 与顶层 `workerReceipts` 必须同时存在。
|
||||
- 从 `0.11.0` 起的新项目初始化包含默认关闭的交付契约；旧项目不要求为了版本号升级
|
||||
自动补交付配置。
|
||||
- `updatedAt` 使用当前带时区时间。
|
||||
- `project.name`、`repoPath`、`devWorktree`、`overlayFile` 和 `knowledgeFile` 使用
|
||||
真实值。
|
||||
- 新项目的 `project.deliveryFile` 固定为 `docs/ack/delivery.yaml`，并保留顶层
|
||||
`deliveryRuns: []`。旧项目只有在采用交付能力时才补这两个字段。
|
||||
- `project.orchestration.allowedWorktrees` 使用已核对的绝对 worktree；模型
|
||||
allowlist、profiles 和 defaults 使用项目实际允许值。不要把完整启动命令、
|
||||
`extraArgs`、`env` 或任意 executable 写进任务板。
|
||||
- 非服务项目的 `baseUrl` 写为 `n/a`。
|
||||
- 没有真实任务时使用 `tasks: []`，不要保留或虚构示例任务。
|
||||
|
||||
每个真实任务的验收必须是可观测信号，例如可见文本、API 状态和字段，或明确的交互
|
||||
结果；不要只写“功能正常”。
|
||||
|
||||
## 初始化项目知识
|
||||
|
||||
新项目的 `docs/ack/knowledge.yaml` 保持 `verificationRegistry: {}` 与
|
||||
`entries: []`。不要从聊天、README、issue 或单次失败中猜测并激活知识。
|
||||
|
||||
项目运行 ACK 后，Developer 和 Test 可以通过回报提名 `knowledgeCandidates`；
|
||||
candidate 留在任务证据中，不会被派发。只有 Test 独立验证且 Coordinator gate
|
||||
通过后，Coordinator 才能把它写成 `active` 条目。全项目范围的强制或权限类规则
|
||||
还需要 User / Decision Owner 确认。
|
||||
|
||||
知识条目只引用项目已审查的 `verification.ref`。对应入口保存在
|
||||
`knowledge.yaml.verificationRegistry`，只允许仓库内相对 path 和结构化 args，
|
||||
不保存或自动执行自由 shell 命令。需要执行时只把 registry ID 交给
|
||||
`<ack-skill-dir>/scripts/run_verification.py`，不直接运行 path/args。关键约束应
|
||||
最终下沉为测试、lint、CI 或正式规范。
|
||||
|
||||
## 初始化项目交付
|
||||
|
||||
新项目的 `docs/ack/delivery.yaml` 保持 `enabled: false`、空能力表和空 profile。
|
||||
不要根据 README 或 CI 自动推断并启用发布/部署。用户用自然语言描述交付要求后，
|
||||
Coordinator 按 `delivery.md` 维护声明式配置：工具 target 与仓库脚本分开引用，产物、
|
||||
目的地、环境和有序 profile 使用稳定 ID。配置中不保存 shell、环境变量值或凭据
|
||||
正文；稳定发布和生产部署必须有显式 approval 步骤。
|
||||
|
||||
## 校验
|
||||
|
||||
Agent 从当前 `SKILL.md` 解析 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>
|
||||
```
|
||||
|
||||
同时确认：
|
||||
|
||||
- `project.md`、`tasks.yaml`、`knowledge.yaml` 和 `delivery.yaml` 没有未替换的
|
||||
`<...>` 占位符。
|
||||
- `project.overlayFile` 指向真实文件。
|
||||
- `project.knowledgeFile` 指向 `docs/ack/knowledge.yaml`。
|
||||
- 新项目的 `project.deliveryFile` 指向 `docs/ack/delivery.yaml`；交付默认关闭。
|
||||
- Developer 与 Test 的验证命令可执行。
|
||||
- `project.orchestration` 的 profile/allowlist/defaults 通过校验，自动模式只允许
|
||||
`read-only` 或 `workspace-write`；旧任务板未迁移时保持手动模式。
|
||||
- 顶层 `workerReceipts` 和 `dispatch.developer/test` 的 task/role/profile/attempt
|
||||
引用一致；`receiptId` 与 `attemptId` 同时为空或同时填写。持久 receipt 只作审计，
|
||||
v0.10 不自动复用旧终端。
|
||||
- 网站或 API 项目写清服务启动、重启和 Base URL。
|
||||
- 任务中的固定 revision `knowledgeRefs` 都能解析，非 `active` 条目没有被派发。
|
||||
|
||||
## 初始化报告
|
||||
|
||||
完成后报告：
|
||||
|
||||
- 创建或确认的四个项目文件。
|
||||
- 检测到的技术栈和验证命令。
|
||||
- 任务板、项目知识和交付契约校验结果。
|
||||
- 仍需用户补充的值。
|
||||
|
||||
只有结构校验通过且必填项目事实完整时才称“初始化完成”；否则称“部分完成”，并列出
|
||||
具体阻塞项。除非用户明确要求，不提交、不推送。
|
||||
@@ -0,0 +1,188 @@
|
||||
# 如何开始一个需求（Kickoff）
|
||||
|
||||
从零开一个需求的启动手册。角色/权限见 `roles-and-permissions.md`，闭环见 `closed-loop.md`，模型见 `model-routing.md`。
|
||||
|
||||
---
|
||||
|
||||
## 前提：谁是 Coordinator
|
||||
|
||||
**你（发起编排的强模型会话）就是 Coordinator (PM) / 产品。** 你负责写文档、拆任务、
|
||||
编排、终检，**不亲自写代码、不亲自跑测试**。开发和测试是另起的 worker agent；
|
||||
具体 CLI、模型、reasoning effort 和执行模式的机器事实源是
|
||||
`docs/ack/tasks.yaml` 的 `project.orchestration`。`docs/ack/project.md` 只解释项目
|
||||
差异，不能提供另一套启动命令。
|
||||
|
||||
---
|
||||
|
||||
## 第 0 步：给 Coordinator 的开场指令（复制改需求）
|
||||
|
||||
```text
|
||||
我要做一个新需求：<一句话需求>。
|
||||
你作为 ack 的 Coordinator(PM)，按 ACK Skill 的 references 规范执行：
|
||||
|
||||
1. 先读 docs/ack/project.md，并用 `scripts/select_tasks.py docs/ack/tasks.yaml`
|
||||
读取有预算的 project、summary 和可工作任务；已知任务时传 `--task-id`，不要把
|
||||
完整 tasks.yaml 注入上下文。校验 docs/ack/knowledge.yaml 并用
|
||||
`scripts/select_knowledge.py` 只读取当前任务相关的 active 条目，再读
|
||||
references/roles-and-permissions.md、closed-loop.md、optimization-method.md。
|
||||
如果 tasks.yaml 声明 project.deliveryFile，再读取 delivery.yaml 与
|
||||
references/delivery.md，但不要把配置本身当作执行授权。
|
||||
2. 写产品文档到 docs/（PRD / 交互 / 验收），把需求拆成任务，每个任务的验收写成可观测信号（可见文本 / API 结果 / 交互结果）。
|
||||
3. 按任务 scope 从 knowledge.yaml 推荐 active 知识，确认后把固定 revision 的
|
||||
knowledgeRefs 写入任务；不要派发 candidate 或全量知识库。
|
||||
4. 把任务写进 docs/ack/tasks.yaml（只有你写），校验 tasks.yaml 和 knowledge.yaml。
|
||||
5. 先把「产品文档 + 任务拆分 + 验收信号 + 适用知识引用」给我确认；若启用了交付，
|
||||
同时列明本次 profile、目标、停止点与审批步骤。不要急着派发或交付。
|
||||
6. 我确认后，按 ack 闭环循环：先用 `scripts/launch_worker.py` 校验结构化
|
||||
Developer/Test profile，审阅 plan 后用 expected fingerprint 创建 fresh worker，
|
||||
dispatch 开发 → worker_done → dispatch 测试独立复测 → 你读证据终检 → 回写 tasks.yaml；
|
||||
每个任务最多三轮，三轮不过记 leftover 并升级我复盘。
|
||||
7. 所选任务都 verified 后，只有本次计划包含交付时才按 profile 顺序执行并写
|
||||
deliveryRuns；默认停在 review_ready，stable/production 步骤再次向我确认。
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 第 1 步：Coordinator 产出（确认前）
|
||||
|
||||
1. 产品文档 → `docs/PRD-<feature>.md` 等（Coordinator R/W）。
|
||||
2. 任务板 → `docs/ack/tasks.yaml`，每条任务带 `expected` + `verification`，验收写成可观测信号（见 `optimization-method.md` §1）。
|
||||
3. 项目知识 → 从 `docs/ack/knowledge.yaml` 按 component、path、dependency、version
|
||||
和 tag 推荐 `active` 条目，Coordinator 确认后写入固定 revision 的显式
|
||||
`knowledgeRefs`。candidate 不参与选择。
|
||||
4. 校验结构与引用：
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
`project.orchestration` 是 worker profile 的机器 SSOT；未知字段、非 allowlist 模型、
|
||||
不匹配的角色/档位和非安全权限必须在派发前 fail closed。
|
||||
|
||||
读取任务上下文使用：
|
||||
|
||||
```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 \
|
||||
--task-id <ack-task-id>
|
||||
```
|
||||
|
||||
选择器解析并校验完整任务板，但只输出命中任务及其 receipt/delivery run；超过预算时
|
||||
显式失败，不得改用 `cat` 或整文件 `sed`。
|
||||
|
||||
5. **停下来给人确认**：这是强模型该花时间的地方，不要跳过。
|
||||
|
||||
如果 `delivery.enabled: true`，确认内容还必须列出：profile、关联 task IDs、构建产物、
|
||||
发布 channel、部署环境、PR 是否创建/标 ready、停止点，以及哪些步骤会再次审批。
|
||||
|
||||
---
|
||||
|
||||
## 第 2 步：决定 worktree
|
||||
|
||||
见 `closed-loop.md` §「子任务放哪」：
|
||||
|
||||
- 需求大 / 要并行 / 要保基线分支干净 → 新建隔离 worktree。
|
||||
- 小改动 / 串行修复 → 当前 worktree 起子 agent。
|
||||
|
||||
---
|
||||
|
||||
## 第 3 步：审阅并启动 worker
|
||||
|
||||
先读 `tasks.yaml.project.orchestration` 的结构化 profiles。v0.10 不把历史 receipt
|
||||
或既有 Orca terminal 当作自动复用授权；每次自动派发都创建 fresh worker。原因和
|
||||
边界见 `model-routing.md` §「Receipt、审计与复用边界」。
|
||||
|
||||
先查看目标 profile hash，确认本次结构化配置。这个 hash 只用于审计和漂移比较，
|
||||
不能用于匹配或复用旧 receipt / 既有终端：
|
||||
|
||||
```bash
|
||||
python3 <ack-skill-dir>/scripts/launch_worker.py profile-hash \
|
||||
--project-root <project-root> --profile-id <profile-id>
|
||||
```
|
||||
|
||||
生成只读计划：
|
||||
|
||||
```bash
|
||||
python3 <ack-skill-dir>/scripts/launch_worker.py plan \
|
||||
--project-root <project-root> --task-id <task-id> \
|
||||
--attempt-id <task-id>-A<round> --role <developer-or-test> \
|
||||
--profile-id <profile-id> --worktree <absolute-worktree> --slot <1..99>
|
||||
```
|
||||
|
||||
审阅计划后执行唯一创建入口：
|
||||
|
||||
```bash
|
||||
python3 <ack-skill-dir>/scripts/launch_worker.py launch \
|
||||
--project-root <project-root> --task-id <task-id> \
|
||||
--attempt-id <task-id>-A<round> --role <developer-or-test> \
|
||||
--profile-id <profile-id> --worktree <absolute-worktree> --slot <1..99> \
|
||||
--expected-launch-fingerprint <plan 中的 sha256:...>
|
||||
```
|
||||
|
||||
`launch` 的 fingerprint 必须来自刚才审阅的 plan；若中间任何关键事实漂移，重新
|
||||
plan，不得覆盖检查。标准输出是单一 JSON。Coordinator 校验其中的 receipt 后，把
|
||||
receipt 原样追加到 `tasks.yaml.workerReceipts`，把 `receipt.id` 写入该任务
|
||||
`dispatch.<role>.receiptId`、把 `profileId` 写入 `dispatch.<role>.profileId`，并把
|
||||
本轮稳定 ID 写入 `dispatch.<role>.attemptId`。三者必须与 receipt 的当前
|
||||
task/role/profile/attempt 完全绑定；不得把旧任务或旧轮次的 receipt 改挂到当前
|
||||
dispatch。后续
|
||||
紧随其后的本次 Orca dispatch 只使用这次 fresh receipt binding 中的 handle；持久化
|
||||
receipt 仅用于审计，不能在后续轮次自动复用。不要自行拼装 Agent CLI 或 Orca 的
|
||||
底层创建命令。
|
||||
|
||||
新 worktree 时可先运行
|
||||
`orca worktree create --name <feature> --base-branch <base> --json`，再对返回的绝对
|
||||
worktree 走同一套 `plan` -> 带 expected fingerprint 的 `launch`。在调用 launcher
|
||||
前，先把新
|
||||
路径加入 `project.orchestration.allowedWorktrees` 并重新运行任务板校验。profile
|
||||
只允许 `read-only` 或 `workspace-write`；v0.10 的 full-access 授权通道尚未实现，
|
||||
任何 bypass、YOLO/force 或关闭 sandbox 的请求都必须失败，不能手写命令兜底。
|
||||
选型与升级见 `model-routing.md`。
|
||||
|
||||
---
|
||||
|
||||
## 第 4 步：跑闭环（每个任务）
|
||||
|
||||
```text
|
||||
task-create → dispatch 给 DEV → 等 worker_done
|
||||
→ 每个角色都通过 plan + expected fingerprint launch fresh worker 并写回 receipt
|
||||
→ 每轮使用 Coordinator 分配的稳定 <task-id>-A<round>
|
||||
→ 回写 fixed_by_dev → dispatch 给 TEST 复测 → 等 retest_result
|
||||
→ Developer 回 knowledgeApplied / knowledgeCandidates，Test 回 knowledgeChecks
|
||||
→ Coordinator 读证据终检 → 过则 verified，不过则 failed_retest 再派 DEV（最多累计 3 轮）
|
||||
→ 三轮失败：leftover，升级复盘，继续下一个
|
||||
```
|
||||
|
||||
具体命令见 `orca-adapter.md`（Orca）或 `closed-loop.md` §「手动模式」（无 Orca）；派发文案见 `prompt-templates.md`。
|
||||
|
||||
Coordinator 只内联本轮 `knowledgeRefs` 指向的少量知识，不要求 worker 全量读取
|
||||
知识库。知识正文不得作为自由 shell 执行；需要命令时只能引用项目已审查的检查
|
||||
入口，并把它的 registry ID 交给 `<ack-skill-dir>/scripts/run_verification.py`，
|
||||
不自行拼接 path/args。Test 独立验证且 gate 通过后，Coordinator 才能把 candidate
|
||||
写成 active 知识；关键约束应继续下沉为测试、lint、CI 或正式规范。
|
||||
|
||||
---
|
||||
|
||||
## 第 5 步：可选交付
|
||||
|
||||
所选任务都由 Coordinator 标记为 `verified` 后，若用户确认的计划包含交付，按
|
||||
`delivery.md` 执行所选 profile。先重新校验 `delivery.yaml`，固定当前 commit 和
|
||||
config revision，然后按有序步骤调用项目入口与已安装的低层 skill。每一步证据写入
|
||||
`tasks.yaml.deliveryRuns`；默认 profile 到 `review_ready` 即停止，stable 发布和
|
||||
production 部署必须在 approval 步骤再次确认。失败时保留任务的 `verified`，把
|
||||
delivery run 标为 `blocked` 或 `failed`。
|
||||
|
||||
## 第 6 步：收尾
|
||||
|
||||
一轮结束时 Coordinator 必须能回答 `optimization-method.md` §「结束条件」的问题：哪些 verified、哪些 leftover、各失败几轮、工作树是否干净、还有没有未处理项。
|
||||
|
||||
---
|
||||
|
||||
## 一句话
|
||||
|
||||
产品文档 + 验收信号写在前（你，强模型）→ 确认显式 `knowledgeRefs` → 从
|
||||
`tasks.yaml.project.orchestration` 解析安全 profile → 审阅 plan 并用 expected
|
||||
fingerprint 启动 fresh DEV/TEST → dispatch / 复测 / 终检循环 → 任务结论落
|
||||
`tasks.yaml` → 可选 delivery profile 到审核点，验证后的
|
||||
跨任务知识由 Coordinator 落 `knowledge.yaml`。
|
||||
@@ -0,0 +1,245 @@
|
||||
# 模型路由（稳定核心）
|
||||
|
||||
本文件是**三角色默认模型档位、升级规则和 worker profile 选择规则**的单一规范源。
|
||||
目标是在不牺牲质量的前提下降低 token 和模型成本：把昂贵的强模型留给需要判断的
|
||||
工作，把机械执行交给较弱模型。
|
||||
|
||||
角色定义见 `roles-and-permissions.md`（Coordinator 编排 / Test 验证 / Developer
|
||||
实现）。本文件只补一层正交的「用哪个档位、以什么安全 profile 启动 worker」。
|
||||
|
||||
---
|
||||
|
||||
## 默认档位
|
||||
|
||||
| 角色 | 默认模型档位 | 理由 |
|
||||
|------|--------------|------|
|
||||
| Coordinator (PM) | 强模型 | 需求拆解、验收信号设计、优先级、终检对齐意图、三轮失败复盘都需要高质量推理 |
|
||||
| Test | 中低模型 | 按既定验收信号执行浏览器/API/脚本，主要做观察、记录、逐条 pass/fail |
|
||||
| Developer | 中低模型（按任务升级） | 多数实现可照规格执行；跨系统、数据迁移、重复失败时再升级 |
|
||||
|
||||
Coordinator 用强模型但**不亲自跑测试**（测试由 Test 承担），所以强模型的 token
|
||||
花在思考和终检上，而不是反复点击页面、跑 smoke、复制日志。这一分工天然省 token，
|
||||
同时保持「验证者 != 实现者」。
|
||||
|
||||
---
|
||||
|
||||
## 什么时候用强模型
|
||||
|
||||
- 新需求理解、产品取舍、范围决策。
|
||||
- 架构与数据模型决策。
|
||||
- 把验收写成可观测信号（见 `optimization-method.md` §1）。
|
||||
- 需求含糊、规格与实现/测试冲突时的裁决。
|
||||
- Coordinator 终检：读证据、对齐原始意图。
|
||||
- 重复失败后的根因复盘与重新拆分。
|
||||
|
||||
## 什么时候用中低模型
|
||||
|
||||
- Test：跑浏览器用例、API smoke、逐条比对期望与实际、产出证据。
|
||||
- Developer：从清晰规格实现范围明确的任务、跑构建与单测、回报 worker_done。
|
||||
|
||||
---
|
||||
|
||||
## 升级规则
|
||||
|
||||
**升级到 Coordinator（强模型）复盘**，当：
|
||||
|
||||
- 同一验收路径 Developer 连续失败三轮（见 `optimization-method.md` §4）。
|
||||
- Test 两次仍无法给出清晰失败证据。
|
||||
- 任务需要改动产品范围或验收标准。
|
||||
- 修复涉及持久化数据、破坏性文件操作、安全或回滚。
|
||||
- 规格、测试、实现三者出现冲突。
|
||||
|
||||
**升级 Developer 模型档位**，当：
|
||||
|
||||
- 任务横跨多个子系统。
|
||||
- 改动涉及数据模型或迁移。
|
||||
- 需要设计新的抽象。
|
||||
- 低档位反复产出表面修复。
|
||||
|
||||
升级由 Coordinator 判断并记录原因。升级不是修改一个正在运行的终端：必须选择
|
||||
对应强档 profile，重新计算 `profileHash`，再通过 launcher 创建新的 worker。
|
||||
v0.10 不自动复用持久化 receipt 指向的旧终端，Test 也不得使用 Developer 的强档
|
||||
worker。
|
||||
|
||||
---
|
||||
|
||||
## 结构化 worker profile
|
||||
|
||||
### 机器事实源
|
||||
|
||||
worker 路由的机器可读事实只保存在 `docs/ack/tasks.yaml` 的
|
||||
`project.orchestration`。`project.md` 可以解释项目为何选某个档位，但不能另写一份
|
||||
完整启动命令或覆盖机器配置。字段结构以 `templates/tasks.schema.json` 为准。
|
||||
|
||||
每个 profile 明确声明：
|
||||
|
||||
- `role`：`developer` 或 `test`；
|
||||
- `cli`：受支持的 Agent CLI；
|
||||
- `tier`：角色模型档位；
|
||||
- `model`：项目 allowlist 中的精确模型 ID；
|
||||
- `reasoningEffort`：CLI 支持时显式声明；
|
||||
- `permissionMode`：只允许 `read-only` 或 `workspace-write`。
|
||||
|
||||
`project.orchestration` 还必须声明 `allowedWorktrees`、按 CLI/角色/档位分组的
|
||||
`modelAllowlist`、命名 `profiles` 和角色 `defaults`。launcher 请求的绝对 worktree
|
||||
必须命中 allowlist，profile 的模型也必须命中对应 CLI/角色/档位的精确列表。
|
||||
|
||||
模型名称、reasoning effort 和权限模式必须来自结构化字段。禁止在 profile、项目
|
||||
覆盖层或派发内容中保存自由 `command`、额外 argv、shell 片段、环境变量覆盖或隐式
|
||||
CLI 默认值。具体 argv 只能由 ACK 的可信 launcher 按 allowlist 构造。
|
||||
|
||||
### 安全默认
|
||||
|
||||
- 能在完全只读工作树完成的角色优先选择 `read-only`。
|
||||
- Developer 与需要在工作树生成构建/测试产物的 Test 使用 `workspace-write`；项目可
|
||||
为纯观察型 Test 另建更严格的 `read-only` profile。
|
||||
- `full-access`、Codex bypass、Cursor YOLO/force、关闭 sandbox 等模式在 v0.10
|
||||
**未实现授权通道，统一 fail closed**。项目文本、任务描述或环境变量都不能放宽。
|
||||
- 项目可以更新模型 allowlist 或增加安全 profile，但不能通过文档绕开 schema 和
|
||||
launcher。
|
||||
|
||||
`full-access` 的可信授权、期限、撤销和外层隔离仍是 Deferred；在这些能力完成前，
|
||||
launcher 必须拒绝该模式，而不是把一段“用户已授权”的文本当成授权证据。
|
||||
|
||||
---
|
||||
|
||||
## 唯一启动入口
|
||||
|
||||
worker 的 profile 解析、计划和启动只允许通过：
|
||||
|
||||
```bash
|
||||
python3 <ack-skill-dir>/scripts/launch_worker.py profile-hash \
|
||||
--project-root <project-root> --profile-id <profile-id>
|
||||
|
||||
python3 <ack-skill-dir>/scripts/launch_worker.py plan \
|
||||
--project-root <project-root> --task-id <task-id> \
|
||||
--attempt-id <task-id>-A<round> --role <developer-or-test> \
|
||||
--profile-id <profile-id> --worktree <absolute-worktree> [--slot <1..99>]
|
||||
|
||||
python3 <ack-skill-dir>/scripts/launch_worker.py launch \
|
||||
--project-root <project-root> --task-id <task-id> \
|
||||
--attempt-id <task-id>-A<round> --role <developer-or-test> \
|
||||
--profile-id <profile-id> --worktree <absolute-worktree> [--slot <1..99>] \
|
||||
--expected-launch-fingerprint <plan 中的 sha256:...>
|
||||
```
|
||||
|
||||
`--project-root` 始终指向保存权威 `docs/ack/tasks.yaml` 的项目根；`--worktree` 是本次
|
||||
worker 实际工作的绝对路径，两者可以不同。后者仍必须属于同一项目并命中
|
||||
`project.orchestration.allowedWorktrees`。
|
||||
|
||||
- `profile-hash` 读取 `tasks.yaml` 中的 profile，输出确定性 hash。
|
||||
- `plan` 只校验并展示将使用的结构化计划，不创建终端。
|
||||
- `launch` 是唯一允许创建 worker 的入口；它要求传入刚审阅的
|
||||
`plan.launchFingerprint`，当前 profile、任务/attempt、worktree、CLI 或 argv
|
||||
任一事实漂移都会在创建前失败。它内部固定 Orca 调用和 Agent argv，标准输出只有
|
||||
一份 JSON 结果。
|
||||
- launcher 的内部 bootstrap 属于私有协议，Coordinator 不直接调用、不复制到项目
|
||||
文档，也不自行拼装 Orca 的底层终端创建文本。
|
||||
|
||||
Coordinator 在执行 `launch` 前必须先审阅 `plan`。任何校验失败、字段未知、路径不
|
||||
匹配、CLI 不可用或权限模式不支持，都停止创建并回报，不回退到裸 Agent 命令。
|
||||
|
||||
---
|
||||
|
||||
## 可执行信任边界
|
||||
|
||||
v0.10 的 launcher 还执行以下约束：
|
||||
|
||||
- 不读取调用者传入的 `PATH` 来寻找 `git`、Orca 或 Agent CLI，只在固定的系统与
|
||||
当前用户工具目录中解析受支持的可执行文件；候选目标必须由 root/当前用户拥有、
|
||||
不是 group/other writable，并在 plan 与 bootstrap 间保持相同 device/inode。
|
||||
- Git、Orca 和 CLI version probe 使用不含供应商凭据的控制环境；worker 使用
|
||||
`per-cli-allowlist-v1`，Codex 只取得 Codex 所需凭据，Cursor 只取得 Cursor 凭据，
|
||||
不跨 CLI 透传。`DBUS_*`、`DISPLAY`、`WAYLAND_DISPLAY`、`XDG_RUNTIME_DIR`、
|
||||
`LD_*`、`PYTHON*`、`NODE_OPTIONS`、`CODEX_HOME`、`GIT_*` 和调用者 PATH 均不会
|
||||
透传给 worker。
|
||||
- worktree 除了命中项目 allowlist、属于同一 Git common-dir，还必须精确出现在
|
||||
`git worktree list --porcelain -z` 中；`.git` symlink 冒充的目录会失败。
|
||||
- Orca 的 `--command` 只含固定 bootstrap 与随机 launch ID。终端创建后，父进程先
|
||||
绑定 runtime/handle/incarnation/worktree，再通过该终端 stdin 发送一次性 nonce；
|
||||
bootstrap 校验 nonce 后才允许启动 Agent CLI，并把 child PID 与 nonce/launch
|
||||
fingerprint 绑定的 proof 原子写入 ready 状态；父进程看到并核对 proof 后才把
|
||||
worker 视为可派发。
|
||||
- `orca terminal create` 一经发出，在取得确定 handle 前遇到超时、transport/解码
|
||||
异常、进程中断、非零退出、畸形 JSON 或缺字段，一律标记为 `indeterminate`，
|
||||
禁止自动重试。
|
||||
- 取得 handle 后若任一绑定或握手检查失败，launcher 会先用
|
||||
`orca terminal close --tab --json` 请求持久关闭，并严格核对 runtime、handle、
|
||||
tab 和 close mode。只有关闭回执完整匹配才记为普通 `failed`；关闭无法确认时保持
|
||||
`indeterminate/reconcile-required`，调用方必须先人工核对，不能直接重试。
|
||||
- bootstrap 在真正启动 Agent 前，会在同一 launch-record 锁内再次确认状态仍为
|
||||
`awaiting-authorization` 且没有 cleanup；父进程一旦先进入 cleanup/reconcile，
|
||||
bootstrap 必须拒绝 `Popen`，不能让取消后的 workspace-write worker 继续启动。
|
||||
- 异常路径的 launch record 写入失败不能阻断上述关闭动作，也不能遮蔽原始
|
||||
`indeterminate`。即使关闭已确认，只要最终状态无法可靠持久化，也保守返回
|
||||
`indeterminate/reconcile-required`。
|
||||
|
||||
这些约束防止任务板、任务文本和普通环境变量变成第二个启动命令入口。它们不抵御已经
|
||||
完全控制 Coordinator 用户账户、Orca 运行时、受信 Agent/Orca 可执行文件或
|
||||
Coordinator 用户级 Agent 配置/插件/MCP 的攻击者；该场景需要独立 OS 身份、受控
|
||||
Agent 配置或平台签发能力。`permissionMode` 约束的是 Agent CLI 的 shell/文件系统
|
||||
执行模式，不是模型供应商或外部工具能力的 attestation。
|
||||
|
||||
---
|
||||
|
||||
## Receipt、审计与复用边界
|
||||
|
||||
成功启动返回的 JSON 含一个可校验 receipt。Coordinator 把 receipt 追加到
|
||||
`tasks.yaml` 顶层 `workerReceipts`，并把它的 `id` 写入当前任务
|
||||
`dispatch.<role>.receiptId`、把 `profileId` 写入 `dispatch.<role>.profileId`，同时把
|
||||
本次 `<task-id>-A<round>` 写入 `dispatch.<role>.attemptId`。
|
||||
|
||||
这三个字段不是可任意组合的历史索引。任务板校验器要求被引用 receipt 的
|
||||
`createdFor.taskId` 等于当前 ACK `tasks[].id`，`createdFor.role` 等于 dispatch
|
||||
角色，`profileId` 完全相同，且 `createdFor.attemptId` 等于
|
||||
`dispatch.<role>.attemptId`。`receiptId: null` 时 `attemptId` 必须同为 `null`；
|
||||
`receiptId` 非空时 `attemptId` 必须存在并命中本轮。`dispatch.<role>.taskId` 是 Orca
|
||||
运行时 task ID，不能拿来替代 ACK task ID 或稳定 attempt ID。
|
||||
|
||||
receipt 至少把以下事实绑定在一起：
|
||||
|
||||
- `profileHash` 与请求的角色、模型、effort、权限和精确 argv；
|
||||
- `slot`，确保 fingerprint 也绑定审阅过的 worker 槽位和派生标题；
|
||||
- 任务、attempt、绝对 worktree 及 path/device/inode/git common-dir 等稳定身份；
|
||||
- Orca `runtimeId`、terminal `handle` 和 `incarnationId`；
|
||||
- 创建时间、launcher 指纹和 `receiptHash`。
|
||||
|
||||
`receiptHash` 是无密钥的规范 JSON checksum，只能发现意外漂移或未同步修改，**不是
|
||||
launcher 身份证明，也不是复用授权**。项目内有写权限的一方可以修改 receipt 后重算
|
||||
hash；而当前 Orca metadata 又不能证明终端最初执行的命令、模型和权限。因此 v0.10
|
||||
明确禁止根据持久化 receipt 自动复用既有终端：每次需要自动派发 worker，都重新走
|
||||
`plan` → 带 expected fingerprint 的 `launch`，只使用该次 launcher 标准输出中的
|
||||
fresh handle 完成本次派发。
|
||||
|
||||
`launchFingerprint` 是确定性的完整计划漂移校验，不是一次性授权或幂等键。同一份
|
||||
计划重复执行 `launch` 会创建新的 fresh terminal；成功后不得用同一 fingerprint
|
||||
再次启动。若结果不确定，必须先 reconcile，不能把重跑当作恢复方式。未来需要自动
|
||||
防重放时，应由 Orca/ACP 的原子 idempotency/claim 能力或项目外可信 launch intent
|
||||
提供，而不是把 checksum 冒充成一次性令牌。
|
||||
|
||||
持久化 receipt 仍用于审计、dispatch 关联和检测配置漂移；标题、preview、分支名、
|
||||
worker 自报或单独的 Orca live metadata 都不能把旧终端提升为可信 worker。未来只有
|
||||
在 Orca/ACP 提供启动参数 attestation，或存在项目外可信签发与校验通道后，才开放
|
||||
自动复用。CLI / 模型变更仍需更新 allowlist 并重新生成 receipt。
|
||||
|
||||
`ackVersion` 必须使用合法 SemVer。`0.10.0` 及以后版本的任务板必须同时存在
|
||||
`project.orchestration` 与顶层 `workerReceipts`；其中任一字段出现，另一个也必须
|
||||
出现，避免 schema-only 校验把半迁移任务板误判为可自动派发。
|
||||
|
||||
---
|
||||
|
||||
## 成本原则
|
||||
|
||||
强模型产出高密度、可复用的产物：需求、架构决策、验收信号、任务拆分、失败复盘。
|
||||
中低模型消费这些产物，产出可核对的执行证据：测试结果、快照、API 响应、构建日志、
|
||||
改动文件清单。
|
||||
|
||||
这样把昂贵推理挡在重复执行之外。
|
||||
|
||||
---
|
||||
|
||||
## 一句话
|
||||
|
||||
Coordinator 是脑，Test 是眼，Developer 是手。脑用强模型且不做机械测试，眼和手
|
||||
默认用安全、较低成本的结构化 profile；只有常规闭环卡住时才升级，并且所有 worker
|
||||
都必须经 launcher 产生可核对的 receipt。
|
||||
+38
-2
@@ -36,7 +36,7 @@
|
||||
|
||||
## 2. 回报必须带证据，不带结论
|
||||
|
||||
Developer 的 `worker_done` 应报告：改了哪些文件、跑了哪些命令、自己如何复现验收路径、仍可能有的风险。Test 的复测报告同理：跑了哪些命令、命中/缺失了哪些验收信号、实际观察到什么、证据（snapshot / API 结果）。两者的"结论"都不作数，只有 Coordinator 落盘的 `tasks.yaml` 才是事实。
|
||||
Developer 的 `worker_done` 应报告：改了哪些文件、跑了哪些命令、自己如何复现验收路径、仍可能有的风险。Test 的复测报告同理：跑了哪些命令、命中/缺失了哪些验收信号、实际观察到什么、证据（snapshot / API 结果）。两者的"结论"都不作数；任务结论只有 Coordinator 落盘到 `tasks.yaml` 才算数，跨任务知识只有 Coordinator 落盘到 `knowledge.yaml` 才会生效。
|
||||
|
||||
不要写：
|
||||
|
||||
@@ -138,7 +138,41 @@ one dispatch = one bug = one acceptance path
|
||||
|
||||
---
|
||||
|
||||
## 9. 结束条件
|
||||
## 9. 让经验成为有证据、会过期的知识护栏
|
||||
|
||||
项目特有、跨任务复用且会改变后续开发或验证行为的经验，可以提名到项目知识护栏。
|
||||
不要把全部对话、日志或单次猜测自动保存成“记忆”。
|
||||
|
||||
```text
|
||||
Developer / Test 当前任务观测
|
||||
-> knowledgeCandidates（只留在任务证据）
|
||||
-> Test 独立验证 + Coordinator gate
|
||||
-> Coordinator 写入 active knowledge
|
||||
-> stale
|
||||
-> superseded / archived
|
||||
```
|
||||
|
||||
`prepare(task)` 时只按 component、path、dependency、version 和 tag 推荐相关
|
||||
`active` 条目；自动匹配只负责推荐，Coordinator 确认固定 revision 的显式
|
||||
`knowledgeRefs` 才是本轮权威上下文。每轮只派发命中的少量条目，不全量注入知识库。
|
||||
|
||||
Developer 回报实际采用的 `knowledgeApplied` 和带当前观测证据的
|
||||
`knowledgeCandidates`。Test 对本轮显式引用回报 `knowledgeChecks`，并用独立观测
|
||||
确认或否定 candidate。同一 Agent 不能把自己读到的旧知识复述成新证据，避免错误
|
||||
知识自我强化。
|
||||
|
||||
知识中的验证只能引用 `knowledge.yaml.verificationRegistry` 中已经审查的仓库内
|
||||
相对 path 和结构化 args，不能把正文或选择器输出拼接成自由 shell 执行。实际运行
|
||||
只把 registry ID 交给 `<ack-skill-dir>/scripts/run_verification.py`。安全、正确性
|
||||
和兼容性等关键约束一旦稳定，应下沉为测试、lint、CI 或正式规范；知识项继续解释
|
||||
触发条件、原因与证据，不替代可执行控制。
|
||||
|
||||
依赖、配置、路径或版本变化后应重新审查相关知识。临时 workaround 必须有失效或
|
||||
移除条件；冲突规则不能靠“最后写入者获胜”处理。
|
||||
|
||||
---
|
||||
|
||||
## 10. 结束条件
|
||||
|
||||
一轮闭环结束时，必须能回答：
|
||||
|
||||
@@ -146,5 +180,7 @@ one dispatch = one bug = one acceptance path
|
||||
- 每个 leftover 失败了几轮？最后一轮失败证据是什么？
|
||||
- 当前工作树有哪些未提交改动？
|
||||
- 是否还有 open / failed_retest 未处理？
|
||||
- 本轮显式 `knowledgeRefs` 是否都有必要的 `knowledgeChecks`？
|
||||
- 是否有待验证 candidate，或因依赖、路径、版本变化需要转为 stale 的知识？
|
||||
|
||||
答不清楚，闭环就还没结束。
|
||||
@@ -0,0 +1,277 @@
|
||||
# Orca 适配器（稳定核心，一种编排实现）
|
||||
|
||||
Orca orchestration 是运行时调度层的一种实现。闭环流程本身与工具无关（见 `closed-loop.md`）；本文件只提供 Orca 的具体命令。没有 Orca 时用 `closed-loop.md` §「手动模式」。
|
||||
|
||||
所有结论仍以 `tasks.yaml` 为准，Orca 消息不是最终记录。
|
||||
|
||||
---
|
||||
|
||||
## 何时用 Orca 编排
|
||||
|
||||
用：需要监督、等待结果、闭环修复、三轮重试；有多个可独立派发的任务；需要 `worker_done` 后再复测。
|
||||
|
||||
不用：单次问答；用户只要求完整 handoff 不需监督；不需要复测的小改动。
|
||||
|
||||
---
|
||||
|
||||
## 运行前检查
|
||||
|
||||
```bash
|
||||
orca status --json
|
||||
orca terminal list --json
|
||||
orca orchestration task-list --json
|
||||
orca orchestration inbox --limit 20 --json
|
||||
```
|
||||
|
||||
确认：Orca runtime 可达并取得本次 `runtimeId`；Coordinator 终端存在；当前没有冲突
|
||||
的活跃编排任务。Developer/Test worker 必须通过本次 launcher 新建，不要求预先存在。
|
||||
|
||||
---
|
||||
|
||||
## 既有 worker 的处理
|
||||
|
||||
v0.10 **不自动复用任何既有终端**。`receiptHash` 是无密钥 checksum，Orca 当前的
|
||||
terminal metadata 也不包含原始 Agent argv、模型或权限 attestation；两者即使完全
|
||||
匹配，仍不足以证明旧终端由可信 launcher 以目标 profile 创建。标题、preview、分支
|
||||
名或 worker 自报更不能作为证明。
|
||||
|
||||
| 情况 | 动作 |
|
||||
|------|------|
|
||||
| 历史 receipt 与 live metadata 看似完全匹配 | 只作审计，不自动复用；重新 launch |
|
||||
| 没有 receipt，或只有同名终端 | 不复用；重新 launch |
|
||||
| 需要并发 worker | 使用下一 `slot` 重新 launch |
|
||||
| Developer 升级模型档位 | 选择强档安全 profile，重新 plan/launch |
|
||||
|
||||
只有刚刚成功返回的 `launch` 标准输出中的 fresh handle，才可用于紧随其后的本次
|
||||
dispatch。未来若 Orca/ACP 增加启动参数 attestation，或 ACK 接入项目外可信签发
|
||||
通道，再单独设计自动复用；不能用项目文档声明跳过这条限制。
|
||||
|
||||
---
|
||||
|
||||
## 通过 launcher 创建 worker
|
||||
|
||||
**模型不由 Orca dispatch 设置。** `task-create` / `dispatch` 只投递任务；Agent CLI、
|
||||
模型、reasoning effort 和权限由 `tasks.yaml.project.orchestration` 的结构化 profile
|
||||
决定，并且只能由 ACK launcher 构造。
|
||||
|
||||
先只读生成计划：
|
||||
|
||||
```bash
|
||||
python3 <ack-skill-dir>/scripts/launch_worker.py plan \
|
||||
--project-root <project-root> --task-id <task-id> \
|
||||
--attempt-id <task-id>-A<round> --role <developer-or-test> \
|
||||
--profile-id <profile-id> --worktree <absolute-worktree> --slot <1..99>
|
||||
```
|
||||
|
||||
确认计划中的任务、attempt、角色、profile hash、绝对 worktree 和安全权限模式后，再
|
||||
执行唯一启动入口：
|
||||
|
||||
```bash
|
||||
python3 <ack-skill-dir>/scripts/launch_worker.py launch \
|
||||
--project-root <project-root> --task-id <task-id> \
|
||||
--attempt-id <task-id>-A<round> --role <developer-or-test> \
|
||||
--profile-id <profile-id> --worktree <absolute-worktree> --slot <1..99> \
|
||||
--expected-launch-fingerprint <plan 中的 sha256:...>
|
||||
```
|
||||
|
||||
`launch` 必须携带刚才审阅的 `plan.launchFingerprint`；若 profile、任务/attempt、
|
||||
worktree、CLI identity/version 或精确 argv 漂移，创建前就失败。它内部调用当前
|
||||
Orca 后端并完成终端绑定；Coordinator 不自行执行或拼装 Orca 的底层终端创建文本，
|
||||
也不直接调用 launcher 的私有 bootstrap。
|
||||
若 launcher 报告 `indeterminate` 或 `reconcile required`，说明终端可能已经创建且
|
||||
持久关闭尚未得到可信确认；此时先按返回的 launch ID/record 和 Orca live state
|
||||
人工核对，禁止直接重复执行 `launch`。
|
||||
标准输出是单一 JSON。成功后：
|
||||
|
||||
1. 校验返回 receipt 的 `receiptHash`；
|
||||
2. 把 receipt 原样追加到 `tasks.yaml.workerReceipts`；
|
||||
3. 把 `receipt.id` 写入当前任务 `dispatch.<role>.receiptId`，把 `profileId` 写入
|
||||
`dispatch.<role>.profileId`，把本轮 `<task-id>-A<round>` 写入
|
||||
`dispatch.<role>.attemptId`；校验器会要求 receipt 的 task/role/profile/attempt
|
||||
与当前 ACK 任务完全一致；
|
||||
4. 再用 receipt binding 中的 handle 创建/派发 Orca 子任务。
|
||||
|
||||
profile 只允许 `read-only` 或 `workspace-write`。v0.10 不提供可信的 full-access 授权
|
||||
通道；bypass、YOLO/force、关闭 sandbox 及其它 full-access 请求必须由 schema 和
|
||||
launcher fail closed，不能改用手写命令兜底。模型档位与升级规则见
|
||||
`model-routing.md`。
|
||||
|
||||
需要隔离/并行时，可以先用 Orca 创建 worktree。Coordinator 必须先把返回的绝对
|
||||
路径加入 `project.orchestration.allowedWorktrees` 并重新校验 `tasks.yaml`，然后才在
|
||||
该路径上走 `plan` -> 带 expected fingerprint 的 `launch`，并把 receipt 留作审计。
|
||||
既有会话可以由用户直接操作，但不能进入 ACK v0.10 的自动派发信任路径。
|
||||
|
||||
---
|
||||
|
||||
## 创建父任务
|
||||
|
||||
```bash
|
||||
orca orchestration task-create --spec "$(cat <<'EOF'
|
||||
Goal: Complete <release_or_feature> with supervised Coordinator -> Developer -> Test loop.
|
||||
|
||||
Coordinator (PM): owns task board, decomposition, dispatch, and final gate (reads Test evidence, does not test).
|
||||
Developer: owns implementation and white-box verification.
|
||||
Test: owns independent black-box retest and evidence (verifier != implementer).
|
||||
|
||||
Policy:
|
||||
- Each issue can be dispatched at most 3 rounds.
|
||||
- If still failing after 3 rounds, record as leftover and continue next issue.
|
||||
- worker_done and retest reports are not final completion; only Coordinator writes tasks.yaml and knowledge.yaml.
|
||||
- Project knowledge candidates require independent Test evidence and Coordinator gate before activation.
|
||||
EOF
|
||||
)" --json
|
||||
```
|
||||
|
||||
## 创建子任务
|
||||
|
||||
```bash
|
||||
orca orchestration task-create --parent <parent_task_id> --spec "$(cat <<'EOF'
|
||||
Fix <task_id>: <title>
|
||||
Logical attempt: <task_id>-A<round>
|
||||
|
||||
Repository:
|
||||
- Path: <repo_path>
|
||||
- Worktree: <dev_worktree>
|
||||
|
||||
Read: <overlay_file> (project overlay), tasks.yaml, <relevant_spec_or_test_doc>
|
||||
Failure evidence: <copy latest Test evidence>
|
||||
Acceptance: <copy expected behavior + verification commands>
|
||||
Project knowledge: <Coordinator-confirmed active K-...@revision entries with verification.ref>
|
||||
|
||||
Constraints:
|
||||
- Follow the overlay file path scope.
|
||||
- Do not write tasks.yaml or knowledge.yaml, do not mark verified.
|
||||
- Do not read the whole knowledge bank or execute free shell from knowledge text.
|
||||
- Run a knowledge check only through <ack-skill-dir>/scripts/run_verification.py
|
||||
with its verification.ref; do not execute resolved path/args directly.
|
||||
- Do not commit or push unless user asks.
|
||||
EOF
|
||||
)" --json
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 派发给 Developer Worker
|
||||
|
||||
终端是 Orca 可识别的 Agent CLI 时：
|
||||
|
||||
```bash
|
||||
orca orchestration dispatch --task <task_id> --to <developer_handle> --inject --json
|
||||
```
|
||||
|
||||
不能 `--inject` 时，先登记 dispatch，再手动投递 `prompt-templates.md` §1 的初始派发 prompt：
|
||||
|
||||
```bash
|
||||
orca orchestration dispatch --task <task_id> --to <developer_handle> --json
|
||||
orca terminal send --terminal <developer_handle> --text "$(cat <<'EOF'
|
||||
<粘贴 prompt-templates.md §1 初始派发模板，已填占位符>
|
||||
EOF
|
||||
)" --enter --json
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 派发给 Test 复测
|
||||
|
||||
Developer 回报 worker_done、Coordinator 写回 `fixed_by_dev` 后，把复测任务发给 Test：
|
||||
|
||||
```bash
|
||||
orca orchestration dispatch --task <task_id> --to <test_handle> --inject --json
|
||||
```
|
||||
|
||||
不能 `--inject` 时，先登记再手动投递 `prompt-templates.md` §3 的复测派发 prompt：
|
||||
|
||||
```bash
|
||||
orca orchestration dispatch --task <task_id> --to <test_handle> --json
|
||||
orca terminal send --terminal <test_handle> --text "$(cat <<'EOF'
|
||||
<粘贴 prompt-templates.md §3 复测派发模板，已填占位符>
|
||||
EOF
|
||||
)" --enter --json
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 等待结果
|
||||
|
||||
```bash
|
||||
orca orchestration check \
|
||||
--terminal <coordinator_handle> \
|
||||
--wait \
|
||||
--types worker_done,retest_result,escalation,decision_gate \
|
||||
--timeout-ms 900000 \
|
||||
--json
|
||||
```
|
||||
|
||||
等待超时不等于失败。长任务可继续等待，或检查 worker 终端活性。`worker_done` 来自 Developer，`retest_result`（无该类型时用 `worker_done` + subject 区分）来自 Test。
|
||||
|
||||
---
|
||||
|
||||
## Developer 回报 worker_done
|
||||
|
||||
字段含义见 `prompt-templates.md` §4：
|
||||
|
||||
```bash
|
||||
orca orchestration send \
|
||||
--to <coordinator_handle> \
|
||||
--type worker_done \
|
||||
--subject "<task_id> fix ready round <n>" \
|
||||
--body "<修了什么。跑了哪些验证。如何复现。还有什么风险。>" \
|
||||
--payload '{
|
||||
"taskId": "<orca_task_id>",
|
||||
"dispatchId": "<orca_dispatch_id>",
|
||||
"attemptId": "<task_id>-A<n>",
|
||||
"filesModified": ["<file_a>", "<file_b>"],
|
||||
"verification": ["<command_a>: passed", "<command_b>: passed"],
|
||||
"knowledgeApplied": [
|
||||
{"ref": "<K-001@1>", "result": "applied", "evidence": "<what was done>"}
|
||||
],
|
||||
"knowledgeCandidates": [
|
||||
{
|
||||
"kind": "pitfall",
|
||||
"title": "<title>",
|
||||
"claim": "<evidence-backed claim>",
|
||||
"scope": {"components": ["<component>"], "paths": ["<path glob>"]},
|
||||
"appliesWhen": "<trigger>",
|
||||
"directive": "<action, not a shell command>",
|
||||
"rationale": "<why it matters>",
|
||||
"evidenceRefs": ["<current task evidence>"]
|
||||
}
|
||||
],
|
||||
"risk": "<remaining risk or none>"
|
||||
}' \
|
||||
--json
|
||||
```
|
||||
|
||||
收到 worker_done 后，Coordinator 写回 `fixed_by_dev`，再按上文派发给 Test 复测。
|
||||
|
||||
---
|
||||
|
||||
## Test 回报复测结果
|
||||
|
||||
字段含义见 `prompt-templates.md` §5：
|
||||
|
||||
```bash
|
||||
orca orchestration send \
|
||||
--to <coordinator_handle> \
|
||||
--type retest_result \
|
||||
--subject "<task_id> retest round <n>" \
|
||||
--body "<逐条验收信号结论 + 实际观察 + 证据>" \
|
||||
--payload '{
|
||||
"taskId": "<orca_task_id>",
|
||||
"dispatchId": "<orca_dispatch_id>",
|
||||
"attemptId": "<task_id>-A<n>",
|
||||
"env": {"worktree": "<path>", "branch": "<branch>", "commit": "<sha>", "baseUrl": "<base_url>"},
|
||||
"signals": ["<signal 1>: pass", "<signal 2>: fail (<evidence>)"],
|
||||
"knowledgeChecks": [
|
||||
{"ref": "<K-001@1>", "result": "passed", "evidence": "<independent evidence>"}
|
||||
],
|
||||
"knowledgeCandidates": [],
|
||||
"conclusion": "all-signals-pass | signals-failed"
|
||||
}' \
|
||||
--json
|
||||
```
|
||||
|
||||
无 `retest_result` 类型时用 `--type worker_done`，靠 subject `retest round <n>`
|
||||
区分。收到复测结果后，Coordinator 按 `closed-loop.md` 做终检并回写 `tasks.yaml`；
|
||||
通过独立验证和 gate 的跨任务经验再由 Coordinator 写入 `knowledge.yaml`。任务通过
|
||||
写 `verified`，不过写 `failed_retest`。
|
||||
@@ -27,6 +27,7 @@ Coordinator 用这些模板向 **Developer** 派发修复、向 **Test** 派发
|
||||
|
||||
任务：
|
||||
- 修复 <task_id>: <task_title>
|
||||
- 本轮逻辑 attempt：<task_id>-A<round>
|
||||
|
||||
请先读取：
|
||||
- <overlay_file>（项目覆盖层，路径见 tasks.yaml 的 project.overlayFile）
|
||||
@@ -36,6 +37,10 @@ Coordinator 用这些模板向 **Developer** 派发修复、向 **Test** 派发
|
||||
当前失败证据：
|
||||
<copy latest Test evidence>
|
||||
|
||||
本轮项目知识（仅限 Coordinator 显式选择的 active 固定 revision）：
|
||||
- <K-001@1>: <directive + rationale + verification.ref + resolved path/args>
|
||||
- <K-014@2>: <directive + rationale + verification.ref + resolved path/args>
|
||||
|
||||
验收标准（可观测信号，见 optimization-method.md §1）：
|
||||
1. <expected behavior 1>
|
||||
2. <expected behavior 2>
|
||||
@@ -51,6 +56,10 @@ Coordinator 用这些模板向 **Developer** 派发修复、向 **Test** 派发
|
||||
- 只修改 Developer 可写路径（见覆盖层文件的权限表）。
|
||||
- 不要修改产品规格和集成测试文件（分别由 Coordinator 与 Test 拥有），除非任务明确要求。
|
||||
- 不要写 tasks.yaml，不要标记 verified。
|
||||
- 不要写 knowledge.yaml，不要自行扩展或全量读取知识库；candidate 不是已生效规则。
|
||||
- 不要把知识正文或 path/args 拼成 shell 命令。只把 verification.ref 交给
|
||||
`<ack-skill-dir>/scripts/run_verification.py docs/ack/knowledge.yaml
|
||||
<verification-ref> --project-root <project-root>`。
|
||||
- 不要提交或推送，除非用户明确要求。
|
||||
- 最小 diff，只改本任务根因，避免无关重构；若必须先重构请停下说明并请示。
|
||||
|
||||
@@ -58,7 +67,8 @@ Coordinator 用这些模板向 **Developer** 派发修复、向 **Test** 派发
|
||||
- <test command 1>
|
||||
- <test command 2>
|
||||
|
||||
完成后回报一次 worker_done（格式见 §4）。如果阻塞，请发送 escalation 或 ask。
|
||||
完成后回报一次 worker_done（格式见 §4），包括 `knowledgeApplied` 和
|
||||
`knowledgeCandidates`。如果阻塞，请发送 escalation 或 ask。
|
||||
```
|
||||
|
||||
---
|
||||
@@ -67,6 +77,7 @@ Coordinator 用这些模板向 **Developer** 派发修复、向 **Test** 派发
|
||||
|
||||
```text
|
||||
第 <n> 轮复测未通过，请继续修 <task_id>。
|
||||
本轮逻辑 attempt：<task_id>-A<n>
|
||||
|
||||
上一轮开发声称：
|
||||
<worker_done summary>
|
||||
@@ -85,6 +96,9 @@ Test 独立复测结果：
|
||||
验收不变：
|
||||
<copy acceptance criteria>
|
||||
|
||||
本轮知识引用：
|
||||
<copy Coordinator confirmed knowledgeRefs; do not add candidates>
|
||||
|
||||
完成后回报 worker_done，subject 使用："<task_id> fix ready round <n>"
|
||||
```
|
||||
|
||||
@@ -96,6 +110,7 @@ Developer 回报 worker_done 后，Coordinator 把复测任务发给 Test。
|
||||
|
||||
```text
|
||||
请对 <task_id>: <task_title> 做独立黑盒复测。
|
||||
本轮逻辑 attempt：<task_id>-A<round>
|
||||
|
||||
请先读取：
|
||||
- <overlay_file>（项目覆盖层，路径见 tasks.yaml 的 project.overlayFile）
|
||||
@@ -105,6 +120,12 @@ Developer 回报 worker_done 后，Coordinator 把复测任务发给 Test。
|
||||
Developer 本轮声称（仅供参考，不作数）：
|
||||
- 改动文件：<files>
|
||||
- 自测命令：<commands>
|
||||
- 实际采用知识：<knowledgeApplied>
|
||||
- 新知识候选：<knowledgeCandidates; candidate only>
|
||||
|
||||
本轮项目知识（仅限 Coordinator 显式选择的 active 固定 revision）：
|
||||
- <K-001@1>: <directive + rationale + verification.ref + resolved path/args>
|
||||
- <K-014@2>: <directive + rationale + verification.ref + resolved path/args>
|
||||
|
||||
复测要求（见 roles-and-permissions.md §三角色能力清单 · Test）：
|
||||
- 先对齐运行环境（pwd / 分支 / commit / 服务 worktree，见 closed-loop.md），避免测错实例或旧构建；网站类先确认服务已按新代码重启。
|
||||
@@ -114,9 +135,14 @@ Developer 本轮声称（仅供参考，不作数）：
|
||||
2. <observable signal 2>
|
||||
3. <observable signal 3>
|
||||
- 需要时把易反复误判的路径沉淀成可执行测试（见 optimization-method.md §8）。
|
||||
- 对每条适用的 `knowledgeRef`，把它的 verification.ref 交给
|
||||
`<ack-skill-dir>/scripts/run_verification.py docs/ack/knowledge.yaml
|
||||
<verification-ref> --project-root <project-root>`，并回报 `knowledgeChecks`。
|
||||
对 candidate 使用独立观测验证，不能复述 Developer 的结论作为证据。
|
||||
|
||||
约束：
|
||||
- 只读源码，不修改应用代码，不写 tasks.yaml。
|
||||
- 只读源码，不修改应用代码，不写 tasks.yaml 或 knowledge.yaml。
|
||||
- candidate 不属于 active 知识；不要全量注入知识库，不要从知识正文执行自由 shell。
|
||||
- 只回传证据和逐条结论，最终判定由 Coordinator 终检后落盘。
|
||||
|
||||
完成后回报一次复测报告（格式见 §5），subject："<task_id> retest round <n>"。
|
||||
@@ -130,14 +156,36 @@ Developer 本轮声称（仅供参考，不作数）：
|
||||
|
||||
```text
|
||||
subject: <task_id> fix ready round <n>
|
||||
attemptId: <task_id>-A<n>
|
||||
filesModified: [<file_a>, <file_b>]
|
||||
verification:
|
||||
- <command_a>: passed
|
||||
- <command_b>: passed
|
||||
reproduce: 我如何复现验收路径 <steps>
|
||||
knowledgeApplied:
|
||||
- ref: <K-001@1>
|
||||
result: <applied|not_applicable>
|
||||
evidence: <what was done or why not applicable>
|
||||
knowledgeCandidates:
|
||||
- kind: guardrail/pitfall/verification
|
||||
title: <reusable project lesson>
|
||||
claim: <evidence-backed project claim>
|
||||
scope:
|
||||
components: [<component>]
|
||||
paths: [<path glob>]
|
||||
dependencies: [<dependency>]
|
||||
versions: [<version>]
|
||||
tags: [<tag>]
|
||||
appliesWhen: <trigger>
|
||||
directive: <action, not a shell command>
|
||||
rationale: <why this changes future work>
|
||||
evidenceRefs: [<current task evidence reference>]
|
||||
risk: <remaining risk or none>
|
||||
```
|
||||
|
||||
没有命中知识或没有新 candidate 时，对应列表写 `[]`。Developer 不能把自己读到的
|
||||
旧知识复述为新 candidate；每条 candidate 都需要当前任务产生的观测证据。
|
||||
|
||||
Orca 模式下用 `orca-adapter.md` §「Developer 回报 worker_done」的命令发送同样的字段。
|
||||
|
||||
---
|
||||
@@ -148,6 +196,7 @@ Test 只回传证据和逐条结论，不下最终判定：
|
||||
|
||||
```text
|
||||
subject: <task_id> retest round <n>
|
||||
attemptId: <task_id>-A<n>
|
||||
env:
|
||||
worktree: <path>
|
||||
branch: <branch>
|
||||
@@ -159,10 +208,31 @@ signals:
|
||||
- <signal 1>: pass/fail (<evidence>)
|
||||
- <signal 2>: pass/fail (<evidence>)
|
||||
browser: <snapshot / DOM / API evidence>
|
||||
knowledgeChecks:
|
||||
- ref: <K-001@1>
|
||||
result: <passed|failed|not_applicable>
|
||||
evidence: <independent evidence>
|
||||
knowledgeCandidates:
|
||||
- kind: guardrail/pitfall/verification
|
||||
title: <new lesson found by Test>
|
||||
claim: <evidence-backed project claim>
|
||||
scope:
|
||||
components: [<component>]
|
||||
paths: [<path glob>]
|
||||
dependencies: [<dependency>]
|
||||
versions: [<version>]
|
||||
tags: [<tag>]
|
||||
appliesWhen: <trigger>
|
||||
directive: <action, not a shell command>
|
||||
rationale: <why this changes future work>
|
||||
evidenceRefs: [<independent evidence reference>]
|
||||
conclusion: all-signals-pass / signals-failed
|
||||
notes: <observations, suspected cause if failed>
|
||||
notes: <observations, suspected cause, and independent candidate validation evidence>
|
||||
```
|
||||
|
||||
没有适用项时列表写 `[]`。Test 的知识结论仍只是证据；只有 Coordinator 能写入或
|
||||
激活 `knowledge.yaml`。
|
||||
|
||||
Orca 模式下用 `orca-adapter.md` §「Test 回报复测结果」的命令发送同样的字段。
|
||||
|
||||
---
|
||||
@@ -181,6 +251,18 @@ Orca 模式下用 `orca-adapter.md` §「Test 回报复测结果」的命令发
|
||||
验证命令：
|
||||
- <command>: passed
|
||||
|
||||
项目知识：
|
||||
- 本轮采用：<knowledgeRefs and checks>
|
||||
- 新增或更新：<active/stale/superseded entries written by Coordinator, or none>
|
||||
- 待验证 candidate：<remaining candidates or none>
|
||||
|
||||
交付（未启用时写 n/a）：
|
||||
- run/profile/status：<delivery run id / profile / review_ready|released|blocked|failed>
|
||||
- PR/MR：<URL and head/base>
|
||||
- 产物：<reference, digest, destination>
|
||||
- 部署：<environment, health/rollback evidence>
|
||||
- 待审批或未完成：<approval/blocked step or none>
|
||||
|
||||
工作树状态：
|
||||
- <repo_path>: <git status summary>
|
||||
- <dev_worktree>: <git status summary>
|
||||
+68
-17
@@ -8,16 +8,16 @@
|
||||
|
||||
## 角色模型（三角色）
|
||||
|
||||
本 kit 默认三个独立 Agent：**Coordinator 只编排、Test 只验证、Developer 只实现**。关键属性是**验证者 ≠ 实现者**：Developer 不能给自己盖章，验证权在独立的 Test。
|
||||
ACK 默认三个独立 Agent：**Coordinator 只编排、Test 只验证、Developer 只实现**。关键属性是**验证者 ≠ 实现者**：Developer 不能给自己盖章，验证权在独立的 Test。
|
||||
|
||||
| 角色 | 主要职责 | 验证方式 | 不应做的事 |
|
||||
|------|----------|----------|------------|
|
||||
| Coordinator (PM) | 需求拆解、定验收信号、排优先级、写 `tasks.yaml`、向 Developer/Test 派发、跑三轮闭环、做最终 gate | 读 Test 证据并对齐原始意图（不亲自跑测试） | 修改源码、亲自复测、凭 worker_done 直接标 `verified` |
|
||||
| Test | 黑盒复测、回归验证、沉淀可执行测试、产出证据 | 浏览器、API、集成脚本、用户可见行为 | 修改应用源码、修改产品规格、写 `tasks.yaml` |
|
||||
| Developer | 实现修复、写单元测试、运行构建和白盒验证 | 单元测试、类型检查、构建、本地运行 | 修改产品规格与集成测试、标记 `verified`、绕过测试声称完成 |
|
||||
| Coordinator (PM) | 需求拆解、定验收信号、排优先级、单写 `tasks.yaml` / `knowledge.yaml`、选择知识、向 Developer/Test 派发、跑三轮闭环、做最终 gate；经确认后编排可选交付 | 读 Test 证据并对齐原始意图（不亲自跑测试）；核对交付证据 | 修改源码、亲自复测、凭 worker_done 直接标 `verified`、自动激活未验证知识、把配置当作发布授权 |
|
||||
| Test | 黑盒复测、回归验证、执行知识检查、独立验证知识候选、沉淀可执行测试、产出证据 | 浏览器、API、集成脚本、用户可见行为 | 修改应用源码、修改产品规格、写 `tasks.yaml` 或 `knowledge.yaml` |
|
||||
| Developer | 实现修复、写单元测试、运行构建和白盒验证、提名项目知识 | 单元测试、类型检查、构建、本地运行 | 修改产品规格与集成测试、写项目状态、标记 `verified`、绕过测试声称完成 |
|
||||
| User / Decision Owner | 决定范围、优先级、阻塞项是否继续 | 审阅报告和遗留清单 | 直接替代复测证据 |
|
||||
|
||||
**独立验证权归 Test。** Coordinator 不亲自复测——它读 Test 的证据，并对照任务的原始意图做一次终检（见「完成定义」）。`worker_done` 不等于完成的原则同时适用于 Developer 和 Test：结论只有落到 `tasks.yaml` 才算数。
|
||||
**独立验证权归 Test。** Coordinator 不亲自复测，它读 Test 的证据，并对照任务的原始意图做一次终检（见「完成定义」）。`worker_done` 不等于完成的原则同时适用于 Developer 和 Test：结论只有落到 `tasks.yaml` 才算数。
|
||||
|
||||
**模型档位（正交层）。** 三角色默认按成本分层：Coordinator 用强模型，Test 与 Developer 用中低模型，必要时升级。完整档位表与升级规则见 `model-routing.md`。Coordinator 用强模型但不跑测试，这一分工天然省 token 又不破坏「验证者 ≠ 实现者」。
|
||||
|
||||
@@ -29,7 +29,7 @@
|
||||
|
||||
这些是**通用工程习惯**，不含项目命令与路径；项目差异写在覆盖层文件（默认 `docs/ack/project.md`）。装了外部 skill 的环境可按每个角色末尾的「可选 skills」加速，未装则照本清单执行，不阻塞。
|
||||
|
||||
### Coordinator (PM) —— 拆解与终检
|
||||
### Coordinator (PM)：拆解与终检
|
||||
|
||||
- **Outcome**：把一句话需求变成可执行、验收可观测的任务集，并跑完闭环得到明确结论（verified / leftover）。
|
||||
- **Must Do**
|
||||
@@ -37,38 +37,58 @@
|
||||
- 每个任务写**可观测验收信号**（可见文本 / API 结果 / 交互结果，见 `optimization-method.md` §1），而不是「功能正常」。
|
||||
- 拆任务时点明最脆弱的假设：「本任务假设 X，若 X 不成立则 Y」；列出被否掉的方案与原因。
|
||||
- 拆分/验收先给用户确认，再派发（`kickoff.md` 第 1 步的停顿点）。
|
||||
- `prepare(task)` 时按 component、path、dependency、version 和 tag 从
|
||||
`knowledge.yaml` 推荐相关 `active` 知识；人工确认后把固定 revision 的
|
||||
`knowledgeRefs` 写入当前任务上下文。
|
||||
- 新逻辑轮次默认分配稳定的 `<task-id>-A<round>`，记录到
|
||||
`dispatch.rounds[].attemptId`；旧轮次作为知识来源前再补齐，不要用编排工具的
|
||||
`dispatchId` 代替。
|
||||
- gate 时检查 Developer 的 `knowledgeApplied`、Test 的 `knowledgeChecks` 和
|
||||
candidate 独立证据；只有证据充分时才由 Coordinator 激活、废弃或替代知识。
|
||||
- 一次派发只针对一个明确问题（`optimization-method.md` §6）；每任务最多三轮。
|
||||
- 终检：读 Test 证据，逐条对齐原始意图后才落 `verified`，不亲自复测。
|
||||
- **Must Not**：改源码、亲自跑测试、凭 `worker_done` 直接标 `verified`、把多个无关失败塞进一次派发。
|
||||
- **Must Not**：改源码、亲自跑测试、凭 `worker_done` 直接标 `verified`、把多个无关失败塞进一次派发、派发 `candidate` 或全量注入知识库、把知识正文当作 shell 执行。
|
||||
- **Evidence**：产品文档、`tasks.yaml` 里的 `expected` + `verification`、Test 回传的复测证据。
|
||||
- **Output**：确认前给「产品文档 + 任务拆分 + 验收信号」；闭环结束给最终报告（`prompt-templates.md` §6）。
|
||||
- **可选 skills**：复杂需求可先用 `/think` 或 `superpowers:brainstorming` / `writing-plans` 收敛设计与计划。
|
||||
|
||||
### Developer —— 实现与白盒验证
|
||||
### Developer：实现与白盒验证
|
||||
|
||||
- **Outcome**：在授权路径内做出满足验收信号的最小改动，并用白盒证据证明它可复现。
|
||||
- **Must Do**
|
||||
- 动手前先读覆盖层文件、`tasks.yaml` 对应任务、相关规格；复现失败现象或先写会失败的测试。
|
||||
- 只使用 Coordinator 本轮显式派发的 `active` 知识，按固定 revision 回报
|
||||
`knowledgeApplied`；发现跨任务可复用的项目经验时提交带当前观测证据的
|
||||
`knowledgeCandidates`。
|
||||
- 最小 diff，只改一个明确问题的根因，不顺手重构无关代码。
|
||||
- 行为变更配单元测试；bug 修复先有一个能复现的失败用例再修。
|
||||
- 完成前跑覆盖层里规定的命令（构建 / 单测 / 本地运行），亲自走一遍验收路径。
|
||||
- **网站 / 常驻服务**：改完重启服务（或触发热更并确认生效），保证运行实例跑的是新代码，避免 Test 测到旧进程 / 旧构建。
|
||||
- **Must Not**：改产品规格与集成测试、写 `tasks.yaml`、标 `verified`、绕过测试声称完成、把 bug 修复扩成大重构（需要就先停下说明并请示）。
|
||||
- **Evidence**：改了哪些文件、跑了哪些命令及结果、如何复现验收路径、残留风险。
|
||||
- **Must Not**：改产品规格与集成测试、写 `tasks.yaml` 或 `knowledge.yaml`、标
|
||||
`verified`、把 candidate 当作已生效规则、绕过测试声称完成、把 bug 修复扩成大
|
||||
重构（需要就先停下说明并请示）。
|
||||
- **Evidence**：改了哪些文件、跑了哪些命令及结果、如何复现验收路径、实际采用的
|
||||
`knowledgeRefs`、新 candidate 的当前任务证据、残留风险。
|
||||
- **Output**：一次 `worker_done`，字段见 `prompt-templates.md` §4（只报证据，不下最终结论）。
|
||||
- **可选 skills**：排查用 `/hunt` 或 `superpowers:systematic-debugging`（先根因后修）；实现行为变更用 `superpowers:test-driven-development`。
|
||||
|
||||
### Test —— 独立黑盒复测
|
||||
### Test：独立黑盒复测
|
||||
|
||||
- **Outcome**：以独立视角复现验收路径，逐条给出通过/失败的可观测证据，供 Coordinator 终检。
|
||||
- **Must Do**
|
||||
- 先对齐运行环境（pwd / 分支 / commit / 服务 worktree，见 `closed-loop.md`），避免测错实例或旧构建；网站类先确认服务已按新代码重启。
|
||||
- 逐条验证验收信号，验证交互后的真实状态，而不是只看静态文案。
|
||||
- 对 Coordinator 派发的每条 `knowledgeRef` 执行适用的额外检查，回报
|
||||
`knowledgeChecks`；对本轮 candidate 使用独立观测验证，不能复述 Developer
|
||||
结论当作证据。
|
||||
- **网站类任务优先用浏览器复测**真实交互（点击 / 跳转 / 渲染），其次才是 API / 脚本；纯后端 / CLI 则以 API smoke 或脚本为主。
|
||||
- 把最容易反复误判的路径沉淀成可执行测试（`optimization-method.md` §8）。
|
||||
- 只回传证据 + 逐条结论，最终判定留给 Coordinator。
|
||||
- **Must Not**：改应用源码、改产品规格、写 `tasks.yaml`、凭 Developer 的 `worker_done` 直接下结论。
|
||||
- **Evidence**：运行环境快照、命令结果、每条信号 pass/fail + 证据（snapshot / DOM / API 结果）。
|
||||
- **Must Not**：改应用源码、改产品规格、写 `tasks.yaml` 或 `knowledge.yaml`、凭
|
||||
Developer 的 `worker_done` 直接下结论、把 candidate 作为 active 知识执行。
|
||||
- **Evidence**：运行环境快照、命令结果、每条信号 pass/fail + 证据
|
||||
（snapshot / DOM / API 结果）、每条适用知识的
|
||||
`passed` / `failed` / `not_applicable` + 证据。
|
||||
- **Output**：一次复测报告，字段见 `prompt-templates.md` §5。
|
||||
- **可选 skills**：合并 / 发版前检查可用 `/check` 或 `superpowers:verification-before-completion`（证据先于结论）。
|
||||
|
||||
@@ -87,7 +107,9 @@
|
||||
| `<unit_test_paths>` | Read-only | Read-only | R/W | 单元测试 |
|
||||
| `<shared_config_templates>` | Read-only | Read-only | R/W | 可提交配置模板 |
|
||||
| `<local_config>` | Read-only | Read-only | Read-only | 本地私有配置，不提交 |
|
||||
| `tasks.yaml` | R/W | Read-only | Read-only | 见下方「任务板写入约定」 |
|
||||
| `tasks.yaml` | R/W | Read-only | Read-only | 见下方「项目状态写入约定」 |
|
||||
| `knowledge.yaml` | R/W | Read-only | Read-only | Coordinator 单写；Developer/Test 通过回报提名或验证 |
|
||||
| `delivery.yaml` | 仅显式维护时 R/W | Read-only | Read-only | 声明项目交付能力，不保存凭据或执行授权 |
|
||||
|
||||
---
|
||||
|
||||
@@ -124,16 +146,43 @@ failed_retest（累计 3 轮） -> leftover
|
||||
|
||||
三轮失败的处理细则见 `optimization-method.md` §「三轮失败策略」。
|
||||
|
||||
## 交付状态（与任务状态正交）
|
||||
|
||||
任务进入 `verified` 后不再改写为发布或部署状态。可选交付的每次执行单独记录在
|
||||
`tasks.yaml.deliveryRuns`：
|
||||
|
||||
```text
|
||||
planned -> running -> review_ready | released
|
||||
-> blocked | failed
|
||||
planned -> skipped
|
||||
```
|
||||
|
||||
`review_ready` 表示 PR、preview 产物和已授权的非生产部署证据已经齐备，等待用户
|
||||
审核；`released` 只用于用户明确批准后的 stable 发布或 production 部署。交付失败
|
||||
不会否定已经独立验证的任务，但必须保留失败步骤、revision 与日志引用。完整顺序、
|
||||
审批点和恢复规则见 `delivery.md`。
|
||||
|
||||
---
|
||||
|
||||
## 任务板写入约定（并发安全）
|
||||
## 项目状态写入约定（并发安全）
|
||||
|
||||
`tasks.yaml` 是持久事实源，为避免多 Agent 并发写冲突：
|
||||
`tasks.yaml` 是任务与交付运行事实源，`knowledge.yaml` 是跨任务项目知识事实源，
|
||||
`delivery.yaml` 是项目交付能力事实源。为避免多 Agent 并发写冲突：
|
||||
|
||||
- **只有 Coordinator 写 `tasks.yaml`**。Test 与 Developer 对它都是只读的。
|
||||
- **只有 Coordinator 写 `tasks.yaml` 和 `knowledge.yaml`**。Test 与 Developer
|
||||
对它们都是只读的。
|
||||
- Developer 的实现状态、Test 的复测证据都通过消息回传（`worker_done` / 复测报告），由 Coordinator 落盘。
|
||||
- Developer 和 Test 只能通过 `knowledgeCandidates` 提名知识；candidate 保存在
|
||||
当前任务证据中，在 Test 独立验证和 Coordinator gate 前不写成可派发的 active
|
||||
知识。
|
||||
- 每次写入前先读最新内容，写入后更新顶层 `updatedAt`。
|
||||
- 单次写入应是一个任务的一次状态跃迁，避免整表批量重写。
|
||||
- `delivery.yaml` 只在用户显式要求维护配置时修改；运行只写
|
||||
`tasks.yaml.deliveryRuns`，不能反向改写能力定义。
|
||||
|
||||
全项目范围的 `must`、`never` 或权限类规则还需要 User / Decision Owner 确认。
|
||||
关键约束应最终下沉为测试、lint、CI 或正式规范；知识条目保存触发条件、原因和
|
||||
证据引用，不替代可执行控制。
|
||||
|
||||
---
|
||||
|
||||
@@ -144,6 +193,8 @@ failed_retest（累计 3 轮） -> leftover
|
||||
- Developer 已提供修改文件和白盒验证证据（`worker_done`）。
|
||||
- Test 在正确 worktree 和正确服务实例上独立复测通过（对齐检查见 `closed-loop.md`），并产出可观测证据。
|
||||
- 相关单元测试、构建、集成或浏览器检查通过。
|
||||
- 当前任务显式 `knowledgeRefs` 对应的必需 `knowledgeChecks` 已由 Test 覆盖；
|
||||
未覆盖或检查引用无法解析时不能标记 `verified`。
|
||||
- **Coordinator 终检**：读 Test 的证据，确认它满足任务的原始意图与验收信号（不是重测，是审证据 + 对齐意图；避免"过了字面没过意图"）。
|
||||
- `tasks.yaml` 中记录了复测证据与 `resolution.verifiedBy`。
|
||||
- 用户可见行为符合验收标准。
|
||||
@@ -0,0 +1,11 @@
|
||||
参考项目1
|
||||
|
||||
[https://github.com/zjp1997720/zhijian-skills/tree/main/skills/codex-model-routing-team](https://github.com/zjp1997720/zhijian-skills/tree/main/skills/codex-model-routing-team)
|
||||
|
||||
参考项目2
|
||||
|
||||
[https://github.com/DannyMac180/sol-advisor](https://github.com/DannyMac180/sol-advisor)
|
||||
|
||||
参考项目3
|
||||
|
||||
[https://cursor.com/cn/blog/agent-swarm-model-economics](https://cursor.com/cn/blog/agent-swarm-model-economics)
|
||||
@@ -0,0 +1,50 @@
|
||||
"""Canonical reviewed Bug task payload shared by intake and validation."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import hashlib
|
||||
import json
|
||||
import re
|
||||
from typing import Any
|
||||
|
||||
|
||||
PAYLOAD_FIELDS = (
|
||||
"title",
|
||||
"description",
|
||||
"priority",
|
||||
"actual",
|
||||
"expected",
|
||||
"stepsToReproduce",
|
||||
"fixLogic",
|
||||
"acceptanceCriteria",
|
||||
)
|
||||
NUMBERED_ITEM = re.compile(r"(?:^|\s)([1-9][0-9]*)\.\s+")
|
||||
|
||||
|
||||
def review_items(value: str) -> list[str]:
|
||||
"""Recover line or numbered-list review text as stable non-empty items."""
|
||||
lines = [line.strip(" \t-*•") for line in value.splitlines() if line.strip()]
|
||||
if len(lines) > 1:
|
||||
return lines
|
||||
text = value.strip()
|
||||
matches = list(NUMBERED_ITEM.finditer(text))
|
||||
if matches:
|
||||
items: list[str] = []
|
||||
for index, match in enumerate(matches):
|
||||
start = match.end()
|
||||
end = matches[index + 1].start() if index + 1 < len(matches) else len(text)
|
||||
item = text[start:end].strip()
|
||||
if item:
|
||||
items.append(item)
|
||||
if items:
|
||||
return items
|
||||
return [text] if text else []
|
||||
|
||||
|
||||
def approval_payload_hash(task: dict[str, Any]) -> str:
|
||||
"""Hash the exact reviewed fields that Developer and Test consume."""
|
||||
payload = {field: task.get(field) for field in PAYLOAD_FIELDS}
|
||||
encoded = json.dumps(
|
||||
payload, ensure_ascii=False, sort_keys=True, separators=(",", ":"),
|
||||
).encode("utf-8")
|
||||
return f"sha256:{hashlib.sha256(encoded).hexdigest()}"
|
||||
@@ -0,0 +1,853 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Read and review an ACK-ready Feishu Base view through the official lark-cli.
|
||||
|
||||
The only mutation is a bounded draft write to configured Coordinator fields.
|
||||
The adapter never reads the active profile and emits one JSON document only
|
||||
on success.
|
||||
"""
|
||||
from __future__ import annotations
|
||||
|
||||
import argparse
|
||||
import hashlib
|
||||
import json
|
||||
import math
|
||||
import os
|
||||
import pwd
|
||||
import re
|
||||
import resource
|
||||
import signal
|
||||
import stat
|
||||
import subprocess
|
||||
import sys
|
||||
import tempfile
|
||||
import time
|
||||
from pathlib import Path
|
||||
from typing import Any
|
||||
|
||||
from approval_payload import approval_payload_hash, review_items
|
||||
from yaml_subset import DuplicateKeyError, YamlSubsetError, load_json_unique, load_yaml_subset, make_unique_pyyaml_loader
|
||||
|
||||
REQUIRED_FIELDS = ("title", "actual", "expected", "stepsToReproduce", "acceptance", "priority", "attachments", "updatedAt")
|
||||
OPTIONAL_FIELDS = ("fixLogic",)
|
||||
SOURCE_FACT_FIELDS = ("title", "actual", "expected", "updatedAt")
|
||||
COORDINATOR_FIELDS = ("steps", "acceptance", "priority")
|
||||
BUG_CONTENT_FIELDS = ("title", "actual", "expected", "fixLogic", *COORDINATOR_FIELDS)
|
||||
MAX_PAGES = 100
|
||||
MAX_RECORDS = 10_000
|
||||
PAGE_SIZE = 100
|
||||
MAX_CLI_STDOUT = 1024 * 1024
|
||||
MAX_CLI_STDERR = 64 * 1024
|
||||
MAX_ATTACHMENTS_PER_RECORD = 10
|
||||
MAX_TOTAL_ATTACHMENTS = 100
|
||||
MAX_ATTACHMENT_BYTES = 20 * 1024 * 1024
|
||||
MAX_TOTAL_ATTACHMENT_BYTES = 200 * 1024 * 1024
|
||||
MAX_ATTACHMENT_BATCH_SECONDS = 300
|
||||
MAX_DRAFT_BYTES = 64 * 1024
|
||||
SAFE_VALUE = re.compile(r"^[^\s\x00-\x1f]{1,256}$")
|
||||
PROFILE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$")
|
||||
RECORD_ID = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]{0,255}$")
|
||||
SOURCE_REF = re.compile(r"^feishu-base:sha256:[0-9a-f]{64}$")
|
||||
DRAFT_REVISION = re.compile(r"^sha256:[0-9a-f]{64}$")
|
||||
WORKFLOWS = {"read-only-v1", "reviewed-writeback-v1"}
|
||||
|
||||
|
||||
class IntakeError(Exception):
|
||||
pass
|
||||
|
||||
|
||||
def account_home() -> Path:
|
||||
"""Return the actual account home, never a caller-controlled HOME value."""
|
||||
try:
|
||||
home = Path(pwd.getpwuid(os.getuid()).pw_dir).resolve(strict=True)
|
||||
except (KeyError, OSError) as exc:
|
||||
raise IntakeError("cannot resolve current account home") from exc
|
||||
if not home.is_dir():
|
||||
raise IntakeError("current account home is not a directory")
|
||||
return home
|
||||
|
||||
|
||||
def trusted_lark_cli_dirs() -> list[Path]:
|
||||
"""Fixed account and system locations; intentionally never consult PATH."""
|
||||
home = account_home()
|
||||
candidates = (
|
||||
home / ".local" / "bin",
|
||||
home / ".local" / "share" / "mise" / "shims",
|
||||
home / ".cargo" / "bin",
|
||||
Path("/home/linuxbrew/.linuxbrew/bin"),
|
||||
Path("/usr/local/go/bin"),
|
||||
Path("/usr/local/bin"),
|
||||
Path("/usr/bin"),
|
||||
Path("/bin"),
|
||||
)
|
||||
result: list[Path] = []
|
||||
for candidate in candidates:
|
||||
try:
|
||||
resolved = candidate.resolve(strict=True)
|
||||
except OSError:
|
||||
continue
|
||||
if resolved.is_dir() and resolved not in result:
|
||||
result.append(resolved)
|
||||
return result
|
||||
|
||||
|
||||
def resolve_lark_cli() -> Path:
|
||||
"""Resolve a safe lark-cli from the fixed trusted locations only."""
|
||||
for directory in trusted_lark_cli_dirs():
|
||||
candidate = directory / "lark-cli"
|
||||
try:
|
||||
candidate_metadata = os.lstat(candidate)
|
||||
resolved = candidate.resolve(strict=True)
|
||||
metadata = resolved.stat()
|
||||
except OSError:
|
||||
continue
|
||||
if not (stat.S_ISREG(candidate_metadata.st_mode) or stat.S_ISLNK(candidate_metadata.st_mode)):
|
||||
continue
|
||||
if candidate_metadata.st_uid not in {0, os.getuid()}:
|
||||
continue
|
||||
if not stat.S_ISREG(metadata.st_mode) or not os.access(resolved, os.X_OK):
|
||||
continue
|
||||
if metadata.st_uid not in {0, os.getuid()} or stat.S_IMODE(metadata.st_mode) & 0o022:
|
||||
continue
|
||||
if resolved.name == "lark-cli":
|
||||
return resolved
|
||||
if not stat.S_ISLNK(candidate_metadata.st_mode):
|
||||
continue
|
||||
official_binary = official_npm_binary(resolved)
|
||||
if official_binary is not None:
|
||||
return official_binary
|
||||
raise IntakeError("lark-cli is not installed in a trusted account or system directory")
|
||||
|
||||
|
||||
def official_npm_binary(path: Path) -> Path | None:
|
||||
"""Resolve a validated npm wrapper to its downloaded native CLI binary."""
|
||||
if path.name != "run.js" or path.parent.name != "scripts":
|
||||
return None
|
||||
manifest = path.parent.parent / "package.json"
|
||||
try:
|
||||
metadata = manifest.stat()
|
||||
if not stat.S_ISREG(metadata.st_mode):
|
||||
return None
|
||||
if metadata.st_uid not in {0, os.getuid()} or stat.S_IMODE(metadata.st_mode) & 0o022:
|
||||
return None
|
||||
package = json.loads(manifest.read_text(encoding="utf-8"))
|
||||
except (OSError, UnicodeError, json.JSONDecodeError):
|
||||
return None
|
||||
if not (
|
||||
isinstance(package, dict)
|
||||
and package.get("name") == "@larksuite/cli"
|
||||
and isinstance(package.get("bin"), dict)
|
||||
and package["bin"].get("lark-cli") == "scripts/run.js"
|
||||
):
|
||||
return None
|
||||
native = path.parent.parent / "bin" / "lark-cli"
|
||||
try:
|
||||
native_lstat = os.lstat(native)
|
||||
resolved = native.resolve(strict=True)
|
||||
metadata = resolved.stat()
|
||||
except OSError:
|
||||
return None
|
||||
if not stat.S_ISREG(native_lstat.st_mode) or resolved.name != "lark-cli":
|
||||
return None
|
||||
if not stat.S_ISREG(metadata.st_mode) or not os.access(resolved, os.X_OK):
|
||||
return None
|
||||
if metadata.st_uid not in {0, os.getuid()} or stat.S_IMODE(metadata.st_mode) & 0o022:
|
||||
return None
|
||||
return resolved
|
||||
|
||||
|
||||
def cli_environment() -> dict[str, str]:
|
||||
"""Build a minimal environment so env credentials cannot override `--profile`."""
|
||||
environment = {
|
||||
"HOME": str(account_home()),
|
||||
"PATH": os.pathsep.join(str(path) for path in trusted_lark_cli_dirs()),
|
||||
}
|
||||
for name in ("LANG", "LC_ALL", "LC_CTYPE"):
|
||||
value = os.environ.get(name)
|
||||
if value and "\x00" not in value and len(value) <= 256:
|
||||
environment[name] = value
|
||||
return environment
|
||||
|
||||
|
||||
def load_board(path: Path) -> dict[str, Any]:
|
||||
try:
|
||||
text = path.read_text(encoding="utf-8")
|
||||
if path.suffix.lower() == ".json":
|
||||
value = load_json_unique(text)
|
||||
else:
|
||||
try:
|
||||
import yaml # type: ignore
|
||||
value = yaml.load(text, Loader=make_unique_pyyaml_loader(yaml))
|
||||
except ImportError:
|
||||
value = load_yaml_subset(text)
|
||||
except (OSError, json.JSONDecodeError, DuplicateKeyError, YamlSubsetError) as exc:
|
||||
raise IntakeError(f"cannot read task board: {exc}") from exc
|
||||
except Exception as exc: # PyYAML errors are intentionally not exposed verbatim.
|
||||
raise IntakeError("cannot parse task board") from exc
|
||||
if not isinstance(value, dict):
|
||||
raise IntakeError("task board must be an object")
|
||||
return value
|
||||
|
||||
|
||||
def load_draft(path: Path) -> dict[str, Any]:
|
||||
"""Load one bounded, regular JSON file with the two writable draft fields."""
|
||||
descriptor: int | None = None
|
||||
try:
|
||||
before = path.lstat()
|
||||
if not stat.S_ISREG(before.st_mode) or path.is_symlink():
|
||||
raise IntakeError("draft input must be a regular file")
|
||||
flags = os.O_RDONLY | getattr(os, "O_CLOEXEC", 0) | getattr(os, "O_NOFOLLOW", 0)
|
||||
descriptor = os.open(path, flags)
|
||||
metadata = os.fstat(descriptor)
|
||||
if (
|
||||
not stat.S_ISREG(metadata.st_mode)
|
||||
or (before.st_dev, before.st_ino) != (metadata.st_dev, metadata.st_ino)
|
||||
):
|
||||
raise IntakeError("draft input changed while opening")
|
||||
if metadata.st_size <= 0 or metadata.st_size > MAX_DRAFT_BYTES:
|
||||
raise IntakeError("draft input size is invalid")
|
||||
chunks: list[bytes] = []
|
||||
total = 0
|
||||
while total <= MAX_DRAFT_BYTES:
|
||||
chunk = os.read(descriptor, min(64 * 1024, MAX_DRAFT_BYTES + 1 - total))
|
||||
if not chunk:
|
||||
break
|
||||
chunks.append(chunk)
|
||||
total += len(chunk)
|
||||
content = b"".join(chunks)
|
||||
if len(content) != metadata.st_size:
|
||||
raise IntakeError("draft input changed while reading")
|
||||
value = load_json_unique(content.decode("utf-8"))
|
||||
except IntakeError:
|
||||
raise
|
||||
except (OSError, UnicodeError, json.JSONDecodeError, DuplicateKeyError) as exc:
|
||||
raise IntakeError("cannot read draft input") from exc
|
||||
finally:
|
||||
if descriptor is not None:
|
||||
os.close(descriptor)
|
||||
if not isinstance(value, dict) or set(value) != {"fixLogic", "acceptance"}:
|
||||
raise IntakeError("draft input must contain exactly fixLogic and acceptance")
|
||||
fix_logic = value["fixLogic"]
|
||||
acceptance = value["acceptance"]
|
||||
if not isinstance(fix_logic, str) or not fix_logic.strip():
|
||||
raise IntakeError("draft fixLogic must be a non-empty string")
|
||||
if (
|
||||
not isinstance(acceptance, list)
|
||||
or not acceptance
|
||||
or any(not isinstance(item, str) or not item.strip() for item in acceptance)
|
||||
):
|
||||
raise IntakeError("draft acceptance must be a non-empty string list")
|
||||
return {
|
||||
"fixLogic": fix_logic.strip(),
|
||||
"acceptance": [item.strip() for item in acceptance],
|
||||
}
|
||||
|
||||
|
||||
def config_from_board(board: dict[str, Any]) -> dict[str, Any]:
|
||||
project = board.get("project")
|
||||
if not isinstance(project, dict) or "bugIntake" not in project:
|
||||
raise IntakeError("project.bugIntake is not configured")
|
||||
config = project["bugIntake"]
|
||||
if not isinstance(config, dict):
|
||||
raise IntakeError("project.bugIntake must be an object")
|
||||
allowed = {"provider", "workflow", "profile", "baseToken", "tableId", "viewId", "fields"}
|
||||
unknown = sorted(set(config) - allowed)
|
||||
if unknown:
|
||||
raise IntakeError("bugIntake has unknown fields")
|
||||
if config.get("provider") != "feishu-base":
|
||||
raise IntakeError("bugIntake.provider must be feishu-base")
|
||||
workflow = config.get("workflow", "read-only-v1")
|
||||
if workflow not in WORKFLOWS:
|
||||
raise IntakeError("bugIntake.workflow is invalid")
|
||||
profile = config.get("profile")
|
||||
if not isinstance(profile, str) or not PROFILE.fullmatch(profile):
|
||||
raise IntakeError("bugIntake.profile is invalid")
|
||||
for key in ("baseToken", "tableId", "viewId"):
|
||||
value = config.get(key)
|
||||
if not isinstance(value, str) or not SAFE_VALUE.fullmatch(value):
|
||||
raise IntakeError(f"bugIntake.{key} is invalid")
|
||||
fields = config.get("fields")
|
||||
supported = set(REQUIRED_FIELDS) | set(OPTIONAL_FIELDS)
|
||||
if (
|
||||
not isinstance(fields, dict)
|
||||
or not set(REQUIRED_FIELDS).issubset(fields)
|
||||
or not set(fields).issubset(supported)
|
||||
):
|
||||
raise IntakeError("bugIntake.fields must map all required and only supported logical fields")
|
||||
if any(not isinstance(value, str) or not SAFE_VALUE.fullmatch(value) for value in fields.values()):
|
||||
raise IntakeError("bugIntake.fields values are invalid")
|
||||
if len(set(fields.values())) != len(fields):
|
||||
raise IntakeError("bugIntake.fields values must be unique")
|
||||
if workflow == "reviewed-writeback-v1" and "fixLogic" not in fields:
|
||||
raise IntakeError("reviewed writeback requires bugIntake.fields.fixLogic")
|
||||
return config
|
||||
|
||||
|
||||
def limit_child_file_size(limit: int) -> None:
|
||||
"""Bound regular-file writes by the CLI and any child spawned by its wrapper."""
|
||||
_, hard = resource.getrlimit(resource.RLIMIT_FSIZE)
|
||||
bounded = limit if hard == resource.RLIM_INFINITY else min(limit, hard)
|
||||
resource.setrlimit(resource.RLIMIT_FSIZE, (bounded, bounded))
|
||||
|
||||
|
||||
def run_cli(
|
||||
args: list[str], *, allow_profile_list: bool = False, max_file_bytes: int = 0,
|
||||
timeout: float = 60, cwd: Path | None = None,
|
||||
) -> Any:
|
||||
"""Run the official CLI and accept only explicit successful JSON shapes."""
|
||||
executable = resolve_lark_cli()
|
||||
file_limit = max(MAX_CLI_STDOUT, MAX_CLI_STDERR, max_file_bytes)
|
||||
with tempfile.TemporaryFile() as stdout_file, tempfile.TemporaryFile() as stderr_file:
|
||||
try:
|
||||
process = subprocess.Popen(
|
||||
[str(executable), *args],
|
||||
shell=False,
|
||||
stdin=subprocess.DEVNULL,
|
||||
stdout=stdout_file,
|
||||
stderr=stderr_file,
|
||||
env=cli_environment(),
|
||||
cwd=cwd,
|
||||
start_new_session=True,
|
||||
preexec_fn=lambda: limit_child_file_size(file_limit),
|
||||
)
|
||||
try:
|
||||
returncode = process.wait(timeout=timeout)
|
||||
except subprocess.TimeoutExpired as exc:
|
||||
try:
|
||||
os.killpg(process.pid, signal.SIGKILL)
|
||||
except ProcessLookupError:
|
||||
pass
|
||||
process.wait()
|
||||
raise IntakeError("lark-cli failed to execute") from exc
|
||||
except (OSError, subprocess.SubprocessError) as exc:
|
||||
raise IntakeError("lark-cli failed to execute") from exc
|
||||
stdout_size = os.fstat(stdout_file.fileno()).st_size
|
||||
stderr_size = os.fstat(stderr_file.fileno()).st_size
|
||||
if stdout_size > MAX_CLI_STDOUT or stderr_size > MAX_CLI_STDERR:
|
||||
raise IntakeError("lark-cli output exceeded the safety limit")
|
||||
if returncode:
|
||||
raise IntakeError("lark-cli command failed")
|
||||
stdout_file.seek(0)
|
||||
try:
|
||||
stdout = stdout_file.read(MAX_CLI_STDOUT + 1).decode("utf-8")
|
||||
except UnicodeDecodeError as exc:
|
||||
raise IntakeError("lark-cli returned malformed JSON") from exc
|
||||
try:
|
||||
value = json.loads(
|
||||
stdout,
|
||||
parse_constant=lambda value: (_ for _ in ()).throw(
|
||||
ValueError(f"non-finite JSON constant: {value}")
|
||||
),
|
||||
)
|
||||
except (json.JSONDecodeError, ValueError) as exc:
|
||||
raise IntakeError("lark-cli returned malformed JSON") from exc
|
||||
if isinstance(value, list):
|
||||
if allow_profile_list:
|
||||
return value
|
||||
raise IntakeError("lark-cli returned an unexpected JSON array")
|
||||
if not isinstance(value, dict):
|
||||
raise IntakeError("lark-cli returned an invalid JSON response")
|
||||
if "ok" in value and value["ok"] is not True:
|
||||
raise IntakeError("lark-cli returned an error response")
|
||||
if "code" in value and (not isinstance(value["code"], int) or isinstance(value["code"], bool) or value["code"] != 0):
|
||||
raise IntakeError("lark-cli returned an error response")
|
||||
if "ok" not in value and "code" not in value:
|
||||
raise IntakeError("lark-cli returned an ambiguous JSON response")
|
||||
return value
|
||||
|
||||
|
||||
def profile_check(config: dict[str, Any]) -> None:
|
||||
# `profile list` is the official non-mutating profile inspection command.
|
||||
value = run_cli(["profile", "list"], allow_profile_list=True)
|
||||
if isinstance(value, list):
|
||||
profiles = value
|
||||
else:
|
||||
# Compatibility wrapper: only a successful envelope with a direct list
|
||||
# is accepted. Do not loosen this into arbitrary nested objects.
|
||||
profiles = value.get("data")
|
||||
if not isinstance(profiles, list):
|
||||
raise IntakeError("profile check returned an invalid response")
|
||||
matching_profile: dict[str, Any] | None = None
|
||||
for item in profiles:
|
||||
# Match the official profile-list item shape. `user` and
|
||||
# `tokenStatus` are optional and deliberately never propagated.
|
||||
if (
|
||||
not isinstance(item, dict)
|
||||
or not isinstance(item.get("name"), str)
|
||||
or not PROFILE.fullmatch(item["name"])
|
||||
or not isinstance(item.get("appId"), str)
|
||||
or not isinstance(item.get("brand"), str)
|
||||
or not isinstance(item.get("active"), bool)
|
||||
):
|
||||
raise IntakeError("profile check returned an invalid profile entry")
|
||||
if item["name"] == config["profile"]:
|
||||
matching_profile = item
|
||||
if matching_profile is None:
|
||||
raise IntakeError("configured lark-cli profile does not exist")
|
||||
if matching_profile["brand"] != "feishu":
|
||||
raise IntakeError("configured lark-cli profile must use the feishu brand")
|
||||
|
||||
|
||||
def text(value: Any) -> str:
|
||||
if value is None:
|
||||
return ""
|
||||
if isinstance(value, str):
|
||||
return " ".join(value.split())
|
||||
if isinstance(value, float) and not math.isfinite(value):
|
||||
raise IntakeError("text field contains a non-finite number")
|
||||
if isinstance(value, (int, float, bool)):
|
||||
return str(value)
|
||||
if isinstance(value, list):
|
||||
return "\n".join(part for part in (text(item) for item in value) if part)
|
||||
if isinstance(value, dict):
|
||||
for key in ("text", "name", "value"):
|
||||
if key in value:
|
||||
return text(value[key])
|
||||
raise IntakeError("text field contains an unsupported object")
|
||||
raise IntakeError("text field contains an unsupported value")
|
||||
|
||||
|
||||
def attachment_items(value: Any) -> list[tuple[dict[str, Any], str]]:
|
||||
if value in (None, ""):
|
||||
return []
|
||||
if not isinstance(value, list):
|
||||
raise IntakeError("attachments cell must be a list")
|
||||
if len(value) > MAX_ATTACHMENTS_PER_RECORD:
|
||||
raise IntakeError("record exceeded the attachment count limit")
|
||||
attachments: list[tuple[dict[str, Any], str]] = []
|
||||
for item in value:
|
||||
if not isinstance(item, dict):
|
||||
raise IntakeError("attachment metadata must be an object")
|
||||
token = item.get("file_token", item.get("token"))
|
||||
if not isinstance(token, str) or not SAFE_VALUE.fullmatch(token):
|
||||
raise IntakeError("attachment token is invalid")
|
||||
metadata = {"name": text(item.get("name")), "type": text(item.get("type", item.get("mime_type"))), "size": item.get("size")}
|
||||
if (
|
||||
not isinstance(metadata["size"], int)
|
||||
or isinstance(metadata["size"], bool)
|
||||
or metadata["size"] < 0
|
||||
or metadata["size"] > MAX_ATTACHMENT_BYTES
|
||||
):
|
||||
raise IntakeError("attachment size is invalid")
|
||||
attachments.append((metadata, token))
|
||||
return attachments
|
||||
|
||||
|
||||
def matrix_from_response(response: dict[str, Any], field_ids: list[str]) -> tuple[list[str], list[list[Any]]]:
|
||||
data = response.get("data", response)
|
||||
if not isinstance(data, dict):
|
||||
raise IntakeError("record list data is invalid")
|
||||
fields = data.get("fields")
|
||||
ids = data.get("record_id_list", data.get("recordIds"))
|
||||
rows = data.get("data", data.get("records", data.get("items", data.get("rows"))))
|
||||
if not isinstance(fields, list) or not all(isinstance(x, str) for x in fields):
|
||||
raise IntakeError("record list fields are invalid")
|
||||
if fields != field_ids:
|
||||
raise IntakeError("record list fields do not match configured projection")
|
||||
if not isinstance(ids, list) or not all(isinstance(x, str) and RECORD_ID.fullmatch(x) for x in ids):
|
||||
raise IntakeError("record list record_id_list is invalid")
|
||||
if not isinstance(rows, list) or len(rows) != len(ids) or any(not isinstance(row, list) or len(row) != len(fields) for row in rows):
|
||||
raise IntakeError("record list matrix does not match fields and record_id_list")
|
||||
return ids, rows
|
||||
|
||||
|
||||
def fetch_pages(config: dict[str, Any]) -> list[tuple[str, list[Any]]]:
|
||||
logical_fields = [
|
||||
logical for logical in (*REQUIRED_FIELDS, *OPTIONAL_FIELDS)
|
||||
if logical in config["fields"]
|
||||
]
|
||||
field_ids = [config["fields"][logical] for logical in logical_fields]
|
||||
all_rows: list[tuple[str, list[Any]]] = []
|
||||
offset = 0
|
||||
for _ in range(MAX_PAGES):
|
||||
args = ["base", "+record-list", "--profile", config["profile"], "--base-token", config["baseToken"], "--table-id", config["tableId"], "--view-id", config["viewId"], "--format", "json", "--offset", str(offset), "--limit", str(PAGE_SIZE)]
|
||||
for field_id in field_ids:
|
||||
args.extend(["--field-id", field_id])
|
||||
response = run_cli(args)
|
||||
ids, rows = matrix_from_response(response, field_ids)
|
||||
if len(ids) > PAGE_SIZE:
|
||||
raise IntakeError("record list exceeded requested page size")
|
||||
all_rows.extend(zip(ids, rows))
|
||||
if len(all_rows) > MAX_RECORDS:
|
||||
raise IntakeError("record list exceeded record limit")
|
||||
data = response.get("data", response)
|
||||
has_more = data.get("has_more", data.get("hasMore", False))
|
||||
if not isinstance(has_more, bool):
|
||||
raise IntakeError("record list pagination marker is invalid")
|
||||
if not has_more:
|
||||
return all_rows
|
||||
if not ids:
|
||||
raise IntakeError("record list pagination made no progress")
|
||||
offset += len(ids)
|
||||
raise IntakeError("record list exceeded page limit")
|
||||
|
||||
|
||||
def download(
|
||||
config: dict[str, Any], record_id: str, file_token: str,
|
||||
output_dir: Path, expected_size: int, timeout: float,
|
||||
) -> str:
|
||||
try:
|
||||
output_dir.mkdir(parents=True, exist_ok=False)
|
||||
except OSError as exc:
|
||||
raise IntakeError("attachment output directory is unsafe") from exc
|
||||
if not output_dir.is_dir() or output_dir.is_symlink():
|
||||
raise IntakeError("attachment output directory is unsafe")
|
||||
run_cli(
|
||||
["base", "+record-download-attachment", "--profile", config["profile"], "--base-token", config["baseToken"], "--table-id", config["tableId"], "--record-id", record_id, "--file-token", file_token, "--output", output_dir.name],
|
||||
max_file_bytes=expected_size,
|
||||
timeout=timeout,
|
||||
cwd=output_dir.parent,
|
||||
)
|
||||
try:
|
||||
created = list(output_dir.iterdir())
|
||||
except OSError as exc:
|
||||
raise IntakeError("attachment download output is unreadable") from exc
|
||||
if len(created) != 1 or not created[0].is_file() or created[0].is_symlink():
|
||||
raise IntakeError("attachment download did not produce one safe file")
|
||||
root = output_dir.resolve()
|
||||
resolved = created[0].resolve()
|
||||
if root not in resolved.parents:
|
||||
raise IntakeError("attachment download escaped output directory")
|
||||
if resolved.stat().st_size != expected_size:
|
||||
raise IntakeError("attachment download size did not match metadata")
|
||||
return str(resolved)
|
||||
|
||||
|
||||
def source_ref(config: dict[str, Any], record_id: str) -> str:
|
||||
"""Return a stable opaque identity without serializing configured identifiers."""
|
||||
identity = "\x1f".join(("ack-feishu-base-source-ref-v1", config["profile"], config["baseToken"], config["tableId"], record_id))
|
||||
return f"feishu-base:sha256:{hashlib.sha256(identity.encode('utf-8')).hexdigest()}"
|
||||
|
||||
|
||||
def draft_revision(
|
||||
record: dict[str, Any], attachment_tokens: list[str] | None = None,
|
||||
) -> str:
|
||||
"""Bind approval to the normalized source facts and review-controlled fields."""
|
||||
tokens = attachment_tokens or []
|
||||
if len(tokens) != len(record["attachments"]):
|
||||
raise IntakeError("draft revision attachment identity is incomplete")
|
||||
stable = {
|
||||
"sourceRef": record["sourceRef"],
|
||||
"updatedAt": record["updatedAt"],
|
||||
"title": record["title"],
|
||||
"actual": record["actual"],
|
||||
"expected": record["expected"],
|
||||
"steps": record["steps"],
|
||||
"fixLogic": record["fixLogic"],
|
||||
"acceptance": record["acceptance"],
|
||||
"priority": record["priority"],
|
||||
"attachments": [
|
||||
{
|
||||
**{key: attachment.get(key) for key in ("name", "type", "size")},
|
||||
"tokenDigest": f"sha256:{hashlib.sha256(('ack-feishu-attachment-v1\x1f' + token).encode('utf-8')).hexdigest()}",
|
||||
}
|
||||
for attachment, token in zip(record["attachments"], tokens)
|
||||
],
|
||||
}
|
||||
encoded = json.dumps(
|
||||
stable, ensure_ascii=False, sort_keys=True, separators=(",", ":"),
|
||||
).encode("utf-8")
|
||||
return f"sha256:{hashlib.sha256(encoded).hexdigest()}"
|
||||
|
||||
|
||||
def fetch(config: dict[str, Any], output_dir: Path | None) -> dict[str, Any]:
|
||||
profile_check(config)
|
||||
prepared: list[tuple[dict[str, Any], list[tuple[dict[str, Any], str]]]] = []
|
||||
batch_warnings: list[dict[str, str]] = []
|
||||
total_attachments = 0
|
||||
total_attachment_bytes = 0
|
||||
for record_id, row in fetch_pages(config):
|
||||
logical_fields = [
|
||||
logical for logical in (*REQUIRED_FIELDS, *OPTIONAL_FIELDS)
|
||||
if logical in config["fields"]
|
||||
]
|
||||
cells = dict(zip(logical_fields, row))
|
||||
attachment_data = attachment_items(cells["attachments"])
|
||||
total_attachments += len(attachment_data)
|
||||
total_attachment_bytes += sum(metadata["size"] for metadata, _ in attachment_data)
|
||||
if total_attachments > MAX_TOTAL_ATTACHMENTS:
|
||||
raise IntakeError("batch exceeded the attachment count limit")
|
||||
if total_attachment_bytes > MAX_TOTAL_ATTACHMENT_BYTES:
|
||||
raise IntakeError("batch exceeded the attachment byte limit")
|
||||
record = {"sourceRef": source_ref(config, record_id), "recordId": record_id, "updatedAt": text(cells["updatedAt"]), "title": text(cells["title"]), "actual": text(cells["actual"]), "expected": text(cells["expected"]), "steps": text(cells["stepsToReproduce"]), "fixLogic": text(cells.get("fixLogic")), "acceptance": text(cells["acceptance"]), "priority": text(cells["priority"]), "attachments": [metadata for metadata, _ in attachment_data], "warnings": []}
|
||||
if not attachment_data and not any(record[field] for field in BUG_CONTENT_FIELDS):
|
||||
batch_warnings.append({"recordId": record_id, "code": "blank_record_skipped"})
|
||||
continue
|
||||
for field in SOURCE_FACT_FIELDS:
|
||||
if not record[field]:
|
||||
raise IntakeError(f"record {field} must not be empty")
|
||||
enrichment_fields = list(COORDINATOR_FIELDS)
|
||||
if "fixLogic" in config["fields"]:
|
||||
enrichment_fields.append("fixLogic")
|
||||
record["enrichmentRequired"] = [
|
||||
field for field in enrichment_fields if not record[field]
|
||||
]
|
||||
record["draftRevision"] = draft_revision(
|
||||
record, [token for _, token in attachment_data],
|
||||
)
|
||||
prepared.append((record, attachment_data))
|
||||
download_root: Path | None = None
|
||||
if output_dir is not None:
|
||||
try:
|
||||
output_dir.mkdir(parents=True, exist_ok=True)
|
||||
if not output_dir.is_dir() or output_dir.is_symlink():
|
||||
raise OSError("unsafe output directory")
|
||||
download_root = output_dir.resolve(strict=True)
|
||||
except OSError as exc:
|
||||
raise IntakeError("attachment output directory is unsafe") from exc
|
||||
records = []
|
||||
attachment_deadline = time.monotonic() + MAX_ATTACHMENT_BATCH_SECONDS
|
||||
for record, attachment_data in prepared:
|
||||
if download_root is not None:
|
||||
for index, (attachment, file_token) in enumerate(attachment_data, start=1):
|
||||
remaining = attachment_deadline - time.monotonic()
|
||||
if remaining <= 0:
|
||||
raise IntakeError("attachment batch exceeded the time limit")
|
||||
attachment_dir = download_root / record["recordId"] / f"attachment-{index:02d}"
|
||||
attachment["localPath"] = download(
|
||||
config, record["recordId"], file_token, attachment_dir,
|
||||
attachment["size"], min(60, remaining),
|
||||
)
|
||||
records.append(record)
|
||||
return {"provider": "feishu-base", "workflow": config.get("workflow", "read-only-v1"), "profile": config["profile"], "tableId": config["tableId"], "viewId": config["viewId"], "records": records, "warnings": batch_warnings}
|
||||
|
||||
|
||||
def review_record(
|
||||
config: dict[str, Any], record_id: str, expected_source_ref: str,
|
||||
expected_revision: str,
|
||||
) -> dict[str, Any]:
|
||||
"""Resolve one record inside the configured view and bind its reviewed version."""
|
||||
if RECORD_ID.fullmatch(record_id) is None:
|
||||
raise IntakeError("review record id is invalid")
|
||||
if SOURCE_REF.fullmatch(expected_source_ref) is None:
|
||||
raise IntakeError("expected source reference is invalid")
|
||||
if DRAFT_REVISION.fullmatch(expected_revision) is None:
|
||||
raise IntakeError("expected draft revision is invalid")
|
||||
matching = [
|
||||
record for record in fetch(config, None)["records"]
|
||||
if record["recordId"] == record_id
|
||||
]
|
||||
if len(matching) != 1:
|
||||
raise IntakeError("configured review view did not contain exactly one record")
|
||||
if (
|
||||
matching[0]["sourceRef"] != expected_source_ref
|
||||
or matching[0]["draftRevision"] != expected_revision
|
||||
):
|
||||
raise IntakeError("review record changed before the requested operation")
|
||||
return matching[0]
|
||||
|
||||
|
||||
def write_draft(
|
||||
config: dict[str, Any], record_id: str, expected_source_ref: str,
|
||||
expected_revision: str, draft_path: Path,
|
||||
) -> dict[str, Any]:
|
||||
"""Overwrite only the configured fix logic and acceptance cells."""
|
||||
if config.get("workflow", "read-only-v1") != "reviewed-writeback-v1":
|
||||
raise IntakeError("draft writeback requires reviewed-writeback-v1 workflow")
|
||||
if "fixLogic" not in config["fields"]:
|
||||
raise IntakeError("bugIntake.fields.fixLogic is required for draft writeback")
|
||||
review_record(config, record_id, expected_source_ref, expected_revision)
|
||||
draft = load_draft(draft_path)
|
||||
patch = {
|
||||
config["fields"]["fixLogic"]: draft["fixLogic"],
|
||||
config["fields"]["acceptance"]: "\n".join(
|
||||
f"{index}. {item}" for index, item in enumerate(draft["acceptance"], start=1)
|
||||
),
|
||||
}
|
||||
profile_check(config)
|
||||
run_cli([
|
||||
"base", "+record-upsert", "--profile", config["profile"],
|
||||
"--base-token", config["baseToken"], "--table-id", config["tableId"],
|
||||
"--record-id", record_id, "--json",
|
||||
json.dumps(patch, ensure_ascii=False, separators=(",", ":")),
|
||||
"--format", "json",
|
||||
])
|
||||
matching = [record for record in fetch(config, None)["records"] if record["recordId"] == record_id]
|
||||
if len(matching) != 1 or matching[0]["sourceRef"] != expected_source_ref:
|
||||
raise IntakeError("draft writeback readback did not find exactly one record")
|
||||
expected_acceptance = text(patch[config["fields"]["acceptance"]])
|
||||
if (
|
||||
matching[0]["fixLogic"] != text(draft["fixLogic"])
|
||||
or matching[0]["acceptance"] != expected_acceptance
|
||||
):
|
||||
raise IntakeError("draft writeback readback did not match the submitted draft")
|
||||
return {
|
||||
"provider": "feishu-base",
|
||||
"recordId": record_id,
|
||||
"written": ["fixLogic", "acceptance"],
|
||||
"draftRevision": matching[0]["draftRevision"],
|
||||
"ok": True,
|
||||
}
|
||||
|
||||
|
||||
def import_approved(
|
||||
config: dict[str, Any], record_id: str, expected_source_ref: str,
|
||||
expected_revision: str,
|
||||
) -> dict[str, Any]:
|
||||
"""Emit the canonical task payload for one explicitly approved draft revision."""
|
||||
if config.get("workflow", "read-only-v1") != "reviewed-writeback-v1":
|
||||
raise IntakeError("approved import requires reviewed-writeback-v1 workflow")
|
||||
record = review_record(
|
||||
config, record_id, expected_source_ref, expected_revision,
|
||||
)
|
||||
steps = review_items(record["steps"])
|
||||
acceptance = review_items(record["acceptance"])
|
||||
if not record["priority"] or not steps or not record["fixLogic"] or not acceptance:
|
||||
raise IntakeError("approved record is missing prepared review fields")
|
||||
task_draft: dict[str, Any] = {
|
||||
"title": record["title"],
|
||||
"priority": record["priority"],
|
||||
"description": record["title"],
|
||||
"actual": record["actual"],
|
||||
"expected": record["expected"],
|
||||
"stepsToReproduce": steps,
|
||||
"fixLogic": record["fixLogic"],
|
||||
"acceptanceCriteria": acceptance,
|
||||
"source": {
|
||||
"kind": "feishu-base",
|
||||
"workflow": "reviewed-writeback-v1",
|
||||
"ref": record["sourceRef"],
|
||||
"recordId": record["recordId"],
|
||||
"updatedAt": record["updatedAt"],
|
||||
"approvedRevision": record["draftRevision"],
|
||||
},
|
||||
}
|
||||
task_draft["source"]["approvedPayloadHash"] = approval_payload_hash(task_draft)
|
||||
return {
|
||||
"provider": "feishu-base",
|
||||
"recordId": record_id,
|
||||
"draftRevision": record["draftRevision"],
|
||||
"taskDraft": task_draft,
|
||||
"ok": True,
|
||||
}
|
||||
|
||||
|
||||
def plan_actions(board: dict[str, Any], records: list[dict[str, Any]]) -> list[dict[str, Any]]:
|
||||
"""Plan idempotent Coordinator actions without mutating the task board."""
|
||||
tasks = board.get("tasks")
|
||||
if not isinstance(tasks, list):
|
||||
raise IntakeError("task board tasks must be a list")
|
||||
existing: dict[str, dict[str, Any]] = {}
|
||||
for task in tasks:
|
||||
if not isinstance(task, dict):
|
||||
continue
|
||||
source = task.get("source")
|
||||
if not isinstance(source, dict) or source.get("kind") != "feishu-base":
|
||||
continue
|
||||
ref = source.get("ref")
|
||||
task_id = task.get("id")
|
||||
status = task.get("status")
|
||||
updated_at = source.get("updatedAt")
|
||||
if (
|
||||
not isinstance(ref, str) or SOURCE_REF.fullmatch(ref) is None
|
||||
or not isinstance(task_id, str) or not task_id
|
||||
or not isinstance(status, str) or not status
|
||||
or not isinstance(updated_at, str) or not updated_at
|
||||
):
|
||||
raise IntakeError("existing Feishu task source is invalid")
|
||||
if ref in existing:
|
||||
raise IntakeError("task board contains duplicate Feishu source references")
|
||||
existing[ref] = task
|
||||
|
||||
actions: list[dict[str, Any]] = []
|
||||
seen_records: set[str] = set()
|
||||
for record in records:
|
||||
ref = record.get("sourceRef")
|
||||
record_id = record.get("recordId")
|
||||
updated_at = record.get("updatedAt")
|
||||
revision = record.get("draftRevision")
|
||||
if (
|
||||
not isinstance(ref, str) or SOURCE_REF.fullmatch(ref) is None
|
||||
or not isinstance(record_id, str) or RECORD_ID.fullmatch(record_id) is None
|
||||
or not isinstance(updated_at, str) or not updated_at
|
||||
or not isinstance(revision, str) or DRAFT_REVISION.fullmatch(revision) is None
|
||||
):
|
||||
raise IntakeError("normalized Feishu record identity is invalid")
|
||||
if ref in seen_records:
|
||||
raise IntakeError("fetched records contain a duplicate source reference")
|
||||
seen_records.add(ref)
|
||||
task = existing.get(ref)
|
||||
if task is None:
|
||||
planned_action: dict[str, Any] = {"sourceRef": ref, "recordId": record_id, "draftRevision": record["draftRevision"], "action": "create"}
|
||||
enrichment_required = record.get("enrichmentRequired")
|
||||
if enrichment_required:
|
||||
planned_action["enrichmentRequired"] = enrichment_required
|
||||
actions.append(planned_action)
|
||||
continue
|
||||
source = task["source"]
|
||||
approved_revision = source.get("approvedRevision")
|
||||
if isinstance(approved_revision, str):
|
||||
if approved_revision == revision:
|
||||
action_name = "unchanged"
|
||||
elif task["status"] == "open":
|
||||
action_name = "refresh"
|
||||
else:
|
||||
action_name = "drift"
|
||||
elif source["updatedAt"] == updated_at:
|
||||
action_name = "unchanged"
|
||||
elif task["status"] == "open":
|
||||
action_name = "refresh"
|
||||
else:
|
||||
action_name = "drift"
|
||||
planned_action = {
|
||||
"sourceRef": ref,
|
||||
"recordId": record_id,
|
||||
"draftRevision": record["draftRevision"],
|
||||
"taskId": task["id"],
|
||||
"status": task["status"],
|
||||
"action": action_name,
|
||||
}
|
||||
enrichment_required = record.get("enrichmentRequired")
|
||||
if enrichment_required and action_name == "refresh":
|
||||
planned_action["enrichmentRequired"] = enrichment_required
|
||||
actions.append(planned_action)
|
||||
return actions
|
||||
|
||||
|
||||
def main(argv: list[str] | None = None) -> int:
|
||||
parser = argparse.ArgumentParser(description="Read and review a configured Feishu Base bug intake")
|
||||
sub = parser.add_subparsers(dest="command", required=True)
|
||||
for name in ("check", "fetch", "plan", "write-draft", "import-approved"):
|
||||
command = sub.add_parser(name)
|
||||
command.add_argument("tasks", type=Path, help="ACK tasks.yaml or JSON board")
|
||||
if name in {"fetch", "plan"}:
|
||||
command.add_argument("--output-dir", type=Path, help="explicit directory for downloaded attachments")
|
||||
if name in {"write-draft", "import-approved"}:
|
||||
command.add_argument("--record-id", required=True, help="existing Feishu Base record id")
|
||||
command.add_argument("--expected-source-ref", required=True, help="sourceRef returned by fetch")
|
||||
command.add_argument("--expected-draft-revision", required=True, help="draftRevision returned by fetch")
|
||||
if name == "write-draft":
|
||||
command.add_argument("--input", type=Path, required=True, help="bounded JSON draft file")
|
||||
args = parser.parse_args(argv)
|
||||
try:
|
||||
board = load_board(args.tasks)
|
||||
config = config_from_board(board)
|
||||
if args.command == "check":
|
||||
profile_check(config)
|
||||
output = {"provider": "feishu-base", "workflow": config.get("workflow", "read-only-v1"), "profile": config["profile"], "ok": True}
|
||||
elif args.command == "fetch":
|
||||
output = fetch(config, args.output_dir)
|
||||
elif args.command == "plan":
|
||||
output = fetch(config, args.output_dir)
|
||||
output["actions"] = plan_actions(board, output["records"])
|
||||
elif args.command == "write-draft":
|
||||
output = write_draft(
|
||||
config, args.record_id, args.expected_source_ref,
|
||||
args.expected_draft_revision, args.input,
|
||||
)
|
||||
else:
|
||||
output = import_approved(
|
||||
config, args.record_id, args.expected_source_ref,
|
||||
args.expected_draft_revision,
|
||||
)
|
||||
except IntakeError as exc:
|
||||
sys.stderr.write(f"Feishu bug intake failed: {exc}\n")
|
||||
return 1
|
||||
except (OSError, subprocess.SubprocessError):
|
||||
sys.stderr.write("Feishu bug intake failed: local I/O failed\n")
|
||||
return 1
|
||||
print(json.dumps(output, ensure_ascii=False, separators=(",", ":")))
|
||||
return 0
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
raise SystemExit(main())
|
||||
Executable
+1636
File diff suppressed because it is too large
Load Diff
Executable
+430
@@ -0,0 +1,430 @@
|
||||
#!/usr/bin/env python3
|
||||
"""安全执行 knowledge.yaml 中已审查的 verificationRegistry 条目。
|
||||
|
||||
本入口只接受 registry ID，不接受额外命令或参数。执行前只打开一次项目根目录
|
||||
fd，知识库、检查目标和子进程 cwd 都固定到该 fd；检查文件逐段以 O_NOFOLLOW
|
||||
打开后复制到匿名、尽可能 sealed 的稳定快照，再使用结构化 argv 和 shell=False
|
||||
启动，避免检查与执行之间被替换。
|
||||
|
||||
退出码: 0..125 沿用检查结果 / 1 知识或执行失败 / 2 环境、路径或用法错误。
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import argparse
|
||||
import fcntl
|
||||
import os
|
||||
import stat
|
||||
import subprocess
|
||||
import sys
|
||||
import tempfile
|
||||
from pathlib import Path, PurePosixPath
|
||||
from typing import Any
|
||||
|
||||
from validate_knowledge import ( # type: ignore
|
||||
infer_project_root,
|
||||
load_yaml_text,
|
||||
validate_all,
|
||||
)
|
||||
|
||||
MAX_KNOWLEDGE_BYTES = 16 * 1024 * 1024
|
||||
MAX_TARGET_BYTES = 16 * 1024 * 1024
|
||||
|
||||
|
||||
def _project_root(
|
||||
value: str | None,
|
||||
knowledge_path: Path,
|
||||
) -> tuple[Path | None, str | None]:
|
||||
inferred = infer_project_root(knowledge_path)
|
||||
if value is not None:
|
||||
candidate = Path(value).expanduser()
|
||||
if not candidate.is_dir():
|
||||
return None, f"项目根目录不存在: {candidate}"
|
||||
resolved = candidate.resolve(strict=True)
|
||||
if inferred is not None and resolved != inferred:
|
||||
return (
|
||||
None,
|
||||
f"--project-root {resolved} 与 knowledge.yaml 推断的项目根目录 "
|
||||
f"{inferred} 不一致",
|
||||
)
|
||||
return resolved, None
|
||||
if inferred is None:
|
||||
return None, "无法从 knowledge.yaml 确定现有项目根目录"
|
||||
return inferred, None
|
||||
|
||||
|
||||
def _validate_knowledge_location(
|
||||
knowledge_path: Path,
|
||||
project_root: Path,
|
||||
) -> str | None:
|
||||
expected = project_root / "docs" / "ack" / "knowledge.yaml"
|
||||
lexical = Path(os.path.abspath(knowledge_path.expanduser()))
|
||||
if lexical != expected:
|
||||
return (
|
||||
"只允许执行项目权威知识库 "
|
||||
f"{expected}，当前输入为 {lexical}"
|
||||
)
|
||||
return None
|
||||
|
||||
|
||||
def _open_regular_beneath(
|
||||
project_root: Path | int,
|
||||
relative_path: str,
|
||||
*,
|
||||
require_executable: bool,
|
||||
) -> tuple[int | None, str | None]:
|
||||
"""从根目录 fd 逐段打开目标，不允许任一段通过 symlink 跳转。"""
|
||||
if not hasattr(os, "O_NOFOLLOW") or not hasattr(os, "O_DIRECTORY"):
|
||||
return None, "当前平台不支持安全的 O_NOFOLLOW/O_DIRECTORY 路径解析"
|
||||
parts = PurePosixPath(relative_path).parts
|
||||
if (
|
||||
not parts
|
||||
or PurePosixPath(relative_path).is_absolute()
|
||||
or any(part in {"", ".", ".."} for part in parts)
|
||||
):
|
||||
return None, "检查目标必须是规范的项目内相对路径"
|
||||
|
||||
directory_fds: list[int] = []
|
||||
target_fd: int | None = None
|
||||
try:
|
||||
root_fd = (
|
||||
os.dup(project_root)
|
||||
if isinstance(project_root, int)
|
||||
else os.open(
|
||||
project_root,
|
||||
os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW,
|
||||
)
|
||||
)
|
||||
directory_fds.append(root_fd)
|
||||
current_fd = root_fd
|
||||
for segment in parts[:-1]:
|
||||
current_fd = os.open(
|
||||
segment,
|
||||
os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW,
|
||||
dir_fd=current_fd,
|
||||
)
|
||||
directory_fds.append(current_fd)
|
||||
target_fd = os.open(
|
||||
parts[-1],
|
||||
os.O_RDONLY | os.O_NOFOLLOW,
|
||||
dir_fd=current_fd,
|
||||
)
|
||||
metadata = os.fstat(target_fd)
|
||||
if not stat.S_ISREG(metadata.st_mode):
|
||||
os.close(target_fd)
|
||||
return None, "检查目标不是普通文件"
|
||||
if require_executable and metadata.st_mode & 0o111 == 0:
|
||||
os.close(target_fd)
|
||||
return None, "检查目标不可执行"
|
||||
return target_fd, None
|
||||
except OSError as exc:
|
||||
if target_fd is not None:
|
||||
os.close(target_fd)
|
||||
return None, f"检查目标不存在、不可访问或路径包含软链接: {exc}"
|
||||
finally:
|
||||
for directory_fd in reversed(directory_fds):
|
||||
os.close(directory_fd)
|
||||
|
||||
|
||||
def _stable_metadata(before: os.stat_result, after: os.stat_result) -> bool:
|
||||
fields = (
|
||||
"st_dev",
|
||||
"st_ino",
|
||||
"st_mode",
|
||||
"st_size",
|
||||
"st_mtime_ns",
|
||||
"st_ctime_ns",
|
||||
)
|
||||
return all(getattr(before, field) == getattr(after, field) for field in fields)
|
||||
|
||||
|
||||
def _read_stable_bytes(
|
||||
source_fd: int,
|
||||
*,
|
||||
maximum: int,
|
||||
) -> tuple[bytes | None, str | None]:
|
||||
before = os.fstat(source_fd)
|
||||
if before.st_size > maximum:
|
||||
return None, f"知识库超过大小上限 {maximum} bytes"
|
||||
chunks: list[bytes] = []
|
||||
total = 0
|
||||
try:
|
||||
os.lseek(source_fd, 0, os.SEEK_SET)
|
||||
while True:
|
||||
chunk = os.read(source_fd, min(1024 * 1024, maximum - total + 1))
|
||||
if not chunk:
|
||||
break
|
||||
chunks.append(chunk)
|
||||
total += len(chunk)
|
||||
if total > maximum:
|
||||
return None, f"知识库超过大小上限 {maximum} bytes"
|
||||
except OSError as exc:
|
||||
return None, f"无法读取权威知识库快照: {exc}"
|
||||
after = os.fstat(source_fd)
|
||||
if not _stable_metadata(before, after):
|
||||
return None, "权威知识库在读取期间发生变化，拒绝执行"
|
||||
return b"".join(chunks), None
|
||||
|
||||
|
||||
def load_authoritative_knowledge(
|
||||
project_root: Path | int,
|
||||
) -> tuple[dict[str, Any] | None, str | None]:
|
||||
source_fd, open_error = _open_regular_beneath(
|
||||
project_root,
|
||||
"docs/ack/knowledge.yaml",
|
||||
require_executable=False,
|
||||
)
|
||||
if open_error is not None or source_fd is None:
|
||||
return None, open_error or "无法安全打开权威知识库"
|
||||
try:
|
||||
content, read_error = _read_stable_bytes(
|
||||
source_fd,
|
||||
maximum=MAX_KNOWLEDGE_BYTES,
|
||||
)
|
||||
finally:
|
||||
os.close(source_fd)
|
||||
if read_error is not None or content is None:
|
||||
return None, read_error or "无法读取权威知识库"
|
||||
try:
|
||||
text = content.decode("utf-8")
|
||||
except UnicodeDecodeError as exc:
|
||||
return None, f"权威知识库不是有效 UTF-8: {exc}"
|
||||
return load_yaml_text(text, "知识库"), None
|
||||
|
||||
|
||||
def _write_all(file_descriptor: int, chunk: bytes) -> None:
|
||||
remaining = memoryview(chunk)
|
||||
while remaining:
|
||||
written = os.write(file_descriptor, remaining)
|
||||
if written <= 0:
|
||||
raise OSError("无法写入检查快照")
|
||||
remaining = remaining[written:]
|
||||
|
||||
|
||||
def _snapshot_executable(source_fd: int) -> tuple[int | None, str | None]:
|
||||
"""复制到匿名快照；Linux 上进一步 seal，冻结本次执行内容。"""
|
||||
before = os.fstat(source_fd)
|
||||
if before.st_size > MAX_TARGET_BYTES:
|
||||
return None, f"检查目标超过大小上限 {MAX_TARGET_BYTES} bytes"
|
||||
snapshot_fd: int | None = None
|
||||
seal_snapshot = all(
|
||||
hasattr(owner, name)
|
||||
for owner, name in (
|
||||
(os, "memfd_create"),
|
||||
(os, "MFD_ALLOW_SEALING"),
|
||||
(os, "MFD_CLOEXEC"),
|
||||
(fcntl, "F_ADD_SEALS"),
|
||||
(fcntl, "F_SEAL_SEAL"),
|
||||
(fcntl, "F_SEAL_SHRINK"),
|
||||
(fcntl, "F_SEAL_GROW"),
|
||||
(fcntl, "F_SEAL_WRITE"),
|
||||
)
|
||||
)
|
||||
try:
|
||||
if seal_snapshot:
|
||||
snapshot_fd = os.memfd_create( # type: ignore[attr-defined]
|
||||
"ack-verification",
|
||||
os.MFD_CLOEXEC | os.MFD_ALLOW_SEALING, # type: ignore[attr-defined]
|
||||
)
|
||||
else:
|
||||
snapshot_fd, snapshot_path = tempfile.mkstemp(
|
||||
prefix="ack-verification-"
|
||||
)
|
||||
os.unlink(snapshot_path)
|
||||
|
||||
os.lseek(source_fd, 0, os.SEEK_SET)
|
||||
total = 0
|
||||
while True:
|
||||
chunk = os.read(
|
||||
source_fd,
|
||||
min(1024 * 1024, MAX_TARGET_BYTES - total + 1),
|
||||
)
|
||||
if not chunk:
|
||||
break
|
||||
_write_all(snapshot_fd, chunk)
|
||||
total += len(chunk)
|
||||
if total > MAX_TARGET_BYTES:
|
||||
os.close(snapshot_fd)
|
||||
return None, f"检查目标超过大小上限 {MAX_TARGET_BYTES} bytes"
|
||||
after = os.fstat(source_fd)
|
||||
if not _stable_metadata(before, after):
|
||||
os.close(snapshot_fd)
|
||||
return None, "检查目标在创建执行快照期间发生变化，拒绝执行"
|
||||
|
||||
os.fchmod(snapshot_fd, before.st_mode & 0o777)
|
||||
os.lseek(snapshot_fd, 0, os.SEEK_SET)
|
||||
if seal_snapshot:
|
||||
seals = (
|
||||
fcntl.F_SEAL_SEAL
|
||||
| fcntl.F_SEAL_SHRINK
|
||||
| fcntl.F_SEAL_GROW
|
||||
| fcntl.F_SEAL_WRITE
|
||||
)
|
||||
fcntl.fcntl(snapshot_fd, fcntl.F_ADD_SEALS, seals)
|
||||
return snapshot_fd, None
|
||||
except OSError as exc:
|
||||
if snapshot_fd is not None:
|
||||
os.close(snapshot_fd)
|
||||
return None, f"无法创建稳定的检查执行快照: {exc}"
|
||||
|
||||
|
||||
def open_target(
|
||||
data: dict[str, Any],
|
||||
verification_ref: str,
|
||||
project_root: Path | int,
|
||||
) -> tuple[int | None, list[str] | None, str | None]:
|
||||
registry = data.get("verificationRegistry")
|
||||
if not isinstance(registry, dict) or verification_ref not in registry:
|
||||
return None, None, f"verification.ref {verification_ref!r} 未在 registry 注册"
|
||||
target = registry.get(verification_ref)
|
||||
if not isinstance(target, dict):
|
||||
return None, None, f"verificationRegistry.{verification_ref} 不是对象"
|
||||
relative_path = target.get("path")
|
||||
args = target.get("args")
|
||||
if not isinstance(relative_path, str) or not isinstance(args, list):
|
||||
return None, None, f"verificationRegistry.{verification_ref} 结构无效"
|
||||
if any(not isinstance(arg, str) for arg in args):
|
||||
return (
|
||||
None,
|
||||
None,
|
||||
f"verificationRegistry.{verification_ref}.args 必须是字符串数组",
|
||||
)
|
||||
source_fd, error = _open_regular_beneath(
|
||||
project_root,
|
||||
relative_path,
|
||||
require_executable=True,
|
||||
)
|
||||
if error is not None or source_fd is None:
|
||||
return None, None, error or "无法安全打开检查目标"
|
||||
try:
|
||||
target_fd, snapshot_error = _snapshot_executable(source_fd)
|
||||
finally:
|
||||
os.close(source_fd)
|
||||
if snapshot_error is not None or target_fd is None:
|
||||
return None, None, snapshot_error or "无法创建检查执行快照"
|
||||
return target_fd, args, None
|
||||
|
||||
|
||||
def _fd_executable_path(target_fd: int) -> str | None:
|
||||
for prefix in ("/proc/self/fd", "/dev/fd"):
|
||||
candidate = f"{prefix}/{target_fd}"
|
||||
if Path(candidate).exists():
|
||||
return candidate
|
||||
return None
|
||||
|
||||
|
||||
def _fd_directory_path(directory_fd: int) -> str | None:
|
||||
for prefix in ("/proc/self/fd", "/dev/fd"):
|
||||
candidate = f"{prefix}/{directory_fd}"
|
||||
if Path(candidate).is_dir():
|
||||
return candidate
|
||||
return None
|
||||
|
||||
|
||||
def main(argv: list[str] | None = None) -> int:
|
||||
parser = argparse.ArgumentParser(
|
||||
description="执行 ACK verificationRegistry 中已审查的检查"
|
||||
)
|
||||
parser.add_argument("knowledge", help="knowledge.yaml 路径")
|
||||
parser.add_argument("verification_ref", help="verificationRegistry 中的检查 ID")
|
||||
parser.add_argument(
|
||||
"--project-root",
|
||||
help="项目根目录；默认从 knowledge.yaml 的 docs/ack 布局或 Git 推断",
|
||||
)
|
||||
args = parser.parse_args(argv)
|
||||
|
||||
knowledge_path = Path(args.knowledge)
|
||||
project_root, root_error = _project_root(args.project_root, knowledge_path)
|
||||
if project_root is None:
|
||||
sys.stderr.write(f"{root_error or '无法确定现有项目根目录'}\n")
|
||||
return 2
|
||||
location_error = _validate_knowledge_location(knowledge_path, project_root)
|
||||
if location_error is not None:
|
||||
sys.stderr.write(f"{location_error}\n")
|
||||
return 2
|
||||
|
||||
try:
|
||||
project_root_fd = os.open(
|
||||
project_root,
|
||||
os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW,
|
||||
)
|
||||
except OSError as exc:
|
||||
sys.stderr.write(f"无法安全打开项目根目录: {exc}\n")
|
||||
return 2
|
||||
|
||||
try:
|
||||
stable_root_path = _fd_directory_path(project_root_fd)
|
||||
if stable_root_path is None:
|
||||
sys.stderr.write("当前平台无法固定项目根目录文件描述符\n")
|
||||
return 2
|
||||
data, knowledge_error = load_authoritative_knowledge(project_root_fd)
|
||||
if knowledge_error is not None or data is None:
|
||||
sys.stderr.write(f"{knowledge_error or '无法读取权威知识库'}\n")
|
||||
return 2
|
||||
schema_path = (
|
||||
Path(__file__).resolve().parent.parent
|
||||
/ "templates"
|
||||
/ "knowledge.schema.json"
|
||||
)
|
||||
errors, mode = validate_all(
|
||||
data,
|
||||
schema_path,
|
||||
project_root=Path(stable_root_path),
|
||||
)
|
||||
if errors:
|
||||
sys.stderr.write(f"知识库校验失败（{mode}），拒绝执行：\n")
|
||||
for error in errors:
|
||||
sys.stderr.write(f" - {error}\n")
|
||||
return 1
|
||||
|
||||
target_fd, target_args, error = open_target(
|
||||
data,
|
||||
args.verification_ref,
|
||||
project_root_fd,
|
||||
)
|
||||
if error is not None or target_fd is None or target_args is None:
|
||||
sys.stderr.write(f"{error or '无法解析检查目标'}\n")
|
||||
return 2
|
||||
|
||||
try:
|
||||
executable_path = _fd_executable_path(target_fd)
|
||||
if executable_path is None:
|
||||
sys.stderr.write(
|
||||
"当前平台无法从已打开的文件描述符安全执行检查\n"
|
||||
)
|
||||
return 2
|
||||
environment = os.environ.copy()
|
||||
environment["ACK_PROJECT_ROOT"] = stable_root_path
|
||||
environment["ACK_PROJECT_ROOT_DISPLAY"] = str(project_root)
|
||||
environment["ACK_VERIFICATION_REF"] = args.verification_ref
|
||||
registry = data.get("verificationRegistry")
|
||||
target = (
|
||||
registry.get(args.verification_ref)
|
||||
if isinstance(registry, dict)
|
||||
else None
|
||||
)
|
||||
if isinstance(target, dict) and isinstance(target.get("path"), str):
|
||||
environment["ACK_VERIFICATION_PATH"] = target["path"]
|
||||
try:
|
||||
completed = subprocess.run(
|
||||
[executable_path, *target_args],
|
||||
cwd=stable_root_path,
|
||||
env=environment,
|
||||
shell=False,
|
||||
check=False,
|
||||
pass_fds=(project_root_fd, target_fd),
|
||||
)
|
||||
except OSError as exc:
|
||||
sys.stderr.write(f"检查启动失败: {exc}\n")
|
||||
return 1
|
||||
finally:
|
||||
os.close(target_fd)
|
||||
finally:
|
||||
os.close(project_root_fd)
|
||||
if 0 <= completed.returncode <= 125:
|
||||
return completed.returncode
|
||||
return 1
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
raise SystemExit(main())
|
||||
Executable
+275
@@ -0,0 +1,275 @@
|
||||
#!/usr/bin/env python3
|
||||
"""按显式项目上下文确定性选择 active ACK 知识。
|
||||
|
||||
匹配采用大小写敏感 glob；entry 中每个非空 scope 维度都必须被查询上下文命中。
|
||||
scope.all=true 的条目始终命中并优先占用 --limit，数量超过预算时显式失败。其余
|
||||
结果按作用域具体程度及稳定引用排序。本脚本只输出数据，绝不执行 knowledge.yaml
|
||||
中的任何文本。
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import argparse
|
||||
import fnmatch
|
||||
import json
|
||||
import sys
|
||||
from functools import lru_cache
|
||||
from pathlib import Path
|
||||
from typing import Any
|
||||
|
||||
from validate_knowledge import ( # type: ignore
|
||||
SCOPE_FIELDS,
|
||||
infer_project_root,
|
||||
load_yaml,
|
||||
stable_ref,
|
||||
validate_builtin_structure,
|
||||
validate_semantics,
|
||||
)
|
||||
|
||||
DEFAULT_LIMIT = 10
|
||||
MAX_LIMIT = 100
|
||||
|
||||
|
||||
def _path_glob_matches(value: str, pattern: str) -> bool:
|
||||
"""路径 glob：* 只匹配单段，只有完整的 ** 段可以跨越 /。"""
|
||||
value_parts = tuple(value.split("/"))
|
||||
pattern_parts = tuple(pattern.split("/"))
|
||||
|
||||
@lru_cache(maxsize=None)
|
||||
def match(pattern_index: int, value_index: int) -> bool:
|
||||
if pattern_index == len(pattern_parts):
|
||||
return value_index == len(value_parts)
|
||||
pattern_part = pattern_parts[pattern_index]
|
||||
if pattern_part == "**":
|
||||
return match(pattern_index + 1, value_index) or (
|
||||
value_index < len(value_parts)
|
||||
and match(pattern_index, value_index + 1)
|
||||
)
|
||||
return (
|
||||
value_index < len(value_parts)
|
||||
and fnmatch.fnmatchcase(value_parts[value_index], pattern_part)
|
||||
and match(pattern_index + 1, value_index + 1)
|
||||
)
|
||||
|
||||
return match(0, 0)
|
||||
|
||||
|
||||
def scope_matches(
|
||||
scope: dict[str, Any], context: dict[str, list[str]]
|
||||
) -> bool:
|
||||
if scope.get("all") is True:
|
||||
return True
|
||||
constrained = False
|
||||
for field in SCOPE_FIELDS:
|
||||
patterns = scope.get(field)
|
||||
if not isinstance(patterns, list) or not patterns:
|
||||
continue
|
||||
constrained = True
|
||||
values = context.get(field, [])
|
||||
matcher = _path_glob_matches if field == "paths" else fnmatch.fnmatchcase
|
||||
if not values or not any(
|
||||
matcher(value, pattern)
|
||||
for pattern in patterns
|
||||
if isinstance(pattern, str)
|
||||
for value in values
|
||||
):
|
||||
return False
|
||||
return constrained
|
||||
|
||||
|
||||
def _pattern_specificity(pattern: str) -> tuple[int, int, int, int, int]:
|
||||
wildcard_count = sum(pattern.count(char) for char in ("*", "?", "["))
|
||||
double_star_count = sum(1 for part in pattern.split("/") if part == "**")
|
||||
literal_count = sum(char not in "*?[]!" for char in pattern)
|
||||
exact = int(wildcard_count == 0)
|
||||
depth = len(pattern.split("/"))
|
||||
return (exact, literal_count, -double_star_count, -wildcard_count, depth)
|
||||
|
||||
|
||||
def _specificity(entry: dict[str, Any]) -> tuple[int, int, int, int, int, int, int]:
|
||||
scope = entry.get("scope")
|
||||
if not isinstance(scope, dict) or scope.get("all") is True:
|
||||
return (0, 0, 0, 0, 0, 0, 0)
|
||||
populated = 0
|
||||
exact = 0
|
||||
literal = 0
|
||||
double_star = 0
|
||||
wildcard = 0
|
||||
depth = 0
|
||||
extra_or_patterns = 0
|
||||
for field in SCOPE_FIELDS:
|
||||
values = scope.get(field)
|
||||
if isinstance(values, list) and values:
|
||||
populated += 1
|
||||
scores = [
|
||||
_pattern_specificity(value)
|
||||
for value in values
|
||||
if isinstance(value, str)
|
||||
]
|
||||
if scores:
|
||||
dimension_score = min(scores)
|
||||
exact += dimension_score[0]
|
||||
literal += dimension_score[1]
|
||||
double_star += dimension_score[2]
|
||||
wildcard += dimension_score[3]
|
||||
depth += dimension_score[4]
|
||||
extra_or_patterns += len(scores) - 1
|
||||
return (
|
||||
populated,
|
||||
exact,
|
||||
literal,
|
||||
double_star,
|
||||
wildcard,
|
||||
depth,
|
||||
-extra_or_patterns,
|
||||
)
|
||||
|
||||
|
||||
def select_entries(
|
||||
data: dict[str, Any],
|
||||
context: dict[str, list[str]],
|
||||
*,
|
||||
limit: int = DEFAULT_LIMIT,
|
||||
) -> list[dict[str, Any]]:
|
||||
if isinstance(limit, bool) or not isinstance(limit, int) or not 1 <= limit <= MAX_LIMIT:
|
||||
raise ValueError(f"limit 必须在 1..{MAX_LIMIT} 之间")
|
||||
entries = data.get("entries")
|
||||
if not isinstance(entries, list):
|
||||
return []
|
||||
matched = [
|
||||
entry
|
||||
for entry in entries
|
||||
if isinstance(entry, dict)
|
||||
and entry.get("status") == "active"
|
||||
and isinstance(entry.get("scope"), dict)
|
||||
and scope_matches(entry["scope"], context)
|
||||
and stable_ref(entry) is not None
|
||||
]
|
||||
global_entries = [
|
||||
entry
|
||||
for entry in matched
|
||||
if isinstance(entry.get("scope"), dict)
|
||||
and entry["scope"].get("all") is True
|
||||
]
|
||||
scoped_entries = [entry for entry in matched if entry not in global_entries]
|
||||
global_entries.sort(key=lambda entry: stable_ref(entry) or "")
|
||||
if len(global_entries) > limit:
|
||||
raise ValueError(
|
||||
f"命中的全项目知识有 {len(global_entries)} 条，超过 --limit={limit}；"
|
||||
"提高 limit 后重试，不能静默丢弃全项目护栏"
|
||||
)
|
||||
scoped_entries.sort(
|
||||
key=lambda entry: (
|
||||
*(-part for part in _specificity(entry)),
|
||||
stable_ref(entry) or "",
|
||||
)
|
||||
)
|
||||
return [
|
||||
*global_entries,
|
||||
*scoped_entries[: limit - len(global_entries)],
|
||||
]
|
||||
|
||||
|
||||
def _parser() -> argparse.ArgumentParser:
|
||||
parser = argparse.ArgumentParser(description="选择当前任务适用的 active ACK 知识")
|
||||
parser.add_argument(
|
||||
"knowledge", nargs="?", default="knowledge.yaml", help="知识库路径"
|
||||
)
|
||||
parser.add_argument("--component", action="append", default=[])
|
||||
parser.add_argument("--path", action="append", default=[])
|
||||
parser.add_argument("--dependency", action="append", default=[])
|
||||
parser.add_argument("--version", action="append", default=[])
|
||||
parser.add_argument("--tag", action="append", default=[])
|
||||
parser.add_argument("--symbol", action="append", default=[])
|
||||
parser.add_argument("--error-signature", action="append", default=[])
|
||||
parser.add_argument("--limit", type=int, default=DEFAULT_LIMIT)
|
||||
parser.add_argument(
|
||||
"--project-root",
|
||||
help="可选项目根目录，用于 verificationRegistry symlink containment 校验",
|
||||
)
|
||||
parser.add_argument(
|
||||
"--format", choices=("json", "refs"), default="json", dest="output_format"
|
||||
)
|
||||
return parser
|
||||
|
||||
|
||||
def main(argv: list[str] | None = None) -> int:
|
||||
args = _parser().parse_args(argv)
|
||||
knowledge_path = Path(args.knowledge)
|
||||
if not knowledge_path.is_file():
|
||||
sys.stderr.write(f"找不到知识库文件: {knowledge_path}\n")
|
||||
return 2
|
||||
if not 1 <= args.limit <= MAX_LIMIT:
|
||||
sys.stderr.write(f"--limit 必须在 1..{MAX_LIMIT} 之间\n")
|
||||
return 2
|
||||
|
||||
if args.project_root:
|
||||
project_root = Path(args.project_root).expanduser()
|
||||
if not project_root.is_dir():
|
||||
sys.stderr.write(f"项目根目录不存在: {project_root}\n")
|
||||
return 2
|
||||
project_root = project_root.resolve()
|
||||
else:
|
||||
project_root = infer_project_root(knowledge_path)
|
||||
|
||||
data = load_yaml(knowledge_path, "知识库")
|
||||
errors = validate_builtin_structure(data)
|
||||
errors.extend(validate_semantics(data, project_root=project_root))
|
||||
registry = data.get("verificationRegistry")
|
||||
if project_root is None and isinstance(registry, dict) and registry:
|
||||
errors.append(
|
||||
"verificationRegistry 非空但无法确定项目根目录；请传入 --project-root"
|
||||
)
|
||||
errors = list(dict.fromkeys(errors))
|
||||
if errors:
|
||||
sys.stderr.write(f"知识库无效，拒绝选择，共 {len(errors)} 项：\n")
|
||||
for error in errors:
|
||||
sys.stderr.write(f" - {error}\n")
|
||||
return 1
|
||||
|
||||
context = {
|
||||
"components": args.component,
|
||||
"paths": args.path,
|
||||
"dependencies": args.dependency,
|
||||
"versions": args.version,
|
||||
"tags": args.tag,
|
||||
"symbols": args.symbol,
|
||||
"errorSignatures": args.error_signature,
|
||||
}
|
||||
try:
|
||||
selected = select_entries(data, context, limit=args.limit)
|
||||
except ValueError as exc:
|
||||
sys.stderr.write(f"知识选择失败: {exc}\n")
|
||||
return 1
|
||||
refs = [stable_ref(entry) for entry in selected]
|
||||
if args.output_format == "refs":
|
||||
if refs:
|
||||
sys.stdout.write("\n".join(ref for ref in refs if ref) + "\n")
|
||||
return 0
|
||||
|
||||
payload = {
|
||||
"count": len(selected),
|
||||
"limit": args.limit,
|
||||
"refs": refs,
|
||||
"entries": [
|
||||
{
|
||||
"ref": stable_ref(entry),
|
||||
**entry,
|
||||
"verificationTarget": (
|
||||
data.get("verificationRegistry", {}).get(
|
||||
entry.get("verification", {}).get("ref")
|
||||
)
|
||||
if isinstance(data.get("verificationRegistry"), dict)
|
||||
and isinstance(entry.get("verification"), dict)
|
||||
else None
|
||||
),
|
||||
}
|
||||
for entry in selected
|
||||
],
|
||||
}
|
||||
sys.stdout.write(json.dumps(payload, ensure_ascii=False, indent=2) + "\n")
|
||||
return 0
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
raise SystemExit(main())
|
||||
Executable
+261
@@ -0,0 +1,261 @@
|
||||
#!/usr/bin/env python3
|
||||
"""为 ACK Coordinator 输出有预算的任务板上下文。
|
||||
|
||||
脚本会解析并校验完整 tasks.yaml，但只输出项目配置、摘要、可工作任务或显式任务，
|
||||
以及这些任务引用的 worker receipt 和 delivery run。它不会修改任务板，也不会静默
|
||||
截断超过预算的任务集合。
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import argparse
|
||||
import json
|
||||
import sys
|
||||
from pathlib import Path
|
||||
from typing import Any
|
||||
|
||||
from validate_tasks import STATUS_ENUM, load_document, validate_builtin # type: ignore
|
||||
|
||||
|
||||
ACTIONABLE_STATUSES = (
|
||||
"open",
|
||||
"dispatched",
|
||||
"fixed_by_dev",
|
||||
"retesting",
|
||||
"failed_retest",
|
||||
)
|
||||
DEFAULT_LIMIT = 20
|
||||
MAX_LIMIT = 100
|
||||
MAX_OUTPUT_BYTES = 512 * 1024
|
||||
BOARD_METADATA_FIELDS = (
|
||||
"version",
|
||||
"updatedAt",
|
||||
"source",
|
||||
"ackVersion",
|
||||
"kitVersion",
|
||||
"testRecord",
|
||||
"statusReference",
|
||||
)
|
||||
|
||||
|
||||
class SelectionError(ValueError):
|
||||
pass
|
||||
|
||||
|
||||
def _unique(values: list[str]) -> list[str]:
|
||||
return list(dict.fromkeys(values))
|
||||
|
||||
|
||||
def select_tasks(
|
||||
data: dict[str, Any],
|
||||
*,
|
||||
task_ids: list[str] | None = None,
|
||||
statuses: list[str] | None = None,
|
||||
limit: int = DEFAULT_LIMIT,
|
||||
) -> tuple[str, list[str], list[dict[str, Any]]]:
|
||||
if isinstance(limit, bool) or not isinstance(limit, int) or not 1 <= limit <= MAX_LIMIT:
|
||||
raise SelectionError(f"limit 必须在 1..{MAX_LIMIT} 之间")
|
||||
tasks = data.get("tasks")
|
||||
if not isinstance(tasks, list):
|
||||
raise SelectionError("tasks 必须是列表")
|
||||
|
||||
requested_ids = _unique(task_ids or [])
|
||||
requested_statuses = _unique(statuses or [])
|
||||
if requested_ids and requested_statuses:
|
||||
raise SelectionError("--task-id 与 --status 不能同时使用")
|
||||
|
||||
if requested_ids:
|
||||
by_id = {
|
||||
task.get("id"): task
|
||||
for task in tasks
|
||||
if isinstance(task, dict) and isinstance(task.get("id"), str)
|
||||
}
|
||||
missing = [task_id for task_id in requested_ids if task_id not in by_id]
|
||||
if missing:
|
||||
raise SelectionError("找不到任务: " + ", ".join(missing))
|
||||
selected = [by_id[task_id] for task_id in requested_ids]
|
||||
mode = "task_ids"
|
||||
criteria = requested_ids
|
||||
else:
|
||||
effective_statuses = requested_statuses or list(ACTIONABLE_STATUSES)
|
||||
unknown = [status for status in effective_statuses if status not in STATUS_ENUM]
|
||||
if unknown:
|
||||
raise SelectionError("未知状态: " + ", ".join(unknown))
|
||||
wanted = set(effective_statuses)
|
||||
selected = [
|
||||
task
|
||||
for task in tasks
|
||||
if isinstance(task, dict) and task.get("status") in wanted
|
||||
]
|
||||
mode = "statuses"
|
||||
criteria = effective_statuses
|
||||
|
||||
if len(selected) > limit:
|
||||
raise SelectionError(
|
||||
f"命中 {len(selected)} 条任务，超过 --limit={limit}；"
|
||||
"请用 --task-id/--status 缩小范围或显式提高 limit"
|
||||
)
|
||||
return mode, criteria, selected
|
||||
|
||||
|
||||
def select_referenced_receipts(
|
||||
data: dict[str, Any], selected: list[dict[str, Any]]
|
||||
) -> list[dict[str, Any]]:
|
||||
receipt_ids: list[str] = []
|
||||
for task in selected:
|
||||
dispatch = task.get("dispatch")
|
||||
if not isinstance(dispatch, dict):
|
||||
continue
|
||||
for role in ("developer", "test"):
|
||||
role_dispatch = dispatch.get(role)
|
||||
if not isinstance(role_dispatch, dict):
|
||||
continue
|
||||
receipt_id = role_dispatch.get("receiptId")
|
||||
if isinstance(receipt_id, str) and receipt_id not in receipt_ids:
|
||||
receipt_ids.append(receipt_id)
|
||||
if not receipt_ids:
|
||||
return []
|
||||
|
||||
receipts = data.get("workerReceipts")
|
||||
if not isinstance(receipts, list):
|
||||
raise SelectionError("选中任务引用了 receipt，但 workerReceipts 不是列表")
|
||||
by_id = {
|
||||
receipt.get("id"): receipt
|
||||
for receipt in receipts
|
||||
if isinstance(receipt, dict) and isinstance(receipt.get("id"), str)
|
||||
}
|
||||
missing = [receipt_id for receipt_id in receipt_ids if receipt_id not in by_id]
|
||||
if missing:
|
||||
raise SelectionError("选中任务引用了未知 receipt: " + ", ".join(missing))
|
||||
return [by_id[receipt_id] for receipt_id in receipt_ids]
|
||||
|
||||
|
||||
def select_delivery_runs(
|
||||
data: dict[str, Any], selected: list[dict[str, Any]]
|
||||
) -> list[dict[str, Any]]:
|
||||
selected_ids = {
|
||||
task.get("id")
|
||||
for task in selected
|
||||
if isinstance(task.get("id"), str)
|
||||
}
|
||||
runs = data.get("deliveryRuns")
|
||||
if not selected_ids or not isinstance(runs, list):
|
||||
return []
|
||||
return [
|
||||
run
|
||||
for run in runs
|
||||
if isinstance(run, dict)
|
||||
and isinstance(run.get("taskIds"), list)
|
||||
and any(task_id in selected_ids for task_id in run["taskIds"])
|
||||
]
|
||||
|
||||
|
||||
def build_payload(
|
||||
data: dict[str, Any],
|
||||
*,
|
||||
mode: str,
|
||||
criteria: list[str],
|
||||
selected: list[dict[str, Any]],
|
||||
) -> dict[str, Any]:
|
||||
receipts = select_referenced_receipts(data, selected)
|
||||
delivery_runs = select_delivery_runs(data, selected)
|
||||
tasks = data.get("tasks")
|
||||
metadata = {
|
||||
field: data[field]
|
||||
for field in BOARD_METADATA_FIELDS
|
||||
if field in data
|
||||
}
|
||||
selected_ids = [
|
||||
task["id"]
|
||||
for task in selected
|
||||
if isinstance(task.get("id"), str)
|
||||
]
|
||||
payload: dict[str, Any] = {
|
||||
"board": metadata,
|
||||
"project": data.get("project"),
|
||||
"summary": data.get("summary"),
|
||||
"selection": {
|
||||
"mode": mode,
|
||||
"criteria": criteria,
|
||||
"count": len(selected),
|
||||
"totalTasks": len(tasks) if isinstance(tasks, list) else 0,
|
||||
"selectedTaskIds": selected_ids,
|
||||
"referencedReceiptIds": [receipt.get("id") for receipt in receipts],
|
||||
"deliveryRunIds": [run.get("id") for run in delivery_runs],
|
||||
},
|
||||
"tasks": selected,
|
||||
"workerReceipts": receipts,
|
||||
"deliveryRuns": delivery_runs,
|
||||
}
|
||||
return payload
|
||||
|
||||
|
||||
def _parser() -> argparse.ArgumentParser:
|
||||
parser = argparse.ArgumentParser(
|
||||
description="选择 ACK 任务板的有预算 Coordinator 上下文"
|
||||
)
|
||||
parser.add_argument(
|
||||
"tasks",
|
||||
nargs="?",
|
||||
default="docs/ack/tasks.yaml",
|
||||
help="任务板路径",
|
||||
)
|
||||
parser.add_argument("--task-id", action="append", default=[])
|
||||
parser.add_argument(
|
||||
"--status",
|
||||
action="append",
|
||||
default=[],
|
||||
choices=sorted(STATUS_ENUM),
|
||||
)
|
||||
parser.add_argument("--limit", type=int, default=DEFAULT_LIMIT)
|
||||
parser.add_argument("--compact", action="store_true", help="输出紧凑 JSON")
|
||||
return parser
|
||||
|
||||
|
||||
def main(argv: list[str] | None = None) -> int:
|
||||
args = _parser().parse_args(argv)
|
||||
tasks_path = Path(args.tasks)
|
||||
if not tasks_path.is_file():
|
||||
sys.stderr.write(f"找不到任务板文件: {tasks_path}\n")
|
||||
return 2
|
||||
|
||||
data = load_document(tasks_path)
|
||||
errors = validate_builtin(data)
|
||||
if errors:
|
||||
sys.stderr.write(f"任务板无效，拒绝选择，共 {len(errors)} 项：\n")
|
||||
for error in errors:
|
||||
sys.stderr.write(f" - {error}\n")
|
||||
return 1
|
||||
|
||||
try:
|
||||
mode, criteria, selected = select_tasks(
|
||||
data,
|
||||
task_ids=args.task_id,
|
||||
statuses=args.status,
|
||||
limit=args.limit,
|
||||
)
|
||||
payload = build_payload(
|
||||
data,
|
||||
mode=mode,
|
||||
criteria=criteria,
|
||||
selected=selected,
|
||||
)
|
||||
except SelectionError as exc:
|
||||
sys.stderr.write(f"任务选择失败: {exc}\n")
|
||||
return 1
|
||||
|
||||
if args.compact:
|
||||
output = json.dumps(payload, ensure_ascii=False, separators=(",", ":"))
|
||||
else:
|
||||
output = json.dumps(payload, ensure_ascii=False, indent=2)
|
||||
if len(output.encode("utf-8")) > MAX_OUTPUT_BYTES:
|
||||
sys.stderr.write(
|
||||
f"任务选择输出超过 {MAX_OUTPUT_BYTES} bytes；请进一步缩小任务范围\n"
|
||||
)
|
||||
return 1
|
||||
sys.stdout.write(output + "\n")
|
||||
return 0
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
raise SystemExit(main())
|
||||
Executable
+809
@@ -0,0 +1,809 @@
|
||||
#!/usr/bin/env python3
|
||||
"""校验 ACK 项目交付契约。
|
||||
|
||||
权威结构位于 templates/delivery.schema.json。jsonschema 是可选依赖；内置规则始终
|
||||
检查引用、步骤顺序、默认 profile 安全边界、敏感信息和仓库内入口路径。
|
||||
|
||||
用法:
|
||||
python3 validate_delivery.py docs/ack/delivery.yaml
|
||||
python3 validate_delivery.py docs/ack/delivery.yaml \
|
||||
--tasks docs/ack/tasks.yaml --project-root <project-root>
|
||||
|
||||
退出码: 0 通过 / 1 校验失败 / 2 环境或用法错误。
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import argparse
|
||||
import json
|
||||
import re
|
||||
import stat
|
||||
import sys
|
||||
from pathlib import Path, PurePosixPath
|
||||
from typing import Any
|
||||
|
||||
from yaml_subset import (
|
||||
DuplicateKeyError,
|
||||
YamlSubsetError,
|
||||
load_json_unique,
|
||||
load_yaml_subset,
|
||||
make_unique_pyyaml_loader,
|
||||
)
|
||||
|
||||
|
||||
ID_RE = re.compile(r"^[a-z][a-z0-9-]{0,63}$")
|
||||
RELATIVE_PATH_RE = re.compile(r"^[A-Za-z0-9._/*?+-]+$")
|
||||
PLATFORM_RE = re.compile(r"^[a-z0-9]+/[A-Za-z0-9._-]+$")
|
||||
SECRET_NAME_RE = re.compile(r"^[A-Z][A-Z0-9_]{0,127}$")
|
||||
REMOTE_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$")
|
||||
|
||||
TOP_LEVEL_FIELDS = {
|
||||
"version",
|
||||
"updatedAt",
|
||||
"project",
|
||||
"enabled",
|
||||
"defaultProfile",
|
||||
"entrypoints",
|
||||
"artifacts",
|
||||
"destinations",
|
||||
"environments",
|
||||
"profiles",
|
||||
}
|
||||
ENTRYPOINT_FIELDS = {
|
||||
"kind",
|
||||
"target",
|
||||
"function",
|
||||
"path",
|
||||
"args",
|
||||
"requiredSecrets",
|
||||
"workingDirectory",
|
||||
"timeoutSeconds",
|
||||
}
|
||||
ARTIFACT_FIELDS = {"type", "build", "outputs", "image", "platforms"}
|
||||
DESTINATION_FIELDS = {
|
||||
"type",
|
||||
"channel",
|
||||
"registry",
|
||||
"repository",
|
||||
"endpoint",
|
||||
"artifactName",
|
||||
"upload",
|
||||
}
|
||||
ENVIRONMENT_FIELDS = {
|
||||
"type",
|
||||
"classification",
|
||||
"target",
|
||||
"deploy",
|
||||
"healthCheck",
|
||||
"rollback",
|
||||
"mutex",
|
||||
}
|
||||
PROFILE_FIELDS = {"stopAt", "steps"}
|
||||
STEP_FIELDS = {
|
||||
"id",
|
||||
"action",
|
||||
"entrypoint",
|
||||
"artifact",
|
||||
"destination",
|
||||
"environment",
|
||||
"gate",
|
||||
"draft",
|
||||
"remote",
|
||||
"baseBranch",
|
||||
}
|
||||
|
||||
ENTRYPOINT_KINDS = {"make", "just", "task", "dagger", "script"}
|
||||
ARTIFACT_TYPES = {"deb", "oci-image", "file"}
|
||||
DESTINATION_TYPES = {"apt-repository", "oci-registry", "ci-artifact"}
|
||||
CHANNELS = {"preview", "staging", "stable"}
|
||||
ENVIRONMENT_TYPES = {"ssh-host", "docker-compose", "kubernetes", "custom"}
|
||||
CLASSIFICATIONS = {"development", "staging", "production"}
|
||||
STOP_POINTS = {"verified", "review_ready", "released"}
|
||||
ACTIONS = {
|
||||
"verify",
|
||||
"pull-request",
|
||||
"build",
|
||||
"publish",
|
||||
"deploy",
|
||||
"health-check",
|
||||
"approval",
|
||||
"mark-ready",
|
||||
}
|
||||
ACTION_FIELDS = {
|
||||
"verify": {"entrypoint"},
|
||||
"pull-request": {"draft", "remote", "baseBranch"},
|
||||
"build": {"artifact"},
|
||||
"publish": {"artifact", "destination"},
|
||||
"deploy": {"artifact", "environment"},
|
||||
"health-check": {"environment"},
|
||||
"approval": {"gate"},
|
||||
"mark-ready": set(),
|
||||
}
|
||||
|
||||
SECRET_PATTERNS = (
|
||||
("private key", re.compile(r"-----BEGIN [A-Z0-9 ]*PRIVATE KEY-----")),
|
||||
("GitHub token", re.compile(r"\bgh[pousr]_[A-Za-z0-9]{20,}\b")),
|
||||
("OpenAI-style token", re.compile(r"\bsk-[A-Za-z0-9_-]{20,}\b")),
|
||||
("AWS access key", re.compile(r"\b(?:AKIA|ASIA)[A-Z0-9]{16}\b")),
|
||||
("URL credentials", re.compile(r"https?://[^/\s:@]+:[^/\s@]+@")),
|
||||
(
|
||||
"inline secret assignment",
|
||||
re.compile(
|
||||
r"(?i)\b(?:api[_-]?key|access[_-]?token|password|secret|token)"
|
||||
r"\s*[:=]\s*[\"']?[^\s,\"']{8,}"
|
||||
),
|
||||
),
|
||||
)
|
||||
|
||||
|
||||
def _nonempty(value: Any) -> bool:
|
||||
return isinstance(value, str) and bool(value.strip())
|
||||
|
||||
|
||||
def _mapping(value: Any) -> bool:
|
||||
return isinstance(value, dict)
|
||||
|
||||
|
||||
def _reject_unknown(
|
||||
value: dict[str, Any],
|
||||
allowed: set[str],
|
||||
where: str,
|
||||
errors: list[str],
|
||||
) -> None:
|
||||
for field in sorted(set(value) - allowed):
|
||||
errors.append(f"{where}: 未知字段 {field!r}")
|
||||
|
||||
|
||||
def _load_document(path: Path, label: str) -> dict[str, Any]:
|
||||
try:
|
||||
content = path.read_text(encoding="utf-8")
|
||||
except OSError as exc:
|
||||
sys.stderr.write(f"{label}读取失败: {exc}\n")
|
||||
raise SystemExit(1)
|
||||
|
||||
if path.suffix.lower() == ".json":
|
||||
try:
|
||||
data = load_json_unique(content)
|
||||
except (json.JSONDecodeError, DuplicateKeyError) as exc:
|
||||
sys.stderr.write(f"{label} JSON 解析失败: {exc}\n")
|
||||
raise SystemExit(1)
|
||||
else:
|
||||
try:
|
||||
import yaml # type: ignore
|
||||
except ImportError:
|
||||
try:
|
||||
data = load_yaml_subset(content)
|
||||
except YamlSubsetError as exc:
|
||||
sys.stderr.write(f"{label} YAML 子集解析失败: {exc}\n")
|
||||
raise SystemExit(1)
|
||||
else:
|
||||
try:
|
||||
data = yaml.load(content, Loader=make_unique_pyyaml_loader(yaml))
|
||||
except yaml.YAMLError as exc: # type: ignore
|
||||
sys.stderr.write(f"{label} YAML 解析失败: {exc}\n")
|
||||
raise SystemExit(1)
|
||||
|
||||
if not isinstance(data, dict):
|
||||
sys.stderr.write(f"{label}顶层必须是对象（mapping）\n")
|
||||
raise SystemExit(1)
|
||||
return data
|
||||
|
||||
|
||||
def _safe_relative_path(value: Any, *, allow_glob: bool = False) -> bool:
|
||||
if not _nonempty(value) or value.startswith("/") or "\\" in value:
|
||||
return False
|
||||
if not RELATIVE_PATH_RE.fullmatch(value):
|
||||
return False
|
||||
if not allow_glob and any(marker in value for marker in "*?"):
|
||||
return False
|
||||
parts = PurePosixPath(value).parts
|
||||
return ".." not in parts and all(part not in {"", "/"} for part in parts)
|
||||
|
||||
|
||||
def _safe_branch_name(value: Any) -> bool:
|
||||
if not _nonempty(value) or len(value) > 255:
|
||||
return False
|
||||
if value == "@" or value.startswith(("/", ".", "-")):
|
||||
return False
|
||||
if value.endswith(("/", ".", ".lock")):
|
||||
return False
|
||||
if "@{" in value or ".." in value or "//" in value:
|
||||
return False
|
||||
return re.search(r"[\x00-\x20\x7f~^:?*\[\\]", value) is None
|
||||
|
||||
|
||||
def _validate_path_binding(
|
||||
project_root: Path,
|
||||
relative_path: str,
|
||||
where: str,
|
||||
*,
|
||||
expected: str,
|
||||
) -> list[str]:
|
||||
errors: list[str] = []
|
||||
current = project_root
|
||||
parts = PurePosixPath(relative_path).parts
|
||||
if relative_path == ".":
|
||||
parts = ()
|
||||
for index, part in enumerate(parts):
|
||||
current = current / part
|
||||
try:
|
||||
metadata = current.lstat()
|
||||
except FileNotFoundError:
|
||||
return [f"{where}: 路径不存在: {relative_path!r}"]
|
||||
except OSError as exc:
|
||||
return [f"{where}: 路径不可访问: {relative_path!r}: {exc}"]
|
||||
if stat.S_ISLNK(metadata.st_mode):
|
||||
return [f"{where}: 路径不能包含 symlink: {relative_path!r}"]
|
||||
if index < len(parts) - 1 and not stat.S_ISDIR(metadata.st_mode):
|
||||
return [f"{where}: 中间路径不是目录: {relative_path!r}"]
|
||||
|
||||
try:
|
||||
metadata
|
||||
except UnboundLocalError:
|
||||
metadata = project_root.lstat()
|
||||
if expected == "directory" and not stat.S_ISDIR(metadata.st_mode):
|
||||
errors.append(f"{where}: 必须指向目录: {relative_path!r}")
|
||||
if expected == "executable":
|
||||
if not stat.S_ISREG(metadata.st_mode):
|
||||
errors.append(f"{where}: 必须指向普通文件: {relative_path!r}")
|
||||
elif metadata.st_mode & 0o111 == 0:
|
||||
errors.append(f"{where}: 脚本不可执行: {relative_path!r}")
|
||||
return errors
|
||||
|
||||
|
||||
def _scan_secrets(value: Any, where: str, errors: list[str]) -> None:
|
||||
if isinstance(value, dict):
|
||||
for key, item in value.items():
|
||||
_scan_secrets(item, f"{where}.{key}", errors)
|
||||
return
|
||||
if isinstance(value, list):
|
||||
for index, item in enumerate(value):
|
||||
_scan_secrets(item, f"{where}[{index}]", errors)
|
||||
return
|
||||
if not isinstance(value, str):
|
||||
return
|
||||
for label, pattern in SECRET_PATTERNS:
|
||||
if pattern.search(value):
|
||||
errors.append(f"{where}: 疑似包含敏感信息（{label}）")
|
||||
|
||||
|
||||
def _validate_ids(values: Any, where: str, errors: list[str]) -> dict[str, Any]:
|
||||
if not isinstance(values, dict):
|
||||
errors.append(f"{where}: 必须是对象")
|
||||
return {}
|
||||
for key in values:
|
||||
if not isinstance(key, str) or ID_RE.fullmatch(key) is None:
|
||||
errors.append(f"{where}: ID {key!r} 必须使用小写连字符格式")
|
||||
return values
|
||||
|
||||
|
||||
def _validate_entrypoints(
|
||||
values: dict[str, Any],
|
||||
errors: list[str],
|
||||
project_root: Path | None,
|
||||
) -> None:
|
||||
for entrypoint_id, value in values.items():
|
||||
where = f"entrypoints.{entrypoint_id}"
|
||||
if not _mapping(value):
|
||||
errors.append(f"{where}: 必须是对象")
|
||||
continue
|
||||
_reject_unknown(value, ENTRYPOINT_FIELDS, where, errors)
|
||||
kind = value.get("kind")
|
||||
if kind not in ENTRYPOINT_KINDS:
|
||||
errors.append(f"{where}.kind: 必须是 {sorted(ENTRYPOINT_KINDS)}")
|
||||
required_selector = {
|
||||
"make": "target",
|
||||
"just": "target",
|
||||
"task": "target",
|
||||
"dagger": "function",
|
||||
"script": "path",
|
||||
}.get(kind)
|
||||
for selector in ("target", "function", "path"):
|
||||
if selector == required_selector:
|
||||
if not _nonempty(value.get(selector)):
|
||||
errors.append(f"{where}.{selector}: {kind} 入口必须填写非空值")
|
||||
elif selector in value:
|
||||
errors.append(f"{where}.{selector}: kind={kind!r} 不允许此字段")
|
||||
|
||||
args = value.get("args")
|
||||
if not isinstance(args, list) or any(not isinstance(item, str) for item in args):
|
||||
errors.append(f"{where}.args: 必须是字符串列表")
|
||||
required_secrets = value.get("requiredSecrets")
|
||||
if (
|
||||
not isinstance(required_secrets, list)
|
||||
or any(
|
||||
not isinstance(item, str) or SECRET_NAME_RE.fullmatch(item) is None
|
||||
for item in required_secrets
|
||||
)
|
||||
or (
|
||||
isinstance(required_secrets, list)
|
||||
and len(required_secrets) != len(set(required_secrets))
|
||||
)
|
||||
):
|
||||
errors.append(
|
||||
f"{where}.requiredSecrets: 必须是唯一的大写 secret 名称列表"
|
||||
)
|
||||
working_directory = value.get("workingDirectory")
|
||||
if not _safe_relative_path(working_directory):
|
||||
errors.append(f"{where}.workingDirectory: 必须是安全的仓库内相对路径")
|
||||
timeout = value.get("timeoutSeconds")
|
||||
if (
|
||||
not isinstance(timeout, int)
|
||||
or isinstance(timeout, bool)
|
||||
or not 1 <= timeout <= 86400
|
||||
):
|
||||
errors.append(f"{where}.timeoutSeconds: 必须是 1..86400 的整数")
|
||||
|
||||
if kind == "script" and not _safe_relative_path(value.get("path")):
|
||||
errors.append(f"{where}.path: 必须是安全的仓库内相对路径")
|
||||
if project_root is not None:
|
||||
if _safe_relative_path(working_directory):
|
||||
errors.extend(
|
||||
_validate_path_binding(
|
||||
project_root,
|
||||
working_directory,
|
||||
f"{where}.workingDirectory",
|
||||
expected="directory",
|
||||
)
|
||||
)
|
||||
if kind == "script" and _safe_relative_path(value.get("path")):
|
||||
errors.extend(
|
||||
_validate_path_binding(
|
||||
project_root,
|
||||
value["path"],
|
||||
f"{where}.path",
|
||||
expected="executable",
|
||||
)
|
||||
)
|
||||
|
||||
|
||||
def _validate_artifacts(
|
||||
values: dict[str, Any],
|
||||
entrypoints: dict[str, Any],
|
||||
errors: list[str],
|
||||
) -> None:
|
||||
for artifact_id, value in values.items():
|
||||
where = f"artifacts.{artifact_id}"
|
||||
if not _mapping(value):
|
||||
errors.append(f"{where}: 必须是对象")
|
||||
continue
|
||||
_reject_unknown(value, ARTIFACT_FIELDS, where, errors)
|
||||
artifact_type = value.get("type")
|
||||
if artifact_type not in ARTIFACT_TYPES:
|
||||
errors.append(f"{where}.type: 必须是 {sorted(ARTIFACT_TYPES)}")
|
||||
build = value.get("build")
|
||||
if build not in entrypoints:
|
||||
errors.append(f"{where}.build: 未定义 entrypoint {build!r}")
|
||||
outputs = value.get("outputs")
|
||||
if artifact_type in {"deb", "file"}:
|
||||
if (
|
||||
not isinstance(outputs, list)
|
||||
or not outputs
|
||||
or any(not _safe_relative_path(item, allow_glob=True) for item in outputs)
|
||||
):
|
||||
errors.append(f"{where}.outputs: deb/file 必须填写安全的产物路径列表")
|
||||
if "image" in value or "platforms" in value:
|
||||
errors.append(f"{where}: deb/file 不允许 image 或 platforms")
|
||||
if artifact_type == "oci-image":
|
||||
if not _nonempty(value.get("image")):
|
||||
errors.append(f"{where}.image: oci-image 必须填写镜像名")
|
||||
platforms = value.get("platforms")
|
||||
if (
|
||||
not isinstance(platforms, list)
|
||||
or not platforms
|
||||
or any(not isinstance(item, str) or PLATFORM_RE.fullmatch(item) is None for item in platforms)
|
||||
or len(platforms) != len(set(platforms))
|
||||
):
|
||||
errors.append(f"{where}.platforms: 必须是唯一的 os/arch 列表")
|
||||
if "outputs" in value:
|
||||
errors.append(f"{where}: oci-image 不允许 outputs")
|
||||
|
||||
|
||||
def _validate_destinations(
|
||||
values: dict[str, Any],
|
||||
entrypoints: dict[str, Any],
|
||||
errors: list[str],
|
||||
) -> None:
|
||||
for destination_id, value in values.items():
|
||||
where = f"destinations.{destination_id}"
|
||||
if not _mapping(value):
|
||||
errors.append(f"{where}: 必须是对象")
|
||||
continue
|
||||
_reject_unknown(value, DESTINATION_FIELDS, where, errors)
|
||||
destination_type = value.get("type")
|
||||
if destination_type not in DESTINATION_TYPES:
|
||||
errors.append(f"{where}.type: 必须是 {sorted(DESTINATION_TYPES)}")
|
||||
type_fields = {
|
||||
"apt-repository": {"endpoint", "repository"},
|
||||
"oci-registry": {"registry", "repository"},
|
||||
"ci-artifact": {"artifactName"},
|
||||
}.get(destination_type, set())
|
||||
allowed_fields = {"type", "channel", "upload"} | type_fields
|
||||
for field in sorted(set(value) - allowed_fields):
|
||||
errors.append(f"{where}.{field}: type={destination_type!r} 不允许此字段")
|
||||
if value.get("channel") not in CHANNELS:
|
||||
errors.append(f"{where}.channel: 必须是 {sorted(CHANNELS)}")
|
||||
upload = value.get("upload")
|
||||
if upload is not None and upload not in entrypoints:
|
||||
errors.append(f"{where}.upload: 未定义 entrypoint {upload!r}")
|
||||
if destination_type == "apt-repository":
|
||||
if not _nonempty(value.get("endpoint")):
|
||||
errors.append(f"{where}.endpoint: APT 目标必须填写服务地址")
|
||||
if not _nonempty(value.get("repository")):
|
||||
errors.append(f"{where}.repository: APT 目标必须填写仓库名")
|
||||
if destination_type == "oci-registry":
|
||||
for field in ("registry", "repository"):
|
||||
if not _nonempty(value.get(field)):
|
||||
errors.append(f"{where}.{field}: OCI 目标必须填写非空值")
|
||||
if destination_type == "ci-artifact" and not _nonempty(value.get("artifactName")):
|
||||
errors.append(f"{where}.artifactName: CI artifact 必须填写名称")
|
||||
|
||||
|
||||
def _validate_environments(
|
||||
values: dict[str, Any],
|
||||
entrypoints: dict[str, Any],
|
||||
errors: list[str],
|
||||
) -> None:
|
||||
for environment_id, value in values.items():
|
||||
where = f"environments.{environment_id}"
|
||||
if not _mapping(value):
|
||||
errors.append(f"{where}: 必须是对象")
|
||||
continue
|
||||
_reject_unknown(value, ENVIRONMENT_FIELDS, where, errors)
|
||||
if value.get("type") not in ENVIRONMENT_TYPES:
|
||||
errors.append(f"{where}.type: 必须是 {sorted(ENVIRONMENT_TYPES)}")
|
||||
classification = value.get("classification")
|
||||
if classification not in CLASSIFICATIONS:
|
||||
errors.append(f"{where}.classification: 必须是 {sorted(CLASSIFICATIONS)}")
|
||||
if not _nonempty(value.get("target")):
|
||||
errors.append(f"{where}.target: 必须是非空目标别名")
|
||||
for field in ("deploy", "healthCheck"):
|
||||
reference = value.get(field)
|
||||
if reference not in entrypoints:
|
||||
errors.append(f"{where}.{field}: 未定义 entrypoint {reference!r}")
|
||||
rollback = value.get("rollback")
|
||||
if rollback is not None and rollback not in entrypoints:
|
||||
errors.append(f"{where}.rollback: 未定义 entrypoint {rollback!r}")
|
||||
if classification == "production" and rollback is None:
|
||||
errors.append(f"{where}.rollback: production 环境必须提供回滚入口")
|
||||
if not _nonempty(value.get("mutex")):
|
||||
errors.append(f"{where}.mutex: 必须填写部署互斥锁 ID")
|
||||
|
||||
|
||||
def _artifact_destination_compatible(artifact_type: str, destination_type: str) -> bool:
|
||||
return destination_type in {
|
||||
"deb": {"apt-repository", "ci-artifact"},
|
||||
"oci-image": {"oci-registry", "ci-artifact"},
|
||||
"file": {"ci-artifact"},
|
||||
}.get(artifact_type, set())
|
||||
|
||||
|
||||
def _validate_profiles(
|
||||
values: dict[str, Any],
|
||||
*,
|
||||
default_profile: Any,
|
||||
entrypoints: dict[str, Any],
|
||||
artifacts: dict[str, Any],
|
||||
destinations: dict[str, Any],
|
||||
environments: dict[str, Any],
|
||||
errors: list[str],
|
||||
) -> None:
|
||||
for profile_id, value in values.items():
|
||||
where = f"profiles.{profile_id}"
|
||||
if not _mapping(value):
|
||||
errors.append(f"{where}: 必须是对象")
|
||||
continue
|
||||
_reject_unknown(value, PROFILE_FIELDS, where, errors)
|
||||
stop_at = value.get("stopAt")
|
||||
if stop_at not in STOP_POINTS:
|
||||
errors.append(f"{where}.stopAt: 必须是 {sorted(STOP_POINTS)}")
|
||||
steps = value.get("steps")
|
||||
if not isinstance(steps, list):
|
||||
errors.append(f"{where}.steps: 必须是列表")
|
||||
continue
|
||||
|
||||
seen_step_ids: set[str] = set()
|
||||
built_artifacts: set[str] = set()
|
||||
published_artifacts: set[str] = set()
|
||||
deployed_environments: set[str] = set()
|
||||
approvals: set[str] = set()
|
||||
has_pull_request = False
|
||||
has_mark_ready = False
|
||||
|
||||
for index, step in enumerate(steps):
|
||||
step_where = f"{where}.steps[{index}]"
|
||||
if not _mapping(step):
|
||||
errors.append(f"{step_where}: 必须是对象")
|
||||
continue
|
||||
_reject_unknown(step, STEP_FIELDS, step_where, errors)
|
||||
step_id = step.get("id")
|
||||
if not isinstance(step_id, str) or ID_RE.fullmatch(step_id) is None:
|
||||
errors.append(f"{step_where}.id: 必须使用小写连字符格式")
|
||||
elif step_id in seen_step_ids:
|
||||
errors.append(f"{step_where}.id: 不能重复 {step_id!r}")
|
||||
else:
|
||||
seen_step_ids.add(step_id)
|
||||
|
||||
action = step.get("action")
|
||||
if action not in ACTIONS:
|
||||
errors.append(f"{step_where}.action: 必须是 {sorted(ACTIONS)}")
|
||||
continue
|
||||
required_fields = ACTION_FIELDS[action]
|
||||
for field in sorted(required_fields):
|
||||
if field not in step:
|
||||
errors.append(f"{step_where}.{field}: action={action!r} 时必填")
|
||||
allowed_fields = {"id", "action"} | required_fields
|
||||
for field in sorted(set(step) - allowed_fields):
|
||||
errors.append(f"{step_where}.{field}: action={action!r} 不允许此字段")
|
||||
|
||||
if action == "verify" and step.get("entrypoint") not in entrypoints:
|
||||
errors.append(
|
||||
f"{step_where}.entrypoint: 未定义 entrypoint {step.get('entrypoint')!r}"
|
||||
)
|
||||
if action == "pull-request":
|
||||
if not isinstance(step.get("draft"), bool):
|
||||
errors.append(f"{step_where}.draft: 必须是布尔值")
|
||||
if (
|
||||
not isinstance(step.get("remote"), str)
|
||||
or REMOTE_RE.fullmatch(step["remote"]) is None
|
||||
):
|
||||
errors.append(f"{step_where}.remote: 必须是安全的 Git remote 名称")
|
||||
if not _safe_branch_name(step.get("baseBranch")):
|
||||
errors.append(f"{step_where}.baseBranch: 必须是安全的 Git 分支名")
|
||||
has_pull_request = True
|
||||
if action == "build":
|
||||
artifact_id = step.get("artifact")
|
||||
if artifact_id not in artifacts:
|
||||
errors.append(f"{step_where}.artifact: 未定义 artifact {artifact_id!r}")
|
||||
else:
|
||||
built_artifacts.add(artifact_id)
|
||||
if action == "publish":
|
||||
artifact_id = step.get("artifact")
|
||||
destination_id = step.get("destination")
|
||||
if artifact_id not in artifacts:
|
||||
errors.append(f"{step_where}.artifact: 未定义 artifact {artifact_id!r}")
|
||||
elif artifact_id not in built_artifacts:
|
||||
errors.append(f"{step_where}: publish 前必须先 build {artifact_id!r}")
|
||||
if destination_id not in destinations:
|
||||
errors.append(
|
||||
f"{step_where}.destination: 未定义 destination {destination_id!r}"
|
||||
)
|
||||
elif artifact_id in artifacts:
|
||||
artifact_type = artifacts[artifact_id].get("type")
|
||||
destination_type = destinations[destination_id].get("type")
|
||||
if not _artifact_destination_compatible(artifact_type, destination_type):
|
||||
errors.append(
|
||||
f"{step_where}: artifact {artifact_type!r} 不能发布到 "
|
||||
f"{destination_type!r}"
|
||||
)
|
||||
if destinations[destination_id].get("channel") == "stable" and "release" not in approvals:
|
||||
errors.append(f"{step_where}: stable 发布前必须有 release approval")
|
||||
published_artifacts.add(artifact_id)
|
||||
if action == "deploy":
|
||||
artifact_id = step.get("artifact")
|
||||
environment_id = step.get("environment")
|
||||
if artifact_id not in artifacts:
|
||||
errors.append(f"{step_where}.artifact: 未定义 artifact {artifact_id!r}")
|
||||
elif artifact_id not in built_artifacts:
|
||||
errors.append(f"{step_where}: deploy 前必须先 build {artifact_id!r}")
|
||||
if environment_id not in environments:
|
||||
errors.append(
|
||||
f"{step_where}.environment: 未定义 environment {environment_id!r}"
|
||||
)
|
||||
else:
|
||||
classification = environments[environment_id].get("classification")
|
||||
if classification == "production" and "production" not in approvals:
|
||||
errors.append(f"{step_where}: production 部署前必须有 production approval")
|
||||
if (
|
||||
classification == "production"
|
||||
and artifact_id not in published_artifacts
|
||||
):
|
||||
errors.append(f"{step_where}: production 部署前必须先 publish 同一产物")
|
||||
deployed_environments.add(environment_id)
|
||||
if action == "health-check":
|
||||
environment_id = step.get("environment")
|
||||
if environment_id not in environments:
|
||||
errors.append(
|
||||
f"{step_where}.environment: 未定义 environment {environment_id!r}"
|
||||
)
|
||||
elif environment_id not in deployed_environments:
|
||||
errors.append(
|
||||
f"{step_where}: health-check 前必须先 deploy {environment_id!r}"
|
||||
)
|
||||
if action == "approval":
|
||||
gate = step.get("gate")
|
||||
if gate not in {"release", "production"}:
|
||||
errors.append(f"{step_where}.gate: 必须是 release/production")
|
||||
else:
|
||||
if gate == "release" and not built_artifacts:
|
||||
errors.append(f"{step_where}: release approval 前必须先 build 产物")
|
||||
if gate == "production" and not published_artifacts:
|
||||
errors.append(f"{step_where}: production approval 前必须先 publish 产物")
|
||||
approvals.add(gate)
|
||||
if action == "mark-ready":
|
||||
if not has_pull_request:
|
||||
errors.append(f"{step_where}: mark-ready 前必须先创建 pull-request")
|
||||
has_mark_ready = True
|
||||
if index != len(steps) - 1:
|
||||
errors.append(f"{step_where}: mark-ready 必须是 profile 最后一步")
|
||||
|
||||
if stop_at in {"review_ready", "released"} and (
|
||||
not has_pull_request or not has_mark_ready
|
||||
):
|
||||
errors.append(
|
||||
f"{where}: {stop_at} 必须包含 pull-request 和末尾 mark-ready"
|
||||
)
|
||||
if stop_at == "released" and not ({"release", "production"} & approvals):
|
||||
errors.append(f"{where}: released profile 必须包含 release 或 production approval")
|
||||
|
||||
if profile_id == default_profile:
|
||||
if stop_at != "review_ready":
|
||||
errors.append(f"{where}: defaultProfile 必须停在 review_ready")
|
||||
used_destinations = {
|
||||
step.get("destination")
|
||||
for step in steps
|
||||
if isinstance(step, dict) and step.get("action") == "publish"
|
||||
}
|
||||
used_environments = {
|
||||
step.get("environment")
|
||||
for step in steps
|
||||
if isinstance(step, dict) and step.get("action") == "deploy"
|
||||
}
|
||||
if any(
|
||||
destinations.get(item, {}).get("channel") == "stable"
|
||||
for item in used_destinations
|
||||
):
|
||||
errors.append(f"{where}: defaultProfile 不能发布 stable 目标")
|
||||
if any(
|
||||
environments.get(item, {}).get("classification") == "production"
|
||||
for item in used_environments
|
||||
):
|
||||
errors.append(f"{where}: defaultProfile 不能部署 production 环境")
|
||||
|
||||
|
||||
def validate_builtin(data: dict[str, Any], project_root: Path | None = None) -> list[str]:
|
||||
errors: list[str] = []
|
||||
_reject_unknown(data, TOP_LEVEL_FIELDS, "<root>", errors)
|
||||
|
||||
if data.get("version") != 1 or isinstance(data.get("version"), bool):
|
||||
errors.append("version 必须是整数 1")
|
||||
if "updatedAt" in data and not _nonempty(data.get("updatedAt")):
|
||||
errors.append("updatedAt 必须是非空字符串")
|
||||
project = data.get("project")
|
||||
if not _mapping(project):
|
||||
errors.append("project 必须是对象")
|
||||
project = {}
|
||||
else:
|
||||
_reject_unknown(project, {"name"}, "project", errors)
|
||||
if not _nonempty(project.get("name")):
|
||||
errors.append("project.name 必须是非空字符串")
|
||||
|
||||
enabled = data.get("enabled")
|
||||
if not isinstance(enabled, bool):
|
||||
errors.append("enabled 必须是布尔值")
|
||||
default_profile = data.get("defaultProfile")
|
||||
if default_profile is not None and (
|
||||
not isinstance(default_profile, str) or ID_RE.fullmatch(default_profile) is None
|
||||
):
|
||||
errors.append("defaultProfile 必须是 null 或小写连字符 ID")
|
||||
|
||||
entrypoints = _validate_ids(data.get("entrypoints"), "entrypoints", errors)
|
||||
artifacts = _validate_ids(data.get("artifacts"), "artifacts", errors)
|
||||
destinations = _validate_ids(data.get("destinations"), "destinations", errors)
|
||||
environments = _validate_ids(data.get("environments"), "environments", errors)
|
||||
profiles = _validate_ids(data.get("profiles"), "profiles", errors)
|
||||
|
||||
_validate_entrypoints(entrypoints, errors, project_root)
|
||||
_validate_artifacts(artifacts, entrypoints, errors)
|
||||
_validate_destinations(destinations, entrypoints, errors)
|
||||
_validate_environments(environments, entrypoints, errors)
|
||||
_validate_profiles(
|
||||
profiles,
|
||||
default_profile=default_profile,
|
||||
entrypoints=entrypoints,
|
||||
artifacts=artifacts,
|
||||
destinations=destinations,
|
||||
environments=environments,
|
||||
errors=errors,
|
||||
)
|
||||
|
||||
if enabled:
|
||||
if default_profile not in profiles:
|
||||
errors.append("enabled=true 时 defaultProfile 必须引用已定义 profile")
|
||||
elif not profiles[default_profile].get("steps"):
|
||||
errors.append("enabled=true 时 defaultProfile.steps 不能为空")
|
||||
elif default_profile is not None and default_profile not in profiles:
|
||||
errors.append("defaultProfile 必须引用已定义 profile")
|
||||
|
||||
_scan_secrets(data, "<root>", errors)
|
||||
return errors
|
||||
|
||||
|
||||
def validate_tasks_link(delivery: dict[str, Any], tasks: dict[str, Any]) -> list[str]:
|
||||
errors: list[str] = []
|
||||
project = tasks.get("project")
|
||||
if not isinstance(project, dict):
|
||||
return ["tasks.project 必须是对象"]
|
||||
if project.get("deliveryFile") != "docs/ack/delivery.yaml":
|
||||
errors.append("tasks.project.deliveryFile 必须固定为 docs/ack/delivery.yaml")
|
||||
delivery_project = delivery.get("project")
|
||||
if (
|
||||
isinstance(delivery_project, dict)
|
||||
and _nonempty(delivery_project.get("name"))
|
||||
and _nonempty(project.get("name"))
|
||||
and delivery_project["name"] != project["name"]
|
||||
):
|
||||
errors.append("delivery.project.name 必须与 tasks.project.name 一致")
|
||||
if not isinstance(tasks.get("deliveryRuns"), list):
|
||||
errors.append("引用 deliveryFile 的任务板必须包含 deliveryRuns 列表")
|
||||
return errors
|
||||
|
||||
|
||||
def validate_with_schema(data: dict[str, Any], schema_path: Path) -> list[str]:
|
||||
import jsonschema # type: ignore
|
||||
|
||||
schema = json.loads(schema_path.read_text(encoding="utf-8"))
|
||||
validator = jsonschema.Draft7Validator(schema)
|
||||
errors = []
|
||||
for error in sorted(validator.iter_errors(data), key=lambda item: list(item.path)):
|
||||
location = "/".join(str(part) for part in error.path) or "<root>"
|
||||
errors.append(f"[schema] {location}: {error.message}")
|
||||
return errors
|
||||
|
||||
|
||||
def main(argv: list[str] | None = None) -> int:
|
||||
parser = argparse.ArgumentParser(description="校验 ACK 项目交付契约")
|
||||
parser.add_argument("delivery", nargs="?", default="docs/ack/delivery.yaml")
|
||||
parser.add_argument("--tasks", help="关联的 docs/ack/tasks.yaml")
|
||||
parser.add_argument("--project-root", help="项目根目录；提供后检查入口路径")
|
||||
parser.add_argument("--schema", help="delivery.schema.json 路径（默认自动探测）")
|
||||
args = parser.parse_args(argv)
|
||||
|
||||
delivery_path = Path(args.delivery)
|
||||
if not delivery_path.is_file():
|
||||
sys.stderr.write(f"找不到交付契约: {delivery_path}\n")
|
||||
return 2
|
||||
project_root = Path(args.project_root).resolve() if args.project_root else None
|
||||
if project_root is not None and not project_root.is_dir():
|
||||
sys.stderr.write(f"项目根目录不存在: {project_root}\n")
|
||||
return 2
|
||||
|
||||
delivery = _load_document(delivery_path, "交付契约")
|
||||
errors = validate_builtin(delivery, project_root)
|
||||
|
||||
if args.tasks:
|
||||
tasks_path = Path(args.tasks)
|
||||
if not tasks_path.is_file():
|
||||
sys.stderr.write(f"找不到任务板: {tasks_path}\n")
|
||||
return 2
|
||||
tasks = _load_document(tasks_path, "任务板")
|
||||
errors.extend(validate_tasks_link(delivery, tasks))
|
||||
|
||||
schema_path = (
|
||||
Path(args.schema)
|
||||
if args.schema
|
||||
else Path(__file__).resolve().parent.parent / "templates" / "delivery.schema.json"
|
||||
)
|
||||
if args.schema and not schema_path.is_file():
|
||||
sys.stderr.write(f"找不到 schema: {schema_path}\n")
|
||||
return 2
|
||||
if schema_path.is_file():
|
||||
try:
|
||||
errors.extend(validate_with_schema(delivery, schema_path))
|
||||
except ImportError:
|
||||
sys.stderr.write("提示: 未安装 jsonschema，仅执行内置语义规则\n")
|
||||
except (OSError, json.JSONDecodeError) as exc:
|
||||
sys.stderr.write(f"schema 读取失败: {exc}\n")
|
||||
return 2
|
||||
|
||||
if errors:
|
||||
for error in errors:
|
||||
sys.stderr.write(f"- {error}\n")
|
||||
return 1
|
||||
|
||||
sys.stdout.write("交付契约校验通过\n")
|
||||
return 0
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
raise SystemExit(main())
|
||||
Executable
+1152
File diff suppressed because it is too large
Load Diff
Executable
+1046
File diff suppressed because it is too large
Load Diff
+31
@@ -0,0 +1,31 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Fail-closed migration shim for ACK's removed free-form command validator.
|
||||
|
||||
ACK v0.10 no longer accepts a shell command as worker configuration. Keep this
|
||||
file only so older documentation or automation fails with a precise migration
|
||||
message instead of silently retaining the unsafe path.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import sys
|
||||
|
||||
|
||||
MIGRATION_MESSAGE = (
|
||||
"ACK v0.10 已停用自由 worker command 校验器；请在 "
|
||||
"docs/ack/tasks.yaml 的 project.orchestration 中声明 profile，并仅调用 "
|
||||
"scripts/launch_worker.py profile-hash|plan|launch。"
|
||||
)
|
||||
|
||||
|
||||
def main(argv: list[str] | None = None) -> int:
|
||||
arguments = list(sys.argv[1:] if argv is None else argv)
|
||||
if arguments == ["--self-test"]:
|
||||
print("legacy worker command 路径已 fail-closed")
|
||||
return 0
|
||||
sys.stderr.write(MIGRATION_MESSAGE + "\n")
|
||||
return 2
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
raise SystemExit(main())
|
||||
@@ -0,0 +1,992 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Strict, zero-dependency primitives for ACK worker routing.
|
||||
|
||||
This module deliberately validates structured data rather than accepting a
|
||||
shell command. It does not invoke Orca, resolve executables, inspect Git, or
|
||||
write ``tasks.yaml``. A launcher can use the validated profile and the exact
|
||||
argv renderer below, then persist its externally observed facts as a receipt.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import hashlib
|
||||
import json
|
||||
import os
|
||||
import re
|
||||
from datetime import datetime
|
||||
from pathlib import Path
|
||||
from typing import Any
|
||||
|
||||
|
||||
PROFILE_VERSION = 1
|
||||
RECEIPT_VERSION = 1
|
||||
LAUNCH_PROTOCOL_VERSION = 1
|
||||
MAX_ROUNDS = 3
|
||||
|
||||
ROLES = frozenset({"developer", "test"})
|
||||
CLIS = frozenset({"codex", "cursor-agent"})
|
||||
TIERS = frozenset({"standard", "strong"})
|
||||
REASONING_EFFORTS = frozenset({"low", "medium", "high", "xhigh"})
|
||||
PERMISSION_MODES = frozenset({"read-only", "workspace-write"})
|
||||
ORCHESTRATION_MODES = frozenset({"orca", "manual"})
|
||||
DEFAULT_KEYS = frozenset({"developer", "test", "developerUpgraded"})
|
||||
|
||||
ORCHESTRATION_FIELDS = frozenset(
|
||||
{
|
||||
"profileVersion",
|
||||
"mode",
|
||||
"allowedWorktrees",
|
||||
"modelAllowlist",
|
||||
"profiles",
|
||||
"defaults",
|
||||
}
|
||||
)
|
||||
PROFILE_FIELDS = frozenset(
|
||||
{
|
||||
"role",
|
||||
"cli",
|
||||
"tier",
|
||||
"model",
|
||||
"reasoningEffort",
|
||||
"permissionMode",
|
||||
}
|
||||
)
|
||||
RECEIPT_FIELDS = frozenset(
|
||||
{
|
||||
"receiptVersion",
|
||||
"id",
|
||||
"launchId",
|
||||
"profileId",
|
||||
"profileHash",
|
||||
"launchFingerprint",
|
||||
"slot",
|
||||
"createdFor",
|
||||
"worktree",
|
||||
"requested",
|
||||
"binding",
|
||||
"createdAt",
|
||||
"receiptHash",
|
||||
}
|
||||
)
|
||||
CREATED_FOR_FIELDS = frozenset({"taskId", "attemptId", "role"})
|
||||
WORKTREE_FIELDS = frozenset(
|
||||
{
|
||||
"path",
|
||||
"device",
|
||||
"inode",
|
||||
"gitCommonDir",
|
||||
"gitCommonDevice",
|
||||
"gitCommonInode",
|
||||
}
|
||||
)
|
||||
REQUESTED_FIELDS = frozenset(
|
||||
{
|
||||
"cli",
|
||||
"tier",
|
||||
"model",
|
||||
"reasoningEffort",
|
||||
"permissionMode",
|
||||
"executable",
|
||||
"executableDevice",
|
||||
"executableInode",
|
||||
"cliVersion",
|
||||
"argv",
|
||||
"argvHash",
|
||||
"environmentPolicy",
|
||||
}
|
||||
)
|
||||
BINDING_FIELDS = frozenset(
|
||||
{
|
||||
"orchestrator",
|
||||
"runtimeId",
|
||||
"handle",
|
||||
"incarnationId",
|
||||
"observedWorktreePath",
|
||||
"connected",
|
||||
"writable",
|
||||
"boundAt",
|
||||
}
|
||||
)
|
||||
ROLE_DISPATCH_FIELDS = frozenset(
|
||||
{"profileId", "receiptId", "attemptId", "taskId", "dispatchId"}
|
||||
)
|
||||
|
||||
PROFILE_ID_RE = re.compile(r"^[a-z][a-z0-9-]{1,63}$")
|
||||
MODEL_ID_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._:/+@-]{0,127}$")
|
||||
RECEIPT_ID_RE = re.compile(r"^WR-[0-9a-f]{64}$")
|
||||
LAUNCH_ID_RE = re.compile(r"^[0-9a-f]{64}$")
|
||||
TASK_ID_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$")
|
||||
ATTEMPT_ID_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]*-A[1-3]$")
|
||||
SHA256_RE = re.compile(r"^sha256:[0-9a-f]{64}$")
|
||||
|
||||
|
||||
def _canonical_json(value: Any) -> str:
|
||||
"""Return the one JSON representation used by all hashes in this module."""
|
||||
|
||||
try:
|
||||
return json.dumps(
|
||||
value,
|
||||
ensure_ascii=False,
|
||||
sort_keys=True,
|
||||
separators=(",", ":"),
|
||||
allow_nan=False,
|
||||
)
|
||||
except (RecursionError, TypeError, ValueError) as exc:
|
||||
raise ValueError(f"value is not canonical JSON data: {exc}") from exc
|
||||
|
||||
|
||||
def canonical_sha256(value: Any) -> str:
|
||||
"""Hash canonical UTF-8 JSON and return ``sha256:<lowercase hex>``."""
|
||||
|
||||
digest = hashlib.sha256(_canonical_json(value).encode("utf-8")).hexdigest()
|
||||
return f"sha256:{digest}"
|
||||
|
||||
|
||||
def _unknown_fields(value: dict[str, Any], allowed: frozenset[str], where: str) -> list[str]:
|
||||
unknown = set(value) - allowed
|
||||
return [
|
||||
f"{where}: unknown field {field!r}"
|
||||
for field in sorted(unknown, key=repr)
|
||||
]
|
||||
|
||||
|
||||
def _missing_fields(value: dict[str, Any], required: frozenset[str], where: str) -> list[str]:
|
||||
return [f"{where}: missing field {field!r}" for field in sorted(required - set(value))]
|
||||
|
||||
|
||||
def _is_nonempty_text(value: Any, *, max_length: int = 1024) -> bool:
|
||||
return (
|
||||
isinstance(value, str)
|
||||
and bool(value.strip())
|
||||
and len(value) <= max_length
|
||||
and all(ord(character) >= 32 and ord(character) != 127 for character in value)
|
||||
)
|
||||
|
||||
|
||||
def _is_absolute_safe_path(value: Any) -> bool:
|
||||
if not _is_nonempty_text(value, max_length=4096):
|
||||
return False
|
||||
path = Path(value)
|
||||
return (
|
||||
path.is_absolute()
|
||||
and value != os.path.sep
|
||||
and not value.startswith("//")
|
||||
and ".." not in path.parts
|
||||
and os.path.normpath(value) == value
|
||||
)
|
||||
|
||||
|
||||
def _is_nonnegative_int(value: Any) -> bool:
|
||||
return isinstance(value, int) and not isinstance(value, bool) and value >= 0
|
||||
|
||||
|
||||
def _is_positive_int(value: Any) -> bool:
|
||||
return isinstance(value, int) and not isinstance(value, bool) and value > 0
|
||||
|
||||
|
||||
def _is_timestamp(value: Any) -> bool:
|
||||
if not isinstance(value, str):
|
||||
return False
|
||||
try:
|
||||
parsed = datetime.fromisoformat(value.replace("Z", "+00:00"))
|
||||
except ValueError:
|
||||
return False
|
||||
return parsed.tzinfo is not None
|
||||
|
||||
|
||||
def validate_profile(profile: Any, *, where: str = "profile") -> list[str]:
|
||||
"""Validate one strict worker profile without consulting its allowlist."""
|
||||
|
||||
if not isinstance(profile, dict):
|
||||
return [f"{where}: must be an object"]
|
||||
|
||||
errors = _unknown_fields(profile, PROFILE_FIELDS, where)
|
||||
errors.extend(_missing_fields(profile, PROFILE_FIELDS, where))
|
||||
|
||||
role = profile.get("role")
|
||||
cli = profile.get("cli")
|
||||
tier = profile.get("tier")
|
||||
model = profile.get("model")
|
||||
effort = profile.get("reasoningEffort")
|
||||
permission = profile.get("permissionMode")
|
||||
|
||||
if not isinstance(role, str) or role not in ROLES:
|
||||
errors.append(f"{where}.role: must be developer/test")
|
||||
if not isinstance(cli, str) or cli not in CLIS:
|
||||
errors.append(f"{where}.cli: must be codex/cursor-agent")
|
||||
if not isinstance(tier, str) or tier not in TIERS:
|
||||
errors.append(f"{where}.tier: must be standard/strong")
|
||||
if not isinstance(model, str) or MODEL_ID_RE.fullmatch(model) is None:
|
||||
errors.append(f"{where}.model: must be a safe model ID")
|
||||
if not isinstance(permission, str) or permission not in PERMISSION_MODES:
|
||||
errors.append(
|
||||
f"{where}.permissionMode: must be read-only/workspace-write"
|
||||
)
|
||||
|
||||
if cli == "codex":
|
||||
if not isinstance(effort, str) or effort not in REASONING_EFFORTS:
|
||||
errors.append(
|
||||
f"{where}.reasoningEffort: Codex requires low/medium/high/xhigh"
|
||||
)
|
||||
elif cli == "cursor-agent" and effort is not None:
|
||||
errors.append(f"{where}.reasoningEffort: Cursor requires null")
|
||||
|
||||
if role == "test" and tier != "standard":
|
||||
errors.append(f"{where}.tier: Test may only use standard")
|
||||
if tier == "strong" and role != "developer":
|
||||
errors.append(f"{where}.tier: strong may only be used by Developer")
|
||||
|
||||
return errors
|
||||
|
||||
|
||||
def _validate_model_allowlist(value: Any, where: str) -> list[str]:
|
||||
if not isinstance(value, dict):
|
||||
return [f"{where}: must be an object"]
|
||||
|
||||
errors: list[str] = []
|
||||
for cli in sorted(set(value) - CLIS, key=repr):
|
||||
errors.append(f"{where}: unknown CLI {cli!r}")
|
||||
for cli, roles in value.items():
|
||||
cli_where = f"{where}.{cli}"
|
||||
if cli not in CLIS:
|
||||
continue
|
||||
if not isinstance(roles, dict):
|
||||
errors.append(f"{cli_where}: must be an object")
|
||||
continue
|
||||
if not roles:
|
||||
errors.append(f"{cli_where}: must not be empty")
|
||||
for role in sorted(set(roles) - ROLES, key=repr):
|
||||
errors.append(f"{cli_where}: unknown role {role!r}")
|
||||
for role, tiers in roles.items():
|
||||
role_where = f"{cli_where}.{role}"
|
||||
if role not in ROLES:
|
||||
continue
|
||||
if not isinstance(tiers, dict):
|
||||
errors.append(f"{role_where}: must be an object")
|
||||
continue
|
||||
if not tiers:
|
||||
errors.append(f"{role_where}: must not be empty")
|
||||
for tier in sorted(set(tiers) - TIERS, key=repr):
|
||||
errors.append(f"{role_where}: unknown tier {tier!r}")
|
||||
if role == "test" and "strong" in tiers:
|
||||
errors.append(f"{role_where}: Test cannot define a strong allowlist")
|
||||
for tier, models in tiers.items():
|
||||
tier_where = f"{role_where}.{tier}"
|
||||
if tier not in TIERS:
|
||||
continue
|
||||
if not isinstance(models, list) or not models:
|
||||
errors.append(f"{tier_where}: must be a non-empty model list")
|
||||
continue
|
||||
seen: set[str] = set()
|
||||
for index, model in enumerate(models):
|
||||
item_where = f"{tier_where}[{index}]"
|
||||
if not isinstance(model, str) or MODEL_ID_RE.fullmatch(model) is None:
|
||||
errors.append(f"{item_where}: must be a safe model ID")
|
||||
elif model in seen:
|
||||
errors.append(f"{item_where}: duplicate model {model!r}")
|
||||
else:
|
||||
seen.add(model)
|
||||
return errors
|
||||
|
||||
|
||||
def _allowed_models(
|
||||
allowlist: Any,
|
||||
cli: Any,
|
||||
role: Any,
|
||||
tier: Any,
|
||||
) -> list[str] | None:
|
||||
if not isinstance(allowlist, dict):
|
||||
return None
|
||||
roles = allowlist.get(cli)
|
||||
if not isinstance(roles, dict):
|
||||
return None
|
||||
tiers = roles.get(role)
|
||||
if not isinstance(tiers, dict):
|
||||
return None
|
||||
models = tiers.get(tier)
|
||||
return models if isinstance(models, list) else None
|
||||
|
||||
|
||||
def validate_orchestration(
|
||||
orchestration: Any,
|
||||
*,
|
||||
where: str = "project.orchestration",
|
||||
) -> list[str]:
|
||||
"""Validate the complete strict routing configuration."""
|
||||
|
||||
if not isinstance(orchestration, dict):
|
||||
return [f"{where}: must be an object"]
|
||||
|
||||
errors = _unknown_fields(orchestration, ORCHESTRATION_FIELDS, where)
|
||||
errors.extend(_missing_fields(orchestration, ORCHESTRATION_FIELDS, where))
|
||||
|
||||
profile_version = orchestration.get("profileVersion")
|
||||
mode = orchestration.get("mode")
|
||||
allowed_worktrees = orchestration.get("allowedWorktrees")
|
||||
allowlist = orchestration.get("modelAllowlist")
|
||||
profiles = orchestration.get("profiles")
|
||||
defaults = orchestration.get("defaults")
|
||||
|
||||
if profile_version != PROFILE_VERSION or isinstance(profile_version, bool):
|
||||
errors.append(f"{where}.profileVersion: must be {PROFILE_VERSION}")
|
||||
if not isinstance(mode, str) or mode not in ORCHESTRATION_MODES:
|
||||
errors.append(f"{where}.mode: must be orca/manual")
|
||||
|
||||
if not isinstance(allowed_worktrees, list):
|
||||
errors.append(f"{where}.allowedWorktrees: must be a list")
|
||||
else:
|
||||
if mode == "orca" and not allowed_worktrees:
|
||||
errors.append(f"{where}.allowedWorktrees: Orca mode requires at least one path")
|
||||
seen_worktrees: set[str] = set()
|
||||
for index, worktree in enumerate(allowed_worktrees):
|
||||
item_where = f"{where}.allowedWorktrees[{index}]"
|
||||
if not _is_absolute_safe_path(worktree):
|
||||
errors.append(f"{item_where}: must be a safe absolute path other than root")
|
||||
elif worktree in seen_worktrees:
|
||||
errors.append(f"{item_where}: duplicate worktree {worktree!r}")
|
||||
else:
|
||||
seen_worktrees.add(worktree)
|
||||
|
||||
errors.extend(_validate_model_allowlist(allowlist, f"{where}.modelAllowlist"))
|
||||
|
||||
valid_profiles: dict[str, dict[str, Any]] = {}
|
||||
if not isinstance(profiles, dict):
|
||||
errors.append(f"{where}.profiles: must be an object")
|
||||
else:
|
||||
if mode == "orca" and not profiles:
|
||||
errors.append(f"{where}.profiles: Orca mode requires profiles")
|
||||
for profile_id, profile in profiles.items():
|
||||
profile_where = f"{where}.profiles.{profile_id}"
|
||||
if not isinstance(profile_id, str) or PROFILE_ID_RE.fullmatch(profile_id) is None:
|
||||
errors.append(f"{where}.profiles: invalid profile ID {profile_id!r}")
|
||||
continue
|
||||
profile_errors = validate_profile(profile, where=profile_where)
|
||||
errors.extend(profile_errors)
|
||||
if profile_errors or not isinstance(profile, dict):
|
||||
continue
|
||||
valid_profiles[profile_id] = profile
|
||||
models = _allowed_models(
|
||||
allowlist,
|
||||
profile.get("cli"),
|
||||
profile.get("role"),
|
||||
profile.get("tier"),
|
||||
)
|
||||
if profile.get("model") not in (models or []):
|
||||
errors.append(
|
||||
f"{profile_where}.model: {profile.get('model')!r} is not allowed "
|
||||
"for its cli/role/tier"
|
||||
)
|
||||
|
||||
if not isinstance(defaults, dict):
|
||||
errors.append(f"{where}.defaults: must be an object")
|
||||
else:
|
||||
for default_key in sorted(set(defaults) - DEFAULT_KEYS, key=repr):
|
||||
errors.append(f"{where}.defaults: unknown key {default_key!r}")
|
||||
if mode == "orca":
|
||||
for role in sorted(ROLES - set(defaults)):
|
||||
errors.append(f"{where}.defaults: missing role {role!r}")
|
||||
for default_key, profile_id in defaults.items():
|
||||
default_where = f"{where}.defaults.{default_key}"
|
||||
if default_key not in DEFAULT_KEYS:
|
||||
continue
|
||||
if not isinstance(profile_id, str) or PROFILE_ID_RE.fullmatch(profile_id) is None:
|
||||
errors.append(f"{default_where}: must be a profile ID")
|
||||
continue
|
||||
profile = valid_profiles.get(profile_id)
|
||||
if profile is None:
|
||||
errors.append(f"{default_where}: unknown or invalid profile {profile_id!r}")
|
||||
continue
|
||||
expected_role = "developer" if default_key == "developerUpgraded" else default_key
|
||||
expected_tier = "strong" if default_key == "developerUpgraded" else "standard"
|
||||
if profile.get("role") != expected_role:
|
||||
errors.append(f"{default_where}: profile role must be {expected_role}")
|
||||
if profile.get("tier") != expected_tier:
|
||||
errors.append(
|
||||
f"{default_where}: default profile must use {expected_tier} tier"
|
||||
)
|
||||
if profile.get("permissionMode") not in PERMISSION_MODES:
|
||||
errors.append(f"{default_where}: default profile has unsafe permissions")
|
||||
|
||||
return errors
|
||||
|
||||
|
||||
def profile_hash(
|
||||
profile: dict[str, Any],
|
||||
*,
|
||||
profile_version: int = PROFILE_VERSION,
|
||||
) -> str:
|
||||
"""Return the canonical hash of a valid strict profile."""
|
||||
|
||||
errors = validate_profile(profile)
|
||||
if errors:
|
||||
raise ValueError("invalid profile: " + "; ".join(errors))
|
||||
if (
|
||||
not isinstance(profile_version, int)
|
||||
or isinstance(profile_version, bool)
|
||||
or profile_version < 1
|
||||
):
|
||||
raise ValueError("profile_version must be a positive integer")
|
||||
return canonical_sha256(
|
||||
{
|
||||
"profileVersion": profile_version,
|
||||
"profile": profile,
|
||||
}
|
||||
)
|
||||
|
||||
|
||||
def render_worker_argv(
|
||||
profile: dict[str, Any],
|
||||
executable: str,
|
||||
worktree: str,
|
||||
) -> list[str]:
|
||||
"""Render the only argv shapes allowed by routing profile version 1."""
|
||||
|
||||
errors = validate_profile(profile)
|
||||
if errors:
|
||||
raise ValueError("invalid profile: " + "; ".join(errors))
|
||||
if not _is_absolute_safe_path(executable):
|
||||
raise ValueError("executable must be a safe absolute path other than root")
|
||||
if Path(executable).name != profile["cli"]:
|
||||
raise ValueError("executable basename must match profile.cli")
|
||||
if not _is_absolute_safe_path(worktree):
|
||||
raise ValueError("worktree must be a safe absolute path other than root")
|
||||
|
||||
model = profile["model"]
|
||||
permission = profile["permissionMode"]
|
||||
if profile["cli"] == "codex":
|
||||
return [
|
||||
executable,
|
||||
"--strict-config",
|
||||
"--model",
|
||||
model,
|
||||
"--config",
|
||||
f"model_reasoning_effort={profile['reasoningEffort']}",
|
||||
"--sandbox",
|
||||
permission,
|
||||
"--ask-for-approval",
|
||||
"never",
|
||||
"--cd",
|
||||
worktree,
|
||||
]
|
||||
|
||||
argv = [executable, "--model", model]
|
||||
if permission == "read-only":
|
||||
argv.extend(["--mode", "plan"])
|
||||
else:
|
||||
argv.append("--auto-review")
|
||||
argv.extend(["--sandbox", "enabled", "--workspace", worktree])
|
||||
return argv
|
||||
|
||||
|
||||
def receipt_hash(receipt: dict[str, Any]) -> str:
|
||||
"""Hash every receipt field except the self-referential ``receiptHash``."""
|
||||
|
||||
if not isinstance(receipt, dict):
|
||||
raise ValueError("receipt must be an object")
|
||||
payload = {key: value for key, value in receipt.items() if key != "receiptHash"}
|
||||
return canonical_sha256(payload)
|
||||
|
||||
|
||||
def _validate_created_for(value: Any, where: str) -> list[str]:
|
||||
if not isinstance(value, dict):
|
||||
return [f"{where}: must be an object"]
|
||||
errors = _unknown_fields(value, CREATED_FOR_FIELDS, where)
|
||||
errors.extend(_missing_fields(value, CREATED_FOR_FIELDS, where))
|
||||
task_id = value.get("taskId")
|
||||
attempt_id = value.get("attemptId")
|
||||
if not isinstance(task_id, str) or TASK_ID_RE.fullmatch(task_id) is None:
|
||||
errors.append(f"{where}.taskId: must be a safe task ID")
|
||||
if not isinstance(attempt_id, str) or ATTEMPT_ID_RE.fullmatch(attempt_id) is None:
|
||||
errors.append(f"{where}.attemptId: must use <task-id>-A1..A3")
|
||||
elif isinstance(task_id, str) and not attempt_id.startswith(f"{task_id}-A"):
|
||||
errors.append(f"{where}.attemptId: must belong to taskId")
|
||||
role = value.get("role")
|
||||
if not isinstance(role, str) or role not in ROLES:
|
||||
errors.append(f"{where}.role: must be developer/test")
|
||||
return errors
|
||||
|
||||
|
||||
def _validate_worktree_snapshot(value: Any, where: str) -> list[str]:
|
||||
if not isinstance(value, dict):
|
||||
return [f"{where}: must be an object"]
|
||||
errors = _unknown_fields(value, WORKTREE_FIELDS, where)
|
||||
errors.extend(_missing_fields(value, WORKTREE_FIELDS, where))
|
||||
for field in ("path", "gitCommonDir"):
|
||||
if not _is_absolute_safe_path(value.get(field)):
|
||||
errors.append(f"{where}.{field}: must be a safe absolute path other than root")
|
||||
for field in ("device", "gitCommonDevice"):
|
||||
if not _is_nonnegative_int(value.get(field)):
|
||||
errors.append(f"{where}.{field}: must be a non-negative integer")
|
||||
for field in ("inode", "gitCommonInode"):
|
||||
if not _is_positive_int(value.get(field)):
|
||||
errors.append(f"{where}.{field}: must be a positive integer")
|
||||
return errors
|
||||
|
||||
|
||||
def _validate_requested(value: Any, where: str) -> list[str]:
|
||||
if not isinstance(value, dict):
|
||||
return [f"{where}: must be an object"]
|
||||
errors = _unknown_fields(value, REQUESTED_FIELDS, where)
|
||||
errors.extend(_missing_fields(value, REQUESTED_FIELDS, where))
|
||||
cli = value.get("cli")
|
||||
tier = value.get("tier")
|
||||
permission = value.get("permissionMode")
|
||||
if not isinstance(cli, str) or cli not in CLIS:
|
||||
errors.append(f"{where}.cli: must be codex/cursor-agent")
|
||||
if not isinstance(tier, str) or tier not in TIERS:
|
||||
errors.append(f"{where}.tier: must be standard/strong")
|
||||
model = value.get("model")
|
||||
if not isinstance(model, str) or MODEL_ID_RE.fullmatch(model) is None:
|
||||
errors.append(f"{where}.model: must be a safe model ID")
|
||||
effort = value.get("reasoningEffort")
|
||||
if cli == "codex" and (
|
||||
not isinstance(effort, str) or effort not in REASONING_EFFORTS
|
||||
):
|
||||
errors.append(f"{where}.reasoningEffort: invalid Codex effort")
|
||||
if cli == "cursor-agent" and effort is not None:
|
||||
errors.append(f"{where}.reasoningEffort: Cursor requires null")
|
||||
if not isinstance(permission, str) or permission not in PERMISSION_MODES:
|
||||
errors.append(f"{where}.permissionMode: must be read-only/workspace-write")
|
||||
executable = value.get("executable")
|
||||
if not _is_absolute_safe_path(executable):
|
||||
errors.append(f"{where}.executable: must be a safe absolute path")
|
||||
elif isinstance(cli, str) and cli in CLIS and Path(executable).name != cli:
|
||||
errors.append(f"{where}.executable: basename must match cli")
|
||||
if not _is_nonnegative_int(value.get("executableDevice")):
|
||||
errors.append(f"{where}.executableDevice: must be a non-negative integer")
|
||||
if not _is_positive_int(value.get("executableInode")):
|
||||
errors.append(f"{where}.executableInode: must be a positive integer")
|
||||
if not _is_nonempty_text(value.get("cliVersion"), max_length=256):
|
||||
errors.append(f"{where}.cliVersion: must be non-empty single-line text")
|
||||
argv = value.get("argv")
|
||||
if (
|
||||
not isinstance(argv, list)
|
||||
or len(argv) < 2
|
||||
or any(not isinstance(arg, str) for arg in argv)
|
||||
):
|
||||
errors.append(f"{where}.argv: must be a string array with at least 2 items")
|
||||
argv_hash = value.get("argvHash")
|
||||
if not isinstance(argv_hash, str) or SHA256_RE.fullmatch(argv_hash) is None:
|
||||
errors.append(f"{where}.argvHash: must be a canonical sha256 hex digest")
|
||||
elif isinstance(argv, list) and all(isinstance(arg, str) for arg in argv):
|
||||
if argv_hash != canonical_sha256(argv):
|
||||
errors.append(f"{where}.argvHash: does not match argv")
|
||||
if value.get("environmentPolicy") != "per-cli-allowlist-v1":
|
||||
errors.append(
|
||||
f"{where}.environmentPolicy: must be 'per-cli-allowlist-v1'"
|
||||
)
|
||||
return errors
|
||||
|
||||
|
||||
def _validate_binding(value: Any, where: str) -> list[str]:
|
||||
if not isinstance(value, dict):
|
||||
return [f"{where}: must be an object"]
|
||||
errors = _unknown_fields(value, BINDING_FIELDS, where)
|
||||
errors.extend(_missing_fields(value, BINDING_FIELDS, where))
|
||||
if value.get("orchestrator") != "orca":
|
||||
errors.append(f"{where}.orchestrator: must be orca")
|
||||
for field in ("runtimeId", "handle", "incarnationId"):
|
||||
if not _is_nonempty_text(value.get(field), max_length=512):
|
||||
errors.append(f"{where}.{field}: must be non-empty single-line text")
|
||||
if not _is_absolute_safe_path(value.get("observedWorktreePath")):
|
||||
errors.append(f"{where}.observedWorktreePath: must be a safe absolute path")
|
||||
for field in ("connected", "writable"):
|
||||
if value.get(field) is not True:
|
||||
errors.append(f"{where}.{field}: must be true")
|
||||
if not _is_timestamp(value.get("boundAt")):
|
||||
errors.append(f"{where}.boundAt: must be a timezone-aware ISO 8601 timestamp")
|
||||
return errors
|
||||
|
||||
|
||||
def validate_worker_receipt(
|
||||
receipt: Any,
|
||||
*,
|
||||
orchestration: dict[str, Any] | None = None,
|
||||
task_ids: set[str] | None = None,
|
||||
where: str = "workerReceipt",
|
||||
) -> list[str]:
|
||||
"""Validate one audit receipt's structure/checksums and routing references.
|
||||
|
||||
This is not origin authentication: ``receiptHash`` is unkeyed, so callers
|
||||
must never use this result alone to authorize reuse of an old terminal.
|
||||
"""
|
||||
|
||||
if not isinstance(receipt, dict):
|
||||
return [f"{where}: must be an object"]
|
||||
errors = _unknown_fields(receipt, RECEIPT_FIELDS, where)
|
||||
errors.extend(_missing_fields(receipt, RECEIPT_FIELDS, where))
|
||||
|
||||
version = receipt.get("receiptVersion")
|
||||
if version != RECEIPT_VERSION or isinstance(version, bool):
|
||||
errors.append(f"{where}.receiptVersion: must be {RECEIPT_VERSION}")
|
||||
for field in ("id", "launchId", "profileId"):
|
||||
value = receipt.get(field)
|
||||
matcher = {
|
||||
"id": RECEIPT_ID_RE,
|
||||
"launchId": LAUNCH_ID_RE,
|
||||
"profileId": PROFILE_ID_RE,
|
||||
}[field]
|
||||
if not isinstance(value, str) or matcher.fullmatch(value) is None:
|
||||
errors.append(f"{where}.{field}: invalid identifier")
|
||||
for field in ("profileHash", "launchFingerprint", "receiptHash"):
|
||||
value = receipt.get(field)
|
||||
if not isinstance(value, str) or SHA256_RE.fullmatch(value) is None:
|
||||
errors.append(f"{where}.{field}: must be a canonical sha256 hex digest")
|
||||
slot = receipt.get("slot")
|
||||
if not isinstance(slot, int) or isinstance(slot, bool) or not 1 <= slot <= 99:
|
||||
errors.append(f"{where}.slot: must be an integer from 1 to 99")
|
||||
receipt_id = receipt.get("id")
|
||||
launch_id = receipt.get("launchId")
|
||||
if (
|
||||
isinstance(receipt_id, str)
|
||||
and RECEIPT_ID_RE.fullmatch(receipt_id)
|
||||
and isinstance(launch_id, str)
|
||||
and LAUNCH_ID_RE.fullmatch(launch_id)
|
||||
and receipt_id != f"WR-{launch_id}"
|
||||
):
|
||||
errors.append(f"{where}.id: must equal 'WR-' + launchId")
|
||||
|
||||
created_for = receipt.get("createdFor")
|
||||
worktree = receipt.get("worktree")
|
||||
requested = receipt.get("requested")
|
||||
binding = receipt.get("binding")
|
||||
errors.extend(_validate_created_for(created_for, f"{where}.createdFor"))
|
||||
errors.extend(_validate_worktree_snapshot(worktree, f"{where}.worktree"))
|
||||
errors.extend(_validate_requested(requested, f"{where}.requested"))
|
||||
errors.extend(_validate_binding(binding, f"{where}.binding"))
|
||||
if not _is_timestamp(receipt.get("createdAt")):
|
||||
errors.append(f"{where}.createdAt: must be a timezone-aware ISO 8601 timestamp")
|
||||
|
||||
if isinstance(created_for, dict) and task_ids is not None:
|
||||
task_id = created_for.get("taskId")
|
||||
if isinstance(task_id, str) and task_id not in task_ids:
|
||||
errors.append(f"{where}.createdFor.taskId: unknown task {task_id!r}")
|
||||
|
||||
profile: dict[str, Any] | None = None
|
||||
if orchestration is not None and not isinstance(orchestration, dict):
|
||||
errors.append(f"{where}: orchestration must be an object")
|
||||
elif isinstance(orchestration, dict):
|
||||
profiles = orchestration.get("profiles")
|
||||
profile_id = receipt.get("profileId")
|
||||
candidate = profiles.get(profile_id) if (
|
||||
isinstance(profiles, dict) and isinstance(profile_id, str)
|
||||
) else None
|
||||
if isinstance(candidate, dict):
|
||||
profile = candidate
|
||||
else:
|
||||
errors.append(f"{where}.profileId: unknown profile {profile_id!r}")
|
||||
allowed = orchestration.get("allowedWorktrees")
|
||||
if isinstance(worktree, dict) and isinstance(allowed, list):
|
||||
if worktree.get("path") not in allowed:
|
||||
errors.append(f"{where}.worktree.path: is not in allowedWorktrees")
|
||||
|
||||
if profile is not None:
|
||||
try:
|
||||
expected_profile_hash = profile_hash(
|
||||
profile,
|
||||
profile_version=orchestration.get(
|
||||
"profileVersion",
|
||||
PROFILE_VERSION,
|
||||
),
|
||||
)
|
||||
except ValueError:
|
||||
errors.append(f"{where}.profileId: referenced profile is invalid")
|
||||
else:
|
||||
if receipt.get("profileHash") != expected_profile_hash:
|
||||
errors.append(f"{where}.profileHash: does not match profile")
|
||||
|
||||
if isinstance(created_for, dict) and created_for.get("role") != profile.get("role"):
|
||||
errors.append(f"{where}.createdFor.role: does not match profile")
|
||||
if isinstance(requested, dict):
|
||||
for field in (
|
||||
"cli",
|
||||
"tier",
|
||||
"model",
|
||||
"reasoningEffort",
|
||||
"permissionMode",
|
||||
):
|
||||
if requested.get(field) != profile.get(field):
|
||||
errors.append(f"{where}.requested.{field}: does not match profile")
|
||||
executable = requested.get("executable")
|
||||
worktree_path = worktree.get("path") if isinstance(worktree, dict) else None
|
||||
if isinstance(executable, str) and isinstance(worktree_path, str):
|
||||
try:
|
||||
expected_argv = render_worker_argv(profile, executable, worktree_path)
|
||||
except ValueError:
|
||||
errors.append(f"{where}.requested.argv: cannot render referenced profile")
|
||||
else:
|
||||
if requested.get("argv") != expected_argv:
|
||||
errors.append(f"{where}.requested.argv: does not match exact renderer")
|
||||
|
||||
if isinstance(binding, dict) and isinstance(worktree, dict):
|
||||
if binding.get("observedWorktreePath") != worktree.get("path"):
|
||||
errors.append(f"{where}.binding.observedWorktreePath: does not match worktree.path")
|
||||
|
||||
if (
|
||||
isinstance(created_for, dict)
|
||||
and isinstance(worktree, dict)
|
||||
and isinstance(requested, dict)
|
||||
):
|
||||
try:
|
||||
expected_fingerprint = canonical_sha256(
|
||||
{
|
||||
"protocolVersion": LAUNCH_PROTOCOL_VERSION,
|
||||
"backend": "orca",
|
||||
"profileId": receipt.get("profileId"),
|
||||
"profileHash": receipt.get("profileHash"),
|
||||
"createdFor": created_for,
|
||||
"worktree": worktree,
|
||||
"requested": requested,
|
||||
"slot": slot,
|
||||
}
|
||||
)
|
||||
except ValueError:
|
||||
errors.append(f"{where}.launchFingerprint: cannot hash launch facts")
|
||||
else:
|
||||
if receipt.get("launchFingerprint") != expected_fingerprint:
|
||||
errors.append(
|
||||
f"{where}.launchFingerprint: does not match launch facts"
|
||||
)
|
||||
|
||||
try:
|
||||
expected_receipt_hash = receipt_hash(receipt)
|
||||
except ValueError:
|
||||
errors.append(f"{where}: must contain canonical JSON data")
|
||||
else:
|
||||
if receipt.get("receiptHash") != expected_receipt_hash:
|
||||
errors.append(f"{where}.receiptHash: does not match receipt")
|
||||
return errors
|
||||
|
||||
|
||||
def validate_worker_receipts(
|
||||
receipts: Any,
|
||||
orchestration: dict[str, Any] | None = None,
|
||||
*,
|
||||
task_ids: set[str] | None = None,
|
||||
where: str = "workerReceipts",
|
||||
) -> list[str]:
|
||||
"""Validate the top-level receipt list and reject duplicate identities."""
|
||||
|
||||
if not isinstance(receipts, list):
|
||||
return [f"{where}: must be a list"]
|
||||
errors: list[str] = []
|
||||
seen_ids: set[str] = set()
|
||||
seen_launch_ids: set[str] = set()
|
||||
for index, receipt in enumerate(receipts):
|
||||
receipt_where = f"{where}[{index}]"
|
||||
errors.extend(
|
||||
validate_worker_receipt(
|
||||
receipt,
|
||||
orchestration=orchestration,
|
||||
task_ids=task_ids,
|
||||
where=receipt_where,
|
||||
)
|
||||
)
|
||||
if not isinstance(receipt, dict):
|
||||
continue
|
||||
receipt_id = receipt.get("id")
|
||||
if isinstance(receipt_id, str):
|
||||
if receipt_id in seen_ids:
|
||||
errors.append(f"{receipt_where}.id: duplicate receipt ID {receipt_id!r}")
|
||||
seen_ids.add(receipt_id)
|
||||
launch_id = receipt.get("launchId")
|
||||
if isinstance(launch_id, str):
|
||||
if launch_id in seen_launch_ids:
|
||||
errors.append(f"{receipt_where}.launchId: duplicate launch ID {launch_id!r}")
|
||||
seen_launch_ids.add(launch_id)
|
||||
return errors
|
||||
|
||||
|
||||
def _validate_dispatch_links(
|
||||
tasks: Any,
|
||||
receipts: Any,
|
||||
orchestration: Any,
|
||||
) -> list[str]:
|
||||
"""Cross-link role dispatch records to persisted audit receipts."""
|
||||
|
||||
if not isinstance(tasks, list):
|
||||
return []
|
||||
receipt_by_id: dict[str, dict[str, Any]] = {}
|
||||
if isinstance(receipts, list):
|
||||
for receipt in receipts:
|
||||
if not isinstance(receipt, dict):
|
||||
continue
|
||||
receipt_id = receipt.get("id")
|
||||
if isinstance(receipt_id, str) and receipt_id not in receipt_by_id:
|
||||
receipt_by_id[receipt_id] = receipt
|
||||
profiles = orchestration.get("profiles") if isinstance(orchestration, dict) else None
|
||||
|
||||
errors: list[str] = []
|
||||
for task_index, task in enumerate(tasks):
|
||||
if not isinstance(task, dict):
|
||||
continue
|
||||
ack_task_id = task.get("id")
|
||||
dispatch = task.get("dispatch")
|
||||
if not isinstance(dispatch, dict):
|
||||
continue
|
||||
for role in sorted(ROLES):
|
||||
if role not in dispatch:
|
||||
continue
|
||||
role_dispatch = dispatch.get(role)
|
||||
where = f"tasks[{task_index}].dispatch.{role}"
|
||||
if not isinstance(role_dispatch, dict):
|
||||
errors.append(f"{where}: must be an object")
|
||||
continue
|
||||
errors.extend(_unknown_fields(role_dispatch, ROLE_DISPATCH_FIELDS, where))
|
||||
errors.extend(_missing_fields(role_dispatch, ROLE_DISPATCH_FIELDS, where))
|
||||
|
||||
profile_id = role_dispatch.get("profileId")
|
||||
if profile_id is not None:
|
||||
if not isinstance(profile_id, str) or PROFILE_ID_RE.fullmatch(profile_id) is None:
|
||||
errors.append(f"{where}.profileId: must be null or a profile ID")
|
||||
else:
|
||||
profile = profiles.get(profile_id) if isinstance(profiles, dict) else None
|
||||
if not isinstance(profile, dict):
|
||||
errors.append(f"{where}.profileId: unknown profile {profile_id!r}")
|
||||
elif profile.get("role") != role:
|
||||
errors.append(f"{where}.profileId: profile role must be {role}")
|
||||
|
||||
runtime_values: list[Any] = []
|
||||
for field in ("taskId", "dispatchId"):
|
||||
runtime_value = role_dispatch.get(field)
|
||||
runtime_values.append(runtime_value)
|
||||
if runtime_value is not None and not _is_nonempty_text(
|
||||
runtime_value,
|
||||
max_length=512,
|
||||
):
|
||||
errors.append(
|
||||
f"{where}.{field}: must be null or non-empty single-line text"
|
||||
)
|
||||
if (runtime_values[0] is None) != (runtime_values[1] is None):
|
||||
errors.append(
|
||||
f"{where}: taskId and dispatchId must both be null or both be set"
|
||||
)
|
||||
|
||||
receipt_id = role_dispatch.get("receiptId")
|
||||
attempt_id = role_dispatch.get("attemptId")
|
||||
current_task_attempts = {
|
||||
f"{ack_task_id}-A{round_number}" for round_number in range(1, 4)
|
||||
}
|
||||
if attempt_id is not None:
|
||||
if (
|
||||
not isinstance(attempt_id, str)
|
||||
or ATTEMPT_ID_RE.fullmatch(attempt_id) is None
|
||||
):
|
||||
errors.append(
|
||||
f"{where}.attemptId: must be null or use <task-id>-A1..A3"
|
||||
)
|
||||
elif (
|
||||
isinstance(ack_task_id, str)
|
||||
and attempt_id not in current_task_attempts
|
||||
):
|
||||
errors.append(
|
||||
f"{where}.attemptId: must belong to current ACK task {ack_task_id!r}"
|
||||
)
|
||||
if receipt_id is None:
|
||||
if attempt_id is not None:
|
||||
errors.append(
|
||||
f"{where}.attemptId: must be null when receiptId is null"
|
||||
)
|
||||
if any(value is not None for value in runtime_values):
|
||||
errors.append(
|
||||
f"{where}.receiptId: is required before runtime dispatch IDs"
|
||||
)
|
||||
continue
|
||||
if attempt_id is None:
|
||||
errors.append(
|
||||
f"{where}.attemptId: is required when receiptId is set"
|
||||
)
|
||||
if not isinstance(receipt_id, str) or RECEIPT_ID_RE.fullmatch(receipt_id) is None:
|
||||
errors.append(f"{where}.receiptId: must be null or a receipt ID")
|
||||
continue
|
||||
receipt = receipt_by_id.get(receipt_id)
|
||||
if receipt is None:
|
||||
errors.append(f"{where}.receiptId: unknown receipt {receipt_id!r}")
|
||||
continue
|
||||
if receipt.get("profileId") != profile_id:
|
||||
errors.append(f"{where}.profileId: does not match referenced receipt")
|
||||
created_for = receipt.get("createdFor")
|
||||
receipt_task_id = (
|
||||
created_for.get("taskId") if isinstance(created_for, dict) else None
|
||||
)
|
||||
receipt_role = created_for.get("role") if isinstance(created_for, dict) else None
|
||||
receipt_attempt_id = (
|
||||
created_for.get("attemptId") if isinstance(created_for, dict) else None
|
||||
)
|
||||
if receipt_task_id != ack_task_id:
|
||||
errors.append(
|
||||
f"{where}.receiptId: referenced receipt task must be current "
|
||||
f"ACK task {ack_task_id!r}"
|
||||
)
|
||||
if receipt_role != role:
|
||||
errors.append(f"{where}.receiptId: referenced receipt role must be {role}")
|
||||
if receipt_attempt_id != attempt_id:
|
||||
errors.append(
|
||||
f"{where}.attemptId: does not match referenced receipt"
|
||||
)
|
||||
return errors
|
||||
|
||||
|
||||
def validate_routing_document(data: Any) -> list[str]:
|
||||
"""Validate routing and receipts embedded in an ACK tasks document."""
|
||||
|
||||
if not isinstance(data, dict):
|
||||
return ["<root>: must be an object"]
|
||||
project = data.get("project")
|
||||
if not isinstance(project, dict):
|
||||
return ["project: must be an object"]
|
||||
if "orchestration" not in project:
|
||||
return ["project.orchestration: is required"]
|
||||
orchestration = project.get("orchestration")
|
||||
errors = validate_orchestration(orchestration)
|
||||
|
||||
task_ids: set[str] = set()
|
||||
tasks = data.get("tasks")
|
||||
if isinstance(tasks, list):
|
||||
for task in tasks:
|
||||
if isinstance(task, dict) and isinstance(task.get("id"), str):
|
||||
task_ids.add(task["id"])
|
||||
|
||||
receipts = data.get("workerReceipts")
|
||||
if "workerReceipts" not in data:
|
||||
errors.append("workerReceipts: is required")
|
||||
else:
|
||||
errors.extend(
|
||||
validate_worker_receipts(
|
||||
receipts,
|
||||
orchestration if isinstance(orchestration, dict) else None,
|
||||
task_ids=task_ids,
|
||||
)
|
||||
)
|
||||
errors.extend(_validate_dispatch_links(tasks, receipts, orchestration))
|
||||
if isinstance(orchestration, dict) and orchestration.get("mode") == "manual":
|
||||
receipts = data.get("workerReceipts")
|
||||
if isinstance(receipts, list) and receipts:
|
||||
errors.append("workerReceipts: manual orchestration requires an empty list")
|
||||
return errors
|
||||
|
||||
|
||||
# Short aliases for callers that treat this module as a builtin validator.
|
||||
validate_routing = validate_orchestration
|
||||
validate_receipts = validate_worker_receipts
|
||||
validate_builtin = validate_routing_document
|
||||
|
||||
|
||||
__all__ = [
|
||||
"PROFILE_VERSION",
|
||||
"RECEIPT_VERSION",
|
||||
"LAUNCH_PROTOCOL_VERSION",
|
||||
"MAX_ROUNDS",
|
||||
"canonical_sha256",
|
||||
"profile_hash",
|
||||
"receipt_hash",
|
||||
"render_worker_argv",
|
||||
"validate_profile",
|
||||
"validate_orchestration",
|
||||
"validate_worker_receipt",
|
||||
"validate_worker_receipts",
|
||||
"validate_routing_document",
|
||||
"validate_routing",
|
||||
"validate_receipts",
|
||||
"validate_builtin",
|
||||
]
|
||||
@@ -0,0 +1,686 @@
|
||||
#!/usr/bin/env python3
|
||||
"""ACK YAML 的零依赖、fail-closed 子集解析器。
|
||||
|
||||
这不是通用 YAML 实现。它只覆盖 ACK 状态文件所需的 mapping、
|
||||
sequence、flow collection、标量和 ``>`` / ``|`` block scalar。锚点、
|
||||
alias、tag、多文档和其它未实现语法会显式失败，不会猜测或静默误解析。
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import json
|
||||
import re
|
||||
from dataclasses import dataclass
|
||||
from typing import Any
|
||||
|
||||
|
||||
class YamlSubsetError(ValueError):
|
||||
"""YAML 超出 ACK 子集或语法无效。"""
|
||||
|
||||
|
||||
class DuplicateKeyError(ValueError):
|
||||
"""JSON/YAML mapping 包含重复键。"""
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class _Line:
|
||||
number: int
|
||||
indent: int
|
||||
content: str
|
||||
|
||||
|
||||
_DECIMAL_INT_RE = re.compile(r"[-+]?(?:0|[1-9][0-9]*)\Z")
|
||||
_AMBIGUOUS_NUMBER_RE = re.compile(
|
||||
r"[-+]?(?:"
|
||||
r"[0-9][0-9_]*\.[0-9_]*(?:[eE][-+]?[0-9]+)?|"
|
||||
r"[0-9][0-9_]*(?:[eE][-+]?[0-9]+)|"
|
||||
r"0[xX][0-9a-fA-F_]+|0[oO][0-7_]+|0[bB][01_]+|"
|
||||
r"0[0-9_]+|[0-9][0-9_]*:[0-9_:]+"
|
||||
r")\Z"
|
||||
)
|
||||
_PLAIN_KEY_FORBIDDEN_RE = re.compile(r"[\[\]{},#]")
|
||||
_ANCHOR_OR_ALIAS_RE = re.compile(
|
||||
r"(?:^|\s)[&*][A-Za-z0-9_-]+(?:\s|$)"
|
||||
)
|
||||
|
||||
|
||||
def load_json_unique(content: str) -> Any:
|
||||
"""Parse JSON while rejecting duplicate object keys at every depth."""
|
||||
|
||||
def unique_object(pairs: list[tuple[str, Any]]) -> dict[str, Any]:
|
||||
result: dict[str, Any] = {}
|
||||
for key, value in pairs:
|
||||
if key in result:
|
||||
raise DuplicateKeyError(f"JSON 存在重复键 {key!r}")
|
||||
result[key] = value
|
||||
return result
|
||||
|
||||
return json.loads(content, object_pairs_hook=unique_object)
|
||||
|
||||
|
||||
def make_unique_pyyaml_loader(yaml_module: Any) -> type:
|
||||
"""Build a SafeLoader that rejects duplicate keys and graph features.
|
||||
|
||||
ACK documents are trees. Anchors/aliases can introduce shared identity or
|
||||
cycles, which are unnecessary here and make recursive validation unsafe.
|
||||
Explicit tags are also outside the fallback grammar, so both code paths
|
||||
reject them consistently.
|
||||
"""
|
||||
|
||||
class UniqueKeySafeLoader(yaml_module.SafeLoader): # type: ignore[misc]
|
||||
def compose_node(self, parent: Any, index: Any) -> Any:
|
||||
if self.check_event(yaml_module.events.AliasEvent):
|
||||
event = self.peek_event()
|
||||
raise yaml_module.YAMLError(
|
||||
f"ACK YAML 不支持 alias: *{event.anchor}"
|
||||
)
|
||||
event = self.peek_event()
|
||||
if getattr(event, "anchor", None) is not None:
|
||||
raise yaml_module.YAMLError(
|
||||
f"ACK YAML 不支持 anchor: &{event.anchor}"
|
||||
)
|
||||
if getattr(event, "tag", None) is not None:
|
||||
raise yaml_module.YAMLError(
|
||||
f"ACK YAML 不支持显式 tag: {event.tag}"
|
||||
)
|
||||
return super().compose_node(parent, index)
|
||||
|
||||
def construct_unique_mapping(
|
||||
loader: Any,
|
||||
node: Any,
|
||||
deep: bool = False,
|
||||
) -> dict[str, Any]:
|
||||
for key_node, _ in node.value:
|
||||
if (
|
||||
getattr(key_node, "tag", None) == "tag:yaml.org,2002:merge"
|
||||
or getattr(key_node, "value", None) == "<<"
|
||||
):
|
||||
raise yaml_module.constructor.ConstructorError(
|
||||
"while constructing an ACK mapping",
|
||||
node.start_mark,
|
||||
"merge keys are not supported",
|
||||
key_node.start_mark,
|
||||
)
|
||||
loader.flatten_mapping(node)
|
||||
mapping: dict[str, Any] = {}
|
||||
for key_node, value_node in node.value:
|
||||
key = loader.construct_object(key_node, deep=deep)
|
||||
if not isinstance(key, str):
|
||||
raise yaml_module.constructor.ConstructorError(
|
||||
"while constructing an ACK mapping",
|
||||
node.start_mark,
|
||||
"mapping key must be a string",
|
||||
key_node.start_mark,
|
||||
)
|
||||
if key == "<<":
|
||||
raise yaml_module.constructor.ConstructorError(
|
||||
"while constructing an ACK mapping",
|
||||
node.start_mark,
|
||||
"merge keys are not supported",
|
||||
key_node.start_mark,
|
||||
)
|
||||
if key in mapping:
|
||||
raise yaml_module.constructor.ConstructorError(
|
||||
"while constructing an ACK mapping",
|
||||
node.start_mark,
|
||||
f"found duplicate key {key!r}",
|
||||
key_node.start_mark,
|
||||
)
|
||||
mapping[key] = loader.construct_object(value_node, deep=deep)
|
||||
return mapping
|
||||
|
||||
UniqueKeySafeLoader.add_constructor(
|
||||
yaml_module.resolver.BaseResolver.DEFAULT_MAPPING_TAG,
|
||||
construct_unique_mapping,
|
||||
)
|
||||
return UniqueKeySafeLoader
|
||||
|
||||
|
||||
def load_yaml_subset(content: str) -> Any:
|
||||
"""Parse the deliberately small YAML subset used by ACK files."""
|
||||
|
||||
return _SubsetParser(content).parse()
|
||||
|
||||
|
||||
class _SubsetParser:
|
||||
def __init__(self, content: str) -> None:
|
||||
if content.startswith("\ufeff"):
|
||||
content = content[1:]
|
||||
if "\t" in content:
|
||||
raise YamlSubsetError("ACK YAML 子集不支持 Tab，请使用空格")
|
||||
self.lines = [
|
||||
_Line(number, len(raw) - len(raw.lstrip(" ")), raw.lstrip(" "))
|
||||
for number, raw in enumerate(content.splitlines(), start=1)
|
||||
]
|
||||
self.index = 0
|
||||
|
||||
def parse(self) -> Any:
|
||||
self._skip_insignificant()
|
||||
if self.index >= len(self.lines):
|
||||
return None
|
||||
first = self.lines[self.index]
|
||||
if first.indent != 0:
|
||||
self._error(first, "顶层不能缩进")
|
||||
value = self._parse_node(0)
|
||||
self._skip_insignificant()
|
||||
if self.index != len(self.lines):
|
||||
line = self.lines[self.index]
|
||||
self._error(line, "文档尾部存在无法解析的内容")
|
||||
return value
|
||||
|
||||
def _parse_node(self, indent: int) -> Any:
|
||||
self._skip_insignificant()
|
||||
if self.index >= len(self.lines):
|
||||
return None
|
||||
line = self.lines[self.index]
|
||||
if line.indent != indent:
|
||||
self._error(line, f"期望 {indent} 个空格的缩进")
|
||||
content = self._without_comment(line.content).rstrip()
|
||||
self._reject_document_syntax(content, line)
|
||||
if self._is_sequence_marker(content):
|
||||
return self._parse_sequence(indent)
|
||||
return self._parse_mapping(indent)
|
||||
|
||||
def _parse_mapping(self, indent: int) -> dict[str, Any]:
|
||||
result: dict[str, Any] = {}
|
||||
while True:
|
||||
self._skip_insignificant()
|
||||
if self.index >= len(self.lines):
|
||||
break
|
||||
line = self.lines[self.index]
|
||||
if line.indent < indent:
|
||||
break
|
||||
if line.indent > indent:
|
||||
self._error(line, "mapping 存在意外缩进")
|
||||
content = self._without_comment(line.content).rstrip()
|
||||
self._reject_document_syntax(content, line)
|
||||
if self._is_sequence_marker(content):
|
||||
break
|
||||
self.index += 1
|
||||
self._consume_mapping_entry(
|
||||
result,
|
||||
content,
|
||||
mapping_indent=indent,
|
||||
line=line,
|
||||
)
|
||||
return result
|
||||
|
||||
def _parse_sequence(self, indent: int) -> list[Any]:
|
||||
result: list[Any] = []
|
||||
while True:
|
||||
self._skip_insignificant()
|
||||
if self.index >= len(self.lines):
|
||||
break
|
||||
line = self.lines[self.index]
|
||||
if line.indent < indent:
|
||||
break
|
||||
if line.indent > indent:
|
||||
self._error(line, "sequence 存在意外缩进")
|
||||
content = self._without_comment(line.content).rstrip()
|
||||
self._reject_document_syntax(content, line)
|
||||
if not self._is_sequence_marker(content):
|
||||
break
|
||||
rest = content[1:].lstrip(" ")
|
||||
self.index += 1
|
||||
if not rest:
|
||||
next_line = self._peek_significant()
|
||||
if next_line is not None and next_line.indent > indent:
|
||||
result.append(self._parse_node(next_line.indent))
|
||||
else:
|
||||
result.append(None)
|
||||
continue
|
||||
if self._is_sequence_marker(rest):
|
||||
self._error(
|
||||
line,
|
||||
"不支持紧凑嵌套 sequence，请把内层 '-' 放到下一行",
|
||||
)
|
||||
if self._looks_like_mapping_entry(rest):
|
||||
mapping_indent = indent + 2
|
||||
item: dict[str, Any] = {}
|
||||
self._consume_mapping_entry(
|
||||
item,
|
||||
rest,
|
||||
mapping_indent=mapping_indent,
|
||||
line=line,
|
||||
)
|
||||
while True:
|
||||
self._skip_insignificant()
|
||||
continuation = self._peek_significant()
|
||||
if continuation is None or continuation.indent < mapping_indent:
|
||||
break
|
||||
if continuation.indent > mapping_indent:
|
||||
self._error(
|
||||
continuation,
|
||||
"sequence mapping 存在意外缩进",
|
||||
)
|
||||
continuation_content = self._without_comment(
|
||||
continuation.content
|
||||
).rstrip()
|
||||
if self._is_sequence_marker(continuation_content):
|
||||
self._error(
|
||||
continuation,
|
||||
"sequence mapping 中需要 key: value",
|
||||
)
|
||||
self.index += 1
|
||||
self._consume_mapping_entry(
|
||||
item,
|
||||
continuation_content,
|
||||
mapping_indent=mapping_indent,
|
||||
line=continuation,
|
||||
)
|
||||
result.append(item)
|
||||
continue
|
||||
if rest in {">", "|"}:
|
||||
result.append(self._parse_block_scalar(indent, rest, line))
|
||||
else:
|
||||
result.append(self._parse_inline_value(rest, line))
|
||||
next_line = self._peek_significant()
|
||||
if next_line is not None and next_line.indent > indent:
|
||||
self._error(next_line, "scalar sequence 项后存在意外缩进")
|
||||
return result
|
||||
|
||||
def _consume_mapping_entry(
|
||||
self,
|
||||
result: dict[str, Any],
|
||||
content: str,
|
||||
*,
|
||||
mapping_indent: int,
|
||||
line: _Line,
|
||||
) -> None:
|
||||
key_text, value_text = self._split_mapping_entry(content, line)
|
||||
key = self._parse_key(key_text, line)
|
||||
if key in result:
|
||||
self._error(line, f"mapping 存在重复键 {key!r}")
|
||||
|
||||
value_text = value_text.strip()
|
||||
if value_text in {">", "|"}:
|
||||
value = self._parse_block_scalar(mapping_indent, value_text, line)
|
||||
elif value_text:
|
||||
if value_text.startswith((">", "|")):
|
||||
self._error(
|
||||
line,
|
||||
"block scalar 只支持 '>' 或 '|'，不支持 chomping/indent 指示符",
|
||||
)
|
||||
value = self._parse_inline_value(value_text, line)
|
||||
next_line = self._peek_significant()
|
||||
if next_line is not None and next_line.indent > mapping_indent:
|
||||
self._error(next_line, f"{key!r} 的 scalar 后存在意外缩进")
|
||||
else:
|
||||
next_line = self._peek_significant()
|
||||
if next_line is not None and next_line.indent > mapping_indent:
|
||||
value = self._parse_node(next_line.indent)
|
||||
else:
|
||||
value = None
|
||||
result[key] = value
|
||||
|
||||
def _parse_block_scalar(
|
||||
self,
|
||||
parent_indent: int,
|
||||
style: str,
|
||||
header: _Line,
|
||||
) -> str:
|
||||
probe = self.index
|
||||
while probe < len(self.lines) and not self.lines[probe].content.strip():
|
||||
probe += 1
|
||||
if probe >= len(self.lines) or self.lines[probe].indent <= parent_indent:
|
||||
return ""
|
||||
block_indent = self.lines[probe].indent
|
||||
if block_indent <= parent_indent:
|
||||
self._error(header, "block scalar 内容必须比键更深缩进")
|
||||
|
||||
values: list[str] = []
|
||||
while self.index < len(self.lines):
|
||||
line = self.lines[self.index]
|
||||
if not line.content.strip():
|
||||
values.append("")
|
||||
self.index += 1
|
||||
continue
|
||||
if line.indent < block_indent:
|
||||
break
|
||||
values.append(" " * (line.indent - block_indent) + line.content)
|
||||
self.index += 1
|
||||
|
||||
while values and values[-1] == "":
|
||||
values.pop()
|
||||
if not values:
|
||||
return ""
|
||||
if style == "|":
|
||||
return "\n".join(values) + "\n"
|
||||
|
||||
output = ""
|
||||
previous: str | None = None
|
||||
blank_count = 0
|
||||
for value in values:
|
||||
if value == "":
|
||||
blank_count += 1
|
||||
continue
|
||||
if previous is None:
|
||||
output = "\n" * blank_count + value
|
||||
elif blank_count:
|
||||
output += "\n" * blank_count + value
|
||||
elif previous.startswith(" ") or value.startswith(" "):
|
||||
output += "\n" + value
|
||||
else:
|
||||
output += " " + value
|
||||
previous = value
|
||||
blank_count = 0
|
||||
return output + "\n"
|
||||
|
||||
def _parse_key(self, text: str, line: _Line) -> str:
|
||||
text = text.strip()
|
||||
if not text:
|
||||
self._error(line, "mapping key 不能为空")
|
||||
if text[0] in {'"', "'"}:
|
||||
parsed = _FlowParser(text, line.number).parse_complete_value()
|
||||
if not isinstance(parsed, str):
|
||||
self._error(line, "mapping key 必须是字符串")
|
||||
return parsed
|
||||
if text == "<<":
|
||||
self._error(line, "ACK YAML 子集不支持 merge key '<<'")
|
||||
if text[0] in "-?:!&*%@`" or _PLAIN_KEY_FORBIDDEN_RE.search(text):
|
||||
self._error(line, f"不支持的 plain mapping key {text!r}")
|
||||
parsed = _plain_scalar(text, line.number)
|
||||
if not isinstance(parsed, str):
|
||||
self._error(line, "mapping key 必须是字符串，特殊标量请加引号")
|
||||
return text
|
||||
|
||||
def _parse_inline_value(self, text: str, line: _Line) -> Any:
|
||||
parser = _FlowParser(text, line.number)
|
||||
return parser.parse_complete_value()
|
||||
|
||||
def _split_mapping_entry(self, content: str, line: _Line) -> tuple[str, str]:
|
||||
quote: str | None = None
|
||||
escaped = False
|
||||
depth = 0
|
||||
index = 0
|
||||
while index < len(content):
|
||||
char = content[index]
|
||||
if quote == '"':
|
||||
if escaped:
|
||||
escaped = False
|
||||
elif char == "\\":
|
||||
escaped = True
|
||||
elif char == quote:
|
||||
quote = None
|
||||
index += 1
|
||||
continue
|
||||
if quote == "'":
|
||||
if char == "'":
|
||||
if index + 1 < len(content) and content[index + 1] == "'":
|
||||
index += 2
|
||||
continue
|
||||
quote = None
|
||||
index += 1
|
||||
continue
|
||||
if char in {'"', "'"}:
|
||||
quote = char
|
||||
elif char in "[{":
|
||||
depth += 1
|
||||
elif char in "]}":
|
||||
depth -= 1
|
||||
if depth < 0:
|
||||
self._error(line, "flow collection 括号不匹配")
|
||||
elif (
|
||||
char == ":"
|
||||
and depth == 0
|
||||
and (index + 1 == len(content) or content[index + 1].isspace())
|
||||
):
|
||||
return content[:index], content[index + 1 :]
|
||||
index += 1
|
||||
self._error(line, "mapping 项必须使用 'key: value'")
|
||||
|
||||
def _looks_like_mapping_entry(self, content: str) -> bool:
|
||||
try:
|
||||
self._split_mapping_entry(content, self.lines[self.index - 1])
|
||||
except YamlSubsetError:
|
||||
return False
|
||||
return True
|
||||
|
||||
@staticmethod
|
||||
def _is_sequence_marker(content: str) -> bool:
|
||||
return content == "-" or content.startswith("- ")
|
||||
|
||||
def _peek_significant(self) -> _Line | None:
|
||||
probe = self.index
|
||||
while probe < len(self.lines):
|
||||
line = self.lines[probe]
|
||||
if line.content.strip() and not line.content.lstrip().startswith("#"):
|
||||
return line
|
||||
probe += 1
|
||||
return None
|
||||
|
||||
def _skip_insignificant(self) -> None:
|
||||
while self.index < len(self.lines):
|
||||
content = self.lines[self.index].content
|
||||
if content.strip() and not content.lstrip().startswith("#"):
|
||||
break
|
||||
self.index += 1
|
||||
|
||||
def _without_comment(self, content: str) -> str:
|
||||
quote: str | None = None
|
||||
escaped = False
|
||||
index = 0
|
||||
while index < len(content):
|
||||
char = content[index]
|
||||
if quote == '"':
|
||||
if escaped:
|
||||
escaped = False
|
||||
elif char == "\\":
|
||||
escaped = True
|
||||
elif char == quote:
|
||||
quote = None
|
||||
elif quote == "'":
|
||||
if char == "'":
|
||||
if index + 1 < len(content) and content[index + 1] == "'":
|
||||
index += 1
|
||||
else:
|
||||
quote = None
|
||||
elif char in {'"', "'"}:
|
||||
quote = char
|
||||
elif char == "#" and (index == 0 or content[index - 1].isspace()):
|
||||
return content[:index]
|
||||
index += 1
|
||||
if quote is not None:
|
||||
raise YamlSubsetError("未结束的引号标量")
|
||||
return content
|
||||
|
||||
def _reject_document_syntax(self, content: str, line: _Line) -> None:
|
||||
if content in {"---", "..."} or content.startswith("%"):
|
||||
self._error(line, "ACK YAML 子集只支持单文档，不支持 directive/marker")
|
||||
if content.startswith(("!", "&", "*")):
|
||||
self._error(line, "ACK YAML 子集不支持 tag/anchor/alias")
|
||||
|
||||
@staticmethod
|
||||
def _error(line: _Line, message: str) -> None:
|
||||
raise YamlSubsetError(f"第 {line.number} 行: {message}")
|
||||
|
||||
|
||||
class _FlowParser:
|
||||
def __init__(self, text: str, line_number: int) -> None:
|
||||
self.text = text
|
||||
self.line_number = line_number
|
||||
self.index = 0
|
||||
|
||||
def parse_complete_value(self) -> Any:
|
||||
value = self._parse_value()
|
||||
self._skip_space()
|
||||
if self.index != len(self.text):
|
||||
self._error(f"标量后存在未支持内容: {self.text[self.index:]!r}")
|
||||
return value
|
||||
|
||||
def _parse_value(self) -> Any:
|
||||
self._skip_space()
|
||||
if self.index >= len(self.text):
|
||||
self._error("缺少标量")
|
||||
char = self.text[self.index]
|
||||
if char == "[":
|
||||
return self._parse_list()
|
||||
if char == "{":
|
||||
return self._parse_map()
|
||||
if char in {'"', "'"}:
|
||||
return self._parse_quoted()
|
||||
if char in "]},":
|
||||
self._error(f"意外字符 {char!r}")
|
||||
return self._parse_plain({",", "]", "}"})
|
||||
|
||||
def _parse_list(self) -> list[Any]:
|
||||
self.index += 1
|
||||
result: list[Any] = []
|
||||
self._skip_space()
|
||||
if self._consume("]"):
|
||||
return result
|
||||
while True:
|
||||
result.append(self._parse_value())
|
||||
self._skip_space()
|
||||
if self._consume("]"):
|
||||
return result
|
||||
if not self._consume(","):
|
||||
self._error("flow list 项之间必须用 ',' 分隔")
|
||||
self._skip_space()
|
||||
if self.index >= len(self.text) or self.text[self.index] == "]":
|
||||
self._error("flow list 不支持尾随逗号")
|
||||
|
||||
def _parse_map(self) -> dict[str, Any]:
|
||||
self.index += 1
|
||||
result: dict[str, Any] = {}
|
||||
self._skip_space()
|
||||
if self._consume("}"):
|
||||
return result
|
||||
while True:
|
||||
self._skip_space()
|
||||
if self.index >= len(self.text):
|
||||
self._error("flow mapping 未结束")
|
||||
if self.text[self.index] in {'"', "'"}:
|
||||
key = self._parse_quoted()
|
||||
else:
|
||||
key = self._parse_plain({":"}, convert=False)
|
||||
if not isinstance(key, str) or not key:
|
||||
self._error("flow mapping key 必须是非空字符串")
|
||||
if key == "<<":
|
||||
self._error("ACK YAML 子集不支持 merge key '<<'")
|
||||
self._skip_space()
|
||||
if not self._consume(":"):
|
||||
self._error("flow mapping key 后必须是 ':'")
|
||||
value = self._parse_value()
|
||||
if key in result:
|
||||
self._error(f"flow mapping 存在重复键 {key!r}")
|
||||
result[key] = value
|
||||
self._skip_space()
|
||||
if self._consume("}"):
|
||||
return result
|
||||
if not self._consume(","):
|
||||
self._error("flow mapping 项之间必须用 ',' 分隔")
|
||||
self._skip_space()
|
||||
if self.index >= len(self.text) or self.text[self.index] == "}":
|
||||
self._error("flow mapping 不支持尾随逗号")
|
||||
|
||||
def _parse_quoted(self) -> str:
|
||||
quote = self.text[self.index]
|
||||
self.index += 1
|
||||
result: list[str] = []
|
||||
while self.index < len(self.text):
|
||||
char = self.text[self.index]
|
||||
self.index += 1
|
||||
if char == quote:
|
||||
if quote == "'" and self.index < len(self.text) and self.text[
|
||||
self.index
|
||||
] == "'":
|
||||
result.append("'")
|
||||
self.index += 1
|
||||
continue
|
||||
return "".join(result)
|
||||
if quote == "'" or char != "\\":
|
||||
result.append(char)
|
||||
continue
|
||||
if self.index >= len(self.text):
|
||||
self._error("双引号标量以转义符结尾")
|
||||
escape = self.text[self.index]
|
||||
self.index += 1
|
||||
simple = {
|
||||
"0": "\0",
|
||||
"a": "\a",
|
||||
"b": "\b",
|
||||
"t": "\t",
|
||||
"n": "\n",
|
||||
"v": "\v",
|
||||
"f": "\f",
|
||||
"r": "\r",
|
||||
"e": "\x1b",
|
||||
" ": " ",
|
||||
'"': '"',
|
||||
"/": "/",
|
||||
"\\": "\\",
|
||||
}
|
||||
if escape in simple:
|
||||
result.append(simple[escape])
|
||||
continue
|
||||
widths = {"x": 2, "u": 4, "U": 8}
|
||||
if escape in widths:
|
||||
width = widths[escape]
|
||||
digits = self.text[self.index : self.index + width]
|
||||
if len(digits) != width or not re.fullmatch(
|
||||
rf"[0-9a-fA-F]{{{width}}}", digits
|
||||
):
|
||||
self._error(f"无效 Unicode 转义 \\{escape}{digits}")
|
||||
codepoint = int(digits, 16)
|
||||
try:
|
||||
result.append(chr(codepoint))
|
||||
except ValueError as exc:
|
||||
raise YamlSubsetError(
|
||||
f"第 {self.line_number} 行: 无效 Unicode 码点"
|
||||
) from exc
|
||||
self.index += width
|
||||
continue
|
||||
self._error(f"不支持的双引号转义 \\{escape}")
|
||||
self._error("引号标量未结束")
|
||||
|
||||
def _parse_plain(
|
||||
self,
|
||||
delimiters: set[str],
|
||||
*,
|
||||
convert: bool = True,
|
||||
) -> Any:
|
||||
start = self.index
|
||||
while self.index < len(self.text) and self.text[self.index] not in delimiters:
|
||||
self.index += 1
|
||||
token = self.text[start : self.index].strip()
|
||||
if not token:
|
||||
self._error("空 plain scalar")
|
||||
if "#" in token:
|
||||
self._error("flow collection 内的注释不受支持")
|
||||
if ": " in token:
|
||||
self._error("plain scalar 中的 ': ' 必须加引号")
|
||||
if token[0] in "!&*%@`?" or _ANCHOR_OR_ALIAS_RE.search(token):
|
||||
self._error("ACK YAML 子集不支持 tag/anchor/alias/directive")
|
||||
return _plain_scalar(token, self.line_number) if convert else token
|
||||
|
||||
def _skip_space(self) -> None:
|
||||
while self.index < len(self.text) and self.text[self.index] == " ":
|
||||
self.index += 1
|
||||
|
||||
def _consume(self, expected: str) -> bool:
|
||||
if self.index < len(self.text) and self.text[self.index] == expected:
|
||||
self.index += 1
|
||||
return True
|
||||
return False
|
||||
|
||||
def _error(self, message: str) -> None:
|
||||
raise YamlSubsetError(f"第 {self.line_number} 行: {message}")
|
||||
|
||||
|
||||
def _plain_scalar(token: str, line_number: int) -> Any:
|
||||
lowered = token.lower()
|
||||
if lowered in {"null", "~"}:
|
||||
return None
|
||||
if lowered in {"true", "yes", "on"}:
|
||||
return True
|
||||
if lowered in {"false", "no", "off"}:
|
||||
return False
|
||||
if _DECIMAL_INT_RE.fullmatch(token):
|
||||
return int(token, 10)
|
||||
if _AMBIGUOUS_NUMBER_RE.fullmatch(token):
|
||||
raise YamlSubsetError(
|
||||
f"第 {line_number} 行: ACK YAML 子集不支持该数字格式 {token!r}，"
|
||||
"如需字符串请加引号"
|
||||
)
|
||||
return token
|
||||
@@ -0,0 +1,228 @@
|
||||
{
|
||||
"$schema": "http://json-schema.org/draft-07/schema#",
|
||||
"$id": "https://git.yumee.top/laily/skills/skills/ack/templates/delivery.schema.json",
|
||||
"title": "ACK project delivery contract",
|
||||
"description": "docs/ack/delivery.yaml 的权威结构；语义规则由 scripts/validate_delivery.py 补充。",
|
||||
"type": "object",
|
||||
"required": [
|
||||
"version",
|
||||
"project",
|
||||
"enabled",
|
||||
"defaultProfile",
|
||||
"entrypoints",
|
||||
"artifacts",
|
||||
"destinations",
|
||||
"environments",
|
||||
"profiles"
|
||||
],
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"version": { "type": "integer", "const": 1 },
|
||||
"updatedAt": { "type": "string" },
|
||||
"project": {
|
||||
"type": "object",
|
||||
"required": ["name"],
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"name": { "type": "string", "minLength": 1, "pattern": "\\S" }
|
||||
}
|
||||
},
|
||||
"enabled": { "type": "boolean" },
|
||||
"defaultProfile": {
|
||||
"type": ["string", "null"],
|
||||
"pattern": "^[a-z][a-z0-9-]{0,63}$"
|
||||
},
|
||||
"entrypoints": {
|
||||
"type": "object",
|
||||
"propertyNames": { "$ref": "#/definitions/id" },
|
||||
"additionalProperties": { "$ref": "#/definitions/entrypoint" }
|
||||
},
|
||||
"artifacts": {
|
||||
"type": "object",
|
||||
"propertyNames": { "$ref": "#/definitions/id" },
|
||||
"additionalProperties": { "$ref": "#/definitions/artifact" }
|
||||
},
|
||||
"destinations": {
|
||||
"type": "object",
|
||||
"propertyNames": { "$ref": "#/definitions/id" },
|
||||
"additionalProperties": { "$ref": "#/definitions/destination" }
|
||||
},
|
||||
"environments": {
|
||||
"type": "object",
|
||||
"propertyNames": { "$ref": "#/definitions/id" },
|
||||
"additionalProperties": { "$ref": "#/definitions/environment" }
|
||||
},
|
||||
"profiles": {
|
||||
"type": "object",
|
||||
"propertyNames": { "$ref": "#/definitions/id" },
|
||||
"additionalProperties": { "$ref": "#/definitions/profile" }
|
||||
}
|
||||
},
|
||||
"definitions": {
|
||||
"id": {
|
||||
"type": "string",
|
||||
"pattern": "^[a-z][a-z0-9-]{0,63}$"
|
||||
},
|
||||
"relativePath": {
|
||||
"type": "string",
|
||||
"minLength": 1,
|
||||
"pattern": "^(?!/)(?!.*(?:^|/)\\.\\.(?:/|$))[A-Za-z0-9._/*?+-]+$"
|
||||
},
|
||||
"stringList": {
|
||||
"type": "array",
|
||||
"items": { "type": "string" }
|
||||
},
|
||||
"secretName": {
|
||||
"type": "string",
|
||||
"pattern": "^[A-Z][A-Z0-9_]{0,127}$"
|
||||
},
|
||||
"entrypoint": {
|
||||
"type": "object",
|
||||
"required": [
|
||||
"kind",
|
||||
"args",
|
||||
"requiredSecrets",
|
||||
"workingDirectory",
|
||||
"timeoutSeconds"
|
||||
],
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"kind": {
|
||||
"type": "string",
|
||||
"enum": ["make", "just", "task", "dagger", "script"]
|
||||
},
|
||||
"target": { "type": "string", "minLength": 1 },
|
||||
"function": { "type": "string", "minLength": 1 },
|
||||
"path": { "$ref": "#/definitions/relativePath" },
|
||||
"args": { "$ref": "#/definitions/stringList" },
|
||||
"requiredSecrets": {
|
||||
"type": "array",
|
||||
"uniqueItems": true,
|
||||
"items": { "$ref": "#/definitions/secretName" }
|
||||
},
|
||||
"workingDirectory": { "$ref": "#/definitions/relativePath" },
|
||||
"timeoutSeconds": {
|
||||
"type": "integer",
|
||||
"minimum": 1,
|
||||
"maximum": 86400
|
||||
}
|
||||
}
|
||||
},
|
||||
"artifact": {
|
||||
"type": "object",
|
||||
"required": ["type", "build"],
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"type": { "type": "string", "enum": ["deb", "oci-image", "file"] },
|
||||
"build": { "$ref": "#/definitions/id" },
|
||||
"outputs": {
|
||||
"type": "array",
|
||||
"minItems": 1,
|
||||
"uniqueItems": true,
|
||||
"items": { "$ref": "#/definitions/relativePath" }
|
||||
},
|
||||
"image": { "type": "string", "minLength": 1 },
|
||||
"platforms": {
|
||||
"type": "array",
|
||||
"minItems": 1,
|
||||
"uniqueItems": true,
|
||||
"items": { "type": "string", "pattern": "^[a-z0-9]+/[A-Za-z0-9._-]+$" }
|
||||
}
|
||||
}
|
||||
},
|
||||
"destination": {
|
||||
"type": "object",
|
||||
"required": ["type", "channel"],
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"type": {
|
||||
"type": "string",
|
||||
"enum": ["apt-repository", "oci-registry", "ci-artifact"]
|
||||
},
|
||||
"channel": {
|
||||
"type": "string",
|
||||
"enum": ["preview", "staging", "stable"]
|
||||
},
|
||||
"registry": { "type": "string", "minLength": 1 },
|
||||
"repository": { "type": "string", "minLength": 1 },
|
||||
"endpoint": { "type": "string", "minLength": 1 },
|
||||
"artifactName": { "type": "string", "minLength": 1 },
|
||||
"upload": { "$ref": "#/definitions/id" }
|
||||
}
|
||||
},
|
||||
"environment": {
|
||||
"type": "object",
|
||||
"required": [
|
||||
"type",
|
||||
"classification",
|
||||
"target",
|
||||
"deploy",
|
||||
"healthCheck",
|
||||
"mutex"
|
||||
],
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"type": {
|
||||
"type": "string",
|
||||
"enum": ["ssh-host", "docker-compose", "kubernetes", "custom"]
|
||||
},
|
||||
"classification": {
|
||||
"type": "string",
|
||||
"enum": ["development", "staging", "production"]
|
||||
},
|
||||
"target": { "type": "string", "minLength": 1 },
|
||||
"deploy": { "$ref": "#/definitions/id" },
|
||||
"healthCheck": { "$ref": "#/definitions/id" },
|
||||
"rollback": { "$ref": "#/definitions/id" },
|
||||
"mutex": { "type": "string", "minLength": 1 }
|
||||
}
|
||||
},
|
||||
"step": {
|
||||
"type": "object",
|
||||
"required": ["id", "action"],
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"id": { "$ref": "#/definitions/id" },
|
||||
"action": {
|
||||
"type": "string",
|
||||
"enum": [
|
||||
"verify",
|
||||
"pull-request",
|
||||
"build",
|
||||
"publish",
|
||||
"deploy",
|
||||
"health-check",
|
||||
"approval",
|
||||
"mark-ready"
|
||||
]
|
||||
},
|
||||
"entrypoint": { "$ref": "#/definitions/id" },
|
||||
"artifact": { "$ref": "#/definitions/id" },
|
||||
"destination": { "$ref": "#/definitions/id" },
|
||||
"environment": { "$ref": "#/definitions/id" },
|
||||
"gate": { "type": "string", "enum": ["release", "production"] },
|
||||
"draft": { "type": "boolean" },
|
||||
"remote": {
|
||||
"type": "string",
|
||||
"pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$"
|
||||
},
|
||||
"baseBranch": { "type": "string", "minLength": 1, "maxLength": 255 }
|
||||
}
|
||||
},
|
||||
"profile": {
|
||||
"type": "object",
|
||||
"required": ["stopAt", "steps"],
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"stopAt": {
|
||||
"type": "string",
|
||||
"enum": ["verified", "review_ready", "released"]
|
||||
},
|
||||
"steps": {
|
||||
"type": "array",
|
||||
"items": { "$ref": "#/definitions/step" }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,24 @@
|
||||
# 复制为 docs/ack/delivery.yaml。默认关闭；由用户明确配置后再启用。
|
||||
version: 1
|
||||
updatedAt: "<YYYY-MM-DDTHH:mm:ss+TZ>"
|
||||
project:
|
||||
name: "<project_name>"
|
||||
|
||||
enabled: false
|
||||
defaultProfile: null
|
||||
|
||||
# 所有可执行入口都使用结构化 argv 语义；requiredSecrets 只保存名称，不保存值。
|
||||
# 不在此保存 shell、env 或凭据正文。
|
||||
entrypoints: {}
|
||||
|
||||
# 支持 deb、oci-image 和 file。复杂构建逻辑留在项目已有入口中。
|
||||
artifacts: {}
|
||||
|
||||
# 支持 apt-repository、oci-registry 和 ci-artifact。
|
||||
destinations: {}
|
||||
|
||||
# 支持 ssh-host、docker-compose、kubernetes 和 custom。
|
||||
environments: {}
|
||||
|
||||
# enabled=true 时，defaultProfile 必须指向一个非空 profile。
|
||||
profiles: {}
|
||||
@@ -0,0 +1,367 @@
|
||||
{
|
||||
"$schema": "http://json-schema.org/draft-07/schema#",
|
||||
"$id": "https://git.yumee.top/laily/skills/skills/ack/templates/knowledge.schema.json",
|
||||
"title": "ACK project knowledge guardrails",
|
||||
"description": "docs/ack/knowledge.yaml 的权威结构。知识只描述约束和验证引用，不保存可执行命令。",
|
||||
"type": "object",
|
||||
"required": ["version", "updatedAt", "project", "verificationRegistry", "entries"],
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"version": {
|
||||
"type": "integer",
|
||||
"minimum": 1
|
||||
},
|
||||
"updatedAt": {
|
||||
"type": "string",
|
||||
"format": "date-time"
|
||||
},
|
||||
"project": {
|
||||
"type": "object",
|
||||
"required": ["name"],
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"name": {
|
||||
"type": "string",
|
||||
"minLength": 1,
|
||||
"pattern": "\\S"
|
||||
}
|
||||
}
|
||||
},
|
||||
"verificationRegistry": {
|
||||
"type": "object",
|
||||
"propertyNames": {
|
||||
"pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*$"
|
||||
},
|
||||
"additionalProperties": {
|
||||
"$ref": "#/definitions/verificationTarget"
|
||||
}
|
||||
},
|
||||
"entries": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"$ref": "#/definitions/entry"
|
||||
}
|
||||
}
|
||||
},
|
||||
"definitions": {
|
||||
"stableRef": {
|
||||
"type": "string",
|
||||
"pattern": "^K-[A-Z0-9][A-Z0-9-]*@[1-9][0-9]*$"
|
||||
},
|
||||
"stringSet": {
|
||||
"type": "array",
|
||||
"uniqueItems": true,
|
||||
"items": {
|
||||
"type": "string",
|
||||
"minLength": 1,
|
||||
"pattern": "\\S"
|
||||
}
|
||||
},
|
||||
"scope": {
|
||||
"type": "object",
|
||||
"required": [
|
||||
"all",
|
||||
"components",
|
||||
"paths",
|
||||
"dependencies",
|
||||
"versions",
|
||||
"tags",
|
||||
"symbols",
|
||||
"errorSignatures"
|
||||
],
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"all": {
|
||||
"type": "boolean"
|
||||
},
|
||||
"components": {
|
||||
"$ref": "#/definitions/stringSet"
|
||||
},
|
||||
"paths": {
|
||||
"$ref": "#/definitions/stringSet"
|
||||
},
|
||||
"dependencies": {
|
||||
"$ref": "#/definitions/stringSet"
|
||||
},
|
||||
"versions": {
|
||||
"$ref": "#/definitions/stringSet"
|
||||
},
|
||||
"tags": {
|
||||
"$ref": "#/definitions/stringSet"
|
||||
},
|
||||
"symbols": {
|
||||
"$ref": "#/definitions/stringSet"
|
||||
},
|
||||
"errorSignatures": {
|
||||
"$ref": "#/definitions/stringSet"
|
||||
}
|
||||
}
|
||||
},
|
||||
"verification": {
|
||||
"type": "object",
|
||||
"required": ["ref", "expected"],
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"ref": {
|
||||
"type": "string",
|
||||
"minLength": 1,
|
||||
"pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*$"
|
||||
},
|
||||
"expected": {
|
||||
"type": "string",
|
||||
"minLength": 1,
|
||||
"pattern": "\\S"
|
||||
}
|
||||
}
|
||||
},
|
||||
"verificationTarget": {
|
||||
"type": "object",
|
||||
"required": ["path", "args"],
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"path": {
|
||||
"type": "string",
|
||||
"minLength": 1,
|
||||
"pattern": "^(?=.*\\S)[A-Za-z0-9][A-Za-z0-9._/-]*$",
|
||||
"description": "项目内可执行文件；运行时 cwd 为项目根，脚本不得依赖自身文件路径定位资源"
|
||||
},
|
||||
"args": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "string"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"provenance": {
|
||||
"type": "object",
|
||||
"required": ["taskId", "attemptId", "codeRef", "evidenceRef"],
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"taskId": {
|
||||
"type": "string",
|
||||
"minLength": 1,
|
||||
"pattern": "\\S"
|
||||
},
|
||||
"attemptId": {
|
||||
"type": "string",
|
||||
"minLength": 1,
|
||||
"pattern": "\\S"
|
||||
},
|
||||
"codeRef": {
|
||||
"type": "string",
|
||||
"minLength": 1,
|
||||
"pattern": "\\S"
|
||||
},
|
||||
"evidenceRef": {
|
||||
"type": "string",
|
||||
"minLength": 1,
|
||||
"pattern": "\\S"
|
||||
}
|
||||
}
|
||||
},
|
||||
"entry": {
|
||||
"type": "object",
|
||||
"required": [
|
||||
"id",
|
||||
"revision",
|
||||
"kind",
|
||||
"status",
|
||||
"title",
|
||||
"subject",
|
||||
"scope",
|
||||
"appliesWhen",
|
||||
"directive",
|
||||
"rationale",
|
||||
"verification",
|
||||
"provenance",
|
||||
"owner",
|
||||
"author",
|
||||
"reviewer",
|
||||
"approval",
|
||||
"createdAt",
|
||||
"lastValidatedAt",
|
||||
"reviewAfter",
|
||||
"temporary",
|
||||
"removalCondition",
|
||||
"statusReason",
|
||||
"supersedes",
|
||||
"conflictsWith"
|
||||
],
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"id": {
|
||||
"type": "string",
|
||||
"pattern": "^K-[A-Z0-9][A-Z0-9-]*$"
|
||||
},
|
||||
"revision": {
|
||||
"type": "integer",
|
||||
"minimum": 1
|
||||
},
|
||||
"kind": {
|
||||
"type": "string",
|
||||
"enum": ["guardrail", "pitfall", "verification"]
|
||||
},
|
||||
"status": {
|
||||
"type": "string",
|
||||
"enum": ["active", "stale", "superseded", "archived"]
|
||||
},
|
||||
"title": {
|
||||
"type": "string",
|
||||
"minLength": 1,
|
||||
"pattern": "\\S"
|
||||
},
|
||||
"subject": {
|
||||
"type": "string",
|
||||
"minLength": 1,
|
||||
"pattern": "^[a-z0-9][a-z0-9-]*$"
|
||||
},
|
||||
"scope": {
|
||||
"$ref": "#/definitions/scope"
|
||||
},
|
||||
"appliesWhen": {
|
||||
"type": "string",
|
||||
"minLength": 1,
|
||||
"pattern": "\\S"
|
||||
},
|
||||
"directive": {
|
||||
"type": "string",
|
||||
"minLength": 1,
|
||||
"pattern": "\\S"
|
||||
},
|
||||
"rationale": {
|
||||
"type": "string",
|
||||
"minLength": 1,
|
||||
"pattern": "\\S"
|
||||
},
|
||||
"verification": {
|
||||
"$ref": "#/definitions/verification"
|
||||
},
|
||||
"provenance": {
|
||||
"$ref": "#/definitions/provenance"
|
||||
},
|
||||
"owner": {
|
||||
"type": "string",
|
||||
"minLength": 1,
|
||||
"pattern": "\\S"
|
||||
},
|
||||
"author": {
|
||||
"type": "string",
|
||||
"minLength": 1,
|
||||
"pattern": "\\S"
|
||||
},
|
||||
"reviewer": {
|
||||
"type": "string",
|
||||
"minLength": 1,
|
||||
"pattern": "\\S"
|
||||
},
|
||||
"approval": {
|
||||
"oneOf": [
|
||||
{ "type": "null" },
|
||||
{ "$ref": "#/definitions/approval" }
|
||||
]
|
||||
},
|
||||
"createdAt": {
|
||||
"type": "string",
|
||||
"format": "date-time"
|
||||
},
|
||||
"lastValidatedAt": {
|
||||
"type": "string",
|
||||
"format": "date-time"
|
||||
},
|
||||
"reviewAfter": {
|
||||
"type": ["string", "null"],
|
||||
"format": "date-time"
|
||||
},
|
||||
"temporary": {
|
||||
"type": "boolean"
|
||||
},
|
||||
"removalCondition": {
|
||||
"type": ["string", "null"],
|
||||
"minLength": 1,
|
||||
"pattern": "\\S"
|
||||
},
|
||||
"statusReason": {
|
||||
"type": ["string", "null"],
|
||||
"minLength": 1,
|
||||
"pattern": "\\S"
|
||||
},
|
||||
"supersedes": {
|
||||
"type": "array",
|
||||
"uniqueItems": true,
|
||||
"items": {
|
||||
"$ref": "#/definitions/stableRef"
|
||||
}
|
||||
},
|
||||
"conflictsWith": {
|
||||
"type": "array",
|
||||
"uniqueItems": true,
|
||||
"items": {
|
||||
"$ref": "#/definitions/stableRef"
|
||||
}
|
||||
}
|
||||
},
|
||||
"allOf": [
|
||||
{
|
||||
"if": {
|
||||
"properties": {
|
||||
"temporary": {
|
||||
"const": true
|
||||
}
|
||||
}
|
||||
},
|
||||
"then": {
|
||||
"properties": {
|
||||
"reviewAfter": {
|
||||
"type": "string",
|
||||
"format": "date-time"
|
||||
},
|
||||
"removalCondition": {
|
||||
"type": "string",
|
||||
"minLength": 1
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
{
|
||||
"if": {
|
||||
"properties": {
|
||||
"status": {
|
||||
"enum": ["stale", "superseded", "archived"]
|
||||
}
|
||||
}
|
||||
},
|
||||
"then": {
|
||||
"properties": {
|
||||
"statusReason": {
|
||||
"type": "string",
|
||||
"minLength": 1
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
},
|
||||
"approval": {
|
||||
"type": "object",
|
||||
"required": ["approvedBy", "approvedAt", "evidenceRef"],
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"approvedBy": {
|
||||
"type": "string",
|
||||
"minLength": 1,
|
||||
"pattern": "\\S"
|
||||
},
|
||||
"approvedAt": {
|
||||
"type": "string",
|
||||
"format": "date-time"
|
||||
},
|
||||
"evidenceRef": {
|
||||
"type": "string",
|
||||
"minLength": 1,
|
||||
"pattern": "\\S"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,9 @@
|
||||
# 复制为 docs/ack/knowledge.yaml，替换占位符。结构见 templates/knowledge.schema.json。
|
||||
# Developer/Test 只能在任务证据中提出 candidate；只有 Coordinator 写入这里。
|
||||
version: 1
|
||||
updatedAt: "<YYYY-MM-DDTHH:mm:ss+TZ>"
|
||||
project:
|
||||
name: "<project_name>"
|
||||
# 检查 ID 映射到仓库内相对 path 和结构化 args；这里的内容不会被校验器执行。
|
||||
verificationRegistry: {}
|
||||
entries: []
|
||||
@@ -0,0 +1,125 @@
|
||||
# <项目名> Agent 协作协议（项目覆盖层）
|
||||
|
||||
> 本项目基于 ACK Skill v<ack_version>。通用规范由 `/ack` 从 Skill 自身的
|
||||
> `references/` 读取；本文件只保存项目差异。
|
||||
>
|
||||
> **本文件是「项目覆盖层」，文件名可配置。** 默认放 `docs/ack/project.md`，
|
||||
> 不占用 `AGENTS.md`，避免与团队已有的 `AGENTS.md` 约定冲突。
|
||||
> 若希望 Agent 自动加载，可由项目维护者自行在 `AGENTS.md` 中引用本文件；ACK
|
||||
> 不会自动修改 `AGENTS.md`、`CLAUDE.md` 或其它 Agent 指令文件。
|
||||
> 无论叫什么，都在 `tasks.yaml` 的 `project.overlayFile` 记录实际路径。
|
||||
> `docs/ack/` 只保存本项目的 `project.md`、`tasks.yaml`、`knowledge.yaml` 与默认关闭的
|
||||
> `delivery.yaml`，
|
||||
> 不复制或链接 Skill。
|
||||
|
||||
## 项目概览
|
||||
|
||||
- 项目：`<project_name>`
|
||||
- 技术栈：`<tech_stack>`
|
||||
- 运行命令：`<run_command>`
|
||||
- Base URL：`<base_url>`
|
||||
- 任务板：`docs/ack/tasks.yaml`
|
||||
- 项目知识：`docs/ack/knowledge.yaml`
|
||||
- 交付契约：`docs/ack/delivery.yaml`（默认关闭）
|
||||
- 覆盖层文件：`<overlay_file_path>`（默认 `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`
|
||||
- 验证后交付与配置维护（可选）：`references/delivery.md`
|
||||
|
||||
## Worker 路由
|
||||
|
||||
机器可校验的模型、reasoning effort、权限模式、默认 profile、允许 worktree 和启动
|
||||
receipt 全部以 `docs/ack/tasks.yaml` 的 `project.orchestration` 与顶层
|
||||
`workerReceipts` 为准。本文件不保存可执行 worker 命令。
|
||||
|
||||
默认 profile：
|
||||
|
||||
| 角色 | profile ID | 档位 |
|
||||
|------|------------|------|
|
||||
| Developer | `codex-dev-standard` | standard |
|
||||
| Test | `codex-test-standard` | standard |
|
||||
| Developer 升级 | `codex-dev-strong` | strong |
|
||||
|
||||
项目如改用 Cursor，应修改结构化 profile、allowlist 和 defaults，再运行任务板
|
||||
校验；不能在这里粘贴 `orca --command`、Agent CLI 参数或自由 shell。
|
||||
每次自动派发必须先审阅 launcher plan，再把其中的 `launchFingerprint` 作为
|
||||
`--expected-launch-fingerprint` 启动 fresh worker。v0.10 的 `receiptHash` 只作
|
||||
审计 checksum，不授权自动复用旧终端。
|
||||
|
||||
## 路径权限（项目覆盖层，必须填实际路径）
|
||||
|
||||
| 路径 | Coordinator | Test | Developer | 说明 |
|
||||
|------|:-----------:|:----:|:---------:|------|
|
||||
| `<spec_paths>` | R/W | Read-only | Read-only | 产品规格、API 文档、计划（PM 拥有） |
|
||||
| `<integration_test_paths>` | Read-only | R/W | Read-only | 浏览器/API 回归（Test 拥有） |
|
||||
| `<test_records_path>` | Read-only | R/W | Read-only | 复测记录 |
|
||||
| `<source_paths>` | Read-only | Read-only | R/W | 应用源码 |
|
||||
| `<unit_test_paths>` | Read-only | Read-only | R/W | 单元测试 |
|
||||
| `<shared_config_templates>` | Read-only | Read-only | R/W | 可提交配置模板 |
|
||||
| `<local_config_paths>` | Read-only | Read-only | Read-only | 本地私有配置 |
|
||||
| `tasks.yaml` | R/W | Read-only | Read-only | 只有 Coordinator 写 |
|
||||
| `knowledge.yaml` | R/W | Read-only | Read-only | 只有 Coordinator 写；Developer/Test 通过回报提名或验证 |
|
||||
| `delivery.yaml` | 仅显式维护时 R/W | Read-only | Read-only | 项目交付能力，不是执行授权 |
|
||||
|
||||
## 命令（项目覆盖层）
|
||||
|
||||
Developer 白盒验证：
|
||||
|
||||
```bash
|
||||
<unit_test_command>
|
||||
<build_command>
|
||||
<local_run_command>
|
||||
```
|
||||
|
||||
Test 黑盒复测：
|
||||
|
||||
```bash
|
||||
<preflight_command>
|
||||
<api_smoke_command>
|
||||
<browser_regression_command>
|
||||
```
|
||||
|
||||
知识项的 `verification.ref` 只能引用 `knowledge.yaml.verificationRegistry` 中已
|
||||
审查的检查入口。Registry 只保存仓库内相对 path 和结构化 args，不保存或执行自由
|
||||
shell 命令；新项目没有知识时保持空对象。Developer/Test 只能把 registry ID 交给
|
||||
Skill 的 `scripts/run_verification.py` 执行，不直接拼接 path/args。检查脚本从项目
|
||||
根 cwd 或 `ACK_PROJECT_ROOT` 定位资源，不能依赖自身文件路径。
|
||||
`ACK_PROJECT_ROOT` 是 runner 固定的根目录 fd 路径；仅用于日志的原始路径位于
|
||||
`ACK_PROJECT_ROOT_DISPLAY`。
|
||||
|
||||
项目状态校验由 `/ack` 使用 Skill 自带的 `scripts/validate_tasks.py`、
|
||||
`scripts/validate_knowledge.py` 和 `scripts/validate_delivery.py` 执行。
|
||||
构建/发布/部署的机器入口以 `delivery.yaml` 为准；本文件不维护第二套交付命令。
|
||||
|
||||
## 硬规则（其余见 references/）
|
||||
|
||||
- 三角色独立：Coordinator 只编排、Test 只验证、Developer 只实现（验证者 ≠ 实现者）。
|
||||
- 模型分层：Coordinator 用强模型且不亲自跑测试，Test/Developer 用中低模型，必要时升级（见 references/model-routing.md）。
|
||||
- 自动 worker 只能由 ACK 的 `scripts/launch_worker.py` 按结构化 profile 启动；
|
||||
禁止直接拼 `orca terminal create --command`，禁止 `command`、`extraArgs`、`env`
|
||||
等第二配置面。
|
||||
- v0.10 自动 launcher 只支持 `read-only` 和 `workspace-write`。full-access、
|
||||
bypass、YOLO/force 与关闭 sandbox 均 fail closed；需要可信平台审批通道后再开放。
|
||||
- v0.10 不自动复用持久化 receipt 指向的旧终端；每次自动派发都重新 plan/launch。
|
||||
- `worker_done` 与复测报告都不等于完成。必须 Test 独立复测 + Coordinator 终检后才能 `verified`。
|
||||
- 只有 Coordinator 写 `tasks.yaml` 和 `knowledge.yaml`；Developer 与 Test 都只读，
|
||||
通过消息回报。
|
||||
- Coordinator 只派发按 scope 命中并显式写入 `knowledgeRefs` 的 `active` 知识；
|
||||
`candidate` 不派发，知识库不全量注入。
|
||||
- Developer 回报 `knowledgeApplied` 与 `knowledgeCandidates`，Test 回报
|
||||
`knowledgeChecks`。关键约束应下沉为测试、lint、CI 或正式规范。
|
||||
- ACK 不自动修改 `AGENTS.md`、`CLAUDE.md` 或其它 Agent 指令文件。
|
||||
- `delivery.yaml` 默认关闭，只描述能力，不自动授权提交、推送、发布或部署；交付仅在
|
||||
任务 `verified` 且本次 profile/目标/停止点得到确认后运行。
|
||||
- 默认交付 profile 最多到 `review_ready`；stable 发布或 production 部署必须有
|
||||
approval 步骤并再次获得明确批准。配置变更只影响下一次 run。
|
||||
- 每个任务最多派发 3 轮，仍不过标记 `leftover` 并继续下一个。
|
||||
- 不提交、推送、发布或部署，除非用户确认的 ACK 任务或 delivery profile 明确包含。
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,180 @@
|
||||
# 复制为 docs/ack/tasks.yaml，替换占位符。结构见 templates/tasks.schema.json。
|
||||
version: 1
|
||||
updatedAt: "<YYYY-MM-DDTHH:mm:ss+TZ>"
|
||||
source: "Coordinator (PM) Agent"
|
||||
ackVersion: "<接入时的 ack skill 版本>"
|
||||
project:
|
||||
name: "<project_name>"
|
||||
repoPath: "<repo_path>"
|
||||
baseUrl: "<base_url>"
|
||||
devWorktree: "<dev_worktree>"
|
||||
overlayFile: "docs/ack/project.md"
|
||||
knowledgeFile: "docs/ack/knowledge.yaml"
|
||||
deliveryFile: "docs/ack/delivery.yaml"
|
||||
# 可选：飞书 Base Bug 收件箱。只保存 profile 名和资源 ID，绝不保存 App Secret。
|
||||
# bugIntake:
|
||||
# provider: "feishu-base"
|
||||
# workflow: "reviewed-writeback-v1"
|
||||
# profile: "project-feishu"
|
||||
# baseToken: "<base_token>"
|
||||
# tableId: "<table_id>"
|
||||
# viewId: "<ack_ready_view_id>"
|
||||
# fields:
|
||||
# title: "<field_id>"
|
||||
# actual: "<field_id>"
|
||||
# expected: "<field_id>"
|
||||
# stepsToReproduce: "<field_id>"
|
||||
# fixLogic: "<field_id>" # 启用飞书审核前协作时必填
|
||||
# acceptance: "<field_id>"
|
||||
# priority: "<field_id>"
|
||||
# attachments: "<field_id>"
|
||||
# updatedAt: "<field_id>"
|
||||
orchestration:
|
||||
profileVersion: 1
|
||||
mode: "orca"
|
||||
allowedWorktrees:
|
||||
- "<dev_worktree>"
|
||||
modelAllowlist:
|
||||
codex:
|
||||
developer:
|
||||
standard: ["gpt-5.6-terra"]
|
||||
strong: ["gpt-5.6-sol"]
|
||||
test:
|
||||
standard: ["gpt-5.6-luna"]
|
||||
cursor-agent:
|
||||
developer:
|
||||
standard: ["auto"]
|
||||
test:
|
||||
standard: ["auto"]
|
||||
profiles:
|
||||
codex-dev-standard:
|
||||
role: "developer"
|
||||
cli: "codex"
|
||||
tier: "standard"
|
||||
model: "gpt-5.6-terra"
|
||||
reasoningEffort: "medium"
|
||||
permissionMode: "workspace-write"
|
||||
codex-test-standard:
|
||||
role: "test"
|
||||
cli: "codex"
|
||||
tier: "standard"
|
||||
model: "gpt-5.6-luna"
|
||||
reasoningEffort: "low"
|
||||
permissionMode: "workspace-write"
|
||||
codex-dev-strong:
|
||||
role: "developer"
|
||||
cli: "codex"
|
||||
tier: "strong"
|
||||
model: "gpt-5.6-sol"
|
||||
reasoningEffort: "high"
|
||||
permissionMode: "workspace-write"
|
||||
cursor-dev-standard:
|
||||
role: "developer"
|
||||
cli: "cursor-agent"
|
||||
tier: "standard"
|
||||
model: "auto"
|
||||
reasoningEffort: null
|
||||
permissionMode: "workspace-write"
|
||||
cursor-test-standard:
|
||||
role: "test"
|
||||
cli: "cursor-agent"
|
||||
tier: "standard"
|
||||
model: "auto"
|
||||
reasoningEffort: null
|
||||
permissionMode: "workspace-write"
|
||||
defaults:
|
||||
developer: "codex-dev-standard"
|
||||
test: "codex-test-standard"
|
||||
developerUpgraded: "codex-dev-strong"
|
||||
|
||||
workerReceipts: []
|
||||
deliveryRuns: []
|
||||
|
||||
summary:
|
||||
verified: []
|
||||
open: []
|
||||
failedRetest: []
|
||||
leftovers: []
|
||||
|
||||
tasks:
|
||||
- id: "BUG-001"
|
||||
type: "bug"
|
||||
title: "<short title>"
|
||||
priority: "P0"
|
||||
status: "open"
|
||||
assignee: "developer"
|
||||
component: "<source file or module>"
|
||||
specRefs:
|
||||
- "<docs/spec.md#section>"
|
||||
testRefs:
|
||||
- "<tests/browser/cases/01-case.md>"
|
||||
knowledgeRefs: []
|
||||
knowledgeApplied: []
|
||||
knowledgeCandidates: []
|
||||
knowledgeChecks: []
|
||||
|
||||
# 从飞书导入时由 Coordinator 写入；source.ref 是幂等键。
|
||||
# source:
|
||||
# kind: "feishu-base"
|
||||
# workflow: "reviewed-writeback-v1"
|
||||
# ref: "feishu-base:sha256:<64-lowercase-hex>"
|
||||
# recordId: "<record-id>"
|
||||
# updatedAt: "<source-updated-at>"
|
||||
# approvedRevision: "sha256:<approved-draft-digest>"
|
||||
# approvedPayloadHash: "sha256:<canonical-task-payload-digest>"
|
||||
|
||||
description: >
|
||||
<What is wrong, in user-visible terms.>
|
||||
|
||||
# 飞书审核通过后写入批准版本；审核前不创建这条 ACK 任务。
|
||||
fixLogic: >
|
||||
<Approved repair logic, affected behavior, invariants, and regression risks.>
|
||||
|
||||
acceptanceCriteria:
|
||||
- "<observable acceptance signal 1>"
|
||||
- "<observable acceptance signal 2>"
|
||||
|
||||
stepsToReproduce:
|
||||
- "<step 1>"
|
||||
- "<step 2>"
|
||||
|
||||
expected: >
|
||||
<Expected behavior.>
|
||||
|
||||
actual: >
|
||||
<Actual behavior observed by Test.>
|
||||
|
||||
evidence:
|
||||
browser: "<snapshot text, screenshot path, or UI finding>"
|
||||
api: "<curl result or API mismatch>"
|
||||
logs: "<relevant log line if any>"
|
||||
|
||||
verification:
|
||||
commands:
|
||||
- "<unit/build command>"
|
||||
- "<browser/API smoke command>"
|
||||
browser:
|
||||
page: "<page path>"
|
||||
checks:
|
||||
- "<visible text or interaction expected>"
|
||||
|
||||
dispatch:
|
||||
developer:
|
||||
profileId: "codex-dev-standard"
|
||||
receiptId: null
|
||||
attemptId: null
|
||||
taskId: null
|
||||
dispatchId: null
|
||||
test:
|
||||
profileId: "codex-test-standard"
|
||||
receiptId: null
|
||||
attemptId: null
|
||||
taskId: null
|
||||
dispatchId: null
|
||||
rounds: []
|
||||
|
||||
resolution:
|
||||
fixedBy: null
|
||||
verifiedBy: null
|
||||
verifiedAt: null
|
||||
leftoverReason: null
|
||||
@@ -0,0 +1,80 @@
|
||||
# deb-publisher
|
||||
|
||||
帮助 Agent 复用项目已有的 DEB 打包与发布方式，完成构建、包检查、上传和发布验证。
|
||||
|
||||
## 什么时候使用
|
||||
|
||||
当你希望 Agent 处理以下任务时使用：
|
||||
|
||||
- “帮我构建这个项目的 DEB 包”
|
||||
- “把 1.2.3 版本的 DEB 发布到包仓库”
|
||||
- “看看项目里的 DEB 发布流程”
|
||||
- “检查这个 DEB 是否可以发布”
|
||||
|
||||
只想在本机安装一个 `.deb`，或者要构建 RPM、Docker 镜像时，不需要使用这个 skill。
|
||||
|
||||
## 使用前准备
|
||||
|
||||
请准备或确认：
|
||||
|
||||
- 要构建或发布的版本号。
|
||||
- 项目已经配置好构建脚本、Make 目标或 `debian/` 目录；上传脚本由 skill 自带，
|
||||
不需要放进项目。
|
||||
- 发布所需的令牌已经放入项目约定的环境变量或密钥系统。
|
||||
- 如果要真实发布，明确告诉 Agent 目标仓库以及是否允许覆盖同版本。
|
||||
|
||||
不要把令牌直接粘贴到对话、命令参数或项目文件中。
|
||||
|
||||
## 使用示例
|
||||
|
||||
仅分析，不产生或上传包：
|
||||
|
||||
```text
|
||||
看看这个项目的 DEB 是怎么构建和发布的。
|
||||
```
|
||||
|
||||
只构建和检查，不上传：
|
||||
|
||||
```text
|
||||
使用 deb-publisher 构建 1.2.3 的 DEB，检查包元数据和内容，不要上传。
|
||||
```
|
||||
|
||||
构建并发布：
|
||||
|
||||
```text
|
||||
使用 deb-publisher 构建并发布 1.2.3 的 amd64 DEB 到项目已配置的测试仓库。
|
||||
```
|
||||
|
||||
发布已有产物：
|
||||
|
||||
```text
|
||||
使用 deb-publisher 检查并发布 ./dist/example_1.2.3_amd64.deb。
|
||||
```
|
||||
|
||||
## Agent 会做什么
|
||||
|
||||
Agent 会优先发现和复用项目已有入口，然后：
|
||||
|
||||
1. 确认版本、架构、产物路径、目标仓库和授权范围。
|
||||
2. 构建 DEB，或定位你指定的已有产物。
|
||||
3. 检查包的元数据、内容和 SHA-256。
|
||||
4. 在你明确要求发布时，通过 skill 自带的 `scripts/upload_deb.sh` 上传。
|
||||
5. 检查服务端响应，并在仓库支持时确认该版本已经可见。
|
||||
|
||||
## 如何判断完成
|
||||
|
||||
结果中应包含包名、版本、架构、产物路径、SHA-256，以及构建、上传和仓库可见性的
|
||||
独立状态。异步索引尚未完成时，Agent 应明确说明“上传已接受，索引待更新”。
|
||||
|
||||
## 上传协议
|
||||
|
||||
自带脚本适用于接收 multipart 字段 `package`、`token` 和 `repository_name` 的
|
||||
HTTP DEB 仓库，默认路径是 `/api/v2/upload/package`。使用以下环境变量：
|
||||
|
||||
- `DEB_SERVER_URL`：仓库服务地址。
|
||||
- `DEB_TOKEN`：认证令牌。
|
||||
- `DEB_REPOSITORY`：目标仓库名。
|
||||
- `DEB_UPLOAD_PATH`：可选的上传路径覆盖。
|
||||
|
||||
令牌只从环境变量读取，不作为命令行参数传递。若你的仓库使用其他 API 协议，应先告诉
|
||||
Agent，不要直接套用该脚本。
|
||||
@@ -0,0 +1,150 @@
|
||||
---
|
||||
name: deb-publisher
|
||||
description: >-
|
||||
构建并发布 Debian DEB 包：发现项目已有的 Makefile 和打包入口，使用 skill 自带的
|
||||
通用上传脚本提交包，校验包元数据与内容，并验证发布结果。触发词：构建 deb、
|
||||
发布 deb、上传 deb、提交 deb、推送 apt 仓库、打 Debian 包。仅分析打包逻辑时也可使用，
|
||||
但不会在未获授权时执行上传。
|
||||
---
|
||||
|
||||
# DEB Publisher
|
||||
|
||||
复用项目已有发布约定，安全地完成“发现入口 → 构建 → 检查 → 上传 → 验证”。
|
||||
|
||||
## 何时使用
|
||||
|
||||
- 用户要求构建、发布、上传或提交 `.deb` 包。
|
||||
- 用户要求梳理或接通项目现有的 DEB 发布流程。
|
||||
- 用户要求把已经生成的 `.deb` 推送到 APT/DEB 包仓库。
|
||||
|
||||
## 不适用
|
||||
|
||||
- 只需要安装或卸载本地 DEB 包。
|
||||
- 目标是 RPM、APK、容器镜像或语言包管理器。
|
||||
- 用户只要求设计全新的 Debian 打包体系；此时应先完成方案设计。
|
||||
|
||||
## 工作流
|
||||
|
||||
### 1. 发现项目约定
|
||||
|
||||
从项目根目录查找，不预设文件位置：
|
||||
|
||||
```bash
|
||||
rg -n -i --hidden --glob '!.git' \
|
||||
'build-deb|upload-deb|publish-deb|dpkg-deb|debuild|curl.*deb|\.deb\b|aptly|reprepro'
|
||||
```
|
||||
|
||||
重点检查：
|
||||
|
||||
- `Makefile`、CI 配置、`debian/`、构建脚本和发布文档。
|
||||
- 版本号、包名、架构、产物目录和仓库名如何传入。
|
||||
- 发布端点、认证方式以及发布是否由构建目标自动触发。
|
||||
- 当前工作树和目标版本是否匹配。
|
||||
|
||||
优先复用已有构建入口。上传默认使用本 skill 的 `scripts/upload_deb.sh`，不要把它
|
||||
复制到项目中；仅当目标仓库协议不兼容时才复用或修改项目专属上传逻辑。
|
||||
|
||||
### 2. 确认发布边界
|
||||
|
||||
上传是外部写操作。仅当用户明确要求发布、上传或提交时执行；若用户只要求查看、
|
||||
诊断或构建，则停在相应阶段。
|
||||
|
||||
执行上传前确认：
|
||||
|
||||
- 目标服务和仓库来自项目配置或用户输入，不猜测生产端点。
|
||||
- 认证令牌已通过环境变量或密钥系统提供。
|
||||
- 目标版本、架构和产物路径能够从构建配置推导。
|
||||
- 相同版本是否允许覆盖；无法确认且可能覆盖时，先询问用户。
|
||||
|
||||
绝不把令牌写入命令输出、文件、提交或最终回复。不要用 `set -x` 执行含凭据的脚本。
|
||||
|
||||
### 3. 构建包
|
||||
|
||||
使用项目声明的构建目标，并显式传入版本。例如项目提供 Make 目标时：
|
||||
|
||||
```bash
|
||||
make build-deb VERSION="$RELEASE_VERSION"
|
||||
```
|
||||
|
||||
如果构建目标会自动上传，而当前仅获构建授权，应改用其纯构建子目标。执行前检查
|
||||
所需工具和环境，例如 Docker、`dpkg-deb`、编译器、SSH 访问或前端工具链。
|
||||
|
||||
不得擅自清理宽泛目录。若脚本包含 `rm -rf`，先解析并确认目标是明确、受限的构建目录。
|
||||
|
||||
### 4. 上传前检查
|
||||
|
||||
定位唯一目标产物；若匹配多个包，不凭文件时间猜测：
|
||||
|
||||
```bash
|
||||
find <artifact-dir> -maxdepth 2 -type f -name '*.deb' -print
|
||||
dpkg-deb --info <package.deb>
|
||||
dpkg-deb --contents <package.deb>
|
||||
```
|
||||
|
||||
至少验证：
|
||||
|
||||
- 文件存在、非空且 `dpkg-deb --info` 成功。
|
||||
- `Package`、`Version`、`Architecture` 与本次发布一致。
|
||||
- 包内容包含预期的主程序或关键文件。
|
||||
- maintainer scripts 存在时权限正确，且没有明显的宿主机破坏性操作。
|
||||
|
||||
建议记录 SHA-256：
|
||||
|
||||
```bash
|
||||
sha256sum <package.deb>
|
||||
```
|
||||
|
||||
### 5. 发布
|
||||
|
||||
解析当前 `SKILL.md` 所在目录，以绝对路径调用随 skill 分发的脚本：
|
||||
|
||||
```bash
|
||||
DEB_SERVER_URL="$DEB_SERVER_URL" \
|
||||
DEB_TOKEN="$DEB_TOKEN" \
|
||||
DEB_REPOSITORY="$DEB_REPOSITORY" \
|
||||
<skill-dir>/scripts/upload_deb.sh <exact-package-path.deb>
|
||||
```
|
||||
|
||||
不要把脚本复制进当前项目，也不要将 token 作为命令行参数。脚本默认请求
|
||||
`/api/v2/upload/package`，以 multipart 字段 `package`、`token`、
|
||||
`repository_name` 上传，接受 `200` 和 `201` 为成功。端点路径不同时可设置
|
||||
`DEB_UPLOAD_PATH`。
|
||||
|
||||
调用前确认目标服务使用上述协议；不兼容时不要强行调用。传入刚刚校验过的确切路径，
|
||||
不要使用宽泛 glob。项目已有 `make upload-deb` 时，检查它是否只是包装了同一协议：
|
||||
如果是，直接使用 skill 脚本；若 CI 或其他人仍依赖 Make 目标，可将目标改为调用已安装
|
||||
skill 的脚本，但不要提交脚本副本。
|
||||
|
||||
脚本支持多个确切文件路径，会汇总每个文件的结果，并在任一失败时返回非零。
|
||||
|
||||
### 6. 验证与汇报
|
||||
|
||||
发布成功不能只依据“curl 已执行”。综合检查：
|
||||
|
||||
- 上传命令退出码为零。
|
||||
- HTTP 状态和响应体明确表示成功。
|
||||
- 若仓库提供只读查询、索引或下载地址，再确认该包和版本已可见。
|
||||
- 若索引更新是异步的，报告“上传已接受，索引尚待更新”，不要声称已完全可用。
|
||||
|
||||
最终回复给出：
|
||||
|
||||
- 包名、版本、架构。
|
||||
- 产物路径和 SHA-256。
|
||||
- 目标服务/仓库的非敏感标识。
|
||||
- 构建、上传及仓库可见性各自的验证结果。
|
||||
- 任何未完成项或回滚/覆盖风险。
|
||||
|
||||
## 修改已有发布逻辑时
|
||||
|
||||
- 保持项目现有变量名和调用入口，避免无关重构。
|
||||
- 修复行为缺陷时增加最小静态检查或可离线运行的测试。
|
||||
- 可用 `bash -n` 检查脚本语法；项目有 ShellCheck 时一并运行。
|
||||
- skill 自带上传脚本是 SSOT；通用上传行为的修改应落在
|
||||
`skills/deb-publisher/scripts/upload_deb.sh`，不要同步复制到业务项目。
|
||||
- 不通过真实生产上传来测试脚本，除非用户明确授权并给出测试版本或测试仓库。
|
||||
|
||||
## 完成标准
|
||||
|
||||
- 仅分析：入口、调用链、配置来源和风险已被准确说明。
|
||||
- 仅构建：DEB 已生成，元数据、内容和校验和通过检查，未发生上传。
|
||||
- 发布：构建检查通过，服务端接受上传，且仓库可见性已验证或被准确标记为待更新。
|
||||
Executable
+133
@@ -0,0 +1,133 @@
|
||||
#!/usr/bin/env bash
|
||||
set -euo pipefail
|
||||
|
||||
usage() {
|
||||
cat <<'EOF'
|
||||
Usage:
|
||||
DEB_SERVER_URL=https://deb.example.com \
|
||||
DEB_TOKEN=secret \
|
||||
DEB_REPOSITORY=main \
|
||||
upload_deb.sh FILE.deb [FILE.deb ...]
|
||||
|
||||
Options:
|
||||
-s SERVER_URL Override DEB_SERVER_URL
|
||||
-n REPOSITORY Override DEB_REPOSITORY
|
||||
-p UPLOAD_PATH Override DEB_UPLOAD_PATH (default: /api/v2/upload/package)
|
||||
-h Show help
|
||||
|
||||
The endpoint must accept multipart fields named package, token, and
|
||||
repository_name. Authentication is read only from DEB_TOKEN so it is not
|
||||
exposed in the process command line.
|
||||
EOF
|
||||
}
|
||||
|
||||
server_url=${DEB_SERVER_URL:-}
|
||||
repository=${DEB_REPOSITORY:-}
|
||||
upload_path=${DEB_UPLOAD_PATH:-/api/v2/upload/package}
|
||||
token=${DEB_TOKEN:-}
|
||||
|
||||
while getopts ":s:n:p:h" option; do
|
||||
case "$option" in
|
||||
s) server_url=$OPTARG ;;
|
||||
n) repository=$OPTARG ;;
|
||||
p) upload_path=$OPTARG ;;
|
||||
h) usage; exit 0 ;;
|
||||
:) echo "Error: -$OPTARG requires a value" >&2; usage >&2; exit 2 ;;
|
||||
\?) echo "Error: unknown option -$OPTARG" >&2; usage >&2; exit 2 ;;
|
||||
esac
|
||||
done
|
||||
shift $((OPTIND - 1))
|
||||
|
||||
if [[ -z "$server_url" || -z "$repository" || -z "$token" || $# -eq 0 ]]; then
|
||||
echo "Error: DEB_SERVER_URL, DEB_TOKEN, DEB_REPOSITORY, and at least one file are required." >&2
|
||||
usage >&2
|
||||
exit 2
|
||||
fi
|
||||
if [[ "$upload_path" != /* ]]; then
|
||||
echo "Error: upload path must start with /" >&2
|
||||
exit 2
|
||||
fi
|
||||
if ! command -v curl >/dev/null 2>&1; then
|
||||
echo "Error: curl is required." >&2
|
||||
exit 2
|
||||
fi
|
||||
|
||||
server_url=${server_url%/}
|
||||
success_count=0
|
||||
fail_count=0
|
||||
response_file=
|
||||
|
||||
cleanup() {
|
||||
if [[ -n "$response_file" && -f "$response_file" ]]; then
|
||||
rm -f -- "$response_file"
|
||||
fi
|
||||
}
|
||||
trap cleanup EXIT
|
||||
|
||||
print_response() {
|
||||
local file=$1
|
||||
if command -v jq >/dev/null 2>&1 && jq -e . "$file" >/dev/null 2>&1; then
|
||||
jq . "$file"
|
||||
else
|
||||
cat -- "$file"
|
||||
fi
|
||||
}
|
||||
|
||||
for package_file in "$@"; do
|
||||
if [[ ! -f "$package_file" ]]; then
|
||||
echo "Skip: file not found: $package_file" >&2
|
||||
fail_count=$((fail_count + 1))
|
||||
continue
|
||||
fi
|
||||
if [[ "$package_file" != *.deb ]]; then
|
||||
echo "Skip: not a .deb file: $package_file" >&2
|
||||
fail_count=$((fail_count + 1))
|
||||
continue
|
||||
fi
|
||||
if [[ ! -s "$package_file" ]]; then
|
||||
echo "Skip: empty file: $package_file" >&2
|
||||
fail_count=$((fail_count + 1))
|
||||
continue
|
||||
fi
|
||||
|
||||
response_file=$(mktemp)
|
||||
echo "Uploading $(basename -- "$package_file") to $server_url (repository $repository)..."
|
||||
|
||||
http_code=000
|
||||
if http_code=$(curl --silent --show-error \
|
||||
--output "$response_file" \
|
||||
--write-out "%{http_code}" \
|
||||
--request POST \
|
||||
"$server_url$upload_path" \
|
||||
--form "package=@${package_file};type=application/vnd.debian.binary-package" \
|
||||
--form "token=${token}" \
|
||||
--form "repository_name=${repository}"); then
|
||||
:
|
||||
else
|
||||
echo "Failed (transport error): $(basename -- "$package_file")" >&2
|
||||
print_response "$response_file" >&2
|
||||
fail_count=$((fail_count + 1))
|
||||
cleanup
|
||||
response_file=
|
||||
continue
|
||||
fi
|
||||
|
||||
if [[ "$http_code" == 200 || "$http_code" == 201 ]]; then
|
||||
echo "Success ($http_code): $(basename -- "$package_file")"
|
||||
print_response "$response_file"
|
||||
success_count=$((success_count + 1))
|
||||
else
|
||||
echo "Failed ($http_code): $(basename -- "$package_file")" >&2
|
||||
print_response "$response_file" >&2
|
||||
fail_count=$((fail_count + 1))
|
||||
fi
|
||||
|
||||
cleanup
|
||||
response_file=
|
||||
done
|
||||
|
||||
echo "Done. Success: $success_count, Failed: $fail_count"
|
||||
if ((fail_count > 0)); then
|
||||
exit 1
|
||||
fi
|
||||
|
||||
@@ -0,0 +1,110 @@
|
||||
# manage-release
|
||||
|
||||
`manage-release` 帮助 Agent 管理从开发版本到发布的 Git 流程，包括 worktree、分支、
|
||||
版本号、PR/MR、合并和 release tag。它可以只处理其中一个阶段，也可以从准备开发目录
|
||||
一直执行到发布。
|
||||
|
||||
## 使用前准备
|
||||
|
||||
- 项目已经是 Git 仓库，并配置了可访问的远端。
|
||||
- 项目已有版本文件或发布约定；没有时可以让 Agent 先给出版本建议。
|
||||
- 创建或合并 PR/MR、创建 Forge Release 时，准备好 GitHub、GitLab、Gitea 或 Forgejo
|
||||
对应的已认证 CLI。只发布 Git tag 时不要求 Forge CLI，但 Git remote 必须可读写。
|
||||
- 请求里写清目标版本、基线分支，以及允许执行到哪一步。没有明确授权的远端写操作
|
||||
不会执行。
|
||||
|
||||
## 常见用法
|
||||
|
||||
### 确定下一个版本号
|
||||
|
||||
```text
|
||||
使用 manage-release 检查当前版本和这次改动，建议下一个版本号。只分析，不修改文件。
|
||||
```
|
||||
|
||||
适合还没决定该发 patch、minor 还是 major 时使用。Agent 会读取项目版本规则、现有 tag
|
||||
和实际改动，给出建议及依据。
|
||||
|
||||
### 开始开发新版本
|
||||
|
||||
```text
|
||||
使用 manage-release，从 main 为 1.6.0 创建独立 worktree 和分支。先不要 push，也不要创建 PR。
|
||||
```
|
||||
|
||||
Agent 会检查已有 worktree、分支和 tag，确认没有冲突后准备开发目录。这个请求只授权
|
||||
本地操作。
|
||||
|
||||
### 把开发分支提交为 PR
|
||||
|
||||
```text
|
||||
使用 manage-release 检查当前分支，更新版本号和 CHANGELOG，运行项目测试，然后 push 并创建指向 main 的 PR。不要合并。
|
||||
```
|
||||
|
||||
适合开发已经完成，只需要整理版本信息并送审。Agent 会停在 PR 创建成功的位置，返回
|
||||
PR 地址、测试结果和待处理项。
|
||||
|
||||
### 合并通过检查的 PR
|
||||
|
||||
```text
|
||||
使用 manage-release 检查当前 PR。如果 CI、review 和冲突检查都通过，就按项目规则合并；不要打 tag。
|
||||
```
|
||||
|
||||
Agent 只会在仓库要求全部满足后合并，不会使用管理员权限绕过保护规则。合并完成后会
|
||||
返回准确的 merged commit。
|
||||
|
||||
### 为已合并版本发布 tag
|
||||
|
||||
```text
|
||||
使用 manage-release，为已经合并到 main 的 1.6.0 发布 v1.6.0 tag。确认 tag 指向包含该版本号的 merged commit，不要创建 Forge Release。
|
||||
```
|
||||
|
||||
适合依靠 Git tag 触发后续 CI 发布的项目。Agent 会分别验证版本文件、目标 commit 和
|
||||
远端 tag，不会给未合并分支打正式 tag。
|
||||
|
||||
### 完成端到端发布
|
||||
|
||||
```text
|
||||
使用 manage-release 完成 1.6.0 发布：从 main 创建 worktree 和分支，完成版本更新和验证，创建 PR，检查通过后合并，推送 v1.6.0 tag，并创建 Forge Release。
|
||||
```
|
||||
|
||||
这条请求授权完整流程。遇到 review 未通过、CI 失败、版本冲突或已有同名 tag 时，
|
||||
Agent 会停止并说明卡在哪一步，不会绕过检查继续发布。
|
||||
|
||||
### 发布紧急修复版本
|
||||
|
||||
```text
|
||||
使用 manage-release 从 main 准备 1.6.1 hotfix。创建独立 worktree，完成修复后开 PR；检查通过就合并并发布 v1.6.1。
|
||||
```
|
||||
|
||||
适合线上问题修复。Skill 仍走正常 PR 和保护分支流程，不会因为是 hotfix 就直接推送
|
||||
main 或覆盖已有 tag。
|
||||
|
||||
### 从中断位置继续
|
||||
|
||||
```text
|
||||
使用 manage-release 检查 v1.6.0 当前发布状态，从尚未完成的步骤继续。不要重复创建分支、PR、tag 或 release。
|
||||
```
|
||||
|
||||
适合合并后打 tag 失败、tag 已推送但 release 未创建，或者 Agent 会话中断的情况。
|
||||
Skill 会从 Git 和代码托管平台重新判断状态，再继续缺失的步骤。
|
||||
|
||||
## Agent 会做什么
|
||||
|
||||
Agent 会先发现项目自己的版本、分支和发布规则，再检查本地 Git 与远端状态。它只执行
|
||||
请求中明确授权的阶段，并在合并、tag 或 release 条件不满足时停止。完整流程结束后，
|
||||
结果中会分别列出 worktree、分支、版本、PR/MR、merged commit、tag 和 Forge Release
|
||||
状态。
|
||||
|
||||
## 如何判断完成
|
||||
|
||||
- 只分析版本时，结果包含建议版本及依据。
|
||||
- 创建开发环境时，结果包含 worktree 路径、分支和基线 commit。
|
||||
- 创建或合并 PR/MR 时，结果包含 URL、检查状态和 merged commit。
|
||||
- 发布 tag 时，远端 tag 解引用后的 commit 与 merged commit 一致。
|
||||
- 创建 Forge Release 时，结果包含可访问的 release URL。
|
||||
- 中途停止时，结果说明停在哪一步、为什么停止，以及下次如何继续。
|
||||
|
||||
## 不适用的场景
|
||||
|
||||
普通功能开发、普通 worktree 或 PR/MR 操作、代码审查、构建 Docker 镜像或上传 DEB 包
|
||||
不需要触发 `manage-release`。只有任务明确涉及版本发布、发布分支、版本号、发布 PR/MR
|
||||
或 release tag 时，才交给这个 Skill。
|
||||
@@ -0,0 +1,198 @@
|
||||
---
|
||||
name: manage-release
|
||||
description: >-
|
||||
管理 Git 项目从开发版本到发布的完整生命周期：发现并遵循项目分支与版本策略，
|
||||
创建或复用隔离 worktree 和版本分支，确定并同步版本号，推送并创建、检查或合并
|
||||
PR/MR，在合并后的准确提交上创建并推送 release tag，并按需创建 Forge Release、
|
||||
恢复中断流程或安全清理。用户要求开始发布相关的新版本、为发布开 worktree 或分支、
|
||||
升版本、提交或合并发布 PR/MR、打 release tag、完成发版、处理 hotfix 或继续未完成
|
||||
发布时使用。只做普通编码、普通 worktree 或 PR/MR 操作、代码审查、构建或上传
|
||||
DEB/Docker 等产物、管理仓库权限时不使用。
|
||||
---
|
||||
|
||||
# Manage Release
|
||||
|
||||
根据项目现有规则管理源码版本生命周期。把项目策略当作规则来源，把 Git 与代码托管
|
||||
平台的实时状态当作运行状态；不要创建另一份会与分支、PR/MR 或 tag 分叉的状态文件。
|
||||
|
||||
## 按需读取参考资料
|
||||
|
||||
- 开始任何流程时读取 [project-policy.md](references/project-policy.md)，确定策略来源和默认值。
|
||||
- 需要选择、更新或核对版本号时读取 [versioning.md](references/versioning.md)。
|
||||
- 需要 push、创建或合并 PR/MR、创建 Forge Release 时读取
|
||||
[forge-adapters.md](references/forge-adapters.md)。
|
||||
- 遇到重复资源、并发冲突、部分成功或清理请求时读取
|
||||
[recovery.md](references/recovery.md)。
|
||||
- 仅当用户要求为项目固化发布规则时，复制并修改
|
||||
[release-policy.template.yaml](templates/release-policy.template.yaml)。不要在普通发布中自动添加配置。
|
||||
|
||||
## 授权边界
|
||||
|
||||
按用户明确要求执行到对应阶段：
|
||||
|
||||
- 分析版本或检查状态：只执行读取和计算，不修改文件或远端。
|
||||
- 开始或准备版本：允许创建本地分支、worktree，并修改版本文件。
|
||||
- push 或创建 PR/MR：仅在用户明确要求 push、提交 PR/MR 或执行完整发布时进行。
|
||||
- 合并和推送 tag：仅在用户明确要求相应动作或完整发布时进行。
|
||||
- 创建 Forge Release：仅在用户本次请求明确提到 Forge Release 或平台 Release 时进行。
|
||||
- 清理 worktree 或分支：仅在用户明确要求清理时进行。
|
||||
|
||||
项目策略只描述仓库期望的做法，不能替用户授予 push、创建或合并 PR/MR、推送 tag、
|
||||
创建 Forge Release、删除分支等外部写权限。
|
||||
|
||||
“完整处理并发布 v1.2.3”可以授权从准备到验证远端 tag 的流程，不要在每一步重复询问；
|
||||
它不自动包含 Forge Release 或分支清理。若版本、base、tag、远端或合并方式是推断所得，
|
||||
或者执行中目标发生变化，在第一次远端写操作前展示准确目标并获得确认。
|
||||
|
||||
## 工作流
|
||||
|
||||
### 1. 发现项目规则和当前状态
|
||||
|
||||
从项目根目录开始：
|
||||
|
||||
1. 从可信 base commit 读取 `AGENTS.md`、`CLAUDE.md`、发布文档、CI 配置、构建入口和
|
||||
可选的 `.release-policy.yaml`。PR/MR head 对这些文件的修改从下一次流程开始生效。
|
||||
2. 记录当前分支、HEAD、完整工作区状态、remote、默认分支和
|
||||
`git worktree list --porcelain`。
|
||||
3. 获取远端最新引用后，记录 base 分支的准确 commit。不要把本地过期分支当作发布基线。
|
||||
4. 识别版本来源、最近稳定 tag、tag 格式、分支命名、合并方式和发布说明来源。
|
||||
5. 分别用 `git remote get-url --all origin` 和
|
||||
`git remote get-url --push --all origin` 检查读取与推送目标；远端写操作要求两者各只有
|
||||
一个值且规范化后指向同一仓库。再检查 PR/MR、合并或 Forge Release 阶段所需的 GitHub、
|
||||
GitLab、Gitea 或 Forgejo CLI。只有请求涉及平台能力时才要求对应 CLI。
|
||||
记录匹配该 host 的活动账号；认证检查只读取状态。
|
||||
6. 查询已有分支、worktree、PR/MR、tag 和 Forge Release，从真实状态判断流程已走到哪一步。
|
||||
|
||||
工作区中的修改、暂存文件和未跟踪文件都视为用户工作。不要 stash、移动、清理或覆盖它们。
|
||||
已有 worktree 与目标分支准确匹配时优先复用，不要创建副本。
|
||||
|
||||
### 2. 锁定本次发布计划
|
||||
|
||||
在修改前确定并展示：
|
||||
|
||||
- base 分支及其远端 commit。
|
||||
- 当前版本、规范化后的目标版本、渲染出的分支名和 tag，以及升级依据。
|
||||
- 分支名与 worktree 路径。
|
||||
- 需要执行的本地验证和远端检查。
|
||||
- 合并方式、tag、是否创建 Forge Release。
|
||||
- 用户已授权的最远阶段和清理范围。
|
||||
|
||||
项目没有约定时，单一协调版本使用 SemVer、`release/v<version>` 分支、
|
||||
`v<version>` annotated tag。仓库只启用一种合并方式时使用该方式；存在多种方式且没有
|
||||
项目规则时默认 squash。默认不删除远端分支，不自动创建 Forge Release。
|
||||
|
||||
把用户输入拆成“规范版本”和“展示名称”：默认 SemVer 的规范版本是无 `v` 前缀的
|
||||
`1.6.0`，版本文件和 `{version}` 都使用该值；分支与 tag 再分别按 pattern 渲染为
|
||||
`release/v1.6.0` 和 `v1.6.0`。用户输入 `v1.6.0` 时先规范化，不要产生双前缀。
|
||||
|
||||
### 3. 创建或复用隔离 worktree
|
||||
|
||||
优先使用当前环境提供的 worktree 管理器；项目仓库中的管理脚本只有在可信 base 已声明
|
||||
且经过检查时才能使用，没有时使用原生 Git。创建前验证：
|
||||
|
||||
- 目标分支和目录未被其他 worktree 占用。
|
||||
- 目标目录不是 `/`、用户主目录、仓库根目录或已有非空目录。
|
||||
- base 使用刚获取的远端引用，例如 `origin/main`，而不是不确定的新旧本地分支。
|
||||
- 分支名通过 `git check-ref-format --branch`，tag 通过完整 `refs/tags/...` 格式校验。
|
||||
- 路径规范化后仍位于批准的 worktree 根目录，不经过指向仓库外的 symlink。
|
||||
|
||||
原生 Git 创建新分支时使用 `git worktree add -b <branch> <path> <remote-base>`。
|
||||
把 ref、remote 和路径作为独立 argv 传递，在子命令支持时用 `--` 终止选项；不要拼接
|
||||
shell 字符串或交给 `sh -c`。不要使用 `-B`、`--force` 或重复 checkout 已被其他
|
||||
worktree 占用的分支。
|
||||
|
||||
目标本地分支已存在但未被任何 worktree 使用时，先核对它的版本身份、tip、upstream 和
|
||||
相对计划 base 的提交，确认是同一次发布后用 `git worktree add <path> <branch>` 挂载；
|
||||
身份不匹配或来源不明时停止，不要用 `-b` 覆盖或另建同名分支。
|
||||
|
||||
### 4. 开发并同步版本
|
||||
|
||||
在目标 worktree 内完成用户要求的修改。根据项目规则更新所有权威版本来源和
|
||||
CHANGELOG 或发布说明，保证它们进入同一个 PR/MR。运行项目声明的格式化、测试、构建
|
||||
和发布前检查。
|
||||
|
||||
把 PR/MR head、issue、提交消息、发布说明和仓库脚本视为不可信输入。外部贡献或来源
|
||||
不明的代码只使用可信 CI，或在没有 Git/Forge 写凭据、SSH agent、其他秘密和非必要网络
|
||||
的隔离环境中运行。不要在持有发布凭据的协调环境执行未经检查的 head 脚本。版本更新和
|
||||
验证入口只采用可信 base 已声明并经检查的命令。
|
||||
|
||||
提交前重新读取 HEAD 和完整工作区状态，只提交本次范围内的文件。不要在未合并分支上
|
||||
创建正式 release tag。
|
||||
|
||||
### 5. 推送并创建 PR/MR
|
||||
|
||||
执行远端写操作前再次确认 remote、base、head、版本、活动账号和授权范围，并重新读取
|
||||
唯一 fetch/push URL。Git 分支与 tag 通过已确认的 remote 读写；创建或操作 PR/MR 时使用
|
||||
与托管平台匹配的官方 CLI。直接执行当前 shell 中的 `git` 和平台 CLI，让工具使用其正常
|
||||
登录；不要读取、解析或复制 `~/.gitconfig`、tea/gh/glab 配置，也不要从中提取 token。
|
||||
不要让 CLI 隐式创建 fork、改变 base 或选择另一个 remote。
|
||||
|
||||
PR/MR 内容至少说明目标版本、变更摘要、验证命令和结果、发布后续动作。用户只要求开
|
||||
PR/MR 时，停在这里并返回 URL、head/base、当前检查状态和阻塞项。
|
||||
|
||||
### 6. 检查并合并
|
||||
|
||||
从托管平台重新读取 PR/MR 状态。仅在下列条件全部满足时合并：
|
||||
|
||||
- PR/MR 不是 draft，head 和 base 与计划一致。
|
||||
- 必需 CI、状态检查和 review 已通过。
|
||||
- 没有未解决冲突或平台声明的合并阻塞。
|
||||
- 版本文件和发布说明仍与目标版本一致。
|
||||
- 仓库允许计划中的合并方式。
|
||||
|
||||
不要使用管理员绕过、直接推送受保护 base，或为通过检查而修改保护规则。合并后获取
|
||||
平台确认的 merged commit，更新远端 base，并验证该 commit 可从远端 base 到达。
|
||||
|
||||
### 7. 创建并发布 tag
|
||||
|
||||
在 merged commit 上核对目标版本后，再查询一次远端同名 tag。tag 不存在时创建
|
||||
annotated tag；项目要求签名时，必须先确认签名工具和密钥可用，创建 signed tag，并在
|
||||
本地验证签名成功后才允许 push。签名不可用或验证失败时停止，不得降级为 unsigned tag。
|
||||
显式指定 merged commit，并只推送这个 tag。
|
||||
|
||||
同名远端 tag 已存在且指向其他 commit 时立即停止。不要覆盖、删除或移动已经发布的
|
||||
tag。推送后读取远端 tag，并将 annotated tag 解引用到 commit，确认它与 merged commit
|
||||
完全相同。
|
||||
|
||||
仅当用户本次请求明确要求时创建 Forge Release；项目策略只能说明创建方式，不能授予
|
||||
外部写权限。必须引用已经存在并验证过的 tag，禁止让平台从默认分支隐式创建 tag。
|
||||
发布说明中的每项变化都应能追溯到本次 PR/MR、提交或项目 CHANGELOG。
|
||||
|
||||
### 8. 验证、恢复和清理
|
||||
|
||||
分别报告以下状态，不要用“发布成功”掩盖其中某一步未完成：
|
||||
|
||||
- 版本文件和本地验证。
|
||||
- PR/MR URL、合并状态和 merged commit。
|
||||
- 远端 tag 及其解引用后的 commit。
|
||||
- Forge Release URL 和可见性，若本次要求创建。
|
||||
- worktree、本地分支和远端分支是否保留。
|
||||
|
||||
清理时只移除干净且已确认不再使用的 linked worktree，不使用强制删除。删除本地或远端
|
||||
分支前确认其提交已合并且可从 base 或 tag 到达；本地和远端分支删除都必须有明确授权。
|
||||
|
||||
## 硬停止条件
|
||||
|
||||
遇到以下任一情况时停止相应写操作并说明恢复路径：
|
||||
|
||||
- base、目标版本、版本来源、remote，或请求阶段所需的托管平台无法唯一确定。
|
||||
- 项目策略包含未知字段、错误类型、仓库外路径或不安全 ref。
|
||||
- 多个权威版本来源不一致。
|
||||
- 目标分支、worktree、PR/MR、tag 或 release 已存在但身份不匹配。
|
||||
- required checks、review 或冲突状态不满足合并规则。
|
||||
- 合并结果的准确 commit 无法从平台确认，或无法从远端 base 到达。
|
||||
- 远端 tag 已指向其他 commit。
|
||||
- 请求的 PR/MR、合并或 Forge Release 阶段所需的平台 CLI 缺失、未认证或无法读取状态。
|
||||
- 项目要求 tag 签名，但签名能力不可用或本地签名验证失败。
|
||||
- 操作需要 force push、管理员绕过、移动已发布 tag 或覆盖用户工作。
|
||||
- 不可信代码只能在带仓库写凭据、SSH agent、秘密或非必要网络的环境中运行。
|
||||
|
||||
不要在命令参数、文件、提交、PR/MR、日志或最终回复中暴露 token、密码、私钥路径或
|
||||
认证配置。CLI 不可用时给出人工交接信息，不要擅自改用带 token 的 `curl`。
|
||||
|
||||
## 完成标准
|
||||
|
||||
只分析时，给出当前状态、建议版本、依据和下一步。开始版本时，给出 worktree 路径、
|
||||
分支和基线 commit。创建 PR/MR 时，给出 URL 与检查状态。合并时，给出 merged commit。
|
||||
发布 tag 时，证明远端 tag 解引用到该 commit。创建 Forge Release 时，再给出 release URL
|
||||
与可见性。任何部分未完成都要标明阻塞阶段和可恢复动作。
|
||||
@@ -0,0 +1,81 @@
|
||||
# 代码托管平台适配
|
||||
|
||||
## 区分 Git 与 Forge 能力
|
||||
|
||||
fetch、查询 remote refs、推送分支和推送单个 tag 属于 Git transport 能力，可直接通过
|
||||
已配置的 Git remote 完成。创建或查看 PR/MR、合并以及创建 Forge Release 才需要平台
|
||||
CLI。只发布 tag 时，不要因为缺少 Forge CLI 而停止；仍要验证 remote、认证目标和推送
|
||||
授权，并在 push 后读回远端 ref。
|
||||
|
||||
## 选择 Forge 适配器
|
||||
|
||||
从 push remote URL 识别平台，并使用对应官方 CLI：
|
||||
|
||||
| 平台 | CLI | PR/MR 命令域 | Release 命令域 |
|
||||
|---|---|---|---|
|
||||
| GitHub | `gh` | `gh pr` | `gh release` |
|
||||
| GitLab | `glab` | `glab mr` | `glab release` |
|
||||
| Gitea / Forgejo | `tea` | `tea pulls` | `tea releases` |
|
||||
|
||||
先运行 CLI 的版本、认证状态和只读查看命令。记录匹配 remote host 的活动账号；存在多
|
||||
个账号或 profile 时，必须唯一确定本次使用的身份。CLI 版本之间的 flags 可能不同，
|
||||
每次执行写操作前读取对应子命令的 `--help`，不要凭记忆拼接参数。
|
||||
|
||||
直接从目标 worktree 的当前 shell 运行 `git` 与平台 CLI，让它们使用各自正常的登录机制。
|
||||
Gitea/Forgejo 使用 `tea whoami` 和 `tea` 对应子命令；不要由 Agent 读取 tea 配置文件、
|
||||
调用 credential helper 导出 token，或把 token 转存到命令参数、环境文件和发布说明。
|
||||
|
||||
当请求确实涉及 PR/MR、合并或 Forge Release，且 remote host 无法识别、CLI 缺失、认证
|
||||
失败或 CLI 指向另一个实例时，停止对应平台阶段并报告：
|
||||
|
||||
- host、owner/repository、remote 名称。
|
||||
- base、head 和当前 commit。
|
||||
- 已完成的本地验证。
|
||||
- 尚需人工执行的创建 PR/MR、合并或 release 步骤。
|
||||
|
||||
不要自动安装 CLI，也不要把 token 放进命令行后改用 `curl`。用户明确提供受支持的其他
|
||||
集成时，可以使用该集成，但仍遵守同一套授权和验证闸门。
|
||||
|
||||
## 创建 PR/MR
|
||||
|
||||
使用显式的 repository、base、head、title 和 body，避免交互式默认值改变目标。把动态
|
||||
值作为独立 argv 或结构化输入传递，不拼接 shell 命令。创建前：
|
||||
|
||||
1. 确认当前分支已经推送到计划中的 remote。
|
||||
2. 查询同一 head/base 是否已有 open PR/MR，有则复用并更新状态，不重复创建。
|
||||
3. 确认 head commit 与本地已验证 commit 相同。
|
||||
4. 确认 CLI 不会隐式创建 fork 或推送到另一个 remote。
|
||||
5. 再次读取活动账号，向用户展示 host、repository、账号和授权的最远阶段。
|
||||
|
||||
PR/MR body 包含目标版本、变更摘要、验证命令与结果、发布后续。创建后读取平台返回的
|
||||
URL、编号、head/base 和状态，不以命令退出码代替远端读回。
|
||||
|
||||
## 检查和合并
|
||||
|
||||
用结构化输出读取 draft、head commit、base、review、required checks、冲突或
|
||||
mergeability、允许的合并方式。平台字段缺失时，使用平台提供的只读详情命令补足；不能
|
||||
证明闸门通过时保持未合并。
|
||||
|
||||
GitHub 使用 `gh pr view`、`gh pr checks` 和 `gh pr merge`；GitLab 使用
|
||||
`glab mr view`、pipeline 状态和 `glab mr merge`；Gitea 或 Forgejo 使用
|
||||
`tea pulls` 的查看、检查和合并能力。实际参数以当前 CLI 的 `--help` 为准。
|
||||
|
||||
若用户要求检查通过后自动合并，优先使用仓库已经启用的 auto-merge 或 merge queue。
|
||||
不要用管理员选项绕过 review、CI、conversation resolution 或 protected branch。
|
||||
|
||||
合并后重新读取 PR/MR，取得平台确认的 merged commit。随后 fetch 远端 base，并验证该
|
||||
commit 已进入远端 base。只看到本地 merge commit 或分支关闭不足以证明平台已合并。
|
||||
|
||||
## 创建 Forge Release
|
||||
|
||||
把 Git tag 和 Forge Release 当成两个独立状态。先创建、推送并验证 tag，再创建 release。
|
||||
|
||||
- GitHub 创建 release 时使用能够拒绝缺失 tag 的选项，例如当前 CLI 支持的
|
||||
`--verify-tag`。
|
||||
- GitLab、Gitea 或 Forgejo 创建 release 前，先用只读命令证明 tag 已存在并指向计划的
|
||||
commit；不要使用会顺便创建 tag 的默认行为。
|
||||
- 预发布版本按项目规则标记 prerelease，不要自动把它标为 latest 或 stable。
|
||||
- 发布后重新读取 release URL、tag 和可见性。
|
||||
|
||||
Forge Release 创建失败但 tag 已成功推送时，保留 tag 并从 release 阶段恢复，不要重新
|
||||
合并或创建另一个 tag。
|
||||
@@ -0,0 +1,73 @@
|
||||
# 项目发布策略
|
||||
|
||||
## 策略优先级
|
||||
|
||||
按以下顺序确定规则，并在来源冲突时停止说明，不要静默覆盖：
|
||||
|
||||
1. 用户本次请求中明确给出的目标和授权范围。
|
||||
2. 项目 `AGENTS.md`、`CLAUDE.md`、发布文档和可选的 `.release-policy.yaml`。
|
||||
3. 构建脚本、包清单、CI 工作流和历史发布使用的实际入口。
|
||||
4. 代码托管平台当前的默认分支、保护规则、检查和允许的合并方式。
|
||||
5. 本 Skill 的默认值。
|
||||
|
||||
用户请求若与项目硬规则或平台保护冲突，展示冲突并请求处理方式。不要借用户的一句
|
||||
“直接发布”绕过仓库声明的检查或保护。
|
||||
|
||||
开始流程时记录 base commit，并读取该提交对应的项目策略。本次发布分支对策略文件的
|
||||
修改不应改变正在执行的流程；新策略从下一次发布开始生效。
|
||||
|
||||
项目策略不能授予外部写权限。即使配置声明创建 Forge Release 或删除远端分支，也必须
|
||||
由用户本次请求明确授权相应动作。
|
||||
|
||||
## 可选配置
|
||||
|
||||
项目反复出现同一种歧义时，用户可以要求创建 `.release-policy.yaml`。从
|
||||
`templates/release-policy.template.yaml` 复制后，只保留项目真正需要固定的字段。
|
||||
|
||||
配置只保存可提交的项目策略：
|
||||
|
||||
- `schema`：配置结构版本，当前为 `1`。
|
||||
- `base_branch`：发布 PR/MR 的目标分支。
|
||||
- `branch_pattern`：版本分支格式，支持无展示前缀的规范 `{version}`。
|
||||
- `version.scheme`：`semver` 或项目已经使用的其他方案。
|
||||
- `version.sources`：构建和运行实际读取的权威版本文件。
|
||||
- `tag_pattern`：release tag 格式，支持无展示前缀的规范 `{version}`。
|
||||
- `merge_method`：`squash`、`merge` 或 `rebase`。
|
||||
- `forge_release`：项目是否建议在 tag 后创建 Forge Release；它不授予创建权限。
|
||||
- `tag_signing`：`off`、`optional` 或 `required`。
|
||||
- `delete_remote_branch`：发布完成后是否建议清理远端源分支；它只是计划偏好，不是删除
|
||||
权限或自动执行指令，仍需用户在本次请求中明确授权。
|
||||
|
||||
不要在配置中保存 token、账号、私钥路径、个人工作目录或一次性发布状态。不要加入任意
|
||||
shell 命令字段；本地验证继续从项目文档、CI 和构建入口发现。
|
||||
|
||||
读取配置后校验字段集合、类型和枚举值，遇到未知字段时停止。`branch_pattern` 和
|
||||
`tag_pattern` 展开后分别用 Git branch/tag ref 规则校验；不要把配置值拼进 shell 字符串。
|
||||
`version.sources` 中每一项必须是仓库相对路径，拒绝绝对路径和 `..`。规范化并解析
|
||||
symlink 后，目标必须仍在当前 worktree 内；权威来源通常还应由 Git 跟踪。
|
||||
|
||||
先按版本方案把用户输入规范化。默认 SemVer 接受 `1.6.0` 或作为用户输入的 `v1.6.0`，
|
||||
但内部 `{version}` 固定为 `1.6.0`；版本文件写入规范值，branch/tag pattern 分别负责添加
|
||||
展示前缀。自定义版本方案按项目文档定义规范值，不能从 pattern 猜测后重复添加前缀。
|
||||
|
||||
## 无配置时的发现顺序
|
||||
|
||||
1. 从 remote HEAD 和平台信息确定默认 base，不能确定时询问。
|
||||
2. 从项目文档、CI 和构建入口找版本文件及更新方式。
|
||||
3. 从已有分支和已合并 PR/MR 识别命名与合并方式。
|
||||
4. 从稳定 tag 识别前缀和版本方案，只把 tag 当作交叉验证。
|
||||
5. 无项目约定时使用 `release/v<version>`、SemVer、`v<version>` annotated tag 和
|
||||
squash merge；默认不创建 Forge Release，不删除远端分支。
|
||||
|
||||
## 每次执行的计划快照
|
||||
|
||||
在第一次写操作前列出以下事实：
|
||||
|
||||
- base 分支和远端 commit。
|
||||
- 当前版本、目标版本、版本来源和升级依据。
|
||||
- worktree 路径与分支名。
|
||||
- PR/MR 托管平台和合并方式。
|
||||
- tag 与 Forge Release 计划。
|
||||
- 用户授权的最远阶段和清理范围。
|
||||
|
||||
任何事实在执行中改变时刷新计划。改变会影响已授权的远端写目标时，再次获得确认。
|
||||
@@ -0,0 +1,52 @@
|
||||
# 中断恢复与安全清理
|
||||
|
||||
## 恢复原则
|
||||
|
||||
每次重入都从 Git 和代码托管平台读取状态，不依赖上一轮聊天结论。先记录准确的
|
||||
base、head、PR/MR、merged commit、tag 和 release，再执行唯一缺失的下一步。
|
||||
|
||||
网络或平台调用返回超时、未知状态或非结构化错误时，先用只读命令刷新远端状态。不要把
|
||||
重试当成默认动作；创建 PR/MR、合并、推 tag 和创建 release 都可能已经成功。
|
||||
|
||||
## 常见部分状态
|
||||
|
||||
| 当前状态 | 继续方式 | 禁止事项 |
|
||||
|---|---|---|
|
||||
| worktree 已创建，无改动 | 继续开发，或经授权移除干净 worktree | 不使用强制删除 |
|
||||
| 本地发布分支已存在，没有 worktree | 核对版本身份、tip、upstream 和 base 后挂载现有分支 | 不用 `-b` 覆盖分支 |
|
||||
| 分支已推送，没有 PR/MR | 确认 head/base 后创建一次 PR/MR | 不重复推送新分支 |
|
||||
| PR/MR 已存在，未合并 | 复用 URL，刷新 checks、review 和冲突状态 | 不创建第二个 PR/MR |
|
||||
| PR/MR 已合并，没有 tag | 获取 merged commit，在该 commit 上继续发布 | 不重新合并 |
|
||||
| tag 已推送，没有 release | 验证 tag 后创建 Forge Release | 不创建替代 tag |
|
||||
| release 已创建，验证未完成 | 读回 release、tag 和可见性 | 不直接声称发布完成 |
|
||||
| 同名资源身份不匹配 | 停止并报告差异 | 不覆盖、关闭或删除未知资源 |
|
||||
|
||||
## 并发冲突
|
||||
|
||||
两个 Agent 或维护者可能同时准备相同版本。创建分支、PR/MR、tag 或 release 前都重新查询
|
||||
目标是否存在。推 tag 前立即检查远端引用；push 因同名引用失败时保持失败，不要 force。
|
||||
|
||||
base 在开发期间前进时，让 PR/MR 和仓库规则决定是否需要更新分支。已经推送的发布分支
|
||||
不在本 Skill 中重写历史；需要更新时优先创建普通提交，或交给平台的 update branch、
|
||||
merge queue 和 auto-merge。任何 force push 都是硬停止条件。
|
||||
|
||||
## 回滚边界
|
||||
|
||||
- 未推送的本地版本提交可以在用户授权下修改或放弃，但不要覆盖其他工作。
|
||||
- 已推送但未合并的 PR/MR 可以关闭，分支默认保留。
|
||||
- 已合并变更通过新的 revert PR/MR 回滚，不重写 base 历史。
|
||||
- 已发布 tag 默认不可变。tag 错误时停止，由维护者决定撤销发布或发布新版本。
|
||||
- Forge Release 失败不回滚已经正确推送的 tag；从 release 阶段恢复。
|
||||
|
||||
## 清理规则
|
||||
|
||||
清理始终放在发布验证之后：
|
||||
|
||||
1. 确认 worktree 没有修改、暂存或未跟踪文件。
|
||||
2. 确认分支提交已从远端 base 或已验证 tag 到达。
|
||||
3. 仅移除目标 linked worktree，不操作主 worktree，不使用 `--force`。
|
||||
4. 删除本地分支前再次确认已合并。
|
||||
5. 删除本地或远端分支都必须有用户本次请求的明确授权；项目策略不能代替授权。
|
||||
6. 使用 `git worktree prune --dry-run` 查看陈旧记录；不要把 prune 当作普通清理步骤。
|
||||
|
||||
任何清理条件不满足时保留现场，并报告路径、分支、未提交状态和后续人工动作。
|
||||
@@ -0,0 +1,79 @@
|
||||
# 版本号与 tag
|
||||
|
||||
## 确定权威版本来源
|
||||
|
||||
按项目实际构建链路寻找版本来源，不要遍历到一个看起来像版本号的字符串就修改。优先级：
|
||||
|
||||
1. 项目发布文档或 `.release-policy.yaml` 明确声明的文件。
|
||||
2. 构建、打包或运行入口直接读取的清单，例如 `VERSION`、`package.json`、
|
||||
`pyproject.toml`、`Cargo.toml` 或语言工具链的版本配置。
|
||||
3. 由权威文件生成的镜像文件、锁文件或发布元数据。
|
||||
4. 最近稳定 tag，只用于验证当前版本和发布历史。
|
||||
|
||||
记录每个权威文件的当前值和更新方式。多个权威来源不一致时停止，不要选择修改时间最新
|
||||
的文件，也不要只改其中一个。
|
||||
|
||||
配置声明的版本文件必须使用仓库相对路径。拒绝绝对路径、`..` 和解析后逃出目标
|
||||
worktree 的 symlink；修改前确认规范化后的准确路径。不要用 glob 或模糊搜索结果执行
|
||||
批量替换。
|
||||
|
||||
## 选择目标版本
|
||||
|
||||
项目已有 CalVer、单调构建号、独立包版本或自定义方案时继续使用，不要迁移到 SemVer。
|
||||
项目没有规则且只有一个协调版本时使用 SemVer：
|
||||
|
||||
- 不兼容的公开 API 或行为变化增加 major。
|
||||
- 向后兼容的新功能增加 minor。
|
||||
- 向后兼容的修复增加 patch。
|
||||
|
||||
根据实际兼容性判断，不要只凭 commit 前缀自动升级。项目明确采用 Conventional Commits
|
||||
或已有版本工具时，可以把它们的结果作为项目规则。破坏性影响无法确定时给出建议并请
|
||||
用户确定准确版本。
|
||||
|
||||
预发布版本沿用项目格式；没有格式时使用 `-alpha.N`、`-beta.N` 或 `-rc.N`。正式 tag
|
||||
默认不加入 build metadata。不要从带 build metadata 的 tag 推断兼容性顺序。
|
||||
|
||||
独立多包版本、多个维护分支和 release train 不属于默认单版本流程。无法确定一个目标
|
||||
版本时停止并说明需要增加包或发布线维度。
|
||||
|
||||
## 规范化与渲染
|
||||
|
||||
内部始终分别记录规范版本、分支名和 tag 名。默认 SemVer 的规范版本不含 `v`，例如
|
||||
用户输入 `v1.6.0` 时规范化为 `1.6.0`；版本文件写入 `1.6.0`，再将它代入
|
||||
`release/v{version}` 和 `v{version}`。不要把完整 tag 名直接代入 `{version}`。
|
||||
|
||||
项目采用自定义前缀或非 SemVer 时，以项目版本来源定义规范值，以 branch/tag pattern
|
||||
定义展示形式。规范化结果无法唯一确定时停止并让用户确认。
|
||||
|
||||
## 同步版本
|
||||
|
||||
在发布分支中一次性更新所有权威版本来源、生成文件和项目要求的 CHANGELOG。运行项目
|
||||
自己的版本更新工具时，先检查它会修改哪些文件，避免隐式发布、提交或上传。
|
||||
|
||||
提交前确认：
|
||||
|
||||
- 所有权威来源都是目标版本。
|
||||
- 生成文件与来源一致。
|
||||
- CHANGELOG 或发布说明描述的是本次实际变更。
|
||||
- 项目构建和测试读取到了新版本。
|
||||
|
||||
## 验证 merged commit
|
||||
|
||||
合并后以代码托管平台返回的 merged commit 为准。获取远端 base 后，确认该 commit 可从
|
||||
远端 base 到达，并直接读取该 commit 中的版本文件。不要用仍停留在 feature worktree
|
||||
中的文件证明已合并版本。
|
||||
|
||||
正式 tag 必须满足：
|
||||
|
||||
- tag 名按项目格式由目标版本唯一生成。
|
||||
- 远端没有同名 tag，或同名 tag 已经准确指向本次 commit。
|
||||
- annotated tag 显式指向 merged commit。
|
||||
- 项目要求签名时，push 前已成功创建 signed tag，并在本地验证签名通过；不可用或失败
|
||||
时停止，不得改用 unsigned tag。
|
||||
- 推送后从远端重新读取，并将 annotated tag 解引用到 commit。
|
||||
|
||||
展开 tag pattern 后用 `git check-ref-format refs/tags/<tag>` 校验。把 tag 和 commit 作为
|
||||
独立 argv 传递，不拼接 shell 字符串。
|
||||
|
||||
tag 已在远端指向其他 commit 时停止。不要 force push、删除或移动已发布 tag；由维护者
|
||||
决定撤销发布或创建新的修订版本。
|
||||
@@ -0,0 +1,17 @@
|
||||
# 复制为项目根目录的 .release-policy.yaml，并按项目实际约定修改。
|
||||
# 此文件描述发布策略，不授予任何远端写操作权限。
|
||||
schema: 1
|
||||
base_branch: main
|
||||
# {version} 是规范版本，例如 1.6.0；前缀由 pattern 添加。
|
||||
branch_pattern: release/v{version}
|
||||
version:
|
||||
scheme: semver
|
||||
sources:
|
||||
- VERSION
|
||||
tag_pattern: v{version}
|
||||
merge_method: squash
|
||||
# 只表示项目偏好；创建 Forge Release 仍需用户本次请求明确授权。
|
||||
forge_release: false
|
||||
tag_signing: optional
|
||||
# 只表示清理偏好；删除仍需用户在本次请求中明确授权。
|
||||
delete_remote_branch: false
|
||||
@@ -0,0 +1,72 @@
|
||||
# orc
|
||||
|
||||
ORC 是显式调用的薄路由器：只把开发、版本发布、DEB 和 Docker 意图映射成阶段，
|
||||
按静态配置选择 `low`、`mid` 或 `high` worker，再交给对应 Skill。
|
||||
|
||||
## 什么时候使用
|
||||
|
||||
- 一个请求同时包含写代码、发版本和构建产物。
|
||||
- 希望由 ORC 监督多个 Agent，并按阶段控制成本与推理能力。
|
||||
- 需要继续中断的多阶段工程流程并保留依赖关系。
|
||||
|
||||
只做单一领域任务时可以直接调用对应 Skill；ORC 不替代它们的安全规则。
|
||||
|
||||
## 使用前准备
|
||||
|
||||
- Orca 正在运行并启用了 orchestration。
|
||||
- 安装本次需要的 `$ack`、`$manage-release`、`$deb-publisher` 或
|
||||
`$publish-docker-image`。
|
||||
- ORC 直接使用 skill 内共享的 `config.yaml`，不需要在每个项目初始化配置。修改这份
|
||||
配置会影响所有项目；旧的项目级 `docs/orc/config.yaml` 不再参与解析。
|
||||
- `/usr/bin/python3`；ORC v2 配置必须保持为 JSON-compatible YAML。
|
||||
resolver 以 `-I -S` 隔离模式运行，不加载项目模块、用户 site-packages 或第三方解析器。
|
||||
- ORC v2 worker 使用 `workspace-write` sandbox，以便发送 Orca lifecycle 消息；
|
||||
只读任务会在阶段 prompt 中禁止文件修改。
|
||||
- release worker 是受信任的发布角色，直接调用当前 shell 中已认证的 `git` 与 Forge CLI
|
||||
（Gitea/Forgejo 使用 `tea`）；ORC 不读取认证配置，也不注入 credential helper。
|
||||
- release 阶段要求 `origin` 只有一个且一致的 fetch/push URL。Codex 只为该阶段开启网络，
|
||||
并用 network proxy 把出站目标限制到 remote/Forge API host；GitHub 额外允许其固定 API
|
||||
与 release upload host，其它本地阶段默认继续禁网。
|
||||
|
||||
## Worker 档位
|
||||
|
||||
| 档位 | 典型任务 |
|
||||
|------|----------|
|
||||
| `low` | 输入明确的测试、构建、打包和上传 |
|
||||
| `mid` | 常规版本发布与范围清晰的工程任务 |
|
||||
| `high` | 需求理解、跨系统改动、异常恢复和高风险裁决 |
|
||||
|
||||
档位不是权限。三个档位仍受各自 profile 和下游 Skill 的授权边界约束。
|
||||
这些档位只选择下游 worker，不会切换当前 ORC Coordinator 已经使用的模型。
|
||||
结构化启动适配器支持 Codex 与 Cursor worker，并固定跟随当前宿主：从 Codex 调用就使用
|
||||
Codex，从 Cursor 调用就使用 Cursor。共享配置为两个 CLI 分别维护三档模型，不设置跨宿主
|
||||
默认值。
|
||||
|
||||
## 使用示例
|
||||
|
||||
```text
|
||||
$orc high 修复登录问题，验证通过后发布新版本。
|
||||
$orc code=high release=mid docker=low，完成修复、发版并推送镜像。
|
||||
$orc low，检查并准备下一个版本，不执行远端写操作。
|
||||
$orc mid 继续上次中断的 v1.4.0 发布流程。
|
||||
```
|
||||
|
||||
阶段级档位优先于全局档位；未指定时只读取 `stageDefaults` / `defaultLevel`。ORC 不根据
|
||||
任务复杂度动态升降档；worker 报告能力不足时，ORC 只转发请求。
|
||||
|
||||
## Agent 会做什么
|
||||
|
||||
1. 识别开发、源码发布、DEB 与 Docker 意图，并按固定表建立阶段依赖。
|
||||
2. 从当前 Agent 的系统身份锁定宿主 CLI，再解析每个阶段的 profile，把共享配置快照、
|
||||
可信 Agent CLI executable 和真实 Git
|
||||
worktree 绑定成 launch fingerprint，并展示计划和外部写入边界。
|
||||
3. 通过 Orca 分发给对应 Skill，转发完成消息、异常和决策门。
|
||||
4. 按下游 Skill 声明的证据字段汇总状态和恢复入口，不重新做领域判断。
|
||||
|
||||
ORC 不分析实现、不建议版本、不评估发布风险、不选择合并或构建方案；这些工作全部属于
|
||||
下游 Skill。
|
||||
|
||||
## 如何判断完成
|
||||
|
||||
最终结果会逐阶段列出所用 Skill、Agent 档位、源 revision、远端或产物状态，以及任何
|
||||
未完成项。只有所有必要阶段都通过各自验证时，ORC 才会报告整个流程完成。
|
||||
@@ -0,0 +1,179 @@
|
||||
---
|
||||
name: orc
|
||||
description: >-
|
||||
作为薄路由器显式识别开发、源码版本发布、DEB 和 Docker 意图，把阶段分发给对应
|
||||
Skill，并按静态规则选择 low、mid、high 执行档位。仅在用户显式调用 $orc 或 /orc，
|
||||
要求跨阶段协调、指定 Agent 级别、监督多个 worker 或继续 ORC 编排时使用。
|
||||
---
|
||||
|
||||
# ORC 工程编排入口
|
||||
|
||||
当前会话担任薄路由器（Thin Coordinator）：只识别阶段、宿主 CLI、静态档位、依赖和
|
||||
授权边界，然后派发 worker、转发决策门并汇总结构化状态。ORC 不做领域判断，不替代
|
||||
下游 Skill 执行、分析或复核其领域流程。
|
||||
|
||||
开始时解析当前 `SKILL.md` 所在目录，记为 `<orc-skill-dir>`；解析真实项目根目录，
|
||||
优先使用 `git rev-parse --show-toplevel`。所有项目共享唯一配置
|
||||
`<orc-skill-dir>/config.yaml`，不得在项目中创建 `docs/orc/config.yaml` 或其它配置副本。
|
||||
|
||||
## 选择模式
|
||||
|
||||
- 用户要求初始化 ORC：说明 ORC 已改为共享配置、不需要项目初始化，然后执行“检查”。
|
||||
- 用户要求检查 ORC、CLI、档位或运行环境：执行“检查”。
|
||||
- 用户明确要求修改 ORC 的共享模型或档位默认值：执行“修改共享配置”。
|
||||
- 用户要求用 ORC 完成任务：执行“编排”。
|
||||
|
||||
配置或运行时无效时 fail closed，不退回裸命令或当前会话直接执行。
|
||||
|
||||
## 薄路由器边界
|
||||
|
||||
ORC 只执行以下机械步骤：
|
||||
|
||||
1. 把用户明确表达的意图映射到 `code`、`release`、`deb`、`docker`。
|
||||
2. 从系统身份映射宿主 CLI，并按显式覆盖或共享配置解析档位。
|
||||
3. 根据固定路由表建立任务依赖，生成满足契约的 worker prompt 并派发。
|
||||
4. 转发 `decision_gate` / `escalation`，按下游 Skill 的完成证据汇总状态。
|
||||
|
||||
不得阅读项目实现来形成技术判断，不得决定版本号、实现方案、测试策略、发布风险、
|
||||
合并方式或产物策略，不得代替 worker 执行命令。意图无法映射时报告范围外；缺少派发所需
|
||||
的关键输入时建立 decision gate。领域问题原样交给对应下游 Skill，不由 ORC 推理补全。
|
||||
|
||||
## 共享配置
|
||||
|
||||
`<orc-skill-dir>/config.yaml` 是 ORC profile 的 SSOT，对所有项目生效。配置使用
|
||||
JSON-compatible YAML，并由隔离的 Python 标准库解析。它固定包含：
|
||||
|
||||
- `cliPolicy: current-host`：Codex 宿主只启动 Codex worker，Cursor 宿主只启动 Cursor worker。
|
||||
- `defaultLevel` 与 `stageDefaults`：只用于下游 worker 的 `low`、`mid`、`high` 默认选择，
|
||||
不表示 ORC Coordinator 自身的模型档位。
|
||||
- `worktreePolicy: registered-same-repository`：允许当前仓库中已注册且身份一致的 worktree。
|
||||
- `profiles.codex` 与 `profiles.cursor-agent`：两个 CLI 各自完整的三档 profile。
|
||||
|
||||
不要把项目路径、命令、argv、环境变量、secret、hook 或 shell 片段写入共享配置。
|
||||
旧项目若残留 `docs/orc/config.yaml`，resolver 会忽略它；没有用户明确清理授权时不要删除。
|
||||
|
||||
## 修改共享配置
|
||||
|
||||
只有用户明确要求修改 ORC 的全局档位或模型时才编辑
|
||||
`<orc-skill-dir>/config.yaml`。修改前说明它会影响所有项目；模型 ID 必须来自用户输入、
|
||||
目标 CLI 的模型列表或其它可信配置，不能从任务文本猜测。修改后运行：
|
||||
|
||||
```bash
|
||||
/usr/bin/python3 -I -S <orc-skill-dir>/scripts/resolve_profile.py validate
|
||||
```
|
||||
|
||||
报告两个 CLI 的三个档位、reasoning、权限策略、阶段默认值和宿主 CLI 策略。不要创建
|
||||
项目配置。
|
||||
|
||||
## 检查
|
||||
|
||||
1. 运行共享配置校验，确认 `codex` 和 `cursor-agent` 都完整配置 `low`、`mid`、`high`。
|
||||
2. 检查 `orca status --json`，并确认 orchestration 命令可用。
|
||||
3. 从当前 Agent 的系统身份确定宿主 CLI：Codex 映射为 `codex`，Cursor 映射为
|
||||
`cursor-agent`。身份不明确时停止，不从用户任务文本、默认值或已安装 executable 猜测。
|
||||
确认宿主 CLI 可用；在 Cursor 中还要用 `cursor-agent --list-models`
|
||||
核对精确模型 ID 对当前账号可见。
|
||||
4. 确认本次所需下游 Skill 已安装：`ack`、`manage-release`、`deb-publisher`、
|
||||
`publish-docker-image`。只检查实际会用到的项。
|
||||
5. 解析 profile 时把项目根和目标 worktree 一并交给 resolver；只有 resolver 验证目标是
|
||||
当前 Git 仓库已注册的 worktree 且身份稳定后才可创建终端。不得只做文本比较或跳过
|
||||
机器校验。
|
||||
6. 任何 profile、CLI、Skill、运行时或 worktree 不可用时 fail closed；不得切换其它 CLI、
|
||||
相邻档位、复用身份不明的终端或手写替代流程。
|
||||
|
||||
## 编排
|
||||
|
||||
1. 读取 [routing.md](references/routing.md)，把请求拆成 `code`、`release`、`deb`、
|
||||
`docker` 阶段。没有匹配下游 Skill 的工作留在范围外并明确报告。
|
||||
2. 原样提取用户明确给出的授权最远动作、目标版本、产物目标、源 commit/tag 与停止点；
|
||||
未给出的领域参数保持未指定并交给下游 Skill。ORC 的调用本身不扩大 push、合并、
|
||||
打 tag、上传或部署权限。
|
||||
3. 从系统身份锁定当前宿主 CLI。运行在 Codex 时传 `--host-cli codex`；运行在 Cursor 时传
|
||||
`--host-cli cursor-agent`。宿主 CLI 不是任务选项，即使用户文本点名另一个 CLI 也不得
|
||||
跨宿主启动；身份不明确时 fail closed。
|
||||
4. 解析档位：阶段级指定 > 全局指定 > `stageDefaults` > `defaultLevel`。只接受
|
||||
`low`、`mid`、`high`；用户显式指定后不得静默升降级。ORC 不根据任务复杂度动态判断
|
||||
档位；worker 报告能力不足时，只转发 escalation 或 decision gate。
|
||||
5. 对每个阶段运行 profile resolver。宿主用必填的 `--host-cli`，全局档位用
|
||||
`--global-level`，阶段
|
||||
档位用 `--stage-level`；项目根与目标 worktree 必须使用规范绝对路径。Codex 默认复用
|
||||
`codex-login`，Cursor 默认复用 `cursor-login`；只有明确使用环境凭据时才分别选择
|
||||
`openai`、`azure-openai` 或 `cursor-api-key`。远端认证默认 `none`。release worker 作为
|
||||
受信任发布角色，直接调用当前 shell 中已认证的 `git` 与 Forge CLI；Gitea/Forgejo 由
|
||||
`$manage-release` 在目标 worktree 中运行 `tea`，resolver 不读取 tea 配置、不注入
|
||||
credential helper，也不把 tea token 转成环境变量。只有明确改用环境 token 或 SSH
|
||||
agent 时，才选择一个精确的 `github-token`、`gitlab-token`、`gitea-token`、
|
||||
`forgejo-token`、`ssh-agent` 或 `deb-token`，不得同时交给 worker 多组环境凭据。resolver
|
||||
不存在静默 fallback：
|
||||
|
||||
```bash
|
||||
/usr/bin/python3 -I -S <orc-skill-dir>/scripts/resolve_profile.py resolve \
|
||||
--stage <stage> \
|
||||
--project-root <absolute-project-root> \
|
||||
--worktree <absolute-target-worktree> \
|
||||
--host-cli <codex|cursor-agent> \
|
||||
[--global-level <low|mid|high>] [--stage-level <low|mid|high>] \
|
||||
[--model-auth <codex-login|openai|azure-openai|cursor-login|cursor-api-key>] \
|
||||
[--remote-auth <exact-provider-or-transport>]
|
||||
```
|
||||
|
||||
6. 核对 resolver 返回的 `launchFingerprint`、绝对 executable、worktree identity、CLI 与
|
||||
档位选择来源，再读取 [orca-adapter.md](references/orca-adapter.md)，把阶段组织为 Orca
|
||||
task DAG。worker prompt 必须显式写出对应 `$skill`、阶段范围、输入 revision、用户授权
|
||||
边界、验收证据和依赖结果；下游 Skill 无需知道 ORC。
|
||||
7. 监督 `worker_done`、`escalation` 与 `decision_gate`。`worker_done` 只代表该 worker
|
||||
回报完成；Coordinator 只核对下游 Skill 声明的证据字段和 DAG 后置条件，不重新进行
|
||||
领域审查。
|
||||
8. 逐阶段汇报所选 CLI、档位、执行 Skill、结果、外部状态和未完成项。任一阶段失败时
|
||||
保留已成功阶段的准确状态，说明安全恢复入口，不把部分成功概括成全部完成。
|
||||
|
||||
## 固定路由边界
|
||||
|
||||
- 功能、缺陷、重构与验证闭环交给 `$ack`。
|
||||
- 发布版本、release 分支/PR/MR、合并、tag 与 Forge Release 交给
|
||||
`$manage-release`。
|
||||
- DEB 构建或上传交给 `$deb-publisher`。
|
||||
- Docker/OCI 镜像构建或上传交给 `$publish-docker-image`。
|
||||
- 普通非发布 PR/MR 不伪装成版本发布；只有 ACK 已验证交付或明确的 release 流程才
|
||||
进入对应下游能力。
|
||||
|
||||
## 依赖与安全边界
|
||||
|
||||
- 依赖始终单向：`orc -> 下游 Skill`。不得要求 ACK 或其它下游 Skill 引用 ORC、读取
|
||||
ORC 配置或改变自身触发规则。
|
||||
- ORC 档位只选择阶段 worker。进入 `$ack` 后，ACK 自己的 Coordinator、Developer、
|
||||
Test 角色和 `standard/strong` 模型路由仍完全由 ACK 管理。
|
||||
- ORC 的 `code` 阶段必须锁定停止点：纯开发停在 ACK `verified`；用户明确要求普通
|
||||
PR/MR 时最多到 ACK `review_ready`。不得让 ACK 在同一阶段继续执行版本发布、DEB、
|
||||
Docker 或部署；这些动作由 ORC 的独立阶段负责。
|
||||
- ORC v2 的 `permissionMode` 固定为 `workspace-write`，因为受监督 worker 需要写入
|
||||
Orca 运行时目录才能发送 lifecycle 消息。只读任务仍由 prompt 限制不得改文件。
|
||||
- release 阶段必须绑定 `origin` 唯一且规范化后完全一致的 fetch/push URL，并把 remote
|
||||
identity 写入 fingerprint；多个 URL、独立 `pushurl` 或不支持的 remote 直接停止。
|
||||
- Codex release worker 固定使用 `on-request` 与 `auto_review`，开启
|
||||
`sandbox_workspace_write.network_access=true`，并用 network proxy 只允许绑定的 remote
|
||||
与确定性的 Forge API host。GitHub 固定追加 `api.github.com` 和 `uploads.github.com`；
|
||||
Gitea、Forgejo 与 GitLab 默认只使用 remote host。其它本地阶段默认禁网；不得改用
|
||||
`danger-full-access`。Cursor 继续使用自身的 `--auto-review --sandbox enabled`。
|
||||
- 安全启动适配器只支持 `codex` 和 `cursor-agent`。Codex 使用结构化 sandbox 与 approval
|
||||
参数；Cursor 使用 `--auto-review --sandbox enabled --workspace <path>`。不接受
|
||||
full-access、bypass、`--force`、`--yolo` 或关闭 sandbox。
|
||||
- `cliPolicy` 固定为 `current-host`，resolver 不提供默认 CLI；漏传宿主身份会直接失败，
|
||||
不得从共享配置回退到 Codex 或 Cursor。
|
||||
- Cursor 的 reasoning 档位编码在精确模型 ID 中，因此其 `reasoningEffort` 必须为 null；
|
||||
Codex 则显式传递 `model_reasoning_effort`。
|
||||
- resolver 只读取 skill 内有大小上限的普通共享配置文件，拒绝 symlink/special file；
|
||||
启动计划绑定配置快照、root-owned 隔离 Python、可信绝对 Agent/Orca executable、Git
|
||||
worktree identity、release remote identity、精确环境认证选择和固定 argv。实际启动会
|
||||
重新校验 fingerprint；release 阶段允许受信任的 `$manage-release` 直接使用当前 shell
|
||||
已有的 Git/Forge 登录，resolver 不检查或复制认证文件。显式 token/SSH 认证仍只注入所选
|
||||
环境变量。不得改写 resolver 返回的 worker argv，也不得把终端创建 argv 的绝对 Orca
|
||||
路径换成项目 `PATH` 解析。
|
||||
- 不把模型档位当作权限。`high` 不自动获得更多文件、凭据、网络或远端写权限。
|
||||
- 不执行 `orca orchestration reset`，除非用户明确要求放弃全部相关运行时状态。
|
||||
|
||||
## 完成标准
|
||||
|
||||
每个计划阶段都有明确下游 Skill、Agent CLI、档位、输入 revision、授权边界和可核对结果；
|
||||
DAG 中所有必要阶段完成，或失败阶段具有准确状态与恢复入口。ACK 和其它下游 Skill
|
||||
保持独立且不存在对 ORC 的反向引用。
|
||||
@@ -0,0 +1,6 @@
|
||||
interface:
|
||||
display_name: "ORC"
|
||||
short_description: "用 Codex 或 Cursor 分档编排开发、发布与产物任务"
|
||||
default_prompt: "Use $orc to coordinate this engineering task on the current host CLI with a low, mid, or high worker level."
|
||||
policy:
|
||||
allow_implicit_invocation: false
|
||||
@@ -0,0 +1,54 @@
|
||||
{
|
||||
"version": 2,
|
||||
"cliPolicy": "current-host",
|
||||
"defaultLevel": "mid",
|
||||
"stageDefaults": {
|
||||
"code": "high",
|
||||
"release": "mid",
|
||||
"deb": "low",
|
||||
"docker": "low"
|
||||
},
|
||||
"worktreePolicy": "registered-same-repository",
|
||||
"profiles": {
|
||||
"codex": {
|
||||
"low": {
|
||||
"model": "gpt-5.6-luna",
|
||||
"reasoningEffort": "low",
|
||||
"permissionMode": "workspace-write",
|
||||
"approvalPolicy": "never"
|
||||
},
|
||||
"mid": {
|
||||
"model": "gpt-5.6-terra",
|
||||
"reasoningEffort": "medium",
|
||||
"permissionMode": "workspace-write",
|
||||
"approvalPolicy": "never"
|
||||
},
|
||||
"high": {
|
||||
"model": "gpt-5.6-sol",
|
||||
"reasoningEffort": "high",
|
||||
"permissionMode": "workspace-write",
|
||||
"approvalPolicy": "never"
|
||||
}
|
||||
},
|
||||
"cursor-agent": {
|
||||
"low": {
|
||||
"model": "auto",
|
||||
"reasoningEffort": null,
|
||||
"permissionMode": "workspace-write",
|
||||
"approvalPolicy": "auto-review"
|
||||
},
|
||||
"mid": {
|
||||
"model": "gpt-5.6-terra-medium",
|
||||
"reasoningEffort": null,
|
||||
"permissionMode": "workspace-write",
|
||||
"approvalPolicy": "auto-review"
|
||||
},
|
||||
"high": {
|
||||
"model": "gpt-5.6-sol-high",
|
||||
"reasoningEffort": null,
|
||||
"permissionMode": "workspace-write",
|
||||
"approvalPolicy": "auto-review"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,110 @@
|
||||
# ORC 的 Orca 适配
|
||||
|
||||
Orca 保存运行时任务、依赖、dispatch 和消息；ORC 保存稳定路由规则。不要在项目中
|
||||
复制一份 Orca 运行时任务板。
|
||||
|
||||
## 运行前
|
||||
|
||||
```bash
|
||||
orca status --json
|
||||
orca orchestration task-list --json
|
||||
orca orchestration inbox --limit 20 --json
|
||||
```
|
||||
|
||||
确认 runtime 可达、orchestration 可用，并识别是否存在与当前请求相同的活跃任务。
|
||||
恢复流程时复用身份匹配的 task；身份不明时不要猜测或清空全局状态。
|
||||
|
||||
## 解析安全启动计划
|
||||
|
||||
对每个阶段调用 `resolve_profile.py resolve`，同时传入规范绝对 `--project-root`、
|
||||
`--worktree` 和从当前 Agent 系统身份确定的必填 `--host-cli`，以及本阶段精确的
|
||||
`--model-auth`、`--remote-auth`。
|
||||
resolver 始终读取 skill 内共享的 `config.yaml`，不接受项目配置路径。JSON 结果包含
|
||||
选择来源、结构化 profile、认证选择、配置与 worktree identity、可信 Python/Agent
|
||||
CLI/Orca executable、
|
||||
`launchFingerprint`、固定 worker/launcher argv，以及完整的 `terminalCreateArgv` 和
|
||||
`terminalCreateShellCommand`。
|
||||
|
||||
- 优先把返回的 `terminalCreateArgv` 原样交给 argv-capable 进程工具；若工具只接受 shell
|
||||
字符串，则执行完整的 `terminalCreateShellCommand`。不得再插值、包引号或追加参数。
|
||||
- `terminalCreateArgv` 的首项是 resolver 选定的绝对 Orca executable，不替换成裸
|
||||
`orca` 或重新通过项目 `PATH` 查找。
|
||||
- 不从 YAML 自行拼接命令，不追加 argv、环境变量、hook 或权限参数。
|
||||
- `remote-auth` 只表示显式注入的单一环境 token 或 SSH agent；默认 `none`，不为方便同时
|
||||
暴露多组环境凭据。release worker 直接使用当前 shell 已有的 Git/Forge CLI 登录，
|
||||
resolver 不读取 tea/gh/glab 配置，也不注入 credential helper。
|
||||
- release 计划要求 `origin` 恰好一个 fetch URL 和一个 push URL，二者规范化后完全一致；
|
||||
remote identity 会进入 fingerprint，并在实际 launch 时重新解析。独立 `pushurl`、多个
|
||||
push URL、local/file remote 或带内嵌 HTTPS 凭据的 URL 都 fail closed。
|
||||
- Codex release 计划固定使用 `on-request` + `auto_review`，开启 workspace-write 网络并启用
|
||||
network proxy，只允许绑定的 remote 与确定性 Forge API host。GitHub 固定追加
|
||||
`api.github.com` 和 `uploads.github.com`；其它本地阶段保持默认禁网。不得替换成
|
||||
`danger-full-access`。Cursor 继续使用自身的 auto-review sandbox。
|
||||
- resolver 失败时停止；不改用默认模型、邻近档位或已有未知终端。
|
||||
- 不从任务文本、可执行文件存在性或共享配置猜宿主；Codex 传 `--host-cli codex`，Cursor
|
||||
传 `--host-cli cursor-agent`。宿主身份不明确时停止。
|
||||
- 不重复手写 worktree 检查；resolver 已拒绝 root、不存在、非规范、含 symlink、未注册
|
||||
或跨仓库的目标，并把身份写入 fingerprint。
|
||||
- ORC v2 profile 必须使用 `workspace-write`。`read-only` sandbox 可能阻止 Orca CLI
|
||||
写入自身运行时或挂载目录，导致 worker 无法发送 `worker_done`；只读工作通过 task
|
||||
spec 限制，而不是换成无法完成 lifecycle 的 sandbox。
|
||||
- Codex 与 Cursor 使用不同的固定 argv 适配器。Cursor 只允许 `--auto-review`、启用的
|
||||
sandbox 和精确 workspace；不得把 Codex 参数套给 Cursor，也不得给 Cursor 追加
|
||||
`--force` 或 `--yolo`。
|
||||
|
||||
## 创建与派发
|
||||
|
||||
每个需要 fresh worker 的阶段依次执行：
|
||||
|
||||
1. 使用解析结果创建目标 worktree 内的终端。下面整行代表 resolver 返回的一个完整值，
|
||||
不是待替换的参数模板：
|
||||
|
||||
```bash
|
||||
<resolver-terminalCreateShellCommand>
|
||||
```
|
||||
|
||||
2. 使用返回的具体 handle 等待 Agent TUI 可接收输入：
|
||||
|
||||
```bash
|
||||
orca terminal wait --terminal <handle> --for tui-idle \
|
||||
--timeout-ms 60000 --json
|
||||
```
|
||||
|
||||
3. 先为前置阶段创建 task，再用其 ID 构造依赖数组创建后置 task。task spec 使用
|
||||
`routing.md` 的 worker prompt 契约。
|
||||
4. 对已就绪 task 执行：
|
||||
|
||||
```bash
|
||||
orca orchestration dispatch --task <task-id> --to <handle> --inject --json
|
||||
```
|
||||
|
||||
不要把同一 task 同时派给多个写 worker。并行阶段必须使用不会竞争同一工作树写入的
|
||||
独立 worker；否则串行执行。`terminal create` 超时或连接中断时状态不确定：先用
|
||||
`terminalTitle`、worktree 和 fingerprint 核对 `orca terminal list --json`，没有完成
|
||||
reconciliation 前不得重试创建。
|
||||
|
||||
## 监督循环
|
||||
|
||||
```bash
|
||||
orca orchestration check --wait \
|
||||
--types worker_done,escalation,decision_gate \
|
||||
--timeout-ms 900000 --json
|
||||
```
|
||||
|
||||
- timeout 或空结果是检查点，不等于失败；任务仍活跃时继续滚动等待。
|
||||
- 收到 `decision_gate` 时只回答当前问题，不扩大用户授权。
|
||||
- 收到 `escalation` 时保留已完成状态，判断是改档、补输入还是停止。
|
||||
- 收到 `worker_done` 后核对 task/dispatch ID、下游完成证据和外部状态，再把依赖 task
|
||||
标记完成并派发新就绪阶段。
|
||||
- 三次连续同因失败后停止重派，报告恢复入口；不要用新终端掩盖同一阻塞。
|
||||
|
||||
## ACK 特例
|
||||
|
||||
`code` worker 是运行 `$ack` 的阶段 Coordinator。ORC 的 `low/mid/high` 只决定这个
|
||||
worker 的启动 profile；ACK 启动 Developer/Test 时继续读取自己的项目配置与
|
||||
`standard/strong` 规则。ORC 不读取、改写或覆盖 ACK 的内部 worker profiles。
|
||||
|
||||
## 收尾
|
||||
|
||||
不要自动关闭仍承担恢复入口的终端，不自动删除 worktree 或清空 runtime-global task。
|
||||
只有用户明确要求清理时，才按 Orca 和下游 Skill 的安全规则处理。
|
||||
@@ -0,0 +1,78 @@
|
||||
# ORC 阶段路由
|
||||
|
||||
ORC 是薄路由器，只负责意图映射、依赖、静态档位和结构化状态汇总。它不判断版本号、
|
||||
实现方案、发布风险或产物策略；领域步骤、授权检查和完成标准由下游 Skill 自己决定。
|
||||
|
||||
## 路由表
|
||||
|
||||
| 阶段 | 下游 Skill | 包含 | 不包含 |
|
||||
|------|------------|------|--------|
|
||||
| `code` | `$ack` | 功能、缺陷、重构、测试、三角色验证闭环，以及用户明确要求的普通非发布 PR/MR | 版本发布、单独上传产物 |
|
||||
| `release` | `$manage-release` | 版本号、release worktree/分支、release PR/MR、合并、tag、Forge Release、恢复发布 | 普通非发布 PR/MR、构建或上传 DEB/Docker |
|
||||
| `deb` | `$deb-publisher` | DEB 构建、校验、上传与仓库可见性 | 源码 tag、Docker 镜像 |
|
||||
| `docker` | `$publish-docker-image` | Docker/OCI 构建、push、digest 与平台验证 | 源码版本生命周期、DEB |
|
||||
|
||||
没有匹配项时不要临时扩写某个 Skill 的职责，也不要让 ORC 自己模仿领域流程。报告缺少
|
||||
的能力，由用户决定直接执行、安装新 Skill 或另行设计。
|
||||
|
||||
路由只依据用户明确表达的目标。缺少目标版本、revision、产物目标或授权停止点时，保留
|
||||
为未指定并交给下游 Skill；只有缺少创建 task 所必需的项目或阶段身份时才建立
|
||||
decision gate。不得为了填满 worker prompt 而分析代码、推断版本或设计执行方案。
|
||||
|
||||
## 拆分规则
|
||||
|
||||
1. 先从用户请求提取最终结果，再拆出真正需要的阶段；不要因为安装了某个 Skill 就
|
||||
自动增加发布或上传。
|
||||
2. 为每个阶段锁定输入：项目、worktree、源 commit/tag、版本、目标和用户授权的最远
|
||||
写操作。
|
||||
3. 同一领域的连续动作保留在一个下游任务中。例如版本号、release PR、合并和 tag
|
||||
属于一个 `manage-release` 生命周期，不拆成多个互相争抢状态的 worker。
|
||||
4. 只有输入 revision 完全相同且互不修改同一工作树时，才并行执行 DEB 与 Docker。
|
||||
5. 普通代码改动进入 ACK。若项目尚未初始化 ACK，`code` 阶段停在前置条件，不由 ORC
|
||||
静默初始化。
|
||||
6. `code` 阶段默认停在 ACK `verified`；用户明确要求普通 PR/MR 时最多到
|
||||
`review_ready`。worker prompt 必须禁止继续执行版本发布、DEB、Docker 或部署。
|
||||
|
||||
## 常见 DAG
|
||||
|
||||
完整交付：
|
||||
|
||||
```text
|
||||
code ($ack)
|
||||
-> release ($manage-release)
|
||||
-> deb ($deb-publisher)
|
||||
-> docker ($publish-docker-image)
|
||||
```
|
||||
|
||||
只从当前 commit 构建产物：
|
||||
|
||||
```text
|
||||
deb ($deb-publisher) || docker ($publish-docker-image)
|
||||
```
|
||||
|
||||
仅发布源码版本：
|
||||
|
||||
```text
|
||||
release ($manage-release)
|
||||
```
|
||||
|
||||
依赖不是固定模板，但 ORC v2 不拆分一个 `manage-release` 生命周期。若项目要求在打开
|
||||
release PR 与合并之间插入 DEB/Docker gate，当前 task 粒度无法安全表达该中间里程碑；
|
||||
在打开 PR 前建立 decision gate 并报告该流程暂不支持，不得用循环依赖或两个 release
|
||||
worker 临时拼接。
|
||||
|
||||
## Worker prompt 契约
|
||||
|
||||
每个 worker prompt 至少包含：
|
||||
|
||||
- 第一条指令显式调用唯一的下游 Skill，例如 `Use $manage-release ...`。
|
||||
- 阶段目标与明确的非目标。
|
||||
- 项目/worktree、输入 commit/tag 和前置阶段的可核对结果。
|
||||
- 用户已经授予的最远动作；未授权动作明确禁止。
|
||||
- 要求遵循项目 Agent 指令和下游 Skill 自身的停止条件。
|
||||
- 完成证据，以及通过 live dispatch preamble 回报 `worker_done` 的要求。
|
||||
- `code` prompt 还必须写明 ACK 停止点是 `verified` 或普通 PR 的 `review_ready`，并禁止
|
||||
ACK 路由版本、DEB、Docker 或部署动作。
|
||||
|
||||
不要把 ORC 的 profile、路由器内部规则或其它下游 Skill 注入 worker。worker 只需要
|
||||
当前阶段、对应 Skill 和必要依赖结果。
|
||||
Executable
+1074
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,67 @@
|
||||
# skiff
|
||||
|
||||
`skiff` 用于创建、维护、安装和发布团队自研的 Agent Skill。Skill 的唯一来源位于
|
||||
`~/.skills/skills/<name>/`，安装到各 Agent 时使用软链接。
|
||||
|
||||
## 什么时候使用
|
||||
|
||||
- 想把项目里的重复工作沉淀成一个 skill。
|
||||
- 想完善、校验、转正或发布已有 skill。
|
||||
- 想把自研 skill 安装到当前项目或全局 Agent。
|
||||
- 想检查并修复 skill 软链接。
|
||||
|
||||
## 创建一个 skill
|
||||
|
||||
```bash
|
||||
skiff create my-skill \
|
||||
--idea "描述这个 skill 要解决的重复问题" \
|
||||
--from-project .
|
||||
```
|
||||
|
||||
命令会在 `~/.skills/.drafts/my-skill/` 创建：
|
||||
|
||||
- `SKILL.md`：给 Agent 阅读的工作流与约束。
|
||||
- `README.md`：给人类阅读的用途、准备事项、示例和完成标准。
|
||||
- `brief.yaml`：草稿来源信息，转正时自动移除。
|
||||
|
||||
完善 `SKILL.md` 和 `README.md` 后运行：
|
||||
|
||||
```bash
|
||||
skiff check my-skill
|
||||
skiff finalize my-skill
|
||||
```
|
||||
|
||||
## 提交和发布
|
||||
|
||||
只提交：
|
||||
|
||||
```bash
|
||||
skiff publish skills/my-skill -m "add my-skill"
|
||||
```
|
||||
|
||||
提交并推送：
|
||||
|
||||
```bash
|
||||
skiff publish skills/my-skill -m "add my-skill" --push
|
||||
```
|
||||
|
||||
## 安装
|
||||
|
||||
安装到当前项目的 Codex：
|
||||
|
||||
```bash
|
||||
skiff add my-skill -a codex -y
|
||||
```
|
||||
|
||||
安装到全局 Codex：
|
||||
|
||||
```bash
|
||||
skiff add my-skill -a codex -g -y
|
||||
```
|
||||
|
||||
## 如何判断完成
|
||||
|
||||
- `skiff check <name>` 输出校验通过。
|
||||
- 正式 skill 同时包含 `SKILL.md` 和 `README.md`。
|
||||
- `skiff status` 或 `skiff doctor` 显示目标软链接正常。
|
||||
|
||||
+32
-13
@@ -2,8 +2,9 @@
|
||||
name: skiff
|
||||
description: >-
|
||||
创建和维护 ~/.skills 自研 skill：把项目开发中产生的想法提炼为草稿，完善并校验后发布，
|
||||
或用 skiff add/remove 在项目及全局挂卸 skill。触发词：skiff、自研 skill、创建 skill、
|
||||
想做一个 skill、publish skill、安装自研 skill、更新 skill 到项目。
|
||||
用 skiff add/remove 在项目及全局挂卸 skill，或用 skiff init 初始化 skill 项目状态。
|
||||
触发词：skiff、自研 skill、创建 skill、想做一个 skill、publish skill、安装自研 skill、
|
||||
更新 skill 到项目、初始化 skill。
|
||||
---
|
||||
|
||||
# skiff 自研 Skill 工作流
|
||||
@@ -14,7 +15,7 @@ SSOT 固定在 `~/.skills/skills/<name>/`。内容通过 **symlink** 分发到
|
||||
|
||||
## 在项目中使用 skill
|
||||
|
||||
先浏览可用的 owned skill，再安装到当前项目：
|
||||
先浏览可用的 builtin skill，再安装到当前项目：
|
||||
|
||||
```bash
|
||||
skiff add --list
|
||||
@@ -37,15 +38,16 @@ skiff add <name> -a cursor -a claude -a codex -y
|
||||
skiff create <name> --idea "<用户原始想法>" --from-project .
|
||||
```
|
||||
|
||||
4. 编辑 `~/.skills/.drafts/<name>/SKILL.md`，完善触发条件、不适用场景、步骤、边界与验证方法。仅在确有必要时增加 `references/`、`scripts/` 或 `assets/`。
|
||||
5. 不要把项目专属路径、私有业务规则、一次性命令或密钥复制到通用 skill。
|
||||
6. 运行校验并修复所有问题：
|
||||
4. 编辑 `~/.skills/.drafts/<name>/SKILL.md`，完善触发条件、不适用场景、步骤、边界与验证方法。
|
||||
5. 编辑同目录的 `README.md`，用面向人类的语言说明用途、准备事项、可直接复制的请求示例、Agent 会做什么以及如何判断完成。README 不应复述 Agent 内部指令。
|
||||
6. 仅在确有必要时增加 `references/`、`scripts/` 或 `assets/`。不要把项目专属路径、私有业务规则、一次性命令或密钥复制到通用 skill。
|
||||
7. 运行校验并修复所有问题：
|
||||
|
||||
```bash
|
||||
skiff check <name>
|
||||
```
|
||||
|
||||
7. 向用户展示名称、description、核心步骤和验证方式。获得确认后再转正：
|
||||
8. 向用户展示名称、description、README 的人类使用方式、核心步骤和验证方式。获得确认后再转正：
|
||||
|
||||
```bash
|
||||
skiff finalize <name>
|
||||
@@ -59,11 +61,11 @@ skiff finalize <name>
|
||||
|
||||
1. 先记录最小证据：触发用户表达、使用的 skill 名称、实际结果、期望结果，以及能复现问题的必要项目上下文。
|
||||
2. 判断归属：
|
||||
- 通用工作流、触发条件或验证缺陷：回流 owned skill。
|
||||
- 通用工作流、触发条件或验证缺陷：回流 builtin skill。
|
||||
- 仅当前项目成立的命令、路径、业务规则：留在项目文档或项目配置，不写回通用 skill。
|
||||
- CLI 安装、软链或校验行为异常：修改 `~/.skills/skiff/` 中的 CLI 和测试。
|
||||
- 第三方 skill：不要复制成 owned skill 或直接改安装目录；整理证据反馈上游，除非用户明确决定维护 fork。
|
||||
3. 确认真实来源。Agent 目录通常是软链，owned skill 的 SSOT 固定为：
|
||||
- 第三方 skill：不要复制成 builtin skill 或直接改安装目录；整理证据反馈上游，除非用户明确决定维护 fork。
|
||||
3. 确认真实来源。Agent 目录通常是软链，builtin skill 的 SSOT 固定为：
|
||||
|
||||
```text
|
||||
~/.skills/skills/<name>/
|
||||
@@ -106,7 +108,7 @@ skiff add discussion-notes -a cursor -g -y
|
||||
skiff add discussion-notes -a cursor -a codex -g -y
|
||||
```
|
||||
|
||||
registry 条目既可以指向单个 skill，也可以指向包含多个 skill 目录的
|
||||
catalog source既可以指向单个 skill，也可以指向包含多个 skill 目录的
|
||||
collection。安装 collection 全部内容或其中一个：
|
||||
|
||||
```bash
|
||||
@@ -114,7 +116,11 @@ skiff add waza -a codex -g -y
|
||||
skiff add waza/think -a codex -g -y
|
||||
```
|
||||
|
||||
`skiff select` 会把 collection 展开为 `waza/think`、`waza/ui` 等候选项。
|
||||
`skiff select` 会把 collection 显示为两级菜单：选择 `waza` 仓库会选中其
|
||||
全部子 skill，也可以只选择 `waza/think`、`waza/ui` 中的若干项。
|
||||
普通 `skiff select` 只向项目安装，并只读显示每个 Agent 的全局安装状态；
|
||||
`skiff select -g` 只向全局安装。取消已勾选项不会卸载，卸载继续使用
|
||||
`skiff remove`。
|
||||
|
||||
卸载：
|
||||
|
||||
@@ -130,6 +136,17 @@ skiff rm discussion-notes -g -y # rm 别名
|
||||
skiff add --list
|
||||
```
|
||||
|
||||
使用 Skill 自带模板初始化项目状态：
|
||||
|
||||
```bash
|
||||
skiff init ack
|
||||
skiff init ack --project ~/app
|
||||
```
|
||||
|
||||
`skiff` 只负责可靠地生成项目状态文件，不复制或链接 Skill。需要分析项目并完善
|
||||
ACK 配置、检查接入状态或
|
||||
运行三角色闭环时，显式调用全局 `/ack` skill。
|
||||
|
||||
---
|
||||
|
||||
## 与 Vercel `npx skills` 的分工
|
||||
@@ -146,6 +163,7 @@ skiff add --list
|
||||
| skiff | 说明 |
|
||||
|-------|------|
|
||||
| `bootstrap` | 将本项目的 `skiff` skill 全局安装到所有 Agent |
|
||||
| `update` | 在 `~/.skills` 执行 `git pull`，更新 skiff 自身 |
|
||||
| `add <name> [-g] [-a AGENT...] [-y]` | 安装 |
|
||||
| `remove <name> [-g] [-a AGENT...] [-y]` | 卸载（`rm` / `r` 别名） |
|
||||
| `add --list` | 列出可用自研 skill |
|
||||
@@ -155,6 +173,7 @@ skiff add --list
|
||||
| `create <name> --idea TEXT [--from-project PATH]` | 创建自研 skill 草稿 |
|
||||
| `check <name>` | 校验草稿或正式 skill |
|
||||
| `finalize <name>` | 校验草稿并转为正式 skill |
|
||||
| `init <name> [--project DIR]` | 使用 skill 模板初始化项目状态 |
|
||||
|
||||
---
|
||||
|
||||
@@ -163,4 +182,4 @@ skiff add --list
|
||||
- 不要在 `project/.agents/skills/` 里直接改文件；应改 `~/.skills/skills/` 再 `publish`
|
||||
- 未完成的内容保留在 `~/.skills/.drafts/`，不要直接放进正式 `skills/`
|
||||
- symlink 正确时，**不需要 reinstall**；保存 SSOT 后各项目自动读到新内容
|
||||
- 社区 skill 用 `npx skills add`，不要用 skiff `registry add` 除非团队要 pin 版本
|
||||
- 社区 skill 用 `npx skills add`，不要用 skiff `catalog add` 除非团队要 pin 版本
|
||||
|
||||
@@ -0,0 +1,291 @@
|
||||
from __future__ import annotations
|
||||
|
||||
import copy
|
||||
import os
|
||||
import subprocess
|
||||
import sys
|
||||
import tempfile
|
||||
import unittest
|
||||
from pathlib import Path
|
||||
|
||||
|
||||
REPO_ROOT = Path(__file__).resolve().parents[1]
|
||||
SCRIPTS_DIR = REPO_ROOT / "skills" / "ack" / "scripts"
|
||||
VALIDATOR = SCRIPTS_DIR / "validate_delivery.py"
|
||||
EXAMPLE = REPO_ROOT / "skills" / "ack" / "examples" / "delivery.example.yaml"
|
||||
sys.path.insert(0, str(SCRIPTS_DIR))
|
||||
|
||||
import validate_delivery # noqa: E402
|
||||
|
||||
|
||||
def valid_contract() -> dict:
|
||||
entrypoints = {
|
||||
name: {
|
||||
"kind": "make",
|
||||
"target": name,
|
||||
"args": [],
|
||||
"requiredSecrets": [],
|
||||
"workingDirectory": ".",
|
||||
"timeoutSeconds": 300,
|
||||
}
|
||||
for name in ("verify", "build", "upload", "deploy", "health", "rollback")
|
||||
}
|
||||
return {
|
||||
"version": 1,
|
||||
"updatedAt": "2026-08-01T10:00:00+08:00",
|
||||
"project": {"name": "demo"},
|
||||
"enabled": True,
|
||||
"defaultProfile": "review",
|
||||
"entrypoints": entrypoints,
|
||||
"artifacts": {
|
||||
"service-deb": {
|
||||
"type": "deb",
|
||||
"build": "build",
|
||||
"outputs": ["dist/*.deb"],
|
||||
}
|
||||
},
|
||||
"destinations": {
|
||||
"preview-apt": {
|
||||
"type": "apt-repository",
|
||||
"channel": "preview",
|
||||
"endpoint": "https://packages.example.com",
|
||||
"repository": "testing",
|
||||
"upload": "upload",
|
||||
}
|
||||
},
|
||||
"environments": {
|
||||
"test-server": {
|
||||
"type": "ssh-host",
|
||||
"classification": "development",
|
||||
"target": "test-server",
|
||||
"deploy": "deploy",
|
||||
"healthCheck": "health",
|
||||
"rollback": "rollback",
|
||||
"mutex": "test-server-deploy",
|
||||
}
|
||||
},
|
||||
"profiles": {
|
||||
"review": {
|
||||
"stopAt": "review_ready",
|
||||
"steps": [
|
||||
{"id": "verify", "action": "verify", "entrypoint": "verify"},
|
||||
{
|
||||
"id": "open-pr",
|
||||
"action": "pull-request",
|
||||
"draft": True,
|
||||
"remote": "origin",
|
||||
"baseBranch": "main",
|
||||
},
|
||||
{"id": "build", "action": "build", "artifact": "service-deb"},
|
||||
{
|
||||
"id": "publish",
|
||||
"action": "publish",
|
||||
"artifact": "service-deb",
|
||||
"destination": "preview-apt",
|
||||
},
|
||||
{
|
||||
"id": "deploy",
|
||||
"action": "deploy",
|
||||
"artifact": "service-deb",
|
||||
"environment": "test-server",
|
||||
},
|
||||
{
|
||||
"id": "health",
|
||||
"action": "health-check",
|
||||
"environment": "test-server",
|
||||
},
|
||||
{"id": "ready", "action": "mark-ready"},
|
||||
],
|
||||
}
|
||||
},
|
||||
}
|
||||
|
||||
|
||||
class AckDeliveryValidationTests(unittest.TestCase):
|
||||
def test_example_is_valid_with_and_without_site_packages(self) -> None:
|
||||
for no_site_packages in (False, True):
|
||||
command = [sys.executable]
|
||||
if no_site_packages:
|
||||
command.append("-S")
|
||||
result = subprocess.run(
|
||||
[*command, str(VALIDATOR), str(EXAMPLE)],
|
||||
cwd=REPO_ROOT,
|
||||
text=True,
|
||||
capture_output=True,
|
||||
check=False,
|
||||
)
|
||||
with self.subTest(no_site_packages=no_site_packages):
|
||||
self.assertEqual(result.returncode, 0, result.stderr)
|
||||
self.assertIn("交付契约校验通过", result.stdout)
|
||||
|
||||
def test_default_profile_rejects_stable_and_production_targets(self) -> None:
|
||||
contract = valid_contract()
|
||||
contract["destinations"]["preview-apt"]["channel"] = "stable"
|
||||
contract["environments"]["test-server"]["classification"] = "production"
|
||||
|
||||
errors = validate_delivery.validate_builtin(contract)
|
||||
|
||||
self.assertTrue(any("stable 发布前必须有 release approval" in item for item in errors))
|
||||
self.assertTrue(any("production 部署前必须有 production approval" in item for item in errors))
|
||||
self.assertTrue(any("defaultProfile 不能发布 stable" in item for item in errors))
|
||||
self.assertTrue(any("defaultProfile 不能部署 production" in item for item in errors))
|
||||
|
||||
def test_nondefault_release_profile_supports_stable_and_production_with_gates(self) -> None:
|
||||
contract = valid_contract()
|
||||
contract["destinations"]["stable-apt"] = {
|
||||
"type": "apt-repository",
|
||||
"channel": "stable",
|
||||
"endpoint": "https://packages.example.com",
|
||||
"repository": "stable",
|
||||
"upload": "upload",
|
||||
}
|
||||
contract["environments"]["prod-server"] = {
|
||||
"type": "ssh-host",
|
||||
"classification": "production",
|
||||
"target": "prod-server",
|
||||
"deploy": "deploy",
|
||||
"healthCheck": "health",
|
||||
"rollback": "rollback",
|
||||
"mutex": "prod-server-deploy",
|
||||
}
|
||||
contract["profiles"]["release"] = {
|
||||
"stopAt": "released",
|
||||
"steps": [
|
||||
{"id": "verify-release", "action": "verify", "entrypoint": "verify"},
|
||||
{
|
||||
"id": "open-release-pr",
|
||||
"action": "pull-request",
|
||||
"draft": True,
|
||||
"remote": "origin",
|
||||
"baseBranch": "main",
|
||||
},
|
||||
{"id": "build-release", "action": "build", "artifact": "service-deb"},
|
||||
{"id": "approve-release", "action": "approval", "gate": "release"},
|
||||
{
|
||||
"id": "publish-release",
|
||||
"action": "publish",
|
||||
"artifact": "service-deb",
|
||||
"destination": "stable-apt",
|
||||
},
|
||||
{"id": "approve-production", "action": "approval", "gate": "production"},
|
||||
{
|
||||
"id": "deploy-production",
|
||||
"action": "deploy",
|
||||
"artifact": "service-deb",
|
||||
"environment": "prod-server",
|
||||
},
|
||||
{
|
||||
"id": "health-production",
|
||||
"action": "health-check",
|
||||
"environment": "prod-server",
|
||||
},
|
||||
{"id": "ready-release", "action": "mark-ready"},
|
||||
],
|
||||
}
|
||||
|
||||
self.assertEqual(validate_delivery.validate_builtin(contract), [])
|
||||
|
||||
def test_publish_and_health_check_require_prior_steps(self) -> None:
|
||||
contract = valid_contract()
|
||||
steps = contract["profiles"]["review"]["steps"]
|
||||
steps[2], steps[3] = steps[3], steps[2]
|
||||
steps[4], steps[5] = steps[5], steps[4]
|
||||
|
||||
errors = validate_delivery.validate_builtin(contract)
|
||||
|
||||
self.assertTrue(any("publish 前必须先 build" in item for item in errors))
|
||||
self.assertTrue(any("health-check 前必须先 deploy" in item for item in errors))
|
||||
|
||||
def test_pull_request_requires_explicit_safe_remote_and_base(self) -> None:
|
||||
contract = valid_contract()
|
||||
step = contract["profiles"]["review"]["steps"][1]
|
||||
del step["remote"]
|
||||
step["baseBranch"] = "../main"
|
||||
|
||||
errors = validate_delivery.validate_builtin(contract)
|
||||
|
||||
self.assertTrue(any(".remote: action='pull-request' 时必填" in item for item in errors))
|
||||
self.assertTrue(any(".remote: 必须是安全的 Git remote 名称" in item for item in errors))
|
||||
self.assertTrue(any(".baseBranch: 必须是安全的 Git 分支名" in item for item in errors))
|
||||
|
||||
def test_unknown_shell_and_inline_secret_are_rejected(self) -> None:
|
||||
contract = valid_contract()
|
||||
contract["entrypoints"]["verify"]["shell"] = "make verify"
|
||||
contract["entrypoints"]["verify"]["requiredSecrets"] = ["token-value"]
|
||||
contract["destinations"]["preview-apt"]["repository"] = (
|
||||
"token=abcdefghijklmnop"
|
||||
)
|
||||
contract["destinations"]["preview-apt"]["registry"] = "unexpected.example"
|
||||
|
||||
errors = validate_delivery.validate_builtin(contract)
|
||||
|
||||
self.assertTrue(any("未知字段 'shell'" in item for item in errors))
|
||||
self.assertTrue(any("requiredSecrets" in item for item in errors))
|
||||
self.assertTrue(any("type='apt-repository' 不允许此字段" in item for item in errors))
|
||||
self.assertTrue(any("疑似包含敏感信息" in item for item in errors))
|
||||
|
||||
def test_project_script_must_be_executable_and_not_a_symlink(self) -> None:
|
||||
contract = valid_contract()
|
||||
contract["entrypoints"]["verify"] = {
|
||||
"kind": "script",
|
||||
"path": "scripts/verify.sh",
|
||||
"args": [],
|
||||
"requiredSecrets": [],
|
||||
"workingDirectory": ".",
|
||||
"timeoutSeconds": 300,
|
||||
}
|
||||
|
||||
with tempfile.TemporaryDirectory() as temp_dir:
|
||||
root = Path(temp_dir)
|
||||
scripts = root / "scripts"
|
||||
scripts.mkdir()
|
||||
target = scripts / "target.sh"
|
||||
target.write_text("#!/bin/sh\nexit 0\n", encoding="utf-8")
|
||||
target.chmod(0o755)
|
||||
os.symlink("target.sh", scripts / "verify.sh")
|
||||
|
||||
errors = validate_delivery.validate_builtin(contract, root)
|
||||
self.assertTrue(any("路径不能包含 symlink" in item for item in errors))
|
||||
|
||||
(scripts / "verify.sh").unlink()
|
||||
plain = scripts / "verify.sh"
|
||||
plain.write_text("#!/bin/sh\nexit 0\n", encoding="utf-8")
|
||||
plain.chmod(0o644)
|
||||
errors = validate_delivery.validate_builtin(contract, root)
|
||||
self.assertTrue(any("脚本不可执行" in item for item in errors))
|
||||
|
||||
def test_tasks_link_requires_fixed_path_runs_and_same_project(self) -> None:
|
||||
contract = valid_contract()
|
||||
tasks = {
|
||||
"project": {"name": "other", "deliveryFile": "delivery.yaml"},
|
||||
"tasks": [],
|
||||
}
|
||||
|
||||
errors = validate_delivery.validate_tasks_link(contract, tasks)
|
||||
|
||||
self.assertIn(
|
||||
"tasks.project.deliveryFile 必须固定为 docs/ack/delivery.yaml",
|
||||
errors,
|
||||
)
|
||||
self.assertIn("delivery.project.name 必须与 tasks.project.name 一致", errors)
|
||||
self.assertIn("引用 deliveryFile 的任务板必须包含 deliveryRuns 列表", errors)
|
||||
|
||||
def test_disabled_empty_contract_remains_valid(self) -> None:
|
||||
contract = copy.deepcopy(valid_contract())
|
||||
contract.update(
|
||||
{
|
||||
"enabled": False,
|
||||
"defaultProfile": None,
|
||||
"entrypoints": {},
|
||||
"artifacts": {},
|
||||
"destinations": {},
|
||||
"environments": {},
|
||||
"profiles": {},
|
||||
}
|
||||
)
|
||||
|
||||
self.assertEqual(validate_delivery.validate_builtin(contract), [])
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
@@ -0,0 +1,309 @@
|
||||
from __future__ import annotations
|
||||
|
||||
import json
|
||||
import os
|
||||
import subprocess
|
||||
import sys
|
||||
import tempfile
|
||||
import unittest
|
||||
import contextlib
|
||||
import io
|
||||
from unittest import mock
|
||||
from pathlib import Path
|
||||
|
||||
|
||||
ROOT = Path(__file__).resolve().parents[1]
|
||||
READER = ROOT / "skills/ack/scripts/feishu_bug_intake.py"
|
||||
sys.path.insert(0, str(READER.parent))
|
||||
import feishu_bug_intake # noqa: E402
|
||||
|
||||
|
||||
class FeishuIntakeBlackBox(unittest.TestCase):
|
||||
def setUp(self) -> None:
|
||||
self.tmp = tempfile.TemporaryDirectory(prefix="feishu-e2e-")
|
||||
self.d = Path(self.tmp.name)
|
||||
self.bin = self.d / "bin"
|
||||
self.bin.mkdir()
|
||||
self.fixture = self.d / "submitted-bug.json"
|
||||
self.fixture.write_text(json.dumps({
|
||||
"recordId": "recBug1",
|
||||
"title": "Crash on save", "actual": "button crashes",
|
||||
"expected": "save succeeds", "steps": ["open app", "click Save"],
|
||||
"acceptance": "regression covered", "priority": "P1",
|
||||
"attachments": [{"file_token": "fileTok", "name": "screen.png", "type": "image/png", "size": 4}],
|
||||
"updatedAt": "2026-08-01T12:00:00Z",
|
||||
}), encoding="utf-8")
|
||||
self.mode_file = self.d / "mode.txt"
|
||||
self.mode_file.write_text("", encoding="utf-8")
|
||||
self.log = self.d / "argv.jsonl"
|
||||
self.fake = self.bin / "lark-cli"
|
||||
self.fake.write_text(
|
||||
"#!" + sys.executable + "\n"
|
||||
"import json, os, pathlib, sys\n"
|
||||
f"fixture=json.loads(pathlib.Path({str(self.fixture)!r}).read_text())\n"
|
||||
f"mode=pathlib.Path({str(self.mode_file)!r}).read_text().strip()\n"
|
||||
f"log=pathlib.Path({str(self.log)!r}); a=sys.argv[1:]\n"
|
||||
"with log.open('a') as f: f.write(json.dumps(a)+'\\n')\n"
|
||||
"p=a[a.index('--profile')+1] if '--profile' in a else None\n"
|
||||
"if a[:2]==['profile','list']:\n"
|
||||
" if '--format' in a: raise SystemExit(8)\n"
|
||||
" print(json.dumps([{'name':'tenant-a','appId':'cli_a','brand':'feishu','active':True},{'name':'tenant-b','appId':'cli_b','brand':'feishu','active':False}])); raise SystemExit\n"
|
||||
"if p != 'tenant-b': print('wrong tenant',file=sys.stderr); raise SystemExit(9)\n"
|
||||
"if mode=='malformed': print('{bad'); raise SystemExit\n"
|
||||
"if a[:2]==['base','+record-list']:\n"
|
||||
" if mode=='okfalse': print(json.dumps({'ok':False})); raise SystemExit\n"
|
||||
" if mode=='code': print(json.dumps({'code':7})); raise SystemExit\n"
|
||||
" if mode=='ambiguous': print(json.dumps({'data':{}})); raise SystemExit\n"
|
||||
" if mode=='noprog': print(json.dumps({'ok':True,'data':{'fields':['fTitle','fActual','fExpected','fSteps','fAcceptance','fPriority','fAttachments','fUpdated'],'record_id_list':[],'data':[],'has_more':True}})); raise SystemExit\n"
|
||||
" if mode=='max': print(json.dumps({'ok':True,'data':{'fields':['fTitle','fActual','fExpected','fSteps','fAcceptance','fPriority','fAttachments','fUpdated'],'record_id_list':['recBug1'],'data':[['x']*8],'has_more':True}})); raise SystemExit\n"
|
||||
" if mode=='matrix': print(json.dumps({'code':0,'data':{'fields':['fTitle'],'record_id_list':['recBug1'],'records':[]}})); raise SystemExit\n"
|
||||
" if mode=='cell': print(json.dumps({'ok':True,'data':{'fields':['fTitle','fActual','fExpected','fSteps','fAcceptance','fPriority','fAttachments','fUpdated'],'record_id_list':['recBug1'],'data':[[{'unexpected':'value'},'actual','expected','steps','accept','P1',[],f['updatedAt']]]}})); raise SystemExit\n"
|
||||
" if mode=='empty': print(json.dumps({'ok':True,'data':{'fields':['fTitle','fActual','fExpected','fSteps','fAcceptance','fPriority','fAttachments','fUpdated'],'record_id_list':['recBug1'],'data':[['title',None,'expected','steps','accept','P1',[],fixture['updatedAt']]]}})); raise SystemExit\n"
|
||||
" if mode=='enrichment': print(json.dumps({'ok':True,'data':{'fields':['fTitle','fActual','fExpected','fSteps','fAcceptance','fPriority','fAttachments','fUpdated'],'record_id_list':['recBug1'],'data':[['title','actual','expected',None,None,None,[],fixture['updatedAt']]]}})); raise SystemExit\n"
|
||||
" if mode=='blank': print(json.dumps({'ok':True,'data':{'fields':['fTitle','fActual','fExpected','fSteps','fAcceptance','fPriority','fAttachments','fUpdated'],'record_id_list':['recBlank'],'data':[[None,None,None,None,None,None,[],fixture['updatedAt']]]}})); raise SystemExit\n"
|
||||
" f=fixture; print(json.dumps({'ok':True,'data':{'fields':['fTitle','fActual','fExpected','fSteps','fAcceptance','fPriority','fAttachments','fUpdated'],'record_id_list':[f['recordId']],'data':[[f['title'],f['actual'],f['expected'],f['steps'],f['acceptance'],f['priority'],f['attachments'],f['updatedAt']]]}})); raise SystemExit\n"
|
||||
"if a[:2]==['base','+record-download-attachment']:\n"
|
||||
" out=pathlib.Path(a[a.index('--output')+1]); out.mkdir(parents=True,exist_ok=True)\n"
|
||||
" if mode=='escape': (out/'escape').symlink_to('/tmp'); raise SystemExit\n"
|
||||
" (out/'screen.png').write_bytes(b'fake'); print(json.dumps({'ok':True})); raise SystemExit\n"
|
||||
"raise SystemExit(2)\n", encoding="utf-8")
|
||||
self.fake.chmod(0o755)
|
||||
self.env = {**os.environ, "PATH": f"{self.bin}{os.pathsep}{os.environ.get('PATH','')}"}
|
||||
self.env["FAKE_FIXTURE"] = str(self.fixture)
|
||||
self.board = self.d / "tasks.yaml"
|
||||
self.board.write_text("""version: 1
|
||||
project:
|
||||
name: isolated-fake
|
||||
bugIntake:
|
||||
provider: feishu-base
|
||||
profile: tenant-b
|
||||
baseToken: base-secret
|
||||
tableId: tbl-bugs
|
||||
viewId: view-ready
|
||||
fields:
|
||||
title: fTitle
|
||||
actual: fActual
|
||||
expected: fExpected
|
||||
stepsToReproduce: fSteps
|
||||
acceptance: fAcceptance
|
||||
priority: fPriority
|
||||
attachments: fAttachments
|
||||
updatedAt: fUpdated
|
||||
tasks: []
|
||||
""", encoding="utf-8")
|
||||
|
||||
def tearDown(self) -> None:
|
||||
self.tmp.cleanup()
|
||||
|
||||
def invoke(self, command: str, *, mode: str | None = None, output: Path | None = None, resolver=None):
|
||||
env = dict(self.env)
|
||||
self.mode_file.write_text(mode or "", encoding="utf-8")
|
||||
args = [command, str(self.board)]
|
||||
if output:
|
||||
args += ["--output-dir", str(output)]
|
||||
stdout, stderr = io.StringIO(), io.StringIO()
|
||||
with mock.patch.object(feishu_bug_intake, "resolve_lark_cli", return_value=self.fake) if resolver is None else mock.patch.object(feishu_bug_intake, "resolve_lark_cli", side_effect=resolver), \
|
||||
mock.patch.dict(os.environ, env, clear=True), \
|
||||
contextlib.redirect_stdout(stdout), contextlib.redirect_stderr(stderr):
|
||||
try:
|
||||
code = feishu_bug_intake.main(args)
|
||||
except SystemExit as exc:
|
||||
code = int(exc.code or 0)
|
||||
return subprocess.CompletedProcess(args, code, stdout.getvalue(), stderr.getvalue())
|
||||
|
||||
def test_isolated_tenant_check_fetch_and_triage_contract(self) -> None:
|
||||
self.assertEqual(self.invoke("check").returncode, 0)
|
||||
downloads = self.d / "downloads"
|
||||
result = self.invoke("fetch", output=downloads)
|
||||
self.assertEqual(result.returncode, 0, result.stderr)
|
||||
payload = json.loads(result.stdout)
|
||||
record = payload["records"][0]
|
||||
self.assertEqual(record["recordId"], "recBug1")
|
||||
self.assertEqual(record["priority"], "P1")
|
||||
self.assertEqual(record["updatedAt"], "2026-08-01T12:00:00Z")
|
||||
self.assertIn("Crash on save", record["title"])
|
||||
self.assertTrue(Path(record["attachments"][0]["localPath"]).is_relative_to(downloads))
|
||||
self.assertRegex(record["sourceRef"], r"^feishu-base:sha256:[0-9a-f]{64}$")
|
||||
for secret in ("tenant-b", "base-secret", "tbl-bugs", "recBug1", "fileTok"):
|
||||
self.assertNotIn(secret, record["sourceRef"])
|
||||
for secret in ("base-secret", "fileTok", "app-secret-sentinel"):
|
||||
self.assertNotIn(secret, result.stdout)
|
||||
second = self.invoke("fetch", output=self.d / "repeat")
|
||||
self.assertEqual(second.returncode, 0, second.stderr)
|
||||
second_record = json.loads(second.stdout)["records"][0]
|
||||
self.assertRegex(second_record["sourceRef"], r"^feishu-base:sha256:[0-9a-f]{64}$")
|
||||
self.assertEqual(record["sourceRef"], second_record["sourceRef"])
|
||||
for secret in ("tenant-b", "base-secret", "tbl-bugs", "recBug1", "fileTok"):
|
||||
self.assertNotIn(secret, second_record["sourceRef"])
|
||||
for secret in ("base-secret", "fileTok", "app-secret-sentinel"):
|
||||
self.assertNotIn(secret, second.stdout)
|
||||
calls = [json.loads(x) for x in self.log.read_text().splitlines()]
|
||||
for call in calls:
|
||||
if call[:1] == ["base"]:
|
||||
self.assertEqual(call[call.index("--profile") + 1], "tenant-b")
|
||||
self.assertNotIn("tenant-a", call)
|
||||
if call[:2] == ["base", "+record-download-attachment"]:
|
||||
self.assertFalse(Path(call[call.index("--output") + 1]).is_absolute())
|
||||
self.assertEqual(sum(1 for c in calls if c[:2] == ["base", "+record-list"]), 2)
|
||||
list_call = next(c for c in reversed(calls) if c[:2] == ["base", "+record-list"])
|
||||
self.assertEqual(list_call[list_call.index("--view-id") + 1], "view-ready")
|
||||
self.assertEqual(list_call[:2], ["base", "+record-list"])
|
||||
self.assertEqual(list_call.count("--field-id"), 8)
|
||||
|
||||
def test_fail_closed_wrong_profile_and_unsafe_response(self) -> None:
|
||||
bad = self.board.read_text().replace("profile: tenant-b", "profile: tenant-a")
|
||||
self.board.write_text(bad)
|
||||
result = self.invoke("fetch")
|
||||
self.assertNotEqual(result.returncode, 0)
|
||||
self.board.write_text(bad.replace("profile: tenant-a", "profile: tenant-b"))
|
||||
result = self.invoke("fetch", mode="malformed")
|
||||
self.assertNotEqual(result.returncode, 0)
|
||||
result = self.invoke("fetch", mode="matrix", output=self.d / "matrix-output")
|
||||
self.assertNotEqual(result.returncode, 0)
|
||||
result = self.invoke("fetch", mode="cell", output=self.d / "cell-output")
|
||||
self.assertNotEqual(result.returncode, 0)
|
||||
result = self.invoke("fetch", mode="empty", output=self.d / "empty-output")
|
||||
self.assertNotEqual(result.returncode, 0)
|
||||
result = self.invoke("fetch", mode="escape", output=self.d / "downloads")
|
||||
self.assertNotEqual(result.returncode, 0)
|
||||
|
||||
def test_missing_coordinator_fields_are_planned_for_enrichment(self) -> None:
|
||||
fetched = self.invoke("fetch", mode="enrichment")
|
||||
self.assertEqual(fetched.returncode, 0, fetched.stderr)
|
||||
payload = json.loads(fetched.stdout)
|
||||
self.assertEqual(payload["warnings"], [])
|
||||
self.assertEqual(payload["records"][0]["enrichmentRequired"], [
|
||||
"steps", "acceptance", "priority",
|
||||
])
|
||||
|
||||
planned = self.invoke("plan", mode="enrichment")
|
||||
self.assertEqual(planned.returncode, 0, planned.stderr)
|
||||
action = json.loads(planned.stdout)["actions"][0]
|
||||
self.assertEqual(action["action"], "create")
|
||||
self.assertEqual(action["enrichmentRequired"], [
|
||||
"steps", "acceptance", "priority",
|
||||
])
|
||||
|
||||
def test_fully_blank_rows_are_skipped_with_a_batch_warning(self) -> None:
|
||||
result = self.invoke("fetch", mode="blank")
|
||||
self.assertEqual(result.returncode, 0, result.stderr)
|
||||
payload = json.loads(result.stdout)
|
||||
self.assertEqual(payload["records"], [])
|
||||
self.assertEqual(payload["warnings"], [{
|
||||
"recordId": "recBlank",
|
||||
"code": "blank_record_skipped",
|
||||
}])
|
||||
|
||||
def test_resolver_trust_and_no_executable_override_surface(self) -> None:
|
||||
trusted, hostile = self.d / "trusted", self.d / "hostile"
|
||||
trusted.mkdir(); hostile.mkdir()
|
||||
safe = trusted / "lark-cli"
|
||||
safe.write_text("#!/bin/sh\nexit 0\n", encoding="utf-8"); safe.chmod(0o755)
|
||||
(hostile / "lark-cli").write_text("#!/bin/sh\nexit 99\n", encoding="utf-8")
|
||||
(hostile / "lark-cli").chmod(0o755)
|
||||
with mock.patch.object(feishu_bug_intake, "trusted_lark_cli_dirs", return_value=[trusted]), mock.patch.dict(os.environ, {"PATH": str(hostile)}, clear=False):
|
||||
self.assertEqual(feishu_bug_intake.resolve_lark_cli(), safe)
|
||||
safe.chmod(0o775)
|
||||
with mock.patch.object(feishu_bug_intake, "trusted_lark_cli_dirs", return_value=[trusted]):
|
||||
with self.assertRaises(feishu_bug_intake.IntakeError):
|
||||
feishu_bug_intake.resolve_lark_cli()
|
||||
help_result = self.invoke("--help")
|
||||
self.assertEqual(help_result.returncode, 0)
|
||||
self.assertNotIn("--lark-cli", help_result.stdout + help_result.stderr)
|
||||
self.assertNotIn("--executable", help_result.stdout + help_result.stderr)
|
||||
self.assertNotIn("executable_override", READER.read_text(encoding="utf-8"))
|
||||
|
||||
def test_fail_closed_envelopes_pagination_and_missing_trusted_cli(self) -> None:
|
||||
for mode in ("okfalse", "code", "ambiguous", "noprog"):
|
||||
result = self.invoke("fetch", mode=mode)
|
||||
self.assertNotEqual(result.returncode, 0, mode)
|
||||
self.assertEqual(result.stdout, "", mode)
|
||||
with mock.patch.object(feishu_bug_intake, "MAX_PAGES", 2):
|
||||
result = self.invoke("fetch", mode="max")
|
||||
self.assertNotEqual(result.returncode, 0)
|
||||
self.assertEqual(result.stdout, "")
|
||||
with mock.patch.object(feishu_bug_intake, "resolve_lark_cli", side_effect=feishu_bug_intake.IntakeError("missing trusted")):
|
||||
result = self.invoke("fetch", resolver=feishu_bug_intake.IntakeError("missing trusted"))
|
||||
self.assertNotEqual(result.returncode, 0)
|
||||
self.assertEqual(result.stdout, "")
|
||||
|
||||
def test_reference_template_example_contract_signals(self) -> None:
|
||||
paths = [ROOT / "skills/ack/references/feishu-bug-intake.md", ROOT / "skills/ack/templates/tasks.template.yaml", ROOT / "skills/ack/examples/tasks.example.yaml"]
|
||||
content = "\n".join(path.read_text(encoding="utf-8") for path in paths)
|
||||
self.assertIn("feishu-base:sha256:", content)
|
||||
self.assertIn('npm install --global --prefix "$HOME/.local" @larksuite/cli@latest', content)
|
||||
self.assertIn("profile add", content)
|
||||
self.assertIn("--brand feishu", content)
|
||||
self.assertTrue("scope" in content)
|
||||
self.assertIn("不要把 `lark-cli auth check`", content)
|
||||
self.assertIn("审核通过前的唯一协作区", content)
|
||||
self.assertIn("不创建或刷新 `tasks.yaml` 中的 ACK 任务", content)
|
||||
self.assertIn("base:record:write", content)
|
||||
self.assertIn("fixLogic", content)
|
||||
self.assertNotIn("--lark-cli", content)
|
||||
self.assertNotIn("--executable", content)
|
||||
|
||||
def test_plan_organizes_stable_sources_against_a_real_task_board(self) -> None:
|
||||
first = json.loads(self.invoke("fetch").stdout)["records"][0]["sourceRef"]
|
||||
second = json.loads(self.invoke("fetch").stdout)["records"][0]["sourceRef"]
|
||||
self.assertRegex(first, r"^feishu-base:sha256:[0-9a-f]{64}$")
|
||||
self.assertEqual(first, second)
|
||||
empty_plan = json.loads(self.invoke("plan").stdout)
|
||||
self.assertEqual(empty_plan["actions"], [{
|
||||
"sourceRef": first,
|
||||
"recordId": "recBug1",
|
||||
"draftRevision": empty_plan["records"][0]["draftRevision"],
|
||||
"action": "create",
|
||||
}])
|
||||
self.assertRegex(
|
||||
empty_plan["actions"][0]["draftRevision"], r"^sha256:[0-9a-f]{64}$",
|
||||
)
|
||||
|
||||
base = self.board.read_text(encoding="utf-8")
|
||||
|
||||
def write_existing(status: str, updated_at: str, *, duplicate: bool = False) -> None:
|
||||
task = f"""tasks:
|
||||
- id: BUG-1
|
||||
title: Existing imported bug
|
||||
status: {status}
|
||||
source:
|
||||
kind: feishu-base
|
||||
ref: "{first}"
|
||||
recordId: recBug1
|
||||
updatedAt: "{updated_at}"
|
||||
"""
|
||||
if duplicate:
|
||||
task += f""" - id: BUG-2
|
||||
title: Duplicate imported bug
|
||||
status: open
|
||||
source:
|
||||
kind: feishu-base
|
||||
ref: "{first}"
|
||||
recordId: recBug1
|
||||
updatedAt: "{updated_at}"
|
||||
"""
|
||||
self.board.write_text(base.replace("tasks: []\n", task), encoding="utf-8")
|
||||
|
||||
write_existing("open", "2026-07-31T12:00:00Z")
|
||||
validator = ROOT / "skills/ack/scripts/validate_tasks.py"
|
||||
validated = subprocess.run(
|
||||
[sys.executable, str(validator), str(self.board)],
|
||||
text=True, capture_output=True, check=False,
|
||||
)
|
||||
self.assertEqual(validated.returncode, 0, validated.stderr)
|
||||
self.assertEqual(json.loads(self.invoke("plan").stdout)["actions"][0]["action"], "refresh")
|
||||
|
||||
write_existing("verified", "2026-07-31T12:00:00Z")
|
||||
self.assertEqual(json.loads(self.invoke("plan").stdout)["actions"][0]["action"], "drift")
|
||||
|
||||
write_existing("verified", "2026-08-01T12:00:00Z")
|
||||
self.assertEqual(json.loads(self.invoke("plan").stdout)["actions"][0]["action"], "unchanged")
|
||||
|
||||
write_existing("open", "2026-07-31T12:00:00Z", duplicate=True)
|
||||
duplicate_result = self.invoke("plan")
|
||||
self.assertNotEqual(duplicate_result.returncode, 0)
|
||||
self.assertEqual(duplicate_result.stdout, "")
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
@@ -0,0 +1,396 @@
|
||||
from __future__ import annotations
|
||||
|
||||
import contextlib
|
||||
import io
|
||||
import json
|
||||
import os
|
||||
import sys
|
||||
import tempfile
|
||||
import unittest
|
||||
from pathlib import Path
|
||||
from unittest import mock
|
||||
|
||||
|
||||
REPO_ROOT = Path(__file__).resolve().parents[1]
|
||||
ACK_SCRIPTS = REPO_ROOT / "skills" / "ack" / "scripts"
|
||||
sys.path.insert(0, str(ACK_SCRIPTS))
|
||||
import feishu_bug_intake # noqa: E402
|
||||
|
||||
|
||||
BOARD = """version: 1
|
||||
project:
|
||||
name: demo
|
||||
bugIntake:
|
||||
provider: feishu-base
|
||||
profile: tenant-b
|
||||
baseToken: bascnDemo
|
||||
tableId: tblDemo
|
||||
viewId: vewReady
|
||||
fields:
|
||||
title: fldTitle
|
||||
actual: fldActual
|
||||
expected: fldExpected
|
||||
stepsToReproduce: fldSteps
|
||||
acceptance: fldAcceptance
|
||||
priority: fldPriority
|
||||
attachments: fldAttachments
|
||||
updatedAt: fldUpdated
|
||||
tasks: []
|
||||
"""
|
||||
|
||||
|
||||
class FeishuBugIntakeUnitTests(unittest.TestCase):
|
||||
def make_fake_cli(self, root: Path) -> tuple[Path, Path]:
|
||||
log_path = root / "calls.jsonl"
|
||||
fake = root / "lark-cli"
|
||||
fake.write_text(
|
||||
"#!" + sys.executable + "\n"
|
||||
"import json, pathlib, sys\n"
|
||||
f"log = pathlib.Path({str(log_path)!r})\n"
|
||||
"args = sys.argv[1:]\n"
|
||||
"with log.open('a') as f: f.write(json.dumps(args) + '\\n')\n"
|
||||
"if args[:2] == ['profile', 'list']:\n"
|
||||
" if '--format' in args: raise SystemExit(8)\n"
|
||||
" print(json.dumps([{'name':'tenant-a','appId':'cli_a','brand':'feishu','active':True},{'name':'tenant-b','appId':'cli_b','brand':'feishu','active':False}]))\n"
|
||||
"elif args[:2] == ['base', '+record-list']:\n"
|
||||
" fields=['fldTitle','fldActual','fldExpected','fldSteps','fldAcceptance','fldPriority','fldAttachments','fldUpdated']; row=[' Bug\\n title ',' actual ','expected',['one','two'],'1. save succeeds\\n2. the crash no longer occurs','P1',[{'file_token':'fileA','name':'shot.png','type':'image/png','size':3}],'2026-08-01']\n"
|
||||
" if 'fldFixLogic' in args: fields.append('fldFixLogic'); row.append('change parser without widening input')\n"
|
||||
" print(json.dumps({'code': 0, 'data': {'fields': fields, 'record_id_list': ['recA'], 'data': [row]}}))\n"
|
||||
"elif args[:2] == ['base', '+record-download-attachment']:\n"
|
||||
" out = pathlib.Path(args[args.index('--output') + 1]); out.mkdir(parents=True, exist_ok=True); (out / 'shot.png').write_bytes(b'png'); print(json.dumps({'ok': True, 'data': {}}))\n"
|
||||
"elif args[:2] == ['base', '+record-upsert']:\n"
|
||||
" print(json.dumps({'code': 0, 'data': {}}))\n"
|
||||
"else: raise SystemExit(2)\n",
|
||||
encoding="utf-8",
|
||||
)
|
||||
fake.chmod(0o755)
|
||||
return fake, log_path
|
||||
|
||||
def invoke(self, argv: list[str], executable: Path) -> tuple[int, str, str]:
|
||||
stdout, stderr = io.StringIO(), io.StringIO()
|
||||
with mock.patch.object(feishu_bug_intake, "resolve_lark_cli", return_value=executable), contextlib.redirect_stdout(stdout), contextlib.redirect_stderr(stderr):
|
||||
code = feishu_bug_intake.main(argv)
|
||||
return code, stdout.getvalue(), stderr.getvalue()
|
||||
|
||||
def test_reader_exposes_check_and_fetch_commands(self) -> None:
|
||||
with self.assertRaises(SystemExit) as exited, contextlib.redirect_stdout(io.StringIO()):
|
||||
feishu_bug_intake.main(["--help"])
|
||||
self.assertEqual(exited.exception.code, 0)
|
||||
|
||||
def test_fetch_uses_mocked_trusted_executable_and_official_wire_shapes(self) -> None:
|
||||
with tempfile.TemporaryDirectory() as temp_dir:
|
||||
temp = Path(temp_dir)
|
||||
board_path = temp / "tasks.yaml"
|
||||
board_path.write_text(BOARD, encoding="utf-8")
|
||||
fake, log_path = self.make_fake_cli(temp)
|
||||
hostile = temp / "hostile"
|
||||
hostile.mkdir()
|
||||
(hostile / "lark-cli").write_text("#!/bin/sh\nexit 99\n", encoding="utf-8")
|
||||
(hostile / "lark-cli").chmod(0o755)
|
||||
|
||||
with mock.patch.dict(os.environ, {"PATH": str(hostile)}, clear=False):
|
||||
code, output, error = self.invoke(["fetch", str(board_path), "--output-dir", str(temp / "downloads")], fake)
|
||||
|
||||
self.assertEqual(code, 0, error)
|
||||
payload = json.loads(output)
|
||||
self.assertEqual(payload["records"][0]["title"], "Bug title")
|
||||
self.assertEqual(payload["records"][0]["steps"], "one\ntwo")
|
||||
self.assertRegex(payload["records"][0]["sourceRef"], r"^feishu-base:sha256:[0-9a-f]{64}$")
|
||||
self.assertNotIn("bascnDemo", output)
|
||||
self.assertNotIn("fileA", output)
|
||||
self.assertNotIn("token", payload["records"][0]["attachments"][0])
|
||||
self.assertTrue(Path(payload["records"][0]["attachments"][0]["localPath"]).is_file())
|
||||
calls = [json.loads(line) for line in log_path.read_text(encoding="utf-8").splitlines()]
|
||||
self.assertEqual(calls[0], ["profile", "list"])
|
||||
for call in calls:
|
||||
if call[:1] == ["base"]:
|
||||
self.assertEqual(call[call.index("--profile") + 1], "tenant-b")
|
||||
|
||||
def test_resolver_ignores_hostile_path_and_rejects_unsafe_target(self) -> None:
|
||||
with tempfile.TemporaryDirectory() as temp_dir:
|
||||
temp = Path(temp_dir)
|
||||
trusted, hostile = temp / "trusted", temp / "hostile"
|
||||
trusted.mkdir()
|
||||
hostile.mkdir()
|
||||
safe = trusted / "lark-cli"
|
||||
safe.write_text("#!/bin/sh\nexit 0\n", encoding="utf-8")
|
||||
safe.chmod(0o755)
|
||||
(hostile / "lark-cli").write_text("#!/bin/sh\nexit 99\n", encoding="utf-8")
|
||||
(hostile / "lark-cli").chmod(0o755)
|
||||
with mock.patch.object(feishu_bug_intake, "trusted_lark_cli_dirs", return_value=[trusted]), mock.patch.dict(os.environ, {"PATH": str(hostile)}, clear=False):
|
||||
self.assertEqual(feishu_bug_intake.resolve_lark_cli(), safe)
|
||||
safe.chmod(0o775)
|
||||
with mock.patch.object(feishu_bug_intake, "trusted_lark_cli_dirs", return_value=[trusted]):
|
||||
with self.assertRaisesRegex(feishu_bug_intake.IntakeError, "trusted"):
|
||||
feishu_bug_intake.resolve_lark_cli()
|
||||
|
||||
def test_resolver_accepts_only_the_official_npm_wrapper_shape(self) -> None:
|
||||
with tempfile.TemporaryDirectory() as temp_dir:
|
||||
temp = Path(temp_dir)
|
||||
trusted = temp / "trusted"
|
||||
scripts = temp / "node_modules" / "@larksuite" / "cli" / "scripts"
|
||||
trusted.mkdir()
|
||||
scripts.mkdir(parents=True)
|
||||
wrapper = scripts / "run.js"
|
||||
wrapper.write_text(
|
||||
"#!" + sys.executable + "\nimport json\nprint(json.dumps({'ok': True}))\n",
|
||||
encoding="utf-8",
|
||||
)
|
||||
wrapper.chmod(0o755)
|
||||
manifest = scripts.parent / "package.json"
|
||||
manifest.write_text(json.dumps({
|
||||
"name": "@larksuite/cli",
|
||||
"bin": {"lark-cli": "scripts/run.js"},
|
||||
}), encoding="utf-8")
|
||||
native = scripts.parent / "bin" / "lark-cli"
|
||||
native.parent.mkdir()
|
||||
native.write_text(
|
||||
"#!" + sys.executable + "\nimport json\nprint(json.dumps({'ok': True}))\n",
|
||||
encoding="utf-8",
|
||||
)
|
||||
native.chmod(0o755)
|
||||
(trusted / "lark-cli").symlink_to(wrapper)
|
||||
|
||||
with mock.patch.object(feishu_bug_intake, "trusted_lark_cli_dirs", return_value=[trusted]):
|
||||
self.assertEqual(feishu_bug_intake.resolve_lark_cli(), native)
|
||||
self.assertEqual(feishu_bug_intake.run_cli(["probe"]), {"ok": True})
|
||||
|
||||
manifest.write_text(json.dumps({
|
||||
"name": "lookalike",
|
||||
"bin": {"lark-cli": "scripts/run.js"},
|
||||
}), encoding="utf-8")
|
||||
with mock.patch.object(feishu_bug_intake, "trusted_lark_cli_dirs", return_value=[trusted]):
|
||||
with self.assertRaises(feishu_bug_intake.IntakeError):
|
||||
feishu_bug_intake.resolve_lark_cli()
|
||||
|
||||
def test_cli_environment_drops_credential_and_runtime_overrides(self) -> None:
|
||||
hostile = {
|
||||
"LARKSUITE_CLI_APP_ID": "wrong-app",
|
||||
"LARKSUITE_CLI_APP_SECRET": "wrong-secret",
|
||||
"LARKSUITE_CLI_CONFIG_DIR": "/tmp/wrong-config",
|
||||
"LARKSUITE_CLI_BRAND": "lark",
|
||||
"FEISHU_APP_SECRET": "wrong-feishu-secret",
|
||||
"NODE_OPTIONS": "--require=/tmp/inject.js",
|
||||
"PYTHONPATH": "/tmp/inject",
|
||||
}
|
||||
with mock.patch.dict(os.environ, hostile, clear=False):
|
||||
environment = feishu_bug_intake.cli_environment()
|
||||
with tempfile.TemporaryDirectory() as temp_dir:
|
||||
fake = Path(temp_dir) / "lark-cli"
|
||||
fake.write_text(
|
||||
"#!" + sys.executable + "\n"
|
||||
"import json, os\n"
|
||||
"keys = ['LARKSUITE_CLI_APP_ID','LARKSUITE_CLI_APP_SECRET','LARKSUITE_CLI_CONFIG_DIR','LARKSUITE_CLI_BRAND','FEISHU_APP_SECRET','NODE_OPTIONS','PYTHONPATH']\n"
|
||||
"print(json.dumps({'ok': True, 'data': {key: os.environ.get(key) for key in keys}}))\n",
|
||||
encoding="utf-8",
|
||||
)
|
||||
fake.chmod(0o755)
|
||||
with mock.patch.object(feishu_bug_intake, "resolve_lark_cli", return_value=fake):
|
||||
child = feishu_bug_intake.run_cli(["probe"])
|
||||
self.assertEqual(set(environment) - {"HOME", "PATH"}, set(environment) & {"LANG", "LC_ALL", "LC_CTYPE"})
|
||||
for name in hostile:
|
||||
self.assertNotIn(name, environment)
|
||||
self.assertIsNone(child["data"][name])
|
||||
|
||||
def test_run_cli_rejects_error_and_ambiguous_envelopes(self) -> None:
|
||||
with tempfile.TemporaryDirectory() as temp_dir:
|
||||
temp = Path(temp_dir)
|
||||
fake = temp / "lark-cli"
|
||||
fake.write_text(
|
||||
"#!" + sys.executable + "\nimport json, sys\nprint(sys.argv[1])\n",
|
||||
encoding="utf-8",
|
||||
)
|
||||
fake.chmod(0o755)
|
||||
with mock.patch.object(feishu_bug_intake, "resolve_lark_cli", return_value=fake):
|
||||
for response in ('{"ok":false}', '{"code":7}', '{"data":{}}'):
|
||||
with self.assertRaises(feishu_bug_intake.IntakeError):
|
||||
feishu_bug_intake.run_cli([response])
|
||||
|
||||
def test_matrix_accepts_official_ok_envelope_and_data_rows(self) -> None:
|
||||
fields = ["fldTitle"]
|
||||
response = {
|
||||
"ok": True,
|
||||
"data": {"fields": fields, "record_id_list": ["recA"], "data": [["Bug"]]},
|
||||
}
|
||||
self.assertEqual(feishu_bug_intake.matrix_from_response(response, fields), (["recA"], [["Bug"]]))
|
||||
|
||||
def test_optional_fix_logic_field_is_normalized_for_preapproval_review(self) -> None:
|
||||
with tempfile.TemporaryDirectory() as temp_dir:
|
||||
board_path = Path(temp_dir) / "tasks.yaml"
|
||||
board_path.write_text(
|
||||
BOARD.replace(
|
||||
" profile: tenant-b\n",
|
||||
" workflow: reviewed-writeback-v1\n profile: tenant-b\n",
|
||||
).replace(
|
||||
" acceptance: fldAcceptance\n",
|
||||
" acceptance: fldAcceptance\n fixLogic: fldFixLogic\n",
|
||||
),
|
||||
encoding="utf-8",
|
||||
)
|
||||
config = feishu_bug_intake.config_from_board(
|
||||
feishu_bug_intake.load_board(board_path)
|
||||
)
|
||||
row = [
|
||||
"Bug", "actual", "expected", "steps", "acceptance", "P1", [],
|
||||
"2026-08-01T12:00:00Z", "change parser without widening input",
|
||||
]
|
||||
with mock.patch.object(feishu_bug_intake, "profile_check"), mock.patch.object(
|
||||
feishu_bug_intake, "fetch_pages", return_value=[("recA", row)]
|
||||
):
|
||||
payload = feishu_bug_intake.fetch(config, None)
|
||||
|
||||
record = payload["records"][0]
|
||||
self.assertEqual(record["fixLogic"], "change parser without widening input")
|
||||
self.assertNotIn("fixLogic", record["enrichmentRequired"])
|
||||
|
||||
def test_write_draft_uses_trusted_cli_and_only_configured_review_fields(self) -> None:
|
||||
with tempfile.TemporaryDirectory() as temp_dir:
|
||||
temp = Path(temp_dir)
|
||||
board_path = temp / "tasks.yaml"
|
||||
board_path.write_text(
|
||||
BOARD.replace(
|
||||
" profile: tenant-b\n",
|
||||
" workflow: reviewed-writeback-v1\n profile: tenant-b\n",
|
||||
).replace(
|
||||
" acceptance: fldAcceptance\n",
|
||||
" acceptance: fldAcceptance\n fixLogic: fldFixLogic\n",
|
||||
),
|
||||
encoding="utf-8",
|
||||
)
|
||||
draft_path = temp / "draft.json"
|
||||
draft_path.write_text(json.dumps({
|
||||
"fixLogic": "change parser without widening input",
|
||||
"acceptance": ["save succeeds", "the crash no longer occurs"],
|
||||
}), encoding="utf-8")
|
||||
fake, log_path = self.make_fake_cli(temp)
|
||||
|
||||
fetched_code, fetched_output, fetched_error = self.invoke([
|
||||
"fetch", str(board_path),
|
||||
], fake)
|
||||
self.assertEqual(fetched_code, 0, fetched_error)
|
||||
fetched_record = json.loads(fetched_output)["records"][0]
|
||||
|
||||
code, output, error = self.invoke([
|
||||
"write-draft", str(board_path), "--record-id", "recA",
|
||||
"--expected-source-ref", fetched_record["sourceRef"],
|
||||
"--expected-draft-revision", fetched_record["draftRevision"],
|
||||
"--input", str(draft_path),
|
||||
], fake)
|
||||
|
||||
self.assertEqual(code, 0, error)
|
||||
self.assertEqual(json.loads(output)["written"], ["fixLogic", "acceptance"])
|
||||
self.assertRegex(json.loads(output)["draftRevision"], r"^sha256:[0-9a-f]{64}$")
|
||||
calls = [json.loads(line) for line in log_path.read_text(encoding="utf-8").splitlines()]
|
||||
write_call = next(call for call in calls if call[:2] == ["base", "+record-upsert"])
|
||||
self.assertEqual(write_call[write_call.index("--profile") + 1], "tenant-b")
|
||||
patch = json.loads(write_call[write_call.index("--json") + 1])
|
||||
self.assertEqual(set(patch), {"fldFixLogic", "fldAcceptance"})
|
||||
self.assertIn("1. save succeeds", patch["fldAcceptance"])
|
||||
|
||||
imported_code, imported_output, imported_error = self.invoke([
|
||||
"import-approved", str(board_path), "--record-id", "recA",
|
||||
"--expected-source-ref", fetched_record["sourceRef"],
|
||||
"--expected-draft-revision", fetched_record["draftRevision"],
|
||||
], fake)
|
||||
self.assertEqual(imported_code, 0, imported_error)
|
||||
task_draft = json.loads(imported_output)["taskDraft"]
|
||||
self.assertEqual(task_draft["source"]["workflow"], "reviewed-writeback-v1")
|
||||
self.assertEqual(
|
||||
task_draft["acceptanceCriteria"],
|
||||
["save succeeds", "the crash no longer occurs"],
|
||||
)
|
||||
self.assertRegex(
|
||||
task_draft["source"]["approvedPayloadHash"], r"^sha256:[0-9a-f]{64}$",
|
||||
)
|
||||
|
||||
def test_write_draft_rejects_stale_revision_before_mutation(self) -> None:
|
||||
with tempfile.TemporaryDirectory() as temp_dir:
|
||||
temp = Path(temp_dir)
|
||||
board_path = temp / "tasks.yaml"
|
||||
board_path.write_text(
|
||||
BOARD.replace(
|
||||
" profile: tenant-b\n",
|
||||
" workflow: reviewed-writeback-v1\n profile: tenant-b\n",
|
||||
).replace(
|
||||
" acceptance: fldAcceptance\n",
|
||||
" acceptance: fldAcceptance\n fixLogic: fldFixLogic\n",
|
||||
),
|
||||
encoding="utf-8",
|
||||
)
|
||||
draft_path = temp / "draft.json"
|
||||
draft_path.write_text(json.dumps({
|
||||
"fixLogic": "fix",
|
||||
"acceptance": ["pass"],
|
||||
}), encoding="utf-8")
|
||||
fake, log_path = self.make_fake_cli(temp)
|
||||
fetched = json.loads(self.invoke(["fetch", str(board_path)], fake)[1])["records"][0]
|
||||
|
||||
code, _, _ = self.invoke([
|
||||
"write-draft", str(board_path), "--record-id", "recA",
|
||||
"--expected-source-ref", fetched["sourceRef"],
|
||||
"--expected-draft-revision", "sha256:" + "0" * 64,
|
||||
"--input", str(draft_path),
|
||||
], fake)
|
||||
|
||||
self.assertNotEqual(code, 0)
|
||||
calls = [json.loads(line) for line in log_path.read_text(encoding="utf-8").splitlines()]
|
||||
self.assertFalse(any(call[:2] == ["base", "+record-upsert"] for call in calls))
|
||||
|
||||
def test_write_draft_rejects_symlink_and_unknown_fields(self) -> None:
|
||||
with tempfile.TemporaryDirectory() as temp_dir:
|
||||
temp = Path(temp_dir)
|
||||
target = temp / "draft.json"
|
||||
target.write_text(json.dumps({
|
||||
"fixLogic": "fix",
|
||||
"acceptance": ["pass"],
|
||||
"unexpected": "do not write",
|
||||
}), encoding="utf-8")
|
||||
with self.assertRaises(feishu_bug_intake.IntakeError):
|
||||
feishu_bug_intake.load_draft(target)
|
||||
|
||||
target.write_text(json.dumps({
|
||||
"fixLogic": "fix",
|
||||
"acceptance": ["pass"],
|
||||
}), encoding="utf-8")
|
||||
linked = temp / "linked.json"
|
||||
linked.symlink_to(target)
|
||||
with self.assertRaises(feishu_bug_intake.IntakeError):
|
||||
feishu_bug_intake.load_draft(linked)
|
||||
|
||||
def test_draft_revision_binds_attachment_identity(self) -> None:
|
||||
record = {
|
||||
"sourceRef": "feishu-base:sha256:" + "a" * 64,
|
||||
"updatedAt": "2026-08-03T12:00:00+08:00",
|
||||
"title": "Bug",
|
||||
"actual": "crash",
|
||||
"expected": "save",
|
||||
"steps": "open then save",
|
||||
"fixLogic": "fix parser",
|
||||
"acceptance": "save succeeds",
|
||||
"priority": "P1",
|
||||
"attachments": [{"name": "same.png", "type": "image/png", "size": 4}],
|
||||
}
|
||||
first = feishu_bug_intake.draft_revision(record, ["fileTokenA"])
|
||||
second = feishu_bug_intake.draft_revision(record, ["fileTokenB"])
|
||||
self.assertNotEqual(first, second)
|
||||
|
||||
def test_attachments_and_required_text_are_resource_bounded_and_strict(self) -> None:
|
||||
with self.assertRaises(feishu_bug_intake.IntakeError):
|
||||
feishu_bug_intake.attachment_items([{
|
||||
"file_token": "fileA",
|
||||
"name": "huge.png",
|
||||
"type": "image/png",
|
||||
"size": feishu_bug_intake.MAX_ATTACHMENT_BYTES + 1,
|
||||
}])
|
||||
too_many = [
|
||||
{"file_token": f"file{index}", "name": f"{index}.png", "size": 1}
|
||||
for index in range(feishu_bug_intake.MAX_ATTACHMENTS_PER_RECORD + 1)
|
||||
]
|
||||
with self.assertRaises(feishu_bug_intake.IntakeError):
|
||||
feishu_bug_intake.attachment_items(too_many)
|
||||
with self.assertRaises(feishu_bug_intake.IntakeError):
|
||||
feishu_bug_intake.text({"unexpected": "value"})
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
@@ -0,0 +1,937 @@
|
||||
from __future__ import annotations
|
||||
|
||||
import copy
|
||||
import json
|
||||
import subprocess
|
||||
import sys
|
||||
import tempfile
|
||||
import unittest
|
||||
from pathlib import Path
|
||||
from unittest import mock
|
||||
|
||||
import yaml
|
||||
|
||||
|
||||
REPO_ROOT = Path(__file__).resolve().parents[1]
|
||||
ACK_DIR = REPO_ROOT / "skills" / "ack"
|
||||
SCRIPTS_DIR = ACK_DIR / "scripts"
|
||||
SCHEMA_PATH = ACK_DIR / "templates" / "knowledge.schema.json"
|
||||
EXAMPLE_PATH = ACK_DIR / "examples" / "knowledge.example.yaml"
|
||||
TASKS_EXAMPLE_PATH = ACK_DIR / "examples" / "tasks.example.yaml"
|
||||
|
||||
sys.path.insert(0, str(SCRIPTS_DIR))
|
||||
import select_knowledge # noqa: E402
|
||||
import validate_knowledge # noqa: E402
|
||||
|
||||
|
||||
def example_data() -> dict:
|
||||
return yaml.safe_load(EXAMPLE_PATH.read_text(encoding="utf-8"))
|
||||
|
||||
|
||||
class AckKnowledgeTests(unittest.TestCase):
|
||||
def test_schema_template_and_example_are_aligned(self) -> None:
|
||||
schema = json.loads(SCHEMA_PATH.read_text(encoding="utf-8"))
|
||||
template = yaml.safe_load(
|
||||
(ACK_DIR / "templates" / "knowledge.template.yaml").read_text(
|
||||
encoding="utf-8"
|
||||
)
|
||||
)
|
||||
self.assertEqual(
|
||||
schema["definitions"]["entry"]["properties"]["kind"]["enum"],
|
||||
["guardrail", "pitfall", "verification"],
|
||||
)
|
||||
self.assertEqual(
|
||||
schema["definitions"]["entry"]["properties"]["status"]["enum"],
|
||||
["active", "stale", "superseded", "archived"],
|
||||
)
|
||||
self.assertEqual(template["entries"], [])
|
||||
self.assertEqual(template["verificationRegistry"], {})
|
||||
|
||||
errors, _ = validate_knowledge.validate_all(
|
||||
example_data(), SCHEMA_PATH, use_schema=False
|
||||
)
|
||||
self.assertEqual(errors, [])
|
||||
self.assertEqual(
|
||||
validate_knowledge.stable_ref(example_data()["entries"][0]), "K-001@1"
|
||||
)
|
||||
|
||||
def test_semantics_run_even_when_schema_reports_no_errors(self) -> None:
|
||||
data = example_data()
|
||||
data["entries"].append(copy.deepcopy(data["entries"][0]))
|
||||
with mock.patch.object(
|
||||
validate_knowledge, "validate_with_schema", return_value=[]
|
||||
):
|
||||
errors, mode = validate_knowledge.validate_all(
|
||||
data, SCHEMA_PATH, use_schema=True
|
||||
)
|
||||
self.assertIn("内置语义", mode)
|
||||
self.assertTrue(any("稳定引用 K-001@1 重复" in error for error in errors))
|
||||
|
||||
def test_blank_required_text_fails_in_builtin_and_schema_modes(self) -> None:
|
||||
data = example_data()
|
||||
data["entries"][0]["title"] = " \t "
|
||||
|
||||
builtin_errors, _ = validate_knowledge.validate_all(
|
||||
data, SCHEMA_PATH, use_schema=False
|
||||
)
|
||||
with mock.patch.object(
|
||||
validate_knowledge, "validate_with_schema", return_value=[]
|
||||
):
|
||||
schema_errors, _ = validate_knowledge.validate_all(
|
||||
data, SCHEMA_PATH, use_schema=True
|
||||
)
|
||||
|
||||
self.assertTrue(any("title: 必须是非空字符串" in e for e in builtin_errors))
|
||||
self.assertTrue(any("title: 必须是非空字符串" in e for e in schema_errors))
|
||||
schema = json.loads(SCHEMA_PATH.read_text(encoding="utf-8"))
|
||||
self.assertEqual(
|
||||
schema["definitions"]["entry"]["properties"]["title"]["pattern"],
|
||||
"\\S",
|
||||
)
|
||||
|
||||
def test_temporary_entry_requires_removal_condition_and_review_date(self) -> None:
|
||||
data = example_data()
|
||||
entry = data["entries"][0]
|
||||
entry["temporary"] = True
|
||||
entry["removalCondition"] = None
|
||||
entry["reviewAfter"] = None
|
||||
errors = validate_knowledge.validate_semantics(data)
|
||||
self.assertTrue(any("removalCondition" in error for error in errors))
|
||||
self.assertTrue(any("reviewAfter" in error for error in errors))
|
||||
|
||||
def test_overdue_active_entry_requires_revalidation(self) -> None:
|
||||
data = example_data()
|
||||
data["entries"][0]["reviewAfter"] = "2020-01-01T00:00:00+00:00"
|
||||
|
||||
errors = validate_knowledge.validate_semantics(data)
|
||||
|
||||
self.assertTrue(any("必须重新验证或标记 stale" in error for error in errors))
|
||||
|
||||
def test_global_active_entry_requires_decision_owner_approval(self) -> None:
|
||||
data = example_data()
|
||||
data["entries"][0]["scope"] = {
|
||||
"all": True,
|
||||
"components": [],
|
||||
"paths": [],
|
||||
"dependencies": [],
|
||||
"versions": [],
|
||||
"tags": [],
|
||||
"symbols": [],
|
||||
"errorSignatures": [],
|
||||
}
|
||||
|
||||
errors = validate_knowledge.validate_semantics(data)
|
||||
|
||||
self.assertTrue(any("Decision Owner approval" in error for error in errors))
|
||||
|
||||
def test_active_conflicts_and_duplicate_active_revision_are_rejected(self) -> None:
|
||||
data = example_data()
|
||||
conflicting = copy.deepcopy(data["entries"][0])
|
||||
conflicting.update(
|
||||
{
|
||||
"id": "K-002",
|
||||
"subject": "service-process-alignment",
|
||||
"conflictsWith": ["K-001@1"],
|
||||
}
|
||||
)
|
||||
data["entries"].append(conflicting)
|
||||
errors = validate_knowledge.validate_semantics(data)
|
||||
self.assertTrue(any("active 条目不能与 active K-001@1 冲突" in e for e in errors))
|
||||
|
||||
conflicting["id"] = "K-001"
|
||||
conflicting["revision"] = 2
|
||||
conflicting["conflictsWith"] = []
|
||||
errors = validate_knowledge.validate_semantics(data)
|
||||
self.assertTrue(any("多个 active revision" in error for error in errors))
|
||||
|
||||
def test_verification_ref_must_resolve_to_contained_registry_target(self) -> None:
|
||||
data = example_data()
|
||||
data["entries"][0]["verification"]["ref"] = "missing-check"
|
||||
errors = validate_knowledge.validate_semantics(data)
|
||||
self.assertTrue(any("未在 verificationRegistry 注册" in e for e in errors))
|
||||
|
||||
data = example_data()
|
||||
data["verificationRegistry"]["service-worktree-alignment"]["path"] = "../run.sh"
|
||||
errors = validate_knowledge.validate_semantics(data)
|
||||
self.assertTrue(any("必须是仓库内相对路径" in error for error in errors))
|
||||
|
||||
def test_verification_registry_rejects_any_symlink_component(self) -> None:
|
||||
data = example_data()
|
||||
data["verificationRegistry"]["service-worktree-alignment"]["path"] = (
|
||||
"checks/verify.py"
|
||||
)
|
||||
with tempfile.TemporaryDirectory() as temp_dir:
|
||||
base = Path(temp_dir)
|
||||
project = base / "project"
|
||||
outside = base / "outside"
|
||||
project.mkdir()
|
||||
outside.mkdir()
|
||||
(project / "checks").symlink_to(outside, target_is_directory=True)
|
||||
|
||||
errors = validate_knowledge.validate_semantics(
|
||||
data, project_root=project
|
||||
)
|
||||
|
||||
self.assertTrue(any("symlink" in error for error in errors))
|
||||
|
||||
data = example_data()
|
||||
data["verificationRegistry"]["service-worktree-alignment"]["path"] = (
|
||||
"checks/verify.py"
|
||||
)
|
||||
with tempfile.TemporaryDirectory() as temp_dir:
|
||||
project = Path(temp_dir) / "project"
|
||||
real_checks = project / "real-checks"
|
||||
real_checks.mkdir(parents=True)
|
||||
target = real_checks / "verify.py"
|
||||
target.write_text("#!/bin/sh\nexit 0\n", encoding="utf-8")
|
||||
target.chmod(target.stat().st_mode | 0o111)
|
||||
(project / "checks").symlink_to(
|
||||
real_checks,
|
||||
target_is_directory=True,
|
||||
)
|
||||
|
||||
errors = validate_knowledge.validate_semantics(
|
||||
data,
|
||||
project_root=project,
|
||||
)
|
||||
|
||||
self.assertTrue(any("symlink" in error for error in errors))
|
||||
|
||||
data = example_data()
|
||||
data["verificationRegistry"]["service-worktree-alignment"]["path"] = (
|
||||
"tests/check.sh;touch"
|
||||
)
|
||||
errors = validate_knowledge.validate_semantics(data)
|
||||
self.assertTrue(any("必须是仓库内相对路径" in error for error in errors))
|
||||
|
||||
def test_verification_registry_requires_regular_executable_target(self) -> None:
|
||||
data = example_data()
|
||||
data["verificationRegistry"]["service-worktree-alignment"]["path"] = (
|
||||
"checks/verify"
|
||||
)
|
||||
with tempfile.TemporaryDirectory() as temp_dir:
|
||||
project = Path(temp_dir) / "project"
|
||||
project.mkdir()
|
||||
|
||||
missing = validate_knowledge.validate_semantics(
|
||||
data,
|
||||
project_root=project,
|
||||
)
|
||||
self.assertTrue(any("不存在" in error for error in missing))
|
||||
|
||||
target = project / "checks" / "verify"
|
||||
target.parent.mkdir()
|
||||
target.write_text("#!/bin/sh\nexit 0\n", encoding="utf-8")
|
||||
not_executable = validate_knowledge.validate_semantics(
|
||||
data,
|
||||
project_root=project,
|
||||
)
|
||||
self.assertTrue(
|
||||
any("不可执行" in error for error in not_executable)
|
||||
)
|
||||
|
||||
target.chmod(target.stat().st_mode | 0o111)
|
||||
valid = validate_knowledge.validate_semantics(
|
||||
data,
|
||||
project_root=project,
|
||||
)
|
||||
self.assertFalse(
|
||||
any("verificationRegistry" in error for error in valid),
|
||||
valid,
|
||||
)
|
||||
|
||||
def test_free_command_fields_are_rejected_and_never_executed(self) -> None:
|
||||
data = example_data()
|
||||
data["entries"][0]["command"] = "echo unsafe"
|
||||
errors = validate_knowledge.validate_semantics(data)
|
||||
self.assertTrue(any("不保存或执行自由命令" in error for error in errors))
|
||||
|
||||
with tempfile.TemporaryDirectory() as temp_dir:
|
||||
marker = Path(temp_dir) / "should-not-exist"
|
||||
safe = example_data()
|
||||
safe["entries"][0]["directive"] = f"touch {marker}"
|
||||
selected = select_knowledge.select_entries(
|
||||
safe,
|
||||
{
|
||||
"components": ["web"],
|
||||
"paths": ["web/app.py"],
|
||||
"dependencies": [],
|
||||
"versions": [],
|
||||
"tags": ["long-running-service"],
|
||||
"symbols": [],
|
||||
"errorSignatures": [],
|
||||
},
|
||||
)
|
||||
self.assertEqual(len(selected), 1)
|
||||
self.assertFalse(marker.exists())
|
||||
|
||||
def test_common_secret_material_is_rejected(self) -> None:
|
||||
data = example_data()
|
||||
data["entries"][0]["rationale"] = (
|
||||
"debug token=sk-abcdefghijklmnopqrstuvwxyz123456"
|
||||
)
|
||||
|
||||
errors = validate_knowledge.validate_semantics(data)
|
||||
|
||||
self.assertTrue(any("OpenAI-style token" in error for error in errors))
|
||||
self.assertTrue(any("脱敏摘要" in error for error in errors))
|
||||
|
||||
def test_selection_is_active_deterministic_and_limited(self) -> None:
|
||||
data = example_data()
|
||||
stale = copy.deepcopy(data["entries"][0])
|
||||
stale.update(
|
||||
{
|
||||
"id": "K-002",
|
||||
"status": "stale",
|
||||
"statusReason": "相关服务已移除",
|
||||
}
|
||||
)
|
||||
global_entry = copy.deepcopy(data["entries"][0])
|
||||
global_entry.update(
|
||||
{
|
||||
"id": "K-003",
|
||||
"subject": "global-release-check",
|
||||
"scope": {
|
||||
"all": True,
|
||||
"components": [],
|
||||
"paths": [],
|
||||
"dependencies": [],
|
||||
"versions": [],
|
||||
"tags": [],
|
||||
"symbols": [],
|
||||
"errorSignatures": [],
|
||||
},
|
||||
}
|
||||
)
|
||||
data["entries"].extend([stale, global_entry])
|
||||
context = {
|
||||
"components": ["web"],
|
||||
"paths": ["web/app.py"],
|
||||
"dependencies": [],
|
||||
"versions": [],
|
||||
"tags": ["long-running-service"],
|
||||
"symbols": [],
|
||||
"errorSignatures": [],
|
||||
}
|
||||
selected = select_knowledge.select_entries(data, context, limit=1)
|
||||
self.assertEqual(
|
||||
[validate_knowledge.stable_ref(entry) for entry in selected], ["K-003@1"]
|
||||
)
|
||||
self.assertFalse(
|
||||
select_knowledge.scope_matches(
|
||||
data["entries"][0]["scope"],
|
||||
{**context, "tags": []},
|
||||
)
|
||||
)
|
||||
|
||||
def test_global_entries_are_never_silently_dropped_by_limit(self) -> None:
|
||||
data = example_data()
|
||||
for number in range(2, 13):
|
||||
scoped = copy.deepcopy(data["entries"][0])
|
||||
scoped.update(
|
||||
{
|
||||
"id": f"K-{number:03d}",
|
||||
"subject": f"scoped-check-{number}",
|
||||
}
|
||||
)
|
||||
data["entries"].append(scoped)
|
||||
global_entry = copy.deepcopy(data["entries"][0])
|
||||
global_entry.update(
|
||||
{
|
||||
"id": "K-999",
|
||||
"subject": "global-release-check",
|
||||
"scope": {
|
||||
"all": True,
|
||||
"components": [],
|
||||
"paths": [],
|
||||
"dependencies": [],
|
||||
"versions": [],
|
||||
"tags": [],
|
||||
"symbols": [],
|
||||
"errorSignatures": [],
|
||||
},
|
||||
}
|
||||
)
|
||||
data["entries"].append(global_entry)
|
||||
context = {
|
||||
"components": ["web"],
|
||||
"paths": ["web/app.py"],
|
||||
"dependencies": [],
|
||||
"versions": [],
|
||||
"tags": ["long-running-service"],
|
||||
"symbols": [],
|
||||
"errorSignatures": [],
|
||||
}
|
||||
|
||||
selected = select_knowledge.select_entries(data, context, limit=10)
|
||||
|
||||
refs = [validate_knowledge.stable_ref(entry) for entry in selected]
|
||||
self.assertEqual(len(refs), 10)
|
||||
self.assertIn("K-999@1", refs)
|
||||
|
||||
second_global = copy.deepcopy(global_entry)
|
||||
second_global.update({"id": "K-998", "subject": "global-security-check"})
|
||||
data["entries"].append(second_global)
|
||||
with self.assertRaisesRegex(ValueError, "不能静默丢弃"):
|
||||
select_knowledge.select_entries(data, context, limit=1)
|
||||
|
||||
def test_path_glob_does_not_let_single_star_cross_directory(self) -> None:
|
||||
self.assertTrue(select_knowledge._path_glob_matches("web/app.py", "web/*"))
|
||||
self.assertFalse(
|
||||
select_knowledge._path_glob_matches("web/pages/app.py", "web/*")
|
||||
)
|
||||
self.assertTrue(
|
||||
select_knowledge._path_glob_matches("web/pages/app.py", "web/**")
|
||||
)
|
||||
|
||||
def test_limit_prefers_narrow_scope_without_rewarding_or_patterns(self) -> None:
|
||||
data = example_data()
|
||||
narrow = copy.deepcopy(data["entries"][0])
|
||||
narrow.update({"id": "K-002", "subject": "narrow-service-check"})
|
||||
narrow["scope"]["paths"] = ["web/special/**"]
|
||||
broad_or = copy.deepcopy(data["entries"][0])
|
||||
broad_or.update({"id": "K-003", "subject": "broad-or-service-check"})
|
||||
broad_or["scope"]["paths"] = ["web/special/**", "api/**"]
|
||||
data["entries"].extend([narrow, broad_or])
|
||||
context = {
|
||||
"components": ["web"],
|
||||
"paths": ["web/special/pages/app.py"],
|
||||
"dependencies": [],
|
||||
"versions": [],
|
||||
"tags": ["long-running-service"],
|
||||
"symbols": [],
|
||||
"errorSignatures": [],
|
||||
}
|
||||
|
||||
selected = select_knowledge.select_entries(data, context, limit=1)
|
||||
|
||||
self.assertEqual(validate_knowledge.stable_ref(selected[0]), "K-002@1")
|
||||
|
||||
def test_task_cross_validation_requires_active_exact_ref_and_passed_check(self) -> None:
|
||||
data = example_data()
|
||||
task = {
|
||||
"id": "BUG-002",
|
||||
"status": "verified",
|
||||
"knowledgeRefs": ["K-001@1"],
|
||||
"knowledgeApplied": [
|
||||
{
|
||||
"ref": "K-001@1",
|
||||
"result": "applied",
|
||||
"evidence": "developer report",
|
||||
}
|
||||
],
|
||||
"knowledgeChecks": [
|
||||
{
|
||||
"ref": "K-001@1",
|
||||
"result": "passed",
|
||||
"evidence": "test report",
|
||||
}
|
||||
],
|
||||
"dispatch": {
|
||||
"rounds": [
|
||||
{
|
||||
"round": 1,
|
||||
"attemptId": "BUG-002-A1",
|
||||
"result": "failed",
|
||||
},
|
||||
{
|
||||
"round": 2,
|
||||
"attemptId": "BUG-002-A2",
|
||||
"result": "passed",
|
||||
}
|
||||
]
|
||||
},
|
||||
}
|
||||
tasks_data = {
|
||||
"project": {
|
||||
"name": "notes-web",
|
||||
"knowledgeFile": "docs/ack/knowledge.yaml",
|
||||
},
|
||||
"tasks": [task],
|
||||
}
|
||||
self.assertEqual(
|
||||
validate_knowledge.validate_task_references(data, tasks_data), []
|
||||
)
|
||||
|
||||
task["knowledgeChecks"][0]["result"] = "not_applicable"
|
||||
errors = validate_knowledge.validate_task_references(data, tasks_data)
|
||||
self.assertTrue(any("缺少 passed knowledgeCheck" in error for error in errors))
|
||||
|
||||
data["entries"][0]["kind"] = "pitfall"
|
||||
errors = validate_knowledge.validate_task_references(data, tasks_data)
|
||||
self.assertTrue(any("缺少 passed knowledgeCheck" in error for error in errors))
|
||||
|
||||
task["knowledgeRefs"] = ["K-001@2"]
|
||||
errors = validate_knowledge.validate_task_references(data, tasks_data)
|
||||
self.assertTrue(any("找不到精确版本 K-001@2" in error for error in errors))
|
||||
|
||||
def test_task_cross_validation_rejects_another_project(self) -> None:
|
||||
data = example_data()
|
||||
tasks = {
|
||||
"project": {
|
||||
"name": "another-project",
|
||||
"knowledgeFile": "docs/ack/knowledge.yaml",
|
||||
},
|
||||
"tasks": [],
|
||||
}
|
||||
|
||||
errors = validate_knowledge.validate_task_references(data, tasks)
|
||||
|
||||
self.assertTrue(any("与知识库项目" in error for error in errors))
|
||||
|
||||
def test_cross_validation_requires_traceable_explicit_attempt_id(self) -> None:
|
||||
data = example_data()
|
||||
task = {
|
||||
"id": "BUG-002",
|
||||
"status": "open",
|
||||
"dispatch": {
|
||||
"rounds": [
|
||||
{
|
||||
"round": 1,
|
||||
"attemptId": "BUG-002-A1",
|
||||
"result": "failed",
|
||||
},
|
||||
{
|
||||
"round": 2,
|
||||
"attemptId": "orca-dispatch-91",
|
||||
"result": "passed",
|
||||
}
|
||||
]
|
||||
},
|
||||
}
|
||||
tasks_data = {
|
||||
"project": {
|
||||
"name": "notes-web",
|
||||
"knowledgeFile": "docs/ack/knowledge.yaml",
|
||||
},
|
||||
"tasks": [task],
|
||||
}
|
||||
|
||||
errors = validate_knowledge.validate_task_references(data, tasks_data)
|
||||
|
||||
self.assertTrue(any("必须精确等于 'BUG-002-A2'" in e for e in errors))
|
||||
self.assertTrue(any("未命中任务 'BUG-002'" in e for e in errors))
|
||||
|
||||
task["dispatch"]["rounds"][1]["attemptId"] = "BUG-002-A2"
|
||||
errors = validate_knowledge.validate_task_references(data, tasks_data)
|
||||
self.assertFalse(any("provenance" in error for error in errors))
|
||||
|
||||
def test_cross_validation_rejects_non_contiguous_rounds(self) -> None:
|
||||
data = example_data()
|
||||
data["entries"][0]["provenance"]["attemptId"] = "BUG-002-A3"
|
||||
tasks_data = {
|
||||
"project": {
|
||||
"name": "notes-web",
|
||||
"knowledgeFile": "docs/ack/knowledge.yaml",
|
||||
},
|
||||
"tasks": [
|
||||
{
|
||||
"id": "BUG-002",
|
||||
"status": "open",
|
||||
"dispatch": {
|
||||
"rounds": [
|
||||
{
|
||||
"round": 3,
|
||||
"attemptId": "BUG-002-A3",
|
||||
"result": "passed",
|
||||
}
|
||||
]
|
||||
},
|
||||
}
|
||||
],
|
||||
}
|
||||
|
||||
errors = validate_knowledge.validate_task_references(data, tasks_data)
|
||||
|
||||
self.assertTrue(any("round 必须按 1..N 连续" in error for error in errors))
|
||||
|
||||
def test_cross_validation_binds_configured_knowledge_file(self) -> None:
|
||||
data = example_data()
|
||||
task = {
|
||||
"id": "BUG-002",
|
||||
"status": "open",
|
||||
"dispatch": {
|
||||
"rounds": [
|
||||
{
|
||||
"round": 1,
|
||||
"attemptId": "BUG-002-A1",
|
||||
"result": "failed",
|
||||
},
|
||||
{
|
||||
"round": 2,
|
||||
"attemptId": "BUG-002-A2",
|
||||
"result": "passed",
|
||||
}
|
||||
]
|
||||
},
|
||||
}
|
||||
with tempfile.TemporaryDirectory() as temp_dir:
|
||||
project = Path(temp_dir) / "project"
|
||||
ack_dir = project / "docs" / "ack"
|
||||
ack_dir.mkdir(parents=True)
|
||||
knowledge_path = ack_dir / "knowledge.yaml"
|
||||
tasks_path = ack_dir / "tasks.yaml"
|
||||
knowledge_path.write_text(
|
||||
yaml.safe_dump(data, allow_unicode=True), encoding="utf-8"
|
||||
)
|
||||
tasks_data = {
|
||||
"project": {
|
||||
"name": "notes-web",
|
||||
"repoPath": str(project),
|
||||
"knowledgeFile": "docs/ack/other.yaml",
|
||||
},
|
||||
"tasks": [task],
|
||||
}
|
||||
|
||||
errors = validate_knowledge.validate_task_references(
|
||||
data,
|
||||
tasks_data,
|
||||
knowledge_path=knowledge_path,
|
||||
tasks_path=tasks_path,
|
||||
)
|
||||
self.assertTrue(any("与当前知识文件" in error for error in errors))
|
||||
|
||||
del tasks_data["project"]["knowledgeFile"]
|
||||
errors = validate_knowledge.validate_task_references(data, tasks_data)
|
||||
self.assertTrue(any("project.knowledgeFile 必填" in e for e in errors))
|
||||
|
||||
tasks_data["project"]["knowledgeFile"] = "docs/ack/knowledge.yaml"
|
||||
staging_root = Path(temp_dir) / "staging"
|
||||
staged = staging_root / "docs" / "ack" / "knowledge.yaml"
|
||||
staged.parent.mkdir(parents=True)
|
||||
staged.write_text(
|
||||
yaml.safe_dump(data, allow_unicode=True), encoding="utf-8"
|
||||
)
|
||||
errors = validate_knowledge.validate_task_references(
|
||||
data,
|
||||
tasks_data,
|
||||
knowledge_path=staged,
|
||||
tasks_path=tasks_path,
|
||||
project_root=staging_root,
|
||||
project_root_is_explicit=True,
|
||||
)
|
||||
self.assertFalse(any("knowledgeFile" in error for error in errors))
|
||||
|
||||
def test_cli_fails_closed_for_missing_repo_root_and_wrong_binding(self) -> None:
|
||||
data = example_data()
|
||||
task = {
|
||||
"id": "BUG-002",
|
||||
"title": "source task",
|
||||
"status": "open",
|
||||
"dispatch": {
|
||||
"rounds": [
|
||||
{
|
||||
"round": 1,
|
||||
"attemptId": "BUG-002-A1",
|
||||
"result": "failed",
|
||||
},
|
||||
{
|
||||
"round": 2,
|
||||
"attemptId": "BUG-002-A2",
|
||||
"result": "passed",
|
||||
}
|
||||
]
|
||||
},
|
||||
}
|
||||
with tempfile.TemporaryDirectory() as temp_dir:
|
||||
base = Path(temp_dir)
|
||||
project = base / "project"
|
||||
ack_dir = project / "docs" / "ack"
|
||||
outside = base / "outside"
|
||||
ack_dir.mkdir(parents=True)
|
||||
outside.mkdir()
|
||||
(project / "checks").symlink_to(outside, target_is_directory=True)
|
||||
data["verificationRegistry"]["service-worktree-alignment"]["path"] = (
|
||||
"checks/verify.py"
|
||||
)
|
||||
knowledge_path = ack_dir / "knowledge.yaml"
|
||||
knowledge_path.write_text(
|
||||
yaml.safe_dump(data, allow_unicode=True), encoding="utf-8"
|
||||
)
|
||||
tasks_data = {
|
||||
"version": 1,
|
||||
"project": {
|
||||
"name": "notes-web",
|
||||
"repoPath": str(project / "missing"),
|
||||
"knowledgeFile": "docs/ack/not-the-current-file.yaml",
|
||||
},
|
||||
"tasks": [task],
|
||||
}
|
||||
tasks_path = ack_dir / "tasks.yaml"
|
||||
tasks_path.write_text(
|
||||
yaml.safe_dump(tasks_data, allow_unicode=True), encoding="utf-8"
|
||||
)
|
||||
|
||||
command = [
|
||||
sys.executable,
|
||||
str(SCRIPTS_DIR / "validate_knowledge.py"),
|
||||
str(knowledge_path),
|
||||
"--tasks",
|
||||
str(tasks_path),
|
||||
]
|
||||
inferred = subprocess.run(
|
||||
command,
|
||||
capture_output=True,
|
||||
text=True,
|
||||
check=False,
|
||||
)
|
||||
explicit = subprocess.run(
|
||||
[*command, "--project-root", str(project)],
|
||||
capture_output=True,
|
||||
text=True,
|
||||
check=False,
|
||||
)
|
||||
|
||||
self.assertEqual(inferred.returncode, 1)
|
||||
self.assertIn("project.repoPath", inferred.stderr)
|
||||
self.assertIn("与当前知识文件", inferred.stderr)
|
||||
self.assertIn("symlink", inferred.stderr)
|
||||
self.assertEqual(explicit.returncode, 1)
|
||||
self.assertIn("与当前知识文件", explicit.stderr)
|
||||
self.assertIn("symlink", explicit.stderr)
|
||||
|
||||
def test_cli_requires_root_for_nonempty_registry_outside_project_layout(self) -> None:
|
||||
with tempfile.TemporaryDirectory() as temp_dir:
|
||||
knowledge_path = Path(temp_dir) / "knowledge.yaml"
|
||||
knowledge_path.write_text(
|
||||
EXAMPLE_PATH.read_text(encoding="utf-8"), encoding="utf-8"
|
||||
)
|
||||
|
||||
result = subprocess.run(
|
||||
[
|
||||
sys.executable,
|
||||
str(SCRIPTS_DIR / "validate_knowledge.py"),
|
||||
str(knowledge_path),
|
||||
],
|
||||
capture_output=True,
|
||||
text=True,
|
||||
check=False,
|
||||
)
|
||||
|
||||
self.assertEqual(result.returncode, 1)
|
||||
self.assertIn("无法确定项目根目录", result.stderr)
|
||||
self.assertIn("--project-root", result.stderr)
|
||||
|
||||
def test_terminal_task_keeps_historical_ref_after_entry_becomes_stale(self) -> None:
|
||||
data = example_data()
|
||||
data["entries"][0]["status"] = "stale"
|
||||
data["entries"][0]["statusReason"] = "service architecture changed"
|
||||
task = {
|
||||
"id": "BUG-002",
|
||||
"status": "verified",
|
||||
"knowledgeRefs": ["K-001@1"],
|
||||
"knowledgeApplied": [],
|
||||
"knowledgeChecks": [
|
||||
{
|
||||
"ref": "K-001@1",
|
||||
"result": "passed",
|
||||
"evidence": "historical test evidence",
|
||||
}
|
||||
],
|
||||
"dispatch": {
|
||||
"rounds": [
|
||||
{
|
||||
"round": 1,
|
||||
"attemptId": "BUG-002-A1",
|
||||
"result": "failed",
|
||||
},
|
||||
{
|
||||
"round": 2,
|
||||
"attemptId": "BUG-002-A2",
|
||||
"result": "passed",
|
||||
}
|
||||
]
|
||||
},
|
||||
}
|
||||
tasks_data = {
|
||||
"project": {
|
||||
"name": "notes-web",
|
||||
"knowledgeFile": "docs/ack/knowledge.yaml",
|
||||
},
|
||||
"tasks": [task],
|
||||
}
|
||||
|
||||
terminal_errors = validate_knowledge.validate_task_references(
|
||||
data, tasks_data
|
||||
)
|
||||
self.assertFalse(any("必须 active" in error for error in terminal_errors))
|
||||
|
||||
task["status"] = "open"
|
||||
active_errors = validate_knowledge.validate_task_references(
|
||||
data, tasks_data
|
||||
)
|
||||
self.assertTrue(any("必须 active" in error for error in active_errors))
|
||||
|
||||
def test_cli_validates_tasks_and_selector_outputs_stable_refs(self) -> None:
|
||||
with tempfile.TemporaryDirectory() as temp_dir:
|
||||
project = Path(temp_dir) / "project"
|
||||
ack_dir = project / "docs" / "ack"
|
||||
ack_dir.mkdir(parents=True)
|
||||
knowledge_path = ack_dir / "knowledge.yaml"
|
||||
knowledge_path.write_text(
|
||||
EXAMPLE_PATH.read_text(encoding="utf-8"), encoding="utf-8"
|
||||
)
|
||||
target = project / "tests" / "ack" / "check_service_worktree.py"
|
||||
target.parent.mkdir(parents=True)
|
||||
target.write_text("#!/bin/sh\nexit 0\n", encoding="utf-8")
|
||||
target.chmod(target.stat().st_mode | 0o111)
|
||||
tasks = {
|
||||
"project": {
|
||||
"name": "notes-web",
|
||||
"repoPath": str(project),
|
||||
"knowledgeFile": "docs/ack/knowledge.yaml",
|
||||
},
|
||||
"tasks": [
|
||||
{
|
||||
"id": "BUG-002",
|
||||
"status": "verified",
|
||||
"knowledgeRefs": ["K-001@1"],
|
||||
"knowledgeApplied": [],
|
||||
"knowledgeChecks": [
|
||||
{
|
||||
"ref": "K-001@1",
|
||||
"result": "passed",
|
||||
"evidence": "independent retest",
|
||||
}
|
||||
],
|
||||
"dispatch": {
|
||||
"rounds": [
|
||||
{
|
||||
"round": 1,
|
||||
"attemptId": "BUG-002-A1",
|
||||
"result": "failed",
|
||||
},
|
||||
{
|
||||
"round": 2,
|
||||
"attemptId": "BUG-002-A2",
|
||||
"result": "passed",
|
||||
}
|
||||
]
|
||||
},
|
||||
}
|
||||
],
|
||||
}
|
||||
tasks_path = ack_dir / "tasks.yaml"
|
||||
tasks_path.write_text(
|
||||
yaml.safe_dump(tasks, allow_unicode=True), encoding="utf-8"
|
||||
)
|
||||
validated = subprocess.run(
|
||||
[
|
||||
sys.executable,
|
||||
str(SCRIPTS_DIR / "validate_knowledge.py"),
|
||||
str(knowledge_path),
|
||||
"--tasks",
|
||||
str(tasks_path),
|
||||
],
|
||||
capture_output=True,
|
||||
text=True,
|
||||
check=False,
|
||||
)
|
||||
self.assertEqual(validated.returncode, 0, validated.stderr)
|
||||
|
||||
selected = subprocess.run(
|
||||
[
|
||||
sys.executable,
|
||||
str(SCRIPTS_DIR / "select_knowledge.py"),
|
||||
str(knowledge_path),
|
||||
"--component",
|
||||
"web",
|
||||
"--path",
|
||||
"web/app.py",
|
||||
"--tag",
|
||||
"long-running-service",
|
||||
"--limit",
|
||||
"1",
|
||||
"--format",
|
||||
"refs",
|
||||
],
|
||||
capture_output=True,
|
||||
text=True,
|
||||
check=False,
|
||||
)
|
||||
self.assertEqual(selected.returncode, 0, selected.stderr)
|
||||
self.assertEqual(selected.stdout.strip(), "K-001@1")
|
||||
|
||||
selected_json = subprocess.run(
|
||||
[
|
||||
sys.executable,
|
||||
str(SCRIPTS_DIR / "select_knowledge.py"),
|
||||
str(knowledge_path),
|
||||
"--component",
|
||||
"web",
|
||||
"--path",
|
||||
"web/app.py",
|
||||
"--tag",
|
||||
"long-running-service",
|
||||
],
|
||||
capture_output=True,
|
||||
text=True,
|
||||
check=False,
|
||||
)
|
||||
self.assertEqual(selected_json.returncode, 0, selected_json.stderr)
|
||||
payload = json.loads(selected_json.stdout)
|
||||
self.assertEqual(
|
||||
payload["entries"][0]["verificationTarget"]["path"],
|
||||
"tests/ack/check_service_worktree.py",
|
||||
)
|
||||
|
||||
def test_paired_examples_validate_when_installed_in_project_layout(self) -> None:
|
||||
with tempfile.TemporaryDirectory() as temp_dir:
|
||||
project = Path(temp_dir) / "notes-web"
|
||||
ack_dir = project / "docs" / "ack"
|
||||
ack_dir.mkdir(parents=True)
|
||||
knowledge_path = ack_dir / "knowledge.yaml"
|
||||
tasks_path = ack_dir / "tasks.yaml"
|
||||
knowledge_path.write_text(
|
||||
EXAMPLE_PATH.read_text(encoding="utf-8"),
|
||||
encoding="utf-8",
|
||||
)
|
||||
tasks = yaml.safe_load(
|
||||
TASKS_EXAMPLE_PATH.read_text(encoding="utf-8")
|
||||
)
|
||||
tasks["project"]["repoPath"] = str(project)
|
||||
tasks["project"]["devWorktree"] = str(project)
|
||||
tasks_path.write_text(
|
||||
yaml.safe_dump(tasks, allow_unicode=True, sort_keys=False),
|
||||
encoding="utf-8",
|
||||
)
|
||||
target = project / "tests" / "ack" / "check_service_worktree.py"
|
||||
target.parent.mkdir(parents=True)
|
||||
target.write_text("#!/bin/sh\nexit 0\n", encoding="utf-8")
|
||||
target.chmod(target.stat().st_mode | 0o111)
|
||||
|
||||
tasks_result = subprocess.run(
|
||||
[
|
||||
sys.executable,
|
||||
str(SCRIPTS_DIR / "validate_tasks.py"),
|
||||
str(tasks_path),
|
||||
],
|
||||
capture_output=True,
|
||||
text=True,
|
||||
check=False,
|
||||
)
|
||||
knowledge_result = subprocess.run(
|
||||
[
|
||||
sys.executable,
|
||||
str(SCRIPTS_DIR / "validate_knowledge.py"),
|
||||
str(knowledge_path),
|
||||
"--tasks",
|
||||
str(tasks_path),
|
||||
"--project-root",
|
||||
str(project),
|
||||
],
|
||||
capture_output=True,
|
||||
text=True,
|
||||
check=False,
|
||||
)
|
||||
|
||||
self.assertEqual(tasks_result.returncode, 0, tasks_result.stderr)
|
||||
self.assertEqual(
|
||||
knowledge_result.returncode,
|
||||
0,
|
||||
knowledge_result.stderr,
|
||||
)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,89 @@
|
||||
from __future__ import annotations
|
||||
|
||||
import unittest
|
||||
from pathlib import Path
|
||||
|
||||
|
||||
REPO_ROOT = Path(__file__).resolve().parents[1]
|
||||
|
||||
|
||||
class AckSkillContentTests(unittest.TestCase):
|
||||
def test_ack_skill_owns_resources_without_modifying_agent_instructions(self) -> None:
|
||||
content = (REPO_ROOT / "skills" / "ack" / "SKILL.md").read_text(encoding="utf-8")
|
||||
|
||||
for expected in (
|
||||
"skiff init ack --project <project-root>",
|
||||
"docs/ack/project.md",
|
||||
"docs/ack/tasks.yaml",
|
||||
"docs/ack/knowledge.yaml",
|
||||
"docs/ack/delivery.yaml",
|
||||
"tasks: []",
|
||||
"validate_tasks.py",
|
||||
"validate_knowledge.py",
|
||||
"validate_delivery.py",
|
||||
"select_tasks.py",
|
||||
"select_knowledge.py",
|
||||
"references/kickoff.md",
|
||||
"不要修改项目的 `AGENTS.md`",
|
||||
"当前会话担任 Coordinator",
|
||||
):
|
||||
self.assertIn(expected, content)
|
||||
|
||||
def test_ack_skill_is_explicit_only(self) -> None:
|
||||
metadata = (REPO_ROOT / "skills" / "ack" / "agents" / "openai.yaml").read_text(
|
||||
encoding="utf-8"
|
||||
)
|
||||
|
||||
self.assertIn('display_name: "ACK"', metadata)
|
||||
self.assertIn("allow_implicit_invocation: false", metadata)
|
||||
|
||||
def test_model_routing_is_fingerprint_bound_and_does_not_trust_receipt_reuse(self) -> None:
|
||||
content = (
|
||||
REPO_ROOT / "skills" / "ack" / "references" / "model-routing.md"
|
||||
).read_text(encoding="utf-8")
|
||||
|
||||
self.assertIn("--expected-launch-fingerprint", content)
|
||||
self.assertIn("allowlist-v1", content)
|
||||
self.assertIn("禁止根据持久化 receipt 自动复用", content)
|
||||
self.assertIn("launcher 身份证明", content)
|
||||
|
||||
def test_ack_knowledge_resources_and_version_are_present(self) -> None:
|
||||
ack_dir = REPO_ROOT / "skills" / "ack"
|
||||
|
||||
for relative_path in (
|
||||
"templates/knowledge.template.yaml",
|
||||
"templates/knowledge.schema.json",
|
||||
"examples/knowledge.example.yaml",
|
||||
"scripts/validate_knowledge.py",
|
||||
"scripts/select_tasks.py",
|
||||
"scripts/select_knowledge.py",
|
||||
"scripts/run_verification.py",
|
||||
"scripts/worker_profiles.py",
|
||||
"scripts/launch_worker.py",
|
||||
"templates/delivery.template.yaml",
|
||||
"templates/delivery.schema.json",
|
||||
"examples/delivery.example.yaml",
|
||||
"references/delivery.md",
|
||||
):
|
||||
self.assertTrue((ack_dir / relative_path).is_file(), relative_path)
|
||||
version = (ack_dir / "VERSION").read_text(encoding="utf-8").strip()
|
||||
self.assertEqual(version, "0.14.0")
|
||||
self.assertIn(
|
||||
f'ackVersion: "{version}"',
|
||||
(ack_dir / "examples" / "tasks.example.yaml").read_text(encoding="utf-8"),
|
||||
)
|
||||
self.assertIn(
|
||||
f"ack v{version}",
|
||||
(ack_dir / "examples" / "project.example.md").read_text(encoding="utf-8"),
|
||||
)
|
||||
self.assertIn(
|
||||
'ackVersion: "<接入时的 ack skill 版本>"',
|
||||
(ack_dir / "templates" / "tasks.template.yaml").read_text(
|
||||
encoding="utf-8"
|
||||
),
|
||||
)
|
||||
self.assertTrue((ack_dir / "references" / "feishu-bug-intake.md").is_file())
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
@@ -0,0 +1,142 @@
|
||||
from __future__ import annotations
|
||||
|
||||
import importlib.util
|
||||
import json
|
||||
import subprocess
|
||||
import sys
|
||||
import tempfile
|
||||
import unittest
|
||||
from pathlib import Path
|
||||
|
||||
|
||||
REPO_ROOT = Path(__file__).resolve().parents[1]
|
||||
SELECTOR = REPO_ROOT / "skills" / "ack" / "scripts" / "select_tasks.py"
|
||||
EXAMPLE = REPO_ROOT / "skills" / "ack" / "examples" / "tasks.example.yaml"
|
||||
SPEC = importlib.util.spec_from_file_location("ack_select_tasks", SELECTOR)
|
||||
assert SPEC and SPEC.loader
|
||||
SELECT_TASKS = importlib.util.module_from_spec(SPEC)
|
||||
sys.path.insert(0, str(SELECTOR.parent))
|
||||
SPEC.loader.exec_module(SELECT_TASKS)
|
||||
|
||||
|
||||
def board() -> dict:
|
||||
return {
|
||||
"version": 1,
|
||||
"updatedAt": "2026-08-01T20:00:00+08:00",
|
||||
"source": "Coordinator",
|
||||
"project": {"name": "demo"},
|
||||
"summary": {"open": ["T-OPEN"], "verified": ["T-DONE"]},
|
||||
"tasks": [
|
||||
{"id": "T-OPEN", "title": "open", "status": "open"},
|
||||
{"id": "T-DEV", "title": "dev", "status": "fixed_by_dev"},
|
||||
{"id": "T-BLOCKED", "title": "blocked", "status": "blocked"},
|
||||
{"id": "T-DONE", "title": "done", "status": "verified"},
|
||||
],
|
||||
}
|
||||
|
||||
|
||||
class AckTaskSelectorTests(unittest.TestCase):
|
||||
def run_selector(
|
||||
self,
|
||||
value: dict,
|
||||
*args: str,
|
||||
no_site_packages: bool = False,
|
||||
) -> subprocess.CompletedProcess[str]:
|
||||
with tempfile.TemporaryDirectory() as temp_dir:
|
||||
path = Path(temp_dir) / "tasks.json"
|
||||
path.write_text(json.dumps(value), encoding="utf-8")
|
||||
command = [sys.executable]
|
||||
if no_site_packages:
|
||||
command.append("-S")
|
||||
command.extend((str(SELECTOR), str(path), *args))
|
||||
return subprocess.run(
|
||||
command,
|
||||
cwd=REPO_ROOT,
|
||||
text=True,
|
||||
capture_output=True,
|
||||
check=False,
|
||||
)
|
||||
|
||||
def test_default_selects_only_actionable_tasks_in_all_modes(self) -> None:
|
||||
for no_site_packages in (False, True):
|
||||
with self.subTest(no_site_packages=no_site_packages):
|
||||
result = self.run_selector(board(), no_site_packages=no_site_packages)
|
||||
self.assertEqual(result.returncode, 0, result.stderr)
|
||||
payload = json.loads(result.stdout)
|
||||
self.assertEqual(
|
||||
payload["selection"]["selectedTaskIds"],
|
||||
["T-OPEN", "T-DEV"],
|
||||
)
|
||||
self.assertEqual(payload["selection"]["totalTasks"], 4)
|
||||
self.assertEqual(payload["project"]["name"], "demo")
|
||||
self.assertEqual(payload["summary"]["open"], ["T-OPEN"])
|
||||
|
||||
def test_example_yaml_runs_without_site_packages(self) -> None:
|
||||
result = subprocess.run(
|
||||
[sys.executable, "-S", str(SELECTOR), str(EXAMPLE), "--compact"],
|
||||
cwd=REPO_ROOT,
|
||||
text=True,
|
||||
capture_output=True,
|
||||
check=False,
|
||||
)
|
||||
self.assertEqual(result.returncode, 0, result.stderr)
|
||||
payload = json.loads(result.stdout)
|
||||
self.assertEqual(payload["project"]["name"], "notes-web")
|
||||
self.assertEqual(payload["selection"]["mode"], "statuses")
|
||||
|
||||
def test_explicit_task_id_selects_terminal_task(self) -> None:
|
||||
result = self.run_selector(board(), "--task-id", "T-DONE")
|
||||
self.assertEqual(result.returncode, 0, result.stderr)
|
||||
payload = json.loads(result.stdout)
|
||||
self.assertEqual(payload["selection"]["mode"], "task_ids")
|
||||
self.assertEqual(payload["selection"]["selectedTaskIds"], ["T-DONE"])
|
||||
self.assertEqual([task["id"] for task in payload["tasks"]], ["T-DONE"])
|
||||
|
||||
def test_missing_task_and_over_budget_fail_closed(self) -> None:
|
||||
missing = self.run_selector(board(), "--task-id", "T-MISSING")
|
||||
self.assertEqual(missing.returncode, 1)
|
||||
self.assertIn("找不到任务", missing.stderr)
|
||||
|
||||
over_budget = self.run_selector(board(), "--limit", "1")
|
||||
self.assertEqual(over_budget.returncode, 1)
|
||||
self.assertIn("超过 --limit=1", over_budget.stderr)
|
||||
|
||||
def test_invalid_board_is_rejected_before_selection(self) -> None:
|
||||
invalid = board()
|
||||
invalid["tasks"].append(
|
||||
{"id": "T-OPEN", "title": "duplicate", "status": "open"}
|
||||
)
|
||||
result = self.run_selector(invalid)
|
||||
self.assertEqual(result.returncode, 1)
|
||||
self.assertIn("任务板无效", result.stderr)
|
||||
self.assertIn("id 重复", result.stderr)
|
||||
|
||||
def test_receipts_and_delivery_runs_are_reduced_to_selected_tasks(self) -> None:
|
||||
selected = [
|
||||
{
|
||||
"id": "T-1",
|
||||
"dispatch": {
|
||||
"developer": {"receiptId": "WR-1"},
|
||||
"test": {"receiptId": None},
|
||||
},
|
||||
}
|
||||
]
|
||||
data = {
|
||||
"workerReceipts": [{"id": "WR-1"}, {"id": "WR-2"}],
|
||||
"deliveryRuns": [
|
||||
{"id": "DR-1", "taskIds": ["T-1"]},
|
||||
{"id": "DR-2", "taskIds": ["T-2"]},
|
||||
],
|
||||
}
|
||||
self.assertEqual(
|
||||
SELECT_TASKS.select_referenced_receipts(data, selected),
|
||||
[{"id": "WR-1"}],
|
||||
)
|
||||
self.assertEqual(
|
||||
SELECT_TASKS.select_delivery_runs(data, selected),
|
||||
[{"id": "DR-1", "taskIds": ["T-1"]}],
|
||||
)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user