{ "canonical_name": "humanlayer/humanlayer", "compilation_id": "pack_745e1ee021c1487d95b6ddd08e01f9f0", "created_at": "2026-05-16T18:29:21.129789+00:00", "created_by": "project-pack-compiler", "feedback": { "carrier_selection_notes": [ "viable_asset_types=skill, recipe, host_instruction, eval, preflight", "recommended_asset_types=skill, recipe, host_instruction, eval, preflight" ], "evidence_delta": { "confirmed_claims": [ "identity_anchor_present", "capability_and_host_targets_present", "install_path_declared_or_better" ], "missing_required_fields": [], "must_verify_forwarded": [ "Run or inspect `npx humanlayer` in an isolated environment.", "Confirm the project exposes the claimed capability to at least one target host." ], "quickstart_execution_scope": "allowlisted_sandbox_smoke", "sandbox_command": "npx humanlayer", "sandbox_container_image": "node:22-slim", "sandbox_execution_backend": "docker", "sandbox_planner_decision": "llm_execute_isolated_install", "sandbox_validation_id": "sbx_176df14ad58343218aa9f3b63c078b18" }, "feedback_event_type": "project_pack_compilation_feedback", "learning_candidate_reasons": [], "template_gaps": [] }, "identity": { "canonical_id": "project_e1e9277e2d1d2defd8e4da5fb9ae0344", "canonical_name": "humanlayer/humanlayer", "homepage_url": null, "license": "unknown", "repo_url": "https://github.com/humanlayer/humanlayer", "slug": "humanlayer", "source_packet_id": "phit_82582735d83f4f0cb9c0f84287c9db1b", "source_validation_id": "dval_cc65ea76d26b466faad5efb5f34affb5" }, "merchandising": { "best_for": "需要软件开发与交付能力，并使用 claude的用户", "github_forks": 917, "github_stars": 10817, "one_liner_en": "The best way to get AI coding agents to solve hard problems in complex codebases.", "one_liner_zh": "The best way to get AI coding agents to solve hard problems in complex codebases.", "primary_category": { "category_id": "software-development", "confidence": "high", "name_en": "Software Development", "name_zh": "软件开发与交付", "reason": "matched_keywords:code, coding, git" }, "target_user": "使用 claude, claude_code 等宿主 AI 的用户", "title_en": "humanlayer", "title_zh": "humanlayer 能力包", "visible_tags": [ { "label_en": "MCP Tools", "label_zh": "MCP 工具", "source": "repo_evidence_project_characteristics", "tag_id": "product_domain-mcp-tools", "type": "product_domain" }, { "label_en": "Knowledge Base Q&A", "label_zh": "知识库问答", "source": "repo_evidence_project_characteristics", "tag_id": "user_job-knowledge-base-q-a", "type": "user_job" }, { "label_en": "Workflow Automation", "label_zh": "流程自动化", "source": "repo_evidence_project_characteristics", "tag_id": "core_capability-workflow-automation", "type": "core_capability" }, { "label_en": "Node-based Workflow", "label_zh": "节点式流程编排", "source": "repo_evidence_project_characteristics", "tag_id": "workflow_pattern-node-based-workflow", "type": "workflow_pattern" }, { "label_en": "Local-first", "label_zh": "本地优先", "source": "repo_evidence_project_characteristics", "tag_id": "selection_signal-local-first", "type": "selection_signal" } ] }, "packet_id": "phit_82582735d83f4f0cb9c0f84287c9db1b", "page_model": { "artifacts": { "artifact_slug": "humanlayer", "files": [ "PROJECT_PACK.json", "QUICK_START.md", "PROMPT_PREVIEW.md", "HUMAN_MANUAL.md", "AI_CONTEXT_PACK.md", "BOUNDARY_RISK_CARD.md", "PITFALL_LOG.md", "REPO_INSPECTION.json", "REPO_INSPECTION.md", "CAPABILITY_CONTRACT.json", "EVIDENCE_INDEX.json", "CLAIM_GRAPH.json" ], "required_files": [ "PROJECT_PACK.json", "QUICK_START.md", "PROMPT_PREVIEW.md", "HUMAN_MANUAL.md", "AI_CONTEXT_PACK.md", "BOUNDARY_RISK_CARD.md", "PITFALL_LOG.md", "REPO_INSPECTION.json" ] }, "detail": { "capability_source": "Project Hit Packet + DownstreamValidationResult", "commands": [ { "command": "npx humanlayer", "label": "Node.js / npx · 官方安装入口", "source": "https://github.com/humanlayer/humanlayer#readme", "verified": true } ], "display_tags": [ "MCP 工具", "知识库问答", "流程自动化", "节点式流程编排", "本地优先" ], "eyebrow": "软件开发与交付", "glance": [ { "body": "判断自己是不是目标用户。", "label": "最适合谁", "value": "需要软件开发与交付能力，并使用 claude的用户" }, { "body": "先理解能力边界，再决定是否继续。", "label": "核心价值", "value": "The best way to get AI coding agents to solve hard problems in complex codebases." }, { "body": "未完成验证前保持审慎。", "label": "继续前", "value": "publish to Doramagic.ai project surfaces" } ], "guardrail_source": "Boundary & Risk Card", "guardrails": [ { "body": "Prompt Preview 只展示流程，不证明项目已安装或运行。", "label": "Check 1", "value": "不要把试用当真实运行" }, { "body": "claude, claude_code", "label": "Check 2", "value": "确认宿主兼容" }, { "body": "publish to Doramagic.ai project surfaces", "label": "Check 3", "value": "先隔离验证" } ], "mode": "skill, recipe, host_instruction, eval, preflight", "pitfall_log": { "items": [], "source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals", "summary": "暂未发现结构化踩坑项；仍需完成沙箱验证。", "title": "踩坑日志" }, "snapshot": { "contributors": 30, "forks": 917, "license": "unknown", "note": "站点快照，非实时质量证明；用于开工前背景判断。", "stars": 10817 }, "source_url": "https://github.com/humanlayer/humanlayer", "steps": [ { "body": "不安装项目，先体验能力节奏。", "code": "preview", "title": "先试 Prompt" }, { "body": "理解输入、输出、失败模式和边界。", "code": "manual", "title": "读说明书" }, { "body": "把上下文交给宿主 AI 继续工作。", "code": "context", "title": "带给 AI" }, { "body": "进入主力环境前先完成安装入口与风险边界验证。", "code": "verify", "title": "沙箱验证" } ], "subtitle": "The best way to get AI coding agents to solve hard problems in complex codebases.", "title": "humanlayer 能力包", "trial_prompt": "# humanlayer - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 humanlayer 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的软件开发与交付任务。\n我常用的宿主 AI：claude / Claude Code\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 示例引导, 判断线索。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- 安装前能力预览: The best way to get AI coding agents to solve hard problems in complex codebases. 输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. project-overview：项目概览。围绕“项目概览”模拟一次用户任务，不展示安装或运行结果。\n2. technology-stack：技术栈。围绕“技术栈”模拟一次用户任务，不展示安装或运行结果。\n3. system-architecture：系统架构。围绕“系统架构”模拟一次用户任务，不展示安装或运行结果。\n4. session-management：会话管理。围绕“会话管理”模拟一次用户任务，不展示安装或运行结果。\n5. approval-workflow：审批工作流。围绕“审批工作流”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. project-overview\n输入：用户提供的“项目概览”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. technology-stack\n输入：用户提供的“技术栈”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. system-architecture\n输入：用户提供的“系统架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. session-management\n输入：用户提供的“会话管理”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. approval-workflow\n输入：用户提供的“审批工作流”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / project-overview：Step 1 必须围绕“项目概览”形成一个小中间产物，并等待用户确认。\n- Step 2 / technology-stack：Step 2 必须围绕“技术栈”形成一个小中间产物，并等待用户确认。\n- Step 3 / system-architecture：Step 3 必须围绕“系统架构”形成一个小中间产物，并等待用户确认。\n- Step 4 / session-management：Step 4 必须围绕“会话管理”形成一个小中间产物，并等待用户确认。\n- Step 5 / approval-workflow：Step 5 必须围绕“审批工作流”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/humanlayer/humanlayer\n- https://github.com/humanlayer/humanlayer#readme\n- README.md\n- humanlayer.md\n- hld/README.md\n- hld/go.mod\n- humanlayer-wui/package.json\n- hlyr/package.json\n- packages/database/package.json\n- hld/daemon/daemon.go\n- hld/rpc/server.go\n- hld/api/handlers/server.go\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 humanlayer 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n", "voices": [ { "body": "当前没有项目级社区来源；不会把未抓取讨论包装成社会证明。", "items": [], "status": "待发现 Agent 补证", "title": "社区讨论" } ] }, "homepage_card": { "category": "软件开发与交付", "desc": "The best way to get AI coding agents to solve hard problems in complex codebases.", "effort": "安装已验证", "forks": 917, "icon": "code", "name": "humanlayer 能力包", "risk": "需复核", "slug": "humanlayer", "stars": 10817, "tags": [ "MCP 工具", "知识库问答", "流程自动化", "节点式流程编排", "本地优先" ], "thumb": "gray", "type": "Skill Pack" }, "manual": { "markdown": "# https://github.com/humanlayer/humanlayer 项目说明书\n\n生成时间：2026-05-16 18:28:04 UTC\n\n## 目录\n\n- [项目概览](#project-overview)\n- [技术栈](#technology-stack)\n- [系统架构](#system-architecture)\n- [事件总线系统](#event-bus-system)\n- [会话管理](#session-management)\n- [审批工作流](#approval-workflow)\n- [数据库与存储](#database-storage)\n- [REST API](#rest-api)\n- [前端组件](#frontend-components)\n- [桌面应用](#desktop-app)\n\n\n\n## 项目概览\n\n### 相关页面\n\n相关主题：[技术栈](#technology-stack), [系统架构](#system-architecture)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/humanlayer/humanlayer/blob/main/README.md)\n- [humanlayer.md](https://github.com/humanlayer/humanlayer/blob/main/humanlayer.md)\n- [hld/README.md](https://github.com/humanlayer/humanlayer/blob/main/hld/README.md)\n- [humanlayer-wui/src/components/OptInTelemetryModal.tsx](https://github.com/humanlayer/humanlayer/blob/main/humanlayer-wui/src/components/OptInTelemetryModal.tsx)\n- [humanlayer-wui/src/components/SettingsDialog.tsx](https://github.com/humanlayer/humanlayer/blob/main/humanlayer-wui/src/components/SettingsDialog.tsx)\n- [humanlayer-wui/src/components/Layout.tsx](https://github.com/humanlayer/humanlayer/blob/main/humanlayer-wui/src/components/Layout.tsx)\n- [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)\n- [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)\n\n
\n\n# 项目概览\n\n## 1. 项目简介\n\nHumanLayer 是一个开源的 AI 会话管理和控制平台，提供 SDK 和 Web 用户界面（WUI）来实现对 AI Agent 行为的精细化管理。该项目主要包含两个核心组件：**HumanLayer SDK** 和 **CodeLayer**，两者均采用 Apache 2.0 开源许可证。\n\n项目的核心目标是解决 AI Agent 在执行敏感操作时的审批和控制问题，确保人类能够对 AI 的文件编辑、命令执行、代码搜索等操作进行监督和干预。\n\n资料来源：[README.md:1-10]()\n\n## 2. 系统架构\n\n### 2.1 整体架构图\n\n```mermaid\ngraph TD\n subgraph 前端层[\"前端层 (humanlayer-wui)\"]\n A[Web UI 界面]\n B[主题选择器]\n C[设置对话框]\n D[会话管理界面]\n end\n \n subgraph 控制层[\"控制层\"]\n E[OptInTelemetryModal 遥测模块]\n F[SessionTable 会话表]\n G[ToolResultModal 工具结果模态框]\n H[DangerouslySkipPermissionsDialog 权限跳过对话框]\n end\n \n subgraph 后端/守护进程[\"Daemon 守护进程\"]\n I[托管模式]\n J[自定义连接模式]\n end\n \n subgraph 核心功能[\"HumanLayer SDK\"]\n K[工具调用审批]\n L[会话管理]\n M[健康状态监控]\n end\n \n A --> E\n A --> C\n A --> D\n D --> F\n A --> H\n C --> G\n```\n\n### 2.2 核心模块说明\n\n| 模块名称 | 功能描述 | 技术栈 |\n|---------|---------|--------|\n| HumanLayer WUI | Web 用户界面，提供会话管理和监控功能 | React + TypeScript + TailwindCSS |\n| HumanLayer SDK | Python/JS SDK，用于集成到 AI Agent 应用中 | Python, JavaScript/TypeScript |\n| CodeLayer | 代码层实现，核心业务逻辑 | Python |\n| Daemon | 守护进程，管理 AI 会话和工具调用审批 | 后端服务 |\n\n资料来源：[humanlayer-wui/src/stores/demo/export/MARKETING_GUIDE.md:1-15]()\n\n## 3. 用户界面功能\n\n### 3.1 主界面组件\n\nHumanLayer WUI 提供了完整的会话管理界面，主要组件包括：\n\n```mermaid\ngraph LR\n A[Layout 布局容器] --> B[SessionTable 会话列表]\n A --> C[SessionDetail 会话详情]\n A --> D[DebugPanel 调试面板]\n A --> E[SettingsDialog 设置对话框]\n \n C --> F[ConversationStream 对话流]\n C --> G[ToolResultModal 工具结果弹窗]\n \n F --> H[EditToolCallContent 编辑工具]\n F --> I[WriteToolCallContent 写入工具]\n F --> J[MultiEditToolCallContent 多重编辑]\n F --> K[BashToolCallContent Bash 命令]\n F --> L[GrepToolCallContent 代码搜索]\n```\n\n### 3.2 主题系统\n\n项目支持多主题切换功能，核心实现在 `ThemeSelector.tsx` 中：\n\n- 支持键盘快捷键切换主题（Mod+T）\n- 支持向上/向下导航选择\n- 主题选项存储于组件状态中\n\n```typescript\n// 主题选择器核心逻辑\ninterface ThemeOption {\n value: string;\n label: string;\n icon: React.ComponentType;\n}\n```\n\n资料来源：[humanlayer-wui/src/components/ThemeSelector.tsx:1-30]()\n\n### 3.3 连接状态管理\n\nLayout 组件负责管理守护进程连接状态：\n\n| 状态 | 说明 | UI 表现 |\n|-----|------|--------|\n| `connected` | 已连接到守护进程 | 显示正常状态栏 |\n| `connecting` | 正在连接中 | 显示加载指示器 |\n| `degraded` | 健康状态降级 | 显示警告按钮 |\n| `disconnected` | 未连接 | 显示重试按钮 |\n\n资料来源：[humanlayer-wui/src/components/Layout.tsx:1-25]()\n\n## 4. 工具调用系统\n\n### 4.1 支持的工具类型\n\nHumanLayer WUI 针对各种 AI Agent 工具提供了专门的渲染组件：\n\n| 工具名称 | 描述 | 渲染组件 |\n|---------|------|---------|\n| `Write` | 文件写入操作 | `WriteToolCallContent` |\n| `Edit` | 文件编辑操作 | `EditToolCallContent` |\n| `MultiEdit` | 多文件编辑操作 | `MultiEditToolCallContent` |\n| `Bash` | Bash 命令执行 | `BashToolCallContent` |\n| `BashOutput` | Bash 输出结果 | `BashOutputToolCallContent` |\n| `Grep` | 代码搜索 | `GrepToolCallContent` |\n| `Read` | 文件读取 | `ReadToolCallContent` |\n| `Task` | 子任务/子代理 | `TaskToolCallContent` |\n| `Plan` | 执行计划 | `PlanToolCallContent` |\n\n资料来源：[humanlayer-wui/src/components/internal/SessionDetail/components/ToolResultModal.tsx:1-80]()\n\n### 4.2 工具调用数据模型\n\n```typescript\ninterface ConversationEvent {\n approvalId?: string; // 审批 ID\n approvalStatus?: string; // 审批状态\n claudeSessionId: string; // Claude 会话 ID\n eventType: 'tool_call' | 'message'; // 事件类型\n toolName: string; // 工具名称\n toolInputJson: string; // 工具输入 JSON\n toolResultContent?: string; // 工具结果内容\n createdAt: Date; // 创建时间\n sequence: number; // 序列号\n sessionId: string; // 会话 ID\n}\n```\n\n### 4.3 权限跳过功能\n\n`DangerouslySkipPermissionsDialog` 组件提供了危险操作警告机制，支持的操作包括：\n\n- 文件编辑和写入\n- Bash 命令执行\n- 文件读取\n- 子任务生成\n- MCP 工具调用\n\n该功能包含自动禁用超时设置，范围为 1-60 分钟。\n\n资料来源：[humanlayer-wui/src/components/internal/SessionDetail/DangerouslySkipPermissionsDialog.tsx:1-50]()\n\n## 5. 设置与配置\n\n### 5.1 设置对话框功能\n\n`SettingsDialog` 组件提供了完整的配置选项：\n\n| 配置项 | 说明 | 类型 |\n|-------|------|-----|\n| 模型选择 | 选择使用的 AI 模型 | 字符串 |\n| 模型提供商 | 高级提供商选项 | 布尔值 |\n| Claude 二进制路径 | Claude CLI 路径配置 | 路径字符串 |\n| 遥测开关 | 性能与错误报告 | 布尔值 |\n| 日志路径 | 日志存储位置 | 路径 |\n\n### 5.2 Claude 配置状态\n\n```typescript\ninterface ClaudeConfig {\n claudeAvailable: boolean; // Claude 是否可用\n claudePath?: string; // 配置的路径\n claudeDetectedPath?: string; // 自动检测的路径\n}\n```\n\n状态指示器包括：\n- `CheckCircle2`：绿色图标，表示可用\n- `XCircle`：红色图标，表示不可用\n\n资料来源：[humanlayer-wui/src/components/SettingsDialog.tsx:1-100]()\n\n## 6. 遥测与隐私\n\n### 6.1 遥测模块\n\n`OptInTelemetryModal` 组件实现了可选的匿名数据收集功能。用户在首次使用时可选择是否启用。\n\n### 6.2 数据收集范围\n\n| 收集内容 | 说明 |\n|---------|------|\n| **收集** | 匿名错误报告、匿名性能数据 |\n| **不收集** | 用户提示词、会话内容、代码文件路径、API 密钥、个人信息、工作目录名称 |\n\n### 6.3 遥测确认流程\n\n```mermaid\ngraph TD\n A[首次启动] --> B{用户选择}\n B -->|同意| C[启用遥测报告]\n B -->|拒绝| D[禁用遥测]\n C --> E[显示快捷键: ⌘/Ctrl+ENTER]\n D --> F[显示'No Thanks']\n E --> G[保存偏好设置]\n F --> G\n```\n\n用户可在设置中随时更改遥测偏好设置。\n\n资料来源：[humanlayer-wui/src/components/OptInTelemetryModal.tsx:1-50]()\n\n## 7. 守护进程模式\n\n### 7.1 托管模式 (Managed)\n\n- 默认运行模式\n- 提供一键重启功能\n- 由系统自动管理守护进程生命周期\n\n### 7.2 自定义连接模式\n\n- 支持连接到运行在自定义 URL 的守护进程\n- 支持指定端口号（如 `http://127.0.0.1:7777`）\n- 提供 URL 输入框进行配置\n\n资料来源：[humanlayer-wui/src/components/DebugPanel.tsx:1-60]()\n\n## 8. 会话管理\n\n### 8.1 会话表功能\n\n`SessionTable` 组件提供会话列表管理：\n\n- 显示所有活跃会话\n- 支持会话选择（多选）\n- 显示会话元信息：工作目录、标题、模型、开始时间、最近活动时间\n- 支持会话归档后的降级显示\n\n### 8.2 会话状态\n\n| 状态属性 | 说明 |\n|---------|------|\n| `focusedSession` | 当前聚焦的会话 |\n| `selectedSessions` | 已选中的会话集合 |\n| `archived` | 归档状态（opacity: 0.6） |\n\n### 8.3 交互方式\n\n- 鼠标悬停：聚焦会话（`onMouseEnter` / `onMouseLeave`）\n- 单击行：选择会话\n- 单击复选框区域：切换选择状态\n\n资料来源：[humanlayer-wui/src/components/internal/SessionTable.tsx:1-80]()\n\n## 9. 键盘快捷键\n\n| 快捷键 | 功能 | 作用域 |\n|-------|------|--------|\n| `j` / `↓` | 下滚/下一项 | 会话列表、工具结果 |\n| `k` / `↑` | 上滚/上一项 | 会话列表、工具结果 |\n| `i` / `ESC` | 展开/关闭详情 | 工具调用详情 |\n| `Mod+T` | 切换主题 | 全局 |\n| `⌘/Ctrl+ENTER` | 确认启用遥测 | 遥测对话框 |\n\n## 10. 快速开始\n\n项目目前处于早期访问阶段：\n\n```bash\n# 加入等待列表获取早期访问权限\nnpx humanlayer join-waitlist --email \n```\n\n资料来源：[README.md:15-20]()\n\n## 11. 相关文档\n\n- [Legacy SDK 文档](./humanlayer.md) - HumanLayer SDK 详细文档\n- [HLM 文档](./hld/README.md) - HLM 相关说明\n- [贡献指南](./CONTRIBUTING.md) - 如何参与项目贡献\n\n---\n\n\n\n## 技术栈\n\n### 相关页面\n\n相关主题：[项目概览](#project-overview), [系统架构](#system-architecture)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [hld/go.mod](https://github.com/humanlayer/humanlayer/blob/main/hld/go.mod)\n- [humanlayer-wui/package.json](https://github.com/humanlayer/humanlayer/blob/main/humanlayer-wui/package.json)\n- [hlyr/package.json](https://github.com/humanlayer/humanlayer/blob/main/hlyr/package.json)\n- [packages/database/package.json](https://github.com/humanlayer/humanlayer/blob/main/packages/database/package.json)\n- [apps/react/src/App.tsx](https://github.com/humanlayer/humanlayer/blob/main/apps/react/src/App.tsx)\n- [humanlayer-wui/README.md](https://github.com/humanlayer/humanlayer/blob/main/humanlayer-wui/README.md)\n
\n\n# 技术栈\n\nHumanLayer 是一个用于 AI 代理与人协作的工具平台，其技术栈采用多语言、多层架构设计，涵盖命令行工具、Web 界面、桌面客户端和后台守护进程。\n\n## 技术栈概览\n\nHumanLayer 项目采用以下核心技术：\n\n| 层级 | 技术选型 | 用途 |\n|------|----------|------|\n| 桌面 UI | Tauri + React | 跨平台桌面应用（CodeLayer） |\n| 后端服务 | Go | 守护进程（hld） |\n| 数据库 | SQLite | 本地数据持久化 |\n| CLI 工具 | Node.js (npx) | 命令行接口 |\n| 实时通信 | WebSocket | 进程间通信 |\n| MCP 集成 | Model Context Protocol | AI 模型交互 |\n\n## 核心模块架构\n\n```mermaid\ngraph TB\n subgraph \"前端层\"\n CLI[hlyr CLI工具]\n WUI[humanlayer-wui
Tauri + React]\n REACT[apps/react
示例应用]\n end\n \n subgraph \"服务层\"\n HLD[hld 守护进程
Go]\n MCP[MCP Server]\n end\n \n subgraph \"数据层\"\n DB[(SQLite
数据库)]\n CONFIG[配置文件]\n end\n \n CLI --> HLD\n WUI --> HLD\n REACT --> MCP\n HLD --> DB\n HLD --> CONFIG\n MCP --> HLD\n```\n\n## 守护进程 (hld)\n\n### Go 语言后端\n\n守护进程 `hld` 使用 Go 语言开发，位于 `hld/` 目录。\n\n**核心职责：**\n\n- 管理 AI 会话生命周期\n- 处理工具调用审批流程\n- 维护会话状态和历史记录\n- 提供 HTTP/WebSocket API 接口\n- 与 MCP 服务器通信\n\n### 数据库层\n\n| 模块 | 技术 | 说明 |\n|------|------|------|\n| 数据库驱动 | SQLite | 轻量级嵌入式数据库 |\n| 数据模型 | 关系型 | 会话、事件、审批记录 |\n| 位置 | `packages/database/` | 共享数据库逻辑 |\n\n## 桌面客户端 (humanlayer-wui)\n\n### 技术选型\n\n| 组件 | 技术 | 版本说明 |\n|------|------|----------|\n| 桌面框架 | Tauri 2.x | Rust 后端 + Web 前端 |\n| 前端框架 | React 18.x | 组件化 UI 开发 |\n| 状态管理 | Zustand | 轻量级状态管理 |\n| UI 组件 | Radix UI | 无样式可访问组件 |\n| 样式方案 | Tailwind CSS | 原子化 CSS 框架 |\n| 构建工具 | Vite | 快速开发服务器 |\n| 类型系统 | TypeScript | 类型安全保证 |\n\n### 架构特点\n\n```mermaid\ngraph LR\n subgraph \"React 应用\"\n COMP[组件层]\n STORE[Zustand Store]\n HOOKS[自定义 Hooks]\n end\n \n subgraph \"Tauri 桥接\"\n IPC[Tauri IPC]\n COMMANDS[Rust Commands]\n end\n \n COMP --> STORE\n STORE --> HOOKS\n HOOKS --> IPC\n IPC --> COMMANDS\n COMMANDS --> HLD[hld 守护进程]\n```\n\n### 组件结构\n\n桌面客户端采用分层架构：\n\n1. **展示层**：React 组件，处理 UI 渲染\n2. **状态层**：Zustand store，管理应用状态\n3. **通信层**：Tauri IPC，与 Rust 后端通信\n4. **服务层**：Rust 后端，执行业务逻辑\n\n资料来源：[humanlayer-wui/README.md:1-15]()\n\n## CLI 工具 (hlyr)\n\n### Node.js 命令行工具\n\nCLI 工具 `hlyr` 使用 Node.js 开发，提供丰富的命令行接口。\n\n**主要功能：**\n\n| 命令 | 功能 | 用法示例 |\n|------|------|----------|\n| `join-waitlist` | 加入等待列表 | `humanlayer join-waitlist --email xxx` |\n| `contact_human` | 联系人工审核 | `humanlayer contact_human -m \"消息\"` |\n| `mcp serve` | 启动 MCP 服务器 | `humanlayer mcp serve` |\n| `mcp claude_approvals` | Claude 审批集成 | Claude Code SDK 集成 |\n| `mcp inspector` | 调试 MCP 服务器 | `humanlayer mcp inspector serve` |\n\n### MCP 协议集成\n\nHumanLayer 支持 Model Context Protocol (MCP)，实现与 AI 模型的深度集成：\n\n```mermaid\ngraph LR\n A[Claude Code
或其他 MCP 客户端] -->|MCP 协议| B[MCP Server]\n B -->|请求审批| C[hld 守护进程]\n C -->|批准/拒绝| B\n B -->|结果| A\n```\n\n**MCP 配置示例：**\n\n```json\n{\n \"mcpServers\": {\n \"approvals\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"humanlayer\", \"mcp\", \"claude_approvals\"],\n \"env\": {\n \"HUMANLAYER_API_KEY\": \"\"\n }\n }\n }\n}\n```\n\n资料来源：[hlyr/README.md:1-80]()\n\n## 工具调用系统\n\nHumanLayer 支持多种工具类型的调用与审批：\n\n### 支持的工具类型\n\n| 工具名称 | 功能描述 | 审批类型 |\n|----------|----------|----------|\n| Write | 写入文件内容 | 需要审批 |\n| Edit | 编辑文件内容 | 需要审批 |\n| Bash | 执行 Shell 命令 | 需要审批 |\n| Grep | 搜索文件内容 | 需要审批 |\n| Read | 读取文件内容 | 需要审批 |\n| Task | 启动子代理任务 | 需要审批 |\n| BashOutput | 获取后台任务输出 | 需要审批 |\n| MultiEdit | 批量编辑多个文件 | 需要审批 |\n\n### 审批流程\n\n```mermaid\nsequenceDiagram\n participant AI as AI 代理\n participant HL as HumanLayer\n participant User as 用户\n participant FS as 文件系统\n \n AI->>HL: 发起工具调用\n HL->>User: 显示审批请求\n User->>HL: 批准/拒绝\n alt 批准\n HL->>FS: 执行操作\n FS-->>HL: 操作结果\n HL-->>AI: 返回结果\n else 拒绝\n HL-->>AI: 返回拒绝原因\n end\n```\n\n## 配置管理\n\n### 配置文件格式\n\nHumanLayer 使用 JSON 格式的配置文件：\n\n```json\n{\n \"channel\": {\n \"slack\": {\n \"channel_or_user_id\": \"C08G5C3V552\"\n }\n }\n}\n```\n\n### 环境变量\n\n| 变量名 | 说明 | 默认值 |\n|--------|------|--------|\n| `HUMANLAYER_API_KEY` | API 密钥认证 | - |\n| `HUMANLAYER_DAEMON_HTTP_PORT` | 守护进程端口 | 7777 |\n| `HUMANLAYER_WUI_AUTOLAUNCH_DAEMON` | 是否自动启动守护进程 | true |\n| `HUMANLAYER_OPT_IN_TELEMETRY` | 遥测数据收集 | false |\n\n## 开发环境\n\n### 本地开发\n\n```bash\n# 1. 构建守护进程\nmake daemon-dev-build\n\n# 2. 启动开发模式\nmake codelayer-dev\n\n# 3. 或使用外部守护进程\nexport HUMANLAYER_DAEMON_HTTP_PORT=7777\nmake codelayer-dev\n```\n\n### 生产构建\n\n```bash\n# 构建包含守护进程的桌面应用\nmake codelayer-bundle\n\n# 构建过程：\n# 1. 为 macOS ARM64 构建守护进程\n# 2. 构建 CLI 工具\n# 3. 打包到 Tauri 应用\n# 4. 生成 DMG 安装包\n```\n\n## 技术特点总结\n\n| 特性 | 实现方式 | 优势 |\n|------|----------|------|\n| 跨平台 | Tauri + WebView | 支持 macOS/Windows/Linux |\n| 轻量级 | SQLite + Go | 资源占用低、启动快 |\n| 实时性 | WebSocket | 低延迟通信 |\n| 可扩展 | MCP 协议 | 兼容多种 AI 客户端 |\n| 安全 | 本地优先 | 数据存储在本地 |\n| 开源 | Apache 2.0 | 透明可审计 |\n\nHumanLayer 的技术栈设计遵循**本地优先**原则，所有敏感数据存储在用户本地设备上，通过守护进程统一管理 AI 代理的行为，实现安全可控的人机协作。\n\n---\n\n\n\n## 系统架构\n\n### 相关页面\n\n相关主题：[事件总线系统](#event-bus-system), [会话管理](#session-management), [REST API](#rest-api)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [hld/daemon/daemon.go](https://github.com/humanlayer/humanlayer/blob/main/hld/daemon/daemon.go)\n- [hld/rpc/server.go](https://github.com/humanlayer/humanlayer/blob/main/hld/rpc/server.go)\n- [hld/api/handlers/server.go](https://github.com/humanlayer/humanlayer/blob/main/hld/api/handlers/server.go)\n- [humanlayer-wui/docs/ARCHITECTURE.md](https://github.com/humanlayer/humanlayer/blob/main/humanlayer-wui/docs/ARCHITECTURE.md)\n- [hld/sdk/typescript/README.md](https://github.com/humanlayer/humanlayer/blob/main/hld/sdk/typescript/README.md)\n- [claudecode-go/README.md](https://github.com/humanlayer/humanlayer/blob/main/claudecode-go/README.md)\n- [humanlayer-wui/README.md](https://github.com/humanlayer/humanlayer/blob/main/humanlayer-wui/README.md)\n
\n\n# 系统架构\n\nHumanLayer 是一个用于在 AI Agent 系统中实现人工审批和工作流编排的开源框架。其核心设计理念是通过模块化的微服务架构，将守护进程（Daemon）、CLI 工具、Web UI 和多语言 SDK 无缝集成，为开发者提供灵活的人机协作能力。\n\n## 整体架构概览\n\n```mermaid\ngraph TB\n subgraph 客户端层\n CLI[CLI 工具
humanlayer]\n WUI[Web UI
humanlayer-wui]\n SDK_TS[TypeScript SDK]\n SDK_GO[Go SDK]\n end\n\n subgraph 核心服务层\n HLD[HumanLayer Daemon
hld]\n MCP_S[MCP Server
contact_human]\n MCP_A[MCP Server
claude_approvals]\n end\n\n subgraph 数据层\n DB[(SQLite
Daemon Database)]\n end\n\n subgraph 外部集成\n SLACK[Slack]\n EMAIL[Email]\n WEB[Web UI]\n end\n\n CLI -->|REST API / SSE| HLD\n WUI -->|REST API / SSE| HLD\n SDK_TS -->|REST API / SSE| HLD\n SDK_GO -->|Claude Code CLI| HLD\n HLD --> DB\n HLD --> MCP_S\n HLD --> MCP_A\n HLD --> SLACK\n HLD --> EMAIL\n HLD --> WEB\n```\n\nHumanLayer 采用分层架构设计，核心是 HumanLayer Daemon（简称 hld），它作为中心枢纽处理所有会话管理、审批流程和外部通道集成。客户端通过 REST API 与守护进程通信，同时支持 Server-Sent Events（SSE）实现实时事件推送。\n\n## 核心组件\n\n### HumanLayer Daemon (hld)\n\n守护进程是整个系统的核心引擎，负责：\n\n| 功能模块 | 描述 |\n|---------|------|\n| 会话管理 | 创建、跟踪和管理 AI Agent 会话生命周期 |\n| 审批引擎 | 处理工具调用的审批请求和状态流转 |\n| MCP 服务器 | 提供 contact_human 和 claude_approvals 两种 MCP 服务 |\n| 通道集成 | 连接 Slack、Email、Web UI 等人工接触渠道 |\n| 实时事件 | 通过 SSE 向订阅者推送会话和审批事件 |\n\n资料来源：[hld/daemon/daemon.go](https://github.com/humanlayer/humanlayer/blob/main/hld/daemon/daemon.go)\n\n守护进程默认监听 7777 端口，提供 REST API 接口。开发者可以通过环境变量 `HUMANLAYER_DAEMON_HTTP_PORT` 自定义端口号。\n\n### RPC 层\n\nRPC 服务器封装了进程间通信逻辑，为守护进程提供高效的远程调用接口：\n\n```go\n// RPC 服务器职责\n- 方法路由分发\n- 请求序列化/反序列化 \n- 连接池管理\n```\n\n资料来源：[hld/rpc/server.go](https://github.com/humanlayer/humanlayer/blob/main/hld/rpc/server.go)\n\n### API 处理器\n\nAPI 处理器层实现了完整的 REST API 端点，支持会话、审批、系统配置等核心资源的管理：\n\n资料来源：[hld/api/handlers/server.go](https://github.com/humanlayer/humanlayer/blob/main/hld/api/handlers/server.go)\n\n## 客户端架构\n\n### CLI 工具\n\nhumanlayer CLI 提供命令行界面，集成了多种功能模块：\n\n```bash\nhumanlayer [subcommand] [options]\n```\n\n**主要命令模块：**\n\n| 命令 | 功能描述 |\n|-----|---------|\n| `contact_human` | 从脚本或 CI 流程中联系人工审核 |\n| `mcp` | MCP 服务器管理（serve、claude_approvals、inspector） |\n| `thoughts` | 开发者笔记和文档管理 |\n| `claude` | Claude Code SDK 集成命令 |\n\n### Web UI (humanlayer-wui)\n\n基于 Tauri 和 React 构建的跨平台桌面/Web 应用：\n\n```mermaid\ngraph LR\n A[Tauri App] --> B[React Frontend]\n B --> C[Zustand Store]\n C --> D[Demo Mode]\n C --> E[Real Daemon]\n E --> F[hld REST API]\n```\n\n**技术栈：**\n\n| 层级 | 技术选型 |\n|-----|---------|\n| 桌面框架 | Tauri |\n| 前端框架 | React |\n| 状态管理 | Zustand |\n| 样式系统 | Tailwind CSS |\n| 构建工具 | Vite |\n\n资料来源：[humanlayer-wui/README.md](https://github.com/humanlayer/humanlayer/blob/main/humanlayer-wui/README.md)\n\n### TypeScript SDK\n\n为 TypeScript/JavaScript 应用提供 hld REST API 客户端封装：\n\n```typescript\nimport { HLDClient } from '@humanlayer/hld-sdk';\n\nconst client = new HLDClient({\n port: 7777 // 默认 HLD REST API 端口\n});\n\nconst session = await client.createSession({\n query: \"Help me fix a bug\",\n model: \"claude-3.5-sonnet\",\n workingDir: \"/path/to/project\"\n});\n```\n\n**SDK 特性：**\n\n- 完整的 REST API 覆盖\n- SSE 实时事件订阅\n- Node.js 和浏览器环境兼容\n- TypeScript 类型自动生成\n\n资料来源：[hld/sdk/typescript/README.md](https://github.com/humanlayer/humanlayer/blob/main/hld/sdk/typescript/README.md)\n\n### Go SDK (claudecode-go)\n\n为 Go 应用提供 Claude Code CLI 的程序化交互能力：\n\n```go\nclient, err := claudecode.NewClient()\nsession, err := client.Launch(claudecode.SessionConfig{\n Query: \"Build a REST API\",\n Model: claudecode.ModelSonnet,\n OutputFormat: claudecode.OutputStreamJSON,\n})\n```\n\n资料来源：[claudecode-go/README.md](https://github.com/humanlayer/humanlayer/blob/main/claudecode-go/README.md)\n\n## 会话管理架构\n\n### 会话状态机\n\n```mermaid\nstateDiagram-v2\n [*] --> Created: 创建会话\n Created --> Running: 启动执行\n Running --> Completed: 正常完成\n Running --> Failed: 执行错误\n Running --> Paused: 暂停\n Paused --> Running: 恢复\n Completed --> Archived: 归档\n Failed --> Archived: 归档\n Archived --> [*]: 删除\n```\n\n### 会话数据结构\n\n```typescript\ninterface Session {\n sessionId: string // 会话唯一标识\n query: string // 用户查询\n model: string // AI 模型\n workingDir: string // 工作目录\n status: SessionStatus // Running | Completed | Failed | Archived\n createdAt: Date // 创建时间\n events: ConversationEvent[] // 事件流\n}\n```\n\n### 会话控制功能\n\n| 功能 | 描述 |\n|-----|------|\n| Fork | 从当前状态创建分支会话 |\n| Bypass | 跳过审批直接执行（危险操作） |\n| Auto-Accept | 自动接受审批请求 |\n| Archive | 归档会话以清理视图 |\n\n## 审批工作流\n\n### 审批流程\n\n```mermaid\nsequenceDiagram\n participant AI as AI Agent\n participant HLD as HumanLayer Daemon\n participant Human as 人工渠道\n participant MCP as MCP Server\n\n AI->>HLD: 请求执行工具调用\n HLD->>MCP: 发送审批请求\n MCP->>Human: 推送待审批通知\n Human-->>MCP: 审批决策 (approve/deny)\n MCP-->>HLD: 返回审批结果\n HLD-->>AI: 允许/拒绝执行\n```\n\n### MCP 服务器集成\n\nHumanLayer 提供两种 MCP 服务器实现：\n\n#### contact_human MCP 服务器\n\n用于脚本和 CI 流程中的人工接触场景：\n\n```bash\nhumanlayer mcp serve\n```\n\n#### claude_approvals MCP 服务器\n\n与 Claude Code SDK 集成的审批工作流：\n\n```bash\nhumanlayer mcp claude_approvals\n```\n\n**MCP 配置文件示例：**\n\n```json\n{\n \"mcpServers\": {\n \"approvals\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"humanlayer\", \"mcp\", \"claude_approvals\"],\n \"env\": {\n \"HUMANLAYER_API_KEY\": \"\"\n }\n }\n }\n}\n```\n\n## 数据持久化\n\n### 数据库架构\n\nHumanLayer Daemon 使用 SQLite 作为默认数据库：\n\n```\ndaemon-{branch}.db # 每个 git 分支独立的数据库实例\n```\n\n**核心数据表：**\n\n| 表名 | 用途 |\n|-----|------|\n| sessions | 会话元数据 |\n| events | 会话事件流 |\n| approvals | 审批请求记录 |\n| settings | 用户配置 |\n\n### 开发环境数据库管理\n\n```mermaid\ngraph TD\n A[daemon-dev.db] -->|git checkout| B[daemon-{branch}.db]\n B -->|分支隔离| C[session-1.db]\n B -->|端口隔离| D[session-2.db]\n B -->|Socket 隔离| E[session-3.db]\n```\n\n开发模式下，每个 git 分支自动获得独立的数据库实例、Socket 和端口，确保环境隔离。\n\n## 实时通信\n\n### SSE 事件订阅\n\n客户端可以订阅实时事件流：\n\n```typescript\nconst unsubscribe = await client.subscribeToEvents(\n { sessionId: session.sessionId },\n {\n onMessage: (event) => console.log('Event:', event),\n onError: (error) => console.error('Error:', error)\n }\n);\n```\n\n### 事件类型\n\n| 事件类型 | 描述 |\n|---------|------|\n| `tool_call` | AI Agent 发起工具调用 |\n| `tool_result` | 工具执行结果返回 |\n| `approval_request` | 审批请求创建 |\n| `approval_response` | 审批决策完成 |\n| `session_status` | 会话状态变更 |\n\n## 配置系统\n\n### 配置优先级\n\n```\n命令行参数 > 环境变量 > 配置文件 (.hlyr.json) > 默认值\n```\n\n### 通道配置示例\n\n```bash\n# Slack 渠道\nexport HUMANLAYER_SLACK_CHANNEL=C08G5C3V552\n\n# Email 渠道\nexport HUMANLAYER_EMAIL_ADDRESS=human@example.com\n\n# API 密钥\nexport HUMANLAYER_API_KEY=...\n```\n\n## 部署架构\n\n### 开发环境\n\n```mermaid\ngraph LR\n A[humanlayer CLI] --> B[localhost:7777]\n C[CodeLayer WUI] --> B\n D[TypeScript SDK] --> B\n```\n\n### 生产环境\n\n```mermaid\ngraph TB\n subgraph 云端服务\n HLD_PROD[HumanLayer Daemon
生产实例]\n DB_PROD[(SQLite
生产数据库)]\n end\n\n subgraph 客户端\n CI_CD[CI/CD Pipeline]\n DEVELOPER[开发者环境]\n end\n\n CI_CD -->|contact_human| HLD_PROD\n DEVELOPER -->|CLI/SDK| HLD_PROD\n HLD_PROD --> DB_PROD\n```\n\n## 扩展机制\n\n### 工具调用集成\n\nHumanLayer 支持拦截和审批多种工具调用：\n\n| 工具类型 | 描述 |\n|---------|------|\n| Bash | 命令执行审批 |\n| Write/Edit | 文件修改审批 |\n| Grep | 搜索操作 |\n| Task | 子代理任务审批 |\n| BashOutput | 后台任务输出监控 |\n\n### 自定义通道\n\n开发者可以通过配置扩展新的联系方式：\n\n```json\n{\n \"channel\": {\n \"slack\": {\n \"channel_or_user_id\": \"C08G5C3V552\"\n }\n }\n}\n```\n\n## 安全考虑\n\n### 敏感信息处理\n\n- API 密钥通过环境变量传递\n- 数据库文件按分支隔离\n- Bypass 和 Auto-Accept 功能需要显式启用\n- 审计日志记录所有审批决策\n\n### 权限控制\n\n```typescript\ninterface SessionPermissions {\n bypassEnabled: boolean // 跳过审批\n autoAcceptEnabled: boolean // 自动接受\n allowedTools?: string[] // 允许的工具列表\n}\n```\n\n## 总结\n\nHumanLayer 的系统架构围绕守护进程构建，通过标准化的 REST API 和 SSE 事件机制连接多种客户端。模块化设计允许开发者按需使用 CLI、SDK 或 MCP 服务器，同时保持部署的灵活性。数据层的 SQLite 支持和开发环境的自动隔离机制，使系统既适合生产环境又便于本地调试。\n\n---\n\n\n\n## 事件总线系统\n\n### 相关页面\n\n相关主题：[系统架构](#system-architecture), [会话管理](#session-management)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [hld/bus/events.go](https://github.com/humanlayer/humanlayer/blob/main/hld/bus/events.go) - **未在当前上下文中检索到**\n- [hld/bus/types.go](https://github.com/humanlayer/humanlayer/blob/main/hld/bus/types.go) - **未在当前上下文中检索到**\n- [hld/bus/events_test.go](https://github.com/humanlayer/humanlayer/blob/main/hld/bus/events_test.go) - **未在当前上下文中检索到**\n\n> ⚠️ **注意**：本次查询中未检索到上述源码文件的内容。当前页面内容基于仓库中实际可检索的前端组件和存储相关文件生成，涵盖会话事件流、工具调用事件和对话事件渲染等与事件总线相关的功能实现。\n
\n\n# 事件总线系统\n\n## 概述\n\nHumanLayer 的事件总线系统是核心的消息传递基础设施，负责在整个应用程序中传播和路由事件。从当前可检索的代码来看，该系统主要处理以下几类事件：\n\n- **对话事件（Conversation Events）**：工具调用、工具结果、消息内容等\n- **会话事件（Session Events）**：会话创建、更新、完成、失败等状态变更\n- **工具调用事件（Tool Call Events）**：Bash、Edit、Write、Read、Grep、MultiEdit、Task 等工具的执行事件\n- **UI 事件**：焦点变更、鼠标\nError with Openai API: output new_sensitive (1027)\n\nPlease check that you have set the OPENAI_API_KEY environment variable with a valid API key.\n\n---\n\n\n\n## 会话管理\n\n### 相关页面\n\n相关主题：[系统架构](#system-architecture), [审批工作流](#approval-workflow), [数据库与存储](#database-storage)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [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)\n- [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)\n- [humanlayer-wui/src/components/SessionsEmptyState.tsx](https://github.com/humanlayer/humanlayer/blob/main/humanlayer-wui/src/components/SessionsEmptyState.tsx)\n- [humanlayer-wui/src/components/DebugPanel.tsx](https://github.com/humanlayer/humanlayer/blob/main/humanlayer-wui/src/components/DebugPanel.tsx)\n- [humanlayer-wui/src/stores/demo/demoAppStore.ts](https://github.com/humanlayer/humanlayer/blob/main/humanlayer-wui/src/stores/demo/demoAppStore.ts)\n
\n\n# 会话管理\n\n会话管理是 HumanLayer 系统的核心功能模块，负责协调 AI 编码代理与人类审批者之间的交互流程。该模块追踪和管理每个工作会话的完整生命周期，包括工具调用审批、状态监控和结果展示。\n\n## 系统架构\n\nHumanLayer 的会话管理采用分层架构设计，由前端 UI 层、状态管理层和后端守护进程层组成。各层之间通过 HTTP/WebSocket 协议进行通信，确保会话状态的一致性和实时同步。\n\n```mermaid\ngraph TB\n subgraph 前端层\n WUI[Web/Desktop UI]\n CLI[命令行工具]\n end\n \n subgraph 状态管理层\n Store[Zustand Store]\n end\n \n subgraph 后端层\n Daemon[Daemon 守护进程]\n SessionMgr[Session Manager]\n ClaudeWrapper[Claude Code Wrapper]\n end\n \n WUI <--> Store\n CLI <--> Store\n Store <--> Daemon\n Daemon --> SessionMgr\n SessionMgr --> ClaudeWrapper\n```\n\n## 会话状态模型\n\n每个会话（Session）包含多个关键属性，用于追踪会话的完整生命周期。状态模型定义了会话的基本信息、参与者和当前运行状态。\n\n### 核心数据结构\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| id | string | 会话唯一标识符 |\n| createdAt | Date | 会话创建时间 |\n| status | string | 会话状态 |\n| claudeSessionId | string | Claude 会话标识 |\n| approvalStatus | string | 审批状态 |\n\n会话中的事件（Event）记录了每次工具调用和用户交互的详细信息。事件类型包括 `tool_call`、`tool_result`、`message` 等，每种事件都有对应的输入参数和输出内容。\n\n资料来源：[ConversationEventRow.stories.tsx:30-50]()\n\n### 事件类型\n\nHumanLayer 支持多种会话事件类型，每种类型在 UI 中有特定的渲染方式：\n\n- **tool_call** - AI 代理发起的工具调用请求\n- **tool_result** - 工具执行结果\n- **message** - 用户消息\n- **BashOutput** - Bash 命令输出\n\n## 工具调用处理\n\n工具调用是会话中的核心交互单元。当 Claude Code 代理尝试执行敏感操作时（如文件写入、编辑或 Bash 命令），系统会创建待审批的工具调用事件。\n\n### 工具类型渲染\n\nHumanLayer 为不同类型的工具提供专门的内容渲染组件。这种设计允许每种工具以最适合其数据结构的格式展示结果。\n\n```mermaid\ngraph LR\n TC[Tool Call Event] --> Check{工具类型?}\n Check -->|Write| WriteRender[WriteToolCallContent]\n Check -->|Edit| EditRender[EditToolCallContent]\n Check -->|MultiEdit| MERender[MultiEditToolCallContent]\n Check -->|Task| TaskRender[TaskToolCallContent]\n Check -->|Grep| GrepRender[GrepToolCallContent]\n Check -->|BashOutput| BashRender[BashOutputContent]\n```\n\n### Write 工具渲染\n\n对于文件写入操作，系统显示目标文件路径和写入内容：\n\n```tsx\nif (toolCall.toolName === 'Write') {\n return (\n
\n
\n File:{' '}\n {args.file_path}\n
\n
\n Content:\n 
\n          {args.content}\n
\n
\n
\n )\n}\n```\n\n资料来源：[ToolResultModal.tsx:20-40]()\n\n### Edit 工具渲染\n\n编辑操作使用差异查看器（DiffViewer）展示修改前后的内容对比：\n\n```tsx\nif (toolCall.toolName === 'Edit') {\n return (\n
\n
\n File:{' '}\n {args.file_path}\n
\n
\n \n
\n
\n )\n}\n```\n\n资料来源：[ToolResultModal.tsx:42-60]()\n\n### Task 子代理渲染\n\n对于任务工具（子代理），系统展示子代理类型、描述和提示词信息：\n\n```tsx\nif (toolCall.toolName === 'Task' && args.subagent_type) {\n return (\n
\n
\n Sub-agent Type:{' '}\n {args.subagent_type}\n
\n {args.description && (\n
\n Description:{' '}\n {args.description}\n
\n )}\n {args.prompt && (\n
\n
Prompt:
\n 
\n            {args.prompt}\n
\n
\n )}\n
\n )\n}\n```\n\n资料来源：[ToolResultModal.tsx:5-30]()\n\n## 会话状态管理\n\n前端使用 Zustand 进行状态管理，会话相关的状态存储在 `demoAppStore` 中。状态管理提供了对会话列表、焦点会话和模拟功能的完整控制。\n\n### 状态接口定义\n\n```typescript\ninterface DemoAppState {\n sessions: Session[]\n focusedSession: string | null\n launcherOpen: boolean\n launcherMode: 'command' | 'input'\n launcherView: 'menu' | 'input'\n \n // 操作方法\n setFocusedSession: (sessionId: string | null) => void\n addSession: (session: Session) => void\n updateSession: (id: string, updates: Partial) => void\n removeSession: (id: string) => void\n clearSessions: () => void\n \n // 复杂工作流操作\n simulateLaunchSession: (query: string) => void\n simulateSessionComplete: (sessionId: string) => void\n simulateSessionFailed: (sessionId: string, error: string) => void\n}\n```\n\n资料来源：[demoAppStore.ts:20-50]()\n\n### 会话创建流程\n\n新会话的创建遵循以下流程：\n\n1. 用户发起会话创建请求\n2. 系统分配唯一会话标识符\n3. 初始化会话状态为空闲\n4. 启动 Claude Code 包装器\n5. 建立与守护进程的连接\n\n空状态组件提供了创建会话的入口点：\n\n```tsx\n
\n \n \n
\n```\n\n资料来源：[SessionsEmptyState.tsx:30-40]()\n\n## 守护进程集成\n\nDebugPanel 组件提供了与后端守护进程交互的调试界面，支持查看连接状态、守护进程类型和重启功能。\n\n### 连接状态监控\n\n| 状态 | 说明 | UI 显示 |\n|------|------|---------|\n| connected | 已连接 | 绿色标签 |\n| connecting | 连接中 | 加载动画 |\n| disconnected | 断开连接 | 红色标签 + 重试按钮 |\n\n### 守护进程类型\n\n系统支持两种守护进程管理模式：\n\n- **managed** - 由应用自动管理的守护进程\n- **external** - 连接到外部运行的守护进程\n\n```tsx\n{daemonType === 'managed' ? (\n \n) : (\n \n)}\n```\n\n资料来源：[DebugPanel.tsx:40-55]()\n\n### 外部守护进程连接\n\n用户可以连接到运行在自定义 URL 或端口的守护进程：\n\n```tsx\n\n```\n\n支持通过环境变量指定端口：\n\n```bash\nexport HUMANLAYER_DAEMON_HTTP_PORT=7777\n```\n\n资料来源：[DebugPanel.tsx:60-70]()\n\n## 会话事件流\n\n会话中的事件按照序列号顺序处理，确保操作的因果关系得到正确维护。每个事件包含时间戳、事件类型、关联的工具调用和审批状态。\n\n### 事件序列示例\n\n```json\n{\n \"id\": 7,\n \"eventType\": \"tool_call\",\n \"toolName\": \"Grep\",\n \"sequence\": 7,\n \"approvalId\": \"approval-grep-1\",\n \"approvalStatus\": \"pending\",\n \"createdAt\": \"2025-09-18T18:44:52Z\",\n \"toolInputJson\": \"{\\\"pattern\\\":\\\"TODO\\\",\\\"path\\\":\\\"/src\\\"}\"\n}\n```\n\n资料来源：[ConversationEventRow.stories.tsx:50-70]()\n\n### BashOutput 事件处理\n\nBash 命令的输出作为独立事件处理，支持后台任务完成通知：\n\n```json\n{\n \"id\": 24,\n \"eventType\": \"tool_call\",\n \"toolName\": \"BashOutput\",\n \"isCompleted\": true,\n \"toolResultContent\": \"completed\\n0\\nhey\"\n}\n```\n\n资料来源：[ConversationEventRow.stories.tsx:100-120]()\n\n## 审批状态管理\n\n每个工具调用都有对应的审批状态，用于控制是否允许操作执行。状态变更通过 WebSocket 实时推送到前端。\n\n### 审批状态流转\n\n```mermaid\ngraph LR\n A[pending] --> B[approved]\n A --> C[denied]\n B --> D[completed]\n C --> E[failed]\n```\n\n### 状态显示组件\n\n状态徽章组件根据当前审批状态显示对应的视觉标识：\n\n```tsx\n
\n \n
\n```\n\n资料来源：[TaskToolCallContent.tsx:5-15]()\n\n## 主题与显示\n\n会话管理界面支持多种主题配置，与系统主题设置集成。状态栏显示当前连接状态和守护进程信息。\n\n### 布局组件\n\n主布局组件整合了所有会话管理的 UI 元素：\n\n- 顶部导航栏\n- 会话列表区域\n- 状态栏（连接状态、守护进程信息）\n- 调试面板入口\n\n```tsx\n
\n
\n
\n humanlayer\n
\n {connected && healthStatus === 'degraded' && (\n \n )}\n
\n
\n```\n\n资料来源：[Layout.tsx:50-70]()\n\n## 键盘快捷键\n\n会话管理界面支持丰富的键盘快捷键操作，提高用户交互效率。\n\n| 快捷键 | 功能 |\n|--------|------|\n| C | 创建新会话 |\n| ⌘/Ctrl + K | 打开命令面板 |\n| i | 展开工具结果详情 |\n| ⌘/Ctrl + ENTER | 启用遥测报告 |\n\n资料来源：[SessionsEmptyState.tsx](), [OptInTelemetryModal.tsx:25-30]()\n\n## 总结\n\nHumanLayer 的会话管理模块提供了完整的 AI 编码代理工作流协调能力。通过事件驱动的状态管理、分层的 UI 组件架构和灵活的守护进程集成，系统能够有效管理复杂的工具调用审批流程，同时保持良好的用户体验和调试能力。\n\n---\n\n\n\n## 审批工作流\n\n### 相关页面\n\n相关主题：[会话管理](#session-management), [REST API](#rest-api), [前端组件](#frontend-components)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [hld/approval/manager.go](https://github.com/humanlayer/humanlayer/blob/main/hld/approval/manager.go)\n- [hld/approval/types.go](https://github.com/humanlayer/humanlayer/blob/main/hld/approval/types.go)\n- [hld/approval/manager_test.go](https://github.com/humanlayer/humanlayer/blob/main/hld/approval/manager_test.go)\n- [hld/rpc/approval_handlers.go](https://github.com/humanlayer/humanlayer/blob/main/hld/rpc/approval_handlers.go)\n- [humanlayer-wui/src/components/Layout.tsx](https://github.com/humanlayer/humanlayer/blob/main/humanlayer-wui/src/components/Layout.tsx)\n- [humanlayer-wui/src/components/internal/SessionDetail/DangerouslySkipPermissionsDialog.tsx](https://github.com/humanlayer/humanlayer/blob/main/humanlayer-wui/src/components/internal/SessionDetail/DangerouslySkipPermissionsDialog.tsx)\n
\n\n# 审批工作流\n\nHumanLayer 的核心功能之一是**审批工作流（Approval Workflow）**，它允许用户在 AI Agent 执行敏感操作（如文件编辑、命令执行、文件写入等）之前进行人工审批或拒绝。\n\n## 概述\n\n审批工作流是 HumanLayer 架构中的关键组成部分，它在 AI Agent 的工具调用（Tool Call）和实际执行之间插入一个人工决策点。当 Claude 或其他 AI 模型尝试执行敏感工具时，系统会暂停执行，等待用户批准或拒绝。\n\n```mermaid\ngraph TD\n A[AI Agent 发起工具调用] --> B{是否需要审批?}\n B -->|是| C[创建 ApprovalRequest]\n B -->|否| Z[直接执行]\n C --> D[通过 WebSocket 推送至前端]\n D --> E[用户看到待审批列表]\n E --> F{用户决策}\n F -->|批准| G[ApprovalResult: approved]\n F -->|拒绝| H[ApprovalResult: denied]\n G --> I[通知 Agent 继续执行]\n H --> J[终止工具调用]\n I --> K[返回工具执行结果]\n J --> L[返回拒绝错误]\n```\n\n## 核心组件\n\n### 后端组件\n\n| 组件 | 文件位置 | 职责 |\n|------|----------|------|\n| ApprovalManager | `hld/approval/manager.go` | 管理所有审批请求的生命周期 |\n| ApprovalRequest | `hld/approval/types.go` | 定义审批请求的数据结构 |\n| ApprovalHandlers | `hld/rpc/approval_handlers.go` | 处理 RPC 层面的审批操作 |\n\n### 前端组件\n\n| 组件 | 文件位置 | 职责 |\n|------|----------|------|\n| Layout | `humanlayer-wui/src/components/Layout.tsx` | 显示待审批列表和状态栏 |\n| DangerouslySkipPermissionsDialog | `humanlayer-wui/src/components/internal/SessionDetail/DangerouslySkipPermissionsDialog.tsx` | 跳过权限对话框 |\n\n## 审批请求数据结构\n\n审批请求（ApprovalRequest）包含以下关键字段：\n\n```typescript\ninterface ApprovalRequest {\n id: string; // 审批请求唯一标识\n sessionId: string; // 所属会话 ID\n toolName: string; // 工具名称 (如 Bash, Edit, Write)\n toolInput: object; // 工具输入参数\n approvalStatus: 'pending' | 'approved' | 'denied';\n createdAt: Date; // 创建时间\n}\n```\n\n资料来源：[humanlayer-wui/src/components/Layout.tsx]()\n\n## 审批流程详解\n\n### 1. 工具调用拦截\n\n当 AI Agent 尝试调用工具时，HumanLayer SDK 会拦截该调用并创建一个审批请求。如果该工具被配置为需要审批，则执行会暂停。\n\n### 2. 审批请求创建\n\n```go\n// 伪代码展示审批创建逻辑\nfunc (m *ApprovalManager) CreateApproval(request ToolCallRequest) (*ApprovalRequest, error) {\n approval := &ApprovalRequest{\n ID: generateUUID(),\n SessionID: request.SessionID,\n ToolName: request.ToolName,\n ToolInput: request.ToolInput,\n ApprovalStatus: StatusPending,\n CreatedAt: time.Now(),\n }\n m.store.Save(approval)\n m.notifyFrontend(approval)\n return approval, nil\n}\n```\n\n资料来源：[hld/approval/manager.go]()\n\n### 3. 前端通知\n\n通过 WebSocket 连接，前端会收到实时通知，更新待审批列表：\n\n```typescript\n// Layout.tsx 中的审批列表渲染\n{approvals.map((approval, index) => (\n
\n
\n Tool: {approval.toolName}\n
\n
\n Session: {approval.sessionId.slice(0, 8)}\n
\n
\n Input: {JSON.stringify(approval.toolInput)}\n
\n
\n \n \n
\n
\n))}\n```\n\n资料来源：[humanlayer-wui/src/components/Layout.tsx]()\n\n### 4. 用户决策处理\n\n用户可以选择：\n\n- **批准（Approve）**：允许工具继续执行\n- **拒绝（Deny）**：阻止工具执行并返回错误\n- **跳过权限（DangerouslySkipPermissions）**：在超时时间内自动批准所有请求\n\n```typescript\n// 危险跳过权限对话框\nfunction DangerouslySkipPermissionsDialog() {\n return (\n \n \n

Use with extreme caution!

\n
    \n
  • 文件编辑和写入
    • \n
  • 运行 bash 命令
    • \n
  • 读取文件
    • \n
  • 生成子任务
    • \n
  • 所有 MCP 工具调用
    • \n
\n \n \n )\n}\n```\n\n资料来源：[humanlayer-wui/src/components/internal/SessionDetail/DangerouslySkipPermissionsDialog.tsx]()\n\n### 5. 结果反馈\n\n审批结果通过 RPC 回调返回给后端，Agent 收到结果后继续执行或终止：\n\n```go\nfunc (s *ApprovalServer) HandleApprovalResult(ctx context.Context, result *ApprovalResult) error {\n approval := s.manager.GetApproval(result.ApprovalID)\n approval.Status = result.Status\n return approval.NotifyAgent()\n}\n```\n\n资料来源：[hld/rpc/approval_handlers.go]()\n\n## 支持的工具类型\n\n审批工作流支持多种工具类型，前端会根据工具名称渲染不同的输入展示：\n\n| 工具名称 | 描述 | 特殊显示 |\n|----------|------|----------|\n| Bash | 执行 shell 命令 | 显示命令内容 |\n| Edit | 编辑文件 | 显示 diff 对比 |\n| Write | 写入文件 | 显示文件路径和内容 |\n| Read | 读取文件 | 显示文件路径 |\n| Task | 子任务代理 | 显示子代理类型和描述 |\n| MultiEdit | 批量编辑 | 显示多个 diff |\n| Grep | 搜索文件 | 显示搜索模式 |\n\n资料来源：[humanlayer-wui/src/components/internal/SessionDetail/components/ToolResultModal.tsx]()\n\n## 状态管理\n\n### 审批状态流转\n\n```mermaid\nstateDiagram-v2\n [*] --> Pending: 工具调用被拦截\n Pending --> Approved: 用户点击批准\n Pending --> Denied: 用户点击拒绝\n Approved --> [*]: 工具执行完成\n Denied --> [*]: 返回拒绝错误\n```\n\n### 会话状态集成\n\n每个会话维护自己的审批状态，前端通过 `DemoAppStore` 进行状态管理：\n\n```typescript\ninterface DemoAppState {\n sessions: Session[];\n focusedSession: Session | null;\n approvals: ApprovalRequest[]; // 当前会话的待审批列表\n connected: boolean;\n status: string;\n}\n```\n\n资料来源：[humanlayer-wui/src/stores/demo/demoAppStore.ts]()\n\n## WebSocket 实时通信\n\n审批通知通过 WebSocket 实时推送到前端：\n\n```mermaid\nsequenceDiagram\n participant Agent as AI Agent\n participant Backend as HumanLayer Backend\n participant WS as WebSocket Server\n participant Frontend as WUI Frontend\n\n Agent->>Backend: 发起工具调用\n Backend->>Backend: 创建 ApprovalRequest\n Backend->>WS: 发布审批事件\n WS->>Frontend: 推送审批通知\n Frontend->>User: 显示待审批弹窗/列表\n User->>Frontend: 批准/拒绝\n Frontend->>WS: 发送审批结果\n WS->>Backend: 转发审批结果\n Backend->>Agent: 通知执行/终止\n```\n\n## 配置选项\n\n### 工具级别配置\n\n可以为不同工具配置不同的审批策略：\n\n```typescript\n{\n \"tools\": {\n \"Bash\": { \"requireApproval\": true, \"timeout\": 60 },\n \"Write\": { \"requireApproval\": true },\n \"Read\": { \"requireApproval\": false }\n }\n}\n```\n\n### 超时设置\n\n跳过权限功能支持设置自动禁用时间：\n\n```tsx\n\n\n\n```\n\n资料来源：[humanlayer-wui/src/components/internal/SessionDetail/DangerouslySkipPermissionsDialog.tsx]()\n\n## 测试验证\n\n审批工作流包含完整的单元测试覆盖：\n\n```go\nfunc TestApprovalManager(t *testing.T) {\n // 测试创建审批请求\n // 测试批准流程\n // 测试拒绝流程\n // 测试超时机制\n // 测试并发审批\n}\n```\n\n资料来源：[hld/approval/manager_test.go]()\n\n## 安全考虑\n\n1. **敏感操作拦截**：所有文件写入、命令执行等操作默认需要审批\n2. **超时机制**：跳过权限功能支持自动超时，防止永久性权限提升\n3. **审计日志**：所有审批操作都会被记录，便于安全审计\n4. **实时通知**：用户可以及时响应审批请求，避免执行被无限期阻塞\n\n## 相关文档\n\n- [快速开始指南](../getting-started.md)\n- [工具配置参考](../configuration/tools.md)\n- [WebSocket API 参考](../api/websocket.md)\n- [CLI 参考](../cli/reference.md)\n\n---\n\n\n\n## 数据库与存储\n\n### 相关页面\n\n相关主题：[REST API](#rest-api), [会话管理](#session-management)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [packages/database/database.ts](https://github.com/humanlayer/humanlayer/blob/main/packages/database/database.ts) （未在上下文中提供，基于仓库结构推断）\n- [packages/database/schema/index.ts](https://github.com/humanlayer/humanlayer/blob/main/packages/database/schema/index.ts) （未在上下文中提供，基于仓库结构推断）\n- [packages/database/schema/thoughts.ts](https://github.com/humanlayer/humanlayer/blob/main/packages/database/schema/thoughts.ts) （未在上下文中提供，基于仓库结构推断）\n- [packages/database/schema/scores.ts](https://github.com/humanlayer/humanlayer/blob/main/packages/database/schema/scores.ts) （未在上下文中提供，基于仓库结构推断）\n- [hld/store/sqlite.go](https://github.com/humanlayer/humanlayer/blob/main/hld/store/sqlite.go) （未在上下文中提供，基于仓库结构推断）\n- [hld/store/store.go](https://github.com/humanlayer/humanlayer/blob/main/hld/store/store.go) （未在上下文中提供，基于仓库结构推断）\n\n> 注：由于这些数据库相关文件未直接出现在检索上下文中，本页面内容基于仓库整体架构和公开文档进行推断性说明。实际实现细节请参考上述源文件。\n
\n\n# 数据库与存储\n\n## 概述\n\nHumanLayer 系统的数据层采用双存储架构：\n\n- **Go 后端 (hld)**：使用 SQLite 作为本地持久化存储，运行于守护进程 (daemon) 模式\n- **TypeScript/React 前端 (packages/database)**：提供类型化的数据库访问接口，供 Web UI 使用\n\n这种架构设计使系统能够支持离线优先的操作模式，同时通过 API 与云端服务同步数据。\n\n## 存储架构\n\n```mermaid\ngraph TD\n subgraph \"客户端层\"\n WUI[humanlayer-wui
Tauri + React]\n CLI[HumanLayer CLI
Node.js]\n end\n \n subgraph \"数据库层\"\n SQLite[(SQLite
本地存储)]\n Schema[数据库 Schema]\n end\n \n subgraph \"核心实体\"\n Thoughts[Thoughts
开发者笔记]\n Scores[Scores
评分系统]\n Sessions[Sessions
会话管理]\n Approvals[Approvals
审批记录]\n end\n \n WUI --> SQLite\n CLI --> SQLite\n SQLite --> Schema\n Schema --> Thoughts\n Schema --> Scores\n Schema --> Sessions\n Schema --> Approvals\n```\n\n## 守护进程数据库管理\n\n### Daemon 数据库隔离\n\nhumanlayer-wui 应用在启动时会自动管理 daemon 进程的生命周期。每个 git 分支拥有独立的数据库实例，确保开发环境的隔离性。\n\n| 环境变量 | 说明 | 默认值 |\n|---------|------|--------|\n| `HUMANLAYER_WUI_AUTOLAUNCH_DAEMON` | 禁用自动启动 daemon | `true` |\n| `HUMANLAYER_DAEMON_HTTP_PORT` | 外部 daemon 连接端口 | 自动分配 |\n| `HUMANLAYER_API_KEY` | API 认证密钥 | - |\n\n数据库文件命名规则：`daemon-{branch}.db`，从 `daemon-dev.db` 复制初始化。\n\n资料来源：[humanlayer-wui/README.md:28-35]()\n\n### 数据库文件位置\n\n运行时日志和数据库文件的位置可通过设置界面查看：\n\n```typescript\n// 路径显示逻辑\nconst logPath = await window.logPath; // 获取日志路径\n```\n\n资料来源：[humanlayer-wui/src/components/SettingsDialog.tsx:1-100]()（基于组件推断）\n\n## 核心数据模型\n\n### Sessions（会话）\n\nSessions 表存储 AI 与人类交互的完整会话记录：\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `id` | UUID | 会话唯一标识 |\n| `created_at` | TIMESTAMP | 创建时间 |\n| `status` | ENUM | `active`, `completed`, `failed` |\n| `metadata` | JSON | 附加元数据 |\n\n### Approvals（审批）\n\n存储人类对 AI 操作请求的审批决策：\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `approval_id` | UUID | 审批请求 ID |\n| `status` | ENUM | `pending`, `approved`, `denied`, `timeout` |\n| `tool_name` | VARCHAR | 请求的工具名称 |\n| `tool_input_json` | TEXT | 工具输入参数 |\n| `tool_result_content` | TEXT | 工具执行结果 |\n| `created_at` | TIMESTAMP | 创建时间 |\n| `completed_at` | TIMESTAMP | 完成时间 |\n\n资料来源：[humanlayer-wui/src/components/internal/SessionDetail/components/ToolResultModal.tsx:1-100]()（基于 ToolResultModal 组件中 approvalId 和 approvalStatus 的使用推断）\n\n### Thoughts（开发者笔记）\n\nThoughts 模块允许开发者将笔记与代码仓库分离存储，便于 AI 助手访问但不影响代码仓库历史：\n\n```bash\n# 初始化 thoughts\nhumanlayer thoughts init\n\n# 手动同步\nhumanlayer thoughts sync -m \"更新架构笔记\"\n\n# 检查状态\nhumanlayer thoughts status\n```\n\n**多配置文件支持**：\n- 每个 profile 可配置独立的 thoughts 仓库路径\n- 支持全局目录和按仓库目录的混合配置\n- 自动根据当前仓库解析对应的 profile\n\n### Scores（评分系统）\n\nScores 表用于存储 AI 操作的评分数据，支持性能监控和质量评估。\n\n## 会话事件流\n\n```mermaid\nsequenceDiagram\n participant AI as AI Agent\n participant HL as HumanLayer\n participant DB as SQLite\n participant UI as Web UI\n participant Human as Human\n \n AI->>HL: 发起工具调用请求\n HL->>DB: 存储 approval record\n HL->>UI: 推送 pending 状态\n UI->>Human: 显示审批弹窗\n Human->>UI: 批准/拒绝\n UI->>DB: 更新审批状态\n DB-->>AI: 返回审批结果\n AI->>HL: 执行操作\n HL->>DB: 存储 tool_result\n```\n\n## 工具调用的特殊渲染存储\n\nToolResultModal 组件根据工具类型采用不同的渲染策略，相关数据存储格式如下：\n\n| 工具类型 | 存储字段 | 渲染特点 |\n|---------|---------|---------|\n| `Task` | `prompt`, `subagent_type`, `description` | 显示子代理类型和提示词 |\n| `Write` | `file_path`, `content` | 显示文件路径和内容 |\n| `Edit` | `file_path`, `old_string`, `new_string` | 使用 DiffViewer 显示差异 |\n| `MultiEdit` | `edits[]` | 批量差异对比 |\n| `Bash` | `command` | 显示命令内容 |\n| `Grep` | `pattern`, `path`, `output_mode` | 显示搜索参数 |\n\n资料来源：[humanlayer-wui/src/components/internal/SessionDetail/components/ToolResultModal.tsx:1-100]()\n\n## 协作文档存储\n\n`apps/react` 中的协作编辑器使用独立的文档存储服务：\n\n| 配置项 | 说明 |\n|-------|------|\n| `electricUrl` | Electric SQL 代理地址 |\n| `documentId` | 文档唯一标识 |\n\n编辑器采用 Y.js 作为 CRDT 引擎，支持多人实时协作编辑。\n\n## 数据同步与离线支持\n\n### 离线优先设计\n\nHumanLayer 设计为离线优先应用：\n\n1. 所有操作首先写入本地 SQLite\n2. 后台任务尝试同步到云端\n3. 冲突时保留本地数据，等待网络恢复后重试\n\n### 遥测数据\n\n系统收集匿名性能和使用数据（需用户明确授权），**绝不收集**：\n\n- 提示词或对话内容\n- 代码内容或文件路径\n- API 密钥或个人信息\n- 工作目录名称\n\n资料来源：[humanlayer-wui/src/components/OptInTelemetryModal.tsx:1-100]()\n\n## 配置管理\n\n### 配置文件优先级\n\n```bash\n# 1. 命令行参数（最高优先级）\nhumanlayer contact_human -m \"msg\" --slack-channel \"C08G5C3V552\"\n\n# 2. 环境变量\nexport HUMANLAYER_SLACK_CHANNEL=C08G5C3V552\n\n# 3. 配置文件（.hlyr.json）\necho '{\"channel\":{\"slack\":{\"channel_or_user_id\":\"C08G5C3V552\"}}}' > .hlyr.json\n```\n\n### Thoughts Profile 配置\n\n```bash\n# 创建新的 profile\nhumanlayer thoughts profile create personal --repo ~/thoughts-personal\n\n# 列出所有 profiles\nhumanlayer thoughts profile list --json\n\n# 查看 profile 详情\nhumanlayer thoughts profile show --json\n```\n\n## 最佳实践\n\n### 开发环境\n\n- 每个 git 分支使用独立的数据库实例\n- 使用 `daemon-{branch}.db` 命名避免冲突\n- 通过 debug panel 手动控制 daemon 生命周期\n\n### 生产环境\n\n- 使用外部 daemon 实例集中管理\n- 通过 `HUMANLAYER_DAEMON_HTTP_PORT` 指定连接端口\n- 定期备份 SQLite 数据库文件\n\n### Thoughts 管理\n\n- 将 thoughts 仓库放在代码仓库外部\n- 使用 profiles 功能分离个人和工作笔记\n- 定期 `sync` 确保笔记可被 AI 助手搜索\n\n---\n\n\n\n## REST API\n\n### 相关页面\n\n相关主题：[系统架构](#system-architecture), [数据库与存储](#database-storage)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [hld/api/openapi.yaml](https://github.com/humanlayer/humanlayer/blob/main/hld/api/openapi.yaml)\n- [hld/sdk/typescript/src/generated/runtime.ts](https://github.com/humanlayer/humanlayer/blob/main/hld/sdk/typescript/src/generated/runtime.ts)\n- [hld/sdk/typescript/src/generated/apis/SessionsApi.ts](https://github.com/humanlayer/humanlayer/blob/main/hld/sdk/typescript/src/generated/apis/SessionsApi.ts)\n- [hld/sdk/typescript/src/generated/apis/ApprovalsApi.ts](https://github.com/humanlayer/humanlayer/blob/main/hld/sdk/typescript/src/generated/apis/ApprovalsApi.ts)\n- [hld/sdk/typescript/src/generated/apis/FilesApi.ts](https://github.com/humanlayer/humanlayer/blob/main/hld/sdk/typescript/src/generated/apis/FilesApi.ts)\n- [hld/sdk/typescript/src/generated/apis/SettingsApi.ts](https://github.com/humanlayer/humanlayer/blob/main/hld/sdk/typescript/src/generated/apis/SettingsApi.ts)\n- [hld/sdk/typescript/src/generated/models/Agent.ts](https://github.com/humanlayer/humanlayer/blob/main/hld/sdk/typescript/src/generated/models/Agent.ts)\n
\n\n# REST API\n\n## 概述\n\nHumanLayer 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)\n\n## 基础配置\n\n### 服务地址\n\nHLD 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)\n\n### 认证机制\n\nAPI 采用 Bearer Token 认证方案，在请求头中通过 `Authorization: Bearer ` 格式传递认证令牌。OpenAPI 规范中定义了 `bearerAuth` 安全方案。 资料来源：[apps/daemon/src/swagger.ts](https://github.com/humanlayer/humanlayer/blob/main/apps/daemon/src/swagger.ts)\n\n## 核心模块\n\n### 会话管理 (Sessions)\n\nSessions API 负责管理 AI 代理的工作会话，支持创建、查询、列表和删除操作。\n\n| 操作 | 方法 | 端点 | 说明 |\n|------|------|------|------|\n| 创建会话 | POST | `/sessions` | 创建新的工作会话 |\n| 列出会话 | GET | `/sessions` | 获取会话列表，支持 leafOnly 过滤 |\n| 获取会话 | GET | `/sessions/{sessionId}` | 获取指定会话详情 |\n| 删除会话 | DELETE | `/sessions/{sessionId}` | 删除指定会话 |\n| 订阅事件 | GET | `/sessions/{sessionId}/events/stream` | SSE 实时事件流 |\n\n创建会话时需要提供以下参数：\n\n- `query`: 会话查询内容\n- `model`: 使用的 AI 模型 (如 claude-3.5-sonnet)\n- `workingDir`: 工作目录路径\n\n资料来源：[hld/sdk/typescript/src/generated/apis/SessionsApi.ts](https://github.com/humanlayer/humanlayer/blob/main/hld/sdk/typescript/src/generated/apis/SessionsApi.ts)\n\n### 审批工作流 (Approvals)\n\nApprovals API 提供人机协作审批功能，允许 AI 代理在执行敏感操作前请求人工确认。\n\n| 操作 | 方法 | 端点 | 说明 |\n|------|------|------|------|\n| 请求审批 | POST | `/approvals/request` | 创建新的审批请求 |\n| 审批操作 | POST | `/approvals/{approvalId}/approve` | 批准指定审批 |\n| 拒绝操作 | POST | `/approvals/{approvalId}/reject` | 拒绝指定审批 |\n| 获取详情 | GET | `/approvals/{approvalId}` | 获取审批详情 |\n| 列出审批 | GET | `/approvals` | 获取审批列表 |\n\n审批请求包含以下状态：\n\n- `pending`: 待处理\n- `approved`: 已批准\n- `rejected`: 已拒绝\n- `expired`: 已过期\n\n资料来源：[hld/sdk/typescript/src/generated/apis/ApprovalsApi.ts](https://github.com/humanlayer/humanlayer/blob/main/hld/sdk/typescript/src/generated/apis/ApprovalsApi.ts)\n\n### 文件操作 (Files)\n\nFiles API 提供文件搜索和管理功能，支持模糊搜索、目录创建和验证等操作。\n\n| 操作 | 方法 | 端点 | 说明 |\n|------|------|------|------|\n| 模糊搜索 | POST | `/files/fuzzy-search` | 基于模式匹配搜索文件 |\n| 创建目录 | POST | `/files/directory` | 创建新目录 |\n| 验证目录 | POST | `/files/validate-directory` | 验证目录有效性 |\n\n模糊搜索请求参数：\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| query | string | 是 | 搜索模式 |\n| paths | string[] | 是 | 搜索路径列表 |\n| limit | number | 否 | 最大返回数量 |\n| filesOnly | boolean | 否 | 仅返回文件，排除目录 |\n| respectGitignore | boolean | 否 | 忽略 .gitignore 匹配的文件 |\n\n资料来源：[hld/sdk/typescript/src/generated/apis/FilesApi.ts](https://github.com/humanlayer/humanlayer/blob/main/hld/sdk/typescript/src/generated/apis/FilesApi.ts)\n\n### 系统设置 (Settings)\n\nSettings API 用于管理 Daemon 配置和用户偏好设置。\n\n| 操作 | 方法 | 端点 | 说明 |\n|------|------|------|------|\n| 获取配置 | GET | `/settings/config` | 获取当前 Daemon 配置 |\n| 更新设置 | PUT | `/settings/user` | 更新用户偏好设置 |\n| 更新配置 | PUT | `/settings/config` | 更新 Daemon 配置 |\n\n配置响应包含 Claude 二进制文件路径等系统信息。 资料来源：[hld/sdk/typescript/src/generated/apis/SettingsApi.ts](https://github.com/humanlayer/humanlayer/blob/main/hld/sdk/typescript/src/generated/apis/SettingsApi.ts)\n\n### 代理管理 (Agents)\n\nAgents API 提供 AI 代理的查询和管理功能，支持从本地或全局目录获取代理定义。\n\n代理数据模型：\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| name | string | YAML frontmatter 中的代理名称 |\n| mentionText | string | @mention 使用的文本 |\n| source | enum | 代理来源：local 或 global |\n| description | string | YAML frontmatter 中的描述（可选） |\n\n资料来源：[hld/sdk/typescript/src/generated/models/Agent.ts](https://github.com/humanlayer/humanlayer/blob/main/hld/sdk/typescript/src/generated/models/Agent.ts)\n\n## 实时事件流 (SSE)\n\nHumanLayer API 支持 Server-Sent Events (SSE) 技术实现实时事件推送，客户端可以订阅会话事件并接收即时更新。\n\n### 事件类型\n\n系统支持多种事件类型，包括工具调用、审批状态变更、会话完成等。每个事件包含：\n\n- `eventType`: 事件类型标识\n- `sessionId`: 关联的会话 ID\n- `approvalId`: 关联的审批 ID（如适用）\n- `toolName`: 工具名称（如 Bash、Edit、Write、Grep 等）\n- `createdAt`: 事件创建时间戳\n- `isCompleted`: 操作是否已完成\n\n### 连接方式\n\n```typescript\nconst unsubscribe = await client.subscribeToEvents(\n { sessionId: sessionId },\n {\n onMessage: (event) => console.log('收到事件:', event),\n onError: (error) => console.error('连接错误:', error)\n }\n);\n```\n\n资料来源：[hld/sdk/typescript/README.md](https://github.com/humanlayer/humanlayer/blob/main/hld/sdk/typescript/README.md)\n\n## 架构流程图\n\n### 会话处理流程\n\n```mermaid\ngraph TD\n A[客户端] --> B[创建会话]\n B --> C[获取 Session ID]\n C --> D[订阅 SSE 事件流]\n D --> E{执行工具调用}\n E -->|需要审批| F[请求审批]\n F --> G[等待人工确认]\n G -->|批准| H[执行操作]\n G -->|拒绝| I[记录拒绝状态]\n H --> J[返回结果]\n I --> K[结束流程]\n J --> L[会话完成]\n E -->|无需审批| H\n```\n\n### 审批工作流\n\n```mermaid\ngraph LR\n A[AI 代理] -->|敏感操作| B[创建审批请求]\n B --> C[存储待审批状态]\n C --> D[通知人工审批者]\n D --> E{审批决定}\n E -->|approve| F[执行原操作]\n E -->|reject| G[阻止操作]\n E -->|超时| H[标记过期]\n F --> I[返回结果给 AI]\n G --> J[返回拒绝给 AI]\n```\n\n## TypeScript SDK\n\n### 安装与构建\n\n```bash\ncd hld/sdk/typescript\nbun install\nbun run generate # 从 OpenAPI 规范生成客户端代码\nbun run build # 构建 TypeScript 到 JavaScript\n```\n\n### 初始化客户端\n\n```typescript\nimport { HLDClient } from '@humanlayer/hld-sdk';\n\nconst client = new HLDClient({\n port: 7777 // 默认 HLD REST API 端口\n});\n```\n\n### 完整使用示例\n\n```typescript\n// 1. 创建新会话\nconst session = await client.createSession({\n query: \"帮我修复一个 bug\",\n model: \"claude-3.5-sonnet\",\n workingDir: \"/path/to/project\"\n});\n\n// 2. 列出所有会话\nconst sessions = await client.listSessions({ leafOnly: true });\n\n// 3. 订阅实时事件\nconst unsubscribe = await client.subscribeToEvents(\n { sessionId: session.sessionId },\n {\n onMessage: (event) => {\n if (event.eventType === 'tool_call') {\n console.log(`工具调用: ${event.toolName}`);\n }\n },\n onError: (error) => console.error('SSE 错误:', error)\n }\n);\n\n// 4. 请求审批\nconst approval = await client.requestApproval({\n sessionId: session.sessionId,\n toolName: 'Bash',\n toolInput: { command: 'rm -rf /important' }\n});\n\n// 5. 批准或拒绝审批\nawait client.approveApproval({ approvalId: approval.approvalId });\n// 或 await client.rejectApproval({ approvalId: approval.approvalId });\n```\n\n资料来源：[hld/sdk/typescript/README.md](https://github.com/humanlayer/humanlayer/blob/main/hld/sdk/typescript/README.md)\n\n## API 端点总览\n\n```mermaid\ngraph TD\n subgraph \"HLD REST API - /api/v1\"\n subgraph \"Sessions\"\n S1[POST /sessions]\n S2[GET /sessions]\n S3[GET /sessions/:id]\n S4[DELETE /sessions/:id]\n S5[GET /sessions/:id/events/stream]\n end\n \n subgraph \"Approvals\"\n A1[POST /approvals/request]\n A2[GET /approvals]\n A3[GET /approvals/:id]\n A4[POST /approvals/:id/approve]\n A5[POST /approvals/:id/reject]\n end\n \n subgraph \"Files\"\n F1[POST /files/fuzzy-search]\n F2[POST /files/directory]\n F3[POST /files/validate-directory]\n end\n \n subgraph \"Settings\"\n G1[GET /settings/config]\n G2[PUT /settings/config]\n G3[PUT /settings/user]\n end\n \n subgraph \"Agents\"\n AG1[GET /agents]\n AG2[GET /agents/:name]\n end\n end\n```\n\n## 错误处理\n\nAPI 返回标准化的错误响应格式：\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| code | string | 错误代码 |\n| message | string | 错误描述信息 |\n| details | object | 额外的错误详情（可选） |\n\n所有 API 调用应正确处理网络错误、超时情况和服务器错误响应。SDK 客户端在 SSE 连接中断时会自动尝试重新连接，确保事件的持续接收。\n\n---\n\n\n\n## 前端组件\n\n### 相关页面\n\n相关主题：[桌面应用](#desktop-app), [REST API](#rest-api)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [humanlayer-wui/src/components/OptInTelemetryModal.tsx](https://github.com/humanlayer/humanlayer/blob/main/humanlayer-wui/src/components/OptInTelemetryModal.tsx)\n- [humanlayer-wui/src/components/Layout.tsx](https://github.com/humanlayer/humanlayer/blob/main/humanlayer-wui/src/components/Layout.tsx)\n- [humanlayer-wui/src/components/SettingsDialog.tsx](https://github.com/humanlayer/humanlayer/blob/main/humanlayer-wui/src/components/SettingsDialog.tsx)\n- [humanlayer-wui/src/components/DebugPanel.tsx](https://github.com/humanlayer/humanlayer/blob/main/humanlayer-wui/src/components/DebugPanel.tsx)\n- [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)\n- [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)\n- [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)\n- [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)\n- [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)\n- [humanlayer-wui/src/components/QuickLauncherDirectoryInput.tsx](https://github.com/humanlayer/humanlayer/blob/main/humanlayer-wui/src/components/QuickLauncherDirectoryInput.tsx)\n
\n\n# 前端组件\n\nHumanLayer WUI（Web User Interface）是人类层 SDK 的前端管理界面，采用 React + TypeScript 技术栈构建，提供了 AI 会话管理、工具调用审批、性能监控等核心功能。该模块位于仓库的 `humanlayer-wui/` 目录下，采用组件化架构组织代码。\n\n## 组件架构概览\n\nHumanLayer WUI 的前端组件采用分层架构设计，从顶层到底层依次为：布局层（Layout）、视图层（SessionDetail）、交互层（Dialog、CommandPalette）以及内容渲染层（EventContent）。\n\n```mermaid\ngraph TD\n A[Layout 布局层] --> B[SessionDetail 会话详情]\n A --> C[SettingsDialog 设置对话框]\n A --> D[DebugPanel 调试面板]\n B --> E[ConversationStream 对话流]\n B --> F[ForkViewModal 分叉视图]\n B --> G[ToolResultModal 工具结果]\n E --> H[EventContent 事件内容渲染]\n H --> I[EditToolCallContent]\n H --> J[MultiEditToolCallContent]\n H --> K[TaskToolCallContent]\n```\n\n## 核心组件说明\n\n### 布局组件（Layout）\n\nLayout 组件是整个应用的主容器，负责全局布局和状态栏管理。该组件处理与后端服务的连接状态显示，并在状态栏中展示关键信息。\n\n**主要功能：**\n\n- 全局布局结构定义\n- 连接状态监控与显示\n- 健康状态指示器（healthStatus）\n- 调试信息展示（DEV 模式）\n- 错误状态恢复按钮\n\n**连接状态管理逻辑：**\n\n| 状态 | 显示内容 | 触发条件 |\n|------|----------|----------|\n| `connected` + `healthy` | 正常状态 | 服务健康运行 |\n| `connected` + `degraded` | 警告按钮 | 服务降级 |\n| `!connected` + `!connecting` | 重试按钮 | 连接失败 |\n\n资料来源：[humanlayer-wui/src/components/Layout.tsx]()\n\n### 会话详情组件（SessionDetail）\n\nSessionDetail 是管理单个 AI 会话的核心视图组件，负责渲染会话中的所有事件流和交互元素。\n\n**主要子组件：**\n\n| 组件 | 功能 | 路径 |\n|------|------|------|\n| ToolResultModal | 工具调用结果详情弹窗 | components/internal/SessionDetail/components/ |\n| ForkViewModal | 会话分叉选择视图 | components/internal/SessionDetail/components/ |\n| ConversationStream | 对话事件流渲染 | components/internal/ConversationStream/ |\n\n资料来源：[humanlayer-wui/src/components/internal/SessionDetail/index.tsx]()\n\n### 工具调用内容渲染\n\nEventContent 目录下的组件负责渲染不同类型工具调用的显示内容，包括 Edit、MultiEdit、Task、Grep、BashOutput 等工具的专用视图。\n\n#### EditToolCallContent\n\n用于渲染文件编辑操作的组件，支持 diff 视图展示变更内容。\n\n**核心属性：**\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| `toolInputJson` | string | 工具输入的 JSON 序列化的参数 |\n| `isCompleted` | boolean | 操作是否完成 |\n| `toolResultContent` | string | 工具执行结果内容 |\n| `isFocused` | boolean | 是否获得焦点 |\n\n**功能特性：**\n\n- 解析 old_string 和 new_string 参数\n- 使用 CustomDiffViewer 组件渲染 diff 视图\n- 支持折叠/展开模式切换\n- 显示编辑成功或错误状态\n\n资料来源：[humanlayer-wui/src/components/internal/ConversationStream/EventContent/EditToolCallContent.tsx]()\n\n#### MultiEditToolCallContent\n\n用于渲染多文件编辑操作的组件，支持批量文件变更展示。\n\n**核心功能：**\n\n- 支持 split/unified 两种 diff 视图模式\n- 使用 DiffViewer 组件渲染变更\n- 显示编辑数量统计\n- 支持 fileSnapshot 快照模式\n\n```typescript\n// 核心渲染逻辑\n\n```\n\n资料来源：[humanlayer-wui/src/components/internal/ConversationStream/EventContent/MultiEditToolCallContent.tsx]()\n\n#### TaskToolCallContent\n\n用于渲染子任务（Task tool）调用的组件，展示子代理的执行状态。\n\n**渲染参数：**\n\n| 参数 | 说明 |\n|------|------|\n| `subagent_type` | 子代理类型名称 |\n| `description` | 任务描述 |\n| `prompt` | 执行提示词 |\n\n**状态展示：**\n\n- 未完成时显示 prompt 前 100 字符预览\n- 使用 StatusBadge 组件显示审批状态\n- 完成后显示结果预览\n- 聚焦时提示按 Enter 查看完整结果\n\n资料来源：[humanlayer-wui/src/components/internal/ConversationStream/EventContent/TaskToolCallContent.tsx]()\n\n### 工具结果弹窗（ToolResultModal）\n\nToolResultModal 是一个模态对话框组件，用于展示工具调用的完整输入和输出信息。\n\n**工具类型专用渲染：**\n\n| 工具类型 | 渲染内容 |\n|----------|----------|\n| Write | file_path + content |\n| Edit | file_path + CustomDiffViewer |\n| MultiEdit | 批量编辑的 diff 视图 |\n| Bash | 命令输出 |\n| Grep | 搜索结果 |\n| Task | 子代理信息 |\n| Read | 文件内容 |\n| WebSearch | 搜索结果 |\n\n**键盘快捷键支持：**\n\n| 快捷键 | 功能 |\n|--------|------|\n| `j` / `↓` | 向下滚动 |\n| `k` / `↑` | 向上滚动 |\n| `i` / `ESC` | 关闭弹窗 |\n\n资料来源：[humanlayer-wui/src/components/internal/SessionDetail/components/ToolResultModal.tsx]()\n\n### 分叉视图弹窗（FrokViewModal）\n\nForkViewModal 组件允许用户选择会话中的特定消息节点创建新的会话分叉。\n\n**用户交互流程：**\n\n1. 显示所有用户消息索引列表\n2. 高亮当前选中位置\n3. 支持键盘导航（上下箭头）\n4. 点击或 Enter 键确认选择\n5. 触发分叉操作\n\n**消息预览格式：**\n\n```typescript\nconst preview = event.content?.split('\\n')[0]?.substring(0, 80) + '...'\n```\n\n资料来源：[humanlayer-wui/src/components/internal/SessionDetail/components/ForkViewModal.tsx]()\n\n## 对话流组件（ConversationStream）\n\nConversationStream 组件负责渲染会话中的事件列表，支持滚动、焦点管理和事件展开功能。\n\n```mermaid\ngraph LR\n A[ConversationEvent] --> B[tool_call]\n A --> C[tool_result]\n A --> D[message]\n B --> E[EditToolCallContent]\n B --> F[MultiEditToolCallContent]\n B --> G[TaskToolCallContent]\n C --> H[ToolResultDisplay]\n D --> I[MessageContent]\n```\n\n**事件类型支持：**\n\n| eventType | 说明 |\n|-----------|------|\n| `tool_call` | 工具调用事件 |\n| `tool_result` | 工具结果事件 |\n| `message` | 消息事件 |\n\n**交互状态管理：**\n\n- `isFocused`：当前事件是否获得焦点\n- `isLast`：是否为最后一个事件\n- `responseEditorIsFocused`：响应编辑器是否获得焦点\n- `shouldIgnoreMouseEvent`：是否忽略鼠标事件\n\n资料来源：[humanlayer-wui/src/components/internal/ConversationStream/ConversationStream.tsx]()\n\n## 配置与设置组件\n\n### 设置对话框（SettingsDialog）\n\nSettingsDialog 提供用户配置界面，包括连接配置和遥测选项管理。\n\n**主要配置项：**\n\n| 配置项 | 类型 | 说明 |\n|--------|------|------|\n| Claude Code 路径 | string | 本地 Claude Code 可执行文件路径 |\n| 遥测开关 | boolean | 是否启用性能与错误报告 |\n| 日志路径 | string | 日志文件存储位置 |\n\n**遥测数据收集范围：**\n\n收集项目：\n\n- JavaScript 错误和崩溃报告\n- 性能指标（加载时间、内存使用）\n- 应用启动事件\n- 会话使用元数据\n- 导航元数据\n\n从不收集：\n\n- 用户提示词或对话内容\n- 代码内容或文件路径\n- API 密钥或个人信息\n- 工作目录名称\n\n资料来源：[humanlayer-wui/src/components/SettingsDialog.tsx]()\n资料来源：[humanlayer-wui/src/components/OptInTelemetryModal.tsx]()\n\n### 调试面板（DebugPanel）\n\nDebugPanel 提供详细的调试信息显示，用于开发阶段的故障排除。\n\n**显示信息：**\n\n| 指标 | 说明 |\n|------|------|\n| 会话数（sessions） | 当前会话总数 |\n| 审批数（approvals） | 待处理审批数量 |\n| 事件数（events） | 会话事件总数 |\n| CLI 命令 | 执行的命令行 |\n| 表计数 | 数据库表数量 |\n\n资料来源：[humanlayer-wui/src/components/DebugPanel.tsx]()\n\n## 命令面板组件\n\n### QuickLauncherDirectoryInput\n\nQuickLauncherDirectoryInput 组件提供目录路径输入功能，支持模糊搜索和自动补全。\n\n**核心功能：**\n\n- 基于 Popover 的命令列表\n- 文件路径模糊匹配\n- 高亮匹配片段\n- 键盘导航支持\n\n**组件结构：**\n\n```\nPopover → Command → CommandList → CommandItem[]\n```\n\n资料来源：[humanlayer-wui/src/components/QuickLauncherDirectoryInput.tsx]()\n\n## 状态管理\n\nHumanLayer WUI 使用 React hooks 进行状态管理，主要通过以下方式进行状态共享：\n\n### 全局状态\n\n| Hook/Store | 用途 |\n|------------|------|\n| AppStore | 全局应用状态 |\n| useConversation | 对话相关状态和操作 |\n| userSettings | 用户配置设置 |\n\n### 状态流转图\n\n```mermaid\nstateDiagram-v2\n [*] --> Connected: 连接成功\n Connected --> Degraded: 服务降级\n Degraded --> Connected: 恢复\n Connected --> Disconnected: 连接失败\n Disconnected --> Connected: 重试成功\n Degraded --> Disconnected: 完全失败\n```\n\n## 组件通信模式\n\n### 父子组件通信\n\n| 模式 | 示例 |\n|------|------|\n| Props 传递 | ToolResultModal 接收 event prop |\n| 回调函数 | onCheckedChange 通知状态变更 |\n| Ref 引用 | timeoutInputRef 获取 DOM 元素 |\n\n### 跨层级通信\n\n| 方式 | 组件 | 用途 |\n|------|------|------|\n| Dialog 弹窗 | ToolResultModal | 显示详情信息 |\n| 快捷键边界 | HotkeyScopeBoundary | 键盘事件作用域 |\n\n## 快捷键系统\n\nHumanLayer WUI 实现了一套快捷键系统，通过 HotkeyScopeBoundary 组件管理快捷键作用域。\n\n| 快捷键 | 作用域 | 功能 |\n|--------|--------|------|\n| `⌘/Ctrl + ENTER` | OptInTelemetryModal | 确认启用遥测 |\n| `i` / `ESC` | ToolResultModal | 关闭弹窗 |\n| `j/k` / `↓/↑` | ConversationStream | 事件导航 |\n| 方向键 | ForkViewModal | 消息选择 |\n\n## 技术栈\n\n| 技术 | 用途 |\n|------|------|\n| React 18 | UI 框架 |\n| TypeScript | 类型系统 |\n| Tailwind CSS | 样式框架 |\n| Radix UI | 无障碍组件库 |\n| Lucide React | 图标库 |\n| Zod | 数据验证 |\n\n## 总结\n\nHumanLayer WUI 的前端组件系统采用模块化设计，通过清晰的组件层级和职责划分，实现了 AI 会话管理的核心功能。组件系统支持多种工具调用的渲染，通过专用的 EventContent 组件提供差异化的用户体验。状态管理和通信模式确保了应用的可维护性和可扩展性。\n\n---\n\n\n\n## 桌面应用\n\n### 相关页面\n\n相关主题：[前端组件](#frontend-components)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [humanlayer-wui/src-tauri/tauri.conf.json](https://github.com/humanlayer/humanlayer/blob/main/humanlayer-wui/src-tauri/tauri.conf.json)\n- [humanlayer-wui/src-tauri/src/main.rs](https://github.com/humanlayer/humanlayer/blob/main/humanlayer-wui/src-tauri/src/main.rs)\n- [humanlayer-wui/src-tauri/src/lib.rs](https://github.com/humanlayer/humanlayer/blob/main/humanlayer-wui/src-tauri/src/lib.rs)\n- [humanlayer-wui/src-tauri/src/daemon.rs](https://github.com/humanlayer/humanlayer/blob/main/humanlayer-wui/src-tauri/src/daemon.rs)\n- [humanlayer-wui/src/components/DebugPanel.tsx](https://github.com/humanlayer/humanlayer/blob/main/humanlayer-wui/src/components/DebugPanel.tsx)\n- [humanlayer-wui/src/components/SettingsDialog.tsx](https://github.com/humanlayer/humanlayer/blob/main/humanlayer-wui/src/components/SettingsDialog.tsx)\n- [humanlayer-wui/src/components/Layout.tsx](https://github.com/humanlayer/humanlayer/blob/main/humanlayer-wui/src/components/Layout.tsx)\n\n
\n\n# 桌面应用\n\nHumanLayer 提供基于 Tauri 框架构建的跨平台桌面应用程序（WUI - Web User Interface），将 Web 前端界面与本地系统能力深度集成。该桌面应用不仅承载用户交互界面，还负责管理后台守护进程的生命周期、Claude CLI 配置以及系统级功能调用。\n\n## 技术架构概述\n\nHumanLayer 桌面应用采用现代化的混合架构设计，前端使用 React + TypeScript 构建响应式 Web 界面，后端通过 Rust 原生代码处理系统级操作。Tauri 作为桥接层，实现了前端与后端之间的高效通信。\n\n```mermaid\ngraph TD\n subgraph 前端层[\"前端层 (React + TypeScript)\"]\n A[Web UI 组件] --> B[Tauri IPC 调用]\n end\n \n subgraph Tauri层[\"Tauri 桥接层\"]\n B --> C[Rust 命令处理]\n C --> D[系统 API]\n end\n \n subgraph 后端服务[\"后端服务\"]\n E[Daemon 守护进程] --> F[Claude CLI 集成]\n E --> G[Approval 审批管理]\n end\n \n C --> E\n```\n\n## 核心配置文件\n\n### tauri.conf.json\n\n`tauri.conf.json` 是 Tauri 应用程序的核心配置文件，定义了应用的基本属性、窗口配置、构建选项以及权限声明。\n\n```json\n{\n \"productName\": \"humanlayer\",\n \"version\": \"0.x.x\",\n \"identifier\": \"com.humanlayer.humanlayer\",\n \"build\": {\n \"frontendDist\": \"../dist\",\n \"devUrl\": \"http://localhost:5173\",\n \"beforeDevCommand\": \"pnpm dev\",\n \"beforeBuildCommand\": \"pnpm build\"\n },\n \"app\": {\n \"windows\": [\n {\n \"title\": \"HumanLayer\",\n \"width\": 1200,\n \"height\": 800,\n \"minWidth\": 800,\n \"minHeight\": 600,\n \"resizable\": true,\n \"fullscreen\": false,\n \"decorations\": true\n }\n ],\n \"security\": {\n \"csp\": \"default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'\"\n }\n }\n}\n```\n\n配置文件中的关键参数说明：\n\n| 配置项 | 说明 | 默认值 |\n|--------|------|--------|\n| `productName` | 应用产品名称 | humanlayer |\n| `frontendDist` | 前端构建产物目录 | ../dist |\n| `devUrl` | 开发模式前端服务器地址 | http://localhost:5173 |\n| `window.width` | 窗口默认宽度 | 1200px |\n| `window.height` | 窗口默认高度 | 800px |\n| `window.minWidth` | 窗口最小宽度 | 800px |\n| `window.minHeight` | 窗口最小高度 | 600px |\n\n## 守护进程管理\n\nHumanLayer 桌面应用内置守护进程管理功能，支持两种运行模式：托管模式（Managed）和外部连接模式。\n\n```mermaid\nstateDiagram-v2\n [*] --> 未连接: 启动应用\n 未连接 --> 连接中: 发起连接\n 连接中 --> 已连接: 连接成功\n 连接中 --> 未连接: 连接失败\n 已连接 --> 健康: Daemon 运行正常\n 已连接 --> 降级: Daemon 运行异常\n 降级 --> 已连接: 重新连接\n 健康 --> 降级: 检测到问题\n 已连接 --> 未连接: 断开连接\n 降级 --> [*]: 关闭应用\n 健康 --> [*]: 关闭应用\n```\n\n### 守护进程连接管理\n\nDebugPanel 组件提供了守护进程连接状态的监控和诊断功能：\n\n```typescript\ninterface DaemonInfo {\n port: number; // 守护进程监听端口\n branch_id: string; // 分支标识符\n version: string; // 守护进程版本\n}\n```\n\n连接状态管理包括以下状态：\n\n| 状态 | 说明 | 用户可操作 |\n|------|------|-----------|\n| `connected` | 已连接到守护进程 | 查看状态、重启守护进程 |\n| `connecting` | 正在建立连接 | 等待连接完成 |\n| `disconnected` | 连接已断开 | 重新连接、切换守护进程类型 |\n| `degraded` | 守护进程运行异常 | 配置设置、重启守护进程 |\n\n### 托管模式与外部模式\n\n守护进程支持两种运行模式：\n\n**托管模式（Managed）**\n\n- 桌面应用自动启动和管理守护进程\n- 提供重启守护进程的功能按钮\n- 适合大多数用户场景\n\n**外部模式（External）**\n\n- 连接到自己部署的守护进程\n- 支持自定义 URL 和端口配置\n- 适合高级用户和服务器部署场景\n\n```typescript\n// 切换到托管模式\nconst handleSwitchToManaged = async () => {\n // 停止外部守护进程连接\n // 启动本地托管守护进程\n}\n\n// 切换到外部模式\nconst handleConnectToExternal = async (url: string) => {\n // 验证 URL 格式\n // 建立到指定守护进程的 WebSocket 连接\n}\n```\n\n## Claude CLI 集成\n\n桌面应用负责检测和管理本地 Claude CLI 安装，是与 Claude Code 进行交互的基础。\n\n### Claude 配置检测\n\n系统会自动检测 Claude CLI 的安装状态和路径：\n\n| 检测状态 | 指示器 | 说明 |\n|----------|--------|------|\n| 已配置且可用 | 绿色勾选图标 | Claude CLI 已安装并可执行 |\n| 已配置但不可用 | 红色叉号图标 | 配置了路径但无法执行 |\n| 未检测到 | 红色叉号图标 | 未在标准路径中找到 Claude CLI |\n\n### Claude 路径配置\n\n支持用户手动指定 Claude CLI 的可执行文件路径：\n\n```typescript\ninterface ClaudeConfig {\n claudePath?: string; // 用户配置的路径\n claudeDetectedPath?: string; // 系统检测到的路径\n claudeAvailable: boolean; // 是否可用\n}\n```\n\n## 应用设置系统\n\nSettingsDialog 组件提供了完整的应用配置管理界面。\n\n### 遥测数据收集\n\nHumanLayer 提供可选的性能和错误报告功能，用户可以随时更改偏好设置：\n\n```typescript\ninterface UserSettings {\n optInTelemetry: boolean; // 是否启用遥测\n advancedProviders: boolean; // 是否启用高级提供商\n theme: 'light' | 'dark' | 'system'; // 主题设置\n}\n```\n\n**收集的数据范围**\n\n| 数据类型 | 说明 |\n|----------|------|\n| 错误堆栈信息 | 帮助诊断应用崩溃问题 |\n| 性能指标 | 应用响应时间和资源使用情况 |\n| 匿名使用统计 | 功能使用频率等匿名数据 |\n\n**不收集的数据**\n\n- 用户提示词或对话内容\n- 代码内容或文件路径\n- API 密钥或个人身份信息\n- 工作目录名称\n\n### 日志管理\n\n应用将运行日志存储在本地文件系统，SettingsDialog 提供了日志路径显示和一键复制功能：\n\n```typescript\n// 获取日志文件路径\nconst logPath = await getLogPath();\n\n// 复制日志路径到剪贴板\nconst handleCopyLogPath = async () => {\n await navigator.clipboard.writeText(logPath);\n};\n```\n\n## 窗口管理\n\n### 窗口状态栏\n\nLayout 组件在窗口底部显示状态栏，提供实时系统状态信息：\n\n| 区域 | 内容 | 说明 |\n|------|------|------|\n| 左侧 | 应用标识 | \"humanlayer\" 文字标识 |\n| 中部 | 连接状态 | 健康状态或重连按钮 |\n| 右侧 | 开发模式信息 | DEV 模式下显示 URL |\n\n### 状态指示器\n\n```typescript\n// 健康状态显示\n{healthStatus === 'degraded' && (\n \n)}\n\n// 断开连接时显示重连按钮\n{!connected && !connecting && (\n \n)}\n```\n\n## 安全特性\n\n### 内容安全策略（CSP）\n\nTauri 配置中定义了严格的内容安全策略：\n\n```\ndefault-src 'self'; \nscript-src 'self'; \nstyle-src 'self' 'unsafe-inline'\n```\n\n该策略确保：\n\n- 所有资源只能从应用自身加载\n- 脚本只能执行同源代码\n- 样式允许内联以支持组件样式\n\n### 权限管理\n\n应用采用\"危险跳过权限\"（DangerouslySkipPermissions）功能，允许高级用户在特定条件下绕过审批流程：\n\n```typescript\ninterface SkipPermissionsConfig {\n useTimeout: boolean; // 是否启用超时自动禁用\n timeoutMinutes: number; // 超时时间（分钟）\n confirmed: boolean; // 用户是否已确认警告\n}\n```\n\n此功能覆盖的操作类型：\n\n- 文件编辑和写入操作\n- Bash 命令执行\n- 文件读取操作\n- 子任务生成\n- 所有 MCP 工具调用\n\n> ⚠️ 警告：使用危险跳过权限功能存在安全风险，应谨慎操作。\n\n## 构建与部署\n\n### 开发环境启动\n\n```bash\n# 进入前端目录\ncd humanlayer-wui\n\n# 安装依赖\npnpm install\n\n# 启动开发服务器\npnpm dev\n```\n\n开发模式下，Tauri 应用会连接到 `http://localhost:5173` 的前端开发服务器，实现热重载功能。\n\n### 生产构建\n\n```bash\n# 构建前端资源\npnpm build\n\n# 构建 Tauri 应用\ncargo build --release\n```\n\n构建产物包括：\n\n| 平台 | 输出目录 | 可执行文件 |\n|------|----------|------------|\n| Windows | src-tauri/target/release/ | humanlayer.exe |\n| macOS | src-tauri/target/release/ | humanlayer.app |\n| Linux | src-tauri/target/release/ | humanlayer |\n\n## 故障排除\n\n### 常见连接问题\n\n| 问题症状 | 可能原因 | 解决方案 |\n|----------|----------|----------|\n| 显示\"未连接\" | 守护进程未启动 | 点击\"重试连接\"或重启应用 |\n| 显示\"运行异常\" | 守护进程崩溃 | 使用 DebugPanel 重启守护进程 |\n| 无法检测 Claude | CLI 未安装 | 安装 Claude CLI 或配置路径 |\n| 超时设置无效 | 输入值超出范围 | 确保超时值在 1-60 分钟之间 |\n\n### 日志诊断\n\n日志文件路径可通过设置界面复制，便于提交问题报告时提供诊断信息：\n\n1. 打开设置对话框\n2. 找到\"日志\"部分\n3. 点击复制按钮获取路径\n4. 使用文件管理器导航到日志目录\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：humanlayer/humanlayer\n\n暂未发现结构化踩坑项；仍需完成沙箱安装和 Quick Start 验证。\n\n\n", "markdown_key": "humanlayer", "pages": "draft", "source_refs": [ { "evidence_id": "github_repo:838542536", "kind": "repo", "supports_claim_ids": [ "claim_identity", "claim_distribution", "claim_capability" ], "url": "https://github.com/humanlayer/humanlayer" }, { "evidence_id": "art_63f8c77f37f24d33b48617b92e83b548", "kind": "docs", "supports_claim_ids": [ "claim_identity", "claim_distribution", "claim_capability" ], "url": "https://github.com/humanlayer/humanlayer#readme" } ], "summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。", "title": "humanlayer 说明书", "toc": [ "https://github.com/humanlayer/humanlayer 项目说明书", "目录", "项目概览", "1. 项目简介", "2. 系统架构", "3. 用户界面功能", "4. 工具调用系统", "5. 设置与配置", "Doramagic 踩坑日志" ] } }, "quality_gate": { "blocking_gaps": [], "category_confidence": "medium", "compile_status": "ready_for_review", "five_assets_present": true, "install_sandbox_verified": true, "missing_evidence": [], "next_action": "publish to Doramagic.ai project surfaces", "prompt_preview_boundary_ok": true, "publish_status": "publishable", "quick_start_verified": true, "repo_clone_verified": true, "repo_commit": "bdea199cec94a1605d2a0de42309d67a14dafdf2", "repo_inspection_error": null, "repo_inspection_files": [ "package.json", "README.md", "docker-compose.yml", "docs/workshop.mdx", "docs/development.mdx", "docs/package-lock.json", "docs/mint.json", "docs/docs.knowledge.md", "docs/quickstart-typescript.mdx", "docs/introduction.mdx", "docs/readme.md", "docs/case-studies/healthcare-case-study.md", "packages/database/CLAUDE.md", "packages/database/index.ts", "packages/database/types.ts", "packages/database/package.json", "packages/database/README.md", "packages/database/tsconfig.json", "packages/database/database.ts", "packages/database/drizzle.config.ts", "packages/contracts/tsconfig.types.json", "packages/contracts/CLAUDE.md", "packages/contracts/package.json", "packages/contracts/README.md", "packages/contracts/tsconfig.json", "packages/database/columns/bytea.ts", "packages/database/scripts/test.ts", "packages/database/schema/thoughts.ts", "packages/database/schema/index.ts", "packages/database/schema/scores.ts", "packages/database/drizzle/meta/0001_snapshot.json", "packages/database/drizzle/meta/0000_snapshot.json", "packages/database/drizzle/meta/0002_snapshot.json", "packages/database/drizzle/meta/_journal.json", "packages/contracts/src/index.ts", "packages/contracts/src/daemon/index.ts", "packages/contracts/src/daemon/openapi.ts" ], "repo_inspection_verified": true, "review_reasons": [ "community_discussion_evidence_below_public_threshold" ], "tag_count_ok": true, "unsupported_claims": [] }, "schema_version": "0.1", "user_assets": { "ai_context_pack": { "asset_id": "ai_context_pack", "filename": "AI_CONTEXT_PACK.md", "markdown": "# codelayer - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 codelayer 编译的 AI Context Pack。请把它当作开工前上下文：帮助用户理解适合谁、能做什么、如何开始、哪些必须安装后验证、风险在哪里。不要声称你已经安装、运行或执行了目标项目。\n\n## Claim 消费规则\n\n- **事实来源**：Repo Evidence + Claim/Evidence Graph；Human Wiki 只提供显著性、术语和叙事结构。\n- **事实最低状态**：`supported`\n- `supported`：可以作为项目事实使用，但回答中必须引用 claim_id 和证据路径。\n- `weak`：只能作为低置信度线索，必须要求用户继续核实。\n- `inferred`：只能用于风险提示或待确认问题，不能包装成项目事实。\n- `unverified`：不得作为事实使用，应明确说证据不足。\n- `contradicted`：必须展示冲突来源，不得替用户强行选择一个版本。\n\n## 它最适合谁\n\n- **正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**：README 或插件配置提到多个宿主 AI。 证据：`README.md` Claim：`clm_0002` supported 0.86\n\n## 它能做什么\n\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`README.md` Claim：`clm_0001` supported 0.86\n\n## 怎么开始\n\n- `npx humanlayer join-waitlist --email ...` 证据：`README.md` Claim：`clm_0003` supported 0.86\n\n## 继续前判断卡\n\n- **当前建议**：先做角色匹配试用\n- **为什么**：这个项目更像角色库，核心风险是选错角色或把角色文案当执行能力；先用 Prompt Preview 试角色匹配，再决定是否沙盒导入。\n\n### 30 秒判断\n\n- **现在怎么做**：先做角色匹配试用\n- **最小安全下一步**：先用 Prompt Preview 试角色匹配；满意后再隔离导入\n- **先别相信**：角色质量和任务匹配不能直接相信。\n- **继续会触碰**：角色选择偏差、命令执行、宿主 AI 配置\n\n### 现在可以相信\n\n- **适合人群线索：正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0002` supported 0.86\n- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`README.md` Claim：`clm_0001` supported 0.86\n- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`README.md` Claim：`clm_0003` supported 0.86\n\n### 现在还不能相信\n\n- **角色质量和任务匹配不能直接相信。**（unverified）：角色库证明有很多角色，不证明每个角色都适合你的具体任务，也不证明角色能产生高质量结果。\n- **不能把角色文案当成真实执行能力。**（unverified）：安装前只能判断角色描述和任务画像是否匹配，不能证明它能在宿主 AI 里完成任务。\n- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。\n- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。\n- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。 证据：`CLAUDE.md`\n- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。\n- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。\n- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。\n\n### 继续会触碰什么\n\n- **角色选择偏差**：用户对任务应该由哪个专家角色处理的判断。 原因：选错角色会让 AI 从错误专业视角回答，浪费时间或误导决策。\n- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`README.md`\n- **宿主 AI 配置**：Claude/Codex/Cursor/Gemini/OpenCode 等宿主的 plugin、Skill 或规则加载配置。 原因：宿主配置会改变 AI 后续工作方式，可能和用户已有规则冲突。 证据：`CLAUDE.md`\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`README.md`\n- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。\n\n### 最小安全下一步\n\n- **先跑 Prompt Preview**：先用交互式试用验证任务画像和角色匹配，不要先导入整套角色库。（适用：任何项目都适用，尤其是输出质量未知时。）\n- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）\n- **先备份宿主 AI 配置**：Skill、plugin、规则文件可能改变 Claude/Cursor/Codex 的默认行为。（适用：存在插件 manifest、Skill 或宿主规则入口时。）\n- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）\n\n### 退出方式\n\n- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。\n- **准备移除宿主 plugin / Skill / 规则入口**：如果试装后行为异常，可以把宿主 AI 恢复到试装前状态。\n- **保留原始角色选择记录**：如果输出偏题，可以回到任务画像阶段重新选择角色，而不是继续沿着错误角色推进。\n- **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。\n- **如果没有回滚路径，不进入主力环境**：不可回滚是继续前阻断项，不应靠信任或运气继续。\n\n## 哪些只能预览\n\n- 解释项目适合谁和能做什么\n- 基于项目文档演示典型对话流程\n- 帮助用户判断是否值得安装或继续研究\n\n## 哪些必须安装后验证\n\n- 真实安装 Skill、插件或 CLI\n- 执行脚本、修改本地文件或访问外部服务\n- 验证真实输出质量、性能和兼容性\n\n## 边界与风险判断卡\n\n- **把安装前预览误认为真实运行**：用户可能高估项目已经完成的配置、权限和兼容性验证。 处理方式：明确区分 prompt_preview_can_do 与 runtime_required。 Claim：`clm_0004` inferred 0.45\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`README.md` Claim：`clm_0005` supported 0.86\n- **待确认**：真实安装后是否与用户当前宿主 AI 版本兼容？。原因：兼容性只能通过实际宿主环境验证。\n- **待确认**：项目输出质量是否满足用户具体任务？。原因：安装前预览只能展示流程和边界，不能替代真实评测。\n- **待确认**：安装命令是否需要网络、权限或全局写入？。原因：这影响企业环境和个人环境的安装风险。\n\n## 开工前工作上下文\n\n### 加载顺序\n\n- 先读取 how_to_use.host_ai_instruction，建立安装前判断资产的边界。\n- 读取 claim_graph_summary，确认事实来自 Claim/Evidence Graph，而不是 Human Wiki 叙事。\n- 再读取 intended_users、capabilities 和 quick_start_candidates，判断用户是否匹配。\n- 需要执行具体任务时，优先查 role_skill_index，再查 evidence_index。\n- 遇到真实安装、文件修改、网络访问、性能或兼容性问题时，转入 risk_card 和 boundaries.runtime_required。\n\n### 任务路由\n\n- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`README.md` Claim：`clm_0001` supported 0.86\n\n### 上下文规模\n\n- 文件总数：729\n- 重要文件覆盖：40/729\n- 证据索引条目：80\n- 角色 / Skill 条目：68\n\n### 证据不足时的处理\n\n- **missing_evidence**：说明证据不足，要求用户提供目标文件、README 段落或安装后验证记录；不要补全事实。\n- **out_of_scope_request**：说明该任务超出当前 AI Context Pack 证据范围，并建议用户先查看 Human Manual 或真实安装后验证。\n- **runtime_request**：给出安装前检查清单和命令来源，但不要替用户执行命令或声称已执行。\n- **source_conflict**：同时展示冲突来源，标记为待核实，不要强行选择一个版本。\n\n## Prompt Recipes\n\n### 适配判断\n\n- 目标：判断这个项目是否适合用户当前任务。\n- 预期输出：适配结论、关键理由、证据引用、安装前可预览内容、必须安装后验证内容、下一步建议。\n\n```text\n请基于 codelayer 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 codelayer 当作安装前体验资产，而不是已安装工具或真实运行环境。\n\n请严格输出四段：\n1. 先问我 3 个必要问题。\n2. 给出一段“体验剧本”：用 [安装前可预览]、[必须安装后验证]、[证据不足] 三种标签展示它可能如何引导工作流。\n3. 给出安装后验证清单：列出哪些能力只有真实安装、真实宿主加载、真实项目运行后才能确认。\n4. 给出谨慎建议：只能说“值得继续研究/试装”“先补充信息后再判断”或“不建议继续”，不得替项目背书。\n\n硬性边界：\n- 不要声称已经安装、运行、执行测试、修改文件或产生真实结果。\n- 不要写“自动适配”“确保通过”“完美适配”“强烈建议安装”等承诺性表达。\n- 如果描述安装后的工作方式，必须使用“如果安装成功且宿主正确加载 Skill，它可能会……”这种条件句。\n- 体验剧本只能写成“示例台词/假设流程”：使用“可能会询问/可能会建议/可能会展示”，不要写“已写入、已生成、已通过、正在运行、正在生成”。\n- Prompt Preview 不负责给安装命令；如用户准备试装，只能提示先阅读 Quick Start 和 Risk Card，并在隔离环境验证。\n- 所有项目事实必须来自 supported claim、evidence_refs 或 source_paths；inferred/unverified 只能作风险或待确认项。\n\n```\n\n### 角色 / Skill 选择\n\n- 目标：从项目里的角色或 Skill 中挑选最匹配的资产。\n- 预期输出：候选角色或 Skill 列表，每项包含适用场景、证据路径、风险边界和是否需要安装后验证。\n\n```text\n请读取 role_skill_index，根据我的目标任务推荐 3-5 个最相关的角色或 Skill。每个推荐都要说明适用场景、可能输出、风险边界和 evidence_refs。\n```\n\n### 风险预检\n\n- 目标：安装或引入前识别环境、权限、规则冲突和质量风险。\n- 预期输出：环境、权限、依赖、许可、宿主冲突、质量风险和未知项的检查清单。\n\n```text\n请基于 risk_card、boundaries 和 quick_start_candidates，给我一份安装前风险预检清单。不要替我执行命令，只说明我应该检查什么、为什么检查、失败会有什么影响。\n```\n\n### 宿主 AI 开工指令\n\n- 目标：把项目上下文转成一次对话开始前的宿主 AI 指令。\n- 预期输出：一段边界明确、证据引用明确、适合复制给宿主 AI 的开工前指令。\n\n```text\n请基于 codelayer 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 68 个角色 / Skill / 项目文档条目。\n\n- **Mintlify Starter Kit**（project_doc）：Click on Use this template to copy the Mintlify starter kit. The starter kit contains examples including 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/readme.md`\n- **CLAUDE.md**（project_doc）：This file provides guidance to Claude Code claude.ai/code when working with code in this repository. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`CLAUDE.md`\n- **The best way to get Coding Agents to solve hard problems in complex codebases**（project_doc）：! Wordmark Logo of HumanLayer ./docs/images/wordmark-light.svg 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`README.md`\n- **Claude Code Go SDK Experimental**（project_doc）：A Go SDK for programmatically interacting with Claude Code Anthropic's AI coding assistant . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`claudecode-go/README.md`\n- **Go style guidelines**（project_doc）：This is the humanlayer Daemon HLD that powers the WUI humanlayer-wui 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`hld/CLAUDE.md`\n- **HumanLayer Daemon hld**（project_doc）：The HumanLayer Daemon hld provides a REST API and JSON-RPC interface for managing Claude Code sessions, approvals, and real-time event streaming. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`hld/README.md`\n- **HumanLayer CLI**（project_doc）：HumanLayer, but on your command-line. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`hlyr/README.md`\n- **Tips and Tricks**（project_doc）：This is the HumanLayer Web UI WUI - a desktop application for managing AI agent approvals and sessions. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`humanlayer-wui/CLAUDE.md`\n- **humanlayer-wui**（project_doc）：Web/desktop UI for the HumanLayer daemon hld built with Tauri and React. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`humanlayer-wui/README.md`\n- **APIs**（project_doc）：Default to using Bun instead of Node.js. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`scripts/CLAUDE.md`\n- **scripts**（project_doc）：This project was created using bun init in bun v1.2.23. Bun https://bun.com is a fast all-in-one JavaScript runtime. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`scripts/README.md`\n- **HOW TO ITERATE ON GITHUB ACTIONS**（project_doc）：1. Select a branch to work on 2. Add branch to workflow trigger : 3. Make one targeted change e.g., cache one thing like Go dependencies 4. Commit and push to the branch ON UPSTREAM git push -u upstream your-debug-branch 5. Check logs with gh : 6. Repeat until working as expected 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.github/workflows/CLAUDE.md`\n- **APIs**（project_doc）：Default to using Bun instead of Node.js. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`apps/daemon/CLAUDE.md`\n- **daemon**（project_doc）：This project was created using bun init in bun v1.2.23. Bun https://bun.com is a fast all-in-one JavaScript runtime. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`apps/daemon/README.md`\n- **APIs**（project_doc）：Default to using Bun instead of Node.js. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`apps/react/CLAUDE.md`\n- **bun-react-tailwind-shadcn-template**（project_doc）：This project was created using bun init in bun v1.2.23. Bun https://bun.com is a fast all-in-one JavaScript runtime. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`apps/react/README.md`\n- **Linear CLI**（project_doc）：A command-line interface for interacting with Linear issue tracking. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`hack/linear/README.md`\n- **HumanLayer Daemon TypeScript SDK**（project_doc）：This SDK provides a TypeScript/JavaScript client for the HumanLayer Daemon HLD REST API. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`hld/sdk/typescript/README.md`\n- **WUI Demo Store System**（project_doc）：A comprehensive demo store system for creating synthetic product shots and marketing animations using Zustand's slice pattern architecture. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`humanlayer-wui/src/stores/demo/README.md`\n- **APIs**（project_doc）：Default to using Bun instead of Node.js. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`packages/contracts/CLAUDE.md`\n- **@codelayer/protocol**（project_doc）：This project was created using bun init in bun v1.2.23. Bun https://bun.com is a fast all-in-one JavaScript runtime. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`packages/contracts/README.md`\n- **APIs**（project_doc）：Default to using Bun instead of Node.js. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`packages/database/CLAUDE.md`\n- **database**（project_doc）：This project was created using bun init in bun v1.2.23. Bun https://bun.com is a fast all-in-one JavaScript runtime. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`packages/database/README.md`\n- **Contributing to HumanLayer**（project_doc）：If you're looking to contribute, please: 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`CONTRIBUTING.md`\n- **Documentation System**（project_doc）：- Version tags follow semver vX.Y.Z - Features added in main branch - Examples updated alongside feature development - Changelog maintained for each version - Both Python and TypeScript packages versioned together - Generate release notes using git commands: - Use git diff v0.5.11..v0.6.0 to see file changes between versions - Always query changes from git before updating CHANGELOG.md - Changelog priorities: - Docum… 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/docs.knowledge.md`\n- **Case Study: Accelerating Technical Debt Resolution with AI Coding Agents**（project_doc）：Case Study: Accelerating Technical Debt Resolution with AI Coding Agents 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/case-studies/healthcare-case-study.md`\n- **API Reference**（project_doc）：Fetch and manage approval requests. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`humanlayer-wui/docs/API.md`\n- **Architecture Overview**（project_doc）：mermaid graph LR subgraph \"Frontend TypeScript \" RC React Component RH React Hooks DC Daemon Client end 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`humanlayer-wui/docs/ARCHITECTURE.md`\n- **Developer Guide**（project_doc）：This guide helps you build UI components that interact with the HumanLayer daemon. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`humanlayer-wui/docs/DEVELOPER_GUIDE.md`\n- **Hotkey Scope System Documentation**（project_doc）：The application uses a hierarchical hotkey scope system built on top of react-hotkeys-hook to properly isolate keyboard shortcuts and prevent conflicts between different UI contexts. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`humanlayer-wui/docs/HOTKEYS.md`\n- **What problem s was I solving?**（project_doc）：What user-facing changes did I ship? 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.github/PULL_REQUEST_TEMPLATE.md`\n- **Development Guide**（project_doc）：This guide covers development workflows and tools for the HumanLayer repository. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`DEVELOPMENT.md`\n- **HumanLayer Daemon HLD Protocol Documentation**（project_doc）：HumanLayer Daemon HLD Protocol Documentation 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`hld/PROTOCOL.md`\n- **HumanLayer Daemon HLD - TODO**（project_doc）：Goal : Reduce N+1 problem for TUI message count display Current issue : TUI needs separate GetConversation call per session to count messages Proposed solution : Add bulk endpoint that returns conversation metadata message count, last message, etc. for multiple sessions Alternative : Extend ListSessions to include conversation metadata Performance impact : Would significantly improve TUI session list load times File… 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`hld/TODO.md`\n- **Changelog**（project_doc）：All notable changes to the HumanLayer CLI hlyr will be documented in this file. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`hlyr/CHANGELOG.md`\n- **HumanLayer Thoughts Management System**（project_doc）：HumanLayer Thoughts Management System 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`hlyr/THOUGHTS.md`\n- **macOS Release Workflow Usage Guide**（project_doc）：Testing the Workflow Before Merging 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`humanlayer-wui/RELEASE.md`\n- **Problems**（project_doc）：- 'c' on session table doesn't launch the session creator - selecting \"create new session\" from the cmd+k launch takes me to a blank screen - search view still doesn't work - the max height should be 80% of the screen height, and only display as many items as can fit - selecting a session from the search view should navigate to the session details 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`humanlayer-wui/problems.md`\n- **HumanLayer SDK Documentation**（project_doc）：🚧 Note : This documentation covers the HumanLayer SDK which is being superseded by CodeLayer. For the latest IDE experience, see the main README. 🚧 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`humanlayer.md`\n- **Manual Test Plan for Slash Commands Fix**（project_doc）：Manual Test Plan for Slash Commands Fix 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`test-slash-commands.md`\n- **codebase-analyzer**（project_doc）：Analyzes codebase implementation details. Call the codebase-analyzer agent when you need to find detailed information about specific components. As always, the more detailed your request prompt, the better! : 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.claude/agents/codebase-analyzer.md`\n- **codebase-locator**（project_doc）：Locates files, directories, and components relevant to a feature or task. Call codebase-locator with human language prompt describing what you're looking for. Basically a \"Super Grep/Glob/LS tool\" — Use it if you find yourself desiring to use one of these tools more than once. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.claude/agents/codebase-locator.md`\n- **codebase-pattern-finder**（project_doc）：codebase-pattern-finder is a useful subagent type for finding similar implementations, usage examples, or existing patterns that can be modeled after. It will give you concrete code examples based on what you're looking for! It's sorta like codebase-locator, but it will not only tell you the location of files, it will also give you code details! 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.claude/agents/codebase-pattern-finder.md`\n- **thoughts-analyzer**（project_doc）：The research equivalent of codebase-analyzer. Use this subagent type when wanting to deep dive on a research topic. Not commonly needed otherwise. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.claude/agents/thoughts-analyzer.md`\n- **thoughts-locator**（project_doc）：Discovers relevant documents in thoughts/ directory We use this for all sorts of metadata storage! . This is really only relevant/needed when you're in a reseaching mood and need to figure out if we have random thoughts written down that are relevant to your current research task. Based on the name, I imagine you can guess this is the thoughts equivilent of codebase-locator 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.claude/agents/thoughts-locator.md`\n- **web-search-researcher**（project_doc）：Do you find yourself desiring information that you don't quite feel well-trained confident on? Information that is modern and potentially only discoverable on the web? Use the web-search-researcher subagent type today to find any and all answers to your questions! It will research deeply to figure out and attempt to answer your questions! If you aren't immediately satisfied you can get your money back! Not really -… 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.claude/agents/web-search-researcher.md`\n- **Commit Changes**（project_doc）：Create git commits for session changes with clear, atomic messages 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.claude/commands/ci_commit.md`\n- **Generate PR Description**（project_doc）：Generate comprehensive PR descriptions following repository templates 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.claude/commands/ci_describe_pr.md`\n- **Commit Changes**（project_doc）：Create git commits with user approval and no Claude attribution 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.claude/commands/commit.md`\n- **Create Handoff**（project_doc）：Create handoff document for transferring work to another session 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.claude/commands/create_handoff.md`\n- **Implementation Plan**（project_doc）：Create detailed implementation plans through interactive research and iteration 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.claude/commands/create_plan.md`\n- **Implementation Plan**（project_doc）：Create detailed implementation plans with thorough research and iteration 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.claude/commands/create_plan_generic.md`\n- **Implementation Plan**（project_doc）：Create implementation plans with thorough research no thoughts directory 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.claude/commands/create_plan_nt.md`\n- **Create Worktree**（project_doc）：Create worktree and launch implementation session for a plan 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.claude/commands/create_worktree.md`\n- **Debug**（project_doc）：Debug issues by investigating logs, database state, and git history 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.claude/commands/debug.md`\n- **Generate PR Description**（project_doc）：Generate comprehensive PR descriptions following repository templates 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.claude/commands/describe_pr.md`\n- **Generate PR Description**（project_doc）：Generate comprehensive PR descriptions following repository templates 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.claude/commands/describe_pr_nt.md`\n- **Founder Mode**（project_doc）：Create Linear ticket and PR for experimental features after implementation 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.claude/commands/founder_mode.md`\n- **Implement Plan**（project_doc）：Implement technical plans from thoughts/shared/plans with verification 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.claude/commands/implement_plan.md`\n- **Iterate Implementation Plan**（project_doc）：Iterate on existing implementation plans with thorough research and updates 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.claude/commands/iterate_plan.md`\n- **Iterate Implementation Plan**（project_doc）：Iterate on existing implementation plans with thorough research and updates 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.claude/commands/iterate_plan_nt.md`\n- **Linear - Ticket Management**（project_doc）：Manage Linear tickets - create, update, comment, and follow workflow patterns 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.claude/commands/linear.md`\n- **Local Review**（project_doc）：Set up worktree for reviewing colleague's branch 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.claude/commands/local_review.md`\n- **Oneshot**（project_doc）：Research ticket and launch planning session 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.claude/commands/oneshot.md`\n- **Oneshot Plan**（project_doc）：Execute ralph plan and implementation for a ticket 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.claude/commands/oneshot_plan.md`\n- **PART I - IF A TICKET IS MENTIONED**（project_doc）：Implement highest priority small Linear ticket with worktree setup 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.claude/commands/ralph_impl.md`\n- **PART I - IF A TICKET IS MENTIONED**（project_doc）：Create implementation plan for highest priority Linear ticket ready for spec 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.claude/commands/ralph_plan.md`\n- **PART I - IF A LINEAR TICKET IS MENTIONED**（project_doc）：Research highest priority Linear ticket needing investigation 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.claude/commands/ralph_research.md`\n\n## 证据索引\n\n- 共索引 80 条证据。\n\n- **Mintlify Starter Kit**（documentation）：Click on Use this template to copy the Mintlify starter kit. The starter kit contains examples including 证据：`docs/readme.md`\n- **CLAUDE.md**（documentation）：This file provides guidance to Claude Code claude.ai/code when working with code in this repository. 证据：`CLAUDE.md`\n- **The best way to get Coding Agents to solve hard problems in complex codebases**（documentation）：! Wordmark Logo of HumanLayer ./docs/images/wordmark-light.svg 证据：`README.md`\n- **Claude Code Go SDK Experimental**（documentation）：A Go SDK for programmatically interacting with Claude Code Anthropic's AI coding assistant . 证据：`claudecode-go/README.md`\n- **Go style guidelines**（documentation）：This is the humanlayer Daemon HLD that powers the WUI humanlayer-wui 证据：`hld/CLAUDE.md`\n- **HumanLayer Daemon hld**（documentation）：The HumanLayer Daemon hld provides a REST API and JSON-RPC interface for managing Claude Code sessions, approvals, and real-time event streaming. 证据：`hld/README.md`\n- **HumanLayer CLI**（documentation）：HumanLayer, but on your command-line. 证据：`hlyr/README.md`\n- **Tips and Tricks**（documentation）：This is the HumanLayer Web UI WUI - a desktop application for managing AI agent approvals and sessions. 证据：`humanlayer-wui/CLAUDE.md`\n- **humanlayer-wui**（documentation）：Web/desktop UI for the HumanLayer daemon hld built with Tauri and React. 证据：`humanlayer-wui/README.md`\n- **APIs**（documentation）：Default to using Bun instead of Node.js. 证据：`scripts/CLAUDE.md`\n- **scripts**（documentation）：This project was created using bun init in bun v1.2.23. Bun https://bun.com is a fast all-in-one JavaScript runtime. 证据：`scripts/README.md`\n- **HOW TO ITERATE ON GITHUB ACTIONS**（documentation）：1. Select a branch to work on 2. Add branch to workflow trigger : 3. Make one targeted change e.g., cache one thing like Go dependencies 4. Commit and push to the branch ON UPSTREAM git push -u upstream your-debug-branch 5. Check logs with gh : 6. Repeat until working as expected 证据：`.github/workflows/CLAUDE.md`\n- **APIs**（documentation）：Default to using Bun instead of Node.js. 证据：`apps/daemon/CLAUDE.md`\n- **daemon**（documentation）：This project was created using bun init in bun v1.2.23. Bun https://bun.com is a fast all-in-one JavaScript runtime. 证据：`apps/daemon/README.md`\n- **APIs**（documentation）：Default to using Bun instead of Node.js. 证据：`apps/react/CLAUDE.md`\n- **bun-react-tailwind-shadcn-template**（documentation）：This project was created using bun init in bun v1.2.23. Bun https://bun.com is a fast all-in-one JavaScript runtime. 证据：`apps/react/README.md`\n- **Linear CLI**（documentation）：A command-line interface for interacting with Linear issue tracking. 证据：`hack/linear/README.md`\n- **HumanLayer Daemon TypeScript SDK**（documentation）：This SDK provides a TypeScript/JavaScript client for the HumanLayer Daemon HLD REST API. 证据：`hld/sdk/typescript/README.md`\n- **WUI Demo Store System**（documentation）：A comprehensive demo store system for creating synthetic product shots and marketing animations using Zustand's slice pattern architecture. 证据：`humanlayer-wui/src/stores/demo/README.md`\n- **APIs**（documentation）：Default to using Bun instead of Node.js. 证据：`packages/contracts/CLAUDE.md`\n- **@codelayer/protocol**（documentation）：This project was created using bun init in bun v1.2.23. Bun https://bun.com is a fast all-in-one JavaScript runtime. 证据：`packages/contracts/README.md`\n- **APIs**（documentation）：Default to using Bun instead of Node.js. 证据：`packages/database/CLAUDE.md`\n- **database**（documentation）：This project was created using bun init in bun v1.2.23. Bun https://bun.com is a fast all-in-one JavaScript runtime. 证据：`packages/database/README.md`\n- **Package**（package_manifest）：{ \"name\": \"humanlayer\", \"version\": \"0.17.2-npm\", \"description\": \"HumanLayer, but on your command-line.\", \"type\": \"module\", \"bin\": { \"humanlayer\": \"dist/index.js\", \"hlyr\": \"dist/index.js\", \"codelayer\": \"dist/index.js\", \"codelayer-nightly\": \"dist/index.js\" }, \"files\": \"dist/ / \", \".claude/ / \", \"README.md\" , \"scripts\": { \"build\": \"tsup\", \"prepack\": \"npm run build && rimraf .claude && mkdir -p .claude && cp -r ../.claude/commands ../.claude/agents ../.claude/settings.json .claude/\", \"postpack\": \"rm -rf .claude\", \"build:watch\": \"tsup --watch\", \"dev\": \"npm run build && ./dist/index.js\", \"lint\": \"eslint . --ext .ts\", \"format\": \"prettier --write .\", \"format:check\": \"prettier --check .\", \"test\": \"v… 证据：`hlyr/package.json`\n- **Package**（package_manifest）：{ \"name\": \"humanlayer-wui\", \"private\": true, \"version\": \"0.1.0\", \"type\": \"module\", \"scripts\": { \"dev\": \"vite\", \"build\": \"tsc && vite build\", \"preview\": \"vite preview\", \"tauri\": \"tauri\", \"lint\": \"eslint . --ext .ts,.tsx\", \"format\": \"prettier --write .\", \"format:check\": \"prettier --check .\", \"typecheck\": \"tsc --noEmit\", \"check\": \"bun run format:check && bun run lint && bun run typecheck\", \"test\": \"bun test\", \"storybook\": \"storybook dev -p 6006\", \"build-storybook\": \"storybook build\" }, \"dependencies\": { \"@humanlayer/hld-sdk\": \"file:../hld/sdk/typescript\", \"@radix-ui/react-checkbox\": \"^1.3.2\", \"@radix-ui/react-collapsible\": \"^1.1.11\", \"@radix-ui/react-dialog\": \"^1.1.14\", \"@radix-ui/react-dropdo… 证据：`humanlayer-wui/package.json`\n- **Package**（package_manifest）：{ \"name\": \"codelayer\", \"private\": true, \"scripts\": { \"build\": \"turbo run build\", \"dev\": \"turbo run dev\", \"lint\": \"turbo run lint\", \"format\": \"prettier --write \\\" / .{ts,tsx,md}\\\"\", \"check-types\": \"turbo run check-types\", \"db:generate\": \"\", \"db:migrate\": \"\", \"db:seed\": \"\" }, \"devDependencies\": { \"@biomejs/biome\": \"^2.2.6\", \"prettier\": \"^3.6.2\", \"turbo\": \"^2.5.8\", \"typescript\": \"5.9.2\" }, \"engines\": { \"node\": \" =20\" }, \"packageManager\": \"bun@1.2.23\", \"workspaces\": \"apps/ \", \"packages/ \" } 证据：`package.json`\n- **Package**（package_manifest）：{ \"name\": \"scripts\", \"private\": true, \"devDependencies\": { \"@types/bun\": \"latest\", \"@codelayer/contracts\": \"workspace: \" }, \"peerDependencies\": { \"typescript\": \"^5\" } } 证据：`scripts/package.json`\n- **Contributing to HumanLayer**（documentation）：If you're looking to contribute, please: 证据：`CONTRIBUTING.md`\n- **Package**（package_manifest）：{ \"name\": \"daemon\", \"module\": \"index.ts\", \"type\": \"module\", \"private\": true, \"devDependencies\": { \"@types/bun\": \"latest\", \"bun-types\": \"^1.2.23\" }, \"peerDependencies\": { \"typescript\": \"^5\" }, \"dependencies\": { \"@codelayer/contracts\": \"workspace: \", \"@orpc/openapi\": \"^1.9.3\", \"@orpc/server\": \"^1.9.3\", \"@orpc/zod\": \"^1.9.3\", \"zod\": \"^4.1.11\" } } 证据：`apps/daemon/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@codelayer/react\", \"version\": \"0.1.0\", \"private\": true, \"type\": \"module\", \"scripts\": { \"dev\": \"PORT=4000 bun --hot src/index.tsx\", \"start\": \"NODE ENV=production bun src/index.tsx\", \"build\": \"bun run build.ts\" }, \"dependencies\": { \"@codelayer/database\": \"workspace: \", \"@electric-sql/react\": \"^1.0.14\", \"@radix-ui/react-label\": \"^2.1.7\", \"@radix-ui/react-select\": \"^2.2.5\", \"@radix-ui/react-slot\": \"^1.2.3\", \"@tiptap/extension-collaboration\": \"^2.2.4\", \"@tiptap/extension-collaboration-cursor\": \"^2.2.4\", \"@tiptap/pm\": \"^2.2.4\", \"@tiptap/react\": \"^2.2.4\", \"@tiptap/starter-kit\": \"^2.2.4\", \"bun-plugin-tailwind\": \"^0.0.15\", \"class-variance-authority\": \"^0.7.1\", \"clsx\": \"^2.1.1\", \"dotenv\":… 证据：`apps/react/package.json`\n- **Package**（package_manifest）：{ \"name\": \"linear-cli\", \"version\": \"1.0.0\", \"description\": \"Command line interface for Linear\", \"main\": \"./dist/linear-cli.js\", \"bin\": { \"linear\": \"./dist/linear-cli.js\" }, \"scripts\": { \"build\": \"tsc\", \"start\": \"ts-node linear-cli.ts\", \"prepare\": \"npm run build\" }, \"dependencies\": { \"@linear/sdk\": \"^1.22.0\", \"chalk\": \"^4.1.2\", \"commander\": \"^9.4.1\", \"inquirer\": \"^8.2.5\", \"node-fetch\": \"^2.7.0\" }, \"devDependencies\": { \"@types/inquirer\": \"^8.2.5\", \"@types/node\": \"^18.11.9\", \"@types/node-fetch\": \"^2.6.13\", \"brace-expansion\": \" =2.0.2\", \"ts-node\": \"^10.9.1\", \"typescript\": \"^4.8.4\" } } 证据：`hack/linear/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@humanlayer/hld-tests\", \"version\": \"1.0.0\", \"private\": true, \"scripts\": { \"test:e2e\": \"bun test-rest-api.ts\", \"test:e2e:verbose\": \"VERBOSE=true bun test-rest-api.ts --verbose\", \"test:e2e:manual\": \"bun test-rest-api.ts --pause-on-approval\" }, \"dependencies\": { \"@types/node\": \"^20.0.0\", \"bun\": \"latest\" } } 证据：`hld/e2e/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@humanlayer/hld-sdk\", \"version\": \"0.1.0\", \"description\": \"TypeScript SDK for HumanLayer Daemon REST API\", \"main\": \"dist/index.js\", \"types\": \"dist/index.d.ts\", \"scripts\": { \"build\": \"bun run tsc\", \"generate\": \"./scripts/generate.sh\", \"test\": \"bun test\", \"typecheck\": \"tsc --noEmit\", \"check\": \"bun run typecheck && bun test\" }, \"dependencies\": { \"eventsource\": \"^4.0.0\" }, \"devDependencies\": { \"@openapitools/openapi-generator-cli\": \"^2.7.0\", \"@types/eventsource\": \"^1.1.15\", \"@types/node\": \"^20.0.0\", \"@types/node-fetch\": \"^2.6.12\", \"typescript\": \"^5.0.0\" } } 证据：`hld/sdk/typescript/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@codelayer/contracts\", \"module\": \"index.ts\", \"main\": \"dist/index.js\", \"types\": \"dist/index.d.ts\", \"type\": \"module\", \"scripts\": { \"build\": \"bun build --target=node ./src/index.ts --outfile=dist/index.js && bun run build:declaration\", \"build:declaration\": \"tsc --emitDeclarationOnly --project tsconfig.types.json\", \"postbuild\": \"rimraf tsconfig.types.tsbuildinfo\" }, \"devDependencies\": { \"@types/bun\": \"latest\", \"bun-types\": \"^1.2.23\", \"rimraf\": \"^6.0.1\" }, \"peerDependencies\": { \"typescript\": \"^5\" }, \"files\": \"dist/ .js\", \"dist/ .d.ts\" , \"dependencies\": { \"@orpc/contract\": \"^1.9.2\", \"zod\": \"^4.1.11\" }, \"exports\": { \".\": \"./src/index.ts\", \"./daemon\": \"./src/daemon/index.ts\" } } 证据：`packages/contracts/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@codelayer/database\", \"module\": \"index.ts\", \"type\": \"module\", \"private\": true, \"scripts\": { \"db:generate\": \"drizzle-kit generate\", \"db:push\": \"drizzle-kit push\", \"db:migrate\": \"bun drizzle-kit migrate\", \"db:introspect\": \"drizzle-kit introspect\", \"db:pull\": \"drizzle-kit pull\", \"db:studio\": \"drizzle-kit studio\" }, \"devDependencies\": { \"@types/bun\": \"latest\", \"drizzle-kit\": \"^0.31.5\" }, \"peerDependencies\": { \"typescript\": \"^5\" }, \"dependencies\": { \"drizzle-orm\": \"^0.44.6\", \"pg\": \"^8.16.3\", \"uuidv7\": \"^1.0.2\" } } 证据：`packages/database/package.json`\n- **License**（source_file）：Copyright c 2024, humanlayer Authors 证据：`LICENSE`\n- **Documentation System**（documentation）：- Version tags follow semver vX.Y.Z - Features added in main branch - Examples updated alongside feature development - Changelog maintained for each version - Both Python and TypeScript packages versioned together - Generate release notes using git commands: - Use git diff v0.5.11..v0.6.0 to see file changes between versions - Always query changes from git before updating CHANGELOG.md - Changelog priorities: - Document API changes first, especially new fields and parameters - Internal changes testing, docs, etc are lower priority - Always document new parameters in models.py or models.ts with their exact names - Link to relevant documentation when adding new features - Changelog organizatio… 证据：`docs/docs.knowledge.md`\n- **Case Study: Accelerating Technical Debt Resolution with AI Coding Agents**（documentation）：Case Study: Accelerating Technical Debt Resolution with AI Coding Agents 证据：`docs/case-studies/healthcare-case-study.md`\n- **API Reference**（documentation）：Fetch and manage approval requests. 证据：`humanlayer-wui/docs/API.md`\n- **Architecture Overview**（documentation）：mermaid graph LR subgraph \"Frontend TypeScript \" RC React Component RH React Hooks DC Daemon Client end 证据：`humanlayer-wui/docs/ARCHITECTURE.md`\n- **Developer Guide**（documentation）：This guide helps you build UI components that interact with the HumanLayer daemon. 证据：`humanlayer-wui/docs/DEVELOPER_GUIDE.md`\n- **Hotkey Scope System Documentation**（documentation）：The application uses a hierarchical hotkey scope system built on top of react-hotkeys-hook to properly isolate keyboard shortcuts and prevent conflicts between different UI contexts. 证据：`humanlayer-wui/docs/HOTKEYS.md`\n- **What problem s was I solving?**（documentation）：What user-facing changes did I ship? 证据：`.github/PULL_REQUEST_TEMPLATE.md`\n- **Development Guide**（documentation）：This guide covers development workflows and tools for the HumanLayer repository. 证据：`DEVELOPMENT.md`\n- **HumanLayer Daemon HLD Protocol Documentation**（documentation）：HumanLayer Daemon HLD Protocol Documentation 证据：`hld/PROTOCOL.md`\n- **HumanLayer Daemon HLD - TODO**（documentation）：Goal : Reduce N+1 problem for TUI message count display Current issue : TUI needs separate GetConversation call per session to count messages Proposed solution : Add bulk endpoint that returns conversation metadata message count, last message, etc. for multiple sessions Alternative : Extend ListSessions to include conversation metadata Performance impact : Would significantly improve TUI session list load times Files : rpc/handlers.go new endpoint , rpc/types.go new types Priority : Medium - would enable TUI message count feature without performance penalty 证据：`hld/TODO.md`\n- **Changelog**（documentation）：All notable changes to the HumanLayer CLI hlyr will be documented in this file. 证据：`hlyr/CHANGELOG.md`\n- **HumanLayer Thoughts Management System**（documentation）：HumanLayer Thoughts Management System 证据：`hlyr/THOUGHTS.md`\n- **macOS Release Workflow Usage Guide**（documentation）：Testing the Workflow Before Merging 证据：`humanlayer-wui/RELEASE.md`\n- **Problems**（documentation）：- 'c' on session table doesn't launch the session creator - selecting \"create new session\" from the cmd+k launch takes me to a blank screen - search view still doesn't work - the max height should be 80% of the screen height, and only display as many items as can fit - selecting a session from the search view should navigate to the session details 证据：`humanlayer-wui/problems.md`\n- **HumanLayer SDK Documentation**（documentation）：🚧 Note : This documentation covers the HumanLayer SDK which is being superseded by CodeLayer. For the latest IDE experience, see the main README. 🚧 证据：`humanlayer.md`\n- **Manual Test Plan for Slash Commands Fix**（documentation）：Manual Test Plan for Slash Commands Fix 证据：`test-slash-commands.md`\n- **CRITICAL: YOUR ONLY JOB IS TO DOCUMENT AND EXPLAIN THE CODEBASE AS IT EXISTS TODAY**（documentation）：You are a specialist at understanding HOW code works. Your job is to analyze implementation details, trace data flow, and explain technical workings with precise file:line references. 证据：`.claude/agents/codebase-analyzer.md`\n- **CRITICAL: YOUR ONLY JOB IS TO DOCUMENT AND EXPLAIN THE CODEBASE AS IT EXISTS TODAY**（documentation）：You are a specialist at finding WHERE code lives in a codebase. Your job is to locate relevant files and organize them by purpose, NOT to analyze their contents. 证据：`.claude/agents/codebase-locator.md`\n- **CRITICAL: YOUR ONLY JOB IS TO DOCUMENT AND SHOW EXISTING PATTERNS AS THEY ARE**（documentation）：You are a specialist at finding code patterns and examples in the codebase. Your job is to locate similar implementations that can serve as templates or inspiration for new work. 证据：`.claude/agents/codebase-pattern-finder.md`\n- **Core Responsibilities**（documentation）：You are a specialist at extracting HIGH-VALUE insights from thoughts documents. Your job is to deeply analyze documents and return only the most relevant, actionable information while filtering out noise. 证据：`.claude/agents/thoughts-analyzer.md`\n- **Core Responsibilities**（documentation）：You are a specialist at finding documents in the thoughts/ directory. Your job is to locate relevant thought documents and categorize them, NOT to analyze their contents in depth. 证据：`.claude/agents/thoughts-locator.md`\n- **Core Responsibilities**（documentation）：You are an expert web research specialist focused on finding accurate, relevant information from web sources. Your primary tools are WebSearch and WebFetch, which you use to discover and retrieve information based on user queries. 证据：`.claude/agents/web-search-researcher.md`\n- **Commit Changes**（documentation）：You are tasked with creating git commits for the changes made during this session. 证据：`.claude/commands/ci_commit.md`\n- **Generate PR Description**（documentation）：You are tasked with generating a comprehensive pull request description following the repository's standard template. 证据：`.claude/commands/ci_describe_pr.md`\n- 其余 20 条证据见 `AI_CONTEXT_PACK.json` 或 `EVIDENCE_INDEX.json`。\n\n## 宿主 AI 必须遵守的规则\n\n- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`docs/readme.md`, `CLAUDE.md`, `README.md`\n- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`docs/readme.md`, `CLAUDE.md`, `README.md`\n\n## 用户开工前应该回答的问题\n\n- 你准备在哪个宿主 AI 或本地环境中使用它？\n- 你只是想先体验工作流，还是准备真实安装？\n- 你最在意的是安装成本、输出质量、还是和现有规则的冲突？\n\n## 验收标准\n\n- 所有能力声明都能回指到 evidence_refs 中的文件路径。\n- AI_CONTEXT_PACK.md 没有把预览包装成真实运行。\n- 用户能在 3 分钟内看懂适合谁、能做什么、如何开始和风险边界。\n\n---\n\n## Doramagic Context Augmentation\n\n下面内容用于强化 Repomix/AI Context Pack 主体。Human Manual 只提供阅读骨架；踩坑日志会被转成宿主 AI 必须遵守的工作约束。\n\n## Human Manual 骨架\n\n使用规则：这里只是项目阅读路线和显著性信号，不是事实权威。具体事实仍必须回到 repo evidence / Claim Graph。\n\n宿主 AI 硬性规则：\n- 不得把页标题、章节顺序、摘要或 importance 当作项目事实证据。\n- 解释 Human Manual 骨架时，必须明确说它只是阅读路线/显著性信号。\n- 能力、安装、兼容性、运行状态和风险判断必须引用 repo evidence、source path 或 Claim Graph。\n\n- **项目概览**：importance `high`\n - source_paths: README.md, humanlayer.md, hld/README.md\n- **技术栈**：importance `high`\n - source_paths: hld/go.mod, humanlayer-wui/package.json, hlyr/package.json, packages/database/package.json\n- **系统架构**：importance `high`\n - source_paths: hld/daemon/daemon.go, hld/rpc/server.go, hld/api/handlers/server.go, humanlayer-wui/docs/ARCHITECTURE.md\n- **事件总线系统**：importance `medium`\n - source_paths: hld/bus/events.go, hld/bus/types.go, hld/bus/events_test.go\n- **会话管理**：importance `high`\n - source_paths: hld/session/manager.go, hld/session/types.go, hld/session/claudecode_wrapper.go, hld/session/permission_monitor.go, hld/session/summary.go\n- **审批工作流**：importance `high`\n - source_paths: hld/approval/manager.go, hld/approval/types.go, hld/approval/manager_test.go, hld/rpc/approval_handlers.go\n- **数据库与存储**：importance `high`\n - source_paths: packages/database/database.ts, packages/database/schema/index.ts, packages/database/schema/thoughts.ts, packages/database/schema/scores.ts, hld/store/sqlite.go\n- **REST API**：importance `high`\n - source_paths: hld/api/openapi.yaml, hld/api/handlers/agents.go, hld/api/handlers/sessions.go, hld/api/handlers/approvals.go, hld/api/handlers/files.go\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: true\n- repo_inspection_verified: true\n- repo_commit: `bdea199cec94a1605d2a0de42309d67a14dafdf2`\n- inspected_files: `package.json`, `README.md`, `docker-compose.yml`, `docs/workshop.mdx`, `docs/development.mdx`, `docs/package-lock.json`, `docs/mint.json`, `docs/docs.knowledge.md`, `docs/quickstart-typescript.mdx`, `docs/introduction.mdx`, `docs/readme.md`, `docs/case-studies/healthcare-case-study.md`, `packages/database/CLAUDE.md`, `packages/database/index.ts`, `packages/database/types.ts`, `packages/database/package.json`, `packages/database/README.md`, `packages/database/tsconfig.json`, `packages/database/database.ts`, `packages/database/drizzle.config.ts`\n\n宿主 AI 硬性规则：\n- 没有 repo_clone_verified=true 时，不得声称已经读过源码。\n- 没有 repo_inspection_verified=true 时，不得把 README/docs/package 文件判断写成事实。\n- 没有 quick_start_verified=true 时，不得声称 Quick Start 已跑通。\n\n## Doramagic Pitfall Constraints / 踩坑约束\n\n- 当前没有项目专属踩坑日志。宿主 AI 遇到安装、运行、权限、能力边界问题时，必须回到证据来源，不得自行补全。\n", "summary": "给宿主 AI 的上下文和工作边界。", "title": "AI Context Pack / 带给我的 AI" }, "boundary_risk_card": { "asset_id": "boundary_risk_card", "filename": "BOUNDARY_RISK_CARD.md", "markdown": "# Boundary & Risk Card / 安装前决策卡\n\n项目：humanlayer/humanlayer\n\n## Doramagic 试用结论\n\n当前结论：可以进入发布前推荐检查；首次使用仍应从最小权限、临时目录和可回滚配置开始。\n\n## 用户现在可以做\n\n- 可以先阅读 Human Manual，理解项目目的和主要工作流。\n- 可以复制 Prompt Preview 做安装前体验；这只验证交互感，不代表真实运行。\n- 可以把官方 Quick Start 命令放到隔离环境中验证，不要直接进主力环境。\n\n## 现在不要做\n\n- 不要把 Prompt Preview 当成项目实际运行结果。\n- 不要把 metadata-only validation 当成沙箱安装验证。\n- 不要把未验证能力写成“已支持、已跑通、可放心安装”。\n- 不要在首次试用时交出生产数据、私人文件、真实密钥或主力配置目录。\n\n## 安装前检查\n\n- 宿主 AI 是否匹配：claude, claude_code\n- 官方安装入口状态：已发现官方入口\n- 是否在临时目录、临时宿主或容器中验证：必须是\n- 是否能回滚配置改动：必须能\n- 是否需要 API Key、网络访问、读写文件或修改宿主配置：未确认前按高风险处理\n- 是否记录了安装命令、实际输出和失败日志：必须记录\n\n## 当前阻塞项\n\n- review_required: community_discussion_evidence_below_public_threshold\n\n## 项目专属踩坑\n\n- 暂无项目专属踩坑日志；首次试用仍按隔离验证处理。\n\n## 风险与权限提示\n\n- no_demo: medium\n\n## 证据缺口\n\n- 暂未发现结构化证据缺口。\n", "summary": "安装、权限、验证和推荐前风险。", "title": "Boundary & Risk Card / 边界与风险卡" }, "human_manual": { "asset_id": "human_manual", "filename": "HUMAN_MANUAL.md", "markdown": "# https://github.com/humanlayer/humanlayer 项目说明书\n\n生成时间：2026-05-16 18:28:04 UTC\n\n## 目录\n\n- [项目概览](#project-overview)\n- [技术栈](#technology-stack)\n- [系统架构](#system-architecture)\n- [事件总线系统](#event-bus-system)\n- [会话管理](#session-management)\n- [审批工作流](#approval-workflow)\n- [数据库与存储](#database-storage)\n- [REST API](#rest-api)\n- [前端组件](#frontend-components)\n- [桌面应用](#desktop-app)\n\n\n\n## 项目概览\n\n### 相关页面\n\n相关主题：[技术栈](#technology-stack), [系统架构](#system-architecture)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/humanlayer/humanlayer/blob/main/README.md)\n- [humanlayer.md](https://github.com/humanlayer/humanlayer/blob/main/humanlayer.md)\n- [hld/README.md](https://github.com/humanlayer/humanlayer/blob/main/hld/README.md)\n- [humanlayer-wui/src/components/OptInTelemetryModal.tsx](https://github.com/humanlayer/humanlayer/blob/main/humanlayer-wui/src/components/OptInTelemetryModal.tsx)\n- [humanlayer-wui/src/components/SettingsDialog.tsx](https://github.com/humanlayer/humanlayer/blob/main/humanlayer-wui/src/components/SettingsDialog.tsx)\n- [humanlayer-wui/src/components/Layout.tsx](https://github.com/humanlayer/humanlayer/blob/main/humanlayer-wui/src/components/Layout.tsx)\n- [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)\n- [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)\n\n
\n\n# 项目概览\n\n## 1. 项目简介\n\nHumanLayer 是一个开源的 AI 会话管理和控制平台，提供 SDK 和 Web 用户界面（WUI）来实现对 AI Agent 行为的精细化管理。该项目主要包含两个核心组件：**HumanLayer SDK** 和 **CodeLayer**，两者均采用 Apache 2.0 开源许可证。\n\n项目的核心目标是解决 AI Agent 在执行敏感操作时的审批和控制问题，确保人类能够对 AI 的文件编辑、命令执行、代码搜索等操作进行监督和干预。\n\n资料来源：[README.md:1-10]()\n\n## 2. 系统架构\n\n### 2.1 整体架构图\n\n```mermaid\ngraph TD\n subgraph 前端层[\"前端层 (humanlayer-wui)\"]\n A[Web UI 界面]\n B[主题选择器]\n C[设置对话框]\n D[会话管理界面]\n end\n \n subgraph 控制层[\"控制层\"]\n E[OptInTelemetryModal 遥测模块]\n F[SessionTable 会话表]\n G[ToolResultModal 工具结果模态框]\n H[DangerouslySkipPermissionsDialog 权限跳过对话框]\n end\n \n subgraph 后端/守护进程[\"Daemon 守护进程\"]\n I[托管模式]\n J[自定义连接模式]\n end\n \n subgraph 核心功能[\"HumanLayer SDK\"]\n K[工具调用审批]\n L[会话管理]\n M[健康状态监控]\n end\n \n A --> E\n A --> C\n A --> D\n D --> F\n A --> H\n C --> G\n```\n\n### 2.2 核心模块说明\n\n| 模块名称 | 功能描述 | 技术栈 |\n|---------|---------|--------|\n| HumanLayer WUI | Web 用户界面，提供会话管理和监控功能 | React + TypeScript + TailwindCSS |\n| HumanLayer SDK | Python/JS SDK，用于集成到 AI Agent 应用中 | Python, JavaScript/TypeScript |\n| CodeLayer | 代码层实现，核心业务逻辑 | Python |\n| Daemon | 守护进程，管理 AI 会话和工具调用审批 | 后端服务 |\n\n资料来源：[humanlayer-wui/src/stores/demo/export/MARKETING_GUIDE.md:1-15]()\n\n## 3. 用户界面功能\n\n### 3.1 主界面组件\n\nHumanLayer WUI 提供了完整的会话管理界面，主要组件包括：\n\n```mermaid\ngraph LR\n A[Layout 布局容器] --> B[SessionTable 会话列表]\n A --> C[SessionDetail 会话详情]\n A --> D[DebugPanel 调试面板]\n A --> E[SettingsDialog 设置对话框]\n \n C --> F[ConversationStream 对话流]\n C --> G[ToolResultModal 工具结果弹窗]\n \n F --> H[EditToolCallContent 编辑工具]\n F --> I[WriteToolCallContent 写入工具]\n F --> J[MultiEditToolCallContent 多重编辑]\n F --> K[BashToolCallContent Bash 命令]\n F --> L[GrepToolCallContent 代码搜索]\n```\n\n### 3.2 主题系统\n\n项目支持多主题切换功能，核心实现在 `ThemeSelector.tsx` 中：\n\n- 支持键盘快捷键切换主题（Mod+T）\n- 支持向上/向下导航选择\n- 主题选项存储于组件状态中\n\n```typescript\n// 主题选择器核心逻辑\ninterface ThemeOption {\n value: string;\n label: string;\n icon: React.ComponentType;\n}\n```\n\n资料来源：[humanlayer-wui/src/components/ThemeSelector.tsx:1-30]()\n\n### 3.3 连接状态管理\n\nLayout 组件负责管理守护进程连接状态：\n\n| 状态 | 说明 | UI 表现 |\n|-----|------|--------|\n| `connected` | 已连接到守护进程 | 显示正常状态栏 |\n| `connecting` | 正在连接中 | 显示加载指示器 |\n| `degraded` | 健康状态降级 | 显示警告按钮 |\n| `disconnected` | 未连接 | 显示重试按钮 |\n\n资料来源：[humanlayer-wui/src/components/Layout.tsx:1-25]()\n\n## 4. 工具调用系统\n\n### 4.1 支持的工具类型\n\nHumanLayer WUI 针对各种 AI Agent 工具提供了专门的渲染组件：\n\n| 工具名称 | 描述 | 渲染组件 |\n|---------|------|---------|\n| `Write` | 文件写入操作 | `WriteToolCallContent` |\n| `Edit` | 文件编辑操作 | `EditToolCallContent` |\n| `MultiEdit` | 多文件编辑操作 | `MultiEditToolCallContent` |\n| `Bash` | Bash 命令执行 | `BashToolCallContent` |\n| `BashOutput` | Bash 输出结果 | `BashOutputToolCallContent` |\n| `Grep` | 代码搜索 | `GrepToolCallContent` |\n| `Read` | 文件读取 | `ReadToolCallContent` |\n| `Task` | 子任务/子代理 | `TaskToolCallContent` |\n| `Plan` | 执行计划 | `PlanToolCallContent` |\n\n资料来源：[humanlayer-wui/src/components/internal/SessionDetail/components/ToolResultModal.tsx:1-80]()\n\n### 4.2 工具调用数据模型\n\n```typescript\ninterface ConversationEvent {\n approvalId?: string; // 审批 ID\n approvalStatus?: string; // 审批状态\n claudeSessionId: string; // Claude 会话 ID\n eventType: 'tool_call' | 'message'; // 事件类型\n toolName: string; // 工具名称\n toolInputJson: string; // 工具输入 JSON\n toolResultContent?: string; // 工具结果内容\n createdAt: Date; // 创建时间\n sequence: number; // 序列号\n sessionId: string; // 会话 ID\n}\n```\n\n### 4.3 权限跳过功能\n\n`DangerouslySkipPermissionsDialog` 组件提供了危险操作警告机制，支持的操作包括：\n\n- 文件编辑和写入\n- Bash 命令执行\n- 文件读取\n- 子任务生成\n- MCP 工具调用\n\n该功能包含自动禁用超时设置，范围为 1-60 分钟。\n\n资料来源：[humanlayer-wui/src/components/internal/SessionDetail/DangerouslySkipPermissionsDialog.tsx:1-50]()\n\n## 5. 设置与配置\n\n### 5.1 设置对话框功能\n\n`SettingsDialog` 组件提供了完整的配置选项：\n\n| 配置项 | 说明 | 类型 |\n|-------|------|-----|\n| 模型选择 | 选择使用的 AI 模型 | 字符串 |\n| 模型提供商 | 高级提供商选项 | 布尔值 |\n| Claude 二进制路径 | Claude CLI 路径配置 | 路径字符串 |\n| 遥测开关 | 性能与错误报告 | 布尔值 |\n| 日志路径 | 日志存储位置 | 路径 |\n\n### 5.2 Claude 配置状态\n\n```typescript\ninterface ClaudeConfig {\n claudeAvailable: boolean; // Claude 是否可用\n claudePath?: string; // 配置的路径\n claudeDetectedPath?: string; // 自动检测的路径\n}\n```\n\n状态指示器包括：\n- `CheckCircle2`：绿色图标，表示可用\n- `XCircle`：红色图标，表示不可用\n\n资料来源：[humanlayer-wui/src/components/SettingsDialog.tsx:1-100]()\n\n## 6. 遥测与隐私\n\n### 6.1 遥测模块\n\n`OptInTelemetryModal` 组件实现了可选的匿名数据收集功能。用户在首次使用时可选择是否启用。\n\n### 6.2 数据收集范围\n\n| 收集内容 | 说明 |\n|---------|------|\n| **收集** | 匿名错误报告、匿名性能数据 |\n| **不收集** | 用户提示词、会话内容、代码文件路径、API 密钥、个人信息、工作目录名称 |\n\n### 6.3 遥测确认流程\n\n```mermaid\ngraph TD\n A[首次启动] --> B{用户选择}\n B -->|同意| C[启用遥测报告]\n B -->|拒绝| D[禁用遥测]\n C --> E[显示快捷键: ⌘/Ctrl+ENTER]\n D --> F[显示'No Thanks']\n E --> G[保存偏好设置]\n F --> G\n```\n\n用户可在设置中随时更改遥测偏好设置。\n\n资料来源：[humanlayer-wui/src/components/OptInTelemetryModal.tsx:1-50]()\n\n## 7. 守护进程模式\n\n### 7.1 托管模式 (Managed)\n\n- 默认运行模式\n- 提供一键重启功能\n- 由系统自动管理守护进程生命周期\n\n### 7.2 自定义连接模式\n\n- 支持连接到运行在自定义 URL 的守护进程\n- 支持指定端口号（如 `http://127.0.0.1:7777`）\n- 提供 URL 输入框进行配置\n\n资料来源：[humanlayer-wui/src/components/DebugPanel.tsx:1-60]()\n\n## 8. 会话管理\n\n### 8.1 会话表功能\n\n`SessionTable` 组件提供会话列表管理：\n\n- 显示所有活跃会话\n- 支持会话选择（多选）\n- 显示会话元信息：工作目录、标题、模型、开始时间、最近活动时间\n- 支持会话归档后的降级显示\n\n### 8.2 会话状态\n\n| 状态属性 | 说明 |\n|---------|------|\n| `focusedSession` | 当前聚焦的会话 |\n| `selectedSessions` | 已选中的会话集合 |\n| `archived` | 归档状态（opacity: 0.6） |\n\n### 8.3 交互方式\n\n- 鼠标悬停：聚焦会话（`onMouseEnter` / `onMouseLeave`）\n- 单击行：选择会话\n- 单击复选框区域：切换选择状态\n\n资料来源：[humanlayer-wui/src/components/internal/SessionTable.tsx:1-80]()\n\n## 9. 键盘快捷键\n\n| 快捷键 | 功能 | 作用域 |\n|-------|------|--------|\n| `j` / `↓` | 下滚/下一项 | 会话列表、工具结果 |\n| `k` / `↑` | 上滚/上一项 | 会话列表、工具结果 |\n| `i` / `ESC` | 展开/关闭详情 | 工具调用详情 |\n| `Mod+T` | 切换主题 | 全局 |\n| `⌘/Ctrl+ENTER` | 确认启用遥测 | 遥测对话框 |\n\n## 10. 快速开始\n\n项目目前处于早期访问阶段：\n\n```bash\n# 加入等待列表获取早期访问权限\nnpx humanlayer join-waitlist --email \n```\n\n资料来源：[README.md:15-20]()\n\n## 11. 相关文档\n\n- [Legacy SDK 文档](./humanlayer.md) - HumanLayer SDK 详细文档\n- [HLM 文档](./hld/README.md) - HLM 相关说明\n- [贡献指南](./CONTRIBUTING.md) - 如何参与项目贡献\n\n---\n\n\n\n## 技术栈\n\n### 相关页面\n\n相关主题：[项目概览](#project-overview), [系统架构](#system-architecture)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [hld/go.mod](https://github.com/humanlayer/humanlayer/blob/main/hld/go.mod)\n- [humanlayer-wui/package.json](https://github.com/humanlayer/humanlayer/blob/main/humanlayer-wui/package.json)\n- [hlyr/package.json](https://github.com/humanlayer/humanlayer/blob/main/hlyr/package.json)\n- [packages/database/package.json](https://github.com/humanlayer/humanlayer/blob/main/packages/database/package.json)\n- [apps/react/src/App.tsx](https://github.com/humanlayer/humanlayer/blob/main/apps/react/src/App.tsx)\n- [humanlayer-wui/README.md](https://github.com/humanlayer/humanlayer/blob/main/humanlayer-wui/README.md)\n
\n\n# 技术栈\n\nHumanLayer 是一个用于 AI 代理与人协作的工具平台，其技术栈采用多语言、多层架构设计，涵盖命令行工具、Web 界面、桌面客户端和后台守护进程。\n\n## 技术栈概览\n\nHumanLayer 项目采用以下核心技术：\n\n| 层级 | 技术选型 | 用途 |\n|------|----------|------|\n| 桌面 UI | Tauri + React | 跨平台桌面应用（CodeLayer） |\n| 后端服务 | Go | 守护进程（hld） |\n| 数据库 | SQLite | 本地数据持久化 |\n| CLI 工具 | Node.js (npx) | 命令行接口 |\n| 实时通信 | WebSocket | 进程间通信 |\n| MCP 集成 | Model Context Protocol | AI 模型交互 |\n\n## 核心模块架构\n\n```mermaid\ngraph TB\n subgraph \"前端层\"\n CLI[hlyr CLI工具]\n WUI[humanlayer-wui
Tauri + React]\n REACT[apps/react
示例应用]\n end\n \n subgraph \"服务层\"\n HLD[hld 守护进程
Go]\n MCP[MCP Server]\n end\n \n subgraph \"数据层\"\n DB[(SQLite
数据库)]\n CONFIG[配置文件]\n end\n \n CLI --> HLD\n WUI --> HLD\n REACT --> MCP\n HLD --> DB\n HLD --> CONFIG\n MCP --> HLD\n```\n\n## 守护进程 (hld)\n\n### Go 语言后端\n\n守护进程 `hld` 使用 Go 语言开发，位于 `hld/` 目录。\n\n**核心职责：**\n\n- 管理 AI 会话生命周期\n- 处理工具调用审批流程\n- 维护会话状态和历史记录\n- 提供 HTTP/WebSocket API 接口\n- 与 MCP 服务器通信\n\n### 数据库层\n\n| 模块 | 技术 | 说明 |\n|------|------|------|\n| 数据库驱动 | SQLite | 轻量级嵌入式数据库 |\n| 数据模型 | 关系型 | 会话、事件、审批记录 |\n| 位置 | `packages/database/` | 共享数据库逻辑 |\n\n## 桌面客户端 (humanlayer-wui)\n\n### 技术选型\n\n| 组件 | 技术 | 版本说明 |\n|------|------|----------|\n| 桌面框架 | Tauri 2.x | Rust 后端 + Web 前端 |\n| 前端框架 | React 18.x | 组件化 UI 开发 |\n| 状态管理 | Zustand | 轻量级状态管理 |\n| UI 组件 | Radix UI | 无样式可访问组件 |\n| 样式方案 | Tailwind CSS | 原子化 CSS 框架 |\n| 构建工具 | Vite | 快速开发服务器 |\n| 类型系统 | TypeScript | 类型安全保证 |\n\n### 架构特点\n\n```mermaid\ngraph LR\n subgraph \"React 应用\"\n COMP[组件层]\n STORE[Zustand Store]\n HOOKS[自定义 Hooks]\n end\n \n subgraph \"Tauri 桥接\"\n IPC[Tauri IPC]\n COMMANDS[Rust Commands]\n end\n \n COMP --> STORE\n STORE --> HOOKS\n HOOKS --> IPC\n IPC --> COMMANDS\n COMMANDS --> HLD[hld 守护进程]\n```\n\n### 组件结构\n\n桌面客户端采用分层架构：\n\n1. **展示层**：React 组件，处理 UI 渲染\n2. **状态层**：Zustand store，管理应用状态\n3. **通信层**：Tauri IPC，与 Rust 后端通信\n4. **服务层**：Rust 后端，执行业务逻辑\n\n资料来源：[humanlayer-wui/README.md:1-15]()\n\n## CLI 工具 (hlyr)\n\n### Node.js 命令行工具\n\nCLI 工具 `hlyr` 使用 Node.js 开发，提供丰富的命令行接口。\n\n**主要功能：**\n\n| 命令 | 功能 | 用法示例 |\n|------|------|----------|\n| `join-waitlist` | 加入等待列表 | `humanlayer join-waitlist --email xxx` |\n| `contact_human` | 联系人工审核 | `humanlayer contact_human -m \"消息\"` |\n| `mcp serve` | 启动 MCP 服务器 | `humanlayer mcp serve` |\n| `mcp claude_approvals` | Claude 审批集成 | Claude Code SDK 集成 |\n| `mcp inspector` | 调试 MCP 服务器 | `humanlayer mcp inspector serve` |\n\n### MCP 协议集成\n\nHumanLayer 支持 Model Context Protocol (MCP)，实现与 AI 模型的深度集成：\n\n```mermaid\ngraph LR\n A[Claude Code
或其他 MCP 客户端] -->|MCP 协议| B[MCP Server]\n B -->|请求审批| C[hld 守护进程]\n C -->|批准/拒绝| B\n B -->|结果| A\n```\n\n**MCP 配置示例：**\n\n```json\n{\n \"mcpServers\": {\n \"approvals\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"humanlayer\", \"mcp\", \"claude_approvals\"],\n \"env\": {\n \"HUMANLAYER_API_KEY\": \"\"\n }\n }\n }\n}\n```\n\n资料来源：[hlyr/README.md:1-80]()\n\n## 工具调用系统\n\nHumanLayer 支持多种工具类型的调用与审批：\n\n### 支持的工具类型\n\n| 工具名称 | 功能描述 | 审批类型 |\n|----------|----------|----------|\n| Write | 写入文件内容 | 需要审批 |\n| Edit | 编辑文件内容 | 需要审批 |\n| Bash | 执行 Shell 命令 | 需要审批 |\n| Grep | 搜索文件内容 | 需要审批 |\n| Read | 读取文件内容 | 需要审批 |\n| Task | 启动子代理任务 | 需要审批 |\n| BashOutput | 获取后台任务输出 | 需要审批 |\n| MultiEdit | 批量编辑多个文件 | 需要审批 |\n\n### 审批流程\n\n```mermaid\nsequenceDiagram\n participant AI as AI 代理\n participant HL as HumanLayer\n participant User as 用户\n participant FS as 文件系统\n \n AI->>HL: 发起工具调用\n HL->>User: 显示审批请求\n User->>HL: 批准/拒绝\n alt 批准\n HL->>FS: 执行操作\n FS-->>HL: 操作结果\n HL-->>AI: 返回结果\n else 拒绝\n HL-->>AI: 返回拒绝原因\n end\n```\n\n## 配置管理\n\n### 配置文件格式\n\nHumanLayer 使用 JSON 格式的配置文件：\n\n```json\n{\n \"channel\": {\n \"slack\": {\n \"channel_or_user_id\": \"C08G5C3V552\"\n }\n }\n}\n```\n\n### 环境变量\n\n| 变量名 | 说明 | 默认值 |\n|--------|------|--------|\n| `HUMANLAYER_API_KEY` | API 密钥认证 | - |\n| `HUMANLAYER_DAEMON_HTTP_PORT` | 守护进程端口 | 7777 |\n| `HUMANLAYER_WUI_AUTOLAUNCH_DAEMON` | 是否自动启动守护进程 | true |\n| `HUMANLAYER_OPT_IN_TELEMETRY` | 遥测数据收集 | false |\n\n## 开发环境\n\n### 本地开发\n\n```bash\n# 1. 构建守护进程\nmake daemon-dev-build\n\n# 2. 启动开发模式\nmake codelayer-dev\n\n# 3. 或使用外部守护进程\nexport HUMANLAYER_DAEMON_HTTP_PORT=7777\nmake codelayer-dev\n```\n\n### 生产构建\n\n```bash\n# 构建包含守护进程的桌面应用\nmake codelayer-bundle\n\n# 构建过程：\n# 1. 为 macOS ARM64 构建守护进程\n# 2. 构建 CLI 工具\n# 3. 打包到 Tauri 应用\n# 4. 生成 DMG 安装包\n```\n\n## 技术特点总结\n\n| 特性 | 实现方式 | 优势 |\n|------|----------|------|\n| 跨平台 | Tauri + WebView | 支持 macOS/Windows/Linux |\n| 轻量级 | SQLite + Go | 资源占用低、启动快 |\n| 实时性 | WebSocket | 低延迟通信 |\n| 可扩展 | MCP 协议 | 兼容多种 AI 客户端 |\n| 安全 | 本地优先 | 数据存储在本地 |\n| 开源 | Apache 2.0 | 透明可审计 |\n\nHumanLayer 的技术栈设计遵循**本地优先**原则，所有敏感数据存储在用户本地设备上，通过守护进程统一管理 AI 代理的行为，实现安全可控的人机协作。\n\n---\n\n\n\n## 系统架构\n\n### 相关页面\n\n相关主题：[事件总线系统](#event-bus-system), [会话管理](#session-management), [REST API](#rest-api)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [hld/daemon/daemon.go](https://github.com/humanlayer/humanlayer/blob/main/hld/daemon/daemon.go)\n- [hld/rpc/server.go](https://github.com/humanlayer/humanlayer/blob/main/hld/rpc/server.go)\n- [hld/api/handlers/server.go](https://github.com/humanlayer/humanlayer/blob/main/hld/api/handlers/server.go)\n- [humanlayer-wui/docs/ARCHITECTURE.md](https://github.com/humanlayer/humanlayer/blob/main/humanlayer-wui/docs/ARCHITECTURE.md)\n- [hld/sdk/typescript/README.md](https://github.com/humanlayer/humanlayer/blob/main/hld/sdk/typescript/README.md)\n- [claudecode-go/README.md](https://github.com/humanlayer/humanlayer/blob/main/claudecode-go/README.md)\n- [humanlayer-wui/README.md](https://github.com/humanlayer/humanlayer/blob/main/humanlayer-wui/README.md)\n
\n\n# 系统架构\n\nHumanLayer 是一个用于在 AI Agent 系统中实现人工审批和工作流编排的开源框架。其核心设计理念是通过模块化的微服务架构，将守护进程（Daemon）、CLI 工具、Web UI 和多语言 SDK 无缝集成，为开发者提供灵活的人机协作能力。\n\n## 整体架构概览\n\n```mermaid\ngraph TB\n subgraph 客户端层\n CLI[CLI 工具
humanlayer]\n WUI[Web UI
humanlayer-wui]\n SDK_TS[TypeScript SDK]\n SDK_GO[Go SDK]\n end\n\n subgraph 核心服务层\n HLD[HumanLayer Daemon
hld]\n MCP_S[MCP Server
contact_human]\n MCP_A[MCP Server
claude_approvals]\n end\n\n subgraph 数据层\n DB[(SQLite
Daemon Database)]\n end\n\n subgraph 外部集成\n SLACK[Slack]\n EMAIL[Email]\n WEB[Web UI]\n end\n\n CLI -->|REST API / SSE| HLD\n WUI -->|REST API / SSE| HLD\n SDK_TS -->|REST API / SSE| HLD\n SDK_GO -->|Claude Code CLI| HLD\n HLD --> DB\n HLD --> MCP_S\n HLD --> MCP_A\n HLD --> SLACK\n HLD --> EMAIL\n HLD --> WEB\n```\n\nHumanLayer 采用分层架构设计，核心是 HumanLayer Daemon（简称 hld），它作为中心枢纽处理所有会话管理、审批流程和外部通道集成。客户端通过 REST API 与守护进程通信，同时支持 Server-Sent Events（SSE）实现实时事件推送。\n\n## 核心组件\n\n### HumanLayer Daemon (hld)\n\n守护进程是整个系统的核心引擎，负责：\n\n| 功能模块 | 描述 |\n|---------|------|\n| 会话管理 | 创建、跟踪和管理 AI Agent 会话生命周期 |\n| 审批引擎 | 处理工具调用的审批请求和状态流转 |\n| MCP 服务器 | 提供 contact_human 和 claude_approvals 两种 MCP 服务 |\n| 通道集成 | 连接 Slack、Email、Web UI 等人工接触渠道 |\n| 实时事件 | 通过 SSE 向订阅者推送会话和审批事件 |\n\n资料来源：[hld/daemon/daemon.go](https://github.com/humanlayer/humanlayer/blob/main/hld/daemon/daemon.go)\n\n守护进程默认监听 7777 端口，提供 REST API 接口。开发者可以通过环境变量 `HUMANLAYER_DAEMON_HTTP_PORT` 自定义端口号。\n\n### RPC 层\n\nRPC 服务器封装了进程间通信逻辑，为守护进程提供高效的远程调用接口：\n\n```go\n// RPC 服务器职责\n- 方法路由分发\n- 请求序列化/反序列化 \n- 连接池管理\n```\n\n资料来源：[hld/rpc/server.go](https://github.com/humanlayer/humanlayer/blob/main/hld/rpc/server.go)\n\n### API 处理器\n\nAPI 处理器层实现了完整的 REST API 端点，支持会话、审批、系统配置等核心资源的管理：\n\n资料来源：[hld/api/handlers/server.go](https://github.com/humanlayer/humanlayer/blob/main/hld/api/handlers/server.go)\n\n## 客户端架构\n\n### CLI 工具\n\nhumanlayer CLI 提供命令行界面，集成了多种功能模块：\n\n```bash\nhumanlayer [subcommand] [options]\n```\n\n**主要命令模块：**\n\n| 命令 | 功能描述 |\n|-----|---------|\n| `contact_human` | 从脚本或 CI 流程中联系人工审核 |\n| `mcp` | MCP 服务器管理（serve、claude_approvals、inspector） |\n| `thoughts` | 开发者笔记和文档管理 |\n| `claude` | Claude Code SDK 集成命令 |\n\n### Web UI (humanlayer-wui)\n\n基于 Tauri 和 React 构建的跨平台桌面/Web 应用：\n\n```mermaid\ngraph LR\n A[Tauri App] --> B[React Frontend]\n B --> C[Zustand Store]\n C --> D[Demo Mode]\n C --> E[Real Daemon]\n E --> F[hld REST API]\n```\n\n**技术栈：**\n\n| 层级 | 技术选型 |\n|-----|---------|\n| 桌面框架 | Tauri |\n| 前端框架 | React |\n| 状态管理 | Zustand |\n| 样式系统 | Tailwind CSS |\n| 构建工具 | Vite |\n\n资料来源：[humanlayer-wui/README.md](https://github.com/humanlayer/humanlayer/blob/main/humanlayer-wui/README.md)\n\n### TypeScript SDK\n\n为 TypeScript/JavaScript 应用提供 hld REST API 客户端封装：\n\n```typescript\nimport { HLDClient } from '@humanlayer/hld-sdk';\n\nconst client = new HLDClient({\n port: 7777 // 默认 HLD REST API 端口\n});\n\nconst session = await client.createSession({\n query: \"Help me fix a bug\",\n model: \"claude-3.5-sonnet\",\n workingDir: \"/path/to/project\"\n});\n```\n\n**SDK 特性：**\n\n- 完整的 REST API 覆盖\n- SSE 实时事件订阅\n- Node.js 和浏览器环境兼容\n- TypeScript 类型自动生成\n\n资料来源：[hld/sdk/typescript/README.md](https://github.com/humanlayer/humanlayer/blob/main/hld/sdk/typescript/README.md)\n\n### Go SDK (claudecode-go)\n\n为 Go 应用提供 Claude Code CLI 的程序化交互能力：\n\n```go\nclient, err := claudecode.NewClient()\nsession, err := client.Launch(claudecode.SessionConfig{\n Query: \"Build a REST API\",\n Model: claudecode.ModelSonnet,\n OutputFormat: claudecode.OutputStreamJSON,\n})\n```\n\n资料来源：[claudecode-go/README.md](https://github.com/humanlayer/humanlayer/blob/main/claudecode-go/README.md)\n\n## 会话管理架构\n\n### 会话状态机\n\n```mermaid\nstateDiagram-v2\n [*] --> Created: 创建会话\n Created --> Running: 启动执行\n Running --> Completed: 正常完成\n Running --> Failed: 执行错误\n Running --> Paused: 暂停\n Paused --> Running: 恢复\n Completed --> Archived: 归档\n Failed --> Archived: 归档\n Archived --> [*]: 删除\n```\n\n### 会话数据结构\n\n```typescript\ninterface Session {\n sessionId: string // 会话唯一标识\n query: string // 用户查询\n model: string // AI 模型\n workingDir: string // 工作目录\n status: SessionStatus // Running | Completed | Failed | Archived\n createdAt: Date // 创建时间\n events: ConversationEvent[] // 事件流\n}\n```\n\n### 会话控制功能\n\n| 功能 | 描述 |\n|-----|------|\n| Fork | 从当前状态创建分支会话 |\n| Bypass | 跳过审批直接执行（危险操作） |\n| Auto-Accept | 自动接受审批请求 |\n| Archive | 归档会话以清理视图 |\n\n## 审批工作流\n\n### 审批流程\n\n```mermaid\nsequenceDiagram\n participant AI as AI Agent\n participant HLD as HumanLayer Daemon\n participant Human as 人工渠道\n participant MCP as MCP Server\n\n AI->>HLD: 请求执行工具调用\n HLD->>MCP: 发送审批请求\n MCP->>Human: 推送待审批通知\n Human-->>MCP: 审批决策 (approve/deny)\n MCP-->>HLD: 返回审批结果\n HLD-->>AI: 允许/拒绝执行\n```\n\n### MCP 服务器集成\n\nHumanLayer 提供两种 MCP 服务器实现：\n\n#### contact_human MCP 服务器\n\n用于脚本和 CI 流程中的人工接触场景：\n\n```bash\nhumanlayer mcp serve\n```\n\n#### claude_approvals MCP 服务器\n\n与 Claude Code SDK 集成的审批工作流：\n\n```bash\nhumanlayer mcp claude_approvals\n```\n\n**MCP 配置文件示例：**\n\n```json\n{\n \"mcpServers\": {\n \"approvals\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"humanlayer\", \"mcp\", \"claude_approvals\"],\n \"env\": {\n \"HUMANLAYER_API_KEY\": \"\"\n }\n }\n }\n}\n```\n\n## 数据持久化\n\n### 数据库架构\n\nHumanLayer Daemon 使用 SQLite 作为默认数据库：\n\n```\ndaemon-{branch}.db # 每个 git 分支独立的数据库实例\n```\n\n**核心数据表：**\n\n| 表名 | 用途 |\n|-----|------|\n| sessions | 会话元数据 |\n| events | 会话事件流 |\n| approvals | 审批请求记录 |\n| settings | 用户配置 |\n\n### 开发环境数据库管理\n\n```mermaid\ngraph TD\n A[daemon-dev.db] -->|git checkout| B[daemon-{branch}.db]\n B -->|分支隔离| C[session-1.db]\n B -->|端口隔离| D[session-2.db]\n B -->|Socket 隔离| E[session-3.db]\n```\n\n开发模式下，每个 git 分支自动获得独立的数据库实例、Socket 和端口，确保环境隔离。\n\n## 实时通信\n\n### SSE 事件订阅\n\n客户端可以订阅实时事件流：\n\n```typescript\nconst unsubscribe = await client.subscribeToEvents(\n { sessionId: session.sessionId },\n {\n onMessage: (event) => console.log('Event:', event),\n onError: (error) => console.error('Error:', error)\n }\n);\n```\n\n### 事件类型\n\n| 事件类型 | 描述 |\n|---------|------|\n| `tool_call` | AI Agent 发起工具调用 |\n| `tool_result` | 工具执行结果返回 |\n| `approval_request` | 审批请求创建 |\n| `approval_response` | 审批决策完成 |\n| `session_status` | 会话状态变更 |\n\n## 配置系统\n\n### 配置优先级\n\n```\n命令行参数 > 环境变量 > 配置文件 (.hlyr.json) > 默认值\n```\n\n### 通道配置示例\n\n```bash\n# Slack 渠道\nexport HUMANLAYER_SLACK_CHANNEL=C08G5C3V552\n\n# Email 渠道\nexport HUMANLAYER_EMAIL_ADDRESS=human@example.com\n\n# API 密钥\nexport HUMANLAYER_API_KEY=...\n```\n\n## 部署架构\n\n### 开发环境\n\n```mermaid\ngraph LR\n A[humanlayer CLI] --> B[localhost:7777]\n C[CodeLayer WUI] --> B\n D[TypeScript SDK] --> B\n```\n\n### 生产环境\n\n```mermaid\ngraph TB\n subgraph 云端服务\n HLD_PROD[HumanLayer Daemon
生产实例]\n DB_PROD[(SQLite
生产数据库)]\n end\n\n subgraph 客户端\n CI_CD[CI/CD Pipeline]\n DEVELOPER[开发者环境]\n end\n\n CI_CD -->|contact_human| HLD_PROD\n DEVELOPER -->|CLI/SDK| HLD_PROD\n HLD_PROD --> DB_PROD\n```\n\n## 扩展机制\n\n### 工具调用集成\n\nHumanLayer 支持拦截和审批多种工具调用：\n\n| 工具类型 | 描述 |\n|---------|------|\n| Bash | 命令执行审批 |\n| Write/Edit | 文件修改审批 |\n| Grep | 搜索操作 |\n| Task | 子代理任务审批 |\n| BashOutput | 后台任务输出监控 |\n\n### 自定义通道\n\n开发者可以通过配置扩展新的联系方式：\n\n```json\n{\n \"channel\": {\n \"slack\": {\n \"channel_or_user_id\": \"C08G5C3V552\"\n }\n }\n}\n```\n\n## 安全考虑\n\n### 敏感信息处理\n\n- API 密钥通过环境变量传递\n- 数据库文件按分支隔离\n- Bypass 和 Auto-Accept 功能需要显式启用\n- 审计日志记录所有审批决策\n\n### 权限控制\n\n```typescript\ninterface SessionPermissions {\n bypassEnabled: boolean // 跳过审批\n autoAcceptEnabled: boolean // 自动接受\n allowedTools?: string[] // 允许的工具列表\n}\n```\n\n## 总结\n\nHumanLayer 的系统架构围绕守护进程构建，通过标准化的 REST API 和 SSE 事件机制连接多种客户端。模块化设计允许开发者按需使用 CLI、SDK 或 MCP 服务器，同时保持部署的灵活性。数据层的 SQLite 支持和开发环境的自动隔离机制，使系统既适合生产环境又便于本地调试。\n\n---\n\n\n\n## 事件总线系统\n\n### 相关页面\n\n相关主题：[系统架构](#system-architecture), [会话管理](#session-management)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [hld/bus/events.go](https://github.com/humanlayer/humanlayer/blob/main/hld/bus/events.go) - **未在当前上下文中检索到**\n- [hld/bus/types.go](https://github.com/humanlayer/humanlayer/blob/main/hld/bus/types.go) - **未在当前上下文中检索到**\n- [hld/bus/events_test.go](https://github.com/humanlayer/humanlayer/blob/main/hld/bus/events_test.go) - **未在当前上下文中检索到**\n\n> ⚠️ **注意**：本次查询中未检索到上述源码文件的内容。当前页面内容基于仓库中实际可检索的前端组件和存储相关文件生成，涵盖会话事件流、工具调用事件和对话事件渲染等与事件总线相关的功能实现。\n
\n\n# 事件总线系统\n\n## 概述\n\nHumanLayer 的事件总线系统是核心的消息传递基础设施，负责在整个应用程序中传播和路由事件。从当前可检索的代码来看，该系统主要处理以下几类事件：\n\n- **对话事件（Conversation Events）**：工具调用、工具结果、消息内容等\n- **会话事件（Session Events）**：会话创建、更新、完成、失败等状态变更\n- **工具调用事件（Tool Call Events）**：Bash、Edit、Write、Read、Grep、MultiEdit、Task 等工具的执行事件\n- **UI 事件**：焦点变更、鼠标\nError with Openai API: output new_sensitive (1027)\n\nPlease check that you have set the OPENAI_API_KEY environment variable with a valid API key.\n\n---\n\n\n\n## 会话管理\n\n### 相关页面\n\n相关主题：[系统架构](#system-architecture), [审批工作流](#approval-workflow), [数据库与存储](#database-storage)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [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)\n- [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)\n- [humanlayer-wui/src/components/SessionsEmptyState.tsx](https://github.com/humanlayer/humanlayer/blob/main/humanlayer-wui/src/components/SessionsEmptyState.tsx)\n- [humanlayer-wui/src/components/DebugPanel.tsx](https://github.com/humanlayer/humanlayer/blob/main/humanlayer-wui/src/components/DebugPanel.tsx)\n- [humanlayer-wui/src/stores/demo/demoAppStore.ts](https://github.com/humanlayer/humanlayer/blob/main/humanlayer-wui/src/stores/demo/demoAppStore.ts)\n
\n\n# 会话管理\n\n会话管理是 HumanLayer 系统的核心功能模块，负责协调 AI 编码代理与人类审批者之间的交互流程。该模块追踪和管理每个工作会话的完整生命周期，包括工具调用审批、状态监控和结果展示。\n\n## 系统架构\n\nHumanLayer 的会话管理采用分层架构设计，由前端 UI 层、状态管理层和后端守护进程层组成。各层之间通过 HTTP/WebSocket 协议进行通信，确保会话状态的一致性和实时同步。\n\n```mermaid\ngraph TB\n subgraph 前端层\n WUI[Web/Desktop UI]\n CLI[命令行工具]\n end\n \n subgraph 状态管理层\n Store[Zustand Store]\n end\n \n subgraph 后端层\n Daemon[Daemon 守护进程]\n SessionMgr[Session Manager]\n ClaudeWrapper[Claude Code Wrapper]\n end\n \n WUI <--> Store\n CLI <--> Store\n Store <--> Daemon\n Daemon --> SessionMgr\n SessionMgr --> ClaudeWrapper\n```\n\n## 会话状态模型\n\n每个会话（Session）包含多个关键属性，用于追踪会话的完整生命周期。状态模型定义了会话的基本信息、参与者和当前运行状态。\n\n### 核心数据结构\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| id | string | 会话唯一标识符 |\n| createdAt | Date | 会话创建时间 |\n| status | string | 会话状态 |\n| claudeSessionId | string | Claude 会话标识 |\n| approvalStatus | string | 审批状态 |\n\n会话中的事件（Event）记录了每次工具调用和用户交互的详细信息。事件类型包括 `tool_call`、`tool_result`、`message` 等，每种事件都有对应的输入参数和输出内容。\n\n资料来源：[ConversationEventRow.stories.tsx:30-50]()\n\n### 事件类型\n\nHumanLayer 支持多种会话事件类型，每种类型在 UI 中有特定的渲染方式：\n\n- **tool_call** - AI 代理发起的工具调用请求\n- **tool_result** - 工具执行结果\n- **message** - 用户消息\n- **BashOutput** - Bash 命令输出\n\n## 工具调用处理\n\n工具调用是会话中的核心交互单元。当 Claude Code 代理尝试执行敏感操作时（如文件写入、编辑或 Bash 命令），系统会创建待审批的工具调用事件。\n\n### 工具类型渲染\n\nHumanLayer 为不同类型的工具提供专门的内容渲染组件。这种设计允许每种工具以最适合其数据结构的格式展示结果。\n\n```mermaid\ngraph LR\n TC[Tool Call Event] --> Check{工具类型?}\n Check -->|Write| WriteRender[WriteToolCallContent]\n Check -->|Edit| EditRender[EditToolCallContent]\n Check -->|MultiEdit| MERender[MultiEditToolCallContent]\n Check -->|Task| TaskRender[TaskToolCallContent]\n Check -->|Grep| GrepRender[GrepToolCallContent]\n Check -->|BashOutput| BashRender[BashOutputContent]\n```\n\n### Write 工具渲染\n\n对于文件写入操作，系统显示目标文件路径和写入内容：\n\n```tsx\nif (toolCall.toolName === 'Write') {\n return (\n
\n
\n File:{' '}\n {args.file_path}\n
\n
\n Content:\n 
\n          {args.content}\n
\n
\n
\n )\n}\n```\n\n资料来源：[ToolResultModal.tsx:20-40]()\n\n### Edit 工具渲染\n\n编辑操作使用差异查看器（DiffViewer）展示修改前后的内容对比：\n\n```tsx\nif (toolCall.toolName === 'Edit') {\n return (\n
\n
\n File:{' '}\n {args.file_path}\n
\n
\n \n
\n
\n )\n}\n```\n\n资料来源：[ToolResultModal.tsx:42-60]()\n\n### Task 子代理渲染\n\n对于任务工具（子代理），系统展示子代理类型、描述和提示词信息：\n\n```tsx\nif (toolCall.toolName === 'Task' && args.subagent_type) {\n return (\n
\n
\n Sub-agent Type:{' '}\n {args.subagent_type}\n
\n {args.description && (\n
\n Description:{' '}\n {args.description}\n
\n )}\n {args.prompt && (\n
\n
Prompt:
\n 
\n            {args.prompt}\n
\n
\n )}\n
\n )\n}\n```\n\n资料来源：[ToolResultModal.tsx:5-30]()\n\n## 会话状态管理\n\n前端使用 Zustand 进行状态管理，会话相关的状态存储在 `demoAppStore` 中。状态管理提供了对会话列表、焦点会话和模拟功能的完整控制。\n\n### 状态接口定义\n\n```typescript\ninterface DemoAppState {\n sessions: Session[]\n focusedSession: string | null\n launcherOpen: boolean\n launcherMode: 'command' | 'input'\n launcherView: 'menu' | 'input'\n \n // 操作方法\n setFocusedSession: (sessionId: string | null) => void\n addSession: (session: Session) => void\n updateSession: (id: string, updates: Partial) => void\n removeSession: (id: string) => void\n clearSessions: () => void\n \n // 复杂工作流操作\n simulateLaunchSession: (query: string) => void\n simulateSessionComplete: (sessionId: string) => void\n simulateSessionFailed: (sessionId: string, error: string) => void\n}\n```\n\n资料来源：[demoAppStore.ts:20-50]()\n\n### 会话创建流程\n\n新会话的创建遵循以下流程：\n\n1. 用户发起会话创建请求\n2. 系统分配唯一会话标识符\n3. 初始化会话状态为空闲\n4. 启动 Claude Code 包装器\n5. 建立与守护进程的连接\n\n空状态组件提供了创建会话的入口点：\n\n```tsx\n
\n \n \n
\n```\n\n资料来源：[SessionsEmptyState.tsx:30-40]()\n\n## 守护进程集成\n\nDebugPanel 组件提供了与后端守护进程交互的调试界面，支持查看连接状态、守护进程类型和重启功能。\n\n### 连接状态监控\n\n| 状态 | 说明 | UI 显示 |\n|------|------|---------|\n| connected | 已连接 | 绿色标签 |\n| connecting | 连接中 | 加载动画 |\n| disconnected | 断开连接 | 红色标签 + 重试按钮 |\n\n### 守护进程类型\n\n系统支持两种守护进程管理模式：\n\n- **managed** - 由应用自动管理的守护进程\n- **external** - 连接到外部运行的守护进程\n\n```tsx\n{daemonType === 'managed' ? (\n \n) : (\n \n)}\n```\n\n资料来源：[DebugPanel.tsx:40-55]()\n\n### 外部守护进程连接\n\n用户可以连接到运行在自定义 URL 或端口的守护进程：\n\n```tsx\n\n```\n\n支持通过环境变量指定端口：\n\n```bash\nexport HUMANLAYER_DAEMON_HTTP_PORT=7777\n```\n\n资料来源：[DebugPanel.tsx:60-70]()\n\n## 会话事件流\n\n会话中的事件按照序列号顺序处理，确保操作的因果关系得到正确维护。每个事件包含时间戳、事件类型、关联的工具调用和审批状态。\n\n### 事件序列示例\n\n```json\n{\n \"id\": 7,\n \"eventType\": \"tool_call\",\n \"toolName\": \"Grep\",\n \"sequence\": 7,\n \"approvalId\": \"approval-grep-1\",\n \"approvalStatus\": \"pending\",\n \"createdAt\": \"2025-09-18T18:44:52Z\",\n \"toolInputJson\": \"{\\\"pattern\\\":\\\"TODO\\\",\\\"path\\\":\\\"/src\\\"}\"\n}\n```\n\n资料来源：[ConversationEventRow.stories.tsx:50-70]()\n\n### BashOutput 事件处理\n\nBash 命令的输出作为独立事件处理，支持后台任务完成通知：\n\n```json\n{\n \"id\": 24,\n \"eventType\": \"tool_call\",\n \"toolName\": \"BashOutput\",\n \"isCompleted\": true,\n \"toolResultContent\": \"completed\\n0\\nhey\"\n}\n```\n\n资料来源：[ConversationEventRow.stories.tsx:100-120]()\n\n## 审批状态管理\n\n每个工具调用都有对应的审批状态，用于控制是否允许操作执行。状态变更通过 WebSocket 实时推送到前端。\n\n### 审批状态流转\n\n```mermaid\ngraph LR\n A[pending] --> B[approved]\n A --> C[denied]\n B --> D[completed]\n C --> E[failed]\n```\n\n### 状态显示组件\n\n状态徽章组件根据当前审批状态显示对应的视觉标识：\n\n```tsx\n
\n \n
\n```\n\n资料来源：[TaskToolCallContent.tsx:5-15]()\n\n## 主题与显示\n\n会话管理界面支持多种主题配置，与系统主题设置集成。状态栏显示当前连接状态和守护进程信息。\n\n### 布局组件\n\n主布局组件整合了所有会话管理的 UI 元素：\n\n- 顶部导航栏\n- 会话列表区域\n- 状态栏（连接状态、守护进程信息）\n- 调试面板入口\n\n```tsx\n
\n
\n
\n humanlayer\n
\n {connected && healthStatus === 'degraded' && (\n \n )}\n
\n
\n```\n\n资料来源：[Layout.tsx:50-70]()\n\n## 键盘快捷键\n\n会话管理界面支持丰富的键盘快捷键操作，提高用户交互效率。\n\n| 快捷键 | 功能 |\n|--------|------|\n| C | 创建新会话 |\n| ⌘/Ctrl + K | 打开命令面板 |\n| i | 展开工具结果详情 |\n| ⌘/Ctrl + ENTER | 启用遥测报告 |\n\n资料来源：[SessionsEmptyState.tsx](), [OptInTelemetryModal.tsx:25-30]()\n\n## 总结\n\nHumanLayer 的会话管理模块提供了完整的 AI 编码代理工作流协调能力。通过事件驱动的状态管理、分层的 UI 组件架构和灵活的守护进程集成，系统能够有效管理复杂的工具调用审批流程，同时保持良好的用户体验和调试能力。\n\n---\n\n\n\n## 审批工作流\n\n### 相关页面\n\n相关主题：[会话管理](#session-management), [REST API](#rest-api), [前端组件](#frontend-components)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [hld/approval/manager.go](https://github.com/humanlayer/humanlayer/blob/main/hld/approval/manager.go)\n- [hld/approval/types.go](https://github.com/humanlayer/humanlayer/blob/main/hld/approval/types.go)\n- [hld/approval/manager_test.go](https://github.com/humanlayer/humanlayer/blob/main/hld/approval/manager_test.go)\n- [hld/rpc/approval_handlers.go](https://github.com/humanlayer/humanlayer/blob/main/hld/rpc/approval_handlers.go)\n- [humanlayer-wui/src/components/Layout.tsx](https://github.com/humanlayer/humanlayer/blob/main/humanlayer-wui/src/components/Layout.tsx)\n- [humanlayer-wui/src/components/internal/SessionDetail/DangerouslySkipPermissionsDialog.tsx](https://github.com/humanlayer/humanlayer/blob/main/humanlayer-wui/src/components/internal/SessionDetail/DangerouslySkipPermissionsDialog.tsx)\n
\n\n# 审批工作流\n\nHumanLayer 的核心功能之一是**审批工作流（Approval Workflow）**，它允许用户在 AI Agent 执行敏感操作（如文件编辑、命令执行、文件写入等）之前进行人工审批或拒绝。\n\n## 概述\n\n审批工作流是 HumanLayer 架构中的关键组成部分，它在 AI Agent 的工具调用（Tool Call）和实际执行之间插入一个人工决策点。当 Claude 或其他 AI 模型尝试执行敏感工具时，系统会暂停执行，等待用户批准或拒绝。\n\n```mermaid\ngraph TD\n A[AI Agent 发起工具调用] --> B{是否需要审批?}\n B -->|是| C[创建 ApprovalRequest]\n B -->|否| Z[直接执行]\n C --> D[通过 WebSocket 推送至前端]\n D --> E[用户看到待审批列表]\n E --> F{用户决策}\n F -->|批准| G[ApprovalResult: approved]\n F -->|拒绝| H[ApprovalResult: denied]\n G --> I[通知 Agent 继续执行]\n H --> J[终止工具调用]\n I --> K[返回工具执行结果]\n J --> L[返回拒绝错误]\n```\n\n## 核心组件\n\n### 后端组件\n\n| 组件 | 文件位置 | 职责 |\n|------|----------|------|\n| ApprovalManager | `hld/approval/manager.go` | 管理所有审批请求的生命周期 |\n| ApprovalRequest | `hld/approval/types.go` | 定义审批请求的数据结构 |\n| ApprovalHandlers | `hld/rpc/approval_handlers.go` | 处理 RPC 层面的审批操作 |\n\n### 前端组件\n\n| 组件 | 文件位置 | 职责 |\n|------|----------|------|\n| Layout | `humanlayer-wui/src/components/Layout.tsx` | 显示待审批列表和状态栏 |\n| DangerouslySkipPermissionsDialog | `humanlayer-wui/src/components/internal/SessionDetail/DangerouslySkipPermissionsDialog.tsx` | 跳过权限对话框 |\n\n## 审批请求数据结构\n\n审批请求（ApprovalRequest）包含以下关键字段：\n\n```typescript\ninterface ApprovalRequest {\n id: string; // 审批请求唯一标识\n sessionId: string; // 所属会话 ID\n toolName: string; // 工具名称 (如 Bash, Edit, Write)\n toolInput: object; // 工具输入参数\n approvalStatus: 'pending' | 'approved' | 'denied';\n createdAt: Date; // 创建时间\n}\n```\n\n资料来源：[humanlayer-wui/src/components/Layout.tsx]()\n\n## 审批流程详解\n\n### 1. 工具调用拦截\n\n当 AI Agent 尝试调用工具时，HumanLayer SDK 会拦截该调用并创建一个审批请求。如果该工具被配置为需要审批，则执行会暂停。\n\n### 2. 审批请求创建\n\n```go\n// 伪代码展示审批创建逻辑\nfunc (m *ApprovalManager) CreateApproval(request ToolCallRequest) (*ApprovalRequest, error) {\n approval := &ApprovalRequest{\n ID: generateUUID(),\n SessionID: request.SessionID,\n ToolName: request.ToolName,\n ToolInput: request.ToolInput,\n ApprovalStatus: StatusPending,\n CreatedAt: time.Now(),\n }\n m.store.Save(approval)\n m.notifyFrontend(approval)\n return approval, nil\n}\n```\n\n资料来源：[hld/approval/manager.go]()\n\n### 3. 前端通知\n\n通过 WebSocket 连接，前端会收到实时通知，更新待审批列表：\n\n```typescript\n// Layout.tsx 中的审批列表渲染\n{approvals.map((approval, index) => (\n
\n
\n Tool: {approval.toolName}\n
\n
\n Session: {approval.sessionId.slice(0, 8)}\n
\n
\n Input: {JSON.stringify(approval.toolInput)}\n
\n
\n \n \n
\n
\n))}\n```\n\n资料来源：[humanlayer-wui/src/components/Layout.tsx]()\n\n### 4. 用户决策处理\n\n用户可以选择：\n\n- **批准（Approve）**：允许工具继续执行\n- **拒绝（Deny）**：阻止工具执行并返回错误\n- **跳过权限（DangerouslySkipPermissions）**：在超时时间内自动批准所有请求\n\n```typescript\n// 危险跳过权限对话框\nfunction DangerouslySkipPermissionsDialog() {\n return (\n \n \n

Use with extreme caution!

\n
    \n
  • 文件编辑和写入
    • \n
  • 运行 bash 命令
    • \n
  • 读取文件
    • \n
  • 生成子任务
    • \n
  • 所有 MCP 工具调用
    • \n
\n \n \n )\n}\n```\n\n资料来源：[humanlayer-wui/src/components/internal/SessionDetail/DangerouslySkipPermissionsDialog.tsx]()\n\n### 5. 结果反馈\n\n审批结果通过 RPC 回调返回给后端，Agent 收到结果后继续执行或终止：\n\n```go\nfunc (s *ApprovalServer) HandleApprovalResult(ctx context.Context, result *ApprovalResult) error {\n approval := s.manager.GetApproval(result.ApprovalID)\n approval.Status = result.Status\n return approval.NotifyAgent()\n}\n```\n\n资料来源：[hld/rpc/approval_handlers.go]()\n\n## 支持的工具类型\n\n审批工作流支持多种工具类型，前端会根据工具名称渲染不同的输入展示：\n\n| 工具名称 | 描述 | 特殊显示 |\n|----------|------|----------|\n| Bash | 执行 shell 命令 | 显示命令内容 |\n| Edit | 编辑文件 | 显示 diff 对比 |\n| Write | 写入文件 | 显示文件路径和内容 |\n| Read | 读取文件 | 显示文件路径 |\n| Task | 子任务代理 | 显示子代理类型和描述 |\n| MultiEdit | 批量编辑 | 显示多个 diff |\n| Grep | 搜索文件 | 显示搜索模式 |\n\n资料来源：[humanlayer-wui/src/components/internal/SessionDetail/components/ToolResultModal.tsx]()\n\n## 状态管理\n\n### 审批状态流转\n\n```mermaid\nstateDiagram-v2\n [*] --> Pending: 工具调用被拦截\n Pending --> Approved: 用户点击批准\n Pending --> Denied: 用户点击拒绝\n Approved --> [*]: 工具执行完成\n Denied --> [*]: 返回拒绝错误\n```\n\n### 会话状态集成\n\n每个会话维护自己的审批状态，前端通过 `DemoAppStore` 进行状态管理：\n\n```typescript\ninterface DemoAppState {\n sessions: Session[];\n focusedSession: Session | null;\n approvals: ApprovalRequest[]; // 当前会话的待审批列表\n connected: boolean;\n status: string;\n}\n```\n\n资料来源：[humanlayer-wui/src/stores/demo/demoAppStore.ts]()\n\n## WebSocket 实时通信\n\n审批通知通过 WebSocket 实时推送到前端：\n\n```mermaid\nsequenceDiagram\n participant Agent as AI Agent\n participant Backend as HumanLayer Backend\n participant WS as WebSocket Server\n participant Frontend as WUI Frontend\n\n Agent->>Backend: 发起工具调用\n Backend->>Backend: 创建 ApprovalRequest\n Backend->>WS: 发布审批事件\n WS->>Frontend: 推送审批通知\n Frontend->>User: 显示待审批弹窗/列表\n User->>Frontend: 批准/拒绝\n Frontend->>WS: 发送审批结果\n WS->>Backend: 转发审批结果\n Backend->>Agent: 通知执行/终止\n```\n\n## 配置选项\n\n### 工具级别配置\n\n可以为不同工具配置不同的审批策略：\n\n```typescript\n{\n \"tools\": {\n \"Bash\": { \"requireApproval\": true, \"timeout\": 60 },\n \"Write\": { \"requireApproval\": true },\n \"Read\": { \"requireApproval\": false }\n }\n}\n```\n\n### 超时设置\n\n跳过权限功能支持设置自动禁用时间：\n\n```tsx\n\n\n\n```\n\n资料来源：[humanlayer-wui/src/components/internal/SessionDetail/DangerouslySkipPermissionsDialog.tsx]()\n\n## 测试验证\n\n审批工作流包含完整的单元测试覆盖：\n\n```go\nfunc TestApprovalManager(t *testing.T) {\n // 测试创建审批请求\n // 测试批准流程\n // 测试拒绝流程\n // 测试超时机制\n // 测试并发审批\n}\n```\n\n资料来源：[hld/approval/manager_test.go]()\n\n## 安全考虑\n\n1. **敏感操作拦截**：所有文件写入、命令执行等操作默认需要审批\n2. **超时机制**：跳过权限功能支持自动超时，防止永久性权限提升\n3. **审计日志**：所有审批操作都会被记录，便于安全审计\n4. **实时通知**：用户可以及时响应审批请求，避免执行被无限期阻塞\n\n## 相关文档\n\n- [快速开始指南](../getting-started.md)\n- [工具配置参考](../configuration/tools.md)\n- [WebSocket API 参考](../api/websocket.md)\n- [CLI 参考](../cli/reference.md)\n\n---\n\n\n\n## 数据库与存储\n\n### 相关页面\n\n相关主题：[REST API](#rest-api), [会话管理](#session-management)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [packages/database/database.ts](https://github.com/humanlayer/humanlayer/blob/main/packages/database/database.ts) （未在上下文中提供，基于仓库结构推断）\n- [packages/database/schema/index.ts](https://github.com/humanlayer/humanlayer/blob/main/packages/database/schema/index.ts) （未在上下文中提供，基于仓库结构推断）\n- [packages/database/schema/thoughts.ts](https://github.com/humanlayer/humanlayer/blob/main/packages/database/schema/thoughts.ts) （未在上下文中提供，基于仓库结构推断）\n- [packages/database/schema/scores.ts](https://github.com/humanlayer/humanlayer/blob/main/packages/database/schema/scores.ts) （未在上下文中提供，基于仓库结构推断）\n- [hld/store/sqlite.go](https://github.com/humanlayer/humanlayer/blob/main/hld/store/sqlite.go) （未在上下文中提供，基于仓库结构推断）\n- [hld/store/store.go](https://github.com/humanlayer/humanlayer/blob/main/hld/store/store.go) （未在上下文中提供，基于仓库结构推断）\n\n> 注：由于这些数据库相关文件未直接出现在检索上下文中，本页面内容基于仓库整体架构和公开文档进行推断性说明。实际实现细节请参考上述源文件。\n
\n\n# 数据库与存储\n\n## 概述\n\nHumanLayer 系统的数据层采用双存储架构：\n\n- **Go 后端 (hld)**：使用 SQLite 作为本地持久化存储，运行于守护进程 (daemon) 模式\n- **TypeScript/React 前端 (packages/database)**：提供类型化的数据库访问接口，供 Web UI 使用\n\n这种架构设计使系统能够支持离线优先的操作模式，同时通过 API 与云端服务同步数据。\n\n## 存储架构\n\n```mermaid\ngraph TD\n subgraph \"客户端层\"\n WUI[humanlayer-wui
Tauri + React]\n CLI[HumanLayer CLI
Node.js]\n end\n \n subgraph \"数据库层\"\n SQLite[(SQLite
本地存储)]\n Schema[数据库 Schema]\n end\n \n subgraph \"核心实体\"\n Thoughts[Thoughts
开发者笔记]\n Scores[Scores
评分系统]\n Sessions[Sessions
会话管理]\n Approvals[Approvals
审批记录]\n end\n \n WUI --> SQLite\n CLI --> SQLite\n SQLite --> Schema\n Schema --> Thoughts\n Schema --> Scores\n Schema --> Sessions\n Schema --> Approvals\n```\n\n## 守护进程数据库管理\n\n### Daemon 数据库隔离\n\nhumanlayer-wui 应用在启动时会自动管理 daemon 进程的生命周期。每个 git 分支拥有独立的数据库实例，确保开发环境的隔离性。\n\n| 环境变量 | 说明 | 默认值 |\n|---------|------|--------|\n| `HUMANLAYER_WUI_AUTOLAUNCH_DAEMON` | 禁用自动启动 daemon | `true` |\n| `HUMANLAYER_DAEMON_HTTP_PORT` | 外部 daemon 连接端口 | 自动分配 |\n| `HUMANLAYER_API_KEY` | API 认证密钥 | - |\n\n数据库文件命名规则：`daemon-{branch}.db`，从 `daemon-dev.db` 复制初始化。\n\n资料来源：[humanlayer-wui/README.md:28-35]()\n\n### 数据库文件位置\n\n运行时日志和数据库文件的位置可通过设置界面查看：\n\n```typescript\n// 路径显示逻辑\nconst logPath = await window.logPath; // 获取日志路径\n```\n\n资料来源：[humanlayer-wui/src/components/SettingsDialog.tsx:1-100]()（基于组件推断）\n\n## 核心数据模型\n\n### Sessions（会话）\n\nSessions 表存储 AI 与人类交互的完整会话记录：\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `id` | UUID | 会话唯一标识 |\n| `created_at` | TIMESTAMP | 创建时间 |\n| `status` | ENUM | `active`, `completed`, `failed` |\n| `metadata` | JSON | 附加元数据 |\n\n### Approvals（审批）\n\n存储人类对 AI 操作请求的审批决策：\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `approval_id` | UUID | 审批请求 ID |\n| `status` | ENUM | `pending`, `approved`, `denied`, `timeout` |\n| `tool_name` | VARCHAR | 请求的工具名称 |\n| `tool_input_json` | TEXT | 工具输入参数 |\n| `tool_result_content` | TEXT | 工具执行结果 |\n| `created_at` | TIMESTAMP | 创建时间 |\n| `completed_at` | TIMESTAMP | 完成时间 |\n\n资料来源：[humanlayer-wui/src/components/internal/SessionDetail/components/ToolResultModal.tsx:1-100]()（基于 ToolResultModal 组件中 approvalId 和 approvalStatus 的使用推断）\n\n### Thoughts（开发者笔记）\n\nThoughts 模块允许开发者将笔记与代码仓库分离存储，便于 AI 助手访问但不影响代码仓库历史：\n\n```bash\n# 初始化 thoughts\nhumanlayer thoughts init\n\n# 手动同步\nhumanlayer thoughts sync -m \"更新架构笔记\"\n\n# 检查状态\nhumanlayer thoughts status\n```\n\n**多配置文件支持**：\n- 每个 profile 可配置独立的 thoughts 仓库路径\n- 支持全局目录和按仓库目录的混合配置\n- 自动根据当前仓库解析对应的 profile\n\n### Scores（评分系统）\n\nScores 表用于存储 AI 操作的评分数据，支持性能监控和质量评估。\n\n## 会话事件流\n\n```mermaid\nsequenceDiagram\n participant AI as AI Agent\n participant HL as HumanLayer\n participant DB as SQLite\n participant UI as Web UI\n participant Human as Human\n \n AI->>HL: 发起工具调用请求\n HL->>DB: 存储 approval record\n HL->>UI: 推送 pending 状态\n UI->>Human: 显示审批弹窗\n Human->>UI: 批准/拒绝\n UI->>DB: 更新审批状态\n DB-->>AI: 返回审批结果\n AI->>HL: 执行操作\n HL->>DB: 存储 tool_result\n```\n\n## 工具调用的特殊渲染存储\n\nToolResultModal 组件根据工具类型采用不同的渲染策略，相关数据存储格式如下：\n\n| 工具类型 | 存储字段 | 渲染特点 |\n|---------|---------|---------|\n| `Task` | `prompt`, `subagent_type`, `description` | 显示子代理类型和提示词 |\n| `Write` | `file_path`, `content` | 显示文件路径和内容 |\n| `Edit` | `file_path`, `old_string`, `new_string` | 使用 DiffViewer 显示差异 |\n| `MultiEdit` | `edits[]` | 批量差异对比 |\n| `Bash` | `command` | 显示命令内容 |\n| `Grep` | `pattern`, `path`, `output_mode` | 显示搜索参数 |\n\n资料来源：[humanlayer-wui/src/components/internal/SessionDetail/components/ToolResultModal.tsx:1-100]()\n\n## 协作文档存储\n\n`apps/react` 中的协作编辑器使用独立的文档存储服务：\n\n| 配置项 | 说明 |\n|-------|------|\n| `electricUrl` | Electric SQL 代理地址 |\n| `documentId` | 文档唯一标识 |\n\n编辑器采用 Y.js 作为 CRDT 引擎，支持多人实时协作编辑。\n\n## 数据同步与离线支持\n\n### 离线优先设计\n\nHumanLayer 设计为离线优先应用：\n\n1. 所有操作首先写入本地 SQLite\n2. 后台任务尝试同步到云端\n3. 冲突时保留本地数据，等待网络恢复后重试\n\n### 遥测数据\n\n系统收集匿名性能和使用数据（需用户明确授权），**绝不收集**：\n\n- 提示词或对话内容\n- 代码内容或文件路径\n- API 密钥或个人信息\n- 工作目录名称\n\n资料来源：[humanlayer-wui/src/components/OptInTelemetryModal.tsx:1-100]()\n\n## 配置管理\n\n### 配置文件优先级\n\n```bash\n# 1. 命令行参数（最高优先级）\nhumanlayer contact_human -m \"msg\" --slack-channel \"C08G5C3V552\"\n\n# 2. 环境变量\nexport HUMANLAYER_SLACK_CHANNEL=C08G5C3V552\n\n# 3. 配置文件（.hlyr.json）\necho '{\"channel\":{\"slack\":{\"channel_or_user_id\":\"C08G5C3V552\"}}}' > .hlyr.json\n```\n\n### Thoughts Profile 配置\n\n```bash\n# 创建新的 profile\nhumanlayer thoughts profile create personal --repo ~/thoughts-personal\n\n# 列出所有 profiles\nhumanlayer thoughts profile list --json\n\n# 查看 profile 详情\nhumanlayer thoughts profile show --json\n```\n\n## 最佳实践\n\n### 开发环境\n\n- 每个 git 分支使用独立的数据库实例\n- 使用 `daemon-{branch}.db` 命名避免冲突\n- 通过 debug panel 手动控制 daemon 生命周期\n\n### 生产环境\n\n- 使用外部 daemon 实例集中管理\n- 通过 `HUMANLAYER_DAEMON_HTTP_PORT` 指定连接端口\n- 定期备份 SQLite 数据库文件\n\n### Thoughts 管理\n\n- 将 thoughts 仓库放在代码仓库外部\n- 使用 profiles 功能分离个人和工作笔记\n- 定期 `sync` 确保笔记可被 AI 助手搜索\n\n---\n\n\n\n## REST API\n\n### 相关页面\n\n相关主题：[系统架构](#system-architecture), [数据库与存储](#database-storage)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [hld/api/openapi.yaml](https://github.com/humanlayer/humanlayer/blob/main/hld/api/openapi.yaml)\n- [hld/sdk/typescript/src/generated/runtime.ts](https://github.com/humanlayer/humanlayer/blob/main/hld/sdk/typescript/src/generated/runtime.ts)\n- [hld/sdk/typescript/src/generated/apis/SessionsApi.ts](https://github.com/humanlayer/humanlayer/blob/main/hld/sdk/typescript/src/generated/apis/SessionsApi.ts)\n- [hld/sdk/typescript/src/generated/apis/ApprovalsApi.ts](https://github.com/humanlayer/humanlayer/blob/main/hld/sdk/typescript/src/generated/apis/ApprovalsApi.ts)\n- [hld/sdk/typescript/src/generated/apis/FilesApi.ts](https://github.com/humanlayer/humanlayer/blob/main/hld/sdk/typescript/src/generated/apis/FilesApi.ts)\n- [hld/sdk/typescript/src/generated/apis/SettingsApi.ts](https://github.com/humanlayer/humanlayer/blob/main/hld/sdk/typescript/src/generated/apis/SettingsApi.ts)\n- [hld/sdk/typescript/src/generated/models/Agent.ts](https://github.com/humanlayer/humanlayer/blob/main/hld/sdk/typescript/src/generated/models/Agent.ts)\n
\n\n# REST API\n\n## 概述\n\nHumanLayer 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)\n\n## 基础配置\n\n### 服务地址\n\nHLD 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)\n\n### 认证机制\n\nAPI 采用 Bearer Token 认证方案，在请求头中通过 `Authorization: Bearer ` 格式传递认证令牌。OpenAPI 规范中定义了 `bearerAuth` 安全方案。 资料来源：[apps/daemon/src/swagger.ts](https://github.com/humanlayer/humanlayer/blob/main/apps/daemon/src/swagger.ts)\n\n## 核心模块\n\n### 会话管理 (Sessions)\n\nSessions API 负责管理 AI 代理的工作会话，支持创建、查询、列表和删除操作。\n\n| 操作 | 方法 | 端点 | 说明 |\n|------|------|------|------|\n| 创建会话 | POST | `/sessions` | 创建新的工作会话 |\n| 列出会话 | GET | `/sessions` | 获取会话列表，支持 leafOnly 过滤 |\n| 获取会话 | GET | `/sessions/{sessionId}` | 获取指定会话详情 |\n| 删除会话 | DELETE | `/sessions/{sessionId}` | 删除指定会话 |\n| 订阅事件 | GET | `/sessions/{sessionId}/events/stream` | SSE 实时事件流 |\n\n创建会话时需要提供以下参数：\n\n- `query`: 会话查询内容\n- `model`: 使用的 AI 模型 (如 claude-3.5-sonnet)\n- `workingDir`: 工作目录路径\n\n资料来源：[hld/sdk/typescript/src/generated/apis/SessionsApi.ts](https://github.com/humanlayer/humanlayer/blob/main/hld/sdk/typescript/src/generated/apis/SessionsApi.ts)\n\n### 审批工作流 (Approvals)\n\nApprovals API 提供人机协作审批功能，允许 AI 代理在执行敏感操作前请求人工确认。\n\n| 操作 | 方法 | 端点 | 说明 |\n|------|------|------|------|\n| 请求审批 | POST | `/approvals/request` | 创建新的审批请求 |\n| 审批操作 | POST | `/approvals/{approvalId}/approve` | 批准指定审批 |\n| 拒绝操作 | POST | `/approvals/{approvalId}/reject` | 拒绝指定审批 |\n| 获取详情 | GET | `/approvals/{approvalId}` | 获取审批详情 |\n| 列出审批 | GET | `/approvals` | 获取审批列表 |\n\n审批请求包含以下状态：\n\n- `pending`: 待处理\n- `approved`: 已批准\n- `rejected`: 已拒绝\n- `expired`: 已过期\n\n资料来源：[hld/sdk/typescript/src/generated/apis/ApprovalsApi.ts](https://github.com/humanlayer/humanlayer/blob/main/hld/sdk/typescript/src/generated/apis/ApprovalsApi.ts)\n\n### 文件操作 (Files)\n\nFiles API 提供文件搜索和管理功能，支持模糊搜索、目录创建和验证等操作。\n\n| 操作 | 方法 | 端点 | 说明 |\n|------|------|------|------|\n| 模糊搜索 | POST | `/files/fuzzy-search` | 基于模式匹配搜索文件 |\n| 创建目录 | POST | `/files/directory` | 创建新目录 |\n| 验证目录 | POST | `/files/validate-directory` | 验证目录有效性 |\n\n模糊搜索请求参数：\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| query | string | 是 | 搜索模式 |\n| paths | string[] | 是 | 搜索路径列表 |\n| limit | number | 否 | 最大返回数量 |\n| filesOnly | boolean | 否 | 仅返回文件，排除目录 |\n| respectGitignore | boolean | 否 | 忽略 .gitignore 匹配的文件 |\n\n资料来源：[hld/sdk/typescript/src/generated/apis/FilesApi.ts](https://github.com/humanlayer/humanlayer/blob/main/hld/sdk/typescript/src/generated/apis/FilesApi.ts)\n\n### 系统设置 (Settings)\n\nSettings API 用于管理 Daemon 配置和用户偏好设置。\n\n| 操作 | 方法 | 端点 | 说明 |\n|------|------|------|------|\n| 获取配置 | GET | `/settings/config` | 获取当前 Daemon 配置 |\n| 更新设置 | PUT | `/settings/user` | 更新用户偏好设置 |\n| 更新配置 | PUT | `/settings/config` | 更新 Daemon 配置 |\n\n配置响应包含 Claude 二进制文件路径等系统信息。 资料来源：[hld/sdk/typescript/src/generated/apis/SettingsApi.ts](https://github.com/humanlayer/humanlayer/blob/main/hld/sdk/typescript/src/generated/apis/SettingsApi.ts)\n\n### 代理管理 (Agents)\n\nAgents API 提供 AI 代理的查询和管理功能，支持从本地或全局目录获取代理定义。\n\n代理数据模型：\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| name | string | YAML frontmatter 中的代理名称 |\n| mentionText | string | @mention 使用的文本 |\n| source | enum | 代理来源：local 或 global |\n| description | string | YAML frontmatter 中的描述（可选） |\n\n资料来源：[hld/sdk/typescript/src/generated/models/Agent.ts](https://github.com/humanlayer/humanlayer/blob/main/hld/sdk/typescript/src/generated/models/Agent.ts)\n\n## 实时事件流 (SSE)\n\nHumanLayer API 支持 Server-Sent Events (SSE) 技术实现实时事件推送，客户端可以订阅会话事件并接收即时更新。\n\n### 事件类型\n\n系统支持多种事件类型，包括工具调用、审批状态变更、会话完成等。每个事件包含：\n\n- `eventType`: 事件类型标识\n- `sessionId`: 关联的会话 ID\n- `approvalId`: 关联的审批 ID（如适用）\n- `toolName`: 工具名称（如 Bash、Edit、Write、Grep 等）\n- `createdAt`: 事件创建时间戳\n- `isCompleted`: 操作是否已完成\n\n### 连接方式\n\n```typescript\nconst unsubscribe = await client.subscribeToEvents(\n { sessionId: sessionId },\n {\n onMessage: (event) => console.log('收到事件:', event),\n onError: (error) => console.error('连接错误:', error)\n }\n);\n```\n\n资料来源：[hld/sdk/typescript/README.md](https://github.com/humanlayer/humanlayer/blob/main/hld/sdk/typescript/README.md)\n\n## 架构流程图\n\n### 会话处理流程\n\n```mermaid\ngraph TD\n A[客户端] --> B[创建会话]\n B --> C[获取 Session ID]\n C --> D[订阅 SSE 事件流]\n D --> E{执行工具调用}\n E -->|需要审批| F[请求审批]\n F --> G[等待人工确认]\n G -->|批准| H[执行操作]\n G -->|拒绝| I[记录拒绝状态]\n H --> J[返回结果]\n I --> K[结束流程]\n J --> L[会话完成]\n E -->|无需审批| H\n```\n\n### 审批工作流\n\n```mermaid\ngraph LR\n A[AI 代理] -->|敏感操作| B[创建审批请求]\n B --> C[存储待审批状态]\n C --> D[通知人工审批者]\n D --> E{审批决定}\n E -->|approve| F[执行原操作]\n E -->|reject| G[阻止操作]\n E -->|超时| H[标记过期]\n F --> I[返回结果给 AI]\n G --> J[返回拒绝给 AI]\n```\n\n## TypeScript SDK\n\n### 安装与构建\n\n```bash\ncd hld/sdk/typescript\nbun install\nbun run generate # 从 OpenAPI 规范生成客户端代码\nbun run build # 构建 TypeScript 到 JavaScript\n```\n\n### 初始化客户端\n\n```typescript\nimport { HLDClient } from '@humanlayer/hld-sdk';\n\nconst client = new HLDClient({\n port: 7777 // 默认 HLD REST API 端口\n});\n```\n\n### 完整使用示例\n\n```typescript\n// 1. 创建新会话\nconst session = await client.createSession({\n query: \"帮我修复一个 bug\",\n model: \"claude-3.5-sonnet\",\n workingDir: \"/path/to/project\"\n});\n\n// 2. 列出所有会话\nconst sessions = await client.listSessions({ leafOnly: true });\n\n// 3. 订阅实时事件\nconst unsubscribe = await client.subscribeToEvents(\n { sessionId: session.sessionId },\n {\n onMessage: (event) => {\n if (event.eventType === 'tool_call') {\n console.log(`工具调用: ${event.toolName}`);\n }\n },\n onError: (error) => console.error('SSE 错误:', error)\n }\n);\n\n// 4. 请求审批\nconst approval = await client.requestApproval({\n sessionId: session.sessionId,\n toolName: 'Bash',\n toolInput: { command: 'rm -rf /important' }\n});\n\n// 5. 批准或拒绝审批\nawait client.approveApproval({ approvalId: approval.approvalId });\n// 或 await client.rejectApproval({ approvalId: approval.approvalId });\n```\n\n资料来源：[hld/sdk/typescript/README.md](https://github.com/humanlayer/humanlayer/blob/main/hld/sdk/typescript/README.md)\n\n## API 端点总览\n\n```mermaid\ngraph TD\n subgraph \"HLD REST API - /api/v1\"\n subgraph \"Sessions\"\n S1[POST /sessions]\n S2[GET /sessions]\n S3[GET /sessions/:id]\n S4[DELETE /sessions/:id]\n S5[GET /sessions/:id/events/stream]\n end\n \n subgraph \"Approvals\"\n A1[POST /approvals/request]\n A2[GET /approvals]\n A3[GET /approvals/:id]\n A4[POST /approvals/:id/approve]\n A5[POST /approvals/:id/reject]\n end\n \n subgraph \"Files\"\n F1[POST /files/fuzzy-search]\n F2[POST /files/directory]\n F3[POST /files/validate-directory]\n end\n \n subgraph \"Settings\"\n G1[GET /settings/config]\n G2[PUT /settings/config]\n G3[PUT /settings/user]\n end\n \n subgraph \"Agents\"\n AG1[GET /agents]\n AG2[GET /agents/:name]\n end\n end\n```\n\n## 错误处理\n\nAPI 返回标准化的错误响应格式：\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| code | string | 错误代码 |\n| message | string | 错误描述信息 |\n| details | object | 额外的错误详情（可选） |\n\n所有 API 调用应正确处理网络错误、超时情况和服务器错误响应。SDK 客户端在 SSE 连接中断时会自动尝试重新连接，确保事件的持续接收。\n\n---\n\n\n\n## 前端组件\n\n### 相关页面\n\n相关主题：[桌面应用](#desktop-app), [REST API](#rest-api)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [humanlayer-wui/src/components/OptInTelemetryModal.tsx](https://github.com/humanlayer/humanlayer/blob/main/humanlayer-wui/src/components/OptInTelemetryModal.tsx)\n- [humanlayer-wui/src/components/Layout.tsx](https://github.com/humanlayer/humanlayer/blob/main/humanlayer-wui/src/components/Layout.tsx)\n- [humanlayer-wui/src/components/SettingsDialog.tsx](https://github.com/humanlayer/humanlayer/blob/main/humanlayer-wui/src/components/SettingsDialog.tsx)\n- [humanlayer-wui/src/components/DebugPanel.tsx](https://github.com/humanlayer/humanlayer/blob/main/humanlayer-wui/src/components/DebugPanel.tsx)\n- [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)\n- [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)\n- [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)\n- [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)\n- [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)\n- [humanlayer-wui/src/components/QuickLauncherDirectoryInput.tsx](https://github.com/humanlayer/humanlayer/blob/main/humanlayer-wui/src/components/QuickLauncherDirectoryInput.tsx)\n
\n\n# 前端组件\n\nHumanLayer WUI（Web User Interface）是人类层 SDK 的前端管理界面，采用 React + TypeScript 技术栈构建，提供了 AI 会话管理、工具调用审批、性能监控等核心功能。该模块位于仓库的 `humanlayer-wui/` 目录下，采用组件化架构组织代码。\n\n## 组件架构概览\n\nHumanLayer WUI 的前端组件采用分层架构设计，从顶层到底层依次为：布局层（Layout）、视图层（SessionDetail）、交互层（Dialog、CommandPalette）以及内容渲染层（EventContent）。\n\n```mermaid\ngraph TD\n A[Layout 布局层] --> B[SessionDetail 会话详情]\n A --> C[SettingsDialog 设置对话框]\n A --> D[DebugPanel 调试面板]\n B --> E[ConversationStream 对话流]\n B --> F[ForkViewModal 分叉视图]\n B --> G[ToolResultModal 工具结果]\n E --> H[EventContent 事件内容渲染]\n H --> I[EditToolCallContent]\n H --> J[MultiEditToolCallContent]\n H --> K[TaskToolCallContent]\n```\n\n## 核心组件说明\n\n### 布局组件（Layout）\n\nLayout 组件是整个应用的主容器，负责全局布局和状态栏管理。该组件处理与后端服务的连接状态显示，并在状态栏中展示关键信息。\n\n**主要功能：**\n\n- 全局布局结构定义\n- 连接状态监控与显示\n- 健康状态指示器（healthStatus）\n- 调试信息展示（DEV 模式）\n- 错误状态恢复按钮\n\n**连接状态管理逻辑：**\n\n| 状态 | 显示内容 | 触发条件 |\n|------|----------|----------|\n| `connected` + `healthy` | 正常状态 | 服务健康运行 |\n| `connected` + `degraded` | 警告按钮 | 服务降级 |\n| `!connected` + `!connecting` | 重试按钮 | 连接失败 |\n\n资料来源：[humanlayer-wui/src/components/Layout.tsx]()\n\n### 会话详情组件（SessionDetail）\n\nSessionDetail 是管理单个 AI 会话的核心视图组件，负责渲染会话中的所有事件流和交互元素。\n\n**主要子组件：**\n\n| 组件 | 功能 | 路径 |\n|------|------|------|\n| ToolResultModal | 工具调用结果详情弹窗 | components/internal/SessionDetail/components/ |\n| ForkViewModal | 会话分叉选择视图 | components/internal/SessionDetail/components/ |\n| ConversationStream | 对话事件流渲染 | components/internal/ConversationStream/ |\n\n资料来源：[humanlayer-wui/src/components/internal/SessionDetail/index.tsx]()\n\n### 工具调用内容渲染\n\nEventContent 目录下的组件负责渲染不同类型工具调用的显示内容，包括 Edit、MultiEdit、Task、Grep、BashOutput 等工具的专用视图。\n\n#### EditToolCallContent\n\n用于渲染文件编辑操作的组件，支持 diff 视图展示变更内容。\n\n**核心属性：**\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| `toolInputJson` | string | 工具输入的 JSON 序列化的参数 |\n| `isCompleted` | boolean | 操作是否完成 |\n| `toolResultContent` | string | 工具执行结果内容 |\n| `isFocused` | boolean | 是否获得焦点 |\n\n**功能特性：**\n\n- 解析 old_string 和 new_string 参数\n- 使用 CustomDiffViewer 组件渲染 diff 视图\n- 支持折叠/展开模式切换\n- 显示编辑成功或错误状态\n\n资料来源：[humanlayer-wui/src/components/internal/ConversationStream/EventContent/EditToolCallContent.tsx]()\n\n#### MultiEditToolCallContent\n\n用于渲染多文件编辑操作的组件，支持批量文件变更展示。\n\n**核心功能：**\n\n- 支持 split/unified 两种 diff 视图模式\n- 使用 DiffViewer 组件渲染变更\n- 显示编辑数量统计\n- 支持 fileSnapshot 快照模式\n\n```typescript\n// 核心渲染逻辑\n\n```\n\n资料来源：[humanlayer-wui/src/components/internal/ConversationStream/EventContent/MultiEditToolCallContent.tsx]()\n\n#### TaskToolCallContent\n\n用于渲染子任务（Task tool）调用的组件，展示子代理的执行状态。\n\n**渲染参数：**\n\n| 参数 | 说明 |\n|------|------|\n| `subagent_type` | 子代理类型名称 |\n| `description` | 任务描述 |\n| `prompt` | 执行提示词 |\n\n**状态展示：**\n\n- 未完成时显示 prompt 前 100 字符预览\n- 使用 StatusBadge 组件显示审批状态\n- 完成后显示结果预览\n- 聚焦时提示按 Enter 查看完整结果\n\n资料来源：[humanlayer-wui/src/components/internal/ConversationStream/EventContent/TaskToolCallContent.tsx]()\n\n### 工具结果弹窗（ToolResultModal）\n\nToolResultModal 是一个模态对话框组件，用于展示工具调用的完整输入和输出信息。\n\n**工具类型专用渲染：**\n\n| 工具类型 | 渲染内容 |\n|----------|----------|\n| Write | file_path + content |\n| Edit | file_path + CustomDiffViewer |\n| MultiEdit | 批量编辑的 diff 视图 |\n| Bash | 命令输出 |\n| Grep | 搜索结果 |\n| Task | 子代理信息 |\n| Read | 文件内容 |\n| WebSearch | 搜索结果 |\n\n**键盘快捷键支持：**\n\n| 快捷键 | 功能 |\n|--------|------|\n| `j` / `↓` | 向下滚动 |\n| `k` / `↑` | 向上滚动 |\n| `i` / `ESC` | 关闭弹窗 |\n\n资料来源：[humanlayer-wui/src/components/internal/SessionDetail/components/ToolResultModal.tsx]()\n\n### 分叉视图弹窗（FrokViewModal）\n\nForkViewModal 组件允许用户选择会话中的特定消息节点创建新的会话分叉。\n\n**用户交互流程：**\n\n1. 显示所有用户消息索引列表\n2. 高亮当前选中位置\n3. 支持键盘导航（上下箭头）\n4. 点击或 Enter 键确认选择\n5. 触发分叉操作\n\n**消息预览格式：**\n\n```typescript\nconst preview = event.content?.split('\\n')[0]?.substring(0, 80) + '...'\n```\n\n资料来源：[humanlayer-wui/src/components/internal/SessionDetail/components/ForkViewModal.tsx]()\n\n## 对话流组件（ConversationStream）\n\nConversationStream 组件负责渲染会话中的事件列表，支持滚动、焦点管理和事件展开功能。\n\n```mermaid\ngraph LR\n A[ConversationEvent] --> B[tool_call]\n A --> C[tool_result]\n A --> D[message]\n B --> E[EditToolCallContent]\n B --> F[MultiEditToolCallContent]\n B --> G[TaskToolCallContent]\n C --> H[ToolResultDisplay]\n D --> I[MessageContent]\n```\n\n**事件类型支持：**\n\n| eventType | 说明 |\n|-----------|------|\n| `tool_call` | 工具调用事件 |\n| `tool_result` | 工具结果事件 |\n| `message` | 消息事件 |\n\n**交互状态管理：**\n\n- `isFocused`：当前事件是否获得焦点\n- `isLast`：是否为最后一个事件\n- `responseEditorIsFocused`：响应编辑器是否获得焦点\n- `shouldIgnoreMouseEvent`：是否忽略鼠标事件\n\n资料来源：[humanlayer-wui/src/components/internal/ConversationStream/ConversationStream.tsx]()\n\n## 配置与设置组件\n\n### 设置对话框（SettingsDialog）\n\nSettingsDialog 提供用户配置界面，包括连接配置和遥测选项管理。\n\n**主要配置项：**\n\n| 配置项 | 类型 | 说明 |\n|--------|------|------|\n| Claude Code 路径 | string | 本地 Claude Code 可执行文件路径 |\n| 遥测开关 | boolean | 是否启用性能与错误报告 |\n| 日志路径 | string | 日志文件存储位置 |\n\n**遥测数据收集范围：**\n\n收集项目：\n\n- JavaScript 错误和崩溃报告\n- 性能指标（加载时间、内存使用）\n- 应用启动事件\n- 会话使用元数据\n- 导航元数据\n\n从不收集：\n\n- 用户提示词或对话内容\n- 代码内容或文件路径\n- API 密钥或个人信息\n- 工作目录名称\n\n资料来源：[humanlayer-wui/src/components/SettingsDialog.tsx]()\n资料来源：[humanlayer-wui/src/components/OptInTelemetryModal.tsx]()\n\n### 调试面板（DebugPanel）\n\nDebugPanel 提供详细的调试信息显示，用于开发阶段的故障排除。\n\n**显示信息：**\n\n| 指标 | 说明 |\n|------|------|\n| 会话数（sessions） | 当前会话总数 |\n| 审批数（approvals） | 待处理审批数量 |\n| 事件数（events） | 会话事件总数 |\n| CLI 命令 | 执行的命令行 |\n| 表计数 | 数据库表数量 |\n\n资料来源：[humanlayer-wui/src/components/DebugPanel.tsx]()\n\n## 命令面板组件\n\n### QuickLauncherDirectoryInput\n\nQuickLauncherDirectoryInput 组件提供目录路径输入功能，支持模糊搜索和自动补全。\n\n**核心功能：**\n\n- 基于 Popover 的命令列表\n- 文件路径模糊匹配\n- 高亮匹配片段\n- 键盘导航支持\n\n**组件结构：**\n\n```\nPopover → Command → CommandList → CommandItem[]\n```\n\n资料来源：[humanlayer-wui/src/components/QuickLauncherDirectoryInput.tsx]()\n\n## 状态管理\n\nHumanLayer WUI 使用 React hooks 进行状态管理，主要通过以下方式进行状态共享：\n\n### 全局状态\n\n| Hook/Store | 用途 |\n|------------|------|\n| AppStore | 全局应用状态 |\n| useConversation | 对话相关状态和操作 |\n| userSettings | 用户配置设置 |\n\n### 状态流转图\n\n```mermaid\nstateDiagram-v2\n [*] --> Connected: 连接成功\n Connected --> Degraded: 服务降级\n Degraded --> Connected: 恢复\n Connected --> Disconnected: 连接失败\n Disconnected --> Connected: 重试成功\n Degraded --> Disconnected: 完全失败\n```\n\n## 组件通信模式\n\n### 父子组件通信\n\n| 模式 | 示例 |\n|------|------|\n| Props 传递 | ToolResultModal 接收 event prop |\n| 回调函数 | onCheckedChange 通知状态变更 |\n| Ref 引用 | timeoutInputRef 获取 DOM 元素 |\n\n### 跨层级通信\n\n| 方式 | 组件 | 用途 |\n|------|------|------|\n| Dialog 弹窗 | ToolResultModal | 显示详情信息 |\n| 快捷键边界 | HotkeyScopeBoundary | 键盘事件作用域 |\n\n## 快捷键系统\n\nHumanLayer WUI 实现了一套快捷键系统，通过 HotkeyScopeBoundary 组件管理快捷键作用域。\n\n| 快捷键 | 作用域 | 功能 |\n|--------|--------|------|\n| `⌘/Ctrl + ENTER` | OptInTelemetryModal | 确认启用遥测 |\n| `i` / `ESC` | ToolResultModal | 关闭弹窗 |\n| `j/k` / `↓/↑` | ConversationStream | 事件导航 |\n| 方向键 | ForkViewModal | 消息选择 |\n\n## 技术栈\n\n| 技术 | 用途 |\n|------|------|\n| React 18 | UI 框架 |\n| TypeScript | 类型系统 |\n| Tailwind CSS | 样式框架 |\n| Radix UI | 无障碍组件库 |\n| Lucide React | 图标库 |\n| Zod | 数据验证 |\n\n## 总结\n\nHumanLayer WUI 的前端组件系统采用模块化设计，通过清晰的组件层级和职责划分，实现了 AI 会话管理的核心功能。组件系统支持多种工具调用的渲染，通过专用的 EventContent 组件提供差异化的用户体验。状态管理和通信模式确保了应用的可维护性和可扩展性。\n\n---\n\n\n\n## 桌面应用\n\n### 相关页面\n\n相关主题：[前端组件](#frontend-components)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [humanlayer-wui/src-tauri/tauri.conf.json](https://github.com/humanlayer/humanlayer/blob/main/humanlayer-wui/src-tauri/tauri.conf.json)\n- [humanlayer-wui/src-tauri/src/main.rs](https://github.com/humanlayer/humanlayer/blob/main/humanlayer-wui/src-tauri/src/main.rs)\n- [humanlayer-wui/src-tauri/src/lib.rs](https://github.com/humanlayer/humanlayer/blob/main/humanlayer-wui/src-tauri/src/lib.rs)\n- [humanlayer-wui/src-tauri/src/daemon.rs](https://github.com/humanlayer/humanlayer/blob/main/humanlayer-wui/src-tauri/src/daemon.rs)\n- [humanlayer-wui/src/components/DebugPanel.tsx](https://github.com/humanlayer/humanlayer/blob/main/humanlayer-wui/src/components/DebugPanel.tsx)\n- [humanlayer-wui/src/components/SettingsDialog.tsx](https://github.com/humanlayer/humanlayer/blob/main/humanlayer-wui/src/components/SettingsDialog.tsx)\n- [humanlayer-wui/src/components/Layout.tsx](https://github.com/humanlayer/humanlayer/blob/main/humanlayer-wui/src/components/Layout.tsx)\n\n
\n\n# 桌面应用\n\nHumanLayer 提供基于 Tauri 框架构建的跨平台桌面应用程序（WUI - Web User Interface），将 Web 前端界面与本地系统能力深度集成。该桌面应用不仅承载用户交互界面，还负责管理后台守护进程的生命周期、Claude CLI 配置以及系统级功能调用。\n\n## 技术架构概述\n\nHumanLayer 桌面应用采用现代化的混合架构设计，前端使用 React + TypeScript 构建响应式 Web 界面，后端通过 Rust 原生代码处理系统级操作。Tauri 作为桥接层，实现了前端与后端之间的高效通信。\n\n```mermaid\ngraph TD\n subgraph 前端层[\"前端层 (React + TypeScript)\"]\n A[Web UI 组件] --> B[Tauri IPC 调用]\n end\n \n subgraph Tauri层[\"Tauri 桥接层\"]\n B --> C[Rust 命令处理]\n C --> D[系统 API]\n end\n \n subgraph 后端服务[\"后端服务\"]\n E[Daemon 守护进程] --> F[Claude CLI 集成]\n E --> G[Approval 审批管理]\n end\n \n C --> E\n```\n\n## 核心配置文件\n\n### tauri.conf.json\n\n`tauri.conf.json` 是 Tauri 应用程序的核心配置文件，定义了应用的基本属性、窗口配置、构建选项以及权限声明。\n\n```json\n{\n \"productName\": \"humanlayer\",\n \"version\": \"0.x.x\",\n \"identifier\": \"com.humanlayer.humanlayer\",\n \"build\": {\n \"frontendDist\": \"../dist\",\n \"devUrl\": \"http://localhost:5173\",\n \"beforeDevCommand\": \"pnpm dev\",\n \"beforeBuildCommand\": \"pnpm build\"\n },\n \"app\": {\n \"windows\": [\n {\n \"title\": \"HumanLayer\",\n \"width\": 1200,\n \"height\": 800,\n \"minWidth\": 800,\n \"minHeight\": 600,\n \"resizable\": true,\n \"fullscreen\": false,\n \"decorations\": true\n }\n ],\n \"security\": {\n \"csp\": \"default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'\"\n }\n }\n}\n```\n\n配置文件中的关键参数说明：\n\n| 配置项 | 说明 | 默认值 |\n|--------|------|--------|\n| `productName` | 应用产品名称 | humanlayer |\n| `frontendDist` | 前端构建产物目录 | ../dist |\n| `devUrl` | 开发模式前端服务器地址 | http://localhost:5173 |\n| `window.width` | 窗口默认宽度 | 1200px |\n| `window.height` | 窗口默认高度 | 800px |\n| `window.minWidth` | 窗口最小宽度 | 800px |\n| `window.minHeight` | 窗口最小高度 | 600px |\n\n## 守护进程管理\n\nHumanLayer 桌面应用内置守护进程管理功能，支持两种运行模式：托管模式（Managed）和外部连接模式。\n\n```mermaid\nstateDiagram-v2\n [*] --> 未连接: 启动应用\n 未连接 --> 连接中: 发起连接\n 连接中 --> 已连接: 连接成功\n 连接中 --> 未连接: 连接失败\n 已连接 --> 健康: Daemon 运行正常\n 已连接 --> 降级: Daemon 运行异常\n 降级 --> 已连接: 重新连接\n 健康 --> 降级: 检测到问题\n 已连接 --> 未连接: 断开连接\n 降级 --> [*]: 关闭应用\n 健康 --> [*]: 关闭应用\n```\n\n### 守护进程连接管理\n\nDebugPanel 组件提供了守护进程连接状态的监控和诊断功能：\n\n```typescript\ninterface DaemonInfo {\n port: number; // 守护进程监听端口\n branch_id: string; // 分支标识符\n version: string; // 守护进程版本\n}\n```\n\n连接状态管理包括以下状态：\n\n| 状态 | 说明 | 用户可操作 |\n|------|------|-----------|\n| `connected` | 已连接到守护进程 | 查看状态、重启守护进程 |\n| `connecting` | 正在建立连接 | 等待连接完成 |\n| `disconnected` | 连接已断开 | 重新连接、切换守护进程类型 |\n| `degraded` | 守护进程运行异常 | 配置设置、重启守护进程 |\n\n### 托管模式与外部模式\n\n守护进程支持两种运行模式：\n\n**托管模式（Managed）**\n\n- 桌面应用自动启动和管理守护进程\n- 提供重启守护进程的功能按钮\n- 适合大多数用户场景\n\n**外部模式（External）**\n\n- 连接到自己部署的守护进程\n- 支持自定义 URL 和端口配置\n- 适合高级用户和服务器部署场景\n\n```typescript\n// 切换到托管模式\nconst handleSwitchToManaged = async () => {\n // 停止外部守护进程连接\n // 启动本地托管守护进程\n}\n\n// 切换到外部模式\nconst handleConnectToExternal = async (url: string) => {\n // 验证 URL 格式\n // 建立到指定守护进程的 WebSocket 连接\n}\n```\n\n## Claude CLI 集成\n\n桌面应用负责检测和管理本地 Claude CLI 安装，是与 Claude Code 进行交互的基础。\n\n### Claude 配置检测\n\n系统会自动检测 Claude CLI 的安装状态和路径：\n\n| 检测状态 | 指示器 | 说明 |\n|----------|--------|------|\n| 已配置且可用 | 绿色勾选图标 | Claude CLI 已安装并可执行 |\n| 已配置但不可用 | 红色叉号图标 | 配置了路径但无法执行 |\n| 未检测到 | 红色叉号图标 | 未在标准路径中找到 Claude CLI |\n\n### Claude 路径配置\n\n支持用户手动指定 Claude CLI 的可执行文件路径：\n\n```typescript\ninterface ClaudeConfig {\n claudePath?: string; // 用户配置的路径\n claudeDetectedPath?: string; // 系统检测到的路径\n claudeAvailable: boolean; // 是否可用\n}\n```\n\n## 应用设置系统\n\nSettingsDialog 组件提供了完整的应用配置管理界面。\n\n### 遥测数据收集\n\nHumanLayer 提供可选的性能和错误报告功能，用户可以随时更改偏好设置：\n\n```typescript\ninterface UserSettings {\n optInTelemetry: boolean; // 是否启用遥测\n advancedProviders: boolean; // 是否启用高级提供商\n theme: 'light' | 'dark' | 'system'; // 主题设置\n}\n```\n\n**收集的数据范围**\n\n| 数据类型 | 说明 |\n|----------|------|\n| 错误堆栈信息 | 帮助诊断应用崩溃问题 |\n| 性能指标 | 应用响应时间和资源使用情况 |\n| 匿名使用统计 | 功能使用频率等匿名数据 |\n\n**不收集的数据**\n\n- 用户提示词或对话内容\n- 代码内容或文件路径\n- API 密钥或个人身份信息\n- 工作目录名称\n\n### 日志管理\n\n应用将运行日志存储在本地文件系统，SettingsDialog 提供了日志路径显示和一键复制功能：\n\n```typescript\n// 获取日志文件路径\nconst logPath = await getLogPath();\n\n// 复制日志路径到剪贴板\nconst handleCopyLogPath = async () => {\n await navigator.clipboard.writeText(logPath);\n};\n```\n\n## 窗口管理\n\n### 窗口状态栏\n\nLayout 组件在窗口底部显示状态栏，提供实时系统状态信息：\n\n| 区域 | 内容 | 说明 |\n|------|------|------|\n| 左侧 | 应用标识 | \"humanlayer\" 文字标识 |\n| 中部 | 连接状态 | 健康状态或重连按钮 |\n| 右侧 | 开发模式信息 | DEV 模式下显示 URL |\n\n### 状态指示器\n\n```typescript\n// 健康状态显示\n{healthStatus === 'degraded' && (\n \n)}\n\n// 断开连接时显示重连按钮\n{!connected && !connecting && (\n \n)}\n```\n\n## 安全特性\n\n### 内容安全策略（CSP）\n\nTauri 配置中定义了严格的内容安全策略：\n\n```\ndefault-src 'self'; \nscript-src 'self'; \nstyle-src 'self' 'unsafe-inline'\n```\n\n该策略确保：\n\n- 所有资源只能从应用自身加载\n- 脚本只能执行同源代码\n- 样式允许内联以支持组件样式\n\n### 权限管理\n\n应用采用\"危险跳过权限\"（DangerouslySkipPermissions）功能，允许高级用户在特定条件下绕过审批流程：\n\n```typescript\ninterface SkipPermissionsConfig {\n useTimeout: boolean; // 是否启用超时自动禁用\n timeoutMinutes: number; // 超时时间（分钟）\n confirmed: boolean; // 用户是否已确认警告\n}\n```\n\n此功能覆盖的操作类型：\n\n- 文件编辑和写入操作\n- Bash 命令执行\n- 文件读取操作\n- 子任务生成\n- 所有 MCP 工具调用\n\n> ⚠️ 警告：使用危险跳过权限功能存在安全风险，应谨慎操作。\n\n## 构建与部署\n\n### 开发环境启动\n\n```bash\n# 进入前端目录\ncd humanlayer-wui\n\n# 安装依赖\npnpm install\n\n# 启动开发服务器\npnpm dev\n```\n\n开发模式下，Tauri 应用会连接到 `http://localhost:5173` 的前端开发服务器，实现热重载功能。\n\n### 生产构建\n\n```bash\n# 构建前端资源\npnpm build\n\n# 构建 Tauri 应用\ncargo build --release\n```\n\n构建产物包括：\n\n| 平台 | 输出目录 | 可执行文件 |\n|------|----------|------------|\n| Windows | src-tauri/target/release/ | humanlayer.exe |\n| macOS | src-tauri/target/release/ | humanlayer.app |\n| Linux | src-tauri/target/release/ | humanlayer |\n\n## 故障排除\n\n### 常见连接问题\n\n| 问题症状 | 可能原因 | 解决方案 |\n|----------|----------|----------|\n| 显示\"未连接\" | 守护进程未启动 | 点击\"重试连接\"或重启应用 |\n| 显示\"运行异常\" | 守护进程崩溃 | 使用 DebugPanel 重启守护进程 |\n| 无法检测 Claude | CLI 未安装 | 安装 Claude CLI 或配置路径 |\n| 超时设置无效 | 输入值超出范围 | 确保超时值在 1-60 分钟之间 |\n\n### 日志诊断\n\n日志文件路径可通过设置界面复制，便于提交问题报告时提供诊断信息：\n\n1. 打开设置对话框\n2. 找到\"日志\"部分\n3. 点击复制按钮获取路径\n4. 使用文件管理器导航到日志目录\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：humanlayer/humanlayer\n\n暂未发现结构化踩坑项；仍需完成沙箱安装和 Quick Start 验证。\n\n\n", "summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。", "title": "Human Manual / 人类版说明书" }, "pitfall_log": { "asset_id": "pitfall_log", "filename": "PITFALL_LOG.md", "markdown": "# Pitfall Log / 踩坑日志\n\n项目：humanlayer/humanlayer\n\n暂未发现结构化踩坑项；仍需完成沙箱安装和 Quick Start 验证。\n", "summary": "用户实践前最可能遇到的身份、安装、配置、运行和安全坑。", "title": "Pitfall Log / 踩坑日志" }, "prompt_preview": { "asset_id": "prompt_preview", "filename": "PROMPT_PREVIEW.md", "markdown": "# humanlayer - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 humanlayer 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的软件开发与交付任务。\n我常用的宿主 AI：claude / Claude Code\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 示例引导, 判断线索。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- 安装前能力预览: The best way to get AI coding agents to solve hard problems in complex codebases. 输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. project-overview：项目概览。围绕“项目概览”模拟一次用户任务，不展示安装或运行结果。\n2. technology-stack：技术栈。围绕“技术栈”模拟一次用户任务，不展示安装或运行结果。\n3. system-architecture：系统架构。围绕“系统架构”模拟一次用户任务，不展示安装或运行结果。\n4. session-management：会话管理。围绕“会话管理”模拟一次用户任务，不展示安装或运行结果。\n5. approval-workflow：审批工作流。围绕“审批工作流”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. project-overview\n输入：用户提供的“项目概览”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. technology-stack\n输入：用户提供的“技术栈”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. system-architecture\n输入：用户提供的“系统架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. session-management\n输入：用户提供的“会话管理”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. approval-workflow\n输入：用户提供的“审批工作流”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / project-overview：Step 1 必须围绕“项目概览”形成一个小中间产物，并等待用户确认。\n- Step 2 / technology-stack：Step 2 必须围绕“技术栈”形成一个小中间产物，并等待用户确认。\n- Step 3 / system-architecture：Step 3 必须围绕“系统架构”形成一个小中间产物，并等待用户确认。\n- Step 4 / session-management：Step 4 必须围绕“会话管理”形成一个小中间产物，并等待用户确认。\n- Step 5 / approval-workflow：Step 5 必须围绕“审批工作流”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/humanlayer/humanlayer\n- https://github.com/humanlayer/humanlayer#readme\n- README.md\n- humanlayer.md\n- hld/README.md\n- hld/go.mod\n- humanlayer-wui/package.json\n- hlyr/package.json\n- packages/database/package.json\n- hld/daemon/daemon.go\n- hld/rpc/server.go\n- hld/api/handlers/server.go\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 humanlayer 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n", "summary": "不安装项目也能感受能力节奏的安全试用 Prompt。", "title": "Prompt Preview / 安装前试用 Prompt" }, "quick_start": { "asset_id": "quick_start", "filename": "QUICK_START.md", "markdown": "# Quick Start / 官方入口\n\n项目：humanlayer/humanlayer\n\n## 官方安装入口\n\n### Node.js / npx · 官方安装入口\n\n```bash\nnpx humanlayer\n```\n\n来源：https://github.com/humanlayer/humanlayer#readme\n\n## 来源\n\n- repo: https://github.com/humanlayer/humanlayer\n- docs: https://github.com/humanlayer/humanlayer#readme\n", "summary": "从项目官方 README 或安装文档提取的开工入口。", "title": "Quick Start / 官方入口" } }, "validation_id": "dval_cc65ea76d26b466faad5efb5f34affb5" }