@cat-kit/agent-context 1.1.5 → 1.2.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/README.md +261 -51
- package/dist/cli.js +1 -1
- package/dist/commands/init.js +1 -0
- package/dist/commands/status.js +1 -1
- package/dist/commands/validate.js +1 -1
- package/dist/content/actions.js +23 -47
- package/dist/content/index.js +24 -11
- package/dist/context/reader.js +1 -1
- package/dist/context/scope.js +5 -0
- package/dist/stats.html +1 -1
- package/package.json +1 -5
- package/src/cli.ts +8 -0
- package/src/commands/init.ts +43 -0
- package/src/commands/status.ts +1 -0
- package/src/commands/validate.ts +1 -0
- package/src/content/actions.ts +24 -17
- package/src/content/index.ts +24 -11
- package/src/context/index.ts +1 -0
- package/src/context/reader.ts +13 -3
- package/src/context/scope.ts +70 -0
- package/src/types.ts +1 -0
package/README.md
CHANGED
|
@@ -1,14 +1,41 @@
|
|
|
1
1
|
# Agent Context
|
|
2
2
|
|
|
3
|
-
`@cat-kit/agent-context`
|
|
3
|
+
`@cat-kit/agent-context` 用来给 AI 编程助手安装统一的 `ac-workflow` Skill，让不同工具都按同一套 `.agent-context/` 协议管理任务。
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
它解决的不是“如何生成代码”，而是“如何让 AI 在多轮协作里始终知道当前计划、下一步动作和什么时候该归档”。
|
|
6
|
+
|
|
7
|
+
## 核心模型
|
|
8
|
+
|
|
9
|
+
`agent-context` 由两部分组成：
|
|
10
|
+
|
|
11
|
+
- CLI：负责安装、同步、校验和归档
|
|
12
|
+
- Skill：负责在对话里识别 `init / plan / replan / implement / patch / rush / done` 这些动作
|
|
13
|
+
|
|
14
|
+
安装 Skill 后，AI 会围绕项目根目录的 `.agent-context/` 目录工作：
|
|
15
|
+
|
|
16
|
+
```text
|
|
17
|
+
.agent-context/
|
|
18
|
+
├── plan-{N}/ # 当前计划（最多一个）
|
|
19
|
+
│ ├── plan.md
|
|
20
|
+
│ └── patch-{N}.md
|
|
21
|
+
├── preparing/ # 待执行计划队列
|
|
22
|
+
│ └── plan-{N}/
|
|
23
|
+
└── done/ # 已归档计划
|
|
24
|
+
└── plan-{N}-{YYYYMMDD}/
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
生命周期如下：
|
|
6
28
|
|
|
7
29
|
```text
|
|
8
30
|
init -> plan -> replan -> implement -> patch -> done
|
|
31
|
+
└-> rush -> done
|
|
9
32
|
```
|
|
10
33
|
|
|
11
|
-
|
|
34
|
+
其中：
|
|
35
|
+
|
|
36
|
+
- `plan / replan / rush / patch` 需要你给出明确任务描述
|
|
37
|
+
- `implement` 不接受额外描述，只执行当前计划
|
|
38
|
+
- `done` 最终由 `agent-context done` 归档当前已执行计划
|
|
12
39
|
|
|
13
40
|
## 安装
|
|
14
41
|
|
|
@@ -18,86 +45,269 @@ Skill 内部会约束 `.agent-context/` 目录、计划编号、`plan.md` 模板
|
|
|
18
45
|
npm install -g @cat-kit/agent-context
|
|
19
46
|
```
|
|
20
47
|
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
在项目根目录执行：
|
|
48
|
+
在项目根目录安装 Skill：
|
|
24
49
|
|
|
25
50
|
```bash
|
|
26
51
|
agent-context install
|
|
27
52
|
```
|
|
28
53
|
|
|
29
|
-
|
|
54
|
+
也可以指定工具：
|
|
30
55
|
|
|
31
|
-
|
|
56
|
+
```bash
|
|
57
|
+
agent-context install --tools claude,codex,cursor
|
|
58
|
+
```
|
|
32
59
|
|
|
33
|
-
|
|
34
|
-
- “为这个需求出一个计划”
|
|
35
|
-
- “重做当前计划”
|
|
36
|
-
- “按当前计划开始实现”
|
|
37
|
-
- “给当前计划补一个 patch”
|
|
38
|
-
- “当前计划已经真正完成，归档它”
|
|
60
|
+
安装完成后，CLI 会在对应目录生成 Skill 文件，例如：
|
|
39
61
|
|
|
40
|
-
|
|
62
|
+
- Codex: `.codex/skills/agent-context/`
|
|
63
|
+
- Claude: `.claude/skills/agent-context/`
|
|
64
|
+
- Cursor: `.cursor/skills/agent-context/`
|
|
41
65
|
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
66
|
+
## 快速开始
|
|
67
|
+
|
|
68
|
+
最常见的用法只有三步：
|
|
69
|
+
|
|
70
|
+
1. 在项目里执行 `agent-context install`
|
|
71
|
+
2. 把生成的 Skill 文件和 `.agent-context/` 一起纳入版本管理
|
|
72
|
+
3. 直接在对话里对 AI 说出动作意图
|
|
73
|
+
|
|
74
|
+
例如：
|
|
75
|
+
|
|
76
|
+
- `初始化这个项目的 agent context`
|
|
77
|
+
- `为“增加导出 Excel 功能”出一个计划`
|
|
78
|
+
- `按当前计划开始实现`
|
|
79
|
+
- `当前计划已经做完，归档它`
|
|
80
|
+
|
|
81
|
+
## Action 参考
|
|
82
|
+
|
|
83
|
+
下面的 action 不是 CLI 子命令，而是你对 AI 说的话。AI 安装 Skill 后，会把这些话映射到固定协议。
|
|
84
|
+
|
|
85
|
+
| Action | 何时使用 | 当前状态要求 | 结果 |
|
|
86
|
+
| ------ | -------- | ------------ | ---- |
|
|
87
|
+
| `init` | 项目还没建立好协作约定，或者 `AGENTS.md` 不完整 | 无 | 生成或补全 `AGENTS.md`，新项目可继续进入计划 |
|
|
88
|
+
| `plan` | 新需求需要正式拆分步骤 | 当前没有冲突中的已执行计划 | 创建 `plan.md`，必要时拆成当前计划 + preparing 队列 |
|
|
89
|
+
| `replan` | 计划还没实施，但拆分方式或技术路线要改 | 目标计划必须仍是 `未执行` | 重写计划结构，保留单当前计划模型 |
|
|
90
|
+
| `implement` | 计划已经明确，开始真正落地 | 当前计划存在且状态为 `未执行` | 实施全部步骤，验证通过后把计划改为 `已执行` |
|
|
91
|
+
| `patch` | 已执行计划上出现 Bug、遗漏项或增量需求 | 当前计划必须是 `已执行` | 执行修补，生成 `patch-{N}.md`，更新影响范围 |
|
|
92
|
+
| `rush` | 任务范围很清晰，不想先单独经历 plan 再 implement | 当前不能存在未实施计划 | 直接创建单计划并立刻实施 |
|
|
93
|
+
| `done` | 当前计划已经真正完成，需要收尾归档 | 当前计划必须是 `已执行` | 把当前计划移入 `done/`，必要时晋升下一个 preparing 计划 |
|
|
94
|
+
|
|
95
|
+
### `init`
|
|
96
|
+
|
|
97
|
+
适合两种场景：
|
|
98
|
+
|
|
99
|
+
- 新项目刚开始，没有统一协作规则
|
|
100
|
+
- 老项目已有代码，但缺少高质量 `AGENTS.md`
|
|
101
|
+
|
|
102
|
+
你可以这样说：
|
|
103
|
+
|
|
104
|
+
```text
|
|
105
|
+
初始化这个项目的 agent context，技术栈是 Bun + TypeScript，测试用 Vitest
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
AI 会先判断这是新项目还是旧项目，再决定是创建还是补全 `AGENTS.md`。如果项目信息不足，`init` 应该先提问，而不是直接猜。
|
|
109
|
+
|
|
110
|
+
### `plan`
|
|
111
|
+
|
|
112
|
+
适合“要做一件事，但还没开始改代码”的阶段。
|
|
113
|
+
|
|
114
|
+
你可以这样说：
|
|
115
|
+
|
|
116
|
+
```text
|
|
117
|
+
为“给 http 客户端补一个重试插件”出计划
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
`plan` 的重点不是生成一段漂亮的说明，而是产出一个后续可执行的 `plan.md`。如果任务很大，AI 应该拆成“当前计划 + preparing 队列”；如果任务很小，就只建一个计划。
|
|
121
|
+
|
|
122
|
+
### `replan`
|
|
123
|
+
|
|
124
|
+
只在“计划还没实施”时使用。它解决的是“原计划思路不对”，不是“代码写完后还想改一点”。
|
|
125
|
+
|
|
126
|
+
你可以这样说：
|
|
127
|
+
|
|
128
|
+
```text
|
|
129
|
+
重做当前计划，不要引入新依赖，保持 core 零依赖
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
如果当前计划已经执行过，再要求修改方案，就不应该走 `replan`，而应该走 `patch`。
|
|
133
|
+
|
|
134
|
+
### `implement`
|
|
135
|
+
|
|
136
|
+
适合“计划已经定了，现在开始按计划干活”的阶段。
|
|
137
|
+
|
|
138
|
+
你可以这样说：
|
|
139
|
+
|
|
140
|
+
```text
|
|
141
|
+
按当前计划开始实现
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
`implement` 不接受附加需求。它只做一件事：读取当前 `plan.md`，逐步实施、验证、回写状态。如果执行中发现阻塞，AI 应该报告，而不是私自跳过步骤。
|
|
145
|
+
|
|
146
|
+
### `patch`
|
|
147
|
+
|
|
148
|
+
适合在“当前计划已经执行完成”之后做增量修补。
|
|
149
|
+
|
|
150
|
+
你可以这样说：
|
|
151
|
+
|
|
152
|
+
```text
|
|
153
|
+
给当前计划补一个 patch，修复流式读取时空行被跳过的问题
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
`patch` 会保留原计划，把新增修补记录写入 `patch-{N}.md`。如果你只是发现实现里还有一个小问题，不需要新开计划，优先用 `patch`。
|
|
157
|
+
|
|
158
|
+
### `rush`
|
|
159
|
+
|
|
160
|
+
适合边界清楚、工作量可控的任务，比如：
|
|
49
161
|
|
|
50
|
-
|
|
162
|
+
- 修一份文档
|
|
163
|
+
- 改一个很明确的测试
|
|
164
|
+
- 补一个小型脚本
|
|
51
165
|
|
|
52
|
-
|
|
166
|
+
你可以这样说：
|
|
53
167
|
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
168
|
+
```text
|
|
169
|
+
rush 一下，把 agent-context 文档里的 action 解释补完整
|
|
170
|
+
```
|
|
171
|
+
|
|
172
|
+
`rush` 的本质是“跳过单独确认计划内容”，但不是跳过计划本身。AI 仍然需要创建 `plan.md`，只是创建后直接实施。
|
|
173
|
+
|
|
174
|
+
### `done`
|
|
175
|
+
|
|
176
|
+
适合真正收尾时使用，不适合把“暂时先停一下”伪装成完成。
|
|
177
|
+
|
|
178
|
+
你可以这样说：
|
|
179
|
+
|
|
180
|
+
```text
|
|
181
|
+
当前计划已经真正完成，归档它
|
|
182
|
+
```
|
|
183
|
+
|
|
184
|
+
归档后，当前计划会进入 `.agent-context/done/`。如果 `preparing/` 里还有下一个计划，它会被晋升为新的当前计划。
|
|
185
|
+
|
|
186
|
+
## 具体协作场景
|
|
187
|
+
|
|
188
|
+
下面是几条更具体、可直接复用的协作方式。
|
|
189
|
+
|
|
190
|
+
### 场景 1：从零开始做一个新功能
|
|
191
|
+
|
|
192
|
+
适用情况：需求还没拆解，涉及多个文件或多个步骤。
|
|
193
|
+
|
|
194
|
+
推荐流程：
|
|
195
|
+
|
|
196
|
+
1. `为“新增 xx 功能”出计划`
|
|
197
|
+
2. 查看 AI 生成的 `plan.md`
|
|
198
|
+
3. `按当前计划开始实现`
|
|
199
|
+
4. 如果上线前又补了一个小需求：`给当前计划补一个 patch，...`
|
|
200
|
+
5. 确认全部完成：`当前计划已经真正完成，归档它`
|
|
201
|
+
|
|
202
|
+
### 场景 2：方案还没落地，但技术路线要改
|
|
203
|
+
|
|
204
|
+
适用情况：计划还是 `未执行`，只是发现拆分不合理或路线变了。
|
|
205
|
+
|
|
206
|
+
推荐指令：
|
|
207
|
+
|
|
208
|
+
```text
|
|
209
|
+
重做当前计划，保留目标不变，但改成不引入三方依赖的方案
|
|
210
|
+
```
|
|
211
|
+
|
|
212
|
+
这时应该用 `replan`，而不是让 AI 一边改计划一边偷偷改代码。
|
|
213
|
+
|
|
214
|
+
### 场景 3：代码已经写完，但需要修一个增量问题
|
|
215
|
+
|
|
216
|
+
适用情况：当前计划状态已经是 `已执行`。
|
|
217
|
+
|
|
218
|
+
推荐指令：
|
|
219
|
+
|
|
220
|
+
```text
|
|
221
|
+
给当前计划补一个 patch，修复 Windows 路径兼容问题
|
|
222
|
+
```
|
|
223
|
+
|
|
224
|
+
这时继续走 `plan` 或 `rush` 都会破坏上下文连续性。正确做法是保留主计划，用 `patch` 记录增量修改。
|
|
225
|
+
|
|
226
|
+
### 场景 4：任务非常明确，不想多轮沟通
|
|
61
227
|
|
|
62
|
-
|
|
228
|
+
适用情况：工作边界清晰，几乎不需要额外澄清。
|
|
229
|
+
|
|
230
|
+
推荐指令：
|
|
231
|
+
|
|
232
|
+
```text
|
|
233
|
+
rush 一下，把 README 里的命令表更新为最新版本
|
|
234
|
+
```
|
|
235
|
+
|
|
236
|
+
`rush` 很适合这种“知道要改什么，也知道验收标准”的任务，但不适合目标模糊的大需求。
|
|
237
|
+
|
|
238
|
+
## CLI 命令参考
|
|
239
|
+
|
|
240
|
+
CLI 只负责文件安装、同步和状态管理，不负责替代 action。
|
|
63
241
|
|
|
64
242
|
### `agent-context install`
|
|
65
243
|
|
|
66
|
-
安装
|
|
244
|
+
安装 Skill 文件。
|
|
67
245
|
|
|
68
246
|
```bash
|
|
69
|
-
# 交互式选择工具
|
|
70
247
|
agent-context install
|
|
71
|
-
|
|
72
|
-
# 指定工具
|
|
73
|
-
agent-context install --tools claude,codex,cursor
|
|
74
|
-
|
|
75
|
-
# 仅检查将产生哪些变更
|
|
248
|
+
agent-context install --tools codex,claude
|
|
76
249
|
agent-context install --check --tools copilot
|
|
250
|
+
agent-context install --yes
|
|
77
251
|
```
|
|
78
252
|
|
|
79
253
|
### `agent-context sync`
|
|
80
254
|
|
|
81
|
-
|
|
255
|
+
当你升级了 `@cat-kit/agent-context` 版本后，用它把项目中的 Skill 内容同步到最新协议。
|
|
82
256
|
|
|
83
257
|
```bash
|
|
84
|
-
# 同步当前已安装工具
|
|
85
258
|
agent-context sync
|
|
259
|
+
agent-context sync --tools cursor,codex
|
|
260
|
+
agent-context sync --check
|
|
261
|
+
```
|
|
86
262
|
|
|
87
|
-
|
|
88
|
-
agent-context sync --tools claude,cursor
|
|
263
|
+
### `agent-context validate`
|
|
89
264
|
|
|
90
|
-
|
|
91
|
-
|
|
265
|
+
校验 `.agent-context/` 是否符合协议，例如：
|
|
266
|
+
|
|
267
|
+
- 当前计划是否唯一
|
|
268
|
+
- `plan.md` 是否存在
|
|
269
|
+
- 状态字段是否合法
|
|
270
|
+
|
|
271
|
+
```bash
|
|
272
|
+
agent-context validate
|
|
92
273
|
```
|
|
93
274
|
|
|
94
|
-
###
|
|
275
|
+
### `agent-context status`
|
|
276
|
+
|
|
277
|
+
查看当前计划、preparing 队列和归档数量。
|
|
278
|
+
|
|
279
|
+
```bash
|
|
280
|
+
agent-context status
|
|
281
|
+
```
|
|
282
|
+
|
|
283
|
+
### `agent-context done`
|
|
284
|
+
|
|
285
|
+
归档当前已执行计划。
|
|
286
|
+
|
|
287
|
+
```bash
|
|
288
|
+
agent-context done
|
|
289
|
+
agent-context done --yes
|
|
290
|
+
```
|
|
291
|
+
|
|
292
|
+
## 通用选项
|
|
293
|
+
|
|
294
|
+
| 选项 | 适用命令 | 说明 |
|
|
295
|
+
| ---- | -------- | ---- |
|
|
296
|
+
| `--tools <tools>` | `install` / `sync` | 指定目标工具，逗号分隔 |
|
|
297
|
+
| `--check` | `install` / `sync` | 只检查是否有变更，不写文件 |
|
|
298
|
+
| `--yes` | `install` / `done` | 跳过交互确认；`install` 会优先复用已安装工具 |
|
|
299
|
+
|
|
300
|
+
## 支持的工具
|
|
301
|
+
|
|
302
|
+
| 工具 | Skill 目录 |
|
|
303
|
+
| ---- | ---------- |
|
|
304
|
+
| Claude | `.claude/skills/agent-context/` |
|
|
305
|
+
| Codex | `.codex/skills/agent-context/` |
|
|
306
|
+
| Cursor | `.cursor/skills/agent-context/` |
|
|
307
|
+
| Antigravity | `.agent/skills/agent-context/` |
|
|
308
|
+
| GitHub Copilot | `.github/skills/agent-context/` |
|
|
95
309
|
|
|
96
|
-
|
|
97
|
-
| ----------------- | ------------------------------------------------------------------- |
|
|
98
|
-
| `--tools <tools>` | 指定目标工具，逗号分隔 |
|
|
99
|
-
| `--check` | 仅检查，不写入文件 |
|
|
100
|
-
| `--yes` | 仅 `install` 支持；非交互模式下优先复用已安装工具，否则安装全部工具 |
|
|
310
|
+
其中 Codex 会额外生成 `agents/openai.yaml` 元数据文件，其余工具只生成 Skill 内容本身。
|
|
101
311
|
|
|
102
312
|
## License
|
|
103
313
|
|
package/dist/cli.js
CHANGED
|
@@ -1,2 +1,2 @@
|
|
|
1
1
|
#!/usr/bin/env node
|
|
2
|
-
import{doneCommand as e}from"./commands/done.js";import{
|
|
2
|
+
import{doneCommand as e}from"./commands/done.js";import{initCommand as t}from"./commands/init.js";import{installCommand as n}from"./commands/install.js";import{statusCommand as r}from"./commands/status.js";import{syncCommand as i}from"./commands/sync.js";import{validateCommand as a}from"./commands/validate.js";import{readFileSync as o}from"node:fs";import{Command as s}from"commander";const c=JSON.parse(o(new URL(`../package.json`,import.meta.url),`utf8`)),l=typeof c.version==`string`?c.version:`0.0.0`,u=new s;u.name(`agent-context`).description(`Agent Context Skills 安装工具`).version(l),u.command(`install`).description(`安装 ac-workflow Skill`).option(`--tools <tools>`,`指定目标工具，逗号分隔：claude,codex,cursor,antigravity,copilot`).option(`--yes`,`非交互模式：优先复用已安装工具，否则安装全部工具`).option(`--check`,`仅检查是否存在待更新内容，不写入文件`).action(n),u.command(`sync`).description(`同步已安装的 ac-workflow Skill`).option(`--tools <tools>`,`指定目标工具，逗号分隔：claude,codex,cursor,antigravity,copilot`).option(`--check`,`仅检查是否存在待更新内容，不写入文件`).action(i),u.command(`init`).description(`初始化 SCOPE（从 git user.name 自动获取或手动指定）`).option(`--scope <name>`,`手动指定 SCOPE 名称`).option(`--yes`,`非交互模式：自动覆盖已存在的 SCOPE`).action(t),u.command(`validate`).description(`校验 .agent-context 目录结构`).action(a),u.command(`status`).description(`查看当前 agent-context 状态`).action(r),u.command(`done`).description(`归档当前已执行计划`).option(`--yes`,`跳过确认，直接归档`).action(e),u.parseAsync().catch(e=>{let t=e instanceof Error?e.message:String(e);console.error(`\n❌ ${t}`),process.exitCode=1});export{};
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
import{initScope as e}from"../context/scope.js";import{existsSync as t}from"node:fs";import{join as n}from"node:path";import{confirm as r}from"@inquirer/prompts";import{mkdir as i,readFile as a}from"node:fs/promises";async function o(o={}){let s=n(process.cwd(),`.agent-context`);await i(s,{recursive:!0});let c=n(s,`.env`);if(t(c)){let e=(await a(c,`utf-8`)).match(/^SCOPE=(.+)$/m)?.[1]?.trim();if(e&&(console.log(`当前 SCOPE: ${e}`),!o.yes&&!await r({message:`是否覆盖当前 SCOPE？`}))){console.log(`已取消`);return}}let l=await e(s,o.scope);console.log(`✅ SCOPE 已设置: ${l}`),console.log(` 目录: .agent-context/${l}/`)}export{o as initCommand};
|
package/dist/commands/status.js
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
import{readRawContext as e}from"../context/reader.js";import{validate as t}from"../context/validator.js";async function n(){let{snapshot:n,currentPlanCount:r}=await e(process.cwd()),i=t(n,r);if(!i.valid){for(let e of i.errors)console.log(`❌ ${e}`);process.exitCode=1;return}if(i.context===null){console.log(`ℹ 无活跃上下文`);return}let a=i.context,o=a.currentPlan?`plan-${a.currentPlan.number} (${a.currentPlan.status})`:`无`,s=a.preparing.length>0?a.preparing.map(e=>`plan-${e.number}`).join(`, `):`无`;console.log(``),console.log(`Agent Context Status`),console.log(`────────────────────`),console.log(`当前计划: ${o}`),console.log(`待执行队列: ${s}`),console.log(`已归档: ${a.done.length} 个`)}export{n as statusCommand};
|
|
1
|
+
import{readRawContext as e}from"../context/reader.js";import{validate as t}from"../context/validator.js";async function n(){let{snapshot:n,currentPlanCount:r}=await e(process.cwd()),i=t(n,r);if(!i.valid){for(let e of i.errors)console.log(`❌ ${e}`);process.exitCode=1;return}if(i.context===null){console.log(`ℹ 无活跃上下文`);return}let a=i.context,o=a.currentPlan?`plan-${a.currentPlan.number} (${a.currentPlan.status})`:`无`,s=a.preparing.length>0?a.preparing.map(e=>`plan-${e.number}`).join(`, `):`无`;console.log(``),console.log(`Agent Context Status`),console.log(`────────────────────`),console.log(`当前作用域: ${a.scope}`),console.log(`当前计划: ${o}`),console.log(`待执行队列: ${s}`),console.log(`已归档: ${a.done.length} 个`)}export{n as statusCommand};
|
|
@@ -1 +1 @@
|
|
|
1
|
-
import{readRawContext as e}from"../context/reader.js";import{validate as t}from"../context/validator.js";async function n(){let{snapshot:n,currentPlanCount:r}=await e(process.cwd()),i=t(n,r);if(i.context===null){console.log(`⚠️ 无 .agent-context 目录`);return}if(i.valid){console.log(`✅ 校验通过`);let e=i.context
|
|
1
|
+
import{readRawContext as e}from"../context/reader.js";import{validate as t}from"../context/validator.js";async function n(){let{snapshot:n,currentPlanCount:r}=await e(process.cwd()),i=t(n,r);if(i.context===null){console.log(`⚠️ 无 .agent-context 目录`);return}if(i.valid){console.log(`✅ 校验通过`);let e=i.context;console.log(` 当前作用域: ${e.scope}`);let t=e.currentPlan?`plan-${e.currentPlan.number} (${e.currentPlan.status})`:`无`;console.log(` 当前计划: ${t}`),console.log(` 待执行: ${e.preparing.length} 个`),console.log(` 已归档: ${e.done.length} 个`);return}for(let e of i.errors)console.log(`❌ ${e}`);process.exitCode=1}export{n as validateCommand};
|
package/dist/content/actions.js
CHANGED
|
@@ -33,7 +33,7 @@ const e=[`init`,`plan`,`replan`,`implement`,`patch`,`rush`],t={init:n,plan:r,rep
|
|
|
33
33
|
- 大型单体仓库按子包拆分维护本地 \`AGENTS.md\`。
|
|
34
34
|
`}function r(){return`# plan
|
|
35
35
|
|
|
36
|
-
创建新的执行计划，写入 \`.agent-context/plan-{number}/plan.md\`。按复杂度可拆分为多个计划，维护「单当前计划 + preparing 队列」结构。
|
|
36
|
+
创建新的执行计划，写入 \`.agent-context/{scope}/plan-{number}/plan.md\`。按复杂度可拆分为多个计划，维护「单当前计划 + preparing 队列」结构。
|
|
37
37
|
|
|
38
38
|
必须附带计划描述。
|
|
39
39
|
|
|
@@ -41,7 +41,9 @@ const e=[`init`,`plan`,`replan`,`implement`,`patch`,`rush`],t={init:n,plan:r,rep
|
|
|
41
41
|
|
|
42
42
|
- 运行 \`agent-context validate\`，不通过则中止并报告错误。
|
|
43
43
|
- 描述为空 → 拒绝执行。
|
|
44
|
-
- 存在未归档的已执行当前计划 →
|
|
44
|
+
- 存在未归档的已执行当前计划 → 判断新需求与当前计划的关联性：
|
|
45
|
+
- 相关联或用户本意是修补 → 拒绝执行，提示改用 patch。
|
|
46
|
+
- 完全无关 → 拒绝执行，提示先运行 \`agent-context done\` 归档后再创建新计划。
|
|
45
47
|
- 存在多个当前计划 → 拒绝执行，提示恢复单活跃状态。
|
|
46
48
|
|
|
47
49
|
## 执行步骤
|
|
@@ -51,7 +53,7 @@ const e=[`init`,`plan`,`replan`,`implement`,`patch`,`rush`],t={init:n,plan:r,rep
|
|
|
51
53
|
- 存在显著不同的技术路径需用户决策。
|
|
52
54
|
- 验收标准不明确：无法判断何时算"完成"。
|
|
53
55
|
2. 按复杂度决定单计划或多计划拆分。
|
|
54
|
-
3. 多计划拆分时：最小编号进入 \`.agent-context/\` 作为当前计划，其余进入 \`.agent-context/preparing/\`。单计划直接创建。
|
|
56
|
+
3. 多计划拆分时：最小编号进入 \`.agent-context/{scope}/\` 作为当前计划，其余进入 \`.agent-context/{scope}/preparing/\`。单计划直接创建。
|
|
55
57
|
4. 每个计划创建 \`plan.md\`，遵循下方模板。
|
|
56
58
|
5. **自检**（不通过则修改后重新检查）：
|
|
57
59
|
- 每个步骤可独立执行且有明确完成标准。
|
|
@@ -98,9 +100,9 @@ const e=[`init`,`plan`,`replan`,`implement`,`patch`,`rush`],t={init:n,plan:r,rep
|
|
|
98
100
|
|
|
99
101
|
## 作用域
|
|
100
102
|
|
|
101
|
-
- 默认作用域：\`.agent-context/preparing/\` 中全部未实施计划。
|
|
103
|
+
- 默认作用域：\`.agent-context/{scope}/preparing/\` 中全部未实施计划。
|
|
102
104
|
- 可通过描述指定仅重规划部分计划（如"重规划 plan-3 和 plan-5"）。
|
|
103
|
-
- 当前计划为 \`已执行\` → 禁止重写，仅允许重规划 \`preparing/\` 队列。
|
|
105
|
+
- 当前计划为 \`已执行\` → 禁止重写，仅允许重规划 \`{scope}/preparing/\` 队列。
|
|
104
106
|
- 当前计划为 \`未执行\` 且用户明确要求 → 可纳入重规划范围。
|
|
105
107
|
|
|
106
108
|
## 执行步骤
|
|
@@ -110,38 +112,7 @@ const e=[`init`,`plan`,`replan`,`implement`,`patch`,`rush`],t={init:n,plan:r,rep
|
|
|
110
112
|
3. 生成新的拆分方案，保持「单当前计划 + 若干 preparing 计划」结构。
|
|
111
113
|
4. 新增计划编号：全局 max(N)+1 递增分配；未改动计划保持原编号。
|
|
112
114
|
5. 更新目录结构，确保每个新计划的 \`plan.md\` 遵循标准模板。
|
|
113
|
-
`}function a(){return`#
|
|
114
|
-
|
|
115
|
-
实施当前计划 \`.agent-context/plan-{number}/plan.md\` 中的全部步骤，通过验证循环后将状态更新为「已执行」。
|
|
116
|
-
|
|
117
|
-
不接受额外描述。
|
|
118
|
-
|
|
119
|
-
## 前置检查
|
|
120
|
-
|
|
121
|
-
- 运行 \`agent-context validate\`，不通过则中止并报告错误。
|
|
122
|
-
- 带描述 → 拒绝执行。
|
|
123
|
-
- 当前计划不存在 → 拒绝执行，提示先创建计划。
|
|
124
|
-
- 当前计划状态为 \`已执行\` → 拒绝执行，提示使用 patch 修补或运行 \`agent-context done\` 归档。
|
|
125
|
-
- \`## 目标\` 或 \`## 内容\` 为空 → 拒绝执行，提示补充。
|
|
126
|
-
- 存在多个当前计划 → 拒绝执行，提示恢复单活跃状态。
|
|
127
|
-
- 仅操作当前计划，不直接操作 \`preparing/\` 中的计划。
|
|
128
|
-
- 遇到阻塞问题应向用户报告，不可静默跳过。
|
|
129
|
-
|
|
130
|
-
## 执行步骤
|
|
131
|
-
|
|
132
|
-
1. **读取计划**：读取当前 \`plan.md\`，理解 \`## 目标\` 与 \`## 内容\`。
|
|
133
|
-
2. **实施变更**：依据 \`## 内容\` 的步骤逐项实施。
|
|
134
|
-
3. **验证循环（WHILE 循环检查）**：
|
|
135
|
-
- **3.1 检查对照**：对照 \`## 内容\`，确保每个步骤均已实施完毕，无遗漏。
|
|
136
|
-
- **3.2 运行验证**：
|
|
137
|
-
- **IF** (编码任务) **THEN**：必须运行代码检查（Lint/Typecheck）与相关测试命令。
|
|
138
|
-
- **ELSE IF** (非编码任务，如纯文档修改或项目规划) **THEN**：无需运行外部命令，仅凭逻辑和视觉排版审阅是否符合验收标准。
|
|
139
|
-
- **3.3 结果判断**：
|
|
140
|
-
- **IF** (存在未通过的验证报错、未完成项或遗漏项) **THEN**：修复发现的问题，然后 **GOTO 3.1**（重新检查）。
|
|
141
|
-
- **ELSE IF** (验证全部通过 或 非编码任务验收合格) **THEN**：退出验证循环，即 **GOTO 4** 继续执行。
|
|
142
|
-
4. **更新状态**：将 \`plan.md\` 的状态行修改为 \`> 状态: 已执行\`。
|
|
143
|
-
5. **记录范围**：更新 \`## 影响范围\`，详细记录本次变动的具体文件路径。
|
|
144
|
-
`}function o(){return`# patch
|
|
115
|
+
`}function a(){return"# implement\n\n实施当前计划 `.agent-context/{scope}/plan-{number}/plan.md` 中的全部步骤，通过验证循环后将状态更新为「已执行」。\n\n不接受额外描述。\n\n## 前置检查\n\n- 运行 `agent-context validate`，不通过则中止并报告错误。\n- 带描述 → 拒绝执行。\n- 当前计划不存在 → 拒绝执行，提示先创建计划。\n- 当前计划状态为 `已执行` → 拒绝执行，提示使用 patch 修补或运行 `agent-context done` 归档。\n- `## 目标` 或 `## 内容` 为空 → 拒绝执行，提示补充。\n- 存在多个当前计划 → 拒绝执行，提示恢复单活跃状态。\n- 仅操作当前计划，不直接操作 `preparing/` 中的计划。\n- 遇到阻塞问题应向用户报告，不可静默跳过。\n\n## 执行步骤\n\n1. **读取计划**：读取当前 `plan.md`，理解 `## 目标` 与 `## 内容`。\n2. **实施变更**：依据 `## 内容` 的步骤逐项实施。\n3. **验证循环（WHILE 循环检查）**：\n - **3.1 检查对照**：对照 `## 内容`，确保每个步骤均已实施完毕，无遗漏。\n - **3.2 运行验证**：\n - **IF** (编码任务) **THEN**：必须运行代码检查（Lint/Typecheck）与相关测试命令。\n - **ELSE IF** (非编码任务，如纯文档修改或项目规划) **THEN**：无需运行外部命令，仅凭逻辑和视觉排版审阅是否符合验收标准。\n - **3.3 结果判断**：\n - **IF** (存在未通过的验证报错、未完成项或遗漏项) **THEN**：修复发现的问题，然后 **GOTO 3.1**（重新检查）。\n - **ELSE IF** (验证全部通过 或 非编码任务验收合格) **THEN**：退出验证循环，即 **GOTO 4** 继续执行。\n4. **更新状态**：将 `plan.md` 的状态行修改为 `> 状态: 已执行`。\n5. **记录范围**：更新 `## 影响范围`，详细记录本次变动的具体文件路径。`.agent-context/` 目录下的文件不计入影响范围。\n"}function o(){return`# patch
|
|
145
116
|
|
|
146
117
|
基于当前已执行计划创建增量补丁，修复问题或追加变更。
|
|
147
118
|
|
|
@@ -164,7 +135,7 @@ const e=[`init`,`plan`,`replan`,`implement`,`patch`,`rush`],t={init:n,plan:r,rep
|
|
|
164
135
|
4. 创建 \`patch-{number}.md\`（编号：扫描当前计划目录已有补丁取 max+1），遵循下方模板。
|
|
165
136
|
5. 回写 \`plan.md\`：
|
|
166
137
|
- \`## 历史补丁\`：追加 \`- patch-{number}: {补丁名称}\`，按编号去重。
|
|
167
|
-
- \`##
|
|
138
|
+
- \`## 影响范围\`：合并本次变更路径，按路径去重。\`.agent-context/\` 目录下的文件不计入影响范围。
|
|
168
139
|
|
|
169
140
|
## patch.md 模板
|
|
170
141
|
|
|
@@ -191,17 +162,22 @@ const e=[`init`,`plan`,`replan`,`implement`,`patch`,`rush`],t={init:n,plan:r,rep
|
|
|
191
162
|
|
|
192
163
|
- 运行 \`agent-context validate\`，不通过则中止并报告错误。
|
|
193
164
|
- 描述为空 → 拒绝执行。
|
|
194
|
-
- 存在未归档的已执行当前计划 →
|
|
165
|
+
- 存在未归档的已执行当前计划 → 判断新需求与当前计划的关联性：
|
|
166
|
+
- 相关联或用户本意是修补 → 拒绝执行，提示改用 patch。
|
|
167
|
+
- 完全无关 → 拒绝执行，提示先运行 \`agent-context done\` 归档后再创建新计划。
|
|
195
168
|
- 存在未实施的当前计划 → 拒绝执行，提示先 implement 或 replan。
|
|
196
169
|
|
|
197
170
|
## 执行步骤
|
|
198
171
|
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
172
|
+
> rush = plan + implement 的连续执行，下方仅列出差异点，未提及的步骤按原协议执行。
|
|
173
|
+
|
|
174
|
+
### 阶段一：plan（差异）
|
|
175
|
+
|
|
176
|
+
- 跳过「需求澄清」步骤——rush 要求描述本身已足够明确。
|
|
177
|
+
- 强制单计划，不拆分，不进入 preparing 队列。
|
|
178
|
+
- 完成 plan 后**不等待用户确认**，直接进入阶段二。
|
|
179
|
+
|
|
180
|
+
### 阶段二：implement
|
|
181
|
+
|
|
182
|
+
- 按 \`implement\` 协议**完整执行**（读取计划 → 实施变更 → 验证循环 → 更新状态与影响范围），无任何裁剪。
|
|
207
183
|
`}export{e as ACTION_NAMES,t as ACTION_RENDERERS};
|
package/dist/content/index.js
CHANGED
|
@@ -1,7 +1,14 @@
|
|
|
1
1
|
import{ACTION_NAMES as e,ACTION_RENDERERS as t}from"./actions.js";function n(n){let i=[{relativePath:`SKILL.md`,body:r(n)},...e.map(e=>({relativePath:`actions/${e}.md`,body:t[e]()}))];return n.metadataFiles.includes(`openai`)&&i.push({relativePath:`agents/openai.yaml`,body:a()}),{files:i}}function r(e){return`${i(e)}
|
|
2
2
|
# Agent Context
|
|
3
3
|
|
|
4
|
-
管理项目中的 \`.agent-context/\`
|
|
4
|
+
管理项目中的 \`.agent-context/\` 计划生命周期。匹配用户意图后，**必须先读取对应协议文件的完整内容**，再严格按协议步骤逐项执行。
|
|
5
|
+
|
|
6
|
+
## 执行纪律
|
|
7
|
+
|
|
8
|
+
- **协议先行**：匹配到动作后，必须先读取对应 \`actions/*.md\` 协议文件的完整内容，再逐步执行。禁止凭记忆、摘要或猜测跳过协议步骤。
|
|
9
|
+
- **前置检查必做**：所有动作（done 除外）均包含「前置检查」，必须逐条执行，不可跳过。包括运行 \`agent-context validate\`。
|
|
10
|
+
- **禁止直接改动**：在 plan / rush 创建计划之前，不得直接修改项目代码文件。任何代码变更必须在已创建计划（implement）或已创建补丁（patch）的上下文中进行。
|
|
11
|
+
- **顺序执行**：协议步骤必须按编号顺序逐项执行，不可跳步、合并或并行。
|
|
5
12
|
|
|
6
13
|
## 意图匹配
|
|
7
14
|
|
|
@@ -15,29 +22,35 @@ import{ACTION_NAMES as e,ACTION_RENDERERS as t}from"./actions.js";function n(n){
|
|
|
15
22
|
| 无活跃计划时快速出计划并实施 | rush | \`actions/rush.md\` |
|
|
16
23
|
| 任务彻底完成、归档当前计划 | done | 运行 \`agent-context done\` |
|
|
17
24
|
|
|
18
|
-
>
|
|
25
|
+
> **消歧**：存在已执行的当前计划时，用户提出变更需求：
|
|
26
|
+
> - 需求与当前计划**相关联**或用户本意是修补当前计划 → 走 **patch**。
|
|
27
|
+
> - 需求与当前计划**完全无关** → 拒绝执行，提示先运行 \`agent-context done\` 归档当前计划后再创建新计划。
|
|
19
28
|
|
|
20
29
|
## 全局约束
|
|
21
30
|
|
|
22
31
|
- 状态机两态：\`未执行\`、\`已执行\`。
|
|
23
|
-
- 任意时刻最多一个当前计划：\`.agent-context/plan-{number}\`。
|
|
32
|
+
- 任意时刻最多一个当前计划：\`.agent-context/{scope}/plan-{number}\`。
|
|
24
33
|
- 多个当前计划 → 拒绝执行，提示恢复单活跃状态。
|
|
25
34
|
- 计划编号全局递增，不复用。补丁编号在单计划目录内递增，不复用。
|
|
35
|
+
- 影响范围（\`## 影响范围\`）不得包含 \`.agent-context/\` 目录下的文件。
|
|
26
36
|
|
|
27
37
|
## 目录结构
|
|
28
38
|
|
|
29
39
|
\`\`\`text
|
|
30
40
|
.agent-context/
|
|
31
|
-
├──
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
├──
|
|
35
|
-
│
|
|
36
|
-
└──
|
|
37
|
-
|
|
41
|
+
├── .env # SCOPE 配置（SCOPE=<name>）
|
|
42
|
+
├── .gitignore
|
|
43
|
+
└── {scope}/ # 作用域目录（按协作者隔离）
|
|
44
|
+
├── plan-{N}/ # 当前计划（最多一个）
|
|
45
|
+
│ ├── plan.md
|
|
46
|
+
│ └── patch-{N}.md
|
|
47
|
+
├── preparing/ # 待执行计划队列
|
|
48
|
+
│ └── plan-{N}/
|
|
49
|
+
└── done/ # 已归档计划
|
|
50
|
+
└── plan-{N}-{YYYYMMDD}/
|
|
38
51
|
\`\`\`
|
|
39
52
|
|
|
40
|
-
|
|
53
|
+
编号规则：在当前 scope 内扫描全部 \`plan-N\` 目录取 \`max(N)+1\`。
|
|
41
54
|
`}function i(e){let t=[`---`,`name: ac-workflow`,`description: 管理 .agent-context 计划生命周期，按 init、plan、replan、implement、patch、rush、done 协议推进任务。`];return e.frontmatterProfile===`claude`&&t.push(`argument-hint: [request]`),e.frontmatterProfile===`copilot`&&t.push(`license: MIT`),t.push(`---`,``),`${t.join(`
|
|
42
55
|
`)}\n`}function a(){return`interface:
|
|
43
56
|
display_name: "Agent Context Workflow"
|
package/dist/context/reader.js
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
import{
|
|
1
|
+
import{resolveScope as e}from"./scope.js";import{existsSync as t}from"node:fs";import{join as n}from"node:path";import{readFile as r,readdir as i}from"node:fs/promises";const a=/^plan-(\d+)$/,o=/^plan-(\d+)(?:-\d{8})?$/,s=/^>\s*状态:\s*(未执行|已执行)$/m,c=/^>?[ \t]*状态[：:].*$/m;async function l(r){let i=n(r,`.agent-context`);if(!t(i))return{snapshot:null,currentPlanCount:0};let a=await e(i),o=n(i,a),s=await d(o),c=await d(n(o,`preparing`)),l=await f(n(o,`done`));return{snapshot:{root:o,scope:a,currentPlan:s[0]??null,preparing:c,done:l},currentPlanCount:s.length}}async function u(e){let i=n(e,`plan.md`);if(!t(i))return`未执行`;let a=await r(i,`utf-8`),o=a.match(s);return o?o[1]:c.test(a)?`未知`:`未执行`}async function d(e){if(!t(e))return[];let r=await i(e,{withFileTypes:!0}),o=[];for(let t of r){if(!t.isDirectory())continue;let r=t.name.match(a);if(!r?.[1])continue;let i=parseInt(r[1],10),s=n(e,t.name),c=await u(s);o.push({number:i,status:c,dir:s})}return o.sort((e,t)=>e.number-t.number)}async function f(e){if(!t(e))return[];let r=await i(e,{withFileTypes:!0}),a=[];for(let t of r){if(!t.isDirectory())continue;let r=t.name.match(o);r?.[1]&&a.push({number:parseInt(r[1],10),dir:n(e,t.name)})}return a.sort((e,t)=>e.number-t.number)}export{l as readRawContext};
|
|
@@ -0,0 +1,5 @@
|
|
|
1
|
+
import{existsSync as e}from"node:fs";import{join as t}from"node:path";import{mkdir as n,readFile as r,writeFile as i}from"node:fs/promises";import{execSync as a}from"node:child_process";async function o(n){let i=t(n,`.env`);if(e(i)){let e=(await r(i,`utf-8`)).match(/^SCOPE=(.+)$/m);if(e?.[1])return e[1].trim()}return s(n)}async function s(e,r){let o;if(r)o=c(r);else{let e;try{e=a(`git config user.name`,{encoding:`utf-8`}).trim()}catch{throw Error(`未找到 git user.name，请先运行 git config user.name <name>`)}if(!e)throw Error(`未找到 git user.name，请先运行 git config user.name <name>`);o=c(e)}return await i(t(e,`.env`),`SCOPE=${o}\n`,`utf-8`),await l(e),await n(t(e,o),{recursive:!0}),o}function c(e){return e.toLowerCase().replace(/[^a-z0-9]/g,`-`).replace(/^-+|-+$/g,``).replace(/-{2,}/g,`-`)}async function l(n){let a=t(n,`.gitignore`);if(e(a)){let e=await r(a,`utf-8`);e.split(`
|
|
2
|
+
`).some(e=>e.trim()===`.env`)||await i(a,e.trimEnd()+`
|
|
3
|
+
.env
|
|
4
|
+
`,`utf-8`)}else await i(a,`.env
|
|
5
|
+
`,`utf-8`)}export{s as initScope,o as resolveScope};
|
package/dist/stats.html
CHANGED
|
@@ -4930,7 +4930,7 @@ var drawChart = (function (exports) {
|
|
|
4930
4930
|
</script>
|
|
4931
4931
|
<script>
|
|
4932
4932
|
/*<!--*/
|
|
4933
|
-
const data = {"version":2,"tree":{"name":"root","children":[{"name":"cli.d.ts","children":[{"name":"home/whj/codes/cat-kit/packages/agent-context/src/cli.d.ts","uid":"
|
|
4933
|
+
const data = {"version":2,"tree":{"name":"root","children":[{"name":"cli.d.ts","children":[{"name":"home/whj/codes/cat-kit/packages/agent-context/src/cli.d.ts","uid":"5218ad55-1"}]},{"name":"cli.js","children":[{"name":"home/whj/codes/cat-kit/packages/agent-context/src/cli.ts","uid":"5218ad55-3"}]},{"name":"commands/done.js","children":[{"name":"home/whj/codes/cat-kit/packages/agent-context/src/commands/done.ts","uid":"5218ad55-5"}]},{"name":"commands/init.js","children":[{"name":"home/whj/codes/cat-kit/packages/agent-context/src/commands/init.ts","uid":"5218ad55-7"}]},{"name":"commands/install.js","children":[{"name":"home/whj/codes/cat-kit/packages/agent-context/src/commands/install.ts","uid":"5218ad55-9"}]},{"name":"commands/printer.js","children":[{"name":"home/whj/codes/cat-kit/packages/agent-context/src/commands/printer.ts","uid":"5218ad55-11"}]},{"name":"commands/status.js","children":[{"name":"home/whj/codes/cat-kit/packages/agent-context/src/commands/status.ts","uid":"5218ad55-13"}]},{"name":"commands/sync.js","children":[{"name":"home/whj/codes/cat-kit/packages/agent-context/src/commands/sync.ts","uid":"5218ad55-15"}]},{"name":"commands/validate.js","children":[{"name":"home/whj/codes/cat-kit/packages/agent-context/src/commands/validate.ts","uid":"5218ad55-17"}]},{"name":"content/actions.js","children":[{"name":"home/whj/codes/cat-kit/packages/agent-context/src/content/actions.ts","uid":"5218ad55-19"}]},{"name":"content/index.js","children":[{"name":"home/whj/codes/cat-kit/packages/agent-context/src/content/index.ts","uid":"5218ad55-21"}]},{"name":"context/archiver.js","children":[{"name":"home/whj/codes/cat-kit/packages/agent-context/src/context/archiver.ts","uid":"5218ad55-23"}]},{"name":"context/reader.js","children":[{"name":"home/whj/codes/cat-kit/packages/agent-context/src/context/reader.ts","uid":"5218ad55-25"}]},{"name":"context/scope.js","children":[{"name":"home/whj/codes/cat-kit/packages/agent-context/src/context/scope.ts","uid":"5218ad55-27"}]},{"name":"context/validator.js","children":[{"name":"home/whj/codes/cat-kit/packages/agent-context/src/context/validator.ts","uid":"5218ad55-29"}]},{"name":"runner.js","children":[{"name":"home/whj/codes/cat-kit/packages/agent-context/src/runner.ts","uid":"5218ad55-31"}]},{"name":"tools.js","children":[{"name":"home/whj/codes/cat-kit/packages/agent-context/src/tools.ts","uid":"5218ad55-33"}]}],"isRoot":true},"nodeParts":{"5218ad55-1":{"renderedLength":0,"gzipLength":0,"brotliLength":0,"metaUid":"5218ad55-0"},"5218ad55-3":{"renderedLength":1767,"gzipLength":0,"brotliLength":0,"metaUid":"5218ad55-2"},"5218ad55-5":{"renderedLength":1349,"gzipLength":0,"brotliLength":0,"metaUid":"5218ad55-4"},"5218ad55-7":{"renderedLength":718,"gzipLength":0,"brotliLength":0,"metaUid":"5218ad55-6"},"5218ad55-9":{"renderedLength":985,"gzipLength":0,"brotliLength":0,"metaUid":"5218ad55-8"},"5218ad55-11":{"renderedLength":909,"gzipLength":0,"brotliLength":0,"metaUid":"5218ad55-10"},"5218ad55-13":{"renderedLength":993,"gzipLength":0,"brotliLength":0,"metaUid":"5218ad55-12"},"5218ad55-15":{"renderedLength":745,"gzipLength":0,"brotliLength":0,"metaUid":"5218ad55-14"},"5218ad55-17":{"renderedLength":813,"gzipLength":0,"brotliLength":0,"metaUid":"5218ad55-16"},"5218ad55-19":{"renderedLength":9957,"gzipLength":0,"brotliLength":0,"metaUid":"5218ad55-18"},"5218ad55-21":{"renderedLength":4203,"gzipLength":0,"brotliLength":0,"metaUid":"5218ad55-20"},"5218ad55-23":{"renderedLength":1012,"gzipLength":0,"brotliLength":0,"metaUid":"5218ad55-22"},"5218ad55-25":{"renderedLength":2173,"gzipLength":0,"brotliLength":0,"metaUid":"5218ad55-24"},"5218ad55-27":{"renderedLength":1479,"gzipLength":0,"brotliLength":0,"metaUid":"5218ad55-26"},"5218ad55-29":{"renderedLength":1905,"gzipLength":0,"brotliLength":0,"metaUid":"5218ad55-28"},"5218ad55-31":{"renderedLength":2037,"gzipLength":0,"brotliLength":0,"metaUid":"5218ad55-30"},"5218ad55-33":{"renderedLength":2174,"gzipLength":0,"brotliLength":0,"metaUid":"5218ad55-32"}},"nodeMetas":{"5218ad55-0":{"id":"/home/whj/codes/cat-kit/packages/agent-context/src/cli.d.ts","moduleParts":{"cli.d.ts":"5218ad55-1"},"imported":[],"importedBy":[],"isEntry":true},"5218ad55-2":{"id":"/home/whj/codes/cat-kit/packages/agent-context/src/cli.ts","moduleParts":{"cli.js":"5218ad55-3"},"imported":[{"uid":"5218ad55-34"},{"uid":"5218ad55-35"},{"uid":"5218ad55-4"},{"uid":"5218ad55-6"},{"uid":"5218ad55-8"},{"uid":"5218ad55-12"},{"uid":"5218ad55-14"},{"uid":"5218ad55-16"}],"importedBy":[],"isEntry":true},"5218ad55-4":{"id":"/home/whj/codes/cat-kit/packages/agent-context/src/commands/done.ts","moduleParts":{"commands/done.js":"5218ad55-5"},"imported":[{"uid":"5218ad55-36"},{"uid":"5218ad55-37"},{"uid":"5218ad55-38"}],"importedBy":[{"uid":"5218ad55-2"}]},"5218ad55-6":{"id":"/home/whj/codes/cat-kit/packages/agent-context/src/commands/init.ts","moduleParts":{"commands/init.js":"5218ad55-7"},"imported":[{"uid":"5218ad55-34"},{"uid":"5218ad55-39"},{"uid":"5218ad55-36"},{"uid":"5218ad55-37"},{"uid":"5218ad55-26"}],"importedBy":[{"uid":"5218ad55-2"}]},"5218ad55-8":{"id":"/home/whj/codes/cat-kit/packages/agent-context/src/commands/install.ts","moduleParts":{"commands/install.js":"5218ad55-9"},"imported":[{"uid":"5218ad55-37"},{"uid":"5218ad55-30"},{"uid":"5218ad55-32"},{"uid":"5218ad55-10"}],"importedBy":[{"uid":"5218ad55-2"}]},"5218ad55-10":{"id":"/home/whj/codes/cat-kit/packages/agent-context/src/commands/printer.ts","moduleParts":{"commands/printer.js":"5218ad55-11"},"imported":[{"uid":"5218ad55-36"}],"importedBy":[{"uid":"5218ad55-8"},{"uid":"5218ad55-14"}]},"5218ad55-12":{"id":"/home/whj/codes/cat-kit/packages/agent-context/src/commands/status.ts","moduleParts":{"commands/status.js":"5218ad55-13"},"imported":[{"uid":"5218ad55-38"}],"importedBy":[{"uid":"5218ad55-2"}]},"5218ad55-14":{"id":"/home/whj/codes/cat-kit/packages/agent-context/src/commands/sync.ts","moduleParts":{"commands/sync.js":"5218ad55-15"},"imported":[{"uid":"5218ad55-30"},{"uid":"5218ad55-32"},{"uid":"5218ad55-10"}],"importedBy":[{"uid":"5218ad55-2"}]},"5218ad55-16":{"id":"/home/whj/codes/cat-kit/packages/agent-context/src/commands/validate.ts","moduleParts":{"commands/validate.js":"5218ad55-17"},"imported":[{"uid":"5218ad55-38"}],"importedBy":[{"uid":"5218ad55-2"}]},"5218ad55-18":{"id":"/home/whj/codes/cat-kit/packages/agent-context/src/content/actions.ts","moduleParts":{"content/actions.js":"5218ad55-19"},"imported":[],"importedBy":[{"uid":"5218ad55-20"}]},"5218ad55-20":{"id":"/home/whj/codes/cat-kit/packages/agent-context/src/content/index.ts","moduleParts":{"content/index.js":"5218ad55-21"},"imported":[{"uid":"5218ad55-18"}],"importedBy":[{"uid":"5218ad55-30"}]},"5218ad55-22":{"id":"/home/whj/codes/cat-kit/packages/agent-context/src/context/archiver.ts","moduleParts":{"context/archiver.js":"5218ad55-23"},"imported":[{"uid":"5218ad55-39"},{"uid":"5218ad55-36"}],"importedBy":[{"uid":"5218ad55-38"}]},"5218ad55-24":{"id":"/home/whj/codes/cat-kit/packages/agent-context/src/context/reader.ts","moduleParts":{"context/reader.js":"5218ad55-25"},"imported":[{"uid":"5218ad55-34"},{"uid":"5218ad55-39"},{"uid":"5218ad55-36"},{"uid":"5218ad55-26"}],"importedBy":[{"uid":"5218ad55-38"}]},"5218ad55-26":{"id":"/home/whj/codes/cat-kit/packages/agent-context/src/context/scope.ts","moduleParts":{"context/scope.js":"5218ad55-27"},"imported":[{"uid":"5218ad55-34"},{"uid":"5218ad55-39"},{"uid":"5218ad55-36"},{"uid":"5218ad55-40"}],"importedBy":[{"uid":"5218ad55-6"},{"uid":"5218ad55-38"},{"uid":"5218ad55-24"}]},"5218ad55-28":{"id":"/home/whj/codes/cat-kit/packages/agent-context/src/context/validator.ts","moduleParts":{"context/validator.js":"5218ad55-29"},"imported":[{"uid":"5218ad55-34"},{"uid":"5218ad55-36"}],"importedBy":[{"uid":"5218ad55-38"}]},"5218ad55-30":{"id":"/home/whj/codes/cat-kit/packages/agent-context/src/runner.ts","moduleParts":{"runner.js":"5218ad55-31"},"imported":[{"uid":"5218ad55-34"},{"uid":"5218ad55-39"},{"uid":"5218ad55-36"},{"uid":"5218ad55-20"},{"uid":"5218ad55-32"}],"importedBy":[{"uid":"5218ad55-8"},{"uid":"5218ad55-14"}]},"5218ad55-32":{"id":"/home/whj/codes/cat-kit/packages/agent-context/src/tools.ts","moduleParts":{"tools.js":"5218ad55-33"},"imported":[{"uid":"5218ad55-34"},{"uid":"5218ad55-36"}],"importedBy":[{"uid":"5218ad55-8"},{"uid":"5218ad55-14"},{"uid":"5218ad55-30"}]},"5218ad55-34":{"id":"node:fs","moduleParts":{},"imported":[],"importedBy":[{"uid":"5218ad55-2"},{"uid":"5218ad55-6"},{"uid":"5218ad55-26"},{"uid":"5218ad55-30"},{"uid":"5218ad55-32"},{"uid":"5218ad55-24"},{"uid":"5218ad55-28"}]},"5218ad55-35":{"id":"commander","moduleParts":{},"imported":[],"importedBy":[{"uid":"5218ad55-2"}]},"5218ad55-36":{"id":"node:path","moduleParts":{},"imported":[],"importedBy":[{"uid":"5218ad55-4"},{"uid":"5218ad55-6"},{"uid":"5218ad55-26"},{"uid":"5218ad55-30"},{"uid":"5218ad55-32"},{"uid":"5218ad55-10"},{"uid":"5218ad55-24"},{"uid":"5218ad55-28"},{"uid":"5218ad55-22"}]},"5218ad55-37":{"id":"@inquirer/prompts","moduleParts":{},"imported":[],"importedBy":[{"uid":"5218ad55-4"},{"uid":"5218ad55-6"},{"uid":"5218ad55-8"}]},"5218ad55-38":{"id":"/home/whj/codes/cat-kit/packages/agent-context/src/context/index.ts","moduleParts":{},"imported":[{"uid":"5218ad55-24"},{"uid":"5218ad55-28"},{"uid":"5218ad55-22"},{"uid":"5218ad55-26"}],"importedBy":[{"uid":"5218ad55-4"},{"uid":"5218ad55-12"},{"uid":"5218ad55-16"}]},"5218ad55-39":{"id":"node:fs/promises","moduleParts":{},"imported":[],"importedBy":[{"uid":"5218ad55-6"},{"uid":"5218ad55-26"},{"uid":"5218ad55-30"},{"uid":"5218ad55-24"},{"uid":"5218ad55-22"}]},"5218ad55-40":{"id":"node:child_process","moduleParts":{},"imported":[],"importedBy":[{"uid":"5218ad55-26"}]}},"env":{"rollup":"4.23.0"},"options":{"gzip":false,"brotli":false,"sourcemap":false}};
|
|
4934
4934
|
|
|
4935
4935
|
const run = () => {
|
|
4936
4936
|
const width = window.innerWidth;
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@cat-kit/agent-context",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.2.0",
|
|
4
4
|
"description": "代理上下文管理工具",
|
|
5
5
|
"bin": {
|
|
6
6
|
"agent-context": "./dist/cli.js"
|
|
@@ -11,10 +11,6 @@
|
|
|
11
11
|
"README.md"
|
|
12
12
|
],
|
|
13
13
|
"type": "module",
|
|
14
|
-
"scripts": {
|
|
15
|
-
"build": "tsc -p tsconfig.json",
|
|
16
|
-
"clean": "rm -rf dist node_modules/.cache/.tsbuildinfo"
|
|
17
|
-
},
|
|
18
14
|
"dependencies": {
|
|
19
15
|
"@inquirer/prompts": "^8.3.0",
|
|
20
16
|
"commander": "^14.0.3"
|
package/src/cli.ts
CHANGED
|
@@ -5,6 +5,7 @@ import { readFileSync } from 'node:fs'
|
|
|
5
5
|
import { Command } from 'commander'
|
|
6
6
|
|
|
7
7
|
import { doneCommand } from './commands/done.js'
|
|
8
|
+
import { initCommand } from './commands/init.js'
|
|
8
9
|
import { installCommand } from './commands/install.js'
|
|
9
10
|
import { statusCommand } from './commands/status.js'
|
|
10
11
|
import { syncCommand } from './commands/sync.js'
|
|
@@ -34,6 +35,13 @@ program
|
|
|
34
35
|
.option('--check', '仅检查是否存在待更新内容，不写入文件')
|
|
35
36
|
.action(syncCommand)
|
|
36
37
|
|
|
38
|
+
program
|
|
39
|
+
.command('init')
|
|
40
|
+
.description('初始化 SCOPE（从 git user.name 自动获取或手动指定）')
|
|
41
|
+
.option('--scope <name>', '手动指定 SCOPE 名称')
|
|
42
|
+
.option('--yes', '非交互模式：自动覆盖已存在的 SCOPE')
|
|
43
|
+
.action(initCommand)
|
|
44
|
+
|
|
37
45
|
program.command('validate').description('校验 .agent-context 目录结构').action(validateCommand)
|
|
38
46
|
|
|
39
47
|
program.command('status').description('查看当前 agent-context 状态').action(statusCommand)
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
import { existsSync } from 'node:fs'
|
|
2
|
+
import { readFile, mkdir } from 'node:fs/promises'
|
|
3
|
+
import { join } from 'node:path'
|
|
4
|
+
|
|
5
|
+
import { confirm } from '@inquirer/prompts'
|
|
6
|
+
|
|
7
|
+
import { initScope } from '../context/scope.js'
|
|
8
|
+
|
|
9
|
+
export interface InitCommandOptions {
|
|
10
|
+
scope?: string
|
|
11
|
+
yes?: boolean
|
|
12
|
+
}
|
|
13
|
+
|
|
14
|
+
export async function initCommand(options: InitCommandOptions = {}): Promise<void> {
|
|
15
|
+
const cwd = process.cwd()
|
|
16
|
+
const acRoot = join(cwd, '.agent-context')
|
|
17
|
+
|
|
18
|
+
await mkdir(acRoot, { recursive: true })
|
|
19
|
+
|
|
20
|
+
const envPath = join(acRoot, '.env')
|
|
21
|
+
|
|
22
|
+
if (existsSync(envPath)) {
|
|
23
|
+
const content = await readFile(envPath, 'utf-8')
|
|
24
|
+
const match = content.match(/^SCOPE=(.+)$/m)
|
|
25
|
+
const existing = match?.[1]?.trim()
|
|
26
|
+
|
|
27
|
+
if (existing) {
|
|
28
|
+
console.log(`当前 SCOPE: ${existing}`) // eslint-disable-line no-console
|
|
29
|
+
|
|
30
|
+
if (!options.yes) {
|
|
31
|
+
const overwrite = await confirm({ message: '是否覆盖当前 SCOPE？' })
|
|
32
|
+
if (!overwrite) {
|
|
33
|
+
console.log('已取消') // eslint-disable-line no-console
|
|
34
|
+
return
|
|
35
|
+
}
|
|
36
|
+
}
|
|
37
|
+
}
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
const scope = await initScope(acRoot, options.scope)
|
|
41
|
+
console.log(`✅ SCOPE 已设置: ${scope}`) // eslint-disable-line no-console
|
|
42
|
+
console.log(` 目录: .agent-context/${scope}/`) // eslint-disable-line no-console
|
|
43
|
+
}
|
package/src/commands/status.ts
CHANGED
|
@@ -27,6 +27,7 @@ export async function statusCommand(): Promise<void> {
|
|
|
27
27
|
console.log('')
|
|
28
28
|
console.log('Agent Context Status')
|
|
29
29
|
console.log('────────────────────')
|
|
30
|
+
console.log(`当前作用域: ${ctx.scope}`)
|
|
30
31
|
console.log(`当前计划: ${current}`)
|
|
31
32
|
console.log(`待执行队列: ${preparing}`)
|
|
32
33
|
console.log(`已归档: ${ctx.done.length} 个`)
|
package/src/commands/validate.ts
CHANGED
|
@@ -12,6 +12,7 @@ export async function validateCommand(): Promise<void> {
|
|
|
12
12
|
if (result.valid) {
|
|
13
13
|
console.log('✅ 校验通过')
|
|
14
14
|
const ctx = result.context
|
|
15
|
+
console.log(` 当前作用域: ${ctx.scope}`)
|
|
15
16
|
const current = ctx.currentPlan
|
|
16
17
|
? `plan-${ctx.currentPlan.number} (${ctx.currentPlan.status})`
|
|
17
18
|
: '无'
|
package/src/content/actions.ts
CHANGED
|
@@ -50,7 +50,7 @@ function renderInit(): string {
|
|
|
50
50
|
function renderPlan(): string {
|
|
51
51
|
return `# plan
|
|
52
52
|
|
|
53
|
-
创建新的执行计划，写入 \`.agent-context/plan-{number}/plan.md\`。按复杂度可拆分为多个计划，维护「单当前计划 + preparing 队列」结构。
|
|
53
|
+
创建新的执行计划，写入 \`.agent-context/{scope}/plan-{number}/plan.md\`。按复杂度可拆分为多个计划，维护「单当前计划 + preparing 队列」结构。
|
|
54
54
|
|
|
55
55
|
必须附带计划描述。
|
|
56
56
|
|
|
@@ -58,7 +58,9 @@ function renderPlan(): string {
|
|
|
58
58
|
|
|
59
59
|
- 运行 \`agent-context validate\`，不通过则中止并报告错误。
|
|
60
60
|
- 描述为空 → 拒绝执行。
|
|
61
|
-
- 存在未归档的已执行当前计划 →
|
|
61
|
+
- 存在未归档的已执行当前计划 → 判断新需求与当前计划的关联性：
|
|
62
|
+
- 相关联或用户本意是修补 → 拒绝执行，提示改用 patch。
|
|
63
|
+
- 完全无关 → 拒绝执行，提示先运行 \`agent-context done\` 归档后再创建新计划。
|
|
62
64
|
- 存在多个当前计划 → 拒绝执行，提示恢复单活跃状态。
|
|
63
65
|
|
|
64
66
|
## 执行步骤
|
|
@@ -68,7 +70,7 @@ function renderPlan(): string {
|
|
|
68
70
|
- 存在显著不同的技术路径需用户决策。
|
|
69
71
|
- 验收标准不明确：无法判断何时算"完成"。
|
|
70
72
|
2. 按复杂度决定单计划或多计划拆分。
|
|
71
|
-
3. 多计划拆分时：最小编号进入 \`.agent-context/\` 作为当前计划，其余进入 \`.agent-context/preparing/\`。单计划直接创建。
|
|
73
|
+
3. 多计划拆分时：最小编号进入 \`.agent-context/{scope}/\` 作为当前计划，其余进入 \`.agent-context/{scope}/preparing/\`。单计划直接创建。
|
|
72
74
|
4. 每个计划创建 \`plan.md\`，遵循下方模板。
|
|
73
75
|
5. **自检**（不通过则修改后重新检查）：
|
|
74
76
|
- 每个步骤可独立执行且有明确完成标准。
|
|
@@ -119,9 +121,9 @@ function renderReplan(): string {
|
|
|
119
121
|
|
|
120
122
|
## 作用域
|
|
121
123
|
|
|
122
|
-
- 默认作用域：\`.agent-context/preparing/\` 中全部未实施计划。
|
|
124
|
+
- 默认作用域：\`.agent-context/{scope}/preparing/\` 中全部未实施计划。
|
|
123
125
|
- 可通过描述指定仅重规划部分计划（如"重规划 plan-3 和 plan-5"）。
|
|
124
|
-
- 当前计划为 \`已执行\` → 禁止重写，仅允许重规划 \`preparing/\` 队列。
|
|
126
|
+
- 当前计划为 \`已执行\` → 禁止重写，仅允许重规划 \`{scope}/preparing/\` 队列。
|
|
125
127
|
- 当前计划为 \`未执行\` 且用户明确要求 → 可纳入重规划范围。
|
|
126
128
|
|
|
127
129
|
## 执行步骤
|
|
@@ -137,7 +139,7 @@ function renderReplan(): string {
|
|
|
137
139
|
function renderImplement(): string {
|
|
138
140
|
return `# implement
|
|
139
141
|
|
|
140
|
-
实施当前计划 \`.agent-context/plan-{number}/plan.md\` 中的全部步骤，通过验证循环后将状态更新为「已执行」。
|
|
142
|
+
实施当前计划 \`.agent-context/{scope}/plan-{number}/plan.md\` 中的全部步骤，通过验证循环后将状态更新为「已执行」。
|
|
141
143
|
|
|
142
144
|
不接受额外描述。
|
|
143
145
|
|
|
@@ -165,7 +167,7 @@ function renderImplement(): string {
|
|
|
165
167
|
- **IF** (存在未通过的验证报错、未完成项或遗漏项) **THEN**：修复发现的问题，然后 **GOTO 3.1**（重新检查）。
|
|
166
168
|
- **ELSE IF** (验证全部通过 或 非编码任务验收合格) **THEN**：退出验证循环，即 **GOTO 4** 继续执行。
|
|
167
169
|
4. **更新状态**：将 \`plan.md\` 的状态行修改为 \`> 状态: 已执行\`。
|
|
168
|
-
5. **记录范围**：更新 \`##
|
|
170
|
+
5. **记录范围**：更新 \`## 影响范围\`，详细记录本次变动的具体文件路径。\`.agent-context/\` 目录下的文件不计入影响范围。
|
|
169
171
|
`
|
|
170
172
|
}
|
|
171
173
|
|
|
@@ -193,7 +195,7 @@ function renderPatch(): string {
|
|
|
193
195
|
4. 创建 \`patch-{number}.md\`（编号：扫描当前计划目录已有补丁取 max+1），遵循下方模板。
|
|
194
196
|
5. 回写 \`plan.md\`：
|
|
195
197
|
- \`## 历史补丁\`：追加 \`- patch-{number}: {补丁名称}\`，按编号去重。
|
|
196
|
-
- \`##
|
|
198
|
+
- \`## 影响范围\`：合并本次变更路径，按路径去重。\`.agent-context/\` 目录下的文件不计入影响范围。
|
|
197
199
|
|
|
198
200
|
## patch.md 模板
|
|
199
201
|
|
|
@@ -224,18 +226,23 @@ function renderRush(): string {
|
|
|
224
226
|
|
|
225
227
|
- 运行 \`agent-context validate\`，不通过则中止并报告错误。
|
|
226
228
|
- 描述为空 → 拒绝执行。
|
|
227
|
-
- 存在未归档的已执行当前计划 →
|
|
229
|
+
- 存在未归档的已执行当前计划 → 判断新需求与当前计划的关联性：
|
|
230
|
+
- 相关联或用户本意是修补 → 拒绝执行，提示改用 patch。
|
|
231
|
+
- 完全无关 → 拒绝执行，提示先运行 \`agent-context done\` 归档后再创建新计划。
|
|
228
232
|
- 存在未实施的当前计划 → 拒绝执行，提示先 implement 或 replan。
|
|
229
233
|
|
|
230
234
|
## 执行步骤
|
|
231
235
|
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
236
|
+
> rush = plan + implement 的连续执行，下方仅列出差异点，未提及的步骤按原协议执行。
|
|
237
|
+
|
|
238
|
+
### 阶段一：plan（差异）
|
|
239
|
+
|
|
240
|
+
- 跳过「需求澄清」步骤——rush 要求描述本身已足够明确。
|
|
241
|
+
- 强制单计划，不拆分，不进入 preparing 队列。
|
|
242
|
+
- 完成 plan 后**不等待用户确认**，直接进入阶段二。
|
|
243
|
+
|
|
244
|
+
### 阶段二：implement
|
|
245
|
+
|
|
246
|
+
- 按 \`implement\` 协议**完整执行**（读取计划 → 实施变更 → 验证循环 → 更新状态与影响范围），无任何裁剪。
|
|
240
247
|
`
|
|
241
248
|
}
|
package/src/content/index.ts
CHANGED
|
@@ -27,7 +27,14 @@ function renderNavigator(target: ToolTarget): string {
|
|
|
27
27
|
return `${renderFrontmatter(target)}
|
|
28
28
|
# Agent Context
|
|
29
29
|
|
|
30
|
-
管理项目中的 \`.agent-context/\`
|
|
30
|
+
管理项目中的 \`.agent-context/\` 计划生命周期。匹配用户意图后，**必须先读取对应协议文件的完整内容**，再严格按协议步骤逐项执行。
|
|
31
|
+
|
|
32
|
+
## 执行纪律
|
|
33
|
+
|
|
34
|
+
- **协议先行**：匹配到动作后，必须先读取对应 \`actions/*.md\` 协议文件的完整内容，再逐步执行。禁止凭记忆、摘要或猜测跳过协议步骤。
|
|
35
|
+
- **前置检查必做**：所有动作（done 除外）均包含「前置检查」，必须逐条执行，不可跳过。包括运行 \`agent-context validate\`。
|
|
36
|
+
- **禁止直接改动**：在 plan / rush 创建计划之前，不得直接修改项目代码文件。任何代码变更必须在已创建计划（implement）或已创建补丁（patch）的上下文中进行。
|
|
37
|
+
- **顺序执行**：协议步骤必须按编号顺序逐项执行，不可跳步、合并或并行。
|
|
31
38
|
|
|
32
39
|
## 意图匹配
|
|
33
40
|
|
|
@@ -41,29 +48,35 @@ function renderNavigator(target: ToolTarget): string {
|
|
|
41
48
|
| 无活跃计划时快速出计划并实施 | rush | \`actions/rush.md\` |
|
|
42
49
|
| 任务彻底完成、归档当前计划 | done | 运行 \`agent-context done\` |
|
|
43
50
|
|
|
44
|
-
>
|
|
51
|
+
> **消歧**：存在已执行的当前计划时，用户提出变更需求：
|
|
52
|
+
> - 需求与当前计划**相关联**或用户本意是修补当前计划 → 走 **patch**。
|
|
53
|
+
> - 需求与当前计划**完全无关** → 拒绝执行，提示先运行 \`agent-context done\` 归档当前计划后再创建新计划。
|
|
45
54
|
|
|
46
55
|
## 全局约束
|
|
47
56
|
|
|
48
57
|
- 状态机两态：\`未执行\`、\`已执行\`。
|
|
49
|
-
- 任意时刻最多一个当前计划：\`.agent-context/plan-{number}\`。
|
|
58
|
+
- 任意时刻最多一个当前计划：\`.agent-context/{scope}/plan-{number}\`。
|
|
50
59
|
- 多个当前计划 → 拒绝执行，提示恢复单活跃状态。
|
|
51
60
|
- 计划编号全局递增，不复用。补丁编号在单计划目录内递增，不复用。
|
|
61
|
+
- 影响范围（\`## 影响范围\`）不得包含 \`.agent-context/\` 目录下的文件。
|
|
52
62
|
|
|
53
63
|
## 目录结构
|
|
54
64
|
|
|
55
65
|
\`\`\`text
|
|
56
66
|
.agent-context/
|
|
57
|
-
├──
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
├──
|
|
61
|
-
│
|
|
62
|
-
└──
|
|
63
|
-
|
|
67
|
+
├── .env # SCOPE 配置（SCOPE=<name>）
|
|
68
|
+
├── .gitignore
|
|
69
|
+
└── {scope}/ # 作用域目录（按协作者隔离）
|
|
70
|
+
├── plan-{N}/ # 当前计划（最多一个）
|
|
71
|
+
│ ├── plan.md
|
|
72
|
+
│ └── patch-{N}.md
|
|
73
|
+
├── preparing/ # 待执行计划队列
|
|
74
|
+
│ └── plan-{N}/
|
|
75
|
+
└── done/ # 已归档计划
|
|
76
|
+
└── plan-{N}-{YYYYMMDD}/
|
|
64
77
|
\`\`\`
|
|
65
78
|
|
|
66
|
-
|
|
79
|
+
编号规则：在当前 scope 内扫描全部 \`plan-N\` 目录取 \`max(N)+1\`。
|
|
67
80
|
`
|
|
68
81
|
}
|
|
69
82
|
|
package/src/context/index.ts
CHANGED
package/src/context/reader.ts
CHANGED
|
@@ -3,6 +3,7 @@ import { readdir, readFile } from 'node:fs/promises'
|
|
|
3
3
|
import { join } from 'node:path'
|
|
4
4
|
|
|
5
5
|
import type { ContextSnapshot, PlanInfo, PlanStatus } from '../types.js'
|
|
6
|
+
import { resolveScope } from './scope.js'
|
|
6
7
|
|
|
7
8
|
const PLAN_DIR_RE = /^plan-(\d+)$/
|
|
8
9
|
const DONE_DIR_RE = /^plan-(\d+)(?:-\d{8})?$/
|
|
@@ -19,17 +20,26 @@ export async function readContext(cwd: string): Promise<ContextSnapshot | null>
|
|
|
19
20
|
export async function readRawContext(
|
|
20
21
|
cwd: string
|
|
21
22
|
): Promise<{ snapshot: ContextSnapshot | null; currentPlanCount: number }> {
|
|
22
|
-
const
|
|
23
|
+
const acRoot = join(cwd, '.agent-context')
|
|
23
24
|
|
|
24
|
-
if (!existsSync(
|
|
25
|
+
if (!existsSync(acRoot)) {
|
|
25
26
|
return { snapshot: null, currentPlanCount: 0 }
|
|
26
27
|
}
|
|
27
28
|
|
|
29
|
+
const scope = await resolveScope(acRoot)
|
|
30
|
+
const root = join(acRoot, scope)
|
|
31
|
+
|
|
28
32
|
const currentPlans = await readPlanDirs(root)
|
|
29
33
|
const preparing = await readPlanDirs(join(root, 'preparing'))
|
|
30
34
|
const done = await readDonePlans(join(root, 'done'))
|
|
31
35
|
|
|
32
|
-
const snapshot: ContextSnapshot = {
|
|
36
|
+
const snapshot: ContextSnapshot = {
|
|
37
|
+
root,
|
|
38
|
+
scope,
|
|
39
|
+
currentPlan: currentPlans[0] ?? null,
|
|
40
|
+
preparing,
|
|
41
|
+
done
|
|
42
|
+
}
|
|
33
43
|
|
|
34
44
|
return { snapshot, currentPlanCount: currentPlans.length }
|
|
35
45
|
}
|
|
@@ -0,0 +1,70 @@
|
|
|
1
|
+
import { existsSync } from 'node:fs'
|
|
2
|
+
import { readFile, writeFile, mkdir } from 'node:fs/promises'
|
|
3
|
+
import { join } from 'node:path'
|
|
4
|
+
import { execSync } from 'node:child_process'
|
|
5
|
+
|
|
6
|
+
export async function resolveScope(acRoot: string): Promise<string> {
|
|
7
|
+
const envPath = join(acRoot, '.env')
|
|
8
|
+
|
|
9
|
+
if (existsSync(envPath)) {
|
|
10
|
+
const content = await readFile(envPath, 'utf-8')
|
|
11
|
+
const match = content.match(/^SCOPE=(.+)$/m)
|
|
12
|
+
if (match?.[1]) {
|
|
13
|
+
return match[1].trim()
|
|
14
|
+
}
|
|
15
|
+
}
|
|
16
|
+
|
|
17
|
+
return initScope(acRoot)
|
|
18
|
+
}
|
|
19
|
+
|
|
20
|
+
export async function initScope(acRoot: string, manualScope?: string): Promise<string> {
|
|
21
|
+
let scope: string
|
|
22
|
+
|
|
23
|
+
if (manualScope) {
|
|
24
|
+
scope = normalizeScope(manualScope)
|
|
25
|
+
} else {
|
|
26
|
+
let userName: string
|
|
27
|
+
try {
|
|
28
|
+
userName = execSync('git config user.name', { encoding: 'utf-8' }).trim()
|
|
29
|
+
} catch {
|
|
30
|
+
throw new Error('未找到 git user.name，请先运行 git config user.name <name>')
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
if (!userName) {
|
|
34
|
+
throw new Error('未找到 git user.name，请先运行 git config user.name <name>')
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
scope = normalizeScope(userName)
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
const envPath = join(acRoot, '.env')
|
|
41
|
+
await writeFile(envPath, `SCOPE=${scope}\n`, 'utf-8')
|
|
42
|
+
|
|
43
|
+
await ensureGitignoreHasEnv(acRoot)
|
|
44
|
+
|
|
45
|
+
const scopeDir = join(acRoot, scope)
|
|
46
|
+
await mkdir(scopeDir, { recursive: true })
|
|
47
|
+
|
|
48
|
+
return scope
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
export function normalizeScope(name: string): string {
|
|
52
|
+
return name
|
|
53
|
+
.toLowerCase()
|
|
54
|
+
.replace(/[^a-z0-9]/g, '-')
|
|
55
|
+
.replace(/^-+|-+$/g, '')
|
|
56
|
+
.replace(/-{2,}/g, '-')
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
async function ensureGitignoreHasEnv(acRoot: string): Promise<void> {
|
|
60
|
+
const gitignorePath = join(acRoot, '.gitignore')
|
|
61
|
+
|
|
62
|
+
if (existsSync(gitignorePath)) {
|
|
63
|
+
const content = await readFile(gitignorePath, 'utf-8')
|
|
64
|
+
if (!content.split('\n').some((line) => line.trim() === '.env')) {
|
|
65
|
+
await writeFile(gitignorePath, content.trimEnd() + '\n.env\n', 'utf-8')
|
|
66
|
+
}
|
|
67
|
+
} else {
|
|
68
|
+
await writeFile(gitignorePath, '.env\n', 'utf-8')
|
|
69
|
+
}
|
|
70
|
+
}
|