Charlie-Wang-03/dsh-sightline

English · 简体中文

Sightline

同一个仓库，不同的 Agent，不同的规则。

在同一个仓库、同一个工作目录下，直接比较 DeepSeek Harness 实际加载了哪些工作区指令，以及 Codex 和 Claude Code 按各自规则会加载哪些指令。

状态：v0.1.0。 首个公开版本现已通过 npm 与 GitHub Releases 发布。核心比较、DSH 运行时观测、Codex / Claude 预测、可安装的 DSH Bundle、clean-profile 验证以及专用 DSH Web ToolView 均已实现并测试。

为什么需要 Sightline

一个仓库可能同时存在：

- AGENTS.md；
- CLAUDE.md；
- 嵌套目录中的局部指令；
- 用户级全局指令；
- .claude/rules/。

DeepSeek Harness、Codex 和 Claude Code 并不会以完全相同的方式发现和加载这些内容。

结果是：

你以为一个仓库只有一套 AI 指令，实际上不同 Coding Agent 看到的可能是三套不同的有效指令面。

Sightline 把这种原本隐藏的差异放到一张表里。

你会看到什么

Same repo. Different agents. Different rules.

DSH        Codex       Claude
Observed    Predicted    Predicted
AGENTS.md             ●           ●
CLAUDE.md              ●                       ●
packages/api/AGENTS.md ●           ●
.claude/rules/always.md                         ●

DSH Web ToolView 使用同一份 canonical report，并明确显示 Observed / Predicted / Unavailable 与 Present / Absent / Unknown 状态。

| Agent | v0.1 证据类型 |
| --- | --- |
| DeepSeek Harness | 在可用时，从当前 DSH Session 的持久化 typed instruction provenance 中获得 Observed 证据 |
| Codex | 根据公开规则与本地文件推导 Predicted 结果 |
| Claude Code | 根据公开 memory / rules 语义与本地文件推导 Predicted 结果 |

Sightline 不会把预测结果包装成运行时观测事实。

安装

v0.1 的主要公开分发方式是预构建 npm 包：

dsh plugin --profile web add dsh-sightline@0.1.0

该包已在 npm 发布为 dsh-sightline@0.1.0。从源码或本地 tarball 开发时，请阅读 docs/PACKAGING.md。

使用

安装后启动 DSH Web：

dsh web

在一个位于 Git 仓库中的 DSH Session 里，可以直接让 Agent 调用 sightline，例如：

Use sightline and tell me where the DSH, Codex, and Claude instruction views diverge.

Sightline 会基于同一个实时 Session cwd 与同一个仓库根目录解析三列结果。

v0.1 做什么

1. Discover：发现与三类 Agent 相关的指令来源；
2. Resolve：分别得到三类 Agent 的有效指令面；
3. Compare：使用确定性的结构规则比较差异；
4. Visualize：在 DSH 中展示一致、分歧与未知状态。

首个版本刻意不做：

- 指令质量评分；
- LLM 语义冲突检测；
- 自动重写或同步 AGENTS.md / CLAUDE.md；
- token 优化；
- CI drift gate；
- 对模型是否真正遵循某条指令作保证。

架构

live DSH tool call + workspace
|
+---- exec.agent.session ----> DSH adapter ------ Observed ----+
|                                                              |
+---- ctx.fs ---------------> Codex adapter ---- Predicted ----+--> canonical report
|                                                              |
+---- ctx.fs ---------------> Claude adapter --- Predicted ----+
|
+--> model-facing projection
+--> DSH Web ToolView

不同 Agent 的发现与优先级语义都封装在各自 adapter 中；比较层本身保持纯函数、与具体 Agent 无关。DSH Hosted 模式下的文件系统读取通过公开 ctx.fs capability 完成。

隐私与信任边界

Sightline 是 local-first、read-only 工具，但 local-first 并不意味着所有 DSH Tool Result 永远不会离开本机。

- Sightline 自身不会调用任何 Sightline 自有的远程服务；
- Sightline 不会修改工作区指令文件；
- 完整 canonical report 会作为 DSH Tool metadata 保留，供 Web ToolView 与 replay 使用，其中包含 repositoryRoot / cwd 等工作区身份信息；ToolView 可能显示绝对 Session cwd 与完整 diagnostic message。任何能够访问该 DSH Web Session 的人都可能看到这些信息，其访问控制由 DSH Web 自身负责；
- 发送给模型的文本投影更窄：默认只包含 source identity、evidence label、presence state 与 diagnostic code，并省略绝对工作区路径和完整 diagnostic message；
- 这部分 model-facing output 与其他 DSH Tool output 一样，由当前 Session 配置的模型 / Provider 处理；
- Sightline 不会把指令文件正文上传到 Sightline 自有服务。

完整边界见 docs/PRODUCT_CONTRACT.md 与 SECURITY.md。

兼容性

v0.1 当前验证基线：

- DeepSeek Harness 0.1.1-rc.2；
- upstream DSH commit b150a551b8d465e31e418e1b2eaf5e79bbb7d28e；
- Node ^22.19.0 || >=24.0.0；
- pnpm 11.7.0。

DSH 仍处于 Developer Preview，因此 Sightline 只声明实际验证过的版本兼容性，不对未验证的新版本做宽泛承诺。

Codex 与 Claude Code adapter 同样保留独立的 compatibility identity。对于 Claude path-scoped rules，如果仅凭 cwd 不能确定规则已经激活，Sightline 会保守地标记为 deferred，而不是猜测。

详见 docs/COMPATIBILITY.md。

验证

当前自动化覆盖包括：

- package / bundle / client surface；
- Codex 全局、项目、嵌套、override、fallback 与 byte budget；
- Claude user / project memory 与 always-loaded rules；
- Claude path-scoped rule 的 fail-closed 行为；
- DSH durable provenance folding；
- 真实 ToolRuntime + SessionStore + dsh-fs-local Host 集成；
- canonical 三列表生成；
- clean-profile packed-artifact 安装与导出解析；
- browser ToolView 注册 / 渲染 smoke；
- Windows / POSIX 路径归一化。

本地验证命令：

pnpm run check

文档

| 文档 | 作用 |
| --- | --- |
| docs/PRODUCT_CONTRACT.md | v0.1 产品、证据、隐私与非目标边界 |
| docs/ARCHITECTURE.md | 系统边界与数据模型 |
| docs/DSH_RUNTIME_SEAM.md | DSH authoritative provenance seam |
| docs/DSH_HOST_TOOL.md | live Session ownership 与文件系统绑定 |
| docs/COMPATIBILITY.md | resolver / runtime compatibility identity |
| docs/PACKAGING.md | npm / bundle 打包与 clean-profile 验证 |
| docs/RELEASE_CHECKLIST.md | v0.1 公开发布 Gate |

贡献

欢迎高质量 Issue 和聚焦的 Pull Request。进行非小型修改前，请先阅读 CONTRIBUTING.md 与 AGENTS.md。

安全问题请按 SECURITY.md 的方式报告。

License

MIT，见 LICENSE。

项目关系

Sightline 是 DeepSeek Harness 生态中的独立社区项目，并非 DeepSeek 官方产品；除非 DeepSeek 官方明确说明，否则不代表任何官方认可或背书。