From ed945abdf124967662f416396e4bc90e515af83c Mon Sep 17 00:00:00 2001 From: zeaslity Date: Wed, 18 Mar 2026 16:16:47 +0800 Subject: [PATCH] =?UTF-8?q?=E5=A4=A7=E9=87=8F=E6=9B=B4=E6=96=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../skills/backend-go-gin-gorm}/SKILL.md | 2 +- .../examples/dao-example.go | 0 .../examples/handler-example.go | 0 .../examples/service-example.go | 0 .../reference/api-design-spec.md | 0 .../reference/api-response-spec.md | 0 .../reference/coding-standards.md | 0 .../reference/error-codes.go | 0 .../reference/framework-usage.md | 0 .../reference/logging-standards.md | 0 .../reference/project-structure.md | 0 .../reference/time-handling.md | 0 .../scripts/validate-structure.sh | 0 .agents/skills/dds-to-skill/SKILL.md | 391 ++++ .../conversion-example-multi-module.md | 137 ++ .../examples/conversion-example-workflow.md | 95 + .../reference/dds-extraction-guide.md | 260 +++ .../reference/frontmatter-spec.md | 162 ++ .../reference/quality-checklist.md | 114 + .../dds-to-skill/reference/skill-templates.md | 255 +++ .../scripts/verify-skill-output.sh | 214 ++ .agents/skills/dds-to-skill/scripts/verify.sh | 60 + .../skills/developing-projectmoneyx/SKILL.md | 267 +++ .../01-architecture/batch-state-machine.md | 57 + .../01-architecture/system-overview.md | 113 + .../02-parser-engine/field-mappings.md | 156 ++ .../02-parser-engine/parser-interface.md | 90 + .../reference/03-dedup-engine/fingerprint.md | 41 + .../reference/03-dedup-engine/fuzzy-dedup.md | 85 + .../reference/03-dedup-engine/strict-dedup.md | 48 + .../03-dedup-engine/transfer-link.md | 78 + .../04-rule-engine/rule-conditions.md | 63 + .../04-rule-engine/rule-execution.md | 89 + .../reference/05-database/db-schema.md | 252 +++ .../reference/05-database/indexes.md | 25 + .../reference/06-api-design/api-catalog.md | 87 + .../06-api-design/response-format.md | 57 + .../07-export-engine/firefly-mapping.md | 65 + .../07-export-engine/import-validation.md | 24 + .../reference/08-frontend/components.md | 82 + .../reference/08-frontend/routes.md | 95 + .../reference/09-nonfunctional/deployment.md | 86 + .../reference/09-nonfunctional/performance.md | 55 + .../scripts/verify.sh | 101 + .../skills/frontend-vue3-vuetify}/SKILL.md | 2 +- .../examples/api-module.ts | 0 .../examples/data-table-page.vue | 0 .../examples/page-layout.vue | 0 .../reference/api-patterns.md | 0 .../reference/layout-patterns.md | 0 .../reference/typescript-rules.md | 0 .../reference/ui-interaction.md | 0 .agents/skills/skill-creator/LICENSE.txt | 202 ++ .agents/skills/skill-creator/SKILL.md | 479 ++++ .../skills/skill-creator/agents/analyzer.md | 274 +++ .../skills/skill-creator/agents/comparator.md | 202 ++ .agents/skills/skill-creator/agents/grader.md | 223 ++ .../skill-creator/assets/eval_review.html | 146 ++ .../eval-viewer/generate_review.py | 471 ++++ .../skill-creator/eval-viewer/viewer.html | 1325 +++++++++++ .../skill-creator/references/schemas.md | 430 ++++ .../scripts/aggregate_benchmark.py | 401 ++++ .../skill-creator/scripts/generate_report.py | 326 +++ .../scripts/improve_description.py | 248 +++ .../skill-creator/scripts/package_skill.py | 136 ++ .../skill-creator/scripts/quick_validate.py | 103 + .../skills/skill-creator/scripts/run_eval.py | 310 +++ .../skills/skill-creator/scripts/run_loop.py | 332 +++ .agents/skills/skill-creator/scripts/utils.py | 47 + .../2026年2月11日-代理方案.md | 287 +++ 14-2026年2月11日-XAwindows转发/gost.yaml | 45 + 15-CICD工具选型/1-开源工具选型.md | 135 ++ 15-CICD工具选型/2-gemi-选型说明.md | 290 +++ 15-CICD工具选型/3-per-选型说明.md | 856 +++++++ .../1-原始需求/0-产品经理-prompt.md | 21 + .../1-原始需求/1-初始需求稿.md | 83 + .../1-原始需求/2-1-优化产品需求文档PRD.md | 106 + .../1-原始需求/2-优化产品需求文档PRD.md | 139 ++ .../2-概要详细设计/0-概要设计prompt.md | 33 + .../2-概要详细设计/3-详细设计说明书.md | 1785 +++++++++++++++ .../3-实现详细稿/1-ProjectMoneyM-PRD.md | 106 + .../3-实现详细稿/2-ProjectMoneyM-DDS.md | 951 ++++++++ .../3-实现详细稿/3-DataGrip-DDS.md | 637 ++++++ .../4-DDS-to-Stitch-Prompt-Guide.md | 566 +++++ .../1-原始需求/0-产品经理-prompt.md | 17 + 17-ProjectMoneyX/1-原始需求/1-初始需求稿.md | 19 + .../1-原始需求/2-优化产品需求文档PRD.md | 0 .../2-概要详细设计/0-概要设计prompt.md | 31 + .../2-概要详细设计/bill-data-instructions.md | 51 + 17-ProjectMoneyX/2-概要详细设计/prd-claude.md | 565 +++++ 17-ProjectMoneyX/2-概要详细设计/prd-gemini.md | 70 + 17-ProjectMoneyX/2-概要详细设计/prd-gpt.md | 528 +++++ 17-ProjectMoneyX/2-概要详细设计/prd-origin.md | 19 + ...账单流水文件(20250101-20250331)_20260202151120.xlsx | Bin 0 -> 25112 bytes .../支付宝交易明细(20250101-20251231).csv | 717 ++++++ .../支付宝交易明细(20250101-20251231).xlsx | Bin 0 -> 78662 bytes .../3-实现详细稿/1-ProjectMoneyX-PRD.md | 565 +++++ .../3-实现详细稿/2-ProjectMoneyX-DDS.md | 1959 +++++++++++++++++ 17-ProjectMoneyX/3-实现详细稿/dds-chatgpt.md | 951 ++++++++ 17-ProjectMoneyX/3-实现详细稿/dds-gemini.md | 230 ++ .../1-项目部署-管理/2-修改需求.md | 26 + .../1-项目部署-管理/claude-dds.md | 514 +++++ .../1-项目部署-管理/docs/AirScript-文档.md | 703 ++++++ .../1-项目部署-管理/docs/python脚本使用指南.md | 1552 +++++++++++++ .../1-项目部署-管理/gemini-dds.md | 84 + .../scripts/airscript-auto-create-deploy-records.js | 386 ++++ .../scripts/airscript-button-create-deploy-records.js | 747 +++++++ .../1-项目部署-管理/scripts/airscript-create-tables.js | 468 ++++ .../scripts/airscript-deploy-type-check.js | 56 + .../1-项目部署-管理/scripts/airscript-export-schema.js | 329 +++ .../1-项目部署-管理/scripts/airscript-fix-link-field.js | 120 + .../1-项目部署-管理/scripts/api-client.js | 256 +++ .../1-项目部署-管理/scripts/config.js | 48 + .../1-项目部署-管理/scripts/create-tables.js | 200 ++ .../1-项目部署-管理/scripts/package.json | 14 + .../1-项目部署-管理/scripts/table-definitions.js | 701 ++++++ .../1-项目部署-管理/scripts/test-auth.js | 70 + .../1-项目部署-管理/金山多维数据表格-PRD.md | 144 ++ .../1-项目部署-管理/项目部署-台账-排期-管理.md | 28 + .../2-对研发交接需求/快文-协作规范.md | 84 + .../3-对行业组交接需求/工作流程说明.md | 37 + .../3-对行业组交接需求/快文-协作规范.md | 39 + .../5-2026年3月10日/2026年3月10日-参会应对.md | 19 + .../5-2026年3月10日/2026年3月10日-暂停原因.md | 29 + .../9-人员分工管理规范/1-工作量占比.md | 20 + .../9-人员分工管理规范/1-工作量绘图-prompt.md | 84 + .../9-人员分工管理规范/1.1-工作粗项.png | Bin 0 -> 5029869 bytes .../9-人员分工管理规范/1.2-工作细项.png | Bin 0 -> 7012902 bytes .../9-人员分工管理规范/2-工作优先级排期.md | 46 + 18-基础架构及交付部署特战队/任务.md | 59 + 19-CMII快文规范/中国移动快文prompt.md | 48 + 19-CMII快文规范/快文prompt.md | 149 ++ .../2-概要详细设计/0-概要设计prompt.md | 5 + .../3-实现详细稿/1-DDS-to-Stitch转换.md | 41 + skills-lock.json | 10 + tmp.md | 27 +- 136 files changed, 28252 insertions(+), 16 deletions(-) rename {1-AgentSkills/coding-go-gin-gorm => .agents/skills/backend-go-gin-gorm}/SKILL.md (99%) rename {1-AgentSkills/coding-go-gin-gorm => .agents/skills/backend-go-gin-gorm}/examples/dao-example.go (100%) rename {1-AgentSkills/coding-go-gin-gorm => .agents/skills/backend-go-gin-gorm}/examples/handler-example.go (100%) rename {1-AgentSkills/coding-go-gin-gorm => .agents/skills/backend-go-gin-gorm}/examples/service-example.go (100%) rename {1-AgentSkills/coding-go-gin-gorm => .agents/skills/backend-go-gin-gorm}/reference/api-design-spec.md (100%) rename {1-AgentSkills/coding-go-gin-gorm => .agents/skills/backend-go-gin-gorm}/reference/api-response-spec.md (100%) rename {1-AgentSkills/coding-go-gin-gorm => .agents/skills/backend-go-gin-gorm}/reference/coding-standards.md (100%) rename {1-AgentSkills/coding-go-gin-gorm => .agents/skills/backend-go-gin-gorm}/reference/error-codes.go (100%) rename {1-AgentSkills/coding-go-gin-gorm => .agents/skills/backend-go-gin-gorm}/reference/framework-usage.md (100%) rename {1-AgentSkills/coding-go-gin-gorm => .agents/skills/backend-go-gin-gorm}/reference/logging-standards.md (100%) rename {1-AgentSkills/coding-go-gin-gorm => .agents/skills/backend-go-gin-gorm}/reference/project-structure.md (100%) rename {1-AgentSkills/coding-go-gin-gorm => .agents/skills/backend-go-gin-gorm}/reference/time-handling.md (100%) rename {1-AgentSkills/coding-go-gin-gorm => .agents/skills/backend-go-gin-gorm}/scripts/validate-structure.sh (100%) create mode 100644 .agents/skills/dds-to-skill/SKILL.md create mode 100644 .agents/skills/dds-to-skill/examples/conversion-example-multi-module.md create mode 100644 .agents/skills/dds-to-skill/examples/conversion-example-workflow.md create mode 100644 .agents/skills/dds-to-skill/reference/dds-extraction-guide.md create mode 100644 .agents/skills/dds-to-skill/reference/frontmatter-spec.md create mode 100644 .agents/skills/dds-to-skill/reference/quality-checklist.md create mode 100644 .agents/skills/dds-to-skill/reference/skill-templates.md create mode 100644 .agents/skills/dds-to-skill/scripts/verify-skill-output.sh create mode 100644 .agents/skills/dds-to-skill/scripts/verify.sh create mode 100644 .agents/skills/developing-projectmoneyx/SKILL.md create mode 100644 .agents/skills/developing-projectmoneyx/reference/01-architecture/batch-state-machine.md create mode 100644 .agents/skills/developing-projectmoneyx/reference/01-architecture/system-overview.md create mode 100644 .agents/skills/developing-projectmoneyx/reference/02-parser-engine/field-mappings.md create mode 100644 .agents/skills/developing-projectmoneyx/reference/02-parser-engine/parser-interface.md create mode 100644 .agents/skills/developing-projectmoneyx/reference/03-dedup-engine/fingerprint.md create mode 100644 .agents/skills/developing-projectmoneyx/reference/03-dedup-engine/fuzzy-dedup.md create mode 100644 .agents/skills/developing-projectmoneyx/reference/03-dedup-engine/strict-dedup.md create mode 100644 .agents/skills/developing-projectmoneyx/reference/03-dedup-engine/transfer-link.md create mode 100644 .agents/skills/developing-projectmoneyx/reference/04-rule-engine/rule-conditions.md create mode 100644 .agents/skills/developing-projectmoneyx/reference/04-rule-engine/rule-execution.md create mode 100644 .agents/skills/developing-projectmoneyx/reference/05-database/db-schema.md create mode 100644 .agents/skills/developing-projectmoneyx/reference/05-database/indexes.md create mode 100644 .agents/skills/developing-projectmoneyx/reference/06-api-design/api-catalog.md create mode 100644 .agents/skills/developing-projectmoneyx/reference/06-api-design/response-format.md create mode 100644 .agents/skills/developing-projectmoneyx/reference/07-export-engine/firefly-mapping.md create mode 100644 .agents/skills/developing-projectmoneyx/reference/07-export-engine/import-validation.md create mode 100644 .agents/skills/developing-projectmoneyx/reference/08-frontend/components.md create mode 100644 .agents/skills/developing-projectmoneyx/reference/08-frontend/routes.md create mode 100644 .agents/skills/developing-projectmoneyx/reference/09-nonfunctional/deployment.md create mode 100644 .agents/skills/developing-projectmoneyx/reference/09-nonfunctional/performance.md create mode 100644 .agents/skills/developing-projectmoneyx/scripts/verify.sh rename {1-AgentSkills/coding-vue3-vuetify => .agents/skills/frontend-vue3-vuetify}/SKILL.md (99%) rename {1-AgentSkills/coding-vue3-vuetify => .agents/skills/frontend-vue3-vuetify}/examples/api-module.ts (100%) rename {1-AgentSkills/coding-vue3-vuetify => .agents/skills/frontend-vue3-vuetify}/examples/data-table-page.vue (100%) rename {1-AgentSkills/coding-vue3-vuetify => .agents/skills/frontend-vue3-vuetify}/examples/page-layout.vue (100%) rename {1-AgentSkills/coding-vue3-vuetify => .agents/skills/frontend-vue3-vuetify}/reference/api-patterns.md (100%) rename {1-AgentSkills/coding-vue3-vuetify => .agents/skills/frontend-vue3-vuetify}/reference/layout-patterns.md (100%) rename {1-AgentSkills/coding-vue3-vuetify => .agents/skills/frontend-vue3-vuetify}/reference/typescript-rules.md (100%) rename {1-AgentSkills/coding-vue3-vuetify => .agents/skills/frontend-vue3-vuetify}/reference/ui-interaction.md (100%) create mode 100644 .agents/skills/skill-creator/LICENSE.txt create mode 100644 .agents/skills/skill-creator/SKILL.md create mode 100644 .agents/skills/skill-creator/agents/analyzer.md create mode 100644 .agents/skills/skill-creator/agents/comparator.md create mode 100644 .agents/skills/skill-creator/agents/grader.md create mode 100644 .agents/skills/skill-creator/assets/eval_review.html create mode 100644 .agents/skills/skill-creator/eval-viewer/generate_review.py create mode 100644 .agents/skills/skill-creator/eval-viewer/viewer.html create mode 100644 .agents/skills/skill-creator/references/schemas.md create mode 100644 .agents/skills/skill-creator/scripts/aggregate_benchmark.py create mode 100644 .agents/skills/skill-creator/scripts/generate_report.py create mode 100644 .agents/skills/skill-creator/scripts/improve_description.py create mode 100644 .agents/skills/skill-creator/scripts/package_skill.py create mode 100644 .agents/skills/skill-creator/scripts/quick_validate.py create mode 100644 .agents/skills/skill-creator/scripts/run_eval.py create mode 100644 .agents/skills/skill-creator/scripts/run_loop.py create mode 100644 .agents/skills/skill-creator/scripts/utils.py create mode 100644 14-2026年2月11日-XAwindows转发/2026年2月11日-代理方案.md create mode 100644 15-CICD工具选型/1-开源工具选型.md create mode 100644 15-CICD工具选型/2-gemi-选型说明.md create mode 100644 15-CICD工具选型/3-per-选型说明.md create mode 100644 16-ProjectMoneyM-转FireFlyIII/1-原始需求/0-产品经理-prompt.md create mode 100644 16-ProjectMoneyM-转FireFlyIII/1-原始需求/1-初始需求稿.md create mode 100644 16-ProjectMoneyM-转FireFlyIII/1-原始需求/2-1-优化产品需求文档PRD.md create mode 100644 16-ProjectMoneyM-转FireFlyIII/1-原始需求/2-优化产品需求文档PRD.md create mode 100644 16-ProjectMoneyM-转FireFlyIII/2-概要详细设计/0-概要设计prompt.md create mode 100644 16-ProjectMoneyM-转FireFlyIII/2-概要详细设计/3-详细设计说明书.md create mode 100644 16-ProjectMoneyM-转FireFlyIII/3-实现详细稿/1-ProjectMoneyM-PRD.md create mode 100644 16-ProjectMoneyM-转FireFlyIII/3-实现详细稿/2-ProjectMoneyM-DDS.md create mode 100644 16-ProjectMoneyM-转FireFlyIII/3-实现详细稿/3-DataGrip-DDS.md create mode 100644 16-ProjectMoneyM-转FireFlyIII/3-实现详细稿/4-DDS-to-Stitch-Prompt-Guide.md create mode 100644 17-ProjectMoneyX/1-原始需求/0-产品经理-prompt.md create mode 100644 17-ProjectMoneyX/1-原始需求/1-初始需求稿.md rename 99-项目模板/3-实现详细稿/1-实现功能-prompt.md => 17-ProjectMoneyX/1-原始需求/2-优化产品需求文档PRD.md (100%) create mode 100644 17-ProjectMoneyX/2-概要详细设计/0-概要设计prompt.md create mode 100644 17-ProjectMoneyX/2-概要详细设计/bill-data-instructions.md create mode 100644 17-ProjectMoneyX/2-概要详细设计/prd-claude.md create mode 100644 17-ProjectMoneyX/2-概要详细设计/prd-gemini.md create mode 100644 17-ProjectMoneyX/2-概要详细设计/prd-gpt.md create mode 100644 17-ProjectMoneyX/2-概要详细设计/prd-origin.md create mode 100644 17-ProjectMoneyX/2-概要详细设计/微信支付账单流水文件(20250101-20250331)_20260202151120.xlsx create mode 100644 17-ProjectMoneyX/2-概要详细设计/支付宝交易明细(20250101-20251231).csv create mode 100644 17-ProjectMoneyX/2-概要详细设计/支付宝交易明细(20250101-20251231).xlsx create mode 100644 17-ProjectMoneyX/3-实现详细稿/1-ProjectMoneyX-PRD.md create mode 100644 17-ProjectMoneyX/3-实现详细稿/2-ProjectMoneyX-DDS.md create mode 100644 17-ProjectMoneyX/3-实现详细稿/dds-chatgpt.md create mode 100644 17-ProjectMoneyX/3-实现详细稿/dds-gemini.md create mode 100644 18-基础架构及交付部署特战队/1-项目部署-管理/2-修改需求.md create mode 100644 18-基础架构及交付部署特战队/1-项目部署-管理/claude-dds.md create mode 100644 18-基础架构及交付部署特战队/1-项目部署-管理/docs/AirScript-文档.md create mode 100644 18-基础架构及交付部署特战队/1-项目部署-管理/docs/python脚本使用指南.md create mode 100644 18-基础架构及交付部署特战队/1-项目部署-管理/gemini-dds.md create mode 100644 18-基础架构及交付部署特战队/1-项目部署-管理/scripts/airscript-auto-create-deploy-records.js create mode 100644 18-基础架构及交付部署特战队/1-项目部署-管理/scripts/airscript-button-create-deploy-records.js create mode 100644 18-基础架构及交付部署特战队/1-项目部署-管理/scripts/airscript-create-tables.js create mode 100644 18-基础架构及交付部署特战队/1-项目部署-管理/scripts/airscript-deploy-type-check.js create mode 100644 18-基础架构及交付部署特战队/1-项目部署-管理/scripts/airscript-export-schema.js create mode 100644 18-基础架构及交付部署特战队/1-项目部署-管理/scripts/airscript-fix-link-field.js create mode 100644 18-基础架构及交付部署特战队/1-项目部署-管理/scripts/api-client.js create mode 100644 18-基础架构及交付部署特战队/1-项目部署-管理/scripts/config.js create mode 100644 18-基础架构及交付部署特战队/1-项目部署-管理/scripts/create-tables.js create mode 100644 18-基础架构及交付部署特战队/1-项目部署-管理/scripts/package.json create mode 100644 18-基础架构及交付部署特战队/1-项目部署-管理/scripts/table-definitions.js create mode 100644 18-基础架构及交付部署特战队/1-项目部署-管理/scripts/test-auth.js create mode 100644 18-基础架构及交付部署特战队/1-项目部署-管理/金山多维数据表格-PRD.md create mode 100644 18-基础架构及交付部署特战队/1-项目部署-管理/项目部署-台账-排期-管理.md create mode 100644 18-基础架构及交付部署特战队/2-对研发交接需求/快文-协作规范.md create mode 100644 18-基础架构及交付部署特战队/3-对行业组交接需求/工作流程说明.md create mode 100644 18-基础架构及交付部署特战队/3-对行业组交接需求/快文-协作规范.md create mode 100644 18-基础架构及交付部署特战队/5-2026年3月10日/2026年3月10日-暂停原因.md create mode 100644 18-基础架构及交付部署特战队/9-人员分工管理规范/1-工作量占比.md create mode 100644 18-基础架构及交付部署特战队/9-人员分工管理规范/1-工作量绘图-prompt.md create mode 100644 18-基础架构及交付部署特战队/9-人员分工管理规范/1.1-工作粗项.png create mode 100644 18-基础架构及交付部署特战队/9-人员分工管理规范/1.2-工作细项.png create mode 100644 18-基础架构及交付部署特战队/9-人员分工管理规范/2-工作优先级排期.md create mode 100644 18-基础架构及交付部署特战队/任务.md create mode 100644 19-CMII快文规范/中国移动快文prompt.md create mode 100644 19-CMII快文规范/快文prompt.md create mode 100644 99-项目模板/3-实现详细稿/1-DDS-to-Stitch转换.md create mode 100644 skills-lock.json diff --git a/1-AgentSkills/coding-go-gin-gorm/SKILL.md b/.agents/skills/backend-go-gin-gorm/SKILL.md similarity index 99% rename from 1-AgentSkills/coding-go-gin-gorm/SKILL.md rename to .agents/skills/backend-go-gin-gorm/SKILL.md index f551b5f..92ed04b 100644 --- a/1-AgentSkills/coding-go-gin-gorm/SKILL.md +++ b/.agents/skills/backend-go-gin-gorm/SKILL.md @@ -1,5 +1,5 @@ --- -name: developing-go-gin-gorm wdd-后端开发 +name: backend-go-gin-gorm description: > 使用 Gin + GORM 生成、编写、修改、评审 production-ready 的 Go 后端代码(Generate & Review Go backend code with Gin/GORM)。 diff --git a/1-AgentSkills/coding-go-gin-gorm/examples/dao-example.go b/.agents/skills/backend-go-gin-gorm/examples/dao-example.go similarity index 100% rename from 1-AgentSkills/coding-go-gin-gorm/examples/dao-example.go rename to .agents/skills/backend-go-gin-gorm/examples/dao-example.go diff --git a/1-AgentSkills/coding-go-gin-gorm/examples/handler-example.go b/.agents/skills/backend-go-gin-gorm/examples/handler-example.go similarity index 100% rename from 1-AgentSkills/coding-go-gin-gorm/examples/handler-example.go rename to .agents/skills/backend-go-gin-gorm/examples/handler-example.go diff --git a/1-AgentSkills/coding-go-gin-gorm/examples/service-example.go b/.agents/skills/backend-go-gin-gorm/examples/service-example.go similarity index 100% rename from 1-AgentSkills/coding-go-gin-gorm/examples/service-example.go rename to .agents/skills/backend-go-gin-gorm/examples/service-example.go diff --git a/1-AgentSkills/coding-go-gin-gorm/reference/api-design-spec.md b/.agents/skills/backend-go-gin-gorm/reference/api-design-spec.md similarity index 100% rename from 1-AgentSkills/coding-go-gin-gorm/reference/api-design-spec.md rename to .agents/skills/backend-go-gin-gorm/reference/api-design-spec.md diff --git a/1-AgentSkills/coding-go-gin-gorm/reference/api-response-spec.md b/.agents/skills/backend-go-gin-gorm/reference/api-response-spec.md similarity index 100% rename from 1-AgentSkills/coding-go-gin-gorm/reference/api-response-spec.md rename to .agents/skills/backend-go-gin-gorm/reference/api-response-spec.md diff --git a/1-AgentSkills/coding-go-gin-gorm/reference/coding-standards.md b/.agents/skills/backend-go-gin-gorm/reference/coding-standards.md similarity index 100% rename from 1-AgentSkills/coding-go-gin-gorm/reference/coding-standards.md rename to .agents/skills/backend-go-gin-gorm/reference/coding-standards.md diff --git a/1-AgentSkills/coding-go-gin-gorm/reference/error-codes.go b/.agents/skills/backend-go-gin-gorm/reference/error-codes.go similarity index 100% rename from 1-AgentSkills/coding-go-gin-gorm/reference/error-codes.go rename to .agents/skills/backend-go-gin-gorm/reference/error-codes.go diff --git a/1-AgentSkills/coding-go-gin-gorm/reference/framework-usage.md b/.agents/skills/backend-go-gin-gorm/reference/framework-usage.md similarity index 100% rename from 1-AgentSkills/coding-go-gin-gorm/reference/framework-usage.md rename to .agents/skills/backend-go-gin-gorm/reference/framework-usage.md diff --git a/1-AgentSkills/coding-go-gin-gorm/reference/logging-standards.md b/.agents/skills/backend-go-gin-gorm/reference/logging-standards.md similarity index 100% rename from 1-AgentSkills/coding-go-gin-gorm/reference/logging-standards.md rename to .agents/skills/backend-go-gin-gorm/reference/logging-standards.md diff --git a/1-AgentSkills/coding-go-gin-gorm/reference/project-structure.md b/.agents/skills/backend-go-gin-gorm/reference/project-structure.md similarity index 100% rename from 1-AgentSkills/coding-go-gin-gorm/reference/project-structure.md rename to .agents/skills/backend-go-gin-gorm/reference/project-structure.md diff --git a/1-AgentSkills/coding-go-gin-gorm/reference/time-handling.md b/.agents/skills/backend-go-gin-gorm/reference/time-handling.md similarity index 100% rename from 1-AgentSkills/coding-go-gin-gorm/reference/time-handling.md rename to .agents/skills/backend-go-gin-gorm/reference/time-handling.md diff --git a/1-AgentSkills/coding-go-gin-gorm/scripts/validate-structure.sh b/.agents/skills/backend-go-gin-gorm/scripts/validate-structure.sh similarity index 100% rename from 1-AgentSkills/coding-go-gin-gorm/scripts/validate-structure.sh rename to .agents/skills/backend-go-gin-gorm/scripts/validate-structure.sh diff --git a/.agents/skills/dds-to-skill/SKILL.md b/.agents/skills/dds-to-skill/SKILL.md new file mode 100644 index 0000000..00f3b64 --- /dev/null +++ b/.agents/skills/dds-to-skill/SKILL.md @@ -0,0 +1,391 @@ +--- +name: dds-to-skill +description: > + 将 DDS(详细设计说明书)/ PRD / 架构文档转换为一套可落地的 Claude Code Agent Skills(Converts DDS/PRD/Architecture docs into production-ready Agent Skills)。 + 包含系统级 Skill、模块级 Skills、横切 Skills 的完整生成流程,涵盖设计细节抽取、reference 分层、frontmatter 规范、质量自检。 + 触发场景 Trigger: 当用户需要将 DDS 文档转为 Skills / 需要从架构设计文档生成开发指导 Skill / 需要批量创建模块级 Skill 套件。 + 关键词 Keywords: DDS, PRD, 架构说明, 设计文档, skill 生成, skill 套件, agent skill, 模块拆分, reference 抽取, 契约, API, 状态机, 事件, Schema。 +argument-hint: " [--output-dir ] [--project-name ]" +allowed-tools: + - Read + - Write + - Edit + - Glob + - Grep + - Bash +--- + +# DDS-to-Skill:从设计文档生成 Agent Skills + +本 Skill 指导你将一份 DDS(Detailed Design Specification)或 PRD / 架构说明文档,转换为一套**可落地、含设计细节**的 Claude Code Agent Skills 套件。 + +> **核心理念**:生成的不是"空洞的工作流提示词",而是**绑定了 DDS 设计细节**、能指导真实开发/审查的 Skill 套件。 + +--- + +## Phase 0:读取与理解 DDS + +### 0.1 动态注入读取(必须执行) + +```bash +# 动态注入:查看源文档目录上下文 +!`ls -la $(dirname "$ARGUMENTS")` + +# 动态注入:读取 DDS 正文(至少 3 段,覆盖全文) +!`sed -n '1,150p' "$ARGUMENTS"` +!`sed -n '150,300p' "$ARGUMENTS"` +!`sed -n '300,500p' "$ARGUMENTS"` + +# 动态注入:抽取章节标题(构建 TOC) +!`grep -nE '^(#{1,6}\s+|[0-9]+(\.[0-9]+){0,3}\s+|第[一二三四五六七八九十]+章|第[0-9]+章)' "$ARGUMENTS" | head -n 80` +``` + +### 0.2 设计要素定向扫描(至少执行 3 项) + +```bash +# API/接口 +!`grep -nE "API|接口|路径|路由|request|response|错误码|error|handler" "$ARGUMENTS" | head -n 60` + +# 事件/消息/Topic +!`grep -nE "事件|event|MQTT|topic|outbox|消息|payload|幂等|retry|publish|subscribe" "$ARGUMENTS" | head -n 60` + +# 数据库/Schema +!`grep -nE "表|schema|字段|索引|unique|constraint|migration|DDL|PostgreSQL|MySQL|GORM" "$ARGUMENTS" | head -n 60` + +# 状态机/流程 +!`grep -nE "状态机|state|transition|流转|工单|workflow|回调|补偿|lifecycle" "$ARGUMENTS" | head -n 60` + +# 安全/授权 +!`grep -nE "RBAC|DAC|鉴权|JWT|claim|授权|TOTP|权限|auth|token|session" "$ARGUMENTS" | head -n 60` + +# 模块/服务/依赖 +!`grep -nE "模块|module|service|微服务|依赖|dependency|import|gateway" "$ARGUMENTS" | head -n 60` +``` + +### 0.3 无法读取时的降级 + +若无法读取文件,**必须停止**,输出"继续所需的最小信息清单": + +1. 系统模块列表(名称 + 职责 + 关键技术) +2. 每个模块的接口/API 列表 +3. 事件/Topic 定义 +4. 数据库表结构 +5. 状态机/流程定义 +6. 授权模型 +7. 模块间依赖关系 + +**禁止在缺少源文档的情况下臆造设计细节。** + +--- + +## Phase 1:分析与规划 + +### 1.1 模块识别 + +从 DDS 中识别所有业务模块,生成模块清单表: + +| 模块名 | 职责概述 | 关键技术 | Skill 类型 | +|--------|---------|---------|-----------| +| *从 DDS 抽取* | *从 DDS 抽取* | *从 DDS 抽取* | 系统级/模块级/横切 | + +### 1.2 Skill 三层架构规划 + +必须生成 3 类 Skills: + +**A) 系统级 Skill(1 个)** +- 跨模块一致性、依赖规则、全局变更流程 +- 命名:`developing--system` + +**B) 模块级 Skills(N 个,每模块 1 个)** +- 高频开发指导:实现步骤 + 依赖影响检查 +- 命名:`developing-` + +**C) 横切 Skills(≥ 3 个)** +- 基于 DDS 内容选择,常见横切关注点: + +| 横切主题 | 适用场景 | 参考命名 | +|---------|---------|---------| +| API/事件/Schema 契约 | 有跨模块接口定义 | `designing-contracts` | +| 数据库迁移 | 有 DB Schema 定义 | `managing-db-migrations` | +| 可观测性/审计 | 有日志/监控/审计需求 | `managing-observability` | +| 安全/认证 | 有 RBAC/JWT/授权体系 | `implementing-auth` | +| 前端开发规范 | 有前端架构设计 | `frontend-` | +| 后端编码规范 | 有后端技术栈规范 | `backend-` | +| 部署/运维 | 有 K8S/Docker/CI 设计 | `deploying-` | + +> 实际横切 Skills 必须根据 DDS 内容动态决定,不可少于 3 个。 + +### 1.3 Name 候选与确认 + +为每个 Skill 提供 2~3 个命名候选,从中选择 1 个并说明理由。命名规则: +- 动名词形式(如 `developing-*`、`managing-*`、`implementing-*`) +- 小写字母 + 数字 + 连字符 +- ≤ 64 字符 +- 包含模块名或领域名 + +--- + +## Phase 2:DDS 设计细节抽取 + +### 2.1 章节提取与 reference 目录构建 + +> **详细规则见** `reference/dds-extraction-guide.md` + +从 DDS 章节标题构建 `reference/` 分层目录: + +``` +/reference/ +├── 01-/ +│ ├── apis.md +│ ├── db-schema.md +│ └── events-topics.md +├── 02-/ +│ └── state-machine.md +└── 03-/ + └── security-model.md +``` + +**目录命名规范**: +- 有序前缀 `01-`、`02-`... + slug +- slug:全小写,非字母数字字符替换为 `-`,连续 `-` 合并,≤ 48 字符 + +### 2.2 六类设计要素抽取(必须覆盖) + +每个模块级 Skill 的 reference/ 必须覆盖**至少 3 类**: + +| 要素类型 | 抽取内容 | reference 文件名 | +|---------|---------|-----------------| +| **API/接口** | 路径、方法、请求/响应字段、错误码 | `apis.md` | +| **事件/Topic** | 字段、版本、幂等键、重试语义 | `events-topics.md` | +| **DB Schema** | 字段、索引、约束、迁移策略 | `db-schema.md` | +| **状态机/流程** | 状态、转移、守卫条件、回调、补偿 | `state-machine.md` | +| **授权模型** | JWT claims、RBAC/DAC、权限层级 | `security-model.md` | +| **依赖关系** | 跨模块调用链路、协议、集成点 | `dependencies.md` | + +### 2.3 reference 条目格式(强制) + +每条 reference 必须包含溯源信息: + +```markdown +## <设计要素名称> + +- **DDS-Section**: <章节标题原文> +- **DDS-Lines**: L120-L168(或近似行号) + +### Extract + +<结构化内容:表格/列表/代码块> +``` + +### 2.4 TBD 标注 + +如果 DDS 中某个设计要素写得不清楚或缺失: +- **必须标注 `[TBD]`** +- 输出"最小补充信息清单" +- **禁止脑补细节** + +--- + +## Phase 3:逐个生成 SKILL.md + +### 3.1 SKILL.md 结构模板 + +> **详细模板见** `reference/skill-templates.md` + +每个 SKILL.md 必须包含以下结构: + +```markdown +--- +name: +description: <单行,< 1024 字符,中英文混合,第三人称,含功能+触发场景+关键词> +argument-hint: "<参数格式说明>" +allowed-tools: + - Read + - Write # 按需 + - Edit # 按需 + - Glob + - Grep + - Bash # 按需 +--- + +# + +<一段话概述本 Skill 的用途和适用范围> + +## Quick Context +<动态注入命令,至少 2 处 !`command`> + +## Plan +### 产物清单 +### 决策点 + +## Verify +<按类别组织的 Checklist,可勾选> + +## Execute +<分步骤的可操作指令> + +## Pitfalls +<3~8 条与该模块/主题强相关的常见坑,至少 2 条引用 reference> + +## Related References +<指向 reference/ 的链接列表,说明何时查阅> +``` + +### 3.2 Frontmatter 编写规则 + +> **详细规范见** `reference/frontmatter-spec.md` + +**关键要点**: +- `description` **必须单行**,否则 skill 触发会失败 +- 必须中英文混合,确保中文和英文查询都能命中 +- 必须包含:功能说明 + 触发场景 + 关键词(含模块名) +- `allowed-tools` 遵循最小授权原则 + +### 3.3 内容编写原则 + +1. **删除常识**:只保留 DDS 特有设计与可操作步骤 +2. **解释 Why**:对重要约束解释原因,不要堆砌 MUST/ALWAYS +3. **可执行动作**:禁止空话(如"检查 API 兼容"),必须写成具体审查动作 +4. **设计细节绑定**:Pitfalls 和 Verify 中至少 2 处引用 `reference/` 的具体内容 +5. **行数限制**:SKILL.md 主体 < 500 行 + +**示例 — 空话 vs 可执行动作**: + +``` +❌ "检查事件一致性" +✅ "在 reference/events-topics.md 找到 topic 列表,对照仓库 grep 出 publish/subscribe 点" + +❌ "验证 JWT 安全" +✅ "校验 JWT claims 是否包含 tenant_id/project_id/role(来自 reference/security-model.md)" + +❌ "检查 migration 可回滚" +✅ "migration 必须包含 down SQL;verify.sh grep 检查 `-- +migrate Down` 或回滚段落存在" +``` + +--- + +## Phase 4:生成 Supporting Files + +### 4.1 目录结构 + +每个 Skill 遵循标准目录模板: + +``` +/ +├── SKILL.md # 主文件(< 500 行) +├── reference/ # 设计细节(按章节分层) +│ ├── 01-
/ +│ │ ├── apis.md +│ │ ├── db-schema.md +│ │ └── ... +│ └── 02-
/ +│ └── ... +├── examples/ # 骨架代码示例 +│ └── ... +└── scripts/ # 验证脚本 + └── verify.sh # 必须提供 +``` + +### 4.2 verify.sh 编写要求 + +每个 Skill 必须至少包含 1 个 `verify.sh`: + +```bash +#!/bin/bash +# verify.sh - Skill 结构与内容验证 +set -e + +PASS=0; FAIL=0 +check() { + if eval "$2"; then + echo "✅ PASS: $1"; ((PASS++)) + else + echo "❌ FAIL: $1"; ((FAIL++)) + fi +} + +SKILL_DIR="$(cd "$(dirname "$0")/.." && pwd)" + +# 结构检查 +check "SKILL.md 存在" "test -f '$SKILL_DIR/SKILL.md'" +check "reference/ 目录存在" "test -d '$SKILL_DIR/reference'" +check "SKILL.md < 500 行" "[ $(wc -l < '$SKILL_DIR/SKILL.md') -lt 500 ]" + +# 内容检查 +check "frontmatter 包含 name" "head -20 '$SKILL_DIR/SKILL.md' | grep -q '^name:'" +check "frontmatter 包含 description" "head -20 '$SKILL_DIR/SKILL.md' | grep -q '^description:'" +check "包含 Plan 章节" "grep -q '## Plan' '$SKILL_DIR/SKILL.md'" +check "包含 Verify 章节" "grep -q '## Verify' '$SKILL_DIR/SKILL.md'" +check "包含 Execute 章节" "grep -q '## Execute' '$SKILL_DIR/SKILL.md'" +check "包含 Pitfalls 章节" "grep -q '## Pitfalls' '$SKILL_DIR/SKILL.md'" + +# reference 检查 +check "reference 有章节子目录" "find '$SKILL_DIR/reference' -maxdepth 1 -type d -name '0*' | grep -q ." +check "reference 文件含 DDS-Section" "grep -rq 'DDS-Section:' '$SKILL_DIR/reference/' 2>/dev/null" + +echo "" +echo "=== 结果: $PASS PASS / $FAIL FAIL ===" +[ $FAIL -eq 0 ] && exit 0 || exit 1 +``` + +### 4.3 examples/ 编写要求 + +- 只放**骨架与关键接口签名**,不放完整实现 +- 与模块职责强相关 +- 注释说明关键设计决策 + +--- + +## Phase 5:全局自检 + +### 5.1 输出顺序(必须遵守) + +1. **Skills 清单表**:系统级 / 模块级 / 横切,含最终 name 与理由 +2. **总目录树**:Unix 路径风格 +3. **每个 SKILL.md**:完整内容 +4. **Supporting files**:按 `文件路径 → 文件内容` 逐个输出 +5. **全局自检结果**:逐条 PASS/FAIL + 修复建议 + +### 5.2 自检 Checklist + +按以下维度逐条检查: + +**结构完整性** +- [ ] 系统级 Skill 存在(1 个) +- [ ] 模块级 Skills 数量 = 模块数 +- [ ] 横切 Skills ≥ 3 个 +- [ ] 每个 Skill 都有 SKILL.md + reference/ + scripts/verify.sh + +**Frontmatter 规范** +- [ ] description 为单行 +- [ ] description < 1024 字符 +- [ ] 中英文混合 +- [ ] 包含触发场景和关键词 +- [ ] allowed-tools 最小授权 + +**内容质量** +- [ ] SKILL.md < 500 行 +- [ ] 包含 Plan/Verify/Execute/Pitfalls 四个章节 +- [ ] ≥ 2 处 `!command` 动态注入 +- [ ] Pitfalls ≥ 2 条引用 reference +- [ ] 无空话("检查 XX 一致性"这类无具体动作的描述) + +**Reference 质量** +- [ ] 每个模块 Skill 覆盖 ≥ 3 类设计要素 +- [ ] reference 有章节分层目录(非扁平) +- [ ] 每条 reference 含 DDS-Section + DDS-Lines 溯源 +- [ ] DDS 缺失内容标注 [TBD] +- [ ] 无脑补设计细节 + +--- + +## Quick Reference + +| 需要了解... | 查阅... | +|------------|--------| +| DDS 抽取的详细方法 | `reference/dds-extraction-guide.md` | +| SKILL.md 模板(系统/模块/横切) | `reference/skill-templates.md` | +| Frontmatter 详细规范 | `reference/frontmatter-spec.md` | +| 质量自检的完整清单 | `reference/quality-checklist.md` | +| 成功案例的目录结构 | `examples/` | diff --git a/.agents/skills/dds-to-skill/examples/conversion-example-multi-module.md b/.agents/skills/dds-to-skill/examples/conversion-example-multi-module.md new file mode 100644 index 0000000..9d8e4b5 --- /dev/null +++ b/.agents/skills/dds-to-skill/examples/conversion-example-multi-module.md @@ -0,0 +1,137 @@ +# DDS-to-Skill 转换实例:完整系统(多模块) + +本文展示将一个包含多模块的 DDS 文档转换为完整 Skill 套件的过程。 + +--- + +## 1. 系统概述(模拟 DDS) + +``` +系统名称:ProjectMoneyX(个人财务管理系统) +技术栈:Go + Gin + GORM / Vue3 + TypeScript + Vuetify3 +模块列表: + - 账单导入模块(bill-import) + - 多维分析模块(analysis) + - 预算管理模块(budget) + - 账户管理模块(account) + - 规则引擎模块(rules) +``` + +--- + +## 2. Skill 套件规划 + +### 2.1 Skills 清单 + +| 类型 | Skill Name | 职责 | +|------|-----------|------| +| 系统级 | `developing-moneyx-system` | 跨模块架构、技术栈规范、依赖管理 | +| 模块级 | `developing-bill-import` | 账单导入 ETL 流水线 | +| 模块级 | `developing-analysis` | 多维财务分析与图表 | +| 模块级 | `developing-budget` | 预算创建与跟踪 | +| 模块级 | `developing-account` | 账户 CRUD 与余额同步 | +| 模块级 | `developing-rules` | 分类规则引擎 | +| 横切 | `designing-contracts` | API/DTO 契约规范 | +| 横切 | `managing-db-migrations` | 数据库迁移策略 | +| 横切 | `managing-observability` | 日志、错误追踪 | + +### 2.2 总目录树 + +``` +1-AgentSkills/ +├── developing-moneyx-system/ +│ ├── SKILL.md +│ ├── reference/ +│ │ ├── 01-architecture/ +│ │ │ └── dependencies.md +│ │ └── 02-tech-stack/ +│ │ └── conventions.md +│ └── scripts/ +│ └── verify.sh +├── developing-bill-import/ +│ ├── SKILL.md +│ ├── reference/ +│ │ ├── 01-etl-pipeline/ +│ │ │ └── pipeline-design.md +│ │ ├── 02-api-design/ +│ │ │ └── apis.md +│ │ └── 03-data-model/ +│ │ └── db-schema.md +│ ├── examples/ +│ │ └── etl-processor.go +│ └── scripts/ +│ └── verify.sh +├── developing-analysis/ +│ ├── ...(同上结构) +├── developing-budget/ +│ ├── ... +├── developing-account/ +│ ├── ... +├── developing-rules/ +│ ├── ... +├── designing-contracts/ +│ ├── SKILL.md +│ ├── reference/ +│ │ └── api-response-spec.md +│ └── scripts/ +│ └── verify.sh +├── managing-db-migrations/ +│ ├── SKILL.md +│ ├── reference/ +│ │ └── migration-conventions.md +│ └── scripts/ +│ └── verify.sh +└── managing-observability/ + ├── SKILL.md + ├── reference/ + │ └── logging-standards.md + └── scripts/ + └── verify.sh +``` + +--- + +## 3. 关键转换决策 + +### 3.1 模块边界划分 + +> **决策依据**:DDS 中每个"章节"对应一个业务域,每个业务域生成一个模块级 Skill。 + +### 3.2 横切关注点识别 + +从 DDS 全文 grep 识别跨模块使用的技术点: + +```bash +# 发现所有模块都用了统一响应格式 → designing-contracts +grep -c "ResponseError\|ResponseSuccess" *.go + +# 发现多个模块有 migration 文件 → managing-db-migrations +find . -name "*migration*" -o -name "*migrate*" + +# 发现多个模块有日志调用 → managing-observability +grep -rn "log\.\(Info\|Error\|Debug\)" --include="*.go" | wc -l +``` + +### 3.3 Reference 深度决策 + +| 要素 | 模块 | DDS 覆盖度 | reference 策略 | +|------|------|-----------|---------------| +| API | bill-import | 完整 | 全量抽取到 apis.md | +| DB Schema | budget | 部分 | 抽取已有 + [TBD] 标注缺失 | +| 事件 | analysis | 无 | 跳过,无需创建事件 reference | +| 状态机 | bill-import | 完整 | ETL 状态流转到 state-machine.md | + +--- + +## 4. 输出示例:系统级 Skill + +```yaml +--- +name: developing-moneyx-system +description: > + 指导 ProjectMoneyX 个人财务管理系统的全局架构决策与跨模块一致性(Guides system-level architecture for ProjectMoneyX personal finance system)。 + 包含:模块注册、技术栈规范、依赖管理、响应格式统一。 + 触发场景 Trigger: 新增模块 / 跨模块变更 / 架构决策 / 技术栈选型。 + 关键词 Keywords: moneyx, system, architecture, 架构, 财务, finance, 模块, cross-module。 +--- +``` diff --git a/.agents/skills/dds-to-skill/examples/conversion-example-workflow.md b/.agents/skills/dds-to-skill/examples/conversion-example-workflow.md new file mode 100644 index 0000000..5613c21 --- /dev/null +++ b/.agents/skills/dds-to-skill/examples/conversion-example-workflow.md @@ -0,0 +1,95 @@ +# DDS-to-Skill 转换实例:工单流程模块 + +本文展示了一个从 DDS 片段到完整 Skill 的转换过程。 + +--- + +## 1. DDS 原文片段(模拟) + +```markdown +## 5. 工单管理模块(rmdc-work-procedure) + +### 5.1 模块职责 +负责工单生命周期管理,包括创建、审批、执行、完成等流转。 + +### 5.2 数据库设计 + +#### workflows 主表 +| 字段 | 类型 | 约束 | 说明 | +|------|------|------|------| +| id | BIGINT | PK, AUTO_INCREMENT | 工单ID | +| type | VARCHAR(50) | NOT NULL | 工单类型 | +| status | VARCHAR(30) | NOT NULL, DEFAULT 'pending' | 当前状态 | +| creator_id | BIGINT | NOT NULL, FK → users.id | 创建人 | +| assignee_id | BIGINT | FK → users.id | 处理人 | +| version | INT | NOT NULL, DEFAULT 1 | 乐观锁版本号 | + +### 5.3 状态机 +- pending → submitted → under_review → approved/rejected +- submitted → revoked(创建人可撤销) +- 终态:approved, rejected, revoked, closed + +### 5.4 API 接口 +- POST /api/workflow/create - 创建工单 +- POST /api/workflow/transition - 状态转换 +- POST /api/workflow/callback - 业务回调 +- POST /api/workflow/list - 工单列表 +``` + +--- + +## 2. 转换步骤演示 + +### 步骤 1:模块识别 + +| 模块 | 职责 | 技术 | Skill 类型 | +|------|------|------|-----------| +| rmdc-work-procedure | 工单生命周期管理 | Go + Gin + PostgreSQL | 模块级 | + +### 步骤 2:设计要素抽取 + +从 DDS 中识别到 4 类要素: +- ✅ API/接口 → 4 个 API 端点 +- ✅ DB Schema → workflows 主表 +- ✅ 状态机 → 5 个状态 + 转换规则 +- ❌ 事件/Topic → DDS 未提及 → 标注 [TBD] +- ❌ 授权模型 → DDS 未提及 → 标注 [TBD] +- ✅ 依赖关系 → 业务模块回调 + +### 步骤 3:reference 文件生成 + +``` +reference/ +├── 01-data-model/ +│ └── db-schema.md # workflows 表结构 +├── 02-api-design/ +│ └── apis.md # 4 个 API 定义 +├── 03-workflow-engine/ +│ └── state-machine.md # 状态机定义 +└── 04-integration/ + └── dependencies.md # 回调接口 +``` + +### 步骤 4:SKILL.md 关键段落 + +```markdown +## Pitfalls + +1. **版本号遗漏**: 更新工单时忘记传递 `version` 字段,导致乐观锁失效 + (参考 `reference/01-data-model/db-schema.md` 中 workflows.version 字段定义) +2. **终态误转换**: 对 approved/rejected/revoked/closed 状态尝试非法转换 + (参考 `reference/03-workflow-engine/state-machine.md` 中的终态定义) +3. **事件推送遗漏**: 状态变更后忘记通知相关方 [TBD - DDS 未定义事件机制] +``` + +--- + +## 3. 自检结果 + +| # | 检查项 | 结果 | 说明 | +|---|-------|------|------| +| S4 | SKILL.md 存在 | ✅ PASS | | +| R1 | 设计要素 ≥ 3 类 | ✅ PASS | API + DB + 状态机 + 依赖 = 4 类 | +| R5 | TBD 标注 | ✅ PASS | 事件和授权标注了 [TBD] | +| C7 | Pitfalls 引用 reference | ✅ PASS | 2 条引用了 reference 路径 | +| R6 | 无脑补 | ✅ PASS | 缺失内容均标注 [TBD] | diff --git a/.agents/skills/dds-to-skill/reference/dds-extraction-guide.md b/.agents/skills/dds-to-skill/reference/dds-extraction-guide.md new file mode 100644 index 0000000..a6ddb83 --- /dev/null +++ b/.agents/skills/dds-to-skill/reference/dds-extraction-guide.md @@ -0,0 +1,260 @@ +# DDS 设计细节抽取指南 + +本文档详细说明如何从 DDS(详细设计说明书)中抽取设计细节,并组织到 reference/ 目录中。 + +--- + +## 1. 章节标题提取 + +### 1.1 标题识别规则(按优先级) + +| 优先级 | 格式 | 示例 | +|-------|------|------| +| 1 | Markdown 标题 | `# 系统架构`、`## 接口设计` | +| 2 | 编号标题 | `1 概述`、`2.3 数据库设计` | +| 3 | 中文章标题 | `第一章 总体设计`、`第3章` | +| 4 | 中文小节 | `一、系统概述`、`(二)接口规范` | + +### 1.2 提取命令 + +```bash +# 综合提取(推荐首选) +grep -nE '^(#{1,6}\s+|[0-9]+(\.[0-9]+){0,3}\s+|第[一二三四五六七八九十]+章|第[0-9]+章|[一二三四五六七八九十]+、)' "$DDS_FILE" | head -n 120 + +# 如果上面匹配不足,尝试更宽松的模式 +sed -n '1,200p' "$DDS_FILE" | nl -ba | sed -n '1,120p' +``` + +### 1.3 降级策略 + +当标题提取不足(少于 3 个)或 DDS 格式混乱时: + +``` +reference/00-unknown/ +├── 01-apis/ +├── 02-events/ +├── 03-db/ +├── 04-state-machine/ +└── 05-security/ +``` + +同时在自检中标记 FAIL: +- **原因**:DDS 标题结构不可识别 +- **建议**:提供 Markdown 标题 / 章节目录 / md 格式导出版本 + +--- + +## 2. 六类设计要素抽取方法 + +### 2.1 API/接口 + +**扫描关键词**: +```bash +grep -nE "API|接口|路径|路由|request|response|错误码|error|handler|endpoint|method" "$DDS_FILE" | head -n 80 +``` + +**抽取内容**: +| 字段 | 说明 | +|------|------| +| 路径 | `/api/v1/users/list` | +| 方法 | POST / GET 等 | +| 请求字段 | 字段名、类型、是否必须、校验规则 | +| 响应字段 | 字段名、类型、说明 | +| 错误码 | code + message + 触发场景 | +| 鉴权要求 | JWT / API Key / 公开 | + +**输出格式**: +```markdown +## POST /api/v1/users/list + +- **DDS-Section**: 3.2 用户管理接口 +- **DDS-Lines**: L120-L168 + +### Request + +| 字段 | 类型 | 必须 | 说明 | +|------|------|------|------| +| page | int | N | 页码,默认 1 | +| page_size | int | N | 每页数量,默认 20 | + +### Response + +| 字段 | 类型 | 说明 | +|------|------|------| +| list | []User | 用户列表 | +| total | int | 总数 | + +### 错误码 + +| code | message | 触发场景 | +|------|---------|---------| +| 1001 | 参数校验失败 | 字段格式错误 | +``` + +### 2.2 事件/Topic/消息 + +**扫描关键词**: +```bash +grep -nE "事件|event|MQTT|topic|outbox|消息|payload|幂等|retry|publish|subscribe|Kafka|RabbitMQ" "$DDS_FILE" | head -n 80 +``` + +**抽取内容**: +| 字段 | 说明 | +|------|------| +| Topic/Queue 名 | `cmii/rmdc/{project_id}/command` | +| 方向 | Publish / Subscribe | +| Payload 字段 | 字段名、类型、说明 | +| QoS / 可靠性 | At-least-once / Exactly-once | +| 幂等键 | 用于去重的唯一标识字段 | +| 重试策略 | 重试间隔、最大次数、死信队列 | + +### 2.3 数据库/Schema + +**扫描关键词**: +```bash +grep -nE "表|schema|字段|索引|unique|constraint|migration|DDL|PostgreSQL|MySQL|GORM|column|CREATE TABLE" "$DDS_FILE" | head -n 80 +``` + +**抽取内容**: +| 字段 | 说明 | +|------|------| +| 表名 | `users`、`workflows` | +| 字段定义 | 名称、类型、约束、默认值 | +| 索引 | 类型(唯一/普通/组合)、字段 | +| 外键关系 | 引用表、级联策略 | +| 迁移策略 | 向前兼容 / 字段演进方案 | + +### 2.4 状态机/流程 + +**扫描关键词**: +```bash +grep -nE "状态机|state|transition|流转|工单|workflow|回调|补偿|lifecycle|FSM|guard" "$DDS_FILE" | head -n 80 +``` + +**抽取内容**: +| 字段 | 说明 | +|------|------| +| 状态枚举 | 名称、值、描述 | +| 转换规则 | from → to、触发动作、守卫条件 | +| 角色权限 | 谁可以触发哪些转换 | +| 回调/副作用 | 状态变更后执行的操作 | +| 补偿机制 | 转换失败时的回滚策略 | + +### 2.5 授权模型 + +**扫描关键词**: +```bash +grep -nE "RBAC|DAC|鉴权|JWT|claim|授权|TOTP|权限|auth|token|session|role|permission" "$DDS_FILE" | head -n 80 +``` + +**抽取内容**: +| 字段 | 说明 | +|------|------| +| 认证方式 | JWT / Session / OAuth | +| JWT Claims | 包含的字段(tenant_id, role 等) | +| 角色定义 | 角色名、权限描述 | +| 权限矩阵 | 角色 × 资源 × 操作 | +| 层级设计 | 一级授权 / 二级授权 | + +### 2.6 依赖关系 + +**扫描关键词**: +```bash +grep -nE "模块|module|service|依赖|dependency|import|gateway|调用|集成|protocol" "$DDS_FILE" | head -n 80 +``` + +**抽取内容**: +| 字段 | 说明 | +|------|------| +| 源模块 | 调用方 | +| 目标模块 | 被调用方 | +| 协议 | HTTP / gRPC / MQTT / 内部调用 | +| 关键接口 | 跨模块调用的接口清单 | +| 失败处理 | 超时、重试、熔断策略 | + +--- + +## 3. reference 目录组织 + +### 3.1 命名规范 + +``` +reference/ +├── 01-architecture-overview/ # 章节序号 + slug +│ └── dependencies.md +├── 02-api-design/ +│ ├── apis.md +│ └── error-codes.md +├── 03-data-model/ +│ └── db-schema.md +├── 04-message-system/ +│ └── events-topics.md +├── 05-workflow-engine/ +│ └── state-machine.md +└── 06-security/ + └── security-model.md +``` + +**Slug 生成规则**: +1. 全小写 +2. 非字母数字字符替换为 `-` +3. 连续 `-` 合并为单个 +4. 截断到 48 字符以内 +5. 序号来自 DDS 中的章节顺序 + +### 3.2 SKILL.md 中的引用方式 + +```markdown +## Pitfalls + +1. **MQTT Topic 命名冲突**:新增 topic 前必须检查 + `reference/04-message-system/events-topics.md` 中的 topic 清单 + +## Related References + +| 需要了解... | 查阅... | +|------------|--------| +| API 完整定义 | `reference/02-api-design/apis.md` | +| 数据库表结构 | `reference/03-data-model/db-schema.md` | +``` + +### 3.3 扁平化兼容 + +当 DDS 章节结构不明显时,也可以采用扁平 reference,但需在自检中说明: + +``` +reference/ +├── apis.md +├── db-schema.md +├── events-topics.md +├── state-machine.md +├── security-model.md +└── dependencies.md +``` + +--- + +## 4. TBD 标注规范 + +当 DDS 中某个设计要素不完整或不清晰时: + +```markdown +## 消息重试策略 + +- **DDS-Section**: 4.3 消息可靠性 +- **DDS-Lines**: L245-L260 + +### Extract + +| 配置项 | 值 | +|-------|---| +| 最大重试次数 | [TBD - DDS 未明确指定] | +| 重试间隔 | [TBD - DDS 未明确指定] | +| 死信队列 | [TBD - DDS 仅提及概念,未给出配置] | + +### 最小补充信息清单 + +1. 重试次数上限(建议 3~5 次) +2. 重试间隔策略(固定 / 指数退避) +3. 死信队列名称与消费策略 +``` diff --git a/.agents/skills/dds-to-skill/reference/frontmatter-spec.md b/.agents/skills/dds-to-skill/reference/frontmatter-spec.md new file mode 100644 index 0000000..c8862df --- /dev/null +++ b/.agents/skills/dds-to-skill/reference/frontmatter-spec.md @@ -0,0 +1,162 @@ +# Frontmatter 编写规范 + +Frontmatter 是 Skill 的"身份证",决定了 Skill 何时被触发、是否被正确识别。编写不当会导致 Skill 永远不会被使用。 + +--- + +## 1. 必须字段 + +### 1.1 name + +**规则**: +- 小写字母 + 数字 + 连字符(`-`) +- 动名词形式开头(`developing-`、`managing-`、`implementing-`、`designing-`) +- ≤ 64 字符 +- 包含模块名或领域名 + +**常用前缀**: +| 前缀 | 适用场景 | +|------|---------| +| `developing-` | 模块开发、功能实现 | +| `managing-` | 管理类操作(DB、配置、部署) | +| `implementing-` | 特定技术方案实现 | +| `designing-` | 设计阶段的规范和契约 | +| `writing-` | 编写文档、脚本、测试 | + +**示例**: +```yaml +# ✅ 正确 +name: developing-work-procedure +name: managing-db-migrations +name: implementing-totp-auth + +# ❌ 错误 +name: WorkProcedure # 不能大写 +name: work_procedure # 不能用下划线 +name: wp # 太短,无法触发 +``` + +### 1.2 description + +**这是最关键的字段** —— 决定 Skill 是否能被正确触发。 + +**硬性规则**: +1. **必须单行**(不换行) —— 换行会导致 YAML 解析出错,Skill 静默失败 +2. **< 1024 字符** +3. **第三人称**描述 +4. **中英文混合** —— 确保中文和英文查询都能命中 +5. **包含触发场景**(Trigger)和**关键词**(Keywords) + +**结构模板**: +``` +<功能概述(中英文)>。包含:<具体能力列表>。触发场景 Trigger: <场景列表>。关键词 Keywords: <关键词列表>。 +``` + +**示例**: +```yaml +# ✅ 正确(单行,中英文混合,包含触发场景和关键词) +description: 指导 rmdc-work-procedure 工单流程模块的开发(Guides development of rmdc-work-procedure workflow module)。包含:状态机实现、工单 CRUD、并发控制、WebSocket 事件。触发场景 Trigger: 修改工单表 / 添加工单类型 / 变更状态转换 / 实现工单 API。关键词 Keywords: workflow, work-procedure, state-machine, 工单, 状态机, 流转。 + +# ❌ 错误 - 多行(会静默失败!) +description: | + 指导工单模块开发。 + 包含状态机实现。 + +# ❌ 错误 - 太短,无关键词 +description: 工单模块开发指导 + +# ❌ 错误 - 纯英文,中文查询无法命中 +description: Guides the development of workflow module with state machine +``` + +**推动触发的技巧**: +- Claude 有"不触发"的倾向,所以 description 应该稍微"激进"一些 +- 多列出触发场景,覆盖用户可能的表述方式 +- 包含同义词(如:工单/workflow/ticket) + +### 1.3 argument-hint + +**规则**: +- 说明 `$ARGUMENTS` 的期望格式 +- 给出 2~3 个具体示例 + +**示例**: +```yaml +argument-hint: " - e.g., 'create handler user', 'add api /workflow/create', 'update schema workflows'" +``` + +--- + +## 2. 可选字段 + +### 2.1 allowed-tools + +**原则**:最小授权 —— 只声明 Skill 真正需要的工具。 + +| 工具 | 适用场景 | +|------|---------| +| `Read` | 读取文件(几乎总是需要) | +| `Glob` | 搜索文件(几乎总是需要) | +| `Grep` | 搜索文件内容(几乎总是需要) | +| `Bash` | 执行 shell 命令(按需) | +| `Write` | 创建新文件(开发类 Skill 需要) | +| `Edit` | 编辑现有文件(开发类 Skill 需要) | + +**示例**: +```yaml +# 只读 Skill(审查/分析类) +allowed-tools: + - Read + - Glob + - Grep + +# 开发 Skill(需要写文件) +allowed-tools: + - Read + - Write + - Edit + - Glob + - Grep + - Bash +``` + +--- + +## 3. YAML 格式注意事项 + +### 3.1 多行 description 的安全写法 + +如果 description 确实很长,使用 `>` 折叠块语法(注意:这仍然会被解析为单行): + +```yaml +description: > + 指导 rmdc-work-procedure 工单流程模块的开发。 + 包含状态机实现、工单 CRUD、并发控制。 + 触发场景 Trigger: 修改工单表、添加工单类型。 +``` + +> ⚠️ 使用 `>` 时,YAML 会将换行替换为空格,最终合并为单行。这是安全的。 +> ❌ 绝不要使用 `|`(保留换行块语法),那会导致多行 description。 + +### 3.2 特殊字符转义 + +```yaml +# 包含冒号时用引号包裹 +argument-hint: ": " + +# 包含 # 时用引号 +description: "指导 C# 项目开发" +``` + +--- + +## 4. 自检清单 + +- [ ] `name` 为动名词形式、小写连字符、≤ 64 字符 +- [ ] `description` 在最终 YAML 中为单行 +- [ ] `description` < 1024 字符 +- [ ] `description` 包含中文和英文 +- [ ] `description` 包含触发场景(Trigger) +- [ ] `description` 包含关键词(Keywords) +- [ ] `argument-hint` 有具体示例 +- [ ] `allowed-tools` 遵循最小授权 diff --git a/.agents/skills/dds-to-skill/reference/quality-checklist.md b/.agents/skills/dds-to-skill/reference/quality-checklist.md new file mode 100644 index 0000000..c86da72 --- /dev/null +++ b/.agents/skills/dds-to-skill/reference/quality-checklist.md @@ -0,0 +1,114 @@ +# 全局质量自检清单 + +DDS-to-Skill 转换完成后,必须按以下清单逐条检查。每条标记 PASS 或 FAIL,FAIL 必须附修复建议。 + +--- + +## 1. 结构完整性 + +| # | 检查项 | PASS 条件 | +|---|-------|----------| +| S1 | 系统级 Skill 存在 | 恰好 1 个 `developing-*-system` Skill | +| S2 | 模块级 Skills 数量 | = DDS 中识别的模块数 | +| S3 | 横切 Skills 数量 | ≥ 3 个 | +| S4 | 每个 Skill 有 SKILL.md | 所有 Skill 目录下存在 SKILL.md | +| S5 | 每个 Skill 有 reference/ | 所有 Skill 目录下存在 reference/ | +| S6 | 每个 Skill 有 verify.sh | 所有 Skill 的 scripts/ 下存在 verify.sh | +| S7 | 目录命名规范 | 全小写、连字符、动名词形式 | + +--- + +## 2. Frontmatter 规范 + +| # | 检查项 | PASS 条件 | +|---|-------|----------| +| F1 | description 单行 | YAML 解析后 description 为单行字符串 | +| F2 | description 长度 | < 1024 字符 | +| F3 | description 中英文 | 同时包含中文和英文描述 | +| F4 | description 含触发场景 | 包含 "触发场景" 或 "Trigger" 关键词 | +| F5 | description 含关键词 | 包含 "关键词" 或 "Keywords" | +| F6 | name 格式 | 小写字母 + 数字 + 连字符,动名词开头 | +| F7 | argument-hint 存在 | frontmatter 中包含 argument-hint 字段 | +| F8 | allowed-tools 最小授权 | 只读 Skill 不包含 Write/Edit | + +--- + +## 3. 内容质量 + +| # | 检查项 | PASS 条件 | +|---|-------|----------| +| C1 | SKILL.md 行数 | < 500 行 | +| C2 | 包含 Plan 章节 | grep 到 `## Plan` | +| C3 | 包含 Verify 章节 | grep 到 `## Verify` | +| C4 | 包含 Execute 章节 | grep 到 `## Execute` | +| C5 | 包含 Pitfalls 章节 | grep 到 `## Pitfalls` | +| C6 | 动态注入 | ≥ 2 处 `!` + 反引号命令 | +| C7 | Pitfalls 引用 reference | ≥ 2 条 Pitfall 中出现 `reference/` 路径 | +| C8 | 无空话 | 不含"检查 XX 一致性"这类无具体动作的描述 | +| C9 | 无常识内容 | 不含 Claude 已知的通用知识(如 HTTP 状态码定义) | +| C10 | 术语一致 | 同一概念在所有 Skill 中使用相同术语 | + +--- + +## 4. Reference 质量 + +| # | 检查项 | PASS 条件 | +|---|-------|----------| +| R1 | 设计要素覆盖率 | 每个模块 Skill 覆盖 ≥ 3 类(API/事件/DB/状态机/权限/依赖) | +| R2 | 章节分层 | reference/ 下存在 `01-*` 等编号目录(或使用扁平+说明) | +| R3 | DDS 溯源 | 每条 reference 含 `DDS-Section:` 字段 | +| R4 | DDS 行号 | 每条 reference 含 `DDS-Lines:` 字段 | +| R5 | TBD 标注 | DDS 缺失内容标注 `[TBD]`,附最小补充清单 | +| R6 | 无脑补 | 所有设计细节可溯源到 DDS 原文 | +| R7 | 内容充分 | reference 包含足够的结构化数据(表格/列表/代码块) | + +--- + +## 5. 跨 Skill 一致性 + +| # | 检查项 | PASS 条件 | +|---|-------|----------| +| X1 | 模块名一致 | 所有 Skill 中模块名拼写相同 | +| X2 | 错误码不冲突 | 相同错误码在不同 Skill 中含义相同 | +| X3 | API 路径不冲突 | 不同模块的 API 路径无重叠 | +| X4 | 事件/Topic 定义一致 | 同一 Topic 在发布方和订阅方 Skill 中定义相同 | +| X5 | 授权模型一致 | JWT Claims、角色定义在所有 Skill 中一致 | + +--- + +## 6. 自检输出格式 + +```markdown +# 全局自检结果 + +## 结构完整性 +- ✅ S1 PASS: 系统级 Skill `developing-xxx-system` 存在 +- ✅ S2 PASS: 模块级 Skills 数量 = 5(匹配 DDS 中的 5 个模块) +- ❌ S3 FAIL: 横切 Skills 仅 2 个,少于要求的 3 个 + - **修复**: 从 DDS 中识别出缓存策略章节,建议增加 `managing-cache` Skill +- ✅ S4 PASS: 所有 Skill 目录下存在 SKILL.md + +## Frontmatter 规范 +- ✅ F1 PASS: 所有 description 为单行 +- ❌ F2 FAIL: `developing-core` 的 description 超过 1024 字符(1156 字符) + - **修复**: 精简触发场景描述,移除重复关键词 + +## 内容质量 +- ✅ C1 PASS: 所有 SKILL.md < 500 行 +- ❌ C8 FAIL: `developing-gateway` 中 Verify 包含"检查 API 一致性" + - **修复**: 改为"对照 reference/02-api-design/apis.md 中的接口清单,grep 仓库中的 handler 注册点,确认路径和方法一致" + +## 总计: XX PASS / YY FAIL +``` + +--- + +## 7. 常见 FAIL 及修复方案 + +| FAIL 类型 | 常见原因 | 修复方案 | +|----------|---------|---------| +| description 多行 | 使用了 `\|` 语法 | 改用 `>` 或单行字符串 | +| reference 不足 | DDS 内容被遗漏 | 重新扫描 DDS,补充缺失要素 | +| 空话 | 直接复制 DDS 原文 | 转化为可执行的审查动作 | +| 脑补 | DDS 未提及的细节 | 标注 [TBD] 并列出补充清单 | +| 横切不足 | 未充分分析 DDS | 从 DDS 中识别更多跨模块关注点 | diff --git a/.agents/skills/dds-to-skill/reference/skill-templates.md b/.agents/skills/dds-to-skill/reference/skill-templates.md new file mode 100644 index 0000000..772fcd6 --- /dev/null +++ b/.agents/skills/dds-to-skill/reference/skill-templates.md @@ -0,0 +1,255 @@ +# SKILL.md 模板库 + +本文档包含系统级 Skill、模块级 Skill、横切 Skill 的 SKILL.md 模板,供 DDS-to-Skill 转换时参照。 + +--- + +## 1. 系统级 Skill 模板 + +```markdown +--- +name: developing--system +description: > + 指导 <系统名> 系统级开发决策与跨模块一致性(Guides system-level development for )。 + 包含:架构总览、模块注册、依赖规则、全局变更流程、版本兼容策略、技术栈规范。 + 触发场景 Trigger: 新增模块 / 跨模块变更 / 全局架构决策 / 技术栈选型。 + 关键词 Keywords: , system, architecture, 架构, 模块, 依赖, 兼容, cross-module。 +argument-hint: " - 指定涉及的模块名或变更类型" +allowed-tools: + - Read + - Glob + - Grep + - Bash +--- + +# Developing System + +<一段话描述系统整体架构、技术栈、模块组成> + +## Quick Context + +```bash +# 动态注入:查看系统模块结构 +!`ls -la /` + +# 动态注入:搜索模块间依赖 +!`grep -rnE "import|module|service" / | head -30` +``` + +## Architecture Overview + + + +## Module Registry + +| 模块 | 职责 | 技术 | Skill | +|------|------|------|-------| +| ... | ... | ... | `developing-` | + +## Plan + +### 产物清单 +- [ ] 确定变更涉及的模块列表 +- [ ] 确认是否涉及跨模块通信 +- [ ] 确认是否涉及契约变更 +- [ ] 确认是否需要数据库迁移 + +### 决策点 +1. 变更是否影响多个模块? +2. 是否需要版本兼容处理? +3. 是否需要全局配置变更? + +## Verify + +- [ ] 模块间依赖无循环 +- [ ] 共享契约版本一致 +- [ ] 全局配置项完整 +- [ ] 技术栈版本对齐 + +## Execute + +### 添加新模块 +1. 在项目根目录创建模块目录... +2. 注册到路由/网关... +3. 更新模块依赖图... + +### 跨模块变更 +1. 列出所有受影响模块... +2. 按依赖顺序逐个修改... +3. 运行集成测试... + +## Pitfalls + +1. **循环依赖**: 模块间禁止直接 import,必须通过共享接口定义 +2. **版本不一致**: 修改共享结构需同步更新所有消费方 +3. ... + +## Related References + +- [模块依赖关系](reference/dependencies.md) +- [技术栈规范](reference/tech-stack.md) +``` + +--- + +## 2. 模块级 Skill 模板 + +```markdown +--- +name: developing- +description: > + 指导 模块的开发(Guides development of module)。 + 包含:<模块职责概述>、API 实现、数据库操作、状态管理、安全校验。 + 触发场景 Trigger: 开发/修改 相关功能 / <模块特定场景>。 + 关键词 Keywords: , <技术关键词>, <业务关键词>。 +argument-hint: " - e.g., 'create handler', 'add api', 'update schema'" +allowed-tools: + - Read + - Write + - Edit + - Glob + - Grep + - Bash +--- + +# Developing + +<一段话描述模块职责、技术栈、在系统中的位置> + +## Quick Context + +```bash +# 动态注入:查看模块结构 +!`find . -name "*.go" -path "*//*" | head -20` + +# 动态注入:查看现有接口 +!`grep -rn "func.*Handler\|func.*Service" .// | head -20` +``` + +## Plan + +### 产物清单 +- [ ] <根据 DDS 列出具体产物> + +### 决策点 +1. <从 DDS 抽取的关键决策> +2. ... + +## Verify + +### <验证类别 1> +- [ ] <具体检查项,引用 reference> + +### <验证类别 2> +- [ ] <具体检查项> + +## Execute + +### 1. <步骤标题> +```bash +# 具体操作命令 +``` + +### 2. <步骤标题> +```go +// 关键代码骨架 +``` + +## Pitfalls + +1. **<坑名>**: <描述>(参考 `reference/.md`) +2. ...(至少 3 条,至少 2 条引用 reference) + +## Related References + +- [API 定义](reference/01-
/apis.md) +- [数据库 Schema](reference/02-
/db-schema.md) +``` + +--- + +## 3. 横切 Skill 模板 + +```markdown +--- +name: +description: > + <横切关注点>的统一规范与实现指导(Guides across all modules)。 + 包含:<具体内容列表>。 + 触发场景 Trigger: <触发场景列表>。 + 关键词 Keywords: <关键词列表>。 +argument-hint: " - 指定要应用规范的模块或文件" +allowed-tools: + - Read + - Glob + - Grep + - Bash +--- + +# <横切 Skill 标题> + +<描述这个横切关注点在系统中的重要性和适用范围> + +## Quick Context + +```bash +# 动态注入 +!`<扫描所有模块中与该横切主题相关的文件>` +``` + +## Plan + +### 产物清单 +- [ ] <横切维度的产物> + +### 决策点 +1. <跨模块的统一决策> +2. ... + +## Verify + +- [ ] <跨模块一致性检查> +- [ ] <规范合规检查> +- [ ] ... + +## Execute + +### 全局规范 +<适用于所有模块的规则> + +### 模块适配 +<各模块的特殊处理> + +## Pitfalls + +1. **<跨模块一致性问题>**: <描述> +2. ... + +## Related References + +- [全局规范定义](reference/.md) +``` + +--- + +## 4. 模板使用注意事项 + +### 4.1 必须自定义的部分 + +- `<尖括号>` 中的所有占位符 +- Plan 的产物清单和决策点必须来自 DDS +- Verify 的检查项必须与模块设计细节对应 +- Pitfalls 必须与模块/主题强相关,不可用通用建议填充 + +### 4.2 禁止照搬模板 + +模板是结构参考,不是内容来源。以下行为将导致自检 FAIL: +- 产物清单中出现模板占位符 +- Pitfalls 与模块无关(如:在前端 Skill 中出现数据库 Pitfall) +- Verify 中没有引用任何 reference + +### 4.3 按 DDS 内容增减 + +- 如果 DDS 中没有状态机,模块 Skill 可以不包含状态机相关 Verify +- 如果 DDS 中有额外的关注点(如性能优化、缓存策略),应增加对应章节 +- 横切 Skill 的数量和主题必须由 DDS 内容决定 diff --git a/.agents/skills/dds-to-skill/scripts/verify-skill-output.sh b/.agents/skills/dds-to-skill/scripts/verify-skill-output.sh new file mode 100644 index 0000000..37d2935 --- /dev/null +++ b/.agents/skills/dds-to-skill/scripts/verify-skill-output.sh @@ -0,0 +1,214 @@ +#!/bin/bash +# verify-skill-output.sh +# 验证 DDS-to-Skill 转换输出的完整性和质量 +# +# 用法:./verify-skill-output.sh +# 示例:./verify-skill-output.sh /path/to/1-AgentSkills +# +# 依赖:bash, grep, sed, find, wc + +set -e + +SKILLS_DIR="${1:-.}" +PASS=0 +FAIL=0 +WARN=0 + +# 颜色输出 +GREEN='\033[0;32m' +RED='\033[0;31m' +YELLOW='\033[0;33m' +NC='\033[0m' # No Color + +pass() { + echo -e "${GREEN}✅ PASS${NC}: $1" + ((PASS++)) +} + +fail() { + echo -e "${RED}❌ FAIL${NC}: $1" + echo -e " ${RED}修复${NC}: $2" + ((FAIL++)) +} + +warn() { + echo -e "${YELLOW}⚠️ WARN${NC}: $1" + ((WARN++)) +} + +echo "============================================" +echo " DDS-to-Skill 输出质量验证" +echo " 目标目录: $SKILLS_DIR" +echo "============================================" +echo "" + +# ============================================ +# 1. 结构完整性检查 +# ============================================ +echo "--- 1. 结构完整性 ---" + +# S1: 检查是否有系统级 Skill +SYSTEM_SKILLS=$(find "$SKILLS_DIR" -maxdepth 1 -type d -name "*-system*" 2>/dev/null | wc -l) +if [ "$SYSTEM_SKILLS" -ge 1 ]; then + pass "S1: 存在系统级 Skill ($SYSTEM_SKILLS 个)" +else + warn "S1: 未找到系统级 Skill(名称包含 '-system')" +fi + +# S4: 每个 Skill 都有 SKILL.md +SKILL_DIRS=$(find "$SKILLS_DIR" -maxdepth 1 -type d ! -name "$(basename "$SKILLS_DIR")" 2>/dev/null) +MISSING_SKILLMD=0 +for dir in $SKILL_DIRS; do + if [ ! -f "$dir/SKILL.md" ]; then + fail "S4: $dir 缺少 SKILL.md" "创建该目录下的 SKILL.md" + ((MISSING_SKILLMD++)) + fi +done +if [ "$MISSING_SKILLMD" -eq 0 ]; then + pass "S4: 所有 Skill 目录都有 SKILL.md" +fi + +# S5: 每个 Skill 都有 reference/ +MISSING_REF=0 +for dir in $SKILL_DIRS; do + if [ ! -d "$dir/reference" ]; then + warn "S5: $dir 缺少 reference/ 目录" + ((MISSING_REF++)) + fi +done +if [ "$MISSING_REF" -eq 0 ]; then + pass "S5: 所有 Skill 目录都有 reference/" +fi + +echo "" + +# ============================================ +# 2. Frontmatter 规范检查 +# ============================================ +echo "--- 2. Frontmatter 规范 ---" + +for dir in $SKILL_DIRS; do + SKILL_FILE="$dir/SKILL.md" + [ ! -f "$SKILL_FILE" ] && continue + SKILL_NAME=$(basename "$dir") + + # F1: name 字段 + if head -20 "$SKILL_FILE" | grep -q '^name:'; then + pass "F1 [$SKILL_NAME]: frontmatter 包含 name" + else + fail "F1 [$SKILL_NAME]: 缺少 name 字段" "在 frontmatter 中添加 name 字段" + fi + + # F2: description 字段 + if head -20 "$SKILL_FILE" | grep -q '^description:'; then + pass "F2 [$SKILL_NAME]: frontmatter 包含 description" + else + fail "F2 [$SKILL_NAME]: 缺少 description 字段" "在 frontmatter 中添加 description 字段" + fi + + # C1: 行数 < 500 + LINE_COUNT=$(wc -l < "$SKILL_FILE") + if [ "$LINE_COUNT" -lt 500 ]; then + pass "C1 [$SKILL_NAME]: SKILL.md = $LINE_COUNT 行 (< 500)" + else + fail "C1 [$SKILL_NAME]: SKILL.md = $LINE_COUNT 行 (>= 500)" "将冗长内容移到 reference/ 中" + fi +done + +echo "" + +# ============================================ +# 3. 内容质量检查 +# ============================================ +echo "--- 3. 内容质量 ---" + +for dir in $SKILL_DIRS; do + SKILL_FILE="$dir/SKILL.md" + [ ! -f "$SKILL_FILE" ] && continue + SKILL_NAME=$(basename "$dir") + + # C2-C5: 必须章节 + for section in "Plan" "Verify" "Execute" "Pitfalls"; do + if grep -q "## $section" "$SKILL_FILE"; then + pass "C [$SKILL_NAME]: 包含 ## $section" + else + warn "C [$SKILL_NAME]: 缺少 ## $section 章节" + fi + done + + # C6: 动态注入 + INJECT_COUNT=$(grep -c '!`' "$SKILL_FILE" 2>/dev/null || echo 0) + if [ "$INJECT_COUNT" -ge 2 ]; then + pass "C6 [$SKILL_NAME]: $INJECT_COUNT 处动态注入 (>= 2)" + else + warn "C6 [$SKILL_NAME]: 仅 $INJECT_COUNT 处动态注入 (建议 >= 2)" + fi + + # C7: Pitfalls 引用 reference + REF_IN_PITFALLS=$(sed -n '/## Pitfalls/,/## /p' "$SKILL_FILE" | grep -c 'reference/' 2>/dev/null || echo 0) + if [ "$REF_IN_PITFALLS" -ge 2 ]; then + pass "C7 [$SKILL_NAME]: Pitfalls 中 $REF_IN_PITFALLS 处引用 reference (>= 2)" + else + warn "C7 [$SKILL_NAME]: Pitfalls 中仅 $REF_IN_PITFALLS 处引用 reference (建议 >= 2)" + fi +done + +echo "" + +# ============================================ +# 4. Reference 质量检查 +# ============================================ +echo "--- 4. Reference 质量 ---" + +for dir in $SKILL_DIRS; do + [ ! -d "$dir/reference" ] && continue + SKILL_NAME=$(basename "$dir") + + # R2: 章节分层 + SECTION_DIRS=$(find "$dir/reference" -maxdepth 1 -type d -name '0*' 2>/dev/null | wc -l) + if [ "$SECTION_DIRS" -ge 1 ]; then + pass "R2 [$SKILL_NAME]: reference 有 $SECTION_DIRS 个章节子目录" + else + warn "R2 [$SKILL_NAME]: reference 无章节子目录(使用扁平结构)" + fi + + # R3: DDS 溯源 + DDS_SECTION_COUNT=$(grep -r 'DDS-Section:' "$dir/reference/" 2>/dev/null | wc -l) + if [ "$DDS_SECTION_COUNT" -ge 1 ]; then + pass "R3 [$SKILL_NAME]: $DDS_SECTION_COUNT 处 DDS-Section 溯源" + else + warn "R3 [$SKILL_NAME]: 无 DDS-Section 溯源标记" + fi + + # R5: TBD 标注 + TBD_COUNT=$(grep -r '\[TBD' "$dir/reference/" 2>/dev/null | wc -l) + if [ "$TBD_COUNT" -ge 0 ]; then + pass "R5 [$SKILL_NAME]: $TBD_COUNT 处 [TBD] 标注" + fi + + # R1: 设计要素类型数 + REF_FILES=$(find "$dir/reference" -name "*.md" 2>/dev/null | wc -l) + if [ "$REF_FILES" -ge 3 ]; then + pass "R1 [$SKILL_NAME]: $REF_FILES 个 reference 文件 (>= 3)" + else + warn "R1 [$SKILL_NAME]: 仅 $REF_FILES 个 reference 文件 (建议 >= 3)" + fi +done + +echo "" + +# ============================================ +# 总结 +# ============================================ +echo "============================================" +echo " 验证完成" +echo " ✅ PASS: $PASS" +echo " ❌ FAIL: $FAIL" +echo " ⚠️ WARN: $WARN" +echo "============================================" + +if [ "$FAIL" -gt 0 ]; then + exit 1 +else + exit 0 +fi diff --git a/.agents/skills/dds-to-skill/scripts/verify.sh b/.agents/skills/dds-to-skill/scripts/verify.sh new file mode 100644 index 0000000..ebfbad7 --- /dev/null +++ b/.agents/skills/dds-to-skill/scripts/verify.sh @@ -0,0 +1,60 @@ +#!/bin/bash +# verify.sh - dds-to-skill Skill 自身结构验证 +# +# 验证本 Skill 的文件结构和内容完整性 +# 用法:cd dds-to-skill && ./scripts/verify.sh + +set -e + +PASS=0; FAIL=0 + +check() { + if eval "$2"; then + echo "✅ PASS: $1"; ((PASS++)) + else + echo "❌ FAIL: $1"; ((FAIL++)) + fi +} + +SKILL_DIR="$(cd "$(dirname "$0")/.." && pwd)" + +echo "=== dds-to-skill Skill 自检 ===" +echo "目录: $SKILL_DIR" +echo "" + +# 结构检查 +check "SKILL.md 存在" "test -f '$SKILL_DIR/SKILL.md'" +check "reference/ 目录存在" "test -d '$SKILL_DIR/reference'" +check "examples/ 目录存在" "test -d '$SKILL_DIR/examples'" +check "scripts/ 目录存在" "test -d '$SKILL_DIR/scripts'" + +# SKILL.md 内容检查 +check "SKILL.md < 500 行" "[ \$(wc -l < '$SKILL_DIR/SKILL.md') -lt 500 ]" +check "包含 name 字段" "head -20 '$SKILL_DIR/SKILL.md' | grep -q '^name:'" +check "包含 description 字段" "head -20 '$SKILL_DIR/SKILL.md' | grep -q '^description:'" +check "包含 argument-hint" "head -20 '$SKILL_DIR/SKILL.md' | grep -q 'argument-hint:'" + +# 阶段结构检查 +check "包含 Phase 0(读取)" "grep -q 'Phase 0' '$SKILL_DIR/SKILL.md'" +check "包含 Phase 1(分析)" "grep -q 'Phase 1' '$SKILL_DIR/SKILL.md'" +check "包含 Phase 2(抽取)" "grep -q 'Phase 2' '$SKILL_DIR/SKILL.md'" +check "包含 Phase 3(生成)" "grep -q 'Phase 3' '$SKILL_DIR/SKILL.md'" +check "包含 Phase 4(支撑文件)" "grep -q 'Phase 4' '$SKILL_DIR/SKILL.md'" +check "包含 Phase 5(自检)" "grep -q 'Phase 5' '$SKILL_DIR/SKILL.md'" + +# Reference 文件检查 +check "dds-extraction-guide.md 存在" "test -f '$SKILL_DIR/reference/dds-extraction-guide.md'" +check "skill-templates.md 存在" "test -f '$SKILL_DIR/reference/skill-templates.md'" +check "frontmatter-spec.md 存在" "test -f '$SKILL_DIR/reference/frontmatter-spec.md'" +check "quality-checklist.md 存在" "test -f '$SKILL_DIR/reference/quality-checklist.md'" + +# Examples 检查 +check "至少 1 个转换示例" "find '$SKILL_DIR/examples' -name '*.md' | grep -q ." + +# 动态注入检查 +INJECT_COUNT=$(grep -c '!\`' "$SKILL_DIR/SKILL.md" 2>/dev/null || echo 0) +check "SKILL.md 包含动态注入 (>= 2 处)" "[ $INJECT_COUNT -ge 2 ]" + +echo "" +echo "=== 结果: $PASS PASS / $FAIL FAIL ===" +[ $FAIL -eq 0 ] && exit 0 || exit 1 diff --git a/.agents/skills/developing-projectmoneyx/SKILL.md b/.agents/skills/developing-projectmoneyx/SKILL.md new file mode 100644 index 0000000..62de690 --- /dev/null +++ b/.agents/skills/developing-projectmoneyx/SKILL.md @@ -0,0 +1,267 @@ +--- +name: developing-projectmoneyx +description: > + 指导 ProjectMoneyX 多源账单数据治理系统的全栈开发(Guides full-stack development of ProjectMoneyX bill data governance system)。 + 包含:ETL Pipeline 编排(Parse → Normalize → Dedup → Link → Rule → Export)、插件化解析器对接、三层去重策略、规则引擎映射、Firefly III 适配、SQLite 数据模型、审计追溯。 + 触发场景 Trigger: 开发/修改 ProjectMoneyX 的 Parser / Pipeline / 去重 / 规则 / 导入导出 / 审计 / 前端页面 / API 接口。 + 关键词 Keywords: ProjectMoneyX, 账单, bill, ETL, parser, dedup, 去重, 链路合并, transfer link, rule engine, 规则引擎, Firefly III, 导入, import, export, audit, 审计, SQLite, GORM, GIN, Vue3, Vuetify。 +argument-hint: " " 例如/ e.g.: + "add parser for ccb", "implement dedup scorer", "create rule handler", + "update transaction schema", "build import preview page" +allowed-tools: + - Read + - Write + - Edit + - Glob + - Grep + - Bash +--- + +# Developing ProjectMoneyX + +ProjectMoneyX 是 Firefly III 生态的**本地化多源账单数据治理中间件**,技术栈为 Go (GIN + GORM) + Vue3 (TypeScript + Vuetify) + SQLite。系统核心是一条 ETL Pipeline:`Parse → Normalize → Dedup → Link → Rule → Export`,将支付宝/微信/银行账单标准化后推送至 Firefly III。 + +> **架构关键词**:DDD 分层 · 插件化 Adapter · 三层去重 · 规则可解释 · 全链路审计 + +## Quick Context + +```bash +# 动态注入:后端项目结构 +!`find projectmoneyx-server/internal -type f -name "*.go" | head -40` + +# 动态注入:前端项目结构 +!`find projectmoneyx-web/src -type f -name "*.ts" -o -name "*.vue" | head -30` + +# 动态注入:数据库表定义 +!`grep -rn "TableName\|func.*TableName" projectmoneyx-server/internal/ | head -20` + +# 动态注入:API 路由注册 +!`grep -rn "Group\|GET\|POST\|PUT\|DELETE" projectmoneyx-server/internal/handler/ | head -30` +``` + +## Architecture Overview + +``` +┌─────────────────────────────────────────────────────┐ +│ 展现层: Vue3 + TypeScript + Vuetify │ +│ 导入中心 / 清洗预览 / 去重处理 / 规则管理 / 导入任务 / 审计 │ +├─────────────────────────────────────────────────────┤ +│ 接入层: GIN RESTful API (/api/v1/*) │ +│ import / transactions / dedup / rules / export / audit │ +├─────────────────────────────────────────────────────┤ +│ 应用服务层: Pipeline 编排 │ +│ ImportBatchService → PipelineService │ +├─────────────────────────────────────────────────────┤ +│ 业务逻辑层 (ETL Core Domain) │ +│ Parser(插件) → Normalize → Match → Link → Rule → Export │ +├─────────────────────────────────────────────────────┤ +│ 数据持久层: GORM + SQLite (WAL) │ +│ 11 张核心表,分阶段事务 │ +└─────────────────────────────────────────────────────┘ +``` + +**分层依赖规则**:handler → service → domain(entity/repository)← dao。Parser/Matcher/Linker/Rule/Exporter 为独立可测试组件。 + +## Module Registry + +| 模块 | 包路径 | 职责 | 优先级 | +|------|--------|------|--------| +| 导入中心 | `handler/import` + `service/import_batch` | 文件上传、批次管理 | P0 | +| 解析引擎 | `parser/` | 插件化平台解析器 | P0 | +| 标准化引擎 | `normalize/` | 异构字段 → 统一 Transaction 模型 | P0 | +| 去重引擎 | `matcher/` | 严格去重 + 模糊去重(P1) | P0/P1 | +| 链路引擎 | `linker/` | 转账闭环 + 订单链路合并 | P0 | +| 规则引擎 | `rule/` | 6 类规则按序执行 | P0/P1 | +| 导出引擎 | `exporter/` | Firefly API/CSV 导出 | P0 | +| 审计中心 | `service/audit` | 全链路追溯 | P0 | +| 系统设置 | `handler/settings` + `config/` | Firefly 连接、阈值参数 | P1 | + +## Plan + +### 产物清单 + +| 动作 | 产物 | +|------|------| +| `add parser` | `parser//_parser.go` — 实现 `BillParser` 接口 | +| `create handler` | `handler/_handler.go` — GIN Handler | +| `create service` | `service/_service.go` — 应用服务 | +| `create dao` | `dao/_dao.go` — GORM 数据访问 | +| `create entity` | `domain/entity/.go` — 领域实体 | +| `add rule type` | `rule/_mapper.go` — 规则映射器 | +| `scaffold module` | 上述全部 + DTO + repository 接口 | + +### 决策点 + +1. **Parser 选择**:先检查 `parser/registry.go` 中已注册的解析器,确认目标平台是否已有实现 +2. **去重层级**:严格去重(P0) vs 模糊去重(P1) — 新功能默认只实现严格去重 +3. **规则执行顺序**:必须遵守 6 步固定顺序(`reference/04-rule-engine/rule-execution.md`) +4. **事务边界**:ETL 每阶段独立事务,禁止跨阶段长事务 +5. **SQLite 约束**:单写连接 `MaxOpenConns=1`,启用 WAL 模式 + +--- + +## Execute + +### 1. 新增平台解析器 + +```go +// 1. 实现 BillParser 接口 (parser//_parser.go) +type Parser struct{} + +func (p *Parser) Platform() string { return "" } + +func (p *Parser) Detect(meta FileMeta, header []string) bool { + // 基于文件名/表头特征判定 +} + +func (p *Parser) Parse(ctx context.Context, reader io.Reader) ([]RawBillRecord, error) { + // 逐行读取 → 填充 RawBillRecord.RawFields + // 必须设置 SourcePlatform, SourceRecordID, RowNo, RowFingerprint +} + +// 2. 注册到 Registry (parser/registry.go) +r.Register(&.Parser{}) +``` + +**字段映射要求**(参考 `reference/02-parser-engine/field-mappings.md`): +- `trade_time`:统一 UTC+8,`time.Time` +- `amount`:去除货币符号,正数 `decimal(18,6)` +- `direction`:`income` / `expense` / `transfer` / `refund` / `fee` / `other` +- `category_raw`:保留原始分类,不在 Parser 中做映射 +- `order_id`:去除空格,作为唯一标识 + +### 2. ETL Pipeline 阶段开发 + +每个阶段必须: +1. 接收 `context.Context` + 数据切片 +2. 返回处理后切片 + error +3. 在独立事务中持久化(`db.Transaction`,每批 500 条 `CreateInBatches`) +4. 更新批次状态 + +```go +// 阶段签名模式 +func (s *StageService) Execute(ctx context.Context, txns []*Transaction) ([]*Transaction, error) +``` + +### 3. 规则引擎扩展 + +新增规则类型时: +1. 在 `rule/engine.go` 的 `executionOrder` 中确认位置 +2. 实现 `MatchConditions(txn)` 和 `ApplyActions(txn)` 方法 +3. 确保 `RuleHit` 记录命中日志(含 `BeforeValue` / `AfterValue`) +4. 规则条件 JSON 存储,参考 `reference/04-rule-engine/rule-conditions.md` + +### 4. API 开发 + +遵循统一响应格式: +```go +type Response struct { + Code int `json:"code"` // 0=成功 + Message string `json:"message"` + Data interface{} `json:"data"` +} +``` + +路由分组:`/api/v1/import/*`、`/api/v1/transactions/*`、`/api/v1/dedup/*`、`/api/v1/rules/*`、`/api/v1/export/*`、`/api/v1/audit/*`、`/api/v1/settings/*` + +### 5. 前端页面开发 + +7 个核心页面,全部使用 Vue3 + Composition API + TypeScript: +- 导入中心:`FileUploader.vue` + 拖拽上传 + 进度条 +- 清洗预览:`TransactionTable.vue` + `v-data-table` + 行展开对比 +- 去重处理:`DedupCompare.vue` + 左右分栏 + 评分因子展开 +- 规则管理:`RuleEditor.vue` + 条件构建器 + 测试预览 +- 导入任务:统计概览 + 失败列表 + 单条/批量重试 +- 审计追溯:`AuditTimeline.vue` + `v-timeline` + 快照展开 +- 系统设置:Firefly 连接配置 + 测试连接 + 去重参数配置 + +--- + +## Verify + +### 架构层级检查 +- [ ] handler 层不包含业务逻辑,仅做参数绑定 + 调用 service + 返回响应 +- [ ] service 层不直接操作 `*gorm.DB`,通过 repository 接口访问数据 +- [ ] domain/entity 不依赖 handler/service +- [ ] 无循环依赖(handler → service → domain ← dao) + +### Parser 检查 +- [ ] 新增 Parser 实现了 `BillParser` 接口的全部 3 个方法(`Platform()`, `Detect()`, `Parse()`) +- [ ] 已注册到 `parser/registry.go`(`reference/02-parser-engine/parser-interface.md`) +- [ ] 字段映射覆盖了所有原始字段(对照 `reference/02-parser-engine/field-mappings.md`) +- [ ] `amount` 为正数,`direction` 独立表达收支方向 +- [ ] `RowFingerprint` 使用 SHA256 生成(`reference/03-dedup-engine/fingerprint.md`) + +### 去重与链路检查 +- [ ] 严格去重判定键按优先级 3 级执行(`reference/03-dedup-engine/strict-dedup.md`) +- [ ] 模糊去重评分因子 6 项,阈值可配置(`reference/03-dedup-engine/fuzzy-dedup.md`) +- [ ] 转账闭环 5 条件全部满足才匹配(`reference/03-dedup-engine/transfer-link.md`) +- [ ] 疑似重复(60-84 分)进入 `PENDING_REVIEW` 人工确认队列 + +### 规则引擎检查 +- [ ] 6 类规则按固定顺序执行:对手方归一 → 商户归一 → 分类 → 账户 → 标签 → Firefly(`reference/04-rule-engine/rule-execution.md`) +- [ ] 同类型内按 `priority` 升序执行,首条命中即停止 +- [ ] 每条命中记录 `RuleHit`,含 `BeforeValue` / `AfterValue` +- [ ] 规则条件 JSON 结构正确(`reference/04-rule-engine/rule-conditions.md`) + +### 数据库检查 +- [ ] 表结构 11 张表齐全(`reference/05-database/db-schema.md`) +- [ ] 关键索引已创建(`reference/05-database/indexes.md`) +- [ ] SQLite 配置:`MaxOpenConns=1`, WAL 模式, `cache_size=-64000` +- [ ] ETL 每阶段独立事务,`CreateInBatches` 每批 500 条 + +### API 检查 +- [ ] 路由路径遵循 `reference/06-api-design/api-catalog.md` +- [ ] 统一 `Response` / `PageResponse` 结构 +- [ ] 导入前 6 项校验完整(`reference/07-export-engine/import-validation.md`) + +### 前端检查 +- [ ] 所有页面使用 ` + + diff --git a/.agents/skills/skill-creator/eval-viewer/generate_review.py b/.agents/skills/skill-creator/eval-viewer/generate_review.py new file mode 100644 index 0000000..7fa5978 --- /dev/null +++ b/.agents/skills/skill-creator/eval-viewer/generate_review.py @@ -0,0 +1,471 @@ +#!/usr/bin/env python3 +"""Generate and serve a review page for eval results. + +Reads the workspace directory, discovers runs (directories with outputs/), +embeds all output data into a self-contained HTML page, and serves it via +a tiny HTTP server. Feedback auto-saves to feedback.json in the workspace. + +Usage: + python generate_review.py [--port PORT] [--skill-name NAME] + python generate_review.py --previous-feedback /path/to/old/feedback.json + +No dependencies beyond the Python stdlib are required. +""" + +import argparse +import base64 +import json +import mimetypes +import os +import re +import signal +import subprocess +import sys +import time +import webbrowser +from functools import partial +from http.server import HTTPServer, BaseHTTPRequestHandler +from pathlib import Path + +# Files to exclude from output listings +METADATA_FILES = {"transcript.md", "user_notes.md", "metrics.json"} + +# Extensions we render as inline text +TEXT_EXTENSIONS = { + ".txt", ".md", ".json", ".csv", ".py", ".js", ".ts", ".tsx", ".jsx", + ".yaml", ".yml", ".xml", ".html", ".css", ".sh", ".rb", ".go", ".rs", + ".java", ".c", ".cpp", ".h", ".hpp", ".sql", ".r", ".toml", +} + +# Extensions we render as inline images +IMAGE_EXTENSIONS = {".png", ".jpg", ".jpeg", ".gif", ".svg", ".webp"} + +# MIME type overrides for common types +MIME_OVERRIDES = { + ".svg": "image/svg+xml", + ".xlsx": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet", + ".docx": "application/vnd.openxmlformats-officedocument.wordprocessingml.document", + ".pptx": "application/vnd.openxmlformats-officedocument.presentationml.presentation", +} + + +def get_mime_type(path: Path) -> str: + ext = path.suffix.lower() + if ext in MIME_OVERRIDES: + return MIME_OVERRIDES[ext] + mime, _ = mimetypes.guess_type(str(path)) + return mime or "application/octet-stream" + + +def find_runs(workspace: Path) -> list[dict]: + """Recursively find directories that contain an outputs/ subdirectory.""" + runs: list[dict] = [] + _find_runs_recursive(workspace, workspace, runs) + runs.sort(key=lambda r: (r.get("eval_id", float("inf")), r["id"])) + return runs + + +def _find_runs_recursive(root: Path, current: Path, runs: list[dict]) -> None: + if not current.is_dir(): + return + + outputs_dir = current / "outputs" + if outputs_dir.is_dir(): + run = build_run(root, current) + if run: + runs.append(run) + return + + skip = {"node_modules", ".git", "__pycache__", "skill", "inputs"} + for child in sorted(current.iterdir()): + if child.is_dir() and child.name not in skip: + _find_runs_recursive(root, child, runs) + + +def build_run(root: Path, run_dir: Path) -> dict | None: + """Build a run dict with prompt, outputs, and grading data.""" + prompt = "" + eval_id = None + + # Try eval_metadata.json + for candidate in [run_dir / "eval_metadata.json", run_dir.parent / "eval_metadata.json"]: + if candidate.exists(): + try: + metadata = json.loads(candidate.read_text()) + prompt = metadata.get("prompt", "") + eval_id = metadata.get("eval_id") + except (json.JSONDecodeError, OSError): + pass + if prompt: + break + + # Fall back to transcript.md + if not prompt: + for candidate in [run_dir / "transcript.md", run_dir / "outputs" / "transcript.md"]: + if candidate.exists(): + try: + text = candidate.read_text() + match = re.search(r"## Eval Prompt\n\n([\s\S]*?)(?=\n##|$)", text) + if match: + prompt = match.group(1).strip() + except OSError: + pass + if prompt: + break + + if not prompt: + prompt = "(No prompt found)" + + run_id = str(run_dir.relative_to(root)).replace("/", "-").replace("\\", "-") + + # Collect output files + outputs_dir = run_dir / "outputs" + output_files: list[dict] = [] + if outputs_dir.is_dir(): + for f in sorted(outputs_dir.iterdir()): + if f.is_file() and f.name not in METADATA_FILES: + output_files.append(embed_file(f)) + + # Load grading if present + grading = None + for candidate in [run_dir / "grading.json", run_dir.parent / "grading.json"]: + if candidate.exists(): + try: + grading = json.loads(candidate.read_text()) + except (json.JSONDecodeError, OSError): + pass + if grading: + break + + return { + "id": run_id, + "prompt": prompt, + "eval_id": eval_id, + "outputs": output_files, + "grading": grading, + } + + +def embed_file(path: Path) -> dict: + """Read a file and return an embedded representation.""" + ext = path.suffix.lower() + mime = get_mime_type(path) + + if ext in TEXT_EXTENSIONS: + try: + content = path.read_text(errors="replace") + except OSError: + content = "(Error reading file)" + return { + "name": path.name, + "type": "text", + "content": content, + } + elif ext in IMAGE_EXTENSIONS: + try: + raw = path.read_bytes() + b64 = base64.b64encode(raw).decode("ascii") + except OSError: + return {"name": path.name, "type": "error", "content": "(Error reading file)"} + return { + "name": path.name, + "type": "image", + "mime": mime, + "data_uri": f"data:{mime};base64,{b64}", + } + elif ext == ".pdf": + try: + raw = path.read_bytes() + b64 = base64.b64encode(raw).decode("ascii") + except OSError: + return {"name": path.name, "type": "error", "content": "(Error reading file)"} + return { + "name": path.name, + "type": "pdf", + "data_uri": f"data:{mime};base64,{b64}", + } + elif ext == ".xlsx": + try: + raw = path.read_bytes() + b64 = base64.b64encode(raw).decode("ascii") + except OSError: + return {"name": path.name, "type": "error", "content": "(Error reading file)"} + return { + "name": path.name, + "type": "xlsx", + "data_b64": b64, + } + else: + # Binary / unknown — base64 download link + try: + raw = path.read_bytes() + b64 = base64.b64encode(raw).decode("ascii") + except OSError: + return {"name": path.name, "type": "error", "content": "(Error reading file)"} + return { + "name": path.name, + "type": "binary", + "mime": mime, + "data_uri": f"data:{mime};base64,{b64}", + } + + +def load_previous_iteration(workspace: Path) -> dict[str, dict]: + """Load previous iteration's feedback and outputs. + + Returns a map of run_id -> {"feedback": str, "outputs": list[dict]}. + """ + result: dict[str, dict] = {} + + # Load feedback + feedback_map: dict[str, str] = {} + feedback_path = workspace / "feedback.json" + if feedback_path.exists(): + try: + data = json.loads(feedback_path.read_text()) + feedback_map = { + r["run_id"]: r["feedback"] + for r in data.get("reviews", []) + if r.get("feedback", "").strip() + } + except (json.JSONDecodeError, OSError, KeyError): + pass + + # Load runs (to get outputs) + prev_runs = find_runs(workspace) + for run in prev_runs: + result[run["id"]] = { + "feedback": feedback_map.get(run["id"], ""), + "outputs": run.get("outputs", []), + } + + # Also add feedback for run_ids that had feedback but no matching run + for run_id, fb in feedback_map.items(): + if run_id not in result: + result[run_id] = {"feedback": fb, "outputs": []} + + return result + + +def generate_html( + runs: list[dict], + skill_name: str, + previous: dict[str, dict] | None = None, + benchmark: dict | None = None, +) -> str: + """Generate the complete standalone HTML page with embedded data.""" + template_path = Path(__file__).parent / "viewer.html" + template = template_path.read_text() + + # Build previous_feedback and previous_outputs maps for the template + previous_feedback: dict[str, str] = {} + previous_outputs: dict[str, list[dict]] = {} + if previous: + for run_id, data in previous.items(): + if data.get("feedback"): + previous_feedback[run_id] = data["feedback"] + if data.get("outputs"): + previous_outputs[run_id] = data["outputs"] + + embedded = { + "skill_name": skill_name, + "runs": runs, + "previous_feedback": previous_feedback, + "previous_outputs": previous_outputs, + } + if benchmark: + embedded["benchmark"] = benchmark + + data_json = json.dumps(embedded) + + return template.replace("/*__EMBEDDED_DATA__*/", f"const EMBEDDED_DATA = {data_json};") + + +# --------------------------------------------------------------------------- +# HTTP server (stdlib only, zero dependencies) +# --------------------------------------------------------------------------- + +def _kill_port(port: int) -> None: + """Kill any process listening on the given port.""" + try: + result = subprocess.run( + ["lsof", "-ti", f":{port}"], + capture_output=True, text=True, timeout=5, + ) + for pid_str in result.stdout.strip().split("\n"): + if pid_str.strip(): + try: + os.kill(int(pid_str.strip()), signal.SIGTERM) + except (ProcessLookupError, ValueError): + pass + if result.stdout.strip(): + time.sleep(0.5) + except subprocess.TimeoutExpired: + pass + except FileNotFoundError: + print("Note: lsof not found, cannot check if port is in use", file=sys.stderr) + +class ReviewHandler(BaseHTTPRequestHandler): + """Serves the review HTML and handles feedback saves. + + Regenerates the HTML on each page load so that refreshing the browser + picks up new eval outputs without restarting the server. + """ + + def __init__( + self, + workspace: Path, + skill_name: str, + feedback_path: Path, + previous: dict[str, dict], + benchmark_path: Path | None, + *args, + **kwargs, + ): + self.workspace = workspace + self.skill_name = skill_name + self.feedback_path = feedback_path + self.previous = previous + self.benchmark_path = benchmark_path + super().__init__(*args, **kwargs) + + def do_GET(self) -> None: + if self.path == "/" or self.path == "/index.html": + # Regenerate HTML on each request (re-scans workspace for new outputs) + runs = find_runs(self.workspace) + benchmark = None + if self.benchmark_path and self.benchmark_path.exists(): + try: + benchmark = json.loads(self.benchmark_path.read_text()) + except (json.JSONDecodeError, OSError): + pass + html = generate_html(runs, self.skill_name, self.previous, benchmark) + content = html.encode("utf-8") + self.send_response(200) + self.send_header("Content-Type", "text/html; charset=utf-8") + self.send_header("Content-Length", str(len(content))) + self.end_headers() + self.wfile.write(content) + elif self.path == "/api/feedback": + data = b"{}" + if self.feedback_path.exists(): + data = self.feedback_path.read_bytes() + self.send_response(200) + self.send_header("Content-Type", "application/json") + self.send_header("Content-Length", str(len(data))) + self.end_headers() + self.wfile.write(data) + else: + self.send_error(404) + + def do_POST(self) -> None: + if self.path == "/api/feedback": + length = int(self.headers.get("Content-Length", 0)) + body = self.rfile.read(length) + try: + data = json.loads(body) + if not isinstance(data, dict) or "reviews" not in data: + raise ValueError("Expected JSON object with 'reviews' key") + self.feedback_path.write_text(json.dumps(data, indent=2) + "\n") + resp = b'{"ok":true}' + self.send_response(200) + except (json.JSONDecodeError, OSError, ValueError) as e: + resp = json.dumps({"error": str(e)}).encode() + self.send_response(500) + self.send_header("Content-Type", "application/json") + self.send_header("Content-Length", str(len(resp))) + self.end_headers() + self.wfile.write(resp) + else: + self.send_error(404) + + def log_message(self, format: str, *args: object) -> None: + # Suppress request logging to keep terminal clean + pass + + +def main() -> None: + parser = argparse.ArgumentParser(description="Generate and serve eval review") + parser.add_argument("workspace", type=Path, help="Path to workspace directory") + parser.add_argument("--port", "-p", type=int, default=3117, help="Server port (default: 3117)") + parser.add_argument("--skill-name", "-n", type=str, default=None, help="Skill name for header") + parser.add_argument( + "--previous-workspace", type=Path, default=None, + help="Path to previous iteration's workspace (shows old outputs and feedback as context)", + ) + parser.add_argument( + "--benchmark", type=Path, default=None, + help="Path to benchmark.json to show in the Benchmark tab", + ) + parser.add_argument( + "--static", "-s", type=Path, default=None, + help="Write standalone HTML to this path instead of starting a server", + ) + args = parser.parse_args() + + workspace = args.workspace.resolve() + if not workspace.is_dir(): + print(f"Error: {workspace} is not a directory", file=sys.stderr) + sys.exit(1) + + runs = find_runs(workspace) + if not runs: + print(f"No runs found in {workspace}", file=sys.stderr) + sys.exit(1) + + skill_name = args.skill_name or workspace.name.replace("-workspace", "") + feedback_path = workspace / "feedback.json" + + previous: dict[str, dict] = {} + if args.previous_workspace: + previous = load_previous_iteration(args.previous_workspace.resolve()) + + benchmark_path = args.benchmark.resolve() if args.benchmark else None + benchmark = None + if benchmark_path and benchmark_path.exists(): + try: + benchmark = json.loads(benchmark_path.read_text()) + except (json.JSONDecodeError, OSError): + pass + + if args.static: + html = generate_html(runs, skill_name, previous, benchmark) + args.static.parent.mkdir(parents=True, exist_ok=True) + args.static.write_text(html) + print(f"\n Static viewer written to: {args.static}\n") + sys.exit(0) + + # Kill any existing process on the target port + port = args.port + _kill_port(port) + handler = partial(ReviewHandler, workspace, skill_name, feedback_path, previous, benchmark_path) + try: + server = HTTPServer(("127.0.0.1", port), handler) + except OSError: + # Port still in use after kill attempt — find a free one + server = HTTPServer(("127.0.0.1", 0), handler) + port = server.server_address[1] + + url = f"http://localhost:{port}" + print(f"\n Eval Viewer") + print(f" ─────────────────────────────────") + print(f" URL: {url}") + print(f" Workspace: {workspace}") + print(f" Feedback: {feedback_path}") + if previous: + print(f" Previous: {args.previous_workspace} ({len(previous)} runs)") + if benchmark_path: + print(f" Benchmark: {benchmark_path}") + print(f"\n Press Ctrl+C to stop.\n") + + webbrowser.open(url) + + try: + server.serve_forever() + except KeyboardInterrupt: + print("\nStopped.") + server.server_close() + + +if __name__ == "__main__": + main() diff --git a/.agents/skills/skill-creator/eval-viewer/viewer.html b/.agents/skills/skill-creator/eval-viewer/viewer.html new file mode 100644 index 0000000..6d8e963 --- /dev/null +++ b/.agents/skills/skill-creator/eval-viewer/viewer.html @@ -0,0 +1,1325 @@ + + + + + + Eval Review + + + + + + + +
+
+
+

Eval Review:

+
Review each output and leave feedback below. Navigate with arrow keys or buttons. When done, copy feedback and paste into Claude Code.
+
+
+
+ + + + + +
+
+ +
+
Prompt
+
+
+
+
+ + +
+
Output
+
+
No output files found
+
+
+ + + + + + + + +
+
Your Feedback
+
+ + + +
+
+
+ + +
+ + +
+
+
No benchmark data available. Run a benchmark to see quantitative results here.
+
+
+
+ + +
+
+

Review Complete

+

Your feedback has been saved. Go back to your Claude Code session and tell Claude you're done reviewing.

+
+ +
+
+
+ + +
+ + + + diff --git a/.agents/skills/skill-creator/references/schemas.md b/.agents/skills/skill-creator/references/schemas.md new file mode 100644 index 0000000..b6eeaa2 --- /dev/null +++ b/.agents/skills/skill-creator/references/schemas.md @@ -0,0 +1,430 @@ +# JSON Schemas + +This document defines the JSON schemas used by skill-creator. + +--- + +## evals.json + +Defines the evals for a skill. Located at `evals/evals.json` within the skill directory. + +```json +{ + "skill_name": "example-skill", + "evals": [ + { + "id": 1, + "prompt": "User's example prompt", + "expected_output": "Description of expected result", + "files": ["evals/files/sample1.pdf"], + "expectations": [ + "The output includes X", + "The skill used script Y" + ] + } + ] +} +``` + +**Fields:** +- `skill_name`: Name matching the skill's frontmatter +- `evals[].id`: Unique integer identifier +- `evals[].prompt`: The task to execute +- `evals[].expected_output`: Human-readable description of success +- `evals[].files`: Optional list of input file paths (relative to skill root) +- `evals[].expectations`: List of verifiable statements + +--- + +## history.json + +Tracks version progression in Improve mode. Located at workspace root. + +```json +{ + "started_at": "2026-01-15T10:30:00Z", + "skill_name": "pdf", + "current_best": "v2", + "iterations": [ + { + "version": "v0", + "parent": null, + "expectation_pass_rate": 0.65, + "grading_result": "baseline", + "is_current_best": false + }, + { + "version": "v1", + "parent": "v0", + "expectation_pass_rate": 0.75, + "grading_result": "won", + "is_current_best": false + }, + { + "version": "v2", + "parent": "v1", + "expectation_pass_rate": 0.85, + "grading_result": "won", + "is_current_best": true + } + ] +} +``` + +**Fields:** +- `started_at`: ISO timestamp of when improvement started +- `skill_name`: Name of the skill being improved +- `current_best`: Version identifier of the best performer +- `iterations[].version`: Version identifier (v0, v1, ...) +- `iterations[].parent`: Parent version this was derived from +- `iterations[].expectation_pass_rate`: Pass rate from grading +- `iterations[].grading_result`: "baseline", "won", "lost", or "tie" +- `iterations[].is_current_best`: Whether this is the current best version + +--- + +## grading.json + +Output from the grader agent. Located at `/grading.json`. + +```json +{ + "expectations": [ + { + "text": "The output includes the name 'John Smith'", + "passed": true, + "evidence": "Found in transcript Step 3: 'Extracted names: John Smith, Sarah Johnson'" + }, + { + "text": "The spreadsheet has a SUM formula in cell B10", + "passed": false, + "evidence": "No spreadsheet was created. The output was a text file." + } + ], + "summary": { + "passed": 2, + "failed": 1, + "total": 3, + "pass_rate": 0.67 + }, + "execution_metrics": { + "tool_calls": { + "Read": 5, + "Write": 2, + "Bash": 8 + }, + "total_tool_calls": 15, + "total_steps": 6, + "errors_encountered": 0, + "output_chars": 12450, + "transcript_chars": 3200 + }, + "timing": { + "executor_duration_seconds": 165.0, + "grader_duration_seconds": 26.0, + "total_duration_seconds": 191.0 + }, + "claims": [ + { + "claim": "The form has 12 fillable fields", + "type": "factual", + "verified": true, + "evidence": "Counted 12 fields in field_info.json" + } + ], + "user_notes_summary": { + "uncertainties": ["Used 2023 data, may be stale"], + "needs_review": [], + "workarounds": ["Fell back to text overlay for non-fillable fields"] + }, + "eval_feedback": { + "suggestions": [ + { + "assertion": "The output includes the name 'John Smith'", + "reason": "A hallucinated document that mentions the name would also pass" + } + ], + "overall": "Assertions check presence but not correctness." + } +} +``` + +**Fields:** +- `expectations[]`: Graded expectations with evidence +- `summary`: Aggregate pass/fail counts +- `execution_metrics`: Tool usage and output size (from executor's metrics.json) +- `timing`: Wall clock timing (from timing.json) +- `claims`: Extracted and verified claims from the output +- `user_notes_summary`: Issues flagged by the executor +- `eval_feedback`: (optional) Improvement suggestions for the evals, only present when the grader identifies issues worth raising + +--- + +## metrics.json + +Output from the executor agent. Located at `/outputs/metrics.json`. + +```json +{ + "tool_calls": { + "Read": 5, + "Write": 2, + "Bash": 8, + "Edit": 1, + "Glob": 2, + "Grep": 0 + }, + "total_tool_calls": 18, + "total_steps": 6, + "files_created": ["filled_form.pdf", "field_values.json"], + "errors_encountered": 0, + "output_chars": 12450, + "transcript_chars": 3200 +} +``` + +**Fields:** +- `tool_calls`: Count per tool type +- `total_tool_calls`: Sum of all tool calls +- `total_steps`: Number of major execution steps +- `files_created`: List of output files created +- `errors_encountered`: Number of errors during execution +- `output_chars`: Total character count of output files +- `transcript_chars`: Character count of transcript + +--- + +## timing.json + +Wall clock timing for a run. Located at `/timing.json`. + +**How to capture:** When a subagent task completes, the task notification includes `total_tokens` and `duration_ms`. Save these immediately — they are not persisted anywhere else and cannot be recovered after the fact. + +```json +{ + "total_tokens": 84852, + "duration_ms": 23332, + "total_duration_seconds": 23.3, + "executor_start": "2026-01-15T10:30:00Z", + "executor_end": "2026-01-15T10:32:45Z", + "executor_duration_seconds": 165.0, + "grader_start": "2026-01-15T10:32:46Z", + "grader_end": "2026-01-15T10:33:12Z", + "grader_duration_seconds": 26.0 +} +``` + +--- + +## benchmark.json + +Output from Benchmark mode. Located at `benchmarks//benchmark.json`. + +```json +{ + "metadata": { + "skill_name": "pdf", + "skill_path": "/path/to/pdf", + "executor_model": "claude-sonnet-4-20250514", + "analyzer_model": "most-capable-model", + "timestamp": "2026-01-15T10:30:00Z", + "evals_run": [1, 2, 3], + "runs_per_configuration": 3 + }, + + "runs": [ + { + "eval_id": 1, + "eval_name": "Ocean", + "configuration": "with_skill", + "run_number": 1, + "result": { + "pass_rate": 0.85, + "passed": 6, + "failed": 1, + "total": 7, + "time_seconds": 42.5, + "tokens": 3800, + "tool_calls": 18, + "errors": 0 + }, + "expectations": [ + {"text": "...", "passed": true, "evidence": "..."} + ], + "notes": [ + "Used 2023 data, may be stale", + "Fell back to text overlay for non-fillable fields" + ] + } + ], + + "run_summary": { + "with_skill": { + "pass_rate": {"mean": 0.85, "stddev": 0.05, "min": 0.80, "max": 0.90}, + "time_seconds": {"mean": 45.0, "stddev": 12.0, "min": 32.0, "max": 58.0}, + "tokens": {"mean": 3800, "stddev": 400, "min": 3200, "max": 4100} + }, + "without_skill": { + "pass_rate": {"mean": 0.35, "stddev": 0.08, "min": 0.28, "max": 0.45}, + "time_seconds": {"mean": 32.0, "stddev": 8.0, "min": 24.0, "max": 42.0}, + "tokens": {"mean": 2100, "stddev": 300, "min": 1800, "max": 2500} + }, + "delta": { + "pass_rate": "+0.50", + "time_seconds": "+13.0", + "tokens": "+1700" + } + }, + + "notes": [ + "Assertion 'Output is a PDF file' passes 100% in both configurations - may not differentiate skill value", + "Eval 3 shows high variance (50% ± 40%) - may be flaky or model-dependent", + "Without-skill runs consistently fail on table extraction expectations", + "Skill adds 13s average execution time but improves pass rate by 50%" + ] +} +``` + +**Fields:** +- `metadata`: Information about the benchmark run + - `skill_name`: Name of the skill + - `timestamp`: When the benchmark was run + - `evals_run`: List of eval names or IDs + - `runs_per_configuration`: Number of runs per config (e.g. 3) +- `runs[]`: Individual run results + - `eval_id`: Numeric eval identifier + - `eval_name`: Human-readable eval name (used as section header in the viewer) + - `configuration`: Must be `"with_skill"` or `"without_skill"` (the viewer uses this exact string for grouping and color coding) + - `run_number`: Integer run number (1, 2, 3...) + - `result`: Nested object with `pass_rate`, `passed`, `total`, `time_seconds`, `tokens`, `errors` +- `run_summary`: Statistical aggregates per configuration + - `with_skill` / `without_skill`: Each contains `pass_rate`, `time_seconds`, `tokens` objects with `mean` and `stddev` fields + - `delta`: Difference strings like `"+0.50"`, `"+13.0"`, `"+1700"` +- `notes`: Freeform observations from the analyzer + +**Important:** The viewer reads these field names exactly. Using `config` instead of `configuration`, or putting `pass_rate` at the top level of a run instead of nested under `result`, will cause the viewer to show empty/zero values. Always reference this schema when generating benchmark.json manually. + +--- + +## comparison.json + +Output from blind comparator. Located at `/comparison-N.json`. + +```json +{ + "winner": "A", + "reasoning": "Output A provides a complete solution with proper formatting and all required fields. Output B is missing the date field and has formatting inconsistencies.", + "rubric": { + "A": { + "content": { + "correctness": 5, + "completeness": 5, + "accuracy": 4 + }, + "structure": { + "organization": 4, + "formatting": 5, + "usability": 4 + }, + "content_score": 4.7, + "structure_score": 4.3, + "overall_score": 9.0 + }, + "B": { + "content": { + "correctness": 3, + "completeness": 2, + "accuracy": 3 + }, + "structure": { + "organization": 3, + "formatting": 2, + "usability": 3 + }, + "content_score": 2.7, + "structure_score": 2.7, + "overall_score": 5.4 + } + }, + "output_quality": { + "A": { + "score": 9, + "strengths": ["Complete solution", "Well-formatted", "All fields present"], + "weaknesses": ["Minor style inconsistency in header"] + }, + "B": { + "score": 5, + "strengths": ["Readable output", "Correct basic structure"], + "weaknesses": ["Missing date field", "Formatting inconsistencies", "Partial data extraction"] + } + }, + "expectation_results": { + "A": { + "passed": 4, + "total": 5, + "pass_rate": 0.80, + "details": [ + {"text": "Output includes name", "passed": true} + ] + }, + "B": { + "passed": 3, + "total": 5, + "pass_rate": 0.60, + "details": [ + {"text": "Output includes name", "passed": true} + ] + } + } +} +``` + +--- + +## analysis.json + +Output from post-hoc analyzer. Located at `/analysis.json`. + +```json +{ + "comparison_summary": { + "winner": "A", + "winner_skill": "path/to/winner/skill", + "loser_skill": "path/to/loser/skill", + "comparator_reasoning": "Brief summary of why comparator chose winner" + }, + "winner_strengths": [ + "Clear step-by-step instructions for handling multi-page documents", + "Included validation script that caught formatting errors" + ], + "loser_weaknesses": [ + "Vague instruction 'process the document appropriately' led to inconsistent behavior", + "No script for validation, agent had to improvise" + ], + "instruction_following": { + "winner": { + "score": 9, + "issues": ["Minor: skipped optional logging step"] + }, + "loser": { + "score": 6, + "issues": [ + "Did not use the skill's formatting template", + "Invented own approach instead of following step 3" + ] + } + }, + "improvement_suggestions": [ + { + "priority": "high", + "category": "instructions", + "suggestion": "Replace 'process the document appropriately' with explicit steps", + "expected_impact": "Would eliminate ambiguity that caused inconsistent behavior" + } + ], + "transcript_insights": { + "winner_execution_pattern": "Read skill -> Followed 5-step process -> Used validation script", + "loser_execution_pattern": "Read skill -> Unclear on approach -> Tried 3 different methods" + } +} +``` diff --git a/.agents/skills/skill-creator/scripts/aggregate_benchmark.py b/.agents/skills/skill-creator/scripts/aggregate_benchmark.py new file mode 100644 index 0000000..3e66e8c --- /dev/null +++ b/.agents/skills/skill-creator/scripts/aggregate_benchmark.py @@ -0,0 +1,401 @@ +#!/usr/bin/env python3 +""" +Aggregate individual run results into benchmark summary statistics. + +Reads grading.json files from run directories and produces: +- run_summary with mean, stddev, min, max for each metric +- delta between with_skill and without_skill configurations + +Usage: + python aggregate_benchmark.py + +Example: + python aggregate_benchmark.py benchmarks/2026-01-15T10-30-00/ + +The script supports two directory layouts: + + Workspace layout (from skill-creator iterations): + / + └── eval-N/ + ├── with_skill/ + │ ├── run-1/grading.json + │ └── run-2/grading.json + └── without_skill/ + ├── run-1/grading.json + └── run-2/grading.json + + Legacy layout (with runs/ subdirectory): + / + └── runs/ + └── eval-N/ + ├── with_skill/ + │ └── run-1/grading.json + └── without_skill/ + └── run-1/grading.json +""" + +import argparse +import json +import math +import sys +from datetime import datetime, timezone +from pathlib import Path + + +def calculate_stats(values: list[float]) -> dict: + """Calculate mean, stddev, min, max for a list of values.""" + if not values: + return {"mean": 0.0, "stddev": 0.0, "min": 0.0, "max": 0.0} + + n = len(values) + mean = sum(values) / n + + if n > 1: + variance = sum((x - mean) ** 2 for x in values) / (n - 1) + stddev = math.sqrt(variance) + else: + stddev = 0.0 + + return { + "mean": round(mean, 4), + "stddev": round(stddev, 4), + "min": round(min(values), 4), + "max": round(max(values), 4) + } + + +def load_run_results(benchmark_dir: Path) -> dict: + """ + Load all run results from a benchmark directory. + + Returns dict keyed by config name (e.g. "with_skill"/"without_skill", + or "new_skill"/"old_skill"), each containing a list of run results. + """ + # Support both layouts: eval dirs directly under benchmark_dir, or under runs/ + runs_dir = benchmark_dir / "runs" + if runs_dir.exists(): + search_dir = runs_dir + elif list(benchmark_dir.glob("eval-*")): + search_dir = benchmark_dir + else: + print(f"No eval directories found in {benchmark_dir} or {benchmark_dir / 'runs'}") + return {} + + results: dict[str, list] = {} + + for eval_idx, eval_dir in enumerate(sorted(search_dir.glob("eval-*"))): + metadata_path = eval_dir / "eval_metadata.json" + if metadata_path.exists(): + try: + with open(metadata_path) as mf: + eval_id = json.load(mf).get("eval_id", eval_idx) + except (json.JSONDecodeError, OSError): + eval_id = eval_idx + else: + try: + eval_id = int(eval_dir.name.split("-")[1]) + except ValueError: + eval_id = eval_idx + + # Discover config directories dynamically rather than hardcoding names + for config_dir in sorted(eval_dir.iterdir()): + if not config_dir.is_dir(): + continue + # Skip non-config directories (inputs, outputs, etc.) + if not list(config_dir.glob("run-*")): + continue + config = config_dir.name + if config not in results: + results[config] = [] + + for run_dir in sorted(config_dir.glob("run-*")): + run_number = int(run_dir.name.split("-")[1]) + grading_file = run_dir / "grading.json" + + if not grading_file.exists(): + print(f"Warning: grading.json not found in {run_dir}") + continue + + try: + with open(grading_file) as f: + grading = json.load(f) + except json.JSONDecodeError as e: + print(f"Warning: Invalid JSON in {grading_file}: {e}") + continue + + # Extract metrics + result = { + "eval_id": eval_id, + "run_number": run_number, + "pass_rate": grading.get("summary", {}).get("pass_rate", 0.0), + "passed": grading.get("summary", {}).get("passed", 0), + "failed": grading.get("summary", {}).get("failed", 0), + "total": grading.get("summary", {}).get("total", 0), + } + + # Extract timing — check grading.json first, then sibling timing.json + timing = grading.get("timing", {}) + result["time_seconds"] = timing.get("total_duration_seconds", 0.0) + timing_file = run_dir / "timing.json" + if result["time_seconds"] == 0.0 and timing_file.exists(): + try: + with open(timing_file) as tf: + timing_data = json.load(tf) + result["time_seconds"] = timing_data.get("total_duration_seconds", 0.0) + result["tokens"] = timing_data.get("total_tokens", 0) + except json.JSONDecodeError: + pass + + # Extract metrics if available + metrics = grading.get("execution_metrics", {}) + result["tool_calls"] = metrics.get("total_tool_calls", 0) + if not result.get("tokens"): + result["tokens"] = metrics.get("output_chars", 0) + result["errors"] = metrics.get("errors_encountered", 0) + + # Extract expectations — viewer requires fields: text, passed, evidence + raw_expectations = grading.get("expectations", []) + for exp in raw_expectations: + if "text" not in exp or "passed" not in exp: + print(f"Warning: expectation in {grading_file} missing required fields (text, passed, evidence): {exp}") + result["expectations"] = raw_expectations + + # Extract notes from user_notes_summary + notes_summary = grading.get("user_notes_summary", {}) + notes = [] + notes.extend(notes_summary.get("uncertainties", [])) + notes.extend(notes_summary.get("needs_review", [])) + notes.extend(notes_summary.get("workarounds", [])) + result["notes"] = notes + + results[config].append(result) + + return results + + +def aggregate_results(results: dict) -> dict: + """ + Aggregate run results into summary statistics. + + Returns run_summary with stats for each configuration and delta. + """ + run_summary = {} + configs = list(results.keys()) + + for config in configs: + runs = results.get(config, []) + + if not runs: + run_summary[config] = { + "pass_rate": {"mean": 0.0, "stddev": 0.0, "min": 0.0, "max": 0.0}, + "time_seconds": {"mean": 0.0, "stddev": 0.0, "min": 0.0, "max": 0.0}, + "tokens": {"mean": 0, "stddev": 0, "min": 0, "max": 0} + } + continue + + pass_rates = [r["pass_rate"] for r in runs] + times = [r["time_seconds"] for r in runs] + tokens = [r.get("tokens", 0) for r in runs] + + run_summary[config] = { + "pass_rate": calculate_stats(pass_rates), + "time_seconds": calculate_stats(times), + "tokens": calculate_stats(tokens) + } + + # Calculate delta between the first two configs (if two exist) + if len(configs) >= 2: + primary = run_summary.get(configs[0], {}) + baseline = run_summary.get(configs[1], {}) + else: + primary = run_summary.get(configs[0], {}) if configs else {} + baseline = {} + + delta_pass_rate = primary.get("pass_rate", {}).get("mean", 0) - baseline.get("pass_rate", {}).get("mean", 0) + delta_time = primary.get("time_seconds", {}).get("mean", 0) - baseline.get("time_seconds", {}).get("mean", 0) + delta_tokens = primary.get("tokens", {}).get("mean", 0) - baseline.get("tokens", {}).get("mean", 0) + + run_summary["delta"] = { + "pass_rate": f"{delta_pass_rate:+.2f}", + "time_seconds": f"{delta_time:+.1f}", + "tokens": f"{delta_tokens:+.0f}" + } + + return run_summary + + +def generate_benchmark(benchmark_dir: Path, skill_name: str = "", skill_path: str = "") -> dict: + """ + Generate complete benchmark.json from run results. + """ + results = load_run_results(benchmark_dir) + run_summary = aggregate_results(results) + + # Build runs array for benchmark.json + runs = [] + for config in results: + for result in results[config]: + runs.append({ + "eval_id": result["eval_id"], + "configuration": config, + "run_number": result["run_number"], + "result": { + "pass_rate": result["pass_rate"], + "passed": result["passed"], + "failed": result["failed"], + "total": result["total"], + "time_seconds": result["time_seconds"], + "tokens": result.get("tokens", 0), + "tool_calls": result.get("tool_calls", 0), + "errors": result.get("errors", 0) + }, + "expectations": result["expectations"], + "notes": result["notes"] + }) + + # Determine eval IDs from results + eval_ids = sorted(set( + r["eval_id"] + for config in results.values() + for r in config + )) + + benchmark = { + "metadata": { + "skill_name": skill_name or "", + "skill_path": skill_path or "", + "executor_model": "", + "analyzer_model": "", + "timestamp": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"), + "evals_run": eval_ids, + "runs_per_configuration": 3 + }, + "runs": runs, + "run_summary": run_summary, + "notes": [] # To be filled by analyzer + } + + return benchmark + + +def generate_markdown(benchmark: dict) -> str: + """Generate human-readable benchmark.md from benchmark data.""" + metadata = benchmark["metadata"] + run_summary = benchmark["run_summary"] + + # Determine config names (excluding "delta") + configs = [k for k in run_summary if k != "delta"] + config_a = configs[0] if len(configs) >= 1 else "config_a" + config_b = configs[1] if len(configs) >= 2 else "config_b" + label_a = config_a.replace("_", " ").title() + label_b = config_b.replace("_", " ").title() + + lines = [ + f"# Skill Benchmark: {metadata['skill_name']}", + "", + f"**Model**: {metadata['executor_model']}", + f"**Date**: {metadata['timestamp']}", + f"**Evals**: {', '.join(map(str, metadata['evals_run']))} ({metadata['runs_per_configuration']} runs each per configuration)", + "", + "## Summary", + "", + f"| Metric | {label_a} | {label_b} | Delta |", + "|--------|------------|---------------|-------|", + ] + + a_summary = run_summary.get(config_a, {}) + b_summary = run_summary.get(config_b, {}) + delta = run_summary.get("delta", {}) + + # Format pass rate + a_pr = a_summary.get("pass_rate", {}) + b_pr = b_summary.get("pass_rate", {}) + lines.append(f"| Pass Rate | {a_pr.get('mean', 0)*100:.0f}% ± {a_pr.get('stddev', 0)*100:.0f}% | {b_pr.get('mean', 0)*100:.0f}% ± {b_pr.get('stddev', 0)*100:.0f}% | {delta.get('pass_rate', '—')} |") + + # Format time + a_time = a_summary.get("time_seconds", {}) + b_time = b_summary.get("time_seconds", {}) + lines.append(f"| Time | {a_time.get('mean', 0):.1f}s ± {a_time.get('stddev', 0):.1f}s | {b_time.get('mean', 0):.1f}s ± {b_time.get('stddev', 0):.1f}s | {delta.get('time_seconds', '—')}s |") + + # Format tokens + a_tokens = a_summary.get("tokens", {}) + b_tokens = b_summary.get("tokens", {}) + lines.append(f"| Tokens | {a_tokens.get('mean', 0):.0f} ± {a_tokens.get('stddev', 0):.0f} | {b_tokens.get('mean', 0):.0f} ± {b_tokens.get('stddev', 0):.0f} | {delta.get('tokens', '—')} |") + + # Notes section + if benchmark.get("notes"): + lines.extend([ + "", + "## Notes", + "" + ]) + for note in benchmark["notes"]: + lines.append(f"- {note}") + + return "\n".join(lines) + + +def main(): + parser = argparse.ArgumentParser( + description="Aggregate benchmark run results into summary statistics" + ) + parser.add_argument( + "benchmark_dir", + type=Path, + help="Path to the benchmark directory" + ) + parser.add_argument( + "--skill-name", + default="", + help="Name of the skill being benchmarked" + ) + parser.add_argument( + "--skill-path", + default="", + help="Path to the skill being benchmarked" + ) + parser.add_argument( + "--output", "-o", + type=Path, + help="Output path for benchmark.json (default: /benchmark.json)" + ) + + args = parser.parse_args() + + if not args.benchmark_dir.exists(): + print(f"Directory not found: {args.benchmark_dir}") + sys.exit(1) + + # Generate benchmark + benchmark = generate_benchmark(args.benchmark_dir, args.skill_name, args.skill_path) + + # Determine output paths + output_json = args.output or (args.benchmark_dir / "benchmark.json") + output_md = output_json.with_suffix(".md") + + # Write benchmark.json + with open(output_json, "w") as f: + json.dump(benchmark, f, indent=2) + print(f"Generated: {output_json}") + + # Write benchmark.md + markdown = generate_markdown(benchmark) + with open(output_md, "w") as f: + f.write(markdown) + print(f"Generated: {output_md}") + + # Print summary + run_summary = benchmark["run_summary"] + configs = [k for k in run_summary if k != "delta"] + delta = run_summary.get("delta", {}) + + print(f"\nSummary:") + for config in configs: + pr = run_summary[config]["pass_rate"]["mean"] + label = config.replace("_", " ").title() + print(f" {label}: {pr*100:.1f}% pass rate") + print(f" Delta: {delta.get('pass_rate', '—')}") + + +if __name__ == "__main__": + main() diff --git a/.agents/skills/skill-creator/scripts/generate_report.py b/.agents/skills/skill-creator/scripts/generate_report.py new file mode 100644 index 0000000..959e30a --- /dev/null +++ b/.agents/skills/skill-creator/scripts/generate_report.py @@ -0,0 +1,326 @@ +#!/usr/bin/env python3 +"""Generate an HTML report from run_loop.py output. + +Takes the JSON output from run_loop.py and generates a visual HTML report +showing each description attempt with check/x for each test case. +Distinguishes between train and test queries. +""" + +import argparse +import html +import json +import sys +from pathlib import Path + + +def generate_html(data: dict, auto_refresh: bool = False, skill_name: str = "") -> str: + """Generate HTML report from loop output data. If auto_refresh is True, adds a meta refresh tag.""" + history = data.get("history", []) + holdout = data.get("holdout", 0) + title_prefix = html.escape(skill_name + " \u2014 ") if skill_name else "" + + # Get all unique queries from train and test sets, with should_trigger info + train_queries: list[dict] = [] + test_queries: list[dict] = [] + if history: + for r in history[0].get("train_results", history[0].get("results", [])): + train_queries.append({"query": r["query"], "should_trigger": r.get("should_trigger", True)}) + if history[0].get("test_results"): + for r in history[0].get("test_results", []): + test_queries.append({"query": r["query"], "should_trigger": r.get("should_trigger", True)}) + + refresh_tag = ' \n' if auto_refresh else "" + + html_parts = [""" + + + +""" + refresh_tag + """ """ + title_prefix + """Skill Description Optimization + + + + + + +

""" + title_prefix + """Skill Description Optimization

+
+ Optimizing your skill's description. This page updates automatically as Claude tests different versions of your skill's description. Each row is an iteration — a new description attempt. The columns show test queries: green checkmarks mean the skill triggered correctly (or correctly didn't trigger), red crosses mean it got it wrong. The "Train" score shows performance on queries used to improve the description; the "Test" score shows performance on held-out queries the optimizer hasn't seen. When it's done, Claude will apply the best-performing description to your skill. +
+"""] + + # Summary section + best_test_score = data.get('best_test_score') + best_train_score = data.get('best_train_score') + html_parts.append(f""" +
+

Original: {html.escape(data.get('original_description', 'N/A'))}

+

Best: {html.escape(data.get('best_description', 'N/A'))}

+

Best Score: {data.get('best_score', 'N/A')} {'(test)' if best_test_score else '(train)'}

+

Iterations: {data.get('iterations_run', 0)} | Train: {data.get('train_size', '?')} | Test: {data.get('test_size', '?')}

+
+""") + + # Legend + html_parts.append(""" +
+ Query columns: + Should trigger + Should NOT trigger + Train + Test +
+""") + + # Table header + html_parts.append(""" +
+ + + + + + + +""") + + # Add column headers for train queries + for qinfo in train_queries: + polarity = "positive-col" if qinfo["should_trigger"] else "negative-col" + html_parts.append(f' \n') + + # Add column headers for test queries (different color) + for qinfo in test_queries: + polarity = "positive-col" if qinfo["should_trigger"] else "negative-col" + html_parts.append(f' \n') + + html_parts.append(""" + + +""") + + # Find best iteration for highlighting + if test_queries: + best_iter = max(history, key=lambda h: h.get("test_passed") or 0).get("iteration") + else: + best_iter = max(history, key=lambda h: h.get("train_passed", h.get("passed", 0))).get("iteration") + + # Add rows for each iteration + for h in history: + iteration = h.get("iteration", "?") + train_passed = h.get("train_passed", h.get("passed", 0)) + train_total = h.get("train_total", h.get("total", 0)) + test_passed = h.get("test_passed") + test_total = h.get("test_total") + description = h.get("description", "") + train_results = h.get("train_results", h.get("results", [])) + test_results = h.get("test_results", []) + + # Create lookups for results by query + train_by_query = {r["query"]: r for r in train_results} + test_by_query = {r["query"]: r for r in test_results} if test_results else {} + + # Compute aggregate correct/total runs across all retries + def aggregate_runs(results: list[dict]) -> tuple[int, int]: + correct = 0 + total = 0 + for r in results: + runs = r.get("runs", 0) + triggers = r.get("triggers", 0) + total += runs + if r.get("should_trigger", True): + correct += triggers + else: + correct += runs - triggers + return correct, total + + train_correct, train_runs = aggregate_runs(train_results) + test_correct, test_runs = aggregate_runs(test_results) + + # Determine score classes + def score_class(correct: int, total: int) -> str: + if total > 0: + ratio = correct / total + if ratio >= 0.8: + return "score-good" + elif ratio >= 0.5: + return "score-ok" + return "score-bad" + + train_class = score_class(train_correct, train_runs) + test_class = score_class(test_correct, test_runs) + + row_class = "best-row" if iteration == best_iter else "" + + html_parts.append(f""" + + + + +""") + + # Add result for each train query + for qinfo in train_queries: + r = train_by_query.get(qinfo["query"], {}) + did_pass = r.get("pass", False) + triggers = r.get("triggers", 0) + runs = r.get("runs", 0) + + icon = "✓" if did_pass else "✗" + css_class = "pass" if did_pass else "fail" + + html_parts.append(f' \n') + + # Add result for each test query (with different background) + for qinfo in test_queries: + r = test_by_query.get(qinfo["query"], {}) + did_pass = r.get("pass", False) + triggers = r.get("triggers", 0) + runs = r.get("runs", 0) + + icon = "✓" if did_pass else "✗" + css_class = "pass" if did_pass else "fail" + + html_parts.append(f' \n') + + html_parts.append(" \n") + + html_parts.append(""" +
IterTrainTestDescription{html.escape(qinfo["query"])}{html.escape(qinfo["query"])}
{iteration}{train_correct}/{train_runs}{test_correct}/{test_runs}{html.escape(description)}{icon}{triggers}/{runs}{icon}{triggers}/{runs}
+
+""") + + html_parts.append(""" + + +""") + + return "".join(html_parts) + + +def main(): + parser = argparse.ArgumentParser(description="Generate HTML report from run_loop output") + parser.add_argument("input", help="Path to JSON output from run_loop.py (or - for stdin)") + parser.add_argument("-o", "--output", default=None, help="Output HTML file (default: stdout)") + parser.add_argument("--skill-name", default="", help="Skill name to include in the report title") + args = parser.parse_args() + + if args.input == "-": + data = json.load(sys.stdin) + else: + data = json.loads(Path(args.input).read_text()) + + html_output = generate_html(data, skill_name=args.skill_name) + + if args.output: + Path(args.output).write_text(html_output) + print(f"Report written to {args.output}", file=sys.stderr) + else: + print(html_output) + + +if __name__ == "__main__": + main() diff --git a/.agents/skills/skill-creator/scripts/improve_description.py b/.agents/skills/skill-creator/scripts/improve_description.py new file mode 100644 index 0000000..a270777 --- /dev/null +++ b/.agents/skills/skill-creator/scripts/improve_description.py @@ -0,0 +1,248 @@ +#!/usr/bin/env python3 +"""Improve a skill description based on eval results. + +Takes eval results (from run_eval.py) and generates an improved description +using Claude with extended thinking. +""" + +import argparse +import json +import re +import sys +from pathlib import Path + +import anthropic + +from scripts.utils import parse_skill_md + + +def improve_description( + client: anthropic.Anthropic, + skill_name: str, + skill_content: str, + current_description: str, + eval_results: dict, + history: list[dict], + model: str, + test_results: dict | None = None, + log_dir: Path | None = None, + iteration: int | None = None, +) -> str: + """Call Claude to improve the description based on eval results.""" + failed_triggers = [ + r for r in eval_results["results"] + if r["should_trigger"] and not r["pass"] + ] + false_triggers = [ + r for r in eval_results["results"] + if not r["should_trigger"] and not r["pass"] + ] + + # Build scores summary + train_score = f"{eval_results['summary']['passed']}/{eval_results['summary']['total']}" + if test_results: + test_score = f"{test_results['summary']['passed']}/{test_results['summary']['total']}" + scores_summary = f"Train: {train_score}, Test: {test_score}" + else: + scores_summary = f"Train: {train_score}" + + prompt = f"""You are optimizing a skill description for a Claude Code skill called "{skill_name}". A "skill" is sort of like a prompt, but with progressive disclosure -- there's a title and description that Claude sees when deciding whether to use the skill, and then if it does use the skill, it reads the .md file which has lots more details and potentially links to other resources in the skill folder like helper files and scripts and additional documentation or examples. + +The description appears in Claude's "available_skills" list. When a user sends a query, Claude decides whether to invoke the skill based solely on the title and on this description. Your goal is to write a description that triggers for relevant queries, and doesn't trigger for irrelevant ones. + +Here's the current description: + +"{current_description}" + + +Current scores ({scores_summary}): + +""" + if failed_triggers: + prompt += "FAILED TO TRIGGER (should have triggered but didn't):\n" + for r in failed_triggers: + prompt += f' - "{r["query"]}" (triggered {r["triggers"]}/{r["runs"]} times)\n' + prompt += "\n" + + if false_triggers: + prompt += "FALSE TRIGGERS (triggered but shouldn't have):\n" + for r in false_triggers: + prompt += f' - "{r["query"]}" (triggered {r["triggers"]}/{r["runs"]} times)\n' + prompt += "\n" + + if history: + prompt += "PREVIOUS ATTEMPTS (do NOT repeat these — try something structurally different):\n\n" + for h in history: + train_s = f"{h.get('train_passed', h.get('passed', 0))}/{h.get('train_total', h.get('total', 0))}" + test_s = f"{h.get('test_passed', '?')}/{h.get('test_total', '?')}" if h.get('test_passed') is not None else None + score_str = f"train={train_s}" + (f", test={test_s}" if test_s else "") + prompt += f'\n' + prompt += f'Description: "{h["description"]}"\n' + if "results" in h: + prompt += "Train results:\n" + for r in h["results"]: + status = "PASS" if r["pass"] else "FAIL" + prompt += f' [{status}] "{r["query"][:80]}" (triggered {r["triggers"]}/{r["runs"]})\n' + if h.get("note"): + prompt += f'Note: {h["note"]}\n' + prompt += "\n\n" + + prompt += f""" + +Skill content (for context on what the skill does): + +{skill_content} + + +Based on the failures, write a new and improved description that is more likely to trigger correctly. When I say "based on the failures", it's a bit of a tricky line to walk because we don't want to overfit to the specific cases you're seeing. So what I DON'T want you to do is produce an ever-expanding list of specific queries that this skill should or shouldn't trigger for. Instead, try to generalize from the failures to broader categories of user intent and situations where this skill would be useful or not useful. The reason for this is twofold: + +1. Avoid overfitting +2. The list might get loooong and it's injected into ALL queries and there might be a lot of skills, so we don't want to blow too much space on any given description. + +Concretely, your description should not be more than about 100-200 words, even if that comes at the cost of accuracy. + +Here are some tips that we've found to work well in writing these descriptions: +- The skill should be phrased in the imperative -- "Use this skill for" rather than "this skill does" +- The skill description should focus on the user's intent, what they are trying to achieve, vs. the implementation details of how the skill works. +- The description competes with other skills for Claude's attention — make it distinctive and immediately recognizable. +- If you're getting lots of failures after repeated attempts, change things up. Try different sentence structures or wordings. + +I'd encourage you to be creative and mix up the style in different iterations since you'll have multiple opportunities to try different approaches and we'll just grab the highest-scoring one at the end. + +Please respond with only the new description text in tags, nothing else.""" + + response = client.messages.create( + model=model, + max_tokens=16000, + thinking={ + "type": "enabled", + "budget_tokens": 10000, + }, + messages=[{"role": "user", "content": prompt}], + ) + + # Extract thinking and text from response + thinking_text = "" + text = "" + for block in response.content: + if block.type == "thinking": + thinking_text = block.thinking + elif block.type == "text": + text = block.text + + # Parse out the tags + match = re.search(r"(.*?)", text, re.DOTALL) + description = match.group(1).strip().strip('"') if match else text.strip().strip('"') + + # Log the transcript + transcript: dict = { + "iteration": iteration, + "prompt": prompt, + "thinking": thinking_text, + "response": text, + "parsed_description": description, + "char_count": len(description), + "over_limit": len(description) > 1024, + } + + # If over 1024 chars, ask the model to shorten it + if len(description) > 1024: + shorten_prompt = f"Your description is {len(description)} characters, which exceeds the hard 1024 character limit. Please rewrite it to be under 1024 characters while preserving the most important trigger words and intent coverage. Respond with only the new description in tags." + shorten_response = client.messages.create( + model=model, + max_tokens=16000, + thinking={ + "type": "enabled", + "budget_tokens": 10000, + }, + messages=[ + {"role": "user", "content": prompt}, + {"role": "assistant", "content": text}, + {"role": "user", "content": shorten_prompt}, + ], + ) + + shorten_thinking = "" + shorten_text = "" + for block in shorten_response.content: + if block.type == "thinking": + shorten_thinking = block.thinking + elif block.type == "text": + shorten_text = block.text + + match = re.search(r"(.*?)", shorten_text, re.DOTALL) + shortened = match.group(1).strip().strip('"') if match else shorten_text.strip().strip('"') + + transcript["rewrite_prompt"] = shorten_prompt + transcript["rewrite_thinking"] = shorten_thinking + transcript["rewrite_response"] = shorten_text + transcript["rewrite_description"] = shortened + transcript["rewrite_char_count"] = len(shortened) + description = shortened + + transcript["final_description"] = description + + if log_dir: + log_dir.mkdir(parents=True, exist_ok=True) + log_file = log_dir / f"improve_iter_{iteration or 'unknown'}.json" + log_file.write_text(json.dumps(transcript, indent=2)) + + return description + + +def main(): + parser = argparse.ArgumentParser(description="Improve a skill description based on eval results") + parser.add_argument("--eval-results", required=True, help="Path to eval results JSON (from run_eval.py)") + parser.add_argument("--skill-path", required=True, help="Path to skill directory") + parser.add_argument("--history", default=None, help="Path to history JSON (previous attempts)") + parser.add_argument("--model", required=True, help="Model for improvement") + parser.add_argument("--verbose", action="store_true", help="Print thinking to stderr") + args = parser.parse_args() + + skill_path = Path(args.skill_path) + if not (skill_path / "SKILL.md").exists(): + print(f"Error: No SKILL.md found at {skill_path}", file=sys.stderr) + sys.exit(1) + + eval_results = json.loads(Path(args.eval_results).read_text()) + history = [] + if args.history: + history = json.loads(Path(args.history).read_text()) + + name, _, content = parse_skill_md(skill_path) + current_description = eval_results["description"] + + if args.verbose: + print(f"Current: {current_description}", file=sys.stderr) + print(f"Score: {eval_results['summary']['passed']}/{eval_results['summary']['total']}", file=sys.stderr) + + client = anthropic.Anthropic() + new_description = improve_description( + client=client, + skill_name=name, + skill_content=content, + current_description=current_description, + eval_results=eval_results, + history=history, + model=args.model, + ) + + if args.verbose: + print(f"Improved: {new_description}", file=sys.stderr) + + # Output as JSON with both the new description and updated history + output = { + "description": new_description, + "history": history + [{ + "description": current_description, + "passed": eval_results["summary"]["passed"], + "failed": eval_results["summary"]["failed"], + "total": eval_results["summary"]["total"], + "results": eval_results["results"], + }], + } + print(json.dumps(output, indent=2)) + + +if __name__ == "__main__": + main() diff --git a/.agents/skills/skill-creator/scripts/package_skill.py b/.agents/skills/skill-creator/scripts/package_skill.py new file mode 100644 index 0000000..f48eac4 --- /dev/null +++ b/.agents/skills/skill-creator/scripts/package_skill.py @@ -0,0 +1,136 @@ +#!/usr/bin/env python3 +""" +Skill Packager - Creates a distributable .skill file of a skill folder + +Usage: + python utils/package_skill.py [output-directory] + +Example: + python utils/package_skill.py skills/public/my-skill + python utils/package_skill.py skills/public/my-skill ./dist +""" + +import fnmatch +import sys +import zipfile +from pathlib import Path +from scripts.quick_validate import validate_skill + +# Patterns to exclude when packaging skills. +EXCLUDE_DIRS = {"__pycache__", "node_modules"} +EXCLUDE_GLOBS = {"*.pyc"} +EXCLUDE_FILES = {".DS_Store"} +# Directories excluded only at the skill root (not when nested deeper). +ROOT_EXCLUDE_DIRS = {"evals"} + + +def should_exclude(rel_path: Path) -> bool: + """Check if a path should be excluded from packaging.""" + parts = rel_path.parts + if any(part in EXCLUDE_DIRS for part in parts): + return True + # rel_path is relative to skill_path.parent, so parts[0] is the skill + # folder name and parts[1] (if present) is the first subdir. + if len(parts) > 1 and parts[1] in ROOT_EXCLUDE_DIRS: + return True + name = rel_path.name + if name in EXCLUDE_FILES: + return True + return any(fnmatch.fnmatch(name, pat) for pat in EXCLUDE_GLOBS) + + +def package_skill(skill_path, output_dir=None): + """ + Package a skill folder into a .skill file. + + Args: + skill_path: Path to the skill folder + output_dir: Optional output directory for the .skill file (defaults to current directory) + + Returns: + Path to the created .skill file, or None if error + """ + skill_path = Path(skill_path).resolve() + + # Validate skill folder exists + if not skill_path.exists(): + print(f"❌ Error: Skill folder not found: {skill_path}") + return None + + if not skill_path.is_dir(): + print(f"❌ Error: Path is not a directory: {skill_path}") + return None + + # Validate SKILL.md exists + skill_md = skill_path / "SKILL.md" + if not skill_md.exists(): + print(f"❌ Error: SKILL.md not found in {skill_path}") + return None + + # Run validation before packaging + print("🔍 Validating skill...") + valid, message = validate_skill(skill_path) + if not valid: + print(f"❌ Validation failed: {message}") + print(" Please fix the validation errors before packaging.") + return None + print(f"✅ {message}\n") + + # Determine output location + skill_name = skill_path.name + if output_dir: + output_path = Path(output_dir).resolve() + output_path.mkdir(parents=True, exist_ok=True) + else: + output_path = Path.cwd() + + skill_filename = output_path / f"{skill_name}.skill" + + # Create the .skill file (zip format) + try: + with zipfile.ZipFile(skill_filename, 'w', zipfile.ZIP_DEFLATED) as zipf: + # Walk through the skill directory, excluding build artifacts + for file_path in skill_path.rglob('*'): + if not file_path.is_file(): + continue + arcname = file_path.relative_to(skill_path.parent) + if should_exclude(arcname): + print(f" Skipped: {arcname}") + continue + zipf.write(file_path, arcname) + print(f" Added: {arcname}") + + print(f"\n✅ Successfully packaged skill to: {skill_filename}") + return skill_filename + + except Exception as e: + print(f"❌ Error creating .skill file: {e}") + return None + + +def main(): + if len(sys.argv) < 2: + print("Usage: python utils/package_skill.py [output-directory]") + print("\nExample:") + print(" python utils/package_skill.py skills/public/my-skill") + print(" python utils/package_skill.py skills/public/my-skill ./dist") + sys.exit(1) + + skill_path = sys.argv[1] + output_dir = sys.argv[2] if len(sys.argv) > 2 else None + + print(f"📦 Packaging skill: {skill_path}") + if output_dir: + print(f" Output directory: {output_dir}") + print() + + result = package_skill(skill_path, output_dir) + + if result: + sys.exit(0) + else: + sys.exit(1) + + +if __name__ == "__main__": + main() diff --git a/.agents/skills/skill-creator/scripts/quick_validate.py b/.agents/skills/skill-creator/scripts/quick_validate.py new file mode 100644 index 0000000..ed8e1dd --- /dev/null +++ b/.agents/skills/skill-creator/scripts/quick_validate.py @@ -0,0 +1,103 @@ +#!/usr/bin/env python3 +""" +Quick validation script for skills - minimal version +""" + +import sys +import os +import re +import yaml +from pathlib import Path + +def validate_skill(skill_path): + """Basic validation of a skill""" + skill_path = Path(skill_path) + + # Check SKILL.md exists + skill_md = skill_path / 'SKILL.md' + if not skill_md.exists(): + return False, "SKILL.md not found" + + # Read and validate frontmatter + content = skill_md.read_text() + if not content.startswith('---'): + return False, "No YAML frontmatter found" + + # Extract frontmatter + match = re.match(r'^---\n(.*?)\n---', content, re.DOTALL) + if not match: + return False, "Invalid frontmatter format" + + frontmatter_text = match.group(1) + + # Parse YAML frontmatter + try: + frontmatter = yaml.safe_load(frontmatter_text) + if not isinstance(frontmatter, dict): + return False, "Frontmatter must be a YAML dictionary" + except yaml.YAMLError as e: + return False, f"Invalid YAML in frontmatter: {e}" + + # Define allowed properties + ALLOWED_PROPERTIES = {'name', 'description', 'license', 'allowed-tools', 'metadata', 'compatibility'} + + # Check for unexpected properties (excluding nested keys under metadata) + unexpected_keys = set(frontmatter.keys()) - ALLOWED_PROPERTIES + if unexpected_keys: + return False, ( + f"Unexpected key(s) in SKILL.md frontmatter: {', '.join(sorted(unexpected_keys))}. " + f"Allowed properties are: {', '.join(sorted(ALLOWED_PROPERTIES))}" + ) + + # Check required fields + if 'name' not in frontmatter: + return False, "Missing 'name' in frontmatter" + if 'description' not in frontmatter: + return False, "Missing 'description' in frontmatter" + + # Extract name for validation + name = frontmatter.get('name', '') + if not isinstance(name, str): + return False, f"Name must be a string, got {type(name).__name__}" + name = name.strip() + if name: + # Check naming convention (kebab-case: lowercase with hyphens) + if not re.match(r'^[a-z0-9-]+$', name): + return False, f"Name '{name}' should be kebab-case (lowercase letters, digits, and hyphens only)" + if name.startswith('-') or name.endswith('-') or '--' in name: + return False, f"Name '{name}' cannot start/end with hyphen or contain consecutive hyphens" + # Check name length (max 64 characters per spec) + if len(name) > 64: + return False, f"Name is too long ({len(name)} characters). Maximum is 64 characters." + + # Extract and validate description + description = frontmatter.get('description', '') + if not isinstance(description, str): + return False, f"Description must be a string, got {type(description).__name__}" + description = description.strip() + if description: + # Check for angle brackets + if '<' in description or '>' in description: + return False, "Description cannot contain angle brackets (< or >)" + # Check description length (max 1024 characters per spec) + if len(description) > 1024: + return False, f"Description is too long ({len(description)} characters). Maximum is 1024 characters." + + # Validate compatibility field if present (optional) + compatibility = frontmatter.get('compatibility', '') + if compatibility: + if not isinstance(compatibility, str): + return False, f"Compatibility must be a string, got {type(compatibility).__name__}" + if len(compatibility) > 500: + return False, f"Compatibility is too long ({len(compatibility)} characters). Maximum is 500 characters." + + return True, "Skill is valid!" + +if __name__ == "__main__": + if len(sys.argv) != 2: + print("Usage: python quick_validate.py ") + sys.exit(1) + + valid, message = validate_skill(sys.argv[1]) + print(message) + sys.exit(0 if valid else 1) \ No newline at end of file diff --git a/.agents/skills/skill-creator/scripts/run_eval.py b/.agents/skills/skill-creator/scripts/run_eval.py new file mode 100644 index 0000000..e58c70b --- /dev/null +++ b/.agents/skills/skill-creator/scripts/run_eval.py @@ -0,0 +1,310 @@ +#!/usr/bin/env python3 +"""Run trigger evaluation for a skill description. + +Tests whether a skill's description causes Claude to trigger (read the skill) +for a set of queries. Outputs results as JSON. +""" + +import argparse +import json +import os +import select +import subprocess +import sys +import time +import uuid +from concurrent.futures import ProcessPoolExecutor, as_completed +from pathlib import Path + +from scripts.utils import parse_skill_md + + +def find_project_root() -> Path: + """Find the project root by walking up from cwd looking for .claude/. + + Mimics how Claude Code discovers its project root, so the command file + we create ends up where claude -p will look for it. + """ + current = Path.cwd() + for parent in [current, *current.parents]: + if (parent / ".claude").is_dir(): + return parent + return current + + +def run_single_query( + query: str, + skill_name: str, + skill_description: str, + timeout: int, + project_root: str, + model: str | None = None, +) -> bool: + """Run a single query and return whether the skill was triggered. + + Creates a command file in .claude/commands/ so it appears in Claude's + available_skills list, then runs `claude -p` with the raw query. + Uses --include-partial-messages to detect triggering early from + stream events (content_block_start) rather than waiting for the + full assistant message, which only arrives after tool execution. + """ + unique_id = uuid.uuid4().hex[:8] + clean_name = f"{skill_name}-skill-{unique_id}" + project_commands_dir = Path(project_root) / ".claude" / "commands" + command_file = project_commands_dir / f"{clean_name}.md" + + try: + project_commands_dir.mkdir(parents=True, exist_ok=True) + # Use YAML block scalar to avoid breaking on quotes in description + indented_desc = "\n ".join(skill_description.split("\n")) + command_content = ( + f"---\n" + f"description: |\n" + f" {indented_desc}\n" + f"---\n\n" + f"# {skill_name}\n\n" + f"This skill handles: {skill_description}\n" + ) + command_file.write_text(command_content) + + cmd = [ + "claude", + "-p", query, + "--output-format", "stream-json", + "--verbose", + "--include-partial-messages", + ] + if model: + cmd.extend(["--model", model]) + + # Remove CLAUDECODE env var to allow nesting claude -p inside a + # Claude Code session. The guard is for interactive terminal conflicts; + # programmatic subprocess usage is safe. + env = {k: v for k, v in os.environ.items() if k != "CLAUDECODE"} + + process = subprocess.Popen( + cmd, + stdout=subprocess.PIPE, + stderr=subprocess.DEVNULL, + cwd=project_root, + env=env, + ) + + triggered = False + start_time = time.time() + buffer = "" + # Track state for stream event detection + pending_tool_name = None + accumulated_json = "" + + try: + while time.time() - start_time < timeout: + if process.poll() is not None: + remaining = process.stdout.read() + if remaining: + buffer += remaining.decode("utf-8", errors="replace") + break + + ready, _, _ = select.select([process.stdout], [], [], 1.0) + if not ready: + continue + + chunk = os.read(process.stdout.fileno(), 8192) + if not chunk: + break + buffer += chunk.decode("utf-8", errors="replace") + + while "\n" in buffer: + line, buffer = buffer.split("\n", 1) + line = line.strip() + if not line: + continue + + try: + event = json.loads(line) + except json.JSONDecodeError: + continue + + # Early detection via stream events + if event.get("type") == "stream_event": + se = event.get("event", {}) + se_type = se.get("type", "") + + if se_type == "content_block_start": + cb = se.get("content_block", {}) + if cb.get("type") == "tool_use": + tool_name = cb.get("name", "") + if tool_name in ("Skill", "Read"): + pending_tool_name = tool_name + accumulated_json = "" + else: + return False + + elif se_type == "content_block_delta" and pending_tool_name: + delta = se.get("delta", {}) + if delta.get("type") == "input_json_delta": + accumulated_json += delta.get("partial_json", "") + if clean_name in accumulated_json: + return True + + elif se_type in ("content_block_stop", "message_stop"): + if pending_tool_name: + return clean_name in accumulated_json + if se_type == "message_stop": + return False + + # Fallback: full assistant message + elif event.get("type") == "assistant": + message = event.get("message", {}) + for content_item in message.get("content", []): + if content_item.get("type") != "tool_use": + continue + tool_name = content_item.get("name", "") + tool_input = content_item.get("input", {}) + if tool_name == "Skill" and clean_name in tool_input.get("skill", ""): + triggered = True + elif tool_name == "Read" and clean_name in tool_input.get("file_path", ""): + triggered = True + return triggered + + elif event.get("type") == "result": + return triggered + finally: + # Clean up process on any exit path (return, exception, timeout) + if process.poll() is None: + process.kill() + process.wait() + + return triggered + finally: + if command_file.exists(): + command_file.unlink() + + +def run_eval( + eval_set: list[dict], + skill_name: str, + description: str, + num_workers: int, + timeout: int, + project_root: Path, + runs_per_query: int = 1, + trigger_threshold: float = 0.5, + model: str | None = None, +) -> dict: + """Run the full eval set and return results.""" + results = [] + + with ProcessPoolExecutor(max_workers=num_workers) as executor: + future_to_info = {} + for item in eval_set: + for run_idx in range(runs_per_query): + future = executor.submit( + run_single_query, + item["query"], + skill_name, + description, + timeout, + str(project_root), + model, + ) + future_to_info[future] = (item, run_idx) + + query_triggers: dict[str, list[bool]] = {} + query_items: dict[str, dict] = {} + for future in as_completed(future_to_info): + item, _ = future_to_info[future] + query = item["query"] + query_items[query] = item + if query not in query_triggers: + query_triggers[query] = [] + try: + query_triggers[query].append(future.result()) + except Exception as e: + print(f"Warning: query failed: {e}", file=sys.stderr) + query_triggers[query].append(False) + + for query, triggers in query_triggers.items(): + item = query_items[query] + trigger_rate = sum(triggers) / len(triggers) + should_trigger = item["should_trigger"] + if should_trigger: + did_pass = trigger_rate >= trigger_threshold + else: + did_pass = trigger_rate < trigger_threshold + results.append({ + "query": query, + "should_trigger": should_trigger, + "trigger_rate": trigger_rate, + "triggers": sum(triggers), + "runs": len(triggers), + "pass": did_pass, + }) + + passed = sum(1 for r in results if r["pass"]) + total = len(results) + + return { + "skill_name": skill_name, + "description": description, + "results": results, + "summary": { + "total": total, + "passed": passed, + "failed": total - passed, + }, + } + + +def main(): + parser = argparse.ArgumentParser(description="Run trigger evaluation for a skill description") + parser.add_argument("--eval-set", required=True, help="Path to eval set JSON file") + parser.add_argument("--skill-path", required=True, help="Path to skill directory") + parser.add_argument("--description", default=None, help="Override description to test") + parser.add_argument("--num-workers", type=int, default=10, help="Number of parallel workers") + parser.add_argument("--timeout", type=int, default=30, help="Timeout per query in seconds") + parser.add_argument("--runs-per-query", type=int, default=3, help="Number of runs per query") + parser.add_argument("--trigger-threshold", type=float, default=0.5, help="Trigger rate threshold") + parser.add_argument("--model", default=None, help="Model to use for claude -p (default: user's configured model)") + parser.add_argument("--verbose", action="store_true", help="Print progress to stderr") + args = parser.parse_args() + + eval_set = json.loads(Path(args.eval_set).read_text()) + skill_path = Path(args.skill_path) + + if not (skill_path / "SKILL.md").exists(): + print(f"Error: No SKILL.md found at {skill_path}", file=sys.stderr) + sys.exit(1) + + name, original_description, content = parse_skill_md(skill_path) + description = args.description or original_description + project_root = find_project_root() + + if args.verbose: + print(f"Evaluating: {description}", file=sys.stderr) + + output = run_eval( + eval_set=eval_set, + skill_name=name, + description=description, + num_workers=args.num_workers, + timeout=args.timeout, + project_root=project_root, + runs_per_query=args.runs_per_query, + trigger_threshold=args.trigger_threshold, + model=args.model, + ) + + if args.verbose: + summary = output["summary"] + print(f"Results: {summary['passed']}/{summary['total']} passed", file=sys.stderr) + for r in output["results"]: + status = "PASS" if r["pass"] else "FAIL" + rate_str = f"{r['triggers']}/{r['runs']}" + print(f" [{status}] rate={rate_str} expected={r['should_trigger']}: {r['query'][:70]}", file=sys.stderr) + + print(json.dumps(output, indent=2)) + + +if __name__ == "__main__": + main() diff --git a/.agents/skills/skill-creator/scripts/run_loop.py b/.agents/skills/skill-creator/scripts/run_loop.py new file mode 100644 index 0000000..36f9b4e --- /dev/null +++ b/.agents/skills/skill-creator/scripts/run_loop.py @@ -0,0 +1,332 @@ +#!/usr/bin/env python3 +"""Run the eval + improve loop until all pass or max iterations reached. + +Combines run_eval.py and improve_description.py in a loop, tracking history +and returning the best description found. Supports train/test split to prevent +overfitting. +""" + +import argparse +import json +import random +import sys +import tempfile +import time +import webbrowser +from pathlib import Path + +import anthropic + +from scripts.generate_report import generate_html +from scripts.improve_description import improve_description +from scripts.run_eval import find_project_root, run_eval +from scripts.utils import parse_skill_md + + +def split_eval_set(eval_set: list[dict], holdout: float, seed: int = 42) -> tuple[list[dict], list[dict]]: + """Split eval set into train and test sets, stratified by should_trigger.""" + random.seed(seed) + + # Separate by should_trigger + trigger = [e for e in eval_set if e["should_trigger"]] + no_trigger = [e for e in eval_set if not e["should_trigger"]] + + # Shuffle each group + random.shuffle(trigger) + random.shuffle(no_trigger) + + # Calculate split points + n_trigger_test = max(1, int(len(trigger) * holdout)) + n_no_trigger_test = max(1, int(len(no_trigger) * holdout)) + + # Split + test_set = trigger[:n_trigger_test] + no_trigger[:n_no_trigger_test] + train_set = trigger[n_trigger_test:] + no_trigger[n_no_trigger_test:] + + return train_set, test_set + + +def run_loop( + eval_set: list[dict], + skill_path: Path, + description_override: str | None, + num_workers: int, + timeout: int, + max_iterations: int, + runs_per_query: int, + trigger_threshold: float, + holdout: float, + model: str, + verbose: bool, + live_report_path: Path | None = None, + log_dir: Path | None = None, +) -> dict: + """Run the eval + improvement loop.""" + project_root = find_project_root() + name, original_description, content = parse_skill_md(skill_path) + current_description = description_override or original_description + + # Split into train/test if holdout > 0 + if holdout > 0: + train_set, test_set = split_eval_set(eval_set, holdout) + if verbose: + print(f"Split: {len(train_set)} train, {len(test_set)} test (holdout={holdout})", file=sys.stderr) + else: + train_set = eval_set + test_set = [] + + client = anthropic.Anthropic() + history = [] + exit_reason = "unknown" + + for iteration in range(1, max_iterations + 1): + if verbose: + print(f"\n{'='*60}", file=sys.stderr) + print(f"Iteration {iteration}/{max_iterations}", file=sys.stderr) + print(f"Description: {current_description}", file=sys.stderr) + print(f"{'='*60}", file=sys.stderr) + + # Evaluate train + test together in one batch for parallelism + all_queries = train_set + test_set + t0 = time.time() + all_results = run_eval( + eval_set=all_queries, + skill_name=name, + description=current_description, + num_workers=num_workers, + timeout=timeout, + project_root=project_root, + runs_per_query=runs_per_query, + trigger_threshold=trigger_threshold, + model=model, + ) + eval_elapsed = time.time() - t0 + + # Split results back into train/test by matching queries + train_queries_set = {q["query"] for q in train_set} + train_result_list = [r for r in all_results["results"] if r["query"] in train_queries_set] + test_result_list = [r for r in all_results["results"] if r["query"] not in train_queries_set] + + train_passed = sum(1 for r in train_result_list if r["pass"]) + train_total = len(train_result_list) + train_summary = {"passed": train_passed, "failed": train_total - train_passed, "total": train_total} + train_results = {"results": train_result_list, "summary": train_summary} + + if test_set: + test_passed = sum(1 for r in test_result_list if r["pass"]) + test_total = len(test_result_list) + test_summary = {"passed": test_passed, "failed": test_total - test_passed, "total": test_total} + test_results = {"results": test_result_list, "summary": test_summary} + else: + test_results = None + test_summary = None + + history.append({ + "iteration": iteration, + "description": current_description, + "train_passed": train_summary["passed"], + "train_failed": train_summary["failed"], + "train_total": train_summary["total"], + "train_results": train_results["results"], + "test_passed": test_summary["passed"] if test_summary else None, + "test_failed": test_summary["failed"] if test_summary else None, + "test_total": test_summary["total"] if test_summary else None, + "test_results": test_results["results"] if test_results else None, + # For backward compat with report generator + "passed": train_summary["passed"], + "failed": train_summary["failed"], + "total": train_summary["total"], + "results": train_results["results"], + }) + + # Write live report if path provided + if live_report_path: + partial_output = { + "original_description": original_description, + "best_description": current_description, + "best_score": "in progress", + "iterations_run": len(history), + "holdout": holdout, + "train_size": len(train_set), + "test_size": len(test_set), + "history": history, + } + live_report_path.write_text(generate_html(partial_output, auto_refresh=True, skill_name=name)) + + if verbose: + def print_eval_stats(label, results, elapsed): + pos = [r for r in results if r["should_trigger"]] + neg = [r for r in results if not r["should_trigger"]] + tp = sum(r["triggers"] for r in pos) + pos_runs = sum(r["runs"] for r in pos) + fn = pos_runs - tp + fp = sum(r["triggers"] for r in neg) + neg_runs = sum(r["runs"] for r in neg) + tn = neg_runs - fp + total = tp + tn + fp + fn + precision = tp / (tp + fp) if (tp + fp) > 0 else 1.0 + recall = tp / (tp + fn) if (tp + fn) > 0 else 1.0 + accuracy = (tp + tn) / total if total > 0 else 0.0 + print(f"{label}: {tp+tn}/{total} correct, precision={precision:.0%} recall={recall:.0%} accuracy={accuracy:.0%} ({elapsed:.1f}s)", file=sys.stderr) + for r in results: + status = "PASS" if r["pass"] else "FAIL" + rate_str = f"{r['triggers']}/{r['runs']}" + print(f" [{status}] rate={rate_str} expected={r['should_trigger']}: {r['query'][:60]}", file=sys.stderr) + + print_eval_stats("Train", train_results["results"], eval_elapsed) + if test_summary: + print_eval_stats("Test ", test_results["results"], 0) + + if train_summary["failed"] == 0: + exit_reason = f"all_passed (iteration {iteration})" + if verbose: + print(f"\nAll train queries passed on iteration {iteration}!", file=sys.stderr) + break + + if iteration == max_iterations: + exit_reason = f"max_iterations ({max_iterations})" + if verbose: + print(f"\nMax iterations reached ({max_iterations}).", file=sys.stderr) + break + + # Improve the description based on train results + if verbose: + print(f"\nImproving description...", file=sys.stderr) + + t0 = time.time() + # Strip test scores from history so improvement model can't see them + blinded_history = [ + {k: v for k, v in h.items() if not k.startswith("test_")} + for h in history + ] + new_description = improve_description( + client=client, + skill_name=name, + skill_content=content, + current_description=current_description, + eval_results=train_results, + history=blinded_history, + model=model, + log_dir=log_dir, + iteration=iteration, + ) + improve_elapsed = time.time() - t0 + + if verbose: + print(f"Proposed ({improve_elapsed:.1f}s): {new_description}", file=sys.stderr) + + current_description = new_description + + # Find the best iteration by TEST score (or train if no test set) + if test_set: + best = max(history, key=lambda h: h["test_passed"] or 0) + best_score = f"{best['test_passed']}/{best['test_total']}" + else: + best = max(history, key=lambda h: h["train_passed"]) + best_score = f"{best['train_passed']}/{best['train_total']}" + + if verbose: + print(f"\nExit reason: {exit_reason}", file=sys.stderr) + print(f"Best score: {best_score} (iteration {best['iteration']})", file=sys.stderr) + + return { + "exit_reason": exit_reason, + "original_description": original_description, + "best_description": best["description"], + "best_score": best_score, + "best_train_score": f"{best['train_passed']}/{best['train_total']}", + "best_test_score": f"{best['test_passed']}/{best['test_total']}" if test_set else None, + "final_description": current_description, + "iterations_run": len(history), + "holdout": holdout, + "train_size": len(train_set), + "test_size": len(test_set), + "history": history, + } + + +def main(): + parser = argparse.ArgumentParser(description="Run eval + improve loop") + parser.add_argument("--eval-set", required=True, help="Path to eval set JSON file") + parser.add_argument("--skill-path", required=True, help="Path to skill directory") + parser.add_argument("--description", default=None, help="Override starting description") + parser.add_argument("--num-workers", type=int, default=10, help="Number of parallel workers") + parser.add_argument("--timeout", type=int, default=30, help="Timeout per query in seconds") + parser.add_argument("--max-iterations", type=int, default=5, help="Max improvement iterations") + parser.add_argument("--runs-per-query", type=int, default=3, help="Number of runs per query") + parser.add_argument("--trigger-threshold", type=float, default=0.5, help="Trigger rate threshold") + parser.add_argument("--holdout", type=float, default=0.4, help="Fraction of eval set to hold out for testing (0 to disable)") + parser.add_argument("--model", required=True, help="Model for improvement") + parser.add_argument("--verbose", action="store_true", help="Print progress to stderr") + parser.add_argument("--report", default="auto", help="Generate HTML report at this path (default: 'auto' for temp file, 'none' to disable)") + parser.add_argument("--results-dir", default=None, help="Save all outputs (results.json, report.html, log.txt) to a timestamped subdirectory here") + args = parser.parse_args() + + eval_set = json.loads(Path(args.eval_set).read_text()) + skill_path = Path(args.skill_path) + + if not (skill_path / "SKILL.md").exists(): + print(f"Error: No SKILL.md found at {skill_path}", file=sys.stderr) + sys.exit(1) + + name, _, _ = parse_skill_md(skill_path) + + # Set up live report path + if args.report != "none": + if args.report == "auto": + timestamp = time.strftime("%Y%m%d_%H%M%S") + live_report_path = Path(tempfile.gettempdir()) / f"skill_description_report_{skill_path.name}_{timestamp}.html" + else: + live_report_path = Path(args.report) + # Open the report immediately so the user can watch + live_report_path.write_text("

Starting optimization loop...

") + webbrowser.open(str(live_report_path)) + else: + live_report_path = None + + # Determine output directory (create before run_loop so logs can be written) + if args.results_dir: + timestamp = time.strftime("%Y-%m-%d_%H%M%S") + results_dir = Path(args.results_dir) / timestamp + results_dir.mkdir(parents=True, exist_ok=True) + else: + results_dir = None + + log_dir = results_dir / "logs" if results_dir else None + + output = run_loop( + eval_set=eval_set, + skill_path=skill_path, + description_override=args.description, + num_workers=args.num_workers, + timeout=args.timeout, + max_iterations=args.max_iterations, + runs_per_query=args.runs_per_query, + trigger_threshold=args.trigger_threshold, + holdout=args.holdout, + model=args.model, + verbose=args.verbose, + live_report_path=live_report_path, + log_dir=log_dir, + ) + + # Save JSON output + json_output = json.dumps(output, indent=2) + print(json_output) + if results_dir: + (results_dir / "results.json").write_text(json_output) + + # Write final HTML report (without auto-refresh) + if live_report_path: + live_report_path.write_text(generate_html(output, auto_refresh=False, skill_name=name)) + print(f"\nReport: {live_report_path}", file=sys.stderr) + + if results_dir and live_report_path: + (results_dir / "report.html").write_text(generate_html(output, auto_refresh=False, skill_name=name)) + + if results_dir: + print(f"Results saved to: {results_dir}", file=sys.stderr) + + +if __name__ == "__main__": + main() diff --git a/.agents/skills/skill-creator/scripts/utils.py b/.agents/skills/skill-creator/scripts/utils.py new file mode 100644 index 0000000..51b6a07 --- /dev/null +++ b/.agents/skills/skill-creator/scripts/utils.py @@ -0,0 +1,47 @@ +"""Shared utilities for skill-creator scripts.""" + +from pathlib import Path + + + +def parse_skill_md(skill_path: Path) -> tuple[str, str, str]: + """Parse a SKILL.md file, returning (name, description, full_content).""" + content = (skill_path / "SKILL.md").read_text() + lines = content.split("\n") + + if lines[0].strip() != "---": + raise ValueError("SKILL.md missing frontmatter (no opening ---)") + + end_idx = None + for i, line in enumerate(lines[1:], start=1): + if line.strip() == "---": + end_idx = i + break + + if end_idx is None: + raise ValueError("SKILL.md missing frontmatter (no closing ---)") + + name = "" + description = "" + frontmatter_lines = lines[1:end_idx] + i = 0 + while i < len(frontmatter_lines): + line = frontmatter_lines[i] + if line.startswith("name:"): + name = line[len("name:"):].strip().strip('"').strip("'") + elif line.startswith("description:"): + value = line[len("description:"):].strip() + # Handle YAML multiline indicators (>, |, >-, |-) + if value in (">", "|", ">-", "|-"): + continuation_lines: list[str] = [] + i += 1 + while i < len(frontmatter_lines) and (frontmatter_lines[i].startswith(" ") or frontmatter_lines[i].startswith("\t")): + continuation_lines.append(frontmatter_lines[i].strip()) + i += 1 + description = " ".join(continuation_lines) + continue + else: + description = value.strip('"').strip("'") + i += 1 + + return name, description, content diff --git a/14-2026年2月11日-XAwindows转发/2026年2月11日-代理方案.md b/14-2026年2月11日-XAwindows转发/2026年2月11日-代理方案.md new file mode 100644 index 0000000..cf6a5eb --- /dev/null +++ b/14-2026年2月11日-XAwindows转发/2026年2月11日-代理方案.md @@ -0,0 +1,287 @@ +完全正确!既然主机B可以直接访问主机C(同局域网),那么**只需要在主机B上配置端口转发**即可,无需在主机A和主机C上安装任何软件。 [github](https://github.com/ginuerzh/gost/issues/1027) + +## 简化方案:仅配置主机B + +### 场景重新分析 + +主机B作为中转枢纽,提供三个端口转发服务: +1. 内网端口 → 主机A:39000(供主机C使用) +2. 内网端口 → 主机A:1999(供主机C使用) +3. 公网端口 → 主机C:1998(供主机A使用) + +### 主机B完整配置(Windows Server) + +#### 1. 下载Gost + +```bash +# 从 https://github.com/go-gost/gost/releases 下载Windows版本 +# 解压到 C:\gost\ +``` + +#### 2. 创建配置文件 + +在 `C:\gost\` 目录创建 `gost.yaml`: + +```yaml +services: + # 服务1: 主机C访问主机A的39000端口(TCP) + # 主机C连接 192.168.10.1:39000 + - name: forward-c-to-a-39000 + addr: 192.168.10.1:39000 + handler: + type: tcp + listener: + type: tcp + forwarder: + nodes: + - name: host-a-39000 + addr: 144.7.97.70:39000 + + # 服务2: 主机C访问主机A的1999端口(HTTP) + # 主机C连接 192.168.10.1:1999 或 http://192.168.10.1:1999 + - name: forward-c-to-a-1999 + addr: 192.168.10.1:1999 + handler: + type: tcp + listener: + type: tcp + forwarder: + nodes: + - name: host-a-1999 + addr: 144.7.97.70:1999 + + # 服务3: 主机A访问主机C的1998端口(HTTP) + # 主机A连接 144.7.8.50:11998 或 http://144.7.8.50:11998 + - name: forward-a-to-c-1998 + addr: 144.7.8.50:11998 + handler: + type: tcp + listener: + type: tcp + forwarder: + nodes: + - name: host-c-1998 + addr: 192.168.10.2:1998 +``` + +#### 3. 测试配置 + +```bash +# 在PowerShell或CMD中测试运行 +cd C:\gost +.\gost.exe -C gost.yaml + +# 观察输出,确认没有错误 +# 看到类似以下输出表示成功: +# 2026/02/11 11:26:00 forward-c-to-a-39000: listening on 192.168.10.1:39000 +# 2026/02/11 11:26:00 forward-c-to-a-1999: listening on 192.168.10.1:1999 +# 2026/02/11 11:26:00 forward-a-to-c-1998: listening on 144.7.8.50:11998 +``` + +如果测试正常,按 `Ctrl+C` 停止,继续下一步。 + +#### 4. 使用NSSM注册为Windows服务 + +```bash +# 下载NSSM: http://www.nssm.cc/download +# 解压到 C:\nssm\ + +# 以管理员身份打开CMD或PowerShell +cd C:\nssm\win64 + +# 安装服务 +nssm.exe install GostService + +# 在弹出的NSSM窗口中配置: +# Application标签页: +# Path: C:\gost\gost.exe +# Startup directory: C:\gost +# Arguments: -C gost.yaml +# +# Details标签页: +# Display name: Gost Port Forwarding Service +# Description: Gost端口转发服务 +# +# 点击 Install service +``` + +#### 5. 启动服务 + +```bash +# 启动服务 +nssm start GostService + +# 查看服务状态 +nssm status GostService + +# 如果需要,可以查看服务是否在运行 +sc query GostService +``` + +#### 6. 服务管理命令 + +```bash +# 启动服务 +nssm start GostService + +# 停止服务 +nssm stop GostService + +# 重启服务(修改配置后使用) +nssm restart GostService + +# 查看服务状态 +nssm status GostService + +# 编辑服务配置 +nssm edit GostService + +# 查看服务日志(在服务属性中可配置日志输出路径) +nssm edit GostService +# 在I/O标签页可以设置: +# Output (stdout): C:\gost\logs\gost.log +# Error (stderr): C:\gost\logs\gost-error.log + +# 删除服务(如果需要重新配置) +nssm stop GostService +nssm remove GostService confirm +``` + +### 防火墙配置 + +在主机B的Windows防火墙中添加入站规则: + +```powershell +# 以管理员身份运行PowerShell + +# 允许39000端口(内网访问) +New-NetFirewallRule -DisplayName "Gost-39000" -Direction Inbound -LocalPort 39000 -Protocol TCP -Action Allow + +# 允许1999端口(内网访问) +New-NetFirewallRule -DisplayName "Gost-1999" -Direction Inbound -LocalPort 1999 -Protocol TCP -Action Allow + +# 允许11998端口(公网访问) +New-NetFirewallRule -DisplayName "Gost-11998" -Direction Inbound -LocalPort 11998 -Protocol TCP -Action Allow +``` + +或者通过图形界面: +1. 打开 `Windows Defender 防火墙` → `高级设置` +2. 点击 `入站规则` → `新建规则` +3. 选择 `端口` → `TCP` → 输入端口号 `39000,1999,11998` +4. 选择 `允许连接` → 完成 + +## 使用方式 + +### 需求1:主机C访问主机A的39000端口(TCP) + +在主机C上: +```bash +# 连接到主机B的内网IP +telnet 192.168.10.1 39000 + +# 或使用你的应用程序连接 +# 目标地址: 192.168.10.1:39000 +``` + +### 需求2:主机C访问主机A的1999端口(HTTP) + +在主机C上: +```bash +# 浏览器访问 +http://192.168.10.1:1999 + +# 或使用curl +curl http://192.168.10.1:1999 + +# 或使用你的应用程序 +# 目标地址: 192.168.10.1:1999 +``` + +### 需求3:主机A访问主机C的1998端口(HTTP) + +在主机A上: +```bash +# 访问主机B的公网IP +curl http://144.7.8.50:11998 + +# 或使用浏览器 +http://144.7.8.50:11998 + +# 实际流量路径:主机A → 144.7.8.50:11998 → 192.168.10.2:1998 +``` + +## 验证配置 + +### 在主机B上验证服务是否运行 + +```powershell +# 查看Gost进程 +tasklist | findstr gost + +# 查看监听端口 +netstat -ano | findstr "39000" +netstat -ano | findstr "1999" +netstat -ano | findstr "11998" + +# 应该能看到类似输出: +# TCP 192.168.10.1:39000 0.0.0.0:0 LISTENING [PID] +# TCP 192.168.10.1:1999 0.0.0.0:0 LISTENING [PID] +# TCP 144.7.8.50:11998 0.0.0.0:0 LISTENING [PID] +``` + +### 测试连通性 + +在主机B上进行本地测试: + +```powershell +# 测试到主机A的连接(需要确保主机A的服务在运行) +Test-NetConnection -ComputerName 144.7.97.70 -Port 39000 +Test-NetConnection -ComputerName 144.7.97.70 -Port 1999 + +# 测试到主机C的连接(需要确保主机C的1998端口服务在运行) +Test-NetConnection -ComputerName 192.168.10.2 -Port 1998 +``` + +## 配置优化建议 + +如果需要添加日志功能,可以修改配置文件: + +```yaml +log: + level: info + format: json + output: C:\gost\logs\gost.log + +services: + # ... 其他配置保持不变 +``` + +## 故障排查 + +如果遇到问题: + +1. **检查Gost服务状态**: +```bash +nssm status GostService +``` + +2. **查看Gost日志**(如果配置了日志输出): +```bash +type C:\gost\logs\gost.log +type C:\gost\logs\gost-error.log +``` + +3. **手动运行查看错误**: +```bash +cd C:\gost +.\gost.exe -C gost.yaml -L debug +``` + +4. **检查端口占用冲突**: +```powershell +netstat -ano | findstr "39000" +netstat -ano | findstr "1999" +netstat -ano | findstr "11998" +``` + +这个简化方案只需要在主机B上操作,维护更简单,性能也更好! [nephen](https://www.nephen.cn/posts/4669df2a/) \ No newline at end of file diff --git a/14-2026年2月11日-XAwindows转发/gost.yaml b/14-2026年2月11日-XAwindows转发/gost.yaml index e69de29..b4585fa 100644 --- a/14-2026年2月11日-XAwindows转发/gost.yaml +++ b/14-2026年2月11日-XAwindows转发/gost.yaml @@ -0,0 +1,45 @@ +log: + level: info + format: json + output: C:\gost\logs\gost.log + + +services: + # 服务1: 主机C访问主机A的39000端口(TCP) + # 主机C连接 192.168.10.1:39000 + - name: forward-c-to-a-39000 + addr: 192.168.10.1:39000 + handler: + type: tcp + listener: + type: tcp + forwarder: + nodes: + - name: host-a-39000 + addr: 144.7.97.70:39000 + + # 服务2: 主机C访问主机A的1999端口(HTTP) + # 主机C连接 192.168.10.1:1999 或 http://192.168.10.1:1999 + - name: forward-c-to-a-1999 + addr: 192.168.10.1:1999 + handler: + type: tcp + listener: + type: tcp + forwarder: + nodes: + - name: host-a-1999 + addr: 144.7.97.70:1999 + + # 服务3: 主机A访问主机C的59014端口(HTTP) + # 主机A连接 144.7.8.50:59014 或 http://144.7.8.50:59014 + - name: forward-a-to-c-59014 + addr: 144.7.8.50:59014 + handler: + type: tcp + listener: + type: tcp + forwarder: + nodes: + - name: host-c-59014 + addr: 192.168.10.2:59014 \ No newline at end of file diff --git a/15-CICD工具选型/1-开源工具选型.md b/15-CICD工具选型/1-开源工具选型.md new file mode 100644 index 0000000..a72e8a4 --- /dev/null +++ b/15-CICD工具选型/1-开源工具选型.md @@ -0,0 +1,135 @@ +我现在想要深入的调研 每年构建数量在10万次左右的CICD工具,要求集成性能较强 +1. 构建能力 + 1. 对多语言构建的要求较强 + 2. 多版本的node + 3. 多版本的Java构建 + 4. 支持maven并发构建 + 5. 构建缓存支持较好 + 6. 支持多分支构建 + 6. 至此gravvl vm构建 +2. 灵活的构建参数 +3. 灵活的服务器调度 +4. 需要又灵活的集成策略 + 1. 构建信息需要向外传递 +5. 主流的脚本语法 +6. 良好的文档、生态支持 +7. 有接口暴露API,能够进行二次开发 +8. 支持私有化部署 + +最好是开源免费的CI CD工具,也可以对比付费的构建工具 如TeamCity等, 我们现在使用的是Jenkins工具。 + +请你根据我的上述实际需求,整理一份精确且丰富的调研需求prompt,用于发起提问 + + + +## CI/CD 选型调研 Prompt(10万次/年构建规模,偏私有化与强集成) + +请你以“企业级 CI/CD 平台架构师 + DevOps 专家”的视角,针对**每年约 10 万次构建**(约 270 次/天,峰值可能更高)的场景,输出一份**可落地的 CI/CD 工具选型调研报告**与建议清单。我们当前使用 **Jenkins**,希望对比开源与商业方案(如 TeamCity 等),并特别关注**性能、扩展性、构建缓存、调度能力与二次开发能力**。 + +### 1) 背景与目标 + +* 当前:Jenkins(请默认我们已有大量 Pipeline/Shared Library/插件依赖) +* 目标:评估下一代 CI/CD 工具是否能在**性能、稳定性、可维护性、可扩展性、集成与安全**上显著优于 Jenkins,或给出 Jenkins 体系增强路线(如分层、控制面/执行面拆分、缓存体系改造等)。 +* 部署要求:**必须支持私有化部署**(IDC / 私有云 / K8s 均可能) + +### 2) 必须满足的构建能力(重点逐条对比) + +请对每个候选工具给出“是否支持/成熟度/实现方式/限制/最佳实践/替代方案”。 + +**多语言与多版本** + +* Node:支持多版本 Node(例如 nvm/asdf/容器镜像/工具链管理),并能在流水线内灵活切换 +* Java:支持多版本 JDK(8/11/17/21 等),并可与 Maven/Gradle 协作 +* Maven:支持 **Maven 并发构建**(并行 stage、并行 module、分布式构建),并说明常见瓶颈与优化方式 + +**多分支与规模化** + +* 支持多分支构建(多分支流水线/PR 构建/分支策略),并说明分支规模增大后的性能与资源开销 +* 支持大规模并发:请给出在 10万次/年构建规模下的参考架构(控制面、执行面、队列、弹性伸缩、隔离模型) + +**构建缓存(强诉求)** + +* 支持高质量缓存体系:依赖缓存(npm/maven)、构建产物缓存、远程缓存(如 Bazel/Gradle build cache 类似能力) +* 缓存可共享、可清理、可审计、可多租户隔离 +* 请说明:缓存命中率提升策略、缓存一致性/污染处理、典型落地方式(PVC/NFS/S3/MinIO/远程 cache 服务) + +**分布式/虚拟化执行** + +* 支持 “可扩展的执行节点/Agent”,以及基于 **K8s** 或 VM 的动态调度 +* 我们有 “**Gravvl VM 构建**”(按你理解:可视为“特定 VM/镜像/硬件架构环境的构建需求”,例如需要在 VM 内执行、或需要特定内核/驱动/安全基线)。请给出:如何接入、如何做资源隔离、如何做镜像管理与复用、如何控制成本。 + +### 3) 灵活的构建参数与触发模型 + +* 参数化构建:动态参数、级联参数、环境矩阵(OS/Arch/版本)、手动触发与 API 触发 +* 触发源:Git Push/PR/MR、Tag、定时、Webhook、外部事件(消息队列/工单/发布平台) +* 复杂流水线编排:条件执行、审批/人工确认、并行/扇出、失败重试与补偿 + +### 4) 灵活的服务器调度与资源治理 + +请说明调度能力是否“内置/需集成/依赖 K8s/需商业组件”: + +* 队列与优先级:不同项目/团队配额、优先级、抢占/限流 +* 弹性:基于队列长度/资源水位自动扩缩容 +* 隔离:多租户隔离、Runner/Agent 隔离、网络隔离、凭据隔离 +* 成本:资源利用率、峰谷策略、冷启动/预热策略 + +### 5) 集成策略与对外传递(强诉求) + +* “构建信息需要向外传递”:请给出可落地的事件模型与集成方式 + + * 构建开始/成功/失败/产物信息/制品元数据/测试报告/覆盖率/安全扫描结果 + * 事件投递方式:Webhook、消息队列(Kafka/NATS/RabbitMQ)、事件总线、回调、API 拉取 + * 幂等、重试、可观测(Trace/Log/Metric)与审计 + +### 6) 脚本语法与可维护性 + +* 主流脚本语法:YAML(GitLab CI/GHA 风格)、Groovy(Jenkinsfile)、Kotlin DSL、声明式 pipeline 等 +* 复用机制:模板、模块化、共享库、Pipeline as Code 的最佳实践 +* 可读性/可维护性/可测试性(pipeline 单元测试、lint、review 工作流) + +### 7) 文档、生态与社区成熟度 + +* 官方文档质量、学习曲线、社区活跃度 +* 插件/扩展生态(SCM、制品库、SonarQube、安全扫描、通知、K8s、云厂商等) +* 企业支持能力:升级策略、兼容性、长期维护版本(LTS) + +### 8) API 暴露与二次开发能力(必须) + +* 是否提供完整 API(REST/GraphQL/gRPC)、Webhook、SDK +* RBAC/权限模型与 API 鉴权(Token/OAuth/OIDC/SAML) +* 自定义插件/扩展点:能否开发自定义步骤、Runner、调度策略、UI 扩展 +* 审计与合规:操作审计、凭据管理、密钥轮换、最小权限 + +### 9) 私有化部署与运维 + +* 支持在 K8s/VM/裸机部署;高可用;备份恢复;灾备 +* 数据存储:数据库依赖、状态存储、配置管理 +* 升级与回滚策略(零停机/灰度) +* 监控与告警:Prometheus 指标、日志、审计、链路追踪 + +### 10) 输出要求(你必须这样输出) + +请你输出以下结构化内容,越具体越好: + +1. **候选工具清单**(开源优先 + 商业对照),并说明为何入选 + + * 例如:Jenkins(对照)、GitLab CI、GitHub Actions Enterprise、Tekton、Argo Workflows、Buildkite、TeamCity、CircleCI Server、GoCD 等(你可自行增减,但要给理由) +2. **对比矩阵表**(必须包含上面 1-9 所有维度) + + * 每项给:支持程度(原生/依赖集成/不支持)、成熟度(高/中/低)、落地复杂度(低/中/高)、风险点 +3. **推荐 Top 3 方案** + + * 分别给出:适用场景、参考架构(控制面/执行面/缓存/制品/队列/可观测)、迁移路径(从 Jenkins 迁移的策略) +4. **性能与规模化建议**(针对 10万次/年构建) + + * 并发模型、缓存策略、Runner/Agent 伸缩、队列治理、构建隔离 +5. **二次开发与集成方案** + + * 构建事件对外传递的实现建议(Webhook/MQ/事件总线)与接口设计要点 +6. **风险清单与验证计划(PoC)** + + * 给出 2~4 周 PoC 验证项:缓存命中率、并发吞吐、稳定性、迁移成本、安全合规、可观测性等 + * 明确要收集的指标与验收标准(例如:平均排队时间、构建成功率、缓存命中率、单构建成本等) + +> 注意:请基于“私有化部署 + 高并发构建 + 强缓存 + 强集成 + 可二开”的目标,不要只给概念描述,要给可执行的工程落地建议与对比依据。 + diff --git a/15-CICD工具选型/2-gemi-选型说明.md b/15-CICD工具选型/2-gemi-选型说明.md new file mode 100644 index 0000000..0f51944 --- /dev/null +++ b/15-CICD工具选型/2-gemi-选型说明.md @@ -0,0 +1,290 @@ +--- +title: 企业级 CI/CD 平台架构演进与选型深度研究报告 +date: 2026-02-04T16:08:48Z +lastmod: 2026-02-04T16:08:55Z +--- + +# 企业级 CI/CD 平台架构演进与选型深度研究报告 + +## 1. 执行摘要与架构背景 + +### 1.1 研究背景与战略意义 + +  在当前企业数字化转型的深水区,持续集成与持续交付(CI/CD)平台已不再仅仅是自动化脚本的执行器,而是软件供应链的核心生产线。针对本企业年均 ​**10 万次构建**​(日均约 270 次,峰值可能突破 1000 次/日)的规模,现有的 Jenkins 架构正面临着从“工具级”向“平台级”跨越的临界点。当前的 Jenkins 体系虽然通过大量 Shared Library 和插件维持运转,但在面对​**GraalVM 原生镜像构建的高资源消耗**​、**Maven/Node 复杂依赖的缓存瓶颈**以及**企业级数据总线(Event Bus)的强集成需求**时,表现出了明显的架构疲态。 + +  本报告站在“企业级架构师”与“DevOps 专家”的双重视角,对私有化部署场景下的主流 CI/CD 解决方案进行了穷尽式的深度剖析。我们的目标不仅是选出一款工具,更是为了构建一套能够在未来 3-5 年内支撑业务倍增、保障构建性能与安全、且具备高度二次开发能力的工程化底座。 + +### 1.2 核心挑战分析:10 万次构建的规模效应 + +  10 万次/年的构建量级是一个关键的分水岭。在此规模之下,简单的脚本编排尚可应付;而一旦跨越此量级,一系列隐性的架构瓶颈将集中爆发: + +- **I/O 吞吐风暴(I/O Throttling):** Java (Maven/Gradle) 和 Node.js (npm/yarn) 生态系统的构建高度依赖网络 I/O。假设单次“净构建”需下载 200MB 依赖,若无高效缓存,10 万次构建将产生 **20TB** 的无效网络流量。这不仅会导致构建排队,甚至可能阻塞 IDC 的出口带宽 ^^。 +- **控制面与执行面的资源竞争:** 传统的 Jenkins 主从架构(Master-Slave)在处理高并发(如峰值 50+ 并发流水线)时,Controller 节点的 JVM 堆内存压力剧增,导致 UI 卡顿甚至宕机。特别是当 GraalVM 等 CPU/内存密集型任务混跑在共享集群时,“吵闹邻居”(Noisy Neighbor)效应将严重影响稳定性 ^^。 +- **集成架构的脆弱性:** 当前“强集成”需求要求构建状态实时向外投递。依赖 Jenkins 插件进行点对点(Point-to-Point)通知的方式在插件升级或 API 变更时极易断裂。架构必须向\*\*事件驱动架构(EDA)\*\*转型,将 CI 平台作为标准的事件生产者(Producer)接入 Kafka 等消息总线 ^^。 + +### 1.3 评估范围与方法论 + +  本报告严格遵循“私有化部署”的红线要求,剔除纯 SaaS 方案(如 CircleCI Cloud、GitHub Actions Cloud),重点考察以下核心维度: + +1. **性能密度:** 单位资源下的并发吞吐能力。 +2. **缓存工程:** 多级缓存体系(本地/远程/分布式)的实现机制。 +3. **异构计算支持:** 对 K8s 动态节点与 GraalVM 专用静态节点的混合调度能力。 +4. **开放性:** API 完备度与事件总线集成能力。 + +--- + +## 2. 候选工具生态格局与入围清单 + +  在私有化部署(Self-Hosted)领域,市场格局呈现出“一超多强”的态势。基于技术栈匹配度(Java/Node/K8s)与企业级特性,我们将以下工具列入深度评估清单: + +### 2.1 核心候选者 + +#### **1. Jenkins (基准对照组)** + +- **入选理由:** 现有的存量资产,拥有全球最大的插件生态。 +- **当前定位:** 传统的自动化服务器。虽然通过 Jenkins X 和 Kubernetes Plugin 尝试现代化,但其核心架构仍基于 Servlet 容器,积重难返。 +- **关键挑战:** “插件地狱”(Plugin Hell)与单点故障风险。维护一个高可用的 Jenkins 集群往往需要专门的运维团队 ^^。 + +#### **2. TeamCity (工程化首选)** + +- **入选理由:** JetBrains 出品,专为复杂工程设计。在 Java/Kotlin 生态中拥有统治级的构建优化能力(智能并行、构建链优化)。 +- **架构特点:** 采用强类型的 Kotlin DSL 配置,Server-Agent 架构极其成熟,原生支持构建队列的智能调度 ^^。 +- **适用性:** 极度适合 Maven 多模块与 Gradle 构建场景,对 GraalVM 等重型构建有优秀的资源隔离管理。 + +#### **3. GitLab CI/CD (DevOps 一体化首选)** + +- **入选理由:** 云原生时代的标杆。与其源码管理(SCM)深度绑定,实现了“代码即流水线”的闭环。 +- **架构特点:** 核心组件(Coordinator)与执行组件(Runner)完全解耦。GitLab Runner 基于 Go 语言开发,极其轻量且稳定,完美契合 Kubernetes 环境 ^^。 +- **适用性:** 适合追求工具链统一、容器化程度高的团队。 + +#### **4. Buildkite (混合云架构对照)** + +- **入选理由:** 以“高并发”和“混合云”著称。虽然其控制面(Control Plane)通常为 SaaS,但其 Agent 必须部署在私有环境。 +- **特别说明:** 尽管它是 SaaS 控制面,但对于拥有极高并发需求且希望零维护控制面的团队,Buildkite 提供了一种独特的思路。如果企业的安全合规允许构建元数据(Metadata)上云,而代码和产物留在本地,Buildkite 是极具竞争力的“黑马” ^^。 +- *在本报告中,Buildkite 将作为架构设计的参考标杆,用于对比极致的 Agent 调度能力。* + +#### **5. Tekton / Argo Workflows (云原生纯粹派)** + +- **入选理由:** Kubernetes 原生(CRD-based)的流水线引擎。 +- **落选深度评估理由:** 尽管它们是底层引擎的未来,但缺乏企业级 CI 所需的用户界面(UI)、权限管理(RBAC)和插件生态。通常作为底层执行器被上层平台(如 OpenShift Pipelines)集成,直接作为企业级 CI 平台使用二次开发成本过高 ^^。 + +--- + +## 3. 核心能力深度对比矩阵与解析 + +  本章节将针对您的具体需求,对 Jenkins、TeamCity 和 GitLab CI 进行“像素级”的横向评测。 + +### 3.1 性能核心:多语言版本管理与并发构建 + +  **需求分析:** 企业内部存在多版本 Node.js (Legacy/Modern) 和 Java (JDK 8/11/17/21) 共存的现状。Maven 构建的并发效率直接决定了开发者的等待时间。 + +|**功能维度**|**Jenkins (现有)**|**TeamCity (JetBrains)**|**GitLab CI (Runner)**|**架构师点评与风险提示**|||||| +| --| -------------------------------------------------------------------------------------------------------------------------------| ---------------------------------------------------------------------------------------------------------------------------------------------------------| ---------------------------------------------------------------------------------------------------------------------| ------------------------------------------------------------------------------------------------------------------------------------------------------| --| --| --| --| --| +|**多版本环境切换**|**依赖插件/脚本**

通常需在 Global Tools 中配置多个 JDK/Node 路径,或在 Shell 中手动 source nvm。容易产生环境污染(Dirty Agent)。|**原生参数化**

Agent 自动汇报环境能力(Capabilities)。通过构建参数直接选择 JDK 版本。支持在同一 Agent 上通过 Docker Wrapper 隔离运行不同步骤。|**容器镜像驱动(最佳实践)**

每一个 Job 都在指定的 Docker 镜像中运行(如`image: maven:3.8-jdk-11`)。切换版本只需修改 YAML 中的 image 标签,完全隔离。|​**GitLab 胜出**。

Jenkins 的环境管理是运维噩梦;TeamCity 的 Agent 管理虽然智能但仍依赖物理/虚拟机环境配置;GitLab 的“容器即环境”彻底解决了版本冲突问题^^。|||||| +|**Maven 并发构建**|**弱/依赖插件**

Groovy 的`parallel`​语法可并行 Stage,但同一 Agent 上的并行 Maven 进程可能导致`.m2`​仓库锁冲突。跨节点并行需频繁`stash/unstash`产物,I/O 开销巨大。|**卓越(构建链)**

原生解析 Maven POM 依赖图,自动拆分为独立的构建链(Build Chain)。支持“快照依赖”,智能调度模块并行构建,且仅重构建修改模块(Incremental Build)。|**中等(手动拆分)**

支持`parallel: matrix`​和 DAG (`needs`) 关键字。需手动定义模块间的依赖关系,不如 TeamCity 智能。|​**TeamCity 胜出**。

对于大型 Maven Monorepo,TeamCity 的增量构建与依赖分析能力可减少 40%-60% 的无用构建时间^^。|||||| +|**GraalVM 原生构建**|**资源黑洞风险**

若调度到常规 K8s Pod,极易因 OOM 被杀。需配置特定的 Label 绑定到大内存节点。|**专用 Agent 池**

将 GraalVM 任务路由到专属的物理机/大内存 Agent 池。支持细粒度的 CPU/内存配额管理。|**Tag 路由机制**

通过`tags: [graalvm]`将任务调度到特定的 Runner(如 Bare-metal Runner)。K8s 执行器支持为特定 Job 设置 hugepages 和资源 limit。|​**平局**。

关键在于基础设施层的隔离。TeamCity 的 Agent Pool 可视化管理更优;GitLab 的 Runner配置更灵活^^。|||||| + +### 3.2 规模化扩展:队列治理与弹性伸缩 + +  **需求分析:** 10 万次/年的构建意味着峰值期间(如发版日)会有大量任务堆积。如何处理优先级(Hotfix 插队)和资源抢占是关键。 + +#### 3.2.1 队列与优先级模型 + +- **TeamCity:** 拥有业界最先进的​**构建队列优化器(Optimizer)** 。它不仅支持基于优先级的插队(Priority Class),还能自动合并队列中的冗余构建(例如:在构建 A 等待期间,代码库又有新提交,TeamCity 可以自动取消构建 A 直接运行包含最新代码的构建 B)。这对节省 10 万次规模下的资源至关重要 ^^。 +- **GitLab CI:** 本质上是 FIFO(先进先出)队列。虽然可以通过设置 Runner 的并发限制来管理,但在同一个 Runner 实例内部很难实现“让 Hotfix 构建立即抢占正在运行的 CI 构建”的逻辑,通常需要预留专用的 Runner 资源,造成浪费。 +- **Jenkins:** 依赖 `Priority Sorter Plugin`,配置繁琐且容易失效。在高负载下,Jenkins Master 的调度线程本身可能成为瓶颈。 + +#### 3.2.2 弹性伸缩架构(Elasticity) + +- **GitLab CI (Kubernetes Executor):** 真正的云原生弹性。Runner 作为一个轻量级 Agent,仅在需要时向 K8s API 申请 Pod。构建结束后 Pod 立即销毁。这种\*\*“用完即焚”\*\*(Ephemeral)模式完美契合 10 万次构建的动态波动特性,资源利用率最高 ^^。 +- **TeamCity:** 支持“云代理”(Cloud Agents)。可以对接 K8s 或 AWS EC2,按需启动 Agent。但 TeamCity 的 Agent 是有状态连接(Bi-directional communication),启动和握手速度通常慢于 GitLab 的无状态 Runner。 + +### 3.3 构建缓存体系:性能决胜点 + +  **需求分析:** “强诉求”——缓存必须可共享、可清理。Maven 和 Node 的依赖下载是性能杀手。 + +#### **架构方案 A:GitLab CI 的分布式缓存(S3/MinIO 后端)** + +  GitLab 采用“压缩-上传-下载-解压”的缓存机制。 + +- **机制:** Job 开始时,Runner 从 MinIO 下载 `cache.zip`​ 并解压;Job 结束时,压缩 `node_modules` 并上传。 +- **瓶颈:** 对于 `node_modules` 动辄 1GB 的情况,压缩和网络传输的时间可能超过下载依赖本身的时间。 +- **优化策略:** 必须使用 **Docker Layer Caching** 或 ​**PVC 挂载**​。在私有化 K8s 环境中,推荐使用 `hostPath`​ 或高性能网络存储(如 CephFS)挂载到 Runner Pod 中作为全局缓存,通过 `KANIKO_CACHE_ARGS` 实现构建层缓存 ^^。 + +#### **架构方案 B:TeamCity 的本地持久化缓存** + +  TeamCity 倾向于使用持久化 Agent。 + +- **机制:** Agent 是长期运行的。Maven 的 `.m2` 仓库直接存储在 Agent 的本地磁盘上。 +- **优势:** 二次构建速度极快(零网络开销)。 +- **风险:** 缓存污染。如果两个并行构建修改同一个本地依赖,可能导致构建失败。TeamCity 通过“共享资源锁”(Shared Resources)机制来解决此问题,但这会降低并发度 ^^。 +- **推荐方案:** 结合 ​**Remote Build Cache**(如 Gradle Enterprise 或 Bazel Remote Cache)。不依赖 CI 工具本身的缓存,而是让构建工具直接连接局域网内的 Nginx/Redis 缓存服务。 + +--- + +## 4. 推荐方案 Top 3 与架构设计 + +  基于“私有化 + 高并发 + 强集成”的目标,我们给出明确的选型建议。 + +### 推荐一:GitLab CI/CD(DevOps 平台化转型的战略首选) + +  **适用场景:** + +- 希望实现从代码管理到部署的​**全链路闭环**。 +- 运维团队具备较强的 **Kubernetes** 运维能力。 +- 追求​**配置即代码**(YAML)和不可变基础设施。 + +  **参考架构(针对 10 万次/年规模):** + +- **控制面(Control Plane):** 部署 GitLab HA 集群(3 节点),配置高性能 Redis 集群用于作业队列缓冲,外接 PostgreSQL 数据库。 +- **执行面(Data Plane):** + + - **通用池:** Kubernetes Executor,配置 HPA(水平自动伸缩),承载 80% 的 Java/Node 构建。 + - **专用池:** 3-5 台高配置裸金属服务器(Bare Metal),安装 Shell Executor 或 Docker Executor,专门用于 **GraalVM Native Image** 构建,避免 K8s OOM 风险 ^^。 +- **缓存策略:** 部署私有化 MinIO 集群作为 Distributed Cache 后端。同时在 K8s Runner 中开启 `PVC` 挂载,将 Maven/NPM 缓存挂载为 ReadWriteMany 卷(需底层存储支持,如 NAS),实现“热缓存”。 +- **迁移路径:** 利用 GitLab 的 `include`​ 机制,将 Jenkins Shared Library 中的逻辑重构为通用的 `.gitlab-ci.yml` 模板库(Templates),供各个项目引用。 + +### 推荐二:TeamCity(工程效能极致优化的战术首选) + +  **适用场景:** + +- 核心业务为复杂的 ​**Java Monorepo**,对依赖管理极其敏感。 +- 需要极度精细的**构建队列管理**和资源抢占能力。 +- 可以接受独立的 SCM 和 CI 工具分离,且预算允许购买 Agent 授权。 + +  **参考架构:** + +- **控制面:** 单节点 TeamCity Server(配备高性能 NVMe SSD 存储数据库和 Artifacts),因 TeamCity Server 架构难以水平扩展,需垂直扩展(Vertical Scaling)以支撑高并发 API 请求。 +- **执行面:** + + - **Agent Pool A (Cloud):** 对接 K8s 集群,用于运行轻量级 Docker 任务。 + - **Agent Pool B (Persistent):** 部署在物理机上的持久化 Agent,用于 Maven 增量构建和 GraalVM 构建。利用本地磁盘 I/O 优势。 +- **集成:** 开发自定义 Java 插件监听构建事件,推送到 Kafka。 + +### 推荐三:Jenkins Modernization(存量资产保护的折衷方案) + +  **适用场景:** + +- 存量 Pipeline 逻辑过于复杂(数万行 Groovy 代码),重写成本不可接受。 +- 预算极其有限,无法承担 TeamCity 许可或 GitLab Premium 费用。 + +  **增强路线(Survival Strategy):** + +- **彻底的控制/执行分离:** 禁止在 Master 节点执行任何 Job。所有构建强制下发到 K8s Pod。 +- **配置即代码(JCasC):** 使用 Jenkins Configuration as Code 插件管理 Master 配置,杜绝手动 UI 修改。 +- **事件总线改造:** 编写一个全局的 Shared Library (`GlobalPipelineListener`​),在 `pipeline`​ 的 `post { always {... } }` 块中注入 Kafka 发送逻辑,强制所有构建接入事件总线。 + +--- + +## 5. 深度专题:二次开发与集成方案(事件总线) + +  **需求:** “构建信息向外传递”是强诉求。我们需要从“轮询查询”转向“事件驱动”。 + +### 5.1 数据模型设计(CloudEvents 标准化) + +  建议采用 **CloudEvents** 规范定义构建事件,确保 Kafka 消息的通用性。 + +  **Kafka Topic:** `cicd.build.events` + +  **Schema (Avro/JSON) 示例:** + +  JSON + +``` +{ + "specversion": "1.0", + "type": "com.company.cicd.build.finished", + "source": "/gitlab/project/1234", + "id": "a1b2c3d4", + "time": "2026-02-04T10:00:00Z", + "datacontenttype": "application/json", + "data": { + "pipeline_id": "998877", + "status": "failed", + "duration_ms": 45000, + "initiator": "devops-user", + "commit_sha": "7f8a9b...", + "artifacts": [ + {"name": "app.jar", "size": 102400, "url": "s3://builds/app.jar"} + ], + "environment": { + "os": "linux", + "arch": "amd64", + "graalvm_version": "21.3" + } + } +} +``` + +### 5.2 集成实现方案对比 + +|**方案**|**Jenkins 实现**|**GitLab CI 实现**|**TeamCity 实现**|**推荐度**|||||| +| --| ---------------------------------------------------------------------------------------| -----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| ------------------------------------------------------------------------------------------------------------------------------------------| --------------------------------------------------------------| --| --| --| --| --| +|**Webhook 桥接**|**使用 Notification Plugin**

配置 Webhook URL 指向一个中间件(Kafka Bridge)。

*缺点:* 插件可靠性一般,重试机制弱。|**使用 System Hooks**

在 Admin 层级配置全局 System Hook,将所有 Pipeline Event 推送到 Kafka Bridge 服务(如用 Go 编写的轻量级转换器)。

*优点:* 全局生效,无需修改.gitlab-ci.yml,官方支持,极为稳定^^。|**Custom Webhook Plugin**

安装 Webhook 插件配置 Payload 模板。

*缺点:* 需手动配置每个项目或继承模板。|**GitLab (High)**

原生 System Hooks 覆盖面最全。|||||| +|**原生插件/监听器**|**Groovy Shared Library**

在库中封装`KafkaProducer`。每次构建必须引用该库。

*缺点:* 侵入性强,依赖 Jenkins 类加载器。|**不可行**

GitLab SaaS/Omnibus 不允许注入自定义代码到核心 Rails 进程中。只能通过 Webhook 异步处理。|**Server-Side Plugin (Java)**

利用 TeamCity Open API 编写 Java 插件,实现`BuildServerAdapter`​接口。在`buildFinished`方法中直接调用 Kafka SDK 发送消息。

*优点:* 性能最高,可靠性最强(事务级保障)^^。|**TeamCity (High)**

如果追求“强集成”且有 Java 开发能力,这是最完美的方案。|||||| + +  **集成建议:** + +  若选型 ​**GitLab**​,请开发一个 **"Webhook-to-Kafka Gateway"** 微服务。该服务接收 GitLab 的 HTTP POST 请求,验证 `X-Gitlab-Token`,将 JSON 转换为 Avro,并投递到 Kafka。这种解耦架构最符合云原生设计原则。 + +--- + +## 6. 性能与规模化落地建议(10万次/年) + +  针对年均 10 万次构建(日均峰值可能达 1000+),必须在架构层面进行针对性优化。 + +### 6.1 并发模型计算与容量规划 + +- **吞吐量估算:** 假设日均 270 次,峰值系数 5 倍(集中在上午 10 点和下午 3 点),即峰值每小时约 60-100 次构建。假设平均构建时长 10 分钟。 +- **并发需求:** \$\\text{并发数} \= \\text{每小时构建数} \\times \\text{构建时长(小时)} \\approx 100 \\times (10/60) \\approx 16.6\$。考虑到排队冗余,需预留 ​**30-50 个并发执行槽位(Executors/Runners)** 。 +- **硬件建议:** + + - **K8s Cluster:** 至少 3 个 Worker 节点,每节点 32C/64G(用于通用构建)。 + - **GraalVM 专用池:** 2 台高频 CPU(4GHz+)、大内存(128G+)的裸金属服务器。GraalVM 构建不仅吃内存,极其依赖 CPU 单核主频来缩短 Native Compile 时间 ^^。 + +### 6.2 GraalVM 构建的特殊隔离策略 + +  GraalVM Native Image 构建过程极其霸道,会瞬间占满宿主机的所有可用 CPU 和内存。 + +- **策略 1:Taints & Tolerations (K8s)** + 为 GraalVM 专用节点打上污点 `kubectl taint nodes node-graalvm dedicated=graalvm:NoSchedule`​。在 CI Job 中添加对应的容忍度(Tolerations),确保只有 GraalVM 任务调度到这些节点,且**绝对禁止**普通 Java/Node 任务抢占这些资源。 +- **策略 2:CPU Pinning (绑核)** + 为了保证构建时间的稳定性,建议在 K8s Pod 中通过 CPU Manager Policy 设置为 `static`,独占 CPU 核心,防止上下文切换带来的性能损耗。 + +### 6.3 镜像管理与复用(Docker Layer Caching) + +- **问题:** 每次构建都 `docker build` 会产生大量重复层。 +- **解法:** 使用 **Kaniko** 或 ​**BuildKit**。 +- **最佳实践:** 搭建私有的 Harbor 镜像仓库,并配置为 **Proxy Cache** 模式代理 Docker Hub。在内网环境中,Runner 拉取基础镜像(如 `openjdk:17-slim`)的速度应达到 Gigabit 线速。 + +--- + +## 7. 风险清单与验证计划(PoC) + +  建议开展为期 4 周的概念验证(PoC),以数据驱动决策。 + +### 7.1 PoC 验证关键指标(KPIs) + +|**验证项**|**关键指标 (Metric)**|**验收标准 (Acceptance Criteria)**|**测试方法**||||| +| --| -----------------------------| ---------------------------------------------------------| -----------------------------------------------------------------------------------| --| --| --| --| +|**Maven 并发构建效率**|缓存命中率 (Cache Hit Rate)|\> 90% 的依赖直接从本地/局域网缓存获取|清空 Runner,运行构建,记录耗时;再次运行,耗时应减少 60% 以上。||||| +|**GraalVM 隔离性**|邻居干扰度 (Interference)|GraalVM 构建期间,同节点其他 Pod 响应延迟增加 \< 10%|在同一节点并发运行 Native Build 和 API 压测,监控 CPU Steal 和 Memory Thrashing。||||| +|**事件总线集成**|事件延迟 (E2E Latency)|Build 结束到 Kafka 收到消息 \< 500ms|触发构建,对比 CI 日志时间戳与 Kafka 消息时间戳。||||| +|**弹性伸缩**|冷启动时间 (Cold Start)|新 Runner Pod 启动并接手任务 \< 30s|模拟突发流量(一次性触发 50 个构建),观察 K8s HPA 响应速度。||||| + +### 7.2 迁移风险与应对 + +- **风险:** **Groovy 脚本黑盒化。** 现有的 Shared Library 包含大量未文档化的业务逻辑(如特定的发包逻辑、通知逻辑)。 +- **应对:** 在 PoC 阶段,选取最复杂的 3 个 Pipeline 进行“翻译”。如果是 GitLab,尝试用 Template 复现;如果是 TeamCity,用 Kotlin DSL 复现。如果复现成本过高,说明 Jenkins 锁定效应(Vendor Lock-in)极强,需重新评估迁移 ROI。 + +--- + +## 8. 结论 + +  面对 10 万次/年的构建规模与私有化强集成的需求: + +1. **若追求架构的先进性与运维的标准化:** 请选择 ​**GitLab CI/CD**。它用“容器化一切”的理念解决了环境版本管理难题,用 System Hooks 解决了集成难题,是云原生时代的最佳实践。 +2. **若受困于超复杂的 Java 构建逻辑与性能瓶颈:** 请选择 ​**TeamCity**。它是构建工程领域的特种兵,能榨干每一分硬件性能,特别是在 GraalVM 和大型 Monorepo 场景下表现无可匹敌。 +3. **Jenkins** 只有在经过彻底的“云原生化改造”(JCasC + K8s)后才值得保留,否则它将成为 DevOps 效能提升的最大阻碍。 + +  **建议下一步:** 立即搭建 GitLab HA 环境与 Kafka Bridge 进行 PoC,实测 Maven 分布式缓存与 System Hooks 的连通性。 diff --git a/15-CICD工具选型/3-per-选型说明.md b/15-CICD工具选型/3-per-选型说明.md new file mode 100644 index 0000000..c8b45d8 --- /dev/null +++ b/15-CICD工具选型/3-per-选型说明.md @@ -0,0 +1,856 @@ +--- + +## 1️⃣ 候选工具清单(开源 + 商业对照) + +基于你的需求(私有化部署、高并发、强缓存、可二开),以下工具入选: + +## 🟢 **开源方案** + +1. **Jenkins**(对照基准)- 插件生态最成熟,但架构老旧 +2. **GitLab CI + Runner** - 一体化 DevOps 平台,私有化首选 +3. **Tekton** - K8s-native,云原生架构,高度可扩展 +4. **Argo Workflows** - K8s-native,适合复杂 DAG 编排 +5. **Drone** - 轻量级容器化,适合中小规模 +6. **GoCD** - 管道可视化强,但社区活跃度下降 + +## 🟡 **商业/混合方案** + +7. **Buildkite** - BYOC 模式,控制面托管 + Agent 自管理 +8. **CircleCI Server** - 私有化部署版本,但价格较高 +9. **TeamCity** - JetBrains 出品,Java 生态友好,商业授权 +10. **Harness** - AI 驱动的 CD 平台,侧重部署编排 + +## ❌ **未入选原因** + +- **GitHub Actions**:虽支持自托管 Runner,但控制面必须依赖 GitHub.com[fuyuan7+1](https://www.fuyuan7.com/post-1172.html) +- **Travis CI**:商业化转型后口碑下降,私有化支持弱 +- **Bamboo**:Atlassian 已停止活跃开发 + +--- + +## 2️⃣ 对比矩阵表(9 大维度 × 10 个工具) + +| **维度/工具** | **Jenkins** | **GitLab CI** | **Tekton** | **Argo Workflows** | **Drone** | **Buildkite** | **TeamCity** | **CircleCI Server** | **GoCD** | +| -- | ----------------------- | ----------------------------- | ---------------------- | ---------------------- | ----------------- | ---------------------- | ----------------- | --------------------- | -------------------- | +| **多语言支持** | ✅ 原生插件 | ✅ Docker 执行器 | ✅ Task 容器化 | ✅ 容器化 | ✅ 容器化 | ✅ 脚本驱动 | ✅ 原生支持 | ✅ 容器化 | ✅ 原生支持 | +| **多版本管理(Node/JDK)** | 🟡 插件 + 容器 | ✅ 镜像 + image 字段 | ✅ 容器镜像 | ✅ 容器镜像 | ✅ 容器镜像 | ✅ 自定义脚本 | ✅ 内置版本管理 | ✅ 容器镜像 | 🟡 手动配置 | +| **Maven 并发构建** | ✅ 插件 + 并行 stage | ✅ 并行 job | ✅ 并行 Task | ✅ 并行 Step | 🟡 基础并行 | ✅ 并行 step | ✅ 并行构建 | ✅ 并行 workflow | ✅ 并行 pipeline | +| **多分支/PR 构建** | ✅ Multibranch Plugin | ✅ 原生支持 | 🟡 需 Triggers 集成 | 🟡 需 Events 集成 | ✅ 原生支持 | ✅ 动态管道 | ✅ 原生支持 | ✅ 原生支持 | ✅ 原生支持 | +| **构建缓存(成熟度)** | 🟡 插件 + 自建 | ✅ 分布式缓存(S3/MinIO)[[cnblogs](https://www.cnblogs.com/Sol-wang/p/16775377.html)] | 🟡 需自建 PVC/S3 | 🟡 需自建 | 🟡 Volume 缓存 | ✅ 插件 + S3 | ✅ 内置缓存 | ✅ 原生缓存 | 🟡 工件缓存 | +| **远程缓存(Gradle/Bazel)** | ⚠️ 手动集成 | ✅ 支持(需配置)[[youtube](https://www.youtube.com/watch?v=zOu3WOKNUcc)][[bitrise](https://bitrise.io/blog/post/bitrise-build-cache-reduces-circleci-build-times)] | ✅ 支持 | ✅ 支持 | ⚠️ 手动集成 | ✅ 支持 | ✅ 支持 | ✅ 支持 | ⚠️ 手动集成 | +| **K8s 动态调度** | 🟡 K8s Plugin | ✅ Runner K8s executor[[gitlab](https://gitlab.cn/docs/runner/fleet_scaling/_index/)] | ✅ 原生 K8s | ✅ 原生 K8s | 🟡 需手动配置 | ✅ Agent K8s 集成 | 🟡 Cloud Agent | ✅ K8s 执行器 | 🟡 弹性 Agent | +| **VM/特定环境构建** | ✅ Docker Machine | ✅ Docker Machine[[gitlab](https://gitlab.cn/docs/runner/configuration/autoscale/)] | 🟡 需自建 | 🟡 需自建 | 🟡 需自建 | ✅ Agent 自定义 | ✅ Cloud Agent | ✅ Machine executor | 🟡 弹性 Agent | +| **队列与优先级** | ✅ Priority Sorter | ✅ resource\_group[[gitlab](https://gitlab.cn/docs/runner/fleet_scaling/_index/)] | 🟡 K8s PriorityClass | 🟡 K8s PriorityClass | ⚠️ 基础队列 | ✅ 高级队列 | ✅ 内置队列 | ✅ 队列管理 | ✅ Pipeline 优先级 | +| **多租户隔离** | 🟡 Folder + Role | ✅ Group/Project 隔离 | ✅ Namespace 隔离 | ✅ Namespace 隔离 | 🟡 Org 隔离 | ✅ Org/Team 隔离 | ✅ Project 隔离 | ✅ Context 隔离 | 🟡 Pipeline Group | +| **事件/Webhook 输出** | ✅ 插件丰富 | ✅ 原生 Webhook | ✅ CloudEvents | ✅ Argo Events | ✅ 原生 Webhook | ✅ Webhook + GraphQL | ✅ Notification | ✅ Webhook | 🟡 通知插件 | +| **API 能力** | ✅ REST API | ✅ REST + GraphQL | ✅ K8s API | ✅ K8s API | ✅ REST API | ✅ GraphQL[[slant](https://www.slant.co/versus/2482/2485/~gitlab-ci_vs_buildkite)] | ✅ REST API | ✅ REST API | ✅ REST API | +| **脚本语法** | Groovy(复杂) | YAML(简洁)[[cnblogs](https://www.cnblogs.com/Sol-wang/p/16775377.html)] | YAML(K8s CRD) | YAML(Workflow) | YAML(简洁)[[juejin](https://juejin.cn/post/7380694342744932390)] | YAML(灵活) | Kotlin DSL | YAML | 声明式 | +| **共享库/模板** | ✅ Shared Library[[blog.csdn](https://blog.csdn.net/weixin_33628677/article/details/150154969)] | ✅ include/extends | ✅ Task Catalog | ✅ Template 库 | 🟡 基础复用 | ✅ 动态模板 | ✅ 模板系统 | ✅ Orb(限 Cloud) | 🟡 模板管道 | +| **插件生态** | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐ | +| **文档质量** | ⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐ | +| **私有化部署** | ✅ 完全支持 | ✅ 完全支持 | ✅ 完全支持 | ✅ 完全支持 | ✅ 完全支持 | 🟡 BYOC 混合 | ✅ 完全支持 | ✅ 完全支持 | ✅ 完全支持 | +| **高可用(HA)** | 🟡 需 CloudBees | ✅ 多节点 + LB | ✅ K8s 原生 | ✅ K8s 原生 | 🟡 需自建 | ✅ SaaS 控制面 | ✅ 主从模式 | ✅ 集群模式 | 🟡 需手动配置 | +| **学习曲线** | 陡峭(Groovy) | 平缓(YAML) | 中等(K8s) | 中等(K8s) | 平缓 | 平缓 | 中等 | 平缓 | 中等 | +| **成本(10万次/年)** | 低(基础设施) | 低(开源/EE 可选) | 低(仅 K8s) | 低(仅 K8s) | 低(开源) | 高(按用户) | 中(授权费) | 高(企业版) | 低(开源) | + +**图例**: + +- ✅ 原生支持/成熟度高 +- 🟡 需集成/配置/成熟度中 +- ⚠️ 需手动实现/风险较高 +- ❌ 不支持 + +--- + +## 3️⃣ 推荐 Top 3 方案 + +## 🥇 **方案 1:GitLab CI + K8s Runner(综合最优)** + +## **适用场景** + +- 需要完整 DevOps 平台(SCM + CI/CD + 制品库 + 安全扫描) +- 团队已有 GitLab 使用经验或愿意投入学习 +- 私有化部署 + 高并发构建 + 强缓存需求 + +## **参考架构** + +``` +┌─────────────────────────────────────────────────────────┐ +│ GitLab Instance(控制面) │ +│ ├─ Postgres(元数据) │ +│ ├─ Redis(队列/缓存) │ +│ └─ Gitaly(Git 存储) │ +└─────────────────────────────────────────────────────────┘ + ↓ gRPC +┌─────────────────────────────────────────────────────────┐ +│ GitLab Runner(执行面)- K8s Executor │ +│ ├─ Runner Manager(Job 调度) │ +│ ├─ Kubernetes Cluster │ +│ │ ├─ Build Pod(动态创建/销毁) │ +│ │ ├─ PVC(共享缓存:npm/maven/gradle) │ +│ │ └─ Pod Priority Class(优先级调度) │ +│ └─ Auto-scaling(HPA + Cluster Autoscaler) │ +└─────────────────────────────────────────────────────────┘ + ↓ Webhook/API +┌─────────────────────────────────────────────────────────┐ +│ 外部集成 │ +│ ├─ 制品库(Nexus/Harbor) │ +│ ├─ 消息队列(Kafka - 构建事件) │ +│ ├─ 监控(Prometheus + Grafana) │ +│ └─ 远程缓存(MinIO/S3 - Gradle/Bazel cache) │ +└─────────────────────────────────────────────────────────┘ +``` + +## **构建缓存策略** + +1. **依赖缓存**:`.gitlab-ci.yml` 中配置 `cache` 字段,存储到 S3/MinIO[[cnblogs](https://www.cnblogs.com/Sol-wang/p/16775377.html)] +2. **远程构建缓存**:Gradle 配置 `--build-cache`,指向 MinIO endpoint[[youtube](https://www.youtube.com/watch?v=zOu3WOKNUcc)] +3. **Docker 层缓存**:使用 `kaniko` 或 `buildkit` 与 Registry 集成 +4. **缓存命中率目标**:60-80%(通过合理的缓存 key 策略)[[bitrise](https://bitrise.io/blog/post/bitrise-build-cache-reduces-circleci-build-times)] + +## **从 Jenkins 迁移路径** + +1. **Phase 1(2周)** : + + - 部署 GitLab + Runner 测试环境 + - 选取 3-5 个简单项目试点(Java/Node) + - Pipeline 脚本从 Jenkinsfile 转换为 `.gitlab-ci.yml` +2. **Phase 2(4周)** : + + - 迁移 20% 项目(优先选择构建频率低的) + - 构建 Shared Template 库(替代 Jenkins Shared Library) + - 配置缓存体系(MinIO + GitLab Cache) +3. **Phase 3(8周)** : + + - 批量迁移剩余项目 + - Jenkins 保留特殊场景(如复杂 Groovy 逻辑) + - 双轨运行 3 个月后评估下线 Jenkins + +## **风险与限制** + +- **Groovy 转换成本**:复杂 Shared Library 需重写为 YAML + 脚本[[blog.csdn](https://blog.csdn.net/weixin_33628677/article/details/150154969)] +- **插件依赖**:部分 Jenkins 插件无对应 GitLab 功能(需自建或接受功能差异) +- **学习曲线**:团队需熟悉 GitLab Runner 的 executor 模型[[gitlab](https://gitlab.cn/docs/runner/fleet_scaling/_index/)] + +--- + +## 🥈 **方案 2:Tekton + Argo Workflows(云原生最佳)** + +## **适用场景** + +- 已有 K8s 基础设施,团队熟悉 K8s 生态 +- 需要极致的可扩展性和定制化(CI/CD as Code) +- 不需要一体化 SCM 平台(Git 使用 GitHub/Gitea 等) + +## **参考架构** + +``` +┌─────────────────────────────────────────────────────────┐ +│ Git 仓库(GitHub/Gitea/GitLab) │ +└─────────────────────────────────────────────────────────┘ + ↓ Webhook +┌─────────────────────────────────────────────────────────┐ +│ Tekton Triggers(事件监听) │ +│ ├─ EventListener(接收 Webhook) │ +│ ├─ TriggerBinding(参数提取) │ +│ └─ TriggerTemplate(Pipeline 实例化) │ +└─────────────────────────────────────────────────────────┘ + ↓ K8s API +┌─────────────────────────────────────────────────────────┐ +│ Tekton Pipelines(核心引擎) │ +│ ├─ Task(构建单元:npm install/mvn test) │ +│ ├─ Pipeline(编排多个 Task) │ +│ ├─ PipelineRun(执行实例) │ +│ └─ Workspace(PVC 共享工作区 + 缓存) │ +└─────────────────────────────────────────────────────────┘ + ↓ 并行编排 +┌─────────────────────────────────────────────────────────┐ +│ Argo Workflows(复杂 DAG) │ +│ ├─ Workflow Template(复用逻辑) │ +│ ├─ Workflow(复杂依赖关系) │ +│ └─ Argo Events(高级事件源:Kafka/SQS) │ +└─────────────────────────────────────────────────────────┘ + ↓ CloudEvents +┌─────────────────────────────────────────────────────────┐ +│ 可观测与集成 │ +│ ├─ Tekton Dashboard(Web UI) │ +│ ├─ Prometheus(指标) │ +│ ├─ Elasticsearch(日志) │ +│ └─ 消息队列(构建事件 → Kafka) │ +└─────────────────────────────────────────────────────────┘ +``` + +## **构建缓存策略** + +1. **PVC 共享缓存**:定义 Workspace 指向 RWX PVC(存储 npm cache/maven .m2) +2. **远程缓存**:Task 中配置 Gradle/Bazel remote cache 参数 +3. **镜像层缓存**:使用 Tekton Catalog 中的 `buildah`/`kaniko` Task + +## **从 Jenkins 迁移路径** + +1. **Phase 1(4周)** : + + - 部署 Tekton + Dashboard + Triggers + - 创建 Task Catalog(npm-build、maven-test、docker-build 等) + - 试点 5 个项目,编写 Pipeline YAML +2. **Phase 2(6周)** : + + - 编写 Tekton → Kafka 的事件适配器(自定义 Task) + - 集成 Argo Workflows 处理复杂分支逻辑 + - 迁移 30% 项目 +3. **Phase 3(8周)** : + + - 批量迁移,建立 Pipeline 模板库 + - Jenkins 逐步退役 + +## **风险与限制** + +- **学习成本高**:团队需深入理解 K8s CRD、RBAC、PVC 等概念[[wangsen](https://wangsen.site/2024/12/13/Argo-v-s-Tekton/)] +- **UI 弱**:Tekton Dashboard 功能基础,缺少 Jenkins 级别的可视化[[juejin](https://juejin.cn/post/7209839016966914085)] +- **调试困难**:Pipeline 失败时需通过 `kubectl logs` 查看日志 +- **社区分裂**:Tekton vs Argo 社区存在竞争,需选择主导工具[reddit+1](https://www.reddit.com/r/devops/comments/vfpnc8/community_feedback_on_argo_workflows_cd_events_vs/) + +--- + +## 🥉 **方案 3:Buildkite(混合云最佳,但成本高)** + +## **适用场景** + +- 需要极致的构建性能和无限并发 +- 愿意接受"控制面 SaaS + 执行面私有化"的混合模式 +- 预算充足(按用户月费,不按分钟计费) + +## **参考架构** + +``` +┌─────────────────────────────────────────────────────────┐ +│ Buildkite SaaS(控制面 - 托管) │ +│ ├─ Pipeline 管理 │ +│ ├─ 队列调度 │ +│ ├─ GraphQL API │ +│ └─ Webhook 集成 │ +└─────────────────────────────────────────────────────────┘ + ↓ 轮询/WebSocket +┌─────────────────────────────────────────────────────────┐ +│ Buildkite Agent(执行面 - 私有化) │ +│ ├─ K8s 集群(Agent DaemonSet/StatefulSet) │ +│ ├─ Elastic CI Stack(AWS/自建) │ +│ ├─ 自定义 Agent(VM/容器/裸机) │ +│ └─ 无限并发(按 Agent 数量扩展) │ +└─────────────────────────────────────────────────────────┘ + ↓ 插件系统 +┌─────────────────────────────────────────────────────────┐ +│ 插件生态 │ +│ ├─ Docker Plugin(容器构建) │ +│ ├─ S3 Cache Plugin(构建缓存) │ +│ ├─ Artifacts(制品存储) │ +│ └─ 自定义插件(Shell/Go/Ruby) │ +└─────────────────────────────────────────────────────────┘ +``` + +## **构建缓存策略** + +1. **S3 Cache Plugin**:自动缓存目录到 S3/MinIO +2. **Docker Layer Cache**:Agent 本地缓存 + Registry 缓存 +3. **自定义缓存逻辑**:通过插件或脚本实现 Gradle/Bazel 远程缓存 + +## **从 Jenkins 迁移路径** + +1. **Phase 1(2周)** : + + - 注册 Buildkite 账户,部署 Agent 到测试环境 + - 转换 3-5 个 Jenkinsfile 为 `pipeline.yml` +2. **Phase 2(4周)** : + + - 配置 Webhook + 队列策略 + - 迁移 20% 项目 +3. **Phase 3(6周)** : + + - 批量迁移,逐步下线 Jenkins + +## **风险与限制** + +- **成本高**:按用户收费(如 50 用户 × \$15/月 \= \$9000/年),但无限并发[[slant](https://www.slant.co/versus/2482/2485/~gitlab-ci_vs_buildkite)] +- **控制面依赖**:必须依赖 Buildkite SaaS,无法完全私有化 +- **数据主权**:元数据存储在 Buildkite 云端(需评估合规风险) +- **供应商锁定**:Pipeline 语法专有,迁移出去成本高 + +--- + +## 4️⃣ 性能与规模化建议(10万次/年构建) + +## **并发模型计算** + +**假设条件**: + +- 平均每次构建时间:15 分钟 +- 每日构建:270 次(平均) +- 峰值时段(工作日 9:00-18:00):每小时 50 次 + +**并发需求**: + +- 平均并发:`270 次/天 ÷ 24 小时 ÷ 4 (每小时平均) = 11.25 并发` +- 峰值并发:`50 次/小时 ÷ 4 (15分钟) = 12.5 → **约 15 并发**` + +**资源配置建议**: + +``` +# GitLab Runner K8s Executor 示例 +[[runners]] + name = "k8s-runner" + limit = 20 # 最大并发 Job + [runners.kubernetes] + namespace = "gitlab-runner" + cpu_request = "2" + cpu_limit = "4" + memory_request = "4Gi" + memory_limit = "8Gi" + # 动态 Pod,构建后自动销毁 +``` + +## **缓存策略(关键性能优化)** + +## **三层缓存体系** + +1. **L1 本地缓存(Runner/Agent 本地)** + + - **适用**:npm cache、maven .m2、gradle cache + - **存储**:Agent 本地磁盘 / K8s hostPath + - **命中率**:80-90%(同 Agent 复用) + - **风险**:Agent 重启丢失 +2. **L2 分布式缓存(共享存储)** + + - **适用**:多 Runner 共享依赖 + - **存储**:NFS / K8s RWX PVC / MinIO + - **命中率**:60-75% + - **实现**:GitLab Cache 配置[[cnblogs](https://www.cnblogs.com/Sol-wang/p/16775377.html)] + + ``` + cache: + key: ${CI_COMMIT_REF_SLUG} + paths: + - node_modules/ + - .m2/repository/ + policy: pull-push + ``` +3. **L3 远程构建缓存(Gradle/Bazel Remote Cache)** + + - **适用**:增量编译、Monorepo + - **存储**:专用缓存服务(HTTP/gRPC) + - **命中率**:50-70% + - **性能提升**:60-83% 构建加速[[youtube](https://www.youtube.com/watch?v=zOu3WOKNUcc)][[bitrise](https://bitrise.io/blog/post/bitrise-build-cache-reduces-circleci-build-times)] + - **实现**: + + ``` + # Gradle 配置 + buildCache { + remote(HttpBuildCache) { + url = 'http://minio.internal:9000/build-cache/' + push = true + } + } + ``` + +## **缓存一致性与污染处理** + +**问题**:缓存 key 冲突导致错误复用 + +**解决方案**: + +- **精细化 key**:`${OS}-${ARCH}-${COMPILER_VERSION}-${DEPS_HASH}` +- **定期清理**:每周清理 \>30 天未访问缓存 +- **分支隔离**:`master` 与 `feature/*` 使用不同缓存 namespace +- **审计日志**:记录缓存写入/读取,排查污染源 + +## **队列治理** + +**GitLab 示例**: + +``` +build: + resource_group: production # 同一时间只允许 1 个该组 Job + script: mvn clean package + +test: + resource_group: test-pool # 限制测试并发 + script: npm test +``` + +**K8s 示例(Tekton)** : + +``` +apiVersion: scheduling.k8s.io/v1 +kind: PriorityClass +metadata: + name: high-priority-build +value: 1000 # 高优先级(Hotfix/Release) + +--- +apiVersion: tekton.dev/v1beta1 +kind: PipelineRun +spec: + podTemplate: + priorityClassName: high-priority-build +``` + +## **Runner/Agent 伸缩策略** + +**GitLab Runner HPA(K8s)** : + +``` +apiVersion: autoscaling/v2 +kind: HorizontalPodAutoscaler +metadata: + name: gitlab-runner +spec: + scaleTargetRef: + apiVersion: apps/v1 + kind: Deployment + name: gitlab-runner + minReplicas: 3 + maxReplicas: 20 + metrics: + - type: Pods + pods: + metric: + name: gitlab_runner_jobs_queue + target: + type: AverageValue + averageValue: "5" # 每个 Runner 队列 >5 时扩容 +``` + +**Cluster Autoscaler**: + +- K8s 节点池自动扩展(AWS EKS / 阿里云 ACK) +- 冷启动时间:3-5 分钟(需预热策略) + +## **构建隔离(安全与稳定)** + +**三层隔离模型**: + +1. **网络隔离**: + + - K8s NetworkPolicy:限制 Pod 出站访问 + - 构建 Pod 仅允许访问制品库、缓存服务 +2. **资源隔离**: + + - CPU/内存配额(LimitRange + ResourceQuota) + - 磁盘 I/O 限制(StorageClass QoS) +3. **凭据隔离**: + + - K8s Secret + RBAC(每个项目独立 ServiceAccount) + - HashiCorp Vault 动态密钥(构建后自动吊销) + +--- + +## 5️⃣ 二次开发与集成方案 + +## **构建事件对外传递实现** + +## **场景需求** + +将构建开始/成功/失败/产物信息传递给: + +- 内部发布平台 +- 消息通知(钉钉/企业微信) +- 质量分析平台(SonarQube、测试报告) +- 可观测系统(Grafana Dashboard) + +## **方案 1:Webhook Push(推荐 - 简单场景)** + +**GitLab CI 示例**: + +``` +stages: + - build + - notify + +build: + stage: build + script: mvn clean package + after_script: + - | + curl -X POST https://internal-api.company.com/builds \ + -H "Content-Type: application/json" \ + -d '{ + "project": "'$CI_PROJECT_NAME'", + "commit": "'$CI_COMMIT_SHA'", + "status": "'$CI_JOB_STATUS'", + "artifacts": "'$CI_JOB_URL'/artifacts" + }' +``` + +**Buildkite 插件**: + +``` +steps: + - label: ":package: Build" + command: npm run build + plugins: + - artifacts#v1.5.0: + upload: "dist/*" + - webhook-notify#v1.0.0: # 自定义插件 + url: https://internal-api.company.com/builds + payload: + build_id: ${BUILDKITE_BUILD_ID} + status: ${BUILDKITE_BUILD_STATUS} +``` + +**优点**:实现简单,延迟低 +**缺点**:无重试机制,目标服务故障导致丢失 + +--- + +## **方案 2:消息队列(推荐 - 高可靠场景)** + +**架构**: + +``` +CI/CD 工具 → Kafka Topic (build-events) → 消费者(发布平台/通知服务) +``` + +**Tekton 自定义 Task**: + +``` +apiVersion: tekton.dev/v1beta1 +kind: Task +metadata: + name: kafka-notify +spec: + params: + - name: event-type + type: string + - name: build-status + type: string + steps: + - name: send + image: confluentinc/cp-kafka:7.3.0 + script: | + echo '{ + "event": "$(params.event-type)", + "status": "$(params.build-status)", + "timestamp": "'$(date -Iseconds)'" + }' | kafka-console-producer \ + --broker-list kafka.internal:9092 \ + --topic build-events +``` + +**Jenkins 插件**(假设使用 Kafka Plugin): + +``` +pipeline { + agent any + stages { + stage('Build') { + steps { + sh 'mvn clean package' + } + } + } + post { + always { + kafkaPublish( + topic: 'build-events', + message: """ + { + "project": "${env.JOB_NAME}", + "build": "${env.BUILD_NUMBER}", + "status": "${currentBuild.result}" + } + """ + ) + } + } +} +``` + +**优点**: + +- 高可靠(持久化、重试) +- 解耦(消费者异步处理) +- 可审计(事件日志) + +**缺点**: + +- 需维护 Kafka 集群 +- 复杂度增加 + +--- + +## **方案 3:API 轮询(补充方案)** + +**场景**:外部系统主动拉取构建状态 + +**GitLab API**: + +``` +# 获取最新 Pipeline 状态 +curl -H "PRIVATE-TOKEN: " \ + "https://gitlab.company.com/api/v4/projects/123/pipelines/latest" +``` + +**Buildkite GraphQL**: + +``` +query { + pipeline(slug: "company/repo") { + builds(first: 10) { + edges { + node { + number + state + createdAt + url + } + } + } + } +} +``` + +**优点**:无需 CI/CD 工具配置 +**缺点**:实时性差,API 调用频率限制 + +--- + +## **接口设计要点(事件 Schema)** + +**标准化事件结构**(参考 CloudEvents 规范): + +``` +{ + "specversion": "1.0", + "type": "build.completed", + "source": "gitlab-ci/project/123", + "id": "a3b7c8d9-1234-5678-90ab-cdef12345678", + "time": "2026-02-04T15:30:00Z", + "datacontenttype": "application/json", + "data": { + "project": "backend-service", + "branch": "main", + "commit": "abc123def456", + "build_number": 4567, + "status": "success", + "duration_seconds": 320, + "artifacts": [ + { + "name": "backend-service.jar", + "url": "https://nexus.company.com/repository/releases/backend-service-1.2.3.jar", + "checksum": "sha256:abcdef1234567890..." + } + ], + "test_results": { + "total": 1523, + "passed": 1520, + "failed": 3 + }, + "metadata": { + "triggered_by": "user@company.com", + "cache_hit_rate": 0.78 + } + } +} +``` + +**幂等性设计**: + +- 事件 ID 唯一(UUID) +- 消费者端去重(Redis/数据库记录已处理事件 ID) + +--- + +## 6️⃣ 风险清单与验证计划(PoC) + +## **PoC 周期:2-4 周** + +## **Week 1-2:基础功能验证** + +| **验证项** | **成功标准** | **测试方法** | +| -- | ------------------------------------- | ------------------------------- | +| **多语言构建** | Node 16/18/20、JDK 8/11/17 构建成功 | 创建包含多版本矩阵的 Pipeline | +| **Maven 并行构建** | 构建时间缩短 \>30% | 对比单线程 vs 多模块并行 | +| **多分支触发** | PR/MR 自动触发构建,状态回写 Git | 提交 PR 测试 | +| **缓存基础功能** | npm/maven 依赖缓存命中率 \>50% | 连续两次构建对比时间 | +| **K8s 动态调度** | Pod 自动创建/销毁,资源隔离有效 | `kubectl top pods`监控资源 | + +## **Week 3:性能与规模测试** + +| **验证项** | **成功标准** | **测试方法** | +| -- | -------------------------------------- | ------------------------------- | +| **并发吞吐** | 15 并发构建,队列时间 \<2 分钟 | JMeter/自定义脚本触发并发构建 | +| **缓存命中率** | 二次构建缓存命中率 \>60% | 分析构建日志 | +| **弹性伸缩** | Runner 自动扩展至 15 个,缩容至 3 个 | 模拟峰谷流量 | +| **稳定性** | 连续运行 100 次构建,成功率 \>99% | 批量触发构建,记录失败率 | + +## **Week 4:集成与可观测性** + +| **验证项** | **成功标准** | **测试方法** | +| -- | ----------------------------------------- | ------------------------ | +| **事件传递** | 构建事件 100% 发送至 Kafka/Webhook | 检查消息队列消费日志 | +| **API 调用** | GraphQL/REST API 响应时间 \<500ms | Postman/curl 测试 | +| **监控指标** | Prometheus 采集到构建时长、成功率等指标 | Grafana Dashboard 验证 | +| **日志审计** | 所有构建操作可追溯(用户、时间、参数) | 查询审计日志 | +| **凭据安全** | Secret 不泄漏到日志,仅授权项目可访问 | 安全扫描 + 权限测试 | + +## **关键指标收集** + +**性能指标**: + +``` +- 平均排队时间(Queue Time):目标 <2 分钟 +- 平均构建时间(Build Time):目标缩短 20%(相比 Jenkins) +- 缓存命中率(Cache Hit Rate):目标 60-80% +- P99 构建时长:目标 <25 分钟 +``` + +**成本指标**: + +``` +- 单次构建成本(计算资源): + = (vCPU 小时数 × CPU 单价 + 内存 GB·小时 × 内存单价) / 构建次数 + 目标:99% +- 系统可用性(Uptime):>99.5% +- 故障恢复时间(MTTR):<30 分钟 +``` + +## **迁移成本评估** + +**技术债务清单**: + +1. **Pipeline 脚本数量**:统计现有 Jenkinsfile 总数 +2. **Shared Library 依赖**:分析哪些可复用、哪些需重写 +3. **插件依赖**:列出关键插件,找对应替代方案 +4. **定制化逻辑**:识别硬编码在 Groovy 中的业务逻辑 + +**迁移时间估算**(假设 100 个项目): + +``` +- 简单项目(标准 npm/maven):0.5 天/项目 = 50 天 +- 中等项目(多 stage、缓存依赖):1 天/项目 = 50 天 +- 复杂项目(Groovy 重逻辑):3 天/项目 = 150 天 +总计:250 人天 ≈ 2-3 人团队 × 4 个月 +``` + +--- + +## 7️⃣ 最终建议与决策树 + +## **决策树** + +``` +开始 + │ + ├─ 是否已有 K8s 基础设施? + │ ├─ 是 → 团队对 K8s 熟悉度? + │ │ ├─ 高 → **Tekton + Argo** (云原生最佳) + │ │ └─ 中/低 → **GitLab CI + K8s Runner** + │ └─ 否 → 是否愿意引入 K8s? + │ ├─ 是 → **GitLab CI + K8s Runner** (平滑过渡) + │ └─ 否 → **GitLab CI + Docker Executor** 或 **Jenkins 优化** + │ + ├─ 是否需要完整 DevOps 平台(SCM + CI/CD)? + │ ├─ 是 → **GitLab** (All-in-One) + │ └─ 否 → 已有 Git 服务 → **Buildkite / Tekton / Drone** + │ + ├─ 预算情况? + │ ├─ 充足 → **Buildkite / TeamCity** (商业支持) + │ └─ 有限 → **GitLab CI / Tekton** (开源) + │ + └─ 迁移风险承受度? + ├─ 低(稳健迁移)→ **GitLab CI** (与 Jenkins 差异小) + └─ 高(激进重构)→ **Tekton** (云原生架构) +``` + +## **综合推荐(基于你的场景)** + +**场景回顾**: + +- ✅ 10 万次/年构建(中等规模) +- ✅ 私有化部署 +- ✅ 强缓存需求(Maven/Gradle/npm) +- ✅ 可二次开发(API + 事件集成) +- ✅ 从 Jenkins 迁移 + +**最佳选择**:**GitLab CI + K8s Runner** + +**理由**: + +1. **功能完整**:覆盖 SCM + CI/CD + 制品库,减少工具碎片化 +2. **迁移成本适中**:YAML 语法接近 Jenkinsfile,学习曲线平缓[[cnblogs](https://www.cnblogs.com/Sol-wang/p/16775377.html)] +3. **缓存成熟**:原生支持分布式缓存 + Gradle/Bazel 远程缓存[[youtube](https://www.youtube.com/watch?v=zOu3WOKNUcc)] +4. **可扩展性强**:K8s Runner 支持动态伸缩,满足 10 万次/年需求[[gitlab](https://gitlab.cn/docs/runner/fleet_scaling/_index/)] +5. **API 丰富**:REST + GraphQL,易于集成外部系统 +6. **社区活跃**:文档完善,问题快速解决 +7. **成本低**:开源社区版免费,企业版功能可选 + +**替代选择**: + +- 如果团队 K8s 专家充足 → **Tekton**(更灵活,但学习成本高) +- 如果预算充足且追求极致性能 → **Buildkite**(无限并发,但成本高) + +--- + +## 8️⃣ 下一步行动项 + +## **立即行动(本周)** + +1. ✅ 确定 PoC 团队(2-3 人) +2. ✅ 准备 K8s 测试环境(或利用现有) +3. ✅ 部署 GitLab CE + GitLab Runner(K8s Executor) +4. ✅ 选取 3 个试点项目(简单 + 中等 + 复杂各 1 个) + +## **第 1-2 周:基础验证** + +1. 转换试点项目的 Jenkinsfile → `.gitlab-ci.yml` +2. 配置分布式缓存(MinIO) +3. 测试多语言、多分支构建 + +## **第 3 周:性能测试** + +1. 并发压测(15 并发) +2. 缓存命中率优化 +3. 监控指标采集(Prometheus + Grafana) + +## **第 4 周:集成测试** + +1. 配置 Webhook → Kafka +2. API 集成测试(获取构建状态) +3. 编写 PoC 报告,决策是否全面推广 + +## **第 2-6 月:全面迁移** + +1. 批量迁移项目(分批次) +2. 培训团队(GitLab CI 最佳实践) +3. 建立 Shared Template 库 +4. Jenkins 逐步下线(保留 6 个月作为备份) + +--- + +## 📚 参考资料 + +- GitLab Runner 自动扩缩容文档[gitlab+1](https://gitlab.cn/docs/runner/configuration/autoscale/) +- GitLab CI/CD 私有化部署指南[[cnblogs](https://www.cnblogs.com/Sol-wang/p/16775377.html)] +- Bazel/Gradle 远程缓存性能分析[[bitrise](https://bitrise.io/blog/post/bitrise-build-cache-reduces-circleci-build-times)][[youtube](https://www.youtube.com/watch?v=zOu3WOKNUcc)] +- Tekton vs Argo Workflows 对比[wangsen+1](https://wangsen.site/2024/12/13/Argo-v-s-Tekton/) +- 高并发 CI/CD 架构设计[csdn+1](https://blog.csdn.net/sinat_28461591/article/details/148729218) +- Jenkins Shared Library 迁移策略[[blog.csdn](https://blog.csdn.net/weixin_33628677/article/details/150154969)] + +--- + +**报告生成时间**:2026 年 2 月 4 日 +**有效期**:建议 3 个月内复核(CI/CD 工具演进快) + +如有具体技术细节需要深入(如某个工具的配置示例、成本计算模型、PoC 脚本等),请随时追问! + +添加到后续问题 + +检查来源 \ No newline at end of file diff --git a/16-ProjectMoneyM-转FireFlyIII/1-原始需求/0-产品经理-prompt.md b/16-ProjectMoneyM-转FireFlyIII/1-原始需求/0-产品经理-prompt.md new file mode 100644 index 0000000..eb5bae5 --- /dev/null +++ b/16-ProjectMoneyM-转FireFlyIII/1-原始需求/0-产品经理-prompt.md @@ -0,0 +1,21 @@ +你现在是一名策略产品经理,你擅长进行市场研究和竞品分析,以制定产品策略。你能把握行业趋势,了解用户需求,并在此基础上优化产品功能和用户体验。请在这个角色下为我解答以下问题。 + +---- + +你是一名出色的产品经理,能够根据用户的初始需求,理解用户需求的真实需求意图,改善客户不够完善的需求,形成专业、简练的需求文档。并且能够在基础需求上优化产品的额设计和功能 + +请根据要求,进行深度的思考,优化[1-初始需求稿.md],直接给出优化后的PRD + +注意及要求如下 +1. 括号内的内容需要关注,需要根据括号内的内容进行修改,是你需要给出建议的内容,正式文档中应该去掉括号及内容 +2. 必要时候应该联网搜索,查询开源的项目实现等 + +---- + +你是一名出色的产品经理,请你根据[1-初始需求稿.md]客户的原始需求,审查[2-优化产品需求文档PRD.md],检查PRD文档是否完全满足原始需求;如果有更加优秀的设计方案,请给出修改建议 + +---- + +你是一名出色的产品经理,能够根据用户的初始需求,理解用户需求的真实需求意图,改善客户不够完善的需求,形成专业、简练的需求文档。并且能够在基础需求上优化产品的额设计和功能 + +你之前根据[1-初始需求稿.md]输出了[2-优化产品需求文档PRD.md], 目前初始需求有一些更新,见[1.1-初始需求稿.md],请你详细对比[1.1-初始需求稿.md]和[1-初始需求稿.md]之间的差异, 修改[2-优化产品需求文档PRD.md],得到新的需求文档 \ No newline at end of file diff --git a/16-ProjectMoneyM-转FireFlyIII/1-原始需求/1-初始需求稿.md b/16-ProjectMoneyM-转FireFlyIII/1-原始需求/1-初始需求稿.md new file mode 100644 index 0000000..cdcae43 --- /dev/null +++ b/16-ProjectMoneyM-转FireFlyIII/1-原始需求/1-初始需求稿.md @@ -0,0 +1,83 @@ +# 个人财务分析系统 +``` 项目名称: ProjectMoneyM ``` +``` 项目版本: v1.0 ``` +``` 项目编制日期: 2026-02-26 ``` + +## 数据来源 + +1. 数据来源 +| 数据来源 | 最长周期 | 文件格式 | 说明 | 数据维度 | +| --- | --- | --- | --- | --- | +| 支付宝账单 | 1年 | csv | 第一来源 | 最全 | +| 微信账单 | 3个月 | csv | 第二来源 | 第二全 | +| 招商银行 | 1年 | pdf | 第三来源 | 第三全 | +| 京东商城 | 1年 | pdf | 第四来源 | 第四全 | + +2. 数据解析工具 + 1. 能够读取不同格式的账单来源 + 2. 能够通过OCR的方式解析特定的收入数据 + + +## 数据清洗及标准化 + +1. 时间维度清洗 + 1. 需要统一时间维度,统一为东八区时间,格式为yyyy-MM-dd HH:mm:ss + 2. 数据展示环节 需要能够通过时间段进行筛选查询收支数据 +2. 支付项目清洗 + 1. 需要过滤重复的支付项 + 2. 需要明确支付途径和支付卡 + 3. 例如,一笔支出,银行账单会记录支出,支付宝或者微信会记录支出,需要将这些重复的支付项合并 + 4. 支付途径为: 支付宝,微信,云闪付,京东,美团,拼多多 + 5. 实际支付卡为: 信用卡,借记卡,余额宝,微信钱包,支付宝钱包 + 6. 支出项目的账本归类 + 1. 一笔支出可以归于一个或者多个账本 + 2. 一笔支出需要在日常开支中进行分析,也需要在过年支出这种特殊的账本中进行分析 +3. 支付金额清洗 + 1. 需要统一为标准的数据格式 +4. 支出去向清洗 + 1. 需要将支出进行分类 + 2. 请参考支付宝的支出分类 + + +## 收支情况 展示内容 +```此部分重要使用前端图表工具进行绘图展示``` + +### 收支分析(请给出能够展示的图形类型) + 1. 需要直观的看出结余情况, 收入大于支出,支出大于收入的对比 + 2. 时间维度为,月度,季度,年度,重点展示月度收支情况 + 3. 收支的最小维度为月度 + + +### 收入分析(请给出能够展示的图形类型) + +#### 收入趋势 + 1. 能够根据不同的时间维度进行收入的对比 + 2. 能够直观的展示收入的趋势 +#### 收入总览 + 1. 收入来源占比分析 + 2. 时间维度,重点展示年度收入,季度收入 + 3. 收入的最小维度为月度 + +#### 收入 + +### 支出分析(请给出能够展示的图形类型) +#### 支出趋势 + 1. 能够根据不同的时间维度进行支出的对比 + 2. 能够直观的展示支出的趋势 +#### 支出总览 + 1. 支出去向占比分析 + 2. 时间维度,重点展示年度支出,季度支出 + 3. 支出的最小维度为月度 + + +### 展示内容导出 +1. 支持将展示内容导出为图片 +2. 支持将展示内容导出为PDF文件 + +## 技术栈 +1. Golang +2. Vue +3. TypeScript +4. SQLite +5. ECharts(寻找适合的图表工具,不限于ECharts) + diff --git a/16-ProjectMoneyM-转FireFlyIII/1-原始需求/2-1-优化产品需求文档PRD.md b/16-ProjectMoneyM-转FireFlyIII/1-原始需求/2-1-优化产品需求文档PRD.md new file mode 100644 index 0000000..89c70d1 --- /dev/null +++ b/16-ProjectMoneyM-转FireFlyIII/1-原始需求/2-1-优化产品需求文档PRD.md @@ -0,0 +1,106 @@ +# 产品需求文档 (PRD): ProjectMoneyX 个人全景财务分析系统 + +| 文档属性 | 详情 | +| --- | --- | +| **项目名称** | ProjectMoneyX | +| **版本号** | v1.2 (基于开源 ETL 架构优化版) | +| **编制日期** | 2026-02-26 | +| **文档状态** | 进行中 | + +## 1. 项目背景与目标 + +### 1.1 项目背景 + +随着移动支付的普及,个人财务数据分散在支付宝、微信、各家银行及电商平台中。用户面临“账单碎片化”、“流水重复记录”等痛点。传统的记账软件通常依赖手动记录或单一的账单导入,缺乏灵活的规则引擎来处理复杂的跨账户对账。 + +### 1.2 项目目标 + +构建一套自动化、高精度的个人财务分析系统。借鉴开源社区成熟的双轨制记账流转架构,通过引入 `Provider` 解析器与 `Translate` 规则引擎,实现多源数据的标准化转换(IR),并利用算法解决跨账户流水重复问题,提供多维度的收支分析与预算管理功能。 + +--- + +## 2. 核心系统架构:ETL 数据工作流 + +参考业内成熟方案,系统底层采用高度解耦的管道架构,确保后续极强的可扩展性: + +**数据流转路径:** `原始账单 (Raw Files) -> 提供方解析 (Provider) -> 中间表示 (IR) -> 规则转换 (Translate) -> 数据库标准账单` + +* **Provider 层:** 专注于“读”。屏蔽不同账单格式(CSV, PDF, Excel)的差异。 +* **IR 层 (Intermediate Representation):** 统一的数据结构协议,作为 Provider 和 Translate 的桥梁。 +* **Translate 层:** 专注于“洗”。基于 YAML/JSON 规则配置,执行分类映射、时间标准化与账户归属。 + +--- + +## 3. 数据采集与 Provider 模块 (Data Ingestion) + +针对不同来源的账单,建立独立的 Provider 适配器。当某银行账单格式更新时,仅需修改或新增对应的 Provider,不影响系统核心逻辑。 + +| 提供方 (Provider) | 原始格式 | 核心提取字段 | 数据权重 | 提取说明 | +| --- | --- | --- | --- | --- | +| **Alipay (支付宝)** | CSV | 订单号、商户、商品明细、金额 | **L1 (最高)** | 标准 CSV 解析,作为消费类主数据。 | +| **WeChat (微信支付)** | CSV | 交易单号、交易对方、交易类型 | **L2** | 预处理跳过表头,提取转账与红包标记。 | +| **Banks (招商/工行等)** | PDF/XLS | 交易日、交易摘要、收支金额 | **L3** | 作为资金实际扣款核对依据 (Reconciliation)。 | +| **JD/Meituan (电商)** | PDF/CSV | 订单明细、支付通道 | **L3** | 重点关注白条/月付等信用支付记录。 | + +--- + +## 4. 数据转换与清洗逻辑 (Translate & Cleaning) + +Translate 层是数据质量的核心把控者,负责将 IR 数据转换为最终的财务记录,并解决数据冲突。 + +### 4.1 Translate 规则引擎 + +建立基于配置文件的映射规则,实现自动化数据归位: + +* **时间与时区标准化:** 统一转换为 ISO 8601 格式,所有国内交易归一化为东八区时间。 +* **账户路由 (Account Routing):** * *规则示例:* 当 Provider 为 `Alipay`,且原始数据中的支付方式为“招商银行信用卡”时,资金来源(Funding Source)自动映射至用户的“招行信用卡”实体账户。 +* **智能分类映射 (Category Mapping):** +* 根据交易对方 (Peer) 或 商品说明 (Item) 进行正则匹配。 +* *规则示例:* `Peer` 包含“星巴克”或“瑞幸” -> 映射分类为 [餐饮-咖啡]。 + + + +### 4.2 交易链路合并与去重算法 (De-duplication) + +同一笔交易会在支付平台(如微信)和资金源(如银行卡)各产生一条流水。系统通过**时间窗与金额双重校验**进行链路合并,而非粗暴删除。 + +**核心算法逻辑:** +设高权重账单记录为 $T_{primary}$(如支付宝),低权重账单记录为 $T_{secondary}$(如银行卡)。 +当同时满足以下条件时,判定为同一条交易链路: + +$$| Time(T_{primary}) - Time(T_{secondary}) | \le \Delta t \quad (\text{建议 } \Delta t = 120s)$$ + +$$Amount(T_{primary}) = Amount(T_{secondary})$$ + +**处理策略:** + +1. 将两条记录在底层数据库建立关联(Parent-Child 或 LinkID)。 +2. 前端展示时,**合并为一笔记录**。保留 $T_{primary}$ 的丰富消费明细(如分类、商户名),将 $T_{secondary}$ 的账户信息作为该笔消费的资金出处。 + +--- + +## 5. 核心功能模块详述 + +### 5.1 全景仪表盘 (Dashboard) + +* **资产负债表:** 实时聚合各账户总资产、总负债(信用卡/白条),计算净资产。 +* **现金流概览:** 本月总收入 vs 总支出,环比上月 (MoM) 增减百分比。 + +### 5.2 账单查询与多维分析 + +* **组合漏斗筛选:** 支持时间范围、金额区间、支付渠道、资金账户、交易分类的多条件交叉查询。 +* **可视化图表:** +* **消费结构:** 饼图展示各大类的支出占比。 +* **资金流向 (Sankey Diagram):** 桑基图直观展示“收入源 -> 资金池 (账户) -> 支出分类”的完整链路。 + + +### 5.3 预算管理 + +* **精细化限额:** 支持全局预算和分类预算(例如:设定“交通”每月额度 1000 元)。 +* **阈值预警:** 当分类支出进度达到 80% 和 100% 时,系统触发视觉高亮预警。 + +--- + +## 6. 非功能需求 (NFR) + +* **数据隐私 (Local-First):** 财务数据极其敏感,系统解析 (Provider) 和转换 (Translate) 过程应优先在客户端(本地环境)执行,拒绝未经加密的云端明文传输。 \ No newline at end of file diff --git a/16-ProjectMoneyM-转FireFlyIII/1-原始需求/2-优化产品需求文档PRD.md b/16-ProjectMoneyM-转FireFlyIII/1-原始需求/2-优化产品需求文档PRD.md new file mode 100644 index 0000000..06056ec --- /dev/null +++ b/16-ProjectMoneyM-转FireFlyIII/1-原始需求/2-优化产品需求文档PRD.md @@ -0,0 +1,139 @@ +# 产品需求文档 (PRD): ProjectMoneyX 个人全景财务分析系统 + +| 文档属性 | 详情 | +| --- | --- | +| **项目名称** | ProjectMoneyX | +| **版本号** | v1.1 (优化版) | +| **编制日期** | 2026-02-26 | + +## 1. 项目背景与目标 + +### 1.1 项目背景 + +随着移动支付的普及,个人财务数据分散在支付宝、微信、各家银行APP及电商平台中。用户难以通过单一平台获取全景财务状况,面临“账单碎片化”、“流水重复记录”、“统计维度单一”等痛点。 + +### 1.2 项目目标 + +构建一套自动化、高精度的个人财务分析系统。通过ETL(抽取、转换、加载)技术整合多源数据,利用算法解决跨账户流水重复问题,提供多维度的收支分析、资产趋势及预算管理功能,帮助用户实现“上帝视角”的财务管控。 + +--- + +## 2. 数据源与采集规范 (Data Ingestion) + +系统需支持多格式、多来源的账单导入,并建立可扩展的解析适配器模式。 + +| 数据来源 | 原始格式 | 数据周期 | 解析策略 | 数据权重 | 备注 | +| --- | --- | --- | --- | --- | --- | +| **支付宝** | CSV | 1年 | Pandas直接读取 | **L1 (最高)** | 包含商品明细,作为消费类主数据 | +| **微信支付** | CSV | 3个月 | Pandas预处理 (表头清洗) | **L2** | 包含转账与社交红包,需特殊标记 | +| **招商银行** | PDF | 1年 | 文本流解析 (pdfplumber) | **L3** | 作为资金来源核对依据 (Reconciliation) | +| **京东金融** | PDF/XLS | 1年 | 文本流解析 / OCR辅助 | **L3** | 重点关注“白条”类信贷数据 | +| **云闪付** | PDF/CSV | 1年 | 适配器解析 | **L3** | 银联通道补充数据 | + +**功能要求:** + +* **适配器模式(Adapter Pattern):** 针对不同来源开发独立的解析类(Parser Class),当银行账单格式变更时,仅需更新对应解析器。 +* **OCR 增强解析:** 针对图片格式的账单或非标准的扫描版PDF,集成 OCR 引擎(如 PaddleOCR)进行关键字段(日期、金额、商户)提取。 + +--- + +## 3. 数据清洗与核心逻辑 (Data Cleaning & Logic) + +这是本系统的核心壁垒,重点解决多渠道数据冲突与标准化问题。 + +### 3.1 时间维度标准化 + +* **存储标准:** 所有交易时间戳统一转换为 **ISO 8601** 格式存储。 +* **时区处理:** 统一归一化为 `UTC+8`。若涉及跨国交易(如外币信用卡),需保留原始交易币种和时间,并记录当期汇率。 +* **查询支持:** 数据库层需支持基于时间窗口(Time Window)的聚合查询(如:`BETWEEN '2026-02-01' AND '2026-02-28'`)。 + +### 3.2 交易去重与链路合并 (De-duplication & Linkage) + +初始需求中提到的“重复项”实际上是“同一笔交易在不同账户的映射”。系统不应简单删除,而应建立**交易链路(Transaction Linkage)**。 + +**核心算法逻辑:** +设支付宝账单记录为 $T_{ali}$,银行账单记录为 $T_{bank}$。 +当满足以下条件时,判定为同一笔交易: + +$$| Time(T_{ali}) - Time(T_{bank}) | \le \Delta t \quad (\text{建议 } \Delta t = 120s)$$ + +$$Amount(T_{ali}) = Amount(T_{bank})$$ + +**处理策略:** + +1. **合并展示:** 将两条记录关联。 +* **主记录(保留):** 支付宝/微信记录(因其包含具体的商户名、商品名、消费分类)。 +* **辅记录(隐藏/标记):** 银行卡记录标记为“资金划转(Transfer)”或“支付源扣款”。 + + +2. **账户归属明确:** +* **支付渠道(Payment Channel):** 支付宝、微信、云闪付、美团。 +* **资金账户(Funding Source):** 招商银行信用卡、工商银行储蓄卡、京东白条、余额宝。 +* *示例:* 用户在淘宝买衣服,用支付宝绑定的招行卡支付。系统记录为:**支出 200元 (分类:服饰)**,支付渠道:**支付宝**,资金来源:**招行信用卡**。 + + + +### 3.3 智能分类 (Smart Categorization) + +* **多级分类体系:** +* 一级分类:餐饮、交通、购物、居住、娱乐、医疗、金融。 +* 二级分类:早餐/正餐、地铁/打车、数码/服饰、房租/水电。 + + +* **关键词映射:** 建立 `Merchant_Keyword_Map` 表。 +* 例:包含“星巴克”、“瑞幸” -> 自动归类为 [餐饮-咖啡]。 +* 例:包含“中国石油” -> 自动归类为 [交通-加油]。 + + +* **人工修正与学习:** 用户手动修改某一笔交易分类后,系统询问“是否将该商户后续交易默认应用此分类”。 + +--- + +## 4. 功能模块详述 + +### 4.1 仪表盘 (Dashboard) + +* **全景资产卡片:** 显示总资产、总负债(信用卡+白条+花呗)、净资产。 +* **本月收支概览:** * 当月支出 vs 上月同期环比 (MoM)。 +* 预算执行进度条(如:本月预算剩余 30%)。 + + +* **收支趋势图:** 折线图展示近12个月的收支波动。 + +### 4.2 账单查询与分析 + +* **高级筛选器:** 支持组合条件筛选: +* 时间范围(自定义/本周/本月/本年)。 +* 金额区间(如:> 1000元的大额支出)。 +* 支付渠道 & 资金账户。 +* 交易分类。 +* 关键词搜索(如:“京东”)。 + + +* **多维图表:** +* [饼图] 消费结构分析(哪类钱花得最多)。 +* [堆叠柱状图] 支付渠道依赖度分析。 +* [桑基图 (Sankey Diagram)] 资金流向可视化(从收入 -> 账户 -> 支出类别)。 + + + +### 4.3 预算与预警 + +* **预算设置:** 支持总预算及分分类预算(如:“餐饮”每月限额 3000元)。 +* **超支预警:** 当某一类别支出达到预算的 80% 时,界面高亮提示。 + +--- + +## 5. 非功能需求 (NFR) + +### 5.1 数据隐私与安全 + +* **本地优先(Local-First):** 鉴于财务数据极度敏感,建议所有数据解析、清洗、存储默认在用户本地电脑中完成。 + +--- +## 技术栈 +1. Golang +2. Vue +3. TypeScript +4. SQLite +5. ECharts(寻找适合的图表工具,不限于ECharts) \ No newline at end of file diff --git a/16-ProjectMoneyM-转FireFlyIII/2-概要详细设计/0-概要设计prompt.md b/16-ProjectMoneyM-转FireFlyIII/2-概要详细设计/0-概要设计prompt.md new file mode 100644 index 0000000..8dccb39 --- /dev/null +++ b/16-ProjectMoneyM-转FireFlyIII/2-概要详细设计/0-概要设计prompt.md @@ -0,0 +1,33 @@ +你是一名资深的软件系统架构师,具备以下核心职责与能力,绘图请使用mermaid语言: + +## 需求分析与理解 + +- 深度解读产品需求文档(PRD),识别业务目标、功能需求与非功能性需求 +- 分析需求间的依赖关系与优先级,识别潜在的技术风险与挑战 + +## 架构设计与规划 + +- 设计高可用、可扩展、高性能的系统架构,确保系统健壮性与安全性 +- 制定技术选型方案,包括开发语言、框架、中间件、数据库等关键技术栈 +- 绘制多层次架构图(系统架构图、数据流图、组件交互图) +- 定义模块划分、接口规范、数据模型与核心算法策略 +- 规划系统分层结构(展现层、业务层、数据层),明确各层职责边界 + +## 方案设计与输出 + +- 针对核心需求点提供详细的技术解决方案,包含实现路径与备选方案 +- 设计关键业务流程的时序图与状态机,确保逻辑清晰完整 +- 输出规范化的《系统详细设计说明书》,包含架构设计、接口定义、数据库设计等完整文档 + +## 技术栈说明 +- 后端开发技术栈 Golang GROM GIN +- 前端开发技术栈 Vue3 TypeScript Vuetify + +## 参考项目 +- 项目有非常完善的数据清洗工具,基本满足了数据读取部分,可以摘取此项目的数据translate provider部分代码 [double-entry-generator](https://github.com/deb-sig/double-entry-generator) + +请根据[2-优化产品需求文档PRD.md],按照上述的要求,输出系统详细设计说明书 + + + +你之前根据[2-优化产品需求文档PRD.md]输出了[3-详细设计说明书.md], 目前PRD需求有一些更新,见[2.1-优化产品需求文档PRD.md],请你详细对比[2.1-优化产品需求文档PRD.md]和[2-优化产品需求文档PRD.md]之间的差异, 修改[3-详细设计说明书.md],得到新的需求文档.要求尽量不改动[3-详细设计说明书.md]的初始设计,只改动差异化部分的设计 \ No newline at end of file diff --git a/16-ProjectMoneyM-转FireFlyIII/2-概要详细设计/3-详细设计说明书.md b/16-ProjectMoneyM-转FireFlyIII/2-概要详细设计/3-详细设计说明书.md new file mode 100644 index 0000000..2f4d816 --- /dev/null +++ b/16-ProjectMoneyM-转FireFlyIII/2-概要详细设计/3-详细设计说明书.md @@ -0,0 +1,1785 @@ +# 家庭游戏中心 (Family Game Center) - 产品需求文档 (PRD) + +**文档版本:** 1.0 +**最后更新:** 2024-12-29 +**状态:** 已审批,进入开发阶段 +**目标平台:** Linux (Ubuntu 22.04 LTS) / 开发平台: Windows 11 + +--- + +## 📋 文档目录 + +1. [项目概述](#项目概述) +2. [功能需求](#功能需求) +3. [技术方案](#技术方案) +4. [系统架构](#系统架构) +5. [开发规范](#开发规范) +6. [API 设计](#api-设计) +7. [数据库设计](#数据库设计) +8. [UI/UX 设计规范](#uiux-设计规范) +9. [安全需求](#安全需求) +10. [测试计划](#测试计划) +11. [部署方案](#部署方案) +12. [验收标准](#验收标准) + +--- + +## 项目概述 + +### 1.1 项目背景 + +为父母(年龄 50+ 岁)设计的易用家庭游戏平台。该平台旨在提供一个完全锁定的游戏环境,使非技术用户无法误操作进入系统,只能使用游戏功能。 + +### 1.2 项目目标 + +| 目标 | 说明 | +|------|------| +| **易用性** | 父母无计算机知识也能独立使用 | +| **安全性** | 系统级锁定,用户无法退出或破坏系统 | +| **稳定性** | 无中断运行 48+ 小时 | +| **游戏性** | AI 对手难度可调,赢率 40-60% | +| **维护性** | 单人可维护和更新 | + +### 1.3 产品范围 + +**包含:** +- 4 款主要游戏 (斗地主、拖拉机、卡五星、赛车) +- Linux Kiosk 启动器 +- 响应式菜单 UI +- 本地 AI 对手 +- 游戏存档管理 +- 基础统计功能 + +**不包含:** +- 网络在线多人对战 +- 云同步和备份 +- 用户账户系统 +- 第三方集成 +- 语音/视频功能 + +### 1.4 项目成功标准 + +✓ MVP 版本 (斗地主 + 菜单): 6-8 周 +✓ 完整版 (全部游戏): 12-18 周 +✓ 总成本: 硬件 5-15K,软件 0 元 +✓ 团队规模: 1-3 人 +✓ 风险等级: 低-中等 + +--- + +## 功能需求 + +### 2.1 用户故事 + +#### 故事 1: 启动和菜单 +``` +作为 父亲 +我想 开机后直接进入游戏菜单 +这样 我无需学习系统操作,只需选择想玩的游戏 +``` + +**验收标准:** +- 系统启动后 5 秒内进入菜单 +- 菜单显示 4 个游戏卡片 +- 卡片字体 32px+,易于阅读 +- 按钮 80px+,易于点击 +- 菜单背景颜色高对比度 (WCAG AAA) + +#### 故事 2: 启动游戏 +``` +作为 母亲 +我想 点击游戏卡片启动游戏 +这样 我可以开始游玩 +``` + +**验收标准:** +- 点击卡片 3 秒内启动游戏 +- 游戏加载时显示进度提示 +- 游戏结束自动返回菜单 +- 支持按 ESC 返回菜单 + +#### 故事 3: 无法退出 +``` +作为 家人 +我想 用户无法通过快捷键或菜单退出游戏 +这样 游戏不会被误关闭或系统被破坏 +``` + +**验收标准:** +- Alt+F4 无效 +- Alt+Tab 无效 +- Windows 键无效 +- 右键菜单禁用 +- 任务栏隐藏 +- TTY 无法切换 (Ctrl+Alt+Fx) + +#### 故事 4: AI 对手 +``` +作为 玩家 +我想 和智能电脑对手对战 +这样 我可以随时游戏,不需要其他玩家 +``` + +**验收标准:** +- 所有游戏都有 2-4 个 AI 对手 +- AI 难度可调 (简单/中等/困难) +- AI 出牌合法且有策略性 +- AI 响应时间 1-2 秒 + +#### 故事 5: 保存进度 +``` +作为 玩家 +我想 每局游戏的成绩和统计被自动保存 +这样 我可以看到我的进度和胜率 +``` + +**验收标准:** +- 游戏结束后自动保存成绩 +- 显示历史成绩和统计数据 +- 统计包括: 总局数、胜率、平均用时 +- 数据持久存储在本地数据库 + +### 2.2 功能清单 + +#### 2.2.1 菜单系统 (Priority: P0 - 必须) + +| 功能 | 说明 | 优先级 | +|------|----------------------------------------|--------| +| **游戏列表展示** | 网格布局显示 4 个游戏卡片 | P0 | +| **游戏卡片** | 包含海报、名称、简描 | P0 | +| **启动游戏** | 点击卡片启动对应游戏 | P0 | +| **时间显示** | 菜单顶部显示当前时间 | P1 | +| **返回菜单** | 游戏结束自动返回,支持 ESC 返回 | P0 | +| **响应式布局** | 适配 1080p 到 4K 分辨率, 以2K分辨率 150%缩放作为基准开发 | P0 | +| **高对比度** | WCAG AAA 标准配色 | P0 | +| **父母友好** | 大字体、大按钮 | P0 | + +#### 2.2.2 斗地主游戏 (Priority: P0 - 必须) + +| 功能 | 说明 | 优先级 | +|------|------|--------| +| **基础规则** | 单张、对、顺、炸、王炸判定 | P0 | +| **手牌显示** | 玩家手牌按大小排序显示 | P0 | +| **出牌交互** | 鼠标/触屏选牌并出牌 | P0 | +| **地主判定** | 系统自动判定地主 | P0 | +| **AI 对手** | 2 个 AI 农民对手 | P0 | +| **游戏流程** | 发牌→抢地主→轮流出牌→结束 | P0 | +| **声音效果** | 出牌音效、胜负音效 | P1 | +| **游戏统计** | 保存胜负和用时 | P1 | + +**牌型规则:** +- 单张: 任何一张牌 +- 对牌: 同点数的两张牌 +- 三张: 同点数的三张牌 +- 顺子: 5 张及以上连续的牌 (2 不能在顺子中) +- 炸弹: 同点数的四张牌 (可以压任何牌) +- 王炸: 红黑王 (最大) +- 其他: 简化版,不实现飞机等复杂牌型 + +#### 2.2.3 拖拉机游戏 (Priority: P1 - 高) + +| 功能 | 说明 | 优先级 | +|------|------|--------| +| **基础规则** | 四人跑牌,拖拉机机制 | P1 | +| **主牌概念** | 主花色、主点数 | P1 | +| **AI 对手** | 3 个 AI 对手 | P1 | +| **游戏流程** | 发牌→选主→轮流出牌→计分→结束 | P1 | + +#### 2.2.4 卡五星麻将 (Priority: P2 - 可选) + +| 功能 | 说明 | 优先级 | +|------|------|--------| +| **基础规则** | 五人麻将变种 | P2 | +| **AI 对手** | 4 个 AI 对手 | P2 | +| **胡牌类型** | 简化版,5-10 种常见胡牌 | P2 | + +#### 2.2.5 赛车游戏 (Priority: P1 - 高) + +| 功能 | 说明 | 优先级 | +|------|------|--------| +| **基础机制** | 加速、减速、转向、碰撞 | P1 | +| **AI 对手** | 1 个 AI 赛手 | P1 | +| **赛道** | 简单环形赛道,3 圈 | P1 | +| **计时** | 完成赛道的用时和排名 | P1 | + +#### 2.2.6 系统功能 (Priority: P0 - 必须) + +| 功能 | 说明 | 优先级 | +|------|------|--------| +| **自动启动** | 系统启动后自动进入菜单 | P0 | +| **快捷键禁用** | 完全禁用系统快捷键 | P0 | +| **进程监控** | 游戏异常退出时自动返回菜单 | P0 | +| **数据持久化** | 游戏数据本地保存 | P0 | +| **日志记录** | 系统和游戏日志记录 | P1 | +| **故障恢复** | 自动修复数据损坏和异常状态 | P1 | + +### 2.3 非功能需求 + +| 类别 | 需求 | 验收标准 | +|------|------|---------| +| **性能** | 启动时间 | < 5 秒进入菜单 | +| **性能** | 菜单响应 | < 100ms UI 反馈 | +| **性能** | 内存占用** | < 500MB (菜单+游戏) | +| **性能** | 帧率 | 60fps 稳定 | +| **可靠性** | 运行时长 | 无中断 48+ 小时 | +| **可靠性** | 故障恢复 | 自动重启恢复 | +| **安全性** | 系统锁定 | 三层防护机制 | +| **兼容性** | 分辨率 | 1080p, 1440p, 2560p, 4K | +| **兼容性** | 输入 | 鼠标、触屏、手柄 | +| **可维护性** | 代码** | 注释完整,易扩展 | +| **可维护性** | 文档** | API、部署、故障排查 | + +--- + +## 技术方案 + +### 3.1 技术栈选择 + +#### 3.1.1 开发平台 (Windows 11) + +``` +IDE/编辑器: VS Code / JetBrains IDE +Golang: 1.20+ (Golang for Windows) +Node.js: 18+ LTS (Windows版) +Godot Engine: 4.1+ (Windows版) +Git: Git Bash or GitHub Desktop +包管理器: npm (Node.js), go mod (Golang) +``` + +**开发优势:** +- 所有开发工具都有完整的 Windows 支持 +- Golang 和 Node.js 可在 Windows 上原生编译 +- Godot 有完整的 Windows 编辑器 +- 跨平台编译: 在 Windows 编译 Linux 二进制 + +#### 3.1.2 部署平台 (Ubuntu 22.04 LTS) + +``` +操作系统: Ubuntu 22.04 LTS (Server 版本推荐) +系统配置: Kiosk 模式 + systemd + Openbox +启动器: Golang 二进制 + zserge/webview +菜单UI: Vue 3 构建输出 +游戏: Godot 导出的 Linux 64-bit 二进制 +运行时: 无需额外依赖 (所有编译为静态二进制) +``` + +**部署优势:** +- Fedora Silverblue 不可变文件系统,或 Ubuntu Server 最小化 +- Kiosk 配置完全锁定系统 +- 无强制系统更新 +- 极低资源占用 + +### 3.2 架构设计 + +``` +┌─────────────────────────────────────────┐ +│ 用户交互层 (User Layer) │ +│ 鼠标/触屏/键盘 │ +└──────────────────┬──────────────────────┘ + ↓ +┌─────────────────────────────────────────┐ +│ 应用层 (Application Layer) │ +│ │ +│ ┌────────────────┐ ┌──────────────┐ │ +│ │ Golang Launcher│ │ Process Mgr │ │ +│ │ - Webview │ │ - Game spawn │ │ +│ │ - 全屏模式 │ │ - 监控 │ │ +│ └────────┬───────┘ └──────┬───────┘ │ +│ │ │ │ +│ ┌────────┴──────────────────┴────┐ │ +│ │ HTTP Server (localhost:8888) │ │ +│ └────────────────┬───────────────┘ │ +│ │ │ +│ ┌────────────────┴──────────────┐ │ +│ │ Vue 3 前端菜单 │ │ +│ │ - 游戏网格 │ │ +│ │ - 响应式布局 │ │ +│ └────────────────┬──────────────┘ │ +└─────────────────────────────────────────┘ + ↓ +┌─────────────────────────────────────────┐ +│ 游戏层 (Game Layer) │ +│ │ +│ ┌──────────┐ ┌──────────┐ ┌────────┐ │ +│ │Godot Game│ │Godot Game│ │Pixi.js │ │ +│ │ 斗地主 │ │ 拖拉机 │ │ 赛车 │ │ +│ └──────────┘ └──────────┘ └────────┘ │ +└─────────────────────────────────────────┘ + ↓ +┌─────────────────────────────────────────┐ +│ 系统层 (System Layer - Linux) │ +│ │ +│ ┌────────────────────────────────────┐ │ +│ │ systemd 系统管理 │ │ +│ │ - 自动登录 kiosk 用户 │ │ +│ │ - 启动 game-launcher 服务 │ │ +│ │ - 禁用睡眠、更新等 │ │ +│ └────────────────────────────────────┘ │ +│ │ +│ ┌────────────────────────────────────┐ │ +│ │ X11/Wayland Display Server │ │ +│ │ - Openbox 极简窗口管理 │ │ +│ │ - 禁用快捷键 (X11 事件) │ │ +│ │ - 禁用系统菜单 │ │ +│ └────────────────────────────────────┘ │ +│ │ +│ ┌────────────────────────────────────┐ │ +│ │ Linux Kernel │ │ +│ │ - SELinux / AppArmor │ │ +│ │ - kiosk 用户权限管理 │ │ +│ └────────────────────────────────────┘ │ +└─────────────────────────────────────────┘ +``` + +### 3.3 技术决策表 + +| 组件 | 选型 | 原因 | +|------|------|------| +| **启动器** | Golang | 内存 20MB, 启动 <100ms, 单二进制 | +| **菜单 UI** | Vue 3 + TypeScript | 响应式, 易修改, 开发快 | +| **卡牌游戏** | Godot 4 + GDScript | UI 系统优秀, 易学, 体积小 | +| **赛车游戏** | Pixi.js (Web 版) | 2D 性能最优, 易于参数调整 | +| **AI 算法** | 决策树 + 蒙特卡洛 | 快速开发, 难度可调, 可解释 | +| **数据库** | SQLite | 轻量级, 无需服务器, 易于备份 | +| **配置** | JSON | 易读易写, 无需解析库 | + +--- + +## 系统架构 + +### 4.1 模块划分 + +``` +project-root/ +│ +├─ launcher/ # Golang 启动器 (Module-1) +│ ├─ cmd/main.go # 入口点 +│ ├─ internal/ +│ │ ├─ launcher/launcher.go # 核心启动器逻辑 +│ │ ├─ server/http.go # HTTP 服务器 +│ │ ├─ process/manager.go # 进程管理 +│ │ ├─ config/config.go # 配置加载 +│ │ └─ logger/logger.go # 日志系统 +│ ├─ go.mod +│ ├─ go.sum +│ └─ Makefile # 编译脚本 +│ +├─ frontend/ # Vue 3 菜单 (Module-2) +│ ├─ src/ +│ │ ├─ App.vue # 根组件 +│ │ ├─ main.ts # 入口 +│ │ ├─ components/ +│ │ │ ├─ GameGrid.vue # 游戏网格 +│ │ │ ├─ GameCard.vue # 游戏卡片 +│ │ │ └─ LoadingSpinner.vue # 加载提示 +│ │ ├─ views/ +│ │ │ ├─ MainMenu.vue # 菜单视图 +│ │ │ ├─ StatisticsView.vue # 统计视图 (可选) +│ │ │ └─ SettingsView.vue # 设置视图 (可选) +│ │ ├─ services/ +│ │ │ └─ api.ts # API 通信 +│ │ ├─ types/ +│ │ │ └─ game.ts # 类型定义 +│ │ └─ styles/ +│ │ └─ main.css # 全局样式 +│ ├─ public/ +│ │ ├─ games.json # 游戏配置 +│ │ ├─ images/ # 游戏海报 +│ │ └─ fonts/ # 中文字体 +│ ├─ package.json +│ ├─ tsconfig.json +│ ├─ vite.config.ts +│ └─ Makefile +│ +├─ games/ # 游戏项目 +│ │ +│ ├─ doudizhu/ # 斗地主 (Module-3) +│ │ ├─ project.godot # Godot 项目配置 +│ │ ├─ scenes/ +│ │ │ ├─ Game.tscn # 主场景 +│ │ │ ├─ Card.tscn # 卡牌节点 +│ │ │ ├─ Player.tscn # 玩家区域 +│ │ │ └─ UI/ +│ │ │ ├─ HandUI.tscn +│ │ │ ├─ TableUI.tscn +│ │ │ └─ InfoPanel.tscn +│ │ ├─ scripts/ +│ │ │ ├─ Game.gd # 主逻辑 (~800 行) +│ │ │ ├─ CardLogic.gd # 规则判定 (~300 行) +│ │ │ ├─ AIPlayer.gd # AI 对手 (~500 行) +│ │ │ └─ UIController.gd # UI 控制 (~200 行) +│ │ ├─ assets/ +│ │ │ ├─ images/ +│ │ │ │ ├─ cards/ # 108 张牌纹理 +│ │ │ │ └─ ui/ +│ │ │ ├─ sounds/ +│ │ │ │ ├─ card_play.wav +│ │ │ │ ├─ win.wav +│ │ │ │ └─ lose.wav +│ │ │ └─ fonts/ +│ │ └─ export_presets.cfg # 导出配置 +│ │ +│ ├─ tractor/ # 拖拉机 (Module-4) +│ │ ├─ project.godot +│ │ ├─ scenes/ +│ │ ├─ scripts/ +│ │ │ ├─ Game.gd +│ │ │ ├─ CardLogic.gd # 拖拉机规则 +│ │ │ └─ AIPlayer.gd +│ │ └─ assets/ +│ │ +│ ├─ mahjong/ # 卡五星 (Module-5, 可选) +│ │ ├─ project.godot +│ │ ├─ scenes/ +│ │ ├─ scripts/ +│ │ │ ├─ Game.gd +│ │ │ ├─ MahjongLogic.gd # 麻将规则 +│ │ │ └─ AIPlayer.gd +│ │ └─ assets/ +│ │ +│ └─ racing/ # 赛车 (Module-6, Pixi.js) +│ ├─ src/ +│ │ ├─ main.ts +│ │ ├─ Game.ts # 游戏主类 +│ │ ├─ Car.ts # 车辆物理 +│ │ ├─ Track.ts # 赛道管理 +│ │ ├─ AI.ts # AI 赛手 +│ │ └─ UI.ts # UI 管理 +│ ├─ assets/ +│ │ ├─ images/ +│ │ ├─ sounds/ +│ │ └─ fonts/ +│ ├─ package.json +│ └─ tsconfig.json +│ +├─ shared/ # 共享资源 +│ ├─ fonts/ +│ │ ├─ SourceHanSansSC-Regular.otf # 中文字体 +│ │ └─ SourceHanSansSC-Bold.otf +│ ├─ images/ +│ │ ├─ doudizhu.jpg # 游戏海报 +│ │ ├─ tractor.jpg +│ │ ├─ mahjong.jpg +│ │ └─ racing.jpg +│ └─ sounds/ +│ ├─ ui_click.wav +│ ├─ ui_hover.wav +│ └─ bgm.ogg +│ +├─ config/ # 配置文件 +│ ├─ kiosk/ +│ │ ├─ gdm-custom.conf # GDM 自动登录 +│ │ ├─ systemd-service.ini # systemd 服务 +│ │ ├─ openbox-rc.xml # Openbox 配置 +│ │ └─ xset-config.sh # X11 配置脚本 +│ └─ app/ +│ ├─ launcher.json # 启动器配置 +│ └─ games.json # 游戏清单 +│ +├─ scripts/ # 构建和部署脚本 +│ ├─ build-windows.bat # Windows 编译脚本 +│ ├─ build-linux.sh # Linux 编译脚本 +│ ├─ build-all.sh # 全量编译脚本 +│ ├─ cross-compile.sh # 交叉编译脚本 +│ ├─ deploy.sh # 部署脚本 +│ ├─ setup-kiosk.sh # Kiosk 配置脚本 +│ └─ verify.sh # 验证脚本 +│ +├─ docs/ # 文档 +│ ├─ PRD.md # 本文档 +│ ├─ ARCHITECTURE.md # 架构详解 +│ ├─ DEVELOPMENT.md # 开发指南 +│ ├─ API.md # API 文档 +│ ├─ DEPLOYMENT.md # 部署指南 +│ ├─ TESTING.md # 测试指南 +│ └─ TROUBLESHOOTING.md # 故障排查 +│ +├─ tests/ # 测试用例 +│ ├─ launcher/ +│ ├─ frontend/ +│ ├─ games/ +│ └─ integration/ +│ +├─ README.md # 项目概述 +├─ Makefile # 顶层编译脚本 +├─ docker-compose.yml # 可选: Docker 支持 +└─ .github/ + └─ workflows/ # CI/CD 配置 + +``` + +### 4.2 依赖关系 + +``` +启动器 (Golang) + │ + ├─ 依赖: zserge/webview (嵌入式浏览器) + │ stdlib (net/http, os/exec, etc.) + │ + └─→ 启动 HTTP 服务器 (localhost:8888) + │ + ├─ 提供静态文件: 菜单 UI (Vue) + │ + ├─ 提供 API 端点: /api/launch + │ │ + │ └─→ 调用 os/exec 启动游戏进程 + │ + └─ 提供 Webview + │ + └─→ 显示菜单 UI + │ + └─→ 用户交互 + │ + └─→ 调用 API 启动游戏 + +游戏进程 (Godot / Pixi.js) + │ + ├─ 通过 IPC/stdio 接收启动参数 + │ + └─ 独立运行,不需与启动器通信 + (游戏结束时自己主动退出) + +菜单 UI (Vue 3) + │ + ├─ 依赖: Vue 3, TypeScript, Vite + │ + └─ 运行于 Webview 中 + │ + ├─ 加载 games.json + │ + └─ 通过 fetch API 调用启动器 HTTP 接口 +``` + +--- + +## 开发规范 + +### 5.1 代码规范 + +#### 5.1.1 Golang 代码规范 + +```go +// 文件头注释 +// Package main 描述此包的用途 +package main + +import ( + "fmt" + "os" + // 标准库分组 + + "github.com/zserge/webview" + // 第三方库分组 +) + +const ( + // 常量大写 + 下划线 + DEFAULT_WEB_PORT = 8888 + LAUNCHER_VERSION = "1.0.0" +) + +type GameLauncher struct { + // 字段注释 + currentGame *exec.Cmd // 当前运行的游戏进程 + webPort int // HTTP 服务器端口 + config Config // 配置对象 +} + +// NewGameLauncher 创建启动器实例 +// 返回: *GameLauncher - 启动器指针 +func NewGameLauncher() *GameLauncher { + return &GameLauncher{ + webPort: DEFAULT_WEB_PORT, + } +} + +// Start 启动游戏启动器 +// 返回: error - 错误信息 +func (gl *GameLauncher) Start() error { + // 函数实现 + return nil +} +``` + +**规则:** +- 变量名用驼峰命名 (camelCase) +- 常量用大写 (CONSTANT_NAME) +- 每个公共函数必须有注释 +- 每个包必须有注释说明其用途 +- 错误处理不能忽略: `if err != nil { return err }` +- 使用 `fmt.Sprintf` 构建字符串,不要用 `+` + +#### 5.1.2 Vue/TypeScript 代码规范 + +```typescript +// 文件头注释 +/** + * GameLauncher.vue - 游戏启动器主组件 + * + * 功能: + * - 显示游戏菜单网格 + * - 处理游戏启动逻辑 + * - 显示加载状态 + */ + + + + + + +``` + +**规则:** +- 使用 `const` 优于 `let`,尽量避免 `var` +- 使用 TypeScript,不要用 JavaScript +- 组件名使用 PascalCase (GameCard.vue) +- 变量名使用 camelCase +- 使用 BEM 命名法管理 CSS 类名 +- 必须包含 ARIA 无障碍属性 +- 类型定义在每个文件头部 + +#### 5.1.3 GDScript 代码规范 + +```gdscript +# 文件头注释 +## CardLogic.gd - 卡牌逻辑和规则判定 +## +## 实现斗地主的卡牌判定算法 +## 包括牌型检查、胜负判定等 + +class_name CardLogic + +# 常量定义 +const CARD_RANKS = ["9", "10", "J", "Q", "K", "A", "2"] +const CARD_SUITS = ["♠", "♥", "♦", "♣", "王"] + +# 静态函数 +static func is_valid_play(cards: Array) -> bool: + """检查出牌是否合法""" + if cards.is_empty(): + return false + + # 单张 + if cards.size() == 1: + return true + + # 对牌 + if cards.size() == 2: + return cards[0].rank == cards[1].rank + + return false + +# 实例函数 +func get_best_play(hand: Array, table_cards: Array) -> Array: + """根据手牌和桌面牌,给出最佳出牌""" + # 实现逻辑 + return [] +``` + +**规则:** +- 类名使用 PascalCase (CardLogic) +- 函数名使用 snake_case (is_valid_play) +- 常量使用 SCREAMING_SNAKE_CASE +- 每个公共函数使用 `##` 文档注释 +- 避免全局变量,使用类成员变量 + +### 5.2 分支管理 + +``` +main (生产分支) + │ + ├─ develop (开发分支) + │ │ + │ ├─ feature/launcher (启动器功能) + │ ├─ feature/menu-ui (菜单 UI) + │ ├─ feature/doudizhu (斗地主) + │ ├─ feature/ai-algorithm (AI 算法) + │ └─ bugfix/xxx (bug 修复) + │ + └─ release/v1.0 (发版分支) +``` + +**规则:** +- 功能开发: `feature/功能名` +- bug 修复: `bugfix/bug名` +- 发版准备: `release/版本号` +- 每个 PR 必须有描述和关联 issue +- 至少一人 code review 后才能合并 + +### 5.3 提交规范 + +```bash +# 格式: (): +# +#