# Python Algorithm Project

> 初始化和维护同时包含 Api_frame 与 Napi_frame 的 Python 算法项目，并编写、整理或审查无需 FastAPI 的独立算法工程。纯 FastAPI 封装应使用 algorithm-api-wrapper；普通单文件 Python 问答无需使用本 skill。

- Skill: `codeboy-bot/python-algorithm-project` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add codeboy-bot/python-algorithm-project`
- Raw SKILL.md: https://api.skillmd.com/api/skills/codeboy-bot/python-algorithm-project/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: Codeboy-bot (https://skillmd.com/u/codeboy-bot)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/codeboy-bot/python-algorithm-project

---


# Python 算法项目规范

## 目标与边界

把算法项目整理为 API 与非 API 两条清晰的工程链路。开始前先检查现有目录、代码和用户改动；补齐缺失内容，不覆盖或删除现有文件，除非用户明确要求。

项目根目录采用：

```text
<project-root>/
├── Api_frame/
└── Napi_frame/
```

- `Api_frame/` 存放需要 FastAPI 调用的算法工程。创建或改造其中的工程时，必须加载并遵循 `algorithm-api-wrapper`，由它决定具体 API 结构、Swagger、配置和验证方式。本 skill 只负责顶层分区与路由，不复制 API 规范。
- `Napi_frame/` 存放无需 API、通过 `main.py` 直接运行的独立算法工程。处理这类工程时，完整读取并执行 [references/napi-project-spec.md](references/napi-project-spec.md)。

如果用户只要求其中一种工程，也保留上述总体分区；不要无故为另一分区生成占位业务代码。

## 工作流程

1. 检查项目根目录和已有算法文件，识别任务属于 API、非 API，或同时包含两者。
2. 确保 `Api_frame/`、`Napi_frame/` 存在；已存在则复用。
3. 对 API 工程加载 `algorithm-api-wrapper` 并在 `Api_frame/` 内实施。
4. 对非 API 工程读取非 API 规范，确定英文业务名，并在 `Napi_frame/` 下创建或更新独立编号目录。
5. 从算法真实入口和调用链拆分 `main.py` 与 `util_tools.py`；在 `main()` 中每次调用 `util_tools.py` 函数前，紧邻写明该调用的输入和输出；不要制造空实现来冒充已完成算法。
6. 同步配置、日志、文档、依赖和调用示例，避免代码与 README 不一致。
7. 验证语法、导入和最小调用；有可用样例数据时执行一次完整算法。

## 非 API 工程编号

- 目录名格式为两位递增编号加简洁英文业务名，例如 `01Vis_Calculate`、`02Wind_Field`。
- 新建时扫描 `Napi_frame/` 下符合 `^[0-9]{2}` 的现有目录，以最大编号加一；没有现有工程时从 `01` 开始。
- 不因目录顺序变化给已有工程重新编号，不复用会造成歧义的旧编号。
- 用户指定目录名或编号时优先遵从；若发生冲突，先说明冲突再请求确认。

## 完成标准

- 两个顶层目录位置正确，目标工程文件齐全。
- 非 API 工程的配置有逐项注释，路径不依赖硬编码的某台机器绝对路径。
- `main.py` 能直接运行，成功时打印最终结果，失败时打印完整 traceback，并在所有情况下打印总耗时。
- `main()` 中调用 `util_tools.py` 函数的每个位置都有与实际参数、返回值一致的输入/输出注释。
- 关键阶段的终端输出包含实际源码行号和处理内容，日志写入配置指定的位置。
- 每个函数有说明，代码格式整齐，README、依赖清单与实现一致。
- 至少运行 `python -m compileall <project-dir>` 和入口导入检查；若无法完整运行，明确列出未验证项及原因。