magic 开发增强技能#

这是一份面向 magic-api 实战开发 的本地技能入口。

它不重复展开完整教程，而是把 4 个本地仓库和 references/ 下的资料组织成一条更适合 Claude 使用的检索路径： 先判断问题类型，再去最合适的样例、源码或审查文档。

这份 skill 适合处理什么问题#

优先用于这些场景：

• 写 .ms 接口、CRUD、分页、事务、文件响应
• 理解 db / request / response / http 等模块怎么工作
• 做自定义模块、函数、扩展方法、provider、interceptor、starter
• 对照 example 和源码排查“不生效 / 报错 / 行为不一致”
• 分析 magic 版本升级影响，输出审查结论和改造方案

四个仓库怎么分工#

先记住最短检索顺序：

• magic-api：框架主实现，先看自动配置、资源加载、内置模块、扩展注册
• magic-script：脚本语言与运行时，先看编译、执行、 import、 exit、上下文变量
• magic-api-example：现成 .ms 样例、扩展模板、Spring Boot 示例配置
• magic-api-plugin：插件 / starter 做法，适合对照自动配置和配置元数据

常用入口：

• 自动配置入口： magic-api/magic-api-spring-boot-starter/src/main/java/org/ssssssss/magicapi/spring/boot/starter/MagicAPIAutoConfiguration.java
• 配置定义： magic-api/magic-api/src/main/java/org/ssssssss/magicapi/core/config/MagicAPIProperties.java
• 脚本运行时： magic-script/src/main/java/org/ssssssss/script/MagicScript.java
• 上下文变量： magic-script/src/main/java/org/ssssssss/script/MagicScriptContext.java
• 示例配置与扩展入口： magic-api-example/src/main/resources/application.yml、 magic-api-example/src/main/java/org/ssssssss/example/configuration/MagicAPIConfiguration.java

按目录找入口时，先看 仓库目录导航。

Claude 使用这份 skill 的回答策略#

默认按下面顺序回答：

1. 先判断问题类型：现成写法 / 原理 / 排障 / 二开 / 插件 / 升版
2. 先给最短结论：先回答“怎么做”或“先查哪里”
3. 能给样例就先给样例：优先 .ms 样例和 example 扩展类
4. 再补源码依据：需要解释原理时再回到 magic-api / magic-script
5. 排障先给排查顺序：先说配置、资源、模块、运行时各查什么
6. 二开先判断扩展点类型：模块 / 函数 / 扩展方法 / provider / interceptor / starter
7. 升版先识别版本与使用面：先看当前版本、目标版本、脚本/扩展/插件使用范围，再给建议

如果要展开具体回答结构，先看 回答组织手册。

什么时候先看哪组资料#

1. 入门与现成示例#

先看这组：当你要 马上给脚本、配置或业务示例。

• magic-script 语法参考
• 数据库操作参考
• 业务场景示例

2. 源码与扩展#

先看这组：当你要 解释原理、定位实现、判断扩展点。

• 源码架构与入口
• 模块与扩展开发
• magic-script 语法与运行时
• 示例与插件对照

3. 检索与回答#

先看这组：当你要 快速决定先读哪份源码、先怎么排查、怎么组织答案。

• 常见提问与源码/样例导航
• 故障排查导航
• 回答组织手册
• 仓库目录导航

4. 升版审查#

先看这组：当你要 分析用户项目升级影响并输出审查结论。

推荐顺序： quick-prompt -> checklist -> template -> example，必要时再补 upgrade-migration-guide。

• 升版后的脚本代码调整指引
• 升级审查清单
• 升级审查输出模板
• 升级审查示例
• 升级审查快速发起提示词

使用原则#

• 要现成方案：先找 magic-api-example 和基础 references
• 要解释机制：先看 architecture.md、 script-runtime.md、 extensions.md
• 要做插件 / starter：先看 magic-api-plugin 和 examples-and-plugins.md
• 要定位目录：先看 repo-map.md
• 要排障：先看 troubleshooting.md
• 要做升级审查：按升版专题资料的顺序走，不要一上来就给改法

这份 skill 的目标不是“把 magic-api 讲全”，而是让 Claude 在回答时 先给正确路径，再给正确内容，再给源码依据。