From b752ce26f7788a0c6e536609b1d640ba4aad199a Mon Sep 17 00:00:00 2001 From: root Date: Wed, 7 Oct 2026 01:52:24 +0800 Subject: [PATCH] =?UTF-8?q?copy(contracts):=20=E8=AE=BE=E7=BD=AE=E6=A0=A1?= =?UTF-8?q?=E9=AA=8C=E3=80=81=E4=BA=8B=E4=BB=B6=E8=AF=B4=E6=98=8E=E4=B8=8E?= =?UTF-8?q?=20API=20=E6=91=98=E8=A6=81=E7=BB=9F=E4=B8=80=E6=9C=AF=E8=AF=AD?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 恢复水位 / 硬阈值 → 恢复线 / 暂停线;库根、哨兵、Feed、快照、建档、纳管等按术语表改。 Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01Cxwgnn2pbzQ7rXv3rq7fei --- packages/contracts/src/api/content.ts | 6 +++--- packages/contracts/src/api/execution.ts | 4 ++-- packages/contracts/src/api/instances.ts | 6 +++--- packages/contracts/src/api/library.ts | 14 +++++++------- packages/contracts/src/api/organize.ts | 8 ++++---- packages/contracts/src/api/platform.ts | 6 +++--- packages/contracts/src/api/review.ts | 2 +- packages/contracts/src/api/rules.ts | 4 ++-- packages/contracts/src/api/sources.ts | 14 +++++++------- packages/contracts/src/api/subtitles.ts | 2 +- packages/contracts/src/events.ts | 12 ++++++------ packages/contracts/src/reasons.ts | 2 +- packages/contracts/src/settings.ts | 8 ++++---- 13 files changed, 44 insertions(+), 44 deletions(-) diff --git a/packages/contracts/src/api/content.ts b/packages/contracts/src/api/content.ts index ba02f55c..c528fd64 100644 --- a/packages/contracts/src/api/content.ts +++ b/packages/contracts/src/api/content.ts @@ -164,7 +164,7 @@ export const contentApi = { // ── 文件(只读;写入只经整理/对账流程,不开放直接改) ── mediaAssets: crud( "/media-assets", - "资产", + "文件", { row: assets.MediaAsset, filters: { mediaEntityId: Id.optional(), status: assets.AssetStatus.optional() }, @@ -173,7 +173,7 @@ export const contentApi = { ), assetUnitCoverage: crud( "/asset-unit-coverage", - "资产覆盖", + "文件覆盖", { row: assets.AssetUnitCoverage, filters: { mediaAssetId: Id.optional(), contentUnitId: Id.optional() }, @@ -182,7 +182,7 @@ export const contentApi = { ), assetLocations: crud( "/asset-locations", - "资产位置", + "文件位置", { row: assets.AssetLocation, filters: { mediaAssetId: Id.optional(), status: assets.LocationStatus.optional() }, diff --git a/packages/contracts/src/api/execution.ts b/packages/contracts/src/api/execution.ts index db7f863b..3b2d8c40 100644 --- a/packages/contracts/src/api/execution.ts +++ b/packages/contracts/src/api/execution.ts @@ -41,7 +41,7 @@ export const executionApi = { method: "get", path: "/tasks/{id}/operations", scope: "read", - summary: "任务的操作账本（业务时间线）", + summary: "任务的操作记录（业务时间线）", params: IdParam, response: z.object({ items: z.array(execution.AssetOperation) }), }), @@ -86,7 +86,7 @@ export const executionApi = { path: "/acquisition-plans/{id}/cancel", scope: "organize.execute", summary: - "取消还没提交到下载器的计划（待批准 / 已预留）：释放收录版本与预算预留；已有下载任务的返回 409。待批准的计划请拒绝审批（拒绝后计划自动取消）", + "取消还没提交到下载器的计划（待批准 / 已预留）：释放收录版本与预算预留；已有下载任务的返回 409。待批准的计划用拒绝审批（拒绝后计划自动取消）", params: IdParam, response: execution.AcquisitionPlan, }), diff --git a/packages/contracts/src/api/instances.ts b/packages/contracts/src/api/instances.ts index 579649c4..e7241696 100644 --- a/packages/contracts/src/api/instances.ts +++ b/packages/contracts/src/api/instances.ts @@ -9,7 +9,7 @@ export const instancesApi = { libraryRoots: { ...crud( "/library-roots", - "库根", + "媒体库目录", { row: instances.LibraryRoot, create: instances.LibraryRootCreate, @@ -17,8 +17,8 @@ export const instancesApi = { }, R, ), - test: instanceTest("/library-roots/{id}/test", "检查库根在线（目录 + 哨兵文件）"), - remove: del("/library-roots/{id}", "删除库根"), + test: instanceTest("/library-roots/{id}/test", "检查媒体库目录在线（目录 + 标记文件）"), + remove: del("/library-roots/{id}", "删除媒体库目录"), }, downloaderInstances: { ...crud( diff --git a/packages/contracts/src/api/library.ts b/packages/contracts/src/api/library.ts index 48d4669a..6524fc8d 100644 --- a/packages/contracts/src/api/library.ts +++ b/packages/contracts/src/api/library.ts @@ -84,7 +84,7 @@ export const libraryApi = { method: "get", path: "/library", scope: "read", - summary: "媒体库列表（已登记资产或正在追踪的作品）", + summary: "媒体库列表（有已整理文件或正在追踪的作品）", query: organization.LibraryListQuery, response: cursorPage(organization.LibraryItem), }), @@ -92,7 +92,7 @@ export const libraryApi = { method: "get", path: "/library/{id}", scope: "read", - summary: "作品详情：实际路径、身份映射、元数据来源、各收录版本、候选拒绝理由、下载历史与校验结果", + summary: "作品详情：实际路径、身份映射、元数据来源、各收录版本、资源被拒原因、下载历史与校验结果", params: IdParam, response: organization.LibraryDetail, }), @@ -100,7 +100,7 @@ export const libraryApi = { method: "get", path: "/library/{id}/versions", scope: "read", - summary: "作品的已整理版本：每季每集的本地文件版本与规格、季 / 作品汇总、与版本目标的比对", + summary: "作品的已整理版本：每季每集的本地文件版本与规格、季 / 作品汇总、与收录版本的比对", params: IdParam, query: libraryVersions.LibraryVersionsQuery, response: libraryVersions.LibraryVersions, @@ -118,7 +118,7 @@ export const libraryApi = { method: "post", path: "/library/reconcile", scope: "admin", - summary: "立即做一轮资产对账（库根哨兵 + 增量 stat；不删记录、不补下载）", + summary: "立即做一轮文件核对（媒体库目录标记文件 + 增量 stat；不删记录、不补下载）", body: z.object({ libraryRootId: z.uuid().optional() }), response: z.object({ runId: z.uuid(), stats: z.record(z.string(), z.unknown()) }), }), @@ -146,7 +146,7 @@ export const libraryApi = { method: "get", path: "/dashboard", scope: "read", - summary: "首页聚合：自动化概览/当前工作/需要我处理/缓存与保留/来源健康/最近产出", + summary: "首页聚合：自动化概览 / 当前工作 / 需要处理 / 缓存与保留 / 站点健康 / 最近产出", response: organization.Dashboard, }), }, @@ -164,7 +164,7 @@ export const libraryApi = { method: "post", path: "/download-cache/cleanup", scope: "admin", - summary: "立即按阈值清理下载缓存（只清已核验整理且满足保留/H&R 的纳管任务）", + summary: "立即按暂停线清理下载盘（只清已整理、满足保种与 H&R 要求的本工具管理任务）", body: z.object({ downloaderInstanceId: z.uuid().optional() }), response: z.object({ report: z.record(z.string(), z.unknown()) }), }), @@ -203,7 +203,7 @@ export const libraryApi = { path: "/media/tmdb/{type}/{id}", scope: "read", summary: - "仅 TMDB 作品的详情：TMDB 信息与季列表、本地库存对比、是否已建档、搜资源的查询词；include=mediaServers 同时查 Emby", + "仅 TMDB 作品的详情：TMDB 信息与季列表、本地库存对比、是否已加入媒体库、搜资源的查询词；include=mediaServers 同时查 Emby", params: search.TmdbMediaParams, query: search.TmdbMediaQuery, response: search.TmdbMediaDetail, diff --git a/packages/contracts/src/api/organize.ts b/packages/contracts/src/api/organize.ts index 5d04d680..a06e91a3 100644 --- a/packages/contracts/src/api/organize.ts +++ b/packages/contracts/src/api/organize.ts @@ -141,7 +141,7 @@ export const organizeApi = { method: "get", path: "/files/roots", scope: "organize.read", - summary: "可浏览的根（库根 + 下载根），含实时健康与空间", + summary: "可浏览的登记目录（媒体库目录 + 下载目录），含实时健康与空间", response: files.FileRootList, }), list: ep({ @@ -204,7 +204,7 @@ export const organizeApi = { method: "post", path: "/files/delete", scope: "organize.execute", - summary: "删除（默认进回收站；引用检查：做种/资产/绑定；permanent 仅 admin 会话）", + summary: "删除（默认进回收站；引用检查：做种 / 已整理文件 / 绑定；permanent 仅 admin 会话）", body: files.FilesDeleteRequest, response: files.FilesDeleteResult, }), @@ -262,7 +262,7 @@ export const organizeApi = { method: "post", path: "/files/probe", scope: "organize.execute", - summary: "ffprobe 摘要（≤20 项；已登记资产写回 media_info，所以要 organize.execute）", + summary: "ffprobe 摘要（≤20 项；已整理文件写回 media_info，所以要 organize.execute）", body: files.FilesProbeRequest, response: files.FilesProbeResult, }), @@ -338,7 +338,7 @@ export const organizeApi = { method: "post", path: "/files/suggest-name", scope: "organize.read", - summary: "按命名模板（作品 > 库根 > 全局）生成推荐名；识别不可信时 name=null + 原因", + summary: "按命名模板（作品 > 媒体库目录 > 全局）生成推荐名；识别不可信时 name=null + 原因", body: files.FilesSuggestNameRequest, response: files.FilesSuggestNameResult, }), diff --git a/packages/contracts/src/api/platform.ts b/packages/contracts/src/api/platform.ts index 30527e0b..30b45881 100644 --- a/packages/contracts/src/api/platform.ts +++ b/packages/contracts/src/api/platform.ts @@ -151,7 +151,7 @@ export const platformApi = { path: "/naming/preview", scope: "read", summary: - "预览：模板 + 样本（文件名 / 资源 / 资产 / 内置）→ 相对路径、段角色、错误（行列号）、提示；已有路径绑定时目录用绑定", + "预览：模板 + 样本（文件名 / 资源 / 已整理文件 / 内置）→ 相对路径、段角色、错误（行列号）、提示；已有路径绑定时目录用绑定", body: settingsNs.NamingPreviewInput, response: settingsNs.NamingPreviewResult, }), @@ -159,7 +159,7 @@ export const platformApi = { method: "get", path: "/naming/templates", scope: "read", - summary: "全局 / 库根 / 作品三级模板与按类型的生效结果（作品 > 库根 > 全局）", + summary: "全局 / 媒体库目录 / 作品三级模板与按类型的生效结果（作品 > 媒体库目录 > 全局）", query: settingsNs.NamingTemplatesQuery, response: settingsNs.NamingTemplatesView, }), @@ -175,7 +175,7 @@ export const platformApi = { method: "put", path: "/library-roots/{id}/naming", scope: "admin", - summary: "库根级命名覆盖（按类型；null 清除）", + summary: "媒体库目录级命名覆盖（按类型；null 清除）", params: IdParam, body: settingsNs.LibraryRootNamingPut, response: settingsNs.LibraryRootNamingPut, diff --git a/packages/contracts/src/api/review.ts b/packages/contracts/src/api/review.ts index 22e87f73..d55a954c 100644 --- a/packages/contracts/src/api/review.ts +++ b/packages/contracts/src/api/review.ts @@ -105,7 +105,7 @@ export const reviewApi = { method: "post", path: "/agent/runs", scope: "organize.execute", - summary: "委托目标：建 agent_run 并入队 runAgent（proposeFirst = 先看方案再执行；mode 已弃用）", + summary: "委托目标：建 agent_run 并入队 runAgent（proposeFirst = 先给方案；mode 已弃用）", body: agent.AgentRunStartInput, response: agent.AgentRun, }), diff --git a/packages/contracts/src/api/rules.ts b/packages/contracts/src/api/rules.ts index 44b254e6..6d2c9b93 100644 --- a/packages/contracts/src/api/rules.ts +++ b/packages/contracts/src/api/rules.ts @@ -41,7 +41,7 @@ export const rulesApi = { method: "post", path: "/subscriptions/{id}/reset", scope: "admin", - summary: "重置进度：取消已预留未提交、下载任务已不在的计划，清延后记录，立即重评；仍在下载的计划与已整理资产保留", + summary: "重置进度：取消已预留未提交、下载任务已不在的计划，清延后记录，立即重评；仍在下载的计划与已整理文件保留", params: IdParam, response: policy.SubscriptionResetResult, }), @@ -140,7 +140,7 @@ export const rulesApi = { method: "get", path: "/subscriptions/{id}/progress", scope: "read", - summary: "订阅进度：季总集数账本、每集状态（已覆盖/在途/缺失/疑似缺集）、收录版本在途与延后", + summary: "订阅进度：季总集数、每集状态（已覆盖/在途/缺失/疑似缺集）、收录版本在途与延后", params: IdParam, response: policy.SubscriptionProgress, }), diff --git a/packages/contracts/src/api/sources.ts b/packages/contracts/src/api/sources.ts index 87e6c92b..78d35b13 100644 --- a/packages/contracts/src/api/sources.ts +++ b/packages/contracts/src/api/sources.ts @@ -56,7 +56,7 @@ export const sourcesApi = { method: "post", path: "/sites/{id}/disable", scope: "admin", - summary: "关闭站点（停止网络访问与新候选，历史资源仍可查）", + summary: "关闭站点（停止访问站点、不再收新资源，历史资源仍可查）", params: IdParam, response: sources.Site, }), @@ -64,7 +64,7 @@ export const sourcesApi = { method: "post", path: "/sites/{id}/snapshot", scope: "admin", - summary: "立即同步站点快照（受站点限流）", + summary: "立即抓取站点列表（受站点限流）", params: IdParam, body: z.object({ maxPages: z.number().int().min(1).max(20).optional() }), response: TaskAccepted, @@ -73,7 +73,7 @@ export const sourcesApi = { method: "get", path: "/sites/{id}/snapshots", scope: "read", - summary: "站点快照/补查记录（覆盖范围与新鲜度）", + summary: "站点抓取记录（覆盖范围与更新时间）", params: IdParam, query: CursorQuery, response: cursorPage(sources.SiteSnapshot), @@ -127,7 +127,7 @@ export const sourcesApi = { method: "get", path: "/sites/{id}/releases", scope: "read", - summary: "资源列表/搜索（快照优先，必要时实时补查；标注来源与更新时间）", + summary: "资源列表 / 搜索（先用上次抓取的结果，必要时去站点搜；标注来源与更新时间）", params: IdParam, query: sources.WorkbenchReleaseQuery, response: sources.WorkbenchReleasePage, @@ -159,7 +159,7 @@ export const sourcesApi = { feedSources: { ...crud( "/feed-sources", - "Feed", + "RSS", { row: sources.FeedSource, create: sources.FeedSourceCreate, @@ -180,7 +180,7 @@ export const sourcesApi = { method: "post", path: "/feed-sources/{id}/enable", scope: "admin", - summary: "启用 Feed", + summary: "启用 RSS", params: IdParam, response: sources.FeedSource, }), @@ -188,7 +188,7 @@ export const sourcesApi = { method: "post", path: "/feed-sources/{id}/disable", scope: "admin", - summary: "停用 Feed", + summary: "停用 RSS", params: IdParam, response: sources.FeedSource, }), diff --git a/packages/contracts/src/api/subtitles.ts b/packages/contracts/src/api/subtitles.ts index bd3561fa..d4e75b90 100644 --- a/packages/contracts/src/api/subtitles.ts +++ b/packages/contracts/src/api/subtitles.ts @@ -24,7 +24,7 @@ export const subtitlesApi = { method: "post", path: "/subtitles/apply", scope: "organize.execute", - summary: "写入字幕：视频同目录、视频主干名 + 语言后缀；同名字幕先备份；登记为字幕资产并记历史", + summary: "写入字幕：视频同目录、视频主干名 + 语言后缀；同名字幕先备份；登记为字幕文件并记历史", body: subtitles.SubtitleApplyRequest, response: subtitles.SubtitleApplyResult, }), diff --git a/packages/contracts/src/events.ts b/packages/contracts/src/events.ts index dbf81f15..879b3101 100644 --- a/packages/contracts/src/events.ts +++ b/packages/contracts/src/events.ts @@ -346,12 +346,12 @@ export const TypedEventEnvelope = z.discriminatedUnion( * 已有的 release.resolved 也算一条(资源识别完成)。emittedBy 是发出的模块,说明写在什么时候发。 */ export const LIFECYCLE_EVENTS: readonly { type: EventType; label: string; emittedBy: string; when: string }[] = [ - { type: "release.resolved", label: "资源识别完成", emittedBy: "sources-identity", when: "来源资源认到本地作品" }, + { type: "release.resolved", label: "资源识别完成", emittedBy: "sources-identity", when: "资源识别到本地作品" }, { type: "subscription.created", label: "订阅已建", emittedBy: "acquisition-organize", - when: "新建订阅（含策略自动建）", + when: "新建订阅（包括按策略自动建的）", }, { type: "subscription.updated", @@ -367,8 +367,8 @@ export const LIFECYCLE_EVENTS: readonly { type: EventType; label: string; emitte }, { type: "subscription.cancelled", label: "订阅已取消", emittedBy: "acquisition-organize", when: "删除订阅" }, { type: "download.submitted", label: "下载已提交", emittedBy: "acquisition-organize", when: "种子交给下载器" }, - { type: "download.completed", label: "下载已完成", emittedBy: "acquisition-organize", when: "下载器报告下完" }, - { type: "download.failed", label: "下载失败", emittedBy: "acquisition-organize", when: "下载任务进入失败" }, + { type: "download.completed", label: "下载已完成", emittedBy: "acquisition-organize", when: "下载器报告已下完" }, + { type: "download.failed", label: "下载失败", emittedBy: "acquisition-organize", when: "下载任务进入失败状态" }, { type: "download.removed", label: "下载已移除", @@ -393,7 +393,7 @@ export const LIFECYCLE_EVENTS: readonly { type: EventType; label: string; emitte type: "media.watched", label: "作品进入关注", emittedBy: "sources-identity / acquisition-organize", - when: "建订阅、开始下载、搜索认定作品", + when: "新建订阅、开始下载或搜索时确认了作品", }, { type: "media.metadata_refreshed", @@ -405,7 +405,7 @@ export const LIFECYCLE_EVENTS: readonly { type: EventType; label: string; emitte type: "media.episode_structure_changed", label: "季集结构已切换", emittedBy: "sources-identity", - when: "作品切换剧集组", + when: "作品换了季集结构", }, { type: "site.unreachable", diff --git a/packages/contracts/src/reasons.ts b/packages/contracts/src/reasons.ts index 5a25e81a..20b89755 100644 --- a/packages/contracts/src/reasons.ts +++ b/packages/contracts/src/reasons.ts @@ -38,7 +38,7 @@ const REASONS: Record = { entity_not_found: { text: "作品已不存在" }, no_library_root: { text: "没有可用的媒体库目录", action: "在设置 → 媒体库与目录里添加" }, library_root_offline: { text: "媒体库目录不可访问或未挂载", action: "检查挂载后重试" }, - target_dir_unavailable: { text: "整理目标目录建不出来", action: "检查目录权限或挂载，恢复后自动重试" }, + target_dir_unavailable: { text: "无法创建整理目标目录", action: "检查目录权限或挂载，恢复后自动重试" }, organize_stalled: { text: "整理多次重试仍未完成", action: "检查后重新整理" }, excluded_unresolved: { text: "有视频没能确定季集或目标目录，留在原处", action: "确认季集后重新整理" }, target_dir_outside_root: { text: "目标目录不在媒体库目录里" }, diff --git a/packages/contracts/src/settings.ts b/packages/contracts/src/settings.ts index d9d6a85e..1b1f3f04 100644 --- a/packages/contracts/src/settings.ts +++ b/packages/contracts/src/settings.ts @@ -62,8 +62,8 @@ const CacheShape = z.object({ }); /** 下载缓存卷硬阈值与恢复水位(REQ §8.4.1) */ export const CacheSettings = CacheShape.refine((v) => v.resumePercent < v.hardThresholdPercent, { - message: "恢复水位必须低于硬阈值", -}).refine((v) => v.cleanupTargetPercent <= v.resumePercent, { message: "清理目标不得高于恢复水位" }); + message: "恢复线必须低于暂停线", +}).refine((v) => v.cleanupTargetPercent <= v.resumePercent, { message: "清理目标不能高于恢复线" }); export type CacheSettings = z.infer; export const OrganizeMode = z.enum(["copy", "move"]); @@ -534,7 +534,7 @@ export const StorageBudgets = z /** Agent 会话 + 视觉证据(DATA_DIR/agent-sessions、tmp/evidence)预算(GB) */ sessionsEvidenceGb: Gb, }) - .refine((v) => v.pgDataWarnGb <= v.pgDataGb, { message: "PG 告警线不得高于预算" }); + .refine((v) => v.pgDataWarnGb <= v.pgDataGb, { message: "PG 告警线不能高于预算" }); export type StorageBudgets = z.infer; /** 各类流水数据保留期(到期由 storage.retention.* 定时任务分批删除) */ @@ -1130,7 +1130,7 @@ export const SETTINGS_SECTIONS: readonly SettingsSectionDef[] = [ id: "agent", group: "flow", label: "智能体", - description: "模型服务、用量与防跑飞限制、自动处理、网页搜索、MCP", + description: "模型服务、用量与限制、自动处理、网页搜索、MCP", legacyTabs: [{ tab: "pi" }], anchors: [ { id: "upstream", label: "模型服务", keywords: ["默认模型服务", "订阅登录"] },