aigroup-workflow 1.1.0 → 1.1.1

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 (2) hide show
  1. package/README.md +638 -621
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,621 +1,638 @@
1
- # aiGroup - AI 团队协作框架
2
-
3
- > 单入口 AI 团队：一个命令启动，按需自动派遣设计、开发、测试专家。
4
- > 内置门禁式工作流：需求澄清 → 方案设计 → 实现计划 → 子代理开发 → 两阶段审查 → 分支收尾。
5
-
6
- ## 快速开始
7
-
8
- ### 环境要求
9
-
10
- | 依赖 | 最低版本 | 用途 |
11
- |------|---------|------|
12
- | [Claude Code](https://docs.anthropic.com/en/docs/claude-code) | 最新版 | AI Agent 运行时（主要使用方式） |
13
- | [Cursor](https://cursor.com) | 最新版 | AI IDE（可选，替代使用方式） |
14
- | Git | 2.x | 版本控制 |
15
- | Bash | 4.x+ | Harness 传感器脚本（Windows 用户可用 Git Bash） |
16
-
17
- ### 安装
18
-
19
- ```bash
20
- # 方式一：作为独立框架使用
21
- git clone https://github.com/codeApe-7/ai-agent-workflowGroup.git
22
- cd ai-agent-workflowGroup
23
-
24
- # 方式二：集成到已有项目（只复制框架文件）
25
- # 详见下方"集成到已有项目"章节
26
- ```
27
-
28
- ### 启动
29
-
30
- **Claude Code 中使用（推荐）：**
31
-
32
- ```bash
33
- cd ai-agent-workflowGroup
34
- claude
35
- ```
36
-
37
- 启动后 Max 自动就位，读取 `CLAUDE.md` 作为入口，根据你的需求驱动整个团队。
38
-
39
- **Cursor 中使用：**
40
-
41
- 直接用 Cursor 打开项目目录，Agent 会自动读取 `CLAUDE.md` 获取框架规则。
42
-
43
- ### 三种使用模式
44
-
45
- **模式一：完整管道（复杂任务）**
46
-
47
- 直接描述需求，Max 自动驱动完整管道：
48
-
49
- ```
50
- 你: 帮我做一个用户认证系统
51
- → Max 启动 brainstorming，逐步澄清需求
52
- → Max 产出实现计划，用户确认
53
- → Max 派遣 Jarvis 逐任务开发，Kyle 两阶段审查
54
- → Max 收尾集成
55
- ```
56
-
57
- **模式二：斜杠命令直接派遣（明确任务）**
58
-
59
- 跳过 Max 调度，直接派遣指定成员：
60
-
61
- ```
62
- /ella 设计一个登录页面 # 直接派遣设计师
63
- /jarvis 实现用户认证 API # 直接派遣开发
64
- /kyle 审查用户模块代码 # 直接派遣质量保障
65
- ```
66
-
67
- **模式三：简单问答（轻量任务）**
68
-
69
- 不涉及设计决策的简单问题，Max 直接回答：
70
-
71
- ```
72
- 你: 这个项目用的什么技术栈？
73
- → Max 直接回答，不启动管道
74
- ```
75
-
76
- 判断标准：涉及 2 个以上文件或需要设计决策 → 走完整管道。
77
-
78
- ## 团队成员
79
-
80
- | 成员 | 角色 | 负责什么 | 不负责什么 |
81
- |------------------|---------------|----------------------------------|--------------------|
82
- | 麦克斯 (Max) | 项目经理 | 需求分析、任务拆解、进度协调 | 写代码、做设计、做测试 |
83
- | 艾拉 (Ella) | UI/UX 设计师 | 界面设计、交互原型、设计规范 | 写代码、做测试 |
84
- | 贾维斯 (Jarvis) | 全栈开发 | 前后端编码、API、技术方案 | 做设计、做测试验收 |
85
- | 凯尔 (Kyle) | 质量保障 | 代码审查、功能验收、安全审计 | 写代码、做设计 |
86
-
87
- ## 工作流程
88
-
89
- ### 总体协作流程
90
-
91
- ```mermaid
92
- flowchart TD
93
- User(["用户提出需求"]) --> Max{"Max 分析需求类型"}
94
- Max -->|设计类| Ella["Ella 设计师"]
95
- Max -->|开发类| Jarvis["Jarvis 开发"]
96
- Max -->|测试/审查| Kyle["Kyle 质量保障"]
97
- Max -->|简单问题| Direct["Max 直接回答"]
98
-
99
- Ella -->|设计稿| D1["shared/designs/"]
100
- Jarvis -->|代码实现| D2["项目代码"]
101
- Kyle -->|审查报告| D3["shared/reviews/"]
102
-
103
- D1 --> Summary["Max 汇总结果"]
104
- D2 --> Summary
105
- D3 --> Summary
106
- Direct --> Summary
107
- Summary --> Done(["反馈给用户"])
108
- ```
109
-
110
- ### 任务派遣决策流程
111
-
112
- ```mermaid
113
- flowchart TD
114
- Input(["用户输入"]) --> Parse["Max 解析需求"]
115
- Parse --> Classify{"需求分类"}
116
-
117
- Classify -->|"界面/交互/视觉"| Design["设计需求"]
118
- Classify -->|"编码/功能/API/修复"| Dev["开发需求"]
119
- Classify -->|"审查/验收/测试"| QA["质量需求"]
120
- Classify -->|"咨询/解释"| Simple["简单问题"]
121
-
122
- Design --> Clarify1{"需求清晰?"}
123
- Clarify1 -->|否| Ask1["追问澄清"] --> Clarify1
124
- Clarify1 -->|是| GoElla["派遣 Ella"]
125
-
126
- Dev --> Clarify2{"需求清晰?"}
127
- Clarify2 -->|否| Ask2["追问澄清"] --> Clarify2
128
- Clarify2 -->|是| HasDesign{"有设计稿?"}
129
- HasDesign -->|是| GoJarvis1["派遣 Jarvis + 设计稿路径"]
130
- HasDesign -->|否| GoJarvis2["派遣 Jarvis + 技术上下文"]
131
-
132
- QA --> GoKyle["派遣 Kyle + 代码路径"]
133
- Simple --> MaxAnswer["Max 直接回答"]
134
- ```
135
-
136
- ### 完整流水线
137
-
138
- ```mermaid
139
- sequenceDiagram
140
- participant User
141
- participant Max
142
- participant Ella
143
- participant Jarvis
144
- participant Kyle
145
- participant Shared
146
-
147
- User->>Max: 提出需求
148
- Max->>Max: 分析并拆解任务
149
-
150
- Note over Max,Ella: 阶段一 设计
151
- Max->>Ella: 派遣设计任务
152
- Ella->>Shared: 输出设计稿
153
- Ella-->>Max: 设计完成
154
- Max-->>User: 需要开发吗
155
-
156
- User->>Max: 确认开发
157
-
158
- Note over Max,Jarvis: 阶段二 开发
159
- Max->>Jarvis: 派遣开发任务+设计稿路径
160
- Jarvis->>Shared: 读取设计稿
161
- Jarvis->>Jarvis: 实现代码
162
- Jarvis-->>Max: 开发完成
163
- Max-->>User: 需要验收吗
164
-
165
- User->>Max: 确认验收
166
-
167
- Note over Max,Kyle: 阶段三 验收
168
- Max->>Kyle: 派遣验收任务+代码路径
169
- Kyle->>Kyle: 代码审查+功能验收
170
- Kyle->>Shared: 输出审查报告
171
- Kyle-->>Max: 验收完成
172
-
173
- Max-->>User: 汇总全流程结果
174
- ```
175
-
176
- ### 上下文传递机制
177
-
178
- ```mermaid
179
- flowchart LR
180
- subgraph CTX["独立上下文窗口"]
181
- MaxCtx["Max\nRules 注入"]
182
- EllaCtx["Ella\n独立窗口"]
183
- JarvisCtx["Jarvis\n独立窗口"]
184
- KyleCtx["Kyle\n独立窗口"]
185
- end
186
-
187
- subgraph SHARED["共享产物目录"]
188
- Tasks[("tasks/")]
189
- Designs[("designs/")]
190
- Reviews[("reviews/")]
191
- end
192
-
193
- MaxCtx -->|"派遣注入\n需求+产物路径"| EllaCtx
194
- MaxCtx -->|"派遣注入\n需求+设计稿路径"| JarvisCtx
195
- MaxCtx -->|"派遣注入\n代码路径+需求"| KyleCtx
196
-
197
- EllaCtx -->|写入设计稿| Designs
198
- JarvisCtx -->|读取设计稿| Designs
199
- KyleCtx -->|写入审查报告| Reviews
200
- MaxCtx -->|写入任务文档| Tasks
201
-
202
- style MaxCtx fill:#4A90D9,color:#fff
203
- style EllaCtx fill:#E91E63,color:#fff
204
- style JarvisCtx fill:#4CAF50,color:#fff
205
- style KyleCtx fill:#FF9800,color:#fff
206
- ```
207
-
208
- > **关键规则**：子 Agent 之间不能直接通信，所有上下文由 Max 在派遣时注入，跨 Agent 协作通过 `.dev-agents/shared/` 目录下的文件实现。
209
-
210
- ### 并行与串行
211
-
212
- ```mermaid
213
- flowchart TD
214
- User(["用户: 多个任务"]) --> Max["Max 分析"]
215
- Max --> Check{"任务间有依赖?"}
216
-
217
- Check -->|无依赖| Parallel["并行派遣"]
218
- Parallel --> P1["Ella: 设计登录页"]
219
- Parallel --> P2["Jarvis: 开发后端 API"]
220
- P1 --> Merge["Max 汇总"]
221
- P2 --> Merge
222
-
223
- Check -->|有依赖| Sequential["串行执行"]
224
- Sequential --> S1["先: Ella 出设计稿"]
225
- S1 --> S2["后: Jarvis 按稿开发"]
226
- S2 --> Merge2["Max 汇总"]
227
- ```
228
-
229
- ## 工作流技能（门禁式管道）
230
-
231
- 受 [Superpowers](https://github.com/obra/superpowers) 和 [Harness Engineering](https://martinfowler.com/articles/harness-engineering.html) 启发，aiGroup 内置 7 个工作流技能，形成严格的门禁管道——每个环节必须完成才能进入下一步：
232
-
233
- ```
234
- brainstorming → writing-plans → subagent-driven-development → finishing-a-development-branch
235
- ↑ ↑
236
- systematic-debugging verification-before-completion
237
- （遇 Bug 时触发） （任何完成声明前触发）
238
- ↑
239
- entropy-management
240
- （定期维护触发）
241
- ```
242
-
243
- | 技能 | 触发时机 | 核心规则 |
244
- |------|---------|---------|
245
- | **brainstorming** | 任何创造性工作之前 | 一次一个问题、2-3 方案对比、用户批准后才能继续 |
246
- | **writing-plans** | 有设计方案后、编码前 | 任务粒度 2-5 分钟、禁止占位符、每步有完整代码 |
247
- | **subagent-driven-development** | 有计划后、开发执行 | 每任务新子代理、两阶段审查（先规格后质量） |
248
- | **systematic-debugging** | 遇到 Bug/测试失败 | 四阶段根因分析、3 次失败后质疑架构 |
249
- | **verification-before-completion** | 声称完成/通过之前 | 无验证证据不得声明完成 |
250
- | **finishing-a-development-branch** | 所有任务完成后 | 全量测试 → 四选一集成方式 → 清理 |
251
- | **entropy-management** | 定期维护/漂移信号 | 传感器扫描 → 推理检查 → 修复 → 更新质量评分 |
252
-
253
- ### 两阶段审查
254
-
255
- 每次 Jarvis 完成开发后，Kyle 按严格顺序执行：
256
-
257
- 1. **Stage 1：规格符合性** — 多了什么？少了什么？偏离了什么？
258
- 2. **Stage 2：代码质量** — 干净、安全、可维护？
259
-
260
- Stage 1 不通过 → 修复 → 重审 Stage 1 → 通过后才进入 Stage 2
261
-
262
- ### 三条铁律
263
-
264
- ```
265
- 1. 证据优于断言 — 任何完成声明必须附带验证证据
266
- 2. 流程不可跳过 — 工作流管道的每个环节必须走完
267
- 3. 不确定时先问 — 宁可多问一句，不要假设
268
- ```
269
-
270
- ## 使用示例
271
-
272
- ### 示例 1：完整功能开发
273
-
274
- ```
275
- 你: 帮我做一个用户认证系统
276
-
277
- Max: [启动 brainstorming] → 逐个提问澄清需求 → 展示设计方案 → 用户批准
278
- Max: [启动 writing-plans] → 产出分步实现计划 → 用户确认
279
- Max: [启动 subagent-driven-development]
280
- → 派遣 Jarvis 执行任务 1 → Kyle Stage 1 审查 → Kyle Stage 2 审查
281
- → 派遣 Jarvis 执行任务 2 → Kyle Stage 1 审查 → Kyle Stage 2 审查
282
- → ...
283
- Max: [启动 finishing-a-development-branch] → 全量测试 → 用户选择集成方式
284
- ```
285
-
286
- ### 示例 2：直接派遣设计
287
-
288
- ```
289
- /ella 设计一个电商首页，风格参考 Apple Store，需要有 hero banner、商品分类、推荐列表
290
-
291
- → Ella 读取 PERSONA 和 ui-ux-pro-max 技能
292
- → 产出设计稿到 .dev-agents/shared/designs/ecommerce-home.md
293
- → 返回：设计稿路径 + 设计决策摘要 + 实现注意事项
294
- ```
295
-
296
- ### 示例 3：代码审查
297
-
298
- ```
299
- /kyle 审查 src/auth/ 目录下的认证模块代码，对照实现计划 .dev-agents/shared/tasks/auth-plan.md
300
-
301
- → Kyle 读取实现计划和代码
302
- → Stage 1：逐条检查规格符合性
303
- → Stage 2：检查代码质量、安全性、可维护性
304
- → 产出审查报告到 .dev-agents/shared/reviews/auth-review.md
305
- ```
306
-
307
- ### 示例 4：Bug 调试
308
-
309
- ```
310
- 你: 用户登录后 token 刷新失败，返回 401
311
-
312
- → Max 检测到 Bug 信号，启动 systematic-debugging
313
- → 派遣 Jarvis 执行四阶段根因调查
314
- → 第一阶段：阅读错误信息、稳定复现
315
- → 第二阶段：找到可工作示例，对照差异
316
- → 第三阶段：假设验证（一次一个变量）
317
- → 第四阶段：创建失败测试 → 修复 → 验证
318
- ```
319
-
320
- ### 示例 5：Harness 健康检查
321
-
322
- ```
323
- 你: 跑一下项目健康检查
324
-
325
- → Max 启动 entropy-management 技能
326
- → 第一阶段：运行 scripts/harness/run-all.sh 自动化扫描
327
- → 第二阶段：推理型扫描（文档一致性、架构漂移）
328
- → 第三阶段：修复问题 + 将重复问题编码为约束
329
- → 第四阶段：更新 docs/QUALITY_SCORE.md 和 docs/tech-debt-tracker.md
330
- ```
331
-
332
- ## 集成到已有项目
333
-
334
- aiGroup 可以作为"脚手架"集成到你的任何项目中。
335
-
336
- ### 步骤 1：复制框架文件
337
-
338
- 将以下目录和文件复制到你的项目根目录：
339
-
340
- ```bash
341
- # 必须复制
342
- CLAUDE.md # Agent 入口
343
- docs/ # 知识库
344
- .claude/ # Claude Code 配置（commands/ + hooks.json + settings.json）
345
- .dev-agents/ # 角色定义 + 协作产物目录
346
- scripts/harness/ # Harness 传感器
347
-
348
- # 按需复制
349
- skills/max/workflow/ # 工作流技能（强烈推荐）
350
- skills/ella/ # 设计技能（如果需要 UI 设计）
351
- skills/jarvis/ # 开发技能（如果需要工程团队技能集）
352
- skills/kyle/ # QA 技能（如果需要质量保障）
353
- ```
354
-
355
- ### 步骤 2：适配你的项目
356
-
357
- 1. **编辑 `CLAUDE.md`**：不需要大改，只需确认知识库地图路径正确
358
- 2. **编辑 `docs/ARCHITECTURE.md`**：替换为你项目的架构描述
359
- 3. **编辑 `docs/coding-standards.md`**：替换为你项目的编码规范
360
- 4. **编辑 `.dev-agents/*/PERSONA.md`**：根据需要调整角色定义
361
-
362
- ### 步骤 3：更新 .gitignore
363
-
364
- 确保 `docs/` 不被忽略（框架已自动处理），协作产物按需忽略：
365
-
366
- ```gitignore
367
- # 子项目文档目录（不影响根目录 docs/ 知识库）
368
- **/docs/
369
- !/docs/
370
-
371
- # shared 目录：保留框架，忽略具体产出内容
372
- .dev-agents/shared/tasks/*.md
373
- .dev-agents/shared/designs/*.md
374
- .dev-agents/shared/reviews/*.md
375
- ```
376
-
377
- ### 步骤 4：验证安装
378
-
379
- ```bash
380
- bash scripts/harness/run-all.sh
381
- ```
382
-
383
- 所有检查通过即可开始使用。
384
-
385
- ## 常用命令速查
386
-
387
- ### 日常使用
388
-
389
- | 命令 | 说明 | 使用场景 |
390
- |------|------|---------|
391
- | `claude` | 启动 Claude Code + Max | 开始工作 |
392
- | `/ella <任务>` | 直接派遣设计师 | 界面设计、交互原型 |
393
- | `/jarvis <任务>` | 直接派遣开发 | 编码、技术方案、Bug 修复 |
394
- | `/kyle <任务>` | 直接派遣质量保障 | 代码审查、功能验收 |
395
-
396
- ### Harness 维护
397
-
398
- | 命令 | 说明 | 建议频率 |
399
- |------|------|---------|
400
- | `bash scripts/harness/run-all.sh` | 全量 Harness 传感器检查 | 每次开发完成后 |
401
- | `bash scripts/update-skills.sh all` | 更新所有远程技能 | 每周一次 |
402
- | `bash scripts/check-gitignore.sh` | 检查 .gitignore 规则 | 添加新文件类型时 |
403
- | `bash scripts/clean-system-files.sh` | 清理 .DS_Store 等系统文件 | 偶尔运行 |
404
-
405
- > Windows 用户：用 Git Bash 运行以上命令（`"D:\Git\bin\bash.exe" scripts/harness/run-all.sh`）。
406
-
407
- ### 自定义与扩展
408
-
409
- | 想要做 | 修改什么 |
410
- |--------|---------|
411
- | 调整 Agent 角色定义 | `.dev-agents/{name}/PERSONA.md` |
412
- | 修改工作流规则 | `skills/max/workflow/{skill}/SKILL.md` |
413
- | 添加新的编码规范 | `docs/coding-standards.md` |
414
- | 添加新的传感器检查 | `scripts/harness/lint-*.sh` 中添加检查项 |
415
- | 添加新的危险信号 | `docs/red-flags.md` 中添加条目 |
416
- | 将重复问题编码为约束 | 遵循 `docs/steering-loop.md` 转向循环流程 |
417
- | 添加新的 Hook | `.claude/hooks.json` 中添加事件 |
418
- | 修改权限控制 | `.claude/settings.json` 中调整 allow/deny |
419
- | 添加新团队成员 | 新建 `.dev-agents/{name}/PERSONA.md` + `.claude/commands/{name}.md` |
420
-
421
- ## 项目结构
422
-
423
- ```
424
- agentGroup/
425
- ├── CLAUDE.md # Agent 入口：全局地图（< 100 行，目录式）
426
- ├── docs/ # 知识库（唯一事实源）
427
- │ ├── README.md # 知识库索引
428
- │ ├── ARCHITECTURE.md # 项目架构总览
429
- │ ├── workflow-pipeline.md # 工作流管道详细规则
430
- │ ├── dispatch-rules.md # 派遣规则与上下文传递
431
- │ ├── coding-standards.md # 编码与 Git 规范
432
- │ ├── red-flags.md # 危险信号检测
433
- │ ├── QUALITY_SCORE.md # 质量评分追踪
434
- │ ├── tech-debt-tracker.md # 技术债追踪
435
- │ └── steering-loop.md # Harness 转向循环
436
- ├── .claude/ # Claude Code 原生配置
437
- │ ├── settings.json # 项目级权限设置
438
- │ ├── hooks.json # Harness 生命周期 Hooks
439
- │ └── commands/ # 斜杠命令
440
- │ ├── ella.md # /ella 派遣设计师
441
- │ ├── jarvis.md # /jarvis 派遣开发
442
- │ └── kyle.md # /kyle 派遣质量保障
443
- ├── .dev-agents/ # 角色定义 + 协作产物
444
- │ ├── ella/PERSONA.md # 艾拉角色定义
445
- │ ├── jarvis/PERSONA.md # 贾维斯角色定义
446
- │ ├── kyle/PERSONA.md # 凯尔角色定义
447
- │ └── shared/ # 协作产物
448
- │ ├── tasks/ # 实现计划（writing-plans 产出）
449
- │ ├── designs/ # 设计方案和设计稿
450
- │ ├── reviews/ # 审查报告
451
- │ └── templates/ # 文档模板（PRD/API/Bug/实现计划/审查报告）
452
- ├── skills/ # 技能资源（按角色分组）
453
- │ ├── ella/ # 设计技能
454
- │ │ ├── ui-ux-pro-max/ # 50+ 设计风格、97 色彩方案
455
- │ │ ├── senior-frontend/ # 前端最佳实践
456
- │ │ └── commands/ # 设计工具命令
457
- │ ├── jarvis/ # 开发技能
458
- │ │ ├── claude-simone/ # 开发框架方法论
459
- │ │ └── engineering-team/ # 205+ 工程技能集（见下表）
460
- │ ├── kyle/ # 测试技能
461
- │ │ ├── senior-qa/ # QA 最佳实践
462
- │ │ └── tdd-guide/ # TDD 指南
463
- │ └── max/ # 管理技能
464
- │ ├── ccpm/ # 关键链项目管理
465
- │ ├── pm-claude-skills/ # PM 技能集
466
- │ └── workflow/ # 工作流技能（7 个门禁技能）
467
- │ ├── brainstorming/
468
- │ ├── writing-plans/
469
- │ ├── subagent-driven-development/
470
- │ ├── systematic-debugging/
471
- │ ├── verification-before-completion/
472
- │ ├── finishing-a-development-branch/
473
- │ └── entropy-management/ # 熵管理/垃圾回收
474
- ├── scripts/ # 自动化脚本
475
- │ ├── harness/ # Harness 传感器套件
476
- │ │ ├── run-all.sh # 全量传感器运行器
477
- │ │ ├── lint-structure.sh # 结构检查
478
- │ │ ├── lint-docs.sh # 文档新鲜度检查
479
- │ │ ├── lint-workflow-artifacts.sh # 工作流产物检查
480
- │ │ ├── hook-post-edit.sh # PostToolUse Hook
481
- │ │ ├── hook-stop.sh # Stop Hook（back-pressure）
482
- │ │ └── hook-subagent-stop.sh # SubagentStop Hook
483
- │ ├── update-skills.sh # 技能更新（支持镜像加速）
484
- │ ├── check-gitignore.sh # .gitignore 规则检查
485
- │ └── clean-system-files.sh # 系统文件清理
486
- └── README.md
487
- ```
488
-
489
- ## 技能体系
490
-
491
- ### 技能与角色对应
492
-
493
- ```mermaid
494
- flowchart TB
495
- subgraph MAX["Max 项目经理"]
496
- M1["ccpm\n关键链项目管理"]
497
- M2["pm-claude-skills\nPM 技能集"]
498
- M3["workflow\n7 个门禁工作流技能"]
499
- end
500
-
501
- subgraph ELLA["Ella 设计师"]
502
- E1["ui-ux-pro-max\n50+ 设计风格"]
503
- E2["senior-frontend\n前端最佳实践"]
504
- end
505
-
506
- subgraph JARVIS["Jarvis 开发"]
507
- J1["claude-simone\n开发框架"]
508
- J2["engineering-team\n205+ 工程技能"]
509
- end
510
-
511
- subgraph KYLE["Kyle 质量保障"]
512
- K1["senior-qa\nQA 最佳实践"]
513
- K2["tdd-guide\nTDD 指南"]
514
- end
515
- ```
516
-
517
- ### Engineering Team 技能清单（205+ 技能）
518
-
519
- 更新 engineering-team 后，贾维斯获得了 9 大领域的技能支持：
520
-
521
- | 领域 | 技能数 | 核心技能 |
522
- |--------------------|--------|----------------------------------------------------------------|
523
- | 核心工程 | 29 | senior-architect, senior-fullstack, senior-frontend, senior-backend, senior-devops, code-reviewer, tdd-guide, a11y-audit, playwright-pro, epic-design |
524
- | 高级工程 (POWERFUL) | 30 | agent-designer, rag-architect, mcp-server-builder, ci-cd-pipeline-builder, database-designer, observability-designer |
525
- | 产品团队 | 13 | RICE 评分, OKR 规划, 用户故事, SaaS 脚手架, 落地页生成器 |
526
- | 营销技能 | 43 | 内容创作, SEO, ASO, 需求生成, 品牌声音, 竞品分析 |
527
- | 项目管理 | 6 | Jira/Confluence 集成, CCPM, Sprint 规划 |
528
- | C-Level 顾问 | 28 | CEO/CTO 战略决策, 组织架构, OKR 战略 |
529
- | 合规质量 (RA/QM) | 12 | ISO 13485, FDA, GDPR, ISO 27001 |
530
- | 商业增长 | 4 | 客户成功, 销售工程, 收入运营 |
531
- | 财务分析 | 2 | DCF 估值, SaaS 指标, 预算编制 |
532
-
533
- 附带 **268 个 Python 自动化工具** 和 **384 份参考指南**。
534
-
535
- ## 技能来源与更新
536
-
537
- | 技能 | 来源 | 许可证 | 更新方式 |
538
- |-------------------|--------------------------------------------------------------------------------------|----------|----------|
539
- | 工作流技能 (7个) | 原创，受 [obra/superpowers](https://github.com/obra/superpowers) 和 [Harness Engineering](https://martinfowler.com/articles/harness-engineering.html) 启发 | MIT | 内置 |
540
- | CCPM 项目管理 | [automazeio/ccpm](https://github.com/automazeio/ccpm) | MIT | 脚本自动 |
541
- | PM Claude Skills | [mohitagw15856/pm-claude-skills](https://github.com/mohitagw15856/pm-claude-skills) | MIT | 脚本自动 |
542
- | Claude Simone | [Helmi/claude-simone](https://github.com/Helmi/claude-simone) | 见原仓库 | 脚本自动 |
543
- | Engineering Team | [alirezarezvani/claude-skills](https://github.com/alirezarezvani/claude-skills) | 见原仓库 | 脚本自动 |
544
- | UI/UX Pro Max | SkillsMP 技能市场 | MIT | 手动下载 |
545
- | Senior Frontend | SkillsMP 技能市场 | MIT | 手动下载 |
546
- | Senior QA / TDD | SkillsMP 技能市场 | MIT | 手动下载 |
547
-
548
- ### 更新 Skills
549
-
550
- ```bash
551
- bash scripts/update-skills.sh all # 更新所有 GitHub 来源
552
- bash scripts/update-skills.sh ccpm # 只更新 CCPM
553
- bash scripts/update-skills.sh pm # 只更新 PM Skills
554
- bash scripts/update-skills.sh simone # 只更新 Claude Simone
555
- bash scripts/update-skills.sh engineering # 只更新 Engineering Team
556
- bash scripts/update-skills.sh manual # 显示需手动更新的技能
557
- ```
558
-
559
- > 直连 GitHub 失败时脚本自动切换镜像加速（ghfast.top / ghproxy）。
560
-
561
- ## Harness Engineering 体系
562
-
563
- aiGroup 采用 [Harness Engineering](https://martinfowler.com/articles/harness-engineering.html) 理念，通过约束、反馈回路和持续改进循环提升 Agent 可靠性。
564
-
565
- ### 核心公式
566
-
567
- ```
568
- Agent = Model + Harness
569
- ```
570
-
571
- 不优化模型本身，而是优化模型运行的环境。
572
-
573
- ### 四层防线
574
-
575
- | 层级 | 机制 | 实现 |
576
- |------|------|------|
577
- | **前馈引导** | 在 Agent 行动前引导方向 | CLAUDE.md 地图、Skills 渐进披露、工作流管道 |
578
- | **计算型反馈** | 确定性检查，快速自动运行 | `scripts/harness/` 传感器套件 + Claude Code Hooks |
579
- | **推理型反馈** | AI 语义审查 | Kyle 两阶段审查（规格符合性 + 代码质量） |
580
- | **熵管理** | 防止长期退化 | entropy-management 技能 + 质量评分追踪 |
581
-
582
- ### Harness 传感器
583
-
584
- ```bash
585
- bash scripts/harness/run-all.sh # 全量检查
586
- ```
587
-
588
- 传感器输出对 Agent 友好：`[PASS]` 通过、`[FAIL]` 失败 + `[FIX]` 修复指令。
589
-
590
- ### 转向循环
591
-
592
- ```
593
- 发现重复问题 → 编码为约束（Linter/文档/技能）→ 自动执行 → 更新质量评分
594
- ```
595
-
596
- 详见 `docs/steering-loop.md`。
597
-
598
- ### 知识库
599
-
600
- 所有规范、架构决策、质量追踪均版本化存储在 `docs/` 目录下，作为项目的唯一事实源。
601
- CLAUDE.md 仅作为地图入口（< 100 行），详细内容按需从 `docs/` 检索。
602
-
603
- ## 致谢
604
-
605
- 本项目基于 [yezannnnn/agentGroup](https://github.com/yezannnnn/agentGroup) 进行开发和扩展。感谢原作者 [@yezannnnn](https://github.com/yezannnnn) 提出的四 AI 专业分工协作框架理念，为本项目奠定了坚实的基础。
606
-
607
- ## 社区支持
608
-
609
- <div align="center">
610
-
611
- **学 AI，上 L 站**
612
-
613
- [![LINUX DO](https://img.shields.io/badge/LINUX%20DO-社区-gray?style=flat-square)](https://linux.do/) [![社区支持](https://img.shields.io/badge/社区支持-交流-blue?style=flat-square)](https://linux.do/)
614
-
615
- 本项目在 [LINUX DO](https://linux.do/) 社区发布与交流，感谢佬友们的支持与反馈。
616
-
617
- </div>
618
-
619
- ## 许可证
620
-
621
- MIT License
1
+ # aiGroup - AI 团队协作框架
2
+
3
+ > 单入口 AI 团队：一个命令启动，按需自动派遣设计、开发、测试专家。
4
+ > 内置门禁式工作流：需求澄清 → 方案设计 → 实现计划 → 子代理开发 → 两阶段审查 → 分支收尾。
5
+
6
+ ## 快速开始
7
+
8
+ ### 环境要求
9
+
10
+ | 依赖 | 最低版本 | 用途 |
11
+ |------|---------|------|
12
+ | [Claude Code](https://docs.anthropic.com/en/docs/claude-code) | 最新版 | AI Agent 运行时（主要使用方式） |
13
+ | [Cursor](https://cursor.com) | 最新版 | AI IDE（可选，替代使用方式） |
14
+ | Node.js | 18+ | CLI 工具运行 |
15
+ | Git | 2.x | 版本控制 |
16
+ | Bash | 4.x+ | Harness 传感器脚本（Windows 用户可用 Git Bash） |
17
+
18
+ ### 安装
19
+
20
+ ```bash
21
+ # 方式一：通过 npm 安装 CLI（推荐）
22
+ npm install -g aigroup-workflow
23
+ aigroup init
24
+
25
+ # 方式二：npx 免安装使用
26
+ npx aigroup-workflow init
27
+
28
+ # 方式三：克隆仓库
29
+ git clone https://github.com/codeApe-7/ai-agent-workflowGroup.git
30
+ cd ai-agent-workflowGroup
31
+ ```
32
+
33
+ ### CLI 命令
34
+
35
+ ```bash
36
+ aigroup init # 交互式初始化（选择角色、安装技能和配置）
37
+ aigroup update # 增量更新（只更新技能和传感器，不覆盖自定义）
38
+ aigroup check # 运行 Harness 健康检查
39
+ aigroup status # 查看工作流状态
40
+ aigroup init --yes # 跳过确认，使用默认配置
41
+ ```
42
+
43
+ `init` 命令支持交互式多选：使用 **方向键** 移动光标，**空格** 切换选中角色，**回车** 确认。
44
+
45
+ ### 启动
46
+
47
+ **Claude Code 中使用（推荐）：**
48
+
49
+ ```bash
50
+ cd your-project
51
+ claude
52
+ ```
53
+
54
+ 启动后 Max 自动就位，读取 `CLAUDE.md` 作为入口，根据你的需求驱动整个团队。
55
+
56
+ **Cursor 中使用：**
57
+
58
+ 直接用 Cursor 打开项目目录，Agent 会自动读取 `CLAUDE.md` 获取框架规则。
59
+
60
+ ### 三种使用模式
61
+
62
+ **模式一：完整管道（复杂任务）**
63
+
64
+ 直接描述需求，Max 自动驱动完整管道：
65
+
66
+ ```
67
+ 你: 帮我做一个用户认证系统
68
+ → Max 启动 brainstorming，逐步澄清需求
69
+ → Max 产出实现计划，用户确认
70
+ → Max 派遣 Jarvis 逐任务开发，Kyle 两阶段审查
71
+ → Max 收尾集成
72
+ ```
73
+
74
+ **模式二：斜杠命令直接派遣（明确任务）**
75
+
76
+ 跳过 Max 调度，直接派遣指定成员：
77
+
78
+ ```
79
+ /ella 设计一个登录页面 # 直接派遣设计师
80
+ /jarvis 实现用户认证 API # 直接派遣开发
81
+ /kyle 审查用户模块代码 # 直接派遣质量保障
82
+ ```
83
+
84
+ **模式三：简单问答（轻量任务）**
85
+
86
+ 不涉及设计决策的简单问题，Max 直接回答：
87
+
88
+ ```
89
+ 你: 这个项目用的什么技术栈？
90
+ → Max 直接回答，不启动管道
91
+ ```
92
+
93
+ 判断标准：涉及 2 个以上文件或需要设计决策 → 走完整管道。
94
+
95
+ ## 团队成员
96
+
97
+ | 成员 | 角色 | 负责什么 | 不负责什么 |
98
+ |------------------|---------------|----------------------------------|--------------------|
99
+ | 麦克斯 (Max) | 项目经理 | 需求分析、任务拆解、进度协调 | 写代码、做设计、做测试 |
100
+ | 艾拉 (Ella) | UI/UX 设计师 | 界面设计、交互原型、设计规范 | 写代码、做测试 |
101
+ | 贾维斯 (Jarvis) | 全栈开发 | 前后端编码、API、技术方案 | 做设计、做测试验收 |
102
+ | 凯尔 (Kyle) | 质量保障 | 代码审查、功能验收、安全审计 | 写代码、做设计 |
103
+
104
+ ## 工作流程
105
+
106
+ ### 总体协作流程
107
+
108
+ ```mermaid
109
+ flowchart TD
110
+ User(["用户提出需求"]) --> Max{"Max 分析需求类型"}
111
+ Max -->|设计类| Ella["Ella 设计师"]
112
+ Max -->|开发类| Jarvis["Jarvis 开发"]
113
+ Max -->|测试/审查| Kyle["Kyle 质量保障"]
114
+ Max -->|简单问题| Direct["Max 直接回答"]
115
+
116
+ Ella -->|设计稿| D1["shared/designs/"]
117
+ Jarvis -->|代码实现| D2["项目代码"]
118
+ Kyle -->|审查报告| D3["shared/reviews/"]
119
+
120
+ D1 --> Summary["Max 汇总结果"]
121
+ D2 --> Summary
122
+ D3 --> Summary
123
+ Direct --> Summary
124
+ Summary --> Done(["反馈给用户"])
125
+ ```
126
+
127
+ ### 任务派遣决策流程
128
+
129
+ ```mermaid
130
+ flowchart TD
131
+ Input(["用户输入"]) --> Parse["Max 解析需求"]
132
+ Parse --> Classify{"需求分类"}
133
+
134
+ Classify -->|"界面/交互/视觉"| Design["设计需求"]
135
+ Classify -->|"编码/功能/API/修复"| Dev["开发需求"]
136
+ Classify -->|"审查/验收/测试"| QA["质量需求"]
137
+ Classify -->|"咨询/解释"| Simple["简单问题"]
138
+
139
+ Design --> Clarify1{"需求清晰?"}
140
+ Clarify1 -->|否| Ask1["追问澄清"] --> Clarify1
141
+ Clarify1 -->|是| GoElla["派遣 Ella"]
142
+
143
+ Dev --> Clarify2{"需求清晰?"}
144
+ Clarify2 -->|否| Ask2["追问澄清"] --> Clarify2
145
+ Clarify2 -->|是| HasDesign{"有设计稿?"}
146
+ HasDesign -->|是| GoJarvis1["派遣 Jarvis + 设计稿路径"]
147
+ HasDesign -->|否| GoJarvis2["派遣 Jarvis + 技术上下文"]
148
+
149
+ QA --> GoKyle["派遣 Kyle + 代码路径"]
150
+ Simple --> MaxAnswer["Max 直接回答"]
151
+ ```
152
+
153
+ ### 完整流水线
154
+
155
+ ```mermaid
156
+ sequenceDiagram
157
+ participant User
158
+ participant Max
159
+ participant Ella
160
+ participant Jarvis
161
+ participant Kyle
162
+ participant Shared
163
+
164
+ User->>Max: 提出需求
165
+ Max->>Max: 分析并拆解任务
166
+
167
+ Note over Max,Ella: 阶段一 设计
168
+ Max->>Ella: 派遣设计任务
169
+ Ella->>Shared: 输出设计稿
170
+ Ella-->>Max: 设计完成
171
+ Max-->>User: 需要开发吗
172
+
173
+ User->>Max: 确认开发
174
+
175
+ Note over Max,Jarvis: 阶段二 开发
176
+ Max->>Jarvis: 派遣开发任务+设计稿路径
177
+ Jarvis->>Shared: 读取设计稿
178
+ Jarvis->>Jarvis: 实现代码
179
+ Jarvis-->>Max: 开发完成
180
+ Max-->>User: 需要验收吗
181
+
182
+ User->>Max: 确认验收
183
+
184
+ Note over Max,Kyle: 阶段三 验收
185
+ Max->>Kyle: 派遣验收任务+代码路径
186
+ Kyle->>Kyle: 代码审查+功能验收
187
+ Kyle->>Shared: 输出审查报告
188
+ Kyle-->>Max: 验收完成
189
+
190
+ Max-->>User: 汇总全流程结果
191
+ ```
192
+
193
+ ### 上下文传递机制
194
+
195
+ ```mermaid
196
+ flowchart LR
197
+ subgraph CTX["独立上下文窗口"]
198
+ MaxCtx["Max\nRules 注入"]
199
+ EllaCtx["Ella\n独立窗口"]
200
+ JarvisCtx["Jarvis\n独立窗口"]
201
+ KyleCtx["Kyle\n独立窗口"]
202
+ end
203
+
204
+ subgraph SHARED["共享产物目录"]
205
+ Tasks[("tasks/")]
206
+ Designs[("designs/")]
207
+ Reviews[("reviews/")]
208
+ end
209
+
210
+ MaxCtx -->|"派遣注入\n需求+产物路径"| EllaCtx
211
+ MaxCtx -->|"派遣注入\n需求+设计稿路径"| JarvisCtx
212
+ MaxCtx -->|"派遣注入\n代码路径+需求"| KyleCtx
213
+
214
+ EllaCtx -->|写入设计稿| Designs
215
+ JarvisCtx -->|读取设计稿| Designs
216
+ KyleCtx -->|写入审查报告| Reviews
217
+ MaxCtx -->|写入任务文档| Tasks
218
+
219
+ style MaxCtx fill:#4A90D9,color:#fff
220
+ style EllaCtx fill:#E91E63,color:#fff
221
+ style JarvisCtx fill:#4CAF50,color:#fff
222
+ style KyleCtx fill:#FF9800,color:#fff
223
+ ```
224
+
225
+ > **关键规则**：子 Agent 之间不能直接通信，所有上下文由 Max 在派遣时注入，跨 Agent 协作通过 `.dev-agents/shared/` 目录下的文件实现。
226
+
227
+ ### 并行与串行
228
+
229
+ ```mermaid
230
+ flowchart TD
231
+ User(["用户: 多个任务"]) --> Max["Max 分析"]
232
+ Max --> Check{"任务间有依赖?"}
233
+
234
+ Check -->|无依赖| Parallel["并行派遣"]
235
+ Parallel --> P1["Ella: 设计登录页"]
236
+ Parallel --> P2["Jarvis: 开发后端 API"]
237
+ P1 --> Merge["Max 汇总"]
238
+ P2 --> Merge
239
+
240
+ Check -->|有依赖| Sequential["串行执行"]
241
+ Sequential --> S1["先: Ella 出设计稿"]
242
+ S1 --> S2["后: Jarvis 按稿开发"]
243
+ S2 --> Merge2["Max 汇总"]
244
+ ```
245
+
246
+ ## 工作流技能（门禁式管道）
247
+
248
+ 受 [Superpowers](https://github.com/obra/superpowers) 和 [Harness Engineering](https://martinfowler.com/articles/harness-engineering.html) 启发，aiGroup 内置工作流技能，形成严格的门禁管道——每个环节必须完成才能进入下一步：
249
+
250
+ ```
251
+ brainstorming → writing-plans → subagent-driven-development → finishing-a-development-branch
252
+ ↑ ↑
253
+ systematic-debugging verification-before-completion
254
+ （遇 Bug 时触发） （任何完成声明前触发）
255
+ ↑
256
+ entropy-management
257
+ （定期维护触发）
258
+ ```
259
+
260
+ | 技能 | 触发时机 | 核心规则 |
261
+ |------|---------|---------|
262
+ | **brainstorming** | 任何创造性工作之前 | 一次一个问题、2-3 方案对比、用户批准后才能继续 |
263
+ | **writing-plans** | 有设计方案后、编码前 | 任务粒度 2-5 分钟、禁止占位符、每步有完整代码 |
264
+ | **subagent-driven-development** | 有计划后、开发执行 | 每任务新子代理、两阶段审查（先规格后质量） |
265
+ | **systematic-debugging** | 遇到 Bug/测试失败 | 四阶段根因分析、3 次失败后质疑架构 |
266
+ | **verification-before-completion** | 声称完成/通过之前 | 无验证证据不得声明完成 |
267
+ | **finishing-a-development-branch** | 所有任务完成后 | 全量测试 → 四选一集成方式 → 清理 |
268
+ | **entropy-management** | 定期维护/漂移信号 | 传感器扫描 → 推理检查 → 修复 → 更新质量评分 |
269
+
270
+ ### 两阶段审查
271
+
272
+ 每次 Jarvis 完成开发后，Kyle 按严格顺序执行：
273
+
274
+ 1. **Stage 1：规格符合性** — 多了什么？少了什么？偏离了什么？
275
+ 2. **Stage 2：代码质量** — 干净、安全、可维护？
276
+
277
+ Stage 1 不通过 → 修复 → 重审 Stage 1 → 通过后才进入 Stage 2
278
+
279
+ ### 三条铁律
280
+
281
+ ```
282
+ 1. 证据优于断言 — 任何完成声明必须附带验证证据
283
+ 2. 流程不可跳过 — 工作流管道的每个环节必须走完
284
+ 3. 不确定时先问 — 宁可多问一句，不要假设
285
+ ```
286
+
287
+ ## 使用示例
288
+
289
+ ### 示例 1：完整功能开发
290
+
291
+ ```
292
+ 你: 帮我做一个用户认证系统
293
+
294
+ Max: [启动 brainstorming] → 逐个提问澄清需求 → 展示设计方案 → 用户批准
295
+ Max: [启动 writing-plans] → 产出分步实现计划 → 用户确认
296
+ Max: [启动 subagent-driven-development]
297
+ → 派遣 Jarvis 执行任务 1 → Kyle Stage 1 审查 → Kyle Stage 2 审查
298
+ → 派遣 Jarvis 执行任务 2 → Kyle Stage 1 审查 → Kyle Stage 2 审查
299
+ → ...
300
+ Max: [启动 finishing-a-development-branch] → 全量测试 → 用户选择集成方式
301
+ ```
302
+
303
+ ### 示例 2：直接派遣设计
304
+
305
+ ```
306
+ /ella 设计一个电商首页，风格参考 Apple Store，需要有 hero banner、商品分类、推荐列表
307
+
308
+ → Ella 读取 PERSONA 和 ui-ux-pro-max 技能
309
+ → 产出设计稿到 .dev-agents/shared/designs/ecommerce-home.md
310
+ → 返回：设计稿路径 + 设计决策摘要 + 实现注意事项
311
+ ```
312
+
313
+ ### 示例 3：代码审查
314
+
315
+ ```
316
+ /kyle 审查 src/auth/ 目录下的认证模块代码，对照实现计划 .dev-agents/shared/tasks/auth-plan.md
317
+
318
+ → Kyle 读取实现计划和代码
319
+ → Stage 1：逐条检查规格符合性
320
+ → Stage 2：检查代码质量、安全性、可维护性
321
+ → 产出审查报告到 .dev-agents/shared/reviews/auth-review.md
322
+ ```
323
+
324
+ ### 示例 4：Bug 调试
325
+
326
+ ```
327
+ 你: 用户登录后 token 刷新失败，返回 401
328
+
329
+ → Max 检测到 Bug 信号，启动 systematic-debugging
330
+ → 派遣 Jarvis 执行四阶段根因调查
331
+ → 第一阶段：阅读错误信息、稳定复现
332
+ → 第二阶段：找到可工作示例，对照差异
333
+ → 第三阶段：假设验证（一次一个变量）
334
+ → 第四阶段：创建失败测试 → 修复 → 验证
335
+ ```
336
+
337
+ ### 示例 5：Harness 健康检查
338
+
339
+ ```
340
+ 你: 跑一下项目健康检查
341
+
342
+ → Max 启动 entropy-management 技能
343
+ → 第一阶段：运行 scripts/harness/run-all.sh 自动化扫描
344
+ → 第二阶段：推理型扫描（文档一致性、架构漂移）
345
+ → 第三阶段：修复问题 + 将重复问题编码为约束
346
+ → 第四阶段：更新 docs/QUALITY_SCORE.md 和 docs/tech-debt-tracker.md
347
+ ```
348
+
349
+ ## 集成到已有项目
350
+
351
+ aiGroup 可以作为"脚手架"集成到你的任何项目中。
352
+
353
+ ### 方式一：CLI 工具（推荐）
354
+
355
+ ```bash
356
+ cd your-project
357
+ npx aigroup-workflow init
358
+ ```
359
+
360
+ 交互式选择需要的角色，自动安装所有框架文件。
361
+
362
+ ### 方式二：手动复制
363
+
364
+ 将以下目录和文件复制到你的项目根目录：
365
+
366
+ ```bash
367
+ # 必须复制
368
+ CLAUDE.md # Agent 入口
369
+ docs/ # 知识库
370
+ .claude/ # Claude Code 配置（commands/ + hooks.json + settings.json）
371
+ .dev-agents/ # 角色定义 + 协作产物目录
372
+ scripts/harness/ # Harness 传感器
373
+
374
+ # 按需复制
375
+ skills/max/workflow/ # 工作流技能（强烈推荐）
376
+ skills/ella/ # 设计技能（如果需要 UI 设计）
377
+ skills/jarvis/ # 开发技能（如果需要工程技能集）
378
+ skills/kyle/ # QA 技能（如果需要质量保障）
379
+ ```
380
+
381
+ ### 适配你的项目
382
+
383
+ 1. **编辑 `CLAUDE.md`**：不需要大改，只需确认知识库地图路径正确
384
+ 2. **编辑 `docs/ARCHITECTURE.md`**：替换为你项目的架构描述
385
+ 3. **编辑 `docs/coding-standards.md`**：替换为你项目的编码规范
386
+ 4. **编辑 `.dev-agents/*/PERSONA.md`**：根据需要调整角色定义
387
+
388
+ ### 验证安装
389
+
390
+ ```bash
391
+ aigroup check
392
+ # 或
393
+ bash scripts/harness/run-all.sh
394
+ ```
395
+
396
+ 所有检查通过即可开始使用。
397
+
398
+ ## 常用命令速查
399
+
400
+ ### 日常使用
401
+
402
+ | 命令 | 说明 | 使用场景 |
403
+ |------|------|---------|
404
+ | `claude` | 启动 Claude Code + Max | 开始工作 |
405
+ | `/ella <任务>` | 直接派遣设计师 | 界面设计、交互原型 |
406
+ | `/jarvis <任务>` | 直接派遣开发 | 编码、技术方案、Bug 修复 |
407
+ | `/kyle <任务>` | 直接派遣质量保障 | 代码审查、功能验收 |
408
+
409
+ ### CLI 工具
410
+
411
+ | 命令 | 说明 |
412
+ |------|------|
413
+ | `aigroup init` | 交互式初始化框架 |
414
+ | `aigroup init --yes` | 使用默认配置初始化 |
415
+ | `aigroup update` | 增量更新技能和传感器 |
416
+ | `aigroup check` | 运行 Harness 健康检查 |
417
+ | `aigroup status` | 查看工作流状态 |
418
+
419
+ ### Harness 维护
420
+
421
+ | 命令 | 说明 | 建议频率 |
422
+ |------|------|---------|
423
+ | `bash scripts/harness/run-all.sh` | 全量 Harness 传感器检查 | 每次开发完成后 |
424
+ | `bash scripts/check-gitignore.sh` | 检查 .gitignore 规则 | 添加新文件类型时 |
425
+ | `bash scripts/clean-system-files.sh` | 清理 .DS_Store 等系统文件 | 偶尔运行 |
426
+
427
+ > Windows 用户：用 Git Bash 运行以上命令（`"D:\Git\bin\bash.exe" scripts/harness/run-all.sh`）。
428
+
429
+ ### 自定义与扩展
430
+
431
+ | 想要做 | 修改什么 |
432
+ |--------|---------|
433
+ | 调整 Agent 角色定义 | `.dev-agents/{name}/PERSONA.md` |
434
+ | 修改工作流规则 | `skills/max/workflow/{skill}/SKILL.md` |
435
+ | 添加新的编码规范 | `docs/coding-standards.md` |
436
+ | 添加新的传感器检查 | `scripts/harness/lint-*.sh` 中添加检查项 |
437
+ | 添加新的危险信号 | `docs/red-flags.md` 中添加条目 |
438
+ | 将重复问题编码为约束 | 遵循 `docs/steering-loop.md` 转向循环流程 |
439
+ | 添加新的 Hook | `.claude/hooks.json` 中添加事件 |
440
+ | 修改权限控制 | `.claude/settings.json` 中调整 allow/deny |
441
+ | 添加新团队成员 | 新建 `.dev-agents/{name}/PERSONA.md` + `.claude/commands/{name}.md` |
442
+
443
+ ## 项目结构
444
+
445
+ ```
446
+ aiGroup/
447
+ ├── CLAUDE.md # Agent 入口：全局地图
448
+ ├── package.json # npm 包配置
449
+ ├── bin/aigroup.mjs # CLI 入口
450
+ ├── cli/ # CLI 实现
451
+ │ ├── commands/ # init / update / check / status
452
+ │ └── utils/ # prompts / logger / scaffold
453
+ ├── docs/ # 知识库（唯一事实源）
454
+ │ ├── ARCHITECTURE.md # 项目架构总览
455
+ │ ├── workflow-pipeline.md # 工作流管道详细规则
456
+ │ ├── dispatch-rules.md # 派遣规则与上下文传递
457
+ │ ├── coding-standards.md # 编码与 Git 规范
458
+ │ ├── red-flags.md # 危险信号检测
459
+ │ ├── QUALITY_SCORE.md # 质量评分追踪
460
+ │ ├── tech-debt-tracker.md # 技术债追踪
461
+ │ └── steering-loop.md # Harness 转向循环
462
+ ├── .claude/ # Claude Code 原生配置
463
+ │ ├── settings.json # 项目级权限设置
464
+ │ ├── hooks.json # Harness 生命周期 Hooks
465
+ │ └── commands/ # 斜杠命令（/ella /jarvis /kyle）
466
+ ├── .dev-agents/ # 角色定义 + 协作产物
467
+ │ ├── ella/PERSONA.md
468
+ │ ├── jarvis/PERSONA.md
469
+ │ ├── kyle/PERSONA.md
470
+ │ └── shared/ # 协作产物（tasks/ designs/ reviews/ templates/）
471
+ ├── skills/ # 技能资源（按角色分组）
472
+ │ ├── max/ # PM 技能
473
+ │ │ ├── workflow/ # 8 阶段工作流管道 + 横切技能（11 个）
474
+ │ │ ├── competitive-analysis/ # 竞品分析
475
+ │ │ ├── meeting-notes/ # 会议纪要
476
+ │ │ ├── prd-template/ # PRD 撰写
477
+ │ │ ├── stakeholder-update/ # 干系人汇报
478
+ │ │ └── user-research-synthesis/ # 用户研究综合
479
+ │ ├── ella/ # 设计技能（10 个）
480
+ │ │ ├── ui-ux-pro-max/ # 50+ 设计风格、97 色彩方案
481
+ │ │ ├── senior-frontend/ # 前端最佳实践
482
+ │ │ ├── react-expert/ # React 组件与 Hooks
483
+ │ │ ├── nextjs-developer/ # Next.js SSR/SSG
484
+ │ │ ├── vue-expert/ # Vue 3 (TypeScript)
485
+ │ │ ├── vue-expert-js/ # Vue 3 (JavaScript)
486
+ │ │ ├── angular-architect/ # Angular 企业级架构
487
+ │ │ ├── react-native-expert/ # React Native 移动端
488
+ │ │ ├── flutter-expert/ # Flutter 跨平台
489
+ │ │ └── commands/ # 设计工具命令
490
+ │ ├── jarvis/ # 开发技能（45 个）
491
+ │ │ ├── architecture-designer/ # 系统架构设计
492
+ │ │ ├── api-designer/ # API 设计
493
+ │ │ ├── fullstack-guardian/ # 全栈安全开发
494
+ │ │ ├── microservices-architect/ # 微服务架构
495
+ │ │ ├── secure-code-guardian/ # 安全编码
496
+ │ │ ├── debugging-wizard/ # 系统化调试
497
+ │ │ ├── typescript-pro/ # TypeScript 专家
498
+ │ │ ├── python-pro/ # Python 专家
499
+ │ │ ├── golang-pro/ # Go 专家
500
+ │ │ └── ... # 更多语言/框架/DevOps 技能
501
+ │ └── kyle/ # QA 技能（7 个）
502
+ │ ├── senior-qa/ # QA 最佳实践
503
+ │ ├── tdd-guide/ # TDD 指南
504
+ │ ├── test-master/ # 测试策略
505
+ │ ├── code-reviewer/ # 代码审查
506
+ │ ├── security-reviewer/ # 安全审计
507
+ │ ├── playwright-expert/ # E2E 测试
508
+ │ └── chaos-engineer/ # 混沌工程
509
+ ├── scripts/ # 自动化脚本
510
+ │ ├── harness/ # Harness 传感器套件
511
+ │ │ ├── run-all.sh # 全量传感器运行器
512
+ │ │ ├── lint-structure.sh # 结构检查
513
+ │ │ ├── lint-docs.sh # 文档新鲜度检查
514
+ │ │ ├── lint-workflow-artifacts.sh # 工作流产物检查
515
+ │ │ ├── hook-post-edit.sh # PostToolUse Hook
516
+ │ │ ├── hook-stop.sh # Stop Hook（back-pressure）
517
+ │ │ └── hook-subagent-stop.sh # SubagentStop Hook
518
+ │ ├── check-gitignore.sh # .gitignore 规则检查
519
+ │ └── clean-system-files.sh # 系统文件清理
520
+ └── README.md
521
+ ```
522
+
523
+ ## 技能体系
524
+
525
+ ### 技能与角色对应
526
+
527
+ ```mermaid
528
+ flowchart TB
529
+ subgraph MAX["Max 项目经理"]
530
+ M1["workflow\n8阶段工作流管道"]
531
+ M2["PM 辅助技能\n竞品分析/PRD/会议纪要等"]
532
+ end
533
+
534
+ subgraph ELLA["Ella 设计师"]
535
+ E1["ui-ux-pro-max\n50+ 设计风格"]
536
+ E2["senior-frontend\n前端最佳实践"]
537
+ E3["前端框架 x7\nReact/Vue/Angular/Next.js\nFlutter/RN"]
538
+ end
539
+
540
+ subgraph JARVIS["Jarvis 开发"]
541
+ J1["架构与设计 x7"]
542
+ J2["后端框架 x7"]
543
+ J3["编程语言 x11"]
544
+ J4["数据库与数据 x8"]
545
+ J5["DevOps x6"]
546
+ J6["安全与工具 x6"]
547
+ end
548
+
549
+ subgraph KYLE["Kyle 质量保障"]
550
+ K1["senior-qa + tdd-guide"]
551
+ K2["test-master\n测试策略"]
552
+ K3["code-reviewer\n代码审查"]
553
+ K4["security-reviewer\n安全审计"]
554
+ K5["playwright-expert\nE2E 测试"]
555
+ K6["chaos-engineer\n混沌工程"]
556
+ end
557
+ ```
558
+
559
+ ### 技能分布总览
560
+
561
+ | 角色 | 技能数 | 核心领域 |
562
+ |------|--------|---------|
563
+ | **Max** (PM) | 16 | 8 阶段工作流管道 + 3 横切技能 + 5 PM 辅助技能 |
564
+ | **Ella** (设计) | 10 | UI/UX 设计 + 前端最佳实践 + 7 前端框架 |
565
+ | **Jarvis** (开发) | 45 | 架构设计、后端框架、编程语言、数据库、DevOps、安全编码 |
566
+ | **Kyle** (QA) | 7 | QA 实践、TDD、测试策略、代码审查、安全审计、E2E、混沌工程 |
567
+
568
+ ## 技能来源
569
+
570
+ | 技能 | 来源 | 许可证 |
571
+ |------|------|--------|
572
+ | 工作流技能 (11个) | 原创，受 [obra/superpowers](https://github.com/obra/superpowers) 和 [Harness Engineering](https://martinfowler.com/articles/harness-engineering.html) 启发 | MIT |
573
+ | Jarvis/Kyle/Ella 开发技能 (62个) | [Jeffallan/claude-skills](https://github.com/Jeffallan/claude-skills) | MIT |
574
+ | PM 辅助技能 (5个) | [mohitagw15856/pm-claude-skills](https://github.com/mohitagw15856/pm-claude-skills) | MIT |
575
+ | UI/UX Pro Max | SkillsMP 技能市场 | MIT |
576
+ | Senior Frontend / QA / TDD | SkillsMP 技能市场 | MIT |
577
+
578
+ ## Harness Engineering 体系
579
+
580
+ aiGroup 采用 [Harness Engineering](https://martinfowler.com/articles/harness-engineering.html) 理念，通过约束、反馈回路和持续改进循环提升 Agent 可靠性。
581
+
582
+ ### 核心公式
583
+
584
+ ```
585
+ Agent = Model + Harness
586
+ ```
587
+
588
+ 不优化模型本身，而是优化模型运行的环境。
589
+
590
+ ### 四层防线
591
+
592
+ | 层级 | 机制 | 实现 |
593
+ |------|------|------|
594
+ | **前馈引导** | 在 Agent 行动前引导方向 | CLAUDE.md 地图、Skills 渐进披露、工作流管道 |
595
+ | **计算型反馈** | 确定性检查，快速自动运行 | `scripts/harness/` 传感器套件 + Claude Code Hooks |
596
+ | **推理型反馈** | AI 语义审查 | Kyle 两阶段审查（规格符合性 + 代码质量） |
597
+ | **熵管理** | 防止长期退化 | entropy-management 技能 + 质量评分追踪 |
598
+
599
+ ### Harness 传感器
600
+
601
+ ```bash
602
+ bash scripts/harness/run-all.sh # 全量检查
603
+ ```
604
+
605
+ 传感器输出对 Agent 友好：`[PASS]` 通过、`[FAIL]` 失败 + `[FIX]` 修复指令。
606
+
607
+ ### 转向循环
608
+
609
+ ```
610
+ 发现重复问题 → 编码为约束（Linter/文档/技能）→ 自动执行 → 更新质量评分
611
+ ```
612
+
613
+ 详见 `docs/steering-loop.md`。
614
+
615
+ ### 知识库
616
+
617
+ 所有规范、架构决策、质量追踪均版本化存储在 `docs/` 目录下，作为项目的唯一事实源。
618
+ CLAUDE.md 仅作为地图入口（< 100 行），详细内容按需从 `docs/` 检索。
619
+
620
+ ## 致谢
621
+
622
+ 本项目基于 [yezannnnn/agentGroup](https://github.com/yezannnnn/agentGroup) 进行开发和扩展。感谢原作者 [@yezannnnn](https://github.com/yezannnnn) 提出的四 AI 专业分工协作框架理念，为本项目奠定了坚实的基础。
623
+
624
+ ## 社区支持
625
+
626
+ <div align="center">
627
+
628
+ **学 AI，上 L 站**
629
+
630
+ [![LINUX DO](https://img.shields.io/badge/LINUX%20DO-社区-gray?style=flat-square)](https://linux.do/) [![社区支持](https://img.shields.io/badge/社区支持-交流-blue?style=flat-square)](https://linux.do/)
631
+
632
+ 本项目在 [LINUX DO](https://linux.do/) 社区发布与交流，感谢佬友们的支持与反馈。
633
+
634
+ </div>
635
+
636
+ ## 许可证
637
+
638
+ MIT License
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "aigroup-workflow",
3
- "version": "1.1.0",
3
+ "version": "1.1.1",
4
4
  "description": "AI 团队协作框架 — 通过角色派遣、工作流管道和 Harness 传感器驱动 AI 协作开发",
5
5
  "type": "module",
6
6
  "bin": {