rootandClaude Opus 5.5
fb84a71f80
Auto-fix of 602 string literals across 74 files (half-width punctuation next to Chinese, parenthesised Chinese, quotes); biome reflow; e2/e6 assertions follow the new full-width summaries. check:copy now runs with --strict in ci. Co-Authored-By: Claude Opus 5.5 <[email protected]>
495 lines
17 KiB
TypeScript
495 lines
17 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",
|
|
]);
|
|
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>;
|
|
|
|
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(),
|
|
/** 只列某个会话直接派生的子会话 */
|
|
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>;
|