在开发者的工具箱里命令行界面工具总是那个Zui不起眼却Zui强大的存在。起初，它们往往只是一个简单的脚本，几十行代码，解决一个具体的问题。但随着业务逻辑的复杂化，尤其是当我们将大语言模型引入到工具链中时原本简单的脚本往往会变成难以维护的“意大利面条式代码”。本文将以一个名为 SmartInspector 的项目为例，深入探讨如何从零开始构建一个健壮、可 的 CLI 工具架构，以及在这个过程中我们踩过的坑和Zuo出的关键设计决策。

每一个伟大的 CLI 工具，Zui初的样子dou极其相似。对于 SmartInspector 来说它Zui开始也只是一个 main.py。那时候的逻辑非常线性：接收用户输入，调用 LLM，解析结果，然后打印输出。没有复杂的状态管理，没有流式输出，甚至连像样的错误处理dou没有。用户输入一句话，然后盯着光标发呆十几秒，Zui后kan到一大段文字一次性刷在屏幕上。

这种“单文件包打天下”的模式在原型阶段非常高效。你不需要考虑文件结构，不需要在模块之间传递数据，所有的逻辑dou在一个作用域内，清晰可见。然而这种简单是有代价的。随着需求的增加——比如我们要加入源码搜索、Android 数据采集、报告生成等功Neng——if-elif 的链条开始疯狂生长。代码的圈复杂度直线上升，每增加一个新功Neng，dou要在原有的逻辑上打补丁，维护成本呈指数级增长。

geng糟糕的是当需求从“单次对话”变成“多轮交互”时单文件的局限性暴露无遗。用户可Neng先执行了一个采集命令，紧接着又基于采集的数据提问。这时候，我们需要在内存中保存上一次的采集结果。在一个 main.py 里用局部变量来管理这些状态，不仅混乱，而且极易出错。到了这个阶段，重构Yi经不再是“锦上添花”，而是“不得不Zuo”的生存问题了。

为了解决 性和状态管理的痛点，我们决定借鉴 LangGraph 的 State Graph 模式，将整个架构模块化。这不仅仅是把代码拆分到不同的文件里geng是一种思维方式的转变：从“过程式编程”转向“声明式配置”。

我们将整个 CLI 工具拆分成了四个核心层次每一层dou有明确的职责边界：

状态管理是整个架构的核心。在重构后的架构中，我们定义了一个 AgentState，它使用 Python 的 TypedDict 来描述。这里有一个非常微妙但关键的设计决策：消息历史与数据字段的语义区分。

在 AgentState 中，messages 字段用于存储对话历史。我们使用了 Annotated 这样的注解，这意味着每当有新的消息产生，LangGraph 会自动将其追加到列表中，而不是覆盖。这对于多轮对话至关重要。然而对于像 perf_summary或 attribution_result这样的数据字段，我们采用“后写覆盖”策略——任何节点写入这些字段，dou会直接geng新其值，下游节点读取到的永远是Zui新的数据。

为什么选择 TypedDict 而不是geng严格的 Pydantic Model？这是一个权衡。Pydantic 提供了运行时的类型校验，Neng在数据格式错误时立即报错，这对于大型系统非常有价值。但对于一个节点数在个位数的 CLI 工具来说Pydantic 的序列化开销和样板代码显得有些过重。我们选择了geng轻量的 TypedDict，虽然牺牲了一定的类型安全性，但换取了代码的简洁和运行时的灵活性。

路由逻辑通常是一堆冗长的 if-else 语句。而在新的架构中，我们将这部分逻辑抽离到了 builder.py 中。这里不再写“怎么Zuo”，而是描述“是什么”。

我们定义了一个“编排器”节点，它就像是一个交通指挥中心，根据用户的意图决定下一步该走哪条路。Ru果用户只是想搜索源码，路由到 explorer；Ru果想分析数据，路由到 analyzer；Ru果要跑全流程，则进入 collector → analyzer → attributor → reporter 的流水线。

这种设计极大地降低了代码的复杂度。通过 LangGraph 的 add_conditional_edges，我们将复杂的分支逻辑变成了配置。Ru果未来需要增加一个新的分支，只需要在 builder.py 里加几行配置，而不需要去修改核心调度逻辑。这就是声明式配置的魅力所在。

在 nodes/ 目录下存放着各个具体的 Agent 节点。每个节点只关心自己的事情：collector 负责采集数据，analyzer 负责分析，reporter 负责生成报告。

这里有一个经常被忽视的细节：透传逻辑。由于状态是一个共享的对象，每个节点在返回geng新时必须包含那些它没有修改的字段，否则这些字段就会在状态geng新中丢失。为了解决这个问题，我们封装了一个 _pass_through 工具函数。它自动把那些不需要当前节点修改的字段打包带走，让节点的返回值保持干净。早期版本没有这个机制，经常出现某个节点忘了透传 perf_summary，导致下游节点拿到空数据，排查起来非常痛苦。

在分布式系统或复杂的流水线中，Zui怕的就是“一颗老鼠屎坏了一锅粥”。Ru果 attributor 节点因为文件编码问题抛出异常，整个程序不应该直接崩溃。

为此，我们实现了一个装饰器 node_error_handler。它给每个节点套上了一层 try-catch 保护罩。当节点内部发生异常时装饰器会捕获错误，打印一条友好的错误信息，并返回一个包含错误详情的 AIMessage，而不是让异常向上冒泡导致整个图的中断。这种设计保证了即使某个环节失败了用户也Neng知道发生了什么而不是面对一个莫名其妙的堆栈跟踪。

架构的健壮性只是基础，对于 CLI 工具来说用户体验同样重要。没有人愿意对着空白的命令行等待 10 秒钟，然后突然kan到一大段输出。

为了解决等待焦虑，我们引入了流式处理机制。通过 LangGraph 的 stream_mode="updates"，我们Ke以实时捕获每个节点的输出。

但这又带来了一个新的问题：并不是所有节点的输出dou适合直接展示给用户。比如 collector 节点可Neng会输出大量的 JSON 数据或进度信息，这些对普通用户来说是噪音。因此，我们在流式处理函数中增加了一层过滤逻辑：只打印 LLM 节点生成的文本内容，而对于后台处理节点的技术性输出，则只在 --debug 模式下显示。这种“按需输出”的策略，极大地提升了终端的整洁度和专业感。

CLI 工具的入口通常是 cli.py。我们使用了 prompt_toolkit 而不是 Python 原生的 input，原因hen简单：我们需要geng好的交互体验。prompt_toolkit 提供了 FileHistory 来保存用户的输入历史，支持上下键翻阅之前的命令；还提供了 WordCompleter，当用户输入斜杠 / 时Ke以自动补全 /full/clear 等命令。这些kan似微小的功Neng，在频繁调试时Neng极大地提高效率。

此外我们还区分了“斜杠命令”和“自然语言输入”。像 /full 这样的命令是确定性的操作，它们直接触发底层的采集流水线，完全不需要经过 LLM 的路由。这种区分不仅节省了 Token 费用，geng重要的是提高了响应速度——用户想要的是立刻执行，而不是让 AI 思考“他是不是想让我执行这个命令”。

多轮对话的核心在于记忆。SmartInspector 使用了 LangGraph 的 checkpointer来实现状态的持久化。

这里有一个深坑：序列化配置。默认情况下MemorySaver 使用 JSON 进行序列化，但我们的状态中包含了一些自定义的类型。Ru果不显式地告诉序列化器如何处理这些类型，它就会静默失败，导致状态丢失。我们不得不配置 serde 参数，使用 msgpack 并显式注册白名单，才解决了这个问题。

通过 graph.get_state，我们Ke以在每一轮对话结束时从 checkpointer 中拉取Zui新的完整状态，而不是手动去合并各个节点的输出。这不仅避免了数据重复的风险，也让状态管理变得geng加透明和可控。

回顾 SmartInspector 的架构演进过程，从单文件的 main.py 到模块化的 graph/ 目录，每一步dou不是预先规划好的，而是被实际问题逼出来的。这大概就是“演进式架构”的真实写照——不要试图在一开始就设计出完美的系统，让架构随着痛点的出现而生长。

Ru果你正在着手构建一个类似的 CLI 工具，我的建议是：

先让它跑起来从单文件开始，快速验证核心逻辑。

识别痛点当 if-else 太多、状态管理混乱、错误难以排查时就是重构的信号。

合理分层将状态定义、拓扑构建、节点逻辑和交互入口分离，各司其职。

重视体验流式输出、历史记录、错误提示，这些细节决定了用户是否愿意使用你的工具。

构建 CLI 工具架构，本质上是在管理复杂度。无论是选择 LangGraph 还是自己写调度器，TypedDict 还是 Pydantic，dou没有绝对的对错，只有适合与否。希望这些从实战中出来的经验，Neng为你构建下一个强大的命令行工具提供一些参考。