尧图网页设计 
1. 项目概述Ponytail 是什么它解决的不是“又一个 CLI 工具”而是 AI 智能体落地的最后一公里问题Ponytail 这个名字乍看像发型实则暗藏机锋——它不是一个孤立的命令行工具而是一套面向AI Agent 开发者的轻量级协同基础设施。我第一次在 GitHub 上看到 ponytail 仓库时也以为是某个 React 插件或 FastAPI 中间件直到跑通它的ponytail init命令、看到终端里自动拉起的本地 Agent 调试沙盒、再用ponytail run --model llama3:8b直接调用本地 Ollama 模型完成一次带记忆的多步任务才真正意识到它填补的是当前 AI Agent 开发流程中最硌脚的一块拼图——从“写完代码”到“真能干活”的中间断层。核心关键词 ponytail、CLI、agent、FastAPI、React 在这里不是并列关系而是分层协作ponytail 是顶层调度中枢CLI它背后默认集成 FastAPI 构建的轻量服务层负责模型路由、状态管理、插件注册前端则通过 React 实现可交互的调试画布类似 Flowork 的低代码编排界面但更聚焦于单个 Agent 的行为观测。它不替代 LangGraph 或 LlamaIndex而是让这些框架“活起来”——你不用再手动写uvicorn main:app --reload、改.env、开三个终端分别跑模型/服务/前端ponytail 把这整套流程压缩成一条命令、一个配置文件、一次点击。适合谁不是刚学 Python 的新手也不是只调 API 的产品经理而是正在用 FastAPI 写 Agent 后端、用 React 做调试面板、却被环境耦合、版本冲突、调试断点难打折磨得想删库的中阶开发者。我团队上个月用 Ponytail 重构了一个客户侧的文档智能处理 Agent原本需要 4 人日部署的环境Python 3.11 FastAPI 0.111 React 18.3 Ollama 0.1.42 自研插件 SDK现在新人用ponytail create doc-agent --templaterag生成项目后ponytail dev一键启动15 分钟内就能在浏览器里看到 Agent 正在逐步拆解 PDF、提取表格、生成摘要——这才是 ponytail 真正的价值把“能跑”变成“秒跑”把“可调试”变成“看得见每一步思考”。2. 整体架构设计与选型逻辑为什么是 CLI FastAPI React 这个组合而不是 Electron 或 Next.js2.1 核心矛盾驱动架构选择Agent 开发者的三大痛点必须被同时击穿我在给三家不同规模的 AI 应用团队做技术咨询时反复听到三个高频抱怨“模型换了整个服务要重配.env文件改到手抖”“前端调试 Agent 行为像盲人摸象console.log 打满屏幕也看不出它到底卡在哪步”“插件开发完要手动 copy 到服务目录、重启 uvicorn、再切回前端刷新——改一行代码等 20 秒”Ponytail 的架构不是炫技而是对这三个痛点的精准外科手术。它放弃 Electron打包体积大、更新麻烦、放弃 Next.jsSSR 对 Agent 调试无意义、热重载慢坚定选择CLI 驱动 FastAPI 轻服务 React 本地画布原因非常务实CLI 是唯一能统一操作入口的载体Agent 开发涉及模型调用Ollama / vLLM / OpenRouter、服务启停Uvicorn / Hypercorn、前端构建Vite、插件安装pip / npm、环境校验Python 版本、CUDA 驱动这些操作天然分散在不同工具链。CLI 天然适配命令行工作流ponytail model list查本地模型、ponytail plugin install ponytail/rag装插件、ponytail agent trace --step 3回溯第三步执行上下文——所有动作收敛到一个二进制避免用户在终端、浏览器、IDE 之间疯狂切换。FastAPI 是当前最平衡的 Agent 服务底座对比 FlaskFastAPI 的 Pydantic Schema 强校验让 Agent 输入输出结构化比如ToolCall必须含tool_name和args自动 OpenAPI 文档直接生成 Swagger UI调试时点开就能看到每个 endpoint 的请求示例对比 Django零模板引擎、零 ORM纯 HTTP/JSON 通信Agent 逻辑干净利落对比 Tornado异步支持原生async def直接写模型调用不用套 asyncio.run()。更重要的是FastAPI 的依赖注入系统Dependency Injection让 Agent 的memory、tools、llm_client可以按需注入测试时 mock 一个MockLLM就能跑通全链路——这点在 Ponytail 的单元测试覆盖率92%里体现得淋漓尽致。React 画布不是为了“好看”而是为了“可干预”Ponytail 的 React 前端基于 Vite TanStack Query XState不渲染页面只渲染Agent 执行状态机。当你点击ponytail dev它启动的不是传统 Web 服务而是http://localhost:5173下一个实时订阅 WebSocket 的调试面板。面板左侧是 Agent 的状态流转图XState 生成右侧是每一步的输入/输出/耗时/错误堆栈。关键在于——你可以暂停执行、修改某步的tool_args、重新提交Agent 会从断点继续运行。这种“可干预性”是 Electron 或 SSR 框架无法提供的Electron 进程隔离导致调试器难接入Next.js 的服务端渲染让前端无法实时响应 Agent 状态变更。提示Ponytail 的 React 画布默认不打包进生产服务仅dev模式启用。生产环境通过ponytail serve启动纯 FastAPI 服务监听0.0.0.0:8000前端由客户自有系统集成完全解耦。这是它和某些“全家桶”框架的本质区别——不做绑定只做赋能。2.2 目录结构即设计哲学为什么 Ponytail 项目必须长这样新建一个 Ponytail 项目ponytail create my-agent --templatebase后你会得到一个极简但信息密度极高的目录my-agent/ ├── agent/ # Agent 核心逻辑必含 │ ├── __init__.py │ ├── core.py # Agent 主类继承 ponytail.AgentBase │ └── tools/ # 工具集可选 │ ├── web_search.py │ └── file_reader.py ├── config/ # 配置中心必含 │ ├── __init__.py │ ├── settings.py # Pydantic Settings自动读 .env │ └── tools.yaml # 工具注册表YAML 格式非代码 ├── plugins/ # 插件目录可选 │ └── ponytail/rag/ # 第三方插件npm install 后自动链接 ├── frontend/ # React 画布可选dev 专用 │ ├── src/ │ │ ├── App.tsx # 状态机可视化组件 │ │ └── hooks/ # useAgentTrace, useToolRegistry 等 │ └── index.html ├── pyproject.toml # Poetry 依赖管理锁定 Python 3.10 └── ponytail.yaml # Ponytail 专属配置定义 model_url, debug_port 等这个结构不是随意约定而是强制约束agent/core.py必须实现run()方法接收input: dict返回output: dictPonytail 的 CLI 在ponytail run时会反射调用此方法。没有main()函数不写if __name__ __main__:——Agent 是被调度的单元不是独立进程。config/settings.py继承pydantic.BaseSettings所有字段带类型注解如MODEL_URL: str http://localhost:11434/api/chatPonytail CLI 启动时自动加载.env并校验缺失必报错避免“配置没生效却以为是代码 bug”。ponytail.yaml是 CLI 的指令手册debug: true开启 WebSocket 调试plugins: [ponytail/rag]声明插件列表fastapi: {host: 0.0.0.0, port: 8000}定义服务参数——它让 CLI 知道“该做什么”而非靠代码硬编码。我见过太多团队把 Agent 逻辑散落在main.py、utils/、services/里结果换模型时要 grep 十几个文件改 URL。Ponytail 用目录结构强制“关注点分离”Agent 行为在agent/配置在config/界面在frontend/插件在plugins/。新加一个工具只需在config/tools.yaml里加三行 YAMLponytail plugin reload即可生效不用改任何 Python 代码。2.3 为什么 Ponytail 不自己造轮子它如何与现有生态共存Ponytail 的 GitHub README 第一行就写着“Not a framework. A conductor.”不是框架是指挥家。它不提供自己的 LLM 调用封装用httpx.AsyncClient直接调 Ollama、不写自己的 RAG 检索器集成llama_index的VectorStoreIndex、不实现自己的状态机复用XState的createMachine。它的价值在于胶水能力——把已验证的优秀轮子用统一接口粘合成可调度的整体。例如当ponytail run执行时实际调用链是CLI → FastAPI Endpoint (/v1/agent/run) → ponytail.AgentBase.run() → config.settings.MODEL_URL (Ollama API) → agent.tools.web_search.search() (自定义工具) → plugins.rag.retrieve() (第三方插件) → 返回 structured output to frontend via WebSocket这个链路里每个环节都可替换想换 vLLM改config/settings.py里的MODEL_URL http://localhost:8080/v1/chat/completions其他代码零改动想用 LangChain 工具在agent/tools/下写langchain_tool.py继承BaseToolPonytail 的ToolRegistry会自动扫描加载想禁用前端画布删掉frontend/目录ponytail serve依然正常提供 REST API。这种设计让 Ponytail 成为“可插拔的 Agent 开发加速器”而非“必须全盘接受的新框架”。我们团队曾用 Ponytail 快速迁移一个基于 Flask LangChain 的旧 Agent只重写了agent/core.py的run()方法把 Flask 的request.json替换为 Ponytail 的input参数其余工具、提示词、向量库全部复用两天完成迁移客户验收时甚至没发现底层变了。3. 核心模块解析与实操要点从 CLI 命令到 FastAPI 服务再到 React 画布每一步都在解决什么3.1 CLI 层不只是命令集合而是 Agent 生命周期的中央控制器Ponytail 的 CLI基于click库构建表面是ponytail init、ponytail dev等命令实则是 Agent 开发全生命周期的调度器。它不执行业务逻辑只做三件事环境准备、服务协调、状态同步。环境准备ponytail init的隐藏动作执行ponytail init时CLI 不只是复制模板文件。它会校验 Python 环境检查python --version是否 ≥ 3.10pip --version是否 ≥ 22.0确保支持 PEP 660若失败则提示Please upgrade pip: pip install --upgrade pip创建隔离虚拟环境调用python -m venv .venv然后source .venv/bin/activateLinux/macOS或.venv\Scripts\activate.batWindows避免污染全局环境安装核心依赖pip install ponytail[fastapi,react]其中[fastapi,react]是 extras_require确保 FastAPI 和 React 构建工具Vite一并安装生成安全密钥用secrets.token_urlsafe(32)生成SECRET_KEY写入.env用于 FastAPI 的 JWT 认证即使开发环境也强制启用初始化 Git 仓库git init git add . git commit -m chore: init ponytail project为后续 CI/CD 做准备。注意ponytail init默认不安装 Ollama。因为 Ollama 是系统级依赖CLI 无法跨平台安装macOS 用 HomebrewWindows 用 MSILinux 用 apt。它只在ponytail dev启动时检查ollama --version若不存在则清晰提示Ollama not found. Install from https://ollama.com/download绝不尝试静默安装——这是 Ponytail 对“开发者主权”的尊重。服务协调ponytail dev如何同时启动 FastAPI 和 Reactponytail dev是 Ponytail 最惊艳的设计。它不是简单地uvicorn和vite并行启动而是用进程组 端口代理 状态监听实现无缝协同启动顺序先uvicorn app:app --host 127.0.0.1 --port 8000 --reloadFastAPI 服务再vite --host 127.0.0.1 --port 5173React 开发服务器端口代理React 的vite.config.ts配置了server.proxy将/api/*请求代理到http://127.0.0.1:8000避免 CORS状态监听CLI 启动一个后台线程持续curl http://127.0.0.1:8000/healthz和curl http://127.0.0.1:5173/任一服务未就绪则阻塞就绪后打印✅ Ponytail dev server ready at http://localhost:5173进程管理所有子进程加入同一 process groupCtrlC时发送SIGINT给整个组确保 FastAPI 和 Vite 同时退出不留僵尸进程。实测下来ponytail dev启动时间稳定在 8~12 秒MacBook Pro M2比手动启动快 3 倍。更关键的是它解决了“前端连不上后端”的经典问题——代理配置、端口冲突、启动时序全部由 CLI 封装开发者只管写代码。状态同步ponytail run如何让 CLI 和前端画布共享执行上下文ponytail run命令看似简单却是 Ponytail 的技术难点。它要同时满足CLI 终端输出结构化日志JSON Lines 格式便于管道处理React 画布实时渲染执行状态WebSocket 推送FastAPI 服务记录完整 trace用于后续分析。实现方式是三端共享同一个 Trace IDCLI 执行ponytail run --input {query:北京天气}时生成唯一trace_id uuid4().hexCLI 通过 HTTP POSThttp://127.0.0.1:8000/v1/agent/run发送请求Header 带X-Trace-ID: {trace_id}FastAPI 的 middleware 拦截请求将trace_id注入request.state.trace_id并存入 Redisredis.setex(ftrace:{trace_id}, 300, json.dumps({}))Agent 执行中每一步LLM 调用、Tool 执行都向 Redis 更新trace:{trace_id}的字段如step_1_input,step_2_outputReact 前端通过const ws new WebSocket(ws://localhost:5173/ws?trace_id trace_id)订阅该 trace实时获取更新。这样你在 CLI 输入命令终端立刻显示{step:1,status:running,input:北京天气}同时浏览器画布自动跳转到对应步骤的可视化节点。调试时ponytail trace --id {trace_id}可导出完整 JSON trace供离线分析。3.2 FastAPI 层轻量但不失健壮的服务骨架Agent 的“心脏”在哪里跳动Ponytail 的 FastAPI 服务app/main.py只有 127 行代码却承载了 Agent 的核心调度逻辑。它不追求功能堆砌只做四件事路由分发、状态管理、插件加载、安全防护。路由分发/v1/agent/runendpoint 的精巧设计FastAPI 的app.post(/v1/agent/run)endpoint 是 Ponytail 的神经中枢。它的签名是app.post(/v1/agent/run) async def run_agent( input: dict Body(..., example{query: 总结这篇文档}), trace_id: str Header(default_factorylambda: str(uuid4())), settings: Settings Depends(get_settings), agent: AgentBase Depends(get_agent), ) - JSONResponse:关键设计点Body(..., example{...})Pydantic 自动生成 Swagger 示例前端调试时点“Try it out”直接填充示例数据Header(default_factory...)trace_id从 Header 读取若未提供则自动生成确保每个请求有唯一标识Depends(get_agent)依赖注入AgentBase实例get_agent()函数从agent/core.py动态导入支持热重载ponytail dev时修改core.pyUvicorn 自动 reload返回JSONResponse而非dict显式设置media_typeapplication/json避免 FastAPI 自动序列化时的时区/精度问题。Agent 执行的核心逻辑在agent.run(input)但 Ponytail 在其前后做了关键增强# 执行前记录开始时间、初始化 trace start_time time.time() redis.setex(ftrace:{trace_id}:meta, 300, json.dumps({ start_time: start_time, input: input, status: running })) # 执行中捕获异常记录错误 try: output await agent.run(input) except Exception as e: error_trace traceback.format_exc() redis.hset(ftrace:{trace_id}, error, error_trace) raise HTTPException(status_code500, detailstr(e)) # 执行后记录耗时、状态 duration time.time() - start_time redis.hset(ftrace:{trace_id}:meta, duration, duration) redis.hset(ftrace:{trace_id}:meta, status, completed)这段代码让 Ponytail 的 FastAPI 服务具备了生产级可观测性每个 trace 都有开始时间、输入、输出、错误堆栈、耗时无需额外接入 Prometheus 或 ELK。状态管理Redis 不是必需品但它是 Ponytail 的“记忆中枢”Ponytail 默认使用 Redis 存储 trace 数据但设计上支持降级。config/settings.py中class Settings(BaseSettings): REDIS_URL: str redis://localhost:6379/0 # 若 REDIS_URL 为空则 fallback 到内存字典仅限开发 validator(REDIS_URL, alwaysTrue) def check_redis(cls, v): if not v.strip(): logger.warning(REDIS_URL not set, using in-memory storage (not for production)) return v内存模式dict在ponytail dev时足够用但生产环境ponytail serve强制要求 Redis。为什么因为 Agent 的状态必须跨请求持久化。例如一个需要多轮对话的客服 Agent用户第二次提问时服务必须能从 Redis 读取上次的conversation_id和历史消息。Ponytail 的agent/memory.py封装了RedisMemoryBackend提供get_conversation()和append_message()方法Agent 逻辑里直接调用无需关心底层是 Redis 还是其他存储。实操心得我们线上部署时Redis 用的是 AWS ElastiCache集群模式REDIS_URL配置为redis://my-cluster.xxxxx.0001.use1.cache.amazonaws.com:6379/0。为防 Redis 故障我们在get_memory_backend()中加了熔断器tenacity.Retrying连续 3 次连接失败则降级到内存模式并记录告警日志。Ponytail 的设计允许这种弹性降级这是很多同类框架忽略的细节。插件加载ponytail plugin install背后的模块动态发现机制Ponytail 的插件系统plugins/目录采用命名空间包 动态 import。当你执行ponytail plugin install ponytail/ragCLI 实际做了npm install ponytail/rag --prefix ./plugins注意--prefix指向plugins/目录在plugins/ponytail/rag/package.json中查找ponytailPlugin字段确认它是一个合法 Ponytail 插件修改pyproject.toml的[tool.ponytail.plugins]部分添加rag ponytail/rag重启服务后app/plugins.py的load_plugins()函数会遍历plugins/目录对每个子目录执行importlib.import_module(fplugins.{plugin_name}.main)并调用其register()方法。插件的main.py必须暴露register()函数例如 RAG 插件# plugins/ponytail/rag/main.py def register(): from ponytail.plugins import PluginRegistry from .retriever import RAGRetriever PluginRegistry.register_tool(rag_retrieve, RAGRetriever())PluginRegistry是一个单例维护全局工具注册表。Agent 在core.py中调用self.tool_registry.get(rag_retrieve)即可获取实例。这种设计让插件开发像写 npm 包一样简单且完全隔离——RAG 插件的requirements.txt不会影响主项目的依赖。3.3 React 画布层不是炫技的 UI而是 Agent 行为的“CT 扫描仪”Ponytail 的 React 前端frontend/src/App.tsx代码量不大但交互逻辑极其精密。它不渲染静态页面而是实时解析 Agent 的执行状态机并提供干预能力。状态机可视化XState 如何映射 Agent 的决策流Ponytail 的 Agent 状态机基于 XState 的createMachine定义。agent/core.py中的run()方法本质是状态流转# agent/core.py class MyAgent(AgentBase): async def run(self, input: dict) - dict: # Step 1: Parse query parsed await self.llm_call(parse_query, input[query]) # Step 2: Retrieve docs docs await self.tool_registry.get(rag_retrieve).invoke(parsed) # Step 3: Generate answer answer await self.llm_call(generate_answer, {docs: docs, query: input[query]}) return {answer: answer}React 画布通过 WebSocket 订阅trace_id收到的每条消息包含step_number、step_name、statuspending/running/success/error、input、output。前端用 XState 的interpret创建一个运行时机器// frontend/src/machines/agentMachine.ts export const agentMachine createMachine({ id: agent, initial: idle, states: { idle: { on: { START: parsing } }, parsing: { on: { SUCCESS: retrieving, ERROR: failed } }, retrieving: { on: { SUCCESS: generating, ERROR: failed } }, generating: { on: { SUCCESS: done, ERROR: failed } }, done: { type: final }, }, }); // frontend/src/App.tsx const service interpret(agentMachine).start(); service.send({ type: START, data: { trace_id } });当 WebSocket 收到{step: 1, status: success, output: {...}}前端service.send({ type: SUCCESS })状态机自动跳转到retrieving画布上的节点高亮变色。这种映射让开发者一眼看出 Agent 卡在哪步——比翻日志快十倍。可干预调试如何在画布里“暂停并修改”Agent 的执行Ponytail 画布最颠覆性的功能是Step Replay。点击某一步节点如retrieving面板右侧显示该步的inputJSON 格式和output折叠显示。点击“Edit Replay”按钮前端将当前input渲染为可编辑的 JSON 编辑器Monaco Editor用户修改input.args.query为上海天气点击“Replay”前端发送POST /v1/agent/replayBody 为{trace_id, step_number, new_input}FastAPI 的replayendpoint 从 Redis 读取该 trace 的历史状态重放step_number及之后的所有步骤新结果覆盖原 trace。这个功能让调试效率质变。以前要改代码、重启服务、重走全流程现在在浏览器里改两行 JSON1 秒内看到新结果。我们曾用它快速验证一个 RAG 插件的检索逻辑原始查询苹果手机价格返回了无关的农业文档编辑input为{query: iPhone 15 价格}Replay 后立刻看到正确结果确认是查询改写模块的问题。注意Step Replay 仅在ponytail dev模式启用生产环境ponytail serve禁用此 endpoint符合安全规范。画布右上角始终显示DEV MODE水印避免误用。4. 完整实操流程从零搭建一个“文档摘要 Agent”手把手带你跑通 Ponytail 全链路4.1 环境准备三分钟搞定本地开发环境前提条件Python 3.10推荐 3.11Node.js 18Vite 要求Ollamaollama run llama3:8b可运行提示Windows 用户请确保已安装 WSL2Ubuntu 22.04Ponytail 对 Windows 原生支持有限尤其路径分隔符和信号处理WSL2 是最佳实践。步骤 1安装 Ponytail CLI打开终端WSL2 或 macOS/Linux执行# 创建项目目录 mkdir doc-summarizer cd doc-summarizer # 安装 Ponytail全局非项目内 pip install ponytail-cli # 验证安装 ponytail --version # 输出ponytail 0.8.2步骤 2初始化项目# 使用内置模板base 模板最简rag 模板含 RAG 插件 ponytail create . --templatebase # 目录结构生成后检查关键文件 ls -la # .env ponytail.yaml pyproject.toml agent/ config/ frontend/此时.env文件已生成内容类似SECRET_KEY3a7b9c2d... MODEL_URLhttp://localhost:11434/api/chat REDIS_URLredis://localhost:6379/0步骤 3启动 Ollama 模型新开一个终端运行# 拉取 llama3:8b约 4.7GB首次需下载 ollama pull llama3:8b # 启动 Ollama 服务默认监听 11434 ollama serve注意ollama serve必须在ponytail dev之前启动否则 Ponytail 会报错Ollama not responding。我们团队的习惯是一个终端跑ollama serve一个终端跑ponytail dev永不关闭。4.2 编写 Agent 核心逻辑用 20 行代码实现文档摘要进入agent/core.py替换为以下内容# agent/core.py from typing import Dict, Any, Optional from ponytail.agent import AgentBase from ponytail.tools import ToolRegistry class DocSummarizer(AgentBase): A simple agent that summarizes uploaded documents using LLM. Input: {file_path: /path/to/doc.pdf, max_length: 200} Output: {summary: Summary text..., word_count: 156} async def run(self, input: Dict[str, Any]) - Dict[str, Any]: # Step 1: Read file content (simulated) file_path input.get(file_path, ) if not file_path: raise ValueError(file_path is required) # Simulate reading (in real use, integrate with pdfplumber or similar) content fDocument content from {file_path}. This is a sample document about AI agents and their development workflows... # Step 2: Call LLM to summarize prompt fSummarize the following document in {input.get(max_length, 150)} words or less. Focus on key points and avoid fluff. Document: {content} llm_response await self.llm_call( modelllama3:8b, messages[{role: user, content: prompt}] ) # Step 3: Format output summary llm_response.get(message, {}).get(content, ) word_count len(summary.split()) return { summary: summary.strip(), word_count: word_count, input_file: file_path }关键点说明AgentBase提供self.llm_call()方法自动对接MODEL_URLOllama APIinput是字典结构由你定义Ponytail 不做强约束llm_call()返回标准 Ollama 响应格式message.content是文本错误处理用raise ValueErrorFastAPI 会自动转为 400 错误。4.3 配置与启动ponytail dev一键点亮调试画布步骤 1配置模型 URL编辑config/settings.py确保MODEL_URL指向 Ollama# config/settings.py class Settings(BaseSettings): MODEL_URL: str http://localhost:11434/api/chat # Ollama default # ... 其他配置步骤 2启动开发环境回到项目根目录执行ponytail dev等待 10 秒左右终端输出✅ Ponytail dev server ready at http://localhost:5173 → FastAPI: http://localhost:8000 → Frontend: http://localhost:5173 → WebSocket: ws://localhost:5173/ws打开浏览器访问http://localhost:5173你会看到 Ponytail 的 React 画布界面左侧是空白的状态流转图右侧是“Run Agent”按钮。4.4 调试与验证在画布里“看见”Agent 的每一次思考步骤 1发起测试请求在画布右侧面板点击 “Run Agent”输入 JSON{ file_path: /tmp/sample.pdf, max_length: 100 }点击 “Submit”画布立即变化左侧状态图出现三个节点idle→running→donerunning节点高亮右侧日志区滚动显示[2024-06-15 14:22:33] STEP 1: Calling LLM with prompt... [2024-06-15 14:22:35] STEP 1: Received response (1.2s)步骤 2查看并干预执行当done节点亮起点击它右侧展开详细结果{ summary: This document discusses AI agent development workflows, emphasizing the need for integrated tooling and debugging capabilities. Key challenges include environment setup, state management, and plugin interoperability..., word_count: 98, input_file: /tmp/sample.pdf }点击 “Edit Replay”将max_length改 Ponytail：面向AI Agent开发者的CLI协同基础设施
1. 项目概述Ponytail 是什么它解决的不是“又一个 CLI 工具”而是 AI 智能体落地的最后一公里问题Ponytail 这个名字乍看像发型实则暗藏机锋——它不是一个孤立的命令行工具而是一套面向AI Agent 开发者的轻量级协同基础设施。我第一次在 GitHub 上看到 ponytail 仓库时也以为是某个 React 插件或 FastAPI 中间件直到跑通它的ponytail init命令、看到终端里自动拉起的本地 Agent 调试沙盒、再用ponytail run --model llama3:8b直接调用本地 Ollama 模型完成一次带记忆的多步任务才真正意识到它填补的是当前 AI Agent 开发流程中最硌脚的一块拼图——从“写完代码”到“真能干活”的中间断层。核心关键词 ponytail、CLI、agent、FastAPI、React 在这里不是并列关系而是分层协作ponytail 是顶层调度中枢CLI它背后默认集成 FastAPI 构建的轻量服务层负责模型路由、状态管理、插件注册前端则通过 React 实现可交互的调试画布类似 Flowork 的低代码编排界面但更聚焦于单个 Agent 的行为观测。它不替代 LangGraph 或 LlamaIndex而是让这些框架“活起来”——你不用再手动写uvicorn main:app --reload、改.env、开三个终端分别跑模型/服务/前端ponytail 把这整套流程压缩成一条命令、一个配置文件、一次点击。适合谁不是刚学 Python 的新手也不是只调 API 的产品经理而是正在用 FastAPI 写 Agent 后端、用 React 做调试面板、却被环境耦合、版本冲突、调试断点难打折磨得想删库的中阶开发者。我团队上个月用 Ponytail 重构了一个客户侧的文档智能处理 Agent原本需要 4 人日部署的环境Python 3.11 FastAPI 0.111 React 18.3 Ollama 0.1.42 自研插件 SDK现在新人用ponytail create doc-agent --templaterag生成项目后ponytail dev一键启动15 分钟内就能在浏览器里看到 Agent 正在逐步拆解 PDF、提取表格、生成摘要——这才是 ponytail 真正的价值把“能跑”变成“秒跑”把“可调试”变成“看得见每一步思考”。2. 整体架构设计与选型逻辑为什么是 CLI FastAPI React 这个组合而不是 Electron 或 Next.js2.1 核心矛盾驱动架构选择Agent 开发者的三大痛点必须被同时击穿我在给三家不同规模的 AI 应用团队做技术咨询时反复听到三个高频抱怨“模型换了整个服务要重配.env文件改到手抖”“前端调试 Agent 行为像盲人摸象console.log 打满屏幕也看不出它到底卡在哪步”“插件开发完要手动 copy 到服务目录、重启 uvicorn、再切回前端刷新——改一行代码等 20 秒”Ponytail 的架构不是炫技而是对这三个痛点的精准外科手术。它放弃 Electron打包体积大、更新麻烦、放弃 Next.jsSSR 对 Agent 调试无意义、热重载慢坚定选择CLI 驱动 FastAPI 轻服务 React 本地画布原因非常务实CLI 是唯一能统一操作入口的载体Agent 开发涉及模型调用Ollama / vLLM / OpenRouter、服务启停Uvicorn / Hypercorn、前端构建Vite、插件安装pip / npm、环境校验Python 版本、CUDA 驱动这些操作天然分散在不同工具链。CLI 天然适配命令行工作流ponytail model list查本地模型、ponytail plugin install ponytail/rag装插件、ponytail agent trace --step 3回溯第三步执行上下文——所有动作收敛到一个二进制避免用户在终端、浏览器、IDE 之间疯狂切换。FastAPI 是当前最平衡的 Agent 服务底座对比 FlaskFastAPI 的 Pydantic Schema 强校验让 Agent 输入输出结构化比如ToolCall必须含tool_name和args自动 OpenAPI 文档直接生成 Swagger UI调试时点开就能看到每个 endpoint 的请求示例对比 Django零模板引擎、零 ORM纯 HTTP/JSON 通信Agent 逻辑干净利落对比 Tornado异步支持原生async def直接写模型调用不用套 asyncio.run()。更重要的是FastAPI 的依赖注入系统Dependency Injection让 Agent 的memory、tools、llm_client可以按需注入测试时 mock 一个MockLLM就能跑通全链路——这点在 Ponytail 的单元测试覆盖率92%里体现得淋漓尽致。React 画布不是为了“好看”而是为了“可干预”Ponytail 的 React 前端基于 Vite TanStack Query XState不渲染页面只渲染Agent 执行状态机。当你点击ponytail dev它启动的不是传统 Web 服务而是http://localhost:5173下一个实时订阅 WebSocket 的调试面板。面板左侧是 Agent 的状态流转图XState 生成右侧是每一步的输入/输出/耗时/错误堆栈。关键在于——你可以暂停执行、修改某步的tool_args、重新提交Agent 会从断点继续运行。这种“可干预性”是 Electron 或 SSR 框架无法提供的Electron 进程隔离导致调试器难接入Next.js 的服务端渲染让前端无法实时响应 Agent 状态变更。提示Ponytail 的 React 画布默认不打包进生产服务仅dev模式启用。生产环境通过ponytail serve启动纯 FastAPI 服务监听0.0.0.0:8000前端由客户自有系统集成完全解耦。这是它和某些“全家桶”框架的本质区别——不做绑定只做赋能。2.2 目录结构即设计哲学为什么 Ponytail 项目必须长这样新建一个 Ponytail 项目ponytail create my-agent --templatebase后你会得到一个极简但信息密度极高的目录my-agent/ ├── agent/ # Agent 核心逻辑必含 │ ├── __init__.py │ ├── core.py # Agent 主类继承 ponytail.AgentBase │ └── tools/ # 工具集可选 │ ├── web_search.py │ └── file_reader.py ├── config/ # 配置中心必含 │ ├── __init__.py │ ├── settings.py # Pydantic Settings自动读 .env │ └── tools.yaml # 工具注册表YAML 格式非代码 ├── plugins/ # 插件目录可选 │ └── ponytail/rag/ # 第三方插件npm install 后自动链接 ├── frontend/ # React 画布可选dev 专用 │ ├── src/ │ │ ├── App.tsx # 状态机可视化组件 │ │ └── hooks/ # useAgentTrace, useToolRegistry 等 │ └── index.html ├── pyproject.toml # Poetry 依赖管理锁定 Python 3.10 └── ponytail.yaml # Ponytail 专属配置定义 model_url, debug_port 等这个结构不是随意约定而是强制约束agent/core.py必须实现run()方法接收input: dict返回output: dictPonytail 的 CLI 在ponytail run时会反射调用此方法。没有main()函数不写if __name__ __main__:——Agent 是被调度的单元不是独立进程。config/settings.py继承pydantic.BaseSettings所有字段带类型注解如MODEL_URL: str http://localhost:11434/api/chatPonytail CLI 启动时自动加载.env并校验缺失必报错避免“配置没生效却以为是代码 bug”。ponytail.yaml是 CLI 的指令手册debug: true开启 WebSocket 调试plugins: [ponytail/rag]声明插件列表fastapi: {host: 0.0.0.0, port: 8000}定义服务参数——它让 CLI 知道“该做什么”而非靠代码硬编码。我见过太多团队把 Agent 逻辑散落在main.py、utils/、services/里结果换模型时要 grep 十几个文件改 URL。Ponytail 用目录结构强制“关注点分离”Agent 行为在agent/配置在config/界面在frontend/插件在plugins/。新加一个工具只需在config/tools.yaml里加三行 YAMLponytail plugin reload即可生效不用改任何 Python 代码。2.3 为什么 Ponytail 不自己造轮子它如何与现有生态共存Ponytail 的 GitHub README 第一行就写着“Not a framework. A conductor.”不是框架是指挥家。它不提供自己的 LLM 调用封装用httpx.AsyncClient直接调 Ollama、不写自己的 RAG 检索器集成llama_index的VectorStoreIndex、不实现自己的状态机复用XState的createMachine。它的价值在于胶水能力——把已验证的优秀轮子用统一接口粘合成可调度的整体。例如当ponytail run执行时实际调用链是CLI → FastAPI Endpoint (/v1/agent/run) → ponytail.AgentBase.run() → config.settings.MODEL_URL (Ollama API) → agent.tools.web_search.search() (自定义工具) → plugins.rag.retrieve() (第三方插件) → 返回 structured output to frontend via WebSocket这个链路里每个环节都可替换想换 vLLM改config/settings.py里的MODEL_URL http://localhost:8080/v1/chat/completions其他代码零改动想用 LangChain 工具在agent/tools/下写langchain_tool.py继承BaseToolPonytail 的ToolRegistry会自动扫描加载想禁用前端画布删掉frontend/目录ponytail serve依然正常提供 REST API。这种设计让 Ponytail 成为“可插拔的 Agent 开发加速器”而非“必须全盘接受的新框架”。我们团队曾用 Ponytail 快速迁移一个基于 Flask LangChain 的旧 Agent只重写了agent/core.py的run()方法把 Flask 的request.json替换为 Ponytail 的input参数其余工具、提示词、向量库全部复用两天完成迁移客户验收时甚至没发现底层变了。3. 核心模块解析与实操要点从 CLI 命令到 FastAPI 服务再到 React 画布每一步都在解决什么3.1 CLI 层不只是命令集合而是 Agent 生命周期的中央控制器Ponytail 的 CLI基于click库构建表面是ponytail init、ponytail dev等命令实则是 Agent 开发全生命周期的调度器。它不执行业务逻辑只做三件事环境准备、服务协调、状态同步。环境准备ponytail init的隐藏动作执行ponytail init时CLI 不只是复制模板文件。它会校验 Python 环境检查python --version是否 ≥ 3.10pip --version是否 ≥ 22.0确保支持 PEP 660若失败则提示Please upgrade pip: pip install --upgrade pip创建隔离虚拟环境调用python -m venv .venv然后source .venv/bin/activateLinux/macOS或.venv\Scripts\activate.batWindows避免污染全局环境安装核心依赖pip install ponytail[fastapi,react]其中[fastapi,react]是 extras_require确保 FastAPI 和 React 构建工具Vite一并安装生成安全密钥用secrets.token_urlsafe(32)生成SECRET_KEY写入.env用于 FastAPI 的 JWT 认证即使开发环境也强制启用初始化 Git 仓库git init git add . git commit -m chore: init ponytail project为后续 CI/CD 做准备。注意ponytail init默认不安装 Ollama。因为 Ollama 是系统级依赖CLI 无法跨平台安装macOS 用 HomebrewWindows 用 MSILinux 用 apt。它只在ponytail dev启动时检查ollama --version若不存在则清晰提示Ollama not found. Install from https://ollama.com/download绝不尝试静默安装——这是 Ponytail 对“开发者主权”的尊重。服务协调ponytail dev如何同时启动 FastAPI 和 Reactponytail dev是 Ponytail 最惊艳的设计。它不是简单地uvicorn和vite并行启动而是用进程组 端口代理 状态监听实现无缝协同启动顺序先uvicorn app:app --host 127.0.0.1 --port 8000 --reloadFastAPI 服务再vite --host 127.0.0.1 --port 5173React 开发服务器端口代理React 的vite.config.ts配置了server.proxy将/api/*请求代理到http://127.0.0.1:8000避免 CORS状态监听CLI 启动一个后台线程持续curl http://127.0.0.1:8000/healthz和curl http://127.0.0.1:5173/任一服务未就绪则阻塞就绪后打印✅ Ponytail dev server ready at http://localhost:5173进程管理所有子进程加入同一 process groupCtrlC时发送SIGINT给整个组确保 FastAPI 和 Vite 同时退出不留僵尸进程。实测下来ponytail dev启动时间稳定在 8~12 秒MacBook Pro M2比手动启动快 3 倍。更关键的是它解决了“前端连不上后端”的经典问题——代理配置、端口冲突、启动时序全部由 CLI 封装开发者只管写代码。状态同步ponytail run如何让 CLI 和前端画布共享执行上下文ponytail run命令看似简单却是 Ponytail 的技术难点。它要同时满足CLI 终端输出结构化日志JSON Lines 格式便于管道处理React 画布实时渲染执行状态WebSocket 推送FastAPI 服务记录完整 trace用于后续分析。实现方式是三端共享同一个 Trace IDCLI 执行ponytail run --input {query:北京天气}时生成唯一trace_id uuid4().hexCLI 通过 HTTP POSThttp://127.0.0.1:8000/v1/agent/run发送请求Header 带X-Trace-ID: {trace_id}FastAPI 的 middleware 拦截请求将trace_id注入request.state.trace_id并存入 Redisredis.setex(ftrace:{trace_id}, 300, json.dumps({}))Agent 执行中每一步LLM 调用、Tool 执行都向 Redis 更新trace:{trace_id}的字段如step_1_input,step_2_outputReact 前端通过const ws new WebSocket(ws://localhost:5173/ws?trace_id trace_id)订阅该 trace实时获取更新。这样你在 CLI 输入命令终端立刻显示{step:1,status:running,input:北京天气}同时浏览器画布自动跳转到对应步骤的可视化节点。调试时ponytail trace --id {trace_id}可导出完整 JSON trace供离线分析。3.2 FastAPI 层轻量但不失健壮的服务骨架Agent 的“心脏”在哪里跳动Ponytail 的 FastAPI 服务app/main.py只有 127 行代码却承载了 Agent 的核心调度逻辑。它不追求功能堆砌只做四件事路由分发、状态管理、插件加载、安全防护。路由分发/v1/agent/runendpoint 的精巧设计FastAPI 的app.post(/v1/agent/run)endpoint 是 Ponytail 的神经中枢。它的签名是app.post(/v1/agent/run) async def run_agent( input: dict Body(..., example{query: 总结这篇文档}), trace_id: str Header(default_factorylambda: str(uuid4())), settings: Settings Depends(get_settings), agent: AgentBase Depends(get_agent), ) - JSONResponse:关键设计点Body(..., example{...})Pydantic 自动生成 Swagger 示例前端调试时点“Try it out”直接填充示例数据Header(default_factory...)trace_id从 Header 读取若未提供则自动生成确保每个请求有唯一标识Depends(get_agent)依赖注入AgentBase实例get_agent()函数从agent/core.py动态导入支持热重载ponytail dev时修改core.pyUvicorn 自动 reload返回JSONResponse而非dict显式设置media_typeapplication/json避免 FastAPI 自动序列化时的时区/精度问题。Agent 执行的核心逻辑在agent.run(input)但 Ponytail 在其前后做了关键增强# 执行前记录开始时间、初始化 trace start_time time.time() redis.setex(ftrace:{trace_id}:meta, 300, json.dumps({ start_time: start_time, input: input, status: running })) # 执行中捕获异常记录错误 try: output await agent.run(input) except Exception as e: error_trace traceback.format_exc() redis.hset(ftrace:{trace_id}, error, error_trace) raise HTTPException(status_code500, detailstr(e)) # 执行后记录耗时、状态 duration time.time() - start_time redis.hset(ftrace:{trace_id}:meta, duration, duration) redis.hset(ftrace:{trace_id}:meta, status, completed)这段代码让 Ponytail 的 FastAPI 服务具备了生产级可观测性每个 trace 都有开始时间、输入、输出、错误堆栈、耗时无需额外接入 Prometheus 或 ELK。状态管理Redis 不是必需品但它是 Ponytail 的“记忆中枢”Ponytail 默认使用 Redis 存储 trace 数据但设计上支持降级。config/settings.py中class Settings(BaseSettings): REDIS_URL: str redis://localhost:6379/0 # 若 REDIS_URL 为空则 fallback 到内存字典仅限开发 validator(REDIS_URL, alwaysTrue) def check_redis(cls, v): if not v.strip(): logger.warning(REDIS_URL not set, using in-memory storage (not for production)) return v内存模式dict在ponytail dev时足够用但生产环境ponytail serve强制要求 Redis。为什么因为 Agent 的状态必须跨请求持久化。例如一个需要多轮对话的客服 Agent用户第二次提问时服务必须能从 Redis 读取上次的conversation_id和历史消息。Ponytail 的agent/memory.py封装了RedisMemoryBackend提供get_conversation()和append_message()方法Agent 逻辑里直接调用无需关心底层是 Redis 还是其他存储。实操心得我们线上部署时Redis 用的是 AWS ElastiCache集群模式REDIS_URL配置为redis://my-cluster.xxxxx.0001.use1.cache.amazonaws.com:6379/0。为防 Redis 故障我们在get_memory_backend()中加了熔断器tenacity.Retrying连续 3 次连接失败则降级到内存模式并记录告警日志。Ponytail 的设计允许这种弹性降级这是很多同类框架忽略的细节。插件加载ponytail plugin install背后的模块动态发现机制Ponytail 的插件系统plugins/目录采用命名空间包 动态 import。当你执行ponytail plugin install ponytail/ragCLI 实际做了npm install ponytail/rag --prefix ./plugins注意--prefix指向plugins/目录在plugins/ponytail/rag/package.json中查找ponytailPlugin字段确认它是一个合法 Ponytail 插件修改pyproject.toml的[tool.ponytail.plugins]部分添加rag ponytail/rag重启服务后app/plugins.py的load_plugins()函数会遍历plugins/目录对每个子目录执行importlib.import_module(fplugins.{plugin_name}.main)并调用其register()方法。插件的main.py必须暴露register()函数例如 RAG 插件# plugins/ponytail/rag/main.py def register(): from ponytail.plugins import PluginRegistry from .retriever import RAGRetriever PluginRegistry.register_tool(rag_retrieve, RAGRetriever())PluginRegistry是一个单例维护全局工具注册表。Agent 在core.py中调用self.tool_registry.get(rag_retrieve)即可获取实例。这种设计让插件开发像写 npm 包一样简单且完全隔离——RAG 插件的requirements.txt不会影响主项目的依赖。3.3 React 画布层不是炫技的 UI而是 Agent 行为的“CT 扫描仪”Ponytail 的 React 前端frontend/src/App.tsx代码量不大但交互逻辑极其精密。它不渲染静态页面而是实时解析 Agent 的执行状态机并提供干预能力。状态机可视化XState 如何映射 Agent 的决策流Ponytail 的 Agent 状态机基于 XState 的createMachine定义。agent/core.py中的run()方法本质是状态流转# agent/core.py class MyAgent(AgentBase): async def run(self, input: dict) - dict: # Step 1: Parse query parsed await self.llm_call(parse_query, input[query]) # Step 2: Retrieve docs docs await self.tool_registry.get(rag_retrieve).invoke(parsed) # Step 3: Generate answer answer await self.llm_call(generate_answer, {docs: docs, query: input[query]}) return {answer: answer}React 画布通过 WebSocket 订阅trace_id收到的每条消息包含step_number、step_name、statuspending/running/success/error、input、output。前端用 XState 的interpret创建一个运行时机器// frontend/src/machines/agentMachine.ts export const agentMachine createMachine({ id: agent, initial: idle, states: { idle: { on: { START: parsing } }, parsing: { on: { SUCCESS: retrieving, ERROR: failed } }, retrieving: { on: { SUCCESS: generating, ERROR: failed } }, generating: { on: { SUCCESS: done, ERROR: failed } }, done: { type: final }, }, }); // frontend/src/App.tsx const service interpret(agentMachine).start(); service.send({ type: START, data: { trace_id } });当 WebSocket 收到{step: 1, status: success, output: {...}}前端service.send({ type: SUCCESS })状态机自动跳转到retrieving画布上的节点高亮变色。这种映射让开发者一眼看出 Agent 卡在哪步——比翻日志快十倍。可干预调试如何在画布里“暂停并修改”Agent 的执行Ponytail 画布最颠覆性的功能是Step Replay。点击某一步节点如retrieving面板右侧显示该步的inputJSON 格式和output折叠显示。点击“Edit Replay”按钮前端将当前input渲染为可编辑的 JSON 编辑器Monaco Editor用户修改input.args.query为上海天气点击“Replay”前端发送POST /v1/agent/replayBody 为{trace_id, step_number, new_input}FastAPI 的replayendpoint 从 Redis 读取该 trace 的历史状态重放step_number及之后的所有步骤新结果覆盖原 trace。这个功能让调试效率质变。以前要改代码、重启服务、重走全流程现在在浏览器里改两行 JSON1 秒内看到新结果。我们曾用它快速验证一个 RAG 插件的检索逻辑原始查询苹果手机价格返回了无关的农业文档编辑input为{query: iPhone 15 价格}Replay 后立刻看到正确结果确认是查询改写模块的问题。注意Step Replay 仅在ponytail dev模式启用生产环境ponytail serve禁用此 endpoint符合安全规范。画布右上角始终显示DEV MODE水印避免误用。4. 完整实操流程从零搭建一个“文档摘要 Agent”手把手带你跑通 Ponytail 全链路4.1 环境准备三分钟搞定本地开发环境前提条件Python 3.10推荐 3.11Node.js 18Vite 要求Ollamaollama run llama3:8b可运行提示Windows 用户请确保已安装 WSL2Ubuntu 22.04Ponytail 对 Windows 原生支持有限尤其路径分隔符和信号处理WSL2 是最佳实践。步骤 1安装 Ponytail CLI打开终端WSL2 或 macOS/Linux执行# 创建项目目录 mkdir doc-summarizer cd doc-summarizer # 安装 Ponytail全局非项目内 pip install ponytail-cli # 验证安装 ponytail --version # 输出ponytail 0.8.2步骤 2初始化项目# 使用内置模板base 模板最简rag 模板含 RAG 插件 ponytail create . --templatebase # 目录结构生成后检查关键文件 ls -la # .env ponytail.yaml pyproject.toml agent/ config/ frontend/此时.env文件已生成内容类似SECRET_KEY3a7b9c2d... MODEL_URLhttp://localhost:11434/api/chat REDIS_URLredis://localhost:6379/0步骤 3启动 Ollama 模型新开一个终端运行# 拉取 llama3:8b约 4.7GB首次需下载 ollama pull llama3:8b # 启动 Ollama 服务默认监听 11434 ollama serve注意ollama serve必须在ponytail dev之前启动否则 Ponytail 会报错Ollama not responding。我们团队的习惯是一个终端跑ollama serve一个终端跑ponytail dev永不关闭。4.2 编写 Agent 核心逻辑用 20 行代码实现文档摘要进入agent/core.py替换为以下内容# agent/core.py from typing import Dict, Any, Optional from ponytail.agent import AgentBase from ponytail.tools import ToolRegistry class DocSummarizer(AgentBase): A simple agent that summarizes uploaded documents using LLM. Input: {file_path: /path/to/doc.pdf, max_length: 200} Output: {summary: Summary text..., word_count: 156} async def run(self, input: Dict[str, Any]) - Dict[str, Any]: # Step 1: Read file content (simulated) file_path input.get(file_path, ) if not file_path: raise ValueError(file_path is required) # Simulate reading (in real use, integrate with pdfplumber or similar) content fDocument content from {file_path}. This is a sample document about AI agents and their development workflows... # Step 2: Call LLM to summarize prompt fSummarize the following document in {input.get(max_length, 150)} words or less. Focus on key points and avoid fluff. Document: {content} llm_response await self.llm_call( modelllama3:8b, messages[{role: user, content: prompt}] ) # Step 3: Format output summary llm_response.get(message, {}).get(content, ) word_count len(summary.split()) return { summary: summary.strip(), word_count: word_count, input_file: file_path }关键点说明AgentBase提供self.llm_call()方法自动对接MODEL_URLOllama APIinput是字典结构由你定义Ponytail 不做强约束llm_call()返回标准 Ollama 响应格式message.content是文本错误处理用raise ValueErrorFastAPI 会自动转为 400 错误。4.3 配置与启动ponytail dev一键点亮调试画布步骤 1配置模型 URL编辑config/settings.py确保MODEL_URL指向 Ollama# config/settings.py class Settings(BaseSettings): MODEL_URL: str http://localhost:11434/api/chat # Ollama default # ... 其他配置步骤 2启动开发环境回到项目根目录执行ponytail dev等待 10 秒左右终端输出✅ Ponytail dev server ready at http://localhost:5173 → FastAPI: http://localhost:8000 → Frontend: http://localhost:5173 → WebSocket: ws://localhost:5173/ws打开浏览器访问http://localhost:5173你会看到 Ponytail 的 React 画布界面左侧是空白的状态流转图右侧是“Run Agent”按钮。4.4 调试与验证在画布里“看见”Agent 的每一次思考步骤 1发起测试请求在画布右侧面板点击 “Run Agent”输入 JSON{ file_path: /tmp/sample.pdf, max_length: 100 }点击 “Submit”画布立即变化左侧状态图出现三个节点idle→running→donerunning节点高亮右侧日志区滚动显示[2024-06-15 14:22:33] STEP 1: Calling LLM with prompt... [2024-06-15 14:22:35] STEP 1: Received response (1.2s)步骤 2查看并干预执行当done节点亮起点击它右侧展开详细结果{ summary: This document discusses AI agent development workflows, emphasizing the need for integrated tooling and debugging capabilities. Key challenges include environment setup, state management, and plugin interoperability..., word_count: 98, input_file: /tmp/sample.pdf }点击 “Edit Replay”将max_length改