背景
当前 main 分支的 Step-Realtime-CLI 历史包袱较重，配置模型、provider 边界、子 agent 调度、文档体系等模块的演进方向需要一次集中梳理。因此开辟 step-code-explore 作为新版本架构探索分支，目标是从零重构式地整理出可对外发布的 step-code 形态。
这不是一次增量补丁，而是一次完整架构快照导入 + 持续小步迭代。后续基于该分支持续演进，逐步收敛到可合并回 main 的状态。
当前状态（0.1.2）
探索分支已完成初始化架构搭建与第一批演进，核心模块全部就位：
| 模块 |
状态 |
| TUI（Ink React 终端界面） |
✅ 流式渲染、Markdown 表格、命令补全（含参数级）、全选择器视口自适应 |
| Agent（智能体循环） |
✅ 主循环、子 agent 派生与只读下钻（/agents）、动态工作流、目标驱动 |
| Provider（多协议接入） |
✅ Anthropic / OpenAI Chat / OpenAI Responses / StepFun 双通道 |
| Tools（工具系统） |
✅ 文件、Bash、搜索、媒体、Skill、Hook、Checkpoint |
| Session（会话管理） |
✅ 持久化、索引缓存、恢复、调试包、Wire 日志、Token 统计 |
| 测试 |
✅ 188 文件 / 2502 测试，CI 三平台通过 |
0.1.1 已解决的核心问题（首批）
- 子 agent 模型选择跨渠道化：
spawn_agent 的 model 字段支持 [models.<别名>] 解析，子 agent 可独立使用与主会话不同的 provider / 通道 / 模型。
- 自定义子 agent 角色可发现：项目级
.step-code/agents/*.md 定义的自定义角色自动出现在主 agent system prompt。
- 恢复会话的模型别名失效回退：
--resume / -r / /resume 恢复的会话如果其存储的模型别名已被删除或重命名，自动回退到 config.model。
- 官方文档视角统一：对外文档以阶跃星辰 Step 官方开发者身份撰写，示例模型优先使用 Step 系列别名。
- npm 发布准备：
step-code 包可通过 npm install -g step-code 直接安装，保留源码安装路径给开发者。
- 多模态支持：
read_media 图片读取、Alt+V 贴图、媒体降级（超限自动换占位）。
- 模型别名消歧：
loadConfig 保留原始别名指针（modelAlias），解决多别名指向同一真实 id 时的渠道混淆问题。
0.1.2 第二批演进要点
- 子 agent 会话呈现重构：全局
/resume 只列主会话；新增 /agents 命令列出当前会话派生的子 agent，只读下钻回看历史（不支持在子会话内继续对话）；子会话目录补 _index.json 索引缓存，/resume 卡顿根治。
- 可靠性修复批：后台通知送达标记与消息本体同刻落盘（消除崩溃丢通知窗口）；子会话锁 stale 检测（进程强杀后可恢复）；
/new /fork 换绑后台任务目录；edit_file diff 截断假承诺改完整落盘。
- TUI 完善：ModelPicker/ThinkPicker 视口自适应 + 滑动窗口 + CJK 宽度修正；斜杠命令参数补全（/goal /permission /provider /lang /mcp /plugin /history）。
- 配置体系：
/think /provider 切换写回配置；[tools.web] 缓存三阈值可配置。
- 合规：README 致谢段与 NOTICE 措辞中性化，代码注释统一自述式表述，审核词表扩八组隐蔽动词自检复核。
关联 PR
分支策略
main：保持原有稳定快照，不直接接收探索性重构。step-code-explore：重构沙盒，当前目标是沉淀出可发布的架构。
后续所有探索性改动都先 PR 到 step-code-explore，待架构稳定后再讨论是否合并回 main。
背景
当前
main分支的 Step-Realtime-CLI 历史包袱较重，配置模型、provider 边界、子 agent 调度、文档体系等模块的演进方向需要一次集中梳理。因此开辟step-code-explore作为新版本架构探索分支，目标是从零重构式地整理出可对外发布的step-code形态。这不是一次增量补丁，而是一次完整架构快照导入 + 持续小步迭代。后续基于该分支持续演进，逐步收敛到可合并回
main的状态。当前状态（0.1.2）
探索分支已完成初始化架构搭建与第一批演进，核心模块全部就位：
0.1.1 已解决的核心问题（首批）
spawn_agent的model字段支持[models.<别名>]解析，子 agent 可独立使用与主会话不同的 provider / 通道 / 模型。.step-code/agents/*.md定义的自定义角色自动出现在主 agent system prompt。--resume/-r//resume恢复的会话如果其存储的模型别名已被删除或重命名，自动回退到config.model。step-code包可通过npm install -g step-code直接安装，保留源码安装路径给开发者。read_media图片读取、Alt+V 贴图、媒体降级（超限自动换占位）。loadConfig保留原始别名指针（modelAlias），解决多别名指向同一真实 id 时的渠道混淆问题。0.1.2 第二批演进要点
/resume只列主会话；新增/agents命令列出当前会话派生的子 agent，只读下钻回看历史（不支持在子会话内继续对话）；子会话目录补_index.json索引缓存，/resume卡顿根治。/new/fork换绑后台任务目录；edit_filediff 截断假承诺改完整落盘。/think/provider切换写回配置；[tools.web]缓存三阈值可配置。关联 PR
分支策略
main：保持原有稳定快照，不直接接收探索性重构。step-code-explore：重构沙盒，当前目标是沉淀出可发布的架构。后续所有探索性改动都先 PR 到
step-code-explore，待架构稳定后再讨论是否合并回main。