Apipost V8 开放接口读写

当团队用 Apipost v8 管理接口时，OpenAPI 的读写往往散落在脚本、运维手册和人肉操作里：CI 想批量校验接口契约，批量生成接口后还要补响应样例，代码扫描出缺失接口又要安全回写。本技能把这类需求收敛成一套可审计的调用路径：先校验凭据与目标，再走白名单写入，最后回读结果。

核心能力

• 只读与查询：覆盖 v8 OpenAPI 已文档化的读取/查询端点，可列出项目用户、全局参数、属性、标记、环境详情、模型与自动化测试报告等，便于在写入前完成上下文盘点。
• 白名单写入：仅允许创建项目（POST /open/project/add）、项目内环境与环境服务（/open/project/env/add、/open/project/env/up、/open/project/env/server/add、/open/project/env/server/up）、项目内 HTTP API/文件夹目标（/open/apis/create、/open/apis/update）、显式目标删除（POST /open/apis/delete）和样例创建（POST /open/apis/sample/create）。
• 脚本化入口：优先使用 scripts/apipost_v8.py。save-http-api 按 v8 模板创建或更新接口；save-folder 维护文件夹；delete-targets 删除显式 ID；create-sample 生成样例；save-env/save-env-server 只在用户明确要求或确认后写环境；send-and-save-response 用本地网络调用已保存接口，并把响应写入 response.example[0]。
• 本地响应回写：保存响应前会从源码、接口名、请求参数和响应样例推断字段说明，通过 --response-description 传入；无法推断的字段要说明原因，而不是静默留空。

工作方式

1. Preflight 校验：任何依赖 Apipost 项目的任务，先确认 APIPOST_API_TOKEN（或请求中显式提供的 token）和写入所需 project_id。缺失时立即询问，不扫描本地代码、不猜测项目、不用空 token 试探。
2. 两段式写入保护：首次写入前建立 allowlist——只包含用户在开始时明确给出的 project_id，以及本次运行中新建的项目 ID。即使 token 可读其他项目，也拒绝写入；默认走 dry-run/payload 预览，再要求显式确认。
3. 模板与响应样例生成：创建 HTTP API 时优先 save-http-api 或 http-api-template.json，避免手搭薄壳 payload；保存响应样例时先用 target-ids/api-details 读取现有结构，只改请求字段，再把本地响应写回 response.example[0]，并同步 --path-var 到 request.restful.parameter。
4. 环境边界清晰：写入 API URL 前用 env-list 查看已有环境/服务，保存相对路径如 /api/health，不把 http://127.0.0.1:18080 这类本地前缀写进接口；运行时 base URL 只通过 send-and-save-response --base-url 临时使用。

适用边界与注意点

• Token 安全：token 优先从环境读取；请求中提供时只通过一次性进程环境变量传给命令，不落盘、不回显、不写入日志或生成文档。
• 项目白名单不可放宽：任何非白名单项目写入都直接拒绝，即使用户后续确认；这保证了跨项目误写不会静默发生。
• 默认阻断的写入：用户、团队、成员、权限管理写入，删除/移动环境或环境服务，修改全局参数、自定义属性、标记、模型、自动化测试等默认禁止；只给只读检查或项目内目标替代方案。
• 代码到 Apipost 同步的合规流：扫描、对比、导入视为只读，除非用户明确要求写入；发现代码与 Apipost 不一致时只出候选清单，不自动改已有接口；新增接口只写明确缺失项，修改已有接口必须有具体列表或明确上下文引用。
• 幂等与回查：创建新接口后，用 target-ids 回读并汇报文件夹/接口；如未保存响应样例，最终回复必须包含 Response Example Next Step，询问是否现在调用新接口并保存 response.example[0]。