# PyFly 终极路线图

> **唯一真源（single source of truth）**：本文件是所有阶段（L/R/P/S）的唯一整合视图。
> 实施细节见各专项文档，本文件只负责总览、阶段编排、验收标准与优先级决策。
> 专项文档：`Plan.md`（语言实现）、`方案.md`（语言设计）、`docs/长期规划.md`（L0-L5 生态）、
> `docs/Rust迁移方案.md`（R0-R5 核心迁移）、`docs/CLI-Rust转型方案.md`（P0-P6 CLI 迁移）、
> `docs/THREAT-MODEL.md`（威胁模型与边界）、`docs/安全测试报告.md`、`docs/沙箱白皮书.md`。

---

## 1. 现状盘点（2026-08）

| 域 | 条目 | 状态 |
| :--- | :--- | :--- |
| 语言 | 8 关键字（safe/only/lock/mask/cage/guard/seal/trace） | ✅ P0-P7 全部落地 |
| 语言 | 污点引擎（R1-R5）、escape 全局扫描、运行时注入（guard/only/seal/trace/cage 节） | ✅ |
| 语言 | 进程级沙箱 fly-sandbox（Linux=ns+Landlock+seccomp；macOS=Seatbelt；Windows=Job Object） | ✅ 三平台原生实现（v0.6.5） |
| CLI | **全 Rust（P0-P6 完全交付，cmd/fly 退役）**：build/run/check/sandbox/version/error/update/lsp + fmt/analyze | ✅ |
| Rust | lexer（R0/R1）、ast、parser、checkd 客户端、错误渲染 format、gen、typeinfer | ✅ |
| 工程 | VSCode 插件（LSP）、npm 包、GitHub Actions 发布链、自更新 | ✅ |
| 质量 | testdata 反例 52+、golden、checker 单测、fuzz（lexer/parser/compile/checker） | ✅ |
| 安全 | 威胁模型、边界清单 B1-B8、外部评估回应（THREAT-MODEL §9/§10）、逃逸面 E1-E14 枚举 | ✅ 2026-08 两次审计落地 |

**已填缺口（2026-08）**：G3 签名 ✅、G5 fuzz+红队 ✅、G2 交互矩阵 ✅、G4 审计注释 ✅、
G7 类型生态澄清 ✅、G1 wrapper 试点 ✅（S6，requests）。G6 错误信息迭代（S7）随 L0 P6 推进。

**已填缺口（2026-08 二轮审查，13 项）**：only 块 dunder `__import__` 逃逸修复（E14，运行时特判 +
编译期 onlyDeny∪escapeModules 联合 + `__builtins__` 纳入）、needs_guard 递归 only/trace/cage、
aug_assign 单次求值（Go/Rust 双修 + golden 重生成）、fmt `not in` 空格、checkArgs `*args` 误报、
propagateTaint 基符号、analyze 评分边界、lexer 省略号列号、http 相对重定向 scheme + 拒绝明文降级、
LSP 单一 debounce 线程、prelude cage ctypes 投递、refCollector 参数默认值；fuzz 追加 FuzzCheckSource。

### 1.1 待收尾清单（2026-08 不完备性报告，未决项）

| # | 条目 | 类型 | 状态 |
| :--- | :--- | :--- | :--- |
| W1 | ~~win/mac 无 OS 级沙箱（空壳 exit 2）~~ | 平台 | ✅ v0.6.5：macOS=Seatbelt（sandbox-exec SBPL：禁网/限文件写/内存CPU上限），Windows=Job Object（kill-on-close+内存/时间/进程上限），强度声明入 README 平台表 |
| W2 | 发布链依赖人工 secret：`SIGN_PRIVATE_KEY`/`VSCE_PAT`/`NPM_TOKEN` 未配即静默跳过 → `fly update` 无 .sig 自断链 | 发布 | 🔲 CI 显性告警；PR 门禁 CI（当前仅 tag 触发 release.yml） |
| W3 | 安全核心（escape/taint/only/guard 拦截逻辑）无专项 fuzz | 质量 | 🔲 补 fuzz 目标 |
| W4 | 错误码双真源（errors.go ↔ errorinfo.rs）靠人工同步 | 质量 | 🔲 CI 一致性校验 |
| W5 | ~~Wasm 沙箱 `fly-sandbox`~~ | 架构 | ✅ 已决（2026-08）：删除 Wasm 原型，单沙箱主线（进程级：Linux=ns+Landlock+seccomp，win/mac=平台原生隔离） |
| W6 | ~~高频语法暂不支持（with/推导式/字典解包），兼容度 74%~~ | 生态 | ✅ 已决（2026-08）：暂不实现，写入 docs/compat.md（报错 E0004/E0008/E0009 + workaround），74% 接受 |
| W7 | 第三方库 wrapper：requests 之后补 sqlalchemy | 生态 | ✅ v0.6.6：sqlalchemy 可用——`text()` 汇点编译期拦截（taint.go）+ `_FLY_SB_ALLOWED_MODS` 白名单 + execute 通用汇点；文档与反例锁定（checker_test TestTaintIOSources） |
| W8 | ~~改名撞车（fly-lang/fly）~~ | 品牌 | ✅ 已决（2026-08）：**不改名**——品牌完全即 PyFly（repo PyFly-lang、产物 fly、npm fly-lang），撞车风险接受并记录风险表 |
| W9 | Go（checker/沙箱）+ Rust（CLI）双实现并存，语义漂移风险靠 golden 对比兜底 | 维护 | 持续（D1/D6 已定，checker 留 Go） |

---

## 2. 阶段总览（统一时间线）

```
现状 ──L0──► v0.3.0（基线收尾）──L1──► v1.0.0（Rust 全量）✅ 2026-08 达成（实际 v0.6.4）
   └───── S 系列安全专项（S1-S6，随阶段插入，S2/S3 优先）──────┐
v1.0.0 ──L2──► v1.1（工具链自举）──L3──► v2.0（自举编译器闭环）
   ──L4──► v2.x（开放协作）──L5──► v3.0（生态与治理）
```

### L0 基线收尾（→ v0.3.0）
| 任务 | 说明 | 验收 |
| :--- | :--- | :--- |
| P6 打磨 | golden 全量覆盖、错误消息快照、边界用例（闭包/嵌套/f-string 内 mask） | ✅ 已交付 |
| 行为测试接入 CI | 生成 .py 由 python3 实跑 | ✅ 已交付（release.yml python 3.10-3.14 矩阵） |
| S1 边界文档 | THREAT-MODEL §9/§10（本文件）+ README 安全边界声明 | ✅ 已交付 |

### S 系列安全专项（插队规则：S2/S3 优先，不阻塞 L1）
| 条目 | 任务 | 优先级 | 验收 |
| :--- | :--- | :--- | :--- |
| S2 | `fly update` 产物签名（ed25519，零第三方）+ 校验，失败拒绝安装 | 🔴 高 | ✅ 已交付：tools/sign + verify.go + release.yml 签名步骤 + 5 单测（正签/篡改/缺签/换钥/--insecure） |
| S3 | Go fuzz（parser/checker）+ 逃逸红队回归 | 🔴 高 | ✅ 已交付：3 个 fuzz 目标（lexer/parser/compile，seed=testdata 全量），修复 3 个 parser panic；redteam_test.go 19 项对抗回归，新增属性赋值污点传播，B7 确认不可达 |
| S4 | 8 关键字交互矩阵文档 + 表驱动组合测试 | 🟡 中 | ✅ 已交付：docs/关键字交互矩阵.md + interaction_test.go 22 组合 |
| S5 | 可选 `--keep-annotations`：产物保留安全标记注释（审计/复盘） | 🟡 中 | ✅ 已交付：fly build --keep-annotations，6 类注解（safe/mask/lock/guard/only/seal/trace/cage） |
| S6 | 第三方库 wrapper 试点（requests/sqlalchemy 任一） | 🟢 低 | ✅ 已交付：requests 受控包装（examples/third_party/safe_http.fly + docs/第三方库安全包装.md）；修复 guard 消息字符串转义 bug；运行时白名单与编译期 taint 源点一致化（allow_requests_s6 防漂移测试） |
| S7 | 错误信息用户测试迭代（G6） | 持续 | 🔲 随 P6 消息快照推进 |

> S2 待用户操作：`~/.fly-sign/priv.pem`（本次生成）内容配置到 GitHub Actions secret `SIGN_PRIVATE_KEY`，否则 CI 跳过签名（无 .sig 时 fly update 默认拒绝安装）。

### L1 Rust 迁移（→ v1.0.0）✅ 2026-08 全部完成（实际版本 v0.6.4）
| 阶段 | 内容 | 状态 |
| :--- | :--- | :--- |
| R0/R1 | lexer（token/缩进/字符串） | ✅ |
| R1.5 | ast + parser（1322 行翻译） | ✅ |
| P1/P2 | version/help/error + check（checkd 桥接，零差异） | ✅ |
| R2 | gen + 运行时注入（only/seal/trace/cage/runtime/sandbox 节） | ✅ |
| P3 | `fly build` / `fly run`（checkd 复用，golden 逐字节一致） | ✅ |
| R3 | checker 语义子集自举（可选，checker 留 Go 为 D6 默认） | 🔲 可选（D1/D6 决策：checker 留 Go） |
| P4 | `fly update`（签名先行，见 S2）/ `fly lsp` | ✅ |
| R4 | compile 管线整合、错误聚合 20 条上限 | ✅（checkd 侧） |
| P5 | `fly sandbox`（决策 B：fly-sandboxd 二进制桥接） | ✅ |
| R5/P6 | 切换与退役：release.yml 切 Rust 构建，产物命名不变，AGENTS.md/README 更新 | ✅（b147c25：cmd/fly 退役 + fmt/analyze 迁 Rust + 三二进制打包） |

验收：v1.0.0 与 Go 版 CLI diff 零差异；单静态二进制（<3MB）；VSCode/CI/update 契约零改动。**已达成**（golden 双端逐字节一致 + LSP full_session 集成 + update 实测全链路）。

### L2 工具链自举（→ v1.1）← 当前主线
- `fly fmt`（AST 驱动，注释保留，**用 Fly 编写**，Rust 壳调用）
- `fly doc`（docstring → Markdown）、`fly test`（目录级测试运行器）
- Neovim/JetBrains LSP 客户端配置
- 验收：`fly fmt` 格式化自身源码后 golden 无差异（dogfooding 自证）
- 前置：§1.1 W2-W4 收尾（CI 门禁、安全 fuzz、错误码校验）随 L2 并行（W1/W5 已于 v0.6.5 完成）

### L3 自举编译器（→ v2.0）
- gen 发射器用 Fly 重写（参考实现，D-1 双实现互证）
- 前端 `flyc.fly` 自编译闭环：`fly build flyc.fly → python3 flyc.py` 编译任意 .fly
- 验收：Fly 写的编译器能编译自身并产出可运行 .py

### L4 开放协作（→ v2.x）
- RFC 流程、CHANGELOG 自动生成、文档站（GitHub Pages + docsify，D-3）、playground
- 安全评审清单 + 漏洞披露流程
- 验收：外部贡献者 PR 全流程无维护者人工干预

### L5 生态与治理（→ v3.0）
- 标准库/包管理寄生 Python（pip/PyPI 复用，无自研 registry）
- 合规行业试点（金融/医疗/政务）与合规报告模板
- 成功指标：示例库 10+、外部贡献 PR ≥ 1（自 L4 持续）

---

## 3. 关键决策（已定，勿反复）

| # | 决策 | 结论 |
| :- | :--- | :--- |
| D1 | checker 是否迁移 Rust | **留 Go**（D6），走 checkd 桥接；R3 可选自举 |
| D2 | 工具语言 | 用 Fly 写 fmt/doc/test（自举优先），Rust 壳调用 |
| D3 | 文档站 | GitHub Pages + docsify（零成本） |
| D4 | 自举编译器形态 | 编译为 .py 由 python3 跑（无引导问题） |
| D5 | sandbox 迁移 | 决策 B：保留 Go 实现，`fly-sandboxd` 二进制桥接（安全关键代码不重写） |
| D6 | 包管理 | 寄生 Python（pip/PyPI），无自研 registry、无 flyx 包 |

## 4. 风险

| 风险 | 等级 | 缓解 |
| :--- | :--- | :--- |
| 安全保证被"改写产物"绕过（THREAT-MODEL §9.1） | 高 | 文档诚实声明 + 编译期零残留关键字为不可篡改层 |
| S2/S3 拖延导致信任链缺口 | 高 | 插队规则：S2/S3 优先于 L1 功能 |
| win/mac 沙箱承诺与实现不符（W1） | 高 | ✅ 已解除（v0.6.5）：macOS Seatbelt / Windows Job Object 真实实现，强度声明入 README |
| 发布 secret 未配 → update 断链 / 发布静默缺件（W2） | 高 | §1.1 W2：CI 显性告警 + PR 门禁 CI |
| 双实现（Go checker/Rust CLI）语义漂移 | 中 | golden 逐字节对比 + LSP full_session 集成 + fuzz（W3/W9） |
| Rust 迁移与工具链并行冲突 | 中 | ✅ 已解除：L1 已达成，L2 串行开始 |
| 自举版漂移 | 中 | golden diff + 双实现互证 |
| 改名撞车（fly 名称已被占用） | 中 | ✅ 已决（2026-08，W8）：不改名——品牌完全即 PyFly，撞车风险接受（产物 fly/npm fly-lang 维持），用户安装走 `fly update` 官方渠道 |
| 单人维护精力 | 低 | 全自动 CI/发布 + RFC 流程 |

## 5. 成功指标

- ✅ v0.3.0（2026-08 达成，实际 v0.6.4）：8 关键字全落地 + S1-S3 完成（签名 + fuzz 就位）
- ✅ v1.0.0（2026-08 达成）：Rust CLI 全量零差异（golden 逐字节 + full_session 集成），update 签名验证上线
- 🔲 v1.1：`fly fmt` 自举（dogfooding 闭环）（W1-W4 已于 v0.6.5 收尾）
- 🔲 v2.0：自举编译器 `flyc` 闭环
- 🔲 v2.x+：示例库 10+、外部贡献 PR ≥ 1、合规试点 ≥ 1

## 6. 版本时间线速览

```
✅ v0.3.0-v0.6.4 ──── L0 + S1-S3 + L1（Rust 全量，2026-08 达成）
🔲 v1.1   ──── L2（工具链自举）
🔲 v2.0   ──── L3（自举编译器 flyc）
🔲 v2.x   ──── L4（开放协作）
🔲 v3.0   ──── L5（生态与治理）
```