企业官网建设流程全解析

1. 项目概述：一个轻量级、可插拔的 CLI Agent 开发框架

“ponytail”这个名字乍一听像某种发型，但在开发者社区里，它正悄然成为新一代 CLI 工具链中一个务实、克制、不炫技却异常好用的代名词。我第一次在 GitHub 上看到 ponytail 仓库时，没点进去看 README，光看 star 增长曲线和 issue 里高频出现的词——“终于不用再写 argparse 嵌套了”、“插件热加载实测 300ms 内生效”、“FastAPI 后端直接复用，连路由都省了”——就意识到：这不是又一个玩具项目，而是一套真正从终端用户和 CLI 维护者双重痛点出发设计的工程化方案。

ponytail 的核心定位非常清晰：它不是一个 AI Agent 框架，也不是一个通用命令行解析器，而是一个面向 CLI Agent 场景的运行时胶水层。所谓 CLI Agent，指的是那些需要在终端中完成“感知—决策—执行”闭环的工具，比如：

• 本地代码审查助手（扫描 Git diff，调用 LLM 生成建议，自动提交修正）；
• DevOps 现场诊断工具（读取 Prometheus 指标 + 日志片段，生成根因摘要并推荐修复命令）；
• 数据管道调度代理（监听 S3 新文件事件，触发 FastAPI 接口启动预处理任务，回传进度）；
• 甚至是你自己写的“每日晨会速记 agent”（语音转文字 → 提取待办 → 自动追加到 Notion 数据库）。

这些场景的共性是：命令行入口要干净，逻辑要可插拔，状态要可观察，后端能力要能复用，且不能让用户等太久。ponytail 正是为解决这五点而生。它不替代 FastAPI，而是让 FastAPI 的路由、中间件、依赖注入机制，能被 CLI 命令天然继承；它不重写 JavaScript 运行时，而是通过 zcode cli 提供的标准化 bridge 协议，让 JS 插件与 Python 主体无缝通信；它不定义 AI 能力边界，但强制所有插件必须声明输入 schema 和输出 contract，从而让 “agent anywhere” 成为可能——不是靠抽象层，而是靠契约。

你不需要懂 LangGraph 或 Ollama 才能上手 ponytail；但如果你已经用 FastAPI 写过服务、用 JavaScript 写过浏览器交互、用 CLI 管理过几十个子命令，那么 ponytail 就像给你配了一把万能扳手：原来拧螺丝得换三把工具，现在一把搞定，还带扭矩反馈。

2. 架构设计与核心思路拆解：为什么 ponytail 不是另一个 CLI 解析器？

2.1 传统 CLI 工具的三大隐性成本

在 ponytail 出现前，我维护过 7 个不同业务线的 CLI 工具，最深的体会是：CLI 的复杂度从来不在命令解析本身，而在命令之后的“上下文维持”。举几个真实踩过的坑：

• 参数爆炸式耦合：mytool run --model gpt-4 --timeout 30 --retry 2 --log-level debug --config ./conf.yaml --dry-run—— 这 7 个参数里，只有--model和--timeout是业务逻辑真正需要的，其余全是运维/调试/兼容性补丁。每次新增一个功能，就要同步更新 help 文本、参数校验、默认值 fallback、环境变量映射……最后argparse的add_argument()调用比业务代码还多。

• 插件加载即地狱：曾用importlib.util.spec_from_file_location()动态加载 JS 插件，结果发现 Node.js 子进程启动耗时 800ms+，且无法共享 FastAPI 的Depends()注入的数据库连接池。用户敲下mytool analyze --plugin js:report，光等插件初始化就卡住 1.2 秒，体验断层。

• 状态不可见、不可控：CLI 执行完就退出，但 agent 需要知道“上次执行是否成功”、“当前缓存命中率多少”、“模型 token 使用量趋势”。我们试过用 SQLite 本地存状态，结果发现 Windows 上文件锁冲突频发；改用 Redis 又引入新依赖，小团队根本不想运维。

ponytail 的破局点很务实：把 CLI 当作 FastAPI 的一个特殊客户端，而不是独立进程。它的架构图没有炫酷的分层箭头，只有一条主干：

Terminal → ponytail CLI 入口 → FastAPI App 实例 → 插件注册中心 → (Python 插件 / JS 插件 bridge) → 业务逻辑

关键在于：CLI 启动时，FastAPI app 已经在内存中完整构建完毕——包括所有@app.get()路由、Depends()依赖、BackgroundTasks队列、甚至/docsSwagger UI。CLI 命令不是“调用 API”，而是直接复用同一进程内的函数指针和对象实例。这就绕开了 HTTP 序列化开销、进程创建延迟、跨语言 IPC 复杂度。

2.2 “插件即路由”的设计哲学

ponytail 的插件系统彻底抛弃了传统entry_points或setuptools插件发现机制。它的插件注册方式，本质上是在 FastAPI 的APIRouter上做动态挂载：

# plugins/json_validator.py from fastapi import APIRouter, Depends from ponytail.plugin import PluginBase from ponytail.dependencies import get_db_session router = APIRouter() class JSONValidatorPlugin(PluginBase): name = "json-validator" description = "Validate JSON against OpenAPI schema" @router.post("/validate") async def validate_json( data: dict, db = Depends(get_db_session) ): # 直接使用 FastAPI 的依赖注入，无需重新连接数据库 result = await db.execute("SELECT ...") # 示例 return {"valid": True, "errors": []}

CLI 调用ponytail json-validator validate --data '{"key": "value"}'时，ponytail 并不启动新进程，而是：

1. 查找json-validator插件模块；
2. 获取其router对象；
3. 在内存中执行router.routes[0].endpoint(data=..., db=...)；
4. 将返回值格式化为终端友好的 JSON 或表格。

这种设计带来三个硬性收益：

• 零序列化延迟：Python dict 直接传参，无 JSON encode/decode；
• 依赖自然复用：get_db_session、get_llm_client等全局依赖，CLI 和 Web 请求共享同一实例；
• 调试一致性：你在curl -X POST http://localhost:8000/json-validator/validate测试的逻辑，和ponytail json-validator validate执行的是完全相同的函数体。

提示：ponytail 插件必须继承PluginBase并实现name和description，这是强制契约。它不关心你是用 Python 还是 JavaScript 写的——JS 插件通过zcode clibridge 被包装成符合 FastAPIAPIRouter接口的 Python 对象，对外完全透明。

2.3 JavaScript 插件的 bridge 协议：zcode cli 如何做到“不黑盒”

网络热词里反复出现的zcode cli，其实是 ponytail 的 JS 插件通信协议标准。它不是某个具体 npm 包，而是一组明确定义的 IPC 规则：

• 启动协议：JS 插件进程启动时，必须监听stdin的START消息，并向stdout返回{ "protocol": "zcode-v1", "capabilities": ["async", "stream"] }；
• 调用协议：CLI 主进程向stdin发送 JSON-RPC 2.0 格式请求，如{"jsonrpc":"2.0","method":"validate","params":{"data":"{...}"}}；
• 响应协议：JS 进程处理后，向stdout输出{"jsonrpc":"2.0","result":{"valid":true},"id":1}；
• 错误协议：任何未捕获异常，必须以{"jsonrpc":"2.0","error":{"code":-32603,"message":"Invalid JSON"},"id":1}格式返回。

ponytail 的zcode_bridge.py模块只做三件事：启动 Node.js 进程、转发 stdin/stdout、解析 JSON-RPC。它不解析 JS 代码、不注入 polyfill、不修改 globalThis——这意味着你可以在插件里用 ESM、Top-level await、甚至fetch()调用外部 API，只要遵守协议即可。

我实测过：一个用zod做 schema 校验的 JS 插件，冷启动耗时 420ms（Node.js 初始化 + 依赖加载），但热加载后（即 ponytail 进程不退出，仅 reload 插件）只需 85ms。这个数字比任何 V8 snapshot 方案都稳定，因为它是协议级优化，而非引擎级黑盒。

3. 核心细节解析与实操要点：从零搭建一个 ponytail CLI Agent

3.1 环境准备与最小可行项目结构

ponytail 对 Python 版本要求严格：仅支持 Python 3.9+，原因在于它深度依赖typing.Annotated和asyncio.Runner（3.11+）。Windows 用户需注意：uvloop在 Windows 上不可用，但 ponytail 默认不启用它，所以无需额外配置。

一个标准 ponytail 项目的目录结构，比 FastAPI 官方教程更精简：

my-agent/ ├── pyproject.toml # 必须包含 [project] 和 [project.optional-dependencies] ├── main.py # ponytail CLI 入口，仅 3 行代码 ├── plugins/ │ ├── __init__.py # 空文件，标记为包 │ └── hello_world.py # 第一个插件 └── tests/ └── test_hello.py # 插件单元测试模板

pyproject.toml的关键配置：

[project] name = "my-agent" version = "0.1.0" requires-python = ">=3.9" dependencies = [ "ponytail>=0.8.0", "fastapi>=0.110.0", "uvicorn>=0.29.0", ] [project.optional-dependencies] js = ["nodejs"] # 仅当需要 JS 插件时才安装 nodejs（实际是提示用户需预装）

main.py是整个项目的灵魂，但它出奇地短：

# main.py from ponytail.cli import PonytailCLI from ponytail.app import create_app if __name__ == "__main__": app = create_app() # 创建 FastAPI app 实例 cli = PonytailCLI(app) # 将 app 注入 CLI 运行时 cli.run() # 启动命令行解析器

这段代码的威力在于：create_app()内部会自动扫描plugins/目录下所有.py文件，导入并注册其中的APIRouter。你不需要手动include_router()，也不需要app.include_router(router)—— ponytail 在create_app()中完成了全部自动化。

注意：plugins/目录名不可更改，这是 ponytail 的硬编码约定。如果想用其他名字（如extensions/），必须在create_app(plugins_dir="extensions")中显式传参，但官方文档明确建议保持默认，避免团队协作时的认知偏差。

3.2 编写第一个 Python 插件：hello-world 的 5 种写法

很多新手以为插件就是写个函数，但 ponytail 的插件本质是FastAPI 路由的语义封装。我们以hello-world插件为例，展示不同复杂度下的正确写法：

写法一：最简版（无依赖、无异步）

# plugins/hello_world.py from fastapi import APIRouter from ponytail.plugin import PluginBase router = APIRouter() class HelloWorldPlugin(PluginBase): name = "hello" description = "Say hello to the world" @router.get("/") def say_hello(name: str = "World"): return {"message": f"Hello, {name}!"}

CLI 调用：ponytail hello get --name Ponytail
输出：{"message": "Hello, Ponytail!"}

写法二：带 FastAPI 依赖注入（复用数据库）

# plugins/hello_world.py from fastapi import APIRouter, Depends from ponytail.plugin import PluginBase from ponytail.dependencies import get_db_session # 假设已定义 router = APIRouter() class HelloWorldPlugin(PluginBase): name = "hello" description = "Greet user and log greeting to DB" @router.post("/greet") async def greet_user( name: str, db = Depends(get_db_session) # 直接复用 FastAPI 的依赖 ): # 插入日志记录 await db.execute("INSERT INTO greetings (name, timestamp) VALUES (:name, NOW())", {"name": name}) return {"status": "logged", "greeting": f"Hello, {name}!"}

写法三：支持流式响应（适合大模型输出）

# plugins/hello_world.py from fastapi import APIRouter, Response from starlette.responses import StreamingResponse from ponytail.plugin import PluginBase router = APIRouter() class HelloWorldPlugin(PluginBase): name = "hello" description = "Stream greeting words one by one" @router.get("/stream") async def stream_greeting(): async def generate(): for word in ["Hello", "Ponytail", "CLI", "Agent"]: yield f"data: {word}\n\n" await asyncio.sleep(0.5) # 模拟流式生成 return StreamingResponse(generate(), media_type="text/event-stream")

CLI 调用ponytail hello stream会实时打印每行data: Hello，无需等待全部生成。

写法四：声明式输入校验（用 Pydantic v2）

# plugins/hello_world.py from pydantic import BaseModel, Field from fastapi import APIRouter from ponytail.plugin import PluginBase class GreetingRequest(BaseModel): name: str = Field(..., min_length=2, max_length=50, description="User's name") language: str = Field("en", pattern="^(en|zh|ja)$", description="Language code") router = APIRouter() class HelloWorldPlugin(PluginBase): name = "hello" description = "Greet with validation" @router.post("/validated") def validated_greet(req: GreetingRequest): translations = { "en": f"Hello, {req.name}!", "zh": f"你好，{req.name}！", "ja": f"こんにちは、{req.name}！" } return {"message": translations.get(req.language, translations["en"])}

CLI 调用ponytail hello validated --data '{"name":"Alice","language":"zh"}'，若name小于 2 字符，会返回标准 FastAPI 422 错误。

写法五：插件元数据扩展（支持 CLI help 自动生成）

# plugins/hello_world.py from fastapi import APIRouter from ponytail.plugin import PluginBase router = APIRouter() class HelloWorldPlugin(PluginBase): name = "hello" description = "Say hello to the world" version = "1.0.0" author = "Your Name" license = "MIT" @router.get("/") def say_hello(name: str = "World"): """Say hello to a person. This is the docstring that becomes CLI help text. It supports Markdown formatting: **bold**, *italic*. """ return {"message": f"Hello, {name}!"}

CLI 执行ponytail hello --help会自动显示say_hello的 docstring 作为命令描述，ponytail --help则列出所有插件的name和description。

实操心得：插件类名（HelloWorldPlugin）可以任意命名，但name属性必须是 CLI 中使用的命令名，且必须全小写、无下划线、无空格。ponytail 会将name作为子命令注册，因此name = "json-validator"对应ponytail json-validator ...，而name = "JSON Validator"会导致解析失败。

3.3 JavaScript 插件开发：从零编写一个 zcode-compliant 插件

JavaScript 插件不是“用 JS 写个函数然后扔给 ponytail”，而是实现一个符合 zcode v1 协议的独立 Node.js 进程。以下是完整开发流程：

步骤一：初始化 JS 插件项目

mkdir js-plugins && cd js-plugins npm init -y npm install zod # 用于输入校验，非必需但强烈推荐

步骤二：编写index.js（必须是入口文件）

// js-plugins/index.js const { createInterface } = require('readline'); const { parse } = require('jsonc-parser'); // 支持注释的 JSON 解析器 // 1. 启动握手 console.log(JSON.stringify({ protocol: "zcode-v1", capabilities: ["async"] })); // 2. 监听 stdin const rl = createInterface({ input: process.stdin, output: process.stdout, terminal: false }); // 3. 处理 JSON-RPC 请求 rl.on('line', (line) => { try { const req = JSON.parse(line); if (req.jsonrpc !== "2.0") throw new Error("Invalid JSON-RPC version"); // 路由分发 switch (req.method) { case "validate": handleValidate(req).catch(err => sendError(req.id, err)); break; default: sendError(req.id, new Error(`Unknown method: ${req.method}`)); } } catch (err) { sendError(0, err); // id=0 表示协议错误 } }); async function handleValidate(req) { const { data } = req.params || {}; if (!data) { sendError(req.id, new Error("Missing 'data' parameter")); return; } try { // 用 zod 校验 JSON 结构 const result = JSON.parse(data); sendResult(req.id, { valid: true, data: result }); } catch (e) { sendError(req.id, new Error(`Invalid JSON: ${e.message}`)); } } function sendResult(id, result) { console.log(JSON.stringify({ jsonrpc: "2.0", result, id })); } function sendError(id, error) { console.log(JSON.stringify({ jsonrpc: "2.0", error: { code: -32603, message: error.message }, id })); }

步骤三：在 Python 插件中桥接 JS 插件

# plugins/js_validator.py from fastapi import APIRouter, Depends from ponytail.plugin import PluginBase from ponytail.bridge.zcode import ZCodeBridge router = APIRouter() class JSValidatorPlugin(PluginBase): name = "js-validator" description = "Validate JSON using JavaScript plugin" def __init__(self): # 指向 JS 插件路径，ponytail 会自动管理进程生命周期 self.bridge = ZCodeBridge( plugin_path="./js-plugins/index.js", node_executable="node" # 可指定绝对路径如 "/usr/local/bin/node" ) @router.post("/validate") async def validate_json(self, data: str): # 向 JS 进程发送 JSON-RPC 请求 result = await self.bridge.call("validate", {"data": data}) return result

CLI 调用ponytail js-validator validate --data '{"key":"value"}'，ponytail 会：

• 启动node ./js-plugins/index.js；
• 发送{"jsonrpc":"2.0","method":"validate","params":{"data":"{...}"}}；
• 等待 stdout 输出并解析；
• 将结果返回给终端。

注意事项：JS 插件进程由 ponytail 全权管理，不要在 JS 代码中调用process.exit()。ponytail 会在 CLI 命令结束或插件 reload 时主动 kill 进程。实测发现，如果 JS 插件意外崩溃，ponytail 会在 5 秒内自动重启，且 CLI 用户无感知——这是通过subprocess.Popen的start_new_session=True和信号隔离实现的。

4. 实操过程与核心环节实现：部署、打包与生产化落地

4.1 FastAPI 项目目录结构的 ponytail 适配

ponytail 并不改变 FastAPI 的标准目录结构，但它对某些模式有强约束。一个生产级 ponytail 项目，推荐采用以下结构：

my-agent/ ├── pyproject.toml ├── main.py ├── app/ │ ├── __init__.py │ ├── core/ # 配置、安全、日志 │ │ ├── config.py # Settings 类，支持 .env │ │ └── logger.py # 统一日志格式，CLI 和 Web 共享 │ ├── api/ # FastAPI 路由（供 Web 访问） │ │ └── v1/ # 版本化 API │ │ └── endpoints.py │ ├── plugins/ # CLI 插件（与 API 路由物理隔离，但逻辑复用） │ │ ├── __init__.py │ │ └── data_cleaner.py # 可同时被 CLI 和 API 调用 │ └── models/ # Pydantic 模型，CLI 和 API 共享 │ └── schemas.py ├── tests/ └── docs/ # 自动生成的 CLI help 文档（ponytail build-docs）

关键设计原则：

• API 和 Plugins 共享models/和core/，但不共享api/和plugins/目录：api/v1/endpoints.py中的路由函数，可以被plugins/data_cleaner.py直接 import 调用，反之亦然；
• CLI 插件不直接 importapi/模块：避免循环依赖。正确做法是将业务逻辑抽到app/core/或app/models/中；
• main.py必须位于项目根目录：ponytail 的create_app()会从main.py所在目录向上搜索app/和plugins/，路径错位会导致插件加载失败。

我曾在一个金融风控 CLI 项目中验证此结构：plugins/risk_score.py调用app.core.risk_engine.calculate_score()，而api/v1/endpoints.py中的/score接口也调用同一函数。单元测试tests/test_risk_score.py只需 mockcalculate_score一次，就能覆盖 CLI 和 Web 两种调用路径，测试覆盖率提升 37%。

4.2 Windows 下打包为单文件可执行程序

ponytail 官方明确支持 PyInstaller 打包，但 Windows 环境有特殊注意事项。以下是经过 12 次失败后总结的可靠流程：

步骤一：安装依赖并冻结环境

pip install ponytail fastapi uvicorn pyinstaller pip freeze > requirements.txt

步骤二：编写build.spec（关键！）

# build.spec # -*- mode: python ; coding: utf-8 -*- block_cipher = None a = Analysis( ['main.py'], # 入口文件 pathex=['.'], binaries=[], datas=[ # 必须包含 plugins/ 目录，否则 CLI 找不到插件 ('plugins', 'plugins'), # 必须包含 app/ 目录（如果存在） ('app', 'app'), # FastAPI 的静态文件（Swagger UI） ('venv/Lib/site-packages/fastapi/openapi', 'fastapi/openapi'), ], hiddenimports=[ # 显式添加 ponytail 的动态导入模块 'ponytail.plugin', 'ponytail.bridge.zcode', # FastAPI 的依赖注入需要的模块 'starlette.datastructures', 'pydantic._internal._generate_schema', ], hookspath=[], hooksconfig={}, runtime_hooks=[], excludes=[], win_no_prefer_redirects=False, win_private_assemblies=False, cipher=block_cipher, noarchive=False, ) pyz = PYZ(a.pure, a.zipped_data, cipher=block_cipher) exe = EXE( pyz, a.scripts, a.binaries, a.zipfiles, a.datas, [], name='my-agent', debug=False, bootloader_ignore_signals=False, strip=False, upx=True, console=True, # 必须为 True，否则 CLI 无法读取 stdin disable_windowed_traceback=False, argv_emulation=False, target_arch=None, codesign_identity=None, entitlements_file=None, )

步骤三：执行打包并验证

pyinstaller build.spec # 输出在 dist/my-agent/ 目录下 dist/my-agent/my-agent.exe --help # 应正常显示所有插件

常见问题排查：

• 插件加载失败：检查dist/my-agent/plugins/是否存在，且.py文件未被 PyInstaller 误删；
• JS 插件无法启动：Windows 默认不识别node命令，需在ZCodeBridge初始化时指定node_executable="C:\\Program Files\\nodejs\\node.exe"；
• 打包后首次启动慢：PyInstaller 会将所有.py编译为.pyc，首次加载需解压，实测平均增加 1.2 秒冷启动时间，但后续执行无影响。

实操心得：不要用--onefile模式打包 ponytail CLI。虽然它生成单个 exe，但插件目录会被打包进资源区，无法被 ponytail 的importlib动态加载。必须用--onedir（默认模式），并确保plugins/目录与 exe 同级。

4.3 FastAPI 调用 Ollama 的集成实践

网络热词中高频出现的fastapi调用ollama，在 ponytail 中有独特优势：CLI 命令可以直接复用 FastAPI 中已配置好的 Ollama 客户端，无需重复初始化。

假设你的app/core/ollama_client.py已定义：

# app/core/ollama_client.py from ollama import AsyncClient from ponytail.core.config import settings class OllamaClient: def __init__(self): self.client = AsyncClient(host=settings.OLLAMA_HOST) async def chat(self, model: str, messages: list): return await self.client.chat(model=model, messages=messages)

在插件中直接使用：

# plugins/ai_review.py from fastapi import APIRouter, Depends from ponytail.plugin import PluginBase from app.core.ollama_client import OllamaClient router = APIRouter() class AIReviewPlugin(PluginBase): name = "ai-review" description = "Review code diff with Ollama" def __init__(self, ollama: OllamaClient = Depends(OllamaClient)): self.ollama = ollama @router.post("/review") async def review_code(self, diff: str): response = await self.ollama.chat( model="codellama", messages=[{"role": "user", "content": f"Review this git diff:\n{diff}"}] ) return {"review": response['message']['content']}

CLI 调用ponytail ai-review review --diff "$(git diff HEAD~1)"，全程复用同一个AsyncClient实例，连接池、超时设置、重试策略全部继承。

注意：Ollama 的AsyncClient默认不支持连接池复用，需在OllamaClient.__init__()中显式传入httpx.AsyncClient实例，并配置limits参数。ponytail 官方示例中提供了app/core/httpx_client.py的参考实现，可直接复用。

5. 常见问题与排查技巧实录：一线开发者踩过的坑与解决方案

5.1 CLI 命令执行卡顿超过 2 秒的 5 种原因及定位方法

ponytail 的设计目标是亚秒级响应，但实际使用中常遇到卡顿。以下是我在 3 个项目中总结的高频原因和精准定位法：

独家技巧：ponytail 内置--profile参数，可生成火焰图。执行ponytail --profile hello get --name World，会生成profile.html，点击即可查看各函数耗时占比。我曾用它发现一个插件中json.loads()被调用了 17 次，改用orjson后性能提升 4.2 倍。

5.2 JavaScript 插件开发中的 3 个致命陷阱

JS 插件看似简单，但因协议约束，极易写出“能跑但不稳定”的代码。以下是血泪教训：

陷阱一：在 JS 插件中使用console.log()输出非 JSON-RPC 内容
现象：CLI 命令偶尔返回乱码或解析失败。
原因：ponytail 的zcode_bridge严格按行解析stdout，任何非 JSON-RPC 输出（如console.log("debug: start")）都会破坏协议流。
解决方案：JS 插件中禁用所有console.log()，改用process.stderr.write("debug: ...\n")输出调试信息。stderr 不参与协议解析，完全安全。

陷阱二：JS 插件未处理 SIGTERM 信号
现象：多次执行ponytail js-plugin command后，系统残留大量node进程。
原因：ponytail 在 CLI 结束时发送SIGTERM给 JS 进程，但默认 Node.js 进程不监听该信号，导致僵死。
解决方案：在 JS 插件顶部添加：

process.on('SIGTERM', () => { console.log(JSON.stringify({ jsonrpc: "2.0", result: { status: "shutdown" }, id: 0 })); process.exit(0); });

陷阱三：JS 插件中require()路径错误
现象：ponytail js-plugin command报错Cannot find module './utils'。
原因：JS 插件的工作目录是main.py所在目录，而非index.js所在目录。require('./utils')会从项目根目录查找，而非js-plugins/目录。
解决方案：统一使用require.resolve('./utils')，或在index.js开头添加：

process.chdir(__dirname); // 切换工作目录到插件目录

5.3 FastAPI Windows 打包日志丢失问题的根治方案

uvicorn fastapi 日志丢失问题是 Windows 用户的经典痛点。ponytail 的解决方案不是 hack uvicorn，而是重构日志流向：

1. 禁用 uvicorn 的默认日志：在create_app()中传入log_config=None；
2. 统一使用app.core.logger.get_logger()：该函数返回一个structlog.stdlib.BoundLogger实例；
3. CLI 和 Web 共享同一 logger 实例：get_logger()内部使用logging.getLogger("ponytail")，确保所有模块日志写入同一 handler；
4. 日志输出到文件而非 stdout：在app/core/logger.py中配置RotatingFileHandler，按大小轮转，避免 Windows 控制台缓冲区溢出。

最终效果：ponytail hello get和uvicorn main:app的日志全部写入logs/app.log，且时间戳、进程 ID、模块名完全一致，可交叉分析。

最后分享一个小技巧：ponytail 的--verbose参数会自动开启structlog的dev渲染器，输出彩色、可折叠的 JSON 日