refactor(agent-collaboration-kit): split stable core from project overrides
- Reorganize flat files into core/ templates/ examples/ scripts/ with VERSION - Deduplicate: single-source state machine, three-round policy, acceptance signals - Abstract orchestration in closed-loop.md with manual mode; move Orca commands to orca-adapter.md - Add tasks.schema.json + validate_tasks.py (jsonschema or builtin rules, no hard deps) - Add filled examples, concurrency write rule, kitVersion tracking; unify to Chinese Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
@@ -0,0 +1,64 @@
|
||||
# <项目名> Agent 协作协议
|
||||
|
||||
> 本项目基于 agent-collaboration-kit v<kit_version>（见 kit 根 `VERSION`）。
|
||||
> 稳定规范引用 `docs/agent-collaboration-kit/core/`，不复制其内容；本文件只填项目自己的差异。
|
||||
|
||||
## 项目概览
|
||||
|
||||
- 项目：`<project_name>`
|
||||
- 技术栈：`<tech_stack>`
|
||||
- 运行命令：`<run_command>`
|
||||
- Base URL：`<base_url>`
|
||||
- 任务板：`tasks.yaml`
|
||||
|
||||
## 稳定规范（不在此重复，直接引用）
|
||||
|
||||
- 角色模型 / 权限 / 状态机 / 完成定义：`docs/agent-collaboration-kit/core/roles-and-permissions.md`
|
||||
- 闭环流程（含手动模式、worktree 对齐）：`docs/agent-collaboration-kit/core/closed-loop.md`
|
||||
- 优化方法（验收信号、三轮策略）：`docs/agent-collaboration-kit/core/optimization-method.md`
|
||||
- 派发 prompt 模板：`docs/agent-collaboration-kit/core/prompt-templates.md`
|
||||
- Orca 编排命令（可选）：`docs/agent-collaboration-kit/core/orca-adapter.md`
|
||||
|
||||
## 路径权限（项目覆盖层，必须填实际路径）
|
||||
|
||||
| 路径 | Product/Test | Developer | 说明 |
|
||||
|------|:------------:|:---------:|------|
|
||||
| `<spec_paths>` | R/W | Read-only | 产品规格、API 文档、计划 |
|
||||
| `<integration_test_paths>` | R/W | Read-only | 浏览器/API 回归 |
|
||||
| `<test_records_path>` | R/W | Read-only | 复测记录 |
|
||||
| `<source_paths>` | Read-only | R/W | 应用源码 |
|
||||
| `<unit_test_paths>` | Read-only | R/W | 单元测试 |
|
||||
| `<shared_config_templates>` | Read-only | R/W | 可提交配置模板 |
|
||||
| `<local_config_paths>` | Read-only | Read-only | 本地私有配置 |
|
||||
| `tasks.yaml` | R/W | Read-only | 只有 Coordinator 写 |
|
||||
|
||||
## 命令（项目覆盖层）
|
||||
|
||||
Developer 白盒验证：
|
||||
|
||||
```bash
|
||||
<unit_test_command>
|
||||
<build_command>
|
||||
<local_run_command>
|
||||
```
|
||||
|
||||
Product/Test 黑盒验证：
|
||||
|
||||
```bash
|
||||
<preflight_command>
|
||||
<api_smoke_command>
|
||||
<browser_regression_command>
|
||||
```
|
||||
|
||||
任务板校验：
|
||||
|
||||
```bash
|
||||
python3 docs/agent-collaboration-kit/scripts/validate_tasks.py tasks.yaml
|
||||
```
|
||||
|
||||
## 硬规则（其余见 core/）
|
||||
|
||||
- `worker_done` 不等于完成。Product/Test 必须独立复测后才能 `verified`。
|
||||
- 只有 Coordinator 写 `tasks.yaml`；Developer 通过 worker_done 回报。
|
||||
- 每个任务最多派发 3 轮，仍不过标记 `leftover` 并继续下一个。
|
||||
- 不提交或推送，除非用户明确要求。
|
||||
@@ -0,0 +1,127 @@
|
||||
{
|
||||
"$schema": "http://json-schema.org/draft-07/schema#",
|
||||
"$id": "https://git.yumee.top/laily/skills/kits/agent-collaboration-kit/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": "接入时所基于的 agent-collaboration-kit 版本，便于日后 diff 升级"
|
||||
},
|
||||
"project": {
|
||||
"type": "object",
|
||||
"required": ["name"],
|
||||
"additionalProperties": true,
|
||||
"properties": {
|
||||
"name": { "type": "string" },
|
||||
"repoPath": { "type": "string" },
|
||||
"baseUrl": { "type": "string" },
|
||||
"devWorktree": { "type": "string" }
|
||||
}
|
||||
},
|
||||
"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"] },
|
||||
"verifiedAt": { "type": ["string", "null"] },
|
||||
"leftoverReason": { "type": ["string", "null"] },
|
||||
"evidence": { "type": "object" }
|
||||
}
|
||||
}
|
||||
},
|
||||
"allOf": [
|
||||
{
|
||||
"if": { "properties": { "status": { "const": "leftover" } } },
|
||||
"then": {
|
||||
"properties": {
|
||||
"resolution": {
|
||||
"required": ["leftoverReason"]
|
||||
}
|
||||
},
|
||||
"required": ["resolution"]
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,67 @@
|
||||
# 复制到项目根目录为 tasks.yaml，替换占位符。结构见 templates/tasks.schema.json。
|
||||
version: 1
|
||||
updatedAt: "<YYYY-MM-DDTHH:mm:ss+TZ>"
|
||||
source: "Product/Test Agent"
|
||||
kitVersion: "<接入时的 agent-collaboration-kit 版本，见 kit 根 VERSION>"
|
||||
project:
|
||||
name: "<project_name>"
|
||||
repoPath: "<repo_path>"
|
||||
baseUrl: "<base_url>"
|
||||
devWorktree: "<dev_worktree>"
|
||||
|
||||
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 Product/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
|
||||
verifiedAt: null
|
||||
leftoverReason: null
|
||||
Reference in New Issue
Block a user