docs: design core code analysis selection
This commit is contained in:
王鹏
@@ -0,0 +1,139 @@
|
||||
# Code Analysis Core Source Selection Design
|
||||
|
||||
## Background
|
||||
|
||||
The current code-analysis flow collects preview source from `backend`, `frontend`, `admin_frontend`, and `sql`, reads every allowed source-like file, and then truncates the assembled prompt context at 120KB. This works for small projects, but it can send too much low-value code to the AI and leave less room for the files that explain the real architecture and business flow.
|
||||
|
||||
The requested change is to send fewer files while keeping the most useful Java, Vue, SQL, and mapper/config context. The AI should receive a curated source snapshot, not a broad dump of every allowed file.
|
||||
|
||||
## Goal
|
||||
|
||||
Make `ProjectCodeAnalysisService` intelligently select a compact set of core files for AI code interpretation. The default expanded source budget is 60KB, with clear metadata and warnings for files that were skipped, summarized, or truncated.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- Do not add a second AI call to ask the model which files to choose.
|
||||
- Do not require the user to manually pick files.
|
||||
- Do not scan arbitrary server directories or uploaded ZIP files.
|
||||
- Do not remove existing ownership checks or preview-read safeguards.
|
||||
- Do not change the report page layout in this feature.
|
||||
|
||||
## Selection Strategy
|
||||
|
||||
The backend keeps using the existing preview source tree as input:
|
||||
|
||||
- `frontProjectPreviewService.getStructure(userId, projectId, "backend")`
|
||||
- `frontProjectPreviewService.getStructure(userId, projectId, "frontend")`
|
||||
- `frontProjectPreviewService.getStructure(userId, projectId, "admin_frontend")`
|
||||
- `frontProjectPreviewService.getStructure(userId, projectId, "sql")`
|
||||
|
||||
Instead of sending every allowed file until the prompt is full, the service will score each candidate file and assemble the prompt from highest-value files first.
|
||||
|
||||
High-priority files:
|
||||
|
||||
- Java controllers, especially paths or class names containing `Controller`
|
||||
- Java services and service implementations
|
||||
- Java mappers and mapper XML files
|
||||
- Java entity/domain/model/DTO classes
|
||||
- SQL files containing table definitions
|
||||
- Vue route files, API wrappers, and core page components
|
||||
- Project dependency/config files such as `pom.xml`, `package.json`, `application.yml`, and router files
|
||||
|
||||
Low-priority or skipped files:
|
||||
|
||||
- Build artifacts and dependency folders: `target`, `dist`, `node_modules`, `.git`, `.idea`
|
||||
- Static assets, generated bundles, minified files, maps, images, fonts, archives, binaries
|
||||
- Tests, screenshots, audit artifacts, demo-only files, mockups, and style-only files unless no better frontend files exist
|
||||
- Very large files after their useful header and structural content have been captured
|
||||
|
||||
## Budget Rules
|
||||
|
||||
The default expanded prompt source budget is 60KB. This is the total size of actual source content sent to the AI, not counting a small file manifest.
|
||||
|
||||
Recommended limits:
|
||||
|
||||
- Total expanded source budget: `60 * 1024` characters
|
||||
- Per-file expanded budget for Java/Vue/XML/SQL/config: about `20 * 1024` characters
|
||||
- Keep a compact manifest of selected and skipped files outside the expanded source body
|
||||
- If the budget is exhausted, include remaining important file names in metadata, but do not expand their contents
|
||||
|
||||
The AI prompt should explicitly say that the source snapshot is curated and compact. It must not infer details from files that were not expanded.
|
||||
|
||||
## Data Shape
|
||||
|
||||
Reuse `CodeAnalysisSourceSummary` and its existing file/skipped-file lists where possible.
|
||||
|
||||
Expected summary behavior:
|
||||
|
||||
- `includedFiles` contains only selected core files with content or compact extracted content
|
||||
- `skippedFiles` includes non-core files and budget-excluded files with a reason
|
||||
- `warnings` describes budget limits and any important omitted areas
|
||||
- `promptContext` contains the curated file manifest and expanded core source blocks
|
||||
- `analyzedFileCount` reflects selected files, while `fileCount` still reflects all scanned candidate files
|
||||
|
||||
Example prompt context shape:
|
||||
|
||||
```text
|
||||
Selected core source files:
|
||||
- backend / src/main/java/.../UserController.java (controller, expanded)
|
||||
- backend / src/main/java/.../UserServiceImpl.java (service, expanded)
|
||||
- backend / src/main/resources/mapper/.../UserMapper.xml (mapper, expanded)
|
||||
- sql / user.sql (table schema, expanded)
|
||||
- frontend / src/views/user/index.vue (vue page, expanded)
|
||||
|
||||
Skipped or summarized files:
|
||||
- frontend / src/styles/index.scss (style-only)
|
||||
- frontend / src/utils/request.js (lower priority after budget)
|
||||
|
||||
## backend / src/main/java/.../UserController.java
|
||||
...
|
||||
```
|
||||
|
||||
## Scoring Details
|
||||
|
||||
The score should be deterministic and testable. A simple weighted rule set is enough for this feature.
|
||||
|
||||
Suggested scoring:
|
||||
|
||||
- SQL schema files: very high
|
||||
- `*Controller.java`: very high
|
||||
- `*Service.java` and `*ServiceImpl.java`: high
|
||||
- `*Mapper.java` and `*Mapper.xml`: high
|
||||
- `domain`, `entity`, `model`, `dto`: medium-high
|
||||
- Vue views/pages and router/API files: medium-high
|
||||
- `application.yml`, `pom.xml`, `package.json`: medium
|
||||
- Utility, style, test, demo, and docs files: low or skipped
|
||||
|
||||
Tie-breakers:
|
||||
|
||||
- Prefer files with shorter, clearer business paths over generic utility paths
|
||||
- Keep a balanced mix of backend, frontend, and SQL rather than letting one layer consume all 60KB
|
||||
- Preserve current stable ordering where scores are equal to avoid noisy test changes
|
||||
|
||||
## Prompt Requirements
|
||||
|
||||
Update the code-analysis prompt wording to make the source selection explicit:
|
||||
|
||||
- "The following source snapshot is a curated subset of core files."
|
||||
- "Use only the expanded source and listed metadata as evidence."
|
||||
- "If a detail is not present in the selected source, say it cannot be confirmed."
|
||||
- "When explaining architecture, cite real class, method, component, table, or field names from the selected files."
|
||||
|
||||
## Testing Plan
|
||||
|
||||
Backend tests should cover:
|
||||
|
||||
- Core files are selected before low-value files when budget is limited
|
||||
- Controller, Service, Mapper/XML, Vue page/API/router, and SQL files appear in the prompt when present
|
||||
- Style-only, test, demo, dependency, and build artifact files are skipped or deprioritized
|
||||
- Total expanded source context stays near the 60KB budget
|
||||
- A large high-priority file is truncated per-file instead of consuming the whole prompt
|
||||
- Budget-excluded but relevant files are recorded in skipped files or warnings
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- Code analysis sends a compact curated source snapshot by default.
|
||||
- The expanded source content sent to AI is about 60KB, not the previous 120KB broad dump.
|
||||
- Java, Vue, SQL, and mapper/config files receive priority based on their architectural value.
|
||||
- The prompt includes enough metadata for the AI to know which important files were selected or omitted.
|
||||
- Existing code-analysis generation, streaming, history, and continuation flows keep working.
|
||||
Reference in New Issue
Block a user