ARTICLE DETAIL

资讯详情

深耕编程入门与网站建设的一线实战洞察。

HumanLayer 开源仓库开发指南:面向 Claude Code 的 Monorepo 架构、构建命令与工程规范全解析

HumanLayer 开源仓库开发指南:面向 Claude Code 的 Monorepo 架构、构建命令与工程规范全解析 HumanLayer 开源仓库开发指南面向 Claude Code 的 Monorepo 架构、构建命令与工程规范全解析【免费下载链接】humanlayerThe best way to get AI coding agents to solve hard problems in complex codebases.项目地址: https://gitcode.com/GitHub_Trending/hu/humanlayer导读本文以仓库根目录的 CLAUDE.md面向 Claude Code 的仓库指引文档为核心骨架系统讲解 humanlayer 这一 Monorepo 的两大项目组划分、端到端架构流程、make开发命令体系、TypeScript/Go 双栈技术规范以及贯穿全仓库的优先级化 TODO 注释约定。读完本文你将掌握如何在复杂仓库中快速定位组件、正确执行构建与测试、遵循统一的代码规范参与开发并理解人类参与回路Human-in-the-loop能力在本地工具链中的落地方式。一、文档定位这不是 README而是 AI 编程助手的入职手册仓库根目录的 CLAUDE.md 是一份面向 Claude Codeclaude.ai/code的指导性文件用于在 AI 编程助手操作本仓库代码时提供上下文。它与面向最终用户的 README 定位不同它关注的是仓库内部结构、开发命令、代码规范与协作约定让 AI 助手以及任何新加入的开发者在最短时间内形成对仓库的正确心智模型。从内容性质看它具备三层价值结构地图快速识别 Monorepo 中的两个项目组及其组件边界操作手册给出统一的make命令入口与语言栈注意事项规范契约定义 TypeScript/Go 的编码准则与优先级化 TODO 标注体系。下文将逐一展开并结合仓库源码与子项目文档做纵深补充。二、仓库总览一个 Monorepo两个互联的项目组CLAUDE.md明确指出这是一个包含两个独立但互联项目组的 Monorepo项目组定位核心职责Project 1: HumanLayer SDK Platform核心产品为 AI Agent 提供人类参与回路Human-in-the-loop能力Project 2: Local Tools Suite本地工具套件基于 HumanLayer SDK提供丰富的审批与协作体验这两个项目组的依赖方向是单向的本地工具套件依托 SDK 平台能力实现具体功能例如将审批请求通过 Slack、Email 等渠道送达人类用户。2.1 Project 1HumanLayer SDK 与平台该组包含四个组件humanlayer-ts/—— 面向 Node.js 与浏览器环境的 TypeScript SDKhumanlayer-go/—— 用于构建工具的极简 Go 客户端本仓库中对应claudecode-go/的 Go 生态实践humanlayer-ts-vercel-ai-sdk/—— 面向 Vercel AI SDK 的专用集成docs/—— Mintlify 驱动的文档站点见 docs/ 目录包含 introduction.mdx、quickstart-typescript.mdx 等入门资料。核心概念联系渠道Contact Channels人类交互可通过 Slack、Email、CLI 与 Web 界面完成。以 hlyr/README.md 中的 CLI 实践为例你可以通过HUMANLAYER_SLACK_CHANNEL、HUMANLAYER_EMAIL_ADDRESS环境变量或.hlyr.json配置文件指定渠道未配置任何渠道时默认回退到 Web UI 进行人类交互。多语言支持Multi-language SupportTypeScript 与 Go SDK 保持功能对等feature parity。仓库中claudecode-go/即是一个 Go 语言实现的、用于编程方式启动 Claude Code 会话的 SDK详见 claudecode-go/README.md。2.2 Project 2本地工具套件该组是仓库中实际可运行的工程代码包含四个组件组件技术栈职责hld/Go守护进程Daemon协调审批并管理 Claude Code 会话hlyr/TypeScriptCLI 工具 MCPModel Context Protocol服务器用于 Claude 集成humanlayer-wui/Tauri ReactCodeLayer——桌面/Web 图形化审批管理界面claudecode-go/Go编程式启动 Claude Code 会话的 Go SDK其中humanlayer-wui/即产品代号CodeLayer是图形化审批管理的核心入口hld/是其后端动力来源见 humanlayer-wui/CLAUDE.mdThis is the humanlayer Daemon (HLD) that powers the WUI。三、架构流程从 Claude Code 到人类审批的完整链路CLAUDE.md用一张架构图描述了核心数据流Claude Code → MCP Protocol → hlyr → JSON-RPC → hld → HumanLayer Cloud API ↑ ↑ TUI ─┘ └─ WUI链路解读如下Claude Code作为 AI 编码代理通过MCPModel Context Protocol与hlyr通信——hlyr提供mcp serve与mcp claude_approvals两个 MCP 服务入口hlyr将请求通过JSON-RPC转发给hld守护进程hld负责会话管理、审批协调并连接HumanLayer Cloud API完成云端能力人类侧存在两条交互通道TUIhlyr的命令行界面与WUIhumanlayer-wui图形界面均可对审批请求做出响应。从源码结构看这条链路得到了充分印证hld/rpc/目录hld/rpc/实现了基于 Unix Socket 的 JSON-RPC 服务端包含approval_handlers.go、subscription_handlers.go等处理器humanlayer-wui通过~/.humanlayer/daemon.sock与守护进程通信见 humanlayer-wui/CLAUDE.mdThe WUI communicates with the daemon via JSON-RPC over a Unix socket纯属表现层所有会话与审批数据均来自 daemonclaudecode-go/通过MCPConfig配置mcp__approvals__request_permission权限提示工具实现审批工作流注入见 claudecode-go/README.md 的 MCP Integration 示例。四、开发命令以make为统一入口CLAUDE.md提供了一组顶层快速操作命令全部委托给根目录 Makefile 实现命令作用make setup解决整个 Monorepo 的依赖与安装问题make check-test运行所有检查与测试make check运行 lint 与类型检查make test运行所有测试套件4.1make check四组件并行检查根 Makefile 将check拆分为四个子目标逐一委托给各子项目的 Makefilecheck-hlyr: # hlyr 的 lint 类型检查 check-wui: # humanlayer-wui 的 lint 类型检查 check-hld: # hldGo的 lint 与 vet check-claudecode-go: # claudecode-goGo的 lint 与 vet执行make check前还会通过hack/run_silent.sh打印统一的检查头信息check-header目标。4.2make test覆盖四套测试体系test目标同样按组件拆分Makefiletest-hlyr—— CLI 单元测试test-wui—— WUI 测试humanlayer-wui使用 Bun 内置测试运行器关键 Store 逻辑测试位于 AppStore.test.tstest-hld—— Go 守护进程的单元与集成测试部分集成测试需-tagsintegration且 e2e REST API 测试通过make e2e-test运行详见 hld/README.mdtest-claudecode-go—— Go SDK 测试。组合命令make check-test即make check后接make test是 CI 与提交前验证的标准动作。根 Makefile 还提供了githooks目标可将make check test写入.git/hooks/pre-push。4.3 日常开发命令速查根 Makefile 中还沉淀了丰富的开发辅助目标源自仓库实际配置非 CLAUDE.md 原文make daemon-dev # 构建并启动开发版 daemon持久化数据库 ~/.humanlayer/daemon-dev.db make wui-dev # 以开发模式运行 CodeLayerTauri dev make codelayer-dev # 一键构建 daemon 并启动 WUI支持 TICKETENG-XXXX 隔离实例 make storybook # 运行 WUI 组件文档Storybook make generate-sdks # 依据 OpenAPI spec 重新生成 TypeScript SDK make daemon-ticket TICKETENG-2114 # 基于 ticket 号自动分配端口启动隔离 daemon其中codelayer-dev是一个值得注意的多进程编排目标当指定TICKET时它会调用hack/port-utils.sh中的端口分配函数为每个 ticket 计算独立的 daemon 端口、Vite 端口与 socket 路径实现并行隔离开发环境。五、GitHub Workflows 与发布流程CLAUDE.md提到两类与 GitHub 相关的操作触发 macOS 夜间构建gh workflow run Build macOS Release Artifacts --repo humanlayer/humanlayerWorkflow 定义位置.github/workflows/目录下。结合根 Makefile 可以看到夜间构建相关的本地流程daemon-nightly、wui-nightly-build、codelayer-nightly-bundle会在构建时通过-ldflags注入版本号、默认数据库路径~/.humanlayer/daemon-nightly.db、默认 socket 路径与 HTTP 端口7778等编译期常量与 nightly 发布产物一一对应。从 hld/config/config.go 看这些默认值以包级变量的形式存在专门设计为可通过-ldflags在构建时覆盖。六、TypeScript 与 Go 的开发注意事项6.1 TypeScript 子项目差异点由于 Monorepo 内 TypeScript 项目众多CLAUDE.md特别提醒包管理器不统一需查看各项目package.json判断使用 npm 还是 bun根目录与多数子项目均含bun.lock或package-lock.json构建/测试命令不同以各项目package.json的scripts段为准测试框架不统一部分项目使用 Jest部分使用 Vitest需查看devDependencies确认。以humanlayer-wui为例humanlayer-wui/CLAUDE.md 进一步补充了其团队约定优先使用 ShadCN 组件、Tailwind 样式、Zustand 管理全局状态、bun run lint与bun run typecheck验证改动并强调React 19 中ref已成为函数组件的标准 prop禁止使用已废弃的forwardRef。6.2 Go 子项目差异点Go 版本区间各模块go.mod中声明版本在 1.21 到 1.24 之间不等Makefile 优先检查目录下是否有 Makefile以其中声明的命令为准集成测试开关仅部分项目包含集成测试通常通过-tagsintegration编译标签启用例如 hld/Makefile 中的集成测试目标。6.3 hld 的 Go 风格红线hld/CLAUDE.md 针对守护进程代码给出了两条强制规范可作为 Go 子项目开发的参照任何异步或长时间运行的 goroutine 都应接受context.Context参数并能优雅处理取消context 与 CancelFunc 绝不能存储在结构体字段上必须始终作为函数第一个参数传递Context-first API 设计与根 CLAUDE.md 的技术指南一致。七、技术规范TypeScript 与 Go 的编码准则CLAUDE.md在 Technical Guidelines 中明确了两个语言栈的硬性要求TypeScript使用现代 ES6 特性严格 TypeScript 配置strict mode保持 CommonJS/ESM 双模块体系兼容从packages/contracts/同时存在tsconfig.json与tsconfig.types.json可以看出类型声明与构建产物是分离管理的。Go遵循标准 Go 惯用法Standard Go idiomsContext-first API 设计需要 mock 时使用make mocks生成对应各 Go 子项目 Makefile 中的 mock 生成目标。八、TODO 注释规范优先级化标注体系CLAUDE.md定义了一套全仓库统一的优先级化 TODO 注解系统这对 AI 助手理解代码中遗留问题的紧急程度至关重要标注优先级含义合入门槛TODO(0)Critical关键问题禁止合并never mergeTODO(1)High架构缺陷、重大 bug应尽快修复TODO(2)Medium小 bug、缺失功能常规迭代TODO(3)Low打磨、测试、文档可延后TODO(4)—待调查/待研究的问题需进一步调研PERF—性能优化机会非功能性改进在源码中可以看到该规范的实际应用例如hld/api/handlers/sessions.go、hld/approval/manager.go、hld/rpc/handlers.go、hld/session/manager.go中均存在按此格式标注的 TODO/PERF 注释。开发者或 AI 助手在遍历代码时应优先关注TODO(0)与TODO(1)级别的问题。九、附加资源与进一步探索路径CLAUDE.md最后建议查阅docs/获取面向用户的功能文档。结合本仓库实际可按以下路径深入面向用户文档docs/introduction.mdxCodeLayer 安装与 FAQ、docs/quickstart-typescript.mdxTypeScript 快速上手守护进程内部机制hld/PROTOCOL.md协议说明、hld/TESTING.md测试规范与数据库隔离要求、hld/CLAUDE.mddaemon 的调试指引含sqlite3 ~/.humanlayer/daemon.db与nc -U手工调用 JSON-RPC 的调试手法CLI 能力hlyr/README.mdcontact_human、mcp、thoughts、claude四大命令族图形界面humanlayer-wui/CLAUDE.mdWUI 日志路径、vim 风格快捷键与选区管理实现细节Go SDKclaudecode-go/README.md启动/流式输出/MCP 集成示例。开发环境提示本文涉及的开发命令make setup、make check-test等与调试手法daemon 日志位于~/.humanlayer/logs/daemon-*.log、数据库可通过 sqlite3 直接查看均以当前仓库实际配置为准部分命令如make daemon-dev依赖本机已安装 Go、Bun、Tauri 等工具链请按 Makefile 与各子项目 README 中的前提条件准备环境。【免费下载链接】humanlayerThe best way to get AI coding agents to solve hard problems in complex codebases.项目地址: https://gitcode.com/GitHub_Trending/hu/humanlayer创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表