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 引导操作。