fanwei-e10-api-doc/SKILL.md

---
name: fanwei-e10-api-doc
description: 为泛微 OA E10 OpenAPI 集成生成面向外部开发者的 Markdown API 文档。当用户要求编写 E10 接口文档时使用，尤其适用于以下场景：创建流程实例、发现流程表单字段、提取 E10 OpenAPI 文档、编写 OAuth2 `access_token` 获取流程说明，或基于 E10 系统产出可供开发者直接使用的 API 文档。
---

# Fanwei E10 API Documentation

Use this skill to create developer-facing Markdown API documentation for 泛微 OA E10 OpenAPI integrations. Focus on external system developers: how to authenticate, which endpoint to call, what parameters to send, how workflow form fields map to request payloads, and how to handle responses.

## Hard boundary: read-only operation

Never modify the E10 system while using this skill.

Allowed actions:
- Navigate pages, view content, take screenshots, and extract rendered text.
- Use authenticated browser-session read calls to retrieve workflow, form, and field metadata.
- Inspect E10 OpenAPI documentation pages.
- Generate documentation outside the E10 system.

Forbidden actions:
- Create, update, delete, publish, enable, disable, submit, approve, or reject any workflow, form, system object, or business data.
- Call any endpoint or UI action that changes E10 configuration or data.
- Save credentials to memory, files, logs, examples, or final documentation.

If an endpoint or UI action might write data, stop and ask the user before continuing.

## Required inputs

Before accessing E10, collect or confirm:
- E10 base URL, expressed as `https://<E10_BASE>` in final documentation.
- Login account and password for the current task only.
- Target documentation type: general E10 OpenAPI documentation or workflow-instance API documentation.
- Target workflow name when documenting workflow instance creation.
- Desired output location and filename if the user cares; otherwise save as `E10_<workflow-or-api-name>_API.md`.

Do not reuse cached credentials. Do not expose real IPs, real credentials, real tokens, internal IDs, database names, or internal API paths in the final external-facing document unless the user explicitly requests an internal-only diagnostic note.

## Workflow decision tree

1. Determine whether the request is for a general E10 API or for creating a workflow instance.
2. If the task needs live E10 inspection, read `references/login-and-browser-harness.md` and log in through an isolated browser session.
3. For OpenAPI documentation pages, read `references/openapi-doc-navigation.md` and extract rendered documentation text.
4. For workflow-instance documentation, read `references/workflow-field-discovery.md` and use the internal read-only API chain described in `references/internal-apis.md` to discover workflow, form, and field metadata.
5. If the API involves attachments, read the file-upload section in `references/openapi-doc-navigation.md` and include an upload prerequisite section.
6. Generate the final Markdown using `assets/templates/e10-api-doc-template.md`.
7. Validate the output with `references/output-document-standard.md` and `evals/test-cases.md` before presenting or saving it.
8. If live access fails, provide the missing inputs or evidence needed instead of inventing field definitions, endpoint details, owners, dates, IDs, or examples.

## External documentation rules

The final output must be written for external integration developers, not E10 administrators.

Always include:
- OAuth2 `code` to `access_token` flow.
- A clear statement that `access_token` is passed as a request-body parameter, not as an HTTP Bearer header.
- Identity mapping guidance: `userType`, `deptType`, and field-level `dataOptions` for employee, department, subcompany, file, and related object fields.
- Request URL, method, content type, request parameters, request examples, response parameters, response examples, and error codes.
- At least two `curl` examples when documenting workflow creation: a minimal request and a full request.
- Workflow field tables grouped by business meaning, not by internal E10 UI group names.

Never include in the external-facing document:
- Real E10 hostnames or IP addresses; use `https://<E10_BASE>`.
- Credentials, session cookies, real tokens, app secrets, or screenshots.
- E10 version numbers, internal document page IDs, internal API paths, database table names, `columnName`, or management UI instructions.
- Internal troubleshooting notes, browser-harness commands, XHR interception details, or generation timestamps.
- Informal warning labels such as “坑”, “注意”, “陷阱”, or “提示”; convert them into formal parameter notes or constraints.

## Resource guide

Use these bundled resources as needed:

- `references/login-and-browser-harness.md`: isolated browser startup, login, captcha handling, session safety, cleanup.
- `references/openapi-doc-navigation.md`: how to navigate rendered E10 OpenAPI docs and distinguish similar API names.
- `references/workflow-field-discovery.md`: workflow lookup, form lookup, field extraction, main/detail table handling.
- `references/internal-apis.md`: read-only internal API chain for workflow/form/field metadata.
- `references/output-document-standard.md`: final documentation quality rules and field mapping conventions.
- `references/troubleshooting.md`: common failures and recovery steps.
- `assets/templates/e10-api-doc-template.md`: output skeleton for generated Markdown API documentation.
- `examples/`: sanitized examples showing prompt, extracted metadata, and expected output style.
- `evals/test-cases.md`: trigger and quality checks for maintaining this skill.

## Completion checklist

Before finishing, verify:
- The document is usable without access to E10 management pages.
- All URLs use `https://<E10_BASE>`.
- Authentication is complete and accurate.
- Request examples use external identifiers, such as job number and department code, rather than internal E10 IDs.
- No internal API path, database table name, session value, screenshot path, or version number appears in the final document.
- Field names, types, required flags, and examples are derived from actual documentation or explicit user-provided metadata.
- Missing or uncertain information is marked as “需确认” rather than fabricated.