项目定位

项目名：PyExplain / Python代码解释器

一句话介绍

一个专门给 Python 初学者使用的代码解释工具。用户输入基础 Python 代码后，程序按行输出“中文解释”和“执行含义”，帮助小白看懂代码在做什么。

一、MVP目标

第一版只验证三件事：

小白愿不愿意把代码贴进来查看解释
基础规则解释能不能帮助他们理解代码
“逐行解释 + 总体说明”这种形式是否足够有用

所以第一版不要追求“解释所有 Python”，而是只做：

基础语法的可读化解释。

二、目标用户

核心用户

Python 初学者
看得懂一点语法但读不懂代码的新手
培训班学员
刚学到 if、for、print、input 的小白

核心痛点

每个单词都认识一点，但合起来不知道代码在干嘛
看教程时能抄，离开教程就不会读
循环、条件判断、变量赋值一混在一起就乱
代码报错不一定多，但“看不懂”本身就很劝退

三、产品核心思路

这个项目不是做真正的 Python 运行器，也不是做 AI 助手，而是：

做一个“基础代码翻译器”

也就是把这些内容翻译给用户：

这行代码是什么类型
这行代码在做什么
这个变量代表什么
这段代码整体目的是什么

例如：

输入：

name = input("请输入姓名")
print(name)

输出：

第1行：让用户输入内容，并把输入结果保存到变量 name
第2行：把变量 name 中保存的内容打印出来
这段代码整体作用：获取用户输入的姓名并显示出来

四、MVP范围

第一版必须有的功能

1. 代码输入

用户可以直接粘贴 Python 代码到输入框中。

支持：

单行代码
多行代码
基础缩进代码

例如：

for i in range(3):
    print(i)

2. 逐行解释

这是核心功能。

程序对每一行输出：

行号
原始代码
中文解释
代码类型标签

例如：

行号	原代码	类型	解释
1	`for i in range(3):`	循环	循环执行3次，每次把当前数字赋给变量 i
2	`print(i)`	输出	打印变量 i 的值

3. 整体说明

在逐行解释之后，给出一个“整段代码作用总结”。

例如：

这段代码会循环 3 次，并依次输出 0、1、2

这个总结第一版可以用规则拼出来，不需要复杂智能。

4. 代码类型识别

第一版只支持以下高频语法：

print(...)
input(...)
变量赋值 a = 1
if
elif
else
for
while
def
return
列表基础操作
注释 #

5. 示例代码快捷体验

首页或输入区下方给几个示例按钮。

例如：

输出示例
输入示例
循环示例
判断示例

用户点一下就能自动填入样例代码。

这对小白很重要，不然很多人连“该输什么”都不知道。

6. 学习历史记录

使用 localStorage 保存最近解释过的代码。

保存内容可以包括：

最近 5~10 次输入的代码
最近查看时间
最常使用的示例类型

这样用户下次打开还能继续看。

7. 手机端适配

要保证手机浏览器也能用。

重点：

文本区域足够大
结果区域纵向排版
按钮大
代码块可横向滚动

五、第一版不要做的功能

这些全部先砍掉：

真正运行 Python 代码
接入 AI
支持全部语法
文件上传 .py
语音讲解
登录注册
云同步
评论区
社区分享
代码高亮到极致
AST 级复杂分析
可视化流程图自动生成

第一版只做：基础翻译 + 可读解释

六、页面设计

建议继续采用 单页面切换或单页布局，最适合纯前端双击运行。

页面模块

1. 首页 / 主界面

模块包括：

标题
简介
代码输入框
示例代码按钮
开始解释按钮
最近历史按钮

2. 解释结果区

内容包括：

原始代码
逐行解释卡片
整体说明
再解释一次按钮
清空按钮

3. 历史记录区

内容包括：

最近解释过的代码片段
点击恢复
删除记录

七、核心用户流程

第一次使用

打开网页 → 看到介绍 → 点击示例代码或粘贴代码 → 点击“开始解释” → 查看逐行解释 → 查看整体总结

再次使用

打开网页 → 从 localStorage 读取最近记录 → 继续查看以前输入过的代码 → 再输入新的代码继续解释

八、推荐文件结构

按照你之前喜欢的“纯前端、简单、双击可用”方式：

pyexplain/
├─ index.html
├─ style.css
├─ app.js
├─ parser.js
├─ rules.js
└─ storage.js

如果想更极简，也可以：

pyexplain/
├─ index.html
├─ style.css
└─ app.js

不过我更建议拆成 4~5 个文件，后期维护更清楚。

九、解释规则设计

这是项目核心。

第一版建议采用 规则匹配 + 简单解析。

规则思路

先判断每一行属于哪一类：

1. print

例如：

print("Hello")

解释：

输出括号中的内容到屏幕上

2. input

例如：

name = input("请输入姓名")

解释：

让用户输入内容，并把结果保存到变量 name

3. 赋值

例如：

age = 18

解释：

把数字 18 保存到变量 age

4. if

例如：

if age > 18:

解释：

判断变量 age 是否大于 18，如果条件成立就执行下面缩进的代码

5. for

例如：

for i in range(5):

解释：

循环执行 5 次，每次把当前数字赋给变量 i

6. while

例如：

while x < 10:

解释：

只要变量 x 小于 10，就重复执行下面的代码

7. def

例如：

def say_hello():

解释：

定义一个名为 say_hello 的函数

8. return

例如：

return total

解释：

把变量 total 作为函数结果返回

9. 注释

例如：

# 这是注释

解释：

这一行是注释，用来说明代码，不会被执行

十、第一版支持的语法范围

建议你只支持这 10 类：

注释
变量赋值
print
input
if
elif
else
for
while
def / return

这已经足够让大多数小白前期使用了。

十一、数据结构设计

这个项目没有数据库，主要有两部分数据。

1. 规则数据

可以写在 rules.js 中：

const explainRules = [
  {
    type: "print",
    match: /^print\s*\((.*)\)$/,
    getExplanation: (match) => `输出 ${match[1]} 的内容到屏幕上`
  },
  {
    type: "assignment",
    match: /^([a-zA-Z_]\w*)\s*=\s*(.+)$/,
    getExplanation: (match) => `把 ${match[2]} 保存到变量 ${match[1]}`
  }
];

2. 历史记录数据

保存在 localStorage：

{
  history: [
    {
      id: 1,
      code: "for i in range(3):\n    print(i)",
      createdAt: "2026-04-09 10:00:00"
    }
  ]
}

你也可以加：

最近使用次数
最近一次示例类型

十二、解释结果结构

程序解释后，建议统一生成这种结构：

[
  {
    lineNumber: 1,
    raw: "for i in range(3):",
    type: "for",
    explanation: "循环执行3次，每次把当前数字赋给变量 i"
  },
  {
    lineNumber: 2,
    raw: "    print(i)",
    type: "print",
    explanation: "输出变量 i 的值到屏幕上"
  }
]

然后再额外生成：

{
  summary: "这段代码会循环3次，并依次打印变量 i 的值。"
}

十三、页面模块设计

模块1：顶部介绍

Logo/项目名
一句话说明
支持语法提示

例如： 把 Python 基础代码翻译成新手能看懂的人话。

模块2：代码输入区

多行 textarea
占位提示
示例代码按钮
清空按钮
开始解释按钮

占位示例：

for i in range(3):
    print(i)

模块3：解释结果区

每一行用卡片展示：

行号
原代码
中文解释
标签（循环 / 输出 / 判断）

模块4：整段总结

单独一个摘要卡片：

这段代码会循环 3 次，并输出 0 到 2。

模块5：最近历史

显示最近解释过的代码标题：

for循环示例
if判断示例
输入输出示例

点击可重新加载到输入框。

十四、手机端需求怎么满足

既然你强调手机端使用，那这一块要在 MVP 里提前考虑。

手机端必须做到

1. 输入区足够大

textarea 高度不要太小，至少方便粘贴和阅读。

2. 结果卡片单列布局

不要做表格，手机端适合卡片式纵向展示。

3. 代码可横向滚动

避免长代码撑破屏幕。

4. 按钮大

按钮至少 44px 高度。

5. 字体清晰

正文 16px 起，代码 14px~16px。

十五、UI方向建议

这个项目适合：

清爽
学习工具风
卡片式
解释信息层次清楚

色彩建议

主色：蓝色
辅助：浅灰
成功提示：绿色
警告 / 未识别：橙色

视觉重点

原始代码和解释要明显区分
每行解释尽量短，不要太啰嗦
标签颜色要帮助识别语法类型

十六、MVP验收标准

只要满足这些，这个 MVP 就算成立：

双击 index.html 能直接打开
能输入多行 Python 基础代码
能按行解释基础语法
能生成整段简单总结
能加载示例代码
能保存最近解释历史到 localStorage
手机端浏览器可正常使用

十七、最小开发顺序

第一步：打通核心闭环

先做：

输入区
规则匹配
逐行解释结果展示

第二步：增强体验

再做：

示例代码
整体总结
localStorage 历史

第三步：优化可用性

最后做：

手机端适配
UI优化
未识别语句提示

十八、三天极简版 MVP

Day 1

建项目
写输入界面
支持 print、赋值、input

Day 2

加 if、for、while
做逐行结果展示
做总结卡片

Day 3

加示例代码
加历史记录
做手机端适配和样式优化

十九、最推荐的首发版本

我建议你第一版直接定成：

项目版本名

PyExplain Lite

首发能力

支持 10 类基础语法解释
输入代码后逐行输出中文说明
给出整段总结
支持示例代码
保存最近历史
支持手机端

这已经足够上线给小白用了。

二十、一句话总结

这个项目的 MVP 本质上是：

一个无需安装、双击即用、支持手机端的 Python基础代码解释器，帮助新手把代码读懂。

它最重要的不是“解释得多高级”，而是三件事：

小白一眼能看懂
常见基础代码都能解释
打开就能用

FilesExpand file tree

新建文本文档.md

Latest commit

History