SuperAPI AI 工具集

flink-agents-dev

编程与开发

查看项目

更新于 10-30 21:11

技能介绍

用途

flink-agents-dev 是随 Apache Flink Agents 项目发布的开发技能,用于在构建、脚手架生成、修改、调试、转换和验证 Flink Agents 应用时提供规范化的开发流程。它面向 Flink Agents 的 YAML 应用、Workflow Agent 以及直接使用 Python/Java API 的应用。

核心模型

技能把每个应用视为四个相互连接的部分:

  • 资源(Resources):具名的模型、提示词(prompts)、工具(tools)、技能(skills)、向量存储、MCP 服务器与连接。
  • 动作(Actions):使用资源并发出事件的事件处理器。
  • 编排(Orchestration):触发条件与发出事件构成的图。
  • 实现(Implementation):Python/Java 函数、类型与运行器。

技能说明,Skills、向量存储、MCP、RAG 和记忆都是上述部分的组合。在与已验证桥接相关的范围内,聊天模型连接、嵌入模型连接和向量存储支持 Python/Java 双向桥接。

依据来源的优先级

技能要求从安装目录工作,不假定用户克隆了 Flink Agents 仓库。判断版本与约定时,信息来源按以下顺序使用:

  1. 目标应用代码、依赖元数据、已安装包/JAR 的 API 与测试。
  2. 与版本匹配的 Flink Agents schema、文档、示例或源码。
  3. 技能自带的 YAML 契约清单、匹配 schema 与参考资料,作为离线基线。

契约按目标 Flink Agents 版本选择,而不是按发布该技能的版本。清单把已发布版本映射到完整 schema,并标注不支持 YAML 的版本;无版本号的 main schema 只描述发布该技能的仓库修订,不得用来验证已发布版本的应用,除非清单把所选版本映射到它。技能明确禁止凭记忆发明 API、版本或命令。

预检流程

在加载平台适配器、发出决策问题或生成文件之前,技能要求:

  • 确认目标是 Flink Agents 应用,或正在被转换为 Flink Agents 应用;普通 Flink 作业不属于该工作流。
  • 检查完整请求、现有项目、依赖元数据、源码、配置与测试,凡是已有证据能回答的框架决策都要先解决。
  • 记录每个必需框架决策为已确认或未解决,包括 Flink Agents 版本、Flink 版本、API、YAML 应用语言、各描述符支撑的资源实现,以及需要 Python 时的 Python 环境。
  • 对请求或项目中已命名的具体外部描述符 Provider 执行 Provider 契约分类。
  • 只把未解决项构建为有顺序的门槛列表;列表为空时跳过宿主检测与交互适配器,直接进入契约解析与实现。
  • 对 YAML,通过 yaml-contracts.yaml 选择精确的目标版本 schema;若请求的 YAML 版本没有匹配 schema,应停止 YAML 生成并要求提供该版本的 schema 或源码,不得用 main schema 替代。

每次回答后都要更新决策记录,以避免重复提问。

Provider 契约分类

这是一个提前退出的检查环节,应在读取 references/ 下任何文件之前执行。技能要求只检查能确立该 Provider 契约的证据:用户明确提供的 JAR、包、源码、测试或文档;目标项目的依赖元数据及元数据指定的已安装产物;已知位置上与版本匹配的权威 Provider 源码或文档。检查命令须限定在目标应用的依赖文件、配置、源码根与明确命名的产物内,排除技能安装目录、项目本地 .agents/、宿主元数据(如 .codex/、.claude/)、工具缓存及无关的主目录或包缓存。

分类需要确立实现类或别名、依赖坐标或包、构造函数/工厂契约,以及每个必填描述符参数。任一要素无法验证时,保留可用的依赖、源码与配置文件,立即停止相关集成,不生成描述符、适配器、包装、占位依赖或测试,并报告已检查的确切来源、缺失的契约要素,以及继续所需的最小 JAR、包、源码、测试或文档。

定义策略

技能给出的建议包括:

  • 新建 Workflow Agent 或重连事件图:提供 YAML 加 Python/Java 实现文件。
  • 现有 YAML 应用:保留并扩展 YAML。
  • 现有程序化 Agent:除非要求转换,保留当前 API。
  • ReActAgent、YAML 不支持的表面或明确的仅代码请求:使用直接 Python 或 Java API。

建议只是解释取舍,不等于替用户选择 API。YAML 不声明 agent 类型,也不选择业务实现语言;新建 YAML 应用前需询问用户选择 Python 还是 Java。

脚手架边界

技能要求完成框架层面的接线,但不发明业务行为。在实现每个自定义 Action、Tool、领域客户端、数据转换、Prompt 或运行时 Skill 之前,先根据明确的用户需求、现有代码和测试判定输入、输出、转换、副作用与错误处理是否已提供。未确立的部分应视为未解决,只能生成可导入或可编译的签名骨架,加上聚焦的 TODO 和明确的 NotImplementedError 或 UnsupportedOperationException,并保留用户提供的名称、参数、类型与描述。未解决的骨架不得发出业务事件、转换负载、组合提示词或聊天消息、调用后端、返回业务数据或提供回退行为。

交互纪律

该部分是交互能力检测、回退选择、重试行为与宿主模式处理的唯一权威。技能要求把未决决策当作有顺序的门槛,逐项提问、等待回答、更新记录后再继续。只有当存在至少一个未解决的封闭式门槛时,才根据明确的系统与工具上下文识别当前宿主:Codex 使用 request_user_input(适配器 codex.md),Claude Code 使用 AskUserQuestion(claude-code.md),Gemini CLI 使用 ask_user 通信工具(gemini-cli.md),Qoder 与未知/不支持的宿主则使用明确暴露的结构化单选工具(qoder.md、generic.md)。若候选工具缺失、返回不可用错误或无法完整表达有效选项,立即读取 generic.md 并使用其编号回退方案。

提问顺序为:先问 Flink Agents 版本并等待,再只提供兼容的 Flink 版本并等待;然后从已确认版本支持的 API 中选择,只有精确契约可用时才提供 YAML;仅在选择 YAML 后询问自定义 Action、函数 Tool 和 Flink 入口点使用 Python 还是 Java,此处不设推荐项。随后清点设计所需资源,逐项解析真实描述符支撑的框架集成,每次确认一个;确定实现后立即执行 Provider 契约分类,通过后再为每个必填配置键生成 TODO_REQUIRED_<FIELD>。技能明确不询问模型标识、端点、凭据值/机制、Provider 选项、Skill 源路径/URL/包或其他资源参数;自定义 Action、函数 Tool、领域客户端、Prompt 内容、运行时 Skill 指令、业务输入 schema 与后端平台也不作为集成门槛,直接脚手架生成而不进行业务访谈。当确认的设计首次需要 Python 运行时,除非现有项目已明确声明环境,否则需在创建环境或安装依赖前暂停,检查兼容的本地 Python 可执行文件/环境,并询问是复用其中一个还是创建项目本地 .venv。

适用场景与限制

适用场景包括:新建 Workflow Agent 或重连事件图、扩展现有 YAML 应用、维护现有程序化 Agent、在 YAML 表面不满足需求时使用直接 Python/Java API,以及调试和验证 Flink Agents 应用。限制方面:普通 Flink 作业不属于该工作流;技能本身不提供业务逻辑,未说明的业务契约只能生成占位骨架;无法验证的 Provider 集成会被阻塞,需用户补充最小依赖或文档;不支持的 YAML 版本必须由用户提供对应 schema 或源码。