# https://github.com/humanlayer/humanlayer 项目说明书

生成时间：2026-05-16 18:28:04 UTC

## 目录

- [项目概览](#project-overview)
- [技术栈](#technology-stack)
- [系统架构](#system-architecture)
- [事件总线系统](#event-bus-system)
- [会话管理](#session-management)
- [审批工作流](#approval-workflow)
- [数据库与存储](#database-storage)
- [REST API](#rest-api)
- [前端组件](#frontend-components)
- [桌面应用](#desktop-app)

<a id='project-overview'></a>

## 项目概览

### 相关页面

相关主题：[技术栈](#technology-stack), [系统架构](#system-architecture)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/humanlayer/humanlayer/blob/main/README.md)
- [humanlayer.md](https://github.com/humanlayer/humanlayer/blob/main/humanlayer.md)
- [hld/README.md](https://github.com/humanlayer/humanlayer/blob/main/hld/README.md)
- [humanlayer-wui/src/components/OptInTelemetryModal.tsx](https://github.com/humanlayer/humanlayer/blob/main/humanlayer-wui/src/components/OptInTelemetryModal.tsx)
- [humanlayer-wui/src/components/SettingsDialog.tsx](https://github.com/humanlayer/humanlayer/blob/main/humanlayer-wui/src/components/SettingsDialog.tsx)
- [humanlayer-wui/src/components/Layout.tsx](https://github.com/humanlayer/humanlayer/blob/main/humanlayer-wui/src/components/Layout.tsx)
- [humanlayer-wui/src/components/internal/SessionDetail/components/ToolResultModal.tsx](https://github.com/humanlayer/humanlayer/blob/main/humanlayer-wui/src/components/internal/SessionDetail/components/ToolResultModal.tsx)
- [humanlayer-wui/src/stores/demo/export/MARKETING_GUIDE.md](https://github.com/humanlayer/humanlayer/blob/main/humanlayer-wui/src/stores/demo/export/MARKETING_GUIDE.md)

</details>

# 项目概览

## 1. 项目简介

HumanLayer 是一个开源的 AI 会话管理和控制平台，提供 SDK 和 Web 用户界面（WUI）来实现对 AI Agent 行为的精细化管理。该项目主要包含两个核心组件：**HumanLayer SDK** 和 **CodeLayer**，两者均采用 Apache 2.0 开源许可证。

项目的核心目标是解决 AI Agent 在执行敏感操作时的审批和控制问题，确保人类能够对 AI 的文件编辑、命令执行、代码搜索等操作进行监督和干预。

资料来源：[README.md:1-10]()

## 2. 系统架构

### 2.1 整体架构图

```mermaid
graph TD
    subgraph 前端层["前端层 (humanlayer-wui)"]
        A[Web UI 界面]
        B[主题选择器]
        C[设置对话框]
        D[会话管理界面]
    end
    
    subgraph 控制层["控制层"]
        E[OptInTelemetryModal 遥测模块]
        F[SessionTable 会话表]
        G[ToolResultModal 工具结果模态框]
        H[DangerouslySkipPermissionsDialog 权限跳过对话框]
    end
    
    subgraph 后端/守护进程["Daemon 守护进程"]
        I[托管模式]
        J[自定义连接模式]
    end
    
    subgraph 核心功能["HumanLayer SDK"]
        K[工具调用审批]
        L[会话管理]
        M[健康状态监控]
    end
    
    A --> E
    A --> C
    A --> D
    D --> F
    A --> H
    C --> G
```

### 2.2 核心模块说明

| 模块名称 | 功能描述 | 技术栈 |
|---------|---------|--------|
| HumanLayer WUI | Web 用户界面，提供会话管理和监控功能 | React + TypeScript + TailwindCSS |
| HumanLayer SDK | Python/JS SDK，用于集成到 AI Agent 应用中 | Python, JavaScript/TypeScript |
| CodeLayer | 代码层实现，核心业务逻辑 | Python |
| Daemon | 守护进程，管理 AI 会话和工具调用审批 | 后端服务 |

资料来源：[humanlayer-wui/src/stores/demo/export/MARKETING_GUIDE.md:1-15]()

## 3. 用户界面功能

### 3.1 主界面组件

HumanLayer WUI 提供了完整的会话管理界面，主要组件包括：

```mermaid
graph LR
    A[Layout 布局容器] --> B[SessionTable 会话列表]
    A --> C[SessionDetail 会话详情]
    A --> D[DebugPanel 调试面板]
    A --> E[SettingsDialog 设置对话框]
    
    C --> F[ConversationStream 对话流]
    C --> G[ToolResultModal 工具结果弹窗]
    
    F --> H[EditToolCallContent 编辑工具]
    F --> I[WriteToolCallContent 写入工具]
    F --> J[MultiEditToolCallContent 多重编辑]
    F --> K[BashToolCallContent Bash 命令]
    F --> L[GrepToolCallContent 代码搜索]
```

### 3.2 主题系统

项目支持多主题切换功能，核心实现在 `ThemeSelector.tsx` 中：

- 支持键盘快捷键切换主题（Mod+T）
- 支持向上/向下导航选择
- 主题选项存储于组件状态中

```typescript
// 主题选择器核心逻辑
interface ThemeOption {
  value: string;
  label: string;
  icon: React.ComponentType;
}
```

资料来源：[humanlayer-wui/src/components/ThemeSelector.tsx:1-30]()

### 3.3 连接状态管理

Layout 组件负责管理守护进程连接状态：

| 状态 | 说明 | UI 表现 |
|-----|------|--------|
| `connected` | 已连接到守护进程 | 显示正常状态栏 |
| `connecting` | 正在连接中 | 显示加载指示器 |
| `degraded` | 健康状态降级 | 显示警告按钮 |
| `disconnected` | 未连接 | 显示重试按钮 |

资料来源：[humanlayer-wui/src/components/Layout.tsx:1-25]()

## 4. 工具调用系统

### 4.1 支持的工具类型

HumanLayer WUI 针对各种 AI Agent 工具提供了专门的渲染组件：

| 工具名称 | 描述 | 渲染组件 |
|---------|------|---------|
| `Write` | 文件写入操作 | `WriteToolCallContent` |
| `Edit` | 文件编辑操作 | `EditToolCallContent` |
| `MultiEdit` | 多文件编辑操作 | `MultiEditToolCallContent` |
| `Bash` | Bash 命令执行 | `BashToolCallContent` |
| `BashOutput` | Bash 输出结果 | `BashOutputToolCallContent` |
| `Grep` | 代码搜索 | `GrepToolCallContent` |
| `Read` | 文件读取 | `ReadToolCallContent` |
| `Task` | 子任务/子代理 | `TaskToolCallContent` |
| `Plan` | 执行计划 | `PlanToolCallContent` |

资料来源：[humanlayer-wui/src/components/internal/SessionDetail/components/ToolResultModal.tsx:1-80]()

### 4.2 工具调用数据模型

```typescript
interface ConversationEvent {
  approvalId?: string;           // 审批 ID
  approvalStatus?: string;       // 审批状态
  claudeSessionId: string;       // Claude 会话 ID
  eventType: 'tool_call' | 'message';  // 事件类型
  toolName: string;              // 工具名称
  toolInputJson: string;         // 工具输入 JSON
  toolResultContent?: string;    // 工具结果内容
  createdAt: Date;               // 创建时间
  sequence: number;              // 序列号
  sessionId: string;             // 会话 ID
}
```

### 4.3 权限跳过功能

`DangerouslySkipPermissionsDialog` 组件提供了危险操作警告机制，支持的操作包括：

- 文件编辑和写入
- Bash 命令执行
- 文件读取
- 子任务生成
- MCP 工具调用

该功能包含自动禁用超时设置，范围为 1-60 分钟。

资料来源：[humanlayer-wui/src/components/internal/SessionDetail/DangerouslySkipPermissionsDialog.tsx:1-50]()

## 5. 设置与配置

### 5.1 设置对话框功能

`SettingsDialog` 组件提供了完整的配置选项：

| 配置项 | 说明 | 类型 |
|-------|------|-----|
| 模型选择 | 选择使用的 AI 模型 | 字符串 |
| 模型提供商 | 高级提供商选项 | 布尔值 |
| Claude 二进制路径 | Claude CLI 路径配置 | 路径字符串 |
| 遥测开关 | 性能与错误报告 | 布尔值 |
| 日志路径 | 日志存储位置 | 路径 |

### 5.2 Claude 配置状态

```typescript
interface ClaudeConfig {
  claudeAvailable: boolean;      // Claude 是否可用
  claudePath?: string;           // 配置的路径
  claudeDetectedPath?: string;   // 自动检测的路径
}
```

状态指示器包括：
- `CheckCircle2`：绿色图标，表示可用
- `XCircle`：红色图标，表示不可用

资料来源：[humanlayer-wui/src/components/SettingsDialog.tsx:1-100]()

## 6. 遥测与隐私

### 6.1 遥测模块

`OptInTelemetryModal` 组件实现了可选的匿名数据收集功能。用户在首次使用时可选择是否启用。

### 6.2 数据收集范围

| 收集内容 | 说明 |
|---------|------|
| **收集** | 匿名错误报告、匿名性能数据 |
| **不收集** | 用户提示词、会话内容、代码文件路径、API 密钥、个人信息、工作目录名称 |

### 6.3 遥测确认流程

```mermaid
graph TD
    A[首次启动] --> B{用户选择}
    B -->|同意| C[启用遥测报告]
    B -->|拒绝| D[禁用遥测]
    C --> E[显示快捷键: ⌘/Ctrl+ENTER]
    D --> F[显示'No Thanks']
    E --> G[保存偏好设置]
    F --> G
```

用户可在设置中随时更改遥测偏好设置。

资料来源：[humanlayer-wui/src/components/OptInTelemetryModal.tsx:1-50]()

## 7. 守护进程模式

### 7.1 托管模式 (Managed)

- 默认运行模式
- 提供一键重启功能
- 由系统自动管理守护进程生命周期

### 7.2 自定义连接模式

- 支持连接到运行在自定义 URL 的守护进程
- 支持指定端口号（如 `http://127.0.0.1:7777`）
- 提供 URL 输入框进行配置

资料来源：[humanlayer-wui/src/components/DebugPanel.tsx:1-60]()

## 8. 会话管理

### 8.1 会话表功能

`SessionTable` 组件提供会话列表管理：

- 显示所有活跃会话
- 支持会话选择（多选）
- 显示会话元信息：工作目录、标题、模型、开始时间、最近活动时间
- 支持会话归档后的降级显示

### 8.2 会话状态

| 状态属性 | 说明 |
|---------|------|
| `focusedSession` | 当前聚焦的会话 |
| `selectedSessions` | 已选中的会话集合 |
| `archived` | 归档状态（opacity: 0.6） |

### 8.3 交互方式

- 鼠标悬停：聚焦会话（`onMouseEnter` / `onMouseLeave`）
- 单击行：选择会话
- 单击复选框区域：切换选择状态

资料来源：[humanlayer-wui/src/components/internal/SessionTable.tsx:1-80]()

## 9. 键盘快捷键

| 快捷键 | 功能 | 作用域 |
|-------|------|--------|
| `j` / `↓` | 下滚/下一项 | 会话列表、工具结果 |
| `k` / `↑` | 上滚/上一项 | 会话列表、工具结果 |
| `i` / `ESC` | 展开/关闭详情 | 工具调用详情 |
| `Mod+T` | 切换主题 | 全局 |
| `⌘/Ctrl+ENTER` | 确认启用遥测 | 遥测对话框 |

## 10. 快速开始

项目目前处于早期访问阶段：

```bash
# 加入等待列表获取早期访问权限
npx humanlayer join-waitlist --email <your-email>
```

资料来源：[README.md:15-20]()

## 11. 相关文档

- [Legacy SDK 文档](./humanlayer.md) - HumanLayer SDK 详细文档
- [HLM 文档](./hld/README.md) - HLM 相关说明
- [贡献指南](./CONTRIBUTING.md) - 如何参与项目贡献

---

<a id='technology-stack'></a>

## 技术栈

### 相关页面

相关主题：[项目概览](#project-overview), [系统架构](#system-architecture)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [hld/go.mod](https://github.com/humanlayer/humanlayer/blob/main/hld/go.mod)
- [humanlayer-wui/package.json](https://github.com/humanlayer/humanlayer/blob/main/humanlayer-wui/package.json)
- [hlyr/package.json](https://github.com/humanlayer/humanlayer/blob/main/hlyr/package.json)
- [packages/database/package.json](https://github.com/humanlayer/humanlayer/blob/main/packages/database/package.json)
- [apps/react/src/App.tsx](https://github.com/humanlayer/humanlayer/blob/main/apps/react/src/App.tsx)
- [humanlayer-wui/README.md](https://github.com/humanlayer/humanlayer/blob/main/humanlayer-wui/README.md)
</details>

# 技术栈

HumanLayer 是一个用于 AI 代理与人协作的工具平台，其技术栈采用多语言、多层架构设计，涵盖命令行工具、Web 界面、桌面客户端和后台守护进程。

## 技术栈概览

HumanLayer 项目采用以下核心技术：

| 层级 | 技术选型 | 用途 |
|------|----------|------|
| 桌面 UI | Tauri + React | 跨平台桌面应用（CodeLayer） |
| 后端服务 | Go | 守护进程（hld） |
| 数据库 | SQLite | 本地数据持久化 |
| CLI 工具 | Node.js (npx) | 命令行接口 |
| 实时通信 | WebSocket | 进程间通信 |
| MCP 集成 | Model Context Protocol | AI 模型交互 |

## 核心模块架构

```mermaid
graph TB
    subgraph "前端层"
        CLI[hlyr CLI工具]
        WUI[humanlayer-wui<br/>Tauri + React]
        REACT[apps/react<br/>示例应用]
    end
    
    subgraph "服务层"
        HLD[hld 守护进程<br/>Go]
        MCP[MCP Server]
    end
    
    subgraph "数据层"
        DB[(SQLite<br/>数据库)]
        CONFIG[配置文件]
    end
    
    CLI --> HLD
    WUI --> HLD
    REACT --> MCP
    HLD --> DB
    HLD --> CONFIG
    MCP --> HLD
```

## 守护进程 (hld)

### Go 语言后端

守护进程 `hld` 使用 Go 语言开发，位于 `hld/` 目录。

**核心职责：**

- 管理 AI 会话生命周期
- 处理工具调用审批流程
- 维护会话状态和历史记录
- 提供 HTTP/WebSocket API 接口
- 与 MCP 服务器通信

### 数据库层

| 模块 | 技术 | 说明 |
|------|------|------|
| 数据库驱动 | SQLite | 轻量级嵌入式数据库 |
| 数据模型 | 关系型 | 会话、事件、审批记录 |
| 位置 | `packages/database/` | 共享数据库逻辑 |

## 桌面客户端 (humanlayer-wui)

### 技术选型

| 组件 | 技术 | 版本说明 |
|------|------|----------|
| 桌面框架 | Tauri 2.x | Rust 后端 + Web 前端 |
| 前端框架 | React 18.x | 组件化 UI 开发 |
| 状态管理 | Zustand | 轻量级状态管理 |
| UI 组件 | Radix UI | 无样式可访问组件 |
| 样式方案 | Tailwind CSS | 原子化 CSS 框架 |
| 构建工具 | Vite | 快速开发服务器 |
| 类型系统 | TypeScript | 类型安全保证 |

### 架构特点

```mermaid
graph LR
    subgraph "React 应用"
        COMP[组件层]
        STORE[Zustand Store]
        HOOKS[自定义 Hooks]
    end
    
    subgraph "Tauri 桥接"
        IPC[Tauri IPC]
        COMMANDS[Rust Commands]
    end
    
    COMP --> STORE
    STORE --> HOOKS
    HOOKS --> IPC
    IPC --> COMMANDS
    COMMANDS --> HLD[hld 守护进程]
```

### 组件结构

桌面客户端采用分层架构：

1. **展示层**：React 组件，处理 UI 渲染
2. **状态层**：Zustand store，管理应用状态
3. **通信层**：Tauri IPC，与 Rust 后端通信
4. **服务层**：Rust 后端，执行业务逻辑

资料来源：[humanlayer-wui/README.md:1-15]()

## CLI 工具 (hlyr)

### Node.js 命令行工具

CLI 工具 `hlyr` 使用 Node.js 开发，提供丰富的命令行接口。

**主要功能：**

| 命令 | 功能 | 用法示例 |
|------|------|----------|
| `join-waitlist` | 加入等待列表 | `humanlayer join-waitlist --email xxx` |
| `contact_human` | 联系人工审核 | `humanlayer contact_human -m "消息"` |
| `mcp serve` | 启动 MCP 服务器 | `humanlayer mcp serve` |
| `mcp claude_approvals` | Claude 审批集成 | Claude Code SDK 集成 |
| `mcp inspector` | 调试 MCP 服务器 | `humanlayer mcp inspector serve` |

### MCP 协议集成

HumanLayer 支持 Model Context Protocol (MCP)，实现与 AI 模型的深度集成：

```mermaid
graph LR
    A[Claude Code<br/>或其他 MCP 客户端] -->|MCP 协议| B[MCP Server]
    B -->|请求审批| C[hld 守护进程]
    C -->|批准/拒绝| B
    B -->|结果| A
```

**MCP 配置示例：**

```json
{
  "mcpServers": {
    "approvals": {
      "command": "npx",
      "args": ["-y", "humanlayer", "mcp", "claude_approvals"],
      "env": {
        "HUMANLAYER_API_KEY": "<YOUR_API_KEY>"
      }
    }
  }
}
```

资料来源：[hlyr/README.md:1-80]()

## 工具调用系统

HumanLayer 支持多种工具类型的调用与审批：

### 支持的工具类型

| 工具名称 | 功能描述 | 审批类型 |
|----------|----------|----------|
| Write | 写入文件内容 | 需要审批 |
| Edit | 编辑文件内容 | 需要审批 |
| Bash | 执行 Shell 命令 | 需要审批 |
| Grep | 搜索文件内容 | 需要审批 |
| Read | 读取文件内容 | 需要审批 |
| Task | 启动子代理任务 | 需要审批 |
| BashOutput | 获取后台任务输出 | 需要审批 |
| MultiEdit | 批量编辑多个文件 | 需要审批 |

### 审批流程

```mermaid
sequenceDiagram
    participant AI as AI 代理
    participant HL as HumanLayer
    participant User as 用户
    participant FS as 文件系统
    
    AI->>HL: 发起工具调用
    HL->>User: 显示审批请求
    User->>HL: 批准/拒绝
    alt 批准
        HL->>FS: 执行操作
        FS-->>HL: 操作结果
        HL-->>AI: 返回结果
    else 拒绝
        HL-->>AI: 返回拒绝原因
    end
```

## 配置管理

### 配置文件格式

HumanLayer 使用 JSON 格式的配置文件：

```json
{
  "channel": {
    "slack": {
      "channel_or_user_id": "C08G5C3V552"
    }
  }
}
```

### 环境变量

| 变量名 | 说明 | 默认值 |
|--------|------|--------|
| `HUMANLAYER_API_KEY` | API 密钥认证 | - |
| `HUMANLAYER_DAEMON_HTTP_PORT` | 守护进程端口 | 7777 |
| `HUMANLAYER_WUI_AUTOLAUNCH_DAEMON` | 是否自动启动守护进程 | true |
| `HUMANLAYER_OPT_IN_TELEMETRY` | 遥测数据收集 | false |

## 开发环境

### 本地开发

```bash
# 1. 构建守护进程
make daemon-dev-build

# 2. 启动开发模式
make codelayer-dev

# 3. 或使用外部守护进程
export HUMANLAYER_DAEMON_HTTP_PORT=7777
make codelayer-dev
```

### 生产构建

```bash
# 构建包含守护进程的桌面应用
make codelayer-bundle

# 构建过程：
# 1. 为 macOS ARM64 构建守护进程
# 2. 构建 CLI 工具
# 3. 打包到 Tauri 应用
# 4. 生成 DMG 安装包
```

## 技术特点总结

| 特性 | 实现方式 | 优势 |
|------|----------|------|
| 跨平台 | Tauri + WebView | 支持 macOS/Windows/Linux |
| 轻量级 | SQLite + Go | 资源占用低、启动快 |
| 实时性 | WebSocket | 低延迟通信 |
| 可扩展 | MCP 协议 | 兼容多种 AI 客户端 |
| 安全 | 本地优先 | 数据存储在本地 |
| 开源 | Apache 2.0 | 透明可审计 |

HumanLayer 的技术栈设计遵循**本地优先**原则，所有敏感数据存储在用户本地设备上，通过守护进程统一管理 AI 代理的行为，实现安全可控的人机协作。

---

<a id='system-architecture'></a>

## 系统架构

### 相关页面

相关主题：[事件总线系统](#event-bus-system), [会话管理](#session-management), [REST API](#rest-api)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [hld/daemon/daemon.go](https://github.com/humanlayer/humanlayer/blob/main/hld/daemon/daemon.go)
- [hld/rpc/server.go](https://github.com/humanlayer/humanlayer/blob/main/hld/rpc/server.go)
- [hld/api/handlers/server.go](https://github.com/humanlayer/humanlayer/blob/main/hld/api/handlers/server.go)
- [humanlayer-wui/docs/ARCHITECTURE.md](https://github.com/humanlayer/humanlayer/blob/main/humanlayer-wui/docs/ARCHITECTURE.md)
- [hld/sdk/typescript/README.md](https://github.com/humanlayer/humanlayer/blob/main/hld/sdk/typescript/README.md)
- [claudecode-go/README.md](https://github.com/humanlayer/humanlayer/blob/main/claudecode-go/README.md)
- [humanlayer-wui/README.md](https://github.com/humanlayer/humanlayer/blob/main/humanlayer-wui/README.md)
</details>

# 系统架构

HumanLayer 是一个用于在 AI Agent 系统中实现人工审批和工作流编排的开源框架。其核心设计理念是通过模块化的微服务架构，将守护进程（Daemon）、CLI 工具、Web UI 和多语言 SDK 无缝集成，为开发者提供灵活的人机协作能力。

## 整体架构概览

```mermaid
graph TB
    subgraph 客户端层
        CLI[CLI 工具<br/>humanlayer]
        WUI[Web UI<br/>humanlayer-wui]
        SDK_TS[TypeScript SDK]
        SDK_GO[Go SDK]
    end

    subgraph 核心服务层
        HLD[HumanLayer Daemon<br/>hld]
        MCP_S[MCP Server<br/>contact_human]
        MCP_A[MCP Server<br/>claude_approvals]
    end

    subgraph 数据层
        DB[(SQLite<br/>Daemon Database)]
    end

    subgraph 外部集成
        SLACK[Slack]
        EMAIL[Email]
        WEB[Web UI]
    end

    CLI -->|REST API / SSE| HLD
    WUI -->|REST API / SSE| HLD
    SDK_TS -->|REST API / SSE| HLD
    SDK_GO -->|Claude Code CLI| HLD
    HLD --> DB
    HLD --> MCP_S
    HLD --> MCP_A
    HLD --> SLACK
    HLD --> EMAIL
    HLD --> WEB
```

HumanLayer 采用分层架构设计，核心是 HumanLayer Daemon（简称 hld），它作为中心枢纽处理所有会话管理、审批流程和外部通道集成。客户端通过 REST API 与守护进程通信，同时支持 Server-Sent Events（SSE）实现实时事件推送。

## 核心组件

### HumanLayer Daemon (hld)

守护进程是整个系统的核心引擎，负责：

| 功能模块 | 描述 |
|---------|------|
| 会话管理 | 创建、跟踪和管理 AI Agent 会话生命周期 |
| 审批引擎 | 处理工具调用的审批请求和状态流转 |
| MCP 服务器 | 提供 contact_human 和 claude_approvals 两种 MCP 服务 |
| 通道集成 | 连接 Slack、Email、Web UI 等人工接触渠道 |
| 实时事件 | 通过 SSE 向订阅者推送会话和审批事件 |

资料来源：[hld/daemon/daemon.go](https://github.com/humanlayer/humanlayer/blob/main/hld/daemon/daemon.go)

守护进程默认监听 7777 端口，提供 REST API 接口。开发者可以通过环境变量 `HUMANLAYER_DAEMON_HTTP_PORT` 自定义端口号。

### RPC 层

RPC 服务器封装了进程间通信逻辑，为守护进程提供高效的远程调用接口：

```go
// RPC 服务器职责
- 方法路由分发
- 请求序列化/反序列化  
- 连接池管理
```

资料来源：[hld/rpc/server.go](https://github.com/humanlayer/humanlayer/blob/main/hld/rpc/server.go)

### API 处理器

API 处理器层实现了完整的 REST API 端点，支持会话、审批、系统配置等核心资源的管理：

资料来源：[hld/api/handlers/server.go](https://github.com/humanlayer/humanlayer/blob/main/hld/api/handlers/server.go)

## 客户端架构

### CLI 工具

humanlayer CLI 提供命令行界面，集成了多种功能模块：

```bash
humanlayer <command> [subcommand] [options]
```

**主要命令模块：**

| 命令 | 功能描述 |
|-----|---------|
| `contact_human` | 从脚本或 CI 流程中联系人工审核 |
| `mcp` | MCP 服务器管理（serve、claude_approvals、inspector） |
| `thoughts` | 开发者笔记和文档管理 |
| `claude` | Claude Code SDK 集成命令 |

### Web UI (humanlayer-wui)

基于 Tauri 和 React 构建的跨平台桌面/Web 应用：

```mermaid
graph LR
    A[Tauri App] --> B[React Frontend]
    B --> C[Zustand Store]
    C --> D[Demo Mode]
    C --> E[Real Daemon]
    E --> F[hld REST API]
```

**技术栈：**

| 层级 | 技术选型 |
|-----|---------|
| 桌面框架 | Tauri |
| 前端框架 | React |
| 状态管理 | Zustand |
| 样式系统 | Tailwind CSS |
| 构建工具 | Vite |

资料来源：[humanlayer-wui/README.md](https://github.com/humanlayer/humanlayer/blob/main/humanlayer-wui/README.md)

### TypeScript SDK

为 TypeScript/JavaScript 应用提供 hld REST API 客户端封装：

```typescript
import { HLDClient } from '@humanlayer/hld-sdk';

const client = new HLDClient({
    port: 7777  // 默认 HLD REST API 端口
});

const session = await client.createSession({
    query: "Help me fix a bug",
    model: "claude-3.5-sonnet",
    workingDir: "/path/to/project"
});
```

**SDK 特性：**

- 完整的 REST API 覆盖
- SSE 实时事件订阅
- Node.js 和浏览器环境兼容
- TypeScript 类型自动生成

资料来源：[hld/sdk/typescript/README.md](https://github.com/humanlayer/humanlayer/blob/main/hld/sdk/typescript/README.md)

### Go SDK (claudecode-go)

为 Go 应用提供 Claude Code CLI 的程序化交互能力：

```go
client, err := claudecode.NewClient()
session, err := client.Launch(claudecode.SessionConfig{
    Query:        "Build a REST API",
    Model:        claudecode.ModelSonnet,
    OutputFormat: claudecode.OutputStreamJSON,
})
```

资料来源：[claudecode-go/README.md](https://github.com/humanlayer/humanlayer/blob/main/claudecode-go/README.md)

## 会话管理架构

### 会话状态机

```mermaid
stateDiagram-v2
    [*] --> Created: 创建会话
    Created --> Running: 启动执行
    Running --> Completed: 正常完成
    Running --> Failed: 执行错误
    Running --> Paused: 暂停
    Paused --> Running: 恢复
    Completed --> Archived: 归档
    Failed --> Archived: 归档
    Archived --> [*]: 删除
```

### 会话数据结构

```typescript
interface Session {
    sessionId: string           // 会话唯一标识
    query: string              // 用户查询
    model: string              // AI 模型
    workingDir: string          // 工作目录
    status: SessionStatus      // Running | Completed | Failed | Archived
    createdAt: Date            // 创建时间
    events: ConversationEvent[] // 事件流
}
```

### 会话控制功能

| 功能 | 描述 |
|-----|------|
| Fork | 从当前状态创建分支会话 |
| Bypass | 跳过审批直接执行（危险操作） |
| Auto-Accept | 自动接受审批请求 |
| Archive | 归档会话以清理视图 |

## 审批工作流

### 审批流程

```mermaid
sequenceDiagram
    participant AI as AI Agent
    participant HLD as HumanLayer Daemon
    participant Human as 人工渠道
    participant MCP as MCP Server

    AI->>HLD: 请求执行工具调用
    HLD->>MCP: 发送审批请求
    MCP->>Human: 推送待审批通知
    Human-->>MCP: 审批决策 (approve/deny)
    MCP-->>HLD: 返回审批结果
    HLD-->>AI: 允许/拒绝执行
```

### MCP 服务器集成

HumanLayer 提供两种 MCP 服务器实现：

#### contact_human MCP 服务器

用于脚本和 CI 流程中的人工接触场景：

```bash
humanlayer mcp serve
```

#### claude_approvals MCP 服务器

与 Claude Code SDK 集成的审批工作流：

```bash
humanlayer mcp claude_approvals
```

**MCP 配置文件示例：**

```json
{
  "mcpServers": {
    "approvals": {
      "command": "npx",
      "args": ["-y", "humanlayer", "mcp", "claude_approvals"],
      "env": {
        "HUMANLAYER_API_KEY": "<YOUR_API_KEY>"
      }
    }
  }
}
```

## 数据持久化

### 数据库架构

HumanLayer Daemon 使用 SQLite 作为默认数据库：

```
daemon-{branch}.db  # 每个 git 分支独立的数据库实例
```

**核心数据表：**

| 表名 | 用途 |
|-----|------|
| sessions | 会话元数据 |
| events | 会话事件流 |
| approvals | 审批请求记录 |
| settings | 用户配置 |

### 开发环境数据库管理

```mermaid
graph TD
    A[daemon-dev.db] -->|git checkout| B[daemon-{branch}.db]
    B -->|分支隔离| C[session-1.db]
    B -->|端口隔离| D[session-2.db]
    B -->|Socket 隔离| E[session-3.db]
```

开发模式下，每个 git 分支自动获得独立的数据库实例、Socket 和端口，确保环境隔离。

## 实时通信

### SSE 事件订阅

客户端可以订阅实时事件流：

```typescript
const unsubscribe = await client.subscribeToEvents(
    { sessionId: session.sessionId },
    {
        onMessage: (event) => console.log('Event:', event),
        onError: (error) => console.error('Error:', error)
    }
);
```

### 事件类型

| 事件类型 | 描述 |
|---------|------|
| `tool_call` | AI Agent 发起工具调用 |
| `tool_result` | 工具执行结果返回 |
| `approval_request` | 审批请求创建 |
| `approval_response` | 审批决策完成 |
| `session_status` | 会话状态变更 |

## 配置系统

### 配置优先级

```
命令行参数 > 环境变量 > 配置文件 (.hlyr.json) > 默认值
```

### 通道配置示例

```bash
# Slack 渠道
export HUMANLAYER_SLACK_CHANNEL=C08G5C3V552

# Email 渠道
export HUMANLAYER_EMAIL_ADDRESS=human@example.com

# API 密钥
export HUMANLAYER_API_KEY=...
```

## 部署架构

### 开发环境

```mermaid
graph LR
    A[humanlayer CLI] --> B[localhost:7777]
    C[CodeLayer WUI] --> B
    D[TypeScript SDK] --> B
```

### 生产环境

```mermaid
graph TB
    subgraph 云端服务
        HLD_PROD[HumanLayer Daemon<br/>生产实例]
        DB_PROD[(SQLite<br/>生产数据库)]
    end

    subgraph 客户端
        CI_CD[CI/CD Pipeline]
        DEVELOPER[开发者环境]
    end

    CI_CD -->|contact_human| HLD_PROD
    DEVELOPER -->|CLI/SDK| HLD_PROD
    HLD_PROD --> DB_PROD
```

## 扩展机制

### 工具调用集成

HumanLayer 支持拦截和审批多种工具调用：

| 工具类型 | 描述 |
|---------|------|
| Bash | 命令执行审批 |
| Write/Edit | 文件修改审批 |
| Grep | 搜索操作 |
| Task | 子代理任务审批 |
| BashOutput | 后台任务输出监控 |

### 自定义通道

开发者可以通过配置扩展新的联系方式：

```json
{
  "channel": {
    "slack": {
      "channel_or_user_id": "C08G5C3V552"
    }
  }
}
```

## 安全考虑

### 敏感信息处理

- API 密钥通过环境变量传递
- 数据库文件按分支隔离
- Bypass 和 Auto-Accept 功能需要显式启用
- 审计日志记录所有审批决策

### 权限控制

```typescript
interface SessionPermissions {
    bypassEnabled: boolean   // 跳过审批
    autoAcceptEnabled: boolean  // 自动接受
    allowedTools?: string[]     // 允许的工具列表
}
```

## 总结

HumanLayer 的系统架构围绕守护进程构建，通过标准化的 REST API 和 SSE 事件机制连接多种客户端。模块化设计允许开发者按需使用 CLI、SDK 或 MCP 服务器，同时保持部署的灵活性。数据层的 SQLite 支持和开发环境的自动隔离机制，使系统既适合生产环境又便于本地调试。

---

<a id='event-bus-system'></a>

## 事件总线系统

### 相关页面

相关主题：[系统架构](#system-architecture), [会话管理](#session-management)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [hld/bus/events.go](https://github.com/humanlayer/humanlayer/blob/main/hld/bus/events.go) - **未在当前上下文中检索到**
- [hld/bus/types.go](https://github.com/humanlayer/humanlayer/blob/main/hld/bus/types.go) - **未在当前上下文中检索到**
- [hld/bus/events_test.go](https://github.com/humanlayer/humanlayer/blob/main/hld/bus/events_test.go) - **未在当前上下文中检索到**

> ⚠️ **注意**：本次查询中未检索到上述源码文件的内容。当前页面内容基于仓库中实际可检索的前端组件和存储相关文件生成，涵盖会话事件流、工具调用事件和对话事件渲染等与事件总线相关的功能实现。
</details>

# 事件总线系统

## 概述

HumanLayer 的事件总线系统是核心的消息传递基础设施，负责在整个应用程序中传播和路由事件。从当前可检索的代码来看，该系统主要处理以下几类事件：

- **对话事件（Conversation Events）**：工具调用、工具结果、消息内容等
- **会话事件（Session Events）**：会话创建、更新、完成、失败等状态变更
- **工具调用事件（Tool Call Events）**：Bash、Edit、Write、Read、Grep、MultiEdit、Task 等工具的执行事件
- **UI 事件**：焦点变更、鼠标
Error with Openai API: output new_sensitive (1027)

Please check that you have set the OPENAI_API_KEY environment variable with a valid API key.

---

<a id='session-management'></a>

## 会话管理

### 相关页面

相关主题：[系统架构](#system-architecture), [审批工作流](#approval-workflow), [数据库与存储](#database-storage)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [humanlayer-wui/src/components/internal/SessionDetail/components/ToolResultModal.tsx](https://github.com/humanlayer/humanlayer/blob/main/humanlayer-wui/src/components/internal/SessionDetail/components/ToolResultModal.tsx)
- [humanlayer-wui/src/components/internal/ConversationStream/ConversationEventRow.stories.tsx](https://github.com/humanlayer/humanlayer/blob/main/humanlayer-wui/src/components/internal/ConversationStream/ConversationEventRow.stories.tsx)
- [humanlayer-wui/src/components/SessionsEmptyState.tsx](https://github.com/humanlayer/humanlayer/blob/main/humanlayer-wui/src/components/SessionsEmptyState.tsx)
- [humanlayer-wui/src/components/DebugPanel.tsx](https://github.com/humanlayer/humanlayer/blob/main/humanlayer-wui/src/components/DebugPanel.tsx)
- [humanlayer-wui/src/stores/demo/demoAppStore.ts](https://github.com/humanlayer/humanlayer/blob/main/humanlayer-wui/src/stores/demo/demoAppStore.ts)
</details>

# 会话管理

会话管理是 HumanLayer 系统的核心功能模块，负责协调 AI 编码代理与人类审批者之间的交互流程。该模块追踪和管理每个工作会话的完整生命周期，包括工具调用审批、状态监控和结果展示。

## 系统架构

HumanLayer 的会话管理采用分层架构设计，由前端 UI 层、状态管理层和后端守护进程层组成。各层之间通过 HTTP/WebSocket 协议进行通信，确保会话状态的一致性和实时同步。

```mermaid
graph TB
    subgraph 前端层
        WUI[Web/Desktop UI]
        CLI[命令行工具]
    end
    
    subgraph 状态管理层
        Store[Zustand Store]
    end
    
    subgraph 后端层
        Daemon[Daemon 守护进程]
        SessionMgr[Session Manager]
        ClaudeWrapper[Claude Code Wrapper]
    end
    
    WUI <--> Store
    CLI <--> Store
    Store <--> Daemon
    Daemon --> SessionMgr
    SessionMgr --> ClaudeWrapper
```

## 会话状态模型

每个会话（Session）包含多个关键属性，用于追踪会话的完整生命周期。状态模型定义了会话的基本信息、参与者和当前运行状态。

### 核心数据结构

| 属性 | 类型 | 说明 |
|------|------|------|
| id | string | 会话唯一标识符 |
| createdAt | Date | 会话创建时间 |
| status | string | 会话状态 |
| claudeSessionId | string | Claude 会话标识 |
| approvalStatus | string | 审批状态 |

会话中的事件（Event）记录了每次工具调用和用户交互的详细信息。事件类型包括 `tool_call`、`tool_result`、`message` 等，每种事件都有对应的输入参数和输出内容。

资料来源：[ConversationEventRow.stories.tsx:30-50]()

### 事件类型

HumanLayer 支持多种会话事件类型，每种类型在 UI 中有特定的渲染方式：

- **tool_call** - AI 代理发起的工具调用请求
- **tool_result** - 工具执行结果
- **message** - 用户消息
- **BashOutput** - Bash 命令输出

## 工具调用处理

工具调用是会话中的核心交互单元。当 Claude Code 代理尝试执行敏感操作时（如文件写入、编辑或 Bash 命令），系统会创建待审批的工具调用事件。

### 工具类型渲染

HumanLayer 为不同类型的工具提供专门的内容渲染组件。这种设计允许每种工具以最适合其数据结构的格式展示结果。

```mermaid
graph LR
    TC[Tool Call Event] --> Check{工具类型?}
    Check -->|Write| WriteRender[WriteToolCallContent]
    Check -->|Edit| EditRender[EditToolCallContent]
    Check -->|MultiEdit| MERender[MultiEditToolCallContent]
    Check -->|Task| TaskRender[TaskToolCallContent]
    Check -->|Grep| GrepRender[GrepToolCallContent]
    Check -->|BashOutput| BashRender[BashOutputContent]
```

### Write 工具渲染

对于文件写入操作，系统显示目标文件路径和写入内容：

```tsx
if (toolCall.toolName === 'Write') {
  return (
    <div className="space-y-2">
      <div className="font-mono text-sm">
        <span className="text-muted-foreground">File:</span>{' '}
        <span className="font-bold">{args.file_path}</span>
      </div>
      <div className="font-mono text-sm">
        <span className="text-muted-foreground">Content:</span>
        <pre className="mt-1 whitespace-pre-wrap bg-muted/50 rounded-md p-3 break-words">
          {args.content}
        </pre>
      </div>
    </div>
  )
}
```

资料来源：[ToolResultModal.tsx:20-40]()

### Edit 工具渲染

编辑操作使用差异查看器（DiffViewer）展示修改前后的内容对比：

```tsx
if (toolCall.toolName === 'Edit') {
  return (
    <div className="space-y-2">
      <div className="font-mono text-sm">
        <span className="text-muted-foreground">File:</span>{' '}
        <span className="font-bold">{args.file_path}</span>
      </div>
      <div className="mt-2">
        <CustomDiffViewer
          edits={[{ oldValue: args.old_string, newValue: args.new_string }]}
          splitView={false}
        />
      </div>
    </div>
  )
}
```

资料来源：[ToolResultModal.tsx:42-60]()

### Task 子代理渲染

对于任务工具（子代理），系统展示子代理类型、描述和提示词信息：

```tsx
if (toolCall.toolName === 'Task' && args.subagent_type) {
  return (
    <div className="space-y-3">
      <div className="font-mono text-sm">
        <span className="text-muted-foreground">Sub-agent Type:</span>{' '}
        <span className="font-bold text-accent">{args.subagent_type}</span>
      </div>
      {args.description && (
        <div className="font-mono text-sm">
          <span className="text-muted-foreground">Description:</span>{' '}
          <span className="italic">{args.description}</span>
        </div>
      )}
      {args.prompt && (
        <div className="font-mono text-sm">
          <div className="text-muted-foreground mb-1">Prompt:</div>
          <pre className="mt-1 whitespace-pre-wrap bg-muted/50 rounded-md p-3 break-words">
            {args.prompt}
          </pre>
        </div>
      )}
    </div>
  )
}
```

资料来源：[ToolResultModal.tsx:5-30]()

## 会话状态管理

前端使用 Zustand 进行状态管理，会话相关的状态存储在 `demoAppStore` 中。状态管理提供了对会话列表、焦点会话和模拟功能的完整控制。

### 状态接口定义

```typescript
interface DemoAppState {
  sessions: Session[]
  focusedSession: string | null
  launcherOpen: boolean
  launcherMode: 'command' | 'input'
  launcherView: 'menu' | 'input'
  
  // 操作方法
  setFocusedSession: (sessionId: string | null) => void
  addSession: (session: Session) => void
  updateSession: (id: string, updates: Partial<Session>) => void
  removeSession: (id: string) => void
  clearSessions: () => void
  
  // 复杂工作流操作
  simulateLaunchSession: (query: string) => void
  simulateSessionComplete: (sessionId: string) => void
  simulateSessionFailed: (sessionId: string, error: string) => void
}
```

资料来源：[demoAppStore.ts:20-50]()

### 会话创建流程

新会话的创建遵循以下流程：

1. 用户发起会话创建请求
2. 系统分配唯一会话标识符
3. 初始化会话状态为空闲
4. 启动 Claude Code 包装器
5. 建立与守护进程的连接

空状态组件提供了创建会话的入口点：

```tsx
<div className="flex gap-2">
  <Button onClick={handleCreateSession} size="lg">
    Create Session <KeyboardShortcut keyString="C" />
  </Button>
  <Button variant="secondary" size="lg" onClick={() => open()}>
    Open command palette <KeyboardShortcut keyString={`${Mod}+K`} />
  </Button>
</div>
```

资料来源：[SessionsEmptyState.tsx:30-40]()

## 守护进程集成

DebugPanel 组件提供了与后端守护进程交互的调试界面，支持查看连接状态、守护进程类型和重启功能。

### 连接状态监控

| 状态 | 说明 | UI 显示 |
|------|------|---------|
| connected | 已连接 | 绿色标签 |
| connecting | 连接中 | 加载动画 |
| disconnected | 断开连接 | 红色标签 + 重试按钮 |

### 守护进程类型

系统支持两种守护进程管理模式：

- **managed** - 由应用自动管理的守护进程
- **external** - 连接到外部运行的守护进程

```tsx
{daemonType === 'managed' ? (
  <Button onClick={handleRestartDaemon} disabled={isRestarting}>
    {isRestarting ? 'Restarting Daemon...' : 'Restart Daemon'}
  </Button>
) : (
  <Button onClick={handleSwitchToManaged}>
    Switch to Managed Daemon
  </Button>
)}
```

资料来源：[DebugPanel.tsx:40-55]()

### 外部守护进程连接

用户可以连接到运行在自定义 URL 或端口的守护进程：

```tsx
<Input
  id="url"
  type="text"
  placeholder="http://127.0.0.1:7777"
  value={daemonUrl}
/>
```

支持通过环境变量指定端口：

```bash
export HUMANLAYER_DAEMON_HTTP_PORT=7777
```

资料来源：[DebugPanel.tsx:60-70]()

## 会话事件流

会话中的事件按照序列号顺序处理，确保操作的因果关系得到正确维护。每个事件包含时间戳、事件类型、关联的工具调用和审批状态。

### 事件序列示例

```json
{
  "id": 7,
  "eventType": "tool_call",
  "toolName": "Grep",
  "sequence": 7,
  "approvalId": "approval-grep-1",
  "approvalStatus": "pending",
  "createdAt": "2025-09-18T18:44:52Z",
  "toolInputJson": "{\"pattern\":\"TODO\",\"path\":\"/src\"}"
}
```

资料来源：[ConversationEventRow.stories.tsx:50-70]()

### BashOutput 事件处理

Bash 命令的输出作为独立事件处理，支持后台任务完成通知：

```json
{
  "id": 24,
  "eventType": "tool_call",
  "toolName": "BashOutput",
  "isCompleted": true,
  "toolResultContent": "<status>completed</status>\n<exit_code>0</exit_code>\n<stdout>hey</stdout>"
}
```

资料来源：[ConversationEventRow.stories.tsx:100-120]()

## 审批状态管理

每个工具调用都有对应的审批状态，用于控制是否允许操作执行。状态变更通过 WebSocket 实时推送到前端。

### 审批状态流转

```mermaid
graph LR
    A[pending] --> B[approved]
    A --> C[denied]
    B --> D[completed]
    C --> E[failed]
```

### 状态显示组件

状态徽章组件根据当前审批状态显示对应的视觉标识：

```tsx
<div className="ml-4">
  <StatusBadge status={approvalStatus} />
</div>
```

资料来源：[TaskToolCallContent.tsx:5-15]()

## 主题与显示

会话管理界面支持多种主题配置，与系统主题设置集成。状态栏显示当前连接状态和守护进程信息。

### 布局组件

主布局组件整合了所有会话管理的 UI 元素：

- 顶部导航栏
- 会话列表区域
- 状态栏（连接状态、守护进程信息）
- 调试面板入口

```tsx
<div className="flex justify-between items-center px-3 py-1.5 border-t border-border bg-secondary/30">
  <div className="flex items-center gap-4">
    <div className="font-mono text-xs uppercase tracking-wider text-muted-foreground">
      humanlayer
    </div>
    {connected && healthStatus === 'degraded' && (
      <Button variant="outline" className="text-amber-500 border-amber-500">
        Unhealthy - Configure
      </Button>
    )}
  </div>
</div>
```

资料来源：[Layout.tsx:50-70]()

## 键盘快捷键

会话管理界面支持丰富的键盘快捷键操作，提高用户交互效率。

| 快捷键 | 功能 |
|--------|------|
| C | 创建新会话 |
| ⌘/Ctrl + K | 打开命令面板 |
| i | 展开工具结果详情 |
| ⌘/Ctrl + ENTER | 启用遥测报告 |

资料来源：[SessionsEmptyState.tsx](), [OptInTelemetryModal.tsx:25-30]()

## 总结

HumanLayer 的会话管理模块提供了完整的 AI 编码代理工作流协调能力。通过事件驱动的状态管理、分层的 UI 组件架构和灵活的守护进程集成，系统能够有效管理复杂的工具调用审批流程，同时保持良好的用户体验和调试能力。

---

<a id='approval-workflow'></a>

## 审批工作流

### 相关页面

相关主题：[会话管理](#session-management), [REST API](#rest-api), [前端组件](#frontend-components)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [hld/approval/manager.go](https://github.com/humanlayer/humanlayer/blob/main/hld/approval/manager.go)
- [hld/approval/types.go](https://github.com/humanlayer/humanlayer/blob/main/hld/approval/types.go)
- [hld/approval/manager_test.go](https://github.com/humanlayer/humanlayer/blob/main/hld/approval/manager_test.go)
- [hld/rpc/approval_handlers.go](https://github.com/humanlayer/humanlayer/blob/main/hld/rpc/approval_handlers.go)
- [humanlayer-wui/src/components/Layout.tsx](https://github.com/humanlayer/humanlayer/blob/main/humanlayer-wui/src/components/Layout.tsx)
- [humanlayer-wui/src/components/internal/SessionDetail/DangerouslySkipPermissionsDialog.tsx](https://github.com/humanlayer/humanlayer/blob/main/humanlayer-wui/src/components/internal/SessionDetail/DangerouslySkipPermissionsDialog.tsx)
</details>

# 审批工作流

HumanLayer 的核心功能之一是**审批工作流（Approval Workflow）**，它允许用户在 AI Agent 执行敏感操作（如文件编辑、命令执行、文件写入等）之前进行人工审批或拒绝。

## 概述

审批工作流是 HumanLayer 架构中的关键组成部分，它在 AI Agent 的工具调用（Tool Call）和实际执行之间插入一个人工决策点。当 Claude 或其他 AI 模型尝试执行敏感工具时，系统会暂停执行，等待用户批准或拒绝。

```mermaid
graph TD
    A[AI Agent 发起工具调用] --> B{是否需要审批?}
    B -->|是| C[创建 ApprovalRequest]
    B -->|否| Z[直接执行]
    C --> D[通过 WebSocket 推送至前端]
    D --> E[用户看到待审批列表]
    E --> F{用户决策}
    F -->|批准| G[ApprovalResult: approved]
    F -->|拒绝| H[ApprovalResult: denied]
    G --> I[通知 Agent 继续执行]
    H --> J[终止工具调用]
    I --> K[返回工具执行结果]
    J --> L[返回拒绝错误]
```

## 核心组件

### 后端组件

| 组件 | 文件位置 | 职责 |
|------|----------|------|
| ApprovalManager | `hld/approval/manager.go` | 管理所有审批请求的生命周期 |
| ApprovalRequest | `hld/approval/types.go` | 定义审批请求的数据结构 |
| ApprovalHandlers | `hld/rpc/approval_handlers.go` | 处理 RPC 层面的审批操作 |

### 前端组件

| 组件 | 文件位置 | 职责 |
|------|----------|------|
| Layout | `humanlayer-wui/src/components/Layout.tsx` | 显示待审批列表和状态栏 |
| DangerouslySkipPermissionsDialog | `humanlayer-wui/src/components/internal/SessionDetail/DangerouslySkipPermissionsDialog.tsx` | 跳过权限对话框 |

## 审批请求数据结构

审批请求（ApprovalRequest）包含以下关键字段：

```typescript
interface ApprovalRequest {
  id: string;                    // 审批请求唯一标识
  sessionId: string;             // 所属会话 ID
  toolName: string;              // 工具名称 (如 Bash, Edit, Write)
  toolInput: object;             // 工具输入参数
  approvalStatus: 'pending' | 'approved' | 'denied';
  createdAt: Date;               // 创建时间
}
```

资料来源：[humanlayer-wui/src/components/Layout.tsx]()

## 审批流程详解

### 1. 工具调用拦截

当 AI Agent 尝试调用工具时，HumanLayer SDK 会拦截该调用并创建一个审批请求。如果该工具被配置为需要审批，则执行会暂停。

### 2. 审批请求创建

```go
// 伪代码展示审批创建逻辑
func (m *ApprovalManager) CreateApproval(request ToolCallRequest) (*ApprovalRequest, error) {
    approval := &ApprovalRequest{
        ID:            generateUUID(),
        SessionID:     request.SessionID,
        ToolName:      request.ToolName,
        ToolInput:     request.ToolInput,
        ApprovalStatus: StatusPending,
        CreatedAt:     time.Now(),
    }
    m.store.Save(approval)
    m.notifyFrontend(approval)
    return approval, nil
}
```

资料来源：[hld/approval/manager.go]()

### 3. 前端通知

通过 WebSocket 连接，前端会收到实时通知，更新待审批列表：

```typescript
// Layout.tsx 中的审批列表渲染
{approvals.map((approval, index) => (
  <div key={index} className="p-4 border border-border bg-secondary/20 font-mono text-sm">
    <div className="mb-2">
      <span className="text-accent">Tool:</span> {approval.toolName}
    </div>
    <div className="mb-2">
      <span className="text-accent">Session:</span> {approval.sessionId.slice(0, 8)}
    </div>
    <div className="mb-3">
      <span className="text-accent">Input:</span> {JSON.stringify(approval.toolInput)}
    </div>
    <div className="flex gap-2">
      <Button onClick={() => handleApproval(approval, true)} size="sm">批准</Button>
      <Button onClick={() => handleApproval(approval, false)} variant="destructive" size="sm">拒绝</Button>
    </div>
  </div>
))}
```

资料来源：[humanlayer-wui/src/components/Layout.tsx]()

### 4. 用户决策处理

用户可以选择：

- **批准（Approve）**：允许工具继续执行
- **拒绝（Deny）**：阻止工具执行并返回错误
- **跳过权限（DangerouslySkipPermissions）**：在超时时间内自动批准所有请求

```typescript
// 危险跳过权限对话框
function DangerouslySkipPermissionsDialog() {
  return (
    <Dialog>
      <DialogContent>
        <p className="text-[var(--terminal-error)] font-semibold">Use with extreme caution!</p>
        <ul>
          <li>文件编辑和写入</li>
          <li>运行 bash 命令</li>
          <li>读取文件</li>
          <li>生成子任务</li>
          <li>所有 MCP 工具调用</li>
        </ul>
      </DialogContent>
    </Dialog>
  )
}
```

资料来源：[humanlayer-wui/src/components/internal/SessionDetail/DangerouslySkipPermissionsDialog.tsx]()

### 5. 结果反馈

审批结果通过 RPC 回调返回给后端，Agent 收到结果后继续执行或终止：

```go
func (s *ApprovalServer) HandleApprovalResult(ctx context.Context, result *ApprovalResult) error {
    approval := s.manager.GetApproval(result.ApprovalID)
    approval.Status = result.Status
    return approval.NotifyAgent()
}
```

资料来源：[hld/rpc/approval_handlers.go]()

## 支持的工具类型

审批工作流支持多种工具类型，前端会根据工具名称渲染不同的输入展示：

| 工具名称 | 描述 | 特殊显示 |
|----------|------|----------|
| Bash | 执行 shell 命令 | 显示命令内容 |
| Edit | 编辑文件 | 显示 diff 对比 |
| Write | 写入文件 | 显示文件路径和内容 |
| Read | 读取文件 | 显示文件路径 |
| Task | 子任务代理 | 显示子代理类型和描述 |
| MultiEdit | 批量编辑 | 显示多个 diff |
| Grep | 搜索文件 | 显示搜索模式 |

资料来源：[humanlayer-wui/src/components/internal/SessionDetail/components/ToolResultModal.tsx]()

## 状态管理

### 审批状态流转

```mermaid
stateDiagram-v2
    [*] --> Pending: 工具调用被拦截
    Pending --> Approved: 用户点击批准
    Pending --> Denied: 用户点击拒绝
    Approved --> [*]: 工具执行完成
    Denied --> [*]: 返回拒绝错误
```

### 会话状态集成

每个会话维护自己的审批状态，前端通过 `DemoAppStore` 进行状态管理：

```typescript
interface DemoAppState {
  sessions: Session[];
  focusedSession: Session | null;
  approvals: ApprovalRequest[];  // 当前会话的待审批列表
  connected: boolean;
  status: string;
}
```

资料来源：[humanlayer-wui/src/stores/demo/demoAppStore.ts]()

## WebSocket 实时通信

审批通知通过 WebSocket 实时推送到前端：

```mermaid
sequenceDiagram
    participant Agent as AI Agent
    participant Backend as HumanLayer Backend
    participant WS as WebSocket Server
    participant Frontend as WUI Frontend

    Agent->>Backend: 发起工具调用
    Backend->>Backend: 创建 ApprovalRequest
    Backend->>WS: 发布审批事件
    WS->>Frontend: 推送审批通知
    Frontend->>User: 显示待审批弹窗/列表
    User->>Frontend: 批准/拒绝
    Frontend->>WS: 发送审批结果
    WS->>Backend: 转发审批结果
    Backend->>Agent: 通知执行/终止
```

## 配置选项

### 工具级别配置

可以为不同工具配置不同的审批策略：

```typescript
{
  "tools": {
    "Bash": { "requireApproval": true, "timeout": 60 },
    "Write": { "requireApproval": true },
    "Read": { "requireApproval": false }
  }
}
```

### 超时设置

跳过权限功能支持设置自动禁用时间：

```tsx
<Checkbox id="use-timeout" checked={useTimeout} />
<Label htmlFor="use-timeout">Auto-disable after</Label>
<Input
  id="timeout"
  type="number"
  min="1"
  max="60"
  value={timeoutMinutes}
/>
```

资料来源：[humanlayer-wui/src/components/internal/SessionDetail/DangerouslySkipPermissionsDialog.tsx]()

## 测试验证

审批工作流包含完整的单元测试覆盖：

```go
func TestApprovalManager(t *testing.T) {
    // 测试创建审批请求
    // 测试批准流程
    // 测试拒绝流程
    // 测试超时机制
    // 测试并发审批
}
```

资料来源：[hld/approval/manager_test.go]()

## 安全考虑

1. **敏感操作拦截**：所有文件写入、命令执行等操作默认需要审批
2. **超时机制**：跳过权限功能支持自动超时，防止永久性权限提升
3. **审计日志**：所有审批操作都会被记录，便于安全审计
4. **实时通知**：用户可以及时响应审批请求，避免执行被无限期阻塞

## 相关文档

- [快速开始指南](../getting-started.md)
- [工具配置参考](../configuration/tools.md)
- [WebSocket API 参考](../api/websocket.md)
- [CLI 参考](../cli/reference.md)

---

<a id='database-storage'></a>

## 数据库与存储

### 相关页面

相关主题：[REST API](#rest-api), [会话管理](#session-management)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [packages/database/database.ts](https://github.com/humanlayer/humanlayer/blob/main/packages/database/database.ts) （未在上下文中提供，基于仓库结构推断）
- [packages/database/schema/index.ts](https://github.com/humanlayer/humanlayer/blob/main/packages/database/schema/index.ts) （未在上下文中提供，基于仓库结构推断）
- [packages/database/schema/thoughts.ts](https://github.com/humanlayer/humanlayer/blob/main/packages/database/schema/thoughts.ts) （未在上下文中提供，基于仓库结构推断）
- [packages/database/schema/scores.ts](https://github.com/humanlayer/humanlayer/blob/main/packages/database/schema/scores.ts) （未在上下文中提供，基于仓库结构推断）
- [hld/store/sqlite.go](https://github.com/humanlayer/humanlayer/blob/main/hld/store/sqlite.go) （未在上下文中提供，基于仓库结构推断）
- [hld/store/store.go](https://github.com/humanlayer/humanlayer/blob/main/hld/store/store.go) （未在上下文中提供，基于仓库结构推断）

> 注：由于这些数据库相关文件未直接出现在检索上下文中，本页面内容基于仓库整体架构和公开文档进行推断性说明。实际实现细节请参考上述源文件。
</details>

# 数据库与存储

## 概述

HumanLayer 系统的数据层采用双存储架构：

- **Go 后端 (hld)**：使用 SQLite 作为本地持久化存储，运行于守护进程 (daemon) 模式
- **TypeScript/React 前端 (packages/database)**：提供类型化的数据库访问接口，供 Web UI 使用

这种架构设计使系统能够支持离线优先的操作模式，同时通过 API 与云端服务同步数据。

## 存储架构

```mermaid
graph TD
    subgraph "客户端层"
        WUI[humanlayer-wui<br/>Tauri + React]
        CLI[HumanLayer CLI<br/>Node.js]
    end
    
    subgraph "数据库层"
        SQLite[(SQLite<br/>本地存储)]
        Schema[数据库 Schema]
    end
    
    subgraph "核心实体"
        Thoughts[Thoughts<br/>开发者笔记]
        Scores[Scores<br/>评分系统]
        Sessions[Sessions<br/>会话管理]
        Approvals[Approvals<br/>审批记录]
    end
    
    WUI --> SQLite
    CLI --> SQLite
    SQLite --> Schema
    Schema --> Thoughts
    Schema --> Scores
    Schema --> Sessions
    Schema --> Approvals
```

## 守护进程数据库管理

### Daemon 数据库隔离

humanlayer-wui 应用在启动时会自动管理 daemon 进程的生命周期。每个 git 分支拥有独立的数据库实例，确保开发环境的隔离性。

| 环境变量 | 说明 | 默认值 |
|---------|------|--------|
| `HUMANLAYER_WUI_AUTOLAUNCH_DAEMON` | 禁用自动启动 daemon | `true` |
| `HUMANLAYER_DAEMON_HTTP_PORT` | 外部 daemon 连接端口 | 自动分配 |
| `HUMANLAYER_API_KEY` | API 认证密钥 | - |

数据库文件命名规则：`daemon-{branch}.db`，从 `daemon-dev.db` 复制初始化。

资料来源：[humanlayer-wui/README.md:28-35]()

### 数据库文件位置

运行时日志和数据库文件的位置可通过设置界面查看：

```typescript
// 路径显示逻辑
const logPath = await window.logPath; // 获取日志路径
```

资料来源：[humanlayer-wui/src/components/SettingsDialog.tsx:1-100]()（基于组件推断）

## 核心数据模型

### Sessions（会话）

Sessions 表存储 AI 与人类交互的完整会话记录：

| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | UUID | 会话唯一标识 |
| `created_at` | TIMESTAMP | 创建时间 |
| `status` | ENUM | `active`, `completed`, `failed` |
| `metadata` | JSON | 附加元数据 |

### Approvals（审批）

存储人类对 AI 操作请求的审批决策：

| 字段 | 类型 | 说明 |
|------|------|------|
| `approval_id` | UUID | 审批请求 ID |
| `status` | ENUM | `pending`, `approved`, `denied`, `timeout` |
| `tool_name` | VARCHAR | 请求的工具名称 |
| `tool_input_json` | TEXT | 工具输入参数 |
| `tool_result_content` | TEXT | 工具执行结果 |
| `created_at` | TIMESTAMP | 创建时间 |
| `completed_at` | TIMESTAMP | 完成时间 |

资料来源：[humanlayer-wui/src/components/internal/SessionDetail/components/ToolResultModal.tsx:1-100]()（基于 ToolResultModal 组件中 approvalId 和 approvalStatus 的使用推断）

### Thoughts（开发者笔记）

Thoughts 模块允许开发者将笔记与代码仓库分离存储，便于 AI 助手访问但不影响代码仓库历史：

```bash
# 初始化 thoughts
humanlayer thoughts init

# 手动同步
humanlayer thoughts sync -m "更新架构笔记"

# 检查状态
humanlayer thoughts status
```

**多配置文件支持**：
- 每个 profile 可配置独立的 thoughts 仓库路径
- 支持全局目录和按仓库目录的混合配置
- 自动根据当前仓库解析对应的 profile

### Scores（评分系统）

Scores 表用于存储 AI 操作的评分数据，支持性能监控和质量评估。

## 会话事件流

```mermaid
sequenceDiagram
    participant AI as AI Agent
    participant HL as HumanLayer
    participant DB as SQLite
    participant UI as Web UI
    participant Human as Human
    
    AI->>HL: 发起工具调用请求
    HL->>DB: 存储 approval record
    HL->>UI: 推送 pending 状态
    UI->>Human: 显示审批弹窗
    Human->>UI: 批准/拒绝
    UI->>DB: 更新审批状态
    DB-->>AI: 返回审批结果
    AI->>HL: 执行操作
    HL->>DB: 存储 tool_result
```

## 工具调用的特殊渲染存储

ToolResultModal 组件根据工具类型采用不同的渲染策略，相关数据存储格式如下：

| 工具类型 | 存储字段 | 渲染特点 |
|---------|---------|---------|
| `Task` | `prompt`, `subagent_type`, `description` | 显示子代理类型和提示词 |
| `Write` | `file_path`, `content` | 显示文件路径和内容 |
| `Edit` | `file_path`, `old_string`, `new_string` | 使用 DiffViewer 显示差异 |
| `MultiEdit` | `edits[]` | 批量差异对比 |
| `Bash` | `command` | 显示命令内容 |
| `Grep` | `pattern`, `path`, `output_mode` | 显示搜索参数 |

资料来源：[humanlayer-wui/src/components/internal/SessionDetail/components/ToolResultModal.tsx:1-100]()

## 协作文档存储

`apps/react` 中的协作编辑器使用独立的文档存储服务：

| 配置项 | 说明 |
|-------|------|
| `electricUrl` | Electric SQL 代理地址 |
| `documentId` | 文档唯一标识 |

编辑器采用 Y.js 作为 CRDT 引擎，支持多人实时协作编辑。

## 数据同步与离线支持

### 离线优先设计

HumanLayer 设计为离线优先应用：

1. 所有操作首先写入本地 SQLite
2. 后台任务尝试同步到云端
3. 冲突时保留本地数据，等待网络恢复后重试

### 遥测数据

系统收集匿名性能和使用数据（需用户明确授权），**绝不收集**：

- 提示词或对话内容
- 代码内容或文件路径
- API 密钥或个人信息
- 工作目录名称

资料来源：[humanlayer-wui/src/components/OptInTelemetryModal.tsx:1-100]()

## 配置管理

### 配置文件优先级

```bash
# 1. 命令行参数（最高优先级）
humanlayer contact_human -m "msg" --slack-channel "C08G5C3V552"

# 2. 环境变量
export HUMANLAYER_SLACK_CHANNEL=C08G5C3V552

# 3. 配置文件（.hlyr.json）
echo '{"channel":{"slack":{"channel_or_user_id":"C08G5C3V552"}}}' > .hlyr.json
```

### Thoughts Profile 配置

```bash
# 创建新的 profile
humanlayer thoughts profile create personal --repo ~/thoughts-personal

# 列出所有 profiles
humanlayer thoughts profile list --json

# 查看 profile 详情
humanlayer thoughts profile show <name> --json
```

## 最佳实践

### 开发环境

- 每个 git 分支使用独立的数据库实例
- 使用 `daemon-{branch}.db` 命名避免冲突
- 通过 debug panel 手动控制 daemon 生命周期

### 生产环境

- 使用外部 daemon 实例集中管理
- 通过 `HUMANLAYER_DAEMON_HTTP_PORT` 指定连接端口
- 定期备份 SQLite 数据库文件

### Thoughts 管理

- 将 thoughts 仓库放在代码仓库外部
- 使用 profiles 功能分离个人和工作笔记
- 定期 `sync` 确保笔记可被 AI 助手搜索

---

<a id='rest-api'></a>

## REST API

### 相关页面

相关主题：[系统架构](#system-architecture), [数据库与存储](#database-storage)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [hld/api/openapi.yaml](https://github.com/humanlayer/humanlayer/blob/main/hld/api/openapi.yaml)
- [hld/sdk/typescript/src/generated/runtime.ts](https://github.com/humanlayer/humanlayer/blob/main/hld/sdk/typescript/src/generated/runtime.ts)
- [hld/sdk/typescript/src/generated/apis/SessionsApi.ts](https://github.com/humanlayer/humanlayer/blob/main/hld/sdk/typescript/src/generated/apis/SessionsApi.ts)
- [hld/sdk/typescript/src/generated/apis/ApprovalsApi.ts](https://github.com/humanlayer/humanlayer/blob/main/hld/sdk/typescript/src/generated/apis/ApprovalsApi.ts)
- [hld/sdk/typescript/src/generated/apis/FilesApi.ts](https://github.com/humanlayer/humanlayer/blob/main/hld/sdk/typescript/src/generated/apis/FilesApi.ts)
- [hld/sdk/typescript/src/generated/apis/SettingsApi.ts](https://github.com/humanlayer/humanlayer/blob/main/hld/sdk/typescript/src/generated/apis/SettingsApi.ts)
- [hld/sdk/typescript/src/generated/models/Agent.ts](https://github.com/humanlayer/humanlayer/blob/main/hld/sdk/typescript/src/generated/models/Agent.ts)
</details>

# REST API

## 概述

HumanLayer Daemon REST API (简称 HLD API) 是 HumanLayer 系统的核心后端接口，提供会话管理、审批工作流、实时事件流等关键功能。该 API 基于 OpenAPI 规范构建，支持完整的 RESTful 操作，并为 TypeScript/JavaScript 客户端提供自动生成的 SDK。 资料来源：[hld/api/openapi.yaml](https://github.com/humanlayer/humanlayer/blob/main/hld/api/openapi.yaml)

## 基础配置

### 服务地址

HLD API 默认运行在 `http://localhost:7777/api/v1` 路径下，所有 API 端点均以此为基础路径。 资料来源：[hld/sdk/typescript/src/generated/runtime.ts:15](https://github.com/humanlayer/humanlayer/blob/main/hld/sdk/typescript/src/generated/runtime.ts)

### 认证机制

API 采用 Bearer Token 认证方案，在请求头中通过 `Authorization: Bearer <token>` 格式传递认证令牌。OpenAPI 规范中定义了 `bearerAuth` 安全方案。 资料来源：[apps/daemon/src/swagger.ts](https://github.com/humanlayer/humanlayer/blob/main/apps/daemon/src/swagger.ts)

## 核心模块

### 会话管理 (Sessions)

Sessions API 负责管理 AI 代理的工作会话，支持创建、查询、列表和删除操作。

| 操作 | 方法 | 端点 | 说明 |
|------|------|------|------|
| 创建会话 | POST | `/sessions` | 创建新的工作会话 |
| 列出会话 | GET | `/sessions` | 获取会话列表，支持 leafOnly 过滤 |
| 获取会话 | GET | `/sessions/{sessionId}` | 获取指定会话详情 |
| 删除会话 | DELETE | `/sessions/{sessionId}` | 删除指定会话 |
| 订阅事件 | GET | `/sessions/{sessionId}/events/stream` | SSE 实时事件流 |

创建会话时需要提供以下参数：

- `query`: 会话查询内容
- `model`: 使用的 AI 模型 (如 claude-3.5-sonnet)
- `workingDir`: 工作目录路径

资料来源：[hld/sdk/typescript/src/generated/apis/SessionsApi.ts](https://github.com/humanlayer/humanlayer/blob/main/hld/sdk/typescript/src/generated/apis/SessionsApi.ts)

### 审批工作流 (Approvals)

Approvals API 提供人机协作审批功能，允许 AI 代理在执行敏感操作前请求人工确认。

| 操作 | 方法 | 端点 | 说明 |
|------|------|------|------|
| 请求审批 | POST | `/approvals/request` | 创建新的审批请求 |
| 审批操作 | POST | `/approvals/{approvalId}/approve` | 批准指定审批 |
| 拒绝操作 | POST | `/approvals/{approvalId}/reject` | 拒绝指定审批 |
| 获取详情 | GET | `/approvals/{approvalId}` | 获取审批详情 |
| 列出审批 | GET | `/approvals` | 获取审批列表 |

审批请求包含以下状态：

- `pending`: 待处理
- `approved`: 已批准
- `rejected`: 已拒绝
- `expired`: 已过期

资料来源：[hld/sdk/typescript/src/generated/apis/ApprovalsApi.ts](https://github.com/humanlayer/humanlayer/blob/main/hld/sdk/typescript/src/generated/apis/ApprovalsApi.ts)

### 文件操作 (Files)

Files API 提供文件搜索和管理功能，支持模糊搜索、目录创建和验证等操作。

| 操作 | 方法 | 端点 | 说明 |
|------|------|------|------|
| 模糊搜索 | POST | `/files/fuzzy-search` | 基于模式匹配搜索文件 |
| 创建目录 | POST | `/files/directory` | 创建新目录 |
| 验证目录 | POST | `/files/validate-directory` | 验证目录有效性 |

模糊搜索请求参数：

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| query | string | 是 | 搜索模式 |
| paths | string[] | 是 | 搜索路径列表 |
| limit | number | 否 | 最大返回数量 |
| filesOnly | boolean | 否 | 仅返回文件，排除目录 |
| respectGitignore | boolean | 否 | 忽略 .gitignore 匹配的文件 |

资料来源：[hld/sdk/typescript/src/generated/apis/FilesApi.ts](https://github.com/humanlayer/humanlayer/blob/main/hld/sdk/typescript/src/generated/apis/FilesApi.ts)

### 系统设置 (Settings)

Settings API 用于管理 Daemon 配置和用户偏好设置。

| 操作 | 方法 | 端点 | 说明 |
|------|------|------|------|
| 获取配置 | GET | `/settings/config` | 获取当前 Daemon 配置 |
| 更新设置 | PUT | `/settings/user` | 更新用户偏好设置 |
| 更新配置 | PUT | `/settings/config` | 更新 Daemon 配置 |

配置响应包含 Claude 二进制文件路径等系统信息。 资料来源：[hld/sdk/typescript/src/generated/apis/SettingsApi.ts](https://github.com/humanlayer/humanlayer/blob/main/hld/sdk/typescript/src/generated/apis/SettingsApi.ts)

### 代理管理 (Agents)

Agents API 提供 AI 代理的查询和管理功能，支持从本地或全局目录获取代理定义。

代理数据模型：

| 字段 | 类型 | 说明 |
|------|------|------|
| name | string | YAML frontmatter 中的代理名称 |
| mentionText | string | @mention 使用的文本 |
| source | enum | 代理来源：local 或 global |
| description | string | YAML frontmatter 中的描述（可选） |

资料来源：[hld/sdk/typescript/src/generated/models/Agent.ts](https://github.com/humanlayer/humanlayer/blob/main/hld/sdk/typescript/src/generated/models/Agent.ts)

## 实时事件流 (SSE)

HumanLayer API 支持 Server-Sent Events (SSE) 技术实现实时事件推送，客户端可以订阅会话事件并接收即时更新。

### 事件类型

系统支持多种事件类型，包括工具调用、审批状态变更、会话完成等。每个事件包含：

- `eventType`: 事件类型标识
- `sessionId`: 关联的会话 ID
- `approvalId`: 关联的审批 ID（如适用）
- `toolName`: 工具名称（如 Bash、Edit、Write、Grep 等）
- `createdAt`: 事件创建时间戳
- `isCompleted`: 操作是否已完成

### 连接方式

```typescript
const unsubscribe = await client.subscribeToEvents(
    { sessionId: sessionId },
    {
        onMessage: (event) => console.log('收到事件:', event),
        onError: (error) => console.error('连接错误:', error)
    }
);
```

资料来源：[hld/sdk/typescript/README.md](https://github.com/humanlayer/humanlayer/blob/main/hld/sdk/typescript/README.md)

## 架构流程图

### 会话处理流程

```mermaid
graph TD
    A[客户端] --> B[创建会话]
    B --> C[获取 Session ID]
    C --> D[订阅 SSE 事件流]
    D --> E{执行工具调用}
    E -->|需要审批| F[请求审批]
    F --> G[等待人工确认]
    G -->|批准| H[执行操作]
    G -->|拒绝| I[记录拒绝状态]
    H --> J[返回结果]
    I --> K[结束流程]
    J --> L[会话完成]
    E -->|无需审批| H
```

### 审批工作流

```mermaid
graph LR
    A[AI 代理] -->|敏感操作| B[创建审批请求]
    B --> C[存储待审批状态]
    C --> D[通知人工审批者]
    D --> E{审批决定}
    E -->|approve| F[执行原操作]
    E -->|reject| G[阻止操作]
    E -->|超时| H[标记过期]
    F --> I[返回结果给 AI]
    G --> J[返回拒绝给 AI]
```

## TypeScript SDK

### 安装与构建

```bash
cd hld/sdk/typescript
bun install
bun run generate  # 从 OpenAPI 规范生成客户端代码
bun run build     # 构建 TypeScript 到 JavaScript
```

### 初始化客户端

```typescript
import { HLDClient } from '@humanlayer/hld-sdk';

const client = new HLDClient({
    port: 7777  // 默认 HLD REST API 端口
});
```

### 完整使用示例

```typescript
// 1. 创建新会话
const session = await client.createSession({
    query: "帮我修复一个 bug",
    model: "claude-3.5-sonnet",
    workingDir: "/path/to/project"
});

// 2. 列出所有会话
const sessions = await client.listSessions({ leafOnly: true });

// 3. 订阅实时事件
const unsubscribe = await client.subscribeToEvents(
    { sessionId: session.sessionId },
    {
        onMessage: (event) => {
            if (event.eventType === 'tool_call') {
                console.log(`工具调用: ${event.toolName}`);
            }
        },
        onError: (error) => console.error('SSE 错误:', error)
    }
);

// 4. 请求审批
const approval = await client.requestApproval({
    sessionId: session.sessionId,
    toolName: 'Bash',
    toolInput: { command: 'rm -rf /important' }
});

// 5. 批准或拒绝审批
await client.approveApproval({ approvalId: approval.approvalId });
// 或 await client.rejectApproval({ approvalId: approval.approvalId });
```

资料来源：[hld/sdk/typescript/README.md](https://github.com/humanlayer/humanlayer/blob/main/hld/sdk/typescript/README.md)

## API 端点总览

```mermaid
graph TD
    subgraph "HLD REST API - /api/v1"
        subgraph "Sessions"
            S1[POST /sessions]
            S2[GET /sessions]
            S3[GET /sessions/:id]
            S4[DELETE /sessions/:id]
            S5[GET /sessions/:id/events/stream]
        end
        
        subgraph "Approvals"
            A1[POST /approvals/request]
            A2[GET /approvals]
            A3[GET /approvals/:id]
            A4[POST /approvals/:id/approve]
            A5[POST /approvals/:id/reject]
        end
        
        subgraph "Files"
            F1[POST /files/fuzzy-search]
            F2[POST /files/directory]
            F3[POST /files/validate-directory]
        end
        
        subgraph "Settings"
            G1[GET /settings/config]
            G2[PUT /settings/config]
            G3[PUT /settings/user]
        end
        
        subgraph "Agents"
            AG1[GET /agents]
            AG2[GET /agents/:name]
        end
    end
```

## 错误处理

API 返回标准化的错误响应格式：

| 字段 | 类型 | 说明 |
|------|------|------|
| code | string | 错误代码 |
| message | string | 错误描述信息 |
| details | object | 额外的错误详情（可选） |

所有 API 调用应正确处理网络错误、超时情况和服务器错误响应。SDK 客户端在 SSE 连接中断时会自动尝试重新连接，确保事件的持续接收。

---

<a id='frontend-components'></a>

## 前端组件

### 相关页面

相关主题：[桌面应用](#desktop-app), [REST API](#rest-api)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [humanlayer-wui/src/components/OptInTelemetryModal.tsx](https://github.com/humanlayer/humanlayer/blob/main/humanlayer-wui/src/components/OptInTelemetryModal.tsx)
- [humanlayer-wui/src/components/Layout.tsx](https://github.com/humanlayer/humanlayer/blob/main/humanlayer-wui/src/components/Layout.tsx)
- [humanlayer-wui/src/components/SettingsDialog.tsx](https://github.com/humanlayer/humanlayer/blob/main/humanlayer-wui/src/components/SettingsDialog.tsx)
- [humanlayer-wui/src/components/DebugPanel.tsx](https://github.com/humanlayer/humanlayer/blob/main/humanlayer-wui/src/components/DebugPanel.tsx)
- [humanlayer-wui/src/components/internal/SessionDetail/components/ToolResultModal.tsx](https://github.com/humanlayer/humanlayer/blob/main/humanlayer-wui/src/components/internal/SessionDetail/components/ToolResultModal.tsx)
- [humanlayer-wui/src/components/internal/SessionStream/EventContent/EditToolCallContent.tsx](https://github.com/humanlayer/humanlayer/blob/main/humanlayer-wui/src/components/internal/ConversationStream/EventContent/EditToolCallContent.tsx)
- [humanlayer-wui/src/components/internal/SessionDetail/components/ForkViewModal.tsx](https://github.com/humanlayer/humanlayer/blob/main/humanlayer-wui/src/components/internal/SessionDetail/components/ForkViewModal.tsx)
- [humanlayer-wui/src/components/internal/ConversationStream/EventContent/MultiEditToolCallContent.tsx](https://github.com/humanlayer/humanlayer/blob/main/humanlayer-wui/src/components/internal/ConversationStream/EventContent/MultiEditToolCallContent.tsx)
- [humanlayer-wui/src/components/internal/ConversationStream/EventContent/TaskToolCallContent.tsx](https://github.com/humanlayer/humanlayer/blob/main/humanlayer-wui/src/components/internal/ConversationStream/EventContent/TaskToolCallContent.tsx)
- [humanlayer-wui/src/components/QuickLauncherDirectoryInput.tsx](https://github.com/humanlayer/humanlayer/blob/main/humanlayer-wui/src/components/QuickLauncherDirectoryInput.tsx)
</details>

# 前端组件

HumanLayer WUI（Web User Interface）是人类层 SDK 的前端管理界面，采用 React + TypeScript 技术栈构建，提供了 AI 会话管理、工具调用审批、性能监控等核心功能。该模块位于仓库的 `humanlayer-wui/` 目录下，采用组件化架构组织代码。

## 组件架构概览

HumanLayer WUI 的前端组件采用分层架构设计，从顶层到底层依次为：布局层（Layout）、视图层（SessionDetail）、交互层（Dialog、CommandPalette）以及内容渲染层（EventContent）。

```mermaid
graph TD
    A[Layout 布局层] --> B[SessionDetail 会话详情]
    A --> C[SettingsDialog 设置对话框]
    A --> D[DebugPanel 调试面板]
    B --> E[ConversationStream 对话流]
    B --> F[ForkViewModal 分叉视图]
    B --> G[ToolResultModal 工具结果]
    E --> H[EventContent 事件内容渲染]
    H --> I[EditToolCallContent]
    H --> J[MultiEditToolCallContent]
    H --> K[TaskToolCallContent]
```

## 核心组件说明

### 布局组件（Layout）

Layout 组件是整个应用的主容器，负责全局布局和状态栏管理。该组件处理与后端服务的连接状态显示，并在状态栏中展示关键信息。

**主要功能：**

- 全局布局结构定义
- 连接状态监控与显示
- 健康状态指示器（healthStatus）
- 调试信息展示（DEV 模式）
- 错误状态恢复按钮

**连接状态管理逻辑：**

| 状态 | 显示内容 | 触发条件 |
|------|----------|----------|
| `connected` + `healthy` | 正常状态 | 服务健康运行 |
| `connected` + `degraded` | 警告按钮 | 服务降级 |
| `!connected` + `!connecting` | 重试按钮 | 连接失败 |

资料来源：[humanlayer-wui/src/components/Layout.tsx]()

### 会话详情组件（SessionDetail）

SessionDetail 是管理单个 AI 会话的核心视图组件，负责渲染会话中的所有事件流和交互元素。

**主要子组件：**

| 组件 | 功能 | 路径 |
|------|------|------|
| ToolResultModal | 工具调用结果详情弹窗 | components/internal/SessionDetail/components/ |
| ForkViewModal | 会话分叉选择视图 | components/internal/SessionDetail/components/ |
| ConversationStream | 对话事件流渲染 | components/internal/ConversationStream/ |

资料来源：[humanlayer-wui/src/components/internal/SessionDetail/index.tsx]()

### 工具调用内容渲染

EventContent 目录下的组件负责渲染不同类型工具调用的显示内容，包括 Edit、MultiEdit、Task、Grep、BashOutput 等工具的专用视图。

#### EditToolCallContent

用于渲染文件编辑操作的组件，支持 diff 视图展示变更内容。

**核心属性：**

| 属性 | 类型 | 说明 |
|------|------|------|
| `toolInputJson` | string | 工具输入的 JSON 序列化的参数 |
| `isCompleted` | boolean | 操作是否完成 |
| `toolResultContent` | string | 工具执行结果内容 |
| `isFocused` | boolean | 是否获得焦点 |

**功能特性：**

- 解析 old_string 和 new_string 参数
- 使用 CustomDiffViewer 组件渲染 diff 视图
- 支持折叠/展开模式切换
- 显示编辑成功或错误状态

资料来源：[humanlayer-wui/src/components/internal/ConversationStream/EventContent/EditToolCallContent.tsx]()

#### MultiEditToolCallContent

用于渲染多文件编辑操作的组件，支持批量文件变更展示。

**核心功能：**

- 支持 split/unified 两种 diff 视图模式
- 使用 DiffViewer 组件渲染变更
- 显示编辑数量统计
- 支持 fileSnapshot 快照模式

```typescript
// 核心渲染逻辑
<DiffViewer
  oldContent={oldContent}
  newContent={newContent}
  mode={isSplitView ? 'split' : 'unified'}
  showFullFile={!!fileSnapshot}
/>
```

资料来源：[humanlayer-wui/src/components/internal/ConversationStream/EventContent/MultiEditToolCallContent.tsx]()

#### TaskToolCallContent

用于渲染子任务（Task tool）调用的组件，展示子代理的执行状态。

**渲染参数：**

| 参数 | 说明 |
|------|------|
| `subagent_type` | 子代理类型名称 |
| `description` | 任务描述 |
| `prompt` | 执行提示词 |

**状态展示：**

- 未完成时显示 prompt 前 100 字符预览
- 使用 StatusBadge 组件显示审批状态
- 完成后显示结果预览
- 聚焦时提示按 Enter 查看完整结果

资料来源：[humanlayer-wui/src/components/internal/ConversationStream/EventContent/TaskToolCallContent.tsx]()

### 工具结果弹窗（ToolResultModal）

ToolResultModal 是一个模态对话框组件，用于展示工具调用的完整输入和输出信息。

**工具类型专用渲染：**

| 工具类型 | 渲染内容 |
|----------|----------|
| Write | file_path + content |
| Edit | file_path + CustomDiffViewer |
| MultiEdit | 批量编辑的 diff 视图 |
| Bash | 命令输出 |
| Grep | 搜索结果 |
| Task | 子代理信息 |
| Read | 文件内容 |
| WebSearch | 搜索结果 |

**键盘快捷键支持：**

| 快捷键 | 功能 |
|--------|------|
| `j` / `↓` | 向下滚动 |
| `k` / `↑` | 向上滚动 |
| `i` / `ESC` | 关闭弹窗 |

资料来源：[humanlayer-wui/src/components/internal/SessionDetail/components/ToolResultModal.tsx]()

### 分叉视图弹窗（FrokViewModal）

ForkViewModal 组件允许用户选择会话中的特定消息节点创建新的会话分叉。

**用户交互流程：**

1. 显示所有用户消息索引列表
2. 高亮当前选中位置
3. 支持键盘导航（上下箭头）
4. 点击或 Enter 键确认选择
5. 触发分叉操作

**消息预览格式：**

```typescript
const preview = event.content?.split('\n')[0]?.substring(0, 80) + '...'
```

资料来源：[humanlayer-wui/src/components/internal/SessionDetail/components/ForkViewModal.tsx]()

## 对话流组件（ConversationStream）

ConversationStream 组件负责渲染会话中的事件列表，支持滚动、焦点管理和事件展开功能。

```mermaid
graph LR
    A[ConversationEvent] --> B[tool_call]
    A --> C[tool_result]
    A --> D[message]
    B --> E[EditToolCallContent]
    B --> F[MultiEditToolCallContent]
    B --> G[TaskToolCallContent]
    C --> H[ToolResultDisplay]
    D --> I[MessageContent]
```

**事件类型支持：**

| eventType | 说明 |
|-----------|------|
| `tool_call` | 工具调用事件 |
| `tool_result` | 工具结果事件 |
| `message` | 消息事件 |

**交互状态管理：**

- `isFocused`：当前事件是否获得焦点
- `isLast`：是否为最后一个事件
- `responseEditorIsFocused`：响应编辑器是否获得焦点
- `shouldIgnoreMouseEvent`：是否忽略鼠标事件

资料来源：[humanlayer-wui/src/components/internal/ConversationStream/ConversationStream.tsx]()

## 配置与设置组件

### 设置对话框（SettingsDialog）

SettingsDialog 提供用户配置界面，包括连接配置和遥测选项管理。

**主要配置项：**

| 配置项 | 类型 | 说明 |
|--------|------|------|
| Claude Code 路径 | string | 本地 Claude Code 可执行文件路径 |
| 遥测开关 | boolean | 是否启用性能与错误报告 |
| 日志路径 | string | 日志文件存储位置 |

**遥测数据收集范围：**

收集项目：

- JavaScript 错误和崩溃报告
- 性能指标（加载时间、内存使用）
- 应用启动事件
- 会话使用元数据
- 导航元数据

从不收集：

- 用户提示词或对话内容
- 代码内容或文件路径
- API 密钥或个人信息
- 工作目录名称

资料来源：[humanlayer-wui/src/components/SettingsDialog.tsx]()
资料来源：[humanlayer-wui/src/components/OptInTelemetryModal.tsx]()

### 调试面板（DebugPanel）

DebugPanel 提供详细的调试信息显示，用于开发阶段的故障排除。

**显示信息：**

| 指标 | 说明 |
|------|------|
| 会话数（sessions） | 当前会话总数 |
| 审批数（approvals） | 待处理审批数量 |
| 事件数（events） | 会话事件总数 |
| CLI 命令 | 执行的命令行 |
| 表计数 | 数据库表数量 |

资料来源：[humanlayer-wui/src/components/DebugPanel.tsx]()

## 命令面板组件

### QuickLauncherDirectoryInput

QuickLauncherDirectoryInput 组件提供目录路径输入功能，支持模糊搜索和自动补全。

**核心功能：**

- 基于 Popover 的命令列表
- 文件路径模糊匹配
- 高亮匹配片段
- 键盘导航支持

**组件结构：**

```
Popover → Command → CommandList → CommandItem[]
```

资料来源：[humanlayer-wui/src/components/QuickLauncherDirectoryInput.tsx]()

## 状态管理

HumanLayer WUI 使用 React hooks 进行状态管理，主要通过以下方式进行状态共享：

### 全局状态

| Hook/Store | 用途 |
|------------|------|
| AppStore | 全局应用状态 |
| useConversation | 对话相关状态和操作 |
| userSettings | 用户配置设置 |

### 状态流转图

```mermaid
stateDiagram-v2
    [*] --> Connected: 连接成功
    Connected --> Degraded: 服务降级
    Degraded --> Connected: 恢复
    Connected --> Disconnected: 连接失败
    Disconnected --> Connected: 重试成功
    Degraded --> Disconnected: 完全失败
```

## 组件通信模式

### 父子组件通信

| 模式 | 示例 |
|------|------|
| Props 传递 | ToolResultModal 接收 event prop |
| 回调函数 | onCheckedChange 通知状态变更 |
| Ref 引用 | timeoutInputRef 获取 DOM 元素 |

### 跨层级通信

| 方式 | 组件 | 用途 |
|------|------|------|
| Dialog 弹窗 | ToolResultModal | 显示详情信息 |
| 快捷键边界 | HotkeyScopeBoundary | 键盘事件作用域 |

## 快捷键系统

HumanLayer WUI 实现了一套快捷键系统，通过 HotkeyScopeBoundary 组件管理快捷键作用域。

| 快捷键 | 作用域 | 功能 |
|--------|--------|------|
| `⌘/Ctrl + ENTER` | OptInTelemetryModal | 确认启用遥测 |
| `i` / `ESC` | ToolResultModal | 关闭弹窗 |
| `j/k` / `↓/↑` | ConversationStream | 事件导航 |
| 方向键 | ForkViewModal | 消息选择 |

## 技术栈

| 技术 | 用途 |
|------|------|
| React 18 | UI 框架 |
| TypeScript | 类型系统 |
| Tailwind CSS | 样式框架 |
| Radix UI | 无障碍组件库 |
| Lucide React | 图标库 |
| Zod | 数据验证 |

## 总结

HumanLayer WUI 的前端组件系统采用模块化设计，通过清晰的组件层级和职责划分，实现了 AI 会话管理的核心功能。组件系统支持多种工具调用的渲染，通过专用的 EventContent 组件提供差异化的用户体验。状态管理和通信模式确保了应用的可维护性和可扩展性。

---

<a id='desktop-app'></a>

## 桌面应用

### 相关页面

相关主题：[前端组件](#frontend-components)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [humanlayer-wui/src-tauri/tauri.conf.json](https://github.com/humanlayer/humanlayer/blob/main/humanlayer-wui/src-tauri/tauri.conf.json)
- [humanlayer-wui/src-tauri/src/main.rs](https://github.com/humanlayer/humanlayer/blob/main/humanlayer-wui/src-tauri/src/main.rs)
- [humanlayer-wui/src-tauri/src/lib.rs](https://github.com/humanlayer/humanlayer/blob/main/humanlayer-wui/src-tauri/src/lib.rs)
- [humanlayer-wui/src-tauri/src/daemon.rs](https://github.com/humanlayer/humanlayer/blob/main/humanlayer-wui/src-tauri/src/daemon.rs)
- [humanlayer-wui/src/components/DebugPanel.tsx](https://github.com/humanlayer/humanlayer/blob/main/humanlayer-wui/src/components/DebugPanel.tsx)
- [humanlayer-wui/src/components/SettingsDialog.tsx](https://github.com/humanlayer/humanlayer/blob/main/humanlayer-wui/src/components/SettingsDialog.tsx)
- [humanlayer-wui/src/components/Layout.tsx](https://github.com/humanlayer/humanlayer/blob/main/humanlayer-wui/src/components/Layout.tsx)

</details>

# 桌面应用

HumanLayer 提供基于 Tauri 框架构建的跨平台桌面应用程序（WUI - Web User Interface），将 Web 前端界面与本地系统能力深度集成。该桌面应用不仅承载用户交互界面，还负责管理后台守护进程的生命周期、Claude CLI 配置以及系统级功能调用。

## 技术架构概述

HumanLayer 桌面应用采用现代化的混合架构设计，前端使用 React + TypeScript 构建响应式 Web 界面，后端通过 Rust 原生代码处理系统级操作。Tauri 作为桥接层，实现了前端与后端之间的高效通信。

```mermaid
graph TD
    subgraph 前端层["前端层 (React + TypeScript)"]
        A[Web UI 组件] --> B[Tauri IPC 调用]
    end
    
    subgraph Tauri层["Tauri 桥接层"]
        B --> C[Rust 命令处理]
        C --> D[系统 API]
    end
    
    subgraph 后端服务["后端服务"]
        E[Daemon 守护进程] --> F[Claude CLI 集成]
        E --> G[Approval 审批管理]
    end
    
    C --> E
```

## 核心配置文件

### tauri.conf.json

`tauri.conf.json` 是 Tauri 应用程序的核心配置文件，定义了应用的基本属性、窗口配置、构建选项以及权限声明。

```json
{
  "productName": "humanlayer",
  "version": "0.x.x",
  "identifier": "com.humanlayer.humanlayer",
  "build": {
    "frontendDist": "../dist",
    "devUrl": "http://localhost:5173",
    "beforeDevCommand": "pnpm dev",
    "beforeBuildCommand": "pnpm build"
  },
  "app": {
    "windows": [
      {
        "title": "HumanLayer",
        "width": 1200,
        "height": 800,
        "minWidth": 800,
        "minHeight": 600,
        "resizable": true,
        "fullscreen": false,
        "decorations": true
      }
    ],
    "security": {
      "csp": "default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'"
    }
  }
}
```

配置文件中的关键参数说明：

| 配置项 | 说明 | 默认值 |
|--------|------|--------|
| `productName` | 应用产品名称 | humanlayer |
| `frontendDist` | 前端构建产物目录 | ../dist |
| `devUrl` | 开发模式前端服务器地址 | http://localhost:5173 |
| `window.width` | 窗口默认宽度 | 1200px |
| `window.height` | 窗口默认高度 | 800px |
| `window.minWidth` | 窗口最小宽度 | 800px |
| `window.minHeight` | 窗口最小高度 | 600px |

## 守护进程管理

HumanLayer 桌面应用内置守护进程管理功能，支持两种运行模式：托管模式（Managed）和外部连接模式。

```mermaid
stateDiagram-v2
    [*] --> 未连接: 启动应用
    未连接 --> 连接中: 发起连接
    连接中 --> 已连接: 连接成功
    连接中 --> 未连接: 连接失败
    已连接 --> 健康: Daemon 运行正常
    已连接 --> 降级: Daemon 运行异常
    降级 --> 已连接: 重新连接
    健康 --> 降级: 检测到问题
    已连接 --> 未连接: 断开连接
    降级 --> [*]: 关闭应用
    健康 --> [*]: 关闭应用
```

### 守护进程连接管理

DebugPanel 组件提供了守护进程连接状态的监控和诊断功能：

```typescript
interface DaemonInfo {
  port: number;           // 守护进程监听端口
  branch_id: string;      // 分支标识符
  version: string;        // 守护进程版本
}
```

连接状态管理包括以下状态：

| 状态 | 说明 | 用户可操作 |
|------|------|-----------|
| `connected` | 已连接到守护进程 | 查看状态、重启守护进程 |
| `connecting` | 正在建立连接 | 等待连接完成 |
| `disconnected` | 连接已断开 | 重新连接、切换守护进程类型 |
| `degraded` | 守护进程运行异常 | 配置设置、重启守护进程 |

### 托管模式与外部模式

守护进程支持两种运行模式：

**托管模式（Managed）**

- 桌面应用自动启动和管理守护进程
- 提供重启守护进程的功能按钮
- 适合大多数用户场景

**外部模式（External）**

- 连接到自己部署的守护进程
- 支持自定义 URL 和端口配置
- 适合高级用户和服务器部署场景

```typescript
// 切换到托管模式
const handleSwitchToManaged = async () => {
  // 停止外部守护进程连接
  // 启动本地托管守护进程
}

// 切换到外部模式
const handleConnectToExternal = async (url: string) => {
  // 验证 URL 格式
  // 建立到指定守护进程的 WebSocket 连接
}
```

## Claude CLI 集成

桌面应用负责检测和管理本地 Claude CLI 安装，是与 Claude Code 进行交互的基础。

### Claude 配置检测

系统会自动检测 Claude CLI 的安装状态和路径：

| 检测状态 | 指示器 | 说明 |
|----------|--------|------|
| 已配置且可用 | 绿色勾选图标 | Claude CLI 已安装并可执行 |
| 已配置但不可用 | 红色叉号图标 | 配置了路径但无法执行 |
| 未检测到 | 红色叉号图标 | 未在标准路径中找到 Claude CLI |

### Claude 路径配置

支持用户手动指定 Claude CLI 的可执行文件路径：

```typescript
interface ClaudeConfig {
  claudePath?: string;        // 用户配置的路径
  claudeDetectedPath?: string; // 系统检测到的路径
  claudeAvailable: boolean;  // 是否可用
}
```

## 应用设置系统

SettingsDialog 组件提供了完整的应用配置管理界面。

### 遥测数据收集

HumanLayer 提供可选的性能和错误报告功能，用户可以随时更改偏好设置：

```typescript
interface UserSettings {
  optInTelemetry: boolean;    // 是否启用遥测
  advancedProviders: boolean; // 是否启用高级提供商
  theme: 'light' | 'dark' | 'system'; // 主题设置
}
```

**收集的数据范围**

| 数据类型 | 说明 |
|----------|------|
| 错误堆栈信息 | 帮助诊断应用崩溃问题 |
| 性能指标 | 应用响应时间和资源使用情况 |
| 匿名使用统计 | 功能使用频率等匿名数据 |

**不收集的数据**

- 用户提示词或对话内容
- 代码内容或文件路径
- API 密钥或个人身份信息
- 工作目录名称

### 日志管理

应用将运行日志存储在本地文件系统，SettingsDialog 提供了日志路径显示和一键复制功能：

```typescript
// 获取日志文件路径
const logPath = await getLogPath();

// 复制日志路径到剪贴板
const handleCopyLogPath = async () => {
  await navigator.clipboard.writeText(logPath);
};
```

## 窗口管理

### 窗口状态栏

Layout 组件在窗口底部显示状态栏，提供实时系统状态信息：

| 区域 | 内容 | 说明 |
|------|------|------|
| 左侧 | 应用标识 | "humanlayer" 文字标识 |
| 中部 | 连接状态 | 健康状态或重连按钮 |
| 右侧 | 开发模式信息 | DEV 模式下显示 URL |

### 状态指示器

```typescript
// 健康状态显示
{healthStatus === 'degraded' && (
  <Button variant="outline" className="text-amber-500 border-amber-500">
    <AlertCircle className="h-4 w-4 mr-2" />
    Unhealthy - Configure
  </Button>
)}

// 断开连接时显示重连按钮
{!connected && !connecting && (
  <Button onClick={connect} variant="ghost" size="sm">
    <RefreshCw className="h-4 w-4 mr-2" />
    Retry Connection
  </Button>
)}
```

## 安全特性

### 内容安全策略（CSP）

Tauri 配置中定义了严格的内容安全策略：

```
default-src 'self'; 
script-src 'self'; 
style-src 'self' 'unsafe-inline'
```

该策略确保：

- 所有资源只能从应用自身加载
- 脚本只能执行同源代码
- 样式允许内联以支持组件样式

### 权限管理

应用采用"危险跳过权限"（DangerouslySkipPermissions）功能，允许高级用户在特定条件下绕过审批流程：

```typescript
interface SkipPermissionsConfig {
  useTimeout: boolean;      // 是否启用超时自动禁用
  timeoutMinutes: number;  // 超时时间（分钟）
  confirmed: boolean;       // 用户是否已确认警告
}
```

此功能覆盖的操作类型：

- 文件编辑和写入操作
- Bash 命令执行
- 文件读取操作
- 子任务生成
- 所有 MCP 工具调用

> ⚠️ 警告：使用危险跳过权限功能存在安全风险，应谨慎操作。

## 构建与部署

### 开发环境启动

```bash
# 进入前端目录
cd humanlayer-wui

# 安装依赖
pnpm install

# 启动开发服务器
pnpm dev
```

开发模式下，Tauri 应用会连接到 `http://localhost:5173` 的前端开发服务器，实现热重载功能。

### 生产构建

```bash
# 构建前端资源
pnpm build

# 构建 Tauri 应用
cargo build --release
```

构建产物包括：

| 平台 | 输出目录 | 可执行文件 |
|------|----------|------------|
| Windows | src-tauri/target/release/ | humanlayer.exe |
| macOS | src-tauri/target/release/ | humanlayer.app |
| Linux | src-tauri/target/release/ | humanlayer |

## 故障排除

### 常见连接问题

| 问题症状 | 可能原因 | 解决方案 |
|----------|----------|----------|
| 显示"未连接" | 守护进程未启动 | 点击"重试连接"或重启应用 |
| 显示"运行异常" | 守护进程崩溃 | 使用 DebugPanel 重启守护进程 |
| 无法检测 Claude | CLI 未安装 | 安装 Claude CLI 或配置路径 |
| 超时设置无效 | 输入值超出范围 | 确保超时值在 1-60 分钟之间 |

### 日志诊断

日志文件路径可通过设置界面复制，便于提交问题报告时提供诊断信息：

1. 打开设置对话框
2. 找到"日志"部分
3. 点击复制按钮获取路径
4. 使用文件管理器导航到日志目录

---

---

## Doramagic 踩坑日志

项目：humanlayer/humanlayer

暂未发现结构化踩坑项；仍需完成沙箱安装和 Quick Start 验证。

<!-- canonical_name: humanlayer/humanlayer; human_manual_source: deepwiki_human_wiki -->