view-your-harness

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

跟另外两个是一套：star-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. 起服务

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），单独跑索引器就行：

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，跟随系统深浅色