企业官网建设流程全解析

读源码这件事，我见过太多人卡在同一个地方：拿到一个项目，目录结构还没看明白，就一头扎进某个文件里逐行读，结果被层层调用绕晕，最后连程序从哪启动的都没搞清楚。源码阅读的第一步永远是找入口，第二步是找主循环。这篇文章要拆的 Hermes，是一个刻意做了减法的教学级 CLI 对话框架 Demo，取“传信使者”的意思，用来演示一个命令行交互程序最核心的两块骨架：入口（main）和主循环（REPL loop）。它能做的事情很简单：你在终端敲一行字，它给你回一行；你敲 /exit，它退出。从命令行启动到一次完整对话，关键代码都集中在入口函数和主循环这两段里。这篇文章适合两类人：一类是刚开始读源码、不知道从哪下手的开发者；另一类是写过 Python 脚本但没写过长期运行的服务型程序的人。我会按真实的阅读顺序来：先画整个项目的结构地图，再逐段拆解入口和主循环，每段代码都会讲清楚“为什么这么写”，最后把我实际踩过的坑一并列出来。

1. 源码阅读的第一步：先画代码地图，别急着读代码

1.1 工程结构：一个包四个模块，各管一件事

很多新手拿到源码，习惯从第一个文件的第一行开始读。这个方法放在小脚本上没问题，放在多模块项目上基本就是自杀式阅读。我的习惯是先在项目根目录停一下，把目录结构完整看一遍，先回答两个问题：入口在哪里，核心流程在哪个文件。读 Hermes 之前，你先看它的目录结构：

hermes/ ├── pyproject.toml └── hermes/ ├── __init__.py ├── cli.py # 命令行入口：参数解析、初始化、拉起主循环 ├── config.py # 配置加载与默认值合并 ├── runtime.py # REPL 主循环：读入、分发、输出 ├── engine.py # 对话引擎：根据输入生成回复 └── context.py # 会话上下文：保存历史消息

这个结构是我刻意收敛过的。真实项目里肯定会有更多模块，但只要你抓住一条主线，再多文件也不会乱。Hermes 的主线是单向的：用户从终端输入，cli.py 负责把启动参数变成运行配置，runtime.py 负责循环接收输入并分发，engine.py 负责产生回复，context.py 负责记录对话历史。方向是从外向里，数据一层层往下流。

每一层只做一件事，这是源码阅读友好的关键。我见过不少项目把参数解析、配置合并、日志初始化、主循环全部堆在 main 函数里，几百行下来边界非常模糊，读起来很累，因为一个函数里同时发生着好几件事。Hermes 刻意把这些拆开了，你阅读时只需要关心当前这一层，出现问题也知道往哪个文件里去找。

1.2 从终端敲下命令到 main 函数之间发生了什么

如果你在终端里执行hermes --config config.yaml，这个过程并不神秘。系统先在 PATH 里找到 hermes 这个可执行命令，它指向的是一个由 Python 安装时生成的启动脚本，这个脚本来自 pyproject.toml 里的 console_scripts 声明：

[project.scripts] hermes = "hermes.cli:main"

这行配置的意思是：安装这个包之后，会生成一个名为 hermes 的命令，执行时调用hermes.cli模块里的 main 函数。Python 的包管理工具会帮你处理好路径和环境问题，于是你在终端敲下 hermes，本质等同于执行了一次python -c "from hermes.cli import main; main()"，命令行里的参数会通过 sys.argv 传入。

所以读 Hermes 的源码，真正的入口是hermes/cli.py里的 main 函数，不是init.py，也不是某个叫 app.py 的文件。有些项目习惯用main.py 支持python -m hermes的启动方式，Hermes 为了简洁没有单独做，但你要知道这两种方式本质等价。找到入口之后，下一步才是读 main 函数。

从终端到 Python 进程这条链路，很多人一开始并不关心，但它实际上决定了你在哪一层打断点。比如你怀疑是参数没传进来，就不需要跑到 engine 那边去打断点，直接在 main 的开头打印 sys.argv 就够了。这属于源码阅读里的“定位感”：先知道自己站在整条链路的哪一段，再决定下一步往哪个方向排查。

2. 入口逻辑：main 函数里的三个动作

cli.py 的完整代码不长，我把整段贴出来，后面逐段讲：

import argparse import logging import sys from hermes.config import load_config from hermes.runtime import run_repl logger = logging.getLogger("hermes.cli") def parse_args(argv=None): parser = argparse.ArgumentParser( prog="hermes", description="Hermes - 轻量级命令行对话框架", ) parser.add_argument("-c", "--config", default="config.yaml", help="配置文件路径，默认 config.yaml") parser.add_argument("-v", "--verbose", action="store_true", help="输出 DEBUG 级别日志") parser.add_argument("--no-color", action="store_true", help="关闭彩色输出") return parser.parse_args(argv) def main(argv=None): args = parse_args(argv) logging.basicConfig( level=logging.DEBUG if args.verbose else logging.INFO, format="%(asctime)s %(levelname)s %(name)s: %(message)s", ) logger.info("Hermes starting, config=%s", args.config) cfg = load_config(args.config) try: run_repl(cfg, color=not args.no_color) except KeyboardInterrupt: logger.info("received interrupt, bye") return 0 if __name__ == "__main__": sys.exit(main())

main 函数只做了三件事：解析参数、初始化运行时环境、把控制权交给主循环。注意它返回的是 int 类型退出码，0 表示正常结束，非 0 表示异常结束。很多脚本不在乎退出码，但作为命令行程序，退出码是你与外部脚本协作时的接口规范，CI 系统、Shell 脚本都要靠它判断程序是否成功，这个习惯值得尽早养成。

2.1 用 argparse 把命令行变成结构化参数

命令行参数是程序与外界的第一个接口。Hermes 使用标准库 argparse，因为它能自动完成三件麻烦事：类型转换、默认值处理、错误提示。如果你手写 sys.argv 去解析，先不说容易漏掉边界情况，光是 -h 帮助信息就要自己写半天，功能参数一多起来，痛苦程度直线上升。argparse 把这些常见能力做好了，我们直接把参数声明出来，剩下的事情交给标准库。

我在这里定义了三个参数。-c/--config用来指定配置文件，带默认值，用户不传就用当前目录下的 config.yaml。-v/--verbose是一个开关参数，action 设为 store_true，只要出现就是 True，不出现就是 False，不用写if arg == "True"这种容易踩坑的逻辑。--no-color同理，它专门给管道输出、日志重定向这类场景准备，交互式终端里带颜色更友好，但把输出重定向到文件时，颜色转义序列会污染日志内容，所以留一个开关让用户自己决定。

这里有一条我长期坚持的经验：命令行参数要克制，最好控制在五个以内。超过五个，用户记忆成本急剧上升，光靠 help 文本也无法很好表达参数间的关联。Hermes 把对话引擎的规则文件、历史消息长度这些内容放到 YAML 配置里，而不是塞进命令行，正是因为命令行只保留与“启动方式”强相关的选项，而与“运行内容”相关的配置交给文件去承载。

另外，main(argv=None)这种写法是刻意的。它让 main 函数不直接依赖真实运行时的 sys.argv，你测试的时候可以直接传一个字符串列表进去，比如main(["-c", "test.yaml"])。这是可测试性的一个细节，很多脚本想测 main，要么改全局变量、要么上 mock，实际上只要在人参处留一个口子，测试难度立刻降一大截。

2.2 配置加载要放在日志初始化之后

再看 config.py 的实现：

import yaml DEFAULTS = { "max_history": 20, "rules_file": "rules.json", } def load_config(path): try: with open(path, "r", encoding="utf-8") as f: data = yaml.safe_load(f) or {} except FileNotFoundError: data = {} return {**DEFAULTS, **data}

这个函数很短，但有一个初始化顺序问题值得提醒：日志初始化一定要在配置加载之前。为什么？因为配置加载过程中可能出错，YAML 语法写错了、文件权限不对、目录不存在，这些错误信息必须能够进到日志系统里。如果日志还没初始化，报错就只能裸抛出来，用户看到一长串 traceback，体验极差。顺序上，日志是最底层的基础设施，先把它立起来，再去做其他初始化操作。

我选择 YAML 而不是 Python 文件来写配置，是因为不想为了一个配置文件承担执行代码的代价。如果配置直接写在一个 .py 文件里，加载它就是执行它，配置内容里万一有恶意代码或者误写的函数调用，会在导入阶段直接执行。YAML 的 safe_load 只做数据解析，不执行任意代码，安全边界更干净。这个选择对命令行工具尤其重要，因为用户往往会反复修改配置文件，你无法预期文件里被写入了什么。

配置合并用了{**DEFAULTS, **data}这个字典展开技巧，后出现的字典覆盖先出现的，所以用户配置里的每一项会覆盖默认值，没配置到的项保留默认值。这个写法比手写 for 循环简洁，语义也清晰。但有一个坑：如果 YAML 里某个键写了但没有值，读到的是 None，它会覆盖掉默认值。我自己就踩过一次，配置文件里写了max_history:没填数字，结果历史记录长度变成了 None，后续切片逻辑直接抛类型错误。处理办法是在加载后做一层类型校验，或者过滤掉值为 None 的项，总之不能默认这句覆盖永远安全。

3. 主循环：一次对话的真正心脏

3.1 while True + break：交互式程序的运行模型

进入 runtime.py，就看整个程序的心脏：

import logging from hermes.engine import ChatEngine from hermes.context import SessionContext logger = logging.getLogger("hermes.runtime") SPECIAL_COMMANDS = { "/exit": "exit", "/quit": "exit", "/help": "help", "/version": "version", } def run_repl(cfg, color=True): engine = ChatEngine(cfg) ctx = SessionContext(max_history=cfg.get("max_history", 20)) logger.info("Hermes ready, type /help to see commands") while True: try: raw = input("hermes> " if color else "> ") except EOFError: print() logger.info("received EOF, exit") break except KeyboardInterrupt: print() logger.info("received Ctrl+C, exit") break text = raw.strip() if not text: continue if text.startswith("/"): result = dispatch_command(text, ctx) else: result = engine.respond(text, ctx) print(result) if ctx.should_exit: break

有读者会问，为什么主循环用while True加 break，而不是写一个带条件的 while 表达式？因为退出条件本身是动态变化的：可能是用户输入了 /exit，可能是收到了 EOF（Ctrl+D），也可能是 Ctrl+C。这三种情形在进入循环之前一个都判断不了。用 while True 加显式 break，是最直接表达“循环直到退出信号出现”的方式，读起来反而最清晰。

这个循环模型叫 REPL（Read-Eval-Print Loop），是交互式程序最经典的骨架。你在 Python 控制台、数据库命令行工具、各种 REPL 工具里看到的交互逻辑，本质都是这个模式：读入一行，计算一个结果，打印出来，然后继续等待下一行输入。理解了它，你就理解了几乎所有命令行交互工具的核心运行方式。

这里还专门处理了标准输入的两个结束信号。EOFError 发生在用户按 Ctrl+D 时，表示输入流结束；KeyboardInterrupt 对应 Ctrl+C。这两个信号都不能让程序直接裸奔，否则会打印出一长串 traceback，把终端弄得很难看。注意我在 break 之前都先打印了一个空行，如果不打印，程序退出后终端会残留一个未换行的提示符，看起来很粗糙。这些细节点往往决定一个工具给人感觉是“业余”还是“专业”。

3.2 输入清洗与空输入跳过：小细节决定稳定性

循环体里第一件正事是对原始输入做 strip，然后检查空输入。这一步看着不起眼，但漏掉它，用户多敲几个空格，程序就会把纯空格当成一条正常消息发到引擎里。strip 之后如果长度为 0，直接 continue，本轮对话逻辑完全不会触发。

为什么不在 input 之后立刻做判断？因为 input 拿到的字符串理论上保持原样，你需要对数据做第一轮加工。清洗规则可以设计得更复杂，比如去掉首尾空白、把全角字符转半角、过滤控制字符，但 Hermes 为了演示只保留最核心的 strip。写更复杂的清洗代码时，要注意别误伤了合法输入，比如用户就是想在消息里带几个空格来表达分段。

这里给你一个排查技巧：当你发现某个输入始终匹配不上规则时，先别怀疑匹配逻辑，用print(repr(text))把输入原样打出来。repr 会把换行符、制表符、零宽字符全部显示成转义形式。我处理过很多次类似的问题，用户从网页上复制了一段带不可见字符的文本，肉眼看着是普通的词，程序就是识别不了。一 repr 立刻真相大白，原来单词中间藏了一个不换行空格，你拿普通空格去匹配当然永远命中不了。

3.3 命令分发：先用 if/elif 跑通，再谈架构

命令分发函数是主循环里最重要的分支点：

def dispatch_command(text, ctx): cmd = text.split()[0].lower() if cmd in ("/exit", "/quit"): ctx.should_exit = True return "bye" if cmd == "/help": return "commands: /help /version /exit" if cmd == "/version": return "Hermes 0.1.0" return "unknown command, type /help"

设计上，text.startswith("/")只是粗筛，真正判断命令用的是text.split()[0].lower()。split 能让你在后面接参数，以后做/echo hello world时，第一个单词是命令，剩下的部分是参数。lower 保证命令大小写不敏感，用户输/HELP也能被识别。这不需要用户感知，但会明显降低程序被抱怨“不好用”的概率。

我很清楚这段代码看起来朴素，但它是故意的。日常开发里，很多需求在 v1 阶段根本不需要什么命令注册机制。用字典映射命令名到处理函数，或者干脆用 if/elif，完全够用。真正需要插件化机制的时候，得先看命令数量是否超过十个、是否允许第三方扩展。Hermes 的定位是教学骨架，把 if/elif 的分支逻辑讲透，比一上来就上一个抽象机制更容易理解，后续扩展时再重构，成本也不高。

3.4 对话响应生命周期：上下文怎么流转

一条非命令消息会走进引擎：

class ChatEngine: def __init__(self, cfg): self.cfg = cfg self.rules = load_rules(cfg.get("rules_file")) def respond(self, text, ctx): ctx.append("user", text) reply = self._match(text) ctx.append("assistant", reply) return reply

这里最有意思的是 SessionContext。一次“对话”从来不是孤立的，用户上一句说过什么、你上一句回答过什么，都应该被记住。Hermes 用 context.py 里的 SessionContext 保存整个会话内容：

class SessionContext: def __init__(self, max_history=20): self.history = [] self.max_history = max_history self.should_exit = False def append(self, role, text): self.history.append((role, text)) if len(self.history) > self.max_history: self.history = self.history[-self.max_history:]

历史记录用列表存二元组，每个元素标记是谁说的，user 还是 assistant。为什么连 assistant 的回复也要保存？因为后续如果要生成更聪明的回复，引擎需要知道自己已经回答过什么，不能永远是一问一答的短记忆。max_history 限制列表长度，保证程序连续跑很久，内存也不会无限涨上去。这个裁剪思路你会在很多项目的缓存、队列、滑动窗口设计里反复看到，核心思想都是同一个：只保留最有用的一小段历史。

一次完整响应的生命周期是这样的：主循环收到纯文本，调用 engine.respond；respond 先把用户消息存进 context，然后匹配规则生成 reply，再把 reply 存进 context；返回给主循环之后，主循环把它 print 出来。数据流是清晰的一条线：输入进、上下文更新、输出出。

那如果匹配规则时崩溃了怎么办？Hermes 在引擎里加了一层兜底：

def _match(self, text): try: for pattern, reply in self.rules: if pattern in text: return reply except TypeError: logger.exception("rules format invalid") return "抱歉，规则配置有问题，请检查 rules_file" return "抱歉，我还没学会回答这个问题"

注意这里只捕获 TypeError，说明我只预期了“规则结构不对”这一种问题。把所有异常都吞掉，真正调试时 bug 也会被一条“抱歉”覆盖掉，问题反而更难定位。这是我反复强调的原则：异常要兜底，但兜底不能把错误信息全部憋回去，日志里必须能看到原始异常。

4. 异常兜底与日志埋点：别让一次报错杀死整个对话

4.1 三层异常防线

Hermes 的异常处理大致分三层，每一层管一类问题。第一层在 input 附近，负责处理输入通道的异常，就是前面说的 EOFError 和 KeyboardInterrupt。第二层在业务逻辑内部，比如规则匹配时的 TypeError，引擎自己处理。第三层在 run_repl 的外围，把任何没被捕获到的异常拦截下来，记录日志后继续循环，而不是让整个程序崩溃。

第三层在实际版本里长这样：

try: result = ( dispatch_command(text, ctx) if text.startswith("/") else engine.respond(text, ctx) ) print(result) except Exception: logger.exception("unexpected error while handling: %r", text) print("抱歉，出了点问题，请查看日志。") finally: if ctx.should_exit: break

这里有人会问：except Exception会不会把错误都藏起来？我的答案是：只要用 logger.exception 把完整 traceback 写进日志，错误就没有被藏起来，它只是从“打断程序的 traceback”变成了“日志文件里的 traceback”。用户面对交互式程序时，永远需要的是友好提示；故障的真实细节，是写给开发者看的。这两件事不能混在一起，面向用户的文案和面向开发者的错误详情必须分道扬镳。

这三层防线对应了一个通用的服务意识：交互式程序的核心目标是让会话继续存在。一次内部错误导致整个程序退出，用户之前输入的几十轮内容全丢了，那才是最严重的体验事故。让程序活着，错误进日志，人类根据日志去排查，这套逻辑在服务端程序、消息队列消费者、爬虫调度器里完全一样，越早建立越好。

4.2 日志打在哪几类节点上

日志不是越多越好，但关键节点一定要打。Hermes 的埋点思路可以总结成三句话：启动时打清楚加载了哪个配置，循环里打清楚收到了什么，异常时打清楚炸在什么地方。

启动处的logger.info("Hermes starting, config=%s", args.config)不是废话。程序跑在哪个环境里、加载的是哪一个配置文件，这是排查问题的第一现场信息。我见过太多项目排查半天才发现服务使用的根本不是自己预期的配置，就是因为启动日志里没有输出关键路径。你甚至可以在这条日志里把 Python 版本、系统平台一并打出来，排查环境类问题时非常管用。

循环内部的日志，我建议不要在每条普通消息上都打 INFO，不然日志会被刷屏。但请求和响应可以做摘要，比如 debug 级别打印recv: %r这种格式，调规则匹配时能看清原始输入。异常节点必须用 logger.exception，它会自动带上当前 exception 的完整 traceback，省得手动写 traceback.format_exc()。如果捕获异常后只打印 exception 的 message，你在现场看到的就是一句碎片化的错误描述，没有调用栈，根本定位不了问题。

还有一个容易被忽略的：日志里不要泄露敏感信息。命令行程序如果支持传 token 或密钥，打印参数时要脱敏。我自己的习惯是，打印任何带敏感性的数据之前，先问一句“这段日志真的需要它吗”，不需要就绝不打印，别让“本地日志随便打没关系”的想法害了你。

5. 动手实验：在 Hermes 里加一个 /health 命令

5.1 三步完成一个自定义命令

光看不练，源码阅读等于白读。我建议你照着 Hermes 的骨架，在本地加一个 /health 命令，用来模拟健康检查，返回当前会话的统计信息。这个命令很小，但能帮你理解修改入口逻辑的完整套路。

第一步，在 dispatch_command 里加一个分支。注意命令判断要在 if 链里排好顺序，我一般把 /health 放在 /help 的后面、默认兜底的前面：

if cmd == "/health": return "history=%d, should_exit=%s" % (len(ctx.history), ctx.should_exit)

第二步，把新命令同步到 /help 的返回文本里。这是一个很容易漏掉的地方，你新增了一个命令但 help 里没有写，用户根本不知道可以用它。好的命令行工具一定做到“命令即文档”，或者至少有完整的 help 自述：

if cmd == "/help": return "commands: /help /version /health /exit"

第三步，启动程序，输入 /health，你会看到类似history=4, should_exit=False的输出。这里的 history 是 4，说明你在前面已经聊了两轮，每一轮会产生 user 和 assistant 两条记录。把这三步走完，你对“修改命令分发逻辑”就有了具体的体感，而不是停留在看过我文章的状态。

再进一步，试着做一个带参数的命令，比如/echo hello world，让程序原样输出 hello world。这需要你拆掉text.split()的结果：第一个元素是命令名，剩下的元素是参数，用空格重新拼起来就是 echo 的输出。只要你能独立做出这一步，说明你已经真正理解了命令分发函数的核心逻辑，而不是在复制粘贴。

5.2 源码阅读三板斧：入口、主循环、状态

我把一套可以反复使用的源码阅读方法总结为三板斧：抓入口、抓主循环、抓状态。入口回答“程序从哪开始”，主循环回答“程序的核心流程是什么”，状态回答“数据怎么流转”。在 Hermes 里，入口是 cli.py 的 main，主循环是 runtime.py 的 run_repl，状态是 SessionContext 里的 history 和 should_exit。

这套方法可以迁移到几乎任何服务型项目。拿 Web 框架举例，入口是请求进来后第一个被触发的中间件或路由函数，主循环是请求处理管线，状态是请求上下文和会话。拿消息队列消费者举例，入口是连接和初始化，主循环是不断拉取消息、分发处理的逻辑，状态是消息偏移量和重试计数。你会发现所有长期运行的程序，核心骨架都跑不出这三个问题。

我见过不少朋友读源码喜欢拿一个函数从头读到尾，读一半就跳到另一个文件，最后哪条线都没走完。我自己的习惯是：先把项目跑起来，然后按一次完整的用户请求走一遍主流程，在这条路上只关注入口、循环、状态三样东西，其他细节全部暂时忽略。等到主干逻辑清楚了，再回头补那些分支细节，效率要高得多。

6. 常见问题与踩坑记录

6.1 读源码时最容易卡住的三个点

第一个卡点是钻进细节出不来。比如读到一个函数，又好奇它内部调用的工具函数，顺着工具函数跳到另一个模块，层层嵌套，最后忘了自己最初要解决什么问题。破法很简单：给自己定一条主线，超过三层调用深度就不再追了，主线上的疑问先用注释标记出来，等整条主线走完再回头补课。

第二个卡点是忽略异常分支。很多人读代码只看正常路径，把 try/except 整段跳过，结果漏掉了大半个业务逻辑。实际上异常分支往往藏着关键设计：哪些错误是可恢复的，哪些错误会直接把进程退出，错误信息如何组织，这些信息对理解系统的可靠性边界非常重要。我读代码时看到 try 会格外慢下来，因为这里往往是最体现经验的地方。

第三个卡点是不运行只看代码。静态阅读的效率和准确率都远低于运行调试。花三分钟跑起来，打印两个关键变量，抵得上盯着代码猜半小时。我读任何陌生项目时都会先想办法把它跑起来，然后在入口和主循环里加临时日志，让程序的真实行为替我验证理解，而不是靠大脑模拟执行。

6.2 Hermes 主循环相关的典型问题

我在维护这个框架时实际碰到过三个比较典型的问题。第一个是键盘输入以 EOF 结束时，没捕获 EOFError，程序直接抛EOFError: EOF when reading a line就退出了，用户完全看不懂。捕获后打印一个空行再退出，体验立刻好起来。这个处理在很多 CLI 工具里都能看到，它属于“输入通道的最后一公里”，不做会显得很糙。

第二个问题是未知命令静默失败。早期的 dispatch_command 对未知命令不返回任何提示，用户打了个拼错的命令，程序毫无反应，看起来像卡死了。后来在兜底分支里明确返回"unknown command, type /help"，用户立刻知道自己做错了什么。这个经验同样适用于 API 设计：失败时永远返回可理解的失败原因，不要用沉默代替错误。

第三个问题比较隐蔽：配置文件缺失时，程序用了默认配置但用户完全不知情。比如执行hermes -c nonexist.yaml，程序照样启动，对话也正常，但机器人加载的不是用户预期的那套规则。排查了半天才发现配置文件根本没读到。给 load_config 加一行警告日志就能解决：

except FileNotFoundError: logger.warning("config file %s not found, use defaults", path)

这个问题的本质是信息不透明。很多故障不是逻辑复杂，而是用户在没有预警的情况下做了错误判断。把关键路径上的提示打出来，让人知道自己处在什么状态，就是真正的排障效率。

7. 最后再聊点工程化：主循环怎么测试

7.1 把输入输出抽成依赖，让主循环可测

如果你准备在自己项目里复用这套骨架，我建议顺便为主循环补上测试。直接对 run_repl 写测试有一个难点：它内部调用 input 和 print，这两个都是阻塞、读写终端的函数，自动化测试没法模拟用户输入。

解决思路是把输入输出变成可注入的依赖。修改后的核心逻辑可以抽成：

def run_repl(cfg, reader=input, writer=print): ... while True: try: raw = reader() except EOFError: break ... writer(result)

测试里，reader 可以是一个生成器，吐出几条预设输入：

def fake_reader(): yield "hello" yield "/version" yield "/exit" def test_repl_exit_normally(cfg): output = [] run_repl(cfg, reader=fake_reader().__next__, writer=output.append) assert "Hermes 0.1.0" in "\n".join(output)

reader 和 writer 作为默认参数传进来，生产环境里不传也能正常工作，测试环境传入替代品，就摆脱了对真实终端的依赖。这个思路是依赖注入的简化版，一点都不高深，但会让代码的可测性提高一个档次。

如果你还想更进一步，把“一次输入产生一次输出”的核心逻辑单独抽成handle_line(text, ctx)函数，然后只对这个函数做单元测试。主循环只负责不断调用 handle_line，业务逻辑与 I/O 完全分离。我实际用下来，这个结构让回归问题少了很多，改业务逻辑时不需要再人工跑到终端里反复敲命令验证。

7.2 复刻这套骨架后的两个扩展点

最后分享两个我自己在后续版本中真实加过的功能，它们的实现都建立在入口和主循环这两个骨架之上。第一个是--one-shot参数：指定后，主循环只处理一次输入就退出，方便脚本化调用。你只需要在 parse_args 里加一个 store_true 参数，然后把它传进 run_repl，在处理完一行之后检查这个标志并决定要不要 break，改动非常小。

第二个是启动时从文件恢复历史记录。做法是把 SessionContext 增加一个load(path)类方法，在创建 context 之后、进入主循环之前把已有的历史消息读进来。这个功能的价值在于，用户重启程序后不会完全失忆，上一次对话的语境还能衔接上。你需要额外处理文件不存在、格式不合法、文件过大等边界情况，正好用得上前面讲的异常兜底和日志埋点技巧。

这两个扩展都不是什么惊天动地的功能，但把它们加到 Hermes 的过程，会让你对“入口和主循环是脚手架，业务逻辑挂上去”这句话有更深的体会。源码阅读是长跑，一篇吃透一条主线，比囫囵吞枣读完一个仓库有用得多。下一轮如果你感兴趣，可以沿着 chat engine 继续往前读，看看规则匹配、插件加载这些内部机制是怎么挂到这个骨架上的。