laily/.pouch
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(ack): add project knowledge guardrails

Browse Source
This commit is contained in:
laily
2026-07-31 21:09:36 +08:00
parent 7d1994cf93
commit ee66dbe9ce
32 changed files with 8353 additions and 139 deletions
Download Patch File Download Diff File Expand all files Collapse all files
skills/ack/templates/knowledge.schema.json
+367
View File
@@ -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"
}
}
}
}
}
skills/ack/templates/knowledge.template.yaml
+9
View File
@@ -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: []
skills/ack/templates/project.template.md
+23 -4
View File
@@ -5,9 +5,11 @@
>
> **本文件是「项目覆盖层」，文件名可配置。** 默认放 `docs/ack/project.md`，
> 不占用 `AGENTS.md`，避免与团队已有的 `AGENTS.md` 约定冲突。
> 若希望 Agent 自动加载，可在项目 `AGENTS.md` 里加一行指向本文件，或直接把本文件命名为 `AGENTS.md`。
> 若希望 Agent 自动加载，可由项目维护者自行在 `AGENTS.md` 中引用本文件；ACK
> 不会自动修改 `AGENTS.md`、`CLAUDE.md` 或其它 Agent 指令文件。
> 无论叫什么，都在 `tasks.yaml` 的 `project.overlayFile` 记录实际路径。
> `docs/ack/` 只保存本项目的 `project.md` 与 `tasks.yaml`，不复制或链接 Skill。
> `docs/ack/` 只保存本项目的 `project.md`、`tasks.yaml` 与 `knowledge.yaml`，
> 不复制或链接 Skill。
## 项目概览
@@ -16,6 +18,7 @@
- 运行命令：`<run_command>`
- Base URL：`<base_url>`
- 任务板：`docs/ack/tasks.yaml`
- 项目知识：`docs/ack/knowledge.yaml`
- 覆盖层文件：`<overlay_file_path>`（默认 `docs/ack/project.md`）
## 通用规范（由 ACK Skill 按需读取）
@@ -48,6 +51,7 @@
| `<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 通过回报提名或验证 |
## 命令（项目覆盖层）
@@ -67,13 +71,28 @@ Test 黑盒复测：
<browser_regression_command>
```
任务板校验由 `/ack` 使用 Skill 自带的 `scripts/validate_tasks.py` 执行。
知识项的 `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` 执行。
## 硬规则（其余见 references/）
- 三角色独立：Coordinator 只编排、Test 只验证、Developer 只实现（验证者 ≠ 实现者）。
- 模型分层：Coordinator 用强模型且不亲自跑测试，Test/Developer 用中低模型，必要时升级（见 references/model-routing.md）。
- `worker_done` 与复测报告都不等于完成。必须 Test 独立复测 + Coordinator 终检后才能 `verified`。
- 只有 Coordinator 写 `tasks.yaml`；Developer 与 Test 都只读，通过消息回报。
- 只有 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 指令文件。
- 每个任务最多派发 3 轮，仍不过标记 `leftover` 并继续下一个。
- 不提交或推送，除非用户明确要求。
skills/ack/templates/tasks.schema.json
+147 -4
View File
@@ -23,13 +23,18 @@
"required": ["name"],
"additionalProperties": true,
"properties": {
"name": { "type": "string" },
"name": { "type": "string", "minLength": 1, "pattern": "\\S" },
"repoPath": { "type": "string" },
"baseUrl": { "type": "string" },
"devWorktree": { "type": "string" },
"overlayFile": {
"type": "string",
"description": "项目覆盖层文件路径，默认 docs/ack/project.md，可自定义"
},
"knowledgeFile": {
"type": "string",
"const": "docs/ack/knowledge.yaml",
"description": "项目知识护栏库的唯一权威路径"
}
}
},
@@ -68,25 +73,155 @@
"required": ["round", "result"],
"additionalProperties": true,
"properties": {
"round": { "type": "integer", "minimum": 1 },
"round": { "type": "integer", "minimum": 1, "maximum": 3 },
"attemptId": {
"type": "string",
"pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*-A[1-9][0-9]*$",
"description": "稳定逻辑轮次 ID，应为 <task-id>-A<round>；旧轮次可缺省，但作为知识来源前必须补齐"
},
"result": { "type": "string", "enum": ["passed", "failed"] },
"evidence": { "type": "string" }
}
},
"knowledgeRef": {
"type": "string",
"pattern": "^K-[A-Z0-9][A-Z0-9-]*@[1-9][0-9]*$"
},
"knowledgeCandidate": {
"type": "object",
"required": [
"kind",
"title",
"claim",
"scope",
"appliesWhen",
"directive",
"rationale",
"evidenceRefs"
],
"additionalProperties": false,
"properties": {
"kind": {
"type": "string",
"enum": ["guardrail", "pitfall", "verification"]
},
"title": { "type": "string", "minLength": 1 },
"claim": { "type": "string", "minLength": 1 },
"scope": {
"type": "object",
"minProperties": 1,
"additionalProperties": false,
"properties": {
"all": { "type": "boolean" },
"components": {
"type": "array",
"items": { "type": "string", "minLength": 1 },
"uniqueItems": true
},
"paths": {
"type": "array",
"items": { "type": "string", "minLength": 1 },
"uniqueItems": true
},
"dependencies": {
"type": "array",
"items": { "type": "string", "minLength": 1 },
"uniqueItems": true
},
"versions": {
"type": "array",
"items": { "type": "string", "minLength": 1 },
"uniqueItems": true
},
"tags": {
"type": "array",
"items": { "type": "string", "minLength": 1 },
"uniqueItems": true
},
"symbols": {
"type": "array",
"items": { "type": "string", "minLength": 1 },
"uniqueItems": true
},
"errorSignatures": {
"type": "array",
"items": { "type": "string", "minLength": 1 },
"uniqueItems": true
}
}
},
"appliesWhen": { "type": "string", "minLength": 1 },
"directive": { "type": "string", "minLength": 1 },
"rationale": { "type": "string", "minLength": 1 },
"evidenceRefs": {
"type": "array",
"minItems": 1,
"items": { "type": "string", "minLength": 1 },
"uniqueItems": true
},
"proposedBy": { "type": "string" },
"proposedAt": { "type": "string" }
}
},
"knowledgeApplication": {
"type": "object",
"required": ["ref", "result", "evidence"],
"additionalProperties": false,
"properties": {
"ref": { "$ref": "#/definitions/knowledgeRef" },
"result": {
"type": "string",
"enum": ["applied", "not_applicable"]
},
"evidence": { "type": "string", "minLength": 1 }
}
},
"knowledgeCheck": {
"type": "object",
"required": ["ref", "result", "evidence"],
"additionalProperties": false,
"properties": {
"ref": { "$ref": "#/definitions/knowledgeRef" },
"result": {
"type": "string",
"enum": ["passed", "failed", "not_applicable"]
},
"evidence": { "type": "string", "minLength": 1 },
"checkedBy": { "type": "string" },
"checkedAt": { "type": "string" }
}
},
"task": {
"type": "object",
"required": ["id", "title", "status"],
"additionalProperties": true,
"properties": {
"id": { "type": "string", "minLength": 1 },
"id": { "type": "string", "minLength": 1, "pattern": "\\S" },
"type": { "type": "string" },
"title": { "type": "string", "minLength": 1 },
"title": { "type": "string", "minLength": 1, "pattern": "\\S" },
"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" } },
"knowledgeRefs": {
"type": "array",
"items": { "$ref": "#/definitions/knowledgeRef" },
"uniqueItems": true
},
"knowledgeApplied": {
"type": "array",
"items": { "$ref": "#/definitions/knowledgeApplication" }
},
"knowledgeCandidates": {
"type": "array",
"items": { "$ref": "#/definitions/knowledgeCandidate" }
},
"knowledgeChecks": {
"type": "array",
"items": { "$ref": "#/definitions/knowledgeCheck" }
},
"description": { "type": "string" },
"stepsToReproduce": { "type": "array", "items": { "type": "string" } },
"expected": { "type": "string" },
@@ -124,6 +259,14 @@
"then": {
"properties": {
"resolution": {
"type": "object",
"properties": {
"leftoverReason": {
"type": "string",
"minLength": 1,
"pattern": "\\S"
}
},
"required": ["leftoverReason"]
}
},
skills/ack/templates/tasks.template.yaml
+5
View File
@@ -9,6 +9,7 @@ project:
baseUrl: "<base_url>"
devWorktree: "<dev_worktree>"
overlayFile: "docs/ack/project.md"
knowledgeFile: "docs/ack/knowledge.yaml"
summary:
verified: []
@@ -28,6 +29,10 @@ tasks:
- "<docs/spec.md#section>"
testRefs:
- "<tests/browser/cases/01-case.md>"
knowledgeRefs: []
knowledgeApplied: []
knowledgeCandidates: []
knowledgeChecks: []
description: >
<What is wrong, in user-visible terms.>