Plan

PyFly 实现方案

Fly = Python 3.10+ 安全增强超集，用 Go 实现转译器（Fly → Python，类似 TypeScript → JavaScript）。 新增 8 个安全关键字，编译期检查 + 展开删除，输出纯净 Python。

语言定位

• Fly 源码是 Python 3.10+ 超集，转译后为合法 Python，无残留语法
• 8 个关键字：safe only lock mask cage guard seal trace
• 编译期报错输出到终端，退出码 1；fly check 仅检查不输出代码

编译管线

.fly → Lexer → Parser(AST) → 语义分析(checker) → 编译期报错 → 代码生成 → .py
                 │                              │
                 └── lock/guard/mask/safe 拦截 ──┴── only/seal/trace/cage 展开注入

项目结构（Go 标准库，零第三方依赖）

flylang/
├── go.mod
├── cmd/fly/main.go            # CLI: fly build <in.fly> [-o out.py] / fly check / fly run
├── internal/
│   ├── lexer/                 # Python 3.10+ 子集 + 8 关键字 token
│   ├── ast/                   # 节点定义 + 位置信息（报错行列号）
│   ├── parser/                # 递归下降；only:/cage():/seal class/mask x 等新语法
│   ├── checker/
│   │   ├── symbol.go          # 符号表、作用域、lock 只读拦截、import 收集
│   │   ├── taint.go           # 赋值 def-use 链：safe(源→危险汇点) mask(敏感→输出上下文)
│   │   ├── whitelist.go       # only 块内名字 vs 白名单
│   │   └── guard.go           # guard 条件合法性验证
│   ├── gen/
│   │   ├── python.go          # 缩进化 Python 代码发射
│   │   └── inject.go          # seal/trace/cage/only 运行时注入
│   ├── version/               # Version/Commit/Repo（ldflags -X 注入）
│   ├── update/                # 自更新：GitHub Releases API + socks5/http 代理（手写 SOCKS5）
│   └── runtime/fly_runtime.py # go:embed；GuardError/ResourceExhaustedError、白名单代理、冻结容器
├── tools/icon/                # 图标生成器（输出 assets/icon.png）
├── assets/                    # logo.svg + icon.png
├── .github/workflows/release.yml  # 打 v* tag → deb/pkg/dmg/zip/SFX + GitHub Release
├── editor/vscode-fly/         # VSCode 插件（TypeScript）
│   ├── package.json           # contributes: languages/grammar/commands/configuration
│   ├── syntaxes/fly.tmLanguage.json  # TextMate 语法高亮（Python 子集 + 8 关键字）
│   ├── src/extension.ts       # 激活逻辑
│   ├── src/diagnostics.ts     # 调 `fly check` 解析报错 → Problem Panel
│   └── src/commands.ts        # build/run/update 命令
└── testdata/                  # .fly 正反例（# fly:error 标记期望编译错误）

VSCode 插件

轻量方案，不引入 LSP（编辑器体验先行，LSP 留待后续）：

• 语法高亮：TextMate grammar（syntaxes/fly.tmLanguage.json），基于 Python 语法注入 8 个关键字样式（safe/mask/lock/guard 与 only/cage/seal/trace 可区分色）
• 编译期诊断：diagnostics.ts 保存时或手动触发，后台执行 fly check <file.fly>，解析 error: file:line:col: msg 输出到 Problems 面板
• 命令：Fly: Build to Python（转译当前文件并显示/保存 .py）、Fly: Check（手动检查）
• 配置：fly.path（fly 可执行文件路径，默认 fly）、fly.checkOnSave（默认 true）
• 未装 fly 时的降级：提示安装并给出构建命令

开发与打包：npm install → npm run compile → F5 调试（Extension Development Host）；打包用 vsce package。

关键字落地分工

关键字	编译期动作	运行时残留
safe	污点追踪：I/O 源（request/input）→ safe 声明点；未净化变量传入 eval/exec/os.system/SQL 拼接等汇点 → 报错	无
only	白名单校验：块内名字/import 与白名单比对，出现 os/subprocess 等 → 报错	注入 __builtins__ 白名单代理，重写块内 import
lock	符号表只读标记：拒绝再赋值、AugAssign、setattr、globals()['X'] 反射读取	生成冻结常量容器
mask	反向追踪：mask 变量出现在 print/logging/f-string 输出上下文 → 报错	无
cage	解析 max_time/max_memory 参数，按块包装	生成装饰器：signal.SIGALRM 计时 + resource.setrlimit 限内存，抛 TimeoutError/ResourceExhaustedError
guard	验证约束为布尔表达式、变量与断言匹配	展开为 if not (...): raise GuardError(...)
seal	标记类、收集类属性	类体内注入 __setattr__/__delattr__，非初始化阶段增删改一律抛错
trace	解析 level/args/ret 参数	函数入口/出口插入 logging 调用，含参数与返回值

报错格式

error: <file>.fly:12:5: lock 变量 SECRET_KEY 不可再赋值

行列为 AST 节点位置。

测试策略

• 单元：lexer/parser 各语法节点
• checker：testdata 表驱动反例测试（# fly:error 注释标记期望错误，编译必须报错）
• 集成：golden 测试对比转译输出
• 行为：生成的 .py 用 Python 3.10 实跑验证 cage/seal/trace 运行时行为

发布与自更新

• 打 v* tag → .github/workflows/release.yml：Linux（deb/tar.gz，amd64+arm64）、macOS（pkg/dmg universal）、Windows（zip + 7z SFX installer），gh release create 自动发布
• fly update：查 GitHub Releases latest → 按 fly-<os>-<arch>.tar.gz|.zip 匹配下载 → 校验 → 原子替换自身；--check 有新版本退出码 2；--proxy 支持 http(s):// 与 socks5://[user:pass@]host:port（手写 SOCKS5，零依赖）
• 版本注入：-ldflags "-X flylang/internal/version.Version=... -X ...Commit=... -X ...Repo=29anan29/Fly-lang"，未注入时显示 dev

开发过程（P0 → P6）

每阶段退出标准（DoD）：go vet ./... 与 go test ./... 全绿；新功能有正反例测试；生成的 .py 用 Python 3.10 实跑通过。

P0 基础设施（CLI + Lexer + Parser + AST）

目标：端到端骨架跑通——任意不含关键字的子集 .fly 可无损转译并执行。

任务：

1. go.mod + 目录骨架（cmd/internal/testdata）
2. internal/ast/pos.go：Position + Diagnostic 错误类型（error: <file>:<line>:<col>: <msg>）
3. internal/lexer/：token 定义（Python 3.10+ 子集 + 8 关键字）、缩进栈、f-string、字符串转义、数字/注释
4. internal/ast/：节点全集（模块/函数/类/if/for/while/import/赋值/表达式/调用/f-string/异常）
5. internal/parser/：递归下降，parse 出模块树；解析错误也带行列号
6. internal/gen/：最小 AST→Python 编码器（只做格式重排，不注入）
7. cmd/fly/main.go：build（默认写同目录 .py、-o 指定）/ check（只检查退出码 1）/ run（临时文件跑 python3）
8. testdata 首批正例 + golden 测试框架（输出快照对比）

验收：hello.fly 转译后 python3 实跑输出一致；错误样例报错格式正确。

P1 符号表 + lock + guard（纯编译期先行）

目标：编译器第一次"拦截"能力——lock 冻结常量、guard 展开断言，零运行时残留。

任务：

1. checker/symbol.go：作用域符号表（模块/函数/类）、名字收集、import 表
2. lock 拦截：对 lock 名的 Assign/AugAssign/setattr/globals()['X']/vars()['X'] 一律报错
3. guard 验证：变量必须已定义、条件为布尔表达式；gen 展开为 if not (...): raise GuardError(...)
4. checker 错误聚合（一次报多个错误，最多 N 条上限）
5. testdata 反例：lock 篡改、guard 类型不匹配等，用 # fly:error 标记

验收：lock SECRET = "x" 后任何再赋值/反射读取编译失败；guard age: int, 0 < age < 150 展开正确。

P2 污点引擎（safe / mask）

目标：数据流分析落地——safe（源→危险汇点）与 mask（敏感→输出上下文）双向污点。

任务：

1. checker/taint.go：def-use 链（赋值/函数调用参数/返回值/容器元素/属性传播）
2. 源点表：request.*、input、os.environ 等 I/O 源
3. 汇点表：eval/exec/os.system/subprocess.*/SQL 字符串拼接
4. safe x 声明点语义：声明的污点变量被清洗（int(x) 等）后解除污点；未清洗流入汇点→报错
5. mask x：变量流入 print/logging.*/f-string/字符串格式化→报错；允许哈希/比较等非输出上下文
6. 反例测试：safe uid 后 eval(uid) 报错、mask password 后 print(password) 报错；正例（清洗后/比较后）不误报

验收：文档示例 1（safe）与 4（mask）的注释行全部编译报错，正文行全部通过。

P3 注入型关键字（only / seal / trace）✅ 完成

目标：代码生成开始"改写"——白名单块、类冻结、审计日志。

任务：

1. only (mods): 块：解析白名单、块内名字/import 比对（os/subprocess/eval 等→报错）；gen 重写块内 import + 注入 __builtins__ 白名单代理 ✅（checker/only.go 黑名单 + gen _FlyOnly 代理 + _fly_patch_builtins 函数包装）
2. seal class：收集类属性；gen 在类体注入 __setattr__/__delattr__（非 __init__ 阶段增删改抛错）；实例属性赋值（admin.role = "user"）编译期可静态识别则直接报错 ✅（checker 静态拦截 + 运行时 _fly_seal_initializing 门控）
3. trace(level=, args=, ret=)：函数入口/出口插入 logging 调用（参数与返回值）✅（gen 包装函数 + _fly_trace_impl_ 原函数保留）
4. 反例：only 块内 os.system 报错、seal 类实例赋值报错；正例：合法模块调用通过 ✅（testdata/errors/only_seal.fly、testdata/golden/p3.fly）
5. fly_runtime.py 起步：GuardError 等异常类型 ✅（internal/runtime/fly_runtime.py go:embed，按 # fly:section: 标记提取注入 guard/only/trace 三节）

验收：文档示例 2/7/8 的注释行全部报错；生成的 .py 结构正确且 Python 3.10 语法合法。✅

P4 资源约束（cage + runtime 库）✅ 完成

目标：运行时防御闭环，cage 限制时间/内存并抛规范异常。

任务：

1. cage(max_time=, max_memory=): 解析参数（"5s"/"100MB" 单位换算）✅（parser 解析 max_time: ms/s/m/h、max_memory: B/KB/MB/GB(+iB)，运行前换算为秒/字节）
2. gen 包装：装饰器生成（signal.SIGALRM 超时 + resource.setrlimit 限内存 + 清理恢复）✅（@_fly_cage(...) 装饰器注入 cage 块内函数；setitimer 计时 + RLIMIT_AS 软限压降，finally 恢复）
3. fly_runtime.py 完善：TimeoutError/ResourceExhaustedError 包装、资源恢复逻辑 ✅（cage 节：_fly_cage 装饰器 + ResourceExhaustedError + _fly_timeout_handler；MemoryError→ResourceExhaustedError 转换；只降软限避免无权限硬限恢复失败）
4. 行为测试：while True 超时抛错、大数组分配抛 ResourceExhaustedError（python3 实跑）✅（testdata/p4_cage.fly 双场景触发 + 嵌套 cage/重复调用/正常快路径验证）

验收：文档示例 5 转译后实跑，超时与超内存两种场景均触发并抛对应异常。✅

P5 VSCode 插件（已升级为 LSP 版）

目标：编辑器体验——高亮 + LSP 编译期诊断。

任务：

1. internal/lsp：零依赖 JSON-RPC over stdio 服务器（Content-Length 帧、请求/通知分发、错误聚合）
2. 能力：initialize/initialized/shutdown/exit、didOpen/didChange(full)/didSave/didClose、publishDiagnostics（compile.CheckSource 内存编译，120ms 防抖）、hover（8 关键字文档 + 所在行）、自定义 fly/forceCheck
3. cmd/fly 新增 lsp 子命令（stdio）
4. editor/vscode-fly/ 插件：vscode-languageclient v10 连接 fly lsp，TextMate 高亮保留，命令（Build/Run/Update/ForceCheck）
5. 配置 fly.path/fly.proxy；fly.checkOnSave 移除（LSP 常驻）
6. 验证：lsp 单测（管道模拟完整会话）+ vsce package + code --install-extension

验收：F5 调试下 .fly 文件实时诊断（与 fly check 同管线）；hover 出关键字说明；fly lsp 冒烟会话（initialize/didOpen/shutdown/exit）通过。

P5.5 发布生态（CI 打包 + 自更新 + 图标）

目标：一键发布多平台安装包，fly update 原地升级。

任务：

1. tools/icon/ 图标生成器（多边形光栅化 → assets/icon.png）
2. internal/version：ldflags 注入版本/提交/仓库
3. internal/update：GitHub API 查版本、AssetFor 按平台匹配、tar.gz/zip 解包原子替换、socks5 代理（含认证）手写实现 + 表驱动测试
4. cmd/fly 新增 version/update 子命令（--check 退出码 2 / --force / --proxy）
5. .github/workflows/release.yml：deb/tar.gz/pkg/dmg/zip/SFX 五类产物 + Release 发布
6. VSCode 插件补 Fly: Check for Updates（复用 --check/--force + fly.proxy 配置）

验收：本地 dpkg-deb 冒烟打包通过；go test ./... 全绿。

P6 打磨与收尾 ✅ 完成

任务：

1. golden 测试全量覆盖 + 错误消息快照测试 ✅（TestErrorSnapshots：24 个 errors 反例的 .err 快照逐行比对，与 LSP 同一 FormatError 管线）
2. 边界用例：嵌套作用域、闭包、递归、f-string 内 mask 变量、only 嵌套 ✅（golden/edge.fly 正例防误报：shadowing/闭包/递归/嵌套 only/safe 清洗；errors/edge_nesting.fly 反例：闭包内 mask 泄露、嵌套 only 内 os、深层嵌套 mask）
3. 文档：README（安装/用法/8 关键字速查）、报错清单整理 ✅（docs/报错清单.md：全部错误消息 + 运行时异常表；README 链接）
4. go vet、gofmt 全绿；vsce package 产出 .vsix ✅（插件 v0.3.0，本地打包 12.56 KB 通过）

验收：CI 式一键命令 go test ./... && go vet ./... 全绿；对方案.md 全部 8 个示例做最终回归。✅（testdata/acceptance/all8_ok.fly 正例全部通过并 python3 实跑；errors/all8_err.fly 反例 9 条错误全部命中）

里程碑：P0-P6 全部完成，发布 v0.3.0（正式版 release 渠道）。

P7 编译期完备检查（check 通过 = 无原生运行时崩溃）✅ 完成

编辑器 check 优化 + 编译前检查强化，两阶段保证：

1. 静态检查扩展（checker/runtime.go）：
   • 未定义名称：模块级顺序敏感（引用须先赋值/import），函数体宽松（参数+局部+外层+内置）
   • 本地函数参数个数：不足/过多/未知关键字/重复传值
   • 常量除零：/、//、% 字面量 0
   • 重复定义：同作用域函数/类/import 撞名、参数重复
   • 字面量类型操作：二元运算/一元/下标/in 的类型兼容表
2. 运行时兜底（gen 注入 _fly_* 护栏 + FlyRuntimeError）：
   • _fly_binop（含除零）/_fly_unary/_fly_get/_fly_set/_fly_attr/_fly_setattr/_fly_cmp/_fly_iter/_fly_cast（int/float）
   • 动态错误统一 FlyRuntimeError: src:行:列: 描述，不再裸抛 Python 异常
   • only 代理放行 _fly_ 前缀 + FlyRuntimeError/GuardError
3. 编辑器同步：LSP 与 fly check 同一 CheckSource 管线，新检查自动生效；fly build 编译前检查本就同管线

验收：新增 undefined_name/dup_def/literal_type/arg_count 反例 + 快照；golden 全量（含转译注入回归）；TestRuntimeCatch 实跑验证 5 类动态错误全部转 FlyRuntimeError；go test ./... && go vet ./... 全绿。

里程碑（与阶段对应）

P0 基础设施 ✅ → P1 lock/guard ✅ → P2 safe/mask ✅ → P3 only/seal/trace → P4 cage+runtime → P5 VSCode 插件 → P5.5 发布生态 → P6 打磨 → P7 编译期完备检查

当前进度

• P1（已完成）：internal/checker/（symbol.go 作用域符号表 + lock.go 冻结常量拦截 + guard.go 条件验证）、parser 支持 lock/guard 语法（含 guard x > 0 纯条件形式）、gen 展开 guard 为 if not (...): raise GuardError(...) 并注入 GuardError 类、错误聚合上限 20 条、LSP 诊断同步；golden（lock/guard）+ 9 个 errors 反例 + checker 单测全绿
• P2（已完成）：checker/taint.go 污点引擎（顺序数据流：赋值/容器/属性/下标传播、清洗 int/float/bool、函数返回污点、f-string 变量提取）；源点（input()/request.*/os.environ）；汇点（eval/exec/compile/os.system/subprocess.*/SQL execute；print/logging.* 输出）；safe/mask 零运行时残留；golden safe_mask + 7 个 errors 反例 + 污点单测全绿；方案.md 示例 1/4 验收通过