diff --git a/api-web/api-interface/src/main/java/com/heyu/api/controller/car/skills/01商品名称.png b/api-web/api-interface/src/main/java/com/heyu/api/controller/car/skills/01商品名称.png deleted file mode 100644 index 72c29bb..0000000 Binary files a/api-web/api-interface/src/main/java/com/heyu/api/controller/car/skills/01商品名称.png and /dev/null differ diff --git a/api-web/api-interface/src/main/java/com/heyu/api/controller/car/skills/02API访问前缀.png b/api-web/api-interface/src/main/java/com/heyu/api/controller/car/skills/02API访问前缀.png deleted file mode 100644 index 9250648..0000000 Binary files a/api-web/api-interface/src/main/java/com/heyu/api/controller/car/skills/02API访问前缀.png and /dev/null differ diff --git a/api-web/api-interface/src/main/java/com/heyu/api/controller/car/skills/03商品logo.png b/api-web/api-interface/src/main/java/com/heyu/api/controller/car/skills/03商品logo.png deleted file mode 100644 index 11d62c2..0000000 Binary files a/api-web/api-interface/src/main/java/com/heyu/api/controller/car/skills/03商品logo.png and /dev/null differ diff --git a/api-web/api-interface/src/main/java/com/heyu/api/controller/car/skills/04产品信息.png b/api-web/api-interface/src/main/java/com/heyu/api/controller/car/skills/04产品信息.png deleted file mode 100644 index 1a4b922..0000000 Binary files a/api-web/api-interface/src/main/java/com/heyu/api/controller/car/skills/04产品信息.png and /dev/null differ diff --git a/api-web/api-interface/src/main/java/com/heyu/api/controller/car/skills/05产品截图.png b/api-web/api-interface/src/main/java/com/heyu/api/controller/car/skills/05产品截图.png deleted file mode 100644 index fada321..0000000 Binary files a/api-web/api-interface/src/main/java/com/heyu/api/controller/car/skills/05产品截图.png and /dev/null differ diff --git a/api-web/api-interface/src/main/java/com/heyu/api/controller/car/skills/06资质与案例.png b/api-web/api-interface/src/main/java/com/heyu/api/controller/car/skills/06资质与案例.png deleted file mode 100644 index 778bbb3..0000000 Binary files a/api-web/api-interface/src/main/java/com/heyu/api/controller/car/skills/06资质与案例.png and /dev/null differ diff --git a/api-web/api-interface/src/main/java/com/heyu/api/controller/car/skills/07售后服务.png b/api-web/api-interface/src/main/java/com/heyu/api/controller/car/skills/07售后服务.png deleted file mode 100644 index 16cd911..0000000 Binary files a/api-web/api-interface/src/main/java/com/heyu/api/controller/car/skills/07售后服务.png and /dev/null differ diff --git a/api-web/api-interface/src/main/java/com/heyu/api/controller/car/skills/08售后服务范围.md b/api-web/api-interface/src/main/java/com/heyu/api/controller/car/skills/08售后服务范围.md deleted file mode 100644 index 0c24e1e..0000000 --- a/api-web/api-interface/src/main/java/com/heyu/api/controller/car/skills/08售后服务范围.md +++ /dev/null @@ -1,10 +0,0 @@ - -售后服务时间：7 * 24小时（8:00-22:00） -售后服务内容：技术支持 -服务热线：19550207125 -服务钉钉1：nat8tfz -服务钉钉2：xmk3f0b -服务邮箱：service@1024api.com - - - diff --git a/api-web/api-interface/src/main/java/com/heyu/api/controller/car/skills/09商品规格.png b/api-web/api-interface/src/main/java/com/heyu/api/controller/car/skills/09商品规格.png deleted file mode 100644 index d57a1d0..0000000 Binary files a/api-web/api-interface/src/main/java/com/heyu/api/controller/car/skills/09商品规格.png and /dev/null differ diff --git a/api-web/api-interface/src/main/java/com/heyu/api/controller/car/skills/10.最终用户协议.md b/api-web/api-interface/src/main/java/com/heyu/api/controller/car/skills/10.最终用户协议.md deleted file mode 100644 index 021f8ba..0000000 --- a/api-web/api-interface/src/main/java/com/heyu/api/controller/car/skills/10.最终用户协议.md +++ /dev/null @@ -1,137 +0,0 @@ - -最终用户使用协议 - - - -欢迎您使用银行卡二、三、四要素核验。 - -本银行卡二、三、四要素核验最终用户协议（“本协议”）是您和杭州谦芝慧科技发展有限公司之间，就服务商为您提供银行卡二、三、四要素核验（“本【服务】”），所达成的合法协议。 - - - -一、协议的生效 - -1、用户确认而生效：本协议由服务商提供在线版本，用户购买本【服务】时，应认真阅读本协议后，须保持本协议为勾选状态，方可进入下一步购买流程。本协议一经用户确认，即具有合同效力，对服务商和用户具有法律约束力。 - -2、用户使用而生效：用户可以通过【获取服务】（注：由服务商根据商品种类选择相应表述），或其他方式使用本【服务】。服务商会在相应环节提供本协议的在线版本供用户阅读。一旦用户以前述任一方式使用本【服务】，即表示用户已同意接受本协议中的所有条款。如果用户不接受本协议中的条款，请不要使用本【服务】。 - - - -二、定义 - -1、××【软件/镜像/服务】是指【】。 - -2、（服务商如有其他需要定义的内容，请补充） - - - -三、使用许可（注：服务商自行增删相应条款） - -1、本【服务】受版权法、国际版权条约以及其他相关的知识产权法律、法规和条约的保护。本软件产品/服务为授权用户使用许可，而非出售。 - -2、本【服务】的【版权/所有权】归【权利人名称】所有。 - -3、根据本协议的约定，服务商授予用户一项非排他的、不可转让的使用本【服务】的使用许可。用户不得转售或以其他方式转让本使用许可权利以牟取商业利益。（注：本条为参考，服务商应自行明确使用许可的性质、范围等） - - - -四、费用： - -1、服务商同意，目前向用户免费提供本【服务】的有限使用许可。但该免费服务，不应视为服务商放弃在未来某一时刻开始收费的权利。未来服务商如对用户就本【服务】收取许可费用，将通过相关网页、购买环节等明示告知用户。（注：适用免费产品） - -1、用户使用本【服务】须按照本【服务】的价格体系、支付所有费用。服务商保留在用户未按照约定支付全部费用之前不向用户提供服务和/或技术支持，或者终止服务和/或技术支持的权利。（注：适用收费产品） - -2、用户如对本【服务】进行续费时，本【服务】的名称、规格或价格已经调整的，用户同意按照届时有效的新的【服务】的名称、规格或价格履行；用户不同意新的【服务】的名称、规格或价格的，可不进行续费，本【服务】到期后自动终止。 - - - -五、用户的权利义务 - -1、用户保证其使用本【服务】的各项行为均符合国家法律法规的规定，合法真实且不侵害任何第三方的合法权益。 - -2、用户应按时足额支付本【服务】的费用（如有），否则服务商保留随时终止用户使用本【服务】的权利，用户应对服务商终止本【服务】而可能造成的损害自行承担全部责任。 - -3、用户保证，除且仅除法律明确允许的活动以外，用户不得逆向工程、反编译或反汇编本【服务】。 - -4、用户理解并同意， - -（1）因现有技术限制，服务商提供的【服务】可能存在瑕疵，并不能保证在任何情况下都能正常执行或达到用户所期望的结果。 - -（2）因用户使用本【服务】所致的任何损害，用户同意服务商的最高赔偿限额为【】 - - - -六、服务商的权利义务 - -1、服务商保证，其有合法权利向用户提供本【服务】的使用许可，并保证其版权的合法性。 - -2、服务商承诺，其向用户提供本【服务】之行为未对任何第三方合法权益，包括但不限于第三方知识产权构成侵害。如因其行为导致用户遭受任何第三方提起的法律诉讼或行政程序（“侵权指控”），服务商承担其法律责任及后果。 - -3、服务商负责及时对本【服务】进行升级、维护和管理，并通过客服电话、在线客服等方式，向用户提供免费的咨询及技术支持服务。 - -4、服务商承诺，保证其为用户提供的【服务】的稳定性和延续性。如因服务商原因，导致用户对于本【服务】的使用许可需提前终止的，服务商应对用户履行相应的退款义务（如有）。如因此给用户造成损失的，服务商应承担全额的赔偿责任。 - -5、服务商承诺，其向用户提供的【服务】中不含有： - -（1）蓄意毁坏、恶意干扰、秘密地截取或侵占任何系统、数据或个人资料的任何病毒、伪装破坏程序、电脑蠕虫、定时程序炸弹或其他电脑程序； - -（2）任何已知的漏洞、后门、恶意软件； - -（3）其他可能对用户的系统安全造成损害的不安全内容。 - -6、责任限制：在适用法律所允许的最大范围内，服务商不会对因使用或不能使用本【服务】所引起的或有关的任何间接的、意外的、直接的、特殊的、惩罚性的或其它任何损害（包括但不限于因人身伤害或财产损坏而造成的损害，因利润损失、数据损失、营业中断、计算机瘫痪或故障、商业信息的遗失而造成的损害，因未能履行包括诚信或相当注意在内的任何责任致使隐私泄露而造成的损害，因疏忽而造成的损害，或因任何金钱上的损失或任何其它损失而造成的损害）承担赔偿责任，即使服务商事先被告知该损害发生的可能性。 - - - -七、用户数据的使用和披露 - -1、为服务用户的目的，服务商可能通过使用用户数据，向用户提供服务，包括但不限于向用户发出产品和服务信息。 - -2、未经用户许可，服务商不会擅自披露用户数据。但在下述情况下，用户数据将部分或全部被披露： - -（1）经用户同意，向第三方披露； - -（2）根据法律的有关规定，或者行政或司法机构的要求，向第三方或者行政、司法机构披露； - -（3）如果用户出现违反中国有关法律法规的情况，需要向第三方披露； - -（4）为提供用户所要求的软件或服务，而必须和第三方分享用户数据。 - - - -八、期限与终止 - -1、本【服务】的期限为【一年】。 - -2、出现下列情况之一的，服务商有权终止继续提供本【服务】，而无需承担任何责任： - -（1）用户购买的【服务】已到期且未续费的； - -（2）用户严重违反本协议项下条款的约定，且自服务商通知其纠正后仍未纠正的。 - - - -九、协议修改 - -1、如果本协议的任何内容发生变动，服务商应通过适当方式向用户提示修改内容。 - -2、如果用户不同意服务商对本协议相关条款所做的修改，用户有权停止使用本【服务】。此等情况下，服务商应向用户退回剩余费用（如有），并在终止服务前给予用户一定的合理期限，进行数据备份、下载、保存、迁移及其他必要工作。如用户继续使用本【服务】，则视为用户接受服务商对本协议相关条款所做的修改。 - - - -十、法律及争议解决 - -1、本协议的订立、执行和解释及争议的解决均应适用【中华人民共和国法律】。 - -2、因双方就本协议的签订、履行或解释发生争议，双方应努力友好协商解决。如协商不成，任何一方均应向【被告所在地】人民法院起诉。 - - - -十一、附则 - -1、如本协议的任何条款被视作无效或无法执行，则上述条款可被分离，其余部分则仍具有法律效力。 - -2、本协议的标题仅为方便阅读所设，非对条款的定义、限制、解释或描述其范围或界限。 - -3、服务商可根据其自身运营状况，在提前【30】个工作日通知用户的前提下，将其在本协议项下的权利义务全部转让给第三方，而无需获得用户的事先同意。服务商之受让人受本协议约束，服务商与其受让人对本协议的履行承担连带责任。 - diff --git a/api-web/api-interface/src/main/java/com/heyu/api/controller/car/skills/10最终用户协议.png b/api-web/api-interface/src/main/java/com/heyu/api/controller/car/skills/10最终用户协议.png deleted file mode 100644 index 6834223..0000000 Binary files a/api-web/api-interface/src/main/java/com/heyu/api/controller/car/skills/10最终用户协议.png and /dev/null differ diff --git a/api-web/api-interface/src/main/java/com/heyu/api/controller/car/skills/11.特殊商品资质.md b/api-web/api-interface/src/main/java/com/heyu/api/controller/car/skills/11.特殊商品资质.md deleted file mode 100644 index b86820c..0000000 --- a/api-web/api-interface/src/main/java/com/heyu/api/controller/car/skills/11.特殊商品资质.md +++ /dev/null @@ -1,5 +0,0 @@ -本公司承诺：所提供的核验能力在合法合规前提下开展，数据来源及使用方式符合国家关于个人信息保护、数据安全及电信管理等相关规定；不向用户索取与业务无关的敏感信息，不将核验结果用于违法违规用途。用户侧授权与告知义务由本公司与用户约定并落实，因本公司违反法律法规或平台规则导致的责任由本公司承担。 - - - - diff --git a/api-web/api-interface/src/main/java/com/heyu/api/controller/car/skills/12特殊商品资质.png b/api-web/api-interface/src/main/java/com/heyu/api/controller/car/skills/12特殊商品资质.png deleted file mode 100644 index 55e28db..0000000 Binary files a/api-web/api-interface/src/main/java/com/heyu/api/controller/car/skills/12特殊商品资质.png and /dev/null differ diff --git a/api-web/api-interface/src/main/java/com/heyu/api/controller/car/skills/ALIYUN_MARKETPLACE_SKILL_DESIGN.md b/api-web/api-interface/src/main/java/com/heyu/api/controller/car/skills/ALIYUN_MARKETPLACE_SKILL_DESIGN.md deleted file mode 100644 index fcd3067..0000000 --- a/api-web/api-interface/src/main/java/com/heyu/api/controller/car/skills/ALIYUN_MARKETPLACE_SKILL_DESIGN.md +++ /dev/null @@ -1,1563 +0,0 @@ -# 阿里云市场上架辅助 Skill — 需求与技术方案 - -> 用途：定义一个 Claude Code Skill，引导开发者完成"API 自测 → 测试用例沉淀 → 阿里云市场上架材料生成"全流程，所有交互在聊天中完成。 -> -> 本文档只做 **需求确认 + 技术方案**，不做实现。开发推进前请先与作者对齐"开放问题"小节中的决策项。 - ---- - -## 〇、TL;DR - -一句话：**"装上 Skill → 聊几轮天 → 拿到一个能直接提交阿里云的材料包 + 一份测试报告"**。 - -Skill 接管两件事： -1. **API 接口测试**：读源码 → 引导启动服务 → 自动调接口 → 给代码建议 → 沉淀测试用例 -2. **上架材料生成**：基于 12 项阿里云要求（商品名称/API 前缀/Logo/产品信息/截图/资质/售后/规格/EULA/特殊资质）逐项确认，能在线查的去网上找，能让 AI 生成的直接生成，需要本地工具的（如 PDF/Logo 绘制）提前告知开发者准备。 - ---- - -## 一、背景 - -### 1.1 现状 -- 团队目前正在把 `eb-service-api` 的 OCR / 核验类接口（驾驶证、行驶证、银行卡核验等）发布到阿里云市场 -- 每个接口上架都要重复整理同一套材料：商品名/Logo/产品截图/EULA/售后/特殊资质 -- 现有材料散落在 `controller/car/skills/` 下（10 多张截图 + 几份 markdown），命名不统一、无脚本化产出 -- 接口本身的功能验证靠开发者手动调 Postman，测试沉淀全靠口头 - -### 1.2 痛点 -| 痛点 | 现状 | -|---|---| -| 测试用例不持久 | 上架前手测一遍，下次发版又得重测 | -| 上架材料每次重做 | 12 项材料每次手工拼凑，命名/格式/版本号不一致 | -| 阿里云要求会变 | 平台审核规则、特殊资质类目时不时调整，开发者每次现查 | -| 资质类材料生成成本高 | Logo 要 PS、EULA 要法务模板、PDF 要排版工具 | - -### 1.3 目标 -- **零检索成本**：开发者不主动去网上查阿里云要求；Skill 主动检索、主动询问、主动给建议 -- **零格式纠错**：所有产出（材料/测试报告）落到统一目录，命名/尺寸/字数符合阿里云规范 -- **可复制**：第二个、第三个接口上架，只需要回答增量问题，公共材料（公司信息、售后、EULA 模板）自动复用 - ---- - -## 二、用户画像 - -| 角色 | 描述 | 使用场景 | -|---|---|---| -| 后端开发（主要） | Java 工程师，写完接口要上架 | 跑 Skill，做完自测，产出材料 | -| 产品/运营（辅助） | 提供商品文案、定价策略、客服信息 | 在 Skill 询问时通过开发者代答 | - -> **设计取舍**：开发者是唯一的交互入口；Skill 不直接接触产品/运营，但要把"需要他们提供"的字段列清楚，方便开发者去要。 - -![角色与交互](./diagrams/actors.svg) - ---- - -## 三、范围 - -### 3.1 In Scope -- 读取 Java Controller / Request / Response 源码，理解接口契约 -- 引导开发者启动本地服务（不替开发者跑 `mvn`，但给出命令） -- 调用本地接口做正向 / 异常路径自测 -- 给代码建议（命名、返回协议一致性、错误处理、字段映射等） -- 生成 JUnit / HTTP 风格的测试用例文件 -- 检索阿里云市场审核规范（联网或 WebFetch） -- 逐项收集 12 类上架材料，输出到统一目录 -- 复用已有资料（`skills/` 目录下的 markdown / png） -- 生成 EULA、售后说明、产品介绍等纯文本材料 -- 给出 Logo / 产品截图 / PDF 类材料的"获取建议"（推荐工具、参考尺寸、模板链接） - -### 3.2 Out of Scope（首版不做） -- ❌ 直接调阿里云 OpenAPI 上架（涉及鉴权、风控，先做"材料就绪"为止） -- ❌ 跨语言：只支持本仓库的 Java + Spring Boot 项目 -- ❌ 性能压测、安全扫描（接口功能自测即可） -- ❌ 自动写法律文本（EULA 用模板 + 填空，不替代法务） - -### 3.3 已纳入（决策更新） -- ✅ **AI 生成 Logo**：Skill 出多版草稿，开发者本地再用 PS / Figma 微调（详见 §6.2、§8.6） -- ✅ **支持非 OCR 接口**：通用 REST 接口也可上架；接口测试模板按"REST 通用"+"OCR 专用"两套（详见 §8.4.5） - -### 3.4 核心原则：全程非阻塞（v0.5 重要原则） - -> 这一条贯穿整个 Skill 的设计，所有章节都要遵守。 - -**任何步骤、任何询问、任何代码建议，都不允许阻塞用户。** - -| 场景 | 处理方式 | -|---|---| -| 用户拒绝回答某个问题 | 标记为 `SKIPPED`，继续下一步 | -| **用户提供的内容不完整** | **一次性给完整建议**（缺哪几项 + 为什么建议补 + 不补的后果）→ 用户回应"补 / 跳过 / 部分补"→ Skill 按选择处理 → **不重复追问**。详见下方 §3.4.1 | -| 代码建议被拒绝 | 标记为 `DECLINED`，记录原因（若用户说明） | -| **某项材料无法生成（如 AI 出图失败）** | **立即通知用户**（不静默失败）+ 给 2~3 个备选方案 + 让用户选下一步 → 用户不响应或选跳过 → 标记 `FAILED` 写入 FINAL_REPORT。详见下方 §3.4.2 | -| 用户中途退出 | 当前阶段写入状态文件，下次 `/aliyun-marketplace 继续` 时无缝续上 | - -#### 3.4.1 "内容不完整 → 建议 → 跳过"模板 - -**🔑 关键原则**：建议只给**一次**，用户忽略就跳过。不允许循环追问（避免逼问感）。 - -``` -Skill: 你刚才填了商品名 "驾驶证识别 API v1.0"，我检查阿里云命名规则发现： - ✅ 含产品功能（驾驶证识别） - ✅ 含版本号 - ⚠️ 缺英文名（阿里云海外市场强制要求；境内市场建议） - ⚠️ 缺品牌前缀（同类商品建议加，便于搜索区分） - - 建议补成："1024API · 驾驶证识别 API v1.0 / DriverLicense OCR API v1.0" - - 怎么处理？ - (1) 用你建议的 ← 推荐 - (2) 我改成：____ （直接告诉我） - (3) 就用我原来的 "驾驶证识别 API v1.0"，跳过补全 ← 标记 PARTIAL - (4) 跳过整项 - -用户：3 -Skill: 好，标记为 PARTIAL（已填中文名，未填英文名 / 品牌前缀）。继续下一项 → - 【FINAL_REPORT 会记：商品名缺英文名，海外市场上架前需补】 -``` - -**Skill 行为约束**： -- 同一项**最多触发 1 次建议**，用户的回应决定终态 -- 用户回 `跳过` / `就用现在的` → 立即标记 `PARTIAL` + 写入待补充清单，**不再询问** -- 用户回 `不知道` / `没建议` → Skill 给 2~3 个推荐选项 + 一个"跳过"路径 -- 不允许出现 "再考虑下" / "再问一次" 这种循环 - -#### 3.4.2 "材料生成失败 → 立即通知 → 备选方案"模板 - -**🔑 关键原则**：**Skill 任何失败必须立即告诉用户**，绝不静默。把失败原因 + 备选方案一并抛给用户决定。 - -**触发场景**： -- AI 出图失败（API 超时 / 限流 / 拒绝生成） -- WebFetch 阿里云规范失败（网络 / 反爬） -- 文件落盘失败（权限 / 磁盘满） -- 模板填空找不到必需占位符值 -- 接口自测请求 502/超时 -- 自动校验失败（如 Logo 尺寸不符） - -**通知 + 备选格式**： -``` -Skill: ⚠️ Logo 生成失败了，告诉你一声。 - - ❌ 失败原因：Pollinations.ai 连续 3 次响应超时（最后一次 30s 后断开） - 📌 已记录：./logs/03_logo_failure.log（含每次请求的 Prompt 与时间戳） - - 备选方案（请选一个）： - (1) 换 fal.ai 重试 —— 质量更高，需要你配 API Key - 获取链接：https://fal.ai/dashboard/keys （5 美元免费额度） - 你只需说"key=xxx"，我自动存到本地 credentials.json - (2) 换通义万相重试 —— 需要阿里云 AK/SK - 获取链接：https://help.aliyun.com/document_detail/450961.html - (3) 用占位 Logo —— 我已经生成 placeholder.png（白底 + 商品名文字） - 路径：./03_logo/placeholder.png - 可后续自己换，FINAL_REPORT 会标记 - (4) 跳过 Logo，整项标 FAILED，FINAL_REPORT 标"待补充" - (5) 等 5 分钟，我再试一次 Pollinations - - 你选？ -``` - -**用户回应处理**： -| 用户回应 | Skill 行为 | -|---|---| -| 选 (1)~(3) | 按选项执行，记录所选备选方案到状态文件 | -| 选 (4) | 标 `FAILED`，写入 FINAL_REPORT，继续下一项 | -| 选 (5) | 自动重试，最多再 2 次；仍失败则回到 (1)~(4) | -| 跳过 / 不响应 | 默认走 (4)，继续下一项 | - -**对 FINAL_REPORT 的影响**： -失败项在 `§六 失败项及原因` 表格中单独列出，包含： -- 失败原因（具体错误信息） -- 已尝试的备选方案 -- 用户最终选择 -- 重试建议（含外部链接） - -**Skill 行为硬约束**： -- ❌ 不允许"静默失败 + 仅写日志" -- ❌ 不允许失败后直接进入下一项不通知 -- ✅ 每次失败必须**主动展示给用户** + **给至少 2 个备选** -- ✅ 同一项失败重试 ≤ 3 次，超出后强制让用户选备选方案或跳过 - -**最终一定要产出 `FINAL_REPORT.md`**，把以下信息汇总给用户（详见 §6.4）： -1. ✅ 已完成项 -2. ⚠️ 用户跳过 / 拒绝的输入项 -3. ⚠️ 建议但未被采纳的代码改进点 -4. ❌ 缺失的上架材料 + 缺失原因 -5. 💡 后续建议优化清单（按优先级排序） - -> **设计哲学**：Skill 是助手，不是审批官。能帮多少帮多少，剩下的清单交还给开发者自己决定。 -> 但有一份"账"必须算清楚 —— 哪些做了、哪些没做、为什么没做、接下来做什么。 - -### 3.5 服务式设计原则（v0.6 核心理念） - -> 比"非阻塞"更进一步：**Skill 不是来问开发者要东西的，是来帮开发者做事的**。 -> 每次问用户之前，先把"做这件事需要的所有上下文"准备好；用户只需要确认 / 修改 / 跳过。 - -#### 3.5.1 三条铁律 - -**铁律 1 — 能自己做的，自己做** -- Skill 能从源码 / 配置 / git / web 推断出来的，**绝不问用户** -- 例如：商品名（从类名 + 注释推断）、API 前缀（从 `@RequestMapping` 抽取）、Logo 关键词（从接口注释抽取）、版本号（从 `pom.xml` 读） - -**铁律 2 — 必须用户做的事，先把"半成品"准备好** -- 用户需要截图？先把要截的页面 URL、要执行的请求、要展示的内容**全部准备好**，让用户复制粘贴即可 -- 用户需要去外部平台操作？给**精确链接 + 步骤截图位置 + 操作指引** -- 用户需要提供二进制文件（如执照 PDF）？给**文件格式要求 + 推荐工具 + 模板下载链接** - -**铁律 3 — 用户每次只回答"确认 / 修改 / 跳过"** -- 不允许"你能不能给我 X" 这种空白提问 -- 必须是"我已经准备好了 X（草稿见 [链接]），你看看要改吗？还是直接用？" - -#### 3.5.2 例：用户需要 Postman 截图 - -**❌ 不要这样**： -``` -Skill: 请提供 3~5 张接口调用的 Postman 截图。 -``` - -**✅ 要这样**： -``` -Skill: 阿里云需要 3~5 张接口调用截图。我已经替你准备好了 Postman 调用包： - - 📋 我已生成 5 组样例请求（已写入 ./05_screenshots/postman/RecognizeDriverLicense.postman_collection.json）： - 1. 正向：识别正页（影像 = 我准备的开源测试图，已埋好 URL） - 2. 正向：识别副页 - 3. 异常：side 非法 → 期望 msg 含 "页面标识无效" - 4. 异常：图片格式错 → 期望 msg 含 "影像不合规" - 5. 异常：URL 不可访问 → 期望 msg 含 "服务无回执" - - 📌 操作步骤： - 1. 打开 Postman → File → Import → 选 RecognizeDriverLicense.postman_collection.json - 2. 把 5 个请求依次跑一遍 - 3. 每个请求跑完后 Cmd+Shift+4 截图（macOS） - 4. 截图丢到 ./05_screenshots/ 目录下，命名 01.png ~ 05.png - - 你打算什么时候做？ - (1) 现在做，我等你 ← 推荐，3 分钟搞定 - (2) 待会做，先跳过，最终报告会提醒你 - (3) 不做了，截图我自己想办法 -``` - -#### 3.5.3 例：用户需要上传公司营业执照 - -**❌ 不要这样**： -``` -Skill: 请提供公司营业执照 PDF。 -``` - -**✅ 要这样**： -``` -Skill: 阿里云对"OCR 类"商品要求上传公司营业执照（PDF 格式，≤5MB）。我已经准备好了： - - 📋 阿里云官方要求（2026 版）： - - 文件格式：PDF（推荐）/ JPG / PNG - - 大小：≤5MB - - 清晰度：能看清统一社会信用代码 - - 有效期：在有效期内的最新版 - - 📌 你可以这样获取： - - 行政同事手里通常有扫描件，邮箱 service@1024api.com 问一下 - - 或自己用手机拍 → 用以下任一工具转 PDF： - • CamScanner（推荐，免安装） - • macOS 预览：拖入图片 → 文件 → 导出为 PDF - • 在线工具：https://smallpdf.com/jpg-to-pdf - - 📌 准备好之后： - - 把文件放到 ./12_special_qualification/营业执照.pdf - - 我会自动校验格式和大小 - - 你打算什么时候做？ - (1) 我去问行政，5 分钟回来 - (2) 跳过，最终报告标记"待补充" -``` - -#### 3.5.4 主动准备清单（每项材料） - -`§六` 的每项材料表格新增"**Skill 替你做**"一列，明确 Skill 主动准备的内容（见 §6 更新）。 - -### 3.6 Skill 主动改代码 / 改注释的能力与边界（v0.11 新增） - -> 用户在聊天中给的信息，Skill **可以直接落到代码**，不要每次让用户自己去改文件。 -> 但要分清边界：哪些可以闷头改，哪些必须先给 diff、哪些必须二次确认。 - -#### 3.6.1 可直接改的内容（低风险）— **闷头改 + 完事汇报** - -Skill 不需要二次确认就可以应用： - -| 触发场景 | Skill 行为 | -|---|---| -| 用户回 "@author 改成 张三 (zhangsan@1024api.com)" | 直接 Edit Controller Javadoc 的 `@author` | -| 用户回 "把 `@author` 同步到所有 OCR Controller" | 批量改全部命中 Controller，给文件清单 | -| 用户回 "Logo 我选 #3" | 复制 `draft/03.png` 到 `final/logo-256.png` | -| 用户回 "商品名用你建议的" | Write `01_product_name.md` | -| 用户回 "用占位 Logo" | 应用 placeholder.png，更新 MANIFEST | -| 给文档/注释加缺失的 section（如 §十六 9 项小节） | 直接补到 Javadoc 中 | -| 替换平台占位符（公司名 / 服务名 / 联系电话） | Edit EULA 等模板里的 `{XXX}` | - -**完事汇报格式**： -``` -Skill: ✅ 已更新： - - RecognizeDriverLicenseController.java（@author） - - RecognizeDrivingLicenseController.java（@author） - - 共 2 处变更，无回归测试需要 - 继续下一项 → -``` - -#### 3.6.2 改前必看 diff 的内容（中风险）— **先展示 diff，用户点头才落地** - -涉及业务逻辑、可能引入语义变化的，给 diff 让用户确认： - -| 触发场景 | Skill 行为 | -|---|---| -| 用户接受 "extends AbstractRecognizeController" 建议 | 给 unified diff，展示删了 5 处重复方法 + 父类导入变更 | -| 接受 "嵌套 PlatformError 改为 BaiduOcrError" | 给 diff 展示删除内嵌枚举 + 引用方式变化 | -| 接受 "recognize() 抽取方法" | 给 diff 展示拆分后的方法骨架 | -| 接受 "把 `imageBase64` + `imageUrl` 合并为 `imageUrlOrBase64`" | 给 diff 展示 Request 字段变化 + 所有引用点 | -| 接受 "把 log.warn 改成 log.info / log.error" | 给 diff 展示每条日志的新级别选择 | - -**diff 展示格式**： -``` -Skill: 我准备这样改（diff 见下），看 OK 吗？ - - RecognizeXxxController.java - --- a/RecognizeXxxController.java - +++ b/RecognizeXxxController.java - @@ -3,3 +3,3 @@ - -import com.heyu.api.controller.BaseController; - +import com.heyu.api.controller.AbstractRecognizeController; - @@ -45,2 +45,2 @@ - -public class RecognizeXxxController extends BaseController { - +public class RecognizeXxxController extends AbstractRecognizeController { - @@ -78,15 +78,2 @@ - - // [删除] 内嵌 PlatformError 枚举（15 行） - ... - 涉及变更：1 个文件，删除 5 个方法（已下沉父类），新增 1 个 defaultEmptyResp 重写 - - 确认？ - (Y) 直接应用 - (N) 我再调一下，回头说 - (M) 给我看完整文件预览 -``` - -#### 3.6.3 必须用户二次确认的内容（高风险）— **不轻易动** - -涉及对外契约、可能影响调用方的，Skill **只给建议、不主动改**： - -- 修改 Request / Response 类的字段名（破坏 JSON 契约） -- 修改 URL 路径 (`@RequestMapping`) -- 修改 HTTP 方法、Content-Type -- 修改鉴权注解（`@EbAuthentication`） -- 删除已有的方法 / 字段 -- 修改返回码、状态约定 -- 任何跨模块的连锁修改 - -这一档 Skill 只展示"如果改，影响范围有这些"，让用户自己决定。 - -#### 3.6.4 改完之后 - -无论哪一档，改完后 Skill 必须： -1. **明确告知变更范围**：哪个文件、哪几行、什么变更 -2. **跑可用的回归检查**：编译 / 单测 / lint（如果环境支持） -3. **失败回滚机制**：如果编译/测试失败，告诉用户并提供 `revert` 命令 -4. **写入 FINAL_REPORT**：变更明细计入"本次 Skill 修改了哪些代码"小节 - -#### 3.6.5 一句话总结 - -> **用户的回复 = 指令；Skill 的工作 = 执行**。能在代码里落实的，不要在聊天里只口头答应。 - ---- - -## 四、端到端用户流程 - -> **总览图**（详细子步骤见 §4.1~§4.8）： -> -> ![端到端流程](./aliyun_skill_flow.svg) - -### 4.1 触发 -开发者在 Claude Code 输入： -``` -/aliyun-marketplace # 首次启动 -/aliyun-marketplace 继续 # 从上次断点继续 -``` -或者自然语言："帮我把驾驶证识别接口上架到阿里云"。 - -### 4.2 阶段 0 — 初始化 -Skill 提问（**首次启动时**）： -1. 你的项目根目录在哪里？（默认从 cwd 推断） -2. 本次要上架/测试哪个 Controller？（如 `RecognizeDriverLicenseController`） -3. 默认的材料输出目录？（默认：`{controller}/skills/output/`） - -把答案存到 `skills/.aliyun-skill-state.json`，下次自动续上。 - -### 4.3 阶段 1 — 源码分析 -- 读 Controller / Request / Response 三个文件 -- 提取：URL 路径、HTTP 方法、入参字段、出参字段、错误码 -- 生成"接口契约摘要"给开发者过目 -- 给出代码建议（基于现有 `CODE_SPECIFICATION.md` 自动比对）： - > "你这个接口没继承 AbstractRecognizeController，建议改造，理由：..." - -### 4.4 阶段 2 — 启动检测（v0.10 简化） - -> Skill 不操心怎么启动，只关心服务有没有起来。启动是开发者自己的事，Skill 等就行。 - -**流程**： -1. **自动探测**：Skill 直接尝试连接默认端口（从 `pom.xml` / `bootstrap.yml` 自动读，识别失败则用项目惯例如 8888） -2. **服务已起**：调一次 health 端点确认连通 → 直接进入阶段 3，不打扰开发者 -3. **服务未起**：提示开发者启动，**不给命令、不教方法**，等待即可 - -**对话样例**： -``` -Skill: 我连不上本地服务（默认 8888 端口，超时 3s）。 - 请你启动服务（怎么启动你比我熟），然后告诉我： - (1) 已起来 ← 我重新探测 - (2) 端口不是 8888，是：____ - (3) 这次不测接口，跳过自测阶段 -``` - -**重新探测循环**： -- 用户回 "已起来" → Skill 再探测一次，成功就继续，失败就再问一次 -- 探测连续失败 3 次 → 主动建议跳过接口自测阶段，FINAL_REPORT 标"未自测" -- 用户回 "跳过" → 整个阶段 3 自测跳过，直接进入阶段 4 测试用例生成（基于源码契约推断） - -> **设计哲学**：服务启动是开发者本地环境的事，Skill 给 mvn 命令反而显得"教学生用筷子"。开发者跑 IDE / 跑 docker / 跑 mvn / 跑 `make run` 都行，Skill 只看结果。 - -### 4.5 阶段 3 — 接口自测 -按"正向 → 异常"顺序自动跑： -1. **正向用例**：用 `ImageInputUtils` 工具构造影像入参（要求开发者提供 1~2 张样例图，或自动找开源测试图） -2. **异常用例**：覆盖参数缺失、side 非法、图片格式错、超大图等 -3. 每跑一条，给开发者展示请求 / 返回 / 结论 -4. 发现 bug 当场报，让开发者改完继续 - -### 4.6 阶段 4 — 测试用例沉淀 -- 生成 `src/test/java/com/heyu/api/controller/xxx/{Object}ControllerTest.java` -- 同步生成一份 `TEST_REPORT.md`，含：用例清单 / 覆盖率估算 / 已知问题 - -### 4.7 阶段 5 — 上架材料采集（服务式） -按 12 项清单逐项处理（详见第 6 节）。每一项 Skill 都遵循"**先备好、再问**"： -- **第一步：自动复用** — 先查目录里有没有现成的（如 `08售后服务范围.md` 已存在 → 直接读 + 确认） -- **第二步：自动检索** — 没有 → WebFetch 阿里云对该项的最新要求 → 缓存 -- **第三步：自动生成草稿** — 能 AI 生成的（如商品名、产品介绍、Logo、EULA 业务正文重写）→ Skill 先出草稿 -- **第四步：备好上下文再问** — 必须用户提供的（如执照 PDF、产品截图），按 §3.5.2/§3.5.3 的格式：给精确要求 + 推荐工具 + 操作步骤 + 文件落地路径 - -> **原则**：让用户每次只面对"确认 / 修改 / 跳过"三选一，永远不给空白提问。 - -### 4.7.5 阶段 5.5 — 最终确认 & 补遗（v0.6 新增，关键环节） -材料采集走完后、打包之前，Skill **必须**做一次"补遗确认"： - -1. **汇总未就绪清单**： - - 之前跳过的输入项 - - AI/Skill 生成了草稿但用户没看过的项 - - 失败的项（重试机会） - -2. **统一展示给用户**： - ``` - Skill: 准备生成最终材料前，我整理了 4 项还没就绪的，给你最后一次机会处理： - - 1. 📷 05 产品截图（跳过中）—— Postman 包已就绪，3 分钟可搞定，要不要现在做？ - 2. 🎨 03 Logo（4 张草稿待选）—— 缩略图 [draft/1.png ~ 4.png]，选哪张？ - 3. 📄 12 营业执照（待提供）—— 行政可能有，要不发我看看？ - 4. 💡 代码建议 #3（@author 占位）—— 真名+联系方式比较好，要改吗？ - - 选项： - (A) 现在逐项处理（推荐，每项不超过 3 分钟） - (B) 1, 3 现在做，2/4 跳过 - (C) 全部跳过，直接生成材料（这些会写入 FINAL_REPORT 的"待补充"清单） - ``` - -3. **用户选 C → 不再追问，直接进入打包**。补遗只是"最后一次提醒"，不是"必须做"。 - -### 4.8 阶段 6 — 材料打包 & 最终报告 -- 输出目录结构（见 §6.3） -- 生成 **`MANIFEST.md`**：纯文件清单 + 阿里云后台对应页面 -- 生成 **`FINAL_REPORT.md`**（**核心交付物**，模板见 §6.4）： - - 整体完成度评分（X/12 项已就绪） - - 用户跳过的输入项清单 - - Skill 给过但用户未采纳的代码建议 - - 缺失材料及其原因 - - 后续优化建议（按优先级排序） -- 即使前面阶段有跳过/失败，此阶段**必须执行**，让用户拿到完整账本 - ---- - -## 五、功能需求详表 - -### 5.1 必备能力 -| 编号 | 能力 | 优先级 | -|---|---|---| -| F-01 | 首次启动收集项目路径 / 目标类 / 输出目录 | P0 | -| F-02 | 状态持久化（断点续跑） | P0 | -| F-03 | 解析 Spring Controller + Request/Response 类的源码 | P0 | -| F-04 | 引导启动服务，验证端口连通 | P0 | -| F-05 | 自动构造测试请求并调用接口 | P0 | -| F-06 | 基于 `CODE_SPECIFICATION.md` 给出代码改进建议 | P1 | -| F-07 | 生成 JUnit 测试用例文件 | P0 | -| F-08 | 生成 `TEST_REPORT.md` | P1 | -| F-09 | 12 项上架材料逐项采集与生成 | P0 | -| F-10 | 检索阿里云市场最新审核要求（WebFetch） | P0 | -| F-11 | 资产生成建议（Logo / PDF / 截图工具推荐） | P0 | -| F-12 | 复用既有材料（`skills/` 目录已有文件） | P0 | -| F-13 | 输出目录 + `MANIFEST.md` 总览 | P0 | -| F-14 | 多接口共享公共材料（公司/售后/EULA 模板） | P1 | - -### 5.2 代码建议覆盖项 -基于已沉淀的 `CODE_SPECIFICATION.md`，Skill 至少检查： -- 是否继承 `AbstractRecognizeController` -- 是否使用 `BaiduOcrError`（vs 自己嵌 PlatformError） -- **请求对象字段数（建议性，根据业务给意见）**： - - ≤ 2 字段：✅ 推荐形态，不提示 - - 3~4 字段：💡 提示但不阻断，给"是否能合并 / 是否可下沉鉴权"的优化建议 - - ≥ 5 字段：⚠️ 进阶建议，例如"`userId` 看起来像鉴权字段，建议走 Header" - - **不强制阻断**：Skill 给的是 *建议*，开发者业务确有需要可以拒绝 -- 是否检测到并列的 `imageBase64` + `imageUrl` 字段（应合并为 `imageUrlOrBase64`） -- 是否检测到鉴权字段放在 Request 里（`userId` / `merchantId` / `token`） -- 是否走 `ImageInputUtils` -- `recognize()` 行数 ≤ 80 -- `@EbAuthentication` 是否添加 -- 6 步注释分块是否完整 -- 响应对象是否全 `String` 字段 -- 是否有 `defaultEmptyResp` 重写 - -### 5.3 用户体验 & 可维护性维度（10 项重点检查） - -> 这一组的目标是：**让接口好用、让线上问题"看一眼日志/错误信息就能定位"**，把人工客服成本降到最低。 -> 标杆参考：`RecognizeDriverLicenseController.java`。 - -#### 5.3.1 错误信息（对外） -| 检查项 | Skill 行为 | -|---|---| -| ① 错误信息要"全 + 详"，一眼看清是什么问题、怎么改 | 检查 `msg` 是否走 `formatHint(category, reason, suggestion, detail)` 四要素；缺一项即提示补全 | -| ② 不允许暴露"百度 / baidu / Baidu / BAIDU"等上游字样 | grep `msg` / `data` 字面量；用 "**平台**" 统一替代；含义不变 | -| ③ 提示文案不重复 | 收集所有 `formatHint(...)` 调用，发现两个 hint 文案 90% 相似时提示 "可差异化表达" | - -**示例对比**： -``` -❌ "图片错误" -✅ "【驾驶证识别·影像不合规】像素尺寸或编码后体积不满足规范（边长 15~4096px，编码后≤4M） - ｜定位信息：错误码=216202，影像模式=Base64，目标页面=正页(front/face) - ｜处置指引：请压缩或裁剪图片，保证最长边≤4096px、最短边≥15px，且 urlencode 后≤4M" -``` - -#### 5.3.2 业务逻辑位置 -| 检查项 | Skill 行为 | -|---|---| -| ④ **所有判断与数据封装在 Controller 内**，不要藏到 Service/Handler/Helper | grep Controller 文件外的辅助类，若被本接口调用且承载业务判断（非纯工具），提示"建议内联回 Controller"。理由：OCR 适配类接口业务很轻，全在 Controller 反而最易排查 | -| ⑤ 异常场景必须**分类捕获 + 写明原因**，禁止裸 `catch (Exception e) { log.error("error", e); }` | 检查 catch 块内是否调用了 `formatHint(...)` 且 `category` 描述具体；裸 catch 提示补救 | - -#### 5.3.3 计费保护 -| 检查项 | Skill 行为 | -|---|---| -| ⑥ **调用过平台之后一律 `R.ok()`**（已扣费） | 静态分析 `recognize` 方法：在 `callPlatform`/`requestBaidu` 调用之后，禁止出现 `R.error(...)`；只能 `okResult(side, hint, null/data)` | - -#### 5.3.4 日志（对内） -| 检查项 | Skill 行为 | -|---|---| -| ⑦ **只允许 `log.info` 与 `log.error`**，禁止 `log.warn` / `log.debug` / `log.trace` | grep 出所有 `log.warn` / `log.debug` 调用，逐条提示改 info 或 error | -| ⑧ 每条日志必须包含完整业务参数（side / imageMode / 入参摘要 / 平台回执 / traceId）| 检查 `log.xxx(...)` 调用中是否拼接了 `ctx.inputLog`、`buildPlatformReceiptSummary(...)`、`sideDesc(...)` 等；缺关键参数即提示补 | -| ⑨ 日志文案不重复 | 同 §5.3.1③，跨 info/error 整体扫一遍 | -| ⑩ 日志"说人话" | Skill 启发式检测：日志内不允许只有变量名+冒号（如 `"side: {}, mode: {}"`），必须有完整句子描述发生了什么、为什么发生（如 `"驾驶证识别：参数检查没通过，直接返回错误（还没调识别、不扣费）..."`）| - -**好/坏对比**： -``` -❌ log.error("error {} {}", side, e); -❌ log.warn("invalid input"); -✅ log.error("驾驶证识别：平台拒绝了本次识别。[{}] 错误码 {}，原因：{}。识别{}，{}。客户传的：{}。{}", - category, errorCode, errorMsg, sideDesc(ctx.side), ctx.imageMode.desc, - ctx.inputLog, buildPlatformReceiptSummary(platformResult)); -``` - -#### 5.3.5 Controller 头部注释（重点） -| 检查项 | Skill 行为 | -|---|---| -| ⑪ Controller 类 Javadoc 必须包含以下小节 | 解析类注释结构，缺一项即提示补 | - -**必备小节清单**： -1. **接口背景 / 用途**（一段话讲清楚这个接口能干什么、服务什么业务场景） -2. **上游平台官方文档链接**（百度 / 阿里云 / 腾讯 的产品页 + 接口地址）—— *这部分写在类注释内部，对外不暴露* -3. **本服务接口路径** + Content-Type + 鉴权方式 -4. **请求参数说明**（字段表） -5. **响应结构说明**（字段表 + side 区分） -6. **返回约定**（强调"调过平台一律 R.ok"等业务约定） -7. **@author 开发者标签**（线上有问题第一时间找谁，含姓名 + 联系方式 / 钉钉） -8. **@since 版本号** -9. **@see 关联类**（Request / Resp） - -**模板片段**： -```java -/** - * 驾驶证识别控制器 - *

- * 接口背景：替代客户手工录入驾驶证字段... - *

- * - *

百度官方文档

- * - * - *

本服务接口

- * - * - *

请求参数

... - *

响应结构

... - *

返回约定

... - * - * @author 张三 (zhangsan@1024api.com / 钉钉 zs_dingding) - * @since 1.0.0 - * @see DriverLicenseRecognizeRequest - * @see RecognizeDriverLicenseFaceResp - */ -``` - -> Skill 检测到 `@author` 缺失、或值为通用占位（如 `heyu` / `system`）时，提示 "请填写真实负责人 + 联系方式，线上故障定位用"。 - ---- - -## 六、上架材料清单（核心交付） - -按 `skills/` 目录截图编号映射。**每项都标明 Skill 替用户做了什么 + 用户需要做什么**： - -| 序号 | 材料 | Skill 替你做 | 用户只需 | 备注 | -|---|---|---|---|---| -| 01 | 商品名称 | 基于类名/注释 AI 生成 3 个候选（含中/英/版本号），含阿里云命名规则比对 | 选一个或微调 | 含 v1.0 等版本号 | -| 02 | API 访问前缀 | 从 `@RequestMapping` 自动提取，无需用户介入 | — | 全自动 | -| 03 | 商品 Logo | 写 3~5 套 Prompt → 调 Pollinations 出 PNG → 落到 `03_logo/draft/` + 生成微调指引 README（含 Figma/Photopea 直达链接） | 选 1 张 + 本地微调（可跳过） | 256×256，<1MB | -| 04 | 产品信息 | 基于接口契约 + 行业模板 AI 生成完整草稿（含简介/特性/场景/定价规则） | 看一眼，改不改都行 | Markdown | -| 05 | 产品截图 | **生成 Postman Collection JSON + 5 组样例请求 + 截图操作步骤说明** | 跑 Postman + 截图 5 张到指定目录（可跳过） | 3~5 张 | -| 06 | 资质与案例 | 自动检测 ICP 备案接口（公司域名）+ 查阿里云对该类目的最低要求 + 给一份案例模板 | 提供 ICP 截图 / 客户 logo（可跳过） | PDF/MD | -| 07 | 售后服务 | 直接复用 `07售后服务.png` 已有信息 | 确认或修改 | 含电话/钉钉/邮箱 | -| 08 | 售后服务范围 | 直接复用 `08售后服务范围.md` | 确认 | 完全沉淀 | -| 09 | 商品规格 | **三步走**：① 问开发者一个数字（"按次调用想收多少钱？不知道也行"）② WebFetch 阿里云市场同类目 3~5 家竞品的定价表（按次/月/年/阶梯）③ 基于 ① + ② 自动生成完整规格方案（按次 / 包月 / 包年 三档 + 阶梯优惠 + 竞品对照表 + 阿里云规格表 JSON）| 选方案 或 改某档具体数字 或 跳过 | 详见 §6.2.3 | -| 10 | EULA | **AI 重写**：把 `10.最终用户协议.md` 当作**结构骨架**（章节顺序、条款类型）使用；正文中"银行卡二、三、四要素核验"等业务描述由 Skill 按当前接口业务**整段重写**；公司名 / 服务商名 / 联系电话从 `pom.xml` / 配置自动填；保留 `【XXX】` 等法务可调占位符 | 通读 + 法务复审（重要） | **AI 生成**，非简单复用 | -| 11 | 特殊资质声明 | 复用 `11.特殊商品资质.md` + 替换业务名 | 确认 | 完全沉淀 | -| 12 | 特殊商品资质 | 给阿里云最新要求清单 + 文件格式/大小要求 + PDF 转换工具推荐（CamScanner、Smallpdf）+ 文件落地路径 | 提供执照扫描件（可跳过） | PDF | - -**单列了"Skill 替你做"之后，每项材料的用户负担都明确收敛到一行**： - -| 用户负担程度 | 项数 | 编号 | -|---|---|---| -| 🟢 完全免操作（Skill 全做） | 2 | 02, 08 | -| 🟢 看一眼确认 | 4 | 01, 04, 07, 11 | -| 🟡 通读 + 法务复审（10 涉及法律责任） | 1 | 10 | -| 🟢 答一个数字（甚至不答也行） | 1 | 09 | -| 🟡 选一选或微调 | 2 | 03, 12 | -| 🟡 需提供外部素材（含完整操作指引） | 2 | 05, 06 | - -**12 项材料按生成方式分类**： - -![材料分类矩阵](./diagrams/materials_matrix.svg) - -### 6.1 阿里云规范检索 -- 用 WebFetch 抓 `https://market.aliyun.com/help/...` 该商品类目的最新要求 -- 缓存到 `skills/.aliyun-spec-cache.json`，每 7 天更新 -- 检索失败时回退到本地规范快照 - -### 6.2 资产生成的工具建议 - -#### 6.2.1 Logo（AI 生成 + 反馈式迭代 + 人工微调） - -**核心 UX 原则**：**生成 → 展示 → 反馈 → 再生成**，直到用户满意；用户不需要懂 Prompt，只用大白话给反馈。 - -##### A. 生成阶段 -1. Skill 基于商品名 / 接口注释 / 行业关键词，**自动**撰写 4 套 Logo Prompt（**默认 4 张**，覆盖 4 种风格）： - - 扁平 + 渐变 - - 抽象图形 + 单色 - - 行业意象 + 立体 - - 极简符号 + 双色 -2. 并发调图像生成 API → 输出 4 张 PNG → 落到 `03_logo/draft/01.png ~ 04.png` -3. 同时生成 `03_logo/draft/README.md`，列出每张图对应的 Prompt 与风格关键词（便于复盘） - -##### B. 展示阶段（适应 Claude Code 环境） -Skill 检测当前对话环境是否支持图片内联展示： - -| 环境 | 展示方式 | -|---|---| -| Claude Code 桌面端 / Web | **直接在对话中内联显示** 4 张缩略图 | -| 仅终端 / 不支持图片渲染 | **给绝对路径 + 一键打开命令**：
`open ./03_logo/draft/01.png` (macOS)
`xdg-open ./03_logo/draft/01.png` (Linux)
`start ./03_logo/draft/01.png` (Windows) | -| 任何环境 | **同时**写入 `03_logo/draft/preview.html`（4 张并排的网页），给链接 `file:///.../preview.html` 一键浏览器打开 | - -##### C. 反馈循环（核心，可无限迭代） -``` -Skill: 我出了 4 张草稿，你看下： - - [显示 01.png 02.png 03.png 04.png 缩略图或路径] - - 下一步？ - (1) 我选 #N，搞定 ← 进入本地微调（或直接定稿） - (2) #N 接近但不完美 → 描述哪里要改，我再生成几张 - (3) 4 张都不满意 → 描述你想要的方向，我重出 4 张 - (4) 跳过 → 用占位符 logo，最终报告标"待补充" - -用户：3 张都太花了，要更简洁的，最好用单色蓝 -Skill: 收到。我把 Prompt 调整为"极简 + 单色蓝 + 几何图形"，重新生成 4 张 → - [新的 4 张缩略图或路径] - 你看？ - -用户：#2 不错，但车的元素能更明显点吗 -Skill: 好，#2 基础上加强"汽车"意象，再出 4 张变体 → - [4 张围绕 #2 的变体] - 你看？ - -用户：#3 就这个！ -Skill: 已定稿 → 复制到 ./03_logo/final/logo-256.png-pre.png - 下一步可选： - (A) 直接用，跳过本地微调 ← 推荐快速上架 - (B) 本地微调（推荐 Photopea 网页版，无需安装） - 打开链接：https://www.photopea.com/ - 把 logo-256.png-pre.png 拖进去 → 微调后导出覆盖 logo-256.png - (C) 我帮你做尺寸/格式校验后定稿 -``` - -**循环退出条件**： -- 用户说"就这个" / "OK" / "定稿" → 进入 D 阶段 -- 用户回 "跳过" / "skip" → 用占位 logo + 标记 FINAL_REPORT 待补充 -- 累计 5 轮迭代后 → Skill 主动提醒"是否换个生成服务（如 fal.ai 提质）或先用占位" - -##### D. 本地微调 & 定稿（可跳过） -- 推荐 Photopea（网页版，零安装）：https://www.photopea.com/ -- 微调常见需求：背景色调整、文字添加、尺寸精确到 256×256 -- 完成后 Skill 自动校验：`logo-256.png` 是否存在、尺寸是否 256×256、文件大小 ≤ 1MB、格式 PNG - -##### E. 用户每轮可用的反馈关键词（不强制，仅参考） -为帮用户表达，Skill 在每轮展示时提供反馈关键词建议： -- 风格：**扁平 / 立体 / 渐变 / 极简 / 复古 / 科技** -- 色调：**单色蓝 / 暖橙 / 黑白 / 渐变绿** -- 元素：**加上 XXX 意象 / 去掉文字 / 让 XX 更突出** -- 调整：**更简洁 / 更生动 / 更专业 / 更年轻化** - -> 用户也可以**直接上传一张参考图** → 把路径告诉 Skill → Skill 提取参考图特征写进 Prompt。 - -**Logo 生成时序**： - -![Logo 生成时序](./diagrams/sequence_logo.svg) - -**图像生成 API 候选**（按推荐度排序）： -| 服务 | 鉴权 | 成本 | 优缺点 | -|---|---|---|---| -| Pollinations.ai | 无需 Key | 免费 | 直接 HTTP GET 出图，零配置；质量中等 | -| fal.ai (FLUX) | 需 API Key | 按张计费 | 质量高、可控；需开发者配 Key | -| 阿里云通义万相 | 需 AK/SK | 按张计费 | 中文场景理解好；与上架平台同生态 | -| Stability AI | 需 API Key | 按张计费 | 经典 SD，可商用 | - -> **默认走 Pollinations.ai**（零门槛），需高质量时引导开发者配 fal.ai / 通义万相 Key。 - -**首次启动时检测**：Skill 询问 "要不要配高质量出图 API Key？(默认用免费版)"，把 Key 存到 `~/.claude/skills/aliyun-marketplace/credentials.json`（仅本机）。 - -#### 6.2.2 其他资产 -| 类型 | 推荐工具 | 是否需开发者本地安装 | -|---|---|---| -| PDF | Pandoc / 在线 markdown 转 PDF | Pandoc 需本地安装；网页版可选 | -| 截图 | 系统自带（macOS shift+cmd+4）+ 在线裁剪 | 否 | -| 视频（如需要） | OBS / Loom | 是 | - -Skill 在该步骤会**先问开发者本地有没有装**，没有就推荐网页版替代。 - -#### 6.2.3 商品规格生成（服务式核心样例） - -**用户负担 = 一个数字（甚至这个数字都可以不知道）**，其余 Skill 全包。 - -**Step 1 — 问开发者唯一一个数字**： -``` -Skill: 09 商品规格我来帮你做。先问你一个事： - 按次调用，你打算收多少钱？ - - (1) 我有想法，告诉你：____ 元/次 - (2) 不知道，你按竞品给我算一个合理价 ← 推荐 - (3) 直接套行业平均价 - (4) 跳过这项 -``` - -**Step 2 — Skill 自动调研竞品**： -- WebFetch 阿里云市场同类目（OCR / 核验类）3~5 家竞品商品页 -- 抓取：按次单价 / 包月 / 包年 / 阶梯阶段 / 免费额度 -- 缓存到 `09_pricing/competitors.json`，附 URL + 抓取时间 - -**Step 3 — Skill 自动生成完整规格方案**： - -``` -Skill: 我查了 5 家同类目竞品（详见 ./09_pricing/competitors.json），定价区间在 - 0.03 ~ 0.10 元/次。基于你说的 0.05 元/次，我给你出 3 套方案： - - ┌─────────────────────────────────────────────────────────────┐ - │ 方案 A · 量大优惠型（推荐，对标 X 公司） │ - │ ├─ 按次：0.05 元/次（基线） │ - │ ├─ 包月：500 元/月，含 12,000 次（折合 0.042 元/次） │ - │ ├─ 包年：5,000 元/年，含 150,000 次（折合 0.033 元/次） │ - │ └─ 阶梯：>10万次/月 按 0.03 元/次（自动结算） │ - │ │ - │ 方案 B · 高频试用型（对标 Y 公司） │ - │ ├─ 免费额度：每月 100 次 │ - │ ├─ 按次：0.06 元/次 │ - │ └─ 包年：8,000 元/年，含 30 万次 │ - │ │ - │ 方案 C · 简洁型（对标 Z 公司） │ - │ └─ 按次：0.05 元/次（无其他规格） │ - └─────────────────────────────────────────────────────────────┘ - - 竞品对照（已查 5 家）： - A 公司：0.10 元/次，包年 ¥8,000 ← 价格最贵 - B 公司：0.05 元/次，包月 ¥499（含 1 万次） ← 与你定价最接近 - C 公司：免费 + 0.06 元/次 ← 走免费+收费模式 - D 公司：0.03 元/次，无包年 ← 价格最便宜 - E 公司：阶梯定价 0.04~0.08 元/次 - - 📌 我建议方案 A，理由： - - 0.05 元/次落在竞品中位（比中位价 0.045 元贵 11%，可解释为质量更好） - - 包月/包年给到量价优惠，符合阿里云市场客户偏好 - - 阶梯结算降低大客户门槛 - - 下一步？ - (1) 选方案 A ← 推荐，我已生成阿里云规格表 JSON - (2) 选方案 B / C - (3) 自定义：保留方案 X 的框架，改其中某个数字 - (4) 我想看 5 家竞品的完整定价表 → 我打开 competitors.json 给你 - (5) 跳过整项 -``` - -**Step 4 — Skill 生成最终产出**： -- `09_pricing/spec.json` —— 阿里云规格表标准 JSON 格式（可直接粘贴到阿里云提交页） -- `09_pricing/spec.md` —— 给开发者看的人类可读版（含表格 + 折算分析） -- `09_pricing/competitors.json` —— 竞品调研缓存（供日后复盘） - -**Step 5 — 用户回 "不知道"/"按竞品来" 的兜底**： -- Skill 不强制开发者给数字 -- 直接用"竞品中位价"生成 3 套方案 -- 在 FINAL_REPORT 标注："09 商品规格 按竞品中位价生成，开发者未提供定价偏好，建议正式提交前与商务确认" - -**Step 6 — 调研失败的兜底**： -- WebFetch 阿里云市场失败 → 用本地缓存（如有） -- 缓存也没有 → 给一份硬编码的"OCR 类目行业惯例参考表"（基于 §8.6 模板库） -- 同时按 §3.4.2 "材料生成失败"模板通知用户 - -### 6.3 输出目录结构 -``` -{output_dir}/ -├── FINAL_REPORT.md ← ★ 核心交付物：本次任务完整账本（见 §6.4） -├── MANIFEST.md ← 文件清单 + 阿里云后台对应页面 -├── 01_product_name.md ← 含中/英/版本号 -├── 02_api_prefix.md -├── 03_logo/ ← 目录，可放多版本 -│ ├── logo-256.png -│ └── README.md ← 生成建议（若开发者还没做） -├── 04_product_intro.md -├── 05_screenshots/ -│ └── README.md -├── 06_qualification/ -├── 07_support.md -├── 08_support_scope.md ← 复用既有 -├── 09_pricing.md -├── 10_eula.md ← AI 按当前接口业务重写 + 占位符已填（建议法务复审） -├── 11_special_declaration.md -├── 12_special_qualification/ -└── .aliyun-skill-state.json ← 内部状态 -``` - -### 6.4 FINAL_REPORT.md 模板（核心交付物） - -> **作用**：把"账"算清楚。即使用户跳过了若干问题、拒绝了若干建议，也必须有一份文档完整记录"做了什么 / 没做什么 / 为什么没做 / 接下来做什么"。 - -```markdown -# 阿里云市场上架材料 — 任务报告 - -> 生成时间：{TIMESTAMP} -> 接口：{CONTROLLER_CLASS} -> Skill 版本：{SKILL_VERSION} - ---- - -## 一、执行摘要 - -| 指标 | 值 | -|---|---| -| 完成度 | **9/12** 项已就绪（75%） | -| 用户跳过项 | 2 项 | -| 拒绝的建议 | 3 条 | -| 失败项 | 1 项 | -| 总耗时 | 42 分钟 | -| 状态 | ⚠️ 部分完成（可提交，但建议补齐后再上） | - ---- - -## 二、各阶段执行情况 - -| 阶段 | 状态 | 备注 | -|---|---|---| -| ① INIT 初始化 | ✅ 完成 | | -| ② SOURCE_SCAN 源码扫描 | ✅ 完成 | 提取 17 个字段 | -| ③ SERVICE_BOOT 启动引导 | ✅ 完成 | 端口 8888 | -| ④ API_TEST 接口自测 | ⚠️ 部分 | 8 条用例跑了 7 条，1 条用户跳过（"超大图测试"，理由：环境受限） | -| ⑤ TEST_GEN 测试用例 | ✅ 完成 | 生成 7 个 JUnit 用例 | -| ⑥ MATERIAL_COLLECT 材料采集 | ⚠️ 部分 | 见下方"材料状态" | -| ⑦ PACKAGE 打包 | ✅ 完成 | | - ---- - -## 三、12 项材料状态 - -| # | 材料 | 状态 | 说明 | -|---|---|---|---| -| 01 | 商品名称 | ✅ 就绪 | "驾驶证识别 API v1.0" | -| 02 | API 访问前缀 | ✅ 就绪 | /driver/license（自动提取） | -| 03 | 商品 Logo | ⚠️ 草稿待选 | AI 生成 4 张，用户尚未确认最终版 | -| 04 | 产品信息 | ✅ 就绪 | | -| 05 | 产品截图 | ❌ 缺失 | **用户跳过**（理由："明天再做"） | -| 06 | 资质与案例 | ❌ 缺失 | **用户跳过**（理由："公司无 ICP"）| -| 07 | 售后服务 | ✅ 就绪 | 复用 07*.png | -| 08 | 售后服务范围 | ✅ 就绪 | 复用 08*.md | -| 09 | 商品规格 | ✅ 就绪 | "0.1 元/次，包年 5000 元" | -| 10 | EULA | ✅ 就绪 | AI 重写银行卡模板 → 驾驶证识别版，占位符已自动填充，**建议法务复审** | -| 11 | 特殊资质声明 | ✅ 就绪 | 复用 11*.md | -| 12 | 特殊资质材料 | ⚠️ 失败 | AI 无法生成营业执照，需要开发者上传 | - ---- - -## 四、用户跳过 / 拒绝的输入项 - -| 项 | 类型 | 用户反馈原文 | 后续动作建议 | -|---|---|---|---| -| 产品截图 | 跳过 | "明天再做" | 提供 3~5 张接口调用截图（推荐 Postman + Swagger）| -| 公司资质 | 跳过 | "公司无 ICP" | 若上架"OCR / 数据类"类目，阿里云强制要求 ICP，需补办 | -| 超大图测试 | 跳过 | "环境受限" | 在压测环境用 5MB+ 图片复测一次 216202 错误码 | - ---- - -## 五、Skill 给过但未被采纳的代码建议 - -| # | 建议 | 严重度 | 用户回应 | 影响 | -|---|---|---|---|---| -| 1 | recognize() 方法 95 行 > 80 行规范上限，建议抽取异常兜底逻辑 | 💡 提示 | "暂不重构" | 长期可读性下降 | -| 2 | 检测到日志含 `log.warn`，规范要求只用 info/error | ⚠️ 警告 | "保留" | 与团队规范不一致，CR 时仍会被打回 | -| 3 | `@author` 标签为 "heyu"，建议改为真名+联系方式 | ⚠️ 警告 | 未回应（默认保留）| 线上凌晨告警找不到人 | - ---- - -## 六、失败项及原因 - -| 项 | 失败原因 | 重试建议 | -|---|---|---| -| 12 特殊资质材料 - 营业执照 | AI 无法生成法律证件类内容 | 让公司行政提供扫描件，按要求转为 PDF | - ---- - -## 七、阿里云规范检索结果（缓存） - -- 检索日期：2026-06-09 -- 来源：https://market.aliyun.com/help/...（已缓存至 .aliyun-spec-cache.json，7 天有效） -- 关键变化：本次未发现规范变更 - ---- - -## 八、后续优化清单（按优先级） - -### 🔴 P0 — 必须补齐才能提交 -- [ ] **03 Logo**：从 4 张草稿里选 1 张，本地微调后放到 `03_logo/final/logo-256.png` -- [ ] **05 产品截图**：截 3~5 张接口调用过程图 -- [ ] **12 营业执照**：补 PDF - -### 🟡 P1 — 强烈建议 -- [ ] **06 资质与案例**：核实公司 ICP 状态，若上架数据类类目这是硬性要求 -- [ ] **代码建议 #3**：把 `@author` 改为真实负责人 - -### 🟢 P2 — 长期优化 -- [ ] **代码建议 #1**：recognize() 方法拆分 -- [ ] **代码建议 #2**：去掉 `log.warn` -- [ ] **测试覆盖**：补充"超大图" 用例 - ---- - -## 九、提交检查清单 - -提交阿里云后台前请确认： - -- [ ] FINAL_REPORT 中"P0 必须补齐"项全部完成 -- [ ] 03_logo/final/ 下有 1 张 256×256 PNG -- [ ] 05_screenshots/ 至少 3 张图 -- [ ] 12_special_qualification/ 下有营业执照 PDF -- [ ] MANIFEST.md 中所有 ⚠️/❌ 项已处理或确认可接受 -- [ ] EULA 中占位符（公司名 / 联系电话）已替换实际值 -- [ ] 走一遍阿里云提交预览页，确认所有字段填好 - ---- - -> **生成方式**：本报告由 aliyun-marketplace Skill v{SKILL_VERSION} 自动生成。 -> 如需重新生成：`/aliyun-marketplace 重做报告` -``` - -> **报告产出原则**： -> - **可读性**：开发者扫一眼就知道下一步做什么（P0/P1/P2 优先级分级） -> - **可追溯**：用户的每个选择（跳过/拒绝）都记录在案，便于复盘 -> - **可执行**：每个未完成项都附带"下一步动作"，不留模糊地带 - ---- - -## 七、非功能需求 - -| 项 | 要求 | -|---|---| -| 交互方式 | 全程聊天，不弹外部 UI；命令通过 `Bash` 执行 | -| 状态持久 | 单文件 JSON，可在 Claude Code 会话中断后续跑 | -| 联网 | 优先用 WebFetch；超时 / 失败时降级到本地缓存 | -| 安全 | 不读 `.env` / `application-online.yml` 等敏感配置；只读 controller / request / resp / pom 等公共代码 | -| 隐私 | 测试用图建议用开源数据集，避免上传客户真实证件 | -| 兼容性 | macOS / Linux 优先；Windows 路径处理需注意分隔符 | -| 容错 | 任一阶段失败可单独重跑（如 "/aliyun-marketplace 重做 阶段5"） | -| 国际化 | 中文为主；商品名称等支持中英双语字段 | - ---- - -## 八、技术方案 - -### 8.1 Skill 元数据 -```yaml -name: aliyun-marketplace -description: | - 引导 Java/Spring Boot API 接口完成自测、测试用例生成、以及阿里云市场上架材料采集与生成。 - TRIGGER: "上架阿里云" / "阿里云市场" / "aliyun marketplace" / "/aliyun-marketplace" / - "生成 OCR 接口的上架材料" / "把这个接口发到阿里云"。 - SKIP: 非 Java 项目；纯调试 / 单测；阿里云控制台运维操作；要求直接调阿里云 OpenAPI 上架。 -``` - -### 8.2 状态机 - -![状态机](./diagrams/state_machine.svg) - -每一步把进度写入 `.aliyun-skill-state.json`： -```json -{ - "version": "1.0", - "phase": "API_TEST", - "project_root": "/Users/.../eb-service-api", - "target_class": "RecognizeDriverLicenseController", - "output_dir": ".../skills/output", - "completed_phases": ["INIT", "SOURCE_SCAN", "SERVICE_BOOT"], - "test_cases": [...], - "materials_status": { "01": "done", "03": "pending", ... } -} -``` - -### 8.3 工具能力依赖 -| Claude Code 工具 | 用途 | -|---|---| -| Read | 读源码、读 markdown、读截图 | -| Glob / Grep | 找 Controller / pom / 启动类 | -| Bash | 启动服务（提示）/ curl 调接口 / mvn 编译 | -| WebFetch | 抓阿里云市场审核规范、行业 Logo 参考 | -| WebSearch | 搜阿里云最新政策、同类商品案例 | -| Write / Edit | 生成测试文件 / 材料 markdown / MANIFEST | -| AskUserQuestion | 关键决策点收集（项目路径、价格策略、是否已有 Logo 等） | - -### 8.4 关键算法/流程 - -**8.4.1 源码契约提取** -- 用 Grep 找 `@RequestMapping` / `@PostMapping` / `@RequestBody` -- 解析 Request 类的字段名 + 注释 -- 解析 Response 类同上 -- 输出一个 `ApiContract` JSON 对象供后续步骤使用 - -**8.4.2 自动调用接口** -- 用 Bash + curl 调本地服务 -- 异常用例的入参从模板库取（见 §8.5） -- 比对响应 `code` / `msg` / `data` 是否符合 `CODE_SPECIFICATION.md` 协议 - -**8.4.3 代码建议生成** -- 把当前 Controller 与 `RecognizeDriverLicenseController`（标杆）做结构比对 -- 输出 diff 风格建议：缺少哪个方法、错误码该不该用 BaiduOcrError、等等 - -**8.4.4 材料生成** -- 文本类 → Skill 直接 Write -- 资产类 → 生成"操作指引 README" + 推荐工具链接 -- 已存在的 → 读取 + 模板替换占位符（如 `{服务名}` / `{公司名} / {联系电话}`） - -### 8.4.5 接口测试模板分层（支持非 OCR 接口） -Skill 在源码扫描阶段自动判定接口类型，选择对应模板： - -![模板选择决策树](./diagrams/template_selection.svg) - -**OCR 专用模板**（详见 §8.5.1） -**通用 REST 模板**（详见 §8.5.2） - -开发者也可以在 §4.2 阶段 0 手动指定模板类型。 - -### 8.5 测试用例模板库 - -#### 8.5.1 OCR 通用异常用例集 -- request 为 null -- imageUrlOrBase64 为空 / 非法 URL / 非法 Base64 -- side 非法值 -- side 多种合法别名（face/front/back） -- 平台错误码模拟（需 mock 或灰度环境） -- 平台无回执（断网模拟） -- 平台返回 words_result 为空 -- 平台返回但字段全空 - -#### 8.5.2 通用 REST 异常用例集 -- request body 为空 / 非法 JSON -- 必填字段缺失（基于 Request 类反射推断） -- 字段类型错误（String 传 Number 等） -- 字段长度超限（如有 `@Size` / 注释中"≤N 字符"） -- 鉴权失败（缺失 token / token 错误） -- 限流模拟（如有 `@QPS`） -- 正向请求（开发者提供至少 1 组合法入参示例） -- 不存在的资源（404 验证） -- 方法不允许（HTTP 405 验证） - -> **共通**：两套模板都生成 JUnit 5 风格用例，统一沿用项目现有测试基类。 - -### 8.6 模板与字典 -Skill 自带一组模板文件（首次安装时落到 `~/.claude/skills/aliyun-marketplace/templates/`）： -- EULA 骨架（基于现有 `10.最终用户协议.md` 抽出**章节结构**与**条款类型**，剥离原"银行卡核验"业务正文 → 形成通用骨架；每次上架时 Skill 按当前接口业务 AI 重写业务正文段落） -- 售后服务模板 -- 产品介绍 markdown 骨架（OCR 版 / 通用 REST 版各一） -- Logo README 模板（含尺寸/颜色/设计建议 + 微调操作步骤） -- Logo Prompt 模板（OCR / 工具类 / 金融类 / 通用 API 等行业关键词） -- 阿里云类目 → 必备材料映射表（JSON） -- API 凭据存储：`~/.claude/skills/aliyun-marketplace/credentials.json`（fal.ai / 通义万相 / Stability 的 Key） - ---- - -## 九、交互样例（关键节点，服务式风格） - -> 风格统一：**Skill 先备好，用户只需确认 / 修改 / 跳过**。 - -### 9.1 首次启动（自动推断 + 让用户确认） -``` -Skill: 你好！我来帮你把接口上架到阿里云市场。我先扫了一下你的项目： - - 📁 项目根目录：/Users/.../eb-service-api ← 已自动识别 - 📦 我在 controller/car 找到 2 个候选 Controller： - 1) RecognizeDriverLicenseController（驾驶证识别） - 2) RecognizeDrivingLicenseController（行驶证识别） - 📂 输出目录默认放到 ./skills/output/ - - 你要上架哪个？（默认 1） - - 输入 1 / 2 → 选择 - - 直接回车 → 用默认 (=1) - - skip → 待会决定 -``` - -### 9.2 代码建议（建议但不强制） -``` -Skill: 我扫了 RecognizeXxxController，对照规范有 3 条建议（不强制，你拒绝也可继续）： - - ⚠️ #1 还在 extends BaseController，建议改为 AbstractRecognizeController - 理由：失去父类公共能力（okResult / 反射统计 / Context），每次新接口要重写 - 自动修复：我可以直接帮你改并跑回归测试，5 分钟搞定 - ⚠️ #2 嵌套了 PlatformError，建议删除改用顶级 BaiduOcrError - 理由：错误码字典维护分散，新增码要改三处 - 自动修复：我可以直接删并跑回归测试 - 💡 #3 recognize() 有 95 行，超过规范 80 行上限 - 理由：可读性下降 - 自动修复：可以抽 try/catch 兜底逻辑到单独方法 - - 下一步？ - (A) 全部自动修，跑测试 ← 推荐 - (B) 只修 #1 和 #2，#3 暂不动 - (C) 全部跳过，写入 SUGGESTIONS.md 备查 -``` - -### 9.3 让用户提供产品截图（服务式核心样例） -``` -Skill: 阿里云需要 3~5 张接口调用截图。我已经替你准备好了： - - 📋 已生成 5 组样例请求（写入 ./05_screenshots/postman/RecognizeDriverLicense.postman_collection.json）： - ① 正向：识别正页（影像 = 开源测试图，URL 已埋好） - ② 正向：识别副页 - ③ 异常：side 非法 - ④ 异常：图片格式错 - ⑤ 异常：URL 不可访问 - - 📌 操作步骤（3 分钟）： - 1. 打开 Postman → File → Import → 选我准备的 .json - 2. 跑 5 个请求 - 3. 每个请求结果页 Cmd+Shift+4 截图 - 4. 保存到 ./05_screenshots/ 下，命名 01.png ~ 05.png（我会自动校验） - - 💡 你也可以用 Insomnia / Apifox / curl，我都准备了对应的命令： - - curl 命令：./05_screenshots/curl-commands.sh （直接 chmod +x && ./curl-commands.sh） - - 你打算？ - (1) 现在做 ← 推荐 - (2) 待会做，先跳过（FINAL_REPORT 会提醒你） - (3) 让我自己想办法（FINAL_REPORT 记"用户自理"） -``` - -### 9.4 让用户提供营业执照（服务式 + 链接） -``` -Skill: 12 项资质材料里有一项营业执照。阿里云要求（2026 年）： - - 📋 文件要求： - - 格式：PDF（推荐）/ JPG / PNG - - 大小：≤5MB - - 清晰度：能看清统一社会信用代码 - - 有效期：最新版 - - 📌 获取方式（任选其一）： - - 行政同事邮箱：service@1024api.com - - 手机拍照 → 用以下工具转 PDF： - • CamScanner：https://www.camscanner.com/ ← 推荐 - • macOS 预览：拖入图片 → 文件 → 导出为 PDF - • Smallpdf：https://smallpdf.com/jpg-to-pdf ← 网页版 - - 工商局官网下载：https://www.gsxt.gov.cn/ - - 📌 准备好之后： - - 把文件放到 ./12_special_qualification/营业执照.pdf - - 我会自动校验格式和大小 - - 你打算？ - (1) 我去问行政，5 分钟回来 - (2) 跳过（FINAL_REPORT 标"待补充"，影响上架审核） - (3) 公司还没有，先放一边 -``` - -### 9.5 最终确认（生成前的"补遗"） -``` -Skill: 准备生成最终材料前，我整理了 4 项还没就绪的，给你最后一次机会： - - 1. 📷 05 产品截图（跳过中）—— Postman 包已就绪 - → 选项：(A) 现在做 / (B) 永久跳过 - - 2. 🎨 03 Logo（4 张草稿待选）—— ./03_logo/draft/1.png ~ 4.png - → 选项：(A) 选 #N / (B) 全部不满意，我重新生成 / (C) 我自己出图 - - 3. 📄 12 营业执照（待提供）—— 已给你转换工具链接 - → 选项：(A) 我有了，路径=... / (B) 跳过 - - 4. 💡 代码建议 #3（@author 仍是 "heyu" 占位） - → 选项：(A) 改为 "张三 zhangsan@1024api.com" / (B) 保留 - - 整体决定： - (X) 逐项处理 ← 推荐，每项不超过 3 分钟 - (Y) 1, 3 现在做，2/4 跳过 - (Z) 全部跳过，直接生成材料（这些会写入 FINAL_REPORT 的"待补充"清单） -``` - -### 9.6 失败兜底（不是用户的错） -``` -Skill: 我尝试用 Pollinations.ai 出 Logo，但 3 次都失败了（响应超时）。 - - 📋 我已经记到 FINAL_REPORT 失败项里。下一步建议： - (1) 我换 fal.ai 再试一次 —— 但需要你配 API Key（5 美元额度） - 配置链接：https://fal.ai/dashboard/keys - (2) 我换通义万相 —— 需要阿里云 AK/SK - (3) 用现成的占位 Logo + 文字（我已生成 placeholder.png 在 ./03_logo/） - (4) 跳过，你自己找设计 - - 选哪个？ -``` - -### 9.7 跳过/不知道也能继续 -``` -用户：skip -Skill: 好，本项标记跳过，已记到 FINAL_REPORT。继续下一项 → - -用户：不知道 -Skill: 没事，我给你 3 个常见选择供参考： - 1) 按次计费：0.05 元/次（最常见） - 2) 包月：500 元/月 - 3) 包年：5000 元/年（含 10 万次额度） - - 选一个？或者继续 skip？ -``` - ---- - -## 十、开放问题（决策前请确认） - -| 编号 | 问题 | 我的倾向 | -|---|---|---| -| Q1 | Skill 是否要替开发者执行 `mvn` 命令？还是只给命令让开发者复制粘贴？ | ✅ **已决策（v0.10 更新）：什么都不给**。Skill 只探测服务是否启动，启动方式由开发者自己决定（IDE / docker / mvn / make 都行）。Skill 给命令反而像"教学生用筷子"。详见 §4.4 | -| Q2 | 接口测试需不需要支持 mock 平台（百度返回）？还是只调真实平台？ | **首版只调真实平台**。Mock 复杂度高，等 v2 | -| Q3 | 材料生成的输出目录是否要进 git？ | **加 .gitignore**。材料文件大，且每次会变 | -| Q4 | EULA 中的公司名、服务名等占位符，要不要从 `pom.xml` / `application.yml` 自动提取？ | **是，能自动就自动**，仅未识别项问开发者 | -| Q5 | Logo / 截图这类资产，Skill 要不要尝试用 AI 生成？（DALL·E / Midjourney API） | ✅ **已决策：Logo 用 AI 生成，开发者本地再改**。默认走 Pollinations.ai 免费 API；可配 fal.ai / 通义万相提质。截图不做 AI 生成（多为接口调用过程截图，需真实场景）。详见 §6.2.1 | -| Q6 | 是否支持非 OCR 类接口（如普通 CRUD）？ | ✅ **已决策：支持非 OCR 接口**。测试模板分两套：OCR 专用 + 通用 REST；上架材料 12 项对两类接口都通用，只是产品介绍/规格的模板分行业。详见 §8.4.5、§8.5.2 | -| Q7 | 状态文件 `.aliyun-skill-state.json` 放哪？项目内 or `~/.claude/skills/state/`？ | **项目内**。方便团队成员接力 | -| Q8 | 同一个接口已上架过，二次发版怎么处理？ | **检测到旧 MANIFEST 时进入"增量更新"模式**，只问变化的字段 | -| Q9 | 是否需要支持双语（中英文）商品文案？ | **是**。阿里云有英文版商品库 | -| Q10 | Skill 触发词的边界？比如开发者说"测一下这个 controller"也要进来吗？ | **不要**。仅在出现"阿里云""上架""marketplace"等明确意图时触发 | - ---- - -## 十一、分期交付 - -![分期时间线](./diagrams/timeline.svg) - -### 11.1 排期总览（v0.15 新增 AI 加速版） - -> **假设**：1 名熟悉项目的全职开发，工作日 8 小时；已纳入 20% 风险缓冲。 - -#### A. 传统开发节奏 - -| 阶段 | 内容 | 净工时 | 缓冲 | 实际周期 | -|---|---|---|---|---| -| **Phase 1 MVP** | 端到端骨架，OCR + 通用 REST 各跑通一个接口 | **16 工日** | +20% | **约 4 周** | -| **Phase 2 增强** | 代码建议、报告、共享公共材料、AI Logo 提质 | **6 工日** | +20% | **约 1.5 周** | -| **小计** | Phase 1 + Phase 2 | 22 工日 | — | **约 5~6 周** | - -#### B. AI 辅助开发节奏（v0.15 新增） - -> **假设**：使用 Claude Code 等 AI 编程助手，开发者熟练使用 AI（≥3 个月经验），且**前提条件**全部满足（见 §11.1.2）。 - -| 阶段 | 净工时 | 缓冲 | **实际周期** | -|---|---|---|---| -| **Phase 1 MVP（AI 加速）** | **10 工日** | +20% | **约 12 工作日 = 2.5 周** ✅ | -| **Phase 2 增强（AI 加速）** | **4 工日** | +20% | 约 1 周 | -| **小计** | 14 工日 | — | **约 3.5 周** | - -#### 11.1.1 AI 加速比逐项分析 - -| M# | 任务 | 传统 | AI 加速比 | AI 加速后 | 加速原因 | -|---|---|---|---|---|---| -| M1 | 骨架 + 状态管理 | 2.0 | 1.5x | 1.3 | schema 设计 AI 快，断点续跑测试要时间 | -| M2 | 源码扫描器 | 1.5 | 2.0x | 0.8 | Grep/Read 模式 AI 写得很快 | -| M3 | 服务探测 + 自测 | 2.0 | 1.5x | 1.3 | 用例模板 AI 快，但调试需手动 | -| M4 | JUnit + TEST_REPORT | 1.0 | 2.0x | 0.5 | 纯模板填空，AI 极快 | -| M5 | 规范检索 + 缓存 | 1.0 | 1.5x | 0.7 | WebFetch 逻辑 AI 写得快 | -| **M6** | **12 项材料采集器** | **3.5** | **1.4x** | **2.5** | 每项逻辑独特，AI 加速有限 | -| M7 | 补遗 + FINAL_REPORT | 1.5 | 2.0x | 0.8 | 模板 + AI 写文档很快 | -| M8 | 主动改代码 | 1.5 | 1.3x | 1.2 | diff 逻辑要反复调 | -| M9 | 联调 + Skill 文档 | 2.0 | 1.3x | 1.5 | 联调时间不可压缩 | -| | **Phase 1 合计** | **16.0** | ~**1.6x** | **10.6** | | - -**加上 20% 缓冲 ≈ 12.7 工日 ≈ 12~13 个工作日 = 2.5 周** - -#### 11.1.2 12 天达成的前提条件（缺一不可） - -| 前提 | 说明 | 不满足的后果 | -|---|---|---| -| ✅ **开发者熟练用 AI** | ≥3 个月日常使用 Claude Code 经验 | 加速比降到 1.2x → 需 14~15 天 | -| ✅ **需求文档已冻结** | 本文档 v0.14 状态已确认，开发期间不改大方向 | 改一次需求 = 多 1~2 天 | -| ✅ **环境就绪** | Claude Code 已装、Pollinations 可访问、`mvn` 可用 | 装环境每个 0.5 天 | -| ✅ **测试接口可访问** | 驾驶证识别 + 任一 REST 接口可本地启动 | 加 0.5~1 天 | -| ✅ **没有同时多任务** | 12 个工作日内 80% 时间投入 Skill 开发，不被其他事打断 | 上下文切换损耗 30% | -| ✅ **接受范围收缩预案** | 真出问题立即砍非关键路径（§11.8），不延期 | 否则会拖到 15+ 天 | - -#### 11.1.3 不同人力配置对应周期 - -| 配置 | 传统 | AI 加速 | -|---|---|---| -| 1 人全职（满足 §11.1.2） | 5~6 周 | **12 天 ≈ 2.5 周** ✅ | -| 1 人全职（用 AI 但不熟） | 5~6 周 | ~15 天 ≈ 3 周 | -| 1 人兼职（50%） | 10~12 周 | 5 周 | -| 2 人并行（Skill 主线 + AI/调研单包，都用 AI） | 3~4 周 | **8~10 天 ≈ 2 周** | - -#### 11.1.4 12 天周计划 - -| 天 | 工作内容 | 累计工日 | -|---|---|---| -| Day 1 | M1 骨架 + 状态管理（含 init phase 0） | 1.3 | -| Day 2 | M2 源码扫描 + M5 规范缓存（并行） | 2.8 | -| Day 3 | M3 服务探测 + 自测开搞 | 4.1 | -| Day 4 | M3 收尾 + M4 JUnit 生成器 | 4.6 | -| Day 5 | **M6 启动** —— 03 Logo 反馈循环（最难）| 5.6 | -| Day 6 | M6 续 —— 01/04/09 商品名 + 产品信息 + 商品规格 | 6.6 | -| Day 7 | M6 续 —— 02/05/06/07/08/10/11/12（剩余 8 项）| 7.6 | -| Day 8 | M6 收尾 + M7 启动（FINAL_REPORT 框架） | 8.4 | -| Day 9 | M7 收尾 + M8 主动改代码（低/中风险） | 9.4 | -| Day 10 | M8 收尾 + M9 跑通 OCR 接口 | 10.4 | -| Day 11 | M9 跑通 REST 接口 + Skill README | 11.5 | -| Day 12 | **D4 收官 demo** + 缓冲（处理临时问题）| 12.0 | - -#### 11.1.5 风险预案 - -| 风险 | 触发条件 | 应对 | -|---|---|---| -| Day 5 时 M3 还没完成 | 落后 1 天以上 | 立即砍 REST 测试模板（M3 省 0.5d），保留 OCR | -| Day 8 时 M6 才做完 6 项 | 落后 1.5 天 | 砍 05 Postman / 06 ICP → 退化为"操作指引文本"，省 0.4d | -| Day 11 时 M9 还没跑通 | 已基本失败 | 把 REST 接口 demo 推到 Phase 2，Phase 1 只演 OCR | - -> **底线承诺**：12 天结束时，至少能完整跑通"驾驶证识别"接口的一次 `/aliyun-marketplace`，出 FINAL_REPORT。其他可以推。 - -### 11.2 Phase 1 详细任务分解（16 工日） - -| # | 里程碑 | 工日 | 关键任务 | 依赖 | -|---|---|---|---|---| -| **M1** | Skill 骨架 + 状态管理 | **2.0** | metadata / TRIGGER / `.aliyun-skill-state.json` schema / 断点续跑 / Phase 0 初始化 | — | -| **M2** | 源码扫描器 | **1.5** | Controller/Request/Resp 解析 + 接口契约抽取 + OCR/REST 判定（§8.4.5）+ §5.2 检查项 | M1 | -| **M3** | 服务探测 + 接口自测 | **2.0** | 端口探测（§4.4）+ OCR 8 用例 + REST 9 用例 + 响应断言 | M2 | -| **M4** | JUnit 生成器 + TEST_REPORT | **1.0** | 模板填空 + 输出测试文件 + 报告 markdown | M3 | -| **M5** | 阿里云规范检索 + 缓存 | **1.0** | WebFetch + 7 天缓存 + 失败回退 | M1 | -| **M6** | **12 项材料采集器**（最重） | **3.5** | 逐项实现，详见 §11.3 | M2, M5 | -| **M7** | 阶段 5.5 补遗 + FINAL_REPORT | **1.5** | 未就绪汇总 + 报告 9 节模板 + MANIFEST + 提交清单 | M6 | -| **M8** | 主动代码修改能力（§3.6） | **1.5** | 低风险闷头改 + 中风险给 diff + 改完跑回归 + revert 机制 | M2 | -| **M9** | 端到端联调 + Skill 自身文档 | **2.0** | 跑通驾驶证（OCR）+ 1 个 REST 接口 + Skill README | All | -| | **Phase 1 合计** | **16.0** | | | - -### 11.3 M6 — 12 项材料采集器详细分解（3.5 工日） - -| # | 材料 | 工日 | 难点 | -|---|---|---|---| -| 01 | 商品名（AI 候选 + 阿里云命名规则比对） | 0.3 | 命名规则查抓 | -| 02 | API 前缀（@RequestMapping 抽取） | 0.1 | 简单 | -| 03 | **Logo（Pollinations + 反馈循环 + 展示回退）** | **1.0** | **最复杂**：反馈循环 + 多端展示适配（§6.2.1） | -| 04 | 产品信息（AI 草稿，OCR / REST 双模板） | 0.3 | 简单 | -| 05 | Postman Collection 生成 + 截图操作指引 | 0.4 | 模板化 | -| 06 | 资质与案例（ICP 检测 + 提示） | 0.2 | ICP API 集成可选 | -| 07-08 | 售后服务（复用 + 占位符替换） | 0.2 | 简单 | -| 09 | **商品规格（竞品调研 + 3 套方案 + JSON）** | **0.5** | 竞品 WebFetch + 方案推导（§6.2.3） | -| 10 | EULA（AI 重写业务正文 + 占位符填充） | 0.3 | 防 AI 误改法律条款 | -| 11 | 特殊资质声明（复用 + 业务名替换） | 0.1 | 简单 | -| 12 | 营业执照（要求清单 + PDF 转换工具推荐） | 0.1 | 简单 | -| | **小计** | **3.5** | | - -### 11.4 Phase 2 任务分解（6 工日） - -| # | 任务 | 工日 | 备注 | -|---|---|---|---| -| F-06 | 代码建议自动比对（§5.3 全部 10 项） | 1.5 | OCR 对 `CODE_SPECIFICATION.md`，REST 通用规范 | -| F-14 | 多接口共享公共材料（公司信息、售后、EULA 骨架） | 1.0 | 跨接口缓存层 | -| AI Logo 提质 | 支持配 fal.ai / 通义万相 Key + Prompt 行业模板 | 1.5 | 凭据管理 + 行业关键词字典 | -| 规范刷新 | 7 天缓存自动失效 + 手动 `refresh-spec` | 0.5 | 简单 | -| 优化 + 用户反馈打磨 | 真实接口跑 3 轮收集反馈 | 1.5 | 必要的"实战打磨" | -| | **合计** | **6.0** | | - -### 11.5 关键路径 - -``` -M1 → M2 → M3 → M4 - └→ M6 → M7 → M9 -M5 (并行 M1 之后) -M8 (并行 M2 之后) -``` - -**关键路径**：M1 → M2 → M6 → M7 → M9 = **10.0 工日** -**总长**：16 工日（含等待 / 切换 / M3 M4 串行开销） - -### 11.6 里程碑 demo 节点（按 1 人全职 4 周计） - -| 节点 | 时点 | 可演示能力 | -|---|---|---| -| **D1** | 第 1 周末 | M1 + M2 + M5 完成 → "扫源码 + 契约提取 + 阿里云规范缓存生效" | -| **D2** | 第 2 周末 | M3 + M4 完成 → "跑接口 + 生成 JUnit + 出 TEST_REPORT" | -| **D3** | 第 3 周末 | M6 完成（含 03 Logo / 09 规格 / 10 EULA） → "12 项材料采集器跑通" | -| **D4** | 第 4 周末 | M7 + M8 + M9 完成 → **Phase 1 收官 demo**：完整一次 `/aliyun-marketplace` 出 FINAL_REPORT | - -### 11.7 风险与缓冲已考虑 - -| 风险 | 应对 | -|---|---| -| AI 出图成功率约 80% | M6 #03 已留 1.0 天（含反馈循环 5 轮上限） | -| 阿里云规范爬取失败 | M5 已设兜底逻辑（本地快照） | -| Skill 工具能力限制（如无法渲染 PNG） | 设计了三种展示方式回退（§6.2.1 B） | -| 整体延期 | 20% 缓冲已含在 4 周内；超 1 周延期触发**范围收缩**（见 §11.8）| - -### 11.8 范围收缩预案（超期触发） - -**砍了就不能交付（必须保留）**： -- M1, M2, M3 -- M6 的 10/12 项（01/02/03/04/07/08/09/10/11/12） -- M7 FINAL_REPORT 生成 -- M9 至少跑通 1 个 OCR 接口 - -**实在跑不完可砍（推到 Phase 2）**： -- M4 JUnit 生成 → 退化为"给 curl 脚本" -- M6 中 05 Postman Collection / 06 ICP 检测 → 退化为"给操作指引文本" -- M8 主动代码修改的"中风险 diff"档 → 退化为"只给文本建议" -- M9 第 2 个接口（通用 REST）的端到端验证 - -### Phase 1 必备能力清单（功能维度） -- F-01 ~ F-05, F-07, F-09 ~ F-13 -- **同时支持 OCR + 通用 REST 接口**（两套测试模板） -- **AI Logo 生成**（默认 Pollinations.ai 免费版） -- 材料目录结构 + MANIFEST + FINAL_REPORT 跑通 -- 至少能为：① 驾驶证识别（OCR）② 任一通用 REST 接口 各产出一套完整材料 - -### Phase 2 必备能力清单（功能维度） -- F-06：代码建议自动比对 -- F-08：测试报告 markdown -- F-14：多接口共享公共材料 -- 阿里云规范检索缓存 + 7 天刷新 -- AI Logo 增强：支持配 fal.ai / 通义万相 Key 提质 -- Logo Prompt 模板按行业分类，自动选词 - -### Phase 3（扩展） -- Mock 平台返回的测试支持 -- 直接调阿里云 OpenAPI 提交材料（需要鉴权方案） -- 阿里云审核状态轮询（材料提交后追踪审核进度） - ---- - -## 十二、风险与缓解 - -| 风险 | 等级 | 缓解 | -|---|---|---| -| 阿里云市场政策频繁变更 | 高 | 缓存 + 检索 + 手动刷新命令 | -| 测试图涉及客户真实数据 | 高 | 强制要求开源/合成图，告警提示 | -| AI 生成 Logo 版权争议 | 中 | 默认走可商用模型（Pollinations 基于 FLUX/SD）；产出物标注"AI 生成，使用前请自查权属"；保留 prompt 与生成时间作为证据 | -| AI 生成 Logo 含敏感符号（如阿里 / 腾讯 Logo 误生成） | 中 | Prompt 模板强制加 `--no logo, brand, trademark, text` 等否定词；生成后让开发者确认 | -| 法务模板自动生成有合规风险 | 中 | EULA 业务正文段落由 AI 重写时，**只允许**改写"服务名称 / 业务描述 / 数据范围"等事实陈述部分；**禁止**修改法律条款（权利义务 / 责任限制 / 数据使用 / 终止条款 / 法律适用）；产出物显著标注"建议法务复审" | -| Skill 触发太宽，干扰其他对话 | 中 | description 写紧；SKIP 条款明确 | -| 状态文件被开发者手动删除/破坏 | 低 | 提供 `/aliyun-marketplace 重置` 指令 | -| 不同操作系统命令差异 | 低 | 启动命令按平台分支输出（macOS/Linux/Windows） | -| 非 OCR 接口测试模板覆盖不全 | 中 | 通用 REST 模板首版只覆盖 9 类常见用例；漏覆盖的让开发者补，并提示加入用例库迭代 | - ---- - -## 十三、验收标准 - -Phase 1 上线后，要满足： - -### 13.1 功能指标 -1. 开发者从 `/aliyun-marketplace` 开始，**全程在聊天里**，不离开 Claude Code -2. **30 分钟内** 能为一个全新接口（OCR 或通用 REST）产出 12 项材料中 ≥ 9 项 ✅，剩余项有明确的"待补充"指引 -3. 测试文件可以直接 `mvn test` 跑通至少 5 条正向/异常用例（OCR / REST 两套模板各跑通一次） -4. 二次启动 Skill，能从断点续跑，不重复问已答的问题 -5. 已有的 `skills/` 目录下的材料（图片 + markdown）能被识别并复用，不重复生成 -6. Logo 项默认能 AI 出图至少 3 张，开发者选一张后落到 `03_logo/draft/`，并附本地微调指引 - -### 13.2 非阻塞指标（v0.5 新增） -7. **任何询问都允许跳过**：用户回复 "skip" / "跳过" / "不知道" / 直接回车，Skill 都能继续下一步，不阻塞 -8. **任何代码建议都不强制执行**：用户拒绝后 Skill 记录原因并继续，不重复追问 -9. **最终一定生成 `FINAL_REPORT.md`**，即使上游所有阶段都被跳过： - - 跳过项有清单 - - 拒绝的建议有清单 - - 缺失项有清单（含原因） - - 后续动作清单按 P0/P1/P2 分级 -10. **失败可恢复**：任一阶段失败可单独重跑（`/aliyun-marketplace 重做 阶段5`），不丢已完成数据 - -### 13.3 服务式指标（v0.6 新增） -11. **没有任何"空白提问"**：每次问用户之前，Skill 必须已经准备好可参考的草稿 / 候选项 / 操作步骤；用户只回答"确认 / 修改 / 跳过" -12. **每项需用户提供的素材都附带**：精确要求 + 推荐工具 + 操作步骤 + 文件落地路径 + 自动校验 -13. **每项外部平台操作都附带**：精确链接 + 步骤说明（不让用户自己找） -14. **失败兜底有备选方案**：单一服务失败时 Skill 主动给 2~3 个备选方案，而不是把问题推给用户 -15. **生成材料前一定有"补遗确认"环节**（阶段 5.5），汇总所有未就绪项给用户最后一次机会 - -### 13.4 不逼问指标（v0.8 新增） -16. **不完整内容只建议一次**：用户填了部分内容时，Skill 给一次完整建议（缺什么+为什么+不补的后果），用户忽略就跳过；不允许"再考虑一下"式追问 -17. **同一项追问次数 ≤ 1**：Skill 同一项至多发起 1 次"建议补充" + 1 次"补遗确认"（§4.7.5），合计最多被询问 2 次 -18. **Logo 反馈循环 ≤ 5 轮**：超过 5 轮迭代时主动提示"换 fal.ai 提质 or 先用占位"，避免无意义循环 - -### 13.5 透明失败指标（v0.9 新增） -19. **任何失败必须立即通知用户**：禁止"静默失败 + 仅写日志"；失败发生时必须在对话中明确告知，并附失败原因与备选方案 -20. **每个失败附 ≥ 2 个备选方案**：包括"换服务重试 / 用占位 / 完全跳过"三类 -21. **同一项重试 ≤ 3 次**：超出后强制让用户选备选或跳过 -22. **失败可在 FINAL_REPORT 完整复盘**：每个失败项含错误信息、已尝试方案、用户最终选择、重试建议链接 - -### 13.6 主动改代码指标（v0.11 新增） -23. **低风险改动直接落地**：用户在聊天中明确给出值（@author / 商品名 / Logo 选择等）的，Skill 直接 Edit 代码，不要让用户自己改文件 -24. **中风险改动先给 diff 再落地**：架构性建议（继承变更 / 枚举替换 / 方法抽取）必须先展示 unified diff 让用户确认 -25. **高风险改动只给建议不主动改**：涉及对外契约（URL / 字段名 / HTTP 方法）的，只展示影响范围让用户决定 -26. **改完必跑回归检查**：编译 / 单测 / lint（环境支持时），失败提供 revert 命令 -27. **代码变更明细计入 FINAL_REPORT**：新增"本次 Skill 修改了哪些代码"小节 - ---- - -> **文档版本**：v0.15.1（§11.1 AI 加速版 + timeline 图同步更新为 12 工作日 / Day 1-12 计划） -> **作者**：heyu -> **创建日期**：2026-06-09 -> **最后更新**：2026-06-09（v0.3 嵌入可视化图） -> **状态**：可进入 Phase 1 开发 -> **下一步**：Phase 1 开发启动 -> -> **配图清单**（D2 源在 `./diagrams/*.d2`，可手动调整后重渲）： -> - `./aliyun_skill_flow.svg` — §4 端到端总览 -> - `./diagrams/actors.svg` — §2 角色与交互 -> - `./diagrams/materials_matrix.svg` — §6 12 项材料分类 -> - `./diagrams/sequence_logo.svg` — §6.2.1 Logo 生成时序 -> - `./diagrams/state_machine.svg` — §8.2 状态机 -> - `./diagrams/template_selection.svg` — §8.4.5 模板选择决策树 -> - `./diagrams/sequence_init.svg` — §9.1 首次启动时序 -> - `./diagrams/timeline.svg` — §11 分期时间线 -> -> **重新渲染命令**： -> ```bash -> cd controller/car/skills/diagrams -> for f in *.d2; do d2 --pad=40 --layout=elk "$f" "${f%.d2}.svg"; done -> ``` diff --git a/api-web/api-interface/src/main/java/com/heyu/api/controller/car/skills/aliyun_skill_flow.d2 b/api-web/api-interface/src/main/java/com/heyu/api/controller/car/skills/aliyun_skill_flow.d2 deleted file mode 100644 index 4943d69..0000000 --- a/api-web/api-interface/src/main/java/com/heyu/api/controller/car/skills/aliyun_skill_flow.d2 +++ /dev/null @@ -1,41 +0,0 @@ -direction: right - -classes: { - trigger: { - shape: oval - style: {fill: "#fff3e0"; stroke: "#fb8c00"; bold: true; font-size: 16} - } - done: { - shape: oval - style: {fill: "#c8e6c9"; stroke: "#43a047"; bold: true; font-size: 16} - } - s1: { - style: {fill: "#e3f2fd"; stroke: "#1e88e5"; stroke-width: 3; border-radius: 12; bold: true; font-size: 18; shadow: true} - } - s2: { - style: {fill: "#f3e5f5"; stroke: "#8e24aa"; stroke-width: 3; border-radius: 12; bold: true; font-size: 18; shadow: true} - } - s3: { - style: {fill: "#e8f5e9"; stroke: "#43a047"; stroke-width: 3; border-radius: 12; bold: true; font-size: 18; shadow: true} - } -} - -trigger: 触发\n/aliyun-marketplace {class: trigger} - -s1: 阶段一\nAPI 自测\n(检测服务→调接口) {class: s1} -s2: 阶段二\n测试沉淀 {class: s2} -s3: 阶段三\n上架材料 {class: s3} -done: 材料就绪\n→ 阿里云 {class: done} - -trigger -> s1: 启动 -s1 -> s2: 接口可用 -s2 -> s3: 测试就绪 -s3 -> done: 报告生成 - -note: |md -**非阻塞 · 服务式 · 不逼问 · 透明失败** -断点续跑：`/aliyun-marketplace 继续` -| { - near: bottom-center - style: {fill: "#fff9c4"; stroke: "#f9a825"; border-radius: 6; italic: true; font-size: 14} -} diff --git a/api-web/api-interface/src/main/java/com/heyu/api/controller/car/skills/aliyun_skill_flow.png b/api-web/api-interface/src/main/java/com/heyu/api/controller/car/skills/aliyun_skill_flow.png deleted file mode 100644 index 834af36..0000000 Binary files a/api-web/api-interface/src/main/java/com/heyu/api/controller/car/skills/aliyun_skill_flow.png and /dev/null differ diff --git a/api-web/api-interface/src/main/java/com/heyu/api/controller/car/skills/aliyun_skill_flow.svg b/api-web/api-interface/src/main/java/com/heyu/api/controller/car/skills/aliyun_skill_flow.svg deleted file mode 100644 index 633cd71..0000000 --- a/api-web/api-interface/src/main/java/com/heyu/api/controller/car/skills/aliyun_skill_flow.svg +++ /dev/null @@ -1,874 +0,0 @@ - - - - - - - - -触发/aliyun-marketplace阶段一API 自测(检测服务→调接口)阶段二测试沉淀阶段三上架材料材料就绪→ 阿里云

非阻塞 · 服务式 · 不逼问 · 透明失败 -断点续跑：/aliyun-marketplace 继续

-
 启动接口可用测试就绪报告生成 - - - - - - - - - - - - diff --git a/api-web/api-interface/src/main/java/com/heyu/api/controller/car/skills/diagrams/actors.d2 b/api-web/api-interface/src/main/java/com/heyu/api/controller/car/skills/diagrams/actors.d2 deleted file mode 100644 index 76976b5..0000000 --- a/api-web/api-interface/src/main/java/com/heyu/api/controller/car/skills/diagrams/actors.d2 +++ /dev/null @@ -1,35 +0,0 @@ -direction: down - -classes: { - dev: { - shape: person - style: {fill: "#fff3e0"; stroke: "#fb8c00"} - } - skill: { - style: {fill: "#dceefb"; stroke: "#4A90D9"; border-radius: 8} - } - ops: { - shape: person - style: {fill: "#f3e5f5"; stroke: "#8e24aa"} - } -} - -dev: 后端开发\n（主交互入口） {class: dev} - -skill: aliyun-marketplace Skill { - class: skill - inner: |md -- 主动询问 -- 检索阿里云规范 -- 生成测试 + 材料 -| { - style: {fill: transparent; stroke: transparent} - } -} - -ops: 产品 / 运营\n（提供文案、定价、客服信息） {class: ops} - -dev -> skill: 启动 / 回答问题 -skill -> dev: 提问 / 给建议 / 产出文件 -dev -> ops: 代问业务字段 -ops -> dev: 提供材料 diff --git a/api-web/api-interface/src/main/java/com/heyu/api/controller/car/skills/diagrams/actors.png b/api-web/api-interface/src/main/java/com/heyu/api/controller/car/skills/diagrams/actors.png deleted file mode 100644 index a0a5519..0000000 Binary files a/api-web/api-interface/src/main/java/com/heyu/api/controller/car/skills/diagrams/actors.png and /dev/null differ diff --git a/api-web/api-interface/src/main/java/com/heyu/api/controller/car/skills/diagrams/actors.svg b/api-web/api-interface/src/main/java/com/heyu/api/controller/car/skills/diagrams/actors.svg deleted file mode 100644 index 7152ed4..0000000 --- a/api-web/api-interface/src/main/java/com/heyu/api/controller/car/skills/diagrams/actors.svg +++ /dev/null @@ -1,860 +0,0 @@ -后端开发（主交互入口）aliyun-marketplace Skill产品 / 运营（提供文案、定价、客服信息）
    -
  • 主动询问
    • -
  • 检索阿里云规范
    • -
  • 生成测试 + 材料
    • -
-
 启动 / 回答问题提问 / 给建议 / 产出文件代问业务字段提供材料 - - - - - - - - - - diff --git a/api-web/api-interface/src/main/java/com/heyu/api/controller/car/skills/diagrams/materials_matrix.d2 b/api-web/api-interface/src/main/java/com/heyu/api/controller/car/skills/diagrams/materials_matrix.d2 deleted file mode 100644 index 1b0c2c9..0000000 --- a/api-web/api-interface/src/main/java/com/heyu/api/controller/car/skills/diagrams/materials_matrix.d2 +++ /dev/null @@ -1,54 +0,0 @@ -direction: down - -vars: { - c-auto: "#e8f5e9" - c-reuse: "#fff8e1" - c-ai: "#e3f2fd" - c-ask: "#fce4ec" -} - -title: 12 项上架材料 — 按生成方式分类 { - near: top-center - shape: text - style: {font-size: 22; bold: true} -} - -matrix: { - grid-columns: 1 - - auto: 自动提取 · 1 项 { - style: {fill: ${c-auto}; stroke: "#43a047"; border-radius: 10} - list: |md -**02** API 访问前缀 -| {style: {fill: transparent; stroke: transparent}} - } - - reuse: 复用既有 · 3 项 { - style: {fill: ${c-reuse}; stroke: "#fbc02d"; border-radius: 10} - list: |md -**07** 售后服务 -**08** 售后服务范围 -**11** 特殊商品资质声明 -| {style: {fill: transparent; stroke: transparent}} - } - - ai: AI 生成 · 3 项 { - style: {fill: ${c-ai}; stroke: "#1e88e5"; border-radius: 10} - list: |md -**03** 商品 Logo（3~5 张草稿） -**04** 产品信息（草稿） -**10** EULA（骨架沿用 + 业务正文重写） -| {style: {fill: transparent; stroke: transparent}} - } - - ask: 询问开发者 · 5 项 { - style: {fill: ${c-ask}; stroke: "#e91e63"; border-radius: 10} - list: |md -**01** 商品名称 -**05** 产品截图 -**06** 资质与案例 -**09** 商品规格 -**12** 特殊商品资质材料 -| {style: {fill: transparent; stroke: transparent}} - } -} diff --git a/api-web/api-interface/src/main/java/com/heyu/api/controller/car/skills/diagrams/materials_matrix.png b/api-web/api-interface/src/main/java/com/heyu/api/controller/car/skills/diagrams/materials_matrix.png deleted file mode 100644 index d05dfdf..0000000 Binary files a/api-web/api-interface/src/main/java/com/heyu/api/controller/car/skills/diagrams/materials_matrix.png and /dev/null differ diff --git a/api-web/api-interface/src/main/java/com/heyu/api/controller/car/skills/diagrams/materials_matrix.svg b/api-web/api-interface/src/main/java/com/heyu/api/controller/car/skills/diagrams/materials_matrix.svg deleted file mode 100644 index dbb75f9..0000000 --- a/api-web/api-interface/src/main/java/com/heyu/api/controller/car/skills/diagrams/materials_matrix.svg +++ /dev/null @@ -1,862 +0,0 @@ -12 项上架材料 — 按生成方式分类matrix自动提取 · 1 项复用既有 · 3 项AI 生成 · 3 项询问开发者 · 5 项

02 API 访问前缀

-

07 售后服务 -08 售后服务范围 -11 特殊商品资质声明

-

03 商品 Logo（3~5 张草稿） -04 产品信息（草稿） -10 EULA（骨架沿用 + 业务正文重写）

-

01 商品名称 -05 产品截图 -06 资质与案例 -09 商品规格 -12 特殊商品资质材料

-
 - - - - - - - - - - - - diff --git a/api-web/api-interface/src/main/java/com/heyu/api/controller/car/skills/diagrams/sequence_init.d2 b/api-web/api-interface/src/main/java/com/heyu/api/controller/car/skills/diagrams/sequence_init.d2 deleted file mode 100644 index b244638..0000000 --- a/api-web/api-interface/src/main/java/com/heyu/api/controller/car/skills/diagrams/sequence_init.d2 +++ /dev/null @@ -1,15 +0,0 @@ -shape: sequence_diagram - -dev: 开发者 -skill: Skill -fs: 文件系统 -state: 状态文件 - -dev -> skill: "/aliyun-marketplace" -skill -> fs: 扫 controller/ 找候选类 -fs -> skill: 返回类列表 -skill -> dev: 项目路径? 目标类? 输出目录? -dev -> skill: 回答 -skill -> fs: 创建输出目录 -skill -> state: 写入 INIT 完成 -skill -> dev: ✅ 初始化完成\n进入阶段 1 源码扫描 diff --git a/api-web/api-interface/src/main/java/com/heyu/api/controller/car/skills/diagrams/sequence_init.png b/api-web/api-interface/src/main/java/com/heyu/api/controller/car/skills/diagrams/sequence_init.png deleted file mode 100644 index 6996a1c..0000000 Binary files a/api-web/api-interface/src/main/java/com/heyu/api/controller/car/skills/diagrams/sequence_init.png and /dev/null differ diff --git a/api-web/api-interface/src/main/java/com/heyu/api/controller/car/skills/diagrams/sequence_init.svg b/api-web/api-interface/src/main/java/com/heyu/api/controller/car/skills/diagrams/sequence_init.svg deleted file mode 100644 index 83311cc..0000000 --- a/api-web/api-interface/src/main/java/com/heyu/api/controller/car/skills/diagrams/sequence_init.svg +++ /dev/null @@ -1,113 +0,0 @@ -开发者Skill文件系统状态文件 /aliyun-marketplace扫 controller/ 找候选类返回类列表项目路径? 目标类? 输出目录?回答创建输出目录写入 INIT 完成✅ 初始化完成进入阶段 1 源码扫描 - - - - - - - - - - - - - - diff --git a/api-web/api-interface/src/main/java/com/heyu/api/controller/car/skills/diagrams/sequence_logo.d2 b/api-web/api-interface/src/main/java/com/heyu/api/controller/car/skills/diagrams/sequence_logo.d2 deleted file mode 100644 index 7a6de13..0000000 --- a/api-web/api-interface/src/main/java/com/heyu/api/controller/car/skills/diagrams/sequence_logo.d2 +++ /dev/null @@ -1,37 +0,0 @@ -shape: sequence_diagram - -dev: 开发者 -skill: Skill -ai: 图像 API\n(Pollinations.ai) -fs: 文件系统 - -# === A. 生成 === -skill -> skill: 基于商品名/注释\n撰写 4 套 Prompt（4 风格） -skill -> ai: 并发出图请求 ×4 -ai -> skill: 返回 4 张 PNG -skill -> fs: 落到 03_logo/draft/01~04.png\n+ preview.html - -# === B. 展示（适配环境） === -skill -> dev: 展示方式三选一：\n① 对话内联缩略图\n② 给文件路径 + open 命令\n③ preview.html 一键浏览器打开 - -# === C. 反馈循环 === -dev -> skill: "都太花了，要简洁单色蓝" -skill -> skill: 调整 Prompt：\n极简 + 单色蓝 + 几何 -skill -> ai: 重新出图 ×4 -ai -> skill: 返回新 4 张 -skill -> dev: 再次展示 - -dev -> skill: "#2 不错，加强汽车元素" -skill -> ai: 围绕 #2 出变体 ×4 -ai -> skill: 返回 4 张变体 -skill -> dev: 再次展示 - -dev -> skill: "#3 就这个，定稿" - -# === D. 定稿 + 可选微调 === -skill -> fs: 复制到 03_logo/final/\nlogo-256.png-pre.png -skill -> dev: 是否本地微调？\n推荐 Photopea (网页版) -dev -> dev: (可选) 本地微调 -dev -> fs: 覆盖 logo-256.png -skill -> fs: 校验尺寸/格式/大小 -skill -> dev: ✅ Logo 就绪 diff --git a/api-web/api-interface/src/main/java/com/heyu/api/controller/car/skills/diagrams/sequence_logo.png b/api-web/api-interface/src/main/java/com/heyu/api/controller/car/skills/diagrams/sequence_logo.png deleted file mode 100644 index e6bf392..0000000 Binary files a/api-web/api-interface/src/main/java/com/heyu/api/controller/car/skills/diagrams/sequence_logo.png and /dev/null differ diff --git a/api-web/api-interface/src/main/java/com/heyu/api/controller/car/skills/diagrams/sequence_logo.svg b/api-web/api-interface/src/main/java/com/heyu/api/controller/car/skills/diagrams/sequence_logo.svg deleted file mode 100644 index 8e92cfb..0000000 --- a/api-web/api-interface/src/main/java/com/heyu/api/controller/car/skills/diagrams/sequence_logo.svg +++ /dev/null @@ -1,126 +0,0 @@ -开发者Skill图像 API(Pollinations.ai)文件系统 基于商品名/注释撰写 4 套 Prompt（4 风格）并发出图请求 ×4返回 4 张 PNG落到 03_logo/draft/01~04.png+ preview.html展示方式三选一：① 对话内联缩略图② 给文件路径 + open 命令③ preview.html 一键浏览器打开都太花了，要简洁单色蓝调整 Prompt：极简 + 单色蓝 + 几何重新出图 ×4返回新 4 张再次展示#2 不错，加强汽车元素围绕返回 4 张变体再次展示#3 就这个，定稿复制到 03_logo/final/logo-256.png-pre.png是否本地微调？推荐 Photopea (网页版)(可选) 本地微调覆盖 logo-256.png校验尺寸/格式/大小✅ Logo 就绪 - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/api-web/api-interface/src/main/java/com/heyu/api/controller/car/skills/diagrams/state_machine.d2 b/api-web/api-interface/src/main/java/com/heyu/api/controller/car/skills/diagrams/state_machine.d2 deleted file mode 100644 index ae07b61..0000000 --- a/api-web/api-interface/src/main/java/com/heyu/api/controller/car/skills/diagrams/state_machine.d2 +++ /dev/null @@ -1,44 +0,0 @@ -direction: down - -classes: { - state: { - style: {fill: "#dceefb"; stroke: "#4A90D9"; border-radius: 20} - } - terminal: { - style: {fill: "#c8e6c9"; stroke: "#43a047"; border-radius: 20; bold: true} - } - start: { - shape: circle - style: {fill: "#212121"; stroke: "#000"} - } -} - -start: " " {class: start} -INIT: INIT\n初始化收集 {class: state} -SOURCE_SCAN: SOURCE_SCAN\n源码扫描 {class: state} -SERVICE_BOOT: SERVICE_BOOT\n启动引导 {class: state} -API_TEST: API_TEST\n接口自测 {class: state} -TEST_GEN: TEST_GEN\n生成测试用例 {class: state} -MATERIAL_COLLECT: MATERIAL_COLLECT\n12 项材料采集 {class: state} -PACKAGE: PACKAGE\n打包 + MANIFEST {class: state} -DONE: DONE\n完成 ✅ {class: terminal} - -start -> INIT -INIT -> SOURCE_SCAN -SOURCE_SCAN -> SERVICE_BOOT -SERVICE_BOOT -> API_TEST -API_TEST -> TEST_GEN: 用例全过 -API_TEST -> API_TEST: 发现 bug\n修复后回归 -TEST_GEN -> MATERIAL_COLLECT -MATERIAL_COLLECT -> PACKAGE -PACKAGE -> DONE - -# 任意节点都可断点续跑 -note: |md -**全程非阻塞**：用户跳过/拒绝任何步骤都可继续 -**断点续跑**：每个状态写入 .aliyun-skill-state.json -**终态保底**：无论前面情况如何，PACKAGE 阶段必出 FINAL_REPORT.md -| { - near: bottom-center - style: {fill: "#fff9c4"; stroke: "#f9a825"; border-radius: 6; italic: true} -} diff --git a/api-web/api-interface/src/main/java/com/heyu/api/controller/car/skills/diagrams/state_machine.png b/api-web/api-interface/src/main/java/com/heyu/api/controller/car/skills/diagrams/state_machine.png deleted file mode 100644 index abba09d..0000000 Binary files a/api-web/api-interface/src/main/java/com/heyu/api/controller/car/skills/diagrams/state_machine.png and /dev/null differ diff --git a/api-web/api-interface/src/main/java/com/heyu/api/controller/car/skills/diagrams/state_machine.svg b/api-web/api-interface/src/main/java/com/heyu/api/controller/car/skills/diagrams/state_machine.svg deleted file mode 100644 index c98208f..0000000 --- a/api-web/api-interface/src/main/java/com/heyu/api/controller/car/skills/diagrams/state_machine.svg +++ /dev/null @@ -1,862 +0,0 @@ - INIT初始化收集SOURCE_SCAN源码扫描SERVICE_BOOT启动引导API_TEST接口自测TEST_GEN生成测试用例MATERIAL_COLLECT12 项材料采集PACKAGE打包 + MANIFESTDONE完成 ✅

全程非阻塞：用户跳过/拒绝任何步骤都可继续 -断点续跑：每个状态写入 .aliyun-skill-state.json -终态保底：无论前面情况如何，PACKAGE 阶段必出 FINAL_REPORT.md

-
 用例全过发现 bug修复后回归 - - - - - - - - - - - - - - diff --git a/api-web/api-interface/src/main/java/com/heyu/api/controller/car/skills/diagrams/template_selection.d2 b/api-web/api-interface/src/main/java/com/heyu/api/controller/car/skills/diagrams/template_selection.d2 deleted file mode 100644 index 0af150a..0000000 --- a/api-web/api-interface/src/main/java/com/heyu/api/controller/car/skills/diagrams/template_selection.d2 +++ /dev/null @@ -1,39 +0,0 @@ -direction: down - -classes: { - step: { - style: {fill: "#dceefb"; stroke: "#4A90D9"; border-radius: 8} - } - decision: { - shape: diamond - style: {fill: "#fffde7"; stroke: "#fbc02d"} - } - ocr: { - style: {fill: "#e8f5e9"; stroke: "#43a047"; border-radius: 8; bold: true} - } - rest: { - style: {fill: "#fce4ec"; stroke: "#e91e63"; border-radius: 8; bold: true} - } -} - -scan: 源码扫描\n读 Controller 类 {class: step} -check_parent: 继承 AbstractRecognizeController? {class: decision} -check_keyword: 含 OCR/识别/核验关键词? {class: decision} - -ocr_template: 使用 OCR 模板\n8 条 OCR 专用用例 {class: ocr} -rest_template: 使用通用 REST 模板\n9 条通用用例 {class: rest} - -scan -> check_parent -check_parent -> ocr_template: 是 -check_parent -> check_keyword: 否 -check_keyword -> ocr_template: 是 -check_keyword -> rest_template: 否 - -manual_override: |md -**开发者可手动覆盖**：在阶段 0 初始化时指定 template = ocr 或 rest -| { - style: {fill: "#fff9c4"; stroke: "#f9a825"; border-radius: 6; italic: true} -} - -ocr_template -> manual_override: 覆盖 -rest_template -> manual_override: 覆盖 diff --git a/api-web/api-interface/src/main/java/com/heyu/api/controller/car/skills/diagrams/template_selection.png b/api-web/api-interface/src/main/java/com/heyu/api/controller/car/skills/diagrams/template_selection.png deleted file mode 100644 index 69b3f80..0000000 Binary files a/api-web/api-interface/src/main/java/com/heyu/api/controller/car/skills/diagrams/template_selection.png and /dev/null differ diff --git a/api-web/api-interface/src/main/java/com/heyu/api/controller/car/skills/diagrams/template_selection.svg b/api-web/api-interface/src/main/java/com/heyu/api/controller/car/skills/diagrams/template_selection.svg deleted file mode 100644 index eebea78..0000000 --- a/api-web/api-interface/src/main/java/com/heyu/api/controller/car/skills/diagrams/template_selection.svg +++ /dev/null @@ -1,860 +0,0 @@ -源码扫描读 Controller 类继承 AbstractRecognizeController?含 OCR/识别/核验关键词?使用 OCR 模板8 条 OCR 专用用例使用通用 REST 模板9 条通用用例

开发者可手动覆盖：在阶段 0 初始化时指定 template = ocr 或 rest

-
 是否是否覆盖覆盖 - - - - - - - - - - - - - - diff --git a/api-web/api-interface/src/main/java/com/heyu/api/controller/car/skills/diagrams/timeline.d2 b/api-web/api-interface/src/main/java/com/heyu/api/controller/car/skills/diagrams/timeline.d2 deleted file mode 100644 index 7bddef4..0000000 --- a/api-web/api-interface/src/main/java/com/heyu/api/controller/car/skills/diagrams/timeline.d2 +++ /dev/null @@ -1,95 +0,0 @@ -direction: down - -classes: { - w1: {style: {fill: "#e3f2fd"; stroke: "#1565c0"; border-radius: 8; bold: true}} - w2: {style: {fill: "#fff8e1"; stroke: "#f9a825"; border-radius: 8; bold: true}} - w3: {style: {fill: "#fce4ec"; stroke: "#c2185b"; border-radius: 8; bold: true}} - w4: {style: {fill: "#c8e6c9"; stroke: "#388e3c"; border-radius: 8; bold: true}} - p2: {style: {fill: "#e1bee7"; stroke: "#7b1fa2"; border-radius: 8; bold: true}} - p3: {style: {fill: "#cfd8dc"; stroke: "#455a64"; border-radius: 8; bold: true}} - phaseframe: {style: {fill: "#fafafa"; stroke-width: 2; border-radius: 12}} -} - -title: AI 加速版 · Phase 1 = 12 工作日（2.5 周）· Phase 2 = 5 工作日 { - shape: text - style: {font-size: 20; bold: true} -} - -subtitle: 净工时 14 工日（传统 22 工日，AI 加速比约 1.6x） { - shape: text - style: {font-size: 14; italic: true; font-color: "#666"} -} - -phase1: Phase 1 · MVP · 12 工作日（含 20% 缓冲） { - class: phaseframe - style.stroke: "#1565c0" - - week1: Day 1-4（基础设施） { - class: w1 - body: |md -**Day 1** M1 骨架 + 状态 (1.3d) -**Day 2** M2 扫描 + M5 缓存 (1.5d) -**Day 3** M3 服务探测 + 自测启动 -**Day 4** M3 收尾 + M4 JUnit (0.5d) - -✅ D1/D2 demo：契约提取 + 测试就绪 -| {style: {fill: transparent; stroke: transparent}} - } - - week2: Day 5-8（材料采集 + 报告） { - class: w2 - body: |md -**Day 5** M6 启动 · 03 Logo 反馈循环 (1.0d) -**Day 6** M6 续 · 01/04/09 商品名+介绍+规格 -**Day 7** M6 续 · 02/05/06/07/08/10/11/12 八项 -**Day 8** M6 收尾 + M7 FINAL_REPORT 框架 - -✅ D3 demo：12 项材料跑通 -| {style: {fill: transparent; stroke: transparent}} - } - - week3: Day 9-12（联调 + 收官） { - class: w3 - body: |md -**Day 9** M7 收尾 + M8 改代码 (低/中风险) -**Day 10** M8 收尾 + M9 跑通 OCR -**Day 11** M9 跑通 REST + Skill README -**Day 12** D4 收官 demo + 缓冲 - -✅ Phase 1 收官：完整 /aliyun-marketplace -| {style: {fill: transparent; stroke: transparent}} - } - - week1 -> week2 -> week3 -} - -phase2: Phase 2 · 增强 · 5 工作日（约 1 周） { - class: phaseframe - style.stroke: "#7b1fa2" - - body: |md -代码建议自动比对 (1.0d) · 多接口共享 (0.7d) · AI Logo 提质 (1.0d) -规范刷新 (0.3d) · 实战打磨 (1.0d) -| {style: {fill: transparent; stroke: transparent}} -} - -phase3: Phase 3 · 扩展 · 待规划 { - class: phaseframe - style.stroke: "#455a64" - - body: |md -Mock 平台测试 · 阿里云 OpenAPI 自动提交 · 审核状态轮询 -| {style: {fill: transparent; stroke: transparent}} -} - -title -> subtitle -> phase1 -> phase2 -> phase3 - -note: |md -**关键路径** M1→M2→M6→M7→M9 -**6 项前提条件**（§11.1.2）缺一不可 -**底线承诺** 第 12 天至少跑通 OCR 接口出 FINAL_REPORT -**风险预案** Day 5/8/11 卡壳即触发范围收缩 -| { - near: bottom-center - style: {fill: "#fff9c4"; stroke: "#f9a825"; border-radius: 6; italic: true} -} diff --git a/api-web/api-interface/src/main/java/com/heyu/api/controller/car/skills/diagrams/timeline.png b/api-web/api-interface/src/main/java/com/heyu/api/controller/car/skills/diagrams/timeline.png deleted file mode 100644 index 08bb4cc..0000000 Binary files a/api-web/api-interface/src/main/java/com/heyu/api/controller/car/skills/diagrams/timeline.png and /dev/null differ diff --git a/api-web/api-interface/src/main/java/com/heyu/api/controller/car/skills/diagrams/timeline.svg b/api-web/api-interface/src/main/java/com/heyu/api/controller/car/skills/diagrams/timeline.svg deleted file mode 100644 index c85850e..0000000 --- a/api-web/api-interface/src/main/java/com/heyu/api/controller/car/skills/diagrams/timeline.svg +++ /dev/null @@ -1,883 +0,0 @@ -AI 加速版 · Phase 1 = 12 工作日（2.5 周）· Phase 2 = 5 工作日净工时 14 工日（传统 22 工日，AI 加速比约 1.6x）Phase 1 · MVP · 12 工作日（含 20% 缓冲）Phase 2 · 增强 · 5 工作日（约 1 周）Phase 3 · 扩展 · 待规划

关键路径 M1→M2→M6→M7→M9 -6 项前提条件（§11.1.2）缺一不可 -底线承诺 第 12 天至少跑通 OCR 接口出 FINAL_REPORT -风险预案 Day 5/8/11 卡壳即触发范围收缩

-
Day 1-4（基础设施）Day 5-8（材料采集 + 报告）Day 9-12（联调 + 收官）

代码建议自动比对 (1.0d) · 多接口共享 (0.7d) · AI Logo 提质 (1.0d) -规范刷新 (0.3d) · 实战打磨 (1.0d)

-

Mock 平台测试 · 阿里云 OpenAPI 自动提交 · 审核状态轮询

-

Day 1 M1 骨架 + 状态 (1.3d) -Day 2 M2 扫描 + M5 缓存 (1.5d) -Day 3 M3 服务探测 + 自测启动 -Day 4 M3 收尾 + M4 JUnit (0.5d)

-

✅ D1/D2 demo：契约提取 + 测试就绪

-

Day 5 M6 启动 · 03 Logo 反馈循环 (1.0d) -Day 6 M6 续 · 01/04/09 商品名+介绍+规格 -Day 7 M6 续 · 02/05/06/07/08/10/11/12 八项 -Day 8 M6 收尾 + M7 FINAL_REPORT 框架

-

✅ D3 demo：12 项材料跑通

-

Day 9 M7 收尾 + M8 改代码 (低/中风险) -Day 10 M8 收尾 + M9 跑通 OCR -Day 11 M9 跑通 REST + Skill README -Day 12 D4 收官 demo + 缓冲

-

✅ Phase 1 收官：完整 /aliyun-marketplace

-
 - - - - - - - - - - - - - - - -