Skill: yaozheng-fang/veadk-skills (version 1.0.0)

--- name: veadk-skills description: 根据用户的功能需求，完成与 VeADK 相关的功能。 license: Complete terms in LICENSE.txt --- # VeADK Agent 生成 本技能可以根据用户的需求，生成符合要求的 VeADK Agent 代码，或完成 VeADK 相关功能。 ## 触发条件 1. 用户简要描述了其功能需求，并希望构建一个 Agent 来完成； 2. 用户希望可以将已有的 Langchain/Langgraph 代码转化为 VeADK Agent 代码 3. 用户希望可以将已有的 Dify 工作流转化为 VeADK Agent 代码 ## 具体步骤 下面是本技能不同的组件能力。 ### 直接根据需求生成 Agent 请你遵循以下步骤： 1. 分析用户需求，生成对应的 Agent 系统结构，参考 `references/generator/analyze.md` 2. 提示词优化，参考 `references/generator/refine_prompt.md` 3. 生成 Agent 代码，参考 `references/generator/coding.md` ### Langchain 代码转换为 VeADK Agent 请你遵循以下步骤： 1. 分析原有 Langchain 或 Langgraph 代码 2. 将原有代码改为 VeADK Agent，对应关系详见 `references/converter/langchain_rules.md` 3. 参照 `references/common/` 目录内的文档来生成 VeADK 代码 ### Dify 工作流转换为 VeADK Agent 请你遵循以下步骤： 1. 分析原有 Dify 工作流 DSL（一般为一个 Yaml 格式文件） 2. 将原有代码改为 VeADK Agent，对应关系详见 `references/converter/dify_rules.md` 3. 参照 `references/common/` 目录内的文档来生成 VeADK 代码 ## 后续工作 在完成 Agent 代码编写后，调用脚本保存代码产物： - `agent_name/__init__.py`: 固定内容为 `from . import agent # noqa` - `agent_name/agent.py`：包含所有智能体的代码 其中，`agent_name` 是你认为合适的 Agent 的名称。 脚本调用方法为： ```bash python save_file.py --path ... --content ... ```

path: LICENSE.txt
content: 
                                 Apache License
                           Version 2.0, January 2004
                        http://www.apache.org/licenses/

   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION

   1. Definitions.

      "License" shall mean the terms and conditions for use, reproduction,
      and distribution as defined by Sections 1 through 9 of this document.

      "Licensor" shall mean the copyright owner or entity authorized by
      the copyright owner that is granting the License.

      "Legal Entity" shall mean the union of the acting entity and all
      other entities that control, are controlled by, or are under common
      control with that entity. For the purposes of this definition,
      "control" means (i) the power, direct or indirect, to cause the
      direction or management of such entity, whether by contract or
      otherwise, or (ii) ownership of fifty percent (50%) or more of the
      outstanding shares, or (iii) beneficial ownership of such entity.

      "You" (or "Your") shall mean an individual or Legal Entity
      exercising permissions granted by this License.

      "Source" form shall mean the preferred form for making modifications,
      including but not limited to software source code, documentation
      source, and configuration files.

      "Object" form shall mean any form resulting from mechanical
      transformation or translation of a Source form, including but
      not limited to compiled object code, generated documentation,
      and conversions to other media types.

      "Work" shall mean the work of authorship, whether in Source or
      Object form, made available under the License, as indicated by a
      copyright notice that is included in or attached to the work
      (an example is provided in the Appendix below).

      "Derivative Works" shall mean any work, whether in Source or Object
      form, that is based on (or derived from) the Work and for which the
      editorial revisions, annotations, elaborations, or other modifications
      represent, as a whole, an original work of authorship. For the purposes
      of this License, Derivative Works shall not include works that remain
      separable from, or merely link (or bind by name) to the interfaces of,
      the Work and Derivative Works thereof.

      "Contribution" shall mean any work of authorship, including
      the original version of the Work and any modifications or additions
      to that Work or Derivative Works thereof, that is intentionally
      submitted to Licensor for inclusion in the Work by the copyright owner
      or by an individual or Legal Entity authorized to submit on behalf of
      the copyright owner. For the purposes of this definition, "submitted"
      means any form of electronic, verbal, or written communication sent
      to the Licensor or its representatives, including but not limited to
      communication on electronic mailing lists, source code control systems,
      and issue tracking systems that are managed by, or on behalf of, the
      Licensor for the purpose of discussing and improving the Work, but
      excluding communication that is conspicuously marked or otherwise
      designated in writing by the copyright owner as "Not a Contribution."

      "Contributor" shall mean Licensor and any individual or Legal Entity
      on behalf of whom a Contribution has been received by Licensor and
      subsequently incorporated within the Work.

   2. Grant of Copyright License. Subject to the terms and conditions of
      this License, each Contributor hereby grants to You a perpetual,
      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
      copyright license to reproduce, prepare Derivative Works of,
      publicly display, publicly perform, sublicense, and distribute the
      Work and such Derivative Works in Source or Object form.

   3. Grant of Patent License. Subject to the terms and conditions of
      this License, each Contributor hereby grants to You a perpetual,
      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
      (except as stated in this section) patent license to make, have made,
      use, offer to sell, sell, import, and otherwise transfer the Work,
      where such license applies only to those patent claims licensable
      by such Contributor that are necessarily infringed by their
      Contribution(s) alone or by combination of their Contribution(s)
      with the Work to which such Contribution(s) was submitted. If You
      institute patent litigation against any entity (including a
      cross-claim or counterclaim in a lawsuit) alleging that the Work
      or a Contribution incorporated within the Work constitutes direct
      or contributory patent infringement, then any patent licenses
      granted to You under this License for that Work shall terminate
      as of the date such litigation is filed.

   4. Redistribution. You may reproduce and distribute copies of the
      Work or Derivative Works thereof in any medium, with or without
      modifications, and in Source or Object form, provided that You
      meet the following conditions:

      (a) You must give any other recipients of the Work or
          Derivative Works a copy of this License; and

      (b) You must cause any modified files to carry prominent notices
          stating that You changed the files; and

      (c) You must retain, in the Source form of any Derivative Works
          that You distribute, all copyright, patent, trademark, and
          attribution notices from the Source form of the Work,
          excluding those notices that do not pertain to any part of
          the Derivative Works; and

      (d) If the Work includes a "NOTICE" text file as part of its
          distribution, then any Derivative Works that You distribute must
          include a readable copy of the attribution notices contained
          within such NOTICE file, excluding those notices that do not
          pertain to any part of the Derivative Works, in at least one
          of the following places: within a NOTICE text file distributed
          as part of the Derivative Works; within the Source form or
          documentation, if provided along with the Derivative Works; or,
          within a display generated by the Derivative Works, if and
          wherever such third-party notices normally appear. The contents
          of the NOTICE file are for informational purposes only and
          do not modify the License. You may add Your own attribution
          notices within Derivative Works that You distribute, alongside
          or as an addendum to the NOTICE text from the Work, provided
          that such additional attribution notices cannot be construed
          as modifying the License.

      You may add Your own copyright statement to Your modifications and
      may provide additional or different license terms and conditions
      for use, reproduction, or distribution of Your modifications, or
      for any such Derivative Works as a whole, provided Your use,
      reproduction, and distribution of the Work otherwise complies with
      the conditions stated in this License.

   5. Submission of Contributions. Unless You explicitly state otherwise,
      any Contribution intentionally submitted for inclusion in the Work
      by You to the Licensor shall be under the terms and conditions of
      this License, without any additional terms or conditions.
      Notwithstanding the above, nothing herein shall supersede or modify
      the terms of any separate license agreement you may have executed
      with Licensor regarding such Contributions.

   6. Trademarks. This License does not grant permission to use the trade
      names, trademarks, service marks, or product names of the Licensor,
      except as required for reasonable and customary use in describing the
      origin of the Work and reproducing the content of the NOTICE file.

   7. Disclaimer of Warranty. Unless required by applicable law or
      agreed to in writing, Licensor provides the Work (and each
      Contributor provides its Contributions) on an "AS IS" BASIS,
      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
      implied, including, without limitation, any warranties or conditions
      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
      PARTICULAR PURPOSE. You are solely responsible for determining the
      appropriateness of using or redistributing the Work and assume any
      risks associated with Your exercise of permissions under this License.

   8. Limitation of Liability. In no event and under no legal theory,
      whether in tort (including negligence), contract, or otherwise,
      unless required by applicable law (such as deliberate and grossly
      negligent acts) or agreed to in writing, shall any Contributor be
      liable to You for damages, including any direct, indirect, special,
      incidental, or consequential damages of any character arising as a
      result of this License or out of the use or inability to use the
      Work (including but not limited to damages for loss of goodwill,
      work stoppage, computer failure or malfunction, or any and all
      other commercial damages or losses), even if such Contributor
      has been advised of the possibility of such damages.

   9. Accepting Warranty or Additional Liability. While redistributing
      the Work or Derivative Works thereof, You may choose to offer,
      and charge a fee for, acceptance of support, warranty, indemnity,
      or other liability obligations and/or rights consistent with this
      License. However, in accepting such obligations, You may act only
      on Your own behalf and on Your sole responsibility, not on behalf
      of any other Contributor, and only if You agree to indemnify,
      defend, and hold each Contributor harmless for any liability
      incurred by, or claims asserted against, such Contributor by reason
      of your accepting any such warranty or additional liability.

   END OF TERMS AND CONDITIONS

   APPENDIX: How to apply the Apache License to your work.

      To apply the Apache License to your work, attach the following
      boilerplate notice, with the fields enclosed by brackets "[]"
      replaced with your own identifying information. (Don't include
      the brackets!)  The text should be enclosed in the appropriate
      comment syntax for the file format. We also recommend that a
      file or class name and description of purpose be included on the
      same "printed page" as the copyright notice for easier
      identification within third-party archives.

   Copyright [yyyy] [name of copyright owner]

   Licensed under the Apache License, Version 2.0 (the "License");
   you may not use this file except in compliance with the License.
   You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.

path: scripts/save_file.py
content: # Copyright (c) 2025 Beijing Volcano Engine Technology Co., Ltd. and/or its affiliates.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

import argparse
import os


def save_file(file_path: str, content: str) -> str:
    """
    保存文件到指定路径

    参数:
    - file_path (str): 文件保存的路径。
    - content (str): 文件内容。

    返回:
    - str: 保存状态，"successfully saved" 表示成功保存。
    """

    # create dir if not exist
    os.makedirs(os.path.dirname(file_path), exist_ok=True)

    with open(file_path, "w", encoding="utf-8") as f:
        f.write(content)

    return "successfully saved"


def main():
    parser = argparse.ArgumentParser(description="Save content to a file")

    parser.add_argument("--path", type=str, required=True, help="Path to save the file")

    parser.add_argument(
        "--content",
        type=str,
        required=True,
        help="Content to write into the file",
    )

    args = parser.parse_args()

    result = save_file(args.path, args.content)
    print(result)


if __name__ == "__main__":
    main()


path: references/converter/langchain_rules.md
content: # Langchain 与 VeADK 对应规则

## Agent

Langchain 写法：

```python
agent = create_agent(model=llm)
```

VeADK 写法：

```python
agent = Agent(
    name="...",
    description="...",
    instruction="...", # 系统提示词
    model_name="..." # 模型名称
)
```

## 工具

Langchain 写法：

```python
agent = create_agent(
    model=llm,
    context_schema=Context,
    tools=[load_knowledgebase], # 工具挂载
)
```

VeADK 写法：

```python
agent = Agent(
    name="...",
    description="...",
    instruction="...", # 系统提示词
    model_name="...", # 模型名称
    tools=[load_knowledgebase], # 工具挂载
)
```


path: references/converter/dify_rules.md
content: # Dify 与 VeADK 对应规则

你可以通过下面的介绍，来了解 Dify 与 VeADK 对应规则。具体的 VeADK 定义方法可以参照 `references/common/` 目录中的内容。

## Dify 节点类型

- LLM 节点：请参照 VeADK Agent
- 知识检索节点：请参照 `references/common/knowledgebase.md` 中的知识库定义和使用方法
- 直接回复节点：请使用 Python 语言实现
- Agent：请参照 VeADK Agent

逻辑分支节点：

- 条件分支、迭代、并行：请使用 Python 语言实现

其它节点：

- 代码执行：定义一个 Agent ，参考 `references/common/tools.md` 中的代码沙箱执行工具定义和使用方法

当遇到无法直接对应到 VeADK 节点类型的情况时，你可以考虑使用自定义的 Python 代码及 VeADK 逻辑来实现。


path: references/generator/refine_prompt.md
content: # 提示词优化

请你根据上一步骤分析出的 Agent 架构，优化每个 Agent 的提示词，确保每个 Agent 的功能描述清晰、准确。

请根据 **用户需求** 与 **Agent 系统架构**，来优化每个 Agent 的系统提示词以及相关的工具描述。注意，生成的语言请以用户语言为主：如果用户主要语言是英文，那么生成的系统提示词也必须是英文了；反之如果用户主要语言是中文，那么生成的系统提示词也必须是中文。

下面是一份系统提示（System Prompt）工程的完整指南，系统性地讲解了如何设计、维护和演进高质量、可靠、可控且安全的 AI 系统提示词：

一、系统提示的基本原则

清晰与精确：避免模糊指令，像写“合同”一样写提示，减少歧义。

具体与灵活的平衡：既要约束行为，又不能过度“硬编码”，为模型保留推理空间。

明确上下文与边界：清楚规定“能做什么 / 不能做什么”，防止越界。

预判失败与边缘情况：提前设计好危险、伦理或模糊场景的应对方式。

二、理解模型本身

不同模型能力不同，对指令的理解深度、稳定性各异。

模型依赖训练数据进行模式匹配，并非真正“理解”。

Token 和上下文窗口有限，关键指令要靠前、简洁。

三、系统提示的架构设计

分层结构：身份 → 能力 → 边界 → 格式 → 兜底策略。

关注点分离：行为（语气）、知识范围、安全规则分开设计。

结构化表达：使用 Markdown、标签（类似 XML）帮助模型“分块理解”。

模块化与可维护性：像软件一样组合、复用、版本化提示。

指令优先级与冲突解决：明确“谁覆盖谁”，避免矛盾指令。

四、行为工程（Behavioral Engineering）

人格与语气设计：不同角色需要一致、可信的“性格”。

专业与亲和力平衡：既可信，又不冷漠。

文化敏感性与包容性：避免俚语、刻板印象，适配全球用户。

决策与推理框架：教模型如何处理不确定性、列出假设、再下结论。

升级与退出机制：知道什么时候拒绝、转人工、给资源而不是“硬答”。

综上，系统提示需要像代码一样需要结构、测试和维护；又像写剧本一样塑造角色、语气与边界。


path: references/generator/analyze.md
content: # Agent 架构生成

你需要分析用户需求，根据用户需求来生成对应的 Agent 系统结构。用户给你的需求可能是模糊的，你需要尽可能地理解用户的需求背景，然后生成对应的 Agent 架构。

Agent 的主要类别包括：

- LLM 自主决策型 Agent：通过 LLM 进行自主决策来文字回复或调用工具
- 工作流型 Agent：包括 顺序型、并行型 Agent，其中，顺序型代表 Agent 中 `sub_agents` 字段中的 agents 会按照字面顺序执行，并行型代表 Agent 中 `sub_agents` 字段中的 agents 会并行执行
每类 Agent 都可以挂载子 Agent

你的任务是基于用户需求，根据上下文来生成一个或多个 Agent 架构以及每个 Agent 的基本信息。下面是一些生成的原则：

- Agent 架构要在满足用户需求的前提下，尽可能少的、使用扁平化的层级来创建 Agent，避免过于复杂的嵌套结构
- Agent 架构要有一个根 Agent，称为 root_agent
- 每个 Agent 都应该有一个清晰的功能描述，避免过于抽象或模糊
- 某些确定性场景，推荐使用 Tool 实现（因为 Tool 可以通过 Python 代码来 hard-coding，准确率更高）


path: references/generator/coding.md
content: # 代码生成

请你根据如下的说明，来基于上述生成的内容，构建生成 Python 代码。具体的 VeADK 代码生成规则你可以参考：

- **Agent 部分**：references/common/agent.md
- **工具部分**：references/common/tools.md


path: references/common/agent.md
content: # Agent 定义方法

## 导入方法

- LLM Agent: `from veadk import Agent`
- Sequential Agent: `from veadk.agents.sequential_agent import SequentialAgent`
- Loop Agent: `from veadk.agents.loop_agent import LoopAgent`

其中，LLM Agent 是最基础的智能体（由 LLM 启动进行自主决策），Sequential Agent 是按顺序执行的智能体，Loop Agent 是循环执行的智能体。

## 代码规范

你可以通过如下方式定义智能体：

```python
root_agent = Agent(
    name="...",
    description="...",
    instruction="...", # 智能体系统提示词
    sub_agents=[sub_agent] # 子智能体列表
)

sub_agent = Agent(
    name="...",
    description="...",
    instruction="...", # 智能体系统提示词
)
```

你也可以生成一个强制按顺序执行的智能体：

```python
sub_agent_1 = Agent(
    name="...",
    description="...",
    instruction="...", # 智能体系统提示词
)

sub_agent_2 = Agent(
    name="...",
    description="...",
    instruction="...", # 智能体系统提示词
)

# SequentialAgent 只需要写入 sub_agent 即可
root_agent = SequentialAgent(
    sub_agents=[sub_agent_1, sub_agent_2] # 子智能体列表
)
```

`sub_agent_1` 与 `sub_agent_2` 将会严格按顺序执行

注意，根智能体的命名必须为 `root_agent`。

## 让 Agent 结构化输出

为保证更高的准确率和 Agent 执行时的可控性，使用结构化输出是一种有效的手段。

在定义 Agent 时，通过 `model_extra_config={"response_format": ...}` 可以让 Agent 结构化输出。其中，`...` 是你定义的 Pydantic 模型，用于描述 Agent 的输出格式。

```python
from pydantic import BaseModel
from veadk import Agent, Runner


# 定义分步解析模型（对应业务场景的结构化响应）
class Step(BaseModel):
    explanation: str  # 步骤说明
    output: str  # 步骤计算结果


# 定义最终响应模型（包含分步过程和最终答案）
class MathResponse(BaseModel):
    steps: list[Step]  # 解题步骤列表
    final_answer: str  # 最终答案


agent = Agent(
    instruction="你是一位数学辅导老师，需详细展示解题步骤",
    model_extra_config={"response_format": MathResponse},
)
```

运行完毕后，你需要将结果解析为你定义的 Pydantic 模型，例如：

```python
import asyncio
import json

from veadk import Agent, Runner

agent = Agent()
runner = Runner(agent=agent) # 挂载想要运行的 Agent

response = asyncio.run(runner.run("你好")) # 使用 `run` 函数执行
response = json.loads(response)

parsed_response = MathResponse(**response)
print(parsed_response) # BaseModel 实例
```

## 运行 Agent

如果你想直接在 Python 中执行 Agent，可以通过定义 Runner 来执行：

```python
import asyncio

from veadk import Agent, Runner

agent = Agent()
runner = Runner(agent=agent) # 挂载想要运行的 Agent

response = asyncio.run(runner.run("你好")) # 使用 `run` 函数执行
print(response)
```

通常情况下，你可以定义一个函数来将 Agent 的执行封装起来，例如：

```python
async def run_agent(agent: Agent, prompt: str) -> str:
    runner = Runner(agent=agent)
    response = await runner.run(prompt)
    return response
```


path: references/common/knowledgebase.md
content: # 知识库

本文档介绍如何在 VeADK 中使用知识库。

## 导入

```python
from veadk.knowledgebase import KnowledgeBase
```

## 定义

通过 `KnowledgeBase` 类可以定义一个知识库，并挂载到智能体上。

```python
from veadk.knowledgebase import KnowledgeBase

# 定义知识库
knowledgebase = KnowledgeBase(
    name="my_knowledgebase",
    description="A knowledge base about ...",
    backend="viking",
    index=app_name,
)

agent = Agent(knowledgebase=knowledgebase)
```

其中，`backend` 为知识库后端，当前支持 `viking` 后端。`name` 为知识库名称，`description` 为知识库描述，你需要根据业务场景和知识库内容，来定义一个有意义的名称和描述。


path: references/common/tools.md
content: # Tools 定义方法

## 导入方法

- 网络搜索：`from veadk.tools.builtin_tools.web_search import web_search`
- 链接读取：`from veadk.tools.builtin_tools.link_reader import link_reader`
- 图像生成：`from veadk.tools.builtin_tools.image_generate import image_generate`
- 视频生成：`from veadk.tools.builtin_tools.video_generate import video_generate`
- 代码沙箱执行（用来执行 Python 代码）：`from veadk.tools.builtin_tools.run_code import run_code`

## 自定义 Tool

你可以通过撰写一个 Python 函数来定义一个自定义 Tool（你必须清晰地定义好 Docstring）：

```python
def add(a: int, b: int) -> int:
    """Add two integers together.
    
    Args:
        a (int): The first integer.
        b (int): The second integer.
    
    Returns:
        int: The sum of a and b.
    """
    return a + b


agent = Agent(tools=[add])
```

如果你使用自定义 Tool，请遵循以下规范：

推荐：（1）返回 dict，字段名稳定且语义清晰；（2）对外部错误用“可解释的错误字符串”或 {"error": "...", "details": ...}，避免直接抛异常导致整轮失败

不推荐：（1）返回复杂对象实例（模型侧不可读）；（2）返回超大文本（建议先做裁剪/分页/只返回必要字段）

为了让模型更愿意正确用工具，挂载与触发建议：（1）instruction 里明确“什么时候必须用工具”；（2）工具函数参数名要贴近业务语义（例如 order_id、city）；（3）返回里提供模型可直接引用的字段（例如 result、items、summary）

## 代码规范

你可以通过如下方式将某个工具挂载到智能体上，例如 `web_search` 网络搜索工具：

```python
from veadk.tools.builtin_tools.web_search import web_search

root_agent = Agent(
    name="...",
    description="...",
    instruction="...", # 智能体系统提示词
    tools=[web_search] # 挂载工具列表
)
```


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: suspicious | SkillSpector: suspicious (HIGH)