@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.
Files changed (30) hide show
  1. package/README.md +163 -554
  2. package/cli/assets/agents/browser-debugger.toml +0 -1
  3. package/cli/assets/agents/docs-researcher.toml +0 -1
  4. package/cli/assets/agents/explorer.toml +1 -2
  5. package/cli/assets/agents/fixer.toml +2 -3
  6. package/cli/assets/agents/reviewer.toml +1 -2
  7. package/cli/assets/skill/SKILL.md +98 -207
  8. package/cli/assets/skill/data/templates/ENGINEERING.md +113 -468
  9. package/cli/assets/skill/data/templates/docs/tasks/closure-log.md +11 -22
  10. package/cli/assets/skill/data/templates/docs/tasks/taskbook.md +16 -39
  11. package/cli/assets/skill/data/templates/tools/ap.py +16 -0
  12. package/cli/assets/skill/scripts/ap.py +703 -138
  13. package/cli/assets/skill/scripts/scaffold_templates.py +136 -0
  14. package/cli/src/index.js +317 -42
  15. package/cli/tests/ap_profiles_test.py +428 -0
  16. package/cli/tests/index.test.js +376 -87
  17. package/package.json +3 -3
  18. package/cli/assets/skill/data/templates/docs/architecture/adr/_TEMPLATE-ADR.md +0 -38
  19. package/cli/assets/skill/data/templates/docs/architecture/structure-standard.md +0 -92
  20. package/cli/assets/skill/data/templates/docs/bugs/bug-list.md +0 -5
  21. package/cli/assets/skill/data/templates/docs/deployment/deploy-records/_TEMPLATE-DEPLOY-RECORD.md +0 -19
  22. package/cli/assets/skill/data/templates/docs/deployment/deploy-runbook.md +0 -11
  23. package/cli/assets/skill/data/templates/docs/design/_TEMPLATE-DD.md +0 -49
  24. package/cli/assets/skill/data/templates/docs/interfaces/api-change-log.md +0 -11
  25. package/cli/assets/skill/data/templates/docs/interfaces/api.md +0 -36
  26. package/cli/assets/skill/data/templates/docs/reviews/_TEMPLATE-REVIEW.md +0 -36
  27. package/cli/assets/skill/data/templates/docs/reviews/optimization-backlog.md +0 -25
  28. package/cli/assets/skill/data/templates/docs/reviews/project-health-baseline.md +0 -66
  29. package/cli/assets/skill/data/templates/docs/tasks/summaries/_TEMPLATE-TASK-SUMMARY.md +0 -35
  30. package/cli/assets/skill/data/templates/docs/testing/regression-matrix.md +0 -11
@@ -1,92 +0,0 @@
1
- # Project Structure Standard
2
-
3
- > 通用工程结构标准。项目可以按技术栈调整目录名,但不能降低分层、复用、可维护性和验证要求。
4
-
5
- ## 1. 目标
6
-
7
- - 目录结构能表达业务边界、技术边界和变更边界。
8
- - 单个文件、类、组件、函数只承担清晰职责。
9
- - 新代码优先复用成熟库、项目已有 helper、组件、脚本和平台能力。
10
- - 优化结论按健康基线和 backlog 判断,避免反复把已接受债务当成当前阻塞。
11
-
12
- ## 2. 推荐分层
13
-
14
- 不同语言和框架可以使用不同目录名,但职责应保持一致:
15
-
16
- | 层级 | 常见目录名 | 职责 | 不应包含 |
17
- | --- | --- | --- | --- |
18
- | Domain | `domain`, `model`, `entity`, `value-object`, `policy` | 业务概念、规则、不可变约束 | HTTP、DB、UI、第三方 SDK 细节 |
19
- | Application | `application`, `service`, `usecase`, `workflow` | 用例编排、事务边界、跨领域协调 | 控制器入参解析、SQL 细节、组件渲染 |
20
- | Infrastructure | `infrastructure`, `adapter`, `repository`, `client`, `gateway` | DB、缓存、消息、外部 API、文件系统、运行时适配 | 核心业务规则 |
21
- | Interface | `api`, `controller`, `handler`, `route`, `page`, `component`, `view` | HTTP/CLI/UI 入口、协议转换、展示逻辑 | 复杂业务编排和持久化细节 |
22
- | Shared | `shared`, `common`, `utils`, `lib` | 稳定通用工具、类型、组件 | 业务专属逻辑、临时拼凑函数 |
23
- | Tooling | `scripts`, `tools`, `docs/tools` | 自动化脚本、门禁、迁移辅助 | 在线业务运行逻辑 |
24
-
25
- ## 3. 落位规则
26
-
27
- - 修改前先定位现有同类实现、模块边界、调用链和测试入口。
28
- - 新增业务规则优先进入 Domain 或 Application,不直接塞进 Controller/Page/Component。
29
- - 新增外部依赖访问优先进入 Infrastructure,并通过接口或窄适配暴露给 Application。
30
- - UI 组件应拆分为容器、状态/数据适配、纯展示组件;不要在单个页面里混合远程请求、权限、复杂计算和大段渲染。
31
- - 跨模块、跨层、数据库、API、部署、权限、并发、缓存、核心页面流的变更,需要最小设计;影响长期结构的决策需要 ADR。
32
-
33
- ## 3.1 Import Boundary Rules
34
-
35
- `structure.layer_rules` 会做轻量 import 边界检查。默认规则:
36
-
37
- - Domain / Model 不依赖 Infrastructure、Repository、Client、Controller、Handler、Page、Component、View。
38
- - Application / Service / Usecase 不依赖 Controller、Handler、Page、Component、View。
39
- - Shared / Common / Utils / Lib 不依赖业务层、应用层、基础设施层或 UI 入口。
40
-
41
- 项目可以按技术栈调整路径规则。调整规则时必须保持方向:内层业务规则不反向依赖外层技术细节。
42
-
43
- ## 4. 文件和函数规模
44
-
45
- 默认阈值来自 `docs/ENGINEERING.md`:
46
-
47
- - 文件超过 `structure.max_file_lines_warn`:只允许小修、缺陷修复、类型补充;新增职责应先抽取模块。
48
- - 文件超过 `structure.max_file_lines_block`:不得继续承载新职责,除非是生成物、外部产物或已在 `structure.allow_large_files` 中声明。
49
- - 禁止仅为了降低行数而拆文件。拆分必须服务于清晰的业务边界、技术边界、变更安全和阅读连续性;如果事务、状态机、用例流程或测试场景需要放在一起维护,应保留内聚结构并记录为接受债务。
50
- - 历史大文件如果已进入健康基线 / backlog,可在 `structure.accepted_debt_paths` 中登记;登记只豁免历史体量,不豁免继续大幅新增。
51
- - 函数 / 方法 / 组件超过 `structure.max_function_lines_warn`:应拆分为命名清晰的子函数、hook、service、query、mapper 或 view component。
52
- - 对大文件新增超过 `structure.max_added_lines_to_large_file` 行:默认阻塞,必须拆分或记录例外理由。
53
-
54
- ## 5. 复用优先规则
55
-
56
- 新增以下能力前必须先搜索现有实现:
57
-
58
- - HTTP/API client、认证、权限、表单校验、错误处理、日志、缓存、重试、并发控制。
59
- - 日期、金额、单位、国际化、文件处理、导入导出、分页、排序、过滤、权限判断。
60
- - UI 基础组件、布局、表格、弹窗、上传、图表、状态管理、路由守卫。
61
- - 自动化脚本、部署脚本、测试工具、mock、fixture、数据迁移 helper。
62
-
63
- 允许自研的前提:
64
-
65
- - 成熟库不能满足性能、并发、部署、许可证、离线、兼容性或安全边界。
66
- - ADR 或设计记录说明取舍。
67
- - 有测试、benchmark、压测或真实运行证据支撑。
68
-
69
- ## 6. Review 口径
70
-
71
- 结构 review 不应只说“还能优化”。必须分级:
72
-
73
- - P0 阻塞:构建 / 发布 / 数据 / 安全 / 核心流程风险。
74
- - P1 必修:明显架构违规、契约漂移、重要测试缺失、近期高风险改动。
75
- - P2 计划债务:大文件、热点目录、可拆分模块、测试增强。
76
- - P3 可选建议:命名、风格、进一步抽象、审美类优化。
77
-
78
- “优化完成”只表示当前约定范围闭环,不表示没有任何后续可优化点。新会话必须先读健康基线和 backlog,只报告新增、恶化、未记录 P0/P1,或需要升级优先级的已记录问题。
79
-
80
- ## 7. Evidence And Gate Profile
81
-
82
- - `docs/tasks/evidence.jsonl` 记录 doctor、classify、structure-check、light-gate、verify、closure 等结构化证据。
83
- - `.local/auto-coding-skill/gate-profile.jsonl` 记录门禁命令耗时和失败率,用于优化小步快跑的 gate 范围。
84
- - Markdown 记录面向人读,JSONL 记录面向工具复盘;两者不互相替代。
85
-
86
- ## 8. Docs Ledger Health
87
-
88
- - `docs/tasks/taskbook.md`、`docs/tasks/closure-log.md` 和顶层 `docs/design/T*.md` 是活跃工作账本,不是永久历史仓库。
89
- - 超过 `docs.active_taskbook_max_lines`、`docs.active_closure_log_max_lines` 或 `docs.active_design_max_files` 后,必须把已关闭历史内容物理归档到 `docs.task_archive_dir` / `docs.design_archive_dir`。
90
- - 归档必须先运行 `docs-ledger-archive --plan` 并确认只包含已关闭任务、无 active task 冲突的闭环记录和对应顶层 DD,再运行 `docs-ledger-archive --write`。补历史月份时才加 `--period 2026-06`。
91
- - `docs.archive_index` 只能做导航和检索入口。只有索引、没有物理归档,仍然是不合格的账本瘦身。
92
- - `doctor` 默认执行 `docs-ledger-check`。迁移期可以临时调高预算或关闭阻塞,但必须在 backlog 中记录恢复条件。
@@ -1,5 +0,0 @@
1
- # Bug List(长期积累:回归必测)
2
-
3
- | Bug ID | Date | Area | Summary | Steps to Reproduce | Expected | Actual | Severity | Status | Fix Commit/PR | Regression Test ID |
4
- |---|---|---|---|---|---|---|---|---|---|---|
5
- | B-0001 | YYYY-MM-DD | API | <desc> | <steps> | <expected> | <actual> | P1 | Open | | R-??? |
@@ -1,19 +0,0 @@
1
- # Deploy Record — <Task ID> — YYYY-MM-DD
2
-
3
- > 仅在真实需要独立部署审计记录时使用。
4
-
5
- ## 1. Deployment Context
6
- - Task ID:
7
- - Commit:
8
- - CI/Jenkins Build:
9
- - Target Env:
10
-
11
- ## 2. Verification
12
- - Health check:
13
- - Key API:
14
- - Key page / business path:
15
-
16
- ## 3. Notes
17
- - Risk:
18
- - Rollback:
19
- - Follow-up:
@@ -1,11 +0,0 @@
1
- # Deployment Runbook(按需使用,不是默认小改动产物)
2
-
3
- 用途:
4
- - 手工部署
5
- - 高风险发布
6
- - 需要额外审计证据的发布
7
-
8
- 默认情况下:
9
- - 小改动优先走项目已配置的 CI/Jenkins 自动构建与自动部署;未启用时以本地 gate 和 closure evidence 为准
10
- - 主要闭环证据写入 `docs/tasks/closure-log.md`
11
- - 只有需要更重的发布审计时,才补本目录文档
@@ -1,49 +0,0 @@
1
- # DD — <Task ID> <Title>
2
-
3
- - Task ID:T0001 / T0001-1
4
- - 状态:Draft | Reviewed | Approved
5
- - 关联:`docs/tasks/taskbook.md` 中对应段落
6
-
7
- ## 1. 背景与目标
8
- ## 2. 范围与非目标
9
- ## 3. 现状与问题
10
- ## 4. 方案与取舍
11
- ## 5. 架构落位与复用检查
12
- - 目标层级:Domain / Application / Infrastructure / Interface / Shared / Tooling
13
- - 既有复用点:
14
- - 是否需要 ADR:Yes / No;如 Yes,记录到 `docs/architecture/adr/`
15
- - 是否触及大文件 / 大组件:
16
-
17
- ## 6. 接口设计(与 docs/interfaces/api.md 对齐)
18
- ## 7. 数据设计(迁移/回滚)
19
-
20
- ## 8. 时序图(强制)
21
- ```mermaid
22
- sequenceDiagram
23
- participant C as Client
24
- participant A as API
25
- participant S as Service
26
- participant D as DB
27
- C->>A: request
28
- A->>S: call
29
- S->>D: query/tx
30
- D-->>S: result
31
- S-->>A: response
32
- A-->>C: response
33
- ```
34
-
35
- ## 9. ER 图(强制)
36
- ```mermaid
37
- erDiagram
38
- ENTITY_A ||--o{ ENTITY_B : relates
39
- ENTITY_A { string id }
40
- ENTITY_B { string id string a_id }
41
- ```
42
-
43
- ## 10. 接口时序/调用编排(强制)
44
- ## 11. 测试方案(必须自动化 + 覆盖历史 bug)
45
- ## 12. 安全与合规
46
- ## 13. 性能与容量
47
- ## 14. 风险清单
48
- ## 15. 回滚方案
49
- ## 16. 影响面与发布计划
@@ -1,11 +0,0 @@
1
- # API Change Log(接口变更清单:追加式)
2
-
3
- ---
4
-
5
- ## T0001 — <Title> — YYYY-MM-DD
6
- - 新增:
7
- - 修改:
8
- - 废弃:
9
- - 兼容策略:
10
- - 迁移/升级说明:
11
- - 影响面:
@@ -1,36 +0,0 @@
1
- # API Documentation(权威接口文档)
2
-
3
- > 本文件为权威接口文档。任何接口新增/修改/废弃,都必须同步更新本文件,并在 `api-change-log.md` 追加记录。
4
-
5
- ## 1. 基本约定
6
- - Base URL:
7
- - Content-Type:
8
- - 认证方式(如有):
9
- - 时区/时间格式:
10
- - 分页/排序(如有):
11
- - 错误码规范:
12
-
13
- ## 2. Endpoint Index(目录)
14
- | Method | Path | Summary | Auth | Request | Response |
15
- |---|---|---|---|---|---|
16
- | <METHOD> | <PATH> | <Summary> | <Yes/No> | <Request shape> | <Response shape> |
17
-
18
- ## 3. Endpoints
19
-
20
- ### 3.1 <METHOD> <PATH>
21
- **Summary**: <Summary>
22
-
23
- **Request**
24
- - Headers: -
25
- - Query: -
26
- - Body: -
27
-
28
- **Response**
29
- - <Status>: <Meaning>
30
- - Example:
31
- ```json
32
- {}
33
- ```
34
-
35
- ## 4. Changelog
36
- - See `api-change-log.md`
@@ -1,36 +0,0 @@
1
- # Review — <Task ID> — YYYY-MM-DD HH:MM
2
-
3
- > 仅在任务需要独立 review 记录时使用;不是每个小改动的默认强制文档。
4
-
5
- ## 1. 静态分析结果
6
- - Command:structure-check / light_gate / diff_check / verify_api_docs / verify_jenkins / verify_jenkins_skipped
7
- - Summary:
8
- - Issues:
9
-
10
- ## 2. 结构与优化基线
11
- - Structure standard:`docs/architecture/structure-standard.md`
12
- - Health baseline read:Yes / No / N/A
13
- - Optimization backlog read:Yes / No / N/A
14
- - New / worsened issues:
15
- - Accepted debt not repeated:
16
- - Completion standard:Met / Not met / N/A
17
-
18
- ## 3. 本地轻量校验
19
- - light_gate or quick_test/test/build:
20
- - structure-check:
21
- - gate-profile:`.local/auto-coding-skill/gate-profile.jsonl`
22
- - evidence-log:`docs/tasks/evidence.jsonl`
23
- - api docs:
24
- - ci/jenkins:
25
-
26
- ## 4. 按需本地运行验证(如果有)
27
- - runtime-up / health:
28
-
29
- ## 5. CI/Jenkins 与目标环境
30
- - CI/Jenkins readiness:
31
- - Target env verification:
32
-
33
- ## 6. 风险与结论
34
- - Risk:
35
- - Priority:P0 / P1 / P2 / P3 / N/A
36
- - Conclusion:Pass / Blocked / Accepted debt
@@ -1,25 +0,0 @@
1
- # Optimization Backlog
2
-
3
- > 这里记录持续优化项。被记录为 `accepted-debt` 的项目不等于当前任务未完成;只有新增、恶化或升级优先级时才需要重新报告。
4
-
5
- ## Status Values
6
-
7
- - `open`: 已确认,等待排期。
8
- - `accepted-debt`: 当前接受的债务,按触发条件再处理。
9
- - `in-progress`: 正在处理。
10
- - `closed`: 已闭环,证据写在表格中。
11
- - `superseded`: 被其他方案或任务替代。
12
-
13
- ## Backlog
14
-
15
- | ID | Priority | Status | Scope | Item | Reason | Acceptance | Last reviewed |
16
- | --- | --- | --- | --- | --- | --- | --- | --- |
17
- | OPT-000 | P2 | open | `<path/module>` | | | | YYYY-MM-DD |
18
- | LEDGER-000 | P2 | open | `docs/tasks`, `docs/design` | Archive active ledgers when they exceed `docs.active_*` budgets | Keeps project context searchable and prevents giant task/closure/DD files | `ap.py docs-ledger-archive --plan` reviewed, `--write` applied when safe, then `ap.py docs-ledger-check` passes | YYYY-MM-DD |
19
-
20
- ## Review Rules
21
-
22
- - P0/P1 不能长期停留在 backlog;应进入当前迭代或明确升级。
23
- - P2 可以排队,但必须有范围、原因和验收标准。
24
- - P3 只在低成本或同域修改时顺手处理,不影响“优化完成”结论。
25
- - 新会话整体分析只允许新增、升级或关闭条目,不要重复制造同义优化项。
@@ -1,66 +0,0 @@
1
- # Project Health Baseline
2
-
3
- > 用于固定“当前项目结构是否达标”的判断口径。整体分析、结构优化和新会话复盘必须先读本文件,再读 `docs/reviews/optimization-backlog.md`。
4
-
5
- - Baseline date: YYYY-MM-DD
6
- - Baseline commit: `<git-sha>`
7
- - Owner: <name / team>
8
- - Review scope: <repo / module / subsystem>
9
- - Standard: `docs/architecture/structure-standard.md`
10
-
11
- ## 1. Current Accepted Structure
12
-
13
- 记录当前被接受的目录结构、主要模块边界、已知历史原因和不再重复争论的事实。
14
-
15
- | Area | Current state | Accepted because | Review date |
16
- | --- | --- | --- | --- |
17
- | <module/path> | | | |
18
- | `docs/tasks/taskbook.md` | active ledger, <= configured line budget | History is archived under `docs/tasks/archives/**` | YYYY-MM-DD |
19
- | `docs/tasks/closure-log.md` | active closure ledger, <= configured line budget | History is archived under `docs/tasks/archives/**` | YYYY-MM-DD |
20
- | `docs/design/` | active DDs only, <= configured file budget | Historical DDs are archived under `docs/archive/design/**` | YYYY-MM-DD |
21
-
22
- ## 2. Closed Optimization Scope
23
-
24
- 记录已经闭环的优化项。新会话不能把这些项重复判定为“当前未完成”。
25
-
26
- | ID | Closed date | Scope | Acceptance evidence |
27
- | --- | --- | --- | --- |
28
- | OPT-000 | YYYY-MM-DD | | |
29
-
30
- ## 3. Accepted Debt
31
-
32
- 这些是已知但暂不处理的问题。除非新增风险、影响扩大或优先级升级,否则只保留在 backlog,不作为当前任务失败原因。
33
-
34
- | ID | Priority | Scope | Debt | Why accepted | Revisit trigger |
35
- | --- | --- | --- | --- | --- | --- |
36
- | DEBT-000 | P2 | | | | |
37
-
38
- ## 4. Priority Rules
39
-
40
- - P0: blocks build, release, deploy, core user flow, data integrity, security, or compliance.
41
- - P1: clear architectural violation, contract drift, missing test around high-risk change, or recently introduced maintainability risk.
42
- - P2: planned debt such as large files, hot directories, module extraction, stronger tests, or tool consolidation.
43
- - P3: optional naming, style, polish, or further abstraction.
44
-
45
- ## 5. Completion Standard
46
-
47
- An optimization task is complete when all are true:
48
-
49
- - The scoped P0/P1/P2 items listed for this task are closed.
50
- - Local gate passed, including docs ledger and structure checks when enabled.
51
- - No new unclassified P0/P1 was introduced.
52
- - Remaining P2/P3 items are either in `docs/reviews/optimization-backlog.md` or accepted debt above.
53
- - Review output says explicitly whether the project meets this baseline.
54
-
55
- ## 6. New Review Instructions
56
-
57
- When asked to analyze structure or optimization:
58
-
59
- - Read this baseline first.
60
- - Read `docs/reviews/optimization-backlog.md` second.
61
- - Report only:
62
- - new or worsened issues;
63
- - unrecorded P0/P1;
64
- - backlog items whose priority should now be upgraded;
65
- - baseline drift.
66
- - Do not repeat accepted debt as fresh findings.
@@ -1,35 +0,0 @@
1
- # Task Summary — <TASK_ID> — <Title>
2
-
3
- > 仅用于高风险、跨模块、阶段性里程碑、需要完整复盘的任务。
4
-
5
- - Task ID:<TASK_ID>
6
- - Date:YYYY-MM-DD
7
- - Scope(本次范围):
8
- - Out of scope(明确未做):
9
-
10
- ---
11
-
12
- ## 1. 目标与验收结论
13
- - 目标:
14
- - 验收结论:PASS / FAIL
15
-
16
- ## 2. 变更概览
17
- - 关键改动点:
18
- - 影响模块:
19
- - 兼容性影响:
20
-
21
- ## 3. 质量证据
22
- - 本地轻量校验:light_gate or quick_test/test/build / api docs / ci/jenkins / diff-check
23
- - 结构检查:structure-check
24
- - 结构化证据:`docs/tasks/evidence.jsonl`
25
- - 门禁画像:`.local/auto-coding-skill/gate-profile.jsonl`
26
- - CI/Jenkins Build:
27
- - 目标环境验证:
28
- - 闭环记录:`docs/tasks/closure-log.md`
29
-
30
- ## 4. 风险与回滚
31
- - 风险:
32
- - 回滚方式:
33
-
34
- ## 5. 后续行动
35
- - TODO:
@@ -1,11 +0,0 @@
1
- # Regression Matrix(按需回归记录,不是每个小改动的默认门禁)
2
-
3
- > 1. 只记录真实执行过的回归项。
4
- > 2. `Status` 允许值:`TODO` / `PASS` / `FAIL`。
5
- > 3. 未执行项保持 `TODO`,不得预填 `PASS`。
6
- > 4. 只有真实执行并具备证据时,才允许填写 `PASS`。
7
- > 5. `check-matrix` 只在显式要求完整回归时使用,不作为默认小改动门禁。
8
-
9
- | ID | Area | Endpoint/Feature | Test Type | Steps / Command | Expected | Status(TODO/PASS/FAIL) | Evidence |
10
- |---|---|---|---|---|---|---|---|
11
- | R-001 | <Area> | <Endpoint or feature> | <manual/smoke/regression> | <command or manual steps> | <expected result> | TODO | <real log path / screenshot / report> |