Files
UHD_Media_Tool/packages/contracts/src/agent.ts
T
rootandClaude Opus 5.5 414ea7c890 feat(智能体): 不设硬性预算上限,花费改为可见
- 去掉每天次数、每天花费、单次花费、单次 token 四个上限的拦截;设置项登记为弃用,旧值兼容读取、不生效
- 保留单次工具调用次数与时长两个防跑飞限制,缺省调宽(120 次 / 1800 秒,后台调查 20 次)
- 新增 GET /agent/usage:今天与最近 7 天按会话类型(对话 / 巡检 / 后台调查 / 整理识别 / 子会话)的次数、token 与费用
- 设置 agent.autoIdentifyOrganize(整理识别不到时叫智能体识别,缺省开)一并加在智能体设置里
- runner 里加整理识别会话的能力白名单与调查会话去重键解析(investigationDecisionId)

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01Cxwgnn2pbzQ7rXv3rq7fei
2026-10-06 16:47:18 +08:00

520 lines
19 KiB
TypeScript

import { z } from "zod";
import { AgentRunEventRow } from "./agent-events.ts";
import { KnownCapabilityId } from "./capability.ts";
import { EntityBase, Id, JsonObject, NonNegInt, SERVER_MANAGED, Timestamp } from "./common.ts";
// 人工/AI 域:Agent 运行、证据/计划产物、待处理事项、审批、持续授权(REQ §10、§11.3、§11.4)
export const AgentTrigger = z.enum(["user", "event", "schedule", "subagent"]);
export type AgentTrigger = z.infer<typeof AgentTrigger>;
export const AgentRunStatus = z.enum([
"queued",
"running",
"waiting",
"succeeded",
"failed",
"cancelled",
"budget_exceeded",
]);
export type AgentRunStatus = z.infer<typeof AgentRunStatus>;
/**
* 内部能力上限(agent_run.mode 列,不再出现在 API 与界面上):execute = 按白名单与授权执行;
* plan_only = 只允许 read/preview/propose 类能力(后台只读调查、只读子会话用)。
* 用户会话一律 execute;"先看方案再执行"是会话选项(scope.proposeFirst),见 AgentRunStartInput。
*/
export const AgentRunMode = z.enum(["execute", "plan_only"]);
export type AgentRunMode = z.infer<typeof AgentRunMode>;
/** 单次运行预算(调用次数/token/时长/费用,REQ §10.5) */
export const AgentBudget = z.object({
maxToolCalls: z.number().int().positive().optional(),
maxTokens: z.number().int().positive().optional(),
maxDurationSec: z.number().int().positive().optional(),
maxCostUsd: z.number().nonnegative().optional(),
});
export type AgentBudget = z.infer<typeof AgentBudget>;
export const AgentUsage = z.object({
inputTokens: NonNegInt.optional(),
outputTokens: NonNegInt.optional(),
cacheReadTokens: NonNegInt.optional(),
cacheWriteTokens: NonNegInt.optional(),
totalTokens: NonNegInt.optional(),
costUsd: z.number().nonnegative().optional(),
durationMs: NonNegInt.optional(),
});
export type AgentUsage = z.infer<typeof AgentUsage>;
export const AgentRun = EntityBase.extend({
taskId: Id.nullable(),
parentRunId: Id.nullable(),
trigger: AgentTrigger,
goal: z.string().min(1),
status: AgentRunStatus,
provider: z.string().nullable(),
model: z.string().nullable(),
thinkingLevel: z.string().nullable(),
/** 授权范围(能力白名单、对象范围);子代理继承父任务上限 */
scope: JsonObject,
budget: AgentBudget,
usage: AgentUsage,
evidenceVersion: z.string().nullable(),
/** Pi 会话持久化状态;不对普通列表返回 */
sessionState: JsonObject.nullable(),
summary: z.string().nullable(),
toolCallCount: NonNegInt,
lastEventSeq: NonNegInt,
error: JsonObject.nullable(),
cancelRequestedAt: Timestamp.nullable(),
startedAt: Timestamp.nullable(),
finishedAt: Timestamp.nullable(),
createdBy: z.string().nullable(),
/** 后台触发按根因去重(如 investigate:<decisionId>);用户委托为 null */
dedupeKey: z.string().nullable(),
/** 派生深度:用户/后台发起的会话为 0,agent.spawn 派生的子会话 = 父 + 1 */
depth: NonNegInt,
/** 父会话派生时给的理由 */
spawnReason: z.string().nullable(),
});
export type AgentRun = z.infer<typeof AgentRun>;
export const AgentRunCreate = AgentRun.pick({
taskId: true,
parentRunId: true,
trigger: true,
goal: true,
scope: true,
budget: true,
}).partial({ taskId: true, parentRunId: true, trigger: true, scope: true, budget: true });
export type AgentRunCreate = z.infer<typeof AgentRunCreate>;
export const AgentRunUpdate = AgentRun.pick({
status: true,
provider: true,
model: true,
thinkingLevel: true,
usage: true,
evidenceVersion: true,
sessionState: true,
summary: true,
toolCallCount: true,
lastEventSeq: true,
error: true,
startedAt: true,
finishedAt: true,
}).partial();
export type AgentRunUpdate = z.infer<typeof AgentRunUpdate>;
export const ArtifactKind = z.enum(["evidence", "plan", "proposal", "report", "snapshot", "log"]);
export type ArtifactKind = z.infer<typeof ArtifactKind>;
/** 证据/计划/提案产物:提案不直接晋升为事实 */
export const Artifact = EntityBase.extend({
kind: ArtifactKind,
agentRunId: Id.nullable(),
taskId: Id.nullable(),
subjectType: z.string().nullable(),
subjectId: Id.nullable(),
title: z.string().min(1),
mimeType: z.string(),
content: JsonObject,
contentHash: z.string().min(1),
sizeBytes: NonNegInt.nullable(),
expiresAt: Timestamp.nullable(),
});
export type Artifact = z.infer<typeof Artifact>;
/** contentHash / sizeBytes 由服务端计算 */
export const ArtifactCreate = Artifact.omit({ ...SERVER_MANAGED, contentHash: true, sizeBytes: true }).partial({
agentRunId: true,
taskId: true,
subjectType: true,
subjectId: true,
mimeType: true,
expiresAt: true,
});
export type ArtifactCreate = z.infer<typeof ArtifactCreate>;
/** 产物内容不可变;只能调整过期时间 */
export const ArtifactUpdate = z.object({ expiresAt: Timestamp.nullable() });
export type ArtifactUpdate = z.infer<typeof ArtifactUpdate>;
export const DecisionKind = z.enum([
"identity_ambiguous",
"download_stalled",
"download_failed",
"path_conflict",
"space_insufficient",
"approval_required",
"metadata_conflict",
"source_unreachable",
"other",
/** 待识别资源没有可选候选(no_match / 复查耗尽的查询失败):手动指定 TMDB id、选本地作品或忽略 */
"identity_unresolved",
/** 资源已绑定作品但集数待确认(无法换算 / 映射规则失效):按作品 + 来源季 + 发布组合并,附建议规则 */
"episode_mapping",
/** 下载器连续不可达超过一段时间(按实例去重,恢复后自动关闭) */
"downloader_offline",
/** 下载目录读不到容量(路径映射 / 挂载问题,按卷去重,恢复后自动关闭) */
"cache_volume_unknown",
]);
export type DecisionKind = z.infer<typeof DecisionKind>;
export const DecisionStatus = z.enum(["open", "investigating", "awaiting_user", "resolved", "dismissed", "expired"]);
export type DecisionStatus = z.infer<typeof DecisionStatus>;
export const Severity = z.enum(["info", "warning", "critical"]);
export type Severity = z.infer<typeof Severity>;
export const DecisionOption = z.object({
key: z.string().min(1),
label: z.string().min(1),
description: z.string().optional(),
/** 选择后执行的能力与参数(仍经授权校验) */
capabilityId: z.string().optional(),
input: JsonObject.optional(),
});
export type DecisionOption = z.infer<typeof DecisionOption>;
/** 待处理中心条目;同一 dedupeKey 同时只有一个未关闭条目 */
export const Decision = EntityBase.extend({
kind: DecisionKind,
status: DecisionStatus,
severity: Severity,
title: z.string().min(1),
summary: z.string().nullable(),
subjectType: z.string().nullable(),
subjectId: Id.nullable(),
dedupeKey: z.string().min(1),
evidence: JsonObject,
options: z.array(DecisionOption),
resolution: JsonObject.nullable(),
taskId: Id.nullable(),
agentRunId: Id.nullable(),
attempts: NonNegInt,
nextReviewAt: Timestamp.nullable(),
resolvedBy: z.string().nullable(),
resolvedAt: Timestamp.nullable(),
});
export type Decision = z.infer<typeof Decision>;
export const DecisionCreate = Decision.pick({
kind: true,
severity: true,
title: true,
summary: true,
subjectType: true,
subjectId: true,
dedupeKey: true,
evidence: true,
options: true,
taskId: true,
agentRunId: true,
nextReviewAt: true,
}).partial({
severity: true,
summary: true,
subjectType: true,
subjectId: true,
evidence: true,
options: true,
taskId: true,
agentRunId: true,
nextReviewAt: true,
});
export type DecisionCreate = z.infer<typeof DecisionCreate>;
export const DecisionUpdate = Decision.pick({
status: true,
severity: true,
summary: true,
evidence: true,
options: true,
agentRunId: true,
nextReviewAt: true,
}).partial();
export type DecisionUpdate = z.infer<typeof DecisionUpdate>;
/** 用户处理待处理事项:选一个选项或关闭 */
export const DecisionResolveInput = z.object({
optionKey: z.string().min(1).optional(),
dismiss: z.boolean().optional(),
note: z.string().max(2000).optional(),
/**
* 身份类事项的手动指定(选项 input.requires 标明需要哪一项):
* requires=tmdb → tmdb {type, id};requires=mediaEntityId → mediaEntityId
*/
identity: z
.object({
mediaEntityId: Id.optional(),
tmdb: z
.object({
type: z.enum(["movie", "tv"]),
id: z
.string()
.trim()
.regex(/^\d{1,10}$/),
})
.optional(),
})
.optional(),
});
export type DecisionResolveInput = z.infer<typeof DecisionResolveInput>;
export const ApprovalStatus = z.enum(["pending", "approved", "rejected", "revoked", "expired", "consumed"]);
export type ApprovalStatus = z.infer<typeof ApprovalStatus>;
/** 单次审批:绑定 planType+planId + payloadHash + expectedRevision;换候选/路径后旧审批失效 */
export const Approval = EntityBase.extend({
planType: z.string().min(1),
planId: Id,
payloadHash: z.string().min(1),
expectedRevision: z.number().int().min(0),
scope: JsonObject,
status: ApprovalStatus,
decisionId: Id.nullable(),
requestedBy: z.string().min(1),
decidedBy: z.string().nullable(),
decidedAt: Timestamp.nullable(),
expiresAt: Timestamp.nullable(),
reason: z.string().nullable(),
});
export type Approval = z.infer<typeof Approval>;
export const ApprovalCreate = Approval.pick({
planType: true,
planId: true,
payloadHash: true,
expectedRevision: true,
scope: true,
decisionId: true,
requestedBy: true,
expiresAt: true,
reason: true,
}).partial({ scope: true, decisionId: true, expiresAt: true, reason: true });
export type ApprovalCreate = z.infer<typeof ApprovalCreate>;
/** 批准/拒绝时回传 payloadHash,服务端比对防止审批被挪用到变更后的计划 */
export const ApprovalUpdate = z.object({
status: z.enum(["approved", "rejected", "revoked"]),
payloadHash: z.string().min(1),
reason: z.string().max(2000).optional(),
});
export type ApprovalUpdate = z.infer<typeof ApprovalUpdate>;
export const GrantStatus = z.enum(["active", "revoked", "expired"]);
export type GrantStatus = z.infer<typeof GrantStatus>;
/** 持续授权:绑定策略版本、动作、对象范围与预算 */
export const AutomationGrant = EntityBase.extend({
action: z.string().min(1),
policyRevisionId: Id.nullable(),
scope: JsonObject,
budget: JsonObject,
status: GrantStatus,
grantedBy: z.string().min(1),
reason: z.string().nullable(),
expiresAt: Timestamp.nullable(),
revokedAt: Timestamp.nullable(),
revokedBy: z.string().nullable(),
});
export type AutomationGrant = z.infer<typeof AutomationGrant>;
export const AutomationGrantCreate = AutomationGrant.pick({
action: true,
policyRevisionId: true,
scope: true,
budget: true,
reason: true,
expiresAt: true,
}).partial({ policyRevisionId: true, scope: true, budget: true, reason: true, expiresAt: true });
export type AutomationGrantCreate = z.infer<typeof AutomationGrantCreate>;
/** 只能撤销或缩短有效期,不能就地扩大范围(扩大 = 新授权) */
export const AutomationGrantUpdate = z.object({
status: z.literal("revoked").optional(),
expiresAt: Timestamp.nullable().optional(),
reason: z.string().max(2000).optional(),
});
export type AutomationGrantUpdate = z.infer<typeof AutomationGrantUpdate>;
// ── Agent 会话 API(W2-D) ──
/** POST /agent/runs:建 agent_run + 入队持久任务 runAgent(不在 HTTP 请求里跑模型) */
export const AgentRunStartInput = z.object({
goal: z.string().trim().min(1).max(8000),
/**
* 先看方案再执行:模型先调查,用 agent.propose_options 给方案,用户选定前服务端拒绝有副作用的执行类能力。
* 缺省关(自动化优先:按步骤清单直接执行,需授权的动作在步骤处审批)。
*/
proposeFirst: z.boolean().default(false),
/** @deprecated 已取消运行模式;plan_only 按 proposeFirst=true 处理,execute 忽略 */
mode: AgentRunMode.optional().describe("已弃用:plan_only 等同 proposeFirst=true"),
/** 能力白名单(缺省全部可用能力) */
capabilityAllowlist: z.array(KnownCapabilityId).min(1).max(50).optional(),
});
export type AgentRunStartInput = z.infer<typeof AgentRunStartInput>;
export const AgentRunMessageInput = z.object({ text: z.string().trim().min(1).max(8000) });
export type AgentRunMessageInput = z.infer<typeof AgentRunMessageInput>;
/**
* 回答 agent.propose_options:选一个方案(optionId),或都不要(optionId=null,reason 写原因)。
* 会话挂起在这个问题上;回答后会话从这里继续。
*/
export const AgentRunChoiceInput = z.object({
decisionId: Id,
optionId: z.string().min(1).max(40).nullable(),
reason: z.string().trim().max(1000).optional(),
});
export type AgentRunChoiceInput = z.infer<typeof AgentRunChoiceInput>;
export const AgentRunAbortInput = z.object({ reason: z.string().max(500).optional() });
export type AgentRunAbortInput = z.infer<typeof AgentRunAbortInput>;
/**
* 智能体用量(2026-10-06 起不设硬性预算上限,花费改为可见):按会话类型统计次数、token 与费用。
* chat = 用户对话;patrol = 智能体巡检;investigate = 待处理事项的后台调查 / 授权内恢复;
* organize_identify = 整理没识别出作品时的智能体识别;subagent = 子会话
*/
export const AgentSpendKind = z.enum(["chat", "patrol", "investigate", "organize_identify", "subagent"]);
export type AgentSpendKind = z.infer<typeof AgentSpendKind>;
export const AgentSpendBucket = z.object({
runs: NonNegInt,
tokens: NonNegInt,
costUsd: z.number().min(0),
byKind: z.array(z.object({ kind: AgentSpendKind, runs: NonNegInt, tokens: NonNegInt, costUsd: z.number().min(0) })),
});
export type AgentSpendBucket = z.infer<typeof AgentSpendBucket>;
export const AgentSpend = z.object({ today: AgentSpendBucket, last7d: AgentSpendBucket });
export type AgentSpend = z.infer<typeof AgentSpend>;
export const AgentRunListQuery = z.object({
cursor: z.string().min(1).optional(),
limit: z.coerce.number().int().min(1).max(200).default(50),
status: AgentRunStatus.optional(),
trigger: AgentTrigger.optional(),
/** auto = 定时巡检 / 事件触发的会话(及其子会话);conversation = 用户发起的会话(及其子会话) */
group: z.enum(["conversation", "auto"]).optional(),
/** 只列某个会话直接派生的子会话 */
parentRunId: Id.optional(),
});
export type AgentRunListQuery = z.infer<typeof AgentRunListQuery>;
/** 详情里的事件分页:afterSeq(不含)之后按 seq 升序;断线后按最后收到的 runSeq 补读 */
export const AgentRunDetailQuery = z.object({
afterSeq: z.coerce.number().int().min(-1).default(-1),
limit: z.coerce.number().int().min(1).max(1000).default(200),
});
export type AgentRunDetailQuery = z.infer<typeof AgentRunDetailQuery>;
/**
* 目标完成度汇报:由服务端从业务表汇总(下载计划 → 下载任务 → 整理记录),不采信模型文本。
* "已提交"只代表进入下载器;只有整理记录 succeeded 才算入库。
*/
export const AgentGoalReport = z.object({
state: z.enum(["no_actions", "waiting", "completed", "partial", "failed"]),
summary: z.string(),
submitted: NonNegInt,
imported: NonNegInt,
inProgress: NonNegInt,
failed: NonNegInt,
plans: z.array(z.object({ planId: Id, status: z.string(), slotId: Id.nullable(), sourceReleaseId: Id.nullable() })),
downloads: z.array(
z.object({ downloadTaskId: Id, planId: Id.nullable(), status: z.string(), name: z.string().nullable() }),
),
organization: z.array(
z.object({
recordId: Id,
status: z.string(),
downloadTaskId: Id.nullable(),
mediaEntityId: Id.nullable(),
targetPath: z.string().nullable(),
}),
),
/** 模型最终文本(仅供参考,不作为完成依据) */
modelText: z.string().nullable(),
generatedAt: Timestamp,
});
export type AgentGoalReport = z.infer<typeof AgentGoalReport>;
export const AgentRunMessageStatus = z.enum(["pending", "consumed"]);
export type AgentRunMessageStatus = z.infer<typeof AgentRunMessageStatus>;
/** 追加到会话的用户消息(纠正/补充);runAgent 任务按创建顺序消费 */
export const AgentRunMessage = EntityBase.extend({
runId: Id,
text: z.string(),
status: AgentRunMessageStatus,
createdBy: z.string().nullable(),
consumedAt: Timestamp.nullable(),
});
export type AgentRunMessage = z.infer<typeof AgentRunMessage>;
/** 会话树节点(父会话 / 子会话,子会话页与父会话页互相跳转) */
export const AgentRunNode = z.object({
id: Id,
parentRunId: Id.nullable(),
goal: z.string(),
status: AgentRunStatus,
depth: NonNegInt,
spawnReason: z.string().nullable(),
toolCallCount: NonNegInt,
usage: AgentUsage,
summary: z.string().nullable(),
/** 能力白名单(继承信息展示) */
capabilities: z.array(z.string()),
budget: AgentBudget,
createdAt: Timestamp,
finishedAt: Timestamp.nullable(),
});
export type AgentRunNode = z.infer<typeof AgentRunNode>;
/** 本会话 + 全部子孙会话的用量合计(父会话总预算含子会话用量) */
export const AgentFamilyUsage = z.object({
runs: NonNegInt,
toolCalls: NonNegInt,
totalTokens: NonNegInt,
costUsd: z.number().nonnegative(),
});
export type AgentFamilyUsage = z.infer<typeof AgentFamilyUsage>;
export const AgentRunDetail = z.object({
run: AgentRun,
/** 父会话(子会话才有) */
parent: AgentRunNode.nullable().optional(),
/** 全部子孙会话(扁平,按 parentRunId 组树) */
children: z.array(AgentRunNode).optional(),
familyUsage: AgentFamilyUsage.optional(),
events: z.array(AgentRunEventRow),
/** 下一页起点(传给 afterSeq);null 表示已到最新 */
nextAfterSeq: z.number().int().nullable(),
messages: z.array(AgentRunMessage),
report: AgentGoalReport.nullable(),
});
export type AgentRunDetail = z.infer<typeof AgentRunDetail>;
/** 单次审批的创建:服务端从计划读取 payloadHash / expectedRevision,调用方只给计划 */
export const ApprovalRequest = z.object({
planType: z.enum(["acquisition_plan", "organize_plan", "policy_revision"]),
planId: Id,
expiresInSec: z
.number()
.int()
.min(60)
.max(30 * 86400)
.default(86400),
reason: z.string().max(2000).optional(),
});
export type ApprovalRequest = z.infer<typeof ApprovalRequest>;
export const CapabilityInvocationStatus = z.enum(["running", "succeeded", "failed"]);
export type CapabilityInvocationStatus = z.infer<typeof CapabilityInvocationStatus>;
/**
* 有副作用能力的操作账本(capability_invocation):幂等键由服务端生成且唯一;succeeded 直接返回记录的输出,
* running(调用中崩溃)按同一幂等键重跑处理器对账。
*/
export const CapabilityInvocation = EntityBase.extend({
idempotencyKey: z.string().min(1),
capabilityId: z.string().min(1),
capabilityVersion: z.number().int().min(1),
agentRunId: Id.nullable(),
actorId: z.string(),
source: z.string(),
status: CapabilityInvocationStatus,
input: JsonObject,
output: JsonObject.nullable(),
error: JsonObject.nullable(),
grantId: Id.nullable(),
approvalId: Id.nullable(),
attempts: NonNegInt,
finishedAt: Timestamp.nullable(),
});
export type CapabilityInvocation = z.infer<typeof CapabilityInvocation>;