Claude-skill-registry debug-coffee-ahk

查询 coffee-ahk 编译架构、bug 定位方法、调试技巧，use when debugging/fixing bugs or need to understand compilation flow

install

source · Clone the upstream repo

git clone https://github.com/majiayu000/claude-skill-registry

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/majiayu000/claude-skill-registry "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/data/debug-coffee-ahk" ~/.claude/skills/majiayu000-claude-skill-registry-debug-coffee-ahk && rm -rf "$T"

manifest: skills/data/debug-coffee-ahk/SKILL.md

coffee-ahk 架构与调试指南

何时使用

修复 coffee-ahk 编译器 bug
理解编译流程、定位渲染错误、token 缺失
需要查询关键文件职责或 Processor 执行顺序

何时更新本 skill：

添加/删除 Formatter/Processor/Renderer 文件或修改执行顺序
关键文件职责变更（如 Content.reload/pick-item.ts 逻辑修改）
发现新的常见陷阱或 bug 定位模式
调试命令或工具链变更

效率优先：Read/Grep/Glob > Task · 优先使用本 skill 提供的路径信息，避免重复探索

编译流程（3 阶段）

entry/index.ts:18-67：

Formatters (formatters/index.ts) - CoffeeScript tokens → Item[]
Processors (processors/index.ts) - AST 结构重写（顺序敏感）
Renderer (renderer/index.ts) - Item[] → AHK 代码

Processor 执行顺序

processors/index.ts:19-37： newLine → validate → for/array/object/logicalOr/ifExpression/chainedCompare → typeof/instanceof/variable → builtInLoader/class/function

function 内部顺序 (function/index.ts:13-34)： mark → class → implicit-return → anonymous → count → parameter → do → ctx-transform

关键文件职责

路径	职责	关键逻辑
models/Content.ts:52	reload() 过滤 void	`filter(it => !it.is('void'))`
processors/function/anonymous/pick-item.ts:27	提取嵌套函数	标记原位置为 void
processors/function/class/prepend-this.ts:20	类方法添加 ℓthis	constructor 特殊处理
processors/function/ctx-transform/params.ts:11-15	收集参数+类方法标记	`classMethods: Set<string>`
processors/function/ctx-transform/bind.ts:12-15	Bind() 添加 this 参数	检测 classMethods 传递 `this`
formatters/property.ts:42	this.prop 处理	检查 lastType 插入 `.`
renderer/index.ts:102	mapMethod 映射	type → 渲染函数

Bug 定位方法论

渲染错误（AHK 输出不符预期）

定位：

查看 AST：
```
{verbose:true, ast:true}
```
确认 Processor 后 Item[]
检查 renderer/index.ts mapMethod 是否有对应 type
检查 renderer/basic.ts, edge.ts, control-flow.ts

Token 缺失（AST 中缺 token）

定位：

查看 CoffeeScript tokens：
```
{coffeeAst:true}
```
检查 formatters/index.ts 是否有对应 formatter
常见：
```
THIS
```
/
```
SUPER
```
/新语法未处理

作用域/闭包错误

定位：检查 processors/function/ctx-transform/ 的 collectParams/transformVars/addBind，验证 λ 对象传递链

Class method arrow functions 特殊处理：

```
collectParams()
```
检测
```
ℓthis
```
参数，记录到
```
classMethods
```
Set
```
addBind()
```
为 class method 内部的
```
.Bind(λ)
```
添加
```
this
```
参数 →
```
.Bind(λ, this)
```
确保嵌套箭头函数能访问正确的
```
this
```
（通过
```
ℓthis
```
传递）

调试技巧

# 查看完整编译流程
node -e "import('./dist/index.js').then(m=>m.default('file.coffee', {verbose:true, ast:true}))"

# 仅查看 CoffeeScript tokens
node -e "import('./dist/index.js').then(m=>m.default('file.coffee', {coffeeAst:true}))"

# 编译单文件（仅非测试文件）
node dist/index.js file.coffee

测试文件规则：

⚠️ 禁止手动编译或修改
```
script/test/*.ahk
```
必须使用
```
pnpm test overwrite
```
自动生成
新增测试：创建
```
.coffee
```
→ 运行
```
pnpm test overwrite -- <name>
```

常见陷阱

问题	原因	解决
Formatter 未消费 token	忘记 return true	添加 return
this 被过滤	formatters 缺少处理	添加 formatter
void 未过滤	Content.reload() 依赖	调用 reload()
嵌套函数 scope 错误	pick-item.ts scope 调整	验证 scope.shift()
Class method arrow 缺少 this	addBind() 未检测 classMethods	更新 params.ts + bind.ts

工作流程

确认问题类型：渲染错误/token缺失/作用域错误（参考上方方法论）
使用调试命令：根据问题类型选择对应的 verbose/ast/coffeeAst 输出
定位具体文件：根据关键文件职责表直接定位，避免全目录探索
验证修复：运行
```
pnpm test
```
或
```
pnpm test overwrite -- <name>
```

返回信息：

✓ Bug 已定位于 {文件}:{行号}

或

✓ 修复完成并通过测试