{"id":"f9251bcf-2444-48f1-acae-ce4820d0c6ba","entityType":"agent","slug":"clawhub-ebandao777-oss-dev-expert","name":"dev-expert","canonicalUrl":"https://www.xpersona.co/agent/clawhub-ebandao777-oss-dev-expert","canonicalPath":"/agent/clawhub-ebandao777-oss-dev-expert","generatedAt":"2026-10-10T06:43:31.431Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T23:54:15.269Z","emptyReason":null},"description":"编程专家综合技能套件，含17个子技能：软件项目总控、网站项目总控、API设计、Bug诊断、代码生成、代码审查、重构建议、测试用例生成、技术选型、文档生成、任务拆解与执行、Spec驱动开发、Karpathy编码规范、项目记忆管理、CMS二次开发、前端设计、MySQL数据库。按用户输入关键词路由到对应子技能模板执行。 关键词路由：软件项目总控(软件项目/API服务/后端服务/后台模块/CLI工具/数据脚本/自动化任务/插件项目/完整功能/项目交付/部署/发布/上线/回滚/运维/监控/告警/巡检)；网站项目总控(做网站/建站/企业官网/营销页/CMS网站/网站上线/网站交付)；API设计(RESTful/GraphQL/接口规范/AJAX防卡死/Init-Step-Poll/长任务接口/轮询接口)；Bug诊断(debug/异常堆栈/报错)；代码生成(写代码/实现功能)；代码审查(code review/安全漏洞/代码缺陷)；重构建议(重构/坏味道/代码异味/可维护性)；测试用例生成(单元测试/集成测试/安全测试/性能测试/长任务测试)；技术选型(技术栈/框架选型)；文档生成(API文档/README/技术文档/部署说明/回滚说明/运维文档)；任务拆解与执行(任务分解/Wave执行)；Spec驱动开发(spec/需求对齐/需求规格)；Karpathy编码规范(Karpathy/编码哲学/简洁优先)；项目记忆管理(项目记忆/跨会话/上下文沉淀)；CMS二次开发(CMS/帝国CMS/WordPress/ThinkPHP/PHP8兼容/二次开发/插件开发/模板开发/批量任务/导入导出/生成静态页)；前端设计(UI设计/UX/交互设计/响应式/设计系统/可访问性/页面视觉/浏览器验证/品牌设计/Banner/图标/社媒图/进度条/轮询状态)；MySQL数据库(MySQL/数据库设计/SQL/索引/事务/慢查询/EXPLAIN/DDL/迁移/表结构/SQL优化)。","descriptionLabel":"Source description","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 1.9K downloads reported by the source. Last updated 10/9/2026.","installCommand":"clawhub skill install s17en637qww2q9z3kz1ep6w79988dec4:dev-expert","sourceUrl":"https://clawhub.ai/ebandao777-oss/dev-expert","homepage":"https://clawhub.ai/ebandao777-oss/skills/dev-expert","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/ebandao777-oss/dev-expert","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/ebandao777-oss/skills/dev-expert","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":65,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"dev-expert technical dossier on Xpersona with agent coverage, OPENCLEW support, and live trust metadata."},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-09T23:54:15.269Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T23:54:15.269Z","emptyReason":null},"stars":null,"forks":null,"downloads":1865,"packageName":null,"latestVersion":"0.1.0","tractionLabel":"1.9K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T23:54:15.269Z","emptyReason":null},"lastUpdatedAt":"2026-10-09T23:54:15.269Z","lastCrawledAt":"2026-10-09T23:54:15.269Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-10T23:54:15.269Z","lastVerifiedAt":null,"highlights":[{"version":"0.1.0","createdAt":"2026-08-15T17:29:13.369Z","changelog":"- 首次发布“dev-expert”编程专家综合技能套件，集成17个编程相关子技能 - 引入关键词路由自动匹配用户需求与子技能，覆盖软件/网站项目总控、API设计、Bug诊断等全流程 - 明确执行流程：意图识别、子技能模板加载、严格按模板分步执行、输出结构化结果 - 引入Karpathy编码规范、Wave执行模式与Spec驱动开发等方法论 - 支持CMS二次开发、前端设计、MySQL数据库等专项能力，强化实际落地与兼容性 - 详细列出子技能优先级矩阵，提升多场景请求的准确分流","fileCount":24,"zipByteSize":87871}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s17en637qww2q9z3kz1ep6w79988dec4:dev-expert","setupComplexity":"low","setupSteps":["Install using `clawhub skill install s17en637qww2q9z3kz1ep6w79988dec4:dev-expert` in an isolated environment before connecting it to live workloads.","No published capability contract is available yet, so validate auth and request/response behavior manually.","Review the upstream CLAWHUB listing at https://clawhub.ai/ebandao777-oss/dev-expert before using production credentials."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-ebandao777-oss-dev-expert/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-ebandao777-oss-dev-expert/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-ebandao777-oss-dev-expert/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-ebandao777-oss-dev-expert/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-ebandao777-oss-dev-expert/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-ebandao777-oss-dev-expert/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-10T06:43:31.429Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-ebandao777-oss-dev-expert/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-ebandao777-oss-dev-expert/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-ebandao777-oss-dev-expert/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-ebandao777-oss-dev-expert/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T23:54:15.269Z","emptyReason":null},"readme":"Skill: dev-expert\n\nOwner: ebandao777-oss\n\nSummary: 编程专家综合技能套件，含17个子技能：软件项目总控、网站项目总控、API设计、Bug诊断、代码生成、代码审查、重构建议、测试用例生成、技术选型、文档生成、任务拆解与执行、Spec驱动开发、Karpathy编码规范、项目记忆管理、CMS二次开发、前端设计、MySQL数据库。按用户输入关键词路由到对应子技能模板执行。 关键词路由：软件项目总控(软件项目/API服务/后端服务/后台模块/CLI工具/数据脚本/自动化任务/插件项目/完整功能/项目交付/部署/发布/上线/回滚/运维/监控/告警/巡检)；网站项目总控(做网站/建站/企业官网/营销页/CMS网站/网站上线/网站交付)；API设计(RESTful/GraphQL/接口规范/AJAX防卡死/Init-Step-Poll/长任务接口/轮询接口)；Bug诊断(debug/异常堆栈/报错)；代码生成(写代码/实现功能)；代码审查(code review/安全漏洞/代码缺陷)；重构建议(重构/坏味道/代码异味/可维护性)；测试用例生成(单元测试/集成测试/安全测试/性能测试/长任务测试)；技术选型(技术栈/框架选型)；文档生成(API文档/README/技术文档/部署说明/回滚说明/运维文档)；任务拆解与执行(任务分解/Wave执行)；Spec驱动开发(spec/需求对齐/需求规格)；Karpathy编码规范(Karpathy/编码哲学/简洁优先)；项目记忆管理(项目记忆/跨会话/上下文沉淀)；CMS二次开发(CMS/帝国CMS/WordPress/ThinkPHP/PHP8兼容/二次开发/插件开发/模板开发/批量任务/导入导出/生成静态页)；前端设计(UI设计/UX/交互设计/响应式/设计系统/可访问性/页面视觉/浏览器验证/品牌设计/Banner/图标/社媒图/进度条/轮询状态)；MySQL数据库(MySQL/数据库设计/SQL/索引/事务/慢查询/EXPLAIN/DDL/迁移/表结构/SQL优化)。\n\nTags: latest:0.1.0\n\nVersion history:\n\nv0.1.0 | 2026-08-15T17:29:13.369Z | auto\n\n- 首次发布“dev-expert”编程专家综合技能套件，集成17个编程相关子技能\n- 引入关键词路由自动匹配用户需求与子技能，覆盖软件/网站项目总控、API设计、Bug诊断等全流程\n- 明确执行流程：意图识别、子技能模板加载、严格按模板分步执行、输出结构化结果\n- 引入Karpathy编码规范、Wave执行模式与Spec驱动开发等方法论\n- 支持CMS二次开发、前端设计、MySQL数据库等专项能力，强化实际落地与兼容性\n- 详细列出子技能优先级矩阵，提升多场景请求的准确分流\n\nArchive index:\n\nArchive v0.1.0: 24 files, 87871 bytes\n\nFiles: .gitattributes (66b), .gitignore (176b), README.md (10826b), references (0b), references/api-design.md (6516b), references/bug-diagnosis.md (8679b), references/cms-development.md (14809b), references/code-generation.md (10031b), references/code-review.md (11772b), references/doc-generation.md (4893b), references/frontend-design.md (17109b), references/karpathy-coding-guidelines.md (10499b), references/mysql-database.md (12757b), references/project-memory-management.md (6718b), references/refactoring.md (6948b), references/software-project.md (8507b), references/spec-driven-development.md (6651b), references/task-decomposition-and-execution.md (8138b), references/tech-selection.md (6370b), references/test-generation.md (7937b), references/website-project.md (11062b), skill-card.md (3367b), SKILL.md (25057b), _meta.json (129b)\n\nFile v0.1.0:SKILL.md\n\n---\nname: dev-expert\ndescription: |\n 编程专家综合技能套件，含17个子技能：软件项目总控、网站项目总控、API设计、Bug诊断、代码生成、代码审查、重构建议、测试用例生成、技术选型、文档生成、任务拆解与执行、Spec驱动开发、Karpathy编码规范、项目记忆管理、CMS二次开发、前端设计、MySQL数据库。按用户输入关键词路由到对应子技能模板执行。\n 关键词路由：软件项目总控(软件项目/API服务/后端服务/后台模块/CLI工具/数据脚本/自动化任务/插件项目/完整功能/项目交付/部署/发布/上线/回滚/运维/监控/告警/巡检)；网站项目总控(做网站/建站/企业官网/营销页/CMS网站/网站上线/网站交付)；API设计(RESTful/GraphQL/接口规范/AJAX防卡死/Init-Step-Poll/长任务接口/轮询接口)；Bug诊断(debug/异常堆栈/报错)；代码生成(写代码/实现功能)；代码审查(code review/安全漏洞/代码缺陷)；重构建议(重构/坏味道/代码异味/可维护性)；测试用例生成(单元测试/集成测试/安全测试/性能测试/长任务测试)；技术选型(技术栈/框架选型)；文档生成(API文档/README/技术文档/部署说明/回滚说明/运维文档)；任务拆解与执行(任务分解/Wave执行)；Spec驱动开发(spec/需求对齐/需求规格)；Karpathy编码规范(Karpathy/编码哲学/简洁优先)；项目记忆管理(项目记忆/跨会话/上下文沉淀)；CMS二次开发(CMS/帝国CMS/WordPress/ThinkPHP/PHP8兼容/二次开发/插件开发/模板开发/批量任务/导入导出/生成静态页)；前端设计(UI设计/UX/交互设计/响应式/设计系统/可访问性/页面视觉/浏览器验证/品牌设计/Banner/图标/社媒图/进度条/轮询状态)；MySQL数据库(MySQL/数据库设计/SQL/索引/事务/慢查询/EXPLAIN/DDL/迁移/表结构/SQL优化)。\nversion: \"1.5.1\"\nauthor: \"智慧半岛\"\n---\n\n# dev-expert -- 编程专家综合技能\n\n本技能是一个综合技能套件，包含多个子技能。接到用户请求后，按以下流程执行。\n\n## 执行流程\n\n### Step 1: 意图识别与路由匹配\n\n分析用户输入，与下方路由表逐一比对。匹配规则：\n\n- 用户输入中包含路由表中「子技能」列的关键词 → 匹配该子技能\n- 用户输入中包含路由表中「功能说明」列中提到的场景 → 匹配该子技能\n- 多个子技能同时匹配时，先按「子技能优先级矩阵」组合路由；无法组合时再选择匹配度最高的\n- 无法唯一确定时，向用户确认意图\n\n### Step 2: 加载子技能模板\n\n匹配到子技能后，根据子技能索引表找到对应的文件路径，**必须**使用 `Read` 工具读取 `references/` 目录下的完整执行模板。\n\n### Step 3: 按模板执行\n\n严格按照加载的模板逐步执行。模板中定义了：\n\n- 输入要求（用户需要提供什么）\n- 执行步骤（每一步做什么、如何判断）\n- 输出格式（最终产出的结构和规范）\n- 质量标准（产出必须满足的底线）\n\n### Step 4: 输出结果\n\n按模板规定的格式输出结果。如果模板要求生成文件，写入后声明产出物。\n\n## 约束规则\n\n1. **必须先读模板再执行**：匹配到子技能后，严禁凭记忆或猜测执行，必须先读取对应的 references 文件\n2. **严格遵循模板**：不得跳过步骤、不得省略检查项、不得自行简化流程\n3. **输入不足时主动索取**：模板中标注「必填」的输入项缺失时，向用户索取\n4. **质量底线不妥协**：模板中的质量标准必须逐条满足\n\n## 本包特色\n\n- **软件项目总控**：面向 API 服务、后台模块、插件、CLI 工具、数据脚本和自动化任务等非网站项目，先定义项目边界、行为契约、架构、数据/API/集成、发布回滚、监控告警、巡检运维和交付沉淀，再进入 Wave 执行\n- **网站项目总控**：面向做网站/建站/CMS网站/企业官网/营销页等完整项目，先定义项目启动、站点规划、内容SEO、前端设计、CMS/API/数据、任务Wave、测试安全、性能部署、验收交接和运维沉淀，再调用任务拆解与执行落地\n- **CMS二次开发**：PHP+MySQL CMS 二次开发子技能提供 CMS 自动探测、PHP 版本选型矩阵、数据库操作规范、PHP 8.x 兼容性检查、安全红线、插件开发标准，与代码生成/Bug诊断/代码审查/技术选型深度联动\n- **前端设计**：融合 UI/UX Pro Max 规则，覆盖设计思维、信息架构、视觉 token、字体配对、品牌规范、Banner、图标、社媒图、组件状态、响应式、可访问性、CMS模板页面和浏览器验证\n- **MySQL数据库**：独立覆盖表结构设计、SQL安全、索引、事务、慢查询、迁移回滚和 PHP/CMS 数据访问约束\n- **AJAX 渐进式防卡死**：长任务强制采用 Init → Step → Poll 架构，覆盖 CMS 批处理、导入导出、静态生成、采集同步、前端进度轮询和 API 契约\n\n- **Karpathy编码哲学**：所有代码产出遵循'先思考、简洁优先、避免浪费、手工胜于模板'原则，代码生成前必须先完成逻辑推演\n- **Wave执行模式**：任务拆解与执行子技能按依赖分Wave串行执行，每Wave完成后验证再进入下一Wave，上下文隔离避免污染\n- **Spec驱动开发**：Spec驱动开发子技能在编码前强制对齐需求规格，用artifact flow分离提案/实施/验证三阶段\n\n## 路由表\n\n| 子技能 | 功能说明 |\n| ---------------- | -------------------------------------------------------------------------------------------------------------- |\n| 软件项目总控 | 通用软件项目从需求到交付的总控：边界、行为契约、架构、数据/API/集成、测试、安全、发布、回滚和沉淀。 |\n| 网站项目总控 | 从需求到上线的建站项目总控：站点规划、内容SEO、前端设计、CMS/API/数据、测试安全、性能部署、验收运维。 |\n| API设计 | 根据业务需求设计RESTful或GraphQL API接口... |\n| Bug诊断 | 分析错误日志、异常堆栈和代码，定位Bug根因并给出修复方案。 |\n| Karpathy编码规范 | Karpathy编码哲学：先思考、简洁优先、避免浪费、手工胜于模板。 |\n| Spec驱动开发 | 编码前对齐需求规格，用OpenSpec的artifact flow分离提案。 |\n| 代码审查 | 审查代码质量，发现潜在Bug、安全漏洞、性能问题和代码异味... |\n| 代码生成 | 根据功能需求生成高质量代码实现，支持多种编程语言和框架，包含错误处理和边界条件。 |\n| 任务拆解与执行 | 将复杂需求拆分为原子任务，按依赖分Wave执行，上下文隔离。 |\n| 技术选型 | 根据项目需求、团队能力和约束条件，推荐合适的技术栈、框架和工具... |\n| 文档生成 | 根据代码生成技术文档，包括函数文档、README、API文档和架构说明... |\n| 测试用例生成 | 根据代码逻辑生成单元测试、集成测试和边界条件测试，覆盖正常路径和异常路径。 |\n| 重构建议 | 分析代码结构，识别坏味道，提供具体的重构方案和步骤，提升代码可维护性。 |\n| 项目记忆管理 | 捕获会话上下文、技术决策和项目规范，实现跨会话项目记忆沉淀与恢复。 |\n| CMS二次开发 | PHP+MySQL CMS 二次开发全链路指引：CMS探测、PHP版本选型、数据库规范、PHP8兼容、安全红线、插件开发。 |\n| 前端设计 | UI/UX 与前端实现设计：设计思维、信息架构、视觉规范、品牌、Banner、图标、社媒图、响应式、可访问性、浏览器验证。 |\n| MySQL数据库 | MySQL 数据建模、SQL安全、索引设计、事务边界、慢查询诊断、迁移回滚和数据安全。 |\n\n## 子技能索引\n\n| 子技能 | 英文标识 | 文件 |\n| ---------------- | ---------------------------------- | -------------------------------------------------------------------------------------------------- |\n| 软件项目总控 | `software-project` | [references/software-project.md](./references/software-project.md) |\n| 网站项目总控 | `website-project` | [references/website-project.md](./references/website-project.md) |\n| API设计 | `api-design` | [references/api-design.md](./references/api-design.md) |\n| Bug诊断 | `bug-diagnosis` | [references/bug-diagnosis.md](./references/bug-diagnosis.md) |\n| Karpathy编码规范 | `karpathy-coding-guidelines` | [references/karpathy-coding-guidelines.md](./references/karpathy-coding-guidelines.md) |\n| Spec驱动开发 | `spec-driven-development` | [references/spec-driven-development.md](./references/spec-driven-development.md) |\n| 代码审查 | `code-review` | [references/code-review.md](./references/code-review.md) |\n| 代码生成 | `code-generation` | [references/code-generation.md](./references/code-generation.md) |\n| 任务拆解与执行 | `task-decomposition-and-execution` | [references/task-decomposition-and-execution.md](./references/task-decomposition-and-execution.md) |\n| 技术选型 | `tech-selection` | [references/tech-selection.md](./references/tech-selection.md) |\n| 文档生成 | `doc-generation` | [references/doc-generation.md](./references/doc-generation.md) |\n| 测试用例生成 | `test-generation` | [references/test-generation.md](./references/test-generation.md) |\n| 重构建议 | `refactoring` | [references/refactoring.md](./references/refactoring.md) |\n| 项目记忆管理 | `project-memory-management` | [references/project-memory-management.md](./references/project-memory-management.md) |\n| CMS二次开发 | `cms-development` | [references/cms-development.md](./references/cms-development.md) |\n| 前端设计 | `frontend-design` | [references/frontend-design.md](./references/frontend-design.md) |\n| MySQL数据库 | `mysql-database` | [references/mysql-database.md](./references/mysql-database.md) |\n\n## 子技能优先级矩阵\n\n当用户输入同时匹配多个子技能时，按以下优先级路由：\n\n| 场景 | 优先子技能 | 理由 |\n| ----------------------------------------------------- | -------------------------------- | ----------------------------------------------------------------------- |\n| \"做网站/建站/企业官网/营销页\" | 网站项目总控 | 网站项目需要先覆盖项目启动、站点规划、SEO、部署、验收和运维，再拆解执行 |\n| \"API服务/后端服务/CLI工具/数据脚本/插件项目/完整功能\" | 软件项目总控 | 非网站类完整项目需要先覆盖边界、架构、验证、发布和交付，再拆解执行 |\n| \"帮我看看这段代码有什么问题\" | 代码审查 | 通用审查优先于专项重构 |\n| \"这段代码有坏味道/代码异味\" | 重构建议 | 专项关键词触发专项技能 |\n| \"帮我修复这个Bug\" | Bug诊断 | 明确修复意图优先于审查 |\n| \"帮我写段代码\" + 提到测试 | 代码生成 | 先生成主代码，再生成测试（代码生成→测试用例生成 协同） |\n| \"设计API\" + 提到技术选型 | 技术选型 | 选型先于设计（技术选型→API设计 协同） |\n| \"重构\" + 提到测试 | 重构建议 | 先重构，再补测试（重构建议→测试用例生成 协同） |\n| \"写文档\" + 提到API | 文档生成 | 通用文档优先，API专项由 API设计 协同 |\n| 任何子技能 + \"记录决策\" | 当前子技能 + 项目记忆管理 | 主任务优先，记忆作为附属步骤 |\n| \"CMS二次开发\" + \"写代码\" | CMS二次开发 + 代码生成 | CMS规范优先，代码生成遵循CMS数据访问层和安全红线 |\n| \"帝国CMS/WordPress\" + \"报错\" | Bug诊断 | CMS关键词触发Bug诊断时自动加载CMS常见Bug模式 |\n| \"PHP\" + \"代码审查\" | 代码审查 + CMS二次开发(自动) | 审查PHP代码时自动追加CMS安全审查清单 |\n| \"MySQL/数据库/SQL/索引/慢查询/EXPLAIN\" | MySQL数据库 | 数据结构、SQL安全和性能问题优先走数据库专项模板 |\n| \"PHP/CMS\" + \"数据库/SQL\" | CMS二次开发 + MySQL数据库 | 先确认CMS访问层和表前缀，再进行SQL/索引/迁移设计 |\n| \"部署/发布/上线/回滚/运维/监控/告警/巡检\" | 软件项目总控 + 文档生成 | 发布运维类请求必须输出发布步骤、回滚方案、观测指标、告警和巡检清单 |\n| \"前端/页面/UI\" + \"设计\" | 前端设计 | 视觉、交互、响应式和可访问性优先于直接写代码 |\n| \"品牌/Banner/图标/社媒图\" | 前端设计 | 视觉资产类请求由前端设计输出规格、风格、尺寸和验收标准 |\n| \"前端设计\" + \"写代码\" | 前端设计 + 代码生成 | 先定义页面结构/组件状态/响应式，再生成实现代码 |\n| \"CMS模板\" + \"页面设计\" | 前端设计 + CMS二次开发 | 同时约束视觉实现、模板变量、输出转义和缓存策略 |\n| \"AJAX防卡死/Init-Step-Poll/长任务/轮询\" | API设计 + 前端设计 + CMS二次开发 | 长任务必须先定义 Init/Step/Poll 接口契约，再实现前端轮询和 CMS 分批处理 |\n\n**互斥规则**：\n\n- 代码审查 vs 重构建议：用户说\"问题/缺陷/漏洞\" → 代码审查；用户说\"坏味道/异味/重构\" → 重构建议\n- Bug诊断 vs 代码审查：用户说\"报错/Bug/崩溃\" → Bug诊断；用户说\"审查/检查/review\" → 代码审查\n- 代码生成 vs 重构建议：用户说\"实现/写/生成\" → 代码生成；用户说\"重构/优化/改\" → 重构建议\n\n**协同顺序规则**：\n\n- 网站项目：网站项目总控 → Spec驱动开发 → 任务拆解与执行 → 前端设计/CMS二次开发/API设计 → 代码生成 → 代码审查 → 测试用例生成 → 文档生成 → 项目记忆管理\n- 通用软件项目：软件项目总控 → Spec驱动开发 → 技术选型/API设计/MySQL数据库/CMS二次开发 → 任务拆解与执行 → 代码生成 → 代码审查 → 测试用例生成 → 文档生成/部署运维说明 → 项目记忆管理\n- 需求→实现：Spec驱动开发 → 任务拆解与执行 → 代码生成 → 代码审查 → 测试用例生成 → 文档生成\n- 页面→实现：前端设计 → 代码生成 → 代码审查 → 测试用例生成 → 文档生成\n- CMS页面→实现：CMS二次开发 → 前端设计 → 代码生成 → 代码审查 → 浏览器验证\n- 治理→沉淀：Bug诊断/重构建议 → 代码审查 → Karpathy编码规范 → 项目记忆管理\n\n## 跨技能协同指引\n\n编程专家为独立技能套件，暂无可直接联动的其他职业技能。如需在编程任务中集成外部数据或服务，可使用主Agent的web_search/web_fetch工具获取。\n\n## 六步闭环工作流对齐\n\n> 本章节使本技能包对齐「六步闭环工作流\\_融合数字员工体系.md」标准，实现分析→方案→执行→验证→交付→复盘的全流程闭环。\n\n### 一、六步闭环映射\n\n本技能原有四步流程（意图识别→加载模板→按模板执行→输出结果）映射到六步闭环：\n\n| 闭环步骤 | 对应本技能环节 | 具体动作 |\n| ----------- | -------------------------- | ----------------------------------------------------------------------------------------- |\n| 1. 分析指令 | Step 1: 意图识别与路由匹配 | 提取用户需求中的目标、范围、技术约束；标注不确定信息；判断子技能匹配度 |\n| 2. 制定方案 | Step 2: 加载子技能模板 | 根据子技能索引读取模板；确认输入要求、执行步骤、输出格式；定义验收口径 |\n| 3. 执行任务 | Step 3: 按模板执行 | 严格按模板逐步执行；记录关键步骤和偏差；遵守Karpathy编码规范 |\n| 4. 验证结果 | Step 3 末尾 + 自查 | 代码编译/运行自检；对照模板质量标准逐条验证；未通过项返回修复 |\n| 5. 交付结果 | Step 4: 输出结果 | 按模板格式输出；附带验证结论和变更说明；标注已知限制 |\n| 6. 复盘沉淀 | （新增） | 将本轮编码/架构中的修正经验固化为开发规范 → 更新代码模板库与最佳实践 → 形成可复用检查清单 |\n\n### 二、数字员工角色配置\n\n本技能包对应的角色分工如下：\n\n| 职能类型 | 角色名称 | 职责 |\n| -------- | -------- | ---------------------------------------------------- |\n| 中枢型 | 主控 | 调度子技能选择、判定交付质量、控制轮次节奏 |\n| 分析型 | 架构师 | 需求拆解、意图识别、子技能路由、技术选型与架构设计 |\n| 产出型 | 程序员 | 实际编码实现、Bug修复、代码重构、测试用例编写 |\n| 验收型 | 测试员 | 代码审查、单元测试验证、功能测试、回归测试、安全审计 |\n\n**角色间接口协议**：\n\n- 主控 → 分析角色：传递用户原始需求，指明技术约束和性能要求\n- 分析角色 → 产出角色：传递匹配的子技能模板路径、技术方案、接口规范和验收标准\n- 产出角色 → 验收角色：传递代码产物、变更说明、自检结果和已知限制\n- 验收角色 → 主控：传递测试报告（阻塞级/严重/一般/建议）、放行结论\n\n### 三、轮次控制与收敛规则\n\n| 参数 | 默认值 | 说明 |\n| ---------------- | ----------------------------------------- | ---------------------------------------------------- |\n| 默认循环轮次 | 3 | 无终极功能时的标准结束轮次 |\n| 安全最大轮次 | 6 | 防无限迭代的硬上限 |\n| 每轮最大改动点数 | 3 | 分析角色每轮最多提出改动点，主目标未完成时禁止P2优化 |\n| 失败熔断 | 同一Bug 2轮未修复→标记已知限制不再循环 | 防止反复尝试无效修复 |\n| 低收益检测 | 连续2轮仅做注释/命名等P2微调→建议提前结束 | 避免过度优化 |\n\n**收敛判定逻辑**：\n\n1. 终极功能完成且测试通过 → 正常结束\n2. 无终极功能时，达到默认轮次且本轮测试通过 → 默认结束\n3. 达到安全最大轮次 → 强制结束，输出未完成清单\n4. 连续2轮仅做P2级微调且测试通过 → 建议提前结束\n\n### 四、验收标准\n\n每个子技能执行完毕后，必须对照以下检查项：\n\n| 检查维度 | 检查项 | 判定标准 |\n| ---------- | ---------------------------------------------- | --------------------------- |\n| 功能完整性 | 是否实现模板/需求所有必选功能 | 全部必选功能可运行 |\n| 代码质量 | 是否通过代码审查（安全/性能/可维护性） | 无阻塞级代码问题 |\n| 构建通过 | 代码能否成功编译/运行 | 构建状态为成功 |\n| 测试覆盖 | 单元测试/集成测试是否覆盖正常与异常路径 | 核心路径有测试用例 |\n| 规范符合性 | 是否符合Karpathy编码规范和项目规范 | 无规范违规 |\n| 可追溯性 | 变更记录是否完整、已知限制是否明示 | 变更文件与影响范围可查 |\n| 逻辑一致性 | 代码实现逻辑是否与需求对齐、架构推演是否无跳跃 | 需求→代码映射关系完整可追溯 |\n\n### 五、模板化交付\n\n关键产出的标准模板由各子技能的 `references/` 文件定义。本技能包级别的通用交付格式：\n\n```markdown\n## 任务交付说明\n\n### 1. 子技能与路由\n\n- **匹配子技能**：（名称）\n- **路由依据**：（用户输入关键词/场景匹配）\n\n### 2. 执行摘要\n\n- **输入信息**：（用户提供的核心输入/技术约束）\n- **执行过程**：（关键步骤简述）\n- **产出清单**：（交付物列表，含文件路径）\n\n### 3. 变更说明\n\n| 改动点 | 涉及文件 | 变更摘要 | 已知限制 |\n| ------ | -------- | -------- | -------- |\n\n### 4. 验证结论\n\n- **构建状态**：通过/失败\n- **测试结果**：\n | 检查项 | 状态 | 备注 |\n |--------|:----:|------|\n | （逐条列出） | 通过/未通过 | （说明） |\n\n### 5. 风险与建议\n\n- **已知限制**：\n- **技术债记录**：\n- **后续建议**：\n\n### 6. 复盘记录\n\n- **本次经验**：（可复用的Bug模式/架构决策/需注意的陷阱）\n```\n\n### 六、项目启动模板\n\n处理复杂编程任务时，启动前填写：\n\n```markdown\n## 项目启动信息\n\n- **项目名称**：\n- **初始需求**：（用户原始需求描述）\n- **技术栈**：\n- **是否存在终极功能**：是 / 否\n- **终极功能定义**：（如有，可验证的一句话描述）\n- **技术约束**：（性能要求/兼容性/安全约束等）\n- **默认循环轮次**：3\n- **安全最大轮次**：6\n- **每轮最大改动点数**：3\n- **角色配置**：主控 + 架构师 + 程序员 + 测试员\n```\n\nFile v0.1.0:README.md\n\n# 编程专家 - dev-expert\n\n面向软件工程师和开发团队的编程全生命周期助手。覆盖从软件项目总控、网站项目总控、需求分析、前端设计、MySQL数据库、代码生成、Bug诊断到重构、测试、文档、上线交付和运维监控的全链路，通过17个子技能提供专业化支持。特别强化PHP+MySQL CMS二次开发场景，提供CMS自动探测、PHP版本选型、数据库规范、安全红线、AJAX渐进式防卡死等专项指引。\n\n## 子技能列表\n\n| 子技能 | 功能 | 触发关键词 |\n|--------|------|-----------|\n| 软件项目总控 | 通用软件项目从需求到交付的总控：边界、行为契约、架构、数据/API/集成、测试、安全、发布、回滚、监控、告警、巡检和沉淀 | 软件项目, API服务, 后端服务, 后台模块, CLI工具, 数据脚本, 自动化任务, 插件项目, 完整功能, 项目交付, 部署, 发布, 回滚, 运维, 监控, 告警, 巡检 |\n| 网站项目总控 | 从需求到上线的建站项目总控：站点规划、内容SEO、前端设计、CMS/API/数据、测试安全、性能部署、验收运维 | 做网站, 建站, 企业官网, 营销页, CMS网站, 网站上线, 网站交付 |\n| API设计 | 根据业务需求设计RESTful或GraphQL API接口，长任务采用 Init-Step-Poll 契约 | API设计, RESTful, GraphQL, 接口规范, AJAX防卡死, Init-Step-Poll, 长任务接口, 轮询接口 |\n| Bug诊断 | 分析错误日志和异常堆栈，定位Bug根因并给出修复方案 | Bug诊断, debug, 报错, 异常堆栈 |\n| Karpathy编码规范 | 提供Karpathy核心编码哲学：思考优先、简洁至上 | Karpathy编码规范, Karpathy, 编码哲学 |\n| Spec驱动开发 | 编码前对齐需求规格，使用OpenSpec artifact flow | Spec驱动开发, spec, 需求对齐 |\n| 代码审查 | 审查代码质量，发现Bug、安全漏洞和代码缺陷 | 代码审查, code review, 代码缺陷 |\n| 代码生成 | 根据功能需求生成高质量代码，含错误处理和边界条件 | 代码生成, 生成代码, 实现功能 |\n| 任务拆解与执行 | 将复杂需求拆分为原子任务，按Wave分组执行 | 任务拆解与执行, 任务分解, Wave执行 |\n| 技术选型 | 根据项目需求推荐合适技术栈、框架和工具 | 技术选型, 技术栈, 框架选型 |\n| 文档生成 | 根据代码生成技术文档、README、API文档、部署说明和运维文档 | 文档生成, API文档, README, 部署说明, 回滚说明, 运维文档 |\n| 测试用例生成 | 生成单元测试、集成测试、安全测试、性能测试和长任务测试 | 测试用例生成, 单元测试, 测试用例, 安全测试, 性能测试, 长任务测试 |\n| 重构建议 | 分析代码结构，识别坏味道并提供重构方案 | 重构建议, 重构, 坏味道, 代码异味 |\n| 项目记忆管理 | 捕获上下文和决策，实现跨会话项目记忆沉淀 | 项目记忆管理, 项目记忆, 跨会话 |\n| CMS二次开发 | PHP+MySQL CMS 二次开发全链路：CMS探测/PHP版本/数据库规范/安全红线/插件开发/长任务防卡死 | CMS, 帝国CMS, WordPress, ThinkPHP, PHP8兼容, 二次开发, 插件开发, 批量任务, 导入导出, 生成静态页 |\n| 前端设计 | UI/UX 与前端实现设计：设计思维、信息架构、视觉规范、品牌、Banner、图标、社媒图、响应式、可访问性、浏览器验证、进度轮询 | 前端设计, UI设计, UX, 交互设计, 响应式, 设计系统, 品牌设计, Banner, 图标, 社媒图, 进度条, 轮询状态 |\n| MySQL数据库 | MySQL 数据建模、SQL安全、索引设计、事务边界、慢查询诊断、迁移回滚和数据安全 | MySQL, 数据库设计, SQL, 索引, 事务, 慢查询, EXPLAIN, DDL, 迁移, 表结构, SQL优化 |\n\n## 使用方法\n\n通过 Marvis 对话自然触发，说出需求即可自动匹配对应子技能。\n\n## 协同技能\n\n### 子技能内部协同\n17个子技能通过\"关联Skill\"章节相互引用，形成全生命周期闭环。常见协同路径：\n- 通用软件项目：软件项目总控 → Spec驱动开发 → 技术选型/API设计/MySQL数据库/CMS二次开发 → 任务拆解与执行 → 代码生成 → 代码审查 → 测试用例生成 → 文档生成/部署运维说明 → 项目记忆管理\n- 网站项目：网站项目总控 → Spec驱动开发 → 任务拆解与执行 → 前端设计/CMS二次开发/API设计/MySQL数据库 → 代码生成 → 代码审查 → 测试用例生成 → 文档生成 → 项目记忆管理\n- 需求阶段：Spec驱动开发 → 任务拆解与执行 → 前端设计/代码生成\n- 页面阶段：前端设计 → 代码生成 → 代码审查 → 测试用例生成 → 文档生成\n- 交付阶段：代码生成 → 代码审查 → 测试用例生成 → 文档生成/部署运维说明\n- 治理阶段：Bug诊断/重构建议 → 代码审查 → Karpathy编码规范 → 项目记忆管理\n- CMS二开：CMS二次开发 → (前端设计/代码生成/Bug诊断/代码审查/技术选型) → 项目记忆管理\n- MySQL专项：MySQL数据库 → 代码生成/代码审查/Bug诊断 → 测试用例生成 → 项目记忆管理\n- AJAX防卡死：Init → Step → Poll，API设计 → 前端设计 → CMS二次开发/代码生成 → 测试用例生成\n- 沉淀阶段：任何子技能 → 项目记忆管理（记录决策/规范/summary）\n\n### 跨技能包协同\n本技能包为独立套件，暂无可直接联动的其他职业技能包。如需在编程任务中集成外部数据或服务，可使用主Agent的web_search/web_fetch工具获取。\n\n## 版本\n\nv1.5.1 | 更新日期: 2026-07-02\n\n## 变更日志\n\n### v1.5.1 (2026-07-02)\n\n- 任务拆解模板新增安全触发面识别，Wave 任务必须写明安全验证项\n- SKILL.md 新增部署、发布、回滚、运维、监控、告警、巡检路由\n- 软件项目总控补强监控指标、告警阈值、巡检清单和运维交付材料\n- 测试用例生成补齐安全测试、性能测试和 Init-Step-Poll 长任务测试分类\n\n### v1.5.0 (2026-07-02)\n\n- 新增 软件项目总控 子技能（references/software-project.md）\n- 覆盖 API 服务、后台模块、插件、CLI 工具、数据脚本、自动化任务等非网站项目的完整交付链\n- 修正组合路由规则：多子技能命中时先按优先级矩阵组合路由，无法组合时才选最高匹配度\n- 补强任务拆解关联链和项目记忆流程格式\n- 更新子技能数量 16 → 17\n\n### v1.4.1 (2026-07-02)\n\n- 强化 MySQL 索引策略：查询路径、联合索引顺序、覆盖索引、分页、JOIN、ORDER BY/GROUP BY、冗余索引治理、写入成本和 EXPLAIN 验收\n- 更新 MySQL数据库输出格式，要求说明字段顺序理由、覆盖查询、写入成本和回滚 SQL\n- 更新代码审查清单，新增 MySQL 索引审查维度\n\n### v1.4.0 (2026-07-02)\n\n- 新增 MySQL数据库 子技能（references/mysql-database.md）\n- 覆盖表结构设计、SQL安全、索引设计、事务边界、慢查询诊断、迁移回滚、数据安全和 PHP/CMS 数据访问约束\n- SKILL.md/README.md 新增 MySQL 路由关键词、子技能索引、优先级矩阵和协同路径\n- 更新子技能数量 15 → 16\n\n### v1.3.3 (2026-07-02)\n\n- 补充 AJAX 渐进式防卡死架构：`Init → Step → Poll`\n- 在 CMS二次开发、API设计、前端设计、网站项目总控中加入长任务防卡死规则\n- 补充 `AJAX防卡死 / Init-Step-Poll / 长任务 / 轮询` 路由关键词\n\n### v1.3.2 (2026-07-02)\n\n- 统一 5 个子技能的执行流程步骤名与失败回退表步骤名\n- 修复 `spec-driven-development.md` 输出示例二级标题被误识别为真实章节的问题\n- 复测 15 个 references 索引、必需章节、代码块和回退表一致性\n\n### v1.3.1 (2026-07-02)\n\n- 将 `ui-ux-pro-max-zh.md` 的高价值规则吸收到前端设计子技能\n- 补充设计思维、色板、字体配对、品牌规范、Banner、图标、社媒图和设计资产规格\n- 更新前端设计路由关键词：品牌设计、Banner、图标、社媒图\n\n### v1.3.0 (2026-07-02)\n\n- 新增 网站项目总控 子技能（references/website-project.md）\n- 补齐完整网站项目生命周期：项目启动、站点规划、内容SEO、前端设计、CMS/API/数据、任务Wave、测试安全、性能部署、验收交接、运维沉淀\n- 建站类需求拆解前强制先调用网站项目总控\n\n### v1.2.0 (2026-07-02)\n\n- 补齐前端设计能力缺口，新增 前端设计 子技能（references/frontend-design.md）\n- 前端设计流程覆盖：需求与场景分析、信息架构、视觉设计系统、交互状态、响应式兼容、可访问性、前端实现方案、浏览器验证、项目记忆沉淀\n- SKILL.md 新增前端设计路由、子技能索引、优先级矩阵和协同路径\n- 更新子技能数量 13 → 14\n\n### v1.1.0 (2026-07-02)\n\n- 新增 CMS二次开发 子技能（references/cms-development.md）\n- 补充 CMS 探测、PHP 版本选型、数据库规范、PHP8兼容、安全红线、插件开发、代码风格、交付检查、记录沉淀\n- code-generation.md、bug-diagnosis.md、code-review.md、tech-selection.md 补充 CMS 专项指引\n- SKILL.md/README.md 新增 CMS 子技能路由、索引、优先级矩阵、协同路径\n- 更新子技能数量 12 → 13\n\n### v1.0.3 (2026-07-02)\n\n- 修复 bug-diagnosis、code-generation、code-review 失败回退表步骤名与执行流程错位\n- 修复 SKILL.md 工具名引用错误：`read_text` → `Read`\n- 补全 spec-driven-development、task-decomposition-and-execution 的「记录到项目记忆」步骤及回退行\n- 统一 SKILL.md 与 README.md 治理阶段协同路径描述\n\n### v1.0.2 (2026-07-02)\n\n- 修复 spec-driven-development.md 章节编号断裂与代码块嵌套解析异常\n- 修复 tech-selection.md 连接器章节位置错误\n- 为多个缺失子技能补全失败回退机制表\n- 补全 code-generation.md、code-review.md 的「记录到项目记忆」步骤\n- 新增子技能优先级矩阵和 `.gitignore`\n\n### v1.0.1 (2026-06-19)\n\n- 对齐 description 子技能名与路由表名称\n- 压缩路由表说明列\n- 新增跨技能协同指引章节\n- 删除冗余英文 description 行\n\n### v1.0.0 (2026-06-15)\n\n- 初始发布，含 12 个子技能：API设计、Bug诊断、代码生成、代码审查、重构建议、测试用例生成、技术选型、文档生成、任务拆解与执行、Spec驱动开发、Karpathy编码规范、项目记忆管理\n- 建立 references/ 目录隔离子技能模板\n- 引入 Karpathy 编码哲学、Wave 执行模式和 Spec 驱动开发 artifact flow\n\n## 文件结构\n\n- `SKILL.md` - 技能运行时指令\n- `README.md` - 本文件，用户入口文档\n- `references/` - 子技能详细模板（共17个子技能）\n\nFile v0.1.0:_meta.json\n\n{\n \"ownerId\": \"kn7096hdmqr56bh0825xpz8ft188dh24\",\n \"slug\": \"dev-expert\",\n \"version\": \"0.1.0\",\n \"publishedAt\": 1786814953369\n}\n\nFile v0.1.0:references/api-design.md\n\n# API设计 -- 智能API设计\n\n## 输入要求\n\n1. **业务需求**（必填）：需要设计的业务场景和功能\n2. **数据模型**（必填）：核心实体和字段\n3. **接口类型**（可选）：RESTful或GraphQL，默认RESTful\n4. **已有接口**（可选）：如果已有部分接口需要兼容\n5. **特殊要求**（可选）：如\"需要支持批量操作\"、\"需要Webhook回调\"\n\n## 执行流程\n\n### 第一步：Spec场景检查\n\n设计前检查是否有明确的spec：\n\n- **如有spec**：提取spec中的Requirement和Scenario作为接口设计依据，确保每个Requirement对应至少一个端点，每个Scenario映射为接口的成功/错误响应\n- **如无spec**：提示用户先使用 `Spec驱动开发` 对齐需求，或基于业务需求生成轻量级spec\n\n```\n✓ Spec场景检查: [检测到/未检测到] 需求规格\n[如检测到，列出 Requirement → 端点 映射]\n```\n\n### 第二步：需求分析\n\n- 识别API的使用场景和用户\n- 确定API的功能边界\n- 明确输入输出数据模型\n\n### 第三步：设计原则应用\n\n- 应用RESTful或GraphQL设计原则\n- 设计URL结构和HTTP方法\n- 定义请求/响应格式\n\n### 第四步：详细设计\n\n- 设计每个端点的详细规范\n- 定义错误处理策略\n- 设计认证和授权机制\n- 如接口涉及长任务/批处理/导入导出/生成任务，必须采用 `Init → Step → Poll` AJAX 渐进式防卡死架构\n\n### 第五步：API规范定义\n\n```markdown\n## API Spec: [API名称]\n\n### ADDED Requirements\n\n#### Requirement: [端点名称]\n\nThe system SHALL provide an endpoint to [功能描述].\n\n##### Scenario: 成功请求\n\n- GIVEN [前置条件]\n- WHEN 发送 `[METHOD] [路径]` 请求\n- THEN 返回 [状态码] 和 [响应体]\n\n##### Scenario: 错误处理\n\n- GIVEN [错误前置条件]\n- WHEN 发送 `[METHOD] [路径]` 请求\n- THEN 返回 [错误状态码] 和 [错误响应体]\n\n### Design\n\n- **URL结构**: [结构说明]\n- **认证方式**: [认证机制]\n- **版本策略**: [版本管理]\n\n### File Changes\n\n- `[API定义文件]` (new/modified)\n\n```\n\n### 第六步：文档生成\n\n- 生成OpenAPI/Swagger规范\n- 编写使用示例\n- 提供SDK代码示例\n\n### 第七步：记录到项目记忆\n\nAPI 设计完成后，将关键决策和规范记录到项目记忆（参见 `project-memory-management.md`）：\n- 记录 API 设计决策（如 RESTful vs GraphQL 选择理由）\n- 记录接口命名约定和版本策略\n- 记录认证/授权方案的选型依据\n\n## 输出格式\n\n````\n\n## API设计文档\n\n### 资源定义\n\n| 资源 | 说明 | 核心字段 |\n| -------- | ------ | ---------- |\n| [资源名] | [说明] | [字段列表] |\n\n### 接口列表\n\n#### [接口名称]\n\n**URL**：`[METHOD] /path`\n**说明**：[功能说明]\n\n**请求参数**：\n| 字段 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| [字段] | [类型] | [是/否] | [说明] |\n\n**响应格式**：\n\n```json\n{\n \"code\": 0,\n \"data\": { ... },\n \"message\": \"success\"\n}\n```\n\n**错误码**：\n| 错误码 | 说明 |\n|--------|------|\n| [CODE] | [说明] |\n\n### 通用规范\n\n- **认证方式**：[Bearer Token / API Key / OAuth2]\n- **版本控制**：[URL路径 / Header / 参数]\n- **分页方式**：[页码分页 / 游标分页]\n- **数据格式**：[snake_case / camelCase]\n\n### 长任务接口规范（如适用）\n\n| 端点 | 方法 | 说明 |\n|------|------|------|\n| `/tasks/{type}/init` | POST | 创建任务，返回 `task_id`、`total`、初始状态 |\n| `/tasks/{task_id}/step` | POST | 执行一批处理，返回进度和 `has_more` |\n| `/tasks/{task_id}/poll` | GET | 查询任务状态、进度、错误和结果 |\n\n**Step 响应必须包含**：`task_id`, `status`, `processed`, `total`, `percent`, `has_more`, `message`, `errors`\n\n````\n\n## 质量标准\n\n- URL必须使用名词复数形式，不能用动词（如/users而非/getUsers）\n- HTTP方法必须符合语义（GET无副作用、POST创建、PUT幂等更新、DELETE删除）\n- 错误响应必须包含机器可读的错误码和人工可读的消息\n- 分页接口必须说明最大页大小和默认页大小\n- 敏感操作（删除、批量修改）必须要求二次确认或特殊权限\n- 不得设计返回超大列表的接口（必须分页或流式）\n- 长任务/批处理接口必须采用 `Init → Step → Poll`，不得设计为单请求同步阻塞执行\n- Step 接口必须幂等、可重试，并限制单批处理数量\n\n## 失败回退机制\n\n| 步骤 | 失败条件 | 回退目标 | 最大重试 | 不可恢复时升级路径 |\n|------|---------|---------|---------|------------------|\n| 第一步：Spec场景检查 | 无spec且业务需求模糊 | 基于业务需求生成轻量级spec草案 | 1 | 标注\"需求未对齐\"，建议先走 Spec驱动开发 |\n| 第二步：需求分析 | 业务场景涉及多个领域，边界不清 | 拆分为多个子API分别设计 | 2 | 输出需求拆分建议，由用户确认后继续 |\n| 第三步：设计原则应用 | RESTful与GraphQL均不完全契合 | 选择主风格+局部例外，标注例外原因 | 1 | 输出两套方案对比，由用户决策 |\n| 第四步：详细设计 | 认证/授权机制与现有系统冲突 | 降级到最简认证（Bearer Token），标注待对齐 | 2 | 输出认证方案选型矩阵，移交架构决策 |\n| 第五步：API规范定义 | 端点数量过多导致单次输出超限 | 按资源域分批输出，每批3-5个端点 | 0 | 建议拆分为多个API版本迭代设计 |\n| 第六步：文档生成 | OpenAPI规范生成失败 | 降级为Markdown表格文档，标注\"未生成机器可读spec\" | 2 | 输出手写文档模板，建议人工补全 |\n| 第七步：记录到项目记忆 | 项目记忆系统不可用 | 输出Decision Record到本地文件 | 1 | 标注\"记忆未沉淀\"，提示用户手动保存 |\n\n## 关联Skill\n\n- **技术选型** — 设计前可用 `技术选型` 确定API技术方案（REST/GraphQL/gRPC）\n- **代码生成** — 设计后可用 `代码生成` 生成API接口代码\n- **测试用例生成** — 设计后可用 `测试用例生成` 生成API测试\n- **文档生成** — 设计后可用 `文档生成` 生成API文档\n\n## 连接器（可选增强）\n\n| 连接器 | 增强能力 |\n|--------|---------|\n| **Filesystem** | 读取现有项目代码结构和接口定义，辅助设计一致性 |\n| **Git** | 读取版本历史和变更记录，理解API演进路径 |\n| **Notion** | 将API设计文档写入 Notion 知识库，便于团队评审 |\n\nFile v0.1.0:references/bug-diagnosis.md\n\n# Bug诊断 -- 智能Bug诊断\n\n## 输入要求\n\n1. **错误信息**（必填）：错误日志、异常堆栈或报错截图\n2. **相关代码**（必填）：出错的代码片段\n3. **运行环境**（可选）：操作系统、语言版本、依赖版本\n4. **复现步骤**（可选）：如何触发这个错误\n\n## 执行流程\n\n### 第一步：Spec场景检查\n\n诊断前先检查相关spec中的scenario：\n- **如有spec**：确认bug是否涉及spec中的scenario，检查scenario的Given/When/Then是否被正确实现\n- **spec与实现不一致**：可能是spec理解偏差导致的bug\n- **无spec**：诊断后建议补充spec防止同类bug\n\n```\n✓ Spec场景检查:\n- 相关Scenario: [scenario名称]\n- 预期行为: [spec定义]\n- 实际行为: [观察到的行为]\n- 偏差分析: [spec vs 实现]\n```\n\n### 第二步：已知问题检查\n\n检查项目记忆中的已知问题：\n- 搜索项目记忆中的类似bug记录\n- 检查是否有已知的workaround\n- **发现新问题**：诊断完成后提示记录到项目记忆\n\n### 第三步：错误解析\n\n- 识别错误类型（语法错误、运行时错误、逻辑错误、环境错误）\n- 提取关键信息（错误码、错误消息、发生位置）\n- 分析堆栈跟踪（调用链、最后执行位置）\n\n### 第四步：根因分析\n\n| 错误类型 | 常见根因 | 分析方法 |\n|---------|---------|---------|\n| **语法错误** | 拼写错误、括号不匹配、缩进错误 | 定位到具体行号和字符 |\n| **运行时错误** | 空指针、数组越界、类型错误 | 检查变量状态和数据流 |\n| **逻辑错误** | 条件判断错误、算法缺陷 | 追踪执行路径和中间结果 |\n| **环境错误** | 依赖缺失、版本不兼容、配置错误 | 检查环境和依赖信息 |\n| **并发错误** | 竞态条件、死锁、资源竞争 | 分析线程/协程交互 |\n\n### 第五步：定位问题\n\n- 指出具体的代码位置（文件、函数、行号）\n- 说明变量在错误时刻的状态\n- 追踪数据流找到问题源头\n\n### 第六步：提供修复（Surgical Changes）\n\n- 给出修复后的代码\n- 说明修复原理\n- **Karpathy约束**：只修改修复Bug必需的代码，不改相邻代码、风格、注释\n- 提供验证修复的方法\n\n### 第七步：定义成功标准（Goal-Driven Execution）\n\n基于已确定的根因和修复方案，明确定义\"修复成功\"的标准：\n- **复现测试**：写一段能稳定触发Bug的测试/步骤\n- **成功标准**：修复后应达到什么状态（如\"空邮箱不再导致崩溃\"）\n- **验证方法**：如何确认修复有效（如\"运行复现测试10次均通过\"）\n\n**示例**：\n```\n成功标准：用户邮箱为空字符串时，validate_user() 抛出 ValueError 而非崩溃。\n复现测试：调用 validate_user({'email': ''}) → 应抛出 ValueError。\n验证方法：运行复现测试 → 通过。\n```\n\n### 第八步：记录到项目记忆\n\n修复完成后，将关键决策和变更记录到项目记忆（参见 `project-memory-management.md`）：\n- 记录 Bug 根因和修复方案（Decision Record 模式）\n- 记录新增的预防措施和编码规范（Convention Capture 模式）\n- 更新已知问题清单，防止同类 Bug 复发\n\n## 输出格式\n\n```\n## Bug诊断报告\n\n**错误类型**：[语法/运行时/逻辑/环境/并发]\n**错误信息**：[核心错误消息]\n**发生位置**：[文件/函数/行号]\n\n## 根因分析\n\n**问题描述**：[一句话说明]\n**详细分析**：[逐步推理过程]\n**相关代码**：\n```[问题代码]```\n\n## 修复方案\n\n```[修复后的代码]```\n\n**修复说明**：[为什么这样修复]\n\n## 验证方法\n\n1. [步骤1]\n2. [步骤2]\n\n## 预防措施\n\n- [建议1]\n- [建议2]\n```\n\n## 质量标准\n\n- 根因分析必须基于代码和日志证据，不能猜测\n- 修复代码必须可运行，且能解决原问题\n- 必须提供验证方法，让用户确认修复有效\n- 对于不确定的根因，标注\"最可能的原因\"并列出其他可能性\n- 环境相关错误必须说明具体的环境要求或版本限制\n- 不得建议用户\"重启试试\"或\"重新安装\"作为首要方案\n- **Karpathy红线**：修复前必须先写复现测试，修复后验证测试通过\n- **Karpathy红线**：只修改修复Bug必需的代码，不改相邻代码、风格、注释\n\n## CMS 常见 Bug 模式\n\n当诊断对象为 PHP+MySQL CMS 时，优先排查以下模式：\n\n| Bug 类型 | 典型表现 | 常见根因 | 修复方向 |\n|----------|---------|---------|---------|\n| PHP 版本兼容 | `Fatal error: Uncaught TypeError` / `Deprecated:` | 低版本代码运行在高版本 PHP | 参见 `cms-development.md` PHP 8.x 兼容性检查表 |\n| CMS 缓存失效 | 修改代码后页面无变化 | CMS 模板/数据缓存未清理 | 清理 `runtime/` `e/tmp/` `data/dbcache/` 后重试 |\n| 模板引擎错误 | 标签不解析或输出原始标签 | 模板语法错误或引擎版本差异 | 检查模板标签闭合和 CMS 版本对应语法 |\n| 数据库表前缀 | `Table 'xxx_tablename' doesn't exist` | 表前缀配置与实际不一致 | 检查 CMS 配置文件中的表前缀设置 |\n| MySQL 慢查询 | 页面卡顿 / SQL 超时 / CPU 飙高 | 缺索引、全表扫描、排序临时表 | 采集 SQL、参数、表行数和 EXPLAIN，参考 `mysql-database.md` |\n| MySQL 死锁 | `Deadlock found when trying to get lock` | 事务顺序不一致或锁范围过大 | 缩短事务、统一更新顺序、检查索引命中 |\n| 序列化数据 | `unserialize(): Error at offset` | WordPress `wp_options` 等序列化数据损坏 | 用 `maybe_unserialize()` 或修复序列化字符串长度 |\n| 伪静态路由 | 404 或路由不生效 | `.htaccess` / Nginx rewrite 规则缺失 | 检查伪静态规则和 CMS 路由配置 |\n| 文件编码 | 中文乱码 / `headers already sent` | UTF-8 BOM / GBK 编码混用 | 统一 UTF-8 无 BOM，用二进制方式读写文件 |\n\n详见 `cms-development.md`。\n\n## 关联Skill\n\n- **Karpathy编码规范** — 修复前可用 `Karpathy编码规范` 确认修复策略符合精准修改原则\n- **代码审查** — 修复后可用 `代码审查` 检查是否引入新问题\n- **测试用例生成** — 修复后可用 `测试用例生成` 生成回归测试\n- **代码生成** — 复杂修复可用 `代码生成` 生成替代实现\n- **CMS二次开发** — PHP+MySQL CMS 场景参考 `cms-development.md` 的兼容性检查和常见 Bug 模式\n- **MySQL数据库** — 数据库报错、慢查询、死锁、表结构和索引问题参考 `mysql-database.md`\n\n## 失败回退机制\n\n| 步骤 | 失败条件 | 回退目标 | 最大重试 | 不可恢复时升级路径 |\n|------|---------|---------|---------|------------------|\n| 第一步：Spec场景检查 | 无spec或spec与实现不一致 | 基于代码和错误信息诊断，标注\"无spec对照\" | 1 | 诊断后建议走 Spec驱动开发 补全spec防止同类bug |\n| 第二步：已知问题检查 | 项目记忆不可用或无相关记录 | 跳过已知问题检查，标注\"记忆未加载\" | 1 | 基于当前信息独立诊断，诊断完成后提示手动记录 |\n| 第三步：错误解析 | 错误信息不完整，无法分类 | 基于已有信息匹配最接近的错误分类 | 2 | 告知所需最小信息集（错误消息+触发操作），等待补充 |\n| 第四步：根因分析 | 多种可能根因均符合症状，无法唯一确定 | 列出候选根因，按可能性排序 | 2 | 输出诊断矩阵（候选根因×验证方法），由用户逐一排除 |\n| 第五步：定位问题 | 涉及第三方库/外部服务，代码不可审视 | 标注第三方边界，定位调用链最近的可控点 | 1 | 给出workaround方案，建议向第三方提issue |\n| 第六步：提供修复（Surgical Changes） | 修复方案需大规模重构（超出Bug修复范围） | 给出最小修复+重构建议供后续规划 | 2 | 拆分为Bug修复（立即）和架构优化（单独任务） |\n| 第七步：定义成功标准（Goal-Driven Execution） | 修复涉及多系统联调，单次验证不充分 | 定义分层验证标准（单元→集成→端到端） | 1 | 给出回归测试checklist，建议灰度发布验证 |\n| 第八步：记录到项目记忆 | 项目记忆系统不可用 | 输出Decision Record到本地文件 | 1 | 标注\"记忆未沉淀\"，提示用户手动保存 |\n\n## 连接器（可选增强）\n\n| 连接器 | 增强能力 |\n|--------|---------|\n| **Filesystem** | 读取项目源代码和配置文件，定位bug根因 |\n| **Git** | 读取提交历史和diff，追溯问题引入时间点 |\n| **Notion** | 将诊断报告和修复方案写入 Notion 知识库 |\n\nFile v0.1.0:references/cms-development.md\n\n# CMS二次开发 -- PHP+MySQL CMS 二次开发\n\n面向基于 PHP+MySQL 的 CMS 二次开发场景，提供从环境探测、兼容性修复、插件开发到安全加固的全链路指引。覆盖 EmpireCMS、WordPress、ThinkPHP、Laravel 等主流 CMS/框架。\n\n## 输入要求\n\n1. **开发任务**（必填）：需要实现的二次开发功能或修复目标\n2. **CMS 类型与版本**（可选）：如未提供，按自动探测流程识别\n3. **PHP 版本**（可选）：如未提供，按默认策略选择\n4. **已有代码**（可选）：涉及修改的现有代码片段或文件路径\n\n## 执行流程\n\n### 第一步：CMS 自动探测\n\n逐项匹配，命中即停：\n\n| 特征文件 | CMS |\n|----------|-----|\n| `e/class/connect.php` | EmpireCMS |\n| `wp-config.php` | WordPress |\n| `thinkphp/base.php` 或 `vendor/topthink` | ThinkPHP |\n| `artisan` + `bootstrap/app.php` | Laravel |\n| `system/core/CodeIgniter.php` | CodeIgniter |\n| `data/config.php` + `simplewind/` | ThinkCMF |\n| `index.php` + `data/conf/` | DedeCMS |\n| `composer.json` 含 `slim/slim` | Slim |\n| `composer.json` 含 `hyperf` | Hyperf |\n| `composer.json` 含 `yii` | Yii |\n\n**未确认 CMS 类型前，禁止生成任何框架特定代码。**\n\n```\n✓ CMS探测: [CMS名称] [版本号]\n 特征文件: [匹配到的特征文件]\n 表前缀: [数据库表前缀]\n 配置文件: [配置文件路径]\n```\n\n### 第二步：环境与版本确认\n\n#### PHP 版本选择\n\n| CMS | 最低版本 | 推荐版本 | 注意事项 |\n|-----|---------|---------|---------|\n| EmpireCMS 7.5 | 7.4 | 8.2 | 需 PHP 8 兼容补丁 |\n| WordPress 6.x | 7.4 | 8.2 | 部分老插件可能不兼容 8.3+ |\n| ThinkPHP 6 | 7.4 | 8.2 | |\n| ThinkPHP 8 | 8.0 | 8.2 | |\n| Laravel 9 | 8.0 | 8.1 | |\n| Laravel 10 | 8.1 | 8.2 | |\n| Laravel 11 | 8.2 | 8.3 | |\n| CodeIgniter 4 | 7.4 | 8.2 | |\n| DedeCMS v5.7 | 5.6 | 7.4 | 不支持 PHP 8 |\n| Hyperf | 8.0 | 8.2 | 建议跟随 Swoole 版本 |\n\n**版本选择原则**：优先匹配 CMS 要求 → 用户指定版本 → 默认 8.2\n\n#### 本地 PHP 路径\n\n| 版本 | 路径 | 状态 |\n|------|------|------|\n| 7.4 | `F:\\BtSoft\\php\\74\\php.exe` | 遗留项目 |\n| 8.0 | `F:\\BtSoft\\php\\80\\php.exe` | 过渡期 |\n| 8.1 | `F:\\BtSoft\\php\\81\\php.exe` | 过渡期 |\n| 8.2 | `F:\\BtSoft\\php\\82\\php.exe` | 新版测试 |\n| 8.3 | `F:\\BtSoft\\php\\83\\php.exe` | 新版测试 |\n| 8.4 | `F:\\BtSoft\\php\\84\\php.exe` | 新版测试 |\n| 8.5 | `F:\\BtSoft\\php\\85\\php.exe` | 当前默认 |\n\n### 第三步：数据库操作规范\n\n#### 访问层优先级\n\n1. CMS 官方数据访问层（WP: `$wpdb` / TP: `Db` 类 / Laravel: Eloquent / ECMS: `$empire->query()`）\n2. PDO 预处理（兜底）\n3. **禁止** `mysql_*` / `mysqli_*` 原生函数（CMS 内核已封装除外）\n\n#### 查询安全红线\n\n| 场景 | 禁止 | 强制 |\n|------|------|------|\n| 条件拼接 | `\"WHERE id=$id\"` | Prepared Statements |\n| LIKE | `LIKE \"%$kw%\"` | `LIKE CONCAT('%', ?, '%')` |\n| IN 子句 | 手动拼串 `IN(1,2,3)` | 动态占位符 `IN(?,?,?)` |\n| 批量写入 | 循环单条 INSERT | 事务 + VALUES 批量 |\n| 结果集 | 无限制全量拉取 | LIMIT/OFFSET 或游标 |\n\n#### 类型映射\n\n| MySQL 类型 | PHP 类型 | 说明 |\n|------------|---------|------|\n| INT/BIGINT | `int` | |\n| DECIMAL | `string` | 禁止 float，防金额精度丢失 |\n| DATETIME | `DateTimeImmutable` | 或 CMS 原生时间类 |\n| JSON | `array` | MySQL 5.7+ 原生类型 |\n| NULL | `null` | 禁止用空字符串替代 |\n\n#### 会话设置\n\n```sql\nSET NAMES utf8mb4;\nSET time_zone = '+08:00';\nSET SESSION sql_mode = 'STRICT_TRANS_TABLES,NO_ENGINE_SUBSTITUTION';\n```\n\n#### CMS 数据库差异\n\n| CMS | 表前缀 | 配置文件 | 特殊字段 |\n|-----|--------|---------|---------|\n| EmpireCMS | `phome_` 可自定义 | `e/config/config.php` | 信息表分主表+副表+索引表 |\n| WordPress | `wp_` 可自定义 | `wp-config.php` | `wp_options` 存序列化数据 |\n| ThinkPHP | 无默认前缀 | `config/database.php` | 遵循 ORM 定义 |\n| Laravel | 无默认前缀 | `.env` | Migration 管理结构 |\n| DedeCMS | `dede_` | `data/common.inc.php` | 旧式 `mediumint` 主键 |\n\n### 第四步：PHP 8.x 兼容性检查\n\n对现有代码执行兼容性扫描：\n\n| 规则 | 严重度 | 修复 |\n|------|--------|------|\n| 数组键加引号 | 致命 | `$arr[key]` → `$arr['key']` |\n| 可选参数不可先于必选参数 | 弃用 | 交换参数顺序 |\n| `each()` | 已移除 | 改用 `foreach()` |\n| `create_function()` | 已移除 | 匿名函数 |\n| `$HTTP_RAW_POST_DATA` | 已移除 | `php://input` |\n| `(real)` 类型转换 | 已移除 | `(float)` |\n| `get_magic_quotes_gpc()` | 已移除 | `function_exists()` 包裹 |\n| `strftime()` | 已弃用 | `date()` 或 `DateTime::format()` |\n| 双引号内 `${var}` | 已弃用 | `{$var}` |\n| `#` 注释中的 `#[` | 属性冲突 | 改用 `//` 注释 |\n\n**兼容性验证命令**：\n\n```bash\n# 目标版本 lint\nF:\\BtSoft\\php\\82\\php.exe -l file.php\n# 低版本兼容检查\nF:\\BtSoft\\php\\74\\php.exe -l file.php\n```\n\n### 第五步：安全红线检查\n\n| 漏洞 | 最低防护 |\n|------|---------|\n| SQL 注入 | 内部接口也必须参数绑定 |\n| XSS | 输出必须 `htmlspecialchars(..., ENT_QUOTES, 'UTF-8')` 或 CMS 等效函数 |\n| CSRF | 状态变更操作必须验证 Token |\n| 文件上传 | MIME 校验 + 扩展名白名单 + 重命名 + 非执行目录 |\n| 反序列化 | 禁止对不可信数据使用 `unserialize()`，改用 JSON |\n| 密码 | `password_hash()` / `password_verify()`，禁止 MD5/SHA1 |\n| Include | 禁止 `include $user_input`，路径必须白名单或固定 |\n\n### 第六步：插件/模块开发\n\n#### 开发标准\n\n- **一功能一文件**：独立功能一个 PHP 文件，清晰分明\n- **命名**：`action_module_function.php`\n- **目录**：按功能模块分子目录\n- **入口**：单一入口，不暴露内部文件\n- **依赖**：通过 CMS 标准 API 调用，不跨插件直接 include\n\n#### IDE 通用排除目录\n\n| 目录 | 原因 |\n|------|------|\n| `data/dbcache/` `data/fc/` `runtime/` `e/tmp/` | CMS 缓存，频繁变更 |\n| `vendor/` `node_modules/` | 第三方依赖，体积巨大 |\n| `uploads/` `d/file/` | 用户上传附件 |\n| `backup/` `sql_dump/` `back/` | 备份与导出 |\n| `.git/` `.svn/` | 版本控制 |\n\n#### AJAX 渐进式防卡死架构\n\nCMS 后台长任务必须优先采用 `Init → Step → Poll` 架构，禁止单请求同步执行到底。\n\n**强制适用场景**：\n\n- 批量导入/导出、批量更新、批量删除\n- 生成静态页、重建索引、清理缓存、图片压缩\n- 内容采集、远程同步、第三方接口批量拉取\n- 预计执行时间超过 3 秒，或处理数据量超过 100 条\n\n**端点职责**：\n\n| 端点 | 职责 | 必须返回 |\n|------|------|----------|\n| Init | 校验权限/CSRF/参数，创建任务记录，计算总量 | `task_id`, `total`, `status=queued` |\n| Step | 每次只处理一小批数据，更新进度和错误列表 | `processed`, `total`, `percent`, `has_more` |\n| Poll | 前端轮询任务状态，不执行重业务逻辑 | `status`, `percent`, `message`, `errors` |\n\n**实现约束**：\n\n- 每个 Step 必须限制批量大小，例如 20-100 条，避免 PHP 超时\n- 任务状态必须持久化到数据库、缓存或任务文件，不能只依赖 PHP 内存\n- Step 必须可重复调用，使用游标/offset/last_id 保证幂等\n- 状态变更必须校验登录态、权限和 CSRF Token\n- 错误必须记录到任务错误列表，允许部分失败后继续处理\n- 前端必须显示进度、当前批次、失败数、重试/取消入口\n- Poll 间隔建议 800-2000ms，连续失败 3 次后停止并提示\n\n**最小响应示例**：\n\n```json\n{\n \"task_id\": \"build_20260702_001\",\n \"status\": \"running\",\n \"processed\": 120,\n \"total\": 500,\n \"percent\": 24,\n \"has_more\": true,\n \"message\": \"正在处理第 120/500 条\",\n \"errors\": []\n}\n```\n\n### 第七步：代码风格与质量\n\n**优先级**：CMS 官方规范 > `.editorconfig`/`phpcs.xml` > 项目现有风格 > PSR-12\n\n| 类型 | 约定 | 示例 |\n|------|------|------|\n| 类名 | PascalCase | `UserController` |\n| 方法/函数 | camelCase | `getUserById()` |\n| 变量 | camelCase | `$userId` |\n| 常量 | UPPER_SNAKE | `MAX_ATTEMPTS` |\n| 字段/表名 | snake_case | `created_at` |\n| 注释 | 中文 | `// 校验登录态` |\n\n#### 五条自审\n\n| # | 规则 | 判定标准 |\n|---|------|---------|\n| 1 | 单一职责 | 每个函数只做一件事，不超过 40 行 |\n| 2 | 早返回 | 异常先 return/throw，主逻辑不被 if 嵌套包裹超过 2 层 |\n| 3 | 无魔法数字 | 硬编码数字/字符串提取为常量或配置 |\n| 4 | 外部输入必校验 | `$_GET/$_POST` 在使用前校验类型和范围 |\n| 5 | 错误处理闭环 | 每个 try 有 catch，每个 catch 有日志或提示，不吞异常 |\n\n#### 技术债禁令\n\n| # | 模式 | 正确做法 |\n|---|------|---------|\n| 1 | `if($a = func())` 赋值当判断 | 拆两行：`$a = func(); if($a !== null)` |\n| 2 | 函数返两种类型 `array\\|false` | 统一返回类型，空用 `[]`，异常用 throw |\n| 3 | `global $var` 在函数内 | 改为参数传入或依赖注入 |\n| 4 | `switch(true)` | 用 `match` 或 `if-elseif` 显式表达 |\n| 5 | 注释掉的代码块留着 | 直接删除，Git 历史可恢复 |\n| 6 | `else` 后紧跟 `if` 不合并 | 用 `elseif` 或提前 return 消除 else |\n| 7 | 函数参数超过 5 个 | 封装为对象/数组或拆分子函数 |\n| 8 | 循环内 `.=` 拼接大字符串 | 压入数组最后 `implode()` |\n\n### 第八步：交付检查清单\n\n| # | 检查项 | 方法 |\n|---|--------|------|\n| 1 | 数组键加引号 | `grep -Pn '\\$[a-z_]+\\s*\\[[a-z_]' *.php` |\n| 2 | 无裸 SQL 拼接 | 人工审查 $_GET/$_POST 直拼 |\n| 3 | 输出已转义 | echo/print 后有无 htmlspecialchars |\n| 4 | PHP Lint | `php -l file.php` |\n| 5 | 错误日志已清空 | `> F:\\BtSoft\\php_logs\\php82_errors.log` |\n| 6 | 事务边界正确 | 写操作路径 try/catch + rollback |\n| 7 | 长任务防卡死 | 批量任务采用 Init → Step → Poll，Step 有批量大小和进度持久化 |\n\n### 第九步：记录到项目记忆\n\n开发完成后，将关键决策记录到项目记忆（参见 `project-memory-management.md`）：\n- 记录 CMS 类型、版本和 PHP 版本选择理由（Decision Record 模式）\n- 记录数据库表结构和前缀约定（Convention Capture 模式）\n- 记录安全加固措施和已知兼容性问题\n- 记录插件/模块的目录结构和命名约定\n\n## 输出格式\n\n````markdown\n## CMS 二次开发交付说明\n\n### 1. 环境信息\n- **CMS**: [名称] [版本]\n- **PHP**: [版本]\n- **数据库**: [类型] [版本]\n- **表前缀**: [前缀]\n- **配置文件**: [路径]\n\n### 2. 变更文件清单\n| 文件 | 操作 | 说明 |\n|------|------|------|\n| [路径] | 新增/修改/删除 | [功能说明] |\n\n### 3. 数据库变更\n| 类型 | SQL | 说明 |\n|------|-----|------|\n| DDL/DDL | [SQL语句] | [变更说明] |\n\n### 4. 安全检查\n| 检查项 | 状态 | 说明 |\n|--------|------|------|\n| SQL 注入防护 | 通过/未通过 | [说明] |\n| XSS 防护 | 通过/未通过 | [说明] |\n| CSRF 防护 | 通过/未通过 | [说明] |\n| 文件上传安全 | 通过/未通过 | [说明] |\n\n### 5. 兼容性检查\n| 检查项 | PHP [版本] | 说明 |\n|--------|-----------|------|\n| 语法兼容 | 通过/未通过 | [说明] |\n\n### 6. PHP Lint 结果\n| 文件 | 状态 |\n|------|------|\n| [文件名] | 通过/失败 |\n\n### 7. 已知限制与后续建议\n- [限制1]\n- [建议1]\n````\n\n## 质量标准\n\n- 未确认 CMS 类型前禁止生成框架特定代码\n- 必须使用 CMS 官方数据访问层，禁止原生 SQL 拼接\n- DECIMAL 金额字段禁止用 PHP float\n- 输出必须转义（XSS 防护）\n- 状态变更操作必须验证 CSRF Token\n- PHP 8.x 兼容性必须通过 lint 检查\n- 插件必须遵循一功能一文件、单一入口原则\n- 代码风格必须遵循 CMS 官方规范 > PSR-12\n- 禁止使用 `==`，统一 `===`\n\n## 失败回退机制\n\n| 步骤 | 失败条件 | 回退目标 | 最大重试 | 不可恢复时升级路径 |\n|------|---------|---------|---------|------------------|\n| 第一步：CMS 自动探测 | 无特征文件匹配 | 列出最接近的 CMS 类型，要求用户确认 | 1 | 输出 CMS 特征检查清单，由用户手动确认 |\n| 第二步：环境与版本确认 | 目标 PHP 版本与 CMS 不兼容 | 降级到 CMS 推荐的最低稳定版本 | 1 | 输出版本兼容矩阵，由用户决策 |\n| 第三步：数据库操作规范 | CMS 数据访问层文档缺失 | 降级到 PDO 预处理，标注\"未使用 CMS 原生 API\" | 1 | 输出数据库操作建议，建议查阅 CMS 官方文档 |\n| 第四步：PHP 8.x 兼容性检查 | 兼容性问题数量超出单次修复能力 | 按致命/弃用分级，优先修复致命项 | 2 | 输出兼容性问题清单，建议分批修复 |\n| 第五步：安全红线检查 | 发现安全漏洞 | 立即修复，标注修复影响范围 | 0 | 安全问题零容忍，不发布含已知漏洞的代码 |\n| 第六步：插件/模块开发 | CMS 插件机制文档不可用 | 按通用单一入口模式开发，标注\"未遵循 CMS 插件规范\" | 1 | 建议查阅 CMS 官方插件开发文档后补充 |\n| 第七步：代码风格与质量 | 代码风格与 CMS 内核不一致 | 优先匹配 CMS 内核风格，标注风格差异 | 1 | 输出风格差异清单，建议统一 |\n| 第八步：交付检查清单 | Lint 检查未通过 | 修复语法错误后重新检查 | 3 | 输出未通过文件清单，建议人工修复 |\n| 第九步：记录到项目记忆 | 项目记忆系统不可用 | 输出 CMS 开发配置到本地文件 | 1 | 标注\"开发配置未沉淀\"，提示用户手动保存 |\n\n## 关联Skill\n\n- **前端设计** — CMS 模板页面、后台管理页面、H5 页面需参考 `frontend-design.md` 的视觉、交互、响应式和浏览器验证规范\n- **代码生成** — CMS 代码生成时参考本 Skill 的数据访问层和安全规范\n- **Bug诊断** — CMS Bug 诊断时参考本 Skill 的 PHP 8.x 兼容性检查和常见模式\n- **代码审查** — CMS 代码审查时参考本 Skill 的安全红线和技术债禁令\n- **技术选型** — CMS 版本选型时参考本 Skill 的 PHP 版本推荐矩阵\n- **MySQL数据库** — CMS 表结构、索引、SQL、事务、慢查询和迁移回滚参考 `mysql-database.md`\n- **项目记忆管理** — 开发配置和约定沉淀时参考本 Skill 的记录模板\n\n## 连接器（可选增强）\n\n| 连接器 | 增强能力 |\n|--------|---------|\n| **Filesystem** | 读取 CMS 特征文件和配置，自动探测 CMS 类型和版本 |\n| **Git** | 读取版本历史，分析 CMS 二开变更轨迹 |\n| **Notion** | 将 CMS 二开文档和配置记录写入 Notion 知识库 |\n\nFile v0.1.0:references/code-generation.md\n\n# 代码生成 -- 智能代码生成\n\n## 输入要求\n\n1. **功能需求**（必填）：需要实现的功能描述\n2. **编程语言**（必填）：如Python、JavaScript、Go、Java\n3. **框架/库**（可选）：如React、Spring Boot、FastAPI\n4. **约束条件**（可选）：如\"时间复杂度O(n)\"、\"不使用第三方库\"\n5. **输入输出示例**（可选）：期望的输入和输出格式\n\n## 执行流程\n\n### 第一步：Spec检查\n\n编码前检查是否有明确的spec：\n\n- **如有spec**：提取spec中的scenario作为编码验收依据，严格按Given/When/Then实现\n- **如无spec**：提示用户先使用 `Spec驱动开发` 对齐需求，或生成轻量级spec\n\n```\n✓ Spec检查: [检测到/未检测到] 需求规格\n[如检测到，列出相关scenario]\n```\n\n### 第二步：编码前环境确认\n\n生成代码前，先确认环境和依赖：\n\n- 确认目标编程语言和版本\n- 确认依赖库和框架版本\n- 确认运行环境约束（操作系统、内存、网络等）\n\n**示例**：\n\n```\n环境确认：Python 3.10+，无第三方依赖，单文件运行。\n```\n\n### 第三步：需求分析\n\n- 理解功能需求和业务场景\n- 识别核心算法或设计模式\n- 明确约束条件（性能、兼容性、依赖）\n- 明确陈述假设：如果需求有歧义，列出多种理解并选择最简方案\n- **Karpathy约束**：识别并排除超出需求的功能；如果存在更简单的方案，优先选择简单方案\n- **加载项目规范**：从项目记忆中加载相关编码规范（命名约定、错误处理模式等）\n\n### 第四步：设计方案\n\n- 确定函数/类/模块的接口\n- 设计数据结构\n- 规划错误处理策略\n- **Karpathy约束**：最小设计，不预先为\"未来可能\"做抽象\n\n### 第五步：代码实现（Simplicity First）\n\n生成包含以下要素的代码：\n\n- 清晰的函数/类签名\n- 输入验证和参数检查\n- 核心逻辑实现（最少代码解决问题）\n- 错误处理（只处理可能发生的场景）\n- 边界条件处理（空值、越界、超时）\n- **简洁优先**（Karpathy原则）：选择最简单的实现方式\n\n**Karpathy约束**：\n\n- 不要超出需求的功能\n- 不要为单次使用代码做抽象\n- 不要未被要求的\"灵活性\"或\"可配置性\"\n- 不要为不可能场景做错误处理\n- 如果200行可以50行搞定，重写\n\n### 第六步：代码审查\n\n**审查路由规则**：\n\n- **内联精简审查**（本步骤）：适用于单函数/单文件、功能边界清晰、无外部依赖的代码生成，执行以下四项基本检查。\n- **完整深度审查**（走 `code-review.md` 完整流程）：适用于多文件/多模块联动、涉及数据持久化/网络通信/安全敏感操作，或代码超过 200 行时，触发 7 步完整审查流程（Spec 一致性→项目规范→代码理解→多维度审查→Karpathy 维度→问题分级→修复建议）。\n\n**内联审查项**：\n\n- 检查代码逻辑是否正确\n- 确认是否有更好的实现方式\n- 验证边界条件处理\n- **精准修改**（Karpathy原则）：只修改必要部分，不引入无关变更\n\n### 第七步：补充说明（Goal-Driven）\n\n- 使用示例\n- 复杂度分析\n- 注意事项\n- **成功标准**：说明如何验证这段代码正确工作\n\n### 第八步：记录到项目记忆\n\n代码生成完成后，将关键决策和新发现的规范记录到项目记忆（参见 `project-memory-management.md`）：\n\n- 记录实现中的关键技术选择（Decision Record 模式）：如算法选型、依赖库选择、错误处理策略\n- 记录新发现的编码规范（Convention Capture 模式）：如命名约定、目录组织、模块划分\n- 若生成过程中暴露需求歧义，反馈到 spec 或更新规范防止下次重蹈\n\n## Task Summary: 代码生成\n\n```\n**完成状态**: [完成/部分完成]\n**生成文件**: [文件列表]\n**关键决策**: [实现中做出的技术选择]\n**偏差说明**: [与原始需求的差异及原因]\n**验证建议**: [如何验证这段代码]\n```\n\n## 输出格式\n\n````markdown\n# [功能名称]\n\n## 代码实现\n\n```[语言]\n[完整可运行的代码，含必要的 import / package 声明]\n```\n\n## 使用示例\n\n```[语言]\n// 示例输入（以下以 JavaScript 为例）\nconst result = functionName(input);\nconsole.log(result);\n// 示例输出\n// { \"key\": \"value\" }\n```\n\n## 复杂度分析\n\n- **时间复杂度**：[O(X)]，[一句话说明瓶颈操作]\n- **空间复杂度**：[O(X)]，[一句话说明额外空间来源]\n\n## 设计说明\n\n[为什么选择这种实现方式，而非备选方案。如有 trade-off 需明确说明。]\n\n## 边界条件处理\n\n| 边界条件 | 处理方式 |\n| ----------------- | ----------------------------- |\n| 空输入 | [返回空/抛异常/默认值] |\n| 超大输入（n > ?） | [分页/流式/降级] |\n| 非法参数类型 | [抛 IllegalArgumentException] |\n| 并发/重入 | [锁/无状态/幂等] |\n\n## 依赖项\n\n- [第三方库名称] v[X.Y.Z]：[用途说明]\n\n## 注意事项\n\n1. [注意事项1：如特定环境限制]\n2. [注意事项2：如已知局限性]\n3. [注意事项3：如后续优化方向]\n````\n\n## 质量标准\n\n- 生成的代码必须可直接运行，不能是伪代码\n- 必须处理常见的边界条件（空输入、越界、类型错误）\n- 必须包含错误处理，不能假设输入总是合法\n- 变量和函数命名必须符合语言惯例（如Python用snake_case，JS用camelCase）\n- 复杂逻辑必须添加注释说明\n- 不得生成包含安全漏洞的代码（如SQL拼接、eval执行用户输入）\n- **Karpathy红线**：不得为单一需求生成抽象类、接口、配置对象等过度设计\n- 涉及 MySQL/SQL/表结构/索引/事务时，必须先参考 `mysql-database.md`，再生成代码\n\n## CMS 二次开发注意事项\n\n当目标为 PHP+MySQL CMS 二次开发时，额外遵守：\n\n1. **数据访问层**：必须使用 CMS 官方 API（WP: `$wpdb` / TP: `Db` / Laravel: Eloquent / ECMS: `$empire->query()`），禁止原生 `mysqli_*`\n2. **SQL 安全**：条件必须参数绑定，LIKE 用 `CONCAT('%', ?, '%')`，禁止 `$_GET/$_POST` 直拼\n3. **输出转义**：`htmlspecialchars(..., ENT_QUOTES, 'UTF-8')` 或 CMS 等效函数，模板引擎输出默认转义\n4. **金额字段**：DECIMAL → PHP `string`，禁止 `float`，防止精度丢失\n5. **插件标准**：一功能一文件，命名 `action_module_function.php`，单一入口\n6. **PHP 兼容性**：数组键加引号 `$arr['key']`，禁止 `each()`/`create_function()`/`mysql_*`，`===` 替代 `==`\n\n详见 `cms-development.md`。\n\n## 关联Skill\n\n- **Karpathy编码规范** — 生成后可用 `Karpathy编码规范` 检查是否符合编码哲学\n- **前端设计** — 生成页面/组件前先用 `前端设计` 确定信息架构、视觉规范、交互状态和响应式策略\n- **代码审查** — 生成后可用 `代码审查` 检查代码质量\n- **测试用例生成** — 生成后可用 `测试用例生成` 生成配套测试\n- **文档生成** — 生成后可用 `文档生成` 生成函数文档\n- **CMS二次开发** — PHP+MySQL CMS 场景参考 `cms-development.md` 的数据访问层和安全规范\n- **MySQL数据库** — 涉及表结构、SQL、索引、事务、慢查询和迁移时参考 `mysql-database.md`\n\n## 失败回退机制\n\n| 步骤 | 失败条件 | 回退目标 | 最大重试 | 不可恢复时升级路径 |\n| ---------------------- | ---------------------------------- | -------------------------------------- | -------- | -------------------------------------------------- |\n| 第一步：Spec检查 | 无关联spec/文件/用户上下文 | 直接基于用户描述启动，标注\"无spec对照\" | 0 | 提示用户先走 Spec驱动开发 对齐需求，或手动描述需求 |\n| 第二步：编码前环境确认 | 目标语言/版本无法确认 | 使用当前环境默认设置，标注假设 | 1 | 提示用户明确指定语言和版本 |\n| 第三步：需求分析 | 需求存在不可调和的歧义 | 列出歧义点，要求用户澄清 | 0 | 选择最简方案并标注\"假设\"，由用户后续修正 |\n| 第四步：设计方案 | 设计约束冲突（性能vs简洁不可兼得） | 优先简洁方案，标注性能取舍 | 2 | 提供两套方案供用户选择 |\n| 第五步：代码实现（Simplicity First） | 依赖库不可用或版本不兼容 | 降级到标准库实现或标注兼容性说明 | 2 | 输出伪代码框架+待替换标注，移交人工实现 |\n| 第六步：代码审查 | 内联审查发现逻辑缺陷 | 退回第四步重新设计方案 | 2 | 触发 code-review.md 完整审查流程 |\n| 第七步：补充说明（Goal-Driven） | 成功标准无法量化或验证方法不可行 | 提供定性验证建议，标注\"待量化\" | 2 | 输出验证骨架，建议用户补充具体验收条件 |\n| 第八步：记录到项目记忆 | 项目记忆系统不可用 | 输出Decision Record到本地文件 | 1 | 标注\"决策未沉淀\"，提示用户手动保存 |\n\n## 连接器（可选增强）\n\n| 连接器 | 增强能力 |\n| -------------- | -------------------------------------------------- |\n| **Filesystem** | 读取项目现有代码结构和编码规范，生成风格一致的代码 |\n| **Git** | 读取版本历史，了解代码演进上下文 |\n| **Notion** | 将生成的代码和设计文档写入 Notion 知识库 |\n\nFile v0.1.0:references/code-review.md\n\n# 代码审查 -- 智能代码审查\n\n## 输入要求\n\n1. **代码片段**（必填）：需要审查的代码\n2. **编程语言**（必填）：代码使用的语言\n3. **上下文说明**（可选）：这段代码的功能、所在的模块\n4. **审查重点**（可选）：如\"重点关注安全性\"、\"检查内存泄漏\"\n\n## 执行流程\n\n### 第一步：Spec一致性检查\n\n审查前先检查代码是否符合spec：\n\n- **如有spec**：逐条检查spec中的scenario是否被正确实现\n- **发现不一致**：标注spec与实现的偏差，建议修正spec或代码\n- **无spec**：提示建议在审查后使用 `Spec驱动开发` 补全spec\n\n```\n✓ Spec一致性检查:\n- Scenario 1: [通过/失败] — [说明]\n- Scenario 2: [通过/失败] — [说明]\n```\n\n### 第二步：项目规范检查\n\n检查代码是否符合项目记忆中的规范：\n\n- 命名约定（snake_case / camelCase / PascalCase）\n- 错误处理模式（异常 vs 返回码）\n- 导入排序、文件组织等风格规范\n- **发现新规范**：提示记录到项目记忆\n\n### 第三步：代码理解\n\n- 识别编程语言和框架\n- 理解代码的功能和逻辑\n- 识别代码的上下文（函数、类、模块）\n\n### 第四步：多维度审查\n\n| 维度 | 检查内容 | 权重 |\n| ---------------- | --------------------------------------- | ---- |\n| **Bug风险** | 空指针、数组越界、资源未释放、并发问题 | 30% |\n| **安全性** | SQL注入、XSS、敏感信息硬编码、权限绕过 | 25% |\n| **性能** | 时间复杂度、内存泄漏、N+1查询、循环内IO | 20% |\n| **可维护性** | 命名规范、函数长度、圈复杂度、重复代码 | 15% |\n| **最佳实践** | 语言特性利用、设计模式、错误处理 | 10% |\n| **Karpathy维度** | 简洁优先、精准修改、编码前思考 | 附加 |\n\n### 第五步：Karpathy维度审查\n\n在常规审查之外，按Karpathy编码哲学进行专项审查：\n\n**简洁优先（Simplicity First）**：\n\n- [ ] 是否包含超出需求的功能？\n- [ ] 是否存在单次使用的抽象（Strategy模式做简单计算）？\n- [ ] 是否可以用更少的代码实现（200行能否变50行）？\n- [ ] 是否包含推测性功能（缓存、验证、通知等未被要求的）？\n\n**精准修改（Surgical Changes）**（针对修改的代码）：\n\n- [ ] 是否只修改了必要的代码？\n- [ ] 是否\"顺手\"改进了相邻代码、注释或格式？\n- [ ] 是否保持了原有代码风格？\n- [ ] 每一行修改是否能追溯到需求？\n\n**编码前思考（Think Before Coding）**：\n\n- [ ] 代码中是否有未陈述的假设（如假设数据总是存在）？\n- [ ] 是否有硬编码的\"魔法值\"没有说明原因？\n- [ ] 函数/类设计是否考虑了多种使用场景？\n\nKarpathy维度问题不纳入 severity 分级，单独标注为 **「Karpathy建议」**。\n\n### 第六步：问题分级\n\n| 级别 | 说明 | 必须修复 |\n| ---------------------- | ---------------------------------- | -------- |\n| **致命（Critical）** | 会导致系统崩溃、数据丢失、安全漏洞 | 是 |\n| **严重（Major）** | 明显Bug、性能严重下降、安全隐患 | 是 |\n| **警告（Warning）** | 潜在风险、代码异味、不符合规范 | 建议 |\n| **建议（Suggestion）** | 可优化点、风格问题、最佳实践 | 可选 |\n\n### 第七步：生成修复建议\n\n对每个问题：\n\n- 指出具体代码位置（行号/函数名）\n- 说明问题原因和影响\n- 提供修复后的代码示例\n- 说明修复后的收益\n\n**Karpathy建议的修复优先级**：\n\n- 过度设计 → 先简化再审查\n- 顺手重构 → 回滚无关修改\n- 隐藏假设 → 添加参数校验或文档\n\n### 第八步：记录到项目记忆\n\n审查完成后，将发现的问题和规范沉淀到项目记忆（参见 `project-memory-management.md`）：\n\n- 记录反复出现的坏味道模式（Convention Capture 模式）：提炼为团队编码规范避免复发\n- 记录安全/性能问题的修复模式（Decision Record 模式）：形成可复用的检查清单\n- 若审查中发现 spec 与实现偏差，反馈到 spec 同步更新\n- 更新已知问题清单，标注高风险模块供后续审查重点关注\n\n## 输出格式\n\n````\n## 代码审查报告\n\n**审查文件**：[文件名]\n**编程语言**：[语言]\n**代码行数**：[X行]\n**问题总数**：[X]个（致命[X] / 严重[X] / 警告[X] / 建议[X]）\n\n## 致命问题（必须修复）\n\n### 问题1：[问题标题]\n**位置**：[函数名/行号范围]\n**原代码**：\n```[代码片段]```\n**问题描述**：[具体说明]\n**影响**：[可能导致什么后果]\n**修复建议**：\n```[修复后的代码]```\n\n## 严重问题（建议修复）\n\n### 问题N：[问题标题]\n...\n\n## 警告与建议\n\n...\n\n## 审查总结\n\n- **整体评分**：[X]/100\n- **主要风险**：[一句话总结]\n- **优先修复**：[Top 3问题]\n- **正向评价**：[代码中的亮点]\n````\n\n## 质量标准\n\n- 每个问题必须指出具体代码位置，不能只说\"这段代码\"\n- 修复建议必须是可运行的代码，不能是伪代码或描述\n- 致命问题必须说明可能导致的具体后果（如\"可能导致SQL注入，攻击者可获取全表数据\"）\n- 不得误报（把正确代码标记为问题），不确定时标注\"疑似\"\n- 安全审查必须覆盖OWASP Top 10相关风险\n- 性能审查必须量化影响（如\"时间复杂度从O(n)变为O(n²)\"）\n- 涉及 MySQL/SQL 时必须检查参数绑定、索引策略、EXPLAIN 证据、事务边界、DDL 风险和回滚方案\n\n### MySQL 索引审查清单\n\n| 检查项 | 判定标准 |\n|--------|----------|\n| 查询路径 | 索引必须对应 WHERE/JOIN/ORDER BY/GROUP BY/分页路径 |\n| 联合索引顺序 | 必须说明等值、区分度、范围、排序、覆盖字段顺序 |\n| EXPLAIN | 高频/慢查询必须提供 `key/type/rows/Extra` 证据 |\n| 覆盖索引 | 只允许覆盖高频小字段列表，禁止塞入大字段 |\n| 冗余索引 | 检查 `(a)` 与 `(a,b)`、唯一索引与普通索引重复 |\n| 写入成本 | 新增索引必须评估 INSERT/UPDATE/DELETE 成本 |\n| 删除索引 | 必须有依赖 SQL、风险说明和回滚 SQL |\n\n## CMS 安全审查清单\n\n当审查对象为 PHP+MySQL CMS 代码时，在「多维度审查」之外追加以下专项检查：\n\n| 检查项 | 检查方法 | 判定标准 |\n| ---------------------- | ----------------------------------------------------------------- | ---------------------------------------- |\n| SQL 注入（CMS 上下文） | 检查是否使用 CMS 官方数据访问层，是否存在 `$_GET/$_POST` 直拼 SQL | 必须使用参数绑定或 CMS API |\n| XSS（CMS 模板） | 检查模板输出是否默认转义，PHP 直接输出是否 `htmlspecialchars` | 所有用户输入输出前必须转义 |\n| CSRF | 检查表单提交和状态变更操作是否有 Token 验证 | POST/PUT/DELETE 必须验证 CSRF Token |\n| 文件上传 | 检查是否有 MIME 校验 + 扩展名白名单 + 重命名 + 非执行目录 | 四项缺一不可 |\n| 反序列化 | 检查是否有 `unserialize()` 对不可信数据的调用 | 禁止，改用 JSON |\n| 密码存储 | 检查密码是否用 `password_hash()`/`password_verify()` | 禁止 MD5/SHA1 |\n| Include 注入 | 检查是否有 `include $user_input` | 路径必须白名单或固定 |\n| 数组键引号 | 检查 `$arr[key]` 无引号访问 | 必须加引号 `$arr['key']`，PHP 8 致命错误 |\n| 类型比较 | 检查是否使用 `==` 而非 `===` | 统一 `===` |\n\n详见 `cms-development.md` 安全红线章节。\n\n## 关联Skill\n\n- **Karpathy编码规范** — 用 `Karpathy编码规范` 深入评估代码是否符合编码哲学\n- **前端设计** — 前端页面审查时参考 `前端设计` 的交互状态、响应式、可访问性和浏览器验证清单\n- **Bug诊断** — 审查发现的具体Bug可用 `Bug诊断` 深入分析根因\n- **重构建议** — 审查发现的代码异味可用 `重构建议` 获取详细重构方案\n- **测试用例生成** — 修复后可用 `测试用例生成` 补充回归测试\n- **CMS二次开发** — PHP+MySQL CMS 场景参考 `cms-development.md` 的安全红线和兼容性检查\n- **MySQL数据库** — 审查 SQL 注入、慢查询、索引滥用、事务边界和迁移风险时参考 `mysql-database.md`\n\n## 失败回退机制\n\n| 步骤 | 失败条件 | 回退目标 | 最大重试 | 不可恢复时升级路径 |\n| ---------------------- | -------------------------------- | ---------------------------------------------- | --------- | -------------------------------------------------------- |\n| 第一步：Spec一致性检查 | Spec文档不可用或无关联 | 跳过一致性检查，从代码反推预期行为 | 0 | 标注\"无Spec对照\"，仅审查内部一致性和通用规范 |\n| 第二步：项目规范检查 | 项目规范文档缺失或代码文件不可读 | 跳过规范加载，直接分析代码结构，标注\"规范缺失\" | 2 | 基于通用最佳实践审查，建议补充项目规范 |\n| 第三步：代码理解 | 代码量过大超出分析能力 | 分批审查，逐文件输出，最后汇总 | 0（分批） | 告知用户分批结果，建议缩小审查范围 |\n| 第四步：多维度审查 | 某维度缺少足够上下文 | 标注\"待验证\"，跳过该维度 | 1 | 输出已覆盖维度的审查结果，缺项标注为\"建议补充后重新审查\" |\n| 第五步：Karpathy维度审查 | 简洁性判断主观争议 | 标注为\"建议评估\"，附正反观点 | 0 | 交由用户/团队讨论决策 |\n| 第六步：问题分级 | 严重性边界模糊（中/高难判） | 默认升级一级（保守策略），标注\"存疑\" | 1 | 所有存疑项统一标记为\"需确认\" |\n| 第七步：生成修复建议 | 修复方案可能引入新问题 | 标注风险提示，建议回归测试范围 | 2 | 输出修复建议+单元测试覆盖要求，由开发者自行实施 |\n| 第八步：记录到项目记忆 | 项目记忆系统不可用 | 输出审查报告和规范沉淀到本地文件 | 1 | 标注\"审查结果未沉淀\"，提示用户手动保存 |\n\n## 连接器（可选增强）\n\n| 连接器 | 增强能力 |\n| -------------- | -------------------------------------- |\n| **Filesystem** | 读取待审查代码和相关依赖文件 |\n| **Git** | 读取diff和提交历史，辅助变更范围审查 |\n| **Notion** | 将审查报告和整改清单写入 Notion 知识库 |\n\nFile v0.1.0:references/doc-generation.md\n\n# 文档生成 -- 智能文档生成\n\n## 输入要求\n\n1. **代码/项目**（必填）：需要生成文档的代码或项目描述\n2. **文档类型**（必填）：函数文档/README/API文档/架构文档\n3. **输出格式**（可选）：Markdown/HTML/reStructuredText，默认Markdown\n4. **目标读者**（可选）：开发者/用户/运维，默认开发者\n5. **语言**（可选）：中文/英文，默认中文\n\n## 执行流程\n\n### 第一步：Spec一致性检查\n\n编写文档前检查与spec的一致性：\n- **如有spec**：确保文档描述与spec中的scenario一致\n- **发现不一致**：标注文档与spec的偏差，建议同步更新\n- **无spec**：文档中标注\"基于当前实现，建议补充spec\"\n\n```\n✓ Spec一致性检查:\n- 文档描述 vs Spec: [一致/不一致]\n- 需要同步更新: [是/否]\n```\n\n### 第二步：内容分析\n\n- 分析目标受众（开发者/用户/维护者）\n- 确定文档类型和深度\n- 识别关键信息点\n\n### 第三步：结构设计\n\n- 设计文档大纲和章节\n- 确定示例和图示\n- 规划交叉引用\n\n### 第四步：内容编写\n\n- 编写清晰简洁的说明\n- 添加代码示例和截图\n- 包含使用场景和最佳实践\n- **引用Spec**：在相关章节引用spec中的scenario作为行为依据\n\n### 第五步：质量检查\n\n- 检查准确性和完整性\n- 验证代码示例可运行\n- 确认格式一致性\n- **Spec同步**：确认文档与spec无冲突\n\n### 第六步：记录到项目记忆\n\n文档生成完成后，将关键决策记录到项目记忆（参见 `project-memory-management.md`）：\n- 记录文档结构和模板选择理由\n- 记录 API 文档规范约定（如参数说明格式、错误码规范）\n- 更新项目文档索引，确保后续文档保持一致性\n\n## 输出格式\n\n### 函数文档示例\n\n```markdown\n## [函数名]\n\n**功能**：[一句话说明]\n\n**签名**：\n```[语言]\n[函数签名]\n```\n\n**参数**：\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| [参数] | [类型] | [是/否] | [说明] |\n\n**返回值**：\n| 类型 | 说明 |\n|------|------|\n| [类型] | [说明] |\n\n**异常**：\n| 异常 | 说明 |\n|------|------|\n| [异常] | [触发条件] |\n\n**示例**：\n```[语言]\n[使用示例]\n```\n```\n\n### README示例\n\n```markdown\n# [项目名]\n\n[项目简介]\n\n## 功能特性\n\n- [特性1]\n- [特性2]\n\n## 安装\n\n```bash\n[安装命令]\n```\n\n## 使用\n\n```[语言]\n[使用示例]\n```\n\n## API文档\n\n自动由代码注解/JSDoc/Python docstrings 提取生成。如项目接入 Swagger/OpenAPI，同时导出机器可读接口定义。\n\n## 贡献\n\n[贡献指南]\n```\n\n## 质量标准\n\n- 文档必须准确反映代码功能，不能虚构不存在的功能\n- 参数说明必须包含类型、必填性和取值范围\n- 示例代码必须可直接运行，不能是伪代码\n- README必须包含安装和使用说明，不能只有功能列表\n- API文档必须包含错误码和异常情况\n- 不得遗漏关键信息（如必要的配置项、环境要求）\n\n## 失败回退机制\n\n| 步骤 | 失败条件 | 回退目标 | 最大重试 | 不可恢复时升级路径 |\n|------|---------|---------|---------|------------------|\n| 第一步：Spec一致性检查 | 无spec或spec与代码严重不一致 | 标注\"基于当前实现反推\"，跳过一致性检查 | 1 | 建议先走 Spec驱动开发 补全spec |\n| 第二步：内容分析 | 代码量大，关键信息点超出单次分析能力 | 按模块分批分析，每批输出局部文档 | 0 | 建议缩小文档范围或分章节生成 |\n| 第三步：结构设计 | 文档类型与目标读者组合产生结构冲突 | 优先服务主要读者，次要读者用附录补充 | 1 | 输出两套结构方案，由用户选择 |\n| 第四步：内容编写 | 代码示例无法直接运行 | 标注\"示例待验证\"，提供伪代码框架 | 2 | 输出最小可运行示例 + 待补全标记 |\n| 第五步：质量检查 | 发现文档与代码功能不一致 | 退回第四步修订内容 | 2 | 标注不一致清单，建议代码与文档同步评审 |\n| 第六步：记录到项目记忆 | 项目记忆系统不可用 | 输出文档索引到本地文件 | 1 | 标注\"索引未沉淀\"，提示用户手动保存 |\n\n## 关联Skill\n\n- **前端设计** — 生成设计系统、组件规范、页面交互说明时参考 `前端设计`\n- **代码审查** — 生成前可用 `代码审查` 确保代码逻辑正确\n- **API设计** — API设计完成后可用 `文档生成` 生成接口文档\n- **代码生成** — 生成代码后可用 `文档生成` 生成配套文档\n\n## 连接器（可选增强）\n\n| 连接器 | 增强能力 |\n|--------|---------|\n| **Filesystem** | 读取项目源代码，提取函数签名和注释生成文档 |\n| **Git** | 读取提交历史，生成变更日志和版本说明 |\n| **Notion** | 将生成的文档写入 Notion 知识库 |\n\nFile v0.1.0:references/frontend-design.md\n\n# 前端设计 -- UI/UX 与前端实现设计\n\n面向 Web 前端、H5、后台管理、官网、落地页、CMS 模板页面、品牌视觉、Banner、图标和社交媒体图片，提供从需求理解、设计思维、信息架构、视觉设计、交互状态、响应式布局到工程落地和浏览器验证的完整流程。\n\n> 增强参考：`ui-ux-pro-max-zh.md`。本模板吸收其高价值规则，但不原样复制大型设计知识库，避免前端设计路由过重。\n\n## UI/UX Pro Max 增强规则\n\n### 设计优先级\n\n| 优先级 | 类别 | 要求 |\n| ------ | ---------- | ----------------------------------------------------------- |\n| 1 | 无障碍访问 | WCAG 2.1 AA，文本对比度至少 4.5:1，支持键盘导航和屏幕阅读器 |\n| 2 | 响应式设计 | 移动优先，覆盖 `sm/md/lg/xl/2xl` 或项目既有断点 |\n| 3 | 视觉层级 | 标题、主操作、正文、辅助信息必须有明确层级 |\n| 4 | 一致性 | 统一 4/8px 间距、字体层级、色彩语义和组件状态 |\n| 5 | 性能 | 图片优化、懒加载、资源压缩、首屏资源控制 |\n| 6 | 交互反馈 | Hover/Active/Focus/Loading/Empty/Error 状态全覆盖 |\n| 7 | 排版 | 正文行高约 1.5，标题行高约 1.2，正文行长控制在 45-75 字符 |\n| 8 | 色彩 | 优先语义化 token，支持暗色模式时必须定义覆盖规则 |\n| 9 | 动效 | 150-300ms 过渡，支持 `prefers-reduced-motion` 降级 |\n| 10 | 间距 | 组件内 8-16px，分区 24-48px，避免随机间距 |\n\n### 设计资产覆盖\n\n- **设计风格**：极简、企业极简、Bento、暗色模式、玻璃态、新拟物、孟菲斯、野兽派、粘土风格等，必须说明适用场景和不适用场景\n- **色板体系**：输出主色、辅助色、中性色、状态色，优先使用 HSL/CSS 变量或项目 token\n- **字体配对**：按 SaaS、企业、内容、电商、开发工具等场景选择标题/正文字体组合\n- **品牌规范**：Logo 使用、安全距离、最小尺寸、禁用规则、品牌色、语气和资产管理\n- **Banner 设计**：尺寸、视觉层级、CTA、主标题、背景图/插画、平台适配\n- **图标设计**：风格、尺寸、线宽、圆角、可读性、SVG 可访问性\n- **社交媒体图片**：平台尺寸、信息密度、品牌一致性、导出比例\n\n## 输入要求\n\n1. **页面/功能目标**（必填）：页面要解决什么用户问题或业务目标\n2. **目标用户**（必填）：使用者角色、设备场景、操作频率\n3. **内容素材**（可选）：文案、图片、品牌色、Logo、现有页面\n4. **技术栈**（可选）：HTML/CSS/JS、Vue、React、Taro、CMS模板等\n5. **设计约束**（可选）：品牌规范、兼容浏览器、SEO、性能、无障碍要求\n6. **设计资产类型**（可选）：页面、组件库、品牌规范、Banner、图标、社媒图、数据图表\n\n## 执行流程\n\n### 第一步：需求与场景分析\n\n- 明确页面核心目标和转化路径\n- 识别用户角色、设备、访问入口和关键任务\n- 明确交付类型：官网/后台/H5/表单/列表/详情/仪表盘/CMS模板/品牌规范/Banner/图标/社媒图\n- 标注不确定信息，必要时先向用户确认\n\n```\n✓ 前端场景分析:\n- 页面类型: [类型]\n- 设计资产: [页面/品牌/Banner/图标/社媒图]\n- 目标用户: [角色]\n- 核心任务: [任务]\n- 主要设备: [桌面/移动/自适应]\n```\n\n### 第二步：设计思维与 UX 策略\n\n- 使用双钻模型：发现问题 → 定义问题 → 构思方案 → 交付方案\n- 必要时输出用户画像、用户旅程、痛点、HMW 问题陈述\n- 营销页可使用 AIDA：注意 → 兴趣 → 欲望 → 行动\n- 数据页必须选择合适图表：柱状/折线/漏斗/热力/雷达/树图等，并说明理由\n- 明确首屏价值主张、主 CTA、用户三次点击内的目标路径\n\n### 第三步：信息架构与内容层级\n\n- 梳理页面区块：Header / Hero / 内容区 / CTA / Footer 等\n- 明确信息优先级：首屏必须传达什么，次级内容如何展开\n- 定义导航、面包屑、筛选、分页、标签等结构\n- 对 CMS 页面，明确模板变量和字段来源\n- 对 Banner/社媒图，明确主标题、副标题、CTA、Logo、背景、视觉焦点和安全区\n\n### 第四步：视觉风格、品牌与设计系统\n\n定义可落地的设计系统，而不是只描述“好看”：\n\n| 维度 | 产出 |\n| --------- | -------------------------------------------------- |\n| 设计风格 | 风格名称、适用场景、不适用场景、关键视觉特征 |\n| 色彩 | 主色、辅助色、背景色、状态色、文本色、暗色模式覆盖 |\n| 字体 | 字体配对、字号层级、行高、字重、标题/正文/注释 |\n| 间距 | 4/8px 栅格或项目现有 spacing token，组件/分区间距 |\n| 圆角/阴影 | 卡片、按钮、浮层、输入框规范 |\n| 图标/图片 | 图标风格、图片比例、alt、占位、压缩和导出策略 |\n| 组件 | Button/Input/Card/Table/Dialog/Toast 等 |\n| 品牌 | Logo 安全距离、最小尺寸、禁用规则、品牌语气 |\n\n设计系统必须采用三级 token 思路：\n\n```css\n/* 原始 Token */\n--color-blue-600: #2563eb;\n--space-4: 1rem;\n\n/* 语义 Token */\n--color-primary: var(--color-blue-600);\n--spacing-section: var(--space-12);\n\n/* 组件 Token */\n--button-bg: var(--color-primary);\n--card-padding: var(--space-6);\n```\n\n### 第五步：组件、交互状态与资产规格\n\n每个可交互元素必须覆盖状态：\n\n- 默认 / Hover / Focus / Active / Disabled\n- Loading / Empty / Error / Success\n- 表单校验错误、异步提交、防重复提交\n- 弹窗、抽屉、提示、确认二次操作\n- 后台管理必须考虑批量操作、筛选重置、分页保留\n- 长任务必须设计 AJAX 渐进式防卡死交互：Init 创建任务、Step 分批执行、Poll 轮询状态\n- Banner 必须定义尺寸、主视觉、主标题、副标题、CTA、Logo 和安全区\n- 图标必须定义尺寸、线宽、圆角、填充/描边、SVG title/aria 策略\n- 社媒图必须定义平台尺寸、文字安全区、导出格式和品牌一致性\n\n#### Init-Step-Poll 前端交互规范\n\n| 阶段 | 前端动作 | UI 状态 |\n| ------ | ------------------------------ | ------------------------------ |\n| Init | 提交参数，禁用按钮，创建任务 | `queued`，显示初始化中 |\n| Step | 循环请求或由 Poll 驱动分批执行 | `running`，显示进度条/当前批次 |\n| Poll | 轮询任务状态，不重复提交表单 | 显示百分比、失败数、日志摘要 |\n| Done | 停止轮询，展示结果和下一步操作 | `success`，允许下载/查看/刷新 |\n| Failed | 停止轮询，展示错误和重试入口 | `error`，允许重试/复制错误 |\n\n**交互约束**：\n\n- 轮询间隔建议 800-2000ms，页面隐藏时降频或暂停\n- 连续失败 3 次必须停止轮询并提示网络/服务异常\n- 用户离开页面前，如任务仍在运行，应提示任务可在后台继续或确认取消\n- 禁止用户重复点击造成重复任务；按钮必须有 disabled/loading 状态\n- 进度必须可感知：百分比、已处理/总数、当前步骤、失败数至少提供两项\n\n### 第六步：响应式与兼容性设计\n\n| 断点 | 设计重点 |\n| ------------ | ------------------------------------------------- |\n| `sm` 640px | 移动端单列布局、触控热区不小于 44px、底部操作优先 |\n| `md` 768px | 平板双列/折叠侧栏、表格横向滚动 |\n| `lg` 1024px | 桌面信息密度、快捷操作、固定筛选/侧栏 |\n| `xl` 1280px | 大屏内容宽度控制，避免行长过宽 |\n| `2xl` 1536px | 宽屏留白、网格扩展、数据看板布局 |\n\n兼容性要求：\n\n- 避免依赖实验性 CSS，除非明确允许\n- 表格、长文本、图片必须定义溢出策略\n- CMS 模板需兼容目标站点现有 CSS 作用域，避免全局污染\n\n### 第七步：可访问性与可用性检查\n\n- 颜色对比度至少达到 WCAG AA\n- 表单控件必须有 label 或 aria-label\n- 键盘可访问：Tab 顺序、Focus 样式、Esc 关闭浮层\n- 图片必须有 alt；装饰图可用空 alt\n- 动画必须可降级，避免强闪烁和过度动效\n- 交互反馈需在 100ms 内可感知，长任务必须有 Loading 或进度提示\n- 空状态不得为空，必须提供说明、引导或 CTA\n\n### 第八步：前端实现方案\n\n根据项目技术栈输出可执行实现方案：\n\n- HTML 语义结构\n- CSS 命名与作用域策略（BEM/CSS Modules/Scoped CSS/Tailwind/项目现有规范）\n- 组件拆分：页面组件、业务组件、基础组件\n- 状态管理：本地状态、URL查询参数、全局状态\n- 数据接口：字段映射、空值处理、错误提示\n- CMS模板：模板标签、字段转义、缓存清理、静态资源路径\n- 长任务交互：Init/Step/Poll 接口字段、轮询间隔、取消/重试策略\n- 组件库选择：按项目技术栈选择原生、Tailwind、shadcn/ui、Ant Design、Element Plus 等，并说明取舍\n- 品牌/Banner/图标/社媒图：输出 HTML/CSS/SVG 或设计参数，不把设计资产停留在文字描述\n\n### 第九步：浏览器验证\n\n前端交付必须有验证证据：\n\n| 验证项 | 方法 |\n| -------- | ------------------------------------------------- |\n| 视觉还原 | 浏览器截图或人工对照 |\n| 响应式 | 检查移动/平板/桌面断点 |\n| 交互状态 | 点击、输入、提交、错误、空状态 |\n| 控制台 | 无 JS error / 资源 404 |\n| 网络 | 核心接口状态码正确 |\n| 性能 | 首屏资源不过大，图片尺寸合理 |\n| A11y | 对比度、键盘导航、aria/label |\n| 设计资产 | 尺寸、导出格式、安全区、品牌一致性 |\n| 长任务 | Init/Step/Poll 状态流正确，轮询可停止、可失败提示 |\n\n### 第十步：记录到项目记忆\n\n前端设计完成后，将关键决策记录到项目记忆（参见 `project-memory-management.md`）：\n\n- 记录设计系统 token、字体配对、色板、组件约定和断点规范\n- 记录页面结构、交互模式、设计风格和可访问性要求\n- 记录品牌规范、Banner尺寸、图标风格、社媒图规格\n- 记录 CMS 模板变量、字段映射和静态资源路径约定\n\n## 输出格式\n\n````markdown\n## 前端设计方案\n\n### 1. 页面目标\n\n- **页面类型**: [官网/后台/H5/CMS模板]\n- **设计资产**: [页面/品牌/Banner/图标/社媒图]\n- **目标用户**: [用户角色]\n- **核心任务**: [一句话说明]\n\n### 2. UX策略\n\n- **设计模型**: [双钻/AIDA/用户旅程/其他]\n- **首屏价值主张**: [说明]\n- **主CTA**: [说明]\n\n### 3. 信息架构\n\n| 区块 | 内容 | 优先级 | 说明 |\n| -------- | ------ | -------- | ------ |\n| [区块名] | [内容] | P0/P1/P2 | [说明] |\n\n### 4. 视觉与品牌规范\n\n| 项目 | 值 | 用途 |\n| ------------- | ------------------- | ---------- |\n| 设计风格 | [风格] | [适用场景] |\n| Primary Color | [颜色/token] | [用途] |\n| 字体配对 | [标题/正文] | [用途] |\n| Logo规则 | [安全距离/最小尺寸] | [说明] |\n\n### 5. 组件与状态\n\n| 组件 | 状态 | 行为 |\n| ------ | ------------------------------ | ------ |\n| Button | default/hover/loading/disabled | [行为] |\n\n### 6. 设计资产规格\n\n| 资产 | 尺寸/格式 | 安全区 | 导出要求 |\n| ------ | --------- | ------ | -------- |\n| Banner | [尺寸] | [说明] | [格式] |\n| Icon | [尺寸] | [说明] | SVG/PNG |\n\n### 7. 响应式策略\n\n| 断点 | 布局 | 注意事项 |\n| ------ | ------ | -------- |\n| mobile | [布局] | [说明] |\n\n### 8. 实现说明\n\n```[语言/框架]\n[关键结构或组件代码]\n```\n\n### 9. 验证清单\n\n| 检查项 | 状态 | 证据 |\n| ---------- | ----------- | ----------- |\n| 响应式 | 通过/未通过 | [截图/步骤] |\n| 控制台错误 | 通过/未通过 | [结果] |\n| 可访问性 | 通过/未通过 | [结果] |\n````\n\n## 质量标准\n\n- 不得只给抽象审美描述，必须给出可执行的布局、组件、状态和 token\n- 必须说明设计风格、色彩、字体、间距、品牌和组件规则\n- 品牌/Banner/图标/社媒图请求必须输出尺寸、导出格式、安全区和验收标准\n- 关键交互必须覆盖 Loading/Empty/Error/Disabled 状态\n- 长任务必须采用 Init → Step → Poll，前端必须提供进度、错误、重试/取消和防重复提交\n- 移动端触控热区不得小于 44px\n- 表单必须包含校验规则和错误提示\n- 输出到页面的用户内容必须转义，CMS 模板必须避免 XSS\n- 图片必须有尺寸、比例、alt 和降级策略\n- 必须说明响应式断点和溢出处理\n- 前端交付必须包含浏览器验证方法或证据\n\n## 失败回退机制\n\n| 步骤 | 失败条件 | 回退目标 | 最大重试 | 不可恢复时升级路径 |\n| -------------------------------- | ------------------------ | ------------------------------------------ | -------- | -------------------------------------- |\n| 第一步：需求与场景分析 | 页面目标或用户角色不清 | 列出2-3种页面/资产类型假设，由用户选择 | 2 | 输出澄清问题清单，等待用户确认 |\n| 第二步：设计思维与 UX 策略 | 用户路径或转化目标不清 | 使用最小用户旅程和 AIDA 草案 | 1 | 输出 UX 假设清单 |\n| 第三步：信息架构与内容层级 | 内容素材不足 | 生成结构骨架并标注待补文案/图片 | 1 | 输出素材缺口清单 |\n| 第四步：视觉风格、品牌与设计系统 | 无品牌规范 | 使用中性设计系统，标注可替换 token | 1 | 要求用户提供品牌色/参考站 |\n| 第五步：组件、交互状态与资产规格 | 业务流程或资产规格不完整 | 覆盖通用状态和标准尺寸，复杂状态标注待确认 | 1 | 输出状态机/资产规格草案 |\n| 第六步：响应式与兼容性设计 | 目标设备不明确 | 默认移动优先 + 桌面增强 | 1 | 标注兼容范围假设 |\n| 第七步：可访问性与可用性检查 | 无法测量对比度或键盘行为 | 输出检查清单和手动验证步骤 | 1 | 标注未实测项 |\n| 第八步：前端实现方案 | 技术栈未知 | 输出 HTML/CSS 通用方案，避免框架特定代码 | 0 | 要求用户确认技术栈 |\n| 第九步：浏览器验证 | 无运行环境 | 输出本地验证步骤，标注未截图 | 1 | 等待用户提供运行地址或截图 |\n| 第十步：记录到项目记忆 | 项目记忆系统不可用 | 输出前端设计决策到本地文件 | 1 | 标注\"设计规范未沉淀\"，提示用户手动保存 |\n\n## 关联Skill\n\n- **代码生成** — 根据前端设计方案生成页面结构、样式和组件代码\n- **代码审查** — 审查前端实现的可访问性、性能、安全和状态覆盖\n- **测试用例生成** — 生成交互、表单、响应式和组件测试\n- **文档生成** — 将设计系统和组件规范整理为文档\n- **CMS二次开发** — CMS模板页面参考其模板变量、输出转义和缓存规范\n- **项目记忆管理** — 记录设计 token、组件约定和断点规范\n\n## 连接器（可选增强）\n\n| 连接器 | 增强能力 |\n| -------------- | --------------------------------------------- |\n| **Filesystem** | 读取现有前端结构、样式文件、组件库和 CMS 模板 |\n| **Git** | 读取 UI 变更历史，辅助判断设计规范演进 |\n| **Browser** | 执行页面交互、截图、控制台和网络请求验证 |\n\nFile v0.1.0:references/karpathy-coding-guidelines.md\n\n# Karpathy编码规范 -- Karpathy编码哲学\n\n基于Andrej Karpathy对LLM编码陷阱的观察，提供4条核心编码原则。\n\n## 输入要求\n\n1. **代码片段**（可选）：需要评估的代码\n2. **具体问题**（可选）：如\"这段代码是否过度设计\"\n3. **场景描述**（可选）：编码场景说明\n\n## 执行流程\n\n### 第一步：明确目标与假设\n\n- 识别用户真实目标和成功标准\n- 标注不确定信息，必要时向用户澄清\n- 列出关键假设，不把猜测隐藏在代码里\n\n### 第二步：应用四大原则\n\n- 用“编码前思考”检查需求歧义\n- 用“简洁优先”排除过度设计\n- 用“精准修改”限制变更范围\n- 用“目标驱动执行”定义验证闭环\n\n### 第三步：检查代码或方案\n\n- 对照四大原则逐项检查\n- 识别具体代码位置、改动点或设计风险\n- 区分必须修复和可选优化\n\n### 第四步：输出改进建议\n\n- 给出最小修改方案\n- 提供修改前后对比或明确执行步骤\n- 标注保留现状的理由和风险\n\n### 第五步：验证与沉淀\n\n- 验证建议是否满足原始目标\n- 将可复用的编码规范、陷阱和决策记录到项目记忆\n\n## 四大原则\n\n### 原则1：编码前思考（Think Before Coding）\n\n**不要假设。不要隐藏困惑。暴露权衡。**\n\n编码前必须：\n\n- 明确陈述假设——如果不确定，提问而不是猜测\n- 存在多种理解时，列出选项——不要默默选择\n- 存在更简单方案时，说出来——该推回时推回\n- 遇到不清楚的地方，停下来——说出困惑所在，提问\n\n**反模式**：\n\n- 用户说\"导出用户数据\"，直接写导出所有用户的代码（假设了范围、格式、字段）\n- 用户说\"让搜索更快\"，直接加缓存和索引（假设了\"更快\"的含义）\n\n**正确做法**：\n\n```\n导出用户数据前，我需要澄清：\n1. 范围：导出全部用户还是筛选后的子集？\n2. 格式：JSON/CSV/直接API返回？\n3. 字段：哪些字段？（有些可能涉及隐私）\n```\n\n### 原则2：简洁优先（Simplicity First）\n\n**最少代码解决问题。不要 speculative。**\n\n- 不要超出需求的功能\n- 不要为单次使用代码做抽象\n- 不要未被要求的\"灵活性\"或\"可配置性\"\n- 不要为不可能场景做错误处理\n- 写了200行但50行能搞定，重写\n\n**自检问题**：\"资深工程师会说这过度复杂吗？\"如果是，简化。\n\n**反模式**：\n\n- 用户说\"计算折扣\"，生成Strategy模式+抽象类+配置对象（30行设置做简单计算）\n- 用户说\"保存用户偏好\"，加缓存、验证、合并、通知（没人要求的功能）\n\n**正确做法**：\n\n```python\n# 简单直接\ndef calculate_discount(amount: float, percent: float) -> float:\n return amount * (percent / 100)\n```\n\n### 原则3：精准修改（Surgical Changes）\n\n**只碰必须碰的。只清理自己制造的。**\n\n编辑现有代码时：\n\n- 不要\"改进\"相邻代码、注释或格式\n- 不要重构没坏的东西\n- 匹配现有风格，即使你自己会不同做法\n- 发现无关死代码，提一下——但不要删\n\n你的修改制造孤儿时：\n\n- 删除**你的修改**导致的未使用import/变量/函数\n- 不要删除预先存在的死代码，除非被要求\n\n**测试标准**：每一行修改都能追溯到用户的请求。\n\n**反模式**：\n\n- 修复空邮箱Bug时，顺便\"改进\"邮箱验证、加用户名验证、改注释、加docstring\n- 添加上传日志时，改引号风格、加类型提示、重排空白\n\n**正确做法**：\n\n```diff\n- if not user_data.get('email'):\n+ email = user_data.get('email', '')\n+ if not email or not email.strip():\n raise ValueError(\"Email required\")\n```\n\n### 原则4：目标驱动执行（Goal-Driven Execution）\n\n**定义成功标准。循环直到验证。**\n\n把指令式任务转化为可验证目标：\n\n- \"加验证\" → \"写无效输入的测试，然后让它们通过\"\n- \"修Bug\" → \"写复现Bug的测试，然后让它通过\"\n- \"重构X\" → \"确保重构前后测试都通过\"\n\n多步骤任务时，陈述简要计划：\n\n```\n1. [步骤] → 验证：[检查]\n2. [步骤] → 验证：[检查]\n3. [步骤] → 验证：[检查]\n```\n\n强成功标准让你独立循环。弱标准（\"让它工作\"）需要持续澄清。\n\n## 失败回退机制\n\n### 原则4 回退机制\n\n| 步骤 | 失败条件 | 回退目标 | 最大重试 | 不可恢复时升级路径 |\n| ------------ | ------------------------------------------ | ------------------------------------------- | ---------------- | ------------------------------------------------- |\n| 定义成功标准 | 用户给出的目标过于模糊（\"让它工作\"类） | 拆分目标为可验证的具体子项 | 2 | 输出\"目标拆解建议\"，由用户确认后继续 |\n| 编写验证测试 | 测试环境/依赖不可用 | 用最小化方式验证核心逻辑（如直接调用+断言） | 2 | 标注\"测试环境缺失\"，输出手动验证步骤 |\n| 实现功能 | 实现中遇到不可预见的依赖缺失或API变更 | 标注阻塞点，绕过或降级实现 | 3 | 输出部分实现+阻塞点清单，建议分阶段交付 |\n| 运行验证 | 验证失败但根因不在当前代码（外部系统问题） | 标注\"外部依赖导致\"，记录复现条件 | 1 | 输出\"已验证逻辑正确，外部依赖异常需单独排查\" |\n| 循环迭代 | 连续3轮修改仍未通过验证 | 暂停循环，输出当前状态和差异分析 | 0（循环上限3轮） | 输出\"达到最大迭代次数\"，产出当前最佳版本+差异报告 |\n\n### 原则1-3 回退机制\n\n| 原则 | 失败条件 | 回退目标 | 最大重试 | 不可恢复时升级路径 |\n| ---------------------------------- | -------------------------------- | -------------------------------------- | -------- | --------------------------------------- |\n| 原则1：编码前思考 — 陈述假设 | 用户无法澄清歧义 | 列出2-3种最可能的理解，标注\"假设\" | 2 | 输出\"假设清单\"，要求用户逐一确认 |\n| 原则1：编码前思考 — 列出选项 | 选项过多导致决策瘫痪 | 收敛到Top 2选项，附trade-off | 1 | 输出选项对比矩阵，由用户决策 |\n| 原则1：编码前思考 — 推回更简方案 | 用户坚持复杂方案 | 接受用户决策，标注\"已提示简化\" | 1 | 记录到项目记忆，后续审查时复盘 |\n| 原则2：简洁优先 — 排除超出需求功能 | 需求边界模糊，难以判断\"超出\" | 保守保留核心功能，标注\"待确认\" | 1 | 输出功能清单，要求用户勾选必需项 |\n| 原则2：简洁优先 — 避免单次使用抽象 | 已存在的抽象难以判断是否单次使用 | 保留抽象，标注\"使用频率待统计\" | 1 | 建议后续走 重构建议 评估 |\n| 原则2：简洁优先 — 简化实现 | 200行代码难以压缩到50行 | 分函数评估，逐个简化 | 2 | 输出简化建议清单，建议人工重构 |\n| 原则3：精准修改 — 仅修改必要代码 | 修复涉及多文件联动 | 限定最小变更集，标注\"未优化相邻代码\" | 1 | 输出变更影响图，建议分批修改 |\n| 原则3：精准修改 — 保持原有风格 | 原有风格不规范 | 遵循原有风格，标注\"风格问题待后续治理\" | 0 | 记录风格问题到项目记忆，单独走 重构建议 |\n| 原则3：精准修改 — 清理孤儿代码 | 孤儿代码判断不确定 | 保留待删代码，标注\"疑似孤儿\" | 1 | 建议走 代码审查 确认后再删 |\n\n## 输出格式\n\n```\n## Karpathy编码规范评估\n\n**评估代码**：[文件名/片段]\n\n### 原则1：编码前思考\n- [ ] 假设是否明确陈述？\n- [ ] 是否存在未澄清的歧义？\n- [ ] 是否遗漏了更简单的方案？\n\n**评估**：[通过/需改进]\n**问题**：[具体问题]\n**建议**：[改进建议]\n\n### 原则2：简洁优先\n- [ ] 是否包含超出需求的功能？\n- [ ] 是否存在单次使用的抽象？\n- [ ] 是否可以更短更简单？\n\n**评估**：[通过/需改进]\n**问题**：[具体问题]\n**建议**：[简化方案]\n\n### 原则3：精准修改\n- [ ] 是否只修改了必要的代码？\n- [ ] 是否保持了原有风格？\n- [ ] 是否清理了自己的孤儿代码？\n\n**评估**：[通过/需改进]\n**问题**：[具体问题]\n**建议**：[改进建议]\n\n### 原则4：目标驱动执行\n- [ ] 是否有明确的验证标准？\n- [ ] 是否可以独立验证每一步？\n\n**评估**：[通过/需改进]\n**问题**：[具体问题]\n**建议**：[改进建议]\n\n## 总体评估\n\n**符合度**：[X]/100\n**主要问题**：[Top 1-2问题]\n**优先修复**：[具体建议]\n```\n\n## 质量标准\n\n- 评估必须基于代码实际内容，不能泛泛而谈\n- 每个原则的评估必须有具体的代码位置引用\n- 改进建议必须提供具体的修改前后对比\n- 不得为符合规范的代码强行找问题\n- 评估应平衡：不是追求绝对完美，而是避免常见陷阱\n\n## 关联Skill\n\n- **代码审查** — 用 `代码审查` 进行全面的技术审查（Bug/安全/性能）\n- **代码生成** — 用 `代码生成` 生成功能代码，再用本Skill评估是否符合规范\n- **重构建议** — 用 `重构建议` 获取结构优化方案，再用本Skill检查是否过度设计\n\n## 连接器（可选增强）\n\n| 连接器 | 增强能力 |\n| -------------- | ------------------------------------------ |\n| **Filesystem** | 读取项目代码进行Karpathy编码哲学符合性检查 |\n| **Git** | 读取提交历史，评估代码简洁性趋势 |\n| **Notion** | 将编码规范审查结果写入 Notion 知识库 |\n\nFile v0.1.0:references/mysql-database.md\n\n# MySQL数据库 -- 数据建模、SQL安全与性能优化\n\n面向 PHP/CMS/网站项目中的 MySQL 数据库设计、SQL 编写、索引优化、慢查询诊断、迁移回滚和数据安全场景。目标是在写代码前先明确表结构、访问路径、事务边界和验证方法，避免后期靠补丁修数据库问题。\n\n## 输入要求\n\n### 必填信息\n\n1. **业务场景**：要存储/查询/统计/更新什么数据\n2. **操作类型**：建表 / 改表 / 查询 / 写入 / 统计 / 慢查询优化 / 数据迁移\n3. **数据规模**：当前行数、预计增长、单次处理量、读写比例\n4. **数据库版本**：MySQL 5.7 / 8.0 / MariaDB，未知则标注假设\n5. **调用环境**：PHP 原生 / CMS 数据访问层 / Laravel / ThinkPHP / WordPress / EmpireCMS\n\n### 可选信息\n\n- 现有表结构：`SHOW CREATE TABLE`\n- 现有 SQL 和参数\n- `EXPLAIN` / `EXPLAIN ANALYZE` 结果\n- 慢查询日志片段\n- 线上约束：是否允许停机、是否大表、是否可加索引\n- 事务/一致性要求\n\n## 执行流程\n\n### 第一步：识别数据库任务类型\n\n先判断当前任务属于哪一类：\n\n| 类型 | 触发关键词 | 优先动作 |\n|------|------------|----------|\n| 表结构设计 | 建表、字段、模型、Schema | 输出 DDL + 字段说明 + 索引 |\n| SQL 编写 | 查询、筛选、分页、统计 | 输出参数化 SQL + 绑定参数 |\n| 慢查询优化 | 慢、卡、超时、EXPLAIN | 先读执行计划，再改 SQL/索引 |\n| 数据迁移 | ALTER、迁移、导入、修数据 | 输出备份、分批、回滚方案 |\n| CMS 数据库 | 表前缀、模型表、副表、options | 调用 CMS二次开发规范 |\n\n### 第二步：确认版本、字符集和会话设置\n\n默认推荐：\n\n```sql\nSET NAMES utf8mb4;\nSET time_zone = '+08:00';\nSET SESSION sql_mode = 'STRICT_TRANS_TABLES,NO_ENGINE_SUBSTITUTION';\n```\n\n建库建表必须优先使用 `utf8mb4`，排序规则优先 `utf8mb4_unicode_ci` 或项目现有规则。\n\n### 第三步：表结构设计\n\n#### 基础规范\n\n| 项 | 规则 |\n|----|------|\n| 引擎 | 默认 InnoDB；只有明确 CMS 历史约束时保留 MyISAM |\n| 主键 | `BIGINT UNSIGNED AUTO_INCREMENT` |\n| 字符集 | 表和字段统一 `utf8mb4` |\n| 时间字段 | `created_at` / `updated_at` 使用 `DATETIME(3)` |\n| 软删除 | 需要恢复/审计时加 `deleted_at` 并建索引 |\n| 金额 | 使用 `DECIMAL`，PHP 侧按 string 处理 |\n| JSON | MySQL 5.7+ 可用 JSON；旧版本用 TEXT + JSON 校验 |\n\n#### 字段类型选择\n\n| 场景 | 类型 |\n|------|------|\n| 主键/外键 | `BIGINT UNSIGNED` |\n| 状态/枚举 | `TINYINT UNSIGNED` |\n| 金额 | `DECIMAL(12,2)` 或按业务精度调整 |\n| 短文本 | `VARCHAR(N)` |\n| 长文本 | `TEXT` / `MEDIUMTEXT` |\n| 布尔 | `TINYINT(1)` |\n| 固定散列 | `CHAR(32)` / `CHAR(64)` |\n\n### 第四步：索引设计\n\n必须先根据查询路径设计索引，禁止“看起来可能会用”就加索引。\n\n#### 索引策略决策树\n\n1. **先列查询路径**：WHERE、JOIN、ORDER BY、GROUP BY、分页、唯一约束分别列出。\n2. **再看数据分布**：字段基数、重复率、NULL 比例、冷热数据范围。\n3. **再定索引类型**：主键、唯一索引、普通索引、联合索引、前缀索引、全文索引。\n4. **最后用 EXPLAIN 验证**：确认 `key`、`type`、`rows`、`Extra` 是否符合预期。\n\n#### 基础规则\n\n| 规则 | 要求 |\n|------|------|\n| 命名 | 普通索引 `idx_表名_字段`，唯一索引 `uk_表名_字段` |\n| 联合索引 | 遵循最左前缀，等值字段在前，范围/排序字段靠后 |\n| 数量 | 普通业务表不超过 5 个，大表不超过 8 个 |\n| VARCHAR 前缀 | utf8mb4 下索引长度注意 191 字符限制 |\n| 禁止 | 低区分度字段单独建索引、频繁更新字段滥建索引 |\n\n#### 联合索引字段顺序\n\n推荐顺序：\n\n```text\n等值过滤字段 → 高区分度字段 → 范围字段 → 排序字段 → 覆盖返回字段\n```\n\n示例：\n\n```sql\nWHERE tenant_id = ?\n AND status = ?\n AND created_at >= ?\nORDER BY created_at DESC\nLIMIT 20\n```\n\n推荐索引：\n\n```sql\nKEY idx_orders_tenant_status_created (tenant_id, status, created_at)\n```\n\n注意：\n\n- 范围字段后面的字段通常不能继续用于高效过滤。\n- `ORDER BY` 方向要和索引顺序兼容；MySQL 8.0 支持降序索引。\n- 多租户表优先把 `tenant_id` 放在联合索引左侧。\n\n#### 查询场景策略\n\n| 场景 | 索引策略 | 禁忌 |\n|------|----------|------|\n| 精确查询 | 唯一键或高区分度普通索引 | 给低区分度状态字段单独建索引 |\n| 列表分页 | 过滤字段 + 排序字段联合索引 | 大 offset 深分页 |\n| 深分页 | 使用游标/last_id 翻页 | `LIMIT 100000,20` |\n| JOIN | 关联字段两侧类型一致，子表关联字段建索引 | 字段类型/字符集不一致 |\n| ORDER BY | 让排序字段进入联合索引 | 依赖 filesort 处理大结果集 |\n| GROUP BY | 分组字段建索引或先缩小数据集 | 全表分组统计 |\n| LIKE 前缀 | `LIKE 'abc%'` 可用索引 | `LIKE '%abc%'` 期待普通索引命中 |\n| 全文搜索 | FULLTEXT 或搜索引擎 | 在大 TEXT 上滥用 LIKE |\n| 唯一约束 | 用唯一索引保障业务唯一性 | 只在代码层判断唯一 |\n\n#### 覆盖索引策略\n\n高频列表页可用覆盖索引减少回表：\n\n```sql\nKEY idx_article_cat_status_time_id (cat_id, status, publish_time, id)\n```\n\n适用：\n\n- 列表页只返回少量字段。\n- 查询频率高、返回行数少。\n- 回表成本明显。\n\n限制：\n\n- 不要为了覆盖索引把大字段、TEXT、长 VARCHAR 塞进索引。\n- 覆盖索引增加写入成本，必须说明收益。\n\n#### 冗余索引治理\n\n必须检查已有索引，避免重复：\n\n| 已有索引 | 新索引 | 判断 |\n|----------|--------|------|\n| `(a,b)` | `(a)` | 通常冗余 |\n| `(a,b)` | `(a,b,c)` | 可能可合并，需看查询 |\n| `(a)` | `(b,a)` | 不等价 |\n| `uk_email(email)` | `idx_email(email)` | 冗余 |\n\n删除索引前必须：\n\n1. 列出依赖 SQL。\n2. 确认没有唯一约束语义。\n3. 在测试环境用 EXPLAIN 对比。\n4. 说明回滚 SQL。\n\n#### 写入成本评估\n\n新增索引不是免费优化，必须评估：\n\n- INSERT/UPDATE/DELETE 是否变慢。\n- 索引是否会放大磁盘占用。\n- 频繁更新字段是否导致页分裂。\n- 大表加索引是否需要在线 DDL。\n\n#### CMS 常见索引策略\n\n| CMS 场景 | 推荐策略 |\n|----------|----------|\n| 栏目内容列表 | `classid/status/newstime` 或项目等效字段联合索引 |\n| 后台搜索 | 关键词字段不做 `%kw%` 普通索引幻想，改全文索引或搜索服务 |\n| 订单/表单列表 | `site_id/status/created_at` 联合索引 |\n| 软删除 | `deleted_at` 进入常用查询联合索引 |\n| 多站点/多租户 | `site_id` / `tenant_id` 放联合索引左侧 |\n\n#### EXPLAIN 验收标准\n\n| 字段 | 目标 |\n|------|------|\n| `type` | 至少达到 `range`，高频点查应为 `ref` / `const` |\n| `key` | 命中预期索引 |\n| `rows` | 扫描行数与业务结果数量同量级 |\n| `Extra` | 高频查询避免大规模 `Using temporary` / `Using filesort` |\n\n如果不能满足，必须说明原因和替代方案。\n\n### 第五步：SQL安全与参数绑定\n\n所有外部输入必须参数绑定，内部接口也不例外。\n\n| 场景 | 禁止 | 强制 |\n|------|------|------|\n| WHERE | `\"id=$id\"` | `WHERE id = ?` |\n| LIKE | `LIKE \"%$kw%\"` | `LIKE CONCAT('%', ?, '%')` |\n| IN | 手动拼 `IN(1,2,3)` | 动态占位符 `IN(?,?,?)` |\n| ORDER BY | 直接拼用户输入 | 白名单字段映射 |\n| LIMIT | 直接拼字符串 | 转 int 后限制最大值 |\n\n### 第六步：事务、锁和批处理\n\n- 多表写入必须显式事务：`begin → write → commit`，异常必须 rollback\n- 单事务影响行数超过 10000 时必须分批\n- 批量导入/导出/修复数据必须使用 `Init → Step → Poll` 渐进式防卡死架构\n- 高并发扣减库存/余额类场景必须说明锁策略：行锁、乐观锁或唯一约束\n- 禁止无 WHERE 的 UPDATE / DELETE\n\n### 第七步：慢查询诊断\n\n慢查询必须先拿证据：\n\n1. 原始 SQL\n2. 参数样例\n3. 表行数\n4. `EXPLAIN` 结果\n5. 相关索引\n\n诊断重点：\n\n| EXPLAIN 字段 | 风险信号 |\n|--------------|----------|\n| type | `ALL` / `index` 需警惕 |\n| rows | 扫描行数远大于返回行数 |\n| key | 未命中预期索引 |\n| Extra | `Using filesort` / `Using temporary` |\n\n优化顺序：改查询条件 → 调整索引 → 改分页/统计方式 → 拆表/缓存。不得先上缓存掩盖 SQL 问题。\n\n### 第八步：迁移、备份与回滚\n\nDDL/数据修复必须输出：\n\n- 执行前 SELECT 验证\n- 备份方案\n- 执行 SQL\n- 影响行数预估\n- 回滚 SQL 或恢复方案\n- 执行窗口和风险提示\n\n大表 ALTER 必须提示使用在线 DDL 或 `pt-online-schema-change`，禁止业务高峰直接执行。\n\n### 第九步：记录到项目记忆\n\n将以下内容沉淀：\n\n- 表结构和字段约定\n- 索引设计理由\n- 关键 SQL 和参数绑定方式\n- 事务边界和回滚策略\n- 慢查询诊断结论\n- CMS 表前缀和特殊表规则\n\n## 输出格式\n\n```markdown\n# MySQL数据库方案\n\n## 1. 场景判断\n- 类型: [建表/查询/优化/迁移/修复]\n- 数据规模: [当前/预估]\n- MySQL版本: [版本或假设]\n\n## 2. 表结构/SQL方案\n[DDL 或参数化 SQL]\n\n## 3. 索引设计\n| 查询路径 | 推荐索引 | 字段顺序理由 | 覆盖查询 | 写入成本 |\n|----------|----------|--------------|----------|----------|\n\n## 3.1 索引治理\n- 冗余索引:\n- 删除/合并建议:\n- 回滚SQL:\n\n## 4. 安全与事务\n- 参数绑定:\n- 事务边界:\n- 锁策略:\n\n## 5. 性能验证\n- EXPLAIN:\n- 预期扫描行数:\n- 风险:\n\n## 6. 迁移/回滚\n- 备份:\n- 执行:\n- 回滚:\n\n## 7. 验证证据\n- 测试SQL:\n- 预期结果:\n- 影响行数:\n```\n\n## 质量标准\n\n- 任何 SQL 涉及外部输入时必须参数绑定\n- 任何 UPDATE / DELETE 必须带 WHERE，并说明执行前 SELECT\n- 建表必须说明字符集、引擎、主键、时间字段、必要索引\n- 索引必须对应具体查询路径，不能无理由添加\n- 联合索引必须说明字段顺序理由：等值、区分度、范围、排序、覆盖\n- 高频查询必须提供 EXPLAIN 验证，说明 `key/type/rows/Extra`\n- 新增索引必须评估写入成本、磁盘成本和冗余索引\n- 删除/合并索引必须提供依赖 SQL、风险和回滚 SQL\n- 金额字段禁止 float\n- 慢查询必须基于 `EXPLAIN` 或明确说明缺少执行计划\n- DDL/数据修复必须有备份和回滚说明\n- 大批量任务必须采用 Init → Step → Poll\n- CMS 场景必须说明表前缀和官方数据访问层\n\n## 失败回退机制\n\n| 步骤 | 失败场景 | 回退策略 | 重试次数 | 最终处理 |\n|------|----------|----------|----------|----------|\n| 第一步：识别数据库任务类型 | 需求不清 | 按建表/查询/优化/迁移四类询问用户 | 1 | 输出假设并标注待确认 |\n| 第二步：确认版本、字符集和会话设置 | MySQL版本未知 | 默认 MySQL 8.0，兼容 5.7 写法 | 1 | 标注版本假设 |\n| 第三步：表结构设计 | 字段含义不足 | 输出最小字段集并列待确认字段 | 1 | 不生成破坏性 DDL |\n| 第四步：索引设计 | 缺查询路径 | 只给必要主键/唯一索引 | 1 | 提示补充查询条件 |\n| 第五步：SQL安全与参数绑定 | 框架访问层未知 | 使用 PDO 预处理示例 | 1 | 标注需替换为项目 ORM/CMS API |\n| 第六步：事务、锁和批处理 | 一致性要求未知 | 按保守事务方案设计 | 1 | 标注并发风险 |\n| 第七步：慢查询诊断 | 缺 EXPLAIN | 先输出需采集命令和初步假设 | 1 | 不宣称已完成优化 |\n| 第八步：迁移、备份与回滚 | 无备份条件 | 阻止破坏性操作 | 0 | 要求先备份 |\n| 第九步：记录到项目记忆 | 项目记忆不可用 | 输出本地记录清单 | 1 | 标注未沉淀 |\n\n## 关联Skill\n\n- **CMS二次开发** - PHP+MySQL CMS 场景必须联动 CMS 表前缀、官方数据访问层和缓存规则\n- **代码生成** - 生成 PHP/后端代码时按本技能的 SQL 安全、事务和类型映射执行\n- **代码审查** - 审查 SQL 注入、慢查询、事务边界、DDL 风险和索引滥用\n- **Bug诊断** - 数据库报错、死锁、慢查询、表不存在、字符集问题优先调用本技能\n- **技术选型** - 数据库版本、存储引擎、缓存和搜索方案选型\n- **网站项目总控** - 建站项目中的数据模型、内容表、表单提交、统计和上线迁移\n- **任务拆解与执行** - 大型数据库变更按 Wave 拆分并逐步验证\n- **项目记忆管理** - 沉淀表结构、索引、SQL 约定和迁移记录","readmeExcerpt":"Skill: dev-expert Owner: ebandao777-oss Summary: 编程专家综合技能套件，含17个子技能：软件项目总控、网站项目总控、API设计、Bug诊断、代码生成、代码审查、重构建议、测试用例生成、技术选型、文档生成、任务拆解与执行、Spec驱动开发、Karpathy编码规范、项目记忆管理、CMS二次开发、前端设计、MySQL数据库。按用户输入关键词路由到对应子技能模板执行。 关键词路由：软件项目总控(软件项目/API服务/后端服务/后台模块/CLI工具/数据脚本/自动化任务/插件项目/完整功能/项目交付/部署/发布/上线/回滚/运维/监控/告警/巡检)；网站项目总控(做网站/建站/企业官网/营销页/CMS网站/网站上线/网站交付)；API设计(RESTful/GraphQL/接口规范/AJAX防卡死/Init-Step-Poll/长任务接口/轮询接口)；Bug诊断(debug/异常堆栈/报错)","codeSnippets":[],"executableExamples":[{"language":"markdown","snippet":"## 任务交付说明\n\n### 1. 子技能与路由\n\n- **匹配子技能**：（名称）\n- **路由依据**：（用户输入关键词/场景匹配）\n\n### 2. 执行摘要\n\n- **输入信息**：（用户提供的核心输入/技术约束）\n- **执行过程**：（关键步骤简述）\n- **产出清单**：（交付物列表，含文件路径）\n\n### 3. 变更说明\n\n| 改动点 | 涉及文件 | 变更摘要 | 已知限制 |\n| ------ | -------- | -------- | -------- |\n\n### 4. 验证结论\n\n- **构建状态**：通过/失败\n- **测试结果**：\n | 检查项 | 状态 | 备注 |\n |--------|:----:|------|\n | （逐条列出） | 通过/未通过 | （说明） |\n\n### 5. 风险与建议\n\n- **已知限制**：\n- **技术债记录**：\n- **后续建议**：\n\n### 6. 复盘记录\n\n- **本次经验**：（可复用的Bug模式/架构决策/需注意的陷阱）"},{"language":"markdown","snippet":"## 项目启动信息\n\n- **项目名称**：\n- **初始需求**：（用户原始需求描述）\n- **技术栈**：\n- **是否存在终极功能**：是 / 否\n- **终极功能定义**：（如有，可验证的一句话描述）\n- **技术约束**：（性能要求/兼容性/安全约束等）\n- **默认循环轮次**：3\n- **安全最大轮次**：6\n- **每轮最大改动点数**：3\n- **角色配置**：主控 + 架构师 + 程序员 + 测试员"},{"language":"text","snippet":"✓ Spec场景检查: [检测到/未检测到] 需求规格\n[如检测到，列出 Requirement → 端点 映射]"},{"language":"markdown","snippet":"## API Spec: [API名称]\n\n### ADDED Requirements\n\n#### Requirement: [端点名称]\n\nThe system SHALL provide an endpoint to [功能描述].\n\n##### Scenario: 成功请求\n\n- GIVEN [前置条件]\n- WHEN 发送 `[METHOD] [路径]` 请求\n- THEN 返回 [状态码] 和 [响应体]\n\n##### Scenario: 错误处理\n\n- GIVEN [错误前置条件]\n- WHEN 发送 `[METHOD] [路径]` 请求\n- THEN 返回 [错误状态码] 和 [错误响应体]\n\n### Design\n\n- **URL结构**: [结构说明]\n- **认证方式**: [认证机制]\n- **版本策略**: [版本管理]\n\n### File Changes\n\n- `[API定义文件]` (new/modified)"},{"language":"text","snippet":"## API设计文档\n\n### 资源定义\n\n| 资源 | 说明 | 核心字段 |\n| -------- | ------ | ---------- |\n| [资源名] | [说明] | [字段列表] |\n\n### 接口列表\n\n#### [接口名称]\n\n**URL**：`[METHOD] /path`\n**说明**：[功能说明]\n\n**请求参数**：\n| 字段 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| [字段] | [类型] | [是/否] | [说明] |\n\n**响应格式**："},{"language":"text","snippet":"**错误码**：\n| 错误码 | 说明 |\n|--------|------|\n| [CODE] | [说明] |\n\n### 通用规范\n\n- **认证方式**：[Bearer Token / API Key / OAuth2]\n- **版本控制**：[URL路径 / Header / 参数]\n- **分页方式**：[页码分页 / 游标分页]\n- **数据格式**：[snake_case / camelCase]\n\n### 长任务接口规范（如适用）\n\n| 端点 | 方法 | 说明 |\n|------|------|------|\n| `/tasks/{type}/init` | POST | 创建任务，返回 `task_id`、`total`、初始状态 |\n| `/tasks/{task_id}/step` | POST | 执行一批处理，返回进度和 `has_more` |\n| `/tasks/{task_id}/poll` | GET | 查询任务状态、进度、错误和结果 |\n\n**Step 响应必须包含**：`task_id`, `status`, `processed`, `total`, `percent`, `has_more`, `message`, `errors`"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: dev-expert\ndescription: |\n 编程专家综合技能套件，含17个子技能：软件项目总控、网站项目总控、API设计、Bug诊断、代码生成、代码审查、重构建议、测试用例生成、技术选型、文档生成、任务拆解与执行、Spec驱动开发、Karpathy编码规范、项目记忆管理、CMS二次开发、前端设计、MySQL数据库。按用户输入关键词路由到对应子技能模板执行。\n 关键词路由：软件项目总控(软件项目/API服务/后端服务/后台模块/CLI工具/数据脚本/自动化任务/插件项目/完整功能/项目交付/部署/发布/上线/回滚/运维/监控/告警/巡检)；网站项目总控(做网站/建站/企业官网/营销页/CMS网站/网站上线/网站交付)；API设计(RESTful/GraphQL/接口规范/AJAX防卡死/Init-Step-Poll/长任务接口/轮询接口)；Bug诊断(debug/异常堆栈/报错)；代码生成(写代码/实现功能)；代码审查(code review/安全漏洞/代码缺陷)；重构建议(重构/坏味道/代码异味/可维护性)；测试用例生成(单元测试/集成测试/安全测试/性能测试/长任务测试)；技术选型(技术栈/框架选型)；文档生成(API文档/README/技术文档/部署说明/回滚说明/运维文档)；任务拆解与执行(任务分解/Wave执行)；Spec驱动开发(spec/需求对齐/需求规格)；Karpathy编码规范(Karpathy/编码哲学/简洁优先)；项目记忆管理(项目记忆/跨会话/上下文沉淀)；CMS二次开发(CMS/帝国CMS/WordPress/ThinkPHP/PHP8兼容/二次开发/插件开发/模板开发/批量任务/导入导出/生成静态页)；前端设计(UI设计/UX/交互设计/响应式/设计系统/可访问性/页面视觉/浏览器验证/品牌设计/Banner/图标/社媒图/进度条/轮询状态)；MySQL数据库(MySQL/数据库设计/SQL/索引/事务/慢查询/EXPLAIN/DDL/迁移/表结构/SQL优化)。\nversion: \"1.5.1\"\nauthor: \"智慧半岛\"\n---\n\n# dev-expert -- 编程专家综合技能\n\n本技能是一个综合技能套件，包含多个子技能。接到用户请求后，按以下流程执行。\n\n## 执行流程\n\n### Step 1: 意图识别与路由匹配\n\n分析用户输入，与下方路由表逐一比对。匹配规则：\n\n- 用户输入中包含路由表中「子技能」列的关键词 → 匹配该子技能\n- 用户输入中包含路由表中「功能说明」列中提到的场景 → 匹配该子技能\n- 多个子技能同时匹配时，先按「子技能优先级矩阵」组合路由；无法组合时再选择匹配度最高的\n- 无法唯一确定时，向用户确认意图\n\n### Step 2: 加载子技能模板\n\n匹配到子技能后，根据子技能索引表找到对应的文件路径，**必须**使用 `Read` 工具读取 `references/` 目录下的完整执行模板。\n\n### Step 3: 按模板执行\n\n严格按照加载的模板逐步执行。模板中定义了：\n\n- 输入要求（用户需要提供什么）\n- 执行步骤（每一步做什么、如何判断）\n- 输出格式（最终产出的结构和规范）\n- 质量标准（产出必须满足的底线）\n\n### Step 4: 输出结果\n\n按模板规定的格式输出结果。如果模板要求生成文件，写入后声明产出物。\n\n## 约束规则\n\n1. **必须先读模板再执行**：匹配到子技能后，严禁凭记忆或猜测执行，必须先读取对应的 references 文件\n2. **严格遵循模板**：不得跳过步骤、不得省略检查项、不得自行简化流程\n3. **输入不足时主动索取**：模板中标注「必填」的输入项缺失时，向用户索取\n4. **质量底线不妥协**：模板中的质量标准必须逐条满足\n\n## 本包特色\n\n- **软件项目总控**：面向 API 服务、后台模块、插件、CLI 工具、数据脚本和自动化任务等非网站项目，先定义项目边界、行为契约、架构、数据/API/集成、发布回滚、监控告警、巡检运维和交付沉淀，再进入 Wave 执行\n- **网站项目总控**：面向做网站/建站/CMS网站/企业官网/营销页等完整项目，先定义项目启动、站点规划、内容SEO、前端设计、CMS/API/数据、任务Wave、测试安全、性能部署、验收交接和运维沉淀，再调用任务拆解与执行落地\n- **CMS二次开发**：PHP+MySQL CMS 二次开发子技能提供 CMS 自动探测、PHP 版本选型矩阵、数据库操作规范、PHP 8.x 兼容性检查、安全红线、插件开发标准，与代码生成/Bug诊断/代码审查/技术选型深度联动\n- **前端设计**：融合 UI/UX Pro Max 规则，覆盖设计思维、信息架构、视觉 token、字体配对、品牌规范、Banner、图标、社媒图、组件状态、响应式、可访问性、CMS模板页面和浏览器验证\n- **MySQL数据库**：独立覆盖表结构设计、SQL安全、索引、事务、慢查询、迁移回滚和 PHP/CMS 数据访问约束\n- **AJAX 渐进式防卡死**：长任务强制采用 Init → Step → Poll 架构，覆盖 CMS 批处理、导入导出、静态生成、采集同步、前端进度轮询和 API 契约\n\n- **Karpathy编码哲学**：所有代码产出遵循'先思考、简洁优先、避免浪费、手工胜于模板'原则，代码生成前必须先完成逻辑推演\n- **Wave执行模式**：任务拆解与执行子技能按依赖分Wave串行执行，每Wave完成后验证再进入下一Wave，上下文隔离避免污染\n- **Spec驱动开发**：Spec驱动开发子技能在编码前强制对齐需求规格，用artifact flow分离提案/实施/验证三阶段\n\n## 路由表\n\n| 子技能 | 功能说明 |\n| ---------------- | -------------------------------------------------------------------------------------------------------------- |\n| 软件项目总控 | 通用软件项目从需求到交付的总控：边界、行为契约、架构、数据/API/集成、测试、安全、发布、回滚和沉淀。 |\n| 网站项目总控 | 从需求到上线的建站项目总控：站点规划、内容SEO、前端设计、CMS/API/数据、测试安全、性能部署、验收运维。 |\n| API设计 | 根据业务需求设计RESTful或GraphQL API接口... |\n| Bug诊断 |"},{"path":"README.md","content":"# 编程专家 - dev-expert\n\n面向软件工程师和开发团队的编程全生命周期助手。覆盖从软件项目总控、网站项目总控、需求分析、前端设计、MySQL数据库、代码生成、Bug诊断到重构、测试、文档、上线交付和运维监控的全链路，通过17个子技能提供专业化支持。特别强化PHP+MySQL CMS二次开发场景，提供CMS自动探测、PHP版本选型、数据库规范、安全红线、AJAX渐进式防卡死等专项指引。\n\n## 子技能列表\n\n| 子技能 | 功能 | 触发关键词 |\n|--------|------|-----------|\n| 软件项目总控 | 通用软件项目从需求到交付的总控：边界、行为契约、架构、数据/API/集成、测试、安全、发布、回滚、监控、告警、巡检和沉淀 | 软件项目, API服务, 后端服务, 后台模块, CLI工具, 数据脚本, 自动化任务, 插件项目, 完整功能, 项目交付, 部署, 发布, 回滚, 运维, 监控, 告警, 巡检 |\n| 网站项目总控 | 从需求到上线的建站项目总控：站点规划、内容SEO、前端设计、CMS/API/数据、测试安全、性能部署、验收运维 | 做网站, 建站, 企业官网, 营销页, CMS网站, 网站上线, 网站交付 |\n| API设计 | 根据业务需求设计RESTful或GraphQL API接口，长任务采用 Init-Step-Poll 契约 | API设计, RESTful, GraphQL, 接口规范, AJAX防卡死, Init-Step-Poll, 长任务接口, 轮询接口 |\n| Bug诊断 | 分析错误日志和异常堆栈，定位Bug根因并给出修复方案 | Bug诊断, debug, 报错, 异常堆栈 |\n| Karpathy编码规范 | 提供Karpathy核心编码哲学：思考优先、简洁至上 | Karpathy编码规范, Karpathy, 编码哲学 |\n| Spec驱动开发 | 编码前对齐需求规格，使用OpenSpec artifact flow | Spec驱动开发, spec, 需求对齐 |\n| 代码审查 | 审查代码质量，发现Bug、安全漏洞和代码缺陷 | 代码审查, code review, 代码缺陷 |\n| 代码生成 | 根据功能需求生成高质量代码，含错误处理和边界条件 | 代码生成, 生成代码, 实现功能 |\n| 任务拆解与执行 | 将复杂需求拆分为原子任务，按Wave分组执行 | 任务拆解与执行, 任务分解, Wave执行 |\n| 技术选型 | 根据项目需求推荐合适技术栈、框架和工具 | 技术选型, 技术栈, 框架选型 |\n| 文档生成 | 根据代码生成技术文档、README、API文档、部署说明和运维文档 | 文档生成, API文档, README, 部署说明, 回滚说明, 运维文档 |\n| 测试用例生成 | 生成单元测试、集成测试、安全测试、性能测试和长任务测试 | 测试用例生成, 单元测试, 测试用例, 安全测试, 性能测试, 长任务测试 |\n| 重构建议 | 分析代码结构，识别坏味道并提供重构方案 | 重构建议, 重构, 坏味道, 代码异味 |\n| 项目记忆管理 | 捕获上下文和决策，实现跨会话项目记忆沉淀 | 项目记忆管理, 项目记忆, 跨会话 |\n| CMS二次开发 | PHP+MySQL CMS 二次开发全链路：CMS探测/PHP版本/数据库规范/安全红线/插件开发/长任务防卡死 | CMS, 帝国CMS, WordPress, ThinkPHP, PHP8兼容, 二次开发, 插件开发, 批量任务, 导入导出, 生成静态页 |\n| 前端设计 | UI/UX 与前端实现设计：设计思维、信息架构、视觉规范、品牌、Banner、图标、社媒图、响应式、可访问性、浏览器验证、进度轮询 | 前端设计, UI设计, UX, 交互设计, 响应式, 设计系统, 品牌设计, Banner, 图标, 社媒图, 进度条, 轮询状态 |\n| MySQL数据库 | MySQL 数据建模、SQL安全、索引设计、事务边界、慢查询诊断、迁移回滚和数据安全 | MySQL, 数据库设计, SQL, 索引, 事务, 慢查询, EXPLAIN, DDL, 迁移, 表结构, SQL优化 |\n\n## 使用方法\n\n通过 Marvis 对话自然触发，说出需求即可自动匹配对应子技能。\n\n## 协同技能\n\n### 子技能内部协同\n17个子技能通过\"关联Skill\"章节相互引用，形成全生命周期闭环。常见协同路径：\n- 通用软件项目：软件项目总控 → Spec驱动开发 → 技术选型/API设计/MySQL数据库/CMS二次开发 → 任务拆解与执行 → 代码生成 → 代码审查 → 测试用例生成 → 文档生成/部署运维说明 → 项目记忆管理\n- 网站项目：网站项目总控 → Spec驱动开发 → 任务拆解与执行 → 前端设计/CMS二次开发/API设计/MySQL数据库 → 代码生成 → 代码审查 → 测试用例生成 → 文档生成 → 项目记忆管理\n- 需求阶段：Spec驱动开发 → 任务拆解与执行 → 前端设计/代码生成\n- 页面阶段：前端设计 → 代码生成 → 代码审查 → 测试用例生成 → 文档生成\n- 交付阶段：代码生成 → 代码审查 → 测试用例生成 → 文档生成/部署运维说明\n- 治理阶段：Bug诊断/重构建议 → 代码审查 → Karpathy编码规范 → 项目记忆管理\n- CMS二开：CMS二次开发 → (前端设计/代码生成/Bug诊断/代码审查/技术选型) → 项目记忆管理\n- MySQL专项：MySQL数据库 → 代码生成/代码审查/Bug诊断 → 测试用例生成 → 项目记忆管理\n- AJAX防卡死：Init → Step → Poll，API设计 → 前端设计 → CMS二次开发/代码生成 → 测试用例生成\n- 沉淀阶段：任何子技能 → 项目记忆管理（记录决策/规范/summary）\n\n### 跨技能包协同\n本技能包为独立套件，暂无可直接联动的其他职业技能包。如需在编程任务中集成外部数据或服务，可使用主Agent的web_search/web_fetch工具获取。\n\n## 版本\n\nv1.5.1 | 更新日期: 2026-07-02\n\n## 变更日志\n\n### v1.5.1 (2026-07-02)\n\n- 任务拆解模板新增安全触发面识别，Wave 任务必须写明安全验证项\n- SKILL.md 新增部署、发布、回滚、运维、监控、告警、巡检路由\n- 软件项目总控补强监控指标、告警阈值、巡检清单和运维交付材料\n- 测试用例生成补齐安全测试、性能测试和 Init-Step-Poll 长任务测试分类\n\n### v1.5.0 (2026-07-02)\n\n- 新增 软件项目总控 子技能（references/software-project.md）\n- 覆盖 API 服务、后台模块、插件、CLI 工具、数据脚本、自动化任务等非网站项目的完整交付链\n- 修正组合路由规则：多子技能命中时先按优先级矩阵组合路由，无法组合时才选最高匹配度\n- 补强任务拆解关联链和项目记忆流程格"},{"path":"_meta.json","content":"{\n \"ownerId\": \"kn7096hdmqr56bh0825xpz8ft188dh24\",\n \"slug\": \"dev-expert\",\n \"version\": \"0.1.0\",\n \"publishedAt\": 1786814953369\n}"},{"path":"references/api-design.md","content":"# API设计 -- 智能API设计\n\n## 输入要求\n\n1. **业务需求**（必填）：需要设计的业务场景和功能\n2. **数据模型**（必填）：核心实体和字段\n3. **接口类型**（可选）：RESTful或GraphQL，默认RESTful\n4. **已有接口**（可选）：如果已有部分接口需要兼容\n5. **特殊要求**（可选）：如\"需要支持批量操作\"、\"需要Webhook回调\"\n\n## 执行流程\n\n### 第一步：Spec场景检查\n\n设计前检查是否有明确的spec：\n\n- **如有spec**：提取spec中的Requirement和Scenario作为接口设计依据，确保每个Requirement对应至少一个端点，每个Scenario映射为接口的成功/错误响应\n- **如无spec**：提示用户先使用 `Spec驱动开发` 对齐需求，或基于业务需求生成轻量级spec\n\n```\n✓ Spec场景检查: [检测到/未检测到] 需求规格\n[如检测到，列出 Requirement → 端点 映射]\n```\n\n### 第二步：需求分析\n\n- 识别API的使用场景和用户\n- 确定API的功能边界\n- 明确输入输出数据模型\n\n### 第三步：设计原则应用\n\n- 应用RESTful或GraphQL设计原则\n- 设计URL结构和HTTP方法\n- 定义请求/响应格式\n\n### 第四步：详细设计\n\n- 设计每个端点的详细规范\n- 定义错误处理策略\n- 设计认证和授权机制\n- 如接口涉及长任务/批处理/导入导出/生成任务，必须采用 `Init → Step → Poll` AJAX 渐进式防卡死架构\n\n### 第五步：API规范定义\n\n```markdown\n## API Spec: [API名称]\n\n### ADDED Requirements\n\n#### Requirement: [端点名称]\n\nThe system SHALL provide an endpoint to [功能描述].\n\n##### Scenario: 成功请求\n\n- GIVEN [前置条件]\n- WHEN 发送 `[METHOD] [路径]` 请求\n- THEN 返回 [状态码] 和 [响应体]\n\n##### Scenario: 错误处理\n\n- GIVEN [错误前置条件]\n- WHEN 发送 `[METHOD] [路径]` 请求\n- THEN 返回 [错误状态码] 和 [错误响应体]\n\n### Design\n\n- **URL结构**: [结构说明]\n- **认证方式**: [认证机制]\n- **版本策略**: [版本管理]\n\n### File Changes\n\n- `[API定义文件]` (new/modified)\n\n```\n\n### 第六步：文档生成\n\n- 生成OpenAPI/Swagger规范\n- 编写使用示例\n- 提供SDK代码示例\n\n### 第七步：记录到项目记忆\n\nAPI 设计完成后，将关键决策和规范记录到项目记忆（参见 `project-memory-management.md`）：\n- 记录 API 设计决策（如 RESTful vs GraphQL 选择理由）\n- 记录接口命名约定和版本策略\n- 记录认证/授权方案的选型依据\n\n## 输出格式\n\n````\n\n## API设计文档\n\n### 资源定义\n\n| 资源 | 说明 | 核心字段 |\n| -------- | ------ | ---------- |\n| [资源名] | [说明] | [字段列表] |\n\n### 接口列表\n\n#### [接口名称]\n\n**URL**：`[METHOD] /path`\n**说明**：[功能说明]\n\n**请求参数**：\n| 字段 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| [字段] | [类型] | [是/否] | [说明] |\n\n**响应格式**：\n\n```json\n{\n \"code\": 0,\n \"data\": { ... },\n \"message\": \"success\"\n}\n```\n\n**错误码**：\n| 错误码 | 说明 |\n|--------|------|\n| [CODE] | [说明] |\n\n### 通用规范\n\n- **认证方式**：[Bearer Token / API Key / OAuth2]\n- **版本控制**：[URL路径 / Header / 参数]\n- **分页方式**：[页码分页 / 游标分页]\n- **数据格式**：[snake_case / camelCase]\n\n### 长任务接口规范（如适用）\n\n| 端点 | 方法 | 说明 |\n|------|------|------|\n| `/tasks/{type}/init` | POST | 创建任务，返回 `task_id`、`total`、初始状态 |\n| `/tasks/{task_id}/step` | POST | 执行一批处理，返回进度和 `has_more` |\n| `/tasks/{task_id}/poll` | GET | 查询任务状态、进度、错误和结果 |\n\n**Step 响应必须包含**：`task_id`, `status`, `processed`, `total`, `percent`, `has_more`, `message`, `errors`\n\n````\n\n## 质量标准\n\n- URL必须使用名词复数形式，不能用动词（如/users而非/getUsers）\n- HTTP方法必须符合语义（GET无副作用、POST创建、PUT幂等更新、DELETE删除）\n- 错误响应必须包含机器可读的错误码和人工可读的消息\n- 分页接口必须说明最大页大小和默认页大小\n- 敏感操作（删除、批量修改）必须要求二次确认或特殊权限\n- 不得设计返回超大列表的接口（必须分页或流式）\n- 长任务/批处理接口必须采用 `Init → Step → Poll`，不得设计为单请求同步阻塞执行\n- Step 接口必须幂等、可重试，并限制单批处理数量\n\n## 失败回退机制\n\n| 步骤 | 失败条件 | 回退目标 | 最大重试 | 不可恢复时升级路径 |\n|------|---------|---------|---------|------------------|\n| 第一步：Spec场景检查 | 无spec且业务需求模糊 | 基于业务需求生成轻量级spec草案 | 1 | 标注\"需求未对齐\"，建议先走 Spec驱动开发 |\n| 第二步：需求分析 | 业务场景涉及多个领域，边界不清 | 拆分为多个子API分别设计 | 2 | 输出需求拆分建议，由用户确认后继续 |\n| 第三步：设计原则应用 | RESTful与GraphQL均不完全契合 | 选择主风格+局部例外，标注例外原因 | 1 | 输出两套方案对比，由用户决策 |\n| 第四步：详细设计 | 认证/授权机制与现有系统冲突 | 降级到最简认证（Bearer Token），标注待对齐 | 2 | 输出认证方案选型矩阵，"},{"path":"references/bug-diagnosis.md","content":"# Bug诊断 -- 智能Bug诊断\n\n## 输入要求\n\n1. **错误信息**（必填）：错误日志、异常堆栈或报错截图\n2. **相关代码**（必填）：出错的代码片段\n3. **运行环境**（可选）：操作系统、语言版本、依赖版本\n4. **复现步骤**（可选）：如何触发这个错误\n\n## 执行流程\n\n### 第一步：Spec场景检查\n\n诊断前先检查相关spec中的scenario：\n- **如有spec**：确认bug是否涉及spec中的scenario，检查scenario的Given/When/Then是否被正确实现\n- **spec与实现不一致**：可能是spec理解偏差导致的bug\n- **无spec**：诊断后建议补充spec防止同类bug\n\n```\n✓ Spec场景检查:\n- 相关Scenario: [scenario名称]\n- 预期行为: [spec定义]\n- 实际行为: [观察到的行为]\n- 偏差分析: [spec vs 实现]\n```\n\n### 第二步：已知问题检查\n\n检查项目记忆中的已知问题：\n- 搜索项目记忆中的类似bug记录\n- 检查是否有已知的workaround\n- **发现新问题**：诊断完成后提示记录到项目记忆\n\n### 第三步：错误解析\n\n- 识别错误类型（语法错误、运行时错误、逻辑错误、环境错误）\n- 提取关键信息（错误码、错误消息、发生位置）\n- 分析堆栈跟踪（调用链、最后执行位置）\n\n### 第四步：根因分析\n\n| 错误类型 | 常见根因 | 分析方法 |\n|---------|---------|---------|\n| **语法错误** | 拼写错误、括号不匹配、缩进错误 | 定位到具体行号和字符 |\n| **运行时错误** | 空指针、数组越界、类型错误 | 检查变量状态和数据流 |\n| **逻辑错误** | 条件判断错误、算法缺陷 | 追踪执行路径和中间结果 |\n| **环境错误** | 依赖缺失、版本不兼容、配置错误 | 检查环境和依赖信息 |\n| **并发错误** | 竞态条件、死锁、资源竞争 | 分析线程/协程交互 |\n\n### 第五步：定位问题\n\n- 指出具体的代码位置（文件、函数、行号）\n- 说明变量在错误时刻的状态\n- 追踪数据流找到问题源头\n\n### 第六步：提供修复（Surgical Changes）\n\n- 给出修复后的代码\n- 说明修复原理\n- **Karpathy约束**：只修改修复Bug必需的代码，不改相邻代码、风格、注释\n- 提供验证修复的方法\n\n### 第七步：定义成功标准（Goal-Driven Execution）\n\n基于已确定的根因和修复方案，明确定义\"修复成功\"的标准：\n- **复现测试**：写一段能稳定触发Bug的测试/步骤\n- **成功标准**：修复后应达到什么状态（如\"空邮箱不再导致崩溃\"）\n- **验证方法**：如何确认修复有效（如\"运行复现测试10次均通过\"）\n\n**示例**：\n```\n成功标准：用户邮箱为空字符串时，validate_user() 抛出 ValueError 而非崩溃。\n复现测试：调用 validate_user({'email': ''}) → 应抛出 ValueError。\n验证方法：运行复现测试 → 通过。\n```\n\n### 第八步：记录到项目记忆\n\n修复完成后，将关键决策和变更记录到项目记忆（参见 `project-memory-management.md`）：\n- 记录 Bug 根因和修复方案（Decision Record 模式）\n- 记录新增的预防措施和编码规范（Convention Capture 模式）\n- 更新已知问题清单，防止同类 Bug 复发\n\n## 输出格式\n\n```\n## Bug诊断报告\n\n**错误类型**：[语法/运行时/逻辑/环境/并发]\n**错误信息**：[核心错误消息]\n**发生位置**：[文件/函数/行号]\n\n## 根因分析\n\n**问题描述**：[一句话说明]\n**详细分析**：[逐步推理过程]\n**相关代码**：\n```[问题代码]```\n\n## 修复方案\n\n```[修复后的代码]```\n\n**修复说明**：[为什么这样修复]\n\n## 验证方法\n\n1. [步骤1]\n2. [步骤2]\n\n## 预防措施\n\n- [建议1]\n- [建议2]\n```\n\n## 质量标准\n\n- 根因分析必须基于代码和日志证据，不能猜测\n- 修复代码必须可运行，且能解决原问题\n- 必须提供验证方法，让用户确认修复有效\n- 对于不确定的根因，标注\"最可能的原因\"并列出其他可能性\n- 环境相关错误必须说明具体的环境要求或版本限制\n- 不得建议用户\"重启试试\"或\"重新安装\"作为首要方案\n- **Karpathy红线**：修复前必须先写复现测试，修复后验证测试通过\n- **Karpathy红线**：只修改修复Bug必需的代码，不改相邻代码、风格、注释\n\n## CMS 常见 Bug 模式\n\n当诊断对象为 PHP+MySQL CMS 时，优先排查以下模式：\n\n| Bug 类型 | 典型表现 | 常见根因 | 修复方向 |\n|----------|---------|---------|---------|\n| PHP 版本兼容 | `Fatal error: Uncaught TypeError` / `Deprecated:` | 低版本代码运行在高版本 PHP | 参见 `cms-development.md` PHP 8.x 兼容性检查表 |\n| CMS 缓存失效 | 修改代码后页面无变化 | CMS 模板/数据缓存未清理 | 清理 `runtime/` `e/tmp/` `data/dbcache/` 后重试 |\n| 模板引擎错误 | 标签不解析或输出原始标签 | 模板语法错误或引擎版本差异 | 检查模板标签闭合和 CMS 版本对应语法 |\n| 数据库表前缀 | `Table 'xxx_tablename' doesn't exist` | 表前缀配置与实际不一致 | 检查 CMS 配置文件中的表前缀设置 |\n| MySQL 慢查询 | 页面卡顿 / SQL 超时 / CPU 飙高 | 缺索引、全表扫描、排序临时表 | 采集 SQL、参数、表行数和 EXPLAIN，参考 `mysql-database.md` |\n| MySQL 死锁 | `Deadlock found when trying to get lock` | 事务顺序不一致或锁范围过大 | 缩短事务、统一更新顺序、检查索引命中 |\n| 序列化数据 | `unserialize(): Error at offset` | WordPress `wp_options` 等序列化数据损坏 | 用 `maybe_unserialize()` 或修复序列化字符串长度 |\n| 伪静态路由 | 404 或路由不生效 | `.htaccess` / Nginx rewrite 规则缺失 | 检查伪静态规则和 CMS 路由配置 |\n| 文件编码 | 中文乱码 / `headers already sent` | UTF-8 BOM"}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":null,"editorialQuality":{"score":100,"threshold":65,"status":"thin","wordCount":811,"uniquenessScore":44,"reasons":["uniqueness-below-45"]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-09T23:54:15.269Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-09T23:54:15.269Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-10T06:43:31.431Z","emptyReason":null},"items":[{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-10-09T19:11:12.944Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}