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.
Files changed (69) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +190 -2
  3. package/install.mjs +254 -0
  4. package/package.json +23 -4
  5. package/scripts/agent-note-tree.mjs +77 -0
  6. package/scripts/archived-agent-notes.mjs +143 -0
  7. package/scripts/verify-agent-note-classification.mjs +17 -0
  8. package/scripts/verify-agent-note-format.mjs +79 -0
  9. package/scripts/verify-archived-agent-notes.mjs +126 -0
  10. package/template/.agents/agents/README.md +40 -0
  11. package/template/.agents/agents/_main.md +46 -0
  12. package/template/.agents/agents/_template.md +18 -0
  13. package/template/.agents/agents/architect.md +18 -0
  14. package/template/.agents/agents/archivist.md +18 -0
  15. package/template/.agents/agents/doc-writer.md +18 -0
  16. package/template/.agents/agents/implementer.md +18 -0
  17. package/template/.agents/agents/reviewer.md +18 -0
  18. package/template/.agents/agents/test-engineer.md +18 -0
  19. package/template/.agents/agents/ui-reviewer.md +18 -0
  20. package/template/.agents/notes/AGENTS.md +7 -0
  21. package/template/.agents/notes/README.md +123 -0
  22. package/template/.agents/notes/archived/AGENTS.md +7 -0
  23. package/template/.agents/notes/archived/architecture/.gitkeep +0 -0
  24. package/template/.agents/notes/archived/bug-fix/.gitkeep +0 -0
  25. package/template/.agents/notes/archived/feature/.gitkeep +0 -0
  26. package/template/.agents/notes/archived/manifest.json +4 -0
  27. package/template/.agents/notes/archived/process/.gitkeep +0 -0
  28. package/template/.agents/notes/archived/simplification/.gitkeep +0 -0
  29. package/template/.agents/notes/archived/testing/.gitkeep +0 -0
  30. package/template/.agents/notes/implemented/AGENTS.md +13 -0
  31. package/template/.agents/notes/implemented/architecture/.gitkeep +0 -0
  32. package/template/.agents/notes/implemented/bug-fix/.gitkeep +0 -0
  33. package/template/.agents/notes/implemented/feature/.gitkeep +0 -0
  34. package/template/.agents/notes/implemented/process/.gitkeep +0 -0
  35. package/template/.agents/notes/implemented/simplification/.gitkeep +0 -0
  36. package/template/.agents/notes/implemented/testing/.gitkeep +0 -0
  37. package/template/.agents/notes/proposed/architecture/.gitkeep +0 -0
  38. package/template/.agents/notes/proposed/bug-fix/.gitkeep +0 -0
  39. package/template/.agents/notes/proposed/feature/.gitkeep +0 -0
  40. package/template/.agents/notes/proposed/process/.gitkeep +0 -0
  41. package/template/.agents/notes/proposed/simplification/.gitkeep +0 -0
  42. package/template/.agents/notes/proposed/testing/.gitkeep +0 -0
  43. package/template/.agents/notes/rejected/architecture/.gitkeep +0 -0
  44. package/template/.agents/notes/rejected/bug-fix/.gitkeep +0 -0
  45. package/template/.agents/notes/rejected/feature/.gitkeep +0 -0
  46. package/template/.agents/notes/rejected/process/.gitkeep +0 -0
  47. package/template/.agents/notes/rejected/simplification/.gitkeep +0 -0
  48. package/template/.agents/notes/rejected/testing/.gitkeep +0 -0
  49. package/template/.agents/skills/agent-experience/SKILL.md +25 -0
  50. package/template/.agents/skills/archive-agent-notes/SKILL.md +68 -0
  51. package/template/.agents/skills/code-review/SKILL.md +40 -0
  52. package/template/.agents/skills/doc-writing/SKILL.md +48 -0
  53. package/template/.agents/skills/error-handling/SKILL.md +35 -0
  54. package/template/.agents/skills/find-simplifications/SKILL.md +43 -0
  55. package/template/.agents/skills/init-architecture/SKILL.md +41 -0
  56. package/template/.agents/skills/pr-description/SKILL.md +51 -0
  57. package/template/.agents/skills/pre-push-checks/SKILL.md +42 -0
  58. package/template/.agents/skills/prose-standard/SKILL.md +49 -0
  59. package/template/.agents/skills/ui-ux/SKILL.md +107 -0
  60. package/template/.agents/skills/ui-ux/references/alignment.md +24 -0
  61. package/template/.agents/skills/ui-ux/references/icons.md +54 -0
  62. package/template/.agents/skills/ui-ux/references/responsive.md +52 -0
  63. package/template/.agents/skills/ui-ux/references/spacing.md +17 -0
  64. package/template/docs/AGENTS.md +36 -0
  65. package/template/docs/architecture.md +33 -0
  66. package/template/docs/contracts.md +22 -0
  67. package/template/docs/design/README.md +7 -0
  68. package/template/docs/design.md +30 -0
  69. package/template/docs/glossary.md +11 -0
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 agent-notes-kit contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,191 @@
1
- # Temporary Holding Version
1
+ # Agent 决策记录 Starter Kit
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ **Agent 决策记录(Agent Notes / RFC)框架**:目录与生命周期约定 + 3 个校验门禁(随包运行,不拷入目标项目)+ 11 个技能(归档、架构、UI、评审、错误、PR、提交、文案、文档、简化、工具设计)+ 按需安装的多 agent 角色模板。本 kit 是**单语言中文版**——一篇记录一个文件,全部内容用中文书写。
4
+
5
+ ## 目录结构
6
+
7
+ ```text
8
+ agent-notes-kit/
9
+ ├── README.md ← 本文件(安装与使用说明)
10
+ ├── install.mjs ← CLI 入口(init / agents / add-agent / verify)
11
+ ├── scripts/ ← 校验门禁(零依赖纯 JS),随包分发、以目标项目为 cwd 运行(不拷贝)
12
+ │ ├── agent-note-tree.mjs ← 目录/文件名/分类结构库
13
+ │ ├── verify-agent-note-classification.mjs ← 门禁 1:树结构与文件名
14
+ │ ├── verify-agent-note-format.mjs ← 门禁 2:头部与章节骨架
15
+ │ ├── archived-agent-notes.mjs ← 归档清单/封存库
16
+ │ └── verify-archived-agent-notes.mjs ← 门禁 3:归档不可变(支持 --write 封存)
17
+ ├── tests/ ← kit 自身的 vitest 测试(不随 npm 包发布)
18
+ ├── vitest.config.ts
19
+ └── template/ ← init 拷贝到目标仓库根目录的文件树
20
+ ├── .agents/
21
+ │ ├── notes/
22
+ │ │ ├── README.md ← 决策记录核心规则(面向 agent 的契约)
23
+ │ │ ├── AGENTS.md ← notes 目录的 agent 说明
24
+ │ │ ├── proposed/ ← 提案,尚未实现
25
+ │ │ ├── implemented/ ← 已落地的决策(内含 AGENTS.md)
26
+ │ │ ├── rejected/ ← 被否决的提案
27
+ │ │ └── archived/ ← 冻结的历史归档(内含 AGENTS.md + manifest.json)
28
+ │ ├── agents/ ← 角色模板:基础件(README + _main + _template)默认安装,7 个示例角色按需安装
29
+ │ └── skills/
30
+ │ ├── archive-agent-notes/ ← 归档/合并/修剪
31
+ │ ├── init-architecture/ ← 扫描代码、生成架构初稿
32
+ │ ├── ui-ux/ ← UI 设计/评审
33
+ │ ├── code-review/ ← 代码评审
34
+ │ ├── error-handling/ ← 错误处理
35
+ │ ├── pr-description/ ← PR 描述
36
+ │ ├── pre-push-checks/ ← 提交前检查
37
+ │ ├── prose-standard/ ← 文案标准
38
+ │ ├── find-simplifications/ ← 找简化
39
+ │ ├── agent-experience/ ← 工具/技能设计
40
+ │ └── doc-writing/ ← 文档写作
41
+ └── docs/
42
+ ├── AGENTS.md ← 文档规范模板
43
+ ├── architecture.md ← 架构现状总览模板
44
+ ├── design.md ← UI 设计规格模板
45
+ ├── glossary.md ← 术语表模板
46
+ ├── contracts.md ← 前后端数据契约模板(DTO ↔ TS)
47
+ └── design/ ← 设计稿存放(README + 素材)
48
+ ```
49
+
50
+ 每个生命周期目录下已预建 6 个分类子目录(`feature` / `bug-fix` / `simplification` / `architecture` / `process` / `testing`),用 `.gitkeep` 让 git 追踪。
51
+
52
+ ## 命令一览
53
+
54
+ | 命令 | 作用 |
55
+ | --- | --- |
56
+ | `agent-notes-kit init <目录> [--force] [--agents a,b,c \| --no-agents] [--dep <spec>]` | 铺模板 + 合并 package.json(verify 脚本 + devDep) |
57
+ | `agent-notes-kit agents` | 列出基础件与可安装的示例角色 |
58
+ | `agent-notes-kit add-agent <角色>... [--dir <目录>] [--force]` | 按需把示例角色拷进项目 |
59
+ | `agent-notes-kit verify [classification\|format\|archived] [--write]` | 以当前目录为项目根运行门禁;无参数 = 三个全跑 |
60
+
61
+ 角色模板**按需安装**:`init` 默认只装基础件(`README.md` 调度说明、`_main.md` 主控、`_template.md` 自定义角色模板);`architect` / `implementer` / `reviewer` / `test-engineer` / `ui-reviewer` / `archivist` / `doc-writer` 7 个示例角色用 `--agents` 选择,或事后 `add-agent` 补装。
62
+
63
+ ## 安装(目标项目要求:Node ≥ 22、git)
64
+
65
+ 门禁是零依赖纯 JS(`.mjs`),由 `node` 直接执行(Node ≥ 22,因 `fs.globSync`),目标项目**无需 tsx / vitest,也不会多出 scripts 副本**——只需把 `agent-notes-kit` 装成 devDependency。
66
+
67
+ ### 方式 A:npx 一键初始化(发布到 npm 后)
68
+
69
+ ```sh
70
+ npx agent-notes-kit init my-app
71
+ cd my-app
72
+ npm install
73
+ ```
74
+
75
+ `init` 会自动:创建目录、铺模板(角色按需)、合并 package.json(verify 脚本 + `agent-notes-kit` devDep)。
76
+
77
+ ### 方式 B:从 GitHub 安装(未发布到 npm 时)
78
+
79
+ ```sh
80
+ cd my-app
81
+ npm i -D github:lhzhou180606/agent-notes-kit
82
+ npx agent-notes-kit init . --agents architect,reviewer # 角色按需要挑
83
+ ```
84
+
85
+ ### 方式 C:本地克隆初始化
86
+
87
+ ```sh
88
+ node agent-notes-kit/install.mjs init D:\path\to\target-project --dep file:D:\path\to\agent-notes-kit
89
+ ```
90
+
91
+ `--dep` 指定写进目标 devDependencies 的来源(npm 版本号 / `github:` / `file:`);不给时默认 `^<当前版本>`,从本地克隆运行会提示改用 `--dep`。
92
+
93
+ ### 收尾(所有方式通用)
94
+
95
+ **① 加两条约定**(在目标根 `AGENTS.md` 或 `CLAUDE.md`):
96
+
97
+ ```markdown
98
+ - **改结构前先读 [docs/architecture.md](docs/architecture.md)**;结构性决策在 `.agents/notes/implemented/architecture/` 留记录。
99
+ - **只为持久的决策理由创建决策记录;** 机械/本地改动可豁免([范围](.agents/notes/README.md#何时写一篇))。归档记录已冻结:绝不编辑,也不当作当前权威([归档策略](.agents/notes/README.md#归档与删除))。
100
+ ```
101
+
102
+ **② Claude Code 软链**(让技能与子 agent 被发现):
103
+
104
+ - macOS / Linux:`mkdir -p .claude && ln -s ../.agents/skills .claude/skills && ln -s ../.agents/agents .claude/agents`
105
+ - Windows:先 `git config core.symlinks true` 再用符号链接,或 `mklink /J .claude\skills .agents\skills` 与 `mklink /J .claude\agents .agents\agents`(目录联接;记得把 `.claude/` 加进 `.gitignore`,避免联接内容被重复跟踪)
106
+
107
+ **③ 先提交再校验**(归档门禁要读 git HEAD 基线,仓库需至少一个提交):
108
+
109
+ ```sh
110
+ git add .agents docs package.json
111
+ git commit -m "chore: 引入 Agent 决策记录框架"
112
+ npm run verify-agent-notes
113
+ ```
114
+
115
+ 空骨架下三个门禁都应输出 OK(0 条记录、0 个产物)。
116
+
117
+ pnpm / yarn 用户:脚本内容一致;转发参数时 pnpm 无需 `--`(`pnpm run verify-archived-agent-notes --write`)。
118
+
119
+ ## 日常使用
120
+
121
+ - **何时写**:只为"代码/测试/现有文档都承载不了的决策理由"写记录(为什么、放弃了什么、否决了哪些备选)。机械改动、小的 UI 微调不写。详见 `template/.agents/notes/README.md` § 何时写一篇。
122
+ - **文件命名**:`{生命周期}/{分类}/yyyy-mm-dd-主题.md`,日期 = 首次提出日期。
123
+ - **格式**(全部中文):
124
+
125
+ ```markdown
126
+ # 决策记录:<标题>
127
+
128
+ 状态:提案
129
+
130
+ ## 问题
131
+
132
+ 动机……
133
+
134
+ ## 提案
135
+
136
+ 预期变更……
137
+
138
+ ## 备选方案
139
+
140
+ **方案 B** — 因某原因落选。
141
+
142
+ ## 验收标准
143
+
144
+ 可观察的完成状态。
145
+
146
+ ## 风险
147
+
148
+ 可能出错之处,以及明知放弃的东西。
149
+ ```
150
+
151
+ 各生命周期的必需章节不同(`proposed` 用 `## 提案`/`## 验收标准`/`## 风险`,`implemented` 用 `## 决策`/`## 后果`)。头部 token、`状态:`/`归档:` 行、规范化 `##` 章节名必须逐字一致(机器校验,冒号兼容全角/半角、`已否决` 后分隔符兼容 `—`/`–`/`-`),正文可自由组织。
152
+
153
+ - **生命周期流转**:proposed → implemented(把 `## 提案` 改写成现在时的 `## 决策`);proposed → rejected(在 `状态:` 行加一句理由并冻结)。
154
+ - **归档**:当 implemented 记录不再指导未来、但有历史价值时,按 archive-agent-notes 技能把它移到 `archived/{分类}/`,加一行 `归档:YYYY-MM-DD`,再执行 `npm run verify-archived-agent-notes -- --write` 做防篡改封存(把 sha256 记入 manifest.json,之后任何篡改都会被门禁拒绝)。
155
+
156
+ ## 测试
157
+
158
+ kit 自身内置两套测试(vitest,在 kit 仓库根目录 `npm run test`):
159
+
160
+ - [`tests/archived-agent-notes.spec.ts`](tests/archived-agent-notes.spec.ts):归档库纯函数单测(清单解析/渲染、封存校验、BOM/CRLF/标点容错、追加与篡改)。
161
+ - [`tests/gates.spec.ts`](tests/gates.spec.ts):集成测试,在临时 git 仓库里以 cwd 方式跑三个门禁(空骨架、合法/非法记录、归档封存、篡改拦截;无 git 时自动跳过归档项)。
162
+
163
+ ## 哪些是中文、哪些保持英文
164
+
165
+ **中文**:所有正文、章节标题、状态/归档行、门禁提示与脚本注释。
166
+
167
+ **保持英文(作为标识符)**:目录名(`proposed`/`implemented`/`rejected`/`archived`)、分类名(`feature`/`bug-fix`/`simplification`/`architecture`/`process`/`testing`)、skill 名 `archive-agent-notes`、npm 脚本名、JSON 清单字段、`yyyy-mm-dd-主题.md` 命名模式。这些是机器路径与命令标识,改动它们会破坏门禁和路径编码设计。
168
+
169
+ ## 设计决策
170
+
171
+ | 决策 | 说明 |
172
+ | --- | --- |
173
+ | 全中文 | 头部 token、章节名、状态值全部中文(`# 决策记录:`、`状态:`、`## 问题` 等),正文自由组织 |
174
+ | 单文件 | 一篇记录一个 `.md`,不带双语配对机制 |
175
+ | 门禁随包运行 | `scripts/*.ts` 不拷入目标项目;`agent-notes-kit verify` 以 cwd 为项目根执行,目标只需一个 devDep |
176
+ | 零运行时依赖 | 门禁为纯 JS,`node` 直接运行,不需要 tsx(Node 禁止对 node_modules 内 TS 做类型剥离);kit 的测试也不进目标项目 |
177
+ | 角色按需安装 | init 只装基础件,7 个示例角色 `--agents` / `add-agent` 按需选装 |
178
+ | 门禁内置规范化 | BOM 去除 + 行尾规范化(CRLF/CR→LF),归档哈希按规范化后内容计算,跨平台稳定 |
179
+ | `.gitkeep` 占位 | 空骨架用 `.gitkeep` 让 git 追踪空分类目录 |
180
+ | 独立聚合命令 | `agent-notes-kit verify` 一次跑三个门禁,不依赖聚合框架 |
181
+ | 环境无关的 frontmatter | agent 模板只写 `name`/`description`,其余字段按 Cursor/Claude Code 补 |
182
+
183
+ 自创能力:`init-architecture` 技能、`docs/contracts.md`、7 个 agent 角色模板(为多 agent / 前后端契约场景而设)。
184
+
185
+ 本 kit 未内置 markdown 链接检查与双语机制,需要时自行接入。
186
+
187
+ ## 可选的扩展(未内置)
188
+
189
+ - **交叉引用链接检查**:可用 markdown 链接门禁机械校验记录间的相对链接,并跳过归档记录的出链。
190
+ - **双语支持**:如需中英双语,可自行加中文对照文件与翻译门禁。
191
+ - **CI 接入**:把 `npm run verify-agent-notes` 加进目标项目 CI 即可(CI 镜像需 Node ≥ 22)。
package/install.mjs ADDED
@@ -0,0 +1,254 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * agent-notes-kit 命令行入口。
4
+ *
5
+ * 用法:
6
+ * agent-notes-kit init <目标目录> [--force] [--agents a,b,c | --no-agents] [--dep <spec>]
7
+ * agent-notes-kit agents 列出可安装的示例角色
8
+ * agent-notes-kit add-agent <角色>... [--dir <目标目录>] [--force]
9
+ * agent-notes-kit verify [classification|format|archived] [--write]
10
+ *
11
+ * 设计约定:
12
+ * - 校验门禁(scripts/*.ts)随包分发、不拷入目标项目;verify 以当前工作目录为项目根运行。
13
+ * - 角色模板按需安装:init 默认只装基础件(README + _main + _template),示例角色用
14
+ * --agents 选择或事后 add-agent 补装。
15
+ * - 门禁是零依赖纯 JS(scripts/*.mjs),node 直接执行;目标项目无需 tsx/vitest。
16
+ */
17
+ import { spawnSync } from 'node:child_process'
18
+ import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs'
19
+ import { basename, dirname, join, resolve } from 'node:path'
20
+ import { fileURLToPath } from 'node:url'
21
+
22
+ const kitRoot = dirname(fileURLToPath(import.meta.url))
23
+ const templateRoot = join(kitRoot, 'template')
24
+ const agentsTemplateDir = join(templateRoot, '.agents', 'agents')
25
+ const kitPkg = JSON.parse(readFileSync(join(kitRoot, 'package.json'), 'utf8'))
26
+
27
+ /** 基础件:随 init 默认安装(调度器、角色模板、目录说明)。 */
28
+ const BASE_AGENT_FILES = ['README.md', '_main.md', '_template.md']
29
+
30
+ /** 包内可用的示例角色名(agents 目录下除基础件外的 .md 文件)。 */
31
+ function exampleRoles() {
32
+ return readdirSync(agentsTemplateDir)
33
+ .filter(f => f.endsWith('.md') && !BASE_AGENT_FILES.includes(f))
34
+ .map(f => f.replace(/\.md$/, ''))
35
+ .sort()
36
+ }
37
+
38
+ /** 目标 package.json 注入的脚本:全部转发到包内门禁,不依赖项目里的脚本副本。 */
39
+ const KIT_SCRIPTS = {
40
+ 'verify-agent-note-classification': 'agent-notes-kit verify classification',
41
+ 'verify-agent-note-format': 'agent-notes-kit verify format',
42
+ 'verify-archived-agent-notes': 'agent-notes-kit verify archived',
43
+ 'verify-agent-notes': 'agent-notes-kit verify',
44
+ }
45
+
46
+ /** verify 子命令到包内门禁脚本的映射;无参数时按此顺序全跑。 */
47
+ const GATES = {
48
+ classification: 'verify-agent-note-classification.mjs',
49
+ format: 'verify-agent-note-format.mjs',
50
+ archived: 'verify-archived-agent-notes.mjs',
51
+ }
52
+
53
+ const SKIP_DIRS = new Set(['node_modules', '.git', '.vite', '.vite-temp'])
54
+
55
+ const USAGE = `用法:
56
+ agent-notes-kit init <目标目录> [--force] [--agents a,b,c | --no-agents] [--dep <spec>]
57
+ agent-notes-kit agents 列出可安装的示例角色
58
+ agent-notes-kit add-agent <角色>... [--dir <目标目录>] [--force]
59
+ agent-notes-kit verify [classification|format|archived] [--write]`
60
+
61
+ const args = process.argv.slice(2)
62
+ const command = args[0]
63
+ const rest = args.slice(1)
64
+
65
+ /** 取出 --flag 的值;缺失时报错退出。 */
66
+ function takeOption(list, flag) {
67
+ const i = list.indexOf(flag)
68
+ if (i === -1) return undefined
69
+ const value = list[i + 1]
70
+ if (value === undefined || value.startsWith('--')) {
71
+ console.error(`${flag} 需要一个值`)
72
+ process.exit(2)
73
+ }
74
+ list.splice(i, 2)
75
+ return value
76
+ }
77
+
78
+ function fail(msg) {
79
+ console.error(msg)
80
+ process.exit(2)
81
+ }
82
+
83
+ // ---------------------------------------------------------------- init ----
84
+ function runInit() {
85
+ const force = rest.includes('--force')
86
+ const noAgents = rest.includes('--no-agents')
87
+ const agentsFlag = takeOption(rest, '--agents')
88
+ const depSpec = takeOption(rest, '--dep')
89
+ const positional = rest.filter(a => !a.startsWith('--'))
90
+ if (positional.length !== 1) fail(`init:需要且仅需要一个目标目录。\n${USAGE}`)
91
+ const target = resolve(positional[0])
92
+
93
+ const available = exampleRoles()
94
+ if (agentsFlag !== undefined && noAgents) fail('init:--agents 与 --no-agents 互斥。')
95
+ let selected = new Set()
96
+ if (agentsFlag !== undefined) {
97
+ for (const name of agentsFlag.split(',').map(s => s.trim().replace(/\.md$/, '')).filter(Boolean)) {
98
+ if (!available.includes(name)) fail(`init:未知角色「${name}」。可用:${available.join(', ')}`)
99
+ selected.add(name)
100
+ }
101
+ }
102
+
103
+ if (!existsSync(target)) {
104
+ mkdirSync(target, { recursive: true })
105
+ console.log(`init:已创建目录 ${target}`)
106
+ }
107
+ if (!statSync(target).isDirectory()) fail(`init:目标不是目录:${target}`)
108
+
109
+ /** 判断模板内一个绝对路径是否属于「未选中的示例角色」。 */
110
+ const isUnselectedAgent = (abs) => {
111
+ const dir = dirname(abs)
112
+ if (resolve(dir) !== resolve(agentsTemplateDir)) return false
113
+ const name = basename(abs)
114
+ return name.endsWith('.md') && !BASE_AGENT_FILES.includes(name) && !selected.has(name.replace(/\.md$/, ''))
115
+ }
116
+ const skip = (abs) => SKIP_DIRS.has(basename(abs)) || isUnselectedAgent(abs)
117
+
118
+ const conflicts = []
119
+ const files = []
120
+ function walk(rel) {
121
+ for (const entry of readdirSync(join(templateRoot, rel), { withFileTypes: true })) {
122
+ const abs = join(templateRoot, rel, entry.name)
123
+ if (SKIP_DIRS.has(entry.name)) continue
124
+ const relPath = rel === '' ? entry.name : `${rel}/${entry.name}`
125
+ if (entry.isDirectory()) { walk(relPath); continue }
126
+ if (isUnselectedAgent(abs)) continue
127
+ files.push(relPath)
128
+ if (existsSync(join(target, relPath))) conflicts.push(relPath)
129
+ }
130
+ }
131
+ walk('')
132
+
133
+ if (conflicts.length > 0 && !force) {
134
+ console.error('init:目标中已存在以下文件;加 --force 才会覆盖:')
135
+ for (const c of conflicts) console.error(` ${c}`)
136
+ process.exit(1)
137
+ }
138
+
139
+ cpSync(templateRoot, target, { recursive: true, force: true, filter: src => !skip(src) })
140
+ const agentNote = noAgents
141
+ ? '未安装任何角色模板(--no-agents)'
142
+ : selected.size === 0
143
+ ? `角色模板只装了基础件;示例角色按需补装:agent-notes-kit add-agent <角色>(可用:${available.join(', ')})`
144
+ : `已装角色:${[...selected].join(', ')}(基础件 _main/_template 随附)`
145
+ console.log(`init:已把 ${files.length} 个文件拷贝到 ${target}`)
146
+ console.log(`init:${agentNote}`)
147
+ if (conflicts.length > 0) console.log(`init:覆盖了 ${conflicts.length} 个已存在的文件。`)
148
+
149
+ // 合并 package.json(目标已有的同名脚本/依赖优先,不覆盖)。
150
+ const pkgPath = join(target, 'package.json')
151
+ let pkg = null
152
+ if (existsSync(pkgPath)) {
153
+ try { pkg = JSON.parse(readFileSync(pkgPath, 'utf8')) } catch { pkg = null }
154
+ }
155
+ if (pkg === null || typeof pkg !== 'object' || Array.isArray(pkg)) {
156
+ const name = basename(target).toLowerCase().replace(/[^a-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '') || 'app'
157
+ pkg = { name, version: '0.1.0', private: true }
158
+ }
159
+ pkg.scripts = { ...KIT_SCRIPTS, ...(pkg.scripts ?? {}) }
160
+ const dep = depSpec ?? `^${kitPkg.version}`
161
+ pkg.devDependencies = { 'agent-notes-kit': dep, ...(pkg.devDependencies ?? {}) }
162
+ writeFileSync(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`)
163
+ console.log(`init:已合并 package.json(verify 脚本 + devDep agent-notes-kit@${dep},同名项保留你原有的)。`)
164
+
165
+ const fromNodeModules = kitRoot.includes(`node_modules${kitRoot.includes('/') ? '/' : '\\'}`)
166
+ if (depSpec === undefined && !fromNodeModules) {
167
+ console.warn(`init:注意——本命令来自本地克隆而非 npm 安装;若 agent-notes-kit@${kitPkg.version} 尚未发布到 npm,`)
168
+ console.warn(' 请改用 --dep 指定可解析的来源,例如:--dep github:lhzhou180606/agent-notes-kit 或 --dep file:<kit路径>')
169
+ }
170
+
171
+ console.log(`
172
+ 后续步骤:
173
+ 1. npm install (安装 agent-notes-kit,提供 verify 命令)
174
+ 2. 在根 AGENTS.md / CLAUDE.md 加「架构 + 决策记录」两条约定(片段见 README)。
175
+ 3. git add .agents docs package.json && git commit (归档门禁需要 git 基线)
176
+ 4. npm run verify-agent-notes (三个门禁都在包内运行,不拷贝脚本进项目)
177
+ 5. agent-notes-kit agents (查看示例角色,add-agent 按需补装)
178
+ `)
179
+ }
180
+
181
+ // -------------------------------------------------------------- agents ----
182
+ function runAgents() {
183
+ console.log('基础件(init 默认安装):')
184
+ for (const f of BASE_AGENT_FILES) console.log(` ${f.replace(/\.md$/, '')}`)
185
+ console.log('\n示例角色(按需安装:agent-notes-kit add-agent <角色>...):')
186
+ for (const role of exampleRoles()) {
187
+ const first = readFileSync(join(agentsTemplateDir, `${role}.md`), 'utf8').split('\n').find(l => l.startsWith('# '))
188
+ console.log(` ${role.padEnd(15)} ${first ? first.replace(/^# /, '') : ''}`)
189
+ }
190
+ }
191
+
192
+ // ----------------------------------------------------------- add-agent ----
193
+ function runAddAgent() {
194
+ const force = rest.includes('--force')
195
+ const dirOpt = takeOption(rest, '--dir')
196
+ const names = rest.filter(a => !a.startsWith('--')).map(a => a.replace(/\.md$/, ''))
197
+ if (names.length === 0) fail(`add-agent:至少给一个角色名。\n${USAGE}`)
198
+ const target = resolve(dirOpt ?? process.cwd())
199
+ const agentsDir = join(target, '.agents', 'agents')
200
+ if (!existsSync(agentsDir)) fail(`add-agent:${agentsDir} 不存在;先运行 agent-notes-kit init ${target}`)
201
+
202
+ const available = exampleRoles()
203
+ let copied = 0
204
+ for (const name of names) {
205
+ if (BASE_AGENT_FILES.includes(`${name}.md`)) {
206
+ console.log(`add-agent:「${name}」是基础件,init 已默认安装,跳过。`)
207
+ continue
208
+ }
209
+ if (!available.includes(name)) fail(`add-agent:未知角色「${name}」。可用:${available.join(', ')}`)
210
+ const dest = join(agentsDir, `${name}.md`)
211
+ if (existsSync(dest) && !force) {
212
+ console.log(`add-agent:${name}.md 已存在,跳过(--force 可覆盖)。`)
213
+ continue
214
+ }
215
+ cpSync(join(agentsTemplateDir, `${name}.md`), dest)
216
+ console.log(`add-agent:已安装 ${name}.md → ${dest}`)
217
+ copied++
218
+ }
219
+ if (copied > 0) console.log(`add-agent:完成,新装 ${copied} 个角色。记得 git add .agents/agents`)
220
+ }
221
+
222
+ // -------------------------------------------------------------- verify ----
223
+ function runVerify() {
224
+ const write = rest.includes('--write')
225
+ const names = rest.filter(a => !a.startsWith('--'))
226
+ if (names.length > 1) fail(`verify:最多指定一个门禁。\n${USAGE}`)
227
+ if (names.length === 1 && !(names[0] in GATES)) fail(`verify:未知门禁「${names[0]}」。可用:${Object.keys(GATES).join(', ')}`)
228
+ const order = names.length === 1 ? names : Object.keys(GATES)
229
+
230
+ for (const name of order) {
231
+ const gateArgs = name === 'archived' && write ? ['--write'] : []
232
+ const result = spawnSync(process.execPath, [join(kitRoot, 'scripts', GATES[name]), ...gateArgs], {
233
+ stdio: 'inherit',
234
+ cwd: process.cwd(),
235
+ })
236
+ if (result.status !== 0) process.exit(result.status ?? 1)
237
+ }
238
+ }
239
+
240
+ // ---------------------------------------------------------------- main ----
241
+ switch (command) {
242
+ case 'init': runInit(); break
243
+ case 'agents': runAgents(); break
244
+ case 'add-agent': runAddAgent(); break
245
+ case 'verify': runVerify(); break
246
+ case undefined:
247
+ case 'help':
248
+ case '--help':
249
+ case '-h':
250
+ console.log(USAGE)
251
+ break
252
+ default:
253
+ fail(`未知命令「${command}」。\n${USAGE}`)
254
+ }
package/package.json CHANGED
@@ -1,6 +1,25 @@
1
1
  {
2
2
  "name": "agent-notes-kit",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "1.0.0",
4
+ "description": "Agent 决策记录框架:决策记录 + 校验门禁(包内运行)+ 技能 + 按需安装的多 agent 角色模板 + 文档,一条命令初始化。",
5
+ "type": "module",
6
+ "bin": {
7
+ "agent-notes-kit": "./install.mjs"
8
+ },
9
+ "engines": {
10
+ "node": ">=22"
11
+ },
12
+ "scripts": {
13
+ "prepublishOnly": "node --check install.mjs",
14
+ "test": "vitest run"
15
+ },
16
+ "files": [
17
+ "install.mjs",
18
+ "scripts/",
19
+ "template/"
20
+ ],
21
+ "devDependencies": {
22
+ "vitest": "^4.0.0"
23
+ },
24
+ "license": "MIT"
25
+ }
@@ -0,0 +1,77 @@
1
+ /**
2
+ * 决策记录树的共享结构事实源。生命周期与分类集合是封闭的,
3
+ * 由 `.agents/notes/README.md` 规定;导入本模块不产生副作用。
4
+ */
5
+
6
+ import { globSync, readdirSync } from 'node:fs'
7
+ import { resolve, sep } from 'node:path'
8
+
9
+ /** 门禁始终以当前工作目录为项目根:脚本随 agent-notes-kit 包分发,不再拷入目标项目。 */
10
+ export const agentNoteRoot = resolve(process.cwd(), '.agents/notes')
11
+
12
+ /** 活跃决策记录的生命周期封闭集合(.agents/notes/ 下的顶层目录)。 */
13
+ const AGENT_NOTE_LIFECYCLES = Object.freeze(['proposed', 'implemented', 'rejected'])
14
+
15
+ /**
16
+ * 决策记录分类的封闭集合(每个生命周期下的嵌套目录)。新增分类是刻意行为:
17
+ * 需同时扩展本列表和 README 的「分类」章节。门禁会拒绝任何未列出的目录。
18
+ */
19
+ export const AGENT_NOTE_CLASSES = Object.freeze(['feature', 'bug-fix', 'simplification', 'architecture', 'process', 'testing'])
20
+
21
+ /** 历史已实施记录存放在活跃生命周期树之外。 */
22
+ const AGENT_NOTE_ARCHIVE = 'archived'
23
+
24
+ /** 允许直接放在生命周期根目录、但不属于决策记录的 Markdown 文件。 */
25
+ const ROOT_ALLOWLIST = new Set(['AGENTS.md', 'CLAUDE.md'])
26
+
27
+ /**
28
+ * 遍历发现的一篇决策记录文件。
29
+ * @typedef {{ lifecycle: string, rel: string }} AgentNote
30
+ * rel 为相对 .agents/notes 的路径。
31
+ */
32
+
33
+ /**
34
+ * 遍历决策记录树并强制结构规则。返回所有合法记录,以及每条违规一个错误字符串
35
+ * (未知生命周期或分类目录、深度错误、或文件名错误)。调用方把非空错误列表视为致命。
36
+ * @returns {{ notes: AgentNote[], errors: string[] }}
37
+ */
38
+ export function walkAgentNoteTree() {
39
+ const notes = []
40
+ const errors = []
41
+ // 生命周期集合同样是封闭的:.agents/notes/ 下任何不是已知生命周期的目录
42
+ // 都会让其中的决策记录对下面的遍历不可见。
43
+ for (const entry of readdirSync(agentNoteRoot, { withFileTypes: true })) {
44
+ if (entry.name === 'INDEX.md') {
45
+ errors.push('结构:INDEX.md — 禁止集中式决策记录索引;请浏览生命周期/分类树或搜索仓库')
46
+ continue
47
+ }
48
+ if (entry.isDirectory()
49
+ && entry.name !== AGENT_NOTE_ARCHIVE
50
+ && !AGENT_NOTE_LIFECYCLES.includes(entry.name)) {
51
+ errors.push(`结构:${entry.name}/ — 未知生命周期目录(允许:${AGENT_NOTE_LIFECYCLES.join(', ')},外加 ${AGENT_NOTE_ARCHIVE}/)`)
52
+ }
53
+ }
54
+ for (const lifecycle of AGENT_NOTE_LIFECYCLES) {
55
+ for (const match of globSync(`${lifecycle}/**/*.md`, { cwd: agentNoteRoot }).map(path => path.split(sep).join('/')).sort()) {
56
+ const segs = match.split('/')
57
+ // 直接位于生命周期根目录的允许文件(例如 implemented/AGENTS.md)。
58
+ if (segs.length === 2 && ROOT_ALLOWLIST.has(segs[1] ?? '')) continue
59
+ const cls = segs[1]
60
+ const base = segs[2]
61
+ if (segs.length !== 3 || cls === undefined || base === undefined) {
62
+ errors.push(`结构:${match} — 应为 {生命周期}/{分类}/文件.md(实际深度 ${segs.length})`)
63
+ continue
64
+ }
65
+ if (!AGENT_NOTE_CLASSES.includes(cls)) {
66
+ errors.push(`结构:${match} — 未知分类目录 "${cls}"(允许:${AGENT_NOTE_CLASSES.join(', ')})`)
67
+ continue
68
+ }
69
+ if (!/^\d{4}-\d{2}-\d{2}-.+\.md$/.test(base)) {
70
+ errors.push(`结构:${match} — 文件名必须是 yyyy-mm-dd-主题.md`)
71
+ continue
72
+ }
73
+ notes.push({ lifecycle, rel: match })
74
+ }
75
+ }
76
+ return { notes, errors }
77
+ }