使用 `planoai init` 模板快速引导 Plano 新项目：内置模板详解与实战工作流

使用planoai init模板快速引导 Plano 新项目：内置模板详解与实战工作流

【免费下载链接】planoPlano is an AI-native proxy server and data plane for agentic apps. Smart LLM routing, observability, agent orchestration, and guardrails so you stay focused on your agents core logic.项目地址: https://gitcode.com/GitHub_Trending/ar/plano

planoai init是 Plano 命令行工具内置的配置初始化命令，它通过一组经过验证的内置模板生成结构正确、带注释的config.yaml，帮助你在几秒钟内启动 LLM 路由网关或多 Agent 编排服务，而无需从空白文件开始手工编写配置。读完本文，你将掌握 5 个内置模板的适用场景与配置结构、planoai init的全部命令行选项，以及从创建项目目录到启动并验证服务的完整实战流程。

为什么应该用模板而不是手写config.yaml

Plano 的配置涉及model_providers（模型提供方）、agents（Agent 注册）、listeners（监听器）、filters（过滤链）、model_aliases（模型别名）、state_storage（状态存储）等多个顶层区块。从空白文件起步很容易遗漏必填字段或犯下常见的结构错误——例如忘记给默认模型标记default: true、没有为 Agent 提供路由描述，或漏配访问密钥的环境变量引用。

planoai init正是针对这一痛点设计的：它从内置模板生成结构正确、示例真实、自带注释的config.yaml，每个模板都演示了 Plano 的某项具体能力。按照 CLI 参考文档 的定义，init支持三种初始化方式：交互式向导、内置模板、以及--clean生成空文件。官方推荐在项目启动阶段直接使用模板，而不是手写配置。

可用模板一览

planoai init共内置 5 个模板（定义于 init_cmd.py 的BUILTIN_TEMPLATES），每个模板对应一种典型的 Plano 能力：

模板的元数据（标题与描述）与模板 YAML 文件一一对应，模板文件存放在 cli/planoai/templates/ 目录下，并通过 template_sync_map.yaml 与仓库中的演示配置保持同步（详见后文"模板与演示配置的同步机制"）。

planoai init命令用法详解

列出可用模板

planoai init --list-templates

输出示例（即上图截图内容）：

Available templates sub_agent_orchestration - multi-agent routing across specialized agents coding_agent_routing - routing preferences + model aliases for coding tasks preference_aware_routing - automatic LLM routing based on preferences filter_chain_guardrails - input guards, query rewrite, and context building conversational_state_v1_responses - stateful responses with memory-backed storage

从源码实现看，该选项会遍历_get_templates()返回的模板列表，逐行打印id与description（见 init_cmd.py）。

使用模板初始化

# 用子 Agent 编排模板初始化 planoai init --template sub_agent_orchestration # 初始化编码 Agent 路由配置 planoai init --template coding_agent_routing # 初始化 RAG + 护栏项目 planoai init --template filter_chain_guardrails

--template接受内置模板 ID；若传入未知 ID，命令会报错并提示运行planoai init --list-templates查看可用模板（见 init_cmd.py）。

交互式向导（默认模式）

不带任何参数直接运行planoai init，会进入交互式向导（依赖questionary，见 init_cmd.py）：

1. 第一步：方向键选择模板（或选择 "Create a clean config.yaml (empty)"）；
2. 第二步：确认输出路径（默认config.yaml）；
3. 若文件已存在，会询问是否覆盖。

向导需要 TTY 环境；在非交互终端（如 CI 管道）中运行不带参数的命令会报错，提示改用--template/--clean/--list-templates这些非交互入口（见 init_cmd.py）。

完整选项参考

两条约束值得注意：--clean与--template不能同时使用（源码会抛出UsageError，见 init_cmd.py）；在不加--force的情况下，若目标文件已存在，命令会拒绝覆盖并提示Refusing to overwrite existing file: ... (use --force)（见 init_cmd.py）。这些行为均有对应的单元测试覆盖，见 test_init.py 中的test_init_refuses_overwrite_without_force与test_init_force_overwrites。

无论走哪条路径，命令完成后都会用 Rich Panel 打印生成配置的前 28 行预览（超出部分截断标注... (truncated)），方便即时核对，见 _print_config_preview。

5 个内置模板的配置结构深度解析

所有模板都以version: v0.3.0开头，并普遍包含tracing.random_sampling: 100的全量采样设置。下面逐一拆解每个模板的核心区块。

1.sub_agent_orchestration：多 Agent 路由

对应模板文件 sub_agent_orchestration.yaml，演示了 Plano 的核心 Agent 编排能力——由一个监听器将请求路由给多个专业子 Agent：

• agents：注册两个下游 Agent（weather_agent、flight_agent），通过url指向各自的 HTTP 服务地址；
• model_providers：配置openai/gpt-4o（标记default: true）与openai/gpt-4o-mini（注释说明它用于抽取位置等实体的更小、更快、更便宜的模型），access_key全部使用$OPENAI_API_KEY环境变量替换；
• listeners：type: agent、name: travel_booking_service、port: 8001，router: plano_orchestrator_v1指定使用编排路由；每个 Agent 下附带一段详细的description，向路由器说明该 Agent 的能力边界（如天气 Agent 只回答天气部分问题），供路由决策使用。

该模板与演示项目 demos/agent_orchestration/multi_agent_crewai_langchain/config.yaml 保持同步，后者展示了天气（LangChain）与航班（CrewAI）双 Agent 的完整落地形态。

2.coding_agent_routing：编码工作流路由

对应 coding_agent_routing.yaml，面向 Claude Code 等编码助手：

• 路由偏好：openai/gpt-5-2025-08-07声明routing_preferences为 "code generation"（按提示生成新代码）；openai/gpt-4.1-2025-04-14声明为 "code understanding"（理解并解释现有代码）；
• 默认模型：anthropic/claude-sonnet-4-5标记default: true；
• 本地模型：示范ollama/llama3.1并通过base_url: http://localhost:11434接入本地 Ollama 服务；
• 模型别名：定义arch.claude.code.small.fast指向claude-haiku-4-5，便于在应用侧使用友好的短别名；
• 监听器：type: model、port: 12000——注意这里是纯模型监听器，不挂 Agent。

该模板与演示 demos/llm_routing/claude_code_router/config.yaml 同步。

3.preference_aware_routing：偏好感知路由

对应 preference_aware_routing.yaml，是大多数 LLM 网关场景的默认起点：

• openai/gpt-4o-mini作为default: true兜底模型；
• openai/gpt-4o声明偏好 "code understanding"，anthropic/claude-sonnet-4-6声明偏好 "code generation"；
• 路由器根据请求任务的语义（代码理解 vs 代码生成）自动挑选最合适的模型，从而实现多模型成本优化。

该模板与演示 demos/llm_routing/preference_based_routing/config.yaml 同步。

4.filter_chain_guardrails：过滤链护栏

对应 filter_chain_guardrails.yaml，演示了 Plano 的过滤链（filter chain）能力——在请求到达 LLM 之前依次执行防护/改写/构建：

• filters：定义三个 HTTP 过滤服务，每个都带注释说明默认协议选项（type: mcp为默认、transport: streamable-http为默认、tool默认与 filter id 同名）：
  • input_guards（端口 10500）：输入防护；
  • query_rewriter（端口 10501）：查询改写；
  • context_builder（端口 10502）：上下文构建；
• 模型与别名：gpt-4o-mini（默认）与gpt-4o，并演示fast-llm/smart-llm两个别名映射；
• Agent 挂载过滤链：agent_1监听器挂载rag_agent，其filter_chain依次列出input_guards → query_rewriter → context_builder，展示过滤链在 Agent 请求路径上的编排顺序。

该模板与演示 demos/filter_chains/http_filter/config.yaml 同步（同一目录下还有 MCP 过滤链的变体 mcp_filter）。

5.conversational_state_v1_responses：状态化对话

对应 conversational_state_v1_responses.yaml，演示带记忆的多轮对话：

• agents：注册assistant指向http://localhost:10510；
• listeners：conversation_service挂载assistant，描述文本强调"跨多轮对话维持上下文、记住先前语境"；
• state_storage：新增状态存储区块，注释标明type: memory | postgres两种后端可选，模板默认type: memory（进程内内存存储），需要持久化时可切换为 PostgreSQL。对应的 Rust 侧实现可参考 state/postgresql.rs 与 state/memory.rs。

典型项目搭建工作流

以下是官方推荐的标准流程，从空目录一路走到可调用的服务端点：

# 1. 创建项目目录 mkdir my-plano-agent && cd my-plano-agent # 2. 用最贴近需求的模板引导 planoai init --template preference_aware_routing # 3. 编辑 config.yaml，填入你的模型、Agent 与 API Key # （配置中的密钥已使用 $VAR 替换语法——只需设置对应的环境变量） # 4. 为本地开发创建 .env 文件 cat > .env << EOF OPENAI_API_KEY=sk-proj-... ANTHROPIC_API_KEY=sk-ant-... EOF echo ".env" >> .gitignore # 5. 启动 Plano planoai up # 6. 验证配置是否生效 curl http://localhost:12000/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{"model": "gpt-4o", "messages": [{"role": "user", "content": "Hello"}]}'

几个关键点：

• 环境变量注入：planoai up启动时会解析配置中的$VAR引用。若未找到.env文件，则从进程环境读取；.env文件需与配置放在同一目录（见 main.py）。缺失的密钥会以红色清单列出，并提示export VAR="your-api-key"或创建.env文件（见 _print_missing_keys）。
• 零配置兜底：如果启动时连config.yaml都不存在，planoai up会自动合成一份默认直通配置并写入~/.plano/default_config.yaml（见 main.py），但这是兜底手段，正式项目仍应使用planoai init生成的显式配置。
• 验证响应：默认model监听器端口为 12000（coding_agent_routing、preference_aware_routing模板均如此），curl 请求返回即代表网关链路可用。

源码实现与测试验证

模板的内嵌与解析机制

模板 YAML 并非在运行时从文件系统读取，而是通过 Python 的importlib.resources在安装包内部加载（见 _load_template_yaml），这意味着pip install planoai后、包括 PyPI 离线安装环境，模板依然可用（Template数据类注释明确写道 "works in PyPI installs"）。模板对象是不可变的frozen dataclass，id字段即--template使用的稳定标识符。

模板与演示配置的同步机制

仓库通过 template_sync.py 保证CLI 模板是演示config.yaml的单一事实来源：它读取 template_sync_map.yaml 中的映射关系（如sub_agent_orchestration对应demos/agent_orchestration/multi_agent_crewai_langchain/config.yaml），校验模板文件与演示文件均存在后，将模板内容写入演示配置。开发者可运行uv run python -m planoai.template_sync手动执行该同步（见 cli/README.md）。这意味着本文解析的模板结构与你在此仓库中看到的任何演示配置保持一致。

单元测试覆盖

test_init.py 覆盖了init的四类核心行为：

• test_init_clean_writes_empty_config：--clean写出仅含换行符的空文件；
• test_init_template_builtin_writes_config：--template coding_agent_routing成功写出包含model_providers:的配置；
• test_init_refuses_overwrite_without_force：无--force时拒绝覆盖已有文件；
• test_init_force_overwrites：加--force后允许覆盖。

这些测试直接验证了命令的非交互行为，也为你写脚本化初始化流程（如 CI 中自动生成配置）提供了行为保证。

选型建议与组合策略

官方建议可以概括为两条主线：

• 大多数 LLM 网关场景从preference_aware_routing起步——它只涉及模型提供方与一个 model 监听器，最接近"把 Plano 当作智能模型网关"的用法，且天然支持多模型成本优化；
• 多 Agent 应用从sub_agent_orchestration起步——它展示了如何注册多个专业子 Agent 并让路由器根据描述自动分派请求。

两条主线各自独立理解之后，可以组合：例如在sub_agent_orchestration的 Agent 请求路径上叠加filter_chain_guardrails的过滤链（参考 filter_chain_guardrails.yaml 中filter_chain的写法），或为 Agent 场景配置state_storage获得多轮记忆。模板的价值在于给你一个已验证、可运行的起点，后续的模型、Agent 与密钥编辑都在这个安全骨架上进行——这正是从空白config.yaml起步最容易被省略的关键一步。

【免费下载链接】planoPlano is an AI-native proxy server and data plane for agentic apps. Smart LLM routing, observability, agent orchestration, and guardrails so you stay focused on your agents core logic.项目地址: https://gitcode.com/GitHub_Trending/ar/plano