当 92% 表示的含义不同
一份关于纯文本界面中自述语境文案的 UX 写作案例研究。
Sweepy 是一款基于终端的求职工具。界面用制表符线条和彩色文本绘制,并读取键盘输入。解释必须写进文本本身,因为此处没有位置显示工具提示。启动台在边框处截断状态行,而不换行。一段文案要么在宽度内写完,要么丢掉结尾。
一条规则由此而来。每段文案都自述其语境。 评分标签说明数字由谁写出。状态文案遵循同样的纪律,从启动台底部那一行一直到每个提示的格式说明。评分是最难的一例,因为无论读者是否知道工具如何得出该数字,一个百分比看上去都像是给出了信息。
两个百分比,两个问题
Sweepy 用两种不同方式为简历评分一份招聘信息。
第一种是确定性评分器,每次扫描都会运行它。sweepy 打开启动台,START SWEEP 为扫描找到的每张卡片评分。sweepy --run 重跑上次保存的配置文件,不打开向导。这一遍比较两份文档。它统计简历与招聘信息之间的共有词,把占比 60% 的需求重合度与占比 40% 的关键词重合度混合,再按 resume.keywords_weight 缩放结果。一个词只有同时出现在两边才计入。评分器从不论断读者能否胜任这份工作。
第二种是智能体评估,通过模型上下文协议(MCP)提供。智能体把解析后的简历与招聘信息放在一起阅读,然后论断读者与该职位的契合程度。它通过 submit_judgments 提交自己的百分比。
共有词计数和智能体判断回答的是不同问题。共有词计数衡量的是重合度,不是契合度,所以标签必须写明作者是谁。计数报告简历与招聘信息共享了多少文本。智能体判断一个人与一份工作的契合程度。一份简历可以逐词复述招聘信息,却仍然描述一种较弱的契合。另一份简历用不同的词汇,却可以描述一种很强的契合。词数计数能发现第一种情况,会漏掉第二种,而智能体可以衡量两种情况。
卡片只显示一个分数。最近一次写入者决定它,一次评估会让报告围绕新数值重新排序。判断替换确定性评分,而不是并排显示。一个孤立的百分比掩盖了读者手里是两者中的哪一个。
文案必须在徽标行内、读者打开招聘信息之前说明作者。界面其余部分遵循同一条规则。
从启动台到结果
流程为启动台 → 设置向导 → 扫描 → 结果。当一次扫描超出客户端的工具调用时限时,它会交接给一个可轮询的状态,该状态持续保持运行,直到扫描结束。
第 3 到第 8 张卡片遵循这一顺序。第 2 张卡片讲评分,评分只在扫描结束后才存在,也是整页其余部分所指向的情形。第 1 张卡片提出问题,第 9 张卡片说明它们之间每段文案背后的约束。
一个评分位,两位作者
一个评分位,两种可能的作者。每次扫描都用确定性重合度计数为每张卡片评分。但一份 MCP 评估会用自己的推理覆盖该数字。如果没有清晰的标签差异,读者无法判断是谁设定了分数,也就无法校准信任。内容问题就是要在徽标行内、在几个词的空间里区分作者。
区分计数与判断
同一份配置文件,同一个数字,两位作者。智能体设定了第一张卡片,所以它显示 92% MATCH。确定性评分器设定了第二张卡片,所以它显示 92% KEYWORD OVERLAP。标签指明作者。只看到 92% 的读者无法区分两者。评估在同一个位置覆盖重合度分数,因为计数与判断回答的是不同问题。
92% KEYWORD OVERLAP表示共有词计数,即把简历与招聘信息作比较。92% MATCH表示智能体通过论断读者与职位的契合程度而得出的数字。
扫描会为它生成的每张卡片写入计数,无论扫描从终端启动,还是通过 MCP 调用 run_sweep。只有提交了 match_pct,才会用 MATCH 替换它。
PDF 排名行用方括号重复标签:#1 // COMPANY | [92% MATCH] 或 [92% KEYWORD OVERLAP]。CSV 把 match_value 写在 match_kind 旁边,以机器可读的形式给读者同一个事实。匹配分数旁还可以出现第三个分数。[88% PORTFOLIO FIT] 出于同样的理由打印自己的标签,因为你的作品样本回答的是与简历不同的问题。
申请徽标先读文本,再读颜色。[STANDARD / QUICK APPLY] 标记标准提交,[EXTENDED RESPONSES REQUIRED] 标记需要写作样本的职位。第三张卡片在排名行上打印 [EXTENDED RESPONSES REQUIRED],该行同时列出简历轨道。两个标签在无颜色时同样有效,这对无障碍访问以及不渲染颜色的终端都很重要。
一行之内说明身份、范围和就绪状态
Current profile: none loaded / build one to start 在一行内说明缺失状态和下一步操作。Current profile: Alex Rivera / 4 titles / Ready 在第一个位置确认姓名,在最后一个位置确认就绪状态。每条斜杠分隔一个答案与下一个答案,而且该行在边框处截断而不换行。当保存的配置文件没有简历路径时,Resume missing 替换 Ready。
在终端里,状态行是唯一持续存在的语境。它同时读作页头和就绪指示。
动词、宾语,然后是读者的目标
START SWEEP 与 Run your job search now 配对。每张卡片打印两行:一个名称,以及一个用读者自己的话重述 Enter 键作用的副标题。SWEEP SETTINGS 显示 Ranking, cards, tracking。SWEEPY'S TOOLBOX 显示 Edit profile, logs, help。EXIT SWEEPY 显示 Save changes and close,承诺保留你的工作。
操作卡片以动词及其宾语开头。其他卡片标注一个位置或一个退出项。副标题用平实语言解释任何内部术语。两位数编号标识每张卡片,而不是给网格排序。第一行把 01 与 04 配在一起。新卡片加入网格时无需重新编号其他卡片。导航依靠方向键和 Enter 键运行。
提示内的格式说明
提示把问题保持在一行,当格式重要时,把规则缩进放在下方:
What job titles are you looking for?
(Separate multiple titles with a comma)
薪资提示把跳过选项写进问题本身:
What is your minimum target salary? (Leave blank to skip):
规则出现在做决定的那一行。读者留在同一屏幕上。终端没有工具提示可以退而求其次。
修改答案而无需重跑向导
向导运行十五个步骤,Esc 每次回退一个问题。复核界面列出十一个条目:← Back,然后是 Submit profile,再后是九个操作。Edit an answer 就在 Submit profile 正下方。修改与提交只隔一行。想改答案的读者不必重跑每个提示。
五个步骤的阶段标签
命令行运行会标出五个带编号的阶段,每个阶段都说明工作内容。
[1/5] Loading profile...
[2/5] Discovering roles...
[3/5] Validating URLs...
[4/5] Scoring against resume...
[5/5] Generating reports...
日志行说明阶段编号。MCP 进度载荷则写明条目:四个职位名称中的第一个显示 total 4 中的 step 1,标签为 Discovering roles: Paralegal。Scoring roles 在评分器工作时报告入围名单。读者看到运行进行到哪一步、还剩什么。进度条会暗示一个工具无法知道的时长。
返回任务 ID 的等待
实时扫描可能运行一分钟或更久。在 MCP 模式下,工具调用返回运行时状态,而不是等待整次扫描完成。这让调用留在客户端超时范围内,并告诉调用方工作仍在继续。
run_sweep 默认等待 45 秒。wait_seconds 设定该等待时间,限制在 0 到 600 之间,而 SWEEPY_MCP_WAIT_SECONDS 在限制更紧的主机上降低上限。运行时状态包含 job_id、progress 对象、elapsed_seconds 值和 message:
{
"status": "ok",
"sweep_status": "running",
"job_id": "<job id>",
"progress": { "step": 3, "total": 5, "label": "Validating URLs" },
"elapsed_seconds": 41.2,
"debug_log": "<path>",
"message": "The sweep is still running. Call get_sweep_status to wait for it, then continue with get_jobs."
}
客户端用 job_id 轮询 get_sweep_status,直到 sweep_status 读作 "completed"。无论客户端是否保持连接,Sweepy 都会跨过这次交接继续工作。文案必须落在超时之内,并且对稍后重连的客户端也读得通。这是一个报告进度的运行时状态。
这 45 秒是产品默认值,由 _DEFAULT_WAIT_SECONDS 设定,并由 _MAX_WAIT_SECONDS 封顶。progress 和 elapsed_seconds 每次运行都会变化,debug_log 也一样。message 写明下一个工具调用,而不是复述调用方已有的数字。
无处藏匿薄弱文案
界面只依靠文本,边框会截断任何过长内容。标签必须自足,因为屏幕上没有别的东西解释它。状态消息说明读者所处位置,没有旋转指示器可以依赖。
命名规则由此而来。START SWEEP、LOAD PROFILE 和 BUILD PROFILE 以动作为先。它们的副标题把它重述为读者目标,因此谁都不需要「配置文件」这个内部概念就能知道接下来会发生什么。评分标签把同一条规则应用到数字上。KEYWORD OVERLAP 标记确定性计数,MATCH 标记智能体的判断。
边框宽度截断长文案
终端定下条件。文本是唯一解释事物的层,边框会截断任何过长内容。错误必须在同一段文案里说明问题与解决办法。读者无法离开这一行去读另一行。
文案自己承担语境成本。Could not parse salary %r. Enter a number like 65000, 65,000, or 65k. 报告什么失败了以及该改输什么,其中 %r 会被替换为被拒绝的输入。Current profile: none loaded / build one to start 对缺失的配置文件做了同样的事。图形界面可以把这两句话的后半段放进工具提示。在这里,同一行包含两半。
标签是唯一的解释
评分标签说明数字由谁写出。文档把它说得很直白:「MATCH 卡片反映判断。KEYWORD OVERLAP 卡片反映共有词。」一张卡片上只有一个分数旁打印一个标签。读者在打开招聘信息前就知道自己拿到的是哪一种主张。
每个词还告诉读者,是哪种比较产生了这个数字。KEYWORD OVERLAP 针对两份文档。MATCH 针对一个人和一份工作。期待这两个数字对得上的读者会误读其中一个。
标签跟随作者,而不是界面。智能体可以提交判断而不带百分比。那张卡片仍然显示 KEYWORD OVERLAP,因为扫描写入了那个数字。执行路径存在于卡片之外。报告文件名用 mcp 标记 MCP 运行,日志页头打印执行方式。
卡片命名遵循同一条规则。BUILD PROFILE 说明动作,其副标题 Set up your job search 去掉内部术语,换成读者的目标。LOAD PROFILE 写 Open a search you saved,描述这张卡片做了什么。
我写了什么,以及如何核对
角色: 本案例研究引用的产品文案的唯一作者。先写启动台副标题和向导提示,再写进度消息和校验文案。评分来源标签和客户端转发的 MCP 交接 message 最后完成。我借助 Copilot 和 Gemini 指导构建,遵循仓库级智能体准则和 CI 质量门。我对照 Sweepy 源代码核对了字面产品文案。
先校准信任,再行动
读者应先校准信任,再依据分数行动,并在等待时知道系统正在做什么。界面无法解释 Sweepy 如何得出一个数字,也无法解释某个过程需要多久。标签和状态文案用最少的词说明这一点,采用不依赖视觉提示也能工作的形式。
十五个提示,按顺序
向导运行十五个步骤。十五个顶层提示按顺序出现,是非题渲染为是/否选择器。
? What is your name?
>
? What job titles are you looking for?
(Separate multiple titles with a comma)
>
? Where do you want to work? (City, State):
>
? Do you want to see remote-only roles? (Y/n)
? Do you want to include hybrid roles? (Y/n)
? What is the path to your resume PDF?
>
? What is your minimum target salary? (Leave blank to skip):
>
? Which boards do you want to search? Pick from any engine; downloaded engines are labeled.
? Do you want to add custom platforms or ATS domains? (Y/n)
? Enter must-have skills or keywords to prioritize
(comma-separated, leave blank to extract from resume):
>
? What export formats do you want?
[x] PDF Report
[x] CSV Spreadsheet
[ ] JSON Data
? Add job-tracking columns to the CSV? (date applied, status, interview stage,
offer, follow-up date, contact, notes) (Y/n)
? Do you want to configure multiple resume tracks
(e.g. Tech Writer vs UX Writer)? (Y/n)
? Do you have a portfolio, writing samples, or case studies to submit
with applications? (Y/n)
? Enable debug logging? (Logs are saved under logs/ in the application
directory): (Y/n)