API脚本化

---
name: API脚本化
description: 根据 API 文档自动生成结构化的、配置驱动的工程项目
---
# api-project-architect: API 项目架构师

该 Workflow 用于将一份原始的 API 技术文档转化为一个结构清晰、配置驱动、零硬编码的生产级脚本工具项目。

## 核心设计理念
- **零硬编码 (Zero Hardcoding)**：所有的密钥、端点、功能开关、参数调整、业务数据都必须存放在外部配置文件中。
- **配置驱动 (Configuration Driven)**：通过修改 JSON 或 ENV 文件即可控制程序行为，无需改动核心代码。
- **保姆级体验 (Nanny-level UX)**：配置文件必须包含详尽的中文说明、可选值参考，且程序运行要有丰富的颜色日志反馈。

## 执行步骤

### 1. 深入分析 API 文档
- 阅读指定的 API 文档，提取以下核心要素：
    - **身份验证**：鉴权方式（Header, Token, AppID 等）。
    - **接口端点**：提交请求、查询结果或回调的 URL。
    - **功能参数**：哪些是布尔开关（开关功能），哪些是数值调整（性能/阈值），哪些是枚举值。
    - **数据载荷**：核心输入（文件路径、URL 等）及其格式要求。
    - **异常处理**：错误码及其对应的业务含义。

### 2. 构建项目文件体系
按照以下标准结构初始化目录：
- **`api_keys.env`**：存储所有敏感信息。包括 AppID、Secret、Endpoint URL 等。
- **`[project_name]_settings.json`**：核心配置手册。
    - 每个条目必须包含：`功能说明` (中文), `所有可选值` (列表/范围), `当前配置值` (用户修改项)。
- **`[custom_data].md`**：如果 API 支持干预词库、敏感词、白名单等，使用 Markdown 片段（如 `- 关键词`）让用户维护。
- **`main.py`**：核心逻辑脚本。
- **`README.md`**：操作手册。

### 3. 实现核心脚本逻辑 (`main.py`)
脚本开发必须遵循以下规范：
- **强加载逻辑**：使用 `load_settings` 函数读取 JSON。如果 JSON 格式报错，程序必须打印错误原因并直接退出，禁止使用隐式的默认值，以防用户配置失效而不自知。
- **自动化依赖处理**：在脚本开头处理环境变量加载。
- **健壮的过程管理**：
    - 鉴权逻辑封装。
    - 请求 Payload 动态构造（根据配置文件自动剔除值为 `null` 的项）。
    - 轮询逻辑（如果是非异步接口）。
    - 结果格式化并保存为本地文件（如 `.md`, `.json`）。
- **颜色日志输出**：使用 ANSI 颜色区分 `[信息]`, `[警告]`, `[错误]`, `[进度]`。

### 4. 生成用户文档
- 编写 `README.md`，包含：
    - 项目背景。
    - 文件体系说明（解释每个配置文件的作用）。
    - 快速开始指南。
    - 故障排除（常见错误码对照）。

## 使用示例
> 用户：请根据 @[某 API 文档.md] 生成项目。
> 助理：收到。我将按照 api-project-architect 规范为您构建项目：
> 1. 生成 api_keys.env 管理密钥。
> 2. 生成 settings.json 作为功能开关手册。
> 3. 生成 main.py 实现核心逻辑并对接上述配置。
> 4. 生成 README.md 引导操作。