reachai-onboarding

name

reachai-onboarding

description

Integrate Java business systems with ReachAI SDK registration, SDK instance heartbeat, gateway/embed access, and optional API Management handoff. Use when asked to connect a Spring Boot service to ReachAI, add reachai-capability-sdk or reachai-spring-boot2-starter, configure reachai.registry/reachai.project/reachai.capability, prepare @ReachCapability metadata for later manual SDK sync, or verify SDK onboarding from a ReachAI manifest.

ReachAI Onboarding

Operating Rules

Treat the current business repository as the source of truth. Inspect its Maven modules, Java version, Spring Boot version, configuration files, existing controller/service boundaries, and test commands before editing.

凡是写入 ReachAI 或展示给业务用户的名称、标题、描述、说明、System Prompt、节点名称、审计原因、进度和结果，默认使用清晰的简体中文。不要仅因 API、Schema 或字段名为英文就生成英文业务文案。Token、MCP、AI、Agent、Supervisor、Workflow、Tool、API、SDK 等熟知专业术语，以及 keySlug、toolName、代码、路径、枚举值、协议字段和技术标识可保留英文；必要时使用“中文名称（英文术语）”。不要翻译或改写技术标识。

Never paste, print, or commit the registry app secret. Use the environment variable named by the manifest, normally REACHAI_REGISTRY_APP_SECRET.

ReachAI task handoffs use a one-time activation code. Activate it once, keep the returned short-lived task token only in the current process, and call /api/ai-coding/tasks/{taskId}/** with Authorization: Bearer <taskToken>. Never reuse a project-level aiCodingKey on task protocol routes.

Separate project/Workflow AI Coding APIs under /api/ai-coding/projects/** and /api/workflows/**/ai-coding/** can still use the explicit project aiCodingKey when the user independently supplies one. Send it as X-ReachAI-AiCoding-Key; never put it in a URL, browser bundle, task artifact, or progress event.

Prefer minimal, reviewable changes:

• Add ReachAI dependencies only to the modules that need them.
• Put reachai-spring-boot2-starter in the runnable Spring Boot application module.
• Put reachai-capability-sdk in modules that declare @ReachCapability methods or DTO field metadata.
• @ReachCapability is method-level, @ReachParam is parameter/field-level, and @ReachOutput is field-only on response DTO fields. Do not put @ReachOutput on methods.
• Do not use the ReachAI platform base URL as a Maven repository or npm registry. Manifest/skill/self-check URLs are not Maven/npm repositories.
• Unique recommended Java SDK install (no ReachAI source checkout): read the absolute Java entries in the onboarding manifest's sdkArtifacts, expand {skillExtractDir} in each installCommandTemplate, and run reachai-capability-sdk before reachai-spring-boot2-starter. The bundled scripts/install-java-sdk.ps1 downloads the declared JAR and standalone consumer POM, verifies both declared SHA-256 values, and installs that exact coordinate into the business system's Maven local repository. Fail if a URL or hash is absent or mismatched; do not guess another URL and do not require access to the ReachAI repository.
• Unique recommended Embed SDK install (no ReachAI source checkout): read sdkArtifacts for @reachai/embed-chat, extract this Skill zip anywhere, then run the expanded installCommandTemplate from the business frontend directory that contains package.json. The bundled scripts/install-embed-chat.mjs verifies integritySha256, copies the tgz to the stable repo-local vendor/reachai/ directory, replaces the exact installed package directory, and records .reachai-artifact-sha256. Re-run this installer whenever a SNAPSHOT artifact checksum changes; npm install --force alone does not prove that a same-version file dependency was refreshed. reachai-doctor --mode static reports EMBED_SDK_ARTIFACT_MATCH. Never run npm install directly against a temporary Skill extract path, and never leave %TEMP%, .cursor, .trae or another machine-specific absolute path in package.json / lockfiles. Authenticated downloadUrl needs auth headers that npm cannot send, so prefer this Skill-bundled installer.
• Do not invent dependency download paths such as /repository/**, /maven/**, /repository/maven/**, /api/embed/sdk, or /npm/**. Do not use cd ai-admin-front && npm run build:sdk as the business-project install path.
• Gateway checklist is a top-level gatewayChecklist object list on the onboarding manifest (id, description, required, verificationHint, failureImpact). See references/java-sdk-access.md.
• Avoid changing unrelated business logic, package structure, formatting, or dependency versions.
• SDK onboarding must not scan or sync business APIs on application startup. After compile, registration and heartbeat succeed, an active ReachAI PROJECT_ONBOARDING task may explicitly trigger exactly one audited SDK sync with POST <taskRoot>/verifications/SDK_SYNC; the task token scopes that operation to its own project. The equivalent console action remains API Management（API 管理）手动触发的 SDK 同步. Restrict both paths to business-owned packages and never include framework, platform, third-party, starter, or shared infrastructure controllers as business APIs.

Workflow

1. If the prompt is a ReachAI task handoff, activate the one-time code and read GET <taskRoot>/context first. Otherwise read the explicitly supplied onboarding manifest URL.
2. Download this skill package if it is not already installed, then read the reference files only as needed.
3. Detect the project layout:
   • Maven root and child modules.
   • Java source level.
   • Spring Boot version.
   • Runnable application module.
   • Business-owned Java base packages from application classes, controllers, services, and module names, as the explicit SDK sync boundary.
   • Framework/platform packages that must be excluded from task-scoped or API Management SDK sync.
   • Existing application.yml, bootstrap.yml, profile-specific config, or config-center conventions.
   • Existing Spring Security, Sa-Token, Shiro, custom login interceptors, CSRF rules, gateway routes, and ingress/firewall boundaries that can affect the inbound SDK sync callback.
4. Resolve and add dependencies using the manifest sdkArtifacts, references/java-sdk-access.md, and templates/pom-dependencies.xml. Platform artifact links are the default when no corporate Maven publication exists.
5. Add configuration using templates/application-reachai.yml. Do not add any capability startup-sync setting. Replace package placeholders only when preparing the explicit SDK sync boundary. Set reachai.project.base-url to an address reachable from the ReachAI server; use localhost, 127.0.0.1, or ::1 only when ReachAI and the business service actually share the same host or network namespace.
6. Do not scan or sync APIs at application startup. Only when the user explicitly asks to prepare API metadata, select one or two low-risk query-style business methods and annotate them with @ReachCapability / @ReachParam. Use templates/reach-capability-example.java only as a style example.
7. Inspect the business gateway boundary before declaring onboarding complete:
   • Spring Cloud Gateway, Nginx, backend-for-frontend, or front-end dev proxy configuration.
   • Existing authentication headers and current-user extraction.
   • Whether a server-side token broker already exists.
   • Whether ReachAI can send POST /reachai/registry/capabilities/sync to the Starter service through the configured base-url and context-path.

• Interpret the platform SDK self-check separately: CODE_READY requires observed Starter registration, RUNTIME_READY requires a fresh instance heartbeat, and SDK_CALLBACK_READY requires a successful signed callback plus a received capability snapshot.
• For an active task handoff, after CODE_READY and RUNTIME_READY are observed, explicitly call POST <taskRoot>/verifications/SDK_SYNC with the task Bearer token. No body is required. This operation is project-scoped, succeeds only for a RUNNING onboarding task, and writes a verification event back to the task.
• For a non-task manifest flow, use the API Management manual SDK sync action; do not invent project-key or public trigger endpoints.
• The SDK self-check does not prove browser acceptance. Task readiness E2E_READY remains pending until ReachAI observes an authorized Embed session, user message and assistant reply created after the current task started. The session may come from the real browser SDK or from reachai-doctor --mode e2e using a business-supplied test Authorization/Cookie; doctor never mints or mocks the business identity. This proves only the authorized conversation protocol: declared Workflow capability nodes and Page Actions need their own exact-Trace / real-browser evidence in the Page Workbench. Final launcher visibility and interaction quality remain user acceptance items.
• A computed SDK sync callback target is not proof of connectivity. The actual task-scoped or API Management sync must distinguish unreachable host/timeout, business-auth or CSRF 401/403, route/context-path 404/405, and Starter signature rejection.

12. For a task handoff, follow protocolGuide.eventStateRules and write real STARTED / PROGRESS events to the current task. While the task is WAITING_USER, you may report work that does not depend on the answer with PROGRESS; it preserves WAITING_USER and every open question. Submit blocking ambiguities through /questions, poll for the user's answer, then write RESUMED only after all answers have been read. Before submission, run the Bootstrap-provided Test-ReachAiArtifact -Content <artifact-content> local schema check; Send-ReachAiArtifact runs the same check again before posting. Finish by submitting exactly one artifact matching the JSON Schema in task context; never invent success evidence.
13. Report changed files, commands run, results, SDK sync verification status, the observed SDK sync callback target, its route/login/CSRF handling, optional scan package choices, gateway route/token broker status, front-end integration status, and whether the user-scoped secret still needs to be configured.

References

• For exact Java SDK signatures, read references/java-sdk-api-reference.md; then use references/java-sdk-access.md for placement, configuration and runtime boundaries.
• For platform API contracts, read references/platform-apis.md.
• For browser SDK public types and the minimal integration, read references/embed-chat-quick-reference.md.
• For Spring Cloud Gateway, Nginx and Kong authentication boundaries, read references/gateway-examples.md and reuse the copy-ready files under examples/gateway/.
• For credential handling and prompt safety, read references/security.md.
• For Page Bridge and action safety, read references/page-action-contract.md.
• For Angular Page Action integration, read references/angular-page-action.md.
• For ready-to-copy snippets, use files under templates/.
• For an optional local verification helper, run scripts/verify-reachai-access.py.
• For layered static/runtime onboarding diagnostics, run node scripts/reachai-doctor.mjs --mode static --business-root <repo> and then node scripts/reachai-doctor.mjs --mode runtime --manifest-url <onboardingManifestUrl> after services are available. For /api/ai-coding/projects/**, put the project AI Coding key in the current process environment variable REACHAI_AI_CODING_KEY; never pass the key as a command-line argument. Use --ai-coding-key-env <name> only when the repository already uses another secret environment variable name.
• For non-interactive authorized conversation verification, let the business system provision a least-privilege test account/token outside ReachAI. Put the complete business Authorization value in REACHAI_E2E_AUTHORIZATION or the business Cookie header in REACHAI_E2E_COOKIE, then run node scripts/reachai-doctor.mjs --mode e2e --broker-url <business-origin>/api/reachai/embed-token --embed-api-base <business-origin>/api/reachai/embed --agent-id <provisioned-key-slug> --page-key <page-key> --route <route>. Never put authorization values on the command line or into task events/artifacts. EMBED_CONVERSATION_E2E=PASS proves only the authorized broker/proxy/session/message protocol; doctor deliberately leaves WORKFLOW_CAPABILITY_E2E and PAGE_ACTION_BROWSER_E2E as PENDING until real intent and real browser evidence are available. It does not prove launcher visibility.

Output Contract

End with:

• Files changed.
• Dependency/configuration summary.
• Gateway route and embed token broker summary.
• Front-end embed/chat integration summary.
• SDK sync verification/API Management handoff status and any optional capability annotations prepared.
• Verification commands and results.
• Whether REACHAI_REGISTRY_APP_SECRET still needs to be configured outside the repository.
• Task id, whether progress/questions were written back, and the submitted artifact key.