lark-acp: Instructions file for Claude Code

LARK API

本项目是把飞书作为ACP的客户端的桥接库，虽然有API SDK调用，但是也不免会涉及到参考飞书官方API文档，必要时候需要参看：https://open.larksuite.com/document/server-docs/getting-started/getting-started

ACP

ACP（Agent Communication Protocol）参考文档 https://agentcommunicationprotocol.dev/core-concepts/architecture

TypeScript 工程准则（TypeScript 5.x / Strict Mode）

适用于本仓库所有 TypeScript 代码。AI 助手与人类贡献者都应遵守。

1. 避免魔法值

除显而易见的平凡值（0、1、一天 24 小时）外，禁止硬编码未加说明的数字或字符串字面量。

• 使用 const 常量，配合 as const 收窄字面量类型；或定义字面量 union。
• 优先使用所引入库已暴露的常量；库中确无定义时再自行声明。
• 常量应放在与其语义最贴近的模块中，不要堆到一个全局 constants.ts。

2. 错误处理：默认抛异常 + 文档化

TS / Node 生态以异常为主，默认采用抛异常 + JSDoc @throws 文档化的风格，与标准库、绝大多数第三方库保持一致。

• 任何可能抛出（含 Promise reject）的函数，必须在 JSDoc 中通过 @throws 描述失败原因与错误类型。
• 错误类型用自定义 Error 子类区分语义，并带上有用的上下文字段；不要把多种语义不同的错误合并成同一个原始 Error。
• 仅在以下特定边界才考虑 Result / Either 风格的返回类型（明确"失败是预期分支而非异常"）：
  • schema 校验 / 反序列化（如 zod 的 safeParse）
  • 用户输入 / 表单校验
  • 解析器 / 协议握手等"成功失败都是常规结果"的场景
• 不要为了一致性把整个工程改成 Result 风格——会和生态摩擦严重。

3. 优先使用原生异步模式

• 使用 async / await 与原生 Promise。
• 不要无理由引入 RxJS、Effect-TS 等重型抽象。
• 并发原语优先 Promise.all / Promise.allSettled 与 AbortController / AbortSignal，而不是再造一套调度层。
• 需要节流 / 限流时使用 p-limit、p-queue、p-retry 等成熟库。

4. 类型系统的纪律

不安全的类型断言和 any 会让 strict mode 形同虚设。

• 禁止 any：需要"任意类型"的位置一律用 unknown 加类型守卫。
• 禁止不安全的 as——即"绕过类型检查的强转"。以下用法是允许甚至推荐的：
  • as const：字面量收窄
  • satisfies 之后的隐式收窄（优先 satisfies 而不是 as）
  • 经过类型守卫 / schema 校验后的合法收窄
  • DOM API 中已知具体子类型时的向下转型（写一行注释说明）
• 禁止 ! 非空断言：通过 early return / 类型守卫 / ?? / ?. 处理；确实必须断言时写一行注释说明理由（与 Rust expect("...") 同义）。
• 解析外部数据（HTTP / 文件 / 用户输入 / IPC）一律走 schema 校验（推荐 zod），不允许直接 as SomeType。

5. 保持代码可维护性

• 长函数拆分为聚焦的辅助函数。
• 函数 / 变量使用有意义的名称，不要 data、info、tmp。
• 每个函数只做一件事。
• 默认写 pure function，副作用收敛到模块边界（IO / 网络 / 全局状态）。
• 仅为非显而易见的逻辑添加简洁注释；不要写"这段代码做什么"，要写"为什么这么做"。

6. 扁平化控制流

• early return / guard clause 让主路径保持在外层作用域。
• 类型收窄替代多层 if：if (!user) return; user.xxx 优于嵌套 if (user) { ... }。
• 错误分支优先 throw 或 return，避免用 else 包裹主逻辑。
• discriminated union + switch + never 穷尽性检查，代替散落的 if / else if 链：