6.8 KiB
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:
- 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.
- 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:
- 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.
- 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:
- 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.
- 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.