普通 Action 协议设计规范

Common Action Protocol Specification

设计背景与目标 / Background & Goals

TFRobotServer平台支持多种类型的Action，普通Action适用于一步到位、无复杂上下文依赖的业务场景。通过@tfs_action注册，结合Pydantic/JsonSchema自动生成参数校验与前端表单。 TFRobotServer supports various types of Actions. Common Actions are suitable for one-step, stateless business scenarios. They are registered via @tfs_action, with parameter validation and frontend forms automatically generated by Pydantic/JsonSchema.

基本约定 / Basic Conventions

普通Action通过@tfs_action注册，category必须为空。
Common Actions are registered via @tfs_action, with category set to None.
每个Action需定义明确的入参Schema和返回Schema，均基于Pydantic/JsonSchema。
Each Action must define explicit parameter and return schemas, both based on Pydantic/JsonSchema.
不涉及x-namespace/x-actions/x-ref/x-default，无需上下文联动。普通Action无需 Options 结构。
No x-namespace/x-actions/x-ref/x-default or context linkage. Common Actions do not require Options structure.
支持扩展字段（如x-ui）辅助前端渲染。
Supports extension fields (e.g., x-ui) for frontend rendering.
普通Action无需定义x-namespace/x-actions/x-ref，简化开发流程。
Common Actions do not need x-namespace/x-actions/x-ref, simplifying development.

Action 元信息扩展 / Action Metadata Extension

支持为每个 Action 指定别名（alias）、分类（category）、资源（resource）、资源操作类型（resource_op_type）、资源标识符（resource_identifier）。
Each Action supports alias, category, resource, resource_op_type, and resource_identifier for fine-grained management.

ActionAlias 结构示例 / ActionAlias Example:

{
  "action": "run_once",
  "alias": "执行一次",
  "category": "pageable",
  "resource": "document",
  "resource_op_type": "get",
  "resource_identifier": "doc_id"
}

典型接口结构 / Typical Interface Structure

1. 普通Action定义 / Common Action Definition

入参Schema：由方法参数自动生成
Parameter Schema: Automatically generated from method parameters
返回Schema：由方法返回类型自动生成
Return Schema: Automatically generated from method return type

@tfs_action(actions={"run_once"}, target_cls=BaseRobotOnlineSetting)
class MySetting(BaseRobotOnlineSetting):
    def run_once(self, param1: str, param2: int) -> dict:
        """普通Action示例 / Example of a common action"""
        ...

入参对应的JsonSchema / Example input JsonSchema:

{
  "type": "object",
  "properties": {
    "param1": {"type": "string"},
    "param2": {"type": "integer"}
  },
  "required": ["param1", "param2"]
}

返回对应的JsonSchema / Example output JsonSchema:

{
  "type": "object"
}

Action 注册与触发 / Action Registration & Trigger

通过 @tfs_action 装饰器注册，所有注册的 Action 会被收集到 tfs_actions 属性。
Actions are registered via @tfs_action and collected in the tfs_actions attribute.
触发 Action 可通过 trigger_tfs_action（同步）或 atrigger_tfs_action（异步）方法，需传入 action_name 及 session/async_session。
Actions are triggered by trigger_tfs_action (sync) or atrigger_tfs_action (async), requiring action_name and session/async_session.
session/async_session 会自动注入到被装饰方法，无需手动传递。
session/async_session is auto-injected into the decorated method.

Action 列表获取 / Action List Retrieval

可通过 get_tfs_actions 方法获取所有注册 Action 的 schema 及元信息，便于前端动态渲染。
Use get_tfs_actions to retrieve all registered Actions' schemas and metadata for frontend rendering.

接口示例 / API Example:

actions = MySetting.get_tfs_actions()
# 返回每个 action 的参数 schema、返回 schema 及元数据
# Returns param schema, return schema, and metadata for each action

方法类型限制 / Method Type Limitation

仅支持普通方法、@classmethod、@staticmethod。不支持 @property。
Only supports normal methods, @classmethod, and @staticmethod. @property is not supported.

Schema 自动生成 / Auto Schema Generation

所有 Action 方法参数和返回类型必须有明确类型注解，以便自动生成 Pydantic/JsonSchema。
All Action method parameters and return types must have explicit type annotations for auto-generation of Pydantic/JsonSchema.

前端渲染与调用 / Frontend Rendering & Invocation

前端可根据Schema自动生成表单，用户填写后直接调用Action。
The frontend can auto-generate forms based on the schema, and users can invoke the action after filling in the form.
返回结果直接展示或用于后续流程。
The result can be displayed directly or used for subsequent processes.

扩展与约定 / Extensions & Conventions

支持x-ui等自定义扩展字段，提升表单体验。
Supports custom fields such as x-ui for better form experience.
普通Action适用于无上下文依赖、单步执行的场景。比如Prompt render等。
Common Actions are suitable for stateless, single-step scenarios (e.g., prompt rendering).
普通Action的简单性和自动Schema生成能力，使其成为快速开发和集成的理想选择。
The simplicity and auto-schema generation make Common Actions ideal for rapid development and integration.
特别注意：普通Action无需x-actions，也无需 Options/x-default/x-namespace 结构，其它协议文档体现x-actions/Options/x-default/x-namespace(新版)用法。
Note: Common Actions do not require x-actions, Options, x-default, or x-namespace structures. For advanced usage, refer to other protocol documents.

其它注意事项 / Additional Notes

若 Action 为异步函数，必须通过 atrigger_tfs_action 触发。
If the Action is asynchronous, it must be triggered via atrigger_tfs_action.