mcpField
E
external-research

external-research

github.com/alexandru开发5111 次安装今天更新
代码仓库

关于 external-research

external-research 是供 Agent 调研软件和公共 API 使用的技能，按成本递增列出检索方式，并说明如何选择可靠且精简的方案。

主要功能

  1. 01分级研究方法
  2. 02JVM API 查询指引
  3. 03持久化仓库与 Maven 缓存
  4. 04GitHub 和 Azure 查询安全规则

适用场景

  1. 01浏览前检查本地源码
  2. 02查询 JVM 依赖的公共 API
  3. 03调研 GitHub 或 Azure 仓库
  4. 04复用缓存的克隆仓库和 Maven 工件

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/alexandru/skills --skill external-research

安装后在 Claude Code 中输入/external-research确认已加载。

详细介绍

外部调研

选择在准确性、Token 成本、请求成本和耗时方面最精简可靠的方案。只有在证据缺失或不可靠时才重新评估；没有具体理由时，不要重复等效检索，也不要检查相关仓库或依赖，除非确有必要。

方案

选项按成本从低到高排列：

  1. 使用 glob、grep、read 和 Shell 过滤器进行本地检查。
  2. 使用 LSP/MCP/IDE 语义工具（IntelliJ IDEA、Metals LSP）。
  3. 如有 cellar 技能，可用于查询 JVM 依赖的公共 API。
  4. 使用 gh 和 az 的只读子命令查询 GitHub 和 Azure。
  5. 已知 URL 时使用 webfetch。
  6. 不知道 URL 时使用 websearch（可用什么工具或技能就用什么）。
  7. 使用 git ls-remote 查询引用，然后用缓存的 Git 克隆获取源码和历史记录。
  8. 使用 Maven、Gradle、sbt、npm 元数据和归档工具查询已发布的软件包。

规则：

  • 如有可选技能（例如 cellar），请使用；否则使用现有工具继续操作。
  • 查询 JVM 依赖的公共 API 时，如果 cellar 技能可用且能直接回答，优先使用该技能。
  • 不要使用会修改内容的 gh 或 az 子命令；请说明此限制。
  • 如果已知网页能直接回答问题，请使用 webfetch 并引用其 URL；无需创建任务目录。如果内容为空、过时或不完整，只切换到可能补充所缺证据的来源。
  • 对于语义问题、编译或代码检查，如果可用的 LSP/MCP/IDE 语义工具（IntelliJ IDEA、Metals LSP）能直接回答或提供相关诊断，请使用该工具，并引用符号或源码位置；只有在其证据不可用或不充分时，才克隆或获取其他内容。

持久化调研缓存

  • 使用 $HOME/.agents/librarian/ 作为跨运行、会话和执行环境的持久化缓存。需要时创建此目录；不要使用会话目录或 mktemp 进行调研缓存。
  • 使用绝对路径。将克隆的仓库保存在 $HOME/.agents/librarian/repos/<repo-key>/ 下，将 Maven 仓库保存在 $HOME/.agents/librarian/maven/<library-key>/ 下。
  • 进行任何网络操作前，先检查相关缓存路径。复用现有且匹配的克隆、工作树、POM、JAR、源代码 JAR、元数据文件或图表输出。仅在所需引用或构件缺失时，或调用方明确要求获取最新远程数据时，才下载或拉取。
  • 复用前验证缓存身份。对于仓库，将 git -C <base-clone> remote get-url origin 的结果与请求的 URL 进行比较。如果 URL 不同，请使用另一个稳定的 <repo-key>，不要覆盖或重新克隆现有目录。
  • 缓存维护可以更新 Git 元数据、添加工作树和下载构件，但不得修改源文件、提交、推送、更改远程源或更改用户的工作区。

克隆与 worktree 工作流

为每个仓库使用一个稳定且适用于文件系统的键，并将其作为单个路径组件。优先使用仓库名称，例如 cats-effect；如果名称可能冲突，则使用限定键，例如 github-typelevel-cats-effect。永久基础克隆始终命名为 main，特定 ref 的 worktree 与它并列。

对于 https://github.com/typelevel/cats-effect/ 的标签 v3.7.0，请严格按以下步骤操作：

  1. 创建持久仓库目录：

    mkdir -p "$HOME/.agents/librarian/repos"
mkdir -p "$HOME/.agents/librarian/repos/cats-effect"

  2. 检查 $HOME/.agents/librarian/repos/cats-effect/main 是否已存在。如果存在，检查其远程仓库和 worktree 列表；不要再次运行 git clone。如果不存在，则克隆完整历史记录的仓库一次：

    git clone https://github.com/typelevel/cats-effect/ "$HOME/.agents/librarian/repos/cats-effect/main"

  3. 检查基础克隆中是否已存在 v3.7.0，并检查 $HOME/.agents/librarian/repos/cats-effect/v3.7.0 是否已由 git worktree list --porcelain 注册。如果该 worktree 已存在，则直接复用，不要 fetch 或再添加一个。

  4. 如果缺少该标签，只 fetch 该标签。不要在每次重复请求时都 fetch 仓库：

    git -C "$HOME/.agents/librarian/repos/cats-effect/main" fetch origin "refs/tags/v3.7.0:refs/tags/v3.7.0"

  5. 如果该标签可用但其 worktree 不存在，则创建并检查并列的 worktree：

    git -C "$HOME/.agents/librarian/repos/cats-effect/main" worktree add "$HOME/.agents/librarian/repos/cats-effect/v3.7.0" v3.7.0
# Inspect with glob, grep, read, or git -C "$HOME/.agents/librarian/repos/cats-effect/v3.7.0" ...

    这等同于在 main worktree 中运行 git worktree add ../v3.7.0 v3.7.0，但使用绝对路径可以避免依赖 Bash 的当前目录。

  6. 对于分支，使用相同流程。仅当远程跟踪 ref 不存在时才 fetch 该分支，然后添加并列的 worktree。如果必须从远程跟踪分支创建本地分支，请使用 git worktree add -b <branch> <absolute-worktree-path> origin/<branch>。

  7. 如果请求的路径已存在但并非已注册的 worktree，或者其远程仓库不匹配，则不要覆盖它。报告确切路径，并且只有在确认它代表不同仓库后，才使用其他稳定键。

不要使用 git checkout，也不要切换基础克隆的分支来检查 ref。不要运行 git worktree remove、git worktree prune、git reset、git clean 或任何会更改源文件的命令。不要推送或更改远程仓库。

如果克隆、fetch 或添加 worktree 失败，请报告确切错误。不要改用其他目标路径重试，也不要重新克隆同一仓库。

Maven 构件工作流

  • 对于 JVM 依赖的公共 API，如果 cellar 可用且是最精简可靠的方法，优先使用它。如果检查 JAR、源代码 JAR、POM、元数据或依赖图更合适，则使用此 Maven 缓存工作流。
  • 选择一个稳定的库键，例如 cats-effect，并将 $HOME/.agents/librarian/maven/cats-effect/ 用作 Maven 的持久本地仓库。在解析前，先检查该目录中精确坐标对应的文件。不要使用默认的 ~/.m2/repository 作为下载目标。
  • 对于单个直接构件，使用 Maven 的 -Dtransitive=false；不要创建合成项目。对于传递依赖图或有效解析，在库缓存下创建请求目录，在其中写入 POM，并使用 -f <absolute-pom-path> 调用 Maven。
  • 将请求 POM 和依赖图输出保存在 $HOME/.agents/librarian/maven/<library-key>/requests/<request-key>/ 下。如果存在坐标和仓库定义相同的请求，则复用，不要再次解析。

例如，要检查 Cats-Effect 3.7.0 的源代码 JAR：

mkdir -p "$HOME/.agents/librarian/maven/cats-effect"
mvn -B dependency:get -Dartifact=org.typelevel:cats-effect_3:3.7.0:jar:sources -Dtransitive=false "-Dmaven.repo.local=$HOME/.agents/librarian/maven/cats-effect"
jar tf "$HOME/.agents/librarian/maven/cats-effect/org/typelevel/cats-effect_3/3.7.0/cats-effect_3-3.7.0-sources.jar"

如果精确的 JAR 已存在，则跳过 mvn，直接检查它。二进制 JAR、POM 和 javadoc 分类器也使用相同缓存。如果 mvn -v 失败，请报告 Maven 不可用，不要尝试此工作流。

对于依赖图，请使用持久请求目录，而不是临时任务目录：

mkdir -p "$HOME/.agents/librarian/maven/cats-effect/requests/3.7.0-graph"
cat > "$HOME/.agents/librarian/maven/cats-effect/requests/3.7.0-graph/pom.xml" <<'EOF'
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <groupId>agents.research</groupId>
  <artifactId>cats-effect-evidence</artifactId>
  <version>1.0.0</version>
  <dependencies>
    <dependency>
      <groupId>org.typelevel</groupId>
      <artifactId>cats-effect_3</artifactId>
      <version>3.7.0</version>
    </dependency>
  </dependencies>
</project>
EOF
mvn -B -q -f "$HOME/.agents/librarian/maven/cats-effect/requests/3.7.0-graph/pom.xml" dependency:tree -Dverbose -DoutputType=text "-DoutputFile=$HOME/.agents/librarian/maven/cats-effect/requests/3.7.0-graph/tree.txt" "-Dmaven.repo.local=$HOME/.agents/librarian/maven/cats-effect"

回复前检查持久化输出和已解析的文件。

报告

引用 URL、构件坐标、Git ref，以及相对于仓库的路径和行范围。将已验证事实与推断分开，并说明不确定之处。

评论

支持 Markdown