Yeaft

中文

English

中文

English

Appearance

原生 Yeaft Engine ​

原生 engine 位于 agent/yeaft/，不依赖 Claude Code 或 GitHub Copilot CLI。它拥有自己的 LLM adapter、Session/VP 编排、tool loop、memory、persistence、sub-agent、background job 和 Work Center runner integration。

本页面向开发者。产品行为请阅读 Yeaft Session 与 Project 和 Work Center。

主要模块 ​

text
agent/yeaft/
  engine.js             query/tool loop、retry、folding、persistence
  session.js            加载一个 engine context 与配套子系统
  web-bridge.js         Web Session/VP 与 event bridge
  cli-session-runner.js transport-neutral multi-VP CLI Session runner
  sessions/             roster、store、coordinator、pre-flow、CRUD
  projects/             Agent-side Project context store
  vp/                   VP library、persona loader、default、registry
  llm/                  adapter router、Anthropic、OpenAI Responses、credential
  memory/               保留但禁用的 H2-AMS 实现
  conversation/         持久 message 与搜索
  tools/                33 个内置工具定义和 registry
  sub-agent/            child-agent runner、log、liveness、notification
  tasks/                持久 background shell job
  work-center/          WorkItem/Action/Run planner、store、watcher、runner
  tool-folding/         执行日志、重复提示与旧 reflection 兼容 helper
  history-window.js     确定性 history window 与执行期工具结果 compact
  dream/                保留但禁用的 maintenance 实现
  archive/              大型/raw turn 与 tool-result archive helper
  templates/            双语 base、unified、保留的 dream、plan、persona prompt

一个原生 turn ​

普通 VP turn 按以下步骤运行：

  1. Pre-query — 解析 Agent/Session/VP/Project identity、project instruction、runtime platform、pending child-agent notification、project docs 与当前 Session 的有界 history。
  2. 构造 context — 组合 system prompt、VP persona、确定性的有预算 history window、当前 user content 和支持的 attachment。Web Session 只保留有界的临时 runtime cache，完整 transcript 仍由 ConversationStore 持有；不再从磁盘加载 LLM 对话摘要。
  3. Stream LLM — 选择配置的 provider/model，调用 Anthropic Messages 或 OpenAI Responses adapter。
  4. 执行工具 — 通过 ToolRegistry 运行允许的 call，append result block 并继续 stream。
  5. 按压力 compact — 当前 turn 超过实际模型窗口的剩余预算（已计入 system、schemas 和 output reserve）时，先压缩 provider 副本中较旧的 tool-result 文本。保持工具配对和 persistence/debug 原始输出；不再周期性 reflection，也不额外调用执行期摘要模型。仍超限时使用确定性的工具协议单元裁剪和有界 overflow recovery。
  6. 结束 — 持久化 message、usage、trace、task state 和 terminal result；确认已注入 notification；可为后续 history window 生成独立的 turn 后 compact。
  7. 恢复 — 在配置上限内 auto-continue max_tokens；context error 直接暴露，不触发隐藏摘要调用；分类为 retryable 的 failure 可以切换 eligible fallback model。

Abort signal 会传入 adapter 和 tools。Engine 区分 user abort、auth error、rate limit、server failure、idle timeout 与 context failure，不把所有 stop 当成 generic error。

活跃、进展与交付 ​

Provider 静默 watchdog 只判断流是否活跃，不是 query 的总时长上限。独立的 query-local 观察器在完整工具批次完成后检查相同参数和结果、重复失败，不用时长或请求次数单独终止有用的长任务。

  • 首次成功观察或结果变化是新证据；分页和范围不同的读取独立计数。不同候选的首次负向读取（例如文件不存在）也是排除范围的证据，参数、权限和不确定错误除外。新写入使先前读取失效，但相同写入及确认不反复算进展。证据不等于验收完成。
  • 连续 4/8/12 个没有新证据且包含重复或失败的批次，分别提示、要求恢复、保留一次无工具收尾响应。收尾原因是 no_progress，不能投影为任务成功；用户追加输入和取消沿用正常关闭契约。收尾期间接受的本轮后台结果会恢复工具执行并先消费结果；终止决定之后到达的结果交给 coordinator 恢复路径。
  • 等待、用户确认、展示和显式允许的实时观察不累计停滞。WebFetch 仅在用户要求等待外部任务时显式设置 polling: true；raw 只改变响应格式，不豁免普通文档/API 的重复检测。
  • 相同失败达到三次后阻止原样重放；非只读操作的 errorEffect: unknown、replaySafe: false 或兼容超时/断连错误首次出现后即禁止原样重放，应先验证目标状态。新输入或成功写入不自动解除不确定副作用保护。唯一的已结束命令分类要求 Bash 明确返回非零退出、未超时且确认进程终止：它仍不立即重放，但在成功修复或新输入后可重新验证；这不代表失败命令已回滚。
  • HistorySearch 默认排除当前用户消息及其后的记录，边界在命中上限之前应用；includeCurrentTurn: true 可显式回看本轮。兄弟 Session 不使用当前 Session 的序号边界。
  • SpawnAgent 复用当前 query 内相同 owner/workspace 和任务规格的委派；显式 taskKey 的规格变化报冲突。接受 PromptAgent 后续任务或收尾控制后，原身份保留，但原规格重试被拒绝，不能把 Agent 的最新回复当作原委派证据；已领取的原回复或原日志仍可查阅。WaitAgent 可逐 revision 领取后续回复。

Web Session 状态区显示请求、工具执行、复用、重复和失败计数。query_progress 只包含白名单元数据，不进入 transcript、模型历史或 provider watchdog；重连隐藏旧计数，终态后的延迟事件不能复活 turn。

Session 与 VP 编排 ​

Session coordinator 根据 roster 解析接收者：

js
const recipients = resolveVps(mentions, roster, defaultVpId);
await Promise.all(recipients.map(vp => runVpTurn(session, vp, input)));

真实 API 还有 identity、attachments、quoting、routing 和 persistence 字段；这个 pseudocode 只展示 fan-out。关键规则是：

  • 每个 turn 只持久化一条 canonical user message；
  • 没有 mention 时发送给 default VP；
  • 显式 mention 发送给匹配的 roster member；
  • 每个 selected VP 有独立 engine/persona/memory context；
  • VP event 保留 sessionId、vpId、turn/thread identity 与 source order；
  • Peer handoff 使用 RouteForward tool 与 loop guard，不依赖文本 mention。

Web path 使用 web-bridge.js。直接运行的 yeaft CLI 使用 transport-neutral Session runner，使 Session ID 和 multi-VP 语义一致。

Prompt 构造 ​

prompts.js 组合：

  • templates/base.md、identity-yeaft.md 和 common-rules.md；
  • 唯一的 interactive mode-unified.md contract；
  • plan operation 的专用 instruction，以及不再 dispatch 的保留 Dream template；
  • selected persona 与 VP metadata；
  • runtime platform metadata；
  • project docs 与 Project instruction；
  • 可选 harness-level instruction。

历史 interactive mode 已收敛进 unified contract。Dream 已禁用；旧 dispatch 命令返回 disabled。

LLM adapter ​

AdapterRouter 按以下优先级解析 provider 与 protocol：

  1. per-model protocol override；
  2. provider protocol；
  3. model-ID heuristic；
  4. OpenAI Responses fallback。

支持的 protocol 是 anthropic 和 openai-responses。Provider entry 可以使用静态 apiKey 或已支持的 dynamic credential provider。Context/output limit 来自 model override、bundled catalog 或保守 default。Model effort 会在支持时转换成 Anthropic thinking/output effort 或 OpenAI reasoning effort。

参见原生 LLM 层。

工具系统 ​

createFullRegistry() 当前注册 33 个内置工具：

  • files 与 patch；
  • grep/glob/directory/disk/history search；
  • foreground/background shell job 与 task log；
  • Git worktree enter/exit；
  • Web search/fetch、local image view 与 image generation；
  • JavaScript REPL 与 notebook edit；
  • planning、visible todo 与 user question；
  • 持久 WorkItem 创建；
  • sub-agent spawn/prompt/wait/list/close 与显式 VP routing；
  • Skills。

MCP tool 在 runtime 添加。Registry policy 可以针对当前 execution context deny tool。

Tool event 与 raw result 会持久化用于 audit/debug。进入 context 的表示另有预算，并可能 fold 或变成 archive stub；UI truncation 不表示 raw record 已丢失。

已退役的 H2-AMS memory ​

Dream/H2-AMS 模块和旧数据为兼容与技术追溯保留，但当前 runtime 不迁移、同步、读取、召回或注入它们。交互 turn 与 Work Center 使用各自当前的数据来源。旧 enable/manual 命令返回 disabled；Web debug surface 不再有 Dream tab 或设置。历史真实消息与常规 debug 记录保持不变。Turn 后 compact 是独立且仍启用的 history-window 能力。

参见 已退役的 H2-AMS 实现。

Background task 与 sub-agent ​

  • Bash 使用 background=true 会创建带 log 的持久 Session task。
  • ListTasks、ReadTaskLog 和 CancelTask 操作这条 record。
  • Agent restart 后，未解决的 process handle 会标为 orphaned，不会假装仍可控制。
  • Sub-agent 有自己的 output log、liveness counter、可选 budget 和 terminal/idle notification。
  • Terminal notification 是 parent re-entry control context，不是新的 user-authored semantic memory。

Work Center integration ​

Work Center 通过 runner adapter 复用 Engine.query()，不实现第二套 LLM/tool loop。Run 会冻结 Action、VP、model/effort、tool-policy、workspace 与 attempt identity。Structured completion tool 提交 completed、waiting、retryable 或 failed；普通 model turn_end 不能推进 Action。

Coordinator 使用相同 model infrastructure，但其 decision contract 受限，没有 file/shell/external side-effect tool。

Persistence 与兼容 ​

Agent-local Session metadata、history、memory、tasks 和 Work Center data 位于解析出的 Yeaft directory。Session 的 workDir 只是 project context。

旧 wire alias、payload identifier 和 storage scope prefix 会在修改可能破坏已部署 client/data 的地方保留。新代码使用 Session/Yeaft 术语，canonical Session memory layout 是 sessions/<id>；迁移期间 reader 仍可能处理 legacy session/<id> 与 group/<id> alias。

验证映射 ​

Test tree 按 subsystem 组织，不再使用历史 phase 文件：

  • test/agent/yeaft/ 覆盖 compact、conversation、memory、Sessions、sub-agent、tasks、tool folding、Work Center 等模块；
  • test/agent/yeaft-*.test.js 覆盖 cross-module native-engine behavior；
  • test/server/yeaft-*.test.js 与 test/web/yeaft-*.test.js 覆盖 relay/UI integration；
  • e2e/ 覆盖 browser-visible flow。

当前 repository-wide gate 使用 npm test、npm run test:e2e 和 npm run release:guard。

Released under the MIT License.

Copyright 2024-present Yeaft