SuperAPI AI 工具集

style-guide

编程与开发

查看项目

更新于 10-31 14:15

技能介绍

Delta 插件约定。当这些规则和周边代码没有规定时,选择能工作的最简单做法:少量重复好过只有一个调用者的抽象。

加载规则:Claude Code 在加载插件前会读取 hooks/register.tsx 以及它导入的每个文件,拒绝它无法跟踪的代码。Anthropic 的插件目录更严格:它仅从 register.tsx 中的引擎调用列出插件能力,并拒绝把 $ 传给另一个文件中的函数,尽管 Claude Code 接受这种做法。claude plugin validate 不应用目录的任何规则;只有开发者门户的 Validate 才应用。引擎的 API 声明在 .claude-plugin/types/claude-code/index.d.ts 中,该文件由 Claude Code 在加载此文件夹时写入。

只有 register.tsx 可以命名 $。需要在直接调用之外使用引擎的 hook,应在第一条语句绑定 const host = hostOf($) 并传递 host。功能模块接收 host: Host(core/host.ts),绝不接收 $。这遵循 Anthropic 自己的 code-modernization 插件。功能需要的引擎调用是 Host 的一个成员,并在 hostOf 中写一行:一个闭包做出单一字面量调用,例如 read: (path) => $.fs.read(path)。重载方法为 Delta 使用的每种形式各设一个成员(session.apiMessages),环境变量为每个名称各设一个成员(env.os),使每次调用保持字面量。每次 hook 调用绑定一个 Host,不要在模块变量中保存任何 Host:$ 携带调用 hook 的上下文。

在 register.tsx 中,$ 只传给 hostOf 和 logHookFailure,这两个是该文件中的顶层函数声明。每次调用都写成字面量:$.noun.method(...)、$.env.get('LITERAL'),以及带字面量插件和键的 $.state 引用。不要给其他任何东西起名为 $、on 或 hook 的第三个参数:目录会把整个文件中的这些名称读作引擎相关名称。

用 type 导入类型(import type { Host },或在混合导入中写 type Host)。每个文件单独编译,因此未标记的 type 导入会在加载时失败,报“Export named … not found”。

只导入插件自己的文件:不要使用 import()、Node 或 DOM API 或 npm 包。

代码放置:register.tsx 存放 on(...) 注册,每个都带 .catch。超过几行的处理函数应作为其功能模块中的函数,类型为 e: HookEvent<'tool.call'>, next: HookNext<'tool.call'>。子代理循环也会引发的事件按 e.agentId 路由到 subagents.ts。每个功能在 hooks/ 下有一个文件夹(watch/、recording/、sharing/ 等),存放其模块和单元测试;core/ 存放所有功能共用的内容,testing/ 存放测试替身。新代码放入其功能对应的模块;每个模块的头部说明它存放什么(head -6 hooks//.ts*)。不含 Host 的逻辑放在独立模块中,由测试直接调用。

把 host 传给辅助函数。更窄的 host(SetupEnv、Interaction、AuthenticationHost 和 UpdateHost)由它构建,以便测试可以替换它们;不要添加其他 host。

只导出另一个模块或测试使用的内容。其他模块读取的模块变量应为 export let,不带 getter。

通过 delta-cli.ts 函数运行 Delta 命令(登录和更新通过各自的 host 进行)。它把命令标记为 Claude Code 的,用于 Delta 的遥测,并检查回答;测试会标记未标记的命令。

状态:模块变量应位于修改它的模块中。如果另一个模块需要修改它,把变量移到那里,或调用其模块中执行完整步骤的函数(startShare 标记共享进行中、显示进度并安排它)。只赋值一个字段的函数会增加间接性,且没有隐藏任何东西。

session-state.ts 中的 SessionState、requests 和 activation 是每个会话共享的记录:功能写入自己的字段,session-state.ts 清除它们。

按会话 ID 为每会话状态设置键,并在 session.end 处理程序中清除它。真正跨会话的缓存保留进程级状态。

用阶段把生命周期建模为可辨识联合,只能通过具名转换改变,如 watch.ts 中的 feed.connection;其他模块询问 liveFor、watchedSession 或 watchStatus。每次 await 后重新读取阶段。独立标志保持为标志。

在可能让出给另一个事件的 await 之后,检查工作是否仍然当前:对已记录会话用 stillActive(session),对 watch 用 feed.revision。

band 的绘制状态保留在 band.tsx 和 rows.tsx 的模块变量中,用 host.ui.invalidate() 重绘。$.state 原子在热重载后仍存在,因此把它移到那里是一个独立决定。

类型:对象形状使用 type 别名;别名可赋值给引擎的 JsonValue,interface 不能。

把不可信输入解析为 unknown(const value: unknown = JSON.parse(text)),并用 json.ts 守卫和 commandErrorFromEnvelope 收窄。验证器是类型守卫或断言函数。any 只出现在测试、替身和生成的夹具中。

对 as const 使用 as,或加注释说明类型为何成立。通过 storedBinding 和 storedChildBinding 读取保存的绑定。

在本地收窄,而不是使用理由很远的 !;紧跟自身检查之后的 ! 没问题。

用 default: { const unreachable: never = value; … } 结束对联合的 switch。

错误:错误类命名为 …Error,仅当调用者用 instanceof 检查时才添加一个。

在功能代码中抛出,在 hook 处把错误转为引擎的回答。失败是标记联合的成员({ kind: 'none'; reason }),而不是裸字符串。

给每个可能阻止或拒绝的 hook 显式 .catch。记录或观察的 hook 失败时放行(logHookFailure,然后 next(e)),因此记录永远不会阻止他人的工作;prompt.submit 失败时关闭。

空的 catch 或丢弃副作用失败的 .catch(() => {}) 需要有注释说明为什么安全。把失败视为不存在的读取、解析器的回退、停止子进程和等待某事完成不需要。

向用户显示 errorText(error);String(error) 会加上类名前缀,只适合调试日志。

用户可见文本是产品文案:只应有意修改它。

命名和注释:$ 是引擎,host 是从它绑定的 Host,e 是事件;session 是 Claude 会话 ID,thread 是 Delta 线程 ID,agentId 是 Claude 子代理 ID。

注释随其代码移动并在那里保持真实。在写关于引擎的声明之前,对照其类型或 claude plugin validate 检查它。

测试:直接单元测试纯函数,放在以其模块命名的文件中,紧邻该模块。

用引擎的测试工具包和 fakeThreads 测试行为,放在 register.test.ts 中该功能的 describe 或功能现有的引擎测试文件中。每个测试文件在自己的进程中运行并重新预热插件,因此新的引擎测试文件会增加 CPU,使 CI 的定时测试变得不稳定。

让插件用 fake.settle() 和 fake.advance(ms) 运行,它们会等到它安静下来,而不是 fake.clock.settle() 或 fake.clock.advance(ms),后者可能被负载高的机器超越。用 fake.settleUntil(…) 等待一个特定条件。

复用 fake-thread-commands.ts 中的辅助函数,一旦第二个测试文件需要某个辅助函数,就把它移到那里。

对 ui.find 结果做断言:未匹配是 undefined,不是失败。

格式化:没有格式化工具:匹配周围的代码,并把格式化更改排除在结构性提交之外。

不使用分号,2 空格缩进,多行列表使用尾随逗号。

使用单引号,当文本包含撇号时使用双引号。

导入花括号内的名称按字母顺序排序,忽略 type。

超过约 120 列的代码在自然断点处换行。用户可见字符串保持在一行,以便通过搜索其文本找到它。

完成前:运行 AGENTS.md 中的检查。claude plugin validate . 列出没有 .catch 的 gating hook。

在重构中,hooks validate 列表和源代码中的 $ 调用(grep -rohE --include='.ts' '$.[a-z]+.[a-zA-Z]+' hooks | sort -u)保持不变。

任何对用户可见文本的更改(host.ui.log、{ drop }、{ text }、band 字符串)都是有意为之。