Skip to main content

产品规划总纲 — h.work

用途。 自上而下地说清楚 h.work 是什么、做什么、各模块成熟度如何、未来走向何处。 这是位于各类明细追踪文档之上、此前缺失的「产品总纲」层。新成员、AM、相关方应当只读这一份文档,就能端到端理解整个产品。

本文档是汇总型的,不是事实源。 它刻意以「总结 + 链接」代替「复制」。当本文档与更具体的来源冲突时,以具体来源为准:

English version: PRODUCT_OVERVIEW.md 最近审阅: 2026-06-30 · 对照 origin/dev @ 569d7cbe。

1. h.work 是什么​

h.work 是 Humanity Protocol(HP)的内部平台,用于向客户公司交付一套托管式的 「AI + 专家」 服务。

客户(客户公司里的某个员工 —— 例如 Acme Financial 的 Amy)向分配给他的 Specialist 人设(例如 Eleanora Voss)发消息。AI agent 起草回复;草稿被路由给一位 HP Expert(真人,例如 David Kim),由其审核并以 Specialist 的身份发出。客户体验到的是一个一致、专业的人设,真人审核者从不暴露。

它不是一款客户用来支持自家终端用户的客服产品。 它是 HP 自己用来在众多客户 org 之间运营这套托管服务的运营平台。

原则落到实处的含义
默认人工复核(HITL)autoRespondThreshold = 101(从不自动发送)。每一条 AI 草稿都进 Expert 复核。AM 在 onboarding 时按客户调阈值。
人设完整性客户只会看到 Specialist(名字、头像、邮箱别名)。Expert 身份从不泄露 —— 聊天里没有、邮件头里没有、也不 BCC。
多租户、分层隔离隔离是按资源类别分层的,不是单一全局边界。PII / 会话 / 队列项按 Org × Specialist 隔离;KB 为 K1(租户)+ K2(Specialist 全局);见 ADR-020。
Agent 出错时 fail-openAgent 不可达时返回一条安全的升级提示并进 Expert 队列 —— 绝不把 500 抛给客户。

谁在用(角色)​

角色界面是谁
Client(org_admin / org_member)/client/*客户公司的员工。与其 Specialist 聊天。
Expert/workspace/*HP 的真人审核者。以 Specialist 身份审核/编辑/发送 AI 草稿。
AM(客户经理)/ops/*HP 员工,负责 onboard 与管理客户 org、分配 Specialist。
SuperAdmin/ops/*平台管理员。创建/管理 Specialist 与 Expert。
Specialist—(非登录账号)一个 AI 人设,不是用户账号。被分配给客户。

术语是关键 —— 见 CLAUDE.md 中的术语表与 features/roles-and-permissions.md。用错词(agent/bot/workspace/tenant)在 code review 里是一个信号。

2. 核心流程​

整个产品都围绕一个闭环组织:一条客户消息,变成一条经过复核、以人设署名的回复。

客户消息  ──►  入站渠道(web / email / WhatsApp / Slack / Telegram)
                  │  去重 + org×specialist 路由
                  ▼
          ConversationsService  ──►  Agent 服务(POST /v1/chat,Hermes/RIG runtime)
                  │                        │  检索(KB)+ 人设 +(规划中)工具
                  ▼                        ▼
          结构化 JSON: { reply, confidence, risk_level, flag_for_review }
                  │
       confidence < 阈值 或 risk ≥ HIGH  ──►  ExpertQueueItem
                  │                                │
                  ▼                                ▼
          Socket.io 推送给 Expert          Expert 在 /workspace 复核
          (8s 轮询兜底)                    接受 / 编辑 / 从头重写
                  │                                │
                  └──────────────►  以 Specialist 身份发出回复  ──►  客户
                                    (Gmail DWD / 渠道分发器,三层保护)

详见:features/expert-queue.md、features/auto-reply.md、features/conversation-status-lifecycle.md。

3. 架构速览​

服务技术栈职责
api/NestJS 11(TypeScript)、PostgreSQL 16 + pgvector、TypeORM、Socket.io控制面:REST + WebSocket、认证、会话、Expert 队列、计费、渠道、KB 检索。
agent/FastAPI(Python 3.11)、Hermes/RIG runtime、GPT-4oAI 起草、风险分类、工具调用。
frontend/Next.js 16 + React 19客户 Portal(/client)、Expert workspace(/workspace)、统一 Ops 界面(/ops)。
rag/Haystack 2.x + Hayhooks、pgvector检索流水线(混合 BM25 + 向量 + RRF + rerank)。

部署为多实例 active-active(staging + prod)—— 这是硬约束。无进程内共享状态、无 setInterval 定时任务、无 sticky session;跨 pod 协调通过 Redis / Postgres / BullMQ。见 ADR-018 及 CLAUDE.md 的 Deployment Model 章节。

基建方向:生产环境从 Railway → AWS ECS 迁移(#701,当前最高优先级的基建项;见 DEFERRED_M1_WORK.md)。RAG 已在 staging+prod 跑在 ECS Fargate 上(ADR-024)。

4. 功能模块蓝图​

产品拆分为下列模块。状态是汇总后的概览 —— 单个功能的事实以所链接的 implementation-status.md 章节为准。

#模块成熟度一句话范围深度文档
1认证与角色🟢 完成邮箱/OTP 登录、2FA、Google SSO、JWT、两层角色、Postgres RLS§1 · roles
2客户 Onboarding🟢 完成AM 校验门禁 → 3 步客户 SPA → org 激活§2 · onboarding
3客户 Portal 聊天🟢 完成会话线程、Specialist 人设展示、渠道徽标、试用横幅§3
4Expert Workspace🟡 主体完成队列、AI 建议 + 置信度/风险、接受/编辑/发送、内部备注§4 · workspace
5会话管理🟢 完成状态生命周期、snooze、分配、全文搜索、审计、SLA 跟踪§5
6渠道适配器🟡 参差邮件(Gmail DWD)+ WhatsApp + Telegram 已上线;Slack 部分;Teams/WeChat stub§6 · channels
6a第三方集成(Nango + 定制)🟡 框架就绪Nango OAuth 目录;Shopify/Amazon 已上线;QuickBooks/Xero 未接线;Jumio 骨架§6a
7Specialist 管理🟢 完成创建/分配 Specialist、per-OSA 邮箱别名、按 org 置信度阈值§7
8通知与实时🟡 部分Socket.io + SSE + 站内通知已上线;push / 邮件 / 偏好待补§8 · notifications
9分析与报表🟡 部分SA 分析已上线;Expert leverage 完成;per-org 毛利待补§9
10计费与订阅🟢 完成Lago、per-Specialist 月费、客户 + Ops 双侧界面、Stripe 作为 PSP§10 · billing
11出站 Webhooks / API🔮 未来按 org 的签名事件订阅 —— 未开始§11
12移动端🟡 仅 PWA响应式 PWA 已上线;原生 App + push 未做§12
13知识库与学习🟢 主体完成K1+K2 KB、混合检索+rerank、客户 KB UI、纠正捕获§13 · ADR-008
14平台 Ops 与 Admin🟡 部分健康、指标、审计、impersonation、DLQ 管理;工具权限 UI 待补§14 · audit
15AI Agent Runtime🟡 演进中Hermes/RIG 聊天 runtime;业务工具尚未上聊天主链路;SSE 部分§15 · AGENT_ARCHITECTURE
16Dogfood(Acme/Eleanora/KYC)🟡 部分首个 dogfood org;Jumio E2E 卡在缺 sandbox 账号§16

成熟度图例: 🟢 完成(可用于生产)· 🟡 部分 / 参差 · 🔮 未来(未开始)。

5. 当前进度快照​

阶段: 面向首个付费客户(「Kaito-launch」) 的上线冲刺。

今天已经扎实的(happy path 端到端跑通):

  • 客户可以被 onboard、通过 web/email/WhatsApp/Telegram 与 Specialist 聊天,AI 起草、Expert 复核并以 Specialist 身份发出,org 按所分配的 Specialist 经 Lago 计费。
  • KB 检索、多租户/RLS、审计、实时推送、出站的熔断/DLQ 保护、优雅停机均已到位。

边界仍在的地方(杠杆最高的几个缺口):

  • Specialist 的专业度未被度量 —— 质量依赖手写 prompt + 良好检索;没有领域准确性 eval,没有 grounding 校验,Expert 编辑信号被丢弃。(这正是 ADR-033 的论点。)
  • 业务工具尚未接到实时聊天链路 —— Specialist 能谈论 KYC/订单/财务,但还取不到真实数据。
  • 渠道可靠性/可观测性 —— 分发 DLQ 积压约 3 万条(#3444);per-channel 指标有限;还有若干入站 bug(跨渠道串话 #3558、WhatsApp 出站 #3506)。
  • 生产硬化 —— Railway → ECS 迁移(#701)、可观测性栈(SigNoz/Langfuse/PostHog #1230/#1231/#1232)。
  • 测试覆盖 —— 前端测试覆盖偏薄(#171)。

最近审阅时约有 87 个 open issue;实时数量与优先级请以 GitHub 为准,而非本文档。

6. 路线图(Now / Next / Later)​

按意图组织,而非按日期。每项都链接其追踪 issue/epic。优先级标签在 GitHub 上;此处是战略分组。

Now —— 为首个付费客户扫清障碍、止血​

  • 生产 Railway → ECS 切换 —— #701 · RDS Proxy IAM #1107
  • Kaito 上线前 UAT 冒烟清单 —— #1198
  • 渠道可靠性 —— DLQ 积压 #3444、WhatsApp 生产配对/出站 #3169/#3506、跨渠道串话 #3558
  • Expert workspace P0 bug —— AI 答复面板错配答案 #3504
  • Onboarding 稳定性 —— 邀请链接流程异常 #3520/#3522

Next —— 让 Specialist 真正专业且可观测​

  • ★ 专业 Specialist 架构 —— ADR-033 / Epic #3322。分层流水线;度量优先。第一块砖:捕获 Expert 编辑差异信号 #3323。
  • 把业务工具接到聊天链路 —— KYC/Jumio #230、QuickBooks/Xero/财务工具 #176
  • 可观测性栈 —— SigNoz APM #1230、Langfuse LLM trace #1231、PostHog 产品分析 #1232、渠道可观测性 epic #3532
  • 通知补全 —— push + 邮件 + 偏好 #170
  • Expert 获取流水线 —— 自助注册 + AI 筛选 + 激活 #1080
  • per-org 毛利 —— 货币化人力+基建成本 #3196
  • 前端测试覆盖 —— #171

Later —— 广度、打磨、战略性界面​

  • 移动端 —— 响应式审计 #2978、原生 App、深链
  • 更多渠道 —— Microsoft Teams #122、WeChat #378、出站媒体 #559
  • Settings 与事务邮件改版 —— #1690、#1258
  • 出站 webhooks / API 可扩展性 —— 客户 CRM/工单集成(战略,未立 issue)
  • Contact Profiles —— 跨会话统一的客户档案(战略,未立 issue)
  • Outbound Campaigns —— Specialist 主动外呼,待入站闭环稳定后(战略,未立 issue)
  • 纠正 → KB 自我改进闭环 —— 闭合飞轮(#303、#323)

7. 待产品拍板的开放决策​

这些需要产品/E 拍板后,依赖它们的工作才能干净地落地。权威清单(含选项 + owner):decisions/OPEN_DECISIONS.md。

ID / Issue需要决策的内容
OD-12客户是否应看到只读的「复核强度」标签(例如「始终由 Expert 复核」)?
OD-10Lago 计费模型:免费 plan_per_rate vs. premium license 的 plan_overrides。
OQ-205已关闭(2026-07-07,CD-30)→ ADR-037:运行时对 Specialist 资产只读;闭环提案、人审批。(原问题:Specialist agent 是否可将 skill 写回 R2?)
#154AM 是否有权改动客户团队成员?
#3501Expert 访问 agent 生成文件的存储 scope(per-agent / per-org / per-conversation)。
#3551「从聊天里呼叫 Specialist」(Tavus)并带上此前聊天上下文 —— 待产品决策。

8. 进一步下钻​

你想看……去读
需求验证、ICP/JTBD、竞争定位(凭什么赢)PRODUCT_STRATEGY.zh.md
任一功能的确切构建状态implementation-status.md
实时 backlog 与优先级GitHub Issues → FUTURE_REQUIREMENTS.md
某个架构选择的理由decisions/(ADR)
某个模块的具体设计features/(26 份模块文档)
UI/IA、流程、按角色的视图design/(INFORMATION_ARCHITECTURE、VIEWS_BY_ROLE、USER_FLOWS)
用户故事(C-/E-/SA- 编号)user-stories.md
上线就绪度mvp-launch-checklist.md
术语表与非显而易见的术语CLAUDE.md · GLOSSARY

维护:在每次上线阶段切换、或某个模块跨越成熟度边界时审阅。保持本文档轻薄 —— 细节下沉到所链接的来源,并向上回链。本文档与英文版 PRODUCT_OVERVIEW.md 应保持同步。

Last updated on by Alex Os