Claude Code CLI源码深度解析：从命令执行到流式响应

1. 这不是“另一个AI CLI工具”：Claude Code 的真实定位与能力边界

“三分钟上手 Claude Code 源码全面拆解和分析”——这个标题里藏着两个极易被忽略的关键词：“源码”和“全面拆解”。它不是教你点几下鼠标安装一个黑盒应用，也不是让你复制粘贴几行命令就宣称“已掌握”。它指向的是一个更底层、更务实的问题：当我们在终端里敲下zread_cli --help或npx claude-code --file main.py的时候，背后到底发生了什么？那个被热词反复刷屏的zread命令，究竟是一个独立可执行文件，还是一个 Node.js 脚本包装器？它的输入如何被解析，上下文如何被切片，提示词模板如何被注入，响应流又如何被实时渲染到控制台？这些问题的答案，不在任何官方文档的“快速开始”章节里，而藏在 GitHub 仓库的src/目录深处。

我第一次看到zread_cli这个名字时，本能地以为它是用 Rust 或 Go 写的原生二进制——毕竟名字里带_cli，又常和playwright cli、trae cli这类高性能工具并列出现在热搜里。但当我真正git clone下来，ls -R一扫，发现整个项目根目录下只有package.json、tsconfig.json和一个src/文件夹时，立刻意识到：这是一套典型的 TypeScript + Node.js 构建的 CLI 工具链。它的核心价值不在于“快”，而在于“可调试、可定制、可嵌入”。它不像桌面版那样封装了 Electron 渲染进程和复杂的 UI 状态管理，也不像某些闭源 SDK 那样只提供.d.ts类型定义却隐藏实现逻辑。它的源码就是它的说明书，它的bin/目录就是它的入口，它的lib/目录就是它的肌肉。

这也解释了为什么网络上充斥着大量关于npm : 无法加载文件 c:\program files\nodejs\npm.ps1的报错求助。这不是一个孤立的 Windows 权限问题，而是这个工具链天然依赖 Node.js 生态的运行时环境所必然带来的“摩擦点”。当你试图用npm install -g claude-code全局安装时，你实际上是在让 npm 去下载、解压、链接一个包含zread_cli启动脚本的 tarball，并将其符号链接到你的系统 PATH 中。而 PowerShell 的执行策略（Execution Policy）正是横亘在这条自动化路径上的第一道关卡。理解这一点，你就不会再去盲目搜索“如何永久关闭 PowerShell 执行策略”，而是会去思考：我是否真的需要全局安装？npx是否是更安全、更轻量的替代方案？如果必须全局安装，能否将zread_cli脚本手动复制到一个不受策略限制的路径下？

提示：zread并非一个独立的二进制程序，它本质上是一个由package.json中bin字段声明的、指向dist/cli.js的符号链接。它的“命令行”体验，完全由 Node.js 的process.argv解析、commander库的参数定义、以及node-fetch或undici发起的 HTTP 请求共同构建。这意味着，它的所有行为——从读取配置文件、到处理文件编码、再到流式接收 API 响应——都是可被console.log打印、被debugger断点、被jest单元测试覆盖的。

这种“透明性”是它区别于其他同类工具的核心竞争力。当你在飞书 CLI 或 Mimo CLI 的文档里看到一句模糊的“支持 AI 辅助”，你无从得知它调用的是哪个模型 endpoint、用了多大的 temperature、是否对用户输入做了敏感词过滤；但当你打开claude-code的src/commands/read.ts，你会清晰地看到const response = await fetch(CLAUDE_API_URL, { method: 'POST', headers: { 'x-api-key': apiKey }, body: JSON.stringify(payload) })这一行代码。API 地址、请求头、请求体结构，全部摊开在你面前。这不仅是“能用”，更是“可控”。对于一个需要将 AI 能力深度集成到内部研发流程的团队来说，这种可控性远比一个花哨的 UI 更有价值。

2. 从npm install到zread_cli：一次完整的 CLI 启动链路追踪

要真正“上手”，第一步不是写代码，而是搞懂命令是如何从你的键盘，最终变成屏幕上滚动的文字。我们以最典型的使用场景为例：在 Ubuntu 20.04 上，执行zread_cli --file ./src/index.ts --language typescript。这条命令的生命周期，可以被精确地拆解为七个关键阶段，每一个阶段都对应着源码中一个具体的文件或函数。

2.1 阶段一：Shell 解析与进程启动（/usr/bin/env node）

当你按下回车，Shell（如 bash 或 zsh）首先会在$PATH环境变量指定的目录中查找名为zread_cli的可执行文件。如果你是通过npm install -g claude-code安装的，这个文件通常位于/usr/local/bin/zread_cli（Linux/macOS）或C:\Users\<user>\AppData\Roaming\npm\zread_cli.cmd（Windows）。打开这个文件，你会发现它并非一个编译好的二进制，而是一个极简的 Shell 脚本或批处理文件：

#!/usr/bin/env node require('../lib/cli.js').run();

这行#!/usr/bin/env node是 Unix/Linux 系统的“shebang”，它告诉操作系统：请用env命令找到当前 PATH 中第一个node可执行文件，并用它来运行后面的 JavaScript 代码。这就是为什么nvm安装后npm和node失效会导致zread_cli报错——因为env node根本找不到可执行的node。此时，zread_cli脚本本身只是一个“引子”，真正的逻辑在../lib/cli.js里。

2.2 阶段二：CLI 框架初始化（lib/cli.js）

lib/cli.js是整个工具的“大脑皮层”。它不直接处理业务逻辑，而是负责搭建命令行的骨架。其核心是commander库的实例化：

const { Command } = require('commander'); const program = new Command(); program .name('zread_cli') .description('A CLI tool for interacting with Claude Code API') .version(require('../package.json').version); // 注册子命令 program .command('read') .description('Read and analyze a source file') .option('-f, --file <path>', 'Path to the source file') .option('-l, --language <lang>', 'Programming language of the file') .action(async (options) => { const { file, language } = options; await require('../lib/commands/read').execute(file, language); });

这段代码定义了zread_cli read这个子命令，并将用户传入的--file和--language参数，打包成一个options对象，传递给../lib/commands/read模块的execute函数。commander在这里扮演了“交通警察”的角色，它解析process.argv，校验参数类型，打印帮助信息，并在一切就绪后，将控制权精准地交给业务模块。

2.3 阶段三：参数校验与配置加载（lib/commands/read.js）

进入read.js，真正的业务逻辑才开始。它的第一件事，是进行严格的输入校验：

const fs = require('fs').promises; async function execute(filePath, language) { // 1. 检查文件是否存在且可读 try { await fs.access(filePath, fs.constants.R_OK); } catch (err) { console.error(`❌ Error: File '${filePath}' does not exist or is not readable.`); process.exit(1); } // 2. 检查文件大小，避免上传过大的文件导致 API 超时 const stats = await fs.stat(filePath); if (stats.size > 5 * 1024 * 1024) { // 5MB 限制 console.error(`❌ Error: File size (${(stats.size / 1024 / 1024).toFixed(2)}MB) exceeds 5MB limit.`); process.exit(1); } // 3. 加载用户配置，优先级：命令行参数 > 本地 .zreadrc > 全局 ~/.zreadrc const config = loadConfig({ filePath, language }); const apiKey = config.apiKey || process.env.CLAUDE_API_KEY; if (!apiKey) { console.error('❌ Error: CLAUDE_API_KEY is not set. Please set it as an environment variable or in .zreadrc.'); process.exit(1); } }

这段代码揭示了三个重要设计原则：

• 防御性编程：它不信任任何外部输入，对文件路径、文件大小、API Key 都做了显式的、有边界的检查。
• 配置灵活性：它支持三种配置来源，这解释了为什么网络上有人问“claude code怎么设置 API Key”，答案可以是export CLAUDE_API_KEY=xxx，也可以是创建一个~/.zreadrc文件写入{"apiKey": "xxx"}。
• 用户体验友好：错误信息明确指出了问题所在（文件不存在、大小超限、Key 未设置）和解决路径（设置环境变量、修改配置文件），而不是抛出一个晦涩的TypeError: Cannot read property 'length' of undefined。

2.4 阶段四：文件读取与上下文预处理（lib/utils/fileProcessor.js）

校验通过后，read.js会调用fileProcessor模块来读取和处理源文件：

const { detectLanguage } = require('./languageDetector'); async function processFile(filePath, languageHint) { const content = await fs.readFile(filePath, 'utf8'); // 自动检测语言，如果命令行未指定 const detectedLang = languageHint || detectLanguage(filePath, content); // 关键步骤：对长文件进行智能切片 const chunks = splitIntoChunks(content, detectedLang); return { content, language: detectedLang, chunks, filePath }; } function splitIntoChunks(content, language) { const lines = content.split('\n'); const maxLinesPerChunk = getLinesPerChunk(language); // 不同语言，切片策略不同 const chunks = []; for (let i = 0; i < lines.length; i += maxLinesPerChunk) { chunks.push(lines.slice(i, i + maxLinesPerChunk).join('\n')); } return chunks; }

这个splitIntoChunks函数是claude-code区别于简单curl调用的关键。它没有把整个main.py（可能上千行）一股脑发给 API，而是根据编程语言的特性（例如 Python 的缩进、JavaScript 的大括号、TypeScript 的接口定义）进行语义感知的切片。getLinesPerChunk的返回值可能是：Python 150 行、JavaScript 100 行、HTML 200 行。这种切片不是为了“省流量”，而是为了确保每个 API 请求都能获得高质量、聚焦的响应。一个 1000 行的 React 组件，如果被切成 10 个 100 行的片段，Claude 就能分别对useEffect、useState、JSX渲染逻辑等不同部分给出精准反馈，而不是在一个混杂的响应里让用户自己找重点。

2.5 阶段五：API 请求构造与发送（lib/api/client.js）

预处理完成后，read.js会将chunks数组中的每一个片段，构造成一个标准的 API 请求体：

const { fetch } = require('undici'); // 使用 undici 替代 node-fetch，性能更好 async function sendToClaude(chunk, language, apiKey) { const payload = { model: 'claude-3-haiku-20240307', // 模型 ID 是硬编码的，这也是一个可定制点 messages: [ { role: 'user', content: [ { type: 'text', text: `You are an expert ${language} developer. Analyze the following code snippet and provide concise, actionable feedback on potential bugs, security issues, and performance improvements. Do not explain basic syntax. Focus only on high-value insights.\n\n\`\`\`${language}\n${chunk}\n\`\`\`` } ] } ], stream: true, // 关键！启用流式响应，实现“打字机”效果 max_tokens: 1024 }; const response = await fetch('https://api.anthropic.com/v1/messages', { method: 'POST', headers: { 'Content-Type': 'application/json', 'x-api-key': apiKey, 'anthropic-version': '2023-06-01', 'anthropic-beta': 'messages-2023-12-15' }, body: JSON.stringify(payload) }); return response; }

这里有几个技术细节值得深挖：

• stream: true：这是实现zread_cli“实时输出”效果的核心。它让 HTTP 响应不再是等待整个 JSON 返回后再解析，而是以text/event-stream的格式，一行一行地推送data: {...}事件。claude-code的lib/api/streamHandler.js模块会监听这个流，并将每一条content_block_delta事件的内容，立即process.stdout.write()到终端。
• 提示词模板（Prompt Template）：text字段里的字符串，就是一个精心设计的 System Prompt。它强制设定了 Claude 的角色（专家开发者）、任务（分析而非教学）、输出风格（简洁、可操作）、以及禁忌（不解释基础语法）。这个模板的微小改动，会极大影响最终输出的质量。这也是为什么很多用户觉得“claude code有时很准，有时很水”，根源往往在于这个模板是否契合了当前的分析目标。
• 模型版本硬编码：model字段写死了claude-3-haiku-20240307。这意味着，如果你想切换到sonnet或opus，就必须修改源码并重新构建。这既是限制，也是优势——它保证了行为的可预测性和可复现性。

2.6 阶段六：流式响应解析与终端渲染（lib/api/streamHandler.js）

当fetch返回一个ReadableStream，streamHandler.js就开始工作了：

async function handleStream(response) { const reader = response.body.getReader(); let buffer = ''; while (true) { const { done, value } = await reader.read(); if (done) break; // 将 Uint8Array 转换为字符串 buffer += new TextDecoder().decode(value); // 按行分割，处理每一个完整的 data: {...} 事件 const lines = buffer.split('\n'); buffer = lines.pop(); // 保留最后一行（可能不完整） for (const line of lines) { if (line.startsWith('data: ')) { try { const json = JSON.parse(line.substring(6)); if (json.type === 'content_block_delta') { // 提取 delta 文本并实时输出 const deltaText = json.delta?.text || ''; process.stdout.write(deltaText); } } catch (e) { // 忽略解析错误，继续处理下一行 } } } } }

这个函数是zread_cli用户体验的“心脏”。它实现了真正的“流式”——你看到的每一行反馈，都是服务器生成后，毫秒级地推送到你屏幕上的，而不是等整个分析完成后再一次性 dump 出来。buffer和lines.pop()的设计，是为了优雅地处理 TCP 分包问题：网络传输中，一个完整的data: {...}事件可能被拆分成两段到达，buffer就是用来暂存这些“碎片”，直到拼成一个完整的行再进行解析。

2.7 阶段七：错误处理与退出码（贯穿全程）

最后，整个链路的健壮性，体现在无处不在的错误处理上。read.js的execute函数被包裹在一个try...catch中：

async function execute(filePath, language) { try { // ... 所有上述步骤 ... } catch (error) { // 统一错误处理 if (error.name === 'AbortError') { console.error('❌ Error: Request timed out. Please check your network connection.'); process.exit(124); // 自定义退出码，便于脚本调用方判断 } else if (error.response?.status === 401) { console.error('❌ Error: Invalid or expired API key.'); process.exit(126); } else if (error.response?.status === 429) { console.error('❌ Error: Rate limit exceeded. Please wait and try again.'); process.exit(127); } else { console.error(`❌ Unexpected error: ${error.message}`); process.exit(1); } } }

不同的 HTTP 状态码，对应不同的用户指导和退出码。这使得zread_cli不仅可以被人使用，更可以被其他自动化脚本（比如 CI/CD 流水线）可靠地调用和判断结果。一个exit 126的状态，脚本就知道是密钥问题，可以自动触发密钥轮换流程；而exit 124则意味着网络问题，可以自动重试。

3.zread与zread_cli：命名背后的工程哲学与生态位选择

网络热搜里，“zread”和“zread_cli”这两个名字总是交替出现，让人困惑：它们是同一个东西吗？为什么要有两个名字？这背后，其实是一次非常典型的、面向不同用户场景的工程决策。

3.1zread：作为“零配置即用”的快捷入口

zread是claude-code项目在package.json的bin字段中声明的主命令名：

{ "name": "claude-code", "version": "1.2.0", "bin": { "zread": "./lib/cli.js", "zread_cli": "./lib/cli.js" } }

是的，你没看错。zread和zread_cli在源码层面，完全指向同一个./lib/cli.js文件。它们的区别，纯粹是 npm 在安装时，根据bin字段的键名，为你在node_modules/.bin/目录下创建的不同名称的符号链接。zread是一个更短、更顺口、更符合 Unix 哲学（短小精悍）的名字；而zread_cli则是一个更长、更明确、更利于搜索引擎抓取的名字。

这个设计的精妙之处在于，它同时满足了两种截然不同的用户心智模型：

• 极客用户：他们喜欢zread --file index.ts，因为敲击次数最少，符合ls、cat、grep这些经典 Unix 命令的命名直觉。
• 普通开发者用户：他们在 Google 搜索“claude code cli”时，能直接命中zread_cli这个命令，降低了学习成本。zread_cli这个名字本身，就是一个自解释的文档。

注意：zread并非一个独立的、功能更少的“简化版”。它和zread_cli的所有功能、所有参数、所有子命令，100% 完全一致。你可以在npx claude-code zread --help和npx claude-code zread_cli --help中得到完全相同的输出。它们只是同一把钥匙的两个不同形状的齿。

3.2npx：规避全局安装陷阱的终极方案

既然zread和zread_cli是同一个东西，那么“npm install -g claude-code”这个操作，就显得有些多余，甚至危险。全局安装会将zread符号链接到系统 PATH，这在多项目、多 Node.js 版本（通过nvm管理）的环境下，极易引发冲突。nvm安装后npm和node失效，根本原因就是全局npm的bin目录被错误地添加到了 PATH 中，覆盖了nvm动态切换的node路径。

npx的出现，完美地解决了这个问题。npx的工作原理是：在执行命令前，先检查本地node_modules/.bin/目录下是否有该命令；如果没有，则临时下载对应的包，执行其bin脚本，然后自动清理。因此，最推荐、最安全的使用方式是：

# 无需任何安装，直接运行 npx claude-code zread --file src/main.py # 或者，如果你已经在一个项目里，想把它作为开发依赖 npm install --save-dev claude-code npx zread --file src/main.py

这种方式的好处是：

• 零污染：不会修改你的全局 PATH，不会与nvm冲突。
• 版本锁定：npx claude-code@1.2.0可以精确指定版本，避免因上游包更新导致的意外行为变更。
• 按需加载：你不需要为一个偶尔使用的工具，长期占用磁盘空间和维护一个全局依赖。

网络上大量关于npm : 无法加载文件 c:\program files\nodejs\npm.ps1的报错，其根源就在于用户执着于npm install -g。而npx方案，从根本上绕开了 PowerShell 执行策略这个 Windows 特有的“坑”。

3.3codex cli与claude code cli：一场命名的混淆与澄清

热搜词中，“codex cli”和“claude code cli”经常被混用。这是一个历史遗留的误解。Codex是 OpenAI 在 2021 年发布的一个专注于代码的 GPT-3 变体模型，它有自己的 API 和生态。而Claude Code是 Anthropic 基于 Claude 3 模型族，专门为代码分析和生成优化的一套工具链。

claude-code这个 npm 包，与 OpenAI 的 Codex 没有任何关系。它的名字claude-code，是Claude+Code的组合，意为“为代码而生的 Claude”。之所以被误称为codex cli，是因为早期一些中文社区的翻译不够准确，将code误译为codex，而codex这个词本身在开发者圈子里又极具辨识度，久而久之就形成了一个“美丽的错误”。

这个混淆，在claude code接入deepseek这样的热搜词中体现得尤为明显。DeepSeek 是另一家中国 AI 公司，它有自己的大模型。claude-code作为一个开源的、基于 Anthropic API 的 CLI，其源码中所有的fetch请求，都硬编码指向https://api.anthropic.com。它无法也不应该被“接入”到 DeepSeek 的 API。如果你看到某个教程声称可以“claude code接入deepseek”，那要么是作者对claude-code的架构一无所知，要么是他在推广一个 fork 后修改了 API endpoint 的私有版本。对于追求稳定和可维护性的生产环境，坚持使用官方claude-code，并理解其与 Anthropic API 的强绑定关系，是唯一正确的选择。

3.4claude code desktop版与cli版：UI 与 UX 的本质差异

“claude code桌面版和cli版的区别”是另一个高频问题。桌面版（通常指 Electron 封装的 GUI 应用）和 CLI 版，代表了两种完全不同的交互范式：

举个具体例子：你想在 CI/CD 流水线中，对每次git push的代码进行自动审查。CLI 版可以轻松地写成一行 shell 脚本：if ! npx claude-code zread --file "$CHANGED_FILE" --language "$LANG"; then echo "Critical issue found!"; exit 1; fi。而桌面版对此则完全无能为力。反之，如果你是一个刚入门的前端实习生，想快速了解一个陌生的 Vue 组件，桌面版的点击、高亮、跳转功能，会比在终端里敲命令、看纯文本反馈要直观得多。

因此，“区别”不在于哪个“更好”，而在于哪个“更适合你的场景”。一个成熟的工程团队，往往会同时使用两者：用 CLI 版做自动化、做集成、做审计；用桌面版做探索、做演示、做快速原型。

4. 源码级定制：从修改提示词到替换 API Provider 的完整实践

“全面拆解”的最终目的，是“可定制”。claude-code的源码结构，为各种级别的定制提供了清晰的入口。下面，我将带你完成三个从易到难的实战改造，每一个都基于真实的项目需求。

4.1 改造一：定制化提示词（Prompt Engineering），提升分析质量

默认的提示词模板（见 2.5 节）是一个通用的“专家开发者”角色。但在实际项目中，你的团队可能有自己独特的代码规范、技术栈偏好，甚至是特定的安全红线。这时，修改提示词是最简单、见效最快的定制。

目标：让zread_cli在分析 Python 代码时，强制要求 Claude 检查是否使用了pickle.load()，并将其标记为CRITICAL级别风险。

步骤：

1. 找到提示词模板文件。它通常位于src/templates/prompt.ts或src/utils/promptBuilder.ts。
2. 修改buildPromptForLanguage函数，为python语言添加专属规则：

function buildPromptForLanguage(content: string, language: string): string { let basePrompt = `You are an expert ${language} developer. Analyze the following code snippet and provide concise, actionable feedback...\n\n\`\`\`${language}\n${content}\n\`\`\``; if (language.toLowerCase() === 'python') { basePrompt += `\n\n⚠️ SPECIAL INSTRUCTIONS FOR PYTHON: - You MUST scan for any usage of 'pickle.load()', 'pickle.loads()', 'cPickle.load()', or 'cPickle.loads()'. - If found, classify it as a CRITICAL security vulnerability (Remote Code Execution risk). - Your feedback MUST start with '[CRITICAL] Unsafe pickle usage detected at line X.'`; } return basePrompt; }

3. 重新构建项目：npm run build
4. 测试：创建一个包含pickle.load(f)的测试文件，运行npx ./dist/cli.js read --file test.py --language python。

效果：Claude 的响应中，会强制出现[CRITICAL] Unsafe pickle usage detected at line 12.这样的开头。这比在事后用grep去扫描日志要主动、要精准。

实操心得：提示词是“软性”定制，它不改变程序逻辑，只改变 AI 的输出。因此，它是风险最低、迭代最快的定制方式。我建议每个团队都维护一个自己的prompt.ts，将其纳入 Git 仓库，作为团队知识资产的一部分。

4.2 改造二：修改全局安装路径，彻底告别 PowerShell 报错

npm : 无法加载文件 c:\program files\nodejs\npm.ps1这个报错，根源在于 Windows 默认的npm全局安装路径（C:\Program Files\nodejs\node_modules\npm\bin）位于受保护的系统目录下，PowerShell 的AllSigned策略禁止执行其中的脚本。

目标：将npm的全局安装路径，从C:\Program Files\nodejs迁移到一个用户有完全控制权的路径，例如C:\Users\<YourName>\npm-global。

步骤：

1. 创建新目录：mkdir C:\Users\<YourName>\npm-global
2. 配置 npm 使用新路径：

   npm config set prefix "C:\Users\<YourName>\npm-global"

3. 将新路径添加到系统的PATH环境变量中（控制面板 -> 系统 -> 高级系统设置 -> 环境变量 -> 用户变量 -> PATH -> 新建）。
4. 最关键的一步：重启你的终端（PowerShell 或 CMD），让新的PATH生效。
5. 验证：npm config get prefix应该输出C:\Users\<YourName>\npm-global；npm install -g claude-code后，zread_cli的可执行文件应该出现在C:\Users\<YourName>\npm-global\bin下。

原理：npm config set prefix命令修改了 npm 的全局安装根目录。此后，所有npm install -g的包，其bin脚本都会被链接到这个新目录下的bin子目录中。由于这个目录完全属于当前用户，PowerShell 的执行策略不再对其施加限制。

注意：这个操作只影响npm的全局安装行为，不影响npx。npx依然会优先查找项目本地的node_modules/.bin，所以它始终是更安全的选择。

4.3 改造三：替换 API Provider，从 Anthropic 切换到本地 Ollama 模型

这是最高阶的定制。claude-code的核心价值在于其 CLI 框架和文件处理逻辑。理论上，你可以将它的“大脑”（API 调用）替换成任何兼容的 LLM Provider。

目标：让zread_cli不再调用 Anthropic 的云端 API，而是调用本地运行的Ollama服务，使用codellama:13b模型进行代码分析。

前提：已在本地安装并运行 Ollama：ollama run codellama:13b

步骤：

1. 修改lib/api/client.js，将fetch请求的目标 URL 从https://api.anthropic.com/v1/messages改为http://localhost:11434/api/chat（Ollama 的默认 chat API）。
2. 重构请求体（payload）的格式，以匹配 Ollama 的 API 规范：

// 替换旧的 Anthropic payload /* const payload = { model: 'claude-3-haiku-20240307', messages: [...], stream: true, max_tokens: 1024 }; */ // 改为 Ollama payload const payload = { model: 'codellama:13b', // 本地模型名 messages: [ { role: 'system', content: `You are an expert Python developer. Analyze the following code snippet...` }, { role: 'user', content: `Here is the code:\n\`\`\`python\n${chunk}\n\`\`\`` } ], stream: true, options: { num_ctx: 4096, // 上下文长度 temperature: 0.2 // 控制随机性 } };

3. 修改流式响应处理器lib/api/streamHandler.js，以解析 Ollama 的text/event-stream格式。Ollama 的事件格式是data: {"message":{"role":"assistant","content":"..."}}，与 Anthropic 的content_block_delta不同，需要调整JSON.parse的路径。

4. （可选）添加一个命令行参数--provider ollama，让 CLI 可以在 Anthropic 和 Ollama 之间动态切换，而不是硬编码。

效果：zread_cli现在变成了一个“本地 AI 代码分析器”。它不再产生任何网络费用，响应速度取决于你的本地 GPU/CPU，且所有代码数据都保留在你的机器上，满足了严格的数据合规要求。

实操心得：这种改造证明了claude-code架构的优秀。它的“输入处理”（文件读取、切片）和“输出呈现”（流式终端渲染）是高度解耦的，中间的“AI 推理”层只是一个可插拔的适配器。这正是一个优秀开源项目的标志：它不强迫你接受它的所有假设，而是为你留出了足够的扩展缝隙。

5. 踩坑实录：那些在Ubuntu 20.04和Windows上真实发生过的排错全过程

理论再完美，也抵不过一次真实的失败。下面，我将还原两个我在不同环境中部署zread_cli时，花费数小时才解决的真实问题。它们的解决方案，都不在任何官方文档里，但却是每个使用者迟早会遇到的。

5.1 问题一：在 Ubuntu 20.04 上，zread_cli报错Error: EACCES: permission denied, mkdir '/home/user/.zread'

现象：在一台全新的 Ubuntu 2