葛店小学张洪雨很多人第一次拿到这类开发平台的文档，看到"03.02.02.01 Add a Simple Action"这种编号，第一反应是：这不就是"加一个按钮、写一个回调"嘛？等真上手才发现，Action在整个对话式AI平台里承担的角色，比你想象的要重得多——它不只是"执行一段代码"，而是意图识别之后、用户感知之前的那一整段逻辑的承载者。
我最早接触这个功能，是想给助手加一个查询订单状态的快捷操作。当时走了不少弯路，对Action的定位、生命周期、参数传递方式都理解得很浅，导致写出来的Action要么拿不到参数，要么响应格式不对，调试了大半天。这篇东西就是把我从零到一跑通"添加一个简单的操作"的完整过程、原理和踩坑记录整理出来，给正要碰这块的开发者做一个能直接照着做的参考。
1. 先搞清楚Action到底是什么：它不是回调，是一段完整的意图处理链
在动手写代码之前，我觉得最值得花时间的地方，是先把Action在整体架构里的位置弄清楚。很多文档只告诉你"Action是一个可执行的操作"，但这个解释对实际开发几乎没有帮助。
1.1 Action在"用户请求→平台响应"链路中的真实位置
我把一次完整的人机交互在平台内部的流转拆开看，大概是这样一个链路：
- 用户说了一句话（比如"帮我查一下订单状态"）；
- 平台的自然语言理解模块(NLU)对这句话做意图识别和槽位提取，得到意图名称（比如query_order_status）和参数（比如order_id=10086）；
- 平台根据意图配置，查找到对应的Action；
- Action被触发，执行你写的业务逻辑，可能去调数据库、调第三方接口，或者做本地计算；
- Action把结果封装成平台规定的响应结构，返回给对话管理模块；
- 对话管理模块根据响应内容，决定是直接回复用户、还是追问缺失参数、还是进入下一个流程。
这里最关键的一点是：Action的输入不是用户的原话，而是NLU处理之后的结构化数据。也就是说，如果你的Action拿不到预期参数，问题大概率出在意图配置、槽位定义上，而不是你的Action代码里。这个认知能帮你省掉大量无意义的调试时间。
1.2 "Simple Action"在本平台里具体指什么
不同平台对Action的叫法略有不同，有的叫"Skill"、有的叫"Function"、有的叫"Plugin"，但核心概念是通用的。在"03.02.02.01"这个章节所对应的平台里，Simple Action指代的是：开发者通过声明式配置和少量代码，将一段自定义逻辑暴露为对话系统可调用的操作。
它和"复合操作"（复合Action）最大的区别在于：Simple Action不关心多轮对话状态管理，不涉及分支跳转，只是完成一个"输入→处理→输出"的闭环。你可以把它理解为对话系统里的一个"函数"，而复合Action是"函数编排"。
打个比方：Simple Action就像餐厅里的一道固定套餐——顾客点了，后厨按标准流程做完端上来，完事。复合Action则像一个自助餐流水线，顾客可以自己选菜、选烹饪方式，后厨根据你的选择动态调整流程。
1.3 搞清楚Action的类型，别一上来就写代码
我见过不少同事（也包括最早的我）犯同一个错误：拿到需求就开始写代码，写完发现平台根本不认这个Action——因为Action需要在平台侧先注册、声明参数和触发条件，代码只是其中一部分。
在平台的常规设计里，一个Action通常由三部分组成：
- 清单文件（manifest）：声明Action的名称、描述、输入参数、输出参数、权限要求等元信息。这是平台的"登记册"，没有登记，平台不会把你的代码当成一个合法Action；
- 业务逻辑代码：真正干活的部分，接收参数、执行业务、返回结果；
- 资源文件（可选）：如对话模板、错误提示文案等。
这三者缺一不可。很多新手在"添加Action"这一步卡住，就是因为只写了代码，没有做清单声明。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 动手前要备好的环境和工程结构：这些细节决定了你后面少踩多少坑
环境准备这块，文档里通常只有一句"请确保已安装XX SDK"，但实际操作中，有几个细节是文档不会告诉你的。我把自己跑通的环境和工程结构列在下面，照着做基本不会出问题。
2.1 开发环境版本组合（实测兼容的组合）
先说明：以下版本组合是我当时实测可用的，不一定是最新，但理论上向后兼容。如果你用的是更新的版本，只要API没有breaking change，问题不大。
| 组件 | 版本 | 说明 |
|---|---|---|
| Python | 3.9+ | 官方SDK对3.10、3.11的支持也正常，别用3.6以下的就行 |
| 平台CLI | 2.x | 用于创建工程、注册Action、本地调试 |
| SDK | 对应CLI同版本 | 不建议混用大版本 |
| 本地的模拟器/调试器 | 随CLI安装 | 用于本地模拟对话，验证Action逻辑 |
有一个小点：一定要在虚拟环境里装SDK，不要图省事装到全局。因为平台SDK的依赖链不算短（通常会有grpc、protobuf这一类的依赖），装在全局很容易和你的其他项目产生版本冲突。我自己的习惯是启动每个新项目前先python -m venv .venv，再激活虚拟环境操作。
2.2 建议的工程目录结构
一个规范化的Action工程目录，通常长这样：
code复制my_actions_project/
├── manifest.json # Action的清单声明文件，核心
├── actions/
│ ├── __init__.py
│ ├── query_order_status.py # 你的Action逻辑代码
│ └── common/
│ ├── __init__.py
│ └── api_client.py # 封装第三方API调用
├── resources/
│ ├── prompts/
│ │ └── query_order_status.md # 对话模板，可选
│ └── errors/
│ └── zh-CN.json # 错误提示文案
├── tests/
│ ├── test_actions.py
│ └── fixtures/
│ └── sample_payloads.json
└── requirements.txt
这个结构不是平台强制的，但建议按这个习惯来。原因有三：
一是