docs: separate plugin install from full manual install (#1544)

2026-04-22 18:13:41 +08:00 · 2026-04-21 18:28:52 -04:00
parent 8ae1499122
commit 8c422a76f4
4 changed files with 82 additions and 59 deletions
--- a/README.md
+++ b/README.md
@@ -191,10 +191,12 @@ This is intentional. Anthropic marketplace/plugin installs are keyed by a canoni

 ### Step 2: Install Rules (Required)

-> WARNING: **Important:** Claude Code plugins cannot distribute `rules` automatically. Install them manually:
+> WARNING: **Important:** Claude Code plugins cannot distribute `rules` automatically.
+>
+> If you already installed ECC via `/plugin install`, **do not run `./install.sh --profile full`, `.\install.ps1 --profile full`, or `npx ecc-install --profile full` afterward**. The plugin already loads ECC skills, commands, and hooks. Running the full installer after a plugin install copies those same surfaces into your user directories and can create duplicate skills plus duplicate runtime behavior.
+>
+> For plugin installs, manually copy only the `rules/` directories you want. Use the full installer only when you are doing a fully manual ECC install instead of the plugin path.
 >
-> If your local Claude setup was wiped or reset, that does not mean you need to repurchase ECC. Start with `ecc list-installed`, then run `ecc doctor` and `ecc repair` before reinstalling anything. That usually restores ECC-managed files without rebuilding your setup. If the problem is account or marketplace access for ECC Tools, handle billing/account recovery separately.
-
 > If your local Claude setup was wiped or reset, that does not mean you need to repurchase ECC. Start with `ecc list-installed`, then run `ecc doctor` and `ecc repair` before reinstalling anything. That usually restores ECC-managed files without rebuilding your setup. If the problem is account or marketplace access for ECC Tools, handle billing/account recovery separately.

 ```bash
@@ -205,34 +207,26 @@ cd everything-claude-code
 # Install dependencies (pick your package manager)
 npm install        # or: pnpm install | yarn install | bun install

-# macOS/Linux
+# Plugin install path: copy only rules
+mkdir -p ~/.claude/rules
+cp -R rules/common ~/.claude/rules/
+cp -R rules/typescript ~/.claude/rules/

-# Recommended: install everything (full profile)
-./install.sh --profile full
-
-# Or install for specific languages only
-./install.sh typescript    # or python or golang or swift or php
-# ./install.sh typescript python golang swift php
-# ./install.sh --target cursor typescript
-# ./install.sh --target antigravity typescript
-# ./install.sh --target gemini --profile full
+# Fully manual ECC install path (use this instead of /plugin install)
+# ./install.sh --profile full
 ```

 ```powershell
 # Windows PowerShell

-# Recommended: install everything (full profile)
-.\install.ps1 --profile full
+# Plugin install path: copy only rules
+New-Item -ItemType Directory -Force -Path "$HOME/.claude/rules" | Out-Null
+Copy-Item -Recurse rules/common "$HOME/.claude/rules/"
+Copy-Item -Recurse rules/typescript "$HOME/.claude/rules/"

-# Or install for specific languages only
-.\install.ps1 typescript   # or python or golang or swift or php
-# .\install.ps1 typescript python golang swift php
-# .\install.ps1 --target cursor typescript
-# .\install.ps1 --target antigravity typescript
-# .\install.ps1 --target gemini --profile full
-
-# npm-installed compatibility entrypoint also works cross-platform
-npx ecc-install typescript
+# Fully manual ECC install path (use this instead of /plugin install)
+# .\install.ps1 --profile full
+# npx ecc-install --profile full
 ```

 For manual install instructions see the README in the `rules/` folder. When copying rules manually, copy the whole language directory (for example `rules/common` or `rules/golang`), not the files inside it, so relative references keep working and filenames do not collide.
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -109,7 +109,11 @@

 ### 第二步：安装规则（必需）

-> WARNING: **重要提示：** Claude Code 插件无法自动分发 `rules`，需要手动安装：
+> WARNING: **重要提示：** Claude Code 插件无法自动分发 `rules`。
+>
+> 如果你已经通过 `/plugin install` 安装了 ECC，**不要再运行 `./install.sh --profile full`、`.\install.ps1 --profile full` 或 `npx ecc-install --profile full`**。插件已经会自动加载 ECC 的技能、命令和 hooks；此时再执行完整安装，会把同一批内容再次复制到用户目录，导致技能重复以及运行时行为重复。
+>
+> 对于插件安装路径，请只手动复制你需要的 `rules/` 目录。只有在你完全不走插件安装、而是选择“纯手动安装 ECC”时，才应该使用完整安装器。

 ```bash
 # 首先克隆仓库
@@ -119,34 +123,26 @@ cd everything-claude-code
 # 安装依赖（选择你常用的包管理器）
 npm install        # 或：pnpm install | yarn install | bun install

-# macOS/Linux 系统
+# 插件安装路径：只复制规则
+mkdir -p ~/.claude/rules
+cp -R rules/common ~/.claude/rules/
+cp -R rules/typescript ~/.claude/rules/

-# 推荐方式：完整安装（完整配置文件）
-./install.sh --profile full
-
-# 或仅为指定编程语言安装
-./install.sh typescript    # 也可安装 python、golang、swift、php
-# ./install.sh typescript python golang swift php
-# ./install.sh --target cursor typescript
-# ./install.sh --target antigravity typescript
-# ./install.sh --target gemini --profile full
+# 纯手动安装 ECC（不要和 /plugin install 叠加）
+# ./install.sh --profile full
 ```

 ```powershell
 # Windows 系统（PowerShell）

-# 推荐方式：完整安装（完整配置文件）
-.\install.ps1 --profile full
+# 插件安装路径：只复制规则
+New-Item -ItemType Directory -Force -Path "$HOME/.claude/rules" | Out-Null
+Copy-Item -Recurse rules/common "$HOME/.claude/rules/"
+Copy-Item -Recurse rules/typescript "$HOME/.claude/rules/"

-# 或仅为指定编程语言安装
-.\install.ps1 typescript   # 也可安装 python、golang、swift、php
-# .\install.ps1 typescript python golang swift php
-# .\install.ps1 --target cursor typescript
-# .\install.ps1 --target antigravity typescript
-# .\install.ps1 --target gemini --profile full
-
-# 通过 npm 安装的兼容入口，支持全平台使用
-npx ecc-install typescript
+# 纯手动安装 ECC（不要和 /plugin install 叠加）
+# .\install.ps1 --profile full
+# npx ecc-install --profile full
 ```

 如需手动安装说明，请查看 `rules/` 文件夹中的 README 文档。手动复制规则文件时，请直接复制**整个语言目录**（例如 `rules/common` 或 `rules/golang`），而非目录内的单个文件，以保证相对路径引用正常、文件名不会冲突。
--- a/docs/zh-CN/README.md
+++ b/docs/zh-CN/README.md
@@ -161,12 +161,16 @@
 /plugin marketplace add https://github.com/affaan-m/everything-claude-code

 # Install plugin
-/plugin install everything-claude-code
+/plugin install everything-claude-code@everything-claude-code
 ```

 ### 步骤 2：安装规则（必需）

-> WARNING: **重要提示：** Claude Code 插件无法自动分发 `rules`。请手动安装它们：
+> WARNING: **重要提示：** Claude Code 插件无法自动分发 `rules`。
+>
+> 如果你已经通过 `/plugin install` 安装了 ECC，**不要再运行 `./install.sh --profile full`、`.\install.ps1 --profile full` 或 `npx ecc-install --profile full`**。插件已经会自动加载 ECC 的技能、命令和 hooks；此时再执行完整安装，会把同一批内容再次复制到用户目录，导致技能重复以及运行时行为重复。
+>
+> 对于插件安装路径，请只手动复制你需要的 `rules/` 目录。只有在你完全不走插件安装、而是选择“纯手动安装 ECC”时，才应该使用完整安装器。

 ```bash
 # Clone the repo first
@@ -176,22 +180,24 @@ cd everything-claude-code
 # Install dependencies (pick your package manager)
 npm install        # or: pnpm install | yarn install | bun install

-# macOS/Linux
-./install.sh typescript    # or python or golang or swift or php
-# ./install.sh typescript python golang swift php
-# ./install.sh --target cursor typescript
-# ./install.sh --target antigravity typescript
+# Plugin install path: copy rules only
+mkdir -p ~/.claude/rules
+cp -R rules/common ~/.claude/rules/
+cp -R rules/typescript ~/.claude/rules/
+
+# Fully manual ECC install path (do this instead of /plugin install)
+# ./install.sh --profile full
 ```

 ```powershell
 # Windows PowerShell
-.\install.ps1 typescript   # or python or golang or swift or php
-# .\install.ps1 typescript python golang swift php
-# .\install.ps1 --target cursor typescript
-# .\install.ps1 --target antigravity typescript
+New-Item -ItemType Directory -Force -Path "$HOME/.claude/rules" | Out-Null
+Copy-Item -Recurse rules/common "$HOME/.claude/rules/"
+Copy-Item -Recurse rules/typescript "$HOME/.claude/rules/"

-# npm-installed compatibility entrypoint also works cross-platform
-npx ecc-install typescript
+# Fully manual ECC install path (do this instead of /plugin install)
+# .\install.ps1 --profile full
+# npx ecc-install --profile full
 ```

 手动安装说明请参阅 `rules/` 文件夹中的 README。
--- a/tests/docs/install-identifiers.test.js
+++ b/tests/docs/install-identifiers.test.js
@@ -25,6 +25,7 @@ const publicInstallDocs = [
  'README.md',
  'README.zh-CN.md',
  'docs/pt-BR/README.md',
+  'docs/zh-CN/README.md',
  'docs/ja-JP/skills/configure-ecc/SKILL.md',
  'docs/zh-CN/skills/configure-ecc/SKILL.md',
 ];
@@ -43,6 +44,32 @@ for (const relativePath of publicInstallDocs) {
  });
 }

+const pluginAndManualInstallDocs = [
+  'README.md',
+  'README.zh-CN.md',
+  'docs/zh-CN/README.md',
+];
+
+for (const relativePath of pluginAndManualInstallDocs) {
+  const content = fs.readFileSync(path.join(repoRoot, relativePath), 'utf8');
+
+  test(`${relativePath} warns not to run the full installer after plugin install`, () => {
+    assert.ok(
+      content.includes('--profile full'),
+      'Expected docs to mention the full installer explicitly'
+    );
+    assert.ok(
+      content.includes('/plugin install'),
+      'Expected docs to mention plugin install explicitly'
+    );
+    assert.ok(
+      content.includes('不要再运行')
+      || content.includes('do not run'),
+      'Expected docs to warn that plugin install and full install are not sequential'
+    );
+  });
+}
+
 if (failed > 0) {
  console.log(`\nFailed: ${failed}`);
  process.exit(1);