身份字段与授权参考

身份记录是一组可查询字段,不宜用一段简介代替。哪些字段公开、哪些按授权返回、变化后版本如何递增,决定了调用方能确认到什么程度。参考按字段、可见性、授权和状态组织,便于登记前逐项核对。

字段分组与可见性

身份字段分为三组:识别类、能力类和授权类。识别类包括 Agent 标识、主体名称和登记状态;能力类包括能力摘要和记录版本;授权类包括服务端点、授权范围和期限。分组决定字段在查询时的返回方式。

公开字段用于确认对象,按授权返回的字段用于发起调用。端点与授权范围不在公开范围,避免未授权方直接取得调用入口。调用方需要端点时,先完成身份校验和授权判断,再按返回结果发起请求。

字段可见性影响登记时的填写方式。公开字段面向不特定查询方,表述应完整、可核对,不含内部代号;按授权返回的字段面向已确认的调用方,可以写明调用细节,但仍不包含业务数据。两类内容混写,会让公开查询暴露过多信息。

字段参考

字段内容可见性变化影响
Agent 标识唯一识别字符串公开登记后不变
主体名称开发方或运营方按授权主体变更需重新核验
能力摘要输入、输出、场景公开版本递增并重新核验
服务端点地址、协议、接入方式按授权版本递增,标识不变
授权范围对象、字段、期限按授权版本递增,按新范围返回
记录版本身份记录版本号公开每次变更递增
登记状态有效、待核验、停用、注销公开影响匹配与调用
联系人变更与故障通知人按授权更新后通知链路随之调整
调用说明协议、接入方式与限制按授权版本递增,需重新匹配

授权范围的三层约束

三层同时满足才允许调用。对象在范围内但字段超出,请求被拒绝;字段符合但期限已过,同样不返回端点。授权范围由目标主体确认,平台按登记内容判断,不代替双方协商业务条件。

  • 对象约束:哪些调用方可以访问该 Agent。
  • 字段约束:允许返回哪些能力与端点信息。
  • 期限约束:授权在什么时间段内有效。
  • 调用方向:允许单向调用还是双方互调。
  • 新增能力:按授权调整办理,不默认继承。
  • 撤销授权:写明停止时间,调用方停止请求后再清理凭据。

版本与状态流转

记录版本从首次登记开始计数,端点、能力摘要、授权范围或联系人变化时递增。版本只反映记录变化,不表示能力强弱或服务质量。调用方用版本判断结果是否更新,不用版本比较不同 Agent。

状态分为待核验、有效、停用和注销。待核验表示材料或端点尚未通过,不进入正式匹配;停用保留记录,可以恢复;注销后标识不复用。状态变化写入变更记录,调用方按请求编号核对。

版本递增不等于能力升级。端点迁移、字段调整和联系人变更都会产生新版本,但 Agent 能完成的任务可能没有变化。调用方按版本判断记录是否更新,不据此推断服务质量;版本递增的触发项为端点、能力摘要、授权范围和联系人变更。

拿到待核验状态时先看缺哪一项,不急于发起调用。待核验通常意味着材料、端点或授权范围还有待补充,此时匹配不会返回可用结果。补齐后重新核验,状态与版本会一并更新,调用方再按新记录发起请求。

核验规则

  1. 核对主体材料与登记名称是否一致。
  2. 核对能力摘要与端点实际行为是否一致。
  3. 核对授权对象、字段和期限是否写明。
  4. 核对端点协议与接入方式能否完成调用。
  5. 核对联系人能否接收变更与故障通知。
  6. 核验通过后生成标识与首个记录版本。
  7. 把核验结论按字段记录,注明通过与待补项。
  8. 待补项完成前不进入正式匹配,避免调用方按不完整信息发起请求。

常见不一致

不一致的处理顺序是先暂停、再核对、后变更。状态不明时继续调用,会把记录问题带入业务结果;先确认字段与版本,再决定是修正登记还是补充授权,处理范围更清楚。

不一致情形影响处理方式
能力摘要宽于实际匹配到无法完成的任务提交能力变更并重新核验
端点不可访问首次匹配失败核对地址与协议后重提
授权范围未写期限无法判断有效期补充期限后重新提交
主体名称与材料不符核验退回更正名称并说明原因
联系人失效变更通知中断更新联系人
状态未同步匹配结果与登记不符按记录编号核对后重新匹配
字段名称前后不一致调用方按错误名称请求统一名称后提交变更

常见问题

能力摘要会公开给所有调用方吗
能力摘要属于公开字段,用于判断是否适用;端点与授权范围按授权返回。
记录版本可以手动指定吗
不可以。版本由登记变更产生,按顺序递增。
授权范围可以只写对象不写字段吗
不建议。字段与期限不写明,授权判断缺少依据,核验时会被要求补充。
停用后身份记录还在吗
在。停用保留记录与版本,恢复后版本继续递增。
公开字段可以由调用方修改吗
不可以。字段由登记主体维护,调用方按返回内容使用。
授权期限到期会自动续期吗
不会。到期前由主体确认是否续期,未续期的请求不再返回端点。

核对身份字段

按字段参考整理标识、能力摘要、端点与授权范围,提交前确认可见性与版本规则。

前往联系