zcf 2.1.1 → 2.2.0

package/dist/cli.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import ansis from 'ansis';
 import cac from 'cac';
-import { d as SUPPORTED_LANGS, I as I18N, L as LANG_LABELS, z as updateZcfConfig, Z as ZCF_CONFIG_FILE, B as readZcfConfig, D as resolveAiOutputLanguage, p as applyAiLanguageDirective, E as configureAiPersonality, u as updateDefaultModel, F as isWindows, r as readMcpConfig, x as fixWindowsMcpConfig, w as writeMcpConfig, M as MCP_SERVICES, s as backupMcpConfig, v as buildMcpServerConfig, t as mergeMcpServers, o as getExistingApiConfig, G as formatApiKeyDisplay, H as modifyApiConfigPartially, J as validateApiKey, l as configureApi, K as displayBanner, N as selectScriptLanguage, S as SETTINGS_FILE, O as updatePromptOnly, P as version, Q as handleExitPromptError, R as handleGeneralError, T as displayBannerWithInfo, i as init } from './shared/zcf.ccfEwLWL.mjs';
+import { d as SUPPORTED_LANGS, I as I18N, L as LANG_LABELS, z as updateZcfConfig, Z as ZCF_CONFIG_FILE, B as readZcfConfig, D as resolveAiOutputLanguage, p as applyAiLanguageDirective, E as configureAiPersonality, u as updateDefaultModel, F as isWindows, r as readMcpConfig, x as fixWindowsMcpConfig, w as writeMcpConfig, G as selectMcpServices, s as backupMcpConfig, M as MCP_SERVICES, v as buildMcpServerConfig, t as mergeMcpServers, o as getExistingApiConfig, H as formatApiKeyDisplay, J as modifyApiConfigPartially, K as validateApiKey, l as configureApi, N as displayBanner, O as selectScriptLanguage, S as SETTINGS_FILE, P as updatePromptOnly, Q as version, R as handleExitPromptError, T as handleGeneralError, U as displayBannerWithInfo, i as init } from './shared/zcf.BES32wHt.mjs';
 import inquirer from 'inquirer';
 import { existsSync, unlinkSync } from 'node:fs';
 import 'node:os';
@@ -127,31 +127,10 @@ async function configureMcpFeature(scriptLang) {
       console.log(ansis.green(`\u2714 ${i18n.windowsMcpFixed || "Windows MCP configuration fixed"}`));
     }
   }
-  const choices = [
-    {
-      title: ansis.bold(i18n.allServices),
-      value: "ALL",
-      selected: false
-    },
-    ...MCP_SERVICES.map((service) => ({
-      title: `${service.name[scriptLang]} - ${ansis.gray(service.description[scriptLang])}`,
-      value: service.id,
-      selected: false
-    }))
-  ];
-  const { services } = await inquirer.prompt({
-    type: "checkbox",
-    name: "services",
-    message: i18n.selectMcpServices + " " + ansis.gray(i18n.spaceToSelectReturn),
-    choices
-  });
-  if (!services) {
+  const selectedServices = await selectMcpServices(scriptLang);
+  if (!selectedServices) {
     return;
   }
-  let selectedServices = services || [];
-  if (selectedServices.includes("ALL")) {
-    selectedServices = MCP_SERVICES.map((s) => s.id);
-  }
   if (selectedServices.length > 0) {
     const mcpBackupPath = backupMcpConfig();
     if (mcpBackupPath) {
@@ -285,9 +264,6 @@ async function update(options = {}) {
     }
     let configLang = options.configLang;
     if (!configLang) {
-      console.log(ansis.dim(`  ${i18n.configLangHint["zh-CN"]}`));
-      console.log(ansis.dim(`  ${i18n.configLangHint["en"]}
-`));
       const { lang } = await inquirer.prompt({
         type: "list",
         name: "lang",

package/dist/index.mjs

@@ -1,4 +1,4 @@
-export { A as AI_OUTPUT_LANGUAGES, C as CLAUDE_DIR, a as CLAUDE_MD_FILE, b as ClAUDE_CONFIG_FILE, I as I18N, L as LANG_LABELS, M as MCP_SERVICES, S as SETTINGS_FILE, d as SUPPORTED_LANGS, Z as ZCF_CONFIG_FILE, y as addCompletedOnboarding, p as applyAiLanguageDirective, j as backupExistingConfig, s as backupMcpConfig, v as buildMcpServerConfig, c as commandExists, l as configureApi, k as copyConfigFiles, h as ensureClaudeDir, x as fixWindowsMcpConfig, o as getExistingApiConfig, q as getMcpConfigPath, g as getPlatform, i as init, f as installClaudeCode, e as isClaudeCodeInstalled, m as mergeConfigs, t as mergeMcpServers, n as mergeSettingsFile, r as readMcpConfig, u as updateDefaultModel, w as writeMcpConfig } from './shared/zcf.ccfEwLWL.mjs';
+export { A as AI_OUTPUT_LANGUAGES, C as CLAUDE_DIR, a as CLAUDE_MD_FILE, b as ClAUDE_CONFIG_FILE, I as I18N, L as LANG_LABELS, M as MCP_SERVICES, S as SETTINGS_FILE, d as SUPPORTED_LANGS, Z as ZCF_CONFIG_FILE, y as addCompletedOnboarding, p as applyAiLanguageDirective, j as backupExistingConfig, s as backupMcpConfig, v as buildMcpServerConfig, c as commandExists, l as configureApi, k as copyConfigFiles, h as ensureClaudeDir, x as fixWindowsMcpConfig, o as getExistingApiConfig, q as getMcpConfigPath, g as getPlatform, i as init, f as installClaudeCode, e as isClaudeCodeInstalled, m as mergeConfigs, t as mergeMcpServers, n as mergeSettingsFile, r as readMcpConfig, u as updateDefaultModel, w as writeMcpConfig } from './shared/zcf.BES32wHt.mjs';
 import 'inquirer';
 import 'ansis';
 import 'node:fs';

package/dist/shared/{zcf.ccfEwLWL.mjs → zcf.BES32wHt.mjs}

@@ -7,7 +7,7 @@ import dayjs from 'dayjs';
 import { fileURLToPath } from 'node:url';
 import { exec } from 'tinyexec';
 
-const version = "2.1.1";
+const version = "2.2.0";
 const homepage = "https://github.com/UfoMiao/zcf";
 
 const CLAUDE_DIR = join(homedir(), ".claude");
@@ -33,8 +33,8 @@ const I18N = {
     aiOutputLangHint: "AI \u5C06\u4F7F\u7528\u6B64\u8BED\u8A00\u56DE\u590D\u4F60\u7684\u95EE\u9898",
     enterCustomLanguage: "\u8BF7\u8F93\u5165\u81EA\u5B9A\u4E49\u8BED\u8A00\uFF08\u4F8B\u5982\uFF1AJapanese, French \u7B49\uFF09",
     configLangHint: {
-      "zh-CN": "\u4E2D\u6587\u7248\uFF08\u4FBF\u4E8E\u4E2D\u6587\u7528\u6237\u81EA\u5B9A\u4E49\uFF09",
-      en: "\u82F1\u6587\u7248\uFF08\u63A8\u8350\uFF0Ctoken \u6D88\u8017\u66F4\u4F4E\uFF09"
+      "zh-CN": "\u4FBF\u4E8E\u4E2D\u6587\u7528\u6237\u81EA\u5B9A\u4E49",
+      en: "\u63A8\u8350\uFF0Ctoken \u6D88\u8017\u66F4\u4F4E"
     },
     installPrompt: "\u68C0\u6D4B\u5230 Claude Code \u672A\u5B89\u88C5\uFF0C\u662F\u5426\u81EA\u52A8\u5B89\u88C5\uFF1F",
     installing: "\u6B63\u5728\u5B89\u88C5 Claude Code...",
@@ -82,7 +82,7 @@ const I18N = {
     configSuccess: "\u914D\u7F6E\u6587\u4EF6\u5DF2\u590D\u5236\u5230",
     apiConfigSuccess: "API \u914D\u7F6E\u5B8C\u6210",
     mcpConfigSuccess: "MCP \u670D\u52A1\u5DF2\u914D\u7F6E",
-    selectMcpServices: "\u9009\u62E9\u8981\u5B89\u88C5\u7684 MCP \u670D\u52A1\uFF08\u7A7A\u683C\u9009\u62E9\uFF0C\u56DE\u8F66\u786E\u8BA4\uFF09",
+    selectMcpServices: "\u9009\u62E9\u8981\u5B89\u88C5\u7684 MCP \u670D\u52A1\uFF08\u7A7A\u683C\u9009\u62E9\uFF0Ca\u5168\u9009\uFF0Ci\u53CD\u9009\uFF0C\u56DE\u8F66\u786E\u8BA4\uFF09",
     allServices: "\u5168\u90E8\u5B89\u88C5",
     mcpServiceInstalled: "\u5DF2\u9009\u62E9\u7684 MCP \u670D\u52A1",
     enterExaApiKey: "\u8BF7\u8F93\u5165 Exa API Key\uFF08\u53EF\u4ECE https://dashboard.exa.ai/api-keys \u83B7\u53D6\uFF09",
@@ -208,8 +208,8 @@ const I18N = {
     aiOutputLangHint: "AI will respond to you in this language",
     enterCustomLanguage: "Enter custom language (e.g., Japanese, French, etc.)",
     configLangHint: {
-      "zh-CN": "Chinese (easier for Chinese users to customize)",
-      en: "English (recommended, lower token consumption)"
+      "zh-CN": "easier for Chinese users to customize",
+      en: "recommended, lower token consumption"
     },
     installPrompt: "Claude Code not found. Install automatically?",
     installing: "Installing Claude Code...",
@@ -257,7 +257,7 @@ const I18N = {
     configSuccess: "Config files copied to",
     apiConfigSuccess: "API configured",
     mcpConfigSuccess: "MCP services configured",
-    selectMcpServices: "Select MCP services to install (space to select, enter to confirm)",
+    selectMcpServices: "Select MCP services to install (space to select, a to select all, i to deselect, enter to confirm)",
     allServices: "Install all",
     mcpServiceInstalled: "Selected MCP services",
     enterExaApiKey: "Enter Exa API Key (get from https://dashboard.exa.ai/api-keys)",
@@ -1452,6 +1452,26 @@ async function resolveAiOutputLanguage(scriptLang, commandLineOption, savedConfi
   return await selectAiOutputLanguage(scriptLang, scriptLang);
 }
 
+async function selectMcpServices(scriptLang) {
+  const i18n = I18N[scriptLang];
+  const choices = MCP_SERVICES.map((service) => ({
+    name: `${service.name[scriptLang]} - ${ansis.gray(service.description[scriptLang])}`,
+    value: service.id,
+    selected: false
+  }));
+  const { services } = await inquirer.prompt({
+    type: "checkbox",
+    name: "services",
+    message: i18n.selectMcpServices,
+    choices
+  });
+  if (services === void 0) {
+    console.log(ansis.yellow(i18n.cancelled));
+    return void 0;
+  }
+  return services;
+}
+
 async function init(options = {}) {
   try {
     if (!options.skipBanner) {
@@ -1504,10 +1524,9 @@ async function init(options = {}) {
       console.log(ansis.green(`\u2714 ${i18n.installSuccess}`));
     }
     ensureClaudeDir();
-    let onlyUpdateDocs = false;
     let action = "new";
     if (existsSync(SETTINGS_FILE) && !options.force) {
-      const { action: action2 } = await inquirer.prompt({
+      const { action: userAction } = await inquirer.prompt({
         type: "list",
         name: "action",
         message: i18n.existingConfig,
@@ -1518,21 +1537,19 @@ async function init(options = {}) {
           { name: i18n.skip, value: "skip" }
         ]
       });
-      if (!action2) {
+      if (!userAction) {
         console.log(ansis.yellow(i18n.cancelled));
         process.exit(0);
       }
-      if (action2 === "skip") {
+      action = userAction;
+      if (action === "skip") {
         console.log(ansis.yellow(i18n.skip));
         return;
       }
-      if (action2 === "docs-only") {
-        onlyUpdateDocs = true;
-      }
     }
     let apiConfig = null;
     const isNewInstall = !existsSync(SETTINGS_FILE);
-    if (!onlyUpdateDocs && (isNewInstall || action === "backup" || action === "merge")) {
+    if (action !== "docs-only" && (isNewInstall || ["backup", "merge"].includes(action))) {
       const existingApiConfig = getExistingApiConfig();
       if (existingApiConfig) {
         console.log("\n" + ansis.blue(`\u2139 ${i18n.existingApiConfig}`));
@@ -1598,12 +1615,20 @@ async function init(options = {}) {
         }
       }
     }
-    if (action === "backup") ; else if (action === "docs-only") ; else if (action === "merge") ; else if (action === "new") {
+    if (["backup", "docs-only", "merge"].includes(action)) {
+      const backupDir = backupExistingConfig();
+      if (backupDir) {
+        console.log(ansis.gray(`\u2714 ${i18n.backupSuccess}: ${backupDir}`));
+      }
+    }
+    if (action === "docs-only") {
+      copyConfigFiles(configLang, true);
+    } else if (["backup", "merge", "new"].includes(action)) {
       copyConfigFiles(configLang, false);
     }
     applyAiLanguageDirective(aiOutputLang);
     await configureAiPersonality(scriptLang);
-    if (apiConfig && !onlyUpdateDocs) {
+    if (apiConfig && action !== "docs-only") {
       const configuredApi = configureApi(apiConfig);
       if (configuredApi) {
         console.log(ansis.green(`\u2714 ${i18n.apiConfigSuccess}`));
@@ -1616,7 +1641,7 @@ async function init(options = {}) {
         }
       }
     }
-    if (!onlyUpdateDocs) {
+    if (action !== "docs-only") {
       const { shouldConfigureMcp } = await inquirer.prompt({
         type: "confirm",
         name: "shouldConfigureMcp",
@@ -1635,32 +1660,10 @@ async function init(options = {}) {
             )
           );
         }
-        const choices = [
-          {
-            title: ansis.bold(i18n.allServices),
-            value: "ALL",
-            selected: false
-          },
-          ...MCP_SERVICES.map((service) => ({
-            title: `${service.name[scriptLang]} - ${ansis.gray(service.description[scriptLang])}`,
-            value: service.id,
-            selected: false
-          }))
-        ];
-        const { services } = await inquirer.prompt({
-          type: "checkbox",
-          name: "services",
-          message: i18n.selectMcpServices + " " + ansis.gray(i18n.spaceToSelectReturn),
-          choices
-        });
-        if (services === void 0) {
-          console.log(ansis.yellow(i18n.cancelled));
+        const selectedServices = await selectMcpServices(scriptLang);
+        if (selectedServices === void 0) {
           process.exit(0);
         }
-        let selectedServices = services || [];
-        if (selectedServices.includes("ALL")) {
-          selectedServices = MCP_SERVICES.map((s) => s.id);
-        }
         if (selectedServices.length > 0) {
           const mcpBackupPath = backupMcpConfig();
           if (mcpBackupPath) {
@@ -1716,4 +1719,4 @@ async function init(options = {}) {
   }
 }
 
-export { AI_OUTPUT_LANGUAGES as A, readZcfConfig as B, CLAUDE_DIR as C, resolveAiOutputLanguage as D, configureAiPersonality as E, isWindows as F, formatApiKeyDisplay as G, modifyApiConfigPartially as H, I18N as I, validateApiKey as J, displayBanner as K, LANG_LABELS as L, MCP_SERVICES as M, selectScriptLanguage as N, updatePromptOnly as O, version as P, handleExitPromptError as Q, handleGeneralError as R, SETTINGS_FILE as S, displayBannerWithInfo as T, ZCF_CONFIG_FILE as Z, CLAUDE_MD_FILE as a, ClAUDE_CONFIG_FILE as b, commandExists as c, SUPPORTED_LANGS as d, isClaudeCodeInstalled as e, installClaudeCode as f, getPlatform as g, ensureClaudeDir as h, init as i, backupExistingConfig as j, copyConfigFiles as k, configureApi as l, mergeConfigs as m, mergeSettingsFile as n, getExistingApiConfig as o, applyAiLanguageDirective as p, getMcpConfigPath as q, readMcpConfig as r, backupMcpConfig as s, mergeMcpServers as t, updateDefaultModel as u, buildMcpServerConfig as v, writeMcpConfig as w, fixWindowsMcpConfig as x, addCompletedOnboarding as y, updateZcfConfig as z };
+export { AI_OUTPUT_LANGUAGES as A, readZcfConfig as B, CLAUDE_DIR as C, resolveAiOutputLanguage as D, configureAiPersonality as E, isWindows as F, selectMcpServices as G, formatApiKeyDisplay as H, I18N as I, modifyApiConfigPartially as J, validateApiKey as K, LANG_LABELS as L, MCP_SERVICES as M, displayBanner as N, selectScriptLanguage as O, updatePromptOnly as P, version as Q, handleExitPromptError as R, SETTINGS_FILE as S, handleGeneralError as T, displayBannerWithInfo as U, ZCF_CONFIG_FILE as Z, CLAUDE_MD_FILE as a, ClAUDE_CONFIG_FILE as b, commandExists as c, SUPPORTED_LANGS as d, isClaudeCodeInstalled as e, installClaudeCode as f, getPlatform as g, ensureClaudeDir as h, init as i, backupExistingConfig as j, copyConfigFiles as k, configureApi as l, mergeConfigs as m, mergeSettingsFile as n, getExistingApiConfig as o, applyAiLanguageDirective as p, getMcpConfigPath as q, readMcpConfig as r, backupMcpConfig as s, mergeMcpServers as t, updateDefaultModel as u, buildMcpServerConfig as v, writeMcpConfig as w, fixWindowsMcpConfig as x, addCompletedOnboarding as y, updateZcfConfig as z };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "zcf",
   "type": "module",
-  "version": "2.1.1",
+  "version": "2.2.0",
   "description": "Zero-Config Claude-Code Flow - One-click configuration tool for Claude Code",
   "license": "MIT",
   "homepage": "https://github.com/UfoMiao/zcf",

package/templates/CLAUDE.md

@@ -1,4 +1,5 @@
 @language.md
 @personality.md
 @rules.md
+@technical-guides.md
 @mcp.md

package/templates/en/technical-guides.md

@@ -0,0 +1,74 @@
+# Technical Execution Guidelines
+
+This document provides best practices that Claude Code should follow when executing specific technical tasks.
+
+## Command Execution Best Practices
+
+### Path Handling Standards
+
+**Important**: Always use double quotes to wrap file paths when executing commands on all operating systems, especially on Windows.
+
+#### Correct Examples
+```bash
+# ✅ Correct: Paths wrapped in double quotes
+cd "C:\Users\name\My Documents"
+python "C:\Program Files\MyApp\script.py"
+node "/path/with spaces/app.js"
+```
+
+#### Incorrect Examples
+```bash
+# ❌ Incorrect: No quotes, backslashes will be swallowed on Windows
+cd C:\Users\name\My Documents
+python C:\Program Files\MyApp\script.py
+```
+
+### Cross-Platform Compatibility
+
+- Prefer forward slashes `/` as path separators (supported by most tools)
+- When backslashes must be used, ensure paths are wrapped in double quotes
+- Be mindful of spaces and special characters even with relative paths
+
+## Search Tool Usage Guidelines
+
+### Content Search Priority
+
+**Always prioritize `rg` (ripgrep) for file content searches** over `grep`.
+
+> **Note**: ripgrep requires user installation. Most developers already have this tool installed. If `rg` command is not found, remind users to install:
+> - macOS: `brew install ripgrep`
+> - Windows: `scoop install ripgrep` or `choco install ripgrep`
+> - Linux: `sudo apt-get install ripgrep` or see [official installation guide](https://github.com/BurntSushi/ripgrep#installation)
+
+#### Reasons
+1. **Superior Performance**: rg won't timeout in large codebases (e.g., Chromium, Emacs)
+2. **Faster Execution**: rg is significantly faster than grep
+3. **Smarter Defaults**: Automatically respects .gitignore files
+
+#### Usage Examples
+```bash
+# ✅ Prefer rg
+rg "search pattern" .
+rg -i "case insensitive" src/
+rg -t js "console.log" .
+
+# ⚠️ Only use grep when rg is unavailable
+grep -r "pattern" .
+```
+
+### File Finding
+- Use Glob tool for filename pattern matching
+- Use LS tool for directory listings
+- Avoid using `find` command (specialized tools are more efficient)
+
+## Tool Usage Principles
+
+1. **Prefer Specialized Tools**: Use Read, Write, Edit tools instead of cat, echo commands
+2. **Batch Operations**: Call multiple tools simultaneously for efficiency
+3. **Error Handling**: Check for path quoting issues first when commands fail
+
+## Performance Optimization Tips
+
+- Use Task tool for complex searches in large projects
+- Understand project structure before searching to narrow scope
+- Use search parameters wisely (e.g., file type filters) for efficiency

package/templates/zh-CN/commands/workflow.md

@@ -1,5 +1,5 @@
 ---
-description: '专业AI编程助手，提供结构化六阶段开发工作流（研究→构思→计划→执行→优化→评审），集成MCP服务'
+description: '专业AI编程助手，提供结构化六阶段开发工作流（研究→构思→计划→执行→优化→评审），适用于专业开发者'
 allowed-tools:
   - Task
   - Bash

package/templates/zh-CN/technical-guides.md

@@ -0,0 +1,74 @@
+# 技术执行指南
+
+本文档提供 Claude Code 在执行具体技术任务时应遵循的最佳实践。
+
+## 命令执行最佳实践
+
+### 路径处理规范
+
+**重要**：在所有操作系统上执行命令时，**始终使用双引号包裹文件路径**，特别是在 Windows 系统上。
+
+#### 正确示例
+```bash
+# ✅ 正确：路径使用双引号
+cd "C:\Users\name\My Documents"
+python "C:\Program Files\MyApp\script.py"
+node "/path/with spaces/app.js"
+```
+
+#### 错误示例
+```bash
+# ❌ 错误：未使用引号，Windows 下反斜杠会被吞掉
+cd C:\Users\name\My Documents
+python C:\Program Files\MyApp\script.py
+```
+
+### 跨平台兼容性
+
+- 优先使用正斜杠 `/` 作为路径分隔符（大多数工具都支持）
+- 当必须使用反斜杠时，确保路径被双引号包裹
+- 使用相对路径时也要注意空格和特殊字符
+
+## 搜索工具使用指南
+
+### 内容搜索优先级
+
+**始终优先使用 `rg` (ripgrep) 进行文件内容搜索**，而不是 `grep`。
+
+> **注意**：ripgrep 需要用户自行安装。大多数开发者已经安装了此工具，如果遇到 `rg` 命令不存在，请提醒用户安装：
+> - macOS: `brew install ripgrep`
+> - Windows: `scoop install ripgrep` 或 `choco install ripgrep`
+> - Linux: `sudo apt-get install ripgrep` 或查看 [官方安装指南](https://github.com/BurntSushi/ripgrep#installation)
+
+#### 原因
+1. **性能优越**：在大型代码库（如 Chromium、Emacs）中，rg 不会超时
+2. **速度更快**：rg 的执行速度显著快于 grep
+3. **默认配置更智能**：自动忽略 .gitignore 中的文件
+
+#### 使用示例
+```bash
+# ✅ 优先使用 rg
+rg "search pattern" .
+rg -i "case insensitive" src/
+rg -t js "console.log" .
+
+# ⚠️ 仅在 rg 不可用时才使用 grep
+grep -r "pattern" .
+```
+
+### 文件查找
+- 使用 Glob 工具查找文件名模式
+- 使用 LS 工具列出目录内容
+- 避免使用 `find` 命令（使用专门的工具更高效）
+
+## 工具使用原则
+
+1. **优先使用专门的工具**：使用 Read、Write、Edit 等专门工具，而不是 cat、echo 等命令
+2. **批量操作**：可以同时调用多个工具以提高效率
+3. **错误处理**：命令失败后，先检查路径引号问题再重试
+
+## 性能优化建议
+
+- 对于大型项目，使用 Task 工具进行复杂搜索
+- 搜索前先了解项目结构，缩小搜索范围
+- 合理使用搜索参数（如文件类型过滤）以提高效率