tower-studio 0.1.0 → 0.1.2

package/.next/standalone/tower/docs/modules/ai.md

@@ -0,0 +1,104 @@
+---
+title: AI 模块
+description: Tower 的 AI 能力层，涵盖 Claude Agent SDK 集成、CLI Adapter、助手聊天、任务执行等
+---
+
+**Slug:** `ai`
+
+## 功能介绍
+
+AI 能力层统一管理 Tower 中所有的 AI 调用，提供 5 种核心 AI 能力：
+
+| 能力 | 说明 | 触发时机 | 建议模型 |
+|------|------|----------|----------|
+| **助手聊天** | 多轮流式对话，支持图片输入 | 用户在助手面板发起对话 | 当前默认 |
+| **小总结** | 50 字执行摘要 | 任务停止时自动生成 | Haiku 4.5 |
+| **大总结 Dreaming** | 结构化洞察 JSON | 任务完成（DONE）时自动生成 | Sonnet 4.6 |
+| **项目分析** | 分析目录结构生成描述 | 点击项目「生成描述」按钮 | Sonnet 4.6 |
+| **任务执行** | PTY 终端交互式执行 | 启动任务执行 | 当前默认 |
+
+不同能力建议使用不同模型（Haiku 适合轻量级摘要，Sonnet 适合深度分析），后续支持为每种能力独立配置模型。
+
+## 详细说明
+
+### AI 能力调用点
+
+| 能力 | 文件 | 调用方式 |
+|------|------|----------|
+| 助手聊天 | `api/internal/assistant/chat/route.ts` | Agent SDK `query()` |
+| 小总结 | `lib/claude-session.ts` → `generateSummaryFromLog` | Agent SDK `aiQuery()` |
+| 大总结(Dreaming) | `lib/claude-session.ts` → `generateDreamingInsight` | Agent SDK `aiQuery()` |
+| 项目分析 | `actions/project-actions.ts` → `analyzeProjectDirectory` | Agent SDK `aiQuery()` |
+| 任务执行 | `actions/agent-actions.ts` → `startPtyExecution` | PTY spawn CLI |
+
+### CLI Adapter 接口（TODO）
+
+当前硬编码 Claude Code，后续接入第二个 CLI 时抽象：
+
+```
+spawn(cwd, args, env)        — 启动 CLI 进程（PTY）
+resume(sessionId)            — 恢复会话
+continue()                   — 继续最近会话
+getSessionId()               — 获取会话 ID
+getHooks() / installHooks()  — Hook 配置注册
+buildEnvOverrides(taskId)    — 环境变量注入
+```
+
+## 文件清单
+
+### 核心库
+
+| 文件 | 说明 |
+|------|------|
+| `lib/claude-session.ts` | AI 统一入口：`aiQuery()`、`generateSummaryFromLog()`、`generateDreamingInsight()` |
+| `lib/assistant-sessions.ts` | 助手会话管理（localStorage 注册表） |
+| `lib/assistant-constants.ts` | `ASSISTANT_SESSION_KEY` 等常量 |
+| `lib/assistant-message-converter.ts` | SDK 消息 → UI 消息格式转换 |
+| `lib/build-multimodal-prompt.ts` | 多模态 prompt 构建（文本+图片） |
+| `lib/execution-summary.ts` | 执行后摘要和 Dreaming 洞察生成 |
+| `lib/cli-test.ts` | CLI Adapter 环境检测 |
+
+### Server Actions
+
+| 文件 | 函数 | 说明 |
+|------|------|------|
+| `actions/agent-actions.ts` | `startPtyExecution` | 启动 Claude CLI PTY |
+| `actions/agent-actions.ts` | `resumePtyExecution` | 恢复会话 |
+| `actions/agent-actions.ts` | `continueLatestPtyExecution` | 继续最近会话 |
+| `actions/cli-profile-actions.ts` | `getDefaultCliProfile` | 获取活跃 CLI 配置 |
+| `actions/prompt-actions.ts` | `getPrompts` / `createPrompt` | Prompt 模板管理 |
+| `actions/project-actions.ts` | `analyzeProjectDirectory` | AI 项目分析 |
+
+### API Routes
+
+| 路由 | 说明 |
+|------|------|
+| `/api/internal/assistant/chat` | 助手聊天 SSE 流式 |
+| `/api/internal/assistant/sessions` | 会话消息检索 |
+| `/api/internal/assistant/images` | 图片服务 |
+| `/api/adapters/test` | CLI Adapter 连接测试 |
+
+### 数据模型
+
+| 模型 | 说明 |
+|------|------|
+| `CliProfile` | CLI 命令、参数、环境变量配置。`command` 仅允许 `claude`/`claude-code` |
+| `AgentConfig` | Agent 特定配置，唯一约束 `(agent, configName)` |
+| `AgentPrompt` | Prompt 模板，支持全局/workspace 级别 |
+| `TaskExecution` | 执行记录，含 `sessionId`、`summary`、`gitLog`、`insightNoteId` |
+
+### 组件
+
+| 组件 | 说明 |
+|------|------|
+| `settings/cli-profile-config.tsx` | CLI Profile 配置 UI |
+| `settings/cli-adapter-tester.tsx` | CLI 连接测试 UI |
+| `settings/prompts-config.tsx` | Prompt 模板管理 UI |
+| `settings/ai-tools-config.tsx` | Agent 配置 UI |
+
+## 约束
+
+- `CliProfile.command` 仅白名单 `claude`、`claude-code`
+- `baseArgs` 禁止 shell 元字符 `;&|$()`
+- `envVars` 禁止危险 key: `PATH`, `LD_PRELOAD`, `NODE_OPTIONS` 等
+- 环境变量通过 `envOverrides` 注入，禁止修改 `process.env`

package/.next/standalone/tower/docs/modules/assets-notes.md

@@ -0,0 +1,68 @@
+---
+title: Assets & Notes 模块
+description: 项目资产管理（图片、文档上传）和项目笔记系统
+---
+
+**Slug:** `assets`
+
+## 功能介绍
+
+资产管理和笔记系统为项目提供文件存储和知识记录能力。
+
+### 资产管理
+
+- **文件上传**：支持上传图片和文档到项目，作为项目资料的一部分
+- **画廊浏览**：资产页面以画廊形式展示所有上传的图片，支持灯箱预览大图
+- **文档预览**：上传的文本文档可以直接在浏览器中预览内容
+- **文件定位**：支持在系统文件管理器中快速定位资产文件
+
+### 笔记系统
+
+- **项目笔记**：在项目下创建和管理笔记，按分类组织
+- **任务笔记**：为特定任务记录笔记
+- **分类管理**：笔记支持分类筛选，方便组织和查找
+- **Dreaming 洞察**：任务执行完成后的 Dreaming 洞察会自动保存为笔记，记录 AI 对任务执行过程的结构化分析
+
+## 详细说明
+
+### 资产存储
+
+资产文件按项目 ID 组织存储，通过内部 API 和公开 API 两种路径提供文件访问服务。
+
+### 笔记与任务关联
+
+笔记可以独立存在于项目下，也可以关联到特定任务。任务完成后生成的 Dreaming 洞察通过 `insightNoteId` 字段关联到执行记录。
+
+## 文件清单
+
+### Server Actions
+
+| 文件 | 说明 |
+|------|------|
+| `asset-actions.ts` | 资产上传和管理 |
+| `note-actions.ts` | 笔记 CRUD |
+
+### API Routes
+
+| 路由 | 说明 |
+|------|------|
+| `/api/internal/assets/[projectId]/[filename]` | 内部资产文件服务 |
+| `/api/internal/assets/reveal` | 资产文件定位 |
+| `/api/files/assets/[projectId]/[filename]` | 公开资产服务 |
+
+### 页面
+
+| 路由 | 说明 |
+|------|------|
+| `/workspaces/[id]/assets` | 资产画廊 |
+| `/workspaces/[id]/notes` | 笔记管理 |
+
+### 组件
+
+**资产** (`src/components/assets/`)：`asset-upload`, `asset-list`, `image-lightbox`, `text-preview`
+
+**笔记** (`src/components/notes/`)：`note-editor`, `note-list`, `note-card`, `category-filter`
+
+### MCP Tools
+
+- `manage_assets` / `manage_notes`（via `note-asset-tools.ts`）

package/.next/standalone/tower/docs/modules/assistant.md

@@ -0,0 +1,74 @@
+---
+title: Assistant 模块
+description: AI 助手聊天系统，通过 Claude API 提供流式对话能力
+---
+
+**Slug:** `assistant`
+
+## 功能介绍
+
+内置 AI 助手，通过 Claude Agent SDK 提供流式聊天能力。助手定位是「任务管理操作员」，可以通过 Tower MCP 工具帮你管理工作区、项目、任务。
+
+主要能力：
+
+- **流式对话**：基于 Claude Agent SDK 的 SSE 流式聊天，实时显示 AI 回复
+- **任务管理操作**：助手可以通过 MCP 工具帮你创建工作区、项目、任务，查询状态，执行搜索等操作
+- **图片上传**：支持多模态输入，上传图片后 AI 可以理解图片内容并结合对话上下文回答
+- **会话恢复**：聊天记录自动保存，重新打开助手后可以继续之前的对话
+- **会话管理**：支持创建新会话、切换历史会话
+
+## 详细说明
+
+### 助手角色
+
+助手通过 Tower MCP Server 获得工具能力，可以执行：
+- 查看和管理工作区、项目
+- 创建和更新任务，移动任务状态
+- 搜索任务、项目、仓库
+- 查看每日摘要和待办
+- 管理标签
+
+### 消息流
+
+用户消息通过 SSE（Server-Sent Events）发送到后端，Claude Agent SDK 流式返回回复，前端实时渲染。
+
+## 文件清单
+
+### Server Actions (`src/actions/assistant-actions.ts`)
+
+会话管理和消息收发。
+
+### API Routes
+
+| 路由 | 说明 |
+|------|------|
+| `/api/internal/assistant/route.ts` | 助手管理 |
+| `/api/internal/assistant/chat/route.ts` | 聊天消息（SSE 流式） |
+| `/api/internal/assistant/images/route.ts` | 图片上传 |
+| `/api/internal/assistant/sessions/route.ts` | 会话管理 |
+
+### 组件 (`src/components/assistant/`)
+
+| 组件 | 说明 |
+|------|------|
+| `assistant-chat.tsx` | 聊天主界面 |
+| `assistant-panel.tsx` | 助手面板 |
+| `image-preview.tsx` | 图片预览 |
+| `chat-bubble.tsx` | 消息气泡 |
+
+### Hooks (`src/hooks/`)
+
+| Hook | 说明 |
+|------|------|
+| `use-assistant-chat.ts` | SSE 事件处理 |
+| `use-image-upload.ts` | 图片上传 |
+| `sse-event-reducer.ts` | SSE 流解析 |
+
+### 核心库
+
+| 文件 | 说明 |
+|------|------|
+| `lib/assistant-sessions.ts` | 会话管理 |
+| `lib/assistant-message-converter.ts` | 消息格式转换 |
+| `lib/claude-session.ts` | Claude API 会话 |
+| `lib/build-multimodal-prompt.ts` | 多模态 prompt 构建 |

package/.next/standalone/tower/docs/modules/board.md

@@ -0,0 +1,56 @@
+---
+title: Board 模块
+description: 看板 UI，Kanban 列展示任务卡片，支持拖拽排序和筛选
+---
+
+**Slug:** `board`
+
+## 功能介绍
+
+看板是任务的可视化管理界面，以 Kanban 列按状态分组展示项目下的任务卡片。
+
+主要能力：
+
+- **5 列看板**：按 TODO、IN_PROGRESS、IN_REVIEW、DONE、CANCELLED 五种状态分列展示
+- **拖拽移动**：拖拽卡片跨列移动自动更新任务状态，同列内拖拽调整排序
+- **右键菜单**：右键点击任务卡片可以快速切换状态、启动执行、跳转到任务详情页
+- **标签筛选**：按标签过滤显示，只展示包含选中标签的任务
+- **优先级筛选**：按优先级过滤，快速定位高优任务
+- **任务卡片**：每张卡片显示标题、描述摘要、优先级徽章、标签列表
+- **置顶功能**：置顶的任务始终显示在所在列的顶部，不受排序影响
+- **归档视图**：已完成和已取消的任务可以在归档页面查看
+
+## 详细说明
+
+### 交互行为
+
+- 拖拽卡片跨列 → 调用 `updateTaskStatus` 更新状态
+- 拖拽卡片同列 → 更新 `order` 字段调整排序
+- 筛选 → 按标签、优先级组合过滤显示
+
+### 状态管理
+
+使用 Zustand store（`src/stores/board-store.ts`）管理列状态、筛选条件、拖拽状态。
+
+## 文件清单
+
+### 组件 (`src/components/board/`)
+
+| 组件 | 说明 |
+|------|------|
+| `kanban-board.tsx` | 看板主容器 |
+| `board-column.tsx` | 状态列 |
+| `task-card.tsx` | 任务卡片 |
+| `board-filters.tsx` | 筛选器（标签、优先级） |
+| `board-stats.tsx` | 统计面板 |
+
+### 页面
+
+| 路由 | 说明 |
+|------|------|
+| `/workspaces/[workspaceId]` | 看板主页面 (`board-page-client.tsx`) |
+| `/workspaces/[workspaceId]/archive` | 归档任务 (`archive-page-client.tsx`) |
+
+### 状态管理 (`src/stores/board-store.ts`)
+
+Zustand store，管理列状态、筛选条件、拖拽状态。

package/.next/standalone/tower/docs/modules/git.md

@@ -0,0 +1,61 @@
+---
+title: Git 模块
+description: Git 操作集成，包括仓库克隆、Worktree 隔离、Diff 解析、Merge 操作
+---
+
+**Slug:** `git`
+
+## 功能介绍
+
+Git 集成提供 Worktree 隔离执行能力，让每个任务在独立分支中工作，不影响主分支。
+
+主要能力：
+
+- **Worktree 隔离**：任务执行时自动创建 Git Worktree，在独立分支中工作。Claude CLI 的所有代码修改都在隔离的工作目录中进行，不影响项目主分支
+- **Diff 查看**：任务完成后可以查看工作分支与基础分支之间的代码差异，逐文件浏览变更内容
+- **一键合并**：确认 Diff 无误后，通过合并确认对话框将工作分支的修改合并回基础分支
+- **仓库克隆**：支持从 Git URL 克隆仓库到本地
+- **分支管理**：管理项目的分支信息
+- **自动检测**：导入本地项目时自动检测 Git remote 信息，填充 Git URL
+
+## 详细说明
+
+### Worktree 机制
+
+- 创建任务时通过 `useWorktree` / `baseBranch` 参数控制是否启用 Worktree 隔离
+- 每个 Task 执行可在独立 worktree 中进行
+- `TaskExecution.worktreePath` / `worktreeBranch` 记录隔离信息
+- 执行完成后，工作分支的修改可以通过 Merge 操作合并回基础分支
+
+### Git 路径映射
+
+在设置页面配置 host/owner 到本地路径的映射规则后，导入 Git 项目时可以自动解析 Git URL 对应的本地目录。
+
+## 文件清单
+
+### Server Actions (`src/actions/git-actions.ts`)
+
+Git 克隆、分支管理等操作。
+
+### API Routes
+
+| 路由 | 说明 |
+|------|------|
+| `/api/git/route.ts` | Git 操作 API |
+| `/api/tasks/[taskId]/diff/route.ts` | 获取任务 diff |
+| `/api/tasks/[taskId]/merge/route.ts` | 执行 merge |
+
+### 核心库
+
+| 文件 | 说明 |
+|------|------|
+| `lib/git-url.ts` | Git URL 解析和规范化 |
+| `lib/worktree.ts` | Git worktree 创建和管理 |
+| `lib/diff-parser.ts` | Git diff 解析器 |
+
+### 组件
+
+| 组件 | 说明 |
+|------|------|
+| `task-diff-view.tsx` | Diff 可视化 |
+| `task-merge-confirm-dialog.tsx` | Merge 确认对话框 |

package/.next/standalone/tower/docs/modules/i18n.md

@@ -0,0 +1,38 @@
+---
+title: I18n 模块
+description: 国际化系统，支持中文和英文双语
+---
+
+**Slug:** `i18n`
+
+## 功能介绍
+
+国际化支持中文和英文双语，所有用户可见的文本使用 `t("key")` 函数获取翻译。
+
+主要能力：
+
+- **双语支持**：完整的中文和英文界面，覆盖所有页面和组件
+- **即时切换**：在设置页面切换语言后即时生效，无需刷新页面
+- **翻译函数**：使用 `t("key")` 函数包裹所有用户可见文本，确保翻译覆盖
+
+## 详细说明
+
+### 翻译规范
+
+- 所有用户可见文本必须用 `t("key")` 包裹
+- 同时维护 zh / en 两套翻译文件
+- Key 命名格式：`模块.功能.描述`（如 `board.column.todo`、`settings.general.theme`）
+
+### 语言切换
+
+在设置页面的通用配置区域选择语言，切换后全局所有文本即时更新。
+
+## 文件清单
+
+### 核心库 (`src/lib/i18n/`)
+
+i18n 配置和资源管理。
+
+### 使用
+
+- `src/lib/i18n.tsx` — i18n Provider 和 hook

package/.next/standalone/tower/docs/modules/mcp.md

@@ -0,0 +1,68 @@
+---
+title: MCP 模块
+description: Model Context Protocol Server，向外部 AI Agent 暴露 Tower 的工具能力
+---
+
+**Slug:** `mcp`
+
+## 功能介绍
+
+Tower 暴露 MCP Server 供外部 AI Agent 调用，通过 stdio 传输协议运行。外部 Agent（如 Claude CLI、OpenClaw、Paperclip）可以通过 MCP 协议管理 Tower 的全部资源。
+
+主要能力：
+
+- **工作区管理**：创建、更新、删除工作区
+- **项目管理**：创建、更新、删除项目，识别项目
+- **任务管理**：创建、更新、删除、移动任务
+- **标签管理**：创建、删除标签，设置任务标签
+- **终端交互**：查询终端输出、发送终端输入、获取执行状态
+- **搜索**：全局搜索任务、项目、仓库
+- **报告**：每日摘要、每日待办
+- **笔记和资产**：管理项目笔记和资产文件
+
+共 24 个工具，分 7 大类。
+
+## 详细说明
+
+### 启动方式
+
+```json
+{
+  "mcpServers": {
+    "tower": {
+      "command": "npx",
+      "args": ["tsx", "<project-root>/src/mcp/index.ts"]
+    }
+  }
+}
+```
+
+### 内部 HTTP 桥接
+
+MCP stdio 进程无法访问内存中的 PTY 会话，通过内部 HTTP 路由桥接：
+- `GET /api/internal/terminal/[taskId]/buffer` — 获取终端输出
+- `POST /api/internal/terminal/[taskId]/input` — 发送终端输入
+- localhost 限定，仅允许本机访问
+
+## 文件清单
+
+### 核心 (`src/mcp/`)
+
+| 文件 | 说明 |
+|------|------|
+| `server.ts` | MCP Server 初始化和配置 |
+| `db.ts` | MCP 专用数据库连接 |
+| `index.ts` | 入口和导出 |
+
+### 工具模块 (`src/mcp/tools/`)
+
+| 文件 | 工具数 | 说明 |
+|------|--------|------|
+| `workspace-tools.ts` | 4 | Workspace CRUD |
+| `project-tools.ts` | 5 | Project CRUD + identify |
+| `task-tools.ts` | 5 | Task CRUD + move |
+| `label-tools.ts` | 4 | Label CRUD + set_task_labels |
+| `terminal-tools.ts` | 3 | 终端输出/输入/状态 |
+| `search-tools.ts` | 1 | 全局搜索 |
+| `report-tools.ts` | 2 | daily_summary / daily_todo |
+| `note-asset-tools.ts` | — | 笔记和资产管理 |

package/.next/standalone/tower/docs/modules/missions.md

@@ -0,0 +1,54 @@
+---
+title: Missions 模块
+description: 多任务监控面板，跨工作区展示所有运行中的 Task 执行
+---
+
+**Slug:** `missions`
+
+## 功能介绍
+
+Mission Control 是多任务监控面板，跨工作区展示所有正在运行的任务执行，每个卡片嵌入实时终端，可以同时观察多个任务的执行状态。
+
+主要能力：
+
+- **网格布局**：支持多种预设布局（1x1、2x1、3x2、2x2、4x2、3x3），布局选择持久化到 localStorage，下次打开自动恢复
+- **实时终端**：每个任务卡片嵌入 xterm.js 终端，实时显示 Claude CLI 的输出
+- **工作区筛选**：通过下拉框按工作区过滤，只显示特定工作区下的运行任务
+- **启动新任务**：通过 Task Picker 选择任务启动新的执行
+- **恢复历史会话**：选择之前的执行记录，通过 sessionId 恢复 Claude CLI 会话
+- **拖拽排序**：使用 dnd-kit 拖拽调整卡片顺序
+- **自动更新**：4 秒轮询刷新执行状态，任务完成后卡片自动移除
+- **停止执行**：手动停止正在运行的任务，卡片随即移除
+
+## 详细说明
+
+### 卡片生命周期
+
+- 启动执行或恢复会话后，卡片出现在面板中
+- 执行过程中实时显示终端输出
+- 手动停止或自然完成后，卡片自动从面板移除
+- 通过 4 秒轮询检测状态变化
+
+## 文件清单
+
+### 页面
+
+| 路由 | 文件 | 说明 |
+|------|------|------|
+| `/missions` | `missions-client.tsx` | Missions 主页面 |
+
+### 组件 (`src/components/missions/`)
+
+| 组件 | 说明 |
+|------|------|
+| `mission-card.tsx` | 任务执行卡片（含终端） |
+| `grid-preset-picker.tsx` | 网格布局选择器 |
+| `task-picker-dialog.tsx` | 任务选择对话框 |
+
+### Server Actions
+
+- `getActiveExecutionsAcrossWorkspaces()` — 获取所有 RUNNING 执行
+
+### 状态管理 (`src/stores/task-execution-store.ts`)
+
+Zustand store，管理活跃执行状态。

package/.next/standalone/tower/docs/modules/project.md

@@ -0,0 +1,65 @@
+---
+title: Project 模块
+description: 项目管理，支持普通项目和 Git 项目两种类型
+---
+
+**Slug:** `project`
+
+## 功能介绍
+
+项目属于工作区，是任务的组织单元。可以关联 Git 仓库或本地目录，创建时根据是否提供 Git URL 自动判定项目类型（普通项目 / Git 项目）。
+
+主要操作：
+
+- **创建项目**：在工作区下新建项目，填写名称、别名、描述等基本信息
+- **关联 Git 仓库**：提供 Git URL 后自动标记为 GIT 类型项目，支持后续的 Worktree 隔离执行和 Diff/Merge 功能
+- **关联本地目录**：指定 localPath，用于代码搜索、预览、项目分析等功能
+- **生成描述**：点击「生成描述」按钮，AI 自动分析项目的 localPath 目录结构，生成结构化的项目描述
+- **导入本地项目**：通过导入对话框选择本地目录，自动检测 Git remote 信息并填充
+- **删除项目**：级联删除项目下的所有任务
+
+## 详细说明
+
+### 数据模型
+
+```
+Project (id, name, alias?, description?, type, gitUrl?, localPath?)
+  ├── Task[]
+  └── Repository[]
+```
+
+- `type`: `NORMAL` | `GIT`，由 `gitUrl` 是否存在自动推导，不可手动设置
+- `workspaceId`: FK → Workspace，级联删除
+
+### 项目类型
+
+项目类型由 `gitUrl` 字段自动推导：
+- 提供了 `gitUrl` → `GIT` 类型，支持 Worktree 隔离、Diff 查看、Merge 操作
+- 未提供 `gitUrl` → `NORMAL` 类型，仅支持基础任务管理
+
+## 文件清单
+
+### Server Actions (`src/actions/`)
+
+| 文件 | 函数 | 说明 |
+|------|------|------|
+| `workspace-actions.ts` | `createProject`, `updateProject`, `deleteProject` | 项目 CRUD |
+| `workspace-actions.ts` | `getProjectByLocalPath(path)` | 按本地路径查找 |
+| `workspace-actions.ts` | `getRecentLocalProjects(limit?)` | 最近本地项目 |
+| `project-actions.ts` | 项目分析相关 | 项目描述生成等 |
+
+### 组件 (`src/components/project/`)
+
+| 组件 | 说明 |
+|------|------|
+| `create-project-dialog.tsx` | 创建项目对话框 |
+| `import-project-dialog.tsx` | 导入项目对话框 |
+
+### MCP Tools (`src/mcp/tools/project-tools.ts`)
+
+- `list_projects` / `create_project` / `update_project` / `delete_project` / `identify_project`
+
+## 约束
+
+- `type` 字段只读，由 `gitUrl` 存在性决定
+- 删除项目级联删除所有 Task

package/.next/standalone/tower/docs/modules/search.md

@@ -0,0 +1,57 @@
+---
+title: Search 模块
+description: 全局搜索和代码搜索，覆盖 Task、Project、Repository
+---
+
+**Slug:** `search`
+
+## 功能介绍
+
+全局搜索覆盖任务、项目、仓库、笔记、资产，基于 SQLite FTS5 全文搜索引擎实现快速检索。
+
+主要能力：
+
+- **全局搜索**：在搜索对话框中输入关键词，搜索所有任务标题/描述、项目名称、仓库信息、笔记内容、资产文件名
+- **分类筛选**：支持按分类过滤搜索结果 — 任务、项目、仓库、笔记、资产
+- **代码搜索**：在项目的 localPath 中搜索代码文件，支持关键词匹配和文件类型过滤
+- **快捷键触发**：通过快捷键快速唤起搜索对话框
+
+## 详细说明
+
+### 全文搜索
+
+基于 SQLite FTS5 实现，需要先运行 `pnpm db:init-fts` 初始化全文搜索索引。索引覆盖任务、项目、仓库等核心实体的文本字段。
+
+### 代码搜索
+
+项目内代码搜索在项目的 `localPath` 目录中执行，搜索代码文件内容，返回匹配的文件路径和代码片段。
+
+## 文件清单
+
+### Server Actions
+
+| 文件 | 函数 | 说明 |
+|------|------|------|
+| `search-actions.ts` | `globalSearch(query, category?)` | 全局搜索 |
+| `search-code-actions.ts` | 代码搜索 | 项目内代码搜索 |
+
+### 核心库
+
+| 文件 | 说明 |
+|------|------|
+| `lib/search.ts` | 全文搜索实现 |
+| `lib/fts.ts` | SQLite FTS 处理 |
+
+### 组件
+
+- `src/components/layout/search-dialog.tsx` — 全局搜索对话框
+
+### MCP Tools (`src/mcp/tools/search-tools.ts`)
+
+- `search` — 按 query 搜索 task/project/repository
+
+## 初始化
+
+```bash
+pnpm db:init-fts  # 创建全文搜索索引
+```