103 lines
6.8 KiB
Markdown
103 lines
6.8 KiB
Markdown
# Feature Specification: AI-Assisted Rename Command
|
||
|
||
**Feature Branch**: `008-ai-rename-command`
|
||
**Created**: 2025-11-05
|
||
**Status**: Draft
|
||
**Input**: User description: "添加 ai 子命令，使用go genkit 调用ai能力对文件列表进行重命名。"
|
||
|
||
## Clarifications
|
||
|
||
### Session 2025-11-05
|
||
|
||
- Q: How should the CLI handle filename privacy when calling the AI service? → A: Send raw filenames without masking.
|
||
- Q: How should the AI provider credential be supplied to the CLI? → A: Read from an environment variable (e.g., `RENAMER_AI_KEY`).
|
||
|
||
## User Scenarios & Testing *(mandatory)*
|
||
|
||
### User Story 1 - Request AI rename plan (Priority: P1)
|
||
|
||
As a command-line user, I can request AI-generated rename suggestions for a set of files so that I get a consistent naming plan without defining rules manually.
|
||
|
||
**Why this priority**: This delivers the core value of leveraging AI to save time on naming decisions for large batches.
|
||
|
||
**Independent Test**: Execute the AI rename command against a sample directory and verify a preview of suggested names is produced without altering files.
|
||
|
||
**Acceptance Scenarios**:
|
||
|
||
1. **Given** a directory with mixed file names and optional user instructions, **When** the user runs the AI rename command, **Then** the tool returns a preview mapping each original name to a suggested name.
|
||
2. **Given** a scope that includes hidden files when the user enables the corresponding flag, **When** the AI rename command runs, **Then** the preview reflects only the files allowed by the selected scope options.
|
||
|
||
---
|
||
|
||
### User Story 2 - Refine and confirm suggestions (Priority: P2)
|
||
|
||
As a command-line user, I can review, adjust, or regenerate AI suggestions before applying them so that I have control over the final names.
|
||
|
||
**Why this priority**: Users need confidence and agency to ensure AI suggestions match their intent, reducing the risk of undesired renames.
|
||
|
||
**Independent Test**: Run the AI rename command, adjust the instruction text, regenerate suggestions, and confirm the tool updates the preview without applying changes until approval.
|
||
|
||
**Acceptance Scenarios**:
|
||
|
||
1. **Given** an initial AI preview, **When** the user supplies new guidance or rejects the batch, **Then** the tool allows a regeneration or cancellation without renaming any files.
|
||
2. **Given** highlighted conflicts or invalid suggestions in the preview, **When** the user attempts to accept the batch, **Then** the tool blocks execution and instructs the user to resolve the issues.
|
||
|
||
---
|
||
|
||
### User Story 3 - Apply and audit AI renames (Priority: P3)
|
||
|
||
As a command-line user, I can apply approved AI rename suggestions and rely on the existing history and undo mechanisms so that AI-driven batches are traceable and reversible.
|
||
|
||
**Why this priority**: Preserving auditability and undo aligns AI-driven actions with existing safety guarantees.
|
||
|
||
**Independent Test**: Accept an AI rename batch, verify files are renamed, the ledger records the operation, and the undo command restores originals.
|
||
|
||
**Acceptance Scenarios**:
|
||
|
||
1. **Given** an approved AI rename preview, **When** the user confirms execution, **Then** the files are renamed and the batch details are recorded in the ledger with AI-specific metadata.
|
||
2. **Given** an executed AI rename batch, **When** the user runs the undo command, **Then** all affected files return to their original names and the ledger reflects the reversal.
|
||
|
||
---
|
||
|
||
### Edge Cases
|
||
|
||
- AI service fails, times out, or returns an empty response; the command must preserve current filenames and surface actionable error guidance.
|
||
- The AI proposes duplicate, conflicting, or filesystem-invalid names; the preview must flag each item and prevent application until resolved.
|
||
- The selected scope includes more files than the AI request limit; the command must communicate limits and guide the user to narrow the scope or batch the request.
|
||
- The ledger already contains pending batches for the same files; the tool must clarify how the new AI batch interacts with existing history before proceeding.
|
||
|
||
## Requirements *(mandatory)*
|
||
|
||
### Functional Requirements
|
||
|
||
- **FR-001**: The CLI must gather the current file scope using existing flags and present the selected files and optional instructions to the AI suggestion service.
|
||
- **FR-002**: The system must generate a human-readable preview that pairs each original filename with the AI-proposed name and indicates the rationale or confidence when available.
|
||
- **FR-003**: The CLI must block application when the preview contains conflicts, invalid names, or missing suggestions and must explain the required corrective actions.
|
||
- **FR-004**: Users must be able to modify guidance and request a new set of AI suggestions without leaving the command until they accept or exit.
|
||
- **FR-005**: When users approve a preview, the tool must execute the rename batch, record it in the ledger with the user guidance and AI attribution, and support undo via the existing command.
|
||
- **FR-006**: The command must support dry-run mode that exercises the AI interaction and preview without writing to disk, clearly labeling the output as non-destructive.
|
||
- **FR-007**: The system must handle AI service errors gracefully by retaining current filenames, logging diagnostic information, and providing retry instructions.
|
||
|
||
### Key Entities
|
||
|
||
- **AISuggestionBatch**: Captures the scope summary, user guidance, timestamp, AI provider metadata, and the list of rename suggestions evaluated during a session.
|
||
- **RenameSuggestion**: Represents a single proposed change with original name, suggested name, validation status, and optional rationale.
|
||
- **UserGuidance**: Stores free-form instructions supplied by the user, including any follow-up refinements applied within the session.
|
||
|
||
## Assumptions
|
||
|
||
- AI rename suggestions are generated within existing rate limits; large directories may require the user to split the work manually.
|
||
- Users running the AI command have network access and credentials required to reach the AI service.
|
||
- Existing ledger and undo mechanisms remain unchanged and can store additional metadata without format migrations.
|
||
- AI requests transmit the original filenames without masking; users must avoid including sensitive names when invoking the command.
|
||
- The CLI reads AI provider credentials from environment variables (default `RENAMER_AI_KEY`); no interactive credential prompts are provided.
|
||
|
||
## Success Criteria *(mandatory)*
|
||
|
||
### Measurable Outcomes
|
||
|
||
- **SC-001**: 95% of AI rename previews for up to 200 files complete in under 30 seconds from command invocation.
|
||
- **SC-002**: 90% of accepted AI rename batches complete without conflicts or manual post-fix adjustments reported by users.
|
||
- **SC-003**: 100% of AI-driven rename batches remain fully undoable via the existing undo command.
|
||
- **SC-004**: In post-launch surveys, at least 80% of participating users report that AI suggestions improved their rename workflow efficiency.
|