it235/multica-best-practices/multica-platform-apifox

Platform · Apifox

Platform 协作

本 skill 为 platform 层；供 multica-artifact-backend、multica-test-t1-design、multica-test-t3-api-automation 等按名调用。凭据：APIFOX_ACCESS_TOKEN。

Purpose

Apifox 读 + 写统一能力，供 @Tester / @BackendDev / @FrontendDev 按名挂载：

跨平台：Node 脚本 + Python runner；npm install -g apifox-cli。私有化基址见 config.yaml → api_base_url（默认 https://apifox.example.com）。

Files

multica-platform-apifox/
├── SKILL.md
├── config.yaml
├── .env.example
├── references/
│   ├── supplement-workflow.md
│   ├── reference.md
│   ├── agent-instructions.md
│   └── CHANGELOG.md
├── tests/                        # node --test tests/*.test.js
├── .apifox/
│   └── systems-registry.example.json
└── scripts/
    ├── sync_openapi.js           # OpenAPI 导入 + 打标 + 删 orphan
    ├── run_apifox.py             # T3 场景/套件跑批
    ├── lib/apifox.js             # CLI JSON 封装
    ├── systems-registry.js       # 系统名 ↔ projectId 登记
    ├── discover-auth.js
    ├── discover-scenario-target.js
    ├── generate-cases.js
    ├── append-to-scenario.js
    ├── safe-update-case.js
    └── validate-config.js

凭据

Write · OpenAPI 同步（Backend / FE 契约）

Backend 发布 openapi.json（或从 api-contract.md 导出）后：

npm install -g apifox-cli
set APIFOX_ACCESS_TOKEN=<token>
set APIFOX_PROJECT_ID=<projectId>
 
node scripts/sync_openapi.js \
  --file docs/backend/<ISSUE-KEY>/openapi.json \
  --issue <ISSUE-KEY> \
  --tag <ISSUE-KEY> \
  --branch ai/<ISSUE-KEY>-openapi-<YYYYMMDD> \
  --json

分支（强制）：每次 OpenAPI 同步须 新建 AI 分支，禁止直写 main。完整步骤见 `references/openapi-branch-workflow.md`。

行为：

1. 导入 — apifox import --format openapi（增/改）
2. 打标 — 对 OpenAPI 内每条 path+method 匹配 endpoint，endpoint update --tags 追加 Issue tag
3. 删除 — 导出带该 tag 的 endpoint，与本次 OpenAPI 对比，多余者 endpoint delete（仅删带该 tag 的 orphan）

回传 JSON：imported / tagged / deleted / errors。

Write · 接口场景补充（Tester T1 并行）

完整步骤见 references/supplement-workflow.md；断言/错误见 reference.md；Agent 指令见 references/agent-instructions.md。

回归测试：node --test tests/*.test.js（见 tests/README.md）。

要点：

• 任务卡片对齐 projectId / 环境 / 接口 / 写入意图
• systems-registry.js lookup 解析项目
• 禁止 patch 修改 path/method/apiDetailId
• 场景挂载：同一 endpoint 默认 append-existing，不重复建场景
• T3 跑批走 run_apifox.py，不在本 skill 出 PASS/FAIL 验收结论

Run · T3 自动化

pip install -r scripts/requirements.txt
python scripts/run_apifox.py \
  --issue AAI-2466 \
  --base-url "https://sit.example.com" \
  --json

multica-test-t3-api-automation 薄编排调用本脚本；配置见 config.yaml（scenario / environment 映射）。

Read

apifox endpoint list --project <id> --access-token <token>
apifox test-scenario list --project <id>

为什么有效

Apifox 能力从角色提示词剥离，测试/后端/前端共用同一 platform skill；OpenAPI 同步与用例补充分轨，避免 supplement 流程误改接口定义。