F2 · 用户如何配置和修改 Agent 的能力？ - Agent Configuration
所属知识库：Agent 全栈技术地图
所属领域：04 · Agent Platform
所属章节：03 · Agent Platform 应该提供哪些产品功能？ - Product Architecture
文档类型：专题研究 / 产品架构 / 交互与工程参考设计
版本：v1.3
更新日期：2026 年 11 月 1 日
核心问题：Agent Platform 如何将角色、指令、模型、工具、知识、记忆、执行参数与权限等能力配置转化为用户可理解、可编辑、可验证、可追溯的产品体验，并保证修改不会意外影响已发布版本与正在执行的任务？
专题导读
本篇属 Product Architecture。F1 解决“创建 Agent 身份与初始草稿”，F2 解决“用户如何定义和修改该 Agent 能做什么、如何做、在什么条件下做”。配置既是产品交互，也是技术契约：前端应帮助用户理解能力及其后果，后端应将配置映射为结构化 Draft/Manifest，并进行授权和有效性校验。F2 不代替 F3 的执行测试、F4 的正式发布、F9 的版本维护，也不取代 P7 的资源接入与 P12 的治理策略。
本文区分可直接依据通用软件工程机制说明的事实与针对 Studio 的参考设计。示例字段、界面结构、阈值和测试均为建议方案，未经实际用户研究或工程验证。
研究结论
- Agent Configuration 应以可解释的能力模块组织，而非直接向所有用户暴露大型 JSON Manifest。
- 必须区分意图声明、资源绑定、实际授权和运行时生效：在界面勾选工具不等于取得工具权限。
- 采用Draft 可编辑、Published Version 不可变、Run 固定版本的三层语义，防止编辑影响生产运行。
- 通过表单/可视化编辑与高级 Manifest 编辑共享同一规范化配置模型，避免双轨数据漂移。
- 以字段级校验、跨字段语义校验、策略校验、预览测试构成逐层反馈；保存成功不等于 Agent 可执行。
- 将敏感凭证与配置分离，只保存受控 Credential Reference，不允许把明文密钥写进 Prompt、Manifest 或导出包。
- 将修改的影响分级：展示属性变更、行为变更、资源/权限变更、兼容性破坏变更，提供差异与风险提示。
- 对 Studio 优先交付六类配置：角色与目标、指令、模型、工具、知识、运行约束；复杂记忆和高级策略逐步开放。
01 · 概念、边界与产品目标
1.1 配置的定义
Agent Configuration 指用户对一个已有 Agent 的能力声明、行为规则、资源依赖和运行约束进行创建、读取、编辑、比较、保存与校验的产品功能。配置应可被持久化为带修订号的 Draft，并在通过后续流程时生成可发布版本。用户可见配置与底层执行器配置不是一一对应的字段拷贝：平台可能将友好的“允许检索公开网页”映射成多个工具绑定、权限范围和执行策略。
1.2 与相邻专题的职责边界
| 领域 | 本篇负责 | 不负责或仅引用 |
|---|---|---|
| F1 Agent Creation | 接收初始 Draft 并继续编辑 | Agent 身份创建、模板入口 |
| F3 Agent Development & Testing | 提供校验入口和测试配置快照 | 测试执行、评估、调试结果判定 |
| F4 Publishing & Sharing | 展示发布前准备状态 | 发布审批与正式发布动作 |
| F9 Agent Management | 展示草稿与发布版本差异 | 发布版本回滚、归档与退役 |
| P3 Agent Registry | 提交草稿修订、读取版本引用 | 注册仓库底层实现 |
| P4 Development Services | 调用校验、解析与预览服务 | 构建管线实现 |
| P7 Resource & Integration | 选择可用资源并申请绑定 | 外部连接创建、凭证保管、工具网关 |
| P12 Platform Governance | 展示策略限制与审批要求 | 最终授权裁决与策略执行 |
1.3 产品成功标准
用户应能在不理解执行器内部实现的前提下回答：这个 Agent 的目标是什么？它使用哪个模型？能访问哪些数据与工具？它的边界在哪里？修改了哪些能力？是否已保存、是否通过校验、是否已发布、实际运行使用哪个版本？
02 · 用户画像、任务与使用场景
| 用户角色 | 主要任务 | 需要的界面能力 | 典型误区 |
|---|---|---|---|
| 业务构建者 | 定义目标、选择工具、控制输出 | 向导、自然语言说明、风险提示 | 以为勾选工具即获得权限 |
| Agent 开发者 | 精细控制模型参数和依赖 | 高级字段、Manifest、Diff、Schema | 误把运行时环境参数当作可移植配置 |
| 项目负责人 | 确认职责边界和成本 | 变更摘要、权限审查、预算概览 | 认为草稿修改已经作用于生产 |
| 安全管理员 | 管理高风险能力 | 权限范围、策略阻断原因、审批 | 以为隐藏前端选项即可阻止调用 |
| 运维人员 | 诊断配置相关故障 | 版本快照、依赖状态、错误关联 | 将模型输出差异全部归因于配置 |
典型场景：首次配置新 Agent；基于运行反馈修改 Prompt；将模型从一个供应商切换到另一个供应商；新增检索工具；更换知识库；限制写操作；批量升级多个 Agent 的共享配置；恢复误编辑草稿。不同场景的风险和验证路径不同，不能一律采用“保存即生效”。
03 · 配置对象模型与生效语义
flowchart LR
A[Agent Definition] --> D[Editable Draft + Revision]
D --> M[Normalized Manifest]
M --> V[Validated Build]
V --> R[Immutable Agent Version]
R --> DEP[Deployment Revision]
DEP --> RUN[Run Snapshot]
M --> B[Resource Bindings]
B --> C[Connection / Credential References]
POL[Governance Policy] -.约束.-> B
POL -.约束.-> RUN建议区分 agent_id（稳定逻辑身份）、draft_id（可编辑对象）、draft_revision（乐观并发修订）、agent_version_id（不可变发布快照）、deployment_revision_id（环境绑定快照）和 run_id（一次执行）。运行时必须记录解析后的版本与关键依赖引用。别名如 production、latest 可用于选择版本，但不可作为历史 Run 的唯一溯源依据。
3.1 配置的四种状态
- 未保存变更（dirty）：仅存在于当前编辑会话；离开页面需提示。
- 已保存草稿（saved draft）：服务端持久化，但不意味着通过校验。
- 校验通过的草稿（validated draft）：在指定配置修订和策略上下文中通过静态校验；后续编辑会使结果过期。
- 已发布版本（published version）：不可变快照；其更新必须生成新版本，不能原地修改。
3.2 生效矩阵
| 修改对象 | 保存草稿后 | 发布后 | 已在运行的 Run |
|---|---|---|---|
| 名称、描述 | 草稿可见 | 版本元数据更新 | 原则上不改变运行逻辑 |
| 指令、模型、工具 | 仅改变草稿 | 新版本可供新任务选择 | 保留已固定的版本和执行上下文 |
| 环境级连接或密钥 | 可能仅更新绑定请求 | 部署/授权检查后可使用 | 受运行时凭证轮换与撤销影响 |
| 治理策略 | 受当前策略校验 | 发布仍须检查 | 高风险调用需按实时策略重新裁决 |
注意：配置版本固定不能保证 LLM 输出完全可重现，外部模型、检索结果、工具服务与随机性仍可能变化。
04 · 配置能力分类与信息架构
推荐以用户目标组织为六个一级区块，并以高级设置承载低频参数：
| 区块 | 用户核心问题 | 主要字段 | 风险级别示例 |
|---|---|---|---|
| 基本信息 | 这是谁、负责什么？ | 名称、描述、标签、所属项目 | 低 |
| 角色与指令 | 应如何理解和完成任务？ | 目标、系统指令、输出规范、约束 | 中 |
| 模型与推理 | 用什么模型、如何权衡质量成本？ | 模型引用、参数、超时、上下文策略 | 中 |
| 工具与操作 | 可以做哪些外部动作？ | 工具绑定、能力范围、调用确认 | 高，视工具而定 |
| 知识与上下文 | 能读取什么信息？ | 知识集合、检索范围、引用要求 | 中至高 |
| 运行与安全 | 什么时候停止、谁能批准？ | 预算、并发、重试、审批策略引用 | 高 |
进阶区块：记忆与状态、结构化输出、协作协议、模型回退、实验参数、环境覆盖与自定义 Manifest。建议采用渐进披露：普通用户先见任务目标和能力概览，专业用户再展开字段级细节。
4.1 页面布局建议
Agent / 选题研究员 [草稿 r18] [已保存] [校验] [预览] [发布…]
├─ 左侧：基本信息 / 指令 / 模型 / 工具 / 知识 / 运行与安全 / 高级
├─ 中间：当前配置表单 + 字段说明 + 默认值来源
└─ 右侧：能力摘要 / 风险提示 / 修改 Diff / 校验问题
底部：保存状态、最近修改人、修订时间、当前发布版本表单每个资源选择器应显示：资源名称、类型、版本/别名、归属、连接状态、可用范围、必要权限、成本或限制。对尚未授权的资源使用“请求连接/请求授权”，而非误导性的“已启用”。
05 · 角色、目标与指令配置
5.1 结构化输入优于单个万能 Prompt
推荐分别记录：任务目标（objective）、职责边界（scope）、行为指令（instructions）、输出契约（output_contract）、成功标准（acceptance_criteria）和禁止行为（prohibited_actions）。这有助于 UI 解释、差异审查和测试生成；并不意味着每个模型供应商都原生支持相同字段。运行时需由适配层将这些信息组合为适合目标模型的请求。
5.2 指令优先级与不可信输入
平台自身的安全约束、应用开发者指令、用户任务输入、检索文档与工具返回值可能处于不同的信任边界。配置界面必须说明：外部文档不能自动覆盖平台治理规则；检索到的“请忽略先前指令”应视为待处理数据而非可信命令。不要承诺仅靠 Prompt 就能实现强隔离；外部操作的权限应由执行层验证。
5.3 输出规范
可配置自然语言格式、Markdown、结构化 JSON Schema、必填字段、引用要求、语言和篇幅约束。对于结构化输出，需分别说明模型端约束能力和服务端 Schema 校验；不支持原生结构化输出的模型可使用生成后验证与修复，但不能保证每次成功。字段变更可能破坏下游工作流，应提示兼容性风险。
06 · 模型与推理参数配置
6.1 模型选择器
模型列表应来自 P7 的受控资源目录，展示提供方、能力标签、可用区域、输入输出模态、上下文窗口、价格信息的时间戳、工作空间授权与可用状态。不能把营销性能力标签当作性能保证；模型支持情况应以具体版本和服务端能力发现结果为准。
6.2 参数分层
| 类别 | 示例 | 交互规则 |
|---|---|---|
| 基础 | 模型、最大输出长度、超时 | 默认展示，标注支持范围 |
| 高级 | temperature、top_p、seed | 按模型能力动态展示；不支持则禁用 |
| 可靠性 | 失败重试、回退模型 | 解释成本、行为漂移与副作用 |
| 成本 | 单次预算、Token 预算 | 明确估算与实际结算差异 |
| 安全 | 内容处理策略引用、数据保留要求 | 受平台治理限制，不可由用户随意关闭 |
模型参数不存在跨供应商完全一致的语义。UI 应区分“用户选择值”“平台默认值”“运行时实际值”；版本快照记录最终解析值和适配器版本。模型别名指向的底层权重可能改变，需尽可能使用固定模型版本并记录提供方响应标识。
07 · 工具与外部资源配置
7.1 资源绑定的四层含义
- 声明能力：Agent 需要搜索、读文件或发送消息。
- 选择资源：绑定某个已注册 Tool/Connector/Model。
- 取得授权：用户、工作空间或管理员批准必要作用域。
- 运行时检查：实际调用仍须验证主体、租户、范围、策略、预算与审批。
四者不能合并为一个布尔开关。对于读写混合的工具，应展示具体动作权限，例如 search:read 与 email:send，并在写入、发送、删除、付款等高风险操作前配置人工确认。
7.2 工具配置表单
字段建议包括：工具 ID 与版本、绑定作用域、参数映射、允许调用的动作、调用超时、失败策略、重试幂等要求、审计级别、是否需要人工确认。凭证仅保存 credential_ref；界面不得回显明文。撤销连接后，配置可保留不可用引用并提示修复，而不应偷偷切换到其他人的连接。
7.3 Tool Schema 与参数安全
工具 Schema 描述输入结构，不等于业务授权。对路径、域名、SQL、文件名等参数应执行服务端范围检查；防范 SSRF、路径穿越、命令注入、超额读取与工具返回中的 Prompt Injection。对外部副作用操作，应尽量使用幂等键、审计记录与人工审批，不能依赖简单重试保证 exactly-once。
08 · 知识、文件、记忆与上下文配置
8.1 知识源绑定
知识配置应明确：数据源身份、集合版本、读取范围、检索策略、过滤条件、引用方式、更新频率与数据保留规则。UI 需提示“可搜索”与“可访问”不同；检索过滤应在服务端施加租户和 ACL 约束。共享知识库的索引、缓存和向量查询也必须隔离。
8.2 记忆的产品语义
应区分会话短期状态、跨 Run 长期记忆、项目共享记忆与用户个人偏好。用户必须知道哪些信息会被持久化、谁可读取、如何更正或删除。记忆写入是有副作用的数据操作，不能仅因 Agent 配置了“启用记忆”就默认拥有跨项目写权限。
8.3 上下文策略
配置可包括检索条数上限、摘要策略、上下文裁剪、来源优先级与引用门槛。实际上下文长度与计费由模型适配层决定。对关键证据型研究任务，应优先保留可追溯的文献引用与输入资产版本，而非仅保留生成后的总结。
09 · 运行约束、安全与权限配置
运行约束建议包含：最长运行时长、最大步骤数、并发数、单 Run 成本上限、失败重试上限、外部调用白名单、人工审批要求、日志保留等级。UI 应展示哪些字段是 Agent 自身建议值、哪些来自 Workspace/Platform 强制策略。强制策略只能收紧，不能通过 Agent 层覆盖放宽。
高风险工具应使用“操作意图 - 参数预览 - 审批 - 执行时参数再校验”的链路。审批必须绑定操作摘要和有效期；审批后参数发生变化需要重新授权。对于正在运行的任务，紧急权限撤销应能在下次敏感调用前生效，而不是等待新版本发布。
10 · 配置继承、覆盖与默认值
配置来源可能包括平台默认值、组织策略、Workspace 默认值、Agent Draft、Deployment 环境覆盖、Run 输入。应区分两种机制：可覆盖的配置默认值与不可覆盖的治理上限。推荐显式展示“当前值来自哪里”，并允许用户恢复继承而不是复制默认值。
| 配置项 | 允许 Agent 覆盖 | 运行时固定方式 |
|---|---|---|
| 描述、目标、输出格式 | 通常允许 | Agent Version 快照 |
| 模型选择 | 在授权目录内允许 | Version + Deployment 解析记录 |
| 工具授权 | 仅可申请/收紧 | Runtime 权限检查 |
| 租户隔离策略 | 不允许放宽 | 平台实时策略 |
| 预算上限 | 仅可收紧或申请提高 | Run 预算预留与结算 |
| 机密凭证 | 不可写入配置正文 | Credential Reference + Runtime Secret Resolution |
建议采用确定性的合并顺序并生成 effective_config 供校验与预览。需要注意“最后写入者获胜”不适用于安全策略；策略冲突应采用明确的优先级或拒绝策略。
11 · 编辑、自动保存、并发与版本差异
11.1 编辑事务
前端可使用局部自动保存，但服务端必须对完整 Draft 修订进行原子更新，返回新的 revision 或 ETag。更新请求携带 If-Match；冲突返回 409/412，展示差异供用户合并。避免无提示覆盖他人编辑。
11.2 保存与校验分离
保存草稿可以允许暂时不完整的字段，便于用户分步工作；但不应允许越权资源绑定或明文敏感数据持久化。校验结果应绑定 Draft Revision、资源目录快照与策略版本。修改任一相关字段后，将旧校验结果标记为过期。
11.3 Diff 与影响评估
| 变更类型 | 示例 | 推荐提示 |
|---|---|---|
| 展示变更 | 描述、标签 | 低风险，可直接保存 |
| 行为变更 | 指令、输出格式 | 建议回归测试 |
| 依赖变更 | 模型、知识库、工具版本 | 检查兼容性、成本、授权 |
| 权限变更 | 增加邮件发送、数据库写入 | 高风险，需审批与安全测试 |
| 破坏性变更 | 删除下游依赖的输出字段 | 阻止直接发布或要求迁移方案 |
差异展示需隐藏密钥，并明确比较基线是“上一草稿修订”还是“当前生产版本”。
12 · 配置校验、错误反馈与预览交接
校验应分层执行：①字段级 Schema；②跨字段约束（如输出模式与模型能力匹配）；③依赖可解析性；④资源授权与策略；⑤兼容性检查；⑥可选预览运行。静态校验无法证明 Agent 在真实任务中表现可靠，质量验证属于 F3。
| 级别 | 示例 | 产品处理 |
|---|---|---|
| Error | 工具版本不存在、必填字段缺失 | 定位字段、阻止构建/发布 |
| Blocked | 资源未授权、违反强制策略 | 显示申请权限或替代方案 |
| Warning | 模型价格未知、未覆盖回归测试 | 允许保存，发布门禁按策略判定 |
| Info | 存在更高版本、可优化参数 | 非阻断提示 |
错误反馈应包含稳定错误码、受影响字段路径、原因、修复建议与请求追踪 ID。避免仅提示“配置无效”。“测试 Agent”应显式标记所用 Draft Revision、资源快照、测试环境与是否会产生外部副作用。
13 · 参考 Manifest、Schema 与配置接口
13.1 Agent Draft 示例（参考契约，非行业统一标准）
schema_version: "studio.agent/v1"
agent_id: "agt_topic_researcher"
draft_revision: 18
metadata:
name: "选题研究员"
description: "为研究报告生成可核验的候选选题"
workspace_id: "ws_research"
role:
objective: "提出有证据支撑的研究选题"
instructions_ref: "asset://prompts/topic-researcher@sha256:example"
output_schema_ref: "asset://schemas/topic-candidates/v2"
model:
resource_id: "model_general_reasoning"
version_policy: "pinned"
model_revision: "provider-model-revision-example"
parameters:
max_output_tokens: 2400
resources:
tools:
- resource_id: "tool_public_search"
version: "2.1.0"
binding_id: "bind_public_search"
allowed_actions: ["search:read"]
knowledge:
- collection_id: "col_research_methods"
snapshot_ref: "snapshot_2026_10"
execution:
max_duration_seconds: 300
max_tool_calls: 12
max_cost_usd: 2.0
requires_approval_for: ["external_write"]
security:
policy_ref: "policy_workspace_research"
credential_refs: []instructions_ref 与 snapshot_ref 是示意标识，必须由实际系统的 Asset/Registry 服务定义解析规则；示例中的 sha256:example 不是有效摘要。模型版本与资源版本也需由运行环境验证是否真实可用。
13.2 参考 API
GET /v1/agents/{agent_id}/draft
PATCH /v1/agents/{agent_id}/draft
If-Match: "18"
Content-Type: application/merge-patch+json
{"model":{"resource_id":"model_general_reasoning"}}{
"agent_id": "agt_topic_researcher",
"draft_revision": 19,
"saved": true,
"validation_state": "stale",
"updated_at": "2026-10-31T12:00:00Z"
}POST /v1/agents/{agent_id}/draft:validate
Content-Type: application/json
{"draft_revision":19,"mode":"static"}{
"draft_revision": 19,
"status": "blocked",
"issues": [
{"code":"RESOURCE_NOT_AUTHORIZED","path":"/resources/tools/0","severity":"blocked","message":"工作空间尚未获准使用该工具"}
],
"policy_version": "policy-r7"
}API 风格、冒号动作路径与 JSON Merge Patch 是参考选择。生产实现应在 OpenAPI 中精确定义字段可空语义、数组替换规则、ETag 格式、错误码、分页和身份授权。Merge Patch 中 null 的删除语义尤其需要谨慎处理。
13.3 参考数据模型
CREATE TABLE agent_drafts (
tenant_id UUID NOT NULL,
agent_id UUID NOT NULL,
revision BIGINT NOT NULL DEFAULT 1,
manifest JSONB NOT NULL,
updated_by UUID NOT NULL,
updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
PRIMARY KEY (tenant_id, agent_id),
CHECK (revision > 0)
);
CREATE TABLE agent_draft_validation (
tenant_id UUID NOT NULL,
agent_id UUID NOT NULL,
draft_revision BIGINT NOT NULL,
policy_version TEXT NOT NULL,
validation_status TEXT NOT NULL,
issues JSONB NOT NULL DEFAULT '[]'::jsonb,
created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
PRIMARY KEY (tenant_id, agent_id, draft_revision, policy_version)
);
-- 并发更新应使用事务中的条件更新：
-- UPDATE agent_drafts SET manifest = $1, revision = revision + 1
-- WHERE tenant_id = $2 AND agent_id = $3 AND revision = $4
-- RETURNING revision;示例仅说明草稿与校验结果关系；生产库仍需定义租户外键、RLS、审计、访问路径索引、数据保留与安全约束。JSONB 便于演进，但不替代 Schema 验证。
14 · Studio 贯穿案例：配置选题 Agent
14.1 场景与目标
用户在 F1 创建“选题研究员”后，希望它根据研究范围、已有知识库和公开资料提出候选主题，输出“标题、研究问题、证据来源、价值判断、风险与待核验点”，交由审核 Agent 判断是否进入调研阶段。F2 负责配置该 Agent 的能力边界，而非代替审核 Agent 执行质量审查。
14.2 端到端用户旅程
sequenceDiagram
actor U as 构建者
participant UI as Agent 配置工作台
participant DEV as Development Services
participant REG as Registry/Draft Store
participant RES as Resource Service
participant GOV as Governance
U->>UI: 编辑目标与输出结构
UI->>REG: 保存 Draft r18（If-Match）
REG-->>UI: Draft r19
U->>UI: 选择检索工具与知识集合
UI->>RES: 查询资源可用性与绑定范围
RES-->>UI: 检索可用，写操作需审批
UI->>REG: 保存 Draft r20
U->>UI: 点击校验
UI->>DEV: Validate(Draft r20)
DEV->>GOV: 检查策略与资源授权
GOV-->>DEV: 允许/阻断及原因
DEV-->>UI: 校验结果与修复建议
U->>UI: 进入 F3 预览测试14.3 配置步骤与产品反馈
| 步骤 | 用户动作 | 界面反馈 | 服务端约束 |
|---|---|---|---|
| 1 | 填写研究目标 | 提示目标应可验证 | 保存 Draft、保留修订 |
| 2 | 编写指令 | 展示变量与预览 | 防止模板注入破坏结构 |
| 3 | 选择模型 | 显示可用性与成本说明 | 校验 Workspace 资源授权 |
| 4 | 绑定公开检索 | 显示只读权限范围 | Runtime Gateway 强制只读 |
| 5 | 绑定方法知识库 | 显示快照与访问范围 | 数据源 ACL 与检索过滤 |
| 6 | 定义输出 JSON | 提示下游审核 Agent 依赖字段 | Schema 校验与兼容性检查 |
| 7 | 设置成本和步骤上限 | 显示预计上限及不可控因素 | 预算预留与调用计量 |
| 8 | 保存并校验 | 显示修订号、错误与警告 | 不自动发布或启动生产 |
14.4 与审核 Agent 的接口兼容
选题 Agent 输出建议固定 candidate_id、title、research_question、evidence_refs、uncertainties、proposed_scope。若 F2 删除 evidence_refs，平台应识别审核 Agent 的输入契约可能被破坏，并提示需要重新运行工作流集成测试。不能仅依据字段名相同就认定语义兼容；审核 Agent 的测试数据和版本锁同样需要更新。
14.5 MVP 范围
Studio 首版只需：单 Agent 配置页、角色/指令编辑、模型选择、只读工具绑定、知识源选择、基本运行上限、自动保存与修订冲突处理、静态校验、与 F3 预览的入口。暂不优先建设复杂可视化编排、跨组织配置继承和大规模批量修改；它们可在有实际使用需求后迭代。
15 · 异常场景、可观测性与运营指标
15.1 典型异常处理
| 异常 | 可见表现 | 恢复方式 | 必要审计 |
|---|---|---|---|
| 网络中断 | 保存中或保存失败 | 本地临时缓冲，重试幂等保存 | 保存失败事件 |
| 并发冲突 | 服务器版本更新 | 对比差异、手动合并 | 冲突双方与修订号 |
| 资源被撤销 | 工具不可用 | 提示重新授权或替换 | 资源撤销与受影响 Agent |
| 模型下线 | 模型选择失效 | 显示替代候选，要求确认 | 依赖变化与修订 |
| 权限不足 | 绑定或校验被阻断 | 显示申请授权入口 | 策略版本与拒绝原因 |
| Schema 破坏 | 下游节点不兼容 | 提供 Diff 与回归测试 | 兼容性检查结果 |
| 密钥误粘贴 | 文本字段疑似包含凭证 | 阻止保存、提示轮换 | 安全事件（不得记录密钥正文） |
| 草稿校验过期 | 旧结果仍显示 | 标记 stale 并重新校验 | 校验输入版本 |
| 预览产生写操作 | 用户误认为无副作用 | 沙箱隔离、显式审批 | 外部操作意图与审批 |
| 配置与生产不一致 | 草稿已改但线上未变 | 展示“生产版本”与“草稿”并排 | 版本映射 |
15.2 产品指标
建议观察：配置完成率、首次保存成功率、配置至首次有效预览耗时、字段级错误率、校验阻断原因分布、资源授权请求完成率、草稿冲突率、误发布/误操作事件、生产版本与草稿混淆率。指标需按用户角色与 Agent 复杂度分层，避免仅以“点击次数少”衡量质量；安全和可解释性可能合理增加步骤。
16 · 分阶段开发路线与验收标准
| 阶段 | 建设重点 | 完成判据 |
|---|---|---|
| Phase 1 · 基础编辑 | 表单、草稿保存、模型与指令配置 | 刷新可恢复；不会影响发布版本 |
| Phase 2 · 能力绑定 | 工具、知识源、授权状态 | 资源不可用时阻止误发布 |
| Phase 3 · 校验与预览 | Schema/语义/策略校验、F3 交接 | 错误可定位、结果绑定修订 |
| Phase 4 · 协作治理 | Diff、审批、并发合并、审计 | 高风险变更可追踪、可审批 |
| Phase 5 · 高级开发体验 | Manifest 编辑、批量配置、配置继承 | UI 与代码视图语义一致 |
16.1 功能验收清单
- 用户能明确区分草稿、校验通过、已发布和正在运行的版本。
- 修改指令、模型或工具后，不会静默改变既有发布版本。
- 配置页面能解释每项工具和知识源的实际访问范围。
- 未授权资源无法仅通过修改前端状态获得运行权限。
- 每次保存返回可追踪的草稿修订，冲突不会覆盖他人修改。
- 静态校验结果绑定修订和策略版本，修改后旧结果失效。
- 任何敏感凭证不得进入 Manifest、导出文件、普通日志或错误消息。
- 能查看与生产版本的配置差异，风险变化有明确提示。
- F3 预览能够获取同一 Draft 的固定修订，不因后续编辑漂移。
- 支持无障碍键盘导航、错误定位、状态文本与操作反馈。
17 · 参考测试矩阵（待执行）
以下均为设计中的测试用例，不是已执行结果。
| ID | 测试主题 | 操作与预期 |
|---|---|---|
| T01 | 创建后进入配置 | F1 创建后打开正确 Agent Draft |
| T02 | 指令编辑 | 保存并刷新后内容一致 |
| T03 | 未保存提示 | 离开页面前明确提示 dirty 状态 |
| T04 | 自动保存重试 | 网络恢复后不重复生成修订 |
| T05 | 乐观并发 | 旧 ETag 更新返回冲突而非覆盖 |
| T06 | 模型能力 | 不支持的参数被阻止或明确降级 |
| T07 | 模型下线 | 不可用模型有明确替代流程 |
| T08 | 工具权限 | 未授权工具不能通过前端绕过 |
| T09 | 工具撤销 | 已撤销绑定在运行时拒绝调用 |
| T10 | 只读工具 | 写操作无法借只读绑定执行 |
| T11 | 知识隔离 | 跨租户知识引用不可被解析 |
| T12 | 向量检索 ACL | 检索结果不会越权泄露 |
| T13 | 密钥保护 | 凭证不会出现在响应或导出包 |
| T14 | Prompt Injection | 外部内容不能绕过服务端授权 |
| T15 | JSON Schema | 必填字段缺失时阻断发布校验 |
| T16 | 下游兼容 | 删除被依赖字段显示破坏提示 |
| T17 | 校验失效 | 编辑后旧校验结果标记 stale |
| T18 | 策略更新 | 策略版本变化触发重新校验 |
| T19 | 成本限制 | 超预算请求受运行时预算机制阻断 |
| T20 | 人工审批 | 参数变化后旧审批不能复用 |
| T21 | 生产隔离 | 编辑草稿不改变已发布版本 |
| T22 | Run 固定 | 执行中修改草稿不影响该 Run 的配置快照 |
| T23 | Diff 隐私 | 差异界面不显示敏感凭证 |
| T24 | 导入导出 | Manifest 往返保持语义一致 |
| T25 | 参数继承 | 默认值来源清晰且不可放宽强制策略 |
| T26 | 错误可解释 | 错误码、字段路径、修复建议可用 |
| T27 | 审计链 | 修改人、修订、时间与事件可追踪 |
| T28 | 可访问性 | 键盘与屏幕阅读器可完成关键配置 |
| T29 | 多人协作 | 并发修改可检测并解决冲突 |
| T30 | 测试交接 | F3 使用固定草稿修订进行预览 |
| T31 | 失败恢复 | 页面崩溃后能恢复最后成功保存状态 |
| T32 | 资源漂移 | 外部连接状态变化后配置提示失效 |
附录 A：参考文献与原始资料
以下优先列出官方规范与文档。它们用于支持 API、配置验证、权限、安全及开发体验中的具体工程机制；并不存在一份统一规定所有 Agent Platform 配置字段的行业标准。文中的 Agent Manifest、产品页面和阶段规划是基于这些原则提出的参考设计。
- JSON Schema. JSON Schema Specification（结构化配置校验）. json-schema.org/specification
- OpenAPI Initiative. OpenAPI Specification（配置接口契约）. spec.openapis.org/oas/latest.html
- IETF RFC 7396. JSON Merge Patch（PATCH 更新语义）. www.rfc-editor.org/rfc/rfc7396
- IETF RFC 9110. HTTP Semantics（条件请求与 ETag）. www.rfc-editor.org/rfc/rfc9110
- PostgreSQL. Documentation: JSON Types（JSONB 数据结构）. www.postgresql.org/docs/current/datatype-json.html
- PostgreSQL. Documentation: Row Security Policies（行级访问控制）. www.postgresql.org/docs/current/ddl-rowsecurity.html
- OWASP. Top 10 for Large Language Model Applications（Prompt Injection、敏感信息等风险）. genai.owasp.org/llm-top-10
- NIST. AI Risk Management Framework（风险治理原则）. www.nist.gov/itl/ai-risk-management-framework
- NIST. Secure Software Development Framework, SP 800-218（软件供应链与开发治理）. csrc.nist.gov/pubs/sp/800/218/final
- Open Policy Agent. Policy Language / Documentation（策略决策机制示例）. www.openpolicyagent.org/docs
- OpenAI. Agents SDK Documentation（Agent 指令、工具与运行接口的一个实现示例）. openai.github.io/openai-agents-python
- LangChain. LangGraph Documentation（状态、执行与持久化示例）. docs.langchain.com/oss/python/langgraph/overview
- W3C. Web Content Accessibility Guidelines (WCAG) 2.2（配置界面可访问性）. www.w3.org/TR/WCAG22
附录 B：研究证据、验证声明与适用边界
证据层次。 JSON Schema、HTTP 条件请求、PostgreSQL RLS、OWASP 风险类别等属于可由相应官方规范或文档核验的技术机制；Agent 配置分类、交互布局、Manifest 字段、MVP 阶段与测试优先级属于本文提出的工程与产品设计建议。它们不应被误读为 OpenAI、LangGraph 或其他产品的统一实现要求。
尚未验证。 本文没有执行真实 Agent Platform 的用户研究、原型可用性测试、API 联调、数据库迁移、授权渗透测试、模型参数兼容测试或成本压测。测试矩阵是后续工程验收计划，不是已通过的测试报告。参考 URL 为可核验入口，本文未对所有页面进行本次实时逐条访问验证。
适用边界。 主要适用于支持多 Agent、工作空间、资源绑定和版本发布的通用平台；单机实验性 Agent 可以简化对象层级，但不应省略对凭证、权限、发布隔离与运行快照的基本控制。受监管业务、跨境数据处理和高风险自动化还需按实际司法辖区、业务流程与组织政策开展专门审查。
与后续专题的衔接。 F2 输出可验证的 Draft Revision；F3 负责调试、预览与评估；F4 负责发布和共享；F9 负责已发布 Agent 的生命周期管理。F2 的“保存”“校验”“预览”“发布”必须在界面上明确区分。