w8123/enterpriseagentframework/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. Console users trigger SDK sync from the project's 业务能力 → 接入与变更. 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 console 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.

1. 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.
2. 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.
3. 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.
4. 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.

1. Add or update the gateway route/token broker:

• Route ReachAI capability traffic to the business service and preserve X-ReachAI-Invocation-Token, X-ReachAI-Trace-Id, X-ReachAI-Run-Id, and the business identity headers required by the service.
• If reachai.project.base-url points to a gateway or ingress, route /reachai/registry/** to the business service that contains reachai-spring-boot2-starter. Preserve X-ReachAI-App-Key, X-ReachAI-Timestamp, X-ReachAI-Nonce, and X-ReachAI-Signature.
• Let POST /reachai/registry/capabilities/sync bypass normal business login/JWT filters and CSRF so the request reaches the Starter controller. Apply the equivalent exclusion for Spring Security, Sa-Token, Shiro, or custom interceptors. Do not remove authentication from the endpoint: the Starter must still validate the ReachAI registry signature and return 401 for invalid requests.
• Treat this callback as server-to-server traffic. CORS is irrelevant; restrict network exposure to the ReachAI service or trusted network when infrastructure supports it.
• Expose a front-end token endpoint such as /api/reachai/embed-token.
• Implement the token endpoint server-side with the Starter-provided ReachAiEmbedTokenClient. Business code maps the current authenticated user to ReachAiEmbedPrincipal and forwards the SDK-owned page identity; the client owns project signing, transport, and wrapped data.token parsing.
• Keep /api/reachai/embed-token on the normal business login token path. It reads the current business user and exchanges that identity for a ReachAI embed token.
• Add the gateway authentication whitelist or dedicated security chain for /api/reachai/embed/**. This path carries ReachAI embed tokens, so business OAuth/JWT filters must not validate it as a business login token; forward Authorization: Bearer <embedToken> unchanged to ReachAI.
• In Spring Security WebFlux / OAuth2 Resource Server, permitAll() on /api/reachai/embed/** is not enough by itself: the resource server can still try to authenticate the Bearer <embedToken> before routing and return 401. Add a higher-priority SecurityWebFilterChain with securityMatcher(ServerWebExchangeMatchers.pathMatchers("/api/reachai/embed/**")) that permits all and does not enable oauth2ResourceServer() for that matcher.
• Inspect whitelist/anonymous filters that remove or rewrite JWT headers, such as IgnoreUrlsRemoveJwtFilter, RemoveJwtFilter, RemoveRequestHeader=Authorization, or security filters that call mutate().header("Authorization", ""). Do not apply that header-clearing behavior to /api/reachai/embed/**; skipping business authentication must still preserve the embed token Authorization header.
• If Spring Cloud Gateway proxies /api/reachai/embed/**, dedupe duplicate CORS response headers when both the gateway and ReachAI write them. A typical route filter is DedupeResponseHeader=Access-Control-Allow-Origin Access-Control-Allow-Credentials, RETAIN_FIRST.
• For a task handoff, use domainContext.implementationGuidance.projectCopilotKeySlug as the front-end agentId; ReachAI Control owns idempotent Agent/Supervisor provisioning before handoff. Do not request a project key from the user or call project-key provisioning APIs from the task.
• For an independently authenticated manifest flow, manifest.agentProvisioning.provisionAgentUrl remains available to an AI coding tool, local shell, or server-side integration. It is idempotent and creates or reuses the project page copilot Agent, selects an active LLM model, and publishes an ACTIVE AgentScope Supervisor config. It does not create a placeholder Workflow.
• When the user asks for another project Agent, Supervisor changes, or Skill binding, download manifest.agentSupervisor.endpoints.skillPackageUrl and follow the agent-ai-coding Skill. Use only the project-key endpoints in that manifest; never call console /api/agents/** or /api/skills/** with an AI Coding key.
• Write only the supplied project copilot key slug into browser configuration. Never write an internal Agent id or any credential.
• Create Workflow drafts only for real business capabilities. Validate and publish each Workflow before adding it through manifest.agentSupervisor.endpoints.workflowToolAttachUrlTemplate; the attach operation publishes the next Agent config version containing that Workflow-as-Tool.
• Workflow attachment is additive by default because one page may legitimately expose several independent tools. To supersede one predecessor, first read the currently attached catalog and send its exact id as replaceWorkflowId; ReachAI removes only that entry and preserves every other Workflow. Never infer replacement from pageKey, name, or display order.
• If a project needs both page operations and explicit API-only queries, publish and attach two tools: a PAGE_ASSISTANT for page behavior and a read-only GENERAL Workflow for the API chain. Agent risk is declared per attached Workflo