AI 辅助开发

ACE Framework 项目在 skills/ 目录附带两个 Claude Code Skill，分工明确、协同工作：

Skill	文件	覆盖范围
cangjie	skills/cangjie.skill	仓颉语言本身：语法、类型系统、stdx 扩展库、构建工具链
ace-framework	skills/ace-framework.skill	ACE 框架 API：宏用法、代码模板、构建环境、已踩的坑

为什么需要 Skill

仓颉和 ACE Framework 均处于早期阶段，主流 AI 训练数据中几乎没有相关内容。没有 skill 时，AI 常见错误：

语言层面（cangjie skill 解决）

• 把 Option 写成 null/nil（仓颉没有 null）
• 把 class 当 struct 用，赋值后修改失效
• 用 \(...) 字符串插值（是 Swift 写法，仓颉用 ${...}）
• 用 \d 正则（仓颉 std.regex 只认 POSIX [0-9]）
• 在 extend 块里重复实现已有成员导致无限递归
• 误用 std.net 而非 stdx.net 写 HTTP 逻辑

框架层面（ace-framework skill 解决）

• 混淆 @OnMessage 参数顺序（message 在前还是 session 在前）
• 把 session.send() 写成不存在的 session.sendText()
• 忘记 source scripts/env.sh 导致 macOS 链接失败
• 用 cjpm test ace-router（返回 0 个测试）代替正确的 cjpm test
• 写出 AceApplication.create() 等不存在的 API

安装

# 在项目根目录执行，安装两个 skill
claude skills install skills/cangjie.skill
claude skills install skills/ace-framework.skill

安装后重启 Claude Code 对话即可生效。

cangjie.skill

触发条件

以下情况自动激活，无需手动唤起：

• 编写或调试任何 .cj 源文件
• 询问仓颉语法、类型系统、模式匹配
• 使用 cjc/cjpm 构建工具链
• 将 Java/Kotlin/Go/Rust/Python 等语言代码迁移到仓颉
• 使用 stdx 扩展库（HTTP、TLS、加解密、JSON、日志等）
• AOT/原生编译优化（-O2/LTO/PGO/静态链接）

仓颉相关任务即使顺带提及也会触发，避免凭记忆臆造语法。

Skill 内容

cangjie.skill
├── SKILL.md                          ← 语言速查 + 高频易错点（触发即加载）
└── references/                       ← 19 个专题参考文件（按需加载）
    ├── 01-language-basics.md         ← 变量、类型、运算符、字符串、区间
    ├── 02-functions.md               ← 函数、lambda、闭包、操作符重载
    ├── 03-types-and-pattern-match.md ← class/struct/enum/interface/match
    ├── 04-generics-and-extension.md  ← 泛型、约束、型变、extend
    ├── 05-collections-concurrency-errors.md  ← ArrayList/HashMap/spawn/Mutex/异常
    ├── 06-packages-macros-reflection.md      ← 包系统、宏开发
    ├── 07-io-net-ffi.md              ← 文件、标准 IO、FFI
    ├── 08-build-and-toolchain.md     ← cjc/cjpm 命令参考
    ├── 09-migration-from-other-languages.md  ← Java/Kotlin/Go/Rust 迁移映射
    ├── 10-stdlib-quickref.md         ← 标准库速查
    ├── 11-program-templates.md       ← 完整程序模板
    ├── 12-stdx-overview.md           ← stdx 接入与模块总览
    ├── 13-stdx-net.md                ← HTTP/WebSocket/TLS
    ├── 14-stdx-crypto.md             ← 加解密、哈希
    ├── 15-stdx-encoding.md           ← JSON/Base64/URL 编码
    ├── 16-stdx-serialization-compress.md     ← 序列化、压缩
    ├── 17-stdx-log-unittest.md       ← 日志、单元测试
    ├── 18-stdx-advanced.md           ← 高级 stdx 特性
    └── 19-aot-native-compilation.md  ← AOT/LTO/PGO/静态链接

参考文件按需加载——询问泛型时只读 04，询问 stdx HTTP 时只读 12+13，不会一次性占满上下文。

使用示例

用仓颉实现一个线程安全的计数器，支持 increment/decrement/get

AI 会查阅 05-collections-concurrency-errors.md 确认 Mutex 和 AtomicInt64 的正确 API 后输出：

import std.sync.*

class Counter {
    var value: Int64 = 0
    let mu: ReentrantMutex = ReentrantMutex()

    public func increment(): Unit {
        synchronized(mu) { value++ }
    }

    public func decrement(): Unit {
        synchronized(mu) { value-- }
    }

    public func get(): Int64 {
        synchronized(mu) { value }
    }
}

ace-framework.skill

触发条件

• 在本项目中编写或修改任何 .cj 文件
• 实现 @Controller、@Service、@Inject 等声明式组件
• 使用 ORM（@Entity、@Transactional）
• 使用 WebSocket（@WsController）或 SSE
• 调试构建错误、运行测试
• 添加新的 cjpm workspace 成员或扩展 Component

Skill 内容

ace-framework.skill
├── SKILL.md                          ← 构建环境 + 宏速查 + 惯用法（触发即加载）
└── references/
    ├── macros.md                     ← 50+ 宏的完整签名与参数规则（按需加载）
    └── patterns.md                   ← 8 类完整代码模板（按需加载）

macros.md 覆盖 14 个分类：Bean 注册、DI、路由、参数绑定、生命周期、AOP、定时任务、事件、中间件/过滤器、组件、WebSocket、DTO 校验、条件装配、日志。

patterns.md 包含可直接复制的完整示例：CRUD Controller+Service、ORM 实体、DTO 校验、JWT 认证、自定义 Component、WebSocket 广播、SSE 推流、单元测试。

使用示例

给 UserController 加一个 POST /login 接口，接收 username/password，
校验非空，验证通过返回 JWT token

AI 查阅 macros.md 确认 @Dto/@NotEmpty/signJwt 的正确用法后输出：

@Dto
public class LoginReq {
    @NotEmpty public var username: String = ""
    @NotEmpty public var password: String = ""
    public func validate(): ?String { None }
}

@Post["/login"]
public func login(body: LoginReq): String {
    if (!userService.verify(body.username, body.password)) {
        throw HttpError(401, "invalid credentials")
    }
    let token = signJwt(JwtClaims(sub: body.username, roles: ["user"]), jwtSecret)
    "{\"token\":\"${token}\"}"
}

两个 Skill 如何协作

两个 skill 分工不同、互不冲突，Claude Code 根据任务类型自动选择：

用户：给 TaskService 加一个 @Cacheable，把结果缓存 5 分钟
         ↓
ace-framework skill 提供 @Cacheable[300] 宏的正确用法
         ↓
用户：这里的 HashMap 为什么并发不安全？
         ↓
cangjie skill 介绍 ConcurrentHashMap 或 Mutex + HashMap 的正确方案

同一次对话中两个 skill 可以同时激活，上下文空间按需共享。

更新 Skill

Skill 随项目演进需要定期更新，重新打包：

# 重新打包 ace-framework skill
python3 ~/.claude/skills/skill-creator/scripts/package_skill.py \
  ~/.claude/skills/ace-framework skills/

# 重新打包 cangjie skill（当仓颉语言版本升级或新增参考文件时）
python3 ~/.claude/skills/skill-creator/scripts/package_skill.py \
  ~/.claude/skills/cangjie skills/

重新安装：

claude skills install skills/ace-framework.skill
claude skills install skills/cangjie.skill