reachai-onboarding

# 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 bou