README_CN.md

July 29, 2026 · View on GitHub

CodeABC — 不用学编程也能读懂代码

Python License: MIT CI

快速开始 · 工作原理 · 功能 · English

不用学编程，也能读懂代码。 一款面向零编程基础用户的 AI 代码阅读工具。

Cursor/VS Code 是给程序员用的瑞士军刀，码上懂是给普通人用的放大镜 -- 让你像读文章一样读代码，像批注文章一样理解代码。

解决什么问题

越来越多非程序员需要和代码打交道：

你是谁你的痛点
文科研究生导师给了 Python 数据分析脚本，要改参数但看不懂代码
产品经理想知道开发写了什么，但看代码像看天书
创业者外包交付了代码，无法判断质量
数据分析师同事给了个 Python 脚本让你跑，不知道从哪开始
编程入门者在学 Python，但课程代码看不懂

AI 已经能完美解释代码了，缺的是一款把这个能力包装成好用体验的产品。

工作原理

CodeABC 架构

拖入一个文件夹或粘贴 GitHub 链接。码上懂扫描项目（跳过构建产物、缓存和疑似密钥的文件），先生成无需 API key 的即时确定性图谱——阅读路线图、核心模块排序、测试覆盖视图等，再在上面叠加 AI 解释：大白话项目说明书、逐行悬停批注、问答框。一切都在双语浏览器界面里呈现。

功能

项目说明书

拖入项目文件夹，或粘贴 GitHub 链接。码上懂自动扫描文件，生成一份大白话的"项目说明书"：

  • 这个项目是什么？ 一句话概括，不用任何术语
  • 文件指南 每个文件用大白话解释作用，按重要性排序
  • 阅读地图 不等 AI 返回，先告诉你从哪个文件开始、接着看什么
  • 怎么跑起来 一步步的操作指南
  • 快捷提示 "如果你只想改配置，直接去 config.py"

悬停批注

点击任何文件进入代码视图。鼠标悬停在代码上，就能看到中文批注：

  • 粒度细：每 1-3 行一个批注，不是笼统地说"这一段在做什么"
  • 说人话：不用任何编程术语，用日常生活类比解释（比如 for 循环 = 点名）
  • 有缓存：批注会存在本地，再次查看同一个文件不用等

术语词典

每个文件视图都会列出这个文件里真正出现过的编程术语：async、装饰器、闭包、中间件、正则等等几十个。把鼠标移到术语上，就能看到一句大白话解释，尽量用日常生活的类比来讲。它是确定性算出来的（不调 LLM、不需要 API Key），所以随时都在、立刻就有。

自然语言改写

用大白话描述你想改什么，比如"把茅台换成比亚迪""把超时从 3600 改成 600"，码上懂会给出选中那段代码的改写建议，只动你要求的地方。它永远不会写你的文件，结果交给你自己看过再决定要不要用。

问答模式

在文件里选中任意一段（不选就是针对整个文件），用大白话问一句"这段是干嘛的？""为什么这里写 0.05？"。码上懂会用同样耐心、少术语的语气回答，而且只依据你指给它看的那段代码，不瞎编。答案有缓存，同样的问题再问一次不花钱。

中英双语界面

整个界面用顶部一个开关在中文和英文之间切换，你的选择会被记住，第一次访问还会跟着浏览器语言走。（说明书、批注这类 AI 生成的内容跟随提问语言；界面文字本身是完整翻译过的。）

更干净的项目扫描

码上懂会在调用 LLM 前跳过构建产物、包缓存、压缩 bundle、生成出来的前端 chunk，以及仓库 .gitignore 已经忽略的路径。它也会跳过真实 .env、凭证 JSON、API key 笔记、私钥等敏感文件，但保留 .env.example 这种安全示例。这样项目说明书会聚焦源代码，不会被 dist/、node_modules、本地临时文件、一整行的压缩 JavaScript 或私人凭证干扰。

不等 AI，先找到入口

项目上传完成后，码上懂会先根据 README、程序入口、依赖清单、核心源码目录和测试，生成一条确定性的阅读路线。即使还没配置 API Key，也能立刻知道第一步该看哪里，不会面对几百个文件无从下手。

一眼看出核心模块

码上懂会从扫描到的文件里建一张轻量的导入关系图，按"被多少个文件引用"（fan-in）排序。被引用最多的文件，往往就是真正放核心逻辑的地方：公共工具、数据模型、核心服务。这些文件会和阅读地图并排显示成"核心模块"，并标出有多少个文件依赖它。它能解析 Python 导入（含相对导入和包导入）和 JavaScript/TypeScript 导入（相对路径，自动补全后缀和 index 文件），第三方库和标准库的导入会被忽略，因为它们指向的不是项目里的文件。和阅读地图一样，这步不调用 LLM，没配 API Key 也能用。

这份代码有没有测试？

评估一份你没写过的代码（比如外包来的）时，一个直接又有用的问题是：它到底有没有测试？码上懂会把每个源文件和测试它的测试文件配对，既看 import 关系，也认 test_scanner.py / scanner.test.ts 这种常规命名，然后给出有测试覆盖的文件比例。更有用的是，它会把没有测试的文件按"被多少个文件依赖"排序：一个半个项目都在 import、却没有任何测试的文件，正是悄悄出 bug 时影响最广的地方，所以它排在"最该先补测试"清单的最上面，并附一句大白话说明为什么。绿色进度条给你一眼能看的数字，清单告诉你该往哪看。和别的地图一样，这步是确定性的，不需要 API Key。

这个文件到底是干嘛的？

conftest.py、serializers.py、__init__.py、urls.py、Dockerfile——这些名字对程序员是常识，对其他人就是一堵墙。打开任意文件，码上懂会在顶部放一句大白话，告诉你这种名字的文件通常是干嘛的：__init__.py 只是标记某个文件夹是一个包、经常是空的；conftest.py 放的是共享测试配置、不是项目功能代码；migrations/ 里的文件是自动生成的数据库变更、一般不用读。它只看文件名，从最具体的约定一路退到光看扩展名来匹配，所以瞬间出结果、不需要 API Key，AI 还没开口它就已经在了。

它会连到外部哪些服务？

在信任一份你没写过的脚本之前，你通常想知道它会往外联系什么：用的哪家 AI、哪朵云、哪个数据库，会不会动钱。码上懂会读代码里的 import 和域名，列出它依赖的外部服务——OpenAI、AWS、一个 Postgres 数据库、一次 Stripe 支付调用——每个都配一句大白话，说明这个依赖意味着什么、你为什么可能要在意。不需要 API Key。

哪里把错误悄悄吞掉了？

一份代码里最危险的一行，往往是悄悄把问题藏起来的那行：一个 except: 把所有异常一网打尽、一个空的 catch {} 把错误直接扔掉、一个失败被记了个日志然后就当没事发生。对不懂代码的人这些完全看不见，对维护者这些正是 bug 藏身的地方。码上懂会把这些"静默失败"的位置标出来，用大白话讲清楚为什么"程序假装什么都没发生地继续跑"有时比当场报错崩掉更糟。

哪些函数根本没有人在用？

"没人 import 的文件"好找，更细一层的问题是：那些正常被用到的文件里，有没有谁写了却没人调用的函数和类？一个当年为某个调用方写的公开函数，调用方没了，函数还在，每个读代码的人都得白白把它装进脑子，重构时又因为它没有测试覆盖而最先坏掉。码上懂会把"名字在项目里其他地方一次都没出现过"的顶层函数、类和导出符号挑出来，并把判断依据写清楚。带装饰器的定义（路由、fixture、命令）会特意跳过，报告也明说自己是"待人工复核的候选"而不是判决书，因为字符串引用和动态 import 是任何文本扫描都看不见的。

哪些文件最该补说明？

不是每个文件都需要注释，但那些被很多别的文件依赖、自己却几乎没有任何说明的文件，是最让新人头疼的。码上懂会按"有多核心"对比"有多缺说明"给每个文件打分，挑出那几个"只要有人在开头写几句话就最能帮到大家"的文件。它既是写文档的提示，也是读代码的向导：这几个文件通常正是最值得先搞懂的。

技术栈

层选择理由
前端React 19 + Vite + TailwindCSS 4快速开发，纯交互应用不需要 SSR
代码高亮ShikiVS Code 级别的语法高亮质量
状态管理Zustand轻量好用
后端FastAPI + uvicorn异步 Python，适合流式返回 LLM 结果
LLMlitellm多模型支持（OpenAI、Claude、DeepSeek、Kimi 等）
缓存SQLite简单够用

快速开始

前提条件

  • Python 3.10+
  • Node.js 18+
  • 一个 LLM API Key（OpenAI、Claude、DeepSeek 或其他 litellm 支持的）

启动后端

cd CodeABC
python3 -m venv .venv && source .venv/bin/activate
pip install -e .

# 设置 API Key
export OPENAI_API_KEY=<OPENAI_API_KEY>
# 或者用其他服务商：
# export ANTHROPIC_API_KEY=<ANTHROPIC_API_KEY>
# export DEEPSEEK_API_KEY=xxx

# 可选：修改默认模型
# export CODEABC_MODEL=deepseek/deepseek-chat

uvicorn backend.app:app --reload

启动前端

cd CodeABC/frontend
npm install
npm run dev

打开浏览器访问 http://localhost:5173

桌面端（Tauri）

同一套界面通过 Tauri 打包成原生桌面窗口——一层很薄的 Rust 外壳包住 Web 前端，没有 Electron 那么臃肿。而且开箱即用：应用把 FastAPI 后端作为 sidecar 一起打包、启动时自动拉起，不用手动起任何东西。构建需要先装好 Rust 工具链。

# 1. 把后端打包成 sidecar 二进制（用只装了项目依赖的干净 venv + pyinstaller，
#    在臃肿环境里打包会产出超大文件）
pip install -e . pyinstaller
python scripts/build_desktop_sidecar.py

# 2. 构建桌面应用（会把这个 sidecar 一起打进去）
cd frontend
npm install
npm run tauri:build    # 安装包在 src-tauri/target/release/bundle/ 下

发布版应用启动时会在 127.0.0.1:8000 拉起后端、退出时关掉它。开发时自己起后端（uvicorn backend.app:app --reload）再用热重载窗口即可——npm run tauri:dev 不会启动 sidecar：

npm run tauri:dev

使用方式

  1. 本地文件夹：把项目文件夹拖到上传区域，或点击选择
  2. GitHub 仓库：粘贴链接如 https://github.com/user/repo，点击"分析"
  3. 浏览生成的项目说明书
  4. 点击任何文件，鼠标悬停查看批注

API Key 配置

码上懂支持两种模式：

  • 免费模式（默认）：每天 20 次调用
  • 自带 Key 模式：点击右上角齿轮图标，填入你自己的 API Key，无限使用。Key 只存在浏览器本地，不会上传。

路线图

已交付

阅读体验已经完整跑通：大白话项目说明书、悬停批注、术语词典、自然语言编辑、片段问答，全部在双语界面里，一条命令就能启动（也可以打包成 Tauri 原生桌面应用）。在这之上是十几张无需 API Key 的确定性图谱：阅读路线、核心模块排序、全项目定义索引（查任何名字，跳到它的定义处、并列出所有用到它的地方）、测试覆盖、Git 历史热点与代码归属、技术债标记、环境变量清单、程序入口、命令行命令、数据模型形状（dataclass / pydantic / TypedDict / NamedTuple 及其字段类型）、写死成全大写常量的可调设置（重试次数、超时、默认模型、开关——不读代码也能改的那些值）、会自己定时跑的自动化任务（cron 定时、APScheduler / Celery beat 定时器、GitHub Actions 定时与 JS 定时器——不用你按按钮就会发生的那些，常见 cron 表达式还翻成大白话）、提交代码后会自动跑的检查（push 或开 PR 时，GitHub Actions、pre-commit、GitLab CI、CircleCI、Jenkins 等里配的代码规范、格式、类型、测试、覆盖率、安全、构建这些关卡，每一道都翻成大白话，红叉不再吓人）、这个项目是怎么发版本的（当前版本号写在哪、用的哪种版本号规则、有没有更新日志、一推 tag 或发 release 时会不会自动发布到 PyPI / npm / GitHub Release）、怎么给这个项目贡献代码（先读哪个文件、有没有 PR 和 issue 模板、提交要不要带 Signed-off-by/DCO、要不要按约定式提交、要不要签 CLA、改动要不要 CODEOWNERS 点头——这些流程没对上，第一次 PR 往往还没被看代码就被打回）、外部依赖、错误被吞点、最缺文档的文件，还有逻辑复杂度。这些还能离线导出：所有图谱可以拼成一份 codemap.md，或者一份自包含的 HTML 报告，直接发给不懂技术的同事或老板——不用起服务、不用 API Key、不从网上拉任何东西。分析结果还会存进一个小的本地项目库（GET /api/projects），可以列出以前分析过的项目、重开其中一个，不用记住它的 id、也不用再扫一遍。

后续规划

按优先级大致排了一下接下来想做的方向：

  • PR 阅读模式：粘贴一个 PR 链接，用大白话讲清楚这次改动改了什么、为什么可能重要、先看哪几个文件。这是被问得最多的扩展，也最贴合现有的批注引擎。
  • 整项目对话：现在的问答只盯着单个文件或片段，下一步是让对话能同时调动项目的各张图谱和源码，同时如实交代它到底读了哪些内容。
  • 批注覆盖更多语言：悬停批注目前优先 Python，把 JavaScript/TypeScript 和 Go 做到同样的深度，主要是 prompt 和分词的工作量。

有想法，或者有让码上懂犯迷糊的代码库？欢迎开 issue，这份路线图就是跟着真实非程序员卡住的地方走的。

贡献

欢迎提 Issue 和 PR。项目处于早期开发阶段。

相关项目

CodeABC 是我做的几个跟代码打交道的工具之一，下面几个也许你会喜欢：

  • CoreCoder — 想搞懂一个 coding agent 到底怎么运作？把整套约 1000 行引擎从头读到尾，而不是当黑箱。
  • RepoWiki — 被丢进一个陌生代码库？它给你一份带「从哪读起」路径的 wiki，一个可自托管的 DeepWiki 替代。
  • FindJobs-Agent — 别再手动刷招聘网站：它按你的简历给岗位排序，还能跑模拟面试。
  • ContractGuard — 签字前先把有风险的条款挑出来：它读合同、标出危险点。
  • GitSense — 想给开源做贡献？它帮你找到值得做的 issue，还能估你的 PR 多大概率被合。

许可证

MIT