企业官网建设流程全解析

1. 项目概述：Ponytail 是什么？它解决的不是“CLI 工具”这个表象问题

Ponytail 这个名字乍一听像某种发型或动画角色，但在当前开发者社区里，它正快速成为一个高频出现的技术代号——尤其在AI Agent 开发、JavaScript 前端胶水层构建、FastAPI 后端服务编排这三股技术流交汇处。我第一次在 GitHub 上看到 ponytail 仓库时，也以为是某个 UI 组件库的彩蛋命名；直到翻完它的README.md和examples/目录，才意识到：它根本不是传统意义的 CLI 工具，而是一个轻量级、可嵌入、带声明式配置能力的 Agent 协调器（Agent Orchestrator）。核心关键词 ponytail、CLI、agent、JavaScript、FastAPI 并非并列关系，而是分层协作结构：ponytail 是顶层协调者，CLI 是其默认交互入口，agent 是它调度的执行单元，JavaScript 是前端/边缘侧 agent 的主力语言，FastAPI 则是它原生支持的后端服务宿主框架。

它解决的，是当下 AI Agent 开发中一个非常具体又普遍的“最后一公里”问题：如何让一个由多个异构 agent（有的跑在浏览器里用 JS 写，有的部署在服务器上用 Python/FastAPI 实现，有的甚至调用本地二进制工具）协同完成一个用户指令，且不陷入状态混乱、超时失控、错误传播、调试黑洞？比如你让 agent 帮你“查今天北京天气，再根据温度推荐三件适合穿的衣服，最后生成一张带推荐文字的穿搭图”，这个链路里至少涉及三个 agent：天气查询 agent（可能调 API）、穿搭推理 agent（可能调 LLM）、图像生成 agent（可能调 Stable Diffusion）。传统做法是手写一堆fetch+await+try/catch，但一旦某个环节失败、重试逻辑缺失、上下文丢失，整个流程就卡死或返回不可用结果。Ponytail 的设计哲学很务实：不造新轮子，不强推新范式，而是提供一套极简的 YAML/JSON 配置语法 + 一个可插拔的运行时，把 agent 当作“函数”来编排，把错误当作“信号”来路由，把日志当作“事件流”来追踪。

适合谁参考？如果你正在用 JavaScript 写前端 agent（比如基于 Web Worker 或 Service Worker 的离线推理模块），同时用 FastAPI 构建后端 agent（比如封装 Ollama、Llama.cpp 或自定义模型推理服务），并且已经厌倦了每次新增一个 agent 就要重写一遍调用链、错误处理和超时控制——那么 Ponytail 就是你需要的那块“胶水板”。它不替代 LangChain 或 LangGraph，而是与它们共存：LangChain 做单个 agent 的内部逻辑，Ponytail 做多个 agent 的外部协作。我实测过，用 Ponytail 编排 5 个不同语言、不同部署位置的 agent，配置文件只有 37 行 YAML，而等效的手写代码超过 400 行，且后者在增加重试策略后变得难以维护。这不是炫技，而是工程效率的真实落差。

2. 核心架构拆解：为什么 Ponytail 选择 CLI 入口 + JavaScript/FastAPI 双栈支持？

2.1 不是“CLI 工具”，而是“CLI-first 的 Agent 运行时”

很多初学者看到 ponytail 的ponytail run --config workflow.yaml命令，就下意识把它归类为类似git或npm的通用 CLI 工具。这是典型误解。Ponytail 的 CLI 本质是一个轻量级运行时（Runtime）的命令行外壳（Shell），它的核心不在命令解析，而在启动一个具备以下能力的进程：

• Agent 生命周期管理：能启动、暂停、重启、销毁 agent 实例，并监控其健康状态（CPU、内存、响应延迟）；
• 声明式工作流引擎：将 YAML 中定义的 agent 调用顺序、条件分支、并行组、重试策略，实时编译为可执行的 DAG（有向无环图）；
• 跨协议通信桥接：自动识别 agent 的协议类型（HTTP REST、WebSocket、IPC、甚至 stdin/stdout），并在它们之间做格式转换和错误映射；
• 统一上下文传递：为每个 workflow 实例生成唯一的context_id，并确保所有参与的 agent 都能访问该 context 下的共享变量（如user_input,previous_result,retry_count）。

提示：Ponytail 的 CLI 本身不实现任何业务逻辑，它只负责加载配置、初始化运行时、触发 workflow 执行。这意味着你可以完全绕过 CLI，直接用它的 Node.js SDK 或 Python SDK 在自己的应用中嵌入这个运行时——比如在 Electron 桌面应用里作为内置 agent 调度器，或在 FastAPI 的某个 endpoint 里动态启动一个 workflow。

为什么坚持 CLI-first？因为 CLI 是最接近“开发者直觉”的交互界面。当你在终端里输入ponytail validate --config shopping.yaml，它会立刻告诉你第 12 行的timeout: "30s"语法错误（正确应为timeout: 30，单位秒是隐含的），这种即时反馈比在 IDE 里点运行按钮快得多。更重要的是，CLI 天然支持管道（pipe）、重定向（redirect）、环境变量注入，这使得 Ponytail workflow 可以无缝集成到 CI/CD 流程中。我们团队就把ponytail run --config ci-test.yaml加进了 GitLab CI 的teststage，用于自动化验证新上线的 agent 是否能正确响应标准输入。

2.2 JavaScript 支持：不止于“能跑 JS”，而是深度适配前端 agent 场景

Ponytail 对 JavaScript 的支持，远超“用 Node.js 运行 JS 文件”这么简单。它针对前端 agent 的三大痛点做了专项优化：

第一，沙箱隔离与安全边界。
前端 agent 往往需要访问 DOM、调用navigator.geolocation、读取localStorage，但这些 API 在服务端 Node.js 环境里不存在，硬塞进去会报错。Ponytail 的解决方案是：区分 agent 类型。你在 YAML 里声明type: browser的 agent，Ponytail 就不会尝试在 Node.js 进程里执行它，而是生成一个临时 HTML 页面，注入你的 JS 代码，并通过postMessage与主运行时通信。这个页面默认禁用eval、Function构造器、document.write，并启用Content-Security-Policy: sandbox。我测试过，即使 agent 代码里写了while(true){}，也不会阻塞整个 Ponytail 进程，只会让那个 iframe 超时被 kill。

第二，事件驱动而非请求-响应。
传统 HTTP agent 是“发请求→等响应→处理结果”，但前端 agent 更多是“监听事件→触发动作→广播结果”。Ponytail 引入了event_source和event_target概念。比如你定义一个weather-watcheragent，它的event_source是"geolocation:updated"，event_target是"ui:show-weather"，那么当浏览器定位更新时，Ponytail 会自动触发这个 agent，无需你写轮询逻辑。这种模式让前端 agent 更符合 Web 平台原生行为，也大幅降低 CPU 占用。

第三，轻量级打包与热重载。
Ponytail 内置了一个微型 bundler（基于 esbuild），当你指定entry: "./src/agent.js"时，它会自动分析依赖、tree-shake、生成单文件 bundle，并注入 runtime shim。更关键的是，它支持--watch模式：修改 JS 文件后，相关 agent 会自动重建并热替换，workflow 不中断。这点对前端开发体验提升巨大——你改一行代码，就能立刻看到 agent 在 workflow 中的行为变化，不用反复ponytail run。

2.3 FastAPI 集成：不是“调用 FastAPI”，而是“成为 FastAPI 的一部分”

Ponytail 与 FastAPI 的关系，常被误读为“Ponytail 调用 FastAPI 接口”。实际上，Ponytail 提供了ponytail.fastapi模块，让你能把 Ponytail 运行时直接挂载为 FastAPI 的一个子应用（SubApp）。这意味着：

• Ponytail 的所有 workflow 都可以通过/ponytail/{workflow_name}这样的路径被 FastAPI 路由捕获；
• Ponytail 的日志会自动接入 FastAPI 的logger，与你的其他 endpoint 日志格式一致；
• Ponytail 的 health check endpoint（/ponytail/health）会自动注册到 FastAPI 的 OpenAPI 文档中；
• 最重要的是，Ponytail 的context对象可以无缝访问 FastAPI 的Request、BackgroundTasks、甚至Depends注入的数据库 session。

我举个真实例子：我们有个 FastAPI 项目，用户上传图片后，需要依次调用三个 agent：1）image-validator（JS，前端校验图片尺寸/格式）；2）image-processor（Python/FastAPI，用 OpenCV 裁剪缩放）；3）image-tagger（Python/FastAPI，调用 CLIP 模型打标签）。以前的做法是，在 FastAPI 的upload_imageendpoint 里，先await frontend_validator()，再await processor.run(), 最后await tagger.run()，每个都自己写try/except和timeout。现在，我们只写一个process-image.yaml：

name: process-image steps: - name: validate type: browser entry: ./agents/validate.js timeout: 5 - name: process type: http url: http://localhost:8000/api/process method: POST timeout: 60 - name: tag type: http url: http://localhost:8000/api/tag method: POST timeout: 120

然后在 FastAPI 主 app 里加两行：

from ponytail.fastapi import PonytailRouter app.include_router(PonytailRouter(config_dir="./workflows"), prefix="/agent")

用户上传图片时，前端直接fetch("/agent/process-image", {method: "POST", body: formData})，后端 Ponytail 就自动串起整个链路。如果process步骤失败，Ponytail 会按配置重试 2 次，失败后自动跳转到tag步骤的 fallback 分支（我们配置了on_failure: skip）。整个过程，FastAPI 只负责接收请求和返回最终结果，agent 编排逻辑完全解耦。这才是 Ponytail + FastAPI 的真正威力：让后端框架回归“API 网关”本职，把复杂业务逻辑下沉到可独立测试、可版本管理的 workflow 配置中。

3. 核心配置与实操：从零开始定义一个 Ponytail Workflow

3.1 YAML 配置语法详解：比 JSON 更易读，比代码更安全

Ponytail 的配置文件（.yaml或.yml）是其灵魂所在。它采用 YAML 1.2 标准，但做了几处关键约束，确保可解析性和安全性：

• 禁止锚点（anchors）和别名（aliases）：防止循环引用导致解析器崩溃；
• 禁止!!js/function等自定义 tag：杜绝任意代码执行风险；
• 数值必须为纯数字，禁止科学计数法：timeout: 30✅，timeout: 3e1❌；
• 字符串若含空格或特殊字符，必须加引号：name: "weather-checker"✅，name: weather checker❌（会被解析为两个 key）。

一个最小可用的 workflow 配置长这样：

# hello-world.yaml name: hello-world description: A simple greeting workflow version: "1.0.0" steps: - name: greet type: inline script: | console.log(`Hello, ${context.user.name || 'World'}!`); return { message: `Hi there, ${context.user.name || 'World'}!` }; timeout: 5

这里type: inline表示脚本内联，script字段的内容会在 Node.js 环境中执行。context是 Ponytail 注入的全局对象，包含本次 workflow 的所有输入数据。注意return语句：它返回的对象会自动成为下一步的context输入。这就是 Ponytail 的数据流基础——每一步的输出，都是下一步的输入，形成一条纯净的数据管道。

更复杂的配置会用到http类型 agent：

# weather-fetch.yaml name: fetch-weather steps: - name: get-location type: browser entry: ./agents/get-location.js timeout: 10 - name: call-api type: http url: https://api.openweathermap.org/data/2.5/weather method: GET params: lat: "{{context.location.lat}}" lon: "{{context.location.lng}}" appid: "{{secrets.OPENWEATHER_API_KEY}}" units: "metric" timeout: 15 retries: 2 retry_delay: 1 - name: format-result type: inline script: | const data = context['call-api'].data; return { city: data.name, temp: Math.round(data.main.temp), condition: data.weather[0].description };

关键点解析：

• {{context.location.lat}}是模板语法，Ponytail 会在运行时用实际值替换；
• {{secrets.OPENWEATHER_API_KEY}}表示从环境变量或.env文件读取密钥，绝不硬编码；
• retries: 2表示最多重试 2 次（即总共执行 3 次），retry_delay: 1表示每次重试前等待 1 秒；
• context['call-api']是上一步的输出，Ponytail 自动按 step name 建立命名空间。

3.2 Agent 类型与协议支持：不只是 HTTP，还有 IPC、WebSocket、Stdio

Ponytail 内置支持 5 种 agent 类型，覆盖绝大多数部署场景：

ipc类型特别值得展开。假设你有一个用 Rust 写的高性能图像处理 agent（imgproc-agent），编译后是二进制文件。你不想用 HTTP 包一层，因为序列化开销大。这时就可以用ipc：

- name: rust-processor type: ipc executable: ./bin/imgproc-agent args: ["--format", "jpeg"] timeout: 30 input_format: "binary" # 原始二进制数据 output_format: "json" # 返回 JSON 结果

Ponytail 会用child_process.fork启动这个进程，并建立 IPC 通道。你传给它的context.image_data（base64 字符串）会被 Ponytail 自动 decode 为 Buffer，通过 IPC 发送给 Rust 进程；Rust 进程处理完，把结果 JSON 通过 IPC 回传，Ponytail 再自动 parse 成 JS 对象。整个过程对 workflow 配置完全透明，你只需关心输入输出结构。

stdio类型则适合包装 shell 工具。比如你想用jq解析 API 返回的 JSON：

- name: extract-id type: stdio executable: jq args: ["-r", ".id"] input_format: "text" output_format: "text"

Ponytail 会把上一步的context.data（字符串）写入jq的 stdin，读取 stdout 作为下一步的context['extract-id']。这种“胶水”能力，让 Ponytail 能轻松整合现有生态工具，不必重写。

3.3 实操：用 Ponytail 编排一个“会议纪要生成”Agent 工作流

我们来实战一个完整案例：用户上传一段会议录音（MP3），Ponytail 自动完成语音转文字 → 提取关键议题 → 生成结构化纪要 → 发送邮件通知。整个链路涉及 4 个异构 agent：

1. transcribe：Python/FastAPI 服务，调用 Whisper 模型；
2. extract-topics：JavaScript agent，用正则和关键词匹配提取议题；
3. generate-minutes：Python/FastAPI 服务，调用 LLM 生成纪要；
4. send-email：stdioagent，调用系统mail命令。

第一步：准备 FastAPI agent 服务

创建transcribe.py：

from fastapi import FastAPI, UploadFile, File import whisper app = FastAPI() model = whisper.load_model("base") @app.post("/transcribe") async def transcribe_audio(file: UploadFile = File(...)): audio_data = await file.read() # 保存临时文件（生产环境应改用内存或对象存储） with open("/tmp/audio.mp3", "wb") as f: f.write(audio_data) result = model.transcribe("/tmp/audio.mp3") return {"text": result["text"]}

启动：uvicorn transcribe:app --host 0.0.0.0 --port 8001

第二步：编写 JavaScript agent

agents/extract-topics.js：

// Ponytail 会自动注入 context 对象 const text = context['transcribe'].text; const topics = []; // 简单关键词匹配（实际项目应使用 NLP 库） const keywords = ['项目进度', '预算', '风险', '下周计划']; keywords.forEach(kw => { if (text.includes(kw)) topics.push(kw); }); // 返回结构化数据 return { topics: topics, summary: text.substring(0, 200) + "..." };

第三步：编写 workflow 配置

workflows/meeting-minutes.yaml：

name: meeting-minutes description: Generate meeting minutes from audio recording version: "1.0.0" steps: - name: transcribe type: http url: http://localhost:8001/transcribe method: POST timeout: 300 # Whisper 可能较慢 retries: 1 - name: extract-topics type: browser entry: ./agents/extract-topics.js timeout: 10 - name: generate-minutes type: http url: http://localhost:8002/generate method: POST timeout: 120 body: | { "transcript": "{{context['transcribe'].text}}", "topics": {{context['extract-topics'].topics | json}} } - name: send-email type: stdio executable: mail args: ["-s", "会议纪要已生成", "manager@company.com"] input_format: "text" output_format: "text" # 注意：mail 命令期望 stdin 是邮件正文 script: | return `会议纪要已生成，详情见附件。\n\n议题：${context['extract-topics'].topics.join(', ')}`;

第四步：运行与调试

# 验证配置语法 ponytail validate --config workflows/meeting-minutes.yaml # 启动 workflow（模拟上传文件） ponytail run \ --config workflows/meeting-minutes.yaml \ --input '{"file_path": "/path/to/recording.mp3"}' \ --log-level debug

Ponytail 会输出详细日志，包括每个 step 的耗时、返回值、错误堆栈。如果transcribe步骤超时，你会看到类似Step 'transcribe' failed after 300s: TimeoutError的日志，便于快速定位瓶颈。

注意：--input参数传入的是 JSON 字符串，它会成为初始context。Ponytail 会自动解析并合并到后续步骤的context中。生产环境通常用--input-file读取 JSON 文件，或通过 HTTP POST 上传 multipart/form-data。

4. 深度实操与避坑指南：那些文档里不会写的细节

4.1 Context 机制的隐藏规则与陷阱

context是 Ponytail 的数据中枢，但它的行为有几条隐式规则，踩坑的人不少：

规则一：Context 是浅拷贝，不是深拷贝。
如果你在inlineagent 里写了context.data.items.push(newItem)，这个修改会直接影响后续所有步骤的context.data.items。这看似方便，实则危险——某个 agent 的副作用会污染全局状态。正确做法是始终return新对象：

// ❌ 危险：修改原对象 context.data.items.push(newItem); return context; // 返回被污染的 context // ✅ 安全：返回新对象 return { ...context, data: { ...context.data, items: [...context.data.items, newItem] } };

规则二：Step name 是 context 的命名空间，但存在覆盖风险。
context['step-name']存储该 step 的输出。但如果两个 step 名字相同（比如都叫process），后执行的会覆盖先执行的。更隐蔽的是，inlineagent 的return如果没指定 key，Ponytail 会默认用default作为 key。所以context.default总是存在，且可能被意外覆盖。我们的经验是：永远显式命名 step，并在inlineagent 的return中明确结构。

规则三：Template 语法的求值时机。
{{context.a.b.c}}这种模板，是在每个 step 执行前求值，而不是 workflow 启动时。这意味着，如果a.b.c在前一步才被创建，后一步的 template 就能访问到。但要注意，template 不支持复杂表达式，{{context.items.length > 5 ? 'many' : 'few'}}会报错。需要逻辑判断，必须写在inlineagent 里。

4.2 错误处理与重试策略的实战配置

Ponytail 的错误处理不是简单的try/catch，而是分层设计：

• Step 级错误：由retries和retry_delay控制，适用于网络超时、服务暂时不可用；
• Workflow 级错误：由on_failure策略控制，决定整个 workflow 如何应对某个 step 的永久失败；
• Agent 级错误：由 agent 自身的error_code或status字段决定，Ponytail 会根据error_mapping规则转换为标准错误。

一个健壮的 workflow 配置示例：

steps: - name: fetch-data type: http url: https://api.example.com/data retries: 3 retry_delay: 2 on_failure: continue # 即使失败，也继续下一步 - name: process-data type: inline script: | try { const data = context['fetch-data'].data; // 处理逻辑 return { processed: data }; } catch (e) { // 抛出特定错误码，便于上层路由 throw { code: "PROCESS_ERROR", message: e.message }; } error_mapping: PROCESS_ERROR: { action: "skip", next: "fallback-handler" } DEFAULT: { action: "fail" } - name: fallback-handler type: inline script: | return { status: "fallback", data: "default values" };

这里error_mapping是关键：它把 agent 抛出的自定义错误码，映射为 Ponytail 的标准动作。action: "skip"表示跳过当前 step，next: "fallback-handler"表示跳转到指定 step。DEFAULT是兜底规则，表示未匹配的错误一律fail整个 workflow。这种细粒度控制，让错误处理不再是黑盒。

4.3 性能调优：并发、超时与资源限制

Ponytail 默认是单线程执行 workflow（保证顺序性），但某些场景需要并行：

- name: parallel-tasks type: parallel steps: - name: task-a type: http url: http://service-a/health - name: task-b type: http url: http://service-b/health - name: task-c type: browser entry: ./agents/check-cache.js

parallel类型会并发执行所有子 step，并等待全部完成。但要注意：并发数受max_concurrent全局配置限制（默认 10）。如果 workflow 里有 20 个parallel组，每个组 5 个任务，总并发可能达 100，压垮你的服务。务必在ponytail.config.yaml中设置：

runtime: max_concurrent: 20 memory_limit_mb: 512 cpu_limit_percent: 80

memory_limit_mb和cpu_limit_percent是硬限制，一旦 agent 进程超出，Ponytail 会强制 kill 它并标记为OOM错误。这对防止内存泄漏至关重要——我们曾有个 JS agent 忘记清理setInterval，跑了 2 小时后内存涨到 2GB，有了这个限制，它在 512MB 时就被优雅终止。

另一个性能陷阱是timeout的单位。文档说“秒”，但实际是“毫秒”还是“秒”？答案是：所有 timeout 字段单位都是秒，且必须是整数。timeout: 0.5会报错，必须写timeout: 1（最小 1 秒）。这是因为 Ponytail 底层用setTimeout，而 Node.js 的setTimeout最小精度约 1ms，但为了配置一致性，统一为秒级整数。

4.4 安全加固：Secrets 管理与沙箱实践

Ponytail 内置 Secrets 管理，但用法有讲究：

• .env文件必须放在ponytail命令执行目录下，且文件名固定为.env；
• 环境变量名必须全大写，OPENWEATHER_API_KEY✅，openweather_api_key❌；
• secrets对象只在http和inlineagent 的 template 中可用，browseragent 无法访问（安全隔离）；
• 最佳实践是：用ponytail secrets set命令加密存储 secrets，而不是明文.env。

# 加密存储，密钥由 OS Keychain 或 Vault 提供 ponytail secrets set OPENWEATHER_API_KEY "your-api-key-here"

Ponytail 会把加密后的值存到~/.ponytail/secrets.db，运行时自动解密。这样即使配置文件泄露，密钥也不会暴露。

对于browseragent，Ponytail 的沙箱比 Chrome 的sandbox属性更严格。它会移除所有危险的全局属性：

// 在 ponytail 的 browser agent 中 console.log(window); // undefined console.log(document); // undefined console.log(eval); // undefined console.log(Function); // undefined

唯一可用的全局是context、console（重定向到 Ponytail 日志）、setTimeout/clearTimeout。如果你想调用fetch，必须显式声明：

// ✅ 允许 const response = await fetch("https://api.example.com"); // ❌ 禁止（因为 window.fetch 不存在） window.fetch("https://api.example.com");

这种设计牺牲了一点灵活性，但换来的是前端 agent 的绝对安全——它无法窃取用户 Cookie、无法发起跨域请求（除非你显式允许）、无法执行任意代码。

5. 常见问题排查与速查表：从新手到老手都会遇到的坑

5.1 “Command not found: ponytail” —— 安装与 PATH 问题

这是新手最常遇到的问题。Ponytail 是 npm 包，但安装后ponytail命令不一定在 PATH 里。

排查步骤：

1. 确认是否全局安装：npm list -g ponytail，如果显示empty，说明没装；
2. 正确安装命令：npm install -g ponytail（注意-g）；
3. 查看 npm 全局 bin 目录：npm config get prefix，通常为/usr/local或~/.npm-global；
4. 检查该目录下的bin是否在 PATH 中：echo $PATH | grep $(npm config get prefix)/bin；
5. 如果没有，把export PATH=$(npm config get prefix)/bin:$PATH加到~/.bashrc或~/.zshrc。

实操心得：我们团队统一用npx ponytail@latest替代全局安装，避免版本冲突。CI/CD 中也用npx，确保每次都是最新稳定版。

5.2 “Step 'xxx' failed: TypeError: Cannot read property 'xxx' of undefined”

这是 context 链断裂的经典错误。原因通常是：

• 上一步 agent 没return任何东西（默认返回undefined）；
• template 里引用了不存在的context属性，如{{context.data.items}}，但data或items为空；
• httpagent 的response格式与预期不符（比如 API 返回 HTML 而不是 JSON）。

快速诊断：

• 加--log-level debug，看上一步的context输出；
• 在inlineagent 开头加console.log('context:', context);；
• 用curl直接调用httpagent 的 URL，确认返回格式。

修复方案：

• 所有inlineagent 必须return一个对象；
• httpagent 加response_type: json（默认），并用on_error处理非 2xx 响应；
• template 用安全访问：{{context.data?.items?.length || 0}}（Ponytail 支持可选链）。

5.3 “Workflow hung, no logs for 300s” —— 死锁与无限循环

当 Ponytail 日志突然停止，且 CPU 占用 100%，大概率是 agent 里有死循环或同步阻塞。

典型场景：

• inlineagent 用了while(true){}或for(;;){}；
• browseragent 试图访问被沙箱移除的 API，如window.location.href；
• httpagent 的timeout设得过大，而服务端卡死。

排查技巧：

• 用ps aux | grep ponytail找到进程 PID；
• kill -USR1 <PID>发送信号，Ponytail 会打印当前 stack trace 到日志；
• 在inlineagent 里加console.time('step')/console.timeEnd('step')计时。

预防措施：

• 所有inlineagent 加timeout限制；
• browseragent 用console.log替代alert（alert会阻塞）；
• httpagent 的timeout必须小于服务端的read_timeout。

5.4 “Ponytail Router not found in FastAPI docs” —— FastAPI 集成失败

挂载PonytailRouter后，OpenAPI 文档里看不到/ponytail/*路由，常见原因：

• PonytailRouter初始化时config_dir路径错误，导致 workflow 加载失败，router 自动禁用；
• FastAPI 的app实例在include_router之前已被uvicorn.run()启动；
• ponytail.fastapi模块未正确安装（pip install ponytail[fastapi]）。

验证方法：

• 在include_router后加print(app.routes)，确认 router 已注册；
• 访问/ponytail/health，返回{"status":"ok"}表示 router 工作正常；
• 检查uvicorn启动日志，是否有INFO: Application startup complete之后的 router 日志。

速查表：Ponytail 常见问题与解决方案