F9 · 用户如何管理 Agent 的版本与生命周期？ - Agent Management

所属知识库：Agent 全栈技术地图
所属领域：04 · Agent Platform
所属章节：03 · Agent Platform 应该提供哪些产品功能？ - Product Architecture
文档类型：专题研究 / 产品架构 / 生命周期与治理参考设计
版本：v1.3
更新日期：2026 年 11 月 1 日
核心问题：用户如何持续维护 Agent 的身份、配置草稿、不可变版本、发布渠道、部署与运行状态，并安全完成升级、回滚、停用、归档、恢复和删除？

专题导读

本篇属 Product Architecture。F1 - F2 - F3 - F4 覆盖创建、配置、开发测试与发布共享，F6 - F7 - F8 覆盖运行、协作和监控。F9 关注 Agent 创建以后如何长期管理：用户需要在一个清晰的产品界面中辨别 Agent 的当前状态、版本、部署、使用关系、风险和可执行操作，并在不破坏历史运行与依赖关系的前提下进行变更。

本篇以 Agent Definition 为稳定身份、Agent Version 为不可变版本、Release Channel 为可变版本指针、Deployment 为环境中的部署对象、Run 为一次实际执行 的模型为基础。与 P3 Agent Registry、P5 Deployment & Runtime Management、P11 Multi-tenancy & Isolation、P12 Platform Governance 的技术职责相衔接，但本篇的核心是用户可见的功能、流程和交互契约。

证据边界：规范性引用支撑 API 版本、数据库并发、安全控制等技术原理；具体产品页面、字段、状态名称和验收阈值为本篇提出的参考设计，尚未进行真实用户或生产验证。

研究结论

Agent Management 应当提供 资产列表、Agent 详情、版本历史、发布渠道、部署与使用关系、维护操作、活动审计 七类核心能力；初期可以整合到少量页面。
必须分开呈现 Agent 身份状态、版本状态、渠道状态、部署状态、运行状态，避免一个笼统的“启用/停用”开关产生误导。
修改草稿不影响已发布版本；切换发布渠道不自动修改既有 Run；停用 Agent 不等于取消所有运行；归档不等于删除。 每项操作需要独立的生效范围。
升级与回滚的产品操作应当先展示影响分析：被引用的 Workflow、项目、Deployment、活跃 Run、工具权限与依赖兼容性。
高风险操作采用预检、明确确认、权限校验、审计和异步反馈；删除还需要保留期、关联关系检查和恢复策略。
Studio MVP 优先支持 Agent 列表、详情、版本对比、渠道切换、停用/恢复、依赖查看、归档，再扩展复杂迁移和自动化治理。

01 · 定义与职责边界

1.1 Agent Management 是什么？

Agent Management 是平台面向 Agent 所有者、项目负责人、开发者与管理员提供的持续维护能力，帮助他们理解一个 Agent 现在是什么、有哪些版本、谁在使用、哪些环境在运行、能否安全变更、如何追溯责任。

它不是再次设计 Agent 的角色和工具配置（F2），不是测试 Agent 行为（F3），也不是一次 Run 的暂停或取消（F6）。F9 主要管理长期存在的 Agent 资产及其发布与使用关系。

相邻专题	核心职责	F9 的衔接点
F2 Agent Configuration	编辑草稿配置	查看草稿、跳转编辑、提示未发布变更
F3 Agent Development & Testing	预览、调试、回归评估	查看版本测试证据与质量变化
F4 Agent Publishing & Sharing	发布版本与共享	管理已发布版本、渠道和共享状态
F6 Agent Execution	启动与控制 Run	展示当前活跃运行和停用后的执行限制
F8 Agent Monitoring	观察运行与质量	在版本详情关联健康指标、错误与成本
P3 Agent Registry	存储定义与不可变版本	F9 通过 API 展示和管理 Registry 对象
P5 Deployment & Runtime	部署、实例与运行生命周期	F9 发起升级、回滚、停用等受控操作
P12 Platform Governance	策略、权限、审批与审计	对所有管理操作进行治理

1.2 用户最容易混淆的五种“状态”

维度	管理对象	典型状态	关键含义
身份状态	Agent Definition	ACTIVE / DISABLED / ARCHIVED	是否允许新的使用、是否仍展示在常规目录
草稿状态	Agent Draft	EDITING / VALIDATED / BLOCKED	是否有待发布修改，是否通过校验
版本状态	Agent Version	PUBLISHED / DEPRECATED / REVOKED	该不可变版本是否被推荐或允许解析
部署状态	Deployment	ACTIVE / ROLLING_OUT / DRAINING / INACTIVE	环境中部署是否可接受新任务
运行状态	Run	QUEUED / RUNNING / SUCCEEDED / FAILED / CANCELED	单次任务的实际执行进度

上述枚举是参考设计，不是行业统一标准。系统必须为每个状态定义可执行操作、权限要求和事件契约。

02 · 用户、任务与使用场景

用户	核心问题	高频操作	风险关注
Agent 所有者	我维护的 Agent 是否健康？	查看版本、编辑、升级、停用	误改生产行为
项目负责人	哪些项目依赖它？	查看使用关系、批准升级	影响在途研究任务
Agent 开发者	新版本比旧版好吗？	对比配置、测试报告、回滚	兼容性和质量退化
工作空间管理员	谁有权限管理它？	转移所有权、授权、审计	越权与资源泄漏
平台管理员	哪些 Agent 有治理风险？	批量审查、撤销、保留	跨租户影响、合规

典型用户故事：①发现某个 Agent 在过去一周错误率升高，定位到版本变更；②新模型配置发布后只让测试项目试用；③原所有者离职，需要移交管理权；④研究项目结束，将 Agent 归档但保留历史报告的来源链；⑤插件凭证泄漏，需要紧急阻止新调用，并处理活跃运行。

03 · 产品功能架构与信息架构

3.1 建议的功能树

mermaid

flowchart TB
  A[Agent Management] --> B[Agent 列表与检索]
  A --> C[Agent 详情]
  A --> D[版本与渠道]
  A --> E[部署与使用关系]
  A --> F[维护操作]
  A --> G[审计与活动]
  C --> C1[概览与健康]
  C --> C2[草稿与配置]
  D --> D1[版本对比]
  D --> D2[升级与回滚]
  E --> E1[项目与工作流引用]
  E --> E2[活跃 Run]
  F --> F1[停用与恢复]
  F --> F2[归档与删除]
  F --> F3[所有权转移]

3.2 Agent 列表

推荐字段：名称、稳定 ID、所属 Workspace、所有者、身份状态、稳定渠道版本、最近发布、活跃 Run 数、依赖项目数、异常标记、最近修改时间。筛选支持状态、所有者、标签、项目、最近使用、版本风险。列表中避免把“最新草稿版本”当作“生产版本”。

3.3 Agent 详情页

建议标签页为：概览｜配置草稿｜版本｜部署与引用｜运行与质量｜权限与共享｜活动记录。概览优先回答：当前生产使用哪个版本？有无未发布修改？最近是否出现异常？哪些项目正在使用？

3.4 管理操作分级

风险等级	操作	建议交互
低	修改描述、标签、查看版本	即时保存、可撤销
中	更改负责人、标记版本弃用、归档	影响提示、确认
高	切换生产渠道、停用、撤销版本	预检、差异比较、二次确认、审计
极高	强制中断运行、跨租户转移、永久删除	专门权限、审批、异步执行、保留证据

04 · 核心对象模型与关系

mermaid

erDiagram
  WORKSPACE ||--o{ AGENT_DEFINITION : owns
  AGENT_DEFINITION ||--o{ AGENT_DRAFT : edits
  AGENT_DEFINITION ||--o{ AGENT_VERSION : publishes
  AGENT_DEFINITION ||--o{ RELEASE_CHANNEL : exposes
  RELEASE_CHANNEL }o--|| AGENT_VERSION : points_to
  AGENT_VERSION ||--o{ DEPLOYMENT_REVISION : pinned_by
  DEPLOYMENT ||--o{ DEPLOYMENT_REVISION : has
  DEPLOYMENT_REVISION ||--o{ RUN : starts
  AGENT_DEFINITION ||--o{ RESOURCE_REFERENCE : referenced_by
  AGENT_DEFINITION ||--o{ MANAGEMENT_OPERATION : records
  AGENT_DEFINITION ||--o{ AUDIT_EVENT : audited_by

关键约束：Agent Definition 的 agent_id 在生命周期内稳定；Agent Version 发布后不可原位编辑；Release Channel 的指针可通过受控事务修改；Deployment Revision 和 Run 应固定不可变版本；跨 Workspace 引用不能越过权限和依赖检查。

4.1 推荐对象字段

对象	关键字段	注意事项
Agent Definition	id, tenant_id, workspace_id, owner_id, status	所有权与身份状态分离
Agent Version	id, agent_id, version_label, manifest_digest, published_at	不可变、可追溯
Release Channel	agent_id, channel, version_id, revision	指针修改需要并发控制
Deployment	id, environment, status, active_revision_id	与渠道指针不是同一对象
Usage Reference	consumer_type, consumer_id, pinned_version_id	区分固定版本和跟随渠道
Management Operation	id, type, requested_by, status, scope, result	高风险操作可能异步完成
Audit Event	actor, action, target, before_hash, after_hash, timestamp	敏感字段脱敏

05 · 生命周期状态与操作语义

5.1 Agent 身份生命周期

mermaid

stateDiagram-v2
  [*] --> ACTIVE: 创建
  ACTIVE --> DISABLED: 停用新使用
  DISABLED --> ACTIVE: 恢复
  ACTIVE --> ARCHIVED: 归档
  DISABLED --> ARCHIVED: 归档
  ARCHIVED --> ACTIVE: 恢复归档
  ARCHIVED --> PENDING_DELETION: 请求删除
  PENDING_DELETION --> ARCHIVED: 撤销删除请求
  PENDING_DELETION --> DELETED: 保留期结束并完成清理

这是产品参考状态机。实际系统可以将 DISABLED 设计为独立布尔治理开关，避免与 ARCHIVED 互斥状态混用，但 UI 必须清晰解释组合状态。

5.2 操作影响范围

操作	新建 Run	已排队 Run	正在运行 Run	已完成 Run	历史版本
保存草稿	无影响	无影响	无影响	无影响	无影响
发布新版本	默认无影响	固定原版本	固定原版本	无影响	保留
切换渠道	后续解析新版本	已固定者不变	不变	无影响	保留
停用 Agent	默认拒绝新启动	按策略取消或继续	按策略排空或终止	保留	保留
标记版本弃用	新解析可提示或阻止	不变	不变	保留	保留
撤销版本	阻止新解析	需策略决策	需风险评估与处置	保留审计	不可再正常使用
归档 Agent	从常规目录隐藏、禁止新启动	需预检	需预检	保留	保留
永久删除	不允许	必须处置	必须处置	按保留策略	受保留策略约束

重要区分：停用不是立即杀死所有执行。对于正在调用外部 API 的 Agent，即使发出终止请求，也不能保证已提交的外部副作用被撤销。

06 · 版本历史、比较与升级

6.1 版本历史页

每个版本至少展示：版本标签、不可变 ID、发布时间、发布者、摘要、测试结果、依赖锁定摘要、渠道指向、部署环境、弃用/撤销状态、引用数。版本标签（如 1.2.0）是便于阅读的命名，不应作为唯一身份。

6.2 版本差异应如何呈现？

差异视图分为三层：①用户可读摘要（角色、工具、知识库、模型策略变化）；②结构化 Manifest 差异（字段级新增、修改、删除）；③风险与证据（权限变化、测试差异、依赖变更、成本估算）。

差异类型	例子	风险提示
Prompt	引用规则调整	可能改变输出格式与质量
模型	供应商或模型版本变更	延迟、成本、行为兼容性
工具	新增网页写入工具	需要重新授权和审批
知识	替换知识库版本	证据覆盖和数据权限变化
Schema	输出字段删除	可能破坏下游 Workflow
运行参数	并发/超时变化	资源预算和稳定性

6.3 升级流程

选择目标版本 → 生成影响分析 → 查看回归测试 → 检查权限与依赖 → 选择环境/渠道 → 提交审批（如需要）→ 切换或部署 → 观察 → 完成或回滚。

升级不应默认同时修改全部部署。渠道指针切换与实际部署 rollout 是两项不同操作；对于固定版本引用，渠道切换不产生影响。

6.4 回滚语义

回滚通常是把渠道或部署重新指向一个已存在的不可变版本，不是删除新版本，也不是恢复外部系统的历史状态。用户应看到回滚范围、活跃任务处理方式、数据 Schema 兼容性和预期影响。

mermaid

sequenceDiagram
  participant U as 用户
  participant UI as 管理工作台
  participant CP as Control Plane
  participant R as Registry
  participant DP as Deployment Service
  U->>UI: 选择从 v3 回滚到 v2
  UI->>CP: 影响分析请求
  CP->>R: 获取版本与依赖
  CP->>DP: 查询部署与活跃 Run
  CP-->>UI: 兼容性、风险与操作范围
  U->>UI: 确认并提交
  UI->>CP: 回滚命令 + 幂等键
  CP->>R: 条件更新渠道指针
  CP->>DP: 按策略执行部署调整
  CP-->>UI: 操作 ID 与阶段状态

07 · 停用、恢复、弃用与撤销

7.1 停用操作

停用向导必须回答：停用后谁不能再启动？排队任务如何处理？正在执行的任务继续、排空还是尝试取消？是否存在必须保持运行的生产工作流？是否存在定时触发器？停用原因和恢复条件是什么？

推荐提供 仅禁止新运行、禁止新运行并排空、紧急阻断 三种明确策略；紧急阻断可能涉及凭证撤销和工具网关禁用，应提示其对其他共享资源的潜在影响。

7.2 版本弃用与撤销

DEPRECATED 表示不再推荐新使用，可设置迁移期限；REVOKED 表示因安全或严重错误被禁止新解析或执行。撤销不等于物理删除，审计、历史 Run 的版本引用仍需保留。产品需展示替代版本、原因、责任人、时间和影响范围。

7.3 恢复

恢复操作不能简单把状态改回 ACTIVE：必须重新验证权限、模型和工具连接、凭证有效性、版本可用性、预算和工作空间策略。归档期间被撤销的外部授权不应自动恢复。

08 · 归档、删除、保留与恢复

8.1 归档

归档是可逆的业务管理操作，适用于项目结束、Agent 不再维护或需要清理工作空间视图。归档后的 Agent 默认从常规目录隐藏、禁止新启动，但仍可在有权限的归档视图中检索，历史 Run 和产物来源保持可追溯。

8.2 删除

永久删除必须检查：活跃 Run、部署、定时任务、Workflow 引用、共享安装、审计保留、法律保留和备份策略。建议采用 删除请求 → 预检 → 冻结新引用 → 保留期 → 异步清理 → 删除完成证明 的流程。无法满足删除条件时应返回明确阻断原因，而不是静默级联删除。

8.3 资产删除与历史证据的张力

隐私删除请求可能与审计保留义务冲突，具体处置取决于适用法律与业务规则。可考虑分离可识别内容、技术摘要、审计元数据和物理 Blob 的保留策略，但不得假定“仅保存哈希”一定满足所有隐私要求。

09 · 所有权、权限与协作维护

9.1 管理权限矩阵（参考）

操作	Viewer	Editor	Owner	Workspace Admin
查看 Agent 与授权版本	✓	✓	✓	✓
编辑 Draft	-	✓	✓	依策略
发布版本	-	依策略	✓	依策略
切换生产渠道	-	-	依策略	依策略
停用/恢复	-	-	✓	✓
归档	-	-	✓	✓
转移所有权	-	-	需确认	需审计
永久删除	-	-	需审批	需审批

以上矩阵是产品建议；真实授权必须结合资源归属、租户策略、操作风险和运行时上下文判定，不能只信任前端按钮显隐。

9.2 所有权转移

所有权转移需要检查接收人是否属于有权工作空间、是否接受维护责任、是否涉及个人凭证和外部连接。转移 Agent 所有权不应自动转移个人 OAuth 凭证；应提示重新绑定目标用户或工作空间级连接。

9.3 多人维护与并发

编辑 Draft 使用 ETag / revision 乐观锁；版本发布时绑定特定草稿修订；渠道切换使用 expected_revision 条件更新；同一时间的竞争升级只能有一个成功，其他请求返回冲突并提示刷新。

10 · 依赖关系与变更影响分析

10.1 依赖图

mermaid

flowchart LR
  A[Agent Version v2] --> B[Workflow Version 研究报告]
  A --> C[Project A]
  A --> D[Project B]
  B --> E[Scheduled Trigger]
  A --> F[Deployment Production]
  F --> G[Active Runs]
  A --> H[Tool/Model/Knowledge Bindings]

依赖分析应区分 直接引用 与 间接引用，并标记 固定版本 与 跟随渠道。例如，工作流固定 agent_version_id=v2，则 production 渠道切换到 v3 不应影响该工作流。

10.2 影响分析结果

至少展示：受影响的工作流与项目数量、活跃 Run 数、定时触发器、部署环境、跨 Workspace 安装、权限差异、输出 Schema 兼容性、未通过的测试、可用回滚版本。数量只能作为影响规模提示，不可替代逐项兼容性判断。

10.3 批量操作

批量归档、停用和迁移应支持预览、逐项失败报告、部分成功状态与操作审计。跨租户批量管理需要额外权限隔离，避免把一个租户的资源标识暴露给另一个租户。

11 · 产品交互与异常反馈

11.1 升级确认示例

将“调研 Agent”生产渠道从 v1.4 切换到 v1.5。已固定版本的 3 个工作流不会自动升级；跟随生产渠道的 2 个新任务入口将使用 v1.5。当前运行中的 5 个 Run 保持原版本。请确认已查看回归测试和资源权限差异。

上述数字仅为示意，不是 Studio 的真实运行数据。

11.2 操作状态

高风险操作使用独立 ManagementOperation：REQUESTED → VALIDATING → AWAITING_APPROVAL → APPLYING → SUCCEEDED / FAILED / PARTIALLY_COMPLETED。UI 不应在收到 HTTP 202 后直接显示“操作完成”。

11.3 错误反馈原则

版本冲突：显示他人已修改的对象、刷新和重新提交入口。
权限不足：说明缺少的操作权限，不泄漏未授权资源详情。
依赖阻断：列出可见的阻断对象与解决方式。
部署升级失败：展示已成功和失败的环境，并给出回滚入口。
删除受限：说明保留期、活跃 Run 或法定保留等原因。
外部连接失效：提示重新授权，不展示密钥明文。

12 · 技术架构映射

mermaid

flowchart TB
  UI[Agent Management UI] --> API[Platform API]
  API --> GOV[Governance / AuthZ]
  API --> CP[Control Plane]
  CP --> REG[Agent Registry]
  CP --> DEP[Deployment & Runtime Management]
  CP --> WF[Workflow Management]
  CP --> ASSET[Asset & Dependency Index]
  CP --> AUDIT[Audit Event Store]
  DEP --> WORKER[Execution Plane]
  REG --> DB[(PostgreSQL)]
  AUDIT --> DB

技术原则：所有改变生产行为的操作由后端验证权限和策略；前端只负责呈现可操作状态。管理命令应具备幂等键、操作 ID、状态查询和审计链。跨服务变更不应假定存在单个分布式 ACID 事务，可采用状态机、Outbox 事件与补偿动作处理部分成功。

13 · 参考 API 与数据契约

13.1 API 资源与端点

方法	端点	作用
GET	`/v1/agents`	列表、筛选、分页
GET	`/v1/agents/{agent_id}`	Agent 详情与状态
GET	`/v1/agents/{agent_id}/versions`	版本历史
GET	`/v1/agents/{agent_id}/versions/{version_id}/diff?against=...`	版本差异
GET	`/v1/agents/{agent_id}/usage`	项目、工作流、部署与 Run 引用
POST	`/v1/agents/{agent_id}/operations/impact-analysis`	变更影响预检
POST	`/v1/agents/{agent_id}/operations`	提交升级、停用、归档等命令
GET	`/v1/management-operations/{operation_id}`	查询异步操作状态
GET	`/v1/agents/{agent_id}/audit-events`	查看审计记录

所有端点均为建议接口，不代表已有产品实现。

13.2 操作请求示例

json

{
  "operation_type": "SWITCH_RELEASE_CHANNEL",
  "agent_id": "agt_topic_001",
  "channel": "production",
  "target_version_id": "av_20261101_002",
  "expected_channel_revision": 7,
  "impact_analysis_id": "impact_001",
  "reason": "通过回归评估，准备切换生产入口",
  "idempotency_key": "op-20261101-topic-002"
}

服务器应校验影响分析是否过期、目标版本是否可用、调用者是否有权、依赖是否满足，并在事务中执行条件更新。幂等键应绑定主体、操作和参数摘要，避免同一键被复用为不同命令。

13.3 操作响应示例

json

{
  "operation_id": "mop_001",
  "status": "VALIDATING",
  "agent_id": "agt_topic_001",
  "submitted_at": "2026-11-01T06:00:00Z",
  "status_url": "/v1/management-operations/mop_001"
}

13.4 统一错误示例

json

{
  "error": {
    "code": "CHANNEL_REVISION_CONFLICT",
    "message": "发布渠道已被其他操作更新，请刷新后重试。",
    "request_id": "req_example_001",
    "retryable": false
  }
}

建议 HTTP 映射：401 未认证、403 无权、404 未授权对象不可见或不存在、409 状态/版本冲突、412 条件请求失败、422 语义校验失败、429 配额限制；具体行为需在 API 契约中统一。

14 · 数据模型与事务设计

以下 PostgreSQL DDL 为简化的概念示例，省略真实系统中的外键、RLS、迁移策略及部分审计字段；不能直接作为生产迁移脚本。

sql

CREATE TABLE agent_management_operations (
  id UUID PRIMARY KEY,
  tenant_id UUID NOT NULL,
  workspace_id UUID NOT NULL,
  agent_id UUID NOT NULL,
  operation_type TEXT NOT NULL,
  status TEXT NOT NULL,
  requested_by UUID NOT NULL,
  request_hash TEXT NOT NULL,
  idempotency_key TEXT NOT NULL,
  expected_revision BIGINT,
  request_payload JSONB NOT NULL,
  result_payload JSONB,
  failure_code TEXT,
  created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
  updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
  UNIQUE (tenant_id, requested_by, idempotency_key)
);

CREATE INDEX idx_agent_mgmt_ops_agent_time
  ON agent_management_operations (tenant_id, agent_id, created_at DESC);

CREATE TABLE agent_release_channels (
  tenant_id UUID NOT NULL,
  agent_id UUID NOT NULL,
  channel TEXT NOT NULL,
  version_id UUID NOT NULL,
  revision BIGINT NOT NULL DEFAULT 1,
  updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
  PRIMARY KEY (tenant_id, agent_id, channel)
);

14.1 原子渠道切换

sql

UPDATE agent_release_channels
SET version_id = :target_version_id,
    revision = revision + 1,
    updated_at = now()
WHERE tenant_id = :tenant_id
  AND agent_id = :agent_id
  AND channel = :channel
  AND revision = :expected_revision
RETURNING revision;

影响行数为 0 表示对象不存在或并发版本冲突，应在授权上下文中进一步区分。真实实现必须在事务内校验目标版本归属与状态，并同步写入审计/Outbox，避免“渠道已切换但事件丢失”。

14.2 版本固定与一致性

启动 Run 时必须把解析后的 agent_version_id、关键依赖锁摘要和执行策略快照写入运行记录；不能仅保存 production 字符串。对于模型供应商提供的可变别名、外部网页和动态工具，固定 Manifest 仍不足以保证完全复现，应明确记录不可控因素。

15 · Studio 贯穿案例

15.1 场景

研究报告 Studio 维护一组 Agent：选题、选题审核、深度调研、分析、写作和终审。多个研究项目共享这些 Agent，但各自的 Workflow Version 和 Run 可以固定不同版本。

15.2 一次完整升级

发现问题：项目负责人在 F8 监控中发现“调研 Agent v1.2”的引用格式失败率上升。
开发修复：开发者在 F2 修改引用指令，并在 F3 使用历史失败案例进行回归测试。
发布新版本：F4 发布不可变 v1.3，保留 v1.2 作为可回滚版本。
影响分析：F9 展示 4 个研究项目、2 个工作流版本引用 v1.2；其中固定引用不会自动变更。
试运行：测试环境或指定项目使用 v1.3，观察结构化输出与引用质量。
生产切换：经授权后，将 production 渠道指向 v1.3；后续跟随渠道的新 Run 使用新版本。
历史保留：正在运行的研究任务继续使用启动时固定的 v1.2。
出现回归：如发现新问题，可把渠道指回 v1.2；已经产生的外部文件或副作用需要单独处理。
收尾：记录升级原因、测试证据、审批人与运行观察结果。

上述数量为假设场景，不代表真实 Studio 数据。

15.3 Studio Agent 管理页草图（文字结构）

text

研究工作空间 / Agent 管理
├─ Agent 列表：名称、角色、状态、生产版本、最近运行、负责人
└─ 调研 Agent / 详情
   ├─ 概览：生产 v1.3｜草稿未发布｜最近质量趋势
   ├─ 配置草稿：编辑入口、校验状态
   ├─ 版本：v1.1 / v1.2 / v1.3，差异与回归证据
   ├─ 部署与引用：研究项目、Workflow、活跃 Run
   ├─ 维护：渠道切换、停用、恢复、归档
   ├─ 权限与共享：所有者、成员、安装与引用
   └─ 活动：发布、变更、审批与异常事件

15.4 与 Studio 现有工作流的结合

Studio 的选题→审核→调研→分析→写作流程应在 Workflow Version 中固定每个节点的 Agent 版本解析策略。对于重要正式报告，建议默认使用固定版本引用；探索性或低风险任务可在明确标识后采用渠道跟随策略。

16 · 分阶段开发路线

阶段	核心能力	验收重点
M0 基础可见性	Agent 列表、详情、状态、版本历史	用户能确认生产版本与所有者
M1 基础维护	版本比较、渠道切换、停用/恢复、审计	操作不改变既有 Run 的固定版本
M2 生命周期	归档/恢复、依赖查询、所有权转移	有阻断原因与可恢复路径
M3 风险治理	影响分析、审批、灰度升级、回滚	高风险变更可审计、可回退
M4 规模化管理	批量操作、保留策略、自动化建议	租户隔离、部分成功与操作追踪

优先级建议：对单人开发的 Studio，不应一开始建设完整 Marketplace 或跨租户资产迁移；先解决版本可见、变更可控、历史可追溯。

17 · 产品指标、可用性与评估

指标	计算口径建议	目的
版本识别成功率	用户能否正确指出当前生产版本	验证信息架构清晰度
变更预检完成率	高风险操作中完成影响分析的比例	检查安全操作路径
误操作恢复时间	从发现错误切换到恢复稳定入口的时间	衡量可恢复性
版本回滚成功率	符合前提的回滚操作中成功比例	评估管理可靠性
孤儿引用数	指向不可用版本/对象的引用数	识别依赖治理缺口
归档恢复成功率	合法恢复请求中完成恢复的比例	验证生命周期设计
审计覆盖率	应记录的管理操作中实际有证据的比例	评估可追溯性

指标必须说明采样窗口、分母、权限范围和数据新鲜度。不能用“用户点击了回滚”代替“系统确实完成回滚”。

18 · 风险、局限与反思

状态复杂性：多个独立状态会增加理解成本，应以用户任务组织界面，并提供状态解释。
伪回滚：切回旧版本不能撤销外部副作用、数据库变更或已经生成的成果。
版本漂移：动态模型别名、外部工具和知识资源可能使同一 Agent Version 的实际行为发生变化。
依赖不完整：若缺乏准确的引用索引，影响分析可能遗漏间接依赖；应显示分析置信度与未知项。
权限竞态：预检通过后到真正执行前，权限、凭证或目标版本可能变化；执行时必须重新校验。
长期任务：正在运行的任务可能跨越多个版本发布周期，必须保存独立运行快照。
删除不可逆：永久删除涉及备份、保留和外部副本，产品不能保证不受控制的副本被删除。
过度设计：早期产品不需要把所有基础设施对象暴露给业务用户；应提供角色化信息披露。

19 · 工程与产品验证矩阵（待执行）

以下是测试设计，不是已经执行的测试结果。

编号	测试场景	预期结果
T01	创建 Agent 后打开详情	稳定 ID、归属、状态正确
T02	草稿修改未发布	生产版本不变
T03	查看版本历史	可见不可变版本及发布信息
T04	对比 Prompt 变化	差异准确且敏感内容受控
T05	对比工具权限变化	明确标记新增授权风险
T06	版本切换前影响分析	显示固定与跟随渠道引用
T07	切换渠道成功	后续解析得到目标版本
T08	已启动 Run 遇渠道切换	继续使用原固定版本
T09	两个管理员并发切换	只有符合预期修订的请求成功
T10	重复提交相同幂等键	不产生重复操作
T11	同一幂等键参数不同	返回冲突或拒绝
T12	未授权用户切换生产	后端拒绝且记录必要审计
T13	目标版本已撤销	阻止渠道切换
T14	目标版本依赖失效	预检提示并阻止不安全操作
T15	停用 Agent	新 Run 被拒绝
T16	停用时有活跃 Run	按所选排空/终止策略处理
T17	紧急撤销工具权限	后续工具调用被阻断
T18	归档 Agent	常规目录隐藏，历史记录可追溯
T19	归档 Agent 恢复	重新校验依赖与权限
T20	归档对象存在固定引用	不发生隐式级联删除
T21	永久删除有活跃 Run	阻断并解释原因
T22	删除受保留策略限制	拒绝且记录依据
T23	所有权转移	新所有者有效、旧授权按策略更新
T24	所有权转移涉及个人 OAuth	不自动转移凭证
T25	跨租户读取版本列表	无数据泄漏
T26	跨租户执行管理命令	被拒绝，避免枚举信息泄漏
T27	管理操作异步失败	UI 展示 FAILED 与可操作原因
T28	部分部署升级失败	显示 PARTIALLY_COMPLETED 与逐项状态
T29	审计事件写入失败	受策略约束，不能静默成功
T30	事件投递重复	消费方去重，最终状态一致
T31	渠道更新后缓存未刷新	版本解析具备一致性保护
T32	已弃用版本被新项目引用	按策略警告或阻断
T33	回滚到旧版但 Schema 不兼容	预检阻断或要求迁移计划
T34	批量归档部分失败	返回逐项结果和审计
T35	恢复后外部连接已失效	提示重新授权，不自动放行
T36	Run 历史来源查看	能追溯固定 Agent Version
T37	删除请求撤销	保留期内恢复合法状态
T38	高风险操作审批过期	拒绝执行并要求重新审批
T39	权限在预检后被撤销	执行阶段重新校验并拒绝
T40	管理页面可用性访谈	用户能区分发布、部署、停用、归档

20 · 总结

F9 的核心不是把 Agent 作为普通文件进行增删改查，而是把它视为具有稳定身份、不可变版本、发布入口、运行依赖、权限边界和历史证据的长期平台资产。好的 Agent Management 产品应让用户在变更前知道影响范围、在变更中看到真实状态、在变更后可以追溯结果，并在必要时恢复到安全配置。

对 Studio，建议先实现版本历史、差异比较、生产渠道切换、停用与归档、使用关系与审计，再扩展自动化升级、跨项目迁移和复杂保留策略。下一篇 F10 · 用户如何管理任务产物与交付成果？ - Artifact & Delivery Management 将转向用户如何查看、审核、整理、导出和交付 Agent 产物。

附录 A：参考文献与原始资料

以下资料支撑不可变版本、并发控制、API 契约、权限、安全和审计等基础原理；不直接规定本文的 Agent Management 产品信息架构。具体产品设计属于工程综合推论。

Kubernetes, Objects in Kubernetes. kubernetes.io/docs/concepts/overview/working-with-objects （对象身份、期望状态与元数据管理的参考。）
Kubernetes, Deployments. kubernetes.io/docs/concepts/workloads/controllers/deployment （部署、滚动更新与回滚的参考机制；不等同于 Agent Deployment。）
Kubernetes, API Concepts. kubernetes.io/docs/reference/using-api/api-concepts （资源版本、并发与 API 操作背景。）
PostgreSQL, Documentation: Transactions. www.postgresql.org/docs/current/tutorial-transactions.html （原子事务与一致性基础。）
PostgreSQL, Documentation: Explicit Locking. www.postgresql.org/docs/current/explicit-locking.html （并发修改与锁语义。）
PostgreSQL, Documentation: Row Security Policies. www.postgresql.org/docs/current/ddl-rowsecurity.html （租户数据隔离的实现参考。）
IETF, HTTP Semantics (RFC 9110). www.rfc-editor.org/rfc/rfc9110.html （HTTP 条件请求与状态码语义。）
OpenAPI Initiative, OpenAPI Specification. spec.openapis.org/oas/latest.html （接口契约描述。）
NIST, Secure Software Development Framework (SP 800-218). csrc.nist.gov/pubs/sp/800/218/final （软件供应链和变更安全背景。）
SLSA, Supply-chain Levels for Software Artifacts. slsa.dev/spec （来源证明和构建工件完整性参考。）
Sigstore, Documentation. docs.sigstore.dev （签名和工件验证的实现参考。）
OWASP, Top 10 for LLM Applications. genai.owasp.org/llm-top-10 （Agent 配置与工具使用中的安全风险。）
NIST, AI Risk Management Framework 1.0. doi.org/10.6028/NIST.AI.100-1 （AI 系统治理和生命周期风险背景。）
Git, Documentation: git-tag. git-scm.com/docs/git-tag （不可变对象与可变引用的类比参考；Git 标签本身可以被强制移动。）
CNCF, CloudEvents Specification. github.com/cloudevents/spec （异步管理事件契约的参考。）

附录 B：研究证据、验证声明与适用边界

B.1 证据分级

有官方技术资料支撑：数据库事务与并发控制、HTTP 条件请求、Kubernetes 部署更新语义、权限与行级安全、软件供应链与 AI 风险治理的基本原理。
工程综合推论：Agent 五类状态拆分、七类产品功能、升级影响分析、管理操作状态机、Studio Agent 管理页、参考 API 和数据模型。
待验证假设：上述页面组织是否最适合 Studio 用户；默认版本固定策略是否符合所有业务场景；归档和停用操作是否足够容易理解；风险提示是否能有效降低误操作。

B.2 验证声明

本文未执行真实用户访谈、可用性测试、数据库迁移、Agent Registry 集成、部署演练、权限渗透测试、性能测试或故障注入。40 项测试是待执行验收设计，不代表实际测试结果。参考链接和产品能力应在正式实施前复核。

B.3 适用范围

适用于具有多个 Agent、长期维护、版本发布、跨项目引用和异步运行的 Agent Platform。对于单用户、一次性脚本式 Agent，可采用更轻量的版本和归档管理；对于受监管业务，需进一步评估法定保留、审批、审计与删除义务。

F9 · 用户如何管理 Agent 的版本与生命周期？ - Agent Management ​

专题导读 ​

研究结论 ​

01 · 定义与职责边界 ​

1.1 Agent Management 是什么？ ​

1.2 用户最容易混淆的五种“状态” ​

02 · 用户、任务与使用场景 ​

03 · 产品功能架构与信息架构 ​

3.1 建议的功能树 ​

3.2 Agent 列表 ​

3.3 Agent 详情页 ​

3.4 管理操作分级 ​

04 · 核心对象模型与关系 ​

4.1 推荐对象字段 ​

05 · 生命周期状态与操作语义 ​

5.1 Agent 身份生命周期 ​

5.2 操作影响范围 ​

06 · 版本历史、比较与升级 ​

6.1 版本历史页 ​

6.2 版本差异应如何呈现？ ​

6.3 升级流程 ​

6.4 回滚语义 ​

07 · 停用、恢复、弃用与撤销 ​

7.1 停用操作 ​

7.2 版本弃用与撤销 ​

7.3 恢复 ​

08 · 归档、删除、保留与恢复 ​

8.1 归档 ​

8.2 删除 ​

8.3 资产删除与历史证据的张力 ​

09 · 所有权、权限与协作维护 ​

9.1 管理权限矩阵（参考） ​

9.2 所有权转移 ​

9.3 多人维护与并发 ​

10 · 依赖关系与变更影响分析 ​

10.1 依赖图 ​

10.2 影响分析结果 ​

10.3 批量操作 ​

11 · 产品交互与异常反馈 ​

11.1 升级确认示例 ​

11.2 操作状态 ​

11.3 错误反馈原则 ​

12 · 技术架构映射 ​

13 · 参考 API 与数据契约 ​

13.1 API 资源与端点 ​

13.2 操作请求示例 ​

13.3 操作响应示例 ​

13.4 统一错误示例 ​

14 · 数据模型与事务设计 ​

14.1 原子渠道切换 ​

14.2 版本固定与一致性 ​

15 · Studio 贯穿案例 ​

15.1 场景 ​

15.2 一次完整升级 ​

15.3 Studio Agent 管理页草图（文字结构） ​

15.4 与 Studio 现有工作流的结合 ​

16 · 分阶段开发路线 ​

17 · 产品指标、可用性与评估 ​

18 · 风险、局限与反思 ​

19 · 工程与产品验证矩阵（待执行） ​

20 · 总结 ​

附录 A：参考文献与原始资料 ​

附录 B：研究证据、验证声明与适用边界 ​

B.1 证据分级 ​

B.2 验证声明 ​

B.3 适用范围 ​

F9 · 用户如何管理 Agent 的版本与生命周期？ - Agent Management

专题导读

研究结论

01 · 定义与职责边界

1.1 Agent Management 是什么？

1.2 用户最容易混淆的五种“状态”

02 · 用户、任务与使用场景

03 · 产品功能架构与信息架构

3.1 建议的功能树

3.2 Agent 列表

3.3 Agent 详情页

3.4 管理操作分级

04 · 核心对象模型与关系

4.1 推荐对象字段

05 · 生命周期状态与操作语义

5.1 Agent 身份生命周期

5.2 操作影响范围

06 · 版本历史、比较与升级

6.1 版本历史页

6.2 版本差异应如何呈现？

6.3 升级流程

6.4 回滚语义

07 · 停用、恢复、弃用与撤销

7.1 停用操作

7.2 版本弃用与撤销

7.3 恢复

08 · 归档、删除、保留与恢复

8.1 归档

8.2 删除

8.3 资产删除与历史证据的张力

09 · 所有权、权限与协作维护

9.1 管理权限矩阵（参考）

9.2 所有权转移

9.3 多人维护与并发

10 · 依赖关系与变更影响分析

10.1 依赖图

10.2 影响分析结果

10.3 批量操作

11 · 产品交互与异常反馈

11.1 升级确认示例

11.2 操作状态

11.3 错误反馈原则

12 · 技术架构映射

13 · 参考 API 与数据契约

13.1 API 资源与端点

13.2 操作请求示例

13.3 操作响应示例

13.4 统一错误示例

14 · 数据模型与事务设计

14.1 原子渠道切换

14.2 版本固定与一致性

15 · Studio 贯穿案例

15.1 场景

15.2 一次完整升级

15.3 Studio Agent 管理页草图（文字结构）

15.4 与 Studio 现有工作流的结合

16 · 分阶段开发路线

17 · 产品指标、可用性与评估

18 · 风险、局限与反思

19 · 工程与产品验证矩阵（待执行）

20 · 总结

附录 A：参考文献与原始资料

附录 B：研究证据、验证声明与适用边界

B.1 证据分级

B.2 验证声明

B.3 适用范围