前段时间我启动了一个新项目，代号 CodeGuard Tutor。简单说，这是一个面向编程初学者的代码质量分析与讲解工具：用户扔进来一段代码，它不单单告诉你哪里有问题，还会用自然语言解释“为什么这是问题”“背后涉及什么概念”“正确的写法长什么样”。这篇文章是这个项目博客的第一篇，我打算把启动阶段的想法、技术选型、整体架构和路线图完整梳理一遍，既是给项目留个底稿，也是给打算做类似工具的同学一个参考。
1. 项目缘起与核心问题定位
1.1 为什么会有 CodeGuard Tutor
做这个项目的直接诱因，是我在带几个新人写代码时反复遇到同一个场景：他们写完一段能跑的代码，但代码里充满了隐性问题——函数命名一塌糊涂、嵌套深度夸张、变量作用域混乱、边界条件缺失。你让他改，他能改，但不知道为什么改，下次照样犯。市面上的静态检查工具够多了，ESLint、Pylint、RuboCop，哪个都能列出一堆 warnings，但它们的输出是面向“已经会写代码的人”的：规则名、行号、错误码，像天书一样。初学者看到W0611: unused import，第一反应是“import 了没用到底会怎样”，而不是“我该怎么组织这段逻辑”。
这就是 CodeGuard Tutor 要解决的问题：把静态分析的结果，翻译成人话。它不做深度的语义理解和自动修复，那需要大模型甚至专门研究的支撑，成本高、反馈慢。我更需要一个轻量的、能嵌入日常学习流程的工具，帮初学者建立“代码质量”这件事的直觉。
另一个触发点是，我在网上看到不少编程教学类内容，几乎全在讲“怎么写对”，很少有人讲“写完之后怎么审视自己的代码”。对初学者来说，“能跑”和“写好”之间存在一条巨大的鸿沟，而现有的工具链里没有一个专门帮他们跨过这道坎的。CodeGuard Tutor 的定位，就是做这道桥。
1.2 项目解决的痛点与边界
给项目画边界很重要，否则很容易失控。CodeGuard Tutor 的目标用户设定得很明确：刚学会基础语法、正在刷题或写小项目、但缺少代码审查经验的入门级开发者。在这个前提下，我提炼出三个核心痛点：
第一，看不懂静态检查工具的输出。这是最普遍的障碍，错误信息的措辞对新手极不友好。第二，不知道自己写的代码“不够好”。没有人在旁边提点的话，新手很难意识到变量名叫a、b和函数写三百行有什么问题。第三，缺少“以点带面”的学习路径。一个 lint 错误背后往往关联着语言特性、编程范式、工程规范，新手需要的不是一条报错，而是一段可以放进上下文里去理解的知识。
边界也一并划清楚了：不做自动修复，不追求分析速度，不覆盖大型工程级代码，不试图替代编译器的类型检查。这些功能要么已经有成熟方案，要么需要大量资源，放进第一个版本只会拖慢节奏。我的原则是：先把“解释清楚”这一件事做透。
2. 整体功能设计与架构拆解
2.1 核心能力与交互流程设计
CodeGuard Tutor 的第一版核心功能，我把它收敛成一条主链路：输入代码 → 静态分析 → 问题筛选 → 讲解生成 → 渲染输出。
用户可以在命令行工具里粘贴一段代码，也可以直接指定文件路径。系统会先做一次语法基础校验，语法都过不了的代码会直接提示“编译失败”，因为这种情况下分析代码风格没有意义，得先用基础信息引导用户检查语法错误。
语法通过后，分析引擎会对代码做两类扫描：一类是结构性问题，比如未使用的变量、重复的代码块、过深的嵌套；另一类是风格与规范问题，比如命名是否符合惯例、函数长度是否异常、是否存在魔法数字。这两类问题不是简单合并输出，而是按照“学习价值”排序：与逻辑正确性相关的排前面，纯粹风格偏好的排后面，因为对初学者来说，先理解逻辑问题，再修正风格问题，学习曲线最平滑。
讲解生成是核心模块。每一类问题都会从预置的知识库中匹配讲解模板，模板里包含四个要素：问题是什么、为什么这个问题值得改、背后的编程原则、可运行的改进示例。这一步要严格控制生成成本，任何动态调用模型生成的方案我都暂时搁置了，第一版全走静态模板映射，保证每次分析的响应时间在百毫秒级。
2.2 架构设计的取舍逻辑
整个系统的架构分为四层，我在设计时坚持了“每层只做一件事”的切割原则：
输入层负责接收用户的代码文本和参数选项，做基础的数据清洗，比如统一换行符、去掉 BOM 头、识别代码语言类型。分析层负责调用具体的静态检查引擎，这一层的设计目标是可插拔——后续要支持新语言，只需要实现新的分析器接口。讲解层是 CodeGuard Tutor 区别于普通 linter 的关键，它拿到分析层输出的问题列表，结合知识库生成人性化解释。输出层根据用户选择的格式渲染结果，默认是纯文本，也预留了 Markdown 和 JSON 的导出能力。
这里有一个我认为做得对的决定：分析层和讲解层强制解耦。这意味着分析结果使用一套中间表示（即“问题对象”）来传递，讲解层只依赖这套中间表示，完全不关心问题是哪个检查器发现的。后续即使把某个检查器整个替换掉，讲解层的代码一行都不用改。中间表示的数据结构大概是这样的：
@dataclass class CodeIssue: rule_id: str # 规则ID，如 "N804" 或 "STYLE-NESTED" severity: str # "error" | "warning" | "suggestion" line: int # 起始行号 end_line: int # 结束行号 message: str # 机器可读的问题摘要 detail: dict # 额外上下文，如变量名、函数名等这个东西在整个架构里的地位，就像数据库的表结构之于后端服务，定义清楚了，前后端才能并行推进。
2.3 为什么静态模板讲解够用
很多朋友问我，为什么不用大模型来做讲解生成？模型输出更灵活、覆盖面更广，不是更“智能”吗？我的判断是：在项目启动阶段，确定性比智能性更重要。
第一，静态检查发现的问题是有限集合。再大的规则库也就几百条，为这几百条规则写好讲解模板，是一次性的成本，但换来的是 100% 一致的输出质量。不会有哪次回答突然跑偏、解释错概念，这对教学工具来说至关重要。学习工具最怕的不是功能少，而是讲错。第二，模板讲解的可维护性极强。发现某个讲解不准确，改 Markdown 模板文件就能修复，不需要重新训练模型、不需要调超参数。第三，性能稳定可控。后续即使做成在线服务，也能在很小的预算内支撑大量请求。
当然，模板讲解也有明显的天花板：它无法应对规则库之外的新颖问题。但这正是后续演进的入口——架构上我已经预留了“动态讲解调度器”的位置，当预置模板找不到匹配项时，可以降级到模型生成。第一阶段不做，但设计上留好口子。
3. 技术选型与实现方案
3.1 语言与核心库的选择
主语言选 Python 没有太多悬念。原因有三：第一，生态里有现成的静态分析基础设施，比如ast标准库，以及flake8、pylint底层的检查插件体系，都是 Python 写的，直接借鉴的成本最低。第二，CodeGuard Tutor 的定位是编程学习辅助工具，面向的用户大概率接触过 Python，选择它做主力语言有利于后续开放规则贡献接口，降低社区参与门槛。第三，我对 Python 的心智负担最低，能把精力集中在业务逻辑上。
分析引擎方面，第一版决定基于 Python 标准库的ast模块自研检查规则，而不是直接封装 flake8。直接封装看起来是捷径，但 flake8 的输出格式是给“人快速浏览”用的，并不适合转译为讲解内容——它丢掉了太多上下文，比如嵌套的父节点信息、作用域链信息。自研规则虽然要多写一些代码，但能在发现问题时保留完整的语法树信息，这对讲解层来说是金矿。
CLI 框架选了 Typer，理由非常朴素：它基于 Click 但提供了类型提示补全，能少写很多参数解析模板代码，而且内建--help文档生成得漂亮，对命令行新手也友好。测试框架用 Pytest，配合几组真实代码样本做回归测试，保证每个检查规则的讲解不跑偏。
3.2 讲解知识库的数据结构设计
讲解知识库不是一堆杂乱的 Markdown 文件，我在设计时就定了一套结构化 Schema，每个规则对应一个 YAML 文件，包含元信息和多语言讲解段落：
rule_id: "STYLE-NESTED" title: "嵌套层级过深" severity: "warning" tags: ["复杂度", "可读性"] explanation: | 你的代码嵌套了 {depth} 层，这意味着读完这段代码需要记住 {depth} 层上下文。 context: | `continue` 和 `break` 可以用来提前退出循环，从而减少一层嵌套。 good_example: | for item in items: if item.eligible: process(item) better_example: | for item in items: if not item.eligible: continue process(item)这里面的{depth}是占位符，运行时从CodeIssue.detail里读取并动态填充。之所以用 YAML 不用 JSON，纯粹是因为 YAML 对多行文本和注释的支持更好，写解释文案时的体验更舒服。讲解文案的写作规范我另有一套要求：每篇不超过 200 字，必须包含“问题展现→影响分析→改进步骤”三段逻辑，避免说教口吻。这块内容的打磨是整个项目中耗时最长但用户感知最明显的部分。
3.3 命令行交互与输出格式设计
第一版以命令行工具为唯一入口，理由很实际：开发成本低、测试方便、自动化友好。但交互上我特意做了设计，让它不像传统 CLI 那样冷冰冰，而是带一点“辅导感”。
默认输出是分段式文本：先给一句总体的代码健康度评价，比如“整体不错，但有 3 个值得关注的逻辑问题、2 个风格建议”；然后按严重程度逐条列出问题，每条包含行号、标题和详细讲解；最后附一句“下一步建议”，引导用户尝试修复后再跑一次。我刻意避免了终端彩色高亮，因为很多初学者用的编辑器终端不支持 ANSI 颜色，输出会变成一堆乱码，得不偿失。
同时预留了--format json参数，这是为后续做 Web 端和编辑器插件做的伏笔。输出层和核心逻辑分离，意味着以后加图形界面的时候，不用改动任何分析代码。
4. 路线图规划与里程碑设定
4.1 版本规划：MVP 先行，迭代驱动
CodeGuard Tutor 被划分为四个阶段，第一阶段的 MVP 被压缩到最小可用的程度：支持 Python 单一语言，内置 20 条高质量检查规则，讲解知识库覆盖这些规则，提供命令行交互和 JSON 输出。这 20 条规则不是随机的，我按照“学习价值/实现成本”的比值精挑过，覆盖四类：未使用变量与导入、函数复杂度、命名规范、常见反模式。
第二个阶段扩展规则库到 80 条以上，增加配置化能力，用户可以按需开关规则和自定义严重级别。同时会加入“批量扫描目录”的能力，让用户能够对一整个练习项目做质量总览。第三个阶段是 Web 端和分享能力，用户可以上传代码生成一个可分享的质量报告链接，这是教学场景里的高频需求——老师说“你把代码传到这个链接我看一下”，比让学生贴文本高效得多。
第四阶段才是真正拉开差距的地方：规则贡献 SDK。我计划开源检查规则的编写接口，让有经验的开发者能编写自定义规则并共享给社区。这一阶段能不能做成，直接决定 CodeGuard Tutor 是小众自嗨工具还是能成长为社区驱动的学习基础设施。
4.2 每个阶段的验收标准与风险控制
每个阶段我都设定了明确的退出条件，不满足就不进入下一阶段。第一阶段要求：20 条规则全部有对应测试用例，对公开代码样本的误报率低于 5%，解决方案文档涵盖安装、升级、排错三个场景。第二阶段要求：至少 10 名外部测试用户连续使用一周并提交反馈，所有规则的讲解都根据反馈迭代过一轮。第三阶段要求：首位非作者用户能独立完成“上传代码 → 获得报告 → 分享链接”的完整流程，且 Web 服务在低配服务器上的 P95 响应时间低于 2 秒。
风险控制方面，最大的风险是规则讲解质量参差不齐导致口碑崩坏。对策是建立“规则上架审核机制”：任何新规则在被合入默认规则集之前，必须经过三关——自动测试通过、至少两名核心维护者审阅讲解文案、在 10 个样本代码上人工核对输出合理。这个机制从第一阶段的内部开发时就开始执行了，因为在项目早期养成的质量惯性，会决定整个项目的天花板。
4.3 社区共建与开源策略
CodeGuard Tutor 从一开始就确定走开源路线。许可证选 MIT，理由是门槛最低、最利于传播，教学工具不应该被许可证阻碍了触达。代码托管、文档站和示例库分开管理，示例库里的代码全部是真实学习场景中收集的问题代码（脱敏后），既能当测试用例，也能当教学案例库。
关于社区共建，我有一半乐观一半谨慎。乐观的是，这类教学工具的需求真实存在，身边已经有不少人主动表示想参与规则编写；谨慎的是，开源项目的通病是“贡献者三分钟热度”，能坚持写文档、修 issue 的人少之又少。我的应对思路是：把贡献门槛降到极低。规则文件只需要写 YAML 和几行 Python，不涉及复杂架构，配合一份细致的贡献指南，让第一次参与的人在一个小时内能完成规则原型。
5. 常见问题与避坑指南
5.1 静态分析中常见的误报场景与对策
做这个项目之后我才深刻体会到，静态分析最大的敌人不是技术复杂，而是误报。误报对初学者信心的打击几乎是致命的：用户写的代码没有问题，工具却提示“存在风险”，他以后的每一条报错都会持怀疑态度。我踩过的坑主要有三类。
第一类是“过度泛化”导致的误报。比如检测函数过长的规则，设了一个 50 行阈值，但有些函数天生就是长一点更合理，比如数据初始化函数。对策是不把这类规则默认设为 error，而是降级为 suggestion，并在讲解文案里明确写“大型初始化函数可以接受，也可以将具体数值抽成配置，以减少单个函数长度”。
第二类是“上下文盲区”导致的误报。例如检测未使用变量，普通作用域里的未使用变量是问题，但异常处理里的except Exception as e:中的e虽然没用到，却是惯例写法，这时候直接提示“未使用变量”就不合适。对策是在规则实现里增加上下文判断，对某些模式加白名单。
第三类是“跨语言习惯”带来的误报。用 Python 的静态分析逻辑去检查最终会被编译成另一种语言风格的代码，必然会出问题。这个目前只能靠用户手动配置关闭不适用的规则，也是我坚持要做规则开关配置的原因。
5.2 讲解文案写作的具体心得
讲解文案写得好不好，直接决定这个工具到底是一个“会说话的 linter”还是“一个真的在教人的老师”。我写了上百条文案之后，总结了四个经验。
第一，解释问题时必须先说“这是什么”，再说“为什么重要”，最后说“怎么改”。顺序不能乱，初学者看到一条错误时最急迫的诉求是先知道“我犯了什么错”，你上来就讲原理，他会觉得你这工具在背课文。第二，每篇讲解只聚焦一个问题。代码里常见的反模式往往是多个问题叠加在一起，但在讲解里必须拆开，一次只讲一件事，最多附一条“相关建议”的引用。第三，例子必须足够简化和完整。简化意味着不能引入超出问题本身的新概念；完整意味着代码片段可以直接复制运行看效果，而不是一个模糊的伪代码残片。第四，语气要克制。宁可平淡，不要煽动。不写“你真是太棒了”“这是个绝妙的问题”这类无信息量的话，客观描述就好。
5.3 项目启动阶段容易踩的管理坑
除了技术本身，项目启动阶段的管理坑也值得说说。第一个坑是过早追求功能数量。我一开始列了四十多条想要支持的规则清单，头脑一热想一口吃成胖子。后来冷静下来，把清单砍到 20 条，并确定“每一条规则都要配讲解、配测试、配示例”的完成标准。事实证明这个决定太正确了，四十条规则全部做到这标准，恐怕到现在还在做第一个版本。
第二个坑是文档滞后。做工具的人容易陷入“代码写出来就完事”的心态，但工具的价值在于被使用，而使用的门槛在于文档。我现在给自己定了规矩：任何一个功能合入主分支的当周，必须更新对应的用户文档和开发文档，没有文档的代码不允许合入，这条纪律我会一直保持下去。
第三个坑是忽略了“卸载体验”。很多开发者重视 onboarding（新用户上手体验），但很少有人重视用户想卸载工具时的体验。CodeGuard Tutor 的配置文件写进了用户目录，卸载时应该提供一条干净的清理命令，这些细节看似无关紧要，但做工具的人是否尊重用户，往往就体现在这些地方。拿这个标准来要求自己，项目才会越来越健康。
写在最后的一点体会
从 CodeGuard Tutor 的构思到写这篇博客，前后大概一个月。这段时间我最大的感悟是：有些项目看起来小，但牵扯到的决策密度一点不比大工程少。单是“讲解模板到底怎么写才不像说教”这一个问题，我就推翻了三版方案。做教学类工具最大的魔力在于,你在教别人的同时，也在被迫重新审视自己到底懂不懂那些“理所当然”的规则。每次我写“为什么这是最佳实践”时，其实都在逼自己回答一个更根本的问题——我真的理解了吗，还是只是随大流地觉得该这样写？
CodeGuard Tutor 现在还在很早期的阶段，后面有大量代码要写、规则要磨、文案要改，但方向已经定了，第一天踩过的坑和做出的取舍也记录在这里了。后续我会按里程碑持续同步进展，也欢迎对编程教育、静态分析、开发者工具感兴趣的朋友一起交流。如果你有想加的检查规则，或者对哪条讲解文案有不同意见，直接提出来，这个项目希望保持听得进话的开放姿态。
