feat(agent): subscription.list, decision.list, download.inspect; grant-scoped requiresApproval

- three read-only summary capabilities (38 registered); task.inspect points
  download task ids to download.inspect
- probe queries reject empty / single-letter / wildcard-only terms; externalId
  documented as string; every description says when to use it
- download.plan requiresApproval uses coveringGrant (shared with authorize)

Co-Authored-By: Claude Opus 5.5 <[email protected]>

packages/contracts/src/capabilities-io.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { DecisionKind, DecisionOption, DecisionStatus, Severity } from "./agent.ts";
 import { AgentOptionItem, AgentPlanStep, AgentPlanStepStatus } from "./agent-events.ts";
 import { MediaAsset } from "./assets.ts";
 import { BrowserController, BrowserDownloadVerification, BrowserSnapshot } from "./browser.ts";
@@ -9,7 +10,14 @@ import { AcquisitionPlan, DownloadStatus, DownloadTask, Task, TaskStatus } from
 import { ExternalEntityType, ExternalIdentity } from "./identity.ts";
 import { ServerMapping } from "./ops.ts";
 import { OrganizationAction, OrganizationRecord } from "./organization.ts";
-import { AcquisitionSlot, PolicyRevision } from "./policy.ts";
+import {
+  AcquisitionPriority,
+  AcquisitionSlot,
+  PolicyRevision,
+  SubscriptionMediaKind,
+  SubscriptionMode,
+  SubscriptionStatus,
+} from "./policy.ts";
 import {
   SiteAccountError,
   SiteAccountOverall,
@@ -30,14 +38,33 @@ import {
 
 const Limit = z.number().int().min(1).max(100).default(20);
 
+/**
+ * 探查用检索词(AG-3):去掉首尾空白后不能为空,不能是单个英文字母/数字/符号(如 "a"、"*"),
+ * 不能只有通配符与标点——这类查询只会拉回全表或噪声,浪费预算。中文单字片名(如「家」)允许。
+ */
+export const ProbeQuery = z
+  .string()
+  .trim()
+  .min(1)
+  .max(200)
+  .refine((v) => !/^[ -~]$/.test(v), { message: "检索词太短：写作品名、别名或关键词，不要用单个字母或符号探查" })
+  .refine((v) => !/^[\s*%?._\-+/\\|,;:!'"()[\]{}]+$/.test(v), { message: "检索词不能只有通配符或标点" })
+  .describe("作品名、别名或关键词（至少一个完整词）；不要用空串、单个字母或通配符探查");
+
 /** 写能力的通用受理结果:返回 task/plan ID,由任务页追踪(REQ §12.3) */
 export const Accepted = z.object({ taskId: Id, planId: Id.nullable() });
 export type Accepted = z.infer<typeof Accepted>;
 
 export const CatalogLookupInput = z
   .object({
-    query: z.string().min(1).max(200).optional(),
-    externalId: z.object({ provider: z.string(), entityType: ExternalEntityType, externalId: z.string() }).optional(),
+    query: ProbeQuery.optional(),
+    externalId: z
+      .object({
+        provider: z.string().describe("如 tmdb、imdb、tvdb"),
+        entityType: ExternalEntityType,
+        externalId: z.string().describe('外部 ID 一律写成字符串，如 "693134"、"tt15239678"'),
+      })
+      .optional(),
     kind: MediaKind.optional(),
     year: z.number().int().optional(),
     includeRemote: z.boolean().default(false),
@@ -62,7 +89,7 @@ export const CatalogLookupOutput = z.object({
 });
 
 export const ReleaseSearchInput = z.object({
-  query: z.string().min(1).max(200).optional(),
+  query: ProbeQuery.optional(),
   mediaEntityId: Id.optional(),
   siteIds: z.array(Id).optional(),
   /** 本地快照不足时是否实时补查 */
@@ -188,7 +215,8 @@ export const PolicyApplyOutput = z.object({ policy: PolicyRevision });
 
 export const InventoryQueryInput = z.object({
   mediaEntityId: Id.optional(),
-  query: z.string().max(200).optional(),
+  /** 不给 query 也不给 mediaEntityId 时按最近更新列出 */
+  query: ProbeQuery.optional(),
   includeServerInventory: z.boolean().default(false),
   limit: Limit,
 });
@@ -205,6 +233,93 @@ export const InventoryQueryOutput = z.object({
   ),
 });
 
+// ── AG-3 只读摘要 ──
+
+const oneOrMany = <T extends z.ZodType>(t: T) =>
+  z.union([t, z.array(t).min(1).max(10)]).transform((v) => (Array.isArray(v) ? v : [v]) as z.infer<T>[]);
+
+export const SubscriptionListInput = z.object({
+  /** 缺省列出全部状态 */
+  status: oneOrMany(SubscriptionStatus).optional(),
+  mediaKind: SubscriptionMediaKind.optional(),
+  /** 按作品标题 / 检索词过滤 */
+  query: ProbeQuery.optional(),
+  groupBy: z.enum(["status", "mediaKind", "none"]).default("status"),
+  limit: z.number().int().min(1).max(200).default(50),
+});
+export const SubscriptionBrief = z.object({
+  id: Id,
+  title: z.string().nullable(),
+  mediaEntityId: Id.nullable(),
+  mediaKind: SubscriptionMediaKind,
+  mode: SubscriptionMode,
+  status: SubscriptionStatus,
+  priority: AcquisitionPriority,
+  statusReason: z.string().nullable(),
+  /** 版本目标:总数 / 已满足数 */
+  slots: z.object({ total: NonNegInt, satisfied: NonNegInt }),
+  lastSearchedAt: z.string().nullable(),
+  nextSearchAt: z.string().nullable(),
+  lastProgressAt: z.string().nullable(),
+});
+export const SubscriptionListOutput = z.object({
+  /** 过滤后的总数(items 可能被 limit 截断) */
+  total: NonNegInt,
+  groups: z.array(z.object({ key: z.string(), count: NonNegInt })),
+  items: z.array(SubscriptionBrief),
+});
+
+export const DecisionListInput = z.object({
+  /** 缺省只列未关闭的:open / investigating / awaiting_user */
+  status: oneOrMany(DecisionStatus).optional(),
+  kind: oneOrMany(DecisionKind).optional(),
+  limit: z.number().int().min(1).max(100).default(20),
+});
+export const DecisionBrief = z.object({
+  id: Id,
+  kind: DecisionKind,
+  status: DecisionStatus,
+  severity: Severity,
+  title: z.string(),
+  summary: z.string().nullable(),
+  subjectType: z.string().nullable(),
+  subjectId: z.string().nullable(),
+  attempts: NonNegInt,
+  options: z.array(DecisionOption),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+});
+export const DecisionListOutput = z.object({
+  total: NonNegInt,
+  byKind: z.array(z.object({ kind: DecisionKind, count: NonNegInt })),
+  items: z.array(DecisionBrief),
+});
+
+export const DownloadInspectInput = z
+  .object({
+    downloadTaskId: Id.optional(),
+    /** 种子 infohash(v1 40 位 / v2 64 位十六进制,大小写均可) */
+    hash: z
+      .string()
+      .trim()
+      .regex(/^[0-9a-fA-F]{40}$|^[0-9a-fA-F]{64}$/)
+      .optional(),
+  })
+  .refine((v) => !!v.downloadTaskId || !!v.hash, { message: "downloadTaskId 与 hash 至少给一个" });
+export const DownloadInspectOutput = z.object({
+  downloadTask: DownloadTask,
+  plan: z
+    .object({ id: Id, status: z.string(), statusReason: z.string().nullable(), slotId: Id, taskId: Id.nullable() })
+    .nullable(),
+  release: z.object({ id: Id, title: z.string(), siteId: Id.nullable() }).nullable(),
+  /** 关联业务任务(提交下载 / 核验入库):任务 ID 可交给 task.inspect / task.retry */
+  tasks: z.array(z.object({ id: Id, kind: z.string(), status: TaskStatus, lastError: JsonObject.nullable() })),
+  organization: z.array(z.object({ id: Id, status: z.string(), targetPath: z.string().nullable() })),
+  decisions: z.array(z.object({ id: Id, kind: DecisionKind, status: DecisionStatus, title: z.string() })),
+  /** 按 hash 查到多个下载器实例里的同一种子时,其余任务的 ID */
+  otherMatches: z.array(Id),
+});
+
 // ── 子代理(W7-B) ──
 
 /** 子会话预算:缺省按父会话剩余预算的一半划拨;超过剩余预算直接拒绝 */
@@ -220,7 +335,9 @@ export const AgentSpawnInput = z.object({
   reason: z.string().max(500).optional(),
   /** 必须是父会话能力白名单的子集;缺省继承父会话白名单 */
   capabilityAllowlist: z.array(z.string()).min(1).max(50).optional(),
-  budget: SubagentBudget.optional(),
+  budget: SubagentBudget.describe(
+    "各项都不能超过本会话剩余预算（工具调用、token、费用、时长），超过直接拒绝；不给则按剩余的一半划拨",
+  ).optional(),
   /** 不得高于父会话:plan_only 的父会话只能派生 plan_only 子会话;缺省同父会话 */
   mode: z.enum(["execute", "plan_only"]).optional(),
   /** 覆盖子会话使用的 Agent 上游;缺省同父会话 */
@@ -688,6 +805,9 @@ export const CAPABILITY_IO = {
   "policy.preview": { input: PolicyPreviewInput, output: PolicyPreviewOutput },
   "policy.apply": { input: PolicyApplyInput, output: PolicyApplyOutput },
   "inventory.query": { input: InventoryQueryInput, output: InventoryQueryOutput },
+  "subscription.list": { input: SubscriptionListInput, output: SubscriptionListOutput },
+  "decision.list": { input: DecisionListInput, output: DecisionListOutput },
+  "download.inspect": { input: DownloadInspectInput, output: DownloadInspectOutput },
   "agent.spawn": { input: AgentSpawnInput, output: AgentSpawnOutput },
   "agent.await": { input: AgentAwaitInput, output: AgentAwaitOutput },
   "site.list": { input: SiteListInput, output: SiteListOutput },
@@ -757,6 +877,12 @@ export type PolicyApplyInput = z.infer<typeof PolicyApplyInput>;
 export type PolicyApplyOutput = z.infer<typeof PolicyApplyOutput>;
 export type InventoryQueryInput = z.infer<typeof InventoryQueryInput>;
 export type InventoryQueryOutput = z.infer<typeof InventoryQueryOutput>;
+export type SubscriptionListInput = z.infer<typeof SubscriptionListInput>;
+export type SubscriptionListOutput = z.infer<typeof SubscriptionListOutput>;
+export type DecisionListInput = z.infer<typeof DecisionListInput>;
+export type DecisionListOutput = z.infer<typeof DecisionListOutput>;
+export type DownloadInspectInput = z.infer<typeof DownloadInspectInput>;
+export type DownloadInspectOutput = z.infer<typeof DownloadInspectOutput>;
 export type AgentSpawnInput = z.infer<typeof AgentSpawnInput>;
 export type AgentSpawnOutput = z.infer<typeof AgentSpawnOutput>;
 export type AgentAwaitInput = z.infer<typeof AgentAwaitInput>;

packages/contracts/src/capability.ts

@@ -66,6 +66,9 @@ export const CAPABILITY_IDS = [
   "policy.preview",
   "policy.apply",
   "inventory.query",
+  "subscription.list",
+  "decision.list",
+  "download.inspect",
   "agent.spawn",
   "agent.await",
   "site.list",
@@ -129,7 +132,7 @@ export const CAPABILITY_CATALOG: Record<KnownCapabilityId, CapabilityDescriptor>
   "catalog.lookup": d(
     "catalog.lookup",
     "查作品",
-    "按标题/别名/外部 ID 查本地作品与元数据候选",
+    "按标题/别名/外部 ID 查本地作品与元数据候选。确认作品身份、拿作品 ID 时用；查库里已有文件与版本目标用 inventory.query",
     "read",
     "CatalogLookup",
     "read",
@@ -140,7 +143,7 @@ export const CAPABILITY_CATALOG: Record<KnownCapabilityId, CapabilityDescriptor>
   "release.search": d(
     "release.search",
     "搜资源",
-    "先查本地资源索引与站点快照，不足时对已开启站点实时补查",
+    "先查本地资源索引与站点快照，不足时对已开启站点实时补查。找可下载的资源时用，检索词写作品名或关键词；已知作品时优先传 mediaEntityId",
     "read",
     "ReleaseSearch",
     "read",
@@ -151,7 +154,7 @@ export const CAPABILITY_CATALOG: Record<KnownCapabilityId, CapabilityDescriptor>
   "release.inspect": d(
     "release.inspect",
     "看资源详情",
-    "读取资源详情、文件清单、促销与解析结果",
+    "读取资源详情、文件清单、促销与解析结果。看某条资源的文件清单、促销或解析细节时用；不要逐条遍历搜索结果",
     "read",
     "ReleaseInspect",
     "read",
@@ -162,7 +165,7 @@ export const CAPABILITY_CATALOG: Record<KnownCapabilityId, CapabilityDescriptor>
   "identity.resolve": d(
     "identity.resolve",
     "识别身份",
-    "为观察/资源提出身份映射；证据充分时自动接受，有歧义时转为待处理事项",
+    "为观察/资源提出身份映射；证据充分时自动接受，有歧义时转为待处理事项。资源 / 观察还没对上作品时用；已识别的资源不要重复提交",
     "propose",
     "IdentityResolve",
     "organize.execute",
@@ -173,7 +176,7 @@ export const CAPABILITY_CATALOG: Record<KnownCapabilityId, CapabilityDescriptor>
   "download.plan": d(
     "download.plan",
     "生成下载计划",
-    "评估候选，生成占用版本目标(slot)与预算预留的下载计划；不提交",
+    "评估候选，生成占用版本目标(slot)与预算预留的下载计划；不提交。选定资源后、提交前用；不会提交下载，也不预留版本目标",
     "preview",
     "DownloadPlan",
     "organize.execute",
@@ -184,7 +187,7 @@ export const CAPABILITY_CATALOG: Record<KnownCapabilityId, CapabilityDescriptor>
   "download.submit": d(
     "download.submit",
     "提交下载",
-    "按已保存的计划提交到下载器；校验授权与硬阈值",
+    "按已保存的计划提交到下载器；校验授权与硬阈值。只提交 download.plan 生成的计划；结果未知时先用 download.inspect / task.inspect 核对，不要重复提交",
     "execute",
     "DownloadSubmit",
     "organize.execute",
@@ -195,7 +198,7 @@ export const CAPABILITY_CATALOG: Record<KnownCapabilityId, CapabilityDescriptor>
   "download.recheck": d(
     "download.recheck",
     "重新校验/恢复下载",
-    "对已纳管的下载任务强制重新校验(action=recheck)，或恢复非阈值、非人工的暂停(action=resume)；不换源、不删除、不改保存路径",
+    "对已纳管的下载任务强制重新校验(action=recheck)，或恢复非阈值、非人工的暂停(action=resume)；不换源、不删除、不改保存路径。下载失败或文件缺失时用；换源、删除不在此能力内",
     "execute",
     "DownloadRecheck",
     "organize.execute",
@@ -206,7 +209,7 @@ export const CAPABILITY_CATALOG: Record<KnownCapabilityId, CapabilityDescriptor>
   "organize.plan": d(
     "organize.plan",
     "生成整理计划",
-    "生成并保存整理计划：冻结源/目标路径、整理方式与前置条件；不执行",
+    "生成并保存整理计划：冻结源/目标路径、整理方式与前置条件；不执行。下载完成后整理入库前用；只生成计划不动文件",
     "preview",
     "OrganizePlan",
     "organize.read",
@@ -217,7 +220,7 @@ export const CAPABILITY_CATALOG: Record<KnownCapabilityId, CapabilityDescriptor>
   "organize.execute": d(
     "organize.execute",
     "执行整理",
-    "执行已保存的整理计划（复制/移动），生成整理记录",
+    "执行已保存的整理计划（复制/移动），生成整理记录。只执行 organize.plan 生成且指纹未变的计划；指纹不一致时重新生成计划",
     "execute",
     "OrganizeExecute",
     "organize.execute",
@@ -228,7 +231,7 @@ export const CAPABILITY_CATALOG: Record<KnownCapabilityId, CapabilityDescriptor>
   "task.inspect": d(
     "task.inspect",
     "查看任务",
-    "读取任务状态、业务时间线与错误",
+    "读取任务状态、业务时间线与错误。按业务任务 ID 查看；下载任务 ID 或种子 hash 用 download.inspect",
     "read",
     "TaskInspect",
     "read",
@@ -239,7 +242,7 @@ export const CAPABILITY_CATALOG: Record<KnownCapabilityId, CapabilityDescriptor>
   "task.retry": d(
     "task.retry",
     "重试任务",
-    "对失败/死信任务重新排队；副作用经操作账本去重",
+    "对失败/死信任务重新排队；副作用经操作账本去重。只用于失败 / 死信的任务；同一任务不要反复重试",
     "execute",
     "TaskRetry",
     "organize.execute",
@@ -250,7 +253,7 @@ export const CAPABILITY_CATALOG: Record<KnownCapabilityId, CapabilityDescriptor>
   "task.cancel": d(
     "task.cancel",
     "取消任务",
-    "停止未来步骤，不撤销已完成的外部动作",
+    "停止未来步骤，不撤销已完成的外部动作。用户要求停止或任务明显无意义时用",
     "execute",
     "TaskCancel",
     "organize.execute",
@@ -261,7 +264,7 @@ export const CAPABILITY_CATALOG: Record<KnownCapabilityId, CapabilityDescriptor>
   "policy.preview": d(
     "policy.preview",
     "预览策略",
-    "用历史数据回放策略草案，展示新增命中与误排除",
+    "用历史数据回放策略草案，展示新增命中与误排除。发布策略前用，确认影响范围",
     "preview",
     "PolicyPreview",
     "read",
@@ -272,7 +275,7 @@ export const CAPABILITY_CATALOG: Record<KnownCapabilityId, CapabilityDescriptor>
   "policy.apply": d(
     "policy.apply",
     "发布策略",
-    "发布策略版本（需授权）；不直接执行 JavaScript",
+    "发布策略版本（需授权）；不直接执行 JavaScript。只在用户明确要求发布策略时用",
     "execute",
     "PolicyApply",
     "admin",
@@ -283,7 +286,7 @@ export const CAPABILITY_CATALOG: Record<KnownCapabilityId, CapabilityDescriptor>
   "inventory.query": d(
     "inventory.query",
     "查库存",
-    "查询本地资产、版本目标满足情况与外部库存证据",
+    "查询本地资产、版本目标满足情况与外部库存证据。查某个作品有哪些文件与版本目标时用；想盘点全部就不给 query，不要用单字母探查",
     "read",
     "InventoryQuery",
     "read",
@@ -291,6 +294,40 @@ export const CAPABILITY_CATALOG: Record<KnownCapabilityId, CapabilityDescriptor>
     true,
     false,
   ),
+  // AG-3 只读摘要:订阅 / 待处理事项 / 下载任务。输出是摘要(不含凭证与私有链接),供模型盘点与调查
+  "subscription.list": d(
+    "subscription.list",
+    "列出订阅",
+    "按状态或媒体类型分组列出订阅摘要（作品、模式、状态、版本目标满足数、上次/下次搜索）。盘点订阅、找缺版本时用；查单个作品的文件与版本目标用 inventory.query",
+    "read",
+    "SubscriptionList",
+    "read",
+    "low",
+    true,
+    false,
+  ),
+  "decision.list": d(
+    "decision.list",
+    "列出待处理事项",
+    "列出待处理事项摘要（种类、严重度、对象、尝试次数与可选处理 options），缺省只列未关闭的。巡检或汇总待处理时用；不要用它处理事项，处理由用户在待处理中心选择",
+    "read",
+    "DecisionList",
+    "read",
+    "low",
+    true,
+    false,
+  ),
+  "download.inspect": d(
+    "download.inspect",
+    "查看下载任务",
+    "按下载任务 ID 或种子 hash 读取下载任务状态、进度、错误、关联计划、资源、业务任务、整理记录与待处理事项。调查下载失败或无进展时用；业务任务 ID 用 task.inspect",
+    "read",
+    "DownloadInspect",
+    "read",
+    "low",
+    true,
+    false,
+  ),
   // 子代理(设置 pi.subagents 开启后才提供给模型):类别 propose——只建有界子会话,不产生外部副作用,
   // "先给方案"的会话也能派生(子会话同样只给方案);授权不高于父会话,由服务端校验
   "agent.spawn": d(
@@ -307,7 +344,7 @@ export const CAPABILITY_CATALOG: Record<KnownCapabilityId, CapabilityDescriptor>
   "agent.await": d(
     "agent.await",
     "等待子会话",
-    "等待本会话派生的子会话结束（等待期间不调用模型），返回各自状态、用量与汇报摘要；超时仍未结束的标为 pending",
+    "等待本会话派生的子会话结束（等待期间不调用模型），返回各自状态、用量与汇报摘要；超时仍未结束的标为 pending。派生子会话后汇总前用；没有派生子会话时不要调用",
     "read",
     "AgentAwait",
     "read",
@@ -319,7 +356,7 @@ export const CAPABILITY_CATALOG: Record<KnownCapabilityId, CapabilityDescriptor>
   "site.list": d(
     "site.list",
     "列出站点",
-    "列出已登记站点的健康、登录状态与账号摘要（不含凭证）",
+    "列出已登记站点的健康、登录状态与账号摘要（不含凭证）。排查站点问题或确认站点可用时用",
     "read",
     "SiteList",
     "read",
@@ -331,7 +368,7 @@ export const CAPABILITY_CATALOG: Record<KnownCapabilityId, CapabilityDescriptor>
   "site.health_check": d(
     "site.health_check",
     "检测站点",
-    "检测站点首页连通与登录态，写回站点健康状态",
+    "检测站点首页连通与登录态，写回站点健康状态。站点连通或登录态可疑时用；不要频繁检测",
     "execute",
     "SiteHealthCheck",
     "admin",
@@ -343,7 +380,7 @@ export const CAPABILITY_CATALOG: Record<KnownCapabilityId, CapabilityDescriptor>
   "site.refresh_login": d(
     "site.refresh_login",
     "刷新站点登录",
-    "对站点账号重新登录或校验 Cookie / API Key，成功后拉取用户数据；需持续授权或审批",
+    "对站点账号重新登录或校验 Cookie / API Key，成功后拉取用户数据；需持续授权或审批。站点登录失效时用；验证码等人工步骤无法自动完成",
     "execute",
     "SiteLoginRefresh",
     "admin",
@@ -354,7 +391,7 @@ export const CAPABILITY_CATALOG: Record<KnownCapabilityId, CapabilityDescriptor>
   "site.user_data": d(
     "site.user_data",
     "查站点用户数据",
-    "读取站点账号的最新用户数据（上传、下载、分享率、魔力、做种）与按天历史",
+    "读取站点账号的最新用户数据（上传、下载、分享率、魔力、做种）与按天历史。关心分享率、魔力或做种情况时用",
     "read",
     "SiteUserData",
     "read",