跳转至

TypeScript 版

TypeScript 版增加了模型 token streaming、异步工具、取消信号、生命周期 hooks、 ContextBuilder、动态 Skill 和 Sub-agent adapter，适合 Node.js 与 Web 应用。核心文件 均包含中文注释，也会解释新人不熟悉的语法。

MiniMax provider 实现了 Anthropic-compatible SSE；其他 provider 只实现 generate() 也仍然可用。streaming 产生 textDelta、thinkingDelta 和 toolArgumentsDelta，完整消息结束后才进入 Agent history。

只先认识五个语法

语法 含义
type A = ... 给一类数据起名字
x?: string 字段可以不存在
A \| B 值可以是 A 或 B
Promise<T> 未来才会得到一个 T
async function* / yield 异步地逐个发出事件

不需要先系统学完整门语言。带着这张表阅读 src/core/types.ts 和 src/core/agent-loop.ts 即可。

运行

npm run dev

完整检查：

npm run check

选择会话存储

# 推荐用于持续使用
AGENT_MEMORY_DATABASE=.agent-data/conversations.sqlite3

# 或者选择便于直接阅读的 JSON；不要同时设置
# AGENT_MEMORY_FILE=.agent-data/conversations.json

SqliteConversationStore 使用 Node.js 22 内置的 node:sqlite，不增加 npm 依赖。每个 session 是一行 JSON messages，数据库负责事务和写锁；切换后端不会改变 Agent 或 agentLoop()。

高级 memory 分为两个可组合 wrapper：TokenContextBuilder 使用注入的 provider tokenizer 裁剪完整轮次，并可用 SummaryProvider 摘要旧历史；MemoryRecallContextBuilder 从 MemoryIndex 召回 episodic、semantic、procedural 记录。开启本地索引：

AGENT_MEMORY_INDEX_DATABASE=.agent-data/memory-index.sqlite3
AGENT_MEMORY_RECALL_LIMIT=5

Skill frontmatter 支持 version、dependencies、tags 和 tools。auto 模式使用 BM25-like 路由，也可注入 ModelSkillRouter；模型路由结果不能绕过 Catalog 和工具白名单。

Stage 4/5 位于 src/subagents/ 和 src/graph/。runSubagent() 统一 depth、turn、token、 timeout、取消、上下文选择和结构化 handoff；scheduler/event bus 组合多个 child。 StateGraph 独立提供条件 edge、fork/reducer、checkpoint 和 interrupt/resume，不影响 基础 agentLoop() 的可读性。

Stage 6 位于 src/evolution/。EvolutionController 把 propose、固定 eval/holdout 对比、 人工 approve、publish 和 rollback 分开；ArtifactStore 与 ArtifactEvaluator 都可替换， 不会把某个数据库、模型或 judge 藏进核心流程。

Stage 7–9 分别位于 src/evals/、src/web/playground.ts 与 src/workspace/。Eval CLI 可在 CI 中重放 JSONL fixture；Component Lab 展示真实组件状态；Workspace toolkit 默认只读， 长结果通过 artifact 分段读取。

Stage 10–12 位于 src/mcp/、src/structured-output/、src/routing/ 与 src/durable/。 MCP discovery 先经过 server namespace 和 tool allowlist，再成为普通 Tool；结构化结果在 repair 前后都由宿主校验；模型路由按 generator/judge 分开计量。Durable Runtime 继续使用 Node 内置 SQLite，保存 graph checkpoint、幂等 task、worker lease 和事件日志。

hooks 放在哪里

  • beforeModel：加载 memory、压缩 context、选择 skill；
  • beforeTool：权限、参数校验和人工审批；
  • afterTool：审计、指标和长期记忆。

hooks 可以改变上下文，但不应该偷偷推进下一轮。这样所有控制流仍能在一个文件中追踪。

快速启用 Context 与动态 Skill

# 只限制本轮发给模型的快照，完整历史仍会持久化
AGENT_CONTEXT_MAX_MESSAGES=40
AGENT_CONTEXT_MAX_CHARACTERS=50000

# 根据最新用户输入匹配少量 SKILL.md
AGENT_SKILLS=auto

RecentContextBuilder 使用字符数近似 token 数并保留完整轮次。AGENT_SKILLS=auto 使用确定性关键词匹配，适合学习和小型 skill 集合，不等同于语义检索。

配置模型请求速率

AGENT_RATE_LIMIT_MAX_REQUESTS=60
AGENT_RATE_LIMIT_WINDOW_MS=60000

这会平滑为约每秒一次请求，状态在同一个 Agent 的多次 run() 间共享。CLI/Web 收到 rateLimitWait 后会显示具体等待时间，取消请求也能中止等待。

顺序或并行执行工具

AGENT_TOOL_EXECUTION=parallel

默认值是 sequential。并行模式用 Promise.all 重叠执行工具，但结果仍按模型生成 tool call 的顺序写入 Context。只有确认工具彼此独立、没有共享写入时才应开启。

配置一次任务的预算

AGENT_MAX_TOTAL_TOKENS=120000

# 需要成本预算时取消注释，并填入当前套餐的真实数字
# AGENT_MAX_COST=10
# AGENT_COST_CURRENCY=CNY
# AGENT_INPUT_COST_PER_MILLION_TOKENS=
# AGENT_OUTPUT_COST_PER_MILLION_TOKENS=

预算在每次 Agent.run() 时重新计算。MiniMax provider 会返回 usage，因此 CLI 和 Web UI 能展示累计 token 和估算成本；实验性的 Codex CLI 后端不提供可核验的 usage，配置预算时 会直接拒绝启动，避免显示一个不可信的数字。价格请按你的当前套餐自行填写。

预算在一次响应结束后才更新，所以它会阻止的是下一次模型调用，而不是截断已经开始的 响应。需要账户级硬额度时，应同时使用模型平台的限额和服务端持久化计量。

开启 Trace

AGENT_TRACE_FILE=.agent-data/traces.jsonl

每次 Agent.run() 会产生一个 agent.run 根 span；模型请求与工具调用分别成为 gen_ai.chat 和 execute_tool <name> 子 span。默认不保存 prompt、工具参数和结果。 TraceExporter 是可替换接口，JSONL 只用于教学和单机调试；完整字段与接入生产 OTel 的 边界见“可观测性与 Trace”。

Stage 16：Governed Memory

src/memory-consolidation/index.ts 把原始 Episode 与抽象 ConsolidationCandidate 分开保存。evaluate() 检查支持证据、反例、适用标签和固定 replay； 只有通过 gate 的版本才能由带身份的调用者 activate()。当前任务标签传给 active(tags) 后， 再用 applyGovernedMemoriesToPrompt() 注入带 episode 引用的记忆。