agent/docs/superpowers/plans/2026-07-21-forest-ai-feature-alignment.md

森林AI Feature Alignment Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: 让前端核心工作流完整使用 /api/v1，补齐搜索、项目设置、Inbox 和受控 AI 会话，同时移除伪功能入口。

Architecture: 前端 API 层只认一种 camelCase DTO，页面事件由 App 编排后刷新聚合工作区。后端为搜索和 AI 会话提供独立 registrar；超出 MVP 的入口从页面移除。

Tech Stack: React、TypeScript、Gin、Gorm、Playwright、Go httptest。

Global Constraints

• 所有前端 ID 是 identity 字符串；不兼容 PascalCase 或数字 ID。
• AI 未经用户确认不得创建任务、笔记或资料。
• 核心操作必须有 loading、成功反馈和可执行的中文错误。
• 不实现探索数据源、支付、窗口停靠、自主 Agent 或实时聊天。

---

Task 1: 前端 API v1 客户端和错误类型

Files:

• Modify: apps/web_v1/src/api/client.ts
• Modify: apps/web_v1/src/api/projects.ts
• Modify: apps/web_v1/src/api/mappers.tsx
• Create: apps/web_v1/src/api/search.ts
• Create: apps/web_v1/src/api/inbox.ts
• Modify: apps/web_v1/scripts/structure-check.mjs

Interfaces:

• Produces: ApiError { status: number; code: string; message: string } and camelCase DTOs only.

• Step 1: Add failing static checks

Reject ID?, Name?, /api/projects, and number project/task IDs in src/api. Require /api/v1 in login and project API paths.

• Step 2: Verify failures

Run: node scripts/structure-check.mjs

Expected: FAIL on legacy paths and PascalCase compatibility fields.

• Step 3: Implement one response contract

Parse the standard error envelope:

export class ApiError extends Error {
  constructor(public status: number, public code: string, message: string) {
    super(message)
  }
}

All DTOs use required camelCase fields and string IDs. Update date formatting to happen only in mappers.

• Step 4: Verify frontend types

Run: node scripts/structure-check.mjs && npm run build && npm run lint

Expected: PASS.

• Step 5: Commit

git add apps/web_v1/src/api apps/web_v1/scripts/structure-check.mjs
git commit -m "refactor(web): consume api v1 contracts"

Task 2: 搜索与项目设置真实往返

Files:

• Create: backend/internal/logic/search/handlers.go
• Create: backend/internal/logic/search/handlers_test.go
• Modify: backend/cmd/api/main.go
• Modify: apps/web_v1/src/pages/projects/project-topbar.tsx
• Modify: apps/web_v1/src/pages/projects/project-sidebar.tsx
• Modify: apps/web_v1/src/app/App.tsx

Interfaces:

• GET /api/v1/search?q= returns {items: SearchResultDTO[]}.

• PATCH /api/v1/projects/:projectId persists settings and returns ProjectDTO.

• Step 1: Write failing search handler tests

Assert blank query returns 400 invalid_query, authenticated matching query returns project/task/note results, and another user's private objects are absent.

• Step 2: Verify backend failures

Run: go test ./internal/logic/search -v

Expected: FAIL because handler is missing.

• Step 3: Implement search registrar and front-end search state

Topbar accepts query, loading, onQueryChange, onSearch. Submit on Enter or the Search button. Render results in an Arco dropdown/list and navigate to the owning project/channel when the result type is known.

• Step 4: Persist project settings

Replace the local setWorkspaces-only update with updateProject(session, update), then call loadWorkspaces with the same identity. Keep the modal open on failure.

• Step 5: Verify

Run: go test ./internal/logic/search ./internal/logic/projects -v; npm run build; npm run lint

Expected: PASS.

• Step 6: Commit

git add backend/internal/logic/search backend/cmd/api/main.go apps/web_v1/src
git commit -m "feat: connect search and project settings"

Task 3: Inbox 确认流与核心写操作

Files:

• Modify: backend/internal/logic/inbox/handlers.go
• Modify: backend/internal/logic/inbox/service.go
• Modify: backend/internal/logic/inbox/service_test.go
• Modify: apps/web_v1/src/api/inbox.ts
• Create: apps/web_v1/src/pages/projects/project-inbox.tsx
• Modify: apps/web_v1/src/pages/projects/project-channel-page.tsx
• Modify: apps/web_v1/src/app/App.tsx

Interfaces:

• Inbox capture/analyze/confirm uses identity strings.

• confirm accepts only suggestions returned for the same inbox item and current user.

• Step 1: Add failing identity and authorization tests

Test capture, analyze without writes, confirm selected task/note/source with source Inbox identity, and reject confirming another user's inbox item.

• Step 2: Verify failures

Run: go test ./internal/logic/inbox -v

Expected: legacy numeric paths or authorization gaps fail new tests.

• Step 3: Implement v1 Inbox DTOs and page

The page shows item content, suggestion checkboxes and one 确认创建 action. Analysis results remain drafts until this action. On success refresh the workspace and show the created object count.

• Step 4: Verify core write operations

Run: go test ./internal/logic/inbox ./internal/logic/tasks ./internal/logic/projects -v; npm run build; npm run lint

Expected: PASS.

• Step 5: Commit

git add backend/internal/logic/inbox apps/web_v1/src
git commit -m "feat: connect inbox confirmation workflow"

Task 4: 受控 AI 会话与伪功能清理

Files:

• Create: backend/internal/logic/ai/handlers.go
• Create: backend/internal/logic/ai/handlers_test.go
• Modify: backend/internal/logic/ai/sessions.go
• Modify: backend/internal/logic/ai/gateway.go
• Modify: backend/cmd/api/main.go
• Modify: apps/web_v1/src/pages/projects/project-ai.tsx
• Modify: apps/web_v1/src/pages/workspace-explore.tsx
• Modify: apps/web_v1/src/pages/projects/project-new-channel.tsx
• Modify: apps/web_v1/src/pages/projects/project-statusbar.tsx
• Modify: apps/web_v1/src/pages/projects/project-topbar.tsx
• Modify: apps/web_v1/scripts/visual-check.mjs

Interfaces:

• GET/POST /api/v1/projects/:projectId/ai-sessions lists/creates controlled sessions.

• No endpoint converts AI output into formal objects without a separate confirmation request.

• Step 1: Write failing AI handler tests

Assert session creation checks project ownership, rate limit runs before provider selection, call logs contain required fields, and the response contains no automatic object IDs.

• Step 2: Verify failures

Run: go test ./internal/logic/ai -v

Expected: FAIL because handlers are missing.

• Step 3: Implement controlled session endpoints

Return a session DTO with identity, title, context, status and timestamps. If no provider key exists, return ai_key_missing without creating formal objects.

• Step 4: Remove unsupported controls

Remove active-looking sync/edit/delete actions from Explore, payment choices from the status bar, dock buttons, fake app launcher and nonfunctional channel save. Keep a concise “暂未开放” empty state only where navigation must remain visible.

• Step 5: Update visual checks and verify

Run: go test ./...; $env:VISUAL_CHECK_PORT='4174'; node scripts/visual-check.mjs; npm run build; npm run lint

Expected: all PASS, AI page has an AI 助手 heading, and console errors are empty.

• Step 6: Commit

git add backend/internal/logic/ai backend/cmd/api/main.go apps/web_v1/src apps/web_v1/scripts/visual-check.mjs
git commit -m "feat: align controlled AI sessions and MVP controls"