# View Your Harness

> 把一个本地目录变成可浏览的可视化工作台，一屏看清「我有哪些文件」和「我有哪些 Skill 可用」。起一个本地只读服务，浏览器里出目录卡片墙、文件清单、Skill 装备台（带真实调用次数和僵尸标记），支持全局搜索、按类型/时间/体量筛选、点开预览、用系统程序打开或在访达中定位。当用户说「打开工作台」「可视化看一下这个目录」「我有哪些 Skill」「我有哪些文件」「这个文件夹里都有什么」「看板」「dashboard」「浏览我的 harness」时触发，也适用于用户直接甩来一个本地路径要求「看看里面有什么」的场景。

- Skill: `spacezephyr/view-your-harness` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add spacezephyr/view-your-harness`
- Raw SKILL.md: https://api.skillmd.com/api/skills/spacezephyr/view-your-harness/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: spacezephyr (https://skillmd.com/u/spacezephyr)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/spacezephyr/view-your-harness

---


# view-your-harness

把一个本地目录清点成一个能浏览、能搜、能点开的工作台。

跟另外两个是一套：[star-your-harness](https://github.com/SpaceZephyr/build-your-harness) 负责**搭**，
better-your-harness 负责**体检**，这个负责**日常看**。

体检回答「我这儿哪里有问题」，工作台回答「我这儿都有什么」。后者是前者的前置——
155 个 Skill 你根本记不住有哪些，2000 篇笔记散在 52 个目录里你也找不着，
这种时候需要的不是一份报告，是一个能翻的架子。

## 铁律

**1. 只读。这个 Skill 不改用户任何文件。**
服务端没有写、改、删接口，这是设计约束不是待办。「可操作」的边界就是打开和定位——
调系统的 `open` 把文件交给用户自己的编辑器和访达。用户要改东西，让他在编辑器里改，
或者去用 better-your-harness 的修复口令。不要为了「更方便」私自加写接口。

**2. 所有路径都必须校验落在 root 之内。**
`serve.py` 的 `safe_join` 会 resolve 后比对，越界返 403。Skill 卡片的绝对路径额外白名单
`~/.claude` 和 `~/.codex`。改动服务端代码时不要绕过这一层——它是本地服务唯一的边界。

**3. 数字只能来自 `index.py`，你不许在对话里编。**
文件数、Skill 数、调用次数，全部以 `index.json` 为准。脚本没统计的量就说「未统计」。

## 流程

### 1. 起服务

```bash
python3 ~/.claude/skills/view-your-harness/scripts/serve.py <目录>
```

它会先跑一遍索引（几秒到半分钟，看目录大小），然后起服务、自动开浏览器。
终端会打印端口和实际盘的路径。Ctrl-C 停止。

常用参数：

| 参数 | 用途 |
|------|------|
| `--port 7799` | 指定端口。被占用会自动往后顺延，一般不用管 |
| `--no-open` | 不自动开浏览器（远程/无头环境） |
| `--no-usage` | 跳过会话日志统计。日志多的时候能快很多，代价是没有调用次数 |

**这是个前台进程。** 用 `run_in_background` 起，把 URL 报给用户，不要傻等它退出。

### 2. 交付

告诉用户三件事就够了：地址、盘的是哪个目录、按 Ctrl-C 停。
然后用一两句话说说清点结果里最扎眼的是什么（比如「155 个 Skill 里 130 个从未调用过」）。

**不要把文件清单在对话里念一遍。**清单就在页面上，念一遍等于把工作台又变回了聊天记录。

### 只要数据不要界面时

需要拿清点结果做别的分析（比如喂给另一个 Skill），单独跑索引器就行：

```bash
python3 ~/.claude/skills/view-your-harness/scripts/index.py <目录> -o /tmp/index.json
```

## 工作台里有什么

**顶栏**：目录路径、文件数、目录数、总体量、Skill 数、用过 / 没用过。
一个搜索框同时搜文件名、文档标题、Skill 名称和描述。按 `/` 聚焦，`Esc` 关抽屉。

**文件页**

- 左侧按文件数排的一级目录，点击下钻
- 卡片显示文档标题（Markdown 的 frontmatter title 或第一个 `#`，比文件名有用得多）、
  类型、体量、最近改动
- 按类型筛（文档/代码/数据/图片/音视频/配置），按最近改动 / 体量 / 名称排

**Skill 页**

- 每个 Skill 一张卡：名字、description、**真实调用次数**、文件数、体量、最后更新
- 筛选：全部 / 用过 / 从未调用 / 元信息不全 / 项目级
- 左侧列出 Skill 的所有来源目录，以及 `skills/` 根下的裸 `.md` 文件——
  那些不是 Skill，永远不会被加载，属于该清理的东西

**抽屉**：点任意卡片右侧滑出。文本文件看内容，图片直接显示，Skill 看 SKILL.md 全文。
三个动作：打开（交给系统默认程序）、在访达中显示、复制绝对路径。

同名 Skill 会被折叠。全局装一份、插件市场又带一份的情况很常见，
按 项目 > 全局 > 插件 留优先级最高的那条，否则「用过几个」会被重复计数，
出现「8 个用过但只有 10 次调用」这种自相矛盾的数字。

## 调用次数的口径

只认会话日志里 `tool_use(name="Skill")` 的 `input.skill`，不认 Skill 出现在系统提示词的可用清单里。

这两个口径能差两个数量级——每轮对话都会带上全部可用 Skill 的列表，按关键词 grep
会把每一个 Skill 都算成「用过」。看到别的工具报出「Skill 使用率 100%」，基本就是踩了这个坑。

统计范围是 `~/.claude/projects` 和 `~/.codex/sessions` 下的全部 jsonl（上限 1200 个文件）。
换过客户端或清过日志就统计不到，这时页面会显示「调用次数未统计」而不是显示 0。

## 局限

主动说清楚，别让用户以为它能证明它证明不了的事：

- 只描述目录当前状态，不评价文件质量，也不判断哪个 Skill 该留该删
- 默认最多索引 20000 个文件，超了会在顶栏标 `+`，不是全量
- 会跳过 `node_modules`、`.git`、`dist`、`.obsidian` 等构建与缓存目录
- 卡片墙一次最多渲染 300 张，剩下的靠搜索缩小范围，不是无限滚动
- 「从未调用」不等于「没用」——刚装的、手动看过 reference 的、被别的 Skill 内部引用的，
  都会显示成从未调用。这是一条线索，不是一条判决

## 文件

```
view-your-harness/
├── SKILL.md
└── scripts/
    ├── index.py    目录 + Skill 清点 → index.json（纯事实，不做判断）
    ├── serve.py    本地只读服务，零依赖，只绑 127.0.0.1
    └── ui.html     单页工作台，原生 JS，跟随系统深浅色
```