Starlog

在您的 AI 编程代理使用某包之前对其进行审查 —— 提供权威事实（CVE、许可证、维护情况），免费、本地化、无需账号。

**只需一条命令即可审查包 —— 无需安装，无需 API 密钥，无需账号：** ``` npx starloghq facts ua-parser-js ``` 然后将其接入到您的编程代理中（Claude Code、Cursor、Copilot、Codex）： ``` npx starloghq init ``` ## 为什么 AI 编程代理（Claude Code、Cursor、Copilot）根据**训练记忆**来选择库 —— 这些记忆是抓取代码的快照，冻结在某个截止日期，并根据选项出现的频率（而非是否适合您的任务或*现在*是否安全）进行排名。这种记忆无法知晓上周披露的 CVE，也从未见过贵公司的内部库。然而，代理依然会进行推荐，并且在两种情况下表现出同样的自信。 其失败模式是可衡量的：研究发现，约 49% 由 AI 推荐的依赖项包含已知漏洞，约 34% 属于纯粹的“幻觉”—— 即该包根本不存在。而且对于整个类别的任务 —— 最危险的是身份验证（auth）—— 代理默认手动编写自定义代码，而不是使用经过审查的库。 您无法通过拼命写提示词来修复记忆召回问题。**Starlog 在您的代理做决策时，为其提供权威的、带有日期的事实。** 它的核心功能是**按名称审查** —— `starlog facts ` 会返回已知的 CVE/事件、SPDX 许可证及其风险、以及维护状态（或者坦诚的*“暂无记录的事实”*）—— 从而让安装/避免/选择的调用基于事实，而非记忆。它完全在您的机器上作为 MCP 服务器和包安装 Hook 运行，无需 API 密钥，无需注册。配套的 `starlog_search` 用于查找特定功能的候选包；而 `facts` 用于审查选定的包。 **这真的会改变代理的决策吗？** 是的 —— 我们在关键场景（私有库和截止日期后的安全通告）中进行了前后对比测量。→ [验证结果](#does-it-change-the-agents-decision)。 ## 您将获得什么 - **`starlog_facts` MCP 工具** —— 您的代理在推荐**关于特定包的权威事实**之前，会先查找它们：已知的 CVE/供应链事件、SPDX 许可证及许可证风险、维护状态（活跃/弃用/废弃/被入侵）以及影响面。在 4 个模型的基准测试中，代理在决定使用包时主动调用了此工具（100% 召回率，98% 特异性），并促使它们做出了正确的安装/避免/选择决定。每一条记录都有来源、经过验证，并且**标有日期** —— 每个结果都会显示一行“截至 ``”，这样就不会把过时的“无已知漏洞”误认为是最新状态。没有记录的包将返回坦诚的“暂无事实记录”。事实由三个独立的层级组成，在查询时组合得出：**L1** 能力/影响面（不可变）、**L2** 声誉/漏洞/许可证/维护状态（可变 —— 带有“截至”的时效性）、**L3** 组织策略（您设定的适用性结论）。您可以在本地覆盖或扩展任何层级：将 `STARLOG_PRIVATE_FACTS` 指向包含独立 `l1`/`l2` 数组的 JSON 文件（用于内部包、许可证裁定），并将 `STARLOG_POLICY` 指向组织策略（`{ org, rules }`）以得出允许/拒绝/标记的结论。设置 `STARLOG_API_KEY` 后，组织私有覆盖层和策略将从托管的事实 API 获取（本地语料库作为离线备用）；`starlog facts push` 会上传您组织的覆盖层和策略。详见 [docs/FACTS-CONTRACT.md](docs/FACTS-CONTRACT.md)。 - **包安装 Hook** —— 在您的代理运行 `npm install` / `pnpm add` / `yarn add` / `pip install` 的瞬间触发，并在代理基于该包进行构建*之前* **展示该包的事实**（已知事件、许可证、维护情况）。这是建议性的 —— 它为下一步操作提供信息，但不会阻止安装。没有记录的包将排队等待覆盖。 - **`starlog_search` MCP 工具** —— 发现：查找特定功能的候选包（优先显示组织批准的选项），然后使用 `starlog_facts` 审查选定的包。发现机制用于探索现有内容；事实用于对其进行审查。 - **`starlog facts` / `starlog search` CLI** —— 在终端中提供相同的事实和发现功能。 - **在您的机器上运行** —— 引擎和语料库都是本地的；审查无需账号、API 密钥和网络。（唯一的例外是匿名、可选择退出的使用情况遥测 —— 见 [遥测](#telemetry)）。 此代码库发布了引擎，以及一个精心策划的 **42 个包的事实语料库** 和一个包含 **7 个类别下 25 个能力清单**的发现语料库。 ## 快速开始 ``` npx starloghq init ``` 这会将 Starlog 接入 Claude Code（并为 Cursor、Copilot、Codex 生成指令文件）： - 将 **MCP 服务器**添加到 `~/.claude/settings.json` —— 暴露 `starlog_facts`（按名称审查包）和 `starlog_search`（发现候选），并将您的**每个项目的私有覆盖层**（`${CLAUDE_PROJECT_DIR}/.starlog/*`）接入代理，从而自动在每个项目中实现内部包的事实查找和发现功能 - 安装 **PostToolUse Hook** —— 在安装时展示包的事实 - 预览所有更改并在写入前询问；**幂等**操作，可安全地重新运行 比起输入 `npx`，更喜欢直接使用纯粹的 `starlog` 命令？全局安装它： ``` npm install -g starloghq starlog init ``` 添加 `--project` 以将 Starlog 指南写入您项目的 `CLAUDE.md`；可以预览而不写入，或者彻底移除： ``` starlog init --project starlog init --dry-run starlog init --uninstall ``` ### 一次性让整个组织入职 无需为每个内部仓库手动编写事实 —— 只需将 Starlog 指向一个检出的目录，它就能一次性推导出它们： ``` starlog org sync ~/code/my-org ``` 对于它找到的每个已发布的包（npm 的 `package.json` **以及** Python 的 `pyproject.toml`），它会推导出： - **L2 事实** → `.starlog/private-facts.json` —— 许可证及许可证风险（从清单中提取，或通过检测 `LICENSE` 文件得出），基于 git 最后一次提交时间得出的维护状态，加盖 `source: analyzer` 以及带有日期的 `as of` 印记。您的代理通过名称**审查**这些内容。 - **发现语料库** → `.starlog/private-corpus.json` —— 捕获每个清单的描述和关键字，以便您的代理可以通过 `starlog_search` 按能力**查找**内部包，而不仅仅是按名称审查它们。 - **建议策略** → `.starlog/policy.suggested.json` —— 标记从这些信号中得出的候选包（例如：强 Copyleft、未声明许可证）。这些是**代理不会读取的建议** —— 审查它们，然后使用 `starlog facts policy 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 ``` 没有记录的包会返回坦诚的 **"暂无事实记录"** —— 而不是猜测。添加 `--format json` 以获取包含独立 `l1` / `l2` / `l3` 层级的机器可读输出。 **发现**特定功能的候选包，然后使用 `facts` 审查选定的包： ``` starlog search "auth for a Next.js app" ``` ``` # 库 分类 得分 解决 -------------------------------------------------------------------------------- 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... ``` 搜索使用的是**本地关键字排名器** —— 无需 API 密钥，无需网络。分数是绝对的（强匹配的得分会在 70 到 80 分之间），因此对于不在索引类别中的查询，会返回*“无强匹配”*，而不是一个充满自信的错误答案。 ``` --category Filter by category (authentication, feature-flags, etc.) --stack Filter by stack affinity (e.g., "next.js", "python") --top-k Number of results (default: 5) --format Output format: table or json --context Project context to tailor the "vs custom" rationale ``` ### 您的内部包 —— 核心场景，仅需两条命令 模型在结构上**无法**知道您私有的 `@acme/*` 包的存在 —— 因此事实在这里能改变最多的决策（从自己动手写 → 转向组织批准的库）。您不需要手写 JSON；只需两条命令即可生成覆盖层，而 `starlog init` 已经配置好代理去**按项目**读取它们： ``` # 使其可被发现 — 搜索将（优先保护隐私）将其展示以提供某种能力： 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" # 使其通过审查 — 事实确认其处于活跃/维护状态： starlog facts add @acme/flags --status active --license MIT ``` 这会在您的项目中写入 `.starlog/private-corpus.json`（用于发现）和 `.starlog/private-facts.json`（用于审查）。由于 `starlog init` 将 `${CLAUDE_PROJECT_DIR}/.starlog/*` 写入了 MCP 服务器的环境变量中，您的编程代理会**自动在该项目中**获取它们 —— 无需 shell `export`，也无需重新运行。可以通过 `starlog doctor` 进行确认（它会报告配置情况以及每个项目生成的内容）。如需更丰富的覆盖层 —— 完整的 `l1`/`l2` 数组、组织 `STARLOG_POLICY` 的允许/拒绝结论，或者使用 `starlog facts push` 推送到托管 API —— 请参见 [docs/FACTS-CONTRACT.md](docs/FACTS-CONTRACT.md)。 ## 工作原理 Starlog 将包审查为**三个独立的层级，在查询时组合得出** —— 绝不会合并成一个模糊的“评分”： | 层级 | 回答 | 可变性 | |---|---|---| | **L1** 能力 / 影响面 | 代码*做*什么？ | 不可变 | | **L2** 声誉覆盖层 | *已知*什么？ —— CVE、许可证、维护情况 | 可变；包含标有日期的 `as of` 时效性 | | **L3** 组织策略 | 在这里*允许*吗？ | 您的规则 → 允许 / 拒绝 / 标记 | `starlog facts ` 会为调用者组合这三个层级并返回结果 —— 或者坦诚地返回未命中 —— 可通过 **MCP 服务器**、**CLI** 或 **安装 Hook** 进行。语料库是本地且可缓存的；使用 `STARLOG_PRIVATE_FACTS`（用于内部包、许可证裁定）和 `STARLOG_POLICY` 可覆盖或扩展任何层级。完整合约：[docs/FACTS-CONTRACT.md](docs/FACTS-CONTRACT.md)。 发现（`starlog_search`）是一个独立的展示面：它使用离线关键字排名器，针对每个库的 `solves` / `best_for` / `stack_affinity` 对能力清单进行排名，并报告*绝对*分数，以便不在语料库中的查询返回“无强匹配”，而不是强制给出结果。当您的代理安装了一个尚无清单的包时，Hook 会将其排入队列（`.starlog/pending.json`）等待覆盖。 ## 它会改变代理的决策吗？ 事实工具的真正考验不在于“它是否返回数据”，而在于“代理是否会做出不同的决策”。经过前后对比测量（对照组 = 仅靠记忆；实验组 = 相同的提示词 + Starlog 事实）： - **私有包（核心场景）：** 假设有一个仅提供信息的状况事实，指出存在一个活跃的内部库 —— 并没有明确指出“你必须使用它” —— 代理就会停止自己动手编写，转而选择该内部库。**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](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 | ## 测试 ``` npx vitest run ``` 单元测试和端到端（e2e）测试涵盖了 schema 验证、语料库加载与完整性、事实/格式输出、衍生 CLI 的往返流程以及搜索排名。所有测试均无需 API 密钥或外部二进制文件即可运行。 ## 遥测 Starlog 会收集**匿名、可选择退出**的使用情况分析数据，以了解哪些 命令、工具和包正在被使用。它会发送：运行的命令/工具 （`init`/`facts`/`search`/`doctor` 以及 `starlog_facts`/`starlog_search` MCP 工具）、CLI/Node/OS 版本、检测到的代理、粗略的结果统计、 您查找的**公开**包名，以及您的**搜索查询 / 项目 上下文** —— 电子邮件、密钥/令牌、绝对文件路径和 IP 地址 **在发送前均会被清除**。 它**绝不**会发送您的**组织私有**的包名（当您使用私有覆盖层时，它们会被脱敏为 布尔值）、您的用户名/主机名或任何文件 内容。在 CI 和测试运行中，它也会自动禁用。 首次运行时会打印通知，并且**每当披露信息发生更改时都会重新显示** （因此，扩大收集范围的行为绝不会在您不知情的情况下发生）。由于 MCP 服务器无法 向您展示通知，**MCP 工具分析数据将保持关闭状态，直到您通过运行 CLI 看过 最新通知为止**（例如在设置期间运行的 `starlog init`）。随时可选择退出： ``` 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 --no-telemetry # one-off ``` ## 链接 - 网站：[starlog.dev](https://starlog.dev) ## 许可证 在商业源码许可证 1.1（Business Source License 1.1）下**可见源代码** —— 详见 [LICENSE](LICENSE)。它不是 OSI 开源许可证：允许免费使用、修改和自托管（用于非竞争性用途），并且它**将于 2030-06-01 转换为 Apache-2.0 许可证**。

标签：AI编程助手, MCP服务, MITM代理, 依赖审查, 文档结构分析, 暗色界面, 自动化攻击