abelworkflow 0.6.5 → 0.8.0

package/lib/cli.mjs

@@ -3,17 +3,22 @@ import { cp, link, lstat, mkdir, readFile, readdir, readlink, realpath, rename,
 import { homedir } from "node:os";
 import { dirname, join, relative, resolve } from "node:path";
 import { stdin as input, stdout as output } from "node:process";
-import { createInterface } from "node:readline/promises";
 import { fileURLToPath } from "node:url";
+import * as p from "@clack/prompts";
+import c from "picocolors";
 import {
   assertInteractiveMenuSupported,
+  assertNotCancelled,
+  CancelledError,
+  confirmOrCancel,
   getRunCommandSpawnOptions,
   interactiveMenuDefaultValue,
   interactiveMenuDescriptors,
   parseArgs,
-  resolvePromptValue,
-  resolveSelectValue,
-  shouldUseVisibleSecretFallback
+  required,
+  requiredUnlessExisting,
+  resolvePasswordValue,
+  selectOrCancel
 } from "./cli/logic.mjs";
 
 const __filename = fileURLToPath(import.meta.url);
@@ -30,6 +35,14 @@ const codexTemplateConfigPath = join(codexTemplateRoot, "config-base.toml");
 const codexTemplateAgentsPath = join(codexTemplateRoot, "agents");
 const installBackupStamp = Date.now();
 const createdBackupPaths = new Set();
+const augmentContextEnginePermission = "mcp__augment-context-engine";
+const augmentContextEngineRetrievalTool = "mcp__augment-context-engine__codebase-retrieval";
+const augmentContextEngineFeaturePrompt = {
+  message: "是否启用 augment-context-engine MCP 代码检索支持？不确定建议选否，可减少 MCP 安装和配置麻烦。",
+  initialValue: false
+};
+const localCodebaseRetrievalPolicy = "Use local codebase retrieval with `rg`, `rg --files`, `git grep`, and direct file reads. Do not require augment-context-engine MCP.";
+const augmentCodebaseRetrievalPolicy = `Use \`${augmentContextEngineRetrievalTool}\` as the primary codebase search tool.`;
 const claudeModelEnvKeys = [
   "ANTHROPIC_MODEL",
   "ANTHROPIC_DEFAULT_OPUS_MODEL",
@@ -69,8 +82,7 @@ const defaultClaudeSettings = {
       "WebSearch",
       "TodoWrite",
       "NotebookRead",
-      "NotebookEdit",
-      "mcp__augment-context-engine"
+      "NotebookEdit"
     ],
     deny: []
   },
@@ -98,20 +110,85 @@ const ignoredSkillPathPatterns = [
   /^dev-browser\/tmp(\/|$)/
 ];
 
-function printHelp() {
-  console.log(`AbelWorkflow installer
+function buildDefaultClaudeSettings({ augmentContextEngine = false } = {}) {
+  const settings = {
+    ...defaultClaudeSettings,
+    env: { ...defaultClaudeSettings.env },
+    permissions: {
+      ...defaultClaudeSettings.permissions,
+      allow: [...defaultClaudeSettings.permissions.allow],
+      deny: [...defaultClaudeSettings.permissions.deny]
+    },
+    hooks: { ...defaultClaudeSettings.hooks }
+  };
+
+  if (augmentContextEngine && !settings.permissions.allow.includes(augmentContextEnginePermission)) {
+    settings.permissions.allow.push(augmentContextEnginePermission);
+  }
+
+  return settings;
+}
+
+function getAugmentContextEnginePromptOptions() {
+  return { ...augmentContextEngineFeaturePrompt };
+}
+
+function resolveAugmentContextEngineFeature(options = {}, previousMetadata = {}) {
+  if (typeof options.augmentContextEngine === "boolean") {
+    return options.augmentContextEngine;
+  }
+
+  if (typeof previousMetadata?.features?.augmentContextEngine === "boolean") {
+    return previousMetadata.features.augmentContextEngine;
+  }
+
+  return false;
+}
+
+function getWorkflowRenderValues(augmentContextEngine) {
+  return {
+    CODEBASE_RETRIEVAL_POLICY: augmentContextEngine
+      ? augmentCodebaseRetrievalPolicy
+      : localCodebaseRetrievalPolicy,
+    AUGMENT_CONTEXT_ENGINE_VALIDATION: augmentContextEngine
+      ? `Verify MCP availability:\n   - \`${augmentContextEngineRetrievalTool}\``
+      : "Skip augment-context-engine MCP validation; use local retrieval tools.",
+    CODEBASE_RETRIEVAL_MANDATORY_RULE: augmentContextEngine
+      ? `Mandatory use of \`${augmentContextEngineRetrievalTool}\``
+      : "Mandatory use of configured codebase retrieval policy.",
+    CODEBASE_RETRIEVAL_STRUCTURE_REFERENCE: augmentContextEngine
+      ? `Inspect codebase structure: \`${augmentContextEngineRetrievalTool}\` with \`file list --recursive\`.`
+      : "Inspect codebase structure with `rg --files`, `git grep`, and direct file reads.",
+    CODEBASE_RETRIEVAL_PATTERN_AUDIT: augmentContextEngine
+      ? `Use augment-context-engine to validate against existing codebase patterns.\n   ${augmentContextEngineRetrievalTool}: "Search for existing implementations similar to change <change_name>. Keywords: [key concepts from proposal]"`
+      : "Use `rg`, `rg --files`, `git grep`, and direct file reads to validate against existing codebase patterns."
+  };
+}
 
-Usage:
-  npx abelworkflow
-  npx abelworkflow init
-  npx abelworkflow install
-  npx abelworkflow install --force
-  npx abelworkflow install --link-only
-  npx abelworkflow install --agents-dir /custom/path
+function renderManagedWorkflowContent(content, { augmentContextEngine = false } = {}) {
+  let nextContent = content;
+  for (const [key, value] of Object.entries(getWorkflowRenderValues(augmentContextEngine))) {
+    nextContent = nextContent.replaceAll(`{{${key}}}`, value);
+  }
+  return nextContent;
+}
 
-Default behavior:
+function printHelp() {
+  console.log(`${c.bold("AbelWorkflow")} ${c.cyan("installer")}
+
+${c.bold("Usage:")}
+  ${c.cyan("npx abelworkflow")}
+  ${c.cyan("npx abelworkflow init")}
+  ${c.cyan("npx abelworkflow install")}
+  ${c.cyan("npx abelworkflow install --force")}
+  ${c.cyan("npx abelworkflow install --link-only")}
+  ${c.cyan("npx abelworkflow install --agents-dir /custom/path")}
+  ${c.cyan("npx abelworkflow --non-interactive")}
+
+${c.bold("Default behavior:")}
   - npx abelworkflow: open the interactive setup menu.
   - npx abelworkflow install: sync managed files and links explicitly.
+  - --non-interactive: auto-execute install (skip interactive menu); auto-enabled in CI.
 `);
 }
 
@@ -178,18 +255,18 @@ async function backupExistingPath(targetPath) {
   const backupPath = await createBackupPath(targetPath);
   await cp(targetPath, backupPath, { recursive: true, force: false });
   createdBackupPaths.add(targetPath);
-  console.log(`已备份已有配置: ${pathToLabel(targetPath)} -> ${pathToLabel(backupPath)}`);
+  p.log.message(`已备份已有配置: ${pathToLabel(targetPath)} -> ${pathToLabel(backupPath)}`);
   return backupPath;
 }
 
-async function backupIfNeeded(targetPath, force) {
+async function backupIfNeeded(targetPath) {
   if (!(await pathExists(targetPath))) {
     return null;
   }
 
   const backupPath = await createBackupPath(targetPath);
   await rename(targetPath, backupPath);
-  console.log(`已备份已有配置: ${pathToLabel(targetPath)} -> ${pathToLabel(backupPath)}`);
+  p.log.message(`已备份已有配置: ${pathToLabel(targetPath)} -> ${pathToLabel(backupPath)}`);
   return backupPath;
 }
 
@@ -313,6 +390,28 @@ async function writeInstallMetadata(agentsDir, metadata) {
   await writeFile(join(agentsDir, installMetadataName), `${JSON.stringify(metadata, null, 2)}\n`, "utf8");
 }
 
+async function renderManagedWorkflowFile(path, augmentContextEngine) {
+  if (!(await pathIsFile(path))) {
+    return;
+  }
+
+  const content = await readFile(path, "utf8");
+  const rendered = renderManagedWorkflowContent(content, { augmentContextEngine });
+  if (rendered !== content) {
+    await writeFile(path, rendered, "utf8");
+  }
+}
+
+async function renderManagedWorkflowFiles(agentsDir, augmentContextEngine) {
+  await renderManagedWorkflowFile(join(agentsDir, "AGENTS.md"), augmentContextEngine);
+
+  const commandsDir = join(agentsDir, "commands");
+  const commandFiles = await getCommandNames(commandsDir);
+  for (const fileName of commandFiles) {
+    await renderManagedWorkflowFile(join(commandsDir, fileName), augmentContextEngine);
+  }
+}
+
 async function syncPreservedManagedEntry(sourceRoot, targetRoot, entry, previousManagedChildren) {
   await removeIfNotDirectory(targetRoot);
   await mkdir(targetRoot, { recursive: true });
@@ -449,7 +548,7 @@ async function createSymlink(targetPath, sourcePath, linkType, kind) {
   await symlink(sourcePath, targetPath, linkType);
 }
 
-async function ensureManagedLink(targetPath, sourcePath, kind, force, previousLinkedTargets) {
+async function ensureManagedLink(targetPath, sourcePath, kind, previousLinkedTargets) {
   await mkdir(dirname(targetPath), { recursive: true });
   const sourceResolved = resolve(sourcePath);
   const sourceExists = await pathTargetExists(sourcePath);
@@ -487,7 +586,7 @@ async function ensureManagedLink(targetPath, sourcePath, kind, force, previousLi
     if (wasPreviouslyManaged) {
       await rm(targetPath, { recursive: true, force: true });
     } else {
-      await backupIfNeeded(targetPath, force);
+      await backupIfNeeded(targetPath);
     }
   } else if (!sourceExists) {
     return { targetPath, status: "skipped" };
@@ -525,7 +624,7 @@ function shouldCopyManagedFile(error) {
   return ["EPERM", "EACCES", "EXDEV", "EINVAL", "UNKNOWN"].includes(error?.code);
 }
 
-async function linkSkillDirectories(baseDir, agentsDir, force, previousLinkedTargets) {
+async function linkSkillDirectories(baseDir, agentsDir, previousLinkedTargets) {
   const results = [];
   const skillsRoot = join(agentsDir, "skills");
   const skillNames = (await getDirectoryNames(skillsRoot)).filter((skillName) => skillName !== ".system");
@@ -536,7 +635,6 @@ async function linkSkillDirectories(baseDir, agentsDir, force, previousLinkedTar
         join(baseDir, "skills", skillName),
         join(skillsRoot, skillName),
         "dir",
-        force,
         previousLinkedTargets
       )
     );
@@ -664,19 +762,7 @@ function isWithinManagedRoot(targetPath, managedSourceRoot) {
   return relativePath !== ".." && !relativePath.startsWith(`..${isWindows() ? "\\" : "/"}`);
 }
 
-function getResultMarker(status) {
-  if (status === "unchanged") {
-    return "=";
-  }
-
-  if (status === "removed") {
-    return "-";
-  }
-
-  return "+";
-}
-
-async function linkClaude(agentsDir, force, previousLinkedTargets) {
+async function linkClaude(agentsDir, previousLinkedTargets) {
   const claudeDir = join(home, ".claude");
   await mkdir(claudeDir, { recursive: true });
   await removeIfNotDirectory(join(claudeDir, "commands"));
@@ -689,21 +775,34 @@ async function linkClaude(agentsDir, force, previousLinkedTargets) {
       join(claudeDir, "CLAUDE.md"),
       join(agentsDir, "AGENTS.md"),
       "file",
-      force,
       previousLinkedTargets
     ),
-    await ensureManagedLink(
-      join(claudeDir, "commands", "oc"),
-      join(agentsDir, "commands", "oc"),
-      "dir",
-      force,
-      previousLinkedTargets
-    ),
-    ...(await linkSkillDirectories(claudeDir, agentsDir, force, previousLinkedTargets))
+    ...(await (async () => {
+      const commandFiles = await getCommandNames(join(agentsDir, "commands"));
+      const r = [];
+      r.push(...(await pruneManagedTargets(
+        join(claudeDir, "commands"),
+        join(agentsDir, "commands"),
+        commandFiles,
+        previousLinkedTargets
+      )));
+      for (const fileName of commandFiles) {
+        r.push(
+          await ensureManagedLink(
+            join(claudeDir, "commands", fileName),
+            join(agentsDir, "commands", fileName),
+            "file",
+            previousLinkedTargets
+          )
+        );
+      }
+      return r;
+    })()),
+    ...(await linkSkillDirectories(claudeDir, agentsDir, previousLinkedTargets))
   ];
 }
 
-async function linkCodex(agentsDir, force, previousLinkedTargets) {
+async function linkCodex(agentsDir, previousLinkedTargets) {
   const results = [];
   const codexDir = join(home, ".codex");
   await mkdir(codexDir, { recursive: true });
@@ -717,17 +816,16 @@ async function linkCodex(agentsDir, force, previousLinkedTargets) {
       join(codexDir, "AGENTS.md"),
       join(agentsDir, "AGENTS.md"),
       "file",
-      force,
       previousLinkedTargets
     )
   );
-  results.push(...(await linkSkillDirectories(codexDir, agentsDir, force, previousLinkedTargets)));
+  results.push(...(await linkSkillDirectories(codexDir, agentsDir, previousLinkedTargets)));
 
-  const commandFiles = await getCommandNames(join(agentsDir, "commands", "oc"));
+  const commandFiles = await getCommandNames(join(agentsDir, "commands"));
   results.push(
     ...(await pruneManagedTargets(
       join(codexDir, "prompts"),
-      join(agentsDir, "commands", "oc"),
+      join(agentsDir, "commands"),
       commandFiles,
       previousLinkedTargets
     ))
@@ -736,9 +834,8 @@ async function linkCodex(agentsDir, force, previousLinkedTargets) {
     results.push(
       await ensureManagedLink(
         join(codexDir, "prompts", fileName),
-        join(agentsDir, "commands", "oc", fileName),
+        join(agentsDir, "commands", fileName),
         "file",
-        force,
         previousLinkedTargets
       )
     );
@@ -750,19 +847,41 @@ async function linkCodex(agentsDir, force, previousLinkedTargets) {
 async function installManagedWorkflow(options) {
   let previousMetadata = {};
   let managedChildren = {};
+  let augmentContextEngine = false;
+  const s = p.spinner();
 
   if (!options.relinkOnly) {
-    ({ previousMetadata, managedChildren } = await syncManagedFiles(options.agentsDir));
+    s.start("正在同步工作流文件...");
+    try {
+      ({ previousMetadata, managedChildren } = await syncManagedFiles(options.agentsDir));
+      augmentContextEngine = resolveAugmentContextEngineFeature(options, previousMetadata);
+      await renderManagedWorkflowFiles(options.agentsDir, augmentContextEngine);
+    } catch (e) {
+      s.cancel(c.red(`同步失败: ${e.message}`));
+      throw e;
+    }
+    s.stop("工作流文件已同步");
   } else if (!(await pathExists(options.agentsDir))) {
     throw new Error(`${options.agentsDir} does not exist; remove --link-only or install first`);
   } else {
     previousMetadata = await readInstallMetadata(options.agentsDir);
     managedChildren = previousMetadata.managedChildren ?? {};
+    augmentContextEngine = resolveAugmentContextEngineFeature(options, previousMetadata);
   }
 
   const previousLinkedTargets = previousMetadata.linkedTargets ?? {};
-  const claudeResults = await linkClaude(options.agentsDir, options.force, previousLinkedTargets);
-  const codexResults = await linkCodex(options.agentsDir, options.force, previousLinkedTargets);
+  s.start("正在链接 Claude / Codex...");
+  let claudeResults;
+  let codexResults;
+  try {
+    claudeResults = await linkClaude(options.agentsDir, previousLinkedTargets);
+    codexResults = await linkCodex(options.agentsDir, previousLinkedTargets);
+  } catch (e) {
+    s.cancel(c.red(`链接失败: ${e.message}`));
+    throw e;
+  }
+  s.stop("链接完成");
+
   const linkedTargets = Object.fromEntries(
     [...claudeResults, ...codexResults]
       .filter((result) => result.sourcePath)
@@ -776,21 +895,30 @@ async function installManagedWorkflow(options) {
       ])
   );
 
+  const managedClaudePermissions = await ensureClaudeSettingsForFeature(augmentContextEngine, previousMetadata);
+
   await writeInstallMetadata(options.agentsDir, {
     package: "abelworkflow",
     installedAt: new Date().toISOString(),
+    features: {
+      ...(previousMetadata.features && typeof previousMetadata.features === "object" ? previousMetadata.features : {}),
+      augmentContextEngine
+    },
     managedChildren,
+    managedClaudePermissions,
     linkedTargets
   });
 
-  console.log(`Installed AbelWorkflow into ${options.agentsDir}`);
-  console.log("");
-  console.log("Linked targets:");
-  for (const result of [...claudeResults, ...codexResults]) {
-    console.log(`- ${getResultMarker(result.status)} ${result.targetPath}`);
-  }
-  console.log("");
-  console.log("Done. Re-run `npx abelworkflow@latest` to update the managed files.");
+  const resultLines = [...claudeResults, ...codexResults].map((result) => {
+    const icon = result.status === "unchanged" ? c.gray("=")
+      : result.status === "removed" ? c.yellow("−")
+        : c.green("+");
+    return `${icon}  ${pathToLabel(result.targetPath)}`;
+  }).join("\n");
+
+  p.note(resultLines, "链接结果");
+  p.log.step(`工作流目录: ${c.cyan(pathToLabel(options.agentsDir))}`);
+  p.log.message(`完成后可运行 ${c.cyan("npx abelworkflow@latest")} 更新托管文件`);
 }
 
 async function readJsonFileSafe(path, fallback = {}) {
@@ -882,121 +1010,6 @@ async function updateDotenvFile(path, updates) {
   await writeFile(path, renderDotenv(current), "utf8");
 }
 
-function currentChoiceIndex(choices, defaultValue) {
-  if (defaultValue === undefined) {
-    return -1;
-  }
-  return choices.findIndex((choice) => choice.value === defaultValue);
-}
-
-async function setTerminalEcho(enabled) {
-  if (!input.isTTY || isWindows()) {
-    return;
-  }
-
-  const result = spawnSync("stty", [enabled ? "echo" : "-echo"], { stdio: ["inherit", "ignore", "ignore"] });
-  if (result.error) {
-    throw result.error;
-  }
-}
-
-async function promptText(message, options = {}) {
-  const { defaultValue, allowEmpty = false } = options;
-
-  while (true) {
-    const suffix = defaultValue !== undefined && defaultValue !== ""
-      ? ` [${defaultValue}]`
-      : "";
-    const rl = createInterface({ input, output });
-    let answer;
-    try {
-      answer = await rl.question(`${message}${suffix}: `);
-    } finally {
-      rl.close();
-    }
-
-    const resolved = resolvePromptValue(answer, { defaultValue, allowEmpty });
-    if (resolved.ok) {
-      return resolved.value;
-    }
-    console.log(resolved.error);
-  }
-}
-
-async function promptSecret(message, options = {}) {
-  const { defaultValue, allowEmpty = false } = options;
-
-  if (shouldUseVisibleSecretFallback({ inputIsTTY: input.isTTY, platform: getPlatform() })) {
-    while (true) {
-      const suffix = defaultValue !== undefined && defaultValue !== ""
-        ? " [直接回车保留现有值]"
-        : "";
-      const rl = createInterface({ input, output });
-      let answer;
-      try {
-        answer = await rl.question(`${message}${suffix}: `);
-      } finally {
-        rl.close();
-      }
-
-      const resolved = resolvePromptValue(answer, { defaultValue, allowEmpty });
-      if (resolved.ok) {
-        return resolved.value;
-      }
-      console.log(resolved.error);
-    }
-  }
-
-  while (true) {
-    const suffix = defaultValue !== undefined && defaultValue !== ""
-      ? " [直接回车保留现有值]"
-      : "";
-    const rl = createInterface({ input, output, terminal: true });
-    let answer;
-    try {
-      await setTerminalEcho(false);
-      answer = await rl.question(`${message}${suffix}: `);
-      output.write("\n");
-    } finally {
-      await setTerminalEcho(true);
-      rl.close();
-    }
-
-    const resolved = resolvePromptValue(answer, { defaultValue, allowEmpty });
-    if (resolved.ok) {
-      return resolved.value;
-    }
-    console.log(resolved.error);
-  }
-}
-
-async function promptSelect(message, choices, options = {}) {
-  const defaultIndex = currentChoiceIndex(choices, options.defaultValue);
-  console.log(`\n${message}`);
-  choices.forEach((choice, index) => {
-    const defaultMarker = index === defaultIndex ? " [默认]" : "";
-    console.log(`  ${index + 1}. ${choice.label}${defaultMarker}`);
-  });
-
-  while (true) {
-    const fallbackValue = defaultIndex >= 0 ? String(defaultIndex + 1) : undefined;
-    const answer = await promptText("请输入序号", { defaultValue: fallbackValue, allowEmpty: defaultIndex >= 0 });
-    const resolved = resolveSelectValue(answer, choices);
-    if (resolved.ok) {
-      return resolved.value;
-    }
-    console.log(resolved.error);
-  }
-}
-
-async function promptConfirm(message, defaultValue = true) {
-  const value = await promptSelect(message, [
-    { value: true, label: "是" },
-    { value: false, label: "否" }
-  ], { defaultValue });
-  return value;
-}
-
 function commandExists(command) {
   const checker = isWindows() ? "where" : "which";
   const result = spawnSync(checker, [command], { stdio: "ignore" });
@@ -1017,22 +1030,12 @@ async function runCommand(command, args) {
   });
 }
 
-function sanitizeProviderId(name) {
-  return name
-    .trim()
-    .toLowerCase()
-    .replace(/[\s.]+/gu, "-")
-    .replace(/[^a-z0-9_-]/gu, "")
-    .replace(/-+/gu, "-")
-    .replace(/^-|-$/gu, "") || "abelworkflow";
-}
-
 async function ensureWorkflowPresent(agentsDir) {
   if (await pathExists(join(agentsDir, "AGENTS.md"))) {
     return;
   }
 
-  console.log("未检测到已安装的 AbelWorkflow，先执行一次工作流同步。");
+  p.log.message("未检测到已安装的 AbelWorkflow，先执行一次工作流同步。");
   await installManagedWorkflow({
     agentsDir,
     force: false,
@@ -1044,123 +1047,239 @@ async function configureGrokSearchEnv(agentsDir) {
   await ensureWorkflowPresent(agentsDir);
   const envPath = join(agentsDir, "skills", "grok-search", ".env");
   const existing = await readDotenvFile(envPath);
-  const baseUrl = await promptText("Grok API URL", {
-    defaultValue: existing.GROK_API_URL || "https://api.x.ai/v1"
+  const baseUrl = await p.text({
+    message: "Grok API URL",
+    defaultValue: existing.GROK_API_URL || "https://api.x.ai/v1",
+    validate: required()
   });
-  const apiKey = await promptSecret("Grok API Key", {
-    defaultValue: existing.GROK_API_KEY || undefined
+  assertNotCancelled(baseUrl);
+
+  const apiKey = await p.password({
+    message: "Grok API Key（输入 - 清除）",
+    mask: "*",
+    defaultValue: existing.GROK_API_KEY || undefined,
+    validate: requiredUnlessExisting(existing.GROK_API_KEY, "Grok API Key 不能为空")
   });
-  const model = await promptText("Grok 默认模型", {
-    defaultValue: existing.GROK_MODEL || "grok-4-fast"
+  assertNotCancelled(apiKey);
+  const finalApiKey = resolvePasswordValue(apiKey, existing.GROK_API_KEY);
+
+  const model = await p.text({
+    message: "Grok 默认模型",
+    defaultValue: existing.GROK_MODEL || "grok-4-fast",
+    validate: required()
+  });
+  assertNotCancelled(model);
+
+  const useTavily = await confirmOrCancel({
+    message: "是否同时配置 Tavily 作为额外搜索源？",
+    initialValue: Boolean(existing.TAVILY_API_KEY)
   });
-  const useTavily = await promptConfirm("是否同时配置 Tavily 作为额外搜索源？", Boolean(existing.TAVILY_API_KEY));
+
   const tavilyKey = useTavily
-    ? await promptSecret("Tavily API Key", { defaultValue: existing.TAVILY_API_KEY || undefined })
+    ? await p.password({
+        message: "Tavily API Key（输入 - 清除）",
+        mask: "*",
+        defaultValue: existing.TAVILY_API_KEY || undefined,
+        validate: requiredUnlessExisting(existing.TAVILY_API_KEY, "Tavily API Key 不能为空")
+      })
     : "";
+  if (useTavily) assertNotCancelled(tavilyKey);
+  const finalTavilyKey = useTavily ? resolvePasswordValue(tavilyKey, existing.TAVILY_API_KEY) : null;
 
   await updateDotenvFile(envPath, {
     GROK_API_URL: baseUrl,
-    GROK_API_KEY: apiKey,
+    GROK_API_KEY: finalApiKey,
     GROK_MODEL: model,
-    TAVILY_API_KEY: useTavily ? tavilyKey : null,
+    TAVILY_API_KEY: finalTavilyKey,
     TAVILY_ENABLED: useTavily ? "true" : null
   });
 
-  console.log(`已写入 ${pathToLabel(envPath)}`);
+  p.log.step(`已写入 ${pathToLabel(envPath)}`);
 }
 
 async function configureContext7Env(agentsDir) {
   await ensureWorkflowPresent(agentsDir);
   const envPath = join(agentsDir, "skills", "context7-auto-research", ".env");
   const existing = await readDotenvFile(envPath);
-  const apiKey = await promptSecret("Context7 API Key", {
-    defaultValue: existing.CONTEXT7_API_KEY || undefined,
-    allowEmpty: true
+  const apiKey = await p.password({
+    message: "Context7 API Key (可选，输入 - 清除)",
+    mask: "*",
+    defaultValue: existing.CONTEXT7_API_KEY || undefined
   });
+  assertNotCancelled(apiKey);
+  const finalApiKey = resolvePasswordValue(apiKey, existing.CONTEXT7_API_KEY);
 
   await updateDotenvFile(envPath, {
-    CONTEXT7_API_KEY: apiKey || null
+    CONTEXT7_API_KEY: finalApiKey
   });
 
-  console.log(`已写入 ${pathToLabel(envPath)}`);
+  p.log.step(`已写入 ${pathToLabel(envPath)}`);
+}
+
+function hasPromptEnhancerApiConfig(config) {
+  return [config.PE_API_URL, config.PE_API_KEY, config.PE_MODEL]
+    .every((value) => typeof value === "string" && value.trim() !== "");
 }
 
 function resolvePromptEnhancerMode(existing) {
-  if (existing.ANTHROPIC_API_KEY) {
-    return "anthropic";
-  }
-  if (existing.OPENAI_API_KEY) {
-    return "openai";
-  }
-  return "local";
+  return hasPromptEnhancerApiConfig(existing) ? "openai-compatible" : "agent";
 }
 
 async function configurePromptEnhancerEnv(agentsDir) {
   await ensureWorkflowPresent(agentsDir);
   const envPath = join(agentsDir, "skills", "prompt-enhancer", ".env");
   const existing = await readDotenvFile(envPath);
-  const mode = await promptSelect("请选择 prompt-enhancer 使用的提供方", [
-    { value: "anthropic", label: "Anthropic 兼容 Key" },
-    { value: "openai", label: "OpenAI 兼容 Key" },
-    { value: "local", label: "仅保留本地模板兜底，不写 API Key" }
-  ], { defaultValue: resolvePromptEnhancerMode(existing) });
-
-  if (mode === "anthropic") {
-    const apiKey = await promptSecret("ANTHROPIC_API_KEY", {
-      defaultValue: existing.ANTHROPIC_API_KEY || undefined
-    });
-    const model = await promptText("PE_MODEL", {
-      defaultValue: existing.PE_MODEL || "claude-sonnet-4-20250514"
-    });
+  const mode = await selectOrCancel({
+    message: "请选择 prompt-enhancer 的运行方式",
+    options: [
+      { value: "openai-compatible", label: "第三方 OpenAI 兼容接口" },
+      { value: "agent", label: "直接使用当前 Agent" }
+    ],
+    initialValue: resolvePromptEnhancerMode(existing)
+  });
 
-    await updateDotenvFile(envPath, {
-      ANTHROPIC_API_KEY: apiKey,
-      OPENAI_API_KEY: null,
-      PE_MODEL: model
+  if (mode === "openai-compatible") {
+    const apiUrl = await p.text({
+      message: "PE_API_URL",
+      defaultValue: existing.PE_API_URL || undefined,
+      validate: required()
     });
-  } else if (mode === "openai") {
-    const apiKey = await promptSecret("OPENAI_API_KEY", {
-      defaultValue: existing.OPENAI_API_KEY || undefined
+    assertNotCancelled(apiUrl);
+
+    const apiKey = await p.password({
+      message: "PE_API_KEY（输入 - 清除）",
+      mask: "*",
+      defaultValue: existing.PE_API_KEY || undefined,
+      validate: requiredUnlessExisting(existing.PE_API_KEY, "PE_API_KEY 不能为空")
     });
-    const model = await promptText("PE_MODEL", {
-      defaultValue: existing.PE_MODEL || "gpt-4o"
+    assertNotCancelled(apiKey);
+    const finalApiKey = resolvePasswordValue(apiKey, existing.PE_API_KEY);
+
+    const model = await p.text({
+      message: "PE_MODEL",
+      defaultValue: existing.PE_MODEL || undefined,
+      validate: required()
     });
+    assertNotCancelled(model);
 
     await updateDotenvFile(envPath, {
-      OPENAI_API_KEY: apiKey,
+      PE_API_URL: apiUrl,
+      PE_API_KEY: finalApiKey,
+      PE_MODEL: model,
       ANTHROPIC_API_KEY: null,
-      PE_MODEL: model
+      OPENAI_API_KEY: null
     });
   } else {
     await updateDotenvFile(envPath, {
+      PE_API_URL: null,
+      PE_API_KEY: null,
+      PE_MODEL: null,
       ANTHROPIC_API_KEY: null,
       OPENAI_API_KEY: null
     });
   }
 
-  console.log(`已写入 ${pathToLabel(envPath)}`);
+  p.log.step(`已写入 ${pathToLabel(envPath)}`);
 }
 
-function mergeClaudeSettingsWithDefaults(settings) {
+function mergeClaudeSettingsWithDefaults(settings, { augmentContextEngine = false } = {}) {
+  const defaults = buildDefaultClaudeSettings({ augmentContextEngine });
   const env = settings?.env && typeof settings.env === "object" ? settings.env : {};
   const permissions = settings?.permissions && typeof settings.permissions === "object" ? settings.permissions : {};
   return {
-    ...defaultClaudeSettings,
+    ...defaults,
     ...settings,
     env: {
-      ...defaultClaudeSettings.env,
+      ...defaults.env,
       ...env
     },
     permissions: {
-      ...defaultClaudeSettings.permissions,
+      ...defaults.permissions,
       ...permissions,
-      allow: Array.isArray(permissions.allow) ? permissions.allow : defaultClaudeSettings.permissions.allow,
-      deny: Array.isArray(permissions.deny) ? permissions.deny : defaultClaudeSettings.permissions.deny
+      allow: Array.isArray(permissions.allow) ? permissions.allow : defaults.permissions.allow,
+      deny: Array.isArray(permissions.deny) ? permissions.deny : defaults.permissions.deny
     },
-    hooks: settings?.hooks && typeof settings.hooks === "object" ? settings.hooks : defaultClaudeSettings.hooks
+    hooks: settings?.hooks && typeof settings.hooks === "object" ? settings.hooks : defaults.hooks
+  };
+}
+
+function getPreviousManagedClaudePermissions(previousMetadata = {}) {
+  return Array.isArray(previousMetadata.managedClaudePermissions)
+    ? previousMetadata.managedClaudePermissions.filter((value) => typeof value === "string")
+    : [];
+}
+
+function applyClaudePermissionFeature(settings, {
+  augmentContextEngine = false,
+  previousManagedPermissions = []
+} = {}) {
+  const hasSettings = settings && typeof settings === "object";
+  const wasManaged = previousManagedPermissions.includes(augmentContextEnginePermission);
+  if (!hasSettings && !augmentContextEngine) {
+    return { settings, changed: false, managedPermissions: [] };
+  }
+
+  const defaults = buildDefaultClaudeSettings({ augmentContextEngine: false });
+  const nextSettings = hasSettings
+    ? {
+        ...settings,
+        permissions: settings.permissions && typeof settings.permissions === "object"
+          ? { ...settings.permissions }
+          : {}
+      }
+    : defaults;
+  const permissions = nextSettings.permissions;
+  const allow = Array.isArray(permissions.allow)
+    ? [...permissions.allow]
+    : [...defaults.permissions.allow];
+  let changed = !hasSettings;
+  let isManaged = wasManaged;
+
+  if (augmentContextEngine) {
+    if (!allow.includes(augmentContextEnginePermission)) {
+      allow.push(augmentContextEnginePermission);
+      changed = true;
+      isManaged = true;
+    }
+  } else if (wasManaged && allow.includes(augmentContextEnginePermission)) {
+    allow.splice(allow.indexOf(augmentContextEnginePermission), 1);
+    changed = true;
+    isManaged = false;
+  } else {
+    isManaged = false;
+  }
+
+  permissions.allow = allow;
+  if (!Array.isArray(permissions.deny)) {
+    permissions.deny = [...defaults.permissions.deny];
+  }
+  nextSettings.permissions = permissions;
+
+  return {
+    settings: nextSettings,
+    changed,
+    managedPermissions: isManaged ? [augmentContextEnginePermission] : []
   };
 }
 
+async function ensureClaudeSettingsForFeature(augmentContextEngine, previousMetadata) {
+  const settingsExists = await pathExists(claudeSettingsPath);
+  const settings = settingsExists ? await readJsonFileSafe(claudeSettingsPath, {}) : undefined;
+  const result = applyClaudePermissionFeature(settings, {
+    augmentContextEngine,
+    previousManagedPermissions: getPreviousManagedClaudePermissions(previousMetadata)
+  });
+
+  if (result.changed && result.settings) {
+    if (settingsExists) {
+      await backupExistingPath(claudeSettingsPath);
+    }
+    await writeJsonFileSafe(claudeSettingsPath, result.settings);
+  }
+
+  return result.managedPermissions;
+}
+
 function getExistingClaudeApiConfig(settings) {
   const env = mergeClaudeSettingsWithDefaults(settings).env;
   return {
@@ -1198,28 +1317,46 @@ function ensureApprovedClaudeApiKey(config, apiKey) {
 async function configureClaudeApi() {
   const settings = await readJsonFileSafe(claudeSettingsPath, {});
   const existing = getExistingClaudeApiConfig(settings);
-  const authType = await promptSelect("Claude Code 第三方 API 认证方式", [
-    { value: "api_key", label: "API Key" },
-    { value: "auth_token", label: "Auth Token" }
-  ], { defaultValue: existing.authType });
-  const baseUrl = await promptText("Claude Code Base URL", {
-    defaultValue: existing.baseUrl
+  const authType = await selectOrCancel({
+    message: "Claude Code 第三方 API 认证方式",
+    options: [
+      { value: "api_key", label: "API Key" },
+      { value: "auth_token", label: "Auth Token" }
+    ],
+    initialValue: existing.authType
+  });
+
+  const baseUrl = await p.text({
+    message: "Claude Code Base URL",
+    defaultValue: existing.baseUrl,
+    validate: required()
   });
-  const key = await promptSecret(authType === "auth_token" ? "Claude Code Auth Token" : "Claude Code API Key", {
-    defaultValue: existing.key || undefined
+  assertNotCancelled(baseUrl);
+
+  const key = await p.password({
+    message: authType === "auth_token" ? "Claude Code Auth Token（输入 - 清除）" : "Claude Code API Key（输入 - 清除）",
+    mask: "*",
+    defaultValue: existing.key || undefined,
+    validate: requiredUnlessExisting(existing.key, "API Key / Auth Token 不能为空")
   });
-  const model = await promptText("Claude Code 模型", {
-    defaultValue: existing.model || undefined
+  assertNotCancelled(key);
+  const finalKey = resolvePasswordValue(key, existing.key);
+
+  const model = await p.text({
+    message: "Claude Code 模型",
+    defaultValue: existing.model || undefined,
+    validate: required()
   });
+  assertNotCancelled(model);
 
   const nextSettings = mergeClaudeSettingsWithDefaults(settings);
   nextSettings.env.ANTHROPIC_BASE_URL = baseUrl;
 
   if (authType === "auth_token") {
-    nextSettings.env.ANTHROPIC_AUTH_TOKEN = key;
+    nextSettings.env.ANTHROPIC_AUTH_TOKEN = finalKey;
     delete nextSettings.env.ANTHROPIC_API_KEY;
   } else {
-    nextSettings.env.ANTHROPIC_API_KEY = key;
+    nextSettings.env.ANTHROPIC_API_KEY = finalKey;
     delete nextSettings.env.ANTHROPIC_AUTH_TOKEN;
   }
   for (const field of claudeModelEnvKeys) {
@@ -1230,10 +1367,10 @@ async function configureClaudeApi() {
 
   const metaConfig = await readJsonFileSafe(claudeMetaConfigPath, {});
   metaConfig.hasCompletedOnboarding = true;
-  ensureApprovedClaudeApiKey(metaConfig, key);
+  ensureApprovedClaudeApiKey(metaConfig, finalKey);
   await writeJsonFileWithBackup(claudeMetaConfigPath, metaConfig);
 
-  console.log(`已更新 ${pathToLabel(claudeSettingsPath)} (${authType}, ${baseUrl}, ${maskSecret(key)})`);
+  p.log.step(`已更新 ${pathToLabel(claudeSettingsPath)} (${authType}, ${baseUrl}, ${maskSecret(finalKey)})`);
 }
 
 function updateTopLevelTomlField(content, field, value) {
@@ -1723,13 +1860,24 @@ async function configureCodexApi() {
   const existing = await getExistingCodexApiConfig();
   const providerId = existing.providerId || "abelworkflow";
   const providerName = existing.providerName || providerId;
-  const baseUrl = await promptText("Codex Base URL", {
-    defaultValue: existing.baseUrl
+  const baseUrl = await p.text({
+    message: "Codex Base URL",
+    defaultValue: existing.baseUrl,
+    validate: required()
   });
-  const apiKey = await promptSecret("Codex 第三方 API Key", {
-    defaultValue: existing.apiKey || undefined
+  assertNotCancelled(baseUrl);
+
+  const apiKey = await p.password({
+    message: "Codex 第三方 API Key（输入 - 清除）",
+    mask: "*",
+    defaultValue: existing.apiKey || undefined,
+    validate: requiredUnlessExisting(existing.apiKey, "API Key 不能为空")
   });
-  const shouldDeploySubagents = await promptConfirm("是否部署 Codex subagents 配置？", true);
+  assertNotCancelled(apiKey);
+  const finalApiKey = resolvePasswordValue(apiKey, existing.apiKey);
+
+  const shouldDeploySubagents = await confirmOrCancel({ message: "是否部署 Codex subagents 配置？", initialValue: true });
+
   const envKey = existing.envKey || "OPENAI_API_KEY";
   const currentContent = await pathExists(codexConfigPath) ? await readFile(codexConfigPath, "utf8") : "";
   const templateContent = await loadBundledCodexConfigTemplate();
@@ -1747,16 +1895,16 @@ async function configureCodexApi() {
   await mkdir(dirname(codexConfigPath), { recursive: true });
   await writeFile(codexConfigPath, content, "utf8");
 
-  const auth = mergeCodexAuthData(await readJsonFileSafe(codexAuthPath, {}), envKey, apiKey, existing.legacyEnvKeys || []);
+  const auth = mergeCodexAuthData(await readJsonFileSafe(codexAuthPath, {}), envKey, finalApiKey, existing.legacyEnvKeys || []);
   await writeJsonFileWithBackup(codexAuthPath, auth);
 
-  console.log(`已更新 ${pathToLabel(codexConfigPath)} (${providerId}, ${baseUrl})`);
-  console.log(`已更新 ${pathToLabel(codexAuthPath)} (${maskSecret(apiKey)})`);
+  p.log.step(`已更新 ${pathToLabel(codexConfigPath)} (${providerId}, ${baseUrl})`);
+  p.log.step(`已更新 ${pathToLabel(codexAuthPath)} (${maskSecret(finalApiKey)})`);
   if (shouldDeploySubagents) {
     const deployed = await deployBundledCodexAgents();
-    console.log(`已部署 ${deployed.length} 个 Codex subagents 到 ${pathToLabel(join(home, ".codex", "agents"))}`);
+    p.log.step(`已部署 ${deployed.length} 个 Codex subagents 到 ${pathToLabel(join(home, ".codex", "agents"))}`);
   } else {
-    console.log("已跳过 Codex subagents 部署。");
+    p.log.message("已跳过 Codex subagents 部署。");
   }
 }
 
@@ -1827,55 +1975,68 @@ async function installCliTool(tool) {
 
   const installed = commandExists(toolConfig.command);
   if (installed) {
-    const shouldUpdate = await promptConfirm(`${toolConfig.label} 已检测到，是否继续执行 npm 强制安装/更新？`, false);
+    const shouldUpdate = await confirmOrCancel({
+      message: `${toolConfig.label} 已检测到，是否继续执行 npm 强制安装/更新？`,
+      initialValue: false
+    });
     if (!shouldUpdate) {
-      console.log(`跳过 ${toolConfig.label} 安装。`);
+      p.log.message(`跳过 ${toolConfig.label} 安装。`);
       return;
     }
   }
 
-  console.log(`开始安装 ${toolConfig.label}...`);
-  await runCommand("npm", ["install", "-g", toolConfig.packageName, "--force"]);
-  console.log(`${toolConfig.label} 安装完成。`);
+  const s = p.spinner();
+  s.start(`正在安装 ${toolConfig.label}...`);
+  try {
+    await runCommand("npm", ["install", "-g", toolConfig.packageName, "--force"]);
+    s.stop(`${toolConfig.label} 安装完成`);
+  } catch (e) {
+    s.cancel(c.red(`${toolConfig.label} 安装失败: ${e.message}`));
+    throw e;
+  }
 }
 
 async function runFullInit(options) {
+  const augmentContextEngine = options.nonInteractive
+    ? false
+    : await confirmOrCancel(getAugmentContextEnginePromptOptions());
+
   await installManagedWorkflow({
     agentsDir: options.agentsDir,
     force: options.force,
-    relinkOnly: false
+    relinkOnly: false,
+    augmentContextEngine
   });
 
-  if (await promptConfirm("是否安装或更新 Claude Code CLI？", false)) {
+  if (await confirmOrCancel({ message: "是否安装或更新 Claude Code CLI？", initialValue: false })) {
     await installCliTool("claude");
   }
-  if (await promptConfirm("是否配置 Claude Code 第三方 API？", commandExists("claude"))) {
+  if (await confirmOrCancel({ message: "是否配置 Claude Code 第三方 API？", initialValue: commandExists("claude") })) {
     await configureClaudeApi();
   }
-  if (await promptConfirm("是否安装或更新 Codex CLI？", false)) {
+  if (await confirmOrCancel({ message: "是否安装或更新 Codex CLI？", initialValue: false })) {
     await installCliTool("codex");
   }
-  if (await promptConfirm("是否配置 Codex 第三方 API？", commandExists("codex"))) {
+  if (await confirmOrCancel({ message: "是否配置 Codex 第三方 API？", initialValue: commandExists("codex") })) {
     await configureCodexApi();
   }
-  if (await promptConfirm("是否填写 grok-search 环境变量？", true)) {
+  if (await confirmOrCancel({ message: "是否填写 grok-search 环境变量？", initialValue: false })) {
     await configureGrokSearchEnv(options.agentsDir);
   }
-  if (await promptConfirm("是否填写 context7-auto-research 环境变量？", true)) {
+  if (await confirmOrCancel({ message: "是否填写 context7-auto-research 环境变量？", initialValue: false })) {
     await configureContext7Env(options.agentsDir);
   }
-  if (await promptConfirm("是否填写 prompt-enhancer 环境变量？", true)) {
+  if (await confirmOrCancel({ message: "是否填写 prompt-enhancer 环境变量？", initialValue: false })) {
     await configurePromptEnhancerEnv(options.agentsDir);
   }
 
-  console.log("\nAbelWorkflow 完整初始化完成。");
+  p.log.success(c.green("AbelWorkflow 完整初始化完成"));
 }
 
 async function runInteractiveMenu(options) {
-  console.log("AbelWorkflow Setup");
-  console.log(`工作流目录: ${pathToLabel(options.agentsDir)}`);
+  p.intro(c.bold(c.bgCyan(c.black(" AbelWorkflow Setup "))));
+  p.log.message(`工作流目录: ${c.cyan(pathToLabel(options.agentsDir))}`);
 
-  const menuChoices = interactiveMenuDescriptors.map(({ value, label }) => ({ value, label }));
   const menuActions = {
     "full-init": async () => runFullInit(options),
     install: async () => installManagedWorkflow({
@@ -1892,14 +2053,63 @@ async function runInteractiveMenu(options) {
     "codex-api": async () => configureCodexApi()
   };
 
+  const buildOption = (d) => {
+    const opt = { value: d.value, label: d.label };
+    if (d.hint) {
+      opt.hint = d.hint;
+    }
+    return opt;
+  };
+
   while (true) {
-    const choice = await promptSelect("请选择操作", menuChoices, { defaultValue: interactiveMenuDefaultValue });
-    const descriptor = interactiveMenuDescriptors.find((item) => item.value === choice);
-    if (descriptor?.value === "exit") {
+    const selectOptions = [
+      ...interactiveMenuDescriptors
+        .filter((d) => d.group === "main")
+        .map(buildOption),
+      { value: "__sep_skills__", label: "─── 技能配置 ───", disabled: true },
+      ...interactiveMenuDescriptors
+        .filter((d) => d.group === "skill")
+        .map(buildOption),
+      { value: "__sep_cli__", label: "─── CLI 工具 ───", disabled: true },
+      ...interactiveMenuDescriptors
+        .filter((d) => d.group === "cli")
+        .map(buildOption),
+      { value: "__sep_exit__", label: "────────────────", disabled: true },
+      ...interactiveMenuDescriptors
+        .filter((d) => d.group === "exit")
+        .map(buildOption)
+    ];
+
+    const choice = await p.select({
+      message: "请选择操作",
+      options: selectOptions,
+      initialValue: interactiveMenuDefaultValue
+    });
+
+    if (p.isCancel(choice)) {
+      p.outro(c.gray("已退出"));
+      return;
+    }
+    if (choice === "exit") {
+      p.outro(c.gray("已退出"));
       return;
     }
 
-    await menuActions[descriptor.value]();
+    const action = menuActions[choice];
+    if (!action) {
+      p.log.warn(`未知菜单选项: ${choice}`);
+      continue;
+    }
+
+    try {
+      await action();
+    } catch (error) {
+      if (error instanceof CancelledError) {
+        p.log.warn("操作已取消，返回菜单");
+        continue;
+      }
+      throw error;
+    }
   }
 }
 
@@ -1914,26 +2124,62 @@ async function main() {
     return;
   }
 
+  // 非交互模式下菜单命令自动回退为 install
+  if (options.command === "menu" && options.nonInteractive) {
+    console.log("检测到非交互模式，自动执行工作流安装...");
+    options.command = "install";
+  }
+
   if (options.command === "install") {
-    await installManagedWorkflow(options);
+    try {
+      await installManagedWorkflow(options);
+    } catch (error) {
+      const message = `操作失败: ${error.message || String(error)}`;
+      // 非交互模式输出纯文本便于日志捕获/管道处理；交互模式使用 clack 格式化输出
+      if (options.nonInteractive) {
+        console.error(message);
+      } else {
+        p.outro(c.red(message));
+      }
+      process.exit(1);
+    }
     return;
   }
 
   assertInteractiveMenuSupported({
     command: options.command,
     inputIsTTY: input.isTTY,
-    outputIsTTY: output.isTTY
+    outputIsTTY: output.isTTY,
+    nonInteractive: options.nonInteractive
   });
 
-  await runInteractiveMenu(options);
+  try {
+    await runInteractiveMenu(options);
+  } catch (error) {
+    const message = `操作失败: ${error.message || String(error)}`;
+    // 非交互模式输出纯文本便于日志捕获/管道处理；交互模式使用 clack 格式化输出
+    if (options.nonInteractive) {
+      console.error(message);
+    } else {
+      p.outro(c.red(message));
+    }
+    process.exit(1);
+  }
 }
 
 export {
+  applyClaudePermissionFeature,
+  buildDefaultClaudeSettings,
   buildCodexConfigContent,
+  getAugmentContextEnginePromptOptions,
   getRunCommandSpawnOptions,
+  hasPromptEnhancerApiConfig,
   main,
   mergeCodexAuthData,
   mergeClaudeSettingsWithDefaults,
+  renderManagedWorkflowContent,
+  resolveAugmentContextEngineFeature,
+  resolvePromptEnhancerMode,
   resolveExistingCodexApiConfig,
   updateTomlSectionFields
 };