feat(agent): add read-only download.list capability

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

packages/contracts/src/capabilities-io.ts

@@ -322,6 +322,47 @@ export const DownloadInspectOutput = z.object({
   otherMatches: z.array(Id),
 });
 
+/** download.list(AG-5):列出下载任务(按状态 / 作品 / 名称筛选),给模型"先列再看",不用向用户要 ID 或 hash */
+export const DownloadListInput = z.object({
+  /** 只列这些状态;缺省全部(不含已移除) */
+  status: z.array(DownloadStatus).max(11).optional(),
+  /** 按下载任务名或作品名模糊匹配(至少 2 个字符) */
+  query: z.string().trim().min(2).max(200).optional(),
+  mediaEntityId: Id.optional(),
+  /** 也列外部任务(不是本工具提交的);缺省只列本工具管理的 */
+  includeExternal: z.boolean().default(false),
+  limit: z.number().int().min(1).max(50).default(20),
+});
+export const DownloadListOutput = z.object({
+  total: NonNegInt,
+  /** 按状态计数(筛选后、limit 前) */
+  byStatus: z.array(z.object({ status: DownloadStatus, label: z.string(), count: NonNegInt })),
+  items: z.array(
+    z.object({
+      /** 下载任务 ID,交给 download.inspect / download.recheck */
+      id: Id,
+      name: z.string(),
+      /** 关联作品名 */
+      title: z.string().nullable(),
+      status: DownloadStatus,
+      /** 界面用词:下载中 / 已入库 / 失败… */
+      statusLabel: z.string(),
+      /** "37%" */
+      progress: z.string(),
+      /** "12.3 GB";未知为 null */
+      size: z.string().nullable(),
+      downloader: z.string().nullable(),
+      managed: z.boolean(),
+      /** 相对时间:"3 小时前" */
+      lastProgress: z.string().nullable(),
+      noProgressSince: z.string().nullable(),
+      completed: z.string().nullable(),
+      /** 最近一次错误的一句话 */
+      error: z.string().nullable(),
+    }),
+  ),
+});
+
 /** downloader.list(FIX-7):已配置的下载器与媒体服务器(只读本地记录,不含地址和凭证) */
 export const DownloaderListInput = z.object({
   includeDisabled: z.boolean().default(true),
@@ -879,6 +920,7 @@ export const CAPABILITY_IO = {
   "subscription.list": { input: SubscriptionListInput, output: SubscriptionListOutput },
   "decision.list": { input: DecisionListInput, output: DecisionListOutput },
   "download.inspect": { input: DownloadInspectInput, output: DownloadInspectOutput },
+  "download.list": { input: DownloadListInput, output: DownloadListOutput },
   "downloader.list": { input: DownloaderListInput, output: DownloaderListOutput },
   "agent.spawn": { input: AgentSpawnInput, output: AgentSpawnOutput },
   "agent.await": { input: AgentAwaitInput, output: AgentAwaitOutput },
@@ -956,6 +998,8 @@ 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 DownloadListInput = z.infer<typeof DownloadListInput>;
+export type DownloadListOutput = z.infer<typeof DownloadListOutput>;
 export type DownloaderListInput = z.infer<typeof DownloaderListInput>;
 export type DownloaderListOutput = z.infer<typeof DownloaderListOutput>;
 export type AgentSpawnInput = z.infer<typeof AgentSpawnInput>;

packages/contracts/src/capability.ts

@@ -69,6 +69,7 @@ export const CAPABILITY_IDS = [
   "subscription.list",
   "decision.list",
   "download.inspect",
+  "download.list",
   "downloader.list",
   "agent.spawn",
   "agent.await",
@@ -330,6 +331,18 @@ export const CAPABILITY_CATALOG: Record<KnownCapabilityId, CapabilityDescriptor>
     true,
     false,
   ),
+  // AG-5:先列再看。反例里模型要用户给下载任务 ID / 种子 hash,其实自己能列
+  "download.list": d(
+    "download.list",
+    "列出下载任务",
+    "按状态、作品或名称列出下载任务（名称、作品、状态、进度、体积、下载器、最近进展与错误），附按状态计数；缺省只列本工具管理的。问下载进度、找失败或卡住的下载、要下载任务 ID 时先用它，再用 download.inspect 看其中一个；不要向用户要 ID 或 hash",
+    "read",
+    "DownloadList",
+    "read",
+    "low",
+    true,
+    false,
+  ),
   // FIX-7:智能体原先只能从站点列表推断下载器是否接入(site.list 不含下载器),汇报成"下载器不在系统内"
   "downloader.list": d(
     "downloader.list",
@@ -627,6 +640,7 @@ export const CAPABILITY_ACTIVITY: Record<KnownCapabilityId, CapabilityActivity>
   "subscription.list": act("查", "订阅"),
   "decision.list": act("查", "待处理事项"),
   "download.inspect": act("查", "下载任务", "个"),
+  "download.list": act("列", "下载任务"),
   "downloader.list": act("查", "下载器"),
   "agent.spawn": act("派出", "子会话", "个"),
   "agent.await": act("等", "子会话"),