Step-Realtime-CLI: Instructions file for Codex

AGENTS.md

Step Realtime CLI 项目架构与开发原则。

1. 总体分层

Step Realtime CLI 采用分层 monorepo 架构，默认依赖方向如下：

packages/protocol <- packages/utils <- packages/core <- packages/agent-sdk <- packages/realtime <- src/gateway <- packages/sdk <- clients

旁路依赖如下：

• src/bootstrap -> packages/core
• src/commands -> src/runtime -> src/gateway
• skills/* -> packages/core
• extensions/* -> packages/core 或 src/gateway
• src/bootstrap 承载多个入口复用的启动 / 配置 / prompt 辅助逻辑

这里的 clients 指：

• src/cli/
• src/tui/
• ui/
• apps/desktop/
• apps/* 中未来新增的独立端侧应用

基础规则：

• 上层可以依赖下层，下层不得反向依赖上层。
• packages/core 不依赖具体厂商 SDK、数据库、WebSocket 服务端或 UI 层。
• src/gateway 是应用组装层，不是公共库层。
• packages/sdk 依赖的是 gateway 的协议，不是 gateway 的源码实现。
• UI、TUI、CLI、Desktop 默认只依赖 packages/sdk，不直接依赖 src/gateway。

2. 各层职责

packages/protocol/

负责跨边界契约：

• request/response schema
• event schema
• DTO
• session、workspace、agent、model 的共享类型

该层应尽量保持纯类型和纯协议，不放业务实现。

packages/core/

负责核心运行时与领域语义：

• Agent Loop
• Agent / SubAgent / AgentTeam 编排
• session / workspace 领域模型
• context / prompt 组装
• memory 抽象
• tool / skill / provider / model 抽象接口

该层默认依赖 packages/protocol，并允许依赖 packages/utils 这类无领域语义的基础共享层；不得直接依赖具体外部实现。

packages/agent-sdk/

负责对外暴露的 Agent 构建 SDK：

• 基于 packages/core 暴露稳定的 Agent / Tool / Skill 构建 API
• 供第三方或上层应用以编程方式声明 agent / 工具
• 仅依赖 packages/core、packages/protocol、packages/utils

该层不得反向依赖 packages/sdk、src/*、apps/*、extensions/*、skills/*、ui/（由 .dependency-cruiser.cjs 的 agent-sdk-no-implementation-deps 强制）。

packages/realtime/

负责实时音频 / 语音相关的协议与运行时：

• 实时音频 stream 抽象
• VAD / AEC / 语音通道的协议层与共享类型
• 供 gateway 与 extensions/realtime-* 复用的实时运行时基础设施

该层不放具体厂商适配；具体实现走 extensions/realtime-*。

packages/utils/

负责基础共享工具与纯辅助函数：

• 文本、路径、错误、token 估算等无业务状态工具
• 纯格式化、解析、归一化函数
• 可被 core / gateway / sdk / src/bootstrap / skills / extensions 复用的轻量 helper

该层不拥有 session authority，不实现 agent loop，不放具体外部系统集成。

skills/

负责 agent-facing 能力单元：

• skills/builtin/：内置工具