diff --git a/README.md b/README.md index 8fa3f7fb374869419dc50885d8297fe198acd148..5a1ac50be83fb8ca1e0a9a390b1d321b162f2b17 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# daedalus-agent 快速部署手册 +# 快速部署手册 解决方案由一体化容器和对话应用构成，一体化容器中内置智能体集群构建与管理所需的全部组件，对话应用使用活字格构建，提供实现对话式交互。 @@ -83,7 +83,7 @@ Ontology zip 需通过 `huozige-ontology-builder` 构建，[点击阅读使用 对话应用采用活字格构建，可使用 `https://gitee.com/low-code-dev-lab/daedalus-agent-cui-hzg`。 -发布后在应用全局变量中配置： +原则上，对话应用仅需要配置以下四个全局变量： - `DA_SERVER_IP` - `DA_MQTT_CHANNEL_PASSWORD` @@ -92,6 +92,22 @@ Ontology zip 需通过 `huozige-ontology-builder` 构建，[点击阅读使用 MQTT/MinIO 密码可在 `系统设置` 页面中 `基础设置` 选项卡获取；管理控制台 Token 在 `访问令牌` 选项卡中创建。 +接下来，检查以下全局变量的值是否和预设值相符，否则可能会导致系统无法正常工作。 + +|全局变量|预设值|需要修改的场景| +|----|----|----| +|DA_MQTT_CHANNEL_PORT|1883|docker启动脚本中修改过MQTT的端口映射，通常用于规避端口占用，下同| +|DA_S3_PORT|9000|docker启动脚本中修改过S3的端口映射| +|DA_MANAGEMENT_CONSOLE_PORT|3030|docker启动脚本中修改过管理控制台的端口映射| +|DA_MQTT_CHANNEL_USERNAME|daedalus-agent|除非必要，不要修改，下同| +|DA_S3_ACCESS_KEY_ID|daedalus-agent|-| +|DA_S3_REGION|local|-| +|DA_S3_FORCE_PATH_STYLE|true|-| +|DA_S3_AGENT_INBOX_BUCKET|daedalus-agent-inbox|-| +|DA_S3_AGENT_OUTBOX_BUCKET|daedalus-agent-outbox|-| +|MQTT_CONNECTION_NAME|daedalus_conn_|-| +|MQTT_TOPIC_FILTER|daedalus-agent/agent/#|-| + 重启应用后，就可以登录对话应用，开始使用您的数字员工了。 ## 性能测试 @@ -120,3 +136,24 @@ MQTT/MinIO 密码可在 `系统设置` 页面中 `基础设置` 选项卡获取 本地 `.env`、`.env.*`、测试运行配置、运行状态、报告和常见构建缓存均不应提交到版本库。仓库允许提交 `.env.example` 和 `.env.*.example` 作为脱敏模板；真实 API Key、MQTT/S3 凭据和访问令牌只能写入被 `.gitignore` 覆盖的本地文件或仓库外临时配置。 集成与压测的本地配置及运行文件约定见 [test/README.md](./test/README.md)，Docker 构建与测试说明见 [docker/BUILD.md](./docker/BUILD.md)。 + +## 常见故障排查 + +### 管理控制台无法打开 + +从 Docker 启动到管理控制台就绪通常需要花费数十秒时间，视服务器性能而定，如等待一分钟后重试仍无法打开，说明服务出现故障，请执行 `docker logs daedalus-agent` 命令检查。 + +- 端口冲突：在日志中发现 `bind: Address already in use` 说明端口被占用，您需要检查服务器上是否有其他容器或服务占用了该端口，如果无法排除（如您需要在同一台服务器上运行多个相互硬隔离的 deadalus agent），可以先移除容器，修改 docker 的启动脚本，映射到其他端口号后重新启动，最后同步修改对话应用的全局变量中对应端口号的值。 +- 其他错误：如在日志中没有找到端口冲突的标识性文字，这通常说明遇到了其他错误，请与我们联系排查。 + +### 对话应用提示：Connecting with MQTT server failed (BadUserNameOrPassword). + +检查对话应用全局配置中的 `DA_MQTT_CHANNEL_USERNAME` 和 `DA_MQTT_CHANNEL_PASSWORD`，确保和管理控制台中【系统设置】页面显示的运行凭据一致。重点检查内容是否完整，中间是否有多余的空格。 + +### 对话应用中发送消息后无应答 + +如果发送消息后，5分钟依然无应答，且无法通过重启对话应用来修复，说明通讯链路可能存在异常，请按照以下顺序进行排查： + +1. 在管理控制台的【系统设置】页面中【系统日志下载】选项卡，下载当前日期的 `交互日志`，检查是否存在 `"direction":"IN"` 的入站日志和 `"direction":"OUT"` 的出站日志。 +2. 如果没有进站日志，则检查对话应用全局配置中的 `DA_MQTT_CHANNEL_USERNAME` 和 `DA_MQTT_CHANNEL_PASSWORD`；如果有入站日志，但没有出站日志，则需要在管理控制台的【数字员工】页面中，点击该员工，通过右上角的【对话测试】，检查大语言模型配置是否正确。 +3. 如果存在进出站日志，请检查对话应用全局配置中的 `MQTT_TOPIC_FILTER`。 \ No newline at end of file diff --git a/docker/docs/enterprise-ai-gateway-meeting-review.md b/docker/docs/enterprise-ai-gateway-meeting-review.md new file mode 100644 index 0000000000000000000000000000000000000000..716a69448a784fafb89b058f7d736239f4b4a69d --- /dev/null +++ b/docker/docs/enterprise-ai-gateway-meeting-review.md @@ -0,0 +1,195 @@ +# 企业 AI 基础设施方案适配性与价值评审 + +## 文档信息 + +| 项目 | 内容 | +| --- | --- | +| 评审对象 | `docker/docs/enterprise-ai-gateway-refactoring-plan.md` Draft v2 | +| 评审日期 | 2026-07-30 | +| 事实来源 | AI 调研目录中的四份会议纪要 Markdown | +| 适用前提 | 产品与 Agent 均部署在企业客户环境，不依赖葡萄城运营的云服务 | + +本评审把会议纪要当作产品和市场假设的证据，不把其中的转述、预测或准确率数字视为已审计事实。涉及真实客户、目标系统接口、WorkBuddy 扩展能力和 IdP/OBO 支持情况，仍需在试点前逐项验证。 + +## 1. 五个关键结论 + +1. **方案方向正确，但“模型网关 + 工具网关”本身不完整。** 企业 SSO 只能证明员工身份，还需要 Runtime 工作负载身份、Credential Broker、组织/数据域策略和目标系统最终鉴权，才能让个人 Agent 安全访问 CRM、SRM 等系统。 +2. **两类 Agent 是并行产品形态，不是简单前后序关系。** WorkBuddy 式个人 Agent 解决员工临时、长尾和探索性工作；综管式 Agent 解决稳定、重复、跨系统和可考核任务。它们应共享治理底座，综管式 Agent 额外需要可靠 Task Orchestrator。 +3. **公司级复用应停在协议和独立服务边界。** 可复用的是身份委托、Runtime 注册、模型/工具入口、凭据兑换、任务状态、审计、知识命名空间和契约测试，不是统一语言 SDK、共享数据库、统一 Agent 框架或统一向量库。 +4. **方案对 SpreadJS 和 Phoenix 的直接价值最高，对活字格价值明确，对 Wyn 价值有前置条件。** SpreadJS 可快速成为跨 Agent 的确定性工具；Phoenix 可复用任务、人审、沙箱和生命周期数据；活字格可复用既有权限/流程能力；Wyn 必须先解决语义、数据加工和权限上下文，网关不能直接提高问数准确率。 +5. **首轮交付必须同时证明安全价值和业务价值。** 先用 WorkBuddy/DAEDALUS -> 企业登录 -> Tool Gateway -> 活字格验证身份、权限和审计闭环，再用 SpreadJS 确定性工具或 Phoenix 生命周期任务验证跨产品复用；不建议以 Wyn Chat BI 作为第一个价值试点。 + +## 2. 会议事实与架构判断 + +| 会议事实 | 对方案的判断 | 对应改造 | +| --- | --- | --- | +| 活字格定位为技术集成平台，不做大规模实施；知识库易启动但治理需要实施能力（活字格纪要 33、41-50、211-213 行） | 基础设施应提供治理工具和 Adapter，不能承诺替客户完成业务建模或知识运营 | Data & Knowledge Gateway 定义 ACL、来源和生命周期，但不建设统一内容平台 | +| 活字格 P0 包含视图、数据库、服务端和 MCP，且要保留权限、流程、报表等资产（活字格纪要 118-142、201 行） | 标准工具协议与 Connector 路线适配；业务权限必须留在活字格 | Tool Gateway + HZG Connector + OBO/员工专属凭据 | +| Wyn 裸接数据问数准确率约 30%-40%，客户自研因掌握数据结构、业务语义和权限可到约 90%（Wyn&SpreadJS 纪要 32-43 行） | 通用模型代理不是准确率方案，Data Agent 必须继承业务语义、指标、权限和来源，并持续回归 | Wyn Adapter 优先接语义层和权限，不直接裸接表；RAG 做访问时过滤和来源引用；Evaluation Gate 跟踪准确率 | +| AI 报告比临时问数更容易形成可沉淀资产，Wyn 方向包括 Data Agent、MCP 和工具化（Wyn&SpreadJS 纪要 51-65、93-115 行） | 网关能降低 Agent 接入和治理成本，但报告编排与质量仍属于 Wyn 产品能力 | 将报表预览、导出、指标解释和数据分析暴露为受控工具 | +| SpreadJS/GCExcel 的优势是 Excel 兼容、确定性、计算和性能，建议做 CLI/MCP/Skill（Wyn&SpreadJS 纪要 117-155、170-174 行） | 与“不同技术栈只复用协议”的方案高度匹配，也是最容易证明平台价值的能力 | 独立文档处理服务或 CLI Adapter，经 Tool Gateway 注册为确定性工具 | +| Phoenix 目标是 IDE + DevOps，优先 AI 测试、运维、问题回溯，强调关键节点人工把关（Phoenix 纪要 14-37、43-79、111-133 行） | 仅有工具调用 API 不够，需要可靠任务、等待审批/人工、检查点和生命周期数据 | Task Orchestrator + Approval + Data & Knowledge Gateway + DevOps Connector | +| Phoenix 要拥抱客户已有 Git/Wiki/Bug/CI，每个组件可替换（Phoenix 纪要 146-168 行） | 基础设施不能捆绑一套 DevOps 或共享数据库 | 语言无关 Connector/Adapter 契约和黑盒测试包 | +| Phoenix 希望支持 Python/TypeScript 混合编程和小模型推理（Phoenix 纪要 171-223 行） | 脚本扩展有价值，但会显著扩大命令执行、依赖和供应链风险 | 任务级脚本沙箱、只读基础文件系统、资源限制、Skill 签名和 SBOM | +| WorkBuddy 已被非专业开发人员用于甲方自研；AI Coding 客户仍购买 SpreadJS/活字格（北京销售纪要 18、31 行） | 个人 Agent 是独立长期形态；专业组件不会因 Agent 普及而消失 | 同一受控工具同时供个人 Agent 和综管式 Agent 使用 | +| 下属单位不愿把数据交给集团模型，核心阻力是数据安全和组织信任（北京销售纪要 51-69 行） | 单一租户或集团超级管理员模型不适用 | `tenant_id + organization_id + data_domain`、分域密钥/索引/审计权限 | +| Phoenix 被认可的差异是“可监管、可控、在框架内发挥”（北京销售纪要 105-120、201-205 行） | 统一身份、审批、策略、审计和任务恢复能把该定位落实为可验证能力 | Runtime Registry、Tool Gateway、Approval、不可变审计和人审节点 | + +## 3. 四个产品的适配性与价值 + +### 3.1 Wyn + +**产品方向**：从 BI 功能转向 Data Agent；优先提升准确率、生成可沉淀报告，并把报表、数据集和分析能力工具化。 + +**支持者与理由**：Wyn 产品经理和 AI 研究团队认为 BI 项目正在被 Data Agent 项目升级或替代；Wyn 仍有数据隔离、多租户、国产化、嵌入和跨源处理等企业能力（Wyn&SpreadJS 纪要 69-115、159-174 行）。 + +**方案适配点**： + +- Model Gateway 提供客户内模型的统一路由、预算和审计。 +- Tool Gateway 将报表目录、参数化预览、导出、指标解释等能力开放给不同 Agent。 +- Data & Knowledge Gateway 可同步 Wyn 的语义、指标、来源和 ACL，而不是把数据库表直接交给模型。 +- Credential Broker 让个人 Agent 继承员工的 Wyn 权限，综管任务使用受限服务主体。 +- Evaluation & Release Gate 用产品自有黄金集比较 Agent、Prompt、模型和语义层版本，未达门槛不发布。 + +**价值判断**：中等，满足前置条件后可升为高。基础设施能解决接入、身份和治理，但不能替代数据加工、语义建模、多轮验证和产品内准确率工程。 + +**主要风险**：如果仍以裸接数据的 Chat BI 为核心，平台会把低准确率能力分发到更多入口，放大负面体验；如果网关统一使用超级账号，还会破坏 Wyn 已有的数据权限优势。 + +### 3.2 活字格 + +**产品方向**：前端走 AI Coding，后端保持 AI Low-Coding，复用流程、权限、报表、数据库和服务端能力，并以 MCP 作为 P0 接口。 + +**支持者与理由**：活字格产品经理倾向保留现有企业资产和低门槛，同时承认纯 Low-Coding 在速度、Token 和新用户吸引力上的风险（活字格纪要 52-100、102-142、185-213 行）。 + +**方案适配点**： + +- HZG Connector 可以先复用现有 SDK 和 ServerCommand，不要求重写产品。 +- Tool Gateway 把流程、权限和写操作放到受控边界，允许 WorkBuddy/DAEDALUS 使用同一能力。 +- Credential Broker 避免共享 Cookie，最终权限仍由活字格应用校验。 +- 高风险写操作使用审批、幂等和可撤销流程。 + +**价值判断**：高。它把活字格从“只能被自身设计器使用的低代码能力”变成可被 Agent 调用的企业应用能力，同时保留产品内部权限和流程资产。 + +**主要风险**：如果把所有 ServerCommand 原样暴露为工具，会形成权限过宽、Schema 不稳定和审计不可解释的问题；知识库治理和客户业务建模仍需要交付伙伴，网关不能补齐实施能力。 + +### 3.3 SpreadJS / GCExcel + +**产品方向**：作为 AI 生态中的表格基础设施，以 CLI、MCP 和 Skill 提供结构读取、公式、计算、兼容和导出能力，而不是独立做通用 Agent。 + +**支持者与理由**：SpreadJS 产品经理和 AI 研究团队强调确定性、Excel 完整兼容、前后端全栈和大数据量性能；销售侧的 Skywork、扣子及现有客户案例支持“专业组件仍会被 Agent 购买和集成”的判断（Wyn&SpreadJS 纪要 117-155 行；北京销售纪要 144-151、201-209 行）。 + +**方案适配点**： + +- 通过 MCP 或 REST 契约接入，不依赖 DAEDALUS 的 Node.js 技术栈。 +- Tool Gateway 提供许可、配额、文件大小、超时、审计和租户隔离。 +- 独立文档处理服务加载 SpreadJS/GCExcel 引擎，Agent 只得到结构化结果或受控文件引用。 +- 同一工具可以同时供 WorkBuddy、DAEDALUS 和其他 Agent 平台使用。 + +**价值判断**：很高，且是最快可验证的跨产品价值。确定性工具正好补大模型不稳定，技术边界也相对独立。 + +**主要风险**：浏览器版与服务端引擎边界、License 计量、并发资源、恶意工作簿、宏/外部链接、生成文件泄露都必须先定义；若只包装几个普通表格操作，容易被 WPS 或开源库替代。 + +### 3.4 Phoenix + +**产品方向**：从 IDE 演进为 IDE + DevOps，围绕需求、设计、开发、测试、发布和运维形成 Agent 闭环；同时开放 Python/TypeScript 扩展和行业小模型能力。 + +**支持者与理由**：Phoenix 产品团队将 AI 辅助测试和压测列为 P0，强调 AI 代码不可信、人必须在关键节点把关；问题回溯的价值来自完整生命周期元数据，而非单个 AI 功能（Phoenix 纪要 26-79、111-168、243-268 行）。 + +**方案适配点**： + +- Task Orchestrator 为长测试、压测、问题回溯提供租约、检查点、取消和人工接管。 +- Tool Gateway/Connector 对接客户已有 Git、Wiki、Bug、CI，而不强制替换。 +- Data & Knowledge Gateway 统一需求、设计、代码、测试、发布和日志的来源、ACL 和血缘引用。 +- 脚本沙箱与 Skill 供应链控制 Python/TypeScript 和小模型执行风险。 +- Evaluation & Release Gate 将生成代码、测试策略、回溯结果和安全负向用例纳入版本回归。 + +**价值判断**：高，但工作量大。基础设施能把“可监管”变成真实执行约束，也能支撑生命周期闭环；它不能单独解决 AI 技术方案质量低或 Phoenix 容易被大厂复制的问题。 + +**主要风险**：Task Orchestrator 容易和 Phoenix 自身 DevOps/BPM 重叠；Python/TS 若与平台进程共享依赖、文件系统和环境变量，会直接突破网关安全边界；连接器过多可能把团队拖入实施项目。 + +## 4. 公司级基础设施边界 + +| 公司级模块 | 独立性的来源 | 首要受益方 | 不应承担 | +| --- | --- | --- | --- | +| Identity & Delegation | OIDC/SAML/JWT 标准协议 | 全部产品与 Agent | 产品内部 RBAC 和业务权限定义 | +| Runtime Registry | mTLS、注册/心跳、签名上下文 | WorkBuddy、DAEDALUS、未来 Runtime | Agent 内部调度和对话状态 | +| Model Gateway | OpenAI 兼容 API | 全部 Agent/产品 | Prompt、业务逻辑和知识库 | +| Tool Gateway + Policy + Approval | MCP/REST、JSON Schema、稳定 Tool ID | 全部产品 | Connector 内部业务实现 | +| Credential Broker | OBO、一次性 Handle、Secret 边界 | CRM/SRM/活字格/Wyn/Phoenix | 统一超级账号和业务授权判断 | +| Task Orchestrator | 队列、租约、检查点和人工接管事件 | 综管式 Agent、Phoenix | 通用 BPM 和产品业务流程 | +| Data & Knowledge Gateway | URI、ACL、来源、版本和 Adapter 契约 | Wyn、Phoenix、活字格 | 统一数据库、统一向量库和数据治理实施 | +| Audit & Governance | 统一事件、脱敏、哈希链和 SIEM 导出 | 全部产品与客户安全团队 | 默认永久保存完整对话 | +| Sandbox & Skill Supply Chain | OCI/进程隔离、签名、SBOM、权限清单 | Phoenix、个人 Agent、文档处理 | 执行未审查代码或继承平台密钥 | +| Evaluation & Release Gate | 版本化评测集、回放结果、CI 门禁 | Wyn、活字格、Phoenix、SpreadJS | 用一个通用分数替产品定义业务正确性 | +| Connector/Adapter Test Kit | OpenAPI/JSON Schema/黑盒测试 | 四条产品线 | 强制统一语言 SDK | +| 本地交付与升级包 | 签名镜像、Compose、离线依赖、SBOM、备份/回滚 | 全部模块和客户运维 | 依赖葡萄城云控制面或默认回传遥测 | + +这组边界符合“技术栈不同、产品非云服务”的前提：共享的是网络协议、身份声明、策略模型和可独立部署的服务，不共享进程、数据库或业务代码。小型客户可合并部署逻辑模块，大型客户可按信任区拆容器或主机。 + +## 5. 适配性评审 + +| 维度 | 结论 | 说明 | +| --- | --- | --- | +| 上下文适配 | 高 | 明确支持客户内网、异构技术栈、两类 Agent 和客户既有基础设施 | +| 系统一致性 | 高 | 人员身份、工作负载身份、策略、凭据、Connector 和审计形成闭环 | +| 产品价值 | 中高 | 对 SpreadJS、活字格、Phoenix 价值直接；Wyn 依赖语义和权限前置建设 | +| 可实施性 | 中 | 当前容器 P0/P1 修复明确，但 WorkBuddy 扩展、客户 IdP/OBO、脚本沙箱需预研 | +| 可维护性 | 中高 | 协议优先、产品自有 Connector 能隔离技术栈；组件数量和本地升级仍是成本 | +| 商业价值 | 中高 | “可监管的个人与综管 Agent + 专业组件能力”可形成整包方案，但需渠道/伙伴补实施 | + +### 保留 + +- Control Plane 与数据面分离，Agent 不持有上游模型或业务系统明文凭据。 +- 个人 Agent 和综管式 Agent 共用底座、按身份和任务差异化授权。 +- 产品 Connector 独立实现，首个 HZG、第二个 Wyn/Phoenix 的渐进验证方式。 +- 审计默认 metadata/redacted，原始内容关闭或短期加密留存。 + +### 已补齐 + +- Runtime Registry 与 mTLS/发送方绑定，避免可读 Bearer Key 被复制重放。 +- Task Orchestrator，补上综管任务的可靠运行、取消和人工接管。 +- Credential Broker，明确 OBO、员工专属凭据和服务账号的优先级。 +- Data & Knowledge Gateway，补上组织/数据域、ACL、来源、记忆和派生数据生命周期。 +- MFA/Step-up、单点登出、JWKS 轮换、管理员职责分离和审计防篡改。 +- 文档/浏览器提示词注入隔离、Skill 签名/SBOM 和 Python/TypeScript 沙箱。 +- 开发/测试/生产环境隔离，以及产品自定义的离线评测与发布门禁。 +- 客户本地/离线交付、客户持有根密钥、无默认遥测和两档部署拓扑。 + +### 仍需验证 + +- WorkBuddy 是否提供可信插件、会话上下文或可部署 Sidecar；否则只能做到 Runtime 级、低风险访问。 +- 首个客户 IdP、CRM/SRM/活字格是否支持 OBO、细粒度 API 权限和及时撤权。 +- SpreadJS/GCExcel 的服务端封装、License 计量和多租户资源隔离方式。 +- Wyn 能否稳定暴露语义层、指标、来源和用户权限，而不只提供裸数据访问。 +- Phoenix 的 Task Orchestrator 与自身 DevOps、测试管理和业务流程边界是否重复。 +- 各产品是否能提供可维护的黄金集、确定性断言或人工评分规范，避免评测平台只有技术指标没有业务判断。 +- 客户对离线授权、镜像签名、漏洞库更新、内部 CA/NTP 和升级停机窗口的要求。 + +## 6. 建议的试点与决策门 + +### 试点 A：治理闭环 + +链路：企业 IdP -> WorkBuddy/DAEDALUS -> Runtime Registry -> Model/Tool Gateway -> Credential Broker -> HZG Connector -> 活字格。 + +范围只包含 5 个以内只读工具和 1 个可撤销写工具。成功标准不是“Agent 能调用”，而是能够证明真实员工、Runtime、Agent、会话、工具、资源、审批、目标系统身份和结果，并在员工停用、Runtime 吊销或会话退出后及时失效。 + +### 试点 B：跨产品价值 + +优先选择 SpreadJS/GCExcel 的工作簿结构读取、公式检查、确定性计算和受控导出，让 WorkBuddy 与 DAEDALUS 调用同一组工具。它技术边界清晰、对数据语义依赖较低，最适合验证公司级复用和专业组件的差异化价值。 + +若客户的 Phoenix DevOps 数据较完整，可改选“问题回溯或 AI 测试”任务，验证 Task Orchestrator、人工把关和生命周期血缘，但范围和交付风险更高。 + +### 决策门 + +| 决策点 | 继续条件 | 不满足时 | +| --- | --- | --- | +| Runtime 身份 | WorkBuddy/DAEDALUS 能提供可信上下文或 Sidecar 绑定 | 只开放 Runtime 级低风险只读能力 | +| 业务凭据 | OBO 或员工专属凭据可行 | 禁止写工具，不使用共享超级账号 | +| 跨产品复用 | 第二个 Connector 无需修改网关核心协议 | 修订契约后再扩产品，不堆产品特例 | +| 产品价值 | 试点减少真实人工步骤、错误或交付时间 | 停止扩平台，回到单产品工具优化 | +| 质量门禁 | 新版本在产品自有评测集和安全回放中达到门槛 | 禁止进入生产，保留上一通过版本 | +| 本地可运维 | 升级、备份、证书轮换和资源占用满足客户基线 | 合并部署或关闭可选模块，不继续拆服务 | + +## 7. 总体建议 + +建议继续推进，但把它定位为**客户本地的企业 Agent 信任与执行底座**，而不是新的通用 Agent 产品或统一数据平台。短期投资应集中在当前容器安全止血、企业登录全生命周期、Runtime 身份、凭据兑换、工具策略和审计闭环；Task Orchestrator、Data & Knowledge Gateway 和脚本沙箱由 Phoenix/Wyn 等真实用例拉动。这样既能服务 WorkBuddy 式个人 Agent，也能承接综管式 Agent，同时保留活字格、Wyn、SpreadJS 和 Phoenix 各自的产品边界与技术栈。 diff --git a/docker/docs/enterprise-ai-gateway-refactoring-plan.md b/docker/docs/enterprise-ai-gateway-refactoring-plan.md new file mode 100644 index 0000000000000000000000000000000000000000..4c1b77bc57958d3f675cde5f583c49f2378ccb7f --- /dev/null +++ b/docker/docs/enterprise-ai-gateway-refactoring-plan.md @@ -0,0 +1,1585 @@ +# DAEDALUS_AGENT 企业 Agent 基础设施改造方案 + +## 文档信息 + +| 项目 | 内容 | +| --- | --- | +| 状态 | Draft v2，供架构评审和任务拆分使用 | +| 基线代码 | `3f30cb6` | +| 基线运行镜像 | `daedalus-agent-x64:local` | +| 验证容器 | `2ce686fbdd27d68163585d2c54942ccd9ad1b9f259c7d300a9907f3ca2a523a4` | +| 编写日期 | 2026-07-30 | +| 适用部署 | 企业客户内网、本地服务器或客户自有私有云，不依赖公司侧云服务 | + +本文细化 DAEDALUS_AGENT 从一体化数字员工容器演进为企业 Agent 运行与管控平台的改造方案。它不只增加模型网关和工具网关，还补齐身份、工作负载、任务、凭据、数据知识和审计治理，使 WorkBuddy、DAEDALUS_AGENT/OpenClaw 等不同 Agent Runtime 能在客户内网中受控访问模型与企业系统。方案重点解决两类企业 Agent 的共同基础设施问题： + +- 综管式 Agent：由企业任务系统从上向下派发任务，以服务身份或岗位身份运行。 +- 分散式 Agent：由员工自发使用，但由企业托管身份、模型、工具、策略和审计。 + +两类 Agent 不建设两套基础设施。它们共用身份与委托、Runtime Registry、模型网关、工具网关、Credential Broker、审计和数据治理能力；综管式 Agent 额外依赖可靠的 Task Orchestrator。差异体现在调用主体、授权范围、审批策略、任务生命周期和运行配额，而不是产品技术栈。 + +## 1. 结论与架构决策 + +### 1.1 核心决策 + +DAEDALUS_AGENT 不直接扩展成一个同时承担管理、模型代理、工具执行、密钥保存和审计存储的单体服务。目标边界调整为： + +- DAEDALUS_AGENT Control Plane：管理 Agent、模板、Skill、模型选择、用户分配、策略引用、状态和用量展示。 +- DAEDALUS_AGENT Runtime：运行 OpenClaw 和 Agent，不保存上游模型密钥，不直接访问业务系统。 +- Model Gateway：作为独立数据面代理模型请求，保存上游模型密钥并执行路由、配额、DLP 和审计。 +- Tool Gateway：作为独立数据面代理业务工具请求，执行身份委托、策略、审批、Connector 调度和审计。 +- Runtime Registry：登记 WorkBuddy、DAEDALUS_AGENT/OpenClaw 等 Runtime，签发并轮换工作负载身份，建立 `runtime -> agent -> subject/task` 的可信绑定。 +- Task Orchestrator：为综管式 Agent 提供持久任务队列、状态机、租约、检查点、取消、补偿和人工接管，不把 `task_id` 当成任务系统本身。 +- Credential Broker：将员工或服务主体权限转换为业务系统可接受的短期凭据，优先使用 On-Behalf-Of，禁止统一超级账号。 +- Data & Knowledge Gateway：统一知识、文件、RAG、Workspace 和长期记忆的命名空间、ACL、来源和生命周期，不强制产品共用向量库。 +- Evaluation & Release Gate：统一离线评测数据、版本追踪和发布门禁，产品自定义指标，平台不统一业务正确性标准。 +- Product Connector：按产品独立实现，技术栈不限，只复用标准协议和安全契约。 + +集中登录是必要条件，但不是充分条件。企业 IdP 只能证明“谁登录了”；要把权限安全地串到 CRM、SRM、Wyn、活字格或 Phoenix，还必须同时证明“哪个 Runtime/Agent 在代表他”“本次会话或任务允许做什么”“目标系统最终接受了哪一种受限凭据”。 + +### 1.2 为什么这样拆分 + +Wyn、活字格、SpreadJS、Phoenix 的技术栈和运行形态不同，可复用边界不能建立在语言 SDK、进程内接口或共享数据库上。公司级复用应限定为以下相对独立的能力： + +- OpenAI 兼容的模型访问协议。 +- MCP Streamable HTTP 或稳定的 REST/JSON 工具协议。 +- 企业身份和短期委托令牌。 +- 工具描述、风险等级和审批策略模型。 +- 统一审计事件和脱敏规则。 +- Connector 健康检查、超时、熔断和幂等契约。 +- Runtime 注册、工作负载身份和发送方绑定令牌契约。 +- 组织、数据域、Workspace 和知识对象的统一命名空间。 +- 长任务状态、检查点和人工接管事件契约。 + +### 1.3 本方案不包含 + +- 不要求四个产品统一开发语言、框架或数据库。 +- 不要求第一阶段重写当前活字格调用链。 +- 不建设公司运营的 SaaS 控制面，全部组件可部署在客户环境。 +- 不允许 Agent 直接连接 CRM、SRM、数据库或模型供应商作为生产兜底路径。 +- 不把 `sessionId`、客户端提供的 `userName` 或 localhost 来源视为身份凭据。 +- 不用统一知识库替换 Wyn、活字格、Phoenix 或客户已有的数据与文档系统。 +- 不把 Task Orchestrator 扩展为新的通用 BPM；产品内已有流程继续由活字格、Phoenix 或客户流程平台负责。 + +## 2. 当前实现与已验证问题 + +### 2.1 当前运行链路 + +```text +CUI -> MQTT -> OpenClaw Agent +OpenClaw Agent -> exec -> daedalus-agent-apps-invoke-cli + -> /var/daedalus-agent/run/app-invoke.sock + -> invoke service(daedalus-svc) + -> management web + -> HZG SDK + -> 活字格业务系统 + +OpenClaw Agent -> OpenAI-compatible Provider +``` + +当前实现已有以下可保留能力： + +- OpenClaw 与 management web 使用不同 Linux 用户运行。 +- Agent 的局域网出口受 UID 和 iptables 限制。 +- 业务系统访问集中到 `daedalus-svc` 运行的 invoke service。 +- 支持 Agent 主模型、Fallback 模型和每日 Token 限额。 +- 已有业务调用日志、请求和响应哈希以及 artifact 存储结构。 +- 已安装 `mcporter`，具备 MCP 客户端和 MCP 聚合能力的技术基础。 +- 已有 OpenClaw channel 插件，可得到 `AgentId`、`SessionKey` 和 `MessageThreadId`。 + +### 2.2 阻止生产使用的问题 + +| 级别 | 问题 | 当前实现位置 | 影响 | +| --- | --- | --- | --- | +| P0 | localhost 请求自动成为管理员 | `server/src/api/middleware/auth.js`、`internal.js` | Agent 进程可绕过管理端登录 | +| P0 | `/api/bootstrap` 返回访问 Token 和运行凭据 | `server/src/api/routes/index.js` | Agent 可获取服务 Token、MQTT 和 S3 凭据 | +| P0 | 上游模型 API Key 写入 Agent 可读的 OpenClaw 配置 | `management-src/capabilities/llm/service.ts` | 提示词注入或恶意 Skill 可窃取模型密钥 | +| P1 | `tools.exec.mode` 为 `full` | `docker/assets/config.json` | Agent 可直接执行任意本地命令并探测控制面 | +| P1 | 工具调用主要依赖 `sessionId` | `apps-invoke-cli/src/protocol/messages.ts` | 调用未绑定真实用户、Agent 和工具权限 | +| P1 | 外部会话 API 信任调用方提供的 `userName` | `server/src/services/external-service.js` | 服务 Token 代表应用，不能证明员工身份 | +| P1 | MQTT 使用共享凭据且无 Topic ACL | `docker/assets/scripts/mqtt-broker.js` | 一个客户端可访问其他 Agent Topic | +| P1 | 工具请求和响应完整落盘，无字段级脱敏和保留期 | `server/src/services/system-service.js` | 审计存储本身成为敏感数据源 | +| P2 | 工具 Provider 固定为 `hzg` | `system-service.js`、`external-service.js` | 不能作为多产品通用工具网关 | +| P2 | OpenClaw 端口不提供通用模型代理 API | 运行时端口 `18789` | 其他产品不能复用其模型配置能力 | + +容器黑盒验证得到以下结果，验证过程未输出真实凭据： + +- 宿主机匿名请求 `http://127.0.0.1:3030/api/bootstrap` 返回 `401`。 +- 容器内以 `daedalus-agent` 用户请求同一地址返回 `200`，角色为 `daedalus-admin`。 +- `daedalus-agent` 用户可以读取至少一个上游模型 API Key。 +- OpenClaw 命令执行模式为 `full`。 +- `18789` 上的 `/v1/models` 和 `/v1/chat/completions` 返回 HTML，不是 OpenAI 兼容 API。 +- `mcporter` 已安装，但没有配置文件，也没有运行中的 MCP 聚合服务。 + +## 3. 目标架构 + +```mermaid +flowchart LR + subgraph ClientZone["用户与任务入口"] + Personal["员工个人 Agent 入口"] + Managed["综管任务系统"] + Admin["企业管理员"] + end + + subgraph ControlZone["控制面"] + IdP["企业 IdP"] + Identity["身份与委托服务"] + Registry["Runtime Registry"] + Control["DAEDALUS Control Plane"] + Orchestrator["Task Orchestrator"] + Approval["审批中心"] + Evaluation["Evaluation & Release Gate"] + end + + subgraph AgentZone["不可信 Agent 运行区"] + WorkBuddy["WorkBuddy Runtime"] + Daedalus["DAEDALUS/OpenClaw Runtime"] + ToolBridge["可信 Tool Bridge"] + end + + subgraph GatewayZone["受控数据面"] + ModelGateway["Model Gateway"] + ToolGateway["Tool Gateway"] + Credential["Credential Broker"] + Knowledge["Data & Knowledge Gateway"] + Audit["Audit Service"] + end + + subgraph ConnectorZone["产品 Connector"] + HZG["活字格 Connector"] + WYN["Wyn Connector"] + SJS["SpreadJS Connector"] + Phoenix["Phoenix Connector"] + end + + Personal --> IdP + Managed --> Orchestrator + Admin --> Control + Control --> Evaluation + IdP --> Identity + Identity --> WorkBuddy + Identity --> Daedalus + Registry -. "工作负载身份" .-> WorkBuddy + Registry -. "工作负载身份" .-> Daedalus + Orchestrator --> Daedalus + WorkBuddy --> ModelGateway + Daedalus --> ModelGateway + WorkBuddy --> ToolBridge + Daedalus --> ToolBridge + WorkBuddy --> Knowledge + Daedalus --> Knowledge + ToolBridge --> ToolGateway + ToolGateway --> Approval + ToolGateway --> Credential + Credential --> HZG + Credential --> WYN + Credential --> Phoenix + ToolGateway --> HZG + ToolGateway --> WYN + ToolGateway --> SJS + ToolGateway --> Phoenix + ModelGateway --> Audit + ToolGateway --> Audit + Identity --> Audit + Registry --> Audit + Orchestrator --> Audit + Credential --> Audit + Knowledge --> Audit + Audit --> Evaluation +``` + +### 3.1 信任区定义 + +| 信任区 | 信任级别 | 允许持有的凭据 | 禁止事项 | +| --- | --- | --- | --- | +| Agent Runtime | 不可信 | 可撤销、限额的试点凭据；生产使用工作负载证书和短期令牌 | 不得持有上游模型 Key、业务系统 Cookie、Connector 服务凭据 | +| Control Plane | 管理可信 | 管理会话、配置引用、签名公钥 | 不直接代理模型请求，不保存业务请求原文 | +| Identity/Delegation | 高可信 | 签名私钥、IdP 客户端凭据 | 不把私钥或用户令牌传入 Prompt | +| Runtime Registry | 高可信 | Runtime 证书、注册和吊销状态 | 不把静态共享 Bearer Key 当成 Runtime 身份 | +| Task Orchestrator | 管理可信 | 任务授权引用、检查点和租约 | 不保存模型或业务系统明文凭据，不绕过 Tool Gateway | +| Evaluation & Release Gate | 管理可信 | 脱敏评测集、版本和质量结果 | 不保存生产密钥，不替产品定义业务正确性 | +| Model Gateway | 高可信 | 上游模型密钥 | 不允许 Agent 绕过网关直连上游模型 | +| Tool Gateway | 高可信 | Connector 访问引用、策略和审批状态 | 不信任调用方提供的用户名或 Agent 名称 | +| Credential Broker | 最高可信 | OBO Token、员工专属凭据和受限服务账号 | 不向 Agent、Prompt、日志或通用配置返回明文凭据 | +| Data & Knowledge Gateway | 受限可信 | 数据源引用、对象 ACL、加密 Key | 不跨组织/数据域检索，不把长期记忆默认共享 | +| Connector | 受限可信 | 对应产品的最小权限凭据 | 不读取其他 Connector 的密钥和数据 | + +### 3.2 两种 Agent 形态的策略差异 + +| 维度 | 企业托管个人 Agent | 综管式 Agent | +| --- | --- | --- | +| 主体 | 员工身份 `user` | 服务身份或岗位身份 `service_principal` | +| 权限上限 | 不超过员工本人在业务系统中的权限 | 不超过任务配置的资源范围和服务账号权限 | +| 启动方式 | 员工主动发起 | 任务系统、调度器或事件触发 | +| 高风险操作 | 员工确认或业务审批 | 任务预授权，超出范围时审批 | +| 审计归属 | 员工、Agent、会话 | 任务、发起系统、服务主体、Agent | +| 典型用途 | 查询、分析、辅助填报 | 批处理、跨系统编排、例行检查 | +| 运行保障 | 交互会话，可选后台任务 | 持久队列、租约、检查点、取消、补偿、人工接管 | +| 凭据优先级 | 员工 OBO 或员工专属凭据 | 受限服务主体；涉及个人权限时仍使用 OBO | + +## 4. 安全设计原则 + +以下原则作为所有后续实现和评审的强制约束： + +1. 默认拒绝：没有显式身份、工具和资源授权的请求必须拒绝。 +2. localhost 不可信：来自 loopback 的请求仍需认证和授权。 +3. Prompt 不持有凭据：上游 Key、业务 Cookie、委托令牌不得进入 Prompt、Skill 文本或模型上下文。 +4. 身份不可由调用方声明：`userName`、`AgentName` 和资源范围必须来自签名令牌或服务端会话映射。 +5. 控制面和数据面分离：管理配置的 API 与执行模型或工具请求的 API 使用不同监听地址、身份和权限。 +6. Agent 不能直连：Agent 网络出口只允许访问 Model Gateway、Tool Bridge/Tool Gateway 和必要的企业代理。 +7. 完整审计、最少留存：记录决策链和哈希，原始内容按敏感级别加密并限期保存。 +8. 高风险操作可中断：写入、删除、付款、发布等操作必须支持审批、取消和幂等。 +9. 组织、数据域和环境先于工具授权：所有请求都必须携带可信的 `tenant_id`、`organization_id`、`data_domain` 和 `environment_id`，禁止只按用户或 Agent 做平面隔离，也禁止测试 Agent 静默访问生产资源。 +10. 人与工作负载双重身份：员工登录不能替代 Runtime 认证；Runtime 身份也不能替代员工或服务主体授权。 +11. 外部内容默认不可信：网页、文档、邮件、代码仓库和工具输出中的指令不得改变系统策略、审批要求或凭据边界。 +12. Skill 和运行环境可验证：生产 Skill/插件必须签名、登记版本和 SBOM；Agent Runtime 使用只读基础文件系统、资源配额和受控出口。 + +## 5. 企业身份与委托令牌 + +### 5.1 身份来源 + +生产形态优先使用企业 IdP，支持顺序建议如下： + +1. OIDC/OAuth 2.1：首选，适用于新建 CUI 和 Web 管理入口。 +2. SAML 2.0：通过本地身份适配器转换为内部身份声明。 +3. AD/LDAP：仅用于用户目录同步或内网登录，登录后仍签发内部会话令牌。 +4. 本地管理员：只作为安装和灾难恢复账号，不作为普通员工身份源。 + +`POST /api/external/session` 不再接收可决定身份的 `userName`。服务端从经过验证的用户令牌中取得 `sub`，再校验该用户是否被分配给目标 Agent。 + +企业登录还必须覆盖以下生命周期，而不是只完成一次 SSO： + +- 支持 IdP MFA；访问高敏数据或执行高风险工具时触发 Step-up Authentication。 +- 支持前台会话退出、IdP 单点登出和后台委托撤销，不能出现“门户已退出但 Agent 仍可调用”的残留会话。 +- 通过 SCIM、AD/LDAP 同步或客户目录事件处理入职、调岗、离职和组织变更。 +- 管理员采用独立 RBAC，至少区分平台管理员、模型管理员、工具/策略管理员、审批管理员、审计员和密钥管理员；高风险策略修改与审批不得由同一角色闭环完成。 +- JWT 验证使用本地缓存的 JWKS，支持签名 Key 轮换、重叠验证窗口和紧急吊销；客户内网断网时仍能按策略继续验证已缓存公钥。 + +### 5.2 委托令牌内容 + +工具调用使用短期签名 JWT，建议采用 Ed25519 或 ES256。示例声明如下： + +```json +{ + "iss": "daedalus-identity", + "aud": "daedalus-tool-gateway", + "sub": "employee-123", + "subject_type": "user", + "tenant_id": "customer-a", + "organization_id": "east-company", + "data_domain": "sales", + "environment_id": "production", + "client_id": "daedalus-runtime", + "runtime_id": "runtime-021", + "agent_id": "personal-agent-08", + "session_id": "session-opaque-id", + "task_id": null, + "tools": ["hzg.sales_order.read"], + "resources": ["organization:east"], + "purpose": "prepare-sales-report", + "approval_id": null, + "cnf": { + "x5t#S256": "runtime-certificate-thumbprint" + }, + "iat": 1785388500, + "exp": 1785388800, + "jti": "c54d08cc-7b07-4fa5-92f8-9d9ea20b1742" +} +``` + +约束： + +- 默认有效期不超过 5 分钟。 +- 高风险工具令牌应绑定单一工具、单一资源和单次 `jti`。 +- Tool Gateway 必须校验 `iss`、`aud`、`exp`、`jti`、工具范围和资源范围。 +- Tool Gateway 必须同时校验租户、组织、数据域、环境、Runtime 状态，以及 `cnf` 绑定的 mTLS 证书或等价发送方证明。 +- 撤销列表至少覆盖会话终止、员工离职、Agent 停用和审批撤销。 +- 数据库只保存 `jti`、状态和必要审计字段，不保存完整 Bearer Token。 + +### 5.3 令牌不能由 LLM 直接处理 + +当前 CLI 由 Agent 通过通用 `exec` 调用，这会把安全参数暴露给 Agent。目标实现增加可信 `daedalus-tool-bridge`： + +1. OpenClaw channel 根据已认证入口建立 `subject -> agent -> session` 映射。 +2. LLM 只选择工具和生成业务参数。 +3. Tool Bridge 从 OpenClaw 可信运行上下文取得 `AgentId`、`SessionKey` 和 `MessageThreadId`。 +4. Tool Bridge 向 Identity Service 请求最小范围委托令牌。 +5. Tool Bridge 在 Prompt 之外附加令牌并调用 Tool Gateway。 + +仓库现有 MQTT channel 已能构造上述运行上下文，见 `extensions/openclaw-plugins/daedalus-agent-mqtt-channel/src/channel-runtime.ts`。但固定版本 OpenClaw `2026.7.1` 是否支持注册自定义 Tool 插件，需要在阶段 0 完成技术预研。预研失败时采用以下降级方案： + +- CLI v2 只接收不可猜测的会话句柄，不接收用户名和业务凭据。 +- 本地 Token Broker 根据服务端会话映射签发令牌。 +- CLI v2 和 Token Broker 使用独立 Unix Socket，限制固定 UID 访问。 +- 该降级方案可用于试点，不作为多租户强隔离的最终形态。 + +### 5.4 集中登录如何把权限串起来 + +完整链路如下： + +```text +企业 IdP 认证员工 + -> Identity Service 建立内部 Subject 和组织/数据域上下文 + -> Runtime Registry 证明请求来自已登记的 WorkBuddy 或 DAEDALUS Runtime + -> Identity Service 按 Agent、Session/Task、Tool 和 Resource 签发短期委托 + -> Tool Gateway 进行策略、审批和 DLP 判定 + -> Credential Broker 将委托兑换为目标系统可接受的最小权限凭据 + -> Connector 调用目标系统，并由目标系统做最终业务权限校验 +``` + +因此，CRM、SRM 等系统应由 Tool Gateway/Connector 代表 Agent 对接，个人 Agent 和综管式 Agent 都不直接保存业务凭据。两类 Agent 可以调用同一工具，但前者通常使用员工 OBO 权限，后者使用受任务范围约束的服务主体；权限语义不能由网关自造，最终仍以目标系统的 RBAC、数据权限和业务规则为准。 + +## 6. Model Gateway 设计 + +### 6.1 职责 + +Model Gateway 负责： + +- 提供统一 OpenAI 兼容 Runtime API。 +- 保存、加密和轮换上游模型 API Key。 +- 校验 Agent 或产品客户端身份。 +- 执行模型白名单、路由、Fallback、配额和并发控制。 +- 统一超时、有限重试、熔断和错误码。 +- 对输入输出执行敏感信息检测和可配置拦截。 +- 生成模型调用审计事件和 Token 用量事件。 + +Model Gateway 不负责： + +- 管理 Agent workspace、Skill 和会话历史。 +- 保存业务系统凭据。 +- 决定员工对 CRM/SRM 的业务权限。 +- 将模型返回内容自动执行为业务写操作。 + +### 6.2 Runtime API + +第一阶段至少实现： + +```text +GET /v1/models +POST /v1/chat/completions +POST /v1/embeddings +GET /health/live +GET /health/ready +``` + +后续根据 OpenClaw 和其他产品需求增加： + +```text +POST /v1/responses +POST /v1/rerank +``` + +试点期 Runtime API 可使用受限 Bearer 客户端凭据；生产使用 mTLS 工作负载身份和发送方绑定短期令牌。请求头中的 Agent、用户和用途字段只作为辅助诊断信息，授权事实必须来自已验证凭据或服务端映射，不能直接信任自定义请求头。 + +### 6.3 Admin API + +Admin API 只监听控制面网络，不对 Agent Runtime 开放： + +```text +POST /admin/v1/providers +PATCH /admin/v1/providers/{providerId} +DELETE /admin/v1/providers/{providerId} +POST /admin/v1/providers/{providerId}:test +POST /admin/v1/models +PATCH /admin/v1/models/{modelRef} +DELETE /admin/v1/models/{modelRef} +PUT /admin/v1/routes/{routeId} +POST /admin/v1/clients +POST /admin/v1/clients/{clientId}:rotate +POST /admin/v1/clients/{clientId}:revoke +``` + +Management web 通过服务身份调用 Admin API。UI 只接收新密钥一次，不通过 `/bootstrap` 或目录同步返回明文。 + +### 6.4 凭据保存 + +单机部署建议采用本地信封加密： + +- Master Key 通过独立文件或 Docker Secret 挂载，只允许 Model Gateway UID 读取。 +- Provider Key 使用 AES-256-GCM 加密后保存，记录 `key_id`、IV、Tag 和指纹。 +- 日志、数据库查询和管理 API 永不返回明文 Provider Key。 +- 轮换时先创建新版本，连通性测试成功后原子切换，旧版本保留短暂回滚窗口。 + +建议持久化位置： + +```text +/var/daedalus-agent/model-gateway/data/ +/var/daedalus-agent/model-gateway/secrets/ +/var/daedalus-agent/model-gateway/logs/ +``` + +目录不得对 `daedalus-agent` 和 management web 用户开放读取。 + +### 6.5 Agent 客户端凭据 + +OpenClaw 当前 Provider 配置使用静态 `apiKey`，且单个 OpenClaw 进程中的 Provider 配置可能被多个 Agent 共用。为保证第一阶段可落地，采用三步演进： + +- 安全止血：使用 Runtime 或策略组级、可撤销的 Gateway Client Key。Agent 即使读取该 Key，也只能使用网关允许的模型和总配额，不能得到上游模型 Key。 +- 细粒度控制：如果一个 Runtime 只承载一个 Agent，可以直接签发 per-Agent Key；共享 Runtime 不宣称已经做到可靠的 per-Agent 身份隔离。 +- 生产目标：通过可信 Model Bridge 附加 Agent/Session 上下文，或为高隔离客户采用每 Agent Runtime，再使用短期 Gateway Token 和 per-Agent 配额。 + +Gateway Client Key 必须独立于管理 Token，服务端只保存哈希。MVP 至少支持按 Runtime/策略组立即撤销，完成可信上下文桥接后再支持按 Agent 立即撤销。 + +### 6.6 路由与配额 + +路由匹配顺序建议为： + +1. 客户端和租户禁用状态。 +2. Agent 或产品允许模型白名单。 +3. 请求用途和数据级别限制。 +4. 主模型健康状态和并发上限。 +5. Fallback 模型策略。 +6. 日配额、月预算和单请求 Token 上限。 + +当前 Agent 的主模型、Fallback 和每日限额仍由 management web 管理，但最终执行点迁移到 Model Gateway。Control Plane 中的字段是期望配置，Gateway 的策略和用量是执行事实。 + +### 6.7 流式与错误处理 + +- SSE 数据必须边接收边转发，不在网关完整缓存模型输出。 +- 在尚未向客户端发送响应体前，可对连接错误和限流错误做有限重试。 +- 已开始流式输出后不得透明重试，避免重复内容和重复工具调用。 +- 对外返回稳定错误码，例如 `gateway_auth_failed`、`model_not_allowed`、`quota_exceeded`、`upstream_timeout`。 +- 审计中记录上游 Provider、实际 Model、Fallback 次数和错误分类，不记录上游密钥或完整 Authorization Header。 + +## 7. Tool Gateway 设计 + +### 7.1 对外接口 + +Tool Gateway 同时提供三种入口，以支持渐进迁移和不同技术栈： + +1. MCP Streamable HTTP：面向支持 MCP 的 Agent 和产品。 +2. REST/JSON Invoke API：面向现有服务和无法直接集成 MCP 的客户端。 +3. Unix Socket v2：仅供同机 DAEDALUS Agent 使用，作为当前 CLI 的迁移路径。 + +REST 调用示例： + +```http +POST /api/v1/tools/hzg.sales_order.read:invoke HTTP/1.1 +Authorization: Bearer +Content-Type: application/json +Idempotency-Key: 7bcfe241-16a7-4fbb-b8f2-1b30594878c8 + +{ + "traceId": "9dccb274-dff3-42a4-a1e7-ef1120c07c56", + "input": { + "orderId": "SO-2026-001" + } +} +``` + +响应统一包含： + +```json +{ + "traceId": "9dccb274-dff3-42a4-a1e7-ef1120c07c56", + "status": "succeeded", + "data": {}, + "error": null, + "auditEventId": "audit-opaque-id" +} +``` + +### 7.2 工具注册模型 + +每个 Connector 通过工具清单注册能力。建议最小 Schema 如下： + +```yaml +id: hzg.sales_order.create +version: 1.0.0 +connectorId: hzg-main +displayName: 创建销售订单 +description: 在指定活字格应用中创建销售订单 +riskLevel: high +sideEffect: write +idempotency: required +requiredPermissions: + - sales_order.create +allowedSubjectTypes: + - user + - service_principal +inputSchema: + type: object + additionalProperties: false + required: [customerId, items] + properties: {} +outputSchema: + type: object + properties: {} +resourceResolver: organization_from_customer +allowedEnvironments: [production] +redactionProfile: sales-order +approvalPolicy: sales-write +timeoutMs: 30000 +``` + +工具 ID 使用稳定的三段式命名： + +```text +{product}.{resource}.{action} +``` + +工具描述中不能包含 Connector 密钥、内部 Cookie、数据库连接串或可绕过网关的直连地址。 + +### 7.3 风险等级 + +| 等级 | 典型操作 | 默认策略 | +| --- | --- | --- | +| low | 查询公开目录、读取低敏汇总 | 身份和工具授权通过后自动执行 | +| medium | 读取客户明细、生成文件、可撤销写入 | 校验业务权限，必要时要求用户确认 | +| high | 创建订单、修改主数据、发布报表 | 显式确认或审批，必须使用幂等键 | +| critical | 删除、付款、批量外发、权限变更 | 双人审批或禁止 Agent 执行 | + +风险等级只是默认策略，企业可以按部门、数据级别和 Agent 类型覆盖，但不能把 `critical` 静默降级为自动执行。 + +### 7.4 策略执行顺序 + +```text +认证委托令牌 + -> 校验 Subject、Agent、Session/Task 状态 + -> 校验工具白名单 + -> 解析资源范围 + -> 校验业务权限 + -> 执行输入 Schema 与 DLP 检查 + -> 判断是否需要审批 + -> 调用 Connector + -> 输出 Schema 与 DLP 检查 + -> 写审计事件 +``` + +任何阶段失败都不得继续调用 Connector。授权失败与资源不存在对非管理员返回一致的安全错误，避免枚举业务资源。 + +策略必须版本化并采用 `draft -> simulate -> approved -> active -> retired` 生命周期。发布前使用近期脱敏审计事件回放策略差异；生产策略变更需要独立审批并记录发布人、审批人、版本和生效范围。Break-glass 只能由受限应急角色在限时、限范围条件下启用，并产生最高级别告警，不能绕过目标系统最终鉴权。 + +### 7.5 审批流程 + +```mermaid +sequenceDiagram + participant A as Agent + participant B as Tool Bridge + participant G as Tool Gateway + participant P as Approval Service + participant C as Connector + + A->>B: 选择高风险工具和参数 + B->>G: 调用工具，携带委托令牌 + G->>G: 身份、权限、Schema、DLP 检查 + G->>P: 创建审批请求和参数摘要 + P-->>G: 返回 pending 和 approvalId + G-->>B: approval_required + P->>G: 审批通过，签发 approval grant + B->>G: 使用原 traceId 和 idempotencyKey 重试 + G->>C: 执行一次 + C-->>G: 返回结果 + G-->>B: 返回脱敏结果和 auditEventId +``` + +审批页面展示经过脱敏但足够决策的参数摘要，审批通过后不允许 Agent 修改参数。可对规范化输入计算哈希并写入 approval grant。 + +### 7.6 Connector 契约 + +Connector 可使用任意语言实现，但必须满足统一协议： + +```text +GET /connector/v1/health +GET /connector/v1/tools +POST /connector/v1/invoke +``` + +或直接提供标准 MCP Server。Tool Gateway 负责协议适配、认证和策略，不允许 Agent 直接访问 Connector 地址。 + +Connector 必须支持： + +- 明确的输入和输出 JSON Schema。 +- 调用超时和取消信号。 +- `traceId` 透传。 +- 写操作幂等键。 +- 结构化错误码，不把异常堆栈返回给 Agent。 +- 最小权限业务凭据。 +- 健康检查和版本信息。 + +### 7.7 活字格 Connector 的渐进改造 + +现有 `daedalus-agent-apps-invoke-cli serve` 作为第一版活字格 Connector 基础，不立即重写 HZG SDK 调用： + +1. 保留 `hzg-provider-client.ts` 的 SDK 封装和 binding 名称归一化。 +2. 从 `handler.ts` 中拆出通用调用上下文和 HZG Connector 接口。 +3. Socket 协议新增 v2，不删除 v1： + +```json +{ + "protocolVersion": 2, + "traceId": "uuid", + "toolId": "hzg.sales_order.read", + "sessionId": "opaque-session", + "delegationToken": "attached-by-trusted-bridge", + "idempotencyKey": "uuid", + "input": {} +} +``` + +4. Service 在执行 HZG SDK 前调用 Tool Gateway 策略接口，或直接由 Tool Gateway 进程加载 HZG Connector。 +5. `sessionId` 只用于查找会话和审计，不再单独产生业务调用权限。 +6. 原 `servercommand`、`binding` CLI 参数保留一段兼容期，由本地映射表转换为稳定 Tool ID。 + +生产目标应将 Cookie 解析从 Connector 中移到凭据代理：Connector 获取一次性 Credential Handle，由 Credential Broker 在内存中换取实际 Cookie，Cookie 不写入调用日志。 + +### 7.8 其他产品 Connector + +| 产品 | 首批建议能力 | 注意事项 | +| --- | --- | --- | +| Wyn | 报表目录查询、参数化预览、导出、权限检查 | 必须复用 Wyn 自身用户和报表权限，禁止网关统一超级账号 | +| SpreadJS | 工作簿结构读取、公式检查、受控计算、文档转换 | 浏览器内能力需通过宿主应用或独立文档处理服务暴露，不能假设 SpreadJS 自身是服务端系统 | +| Phoenix | 依据现有业务 API 定义首批读工具和少量可撤销写工具 | Connector 只适配接口，不复制 Phoenix 业务权限逻辑 | +| 活字格 | ServerCommand、Binding、应用元数据 | 先完成身份委托和日志脱敏，再扩展工具数量 | + +第二个 Connector 应选择 Wyn 或 Phoenix，用于验证通用 Tool Gateway 没有继续依赖 HZG 特有字段。SpreadJS 更适合在文档处理服务边界明确后接入。 + +## 8. 企业 Agent 运行支撑层 + +本节中的组件是逻辑边界，不要求 MVP 立即拆成五个独立容器。客户本地部署初期可以将 Runtime Registry 和 Task Orchestrator 作为 Control Plane 内的独立模块，将 Credential Broker 作为 Tool Gateway 旁路高可信模块，将 Data & Knowledge Gateway 先实现为统一契约和少量 Adapter。边界稳定、容量或合规要求出现后再拆进程。 + +### 8.1 Runtime Registry 与工作负载身份 + +企业 SSO 只能认证人，不能证明模型请求或工具调用确实来自被批准的 Agent Runtime。Runtime Registry 负责： + +- 登记 `runtime_id`、实例、产品类型、版本、所属租户/组织、可承载的 Agent 和支持协议。 +- 为 WorkBuddy、DAEDALUS/OpenClaw 或其他 Runtime 签发短期证书或可轮换设备证书，并维护吊销状态。 +- 建立 `runtime_id -> agent_id -> subject_id/session_id` 或 `task_id/service_principal` 的可信绑定。 +- 记录 Runtime 健康状态、最后心跳、版本、Skill 清单、SBOM 摘要和策略版本。 +- 对共享 Runtime 明确隔离级别；无法提供可信 per-Agent 上下文时，只能按 Runtime 授权，不能宣称已实现 per-Agent 隔离。 + +推荐接入方式按安全强度排序： + +1. Runtime 原生支持 mTLS 和可信上下文插件，由 Bridge 生成发送方绑定令牌。 +2. 在 Runtime 同机部署企业管理的 Sidecar/Bridge，由 Unix Socket 或命名管道接收受限请求并附加身份。 +3. 试点期使用可撤销的 Runtime Key，但必须限制模型、工具、来源地址和配额，并尽快迁移；可读静态 Bearer Key 不能作为生产终态。 + +Runtime 最小心跳数据示例： + +```json +{ + "runtimeId": "runtime-021", + "runtimeType": "daedalus-openclaw", + "instanceId": "host-a-runtime-01", + "version": "2026.7.1", + "agentIds": ["personal-agent-08"], + "skillSetDigest": "sha256:...", + "status": "ready" +} +``` + +### 8.2 Task Orchestrator + +综管式 Agent 不能只靠一次 HTTP 调用和一个 `task_id` 运行。Task Orchestrator 提供可靠任务运行面： + +- 持久队列、优先级、计划任务和事件触发。 +- 状态机：`queued -> leased -> running -> waiting_approval/waiting_human -> succeeded/failed/cancelled`，必要时进入 `compensating`。 +- 租约、心跳和超时接管，防止 Runtime 崩溃后任务永久悬挂或重复执行。 +- 步骤级检查点、有限重试、退避、幂等键和补偿动作。 +- 用户取消、管理员暂停、人工接管和从检查点恢复。 +- 任务级模型预算、工具白名单、数据域、截止时间和最大并发。 + +任务信封至少包含： + +```json +{ + "taskId": "task-opaque-id", + "tenantId": "customer-a", + "organizationId": "east-company", + "dataDomain": "sales", + "environmentId": "production", + "initiatorSubjectId": "employee-123", + "runAs": "service-principal-sales-report", + "agentId": "managed-agent-02", + "purpose": "monthly-sales-report", + "policySetId": "managed-report-v1", + "inputRefs": ["knowledge://customer-a/east-company/sales/production/2026-06"], + "deadline": "2026-08-01T08:00:00+08:00", + "maxModelTokens": 200000 +} +``` + +Task Orchestrator 只管理 Agent 任务的可靠执行，不替代活字格/Phoenix 的业务流程引擎，也不直接调用产品 API。每一步业务操作仍经 Tool Gateway；等待审批和人工接管必须进入统一审计。 + +### 8.3 Credential Broker + +Credential Broker 解决“通过网关之后，目标系统到底接受什么身份”的问题。凭据选择顺序固定为： + +1. **On-Behalf-Of 用户令牌**：目标系统支持 OIDC/OAuth 时首选，CRM/SRM 可以直接执行员工原有权限和数据范围。 +2. **员工专属凭据代持**：旧系统只支持 Cookie、API Key 或用户名密码时，由 Broker 加密保存每名员工的独立凭据，运行时签发一次性 Credential Handle。 +3. **受限服务账号**：仅用于明确的综管任务，必须绑定组织、数据域、工具、资源和用途；禁止一个超级账号服务所有员工和 Agent。 + +约束： + +- Agent、Prompt、Skill、Task Payload 和通用日志永远看不到实际凭据。 +- Connector 使用一次性 Handle 或短期 Token，且 Handle 绑定 `runtime_id`、`agent_id`、`subject/task`、`tool_id` 和 `trace_id`。 +- 凭据读取、兑换、失败、轮换和吊销都写入独立审计事件。 +- 员工离职、调岗、单点登出或目标系统权限变化时，缓存委托应在可配置窗口内失效。 +- 无法证明业务系统最终按员工或受限服务主体鉴权的 Connector，只能进入只读试点，不允许高风险写入。 + +### 8.4 Data & Knowledge Gateway + +Data & Knowledge Gateway 不建设一个替代所有产品的数据平台，而是为不同技术栈提供统一的治理契约和 Adapter： + +- 统一 URI 和命名空间：`tenant/organization/data_domain/environment/subject/agent/workspace/session_or_task/object`。 +- 对接客户现有文档库、对象存储、数据库、Wyn 数据语义层、活字格应用数据和 Phoenix DevOps 文档，不要求迁移到同一向量库。 +- 摄取时执行文件类型校验、恶意文件扫描、敏感信息识别、来源登记、版本和 ACL 同步。 +- 检索时执行 Security Trimming；RAG 返回内容必须携带来源、版本、授权依据和可引用片段。 +- 长期记忆默认按用户和 Agent 隔离，跨用户/部门共享必须显式发布到组织知识空间。 +- 会话结束、任务结束、员工离职、数据源删除和保留期到期时，清理缓存、向量索引、临时文件和派生内容。 + +该模块对四类产品的价值不同：Wyn 重点复用数据语义、指标和原有权限；活字格重点复用应用元数据、流程和知识文档；Phoenix 重点复用需求、设计、Git、Bug、CI、测试和日志血缘；SpreadJS 重点处理受控工作簿和生成文件，不需要被强行纳入长期知识库。 + +### 8.5 不可信内容、Skill 供应链与运行沙箱 + +分散式 Agent 会接触网页、邮件、文档和用户自装 Skill，提示词注入和供应链风险高于固定综管任务。生产基线包括： + +- Browser Gateway/企业代理负责域名白名单、下载扫描、内容类型限制和访问审计；浏览器会话与高权限工具会话隔离。 +- 文档解析在低信任进程中完成，抽取文本标记来源和不可信等级；文档中的“忽略策略”“上传凭据”等内容不得改变系统指令或工具授权。 +- Tool Gateway 只接受注册工具和结构化参数，不允许模型通过工具输入注入 `Authorization`、Cookie、内部 URL 或任意命令。 +- Skill/插件发布前完成签名、来源、版本、权限清单、SBOM、许可证和静态扫描；生产 Runtime 默认禁止加载未签名 Skill。 +- Runtime 使用非 root 用户、只读基础文件系统、临时可写 Workspace、CPU/内存/进程数限制和默认拒绝的网络出口。 +- Python/TypeScript 等脚本执行必须进入独立沙箱，按任务挂载最小文件和短期工具能力，不能继承 Control Plane 或 Connector 环境变量。 + +### 8.6 Evaluation & Release Gate + +会议中的三个问题都需要可重复评测，而不是只靠演示判断：Wyn 需要跟踪问数准确率，活字格需要比较时间、Token 和可维护性，Phoenix 需要证明生成代码、测试策略和问题回溯的可靠性。公司级 Evaluation & Release Gate 只统一评测运行和证据格式： + +- 记录 Agent 模板、Prompt、模型、Skill、工具 Schema、Connector、数据集和评测器版本。 +- 支持产品自带的离线黄金集、回放集、确定性断言、人工评分和安全负向用例。 +- 输出准确率、任务成功率、人工接管率、工具错误率、Token/时延/成本和越权拒绝率等基础指标。 +- 新版本先在脱敏或合成数据上运行，达到产品团队设定的门槛后才可发布到指定组织和环境。 +- 评测集按产品和数据域隔离；平台不要求 Wyn、活字格、SpreadJS 和 Phoenix 使用同一种业务评分器。 + +该模块不进入在线请求关键路径，也不承诺用一个通用分数衡量所有 Agent。MVP 可以先用版本化文件、CI Job 和统一结果 Schema 实现，达到复用规模后再建设独立服务。 + +## 9. 审计与数据治理 + +### 9.1 统一审计事件 + +Model Gateway、Tool Gateway、Identity Service、Runtime Registry、Task Orchestrator、Credential Broker、Data & Knowledge Gateway、Evaluation Service 和 Approval Service 使用统一事件字段： + +```json +{ + "eventId": "opaque-id", + "traceId": "uuid", + "eventType": "tool.invocation.completed", + "tenantId": "customer-a", + "organizationId": "east-company", + "dataDomain": "sales", + "environmentId": "production", + "subjectId": "employee-123", + "subjectType": "user", + "clientId": "daedalus-runtime", + "runtimeId": "runtime-021", + "agentId": "personal-agent-08", + "sessionId": "opaque-session", + "taskId": null, + "taskStepId": null, + "targetId": "hzg.sales_order.read", + "skillId": "sales-analysis", + "skillVersion": "1.2.0", + "credentialGrantId": "grant-opaque-id", + "policyDecision": "allow", + "policyIds": ["sales-read-default"], + "policyVersions": ["sales-read-default@3"], + "approvalId": null, + "inputSha256": "hex", + "outputSha256": "hex", + "success": true, + "durationMs": 82, + "createdAt": "2026-07-30T10:00:00+08:00" +} +``` + +### 9.2 内容留存 + +建议默认值如下，最终由客户安全和合规要求覆盖： + +| 数据 | 默认留存 | 保存形式 | +| --- | ---: | --- | +| 身份和策略决策元数据 | 180 天 | 结构化数据库 | +| 模型和工具调用计量 | 180 天 | 结构化数据库 | +| 输入输出哈希 | 180 天 | 结构化数据库 | +| 脱敏预览 | 30 天 | 结构化数据库 | +| 加密原始 Payload | 默认关闭；开启时 7 天 | 独立对象存储 | +| 审批记录 | 365 天 | 结构化数据库和审批摘要 | + +加密原始 Payload 必须满足： + +- 与审计索引分开保存。 +- 使用独立数据加密 Key。 +- 按部门或数据域配置保留期。 +- 支持管理员按 `traceId` 解密查看并产生二次审计。 +- 到期删除对象、数据库引用和旧 Key 版本。 + +### 9.3 脱敏规则 + +当前 `previewPayload` 只有截断能力。改造后使用结构化规则： + +- 固定敏感字段：`password`、`secret`、`token`、`authorization`、`cookie`、`apiKey`。 +- 工具清单声明的业务字段，例如身份证、手机号、银行卡号、客户名称。 +- 内容扫描规则，用于无法依赖字段名的文本和文件。 +- 输出显示规则，例如仅保留后四位或不可逆哈希。 + +脱敏必须发生在持久化之前。`redaction_status` 使用可验证状态，例如 `redacted`、`metadata_only`、`encrypted_raw`、`redaction_failed`；`redaction_failed` 时默认只保存元数据，不保存原文。 + +### 9.4 防篡改与可信时间 + +- 审计事件采用仅追加写入，普通平台管理员无更新和删除权限。 +- 每批事件计算哈希链并生成签名检查点；客户有合规要求时导出到 WORM 对象锁或既有 SIEM/日志审计平台。 +- 所有节点使用客户可信 NTP，事件同时记录业务时间、接收时间和递增序号，避免依赖 Agent 提供的时间戳。 +- 审计导出、解密查看、保留期修改和清理操作本身也进入不可变审计链。 +- 审计员只能查看策略允许的数据域；密钥管理员、策略管理员和审计员职责分离。 + +## 10. 服务数据模型 + +各服务拥有自己的存储，不允许通过共享 SQLite 文件直接耦合。单机 MVP 可分别使用 SQLite，进入高可用部署后迁移 PostgreSQL。服务间只通过 API 和事件同步。 + +### 10.1 Control Plane 新增或调整 + +| 表/对象 | 关键字段 | 说明 | +| --- | --- | --- | +| `identity_subjects` | `subject_id`、`type`、`issuer`、`status` | 企业用户和服务主体映射 | +| `external_sessions` | `subject_id`、`agent_id`、`expires_at` | 会话绑定真实身份，不再由 `userName` 决定 | +| `agent_policy_bindings` | `agent_id`、`policy_set_id` | Agent 与模型/工具策略集绑定 | +| `service_clients` | `client_id`、`credential_hash`、`scopes`、`status` | 内部服务身份，替代无范围 access token | +| `organization_domains` | `tenant_id`、`organization_id`、`data_domain`、`environment_id`、`parent_id` | 组织、数据域和环境边界，不假定集团与下属单位天然互信 | +| `admin_role_bindings` | `subject_id`、`admin_role`、`scope`、`status` | 管理 RBAC 和职责分离 | +| `component_sync_state` | `component`、`version`、`last_sync_at` | 记录 Gateway 配置同步状态 | + +现有 `access_tokens` 不继续作为通用共享 Bearer Token。迁移后只保留兼容期 Token，并增加 Scope、过期时间、哈希和撤销状态；新服务统一使用服务身份或 mTLS。 + +### 10.2 Model Gateway + +| 表/对象 | 关键字段 | +| --- | --- | +| `model_providers` | `provider_id`、`base_url`、`secret_ref`、`status` | +| `model_provider_secret_versions` | `secret_ref`、`ciphertext`、`key_id`、`version`、`status` | +| `model_catalog` | `model_ref`、`provider_id`、上下文和能力字段 | +| `model_routes` | `route_id`、匹配条件、主模型、Fallback、限额 | +| `gateway_clients` | `client_id`、`credential_hash`、允许模型和配额 | +| `model_usage_events` | `trace_id`、Token、模型、主体、时间 | + +### 10.3 Tool Gateway + +| 表/对象 | 关键字段 | +| --- | --- | +| `connectors` | `connector_id`、`protocol`、`endpoint`、`secret_ref`、`status` | +| `tool_definitions` | `tool_id`、`version`、Schema、风险等级、Connector | +| `tool_policies` | `policy_id`、匹配条件、决策、审批策略 | +| `delegations` | `jti`、主体、Agent、Session/Task、范围、状态、过期时间 | +| `approval_requests` | `approval_id`、输入哈希、状态、审批人、过期时间 | +| `idempotency_records` | `tool_id`、`subject_id`、`idempotency_key`、结果引用 | +| `audit_events` | 统一审计字段、Payload 引用 | + +### 10.4 Runtime Registry 与 Task Orchestrator + +| 表/对象 | 关键字段 | +| --- | --- | +| `runtime_registrations` | `runtime_id`、类型、版本、租户/组织、证书指纹、状态 | +| `runtime_instances` | `instance_id`、`runtime_id`、主机、心跳、能力、Skill/SBOM 摘要 | +| `runtime_agent_bindings` | `runtime_id`、`agent_id`、隔离级别、状态 | +| `agent_tasks` | `task_id`、租户/组织/数据域/环境、发起人、`run_as`、Agent、策略、状态、预算 | +| `task_steps` | `task_step_id`、租约、心跳、尝试次数、检查点、幂等键、结果引用 | +| `task_human_actions` | `task_id`、动作、操作者、原因、时间 | + +### 10.5 Credential Broker 与 Data & Knowledge Gateway + +| 表/对象 | 关键字段 | +| --- | --- | +| `credential_accounts` | `account_id`、主体、目标系统、类型、加密引用、状态 | +| `credential_grants` | `grant_id`、主体/任务、Runtime、Agent、Tool、资源、过期和兑换状态 | +| `knowledge_sources` | `source_id`、Adapter、租户/组织/数据域、ACL 同步状态、版本 | +| `knowledge_objects` | `object_id`、来源、命名空间、分类、内容哈希、ACL、保留期 | +| `knowledge_derivatives` | `object_id`、切片/向量/缓存引用、模型版本、清理状态 | +| `agent_memories` | `memory_id`、Subject、Agent、Session/Task、可见范围、过期时间 | + +实际凭据和原始知识内容不得直接保存在上述索引表中，分别进入独立加密存储；索引库只保存引用、策略字段和哈希。 + +### 10.6 Evaluation & Release Gate + +| 表/对象 | 关键字段 | +| --- | --- | +| `evaluation_suites` | `suite_id`、产品、数据域、指标定义、Owner、版本 | +| `evaluation_cases` | `case_id`、输入引用、期望/评分器引用、敏感级别、版本 | +| `evaluation_runs` | `run_id`、Agent/Prompt/模型/Skill/Tool/Connector 版本、环境、状态 | +| `evaluation_results` | `run_id`、指标、结果、失败样本引用、人工复核状态 | +| `release_gates` | `gate_id`、目标组织/环境、门槛、审批、发布版本、状态 | + +## 11. 部署与网络改造 + +### 11.1 阶段 A：保持单容器，先完成进程隔离 + +为降低改造风险，第一阶段不要求立即拆分镜像，但必须增加独立 Unix 用户： + +```text +daedalus-agent OpenClaw Agent Runtime +daedalus-control management web / Control Plane +daedalus-model-gw Model Gateway +daedalus-tool-gw Tool Gateway +daedalus-credential Credential Broker +daedalus-knowledge Data & Knowledge Gateway +daedalus-connector HZG Connector +``` + +Runtime Registry 和 Task Orchestrator 在阶段 A 可运行在 `daedalus-control` 进程边界内，但数据表、接口和权限必须独立；Credential Broker 因持有业务凭据，从第一版开始使用独立 UID。知识文件解析器必须使用比 `daedalus-knowledge` 更低权限的临时进程。 + +最小权限目录建议： + +| 路径 | Owner | Agent 权限 | +| --- | --- | --- | +| `/var/daedalus-agent/.openclaw` | `daedalus-agent` | 读写 | +| `/var/daedalus-agent/control` | `daedalus-control` | 无 | +| `/var/daedalus-agent/model-gateway` | `daedalus-model-gw` | 无 | +| `/var/daedalus-agent/tool-gateway` | `daedalus-tool-gw` | 无 | +| `/var/daedalus-agent/credential-broker` | `daedalus-credential` | 无 | +| `/var/daedalus-agent/knowledge` | `daedalus-knowledge` | 无；只能经受控 API 访问 | +| `/var/daedalus-agent/connectors/hzg` | `daedalus-connector` | 无 | +| `/var/daedalus-agent/run/tool-bridge.sock` | `daedalus-tool-gw:daedalus-agent` | 仅连接 | + +单容器模式仍必须取消 loopback 免认证。内部服务使用不同的 Scope Token 或 Unix Socket，不得因为同容器而获得管理员权限。 + +### 11.2 阶段 B：拆分为本地多容器 + +生产推荐使用 Docker Compose；客户已有 Kubernetes 时再提供 Helm，不要求第一版同时维护两套编排。 + +建议服务： + +```text +daedalus-control-plane +daedalus-agent-runtime +daedalus-runtime-registry +daedalus-task-orchestrator +daedalus-model-gateway +daedalus-tool-gateway +daedalus-credential-broker +daedalus-knowledge-gateway +daedalus-connector-hzg +daedalus-mqtt +daedalus-minio +``` + +上述是可部署单元清单，不表示小规模客户必须运行九个以上容器。标准本地版可以将 Registry/Orchestrator 合并到 Control Plane，将 Knowledge Gateway 与受限解析 Worker 组合部署；高隔离版再按清单拆分。部署包必须给出单机资源基线和按功能关闭可选模块的方式。 + +网络划分： + +- `edge-net`：CUI、反向代理和需要公开的管理入口。 +- `control-net`：Control Plane、Identity、Runtime Registry、Task Orchestrator、Approval、Gateway Admin API。 +- `agent-net`：Agent Runtime 到两个 Gateway Runtime API。 +- `connector-net`：Tool Gateway、Credential Broker、Data & Knowledge Gateway 到各 Connector/Adapter。 +- `data-net`：数据库和对象存储，仅对应服务可访问。 + +Agent Runtime 不加入 `control-net`、`connector-net` 和 `data-net`。Connector 不加入 `agent-net`。 + +### 11.3 端口暴露 + +当前默认映射 `3030-3050`、`1883` 和 `9000` 到所有宿主机接口。生产改造后： + +- 只通过反向代理暴露必要的 HTTPS 入口。 +- Model Gateway Runtime API 默认仅对 `agent-net` 和授权产品开放。 +- Gateway Admin API 仅对 `control-net` 开放。 +- MinIO 不直接映射到企业办公网。 +- MQTT 若继续使用，采用每个 CUI/Agent 独立凭据和 Topic ACL。 +- `3031-3050` 不再作为无条件预留并全部映射，应按实际服务逐个开放。 + +### 11.4 Agent 出口策略 + +生产模式下，`daedalus-agent` UID 或 Agent Runtime 容器默认只能访问： + +- Model Gateway Runtime API。 +- Tool Bridge/Tool Gateway Runtime API。 +- 经审批的文件扫描或内容处理服务。 +- DNS、NTP 等基础服务。 + +不再默认允许 Agent 访问整个互联网。需要网页浏览的 Agent 通过独立 Browser Gateway 或企业代理访问，并应用域名白名单、下载扫描和审计。 + +WorkBuddy 若不能部署在同一 Compose 中，必须通过客户内网反向代理或 Sidecar 进入 `agent-net` 的授权入口，并完成 mTLS Runtime 注册。不能因为它运行在员工桌面就放宽工具直连、静态凭据和审计要求。 + +### 11.5 客户本地与离线交付 + +- 标准交付物包含签名镜像、Compose 配置、离线依赖包、SBOM、许可证清单、配置模板、升级/回滚和备份恢复工具。 +- 所有组件默认禁止向葡萄城或第三方遥测地址回传数据；需要许可证激活时提供客户可接受的离线授权方式，并明确采集字段。 +- 优先复用客户内部 DNS、NTP、CA、镜像仓库、日志平台和对象存储；没有时才部署最小本地依赖。 +- 根加密 Key、签名 Key 和备份加密 Key 由客户控制，安装包不得内置跨客户共享密钥。 +- 提供“标准合并部署”和“高隔离拆分部署”两档拓扑及资源基线，不要求所有客户使用 Kubernetes。 +- 模型 Provider 可以是客户本地模型服务或客户批准的外部出口；无外网时核心身份、工具、审计和任务能力仍可运行。 +- 离线漏洞库、签名信任根和撤销列表必须有人工导入与审计流程，不能因断网永久停止安全更新。 + +## 12. 源码改造清单 + +### 12.1 现有文件 + +| 路径 | 改造内容 | 重点测试 | +| --- | --- | --- | +| `server/src/api/middleware/auth.js` | 删除 localhost 自动管理员逻辑 | loopback 无 Token 返回 401 | +| `server/src/api/middleware/internal.js` | 用有 Scope 的服务身份替代 loopback 放行 | 错误 Scope 返回 403 | +| `server/src/api/routes/index.js` | 拆分 bootstrap、secret 和 token 管理 API | bootstrap 不包含任何明文凭据 | +| `server/src/services/auth-service.js` | 删除 `getLocalApiUser` 依赖，增加服务主体校验 | 管理员和服务主体不可互换 | +| `server/src/services/external-service.js` | 从认证上下文取得用户身份，绑定 Session 和 Agent | 伪造 `userName` 无效 | +| `server/src/services/large-language-model-service.js` | 改为调用 Model Gateway Admin API | Provider Key 不写入本地缓存 | +| `management-src/capabilities/llm/service.ts` | 停止把上游 Key 写入 OpenClaw；写入 Gateway 地址和客户端 Key | OpenClaw 配置不出现上游 Key | +| `server/src/services/system-service.js` | 调用日志先脱敏再落盘，增加保留期和 Payload 加密引用 | 敏感字段不出现在日志文件 | +| `apps-invoke-cli/src/protocol/messages.ts` | 增加 v2 协议和版本协商 | v1/v2 兼容及拒绝未知版本 | +| `apps-invoke-cli/src/proxy/socket-service.ts` | 验证委托令牌、限制 Payload 和并发 | 缺失/伪造令牌不能到达 Handler | +| `apps-invoke-cli/src/proxy/handler.ts` | 从固定 HZG 执行拆为通用 Connector 调度 | Tool ID 到 Connector 的稳定映射 | +| `apps-invoke-cli/src/proxy/hzg-provider-client.ts` | 实现 HZG Connector 契约，移除日志中的 Cookie | HZG 回归测试和错误映射 | +| `docker/assets/config.json` | 限制通用 exec，业务工具改走可信 Bridge | Agent 无法通过 exec 绕过 Tool Gateway | +| `docker/assets/scripts/mqtt-broker.js` | 每客户端认证和 Topic ACL | 跨 Agent 发布/订阅被拒绝 | +| `docker/assets/scripts/startup.sh` | 创建独立用户、目录、Socket 和健康检查 | 权限、重启和持久化测试 | +| `docker/assets/scripts/apps-startup.sh` | 分离 Control、Gateway 和 Connector 进程 | 单进程故障不泄漏凭据 | + +### 12.2 建议新增模块 + +```text +packages/daedalus-agent-model-gateway/ +packages/daedalus-agent-tool-gateway/ +packages/daedalus-agent-identity/ +packages/daedalus-agent-audit/ +packages/daedalus-agent-runtime-registry/ +packages/daedalus-agent-task-orchestrator/ +packages/daedalus-agent-credential-broker/ +packages/daedalus-agent-knowledge-gateway/ +packages/daedalus-agent-evaluation/ +extensions/openclaw-plugins/daedalus-agent-tool-bridge/ +``` + +为控制第一阶段规模，可以把 Identity、Runtime Registry、Task Orchestrator、Approval 和 Audit 先作为 Tool Gateway/Control Plane 中边界清晰的模块实现，但必须使用独立接口和表，不能继续散落在路由和 Provider 代码中。Credential Broker 必须保持独立权限边界；Data & Knowledge Gateway 可以先交付协议、ACL 和两个 Adapter，再按容量拆进程。 + +### 12.3 技术选型约束 + +- 新增 Node 服务默认使用 TypeScript，保持与现有管理端和 invoke CLI 的构建链一致。 +- 模型协议转换可以引入成熟代理引擎，但必须先完成许可证、离线部署、流式兼容和安全评审。 +- 策略 MVP 可使用代码化规则；规则数量和客户定制增加后再评估 OPA/Casbin 等独立策略引擎。 +- Connector 不强制 TypeScript，只需通过 MCP 或 Connector REST 契约测试。 +- WorkBuddy、Wyn、活字格、SpreadJS 和 Phoenix 不强制引用共享 SDK；优先发布 OpenAPI、JSON Schema、MCP 清单、事件 Schema 和语言无关的黑盒契约测试包。 +- 不允许新服务直接读取 management web 的 SQLite 文件。 + +## 13. 迁移计划 + +迭代长度按团队现有节奏确定。以下顺序表示依赖关系，不是固定日历承诺。 + +### 阶段 0：技术预研和安全基线 + +交付物： + +- 固定 OpenClaw `2026.7.1` 的 Tool 插件注册和上下文传递验证。 +- Model Gateway 流式代理最小原型。 +- 委托令牌签发、校验和撤销原型。 +- WorkBuddy 和 DAEDALUS/OpenClaw 的 Runtime 身份、可信上下文和 Sidecar 可行性验证。 +- 选择一个客户目标系统验证 OBO；若不支持，验证员工专属 Credential Handle，不允许直接退化为共享超级账号。 +- 选择一个真实知识源验证对象 ACL 和组织/数据域过滤，不先建设通用向量平台。 +- 当前容器安全回归脚本，固化已发现的 P0/P1 问题。 +- 架构决策记录：MCP Transport、Token 签名算法、密钥存储方式、Runtime 工作负载身份和客户 IdP 接入方式。 + +退出条件： + +- 能证明工具令牌在 Prompt 外附加；如果不能，明确采用 CLI v2 降级方案。 +- 能证明 SSE 工具调用消息可通过 Model Gateway 无损转发。 +- 能证明同一员工从未登记 Runtime 或其他 Runtime 重放委托时被拒绝。 +- 安全回归脚本在旧版本失败，在修复分支通过。 + +### 阶段 1：安全止血 + +交付物： + +- 移除所有 localhost 免认证逻辑。 +- `/api/bootstrap` 不再返回访问 Token 和运行凭据。 +- 内部 API 使用服务身份和 Scope。 +- 部署最小 Model Secret Proxy，只负责隔离上游 Provider Key 和转发现有 OpenAI 兼容请求；完整路由、配额和管理能力在阶段 2 实现。 +- MQTT 每客户端凭据和 Topic ACL。 +- 调用日志字段级脱敏和可配置保留期。 +- Agent 网络出口改为显式允许列表。 + +退出条件： + +- `daedalus-agent` 用户访问管理 API 无凭据时全部返回 401/403。 +- Agent 无法读取 management、MQTT、S3 和上游模型明文凭据。 +- 跨 Agent MQTT Topic 测试全部拒绝。 +- 敏感字段扫描在持久化目录中无命中。 + +### 阶段 2：Model Gateway MVP + +交付物： + +- 独立 Runtime API 和 Admin API。 +- Provider Key 加密、轮换和管理 UI 适配。 +- Runtime/策略组 Gateway Client Key；独立 Runtime 场景支持 per-Agent Key。 +- Runtime Registry MVP：登记、心跳、证书轮换、吊销和 Agent 绑定。 +- 主模型、Fallback、Token 限额和用量审计。 +- OpenClaw 只连接 Model Gateway。 + +退出条件： + +- OpenClaw 配置和 Agent 可读文件中不存在上游 Provider Key。 +- 禁用 Runtime/策略组或撤销 Client Key 后，模型请求立即失败；具备可信 Agent 上下文时再验证按 Agent 撤销。 +- 未登记、已吊销、证书与令牌不匹配的 Runtime 请求全部失败。 +- 现有主模型、Fallback 和配额用例通过。 +- 网关自身故障不会自动退回直连 Provider。 + +### 阶段 3：Tool Gateway MVP 和活字格迁移 + +交付物： + +- Tool Registry、Policy、Delegation、Approval 和 Audit 最小闭环。 +- Tool Bridge 或 CLI v2。 +- Credential Broker MVP，至少覆盖员工专属 Credential Handle；目标系统支持时优先实现 OBO。 +- HZG Connector 和旧命令映射。 +- low/medium/high 三档策略和幂等处理。 +- v1/v2 兼容开关和迁移监控。 + +退出条件： + +- 只有 `sessionId` 的请求不能调用业务系统。 +- 伪造用户、Agent、Tool ID 或资源范围均被拒绝。 +- 高风险工具未经审批不能到达 HZG SDK。 +- Agent、Prompt、Tool Bridge 日志和 Connector 日志中不存在目标系统明文凭据。 +- 相同幂等键不会产生两次写操作。 +- 审计能完整关联员工、Agent、会话、工具、资源、审批和结果。 + +### 阶段 4：企业身份、可靠任务和第二个 Connector + +交付物： + +- OIDC 企业登录和用户目录映射。 +- MFA/Step-up、单点登出、调岗/离职同步、JWKS 轮换和管理员 RBAC。 +- 服务主体支持综管式 Agent。 +- Task Orchestrator MVP：队列、租约、心跳、取消、检查点、人工接管和模型预算。 +- Wyn 或 Phoenix Connector。 +- MCP/REST Connector 契约测试套件。 +- 管理 UI 中的工具、策略和审批查询。 + +退出条件： + +- 个人 Agent 权限不超过员工本人。 +- 综管式 Agent 的权限不超过任务授权范围。 +- 第二个 Connector 不依赖 HZG 特有字段或 Cookie 模型。 +- 员工停用后，新会话和新委托立即失败。 +- Runtime 崩溃后任务可从检查点接管，取消或审批等待不会造成重复写入。 + +### 阶段 5：数据知识治理和产品价值试点 + +交付物： + +- Data & Knowledge Gateway 的命名空间、ACL、来源、版本和生命周期契约。 +- 两个 Adapter：一个文档/知识源，一个产品数据源；优先从 Phoenix DevOps 血缘或 Wyn 语义/权限上下文中选择有真实客户数据的方向。 +- 文件解析沙箱、恶意文件扫描和提示词注入隔离。 +- Skill 签名、权限清单、SBOM 和生产 Runtime 白名单。 +- Evaluation & Release Gate MVP，先覆盖一个 Wyn/活字格质量集和一个 Phoenix/SpreadJS 确定性或安全回放集。 +- SpreadJS/GCExcel 首批确定性工具或 Phoenix 生命周期 Agent 试点，用于验证平台产生业务价值，而不只验证安全合规。 + +退出条件： + +- 不同组织和数据域使用相同关键词检索时不会返回越权内容。 +- 原知识对象撤权或删除后，缓存、向量切片和派生文件在约定窗口内失效。 +- 文档中的恶意指令不能修改系统策略、调用未授权工具或获取凭据。 +- 至少一个非活字格产品在不引用网关实现代码的前提下通过契约测试。 +- Agent/Prompt/模型/Skill/工具版本变更未达到产品门槛时，不能发布到目标生产环境。 + +### 阶段 6：生产化 + +交付物： + +- Docker Compose 多容器部署和升级脚本。 +- 数据备份恢复、密钥轮换、审计导出和告警。 +- 审计哈希链、签名检查点和客户 WORM/SIEM 导出选项。 +- 高可用存储选项和容量规划。 +- 安全测试、压力测试、故障注入和客户验收手册。 + +退出条件： + +- 满足第 15 节的生产验收门槛。 +- 完成至少一次备份恢复演练和密钥轮换演练。 +- 完成一个真实客户网络环境的灰度试点。 + +## 14. 兼容、灰度与回滚 + +### 14.1 功能开关 + +建议增加： + +```text +DA_MODEL_GATEWAY_ENABLED=true|false +DA_TOOL_GATEWAY_PROTOCOL=v1|v2 +DA_TOOL_POLICY_MODE=observe|enforce +DA_AUDIT_PAYLOAD_MODE=metadata|redacted|encrypted +DA_MQTT_ACL_MODE=observe|enforce +DA_RUNTIME_IDENTITY_MODE=static|mtls +DA_TASK_ORCHESTRATOR_ENABLED=true|false +DA_KNOWLEDGE_GATEWAY_ENABLED=true|false +DA_UNSIGNED_SKILLS_ALLOWED=false +DA_RELEASE_GATE_MODE=observe|enforce +``` + +`observe` 仅用于迁移期生成策略决策差异，不允许在生产长期保持。`static` 只允许试点期使用，并须设置迁移期限。P0 安全修复不提供回退到不安全行为的开关；生产不得开启未签名 Skill。 + +### 14.2 灰度顺序 + +1. 内部测试 Agent。 +2. 只读活字格工具。 +3. 少量内部员工个人 Agent。 +4. 可撤销写工具。 +5. 高风险审批工具。 +6. 综管式批量任务。 +7. 第二个产品 Connector。 +8. 受 ACL 保护的知识源和长期记忆。 +9. WorkBuddy 等外部 Runtime。 + +### 14.3 回滚原则 + +- Model Gateway 回滚到前一网关版本，不回滚到 Agent 直连 Provider。 +- Tool Gateway v2 可回滚到前一 v2 版本；v1 只允许非敏感、只读工具作为临时兼容。 +- 数据库迁移采用 expand/contract，先增加新字段和双读，再停止旧写入，最后删除旧结构。 +- 轮换密钥保留有限旧版本窗口，但旧密钥不得重新下发给 Agent。 +- 审计事件必须先持久化策略决策，再执行高风险 Connector 调用；审计服务故障时高风险写操作默认失败关闭。 +- Task Orchestrator 回滚时不得丢弃已租赁任务；先停止新租约，等待或回收运行中任务，再切换版本。 +- Knowledge Adapter 回滚不能恢复已撤销 ACL 或已过保留期内容；派生索引必须跟随源对象版本回滚或重建。 + +## 15. 测试与生产验收 + +### 15.1 单元测试 + +- Token 签发、过期、错误 Audience、撤销和重放。 +- 工具 Schema 校验、资源解析和策略匹配。 +- 风险等级和审批状态机。 +- Provider Key 加解密和轮换。 +- 日志字段脱敏和保留期计算。 +- 幂等键状态机和并发竞争。 +- Runtime 注册、证书轮换、吊销和发送方绑定验证。 +- 任务租约、心跳超时、取消、重试、检查点和补偿状态机。 +- Credential Handle 单次兑换、范围绑定和过期。 +- 知识对象 ACL、派生数据失效和长期记忆可见范围。 + +### 15.2 契约测试 + +- OpenAI Chat Completions、SSE、Tool Calls 和错误响应。 +- MCP Tool List、Tool Call 和断连恢复。 +- Connector REST 的 Schema、错误码、超时和取消。 +- Runtime Registry 心跳/注册、Task Worker 租约和 Knowledge Adapter ACL 契约。 +- 审计事件字段完整性和向后兼容。 + +每个非 TypeScript Connector 也必须运行同一套黑盒契约测试。 + +### 15.3 集成测试 + +- OpenClaw -> Model Gateway -> 模拟 Provider。 +- OpenClaw -> Tool Bridge -> Tool Gateway -> HZG 模拟器。 +- CUI 登录 -> Session -> Agent -> Tool -> Audit 完整链路。 +- 综管任务 -> 服务主体 -> Agent -> 审批 -> Tool 完整链路。 +- 企业 SSO -> WorkBuddy/DAEDALUS Runtime -> OBO/Credential Broker -> CRM/HZG 模拟器完整链路。 +- Task Orchestrator -> Runtime 崩溃 -> 租约回收 -> 检查点恢复 -> 幂等工具完整链路。 +- 知识源撤权 -> ACL 同步 -> 检索缓存和向量切片失效完整链路。 +- Gateway 重启、Provider 限流、Connector 超时和审批过期。 + +### 15.4 安全回归 + +必须自动化以下负向用例： + +- Agent 通过 localhost 调用 management API。 +- Agent 读取 Provider Key、管理 Token、MQTT/S3 凭据。 +- 伪造 `userName`、`AgentName`、`sessionId` 和 Tool ID。 +- 使用其他 Agent 的委托令牌或 MQTT Topic。 +- 使用未登记 Runtime、已吊销 Runtime 或从另一台主机复制的 Bearer Token。 +- 使用过期、撤销、错误 Audience 和已重放的令牌。 +- 通过工具输入注入 Cookie、Authorization Header 或内部 URL。 +- 通过日志、错误栈和审计预览获取敏感字段。 +- 通过通用 exec、MCP 直连或 Connector 地址绕过 Tool Gateway。 +- 通过网页、Office 文档、PDF、邮件或工具输出注入指令，尝试越权调用工具或泄露凭据。 +- 加载未签名、SBOM 不匹配或申请额外权限的 Skill/插件。 +- 跨 `tenant_id`、`organization_id`、`data_domain`、用户 Workspace 或长期记忆检索。 +- 使用测试环境令牌、Credential Handle、Connector 或知识引用访问生产环境。 +- SSO 退出、员工离职或调岗后继续使用旧 Session、OBO Token 或 Credential Handle。 +- 普通管理员修改审计记录，或同一管理员完成高风险策略修改和审批。 + +### 15.5 性能基线 + +当前仓库已有 100 Agent、1000 用户和并发 20/50/100 的测试基线。改造后至少复用同一规模，并增加： + +- Model Gateway 流式首包延迟和非流式额外开销。 +- Tool Gateway 策略判定和审计写入额外开销。 +- 单 Agent 和多 Agent 的公平限流。 +- 同一幂等键并发写入竞争。 +- 审计服务和 Approval Service 降级行为。 +- Task Orchestrator 的队列吞吐、租约回收和检查点大小。 +- Knowledge Gateway 的 ACL 过滤开销、索引失效延迟和解析沙箱资源上限。 +- Evaluation 回放吞吐、评测数据隔离和 CI 发布门禁耗时。 + +建议初始目标值，需在阶段 0 根据客户硬件确认： + +- 网关本身增加的模型请求 P95 延迟不高于 100 ms，不含上游模型耗时。 +- 无审批的本地工具调用增加的 P95 延迟不高于 100 ms，不含 Connector 和业务系统耗时。 +- 100 Agent 并发基线下不出现跨 Agent 身份、配额或审计串线。 +- 安全相关拒绝测试错误率必须为 0，不能以性能为由放宽。 + +### 15.6 生产验收门槛 + +以下条件必须全部满足： + +1. Agent 可读目录中不存在上游模型和业务系统明文凭据。 +2. Agent 不能绕过两个网关直接访问模型或业务系统。 +3. 每次调用都能确定真实主体、Agent、会话或任务、目标、策略和结果。 +4. 个人 Agent 权限不超过员工本人，综管式 Agent 权限不超过任务授权。 +5. 高风险和关键风险工具按策略完成确认或审批。 +6. 日志在落盘前完成脱敏，原始 Payload 有加密和保留期。 +7. 密钥撤销、员工停用和 Agent 停用能够及时生效。 +8. 完成备份恢复、密钥轮换、故障注入和压力测试。 +9. 所有调用都能验证 Runtime 工作负载身份，复制静态凭据不能在其他实例重放。 +10. 组织、数据域和环境隔离同时覆盖工具、知识、长期记忆、审计查询和管理员权限。 +11. 综管任务支持取消、崩溃接管和人工接管，写操作在恢复后不会重复执行。 +12. Skill/插件可追溯到签名版本和 SBOM，脚本与文档解析运行在受限沙箱。 +13. 审计记录具备哈希链或等价防篡改证明，并使用可信时间源。 +14. 发布到生产的 Agent、Prompt、模型、Skill 和工具组合均能关联最近一次通过的评测运行。 + +## 16. 可观测性与运维 + +### 16.1 指标 + +Model Gateway： + +- 按客户端、Agent、模型统计请求数、Token、并发、限流和错误。 +- 上游 Provider 延迟、首包延迟、Fallback 和熔断状态。 +- Client Key 撤销和异常来源使用次数。 + +Tool Gateway： + +- 按工具、Connector、主体类型统计调用数、拒绝、审批和错误。 +- 策略判定耗时、Connector 延迟、幂等命中和超时。 +- 跨资源越权尝试、令牌重放和 DLP 拦截次数。 + +Agent 运行支撑层： + +- Runtime 在线数、版本分布、证书到期、心跳丢失和身份拒绝。 +- 任务队列深度、等待时长、租约超时、重试、人工接管、取消和补偿结果。 +- Credential 兑换次数、失败、目标系统、凭据类型和异常重复兑换。 +- 知识源 ACL 同步延迟、索引失效、解析失败、跨域拒绝和派生数据清理积压。 + +### 16.2 告警 + +- Agent 访问 Control Plane、Secret 目录或未允许网络目标。 +- 同一 Client Key 从异常地址或多个部署实例使用。 +- 上游 Provider Key 认证失败或即将过期。 +- 高风险工具拒绝率、审批积压或 Connector 错误率异常。 +- 审计写入失败、脱敏失败或 Payload 清理失败。 +- MQTT 跨 Topic 访问和重复认证失败。 +- Runtime 证书即将过期、Skill/SBOM 摘要变化或未登记实例上线。 +- 任务长时间无心跳、审批/人工接管积压或补偿失败。 +- 目标系统权限已撤销但 Credential 缓存仍成功兑换。 +- 知识 ACL 同步失败、派生索引过期或提示词注入检测异常上升。 +- 审计哈希链断裂、签名检查点失败或节点时间偏差超限。 + +### 16.3 运维操作 + +管理控制台需要增加受控操作： + +- 撤销 Agent 的模型客户端 Key。 +- 撤销 Session/Task 的所有委托。 +- 吊销 Runtime 证书、隔离实例并查看其 Agent/Skill/SBOM 清单。 +- 暂停、取消、重新排队或人工接管任务。 +- 暂停指定 Tool、Connector、Provider 或 Model。 +- 轮换 Provider Key、Connector 凭据和签名 Key。 +- 撤销 Credential Account/Grant，并触发知识源 ACL 与派生索引重同步。 +- 按 `traceId` 查询完整调用链。 +- 导出脱敏审计事件。 +- 执行保留期清理并查看结果。 + +所有运维操作自身也要进入管理员审计日志。 + +## 17. 风险与待确认事项 + +| 风险/问题 | 影响 | 处理方式 | 阻塞阶段 | +| --- | --- | --- | --- | +| OpenClaw 2026.7.1 Tool 插件接口是否满足可信上下文附加 | 决定能否完全替代通用 exec | 阶段 0 编写最小插件验证 | 阶段 3 | +| OpenClaw 静态 Provider Key 刷新能力有限 | 难以使用短期模型 Token | MVP 使用可撤销限权 Key，评估 Model Bridge | 阶段 2 | +| 当前 CUI 只传用户名、Cookie 和共享 Token | 无法证明员工身份 | 接入 OIDC，兼容期建立服务端会话映射 | 阶段 4 | +| 单 OpenClaw 进程承载多个 Agent，OS 级身份相同 | Unix UID 无法区分 Agent | 使用签名运行上下文；高隔离客户采用每 Agent Runtime | 阶段 3/5 | +| 原始工具 Payload 可能含大量业务数据 | 审计存储风险高 | 默认 metadata/redacted，原文独立加密和短期留存 | 阶段 1 | +| 第二个 Connector 过晚接入 | 通用网关可能继续固化 HZG 假设 | 阶段 4 强制接入 Wyn 或 Phoenix | 阶段 4 | +| 多容器增加部署复杂度 | 客户运维成本上升 | 先单容器多 UID，稳定后提供 Compose 一键部署 | 阶段 6 | +| MCP Server 质量和权限模型不一致 | 工具行为不可预测 | 所有 MCP Server 仍经过 Tool Gateway 注册、策略和契约测试 | 阶段 3/4 | +| WorkBuddy 无法提供可信 Agent/Session 上下文 | 只能识别桌面 Runtime，无法可靠审计到具体 Agent | 优先 Sidecar/Bridge；不能证明时缩小到低风险只读和 Runtime 级权限 | 阶段 0/4 | +| 旧 CRM/SRM 不支持 OBO | 容易退化为共享超级账号 | 员工专属凭据代持；综管任务使用按组织/工具受限服务账号 | 阶段 0/3 | +| 集团与下属单位不互信 | 统一租户模型可能造成横向或向上泄露 | `tenant/organization/data_domain/environment` 分层隔离，密钥、索引和审计权限可按域拆分 | 阶段 4/5 | +| 知识源 ACL 与派生索引不同步 | 已撤权内容仍可能被 RAG 命中 | 版本化 ACL、访问时过滤、撤权事件和缓存/向量失效 SLA | 阶段 5 | +| 文档、网页或 Skill 提示词注入 | 绕过工具策略或诱导数据外发 | 内容低信任标记、Browser Gateway、结构化工具、Skill 签名和运行沙箱 | 阶段 5 | +| 审计库管理员可修改记录 | 无法满足责任追溯和争议举证 | 仅追加、哈希链、签名检查点、WORM/SIEM 导出和职责分离 | 阶段 5/6 | +| Task Orchestrator 被扩展为通用流程平台 | 与活字格/Phoenix 重叠并扩大项目范围 | 只负责 Agent 任务可靠运行，业务流程留在产品或客户系统 | 阶段 4 | +| 本地部署组件过多 | 中小客户资源和维护成本不可接受 | 逻辑拆分、两档部署拓扑、可选模块和明确资源基线 | 阶段 5/6 | +| 评测集泄露或指标被单一化 | 过拟合、跨产品误判或敏感数据扩散 | 产品自有评分器、数据域隔离、盲测集和人工复核 | 阶段 5 | + +不阻塞阶段 1 的事项：企业 IdP 品牌、第二个 Connector 选择、最终数据库、高可用方案和知识库技术选型。这些选择不能延迟 localhost 鉴权、密钥隔离、MQTT ACL 和日志脱敏修复。OBO 不可用也不是采用超级账号的理由，应转为员工专属凭据或缩小试点权限。 + +## 18. 实施任务拆分 + +### Epic A：控制面鉴权加固 + +- A1 删除 localhost 管理员和内部 API 免认证逻辑。 +- A2 将 `/bootstrap` 拆成非敏感启动数据和管理员专用接口。 +- A3 服务 Token 增加哈希、Scope、过期、轮换和撤销。 +- A4 外部 Session 从认证上下文取得 Subject。 +- A5 增加负向鉴权和回归测试。 + +### Epic B：Model Gateway + +- B1 建立 Runtime/Admin API 和健康检查。 +- B2 实现 Provider Secret 加密、版本和轮换。 +- B3 实现 OpenAI 兼容流式代理。 +- B4 实现客户端凭据、模型白名单和配额。 +- B5 将 management LLM 服务改为 Gateway Admin Client。 +- B6 迁移 OpenClaw Provider 配置并删除上游 Key。 +- B7 增加模型用量、审计和压力测试。 + +### Epic C：身份委托与 Tool Bridge + +- C1 定义 Subject、Service Principal、Session 和 Task 模型。 +- C2 实现委托签发、验证、撤销和重放保护。 +- C3 验证并实现 OpenClaw Tool Bridge 插件。 +- C4 实现 CLI v2 降级路径和协议版本协商。 +- C5 将业务调用从通用 exec 切换到可信 Bridge。 + +### Epic D：Tool Gateway + +- D1 Tool Registry 和 Connector Registry。 +- D2 策略匹配、资源范围和风险等级。 +- D3 Approval 状态机和输入哈希绑定。 +- D4 幂等、超时、取消、重试和熔断。 +- D5 MCP/REST/Socket 入口。 +- D6 统一审计和脱敏。 + +### Epic E：HZG Connector + +- E1 提取现有 HZG SDK 调用为 Connector。 +- E2 建立旧命令到稳定 Tool ID 的映射。 +- E3 Cookie 改为 Credential Handle。 +- E4 补齐只读、写入、审批和幂等集成测试。 +- E5 灰度迁移现有 CUI 和 Agent。 + +### Epic F：通信与存储加固 + +- F1 MQTT 每客户端凭据和 Topic ACL。 +- F2 MinIO 仅内部网络访问，按服务拆分凭据。 +- F3 日志字段级脱敏、Payload 加密和清理任务。 +- F4 统一 `traceId` 和审计事件。 +- F5 告警、备份恢复和密钥轮换演练。 + +### Epic G：多产品验证 + +- G1 发布 Connector 契约和测试工具包。 +- G2 完成 Wyn 或 Phoenix Connector。 +- G3 清理 Tool Gateway 中残留的 HZG 特有字段。 +- G4 明确 SpreadJS/GCExcel 文档处理服务边界并实现首批确定性工具。 +- G5 验证产品无需引用共享语言 SDK，只通过协议和契约测试接入。 + +### Epic H：Runtime 身份与企业登录生命周期 + +- H1 建立 Runtime Registry、实例心跳、Agent 绑定和隔离级别模型。 +- H2 实现 mTLS 证书注册、轮换、吊销和发送方绑定令牌。 +- H3 实现 OIDC/SAML Adapter、目录同步、MFA/Step-up 和单点登出。 +- H4 建立平台管理员 RBAC、职责分离和管理操作审计。 +- H5 完成 WorkBuddy Sidecar/Bridge 与 DAEDALUS/OpenClaw 原生 Bridge 对比验证。 + +### Epic I：Task Orchestrator + +- I1 实现任务队列、状态机、租约、心跳和任务预算。 +- I2 实现检查点、取消、有限重试、幂等和补偿。 +- I3 实现等待审批、等待人工、人工接管和恢复。 +- I4 将综管任务的每个业务步骤强制路由到 Tool Gateway。 +- I5 完成 Runtime 崩溃、重复投递和任务恢复测试。 + +### Epic J：凭据、知识与运行隔离 + +- J1 实现 OBO、员工专属 Credential Handle 和受限服务账号策略。 +- J2 定义知识命名空间、来源、ACL、引用和生命周期契约。 +- J3 实现一个文档 Adapter 和一个产品数据 Adapter。 +- J4 实现文档解析/脚本沙箱、Browser Gateway 策略和网络出口限制。 +- J5 实现 Skill 签名、权限清单、SBOM、白名单和审计。 +- J6 实现审计哈希链、签名检查点和 WORM/SIEM 导出。 + +### Epic K：评测与发布门禁 + +- K1 定义版本化评测集、运行结果和发布门禁 Schema。 +- K2 接入 Agent、Prompt、模型、Skill、Tool 和 Connector 版本指纹。 +- K3 支持确定性断言、产品自定义评分器、人工复核和安全负向回放。 +- K4 集成 CI 和目标组织/环境发布审批。 +- K5 建立评测数据脱敏、权限、保留期和防过拟合规则。 + +## 19. 责任边界与首个试点 + +### 19.1 团队责任边界 + +| 团队/角色 | 主要责任 | 不应承担 | +| --- | --- | --- | +| 企业 AI 基础设施团队 | Model/Tool Gateway、Identity、Runtime Registry、Task Orchestrator、Credential Broker、Knowledge 契约、Evaluation、Audit | 不实现各产品内部业务权限规则，不建设统一业务流程平台 | +| DAEDALUS_AGENT 团队 | Control Plane、OpenClaw Runtime、Tool/Model Bridge、管理 UI | 不保存上游和业务系统明文凭据，不把 OpenClaw 内部模型变成公司级协议 | +| 活字格/Wyn/SpreadJS/Phoenix 产品团队 | 对应 Connector、业务权限校验、工具 Schema、评测集/评分器和回归测试 | 不各自复制一套模型网关和审计中心 | +| 企业交付/运维团队 | 客户内网部署、IdP、证书、备份、升级和监控 | 不通过关闭安全策略解决兼容问题 | +| 安全与测试团队 | 威胁建模、策略基线、契约测试、安全回归和渗透测试 | 不以人工评审替代自动化负向测试 | +| 客户 IAM 与业务系统 Owner | IdP、组织/数据域、OBO Client、服务账号和目标系统权限 | 不把统一超级账号交给平台或 Connector | + +平台团队发布 Connector SDK 或测试包时，只提供协议类型、签名验证、测试夹具和本地模拟器。产品团队可以使用自己的语言实现 Connector，避免形成对 Node.js SDK 的强绑定。 + +### 19.2 建议首个企业试点范围 + +首个试点只验证安全闭环和通用边界，不追求覆盖全部产品能力： + +- 1 套客户测试环境，保持单机部署但使用独立进程/UID。 +- 1 个 Model Gateway，接入 1 个 Provider 和不超过 2 个模型。 +- 5 个以内 Agent，其中至少包含 1 个 WorkBuddy 或同类个人 Agent、1 个 DAEDALUS 个人 Agent 和 1 个综管式 Agent。 +- 20 个以内试点员工。 +- 1 个 HZG Connector，首批不超过 5 个只读工具和 1 个可撤销写工具。 +- 1 个 Runtime Registry，个人 Agent 通过 mTLS 或 Sidecar 注册，综管任务通过 Task Orchestrator 派发。 +- 目标系统支持时使用 OBO；否则仅为试点员工保存专属凭据，不创建统一超级账号。 +- 写工具必须经过确认或审批，并支持幂等键。 +- 审计默认保存 metadata 和 redacted preview，关闭原始 Payload 留存。 +- 关闭 Agent 直连 Provider、业务系统和未受控互联网出口。 + +试点成功标准： + +- 连续完成真实业务流程，不需要临时恢复 localhost 免认证、共享 Cookie 或明文模型 Key。 +- 安全回归和跨 Agent 隔离测试全部通过。 +- 业务人员能够通过 `traceId` 解释一次模型或工具调用的主体、授权、审批和结果。 +- SSO 退出、Runtime 吊销、员工停用和任务取消都能在约定时间内切断后续调用。 +- 综管任务在 Runtime 重启后可恢复，已成功的写步骤不会重复执行。 +- HZG Connector 的实现没有进入 Model Gateway 或 Tool Gateway 核心模块。 +- 根据试点反馈可以新增第二个 Connector，而不修改既有网关协议。 + +安全闭环通过后，再增加一个小型价值试点，二选一： + +- SpreadJS/GCExcel：提供工作簿结构读取、公式检查、确定性计算和文件导出，验证同一工具可被 WorkBuddy 与 DAEDALUS 复用。 +- Phoenix：接入需求、Git、Bug、CI/测试元数据，运行一个带人工把关的问题回溯或测试任务，验证 Task Orchestrator 和生命周期血缘。 + +Wyn 不建议作为第一个网关价值试点。会议记录显示裸接数据问数准确率只有 30%-40%，该问题主要来自业务语义、数据加工和权限上下文缺失，单纯增加网关不能解决。应在 Wyn 先能稳定暴露语义层、指标、来源和用户权限后，再接入 Data & Knowledge Gateway。 + +在核心团队约 4 至 6 人、产品 Connector 团队独立配合的前提下，从阶段 0 到完成上述试点通常需要多个迭代。实际周期取决于 OpenClaw Tool 插件验证、客户 IdP 和首批 HZG 写工具的业务权限复杂度，不在本文给出固定日期承诺。 + +## 20. 建议的首批 Pull Request + +为减少并行修改冲突，建议按以下顺序提交： + +1. `security: remove loopback authentication bypass` +2. `security: split secrets from bootstrap response` +3. `security: add scoped internal service clients` +4. `model-gateway: add minimal secret-isolating proxy` +5. `model-gateway: move provider secrets out of openclaw config` +6. `security: redact invocation payloads before persistence` +7. `security: add mqtt per-client credentials and topic acl` +8. `model-gateway: add full runtime and admin api` +9. `tool-gateway: add delegation and tool registry skeleton` +10. `app-invoke: add protocol v2 and hzg connector adapter` +11. `openclaw: add trusted tool bridge or token broker fallback` +12. `runtime-registry: add workload enrollment and mtls identity` +13. `credential-broker: add scoped one-time credential handles` +14. `task-orchestrator: add leases checkpoints and cancellation` +15. `knowledge-gateway: add namespace acl and source contracts` +16. `runtime-security: require signed skills and sandbox document parsing` +17. `audit: add hash-chain checkpoints and admin separation` +18. `evaluation: add versioned results and release-gate schema` + +前七个 PR 可以在完整 Model Gateway 和 Tool Gateway 完成前独立关闭主要 P0/P1 风险。第八个 PR 起必须保持旧功能可回归，但不允许用重新开启 localhost 免认证、Agent 直连 Provider 或明文密钥作为兼容手段。 + +## 21. 相关文档 + +- `docker/docs/spec.md` +- `docker/docs/3rd-party-interactive-solution.md` +- `docker/docs/environment-variables.md` +- `packages/daedalus-agent-management-web/docs/spec.md` +- `packages/daedalus-agent-apps-invoke-cli/docs/design.md`