@yottameta/yotta-chain 0.1.0 → 0.1.2

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## v0.1.2 (2026-08-29)
+
+- 安装方式统一为四方式（对齐发布规范 §3.3.1）：方式一 `npx -y @yottameta/yotta-chain --agent <name>` / `--dir <dir>`（推荐，走 npm 源）；方式二 `git clone https://github.com/YottaMeta/yotta-chain.git`；方式三 GitHub Download ZIP；方式四 `bash install.sh --agent/--dir/--list`。移除 `npx skills` 与 `-g` 推荐；中英双 README 安装节同步。
+- 版本对齐：package.json / SKILL.md / CHANGELOG / 引擎 VERSION / 测试断言 / README 锚点 = 0.1.2。
+- 无功能变更（仅文档与版本同步）。
+
+## 0.1.1 (2026-08-27)
+
+- 修复：README 安装方式统一为三方式（方式一 npx `-g` / `--dir` 指定目录，方式二 install.sh（`--agent` 仅示例用），方式三手动复制+目录表），删除 npx 固定 `--agent codex` 的写法；README 中英双版同步。
+- 对齐：package.json / SKILL.md / CHANGELOG / README / references/rules.md 的版本锚点统一到 v0.1.1；引擎 `version` 输出与测试断言同步。
+- 引擎无功能变更，测试保持 52/52。
+
 ## 0.1.0 (2026-08-27)
 
 - 初始版本：零依赖供应链依赖校验引擎（Python 3.8+ 标准库，纯本地离线）。

package/README.md

@@ -81,16 +81,39 @@ python3 scripts/yotta_chain.py version
 
 ## Installation
 
-Install the skill into your agent:
+Pick any of the four methods below; the order is the recommended priority. Skill files always come from **npm** (GitHub can be slow without a proxy; npm supports mirrors).
 
-| 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 |
+### Method 1: npm one-liner (recommended)
+
+```text
+# Optional China mirror: npm config set registry https://registry.npmmirror.com
+npx -y @yottameta/yotta-chain --agent <agent-name>      # install to the agent's default user-level skills dir
+npx -y @yottameta/yotta-chain --dir <your-skills-dir>   # point to the skills dir itself (e.g. ~/.codex/skills)
+```
+
+- `--agent <name>` installs to that agent's default user-level directory; `--list` shows each agent's default directory.
+- `--dir <path>` installs to the given directory; for agents not in the preset list, point `--dir` at their skills directory.
+- If the mirror has not synced the new package (404): add `--registry=https://registry.npmjs.org/` (a proxy may be needed in China), or wait for the mirror cache.
+
+### Method 2: git clone (developers / git available)
+
+```text
+git clone https://github.com/YottaMeta/yotta-chain.git <your-skills-dir>/yotta-chain
+```
+
+### Method 3: GitHub Download ZIP (manual / no git)
+
+On the GitHub repository `YottaMeta/yotta-chain`, click **Code → Download ZIP**, unzip it and put the `yotta-chain` folder into the 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.
+### Method 4: install.sh (multi-agent one-liner script)
+
+```text
+bash install.sh --agent <name>   # install to the agent's default user-level directory
+bash install.sh --dir <path>     # install to the given directory
+bash install.sh --list           # list agents -> default directories
+```
 
+> Method 1 uses the npm registry (npmmirror / npmjs) and does not depend on GitHub; Methods 2/3 use GitHub and may fail without a proxy in China.
 ## Usage with an AI agent
 
 Tell the agent the context, e.g.:
@@ -121,12 +144,12 @@ The agent runs the engine, reports findings by severity, and explains each rule
 | `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)
+## Supported ecosystems (v0.1.2)
 
 - **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).
+- `yarn.lock` / `pnpm-lock.yaml` / `go.mod` / `Cargo.lock` are not yet supported in v0.1.2 (see CHANGELOG).
 
 ## Boundaries
 

package/README.zh-CN.md

@@ -81,16 +81,39 @@ python3 scripts/yotta_chain.py version
 
 ## 安装
 
-把技能装进你的智能体：
+以下四种方式任选，顺序即推荐优先级；技能文件一律从 **npm** 获取（GitHub 无代理较慢，npm 支持镜像）。
 
-| 方式 | 命令 |
-|---|---|
-| npm（推荐） | `npx -y @yottameta/yotta-chain --agent codex`（或 `--dir <路径>` / `-g`） |
-| 脚本 | `bash install.sh --agent <名称>`（`bash install.sh --list` 查看支持的智能体） |
-| 手动 | 把技能目录复制到智能体的 skills 目录 |
+### 方式一：npm 一行装（推荐）
+
+```text
+# 可选国内加速：npm config set registry https://registry.npmmirror.com
+npx -y @yottameta/yotta-chain --agent <智能体名称>      # 装到指定智能体默认用户级技能目录
+npx -y @yottameta/yotta-chain --dir <智能体的技能目录>  # 指到技能目录本身（如 ~/.codex/skills）
+```
+
+- `--agent <name>` 自动装到该智能体默认用户级目录；`--list` 可查看各智能体默认目录。
+- `--dir <路径>` 装到指定的技能目录；未收录的智能体用 `--dir` 指到它的技能目录。
+- npmmirror 未同步新包（404）：加 `--registry=https://registry.npmjs.org/`（国内需代理），或稍等镜像缓存。
+
+### 方式二：git clone（开发者 / 有 git 环境）
+
+```text
+git clone https://github.com/YottaMeta/yotta-chain.git <智能体的技能目录>/yotta-chain
+```
+
+### 方式三：GitHub 下载压缩包（手动 / 无 git 环境）
+
+在 GitHub 仓库 `YottaMeta/yotta-chain` 点 **Code → Download ZIP**，解压后把 `yotta-chain` 文件夹放进智能体技能目录。
 
-装到项目：在项目内运行 `npx -y @yottameta/yotta-chain` 或 `bash install.sh`，会装到检测到的项目级目录。
+### 方式四：install.sh（多智能体一键脚本）
+
+```text
+bash install.sh --agent <name>   # 装到指定智能体默认用户级目录
+bash install.sh --dir <path>     # 装到指定目录
+bash install.sh --list           # 列出智能体 -> 默认目录
+```
 
+> 方式一走 npm 源（npmmirror / npmjs），不依赖 GitHub；方式二 / 三走 GitHub，国内无代理可能失败。
 ## 让智能体使用
 
 给智能体下指令即可，例如：
@@ -121,12 +144,12 @@ python3 scripts/yotta_chain.py version
 | `typosquat` | low | 名字与知名包编辑距离 ≤ 2，疑似拼写仿冒 |
 | `snapshot` | low | Maven 依赖使用 SNAPSHOT 版本 |
 
-## 支持的生态（v0.1.0）
+## 支持的生态（v0.1.2）
 
 - **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）。
+- `yarn.lock` / `pnpm-lock.yaml` / `go.mod` / `Cargo.lock` v0.1.2 暂不支持（见 CHANGELOG）。
 
 ## 边界
 

package/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: yotta-chain
-version: 0.1.0
+version: 0.1.2
 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
 ---
@@ -77,13 +77,13 @@ python3 scripts/yotta_chain.py version
 
 完整规则、判定逻辑与修复指引见 `references/rules.md`。
 
-## 支持的生态（v0.1.0）
+## 支持的生态（v0.1.2）
 
 - **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 后续计划。
+- yarn.lock / pnpm-lock.yaml / go.mod / Cargo.lock：v0.1.2 暂不支持，见 CHANGELOG 后续计划。
 
 ## 与家族协同
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yottameta/yotta-chain",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Yuanlian — a zero-dependency supply-chain dependency validator for AI agents: detects dependency confusion (private package names resolved from public registries, mixed registries, suspicious registry URLs), lockfile consistency issues (missing entries, unsatisfied ranges, dangling references, missing integrity), missing lockfiles, unpinned versions, SNAPSHOT deps and typosquatting across npm (package.json + package-lock v1/v2/v3), Python (requirements.txt, pyproject.toml, poetry.lock, Pipfile/Pipfile.lock) and Maven (pom.xml); generates SBOM-lite (CycloneDX 1.5 subset). Pure Python 3.8+ standard library, fully local and offline, no online CVE lookups. Triggers when the user needs to check a project dependencies for supply-chain risks before build/release, verify a lockfile matches its manifest, detect dependency-confusion exposure, or generate an SBOM. Boundaries: local and offline; no CVE databases, no package-registry queries, no data leaves the machine; findings are review signals to be verified by humans; authorized / own-asset / educational use only.",
   "license": "MIT",
   "keywords": [

package/references/rules.md

@@ -115,7 +115,7 @@
 - **npm semver**：`^` `~` `>=` `<=` `>` `<` `=`、x 范围（`1.x` / `1.2.x`）、`*`、`||` 或、连字符范围（`1.2.3 - 2.3.4`）、预发布规则（预发布版本默认不满足不含预发布的比较器）。
 - **PEP 440**：`==` `!=` `>=` `<=` `>` `<` `~=` `===`、逗号 AND、`||` 或、`==1.2.*` 通配；`~=1.2` = `>=1.2,==1.2.*`。
 
-## 六、已知限制（v0.1.0）
+## 六、已知限制（v0.1.2）
 
 - 不做在线 CVE 比对（那是 snyk / trivy / npm audit 的地盘）。
 - 依赖混淆为本地近似：真正确认「私有包名被公共仓库抢占」需要在线核对，引擎给强信号供人工复核。

package/scripts/test_yotta_chain.py

@@ -115,7 +115,7 @@ class TestToml(unittest.TestCase):
         doc = '''
 [project]
 name = "demo"
-version = "0.1.0"
+version = "0.1.2"
 dependencies = [
     "requests>=2.28",
     'flask<3.0',
@@ -547,7 +547,7 @@ class TestCli(unittest.TestCase):
             self.assertEqual(data["bomFormat"], "CycloneDX")
 
     def test_version(self):
-        self.assertEqual(yc.VERSION, "0.1.0")
+        self.assertEqual(yc.VERSION, "0.1.2")
 
 
 class TestNpmLockV1(unittest.TestCase):

package/scripts/yotta_chain.py

@@ -4,7 +4,7 @@
 
 Zero-dependency Python 3.8+ implementation (standard library only).
 
-Scope (v0.1.0):
+Scope (v0.1.2):
   - npm   : package.json + package-lock.json (v1/v2/v3) + npm-shrinkwrap.json + .npmrc
   - python: requirements*.txt + pyproject.toml (PEP 621 / poetry) + poetry.lock
             + Pipfile / Pipfile.lock
@@ -35,7 +35,7 @@ try:
 except Exception:
     pass
 
-VERSION = "0.1.0"
+VERSION = "0.1.2"
 
 SEVERITY_ORDER = ["info", "low", "medium", "high"]
 SEVERITY_RANK = {s: i for i, s in enumerate(SEVERITY_ORDER)}