1. 项目定位与核心价值

HumanLayer 是一个围绕 CodeLayer（开源 AI 编码代理编排 IDE）展开的多模块代码仓库。CodeLayer 自身的定位是："The best way to get Coding Agents to solve hard problems in complex codebases"——一款基于 Claude Code 构建、面向复杂代码库的键盘优先 IDE，并配套一系列 CLI、SDK 与协作工具，用以在开发者与 AI 代理之间建立"人类把关（Human-in-the-Loop）"的工作流。

资料来源：README.md:1-30

仓库主要承载三件互相支撑的事情：

2. 顶层架构一览

仓库并不是单一应用，而是一个 monorepo。每个顶层目录对应一条独立的产品线或工具链：

graph TD
    A[HumanLayer Monorepo] --> B[humanlayer-wui<br/>CodeLayer 桌面 IDE]
    A --> C[hlyr<br/>统一 CLI]
    A --> D[hld<br/>Daemon + TypeScript SDK]
    A --> E[apps/react<br/>Tiptap 协作编辑]
    A --> F[hack/linear<br/>Linear CLI 工具]
    A --> G[docs<br/>官方文档站]

    B -->|调用| D
    C -->|调用| D
    C -->|本地 MCP 审批| B
    E -->|Electric/Yjs| E
    F -->|读取 Linear API| F

图示说明：实线箭头表示运行时调用或数据流方向。humanlayer-wui 与 hlyr 都通过 hld 提供的 HTTP/SSE 接口访问会话（Session）、审批（Approval）与对话事件。

3. 顶层目录清单

下表汇总了仓库根目录下具有独立职能的子项目（基于 humanlayer-wui/package.json 等清单文件整理）：

资料来源：humanlayer-wui/package.json:1-60、hlyr/README.md:1-40

4. 各子模块详解

4.1 `humanlayer-wui` —— CodeLayer 桌面 IDE

桌面端是仓库中体积最大、迭代最频繁的子项目，承担了与人类用户直接交互的几乎所有功能。

• 运行形态：通过 Tauri 2 将 React 前端打包为原生桌面应用，因此 package.json 中同时声明了 @tauri-apps/cli 与 React 工具链。
• 核心交互库：
• @tiptap/* 用于富文本与协同编辑；
• cmdk 用于命令面板；
• react-hotkeys-hook 提供键盘优先的快捷键体系；
• zustand 作为状态层（详见 src/stores/demo/README.md）；
• sonner 提供轻量提示。
• 可观测性：内置 posthog-js，并在 src/lib/telemetry/posthog-sanitizer.ts 中维护白名单式的 ALLOWED_KEYS，过滤掉 URL、UA、$current_url、$referrer 等可能泄露本地路径的键后再上行。
• Daemon 协议：与 hld 通讯的领域模型集中在 src/lib/daemon/types.ts，例如 NewApprovalEventData、SessionStatusChangedEventData、SessionSettingsChangedEventData（含 EXPIRED 原因枚举）。

graph LR
    UI[humanlayer-wui React] -->|fetch/SSE| Daemon[hld Daemon]
    UI -->|sanitize| PH[PostHog]
    UI -->|store| Z[Zustand slices]
    Z --> SessionSlice
    Z --> ThemeSlice
    Z --> LauncherSlice
    Z --> AppSlice

社区关注点：用户在 issue #956 中提出希望公司安全策略下禁止"Disable bypass permissions"开关；#944 反馈步骤悬停时自动滚动到顶部影响阅读体验；#905 建议提供 CMD+C 一键归档/重建会话的快捷键。WUI 负责承载这些 UX 改进（react-hotkeys-hook 与 Zustand 切片）。

4.2 `hlyr` —— 统一 CLI

hlyr 既是"联系人类"命令的入口，也承载 MCP 服务器、Claude Code 工作流初始化与 thoughts 笔记系统。

• 快速启动：通过 npx humanlayer contact_human -m "..." 直接运行；也可以 npm install -g . 全局安装。
• 联系渠道：HUMANLAYER_API_KEY + 可选 HUMANLAYER_SLACK_CHANNEL / HUMANLAYER_EMAIL_ADDRESS；或通过 .hlyr.json 显式声明 channel.slack.channel_or_user_id。
• Claude 子命令：hlyr claude init 将 30 个 commands、6 个 agents、1 个 settings 模板复制到项目 .claude/，支持 --all（非交互）、--force（覆盖）。
• Thoughts 系统：
• 顶层命令 humanlayer thoughts {init,sync,status,config}；
• 子命令组 profile {create,list,show,delete} 支持多 profile（不同 thoughts 仓库、reposDir、globalDir）；
• 实现见 src/thoughtsConfig.ts，通过 ResolvedProfileConfig 统一解析；
• 在 src/commands/thoughts/init.ts 中维护了仓库 README、thoughts/searchable/ 硬链接策略以及 git pre-commit 钩子。

graph TD
    CLI[hlyr CLI] -->|npx / global| Core[contact_human]
    CLI --> MCP[MCP Server]
    CLI --> Claude[claude init]
    CLI --> Thoughts[thoughts *]
    Thoughts --> Profile[profile *]
    Profile -->|ResolvedProfileConfig| Resolver

4.3 `hld` 与 TypeScript SDK

hld（HumanLayer Daemon）作为后端守护进程，向 humanlayer-wui 与 hlyr 提供：

• 会话与审批的 REST 接口（SessionsApi、ApprovalsApi、SettingsApi、FilesApi、AgentsApi、SystemApi）；
• 服务端事件流（SSE），由 HLDClient 内部 Map<string, EventSourceLike> 维护长连接；
• 统一的错误拦截中间件 createErrorInterceptor，并允许通过 HLDClientOptions.onFetchError 自定义上报。

资料来源：hld/sdk/typescript/src/client.ts:1-60

面向前端的核心数据模型 ConversationEvent（hld/sdk/typescript/src/generated/models/ConversationEvent.ts）枚举了：

• eventType：message / tool_call / tool_result / system / thinking；
• role：user / assistant / system；
• approvalStatus：pending / approved / denied / resolved；
• 字段：toolName、toolResultContent、isCompleted、approvalId 等。

4.4 `apps/react` —— 协同编辑实验

apps/react/src/components/Editor.tsx 通过 Tiptap + Yjs + Electric Provider 实现多人协同：

• 每篇文档对应一个 ElectricProvider 实例，缓存在模块级 Map 中（eProviderCache）；
• 文档数据走 http://localhost:4000/shape-proxy（Bun 应用）；
• 共享 Awareness 用于展示协作者光标 / 状态。

apps/react/src/App.tsx 负责文档选择与编辑器挂载：未选择文档时显示提示，选择后将 documentId 注入到 Editor 组件。

4.5 `hack/linear` —— 内部 Linear CLI

hack/linear/README.md 描述了一个为开发者常用的工单系统 Linear 编写的命令行小工具：

• 子命令：list-issues、get-issue、add-comment、fetch-images；
• 自动从当前 git 分支名（如 feature/ENG-123-...）中解析 issue ID；
• 提供 fish / zsh / bash shell completions；
• 通过 export LINEAR_API_KEY=... 注入凭据，对帮助/补全子命令不强制要求。

它体现了仓库 hack/ 目录一贯的风格：放置与日常开发体验相关、但不属于核心产品的小工具。

5. 关键横切关注点

5.1 状态管理

humanlayer-wui 通过 Zustand 将 UI 状态切分为多个 slice（session、launcher、theme、app），并在 src/stores/demo/ 中提供 DemoStoreProvider 与一组预制动画序列（launcherWorkflowSequence、statusChangesSequence、themeShowcaseSequence），便于在 Storybook/录屏中重现工作流。

资料来源：humanlayer-wui/src/stores/demo/README.md:1-60

5.2 遥测与隐私

posthog-sanitizer.ts 中的 ALLOWED_KEYS 同时收纳了：

• 业务事件键（session_created、approval_requested、menu_opened 等）；
• PostHog 标准属性（$current_url、$browser、$os、$session_id、$active_feature_flags 等）；
• 元素自动采集属性（tag_name、attr_class、attr_id、href）。

sanitizeEventProperties 通过递归 + 深度上限（10 层）+ 路径日志的方式保证敏感字段不会上行。

5.3 领域事件协议

humanlayer-wui/src/lib/daemon/types.ts 把 Daemon → UI 的事件聚合为：

社区 #956 中"禁止 Disable bypass permissions"诉求正是围绕 SessionSettingsChangedEventData 中 dangerously_skip_permissions 展开——目前 UI 仍允许用户勾选，但已有 EXPIRED 原因枚举支持安全策略后续扩展。

6. 开发与运行

通用脚本（来自 humanlayer-wui/package.json）：

• check：format:check + lint + typecheck 的串联，用于 PR 校验；
• test：bun test 跑单元测试；
• storybook：在 :6006 启动组件文档站，便于设计/产品对齐 UI 细节。

资料来源：humanlayer-wui/package.json:8-30

7. 常见失败模式与排查

8. 许可证与社区

仓库遵循 Apache-2.0 协议（见 README.md 顶部徽章与 hlyr/README.md 底部声明）。社区入口包括 Discord 与 Waitlist 链接（见 README.md），社区反馈主要沉淀在 GitHub Issues。

9. See Also

• 协作编辑器实现细节：apps/react/Editor 与 Tiptap+Yjs 集成
• 桌面 UI 键盘优先工作流：humanlayer-wui 快捷键与 Zustand 切片
• Daemon ↔ UI 协议：ConversationEvent 与事件类型

Research document (citation source reference)

(no reference document available)

概述

hld（HumanLayer Daemon）是 HumanLayer / CodeLayer 项目的本地后端守护进程，作为 IDE（humanlayer-wui）、CLI 工具（hlyr）以及外部脚本之间的协调中心。它承担三类核心职责：

1. 会话生命周期管理：创建、列出、归档和继续 Claude Code 会话，代理 Claude Code SDK 的执行过程。
2. 审批工作流：在 AI 代理调用工具（写文件、执行命令等）时拦截操作，向用户（通过 Slack、Email 或 Web）发起审批请求，回收结果并继续执行。
3. 事件总线与持久化：通过内部事件总线把会话状态、审批事件、设置变更等流式分发给前端和 SDK，同时将状态持久化到本地存储中。

整套架构的契约由 hld/api/openapi.yaml 描述，并由 hld/sdk/typescript 中的代码生成器输出对应的 TypeScript 客户端，使前端（humanlayer-wui）能够以强类型方式消费后端能力。资料来源：hld/sdk/typescript/src/client.ts:1-12

架构总览

graph TD
  subgraph Client[客户端层]
    WUI[humanlayer-wui<br/>React + Tauri]
    CLI[hlyr CLI]
    EXT[外部脚本 / MCP 客户端]
  end

  subgraph Daemon[hld 守护进程]
    HTTP[HTTP/REST API<br/>端口 7777]
    SSE[SSE 事件流]
    SESS[Session Manager]
    APPR[Approval Manager]
    BUS[Event Bus]
    STORE[(SQLite 存储)]
    WRAP[Claude Code Wrapper]
  end

  subgraph External[外部服务]
    SLACK[Slack]
    EMAIL[SMTP / Email]
    WEBUI[Web UI]
    CC[Claude Code SDK]
  end

  WUI -->|REST + SSE| HTTP
  CLI -->|REST| HTTP
  EXT -->|REST + SSE| HTTP

  HTTP --> SESS
  HTTP --> APPR
  SESS --> BUS
  APPR --> BUS
  SESS <-->|读写| STORE
  APPR <-->|读写| STORE
  SESS --> WRAP
  WRAP --> CC

  BUS --> SSE
  SSE --> WUI

  APPR --> SLACK
  APPR --> EMAIL
  APPR --> WEBUI

上图中各模块的具体实现分散在 hld/daemon、hld/session、hld/approval、hld/bus、hld/store 等目录中。资料来源：hld/sdk/typescript/src/client.ts:14-30、humanlayer-wui/src/lib/daemon/types.ts:1-30

进程入口

hld 的二进制入口位于 hld/cmd/hld/main.go，由它完成配置加载、日志初始化、依赖装配并启动 HTTP 服务器与事件总线。默认监听 http://127.0.0.1:7777，TypeScript 客户端默认 baseUrl 与该端口一致。资料来源：hld/sdk/typescript/src/client.ts:50-58

// 伪代码示意（参考自 main.go 与 daemon.go）
daemon := hld.NewDaemon(cfg)
daemon.Start() // 启动 HTTP、SSE、Session、Approval、Bus
<-daemon.Done()

HTTP API

路径与版本

所有 REST 端点统一挂在 /api/v1 前缀下。OpenAPI 规范文件位于 hld/api/openapi.yaml，由其生成的 TypeScript 类型被 HLDClient 直接使用，确保前后端契约一致。资料来源：hld/sdk/typescript/src/client.ts:50-70

客户端封装

HLDClient 是 TypeScript 端的核心封装类，它聚合了多个子 API（SessionsApi、ApprovalsApi、SettingsApi、FilesApi、AgentsApi、SystemApi），并内置了错误拦截中间件和 SSE 长连接管理。资料来源：hld/sdk/typescript/src/client.ts:36-50

资料来源：hld/sdk/typescript/src/client.ts:39-50、hld/sdk/typescript/src/generated/apis/FilesApi.ts:38-72

错误拦截

HLDClient 在构造 Configuration 时注入了一个错误拦截中间件 createErrorInterceptor，可在每次请求出错时通过 onFetchError 回调把 url 与 method 报告给上层，便于前端做统一重试或提示。资料来源：hld/sdk/typescript/src/client.ts:60-78

const client = new HLDClient({
  port: 7777,
  onFetchError: (err, { url, method }) => {
    console.warn(`API 调用失败 ${method} ${url}:`, err)
  },
})

事件总线与 SSE

事件通道

hld 内部维护一个事件总线（hld/bus/events.go），由 SessionManager、ApprovalManager 等组件把状态变更发布到总线，再由 HTTP 服务器以 Server-Sent Events（SSE）形式推送到订阅者。TypeScript 端通过 EventSource（或 polyfill）订阅 sseConnections 维护的连接列表。资料来源：hld/sdk/typescript/src/client.ts:18-34

事件类型

humanlayer-wui/src/lib/daemon/types.ts 定义了前端约定的事件数据结构，关键枚举与接口如下：

资料来源：humanlayer-wui/src/lib/daemon/types.ts:1-60

危险权限与超时

SessionSettingsChangedEventData 中专门包含 dangerously_skip_permissions 与 dangerously_skip_permissions_timeout_ms 字段，且定义了 SessionSettingsChangeReason.EXPIRED 用来标识因超时而被自动关闭的危险权限。资料来源：humanlayer-wui/src/lib/daemon/types.ts:42-60

社区反馈：#956 提议让企业策略禁止勾选“Disable bypass permissions”，但当前 hld 与前端都允许该选项并依赖超时来兜底。如果需要强制策略，需要在 ApprovalManager 处增加策略校验，并配合会话设置变更事件把选项置灰或拒绝保存。资料来源：humanlayer-wui/src/lib/daemon/types.ts:50-58

会话管理

创建会话

SessionsApi.createSession 接收一个 CreateSessionRequest（包含工作目录、模型、系统提示、初始查询等），由 SessionManager 创建一条 Session 记录，并通过 ClaudeCodeWrapper 启动 Claude Code SDK 子进程。资料来源：hld/sdk/typescript/src/client.ts:81-83

继续会话

ContinueSessionRequest 携带 session_id 与新的 query，同时支持 system_prompt（完全替换）或 append_system_prompt（追加到已有提示尾部）。这一区分在 humanlayer-wui 中用于“快速清除上下文 + 重新发问”的工作流。资料来源：humanlayer-wui/src/lib/daemon/types.ts:60-100

社区反馈：#905 希望在 CodeLayer 中提供类似 Claude Code /clear 的快捷方式来归档并重建会话，以更快地切换上下文。hld 后端目前已经具备 listSessions + 归档/新建能力，前端只需把 E → C → 输入名字 → 选目录 的多步骤折叠为一个热键即可。资料来源：humanlayer-wui/src/lib/daemon/types.ts:60-100

会话状态机

stateDiagram-v2
  [*] --> Created
  Created --> Running: SessionManager 启动 Wrapper
  Running --> WaitingInput: 出现 tool_use 等待人工
  WaitingInput --> Running: 审批通过 / 收到继续指令
  Running --> Completed: 正常结束
  Running --> Failed: 子进程异常
  Running --> Archived: 手动归档
  Archived --> [*]
  Completed --> [*]
  Failed --> [*]

状态变化会通过 SessionStatusChangedEventData 推送给订阅者，前端据此刷新 UI 状态徽标与审批按钮。资料来源：humanlayer-wui/src/lib/daemon/types.ts:30-42

审批工作流

数据模型

• Approval 包含 approval_id（旧名 call_id）、session_id、tool_name、工具参数、状态等。
• 决策状态在 ConversationEventApprovalStatusEnum 中枚举：pending、approved、denied、resolved。资料来源：hld/sdk/typescript/src/generated/models/ConversationEvent.ts:75-100

触发与回收

1. ClaudeCodeWrapper 监控 Claude Code SDK 输出的 tool_use 事件。
2. 命中需要审批的工具时，调用 ApprovalManager 创建一条审批记录，并通过事件总线发出 NewApprovalEventData。
3. ApprovalManager 根据配置（Slack / Email / Web）发送通知，订阅者收到回复后写入决策。
4. 决策通过 ApprovalResolvedEventData 回流，Wrapper 继续把结果回传给 Claude Code SDK。资料来源：humanlayer-wui/src/lib/daemon/types.ts:6-30

通知通道

通知通道配置遵循 HLYR 相同的优先级：

1. 命令行参数（如 --slack-channel）。
2. 环境变量（HUMANLAYER_SLACK_CHANNEL、HUMANLAYER_EMAIL_ADDRESS）。
3. 配置文件（.hlyr.json）。
4. 缺省值（Web UI）。

资料来源：hlyr/README.md:13-72

文件与代理 API

`FilesApi`

FilesApi 暴露文件/目录相关能力，关键方法包括：

• fuzzySearchFiles：在指定目录内做模糊搜索，返回带字符级高亮的匹配项，遵守 .gitignore，5 秒超时。资料来源：hld/sdk/typescript/src/generated/apis/FilesApi.ts:38-72
• createDirectory：递归创建目录。
• validateDirectory：检查路径是否合法、是否在允许的工作目录内。

`AgentsApi`

discoverAgents 用于扫描仓库内可用的 Claude Code 代理定义（.claude/agents/*.md），返回结构化结果供 UI 选择。

MCP 服务器配置

MCPServer 模型用于描述外部工具服务器（Model Context Protocol），支持两种运行方式：

资料来源：hld/sdk/typescript/src/generated/models/MCPServer.ts:8-44

持久化

hld/store/sqlite.go 提供本地持久化能力。会话、审批、事件、设置等结构均落到 SQLite 中，确保进程崩溃后状态可恢复。SQLite 路径和模式可在配置文件中调整（参见 hld/api/openapi.yaml 中 ConfigResponse 的字段定义）。

配置

运行时配置

HLDClientOptions 是 SDK 视角的运行时配置：

资料来源：hld/sdk/typescript/src/client.ts:23-34

通知配置

通知通道配置由 hlyr 共享，可通过环境变量、命令行参数或 .hlyr.json 文件提供：

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

资料来源：hlyr/README.md:40-66

SDK 使用示例

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

const client = new HLDClient({
  port: 7777,
  onFetchError: (err, { url, method }) => {
    console.error(`[hld] ${method} ${url} 失败`, err)
  },
})

// 1. 创建会话
const session = await client.createSession({
  query: '解释 hld 守护进程的事件流',
  working_directory: process.cwd(),
})

// 2. 订阅审批事件
const source = new EventSource('http://127.0.0.1:7777/api/v1/events')
source.onmessage = (evt) => {
  const data = JSON.parse(evt.data)
  if (data.event === 'new_approval') {
    console.log('新审批：', data.approval_id, data.tool_name)
  }
}

资料来源：hld/sdk/typescript/src/client.ts:36-90

失败模式与排查

资料来源：hld/sdk/typescript/src/client.ts:14-90、humanlayer-wui/src/lib/daemon/types.ts:30-60、hlyr/README.md:13-72

安全性注意事项

• 危险权限：dangerously_skip_permissions 应仅在受信任环境使用，并尽量设置较短的 timeout_ms 以确保自动过期。资料来源：humanlayer-wui/src/lib/daemon/types.ts:50-58
• 通知内容：审批通知中可能包含敏感参数（如 shell 命令），配置 Slack 频道时务必限制可见范围。
• 遥测脱敏：humanlayer-wui 端通过 posthog-sanitizer.ts 对事件属性做白名单过滤，避免后端错误信息或工具参数被意外上报。资料来源：humanlayer-wui/src/lib/telemetry/posthog-sanitizer.ts:1-60

与其他模块的关系

• CLI（hlyr）：通过同样的 REST/SSE 契约与 hld 通信，配置和通知通道可共用。资料来源：hlyr/README.md:1-90
• 前端 IDE（humanlayer-wui）：通过 @humanlayer/hld-sdk（hld/sdk/typescript）消费后端能力，事件类型定义在 humanlayer-wui/src/lib/daemon/types.ts。资料来源：humanlayer-wui/src/lib/daemon/types.ts:1-30、humanlayer-wui/package.json:21-32
• Linear CLI（hack/linear）：作为独立脚本，把 Linear 工单内容写入 thoughts/shared/，由 hlyr thoughts sync 与 hld 协同在 IDE 中展示。资料来源：hack/linear/README.md:1-50

参见

• hlyr CLI 与 thoughts 系统
• humanlayer-wui 前端架构
• HumanLayer 审批与通知通道
• Claude Code SDK 集成

概述

CodeLayer 是一个开源的 IDE（集成开发环境），专为协调 AI 编程代理而设计，定位为 Claude Code 的"超级人类化"键盘优先工作流工具。它使用 Tauri 框架打包为原生桌面应用，并使用 React 构建 Web 端用户界面。 资料来源：README.md。

整个项目是一个 monorepo，包含三个核心工作区：apps/* 和 packages/*，由 Turbo 管理构建流程，使用 Bun 作为包管理器与运行时。 资料来源：package.json:9-15。

桌面应用的整体目标是为开发者提供一个可以并行运行多个 Claude Code 会话、进行 Worktree 切换、以及进行高级上下文工程的统一界面。

概述

HumanLayer（codelayer）是一个面向 Claude Code 的开源 IDE，专注于以键盘优先（keyboard-first）的工作流编排 AI 编码代理。项目的核心子系统包含 会话（Session）管理、审批（Approval）编排、以及围绕 dangerously_skip_permissions / auto_accept_edits 的 权限监控 机制。这三个子系统共同决定了代理在执行工具调用时，是被允许自动放行、被人工拦截，还是在超时后自动失效。

本页面将围绕以下三个层面展开：

1. 会话生命周期与审批事件的数据流（涉及 hld/session 与 hld/approval 模块，以及 WUI 的 React 状态层）。
2. 权限旁路（Bypass Permissions）的开关、监控与超时机制（对应 Issue #956 的企业安全诉求）。
3. 社区对 IDE 体验的反馈（Issue #944 的自动滚动、Issue #905 的归档 / 重建快捷键），并与代码层面对应的 Hook / 组件进行映射。

资料来源：README.md

会话工作流架构

核心角色

会话工作流涉及四个核心角色：

状态机

会话的主要状态包含：Running → WaitingInput（等待人工审批）→ Running / Completed / Failed。在 dangerously_skip_permissions 启用时，会话可以绕过 WaitingInput 状态，但 PermissionMonitor 仍会跟踪其有效期。

stateDiagram-v2
    [*] --> Running: 创建会话 (CreateSession)
    Running --> WaitingInput: 工具调用需要审批
    WaitingInput --> Running: 人工批准 (Approve)
    WaitingInput --> Running: 拒绝并调整参数 (Edit & Approve)
    WaitingInput --> Failed: 人工拒绝 (Deny)
    Running --> Completed: 代理完成
    Running --> Failed: 代理异常
    Running --> Archived: 用户归档 (Archive)
    Archived --> [*]

资料来源：humanlayer-wui/src/lib/daemon/types.ts

审批数据流

WUI 通过 SSE 订阅 humanlayer-daemon（HLD）的事件流，关键事件类型在 humanlayer-wui/src/lib/daemon/types.ts 中定义：

graph TD
    A[Claude Code Agent] -->|需要审批的工具| B[ApprovalManager]
    B -->|NewApprovalEvent| C[SSE Stream]
    C --> D[HLDClient.subscribe]
    D --> E[useApprovals Hook]
    E --> F[AppStore]
    F --> G[SessionDetail UI]
    G -->|用户点击 Approve/Deny| H[useSessionActions]
    H --> I[ApprovalsApi/SessionsApi]
    I --> J[ApprovalManager 回写]
    J -->|ApprovalResolvedEvent| C
    J -->|SessionStatusChanged| F

资料来源：hld/sdk/typescript/src/client.ts、humanlayer-wui/src/hooks/useApprovals.ts

审批系统

数据模型

Approval 对象在前后端协议中保持一致，核心字段包括：

资料来源：humanlayer-wui/src/lib/daemon/types.ts

React 端状态管理

WUI 使用 Zustand 的 AppStore 管理审批与会话状态。社区中常见的工作流模式示例可在 humanlayer-wui/src/stores/demo/README.md 中找到，例如：

const completeApproval = (approvalId: string) => {
  const { removeApproval, sessions, updateSession } = store.getState()
  removeApproval(approvalId)
  const session = sessions.find(s => s.status === SessionStatus.WaitingInput)
  if (session) {
    updateSession(session.id, { status: SessionStatus.Running })
  }
}

资料来源：humanlayer-wui/src/stores/demo/README.md

useSessionActions Hook 负责封装面向用户的动作（归档、继续、删除），并以乐观更新（optimistic update）模式与 SSE 回填结合，避免闪烁。

资料来源：humanlayer-wui/src/components/internal/SessionDetail/hooks/useSessionActions.ts

权限系统：Bypass Permissions 与 Auto-Accept

三个会话级开关

SessionSettingsChangedEventData 中包含 reason: SessionSettingsChangeReason 字段，目前定义了一个枚举值 expired，表示旁路被超时关闭。

资料来源：humanlayer-wui/src/lib/daemon/types.ts

监控与 UI 反馈

• 后端 PermissionMonitor 周期性扫描活跃会话，对已过期的旁路设置将 reason 置为 expired 并发布事件。
• 前端 DangerousSkipPermissionsMonitor 监听该事件，向用户展示倒计时与到期横幅。
• DangerouslySkipPermissionsDialog 在用户主动开启 / 续期旁路时弹出确认。
• AutoAcceptIndicator 在会话详情顶部显示自动接受状态徽标。

资料来源：humanlayer-wui/src/components/DangerousSkipPermissionsMonitor.tsx、humanlayer-wui/src/components/internal/SessionDetail/DangerouslySkipPermissionsDialog.tsx、humanlayer-wui/src/components/internal/SessionDetail/AutoAcceptIndicator.tsx

超时机制状态流

stateDiagram-v2
    [*] --> Off
    Off --> Active: 用户开启 (Open Dialog → Confirm)
    Active --> Active: 用户续期 (Extend Timeout)
    Active --> Expired: PermissionMonitor 触发 reason=expired
    Expired --> Off: 事件被前端处理
    Expired --> Active: 用户重新开启
    Active --> Off: 用户主动关闭

社区反馈热点

Issue #956：禁止"Disable bypass permissions"勾选项

诉求：出于企业安全策略，管理员希望能在组织层面禁用 "Disable bypass permissions check" 选项，杜绝个别用户绕过审批。

当前实现：

• 后端目前没有组织级 / 用户级策略字段强制禁用 dangerously_skip_permissions，仅依赖客户端的对话框提示。
• DangerouslySkipPermissionsDialog 只是软提醒，不构成硬性约束。
• PermissionMonitor 仍按会话粒度跟踪旁路状态。

可能的落地路径（仅基于代码现状的推断）：

1. 在 hld/session 引入 org_policy 配置，包含 allow_dangerously_skip_permissions: boolean。
2. 在 SessionSettingsChangedEventData 中携带策略违规原因。
3. DangerouslySkipPermissionsDialog 在策略禁用时直接隐藏入口。

资料来源：humanlayer-wui/src/components/internal/SessionDetail/DangerouslySkipPermissionsDialog.tsx、hld/session/permission_monitor.go

Issue #944：悬停时自动滚动体验不佳

反馈：在 SessionDetail 中滚动浏览步骤 / 消息时，光标悬停到某条消息上会触发自动滚动回该块顶部，影响阅读节奏。

涉及代码：useAutoScroll Hook 通常使用 IntersectionObserver 或滚动事件触发滚动，缺少用户意图识别（prefers-reduced-motion、鼠标按下 / 拖动状态等）。

建议改造方向（基于代码层面）：

• 在 useAutoScroll 中加入 userScrolling 引用，仅在用户停止滚动一段时间后才执行对齐。
• 尊重 window.matchMedia('(prefers-reduced-motion: reduce)')，自动滚动降级为高亮。
• 将"自动滚动"行为拆分为可选 behavior: 'smooth' | 'none' | 'manual'，暴露给偏好设置。

资料来源：humanlayer-wui/src/components/internal/SessionDetail/hooks/useAutoScroll.ts

Issue #905：缺少一键归档 / 重建会话的快捷键

反馈：Claude Code 的 /clear 一键清空上下文，而 CodeLayer 中归档 + 重建需要：按 E → C → 命名 → 修改目录，工作树场景下尤其繁琐。

涉及代码：

• useSessionActions 已经封装了 archive 动作，可以在前端补一个 archiveAndRecreate 复合动作。
• useSessionLauncher 负责新建会话的参数收集（名称、工作目录、模型等），可与归档组合。
• AppStore.archive.test.ts 已存在针对归档的测试用例，可作为复合动作的回归基线。

建议快捷键：Cmd+C（macOS） / Ctrl+C（Win/Linux）触发 archiveAndRecreate，在设置中允许用户在归档前选择是否修改工作目录（默认继承当前 worktree）。

资料来源：humanlayer-wui/src/components/internal/SessionDetail/hooks/useSessionActions.ts、humanlayer-wui/src/hooks/useSessionLauncher.ts、humanlayer-wui/src/AppStore.archive.test.ts

周边子系统

hlyr CLI

hlyr 是命令行形态的 HumanLayer 客户端，提供 contact_human、mcp server、thoughts 管理等子命令。thoughts 子系统支持多 Profile（个人 / 组织 / 客户），将本地笔记与代码仓库解耦，并通过符号链接让 AI 助手在代理运行时访问上下文。

资料来源：hlyr/README.md、hlyr/src/thoughtsConfig.ts

TypeScript SDK

hld/sdk/typescript 暴露的 HLDClient 封装了 OpenAPI 生成代码，支持 SSE 订阅、错误拦截、请求头注入。前端 humanlayer-wui 通过 file:../hld/sdk/typescript 直接引用本地 SDK，便于在 IDE 内调试。

资料来源：hld/sdk/typescript/src/client.ts

MCP 协议

MCPServer 模型支持 stdio 与 http 两种传输方式，可附带 env 与 headers；HLD 的 SettingsApi 可管理 MCP 服务器列表。

资料来源：hld/sdk/typescript/src/generated/models/MCPServer.ts

Telemetry 与隐私

posthog-sanitizer.ts 通过白名单（ALLOWED_KEYS）递归清洗 PostHog 事件属性，避免敏感字段（路径、文本、识别码等）泄漏。这是审批 / 会话流之外、与企业合规相关的重要环节。

资料来源：humanlayer-wui/src/lib/telemetry/posthog-sanitizer.ts

协作编辑器（探索性）

仓库内 apps/react 演示了基于 Tiptap + Y.js + Electric 的协同编辑原型。虽然不在主审批流中，但暗示未来 CodeLayer 可能引入"协同审批 / 协同 Review"等扩展。

资料来源：apps/react/src/components/Editor.tsx、apps/react/src/lib/tiptap.ts

常见失败模式

配置参考

资料来源：hlyr/README.md、humanlayer-wui/src/lib/daemon/types.ts

See Also

• HumanLayer 主仓库首页
• CodeLayer Nightly Release 公告
• Issue #956 — Disallow "Disable bypass permissions"
• Issue #944 — Auto-scroll on hover feels weird
• Issue #905 — CMD+C to archive and recreate session
• packages/contracts 公共契约包

Pitfall Log / 踩坑日志

项目：humanlayer/humanlayer

摘要：发现 11 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：[Bug]: The first auto-started create-research-questions session that results from creating a task always selects the…。

1. 安装坑 · 来源证据：[Bug]: The first auto-started `create-research-questions` session that results from creating a task always selects the…

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: The first auto-started create-research-questions session that results from creating a task always selects the wrong model, ignores global `~/.claude/s…
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/humanlayer/humanlayer/issues/981 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。

2. 安装坑 · 来源证据：humanlayer thoughts init is unusable in non-TTY shells (agents/CI): per-prompt readline drops piped input

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：humanlayer thoughts init is unusable in non-TTY shells (agents/CI): per-prompt readline drops piped input
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/humanlayer/humanlayer/issues/994 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

3. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 证据：capability.host_targets | github_repo:838542536 | https://github.com/humanlayer/humanlayer | host_targets=claude, claude_code

4. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | github_repo:838542536 | https://github.com/humanlayer/humanlayer | README/documentation is current enough for a first validation pass.

5. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | github_repo:838542536 | https://github.com/humanlayer/humanlayer | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | github_repo:838542536 | https://github.com/humanlayer/humanlayer | no_demo; severity=medium

7. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | github_repo:838542536 | https://github.com/humanlayer/humanlayer | no_demo; severity=medium

8. 安全/权限坑 · 来源证据：[Feature]: Riptide - Expose a local HTTP API for external tool integration

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Feature]: Riptide - Expose a local HTTP API for external tool integration
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/humanlayer/humanlayer/issues/959 | 来源类型 github_issue 暴露的待验证使用条件。

9. 安全/权限坑 · 来源证据：[Feature]: multi org connection

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Feature]: multi org connection
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/humanlayer/humanlayer/issues/983 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。

10. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | github_repo:838542536 | https://github.com/humanlayer/humanlayer | issue_or_pr_quality=unknown

11. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | github_repo:838542536 | https://github.com/humanlayer/humanlayer | release_recency=unknown