apipost-v8读取、写入

概述

Apipost V8 OpenAPI

Use this skill for Apipost v8 OpenAPI work.

Official v8 document reviewed on 2026-06-30: https://docs.apipost.net/docs/detail/2a37986cbc64000?target_id=0

Required Inputs

When this skill is explicitly invoked for a task that depends on an Apipost project, perform this check before any task work, including local code scanning, repository file reads, Apipost API calls, or attempts to infer context from the workspace.

Verify that the user has provided or the environment already contains:

• An API token, either from APIPOST_API_TOKEN or a token explicitly supplied in the current request.
• A project_id for every project-scoped read or write operation.

If either value is missing, stop immediately and ask for the missing value as the first user-visible response after reading this skill. If the user supplied the token and project_id in the current request, treat them as present; do not ask the user to also set environment variables. Do not scan local code first, do not inspect project files, do not make exploratory Apipost API calls, do not list teams/projects to guess a project, and do not attempt calls with placeholder or empty tokens.

project_code is optional in v8 and should be passed when the user provides it, but prefer project_id when both are available.

Scope

Support all read/query endpoints documented in Apipost v8.

Allow writes only for:

• Creating projects via POST /open/project/add.
• Project-internal environment and service create/update operations via /open/project/env/add, /open/project/env/up, /open/project/env/server/add, and /open/project/env/server/up.
• Project-internal target operations: create/update HTTP API and folder targets via /open/apis/create and /open/apis/update.
• Project-internal explicit target deletion via POST /open/apis/delete.
• Project-internal API sample creation via POST /open/apis/sample/create.
• Local response capture plus writeback to an explicit target through send-and-save-response.

Project-internal writes are allowed only for project IDs explicitly provided by the user at the start of the skill use as write targets, plus project IDs created during the same skill run. If a request tries to write to any other project, refuse even if the token has access and even if the user confirms.

Do not perform user, team, member, or permission-management writes. Do not delete or move environments or environment services by default. Do not modify global params, custom attributes, marks, models, or automated tests by default; these writes are listed as blocked in references/capability-matrix.md.

References

Read only what the task needs:

• references/capability-matrix.md for the complete endpoint list and allowed/blocked operation policy.
• references/payload-guidance.md before any create/update/delete/response-write operation.
• references/spring-import-notes.md before importing Java/Spring Controller interfaces into Apipost.
• references/http-api-template.json as the base shape when creating HTTP API targets.

Script

Use scripts/apipost_v8.py for deterministic calls when possible.

Prefer dedicated subcommands over raw request for fragile writes:

• save-http-api creates or updates HTTP API targets from the v8 template; for JSON body field descriptions, the agent should generate concise descriptions from context and pass --body-description key=description.
• save-folder creates or updates project target folders without fragile inline JSON.
• delete-targets deletes explicit target IDs with the confirmed Apipost v8 body shape.
• create-sample creates an API sample from a JSON payload file or object with project allowlist and confirmation checks.
• save-env-server creates or updates a project environment service only after the user explicitly asks for that environment/service write or confirms a proposed environment change.
• save-env creates or updates a project environment and can bind existing services with --server server_id=uri and environment variables with --env-var key=value|description; do not call it automatically from API creation, synchronization, or response-example capture flows.
• send-and-save-response sends a saved HTTP API with local networking and writes the response body/parameter table into response.example[0]; it resolves {pathVar} placeholders from request.restful.parameter or --path-var key=value, applies saved query parameters when sending, synchronizes --path-var values back to request.restful.parameter, and never saves runtime values back into request.url. Before using it for JSON responses, the agent must generate concise response field descriptions from source code, interface names, request parameters, response samples, and existing Apipost descriptions, then pass repeated --response-description key=description arguments. If descriptions cannot be inferred, state the reason in the final report; do not silently omit them.
• target-ids maps to v8 GET /open/apis/list.
• api-details maps to v8 POST /open/apis/details.
• env-list maps to v8 GET /open/project/env/list.
• Read-only helpers include project-users, global-params, attributes, attribute-detail, marks, env-detail, env-server-list, env-server-detail, models-list, model-details, automated-tests, report-list, and report-detail.

Token handling:

• Prefer APIPOST_API_TOKEN from the environment.
• If the user explicitly supplied a token in the current request, use it for this skill run instead of asking them to set APIPOST_API_TOKEN.
• When using a request-supplied token with the bundled script, pass it only through a transient process environment variable for the single command or command group, then remove it. Do not persist it.
• Never write tokens into scripts, source files, notes, logs, or generated documents.
• Do not echo token values.

Base host:

• Default host is https://api.apipost.net.
• Use --host only for private deployments.

Examples:

$env:APIPOST_API_TOKEN = '<token>'
$env:APIPOST_WRITE_PROJECT_IDS = '<project_id_allowed_for_writes>'
python scripts/apipost_v8.py user-info
python scripts/apipost_v8.py create-project --team-id '<team_id>' --name '新项目' --dry-run
python scripts/apipost_v8.py target-ids --project-id '<project_id>'
python scripts/apipost_v8.py env-list --project-id '<project_id>'
python scripts/apipost_v8.py env-server-list --project-id '<project_id>'
python scripts/apipost_v8.py save-env-server --project-id '<project_id>' --name '本地服务' --dry-run
python scripts/apipost_v8.py save-env-server --project-id '<project_id>' --name '本地服务' --confirm
python scripts/apipost_v8.py save-env --project-id '<project_id>' --name '本地环境' --server '<server_id>=http://127.0.0.1:18080' --dry-run
python scripts/apipost_v8.py save-env --project-id '<project_id>' --name '本地环境' --server '<server_id>=http://127.0.0.1:18080' --confirm
python scripts/apipost_v8.py api-details --project-id '<project_id>' --target-id '<target_id>'
python scripts/apipost_v8.py models-list --project-id '<project_id>'
python scripts/apipost_v8.py automated-tests --project-id '<project_id>'
python scripts/apipost_v8.py save-folder --project-id '<project_id>' --name '技能测试示例接口' --dry-run
python scripts/apipost_v8.py save-http-api --project-id '<project_id>' --parent-id '<folder_or_0>' --name '健康检查' --method GET --url '/api/health' --dry-run
python scripts/apipost_v8.py save-http-api --project-id '<project_id>' --parent-id '<folder_or_0>' --name '健康检查' --method GET --url '/api/health' --confirm
python scripts/apipost_v8.py create-sample --project-id '<project_id>' --payload-file '.sample.json' --dry-run
python scripts/apipost_v8.py send-and-save-response --project-id '<project_id>' --target-id '<target_id>' --base-url 'http://127.0.0.1:18080' --dry-run
python scripts/apipost_v8.py send-and-save-response --project-id '<project_id>' --target-id '<target_id>' --base-url 'http://127.0.0.1:18080' --confirm
Remove-Item Env:APIPOST_API_TOKEN -ErrorAction SilentlyContinue
Remove-Item Env:APIPOST_WRITE_PROJECT_IDS -ErrorAction SilentlyContinue

For JSON request bodies, prefer --raw-body-file over inline --raw-body. PowerShell quoting can strip JSON quotes from inline arguments, which prevents request body parameter extraction.

Safety Rules

For read operations, execute directly when the user provides enough identifiers.

For code scan, import, and synchronization tasks:

• Treat reading backend code and comparing it with Apipost as read-only unless the user explicitly asks for a write action.
• Do not treat a code/Apipost mismatch as permission to modify an existing Apipost interface. Existing interfaces may intentionally differ because of reverse proxy prefixes, deployment environments, historical contracts, or another person's work.
• When the user asks to "see which interfaces are missing", "compare", "inspect", "scan", or similar, only produce a candidate list. Do not create, update, delete, reorder, rename, or rewrite any interface.
• When the user asks to "write/add/create new interfaces", write only interfaces that are clearly missing from the reviewed comparison result. Do not modify existing interfaces discovered during that comparison.
• To modify existing interfaces, require a concrete interface list or an unambiguous current-context reference. Valid examples: "the 4 interfaces you just created", "the missing interfaces from the previous comparison that you just created", or an explicit pasted list of names/target_ids.
• Prefer a two-step workflow for risky changes: first list grouped interface names with short details such as method, path, Apipost status, target_id when known, and proposed action; then let the user paste the chosen names/ids and the next action.

For allowed writes:

• Explain the exact host, endpoint, project_id, target_id if present, and operation.
• Before the first write in a skill run, identify the write allowlist: project IDs explicitly supplied by the user at skill start, plus any project IDs created during this skill run.
• Refuse writes to projects outside that allowlist. Do not broaden the allowlist just because the token can read or list a project.
• Use dry-run or payload preview first unless the user explicitly asks to execute immediately.
• Require an explicit confirmation flag or explicit user confirmation before execution.
• Keep response bodies concise; save large JSON to a scratch file only when useful and never include tokens.

For blocked writes, refuse briefly and offer the nearest read-only inspection or project-internal target alternative.

Workflow

1. Identify whether the request is read, allowed write, or blocked write.
2. Check required inputs before any task work for project-dependent Apipost tasks. If a token or required project_id is missing, stop and ask for it before local scanning or API calls.
3. Read references/capability-matrix.md if endpoint selection is uncertain.
4. For allowed writes, read references/payload-guidance.md.
5. Use scripts/apipost_v8.py when it covers the operation; otherwise make a direct HTTP call following the same token and safety rules.
6. Treat Apipost response code == 0 as success. If transport fails, JSON parsing fails, or code != 0, stop and report the concrete reason.
7. For project-internal APIs, preserve Apipost target payload structure. Prefer reading an existing target detail and modifying only requested fields instead of inventing a full payload from memory.
8. For new HTTP API targets, use save-http-api or references/http-api-template.json; do not send thin hand-built payloads.
9. For Java/Spring imports, use Chinese folder/API names when available and follow references/spring-import-notes.md.
10. Before writing API URLs, use env-list to inspect existing environments and servers. Do not save local simulation prefixes such as http://127.0.0.1:18080 into API targets. Save relative paths such as /api/health; use send-and-save-response --base-url only for local response capture.
11. When an API synchronization task needs a runtime environment and the expected environment or service is missing, do not create it automatically. Report the missing environment/service and propose the exact environment changes that would be needed, including environment name, service names, service URLs, target folder/server bindings if relevant, host, project_id, and endpoints that would be called. Stop there until the user explicitly asks to create or update those environments/services. Keep documented API targets relative; store runtime host prefixes in environments, not in API URLs.
12. For code-to-Apipost synchronization, separate actions into read-only comparison, creation of missing interfaces, and modification of existing interfaces. Do not combine these stages unless the user has already seen and explicitly selected the exact interfaces to modify.
13. When saving response examples, first inspect the code and/or existing response body to generate response field descriptions. For every JSON response field whose meaning is clear, pass --response-description key=description to send-and-save-response; for nested object or array fields use dotted keys such as items.id. If no reliable description can be generated for a field, leave only that field blank and report the reason. This step is mandatory and is part of response-example completion, not an optional polish pass.
14. After creating new HTTP API targets, read back target-ids and report the created folders/APIs. Unless the user already explicitly asked to call APIs and save response examples in the same request, the final response must include a separate section titled Response Example Next Step with an explicit question asking whether to call the created interfaces and save response.example[0].

Mandatory Post-Creation Gate

When a turn creates HTTP API targets but does not also save response examples, end the final user-visible response with:

• Response Example Next Step
• A direct yes/no question, for example: "Do you want me to call these newly created interfaces now and save successful response examples?"
• The recommended mode: safe mode or full mode.
• The runtime-only base URL(s) required for send-and-save-response.
• A short side-effect note for create-like, update-like, delete-like, or unknown-risk endpoints.
• For delete/cancel endpoints, state whether a matching create endpoint exists; if not, say that a disposable ID or manually prepared resource is required.

Do not replace this gate with a passive sentence such as "response examples were not saved."