尧图网页设计 
claude-mem 动画式安装器设计与实现基于 clack/prompts 的交互式 CLI 安装向导【免费下载链接】claude-memPersistent Context Across Sessions for Every Agent – Captures everything your agent does during sessions, compresses it with AI, and injects relevant context back into future sessions. Works with Claude Code, OpenClaw, Codex, Gemini, Hermes, Copilot, OpenCode More项目地址: https://gitcode.com/GitHub_Trending/cl/claude-memclaude-mem 的核心使用门槛在于用户需要手动克隆仓库、构建插件、配置settings.json、再单独启动 worker 服务。animated-installer 计划文档给出了一套完整方案用clack/prompts构建一个带动画效果的 CLI 安装向导通过npx与curl | bash两种分发方式一键完成全部流程。本文以该计划文档为主线逐阶段还原其 API 选型、工程结构与验证标准并对照仓库中已落地的 npx CLI 实现 与 运行时准备逻辑讲解这套安装器从设计到源码的实际形态。读完本文你可以掌握交互式 CLI 安装器的 API 用法边界、TTY 防护、依赖自检与 worker 健康检查等关键工程实践。一、计划目标与两种分发形态计划文档的 Overview 明确了两条分发路径npx 分发npx claude-mem-installer计划阶段的包名仓库最终实现为npx claude-mem installpackage.json的bin字段指向带 shebang 的dist/index.jscurl | bash 分发Shell 引导脚本下载打包后的安装器 JS直接用node script.js执行——关键是保留 TTY因为clack/prompts的交互式提示在管道输入下会无限挂起。安装器的价值在于替代四个手动环节clone 仓库、构建插件、配置设置、启动 worker。文档同时注明设计工作在独立 worktreefeat/animated-installer中推进主仓库只保留规划与最终实现。二、Phase 0clack/prompts API 选型与反模式清单计划文档把 API 选型作为 Phase 0列出了 v1.0.1ESM-only下允许使用的 API 及其用途这是理解后续每个步骤实现的基础API签名用途intro(title?)void开场横幅outro(message?)void完成消息cancel(message?)void用户取消isCancel(value)boolean判断用户是否按了 CtrlCtext(opts)Promisestring \| symbol输入 API key、端口、数据目录password(opts)Promisestring \| symbol遮罩输入 API keyselect(opts)PromiseValue \| symbol选择 Provider、模型、认证方式multiselect(opts)PromiseValue[] \| symbol多选 IDE、观测类型confirm(opts)Promiseboolean \| symbol启用 Chroma、启动 workerspinner()SpinnerResult安装依赖、构建、启动 worker 的动画progress(opts)ProgressResult多步骤安装进度tasks(tasks[])Promisevoid顺序执行安装步骤group(prompts, opts)PromiseResults链式提示并共享结果note(message, title)void显示配置摘要、下一步log.info/success/warn/error(msg)void状态消息box(message, title, opts)void欢迎框、完成摘要框反模式清单Anti-Patterns计划文档特别列出六条必须规避的写法每一条都对应一类真实的运行故障不要使用require()——clack/prompts是 ESM-only不要未做 TTY 检查就调用提示——非 TTY 环境下会无限挂起每个 prompt 之后都要检查isCancel()或使用带onCancel的group()不要引入chalk——统一用 clack 的依赖picocolors保证颜色输出一致text()没有数字模式——端口号必须手工做数值校验spinner.stop()不接受状态码——失败场景要用spinner.error()。分发包的技术模式npxbin字段指向./dist/index.js产物首行需要#!/usr/bin/env nodecurl | bash引导脚本直接node script.js不经 shell 中转保住 TTYesbuild打包成单文件 ESMplatform: node用banner注入 shebang。文档还给出了实现时应参考的 8 个关键源文件SettingsDefaultsManager默认设置 schema、SettingsRoutes.ts设置校验、worker-service.tsworker 启动、HealthMonitor健康检查、plugin.json 与 marketplace.json插件注册、sync-marketplace.cjsmarketplace 同步、CursorHooksInstallerCursor 集成、openclaw.sh既有安装脚本的逻辑参考。三、Phase 1包结构、构建配置与验证标准计划给出的目录结构按「步骤」与「工具」分层installer/ ├── src/ │ ├── index.ts # 入口含 TTY 防护 │ ├── steps/ │ │ ├── welcome.ts # intro 版本检查 │ │ ├── dependencies.ts # bun、uv、git 检查 │ │ ├── ide-selection.ts # IDE 选择 注册 │ │ ├── provider.ts # AI 供应商 API key │ │ ├── settings.ts # 附加设置 │ │ ├── install.ts # 克隆、构建、注册插件 │ │ ├── worker.ts # 启动 worker 健康检查 │ │ └── complete.ts # 摘要 下一步 │ └── utils/ │ ├── system.ts # OS 检测、命令执行 │ ├── dependencies.ts # bun/uv 安装辅助 │ └── settings-writer.ts # 写 ~/.claude-mem/settings.json ├── build.mjs # esbuild 配置 ├── package.json # bin、type: module、依赖 └── tsconfig.jsonpackage.json的关键字段是type: module、bin指向dist/index.js、engines.node 18build.mjs使用 esbuild 以format: esm、platform: node、target: node18打包banner 注入 shebangtsconfig.json采用module: ESNext、target: ES2022、moduleResolution: bundler。验证标准三条node build.mjs成功、产物带 shebang、空安装器也能运行。仓库最终实现把这套结构落到了主包里package.json的bin为claude-mem: ./dist/npx-cli/index.js运行时要求升级为node: 20.12.0、bun: 1.0.0见 package.json。值得注意的是 dependencies-note 的说明clack/prompts等库被 esbuild内联进 npx 包属于构建期 devDependency不会被消费该包的用户额外下载——这正是计划中「单文件 ESM 产物」模式的规模化版本当前 package.json 中该依赖为^1.3.0。四、Phase 2入口 TTY 防护与欢迎步骤计划中src/index.ts的三个要点TTY 防护!process.stdin.isTTY时打印错误并引导用户改用npx claude-mem-installerexit 1导入并调用steps中的runInstaller()顶层 catch 统一走p.cancel()并退出。welcome.ts负责p.intro()用 picocolors 加样式的标题、版本号展示、已安装检测探测~/.claude-mem/settings.json与~/.claude/plugins/marketplaces/thedotmack/、升级确认以及 Fresh Install / Upgrade / Configure Only 三选一。system.ts提供四个基础工具detectOS()、commandExists()、runCommand()返回 stdout/stderr/exitCode、expandHome()。仓库最终实现中这一设计以 install.ts 的开头几行得到印证——交互性是全局一次性判定的而非逐提示判断const isInteractive process.stdin.isTTY true; // src/npx-cli/commands/install.ts#L58 async function runTasks(tasks: TaskDescriptor[]): Promisevoid { if (isInteractive) { await p.tasks(tasks); } else { for (const t of tasks) { const result await t.task((msg: string) console.log( ${msg})); console.log( ${result}); } } }这里比计划更进一步非 TTY 不是简单报错退出而是降级为纯文本顺序执行——p.tasks换成逐条console.log让 CI / 脚本环境也能跑通安装。而isCancel检查则严格遵循了 Phase 0 反模式清单install.ts 中几乎每个 prompt 之后都有成对的模式如 L294-L295、L946-L947if (p.isCancel(choice)) { p.cancel(Installation cancelled.);欢迎横幅的样式实现位于 L1966p.intro(styleText([bgCyan, black], claude-mem install ))——最终版用 Node 内置styleText替代了计划中的 picocolors效果等价且零依赖。五、Phase 3依赖检查与自动安装计划要求用p.tasks()依次以动画 spinner 检查四类依赖Node.jsprocess.version校验 18.0.0gitcommandExists(git)缺失时按 OS 给出安装指引不能自动装则优雅失败Bun查 PATH 与常见位置~/.bun/bin/bun、/usr/local/bin/bun、/opt/homebrew/bin/bun最低 1.1.14确认后从官方脚本自动安装uv查 PATH 与~/.local/bin/uv、~/.cargo/bin/uv确认后自动安装。安装尝试之后必须重新验证一遍。验证标准覆盖四种终态找到的依赖显示绿色对勾、缺失的显示黄色警告并提供安装选项、确认后真的完成安装、git 缺失时优雅失败。这部分在 setup-runtime.ts 中有完整且更精细的落地。二进制搜索逻辑与计划完全一致——先探测 PATH再回退到常见安装位置const BUN_COMMON_PATHS IS_WINDOWS ? [join(homedir(), .bun, bin, bun.exe)] : [join(homedir(), .bun, bin, bun), /usr/local/bin/bun, /opt/homebrew/bin/bun, ...]; const UV_COMMON_PATHS IS_WINDOWS ? [join(homedir(), .local, bin, uv.exe), join(homedir(), .cargo, bin, uv.exe)] : [join(homedir(), .local, bin, uv), join(homedir(), .cargo, bin, uv), /usr/local/bin/uv, /opt/homebrew/bin/uv];自动安装失败时的补救信息被做成平台感知的一等公民Windows 下提示winget install Oven-sh.Bun/winget install astral-sh.uv类 Unix 下提示curl -fsSL https://bun.sh/install | bash或 Homebrew 等价命令见 setup-runtime.ts 中platformBunRemediation()/platformUvRemediation()。另一个工程化细节是安装超时可用环境变量覆盖默认 5 分钟const INSTALL_TIMEOUT_MS (() { const override process.env.CLAUDE_MEM_INSTALL_TIMEOUT_MS; if (override Number.isFinite(Number(override))) return Number(override); return 5 * 60 * 1000; })();六、Phase 4IDE 多选与 Provider 配置IDE 选择用p.multiselect()Claude Code默认选中hint 为 recommended、Cursor、Windsurfhint coming soondisabled: true。选中 Claude Code 时提示插件将通过 marketplace 注册选中 Cursor 时提示 hooks 将按 CursorHooksInstaller 的模式安装。Provider 配置用p.select()三选一每个分支的追问结构是计划的精华Claudehint使用 Claude 订阅再选认证方式——CLIMax Plan 订阅 vs API KeyAPI Key 走p.password()遮罩输入Geminihint有免费额度p.password()必填 keyp.select()选模型默认 gemini-2.5-flash-lite另有 gemini-2.5-flash、gemini-3-flash-previewp.confirm()确认限流默认 trueOpenRouterhint有免费模型p.password()必填 keyp.text()填模型默认xiaomi/mimo-v2-flash:free。所有 key 尽量做非空与格式校验。验证标准四条多选可用、各分支追问正确、key 全程遮罩、任意步骤可取消且优雅退出。仓库的 index.ts 把这一交互层同时翻译成了非交互命令行参数这是计划文档没有展开、但生产环境必需的能力npx claude-mem install --provider claude|gemini|openrouter|host # 非交互指定供应商 npx claude-mem install --model id # providerclaude 时指定模型 npx claude-mem install --no-auto-start # 跳过结束时的 worker 自启动 npx claude-mem install --runtime worker|server # 非交互选择运行时参数解析用parseArgsstrict: false并对--provider/--runtime做白名单校验非法值直接报错退出index.ts L66-L114。还有一个关键的非交互默认值逻辑当stdin.isTTY ! true且未显式传 provider 时调用resolveInstallerProviderChoice({ ide })为特定 IDE 推导隐式 providerL99-L104——这正对应 Phase 0 反模式「不要未做 TTY 检查就调用提示」的彻底贯彻非 TTY 下根本不会弹出任何 prompt。七、Phase 5设置向导与 Schema 对齐的设置写入设置步骤的策略是「默认优先」先用p.confirm()问 Use default settings?推荐选 yes 直接跳过明细选自定义则用p.group()组织六个配置项其中数值项都要手工校验——这正是反模式清单第 5 条text()无数字模式的应对Worker 端口默认 37777校验 1024-65535数据目录默认~/.claude-memContext 观测数默认 50校验 1-200日志级别DEBUG / INFO默认/ WARN / ERRORPython 版本默认 3.13Chroma 向量检索默认 true若启用再选 local默认/ remoteremote 时追问 host、port 与 SSL。进入下一步前用p.note()展示设置摘要。设置写入器settings-writer.ts的要求是构建与 SettingsDefaultsManager schema 完全一致的扁平键值对象、升级时与既有设置合并保留用户自定义、写入~/.claude-mem/settings.json、目录不存在则创建。验证标准包括默认模式跳过全部明细提示、自定义模式全量校验、产物与 schema 精确匹配、升级保留既有设置。八、Phase 6安装执行、插件注册与两阶段健康检查install.ts计划阶段的步骤文件用p.tasks()呈现四个视觉化步骤克隆仓库到临时目录--depth 1、npm install、npm run build、注册插件。插件注册是四个落点拷贝插件文件到~/.claude/plugins/marketplaces/thedotmack/并建立 marketplace.json / plugin.json 结构、更新known_marketplaces.json、更新installed_plugins.json、在~/.claude/settings.json的enabledPlugins下启用。若用户勾选了 Cursor还要额外执行 hooks 安装逻辑写hooks.json到~/.cursor/或项目级.cursor/并在.cursor/mcp.json配置 MCP。worker.ts的步骤用p.spinner()呈现并采用两阶段健康检查计划注明该模式参考 OpenClaw 安装脚本启动 workerbun plugin/scripts/worker-service.cjsPID 写入~/.claude-mem/worker.pidStage 1轮询/api/healthspinner 文案 Starting worker service...Stage 2轮询/api/readinessspinner 文案 Initializing database...预算30 次尝试、间隔 1 秒成功spinner.stop(Worker running on port {port})失败spinner.error(Worker failed to start)并展示日志路径。验证清单要求四个注册文件全部更新、worker 两个端点均返回 200。仓库侧对应的健康检查能力实现在 HealthMonitorworker 启动路径见 worker-service.ts。九、Phase 7 与 Phase 8完成摘要与 curl | bash 引导完成页用两段p.note()第一段是配置摘要Provider 模型、已配置 IDE、数据目录、worker 端口、Chroma 开关第二段是下一步指引——打开 Claude Code 即可自动记忆、http://localhost:{port}查看记忆、用/mem-search搜索历史工作、若装了 Cursor 则 hooks 已生效——最后p.outro()收尾。验证要点摘要与所选设置一致、URL 端口正确、下一步与已选 IDE 相关。curl | bash 引导脚本计划阶段的install/public/install.sh要求检查 Node 18、把打包好的安装器 JS 下载到临时文件、直接node执行以保留 TTY、用trap在成功和失败两种路径下都清理临时文件、透传--non-interactive与--providerX --api-keyY。配套要求 install/vercel.json 把install.sh作为站点根路径服务出去。这里值得对照仓库现状说明一次设计演进当前 install.sh 已经不再是引导脚本而是一个明确的迁移提示——echo -e ${YELLOW}The curl-pipe-bash installer has been replaced.${NC} echo ${CYAN}npx claude-mem install${NC} echo This requires Node.js 20. ...也就是说计划中 Phase 8 的 curl | bash 方案在演进中被npx claude-mem install取代Node 门槛同步从 18 提到 20而 vercel.json 的 rewrite 规则/→/install.sh.sh以text/plain服务并带短缓存头保留了下来用于继续承接旧安装命令的用户。这是「计划文档描述设计意图、仓库现状描述演进结果」的典型对照。十、Phase 9最终验证清单可直接复用的验收模板计划把验收标准压缩成 12 条可勾选的检查项这套清单本身就值得作为任何 CLI 安装器的模板npm run build产出单文件dist/index.jsnode dist/index.js可完整跑通向导流程干净系统全新安装端到端成功升级路径保留既有设置任意步骤 CtrlC 干净退出非 TTY 显示错误消息最终实现中进一步演进为非交互降级模式写入的所有设置与 SettingsDefaultsManager.ts 的默认 schema 一致安装后 worker 健康检查成功插件出现在 Claude Code 插件列表中grep弃用/不存在的 API 结果为 0源码中无require()调用ESM-only无chalk导入统一 picocolors / 内置 styleText。小结animated-installer.md 的价值不仅在于描述了一个安装器更在于它示范了「计划文档如何与源码对齐」Phase 0 的 API 表与反模式清单约束了全部代码形态ESM-only、TTY 检查、isCancel成对出现Phase 3 的常见二进制路径与平台补救话术在 setup-runtime.ts 中原样实现Phase 4 的交互选择在 index.ts 中被扩展为非交互 CLI 参数使同一套安装逻辑同时服务人类终端与自动化环境Phase 8 的 curl | bash 则被npx claude-mem install平滑取代旧入口改为迁移提示。对照计划与实现可以推断出该仓库的 CLI 工程原则交互体验由clack/prompts承担、所有提示必须先过 TTY 判定、每个用户输入都有取消出口、设置产物必须与默认值 schema 逐字段对齐。【免费下载链接】claude-memPersistent Context Across Sessions for Every Agent – Captures everything your agent does during sessions, compresses it with AI, and injects relevant context back into future sessions. Works with Claude Code, OpenClaw, Codex, Gemini, Hermes, Copilot, OpenCode More项目地址: https://gitcode.com/GitHub_Trending/cl/claude-mem创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 claude-mem 动画式安装器设计与实现：基于 @clack/prompts 的交互式 CLI 安装向导
claude-mem 动画式安装器设计与实现基于 clack/prompts 的交互式 CLI 安装向导【免费下载链接】claude-memPersistent Context Across Sessions for Every Agent – Captures everything your agent does during sessions, compresses it with AI, and injects relevant context back into future sessions. Works with Claude Code, OpenClaw, Codex, Gemini, Hermes, Copilot, OpenCode More项目地址: https://gitcode.com/GitHub_Trending/cl/claude-memclaude-mem 的核心使用门槛在于用户需要手动克隆仓库、构建插件、配置settings.json、再单独启动 worker 服务。animated-installer 计划文档给出了一套完整方案用clack/prompts构建一个带动画效果的 CLI 安装向导通过npx与curl | bash两种分发方式一键完成全部流程。本文以该计划文档为主线逐阶段还原其 API 选型、工程结构与验证标准并对照仓库中已落地的 npx CLI 实现 与 运行时准备逻辑讲解这套安装器从设计到源码的实际形态。读完本文你可以掌握交互式 CLI 安装器的 API 用法边界、TTY 防护、依赖自检与 worker 健康检查等关键工程实践。一、计划目标与两种分发形态计划文档的 Overview 明确了两条分发路径npx 分发npx claude-mem-installer计划阶段的包名仓库最终实现为npx claude-mem installpackage.json的bin字段指向带 shebang 的dist/index.jscurl | bash 分发Shell 引导脚本下载打包后的安装器 JS直接用node script.js执行——关键是保留 TTY因为clack/prompts的交互式提示在管道输入下会无限挂起。安装器的价值在于替代四个手动环节clone 仓库、构建插件、配置设置、启动 worker。文档同时注明设计工作在独立 worktreefeat/animated-installer中推进主仓库只保留规划与最终实现。二、Phase 0clack/prompts API 选型与反模式清单计划文档把 API 选型作为 Phase 0列出了 v1.0.1ESM-only下允许使用的 API 及其用途这是理解后续每个步骤实现的基础API签名用途intro(title?)void开场横幅outro(message?)void完成消息cancel(message?)void用户取消isCancel(value)boolean判断用户是否按了 CtrlCtext(opts)Promisestring \| symbol输入 API key、端口、数据目录password(opts)Promisestring \| symbol遮罩输入 API keyselect(opts)PromiseValue \| symbol选择 Provider、模型、认证方式multiselect(opts)PromiseValue[] \| symbol多选 IDE、观测类型confirm(opts)Promiseboolean \| symbol启用 Chroma、启动 workerspinner()SpinnerResult安装依赖、构建、启动 worker 的动画progress(opts)ProgressResult多步骤安装进度tasks(tasks[])Promisevoid顺序执行安装步骤group(prompts, opts)PromiseResults链式提示并共享结果note(message, title)void显示配置摘要、下一步log.info/success/warn/error(msg)void状态消息box(message, title, opts)void欢迎框、完成摘要框反模式清单Anti-Patterns计划文档特别列出六条必须规避的写法每一条都对应一类真实的运行故障不要使用require()——clack/prompts是 ESM-only不要未做 TTY 检查就调用提示——非 TTY 环境下会无限挂起每个 prompt 之后都要检查isCancel()或使用带onCancel的group()不要引入chalk——统一用 clack 的依赖picocolors保证颜色输出一致text()没有数字模式——端口号必须手工做数值校验spinner.stop()不接受状态码——失败场景要用spinner.error()。分发包的技术模式npxbin字段指向./dist/index.js产物首行需要#!/usr/bin/env nodecurl | bash引导脚本直接node script.js不经 shell 中转保住 TTYesbuild打包成单文件 ESMplatform: node用banner注入 shebang。文档还给出了实现时应参考的 8 个关键源文件SettingsDefaultsManager默认设置 schema、SettingsRoutes.ts设置校验、worker-service.tsworker 启动、HealthMonitor健康检查、plugin.json 与 marketplace.json插件注册、sync-marketplace.cjsmarketplace 同步、CursorHooksInstallerCursor 集成、openclaw.sh既有安装脚本的逻辑参考。三、Phase 1包结构、构建配置与验证标准计划给出的目录结构按「步骤」与「工具」分层installer/ ├── src/ │ ├── index.ts # 入口含 TTY 防护 │ ├── steps/ │ │ ├── welcome.ts # intro 版本检查 │ │ ├── dependencies.ts # bun、uv、git 检查 │ │ ├── ide-selection.ts # IDE 选择 注册 │ │ ├── provider.ts # AI 供应商 API key │ │ ├── settings.ts # 附加设置 │ │ ├── install.ts # 克隆、构建、注册插件 │ │ ├── worker.ts # 启动 worker 健康检查 │ │ └── complete.ts # 摘要 下一步 │ └── utils/ │ ├── system.ts # OS 检测、命令执行 │ ├── dependencies.ts # bun/uv 安装辅助 │ └── settings-writer.ts # 写 ~/.claude-mem/settings.json ├── build.mjs # esbuild 配置 ├── package.json # bin、type: module、依赖 └── tsconfig.jsonpackage.json的关键字段是type: module、bin指向dist/index.js、engines.node 18build.mjs使用 esbuild 以format: esm、platform: node、target: node18打包banner 注入 shebangtsconfig.json采用module: ESNext、target: ES2022、moduleResolution: bundler。验证标准三条node build.mjs成功、产物带 shebang、空安装器也能运行。仓库最终实现把这套结构落到了主包里package.json的bin为claude-mem: ./dist/npx-cli/index.js运行时要求升级为node: 20.12.0、bun: 1.0.0见 package.json。值得注意的是 dependencies-note 的说明clack/prompts等库被 esbuild内联进 npx 包属于构建期 devDependency不会被消费该包的用户额外下载——这正是计划中「单文件 ESM 产物」模式的规模化版本当前 package.json 中该依赖为^1.3.0。四、Phase 2入口 TTY 防护与欢迎步骤计划中src/index.ts的三个要点TTY 防护!process.stdin.isTTY时打印错误并引导用户改用npx claude-mem-installerexit 1导入并调用steps中的runInstaller()顶层 catch 统一走p.cancel()并退出。welcome.ts负责p.intro()用 picocolors 加样式的标题、版本号展示、已安装检测探测~/.claude-mem/settings.json与~/.claude/plugins/marketplaces/thedotmack/、升级确认以及 Fresh Install / Upgrade / Configure Only 三选一。system.ts提供四个基础工具detectOS()、commandExists()、runCommand()返回 stdout/stderr/exitCode、expandHome()。仓库最终实现中这一设计以 install.ts 的开头几行得到印证——交互性是全局一次性判定的而非逐提示判断const isInteractive process.stdin.isTTY true; // src/npx-cli/commands/install.ts#L58 async function runTasks(tasks: TaskDescriptor[]): Promisevoid { if (isInteractive) { await p.tasks(tasks); } else { for (const t of tasks) { const result await t.task((msg: string) console.log( ${msg})); console.log( ${result}); } } }这里比计划更进一步非 TTY 不是简单报错退出而是降级为纯文本顺序执行——p.tasks换成逐条console.log让 CI / 脚本环境也能跑通安装。而isCancel检查则严格遵循了 Phase 0 反模式清单install.ts 中几乎每个 prompt 之后都有成对的模式如 L294-L295、L946-L947if (p.isCancel(choice)) { p.cancel(Installation cancelled.);欢迎横幅的样式实现位于 L1966p.intro(styleText([bgCyan, black], claude-mem install ))——最终版用 Node 内置styleText替代了计划中的 picocolors效果等价且零依赖。五、Phase 3依赖检查与自动安装计划要求用p.tasks()依次以动画 spinner 检查四类依赖Node.jsprocess.version校验 18.0.0gitcommandExists(git)缺失时按 OS 给出安装指引不能自动装则优雅失败Bun查 PATH 与常见位置~/.bun/bin/bun、/usr/local/bin/bun、/opt/homebrew/bin/bun最低 1.1.14确认后从官方脚本自动安装uv查 PATH 与~/.local/bin/uv、~/.cargo/bin/uv确认后自动安装。安装尝试之后必须重新验证一遍。验证标准覆盖四种终态找到的依赖显示绿色对勾、缺失的显示黄色警告并提供安装选项、确认后真的完成安装、git 缺失时优雅失败。这部分在 setup-runtime.ts 中有完整且更精细的落地。二进制搜索逻辑与计划完全一致——先探测 PATH再回退到常见安装位置const BUN_COMMON_PATHS IS_WINDOWS ? [join(homedir(), .bun, bin, bun.exe)] : [join(homedir(), .bun, bin, bun), /usr/local/bin/bun, /opt/homebrew/bin/bun, ...]; const UV_COMMON_PATHS IS_WINDOWS ? [join(homedir(), .local, bin, uv.exe), join(homedir(), .cargo, bin, uv.exe)] : [join(homedir(), .local, bin, uv), join(homedir(), .cargo, bin, uv), /usr/local/bin/uv, /opt/homebrew/bin/uv];自动安装失败时的补救信息被做成平台感知的一等公民Windows 下提示winget install Oven-sh.Bun/winget install astral-sh.uv类 Unix 下提示curl -fsSL https://bun.sh/install | bash或 Homebrew 等价命令见 setup-runtime.ts 中platformBunRemediation()/platformUvRemediation()。另一个工程化细节是安装超时可用环境变量覆盖默认 5 分钟const INSTALL_TIMEOUT_MS (() { const override process.env.CLAUDE_MEM_INSTALL_TIMEOUT_MS; if (override Number.isFinite(Number(override))) return Number(override); return 5 * 60 * 1000; })();六、Phase 4IDE 多选与 Provider 配置IDE 选择用p.multiselect()Claude Code默认选中hint 为 recommended、Cursor、Windsurfhint coming soondisabled: true。选中 Claude Code 时提示插件将通过 marketplace 注册选中 Cursor 时提示 hooks 将按 CursorHooksInstaller 的模式安装。Provider 配置用p.select()三选一每个分支的追问结构是计划的精华Claudehint使用 Claude 订阅再选认证方式——CLIMax Plan 订阅 vs API KeyAPI Key 走p.password()遮罩输入Geminihint有免费额度p.password()必填 keyp.select()选模型默认 gemini-2.5-flash-lite另有 gemini-2.5-flash、gemini-3-flash-previewp.confirm()确认限流默认 trueOpenRouterhint有免费模型p.password()必填 keyp.text()填模型默认xiaomi/mimo-v2-flash:free。所有 key 尽量做非空与格式校验。验证标准四条多选可用、各分支追问正确、key 全程遮罩、任意步骤可取消且优雅退出。仓库的 index.ts 把这一交互层同时翻译成了非交互命令行参数这是计划文档没有展开、但生产环境必需的能力npx claude-mem install --provider claude|gemini|openrouter|host # 非交互指定供应商 npx claude-mem install --model id # providerclaude 时指定模型 npx claude-mem install --no-auto-start # 跳过结束时的 worker 自启动 npx claude-mem install --runtime worker|server # 非交互选择运行时参数解析用parseArgsstrict: false并对--provider/--runtime做白名单校验非法值直接报错退出index.ts L66-L114。还有一个关键的非交互默认值逻辑当stdin.isTTY ! true且未显式传 provider 时调用resolveInstallerProviderChoice({ ide })为特定 IDE 推导隐式 providerL99-L104——这正对应 Phase 0 反模式「不要未做 TTY 检查就调用提示」的彻底贯彻非 TTY 下根本不会弹出任何 prompt。七、Phase 5设置向导与 Schema 对齐的设置写入设置步骤的策略是「默认优先」先用p.confirm()问 Use default settings?推荐选 yes 直接跳过明细选自定义则用p.group()组织六个配置项其中数值项都要手工校验——这正是反模式清单第 5 条text()无数字模式的应对Worker 端口默认 37777校验 1024-65535数据目录默认~/.claude-memContext 观测数默认 50校验 1-200日志级别DEBUG / INFO默认/ WARN / ERRORPython 版本默认 3.13Chroma 向量检索默认 true若启用再选 local默认/ remoteremote 时追问 host、port 与 SSL。进入下一步前用p.note()展示设置摘要。设置写入器settings-writer.ts的要求是构建与 SettingsDefaultsManager schema 完全一致的扁平键值对象、升级时与既有设置合并保留用户自定义、写入~/.claude-mem/settings.json、目录不存在则创建。验证标准包括默认模式跳过全部明细提示、自定义模式全量校验、产物与 schema 精确匹配、升级保留既有设置。八、Phase 6安装执行、插件注册与两阶段健康检查install.ts计划阶段的步骤文件用p.tasks()呈现四个视觉化步骤克隆仓库到临时目录--depth 1、npm install、npm run build、注册插件。插件注册是四个落点拷贝插件文件到~/.claude/plugins/marketplaces/thedotmack/并建立 marketplace.json / plugin.json 结构、更新known_marketplaces.json、更新installed_plugins.json、在~/.claude/settings.json的enabledPlugins下启用。若用户勾选了 Cursor还要额外执行 hooks 安装逻辑写hooks.json到~/.cursor/或项目级.cursor/并在.cursor/mcp.json配置 MCP。worker.ts的步骤用p.spinner()呈现并采用两阶段健康检查计划注明该模式参考 OpenClaw 安装脚本启动 workerbun plugin/scripts/worker-service.cjsPID 写入~/.claude-mem/worker.pidStage 1轮询/api/healthspinner 文案 Starting worker service...Stage 2轮询/api/readinessspinner 文案 Initializing database...预算30 次尝试、间隔 1 秒成功spinner.stop(Worker running on port {port})失败spinner.error(Worker failed to start)并展示日志路径。验证清单要求四个注册文件全部更新、worker 两个端点均返回 200。仓库侧对应的健康检查能力实现在 HealthMonitorworker 启动路径见 worker-service.ts。九、Phase 7 与 Phase 8完成摘要与 curl | bash 引导完成页用两段p.note()第一段是配置摘要Provider 模型、已配置 IDE、数据目录、worker 端口、Chroma 开关第二段是下一步指引——打开 Claude Code 即可自动记忆、http://localhost:{port}查看记忆、用/mem-search搜索历史工作、若装了 Cursor 则 hooks 已生效——最后p.outro()收尾。验证要点摘要与所选设置一致、URL 端口正确、下一步与已选 IDE 相关。curl | bash 引导脚本计划阶段的install/public/install.sh要求检查 Node 18、把打包好的安装器 JS 下载到临时文件、直接node执行以保留 TTY、用trap在成功和失败两种路径下都清理临时文件、透传--non-interactive与--providerX --api-keyY。配套要求 install/vercel.json 把install.sh作为站点根路径服务出去。这里值得对照仓库现状说明一次设计演进当前 install.sh 已经不再是引导脚本而是一个明确的迁移提示——echo -e ${YELLOW}The curl-pipe-bash installer has been replaced.${NC} echo ${CYAN}npx claude-mem install${NC} echo This requires Node.js 20. ...也就是说计划中 Phase 8 的 curl | bash 方案在演进中被npx claude-mem install取代Node 门槛同步从 18 提到 20而 vercel.json 的 rewrite 规则/→/install.sh.sh以text/plain服务并带短缓存头保留了下来用于继续承接旧安装命令的用户。这是「计划文档描述设计意图、仓库现状描述演进结果」的典型对照。十、Phase 9最终验证清单可直接复用的验收模板计划把验收标准压缩成 12 条可勾选的检查项这套清单本身就值得作为任何 CLI 安装器的模板npm run build产出单文件dist/index.jsnode dist/index.js可完整跑通向导流程干净系统全新安装端到端成功升级路径保留既有设置任意步骤 CtrlC 干净退出非 TTY 显示错误消息最终实现中进一步演进为非交互降级模式写入的所有设置与 SettingsDefaultsManager.ts 的默认 schema 一致安装后 worker 健康检查成功插件出现在 Claude Code 插件列表中grep弃用/不存在的 API 结果为 0源码中无require()调用ESM-only无chalk导入统一 picocolors / 内置 styleText。小结animated-installer.md 的价值不仅在于描述了一个安装器更在于它示范了「计划文档如何与源码对齐」Phase 0 的 API 表与反模式清单约束了全部代码形态ESM-only、TTY 检查、isCancel成对出现Phase 3 的常见二进制路径与平台补救话术在 setup-runtime.ts 中原样实现Phase 4 的交互选择在 index.ts 中被扩展为非交互 CLI 参数使同一套安装逻辑同时服务人类终端与自动化环境Phase 8 的 curl | bash 则被npx claude-mem install平滑取代旧入口改为迁移提示。对照计划与实现可以推断出该仓库的 CLI 工程原则交互体验由clack/prompts承担、所有提示必须先过 TTY 判定、每个用户输入都有取消出口、设置产物必须与默认值 schema 逐字段对齐。【免费下载链接】claude-memPersistent Context Across Sessions for Every Agent – Captures everything your agent does during sessions, compresses it with AI, and injects relevant context back into future sessions. Works with Claude Code, OpenClaw, Codex, Gemini, Hermes, Copilot, OpenCode More项目地址: https://gitcode.com/GitHub_Trending/cl/claude-mem创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考