跳转至

AI 辅助编程

本文以 OpenCode 为例，说明如何通过 MCP Coding 接入 DataFlux Func，让 AI Agent 在授权范围内阅读代码、修改脚本、执行草稿验证，以及处理资源目录中的文件。

如果只需要了解最基础的接入步骤，可以先阅读 MCP 服务 / MCP 编程。本文在此基础上补充更完整的权限配置、提示词示例和本地缓存目录工作流。

请按任务拆分最小权限

MCP Coding 可以读取、修改、执行和发布 DataFlux Func 中的对象。为 AI Agent 创建 Access Token 时，建议按任务开放最小范围，例如只读代码时不要开放写入和发布权限，修改单个脚本时不要开放整个资源根目录。

1. 使用 OpenCode 接入 MCP Coding

1.1 创建 Access Token

在 DataFlux Func 中进入：

管理 / Access Token / 当前 Access Token 行的「配置」 / 配置 Access Token / MCP 编程 / 规则

开启「MCP 编程」后，为当前任务配置规则。规则从上到下依次匹配，首个命中的规则决定是否允许访问。

常见规则如下：

规则 说明
scriptSet:demo:r 允许读取脚本集 demo 及其下属脚本
scriptSet:demo:rwxp 允许读取、创建、修改、删除、执行和发布脚本集 demo 下的脚本
script:demo__tools:rwxp 允许读取、修改、执行和发布脚本 demo__tools
funcAPI:demo*:rw 允许读取、创建、修改和删除匹配 demo* 的函数 API
apiAuth:demo*:rw 允许读取和修改匹配 demo* 的 API Auth
fileManager:demo_cache:rw 允许读写资源路径 demo_cache
fileManager:demo_cache/*:rw 允许读写资源路径 demo_cache 下的文件和目录
fileService:demo_cache:rw 允许读取和修改文件服务 demo_cache
connector:guance:rx 允许读取并执行连接器 guance
envVariable:demo_*:r 允许读取匹配 demo_* 的环境变量
cronJob:demo*:rwx 允许读取、修改并手工触发匹配 demo* 的定时任务

规则后可以添加 # 注释，系统保存规则时会忽略这些注释：

规则示例
1
2
3
4
5
6
scriptSet:demo:rwxp      # 允许 AI Agent 维护 demo 脚本集
script:demo__*:rwxp      # 允许 AI Agent 维护 demo 脚本集下的脚本
funcAPI:demo*:rw         # 允许维护 demo 相关函数 API
fileManager:demo_cache:rw
fileManager:demo_cache/*:rw
connector:guance:r       # 默认只读连接器配置

空规则表示无权限

如果 MCP 编程规则为空，AI Agent 连接成功后也无法看到脚本、资源文件或其他对象。此时应让 AI Agent 输出最小权限建议，而不是继续猜测对象不存在。

1.2 配置 OpenCode

在 OpenCode 的 MCP 配置中添加 DataFlux Func MCP Coding 服务：

示例：OpenCode 配置
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
{
  "mcp": {
    "dataflux-func-mcp-coding": {
      "enabled": true,
      "type"   : "remote",
      "url"    : "{DataFlux Func 访问地址}/mcp/coding",
      "headers": {
        "X-Dff-Access-Token": "atk-xxxxx:xxxxx"
      }
    }
  }
}

配置项如下：

配置项 值
URL 地址 {DataFlux Func 访问地址}/mcp/coding
请求头 X-Dff-Access-Token: atk-xxxxx:xxxxx

先用 MCP Inspector 调试

DataFlux Func 的 MCP Coding 服务遵循 MCP 规范。接入 OpenCode 前，可以先使用 MCP Inspector 检查地址、请求头和工具列表是否正常。

1.3 检查连接和权限

接入后，建议先让 AI Agent 读取 MCP Coding 帮助信息并总结权限范围：

提示词示例：检查连接
1
2
3
4
5
6
7
8
请检查 DataFlux Func MCP Coding 是否已连接成功。

要求：
1. 读取 MCP Coding 帮助信息。
2. 总结当前 Access Token 开放了哪些脚本集、脚本、函数 API、API Auth、资源目录、文件服务、连接器、环境变量和定时任务。
3. 如果目标对象不可见，请判断是权限不足还是对象确实不存在。
4. 如权限不足，请给出完成当前任务所需的最小规则建议。
5. 只做检查和总结，不要修改任何代码、文件或配置。

AI Agent 能读取到 help 返回的权限规则和工具说明，通常表示连接正常。后续 list-* 工具的结果会按权限过滤，因此列表为空不一定代表对象不存在，也可能是 Access Token 没有覆盖目标 ID 或路径。

2. 使用 AI 阅读和理解代码

阅读类任务适合只开放 r 权限。AI Agent 可以帮助梳理脚本结构、入口函数、函数 API、连接器和环境变量使用情况，但不能修改草稿、执行函数或发布脚本。

2.1 示例背景

假设有一个脚本集 monitor_tools，其中包含告警处理逻辑：

对象 示例
脚本集 monitor_tools
脚本 monitor_tools__alert、monitor_tools__utils
入口函数 monitor_tools__alert.alert_webhook
函数 API monitor_tools_alert_webhook
连接器 guance
环境变量 monitor_default_level

希望 AI Agent 回答以下问题：

  • 哪些函数会被外部调用
  • 每个入口函数接收什么参数，返回什么数据
  • 告警数据如何被校验、清洗、转换和写入
  • 哪些默认值、异常分支和外部依赖需要人工确认

2.2 推荐权限

Access Token MCP 编程规则示例
1
2
3
4
5
scriptSet:monitor_tools:r      # 读取脚本集及其下属脚本
script:monitor_tools__*:r      # 读取 monitor_tools 下的脚本
funcAPI:monitor_tools*:r       # 读取函数 API 配置
connector:guance:r             # 读取连接器配置
envVariable:monitor_*:r        # 读取相关环境变量

阅读代码不需要 rw、rwx 或 rwxp。如果需要让 AI Agent 执行连接器查询，再把对应连接器规则调整为 rx。

2.3 提示词示例

提示词示例：阅读代码
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
请通过 DataFlux Func MCP Coding 阅读脚本集 monitor_tools，并帮我理解告警处理流程。

范围：
- 重点阅读 monitor_tools__alert 和 monitor_tools__utils。
- 如果存在 @DFF.API(...) 修饰的顶层函数，请逐个说明用途。
- 如需查看函数 API、连接器或环境变量配置，只读取配置，不要修改。

输出要求：
1. 先列出你实际读取到的脚本、入口函数、函数 API 和外部依赖。
2. 用一段话说明整体处理流程。
3. 用表格列出每个入口函数的参数、返回值、外部依赖和错误处理。
4. 标出需要人工确认的逻辑分支、默认值和兼容性风险。
5. 不要修改草稿，不要执行函数，不要发布脚本。

2.4 AI Agent 的典型流程

阅读代码时，AI Agent 通常会使用以下 MCP Coding 工具：

步骤 工具 说明
读取帮助 help 确认权限范围、ID 规则和操作约束
查找脚本集 list-script-sets 查找目标脚本集
查找脚本 list-scripts 查找脚本集中的脚本
读取代码 get-script-code 或 get-script-code-draft 读取已发布代码或草稿代码
查看函数 API list-func-apis 了解函数如何对外暴露
查看连接器 list-connectors 确认连接器 ID 和类型
查看环境变量 list-env-variables 确认代码依赖的环境变量

阅读类任务不应调用 modify-script、execute-script-code-draft、publish-script、write-file 或 upload-file。

2.5 结果示例

可以要求 AI Agent 使用固定结构输出，便于人工检查：

输出结构示例
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
已读取对象：
- 脚本集：monitor_tools
- 脚本：monitor_tools__alert、monitor_tools__utils
- 函数 API：monitor_tools_alert_webhook
- 外部依赖：guance 连接器、monitor_default_level 环境变量

整体流程：
外部系统通过函数 API 调用 alert_webhook。函数先校验告警参数，
再使用默认级别补齐缺失字段，随后调用 utils 中的构造函数生成事件数据，
最后通过 guance 连接器写入事件。

入口函数：
| 函数 | 用途 | 参数 | 返回值 | 外部依赖 |
| ---- | ---- | ---- | ------ | -------- |
| monitor_tools__alert.alert_webhook | 接收告警 Webhook | alert_id, title, level | dict | guance 连接器、monitor_default_level |

需要人工确认：
1. level 为空时默认使用 monitor_default_level，是否符合业务预期。
2. 写入事件失败时当前逻辑只返回失败结果，没有重试。
3. title 为空时是否应该直接拒绝请求。

3. 使用 AI 修改代码

修改类任务应明确要求 AI Agent 遵守「读取最新草稿 - 修改草稿 - 执行草稿验证 - 按需发布」流程。

DataFlux Func 中脚本修改后会先保存为草稿，发布后才会成为正式版本。写回草稿前，AI Agent 应使用最新 codeDraftMD5，避免覆盖其他人的更新。

3.1 示例目标

继续使用 monitor_tools 作为示例。现在希望修改 monitor_tools__alert.alert_webhook：

  • 新增可选参数 source
  • 当 source 为空时，默认使用 dataflux-func
  • 返回结果中增加 source
  • 保持已有参数、返回结构和错误处理兼容

3.2 推荐权限

Access Token MCP 编程规则示例
1
2
3
4
5
scriptSet:monitor_tools:rwxp   # 读取、修改、执行、发布脚本集下的脚本
script:monitor_tools__*:rwxp   # 读取、修改、执行、发布 monitor_tools 脚本
funcAPI:monitor_tools*:r       # 读取函数 API 配置，确认外部调用关系
connector:guance:r             # 默认只读取连接器配置；需要真实调用时再改为 rx
envVariable:monitor_*:r        # 读取相关环境变量

如果修改过程中需要读写资源文件，再按需增加 fileManager:<resourcePath>:rw 和 fileManager:<resourcePath>/*:rw 规则。

3.3 提示词示例

提示词示例：修改代码
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
请通过 DataFlux Func MCP Coding 修改脚本 monitor_tools__alert。

目标：
- 为入口函数 alert_webhook 新增可选参数 source。
- source 为空时默认使用 dataflux-func。
- 返回结果中增加 source 字段。
- 保持现有参数、返回结构和错误处理逻辑兼容。

执行要求：
1. 先读取 MCP Coding 帮助信息，确认当前权限。
2. 读取 monitor_tools__alert 的最新草稿，并说明你准备修改的位置。
3. 修改前参考同脚本中类似参数的处理方式，保持代码风格一致。
4. 写回草稿时使用最新 codeDraftMD5，避免覆盖远端更新。
5. 修改后使用 execute-script-code-draft 执行 alert_webhook，至少覆盖 source 为空和 source 有值两种情况。
6. 测试通过后再发布脚本；如果测试失败，不要发布，并说明失败原因。
7. 不要修改无关脚本、函数 API、连接器或环境变量。

3.4 AI Agent 的典型流程

步骤 工具 说明
读取帮助 help 确认权限、ID 规则和任务约束
查找脚本 list-scripts 确认目标脚本在权限范围内
读取草稿 get-script-code-draft 获取最新草稿和 codeDraftMD5
修改草稿 modify-script 写回完整草稿，并传入最新 codeDraftMD5
执行验证 execute-script-code-draft 调用草稿函数验证行为
发布脚本 publish-script 测试通过后发布为正式版本

需要注意：

  • 脚本 ID 格式为 <script_set_id>__<script_name>，例如 monitor_tools__alert。
  • 函数 ID 格式为 <script_id>.<function_name>，例如 monitor_tools__alert.alert_webhook。
  • 需要被调试执行、函数 API、定时任务或函数页面调用的顶层函数，应使用 @DFF.API(...) 修饰。
  • 同一脚本集内导入其他脚本时，推荐使用 import __utils as utils 或 from __utils import xxx。
  • 被导入脚本使用的是已发布版本，不是草稿版本。不要依赖两个未发布草稿互相导入后的行为。

3.5 验证提示词示例

如果只想让 AI Agent 验证草稿，不发布脚本，可以单独输入：

提示词示例：只验证不发布
1
2
3
4
5
6
7
8
请验证 monitor_tools__alert 当前草稿是否符合预期。

要求：
1. 使用 execute-script-code-draft 调用 alert_webhook。
2. 测试 source 为空时是否返回 dataflux-func。
3. 测试 source 为 webhook 时是否原样返回 webhook。
4. 输出每个测试用例的入参、返回值和结论。
5. 不要发布脚本。

4. 本地缓存目录说明

对于较复杂的任务，AI Agent 可能会把 DataFlux Func 中的脚本草稿或资源文件临时同步到本地缓存目录，借助本地搜索、格式化、构建、差异比较等工具完成处理。这个过程由 MCP Coding 的工具提示和 AI Agent 自动完成，用户通常不需要关心，也不需要在提示词中要求「下载、修改、上传」。

用户只需要说明任务目标和必要约束：

  • 要修改的脚本集、脚本、函数或资源路径
  • 业务目标和验收标准
  • 是否需要发布脚本
  • 哪些对象不能修改或删除
  • 涉及资源文件、外部连接器或生产数据时的安全边界

DataFlux Func 远端脚本草稿和资源目录始终是权威数据。本地缓存目录只是 AI Agent 的临时工作区，不能作为长期存储或最终结果来源。

4.1 提示词示例

提示词示例：本地缓存目录工作流
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
请通过 DataFlux Func MCP Coding 协助修改脚本集 monitor_tools。

目标：
- 重点分析 monitor_tools__alert 和 monitor_tools__utils。
- 完成代码修改并写回 DataFlux Func 草稿。
- 执行草稿验证，通过后发布。

约束：
1. 不要修改 monitor_tools 之外的脚本。
2. 不要删除资源文件。
3. 如果发现远端草稿在修改期间发生变化，请暂停并说明冲突。
4. 发布前必须列出测试用例和测试结果。

5. 常见注意事项

  • 如果只是阅读代码，只开放 r 权限。
  • 如果需要修改但不需要发布，可以开放 rwx，不开放 p。
  • 如果需要发布脚本，才开放 rwxp。
  • 如果需要操作资源文件，路径使用 fileManager:<resourcePath>:r 或 fileManager:<resourcePath>:rw。
  • 如果需要公开资源目录，还要配置对应的 fileService:<id>:r 或 fileService:<id>:rw 权限。
  • 如果需要手工触发定时任务，cronJob 权限必须包含 x。
  • 如果函数需要返回大数据或文件，应使用 DFF.RESP_LARGE_DATA(...) 或 DFF.RESP_FILE(...)。
  • 如果任务涉及外部系统写入，先确认连接器权限和测试环境，避免误写生产数据。
  • 如果 AI Agent 发现权限为空或目标对象不可见，应先生成最小权限建议，而不是继续猜测对象不存在。