Repository navigation
Expand file tree
/
Copy pathinit_agent_rules.sh
More file actions
executable file
·3749 lines (3178 loc) · 106 KB
/
Copy pathinit_agent_rules.sh
File metadata and controls
executable file
·3749 lines (3178 loc) · 106 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
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
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
#!/usr/bin/env bash
set -euo pipefail
## init_agent_rules.sh
## 说明：Antigravity（优先）/ Cursor（兼容）规则一键初始化脚本（all-in-one）。
## 用法：
## wget -O init_agent_rules.sh <raw-url> && bash init_agent_rules.sh
## curl -fsSL <raw-url> | bash -s -- --verify
ROOT_DIR="$(pwd)"
FORCE="0"
DRY_RUN="0"
SYNC_CURSOR="1"
VERIFY="0"
MANIFEST="0"
NO_SKILLS="0"
# 输出 INFO 日志
log_info() { echo "[INFO] $*"; }
# 输出 WARN 日志
log_warn() { echo "[WARN] $*" >&2; }
# 输出 ERROR 日志
log_error() { echo "[ERROR] $*" >&2; }
# 打印帮助信息
usage() {
cat <<'USAGE'
用法：
bash init_agent_rules.sh [--dir <path>] [--force] [--no-cursor] [--no-skills] [--dry-run] [--verify] [--manifest] [--help]
参数：
--dir <path> 指定输出/安装目录（默认：当前目录）
--force 允许覆盖已存在文件（不备份）
--no-cursor 不同步到 .cursor/rules/
--no-skills 不安装 Awesome Skills
--dry-run 只打印将创建/覆盖/跳过的清单，不实际写入
--verify 执行后做一次自检并输出结果
--manifest 生成 MANIFEST.txt 与 MANIFEST.sha256（可选）
--help 显示帮助
USAGE
}
# 打印错误并退出
fail() {
log_error "$*"
exit 1
}
# 取目录绝对路径（解析符号链接）
abs_dir() {
(cd "$1" >/dev/null 2>&1 && pwd -P)
}
# 取路径“尽力而为”的绝对路径（用于日志与安全前缀校验）
abs_path() {
local path="$1"
if [ -d "$path" ]; then
abs_dir "$path"
return 0
fi
local parent
parent="$(dirname "$path")"
local base
base="$(basename "$path")"
local abs_parent=""
abs_parent="$(abs_dir "$parent" || true)"
if [ -n "$abs_parent" ]; then
echo "$abs_parent/$base"
return 0
fi
echo "$path"
}
# 生成时间戳（用于备份目录）
timestamp() {
date "+%Y%m%d-%H%M%S"
}
# 计算文件 sha256（用于 MANIFEST.sha256）
sha256_file() {
local file="$1"
if command -v shasum >/dev/null 2>&1; then
shasum -a 256 "$file" | awk '{print $1}'
return 0
fi
if command -v sha256sum >/dev/null 2>&1; then
sha256sum "$file" | awk '{print $1}'
return 0
fi
if command -v openssl >/dev/null 2>&1; then
openssl dgst -sha256 "$file" | awk '{print $2}'
return 0
fi
return 1
}
# 写文件（从 stdin 读取），支持 dry-run/force，并保证不写出 ROOT_DIR 之外
write_file() {
local rel="$1"
local abs_root
abs_root="$(abs_dir "$ROOT_DIR")"
case "$rel" in
/*) fail "安全保护：仅允许相对路径：$rel" ;;
*".."*) fail "安全保护：路径包含 ..，拒绝写入：$rel" ;;
esac
local dest="$abs_root/$rel"
local abs_dest
abs_dest="$(abs_path "$dest")"
case "$abs_dest" in
"$abs_root"/*) ;;
*) fail "安全保护：目标不在输出目录内，拒绝写入：$rel" ;;
esac
if [ -e "$dest" ] && [ "$FORCE" != "1" ]; then
if [ "$DRY_RUN" = "1" ]; then
log_warn "[DRY-RUN] 将跳过（已存在）：${rel}"
else
log_warn "已存在且默认不覆盖：${rel}（可用 --force 覆盖）"
fi
cat >/dev/null
return 0
fi
if [ "$DRY_RUN" = "1" ]; then
if [ -e "$dest" ]; then
log_info "[DRY-RUN] 将覆盖：${rel}"
else
log_info "[DRY-RUN] 将创建：${rel}"
fi
cat >/dev/null
return 0
fi
mkdir -p "$(dirname "$dest")"
cat >"$dest"
log_info "已写入：${rel}"
}
# 解析命令行参数
parse_args() {
while [ $# -gt 0 ]; do
case "$1" in
--dir)
shift
[ $# -gt 0 ] || fail "--dir 需要一个路径"
ROOT_DIR="$1"
;;
--force)
FORCE="1"
;;
--no-cursor)
SYNC_CURSOR="0"
;;
--no-skills)
NO_SKILLS="1"
;;
--dry-run)
DRY_RUN="1"
;;
--verify)
VERIFY="1"
;;
--manifest)
MANIFEST="1"
;;
--help|-h)
usage
exit 0
;;
*)
fail "未知参数：$1（使用 --help 查看用法）"
;;
esac
shift
done
}
# 写出仓库文件（内嵌内容）
emit_repo_files() {
EMBEDDED_FILES=(
.agent/workflows/openspec-apply.md
.agent/workflows/openspec-archive.md
.agent/workflows/openspec-proposal.md
.context/coding_style.md
.context/system_prompt.md
.editorconfig
.gitignore
.prettierignore
.prettierrc
.vscode/settings.json
AGENTS.md
CHANGELOG.md
Debugging-Rules.md
PACKING.md
README.md
scripts/templates/build.sh
scripts/templates/clean.sh
scripts/templates/debug.sh
scripts/templates/dev.sh
scripts/templates/diagnose.sh
scripts/templates/reset.sh
scripts/templates/start.sh
scripts/templates/tail.sh
scripts/templates/test.sh
tools/build_init.sh
)
write_file ".agent/workflows/openspec-apply.md" <<'__AR_EOF_b594aa97c0e3__'
---
description: 需求实施阶段流程
---
<!-- 说明：OpenSpec 实施流程指引 -->
<!-- OPENSPEC:START -->
**守则**
- 改动尽量小
- 只做已批准项
- 先验证再勾选
**步骤**
1. 读 proposal/tasks
2. 按序实现任务
3. 完成后再勾选
4. 更新任务状态
5. 需要时补测试
**参考**
- openspec show 可查
- 信息不足先提问
<!-- OPENSPEC:END -->
__AR_EOF_b594aa97c0e3__
write_file ".agent/workflows/openspec-archive.md" <<'__AR_EOF_5c4eb50fd669__'
---
description: 需求归档阶段流程
---
<!-- 说明：OpenSpec 归档流程指引 -->
<!-- OPENSPEC:START -->
**守则**
- 确认变更已发布
- 归档前先核对
- 不确定就停下
**步骤**
1. 确认 change-id
2. 验证变更状态
3. 执行归档操作
4. 检查规格更新
5. 记录归档结果
**参考**
- openspec list 用于查
- 失败先输出日志
<!-- OPENSPEC:END -->
__AR_EOF_5c4eb50fd669__
write_file ".agent/workflows/openspec-proposal.md" <<'__AR_EOF_3368586c5764__'
---
description: 需求提案阶段流程
---
<!-- 说明：OpenSpec 提案流程指引 -->
<!-- OPENSPEC:START -->
**守则**
- 先澄清范围
- 仅写文档
- 有歧义先问
**步骤**
1. 读项目上下文
2. 定义 change-id
3. 产出 proposal/tasks/design
4. 拆分可验任务
5. 自检格式与风险
**参考**
- 需要时再用 openspec
- 无 openspec 就说明
<!-- OPENSPEC:END -->
__AR_EOF_3368586c5764__
write_file ".context/coding_style.md" <<'__AR_EOF_21eb010ec72b__'
<!-- 说明：编码风格补充规则 -->
# 编码风格补充
## 结构
- 目录层级清晰
- 文件不过长
- 避免循环依赖
## 代码
- 强类型优先
- 函数前写中文注释
- 复杂逻辑加说明
## 工具
- 运行走 scripts/*.sh
- 日志落到 logs/
__AR_EOF_21eb010ec72b__
write_file ".context/system_prompt.md" <<'__AR_EOF_d6d94f8911f0__'
<!-- 说明：工作区系统提示（简版） -->
# 系统提示（工作区）
## 核心目标
- 对齐用户目标
- 保持改动最小
- 必要时先提问
## 必读文件
- AGENTS.md
- Debugging-Rules.md
- README.md（如存在）
## 行为要求
- 复杂任务先给计划
- 输出中文
- 命令先 dry-run
- 变更需写 CHANGELOG.md
__AR_EOF_d6d94f8911f0__
write_file ".editorconfig" <<'__AR_EOF_0947e2727d6b__'
# EditorConfig is awesome: https://editorconfig.org
root = true
[*]
charset = utf-8
indent_style = space
indent_size = 2
end_of_line = lf
insert_final_newline = true
trim_trailing_whitespace = true
max_line_length = 120
# Vue 文件配置
[*.vue]
indent_style = space
indent_size = 2
# TypeScript/JavaScript 文件配置
[*.{ts,js,tsx,jsx}]
indent_style = space
indent_size = 2
# JSON 文件配置
[*.json]
indent_style = space
indent_size = 2
# CSS/SCSS 文件配置
[*.{css,scss,sass}]
indent_style = space
indent_size = 2
# Markdown 文件配置
[*.md]
trim_trailing_whitespace = false
indent_style = space
indent_size = 2
# YAML 文件配置
[*.{yml,yaml}]
indent_style = space
indent_size = 2
# Shell 脚本配置
[*.sh]
indent_style = space
indent_size = 2
__AR_EOF_0947e2727d6b__
write_file ".gitignore" <<'__AR_EOF_bc37d034bad5__'
.DS_Store
.backup/
logs/
.venv/
__pycache__/
*.pyc
node_modules/
dist/
build/
__AR_EOF_bc37d034bad5__
write_file ".prettierignore" <<'__AR_EOF_b640b344ee7f__'
# Dependencies
node_modules/
.pnpm-store/
# Build outputs
dist/
.output/
.nuxt/
.nitro/
# Logs
logs/
*.log
# Database files
*.db
*.sqlite
*.sqlite3
# Environment files
.env
.env.*
# IDE files
.vscode/
.idea/
# OS files
.DS_Store
Thumbs.db
# Package files
*.tar.gz
*.zip
# Backup files
data/backups/
*.backup
# Generated files
coverage/
.nyc_output/
# Lock files
package-lock.json
yarn.lock
pnpm-lock.yaml
__AR_EOF_b640b344ee7f__
write_file ".prettierrc" <<'__AR_EOF_663ade211b3a__'
{
"semi": false,
"singleQuote": true,
"trailingComma": "es5",
"tabWidth": 2,
"useTabs": false,
"printWidth": 120,
"endOfLine": "lf",
"bracketSpacing": true,
"bracketSameLine": false,
"arrowParens": "avoid",
"vueIndentScriptAndStyle": false,
"htmlWhitespaceSensitivity": "ignore"
}
__AR_EOF_663ade211b3a__
write_file ".vscode/settings.json" <<'__AR_EOF_a5de3e5871ff__'
{
// 自动保存设置
"files.autoSave": "afterDelay",
"files.autoSaveDelay": 500,
// 格式化设置
"editor.formatOnSave": true,
"editor.formatOnPaste": true,
"editor.formatOnType": false,
"editor.codeActionsOnSave": {
"source.fixAll": "explicit",
"source.organizeImports": "explicit"
},
// 默认格式化器
"editor.defaultFormatter": "esbenp.prettier-vscode",
// 文件类型特定格式化器
"[vue]": {
"editor.defaultFormatter": "Vue.volar"
},
"[typescript]": {
"editor.defaultFormatter": "esbenp.prettier-vscode"
},
"[javascript]": {
"editor.defaultFormatter": "esbenp.prettier-vscode"
},
"[json]": {
"editor.defaultFormatter": "esbenp.prettier-vscode"
},
"[css]": {
"editor.defaultFormatter": "esbenp.prettier-vscode"
},
"[scss]": {
"editor.defaultFormatter": "esbenp.prettier-vscode"
},
"[html]": {
"editor.defaultFormatter": "esbenp.prettier-vscode"
},
"[markdown]": {
"editor.defaultFormatter": "esbenp.prettier-vscode"
},
// Prettier 配置
"prettier.semi": false,
"prettier.singleQuote": true,
"prettier.trailingComma": "es5",
"prettier.tabWidth": 2,
"prettier.useTabs": false,
"prettier.printWidth": 120,
"prettier.endOfLine": "lf",
// Vue 特定设置
"vetur.format.defaultFormatter.html": "prettier",
"vetur.format.defaultFormatter.css": "prettier",
"vetur.format.defaultFormatter.scss": "prettier",
"vetur.format.defaultFormatter.js": "prettier",
"vetur.format.defaultFormatter.ts": "prettier",
// TypeScript 设置
"typescript.preferences.importModuleSpecifier": "relative",
"typescript.suggest.autoImports": true,
"typescript.updateImportsOnFileMove.enabled": "always",
// 编辑器设置
"editor.tabSize": 2,
"editor.insertSpaces": true,
"editor.detectIndentation": false,
"editor.rulers": [120],
"editor.wordWrap": "wordWrapColumn",
"editor.wordWrapColumn": 120,
// 文件设置
"files.eol": "\n",
"files.insertFinalNewline": true,
"files.trimTrailingWhitespace": true,
"files.trimFinalNewlines": true,
// 搜索设置
"search.exclude": {
"**/node_modules": true,
"**/dist": true,
"**/.nuxt": true,
"**/.output": true,
"**/coverage": true
},
// 文件监视设置
"files.watcherExclude": {
"**/node_modules/**": true,
"**/dist/**": true,
"**/.nuxt/**": true,
"**/.output/**": true
},
// Emmet 设置
"emmet.includeLanguages": {
"vue-html": "html",
"vue": "html"
},
// 其他设置
"editor.minimap.enabled": true,
"editor.minimap.maxColumn": 120,
"breadcrumbs.enabled": true,
"explorer.confirmDelete": false,
"explorer.confirmDragAndDrop": false
}
__AR_EOF_a5de3e5871ff__
write_file "AGENTS.md" <<'__AR_EOF_a54ff182c7e8__'
# AGENTS.md
## 总则
你是一个出色的高级程序员。你在 Antigravity 中工作时必须遵守本规范；同时保持对 Cursor/VS Code 的兼容。
- 严格遵循规则，不得越权修改
- 对外输出（回复/文档/注释/脚本日志）必须使用简体中文
- 分析/检索/推理过程可使用英文，但最终交付必须中文
- 调试与排查遵循 `Debugging-Rules.md`，并主动提供可复现的日志/命令
- 每次修复/优化必须更新 `CHANGELOG.md`（使用当前日期，遵循模板）
- 脚本模板统一放在 `scripts/templates/`
---
## 测试与验收原则
- 用户可见行为与复杂功能，优先通过 E2E 验收。
- 尽量使用真实依赖；注明 Mock 范围及验证盲区。
- 实现前识别失败模式、边界及集成风险。
- 分析深度与改动风险匹配。
- 单元或集成测试用于快速定位、边界验证和缺陷回归。
- 不为凑覆盖率或宣告完成而补测试。
- E2E 必须验证明确的预期结果。
- 保留可核验产物及复现步骤。
- 产物记录输入、预期、实际结果及运行环境。
- 可采用 trace、截图、视频或结构化结果。
- 构建、类型检查或 Lint 通过，不等于功能可用。
- Mock 测试通过，不能单独证明功能可用。
- 复杂功能须跑通受影响的真实流程，才能宣告验收完成。
- 验证未执行或受阻时，说明范围、原因及剩余步骤。
- 区分“实现完成”与“真实流程验收完成”。
---
## 规则加载约定（Antigravity 优先 + Cursor 兼容）
- Antigravity 项目规则目录：`.agent/rules/*.mdc`（自动加载）
- Cursor/VS Code 兼容目录：`.cursor/rules/*.mdc`（如存在则同步）
---
## 强护栏（权限边界与破坏性操作）
### 文件系统边界（硬性）
- 禁止在项目根目录之外写入/删除/迁移文件
- 如必须跨目录操作：先说明影响范围并征求确认，再执行
### 破坏性操作（必须先征求确认）
- 删除/迁移：`rm`、`mv`、`git clean`、批量替换/重构
- Git 高风险：`git reset --hard`、`git push -f`、重写历史
- CI/发布：修改 `.github/`、流水线、发布脚本
- 依赖与版本：升级/降级依赖、改 lock、改包管理器
### 终端执行策略（硬性）
- 先 dry-run：先列出匹配项/影响面，再执行实际修改
- 先小后大：先对单文件/小范围验证，再扩大范围
- 失败先定位：必须输出关键日志、命令与复现路径
---
## Communication（对话规范）
- 对外输出必须中文；分析/检索可英文；最终交付中文
- 解释复杂概念时：先给结论，再分点说明
✅ 正确：「这是因为……（结论）→ 三个原因如下」
❌ 错误：「原因有很多，我们先来一步一步分析」
---
## Documentation（文档规范）
- 编写 `.md` 文档时必须使用中文
- 正式文档写到 `docs/` 目录下
- 讨论和评审文档写到 `discuss/` 目录下
- 文档风格：一段 ≤ 3 句，句子 ≤ 20 字，优先用列表
✅ 正确：`docs/架构设计.md`
❌ 错误：`docs/architecture_design.md`
✅ 正确：`discuss/技术方案评审.md`
❌ 错误：`docs/技术方案评审.md`
---
## Code Architecture（代码结构与坏味道）
### 硬性指标
- Python / JavaScript / TypeScript 文件建议 ≤ 300 行
- Java / Go / Rust 文件建议 ≤ 300 行
- 单文件超过 400 行时，必须评估是否存在职责过多、依赖扩散、测试困难等问题
- 单文件超过 500 行时，原则上必须拆分；生成代码、协议文件、迁移脚本、框架约定入口文件除外
- HTML 文件建议 ≤ 500 行；超过 700 行原则上必须组件化拆分
- 每层目录 ≤ 8 个文件（不含子目录），多了需拆子目录
### 判断原则（优先级高于行数）
- 行数不是唯一标准，职责边界比行数更重要
- 如文件职责单一、结构清晰、命名稳定、测试容易补充，可接受适度超出建议值
- 如文件虽然未超行数，但已出现多职责、重复逻辑、难以导航、难以测试，也必须拆分
- 拆分后不得制造更差的抽象、循环依赖或无意义的中转层
### 允许超限的典型场景
- 生成代码或第三方同步文件
- 协议声明、类型清单、路由注册表、错误码表
- 框架要求的入口文件或集中配置文件
- 临时迁移文件，但应在迁移完成后清理
### 必须拆分的信号
- 一个文件包含 2 个及以上独立职责
- 一个文件同时承担 models / repo / service / api 中多个层的职责
- 修改一个需求时，经常需要在同一文件多个远距离区域联动修改
- 单元测试难写，或必须依赖大量上下文才能理解
- 出现大量“顺手塞进去”的 helper、utils、common 逻辑
✅ 正确：`user_service.py` 320 行，但职责单一、分段清晰、测试完整
✅ 正确：`route_registry.ts` 420 行，但属于集中声明文件，结构稳定
❌ 错误：`main.js` 220 行，却同时包含路由、数据库、鉴权、日志初始化
❌ 错误：`user_service.py` 380 行，混合 repo、service、api 响应拼装逻辑
✅ 正确：`services/` 下 6 个文件
❌ 错误：`utils/` 下 20 个文件堆一起
### 坏味道（必须避免）
1. 僵化：改动困难，牵一发而动全身
2. 冗余：重复逻辑多处出现
3. 循环依赖：模块互相缠绕
4. 脆弱性：改动一处导致其他地方报错
5. 晦涩性：代码意图不明，难以理解
6. 数据泥团：多个参数总是成对出现，应封装对象
7. 不必要的复杂性：过度设计
【非常重要】
- 一旦识别坏味道：先提示用户是否需要优化，并给出可落地方案
---
## 依赖与版本策略（以仓库锁为准）
- 前端：以 `package.json` + lock（`pnpm-lock.yaml` / `package-lock.json` / `yarn.lock` 等）为单一真相
- 后端 Python：以 `pyproject.toml` + lock（例如 `uv.lock` 或项目既有锁）为单一真相
- 未经用户明确要求：不得升级/降级依赖版本，不得更换包管理器
- `requirements.txt`：如项目需要，只能由 lock 导出生成；禁止“随手更新”
---
## HTML（分离关注点）
- 遵循“分离关注点”原则：样式（CSS）、行为（JS）、结构（HTML）必须分离
- 单个 HTML 文件 ≤ 500 行，功能过多时拆分为组件
✅ 正确：
```html
<link rel="stylesheet" href="style.css">
<script src="app.js"></script>
<div class="user-card">张三</div>
```
❌ 错误：
```html
<div style="color:red;" >
```
---
## Python（uv 优先）
- 数据结构必须强类型；如必须用 `dict`/弱类型结构，需征求用户同意
- 虚拟环境目录统一为 `.venv`；优先用 `uv venv` 创建并管理
- 依赖管理必须使用 `uv`；禁止 `pip install`（也不直接使用 `python`/`python3` 执行项目命令）
- 依赖与锁：以 `pyproject.toml` + lock 为准；`requirements.txt` 仅允许从 lock 导出
- 根目录保持简洁；`main.py` 保持最小启动逻辑（业务逻辑下沉到模块）
✅ 正确：
```python
@dataclass
class User:
id: int
name: str
```
❌ 错误：
```python
user = {"id": 1, "name": "张三"} # 未定义结构
```
✅ 正确：`uv add requests`
❌ 错误：`pip install requests`
✅ 正确：
```python
if __name__ == "__main__":
run_app()
```
❌ 错误：在 `main.py` 里写 500 行业务逻辑
---
## React / Next.js / TypeScript / JavaScript
- 版本以项目 `package.json` 与 lock 为准；未经用户明确要求不得升级/降级
- 严禁使用 CommonJS（禁止 `require` / `module.exports`）
- 尽量使用 TypeScript；如必须用 JS，需说明原因
- 数据结构必须强类型；如必须用 `any` 或未定义结构的 JSON，需征求用户同意
✅ 正确：`import fs from "fs"`
❌ 错误：`const fs = require("fs")`
✅ 正确：
```ts
interface User {
id: number
name: string
}
```
❌ 错误：
```ts
let user: any = {}
```
---
## Run & Debug（运行与调试）
- 运行/调试/构建脚本必须维护在 `scripts/` 目录下，并通过 `scripts/*.sh` 执行
- `.sh` 脚本失败：先修复脚本，再继续使用脚本（不要绕开脚本手动跑命令）
- 调试前配置 Logger：统一输出到 `logs/`；并在输出中包含关键上下文
- 初始化类脚本（例如 `setup_agent_rules.sh`）用于一次性安装/初始化，不属于日常 Run/Debug 流程
✅ 正确：`./scripts/run_server.sh`
❌ 错误：`npm run dev` 或 `python main.py`
---
## Flutter Widget 树括号封闭规则
在 Widget 树嵌套较深时，必须在封闭括号后添加注释，标明对应的 Widget 名称，便于识别层级。
✅ 正确示例：
```dart
return Scaffold(
body: Center(
child: Column(
children: [
Text("Hello"),
ElevatedButton(
onPressed: () {},
child: Text("Click"),
), // ElevatedButton
],
), // Column
), // Center
); // Scaffold
```
❌ 错误示例：
```dart
return Scaffold(
body: Center(
child: Column(
children: [
Text("Hello"),
ElevatedButton(
onPressed: () {},
child: Text("Click"),
),
],
),
),
);
```
---
## 开发流程规范
- 分析代码问题可英文；回答与注释必须中文
- 修复错误必须检查完整链路，并修复关联代码（仅限相关范围）
- 非本问题范围的改动：必须先征求用户确认
- 修改后必须输出代码改动对比（例如 `git diff` 关键片段或摘要）
- 修改需基于上下文（如 @ 引用文件），避免脱离上下文的推断
- 新增/修改文件、类、函数、方法声明前必须有中文注释
- 不得私自修改界面样式或配置文件（除非为修复所必需，并说明原因）
- 如项目需要 `requirements.txt`：必须由 lock 导出生成，禁止手工维护
- Python 项目运行需确保 `.venv` 已就绪；优先通过 `uv run` 执行命令
### Go 代码规范
- 对 `map[string]string` 这类键和值都是基础类型、语义不直观的映射，必须加类型含义注释，格式固定：`// <key> -> <value>`，例如：`regionToInstanceID := map[string]string{} // region -> instanceID`
- 如果已经使用强语义类型（如 `map[Region]InstanceID`），或变量名已明确表达映射关系（如 `instanceIDByRegion`），可以不写该注释。
---
## 项目管理规范
- 使用 monocode 架构：功能模块按文件分开，文件开头提供说明，并保持更新
- 如缺失 `.gitignore`：按需补齐（至少忽略 `.venv/`、`__pycache__/`、`logs/` 等）
- 项目功能、使用方法、todo-list 必须写入 `README.md`
- 每次修复问题要记录：原因、解决方案、更改内容
- 必须在 `CHANGELOG.md` 中记录修复情况，遵循统一模板
## Monocode 约束
- 源码统一置于 `src/`；按功能（feature）为第一维度拆分目录
- 每个功能目录内包含：`models/`、`repo/`、`service/`、`api/`、`schemas/`（缺失项按需补全）
- `service` 不得直接调用外部依赖（DB/HTTP/缓存）；此类依赖只允许在 `repo` 层
- `shared` 仅存放基础设施与纯工具，禁止业务逻辑
- 单文件建议 ≤ 300 行；超过 400 行必须评估拆分；超过 500 行原则上必须拆分
- HTML 单文件建议 ≤ 500 行；超过 700 行原则上必须组件化拆分
- 同层 ≤ 8 文件（不含子目录），超限必须拆分
- 运行/调试/构建仅通过 `scripts/*.sh`
### 文件/目录数量约束
- 每个目录下的直接文件 ≤ 8 个（不含子目录）
- 目录层级 ≤ 3 层
- 目录必须表达明确的功能边界，禁止使用 “misc/、common/、utils/” 作为垃圾桶
__AR_EOF_a54ff182c7e8__
write_file "CHANGELOG.md" <<'__AR_EOF_06572a96a58d__'
# CHANGELOG
此文件用于记录项目的所有修改历史，确保每次修复、优化或新增功能都有迹可循。
请按照以下格式填写：
---
## [2026-09-22] - 明确测试与真实流程验收标准
### 问题描述
- 缺少真实流程验收标准
- 评审偏重单元测试数量
### 分析原因
- 未区分检查通过与功能可用
- 缺少成功验收的证据要求
### 解决方案
- 用户行为与复杂功能优先 E2E 验收
- 按风险选择单元与集成测试
- 要求明确断言和可核验产物
- 区分实现完成与验收完成
### 改动内容
- 更新 `AGENTS.md` 测试与验收原则
- 同步 `opencode_rules/AGENTS.md`
- 调整 `opencode_rules/SKILLS/code-review.mdc` 检查项
- 同步 `setup_agent_rules.sh` 内嵌规则
- 同步 `init_agent_rules.sh` 内嵌规则与日志
### 影响范围
- 统一开发与评审的验收口径
- 新项目安装时获得更新规则
- 不改变安装脚本执行逻辑
### 后续计划
- 根据实际验收补充必要例外
## [2026-03-20] - 调整单文件行数约束为分层规则
### 问题描述
- `260 行` 作为统一硬限制偏紧
- 容易引发机械拆分与过度碎片化
### 分析原因
- 规则只看行数，未区分职责边界
- 集中声明文件与生成文件不适合套用同一阈值
- 旧规则对评审触发线与例外场景定义不足
### 解决方案
- 将单文件约束改为“建议值 + 评估线 + 硬上限”
- 新增判断原则、允许超限场景、必须拆分信号
- 同步 OpenCode 规则、安装脚本与技能模板
### 改动内容
- 更新 `AGENTS.md`：将 `≤ 260 行` 升级为分层规则
- 更新 `opencode_rules/AGENTS.md`：同步新规则
- 更新 `setup_agent_rules.sh` 与 `init_agent_rules.sh`：同步内嵌规则模板
- 更新 `opencode_rules/SKILLS/refactor.mdc`：调整重构校验项文案
### 影响范围
- 新项目初始化后默认采用更稳妥的代码规模约束
- 评审时可结合职责边界判断，而非只看行数
- 对已有项目无运行时影响，仅更新规范说明
### 后续计划
- 如后续出现执行分歧，再补充语言或场景级例外说明
## [2026-01-20] - 修复 Awesome Skills 扁平化安装
### 问题描述
- skills 目录嵌套为 `.agent/skills/antigravity-awesome-skills/skills`
- Antigravity 无法识别技能
### 分析原因
- 安装脚本直接复制/克隆仓库根目录
- 未将 `skills/*` 扁平化到 `.agent/skills/`
### 解决方案
- 安装时将 `skills/*` 扁平化到 `.agent/skills/`
- 保留 `scripts/`、`skills_index.json`、`README.md`
### 改动内容
- 更新 `setup_agent_rules.sh`：技能扁平化安装
- 更新 `tools/build_init.sh` 与 `init_agent_rules.sh`：临时目录克隆后扁平化
- 更新 `README.md`：补充扁平化说明
### 影响范围
- 新项目默认可识别 skills
- 旧项目需重新安装或手动调整
### 后续计划
- 无
## [2026-01-20] - 补充 README 一键安装指令
### 问题描述
- 需要在 README 提供可复制的安装指令
- 便于直接交给 Agent 自动部署
### 分析原因
- README 中缺少明确的“可复制指令”区块
### 解决方案
- 增加一条可复制的 Agent 安装指令
- 保留 `--no-skills` 可选说明
- 使用仓库实际 raw 地址示例
### 改动内容
- 更新 `README.md`：新增“给 Agent 的一条可复制指令”
- 重新生成 `init_agent_rules.sh`：同步内嵌 README
### 影响范围
- 文档说明更清晰
- 不影响安装逻辑
### 后续计划
- 无
## [2026-01-20] - 集成 Awesome Skills 与工作区模板增强
### 问题描述
- 现有规则库缺少稳定技能集合
- 新项目初始化缺少模板配置
- 一键部署未覆盖技能安装
### 分析原因
- Awesome Skills 未纳入安装链路
- 工作区模板未同步到本库
- init 脚本缺少技能拉取
### 解决方案
- 引入 Awesome Skills 作为内置来源
- 新增 `.context` 与 `.agent/workflows`
- 安装脚本补充技能步骤
### 改动内容
- 新增 `.context/*.md` 与 `.agent/workflows/*.md`
- 拉取 `antigravity-awesome-skills` 到 `.agent/skills/antigravity-awesome-skills`
- 更新 `setup_agent_rules.sh`：安装技能与模板目录
- 更新 `tools/build_init.sh` 与 `init_agent_rules.sh`：支持 `--no-skills`
- 更新 `README.md`、`PACKING.md`：补充部署说明