@yottameta/yotta-chain 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+## 0.1.0 (2026-08-27)
+
+- 初始版本：零依赖供应链依赖校验引擎（Python 3.8+ 标准库，纯本地离线）。
+- 生态：npm（package.json + package-lock v1/v2/v3 + npm-shrinkwrap + .npmrc 作用域仓库）、
+  Python（requirements*.txt + pyproject.toml（PEP 621 / poetry）+ poetry.lock + Pipfile / Pipfile.lock）、
+  Maven（pom.xml 基础：未固定版本 / SNAPSHOT / 可疑仓库 URL）。
+- 检测：
+  - 依赖混淆：scope 私有仓库配置 vs 实际解析仓库、同一包多仓库混合、可疑仓库 URL（http / IP / localhost）、
+    pip extra-index 公共回退、poetry secondary 源、Pipfile 公私源混配；
+  - lockfile 一致性：清单条目缺失 / 版本范围不满足（npm semver + PEP 440）/ 根信息不一致 /
+    悬空引用 / 缺 integrity / 同版本多来源冲突；
+  - 卫生：缺失锁文件 / 未固定版本（* / latest）/ Maven SNAPSHOT；
+  - typo-squat：依赖名与知名 npm / PyPI 包编辑距离 ≤ 2 提示。
+- SBOM-lite：CycloneDX 1.5 子集 JSON（components + dependencies + purl，scope / direct / resolved / integrity）。
+- 输出：text / JSON / CSV；scan 退出码 0（干净）/ 1（有发现）/ 4（错误），--gate 可调 CI 闸门。
+- 测试：52/52 全绿。

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 YottaMeta
+
+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:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE

@@ -0,0 +1,11 @@
+# NOTICE — YottaMeta 品牌声明
+
+「YottaMeta」「元链」「yotta-chain」「元察」「yotta-logwatch」「元情」「yotta-intel」「元钥」「yotta-secret」「元史」「yotta-logs」「元忆」「yotta-memory」以及本家族各技能名称（yotta-* 前缀）是 YottaMeta 的品牌与标识。
+
+本软件以 MIT 许可证开源，任何人均可自由使用、修改与分发。若你在其基础上制作派生作品：
+
+1. 不得继续使用 YottaMeta 或本家族名称（yotta-*、元链、元察、元情、元钥、元史、元忆 等）作为派生作品的名称；
+2. 不得暗示派生作品由 YottaMeta 官方维护、认可或与之存在关联；
+3. 建议在派生作品中明确声明「与 YottaMeta 官方无关联」。
+
+上游来源致谢：本技能由 YottaMeta 全新实现（零依赖自研 + 中文教学），供应链依赖校验方向参考开源社区 supply-chain 类技能（如 dependency-confusion / lockfile 审计 / SBOM 的检测思路）与 kali-claw 防御素材库的域映射（MIT，OpenClaw Contributors），无上游代码。

package/README.md

@@ -0,0 +1,151 @@
+<p align="center"><b>Language</b>: English · <a href="./README.zh-CN.md">中文</a></p>
+
+<p align="center">
+  <img src="assets/banner.png" alt="yotta-chain banner" width="100%" />
+</p>
+
+<h1 align="center">yotta-chain · 元链 (Yuanlian)</h1>
+
+<p align="center">YottaMeta's zero-dependency <b>supply-chain dependency validator</b>: detects <b>dependency confusion, lockfile inconsistencies, missing lockfiles, unpinned versions and typosquatting</b> across npm / Python / Maven by parsing manifests and lockfiles locally, and generates <b>SBOM-lite (CycloneDX 1.5 subset)</b>.</p>
+<p align="center">Activates when the user needs to check a project's dependencies for supply-chain risks before build / release / CI, verify a lockfile matches its manifest, assess dependency-confusion exposure, or generate an SBOM — <b>fully local and offline: no online CVE lookups, no package-registry queries, no data leaves the machine</b>.</p>
+<p align="center">No external tools required (Python 3.8+ standard library); Windows + Linux + macOS; every finding ships a severity, a plain-language explanation and a fix hint.</p>
+
+<p align="center">
+  <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-blue" /></a>
+  <a href="https://agentskills.io/"><img alt="Standard: agentskills.io" src="https://img.shields.io/badge/standard-agentskills.io-orange" /></a>
+  <a href="https://www.npmjs.com/package/@yottameta/yotta-chain"><img alt="npm package" src="https://img.shields.io/npm/v/@yottameta/yotta-chain" /></a>
+  <a href="https://github.com/YottaMeta/yotta-chain"><img alt="GitHub stars" src="https://img.shields.io/github/stars/YottaMeta/yotta-chain" /></a>
+  <a href="https://github.com/YottaMeta/yotta-chain/commits/main"><img alt="last commit" src="https://img.shields.io/github/last-commit/YottaMeta/yotta-chain" /></a>
+  <a href="https://github.com/YottaMeta/yotta-chain"><img alt="PRs welcome" src="https://img.shields.io/badge/PRs-welcome-brightgreen" /></a>
+</p>
+
+## What it is
+
+Supply-chain attacks target the parts developers trust: dependency confusion (a private package name is squatted on a public registry), typosquatting, stale or hand-edited lockfiles, missing integrity hashes. Yuanlian packages "supply-chain triage" into a zero-dependency engine that reads your manifests and lockfiles **locally** — no Trivy / Snyk / npm audit needed.
+
+It is agent-agnostic and works in any agent supporting Agent Skills. **Fully local and offline** — no online CVE databases, no registry queries, no data leaves the machine.
+
+## Core value
+
+- **Zero-dependency engine** — npm semver + PEP 440 range checks, TOML / JSON / requirements parsers, all built with Python 3.8+ standard library.
+- **Dependency confusion** — scope registry configured in `.npmrc` but resolved from a public registry; the same package resolved from multiple registries; suspicious registry URLs (http / IP literal / localhost); pip extra-index and poetry secondary-source public fallback.
+- **Lockfile consistency** — manifest entry missing from lockfile, locked version out of the declared range, root name / version mismatch, dangling references, missing integrity, same version with conflicting sources.
+- **Hygiene** — missing lockfile, unpinned versions (`*` / `latest` / no constraint), Maven SNAPSHOT dependencies.
+- **Typosquatting** — dependency names within edit distance 2 of well-known npm / PyPI packages are flagged for manual review.
+- **SBOM-lite** — CycloneDX 1.5 subset JSON (components + dependencies + purl, with scope / direct / resolved / integrity as properties).
+- **Three output modes** — text / JSON / CSV, plus a `--gate` exit-code gate for CI.
+
+## Why use it
+
+| Advantage | Description |
+|---|---|
+| **Zero dependency** | Python 3.8+ standard library; no daemon / database / external scanner; Windows + Linux + macOS |
+| **Fully local offline** | Parses existing manifests / lockfiles only; no online CVE lookups, no registry queries, no data leaves the machine |
+| **Deterministic signals** | Registry config vs actual resolution, range math (npm semver / PEP 440), integrity presence — not a random URL list |
+| **CI-friendly** | `scan --gate high` exits 1 only when findings reach a chosen severity |
+| **Teaching layer** | Every rule ships a Chinese plain-language explanation and a fix hint |
+
+## Commands
+
+| Command | Purpose |
+|---|---|
+| `scan` | Validate a project directory (auto-detect npm / python / maven) |
+| `sbom` | Generate SBOM-lite (CycloneDX 1.5 subset JSON or text) |
+| `version` | Print version |
+
+`scan` exit codes: **0** = no findings at or above `--gate`; **1** = findings; **4** = usage / path / unsupported-manifest error. Default `--gate=info` (any finding exits 1); use `--gate high` for a stricter CI gate.
+
+## Quick start
+
+Windows: use `python`; Linux/macOS: use `python3`.
+
+```bash
+# scan the current project (auto-detects npm / python / maven)
+python3 scripts/yotta_chain.py scan --path ./
+
+# only medium and above, JSON output
+python3 scripts/yotta_chain.py scan --path ./src --level medium --format json
+
+# CI gate: exit 1 only when high-severity findings exist
+python3 scripts/yotta_chain.py scan --path . --gate high; echo $?
+
+# generate SBOM-lite (CycloneDX 1.5 subset JSON)
+python3 scripts/yotta_chain.py sbom --path . --output sbom.json
+
+# view the SBOM as text
+python3 scripts/yotta_chain.py sbom --path . --format text
+
+# version
+python3 scripts/yotta_chain.py version
+```
+
+## Installation
+
+Install the skill into your agent:
+
+| Method | Command |
+|---|---|
+| npm (recommended) | `npx -y @yottameta/yotta-chain --agent codex` (or `--dir <path>` / `-g`) |
+| Shell script | `bash install.sh --agent <name>` (see `bash install.sh --list`) |
+| Manual | Copy the skill folder into your agent's skills directory |
+
+Installing into a project: run `npx -y @yottameta/yotta-chain` or `bash install.sh` inside the project to install into the detected project-level directory.
+
+## Usage with an AI agent
+
+Tell the agent the context, e.g.:
+
+```text
+Before we release, run yotta-chain scan on the repo (gate high) and summarize the findings with fix suggestions.
+```
+
+The agent runs the engine, reports findings by severity, and explains each rule with the Chinese plain-language guidance in `references/rules.md`.
+
+## Detection rules
+
+| Rule | Severity | What it means |
+|---|---|---|
+| `confusion_scope_registry` | high | Scope has a private registry in `.npmrc`, but the lockfile resolves it from a public registry |
+| `confusion_mixed_registry` | high | The same package is resolved from multiple registry hosts |
+| `lockfile_missing_entry` | high | A manifest dependency is absent from the lockfile |
+| `lockfile_range_unsatisfied` | high | Locked version does not satisfy the declared range (npm semver / PEP 440) |
+| `lockfile_dangling_ref` | high | A lockfile package depends on a package not present in the lockfile |
+| `lockfile_duplicate_conflict` | high | Same name + version with conflicting resolved / integrity sources |
+| `missing_lockfile` | medium | Dependencies declared but no lockfile committed |
+| `lockfile_root_mismatch` | medium | Lockfile root name / version differs from the manifest |
+| `lockfile_integrity_missing` | medium | Lockfile entry has no integrity / hash |
+| `confusion_extra_index` | medium | pip / poetry / pipenv mix a public registry with a private one (public becomes a fallback) |
+| `confusion_suspicious_registry` | medium | Registry / index URL is http, an IP literal or a localhost address |
+| `confusion_registry_mismatch` | medium | A private default registry is configured but packages resolve from a public registry |
+| `unpinned` | low / medium | Dependency has no fixed version (`*` / `latest` / no constraint) |
+| `typosquat` | low | Name within edit distance 2 of a well-known package — review manually |
+| `snapshot` | low | Maven dependency uses a SNAPSHOT version |
+
+## Supported ecosystems (v0.1.0)
+
+- **npm** — `package.json` + `package-lock.json` (v1 / v2 / v3) / `npm-shrinkwrap.json` + `.npmrc` (per-scope registries);
+- **Python** — `requirements*.txt` (with `--index-url` / `--extra-index-url` / `-r` recursion), `pyproject.toml` (PEP 621 / poetry), `poetry.lock`, `Pipfile` / `Pipfile.lock`;
+- **Maven** — `pom.xml` (basic: unpinned / SNAPSHOT / suspicious repository URLs / property + dependencyManagement resolution).
+- `yarn.lock` / `pnpm-lock.yaml` / `go.mod` / `Cargo.lock` are not yet supported in v0.1.0 (see CHANGELOG).
+
+## Boundaries
+
+- Reads local files only; no networking, no CVE databases, no package-registry queries, no data leaves the machine.
+- No online CVE comparison — that is the domain of Trivy / Snyk / npm audit; this engine provides local deterministic parsing and heuristic signals.
+- Dependency-confusion detection is a **local approximation**: confirming "a private name is squatted publicly" needs an online check; the engine emits strong signals for manual review.
+- Read-only; it never edits lockfiles or upgrades dependencies.
+
+## Development & validation
+
+```bash
+python3 -m py_compile scripts/yotta_chain.py
+python3 scripts/test_yotta_chain.py   # 52/52
+```
+
+## Changelog
+
+Version history lives in [CHANGELOG.md](./CHANGELOG.md).
+
+## License
+
+[MIT](./LICENSE)

package/README.zh-CN.md

@@ -0,0 +1,151 @@
+<p align="center"><b>Language</b>: <a href="./README.md">English</a> · 中文</p>
+
+<p align="center">
+  <img src="assets/banner.png" alt="yotta-chain banner" width="100%" />
+</p>
+
+<h1 align="center">yotta-chain · 元链 (Yuanlian)</h1>
+
+<p align="center">YottaMeta 的零依赖供应链依赖校验引擎：本地解析 npm / Python / Maven 的依赖清单与锁文件，检测<b>依赖混淆、lockfile 不一致、缺失锁文件、未固定版本、typo-squat</b>，并生成 <b>SBOM-lite（CycloneDX 1.5 子集）</b>。</p>
+<p align="center">触发场景：构建 / 发布 / CI 前检查项目依赖是否存在供应链风险、核对锁文件与清单是否一致、排查依赖混淆暴露面、生成 SBOM。</p>
+<p align="center">纯 Python 3.8+ 标准库实现，零外部依赖，Windows + Linux + macOS 通用；纯本地离线——不做在线 CVE 比对、不查询公共包仓库、不发送任何数据。</p>
+
+<p align="center">
+  <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-blue" /></a>
+  <a href="https://agentskills.io/"><img alt="Standard: agentskills.io" src="https://img.shields.io/badge/standard-agentskills.io-orange" /></a>
+  <a href="https://www.npmjs.com/package/@yottameta/yotta-chain"><img alt="npm package" src="https://img.shields.io/npm/v/@yottameta/yotta-chain" /></a>
+  <a href="https://github.com/YottaMeta/yotta-chain"><img alt="GitHub stars" src="https://img.shields.io/github/stars/YottaMeta/yotta-chain" /></a>
+  <a href="https://github.com/YottaMeta/yotta-chain/commits/main"><img alt="last commit" src="https://img.shields.io/github/last-commit/YottaMeta/yotta-chain" /></a>
+  <a href="https://github.com/YottaMeta/yotta-chain"><img alt="PRs welcome" src="https://img.shields.io/badge/PRs-welcome-brightgreen" /></a>
+</p>
+
+## 这是什么
+
+供应链攻击瞄准的是开发者默认信任的部分：依赖混淆（私有包名被攻击者在公共仓库同名抢占）、typo-squat 仿冒包、过期或被手工改动的锁文件、缺失完整性哈希。元链把「供应链排查」打包成零依赖引擎，**本地**读取你的清单与锁文件——不需要 Trivy / Snyk / npm audit。
+
+它与任何平台无关，是智能体无关的工具包，支持 Agent Skills 的智能体都能调用。**纯本地离线**——不做在线 CVE 比对、不查询包仓库、不发送任何数据。
+
+## 核心价值
+
+- **零依赖引擎**——npm semver + PEP 440 版本范围判定、TOML / JSON / requirements 解析器，全部用 Python 3.8+ 标准库实现。
+- **依赖混淆**——.npmrc 里配置了私有仓库的 scope 却从公共仓库解析；同一包被多个仓库解析；可疑仓库地址（http / IP 字面量 / 本机）；pip extra-index 与 poetry secondary 源造成的公共回退。
+- **lockfile 一致性**——清单条目在锁文件缺失、锁定版本超出声明范围、根 name / version 不一致、悬空引用、缺 integrity、同版本多来源冲突。
+- **卫生**——缺失锁文件、未固定版本（`*` / `latest` / 无约束）、Maven SNAPSHOT 依赖。
+- **typo-squat**——依赖名与知名 npm / PyPI 包编辑距离 ≤ 2 时提示人工复核。
+- **SBOM-lite**——CycloneDX 1.5 子集 JSON（components + dependencies + purl，scope / direct / resolved / integrity 作为属性）。
+- **三种输出**——text / JSON / CSV，外加 `--gate` 退出码闸门供 CI 使用。
+
+## 为什么用它
+
+| 优势 | 说明 |
+|---|---|
+| **零依赖** | Python 3.8+ 标准库；无常驻服务 / 数据库 / 外部扫描器；Windows + Linux + macOS |
+| **纯本地离线** | 只解析已存在的清单 / 锁文件；不做在线 CVE 比对、不查询仓库、不发送任何数据 |
+| **确定性信号** | 仓库配置 vs 实际解析来源、版本范围数学（npm semver / PEP 440）、完整性存在性——不是随机 URL 清单 |
+| **CI 友好** | `scan --gate high` 只在达到指定严重度时退出 1 |
+| **教学层** | 每条规则都带中文直白解释与修复提示 |
+
+## 命令
+
+| 命令 | 用途 |
+|---|---|
+| `scan` | 校验项目目录（自动识别 npm / python / maven） |
+| `sbom` | 生成 SBOM-lite（CycloneDX 1.5 子集 JSON 或文本） |
+| `version` | 显示版本 |
+
+`scan` 退出码：**0** = 未发现达到 `--gate` 级别的风险；**1** = 有发现；**4** = 用法 / 路径 / 无受支持清单错误。默认 `--gate=info`（任何发现即退出 1）；CI 可用 `--gate high` 收紧。
+
+## 快速使用
+
+Windows 用 python，Linux/macOS 用 python3。
+
+```bash
+# 扫描当前项目（自动识别 npm / python / maven）
+python3 scripts/yotta_chain.py scan --path ./
+
+# 只看 medium 及以上，JSON 输出
+python3 scripts/yotta_chain.py scan --path ./src --level medium --format json
+
+# CI 闸门：达到 high 才退出码 1
+python3 scripts/yotta_chain.py scan --path . --gate high; echo $?
+
+# 生成 SBOM-lite（CycloneDX 1.5 子集 JSON）
+python3 scripts/yotta_chain.py sbom --path . --output sbom.json
+
+# 文本形式查看 SBOM
+python3 scripts/yotta_chain.py sbom --path . --format text
+
+# 版本
+python3 scripts/yotta_chain.py version
+```
+
+## 安装
+
+把技能装进你的智能体：
+
+| 方式 | 命令 |
+|---|---|
+| npm（推荐） | `npx -y @yottameta/yotta-chain --agent codex`（或 `--dir <路径>` / `-g`） |
+| 脚本 | `bash install.sh --agent <名称>`（`bash install.sh --list` 查看支持的智能体） |
+| 手动 | 把技能目录复制到智能体的 skills 目录 |
+
+装到项目：在项目内运行 `npx -y @yottameta/yotta-chain` 或 `bash install.sh`，会装到检测到的项目级目录。
+
+## 让智能体使用
+
+给智能体下指令即可，例如：
+
+```text
+发布前用 yotta-chain scan --gate high 扫一遍仓库，按严重度汇总发现并给出修复建议。
+```
+
+智能体会运行引擎、按严重度汇报发现，并用 `references/rules.md` 里的中文说明逐条解释。
+
+## 检测规则
+
+| 规则 | 严重度 | 说明 |
+|---|---|---|
+| `confusion_scope_registry` | high | .npmrc 为某 scope 配置私有仓库，锁文件却从公共仓库解析（依赖混淆） |
+| `confusion_mixed_registry` | high | 同一包被解析自多个不同仓库主机 |
+| `lockfile_missing_entry` | high | 清单声明的依赖在锁文件中缺失 |
+| `lockfile_range_unsatisfied` | high | 锁定版本不满足声明范围（npm semver / PEP 440） |
+| `lockfile_dangling_ref` | high | 锁文件某包依赖的包不在锁文件包列表 |
+| `lockfile_duplicate_conflict` | high | 同名同版本存在多个不同 resolved / integrity 来源 |
+| `missing_lockfile` | medium | 声明了依赖但没有锁文件 |
+| `lockfile_root_mismatch` | medium | 锁文件根 name / version 与清单不一致 |
+| `lockfile_integrity_missing` | medium | 锁文件条目缺少 integrity / 哈希 |
+| `confusion_extra_index` | medium | pip / poetry / pipenv 同时配置公共仓库与私有源（公共成为回退源） |
+| `confusion_suspicious_registry` | medium | 仓库 / 索引地址是 http、IP 字面量或本机地址 |
+| `confusion_registry_mismatch` | medium | 配置了私有默认仓库，包却从公共仓库解析 |
+| `unpinned` | low / medium | 依赖未固定版本（`*` / `latest` / 无约束） |
+| `typosquat` | low | 名字与知名包编辑距离 ≤ 2，疑似拼写仿冒 |
+| `snapshot` | low | Maven 依赖使用 SNAPSHOT 版本 |
+
+## 支持的生态（v0.1.0）
+
+- **npm** — `package.json` + `package-lock.json`（v1 / v2 / v3）/ `npm-shrinkwrap.json` + `.npmrc`（作用域仓库映射）；
+- **Python** — `requirements*.txt`（含 `--index-url` / `--extra-index-url` / `-r` 递归）、`pyproject.toml`（PEP 621 / poetry）、`poetry.lock`、`Pipfile` / `Pipfile.lock`；
+- **Maven** — `pom.xml`（基础：未固定版本 / SNAPSHOT / 可疑仓库 URL / 属性与 dependencyManagement 解析）。
+- `yarn.lock` / `pnpm-lock.yaml` / `go.mod` / `Cargo.lock` v0.1.0 暂不支持（见 CHANGELOG）。
+
+## 边界
+
+- 只读本地文件；不联网、不做在线 CVE 比对、不查询包仓库、不发送任何数据。
+- 不做在线 CVE 比对——那是 Trivy / Snyk / npm audit 的地盘；本引擎提供本地确定性解析与启发式信号。
+- 依赖混淆检测是**本地近似**：真正确认「私有包名被公共仓库抢占」需要在线核对，引擎给出强信号供人工复核。
+- 只读不写：绝不改锁文件、不升级依赖。
+
+## 开发与校验
+
+```bash
+python3 -m py_compile scripts/yotta_chain.py
+python3 scripts/test_yotta_chain.py   # 52/52
+```
+
+## Changelog
+
+版本历史见 [CHANGELOG.md](./CHANGELOG.md)。
+
+## License
+
+[MIT](./LICENSE)

package/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: yotta-chain
+version: 0.1.0
+description: 元链 —— 跨智能体的供应链依赖校验技能：零依赖自研引擎本地解析 npm（package.json / package-lock v1-v3 / .npmrc）与 Python（requirements / pyproject.toml / poetry.lock / Pipfile）及 Maven pom.xml，检测依赖混淆（私有包名被公共仓库同名抢占 / 混合仓库 / 可疑仓库 URL / extra-index 回退）、lockfile 与清单不一致、缺失锁文件、未固定版本、typo-squat 仿冒命名，并生成 SBOM-lite（CycloneDX 1.5 子集）。触发：用户要在构建 / 发布 / CI 前检查项目依赖是否存在供应链风险、核对锁文件与清单是否一致、排查依赖混淆风险或生成 SBOM 时。边界：纯本地离线解析，不做在线 CVE 比对、不查询公共包仓库、不发送任何数据；结果只是「需人工复核的风险信号」，是否真实需人工核实；仅用于已获授权 / 自有资产 / 教学环境。
+license: MIT
+---
+
+# 元链（yotta-chain）
+
+跨智能体的供应链依赖校验技能：零依赖自研引擎**本地解析** npm / Python / Maven 依赖清单与锁文件，
+检测**依赖混淆 / lockfile 一致性 / 缺失锁文件 / typo-squat** 四类供应链风险，
+并生成 **SBOM-lite（CycloneDX 1.5 子集）**。
+
+纯 Python 3.8+ 标准库实现，零外部依赖；Windows + Linux + macOS 通用。
+**纯本地离线**：不做在线 CVE 比对、不查询公共包仓库、不发送任何数据。
+
+## 何时使用
+
+- 构建 / 发布 / CI 前检查项目依赖是否存在供应链风险；
+- 核对 package-lock.json / poetry.lock / Pipfile.lock 与清单是否一致；
+- 排查依赖混淆暴露面（私有包名 / 混合仓库 / extra-index 公共回退）；
+- 生成 SBOM-lite 用于依赖清单审计与合规留痕。
+
+**Do NOT trigger**：
+
+- 不做在线 CVE 比对（snyk / trivy / npm audit / safety 的地盘）；
+- 不查询公共包仓库、不联网、不发送任何数据；
+- 不自动改锁文件 / 升级依赖——发现后由人工处理；
+- 不扫描他人系统；只解析**已存在**的本地依赖文件；
+- 结果只是「风险信号」，是否真实需人工复核；仅用于已获授权 / 自有资产 / 教学环境。
+
+## 快速使用
+
+Windows 用 python，Linux/macOS 用 python3。
+
+```bash
+# 扫描项目目录（自动识别 npm / python / maven）
+python3 scripts/yotta_chain.py scan --path ./
+
+# 只看 medium 及以上，JSON 输出
+python3 scripts/yotta_chain.py scan --path ./src --level medium --format json
+
+# CI 闸门：达到 high 才退出码 1（默认 gate=info，任何发现即 1）
+python3 scripts/yotta_chain.py scan --path . --gate high; echo $?
+
+# 生成 SBOM-lite（CycloneDX 1.5 子集 JSON）
+python3 scripts/yotta_chain.py sbom --path . --output sbom.json
+
+# 文本形式查看 SBOM
+python3 scripts/yotta_chain.py sbom --path . --format text
+
+# 版本
+python3 scripts/yotta_chain.py version
+```
+
+退出码：**scan 0** = 未发现达到 gate 级别的风险；**1** = 发现；**4** = 用法 / 路径 / 无受支持清单错误。
+
+## 检测规则一览
+
+| 规则 | 严重度 | 说明 |
+|---|---|---|
+| confusion_scope_registry | high | .npmrc 为某 scope 配置私有仓库，但锁文件里该 scope 包实际解析自公共仓库（依赖混淆） |
+| confusion_mixed_registry | high | 同一包在锁文件里被解析自多个不同仓库主机 |
+| lockfile_missing_entry | high | 清单声明了依赖，锁文件里却没有 |
+| lockfile_range_unsatisfied | high | 锁文件版本不满足清单声明的范围（npm semver / PEP 440） |
+| lockfile_dangling_ref | high | 锁文件里某包依赖的包不存在于锁文件包列表 |
+| lockfile_duplicate_conflict | high | 同一包同版本存在多个不同 resolved / integrity 来源 |
+| missing_lockfile | medium | 声明了依赖但没有锁文件 |
+| lockfile_root_mismatch | medium | 锁文件根 name / version 与清单不一致 |
+| lockfile_integrity_missing | medium | 锁文件条目缺少 integrity / 哈希 |
+| confusion_extra_index | medium | pip / poetry / pipenv 同时配置公共仓库与私有源（公共成为回退源） |
+| confusion_suspicious_registry | medium | 仓库 / 索引地址为 http、IP 字面量或本机地址 |
+| confusion_registry_mismatch | medium | 配置了私有默认仓库，但包实际解析自公共仓库 |
+| unpinned | low / medium | 依赖未固定版本（npm `*` / `latest`、requirements 无约束、Maven 无 version） |
+| typosquat | low | 依赖名与知名包编辑距离 ≤ 2，疑似拼写仿冒 |
+| snapshot | low | Maven 依赖使用 SNAPSHOT 版本 |
+
+完整规则、判定逻辑与修复指引见 `references/rules.md`。
+
+## 支持的生态（v0.1.0）
+
+- **npm**：package.json + package-lock.json（v1 / v2 / v3）/ npm-shrinkwrap.json + .npmrc（作用域仓库映射）；
+- **Python**：requirements*.txt（含 --index-url / --extra-index-url / -r 递归）、pyproject.toml（PEP 621 / poetry）、
+  poetry.lock、Pipfile / Pipfile.lock；
+- **Maven**：pom.xml（基础：未固定版本 / SNAPSHOT / 可疑仓库 URL / dependencyManagement 属性解析）。
+- yarn.lock / pnpm-lock.yaml / go.mod / Cargo.lock：v0.1.0 暂不支持，见 CHANGELOG 后续计划。
+
+## 与家族协同
+
+- **元盾 yotta-guardian**：供应链检查结果可作为 CI 闸门（--gate），在发布 / 合并前拦截高风险依赖；
+- **元钥 yotta-secret**：同一仓库先查硬编码密钥，再查依赖供应链风险；
+- **元察 yotta-logwatch**：运行时异常日志与供应链风险交叉印证。
+
+## 边界
+
+- 只读本地文件；不联网、不查询 CVE 库 / 包仓库、不发送任何数据；
+- 不做在线 CVE 比对（那是 snyk / trivy / npm audit 的地盘），只做本地确定性解析与启发式信号；
+- 依赖混淆检测是**本地近似**：真正确认「私有包名被公共仓库抢占」需要在线核对，本引擎给的是强信号 + 人工复核；
+- 不自动修复；发现后由人工处理。
+
+## 开发与校验
+
+```bash
+python3 -m py_compile scripts/yotta_chain.py
+python3 scripts/test_yotta_chain.py   # 52/52
+```
+
+## Changelog
+
+版本历史见 `CHANGELOG.md`（本技能不内嵌版本历史表）。

package/bin/install.js

@@ -0,0 +1,163 @@
+#!/usr/bin/env node
+/**
+ * yotta-chain 跨平台安装器（YottaSkills）
+ * 用法:
+ *   npx -y @yottameta/yotta-chain --agent <name>  # 按智能体默认用户级目录安装（推荐）
+ *   npx -y @yottameta/yotta-chain --dir PATH      # 装到指定目录（用户改了目录的智能体）
+ *   npx -y @yottameta/yotta-chain -g              # 安装到全部已知智能体用户级目录
+ *   npx -y @yottameta/yotta-chain                 # 安装到检测到的项目级目录
+ *   npx -y @yottameta/yotta-chain --list          # 列出智能体 -> 默认目录
+ */
+'use strict';
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const SKILL_NAME = 'yotta-chain';
+const PKG_ROOT = path.join(__dirname, '..');
+
+// 智能体 -> 用户级默认技能目录（dirs 按优先级排列；--agent 装到第一个）
+// 依据官方文档：.agents/skills 并非通用目录，被 OpenCode / Cursor / Cline / Amp /
+// Kimi / Gemini CLI / GitHub Copilot 等读取；Claude Code 与 Codex 默认不读 .agents。
+const AGENT_DIRS = {
+  claude:    { label: 'Claude Code',      dirs: ['.claude/skills'] },
+  cursor:    { label: 'Cursor',           dirs: ['.cursor/skills', '.agents/skills'] },
+  codex:     { label: 'Codex',            dirs: ['.codex/skills'] }, // 特判：$CODEX_HOME/skills
+  gemini:    { label: 'Gemini CLI',       dirs: ['.gemini/skills', '.agents/skills'] },
+  goose:     { label: 'Goose',            dirs: ['.config/goose/skills', '.agents/skills'] },
+  amp:       { label: 'Amp',              dirs: ['.config/agents/skills', '.agents/skills'] },
+  opencode:  { label: 'OpenCode',         dirs: ['.config/opencode/skills'] }, // 特判：$XDG_CONFIG_HOME
+  windsurf:  { label: 'Windsurf',         dirs: ['.codeium/windsurf/skills'] },
+  workbuddy: { label: 'WorkBuddy',        dirs: ['.workbuddy/skills'] },
+  kiro:      { label: 'Kiro',             dirs: ['.kiro/skills'] },
+  trae:      { label: 'Trae Code CLI',    dirs: ['.traecli/skills'] },
+  'trae-cn': { label: 'Trae IDE（国内）',  dirs: ['.trae-cn/skills'] },
+  qwen:      { label: 'Qwen Code',        dirs: ['.qwen/skills'] },
+  comate:    { label: 'Comate 文心快码',   dirs: ['.comate/skills'] },
+  codebuddy: { label: 'CodeBuddy Code',   dirs: ['.codebuddy/skills'] },
+  kimi:      { label: 'Kimi Code CLI',    dirs: ['.kimi/skills'] },
+  agents:    { label: '通用 AGENTS.md',    dirs: ['.agents/skills'] },
+};
+
+// Codex 用户级目录特判：优先 $CODEX_HOME/skills，否则 ~/.codex/skills
+function codexUserDir() {
+  const base = process.env.CODEX_HOME || path.join(os.homedir(), '.codex');
+  return path.join(base, 'skills');
+}
+
+// OpenCode 用户级目录特判：优先 $XDG_CONFIG_HOME/opencode/skills，否则 ~/.config/opencode/skills
+function opencodeUserDir() {
+  const base = process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config');
+  return path.join(base, 'opencode', 'skills');
+}
+
+function resolveUserDir(rel) {
+  if (rel === '.codex/skills') return codexUserDir();
+  if (rel === '.config/opencode/skills') return opencodeUserDir();
+  return path.join(os.homedir(), rel);
+}
+
+function installTo(dest) {
+  const target = path.join(dest, SKILL_NAME);
+  fs.mkdirSync(target, { recursive: true });
+  copyDir(PKG_ROOT, target, new Set(['package.json', 'bin', 'node_modules', '.git']));
+  console.log('installed -> ' + target);
+}
+
+function copyDir(src, dst, skip) {
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    if (skip.has(entry.name)) continue;
+    const s = path.join(src, entry.name);
+    const d = path.join(dst, entry.name);
+    if (entry.isDirectory()) {
+      fs.mkdirSync(d, { recursive: true });
+      copyDir(s, d, skip);
+    } else if (entry.isFile()) {
+      fs.copyFileSync(s, d);
+    }
+  }
+}
+
+function displayDir(rel) {
+  if (process.platform === 'win32') return '%USERPROFILE%\\' + rel.replace(/\//g, '\\');
+  return '~/' + rel;
+}
+
+function main() {
+  const args = process.argv.slice(2);
+  const isGlobal = args.includes('-g') || args.includes('--global');
+  const list = args.includes('--list') || args.includes('-l');
+  let explicitDir = null;
+  const di = args.indexOf('--dir');
+  if (di !== -1 && args[di + 1]) explicitDir = args[di + 1];
+  let agent = null;
+  const ai = args.indexOf('--agent');
+  if (ai !== -1 && args[ai + 1]) agent = String(args[ai + 1]).toLowerCase();
+
+  if (list) {
+    console.log('智能体 -> 默认技能目录（--agent <name> 装到第一个，用户级）:');
+    for (const [key, v] of Object.entries(AGENT_DIRS)) {
+      const resolved = v.dirs.map(displayDir);
+      console.log('  ' + key.padEnd(10) + v.label.padEnd(18) + resolved.join('、'));
+    }
+    console.log('\n说明：Windows 用 %USERPROFILE%，Linux/macOS 用 ~；仅收录有官方默认目录的智能体。');
+    console.log('改了目录的请用 --dir <路径>，不要依赖默认位置；若设置了 CODEX_HOME / XDG_CONFIG_HOME，安装自动以该变量为准。');
+    return;
+  }
+
+  if (explicitDir) { installTo(explicitDir); return; }
+
+  if (agent) {
+    const info = AGENT_DIRS[agent];
+    if (!info) {
+      console.log('未收录智能体: ' + agent + '。请用 --dir <路径> 指定技能目录。');
+      console.log('可用: ' + Object.keys(AGENT_DIRS).join(', '));
+      return;
+    }
+    installTo(resolveUserDir(info.dirs[0]));
+    console.log('完成。');
+    return;
+  }
+
+  if (isGlobal) {
+    const seen = new Set();
+    for (const v of Object.values(AGENT_DIRS)) {
+      for (const d of v.dirs) {
+        if (seen.has(d)) continue;
+        seen.add(d);
+        installTo(resolveUserDir(d));
+      }
+    }
+    console.log('完成。');
+    return;
+  }
+
+  const PROJECT_DIRS = [
+    '.claude/skills',
+    '.cursor/skills',
+    '.codex/skills',
+    '.config/goose/skills',
+    '.config/agents/skills',
+    '.opencode/skills',
+    '.codeium/windsurf/skills',
+    '.workbuddy/skills',
+    '.kiro/skills',
+    '.traecli/skills',
+    '.gemini/skills',
+    '.trae-cn/skills',
+    '.qwen/skills',
+    '.comate/skills',
+    '.codebuddy/skills',
+    '.kimi/skills',
+    '.agents/skills',
+  ];
+  let installedAny = false;
+  for (const d of PROJECT_DIRS) {
+    if (fs.existsSync(d)) { installTo(d); installedAny = true; }
+  }
+  if (!installedAny) {
+    console.log('未检测到项目级智能体目录。可手动复制，或用 --agent <name> / -g 装到用户级。');
+  }
+}
+
+main();