openxiangda 1.0.155 → 1.0.157

package/openxiangda-skills/skills/openxiangda-open-api/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: openxiangda-open-api
+description: "Build or maintain external backend and third-party system integrations against the private low-code platform DingTalk-compatible Open API. Use for /dingtalk-api/v1.0, AK/SK, appKey/appSecret, x-acs-dingtalk-access-token, backend token caching, OpenAPI contract lookup, organization sync, external form/workflow calls, or one-time Open API credential management."
+---
+
+# OpenXiangda Open API
+
+Use this skill only for external backend services and third-party integrations. Keep normal OpenXiangda CLI, workspace, page, form, workflow, automation, and App Function development on `/openxiangda-api/v1` with the logged-in user's token.
+
+## Required workflow
+
+1. Inspect the target backend's language, HTTP client, configuration system, deployment model, and existing secret store.
+2. Run `openxiangda open-api spec list --search <keyword> --json`, then `openxiangda open-api spec describe <operationId|path> --method <method> --json`. Implement the exact request and response schemas returned; do not guess DTO fields or unwrap shapes.
+3. Read [references/backend-authentication.md](references/backend-authentication.md) before adding credentials or token code.
+4. Reuse an existing API credential when the user identifies one. Otherwise list credentials first. Create, update, or rotate only after explicit user authorization and only with a platform-admin profile.
+5. Hand AK/SK directly to the backend's approved secret store. Never persist them in OpenXiangda profile or workspace state.
+6. Implement token acquisition and caching inside the backend application. OpenXiangda must not cache or renew the backend's Open API token.
+7. Add contract tests for request serialization, business-envelope errors, token expiry, one retry after 401, and concurrent refresh behavior.
+
+## Contract lookup
+
+Prefer the CLI index so the 15,000-line specification is not loaded wholesale:
+
+```bash
+openxiangda open-api spec tags --json
+openxiangda open-api spec list --tag "表单与菜单" --json
+openxiangda open-api spec list --search submitFormData --json
+openxiangda open-api spec describe /dingtalk-api/v1.0/forms/submitFormData --method post --json
+```
+
+The bundled source contract is [references/dingtalk-api.openapi.json](references/dingtalk-api.openapi.json). Read or query it directly only when the CLI view is insufficient.
+
+## Credential management
+
+Use the normal OpenXiangda login token only for the platform-admin management API:
+
+```bash
+openxiangda open-api credential list --profile dev --json
+openxiangda open-api credential get <id> --profile dev --json
+openxiangda open-api credential create --name "Backend Integration" --profile dev --yes --show-secret --json
+openxiangda open-api credential update <id> --description "..." --profile dev --json
+openxiangda open-api credential rotate-secret <id> --profile dev --yes --show-secret --json
+```
+
+- Treat create, update, and rotation as live platform writes. Obtain explicit authorization first.
+- Keep secrets redacted unless performing an authorized handoff to the backend secret store.
+- Stop on a platform-admin permission error. Do not bypass it and do not ask the user to paste AK/SK into chat.
+- Do not treat the API application's `permissions` or `ipWhitelist` fields as enforced authorization. The current middleware authenticates the access token and tenant; use network controls and backend authorization independently.
+
+## Backend rules
+
+- Build the service base as `<platform-origin>/service`; call `/dingtalk-api/v1.0` beneath it.
+- Keep AK/SK and access tokens server-side. Never put them in browser bundles, mobile apps, public runtime config, source control, logs, traces, or error payloads.
+- Exchange AK/SK at `POST /dingtalk-api/v1.0/oauth2/accessToken`; send the returned token as `x-acs-dingtalk-access-token`.
+- Cache until shortly before `expireIn`, single-flight concurrent refreshes, and retry one time after a 401 with a newly acquired token.
+- Inspect both HTTP status and the endpoint's documented business response. Most endpoints use `{ code, message, data }`, the token endpoint does not on success, and workflow callback success may use `code: 0`.
+- Supply `userId`, `systemToken`, `appType`, or other actor/application context only when the selected operation schema requires it.

package/openxiangda-skills/skills/openxiangda-open-api/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "OpenXiangda Open API"
+  short_description: "External backend API contracts and AK/SK workflows."
+  default_prompt: "Use $openxiangda-open-api to implement a secure backend integration with the private low-code platform Open API."

package/openxiangda-skills/skills/openxiangda-open-api/references/backend-authentication.md

@@ -0,0 +1,63 @@
+# Backend authentication and token lifecycle
+
+## API selection
+
+- Use `/openxiangda-api/v1` for OpenXiangda CLI and low-code app development with a normal platform-user token.
+- Use `/dingtalk-api/v1.0` for an external backend or third-party system that owns an AK/SK credential.
+- Resolve a copied root, `/platform`, or `/view` URL to `<origin>/service` before appending either API namespace.
+
+## Create or retrieve AK/SK
+
+The API application management endpoints are platform-admin APIs authenticated by the current OpenXiangda profile's normal Bearer token. They are not part of `/dingtalk-api/v1.0`:
+
+| Operation | Request | Secret behavior |
+| --- | --- | --- |
+| `GET /api/dingtalk-apps` | no body | lists IDs and AKs; never returns SK |
+| `POST /api/dingtalk-apps` | `{ name, description?, permissions? }` | creates and can return AK/SK |
+| `GET /api/dingtalk-apps/:id` | no body | detail can return the existing AK/SK |
+| `POST /api/dingtalk-apps/:id` | `{ name?, description?, permissions? }` | updates metadata; no SK |
+| `POST /api/dingtalk-apps/:id/regenerate-secret` | `{}` | invalidates the old SK and returns the new one |
+
+Prefer the `openxiangda open-api credential ...` wrappers. They redact `appSecret` unless `--show-secret` is explicit and never store it locally. Creation requires `--yes`; rotation requires both `--yes` and `--show-secret`.
+
+The authenticated user must be a platform administrator. If the platform reports a permission failure, stop and ask an administrator to perform or authorize the operation. Never bypass the permission check.
+
+## Exchange AK/SK for an access token
+
+Send JSON to the service base:
+
+```http
+POST /dingtalk-api/v1.0/oauth2/accessToken
+Content-Type: application/json
+
+{"appKey":"ak_...","appSecret":"sk_..."}
+```
+
+Success:
+
+```json
+{"expireIn":7200,"accessToken":"..."}
+```
+
+Invalid credentials and internal errors use a different business shape such as `{ "code": 40014, "message": "..." }`, potentially with an HTTP 2xx status. Accept the exchange only when a non-empty `accessToken` and positive `expireIn` are present.
+
+## Backend token provider
+
+Implement the following behavior in the target backend's native stack:
+
+1. Read AK/SK from its environment/secret manager at process startup; never accept them from an end-user request.
+2. Return a cached token while it remains outside a five-minute refresh window.
+3. Use a single-flight promise or lock so concurrent requests share one exchange.
+4. For multiple backend instances, place token state in the existing shared cache when available; otherwise allow each instance to maintain its own token.
+5. Record `expiresAt = acquiredAt + expireIn`; do not assume a fixed lifetime even though the current server commonly returns 7200 seconds.
+6. Send protected calls with `x-acs-dingtalk-access-token: <token>` and `Content-Type: application/json`.
+7. On HTTP 401, invalidate the cached token, exchange once, and retry the original request once. Do not loop.
+8. Reject a protected response when its documented business code indicates failure even if HTTP status is successful.
+
+Never log the AK, SK, access token, Authorization header, token exchange body, or unredacted credential-management response.
+
+## Current security boundary
+
+The current authentication middleware validates the access token, token expiry, API-app active state, and tenant. If a request body contains `userId`, it also resolves that platform user as the operation context.
+
+Do not rely on the API-app `permissions` array or `ipWhitelist` column as active route authorization or network enforcement. Apply least privilege through platform user/application permissions, backend business authorization, deployment-network policy, and secret rotation.