A 常见错误与排查速查表
| 报错/现象 |
原因 |
解法 |
init() requires an agent created with createAgent(...) |
把配置对象直接丢给 init() |
先 createAgent()，再 init(agent) |
Invalid model "xxx" |
少了 provider/ 前缀 |
用 deepseek/deepseek-v4-flash |
403 Forbidden（Anthropic + DeepSeek） |
端点不兼容 |
用内置 deepseek provider 或改 baseUrl |
registerProvider 不生效 |
写在 Agent 文件里 |
移到 src/app.ts |
Agent "xxx" not found（flue run） |
文件在 workflows/ |
flue run 只认 agents/ |
| dev 服务器老断连 |
监听所有根文件 |
用生产模式 npm start |
TypeError: Cannot read properties of undefined |
valibot 0.x |
升到 valibot@^1.0.0 |
harness.fs is not a function |
Agent 里用了 harness.fs |
改用 harness.env.writeFile |
B 核心 API 速查表
| API |
作用 |
关键注意 |
createAgent(fn) |
定义 Agent |
返回函数，文件名即 Agent 名 |
defineTool({...}) |
定义工具 |
参数用 Type，execute 返字符串 |
defineAgentProfile({...}) |
定义子智能体/档案 |
name、instructions 必填 |
init(agent, opts?) |
初始化运行环境 |
只接 createAgent() 结果 |
session.prompt(msg, {result}) |
发消息 |
带 result 直接返数据 |
session.task(msg, {agent}) |
派给子智能体 |
在独立子会话执行 |
connectMcpServer(name, {...}) |
接 MCP |
工具名前缀 mcp__名__工具 |
dispatch(agent, {id, input}) |
异步投递 |
不等回复，返回 receipt |
observe(fn) |
全局可观测 |
写在 app.ts |
local() |
本地沙箱 |
从 @flue/runtime/node 导入 |
阅读指南
| 时间 |
章节 |
目标 |
| Day 1 |
§01-§03 |
从零到第一个会干活的 Agent |
| Day 2-3 |
§04-§07 |
吃透 Harness 五个零件与核心能力 |
| Day 4-5 |
§08-§11 |
工作流、路由安全、可观测、部署 |
| Day 6 |
§12 + 附录 |
思维转变，查错与速查 |
标叔出品 | AI Native Coder · 独立开发者
公众号「标叔」
代表作：github.com/liangdabiao
参考文档：
https://mp.weixin.qq.com/s/-QaD5vDZ13v2NXf2rTR7zg?scene=1&click_id=320