agent-notes-kit 0.0.0-stage → 1.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +190 -2
- package/install.mjs +254 -0
- package/package.json +23 -4
- package/scripts/agent-note-tree.mjs +77 -0
- package/scripts/archived-agent-notes.mjs +143 -0
- package/scripts/verify-agent-note-classification.mjs +17 -0
- package/scripts/verify-agent-note-format.mjs +79 -0
- package/scripts/verify-archived-agent-notes.mjs +126 -0
- package/template/.agents/agents/README.md +40 -0
- package/template/.agents/agents/_main.md +46 -0
- package/template/.agents/agents/_template.md +18 -0
- package/template/.agents/agents/architect.md +18 -0
- package/template/.agents/agents/archivist.md +18 -0
- package/template/.agents/agents/doc-writer.md +18 -0
- package/template/.agents/agents/implementer.md +18 -0
- package/template/.agents/agents/reviewer.md +18 -0
- package/template/.agents/agents/test-engineer.md +18 -0
- package/template/.agents/agents/ui-reviewer.md +18 -0
- package/template/.agents/notes/AGENTS.md +7 -0
- package/template/.agents/notes/README.md +123 -0
- package/template/.agents/notes/archived/AGENTS.md +7 -0
- package/template/.agents/notes/archived/architecture/.gitkeep +0 -0
- package/template/.agents/notes/archived/bug-fix/.gitkeep +0 -0
- package/template/.agents/notes/archived/feature/.gitkeep +0 -0
- package/template/.agents/notes/archived/manifest.json +4 -0
- package/template/.agents/notes/archived/process/.gitkeep +0 -0
- package/template/.agents/notes/archived/simplification/.gitkeep +0 -0
- package/template/.agents/notes/archived/testing/.gitkeep +0 -0
- package/template/.agents/notes/implemented/AGENTS.md +13 -0
- package/template/.agents/notes/implemented/architecture/.gitkeep +0 -0
- package/template/.agents/notes/implemented/bug-fix/.gitkeep +0 -0
- package/template/.agents/notes/implemented/feature/.gitkeep +0 -0
- package/template/.agents/notes/implemented/process/.gitkeep +0 -0
- package/template/.agents/notes/implemented/simplification/.gitkeep +0 -0
- package/template/.agents/notes/implemented/testing/.gitkeep +0 -0
- package/template/.agents/notes/proposed/architecture/.gitkeep +0 -0
- package/template/.agents/notes/proposed/bug-fix/.gitkeep +0 -0
- package/template/.agents/notes/proposed/feature/.gitkeep +0 -0
- package/template/.agents/notes/proposed/process/.gitkeep +0 -0
- package/template/.agents/notes/proposed/simplification/.gitkeep +0 -0
- package/template/.agents/notes/proposed/testing/.gitkeep +0 -0
- package/template/.agents/notes/rejected/architecture/.gitkeep +0 -0
- package/template/.agents/notes/rejected/bug-fix/.gitkeep +0 -0
- package/template/.agents/notes/rejected/feature/.gitkeep +0 -0
- package/template/.agents/notes/rejected/process/.gitkeep +0 -0
- package/template/.agents/notes/rejected/simplification/.gitkeep +0 -0
- package/template/.agents/notes/rejected/testing/.gitkeep +0 -0
- package/template/.agents/skills/agent-experience/SKILL.md +25 -0
- package/template/.agents/skills/archive-agent-notes/SKILL.md +68 -0
- package/template/.agents/skills/code-review/SKILL.md +40 -0
- package/template/.agents/skills/doc-writing/SKILL.md +48 -0
- package/template/.agents/skills/error-handling/SKILL.md +35 -0
- package/template/.agents/skills/find-simplifications/SKILL.md +43 -0
- package/template/.agents/skills/init-architecture/SKILL.md +41 -0
- package/template/.agents/skills/pr-description/SKILL.md +51 -0
- package/template/.agents/skills/pre-push-checks/SKILL.md +42 -0
- package/template/.agents/skills/prose-standard/SKILL.md +49 -0
- package/template/.agents/skills/ui-ux/SKILL.md +107 -0
- package/template/.agents/skills/ui-ux/references/alignment.md +24 -0
- package/template/.agents/skills/ui-ux/references/icons.md +54 -0
- package/template/.agents/skills/ui-ux/references/responsive.md +52 -0
- package/template/.agents/skills/ui-ux/references/spacing.md +17 -0
- package/template/docs/AGENTS.md +36 -0
- package/template/docs/architecture.md +33 -0
- package/template/docs/contracts.md +22 -0
- package/template/docs/design/README.md +7 -0
- package/template/docs/design.md +30 -0
- package/template/docs/glossary.md +11 -0
|
@@ -0,0 +1,143 @@
|
|
|
1
|
+
/** 纯归档格式与不可变清单辅助函数。 */
|
|
2
|
+
|
|
3
|
+
import { createHash } from 'node:crypto'
|
|
4
|
+
import { basename } from 'node:path'
|
|
5
|
+
import { AGENT_NOTE_CLASSES } from './agent-note-tree.mjs'
|
|
6
|
+
|
|
7
|
+
/**
|
|
8
|
+
* 冻结内容清单中的版本化字段。
|
|
9
|
+
* @typedef {{ version: 1, files: Readonly<Record<string, string>> }} ArchiveManifest
|
|
10
|
+
*/
|
|
11
|
+
|
|
12
|
+
/** 去掉开头 UTF-8 BOM,并把 CRLF / 孤立 CR 规范化为 LF,使内容与哈希跨平台稳定。 */
|
|
13
|
+
function normalizeContent(text) {
|
|
14
|
+
return text.replace(/^/, '').replace(/\r\n?/g, '\n')
|
|
15
|
+
}
|
|
16
|
+
|
|
17
|
+
/** 独立于仓库 Git 对象格式,对单个归档产物做哈希(BOM 与行尾已规范化)。 */
|
|
18
|
+
function archiveContentHash(content) {
|
|
19
|
+
return `sha256:${createHash('sha256').update(normalizeContent(content.toString('utf8'))).digest('hex')}`
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
function isRecord(value) {
|
|
23
|
+
return typeof value === 'object' && value !== null && !Array.isArray(value)
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
/**
|
|
27
|
+
* 解析归档清单,拒绝超出其封闭 schema 的字段或哈希。
|
|
28
|
+
* @param {string} content
|
|
29
|
+
* @returns {ArchiveManifest}
|
|
30
|
+
*/
|
|
31
|
+
export function parseArchiveManifest(content) {
|
|
32
|
+
const value = JSON.parse(content)
|
|
33
|
+
if (!isRecord(value)) throw new Error('应为 JSON 对象')
|
|
34
|
+
const fields = Object.keys(value).sort()
|
|
35
|
+
if (fields.join(',') !== 'files,version') throw new Error('只能包含 `version` 和 `files` 两个字段')
|
|
36
|
+
if (value.version !== 1) throw new Error('不支持的清单版本(应为 1)')
|
|
37
|
+
if (!isRecord(value.files)) throw new Error('`files` 必须是对象')
|
|
38
|
+
const files = {}
|
|
39
|
+
for (const [path, hash] of Object.entries(value.files)) {
|
|
40
|
+
if (typeof hash !== 'string' || !/^sha256:[0-9a-f]{64}$/.test(hash)) {
|
|
41
|
+
throw new Error(`${path} 的内容哈希无效`)
|
|
42
|
+
}
|
|
43
|
+
files[path] = hash
|
|
44
|
+
}
|
|
45
|
+
return { version: 1, files }
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
/**
|
|
49
|
+
* 以确定性路径顺序渲染归档清单。
|
|
50
|
+
* @param {Readonly<Record<string, string>>} files
|
|
51
|
+
* @returns {string}
|
|
52
|
+
*/
|
|
53
|
+
export function renderArchiveManifest(files) {
|
|
54
|
+
return `${JSON.stringify({
|
|
55
|
+
version: 1,
|
|
56
|
+
files: Object.fromEntries(Object.entries(files).sort(([left], [right]) => left.localeCompare(right))),
|
|
57
|
+
}, null, 2)}\n`
|
|
58
|
+
}
|
|
59
|
+
|
|
60
|
+
/**
|
|
61
|
+
* 拒绝任何对已封存清单条目的改动。
|
|
62
|
+
* @param {ArchiveManifest} baseline
|
|
63
|
+
* @param {ArchiveManifest} current
|
|
64
|
+
* @returns {string[]}
|
|
65
|
+
*/
|
|
66
|
+
export function validateArchiveManifestExtension(baseline, current) {
|
|
67
|
+
const errors = []
|
|
68
|
+
for (const [path, expected] of Object.entries(baseline.files)) {
|
|
69
|
+
const actual = current.files[path]
|
|
70
|
+
if (actual === undefined) errors.push(`${path}:已封存的清单条目缺失`)
|
|
71
|
+
else if (actual !== expected) errors.push(`${path}:已封存的内容哈希发生变化`)
|
|
72
|
+
}
|
|
73
|
+
return errors
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
function validDate(value) {
|
|
77
|
+
const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(value)
|
|
78
|
+
if (match === null) return false
|
|
79
|
+
const year = Number(match[1])
|
|
80
|
+
const month = Number(match[2])
|
|
81
|
+
const day = Number(match[3])
|
|
82
|
+
const date = new Date(Date.UTC(year, month - 1, day))
|
|
83
|
+
return date.getUTCFullYear() === year && date.getUTCMonth() === month - 1 && date.getUTCDate() === day
|
|
84
|
+
}
|
|
85
|
+
|
|
86
|
+
function validateMetadata(path, content, sourceBase) {
|
|
87
|
+
const errors = []
|
|
88
|
+
const lines = normalizeContent(content.toString('utf8')).split('\n')
|
|
89
|
+
const status = lines.findIndex(line => /^状态[::]/.test(line))
|
|
90
|
+
if (!/^状态[::]\s*已实施$/.test(lines[status] ?? '')) errors.push(`${path}:必须是 \`状态:已实施\``)
|
|
91
|
+
const archived = /^归档[::]\s*(\d{4}-\d{2}-\d{2})$/.exec(lines[status + 1] ?? '')?.[1]
|
|
92
|
+
if (status < 0 || archived === undefined || !validDate(archived)) {
|
|
93
|
+
errors.push(`${path}:状态行之后必须紧跟 \`归档:YYYY-MM-DD\` 且日期有效`)
|
|
94
|
+
} else if (archived < sourceBase.slice(0, 10)) {
|
|
95
|
+
errors.push(`${path}:归档日期 ${archived} 早于记录文件名中的日期`)
|
|
96
|
+
}
|
|
97
|
+
return errors
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
/**
|
|
101
|
+
* 校验封闭的分类树、已实施/归档元数据与带日期文件名。
|
|
102
|
+
* @param {ReadonlyMap<string, Buffer>} artifacts
|
|
103
|
+
* @returns {string[]}
|
|
104
|
+
*/
|
|
105
|
+
export function validateArchiveArtifacts(artifacts) {
|
|
106
|
+
const errors = []
|
|
107
|
+
for (const [path, content] of [...artifacts].sort(([left], [right]) => left.localeCompare(right))) {
|
|
108
|
+
const match = /^([^/]+)\/(\d{4}-\d{2}-\d{2}-.+)\.md$/.exec(path)
|
|
109
|
+
if (match?.[1] === undefined || match[2] === undefined) {
|
|
110
|
+
errors.push(`${path}:应为 {分类}/yyyy-mm-dd-主题.md`)
|
|
111
|
+
continue
|
|
112
|
+
}
|
|
113
|
+
if (!AGENT_NOTE_CLASSES.includes(match[1])) {
|
|
114
|
+
errors.push(`${path}:未知决策记录分类 ${JSON.stringify(match[1])}`)
|
|
115
|
+
continue
|
|
116
|
+
}
|
|
117
|
+
errors.push(...validateMetadata(path, content, basename(match[2])))
|
|
118
|
+
}
|
|
119
|
+
return errors
|
|
120
|
+
}
|
|
121
|
+
|
|
122
|
+
/**
|
|
123
|
+
* 保留所有已封存的路径/哈希,并为新归档产物追加哈希。
|
|
124
|
+
* @param {ArchiveManifest} existing
|
|
125
|
+
* @param {ReadonlyMap<string, Buffer>} artifacts
|
|
126
|
+
* @returns {{ files: Record<string, string>, added: string[], errors: string[] }}
|
|
127
|
+
*/
|
|
128
|
+
export function extendArchiveManifest(existing, artifacts) {
|
|
129
|
+
const errors = []
|
|
130
|
+
const files = { ...existing.files }
|
|
131
|
+
for (const [path, expected] of Object.entries(existing.files)) {
|
|
132
|
+
const content = artifacts.get(path)
|
|
133
|
+
if (content === undefined) errors.push(`${path}:已封存产物缺失`)
|
|
134
|
+
else if (archiveContentHash(content) !== expected) errors.push(`${path}:已封存内容哈希发生变化`)
|
|
135
|
+
}
|
|
136
|
+
const added = []
|
|
137
|
+
for (const [path, content] of [...artifacts].sort(([left], [right]) => left.localeCompare(right))) {
|
|
138
|
+
if (files[path] !== undefined) continue
|
|
139
|
+
files[path] = archiveContentHash(content)
|
|
140
|
+
added.push(path)
|
|
141
|
+
}
|
|
142
|
+
return { files, added, errors }
|
|
143
|
+
}
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* 强制决策记录的生命周期/分类路径与带日期文件名。结构规则与
|
|
3
|
+
* `agent-note-tree.mjs` 共享;封闭分类规则见 `.agents/notes/README.md`。
|
|
4
|
+
*/
|
|
5
|
+
|
|
6
|
+
import { walkAgentNoteTree } from './agent-note-tree.mjs'
|
|
7
|
+
|
|
8
|
+
const { notes, errors } = walkAgentNoteTree()
|
|
9
|
+
|
|
10
|
+
if (errors.length === 0) {
|
|
11
|
+
console.log(`verify-agent-note-classification:已检查 ${notes.length} 篇决策记录,结构一致。`)
|
|
12
|
+
process.exit(0)
|
|
13
|
+
}
|
|
14
|
+
|
|
15
|
+
console.error('verify-agent-note-classification:发现违规:')
|
|
16
|
+
for (const e of errors) console.error(` ${e}`)
|
|
17
|
+
process.exit(1)
|
|
@@ -0,0 +1,79 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* 强制决策记录的头部、各生命周期章节,以及必填的备选方案记录。
|
|
3
|
+
* 分类与文件名归兄弟树门禁管;精确格式规则见 `.agents/notes/README.md`。
|
|
4
|
+
*/
|
|
5
|
+
|
|
6
|
+
import { readFileSync } from 'node:fs'
|
|
7
|
+
import { resolve } from 'node:path'
|
|
8
|
+
import { agentNoteRoot, walkAgentNoteTree } from './agent-note-tree.mjs'
|
|
9
|
+
|
|
10
|
+
/**
|
|
11
|
+
* 各生命周期目录的状态行语法。冒号兼容全角 `:` 与半角 `:`;
|
|
12
|
+
* `已否决` 后的分隔符兼容 `—`、`–` 与 `-`(左右空格可有可无)。
|
|
13
|
+
*/
|
|
14
|
+
const STATUS = {
|
|
15
|
+
proposed: /^状态[::]\s*提案$/,
|
|
16
|
+
implemented: /^状态[::]\s*已实施$/,
|
|
17
|
+
rejected: /^状态[::]\s*已否决\s*[-—–]+\s*.+$/,
|
|
18
|
+
}
|
|
19
|
+
|
|
20
|
+
/** 各生命周期必需的 `##` 章节,除通用的 `## 问题` 开头之外。 */
|
|
21
|
+
const REQUIRED = {
|
|
22
|
+
proposed: ['## 提案', '## 备选方案', '## 验收标准', '## 风险'],
|
|
23
|
+
implemented: ['## 决策', '## 备选方案', '## 后果'],
|
|
24
|
+
rejected: ['## 提案', '## 备选方案'],
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
/** `implemented/` 中禁用的标题——提案期表述。 */
|
|
28
|
+
const BANNED_IMPLEMENTED = /^## (?:提案|计划|迁移计划|验收标准)(?::|:|$)/
|
|
29
|
+
|
|
30
|
+
const { notes, errors } = walkAgentNoteTree()
|
|
31
|
+
|
|
32
|
+
for (const note of notes) {
|
|
33
|
+
const fail = (msg) => {
|
|
34
|
+
errors.push(`格式:${note.rel} — ${msg}`)
|
|
35
|
+
}
|
|
36
|
+
// 规范化:去掉开头 UTF-8 BOM,并把 CRLF / 孤立 CR 统一为 LF,避免 Windows 引入的差异导致误判。
|
|
37
|
+
const lines = readFileSync(resolve(agentNoteRoot, note.rel), 'utf8').replace(/^/, '').replace(/\r\n?/g, '\n').split('\n')
|
|
38
|
+
// 代码块内的格式记号不属于文档结构。
|
|
39
|
+
let inFence = false
|
|
40
|
+
const prose = lines.filter((l) => {
|
|
41
|
+
if (l.startsWith('```')) {
|
|
42
|
+
inFence = !inFence
|
|
43
|
+
return false
|
|
44
|
+
}
|
|
45
|
+
return !inFence
|
|
46
|
+
})
|
|
47
|
+
|
|
48
|
+
if (!/^# 决策记录[::]\s*\S/.test(lines[0] ?? '')) fail('第 1 行必须是 `# 决策记录:<标题>`(冒号可用全角或半角)')
|
|
49
|
+
if (lines[1] !== '') fail('第 2 行必须为空行')
|
|
50
|
+
const status = STATUS[note.lifecycle]
|
|
51
|
+
if (status !== undefined && !status.test(lines[2] ?? '')) {
|
|
52
|
+
fail(`第 3 行必须符合 ${note.lifecycle} 的状态语法(${String(status)})`)
|
|
53
|
+
}
|
|
54
|
+
if (lines[3] !== '') fail('第 4 行必须为空行')
|
|
55
|
+
const statusLines = prose.filter(l => /^状态[::]/.test(l) && l !== lines[2])
|
|
56
|
+
if (statusLines.length > 0 || prose.filter(l => l === lines[2]).length > 1) {
|
|
57
|
+
fail('第 3 行的 `状态:` 行必须是文件中唯一的一条')
|
|
58
|
+
}
|
|
59
|
+
|
|
60
|
+
const h2s = prose.filter(l => l.startsWith('## ')).map(l => l.trimEnd())
|
|
61
|
+
if (h2s[0] !== '## 问题') fail(`第一个章节必须是 \`## 问题\`(实际为 ${JSON.stringify(h2s[0] ?? '<无>')})`)
|
|
62
|
+
for (const required of REQUIRED[note.lifecycle] ?? []) {
|
|
63
|
+
if (!h2s.includes(required)) fail(`缺少必需的 \`${required}\` 章节`)
|
|
64
|
+
}
|
|
65
|
+
if (note.lifecycle === 'implemented') {
|
|
66
|
+
for (const h of h2s.filter(h => BANNED_IMPLEMENTED.test(h))) {
|
|
67
|
+
fail(`\`${h}\` 是提案期标题;已实施记录应陈述现状(并入 决策/后果/测试)`)
|
|
68
|
+
}
|
|
69
|
+
}
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
if (errors.length === 0) {
|
|
73
|
+
console.log(`verify-agent-note-format:已检查 ${notes.length} 篇决策记录,全部符合 .agents/notes/README.md § 文件格式。`)
|
|
74
|
+
process.exit(0)
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
console.error('verify-agent-note-format:发现违规:')
|
|
78
|
+
for (const e of errors) console.error(` ${e}`)
|
|
79
|
+
process.exit(1)
|
|
@@ -0,0 +1,126 @@
|
|
|
1
|
+
/** 校验并追加封存冻结的决策记录归档。 */
|
|
2
|
+
|
|
3
|
+
import { spawnSync } from 'node:child_process'
|
|
4
|
+
import { existsSync, readFileSync, readdirSync, writeFileSync } from 'node:fs'
|
|
5
|
+
import { resolve } from 'node:path'
|
|
6
|
+
import { AGENT_NOTE_CLASSES, agentNoteRoot } from './agent-note-tree.mjs'
|
|
7
|
+
import {
|
|
8
|
+
extendArchiveManifest,
|
|
9
|
+
parseArchiveManifest,
|
|
10
|
+
renderArchiveManifest,
|
|
11
|
+
validateArchiveArtifacts,
|
|
12
|
+
validateArchiveManifestExtension,
|
|
13
|
+
} from './archived-agent-notes.mjs'
|
|
14
|
+
|
|
15
|
+
const args = process.argv.slice(2)
|
|
16
|
+
const writeMode = args.length === 1 && args[0] === '--write'
|
|
17
|
+
if (args.length > 0 && !writeMode) {
|
|
18
|
+
console.error('verify-archived-agent-notes:用法:agent-notes-kit verify archived [--write]')
|
|
19
|
+
process.exit(1)
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
const archiveRoot = resolve(agentNoteRoot, 'archived')
|
|
23
|
+
const manifestPath = resolve(archiveRoot, 'manifest.json')
|
|
24
|
+
const repoRoot = resolve(agentNoteRoot, '../..')
|
|
25
|
+
const errors = []
|
|
26
|
+
const allowedRootFiles = new Set(['AGENTS.md', 'manifest.json'])
|
|
27
|
+
const kinds = new Set()
|
|
28
|
+
|
|
29
|
+
if (!existsSync(resolve(archiveRoot, 'AGENTS.md'))) errors.push('必须存在 archived/AGENTS.md')
|
|
30
|
+
const artifacts = new Map()
|
|
31
|
+
for (const entry of readdirSync(archiveRoot, { withFileTypes: true })) {
|
|
32
|
+
if (entry.isFile()) {
|
|
33
|
+
if (!allowedRootFiles.has(entry.name)) errors.push(`archived/${entry.name}:意外的根目录文件`)
|
|
34
|
+
continue
|
|
35
|
+
}
|
|
36
|
+
if (!entry.isDirectory()) {
|
|
37
|
+
errors.push(`archived/${entry.name}:只允许普通文件和分类目录`)
|
|
38
|
+
continue
|
|
39
|
+
}
|
|
40
|
+
if (!AGENT_NOTE_CLASSES.includes(entry.name)) {
|
|
41
|
+
errors.push(`archived/${entry.name}/:未知决策记录分类`)
|
|
42
|
+
continue
|
|
43
|
+
}
|
|
44
|
+
kinds.add(entry.name)
|
|
45
|
+
for (const child of readdirSync(resolve(archiveRoot, entry.name), { withFileTypes: true })) {
|
|
46
|
+
// 骨架占位符,让 Git 能追踪空分类目录。
|
|
47
|
+
if (child.name === '.gitkeep') continue
|
|
48
|
+
const rel = `${entry.name}/${child.name}`
|
|
49
|
+
if (!child.isFile()) {
|
|
50
|
+
errors.push(`${rel}:归档分类目录中只能包含普通文件`)
|
|
51
|
+
continue
|
|
52
|
+
}
|
|
53
|
+
artifacts.set(rel, readFileSync(resolve(archiveRoot, rel)))
|
|
54
|
+
}
|
|
55
|
+
}
|
|
56
|
+
for (const kind of AGENT_NOTE_CLASSES) {
|
|
57
|
+
if (!kinds.has(kind)) errors.push(`archived/${kind}/:缺少必需的分类目录`)
|
|
58
|
+
}
|
|
59
|
+
errors.push(...validateArchiveArtifacts(artifacts))
|
|
60
|
+
|
|
61
|
+
/** 在给定工作目录下执行 git,失败即抛错。 */
|
|
62
|
+
function runGit(gitArgs, cwd) {
|
|
63
|
+
const result = spawnSync('git', gitArgs, { cwd, encoding: 'utf8' })
|
|
64
|
+
if (result.error !== undefined) throw result.error
|
|
65
|
+
if (result.status !== 0) throw new Error(result.stderr.trim() || `git 退出码 ${result.status}`)
|
|
66
|
+
return result.stdout
|
|
67
|
+
}
|
|
68
|
+
|
|
69
|
+
/**
|
|
70
|
+
* 读取基线清单。git 的 `show <ref>:<path>` 以仓库根目录为基准、而 `ls-tree` 的
|
|
71
|
+
* pathspec 以工作目录为基准;这里统一以 git 顶层目录为 cwd,并用 `--show-prefix`
|
|
72
|
+
* 算出清单相对顶层目录的路径,从而兼容 kit 被装在 monorepo 子目录(而非 git
|
|
73
|
+
* 根目录)的情况。
|
|
74
|
+
* @param {string} ref
|
|
75
|
+
*/
|
|
76
|
+
function readBaselineManifest(ref) {
|
|
77
|
+
const topLevel = runGit(['rev-parse', '--show-toplevel'], repoRoot).trim()
|
|
78
|
+
const prefix = runGit(['rev-parse', '--show-prefix'], repoRoot).trim()
|
|
79
|
+
const manifestRepoPath = `${prefix}.agents/notes/archived/manifest.json`
|
|
80
|
+
runGit(['cat-file', '-e', `${ref}^{commit}`], topLevel)
|
|
81
|
+
const manifestEntry = runGit(['ls-tree', '--name-only', ref, '--', manifestRepoPath], topLevel).trim()
|
|
82
|
+
if (manifestEntry === '') return { version: 1, files: {} }
|
|
83
|
+
return parseArchiveManifest(runGit(['show', `${ref}:${manifestRepoPath}`], topLevel))
|
|
84
|
+
}
|
|
85
|
+
|
|
86
|
+
let manifest = { version: 1, files: {} }
|
|
87
|
+
if (existsSync(manifestPath)) {
|
|
88
|
+
try {
|
|
89
|
+
manifest = parseArchiveManifest(readFileSync(manifestPath, 'utf8'))
|
|
90
|
+
} catch (error) {
|
|
91
|
+
errors.push(`archived/manifest.json:${error instanceof Error ? error.message : String(error)}`)
|
|
92
|
+
}
|
|
93
|
+
} else if (!writeMode) {
|
|
94
|
+
errors.push('必须存在 archived/manifest.json;请用 `npm run verify-archived-agent-notes -- --write` 封存新产物')
|
|
95
|
+
}
|
|
96
|
+
|
|
97
|
+
// CI 提供其可信的变更前提交;本地写入则与已提交的 HEAD 比较。
|
|
98
|
+
const baselineRef = process.env.AGENT_NOTE_ARCHIVE_BASE_REF ?? 'HEAD'
|
|
99
|
+
try {
|
|
100
|
+
const baseline = readBaselineManifest(baselineRef)
|
|
101
|
+
errors.push(...validateArchiveManifestExtension(baseline, manifest))
|
|
102
|
+
} catch (error) {
|
|
103
|
+
errors.push(`archived/manifest.json:无法读取基线 ${JSON.stringify(baselineRef)}:${error instanceof Error ? error.message : String(error)}`)
|
|
104
|
+
}
|
|
105
|
+
|
|
106
|
+
const extended = extendArchiveManifest(manifest, artifacts)
|
|
107
|
+
errors.push(...extended.errors)
|
|
108
|
+
if (!writeMode) {
|
|
109
|
+
for (const path of extended.added) errors.push(`${path}:归档产物尚未封存在 manifest.json 中`)
|
|
110
|
+
}
|
|
111
|
+
|
|
112
|
+
if (errors.length > 0) {
|
|
113
|
+
console.error('verify-archived-agent-notes:归档规则被违反:')
|
|
114
|
+
for (const error of errors) console.error(` ${error}`)
|
|
115
|
+
process.exit(1)
|
|
116
|
+
}
|
|
117
|
+
|
|
118
|
+
if (writeMode) {
|
|
119
|
+
const rendered = renderArchiveManifest(extended.files)
|
|
120
|
+
if (!existsSync(manifestPath) || readFileSync(manifestPath, 'utf8') !== rendered) {
|
|
121
|
+
writeFileSync(manifestPath, rendered)
|
|
122
|
+
}
|
|
123
|
+
console.log(`verify-archived-agent-notes:已封存 ${extended.added.length} 个新产物;已有封存保持不变。`)
|
|
124
|
+
} else {
|
|
125
|
+
console.log(`verify-archived-agent-notes:已检查 ${artifacts.size} 个冻结产物,涉及 ${kinds.size} 个分类。`)
|
|
126
|
+
}
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
# Agent 角色模板
|
|
2
|
+
|
|
3
|
+
通用多 agent 角色模板,适配**单 agent / 多 agent** 两种场景,也适配 **Cursor / Claude Code / 其他** 环境。
|
|
4
|
+
|
|
5
|
+
## 单 agent 还是多 agent
|
|
6
|
+
|
|
7
|
+
- **单 agent**:一个主 agent 按根 `AGENTS.md` 常驻规则 + `.agents/skills/` 技能走完整流程,不需要本目录。
|
|
8
|
+
- **多 agent**:按 `_template.md` 复制出若干角色,各司其职,靠决策记录与 docs 交接。
|
|
9
|
+
|
|
10
|
+
## 环境适配
|
|
11
|
+
|
|
12
|
+
角色文件只写 `name` + `description`(各环境通用);其余 frontmatter 字段按目标环境补:
|
|
13
|
+
|
|
14
|
+
| 环境 | 放哪 | 额外字段 |
|
|
15
|
+
|---|---|---|
|
|
16
|
+
| Cursor | `.cursor/agents/` | `model`、`readonly`、`background` |
|
|
17
|
+
| Claude Code | `.claude/agents/` | `tools`、`model` |
|
|
18
|
+
| 其他 | 自定义 | 按目标框架 |
|
|
19
|
+
|
|
20
|
+
用法:把模板拷到目标环境目录,补上对应字段即可;正文(职责/边界/协作)与环境无关。
|
|
21
|
+
|
|
22
|
+
## 主 Agent
|
|
23
|
+
|
|
24
|
+
主 Agent(协调者)的调度规则见 [_main.md](_main.md):单 agent 模式自己走全程,多 agent 模式只协调不抢活。正文可直接粘贴进根 `AGENTS.md` / `.cursorrules` / Composer 主会话。
|
|
25
|
+
|
|
26
|
+
## 示例角色
|
|
27
|
+
|
|
28
|
+
| 角色 | 职责 | 对应技能 |
|
|
29
|
+
|---|---|---|
|
|
30
|
+
| [architect](architect.md) | 出方案,不写代码 | [init-architecture](../skills/init-architecture/SKILL.md) |
|
|
31
|
+
| [implementer](implementer.md) | 落地代码,维护 docs 现状 | [error-handling](../skills/error-handling/SKILL.md) |
|
|
32
|
+
| [reviewer](reviewer.md) | 代码评审,出问题清单 | [code-review](../skills/code-review/SKILL.md) |
|
|
33
|
+
| [archivist](archivist.md) | 归档/合并决策记录 | [archive-agent-notes](../skills/archive-agent-notes/SKILL.md) |
|
|
34
|
+
| [ui-reviewer](ui-reviewer.md) | UI 评审 | [ui-ux](../skills/ui-ux/SKILL.md) |
|
|
35
|
+
| [doc-writer](doc-writer.md) | 维护文档 | [doc-writing](../skills/doc-writing/SKILL.md)、[prose-standard](../skills/prose-standard/SKILL.md) |
|
|
36
|
+
| [test-engineer](test-engineer.md) | 写测试、跑门禁 | [pre-push-checks](../skills/pre-push-checks/SKILL.md) |
|
|
37
|
+
|
|
38
|
+
这些只是骨架,按项目裁剪。
|
|
39
|
+
|
|
40
|
+
> 另有 2 个技能按需触发、不绑角色:[find-simplifications](../skills/find-simplifications/SKILL.md)(瘦身/清理)、[agent-experience](../skills/agent-experience/SKILL.md)(写/改工具或技能定义)。
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: main
|
|
3
|
+
description: 主协调 Agent。单 agent 模式自己走完整流程;多 agent 模式只协调子 agent,不抢活。
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# 主 Agent
|
|
7
|
+
|
|
8
|
+
本正文是主 Agent 的调度规则(可粘贴进根 `AGENTS.md` / `CLAUDE.md` / `.cursorrules` / Composer 主会话)。
|
|
9
|
+
|
|
10
|
+
## 单 agent 模式
|
|
11
|
+
|
|
12
|
+
只有一个 agent 时,不派发子 agent,按根 `AGENTS.md` 常驻规则 + `.agents/skills/` 技能自己走完整流程:
|
|
13
|
+
|
|
14
|
+
1. 需求进来 → 先做架构/方案(读 `docs/architecture.md`、`docs/design.md`,必要时用 init-architecture 生成初稿);
|
|
15
|
+
2. 落地代码(error-handling);
|
|
16
|
+
3. 写测试(pre-push-checks 选最小检查,跑门禁与测试);
|
|
17
|
+
4. 维护 docs 现状 + 写决策记录(doc-writing / prose-standard);
|
|
18
|
+
5. 自查(code-review),PR 用 pr-description;
|
|
19
|
+
6. 归档被取代的决策(archive-agent-notes);
|
|
20
|
+
7. 需要瘦身/清理时用 find-simplifications;写/改工具或技能定义时用 agent-experience。
|
|
21
|
+
|
|
22
|
+
## 多 agent 模式
|
|
23
|
+
|
|
24
|
+
有子 agent 时,你只做协调,不抢子 agent 的活。
|
|
25
|
+
|
|
26
|
+
核心链:
|
|
27
|
+
|
|
28
|
+
1. 需求进来 → 派 `architect` 出方案(只出方案,不写代码);
|
|
29
|
+
2. 方案确认后,你负责落盘到 docs(architecture / design / contracts)+ 决策记录(architect 通常 readonly);
|
|
30
|
+
3. 派 `implementer`(一个或多个)落地;
|
|
31
|
+
4. 派 `test-engineer` 补测试;
|
|
32
|
+
5. 派 `reviewer` 评审;
|
|
33
|
+
6. 评审/测试失败 → 回派对应角色修复。
|
|
34
|
+
|
|
35
|
+
按需派发:
|
|
36
|
+
|
|
37
|
+
- UI 改动 → 额外派 `ui-reviewer` 评审;
|
|
38
|
+
- 文档需同步 → 派 `doc-writer`;
|
|
39
|
+
- 决策被取代 → 派 `archivist` 归档;
|
|
40
|
+
- 需要瘦身/清理 → 用 find-simplifications 技能;
|
|
41
|
+
- 写/改工具或技能定义 → 用 agent-experience 技能。
|
|
42
|
+
|
|
43
|
+
## 铁律
|
|
44
|
+
|
|
45
|
+
- 角色边界不可越:架构师不写业务代码、开发不推翻架构、评审不改代码。
|
|
46
|
+
- 交接靠文档,不靠对话:方案/契约/决策都落盘到 docs 与 `.agents/notes/`。
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
# AGENTS.md — 决策记录
|
|
2
|
+
|
|
3
|
+
决策记录本质上是 agent 写的 RFC:持久的提案与决策记录,保留理由、备选方案、后果和必需验证。遵循[决策记录规则](README.md)。
|
|
4
|
+
|
|
5
|
+
**每新增一篇决策记录都要做取代检查。** 在活跃树中搜索覆盖同一决策或机制的旧记录,用 [`archive-agent-notes`](../skills/archive-agent-notes/SKILL.md) 对每个完全或部分取代进行分类,并在同一次改动里归档所有够格的已实施记录。部分取代的记录保持活跃并交叉链接。
|
|
6
|
+
|
|
7
|
+
[`archived/`](archived/AGENTS.md) 下的文件是冻结的历史快照:绝不编辑它们,也不把它们当作当前权威。
|