Agent 教程

外观

示例：Minimal Agent ​

这是一个可运行的最小 Agent demo。它不依赖真实模型 API，默认使用 MockModelClient 演示：

text
用户输入
  -> mock model 生成 tool_use
  -> ToolExecutor 执行 read_file / list_files
  -> tool_result 写回 messages
  -> mock model 给出最终回答

运行 ​

在本目录执行：

bash
node src/cli.js "请列出文件并读取 hello.txt"

也可以运行测试：

bash
node --test test/*.test.js

如果你的本机 node 不可用，可以用 Codex runtime 的 Node：

bash
/Users/huangnv/.cache/codex-runtimes/codex-primary-runtime/dependencies/node/bin/node src/cli.js "请列出文件并读取 hello.txt"

文件结构 ​

text
src/
  agent-loop.js       # ReAct 主循环
  cli.js              # 命令行入口
  messages.js         # Message 和 tool_use 工具函数
  mock-model.js       # 无外部 API 的 mock model
  permissions.js      # PermissionGate
  session-store.js    # JSONL 会话日志
  tool-registry.js    # ToolRegistry
  tools.js            # read_file / list_files / write_file
fixtures/
  hello.txt
  notes.md
test/
  agent-loop.test.js

教学重点 ​

这个 demo 有意保持简单：

  • read_file 和 list_files 是只读工具，默认允许。
  • write_file 是写工具，默认拒绝。
  • --mock-write 会让 mock model 请求 write_file，用于演示权限拒绝。
  • --yes --mock-write 会允许写入 fixtures/generated.txt。
  • 工具失败也会生成 isError=true 的 tool result。
  • 会话写入 .sessions/<session-id>.jsonl。
  • mock model 只用于演示工具闭环，不代表真实模型能力。