# 项目文档：PerfScope for DeepSeek Harness（暂定名 `dsh-perfscope`）

> 状态：立项调研完成，方向已定，待进入 SPIKE 验证
> 日期：2026-08-20

---

## 0. TL;DR（给决策者 30 秒看完）

- **结论**：做。为 DeepSeek Harness（dsh）做一款「插件体检」插件，一键健康扫描 → 0–100 健康评分 → 安全一键修复（可撤销）→ 导出可分享报告。
- **为什么现在做**：dsh 8/13 开源、一周 172k star、生态 8782+ 插件但**无人做健康评分**；安全（DShScan）、代理审计（api-relay-audit）、加载诊断（dsh-market Diagnostics）都被占了，健康/运行时性能这个面是空的。
- **为什么你能做**：PerfScope 在 VS Code 已验证了「扫描→评分→修复→撤销」整套产品逻辑；dsh 插件同样是 TypeScript/Cordis；且 dsh 的「run is traceable」特性让**运行时数据比 VS Code 更丰富**。
- **战略修正**：不只做 CLI 工具——必须带**可视化体检面板 + 可分享分数卡**（生态高星规律：视觉类最吃流量），并把「健康」定义为 3 个维度：**硬健康（能不能用）+ 运行健康（快不快/稳不稳）+ 治理健康（乱不乱/旧不旧）**。
- **目标（现实版）**：上线 1 个月 ~2k stars、入驻 dsh-market 自动分发、成为该品类事实标准；不上头去追 89k（那是桌面端/设计工具的赛道）。

---

## 1. 背景：两个产品的定位

### 1.1 PerfScope（已有，VS Code，下载仅 26）

- 理念：VS Code 性能健康扫描：扩展清单 + 激活事件 + 工作区设置 + 内存提示 → 0–100 分 → 预览式一键修复（`files.watcherExclude` / `search.exclude` / `search.followSymlinks`）→ 可撤销 → Markdown 报告 → 纯离线。
- 26 次下载的教训：**VS Code 性能优化市场已饱和**（市场有成熟的 Profiling 工具 + 海量竞品 + 官方内置），小工具没有分发渠道，基本盘太死。
- 可复用的资产：产品逻辑、评分心智、安全/撤销设计、文档/报告模板、品牌名 PerfScope。

### 1.2 DeepSeek Harness（dsh，目标平台）

- 开源 agent harness，「**everything is a plugin**」，基于 Cordis，MIT。
- 形态：Web UI（`npx @deepseek-ai/dsh web`）+ 无头模式 + 桌面客户端（社区）。
- 现状：v0.1 开发者预览，`0.1.0-rc.x` 快速迭代，官方明示有 breaking changes。
- 生态：GitHub `dsh-plugin` 话题 9347 仓库、索引 8782 插件、双 awesome 清单、`dsharness.io` 目录、`dsh-market` 内置插件市场。

---

## 2. 深度调研结论

### 2.1 分发链路（决定「下载量」上限）

| 渠道 | 说明 | 对项目的意义 |
|---|---|---|
| `dsh-market`（1.4k★） | 内置在 `deepseek-harness-desktop`(16.3k★)/`dsh-desktop` 等桌面客户端；浏览/搜索/一键安装/更新/热禁用 | **主要分发口。上架=给 awesome-dsh-plugin 提 PR，约 1 天自动收录。** |
| `awesome-dsh-plugin` registry | dsh-market 与官网目录的数据源；中英双语 | 单一入口 PR 即全覆盖 |
| `dsharness.io` / `dshget.com` / 官方 docs | 目录站，自动抓 topic 与 registry | 免费曝光 |
| 官方 Web UI | 插件设置页（rc.7+ 有插件自身配置卡片） | 产品落地 UI 载体 |

> 结论：dsh 的分发是「一个 PR 全生态可达」，且免登录、一键安装——**启动效率远超 VS Code Marketplace**。下载量上限由「产品值得装 + 排名靠前」决定，而非渠道。

### 2.2 技术可行性（决定「做不做得出来」）

以下信号源均已被官方 `docs/architecture.md` 与 cookbook 确认：

| 健康信号 | 数据来源 | 可行性 |
|---|---|---|
| 插件/加载失败、依赖解析失败 | Cordis 生命周期 + 启动日志 | ✅ 高 |
| 多版本核心包、配置校验失败 | `--dump-config` + 官方 config-catalog 比对 | ✅ 高 |
| 每次调用耗时、工具错误/超时 | session 事件流（per-call timing）+ `telemetry/*` seam | ⚠️ 需 SPIKE 确认事件是否带插件归因（核心不确定点） |
| 每插件 token/上下文占用 | llm 流事件 + 会话日志统计 | ⚠️ 同上（归因粒度待验证） |
| 版本兼容性 | 各 bundle 的 `package.json` 的 `dsh` 字段 vs 当前 rc 版本 | ✅ 高（rc.x 走太快，这是真实痛点） |
| 维护度 / 冗余能力重叠 | npm publish 时间（可选联网）+ service 注册表去重 | ✅ 高 |

### 2.3 竞品与空白（决定「定位」）

| 已有玩家 | 覆盖 | 没覆盖的（=我们的差异化） |
|---|---|---|
| `DShScan`（今天刚进审核） | 安全静态扫描 | 不做运行时健康/评分/修复 |
| `dsh-market` Diagnostics | 仅加载顺序/依赖冲突 | 没有全局评分、没有运行时 perf、没有可分享报告 |
| `api-relay-audit`（796★） | LLM 代理安全审计 | 场景窄（代理） |
| `dsh-handbook`（571★） | 文档手册（含 perf-tuning 章节） | 是指南不是工具 |
| `dsh-web-ui`（5.1k★） | 面板/皮肤/实时 token 统计 | 只展示不做诊断/修复 |

**空白结论**：全局 0–100 健康评分 + 运行时性能归因 + 一键修复（可撤销）+ 报告/分数卡分享 = **全空**。

### 2.4 生态流行规律（决定「星数天花板」）

- 高星都是**视觉/体验**类：皮肤（dsh-deep-whale 1.5k、whale-girl 252、open-sea-skin 185）、桌面端（16.3k）、设计（89.6k）、面板（5.1k）。
- 工具/实用类天花板 1–3k：dsh-TUI 2.2k、dsh-market 1.4k、brooks-lint 1.4k、sandbase-harness 629。
- 生态**质量信任塌陷**（大量蹭 tag 的仓库、皮肤、玩具），用户需要「可信判断依据」——这是体检工具的情感切入点。

> 结论：**纯 CLI 工具星数到顶约 2k**；要突破必须叠加视觉化（面板 + 可分享分数卡），并借生态信任缺口做传播。

---

## 3. 方向决策（含「如果更好就转向」的判断）

### 3.1 判断

基于 2.4，我们认真评估过转向：皮肤/桌面端/设计是星数放大器，但（a）都是资源/美术/运营重投入，（b）赛道已拥挤且头部已锁定（89k/16k/5k）——现在进是跟跑。**健康评分是唯一「我们擅长 + 空白 + 有增长势能」的组合**。

### 3.2 结论：保留健康评分大方向，但做三次战略升级

1. **从「工具」升级为「体检中心 + 信任背书」**：产品名字给用户「放心」信号，报告/分数卡成为可分享的「我的 dsh 很健康」证据。
2. **从「静态配置扫描」升级为「配置 + 运行时」双引擎**：吃 dsh 独有的 traceability 红利（VS Code 拿不到的 per-call 时序/token）。
3. **从「单页报告」升级为「面板 + 分数卡」**：面板常驻 UI 蹭视觉流量，分数卡专攻社媒截图传播。

### 3.3 明确「不做」边界（避免被拖进红海）

- 不做安全静态扫描（DShScan 主场）；可以给「来源可信度」做一个轻量提示（是否在 curated registry）。
- 不做代理审计（api-relay-audit 主场）。
- 不做主题/皮肤/桌面端。

---

## 4. 产品定义（v1.0）

### 4.1 一句话

> **一键体检你的 DeepSeek Harness：插件能不能用、快不快、乱不乱——0–100 健康分，一键修，可撤销，还能分享分数卡。**

### 4.2 功能清单（对照 PerfScope 方法论迁移）

| PerfScope（VS Code） | dsh-perfscope（本插件） | 备注 |
|---|---|---|
| 一键全量扫描 | `Doctor: Full Check`（命令/面板按钮） | 扫描项见 4.3 |
| 0–100 PerfScope Score | 0–100 Health Score（分三维度） | 评分模型见 4.4 |
| 预览式一键修复 | 预览 → 写 `cordis.patch.yml` patch 行（禁用/校正配置） → HMR 约 1s 生效 | 完全复用安全模式 |
| 撤销每次修复 | Doctor Change Log：只记录本插件写入的行，一键回滚 | 同 PerfScope 的 change log |
| Markdown 报告导出 | Markdown 报告 + **单文件 HTML 分数卡（可截图/可直接分享）** | 新增分享入口 |
| 纯离线 | 默认离线；「维护度」等需联网项单独开关 | 延续离线哲学 |
| —（VS Code 无此能力） | 每个插件独立跑分 + 建议（降级禁用/更新/卸载） | 运行时归因（见 SPIKE） |

### 4.3 扫描项（v1.0 全集）

**A. 硬健康（能不能用）——评分权重高、优先级最高**
1. 挂载/加载失败（Cordis mount 错误）
2. 依赖缺失 / 注入解析失败（依赖未满足）
3. 核心包多版本冲突 / loader 重复
4. 配置项与插件 schema 不符（对照 config-catalog）
5. 版本兼容：插件声明的 `dsh` 版本 vs 当前 rc（rc.x 前进快，天天有人踩）

**B. 运行健康（快不快 / 稳不稳）——依赖 SPIKE 结果，可二段上线**
6. 近 N 次会话内，插件相关工具调用错误率 / 超时率（telemetry）
7. 每次调用耗时中位数对比基线（session timing）
8. 每插件 token / 上下文占用（llm 流事件）

**C. 治理健康（乱不乱 / 旧不旧）**
9. 能力冗余：多插件 provide 同一 service
10. 长期未更新（npm publish 距今，可选联网）
11. 来源可信度轻提示（是否在 curated awesome registry，不深挖安全）

### 4.4 评分模型（v1.0 草案，权重要在 SPIKE 后定稿）

- 基准 100 分，分三档扣分；只扣命中项。分级展示（严重 / 警告 / 建议），每项给 one-line 人话解释（参考 dsh-market Diagnostics 的「plain-language terms」打法）。

| 层级 | 信号 | 单次扣分 |
|---|---|---|
| 严重 | 挂载失败 / 依赖解析失败 / 多版本核心冲突 | -40 |
| 严重 | 版本不兼容（与当前 rc） | -30 |
| 严重 | 配置校验失败 | -20 |
| 警告 | 运行错误率 / 超时率超标 | -20 |
| 警告 | 工具平均耗时超基线 | -10 |
| 警告 | token 占用异常偏高 | -10 |
| 建议 | 能力冗余 | -10 |
| 建议 | 久未更新 / 不在 curated registry | -10 |

- 结果页：总分 + 三维雷达/条形 + 逐插件列表（独立分 + 建议动作）。
- 阈值与权重内置但可配置（`doctor.schema.json`）。

### 4.5 安全与撤销（PerfScope 铁律全套迁移）

- 只写**项目/用户级 patch 行**（`cordis.patch.yml`），绝不卸载、不删文件、不动源码。
- 所有写操作：预览 diff → 显式确认 → 写入 → 记录到 Doctor Change Log。
- Change Log 只增、可一键回滚 / 全部回滚。
- 对宿主关键基础设施插件、手工编辑过的 patch 行加保护（dsh-market 已证明这套机制可行，直接沿用思路）。
- 默认离线；联网项（10）单独开关并明示。

### 4.6 运行形态（对齐生态习惯）

1. **Web UI 设置页面板**（cookbook: adding-a-settings-card）：扫描入口 + 分数卡 + 插件列表 + 一键修复/撤销。
2. **命令/CLI**（headless：`dsh doctor`）：CI/无头扫描，导出报告。
3. 可选 v2：常驻侧边面板（轻量实时健康灯），蹭 dsh-web-ui 的「live token stats」范式。

---

## 5. 技术方案

### 5.1 技术栈

- TypeScript / Cordis 插件（与 dsh 同构），Node ^22.19 / 24，pnpm 11.7（Corepack）。
- 参考实现：官仓 `packages/` 内置包（docs 明言 built-ins 就是最佳典范），尤其是 `core/session`、`core/tools`、`core/agent`、`dsh-base` 的 telemetry。
- UI：跟随 dsh Web 客户端约定（`ConversationNodeDefinition` / settings card cookbook），不另起炉灶。

### 5.2 关键接口面（初版，契约随 rc 演化，必须锁定版本）

- `dsh --profile web --dump-config` → 解析插件树。
- 生命周期事件（Cordis mount/unmount）+ 启动日志 → 硬健康。
- `SessionEventMap` / `session/event`、`telemetry/*` → 运行时健康（SPIKE 确认归因粒度）。
- `cordis.patch.yml`（`- id: ...` + `disabled: true`）→ 一键修复 + 撤销，靠 HMR 热生效。
- npm registry（可选）→ 维护度。

### 5.3 仓库结构（规划）

```
dsh-perfscope/
├─ package.json            # dsh 字段声明 bundle；npm 包 id 待定（见 6.3）
├─ cordis.patch.yml        # 本插件自身的 patch 行
├─ src/
│  ├─ scanner/             # 采集器：config-tree / lifecycle / telemetry / registry
│  ├─ model/               # 评分与规则引擎（weights 可配置）
│  ├─ fixes/               # 修复动作抽象 + 写入 confirm + Change Log + 回滚
│  ├─ report/              # Markdown 报告 + HTML 分数卡生成（纯本地）
│  ├─ ui/                  # Web UI 设置页/面板
│  └─ cli/                 # headless 命令
├─ test/                   # 单测 + 集成（跑在真实 dsh 上）
├─ docs/  ├─ README.md(双语) └─ CHANGELOG.md
└─ .github/                # CI + issue 模板
```

### 5.4 里程碑（含 SPIKE 决策门）

| 阶段 | 时间 | 目标 / 产出 | 通过标准 |
|---|---|---|---|
| **S0 环境** | 第 1 周 | fork 官仓跑起来；`dsh web` 可用；锁版本 | `src` 构建 + 启动成功 |
| **S1 SPIKE（决策门）✅ 已完成** | 第 2 周 | 验证 3 件事：① telemetry/session 事件是否带插件归因 ② dump-config 能否还原全插件树 ③ patch 写入+HMR 热生效闭环 | ① 会话级统计免费、插件级需自建映射（降级为 v1.1）· ②③ 源码+测试确证 · 详见 [docs/SPIKE-S1.md](./docs/SPIKE-S1.md) |
| **S2 MVP v0.1** ✅ **已完成**（2026-08-23） | 第 3–4 周 | 无头 CLI：扫描(硬健康+治理) → 评分 → 一键修复(预览/撤销) → Markdown 报告；README 双语 + `dsh-plugin` topic | 真实 profile 全流程走通：scan/fix/undo 已对真实宿主验证 |
| **S3 上架** | 第 4–5 周 | 发 PR 进 awesome-dsh-plugin（含 dsh-market 自动收录）；提交 dsharness.io 等目录 | 审核通过、可 `dsh plugin add` 一键装 |
| **S4 v1.0** | 第 6–8 周 | Web 设置页面板 + HTML 分数卡分享 + 运行时健康维度（按 SPIKE 结论） | 面板可用、分数卡可分享 |
| **S5 增长** | 第 9 周起 | 内容投放 + 社区运营 + 指标迭代（见第 7 节） | 见 7.3 KPI |

---

## 6. 发布与命名

### 6.1 发布（一次 PR 全生态）

1. GitHub 仓库公开 + `dsh-plugin` 话题（官方约定的可发现性入口）。
2. 给 `awesome-dsh-plugin/awesome-dsh-plugin` 提一个 entry PR → dsh-market 与官网目录约 1 天内自动收录。
3. 顺带提交 `0xsline/awesome-deepseek-harness`、`dsharness.io`、`dshget.com` 收录。
4. 若发 npm（当前 rc 无强制要求；dsh-market 支持 npm 分发更快的路径，建议发）→ `dsh plugin add` 秒装。

### 6.2 命名（已定）

- **产品 / npm / GitHub 仓库名：`dsh-perfscope`**（npm id 已确认可用；品牌口号沿用 *PerfScope for DeepSeek Harness*，与 VS Code 版 PerfScope 一脉相承）。
- 决策依据：`dsh-doctor`、`dsh-health` 在 npm 已被占用；`dsh-perfscope` 可用且保留品牌延续性。

### 6.3 品牌话术（README 第一屏话术草稿）

> **dsh-perfscope · 一键体检你的 DeepSeek Harness**
> Scan → Score → Fix → Share，全程本地。插件能不能用、快不快、乱不乱——一眼 0–100。安全修复，随时撤销。把报告和分数卡发给队友，证明你的 Harness 很健康。

---

## 7. 增长策略（面向「高星 + 高下载」）

### 7.1 生态规律 → 打法映射

| 观察 | 打法 |
|---|---|
| 高星=视觉/面板 | 分数卡 + 设置页面板做成「截图即广告」；demo 图植入 README 顶部（参考 dsh-market/dsh-web-ui 的 README 头图） |
| 分发靠 dsh-market 内置 | 上架即进桌面客户端，一键安装免登录 → 下载量走量 |
| 中英文社区并重 | README/报告 HTML 双语文档（生态头部做双语的普遍更有影响） |
| 信任塌陷 | 定位「信任背书」：报告里内置「本报告由 … 生成」，鼓励晒分 |
| 官方/社区星标聚集区 | GitHub Discussions + Discord 发质量帖/roadmap；参与 dsh 官方列表被引用 |

### 7.2 内容与运营（低成本高杠杆）

- **发布日**：README 头图（分数卡 demo）+ 3 条「修复成果 before/after」gif → 发 X/中文社区/newsletter；同步上 awesome PR。
- **Weekly 分享**：「本周最离谱插件配置翻车现场」系列（用匿名化数据讲故事）→ 带来持续搜索流量。
- **徽章体系**：分数 ≥90 生成一枚可内嵌 markdown badge（生态里很多人会贴在 README，自带回流）。
- **合作**：与 `dsh-market` 互推（它的 diagnostics 与我们的体检互补，可谈「打开诊断的高级版」入口）。

### 7.3 KPI（现实基准：工具类天花板 ~2k，靠视觉/分发冲 5k）

| 指标 | 2 周（S3 结束） | 1 个月 | 3 个月 |
|---|---|---|---|
| GitHub stars | 300 | 1500–2000 | 4000–6000 |
| 下载/安装（dsh-market+桌面内置） | 首周可见 | 累计 ~5k | ~30k |
| 生态收录 | awesome×2 | 全部目录 + 官方被引用 | 被 featured/内置推荐 |
| 社区反馈 | 10+ issue/discussion | 50+ | 100+ |

> 天花板说明：健康工具类目单打是 2k 量级；3k+ 依赖叠加面板/分享卡/分发红利。若 1 个月未到 300★，触发复盘（见 8.3）。

---

## 8. 风险与对策

| 风险 | 等级 | 对策 |
|---|---|---|
| rc.x 快速迭代、breaking changes | 高 | 锁定开发版本；README 声明；跟 GitHub Discussions/Discord；Change Log 记录每条契约变化；发布流水线跑真实 dsh 集成测试 |
| telemetry 无插件级归因（SPIKE 未过） | 中 | 降级套餐：运行时健康降为会话级统计；评审时把「归因」列为首个 feature request 挂钩官方 roadmap |
| dsh-market Diagnostics 已有加载诊断 | 中 | 差异化正面刚：他们是「单点诊断」，我们是「全局评分 + 运行时 + 修复 + 分享」；考虑合作而非对立 |
| 平台小众 / 可能被官方实现 | 中 | 窗口期收益（可快速低成本验证）；官方核心专注 model/agent loop，体检类大概率留白；保持敏捷 |
| 生态垃圾多、标题党多 | 中 | 靠「可信报告」反向建立口碑；坚持不夸大、不放飞曝光 |
| 单押一个平台 | 低 | 若 v1 验证成功，评分引擎可抽象成可复用的 `@dsh-perfscope/engine`，未来适配其它 cordis/agent 宿主 |

---

## 9. 下一步行动（本周）

1. 初始化仓库骨架（package.json / dsh 字段 / cordis.patch.yml / CI）。
2. 跑通 S0：`git clone` 官仓 → `pnpm install && pnpm run build` → `dsh web` 本地可用。
3. 启动 S1 SPIKE（3 个验证点，输出一页结论 + 决策）。
4. 按 4.4 把评分模型参数化，先写规则引擎与单测（不依赖真实数据）。
5. 写 README 双语草稿 + 分数卡 HTML 原型（先让传播素材动起来）。

---

## 附录：参考资料

- 官仓：github.com/deepseek-ai/deepseek-harness（docs/development.md, docs/architecture.md, docs/event-producer-consumer.md, docs/config-catalog.md, docs/cookbook/）
- 生态目录：dsharness.io/en/plugins · rankings（数据日更）
- 分发：github.com/dsh-market/dsh-market（上架协议 = awesome-dsh-plugin registry）
- 清单：github.com/awesome-dsh-plugin/awesome-dsh-plugin（双语）· 0xsline/awesome-deepseek-harness
- 参考实现：dsh-market（诊断/热禁用/回滚）、dsh-web-ui（面板/实时 token 统计）、dsh-handbook（perf-tuning 章节）、DShScan / api-relay-audit（安全审计边界）