Starlog

Starlog

在 AI 编码 Agent 使用软件包前先审查它——获取权威信息（CVE、许可证、维护情况），免费、本地运行、无需账户。

只需一条命令即可审查软件包——无需安装任何东西，无需 API 密钥，也无需账户：

npx starloghq facts ua-parser-js

然后将其接入你的编码 Agent（Claude Code、Cursor、Copilot、Codex）：

npx starloghq init

源代码可用，采用 BUSL-1.1 许可——可免费使用、修改和自托管；2030 年转为 Apache-2.0。详情 ↓

---

为什么

AI 编码 Agent（Claude Code、Cursor、Copilot）根据训练数据中的记忆选择库——这是一份经过抓取的代码快照，在某个截止日期冻结，并按选项出现的频率排序，而不是根据选项是否适合你的任务或当前是否安全来排序。这种记忆无法获知上周披露的 CVE，也从未见过你公司的内部库。无论情况如何，Agent 都会照样给出建议，并表现出同样的自信。

这些失效情况可以量化：研究发现，约 49% 的 AI 推荐依赖项存在已知漏洞，约 34% 则完全是幻觉——对应的软件包根本不存在。而在某些类别中——尤其是身份验证——Agent 默认选择手写自定义代码，而不是采用经过审查的库。

再努力调整提示词也无法修复这种记忆。Starlog 会在做出决策时，将权威且带日期的信息呈现给你的 Agent。它的核心功能是按名称审查——starlog facts <package> 会返回已知 CVE／事故、SPDX 许可证及风险、维护状态（或者坦诚说明*“没有相关记录”*）——让安装／规避／选择的决策依据事实，而不是记忆。它完全在你的计算机上作为 MCP 服务和软件包安装钩子运行，无需 API 密钥，也无需注册。配套的 starlog_search 可查找满足某项能力需求的候选软件包；再用事实审查选出的软件包。

**它真的会改变 Agent 的决策吗？**会——通过前后对比进行测量，测试场景也正是关键所在（私有库和截止日期之后发布的安全公告）。→ 经验证的结果。

你将获得

• starlog_facts MCP 工具 — 你的 Agent 会在推荐某个特定软件包前，查询关于它的权威事实：已知的 CVE／供应链事件、SPDX 许可证及许可证风险、维护状态（活跃／已弃用／已停止维护／已遭入侵）和影响范围。在一项包含 4 个模型的基准测试中，Agent 在软件包决策时会主动调用此工具（召回率为 100%，特异度为 98%），并因此更倾向于做出正确的安装／规避／选择判断。每条记录都有来源、经过验证并且标注日期——每条结果都会显示一行“截至 <date>”，因此不会把过时的“暂无已知漏洞”误认为是最新结果。没有记录的软件包会如实显示“暂无相关事实”。事实分为三个独立层，在查询时组合：L1 能力／影响范围（不可变）、L2 信誉／漏洞／许可证／维护状况（可变，包含 as of 时效信息）、L3 组织策略（你的适用性判定）。你可以在本地覆盖或扩展任意层：将 STARLOG_PRIVATE_FACTS 指向一个包含独立 l1／l2 数组的 JSON 文件（用于内部软件包、许可证裁定），并将 STARLOG_POLICY 指向组织策略（{ org, rules }），以给出允许／拒绝／标记判定。设置 STARLOG_API_KEY 后，组织私有覆盖层和策略会从托管事实 API 获取（本地语料库作为离线回退）；starlog facts push 可上传组织的覆盖层和策略。参见 docs/FACTS-CONTRACT.md。
• 软件包安装钩子 — 当你的 Agent 运行 npm install／pnpm add／yarn add／pip install 时立即触发，并在 Agent 基于该软件包开展工作之前展示该软件包的事实（已知事件、许可证、维护状况）。此钩子仅提供建议——它会告知下一步操作，但不会阻止安装。没有记录的软件包会加入队列，以便补充覆盖。
• starlog_search MCP 工具 — 用于发现：查找满足某项能力需求的候选软件包（优先显示组织认可的选项），然后使用 starlog_facts 审核指定的软件包。发现功能会展示现有选项；事实查询会对其进行审核。
• starlog_advise MCP 工具 — 当你的 Agent 发现自行实现或重复编写的能力代码时，建议迁移到安全的库（例如，使用 Clerk／Auth0／Supabase 代替自行实现身份验证）；仅当语料库中不存在安全替代方案时，才建议封装为软件包。该工具会在 .starlog/patterns.json 中跟踪模式。
• starlog facts／starlog search／starlog advise／starlog patterns CLI — 在终端中提供相同的事实查询、发现以及迁移或封装为软件包的建议。
• 在你的机器上运行 — 引擎和语料库都在本地；默认的无密钥路径无需账户、API 密钥或网络。设置 STARLOG_API_KEY 即可启用托管事实／搜索层（并提供本地回退）——在 starlog.dev 获取密钥，并通过 starlog init --api-key <key> 配置；除此之外，唯一会发送的数据是匿名、可选择退出的使用遥测——参见遥测。

此仓库包含引擎、精选的事实语料库，以及涵盖 7 个类别的 26 份能力清单所组成的发现语料库（包括用于迁移的身份验证操作指南）。

快速开始

npx starloghq init

这会将 Starlog 接入 Claude Code（并为 Cursor、Copilot、Codex 添加说明文件）：

• MCP 服务添加到 ~/.claude/settings.json — 提供 starlog_facts（按名称审核软件包）、starlog_search（发现候选项）和 starlog_advise（针对 DIY 模式建议迁移或打包），并将你的每个项目的私有覆盖层（${CLAUDE_PROJECT_DIR}/.starlog/*）接入 Agent，让每个项目都能自动使用内部软件包事实和发现功能
• 安装 PostToolUse hook — 在安装软件包时显示其事实
• 预览每项更改并在写入前征求确认；可幂等执行，可安全地重复运行

想使用简洁的 starlog 命令，而不是输入 npx？可以全局安装：

npm install -g starloghq
starlog init

如果 starlog 随后提示 command not found，说明你的 npm 全局 bin 目录不在 PATH 中（这是常见的 npm 配置缺漏，与 Starlog 无关）。可以运行 export PATH="$(npm prefix -g)/bin:$PATH"（将其添加到 shell 配置文件中以永久生效），也可以继续使用 npx starloghq init / npx starloghq facts <pkg>，这些命令无需配置 PATH 即可正常使用。如果安装时显示了 EACCES/权限错误，则表示安装未完成 — 修复 npm prefix 或使用 npx。

添加 --project 还会将 Starlog 指引写入项目的 CLAUDE.md；也可以只预览而不写入，或彻底移除：

starlog init --project
starlog init --dry-run
starlog init --uninstall

想让编码 Agent 为你完成设置？starlog init --agent-prompt 会打印一段可直接粘贴的提示词（预览 → 可选密钥 → 应用 → doctor → 重启 → 演示），引导 Claude Code、Cursor、Copilot 或 Codex 以非交互方式完成设置。它不会写入任何内容。

想在 Starlog 的带日期事实旁添加实时依赖扫描器？starlog init --with-socket 也会接入 Socket 的免费托管 MCP 服务（depscore），让你的 Agent 能发现任何在事实“截至”日期之后披露的问题。此功能需选择启用，因为之后你的 Agent 会将其检查的软件包名称发送到 socket.dev。你自行配置的现有 socket 条目绝不会被覆盖，而 --uninstall 只会移除 Starlog 写入的条目。

一次性接入整个组织

不必为每个内部仓库手动编写事实 — 只需将 Starlog 指向一个检出目录，它就会一次性推导出相关信息：

starlog org sync ~/code/my-org

对于找到的每个已发布软件包（npm package.json 和 Python pyproject.toml），它会推导出：

• L2 事实 → .starlog/private-facts.json — 许可证和许可证风险（来自清单，或从 LICENSE 文件检测），根据 git 最近一次提交的时间判断维护状态，并标注 source: analyzer 和带日期的 as of。你的 Agent 会按名称审核这些软件包。
• 发现语料库 → .starlog/private-corpus.json — 提取每个清单中的描述和关键词，让你的 Agent 可通过 starlog_search 按能力查找内部软件包，而不只是按名称审核。
• 建议策略 → .starlog/policy.suggested.json — 根据这些信号标记候选项（例如强 copyleft、未声明许可证）。这些都是Agent 不会读取的提案 — 请先审核，再通过 starlog facts policy <pkg> flag 采用你信任的提案。

源代码不会离开你的设备；只会写入推导出的事实。可随时重新运行以刷新（它会合并现有事实并重新生成建议）。未发布名称或没有描述的仓库只会被报告，不会凭空编造信息。已知漏洞扫描和远程 GitHub 组织枚举已列入路线图。

从源代码安装

git clone https://github.com/starloghq/index.git starlog-index
cd starlog-index && npm install
npx tsx src/cli.ts facts ua-parser-js

手动配置 MCP

starlog init 会自动为你写入此配置。若要手动配置，请添加到 ~/.claude/settings.json：

{
  "mcpServers": {
    "starlog": {
      "command": "npx",
      "args": ["-y", "starloghq", "mcp"]
    }
  }
}

这是 MCP 注册表使用的同一条启动命令。（如果改用本地源码克隆，请将 node 指向 dist/mcp.js——全局安装时为 $(npm root -g)/starloghq/dist/mcp.js，或使用你的克隆路径。）该服务提供两个工具：starlog_facts（权威的单包事实查询——CVE、许可证、维护情况）和 starlog_search（自然语言能力查询，可选用 category、stack 和 top_k 筛选）。

CLI 用法

按名称审查包——核心功能。本地运行，无需密钥，也无需联网：

starlog facts ua-parser-js

## ua-parser-js (npm)
**Effect surface:** Parses User-Agent strings; pure data transformation, in-process.
**Capabilities:** parsing
**Maintenance:** active
**License:** MIT (risk: none)
**Known vulnerabilities / incidents:**
  - INCIDENT:ua-parser-js-2021 [critical] affected: 0.7.29, 0.8.0, 1.0.0 — Maintainer account hijacked (Oct 2021); these versions shipped a password stealer and cryptominer. Treat installs as account-compromise.
**Transitive risk:** Frequently a transitive dep — pin away from the three bad versions.
**Source:** GitHub Security Advisory; CISA alert Oct 2021 (hand)
**Verified:** as of 2026-06-01

没有记录的包会如实返回 “No facts on file”——而不是猜测。添加 --format json 可获取机器可读输出，其中包含独立的 l1 / l2 / l3 层。

查找候选项以满足某项能力，然后用 facts 审查指定项：

starlog search "auth for a Next.js app"

#   Library             Category          Score   Solves
--------------------------------------------------------------------------------
1   Auth0 Next.js SDK   authentication    71.36   Implements user authentication in Next.js applications using Auth0 ...
2   Clerk               authentication    60.64   Provides a fully managed authentication and user management platfor...

搜索由关键词排序器在本地排序——分数是绝对值（强匹配的分数通常在 70～80），因此，查询不在索引类别中时会返回 “no strong match”，而不是自信地给出错误答案。无密钥时，候选项来自内置语料库（无需联网）。设置 STARLOG_API_KEY 后，候选项来自托管的完整语料库（api.starlog.dev/search），并由同一套本地引擎排序——因此，密钥只会扩大可查找的范围，绝不会影响评分方式；托管服务出现问题时，会静默回退到内置语料库。

--category <cat>    Filter by category (authentication, feature-flags, etc.)
--stack <stack>     Filter by stack affinity (e.g., "next.js", "python")
--top-k <n>         Number of results (default: 5)
--format <type>     Output format: table or json
--context <desc>    Project context to tailor the "vs custom" rationale

你的内部包——核心用例，只需两条命令

模型在结构上无法知道你的私有 @acme/* 包存在——因此，事实信息在这里最能改变决策（从 DIY 转向组织认可的库）。你无需手写 JSON；两条命令即可生成叠加数据，而 starlog init 已配置 Agent 按项目读取它们：

# Make it discoverable — search will surface it (private-first) for a capability:
starlog corpus add @acme/flags --solves "Feature flags + remote config for Acme Node services" \
    --category feature-flags --stack node --best-for "gradual rollout,kill switches"

# Make it vet clean — facts confirms it's active/maintained:
starlog facts add @acme/flags --status active --license MIT

这些命令会在你的项目中写入 .starlog/private-corpus.json（用于发现）和 .starlog/private-facts.json（用于审查）。由于 starlog init 会将 ${CLAUDE_PROJECT_DIR}/.starlog/* 写入 MCP 服务的环境变量，你的编码 Agent 会在该项目中自动读取它们——无需 shell export，也无需重新运行任何命令。运行 starlog doctor 确认配置（它会报告连接配置，以及每个项目生成了哪些内容）。如需更丰富的叠加数据——完整的 l1 / l2 数组、组织 STARLOG_POLICY 允许/拒绝判定，或使用 starlog facts push 推送到托管 API——请参阅 docs/FACTS-CONTRACT.md。

工作原理

Starlog 会将软件包评估为三个彼此独立、在查询时组合的层——绝不会将它们压缩成一个模糊的“分数”：

层	回答的问题	可变性
L1 能力／影响面	代码做什么？	不可变
L2 声誉叠加层	已知什么？——CVE、许可证、维护情况	可变；带有标注日期的 as of 时效信息
L3 组织策略	在这里允许使用吗？	你的规则 → 允许／拒绝／标记

starlog facts <pkg> 会为调用方组合这三层并返回结果——如果没有匹配项，也会如实说明——可通过 MCP 服务、CLI 或安装钩子使用。语料库位于本地且可缓存；可通过 STARLOG_PRIVATE_FACTS（内部软件包、许可证裁定）和 STARLOG_POLICY 覆盖或扩展任一层。完整约定见：docs/FACTS-CONTRACT.md。

发现功能（starlog_search）是独立的接口：它通过本地关键词排序器，根据每个库的 solves／best_for／stack_affinity 对能力清单排序，并报告绝对分数，因此对于语料库外的查询，会返回“没有强匹配项”，而不是强行给出结果。候选集为内置语料库；或者，设置 STARLOG_API_KEY 后，使用托管的完整语料库。两种情况下都由同一个本地引擎排序。当你的 Agent 安装尚无清单的软件包时，钩子会将其加入队列（.starlog/pending.json），以便补充覆盖范围。

如需全面了解接口、引擎、数据来源以及哪些遥测数据会离开本机，请参阅 docs/ARCHITECTURE.md（含示意图）。

它会改变 Agent 的决策吗？

事实工具的真正检验标准不是“它是否返回数据”，而是“Agent 是否因此做出不同决定”。以下为前后对比测试结果（对照组 = 仅回忆；实验组 = 相同提示词 + Starlog 事实）：

• **私有软件包（核心场景）：**向 Agent 提供一条仅供参考的事实，告知某个活跃的内部库存在——不要求“必须使用它”——Agent 就会停止自行手写代码，转而选择内部库。**2/2，从自行实现转为使用内部库，仅凭信息便做到了。**模型无法从结构上回忆你的私有 @acme/* 软件包；事实信息让它得以了解这些软件包的存在。
• **知识截止日期之后的供应链信息：对于 posthog-node，事实信息会补充“固定版本以避开恶意版本 4.18.1／5.11.3／5.13.3”——该安全公告 MAL-2025-190925 发布于模型训练截止日期之后。模型无法得知此事；事实信息可以。
• **没有无端改变决定：**健康的对照项（zod、fastify）不会改变；node-cache（有歧义，且没有真实情况作为依据）也会被有意排除在成功案例之外——把每次变化都算作胜利的工具是在欺骗你。

此结论由一项覆盖四家模型供应商、统计功效充分的基准测试支持：正确的采用／规避决策比例从 ~20% → ~78%，且100% 未经提示便采用。

完整的前后对比、客观的适用范围以及我们舍弃的实验 → docs/VALIDATION.md。

覆盖范围

**事实语料库——42 个软件包。**经过整理并注明日期：已知供应链事件（xz、event-stream、ua-parser-js、node-ipc、……）、重要的弃用信息以及健康基准——每项均包含 SPDX 许可证及风险、维护状态和 as of 日期。可通过 STARLOG_PRIVATE_FACTS（内部软件包）为你的组织扩展语料库，无需更改公开内容。

发现语料库——涵盖 7 个类别的 25 份能力清单：

类别	示例
身份验证	Clerk、Auth0
实时通信	Socket.IO、Ably、Pusher、Supabase Realtime、ws
ORM／数据库	Prisma、Drizzle、Kysely
后台作业	BullMQ、Inngest、Bree
邮件	Resend、SendGrid、Nodemailer
功能标志	LaunchDarkly、PostHog、Flagsmith、ConfigCat、DevCycle
缓存	ioredis、Upstash Redis、Keyv、Cacheable

注意：事实和清单数据均为特定时点的信息——有来源且注明日期，但它们只是决策辅助信息，并非绝对事实。对于任何关键依据，请务必核实；欢迎通过 PR 提交更正。

测试

npx vitest run

单元测试和端到端测试涵盖架构验证、语料库加载与完整性、事实/格式输出、启动 CLI 后的往返流程，以及搜索排序。所有测试均无需 API 密钥或外部二进制文件即可运行。

遥测

Starlog 会收集匿名、可选择退出的使用情况分析数据，以了解哪些命令、工具和软件包正在使用。收集的数据包括：运行的命令/工具（init/facts/search/doctor 和 starlog_facts/starlog_search MCP 工具）、CLI/Node/OS 版本、检测到的 Agent、粗略的结果计数、你查询的公开软件包名称，以及你的搜索查询/项目上下文——电子邮件、机密信息/令牌、绝对文件路径和 IP 地址会在发送前清除。

它绝不会发送你的组织私有软件包名称（使用私有覆盖层时，这些名称会被替换为布尔值）、你的用户名/主机名或任何文件内容。在 CI 和测试运行中，遥测也会自动禁用。

首次运行时会显示通知，且每当披露内容发生变化时都会再次显示（因此，扩大数据收集范围绝不会悄无声息地发生）。通过 MCP 工具使用时，服务会在首次工具调用结果中包含披露信息（由你的 Agent 转达给你），并从下一次调用开始记录——因此，在你看到收集内容之前，绝不会收集 MCP 分析数据。你可以随时选择退出：

starlog telemetry disable          # persistent opt-out
starlog telemetry status           # see current state + anonymous id
export STARLOG_TELEMETRY=0         # env opt-out
export DO_NOT_TRACK=1              # honored too
starlog <command> --no-telemetry   # one-off

链接

• 网站：starlog.dev

许可证

可查看源代码，采用 Business Source License 1.1——详见 LICENSE。这不是 OSI 认可的开源许可证：可免费使用、修改和自托管（限非竞争用途），并将于 2030-06-01 转为 Apache-2.0。