Coding Skills#

AI 驱动的分布式数据开发编程助手。

功能概述#

MaxFrame Coding Skill 是阿里云 MaxFrame 推出的 AI 编程辅助工具。它以智能插件的形式集成到主流 AI 编程助手中，将 MaxFrame 完整的分布式数据处理知识体系注入 AI Agent，使其能够根据自然语言描述，自动生成可直接运行的 MaxFrame 代码。

MaxFrame Coding Skill 覆盖 MaxFrame 开发的全链路流程：从会话管理、数据读写、算子选择到结果写入，降低分布式数据处理的开发门槛，提升编码效率。

技术架构#

MaxFrame Coding Skill 采用多层知识注入架构，将完整的开发知识体系系统化地注入 AI Agent：

+---------------------------------------------------+
|               AI Coding Assistants                |
|    (Claude Code / Cursor / Codex / Gemini CLI /   |
|        Tongyi Lingma / OpenCode / ...)            |
+---------------------------------------------------+
|            MaxFrame Coding Skill                  |
|  +----------+  +----------+  +----------+         |
|  | Coding   |  | Context  |  | Operator |         |
|  | Skill    |  | Guide    |  | Selector |         |
|  +----------+  +----------+  +----------+         |
|  +----------+  +----------+  +----------+         |
|  | Selection|  | API Docs |  | Operator |         |
|  | Rules    |  | 900+ pp. |  | Validator|         |
|  +----------+  +----------+  +----------+         |
|  +----------------------------------------+       |
|  |      Production-grade code examples    |       |
|  +----------------------------------------+       |
+---------------------------------------------------+
|               MaxFrame SDK                        |
|    DataFrame | Tensor | Learn | UDF | Session     |
+---------------------------------------------------+
|            MaxCompute distributed engine          |
+---------------------------------------------------+

组件	功能
编码技能定义	定义 Skill 的核心职责、能力边界和工作流程。
上下文指南	1700+ 行的全面参考文档，覆盖从基础到高级的所有功能。
算子选择代理	智能代理，负责算子发现、验证和推荐。
选择规则引擎	基于性能优先、批处理优先、兼容性优先等原则的选择策略。
API 文档库	900+ 页 MaxFrame 完整 API 文档，支持实时查询。
算子验证脚本	可执行脚本，验证算子是否存在并获取详细文档。
实战代码示例	10 个覆盖典型场景的完整生产级代码模板。

适用平台#

MaxFrame Coding Skill 支持主流 AI 编程助手，安装方式统一：

AI 编程平台	安装目录
Claude Code	`.claude/skills/`
Cursor	`.cursor/rules/`
Codex	`.codex/skills/`
OpenCode	`.opencode/skills/`
Gemini CLI	`.gemini/skills/`
通义灵码 / Qoder	`.aone_copilot/skills/` 或 `.qoder/skills/`

安装步骤#

下载安装包

Skill 安装包：maxframe-coding-skill.zip
解压到对应 AI 编程助手的 skills 目录。以 Claude Code 为例：
```
unzip maxframe-coding-skill.zip -d your-project/.claude/skills/
```
验证安装结果
```
ls your-project/.claude/skills/maxframe-job-coding/
```
目录中应包含 SKILL.md、examples/、references/ 和 scripts/。
安装完成后，在 AI 编程助手中输入以下指令验证
```
Create a MaxFrame job that reads data from the user_behavior table, groups by city to calculate GMV, and writes the result to the city_gmv_report table.
```
AI 将自动完成以下流程：
- 确认数据源和输出目标。
- 推荐最优算子组合，例如 groupby().agg()。
- 生成包含完整 Session 管理和错误处理的可运行代码。

核心能力#

智能算子推荐#

MaxFrame 提供多层次算子体系，包括标准 pandas 兼容算子、MaxFrame 专属的 .mf 扩展算子（如 apply_chunk、map_reduce、flatmap、rebalance 等），以及 UDF / UDTF 能力。面对具体的数据处理需求，Coding Skill 内置的 Operator Selector 智能代理能够自动完成算子选择与验证：

任务驱动推荐：根据任务描述，自动推荐最优算子组合，并给出选择理由。
API 真实性校验：基于 900+ 页 API 文档实时验证算子是否存在，杜绝幻觉 API。
备选方案提供：当首选算子存在限制时，自动提供替代方案，包括 UDF 回退方案。

示例：

User: "I need a rolling average for time-series data."
AI:   "Use DataFrame.rolling().
       If you need custom window logic, use .mf.apply_chunk() as an alternative."

全链路代码生成#

Coding Skill 覆盖 MaxFrame 开发的完整生命周期：

Session creation -> data reading -> operator selection -> data processing -> result writing -> Session cleanup

采用先确认再执行的三阶段交互模式，确保生成的代码精确匹配需求：

阶段	内容	说明
Phase 1	需求与数据确认	确认数据来源、目标表、列选择等。
Phase 2	算子选择确认	展示推荐算子及备选方案，等待确认。
Phase 3	代码生成与验证	基于确认结果生成完整可运行代码。

所有生成的代码均遵循生产级标准：

使用 try/finally 模式确保 Session 资源清理。
自动调用 .execute() 触发懒执行。
正确声明 UDF 返回类型（dtypes）。
包含完善的错误处理逻辑。

常见陷阱自动规避#

通用 AI 生成的 MaxFrame 代码常会遇到以下问题，Coding Skill 通过内置的知识体系逐一解决：

常见问题	Coding Skill 的解法
调用不存在的 API	基于 900+ 页文档实时校验，杜绝幻觉 API。
遗漏 `.execute()` 调用	强制遵循懒执行模式，代码模板自带执行触发。
Session 未正确销毁	所有代码使用 `try/finally` 模式确保资源释放。
UDF 返回类型不匹配	通过示例代码展示正确的 `dtypes` 声明方式。
执行引擎选择不当	按 SQL Engine > DPE > SPE 优先级自动推荐。
使用低效算子	在合适场景中自动推荐 `DataFrame.mf.apply_chunk` 替代 `Series.apply`。

内置应用场景模板#

Coding Skill 内置 10 个覆盖典型业务场景的生产级代码模板，AI Agent 可参考这些模板生成高质量代码：

场景分类	示例文件	核心能力
AI 大模型推理	`ai_function_basic.py`	ManagedTextLLM 分布式批量推理，开箱即用。
GPU 加速计算	`gpu_unit_dpe_processing.py`	`@with_running_options(gu=1)` GPU 资源分配。
OSS 文件处理	`fs_mount_example.py`	`@with_fs_mount` 分布式 OSS 文件读取。
多路 OSS 挂载	`oss_multi_mount.py`	单 / 多 OSS Bucket 同时挂载。
分组批处理	`groupby_batch_processing.py`	`groupby` + `apply_chunk` 高效分组批处理。
复杂数据结构	`complex_struct.py`	嵌套结构体 + 自定义分组处理。
Arrow 类型处理	`complex_struct_arrow.py`	PyArrow 复杂类型 + JSON 转换。
DLF 外部表写入	`dlf_table_write_basic.py`	DLF 外部表配置与数据写入。
DLF 主键表写入	`dlf_table_write_with_pk.py`	主键表 + 二进制数据类型处理。
大规模文档去重	`minhash_lsh_document_similarity.py`	MinHash + LSH 算法，支持 4000+ 并行度。

典型应用场景#

场景一：大模型分布式批量推理#

需求描述：使用大语言模型对海量文本数据批量推理。

无需部署模型、无需管理 GPU 资源、无需编写推理服务。ManagedTextLLM 内置 qwen2.5 系列、DeepSeek-R1 等多个模型，开箱即用。

生成代码示例：

import os

import maxframe.dataframe as md
from maxframe.learn.contrib.llm.models.managed import ManagedTextLLM
from maxframe.session import new_session
from odps import ODPS

o = ODPS(
    os.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"),
    os.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"),
    project="your-default-project",
    endpoint="your-end-point",
)

session = new_session(o)

try:
    df = md.DataFrame(
        {
            "query": [
                "What is the average distance from Earth to the Sun?",
                "What is the boiling point of water?",
            ]
        }
    )
    df.execute()

    llm = ManagedTextLLM(name="qwen2.5-1.5b-instruct")
    messages = [
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "{query}"},
    ]
    result = llm.generate(df, prompt_template=messages)
    result.execute()
finally:
    session.destroy()

场景二：OSS 分布式文件处理#

需求描述：将 OSS 存储中的文件挂载到每个分布式 Worker 节点，并行读取与处理。

OSS 路径自动挂载为本地文件系统路径，分布式 Worker 自动并行读取，吞吐量随节点数线性扩展。