AsterASTER CODE / 构建终端智能体
终端编码智能体教程
在同一个 Rust 工程中实现会话、终端界面、权限、验证、恢复和扩展能力。
教程产物
教程从空的 Rust 宿主开始，实现 tutorial-agent 终端编码助手。程序接收任务，显示模型回复和工具进度，处理操作确认，检查修改结果，并在退出后恢复会话。程序使用 Aster Code 的 Rust SDK，Core 负责模型推理、工具执行和事实日志。
各章持续修改 apps/tutorial-agent。先实现只读任务，再加入写入和执行权限。完成基础界面后，按需求接入后续能力。未配置的外部服务仍需单独配置。
- 01界面只处理交互
键盘事件进入宿主。界面显示文本与工具状态。
- 02宿主调用原有会话
Rust 宿主提交任务，并消费 Core 的事件。
fact_control.rsL126 ↗ - 03显示状态也保留身份
工具行使用原始调用 ID。生成结束与资源结束分别处理。
turn.rsL26 ↗
参考工程
仓库中的 apps/tutorial-agent 是可编译的参考实现，沿用根工作区和锁文件。无密钥演示运行 cargo run --locked -p tutorial-agent --example offline_tui。真实模型运行方法与按键见工程说明。教程按最小版本逐步实现，参考工程用于核对最终接线。
先决条件
开始前，确认能阅读 Rust 的 async、Result 和 Arc，并准备一份可连接模型的可信 ACL 配置。所有 Cargo 命令都在本仓库根目录执行，沿用根工作区、锁文件和固定 Rust 工具链。练习包使用本地 aster-core，不从包仓库安装另一个 SDK。
终端界面使用工作区已有的 Ratatui 和 Crossterm。教程给出文件名和代码。需要替换 main.rs 时会明确说明，后续函数接入前面建好的运行层。
示例中的 use 合并到对应模块顶部，已有导入不必重复添加。第四章开始，运行层保留一个 Runtime，统一持有 Agent、会话和确认通道。后续存储与扩展继续接入这个对象。
学习顺序
| 阶段 | 产物 | 验收标准 |
|---|---|---|
| 01–02：运行基础 | 可信模型配置、工作区、只读会话、流式事件 | 能解释项目，并找到对应 Run 的终态 |
| 03–04：终端应用 | 输入区、回复区、工具状态、权限确认 | 界面不阻塞，拒绝操作不执行 |
| 05–06：修改与恢复 | 验证契约、取消、保存和恢复 | 修改与报告对应，重启后不重复旧操作 |
| 07–10：项目扩展 | Harness、上下文、Skills、MCP、工具与记忆 | 扩展进入原有会话，数据与权限范围明确 |
| 11–12：长期任务与交付 | 目标推进、资源寿命、故障回归 | 每轮有界，清理失败不能显示成功 |
基础章节统一使用“解释 README 和测试入口”任务。验证章节再在可丢弃的练习项目中修复一个失败测试，以分别观察读取、权限、修改和验证。
教程与接口参考
设计原则说明组合接口的设计原因。RSI 与 Meta Harness说明递归自我改进实验中的宿主职责。
教程说明能力所属的应用层和需要修改的文件。Meta Harness 使用指南列出字段、限制和实现位置。参数细节以接口参考为准。
界面显示“回复结束”不代表全部工作完成。验收必须核对工具结果、当前修改的报告、原运行退出状态和资源收尾结果。