Jingwei 开发指南
Jingwei 是面向端侧小模型的 Rust Agent 运行框架。它提供可组合的模型、工具、会话和运行时契约，由宿主决定业务目标、权限、模型与数据位置。
开发版本
本指南对应开发中的 v0.1。已实现能力与尚未交付的恢复边界在各章说明，不代表框架已经发布到 crates.io 或完成全部验收。
当前可用内容
现有框架可以装配自定义 Agent、受控模型调用、工具执行和会话日志。模型生成已经统一为文本、原生工具和 JSON Schema 三种路径；可选的单步动作组件把原生/JSON 动作安全交给 ToolRuntime。真实模型的结构化能力仍需宿主核实，当前验证使用私有假 provider 与本机回环 HTTP。
canonical 模型运行时提供有限执行槽、等待队列、总在途容量和准入截止时间。Agent、模型和工具共享 Task 内存预算，支持跨 Turn 累计、默认有限作用域和规范停止报告。
已提供底层预算快照、旧账本封存和未决状态冻结。显式持久模式通过 BudgetExecutionLease 取得唯一运行占用，canonical runtime 核验日志并提交最终检查点。宿主可在安全边界审计增额；持有原始最终候选时可审计恢复，其他中断冻结及完整 Task 状态恢复尚未交付。
可选的 jingwei-budget-file 提供有界本地文件检查点存储、跨进程 CAS 与精确重试，供宿主显式接入；存储操作锁不等同于运行时执行租约。
阅读顺序
- 查看开发环境与兼容性，了解当前源码版本和 Rust 要求。
- 阅读模型生成，接入文本/流式输出并理解结构化结果与工具权限的边界。
- 阅读模型调度与超时，配置容量、理解拒绝和观察清理积压。
- 阅读单步动作执行，理解 CallTool、Final、AskUser 与规范证据。
- 阅读任务预算，把宿主 Task 交给 Agent，并理解预留、用量可信度和运行报告。
- 阅读预算快照，了解宿主接入的原语与尚未闭合的持久化边界。
- 阅读文件检查点存储，了解显式接入、失败处理与关闭排空。
- 阅读持久预算运行，理解正常续跑、异常冻结、回执与部署限制。
- 阅读宿主审计增额，理解安全边界、原子审计和幂等重试。
- 阅读预算候选恢复，理解写者交接、原始证据与取消时的所有权。
- 阅读完整 assistant 回复，了解 final_text 的规范持久化和失败屏障。
- 阅读确定性对话投影，将规范历史转换为有来源、可重复的模型消息。
- 阅读上下文预算与消息选择，保护必要约束并控制请求大小。
- 阅读工具视图与动作接入，在授权范围内选择工具并按需读取大结果。
- 阅读有限参考 Agent，显式装配有限步骤驱动并理解停止与报告。
- 后续按实现进度补充完整装配入门、上下文、参考 Agent 及完整恢复教程。
本指南使用 VitePress 独立构建，阅读方式见编写与发布指南。类型和方法签名见 API 参考。完整装配与任务恢复教程将随实现补齐。