P4 · 平台如何提供 Agent 构建与开发服务？ - Agent Development Services
所属知识库：Agent 全栈技术地图
所属领域：04 · Agent Platform
所属章节：02 · Agent Platform 是如何构建和运行的？ - Technical Architecture
文档类型：专题研究 / 技术架构 / 参考设计
版本：v1.3
更新日期：2026 年 11 月 1 日
核心问题：Agent Platform 如何将 Agent 的创建、编辑、配置、校验、调试、测试和构建能力封装为可复用、可治理的开发服务，并与注册、发布及运行系统形成一致的工程闭环？
专题导读
本篇属 Technical Architecture。P4 研究 Agent Development Services（智能体开发服务），即平台向可视化编辑器、代码开发工具、CLI、SDK 和自动化流水线提供的一组后端开发能力与契约。研究对象不是某一款 Builder 的 UI，也不是 Agent 内部如何推理；核心是如何将不同开发入口产生的 Agent 定义转换为可校验、可测试、可构建、可交付的标准化资产。
前序 P3 已建立 Agent Definition、Draft、Agent Version 与 Registry 的身份和版本边界。P4 在其基础上解决：开发者如何安全地修改 Draft、如何管理开发环境和依赖、如何得到可信的验证反馈、如何在不污染生产环境的前提下试运行，以及如何把开发结果交给 P3 发布。后续 F1 - F2 - F3 从用户体验角度研究创建、配置和调试；P4 从服务端架构角度研究其支撑机制。
研究结论
- Agent Builder 不等于 Agent Development Services。 Builder 是一种交互入口；开发服务应通过统一契约支持 UI、API、CLI、代码仓库及自动化工具。
- 以可验证的 Agent Manifest 为中间表示（IR）更有利于平台演进。 可视化配置、代码配置和模板实例化可以编译或转换到统一定义，再进行语义校验、依赖解析与构建。
- Draft 与 Version 必须严格分离。 开发阶段允许编辑和迭代；可供生产引用的版本由 Registry 冻结、审核和发布。调试结果不能隐式覆盖已发布版本。
- 校验、构建、测试、发布是不同关口。 Schema 合法不代表工具可用，工具可用不代表 Agent 行为合格，测试通过也不等于获准发布。
- 开发环境应默认隔离生产凭据和高风险副作用。 预览运行需有身份、预算、网络与工具权限边界；必要时采用 Mock、沙箱与人工确认。
- 可复现构建要求记录输入和环境。 定义快照、依赖锁、构建器版本、策略版本和生成工件摘要共同形成可追溯的构建记录；外部模型输出仍不保证逐字复现。
- MVP 应优先实现“统一定义 - 草稿保存 - 静态校验 - 预览运行 - 测试 - 发布交接”闭环。 复杂低代码画布、插件市场和跨语言编译可后置。
一、定义、目标与边界
1.1 服务定义
Agent Development Services 是平台控制面中面向 Agent 开发过程的服务集合，承担定义编辑、模板实例化、依赖解析、校验、预览调试、测试执行、构建打包及开发反馈等职责。它通常包含多个逻辑模块，但不要求物理拆分为独立微服务。
平台应支持至少三类开发入口：可视化 Builder（表单、流程画布、配置面板）、代码优先（Git、CLI、SDK、IDE）和自动化入口（CI/CD、批量生成、API）。三者的共同点是产生符合平台契约的定义；差异在交互方式、代码可表达范围及验证路径。
1.2 与相邻专题的职责
| 专题 | 核心职责 | P4 与其边界 |
|---|---|---|
| P1 Control Plane | 准入、授权、控制与运行协调 | P4 请求授权和调试运行，不代替全局控制面 |
| P2 Execution Plane | Worker、沙箱、执行与状态回传 | P4 使用受限预览执行环境，不自建第二套 Agent Runtime |
| P3 Agent Registry | 定义身份、版本、发布和引用解析 | P4 维护草稿与构建结果；正式不可变版本由 P3 负责 |
| P5 Deployment & Runtime Management | 环境部署、实例与运行生命周期 | P4 输出可部署工件，不直接管理生产部署 |
| P6 Workflow Management | 工作流定义、编排和调度 | P4 提供工作流编辑与校验入口，P6 负责运行语义 |
| P7 Resource & Integration | 模型、工具、知识等资源接入 | P4 引用资源契约，不在草稿中复制生产密钥 |
| P8 Platform API & SDK | 对外统一接口与客户端契约 | P4 提供领域能力，P8 统一暴露与治理接口 |
| P9 Extensibility & Ecosystem | 扩展点与插件生命周期 | P4 消费扩展定义及其开发工具 |
| P10 Platform Data & Assets | 资产、文件、模板和产物 | P4 创建开发工件与验证报告，交由资产服务管理 |
| P11 - P12 | 租户隔离与治理 | P4 必须执行隔离、策略与审计约束 |
关键边界： P4 的 Preview Run 属于开发活动，但底层执行仍应委托 P1/P2；P4 的 Publish Request 属于开发交付，但正式发布决策和版本冻结由 P3 与治理流程完成。
二、平台开发服务的能力模型
建议划分为八组逻辑能力：
| 能力组 | 主要输入 | 主要输出 | 关键约束 |
|---|---|---|---|
| Authoring | 模板、用户编辑、代码配置 | Draft | 并发修改、权限 |
| Schema & IR | 多种编辑器配置 | 标准 Manifest | Schema 版本、兼容性 |
| Dependency Resolution | 模型、工具、Skill、知识引用 | 依赖图与锁定清单 | 可用性、租户范围 |
| Validation | Manifest、资源策略 | 诊断报告 | 错误分级、确定性 |
| Preview & Debug | Draft 快照、测试输入 | 预览 Run、事件流 | 沙箱、预算、副作用 |
| Evaluation & Tests | 测试集、断言、评分规则 | 测试报告 | 评估可靠性、样本偏差 |
| Build & Packaging | 已验证 Draft、依赖锁 | 构建工件、摘要、证明 | 供应链完整性 |
| Handoff | 构建工件、审核记录 | Registry 发布请求 | 审批、不可变版本 |
2.1 统一开发链路
flowchart LR
UI[Visual Builder] --> N[Normalize / Compile]
CODE[Code / CLI / SDK] --> N
TPL[Template] --> N
N --> D[Draft + Agent Manifest]
D --> R[Resolve Dependencies]
R --> V[Validate]
V --> PRE[Preview / Debug]
PRE --> TEST[Test / Evaluate]
TEST --> BUILD[Build Artifact]
BUILD --> PUB[Publish Request to Registry]
PUB --> REG[Immutable Agent Version]此图是逻辑工作流。实际产品允许开发者在预览与编辑之间多次迭代，且发布前的必需门禁取决于风险等级与平台策略。
2.2 为什么需要中间表示
如果可视化 Builder 直接生成某个 Runtime 的私有 JSON，而代码 SDK 又产生另一套定义，平台会出现语义分叉：同一个 Agent 在 UI 与代码路径下行为不同、校验不一致、版本难以比较。引入统一 Manifest 或 IR 可以把编辑方式与执行语义解耦。
IR 不必是一套复杂编译器。MVP 可以采用版本化 JSON Schema + 语义校验器；只有当多语言 SDK、图形工作流、条件节点和插件 DSL 复杂到一定程度时，才引入完整 AST、编译阶段和优化器。
三、核心领域对象与数据关系
| 对象 | 含义 | 建议标识与关系 |
|---|---|---|
| Agent Definition | Agent 的稳定逻辑身份 | agent_id，归属租户/项目 |
| Agent Draft | 可编辑的开发状态 | draft_id、revision、agent_id |
| Agent Manifest | 规范化的能力与依赖声明 | schema_version、content_digest |
| Dependency Lock | 解析后的依赖快照 | lock_id、依赖版本/摘要 |
| Validation Report | 一次校验结果 | validation_id、draft_revision |
| Preview Session | 调试会话及上下文 | preview_id、隔离策略 |
| Preview Run | 预览中的一次执行 | run_id、draft_snapshot_digest |
| Test Suite | 测试集合与预期 | suite_id、suite_version |
| Test Run | 一次测试执行 | test_run_id、输入快照 |
| Build | 从快照生成工件的操作 | build_id、构建器版本 |
| Build Artifact | 可供注册/部署的产物 | artifact_uri、sha256 |
| Publish Request | 向 Registry 的发布交接 | request_id、build_id |
3.1 草稿并发与版本语义
Draft 采用乐观并发控制：更新请求必须携带 expected_revision 或 If-Match，服务端仅在当前修订号匹配时接受写入，否则返回冲突。这样可避免多个编辑器标签页覆盖彼此的修改。
Draft 的每次修改可以保存修订历史，但 Draft Revision 不等于 Agent Version。前者用于编辑回退和协作，后者是 Registry 的不可变发布资产。预览与测试必须固定到某个 Draft Revision 或内容摘要，避免运行期间定义变化导致结果无法解释。
3.2 依赖图与引用
Manifest 中建议以稳定资源 ID + 约束描述依赖，解析后写入 Dependency Lock。需区别：
- 硬依赖：执行必需，如工具契约、运行适配器、指定知识资源。
- 可选依赖：缺失时允许能力降级，必须明确降级行为。
- 动态依赖：运行时查询的模型路由或实时知识；应记录解析策略和运行时实际结果。
- 敏感配置引用：保存 Secret Reference，不保存明文密钥。
对外部托管模型，仅锁定模型名称通常不足以保证输出可复现；应保留提供商、请求参数、模型标识和运行时响应元数据，并注明不可控变更。
四、Agent Manifest 与开发契约
以下是教学性示例，并非现有框架的标准 Schema。
{
"schema_version": "agent.platform/v1",
"agent_id": "research-topic-agent",
"display_name": "选题 Agent",
"instructions_ref": "asset://prompts/topic-v3",
"model": {
"policy_ref": "model-policy://research-default",
"temperature": 0.2
},
"tools": [
{"resource_ref": "tool://web-search", "contract_version": "2.0"}
],
"skills": ["skill://topic-proposal@1.2"],
"knowledge": ["kb://research-guidelines"],
"runtime": {"adapter": "agent-runtime-v1", "timeout_seconds": 900},
"output": {"schema_ref": "schema://topic-proposals@1"}
}4.1 Schema 校验与语义校验
Schema 校验检查字段类型、必填项、枚举、结构约束。语义校验进一步检查：资源是否存在、引用是否跨租户、工具输入输出是否兼容、超时是否超过配额、是否包含不允许的能力、输出 Schema 是否与工作流消费者兼容。
建议诊断结果具有稳定的 code、severity、path、message 和可选 fix_hint，供 UI、CLI 和 CI 统一消费。禁止仅返回模糊的“配置错误”。
4.2 校验分级
| 级别 | 示例 | 处理方式 |
|---|---|---|
| Error | 缺少必需字段、非法资源引用 | 阻止构建或发布 |
| Warning | 未设置预算、模型可能不兼容 | 提示并按策略处理 |
| Info | 建议补充测试样例 | 不阻断 |
| Policy Denial | 禁止使用生产工具或跨租户资源 | 强制阻断，记录策略依据 |
五、Authoring：编辑、模板与开发环境
5.1 可视化与代码两条路径
可视化路径适合表单配置、工具选择、Prompt 编辑、Workflow 画布及实时反馈。代码路径适合复杂逻辑、Git 版本控制、单元测试、团队审查和 CI 集成。平台应定义明确的能力交集和超出可视化表达范围的降级方式：例如，复杂代码 Agent 可在 UI 中只读展示或提供受限编辑，不能静默丢失配置。
5.2 模板实例化
模板不是 Agent Version 的替代物。模板应具有模板 ID、版本、参数 Schema、默认依赖和使用许可。实例化过程产生新的 Agent Draft，并记录 origin_template_id 和 origin_template_version 以便追踪。后续模板更新不应自动覆盖既有 Agent。
5.3 环境隔离
至少区分开发、测试和生产环境。开发服务可以提供测试模型凭据、模拟工具、临时知识库、受限外网访问及低预算额度。开发环境可读生产数据应被视为显式授权的高风险例外，而不是默认行为。
六、Dependency Resolution：依赖解析与兼容性
依赖解析顺序建议为：解析资源身份 → 验证租户可见性 → 检查契约版本 → 计算依赖图 → 检查循环与冲突 → 生成锁定清单 → 输出诊断。
依赖的兼容性至少涉及四类：API Schema 兼容、Runtime Adapter 兼容、模型能力兼容（如工具调用和结构化输出）、权限与策略兼容。对于无法静态确认的能力，必须在测试环境中执行探测，并在报告中标明“运行时验证”。
注意： “工具名称存在”不等于“工具可调用”；“模型支持 Function Calling”不等于其行为在具体任务上稳定可靠。
七、Validation：多阶段校验流水线
建议将校验分为以下阶段，避免把所有失败混为一类：
- 结构校验：Schema、字段、引用格式。
- 依赖校验：模型、工具、Skill、知识资源的可解析性与兼容性。
- 安全策略校验：敏感权限、危险工具、数据边界、预算限制。
- 静态质量检查：死配置、缺失输出约束、循环依赖、不合理超时。
- 预览执行检查：真实或模拟 Runtime 下的行为与事件。
- 测试/评估门禁：断言、基准集、回归与人工审查。
这些阶段可以按成本由低到高执行，快速反馈。测试门禁要与任务风险匹配：低风险内部原型可以使用较轻的检查；涉及外部写入、财务或敏感数据时需要更严格的审批与回归验证。
八、Preview & Debug：开发时运行与调试
8.1 预览执行不是生产执行
Preview Run 仍应复用 P1/P2 的运行契约与事件模型，但必须带有 environment=preview、草稿快照摘要、预算限制和工具权限范围。预览中的人工审批、工具 Mock 与网络限制属于开发策略，不应依赖开发者自觉遵守。
sequenceDiagram
participant D as Developer / Builder
participant DEV as Development Service
participant CP as Control Plane
participant EP as Execution Plane
participant AS as Artifact Store
D->>DEV: Preview(draft_id, revision, input)
DEV->>DEV: Snapshot + Validate + Resolve
DEV->>CP: Create preview run (policy + budget)
CP->>EP: Dispatch sandboxed run
EP-->>DEV: Events / traces / outputs
EP->>AS: Store debug artifacts
DEV-->>D: Timeline + diagnostics + result8.2 调试信息模型
建议将调试数据分为：运行事件、模型请求元数据、工具调用、输入输出摘要、结构化错误、成本/耗时和最终产物。涉及敏感内容的 Prompt、工具参数和外部数据需要脱敏或限制可见性。不能为了调试方便将所有原始上下文默认写入日志。
8.3 常见调试能力
- 固定输入重跑、模型参数对比、工具调用回放。
- Mock 工具结果、注入异常、模拟超时和权限拒绝。
- Workflow 节点级事件与输出 Schema 检查。
- 运行差异对比：定义版本、依赖、环境、输入和结果。
- 失败归因：配置错误、资源不可用、执行错误、模型行为偏差。
回放外部写操作时必须采取只读模拟或专用测试环境，避免重复发送邮件、支付或修改生产数据。
九、Testing & Evaluation：从可运行到可交付
9.1 测试层次
| 层次 | 测试对象 | 例子 |
|---|---|---|
| Schema Test | Manifest 合法性 | 缺字段、非法类型 |
| Contract Test | 模型/工具/输出契约 | 工具返回字段变更 |
| Unit Test | 纯函数或配置转换 | 模板参数替换 |
| Integration Test | Registry/资源/Runtime | 预览 Run 可创建 |
| Scenario Test | 任务行为 | 生成选题候选 |
| Regression Test | 版本变化 | 新版本是否退化 |
| Safety Test | 权限和副作用 | 未授权工具调用被拒绝 |
| Performance/Cost | 时延、Token、费用 | 超预算能否终止 |
9.2 Agent 评估的特殊性
Agent 输出具有随机性与环境依赖。不能只用字符串完全一致来判断质量。应组合结构化断言、确定性规则、人工评分和有校准机制的模型评分。记录数据集版本、评分规则版本、模型与运行环境，并采用失败样例回归。对于 LLM-as-judge，应关注偏差、重复评分稳定性与人工抽样校准。
9.3 发布门禁
测试报告至少应包含 suite_version、manifest_digest、dependency_lock_digest、environment、passed/failed、关键指标与失败样例引用。发布审批只能针对具体构建摘要生效；若审批后草稿修改，应重新生成构建或重新验证，防止 TOCTOU（检查与使用之间发生变更）。
十、Build & Packaging：构建与交付
10.1 构建不等于模型训练
此处 Build 指把 Agent Manifest、依赖锁、提示词引用、代码插件、Runtime 约束及验证元数据整理为可校验的发布工件；它通常不涉及训练模型。对于纯配置型 Agent，构建可能只产生签名 Manifest 和依赖锁；对于代码型 Agent，可能额外产生容器镜像或打包代码。
10.2 参考构建步骤
- 读取并固定 Draft Revision。
- 生成规范化 Manifest 和内容摘要。
- 解析并锁定依赖。
- 执行必需校验与测试门禁。
- 生成 Build Artifact，计算摘要并保存来源信息。
- 记录 Build Provenance（输入、构建器、时间、环境、策略）。
- 将构建结果提交 P3 Registry，进入审批与发布流程。
可复现构建与可复现输出不同。 即使构建工件逐字相同，外部模型、实时工具和知识源也可能使任务输出不同。
10.3 构建状态机
stateDiagram-v2
[*] --> Queued
Queued --> Building
Building --> Succeeded
Building --> Failed
Queued --> Cancelled
Building --> Cancelled
Succeeded --> [*]
Failed --> [*]
Cancelled --> [*]Build 状态不应直接复用 Agent Version 的发布状态。Succeeded 表示构建完成，不代表已经获准发布。
十一、服务 API 与事件契约（参考设计）
下列端点为示例设计，不是既有产品的真实接口。
| 方法 | 路径 | 用途 | 关键控制 |
|---|---|---|---|
| POST | /agents/{id}/drafts | 创建草稿 | Agent 编辑权限 |
| PATCH | /drafts/{id} | 更新草稿 | If-Match 乐观锁 |
| POST | /drafts/{id}/validate | 创建校验任务 | Revision 固定 |
| POST | /drafts/{id}/preview-runs | 创建预览执行 | 预算、工具权限 |
| POST | /drafts/{id}/test-runs | 运行测试集 | 数据集版本 |
| POST | /drafts/{id}/builds | 创建构建 | 构建输入快照 |
| GET | /builds/{id} | 查询构建结果 | 租户可见性 |
| POST | /builds/{id}/publish-requests | 提交发布请求 | 审批与策略 |
示例预览请求：
{
"draft_revision": 17,
"input": {"topic": "城市公共空间"},
"environment": "preview",
"tool_policy": "mock_external_writes",
"budget": {"max_usd": 1.5, "timeout_seconds": 300},
"idempotency_key": "preview-req-20261031-001"
}服务应返回稳定任务 ID；长时间校验、测试和构建可采用异步任务 + 事件订阅或轮询。对于写操作应定义幂等键、请求超时、重试语义和审计事件。事件示例：draft.updated、validation.completed、preview.run.completed、test.run.failed、build.succeeded、publish.requested。事件版本需纳入契约管理。
十二、安全、隔离与治理
12.1 威胁与控制
| 风险 | 典型情形 | 必要控制 |
|---|---|---|
| Prompt Injection | 测试数据诱导调用危险工具 | 工具授权与执行时策略校验 |
| Secret 泄漏 | Manifest 包含明文 API Key | Secret Reference、扫描与脱敏 |
| 跨租户引用 | 草稿绑定其他组织知识库 | 资源解析时租户授权校验 |
| 预览副作用 | 调试时发送真实邮件 | Mock、沙箱、审批与出口限制 |
| 构建供应链风险 | 恶意插件或被替换的依赖 | 来源校验、依赖锁、摘要与签名 |
| 越权发布 | 编辑者绕过审批直接发布 | 分离编辑/审核/发布权限 |
| 资源滥用 | 无限预览或评估调用 | 并发、速率、Token/费用预算 |
| 日志敏感信息 | Trace 包含用户数据 | 分类、脱敏、保留与访问控制 |
12.2 运行时权限不能只靠静态校验
开发时校验只能证明某个快照在特定条件下符合规则。生产执行时的用户身份、工具参数、资源可见性和治理策略可能变化，因此 P1/P2/P7/P12 仍必须在实际调用时执行授权与策略检查。
十三、研究报告 Studio：贯穿案例
13.1 业务目标
Studio 需要让创建者配置“选题 Agent - 审核 Agent - 深度调研 Agent - 分析 Agent”，在发布前验证角色、工具和输出契约，并在执行过程中支持人工审核、返工和报告交付。
13.2 从开发到发布的实例
- 创建
topic-agent的 Agent Definition，基于“选题研究模板”生成 Draft。 - 在 Builder 中编辑角色、指令、模型策略、搜索工具和选题输出 Schema。
- Development Service 对 Manifest 进行结构与资源校验，生成 Revision 17 的诊断报告。
- 创建 Preview Run，在受限环境中以样例选题输入测试，并检查候选题目结构与引用质量。
- 执行测试集：空输入、来源缺失、工具超时、输出格式错误和恶意资料注入。
- 测试达到约定门槛后，构建 Manifest 与依赖锁，生成 Build Artifact。
- 提交发布请求，审核通过后由 P3 创建不可变 Agent Version。
- P5 将该版本部署到测试或生产环境；P1 创建 Run 时固定版本，P2 执行。
13.3 初期推荐架构
flowchart TB
WEB[Studio Builder / Dev UI] --> API[Platform API]
CLI[CLI / CI] --> API
API --> DEV[Development Module]
DEV --> DB[(Drafts / Reports DB)]
DEV --> RES[Resource Resolver]
DEV --> VAL[Validator]
DEV --> CP[Control Plane]
CP --> Q[Task Queue]
Q --> WORKER[Preview Worker / Sandbox]
WORKER --> STORE[(Debug Artifacts)]
DEV --> BUILD[Build Service]
BUILD --> REG[Agent Registry]对于单租户 MVP，可将 Development、Validator、Resolver 与 Registry 放在同一个模块化后端进程，Preview Worker 独立运行。只有当构建吞吐、租户隔离或团队协作需求明确时再拆分服务。
13.4 迭代优先级
| 阶段 | 优先实现 | 暂缓 |
|---|---|---|
| MVP | Draft、Manifest、校验、预览、基础测试、发布交接 | 插件市场、复杂画布 |
| 团队版 | 乐观锁、修订对比、审批、共享模板、回归测试 | 多语言编译 |
| 平台版 | API/CLI/SDK、构建缓存、策略门禁、资产共享 | 大规模市场运营 |
| 生态版 | 扩展 SDK、签名、兼容性矩阵、第三方开发工具 | 依需求演进 |
十四、工程验证方案与验收标准
以下为建议实施的测试计划，不是已完成的测试结果。
| 编号 | 场景 | 预期验收 |
|---|---|---|
| T01 | 新建 Draft | 生成稳定 ID 与 Revision |
| T02 | 两个编辑器并发修改 | 冲突写入被拒绝，不发生静默覆盖 |
| T03 | 非法 Schema | 返回定位明确的结构错误 |
| T04 | 不存在的工具引用 | 依赖校验失败 |
| T05 | 跨租户知识库引用 | 拒绝并审计 |
| T06 | 明文密钥写入 | 拒绝或触发受控处理 |
| T07 | 模板实例化 | 生成独立 Draft 并保留来源 |
| T08 | 预览期间修改 Draft | 当前 Run 仍使用原快照 |
| T09 | 预览调用写入工具 | Mock 或审批拦截生效 |
| T10 | 预览超出预算 | 停止后续调用并记录原因 |
| T11 | 工具契约变更 | 兼容性检查提示或阻断 |
| T12 | 模型不支持必需能力 | 校验或探测失败 |
| T13 | 测试数据集更新 | 旧报告仍可追溯数据集版本 |
| T14 | 评分器波动 | 报告显示不确定性与人工复核 |
| T15 | 相同快照重复构建 | 构建输入摘要一致 |
| T16 | 构建中途失败 | 无半成品被发布 |
| T17 | 发布前修改草稿 | 旧审批不能授权新构建 |
| T18 | 越权发布 | 被拒绝并审计 |
| T19 | 依赖工件被篡改 | 摘要验证失败 |
| T20 | CLI 与 UI 提交相同定义 | 规范化语义一致 |
| T21 | 预览 Worker 崩溃 | Run 标记失败或按策略恢复 |
| T22 | 敏感 Trace 访问 | 未授权主体无法读取 |
14.1 建议监控指标
开发链路关注：草稿保存成功率、校验耗时、诊断分布、预览启动延迟、测试通过率、构建成功率、发布阻断原因和回归缺陷率。成本方面关注预览/测试的模型调用费用、工具费用及执行资源消耗。所有指标应按租户、环境和构建版本进行可控聚合，避免泄漏敏感标识。
14.2 架构验收问题
- UI 与 CLI 是否消费相同的校验结果和发布契约？
- 每个 Preview Run 是否能追溯 Draft Revision、依赖、环境与策略？
- 能否证明测试报告对应即将发布的构建摘要？
- 预览和测试是否有独立预算及高风险工具限制？
- 发布后能否不改变既有 Version 而继续编辑新 Draft？
- Worker、Registry、资源服务暂时不可用时是否给出可诊断的失败状态？
十五、常见误区、取舍与研究边界
误区一：把 Builder 当作平台开发架构。 画布或表单只能体现交互层；开发服务还需要标准定义、校验、测试、构建和治理契约。
误区二：保存草稿就等于发布。 草稿可变且未必通过校验；发布版本应具有固定摘要、审批记录和明确依赖。
误区三：预览成功就等于生产可靠。 单次成功不能覆盖随机性、外部资源波动、异常路径和权限边界，需要回归测试与生产监控。
误区四：把所有功能一次做成低代码。 复杂画布的维护成本可能高于业务价值。先建立统一 Manifest 和服务 API，再扩展交互形式。
误区五：将全部工具调用权限交给开发者配置。 配置声明与最终执行授权不同，必须由运行时策略强制执行。
取舍原则： 首先优化定义一致性、开发反馈和安全边界，再优化 Builder 的丰富度与视觉交互。对个人开发者或小团队，模块化单体 + 独立预览 Worker 往往比微服务集群更容易维护，但需要用真实负载和团队边界验证。
十六、与其他研究专题的衔接
P4 的输入来自 P3 的对象模型、P7 的资源契约及 P12 的治理策略；输出包括可交付 P3 的构建工件、供 P5 部署的版本引用、供 P6 使用的工作流定义和供 P10 存储的测试/调试资产。F1 Agent Creation、F2 Agent Configuration、F3 Agent Development & Testing 是本专题最直接的产品映射；F4 Publishing & Sharing 依赖 P3 的发布与共享机制。
后续 P5 应重点回答“版本如何部署、实例如何启动与管理”，避免重复本篇开发时构建与预览；P8 应重点回答“这些能力如何以稳定、受控的 API/SDK 暴露”，避免重复各开发服务的内部实现。
附录 A：参考文献与原始资料
以下资料用于后续核验概念与工程实现。不同项目的术语和支持范围并不完全一致；本篇统一 Manifest、对象模型和 API 均为研究性参考设计，不应误认为这些产品共同遵循的标准。
- Dify Documentation - 工作流、应用编排、调试与发布等产品/开发能力。官方文档：<docs.dify.ai>。
- LangGraph Documentation - 图式 Agent 工作流、持久化、开发和调试概念。官方文档：<docs.langchain.com/oss/python/langgraph/overview>。
- LangSmith Documentation - Agent 开发、Tracing、Evaluation 与部署相关能力。官方文档：<docs.langchain.com/langsmith/home>。
- Microsoft Copilot Studio Documentation - Agent 创建、测试、发布和治理等平台流程。官方文档：<learn.microsoft.com/en-us/microsoft-copilot-studio>。
- OpenAI Agents SDK Documentation - 代码优先的 Agent 构建、工具与追踪接口。官方文档：<openai.github.io/openai-agents-python>。
- JSON Schema Specification - 结构化配置的声明式校验基础。<json-schema.org/specification>。
- OpenAPI Specification - 平台服务接口的机器可读契约。<spec.openapis.org/oas/latest.html>。
- OWASP Top 10 for LLM Applications - LLM/Agent 相关威胁与控制参考。<owasp.org/www-project-top-10-for-large-language-model-applications>。
- SLSA - 软件构建来源与供应链完整性参考。<slsa.dev>。
- NIST AI Risk Management Framework - AI 系统风险管理与治理参考。<www.nist.gov/itl/ai-risk-management-framework>。
附录 B：研究证据、验证声明与适用边界
B.1 证据分类
- 基础事实与通用机制：Schema 校验、API 契约、版本快照、乐观锁、构建摘要等属于通用软件工程方法；可依据相应规范与工程文献验证。
- 行业产品参考：Dify、LangGraph、LangSmith、Copilot Studio、Agents SDK 展示了不同的 Agent 开发与测试入口，但其内部实现、商业能力与产品命名并不完全相同。
- 本文研究性设计：Agent Manifest、Development Service 分组、API 路径、事件名称、测试矩阵、Studio 架构和演进阶段均为建议方案，并非行业强制标准。
B.2 已执行与未执行的验证
已执行：文档结构编写、目录名称核对、概念职责检查及示例 JSON 的语法自检。未执行：真实平台部署、API 集成测试、工具沙箱测试、负载测试、故障注入、生产权限测试以及具体产品最新版本功能核验。因此，文中的 T01 - T22 是待实施的工程验证计划，不是测试通过声明。
B.3 适用边界
本文适用于需要同时支持可视化/代码开发入口、Agent 定义复用、开发时预览和受控发布的 Agent Platform。对于单一用途的 Agent 脚本，完整开发服务可能过重；对于高度监管或多租户商业平台，则需额外细化合规、供应链、租户数据治理和组织审批要求。有关 Runtime 内部实现应以 03 · Agent System 和 P2 为主；有关用户界面和产品流程应以 F1 - F2 - F3 - F4 为主。