一、先看效果

一样一个任务“创建 React 项目”，没做可视化之前：

$ node src/main.js
任务完成。项目已创建在 react-todo-app

做了可视化之后：

$ node src/main.js "创建一个 todo 应用"
🚀 Agent 启动📝 任务: 创建一个 todo 应用━━━ 第 / 轮 ━━━📋 模型请求调用 个工具:
→ execute_command command: pnpm create vite react-todo-app --template react-ts
⚡ execute_command ✔ execute_command → 命令执行成功━━━ 第 / 轮 ━━━📋 模型请求调用 个工具:
→ write_file filePath: react-todo-app/src/App.tsx
⚡ write_file ✔ write_file → 字符━━━ 第 / 轮 ━━━🤖 Agent 最终回复:
TodoList 应用已创建完成，功能包含添加、删除、筛选和本地存储。✅ Agent 执行完成!不过，

一样的功能。后者让你看清楚 Agent 的每一步决策。老实说，

一个给终端文字上色的库。只有一件事：把 console.log 变成彩色的。

import chalk from 'chalk'
console.log);// 绿色文字
console.log);// 红色加粗
console.log);// 蓝色
console.log);// 灰色

Chalk v5 的 ESM 变化

v5 是 ESM-only，只能用 import

// ✅ v5 正确写法
import chalk from 'chalk';不过，chalk.green;// ❌ 常见错误 — 从旧版本教程抄来的
const chalk = require;怎么说呢，// v5 不支持 require
import { Chalk } from 'chalk';// Chalk 是类，不是你要用的

常用颜色与使用场景

chalk.green // 工具执行成功 chalk.red // 错误信息 chalk.yellow // 达到最大迭代次数 chalk.cyan // Agent 计划做什么 chalk.magenta.bold // 轮次分隔 chalk.blue // Agent 的最终输出 chalk.gray // 文件方法、耗时、ID chalk.white // 具体要执行的命令

三、从散弹到统一：Logger 模式的设计

从第一版来看。各自为政

最早我在四个工具文件里各自写 console.log：

// readFileTool.js
console.log 成功读取${content.length}字节`);// writeFileTool.js
console.log 创建成功写入${content.length}字节`);// execCommandTool.js
console.log 成功执行`);

• 格式不统一: 有的带 前缀，有的没有；按理说，有的显示字节数，有的不显示。
• 没有颜色: 全是白字，关键信息淹没在日志里。按理说，
• 职责混乱: 工具既要执行逻辑又要管展示。老实说，

第二版这方面，加 Chalk，但没统一

改成彩色了但日志逻辑仍然散落在各个文件：

// 每个工具文件都 import chalk from 'chalk'。接下来各自 console.log

改一个颜色规范要动四个文件。新增工具还得记住用什么格式。

从最终版来看，Logger 集中管理

Create a single logger in src/utils/logger.js。all visualization logic is centralized:

import chalk from 'chalk';export const logger = {
phase {
console.log);},toolPlan {
console.log);for {
console.log);if {
for ) {
console.log);}
}
}
},toolSuccess {
console.log(
chalk.green +
chalk.gray`) +
: '')
);},toolFail {
console.log(
chalk.red +
chalk.gray`) +
chalk.red
);},agentReply {
console.log);console.log);
},}，

现在工具文件里一行 console.log 都没有了——纯函数，只返回结果字符串。不过，所有可视化由 ReactAgent 调用 logger 完成。说起来，

四、可视化与执行分离

改造前的工具示例

// 写入文件并直接打印日志
async => {
try {
await fs.mkdir;说起来，await fs.writeFile;console.log(
chalk.green))
return成功写入${filePath};} catch {
console.error(
chalk.red);return写入失败: ${err.message}`;}
}

使用者痛点：因为日志混杂导致调试困难，无法快速定位错误或确认进度。把日志逻辑剥离，让业务代码更简洁，也让调试更高效！怎么说呢，

javascript async => { try { const dir = path.dirname;await fs.mkdir;await fs.writeFile;return `成功写入${filePath} `;} catch{ return `写入文件${filePath}失败:${err.message}`;} }

Agent 层统一调用 logger

使用者痛点：Agent 层缺乏可观察性，导致使用者无法知道步骤是否卡住或慢速。通过集中管理日志，可实时看到每一步进度和耗时！

javascript for{ logger.toolStart;// 开始执行 const start=Date.now;let result，try{ result=await tool.invoke;}catch{result=`工具执行出错:${e.message}`;} const dur=Date.now-start;logger.toolSuccess);}

旧方案	新方案
* 工具文件含 ch?log * 彩色规范 散落各处 易不一致*	* logger.js 一处定义 新增工具只需记住格式 logger 自动处理修改展示*
N 个文件只改 logger.js测试日志干扰测试*	logger 自动处理无干扰测试*
tools 函数内含 log 返回结果字符串*	tools 函数仅返回字符串。无 log*
调试难度大*	调试轻松，可查看完整流程*
* 更多好处请自行体验 *

css css css ​

---

至于**注意**，上述表格仅为示意，实际代码与结构请参照原始实现。

---

五、让信息有层次

好的可视化不是“所有东西都亮”，而是`关键信息跳出来辅助信息退到背景里`。

色彩语义程序

色	用途
🟢 green	成功
🔴 red	失败
🔵 blue	Agent 回复
🟣 magenta	阶段标记
🟡 cyan	意图/计划
🟡 yellow	警告
⚪ gray	元数据

控制信息密度

长字符串自动截断。例如只显示摘要，而非全量内容：

javascript// logger.js 中处理 const display = typeof value === 'string' && value.length> MAX_LEN?value.slice(0,MAX_LEN)+'...' : value;按理说，

时序与计时

每轮迭代和每个工具调用都有计时：

━━━ 第 / 卷 ┗─── 执行时间：execute_command ┗─── 写入文件

这让使用者能直观感受到哪些步骤慢。还有慢在哪里，

---

这篇文章讲了三个层次的事：

1. 第一层 — 工具Chalk v5 是 ESM-only。用 import chalk from 'chalk'即可，并支持链式如.red.bold`。
2. 第二层 — 模式logger.js 集中管理模式。把业务代码纯净化，让 Agent 层统一调度。
3. 第三层 — 思想可视化不是为了花哨，而是提高可观测性。

三篇文章构成完整学习方法：

篇	主題	主要問題
第一篇	Agent 設計	為什麼能工作？说起来，
第二篇	内置模块	怎麼干活？
第三篇	可視化	干了什麼？

• 仓库地址 ： min‑cursor

---

---