前言¶
在 DSH 里做新功能或新插件之前，常见做法是自己在浏览器里搜 GitHub、逐个打开 README，再凭印象决定要不要读源码。想法往往只有一句话，检索词却要想好几组；搜出来的结果既要看得懂相关性，又得兼顾 star 和活跃度。下面介绍社区插件 dsh-find-ideas（维护者 tianyao2003），它把「搜相似项目 → 加权排序 → 选几个仓库读结构」做成一组内置工具，由 agent 按对话自动串联。
这是什么¶
dsh-find-ideas 是 DeepSeek Harness 的联网类插件：你描述一个开发想法，agent 解析关键词、在 GitHub 上检索相似项目，按相关性与 star 加权排序后给出一张固定格式的候选卡片；你再指定若干仓库，插件会读取 README、依赖清单、目录树和关键文件，整理成可借鉴的架构说明。README 里的定位是：「Before you build it, check whether it already exists.」
- 仓库：github.com/tianyao2003/dsh-find-ideas
- 社区目录：skillhub.cn 插件页
- 许可证：MIT；当前包版本 0.4.0（以
package.json为准） - 运行要求：Node ≥ 22；与 DSH
0.2.0-rc.2/0.2.1-rc.2等发布线兼容（peer：@deepseek-ai/dsh-tools自0.1.0-rc.6起）
四个工具彼此独立、不共享状态：scout_projects → rank_candidates → inspect_projects → read_repo_files。0–10 的 relevance 由 agent 判断；工具只负责搜索、计算、排序和读取，不做语义相似度裁决。
核心功能¶
检索与排序¶
scout_projects：把想法拆成多条 GitHub 搜索查询，返回按 star 排序的候选池（此处 deliberately 不按相关性排序）。若想法里没有拉丁字母，会先翻译成英文检索词；若调用方未提供拉丁keywords且没有可用 LLM，则返回plan_failed。rank_candidates：对候选池打分并生成卡片。公式为：
relevance × (1 + log10(max(stars, 10) + 1)) / 2
卡片固定八列，顺序不变：rank、project、last updated、relevance、stars、score、language、description。
仓库精读¶
inspect_projects：一次最多读 5 个仓库的 README、依赖 manifest、目录树摘要和部分关键文件。返回卡片上限为固定 24 KB；超出时按「manifest → README → 单文件摘录 → 签名骨架」从代价最低的证据开始裁剪，并在卡片中说明省略了什么、如何补全（用read_repo_files定点读文件，或减少本次仓库数量）。没有可调的 budget 参数。read_repo_files：对单个仓库在某一 commit 上定点读取最多 4 个文件，返回行窗口（focus可对准匹配关键词的行）及带 commit 与行范围的 permalink；读取量不超过返回预算。
卡片与错误语义¶
relevance为 agent 的 0–10 分；score由公式计算，不能靠自然语言改排序。- 未测得的查询项显示为「未知（未测得）」；缺失的归档计数显示「数据缺失」——不会把未测量的数写成
0。 - 仓库原文作为数据引用，不会冒充卡片结构；链接仅
github.com或raw.githubusercontent.com。 - 工具不抛异常：失败返回
reason与detail；部分成功会说明原因。
缓存与出站流量¶
- 内存：最多 64 条结果，5 分钟。
- 磁盘：搜索结果 24 小时，源码读取 10 分钟，总量上限约 64 MB，约每小时清扫；目录为
$DSH_HOME/cache/dsh-find-ideas/，删除该目录始终安全。 - 搜索词与仓库路径发往
api.github.com；inspect_projects/read_repo_files只读 GitHub 上的仓库内容，不上传本地代码。除 DSH 已使用的模型外，仅在「想法无拉丁字母且调用方未提供拉丁keywords」时会把想法送去翻译；纯英文想法不会为翻译而出站。
安装与启用¶
插件以当前 dsh 进程权限运行，安装前请自行查看仓库源码与 MIT 许可证。安装命令以 README 为准：
# from npm (recommended)
dsh plugin --profile web add dsh-find-ideas
# or from GitHub
dsh plugin --profile web add github:tianyao2003/dsh-find-ideas
# or from a local directory
dsh plugin --profile web add /path/to/dsh-find-ideas
npm 包约 391 KB 下载、805 KB 解压、28 个文件、无运行时依赖。从 GitHub 安装会在安装时执行一次构建，需要 pnpm 允许 build scripts；npm 包已带编译产物，无此步骤。
安装后需重启 dsh。
配置 GitHub Token（推荐）¶
未认证搜索：同一公网出口 IP 每分钟 10 次（共享配额）。配置 token 后提升至每分钟 30 次（按账号计）。插件通过 DSH 凭据存储读取 GITHUB_TOKEN：
export GITHUB_TOKEN=ghp_... # bash
$env:GITHUB_TOKEN = 'ghp_...' # PowerShell, current session
无 token 也可使用，但 inspect_projects 在估算匿名请求超过 10 次时会拒绝整批操作。
典型用法¶
重启 dsh 后，用自然语言描述想法即可，agent 会自动调用上述工具。README 示例：
- “I want to build a local-first Markdown note app — what’s out there on GitHub?”
- “I want to build a UI-enhancing DSH plugin. Which projects exist?”
经过上面的步骤，你会先看到排序卡片，再对选中的仓库做架构梳理；需要某几个文件时，由 agent 走 read_repo_files 补读。
适用场景与注意¶
适合：开新项前做 prior-art 检索、对比同类开源实现、快速摸清几个候选仓库的依赖与目录结构，而不必手动拼多组 GitHub 搜索词。
注意：
- GitHub API 限流与 token 配额见上文；高频或大批量
inspect_projects要留意匿名上限。 - 0.4.0 起
inspect_projects固定 24 KB 上限，大仓库需分次少选仓库或定点读文件。 - 社区目录（如 SkillHub）与 DeepSeek / 幻方无官方从属关系；DSH 生态是「一切皆插件」，本插件归类为联网工具。
结尾¶
dsh-find-ideas 把「想法 → GitHub 候选 → 加权卡片 → 选仓读架构」收成一条可复用的 agent 工具链，适合在动手写代码前先确认「是不是已经有人做过、能借鉴什么结构」。进一步了解可访问 社区目录页 与 GitHub 仓库。
