# 项目注册与能力资产

## 定位

项目注册与能力资产是睿池 ReachAI 的入口层。历史系统可以通过平台扫描接入，可改造系统优先通过 `ai-spring-boot-starter` 主动注册。两条路径最终都进入项目、实例、能力快照、Tool/Capability 目录和评审流程。

## 当前已落地

### 接入路径

| 路径 | 适用对象 | 当前实现 |
| --- | --- | --- |
| 平台扫描 | 历史系统、PoC、无法改造项目 | `ScanProjectController`、`ScannerController`、`scan_project`、`scan_project_tool` |
| SDK 主动注册 | 新系统、可改造业务系统 | `EafRegistryClient.registerAndSync()`、`AiRegistryController`、`ai_project_instance` |
| SDK 图同步 | 由业务代码声明或生成的 Agent 图 | `EafRegistryClient.syncAgentGraphs()`、`/api/registry/projects/{projectCode}/agent-graphs/sync` |
| 手工维护 | 平台内创建 Tool 或 Capability | `ToolController`、`SkillController`，其中 `/api/capabilities` 是推荐产品入口 |

### SDK 契约

`ai-skill-sdk` 提供能力声明和运行时基础接口：

- `@AiCapability`：声明业务方法或 Controller 方法可作为 Agent 能力。
- `@AiParam`：补充参数语义、示例、来源和约束。
- `@AiOutput`：声明返回字段是否可被后续节点引用。
- `AiTool` 与 `ToolRegistry`：框架无关的工具注册和执行接口。
- `AiSkill`、`SkillKind`、`SkillMetadata`：代码名保留 `Skill` 是兼容历史，产品语义应写作 Capability。

`ai-spring-boot-starter` 提供接入自动化：

- `EafRegistryProperties` 使用 `eaf.registry`、`eaf.project`、`eaf.capability` 配置。
- `EafCapabilityScanner` 基于 Spring MVC Mapping、`@AiCapability`、`@AiParam` 和请求体反射生成 `EafCapabilityDescriptor`。
- `EafRegistryClient` 调用注册中心接口完成项目注册、实例心跳、能力同步和 SDK 图同步。
- `EmbeddedRuntimeEndpoint` 暴露 `/eaf/runtime/embedded/execute`，为嵌入式 Runtime 调度预留入口。

### 注册中心接口

`AiRegistryController` 的当前关键接口：

- `POST /api/registry/projects/register`：注册项目和接入凭证。
- `POST /api/registry/projects/{projectCode}/instances/heartbeat`：业务实例心跳。
- `POST /api/registry/projects/{projectCode}/instances/offline`：实例下线。
- `POST /api/registry/projects/{projectCode}/capabilities/sync`：同步能力快照。
- `POST /api/registry/projects/{projectCode}/agent-graphs/sync`：同步 SDK 图。
- `POST /api/registry/projects/{projectCode}/capabilities/diff`：生成字段级差异。
- `POST /api/registry/projects/{projectCode}/capabilities/apply`：应用评审结果。
- `GET /api/registry/projects/{projectCode}/capability-snapshots` 和 `GET /api/registry/capability-snapshots/{snapshotId}/diff-items`：查看快照与差异。

管理端对应 `RegistryProjectList.vue`、`RegistryProjectDetail.vue`、`CapabilitySyncDebug.vue`。

### 能力资产模型

`tool_definition` 是当前统一能力表：

- `kind='TOOL'` 表示原子 Tool。
- `kind='SKILL'` 是历史字段名，产品文档中应理解为粗粒度 Capability。
- `skill_kind` 区分 SubAgent、Interactive Form 等能力形态。
- `capability_metadata_json` 保存 `@AiCapability`、`@AiParam` 等声明元数据。
- `project_id`、`project_code`、`visibility`、`qualified_name` 用于项目隔离和稳定引用。
- `side_effect` 描述副作用等级，供 Studio 发布、Tool ACL 和运行护栏使用。
- `spec_json` 保存粗粒度 Capability 的专属执行配置。

扫描阶段的 `scan_project_tool` 是项目内接口资产，只有 promote 或同步应用后才进入全局 `tool_definition`。`removed_from_source` 和 `removed_at` 用于记录源代码或 OpenAPI 中已经消失但仍可能被全局能力引用的墓碑行。

### 语义和图谱补强

扫描接入不是终点。当前系统已经把语义文档和接口图谱接入项目资产：

- `SemanticDocController` 维护项目、模块、接口级 `semantic_doc`，用于让 Agent 看懂接口含义。
- `ApiGraphController` 维护 `api_graph_node`、`api_graph_edge`、`api_graph_layout`，支持候选边确认、参数来源提示和画布布局。
- `ScanProjectController` 提供扫描、重扫、差异摘要、敏感数据扫描、接口测试、promote/unpromote/push-to-global 等操作。

## 仍待补齐

- `tool_definition.kind='SKILL'` 和 `skill_kind` 是历史存储名，短期不改库表，但新文档、前端文案和新接口应继续收敛到 Capability 语义。
- 稳定引用 `tool_refs_json`、`skill_refs_json` 已进入 `agent_definition`，仍需持续替换只按裸 `name` 引用的旧路径。
- SDK 能力同步已具备快照和差异表，但真实业务下的评审策略、冲突处理和回滚体验还需要继续产品化。
- 扫描链路和 SDK 链路都能进入能力目录，后续需要更明确的优先级：新系统优先 SDK，历史系统保留扫描。