公共可用页面

AweeClaw 客户端内置了一批公共面板组件，所有场景（声明式 / 编程式）均可直接引用，无需自行实现。这些面板覆盖了文件管理、知识库、任务、项目、自动化等通用功能，数据通过后端 API 统一存储，跨场景共享。

上一篇：左侧菜单配置

面板总览

面板	component 值	数据存储	推荐布局	说明
文件浏览器	`ExplorerView`	本地文件系统	侧边栏	工作区文件树管理
知识库	`KnowledgeView`	后端 API	wideMode	文档/资料的上传、索引、检索
任务工作台	`TaskWorkspace`	后端 API	wideMode	看板/列表双视图的任务管理
项目管理	`ProjectsView`	后端 API	wideMode	多 Tab 详情的项目管理
自动化	`AutomationView`	后端 API	wideMode	触发器+动作的规则引擎
笔记	`NotesView`	本地存储	侧边栏	快速记录
书签	`BookmarksView`	本地存储	侧边栏	文件/位置书签
提示词库	`PromptsView`	后端 API	侧边栏	可复用提示词模板
全局搜索	`SearchView`	本地索引	侧边栏	跨文件内容搜索
Git 管理	`GitView`	本地 Git	侧边栏	源码版本控制
问题诊断	`ProblemsView`	实时计算	侧边栏	代码问题与诊断
符号大纲	`OutlineView`	实时计算	侧边栏	当前文件符号结构
Shell 终端	`ShellView`	本地终端	侧边栏	命令行交互

标注「后端 API」的面板需要用户登录后端账号；标注「本地存储」的面板离线可用。

生产力套件

「任务 → 项目 → 自动化」三个面板构成完整的生产力套件，它们之间通过 projectId 关联，形成 项目容纳任务、自动化驱动任务 的闭环：

┌─────────────────────────────────────────────────┐
│                   ProjectsView                   │
│  ┌───────────┐  ┌───────────┐  ┌─────────────┐ │
│  │  概览 Tab  │  │  任务 Tab  │  │  设置 Tab    │ │
│  │  统计仪表  │  │  关联任务  │  │  状态流转    │ │
│  └───────────┘  └─────┬─────┘  └─────────────┘ │
│                       │ projectId                 │
│                       ▼                           │
│                ┌──────────────┐                   │
│                │ TaskWorkspace │                   │
│                │  看板 / 列表   │                   │
│                │  子任务 / 排序  │                   │
│                └──────┬───────┘                   │
│                       │ 触发动作                   │
│                       ▼                           │
│                ┌──────────────┐                   │
│                │AutomationView│                   │
│                │ 触发器 + 动作  │                   │
│                │ 运行历史      │                   │
│                └──────────────┘                   │
└─────────────────────────────────────────────────┘

TaskWorkspace — 任务工作台

功能特性

功能	说明
双视图切换	看板视图（按状态分列拖拽）/ 列表视图（紧凑表格）
状态流转	TODO → IN_PROGRESS → BLOCKED → DONE / CANCELED，自动维护时间戳
子任务	支持父子任务层级，级联软删除
拖拽排序	支持 `sortOrder` 排序和跨项目移动
筛选搜索	按状态、优先级、标签、关键字、截止时间筛选
AI 接力	任务关联 `threadId`，可恢复对话上下文继续工作
批量操作	批量修改状态、优先级、项目归属
来源标记	区分手动创建 / AI 生成 / 自动化触发 / 项目模板

数据模型

typescript

interface TaskItem {
  id: string
  userId: string
  projectId: string | null      // 所属项目（null 为独立任务）
  parentTaskId: string | null   // 父任务（null 为顶级任务）
  threadId: string | null       // 关联对话 ID（AI 接力用）
  title: string
  description: string | null
  status: 'TODO' | 'IN_PROGRESS' | 'BLOCKED' | 'DONE' | 'CANCELED'
  priority: 'LOW' | 'MEDIUM' | 'HIGH' | 'URGENT'
  source: 'MANUAL' | 'AI_GENERATED' | 'AUTOMATION' | 'PROJECT_TEMPLATE'
  tags: string[]
  dueAt: string | null          // 截止时间（ISO 8601）
  startedAt: string | null      // 开始时间（状态转为 IN_PROGRESS 时自动写入）
  completedAt: string | null    // 完成时间（状态转为 DONE 时自动写入）
  estimatedMin: number | null   // 预估耗时（分钟）
  actualMin: number | null      // 实际耗时（分钟）
  sortOrder: number             // 排序权重
  metadata: unknown             // 扩展元数据
  createdAt: string
  updatedAt: string
  children?: TaskItem[]         // 子任务（getById 时返回）
}

状态流转规则

TODO ────────► IN_PROGRESS ────────► DONE
  │                │                   │
  │                ▼                   │
  │            BLOCKED                 │
  │                │                   │
  └──────────────► ┴ ────────────────► CANCELED

当前状态	允许的下一个状态
`TODO`	`IN_PROGRESS`, `CANCELED`, `DONE`
`IN_PROGRESS`	`BLOCKED`, `DONE`, `CANCELED`, `TODO`
`BLOCKED`	`IN_PROGRESS`, `CANCELED`
`DONE`	`TODO`, `IN_PROGRESS`
`CANCELED`	`TODO`, `IN_PROGRESS`

后端 API

方法	路径	说明
`GET`	`/api/v1/tasks`	查询任务列表（支持筛选、分页）
`GET`	`/api/v1/tasks/:id`	获取任务详情（含子任务）
`POST`	`/api/v1/tasks`	创建任务
`PATCH`	`/api/v1/tasks/:id`	更新任务（含状态流转）
`DELETE`	`/api/v1/tasks/:id`	删除任务（软删除，级联子任务）
`POST`	`/api/v1/tasks/:id/reorder`	拖拽排序（支持跨项目移动）
`POST`	`/api/v1/tasks/:id/ai-resume`	AI 接力：获取关联对话上下文
`POST`	`/api/v1/tasks/batch`	批量更新任务

接入方式

typescript

// 在 scenario.json 或 getPlugin() 中声明
{
  id: 'tasks',
  icon: 'CheckSquare',
  label: 'Tasks',
  labelZh: '任务',
  component: 'TaskWorkspace',
  position: 2,
  wideMode: true,  // 必须启用宽屏模式
}

ProjectsView — 项目管理

功能特性

功能	说明
项目列表	展示所有项目（含统计：任务数、完成率、自动化规则数）
多 Tab 详情	概览 Tab / 任务 Tab / 设置 Tab，每个 Tab 独立组件
模板创建	从预置模板创建项目，自动生成任务清单（事务保证一致性）
状态流转	PLANNING → ACTIVE → ON_HOLD/COMPLETED → ARCHIVED
统计仪表	实时计算任务完成率、各状态任务分布
关联管理	关联工作区路径、知识库、对话线程
归档恢复	软删除 + 归档机制，数据可恢复
项目隔离	删除项目时任务保留为独立任务，不丢失用户数据

数据模型

typescript

interface ProjectItem {
  id: string
  userId: string
  name: string
  description: string | null
  icon: string | null          // 图标名（lucide-react）
  color: string | null         // 主题色（hex）
  status: 'PLANNING' | 'ACTIVE' | 'ON_HOLD' | 'COMPLETED' | 'ARCHIVED'
  visibility: 'PRIVATE' | 'SHARED' | 'PUBLIC'
  goal: string | null          // 项目目标
  workspacePaths: string[]     // 关联的工作区路径
  knowledgeBaseIds: string[]   // 关联的知识库 ID
  threadIds: string[]          // 关联的对话 ID
  tags: string[]
  dueAt: string | null         // 截止时间
  startedAt: string | null     // 启动时间
  completedAt: string | null   // 完成时间
  archivedAt: string | null    // 归档时间
  createdAt: string
  updatedAt: string
  stats?: ProjectStats         // 列表接口附带统计
}

interface ProjectStats {
  totalTasks: number
  doneTasks: number
  inProgressTasks: number
  blockedTasks: number
  todoTasks: number
  completionRate: number       // 0-1
  automationRuleCount: number
  conversationCount: number
}

项目状态流转

PLANNING ──► ACTIVE ──► COMPLETED ──► ARCHIVED
               │  ▲           │
               ▼  │           ▼
           ON_HOLD │       (可重新激活)
               │  │
               └──┘

后端 API

方法	路径	说明
`GET`	`/api/v1/projects`	查询项目列表（含统计）
`GET`	`/api/v1/projects/:id`	获取项目详情（含统计）
`GET`	`/api/v1/projects/:id/tasks`	获取项目下任务列表
`GET`	`/api/v1/projects/templates`	获取可用项目模板
`POST`	`/api/v1/projects`	创建项目
`POST`	`/api/v1/projects/from-template`	从模板创建项目（含任务清单）
`PATCH`	`/api/v1/projects/:id`	更新项目（含状态流转）
`DELETE`	`/api/v1/projects/:id`	删除项目（软删除）
`POST`	`/api/v1/projects/:id/archive`	归档项目

接入方式

typescript

{
  id: 'projects',
  icon: 'FolderKanban',
  label: 'Projects',
  labelZh: '项目',
  component: 'ProjectsView',
  position: 3,
  wideMode: true,
}

AutomationView — 自动化

功能特性

功能	说明
规则列表	展示所有自动化规则，支持启用/禁用切换
触发器配置	支持定时调度（cron）、Webhook、事件三种触发类型
动作配置	支持工作流、Agent、通知、Webhook、知识库、邮件六种动作
模板库	预置常用自动化模板，一键创建
手动执行	支持手动触发规则执行，便于调试
运行历史	记录每次执行的状态、耗时、输出、错误
运行统计	统计成功率、平均耗时、最近执行时间
项目关联	规则可绑定到特定项目，实现项目级自动化
安全控制	冷却时间（cooldownSeconds）、最大执行次数（maxExecutions）

数据模型

typescript

interface AutomationRule {
  id: string
  userId: string
  projectId: string | null      // 关联项目（null 为全局规则）
  templateId: string | null     // 来源模板 ID
  name: string
  description: string | null
  enabled: boolean
  triggerConfig: TriggerConfig
  actionConfig: ActionConfig
  priority: number              // 优先级（数字越大越优先）
  cooldownSeconds: number       // 冷却时间（秒），防止频繁触发
  maxExecutions: number         // 最大执行次数（0 为不限）
  executionCount: number        // 已执行次数
  lastExecutedAt: string | null
  lastError: string | null
  createdAt: string
  updatedAt: string
}

interface TriggerConfig {
  type: 'schedule' | 'webhook' | 'event'
  cron?: string                 // schedule 类型的 cron 表达式
  event?: string                // event 类型的事件名
  filter?: Record<string, unknown>  // 事件过滤条件
  path?: string                 // webhook 类型的路径
}

interface ActionConfig {
  type: 'workflow' | 'agent' | 'notification' | 'webhook' | 'knowledge' | 'email'
  workflowId?: string           // workflow 动作的工作流 ID
  agentId?: string              // agent 动作的 Agent ID
  prompt?: string               // agent 动作的提示词
  channel?: string              // notification 动作的渠道
  template?: string             // notification/email 动作的模板
  url?: string                  // webhook 动作的 URL
  knowledgeBaseId?: string      // knowledge 动作的知识库 ID
  inputMapping?: Record<string, string>  // 输入参数映射
}

interface AutomationRun {
  id: string
  ruleId: string
  triggerType: string
  triggerData: unknown
  status: 'SUCCESS' | 'FAILED' | 'TIMEOUT' | 'RUNNING'
  output: unknown
  error: string | null
  durationMs: number
  startedAt: string
  finishedAt: string | null
  rule?: { id: string; name: string }
}

触发器与动作矩阵

触发器 \ 动作	workflow	agent	notification	webhook	knowledge	email
`schedule` (cron)	✅	✅	✅	✅	✅	✅
`webhook`	✅	✅	✅	—	✅	✅
`event`	✅	✅	✅	✅	✅	✅

后端 API

方法	路径	说明
`GET`	`/api/v1/automation-rules`	查询规则列表
`GET`	`/api/v1/automation-rules/:id`	获取规则详情
`GET`	`/api/v1/automation-rules/templates`	获取可用模板
`GET`	`/api/v1/automation-rules/triggers`	获取可用触发器类型
`GET`	`/api/v1/automation-rules/actions`	获取可用动作类型
`GET`	`/api/v1/automation-rules/runs`	获取全局运行历史
`GET`	`/api/v1/automation-rules/:id/runs`	获取某规则的运行历史
`GET`	`/api/v1/automation-rules/:id/runs/stats`	获取运行统计
`POST`	`/api/v1/automation-rules`	创建规则
`POST`	`/api/v1/automation-rules/from-template`	从模板创建规则
`PATCH`	`/api/v1/automation-rules/:id`	更新规则
`DELETE`	`/api/v1/automation-rules/:id`	删除规则（级联删除运行历史）
`POST`	`/api/v1/automation-rules/:id/execute`	手动执行规则

接入方式

typescript

{
  id: 'automation',
  icon: 'Zap',
  label: 'Automation',
  labelZh: '自动化',
  component: 'AutomationView',
  position: 4,
  wideMode: true,
}

编程式场景中调用 API

编程式场景除了使用面板组件外，还可以直接调用后端 API 实现自定义逻辑。客户端提供了类型安全的 API 适配层：

typescript

import { tasksApi, projectsApi, automationApi } from '@renderer/adapters/taskProjectApi'

// 创建任务并关联到项目
const task = await tasksApi.create({
  title: '完成需求文档',
  projectId: 'project-xxx',
  priority: 'HIGH',
  dueAt: '2026-08-15T00:00:00Z',
})

// 查询项目下所有任务
const tasks = await tasksApi.list({ projectId: 'project-xxx' })

// 从模板创建项目（自动生成任务清单）
const project = await projectsApi.createFromTemplate('software-dev', '我的新产品')

// 创建自动化规则：每天早上 9 点发送通知
const rule = await automationApi.create({
  name: '每日站会提醒',
  triggerType: 'schedule',
  triggerConfig: { type: 'schedule', cron: '0 9 * * *' },
  actionType: 'notification',
  actionConfig: { type: 'notification', channel: 'desktop', template: 'standup-reminder' },
  enabled: true,
})

// 手动执行规则
await automationApi.execute(rule.id)

错误处理：API 适配层提供 getApiErrorMessage(err, fallback) 和 safeCall(fn, context) 工具函数，统一处理异常。

最佳实践

1. 按需启用面板

并非所有场景都需要全部生产力面板。根据场景定位选择性地启用：

typescript

// 轻量对话场景：仅启用任务
sidebarItems: [
  { id: 'explorer', ..., component: 'ExplorerView', position: 0 },
  { id: 'tasks', ..., component: 'TaskWorkspace', position: 1, wideMode: true },
]

// 项目管理场景：启用项目 + 任务
sidebarItems: [
  { id: 'projects', ..., component: 'ProjectsView', position: 0, wideMode: true },
  { id: 'tasks', ..., component: 'TaskWorkspace', position: 1, wideMode: true },
]

// 完整生产力场景：全部启用
sidebarItems: [
  { id: 'explorer', ..., component: 'ExplorerView', position: 0 },
  { id: 'tasks', ..., component: 'TaskWorkspace', position: 1, wideMode: true },
  { id: 'projects', ..., component: 'ProjectsView', position: 2, wideMode: true },
  { id: 'automation', ..., component: 'AutomationView', position: 3, wideMode: true },
]

2. 跨场景数据共享

生产力面板的数据存储在后端，所有场景共享同一份数据。这意味着：

用户在「通用助手」场景创建的任务，切换到「开发助手」场景后依然可见
项目的关联关系（项目→任务→自动化）在不同场景间保持一致
无需场景间同步数据，后端 API 保证一致性

3. 与 AI 对话联动

任务面板支持 AI 接力 功能：每个任务可关联一个 threadId，AI 执行任务时会在对话中记录进度。用户下次打开任务时，可通过 AI 接力恢复上次对话上下文，继续未完成的工作。

typescript

// AI 接力：恢复任务关联的对话
const context = await tasksApi.aiResume(taskId)
// 返回 { threadId, task }，客户端可切换到对应对话

4. 自动化与场景结合

自动化规则可以绑定到特定项目，实现项目级的智能联动：

定时触发：每天汇总项目进度并生成报告
事件触发：任务状态变更时自动通知相关人员
Webhook 触发：外部系统（如 GitHub Push）触发项目任务更新

公共可用页面 ​

面板总览 ​

生产力套件 ​

TaskWorkspace — 任务工作台 ​

功能特性 ​

数据模型 ​

状态流转规则 ​

后端 API ​

接入方式 ​

ProjectsView — 项目管理 ​

功能特性 ​

数据模型 ​

项目状态流转 ​

后端 API ​

接入方式 ​

AutomationView — 自动化 ​

功能特性 ​

数据模型 ​

触发器与动作矩阵 ​

后端 API ​

接入方式 ​

编程式场景中调用 API ​

最佳实践 ​

1. 按需启用面板 ​

2. 跨场景数据共享 ​

3. 与 AI 对话联动 ​

4. 自动化与场景结合 ​

公共可用页面

面板总览

生产力套件

TaskWorkspace — 任务工作台

功能特性

数据模型

状态流转规则

后端 API

接入方式

ProjectsView — 项目管理

功能特性

数据模型

项目状态流转

后端 API

接入方式

AutomationView — 自动化

功能特性

数据模型

触发器与动作矩阵

后端 API

接入方式

编程式场景中调用 API

最佳实践

1. 按需启用面板

2. 跨场景数据共享

3. 与 AI 对话联动

4. 自动化与场景结合