happyclaw: Instructions file for Claude Code

HappyClaw — 工程协作指南

本文档描述当前代码的工程约束和导航入口，供人类与 AI 协作者共同使用。

1. 文档与代码真相源

• 产品介绍、安装和常用操作：README.md
• 路由族与主要 Web API：docs/API.md
• 权限边界：docs/ACL-MATRIX.md
• 生产部署与回滚：DEPLOYMENT.md
• 运行时 Prompt：container/agent-runner/prompts/
• 数据库 Schema：src/db.ts 中的 CURRENT_SCHEMA_VERSION 与建表/迁移代码
• Web 路由：web/src/App.tsx
• 系统设置及默认值：src/runtime-config.ts
• 渠道能力与会话路由：src/im-channel-capabilities.ts、src/channel-mount-service.ts
• StreamEvent：shared/stream-event.ts
• 模型连接预设、模型列表解析与上游错误分类：shared/model-providers.ts
• 第三方代码与许可：THIRD_PARTY_NOTICES.md

docs/agent-first-architecture-plan.md 和 docs/claude-code-plugin-automation-design.md 是历史设计记录，不作为当前接口或数据结构的真相源。

2. 产品模型

HappyClaw 是基于 Claude Agent SDK 的自托管、多用户 Agent 工作台，支持 Web 与飞书、 Telegram、QQ、钉钉、微信、企业微信、Discord、WhatsApp。

当前产品层级：

Agent Profile（身份、四段 Prompt、能力策略）
└── Workspace（文件目录、执行模式、工作方式、环境变量、话题群绑定）
    ├── Runtime Session（独立 Claude 上下文，可绑定私聊或普通群；Host 工作区可选独立 git worktree）
    ├── Native Context Session（飞书话题等原生线程）
    ├── Automation（自动化：按计划把提示词作为真实的一轮发进会话）
    └── Work Item（工作项：一件被授权的工作，由自己的执行会话完成；来自团队模式的群，
                   或多任务工作区里派出它的会话）

重要命名边界：

• agent_profiles 是产品级 Agent。
• registered_groups 是当前兼容层中的工作区和渠道路由记录。
• agents 表及 /api/groups/:jid/agents 是历史命名，实际表示工作区内的运行会话， 不是产品级 Agent Profile。
• 工作区没有主会话，会话之间一视同仁：工作区 JID 不是任何会话的聊天地址，每个会话都是 agents 行（kind='conversation'），地址为 <工作区JID>#agent:<id>；工作区可以一个 会话都没有。会话列表的顺序（用户置顶的在前，然后按最近活跃）由 shared/session-order.ts 给出，Web 与 IM /list 共用；置顶按用户记在 user_pinned_sessions。旧库里每个工作区的 隐式主会话由 v88 迁移成普通会话（source_kind='legacy_main'），历史、Claude 上下文、 模型选择、渠道绑定和自动化随之迁移。
• 同一个 Workspace 内的会话共享工作区文件目录，但拥有独立 Claude Session； 工作区文件隔离与对话上下文隔离是两件事。
• 自动化（Automation）属于 Workspace，每次运行都是某个真实会话里的一轮：绑定已有会话 （Agent 在聊天里创建时默认绑定当前会话）、每次新建或持续会话。运行会话是普通 agents 行（source_kind='automation'、automation_id），不是 kind='task'。
• 例外是独立 worktree 的 Runtime Session：Host 工作区的工作目录是 git 仓库时，新建会话 可选它，宿主在 data/worktrees/{folder}/{sessionId} 建分支 happyclaw/<短 id>，该会话 每轮以它为 cwd，文件面板、项目 Skills 和 Review 面板也以它为根。worktree 缺失或损坏时 运行失败，不回退到主仓库；删除会话时移除 worktree、保留分支，有未提交改动或已初始化的 子模块时须确认。同一目录上的会话可以同时运行，界面不做提示。
• 团队模式（Team mode）按群开启（v1 只支持绑定到工作区某个会话的飞书普通群），关闭时 任何行为不变，群回到它绑定的会话。开启后，宿主为该群建一个路由会话 （source_kind='team_router'，不是群绑定的那个会话）， 每个被接下的请求成为一个工作项（work_items），由它自己的执行会话 （source_kind='work_item'；Host 工作区的 git 仓库用 worktree 会话）完成。只有路由会话在群里 说话；执行会话只能发一次确认，结果经 work_report 回流给路由会话。工作项的阶段 （等你回答、等你批准、受阻、失败、工作中、等待新消息）由记录派生，不存储。
• 工作区有工作方式 work_mode（存于 workspace_agent_profiles）：single（单任务，默认） 一条输入处理完再处理下一条，长任务在会话内完成，行为与没有这个设置时一致；multi（多任务） 下，普通会话可以用 work_delegate 把较大的任务派给 Worker，这一轮随即结束，会话继续接下一条 输入。派出的任务是派发型工作项（work_items.origin='delegated'），由它自己的执行会话 （source_kind='work_item'，不建 worktree，与派出它的会话共用工作目录）完成；Worker 只用 work_report（progress、ready、blocked、failed）。ready、blocked、failed，以及并非派出会话自己 work_stop 造成的停止（state="stopped"），以 work_item_input 注入派出它的会话，排在当前轮次 之后、不 steer，回复沿用派出那一轮所回答输入的来源路由；派出的会话转述给用户，用 work_followup 把用户的回答转给 Worker。派发、停止和跟进都只接受工作区主人亲自发起的轮次 （与 install_skill 同一闸门；派发请求不带 inputTurnId 时按非主人拒绝），每个会话最多 3 个、 每个工作区最多 5 个未结束，并受计费闸门约束；处理回报的那一轮不算主人亲自发起。独立 worktree 会话与自动化运行会话不能派发。Worker 的 summary 不超过 4000 字，更长的结果写进文件。Worker 一轮结束却没交回 ready、failed 或 blocked，或运行失败、被计费拒绝时，任务记为失败并告知派出的 会话；/break 与停止不会取消排队中的派发回报（会话没有在跑的查询时立即交出处理），/clear、 /fresh 把它们排到重置之后照常处理。删除派出的会话会停止它未结束的任务。切回 single 后，还有未结束派发项的会话仍按多任务运行到它们结束（只是不能再派），切换不中断运行， 暖 Runner 在本轮结束后退役。团队模式的代码路径只处理 origin='team' 的工作项。