工程选型与部署参考

用途：工程参考（与逻辑设计分开维护）。

项目入口 · 文档索引 · 逻辑总设计 · 逻辑契约 · go-mini 库行为

本文说明物理部署、软件依赖、技术栈和存储机制，并记录选型理由与证据边界。工程组件承载逻辑职责，但 Mind、活动和能力不必各自对应一个进程。方案设计范围统一见设计台账。

1. 承载约束与物理部署

本节定义核心及其能力依赖的部署边界。主体行为与职责分工见逻辑总设计。

核心采用以下承载约束：TinyAGI 核心单机、单二进制、单宿主进程；SQLite 保存业务状态，本地文件保存原始资料。向量服务与 Attemory 作为同级外部检索提供者，经 API／SDK 按需接入；本地和远程均可配置，向量路线初始选择为本地单节点 Qdrant。Go 承担宿主机制，go-mini 组织认知。核心之外允许宿主管理的本地能力子进程、原生构建产物、Node.js 程序包及 Go／Rust／Node.js（npm）工具链与运行依赖；单二进制描述核心发布物，不表示整个运行环境只有一个文件或进程。子进程不拥有第二份主体真值，也不构成 TinyAGI 集群。

不采用 TinyAGI 集群、Kubernetes、节点接管、服务发现、对象存储或独立业务数据库，以保持单机核心和本地状态的边界。嵌入向量引擎及 SQLite 向量扩展暂缓，原因是当前选择通过 SDK 接入独立向量服务，并非性能实验证伪。外部模型、工具和远程向量服务不改变核心部署约束。

核心为受管理认知程序提供基础受限执行，并默认携带额外隔离执行的契约与适配入口。容器引擎、镜像和工具链按需配置，缺失不阻止核心启动或基础人物初始化；直接接触系统环境、运行依赖脚本或执行高风险远程操作等能力，按实际要求使用合格容器。基础执行与额外隔离的分类见逻辑契约。容器不拥有主体真值，也不要求部署 TinyAGI 集群；工程接入优先 Linux 上的 Rootless Docker，增强隔离预留 gVisor，具体条件见容器执行。

1.1 物理部署总图

flowchart TB
    User["Web 管理工作台／CLI 入口"]
    subgraph Machine["TinyAGI 所在主机"]
        subgraph Process["一个 tinyagi 二进制／宿主进程"]
            Entry["输入输出适配、来源绑定与格式校验"]
            VM["go-mini 实例与认知调度"]
            Library["客户端预制库：固定源码模块、宿主适配、契约与资料"]
            Bootstrap --> Library
            VM --> Library
            Library --> Jobs
            Bootstrap["Go 引导器：初始化／修复工具循环与固定维护入口"]
            Entry <--> Bootstrap
            Bootstrap --> Jobs
            Bootstrap --> Data
            Bootstrap -->|"候选编译与受控实例"| VM
            Jobs["任务、读取与能力适配、后台维护"]
            Control["宿主优先控制：任务到执行关联、准入与收尾"]
            TaskVM["独立任务 go-mini 实例（按需要）"]
            Entry --> Control
            Control --> Jobs
            Control --> VM
            Control --> TaskVM
            Control --> Data
            Jobs --> TaskVM
            TaskVM -->|"结果及失败"| Events
            Ext["构建、隔离执行适配与 MRPC 绑定"]
            Jobs <--> Ext
            Ext --> Data
            Access["受控出站、认证绑定与返回过滤"]
            Events["事件接入、分发、订阅与关联"]
            Data["数据访问、单写入通路与维护入口"]
            Trials["评估模块：测试与基线、沙箱装配、评阅与比较"]
            Entry <--> Events
            Events <--> VM
            Events <--> Jobs
            Entry --> Data
            VM --> Data
            Jobs --> Data
            Jobs -->|"试验请求"| Trials
            Trials -->|"试验状态、基线与报告"| Data
            Trials -->|"独立试验实例"| VM
            Events --> Data
        end
        DB[("本地 SQLite：状态、元数据、事件和待办")]
        Files["本地文件：媒体、证据、代码和导出"]
        RetrievalServices["本地检索服务（按需选用）<br/>向量服务／Attemory；各自独立运行"]
        RetrievalFiles["各检索服务自有数据目录"]
        ContainerRuntime["可选容器引擎：Rootless Docker<br/>增强运行时按要求装配"]
        Containers["能力容器：Go／Rust／Node.js<br/>准备、构建、测试及运行"]
        Workers["普通受管理进程：仅承载满足普通执行条件的能力"]
        Ext -->|"受控创建、观察与结束"| ContainerRuntime
        ContainerRuntime --> Containers
        Ext <-->|"受限 MRPC 与产物收集"| Containers
        Containers <-->|"按用途开放的访问"| Access
        Ext -->|"启动、观察与结束"| Workers
        Ext <-->|"MRPC：本地 Unix socket 或回环连接"| Workers
        Devices["本机设备／驱动／外部推理服务"]
        Data --> DB
        Data --> Files
        Jobs <-->|"API／SDK：选本地提供者"| RetrievalServices
        RetrievalServices --> RetrievalFiles
        Jobs --> Devices
    end
    RemoteRetrieval["远程检索端点（按需配置）<br/>数据由服务侧维护"]
    Jobs <-->|"API／SDK：选远程提供者"| RemoteRetrieval
    API["可选第三方模型／工具 API"]
    Sources["外部事件源／通知提供者<br/>平台、文件监听、后台任务；闹钟仅为示例"]
    Jobs -->|"可创建／管理来源"| Sources
    Sources -->|"经适配器进入统一事件通路"| Entry
    User <--> Entry
    Jobs <-->|"符合条件的受信适配"| API
    Access <--> API

TinyAGI 自有逻辑模块和事件机制映射到进程内组件，核心不内置闹钟业务模块。外部通知源可位于本机的独立程序、操作系统设施或远程服务，经适配器接入；图中置于宿主进程之外，不要求它必须在远端。SQLite 保存任务责任、来源引用、订阅和必要事件，通知对象与计时由相应提供者管理。宿主执行期限和预算控制仍属于运行机制。模型计算交给外部推理组件，选用库时可在宿主内运行，使用已有运行时／API 时属于能力接入。发布单个 TinyAGI 可执行文件；当前完整初始化提示词、预制库源码与接口资料、固定引导支持及管理静态文件可内嵌，各 Self 生成的认知源码、修改产物与用户数据写本地目录，不引入内部服务集群。

外部检索提供者是独立能力依赖，可配置同机或远程服务；各服务维护自己的材料副本和检索状态。图中连接表示按用途选用，不要求同时部署、双写或调用全部提供者。向量服务与 Attemory 同级接入，Qdrant／本地单节点只是向量路线的初始配置。单二进制描述 TinyAGI 核心，服务内部实现与拓扑不属于主体运行架构。检索接入与取舍

回应的证据核对、意愿与规范适用判断仍由 go-mini 组织模型及工具完成；宿主输出入口执行确定格式检查，规则／契约版本和观测关联仍使用同一 SQLite 与本地文件。逻辑上新增的责任不对应新进程或外部审查服务。

沙箱沿同一事件／能力接口装配替代来源、输出、试验文件区和环境时钟；允许的模型计算仍经宿主适配并计入全局计算资源预算。数据库按宿主绑定的执行域隔开正式状态与试验状态，试验文件放入各自本地目录；共享的只读基准材料必须满足原可见范围，不向候选开放原始数据库连接、宿主路径或生产能力句柄。

平台适配器接收其可确认的账号、会话及受众元数据，人物关联和情境化记忆仍位于同一宿主的数据与认知层。对接多个聊天平台是能力接入，不是分布式部署；不新增独立身份服务或人物图数据库。

2. 软件组合与编译依赖

采用明确状态所有者和可替换能力端口的模块化设计。下图是编译依赖方向；前后调用产生的事件流见总逻辑架构，两者不混用。名称用于说明分工，尚未创建产品包。

flowchart TB
    App["app：启动、配置与装配"]
    Cog["cognition：go-mini 编译、实例与宿主桥接"]
    Core["领域组件：activity / materials / knowledge<br/>programs / models / execution / evaluation / secrets"]
    Events["events：共同事件协议、来源绑定、订阅与分发"]
    Ports["公共能力 API：各模块声明的端口与业务契约"]
    Adapter["adapters：SQLite、文件、检索 API／SDK<br/>模型、平台、MRPC 与工具链"]
    Domain["公共契约：带类型引用、调用上下文与事件类型"]
    App --> Cog
    App --> Core
    App --> Events
    App --> Adapter
    Cog --> Ports
    Core --> Ports
    Core --> Events
    Events --> Domain
    Adapter --> Ports
    Ports --> Domain

宿主桥接将认知请求表达为有类型的事件，分发给状态所有者或能力接纳入口；所有者经端口调用存储或能力。适配器将结果归入同一事件协议，不直接重入 VM 或任意修改其他模块。同步 API 可以等待并返回同一结果事件的业务视图，不另产生一个语义重复的完成事件。事件机制通过进程内接口和有界队列承载，跨模块的必要共同提交仍由宿主协调，不建立独立消息中间件。接口以业务用途划分，不做一套对所有对象通用的 CRUD／插件框架。

工作区可引用上述状态，但不复制成另一个事实库。一次用户交流可关联多个 Episode，一个 Episode 也可跨会话接续；不得用“聊天 ID＝活动 ID＝模型会话 ID”合并三者。人物关系／剧情、现实观测／体验和沙箱经历沿已有语义分开，表结构不得把它们压成无来源的聊天文本。

调用上下文由宿主绑定 Self／Mind、可选交流／活动或直接管理请求，以及实际执行者、能力范围、用途、执行域与预算。认知可以没有会话和 Episode，操作与费用仍归属于对应主体／心智；转入活动后保留原请求及用量关联。各领域按当前授权裁决，委托不扩大父范围；SecretGrant 继续由独立机密模块核对，不把多方权限合并成进程级通用凭据。交互归属与授权上下文规定逻辑语义，不要求增加数据库或服务。

认知输入保存所选来源、修订、派生关系及会话使用记录；撤权或用途变化时，宿主使受影响上下文和候选输出失效，不能确认已经移除内容的外部会话停止沿用。长期记忆由 knowledge 按保留规则维护，必要过程记录仍留在原模块；已交付结论的纠正使用 activity、knowledge 与交付记录的既有关联，不以重放全部历史代替影响判断。上下文有效性、记忆与纠正

持久化模式默认采用当前业务状态＋必要过程记录＋可重建派生索引。 状态用于接续，事件／决策／操作记录用于查证，原文与内容修订由资料和记忆职责分别保留。当前不采用“所有状态只能重放全部事件得到”的完整事件溯源：模型和外部动作无法仅凭本地事件重新产生相同结果，且重放与隐私保留会增加复杂度。这是工程取舍，未做框架优劣对照。ORM、依赖注入容器及 Agent 工作流框架也不作为默认依赖；先用显式 Go 结构、构造函数及参数化 SQL 表达当前有限边界。

3. 技术栈与依赖版本

“默认”表示当前设计选择；“已测”只限报告列出的组件组合。本文定义设计选择，不构成产品实现。

宿主组合实验已验证固定 go-mini、Go 标准库、modernc SQLite 和本地文件在本机组成无 CGO 可执行文件，并经确定提供者完成两段活动；这支持当前默认，未测试真实模型、生产负载或跨平台。

执行库更新另以当前固定提交核对，库回归及跨语言互通结果见报告 018。报告 014 的工具链和组合成绩保持原条件；新库用例不替代完整宿主组合重测。

已测构建目标是本机 Linux/amd64 的最小文本闭环；Windows／macOS、本机 GPU／语音库、跨机型安装与真实容量留到明确用途后验证。单二进制目标不等于把权重、显卡驱动、CA／操作系统环境或第三方工具都内嵌。

mattn/go-sqlite3 暂不作默认，主要理由是其 CGO／C 编译依赖与当前简化构建的偏好；它仍可构建单二进制，不是违反架构或被性能实验否定。若实际任务暴露驱动负担、扩展需求或目标平台问题，再在相同业务负载比较。向量服务的选型不重新打开业务状态数据库选型。

FTS5 默认 unicode61 以连续 token 字符分词，不是中文语义分词器；trigram 对少于三个 Unicode 字符的全文查询有限制。因此保留有界原文扫描作为覆盖路径，按实际中文／混合文本查询选择分词或索引，不直接把 BM25／向量相似度当成证据可信度。向量存储采用下述 SDK 路线，embedding 模型、切分和检索策略按用途配置，组合收益尚无本项目实测；不要求每次活动都使用语义检索。

3.1 Web 工作台

工作台覆盖完整管理范围。Go 宿主提供管理 API 与静态文件，前端构建产物可内嵌二进制；浏览器不直接连接 SQLite、外部检索服务或 VM。普通查询与命令使用 HTTP，状态推送可用 SSE，前端选用 Angular／TypeScript。动态表单与蓝图组件尚未选定，运行时无需增加独立前端服务。逻辑职责与管理方案

依据：Go embed 支持编译期文件内嵌；WHATWG SSE 定义事件推送和重连。二者用于承载推论，不证明完整管理台已经实现或通信无遗漏；页面可重新读取当前状态。

执行库的状态重建、旧帧保留和不兼容变更依据集中在go-mini 读取记录。

提交切换的契约见管理工作台。设置定义、认知程序与蓝图可设计为热调整对象；修改核心宿主原生实现属于软件更新；按契约受管理的原生能力采用产物准备与 MRPC 绑定切换，见能力工具链。库补丁与绑定行为有局部测试依据，完整管理提交、主体级试验和人物迁移尚无端到端成绩。

3.2 提示词初始化、自迁移与 API 兼容

采用“当前完整初始化提示词 + 相邻修订的差异与迁移说明”交付认知初始化要求。每份完整提示词有来源、日期和内容身份；历史正文保留，文本 diff 从相应两份正文生成，语义说明补充变化原因、影响范围、必要／可选项、替代接口及检查条件，并与相同起止身份关联。跨多次修订可顺序处理或使用有完整覆盖关系的累计说明。差异表达要求变化，不是针对所有个体源码的统一补丁；实际运行提示词和人物程序尚未交付。

TinyAGI 对自身公开给 .mgo 的稳定接口承担兼容责任：旧导入路径、类型、调用入口、MRPC handler 或适配层在声明窗口内确实可用，并保留承诺的参数、结果、错误、状态和资源语义。弃用说明提供替代方式、开始弃用的契约修订、支持范围及最早移除条件。窗口按若干次稳定 API 契约修订计数，不能把每次提示词编辑或客户端补丁都计为一次；具体保留数量属于发布支持策略，尚未指定。无法保持旧语义的改变应明确为不兼容迁移，不能只保留同名函数却改变含义。

采用 Go 的 Deprecated: 注释习惯，并复用 go-mini 文档提取结果展示给 Self 和工作台。调用点提示、依赖影响分析、兼容清单与旧实现保留由 TinyAGI 工具及适配层补充；注释不会自动实现兼容，也不能据此声称库已提供完整弃用告警或迁移系统。稳定宿主包装层隔开第三方接口变化，生成绑定仍由相应声明重新生成。

优先在旧程序仍可运行、旧接口仍受支持时，让 Self 根据实际源码和迁移项完成改写、编译及受影响功能检查。跨客户端更新时还要检查语言、标准库、编译工具链和运行依赖；宿主 API 兼容不能覆盖这些变化。go-mini 将源码、资源和 .mrpc 作为分发边界，执行镜像与缓存属于当前工具链派生物，不能保证旧字节码跨客户端继续启动。旧程序不可运行时，Go 引导器按原身份和可读状态修复候选；不依赖旧 VM 自己先成功启动，也不默认捆绑所有旧 VM。无法识别的数据格式进入受限维护，由原状态所有者处理迁移，回退可执行文件不自动等于数据可回退。

引导与迁移使用管理操作或既有授权策略绑定的范围和独立维护预算，沿用领域视图、按需读取、机密注入／过滤及候选采用规则。学习强度为关闭时，获准的必要兼容维护仍可执行；不得因此开启主动学习、改写人格目标或扩大权限。客户端更新、提示词发布、个体程序采用和业务数据迁移分别显示实际结果，准备耗时可见，成功采用仍按提交即生效。

选择理由：提示词与语义差异适合个体程序有不同结构的前提；宿主独立引导消除“生成或修复程序必须先运行该程序”的循环依赖；显式兼容窗口为 Self 留出迁移机会。未采用统一默认人格代码、强制套用源码补丁、更新即重新初始化或永久保留全部历史运行时，分别因为会覆盖个体差异、误配实际源码、破坏连续性或失去可控支持范围。这些是工程取舍，未被性能实验证伪。

Go Doc Comments 的弃用约定支持弃用信息的表达；go-mini 固定提交记录支持文档提取、源码注册与编译／实例分工。资料不证明本项目引导器已实现、任意模型可生成可运行程序或长期迁移无退化。逻辑语义见引导契约，检查设计见沙箱评价。

3.3 客户端预制能力库的交付与接入

TinyAGI 随核心客户端提供预制工具能力，采用固定源码模块、宿主实现／适配及同源文档／示例的组合。库对 Self 的只读性是维护权和交付边界：权威源码与绑定由客户端维护，个体认知源码、包装和构建产物保存在自己的工作区。库内函数按实际用途执行计算、读取、写入或外部操作，权限及状态修改仍经现有宿主入口。

预制工具可覆盖 API／能力查询、资料读取、源码结构与诊断、配置及预算查询、解析转换、差异计算，以及候选编辑、模型、构建和沙箱的受控接口。函数清单与命名按具体接入确定，不另建一套直接操作数据库、任意文件或不受控进程的旁路。稳定业务状态、权限及各领域生命周期仍由已有宿主模块负责。

库更新随客户端提供新增能力、修复及弃用说明。新增项可选；已依赖模块的实现变化可能直接影响行为，须保持承诺的兼容语义，必要时由 Self 在窗口内迁移。预制权威实现不经个体热加载改写，个体包装可按受管理程序契约更新；同次执行和编译绑定确定来源，不强行复用不兼容旧镜像。核心软件更新与预制库更新一并记录实际完成状态，不新增在线替换核心 Go 任意代码的承诺。

采用理由是复用成熟语言工具和通用操作，减少初始化时的接口猜测与机械性重复编写，同时保留个体逻辑自由。不采用强制使用固定便利层、手工维护多份接口说明或按新增库能力自动改写个体程序；前两者增加约束或漂移，后者混淆能力供给与个体采用。预期收益属于工程判断，尚无初始化成功率或性能实测。

资料依据为 go-mini 固定提交的源码注册、显式宿主装配及语言工具；逻辑维护归属见预制库契约。

3.4 主体认知、任务执行与外部控制

核心 .mgo 保持关注、判断和任务组织，Go 宿主负责接纳、执行与控制。Self／Mind 的认知执行可独立于交流和 Episode 创建，宿主绑定主体额度、代码、已装配能力和结果关联；形成活动后沿用已有操作及投入。主体生命周期不使用业务任务的 deadline；长任务提交成功即返回操作引用，由宿主任务所有者维护 context、预算、工作者与结果事件。认知分段仅拥有局部计算和短调用，跨分段工作归 Operation 管理。接纳边界保存原来源、授权及预算关联，既不把任务挂在提交它的短调用 context 下，也不通过移除取消传播获得不受控后台工作。

宿主普通操作使用有界工作者；长时间脚本或需要隔离 guest 故障的工作按需使用独立 Instance，Program 可在兼容条件下共享，globals／scope／FFI Session 分开。任务实例不是另一个 Self，不拥有第二份主体真值；同进程的独立实例也不提供操作系统级资源隔离。原生能力继续按既有子进程设计管理。输入、停止与核心调度不等待后台队列排空，后台工作限制并发及份额；Executor 容量、模型队列与进程资源按用途装配，未承诺硬实时响应或无推理容量时即时答复。

受管理认知程序通过显式绑定的 FFI／MRPC 能力操作状态及外部环境，不默认装配任意文件、网络、进程或宿主环境访问。宿主负责核对可达入口、接口契约、额度和状态提交；这是本项目基础执行的装配要求，不能仅凭使用 go-mini 宣称自动满足。模型生成的认知候选可在该范围完成初始化及局部检查；调用原生命令、依赖脚本或其他需额外隔离的实现时，沿执行分类切换到合格环境，基础程序包装不免除执行方要求。

InterruptHandle.Interrupt 只提交取消请求；Execution.Cancel 实现需要取得 VM owner，故控制入口不能同步等待任意清理才接收其他请求。FFI Open／Start 必须快速返回，阻塞工作在 provider 自有有界执行器中完成；子进程及远端服务按原生命周期处理。核对当前控制范围与任务到 Execution／操作／子工作的映射后执行，不能仅取消一次调用却允许任务调度器继续重试。

API 装配使用普通 library 入口承载有界认知段，避免 main 生命周期结束其他工作。同一 Instance 有活跃前台 Execution 时不能另起前台入口；Pending FFI 虽让出 worker，核心须结束／中断占用入口的认知段，由宿主按事件安排后续有界认知执行。核心分段的 WaitScope 仅等待局部所属工作，不等待整项外部任务。任务使用独立 Instance 时，后台 guest panic 的实例级影响不落到核心实例；业务错误用结构化结果返回。具体固定提交事实见库记录。

Go context 文档（页面所示 go1.27.1）：取消沿派生 context 传播，支持分清提交请求与已接纳任务的生命周期。结合 mini-go 源码，本项目采用独立归属、分段接续和受控取消；这是接入设计，未新增完整响应性、隔离或停止延迟实测。既有报告 014 只支持异步 FFI 与顺序跨实例接续，不覆盖此处的并行中止场景。选择理由及业务约束见总设计，未来评价见沙箱。

3.5 受管理函数的声明与生成工具

采用 TinyAGI 构建工具读取 go-mini 源码快照、类型信息与结构化注释，经确定性校验生成调用描述、适配代码及前端表单／蓝图描述，再编译完整候选 Program。普通内部函数沿语言规则调用，跨宿主边界的可调用函数必须登记并适配受支持的 HostValue 类型。具体注释语法、类型子集和生成工具尚未实现，以下仅为声明示意：

// ComposeReply 根据当前任务材料组织答复。
//agi:entry id="reply.compose" expose="workflow,console,model"
//agi:requires model.generate
// 对应函数签名：ComposeReply(ctx Context, input ReplyInput) (ReplyResult, error)

type ReplyOptions struct {
    // 回答长度的目标上限。
    //agi:field title="回答长度" min=1 default=200
    MaxChars int
}

参数／返回类型从类型信息推导，不在注释中手写第二份完整 Schema；说明由普通文档注释提供，默认值与字段约束作为声明，用户修改存为配置覆盖。特殊注释是受限元数据，不执行注释中的任意命令。类型、描述、适配代码及其依赖绑定同一来源产物，生成结果不供人工独立修改。

内部受管理函数可采用固定宿主入口加生成分派代码：函数稳定标识映射到类型适配及普通命名调用，避免每新增一个受管理函数都人工维护宿主入口和 UI。分派层采用现有显式 EntryPoint 与 Call／Start 路径，不能声称库可直接调用任意未登记符号；方法、泛型和特殊参数仅在适配工具能够明确解析时支持。固定分派入口只减少入口变化，不保证任意内部签名或状态变更均可原地补丁。

候选连同调用描述及普通行为配置一起准备；有效配置使用统一的声明与覆盖解析，当前授权、Secret、预算和控制另行核对，规则见配置解析。兼容时在受影响执行／scope 收束后使用补丁，需改变状态契约时明确准备替代实例及转换，不兼容则提交失败。一次执行期间不应用会改变其调用图的补丁。提交结果在可调用实现和管理描述已经一致切换后报告成功，已有外部 Operation 独立保留。试验主体及临时函数测试入口使用同一生成路径，绑定试验域。

检查分为声明／类型／禁止依赖等构建期规则与授权／预算／机密／作用等运行期规则。不能从纯计算注释推定实际纯度；受限能力装配和宿主执行检查仍须成立。核心 Go 宿主本身的任意代码在线替换不纳入此机制；受管理原生能力走独立的 Provider 替换路径。

Go 官方 Generating code，2014-12-22 发布，说明特殊注释与显式生成工具可用于生成代码；go generate 不自动属于 go build。这里只借鉴元数据驱动生成方式，不直接执行用户源码中的生成命令，也不据此宣称 go-mini 已支持 agi: 语法。固定库提交的命名调用与热更新核对支持接入分工；整套生成工具、类型覆盖和性能未经实现或实测。

3.6 能力工具链、MRPC 与运行管理

采用范围：尽量复用 go-mini 的 MRPC 与嵌入 API，补充宿主侧构建、局部 VM 试验与子进程生命周期适配。它们实现能力构建逻辑契约，不修改通用 VM 的认知语义，也不将全部内部调用改成 RPC。

接口权威与多语言生成

表单、蓝图、模型调用描述关联接口修订，服务产物另记录所支持的接口和实现修订；纯实现变化无需伪造接口变化。TinyAGI 的注释／元数据生成器仍是待实现的设计，MRPC 生成器则是库已有能力，二者不能混写成同一验证状态。现有声明示意中的 int 等内部类型不直接成为 MRPC 类型；跨语言发布遵循库的固定宽度等类型约束。

接入选择与工具链

宿主调用已配置的 Go 工具链、Cargo／rustc，或 Node.js／npm 与需要的 TypeScript 构建工具，记录版本、目标平台、依赖与锁定输入、源码／接口及生成器身份、构建参数和产物摘要。复用缓存须满足输入身份及处理范围；原生 Go 适合已有 Go SDK，Rust 适合相关库或明确原生处理需要，Node.js 适合 npm 生态中的 SDK 与业务整合；按现成依赖、运行条件及任务需要选择，不预设某语言必然更快。工具链为可选能力依赖，安装及更新沿已授权维护操作处理；缺少环境时报告依赖不足，不假定核心内嵌全部编译器。

MRPC 本地固定绑定足够时不使用 Router；动态 Provider 才使用 Router。Go／Rust 跨进程能力使用库已有的 Unix socket／WebSocket 接入，支持平台上优先受限本地 Unix socket；当前 Node RPC SDK 使用 WebSocket，采用明确配置的受限回环 ws／wss 接入，不把原生端的 Unix socket 能力推定给 JavaScript SDK；Gateway 作为库装配，不要求启动独立中间件。业务 RPC 不另设未经库确认的 stdio 传输。发布入口与调用路由由宿主管理，不能对候选开放任意 fallback 或未授权服务。

Node.js、npm 与 JavaScript RPC 的装配

.mrpc 仍为跨语言接口唯一来源；用 -ts-out 生成 TypeScript ESM 绑定，再由项目构建流程生成 JavaScript。Node 能力使用 @d7z-team/mini-go/rpc 的连接、生成客户端和 Provider 适配，不另写一套 JSON RPC。

当前 SDK 内部使用 Worker、Rust WASM Endpoint 与 WebSocket，无需创建 MiniGo 或加载 Program；“无需 Mini-Go 程序”不等于没有 SDK 的 WASM／Worker 分发依赖。接口沿JavaScript RPC 记录解释，当前分发及验证范围见更新基线。SDK 的编译器与语言工具可供非 Go 工具端按需使用，不改变核心 Go 宿主的编译职责，也不要求管理页面取得原生能力。

采用产物包含实际 JavaScript 入口、生成绑定、包清单、依赖锁定输入及必要分发文件，并关联 Node、npm、SDK、生成器和可选构建工具身份；源码、依赖或 SDK 改变均形成新的实现候选。依赖取得、生命周期脚本及打包过程只在获准准备环境执行，正式启动使用已准备产物，不默认临时安装最新版包。复用已构建 SDK 分发包与从库源码构建 SDK 分别记录条件；包名或本地版本号不证明已从公共仓库取得某一发布物。

Node 服务按既有子进程机制准备、启动、publish、绑定、替换和关闭，其 Worker、连接及下属工作由该运行对象负责。宿主显式传入调用期限与取消信号；SDK 取消等待不当成处理函数或其外部动作已经停止，terminate() 也不替代完整清理。断线后原绑定及资源按实际契约失效，重新连接、bind／publish 经原任务与授权核对，不能自动重发不明动作。接口的 64 位整数、字节、可选值和资源沿生成类型处理，不经通用 JSON 转换损失精度或归属。

npm 程序与原生程序共用实现信任、Secret 投影、执行环境准入、父活动预算和沙箱规则；Worker 分离或 WASM 计量不代表整个 Node 服务被隔离。SDK 同时支持浏览器是库事实，这里仅讨论 Node 能力端，不因此让管理页面脚本直接获得宿主能力。Web 工作台仍由核心提供管理 API 和内嵌页面，选用 Node 能力不要求另设管理服务。

局部 VM 服务与子进程管理

宿主封装局部 VM 的创建、检查、执行、观察、取消和结果读取，并可经 MRPC 向获准认知程序提供。每次试验使用独立 Instance 与受控 FFI，允许复用不可变 Program；较长试验通过 Operation／结果事件接续。不得从 FFI 同步重入同一活跃 Instance，也不把 VM 逻辑额度解释为整个进程的 CPU／RSS 限制。

Go／Rust／Node.js 外部能力工作由宿主管理：依赖准备、构建、测试和一次性转换是任务进程；持续提供能力的是服务进程。状态覆盖准备、启动、接口可绑定、运行、退出与清理，关联 PID 等运行身份、所属活动或已安装能力、固定产物与用量。进程退出信息、RPC 就绪和业务成功分别记录。子进程树及其输出、取消和结束责任归启动者，不能用直接子进程已退出证明全部后代已停止。

Go os/exec 提供启动、管道、等待和取消基础；面向 TinyAGI 的进程管理及经 RPC 暴露的局部 VM 服务是本项目待封装能力，本次库快照未确认现成通用实现。标准输入输出可用于构建诊断及受控命令交互，业务 MRPC 连接仍遵循上述传输契约。

实现替换与资源归属

认知脚本补丁与外部能力 Provider 替换分别执行。Go／Rust／Node.js 服务更新先准备固定产物，启动候选并核对接口和可绑定性，再用 Router 的准备／替换机制更新 publication。库中旧客户端绑定旧 Provider，因此宿主还必须在受影响执行边界更新绑定：同一次执行保留固定实现，新执行选择目标实现，调用描述与实际绑定一致后才报告提交成功。

旧执行句柄留在创建它的 Provider 与连接上，不能自动迁移；需要新实现时显式重开或转换，否则继续记录旧执行句柄的收束。MRPC resource 是临时会话对象，不写成 SQLite 中可恢复的唯一业务身份，也不复制进试验主体。旧 publication 的实际关闭与 backend 释放由其所有者负责，停止新绑定不等于既有调用已停止。

服务可以长驻并被多个活动复用；认知的有界调用不要求每次重启服务。宿主能力可按权限被服务反向调用，使文件读取、产物提交和状态修改仍沿原所有者处理。外部能力进程不取得业务 SQLite 或全部主体状态的直接控制权。

构建环境、机密与输出

文件读取、可写目录、网络、环境变量及实际计算资源限制覆盖依赖处理、代码生成、构建、测试和运行。Cargo 构建脚本及包准备中获准的脚本执行也在控制范围内，控制不能等到最终能力程序启动才开始。需要隔离的候选统一使用受控容器执行，不将进程分离或 VM 限额当作完整隔离证明。适配器须声明实际可强制执行的文件、网络、进程、资源与输出限制；宿主按候选所需约束选择可用环境，无法满足则拒绝构建／运行该候选，不降级到普通生产进程。

功能采用记录与实现信任记录分开；后者绑定受信维护者或既定发布策略、来源及产物摘要、适用用途与敏感能力。接口稳定、MRPC 类型正确、沙箱通过或候选自称可信都不能自动授予原值访问；新产物按原发布策略重新核对，不强制已有自动授权范围每次再人工审批。

默认不继承宿主完整环境与凭据。Secret 由独立机密模块管理，宿主代理使用与按读取授权向 RPC 执行方交付原值并存；后者核对固定产物、接收方、当前 SecretGrant 和审计条件，经专用通路返回或注入。认证数据不进入模型、普通事件、日志、索引或试验快照；沙箱执行方领取须有单独的测试授权。构建和运行日志先经确定性过滤，再由相应操作保存为受限记录；模型只见状态与投影，按需读取。大对象使用 MRPC resource 分块读取，不将 SecretRef 映射为普通内容读取句柄。

依据、替代项与适用边界

go-mini 适用提交、实测范围及更新流程唯一维护于库参考；RPC 机制与Node／TypeScript 契约保留各自来源，早期实验仍按原提交解释。下列在线官方资料未固定成本项目工具链依赖版本：

不采用全函数 RPC 化、另一套跨语言序列化协议、每项局部试验复制完整主体或默认常驻所有服务，原因是增加重复状态、成本与生命周期负担。进程内 Go plugin／Rust 动态库热装载不作为默认，避免为动态能力引入额外 ABI 与宿主稳定性耦合；这是工程取舍，未经性能对照。能力种类可继续扩展，但构建成功率、运行成本和真实任务收益没有新增实测结论。

3.7 主动学习扩展的接入与强度控制

学习策略作为可替换的 go-mini 受管理模块接入，原生计算及试验工具经 MRPC 能力调用；复用 activity、knowledge、programs、execution、evaluation 及管理配置，不增加独立学习服务、数据库或进程。长期方向使用 Goal，问题使用 Episode，构建／练习／试验使用 Operation，知识候选由记忆维护，程序候选由构建职责维护，报告正文归资料，评价结论归 evaluation。核心 VM 不需要理解“兴趣”“学习议程”等业务概念。

学习强度配置从受信管理通路提交，宿主在选题调用、操作进入、子工作接纳、接续及自动采用入口核对当前限制；不能仅在编译策略或启动 VM 时读取一次。配置修订不要求中途热补丁：关闭和调低额度作为运行控制执行，普通代码／配置的单次执行一致性仍沿既有契约。下属 VM、能力子进程和后续事件保留原活动来源，换服务、换实例或保存再读取候选不能绕过关闭。

关闭后终止自发学习的新增准入、接续和自动采用，按所属 Operation／scope／Provider 管理在途取消及清理；共享模型、能力服务、正常主体认知及普通活动不随学习关闭而整体停止。迟到结果只登记状态或受限产物，不再启动学习。已关闭状态在宿主重启后仍从已保存配置装配，不因重新创建实例变成启用。用户明确学习任务使用独立接纳范围和预算，不隐式调整主动学习开关。

学习策略的库依据复用MRPC 与嵌入核对，所核对的库接口不包含自主选题、学习强度或学习收益评价；这些是 TinyAGI 的宿主与策略设计。强度的逻辑语义见运行协议，工作台见学习管理。课程、反馈记忆及代码迭代的原论文依据集中于资料索引，没有本项目实际性能或学习效果数据。

模型参数训练保留为外部训练能力接入选项，管理训练任务、数据许可、候选模型和采用绑定；当前不选择训练框架，训练与推理继续通过外部服务接口接入。具体学习算法、工具链参数及强度档位数值按用途配置，实验性不等于已经运行实验。

3.8 模型维护与机密处理

维护入口位于同一 TinyAGI 宿主，连接模型资产、加载状态、服务配置和能力绑定。远程维护只执行提供者真实支持的接口；下载、卸载或删除以维护操作记录，不依赖模型生成管理请求。

Secret 是独立模块，元数据及 SecretGrant 可使用现有 SQLite，原值使用受限本地存储。密文或操作系统凭据设施可作为保管方式，解锁材料与普通导出分开；无需增加独立服务。加密保护保管与传输过程，防止错误外发仍由真实接收方、目标接口和数据路径落实，具体库与平台适配按接入选择。

Web 使用固定受信控件和专用 API，CLI 可用无回显输入或受控流；专用指令不带明文参数，在普通请求日志、聊天记录和模型调用之前分流。用户可以维护自己的凭据，管理者可按权限调整归属及使用配置。临时入口绑定用户、用途与有效期，接纳有效提交后失效；原值不放 URL，入口凭证不进入普通日志、远程内容分析或通用通知。

输入页面不加载任意动态脚本、第三方录屏或分析组件；动态工作台通过隔离的受信控件完成提交。无原值权限的中继只转发面向保管方封装的数据，宿主仍核对提交身份。获写入权的组件可以提交自己已有的新值，不自动获得旧值读取权限。

普通配置、认知 VM 和模型请求持有 SecretRef。宿主适配器在最终认证字段注入原值，或将原值交给受信 SDK／RPC 实现；不放进通用环境、任意临时文件或默认日志。远程模型服务的认证头与其推理正文是不同接收用途，配置允许前者不意味着允许把凭据写入提示词。

实际接收方、RPC 交付与返回处理

Go／Rust／Node.js 能力端以宿主绑定的服务及实现身份调用专用机密接口，SecretGrant 核对实际用途和目标。原值直接到达指定组件，普通工具响应只返回引用、状态或业务结果。MRPC 的认证、拦截器及传输是接入工具，不自动提供 Secret 隔离；绑定和序列化检查由 TinyAGI 适配，见库事实。

若计算组件确需处理原值，配置必须明确组件身份、输入用途、后续服务和输出范围，使用独立注入及记录路径。组件可为模型或程序，可本地运行或远程接入；这些标签不代替信任判断。特殊输入不混入默认上下文保存、缓存导出、遥测和调试记录。受信组件若调用其他远程 API，该目标仍须在允许范围内，不能沿普通代理或重定向自动携带凭据。

确定性管线执行可信输入、字段校验、保管与引用、用途核对、认证注入或原值交付、返回处理。凭据编码不等于脱敏；业务结果不因使用认证就全部成为 Secret。返回中的认证回显、异常载荷和请求头不进入普通输出，无法安全分离时只返回状态。额外原值处理规则采用受信配置，不由模型临时生成一段过滤代码自行授权。

必要记录保存 Secret 修订、操作者、实际接收方、用途、目标与结果，不保存原值。放行前记录决定，失败时拒绝新的原值交付，撤销和禁用仍可执行；执行方上报与宿主观察分别标明。更换凭据或撤销约束后续访问，已经交付的静态值需通过上游吊销、轮换或到期失效。试验配置单独绑定允许的凭据用途，不把生产原值和授权复制进初态或快照。

逻辑目的与边界见机密契约，归属、可信提交及管理操作见工作台。此处是接入方案，未声称已有端到端防泄漏实测。

3.9 模型接入的证据与选择

实验使用同一模型网关的chat/completions接口承载 JSON 动作。请求标识kimi-k3、deepseek-v4-flash对应实际响应k3-256k、deepseek-flash；没有独立核实上游权重或固定快照。服务修复与功能轨迹见报告015、016，参数及接续对照见017。

DeepSeek官方投入说明给出推理档位与默认设置，并区分普通消息和原生tools的推理块续接；接口契约定义生成上限和截断含义。这些支持参数候选及错误映射，不证明网关身份、最优额度或任务可靠性。未来接入原生工具须另按提供者契约保留必要续接块，不能照搬报告 017 中普通消息的处理方式。

3.9.1 可选的外部认知辅助组件

分类、重排和记忆整理等开源组件通过既有 RPC／API 适配接入，按实际用途定义接口，不将某产品的判断类型固化为核心契约。支持本地运行或远程服务，运行环境属于可选依赖；管理与沙箱复用已有装配机制，领域视图、Secret、预算及必要执行隔离沿原规则处理。停用或替换时保留原始资料和主体状态，能用既有方法就继续，任务确有依赖则报告缺失，不自动扩大处理范围。

资料范围为官方在线文档及仓库默认分支的说明、许可证。以下资料支持将局部判断与生成式综合分工的思想融入有限思考，不证明本项目质量或性能收益。接入原则与候选状态见决策台账。

3.10 外部检索提供者与 API 接入

向量检索服务与 Attemory 是同级的外部检索提供者。 两者经公共检索契约用于记忆、资料、程序定位和能力发现等已定义领域；支持独立登记、发现、指定调用、用途配置、维护和评价，实际安装与启用可选。TinyAGI 实现接入与请求组织，检索引擎、计算及服务侧数据维护由组件负责。逻辑契约

3.10.1 共用接入与本地／远程配置

Go 宿主优先使用提供者已有 API 或 SDK，适配器转换请求及有类型结果。已有 HTTP 接口可直接接入；需要受管理的本地桥接程序时才使用现有 RPC 与子进程机制，不为所有提供者增加必经桥接层。领域入口决定查询含义，策略选择单次、并行、分步或替代调用；适配器不要求每个实现支持向量特有字段。

同一产品优先共用适配器处理连接差异，不默认双写或联查全部服务。管理页面仅展示实际支持的操作；查询权不包含维护权，Secret 通过专用授权绑定使用。外部服务不接管主体调度、领域业务状态或原文真值。

准备材料和持续同步各有明确范围与后台任务。主体只取得获准描述或明确请求的片段，服务返回的全部文本不自动入模。跨域结果保留类型，组合按来源对象、修订及片段关联；得分和排序附带提供者语义，不直接跨实现相加。覆盖不足与调用失败可触发允许的替代策略，所有分支和重试计入原认知或活动预算。管理、评价

3.10.2 向量服务适配

向量检索通过 SDK 接入独立向量数据库，当前初始配置选择 Qdrant、本地单节点。该选择只确定向量路线的默认组件，不规定所有领域先用向量，也不降低其他提供者的接入地位。服务端不必使用 Go，索引引擎无需链接进核心。

选择依据是官方客户端、部署复杂度和过滤契约。Qdrant 官方 Go SDK github.com/qdrant/go-client/qdrant 使用 gRPC，提供本机与远程连接、集合、写入、查询和过滤示例；本地单容器及持久目录便于初始装配。实际接入须固定服务端与 SDK 版本。向量服务依据

各领域提供获准内容和修订，embedding 提供者生成向量，向量适配器执行条目维护及查询。Embedding／VectorIndex 只表达此路线的调用分工。条目关联执行域、对象类型、标识、修订和片段，模型、切分、维度和度量作为该适配的配置；维度相同不保证兼容。数据库点 ID 不替代业务身份，payload 只保留定位及过滤所需信息。

分别核对 embedding 服务和向量数据库的材料处理范围，查询向量及过滤字段也受约束。配置与原领域状态变更形成明确的准备或清理操作，服务报告完成后记录可确认覆盖；本地业务变更不表示索引已经同步。检索结果核对当前来源，过滤不能冒充已删除。

3.10.3 Attemory 适配

Attemory 经已有 HTTP API 接入；官方 Python 客户端是可复用的另一种接入方式，不要求核心增加 Python 运行依赖。它与向量适配同级，可独立配置为某类查询的提供者，也可参与组合。TinyAGI 只对接材料准备、查询、状态及服务支持的维护操作。

服务中的 Session 作为外部检索空间引用，不等同于 TinyAGI 的聊天会话、人物或活动。上传的是允许处理的材料副本，原领域身份和来源修订仍由 TinyAGI 维护。程序定位与能力发现通过对应领域选择允许检索的说明或内容，不把程序执行权、机密原值或全部人物历史作为检索材料。

采用已有接口可减少接入工作，代价是承担服务运行、材料准备、覆盖滞后和接口差异。当前确认依据是官方接口资料，不是本项目端到端验证；不采用厂商性能数字作为默认收益，也不把具体接入参数列为必须先完成的新实验。

3.11 可选的原生容器执行能力

容器执行适配承载预制隔离执行契约中的额外系统隔离，不替代核心基础受限执行。稳定入口与宿主适配随客户端维护；引擎、基础镜像和工具链是可选依赖，不自动安装、提升系统权限或随主体初始化启动。首先面向 Linux 接入 Rootless Docker，公共接口保留其他合格提供者的扩展位置；不要求同时维护多种引擎，也不引入集群控制面。

宿主负责生成受约束的执行请求并调用引擎，Self 只提交用途、能力及计算资源需求。Docker socket、任意引擎 API、特权参数和宿主挂载配置不暴露给候选。高风险远程调用的本地实现、不可信解析、动态 Go／Rust／Node.js 程序、Shell 及依赖脚本在容器内运行；普通路径仅承载满足其准入条件的受信能力，不能通过直接 os/exec、FFI 或 MRPC 绑定绕过检查。远端服务本身的运行位置不由本地容器控制。

默认约束与实际能力检查

Rootless 降低引擎与容器依赖宿主 root 权限的范围，但不自动提供全部限额。环境检查须报告实际内核、引擎、cgroup 与控制器条件，网络及文件限制同样按所选提供者核对；约束不满足时该执行不可用。具体开关、额度及运行时版本由用途配置确定，不能把已安装 Docker 当作全部请求均可接纳。

构建适配器也不能通过向候选挂载引擎 socket 获得便利。依赖下载、包生命周期脚本和编译安排在相应容器执行范围内，正式运行使用已准备产物；构建阶段的联网资格不自动延续到运行阶段。容器取得的原始材料须满足外部处理许可，执行组件加载程序或使用材料不等于模型已经读过它们。

调用、复用与停止

一次构建、任务或受管理服务会话可对应一个持续执行环境，多次 MRPC 调用复用原实现和作用范围；不按每个 RPC 重建容器。不同用户、试验分支或信任范围默认不共享可变环境。传输适配只开放所需业务通道，并绑定原操作身份及回调范围，不开放宿主通用管理端点；容器环境的传输装配不作为既有 go-mini 库已验证的行为。

宿主保留容器运行身份、原 Operation、固定产物、实际限制、用量及收尾状态。停止按任务范围传递到所属容器工作，清理子工作和临时目录、连接及执行句柄；控制请求发出、持久接纳、进程停止及远端效果核对分别显示。共享受信服务只结束目标任务的使用，不以中止一次调用关闭其他任务。引擎失联时记录实际未知状态，不宣称全部停止，也不转到宿主重新执行。

容器镜像及可共享的只读缓存按来源、修订和处理范围复用，工作目录与可变会话按原范围隔开。产物收集、日志登记和清理属于原执行责任，仍受限额约束；容器退出不自动表示任务已交付或全部临时目录、连接及执行句柄已回收。管理页面见执行环境。

选择理由与替代项

采用容器是为动态能力提供可管理的文件、网络、权限和资源边界，同时复用现有运行生态；Rootless Docker 是首个工程接入选择，未由性能对照得出最优结论。成本包括额外运行时、镜像维护、启动及兼容性限制。其他引擎可作为同一契约的后续提供者，当前不同时展开实现。

需要进一步减少不可信程序接触宿主内核时，预留 gVisor 等增强隔离提供者。增强环境有自己的兼容性和系统调用开销，必须按实际组合报告能力；不预设它与任意 Rootless 配置均可直接组合。任务要求增强隔离而环境缺失时拒绝该执行，不降为普通容器。

不采用全能力强制容器化、把 TinyAGI 核心一并迁入容器作为前提、每次调用新建容器或缺失时回落宿主；这些方式分别增加环境依赖、耦合及启动成本，或违背准入要求。资料支持见来源表，实际状态及适用边界见设计台账。

3.12 计算节约与复用的工程接入

沿逻辑节约契约，Go 宿主在原模型、读取、检索、构建及运行适配器中利用现有机制。小型热点结果可在进程内有界保存，派生文件和必要索引信息沿现有本地文件／SQLite 承载；不新增 Redis、统一缓存服务或 TinyAGI 分布式部署。原始材料、主体状态和正式产物独立于可清理缓存。

3.12.1 提供者和本地组件映射

复用能力和计费口径绑定实际端点、账户处理范围、模型／实现及配置。应用内分组键不自动构成上游隔离；跨用途、试验域或身份共用只读准备仍须符合原信息范围。缓存放行也不能使特殊机密计算进入普通缓存、输入日志或诊断通路。

首次准备、重复使用、失效重建及空闲占用分别计量；写入／读取费用可能互斥或包含在其他字段中，按提供者原口径映射，不静默重复相加。预期避免的费用与服务报告、估算及最终账单分别显示。缓存配置和前缀发生变化时保留原因及相关修订，不必记录敏感正文来解释未命中。

3.12.2 一手契约、选择依据与适用边界

下列在线官方契约支持机制选择；实际接入按所用模型、版本、账户及端点固定支持范围。供应商调整参数、期限或价格时更新适配，逻辑正文不固化统一 token 门槛、保留时间或折扣。

采用分层复用，是为了利用组件已有能力并保留业务所有权；不采用自建通用缓存后端、合并独立推理结果、为了命中填充提示或按费用自动降级模型。已有报告仅支持各自读取、构建或模型条件，没有形成完整节约性能基线；设计与观测字段可确定，实际收益仍是适用边界。状态、评价

4. 领域状态与内容存储

逻辑上的提交、接续和外部不确定性见运行契约。以下说明领域接口、SQLite、文件与恢复机制。

领域接口与共用承载

领域对象在同一 Go 宿主内按状态所有者组织接口和记录。资料、记忆、程序、配置、模型、运行、检索及机密各自处理请求；不建立统一 Resource 表、必填公共属性结构或能访问所有对象的通用读写服务。SQLite 与本地文件工具可以共用，文件位置不决定业务归属或权限。

大段文档、媒体、源码、权重及必要记录可由文件工具承载，原领域保存自己的标识、修订、引用和约束；小文本可直接保存在 SQLite。内部字节定位不向调用者提供绕过领域授权的路径。内容共享或复用不得复制另一份可独立改写的业务真值，具体存储结构不在逻辑设计中规定。

查询编排调用各领域的受限查询，管理页面复用展示和关联组件。动态表单从领域接口及受管理函数描述生成，提交进入对应处理器；不让 UI Schema 变成任意数据库字段编辑权。文档读取、记忆查询、程序构建、模型加载及机密领取拥有不同的参数与返回。

跨语言接口继续复用 MRPC 生成与绑定。业务引用使用有类型的对象标识及必要修订，SecretRef 只用于专用机密接口。MRPC 的 resource 是服务所属的传输／调用句柄，保持库的原生命周期，不定义 TinyAGI 的业务对象分类，也不让协议句柄自带业务授权。完整库事实见接入记录。

读取／结果缓存由对应处理能力维护，检索提供者通过独立适配调用；共享来源关联、日志元数据及授权上下文工具不合并其所有权。机密保管和原值交付另见专用映射，不进入普通文件读取、认知工具响应或通用导出。

4.1 SQLite 提交机制

现有机制基线为 WAL／FULL、读取结束后短写；依据限于报告 010的条件，吞吐、checkpoint 和超时参数尚未选定。派发入口以条件状态转换共同裁决 queued → entered 或 closed；此事务不覆盖提供者的现实效果。

宿主为步骤绑定身份、尝试号和可撤销令牌。步骤读取固定上下文后进行计算，不持有长事务；每心智最多一个可提交步骤。不同心智可以并行计算，写入通过一个宿主写入通路串行安排；写入顺序不授予 Self 公共决策权，公共提案先沿整合职责处理。

步骤内需要先取得工具结果时，按独立操作接纳通过短事务保存 StepID、RequestKey、请求内容、Operation、预算关联及接纳回执，成功后才派发。相同请求键与内容返回原回执，冲突内容拒绝；该操作不等待最终 Continuation 才成立。

计算完成后以 BEGIN IMMEDIATE 开始短 SQLite 写事务，复核当前令牌、状态版本、授权、必要依赖及预算，将状态变化、尚未接纳的请求意图、既有操作引用、必要预留、输入消费、等待订阅和提交回执共同保存。既有操作只关联，不再次派发或扣取同一预留；步骤内实际读取的结果留存输入依据，最终提交失败不回滚已经独立接纳的操作。相同 StepID 与相同内容重试返回原回执，不同内容视为冲突。需要的新文件先按文件发布协议准备完成，再在事务中保存引用。

上下文读取结束即释放读事务，不将旧快照保持到模型返回。BUSY_SNAPSHOT 时回滚并重新读取／复核；普通写入竞争有界等待或重试，不能重发已经发生的外部动作。S1a 已观察旧快照升级失败及长读阻碍 checkpoint，生产参数仍待负载验证。

事务内不调用模型或外部工具，不等待大文件生成。提交后唤醒进程内派发器；内存通知丢失时，定期扫描数据库中的未完待办。等待条件与消费游标共同提交，并检查已经到达的完成事件，避免丢失唤醒。

正式任务控制与工作接纳按宿主持久顺序裁决，均携带目标类型和传播范围。经授权的实时通路可在持久化完成前先发送止动信号；阻断／中止状态须成功保存到 SQLite 后，才返回“控制已正式接纳”的确认。保存失败或结果未知时，分别报告失败或待确认，保留已知止动结果；不能因本地执行已停就声称任务中止已持久接纳，或承诺重启后仍有该控制。请求发送、接纳记录和提供者停止观察按控制契约分开呈现。

仅取消认知步骤时撤销旧令牌，拒绝其后续提交，已经独立接纳的 Operation 仍归原活动继续；中止 Episode／Task 或取消指定 Operation 时，才按其范围关闭派发并向所属在途工作传递控制。不能从“请求已接纳”自动推导该请求应被认知取消连带终止。结果复核实验表明串行写入不能补足遗漏依赖，进程／提供者实验只支持部分事务边界，不代表完整单机协议已测。

4.2 数据放置与文件发布

tinyagi                 单个二进制
<data-dir>/
  state.sqlite          业务状态；SQLite 管理 WAL／SHM
  files/                已发布证据和媒体
  artifacts/            认知代码、构建与验证产物
  sandboxes/<id>/       试验材料与产物
  tmp/  cache/  logs/   未发布文件、派生缓存与有界日志
  runtime.lock          宿主独占锁的稳定载体
<backup-dir>/           数据库与必要文件的完整备份
<retrieval-data-dir>/   各本地检索服务分别配置；提供者维护，TinyAGI 不直接读写其内部文件

目录名是候选。远程向量选项只配置端点与凭据引用，服务侧数据不映射为本机目录。资料、记忆、程序和模型各自提供受限视图；宿主经对应领域接口核对范围后解析文件，路径不是授权。单数据目录只由一个宿主持有，Linux 候选使用稳定锁对象，不靠 PID 文件存在判断；不删除／重建在用锁或把锁句柄传给工具。

文件先发布，后提交数据库引用。失败可留下未引用文件，不能让已确认引用指向未发布内容。维护覆盖从发布到引用事务结束的完整阶段，备份／回收关闭新准入并排空相关工作和读者，不能误删在途文件。原实验支持其指定夹具条件，不证明掉电和完整产品恢复。

业务状态的 SQLite 与原始资料的本地文件保持不变；外部检索服务按提供者配置接入，不引入对象存储后端。服务自有数据目录不纳入 TinyAGI 文件发布／回收算法，清理由相应维护契约处理；重建取决于仍保留的来源、当前处理许可及服务支持，不能承诺任意历史材料都能重建。Go 驱动默认候选与组合验证范围见上文；生产负载和完整发行尚无验证结论，此为适用边界，不自动新增验证任务或启动产品实现。

4.2.1 个体自定义状态的承载

个体可定义自己的记忆辅助结构、策略状态和工作区内容，宿主在同一 SQLite 中管理其 Self／Mind／模块命名空间、逻辑标识、Schema 身份、结构修订、记录修订、可见范围、写入权限与迁移来源。载荷可用经过声明校验的结构化数据，小文本直接保存，大内容沿文件带类型引用；具体表结构与编码在实现时确定，不增加第二套业务数据库或任意 SQL 入口。

宿主校验归属、结构及版本，个体程序解释主观语义；公共目标、关系承诺、授权和预算仍由原所有者维护，不能因自定义字段同名而获得修改资格。表单描述绑定结构修订，未知结构保留原数据和受限维护视图。程序、Schema、配置与候选转换结果按一致采用边界准备；失败保留旧有效组合，回退也需满足当前状态及在途结果兼容性，不能单独退回旧代码后假定数据兼容。

试验按问题导入所需且获准的个体状态，保留定义、格式修订及必要迁移身份。导入限定支持的格式与程序组合，不自动理解任意扩展或遍历全部依赖；相关状态缺失不能用空载荷掩盖，无关状态不要求全量重建。完整逻辑见个体状态契约与试验初态。此为存储映射，无新增持久化或迁移实测。

4.3 重启、备份与保留

正常重启取得独占运行资格，检查存储和代码身份，恢复已确认状态，接续待办，核对未明效果。旧备份恢复需先停止旧派发，校验数据库、文件清单与代码，记录缺失区间，避免重放可能已经发生的外部动作；换身份不能抹去这段现实历史。

备份包含数据库和全部必要引用文件，不只复制数据库；删除、保留期、派生索引／缓存及备份中的副本分别管理。记录缺失如实可见，不能承诺在线删除清除了所有副本或总能重放。故障矩阵、恢复细节和新增参数实验继续暂缓，完整原规格见工程参考。

5. go-mini 接入与运行版本

go-mini 是嵌入式认知执行库，宿主提供状态、权限、能力和预算，脚本负责上下文、判断及协调。实例、scope、Step、活动和模型会话分别管理。生产与沙箱只装配受控接口，关闭 VM 不等于所有外部工作已停止。

候选程序独立构建，保留代码与来源身份；按业务提交边界和 VM 支持的补丁机制部署。旧闭包／defer 和带类型引用不因命名函数更新而自动升级；失败保留当前已确认版本，不自动重试现实动作。库事实和接口版本以go-mini 核对记录为准，不把上游最新代码与旧实验混用。

影子验证统一使用沙箱：录制重放、真实模型重新评估和反事实模拟分开报告；响应按请求含义匹配，缺环境夹具如实说明。没有完整调度和非确定输入记录，不宣称 VM 级确定重放；代码回滚不撤销现实历史。

沙箱装配的库依据

沙箱接入复用独立实例、受控能力和独立业务状态。对应库行为及其固定源码版本见库接入参考，完整隔离效果仍需在实际装配条件下评价。

试验主体复用正式的认知程序、宿主业务处理及能力端口，差异集中在初态、执行域、提供者绑定和输入输出去向。SQLite 中的试验状态、本地独立文件区及提供者映射按问题装配；宿主仅激活指定工作，不把导入的生产待办、订阅或学习议程直接放入运行队列。源 Self／Mind 身份仅用于追溯，状态读写始终绑定试验域。

初态可使用固定夹具、获准个体状态或已保存的活动状态，导入沿现有格式及兼容机制处理，保留程序和状态修订。完整状态导入按明确用途及支持条件选用，不为每个模块另建必须支持任意克隆的接口。数据库快照只承载已有数据；文件依赖和外部环境仍须装配，不以备份成功证明试验就绪。资料与设计边界

创建后默认暂停，记录所需条件、环境覆盖和实际用量。VM 栈、连接、生产授权、机密原值和外部会话不随初态导入；在途活动测试使用明确的后续输入及替代响应。重置或分支使用新的运行绑定，旧回调不能写入新运行，历史用量和父预算不变；采用只提交有明确范围的候选。独立 Instance 是执行手段，不承诺完整克隆或自动隔离，库事实仍沿固定接入记录解释。

6. 技术选择的一手依据

存储依据：SQLite 使用场景支持将其用于本地应用存储；同步配置说明同步级别及耐久性差异。它们支持机制选择，不证明本项目吞吐或硬件掉电行为。

下面支持能力事实或工程推论，未复现官方性能数据；本机组合实验单独报告。

容器执行与隔离的资料依据

以下为官方在线文档，未固定本项目运行时发行版，也未运行安装、容器、逃逸或性能实验。来源支持机制与适用条件，实际接入须记录所用系统、引擎、执行配置及其能力。

选择容器与 Rootless 优先级属于基于上述资料的工程判断；资料不证明 TinyAGI 的完整约束、远端动作授权、Secret 管线或停止流程已经验证。执行隔离、业务授权与认知沙箱仍分别成立。

外部检索接入的资料依据

Attemory 固定到官方提交 603c03afa9a04e48b778922eae156a0024752f37，该提交的 VERSION 为 0.1.3；仅阅读接口资料，未安装服务或运行检索。向量服务沿既有读取记录，两者的同级接入与用途策略属于本项目设计判断。

资料只支持此提交的公开接口和接入方式，不证明 TinyAGI 已完成适配、授权隔离、材料同步或性能对照。更新组件时重新核对支持操作与差异，保留领域契约，不将提供者内部实现写成本项目职责。

向量服务的资料论证

以下为官方在线文档／仓库，不是已经固定的实验依赖；运行前须记录服务端、SDK 和 embedding 模型的实际版本。Qdrant 是向量路线的初始选择，不决定跨提供者优先级；SDK 接入的判断来自这些契约，没有本项目向量性能实测。