@yottameta/yotta-chain 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 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,15 +81,53 @@ python3 scripts/yotta_chain.py version
 
 ## Installation
 
-Install the skill into your agent:
+Pick any of the three methods; skill files are always fetched 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 (recommended, one-liner)
+```bash
+# 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
+```
+> 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
+```
+> 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):
+
+| 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.
 
-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
 
@@ -121,12 +159,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.1)
 
 - **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.1 (see CHANGELOG).
 
 ## Boundaries
 

package/README.zh-CN.md

@@ -81,15 +81,53 @@ 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（推荐，一行安装）
+```bash
+# 国内加速（可选）：npm config set registry https://registry.npmmirror.com
+npx -y @yottameta/yotta-chain -g
+npx -y @yottameta/yotta-chain --dir <你的技能目录>   # 任意智能体：指定目录安装
+```
+> 智能体不在预置列表里？用 `--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
+```
+> 覆盖 17 类智能体，含国内 Trae / Qwen / Comate / CodeBuddy / Kimi。Windows 用户：装有 Git Bash 即可用；否则用方式三手动复制。
+
+### 方式三：手动复制
+把整个 `yotta-chain` 文件夹复制到目标智能体的 skills 目录。常见位置（用户级；Windows 用 `%USERPROFILE%`，Linux/macOS 用 `~`）：
+
+| 智能体 | 用户级目录 | 项目级目录 |
+|---|---|---|
+| 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`，会装到检测到的项目级目录。
 
-装到项目：在项目内运行 `npx -y @yottameta/yotta-chain` 或 `bash install.sh`，会装到检测到的项目级目录。
 
 ## 让智能体使用
 
@@ -121,12 +159,12 @@ python3 scripts/yotta_chain.py version
 | `typosquat` | low | 名字与知名包编辑距离 ≤ 2，疑似拼写仿冒 |
 | `snapshot` | low | Maven 依赖使用 SNAPSHOT 版本 |
 
-## 支持的生态（v0.1.0）
+## 支持的生态（v0.1.1）
 
 - **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.1 暂不支持（见 CHANGELOG）。
 
 ## 边界
 

package/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: yotta-chain
-version: 0.1.0
+version: 0.1.1
 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.1）
 
 - **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.1 暂不支持，见 CHANGELOG 后续计划。
 
 ## 与家族协同
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yottameta/yotta-chain",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "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.1）
 
 - 不做在线 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.1"
 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.1")
 
 
 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.1):
   - 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.1"
 
 SEVERITY_ORDER = ["info", "low", "medium", "high"]
 SEVERITY_RANK = {s: i for i, s in enumerate(SEVERITY_ORDER)}