TinyAGI 实施方案与阶段验收
用途：实施规划。项目阶段与证据范围统一见设计台账；本文定义实施顺序、交付内容和验收条件，不表示所列功能已经实现或通过验证。
项目入口 · 逻辑总设计 · 文档索引 · 工程参考 · 库接入基线
| 阅读主题 | 入口 |
|---|---|
| 实施目标与职责 | 交付目标 · 实现边界 |
| 推进顺序与依赖 | 阶段计划 · 优先明确的契约 |
| 首批交付 | 实施范围 · 完整验收场景 |
| 范围与质量控制 | 各部分的实施安排 · 三层验收 |
| 依赖与后续维护 | 执行库和工具链 · 推进与记录 |
1. 交付目标
首个交付目标是能够初始化、持续运行、观察环境、执行行动并积累经历的最小主体，之后逐步补齐认知协作、程序演进、能力扩展和主动学习。每个阶段都交付可运行、可管理、可评价的完整链路。
实施从正式宿主骨架、业务状态和认知运行链路开始。已有实验和库回归提供接入依据，不能代替产品组件及组合验收。优先把已确定的职责连接起来，按实际链路落实接口和数据结构。
核心沿用单机、单二进制、单宿主进程的工程约束，SQLite 保存业务状态，本地文件保存大型资料与产物。模型、检索、原生工具及设备按需接入。主体自主性、任务解耦和状态所有权从第一条运行链路成立；主体无需先收到聊天或建立用户任务才能认知。
2. 三个实现边界
| 实现部分 | 维护的职责 | 与其他部分的关系 |
|---|---|---|
| Go 宿主 | 主体及各领域状态、操作接纳、事件、预算、权限、停止、程序采用和运行清理 | 向认知提供有范围的能力，保障行为可持续、可观察、可停止 |
.mgo 认知程序 | 决定关注什么、读取什么、怎样思考、是否回应、组织哪些心智、如何行动和复盘 | 经宿主能力访问状态和环境；主观意义与认知方法由个体程序组织 |
| 外部组件 | 模型、检索、原生工具、设备和平台的具体计算或动作 | 经公共能力端口及 MRPC 接入，声明支持范围；Go／Rust／Node.js 的实现差异留在适配层 |
软件组织沿用工程模块分工。初期根据实际链路建立必要包，接口由使用它的领域定义；共享身份、调用上下文、事件封装和错误语义，领域对象继续保留自己的操作与所有权。
管理页面经原状态所有者查询和提交，认知与管理共用业务契约；管理身份与聊天身份分别处理。初始化引导及固定维护入口独立于个体程序，人物程序不存在、损坏或暂不可用时仍可维护系统。
3. 阶段计划
阶段按主要依赖顺序排列。每个阶段的验收包含其新增功能及受影响的既有行为，不用包数量或接口数量代替完整链路的交付。
| 阶段 | 主要交付内容 | 阶段验收重点 |
|---|---|---|
| 一、宿主与维护入口 | 核心启动与关闭、数据目录、SQLite／文件访问、状态所有者、事件接入、执行域、预算与停止控制；独立机密模块；固定 Web 维护页；最小试验装配 | 没有可运行人物程序时仍能维护系统；模型配置和机密可通过可信入口管理；事件、操作、状态及用量可追查；试验状态与现实状态分开 |
| 二、最小持续主体 | 有界初始化引导、完整初始化提示词、预制能力库、.mgo 检查／编译／运行；一个主要 Mind；基础关注、经历与接续；一个模型适配器；有范围的资料读取和产物写入 | 从空数据目录创建主体；能够在无新对话时按自身关注继续或休息；外部慢操作不占住唯一认知入口；暂停、恢复和重启保持身份与已保存进度 |
| 三、记忆、协作与完整活动 | 资料修订、经历／断言／Reference、来源和记忆纠正；活动与任务责任；多人格私有状态与公共整合；人物、受众、关系及输出契约；领域检索入口 | 能完成需要取证、处理冲突、交付与复盘的活动；不同 Mind 的判断不会直接覆盖公共状态；不同情境下正确处理披露范围、事实标准和格式要求 |
| 四、程序演进与完整沙箱 | 受管理函数描述、类型及注释适配、动态表单；代码和配置提交；初始化提示词差异及 API 迁移；按问题装配试验主体；基线／候选比较 | 修改后经过准备并在调用边界生效；失败保留旧有效程序；状态及身份连续；已有个体的测试使用实际程序与所需状态；评价结果可以关联具体候选 |
| 五、原生能力扩展与隔离 | 能力发现、复用、构建和采用；受管理子进程；MRPC 发布、绑定、替换与清理；Go／Rust／Node.js 接入；容器执行适配；授权 Secret 交付 | 完成“发现缺口→构建能力→试验→采用→实际调用”的链路；任务可被外部中止；高风险操作只进入满足要求的环境；缺少容器时核心仍可使用 |
| 六、主动学习与外部接入扩展 | 学习议程、强度和额度；候选研究与采用；向量服务、Attemory 等实际适配；更多平台、事件源及设备；增量准备与复用优化 | 关闭学习后停止自主学习和自动采用，正常认知与经历积累继续；不同检索提供者按用途选择；外部事件不要求每次调用模型；复用保持质量和信息范围 |
| 七、集成验收与交付 | 完整工作台、核心发行物、安装和升级流程、缺失依赖提示、运行诊断；整体能力与回归基线 | 在干净环境中完成安装、初始化、持续运行、控制、修改、试验和维护；同一份核心发行物可按配置接入可选能力 |
管理、评价、机密、预算和观测贯穿每个阶段。 阶段二新增模型调用时，同时交付模型配置、停止、用量记录和对应测试；阶段五新增原生服务时，同时交付服务状态、绑定关系及清理结果的管理页面。
检索分步落地：先让记忆、资料、程序等领域表达清楚查询和结果含义，再接入具体提供者。Qdrant 与 Attemory 的实现先后只是开发安排，它们在契约、管理与评价上保持同级。具体提供者的安装和启用按用途配置，核心运行不依赖全部可选组件齐备。
4. 优先明确的实现契约
第一批编码前，具体化会影响后续返工的接缝。契约随第一条运行链路落成，后续新增领域功能时扩展相应接口；不以枚举全部未来方法、表结构或表单组件作为启动前提。
| 接缝 | 应先明确的内容 |
|---|---|
| 身份与执行上下文 | Self／Mind、执行域、实际调用者、预算归属必需明确；交流、Episode、Task 按实际需要关联。主体可以直接认知和调用能力 |
| 认知与操作 | StepContext、接续结果、步骤令牌、操作接纳回执和结果事件之间的关系；步骤内已经接纳的操作独立存在 |
| 状态与程序修订 | 哪个模块可以写什么状态；程序修订、个体数据结构和宿主 API 的兼容关系；哪些状态足以支持正常接续 |
| 能力描述与实际调用 | 接口、实现身份、作用、权限、输入输出类型和调用绑定同源；管理表单与模型工具描述从权威声明派生 |
| 配置与生效 | 普通行为配置随一次执行固定；权限、机密资格、预算与控制读取当前值；提交成功对应实际采用完成 |
| 试验装配 | 同一正式运行逻辑如何绑定不同状态、能力和环境；执行域由宿主确定，候选程序不能自行选择现实域 |
具体逻辑约束分别沿运行协议、管理生效契约和试验主体契约落实，本文不另定义冲突的提交、控制或状态恢复语义。
5. 首批实施范围
首批交付覆盖阶段一和阶段二，形成一个可管理、可持续运行、能使用受控能力并可在独立试验域检查的最小主体。
“最小”主要缩小能力数量：一个主要 Mind、一个已确认的模型适配器、少量资料与工具入口、一组明确的事件。可信密钥输入、预算与停止控制、试验域绑定随宿主骨架建立，人物生成和持续认知随后贯通。
初始化产物允许个体差异。用于测试宿主机制的固定 .mgo 夹具，与通过提示词形成的真实个体分别保存：前者用于确定性回归，后者用于初始化和行为评价。预制能力提供共同契约和客观工具，不固定个体的兴趣、人格或思考顺序。
5.1 完整验收场景
- 启动核心，打开固定维护页面，配置模型连接，通过专用入口录入机密。
- 登记 Self 身份，使用完整初始化提示词及预制 API 说明生成
.mgo程序；编译失败时在原初始化进度上有界修正。 - 生成的主体保存自己的初始关注和状态，进入正常运行；没有新聊天输入时，也可以继续关注、整理经历或休息。
- 接入一个外部事件源，主体按来源与当前关注决定是否处理，按需读取一份资料并保存结果。
- 接纳一项较慢的能力操作；等待期间，主体仍能处理其他输入，控制台可以独立中止该操作。
- 暂停、恢复并重启核心，确认同一主体身份、已保存状态及操作事实能够接续。
- 用固定测试初态和受控能力，在独立试验域运行同一认知程序，取得状态变化、操作、用量及结果记录。
- 从工作台查看发生了什么、当前在等待什么、哪些操作已停止，以及哪些外部结果仍未知。
验收中的接续使用已保存业务状态及明确输入，不要求恢复任意 VM 运行现场。操作中止请求、执行实际停止和外部效果按原契约分别记录；结果未知时保持未知，不用重发动作冒充恢复成功。
6. 各部分的实施安排
6.1 工作台与动态页面
前端使用 Angular。先形成固定维护能力，再扩展动态页面。首先具备模型、Secret、主体状态、程序诊断、操作停止和运行记录；真实函数描述跑通后，再生成表单，最后加入需要图形编辑的蓝图。全部操作始终调用原状态所有者。
工作台随各阶段持续交付，保留不依赖人物程序的维护入口。页面描述来自权威接口和配置定义，不能从 UI Schema 推导任意数据库编辑权或函数执行权。完整职责见管理专题。
6.2 沙箱与试验主体
沙箱从最小运行链路开始接入。先支持固定初态、独立可写状态和替代能力；之后增加已有主体状态的按需导入。完整 VM 现场复制不作为实施前置。
正式运行和试验复用同一认知与业务契约，范围由宿主装配。评价已有个体时使用其实际程序及必要状态；重新初始化的人物不冒充同一个体的修改对照。环境覆盖、状态缺失、真实计算与替代能力分别记录，沿沙箱与评价规格解释结果。
6.3 热更新、状态迁移与实际绑定
热更新同时处理代码、状态与绑定。编译成功之后还要确认状态兼容和实际调用切换。工作台显示“提交中／已生效／失败”；成功后无需再次点击启用。核心宿主更新继续走软件升级流程。
普通代码和行为配置在调用边界采用，当前权限、机密资格、预算及控制按现行约束核对。已经接纳的操作保留原归属和实际效果，迟到结果沿原契约处理。人物初始化、提示词差异、API 兼容及必要修复使用相同程序与状态身份关系，保留个体连续性。
6.4 原生能力与容器执行
原生能力按一条完整路径打通后扩展语言。先完成一种能力端从构建到调用、取消及清理的全流程，再复用 MRPC 契约接入 Rust 和 Node.js。容器环境满足要求后，才开放依赖脚本和高风险执行。
能力发现、复用、组合、构建、试验和采用沿同一生命周期，实际接口与实现身份分别记录。容器为可选依赖；缺失时核心及基础受限认知仍可使用，确需额外隔离的操作按缺失条件报告，不自动改到宿主执行。
6.5 独立机密与授权使用
普通认知使用 Secret 引用；可信适配器可以代理使用，获授权的 RPC 执行方可以通过专用接口取得原值。可信输入、领取授权、返回处理和审计作为一条链路实现，不能只在界面上隐藏输入框内容。
机密归属、维护权及使用授权分别处理，实际接收方、用途和目标决定原值交付范围。可信提交绕过普通认知输入，普通事件、日志和试验初态不承载原值。具体职责沿机密管理和运行契约实施。
6.6 主动学习与正常认知
学习强度独立于正常主体行为。首批验收时可明确关闭实验性主动学习，以便观察基础运行；后续开启学习时复用已经完成的构建、试验、评价与采用流程。
关闭学习时停止自主学习和自动采用，正常感知、关注、日常活动及经历积累继续。用户明确学习任务和必要兼容维护按各自范围接纳，不隐式提高学习强度。候选研究价值、试验结果和正式采用分别表达。
6.7 计算节约与复用
节约机制分为基础配置与后续优化。稳定输入装配、连接复用、编译缓存和真实用量记录从模型／执行适配开始加入；更复杂的在途合并、增量检索和跨工作准备复用，在语义及归属测试成立后加入。
独立判断和采样保持独立，当前权限、状态变化和必要实现切换优先于命中率。主体行为、所需信息、响应要求和完整成本共同评价；具体机制见计算复用契约及工程接入。
7. 三层验收
| 验收层次 | 方法与对象 | 结论边界 |
|---|---|---|
| 机制正确性 | 用确定输入检查调用归属、状态接纳、中断、任务独立、配置切换、权限变化、机密通路、试验域隔离及必要接续 | 说明所测机制是否符合契约，不能替代主体认知质量 |
| 主体行为 | 用固定开发场景和真实模型评价自主关注、按需取证、意愿表达、严谨工作、情境切换、协作与复盘；规则判定与内容评阅分别记录 | 采用前后比较不能只看运行成功，受所用模型、场景、预算和评价条件限制 |
| 成本与响应 | 在同条件下比较完整用量、等待、重复准备和质量变化；区分首次准备、重复使用与失效重建 | 提供者报告的缓存命中只是一个指标，不直接等于完整净收益 |
各阶段按新增功能和受影响契约安排测试，保留基线、候选、输入及评价规则的身份。真实模型运行前明确接口、模型、预算、场景与判定方法；开发材料、回归材料和保留评价材料按评估规格分别使用。失败、跳过和覆盖不足与通过结果一起保存。
8. 执行库与工具链基线
go-mini 的源码与实测范围见当前库基线及报告 018。后续升级沿固定提交核对流程，正式工程锁定可复现依赖，构建不依赖相邻开发目录。
库回归之外保留 TinyAGI 自己的接入与完整链路测试。根项目声明 Go 1.27，报告 018 使用 Go 1.26.6；实施时先固定正式工具链，并在该工具链下确认组合可用，不能将不同工具链的库成绩直接视为正式组合已通过。
生成器、绑定、编译器、运行库和派生产物按匹配来源准备。库升级结果分别保存，不覆盖历史证据；源码阅读、库回归、跨语言互通和完整主体行为分别说明，测试通过不扩大实现信任或机密访问资格。
9. 推进与记录
首批交付范围为阶段一和阶段二。后续功能沿同一状态、事件、能力和评价契约逐步加入，各阶段保持可维护的运行入口及可复核的验收依据。
本文维护实施顺序、交付内容和验收安排；总设计及六份专题维护逻辑，工程参考维护技术承载，设计台账维护项目阶段与设计状态，实验报告保存实际条件与结果。实现中出现新的职责冲突或直接反证时，先修订对应设计，再同步受影响的实施安排及验收场景。
已有实验只支持原条件内的结论，规划中的验收条件不计作测试成绩。完成阶段交付时关联实际实现及验证证据，不以文档补充或库用例通过代替产品功能完成。