257 lines
12 KiB
Markdown
257 lines
12 KiB
Markdown
# AI Operator Co-Pilot & Conversation Auto-Summarization Implementation Plan
|
||
|
||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||
|
||
**Goal:** Empower human operators with an AI Co-Pilot that generates contextual draft reply suggestions with 1 click, and provides automated conversation summaries (for quick handoffs and close documentation).
|
||
|
||
**Architecture:** Create an `AICopilotService` in the Go backend utilizing `ai.LLM.Chat` with conversation history assembly, locale-aware prompt instructions, and graceful fallbacks. Expose endpoints `POST /api/dashboard/conversation/suggest_reply` and `POST /api/dashboard/conversation/summarize`. On the frontend, integrate a Sparkles (✨) AI Suggest action in `SharedMessageEditor` and an AI Summary inspection/close button in the conversation panel.
|
||
|
||
**Tech Stack:** Go 1.26, Next.js 16 App Router, TypeScript, Base UI / Tailwind CSS, Lucide icons (`Sparkles`, `FileText`), OpenAI/Qwen compatible LLM backend.
|
||
|
||
**Spec:** Agreed enhancements roadmap (Option 2 - AI operator features).
|
||
|
||
## Global Constraints
|
||
|
||
- Follow AGENTS.md layer ownership (`handlers -> services -> repositories/builders`). Handlers must not call LLM or repositories directly.
|
||
- Symmetrical 3-locale i18n parity (`zh-CN.json`, `en-US.json`, `ru-RU.json`).
|
||
- Resilient against absent/offline LLM config: return clean, localized errors rather than crashes or unhandled exceptions.
|
||
- TypeScript compilation must pass with 0 errors (`tsc --noEmit`).
|
||
- Go formatting (`gofmt`) and all Go tests must pass cleanly.
|
||
|
||
## Review Focus
|
||
|
||
1. Prompt formatting & injection safety: customer input must be clearly delimited so user messages cannot hijack system instructions.
|
||
2. Context window limits: only format the most recent 10-15 messages to prevent exceeding LLM context windows or incurring high latency.
|
||
3. Locale matching: if the customer spoke Russian or English, the draft reply must match the conversation's language.
|
||
4. Concurrent suggestions: disable the AI Suggest button while generation is in flight to prevent duplicate requests.
|
||
5. Base UI compatibility: avoid Radix `asChild` assumptions; follow AGENTS.md styling guidelines (`rounded-md`, clean spacing).
|
||
|
||
---
|
||
|
||
### Task 1: Backend AI Co-Pilot Service (`SuggestReply` and `SummarizeConversation`)
|
||
|
||
**Files:**
|
||
- Create: `internal/services/ai_copilot_service.go`
|
||
- Create: `internal/services/ai_copilot_service_test.go`
|
||
|
||
**Interfaces:**
|
||
- Produces:
|
||
```go
|
||
var AICopilotService = newAICopilotService()
|
||
|
||
type AICopilotService interface {
|
||
SuggestReply(ctx context.Context, conversationID int64, locale string) (string, error)
|
||
SummarizeConversation(ctx context.Context, conversationID int64, locale string) (string, error)
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 1: Write unit tests for AICopilotService**
|
||
|
||
In `internal/services/ai_copilot_service_test.go`:
|
||
- Test prompt generation with recent messages.
|
||
- Test message normalization and conversation history formatting.
|
||
- Test fallback behavior when no messages exist.
|
||
|
||
- [ ] **Step 2: Run test to verify it fails**
|
||
|
||
Run: `& 'C:\Program Files\Go\bin\go.exe' test -run TestAICopilotService ./internal/services/...`
|
||
Expected: FAIL
|
||
|
||
- [ ] **Step 3: Implement `AICopilotService`**
|
||
|
||
In `internal/services/ai_copilot_service.go`:
|
||
- Fetch recent messages (up to 12) from `MessageService`.
|
||
- Build conversation transcript formatted as `Customer: ...` / `Agent: ...`.
|
||
- Assemble system and user prompts respecting `locale`.
|
||
- Call `ai.LLM.Chat(ctx, systemPrompt, userPrompt)`.
|
||
|
||
- [ ] **Step 4: Run test to verify it passes**
|
||
|
||
Run: `& 'C:\Program Files\Go\bin\go.exe' test -run TestAICopilotService ./internal/services/...`
|
||
Expected: PASS
|
||
|
||
- [ ] **Step 5: Run gofmt and commit**
|
||
|
||
```bash
|
||
git add internal/services/ai_copilot_service.go internal/services/ai_copilot_service_test.go
|
||
git commit -m "feat(ai): implement AICopilotService for draft replies and conversation summarization"
|
||
```
|
||
|
||
---
|
||
|
||
### Task 2: Dashboard API Endpoints for AI Co-Pilot
|
||
|
||
**Files:**
|
||
- Create: `internal/pkg/dto/request/ai_copilot_request.go`
|
||
- Create: `internal/pkg/dto/response/ai_copilot_response.go`
|
||
- Modify: `internal/handlers/dashboard/conversation_handler.go`
|
||
- Modify: `internal/handlers/dashboard/conversation_handler_test.go`
|
||
- Modify: `internal/bootstrap/routes.go`
|
||
|
||
**Interfaces:**
|
||
- Produces:
|
||
- `POST /api/dashboard/conversation/suggest_reply`: takes `{ conversationId: int64 }`, returns `{ suggestion: string }`.
|
||
- `POST /api/dashboard/conversation/summarize`: takes `{ conversationId: int64 }`, returns `{ summary: string }`.
|
||
- Permission: requires `constants.PermissionConversationView`.
|
||
|
||
- [ ] **Step 1: Write handler tests**
|
||
|
||
In `internal/handlers/dashboard/conversation_handler_test.go`:
|
||
Add tests for `ConversationPostSuggest_reply` and `ConversationPostSummarize` (validation, permission check, success).
|
||
|
||
- [ ] **Step 2: Run test to verify it fails**
|
||
|
||
Run: `& 'C:\Program Files\Go\bin\go.exe' test -run TestConversationSuggestReply ./internal/handlers/dashboard/...`
|
||
Expected: FAIL
|
||
|
||
- [ ] **Step 3: Implement DTOs, handlers, and routes**
|
||
|
||
1. Create `internal/pkg/dto/request/ai_copilot_request.go` with `SuggestReplyRequest` and `SummarizeConversationRequest`.
|
||
2. Create `internal/pkg/dto/response/ai_copilot_response.go` with `SuggestReplyResponse` and `ConversationSummaryResponse`.
|
||
3. In `internal/handlers/dashboard/conversation_handler.go`: implement `ConversationPostSuggest_reply` and `ConversationPostSummarize`.
|
||
4. In `internal/bootstrap/routes.go`: register both routes under dashboard conversation group.
|
||
|
||
- [ ] **Step 4: Run test to verify it passes**
|
||
|
||
Run: `& 'C:\Program Files\Go\bin\go.exe' test ./internal/handlers/dashboard/...`
|
||
Expected: PASS
|
||
|
||
- [ ] **Step 5: Run gofmt and commit**
|
||
|
||
```bash
|
||
git add internal/pkg/dto/request/ai_copilot_request.go internal/pkg/dto/response/ai_copilot_response.go internal/handlers/dashboard/conversation_handler.go internal/handlers/dashboard/conversation_handler_test.go internal/bootstrap/routes.go
|
||
git commit -m "feat(api): register /suggest_reply and /summarize dashboard endpoints"
|
||
```
|
||
|
||
---
|
||
|
||
### Task 3: Symmetrical i18n Translations for AI Co-Pilot
|
||
|
||
**Files:**
|
||
- Modify: `web/messages/en-US.json`
|
||
- Modify: `web/messages/ru-RU.json`
|
||
- Modify: `web/messages/zh-CN.json`
|
||
- Test: `web/i18n/message-integrity.test.mjs`
|
||
|
||
**Interfaces:**
|
||
- Produces: Symmetrical keys across all 3 locales:
|
||
- `aiCopilot.suggestReply`: "AI Suggest" / "Подсказать ответ" / "AI 生成回复"
|
||
- `aiCopilot.generating`: "Generating reply..." / "Генерация ответа..." / "正在生成回复..."
|
||
- `aiCopilot.insertReply`: "Use this reply" / "Использовать ответ" / "填入输入框"
|
||
- `aiCopilot.discardReply`: "Dismiss" / "Отклонить" / "放弃"
|
||
- `aiCopilot.summarize`: "AI Summary" / "AI Резюме" / "AI 总结"
|
||
- `aiCopilot.summarizing`: "Summarizing..." / "Составление резюме..." / "正在生成总结..."
|
||
- `aiCopilot.summaryTitle`: "Conversation Summary" / "Краткое резюме диалога" / "会话小结"
|
||
- `aiCopilot.noSummary`: "No summary available yet" / "Резюме пока недоступно" / "暂无会话总结"
|
||
- `aiCopilot.errorGenerating`: "Failed to generate AI suggestion" / "Не удалось сгенерировать ответ" / "生成 AI 建议失败"
|
||
|
||
- [ ] **Step 1: Check baseline integrity**
|
||
|
||
Run: `node --test web/i18n/message-integrity.test.mjs`
|
||
|
||
- [ ] **Step 2: Add keys symmetrically to all 3 JSON files**
|
||
|
||
Add `aiCopilot.*` keys with exact placeholder parity.
|
||
|
||
- [ ] **Step 3: Run integrity tests**
|
||
|
||
Run: `node --test web/i18n/message-integrity.test.mjs`
|
||
Expected: PASS (0 missing keys, 0 placeholder mismatches).
|
||
|
||
- [ ] **Step 4: Commit**
|
||
|
||
```bash
|
||
git add web/messages/en-US.json web/messages/ru-RU.json web/messages/zh-CN.json
|
||
git commit -m "feat(i18n): add localized messages for AI copilot draft replies and summarization"
|
||
```
|
||
|
||
---
|
||
|
||
### Task 4: AI Reply Suggestion UI in Message Editor
|
||
|
||
**Files:**
|
||
- Modify: `web/lib/api/agent.ts`
|
||
- Modify: `web/components/chat/shared-message-editor.tsx`
|
||
- Modify: `web/app/(dashboard)/dashboard/conversations/_components/agent-message-editor.tsx`
|
||
- Test: `web/node_modules/.bin/tsc.cmd --noEmit` and node tests
|
||
|
||
**Interfaces:**
|
||
- Consumes: `POST /api/dashboard/conversation/suggest_reply`
|
||
- Produces:
|
||
- Sparkles icon button in operator message editor toolbar.
|
||
- When clicked: requests suggestion, renders an interactive floating/docked suggestion card with:
|
||
- Generated text preview
|
||
- "Use this reply" button (inserts text into editor and closes card)
|
||
- "Dismiss" button
|
||
- Disabled / loading state with spinner while generating.
|
||
|
||
- [ ] **Step 1: Add API client methods in `web/lib/api/agent.ts`**
|
||
|
||
Export `suggestAgentReply(conversationId: number)` and `summarizeAgentConversation(conversationId: number)`.
|
||
|
||
- [ ] **Step 2: Add AI Suggest button & suggestion drawer in `SharedMessageEditor`**
|
||
|
||
In `SharedMessageEditor`:
|
||
- Add `aiCopilot?: { onSuggest: () => Promise<string | null>; loading?: boolean }` prop.
|
||
- Render `SparklesIcon` button in operator toolbar.
|
||
- When suggestion is available, render a clean draft suggestion card above the editor with "Use this reply" and "Dismiss".
|
||
|
||
- [ ] **Step 3: Wire into `AgentMessageEditor`**
|
||
|
||
In `agent-message-editor.tsx`:
|
||
- Connect `aiCopilot` calling `suggestAgentReply(selectedConversationId)`.
|
||
- Handle insertion and toast notification.
|
||
|
||
- [ ] **Step 4: Run typecheck and tests**
|
||
|
||
Run: `& "web/node_modules/.bin/tsc.cmd" --noEmit --project web/tsconfig.json`
|
||
Run: `node --test web/lib/*.test.mjs web/i18n/*.test.mjs`
|
||
Expected: ALL PASS with 0 errors.
|
||
|
||
- [ ] **Step 5: Commit**
|
||
|
||
```bash
|
||
git add web/lib/api/agent.ts web/components/chat/shared-message-editor.tsx web/app/\(dashboard\)/dashboard/conversations/_components/agent-message-editor.tsx
|
||
git commit -m "feat(ui): add AI reply suggestion action and preview card to operator message editor"
|
||
```
|
||
|
||
---
|
||
|
||
### Task 5: AI Conversation Summary in Header & Close Dialog
|
||
|
||
**Files:**
|
||
- Modify: `web/app/(dashboard)/dashboard/conversations/_components/chat-panel.tsx`
|
||
- Modify: `web/app/(dashboard)/dashboard/conversations/_components/conversation-info-panel.tsx`
|
||
- Modify: `web/app/(dashboard)/dashboard/conversations/_components/conversation-close-dialog.tsx` (if present)
|
||
- Test: `web/node_modules/.bin/tsc.cmd --noEmit` and node tests
|
||
|
||
**Interfaces:**
|
||
- Consumes: `summarizeAgentConversation(conversationId)`
|
||
- Produces:
|
||
- "AI Summary" popover / dialog button in conversation header or info panel.
|
||
- Generates summary of the conversation turns on demand.
|
||
- Displays structured summary in dialog/card.
|
||
|
||
- [ ] **Step 1: Add AI Summary dialog/popover component**
|
||
|
||
Create `web/app/(dashboard)/dashboard/conversations/_components/conversation-summary-dialog.tsx` rendering summary with loading state.
|
||
|
||
- [ ] **Step 2: Mount summary trigger in header/info panel**
|
||
|
||
In `chat-panel.tsx` or `conversation-info-panel.tsx`:
|
||
Add an action button with `FileTextIcon` / `SparklesIcon` labeled `aiCopilot.summarize` opening the summary dialog.
|
||
|
||
- [ ] **Step 3: Run typecheck, node tests, and Go backend tests**
|
||
|
||
Run: `& "web/node_modules/.bin/tsc.cmd" --noEmit --project web/tsconfig.json`
|
||
Run: `node --test web/lib/*.test.mjs web/i18n/*.test.mjs`
|
||
Run: `& 'C:\Program Files\Go\bin\go.exe' test ./internal/...`
|
||
Expected: ALL PASS with 0 errors.
|
||
|
||
- [ ] **Step 4: Commit**
|
||
|
||
```bash
|
||
git add web/app/\(dashboard\)/dashboard/conversations/_components/conversation-summary-dialog.tsx web/app/\(dashboard\)/dashboard/conversations/_components/chat-panel.tsx web/app/\(dashboard\)/dashboard/conversations/_components/conversation-info-panel.tsx
|
||
git commit -m "feat(ui): add AI conversation summarization dialog and header action"
|
||
```
|