tower-studio 0.1.0 → 0.1.2

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

@@ -0,0 +1,72 @@
+---
+title: Settings 模块
+description: 系统配置管理，包括通用配置、AI 工具配置、CLI Profile 管理
+---
+
+**Slug:** `settings`
+
+## 功能介绍
+
+系统设置分为多个配置区域，管理 Tower 的全局行为和 AI 执行参数。
+
+### 配置区域
+
+- **通用配置**：主题切换（暗色 / 亮色 / 跟随系统）、语言切换（中文 / 英文）、默认终端应用
+- **终端配置**：WebSocket 端口设置、空闲超时时间
+- **系统配置**：上传文件大小限制、最大并发执行数、Git 操作超时时间、搜索参数
+- **CLI Profile**：配置 AI CLI 的命令（如 `claude`）、启动参数、环境变量。CLI Profile 影响所有任务执行时使用的 CLI 命令，仅允许一个默认配置
+- **Prompt 模板**：自定义 AI 提示词模板，可以按工作区隔离。任务执行时可以选择使用哪个 Prompt 模板
+- **Agent 配置**：管理 AI 代理的附加 prompt 和设置，每个 Agent 配置有唯一的 `(agent, configName)` 约束
+- **Git 路径映射**：配置 host/owner 到本地路径的映射规则，自动解析 Git URL 对应的本地目录
+
+## 详细说明
+
+### CLI Profile
+
+CLI Profile 控制 PTY 终端使用的 CLI 命令和参数：
+- `command`: CLI 命令（默认 `claude`），仅允许 `claude` / `claude-code`
+- `baseArgs`: JSON 字符串数组，传给 CLI 的启动参数
+- `envVars`: JSON 对象，注入到 PTY 环境变量
+- `isDefault`: 仅允许一个默认配置
+
+### Agent 配置
+
+Agent 配置管理 AI 代理的附加 prompt 和高级设置：
+- 唯一约束: `(agent, configName)`
+- 支持全局和工作区级别的 Prompt 模板
+
+## 文件清单
+
+### 页面
+
+| 路由 | 说明 |
+|------|------|
+| `/settings` | 设置主页面 |
+
+### 组件 (`src/components/settings/`)
+
+| 组件 | 说明 |
+|------|------|
+| `general-config.tsx` | 通用配置 |
+| `system-config.tsx` | 系统配置 |
+| `ai-tools-config.tsx` | AI 工具配置 |
+| `cli-profile-config.tsx` | CLI Profile 管理 |
+
+### Server Actions
+
+| 文件 | 说明 |
+|------|------|
+| `config-actions.ts` | 系统配置读写 |
+| `agent-config-actions.ts` | Agent 配置管理 |
+| `cli-profile-actions.ts` | CLI Profile CRUD |
+
+### 数据模型
+
+**CliProfile**: 控制 PTY 使用的 CLI 命令和参数
+- `command`: CLI 命令（默认 `claude`）
+- `baseArgs`: JSON 字符串数组
+- `envVars`: JSON 对象
+- `isDefault`: 仅允许一个默认配置
+
+**AgentConfig**: Agent 特定配置
+- 唯一约束: `(agent, configName)`

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

@@ -0,0 +1,82 @@
+---
+title: Task 模块
+description: Tower 的核心工作单元，支持标签、执行记录、消息等关联
+---
+
+**Slug:** `task`
+
+## 功能介绍
+
+任务是 Tower 的核心工作单元，在看板上以卡片形式展示。每个任务属于一个项目，通过状态字段在看板列间流转。
+
+主要能力：
+
+- **状态流转**：支持 5 种状态 — TODO → IN_PROGRESS → IN_REVIEW → DONE → CANCELLED，拖拽卡片或右键菜单即可切换
+- **优先级**：4 个级别 — LOW / MEDIUM / HIGH / CRITICAL，影响卡片上的优先级徽章显示
+- **自定义标签**：关联工作区标签池中的标签，支持多标签组合筛选
+- **置顶**：置顶的任务始终显示在看板列顶部
+- **基础分支设置**：可以指定 Git 基础分支，任务执行时自动创建 Worktree 在独立分支中工作，不影响主分支
+- **执行任务**：点击执行后自动创建 PTY 终端会话，Claude CLI 在独立环境中运行任务
+- **执行摘要**：任务完成后自动生成执行摘要（50 字简述）和 Dreaming 洞察（结构化 JSON），洞察自动保存为笔记
+
+## 详细说明
+
+### 数据模型
+
+```
+Task (id, title, description?, status, priority, order)
+  ├── TaskLabel[] → Label
+  ├── TaskExecution[]
+  └── TaskMessage[]
+```
+
+- `status`: `TODO` | `IN_PROGRESS` | `IN_REVIEW` | `DONE` | `CANCELLED`
+- `priority`: `LOW` | `MEDIUM` | `HIGH` | `CRITICAL`
+- `order`: 看板列内排序（升序，小值在上）
+- `projectId`: FK → Project，级联删除
+
+### Label 子系统
+
+- Server Actions: `src/actions/label-actions.ts`
+- MCP Tools: `src/mcp/tools/label-tools.ts`
+- `set_task_labels` / `setTaskLabels` 执行全量替换（非合并）
+
+## 文件清单
+
+### Server Actions (`src/actions/task-actions.ts`)
+
+| 函数 | 说明 |
+|------|------|
+| `createTask({ title, projectId, ... })` | 创建任务 |
+| `updateTask(taskId, data)` | 更新任务 |
+| `updateTaskStatus(taskId, status)` | 状态流转 |
+| `deleteTask(taskId)` | 删除任务 |
+| `getProjectTasks(projectId)` | 获取项目下所有任务 |
+
+### 页面
+
+| 路由 | 文件 | 说明 |
+|------|------|------|
+| `/workspaces/[id]/tasks/[taskId]` | `task-page-client.tsx` | 任务详情页 |
+
+### 组件 (`src/components/task/`)
+
+| 组件 | 说明 |
+|------|------|
+| `task-detail-panel.tsx` | 任务元信息面板 |
+| `task-terminal.tsx` | 终端 UI |
+| `task-diff-view.tsx` | Git diff 视图 |
+| `task-merge-confirm-dialog.tsx` | 合并确认 |
+| `code-editor.tsx` | 代码编辑器 |
+| `file-tree.tsx` | 文件树 |
+| `execution-timeline.tsx` | 执行历史时间线 |
+
+### MCP Tools (`src/mcp/tools/task-tools.ts`)
+
+- `list_tasks` / `create_task` / `update_task` / `move_task` / `delete_task`
+
+## 约束
+
+- `order` 字段控制看板排序，创建时不要破坏现有排序
+- Label 替换是全量操作，需传完整 labelIds 数组
+- 删除任务级联删除 Message 和 Execution

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

@@ -0,0 +1,70 @@
+---
+title: Terminal 模块
+description: PTY 终端系统，为每个 Task 提供独立的 Claude CLI 终端会话
+---
+
+**Slug:** `terminal`
+
+## 功能介绍
+
+每个任务有独立的终端会话，通过 xterm.js 在浏览器中渲染完整的终端界面。
+
+主要能力：
+
+- **实时终端**：通过 WebSocket 实时传输终端 I/O，支持完整的 ANSI 渲染（颜色、进度条、光标移动）
+- **键盘交互**：支持完整的键盘输入，可以直接在终端中和 Claude CLI 对话、回答问题、确认操作
+- **断连保活**：断开连接后会话不会立即销毁 — 运行中的会话保活 2 小时，已退出的会话保活 5 分钟。重连后不丢失任何输出
+- **多客户端查看**：同一个终端会话支持多个客户端同时查看，任务详情页和 Missions 面板可以同时显示同一个终端
+- **会话恢复**：支持通过 sessionId 恢复之前的 Claude CLI 会话，继续上一次的对话上下文
+
+## 详细说明
+
+### 架构
+
+```
+Client (xterm.js) ←→ WebSocket ←→ ws-server.ts ←→ PTY Session (node-pty)
+                                                         ↕
+                                                    session-store.ts
+```
+
+### 生命周期
+
+- 每个 taskId 只能有一个活跃 PTY 会话
+- 并发上限由 `system.maxConcurrentExecutions` 配置（默认 20）
+- SIGTERM 时自动清理所有会话
+- `AI_MANAGER_TASK_ID` 和 `CALLBACK_URL` 注入到 PTY 环境变量
+- 禁止修改 `process.env`，使用 `envOverrides`
+
+## 文件清单
+
+### 核心库 (`src/lib/pty/`)
+
+| 文件 | 说明 |
+|------|------|
+| `pty-session.ts` | PTY 会话管理（node-pty 封装） |
+| `session-store.ts` | 内存中 PTY 会话存储，按 taskId 索引 |
+| `ws-server.ts` | WebSocket 服务器，端口由 `terminal.wsPort` 配置 |
+
+### API Routes
+
+| 路由 | 方法 | 说明 |
+|------|------|------|
+| `/api/internal/terminal/[taskId]/start` | POST | 启动 PTY 会话 |
+| `/api/internal/terminal/[taskId]/buffer` | GET | 获取终端输出缓冲 |
+| `/api/internal/terminal/[taskId]/input` | POST | 发送输入到终端 |
+
+### Server Actions (`src/actions/agent-actions.ts`)
+
+| 函数 | 说明 |
+|------|------|
+| `startPtyExecution(taskId, prompt)` | 启动 Claude CLI PTY |
+| `resumePtyExecution(taskId, sessionId)` | 恢复会话 |
+| `stopPtyExecution(taskId)` | 终止会话 |
+
+### 组件
+
+- `src/components/task/task-terminal.tsx` — xterm.js 终端 UI
+
+### MCP Tools (`src/mcp/tools/terminal-tools.ts`)
+
+- `get_task_terminal_output` / `send_task_terminal_input` / `get_task_execution_status`

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

@@ -0,0 +1,68 @@
+---
+title: Workspace 模块
+description: Tower 顶层容器，管理项目和标签的命名空间
+---
+
+**Slug:** `workspace`
+
+## 功能介绍
+
+工作区是 Tower 的顶层容器，可以创建多个工作区来组织不同团队或项目群。每个工作区有独立的标签池，工作区下的项目共享这些标签。
+
+主要操作：
+
+- **创建工作区**：指定名称和可选描述，作为项目的顶层分组
+- **重命名和描述编辑**：随时更新工作区名称和描述信息
+- **删除工作区**：级联删除工作区下的所有项目和任务，操作不可逆
+- **标签管理**：每个工作区有独立的标签池，除了全局内置标签外，可以创建工作区专属标签供项目内的任务使用
+
+## 详细说明
+
+### 数据模型
+
+```
+Workspace (id, name, description?)
+  ├── Project[]
+  └── Label[]
+```
+
+- `id`: cuid
+- `name`: 必填
+- `description`: 可选
+- 级联删除：删除 Workspace 会删除所有 Project 和 Label
+
+### 标签体系
+
+工作区下的 Label 分为两类：
+- **builtin（内置标签）**：全局共享，不可删除，所有工作区可见
+- **workspace-scoped（工作区标签）**：仅在当前工作区内可见，可以自由创建和删除
+
+## 文件清单
+
+### Server Actions (`src/actions/workspace-actions.ts`)
+
+| 函数 | 说明 |
+|------|------|
+| `getWorkspaces()` | 列出所有工作区 |
+| `getWorkspaceById(id)` | 按 ID 获取 |
+| `createWorkspace({ name, description? })` | 创建 |
+| `updateWorkspace(id, data)` | 更新 |
+| `deleteWorkspace(id)` | 删除（级联） |
+| `getWorkspacesWithProjects()` | 含项目列表 |
+| `getWorkspacesWithRecentTasks(limit?)` | 含最近任务 |
+
+### 页面
+
+| 路由 | 文件 | 说明 |
+|------|------|------|
+| `/workspaces` | `src/app/workspaces/page.tsx` | 工作区列表 |
+| `/workspaces/[id]` | `src/app/workspaces/[workspaceId]/` | 工作区详情（看板） |
+
+### MCP Tools (`src/mcp/tools/workspace-tools.ts`)
+
+- `list_workspaces` / `create_workspace` / `update_workspace` / `delete_workspace`
+
+## 约束
+
+- Workspace 下的 Label 分为 builtin（全局）和 workspace-scoped
+- builtin Label 不可删除

package/.next/standalone/tower/docs/package.json

@@ -0,0 +1,11 @@
+{
+  "private": true,
+  "scripts": {
+    "dev": "vitepress dev",
+    "build": "vitepress build",
+    "preview": "vitepress preview"
+  },
+  "devDependencies": {
+    "vitepress": "^1.6.3"
+  }
+}