跳到主要内容

Core v0.2.4

2026-09-05 · Tag steamharness/v0.2.4 · npm

新特性​

  • Agent 能力层：基于 pi agent SDK 新增 workflow.createAgent(...)、createAgentNode(...) 与对话 executor。
  • 跨轮会话恢复：pi 的 AgentMessage[] 存入 agent.transcript.<sessionKey>，下一轮写回 initialState.messages。
  • 关联项目知识库与入口调用：relatedProjects.get(alias) 提供目标项目的知识库与入口调用，授权逐 key 判定。

新增​

  • 新增 输出协议支持 contentType: "video"，保留视频描述对象与流式 output item 类型。
  • 新增 workflow.createAgent(...) 可编程驱动的 agent 运行时。
  • 新增 workflow.createAgentNode(...) 放进任意 workflow 的 agent 节点。
  • 新增 workflow.defineAgentConversationExecutor(...) 一步生成完整 conversation executor。
  • 新增 该 executor 含 conversation 配置、token usage、工具、参数与 OpenAI 网关对接。
  • 新增 需过结构校验的项目可用 createAgentConversationProject(...) 与 createAgentProjectParams(...) 拆分形式。
  • 新增 Agent 输入支持 prompt、images、workdir、provider、model 与 baseUrl。
  • 新增 Agent 输入支持 effort、agent、permissionPolicy、contextWindow、compact 与审批恢复载荷。
  • 新增 effort 取 off 到 max，ultra 等同 max，超出模型支持范围自动收敛。
  • 新增 agent 取 build 或 plan，plan 模式正文只渲染成一条 Plan 行并在轮末请求批准。
  • 新增 plan 审批沿用 decision 单选与可选 instructions，批准后在同一会话以 build 模式继续。
  • 新增 permissionPolicy 取 read-only、workspace、auto，三者都不为内置工具弹审批。
  • 新增 输出项使用 agent-part、agent-notice、agent-error、agent-answer 中性 metadata.kind 族。
  • 新增 输出 payload 带 contextUsage: { used, total }，宿主据此显示已用与总量并提供压缩入口。
  • 新增 --context-window 覆盖上下文用量分母。
  • 新增 工具审批复用 context.toolPermissions，plan 审批复用 context.userInput。
  • 新增 token 用量经 context.tokenUsage.report(...) 上报一次，项目侧无需实现。
  • 新增 依赖 @earendil-works/pi-agent-core 与 @earendil-works/pi-ai，宿主安装 steamharness 即自带。
  • 新增 AgentNodeOptions.createTools 可返回 { tools, close?() }，close 在本轮结束时调用。
  • 新增 AgentNodeOptions.createTools(context) 组装内置 7 个工具之外的工具，编程式运行时用 AgentRuntimeOptions.extraTools。
  • 新增 AgentInput.systemPrompt 逐轮给出本轮系统提示词，AgentInput.images 随 prompt 发给模型。
  • 新增 workflow.connectMcpServer(...) 启动并握手 stdio MCP 服务并列出其暴露的工具。
  • 新增 workflow.createMcpTools(...) 把 MCP 工具变成 agent 工具，名字保持 <服务 id>_<工具名>。
  • 新增 workflow.normalizeMcpServers(...) 在启动任何子进程之前校验服务定义。
  • 新增 带能力的变量只能按名继承：allowedInheritedEnvKeys 列出允许项，inheritEnvironment 申请。
  • 新增 workflow.createProjectCapabilityTools({ context }) 渲染能力为 agent 原生工具。
  • 新增 workflow.createProjectCapabilityServer(toolId, { context }) 渲染同一能力为 MCP 服务端。
  • 新增 workflow.runProjectCapabilityAction(toolId, context, args) 按工具 id 直接执行，供审批恢复使用。
  • 新增 workflow.listProjectCapabilityToolIds({ globalMemory? }) 列出本次运行会提供的工具。
  • 新增 workflow.isProjectCapabilityAvailable(toolId) 报告能力在当前进程能否工作。
  • 新增 四个内置工作流能力工具：知识库、KV、跨会话记忆与宿主配置，工具 id 与内置 OpenCode 项目一致。
  • 新增 workflow.createSkillTools({ directories, approve? }) 把技能做成按需读取的工具。
  • 新增 workflow.runSkillAction(directories, args) 供审批恢复时按名字重跑同一动作。
  • 新增 KV 与 PersistentValue namespace 的 deleteValue(key)，返回是否真的删除了已存在的条目。
  • 新增 plan 模式 agent 的内置工具 ask_user，可中途提问并支持选项、多选与自定义回答。
  • 新增 参数定义可声明 step 把多问题请求分步，同一问题的字段留在同一步。
  • 新增 relatedProjects.get(alias) 的知识库 helper，作用于目标项目的文档读写。
  • 新增 listEntrypoints() 与 runEntrypoint(id, args) 列出并调用目标项目授权的入口。
  • 新增 关联项目授权字段 knowledge: { read, write } 与 entrypoints，不写即不授权。
  • 新增 modelAttributes 让自定义 provider 声明 contextWindow、maxTokens、cost 与 thinkingLevelMap。
  • 新增 Workflow entrypoint 静态 group: { id, title, order? } 展示元数据并透传到结构报告。
  • 新增 参数契约支持 type: "file", control: "audio" 及音频时长与大小限制。
  • 新增 Conversation 默认输入契约的视频附件与常用视频 MIME 推断。

变更​

  • 变更 Agent 会话正文写在被说出的位置，每段文字成一条 agent-part 文本行。
  • 变更 宿主驱动的运行保持原样，conversation.openai.outputItemId 声明的条目只在其中产出。
  • 变更 一轮内的输出项按结束顺序排列，工具与推理在前、正文停在真正写完的位置。
  • 变更 plan 模式的工具审批才暂停运行，build 回合执行已批准计划时不再弹确认。
  • 变更 运行报告的错误信息附带上游 HTTP 响应体摘要，只带状态短语的错误不再掩盖原因。

修复​

  • 修复 Agent 会话上下文从未实现，每轮用户消息是新进程，模型只看得到本轮那一句。
  • 修复 恢复的记录超过模型窗口时请求直接失败，现在调用模型前按需自动压缩。
  • 修复 被取消或中断的轮次留下未回答工具调用的消息导致 provider 拒收，落盘前修剪未收尾尾部。
  • 修复 agent.transcript.<sessionKey> 读写失败不再让整轮失败，改以一行说明代替。
  • 修复 Agent 类项目的 OpenAI / Responses 适配器必然以「did not produce output item」结束。
  • 修复 createAgentConversationProject({ outputItemId }) 不再按会话派生 id，改用声明的 id。
  • 修复 工作区内的软链接可让 read / write / edit / grep / find 访问工作区之外的路径。
  • 修复 bash 超时或中止只结束 shell，现在连同整棵进程树一起结束。
  • 修复 取消运行未真正中止本轮，context.abortSignal 现在调用 pi 的 agent.abort()。
  • 修复 read 把整个文件读进内存，超过 8 MiB 按请求行区间流式读取。
  • 修复 edit 把 $&、$' 当替换模式展开，改为字面量替换。
  • 修复 上下文压缩切分点可能把整份记录（含当前任务）交给摘要。
  • 修复 /compact 在没有可压缩内容时闪现压缩行。
  • 修复 effort 传空字符串被当作档位，OpenAI 类端点因此收不到 reasoningEffort。
  • 修复 上下文用量按 4 字符 1 token 估算，中文此前被低估约 3 倍。
  • 修复 kv_store 能写入运行时自己的 tokenUsage.*、conversation.state 与 agent.* 键。
  • 修复 能力声明的长度上限（知识库、记忆与 KV 的 markdown、title、query、cursor、key）未在实现里执行。
  • 修复 跨会话记忆的 cursor 在 list 与 search 语义不同，返回值不带 list: / search: 前缀。
  • 修复 宿主配置回环桥地址不合法时抛异常打断其它能力，isAvailable 现在返回 false。
  • 修复 MCP 服务发布的工具 schema 非对象、过深或超过 256 KiB 时在注册阶段压垮进程。
  • 修复 MCP 工具总数上限在合并分页之后才检查。
  • 修复 MCP 工具列表分页遇到重复游标时无限请求，现在重复游标直接报错。
  • 修复 宿主配置 values 丢失键与值校验，越界参数不再穿透到宿主桥。
  • 修复 skill 文件清单被 60 条上限截断时不作说明。
  • 修复 节点输出的 workdir / provider / model / effort / agent 取自运行时选项而非本轮输入。
  • 修复 createAgentInputFromArgs 把不认识的 --flag 及其取值拼进 prompt。
  • 修复 只调用工具、没有正文的一轮往 conversation 写入空 assistant 消息。
  • 修复 带 hostInput 的一轮同时写 workflow conversation，宿主会话记录被写两份。
  • 修复 自定义端点写进进程级模型目录，同一 id 的两次运行互相覆盖端点与凭据。
  • 修复 AgentInput.workdir 只影响输出 payload，内置工具仍在建运行时的工作区内操作。
  • 修复 图片附件在进入模型前消失，宿主传来的 imageFiles 现在读成 base64。
  • 修复 只发图片、没有文字的一轮以 Prompt is required. 结束。
  • 修复 --images 对 defineAgentConversationExecutor / createAgentProjectInput 形态的项目被吞掉。
  • 修复 智能体的模型调用没有重试预算，第一次 502 或流中途断开就终止整个 run。
  • 修复 模型在回答中途断流时整轮以 terminated 失败，现在续写并保留已生成内容。
  • 修复 被模型输出上限截断的一轮被当成正常答完，现在走续写通道且预算独立为 2 次。
  • 修复 宣告了工具调用、调用却没传过来的消息被当成成功的纯文本回答。
  • 修复 模型流没有收尾就结束时本轮永远挂着，现在合成为可恢复错误。
  • 修复 reasoning 攒到整轮结束才输出，高 effort 模型思考期间宿主一行都拿不到。
  • 修复 关联项目的知识库写入绕过按 key 授权，在 mutation 路径上索引与文档可直接改写。
  • 修复 readEntrypointOutput(...) 把失败的入口结果当成 payload 返回。
  • 修复 关联项目知识库不可达时只说「关系未确认」，不说宿主缺少持久值句柄。