Sightglass

追踪 AI 编码智能体的依赖选择与供应链风险，暴露训练记忆偏差与替代方案。

## 概述（中文）

追踪 AI 编码智能体的依赖选择与供应链风险，暴露训练记忆偏差与替代方案。

## 技能正文

# 🔍 Sightglass — 智能体供应链情报

你的 AI 编码智能体刚向项目添加了 47 个依赖。你知道它为何选择其中任何一个吗？

**Sightglass 为 AI 编码智能体插桩**，捕获每次工具选择、依赖安装与架构决策 — 然后浮现你从未见过的风险、偏见与更好替代方案。

## 为何重要

人类开发者选择依赖时有推理轨迹：读过的博客、比较的替代方案、团队讨论。AI 智能体选择时该轨迹不可见。智能体从训练数据「就是知道」包 — 意味着它偏向：

- 训练数据截止时流行的东西
- Stack Overflow 提及最多的包（不一定是最好的）
- 在类似项目中见过的依赖（不一定适合你的项目）

Sightglass 使这种不可见的决策变得可见。

## 发现分类

Sightglass 分类智能体**如何**发现每个依赖：

| 分类 | 含义 | 风险等级 |
|---|---|---|
| **TRAINING_RECALL** | 智能体从训练数据「就是知道」— 未执行搜索 | 🟡 中 |
| **CONTEXT_INHERITANCE** | 在现有项目文件中发现（package.json、imports 等） | 🟢 低 |
| **REACTIVE_SEARCH** | 智能体遇到问题并搜索解决方案 | 🟡 中 |
| **PROACTIVE_SEARCH** | 智能体选择前主动比较替代方案 | 🟢 低 |
| **USER_DIRECTED** | 人类明确告诉智能体使用什么 | ⚪ 无 |

高 `TRAINING_RECALL` 百分比是红旗 — 意味着智能体在自动驾驶，而非思考。

## 快速开始

### 1. 设置

```bash
./skills/sightglass/setup.sh
```

安装 CLI（`@sightglass/cli`）、运行初始配置并检查监视守护进程。

### 2. 登录

```bash
sightglass login
```

通过 [sightglass.dev](https://sightglass.dev) 认证以启用云分析与历史。

### 3. 监视

```bash
sightglass watch
```

启动后台监视器监控智能体会话 — 文件变更、包安装、工具调用。

### 4. 分析

```bash
sightglass analyze
# or
./skills/sightglass/analyze.sh --since "1 hour ago" --format json
```

## OpenClaw 集成

### 自动会话跟踪

Sightglass 为编码智能体会话提供前/后钩子：

**会话前** — `hooks/pre-spawn.sh`：
- 记录开始时间与项目上下文
- 确保监视守护进程在运行

**会话后** — `hooks/post-session.sh`：
- 分析发生的一切
- 输出摘要：发现的风险、训练回忆 %、错过的替代方案

### 与编码智能体配合使用

通过 OpenClaw 生成编码智能体时，用 Sightglass 包装：

```bash
# Before spawning
source ./skills/sightglass/hooks/pre-spawn.sh /path/to/project

# ... agent does its work ...

# After session ends
./skills/sightglass/hooks/post-session.sh
```

会话后输出如下：

```
📊 Session Summary
  Dependencies added: 12
  Risks found: 3
  Training recall: 67%
  Alternatives missed: 5

  ⚠️  Run 'sightglass analyze --since ...' for details
```

67% 训练回忆意味着三分之二的包是从记忆中直接抓取、零比较购物。Sightglass 将展示存在哪些替代方案。

## 命令参考

### CLI (`@sightglass/cli`)

| 命令 | 说明 |
|---|---|
| `sightglass init` | 在项目目录初始化 Sightglass |
| `sightglass login` | 通过 sightglass.dev 认证 |
| `sightglass setup` | 交互式首次配置 |
| `sightglass watch` | 启动监视守护进程 |
| `sightglass analyze` | 分析智能体会话与依赖决策 |

### 技能脚本

| 脚本 | 说明 |
|---|---|
| `setup.sh` | 安装 CLI、配置、验证监视器 |
| `analyze.sh` | 独立分析，支持 `--since`、`--session`、`--format`、`--push` 标志 |
| `hooks/pre-spawn.sh` | 会话前钩子 — 记录开始、确保监视器 |
| `hooks/post-session.sh` | 会话后钩子 — 分析并摘要 |

### analyze.sh 标志

```
--since <time>     Analysis window start (ISO timestamp or relative like "1 hour ago")
--session <id>     Analyze a specific session by ID
--format <fmt>     Output format: text (default), json, markdown
--push             Push results to https://sightglass.dev
```

## Sightglass 呈现的内容

每个智能体会话你将获得：

- **依赖清单** — 每个添加、移除或升级的包
- **发现方法** — 智能体如何发现每个包（训练回忆 vs 搜索）
- **风险标记** — 已知漏洞、无人维护的包、更好替代方案
- **替代方案报告** — 智能体*本可*选择但未考虑的方案
- **偏见指标** — 显示训练数据影响而非理性选择的模式

## API

认证后所有数据同步到 [sightglass.dev](https://sightglass.dev)。在 analyze 中使用 `--push` 或在 setup 中配置自动推送。

---

*智能体的依赖就是你的依赖。知道它们从何而来。*