# 目标与路径：为什么做这个仓库

本文记录**为什么做**。具体做到哪一步见 [progress.md](progress.md)，
怎么进各插件市场见 [marketplace-listing.md](marketplace-listing.md)。

## 目录

- [一、判断](#一判断)
- [二、要验证的假设](#二要验证的假设)
- [三、验证指标](#三验证指标)
- [四、载体：联想专业工具集](#四载体联想专业工具集)
- [五、工具规划](#五工具规划)
- [六、设计原则](#六设计原则)
- [七、风险与边界](#七风险与边界)

---

## 一、判断

**正面抢占通用 agent 平台，现阶段极为困难。** 模型、入口、用户心智都不在我们手里，
从零做一个平台去和现有玩家竞争，投入产出比不成立。

但平台之上还有一层：**公共技能／插件生态**。这一层的特点是：

- **准入门槛低。** 不需要平台方授权，打个 GitHub topic 就进了社区目录（已实测，见 progress.md）。
- **占位效应真实存在。** 目录站按分类组织，同一件事先来者占住位置；
  awesome-dsh-plugin 明确写了「两个插件做同一件事时，先来者保留位置」。
- **和我们的存量能力天然契合。** 联想的服务体系里已经有大量专业判断（硬件诊断、备件、
  保修、服务网点），这些是通用 agent 做不了、也不会去做的事。

所以路径是：**不抢平台，抢平台上的生态位。**

## 二、要验证的假设

这个仓库是**路径验证的第一个试点**，不是一个产品。要验证的是下面这条链能不能跑通：

```
把一个联想的专业能力做成 agent 插件
      → 能被公共插件生态收录
        → 有真实用户安装并使用
          → 能把用户导向联想的服务与商品
            → 形成可复制的模式，把更多专业能力推上去
```

拆成四个可以分别证伪的假设：

| # | 假设 | 当前状态 |
|---|---|---|
| H1 | 联想的专业能力能被做成符合生态规范的插件并被收录 | ✅ **已验证**，见 progress.md |
| H2 | 这类专业工具在通用 agent 生态里有真实需求 | ⏳ 待安装量与使用数据 |
| H3 | 诚实的诊断结论能有效导向服务与商品，而不损害信任 | ⏳ 待埋点 |
| H4 | 模式可复制——第二、第三个工具的边际成本显著低于第一个 | ⏳ 待第二个工具 |

H1 是最便宜的一环，先做掉它就能把后面三个的讨论建立在事实上，而不是猜测上。

## 三、验证指标

试点期不追求规模，追求**信号清晰**。

| 层级 | 指标 | 说明 |
|---|---|---|
| 生态 | 被几个目录站收录、是否出现在分类页 | H1 |
| 触达 | 安装量、npm 下载量、仓库 star/fork | H2 |
| 使用 | 工具调用次数、完成一次完整检测的比例 | H2 |
| 转化 | 推荐触发率、触发后的点击率 | H3，**依赖埋点，目前没有** |
| 复制 | 第二个工具从零到收录的耗时 | H4 |

**转化指标目前拿不到。** 纯 skill 形态没有运行时钩子，插件形态有了钩子但还没接埋点。
这是当前最大的数据缺口，见 progress.md 的未来计划。

## 四、载体：联想专业工具集

仓库定位是**一个容器**，不是单个工具。命名 `dsh-len-assistant` 而不是
`dsh-battery-health`，就是为了不被第一个工具锁死。

结构上每类专业能力是一个**工具组**：

```
src/tools/<组名>/
├── collector.js   纯逻辑：跑脚本、解析结果（无 peer 依赖，可独立测试）
└── register.js    注册该组的 DSH 工具

.dsh/skills/<skill 名>/
├── SKILL.md       流程编排与输出格式
├── scripts/       平台采集脚本
└── references/    判读规则、话术素材
```

加一个工具组 = 加这两个目录 + 在 `src/index.js` 的 `GROUPS` 里加一行。
这个形状是为了让 H4 的边际成本真的降下来，而不只是口头上说可复制。

## 五、工具规划

| 工具组 | 状态 | 说明 |
|---|---|---|
| **电池健康** | ✅ macOS 已验证，Windows 待验证 | 容量、循环、双口径健康度、衰减趋势图、官方报告 |
| 其他硬件诊断 | 计划中 | 存储健康、内存、散热、电源适配器等，复用同一套「采集脚本 + 判读规则」骨架 |
| 知识检索 | 计划中 | 把联想服务知识库、保修政策、备件价格接成可检索路径，让 agent 能回答具体机型的具体问题 |

选电池作为第一个，是因为它同时满足：数据能从系统原生接口拿到（不需要装驱动）、
判读有明确的行业标准（80% 更换线）、且**天然连接到服务与商品**（换电池、延保）——
一个工具就能把 H1 到 H3 都串起来。

## 六、设计原则

这些原则是从第一个工具里提炼的，后续工具组也要遵守。

**1. 诊断与推荐严格分离，且顺序不可颠倒。**
先出结论，再看结论是否触发推荐。诊断报告的全部价值来自「用户相信这些数字没被动过手脚」，
一旦用户察觉结论是被推荐目标反向凑出来的，他不但不下单，还会连带不信任整个联想服务。
**这条不是道德要求，是转化率要求。**

**2. 不确定就说不确定。**
虚假的确定性在服务场景里会直接变成投诉。数据不足时给区间和条件，不给假装精确的数字。

**3. 采集零依赖。**
脚本要能直接扔到客户机器上跑，多一个依赖就多一次失败。平台的坑在脚本层一次性吃掉。

**4. 平台差异不外泄。**
上层拿到的字段口径统一，平台差异（单位、缺失字段、口径含义）在采集层消化并显式标注。

## 七、风险与边界

**品牌署名。** 用 `lenovo` 命名的公共仓 + npm 包 + 市场条目，挂在个人账号下，
外部读者会默认它是联想官方发布。**必须在 README 顶部写明真实归属。**
如果这是官方项目，应当迁到 Lenovo 组织下；如果是员工个人试点，就要写清楚不代表官方。
目录站会核对描述真实性，含糊其辞是被打回甚至移除的理由。

**内部策略公开。** `references/lenovo-offers.md` 含试点触发条件、试点范围、埋点建议。
仓库 public 且已打 topic，这些内容会被十几个目录站索引。
**这是不可撤回的**——改回 private 挡不住已被爬取或缓存的内容。
正式推广前需要决定：把内部决策逻辑抽成本地配置，还是接受它公开。

**生态站不稳定。** 这些目录站都是个人或小团队维护，收录标准和存续性没有保证。
不要把关键路径押在任何单一站点上。

**收录不等于背书。** 各站都明确声明收录不等于安全审查。反过来，
我们也不应在对外材料里把「被 X 收录」表述成任何形式的认证。

**合规。** 当前 skill 与插件**不采集任何用户数据**。后续加埋点时，
必须按平台埋点规范走并明示，不要在 skill 或脚本里私自采集。