Skip to content

从 1.0.1 升级到 1.2.0 ​

English · 1.2.0 发布说明

本页说明 1.2.0 发布线从 1.0.1 直接升级的要求。1.1.0 没有独立发布,其开发成果纳入 1.2.0,无须先安装 1.1。重复 Call 身份、日志前缀缓存、Python 通知 drain、项目脚本加载信任与终端编辑共同遵守以下兼容和权限边界;公开可用性与正式资格以同版本、提交及准确制品证据为准。

先备份并统一版本 ​

  1. 停止 CLI、SDK、Worker 和写同一状态目录的宿主进程。备份 .coremind/、Session、Checkpoint、Run Store、配置和外部副作用收据;备份应在没有在途写入时完成。
  2. 确认 Node.js ≥ 22.19、Python ≥ 3.10。全部 CoreMind npm 包、Python SDK 与随包 Worker 一起升级到实际发布的 1.2.0;不要先升级一侧继续使用旧 Worker。新版本公开前,不把本页当作 Registry 已可用或安装成功的依据。
  3. 保留 Config v2、Protocol v1/v2 和既有 V4 Session;不要求重写会话正文。新能力按能力协商启用,Protocol v2 必须匹配 Schema 指纹。即使协议大版本相同,指纹或能力缺失也不能靠删字段降级绕过。
  4. 不单独复制 Worker:Linux Shell 所需 vendor/linux-sandbox 和当前架构 helper 必须同包,缺失、摘要不符或系统隔离能力不足时拒绝执行。Python SDK 仍调用同一 Node Runtime,不是纯 Python 实现。

会话、恢复与模型请求 ​

同一规范 Session 的写租约覆盖历史读取、执行、压缩与最终持久化,取消后也要等待在途收尾。第二个 holder 或进程不能在同一会话并发运行;租约依赖支持硬链接的本机文件系统,不支持多机共享目录上的分布式互斥。显式 Session 配置与 ID 在 Runtime 创建时可能创建空会话和公开别名;只读目录可能更早报错。这不代表已经接受输入或发送模型请求。

普通 Run 会在租约内刷新历史;已经持有旧历史的 ChatSession 会在失效水位下拒绝,而非覆盖新内容。重新打开并读取最新会话后,由调用者确认是否提交新输入;不要自动重放结果未知、可能产生外部副作用的旧请求。进程崩溃后的锁恢复须核验 owner,不能只按时间删除仍可能有效的锁。

损坏的 JSONL 尾段按有效 UTF-8 前缀原位截断,保留原文件和硬链接关系;中间损坏或陌生文件身份仍拒绝,不会为继续运行而静默删除历史。历史分支、摘要、操作回执和后续 seq/parent 关系应纳入升级抽查。系统提示和工具声明在请求边界装配,不混入原会话正文。

历史思考按 Provider/API/模型身份进入请求视图;切换模型时不会当普通正文发送不兼容思考。普通回答及工具调用配对保留,原会话不被迁移过滤。模型签名的本地保真不代表真实外部 Provider 已接受该签名。

最终工具参数若是畸形或截断结构,会作为参数错误返回,不补齐结构后执行。完整字符串内允许的转义修复不等于允许缺失字段、括号或字符串。模型收到错误后仍可生成新合法调用;有权限的合法工具继续经过原审批与执行路径。

输出长度上限现在是 failed / model_output_limit,保留部分正文和停止原因;CLI 输出部分正文并失败退出。不得把“有正文”当作成功,也不能沿旧逻辑自动进行下一编排步骤、验证或该响应附带的工具调用。宿主若选择新请求,应先检查已完成效果和预算;Runtime 不自动续写。

明确的网关暂态错误允许有界重试;当前步骤已经开始写入、外部副作用或委派时,整步重放会暂停待人工核对。纯读保留有界重试;委派父回执不能证明子任务无副作用,即使子任务只读也保守暂停。maxRetries: 0 不获得自动重试,认证、配额和未知错误不因本次改动变成可重试。

重复 Call 身份修复已合并并通过双平台 CI。运行行为是在当前 Run 及同 Run 恢复中按 Agent/Step/Call 完整身份拒绝重复调用,保留首次持久事实与原工具绑定;合法的新 Call 身份不受影响。外部工具结果仍须核对,不把拒绝重复调用当作业务幂等保证。

技能、输入控制与 MCP ​

标准技能仍用 agents.<name>.skills 选择目录 ID。内置技能和仅含 README.md 的项目技能维持原注入方式;configDir/skills/<id>/SKILL.md 首先提供索引,正文经原 ToolPolicy 下的 load_skill 按需加载。同 ID 内置优先,双文件选 SKILL 并告警,损坏不回落。源文件上限 256 KiB,解析结果与全部 Agent 冻结快照各上限 2 MiB 序列化 UTF-8 JSON。

Runtime 创建时冻结标准技能,Child 与恢复沿用原快照;修改文件需新 Runtime 生效。丢失或损坏的旧快照不会用当前文件替换。受信原始 Store 包含正文,公开投影/事件/遥测剥离私有旁挂字段;不代表 Session 或业务输出没有正文,也不防宿主改 Store 后重算摘要。技能不授予权限或自动执行 scripts。详见技能指南。

TypeScript ChatSession.steer/followUp(message, options?) 可保留 { controlId, runId },CLI 使用 /steer 文本 与 /follow-up 文本。投递绑定调用时的活动 Turn Runtime,未就绪、已封口或 Run 不符会拒绝,不误投下一轮。忙时普通输入保留草稿,空闲后确认,不自动发送;迟到回执不清除新稿。

控制回执与 input_* 事件分开;applied 不等于 consumed/completed。冷恢复可处理 accepted 控制;applied 但消费未知时明确 discarded,不自动重新投递。持久提交与内存交付间仍有崩溃窗口,不承诺绝对 exactly-once。原输入、Session 和完整对话重建继续遵守恢复门。

MCP 必须显式配置、连接并经过工具权限和预算;HTTP 目标与资源 URI 精确受控,Child 不继承授权。OAuth 是宿主显式发起的 PKCE/state/受控 loopback 流程,不自动开浏览器,401/403 不授权登录。认证只建立连接凭据,不代替工具审批。服务端和本地脚本按其宿主权限执行,不是 OS 沙箱。真实外部服务互通须独立验证。

Protocol v2 返回当前终态的 query、包含当前终态的事件页及过期游标终态投影前会等待该 Run 的宿主收尾,之后同一调用方可启动下一 Run;执行中的并发仍拒绝 worker_busy。历史暂停或旧事件页不代表当前执行已经静止,也不代表所有 Child 业务已处置。

项目脚本加载信任 ​

配置的脚本工具会在 Runtime 初始化时 import,模块顶层与传递依赖具有宿主进程权限。因此存在实际脚本入口时,加载前必须由宿主明确同意;未提供决定、拒绝或回调抛错均以 execution_security_violation 拒绝,取消保持 aborted。没有项目脚本的配置不需要此决定。缺失脚本仍可由原加载器告警跳过;未经本批批准、之后出现的入口不能加载。

TypeScript 宿主使用唯一的 approveProjectCode(request, signal) 回调。请求列出规范项目目录、去重排序的入口路径、入口 SHA-256 与整批 fingerprint。批准范围包含所有实际构建 Agent 的有效全局继承、独立和 deferred 工具;每次真实 import 前再次确认入口。仅对自己已审查的代码返回 true:

ts
const runtime = await CoreMindRuntime.create({
  config,
  configDir,
  approveProjectCode: async (request) => approvedFingerprints.has(request.fingerprint),
});

CLI 的 run、chat、eval 共用这项决定。TTY 默认询问,空回答、拒绝、EOF 和取消都不批准;提示只写 stderr。同一命令进程以完整 fingerprint 复用决定,不保存永久许可。非 TTY 不读取管道内容作为同意;只有显式 --trust-project-code 或 --trust-project-code=true 才允许可信项目脚本,false 明确拒绝,其他值报错。工具的 --permission full 不表示信任脚本。doctor 和 check 保持静态,不 import 项目脚本。

Python 同步和异步客户端增加关键字参数 trust_project_code: bool = False;严格只接受 bool。只有已审核项目才显式传 True。标准 Worker 的 v1/v2 initialize 新增 trustProjectCode boolean,并报告 projectCodeTrust 能力。新 SDK 在发 run/chat 或注册 callable 前要求该能力,即使默认 False 也不能降级到旧 Worker。旧 Worker 需与 SDK 一起升级;v2 schema fingerprint 和默认 Worker 来自同次构建。v1 工具发现挑战的一次重发保留原信任字段。

加载同意不允许工具调用、文件访问、联网、凭据或 Child 权限。工具审批、deny、工作区与恢复安全门继续生效。入口摘要不证明全部传递依赖不可变,也不能防止拥有宿主权限的外部进程在检查后替换文件;本机制不是 OS 沙箱。宿主已加载的生命周期扩展或函数对象不重复询问。直接调用低层 loadScriptTool() / buildTools() 表示调用者已信任指定来源,不能用于绕过配置驱动 Runtime 的加载决定。

修复正常拒绝项目脚本后的 SDK 关闭:仅对入口检查完成且尚未创建 Runtime 的明确拒绝保留原静止状态;读取或工厂失败,以及此前未静止的执行状态,仍按原保守规则处理。

自定义端点认证 ​

只对自定义兼容 baseUrl 端点提供免 key 或仅 Header 认证,内置及原生入口仍要求原凭据。显式 apiKeyEnv、SecretRef 或敏感 Header 引用缺失、空白或解析失败继续拒绝;不能因另一个 Header 可用就匿名降级。

未声明显式 key 时,原 Provider ID 推断环境变量的有效值仍生效;真正匿名需确认该变量未设置。Authorization 的环境变量值应为完整 Bearer <token>,也可按服务协议提供 X-API-Key;显式 Authorization 按大小写不敏感语义覆盖默认 Bearer。免 key 不发送内部占位凭据。不要把敏感值直接写入 YAML;CLI、Python 与标准 Worker 没有凭空新增 SecretResolver,缺少宿主解析器的 SecretRef 仍拒绝。服务端 401 保持认证失败,不自动换来源或登录。

有界输出交付 ​

非 Ink CLI 文本输出与 Worker stdio 采用最多 64 MiB UTF-8 / 1024 条的编码队列(含在途项);关键响应无法交付时报 output_delivery_failed。既有可补读 live 事件按原语义处理,RPC、控制和最终正文不会默丢。等 drain 期间仍处理审批/取消;交付失败后停止接收、取消自身运行并等待已接收工作收尾,不自动重放。

最终 flush 的 10 秒期限不是进程强停保证,也不能强制终止不合作的宿主函数或已经开始的物理写入。SDK 断管可能只收到 WorkerExitedError;运行已有事实不因 transport 错误被改写,取消仍可产生原 aborted 终态。预算不包含模型生成、序列化瞬时分配、Ink 绘制或全进程 RSS。

常驻 Python 通知 ​

Python 提供 client.drain_notifications() / await async_client.drain_notifications(),原子返回并原位清空四桶 events、tool_calls、tool_cancellations、verification_requests。默认 received_* 仍完整保留;返回新 list、浅共享元素,每桶保序,没有跨桶总序。处理或留存整个 batch,并按 runId 分发,不能只取 events 后丢弃待响应事项。

drain 不发 RPC、不启动 Worker,可在 start 前/close 后取已有历史;不是服务端 ack,不回答工具、取消或验收,也不清 callback 队列或消除过载。MCP 认证保持专用 handler。复制是 O(N),async 也在原 loop 本地执行;主动消费有助释放已接收对象,但没有自动内存上限。

v2 durable 补读是独立合同:按每个 runId 处理 events 页成功后保存该页实际 nextCursor;live notification 的 sequence 不是 durable cursor,不能混用或加一推算。drain 不推进游标,空页不代表终态,durable 事件不保证原样重放每条专用通知;过期游标按 recovery details 处理,不静默从零重播。v1 不具备 v2 durable 补读。

日志成本与终端编辑 ​

关键日志前缀优化只降低已验证前缀命中的解析/序列化重复:仍完整读取并精确比较原文字符串,仍全量写临时文件、同步和原子发布。缓存总正文预算为 4 MiB UTF-8、至多 64 个 cursor,不是总堆上限;无整体生产吞吐或时延收益承诺,无日志分段或存储格式迁移。

TUI 提供字素光标、中段插入/退格、整稿 Home/End,以及当前界面最多 50 条已接纳普通输入历史;Up 留存草稿,Down 越过最新恢复。slash 命令、审批输入和未接纳忙时输入不进入历史。审批冻结普通稿与历史,paste 不直接批准,先对完整文本脱敏再显示光标。历史仅内存保留;不承诺 Delete/词移动、视觉行 Home/End、外部编辑器或全部输入法兼容。原输入上限仍为 16,384 字素 / 65,536 UTF-8 字节,超限整段拒绝。

验收后切换与回滚 ​

先在备份副本检查旧会话恢复、分支/摘要、租约冲突与合法追加,再验证允许/拒绝的真实工具、输出长度终态、取消收尾和下一个 Run。对用到的脚本信任、自定义认证、通知消费与 MCP 单独验收。受控本地夹具不替代外部 Provider/OAuth/MCP 互通;正式发布必须取得绑定同一最终提交的严格 Provider、双平台稳定性/覆盖率/PTY 与准确公开产物回装证据。

失败时停止新进程;统一退回实际发布的 1.0.1 程序、SDK 与 Worker,恢复升级前配置和持久状态备份。新旧进程不得并发写同一状态目录;旧程序不得继续写含其不认识事实的新日志。先人工核对外部副作用再决定是否补偿或重试,恢复本地备份不会撤销外部操作。公开资产不可覆盖;部分发布只能按原身份继续复用相同资产,不能重建不同的同版本包。

Last updated:

Released under the MIT License.