From b77b3a3a9a55e14bacd09b1ada1d8ede8987a72c Mon Sep 17 00:00:00 2001 From: zh Date: Wed, 23 Sep 2026 11:16:12 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E8=A1=A5=E5=85=85=E6=9C=AF=E8=AF=AD?= =?UTF-8?q?=E8=A1=A8=E4=B8=8E=E8=BE=B9=E7=95=8C=E4=B8=80=E9=A1=B5=E7=BA=B8?= =?UTF-8?q?=EF=BC=88A0.6=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/glossary.md | 63 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 63 insertions(+) create mode 100644 docs/glossary.md diff --git a/docs/glossary.md b/docs/glossary.md new file mode 100644 index 0000000..a92af10 --- /dev/null +++ b/docs/glossary.md @@ -0,0 +1,63 @@ +# 术语表与边界 + +> 用于统一口径。写代码、写文档、评审时以本表为准；发现同一件事有两种叫法，先改本表再改别处。 + +## 术语 + +| 术语 | 含义 | 容易混淆的地方 | +| --- | --- | --- | +| **平台** | 承载智能体与多系统接入的系统本体：客户端、平台服务、Core、Provider 接入 | 不是业务系统；APS 不在平台内 | +| **客户端** | 桌面端与浏览器界面，含工作区与本地能力 | 不直连 Provider，不持有业务凭据 | +| **平台服务** | 服务端进程：入口、应用服务、引擎适配、Core、Provider 接入 | 引擎在开发或部署期选定，服务端本身引擎中立 | +| **应用服务** | 会话与任务编排、能力查询、确认流转、事件推送 | 不做业务规则，不替引擎判断 | +| **Agent 引擎** | 驱动一轮智能体循环的实现，Pi 或 Codex 二选一 | 不等于平台，也不等于 Core | +| **Pi** | 进程内嵌入的 Node 库，工具由应用注册 | 核心不带工具，不带权限模型 | +| **Codex** | 以子进程驱动的引擎实现 | 自带 shell 与文件类工具，接入时必须关闭 | +| **Core** | 平台控制面：身份、策略、确认、执行、审计五个模块 | 不是第二个智能体；不放业务规则与业务数据 | +| **身份** | 平台用户到各业务系统账号的映射 | 不复制业务系统的角色与权限 | +| **策略** | 用代码判断允许、拒绝或需确认 | 默认拒绝；每次执行前都查，不能只在展示工具列表时过滤 | +| **确认** | 待确认动作落库，界面确认或拒绝 | 防的是 Agent 误解意图，不是防越权；确认者是会话发起人 | +| **确认卡** | 界面上呈现影响范围、参数摘要与版本的卡片 | 弹窗只是界面，真正的状态在数据库 | +| **执行** | 建执行记录，管幂等、并发与超时，调用 Provider | 超时不等于失败 | +| **执行授权** | 确认后绑定具体动作、参数与版本的一次性许可 | 不等于业务系统凭据 | +| **幂等键** | 保证同一逻辑执行只生效一次的标识 | 安全重试沿用原键 | +| **审计** | 只追加、可追溯的记录 | 与运行日志不同，与确认记录也不同 | +| **证据链** | 把结论与来源（系统、时间、版本）关联起来 | 不是截图，是可核对的引用 | +| **Provider** | 能力适配器：把统一调用翻译成某个系统的 API，再翻译回统一回执 | 不是业务系统，不做业务决策 | +| **Capability** | Provider 暴露的一个可调用单元：id、effect、mode、输入输出 Schema | effect 分 read / draft / write | +| **能力目录** | 保存能力、版本与实例配置，按身份提供给引擎 | 不等于工具列表；工具是按身份过滤后的投影 | +| **Provider 套件** | 一个系统的适配器包：manifest、adapter、可选视图、契约测试 | 指"包"，不指系统本身 | +| **业务系统** | 平台外部的独立系统：APS、ERP、EMS | 是业务事实源，权限与规则都在它这里 | +| **会话** | 一次对话的载体，含消息与工具调用 | 个人会话只读，写操作必须在项目会话内 | +| **工作区** | 右侧多标签面板：表格、甘特、图表、文件、网页 | 数据都经 Core 获取，不直连业务系统 | +| **平台事件** | 引擎事件转换后的统一事件类型：文本、工具调用、工具结果、需确认、轮次结束、错误 | 界面只认它，不认引擎原生事件 | +| **上下文检查点** | 平台保存的"发给模型的上下文"，是权威 | 引擎原生状态只作同引擎恢复 | +| **Goal / Plan / Task** | 平台定义的多步协作对象 | 引擎不提供，与所选引擎无关 | +| **Sub-agent** | 执行某个 Task 的一次受控运行 | 权限只减不增 | +| **UI 块** | 模型输出的结构化界面块，由前端按类型渲染 | provider-view 是其中一种 | + +## 边界一页纸 + +调用方向： + +``` +用户 → 客户端 → 应用服务 → Agent 引擎（Pi 或 Codex）→ Core → Provider → 业务系统 +``` + +| 角色 | 只做 | 不做 | +| --- | --- | --- | +| 客户端 | 界面、工作区、本地能力 | 业务判断、权限判断、持有业务凭据 | +| 应用服务 | 编排、能力查询、确认流转、事件推送 | 业务规则、替引擎判断 | +| Agent 引擎 | 理解意图、挑工具、解释结果 | 碰凭据、判断权限、直连业务库 | +| Core | 决定能不能做、以谁的身份、要不要确认，并留痕 | 业务规则、业务数据 | +| Provider | 翻译调用与回执 | 业务决策、持有模型上下文 | +| 业务系统 | 原生权限、业务规则、状态与数据的最终判定 | 因为平台放行就执行 | + +四条不可破的规则： + +1. **引擎只能提议，Core 决定，业务系统最终说了算。** +2. **权限归业务系统，映射与确认归平台。** 平台不做转派、委托、多人计数与角色策略。 +3. **工具只有一个出口** `Core.invoke`；不允许任何旁路。 +4. **数据归属固定**：会话与检查点归平台，执行与审计归 Core，业务数据归业务系统，引擎原生状态只作同引擎恢复。 + +口径来源：设计文档《架构设计》第 1、4 节与《实施设计》第 1.5 节；决策 D9。