@shirayner/ace 0.1.0-snapshot.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.
- package/bin/ace.js +39 -0
- package/package.json +42 -0
- package/src/commands/doctor.js +86 -0
- package/src/commands/init.js +98 -0
- package/src/commands/list.js +67 -0
- package/src/core/constants.js +106 -0
- package/src/core/installer.js +206 -0
- package/src/core/merger.js +103 -0
- package/templates/CLAUDE.md +16 -0
- package/templates/commands/report.md +63 -0
- package/templates/hookify/hookify.block-dangerous-ops.local.md +16 -0
- package/templates/hookify/hookify.protect-secrets.local.md +17 -0
- package/templates/hookify/hookify.require-verification.local.md +13 -0
- package/templates/hooks/java-compile-check.sh +106 -0
- package/templates/memory/MEMORY.md +4 -0
- package/templates/memory/roles/backend.md +11 -0
- package/templates/memory/roles/client.md +11 -0
- package/templates/memory/roles/frontend.md +11 -0
- package/templates/memory/roles/fullstack.md +11 -0
- package/templates/rules/clean-code.md +33 -0
- package/templates/rules/code-quality.md +74 -0
- package/templates/rules/context-hygiene.md +29 -0
- package/templates/rules/memory-policy.md +30 -0
- package/templates/rules/reporting.md +9 -0
- package/templates/rules/task-recovery.md +13 -0
- package/templates/rules/thinking.md +19 -0
- package/templates/settings.json +11 -0
- package/templates/skills/auto-goal/SKILL.md +188 -0
- package/templates/skills/coding/SKILL.md +251 -0
- package/templates/skills/coding/references/code-review-guide.md +137 -0
- package/templates/skills/coding/references/code-smells.md +201 -0
- package/templates/skills/coding/references/implement-guide.md +123 -0
- package/templates/skills/coding/references/unit-test-guide.md +211 -0
- package/templates/skills/skill-creator/LICENSE.txt +202 -0
- package/templates/skills/skill-creator/SKILL.md +479 -0
- package/templates/skills/skill-creator/agents/analyzer.md +274 -0
- package/templates/skills/skill-creator/agents/comparator.md +202 -0
- package/templates/skills/skill-creator/agents/grader.md +223 -0
- package/templates/skills/skill-creator/assets/eval_review.html +146 -0
- package/templates/skills/skill-creator/eval-viewer/generate_review.py +471 -0
- package/templates/skills/skill-creator/eval-viewer/viewer.html +1325 -0
- package/templates/skills/skill-creator/references/schemas.md +430 -0
- package/templates/skills/skill-creator/scripts/__init__.py +0 -0
- package/templates/skills/skill-creator/scripts/aggregate_benchmark.py +401 -0
- package/templates/skills/skill-creator/scripts/generate_report.py +326 -0
- package/templates/skills/skill-creator/scripts/improve_description.py +248 -0
- package/templates/skills/skill-creator/scripts/package_skill.py +136 -0
- package/templates/skills/skill-creator/scripts/quick_validate.py +103 -0
- package/templates/skills/skill-creator/scripts/run_eval.py +310 -0
- package/templates/skills/skill-creator/scripts/run_loop.py +332 -0
- package/templates/skills/skill-creator/scripts/utils.py +47 -0
- package/templates/skills/skill-optimize/SKILL.md +287 -0
- package/templates/skills/skill-optimize/references/.claude/settings.local.json +7 -0
- package/templates/skills/skill-optimize/references/anthropic-design-philosophy.md +250 -0
- package/templates/skills/skill-optimize/references/auto-goal-optimization-directions.md +130 -0
- package/templates/skills/skill-optimize/references/cross-disciplinary-insights.md +211 -0
- package/templates/skills/skill-optimize/references/quality-checklist.md +170 -0
- package/templates/skills/skill-optimize/references/theory-foundations.md +201 -0
|
@@ -0,0 +1,188 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: auto-goal
|
|
3
|
+
description: |
|
|
4
|
+
自主完成目标的AI Skill。当用户需要完成复杂目标、项目、任务或学习需求时使用此skill。
|
|
5
|
+
触发词:"帮我实现..."、"完成...目标"、"搞定...任务"、"自动完成..."、"逐步完成..."、
|
|
6
|
+
"学习..."、"教程"、"入门"、"深入理解..."、"掌握..."、"什么是XXX"、"如何学习XXX"、"请讲解XXX"
|
|
7
|
+
核心:六字原则 + 域感知OODA循环 + 假设驱动行动 + 上下文工程 + 韧性机制。验证内建于每步。
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
# Auto Goal Skill
|
|
11
|
+
|
|
12
|
+
自主完成目标的赋能系统。**核心信念**:每步行动都是对假设的检验——验证内建于行动本身,失败是认知升级的信号,上下文是最稀缺的资源,足够好胜过完美。
|
|
13
|
+
|
|
14
|
+
---
|
|
15
|
+
|
|
16
|
+
## 六字原则(始终生效)
|
|
17
|
+
|
|
18
|
+
| 字 | 含义 | 自检 |
|
|
19
|
+
|----|------|------|
|
|
20
|
+
| **序** | 理解与行动螺旋深化 | 理解够启动下一步吗? |
|
|
21
|
+
| **验** | 用事实闭环,证伪导向 | 什么条件下结论不成立? |
|
|
22
|
+
| **深** | 多问一层为什么 | 到根因层了吗? |
|
|
23
|
+
| **广** | 系统中定位局部 | 改动影响传向何方? |
|
|
24
|
+
| **辨** | 区分事实/推断/假设 | FACT / INFER / ASSUME? |
|
|
25
|
+
| **简** | 复杂度需要理由 | 能更简单吗? |
|
|
26
|
+
|
|
27
|
+
---
|
|
28
|
+
|
|
29
|
+
## 执行循环(域感知 OODA)
|
|
30
|
+
|
|
31
|
+
### 域感知路由(每个循环入口)
|
|
32
|
+
|
|
33
|
+
判断问题所处的域,选择匹配策略:
|
|
34
|
+
|
|
35
|
+
| 域 | 特征 | 策略 |
|
|
36
|
+
|----|------|------|
|
|
37
|
+
| **Clear** | 因果明确,已知解法 | 感知→分类→响应。直接执行最佳实践 |
|
|
38
|
+
| **Complicated** | 因果可分析,需专业知识 | 感知→分析→响应。探索后规划执行 |
|
|
39
|
+
| **Complex** | 因果仅事后可见,涌现性 | 试探→感知→响应。小步实验,观察涌现 |
|
|
40
|
+
| **Chaotic** | 无稳定因果 | 行动→感知→响应。先止血再诊断 |
|
|
41
|
+
|
|
42
|
+
**域可迁移**:初判不是终判。执行中发现域判断错误时立即切换策略。
|
|
43
|
+
|
|
44
|
+
### OODA 循环
|
|
45
|
+
|
|
46
|
+
```
|
|
47
|
+
接收目标 → 初始理解 → 域判断 + 估算深度(1-4)
|
|
48
|
+
↓
|
|
49
|
+
┌─────────────────────────────────────────────────┐
|
|
50
|
+
│ Sense :状态?变化?新信息?⚡弱信号+外围扫描 │
|
|
51
|
+
│ Orient :距目标多远?心智模型需要更新吗? │
|
|
52
|
+
│ Decide :策略 + 推理模式 + 深度 + 验证标准 │
|
|
53
|
+
│ Act :识别即行动 or 完整分析(= 检验假设) │
|
|
54
|
+
│ Observe:结果 vs 预期?验证精度匹配风险级别 │
|
|
55
|
+
│ Adapt :更新理解,调节深度/域,外化状态 │
|
|
56
|
+
│ │
|
|
57
|
+
│ → 循环,直到目标满足或触发降级 │
|
|
58
|
+
└─────────────────────────────────────────────────┘
|
|
59
|
+
↓
|
|
60
|
+
终态验证(证伪导向) → 交付结果
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
**关键机制**:
|
|
64
|
+
|
|
65
|
+
- **弱信号检测**(Sense):不等失败才反应。主动扫描——进展在减速?假设在累积未验证?复杂度在悄然上升?发现弱信号 → 升级深度或回到 Orient。模糊时先恢复情境意识
|
|
66
|
+
- **假设驱动行动**(Act):**已知模式→识别即行动**(模式匹配→心理模拟→执行);**未知→完整分析**。每步明确"检验什么假设"。意外结果的信息量 > 预期结果
|
|
67
|
+
- **推理模式选择**(Decide):不可逆选择→生成备选评估后决策;置信度低→多角度推理检查收敛;关键输出完成→切换为怀疑论审查者
|
|
68
|
+
- **验证精度分级**(Observe):微验证(低风险,心理校验)/ 标准验证(中风险,工具确认)/ 深度验证(高风险/不可逆,交叉证伪)
|
|
69
|
+
- **深度调节**(1=自动…4=全面):升级信号:偏离/新复杂度/验证失败/弱信号;降级信号:连续顺利/模式匹配/不确定性收敛
|
|
70
|
+
- **熔断器**(持续):同一子问题重试 > 3 次→换策略或求助;探索超阶段预算→强制转向;每 5 步→目标漂移检查
|
|
71
|
+
- **终态证伪**:不问"能运行吗?",问"什么条件下会失败?"
|
|
72
|
+
|
|
73
|
+
---
|
|
74
|
+
|
|
75
|
+
## 策略工具箱
|
|
76
|
+
|
|
77
|
+
五个策略,按需组合,可重复调用。
|
|
78
|
+
|
|
79
|
+
### 澄清(Clarify)
|
|
80
|
+
消除歧义,对齐理解。区分表面需求与真实需求。不确定性分级:必须澄清 / 可合理假设 / 无关紧要。批量提问减少打断。**不过度提问**:能推断的不问,能合理假设的标注后继续。
|
|
81
|
+
|
|
82
|
+
### 探索(Explore)
|
|
83
|
+
获取知识,识别最佳实践和风险。**在 sub-agent 中执行**,只将摘要返回主上下文。交叉验证关键信息,标注置信度。**觅食启发**:跟踪信息气味(相关性信号)→ 收益递减时果断换源 → 探索超总预算 30% 停止。**认知行动合法**:为理解而做的探索(临时测试、中间状态打印)是投资非浪费。
|
|
84
|
+
|
|
85
|
+
### 规划(Plan)
|
|
86
|
+
将目标分解为可验证的交付物。**目标层级**:完整目标 / 核心目标 / 最小可交付——规划时即定义降级边界。倾向简单方案,识别依赖,插入检查点。**Pre-mortem**:假设计划已失败——最可能原因是什么?
|
|
87
|
+
|
|
88
|
+
### 执行(Execute)
|
|
89
|
+
按计划渐进交付。优先核心功能,尽早产出可验证结果。关键节点保存进度。遇到意外:能当场解决→解决;需调整→回到规划/澄清。
|
|
90
|
+
|
|
91
|
+
### 试探(Probe)
|
|
92
|
+
**Complex 域专用**。设计安全的小实验验证假设:明确实验目的 → 限定影响范围 → 执行 → 观察涌现 → 提取模式。失败的试探也是有效信息。
|
|
93
|
+
|
|
94
|
+
---
|
|
95
|
+
|
|
96
|
+
## 上下文工程
|
|
97
|
+
|
|
98
|
+
上下文窗口是工作记忆,主动管理而非被动耗尽。
|
|
99
|
+
|
|
100
|
+
| 策略 | 做法 | 时机 |
|
|
101
|
+
|------|------|------|
|
|
102
|
+
| **隔离** | 探索性工作用 sub-agent,只回传摘要 | 搜索、读大文件、查资料 |
|
|
103
|
+
| **压缩** | 已完成阶段压缩为摘要,保留决策和结论 | 每个大阶段完成后 |
|
|
104
|
+
| **外化** | 关键中间结果写入状态文件 | 做出重要决策、发现关键信息 |
|
|
105
|
+
| **按需加载** | 根据当前阶段拉入相关上下文 | 每步开始前 |
|
|
106
|
+
|
|
107
|
+
**压缩保护**:压缩时必须保留——当前目标与验收标准、关键决策及理由、已修改文件列表、未完成待办、心智模型核心假设、延迟意图队列。
|
|
108
|
+
|
|
109
|
+
**信息节奏**:前期宽探索(广度优先)→ 中期深执行(深度优先)→ 后期纯验证。节奏错配是上下文浪费的主因。
|
|
110
|
+
|
|
111
|
+
---
|
|
112
|
+
|
|
113
|
+
## 韧性机制
|
|
114
|
+
|
|
115
|
+
### 信息分级
|
|
116
|
+
- **FACT** — 经过验证(工具输出、测试结果、文档确认)
|
|
117
|
+
- **INFER** — 基于事实的推断(标注依据)
|
|
118
|
+
- **ASSUME** — 未经验证的假设(标注验证方法)
|
|
119
|
+
|
|
120
|
+
决策不应仅依赖 ASSUME。INFER/ASSUME 被推翻时,回溯所有依赖它的后续决策。
|
|
121
|
+
|
|
122
|
+
### Reflect-then-Retry
|
|
123
|
+
遇到意外时(失败、意外成功、意外副作用),不直接重试,先结构化反思(写入 reflections.md):
|
|
124
|
+
1. 失败现象 vs 预期偏差
|
|
125
|
+
2. 根因分类:理解偏差 / 知识不足 / 规划缺陷 / 执行错误 / 环境变化
|
|
126
|
+
3. **溯因诊断**:生成竞争假设,按可测试性排序,优先证伪最易检验的;暴露未言明的前提
|
|
127
|
+
4. 修正策略(必须可执行,"更仔细"不算)
|
|
128
|
+
5. 重试前**必须**读取之前的反思记录
|
|
129
|
+
6. 三次反思后仍无法解决 → 向用户透明报告
|
|
130
|
+
7. **成功解剖**:捕获意外有效方案 + 使其成功的关键适应性调整,持久化为可复用启发式
|
|
131
|
+
|
|
132
|
+
### 优雅降级
|
|
133
|
+
永不空手而归。面对压力三态响应:**吸收**(重试/回退)→ **适应**(换策略/重规划)→ **转化**(重定义问题/升级给用户)。
|
|
134
|
+
交付物逐级降级:
|
|
135
|
+
- **L0** 完整交付 → **L1** 核心交付(标注未完成次要部分)
|
|
136
|
+
- **L2** 部分交付(已验证部分 + 未完成原因)→ **L3** 分析交付(问题理解 + 已探索方案 + 建议路径)
|
|
137
|
+
|
|
138
|
+
---
|
|
139
|
+
|
|
140
|
+
## 记忆架构
|
|
141
|
+
|
|
142
|
+
```
|
|
143
|
+
.tasks/auto-goal-{id}/
|
|
144
|
+
├── state.md # Orient — 我在哪,去哪,下一步
|
|
145
|
+
├── decisions.md # Decide — 关键决策 + 理由 + 备选方案
|
|
146
|
+
├── observations.md # Sense — 意外发现、环境变化、新信息
|
|
147
|
+
└── reflections.md # Adapt — 失败根因 + 成功解剖
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
### state.md 结构指引
|
|
151
|
+
|
|
152
|
+
- **目标**(完整 / 核心 / 最小可交付)+ 验收标准
|
|
153
|
+
- **当前域判断** + **深度级别**
|
|
154
|
+
- **心智模型**:当前理解——关键假设、已验证事实、未知区域
|
|
155
|
+
- **进度概览**(已完成 / 进行中 / 待做)+ **下一步行动**
|
|
156
|
+
- 深度 ≥ 3:阶段分解(步骤 / 验证条件 / 完成摘要)
|
|
157
|
+
- **延迟意图**:`When [条件] do [行动]` 格式,阶段边界自动检查
|
|
158
|
+
- 编码任务:追踪已修改文件
|
|
159
|
+
|
|
160
|
+
**为陌生读者而写**:状态文件的受众不是"提醒自己",而是"让一个全新 agent 能理解并继续"。文件系统是跨会话协调层,非备份记忆。
|
|
161
|
+
|
|
162
|
+
### 恢复验证
|
|
163
|
+
|
|
164
|
+
信任但验证:交叉验证 state.md 声称的产出是否真实存在(Glob/Read 轻量确认)。用 TaskCreate/TaskUpdate 重建 UI 进度(仅为未完成阶段创建)。
|
|
165
|
+
|
|
166
|
+
---
|
|
167
|
+
|
|
168
|
+
## 介入模式
|
|
169
|
+
|
|
170
|
+
不是静态三档,而是操作类型驱动:
|
|
171
|
+
|
|
172
|
+
| 操作类型 | 默认行为 |
|
|
173
|
+
|----------|----------|
|
|
174
|
+
| 可逆、影响范围小 | 自主执行,事后简报 |
|
|
175
|
+
| 不可逆或影响范围大 | 执行前确认 |
|
|
176
|
+
| 涉及用户偏好/价值判断 | 提供选项,等待决策 |
|
|
177
|
+
| 目标/方向性调整 | 始终询问 |
|
|
178
|
+
|
|
179
|
+
---
|
|
180
|
+
|
|
181
|
+
## 反模式警觉
|
|
182
|
+
|
|
183
|
+
| 反模式 | 解药 |
|
|
184
|
+
|--------|------|
|
|
185
|
+
| 确认偏误:只找支持假设的证据 | 证伪导向——主动找反证 |
|
|
186
|
+
| 盲目重试:失败后不反思直接重来 | Reflect-then-Retry |
|
|
187
|
+
| 域错配:用 Complicated 策略应对 Complex 问题 | 域感知路由——试探优先于分析 |
|
|
188
|
+
| 吸收循环:卡在重试中不升级策略 | 韧性三态——吸收失败后升级到适应或转化 |
|
|
@@ -0,0 +1,251 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: coding
|
|
3
|
+
description: |
|
|
4
|
+
代码域认知协议。覆盖三种意图:
|
|
5
|
+
|
|
6
|
+
**实现** — 当用户需要编写代码、修复bug、重构、添加功能时触发。
|
|
7
|
+
关键词:"实现"、"开发"、"修复"、"重构"、"添加功能"、"coding"、"implement"、"fix bug"。
|
|
8
|
+
|
|
9
|
+
**测试** — 当用户需要生成或修复单元测试时触发。
|
|
10
|
+
关键词:"生成单测"、"写测试"、"补测试"、"UT"、"unit test"、"测试覆盖率"。
|
|
11
|
+
|
|
12
|
+
**审查** — 当用户需要代码审查时触发。
|
|
13
|
+
关键词:"review"、"审查"、"code review"、"检查代码"、"帮我看看这段代码"。
|
|
14
|
+
|
|
15
|
+
**不触发(留给 auto-goal)**:纯分析、调研、非代码产出任务。
|
|
16
|
+
**不触发(直接工具)**:单文件几行代码的简单修改。
|
|
17
|
+
allowed-tools: Read, Write, Edit, Bash, Agent, Glob, Grep, Skill, TaskCreate, TaskUpdate, TaskList, EnterPlanMode, ExitPlanMode, AskUserQuestion
|
|
18
|
+
---
|
|
19
|
+
|
|
20
|
+
# Coding Skill — 代码域认知协议
|
|
21
|
+
|
|
22
|
+
继承 auto-goal 的六字原则(序验深广辨简)和 OODA 循环,适配代码域特性:
|
|
23
|
+
**编译和测试是天然证伪器;代码变更即假设检验;版本控制提供安全回退。**
|
|
24
|
+
|
|
25
|
+
---
|
|
26
|
+
|
|
27
|
+
## 1. 意图路由
|
|
28
|
+
|
|
29
|
+
进入 skill 后,首先识别用户意图:
|
|
30
|
+
|
|
31
|
+
| 意图 | 信号 | 加载参考 | 核心交付物 |
|
|
32
|
+
|------|------|----------|-----------|
|
|
33
|
+
| **实现** | 功能开发、bug修复、重构 | `references/implement-guide.md` | 可编译运行的代码变更 |
|
|
34
|
+
| **测试** | 生成/修复单元测试 | `references/unit-test-guide.md` | 通过的测试类 + 覆盖率 |
|
|
35
|
+
| **审查** | review、检查代码质量 | `references/code-review-guide.md` | 分级审查报告 |
|
|
36
|
+
|
|
37
|
+
**路由规则**:
|
|
38
|
+
- 信号明确 → 直接路由,加载对应参考
|
|
39
|
+
- 信号模糊 → 从上下文推断(有 diff → 审查;提到测试 → 测试;其余 → 实现)
|
|
40
|
+
- 混合意图 → 拆分为顺序子任务(如"实现功能并补测试"→ 先实现后测试)
|
|
41
|
+
|
|
42
|
+
---
|
|
43
|
+
|
|
44
|
+
## 2. 复杂度适配
|
|
45
|
+
|
|
46
|
+
识别意图后,评估复杂度选择执行路径:
|
|
47
|
+
|
|
48
|
+
### 轻量(识别即行动)
|
|
49
|
+
- **判据**:单文件、改动位置明确、影响范围清晰
|
|
50
|
+
- **执行**:直接 Read → Edit → 验证,无需规划文件
|
|
51
|
+
- **示例**:修 typo、改常量、添加简单 mock、单方法 review
|
|
52
|
+
|
|
53
|
+
### 标准(规划后执行)
|
|
54
|
+
- **判据**:多文件但边界清晰、需要理解调用关系
|
|
55
|
+
- **执行**:EnterPlanMode → 探索 → 规划 → ExitPlanMode → 用户确认 → 执行 → 验证
|
|
56
|
+
- **示例**:添加 API、跨类重构、完整测试类、多文件 review
|
|
57
|
+
|
|
58
|
+
### 深度(状态外化 + 分阶段)
|
|
59
|
+
- **判据**:跨系统多层面、需分阶段完成、可能跨会话
|
|
60
|
+
- **执行**:创建 `.tasks/coding-{slug}/state.md` → 分 Phase 执行 → 每阶段验证 + 更新状态
|
|
61
|
+
- **示例**:架构迁移、大规模重构、批量测试生成(10+ 类)、大型变更审查
|
|
62
|
+
|
|
63
|
+
**升级信号**:验证失败、影响范围超预期、依赖关系比预想复杂 → 升级到更高层级。
|
|
64
|
+
**降级信号**:进展顺利、不确定性收敛 → 可简化后续步骤。
|
|
65
|
+
|
|
66
|
+
---
|
|
67
|
+
|
|
68
|
+
## 3. 代码域 OODA 循环
|
|
69
|
+
|
|
70
|
+
在 auto-goal 的 OODA 基础上,注入代码域特有认知:
|
|
71
|
+
|
|
72
|
+
### Sense — 感知代码现状
|
|
73
|
+
- **读代码前先建假设**:从命名、结构、上下文推测行为,再读代码验证
|
|
74
|
+
- **依赖图谱**:识别被修改代码的上下游依赖
|
|
75
|
+
- **弱信号**:编译警告、废弃 API 调用、异常的命名模式、过深嵌套
|
|
76
|
+
- **大范围探索用 sub-agent**:超过 5 个文件的代码探索,委托给 Agent(subagent_type: "Explore")
|
|
77
|
+
|
|
78
|
+
### Orient — 定位问题与方案空间
|
|
79
|
+
- **域判断**:
|
|
80
|
+
- Clear:已知 pattern(如标准 CRUD、常见 mock 设置)→ 识别即行动
|
|
81
|
+
- Complicated:需分析调用链/数据流 → 探索后规划
|
|
82
|
+
- Complex:行为不可预测(并发、分布式、遗留代码)→ 小步试探
|
|
83
|
+
- Chaotic:生产事故 → 先止血(回滚/hotfix),再诊断
|
|
84
|
+
- **心智模型更新**:每次读到新信息,检查是否需要修正之前的假设
|
|
85
|
+
|
|
86
|
+
### Decide — 选择策略
|
|
87
|
+
- **方案评估**:不可逆变更(删除代码、修改接口)→ 生成备选方案,评估后决策
|
|
88
|
+
- **验证策略**:根据风险级别选择——
|
|
89
|
+
- 微验证:心理走查(低风险局部改动)
|
|
90
|
+
- 标准验证:编译 + 单元测试(常规变更)
|
|
91
|
+
- 深度验证:集成测试 + 回归 + code review(高风险/公共接口变更)
|
|
92
|
+
|
|
93
|
+
### Act — 执行代码变更
|
|
94
|
+
- **每次变更是一个假设**:"修改 X 应该产生效果 Y"
|
|
95
|
+
- **优先核心路径**:先让主流程跑通,再处理边界和异常
|
|
96
|
+
- **原子变更**:每个 Edit 有明确目的,避免一次性大范围修改
|
|
97
|
+
- **代码质量内建**:编写时即遵循 clean-code 原则,不留"以后再改"
|
|
98
|
+
|
|
99
|
+
### Observe — 验证结果
|
|
100
|
+
- **编译是第一道证伪**:改完就编译,不攒到最后
|
|
101
|
+
- **测试是第二道证伪**:运行相关测试,关注失败测试的信息量
|
|
102
|
+
- **预期 vs 实际**:结果符合预期 → 继续;不符合 → 停下来,进入 Adapt
|
|
103
|
+
- **意外成功也要分析**:测试通过但不确定为什么 → 追查原因,避免假阳性
|
|
104
|
+
|
|
105
|
+
### Adapt — 调整策略
|
|
106
|
+
- **Reflect-then-Retry**:失败时不盲目重试,先分析根因分类:
|
|
107
|
+
1. 理解偏差 → 重新读代码
|
|
108
|
+
2. 知识不足 → 查文档/搜索
|
|
109
|
+
3. 规划缺陷 → 修正方案
|
|
110
|
+
4. 执行错误 → 修正代码
|
|
111
|
+
5. 环境变化 → 重新评估约束
|
|
112
|
+
- **三次失败熔断**:同一问题重试 3 次仍失败 → 换策略或向用户透明报告
|
|
113
|
+
- **更新状态文件**(深度任务):记录决策变更和新发现
|
|
114
|
+
|
|
115
|
+
---
|
|
116
|
+
|
|
117
|
+
## 4. 上下文工程
|
|
118
|
+
|
|
119
|
+
代码域的上下文管理策略:
|
|
120
|
+
|
|
121
|
+
### 隔离(保护主上下文)
|
|
122
|
+
- 代码探索(调用链、影响范围、模式搜索)→ Agent(subagent_type: "Explore")
|
|
123
|
+
- 只将探索结论回传主上下文,原始搜索结果留在 sub-agent
|
|
124
|
+
- **何时用 sub-agent**:不确定要找什么 / 需要跨多文件搜索 / 结果量大
|
|
125
|
+
- **何时直接操作**:精确知道文件和位置 / 单文件 Read + Grep
|
|
126
|
+
|
|
127
|
+
### 压缩
|
|
128
|
+
- 已完成的 Phase 压缩为摘要,保留:变更了什么文件、关键决策、验证结果
|
|
129
|
+
- 大段代码分析结论提炼为要点
|
|
130
|
+
|
|
131
|
+
### 外化(深度任务)
|
|
132
|
+
状态文件结构(`.tasks/coding-{slug}/state.md`):
|
|
133
|
+
```markdown
|
|
134
|
+
# {Task Title}
|
|
135
|
+
Type: coding
|
|
136
|
+
Status: in-progress
|
|
137
|
+
Created: {YYYY-MM-DD}
|
|
138
|
+
Updated: {YYYY-MM-DD HH:MM}
|
|
139
|
+
Intent: implement | test | review
|
|
140
|
+
|
|
141
|
+
## Goal
|
|
142
|
+
{目标 + 验收标准}
|
|
143
|
+
|
|
144
|
+
## Mental Model
|
|
145
|
+
{当前理解:关键假设、已验证事实、未知区域}
|
|
146
|
+
|
|
147
|
+
## Progress
|
|
148
|
+
### Phase N: {title} — {pending|in-progress|done}
|
|
149
|
+
- Objective: ...
|
|
150
|
+
- Steps: [x] done / [ ] todo
|
|
151
|
+
- Verification: ...
|
|
152
|
+
- Summary: {完成后填写}
|
|
153
|
+
|
|
154
|
+
## Decisions
|
|
155
|
+
- {决策}: {理由} (备选: {被否方案})
|
|
156
|
+
|
|
157
|
+
## Files Modified
|
|
158
|
+
- {path}: {变更说明}
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
### 按需加载
|
|
162
|
+
- 意图确定后才加载对应 reference 文件
|
|
163
|
+
- 大文件用 offset/limit 分段读取
|
|
164
|
+
- 已完成阶段的代码细节不重复读取
|
|
165
|
+
|
|
166
|
+
---
|
|
167
|
+
|
|
168
|
+
## 5. 交付规范
|
|
169
|
+
|
|
170
|
+
### 实现意图
|
|
171
|
+
|
|
172
|
+
**执行后**:
|
|
173
|
+
- 所有变更文件编译通过
|
|
174
|
+
- 相关测试通过(如有)
|
|
175
|
+
- 简要变更摘要(改了什么、为什么、影响范围)
|
|
176
|
+
|
|
177
|
+
**执行摘要**:
|
|
178
|
+
```
|
|
179
|
+
完成: {简述}
|
|
180
|
+
变更: {文件列表}
|
|
181
|
+
验证: {编译/测试结果}
|
|
182
|
+
遗留: {如有}
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
### 测试意图
|
|
186
|
+
|
|
187
|
+
**执行后**:
|
|
188
|
+
- 测试类编译通过
|
|
189
|
+
- 所有测试用例通过
|
|
190
|
+
- 覆盖率达标(行 >= 80%,分支 >= 70%)
|
|
191
|
+
|
|
192
|
+
**交付格式**:
|
|
193
|
+
```
|
|
194
|
+
被测类: XxxService
|
|
195
|
+
测试类: XxxServiceTest
|
|
196
|
+
用例数: N (正常M + 异常K + 边界J)
|
|
197
|
+
覆盖率: 行 XX% / 分支 XX%
|
|
198
|
+
框架: JUnit X + Mockito/PowerMock
|
|
199
|
+
```
|
|
200
|
+
|
|
201
|
+
### 审查意图
|
|
202
|
+
|
|
203
|
+
**执行后**:
|
|
204
|
+
- 分级审查报告(Critical / Warning / Suggestion / Positive)
|
|
205
|
+
- 每个问题有文件路径、行号、具体修复建议
|
|
206
|
+
- 报告保存到 `.tasks/coding-{slug}/code-review-report.md`
|
|
207
|
+
|
|
208
|
+
**报告分级**:
|
|
209
|
+
- **Critical** — 可能导致生产事故的 bug 或安全漏洞
|
|
210
|
+
- **Warning** — 代码坏味道或潜在风险
|
|
211
|
+
- **Suggestion** — 可改进的设计和最佳实践
|
|
212
|
+
- **Positive** — 值得肯定的设计和实现
|
|
213
|
+
|
|
214
|
+
详细报告模板见 `references/code-review-guide.md`。
|
|
215
|
+
|
|
216
|
+
---
|
|
217
|
+
|
|
218
|
+
## 6. 恢复协议
|
|
219
|
+
|
|
220
|
+
当用户说"继续"且存在 `.tasks/coding-*/state.md`:
|
|
221
|
+
|
|
222
|
+
1. 读取 state.md,提取 Status、Intent、当前 Phase
|
|
223
|
+
2. **信任但验证**:用 Glob/Read 确认已完成 Phase 的产出确实存在
|
|
224
|
+
3. 从当前 in-progress 或下一个 pending Phase 继续
|
|
225
|
+
4. 用 TaskCreate 重建 UI 进度(仅未完成部分)
|
|
226
|
+
|
|
227
|
+
---
|
|
228
|
+
|
|
229
|
+
## 7. 反模式
|
|
230
|
+
|
|
231
|
+
| 反模式 | 代码域表现 | 解药 |
|
|
232
|
+
|--------|-----------|------|
|
|
233
|
+
| 盲目重试 | 编译失败后不看错误直接改 | 读错误信息,分类根因再修 |
|
|
234
|
+
| 过度探索 | 读了 20 个文件还没开始改 | 设探索预算,够用就停 |
|
|
235
|
+
| 假阳性信心 | 测试通过但不理解为什么 | 追查通过原因,排除巧合 |
|
|
236
|
+
| 一次性大改 | 攒了 10 个文件最后一起编译 | 原子变更,改一步验一步 |
|
|
237
|
+
| 模板依赖 | 套模板而不理解上下文 | 理解优先,模板参考而非照搬 |
|
|
238
|
+
| 噪声交付 | 报告充斥通用建议 | 只报告该上下文特有的发现 |
|
|
239
|
+
|
|
240
|
+
---
|
|
241
|
+
|
|
242
|
+
## 8. 深度参考
|
|
243
|
+
|
|
244
|
+
按需加载,仅在对应意图激活时读取:
|
|
245
|
+
|
|
246
|
+
| 参考文件 | 适用意图 | 内容 |
|
|
247
|
+
|----------|---------|------|
|
|
248
|
+
| `references/implement-guide.md` | 实现 | sub-agent 使用原则、Plan Mode 要点 |
|
|
249
|
+
| `references/unit-test-guide.md` | 测试 | 框架适配、mock 陷阱、覆盖率策略 |
|
|
250
|
+
| `references/code-review-guide.md` | 审查 | 三层分析框架、报告模板、diff 获取 |
|
|
251
|
+
| `references/code-smells.md` | 审查 | Bug 风险、坏味道、设计问题详细清单 |
|
|
@@ -0,0 +1,137 @@
|
|
|
1
|
+
# 代码审查意图深度参考
|
|
2
|
+
|
|
3
|
+
> 当 coding skill 路由到"审查"意图时按需加载。
|
|
4
|
+
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
## Diff 获取
|
|
8
|
+
|
|
9
|
+
### 标准流程(分支对比)
|
|
10
|
+
|
|
11
|
+
```bash
|
|
12
|
+
# 找共同祖先
|
|
13
|
+
git merge-base HEAD master
|
|
14
|
+
|
|
15
|
+
# 获取完整 diff
|
|
16
|
+
git diff master...HEAD
|
|
17
|
+
|
|
18
|
+
# 变更文件列表
|
|
19
|
+
git diff --name-only master...HEAD
|
|
20
|
+
|
|
21
|
+
# 变更统计
|
|
22
|
+
git diff --stat master...HEAD
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
### 备选场景
|
|
26
|
+
|
|
27
|
+
- 无 diff 可获取 → 询问用户目标分支或请提供 diff 内容
|
|
28
|
+
- 用户直接提供代码片段 → 对提供的代码进行审查
|
|
29
|
+
|
|
30
|
+
---
|
|
31
|
+
|
|
32
|
+
## 三层分析框架
|
|
33
|
+
|
|
34
|
+
### 第一层:核心关注点(What)
|
|
35
|
+
|
|
36
|
+
| 维度 | 关键问题 |
|
|
37
|
+
|------|---------|
|
|
38
|
+
| **正确性** | 逻辑是否正确?边界条件?隐藏错误? |
|
|
39
|
+
| **健壮性** | 异常处理?输入验证?资源释放? |
|
|
40
|
+
| **可维护性** | 意图清晰?修改一处会破坏其他吗? |
|
|
41
|
+
| **可测试性** | 容易验证吗?依赖可替换吗? |
|
|
42
|
+
| **安全性** | 注入风险?敏感数据处理?权限检查? |
|
|
43
|
+
|
|
44
|
+
### 第二层:分析方法(How)
|
|
45
|
+
|
|
46
|
+
**数据流分析**:数据从哪来 → 在哪变换 → 到哪去。变换中有丢失、污染、类型不匹配吗?
|
|
47
|
+
|
|
48
|
+
**控制流分析**:所有分支覆盖?循环边界正确?并发竞态?异常路径?
|
|
49
|
+
|
|
50
|
+
**依赖分析**:耦合度?接口稳定性?循环依赖?隐式依赖?
|
|
51
|
+
|
|
52
|
+
**契约分析**:前置条件满足?后置条件保证?不变量维护?异常契约?
|
|
53
|
+
|
|
54
|
+
### 第三层:具体清单(Checklist)
|
|
55
|
+
|
|
56
|
+
详见 `references/code-smells.md`。按复杂度适配使用:
|
|
57
|
+
- **轻量审查**:只看第一层核心关注点
|
|
58
|
+
- **标准审查**:第一层 + 第二层分析方法
|
|
59
|
+
- **深度审查**:三层全覆盖 + code-smells.md 完整清单
|
|
60
|
+
|
|
61
|
+
---
|
|
62
|
+
|
|
63
|
+
## 审查原则
|
|
64
|
+
|
|
65
|
+
1. **正确性优先**:Bug 风险 > 坏味道 > 设计建议
|
|
66
|
+
2. **由抽象到具体**:先理解整体设计意图,再检查实现细节
|
|
67
|
+
3. **具体可操作**:每个问题必须有文件路径、行号、修复建议
|
|
68
|
+
4. **只报告该上下文特有的发现**:避免通用的"最佳实践"建议
|
|
69
|
+
5. **平衡**:既指出问题,也肯定好的实践
|
|
70
|
+
6. **分级**:区分"必须修复"、"建议修复"、"可选优化"
|
|
71
|
+
|
|
72
|
+
---
|
|
73
|
+
|
|
74
|
+
## 报告模板
|
|
75
|
+
|
|
76
|
+
```markdown
|
|
77
|
+
# 代码审查报告
|
|
78
|
+
|
|
79
|
+
## 变更概览
|
|
80
|
+
- 分支: `<current-branch>` -> `master`
|
|
81
|
+
- 变更文件数: X 个
|
|
82
|
+
- 新增/删除: +XXX / -XXX
|
|
83
|
+
|
|
84
|
+
## Critical — 可能导致生产事故
|
|
85
|
+
|
|
86
|
+
### 1. [文件路径:行号] 问题标题
|
|
87
|
+
**问题**: 具体描述
|
|
88
|
+
**影响**: 可能造成什么后果
|
|
89
|
+
**修复**: 具体建议
|
|
90
|
+
```语言
|
|
91
|
+
// 问题代码
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
## Warning — 坏味道或潜在风险
|
|
95
|
+
|
|
96
|
+
### 1. [文件路径:行号] 问题标题
|
|
97
|
+
**问题**: ...
|
|
98
|
+
**建议**: ...
|
|
99
|
+
|
|
100
|
+
## Suggestion — 可改进项
|
|
101
|
+
|
|
102
|
+
### 1. [文件路径:行号] 建议标题
|
|
103
|
+
**现状**: ...
|
|
104
|
+
**建议**: ...
|
|
105
|
+
|
|
106
|
+
## Positive — 值得肯定
|
|
107
|
+
|
|
108
|
+
- ...
|
|
109
|
+
|
|
110
|
+
## 总结
|
|
111
|
+
- Critical: X | Warning: X | Suggestion: X
|
|
112
|
+
- 整体评价: ...
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
报告保存到 `.tasks/coding-{slug}/code-review-report.md`。
|
|
116
|
+
|
|
117
|
+
---
|
|
118
|
+
|
|
119
|
+
## 大型变更处理
|
|
120
|
+
|
|
121
|
+
变更文件超过 20 个或代码行变化超过 1000 行时:
|
|
122
|
+
|
|
123
|
+
1. 优先审查核心逻辑变更
|
|
124
|
+
2. 配置文件、生成代码可简化审查
|
|
125
|
+
3. 可建议分多次 review
|
|
126
|
+
4. 使用 sub-agent 并行分析不同模块
|
|
127
|
+
|
|
128
|
+
---
|
|
129
|
+
|
|
130
|
+
## 语言特定检查要点
|
|
131
|
+
|
|
132
|
+
| 语言 | 重点关注 |
|
|
133
|
+
|------|---------|
|
|
134
|
+
| Java/Kotlin | Optional 使用、Stream API、Spring 最佳实践、自动装箱 |
|
|
135
|
+
| Python | 可变默认参数、异常粒度、上下文管理器、类型注解 |
|
|
136
|
+
| JS/TS | 隐式转换、异步处理、any 滥用、this 绑定 |
|
|
137
|
+
| Go | error 处理、context 使用、goroutine 泄漏 |
|