UHD_Media_Tool/docs/design/de-ai-review.md

# 去 AI 味、去工程味审查(DEAI-1)

> 2026-09-29 · 只审查,不改代码。依据:`human-copy` 文案规范、用户品味清单、[glossary.md](glossary.md)、[console-ia.md](console-ia.md);对照 MoviePilot 前端 `src/locales/zh-CN.ts`。
> 截图:登录 `https://127.0.0.1` 只读抓取(非 GET 的 `/api` 请求一律拦截,未碰站点搜索),存在 `apps/web/test/screenshots/deai/`(不进 git),下文用文件名前缀引用,如 `01-home`。
> 缺口:库里没有订阅,订阅详情页无法截图,该页条目来自源码字符串(`routes/console/subscriptions.$id.tsx`、`components/subscriptions/*`)。

## 1. 总诊断

问题主要有五类,根源都是「界面是从数据模型和实现往外长出来的,没有先问用户此刻要什么」。

1. **数据模型直接当界面**。表名、状态码、枚举值原样上屏:`identity_unknown`、`blocked:target_exists`、`capability.invoke`、`tmdb:tv:90228`、`agent_run_event`、`r1`。整理记录、待处理、下载时间线、审计都有。
2. **每个字段都想解释,解释的是实现而不是后果**。计划页 29 行说明里有「对照 MP 启动时的 clear_temp」「observation,按 created_at」「umt backup(宿主机 cron 调用)」;设置页讲哨兵文件 `.uhd-root`、负缓存、三个进程共用。用户看不懂,看懂了也做不了决定。
3. **为可审计而堆证据**。Agent 会话一屏里同时有「模型说的(未经核查)」「仅供参考,不作为完成依据」「系统核实的结果」、5 个状态徽章、4 个 0 计数、数据来源说明、token 数和四位小数的美元费用。可信度是靠一句话和一个链接建立的,不是靠把账本摊开。
4. **内部概念名直接露给用户**。版本目标、内容单元、临时单元、资产、外部身份、库根、纳管、快照、候选、修订、草案、抑制记录、持续授权、幂等。MP 用「洗版」「已入库 / 缺失」「媒体库目录」「整理」「识别」这类用户早就会说的词。
5. **同一件事多种说法、多重信号**。「身份歧义 / 识别有歧义 / 无法确定作品」「RSS 订阅 / 来源健康 / Feed」「媒体概览 / 媒体库」「整理冲突 / 路径冲突 / target_exists」;「自动化运行中」同时用播放图标、绿点徽章「总开关开」和一句口号表达。

另有一个事实性问题:首页写「0 个订阅在追踪,自动收录、下载和整理」,数字为 0 时后半句是空承诺。

## 2. 术语对照表

「界面」一列:**显示** = 默认视图可以出现;**详情** = 只在详情页 / 折叠区 / 高级设置出现;**隐藏** = 只在代码、日志、给模型的提示里。

| 当前用词 | 用户视角的说法(参考 MP / 常识) | 界面 | 说明 |
| --- | --- | --- | --- |
| 版本目标 / Slot | 「想要的版本」;升级动作沿用 MP 的「洗版」 | 显示(改名后) | 首页「版本目标满足率」改「想要的版本已到齐 x / y」;列名「版本目标」→「版本」。**需拍板**,见 §5.4 |
| 资源(SourceRelease) | 资源 | 显示 | 保留,和 MP 一致 |
| 候选 | 不单独命名;说「可下载的资源」「选一个下载」 | 隐藏 | 「候选被选中后生成计划」这种句子直接删 |
| 观察(observation) | 不出现 | 隐藏 | 目前出现在设置「Feed 观察」、计划页「观察记录清理」、下载时间线「观察 · 无」 |
| 内容单元 | 季 / 集 | 隐藏 | 作品详情面板标题「内容单元」→「季与集」 |
| 临时单元 | 「未确认的集」或不提示 | 详情 | 徽章「临时单元」→「编号待确认」 |
| 资产 / 资产位置 | 文件 / 已入库文件 | 显示为「文件」 | 首页「资产 5 已入库视频」→「已入库文件 5」 |
| 运行 / run / 引擎运行 | 任务(用户侧);引擎步骤只在详情折叠区 | 详情 | 「未关联业务对象 · ce28d777」这种行默认不进任务列表 |
| 租约 / 控制权 / 接管(浏览器) | 「你在操作」/「交还给 Agent」 | 显示(按钮) | 「租约」一词不出现 |
| 纳管 / 接管(下载器) | 「由本工具管理」;筛选叫「来源:本工具 / 其他」 | 显示(改名后) | 下载列表每行的「接管」徽章删掉,只在不是本工具管理的行标「外部任务」 |
| 证据 / 原始证据 / 证据等级 | 「详情」「依据」 | 详情 | 待处理的「原始证据」→「详细信息」;身份的「证据 人工确认 · 校验通过 · r1」→「你确认的」/「自动匹配」 |
| 能力 / capability | 「Agent 能做的事」;具体项用动作名(查作品、提交下载) | 详情 | 审计里的 `capability.invoke` / `capability.denied` 显示为「Agent 查询 · 订阅列表」「Agent 被拒绝 · 检测站点健康」 |
| Agent 上游 / 上游 | 模型服务 / 模型 | 显示(改名后) | MP 叫「AI Agent / 上游 provider」也不好;「上游登录刷新」每 10 分钟刷屏,见 §3.2。**需拍板** |
| 巡检 | 巡检 | 显示 | 可保留;说明里去掉「能力白名单」 |
| 待识别 / 待识别池 | 未识别 | 显示 | MP 用「未识别到媒体信息」。「池」字去掉(console-ia §6.4 早已记为遗留) |
| 身份 / 外部身份 | 「TMDB / IMDb 编号」;动作叫「识别」「改匹配」 | 详情 | 「身份歧义」统一成「识别有歧义」;`tmdb:tv:90228` 显示为「TMDB 90228」链接 |
| TMDB 映射 | 匹配的 TMDB 条目 | 详情 | |
| 持续授权 | 「允许 Agent 自动执行 xx」 | 详情 | 只在 Agent 设置和巡检编辑框出现,不带 ID 前缀 |
| 审批 | 批准 / 拒绝 | 显示 | 保留;「会话内审批有效期」→「等你批准的最长时间」 |
| 幂等 / 幂等键 | 不出现 | 隐藏 | 工具调用卡片上的「幂等」徽章删,幂等键进审计详情 |
| 整理记录 | 整理记录 | 显示 | 与 MP「媒体整理 / 历史记录」一致,保留 |
| 库根 | 媒体库目录 | 显示(改名后) | MP 叫「媒体库目录」;「实际路径与库根」→「文件位置」 |
| 登记目录 | 不单独命名,就是「目录」 | 隐藏 | 文件管理左栏已经按「下载目录 / 媒体库」分组,不需要这个词 |
| 哨兵 / 哨兵文件 | 「目录检查」;失败时说「目录不可访问或未挂载」 | 详情 | 按钮「检查哨兵」→「检查目录」 |
| 快照 | 「站点最新资源」/「抓取」 | 详情 | 站点卡「快照 22 分钟前」→「资源更新于 22 分钟前」;「实时补查」→「去站点搜」 |
| 账本 / 本地账本 | 不出现 | 隐藏 | 「本地账本:作品、版本目标、资产与外部身份」整句删 |
| 建档 / 已建档 | 「加入媒体库」/「已在库中,未下载」 | 显示(改名后) | 「建档不订阅」→「只加入媒体库」 |
| 修订 r1 / 草案 / 策略版本 | 「最后修改于…」;草案叫「未启用」 | 详情 | 列表的「修订」列删 |
| 抑制记录 | 「已忽略的资源」 | 显示(改名后) | 规则页签名 |
| 收录策略 | 「自动收新作品」 | 显示(改名后) | 规则页签;只在开启新作品自动收录时有意义 |
| 缓存卷 / 硬阈值 / 恢复水位 | 下载盘 / 暂停线 / 恢复线 | 显示(改名后) | 「保留期锁定 287.92 MB」→「做种保留中 288 MB」 |
| 进程 / 心跳 / SSE / 事件循环延迟 | 不出现在首页 | 详情 | 只在运行状态页的「高级」折叠区 |

## 3. 页面级问题

格式:截图 · 现象(原文) · 为什么 · 改成。

### 3.1 首页

| 截图 | 现象 | 为什么 | 改成 |
| --- | --- | --- | --- |
| 01-home | 横幅「自动化运行中」+ 绿点徽章「总开关开」+ 播放图标 +「0 个订阅在追踪,自动收录、下载和整理。」 | 三个信号说一件事;0 订阅配口号是空承诺 | 一行:「自动化已开启 · 0 个订阅」+ 右侧「暂停」。订阅为 0 时换成「还没有订阅。去搜索添加」 |
| 01-home | 首页有「只读对账」开关 | 恢复备份才用的运维开关,放首页既吓人又易误点 | 移到设置 → 自动化 → 高级;首页只在它开启时显示一条警告「只读模式:不会自动下载和整理」 |
| 01-home | 「排队 0 · 下载中 0 · 无进展 0 · 入库中 0」「满足 0 / 0 · 需关注 0 · 下载中 0」「新计划 0 · 提交下载 4 · 入库文件 5 · 升级 0」 | 0 值全部铺开,读者要自己找非零项 | 只显示非零项;全为 0 时不显示这一行 |
| 01-home | 「版本目标满足率 —」 | 内部指标名;分母为 0 时显示横线等于没说 | 分母为 0 时整块隐藏;有数据时「想要的版本已到齐 12 / 15」 |
| 01-home | 「最近完成 / 失败」6 行全是绿色「完成」徽章,副标题「处理待处理事项」「核验入库」 | 徽章泛滥;副标题是工作流名 | 只列失败和入库完成;成功不加徽章;副标题写结果「已入库」「识别失败」 |
| 01-home | 「缓存与保留:阈值 90% / 恢复 85% · 在途 0 B · 可清理 0 B · 保留期锁定 287.92 MB」 | 5 个运维参数挤一行 | 「下载盘 36% 已用 · 剩 1 TB」,细节进下载面板 |
| 01-home | 「运行状态:进程 3 在线 · 待执行 0 · 24 小时失败率 0.2% · 数据库 5.3 毫秒」 | 首页给普通用户看数据库延迟 | 正常时只显示「运行正常」一行或不显示;异常时显示问题本身 |
| 01-home | 「近 7 天 $0.0191」 | 四位小数制造精确感 | 「近 7 天 $0.02」,不足一分写「< $0.01」 |

### 3.2 任务

| 截图 | 现象 | 为什么 | 改成 |
| --- | --- | --- | --- |
| 02-tasks | 页描述「每次运行都是一条任务,不论定时、事件、手动还是 Agent 触发。」 | 解释数据模型,排比式列举 | 删,或「最近处理了什么、有没有失败」 |
| 02-tasks | 「评估候选 · 未关联业务对象 · ce28d777」「识别资源 · 未关联业务对象 · 37b8a16c」成片出现 | 内部步骤和短 ID 占满列表 | 默认隐藏无业务对象的运行,筛选里提供「显示系统任务」 |
| 02-tasks | 「上游登录刷新」每 10 分钟一条 | 后台保活刷屏 | 维护类定时任务成功时不进任务列表,只记在计划页 |
| 02-tasks | 耗时「20 毫秒」「206 毫秒」 | 毫秒级精度对用户无意义 | 小于 1 秒写「< 1 秒」 |
| 02b-tasks-failed | 标题「下载 c062c84a」,「未开始 · 19 小时前」 | 用 ID 当标题 | 用作品名 + 资源名;无作品时用资源标题 |
| 02-tasks | 行副标题「核验入库 · 下载」「处理待处理事项 · 待处理事项」 | 工作流名 + 对象类型,重复且拗口 | 只留一个:「入库检查」「识别」 |

### 3.3 计划

| 截图 | 现象 | 为什么 | 改成 |
| --- | --- | --- | --- |
| 03-schedules | 「图片缓存清理:删除超过保留天数的图片代理缓存文件(对照 MP 启动时的 clear_temp)」 | 实现备忘写进界面 | 「删除过期的海报缓存」 |
| 03-schedules | 「观察记录清理 … (observation,按 created_at)」「SSE 事件清理 … (sse_event,按 at;发布方另按条数裁剪)」「审计清理 …(audit_event…)」 | 表名、字段名上屏 | 把 18 项「维护」合并成一行「数据清理(9 项)」,展开后每项一句人话 |
| 03-schedules | 「备份:…目前用 umt backup(宿主机 cron 调用),未接入调度」,状态「未运行 · 未配置」 | 开发状态说明;一个不能用的开关占一行 | 未接入就不列;或只在运行状态页写「备份:上次 2026-09-28」 |
| 03-schedules | 「统计信息更新:对全库执行 ANALYZE,刷新查询规划用的统计信息」 | 数据库运维 | 放进「数据清理」组,文案「数据库维护」 |
| 03-schedules | 「到期重评:到了重评时间的收录位重新评估(忙时延后的发布、定时)」 | 「收录位」是术语表外的第三个 Slot 名 | 「重新检查等待中的资源」 |
| 03b-schedules-checks | 巡检卡片直接显示目标模板「巡检待处理({{now}}):有 {{openDecisions}} 条…」 | 模板变量上屏 | 卡片只显示一句用途「检查待处理并给建议」,模板进编辑框 |
| 03b-schedules-checks | 每张卡有「能力」6 个标签 + 3、预算、上游、触发条件、间隔、下次、每次费用、最近结果、最近会话 9 项 | 字段全铺 | 默认:名称、开关、间隔、上次结果与费用;其余进编辑框 |

### 3.4 Agent 会话与抽屉

| 截图 | 现象 | 为什么 | 改成 |
| --- | --- | --- | --- |
| 04b-agent-run | 「模型说的(未经核查)」+「仅供参考,不作为完成依据。」+「系统核实的结果」 | 同一个免责声明说了三遍,措辞防御 | 回复区不加标题;下面一行「实际结果:没有提交下载或整理」,有动作时列出链接 |
| 04b-agent-run | 徽章「没有产生业务动作」「运行已完成」「工具成功 7」「失败 1」「被拒绝 1」+ 四个 0 计数 + 「取自下载计划、下载任务和整理记录(生成于 …)。「已提交」指已进入下载器,整理成功才算入库。」 | 为可审计堆证据;0 计数和数据来源说明是噪音 | 只在有动作时显示计数;工具统计进「步骤」折叠区;数据来源说明删 |
| 04b-agent-run | 步骤列表显示 `site.list(inclu…`、`site.health_c…` | 工具函数名上屏 | 步骤只写人话,工具名进展开详情 |
| 04b-agent-run | 右栏「预算与用量:工具调用 9 · token 320.7k · 时长 41s · 费用(估算)$0.014」;头部「opencode-go/deepseek-v4.1-flash」 | token、模型 ID 对普通用户无意义 | 默认只显示「费用约 $0.01 · 41 秒」,token 与模型进「详情」 |
| 04-agent | 会话列表标题是原始提示词:「在浏览器会话 16be7338-… 上直接调用一次 browser.solve_challenge,参数:…」 | UUID、JSON 当标题 | 标题取模型生成的短摘要或截断到第一句;子会话默认折叠在父会话下 |
| 04-agent / 04c | 「交代目标,边做边汇报」出现在侧栏按钮、悬浮按钮;抽屉又写「交代目标,Agent 在授权范围内执行并汇报。(Ctrl+J 开关,Esc 关闭)」,输入框下再写「Agent 列出步骤后直接执行…Enter 发送,Shift+Enter 换行。」 | 口号式对仗重复 3 处;快捷键提示重复 4 处 | 侧栏按钮只写「Agent」+ 快捷键;删悬浮按钮或侧栏按钮其一;抽屉只保留 placeholder「例如:把沙丘:第二部的 4K 收进来」 |
| 04c | 收起按钮是带渐变描边的胶囊「收起 Ctrl+J / Esc 关闭」 | 渐变描边 + 发光,和侧栏、悬浮按钮三处同款 | 普通关闭按钮 × |
| agent-conversation.tsx | 「有副作用的能力需要有效的持续授权或单次审批,由服务端在执行前核对,模型声称"用户已同意"无效。」;工具卡片「幂等」徽章 | 安全设计说明写给用户 | 拒绝时只说「未执行:需要你批准」+「批准」按钮 |

### 3.5 站点与站点详情

| 截图 | 现象 | 为什么 | 改成 |
| --- | --- | --- | --- |
| 05-sites | 页描述「凭证、账号数据和健康状态;点站点名看资源、快照与 Feed」 | 列内容 + 操作指引,都能从界面看出 | 删 |
| 05-sites | 卡片:「健康检测 正常 · 1201 ms · 4 小时前」「快照 22 分钟前」「限流 默认」 | 毫秒延迟、限流、快照是运维字段 | 卡片只留账号数据 + 一行状态「正常 · 资源更新于 22 分钟前」;异常时写原因 |
| 05-sites | 徽章「账号正常」「Cookie」「VIP」 | 登录方式不需要徽章 | 只留「VIP」这类等级;状态正常不加徽章,异常才标 |
| 05b-site-overview | 「快照每 1 小时 1 页 · 健康检测每 6 小时 · 详情缓存 24 小时」「近 24 小时请求 22 次」「代理 不使用」 | 配置回显 | 放进「编辑站点」 |
| 05b / 03 | 站点页「健康检测每 6 小时」,计划页「站点健康检测 每 1 小时」 | 两个数字说的是扫描间隔和单站间隔,用户看到的是矛盾 | 计划页写「每 1 小时检查一次哪些站点到期」或直接不在计划页列出 |
| 05c-site-resources | 每行资源都有「已识别,无版本目标」 | 默认情况重复 50 次 | 只标需要注意的:「未识别」「已在库中」「可洗版」 |
| 05c-site-resources | 按钮「快照」「实时补查」,角落「近 24 小时请求站点 22 次」 | 实现术语 | 「刷新」「去站点搜」;请求次数进站点详情 |
| 05e-site-accounts | 账号页的「Passkey」(站点 RSS 密钥)与账户设置里的「Passkey」(登录用生物识别)同名 | 同名两物 | 站点这边写「站点 Passkey(RSS 与下载链接用)」,账户那边写「通行密钥(Passkey)」 |

### 3.6 RSS 订阅

| 截图 | 现象 | 为什么 | 改成 |
| --- | --- | --- | --- |
| 06-rss | 侧栏叫「RSS 订阅」,页标题叫「来源健康」,表格节标题叫「FEED」,术语表叫「Feed」 | 一物三名 | 全站统一「RSS」;页标题「RSS」,节标题「RSS 地址」 |
| 06-rss | 页描述「单个站点的快照、Feed 和账号在站点页管理。」 | 用说明文字修补 IA | 删;站点名本身可点 |
| 06-rss | 「站点」表格与站点页重复(健康、账号、最近快照) | 同一信息两处 | 本页只列 RSS;站点健康只在站点页 |
| 06-rss | 列「用途:通用」 | 只有一个取值时是噪音 | 只有非通用时显示 |

### 3.7 订阅与订阅详情(源码)

| 位置 | 现象 | 为什么 | 改成 |
| --- | --- | --- | --- |
| 07-subscriptions | 筛选栏 11 组(类型、批量、状态 6 值、站点、规则组、来源、洗版、排序),库里 0 条订阅时全部显示 | 空库也铺满控件 | 0 条时只显示空态和「新建订阅」 |
| 07-subscriptions | 空态「从媒体库、搜索或 Agent 添加,也可以点「新建订阅」。」 | 列举三个入口 | 「还没有订阅。」+ 按钮「新建订阅」 |
| coverage-matrix.tsx | 「临时单元」「还没有正式的内容单元」「按版本目标逐集对比」 | 内部概念 | 「编号待确认」「按版本逐集查看」 |
| subscriptions.$id.tsx | 「按选择顺序串联;不选 = 订阅默认规则组。版本目标自己的规则组另算」「空 = 24;0 = 关」「空 = 按 TMDB;不锁定时只升不降」 | 规则引擎语义写成等式 | 字段默认值直接填进输入框作为 placeholder;规则组说明只留「不选时用默认规则组」 |
| subscriptions.$id.tsx | 「季建好后不能改;要换季就新建订阅」 | 好文案 | 保留 |

### 3.8 规则

| 截图 | 现象 | 为什么 | 改成 |
| --- | --- | --- | --- |
| 08-rules | 页描述「规则组决定哪些资源能下载、同一作品优先挑哪个。收录策略决定哪些新作品自动收录。」 | 两句对仗定义 | 删;页签名本身要自解释 |
| 08-rules | 页签「规则组 / 自定义条件 / 默认值 / 收录策略 / 抑制记录」 | 五个里三个是内部名 | 「规则组 / 自定义条件 / 默认规则 / 自动收新作品 / 已忽略」 |
| 08-rules | 列「修订 r1」「引用 默认链」 | 版本号与引用关系 | 删「修订」列;「引用」写「订阅默认」这种具体用途 |
| 08b-rules-atoms | 13 个关键字各写「不支持,规则串里出现会报错」;标题「对齐 MoviePilot;判定依据按解析字段优先」 | 列出不支持的东西;实现备忘 | 不支持的关键字不列,或合并为一行「音乐相关关键字暂不支持」;副标题删 |
| 08c-rules-defaults | 「链上的组按顺序串联,任一组拒绝即拒绝,优先级取最后一个带层的组。」 | 算法描述 | 「按顺序检查,任一组不通过就不下载。」「带层」概念不出现 |
| 08d-rules-policies | 策略名「AGENT-REAL 最小收录策略(测试)」,按钮「新建策略草案」「基于 r1 新建草案」 | 测试数据留在用户栈;草案 / 发布模型外露 | 清理测试数据(数据问题,另开);按钮「新建」「复制并修改」 |

### 3.9 下载面板

| 截图 | 现象 | 为什么 | 改成 |
| --- | --- | --- | --- |
| 09-downloads | 页描述「阈值暂停不能手动绕过;无进展只记录,不自动换源。」 | 两条否定式声明当首屏第一句 | 删;在暂停的任务行上写「磁盘超过 90%,已暂停」 |
| 09-downloads | 「qB 测试 36.2% · 604.4 GB / 1.6 TB · 硬阈值 90% / 恢复 85% · 在途 0 B · 预留 0 B · 可清理 0 B · 保留锁定 287.9 MB」 | 7 个数一排 | 进度条 + 「已用 604 GB / 1.6 TB」;其余进「详情」 |
| 09-downloads | 每行徽章「接管」,筛选「纳管」 | 内部概念,且每行都一样 | 删徽章;筛选「来源:本工具 / 其他」 |
| 09-downloads | Interstellar 行状态「下载完成」,但整理两次失败 | 状态没反映真实问题 | 状态列写「入库失败:目标已存在」并链到待处理 |
| 09c-download-detail | 时间线「0/0 文件成功 · identity_unknown」「blocked:target_exists」 | 错误码原样上屏 | 「没有识别出作品」「媒体库里已有同名文件」 |
| 09c-download-detail | 时间线筛选「观察 · 无 / 计划 · 无 / 下载 · 2 / 整理 · 2 / Agent · 无 / 任务 · 2」,标题「业务时间线」 | 空类别也列;「业务」是开发词 | 标题「经过」;只显示有记录的类别 |
| 09c-download-detail | 「torrent hash 31090bf…」直接列在概况 | 技术信息占首屏 | 进「详情」折叠 |
| 09b-download-plans | 「候选被选中后生成计划,同时预留版本目标、空间与预算。」 | 机制说明 | 删;空态「还没有下载计划」 |

### 3.10 整理记录

| 截图 | 现象 | 为什么 | 改成 |
| --- | --- | --- | --- |
| 10-organize | 失败原因列显示 `identity_unknown`、`blocked:target_exists` | 服务端把错误码当 message 返回(`organize.ts:393`、`:641`),前端原样显示 | 服务端给中文 message;前端已有映射 `organize-wizard/model.ts` 的 `target_exists: "目标已存在"`,统一复用 |
| 10-organize | 「未关联作品 · — · 失败 · 复制 0/0」连续 4 行 | 0 文件的失败记录 | 合并为一行「4 次未识别,未整理」或只在待处理出现 |
| 10b-organize-detail | 「变更游标 35」「记录 ID」「任务 ID」「执行进程本地」「未知或未授权」 | 同步接口字段、内部 ID | 进「技术信息」折叠;「未知或未授权」改「未整理」 |
| 10b-organize-detail | 按钮「让 Agent 排查」 | 可以 | 保留 |
| 10-organize | 页描述「每次整理的前后路径与逐文件结果,自动和手动整理都记在这里。」 | 能看出来 | 删 |

### 3.11 文件管理

| 截图 | 现象 | 为什么 | 改成 |
| --- | --- | --- | --- |
| 11-files | 左栏下载目录与媒体库各带「正常」徽章和「剩余 1 TB」,底部又一处「剩余 1 TB」 | 同一信息两次;正常态徽章 | 正常不标;剩余空间只在底栏 |
| 11-files | 行摘要「1 视频 · 0 已登记」 | 「已登记」是内部状态 | 「1 个视频 · 未入库」 |
| 11-files | 筛选「临时文件」「已登记」 | 同上 | 「未完成下载」「已入库」 |
| 库根设置 | 「没有可写的库根。在设置里把库根设为纳管后再选。」(`dir-picker.tsx`) | 双重术语 | 「没有可写入的媒体库目录。去设置添加」 |

### 3.12 媒体概览与作品详情

| 截图 | 现象 | 为什么 | 改成 |
| --- | --- | --- | --- |
| 12-library | 侧栏「媒体概览」,详情页面包屑「媒体库」 | 一物两名 | 统一「媒体库」(MP 同) |
| 12-library | 描述「本地账本:作品、版本目标、资产与外部身份。自动匹配不覆盖人工锁定的外部身份。」 | 比喻 + 规则声明 | 删 |
| 12-library | 页签「作品 / 待识别 / 外部身份 / 别名」 | 后两个是维护工具 | 默认只留「作品 / 未识别」;外部身份、别名进作品详情 |
| 12c-library-identities | 行「tmdb:tv:90228 · 已确认 · 人工确认 · 校验通过 · r1 · 23 分钟前」 | 键值串 + 三个同义状态 | 「TMDB 90228 · 你确认的」 |
| 12a-library-unidentified | 原因「未命中订阅」,列「尝试 1 次 · 26 分钟前」「下次复查 24 小时后」 | 未命中订阅不是问题,不该叫原因 | 这类资源默认不进「未识别」,只放真正需要人处理的 |
| 12b-library-detail | 标题下直接显示 UUID `d1fd8828-…`;「以本地 ID 为准,外部身份可修改」 | 内部 ID 与实现声明 | UUID 进「更多 → 复制 ID」;说明删 |
| 12b-library-detail | 「字段来源与锁:锁定的字段刷新时不变」,每字段「来源 TMDB · zh-CN · 26 分钟前 · 候选:TMDB「2014」」 | 字段溯源铺满 | 默认折叠为「元数据来自 TMDB · 更新于 26 分钟前 · 编辑」 |
| 12b-library-detail | 别名一次铺出 80 多种语言 | 无筛选的数据倾倒 | 只显示中英文与用户添加的,其余「+83」 |
| 12b-library-detail | 「实际路径与库根:路径绑定建立后不随译名变化」,每个文件「主位置 · 可访问 · 已核验」 | 同上 | 「文件」一节,每行路径 + 大小;异常才标 |

### 3.13 设置(9 区)

| 截图 | 现象 | 为什么 | 改成 |
| --- | --- | --- | --- |
| 13-settings-automation | 「存储预算」「流水数据保留」「缓存有效期」三组 13 个天数 / GB 字段,含「Feed 观察」「实时事件」「进程心跳(小时)」「能力调用统计」「负缓存」 | 每张表一个旋钮 | 用户层只留:源文件保留天数、日志保留天数、图片缓存上限;其余进「高级」且默认折叠 |
| 13-settings-automation | 「只读对账:从备份恢复后先开启:只核对库存与路径,不做自动写入。核对完再关闭。」 | 好文案,位置不对 | 文案保留,移入「高级」 |
| 13-settings-sites | 「浏览器服务:原站视图和 Agent 打开站点网页用的 camofox-browser。部署自带的一台由环境变量登记(camofox-env)。」 | 组件名、部署细节 | 「浏览器服务:打开站点网页用。」;实例名显示「内置」 |
| 13-settings-library | 「登记或改路径时会在目录里写哨兵文件 .uhd-root,据此判断库根是否在线」;按钮「检查哨兵」 | 实现机制 | 「保存时会在目录里放一个标记文件,用来判断目录是否挂载。」按钮「检查目录」 |
| 13-settings-library | 命名模板变量表里的「MP 无」标签 | 给开发者的对照 | 删 |
| 13-settings-metadata | 「旧行为。每条资源约 1–2 次搜索 + 命中时 1 次详情(识别缓存命中为 0);每小时 100 条的 RSS 约每天 2400–7200 次请求…」 | 实现细节 + 「旧行为」是开发者口吻 | 「每条新资源都查一次 TMDB。RSS 量大时每天可能上千次请求。」 |
| 13-settings-agent | MCP 区块「Streamable HTTP(POST / GET / DELETE)」「read 16 个 · read + organize.execute 26 个 · admin 35 个」「授权、审计、幂等与控制台一致」 | 接入文档写在设置里 | 设置只留开关、端点、复制配置;其余进 docs 链接 |
| 13-settings-agent | 「fake 脚本(JSON):只对 fake 上游生效」「会话目录:api 与 worker 都要可读写」 | 开发调试项 | 生产构建隐藏 |
| 13-settings-api-keys | scope 名 `organize.read` / `organize.execute` 直接作为选项 | 可接受(给开发者用的页) | 保留英文 scope,前面加中文名「只读 / 读整理记录 / 执行整理 / 管理员」 |
| 全部分区 | 页描述「全局参数、实例与凭证。凭证保存后不回显。」 | 前半句空泛 | 只留「密钥保存后不再显示。」 |

### 3.14 运行状态

| 截图 | 现象 | 为什么 | 改成 |
| --- | --- | --- | --- |
| 14-status | 进程表「9428df7231e2 · pid 29」「io 4 · Agent 0」「SSE 3」 | 容器 ID 与 pid | 这是管理员页,可以保留,但放在「进程」折叠区;默认视图是一行结论「全部正常」 |
| 14-status | 「体积最大的表(前 10)· 含索引与 TOAST」列出 `metadata_field`、`agent_run_event`、`openworkflow.workflow_runs` | 数据库内部表 | 移到「高级 → 数据库」,默认折叠 |
| 14-status | 首页「失败 0」,本页「24 小时失败运行 2」,任务页失败页签「2」 | 三处口径不同 | 首页计划块写「上次失败 0 项」,和本页「24 小时失败」分开表述 |
| 14-status | 「已下线实例 33 个 · 不计入告警,24 小时后清理」 | 容器重建历史 | 删,或只在进程折叠区 |
| 14-status | 图表图例「api · 29api · 29api · 29…」重复拼接 | 渲染问题 | 修图例(bug,单独处理) |

### 3.15 待处理 / 收件箱

| 截图 | 现象 | 为什么 | 改成 |
| --- | --- | --- | --- |
| 15-inbox | 身份类事项只有「原始证据」和「忽略」,没有主操作 | 用户来这里就是要处理,最重要的按钮缺了 | 加「指定作品」主按钮;「原始证据」→「详细信息」 |
| 15-inbox | 每条都挂「警告」「待处理」两个徽章 | 全部一样的徽章等于没有 | 删状态徽章(页面已按状态筛选);级别只标「严重」 |
| 15-inbox | 分组「身份歧义 · 尚未归属作品」「路径冲突 · 系统级」 | 分组名是内部分类 | 「没识别出作品」「媒体库里已有同名文件」 |
| 15-inbox | 路径冲突事项正文 `target_exists` | 错误码 | 「媒体库里已有《星际穿越 (2014)》的同名文件」 |
| 15-inbox | 描述「Agent 调查和重试后仍未解决的事项,按作品和问题类型合并」;事项创建于「刚刚」 | 声称经过调查,实际未必 | 「需要你决定的事」 |
| 15b-inbox-bell | 铃铛下拉写「识别有歧义」,页面写「身份歧义」,首页写「无法确定作品」 | 一物三名 | 统一「没识别出作品」 |

### 3.16 全局搜索与作品预览

| 截图 | 现象 | 为什么 | 改成 |
| --- | --- | --- | --- |
| 17-search | 描述「先看作品和库内状态,需要时再到站点搜资源。」 | 教用户流程 | 删 |
| 17-search | 状态「已建档 · 未入库」「未收录」 | 「建档」「收录」都是内部词,两者区别用户不懂 | 「在媒体库 · 未下载」「不在媒体库」(MP:「已入库 / 缺失」) |
| 17b-command-palette | 底部三条提示「作品卡上可以选站点搜资源」「↑↓ 选择 ↵ 打开」「搜资源在作品详情页」 | 两条说同一件事 | 只留键位提示 |
| 18-tmdb-preview | 按钮「订阅 / 搜索资源 / 建档不订阅」 | 「建档」 | 「订阅 / 搜索资源 / 加入媒体库」 |
| 18-tmdb-preview | 「库内对比:本地账本按 TMDB 身份对应;Emby 查询失败记为未知,不等于缺失」 | 实现声明 | 标题「库中情况」;说明删,Emby 失败时就写「Emby 查询失败」 |

### 3.17 审计与外壳

| 截图 | 现象 | 为什么 | 改成 |
| --- | --- | --- | --- |
| 16-audit | 每行动作列同时显示中文和代码「登录 admin.login_success」,对象列显示 UUID | 双语重复 + ID | 代码与 ID 进行详情;对象显示名称 |
| 16-audit | 「capability.denied」没有中文名 | 翻译漏了 | 「Agent 操作被拒绝」 |
| 全局 | 页面标题 + 描述 + 侧栏说明三层,几乎每页描述都在解释页面 | 模板化 | 列表页默认不写描述;只在需要做决定的页(设置分区)写一句 |
| 全局 | Agent 入口三处:侧栏顶部渐变按钮、右下渐变悬浮按钮、侧栏「Agent 会话」 | 冗余 + 发光渐变 | 保留侧栏项和快捷键;悬浮按钮删或只在窄屏出现 |

## 4. 设计层面

**信息层级**。每页默认视图只回答「现在有没有事要我管」。技术信息分三层:正常视图(名称、状态、结果)→ 详情(路径、时间线、来源)→ 技术信息折叠区(ID、hash、trace、token、模型 ID、错误码)。现在大多数页把第三层放在第一层。

**首页该回答的三个问题**:
1. 有没有要我处理的?(待处理数 + 前 3 条,每条带主操作)
2. 最近拿到了什么?(今日入库的作品,海报或列表,MP 的「近期入库」)
3. 有没有东西坏了?(只在出问题时出现:站点登录失效、下载盘快满、服务异常)

计划带、运行状态、缓存参数、版本目标满足率都不属于这三个问题,移出首页或改为异常时才出现。

**徽章、图标、色块**。徽章只用于「不正常」和「需要区分的类别」。正常态(完成、正常、已启用、账号正常、待处理)不加徽章。一行最多一个徽章。卡片内的小卡片(首页媒体概览的三个统计块、待处理页顶部三张计数卡)改成一行文字数字,去掉套娃圆角。

**表格 vs 卡片**。同类对象多于 5 个用表格(任务、整理记录、下载、计划);站点这种少量、每个有多项数据的对象用卡片。计划页巡检卡字段太多,应改表格 + 编辑框。

**动效信号**。「实时」徽章 + 「更新于 刚刚」+ 刷新按钮 + 自动刷新,四个信号说一件事,留一个「更新于 刚刚」即可。Agent 按钮的彩色渐变描边与发光在侧栏、悬浮按钮、抽屉收起按钮三处重复,品牌色集中在一处用。

## 5. 优先级改造清单

### 5.1 P0:误导或吓人

| # | 改什么 | 文件 | 工作量 |
| --- | --- | --- | --- |
| 1 | 错误码不上屏:整理失败 message 改中文(`identity_unknown`、`blocked:*`),前端统一走一张原因映射表 | `apps/server/src/modules/acquisition-organize/services/organize.ts`、`apps/web/app/lib/labels.ts`、`routes/console/organize*.tsx`、`routes/console/inbox.tsx`、`components/downloads/business-timeline.tsx` | 0.5 天 |
| 2 | 待处理身份类事项加主按钮「指定作品」 | `routes/console/inbox.tsx` | 0.5 天 |
| 3 | 首页「0 个订阅在追踪,自动收录…」改为按数据说话;0 值行隐藏 | `routes/console/home.tsx` | 0.3 天 |
| 4 | 下载行状态反映入库失败,而不是「下载完成」 | `routes/console/downloads.tsx`、`components/downloads/*` | 0.5 天 |
| 5 | 「只读对账」移出首页 | `routes/console/home.tsx`、`components/settings/automation.tsx` | 0.2 天 |
| 6 | 「身份歧义 / 识别有歧义 / 无法确定作品」统一一个说法 | `components/library/labels.ts`、`lib/labels.ts`、服务端 `routes/decisions.ts` | 0.3 天 |

### 5.2 P1:高频页面的噪音

| # | 改什么 | 文件 | 工作量 |
| --- | --- | --- | --- |
| 1 | Agent 会话:三段免责合并为一行「实际结果」;token、模型 ID、工具名进详情;会话标题不用原始提示词 | `components/agent/agent-conversation.tsx`、`routes/console/agent.tsx` | 1 天 |
| 2 | Agent 入口去重与去口号(「交代目标,边做边汇报」删,悬浮按钮删或限窄屏) | `components/console/agent-launcher.tsx`、`components/agent/agent-drawer.tsx`、`routes/console/layout.tsx` | 0.5 天 |
| 3 | 任务列表默认隐藏无业务对象的运行和维护类成功运行;标题不用 ID | `components/tasks/task-stream.tsx`、`routes/console/tasks.tsx` | 0.5 天 |
| 4 | 计划页维护类 18 项合并折叠,说明去表名 | `components/schedules/auto-task-list.tsx`、服务端定时任务描述(`modules/system/retention.ts` 等) | 0.5 天 |
| 5 | 首页重排为三个问题;运行状态、缓存参数、满足率移出或异常才显示 | `routes/console/home.tsx` | 1 天 |
| 6 | 全站删解释型页描述(约 15 处),只保留设置分区的一句话 | `components/console/nav.ts`、各 `routes/console/*.tsx` 的 `PageHeader` | 0.5 天 |
| 7 | 正常态徽章清理:完成、正常、账号正常、接管、待处理 | `home.tsx`、`sites/site-card.tsx`、`downloads.tsx`、`inbox.tsx`、`files.tsx` | 0.5 天 |
| 8 | 术语落地:RSS 统一、媒体库统一、「建档 / 收录」、「资产」「账本」「纳管」「哨兵」「快照」按 §2 改,同步更新 `glossary.md` | 全站 + `docs/design/glossary.md` | 1 天 |
| 9 | 作品详情:UUID、字段来源、别名全集、路径核验折叠 | `routes/console/library.$id.tsx` | 0.5 天 |

### 5.3 P2:细节

| # | 改什么 | 文件 | 工作量 |
| --- | --- | --- | --- |
| 1 | 费用统一两位小数,< 0.01 写「< $0.01」;耗时 < 1 秒写「< 1 秒」 | `lib/format*.ts` | 0.2 天 |
| 2 | 规则页:不支持的关键字不列;「修订」列删;页签改名 | `components/rules/tabs.tsx`、`components/rules/labels.ts` | 0.3 天 |
| 3 | 设置高级项折叠:存储预算、流水保留、缓存有效期、fake 脚本、会话目录、MCP 详情 | `components/settings/*.tsx`、`packages/contracts/src/settings.ts`(字段加 `advanced` 标记) | 0.5 天 |
| 4 | 运行状态页默认只显示结论,表体积、进程、已下线实例折叠;修图例重复 | `routes/console/status.tsx`、`components/status/*` | 0.5 天 |
| 5 | 审计行去掉代码与 UUID,补 `capability.denied` 中文 | `routes/console/audit.tsx` | 0.2 天 |
| 6 | 站点 Passkey 与登录 Passkey 区分命名 | `components/sites/site-accounts-tab.tsx`、`components/settings/account*.tsx` | 0.1 天 |
| 7 | 命令面板提示去重 | 命令面板组件 | 0.1 天 |
| 8 | 清掉用户栈里的测试策略「AGENT-REAL 最小收录策略(测试)」 | 数据,不是代码 | 另开 |

合计约 P0 2.3 天、P1 6 天、P2 2 天。

### 5.4 需要用户拍板

1. **「版本目标」是否改名**。候选:「想要的版本」(直白,略长)或沿用 MP 的思路只在升级场景说「洗版」、其余场景说「版本」。改名涉及 139 处字符串和给模型的提示词。
2. **是否默认隐藏技术信息**。建议:ID、hash、token、模型 ID、错误码、表名一律进「技术信息」折叠区;是否提供全局开关「显示技术细节」(管理员默认关)。
3. **「Agent 上游」改不改成「模型服务」**。glossary 刚定过「Agent 上游」;用户侧「模型」更好懂,但设置里有 provider / 认证 / 订阅登录,改名要一起理。
4. **计划页是否只展示用户关心的 11 项**,18 项维护任务收成一行「数据清理」。
5. **首页是否删掉「运行状态」「计划」两块**,只在异常时出现。
6. **「收录」「建档」两个词是否全站退场**,换成「加入媒体库 / 在媒体库 / 已下载」。
7. **Agent 会话里「模型说的(未经核查)」这层防护是否保留**。建议保留一个很轻的标记(回复旁一行「以下是模型的说法」),删掉另外两处。

## 6. DEAI-2 处理情况(2026-09-29)

用户拍板(见 `docs/plan/00-first-version-plan.md`):「版本目标」→「收录版本」;「Agent 上游」→「模型服务」;界面上的 Agent → 「智能体」;技术信息默认折叠(设置 → 界面可默认展开);首页只留三块;计划页维护类收成「数据清理」、智能体巡检置顶;「未经核查」只在最终汇报留一处。术语落地见 [glossary.md](glossary.md)。

### P0

| # | 状态 | 说明 |
| --- | --- | --- |
| 1 | 完成 | 原因码表 `packages/contracts/src/reasons.ts`,服务端整理记录 message、冲突事项标题/摘要与前端(整理记录、下载时间线、待处理摘要、任务详情)共用;原码进「技术信息」 |
| 2 | 完成 | 「指定作品」主按钮:搜媒体库 + TMDB,走已有 decision resolve(local_entity / manual_tmdb);整理类事项打开重新整理,整理成功后自动关闭事项 |
| 3 | 完成 | 首页状态行按数据说话,0 订阅写「还没有订阅。去搜索添加」 |
| 4 | 部分 | 下载详情在「下载完成但最近一次整理失败」时单独提示入库失败并链到待处理;下载列表行状态未改——需要服务端在下载任务上带最近整理结果,QB-1 正在改整理服务,留给合并后另做 |
| 5 | 完成 | 只读对账移出首页,放进设置 → 自动化 →「高级」 |
| 6 | 完成 | 统一为「没识别出作品」(事项);未确认身份的资源叫「未识别」 |

### P1

| # | 状态 | 说明 |
| --- | --- | --- |
| 1 | 完成 | 见提交说明;对话组件结构不动(另有代理出易用性方案) |
| 2 | 完成 | 删口号;悬浮按钮只在无侧栏的窄屏出现,抽屉打开时不再显示胶囊 |
| 3 | 完成 | 默认隐藏系统任务(可一键显示),标题不用 ID |
| 4 | 完成 | 维护类合成「数据清理」组;自动任务按分类折叠并记忆;说明去表名 |
| 5 | 完成 | |
| 6 | 完成 | 约 14 处页描述删除或改一句 |
| 7 | 完成 | 首页、站点卡、下载、待处理、文件管理、整理记录 |
| 8 | 完成 | RSS、媒体库、建档 / 收录、资产、账本、纳管、哨兵、快照;「外部身份」一词在作品详情改「匹配的 TMDB 条目」,其余处保留 |
| 9 | 完成 | UUID、字段来源、别名全集、路径核验 |

### P2

| # | 状态 | 说明 |
| --- | --- | --- |
| 1 | 完成 | `formatUsd`、`formatDuration` |
| 2 | 完成 | |
| 3 | 部分 | 自动化分区的只读对账 / 存储预算 / 流水保留 / 缓存有效期收进「高级」;会话目录与 fake 脚本只在开发构建显示;没有在 contracts 加 `advanced` 标记(纯前端即可) |
| 4 | 完成 | 进程、趋势、最大表折叠;图例同名序列加序号 |
| 5 | 完成 | |
| 6 | 完成 | |
| 7 | 完成 | |
| 8 | 不做 | 用户栈数据,不是代码 |

### 页面级条目中不做的

- 05b 站点概况的配置回显、05c 资源行「已识别,无收录版本」、「实时补查」按钮位置:DETAIL-1 / SEARCH-3 正在改站点详情与资源列表,只改了名词(抓取、去站点搜),结构留给它们。
- 10 整理记录里连续的 0 文件失败行合并:需要服务端按下载任务聚合,放到 QB-1 合并之后。
- 12 媒体库页签只留「作品 / 未识别」、「未命中订阅」不进未识别:DH-1 正在改身份服务,避免冲突。
- 13-settings-agent MCP 区块的能力计数与接入说明移到文档:保留,只改了一句说明。
- 14 「已下线实例 N 个」文案:已随进程区折叠,文案不改。