spring-explore

预检：Spring MCP

此技能属于 Spring Agent Toolkit，旨在与 Spring MCP 服务（由 Amplicode IntelliJ 插件提供）配合使用。开始前，请检查工具列表中是否有 Spring MCP 工具——这些工具通过 amplicode MCP 服务公开（例如，get_project_summary、list_module_dependencies、get_entity_details）；将 MCP 工具扁平化到工具列表中的运行环境会在相同名称前加上 mcp__amplicode__ 前缀。

• 如果至少有一个 Amplicode 工具可用——MCP 已连接。继续使用以下技能。
• 如果没有可用工具——停止并调用 amplicode-install 技能（随 Spring Agent Toolkit 一同提供）。它会安装 Amplicode 插件，并引导用户点击欢迎屏幕上的 «Настроить Spring Agent» 按钮，然后重启 MCP 客户端。完成后，MCP 工具即可使用——继续此技能。
• 如果技能列表中未注册 amplicode-install，请用用户所用的语言告知用户：“此技能需要 Amplicode IntelliJ 插件及其 MCP 服务。请从 https://amplicode.ru/marketplace 安装到 IntelliJ IDEA Ultimate/Community 或 GigaIDE，打开任意项目，点击 Amplicode 欢迎屏幕上的 «Настроить Spring Agent」，然后重启 MCP 客户端。”

---

探索应用

分步骤 0–6 收集项目的主要上下文。按顺序执行每个步骤—— 每一步都基于前一步的结果。

**重要提示：**如果当前对话中已收集上下文，请勿重复探索——使用已有信息。

---

步骤 0 — 根据用户请求预测涉及范围

告诉用户：Step 0/6: Analyzing request...

此步骤中不要调用任何工具。

阅读用户的请求，并推断实现可能涉及的内容。 不要调用任何工具，根据命名约定、领域语言和典型 Spring Boot 模式进行合理推测：

• 实体——可能涉及哪些领域对象？（例如，“创建订单” → Order、OrderItem）
• Repository——这些实体可能对应哪些 Repository？
• 服务——可能需要哪些服务类？
• 控制器——哪些 REST 控制器可能负责此领域？
• 其他 Bean/组件——映射器、验证器、事件监听器、配置等。
• 文件——可能相关的非 Java 文件有哪些？（例如，数据库迁移脚本、application.properties、Liquibase 变更日志、HTML 模板）。此处不要列出 Java 类——它们属于上述类别。

建立一份初步待补充项列表，仅包含确实需要的内容：

### Predicted involvement:
- Entities: Order, OrderItem, Customer
- Repositories: OrderRepository, CustomerRepository
- Services: OrderService
- Controllers: OrderController
- Other: OrderMapper
- Files: src/main/resources/db/migration/V1__create_orders.sql, application.properties

此预测将指导步骤 1–5——跳过与任务无关的内容。

---

步骤 1 — 确定探索目标并选择路径

告诉用户：Step 1/6: Selecting exploration paths...

此步骤中不要调用任何工具。

阅读当前对话上下文——用户的请求、之前的探索结果和剩余待补充项——并用一句话概括关键探索目标。向用户展示：

### Exploration goal:
Understand the Order aggregate structure and verify what repositories and mappers already exist.

根据此目标，逐一检查以下每条探索路径，并明确决定：纳入或跳过，同时用一句话说明理由。每条路径都必须评估——不要跳过评估本身。 项目结构

• 获取项目摘要——如果需要了解技术栈、Spring Boot 版本或模块结构，则包含此项。如果任务范围仅限于特定类，则跳过。
• 检测持久化技术栈——如果选择了下方任何涉及实体的路径，且对话中尚未确定技术栈（JPA 还是 JDBC），则包含此项。调用 list_module_dependencies：依赖项为 spring-boot-starter-data-jpa / hibernate → JPA；spring-boot-starter-data-jdbc / spring-data-jdbc → JDBC；两者都没有 → 不支持持久化层，跳过涉及实体的路径。
• 列出领域实体——仅当完全不了解领域，且无法预测涉及哪些实体时才包含此项。如果请求中已指明实体，或可根据上下文预测实体，则跳过。不要用它获取实体结构或解析 FQN。
• 列出 REST 端点——仅当需要检查现有端点，以避免重复或了解惯例时才包含此项。如果请求已完整定义所有端点，则跳过。

领域模型

• 获取实体描述——如果需要实体字段或注解，则包含此项。仅针对预测的实体，不要查询所有实体。按技术栈选择：JPA → get_entity_details，参见 references/entity-description.md；JDBC → get_jdbc_entity_details，参见 references/entity-description-jdbc.md。
• 从实体获取深层模型——如果需要遍历多个实体之间的关系（例如嵌套资源、级联），则包含此项。仅限 JPA——对于 JDBC，get_jdbc_entity_details 已返回完整的所属子项树（aggregates）和反向链接（referencedBy）；请改用下方的 DDD 路径。参见 references/deep-model-based-on-jpa.md。
• 从实体获取 DDD 模型——如果聚合边界很重要（例如 URL 设计、级联规划、DTO 构造），则包含此项。JPA：遵循 references/ddd-model-based-on-jpa.md。JDBC：调用 get_jdbc_entity_details 并直接读取 aggregateRootFqn、aggregates、referencedBy——Spring Data JDBC 在框架层面强制执行聚合边界。

持久化

• 获取实体仓库——如果未知预测实体对应的仓库，或需要验证仓库，则包含此项。参见 references/entity-repositories.md。
• 获取实体组件——如果需要全面了解某个实体的所有组件（仓库、服务、控制器），则包含此项。参见 references/entity-components.md。

服务

• 获取实体服务——如果未知预测实体对应的服务，或需要验证服务，则包含此项。参见 references/entity-services.md。

映射器

• 获取实体映射器——如果任务涉及 DTO，且需要了解现有哪些映射器，则包含此项。参见 references/entity-mappers.md。

DTO

• 获取实体 DTO——如果需要了解现有哪些 DTO 类，则包含此项。参见 references/entity-dtos.md。

REST 层

• 获取实体控制器——如果需要查找与某个实体关联的控制器，则包含此项。参见 references/entity-controllers.md。

明确写出评估结果，然后仅根据纳入的路径制定最终计划：

示例——对于请求“添加一个分页端点，返回某位客户的所有订单以及订单项和产品名称”：

### Path evaluation:
- Fetch project summary: INCLUDE — need Spring Boot version and module structure
- Detect persistence stack: INCLUDE — entity-touching paths selected and stack unknown from conversation
- List domain entities: SKIP — Order, Customer, OrderItem, Product are predictable from the request
- List REST endpoints: INCLUDE — need to check if an orders endpoint already exists
- Get entity description: INCLUDE — need Order, OrderItem, Product fields for response DTO design
- Get deep model: SKIP — relationship structure is clear: Order → OrderItem → Product
- Get DDD model: SKIP — no cascade planning needed, just a read endpoint
- Get entity repositories: INCLUDE — need to verify OrderRepository exists and supports pagination
- Get entity components: SKIP — repositories are sufficient, no need for full component chain
- Get entity services: SKIP — no service layer changes expected
- Get entity mappers: INCLUDE — need to know if OrderMapper already exists before creating DTOs
- Get entity DTOs: INCLUDE — need to know if OrderDto already exists
- Get entity controllers: SKIP — will check via "List REST endpoints" instead

### Exploration plan:
1. Fetch project summary
2. Detect persistence stack
3. List REST endpoints (filter to order-related controllers)
4. Get entity description for Order, OrderItem, Product
5. Get entity repositories for Order
6. Get entity mappers for Order
7. Get entity DTOs for Order

---

第 2 步 — 加载参考资料

告知用户：Step 2/6: Loading relevant references...

此步骤中请勿调用任何工具。

根据第 1 步的探索计划，仅加载所选路径所需且本次对话中尚未加载的参考资料。 加载后直接进入第 3 步——请勿搜索文件、使用 glob 或手动探索项目结构。所有项目信息都必须仅通过第 3–5 步中的 MCP 工具获取。

所选路径	要加载的参考资料
获取实体描述（JPA）	references/entity-description.md
获取实体描述（JDBC）	references/entity-description-jdbc.md
根据实体获取深层模型	references/deep-model-based-on-jpa.md
根据实体获取 DDD 模型	references/ddd-model-based-on-jpa.md
获取实体仓库	references/entity-repositories.md
获取实体组件	references/entity-components.md
获取实体服务	references/entity-services.md
获取实体映射器	references/entity-mappers.md
获取实体 DTO	references/entity-dtos.md
获取实体控制器	references/entity-controllers.md

如果没有路径需要参考资料，请跳过此步骤并进入第 3 步。

---

第 3 步 — 制定统一探索计划

告知用户：Step 3/6: Building exploration plan...

此步骤中请勿调用任何工具。

根据第 1 步所选的路径和已加载参考资料中描述的流程， 制定一个统一的编号计划，列出要在第 4–5 步中执行的 MCP 调用。 每一项都必须是具体的 MCP 工具调用，而非类别名称。

### Unified exploration plan:
1. get_project_summary
2. list_project_endpoints
3. list_all_domain_entities (regexPattern=Owner) — resolve FQN
4. get_entity_details (Owner FQN)
5. get_entity_details (Pet FQN)
6. get_entity_details (Visit FQN)
7. list_entity_repositories (Owner FQN)
8. list_entity_repositories (Pet FQN)
9. list_entity_repositories (Visit FQN)

---

第 4 步 — 通过子 Agent 执行探索计划

告知用户：Step 4/6: Executing exploration plan...

启动一个子 Agent，并向其传递以下指令：

Execute the exploration plan below by calling each MCP tool in order.
Use MCP tools directly (e.g. get_entity_details, list_entity_repositories).

Collect and return ALL results in full — do not summarize or truncate.

Secret redaction: if any returned value belongs to a key that looks like a credential
(`password`, `passwd`, `secret`, `token`, `api-key`, `apikey`, `access-key`, `private-key`,
`credentials`, `client-secret`, `auth`, or similar), replace only the value with `[REDACTED]`
and keep the key and surrounding structure intact. Never echo credential values verbatim.

Plan:
<paste the numbered plan from step 3 here>

等待子 Agent 完成，并收集所有结果后再继续。

---

第 5 步 — 编写探索报告

告知用户：Step 5/6: Building exploration report...

此步骤中请勿调用任何工具——仅根据子 Agent 的结果进行推理。

综合所有探索周期中收集的发现，编写一份报告。仅包含对任务确有价值的内容——省略噪声和显而易见的默认值。

结构：

### Exploration Report

**Stack:** Java 21 · Spring Boot 3.x · Maven
**Persistence:** JPA   

**Domain model:**
- Order (id, status, totalAmount) → has many OrderItem → references Product
- Customer (id, name, email)

**Repositories:**
- OrderRepository — extends JpaRepository, supports pagination
- CustomerRepository — extends JpaRepository

**Services:**
- OrderService — handles order creation and status transitions

**Mappers:**
- OrderMapper (MapStruct) — maps Order ↔ OrderDto

**DTOs:**
- OrderDto, OrderItemDto — already exist

**REST API (relevant endpoints):**
- GET /orders — paginated list
- POST /orders — create order

**Notable findings:**
- SecurityConfig present — all endpoints require authentication
- No mapper for Customer — will need to create one

---

第 5.5 步 — 提出隐含假设

告诉用户：Step 5.5/6: Formulating implicit assumptions...

此步骤中不要调用任何工具——只能根据子 Agent 的结果和用户的请求进行推理。

根据探索报告和用户的请求，找出用户没有明确说明、但可能希望在实现中满足的所有要求。这些都是隐含假设——用户可能认为理所当然、但没有明说的要求、惯例和设计决策。

重点关注：

• 行为预期——例如：“用户可能希望软删除，而不是硬删除”“分页默认采用偏移量方式”
• 安全性/访问控制——例如：“该端点可能应该像项目中的其他端点一样要求身份验证”
• 验证——例如：“用户可能希望验证电子邮件和价格等字段”
• 错误处理——例如：“找不到实体时，用户可能希望返回 404，而不是 500”
• 惯例——例如：“用户可能希望响应格式与现有端点一致（camelCase，数据包含在 data 字段中）”
• 相关副作用——例如：“创建订单时，用户可能希望更新库存或发送通知”
• DTO 结构——例如：“用户可能希望响应中包含嵌套项目，而不只是 ID”

明确列出所有假设，以便用户确认或更正：

### Implicit assumptions:
1. The new endpoint should require authentication — all existing endpoints use SecurityConfig with auth required.
2. Response format should match existing endpoints — camelCase JSON, no wrapper object.
3. Pagination is expected to be offset-based (Pageable) — consistent with other list endpoints.
4. Missing entity should return 404, not 500 — standard REST convention followed elsewhere.
5. Price field is expected to be validated as positive — consistent with other monetary fields in the domain.
6. OrderItem list in response should include product name and quantity — implied by "order details" framing.

如果无法识别出任何隐含假设，请明确说明：

### Implicit assumptions: none identified — the request is fully specified.

---

第 6 步 — 决定是否进入下一轮

告诉用户：Step 6/6: Evaluating next cycle...

此步骤中不要调用任何工具——只能根据子 Agent 的结果进行推理。

预测再进行一轮的价值（0–100）：剩余差距有多关键，以及能否通过 MCP 解决。给出分数和理由：

### Additional cycle value: 87/100 → additional exploration cycle required.

分数 > 80 — 转到第 1 步。分数 ≤ 80 — 停止。