从这里开始

看清配置,
少些困惑。

从“智能体为什么忽略了这条规则”出发,找到来源文件、加载依据和下一步操作。检查器界面与诊断说明目前使用英文,指南中的控件名称与界面保持对应。

安装 Sightline

需要在 macOS、Windows 或 Linux 上安装 Node.js 22 或更高版本。在项目目录中打开终端,运行以下命令,即可在浏览器中检查仓库。

npx --yes https://github.com/iamzwxyy/agent-sightline/releases/download/v0.3.47/agent-sightline-0.3.47.tgz ui

检查器会在本地读取项目配置和用户配置。使用时保持终端运行,结束后按 Ctrl+C 停止。

如需重复使用,请安装 v0.3.47 CLI 包。

下载 CLI 安装包 ↓

运行依赖已包含在安装包中。下载后可离线安装,命令为 npm install -g --offline ./agent-sightline-0.3.47.tgz,也可直接从公开安装包 URL 安装。

npm install -g https://github.com/iamzwxyy/agent-sightline/releases/download/v0.3.47/agent-sightline-0.3.47.tgz

在浏览器中打开内置示例。示例包含故意设置的配置问题,并排除个人配置。

agent-sightline demo --ui

也可用一条命令打开示例。

npx --yes https://github.com/iamzwxyy/agent-sightline/releases/download/v0.3.47/agent-sightline-0.3.47.tgz demo --ui

安装包通过公开 GitHub Releases 和官网下载分发。npm 公共仓库首次发布仍待完成。

首次扫描

在仓库的任意子目录中打开终端并运行 CLI。Sightline 会找到最近的 Git 根目录,并纳入适用的祖先配置。它会发现文档规定的配置来源,报告可确定的问题。

相对目标路径以当前目录为基准。使用 --repo 可指定检查边界,并相对于该目录解析目标。诊断跟随所选目标和客户端。其他项目中发现的文件会保留其来源状态。要诊断这些文件,请选择对应目标或项目边界。

agent-sightline

运行 UI 命令,即可在浏览器中打开检查器,查看客户端概览和可操作的诊断。

agent-sightline ui

终端首次摘要会列出已加载指令来源、生效字节数、条件生效来源和截断情况。在浏览器概览中,选择 Inspect conditional loading(检查条件加载) ,即可打开来源,查看信任、批准或会话要求。

在顶部选择目标文件。可以按文件名、路径或模糊关键字搜索,再用方向键和 Enter 选择结果,也可直接输入路径。macOS 按 ⌘K,Windows 和 Linux 按 Ctrl+K,即可聚焦目标选择器。

追踪一条指令

在侧栏选择客户端。来源按加载顺序排列。选择文件后,可阅读来源预览、检查加载决策和精确的字节贡献。同一文件的重复行保留各自的加载决策与导入来源。在解释面板中打开导入来源,可定位声明行。重新加载和浏览器历史会保留本地报告与便携报告中选定的加载次数。

All discovered(所有已发现来源)包含已忽略和被覆盖的文件,方便找到磁盘上存在、但未被客户端读取的配置。按 / 搜索来源路径及导入来源。可以组合多个关键词,例如 shared beta.md:3 可查找特定导入。匹配忽略大小写和斜杠方向。如果 In scope(作用域内)隐藏了匹配来源,选择 Show all discovered(显示所有来源)即可显示并聚焦它们。清除搜索会恢复结果,并将焦点移回搜索框。Tab 只进入列表一次,随后用方向键或 Home/End 移动,按 Enter 选择。跳转来源后,焦点会移到带加载状态的文件名标题。Shift+Tab 返回来源列表。长列表会在来源跳转、重新加载及浏览器历史导航后显示选定行。桌面搜索与筛选器位于滚动列表上方。来源溯源和指令覆盖链接会清除来源搜索,让目标显示在列表中。浏览器前进或后退也会清除排除目标的搜索条件。

Claude 按需加载的指令使用已捕获的模型和上下文配置来确定字符预算。截断来源会显示原始文件中第一个未加载字符的行号与列号。无法确定会话模型或上下文时,限制会保留为条件结果。修改模型后刷新,即可检查新的加载前缀。导出报告保留捕获时的检查结果。

切换到 Read effective text(阅读生效文本),即可阅读最终累积的指令。加载链中的每个来源都链接到定义位置。打开 Settings(设置),可搜索解析后的值、检查生效定义,并追踪被其替换的配置层。

终端也能提供相同的解释。

agent-sightline explain src/payments/refund.ts --client codex --trust trusted

目标文件目录用于模拟新智能体会话的启动目录。信任选择器改变模拟假设,不会修改客户端保存的信任设置。

检查 Codex 配置档

如果使用 --profile review 启动 Codex,请在 Sightline 中检查相同的配置档。它在用户默认配置之后、项目配置之前加载 $CODEX_HOME/review.config.toml。选择设置即可追踪生效定义及被替换的定义。

agent-sightline explain src/payments/refund.ts --client codex --profile review --trust trusted

本地检查器的 Codex profile(Codex 配置档)字段可选择同一文件。清空并应用,即可返回基础配置。所选配置档在重新加载后保持,并写入报告快照。配置档依赖用户配置,因此 --no-user 会排除它们。

对比不同客户端

打开 Compare clients(对比客户端),可查找不同来源文件中的相同指令段落。筛选共同内容或接收客户端不同的内容,再从每次出现的位置跳转到对应客户端与原始行。重复段落会保留每次出现记录。还可并排查看精确的已加载文本,并查看来源与客户端的覆盖矩阵。选择自己使用的客户端,启用 Differences only(仅差异),集中查看加载差异。点击任意状态可检查来源及该客户端的加载原因。

覆盖范围包含结构化导入和各客户端的配置角色。若一个状态包含多次贡献,点击后可查看每次出现的位置及来源行。

扩展对比展示 MCP、技能、钩子和权限的命令与定义。每个生效和条件生效候选都有独立的操作入口和加载状态。选择定义可检查其配置及来源。

agent-sightline diff src/payments/refund.ts --clients codex,claude,copilot

客户端选择、内容筛选、Differences only 和展开的段落会在重新加载与浏览器历史导航后保留。Refresh scan(刷新扫描)保留当前对比,Export report(导出报告)会保存它,供离线查看和再次分享。

逐行对比会对齐两个所选客户端已脱敏的生效文本。选择左右客户端,显示未修改行以补充上下文,并用 Inspect sources(检查来源)打开客户端的加载链。行号对应屏幕上的生效文本。视图会标记对齐后的新增与删除,并突出替换内容中变更的词和字符。Emoji 与组合重音字符保持完整。较大的替换仍保留完整的行级高亮。长对比可展开前 200 行之后的内容。所选客户端组合、上下文和已展开行会在重新加载、刷新与离线分享后保留。

分享检查结果

Export report(导出报告)会生成独立的 HTML 快照。打开文件会恢复所选视图和来源位置,包括客户端、导入次数和高亮行。Read effective text 模式也会恢复。离线报告可重新导出,分享新的查看位置。带视图或来源片段的浏览器链接会打开对应位置。报告包含交互式来源浏览、客户端对比和诊断。相关来源会链接到所属客户端及来源行。跳转后会显示选定行。重新加载、浏览器前进和后退会在本地和便携报告中保留该行。使用键盘遍历来源后,重新加载也会显示链接行。Refresh scan 会在本地检查器中保留所选行。刷新后,固定工具栏会汇总当前错误、警告和发现覆盖范围,可继续选择 Review findings(查看诊断)或 Review scan scope(查看扫描范围)。阅读长来源时,导航和导出始终可用。本地检查器还会持续显示目标控件和扫描错误。Copy location(复制位置)会复制文件系统诊断的路径和位置。可直接在浏览器打开报告,或发送给队友。

agent-sightline report --format html --output report.html

快照会替换已捕获的仓库路径、主目录路径、已验证配置别名和自定义智能体根目录,并脱敏环境变量、请求头的值及已识别的密钥。自然语言或 shell 片段中无法识别的路径可能保留。分享前请检查个人信息。

v0.3.47 会隐藏指令截断边界处分割的已捕获私密值。分享前,请重新生成并替换受影响的旧报告。现有导出文件保留生成时的内容。

v0.3.13 修正了 Copilot 对目录别名、软链接越界,以及格式错误或冲突声明的保存信任匹配。请重新运行受影响的 v0.3.11 检查,更新工作区 MCP 和项目设置状态。

v0.3.11 会在检查边界包含活动 Copilot 配置目录时保护个人状态预览。在此条件下,v0.3.10 可能把内部 config.json 状态包含在 JSON 和 HTML 预览中。分享前请检查受影响的旧报告。

v0.3.10 修复了格式错误 TOML 中复制值的脱敏。在 v0.3.9 中,如果该文件中的环境变量值重复出现在已加载指令里,就可能进入报告。分享前请检查受影响的旧报告。

查看英文示例报告 →

在 CI 中发现配置错误

仅发现仓库配置,可让 CI 扫描结果可复现。设置应该导致构建失败的诊断严重程度。

agent-sightline ci --no-user --fail-on warn --json

退出码 0 表示检查完成且未达到阈值。退出码 1 表示诊断达到阈值。退出码 2 表示输入或检查错误。规则 ID 和 JSON schema 版本 1.0 支持脚本集成。

了解检查范围

Codex 0.167.2 的基础及项目标量配置、MCP 值和生效文件,已在 23 个隔离场景中与原生配置 API 对照。另有 21 个脚本化原生请求,对比精确的 AGENTS.md 正文、字节限制、override 选择、根标记、信任,以及所选配置档的预算和回退文件名。其他配置档字段与来源行号使用版本固定的源码及 schema 样例。Codex 技能名称、规范文件路径、启用状态及用户和项目作用域,也有原生清单对照,覆盖目录链接和禁用路径。98 个隔离的原生 Claude Code 2.1.322 场景对比指令顺序、精确加载文本、模型和上下文字符预算、规则文件导入、AGENTS 模式、路径级加载及已保存的外部导入批准。路径规则在启动时展开导入,其自身正文等待匹配的文件。会话目录之外的项目导入使用独立保存的批准,并保留待批准和已拒绝状态。链接工作树使用共享的 Git 项目标识。标准 .git 目录选择主检出目录,独立 Git 目录保留自己的键。Windows 启动别名与规范路径不同时会保留独立条目,批准键使用正斜杠。MCP 传输、批准边界和 stdio 目录行为也与原生 CLI 对照。11 个原生本地作用域注册,验证目录别名、子目录、非 Git 会话、更宽检查边界、链接工作树及独立 Git 目录中的保存项目键。本地服务器会替换同名用户和项目候选,无效的本地声明则保留符合条件的低作用域定义。19 个隔离权限检查通过回环脚本 API 验证原生工具执行、deny/ask/allow 优先级及工作区授权准入。工作区信任未显式模拟时,本地授权保留 Git 和会话条件。Copilot CLI 1.0.110 的设置合并、个人别名、文件加载、工作区 MCP 准入和共享 Claude 规则发现,已与原生配置 API 及 CLI 清单对照。个人设置 schema 仅部分覆盖。其他 Claude 能力使用带可执行样例的官方文档契约。Gemini 树形和扁平上下文导入,与公开 0.68.0 处理器有 31 个可执行对照。导入文本保留来源片段和客户端原生的上下文边界。Gemini、Cursor 和 OpenCode V2 的适配器为实验性支持,覆盖部分能力。

在检查器中打开 Scan scope & rule versions(扫描范围与规则版本),可查看官方来源链接和各适配器限制。命令行覆盖、运行中会话开关、已安装插件和远程托管策略可能贡献额外配置。

默认发现预算为 50,000 个仓库条目,以及每个用户配置根目录 4,000 个匹配文件。使用 --max-entries 和 --max-user-files 可调整预算。即使筛选了诊断,不完整的发现状态仍会显示在检查器和导出报告中。

扫描在本地运行,无遥测、模型调用或上传。默认扫描会读取仓库及文档规定的用户配置位置。添加 --no-user 可仅发现仓库配置。使用 --system 检查 Claude 托管设置、策略片段及独占的 managed-mcp.json。被阻止的 MCP 条目会链接到排除它的策略。无关的外部私有目录树会被跳过。

默认扩展诊断检查发现与配置。显式运行 doctor --probe 会启动本地 stdio MCP 进程,初始化并列出工具。启动服务器代码可能产生副作用。扫描不会执行钩子命令或 MCP 工具。

复制这条命令

按 ⌘C 或 Ctrl+C 复制选中的命令。在手机上,长按文本并选择“复制”。