pull-edit-push：用 ADK 开发 PolyAI 智能体的完整循环

完整工作流一览

ADK 的开发循环可以浓缩为六个命令：

poly init    # 把本地目录和 Studio 项目关联
poly pull    # 把远端配置拉成本地 YAML / Python 文件
poly branch switch <name>  # 创建或切换分支
# 在 IDE 里编辑文件 ← 这里你写代码
poly validate  # 本地校验改动
poly push     # diff + 推送到远端

poly init：关联本地目录和 Studio 项目

在要存放项目的目录里运行：

poly init

交互式选择区域、账户和项目，或者用参数一次性指定：

poly init --region us-east --account my-company --project customer-support

init 完成后，本地目录结构已经搭建好，等待 pull。

poly pull：拉取项目配置

poly pull

这会把 Agent Studio 上当前选中的项目的全部配置拉下来，按资源类型组织成 YAML 和 Python 文件。pull 完成后你可以用任意 IDE 打开这个目录。

poly branch switch：在分支上工作

poly branch switch my-new-feature

这会创建一个新的本地分支（和 Studio 里的 Branch 概念一致）。分支上的改动不会影响 Main，也不会影响 Live。你可以随时切换分支：

poly branch switch main       # 切回主分支
poly branch list              # 查看所有分支
poly branch delete my-old-branch  # 删除旧分支

编辑阶段

直接用 IDE 编辑 YAML 和 Python 文件——VS Code、Cursor、任何支持 YAML 高亮的编辑器都可以。编辑内容包括：

修改 Flow 的 Step Prompt（flows/<flow-name>/flow_step_*.yaml）
修改 FAQ 话题的回答内容（topics/<topic-name>.yaml）
写 / 改 Python 转场函数（functions/<function-name>.py）
修改 Agent 角色和规则（agent_settings/role.yaml）
添加 / 修改实体类型（config/entities/<entity-name>.yaml）

poly validate：本地校验

poly validate

在 push 之前跑一次 validate——它会检查：

YAML 语法是否正确
资源交叉引用是否有效（比如 Flow 引用的实体是否存在）
Python 函数是否能导入、是否有明显错误
项目结构是否完整

校验失败的错误信息会指向具体文件和行号，在本地修完再 push 比 push 到远端再报错快得多。

poly push：diff + 推送

poly push

push 的过程：

对比本地文件和远端 Studio 配置的差异
显示 diff（新增了什么、修改了什么、删除了什么）
提示确认（加 --yes 参数跳过交互）
推送更新到远端 Branch

push 完成后，Studio 界面实时显示更新——你可以在 Studio 里继续 review，也可以继续用 ADK 改下一批。

poly chat：本地测试

poly chat

ADK 内置了一个命令行聊天界面，可以在本地直接和智能体对话测试。这对于不接电话线路、只想快速验证行为的场景很方便。poly chat 会把你的输入发送到对应 Branch 的 Sandbox 环境，拿到智能体回复并在终端显示。

和 Git 的关系

ADK 的分支管理和你本地的 Git 仓库可以并存。推荐做法：

poly pull 下来后，在本地 git init
每次 push 前 git commit 一次本地改动
用 Git 做详细的提交历史和 Code Review
poly push 负责把改动同步到 Studio

这样你同时拥有了完整的 Git 版本管理和PolyAI 远端配置同步两个能力。