@elvis1513/auto-coding-skill 2.1.4 → 2.2.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/README.md +163 -554
- package/cli/assets/agents/browser-debugger.toml +0 -1
- package/cli/assets/agents/docs-researcher.toml +0 -1
- package/cli/assets/agents/explorer.toml +1 -2
- package/cli/assets/agents/fixer.toml +2 -3
- package/cli/assets/agents/reviewer.toml +1 -2
- package/cli/assets/skill/SKILL.md +98 -207
- package/cli/assets/skill/data/templates/ENGINEERING.md +113 -468
- package/cli/assets/skill/data/templates/docs/tasks/closure-log.md +11 -22
- package/cli/assets/skill/data/templates/docs/tasks/taskbook.md +16 -39
- package/cli/assets/skill/data/templates/tools/ap.py +16 -0
- package/cli/assets/skill/scripts/ap.py +703 -138
- package/cli/assets/skill/scripts/scaffold_templates.py +136 -0
- package/cli/src/index.js +317 -42
- package/cli/tests/ap_profiles_test.py +428 -0
- package/cli/tests/index.test.js +376 -87
- package/package.json +3 -3
- package/cli/assets/skill/data/templates/docs/architecture/adr/_TEMPLATE-ADR.md +0 -38
- package/cli/assets/skill/data/templates/docs/architecture/structure-standard.md +0 -92
- package/cli/assets/skill/data/templates/docs/bugs/bug-list.md +0 -5
- package/cli/assets/skill/data/templates/docs/deployment/deploy-records/_TEMPLATE-DEPLOY-RECORD.md +0 -19
- package/cli/assets/skill/data/templates/docs/deployment/deploy-runbook.md +0 -11
- package/cli/assets/skill/data/templates/docs/design/_TEMPLATE-DD.md +0 -49
- package/cli/assets/skill/data/templates/docs/interfaces/api-change-log.md +0 -11
- package/cli/assets/skill/data/templates/docs/interfaces/api.md +0 -36
- package/cli/assets/skill/data/templates/docs/reviews/_TEMPLATE-REVIEW.md +0 -36
- package/cli/assets/skill/data/templates/docs/reviews/optimization-backlog.md +0 -25
- package/cli/assets/skill/data/templates/docs/reviews/project-health-baseline.md +0 -66
- package/cli/assets/skill/data/templates/docs/tasks/summaries/_TEMPLATE-TASK-SUMMARY.md +0 -35
- package/cli/assets/skill/data/templates/docs/testing/regression-matrix.md +0 -11
|
@@ -1,32 +1,20 @@
|
|
|
1
1
|
---
|
|
2
2
|
workflow:
|
|
3
3
|
mode: "dev"
|
|
4
|
+
profile: "auto"
|
|
4
5
|
|
|
5
6
|
project:
|
|
6
7
|
name: ""
|
|
7
8
|
repo_root: "."
|
|
8
9
|
stack: "generic"
|
|
9
|
-
backend_dir: ""
|
|
10
|
-
frontend_dir: ""
|
|
11
|
-
go_main: ""
|
|
12
|
-
dockerfile: ""
|
|
13
|
-
jenkinsfile: "Jenkinsfile"
|
|
14
10
|
|
|
15
11
|
commands:
|
|
16
12
|
gate_changed: ""
|
|
17
13
|
gate_standard: ""
|
|
18
14
|
gate_full: ""
|
|
19
|
-
structure_check: ""
|
|
20
|
-
light_gate: ""
|
|
21
|
-
build: ""
|
|
22
|
-
test: ""
|
|
23
|
-
quick_test: ""
|
|
24
|
-
lint: ""
|
|
25
|
-
typecheck: ""
|
|
26
|
-
format: ""
|
|
27
15
|
|
|
28
16
|
gate:
|
|
29
|
-
default_scope: "
|
|
17
|
+
default_scope: "auto"
|
|
30
18
|
fallback_scope: "standard"
|
|
31
19
|
full_on_unknown: true
|
|
32
20
|
no_change_scope: "standard"
|
|
@@ -57,7 +45,8 @@ gate:
|
|
|
57
45
|
|
|
58
46
|
structure:
|
|
59
47
|
enabled: true
|
|
60
|
-
|
|
48
|
+
enforcement: "advisory"
|
|
49
|
+
architecture_standard: "project-defined"
|
|
61
50
|
max_file_lines_warn: 800
|
|
62
51
|
max_file_lines_block: 1500
|
|
63
52
|
max_function_lines_warn: 120
|
|
@@ -69,125 +58,27 @@ structure:
|
|
|
69
58
|
- "docs/tools/autopipeline/**"
|
|
70
59
|
- "generated/**"
|
|
71
60
|
- "**/generated/**"
|
|
72
|
-
- "**/__generated__/**"
|
|
73
61
|
- "vendor/**"
|
|
74
62
|
- "dist/**"
|
|
75
63
|
- "build/**"
|
|
76
64
|
- "target/**"
|
|
77
65
|
- "node_modules/**"
|
|
78
66
|
- "**/*.generated.*"
|
|
79
|
-
- "**/*.gen.*"
|
|
80
67
|
- "**/*.min.js"
|
|
81
|
-
- "**/*.bundle.js"
|
|
82
68
|
- "**/*.map"
|
|
83
69
|
accepted_debt_paths: []
|
|
84
70
|
layer_rules:
|
|
85
71
|
enabled: true
|
|
86
|
-
block:
|
|
87
|
-
rules:
|
|
88
|
-
- name: "domain"
|
|
89
|
-
paths:
|
|
90
|
-
- "**/domain/**"
|
|
91
|
-
- "**/domains/**"
|
|
92
|
-
- "**/model/**"
|
|
93
|
-
- "**/models/**"
|
|
94
|
-
forbidden_imports:
|
|
95
|
-
- "**/infrastructure/**"
|
|
96
|
-
- "**/infra/**"
|
|
97
|
-
- "**/adapter/**"
|
|
98
|
-
- "**/repository/**"
|
|
99
|
-
- "**/repositories/**"
|
|
100
|
-
- "**/client/**"
|
|
101
|
-
- "**/clients/**"
|
|
102
|
-
- "**/controller/**"
|
|
103
|
-
- "**/handler/**"
|
|
104
|
-
- "**/page/**"
|
|
105
|
-
- "**/pages/**"
|
|
106
|
-
- "**/component/**"
|
|
107
|
-
- "**/components/**"
|
|
108
|
-
- "**/view/**"
|
|
109
|
-
- "**/views/**"
|
|
110
|
-
- name: "application"
|
|
111
|
-
paths:
|
|
112
|
-
- "**/application/**"
|
|
113
|
-
- "**/service/**"
|
|
114
|
-
- "**/services/**"
|
|
115
|
-
- "**/usecase/**"
|
|
116
|
-
- "**/usecases/**"
|
|
117
|
-
forbidden_imports:
|
|
118
|
-
- "**/controller/**"
|
|
119
|
-
- "**/handler/**"
|
|
120
|
-
- "**/page/**"
|
|
121
|
-
- "**/pages/**"
|
|
122
|
-
- "**/component/**"
|
|
123
|
-
- "**/components/**"
|
|
124
|
-
- "**/view/**"
|
|
125
|
-
- "**/views/**"
|
|
126
|
-
- name: "shared"
|
|
127
|
-
paths:
|
|
128
|
-
- "**/shared/**"
|
|
129
|
-
- "**/common/**"
|
|
130
|
-
- "**/utils/**"
|
|
131
|
-
- "**/lib/**"
|
|
132
|
-
forbidden_imports:
|
|
133
|
-
- "**/domain/**"
|
|
134
|
-
- "**/application/**"
|
|
135
|
-
- "**/service/**"
|
|
136
|
-
- "**/services/**"
|
|
137
|
-
- "**/infrastructure/**"
|
|
138
|
-
- "**/controller/**"
|
|
139
|
-
- "**/page/**"
|
|
140
|
-
- "**/pages/**"
|
|
141
|
-
reusable_tool_dirs:
|
|
142
|
-
- "docs/tools/**"
|
|
143
|
-
- "scripts/**"
|
|
144
|
-
- "tools/**"
|
|
145
|
-
- "packages/*/src/**"
|
|
146
|
-
- "src/**/shared/**"
|
|
147
|
-
- "src/**/utils/**"
|
|
72
|
+
block: false
|
|
148
73
|
|
|
149
74
|
optimization:
|
|
150
75
|
completion_policy: "baseline-aware"
|
|
151
|
-
require_baseline_for_global_review:
|
|
76
|
+
require_baseline_for_global_review: false
|
|
152
77
|
report_accepted_debt_as_findings: false
|
|
153
78
|
|
|
154
|
-
runtime:
|
|
155
|
-
docker_compose_file: ""
|
|
156
|
-
docker_service: ""
|
|
157
|
-
health_base_url: ""
|
|
158
|
-
health_path: ""
|
|
159
|
-
env_file: ""
|
|
160
|
-
startup_timeout_sec: 120
|
|
161
|
-
|
|
162
79
|
verification:
|
|
163
|
-
target_env_required:
|
|
164
|
-
jenkins_required:
|
|
165
|
-
|
|
166
|
-
target_env:
|
|
167
|
-
name: ""
|
|
168
|
-
frontend_base_url: ""
|
|
169
|
-
frontend_username: ""
|
|
170
|
-
frontend_password_env: ""
|
|
171
|
-
backend_base_url: ""
|
|
172
|
-
backend_username: ""
|
|
173
|
-
backend_password_env: ""
|
|
174
|
-
backend_root_username: ""
|
|
175
|
-
backend_root_password_env: ""
|
|
176
|
-
health_base_url: ""
|
|
177
|
-
health_path: ""
|
|
178
|
-
|
|
179
|
-
jenkins:
|
|
180
|
-
base_url: ""
|
|
181
|
-
ui_username: ""
|
|
182
|
-
ui_password_env: ""
|
|
183
|
-
job_url: ""
|
|
184
|
-
trigger_branch: ""
|
|
185
|
-
image_repository: ""
|
|
186
|
-
image_tag_strategy: ""
|
|
187
|
-
deploy_env: ""
|
|
188
|
-
deploy_timeout_sec: 1800
|
|
189
|
-
api_user: ""
|
|
190
|
-
api_password_env: ""
|
|
80
|
+
target_env_required: false
|
|
81
|
+
jenkins_required: false
|
|
191
82
|
|
|
192
83
|
docs:
|
|
193
84
|
taskbook: "docs/tasks/taskbook.md"
|
|
@@ -202,11 +93,10 @@ docs:
|
|
|
202
93
|
active_taskbook_max_lines: 1200
|
|
203
94
|
active_closure_log_max_lines: 800
|
|
204
95
|
active_design_max_files: 120
|
|
205
|
-
review_dir: "docs/reviews"
|
|
206
96
|
health_baseline: "docs/reviews/project-health-baseline.md"
|
|
207
97
|
optimization_backlog: "docs/reviews/optimization-backlog.md"
|
|
208
98
|
structure_standard: "docs/architecture/structure-standard.md"
|
|
209
|
-
|
|
99
|
+
api_docs_required: false
|
|
210
100
|
api_doc: "docs/interfaces/api.md"
|
|
211
101
|
api_change_log: "docs/interfaces/api-change-log.md"
|
|
212
102
|
regression_matrix: "docs/testing/regression-matrix.md"
|
|
@@ -214,361 +104,116 @@ docs:
|
|
|
214
104
|
summary_dir: "docs/tasks/summaries"
|
|
215
105
|
---
|
|
216
106
|
|
|
217
|
-
#
|
|
218
|
-
|
|
219
|
-
目标:默认采用高效率开发闭环,并通过 `workflow.mode` 控制流程长度。
|
|
220
|
-
|
|
221
|
-
- `dev`:开发模式,最快闭环。轻量门禁通过后,提前写 `DEV-CLOSED` 闭环,commit + push 后结束。
|
|
222
|
-
- `verify`:验证模式,完整闭环。轻量门禁、commit + push、已启用的 CI/Jenkins 构建验证和目标环境验证全部完成后,写 `PASS` 闭环。
|
|
223
|
-
|
|
224
|
-
默认原则:
|
|
225
|
-
- 默认不要求本地 Docker Compose 启动。
|
|
226
|
-
- 默认不要求本地 Docker build。
|
|
227
|
-
- 默认不要求本地完整 regression。
|
|
228
|
-
- 默认不要求每个小改动生成长 summary。
|
|
229
|
-
- 默认不要求 regression matrix 全 PASS。
|
|
230
|
-
- 默认不要求 deployment record。
|
|
231
|
-
- 已启用的 CI/Jenkins 构建结果和目标环境真实验证,比本地模拟更重要。
|
|
232
|
-
|
|
233
|
-
补充规则:
|
|
234
|
-
- 每次任务闭环后,必须清理临时文件、临时目录、日志、截图、构建缓存等非必要产物;仅明确需要保留的本地诊断目录允许保留。
|
|
235
|
-
- 所有手工填写信息,只维护在本文件 frontmatter 中,其他文档不得重复配置。
|
|
236
|
-
- `docs/ENGINEERING.md` 必须提交到 Git 管理,不允许写入 `.gitignore`。
|
|
237
|
-
- 目标环境和 Jenkins 密码默认通过 `*_password_env` 指向当前 shell 中的环境变量;确需兼容旧项目时才使用明文 `*_password` 字段。
|
|
238
|
-
- 非 Jenkins 或本地-only 项目可以把 `verification.jenkins_required` / `verification.target_env_required` 设为 `false`,让 `doctor` 只检查通用门禁、文档和结构配置。
|
|
239
|
-
- 未参与默认流程的环境项不要保留占位;模板中未保留的字段视为已清理,不再额外配置。
|
|
240
|
-
|
|
241
|
-
---
|
|
242
|
-
|
|
243
|
-
## 0. 配置填写(必须)
|
|
244
|
-
|
|
245
|
-
先填写 `docs/ENGINEERING.md` frontmatter 中的所有空值。重点包括:
|
|
246
|
-
- `workflow.mode`:`dev` 或 `verify`,默认推荐 `dev`
|
|
247
|
-
- `commands.gate_changed` / `commands.gate_standard` / `commands.gate_full`:推荐配置分层门禁命令;旧项目也可以继续只配置 `commands.light_gate`
|
|
248
|
-
- `gate.*`:按项目声明路径规则和高风险升级规则;未配置时保持标准门禁行为
|
|
249
|
-
- `commands.structure_check`:可覆盖内置结构检查;留空时使用通用 `ap.py structure-check`
|
|
250
|
-
- `structure.*`:通用工程结构阈值、允许的大文件模式、复用搜索目录
|
|
251
|
-
- `structure.layer_rules`:通用分层 import 边界检查;项目可按技术栈细化路径
|
|
252
|
-
- `optimization.*`:健康基线感知的优化闭环口径,避免重复把已接受债务判定为当前未完成
|
|
253
|
-
- `verification.target_env_required` / `verification.jenkins_required`:控制 `doctor` 是否强校验目标环境和 Jenkins 配置
|
|
254
|
-
- `docs.evidence_log`:结构化证据 JSONL,记录 doctor / gate / verify / closure 等实际执行结果
|
|
255
|
-
- `docs.task_archive_dir` / `docs.design_archive_dir` / `docs.archive_index`:文档账本物理归档目录和导航索引;索引不能替代归档
|
|
256
|
-
- `docs.active_taskbook_max_lines` / `docs.active_closure_log_max_lines` / `docs.active_design_max_files`:活跃账本预算,超过后必须归档瘦身
|
|
257
|
-
- `docs.health_baseline` / `docs.optimization_backlog` / `docs.structure_standard` / `docs.adr_dir`:项目结构治理文档位置
|
|
258
|
-
- `target_env.*`:当 `verification.target_env_required: true` 时,目标环境前端 / 后端地址、用户名、密码引用必须全部填写且真实可用
|
|
259
|
-
- `jenkins.*`:当 `verification.jenkins_required: true` 时,Jenkins UI/API 用户名、密码引用、Job、分支、镜像、部署环境必须全部填写且真实可用
|
|
260
|
-
|
|
261
|
-
字段说明:
|
|
262
|
-
- `target_env.backend_username` + `target_env.backend_password_env` 或 `target_env.backend_password`:目标环境后台账号
|
|
263
|
-
- `target_env.backend_root_username` + `target_env.backend_root_password_env` 或 `target_env.backend_root_password`:目标环境后台服务器 root 账号
|
|
264
|
-
- `target_env.frontend_username` + `target_env.frontend_password_env` 或 `target_env.frontend_password`:目标环境前端登录账号
|
|
265
|
-
- `jenkins.ui_username` + `jenkins.ui_password_env` 或 `jenkins.ui_password`:Jenkins 页面登录账号
|
|
266
|
-
- `jenkins.api_user` + `jenkins.api_password_env` 或 `jenkins.api_password`:Jenkins API 用户名 / 密码
|
|
267
|
-
|
|
268
|
-
默认必填:
|
|
269
|
-
- `workflow.mode`
|
|
270
|
-
- `project.name`
|
|
271
|
-
- `commands.gate_changed` / `commands.gate_standard` / `commands.gate_full`,或 `commands.light_gate` / `commands.quick_test` / `commands.test` / `commands.build`
|
|
272
|
-
- `verification.target_env_required`
|
|
273
|
-
- `verification.jenkins_required`
|
|
274
|
-
|
|
275
|
-
当 `verification.target_env_required: true` 时必填:
|
|
276
|
-
- `target_env.name`
|
|
277
|
-
- `target_env.frontend_base_url`
|
|
278
|
-
- `target_env.frontend_username`
|
|
279
|
-
- `target_env.frontend_password` 或 `target_env.frontend_password_env`
|
|
280
|
-
- `target_env.backend_base_url`
|
|
281
|
-
- `target_env.backend_username`
|
|
282
|
-
- `target_env.backend_password` 或 `target_env.backend_password_env`
|
|
283
|
-
- `target_env.backend_root_username`
|
|
284
|
-
- `target_env.backend_root_password` 或 `target_env.backend_root_password_env`
|
|
285
|
-
- `target_env.health_base_url`
|
|
286
|
-
- `target_env.health_path`
|
|
287
|
-
|
|
288
|
-
当 `verification.jenkins_required: true` 时必填:
|
|
289
|
-
- `jenkins.base_url`
|
|
290
|
-
- `jenkins.ui_username`
|
|
291
|
-
- `jenkins.ui_password` 或 `jenkins.ui_password_env`
|
|
292
|
-
- `jenkins.api_user`
|
|
293
|
-
- `jenkins.api_password` 或 `jenkins.api_password_env`
|
|
294
|
-
- `jenkins.trigger_branch`
|
|
295
|
-
- `jenkins.image_repository`
|
|
296
|
-
- `jenkins.image_tag_strategy`
|
|
297
|
-
- `jenkins.deploy_env`
|
|
298
|
-
- `jenkins.job_url`
|
|
299
|
-
|
|
300
|
-
按需填写:
|
|
301
|
-
- `gate.default_scope`:默认 `standard`;需要小步快跑时设为 `auto` 或 `changed`
|
|
302
|
-
- `gate.profile_log`:本地门禁耗时画像,默认写入 `.local/auto-coding-skill/gate-profile.jsonl`
|
|
303
|
-
- `gate.rules`:项目自定义路径规则。每条规则可包含 `name`、`paths`、`commands`、`scope`
|
|
304
|
-
- `structure.enabled`:是否把结构检查纳入 `light-gate`
|
|
305
|
-
- `structure.layer_rules.enabled` / `block`:是否检查分层 import 边界,以及违规时阻塞还是仅提示
|
|
306
|
-
- `structure.max_file_lines_warn` / `structure.max_file_lines_block`:文件长度预警 / 阻塞阈值
|
|
307
|
-
- `structure.max_added_lines_to_large_file`:禁止在已偏大的文件里继续大块堆职责
|
|
308
|
-
- `structure.allow_large_files`:生成物、供应商代码、构建产物等允许超长或跳过结构检查的路径
|
|
309
|
-
- `structure.accepted_debt_paths`:已记录为接受债务的历史大文件;只豁免历史体量,不豁免继续大幅新增
|
|
310
|
-
- `optimization.completion_policy`:默认 `baseline-aware`,表示“优化完成”按本轮范围和已记录基线判断,不等于仓库没有任何可优化点
|
|
311
|
-
- `docs.ledger_check_enabled`:默认启用文档账本健康检查
|
|
312
|
-
- `docs.ledger_block_on_exceed`:默认阻塞超过预算的活跃账本;仅迁移期才允许临时关闭
|
|
313
|
-
- `runtime.*`:仅在本地运行诊断时使用
|
|
314
|
-
- `commands.build` / `commands.test` / `commands.quick_test` / `commands.lint` / `commands.typecheck` / `commands.format`:按项目实际情况保留
|
|
315
|
-
|
|
316
|
-
---
|
|
317
|
-
|
|
318
|
-
## 1. 权威输入与冲突裁决(优先级)
|
|
319
|
-
|
|
320
|
-
1) `docs/ENGINEERING.md`
|
|
321
|
-
2) `docs/tasks/taskbook.md`
|
|
322
|
-
3) `docs/tasks/archives/**`
|
|
323
|
-
4) `docs/design/**`
|
|
324
|
-
5) `docs/archive/design/**`
|
|
325
|
-
6) `docs/interfaces/api.md`
|
|
326
|
-
7) `docs/interfaces/api-change-log.md`
|
|
327
|
-
8) `docs/testing/regression-matrix.md`
|
|
328
|
-
9) `docs/bugs/bug-list.md`
|
|
329
|
-
10) `docs/tasks/closure-log.md`
|
|
330
|
-
11) `docs/tasks/summaries/**`
|
|
331
|
-
12) `docs/deployment/**`
|
|
332
|
-
13) 代码实现
|
|
333
|
-
|
|
334
|
-
说明:
|
|
335
|
-
- `closure-log.md` 是每个任务默认必须留下的轻量闭环记录。
|
|
336
|
-
- `taskbook.md`、`closure-log.md` 和顶层 `docs/design/T*.md` 是活跃账本,不是永久历史仓库。超过预算时必须把已关闭历史内容物理归档到 `docs/tasks/archives/**` 和 `docs/archive/design/**`。
|
|
337
|
-
- `docs/tasks/archive-index.md` 只用于导航归档位置;只有索引、没有物理归档,不算完成账本瘦身。
|
|
338
|
-
- `summaries/**` 只用于跨模块、高风险、阶段性里程碑、需要完整复盘的任务。
|
|
339
|
-
- `deployment/**` 只用于真实部署记录、手工发布或高风险发布场景。
|
|
340
|
-
|
|
341
|
-
---
|
|
342
|
-
|
|
343
|
-
## 1.5 工具使用策略(通用 .agents 默认)
|
|
344
|
-
|
|
345
|
-
任务开始时先做能力盘点:当前可用的 MCP servers、已安装 skills、plugins / apps / connectors、浏览器控制能力、repo 脚本。能直接读取权威状态、当前文档或真实 UI 的能力,优先于手写推测。
|
|
346
|
-
|
|
347
|
-
默认路由:
|
|
348
|
-
|
|
349
|
-
1) 本地代码 / 测试 / Git / 门禁
|
|
350
|
-
优先使用 shell、项目脚本、`docs/tools/autopipeline/ap.py`。本地 diff、提交、推送以 Git 实际状态为准。
|
|
351
|
-
|
|
352
|
-
2) 当前库 / 框架 / SDK / API / CLI / 云服务文档
|
|
353
|
-
优先使用 Context7 等文档 MCP 或对应已安装 skill,先确认版本、参数、默认行为、废弃项,再改代码。
|
|
354
|
-
|
|
355
|
-
3) 浏览器与 UI 验证
|
|
356
|
-
- localhost、file、应用内页面:优先 Browser / in-app browser;需要脚本控制时配合 node_repl。
|
|
357
|
-
- 必须复用用户 Chrome 登录态、扩展或已有标签页:使用 Chrome 控制能力;需要脚本控制时配合 node_repl。
|
|
358
|
-
- 需要稳定自动化复现、截图或 smoke test:使用 Playwright。
|
|
359
|
-
- 原生桌面 App 或没有专用连接器的 UI:才使用 Computer Use。
|
|
360
|
-
|
|
361
|
-
4) GitHub / PR / Issue / CI
|
|
362
|
-
远端 PR、Issue、review comments、Actions/CI 状态优先用 GitHub connector;本地 diff、commit、push 仍用本地 Git。
|
|
363
|
-
|
|
364
|
-
5) Figma / 视觉设计 / 前端体验
|
|
365
|
-
设计上下文先用 Figma;视觉强相关页面优先使用 frontend / build-web / product-design 类 skill,并用浏览器截图或真实页面验证收口。
|
|
366
|
-
|
|
367
|
-
6) 安全敏感变更
|
|
368
|
-
鉴权、权限、支付、文件上传下载、部署、依赖、数据边界变更,默认安排 reviewer 或安全扫描能力做只读复核。
|
|
369
|
-
|
|
370
|
-
7) 报告与文件类产物
|
|
371
|
-
Dashboard / 数据报告使用 Data Analytics;Word/PDF/表格/PPT/LaTeX 使用对应文档类 skill 或插件,并做渲染/校验。
|
|
372
|
-
|
|
373
|
-
8) OpenAI/API key/密钥类操作
|
|
374
|
-
使用平台提供的安全 key 创建或写入流程;不要在普通文档、日志或提交中手写、复制、持久化密钥。
|
|
375
|
-
|
|
376
|
-
9) 屏幕与近期操作上下文
|
|
377
|
-
当任务依赖用户当前屏幕、浏览器登录状态或最近手工操作时,优先使用 Chronicle / screenshot 类能力获取真实上下文。
|
|
378
|
-
|
|
379
|
-
回退规则:
|
|
380
|
-
- 工具不可用、权限不足、结果不可靠或比直接执行更慢时,才回退到 shell 或手工流程。
|
|
381
|
-
- 不重复手写工具已经能直接读取或写回的权威数据。
|
|
382
|
-
- 外部信息必须优先来自官方文档、项目连接器或真实运行状态。
|
|
383
|
-
|
|
384
|
-
---
|
|
385
|
-
|
|
386
|
-
## 1.6 多 Agent 协作策略(通用 .agents 默认)
|
|
107
|
+
# Engineering Workflow
|
|
387
108
|
|
|
388
|
-
|
|
109
|
+
This file is the single manually maintained workflow configuration. Keep it in
|
|
110
|
+
Git. Add optional sections only when the project enables the related surface.
|
|
389
111
|
|
|
390
|
-
|
|
112
|
+
## Execution profiles
|
|
391
113
|
|
|
392
|
-
|
|
393
|
-
只读探索:定位入口、调用链、关键文件、配置项、根因候选。
|
|
114
|
+
`workflow.profile: auto` selects one of three effective profiles:
|
|
394
115
|
|
|
395
|
-
|
|
396
|
-
|
|
116
|
+
| Profile | Typical work | Gate | Closure mode |
|
|
117
|
+
| --- | --- | --- | --- |
|
|
118
|
+
| `micro` | docs/tests-only, very small isolated work | changed | dev |
|
|
119
|
+
| `standard` | ordinary feature and defect work | standard | dev |
|
|
120
|
+
| `high-risk` | DB/auth/payment/deploy/build config or declared high risk | full | verify |
|
|
397
121
|
|
|
398
|
-
|
|
399
|
-
|
|
122
|
+
`auto` is only a selector. The effective profile is always `micro`, `standard`,
|
|
123
|
+
or `high-risk`. A high-risk signal cannot be downgraded with a CLI flag or a
|
|
124
|
+
project rule. An explicit non-auto profile replaces auto's low/normal baseline.
|
|
125
|
+
`workflow.mode: verify` also requires the full gate.
|
|
400
126
|
|
|
401
|
-
|
|
402
|
-
|
|
127
|
+
Project `gate.rules` may declare `paths`, `commands`, `scope`, and an optional
|
|
128
|
+
`profile`. Configure `commands.gate_full` (or legacy `commands.full_gate`) for
|
|
129
|
+
high-risk work; a light or standard command does not count as a full gate.
|
|
403
130
|
|
|
404
|
-
|
|
405
|
-
只读复核:正确性、安全性、回归风险、边界条件和测试缺口。
|
|
406
|
-
|
|
407
|
-
主 agent 始终负责:
|
|
408
|
-
- 任务定义、范围裁决、方案取舍
|
|
409
|
-
- 代码集成和冲突处理
|
|
410
|
-
- 轻量门禁、已启用的 CI/Jenkins/目标环境闭环
|
|
411
|
-
- 文档闭环、Git 状态、最终交付
|
|
412
|
-
|
|
413
|
-
任务边界不清、需要强一致裁决或涉及架构取舍时,由主 agent 保持控制,不机械拆分。
|
|
414
|
-
|
|
415
|
-
---
|
|
131
|
+
## Minimal configuration
|
|
416
132
|
|
|
417
|
-
|
|
418
|
-
|
|
419
|
-
默认采用 `docs/architecture/structure-standard.md` 中的通用结构标准。具体项目可以按技术栈细化目录名,但不得降低以下要求:
|
|
420
|
-
|
|
421
|
-
1) 分层清晰
|
|
422
|
-
- 业务规则、用例编排、外部适配、接口入口、共享工具必须有清晰边界。
|
|
423
|
-
- 新代码先落到对应层;没有合适位置时,先补最小设计或 ADR,再新增目录 / 模块。
|
|
424
|
-
|
|
425
|
-
2) 复用优先
|
|
426
|
-
- 新增工具、并发控制、缓存、请求封装、格式转换、权限判断、校验逻辑前,必须先搜索已有 helper、库、组件、脚本。
|
|
427
|
-
- 正常情况下复用成熟库或项目既有工具;只有明确的性能、并发、部署、许可证、兼容性约束才允许自研,并记录理由和验证。
|
|
428
|
-
|
|
429
|
-
3) 单文件容量控制
|
|
430
|
-
- 超过 `structure.max_file_lines_warn` 的文件只允许小修和缺陷修复,新增职责应优先抽取模块。
|
|
431
|
-
- 超过 `structure.max_file_lines_block` 的文件不得继续承载新职责,除非该文件在 `structure.allow_large_files` 中声明为生成物或外部产物。
|
|
432
|
-
- 禁止仅为了降低行数而拆文件。拆分必须服务于清晰的业务边界、技术边界、变更安全和阅读连续性;如果事务、状态机、用例流程或测试场景需要放在一起维护,应保留内聚结构并记录为接受债务。
|
|
433
|
-
- 已记录为接受债务的历史大文件可放入 `structure.accepted_debt_paths`,但继续大幅新增仍会被阻塞。
|
|
434
|
-
- 对已偏大的文件一次性增加超过 `structure.max_added_lines_to_large_file` 行时,`structure-check` 会阻塞,要求拆分或写明例外理由。
|
|
435
|
-
|
|
436
|
-
4) 优化完成标准
|
|
437
|
-
- “优化完成”不表示仓库没有任何可优化点。
|
|
438
|
-
- 默认定义为:本轮约定范围内的 P0/P1/P2 scoped items 已闭环,本地 gate 通过,没有新增未分级 P0/P1,剩余 P2/P3 已进入 backlog 或被接受为债务。
|
|
439
|
-
- 新会话做整体分析时,必须先读 `docs/reviews/project-health-baseline.md` 和 `docs/reviews/optimization-backlog.md`,只报告新增、恶化、未记录 P0/P1,或已记录但需要升级优先级的问题。
|
|
440
|
-
|
|
441
|
-
5) 本地执行
|
|
442
|
-
- 任务开始分类:`python3 docs/tools/autopipeline/ap.py classify --scope auto`
|
|
443
|
-
- 小步快跑默认执行:`python3 docs/tools/autopipeline/ap.py structure-check --scope auto`
|
|
444
|
-
- 发布、跨模块重构、架构调整默认执行:`python3 docs/tools/autopipeline/ap.py structure-check --scope full`
|
|
445
|
-
- 首次落基线:`python3 docs/tools/autopipeline/ap.py baseline init --write --update-config`
|
|
446
|
-
- 项目升级预检:`python3 docs/tools/autopipeline/ap.py upgrade --dry-run`
|
|
447
|
-
- 文档账本健康检查:`python3 docs/tools/autopipeline/ap.py docs-ledger-check`
|
|
448
|
-
- 文档账本归档预览:`python3 docs/tools/autopipeline/ap.py docs-ledger-archive --plan`
|
|
449
|
-
- 文档账本归档执行:`python3 docs/tools/autopipeline/ap.py docs-ledger-archive --write`
|
|
450
|
-
- 门禁耗时画像:`python3 docs/tools/autopipeline/ap.py gate-profile`
|
|
451
|
-
- `doctor` 默认纳入文档账本健康检查;`light-gate` 会先跑 `doctor`,因此活跃账本超预算会阻塞后续任务,避免“只建索引、不归档瘦身”的状态长期存在。
|
|
452
|
-
- `light-gate` 在 `structure.enabled: true` 时会自动纳入结构检查;如项目需要更强规则,可配置 `commands.structure_check` 覆盖内置实现。
|
|
133
|
+
Required for normal development:
|
|
453
134
|
|
|
454
|
-
|
|
455
|
-
|
|
456
|
-
|
|
457
|
-
|
|
458
|
-
|
|
459
|
-
|
|
460
|
-
|
|
461
|
-
|
|
462
|
-
|
|
463
|
-
|
|
464
|
-
|
|
465
|
-
|
|
466
|
-
|
|
467
|
-
|
|
468
|
-
|
|
469
|
-
|
|
470
|
-
|
|
471
|
-
|
|
472
|
-
|
|
473
|
-
|
|
474
|
-
|
|
475
|
-
|
|
476
|
-
|
|
477
|
-
|
|
478
|
-
|
|
479
|
-
|
|
480
|
-
-
|
|
481
|
-
|
|
482
|
-
-
|
|
483
|
-
|
|
484
|
-
|
|
485
|
-
|
|
486
|
-
|
|
487
|
-
|
|
488
|
-
|
|
489
|
-
|
|
490
|
-
|
|
491
|
-
|
|
492
|
-
|
|
493
|
-
|
|
494
|
-
|
|
495
|
-
|
|
496
|
-
|
|
497
|
-
|
|
498
|
-
|
|
499
|
-
|
|
500
|
-
|
|
501
|
-
|
|
502
|
-
|
|
503
|
-
|
|
504
|
-
|
|
505
|
-
|
|
506
|
-
|
|
507
|
-
|
|
508
|
-
|
|
509
|
-
|
|
510
|
-
|
|
511
|
-
|
|
512
|
-
|
|
513
|
-
|
|
514
|
-
|
|
515
|
-
|
|
516
|
-
|
|
517
|
-
|
|
518
|
-
|
|
519
|
-
|
|
520
|
-
|
|
521
|
-
|
|
522
|
-
|
|
523
|
-
|
|
524
|
-
|
|
525
|
-
|
|
526
|
-
|
|
527
|
-
|
|
528
|
-
|
|
529
|
-
|
|
530
|
-
|
|
531
|
-
-
|
|
532
|
-
-
|
|
533
|
-
-
|
|
534
|
-
|
|
535
|
-
|
|
536
|
-
|
|
537
|
-
|
|
538
|
-
-
|
|
539
|
-
- 必要时补 summary / deployment record / regression matrix
|
|
540
|
-
|
|
541
|
-
---
|
|
542
|
-
|
|
543
|
-
## 4. 本地 Docker 与完整回归(按需,不默认)
|
|
544
|
-
|
|
545
|
-
以下能力保留,但仅用于显式要求、问题复现、CI/Jenkins/目标环境问题前置诊断:
|
|
546
|
-
- `runtime-up`
|
|
547
|
-
- `runtime-down`
|
|
548
|
-
- 本地 health check
|
|
549
|
-
- `check-matrix`
|
|
550
|
-
- `gen-summary`
|
|
551
|
-
|
|
552
|
-
默认情况下,不把它们作为每个小改动的固定门禁。
|
|
553
|
-
|
|
554
|
-
---
|
|
555
|
-
|
|
556
|
-
## 5. Repo 工具入口
|
|
557
|
-
|
|
558
|
-
统一使用:
|
|
559
|
-
- `python3 docs/tools/autopipeline/ap.py doctor`
|
|
560
|
-
- `python3 docs/tools/autopipeline/ap.py commit-push <TASK_ID> --msg "<TASK_ID>: <summary>"`
|
|
561
|
-
- `python3 docs/tools/autopipeline/ap.py commit-push <TASK_ID> --mode verify --msg "<TASK_ID>: <summary>" ...`
|
|
562
|
-
- `python3 docs/tools/autopipeline/ap.py light-gate`
|
|
563
|
-
- `python3 docs/tools/autopipeline/ap.py verify-jenkins-build ...`
|
|
564
|
-
- `python3 docs/tools/autopipeline/ap.py wait-health --scope target`
|
|
565
|
-
- `python3 docs/tools/autopipeline/ap.py verify-target ...`
|
|
566
|
-
- `python3 docs/tools/autopipeline/ap.py record-closure <TASK_ID> ...`
|
|
567
|
-
|
|
568
|
-
说明:
|
|
569
|
-
- `doctor`:检查默认流程必填项和常见配置错误。
|
|
570
|
-
- `light-gate`:默认轻量门禁,优先执行项目自定义快速门禁命令。
|
|
571
|
-
- `commit-push`:按 `workflow.mode` 自动选择开发闭环或完整验证闭环。
|
|
572
|
-
- `verify-target`:目标环境健康检查 + 按需关键 API / 页面验证。
|
|
573
|
-
- `record-closure`:默认轻量闭环记录。
|
|
574
|
-
- `check-matrix`、`gen-summary`、`runtime-up/down`:保留为按需工具。
|
|
135
|
+
- `workflow.mode`: `dev` or `verify`
|
|
136
|
+
- `workflow.profile`: `auto`, `micro`, `standard`, or `high-risk`
|
|
137
|
+
- `project.name`
|
|
138
|
+
- at least one usable gate command; configure all three gate commands when the
|
|
139
|
+
project can exercise changed, standard, and full scopes
|
|
140
|
+
- `verification.target_env_required` and `verification.jenkins_required`
|
|
141
|
+
|
|
142
|
+
Legacy command keys such as `commands.light_gate`, `quick_test`, `test`, and
|
|
143
|
+
`build` remain supported. Run `doctor` for exact missing-field diagnostics.
|
|
144
|
+
|
|
145
|
+
When target verification is enabled, add `target_env.health_base_url` and
|
|
146
|
+
`health_path`. Add frontend/backend URLs only for requested endpoint checks, and
|
|
147
|
+
login/secret references only when basic auth is requested. When Jenkins is
|
|
148
|
+
enabled, add `jenkins` with its base/job URLs, branch, artifact/deploy metadata,
|
|
149
|
+
timeout, UI/API users, and password values or environment references. Unused
|
|
150
|
+
sections should remain absent rather than filled with placeholders.
|
|
151
|
+
|
|
152
|
+
## Default workflow
|
|
153
|
+
|
|
154
|
+
Development:
|
|
155
|
+
|
|
156
|
+
1. Read this file and the active task entry.
|
|
157
|
+
2. Run or reason through `classify --scope auto`.
|
|
158
|
+
3. Record the smallest useful design note; create DD/ADR only when indicated.
|
|
159
|
+
4. Implement the necessary change using existing project structure and reuse points.
|
|
160
|
+
5. Run the resolved profile gate.
|
|
161
|
+
6. Record `DEV-CLOSED`, commit, and push.
|
|
162
|
+
|
|
163
|
+
High-risk or explicit verification:
|
|
164
|
+
|
|
165
|
+
1. Run the real full gate.
|
|
166
|
+
2. Commit and push.
|
|
167
|
+
3. Verify enabled CI/Jenkins and target-environment surfaces.
|
|
168
|
+
4. Record `PASS`, `FAIL`, or `PARTIAL` from actual evidence.
|
|
169
|
+
|
|
170
|
+
The authoritative order remains ENGINEERING, taskbook/archives, design and
|
|
171
|
+
interface records, regression/bug records, closure evidence, deployment records,
|
|
172
|
+
then implementation. Do not mark unexecuted checks as PASS.
|
|
173
|
+
|
|
174
|
+
## Structure policy
|
|
175
|
+
|
|
176
|
+
Generic structure checks are advisory by default. They may report file size,
|
|
177
|
+
function size, or regex-based import-boundary signals, but they block only when
|
|
178
|
+
`structure.enforcement: blocking` is explicitly configured. Repository-native
|
|
179
|
+
architecture and compiler/test evidence take precedence over generic naming
|
|
180
|
+
heuristics. Reuse existing helpers and avoid adding unrelated responsibilities
|
|
181
|
+
to already large files; do not split code merely to satisfy a line count.
|
|
182
|
+
|
|
183
|
+
Use `baseline init --write --update-config` for repository-wide structural work.
|
|
184
|
+
Accepted historical debt belongs in the generated baseline/backlog.
|
|
185
|
+
|
|
186
|
+
## Core and optional documents
|
|
187
|
+
|
|
188
|
+
The default scaffold contains only this file, taskbook, and closure log. Create
|
|
189
|
+
specialized documents when the task needs them:
|
|
190
|
+
|
|
191
|
+
```bash
|
|
192
|
+
python3 docs/tools/autopipeline/ap.py scaffold api --write
|
|
193
|
+
python3 docs/tools/autopipeline/ap.py scaffold design --write
|
|
194
|
+
python3 docs/tools/autopipeline/ap.py scaffold architecture --write
|
|
195
|
+
python3 docs/tools/autopipeline/ap.py scaffold review --write
|
|
196
|
+
python3 docs/tools/autopipeline/ap.py scaffold testing --write
|
|
197
|
+
python3 docs/tools/autopipeline/ap.py scaffold deployment --write
|
|
198
|
+
python3 docs/tools/autopipeline/ap.py scaffold bugs --write
|
|
199
|
+
python3 docs/tools/autopipeline/ap.py scaffold all --write
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
`baseline init` and `gen-summary` generate their outputs directly. The active
|
|
203
|
+
taskbook, closure log, and top-level DD files are bounded working ledgers; use
|
|
204
|
+
`docs-ledger-archive --plan` before archiving closed history.
|
|
205
|
+
|
|
206
|
+
## Common commands
|
|
207
|
+
|
|
208
|
+
```bash
|
|
209
|
+
python3 docs/tools/autopipeline/ap.py doctor
|
|
210
|
+
python3 docs/tools/autopipeline/ap.py classify --scope auto
|
|
211
|
+
python3 docs/tools/autopipeline/ap.py light-gate --scope auto --explain
|
|
212
|
+
python3 docs/tools/autopipeline/ap.py structure-check --scope auto
|
|
213
|
+
python3 docs/tools/autopipeline/ap.py commit-push <TASK_ID> --msg "<TASK_ID>: <summary>"
|
|
214
|
+
python3 docs/tools/autopipeline/ap.py docs-ledger-check
|
|
215
|
+
python3 docs/tools/autopipeline/ap.py gate-profile
|
|
216
|
+
```
|
|
217
|
+
|
|
218
|
+
The launcher under `docs/tools/autopipeline` delegates to the single runtime in
|
|
219
|
+
`.agents/skills/auto-coding-skill/scripts`; do not duplicate that runtime.
|