fanwei-e10-api-doc/SKILL.md

name, description

name	description
fanwei-e10-api-doc	为泛微 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.