使用只读 Agent 任务指令审查文档失效链接

开始前的准备工作

这是一次由你手动执行并核验的审查。Cue 提供语音输入以及针对所提供素材的可选 Agent 辅助。安装 Cue 并不意味着 Agent 能读取你的代码仓库、访问内网、爬取网站或编辑文件。

开始前，请确保具备以下各项：

• 已安装 Cue 且 Dictation 功能正常。确认麦克风权限以及 Cue 在你的操作系统中所要求的输入或辅助功能权限。请使用 Cue Settings 中显示的快捷键，而非从别处看到的组合键。本指南默认你已掌握 Dictation 教程中的焦点定位、录音状态与文本插入检查步骤。
• 可编辑的草稿便签。请在草稿输入区开始，切勿直接在终端提示符或自动发布的文档中操作。在提交到任何地方之前先审查指令文本。
• 可随时删除的文件夹。下方练习会创建 7 个小文件。请将其放置在可丢弃的目录下。切勿在真实代码仓库中构建测试集，以免随手执行 git add . 导致意外提交。
• 日常使用的终端，或显示行号的文本编辑器。你可以手动检查每个文件；并不强制要求执行 Shell 命令。
• 自行连接的 Agent。已安装的 Cue 可能在 Agent 选择器中显示 Cue、Claude、Codex 和 Gemini。列表可见并不等同于已连接、已登录、已获授权或能够读取你的磁盘。在你认定报告反映了对文件的真实读取之前，请在自己的软件副本中确认这一点。
• 处理范围内不含机密信息。不得包含凭据、令牌、私有 URL 或客户文档。该练习完全由虚拟内容构成，便于你在脱敏环境下练习。

有一项决定权属于你，而非任何 Agent：即何为“失效”。在审查前请先明确，在你的项目中，锚点缺失、无法访问的外部站点、文件名大小写不匹配或代码示例中的链接是否算作缺陷。若无此定义，审查只会产生一份无人能据此行动的混乱列表。

实战练习：Orchid Notes 文档测试集

Orchid Notes 是为本次练习虚构的笔记应用。以下文件均为练习素材，非 Cue 官方文档，亦非真实项目。外部地址均采用保留后缀 .invalid。这并不是网络沙箱：切勿请求这些地址，审查期间请保持网络访问处于禁用状态。请将其归类为未检查，而不是赋予未经核实的状态。

创建一个名为 link-audit-fixture 的文件夹，并将这 7 个文件放入其中。路径必须严格保持一致——部分植入缺陷依赖于具体的目录结构。

index.md

# Orchid Notes documentation

Orchid Notes is a fictional note-taking app used only for this exercise.

- [Getting started](./getting-started.md)
- [Install guide](./guides/install.md)
- [Troubleshooting](./guides/troubleshooting.md)
- [API reference](./reference/api.md)
- [Uninstall guide](./guides/uninstall.md)
- [Release notes](./CHANGELOG.md)
- [Support mailbox](mailto:support@example.invalid)

![Architecture diagram](./assets/architecture.png)

getting-started.md —— 请注意，第 12 至 14 行是展示链接语法的围栏代码块，并非供读者点击的链接：

# Getting started

Read the [install guide](./guides/Install.md) first, then open the
[API reference](./reference/api.md).

For offline setup, see [offline mode](./guides/install.md#offline-mode).

The legacy handbook lives at https://example.invalid/orchid/legacy-handbook.

Downloads are named like this in our release template:

```markdown
[Download the installer](./dist/orchid-1.2.3.dmg)
```

See [release notes]() for the full history.

CHANGELOG.md

# Release notes

## 1.2.0
Adds the sync panel. See [sync settings](./reference/api.md#sync-settings).

## 1.1.0
Fixes the export bug described in [troubleshooting](./guides/troubleshooting.md).

## 1.0.0
First release. The old notes format is documented in
[the legacy handbook](./guides/uninstall.md).

guides/install.md

# Install

## Requirements

## Desktop install

Return to the [documentation home](../index.md) or continue to the
[API reference](../reference/api.md).

If the installer fails, read [troubleshooting](./troubleshooting.md).

guides/troubleshooting.md

# Troubleshooting

## Export produces an empty file

Check the [install requirements](./install.md#requirements).

## Sync never finishes

See the [sync notes](../reference/api.md#sync-settings) and the
[status page](https://example.invalid/orchid/status).

Still stuck? Open the [support checklist](../support/checklist.md).

reference/api.md

# API reference

## Sync settings

## Export endpoint

Back to [home](../index.md).

assets/diagram.png —— 创建包含任意内容的占位文件。其文件名至关重要；内容无关紧要，写入一行文本即可。

在运行任何操作前写下预期的失效链接清单

这是让练习发挥价值的关键一步。先写好标准答案，再对比报告内容。如果你先看报告，往往会不自觉地顺从其结论。

人为植入的缺陷 —— 共 7 处出现，对应 6 个不同目标：

干扰项 —— 绝不应出现在失效列表中的 6 项：

D-2 和 K-6 能暴露两类报告缺陷：如果报告将 D-1 和 D-2 合并而未保留两个源文件位置，说明它漏掉了需要审查的文件；如果报告将 K-6 列为失效，说明它要么凭空猜测，要么发起了未经许可的外部网络请求。

口述指令并选择执行路径

1. 构建测试文件夹，并将预期清单单独保存在其他位置。切勿将标准答案粘贴到 Agent 的上下文环境中；本次是在测试 Agent，包含答案的指令无法验证其真实能力。
2. 打开空白草稿便签并聚焦文本框。使用 Cue Settings 中配置的快捷键启动 Dictation，在说话前确认录音状态已就绪。
3. 清晰说出审查目标与边界范围。例如：“审查此文件夹中的 Markdown 文件，找出指向不存在的文件或标题的链接。报告每个缺陷的文件名、行号及确切目标。不要请求任何外部地址。不要编辑任何文件。单独列出所有未检查的项目。”使用设定的控制操作停止录音，等待处理完成，随后仔细阅读插入的文本。
4. 在将文本发送至任何地方之前完成校对。路径、文件扩展名、大写字母以及“不/不要”等否定词需要专门仔细校对：改动一字就可能改变任务性质。对于 link-audit-fixture、./guides/install.md 等字符串，建议直接从源处复制，而非口述。如果标识符频繁识别错误，请参考精确口述专业术语教程。
5. 从以下三种路径中选择一种，并清楚当前所处的路径。它们之间不可互相混淆。 直接口述至日常使用的 Agent：将光标聚焦于终端或编辑器中的编程 Agent 输入框，口述或粘贴校对后的指令。Cue 仅负责提供文本，Agent 自身的权限决定其能读取哪些内容。 在 Cue 内部选择外部 Agent：如果已安装的 Cue 提供了 Claude、Codex 或 Gemini 作为可选 Agent，请先确认该路径的连接、登录、项目及权限配置。切勿假设它会自动继承终端的工作目录或先前的对话历史。 使用 Cue 原生 Agent 并搭配指定模型：Cue 的模型选择器仅用于选择模型。它不会授予文件访问、终端访问或网络权限，也不会自动连接外部 Agent。如果不确定 Agent 能否读取该文件夹，请采用下方的第四种备选方案。
6. 手动备选方案：自行打开这 6 个 Markdown 文件，将不含敏感内容的正文连同文件名和行号一起粘贴至 Agent。它可以审查提供的文本，但仅凭粘贴内容无法验证你的本地磁盘。任何此类报告都应明确标记为“文本审查”，而非“文件系统审查”。
7. 对照预先写好的预期清单核对报告，而不是凭记忆中的测试集进行对比。逐一标记植入缺陷是检出还是遗漏，并确认额外的报告项目是属实还是虚构。
8. 完成后可删除测试集，或特意将其保留下来，作为评估后续 Agent 或模型时的回归测试用例。

复制只读审查指令模板

替换括号内的字段。在实际任务中切勿保留占位符，也不要为了让执行通过而擅自扩大权限范围。

任务：审查文档链接。只读执行。不得编辑、创建、移动或删除任何文件。
范围：[link-audit-fixture 的绝对路径]，仅限 Markdown 文件，不得包含外部子目录。
针对本次审查的失效定义：
- 目标文件不存在的相对链接或图片
- 链接指向目标文件中不存在的标题锚点
- 目标为空的链接
- 拼写与磁盘实际文件不一致的目标，包括大小写差异
超出范围项，请单独列出，切勿判定为失效：
- 外部 http 与 https 地址。请勿请求它们。允许列表：[无]
- mailto 与 tel 链接
- 出现在围栏代码块内部的链接（属于语法示例，非链接）
对于每处发现，请返回：文件路径、行号、书写的确切链接目标、
符合上述四类中的哪一类，以及你采用的依据。
若未打开某文件，请明确说明。若是推断而非实际检查，请明确说明。
将所有未能分类的链接列于“未检查”板块中，并说明原因。
暂勿提出编辑建议。不要运行任何写入命令。不要抓取任何网络资源。
仅输出报告。等待我的下一步指令。

“允许列表：无”这一行是刻意设定的。本次练习没有任何理由去抓取虚拟的外部地址。后续针对真实外部链接的审查需要独立的允许列表，并配合网络访问权限受限于该列表的工具。即便只读请求，仍可能泄露地址或触及私有、需鉴权或受频次限制的系统；只读并不等于离线。切勿仅仅为了让本次练习通过而向 Agent 提供凭据。

对报告进行评分与核验，而非单纯阅读

示例参考 —— 模拟数据，非真实 Agent 运行结果：假设某份报告列出了 D-1、D-2、D-3、D-6 和 D-7，同时误报了 K-5，并将 K-6 归入未检查项。这意味着它找出了 5 处植入缺陷，漏掉了 D-4 和 D-5，并产生了 1 处误报（K-5）。对于离线范围而言，将 K-6 保持未检查是正确的。在自行复核时，请清晰归纳这三类情况，而不是全盘接受一句笼统的“审查完毕”。

拿出 Agent 的报告和你的标准答案，在一轮核验中逐项比对。由你填写以下三列内容：

随后，将文件本身与审查前保存在 Agent 可写范围之外的基准快照进行对比。检查文件清单与内容哈希值。在代码仓库中，检查 git status 和 git diff，并在适当时检查未跟踪与已忽略的文件。干净的 Git 状态或未变更的修改时间均不能证明未发生过临时写入，也不能证明未读取或未外发数据。这些检查仅能确定最终文件状态；强制执行只读与离线边界依赖于工具权限，并以调用记录作为佐证。Agent 自称未作修改，并不构成其确实未作修改的证据。

将发现的结果按客观数量统计：7 个目标中指出了几个，凭空捏造了几个。不要将其换算为评分、百分比或准确率数值。在单个虚拟文件夹中植入的 7 处缺陷无法支撑这些指标，这类笼统数字的传播往往会脱离背后的实际依据。

漏掉了 D-4 和 D-5 的报告并非毫无用处 —— 它明确了你目前所用的能力边界。评分的意义在于了解该特定 Agent 在该特定路径下实际能够检查哪些类别，以便你知道哪些部分仍需由自己手动核验。

局限性

• 本方法仅用于审查包含 Markdown 文件的文件夹。它无法确定渲染后站点的状态、重定向、模板生成的链接、HTML 属性内的链接或构建阶段拼接的链接。那些场景需要爬虫工具以及完全不同的权限配置。
• 本流程完全不检查外部链接。这是设计使然。虚构的 .invalid 地址保持未检查状态；其保留后缀并不能证明工具没有发起网络请求。针对真实外部链接的独立审查需要经过审批的访问范围。
• 执行结果无报错并不意味着文档内容正确。链接可能解析到了错误的页面，页面虽然存在但也可能内容已过时。链接是否存在是最容易测试的属性，但绝非最重要的属性。
• 文本搜索并不等同于 Markdown 解析器。简陋的字符串搜索可能会将代码块内的示例误报为失效链接，同时漏掉裸 URL 或引用式链接。在将匹配项视作缺陷之前，请先确认文档渲染器的解析规则。
• 底层文件系统的行为存在差异。针对 D-4 的文件存在性检查取决于本地文件系统是否区分大小写。完全相同的审查操作在 Mac 与 Linux CI 运行环境中产生不同结论是完全合情合理的。
• 此处未验证任何内置链接检查器。本文介绍的是通过语音捕获审查指令并约束 Agent 行为边界的方法，而非 Cue 功能清单。特定 Agent 是否具备读取本地文件夹的能力，需在你的安装版本中进行确认。
• 单套测试集仅作为一个样本。在此表现良好，并不代表在庞大的真实代码仓库、更换模型或切换执行路径后依然表现一致。

步骤出错时的恢复方法

如果是 Cue 本身出现故障，请通过 联系 Cue 支持团队，并附上你的操作系统平台、Cue 版本、使用模式及脱敏后的示例。切勿发送私有文档、仓库内容或令牌凭据。

扩大规模前值得思考的问题

为什么先植入缺陷，而不是直接在真实文档上运行？ 面对不熟悉的文档，“未发现任何问题”可能掩盖了“根本未进行任何检查”。测试集让你在运行前掌握确定答案；而真实仓库仍需专门的覆盖范围核验。

评分一次后，测试集还需要保留吗？ 保留它的成本极低，且在更换模型、Agent 或路径时非常有用。请将其保存在任何公开仓库之外，并将标准答案保存在同一处，避免两者发生脱节。

可以直接让 Agent 修复失效链接吗？ 修复属于独立的、需要专门授权的任务，需经过单独审查，且这些缺陷中多数存在不止一种正确修复方案。例如 uninstall.md 缺失，既可以编写对应的新页面，也可以删除该链接，或是指向其他地址——这属于编辑决策。应先完成审查评分；再提出修复建议；最后由人工手动应用修改。

应该使用哪种模型？ 首先取决于该路径实际能够读取的内容，而非仅仅看模型名称。无法访问本地文件的模型理应如实说明该限制。但它也可能会就从未打开过的文件生成一份看似合理的假报告；本次练习正有助于暴露此类问题。能够诚实回复“未检查”的模型虽未完成审查，但至少没有编造结果。

参考资料与相关工作流

上述测试集、内置缺陷及展示的 Agent 行为均为练习素材。本指南中的任何内容均不构成对 Cue 或任何 Agent 的效果承诺。当前版本采用人工审查练习，而非可执行的链接检查脚本。你所安装的 Cue 版本、其可见控制项以及 Agent 的权限设置，均优先于本文所述内容。

• Cue Dictation 教程：焦点定位、录音状态与插入核验。
• Cue Voice Agent 教程：显式上下文与操作前的审查确认。
• Cue 与编程 Agent 协作：口述至现有工具、选择外部 Agent 与使用 Cue 原生 Agent（配合所选模型）之间的区别。
• 用 Codex 审查代码变更：将相同的事实依据核验规范应用于代码 diff 而非文档树。
• 口述精确技术术语：确保路径、版本号和各类标识符准确无误。
• 将选中上下文变为完成的任务：在审查整理出待办任务后，如何进一步推动落实。