malganiswu/red-bean-qing-tuan/red-bean-qing-tuan-coding-conventions

red-bean-qing-tuan 编码规范

本 Skill 是本仓编码规则的唯一事实来源。

通用 TypeScript 规则在 `references/common.md`——与产品仓 red-bean-nian-gao

中的同名文件逐字相同，由 scripts/check-shared-files.mjs 校验。两者冲突时以通用件为准；

本文件只写本仓特有约束与落点。

写代码前完整读取两份：本文件 + `references/common.md`。

语言与风格

通用规则（类型标注边界、硬性禁止、外部输入、泛型、控制流与错误、函数与流程可读性、表达式与调用 可读性、判空与可空映射、命名与签名约定）全在 `references/common.md`。 本仓额外强调：

• revision/fencing 使用 bigint，不得经不安全的 number 转换。
• Promise、stream、iterator 的所有权与关闭责任必须明确：创建方负责关闭或取消。
• 事件联合必须可穷尽；新增事件不能依赖字符串拼接或宽泛索引签名绕过调用方检查。
• checkpoint revision 从持久化层读回后必须运行时校验，不能只靠静态类型。
• SDK 主包零生产依赖：不依赖 HTTP 服务、数据库、Redis 或产品展示类型。宿主能力一律通过

显式接口注入，由产品仓在组装期提供实现。

• *-dto.ts 只允许类型和 interface；校验、序列化、映射和业务函数必须放在相邻的 parser、serializer、

presenter 或 service 模块。DTO 按所属能力就近放置，不建 core/ 一类的聚合目录。

• 错误「类型不重要、可定位性优先」——SDK 的 adapter/plugin 包装宿主错误时尤其遵守，不得只取

message 重抛使宿主日志断链。

架构与依赖

完整架构见 `docs/design/architecture.md`。顶层能力依赖方向固定：

protocol
   ↑
llm   tool   observability
   \   |   /
    pipeline
       ↑
    runtime
       ↑
public entrypoints / testing

硬边界：

• src/protocol 与各能力的 port/ 只包含中性类型、小型纯 helper 和接口，不依赖宿主或具体基础设施。
• 纯数据 DTO 按所属能力放在 model/ 或 request/，只允许类型和 interface，不允许函数、Schema 或

运行时常量；parser、serializer 和业务规则必须放在相邻专责文件。Port 与领域状态不是 DTO，不为形式 统一混入 DTO。Runtime 不建立全局 DTO 大文件，也不接收产品 HTTP DTO。

• 一个模块的实现不直接耦合另一个模块的内部实现；跨模块通过公开入口和最小接口组合。
• 禁止重新建立宽泛的 core/、impl/ 或 dto.ts 聚合目录；能力目录采用 port/ 配合

service/adapter，纯转换保留为具名函数。

• 高层 AgentRuntime 与低层 Pipeline 共用一套中性消息、事件、Tool、Interrupt 和 Checkpoint 语义。
• 默认实现必须可替换；MemoryCheckpointStore 仅是单进程参考实现。产品取消、锁与 ID registry

属于宿主，SDK 不提供。

• SDK 只定义 revision/CAS/fencing/Resume claim 协议，不实现数据库、Redis、lease、heartbeat、

超时接管或 exactly-once 外部副作用；这些属于宿主。

• 静态插件仅在构造期注册并封闭。禁止恢复动态热更新、Generation、Supervisor 或运行期插件市场。
• 文件和网络工具默认 fail-closed，必须由宿主显式选择并授权。
• 公开 API 的接口是消费方契约，必须保留；SDK 内部 1:1 且无多实现/宿主替换需求的能力接口应删除。
• 没有对应接口的默认实现类必须登记在 scripts/check-architecture.mjs 的白名单中并附理由；

判据是「宿主或测试需要替换它的地方」。

• 本仓的默认组装入口是 AgentRuntime、builder 或宿主 composition root。
• 能力之间保持单向依赖；make ts-architecture-check 校验能力 DAG 无环、实现与接口精确对应

以及 DTO 纯度。

新增 TypeScript 能力必须同时审查公开 exports 和宿主影响。

目录与后缀的分工

两者常被混为一谈，实际管的是不同的事：

后缀之间不是同义词，各自的语义角色：

• Store —— 状态的持久化与读取（CheckpointStore）；
• Dispatcher —— 把一次调用分派出去（ToolDispatcher）；
• Adapter —— 与外部系统或宿主之间的协议转换（LlmAdapter）；
• Registry —— 注册与查找；
• Factory —— 构造；
• Hook —— 生命周期回调；
• Tracer —— 观测出口。

`Plugin` 不是 `Middleware` 的同义词：插件是注册单位，中间件是它装进去的包裹层 （RuntimePlugin 的 useRun / useLlm / useTool）；Hook 又是另一层，属于流水线的生命周期 回调。三者的关系属于本节，读者最容易在这里以为认识。

注释

注释的唯一事实来源是 `references/common.md` 的「注释」章节。本仓额外强调：

• 与 Port 一起演进的请求/结果类型应说明所有权和失败语义；宿主实现要求写在接口附近。
• Port JSDoc 应说明 Runtime 默认实现和默认组装入口；若实现只能由宿主提供，则明确标注宿主责任。

兼容性与判断边界

• 必须询问：破坏公开 API/序列化兼容性、不可逆数据或外部副作用、新的生产依赖、现有范围外能力、

未批准的安全边界变化。

• 已批准迁移计划内的兼容实现、测试、文档和本地验证可自主完成，不重复询问。
• TypeScript API 尚未正式 semver 发布，但任何 surface 变化仍须更新快照、契约、迁移指南和产品消费方。

公开契约与发布物

本仓是对外发布的包，公开面比内部代码受更严的约束：

• 六个公开入口经 public-api 聚合；入口之外的文件不是契约，可以自由重构。
• 公开 API 导出的接口是消费方契约，必须保留且受 semver 约束。SDK 内部 1:1 且无多实现或宿主

替换需求的能力接口应删除，调用方直接依赖实现类。

• 公开 API surface 快照与 TypeScript 声明基线分别由 testdata/api/public-exports.json 与

testdata/api/public-declarations.sha256 锁定。JSDoc 会编译进 `.d.ts`，因此任何注释改动 都要重生成声明基线；顺序是构建 → 更新基线 → 验证，不能倒过来。

• 修改公开面时必须先跑 make ts-api-check：check-api-surface.mjs 通过只说明导出形状没变，

与声明基线是两道独立检查，不能互相替代。

架构门禁（make ts-architecture-check）

• 校验顶层能力 DAG 无环、源码无循环依赖、port/ 不得导入实现目录、model/request/result 中 DTO

的纯数据约束，以及 service、adapter、builtin 与 Runtime 观测实现的显式 implements。

• 公开聚合文件只维护兼容导出，不作为内部依赖捷径。checkpoint.ts、Runtime 配置转发和 Testing 旧入口

只能由 public-api.ts 引用；生产内部代码必须直接依赖各能力的单一来源。

• 同时扫描 test/**/*.test.ts：单文件超过 400 行只产生 review warning，不令门禁失败。

编译器 API 接触点的隔离层（scripts/architecture-syntax.mjs）与主版本升级的替换点见 `../../docs/design/architecture.md`「依赖方向」。

门禁

本仓门禁命令的唯一清单在根 [`AGENTS.md`](../../AGENTS.md)「门禁」，本节不重列。 配置位于仓库根 tsconfig.json、eslint.config.js 与 tooling/typescript/。