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.