HiBuddy 开发文档

版本 v0.1（原型阶段）· 本文档与 specs/001-csic-party-school-mvp/ 规格保持同步

核心概念

概念	定义
角色 Role	岗位模板 × 个人上下文；决定订阅事件、默认轻应用与 AI 工作口径。千人千面的组织方式。
事件 Event	驱动工作的最小单元。五类来源：系统 / IM / 邮件 / 周期 / 人工。AI 预处理，人确认。
轻应用 Light App	确定性内核（表单/状态机/规则）+ AI 边缘（提取/建议/沟通）+ 进化机制（AI 提案 → 人确认 → 版本化可回滚）。
Skill	个人/组织经验的最小沉淀单元，可在角色间共享、在市场流通。
Agent	事件的自主执行者，受权限沙箱、预算熔断、Human-in-the-Loop 三重约束。
MCP	Model Context Protocol，HiBuddy 与外部能力之间的唯一集成协议。

快速开始

创建组织：注册即建立组织租户与管理员角色。
导入成员并指派角色：管理控制台粘贴名单「姓名,部门,角色ID」批量导入。
确认推荐编排：系统按角色推荐 MCP / 智能体 / 轻应用 / 模型档位，勾选确认即生效。
挂载 MCP 服务：登记 endpoint 与凭证（存凭证保险库），自动同步 tools/list。
员工打开工作台：事件收件箱开始工作——AI 已处理大部分，人只确认。

演示环境：中船党校原型（4 个角色可切换，12 类事件可交互）。

事件总线

事件信封（Envelope）：

{
  "id": "evt_20260726_0001",
  "type": "E01",                      // 内置 E01–E12 或 external.<source>.<name>
  "source": "schedule",               // system | im | email | schedule | manual
  "roleTargets": ["role_teacher"],
  "title": "今日选题推荐（5 条）",
  "payload": { /* 按类型定义 */ },
  "aiResult": { "summary": "...", "draft": "...", "confidence": 0.86 },
  "requireConfirm": true,             // 默认 true：AI 不产生外部副作用
  "status": "pending_review"
}

生命周期：接入 → 富化（AI 补全上下文）→ 分派 → 执行 → 待确认 → 人确认/忽略 → 回执 → 沉淀（Skill/知识库/规则）。置信度 < 0.6 直接转人工，不自动草拟。

轻应用

确定性内核：表单、状态机、规则集——保证数字与流程 100% 可预期。
AI 边缘：信息提取、判断建议、沟通草拟——附引用、带置信度。
进化机制：运行数据 → AI 生成优化提案 → 人确认 → 新版本灰度发布 → 可一键回滚。内核变更必须人确认，AI 只能自动改 AI 边缘。

MCP 接入

传输优先 Streamable HTTP（兼容 SSE）；认证 token / oauth2 / none；凭证一律存凭证保险库，HiBuddy 侧不留明文。

挂载后 HiBuddy 自动同步 tools/list，按角色授权使用；服务离线时相关轻应用「内核可用、AI 边缘挂起」，事件继续入箱并标注等待恢复。

标杆集成：中船党校 AI 助手（M01）——客户侧工具型产品经 MCP 被 HiBuddy 集成，课件生成 / 政策问答 / 校内检索 / 班次查询四类工具映射至轻应用 AI 边缘。契约详见 contracts/mcp-integration.md。

API 参考

Core API 采用 OpenAPI 3.1 契约先行（contracts/openapi.yaml），主要端点：

端点	说明
`GET /events`	拉取当前角色的事件收件箱（按订阅过滤）
`POST /events`	外部系统注入事件（CSIC 桥接使用）
`POST /events/{id}/actions`	人工动作：confirm / edit_confirm / dismiss
`GET/POST /roles`	角色模板列表 / 自定义角色（派生）
`GET /roles/{id}/recommendations`	角色推荐编排（MCP/智能体/轻应用/模型）
`GET /roles/{id}/export`	导出角色配置（资产归客户）
`POST /light-apps/{id}/versions`	发布新版本（AI 提案须 approvedBy 人批准）
`POST /light-apps/{id}/rollback`	回滚到指定版本
`GET/POST /mcp-services`	MCP 服务列表 / 挂载新服务
`GET/POST /credentials`	凭证保险库（永不返回明文）
`GET /audit-logs`	审计日志

部署与私有化

SaaS：注册即用；当前演示环境 thinkalike.com.cn/hibuddy，将切换至独立域名。
专有云：VPC 数据隔离，独立租户资源。
私有化：全栈交付（容器化），默认适配国产模型（DeepSeek / Qwen），支持 BYOM；审计与凭证保险库本地闭环。

安全与审计

确定性红线：AI 草拟内容默认不直发；涉及资金/人事/对外发送的动作必须人确认。
凭证保险库：加密存储、按角色授权、AI 代理调用、永不展示明文、异常巡检（E08）。
全程审计：事件接入、AI 处理（模型/token/耗时）、人工操作、轻应用版本变更，全部可回溯。
资产归客户：角色/轻应用/Skill/知识库可导出、可迁移，写进合同。