主动与学习

InitiativeCoordinator复制本节链接

协调器接收项目观察，调用真实模型在 wait、work、share、learn 之间选择。宿主提供每种动作的执行函数和持久化。

import { InitiativeCoordinator } from './packages/sdk/src/index.mjs';

const initiative = new InitiativeCoordinator({
  project,
  model,
  apiKey,
  provider,
  handlers, // work / share / learn 的宿主实现
  policy: {
    tokenBudget: 200000,
    decisionMaxTokens: 2048,
    workBudgetTokens: 24000,
    maxConcurrent: 1,
    cooldownMs: 10000,
  },
  saveState: (state) => writeJsonAtomically(statePath, state),
  onEvent: emit,
});

await initiative.observe({
  id: 'project-opened:1',
  type: 'project_opened',
  summary: '用户刚创建项目，尚未下达具体任务。',
});

const result = await initiative.tick({ presence: { typing: false, activeTurn: false }, signal });
await initiative.idle();

writeJsonAtomically、handlers 和 emit 由宿主实现。presence 应该传入真实的输入状态和当前轮次：它只影响发言时机，不影响后台判断。

完整可运行示例：

node packages/sdk/examples/proactive-project.mjs \
  --model ./model.json \
  --title "离线备份工具" \
  --description "给独立开发者设计可验证、可恢复的备份流程" \
  --workspace ./packages/sdk --interactive

挡下重复的工作复制本节链接

宿主可以提供 workCheck 钩子。模型决定 work 之后、入队之前调用它：判定为已覆盖时这项工作不入队，按“重复意图”处理，复查退避；lastDecision、结果和事件里带 admission，下一次决策在请求末尾看到 previousDecision。钩子出错时一律放行。Rna 宿主用它接入 JEV 的 work.coverage 判断。

其他宿主钩子复制本节链接

• messageCheck(decision)：对 share 和 ask 的文字做宿主检查，返回违规项时模型会被要求重写。
• decisionReasoning(input)：宿主为这次决策选择推理强度，返回 { reasoning }；不返回或抛错时沿用模型自己的设置。
• policy.notificationMuted：静音。收件箱和摘要层级的分享照常，对话内和通知层级的分享与提问被挂起。

长期运行复制本节链接

• decisionTimeoutMs、actionTimeoutMs 与独立的故障退避。
• archiveHistory({ actions, seenEventIds }) 成功后才裁剪热历史；没有归档回调时不会删除历史。
• 忽略取消的自定义函数会被隔离，未知副作用保持 needs_review，不会靠自动重试伪造恢复。

LearningCoordinator复制本节链接

宿主提供 saveState、review、execute，通过 ingest() 录入身份稳定的轻量经验。tick() 先持久化 claim，再调用模型。

每次反思必须明确选择一种结果：

同一证据连续反思失败会退避，第三次后进入 awaiting_evidence；只有真正接受的新外部证据才能解除等待，重复的 ingest 或计时器不算新证据。重启时未结束的反思和实验标为 interrupted，未知实验不会被自动重放。

EvolutionCoordinator复制本节链接

冻结项目基线，调用宿主的评测器，对相同案例分别执行基线和候选。满足提升、安全、成本和无退步门槛后，才发布 evolution_candidate_ready 事件。试用、晋升和回滚都由宿主显式调用；SDK 不把候选模型自己的评分当作评测。