Cadau 产品规格

版本：2.5.40（检查方案管理页可导入导出，2026-08-18）

一致性：Web 与移动端经 Go 后端 REST 统一接入；接口与交互细节以同目录 后端与Web设计.md 第 9 节（已确认决策） 为评审真值（v7.0+ 已与「自研 Runtime、不调用 OpenClaw」叙事对齐）。本文自 2.0.0 起为产品与技术对外的首要规格。

表述：凡产品能力、流程与界面相关说明，一律以用户表达为准——即用 用户能理解的自然用语、用户视角下的主语与场景（谁、在什么场景、得到什么结果）来书写；实现层术语（如 API 路径、数据库字段、运行时 Workspace 目录树等）仅在 §5～§7、实现备注或括号中分层给出，不以实现名词替代对用户说的话。命名：未选工作区时在「消息」中的引导对话能力，产品与文案统称为 「帮助智能体」。

---

1. 项目概述

1.1 项目名称

Cadau

1.2 项目定位

Cadau 是面向企业与团队的 AI 助手产品（多用户、多工作区协作）；Web 与移动端统一通过 Cadau Go 后端调用业务与对话能力。浏览器与移动端均不直连第三方「智能体网关」（历史上曾规划对接 OpenClaw，现已取消）。每个用户账号相互独立；用户可 创建工作区，并将其他用户 邀请或加入 自己任一所创建的工作区，在 工作区范围内 协作。共享资源、协作数据与配额 以 工作区 为主隔离边界（个人资源仍属用户维度，见 §1.5）。用户以 手机号或邮箱，通过 密码或验证码 注册/登录（双主路径，默认密码，见 §1.5.2）。

后端在 自研「智能体运行时」 上实现与原先设想一致的体验：多会话、用户智能体、技能与市场、记忆与个性化等，推理能力通过服务端持有的 LLM API（如 OpenAI 兼容接口或其它供应商）完成，由 Cadau 自行编排 Soul（灵魂/人格与行为内核）、Memory（记忆体系） 与 执行管线，不再依赖外部 OpenClaw 服务。实现上采用与 OpenClaw 同构的「文件优先 Workspace」范式（见 §3.5）：认知状态以 Markdown 落盘 + 运行时工具检索/写入，由 Cadau 代码实现，不调用 OpenClaw 网关或 CLI。产品需具备 自进化能力（见 §3.6）：在服务端闭环内积累 技能文档、长期记忆、用户画像 并支持 跨会话检索与复用，对齐业界「持久智能体」方向，但以 企业 SaaS 的审计与隔离 为约束自行实现。

1.3 核心价值

• 自主可控：智能体人格、记忆、工具与对话状态由 Cadau 自有数据模型与运行时管理，便于审计、合规与 多工作区、多用户 规模扩展。
• 持续演进：通过 §3.6 自进化与学习闭环，使智能体随使用改进可复用技能与记忆，而非单次会话即弃；进化过程 可配置、可审计（与开源单机助手差异化）。
• 统一体验：单一后端入口，品牌与交互一致；可扩展 Web、移动端与 SDK 嵌入。
• 能力聚合：LLM、检索、工具调用、业务 API 在后端统一编排，密钥不暴露给客户端。
• 工作区协作：多名用户在同一 工作区 内，在授权范围内共享协作资源与上下文，支撑团队使用场景。
• 对话即操作：用户说要做什么，助手就代做；只有用户问「如何 / 怎么」时才给说明书。缺参数就追问，不要改成「请到某某页自己点」。见 §4.1.5。

1.4 目标用户

• 企业用户：使用 AI 助手提升工作效率。
• SaaS 厂商：通过 SDK 嵌入 AI 能力。
• 团队与管理员：需要 工作区级 协作、成员邀请与权限分工的场景。

1.5 账号、工作区与协作

#### 1.5.1 用户与工作区模型

• 用户（User）：每个注册用户对应 一个独立账号；账号之间默认 不共享 个人数据。
• 工作区（产品概念）：用户可 创建一个或多个工作区；创建者可邀请其他用户加入 其所创建的任一工作区，协作与共享资源 以工作区为边界（同一用户可在不同工作区承担不同角色）。
• 与「运行时 Workspace」区分：本节「工作区」指 产品协作单元；§3.5 中的 Workspace 指 单个用户智能体实例下的文件目录树（SOUL.md 等），下文必要时称 「运行时 Workspace」，避免与产品「工作区」混淆。
• 业务数据（用户资料、智能体、会话与消息元数据、知识库、计费等）须 带用户维度 存储与鉴权；属工作区共享 的资源须同时带 workspace_id（或等价）并校验 成员身份；Runtime Workspace、记忆与自进化产物（§3.5、§3.6）须明确 属个人、属工作区共享还是属智能体实例，默认策略在实现中定义并满足 §3.6.2 隔离要求。
• 禁止跨工作区 越权读写（禁止在未授权下读取另一工作区数据）；运维与报表可按 用户 与 工作区 维度聚合。

#### 1.5.2 注册与登录（密码与验证码双路径）

• 双主路径：用户既可使用 手机号或邮箱 + 密码 登录，也可使用 手机号或邮箱 + 一次性验证码 登录/注册；两种路径在能力上 并列（均为正式登录方式），UI 默认展示密码登录（与 界面与布局.md §2 一致：默认表单为密码，验证码路径通过 Tab/切换等同层到达，而非藏入深层菜单）。
• 验证码路径：使用 POST /api/v1/auth/send-code，请求体区分 channel（如 sms / email）与 scene（如 register、login、reset_password）；成功后以验证码完成 register / login 等（字段级与错误码见 后端与Web设计.md 第 9 节）。
• 密码路径：注册时设置密码、登录时校验密码；与验证码路径 二选一完成登录（是否允许同一账号同时启用两种登录方式由实现与安全策略定义，须在接口文档中写明）。

#### 1.5.3 工作区与成员（多人协作）

• 创建工作区：已注册用户可 创建工作区，成为该工作区的 所有者/管理员（角色名实现可定），系统为该工作区分配 唯一 workspace_id。
• 加入工作区：通过 邀请 将其他用户纳入某一工作区：

- 邀请渠道：手机号或邮箱（与账号体系一致）； - 受邀人通过 验证码确认 或 邀请链接 + 身份校验 接受邀请，成为该工作区成员。

• 多人协作（产品目标）：

- 同一工作区内多名成员在 授权范围内 使用共享资源，例如：工作区知识库、团队可见的智能体/模板、会话与任务的协作策略（具体共享粒度与 RBAC 分阶段落地，见 §4.5）。 - 上下文切换：若用户属于 多个工作区（含自己创建与被邀请加入），客户端与 Token 须支持 当前工作区（current workspace） 切换；访问 工作区范围 资源时，后端在 workspace_id 上下文 下解析，避免串数据。

#### 1.5.4 时间显示与时区偏好

• 用户看到的时间：消息、通知、会话「今天/昨天」分组、工单、训练与审批记录、嵌入/能力到期、定时任务选择器与说明、更新记录日期、注册日等所有给人看的时间，默认按北京时间（东八区）、中文日期、24 小时制 展示，不跟随浏览器系统时区。
• 可改偏好：用户可在 我的 → 偏好设置 → 时间显示（手机端「我的」同区）中选择：

- 时区（默认北京时间）； - 日期格式：中文年月日（如 2026年8月5日）、年-月-日、年/月/日、月/日/年、日/月/年（默认中文年月日）； - 时间制式：24 小时制 或 12 小时 AM/PM（默认 24 小时制）。 选定后全站界面时间按该时区、日期格式与制式换算显示。每位用户独立配置，互不影响。

• 存盘约定（实现备注）：服务端与库表中的绝对时刻仍以 协调世界时（UTC） 存储与传输；时区、日期格式与制式只影响 如何给人看。定时任务「几点触发」仍按任务自身时区（默认亦为北京时间）计算，与界面显示时区可不同。
• 智能体对话中的「现在几点」：注入给帮助智能体 / 工作智能体的运行时时钟 优先使用当前用户账号的显示时区（制式仍用 24 小时便于解析）；若账号未设置则回退部署默认（MINDLINK_RUNTIME_TIMEZONE，默认北京时间）。定时任务触发时刻仍按任务自身时区计算。
• 接口（实现备注）：GET/PATCH /api/v1/auth/me 读写 timezone（IANA，默认 Asia/Shanghai）、date_format（ymd_cn / ymd / ymd_slash / mdy / dmy，默认 ymd_cn）、time_format（h24 / h12，默认 h24）。

---

2. 技术架构

2.1 系统架构图

     LLM 供应商 API（仅服务端持有密钥与路由策略）
                    ↑
          Cadau Go 后端
   ┌──────────────────────────────────────┐
   │  REST API：auth、chat、skills、agents… │
   │  自研智能体运行时（Cadau Runtime）   │
   │    · Soul 配置与解析                   │
   │    · Memory 写入/检索/摘要             │
   │    · 对话与工具执行编排                 │
   │    · 自进化：技能沉淀、记忆晋升、画像、跨会话召回 │
   └──────────────────────────────────────┘
                    ↑
        ┌───────────┴───────────┐
        │                       │
 Cadau Web              Cadau 移动端
 （HTTP REST + JWT）    （HTTP REST + JWT）

2.2 技术栈（客户端与接入层）

2.3 后端与运行时原则

---

3. 自研智能体运行时（Cadau Runtime）

本节描述为实现原产品设想而必须自研的 架构能力（名称仅为规格用语，实现可映射到具体模块/包名）。

3.1 Soul（灵魂 / 人格与行为内核）

定义：与用户智能体或市场模板绑定的 结构化配置，决定智能体「是谁、如何说话、默认目标、可用工具与边界」，在运行时被解析为系统提示、策略与工具清单。

要求：

• 与 用户智能体（user_agents）、市场模板（agent_templates） 的配置模型打通；支持版本与升级合并策略（见原规格中的 merge_mode 等概念）。
• 支持 提示词、工具/技能绑定、知识源引用 等字段；训练/发布后应能触发 Soul 生效版本 更新（与训练任务联动）。
• 执行对话时，Runtime 将 Soul 与当前会话、记忆检索结果 组装为模型输入（具体拼装策略由实现定义，需可测试、可审计）。

3.2 Memory（记忆体系）

定义：维持多轮对话连贯性与长期个性化的 存储与检索，至少区分以下逻辑类别（物理存储可合并）：

要求：

• 记忆写入、读取、删除须 带用户、智能体及工作区（若适用）维度 的授权校验；协作场景下「团队可见」记忆须显式策略，与 §1.5、§3.6.2 一致。
• 对外 REST 不要求暴露底层记忆块 ID 给浏览器（除非产品明确需要）；优先通过 chat 与「训练/知识库」接口间接使用。
• 摘要与向量索引的 异步任务、失败重试与一致性策略应在实现层定义并写入运维文档。

3.2.1 知识文档目录（全局 / 工作区 / 用户）

表述：产品上把 供智能体检索、作为应答依据的知识类文件（多为 Markdown；与 §3.2 表中「会话内记忆」「长期记忆中的动态沉淀」区分开）统称为 「知识文档目录」（实现层也可用 知识库存储根 / 挂载点等说法，对用户说明用本称谓即可）。

为满足 「同一工作区内、不同成员各自拥有的多个用户智能体能共用一套团队知识」（类似帮助智能体使用部署侧 HELP_DOCS_* 全局文档 的机制，但适用范围从「全租户帮助」收窄到 绑定 workspace_id 的协作边界），知识文档按下列 三层配置与检索（合并策略与向量/全文索引由实现定义，须可审计）：

与 §3.5「运行时 Workspace」的分工：本节 「知识文档目录」侧重 可被 RAG/检索批量引用的、按全局/工作区/用户分层的产品知识；§3.5 的运行时目录侧重 单体智能体的 Soul/Memory/日笔记执行态。二者可在编排层 拼接进同一次对话上下文，但在 隔离边界、配额与运维 上分治。

与 §3.2.2「规范库」、§3.2.3「资料库」、§3.2.4「检查方案」的分工：知识文档目录服务 对话答疑与团队 Wiki；法规与管理标准真源归 规范库；共用表格、表单/合同等可套用文件归 资料库；专家把条文操作化后的机读检查包归 检查方案（须依据规范，不冒充法规）——四者并列，勿混用入口与存储。

• [x] 正文插图与短视频：Markdown 文档可粘贴/上传 png/jpg/gif/webp 图片，以及 几秒到十几秒 的 mp4/webm 说明片（体积上限约 8MB）；落在文档旁 media/。可在编辑区调整宽度与左右居中对齐；预览与智能体问答可显示图片/播放短视频（对话侧经鉴权加载）。（2026-07-25）

3.2.2 规范库（法规与管理标准）

表述：工作区内维护的 法规、行业标准、管理制度与管理理论 统称 「规范库」（界面副题可用「法规与管理标准」）。它是 人力资源、合规管理 等多类应用插件与智能体答疑的 共用真源，不是 某一插件的私有文件夹，也 不是 §3.2.1 工作区知识文档的别名。

机制详稿：docs/core-mechanisms/规范库.md。

要求（产品决策，2026-07-25）：

• [ ] 工作区隔离：规范按 当前工作区 存放与鉴权；禁止跨工作区读。
• [x] 条目元数据：标题与正文（或附件）、类型（法规 / 行业标准 / 企业内部制度 / 管理理论等）、领域标签、文号与发布机关（适用时）、生效/废止日、来源（手工或官网）、状态（草稿 / 待审核 / 已发布 / 已废止）、版本。（Phase 1 已落地）
• [x] 正文格式：Markdown；编辑/预览切换；插图与短说明视频存于条目 media/，正文用相对路径引用；可调宽度与对齐（粘贴或选择上传；视频≤约 15 秒、≤约 8MB）。（2026-07-25）
• [x] 多维索引树（浏览方式，非知识文件夹）：工作区预置 地域 / 行业 / 类型 等分类维度；每维一棵可管理的树。同一规范可挂多个节点。界面「切换索引 → 左树 → 中列表 → 右正文」；树为浏览索引，不是知识物理目录。详稿 规范库.md §4.7（2026-07-25 已落地）。
• [x] 管理入口：协作页简介 +「管理规范库」→ /workspace/standards 全屏管理；保留草稿/审核/发布/废止。
• [x] 导入/导出：管理员可 导入 / 导出（zip；含正文、插图与分类挂载）；导入支持增量（相同跳过、草稿更新、已发布不覆盖），须再审核发布。
• [x] 智能体写入草稿：已选工作区时，智能体可用系统工具写入/更新规范库 条文草稿（须用户确认；禁止自动发布）；与知识文档、检查方案工具分治。（2026-08-07）
• [ ] 来源白名单：仅允许对工作区登记过的 官网域名/入口 自动抓取；白名单外地址不得写入自动更新结果。
• [ ] 爬取与发布分离：工作智能体或定时任务从官网抓取后，结果进入 草稿/待审核；发布后 才对普通成员答疑与插件生成生效。法规与强制标准 默认须人审；可指定启用日。
• [ ] 智能体答疑：默认只检索 已发布且已启用、未废止 的规范；回答尽量标明依据（文号/版本/来源）。业务事实（花名册、检查结论等）仍经各插件受控操作查询，不得用规范库冒充实时业务数据；不得把检查方案正文当法规注入。
• [ ] 插件共用：平台提供只读能力，供已接入的平台插件按领域标签或索引节点读取已发布规范；插件可据此预填调查表、展示依据等，但 生成检查项的机读包 见 §3.2.4 检查方案；须 预览并经人确认 后写入插件业务库，并记录 规范 ID + 版本（及方案 ID + 版本）。
• [ ] 变更传播：新版本发布后，向订阅该领域的插件推送 影响清单；禁止静默覆盖已落库的业务规则与数据；支持回滚已发布版本。
• [ ] 插件互调：跨插件业务调用（如合规查人事）经 Cadau 代签与审计；法规全文由各方读规范库，不经插件互传冒充真源。
• [ ] 与出厂模板：插件可自带默认模板；工作区已发布规范可覆盖或裁剪默认模板。
• [ ] 与资料库：规范可被资料库条目「依据」关联；空白业务表/填报模板本身放 §3.2.3 资料库，不以规范库当文件柜。
• [x] 与检查方案（2026-08-07）：专家实践机读包 不 进规范库冒充条文；放 §3.2.4 检查方案，必填依据本库条目。机制详稿 docs/core-mechanisms/检查方案.md、合规实践检查表转机读包.md。

3.2.3 资料库（模板与表格）

表述：工作区内团队共用的 表格、表单模板、合同样例、检查表空白版、自己做好的演示/文档/表格样式 等可下载、可套用文件，统称 「资料库」（界面副题可用「模板与表格」）。它服务 成员套用、智能体填表产出附件、平台插件开局/检查选用模板，不是 §3.2.1 知识文档（Wiki），也 不是 §3.2.2 规范库（条文真源），也 不是 §3.2.4 检查方案（机读包），更 不是 聊天会话附件或某一技能包内的私有 references/。

机制详稿：docs/core-mechanisms/资料库.md。

要求（产品决策，2026-07-25）：

• [ ] 工作区隔离：资料按 当前工作区 存放与鉴权；禁止跨工作区读。
• [x] 条目元数据：标题、短说明、文件（及版本）、类型（演示样式 / 文档样式 / 表格样式 / 表格模板 / 表单 / 合同样例 / 检查表空白版等）、领域标签、状态（草稿 / 已发布 / 已废止）、版本；可选 依据规范（规范库 ID + 版本）。
• [x] 权限：成员可浏览与下载 已发布 条目，并可看到自己的草稿。办公样式（演示/文档/表格样式）由上传者自己发布、废止；合同样例、检查表等仍由 工作区创建者/管理员 发布。导入/导出仍仅管理员。套用办公样式时 复制为新附件，不覆盖资料库原件。
• [x] 智能体使用：对话注入匹配资料 元数据；填表产出新附件依赖办公/脚本能力；禁止覆盖资料库真源。
• [x] 插件共用：GET /platform-plugins/assets… 只读已发布资料与文件流；选用时记录 资料 ID + 版本。
• [x] 与相邻对象分治：聊天附件、技能 references/、应用模板、智能体市场模板 不 充当资料库；勿把 Excel/Word 主存放进知识文档目录。
• [ ] 索引浏览（后续）：可按领域/用途等 索引树 浏览（与规范库同类：树为筛选视图，非知识物理目录）；首期扁平标签列表可用。
• [ ] 配额硬门控与自动填表工具链（后续）。
• [ ] 配额：文件占用计入工作区存储配额（与 §4.5 一致）。
• [x] 入口：工作区协作中与「知识文档」「规范库」「检查方案」并列展示；协作页简介 +「管理资料库」→ /workspace/assets 全屏管理（返回 + 标题 + 工作区名；左列表/右元数据与下载；按状态、类型、关键词筛选）。不照搬规范库索引树与 Markdown 正文。（2026-07-25）
• [x] 导入/导出：管理员可 导入 / 导出（zip；含说明与文件）；导入支持增量（相同跳过、草稿更新、已发布不覆盖），须再发布。
• [ ] 实践检查表原材料（2026-08-06）：类型含 检查表 时，可作为合规「实践检查表 → 机读包」技能的输入源；转换结果进 §3.2.4 检查方案草稿，不 在资料库内存机读包真源。见 docs/core-mechanisms/合规实践检查表转机读包.md、检查方案.md。

3.2.4 检查方案（实践机读包）

表述：工作区内维护的、把规范库条文 操作化 后的 机读检查包（及同类标准包），统称 「检查方案」（副题可用「实践机读包」）。它回答 「专家建议怎么查，才能符合规范」，不是 法规条文本身，也 不是 资料库里的 Excel/Word 原件。

机制详稿：docs/core-mechanisms/检查方案.md；转换流程见 合规实践检查表转机读包.md。

要求（产品决策，2026-08-07，方案 B）：

• [x] 工作区隔离：方案按 当前工作区 存放与鉴权；禁止跨工作区读。
• [x] 条目元数据：标题、说明、机读正文（Markdown）、领域标签、状态（草稿 / 待审核 / 已发布 / 已废止）、版本；必填依据规范（规范库 ID + 发布版本，可多条）；可选来源资料库条目。
• [x] 发布门控：无依据规范 不得发布；管理员发布后供插件选用；禁止自动发布。
• [x] 管理入口：协作页与规范库/资料库并列；「管理检查方案」→ 全屏管理（/workspace/check-schemes）。
• [x] 智能体写入草稿：系统工具写入/更新 检查方案草稿（须用户确认）；禁止用规范库条目或知识文档冒充检查方案。
• [x] 插件选用：合规调查问卷优先选择 已发布检查方案（界面展示其所依据的规范标题/版本）；生成检查项须预览与人确认；过渡期可回退规范库条目。
• [ ] 答疑边界：默认 不 把检查方案正文注入为「法规怎么说」；条文仍只来自规范库已发布内容。（系统提示已引导；检索注入边界待补强）
• [x] 存量迁移：已误作规范库「实践条目」发布的机读包，可经「管理检查方案 → 从规范库迁入」迁入本能力并补依据；迁入后废止/删除原实践包条目。
• [x] 导入/导出：管理员可 导入 / 导出（zip；含正文与依据规范标题/文号）；导入支持增量（相同跳过、草稿更新、已发布不覆盖），依据规范按标题/文号尽量挂回本工作区，须再审核发布。
• [ ] 与 HR 等扩展（后续）：胜任力等机读标准包可并入本模型；首期以合规为主。

3.3 执行与编排

定义：将一次用户请求转为 模型调用、可选多步工具调用、再汇总回复 的控制流。

要求：

• 支持 技能（Skills） 与 工具调用 的统一或分层模型；与 POST /api/v1/skills/execute 及聊天内触发策略一致（见历史决策或本文第 3.4 节功能列表）。
• 支持 幂等：客户端 request_id 与后端去重策略（见第 4 节）。
• 流式输出（SSE/WebSocket）可作为二期增强；首期可与历史一致以 完整 JSON 响应 为主，但架构上应预留流式扩展点。

3.4 与原有功能需求的对应关系

原有规格中的 Web 聊天、附件、多会话、技能列表、智能体市场、付费与训练 等 业务目标保持不变；变化仅为底层 由「对接 OpenClaw」改为「自研 Runtime + LLM API」。 管理员端若曾包含「OpenClaw 运行管理」，应调整为 模型路由、运行时健康、记忆索引与训练任务队列 等运维对象（详细可另起管理员规格修订稿，见第 10 节）。

3.5 文件优先 Workspace（实现范式，与 OpenClaw 同构）

本节约定 Cadau 如何实现 §3.1～§3.3：采用 「每个用户智能体一个运行时 Workspace + 固定语义 Markdown 文件 + 运行时工具」 的架构，与 OpenClaw 的 Memory / Workspace / SOUL 公开描述 同构（便于团队理解与对标），但 全部在 Cadau 进程与存储内实现，不依赖 OpenClaw 二进制、网关 WebSocket 或 CLI。注意：本节 Workspace 为 运行时目录树，与 §1.5 产品 「工作区」（协作单元）不同名相混时请以上下文为准。

#### 3.5.1 运行时 Workspace 边界

#### 3.5.2 标准文件（命名与职责）

以下 相对 Workspace 根 的路径与文件名 作为产品/工程约定（实现可额外生成索引或派生文件，但不应破坏下列语义）。

说明：上述文件均为 Markdown 文本；模型「能记住的」以 实际写入 Workspace 并经 Memory 工具检索 的内容为准，与 OpenClaw「无隐藏状态、落盘为准」的理念一致。

#### 3.5.3 运行时工具（模型可调用的能力）

Runtime 应向 LLM 暴露 与 OpenClaw 记忆工具同构 的最小集合（名称可一致，便于提示词迁移）：

可选增强（二期）：维基式知识层（对齐 OpenClaw memory-wiki 插件思想）、wiki_search / wiki_get 等，用于结构化知识与溯源。

备忘（与记忆分开）：用户主动存放的记录（文字 / 文件 / 图片），按 标签（唯一 / 可重复）与 保存日期 检索，相当于该智能体的小型资料库。不在每轮对话自动注入。默认 对话模式 下仅当用户明确要保存或查询备忘（含按标签查员工、请假、支出等）时才调用 memo_*；用户可把对话切到 备忘模式，此后若无特殊说明，写入和读取都针对备忘（仍可明确说「写进记忆」等改道）；切到备忘后对话旁会出现备忘小窗，助手改了备忘会马上刷新；关掉后留下的「备忘」按钮也可拖到别处。在小窗里点选备忘后，可直接在对话里改或删。文件与图片在保存或覆盖时须由模型给出内容说明。机制见 docs/core-mechanisms/智能体备忘.md。

#### 3.5.4 编排与并发（执行管线）

#### 3.5.5 Prompt 拼装顺序（实现约束）

拼装发给 LLM 的系统侧上下文时，建议顺序为：基础系统提示 → SOUL.md → AGENTS.md → USER.md（若有）→ 检索得到的 Memory 片段 → 当前会话消息；具体 token 分配与截断策略由实现文档细化，须 可单测（同一 Workspace 文件版本应对应确定性输入摘要）。

#### 3.5.6 与 REST / 客户端的边界

• 客户端 只 调用 §5 所列 REST；不接触 Workspace 路径与 SOUL.md 等原始文件。
• 用户通过 智能体配置、训练、知识库 等 API 修改的配置，后端应 同步到对应 Workspace 文件或生成新版本，保证 Runtime 单次执行所读文件与 DB 生效版本 一致。

3.6 自进化与学习闭环（Evolution Loop）

本节定义 Cadau 的 自进化：智能体在 不依赖外部 Hermes / OpenClaw 进程 的前提下，通过服务端 闭环任务 与 Workspace 落盘，随使用 积累并复用 知识与能力。 重要：业界（如 Hermes Agent）所述「自改进 / 学习闭环」通常 不等于「仅技能自动生成」一条线，而是 技能沉淀、记忆固化、用户建模、历史检索 等多条子链路的组合；Cadau 对齐完整愿景，并在 多用户、多工作区 场景下增加 强制治理约束。

#### 3.6.1 子链路（规格语义）

以下子链路 共同构成 自进化；实现可分期，但 数据模型与 Workspace 约定 须预留扩展，避免后期推倒重来。

说明：OpenClaw 的 Dreaming 主要对应上表中的 记忆晋升 子链路（后台整理、晋升长期记忆）；不等于 技能沉淀整条线。业界 Hermes 类「自进化」则更接近 上表多链路组合——本节采用后一种 完整 定义，避免将「自进化」窄化为单一机制。

#### 3.6.2 企业级治理（相对开源助手的必选项）

#### 3.6.3 工具与扩展（建议）

• MCP 兼容或适配：工具面宜支持 标准协议（如 MCP）接入外部能力，使「进化」产生的技能与 新工具 组合时 少改核心编排（与 §3.3 工具模型一致）。
• 执行隔离：若技能涉及 代码/Shell 执行，须走 沙箱、审批或企业策略（实现另述），避免「越进化越危险」。

#### 3.6.4 与 REST 的边界

• 自进化的 触发、配置、审核 通过 后端 API 与管理端 完成；客户端仍 只 使用 §5 的 REST，不 直接写 Workspace 文件。
• 用户可见效果体现为：更准的记忆、更顺手的技能、更贴身的画像，背后由闭环任务写入 Workspace 与索引。

---

4. 功能需求

4.1 Web 客户端

#### 4.1.1 连接与鉴权

• [ ] 经 Go 后端完成注册/登录（密码或验证码 双路径，UI 默认密码，见 §1.5.2），获取 JWT；JWT/会话须能表达 当前用户，并在涉及协作资源时表达 当前工作区（若用户已加入或创建工作区）；生产路径 不在浏览器直连任何 LLM 或内部运行时管理端点。
• [ ] 使用 HTTP 客户端调用 /api/v1；401 时按既有策略尝试 refresh 并重放（细节见 后端与Web设计.md 第 9 节）。
• [ ] 连接/健康态：以后端可达、登录态与请求中状态为主。

#### 4.1.2 消息功能

• [ ] 发送文本消息（POST /api/v1/chat 等，响应体与后端 ChatResponse 对齐）。
• [ ] 聊天 附件：上传与 chat 消息关联。
• [ ] 接收 AI 回复（以服务端返回为准）。
• [x] 消息时间戳与角色区分（用户/助手）：对话中间隔约 5 分钟及以上时居中显示时间（今日仅时分，跨日含月日），与微信类似。（2026-07-31）
• [ ] 多会话、列表分页与消息分页、技能列表分页。
• [ ] 发送重试携带客户端 request_id 幂等。
• [x] 阅读模式（Web）：把对话改成连续正文、收起侧栏与输入区，便于在电纸书等设备上阅读；可调字号；可按提问跳转；可将当前会话 导出为电子书（EPUB）或 PDF。（2026-07-29）
• [x] 回复批注改进（Web）：对助手回复点「批改」，在各段原文下方写批注（可加总要求），再「按批注改进」交给智能体改写。（2026-07-29）

#### 4.1.3 Skill 功能

• [ ] 快捷指令触发（首期可走聊天内容或 skills 接口）。
• [ ] Skill 列表展示（GET /api/v1/skills）。
• [ ] Skill 调用（POST /api/v1/skills/execute 或与 chat 合并策略一致）。

#### 4.1.4 界面功能

• [ ] 侧边栏导航、登录/注册/忘记密码流程（验证码走 send-code；支持 创建/切换工作区 与 邀请成员 入口，见 §4.5）。
• [ ] AI 对话页面。
• [ ] Skill 管理页面。
• [ ] 设置页面（API 基地址可仅开发环境展示）。
• [ ] 响应式设计、移动端适配；帮助类只读页、主题与 i18n 见 界面与布局.md。

#### 4.1.5 操作助手与帮助智能体（对话操作）

• [x] 在控制台各模块中，用户可随时打开 操作助手，用自然语言问「下一步怎么做」；助手回答可结合当前产品界面给出引导。操作助手与 帮助智能体 同一身份。
• [x] 助手面板底部提供少量 快捷一句（点一下即带上预设问题并跳到相关能力页）。这些入口会随 你当前在看哪一块、是否已选工作区、以及你刚在助手里聊过什么 而调整顺序与文案，优先露出更可能接着要问的事；不要求用户理解排序规则。
• [x] 对话操作（ChatOps，产品核心）：用户说 要做什么 就代做；只有问 「如何 / 怎么 / 怎样」 时才给说明和入口。例如说「帮我创建一个工作区」「把工作区改名为…」「生成技能」「创建一个应用」「添加数据连接」「列出部门」「入库」，由系统按当前用户权限写入，而不是只给说明书再让用户去页面粘贴。创建或改名工作区不必先选工作区（创建先问名称，不提供则用「我的工作区」）；插件业务走对应 应用助手 的操作清单（帮助智能体接到同一请求也须代做）。其它写操作未选工作区时先请用户选工作区。帮助智能体 没有 个人记忆与备忘；定时任务须指定要绑定的工作智能体或到定时任务页创建。机制见 docs/core-mechanisms/帮助智能体对话操作.md。
• [ ] 实现与扩展（打分信号、候选池、无工作区时的可达性）见 docs/core-mechanisms/工作区帮助快捷一句.md。

4.2 SDK 嵌入包

#### 4.2.1 Web Component

• [x] 自定义元素 <mindlink-widget>
• [x] Shadow DOM 隔离
• [x] 主题配置（light/dark/auto）
• [x] 位置配置（bottom-right/bottom-left/middle-right/center/inline）

#### 4.2.2 配置参数

#### 4.2.3 我的智能体 JS 嵌入（V1）

• [ ] 嵌入目标：支持外部系统以一段 JS（<script src="...">）嵌入「我的智能体」，在宿主页面完成 AI 对话与受控操作。
• [ ] 绑定对象：嵌入实例必须显式绑定 user_agent_id；未传时 init 抛错，不进入可对话态。
• [ ] 初始化方式：支持 window.MindLinkWidget.init(...)（或等价 API）与 <mindlink-widget ...> 两种方式；参数语义保持一致。
• [ ] 最小参数：user-agent-id 与 auth.token 必填；须另给 base-url 或 api-base-url。app-id、auth.expires_at、workspace-id、theme、position、locale、entry、host_actor（B 路径必传）为可选。
• [ ] 鉴权约束：嵌入端不得持有主系统长期密钥；仅使用服务端签发的短期令牌（含过期时间、可访问范围、可选 workspace_id 约束）。
• [ ] 对话能力：嵌入会话通过后端 chat 契约执行；多位访客可同时对话（同一对话内仍一轮一轮回复）。同时正在生成的回复受上限约束（智能体可配，默认 20 路；超出时挂件提示「当前对话人数已达上限，请稍后再试」）。新会话需校验 user_agent_id 可用性与授权。
• [ ] 受控操作能力：智能体在嵌入场景触发操作时，必须通过白名单动作（如 open_url、open_module、emit_event），禁止任意脚本执行。
• [ ] 事件回调：至少提供 onReady、onMessage、onAction、onError、onClose；宿主侧可监听并决定是否放行高风险动作。
• [ ] 安全基线：默认启用 Shadow DOM 隔离、来源校验（Origin Allowlist）、CSP 建议项与操作审计日志（含 request_id、user_agent_id）。
• [ ] 降级与容错：令牌过期、网络异常、权限不足时，需展示用户可理解的错误提示，并提供重新授权或重试入口。

首版交付对照（2026-08）：Script / Web Component 嵌入、embed-token 登记与吊销、POST /api/v1/chat/stream、回答内 mindlink://action/ 与 entry.auto_execute_navigation（默认开启）、updateAuth / updateHostActor、Shadow DOM、inline + container、人工客服 / 工单、回答「下一步」芯片、复制脚本时可选入口形态（角落按钮 / 首次招呼 / 打开即展开）与面板名称等已落地，见 sdk/host-embed/SDK契约.md §6.3 与 sdk/host-embed/网站集成说明.md。Origin 白名单、操作卡片、专用 embed_token_expired 错误码仍为规划中。

#### 4.2.4 两种业务集成形态（宿主增强 / 平台插件）

Cadau 与 外部业务产品有两种典型接法（可并存）；二者均须在集成层校验 当前用户，涉及工作区时再校验 workspace_id 与工作区成员身份，禁止跨工作区或未授权访问插件侧数据。

• 宿主增强（旧有业务系统）：用户仍以 原有业务系统 为主界面与权限边界；Cadau 通过 §4.2.3「我的智能体」嵌入等方式，为该宿主 补上 AI 对话与受控动作（契约见 sdk/host-embed/SDK契约.md）。业务数据不归 Cadau 落库时，不得在对话中捏造宿主未授权的字段级结论。
• 平台插件模块（新业务产品）：独立开发与部署的业务应用（自有 Web 与租户模型；服务端接口可与前端 同源单体 部署（如 Next.js），亦可拆为多服务）接入 Cadau 后，用户在 工作台或侧栏菜单进入该模块，形成「Cadau 里多了一项专业能力」的一体体验；Cadau 仅负责导航壳、账号/工作区上下文，以及可用的智能体（与插件业务之间通过短期令牌、显式 工作区 ↔ 插件企业/租户 映射衔接）。插件内的合规、审批、报表等 仍由插件服务实现与审计。多插件共用的 法规与管理标准 见 §3.2.2 规范库（不落在某一插件私有知识目录）；跨插件业务调用须经平台代签与审计。

范例（仓库内）：plugins/hr/ — 官方 平台插件（人力资源）；plugins/compliance/ — 官方 合规管理平台插件（问卷 → 检查项 → 绑定工作流 → 对 人力资源部门 执行检查；IWAY 仅为可替换范例规范，亦可接法规/管理制度）；plugins/warehouse/ — 仓管；examples/hr-multi-tenant/ — 可多角色运行于 HR 小样 + 宿主嵌入对照；examples/henry-iway-compliance/ — 「亨瑞艾维」品牌化平台插件范例（集成口径见其 docs/PRODUCT.md）；可运行官方合规能力优先看 plugins/compliance/。

合规 · 实践检查表 → 机读包（产品决策，2026-08-06；存放目标于 2026-08-07 更正为检查方案）：

• [x] 合规插件随发版提供技能 「实践检查表 → 合规机读包」（可随仓库技能目录分发）；打开合规时 提示 安装到工作区技能中心（区内智能体默认可召回），禁止静默改写各智能体的「可用技能」收窄配置。（2026-08-06 首期）
• [x] 用户通过智能体，将资料库（或附件）中的专家实践表转为机读包并写入 检查方案草稿（须确认、建议带依据规范）；经发布后在调查问卷中 选用检查方案 生成检查项；存量误放规范库的实践包可 从规范库迁入。（合规侧独立「校验/预览」操作仍可加强；见 §3.2.4）
• [x] 实践机读包 补充「怎么查」，不 取代规范库中的标准条文；生成检查项仍须预览与人确认。详稿 docs/core-mechanisms/检查方案.md、合规实践检查表转机读包.md；样板 plugins/compliance/samples/iway6-internal-audit-g1.pack.md。

4.3 智能体市场与用户智能体

业务目标与已确认策略（混合型模板实例、商业模式、抽成、数量限制、软删除、训练范围、审核、会话绑定等）维持 1.x 规格中的产品结论，实现时由 Runtime 的 Soul/Memory/编排层支撑，不再经过 OpenClaw。

4.4 自进化（产品能力）

• [ ] 技能沉淀：支持从任务/对话中生成或更新 技能文档（版本化、可检索），并与技能列表/执行接口策略一致；支持与市场模板、训练任务的衔接边界（见 §3.6.1）。
• [ ] 记忆晋升：支持 flush + Dreaming 类 后台任务（可关闭、可配置频率与门槛），晋升内容写入 MEMORY.md 等，摘要面可对接 DREAMS.md（§3.5）。
• [ ] 跨会话召回：memory_search / 摘要注入路径与产品开关（用户或 工作区策略 可弱化召回强度以换隐私）。
• [ ] 用户画像：USER.md（或等价）在策略允许下 渐进更新，敏感项需显式授权或审核策略。
• [ ] 治理与运维：进化任务队列、失败告警、配额与审计查询；管理端可查看/干预（与 §3.6.2 一致）。

4.5 工作区协作（产品能力）

• [ ] 工作区上下文：访问 工作区范围 资源时，请求在 当前工作区 下执行；支持用户在 多个工作区 间切换，切换后列表与数据刷新。
• [ ] 创建工作区：注册用户可以 创建工作区，获得该工作区的 所有者/管理员 权限。
• [ ] 邀请成员：向 手机号或邮箱 发送邀请；受邀用户 登录/验证 后加入 对应工作区。
• [x] 成员与角色：工作区身份区分所有者/管理员/成员；工作区内可自定义 业务职责（流程领取与能力包授权）；细粒度更多身份与转让所有者策略可继续演进。（2026-08-03）
• [ ] 协作资源：同一工作区内 知识库、智能体、会话策略 等按产品阶段开放 团队可见/仅本人 等共享模式；与 Runtime 记忆隔离策略一致（§3.2）。
• [x] 规范库：同一工作区内维护 法规与管理标准（§3.2.2）；API + 对话注入 + 多维索引树与全屏管理页（2026-07-25）；待做来源白名单抓取、插件订阅影响清单。
• [x] 资料库：同一工作区内维护 模板与表格（§3.2.3）；全屏管理页 + API + 插件只读 + 对话元数据注入（2026-07-25）；待做索引树浏览、配额硬门控与自动填表工具链；机制见 docs/core-mechanisms/资料库.md。
• [ ] 配额：每 工作区 成员数、智能体数、存储等 可配置上限，并可叠加 用户级 配额（与「用户等级」等策略可合并）。

4.6 统一对话与联络（产品能力，2026-05-23 已确认）

机制详稿：docs/core-mechanisms/统一对话与联络.md。

与 §4.1 关系：顶栏 「消息」 演进为 统一对话入口（与真人、租用智能体、群聊同一列表与气泡界面）；与智能体的推理仍经 Cadau Runtime，但 不再 以「仅当前用户拥有的 chat_sessions」作为长期唯一的对话产品模型。

#### 4.6.1 统一对话

• [ ] 一套界面：用户在一个对话列表里看到 同事、智能体、工作区群；进入任一会话后用同一时间线收发文字与附件（附件策略与 §5.2 上传能力对齐）。
• [ ] 智能体也是对话成员：自己创建的智能体可直接对话；租用 的智能体与真人一样出现在会话中，回复由服务端 Runtime 生成并写入同一会话。
• [ ] 展示：消息以 智能体身份 呈现（如「某人的 · 报税助手」）；出租方与租用方均可为同一智能体设置备注名，界面优先显示备注名。
• [ ] 帮助智能体：未选工作区时的引导对话可仍走帮助路径，最终纳入统一入口或保留快捷入口（实现阶段定，须避免用户混淆「同事消息」与「帮助」）。

#### 4.6.2 智能体租用（公开市场）

• [ ] 公开市场：拥有者可将训练好的智能体 上架，供他人浏览、申请或 付费租用（具体支付与订单与计费系统对接，可分阶段）。
• [ ] 租用合同：AI 调用消耗 由租用合同/套餐约定 计入出租方、租用方或工作区之一（非单一全局规则）。
• [ ] 进群：租用方在自己有权限的 工作区群 中可加入 已租用且仍有效 的智能体，供群内 @ 或按规则触发回复。

#### 4.6.3 真人单聊与好友

• [ ] 不依赖工作区：加好友、真人单聊 以 账号 为边界，不要求 用户已加入任何工作区；仅 工作区群聊、同工作区同事信任单聊 依赖工作区成员身份。
• [ ] 同工作区同事：视为 信任关系，单聊 无需 先加好友、不适用「对方未回复前只能发一条」。
• [ ] 非同事、非好友：适用类微信陌生人规则 — 对方未回复前仅可发 1 条；对方回复后进入 短期可聊（时长或条数上限由实现配置）；长期联系须互为好友。
• [ ] 好友：互为好友后 自由单聊；支持好友申请、拒绝、拉黑（文案避免实现术语）。

#### 4.6.4 工作区群聊

• [ ] 默认全员群：每个工作区自动有一个 全员群，成员随工作区 加入/退出 同步。
• [ ] 自建子群：成员或管理员可创建 子群（项目群等），规则由群角色管理（首期可仅「拉人入群」）。
• [ ] 群内成员：真人 + 满足租用/授权条件的 智能体；群消息仅 该工作区相关成员（及合法租用智能体）可访问。

#### 4.6.5 实现备注（非用户文案）

• 新对话域 API 建议前缀 /api/v1/im/（与现有 /api/v1/chat 人机助手路径区分，迁移期可并存）；数据表与 chat_sessions / chat_messages 分库分表，见机制文档 §3～§7。
• 安全：全员鉴权会话成员身份；租用扣费与审计绑定 lease_id；陌生人/好友规则 仅约束真人↔真人。

---

4.7 服务通知（产品能力，2026-05-25 已确认）

机制详稿：docs/core-mechanisms/服务通知.md。

• [ ] 固定入口：在 「消息」 模块中 置顶 「服务通知」；与 帮助智能体、业务智能体、同事会话 并列，名称固定，不随工作区变化。
• [ ] 只读时间线：展示 系统代发 的说明与 可点操作（如「去处理」「打开工作区协作」）；不可回复；不 用大模型现场生成通知正文。
• [ ] 未选工作区也可用：账号级事件（如收到工作区邀请）仍投递；顶栏 「消息」 未读角标 合并 AI 对话未读与服务通知未读。
• [ ] 首期事件：工作区 邀请、加入申请 的提交/批准/拒绝/撤回，及邀请被接受等（详机制文档 §5.1）；处理界面仍在 工作区协作，通知负责 触达。
• [ ] 已读：进入 服务通知 即更新已读水位，顶栏角标相应减少。

4.8 人工客服与工单（产品能力）

机制详稿：即时 — docs/core-mechanisms/人工客服.md；异步工单 — docs/core-mechanisms/工单.md。

• [ ] 按智能体配置：每个智能体（含工作区 帮助智能体）可单独 开启人工客服，并指定 本区客服席位；也可不勾本区人员，改为授权 客服小组。不是 默认把工作区管理员当作客服。开启后同时提供即时与工单入口。
• [ ] 即时人工客服：快捷条 「人工客服」 → 排队（队位/约等）→ 在线沟通；结束后记录留在当前对话中；客户可结束；结束后可五星评价（座席绩效）。无人上班（本区席位与已授权小组均无上班）时只保留 提交工单。
• [ ] 工单（异步）：快捷条 「提交工单」；不要求及时性；待处理 / 处理中 / 已办结；可留言；办结后可评分。即时排队中可 改提工单。
• [ ] 客服工作台：顶栏 「客服」（本区席位或客服小组成员）或功能菜单。顶栏一行：左侧标题，右侧范围组合框 / 在岗状态 / 刷新。左侧分段：即时客服（待接单 / 我负责的 / 进行中 / 已完结）、工单、服务时段。小组成员可切 本区客服 / 小组工作台（后者仅已授权且列入服务范围的客户）。小组工作台接单 不切换 顶栏当前工作区。
• [ ] 客服小组：本队工作区管理员创建小组、指定队员、选择要服务的工作区；客户工作区管理员授权后生效。三门齐备（队员 + 服务范围 + 授权）才能看见并接该客户的单。授权只给客服权，不成为客户区成员。
• [ ] 配置入口：自建智能体 → 管理 → 人工客服；帮助智能体 → 工作区协作 → 客服队列（左侧：请求 / 本区客服 / 我们的小组 / 授权外来小组）。

#### 4.8.1 实现备注（非用户文案）

• 配置：user_agent_cs_config、user_agent_cs_staff。
• 客服小组：cs_groups、cs_group_members、cs_group_workspace_grants、cs_group_workspace_scope。
• 即时会话：cs_tickets、cs_ticket_messages（用户侧勿称工单）。
• 异步工单：support_cases、support_case_messages。
• API：见两份机制文档；Web：/customer-service；帮助智能体占位 ID：__builtin_assistant__。

---

5. 数据格式与 API 约定

5.1 Web 客户端与后端（REST）

• 鉴权头：Authorization: Bearer <token>（access / refresh 策略见 后端与Web设计.md §3.2 与第 9 节决策，或后端实现）；涉及 工作区范围 资源时，Token 或配套头/字段须能表达 当前 workspace_id（或等价），服务端以 用户 + 工作区成员身份 鉴权；纯个人资源以 用户 维度鉴权。
• 限流：HTTP 429，JSON 含 error、retry_after，可含 request_id，并可设 Retry-After 头。
• 其它 4xx / 5xx：错误 JSON 字段 error（必选）、code、request_id、details（可选）。
• 成功 2xx：JSON 顶层 request_id；请求体幂等 request_id 与响应追踪 ID 语义不同。
• 分页：limit + cursor；默认 limit = 20；next_cursor 等约定见 后端与Web设计.md 第 9 节。
• OpenAPI：首期不强制维护可生成 Swagger；契约以 本文与 后端代码 为准。

5.2 主要端点（摘要，与 1.x 对齐）

智能体市场相关端点（agent-templates、user-agents、train 等）字段级约定见 §7.4；实施时以 Soul/Memory 落地为准则更新实现说明。

5.3 前端消息类型（UI 层）

interface Message {
  id: string
  role: 'user' | 'assistant' | 'system'
  content: string
  timestamp: Date
  attachments?: Attachment[]
  metadata?: Record<string, unknown>
}

type AppConnectionStatus = 'disconnected' | 'connecting' | 'ready' | 'error'

5.4 内部运行时消息流（实现参考，非客户端协议）

客户端 仅使用 REST。以下为服务端内部 示意（非对外 WebSocket 契约）：

1. 鉴权与会话解析 → 解析 用户、当前工作区（若业务绑定）、user_agent_id 对应 运行时 Workspace，加载 SOUL.md / AGENTS.md / USER.md 与 Memory 检索（§3.5）
2. 组装 LLM 请求 → 可选 工具循环（memory_search / memory_get 等）
3. 持久化消息与记忆文件更新 → 返回 ChatResponse

---

6. 项目结构（示意）

mindlink/
├── sdk/                    # SDK 嵌入包
├── client/                 # Web / Mobile 客户端
├── backend/                # Go：REST API + Cadau Runtime + LLM 网关
└── docs/
    ├── 产品规格.md                      # 本需求规格书（首要）
    ├── 后端与Web设计.md    # Web 经后端接入：已确认决策（第 9 节）
    ├── 界面与布局.md              # Web UI 约定
    ├── 文档索引.md                  # 文档导航（中文文件名）
    ├── 管理员端规格.md              # 管理端功能规格与运维附录
    ├── 实施计划.md / 实施验收.md
    └── 手机验证码发送集成说明.md    # 短信通道集成（与 DESIGN 决策 35 配套）

---

7. API 参考（Web 客户端）

7.1 后端访问约定

• HTTP 客户端：拦截器、超时、401→refresh→重放（见 后端与Web设计.md 第 9 节）。
• 端点：以第 5.2 节为准；字段与错误码以仓库内 Go 实现为准。

7.2 前端服务模块（示意）

function getAccessToken(): string | null

async function login(body: Record<string, unknown>): Promise<AuthResult>
async function register(body: Record<string, unknown>): Promise<AuthResult>
async function sendCode(body: { channel: 'sms' | 'email'; scene: string; [k: string]: unknown }): Promise<void>
async function resetPassword(body: Record<string, unknown>): Promise<void>
async function sendChat(input: { message: string; session_id?: string; request_id?: string; user_agent_id?: string }): Promise<ChatResponse>

7.3 智能体市场接口（摘要）

以下路径由 Go 后端 暴露；对话与训练编排由 Cadau Runtime 完成，不经外部 OpenClaw。

7.4 智能体市场接口契约（字段级，V1）

以下为首期建议契约，实际实现可在不破坏语义前提下调整字段命名。

#### 7.4.1 统一分页约定

• 请求参数：limit（默认 20）、cursor（可选）
• 响应字段：items、next_cursor（无更多为 null）、可选 has_more
• 排序建议：市场列表按 published_at desc；我的智能体按 updated_at desc

#### 7.4.2 模板（agent_templates）

1) POST /api/v1/agent-templates（创建草稿）

请求示意：

{
  "name": "财务助手 Pro",
  "summary": "处理报销与对账",
  "category": "finance",
  "pricing_mode": "subscription",
  "price_amount": 39.9,
  "price_currency": "CNY",
  "base_config": {
    "system_prompt": "你是财务助手",
    "tools": [],
    "knowledge_sources": []
  }
}

2) PATCH /api/v1/agent-templates/:id（更新草稿/驳回稿）

• 允许更新：name、summary、category、pricing_*、base_config
• status=published 时禁止直接覆盖，需走“新版本草稿”流程（建议）

3) POST /api/v1/agent-templates/:id/submit-review（提交审核）

请求可选字段：

{
  "changelog": "新增考勤异常处理工具"
}

4) 审核状态机（模板）

• draft -> pending_review -> approved -> published
• pending_review -> rejected
• rejected -> draft（修改后可再次提交）
• published -> unpublished（下架，不影响已创建的用户实例）

#### 7.4.3 用户智能体（user_agents）

1) POST /api/v1/agent-templates/:id/create-user-agent（从模板创建实例）

请求示意：

{
  "name": "我的财务助手",
  "request_id": "optional-idempotency-key"
}

响应示意：

{
  "user_agent": {
    "id": "ua_xxx",
    "name": "我的财务助手",
    "source_template_id": "tpl_xxx",
    "source_template_version": 3
  },
  "entitlement": {
    "pricing_mode": "subscription",
    "valid_until": "2026-05-01T00:00:00Z"
  },
  "request_id": "srv_xxx"
}

2) POST /api/v1/user-agents（创建空白智能体）

{
  "name": "空白助手",
  "system_prompt": "",
  "tools": [],
  "knowledge_sources": []
}

3) PATCH /api/v1/user-agents/:id（更新实例配置）

• 可更新：name、system_prompt、tools、knowledge_sources
• 更新时建议记录 config_version 递增，便于审计和回滚

4) DELETE /api/v1/user-agents/:id（软删除）

• 建议行为：is_deleted=true，保留恢复窗口（如 7/30 天）
• 软删除后默认不可新建会话，不影响历史会话只读查看

5) POST /api/v1/user-agents/:id/upgrade（手动升级）

{
  "target_template_version": 5,
  "merge_mode": "prompt_only"
}

merge_mode 建议：

• prompt_only：仅升级系统提示词
• safe_merge：升级模板默认项，保留用户自定义覆盖
• force_replace：完全按模板替换（高风险，建议二次确认）

#### 7.4.4 训练任务（train jobs）

1) POST /api/v1/user-agents/:id/train

{
  "mode": "full_rebuild",
  "knowledge_file_ids": ["file_1", "file_2"],
  "tool_bindings": [
    { "tool_id": "attendance.query", "config": {} }
  ]
}

2) 任务状态建议：queued -> running -> succeeded/failed/cancelled

3) 建议补充查询接口：

• GET /api/v1/user-agents/:id/train-jobs
• GET /api/v1/train-jobs/:job_id

#### 7.4.5 对话与智能体绑定

POST /api/v1/chat 请求示意（新增 user_agent_id）：

{
  "message": "本月薪资核算流程",
  "session_id": "optional",
  "user_agent_id": "ua_xxx",
  "request_id": "optional-idempotency-key"
}

规则：

• 新会话：user_agent_id 必填
• 已存在会话：默认沿用会话绑定的 user_agent_id
• 切换智能体：不在原会话内直接切换，需“新建分支会话”并绑定新 user_agent_id

#### 7.4.6 付费与授权（V1）

• pricing_mode：free | buyout | subscription
• 平台抽成固定：20%
• 建议订单字段：

- order_id、buyer_user_id、template_id、pricing_mode - gross_amount、platform_fee_amount、creator_income_amount - status：pending/paid/refunded/closed

• 授权校验：

- free：永远有效 - buyout：支付成功后永久有效 - subscription：仅在 valid_until > now 时有效

#### 7.4.7 推荐业务错误码（补充）

• agent_quota_exceeded：超出用户等级可创建数量
• template_not_published：模板未发布不可创建实例
• template_review_pending：模板审核中，禁止发布相关操作
• entitlement_required：缺少购买/订阅授权
• subscription_expired：订阅已过期
• agent_deleted：智能体已删除
• session_agent_mismatch：会话与 user_agent_id 不匹配
• upgrade_conflict：升级版本冲突
• train_job_running：已有训练任务在执行

7.5 我的智能体嵌入契约（字段级，V1）

以下契约用于“外部系统通过一段 JS 嵌入我的智能体”场景，嵌入端能力边界与鉴权策略与 §4.2.3 对齐。

实现对照：联调与 TypeScript 类型以 sdk/host-embed/SDK契约.md（当前 V1.5.10）、可交付集成说明 sdk/host-embed/网站集成说明.md 为准。本节保留产品字段级摘要；与「当前实现」标注冲突时以前两者为准。

#### 7.5.1 初始化参数（widget init）

宿主页面可通过 window.MindLinkWidget.init(options) 或 <mindlink-widget ...> 传入以下等价参数：

初始化示意：

{
  "base_url": "https://mindlink.example.com",
  "user_agent_id": "ua_123",
  "auth": { "token": "eyJ..." },
  "theme": "auto",
  "position": "bottom-right"
}

B 路径另传 host_actor，并可显式给 app_id、api_base_url、workspace_id、auth.expires_at。

#### 7.5.2 嵌入鉴权与令牌声明

• 嵌入端不持有 Cadau 主系统长期密钥；生产由 宿主后端代签 短期（或登记型长期）令牌再给浏览器（见 sdk/host-embed/网站集成说明.md §4.3）。
• 当前 JWT Claims（authx.Claims）：sub、wid（工作区）、emb=1、jti、exp；JWT 内不含 app_id / user_agent_id，二者由 init 与 embed_access_tokens 登记约束。
• 受保护 API：Authorization: Bearer；emb=1 时 middleware 查登记未吊销且未过期；收回返回 embed_token_revoked。
• 过期/签名错误：当前并入 unauthorized（文案「令牌无效或已过期」）；专用 embed_token_expired 仍为规划项，前端应依赖 updateAuth 或宿主重新代签。

#### 7.5.3 对话请求与响应（嵌入模式）

嵌入挂件当前使用 POST /api/v1/chat/stream（SSE），非同步 POST /api/v1/chat。请求体示例：

{
  "message": "请帮我总结今天未完成的任务",
  "session_id": "optional",
  "user_agent_id": "ua_123",
  "request_id": "req_embed_001",
  "client_context": {
    "channel": "embed_widget",
    "app_id": "crm-prod",
    "page_url": "https://crm.example.com/home",
    "host_actor": { "external_user_id": "…", "actor_kind": "employee" }
  },
  "host_actor": { "external_user_id": "…", "actor_kind": "employee" }
}

约束：

• 新会话必须显式提供 user_agent_id。
• 已有会话默认沿用既有智能体绑定；不允许在同会话内无提示切换智能体。
• client_context 客户端已发送，服务端已解析：channel=embed_widget（或 JWT emb=1）时会话来源记为嵌入；app_id 写入会话的 embed_app_id；host_actor（或顶层同名字段）用于会话隔离与数据连接策略。
• 嵌入模式下所有高风险操作只可通过动作白名单下发（见 §7.5.5）；回答内 mindlink://action/ 链接点击或 auto_execute_navigation 触发 action 事件，由宿主白名单执行。

#### 7.5.4 事件回调契约（宿主可监听）

建议标准事件：

事件示意：

{
  "type": "action",
  "request_id": "srv_abc",
  "action": {
    "type": "open_url",
    "payload": { "url": "https://crm.example.com/order/123" }
  }
}

#### 7.5.5 受控动作白名单（V1）

首期允许：

• open_url：打开业务页面（需域名白名单校验）。
• open_module：通知宿主切换到已注册模块。
• emit_event：向宿主发送业务事件（仅透传白名单字段）。

首期禁止：

• 任意 JS 执行（如 eval、动态脚本注入）。
• 未经声明的跨域请求代理。
• 超出白名单的数据写操作。

#### 7.5.6 推荐错误码（嵌入场景）

---

8. 非功能需求（补充）

• 安全：密钥仅服务端；记忆与知识库按 工作区与用户 隔离；工作区成员邀请与验证码通道防刷、防枚举；敏感接口日志脱敏（对齐历史决策）。
• 自进化安全：自动写入须符合 §3.6.2（门控、配额、审计）；禁止未授权将一用户进化数据用于另一 用户或工作区；技能若含可执行内容须经 沙箱/审批 策略。
• 性能：记忆检索与模型调用可异步化；热点接口限流；进化后台任务须限并发，避免拖垮存储与 embedding 配额。
• 可运维：运行时与索引任务的可观测指标、告警与备份策略在部署文档中定义；进化任务须单独指标（成功率、延迟、队列深度）。
• 运行时可观测事件：对话执行链路需输出可追踪事件（如模型调用开始/结束、工具调用开始/结束、检索命中摘要、降级路径），并与 request_id、session_id、user_agent_id、workspace_id 关联；事件可用于管理端排障与审计导出。
• 技能契约治理：技能需具备最小元数据契约（skill_id、版本、输入输出约束、权限范围、超时与重试策略、可见范围），支持启停与灰度；新增或升级技能需保留版本审计记录并可回滚。
• RAG 策略开关：检索链路应支持分阶段开关与配置（向量召回、关键词召回、重排、query rewrite）；默认策略以稳定与成本可控优先，开关变更需可审计并支持工作区级策略覆盖。

---

9. 版本历史

---

10. TODO

• [ ] §4.6 统一对话：im_* 数据模型、REST、与 Runtime 编排；chat → 统一对话迁移方案；界面与布局.md「消息」区改版
• [ ] 智能体租用：公开市场 listing、agent_leases 与计费条款、双端备注名、群内租用智能体触发回复
• [ ] -runtime 模块设计文档（Soul/Memory/编排与 LLM 网关的接口与数据模型；含 Workspace 落盘布局与 DB 版本指针、索引重建、memory_search 实现）
• [ ] 自进化实现设计：技能沉淀流水线、记忆晋升与 Dreaming 调度、画像更新策略、§3.6.2 门控与审计表结构；管理端任务与审核界面
• [ ] 运行时可观测事件规范：事件类型、字段字典、采样与脱敏策略；后端日志与管理端查询接口对齐
• [ ] 技能契约 V1：技能元数据、输入输出约束、权限模型、超时重试、版本回滚与发布流程
• [ ] RAG 策略配置中心：向量召回/关键词召回/重排/query rewrite 的可配置开关与工作区级覆盖策略
• [ ] 规范库（§3.2.2）：~~存储、发布流、插件只读、对话注入、多维索引树与全屏管理 UI（2026-07-25 已落地）~~；~~智能体写入规范库条文草稿（2026-08-07）~~；待做：来源白名单与抓取、订阅与影响清单、跨插件代调审计；机制见 docs/core-mechanisms/规范库.md
• [ ] 资料库（§3.2.3）：~~元数据与文件、上传/发布/废止、全屏管理页、插件只读、对话元数据（2026-07-25 已落地）~~；~~成员上传并发布办公样式、对话选用（2026-08-15）~~；待做：索引树浏览、配额硬门控、从技能/插件导入、自动填表工具链；作实践检查表原材料；机制见 docs/core-mechanisms/资料库.md
• [x] 检查方案（§3.2.4）：存储、发布门控（必填依据规范）、管理页、插件只读、智能体写入草稿、问卷改选源、存量迁入、管理员导入/导出已落地；待做：答疑注入边界补强；机制见 docs/core-mechanisms/检查方案.md
• [x] 合规实践检查表 → 机读包（§4.2.4）：~~技能分发与打开合规时提示安装到技能中心~~；~~产品决策：写入检查方案~~；~~平台检查方案能力 + 问卷改选 + 存量迁入~~；待做：合规侧独立校验/预览增强；详稿 合规实践检查表转机读包.md
• [ ] 管理员端规格：管理员端规格.md 已修订为 运行时/LLM 运维（v0.3）；落地时核对 API 路径与指标
• [ ] Web / Mobile：登录与聊天 REST 全链路（含附件）
• [ ] 智能体市场与训练、记忆索引任务联调
• [ ] 付费与订阅授权校验
• [ ] 单元测试与集成测试
• [ ] 二期：流式输出、OpenAPI 3.x、更强安全头与 CSP

---

11. 参考资料

• OpenClaw 概念参考（实现范式对标，非运行时依赖）：Memory Overview、Dreaming、Gateway Architecture、Agent Loop、SOUL.md Guide
• Hermes Agent（概念对标：学习闭环与技能沉淀，非运行时依赖）：NousResearch/hermes-agent
• Web 经后端接入（决策真值）：docs/后端与Web设计.md
• 我的智能体嵌入 SDK 联调契约：sdk/host-embed/SDK契约.md
• 第三方嵌入助手指南（总览）：sdk/host-embed/README.md
• 网站嵌入集成说明（可交付宿主方）：sdk/host-embed/网站集成说明.md
• 宿主知识文档撰写：sdk/host-embed/宿主知识文档撰写要求.md
• 业务集成范例（宿主增强 / 平台插件）：plugins/hr/（官方人力资源）、examples/hr-multi-tenant/、examples/henry-iway-compliance/（后者真值：docs/PRODUCT.md，Next.js 骨架：examples/henry-iway-compliance/web/）
• 规范库（法规与管理标准）：docs/core-mechanisms/规范库.md（与 §3.2.2 配套）
• 检查方案（实践机读包）：docs/core-mechanisms/检查方案.md（与 §3.2.4 配套）
• 合规实践检查表 → 机读包：docs/core-mechanisms/合规实践检查表转机读包.md（与 §3.2.2 / §3.2.3 / §3.2.4 / §4.2.4 配套）
• 资料库（模板与表格）：docs/core-mechanisms/资料库.md（与 §3.2.3 配套）
• 资料库（模板与表格）：docs/core-mechanisms/资料库.md（与 §3.2.3 配套）
• 管理端功能规格：docs/管理员端规格.md
• 短信验证码（联麓模板发送、签名、Go 示例）：docs/手机验证码发送集成说明.md（与 DESIGN 决策 35 配套）
• React：https://react.dev
• Tailwind CSS：https://tailwindcss.com
• axios：https://axios-http.com

---

*本文档结束。*