@yottameta/yotta-chain 0.1.1 → 0.1.2

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # 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/README.md

@@ -81,54 +81,39 @@ python3 scripts/yotta_chain.py version
 
 ## Installation
 
-Pick any of the three methods; skill files are always fetched from **npm** (GitHub can be slow without a proxy; npm supports mirrors).
+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 1: npm (recommended, one-liner)
-```bash
+### Method 1: npm one-liner (recommended)
+
+```text
 # Optional China mirror: npm config set registry https://registry.npmmirror.com
-npx -y @yottameta/yotta-chain -g
-npx -y @yottameta/yotta-chain --dir <your skills dir>   # any agent: install to a custom directory
+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 not in the preset list? Use `--dir` to point at its skills directory, or copy manually (Method 3). `--list` shows the default directory of each agent.
 
-### Method 2: install.sh
-After obtaining the skill folder (`npm pack` unpack or `git clone`), enter the folder:
-```bash
-bash install.sh -g    # user-level; bash install.sh --list shows all directories
-bash install.sh --agent codex   # a specific agent (see --list)
-bash install.sh       # project-level: auto-detect existing skills directories
-bash install.sh --dir /path/to/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
 ```
-> Covers 17 agent families, including Trae / Qwen / Comate / CodeBuddy / Kimi.
 
-### Method 3: manual copy
-Copy the whole `yotta-chain` folder into the target agent's skills directory. Common user-level locations (`%USERPROFILE%` on Windows, `~` on Linux/macOS):
+### Method 3: GitHub Download ZIP (manual / no git)
 
-| Agent | User-level directory | Project-level directory |
-|---|---|---|
-| Codex | `%USERPROFILE%\.codex\skills\yotta-chain\` | `.codex\skills\` |
-| Claude Code | `%USERPROFILE%\.claude\skills\yotta-chain\` | `.claude\skills\` |
-| Cursor | `%USERPROFILE%\.cursor\skills\yotta-chain\` | `.cursor\skills\` |
-| Windsurf | `%USERPROFILE%\.codeium\windsurf\skills\yotta-chain\` | `.windsurf\skills\` |
-| opencode | `%USERPROFILE%\.config\opencode\skills\yotta-chain\` | `.opencode\skills\` |
-| Gemini | `%USERPROFILE%\.gemini\skills\yotta-chain\` | `.gemini\skills\` |
-| Goose | `%USERPROFILE%\.config\goose\skills\yotta-chain\` | `.goose\skills\` |
-| Amp | `%USERPROFILE%\.config\agents\skills\yotta-chain\` | `.agents\skills\` |
-| Kiro | `%USERPROFILE%\.kiro\skills\yotta-chain\` | `.kiro\skills\` |
-| WorkBuddy | `%USERPROFILE%\.workbuddy\skills\yotta-chain\` | `.workbuddy\skills\` |
-| Trae Code CLI | `%USERPROFILE%\.traecli\skills\yotta-chain\` | `.traecli\skills\` |
-| Trae IDE (CN) | `%USERPROFILE%\.trae-cn\skills\yotta-chain\` | `.trae\skills\` |
-| Qwen Code | `%USERPROFILE%\.qwen\skills\yotta-chain\` | `.qwen\skills\` |
-| Comate | `%USERPROFILE%\.comate\skills\yotta-chain\` | `.comate\skills\` |
-| CodeBuddy | `%USERPROFILE%\.codebuddy\skills\yotta-chain\` | `.codebuddy\skills\` |
-| Kimi | `%USERPROFILE%\.kimi\skills\yotta-chain\` | `.kimi\skills\` |
-| Generic AGENTS.md | `%USERPROFILE%\.agents\skills\yotta-chain\` | `.agents\skills\` |
-
-> If Codex's `CODEX_HOME` is set, it overrides the default; the same applies to opencode's `XDG_CONFIG_HOME`. `.agents\skills` is not a universal directory — only OpenCode / Cursor / Cline / Amp / Kimi / Gemini CLI / GitHub Copilot etc. read it; **Claude Code and Codex do not read it by default**. When unsure, use `--dir` or let the agent install it.
-
-> Project-level: run `npx -y @yottameta/yotta-chain` or `bash install.sh` inside the project to install into the detected project-level directory.
+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.
+
+### 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.:
@@ -159,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.1)
+## 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.1 (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,54 +81,39 @@ python3 scripts/yotta_chain.py version
 
 ## 安装
 
-三种方式任选其一，技能文件统一从 **npm** 获取（GitHub 无代理时较慢，npm 可配国内镜像加速）。
+以下四种方式任选，顺序即推荐优先级；技能文件一律从 **npm** 获取（GitHub 无代理较慢，npm 支持镜像）。
 
-### 方式一：npm（推荐，一行安装）
-```bash
-# 国内加速（可选）：npm config set registry https://registry.npmmirror.com
-npx -y @yottameta/yotta-chain -g
-npx -y @yottameta/yotta-chain --dir <你的技能目录>   # 任意智能体：指定目录安装
+### 方式一：npm 一行装（推荐）
+
+```text
+# 可选国内加速：npm config set registry https://registry.npmmirror.com
+npx -y @yottameta/yotta-chain --agent <智能体名称>      # 装到指定智能体默认用户级技能目录
+npx -y @yottameta/yotta-chain --dir <智能体的技能目录>  # 指到技能目录本身（如 ~/.codex/skills）
 ```
-> 智能体不在预置列表里？用 `--dir` 指定它的 skills 目录，或手动复制（方式三）。`--list` 可查看各智能体对应的默认目录。想手动拿文件也可 `npm pack @yottameta/yotta-chain` 解包后按方式二/三安装。
 
-### 方式二：install.sh 一键安装
-获取技能文件夹后（`npm pack` 解包或 `git clone`），进入技能文件夹：
-```bash
-bash install.sh -g    # 用户级；bash install.sh --list 查看全部目录
-bash install.sh --agent codex   # 指定智能体（--list 可查看可用项）
-bash install.sh       # 项目级：自动检测已存在的 .claude/.cursor/.codex 等 skills 目录
-bash install.sh --dir /path/to/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
 ```
-> 覆盖 17 类智能体，含国内 Trae / Qwen / Comate / CodeBuddy / Kimi。Windows 用户：装有 Git Bash 即可用；否则用方式三手动复制。
 
-### 方式三：手动复制
-把整个 `yotta-chain` 文件夹复制到目标智能体的 skills 目录。常见位置（用户级；Windows 用 `%USERPROFILE%`，Linux/macOS 用 `~`）：
+### 方式三：GitHub 下载压缩包（手动 / 无 git 环境）
 
-| 智能体 | 用户级目录 | 项目级目录 |
-|---|---|---|
-| Codex | `%USERPROFILE%\.codex\skills\yotta-chain\` | `.codex\skills\` |
-| Claude Code | `%USERPROFILE%\.claude\skills\yotta-chain\` | `.claude\skills\` |
-| Cursor | `%USERPROFILE%\.cursor\skills\yotta-chain\` | `.cursor\skills\` |
-| Windsurf | `%USERPROFILE%\.codeium\windsurf\skills\yotta-chain\` | `.windsurf\skills\` |
-| opencode | `%USERPROFILE%\.config\opencode\skills\yotta-chain\` | `.opencode\skills\` |
-| Gemini | `%USERPROFILE%\.gemini\skills\yotta-chain\` | `.gemini\skills\` |
-| Goose | `%USERPROFILE%\.config\goose\skills\yotta-chain\` | `.goose\skills\` |
-| Amp | `%USERPROFILE%\.config\agents\skills\yotta-chain\` | `.agents\skills\` |
-| Kiro | `%USERPROFILE%\.kiro\skills\yotta-chain\` | `.kiro\skills\` |
-| WorkBuddy | `%USERPROFILE%\.workbuddy\skills\yotta-chain\` | `.workbuddy\skills\` |
-| Trae Code CLI | `%USERPROFILE%\.traecli\skills\yotta-chain\` | `.traecli\skills\` |
-| Trae IDE（国内） | `%USERPROFILE%\.trae-cn\skills\yotta-chain\` | `.trae\skills\` |
-| Qwen Code | `%USERPROFILE%\.qwen\skills\yotta-chain\` | `.qwen\skills\` |
-| Comate | `%USERPROFILE%\.comate\skills\yotta-chain\` | `.comate\skills\` |
-| CodeBuddy | `%USERPROFILE%\.codebuddy\skills\yotta-chain\` | `.codebuddy\skills\` |
-| Kimi | `%USERPROFILE%\.kimi\skills\yotta-chain\` | `.kimi\skills\` |
-| 通用 AGENTS.md | `%USERPROFILE%\.agents\skills\yotta-chain\` | `.agents\skills\` |
-
-> 若设置了 Codex 的 `CODEX_HOME`，安装自动以该变量为准；opencode 同理（`XDG_CONFIG_HOME`）。`.agents\skills` 不是通用目录——仅 OpenCode / Cursor / Cline / Amp / Kimi / Gemini CLI / GitHub Copilot 等读取；**Claude Code 与 Codex 默认不读**。不确定时用 `--dir` 或让智能体自行安装。
-
-> 装到项目：在项目内运行 `npx -y @yottameta/yotta-chain` 或 `bash install.sh`，会装到检测到的项目级目录。
+在 GitHub 仓库 `YottaMeta/yotta-chain` 点 **Code → Download ZIP**，解压后把 `yotta-chain` 文件夹放进智能体技能目录。
+
+### 方式四：install.sh（多智能体一键脚本）
 
+```text
+bash install.sh --agent <name>   # 装到指定智能体默认用户级目录
+bash install.sh --dir <path>     # 装到指定目录
+bash install.sh --list           # 列出智能体 -> 默认目录
+```
 
+> 方式一走 npm 源（npmmirror / npmjs），不依赖 GitHub；方式二 / 三走 GitHub，国内无代理可能失败。
 ## 让智能体使用
 
 给智能体下指令即可，例如：
@@ -159,12 +144,12 @@ bash install.sh --dir /path/to/skills
 | `typosquat` | low | 名字与知名包编辑距离 ≤ 2，疑似拼写仿冒 |
 | `snapshot` | low | Maven 依赖使用 SNAPSHOT 版本 |
 
-## 支持的生态（v0.1.1）
+## 支持的生态（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.1 暂不支持（见 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.1
+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.1）
+## 支持的生态（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.1 暂不支持，见 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.1",
+  "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.1）
+## 六、已知限制（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.1"
+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.1")
+        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.1):
+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.1"
+VERSION = "0.1.2"
 
 SEVERITY_ORDER = ["info", "low", "medium", "high"]
 SEVERITY_RANK = {s: i for i, s in enumerate(SEVERITY_ORDER)}