codescout

codescout

代码库搜索只完成了一半的工作：搜索返回数十个文件后，仍然需要有人决定先打开哪些文件。codescout 使用一条固定且可检查的规则来做出这个决定。你把已有的搜索结果交给它——每条结果包含所在文件、文件中的匹配数、文件上次修改距今的天数，以及（如果知道）文件所有者——它会按优先级返回这些结果，并为每条结果附上分数和所有者信息。它不会自行搜索，也不会触碰索引；这条排序规则就是整个工具。

所有结果都采用相同的方式评分：matches * 100 - last_modified_days。每次匹配计 100 分，因此相关性占主导；文件每多一天未更新，分数就会悄然下降——只有一次匹配的旧文件可能得分低于零，而且负分会原样报告，不会截断。结果按分数排序；分数相同时，按固定顺序打破平局：匹配更多的优先，其次是修改时间更新的文件，最后按路径的代码单元顺序排列。由于规则始终不变，相同的结果集合总会产生相同的排序列表，无论你以什么顺序提供这些结果。

只会返回列表顶部的结果：limit 限制返回结果的数量，默认值为 10。每个返回条目都包含 rank（在返回列表中的 1 起始位置），以及原样返回的 path、matches、last_modified_days 和 owner。所有权有一项明确的判定规则：所有者缺失、为空或仅包含空白字符时，表示文件无人拥有，此时 owner 报告为 null；其他所有者字符串都会按原样返回。计数会报告输入的结果数和返回的结果数。

格式错误的输入——包括缺少或为空的结果列表、某条结果不是对象、path 缺失、为空或不是字符串、matches 缺失、为小数或小于 1、last_modified_days 缺失、为小数或为负数、owner 不是字符串，或 limit 小于 1——都会导致验证错误，并指出出错路径；不会返回部分结果。同一路径出现两次会导致错误，并指出重复路径。未知的额外字段会被忽略。

CLI

npx @reneturcios/codescout rank --input args.json
npx @reneturcios/codescout --version

args.json 包含完整的参数对象：

{
  "hits": [
    {
      "path": "src/search/rank.ts",
      "matches": 14,
      "last_modified_days": 2,
      "owner": "alice"
    },
    {
      "path": "src/legacy/old-index.ts",
      "matches": 1,
      "last_modified_days": 240
    },
    {
      "path": "src/search/tokenize.ts",
      "matches": 9,
      "last_modified_days": 30,
      "owner": "bob"
    }
  ],
  "limit": 2
}

排序后的列表会以 JSON 格式打印：

{
  "results": [
    {
      "path": "src/search/rank.ts",
      "matches": 14,
      "last_modified_days": 2,
      "owner": "alice",
      "score": 1398,
      "rank": 1
    },
    {
      "path": "src/search/tokenize.ts",
      "matches": 9,
      "last_modified_days": 30,
      "owner": "bob",
      "score": 870,
      "rank": 2
    }
  ],
  "counts": {
    "hits": 3,
    "returned": 2
  }
}

第三条结果的得分为 1 * 100 - 240 = -140，因此它会被 limit 设定的 2 条上限完全排除。

退出代码：成功时为 0，运行时错误时为 1（包括输入文件无法读取或无效，以及输入无效），用法错误时为 2。

MCP 服务

npx -y @reneturcios/codescout mcp

MCP 客户端配置：

{
  "mcpServers": {
    "codescout": {
      "command": "npx",
      "args": ["-y", "@reneturcios/codescout", "mcp"]
    }
  }
}

工具

• rank_search_results — 按固定的相关性和时效性分数对调用方提供的代码库搜索结果排序，并附上文件所有者信息。

  • hits（数组，必填，至少 1 项）— 要排序的搜索结果，顺序为调用方提供的顺序；每项包括：
    • path（字符串，必填，非空）— 结果所在的文件
    • matches（整数，必填，至少为 1）— 文件中的匹配数
    • last_modified_days（整数，必填，至少为 0）— 文件上次修改距今的天数
    • owner（字符串，可选）— 文件所有者；缺失、为空或仅包含空白字符表示无人拥有
  • limit（整数，可选，至少为 1，默认值为 10）— 要返回的最大结果数

  返回 {results, counts}，其中 results 按排序顺序包含每条已返回结果对应的一个 {path, matches, last_modified_days, owner, score, rank}（无人拥有时，owner 为 null；score 为 matches * 100 - last_modified_days；rank 是该结果在返回列表中的 1 起始位置），counts 的结构为 {hits, returned}。

Docker

docker run -i ghcr.io/cloudcorprecords/codescout
docker run --rm -v "$PWD:/w" ghcr.io/cloudcorprecords/codescout rank --input /w/args.json

开发

npm install
npm run build   # tsc -> dist/
npm test        # tsx --test test/*.test.ts (pure local, no network)
npm run dev     # run the CLI from source

许可证

MIT — 版权所有 (c) 2026 Rene Turcios