aigroup-workflow 2.1.0 → 2.1.2
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/docs/rules/README.md +1 -0
- package/docs/rules/coding-style.md +21 -1
- package/docs/rules/entropy.md +75 -0
- package/package.json +1 -1
package/docs/rules/README.md
CHANGED
|
@@ -14,6 +14,7 @@
|
|
|
14
14
|
| [security.md](security.md) | 安全清单、密钥管理、应急响应 |
|
|
15
15
|
| [performance.md](performance.md) | MCP / tool 预算、上下文卫生、长任务拆分 |
|
|
16
16
|
| [hooks.md](hooks.md) | Hooks 使用规则（Claude 自动 / Codex 手动） |
|
|
17
|
+
| [entropy.md](entropy.md) | 熵管理三条 Golden Rule + 沉淀义务 |
|
|
17
18
|
|
|
18
19
|
## 语言专项（按栈加载）
|
|
19
20
|
|
|
@@ -16,12 +16,26 @@
|
|
|
16
16
|
- 不构建当下不需要的功能
|
|
17
17
|
- 避免投机性通用化
|
|
18
18
|
- 先简单做出来，需要时再重构
|
|
19
|
+
- **长度压力**：能用 50 行写清楚的逻辑，不写 200 行；写完先压一遍再提交
|
|
20
|
+
- 不给"不可能发生的情况"加保险（如内部受控数据再做 null 校验）；边界处的校验另由 [entropy.md Golden Rule 2](entropy.md) 强制
|
|
19
21
|
|
|
20
22
|
### 防御编程
|
|
21
23
|
- 在系统边界（用户输入、外部 API、文件读取）做输入校验
|
|
22
24
|
- 用 schema 校验，快速失败并给出明确错误
|
|
23
25
|
- 不信任外部数据
|
|
24
26
|
|
|
27
|
+
## 动手前澄清
|
|
28
|
+
|
|
29
|
+
写代码之前的强制流程：
|
|
30
|
+
|
|
31
|
+
1. **显式声明假设** — 把"我假设 X / 我以为 Y"写出来，别藏在脑子里。前提一旦错，所有产出都白费
|
|
32
|
+
2. **不确定就停下，不要猜** — 命名歧义、需求模糊、行为未定义时，明确说出"哪里不清楚"，不要靠猜继续
|
|
33
|
+
3. **多解读时呈选项** — 任务有 2 种以上合理解读时，把候选方案列给用户选，不替用户做决定
|
|
34
|
+
4. **复杂方案先反问** — 方案过度设计时，先质疑能否简化；用户坚持复杂方案才执行
|
|
35
|
+
5. **不知道现有约定就先读** — 新模块陌生时先翻 3 个相似实现 + 对应 `docs/rules/<lang>/`，再动手
|
|
36
|
+
|
|
37
|
+
不做这一步的代价：返工、与现有模式冲突、引入与项目品味不符的代码。
|
|
38
|
+
|
|
25
39
|
## File Organization
|
|
26
40
|
|
|
27
41
|
**多个小文件 > 少个大文件**：
|
|
@@ -64,6 +78,9 @@
|
|
|
64
78
|
- **先读后写** — 先理解现有代码模式再动手
|
|
65
79
|
- **精准修改** — 只改需要改的部分
|
|
66
80
|
- **闭环优先** — 先跑通再优化，不过度设计
|
|
81
|
+
- **跟随现有风格** — 即便现有写法不是你认为的最优，也保持一致；风格统一比单点最优更重要
|
|
82
|
+
- **改动孤立才清理** — 只删除你的改动产生的孤立 import / 局部变量；不相关的死代码标注出来但不动手（重构走独立 PR）
|
|
83
|
+
- **不在功能 PR 里偷重构** — 修一个功能时顺手重构其他模块 = 评审噩梦 + 回归风险，禁止
|
|
67
84
|
|
|
68
85
|
## Code Quality Checklist
|
|
69
86
|
|
|
@@ -73,7 +90,10 @@
|
|
|
73
90
|
- [ ] 函数小（< 50 行）
|
|
74
91
|
- [ ] 文件聚焦（< 800 行）
|
|
75
92
|
- [ ] 无深嵌套（≤ 4 层）
|
|
76
|
-
- [ ]
|
|
93
|
+
- [ ] 错误处理完整，边界处有校验
|
|
77
94
|
- [ ] 无硬编码值（用常量或 config）
|
|
78
95
|
- [ ] 中文注释规范，无尾行注释
|
|
96
|
+
- [ ] 改动范围与任务直接相关；不相关代码已标记但未顺手改
|
|
97
|
+
- [ ] 风格与本模块/项目现有写法一致
|
|
98
|
+
- [ ] 没有为不可能发生的情况加保险逻辑
|
|
79
99
|
- [ ] 通过 `node scripts/hooks/dispatcher.cjs stop`
|
|
@@ -0,0 +1,75 @@
|
|
|
1
|
+
# Entropy Rules
|
|
2
|
+
|
|
3
|
+
> 防止 AI 反复复制不良模式造成的代码漂移。三条 Golden Rule + 沉淀义务。
|
|
4
|
+
|
|
5
|
+
## Golden Rule 1：共享 utility 优先于手写 helper
|
|
6
|
+
|
|
7
|
+
**强制**：实现新功能前，必须搜索现有 utility 包；只有在确认无可复用项后才允许手写。
|
|
8
|
+
|
|
9
|
+
| 场景 | 必须做 |
|
|
10
|
+
|------|-------|
|
|
11
|
+
| 需要工具函数（格式化、校验、转换） | 先 grep `utils/` `shared/` `common/` 现有实现；存在即复用 |
|
|
12
|
+
| 现有实现接近但不完全匹配 | 扩展现有函数而不是新写一个并行版本 |
|
|
13
|
+
| 真的需要新函数 | 放进项目约定的共享目录，不放业务模块内 |
|
|
14
|
+
|
|
15
|
+
**违规信号**：同名/近似名函数在多个文件出现、业务模块内出现纯工具函数、`copy from X` 注释。
|
|
16
|
+
|
|
17
|
+
**自动检测**：`refactor-cleaner` agent 跑 `knip` / `ts-prune` 检测重复导出与未使用导出；同名函数检测应纳入未来 `scripts/hooks/checks/duplicate-utility.cjs`（待补）。
|
|
18
|
+
|
|
19
|
+
## Golden Rule 2：边界处必须做数据验证
|
|
20
|
+
|
|
21
|
+
**强制**：跨信任边界的数据进入系统时，必须经过类型/Schema 验证。"内部代码可信"的假设仅在边界之内成立。
|
|
22
|
+
|
|
23
|
+
| 边界 | 必须做 |
|
|
24
|
+
|------|-------|
|
|
25
|
+
| 用户输入（HTTP / CLI / 表单） | Schema 校验后再进业务层 |
|
|
26
|
+
| 外部 API 返回 | 类型化 SDK 或显式 Schema 解析 |
|
|
27
|
+
| 数据库读取（无强类型 ORM 时） | 出库即校验或类型断言 |
|
|
28
|
+
| 进程间消息（队列、IPC） | 反序列化后立刻 Schema 校验 |
|
|
29
|
+
|
|
30
|
+
**禁止**：
|
|
31
|
+
- `as any` / `as unknown as T` 跨边界使用
|
|
32
|
+
- `JSON.parse` 后直接当业务对象用
|
|
33
|
+
- 把外部数据直接作为内部函数参数传入
|
|
34
|
+
|
|
35
|
+
**自动检测**：各语言 rules 文件应给出该栈的强制写法（参考 `docs/rules/typescript/` 等）。
|
|
36
|
+
|
|
37
|
+
## Golden Rule 3：关键子系统自实现 + 全覆盖
|
|
38
|
+
|
|
39
|
+
**强制**：业务关键路径（鉴权、计费、数据持久化、安全）不外包给"看起来能用"的第三方包；要么用业界标准（且锁版本 + 监控 CVE），要么自实现并保证测试覆盖。
|
|
40
|
+
|
|
41
|
+
| 子系统类型 | 选择策略 |
|
|
42
|
+
|-----------|---------|
|
|
43
|
+
| 鉴权 / 加密 / 签名 | 用经过审计的标准库（如 OpenSSL、libsodium、JWT 标准实现），不允许"自己写一个" |
|
|
44
|
+
| 计费 / 限流 / 配额 | 自实现 + 100% 行覆盖 + 边界测试齐全 |
|
|
45
|
+
| 数据序列化 / 持久化关键字段 | 自实现 + Schema 版本兼容测试 |
|
|
46
|
+
| 通用 utility / UI 组件 | 可用社区包，按 Golden Rule 1 复用 |
|
|
47
|
+
|
|
48
|
+
**禁止**：关键路径依赖未审计的小众包；关键路径测试覆盖率 < 100%。
|
|
49
|
+
|
|
50
|
+
## 沉淀义务（与本规则配套）
|
|
51
|
+
|
|
52
|
+
**铁律**：发现的违规不能只修一次。每次熵管理或 code review 发现的反复模式必须在以下位置编码为约束：
|
|
53
|
+
|
|
54
|
+
| 类型 | 沉淀位置 |
|
|
55
|
+
|------|---------|
|
|
56
|
+
| 自动可检测的代码模式 | 加 `scripts/hooks/checks/<name>.cjs` 让 dispatcher 报 [FAIL] |
|
|
57
|
+
| 跨任务的架构约定 | 写入 `docs/PROJECT_CONTEXT.md` 或 `docs/ARCHITECTURE.md` |
|
|
58
|
+
| 强制规则（语言无关） | 加入本文件或 `docs/rules/<topic>.md` |
|
|
59
|
+
| 强制规则（语言专项） | 加入 `docs/rules/<lang>/<topic>.md` |
|
|
60
|
+
| 高频踩坑信号 | 加入 `docs/red-flags.md` |
|
|
61
|
+
|
|
62
|
+
未沉淀的修复 = **没修**。
|
|
63
|
+
|
|
64
|
+
## 触发与执行
|
|
65
|
+
|
|
66
|
+
- **何时检视本规则**：`entropy-management` skill 第二阶段、code-reviewer 审查、refactor-cleaner 任务前
|
|
67
|
+
- **谁负责**：主会话编排，`refactor-cleaner` / `code-reviewer` agent 执行
|
|
68
|
+
- **频率**：完成 5 个任务后 / 怀疑漂移时 / 用户主动要求
|
|
69
|
+
|
|
70
|
+
## 关联
|
|
71
|
+
|
|
72
|
+
- `skills/entropy-management/SKILL.md` — 执行流程
|
|
73
|
+
- `agents/refactor-cleaner.md` — 死代码与重复清理
|
|
74
|
+
- `docs/red-flags.md` 信号 #8 / #9 — 反复问题与文档漂移
|
|
75
|
+
- `scripts/hooks/checks/` — 自动化传感器套件
|