# Algorithm Code Standards

> 算法代码提交规范

- Skill: `fdueblab/algorithm-code-standards` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add fdueblab/algorithm-code-standards`
- Raw SKILL.md: https://api.skillmd.com/api/skills/fdueblab/algorithm-code-standards/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: fdueblab (https://skillmd.com/u/fdueblab)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/fdueblab/algorithm-code-standards

---

# 算法代码提交规范

本技能定义了众智工场平台的算法代码提交要求，适用于「算法模型想定式开发」任务。
生成的代码必须满足以下规范，以便后续在平台进行自动代码分析与封装为 MCP 服务。

## 核心函数独立性（最重要）

- 每个可被封装为 MCP 工具的核心函数必须能单独直接调用，不依赖模块级/全局可变状态。
- 模型加载、配置读取、资源路径解析等必须在函数内部完成。
- 禁止在函数外 `model = load_model()` 再在函数内使用。
- 推荐每次调用在函数内完成加载以保证独立性与可测试性。

## 类型注解与 Google 风格文档字符串

- 所有对外核心函数必须具备完整类型注解（参数与返回值）。
- 每个核心函数必须使用 Google 风格 docstring：
  - 第一行：简短功能描述
  - `Args:` 列出每个参数
  - `Returns:` 列出返回值含义

## 代码结构

- **算法层**：清晰的顶层函数，必须包含 `main_process(...)` 主入口，签名带完整类型注解。
- **Web 层（可选推荐）**：Flask + flask-restx 生成 Swagger，路由只做参数校验与调用核心函数。
- 保存为单文件 `{model_name}_algorithm.py`。
- 文件顶部用注释块列出依赖清单（pip requirements 风格，带版本号）。

## 质量要求

- 语法正确，可直接 `python <文件名>.py` 运行。
- 符合 PEP 8。
- 适当的 try/except、输入校验与日志。
- 不要使用省略号或 pass 代替真实实现。
- 如有参考来源，在 docstring 中标注。