Skip to content

Commit cf8629e

Browse files
Update MiniApp platform APIs and native capability docs
1 parent 50ae6be commit cf8629e

241 files changed

Lines changed: 51110 additions & 1072 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.
Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
# PythonIDE 全量产品功能审计:执行摘要
2+
3+
> 审计基线:2026-07-20 当前工作区;只读分析。生产代码、工程配置与 Git 历史均未修改。详细置信度、证据与动态验证边界见其余报告。
4+
5+
## L0:一句话核心价值
6+
7+
PythonIDE 让用户在 iPhone 与 iPad 上完成从“编写/导入代码”到“运行、调试、用 AI 协作、封装 MiniApp/Widget、连接服务器与 Git、发布和分享结果”的完整 Python 工作流。
8+
9+
## 审计规模
10+
11+
本审计把页面合并为用户任务,不以 View 数量冒充功能数量。稳定统计口径为:
12+
13+
- L1 大功能板块:12
14+
- L2 用户能力:62
15+
- L3 用户细节功能:162(A 已确认 133;B 高可信推断 29)
16+
- L3 之外的条件/非用户候选:C 待确认 1(默认关闭的后台 Agent);D 不可达或疑似废弃 0;E 内部功能 4
17+
- Target:1 个主 App、2 个测试 Target、3 个用户扩展
18+
- 平台:iPhone、iPad;支持在 Apple Silicon Mac 上以 Designed for iPad/iPhone 方式运行,但没有独立 macOS/Catalyst、watchOS 或 visionOS Target
19+
20+
## 产品领域(L1)
21+
22+
| ID | 大功能板块 | 核心用户结果 |
23+
|---|---|---|
24+
| F01 | 工作区与文件 | 创建、导入、组织、恢复和分享项目资产 |
25+
| F02 | 编辑器、Notebook 与预览 | 编辑多种源码/数据格式并即时预览 |
26+
| F03 | 运行、调试、输出与包 | 执行 Python/JavaScript,定位问题并扩展依赖 |
27+
| F04 | AI 助手与 Agent | 让模型结合项目上下文解释、修改并执行任务 |
28+
| F05 | MiniApp、AppUI 与桌面开发 | 把 Python 工作流封装为可交互应用并联机开发 |
29+
| F06 | Widget、Live Activity 与自动化 | 把脚本结果与动作带到系统表面和快捷指令 |
30+
| F07 | iOS 原生能力与 Python 桥接 | 从 Python 调用设备、媒体、系统和 UI 能力 |
31+
| F08 | SSH、SFTP、WebDAV 与远程运维 | 在移动端连接、传输和部署到远程环境 |
32+
| F09 | Git 版本控制 | 管理从改动、提交到分支、冲突和远端同步的生命周期 |
33+
| F10 | 社区与网站发布 | 发现/发布作品并把 HTML 项目发布到公网 |
34+
| F11 | 工具、设置、数据与安全 | 配置环境、管理应用数据并保护隐私 |
35+
| F12 | 账号、购买与支持 | 登录、管理身份、解锁权益、恢复购买与支持项目 |
36+
37+
## 第一批最小高质量内容集
38+
39+
| 内容 ID | 解决的问题 / 优先原因 | 形式与旁白 | 复杂度 | 复用与准备 | 设备 | 主要影响 |
40+
|---|---|---|---|---|---|---|
41+
| C-P0-01 | 让潜在用户在 60 秒内明白 App 做什么;核心价值入口 | T6/T7;旁白可选 | M | 复用 Agent/MiniApp/Widget/网站原子片段;需完成态 Demo | Simulator,系统表面可补真机 | 下载、认知 |
42+
| C-P0-02 | 首次新建、运行并看到输出;决定首次成功 | T5;无需旁白 | M | 复用新建/运行素材;无需 Tutorial Mode,重置有价值 | Simulator | 上手、留存 |
43+
| C-P0-03 | 解释导入与连接文件夹的差异;减少“文件去哪了” | T4;建议旁白 | M | 复用 Picker/工作区素材;需固定 zip/文件夹 | Simulator | 上手、客服 |
44+
| C-P0-04 | 解决缺包与 iOS 包兼容误解 | T4;建议旁白 | M | 复用运行成功;固定 PyPI 响应最稳 | Simulator | 成功率、客服 |
45+
| C-P0-05 | 区分等待输入、Traceback 和真正卡住;避免误停 | T4;建议旁白 | M | 三段独立原子脚本;不依赖 Tutorial Mode | Simulator | 失败恢复、数据安全 |
46+
| C-P0-06 | 解释 Agent 的确认、Diff、`接受`和验证;建立安全感 | T4;建议旁白 | L | 高度复用;依赖固定 Agent 回放与可重置 Repo | Simulator | 核心差异、付费 |
47+
| C-P0-07 | 展示脚本如何成为可交互 MiniApp | T4/T6;旁白可选 | L | 复用宣传结果;固定 Seed/日期 | Simulator;图形性能可补真机 | 差异化、留存 |
48+
| C-P0-08 | 让用户拿到结果,并理解何时用`加密分享` | T3 + T2;无需旁白 | S | 复用 Share/加密原子素材;假密码 | Simulator | 结果交付、数据安全 |
49+
| C-P0-09 | 从本地 HTML 得到公网网址并更新同一站点 | T4/T7;建议旁白 | L | 复用网站宣传;需测试账号、站点与稳定服务 | Simulator;最终分享可补真机 | 最终结果、付费、客服 |
50+
51+
第一批不要先做“每个设置项一条视频”。静态设置与规则优先用可搜索图文;视频资源集中在手势、跨页、失败分支与高价值结果。
52+
53+
## 三个最重要的录制准备工作
54+
55+
1. 固定一套匿名 Demo 工作区:`hello.py`、一个会报错的脚本、一个带 `requests` 的包安装样例、一个视觉完成度高的 MiniApp、一个可部署 HTML 项目。
56+
2. 增加 Debug/UITest-only 的 Recording Profile:一键重置 Demo 数据、跳转到指定页面、冻结日期与运行结果、关闭遥测/通知;不暴露给 Release 用户。
57+
3. 统一原子素材规范:iPhone 竖屏中文主版本,无旁白母片、触点单独图层、首尾各留 0.5 秒;iPad 只补录布局或键盘专属能力。
58+
59+
## 最大风险
60+
61+
- 功能审计风险:AI、社区、网站发布、Git/SSH 的部分状态依赖账号、服务端、远端主机、Pro 权益或真实权限;它们有完整静态实现,但不能把未成功走通的服务端流程写成动态确认。
62+
- 教程维护风险:主导航存在 iOS 16、iOS 18 与 iOS 26 三套渲染路径,且可选 Tab 可隐藏/重排;把教程写死为坐标会快速失效。镜头必须以真实 UI 文案和稳定起始状态为锚点。
63+
- 隐私与发布风险:仓库未发现主 App 自有 `PrivacyInfo.xcprivacy`;是否由依赖清单完全覆盖需在发布审计中另行核对,本报告不据此断言违规。
64+
65+
## 结论
66+
67+
最合适的内容体系不是“长篇全功能介绍”,而是三层:可搜索图文知识库负责规则和设置;15–45 秒原子微视频负责隐藏入口和手势;3–6 分钟完整任务教程只覆盖首次成功、失败恢复与高价值交付。第一批 9 条可以复用约 18 个无旁白原子录屏片段,后续 UI 变化只重录受影响片段。
68+
69+
> 数量来自对 `03-complete-feature-inventory.md``feature-inventory.json` 的逐条校验;`F08``F09` 各有 6 个 L2,因此不能按“每个 L1 固定 5 个 L2”估算。
Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
# 仓库、工程与 Target 地图
2+
3+
## 扫描范围与方法
4+
5+
检查了 `git ls-files` 的 64,122 个受版本控制文件,并交叉扫描工程文件、主 App、三个扩展、测试、内置 Python 包、Swift Package、本地化、文档、示例、Fixtures、Feature Flag、Entitlement 与 App Store/发布资料。第三方源码不逐个记为产品功能,但其被主 Target 链接的用户价值已映射。
6+
7+
主要命令:`git ls-files``find``rg``xcodebuild -list``xcodebuild -showdestinations``xcodebuild build``xcodebuild test``xcrun simctl`。完整构建结果见本文件末尾与 `16-gaps-unknowns-and-risks.md`
8+
9+
## Xcode 容器
10+
11+
- Project:`Py编程IDE.xcodeproj`
12+
- Workspace:`Py编程IDE.xcodeproj/project.xcworkspace`
13+
- 共享 Scheme:`pythonide`
14+
- 依赖带出的 Scheme:`MarkdownUI`,不是产品 App Scheme
15+
- Build Configuration:`Debug``Release`
16+
- 最低系统:iOS 16.2
17+
- 设备族:iPhone + iPad
18+
19+
证据:`Py编程IDE.xcodeproj/project.pbxproj``Py编程IDE.xcodeproj/xcshareddata/xcschemes/pythonide.xcscheme`;动态 `xcodebuild -list`
20+
21+
## Target 分类
22+
23+
| Target | 类型 | 用户能力 | 归类 | 状态 |
24+
|---|---|---|---|---|
25+
| `Python IDE` | 主 App | 全部 L1 | F01–F12 | 主 Scheme 构建入口 |
26+
| `PythonScriptActivityWidgetExtension` | WidgetKit 扩展 | Home/Lock Screen Widget、Live Activity、Control Center | F06 | 用户功能 |
27+
| `ShareExtension` | Share Extension | 从其他 App 导入文件、文本、URL、图片、MiniApp 包 | F01 | 用户功能 |
28+
| `WidgetIntentExtension` | Intent Extension | iOS 16 旧式 Widget 槽位选择 | F06 | 用户功能,兼容路径 |
29+
| `Py编程IDETests` | Unit Test | 验证模型、存储、运行、AI、Git、SSH、Widget 等 | 证据来源 | 非用户功能 |
30+
| `Py编程IDEUITests` | UI Test | AppUI 手势回归、性能脚本、启动截图 | 证据来源 | 非用户功能 |
31+
32+
主 App 的 Target dependency graph 明确嵌入三个扩展。证据:动态构建输出 `Target dependency graph (107 targets)`
33+
34+
## 平台与呈现差异
35+
36+
- iPhone:主录制平台;竖屏为默认内容规格。
37+
- iPad:支持 Split/Popover、外接键盘、多栏与大画布;高级编辑、文件拖放、桌面开发需补录。
38+
- iOS 16:旧 Tab/旧 Widget Intent 兼容路径。
39+
- iOS 18:隐藏系统 Tab + 自定义 Tab Chrome;Control Center 控件可用。
40+
- iOS 26:系统 Tab 与部分新 UI/材质路径。
41+
- Apple Silicon Mac:`xcodebuild -showdestinations` 显示 Designed for iPad/iPhone;不是独立 macOS 产品承诺。
42+
- 未发现 watchOS、visionOS、独立 Mac Catalyst Target。
43+
44+
## Swift Package 与本地组件
45+
46+
主要用户价值映射:
47+
48+
- `Runestone` + `TreeSitterLanguages`:多语言编辑、语法高亮、缩进、查找替换。
49+
- `SwiftTerm` + `NSRemoteShell` + `libssh2-spm` + `OpenSSL`:本地/SSH 终端、SFTP 与安全连接。
50+
- `libgit2-spm`:Git 本地操作。
51+
- `PythonIDEKit` + `mcp-swift-sdk`:Agent 核心与 MCP。
52+
- `Nuke``MarkdownUI`:网络图片、Markdown 渲染。
53+
- `Lottie``SwiftUI-Shimmer`:品牌与加载视觉,不单独计为用户功能。
54+
- `KeyboardToolbar`:编辑器/终端快捷键条。
55+
56+
还解析到远端依赖 `swift-nio``swift-log``swift-collections``swift-async-algorithms``swiftui-introspect``cmark-gfm` 等。精确版本来自动态 `xcodebuild -list` 输出。
57+
58+
## 系统配置与 Entitlement
59+
60+
| 系统能力 | 证据 | 用户功能映射 |
61+
|---|---|---|
62+
| iCloud Documents / KV | `Config/Xcode/Python IDE*.entitlements` | F01 iCloud 工作区、跨设备文件/设置 |
63+
| App Group `group.app.pythonide` | 主 App 与扩展 Entitlement | F01 Share Inbox;F06 Widget 数据交换 |
64+
| Associated Domains | `applinks:link.pythonide.xin` | F05/F10 深链安装或打开社区内容 |
65+
| Sign in with Apple | Entitlement + `PythonIDEAccountLoginView` | F12 账号 |
66+
| HealthKit / WeatherKit | Entitlement + Bridge | F07 Python 原生模块/Agent 工具 |
67+
| NFC Tag Reading | Entitlement + `NFCBridge` | F07 NFC |
68+
| Live Activities | `Info.plist` + ActivityKit 代码 | F06 脚本/Agent/Git 运行状态 |
69+
| Background fetch/processing/audio | `Info.plist` + `BackgroundTaskManager` | F03/F06 后台运行与刷新 |
70+
| Local Network / Bonjour | `Info.plist` + DesktopDev | F05 桌面开发发现与连接 |
71+
| Document Browser / File Sharing | `Info.plist` | F01 Files App 与外部导入 |
72+
73+
主 App `Info.plist` 还声明相机、相册、麦克风、语音、定位、蓝牙、通讯录、日历、提醒事项、运动、Face ID、通知、Apple Music 等用途。每项均在 F04 或 F07 找到实际代码映射;权限存在不等于用户已经授权。
74+
75+
## 本地化与文档资源
76+
77+
- String Catalog:`Localizable.xcstrings`
78+
- 传统本地化:`zh-Hans``zh-Hant``en``ja``ko``ru` 等;覆盖度不完全相同。
79+
- Widget 扩展有独立多语言资源。
80+
- `README.md``Documentation/Internal/FINAL_RELEASE_AUDIT.md`、开发者文档 Manifest、Help 文案、MiniApp 示例均用于交叉核对,但不会单凭营销文案把功能标成 A。
81+
82+
## 构建与测试记录
83+
84+
| 项目 | 命令摘要 | 结果 |
85+
|---|---|---|
86+
| 工程枚举 | `xcodebuild -list -project Py编程IDE.xcodeproj` | 成功;确认 6 Target、2 Configuration、2 Scheme |
87+
| 目的地枚举 | `xcodebuild -showdestinations ... -scheme pythonide` | 成功;iOS 16.2/17.5/18.1/26.5 Simulator 与真机可用 |
88+
| Debug Simulator 构建 | `xcodebuild -project Py编程IDE.xcodeproj -scheme pythonide -configuration Debug -destination 'platform=iOS Simulator,id=3D29BCB0-173B-4191-B80A-9EF9E8BEE7C3' -derivedDataPath /private/tmp/pythonide-content-audit-derived CODE_SIGNING_ALLOWED=NO build` | 成功;iPhone 17 Pro / iOS 26.5;依赖图 107 Targets;主 App 与三个扩展均构建/嵌入 |
89+
| 单元/UI 测试 | 同目的地执行 `xcodebuild ... test` | 失败(exit 65),测试未执行:`pythonideTests/PythonHighlightQueryTests.swift:99,132``.zero` 缺少可推断上下文;这是测试 Target 编译阻断,本轮按只读约束未修复 |
90+
| Simulator 启动 | 安装构建产物后启动 `app.xinmini.PythonIDE` | 仅确认 PythonIDE 启动封面;后续 `simctl` 截图/启动调用挂起,未完成根 Tab 与核心流程遍历,因此不把静态功能升级为动态确认 |
91+
92+
首次沙箱内 `xcodebuild -list` 因 SwiftPM/Xcode 缓存与 CoreSimulator 权限失败;在获准访问 Xcode 缓存后成功。这是环境限制,不是项目故障。
Lines changed: 114 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
1+
# 导航、页面与功能映射
2+
3+
## 根入口
4+
5+
`pythonideApp``@main` 入口位于 `pythonide/AppShell/pythonideApp.swift:119``WindowGroup` 创建 `RootTabView`,见 `pythonide/AppShell/pythonideApp.swift:253-306`。根部同时处理 App Lock、启动封面、URL、Quick Action、Share Extension Inbox、App Intent 输出和 Widget 命令。
6+
7+
## 根 Tab 地图
8+
9+
| TabID | 用户文案 | 默认状态 | 根页面 | 主要功能 |
10+
|---|---|---|---|---|
11+
| `home` | 首页 | 固定可见 | `HomeView` | F01–F03、F05、F09 |
12+
| `agent` | Agent | 默认可见,可隐藏/重排 | `SearchTabAIChatLayer` | F04 |
13+
| `terminal` | 终端 | 默认可见,可隐藏/重排 | `TerminalTabView` | F03、F08、F09、F11 工具 |
14+
| `settings` | 设置 | 固定可见 | `SettingsView` | F04–F12 配置入口 |
15+
| `community` | 社区 | 默认可见,可隐藏/重排 | `ScriptLibraryNextPreviewView` | F10 |
16+
| `widget` | 小组件 | 默认隐藏,可启用/重排 | `WidgetSettingsView`/Studio | F06 |
17+
18+
证据:`pythonide/AppShell/RootTabView.swift:218-260,1327-1515``pythonide/Settings/SettingsGeneralViews.swift:336-410`。可选 Tab 隐藏后,设置搜索提供 Agent、社区与终端兜底入口,见 `SettingsHomeModels.swift:55-59`
19+
20+
## 首页导航树
21+
22+
```text
23+
首页
24+
├─ 工作区:此 iPhone / iCloud / 外部文件夹
25+
├─ 文件与文件夹列表
26+
│ ├─ 源码编辑器(py/js/html/css/json/md/txt/csv…)
27+
│ ├─ Notebook 编辑器(ipynb)
28+
│ ├─ Markdown / CSV / SVG / HTML 预览
29+
│ ├─ 图片 / 音频 / 视频 / PDF / Office Quick Look
30+
│ ├─ Archive 浏览与解压
31+
│ └─ SQLite 浏览
32+
├─ MiniApp 集合与 Launcher
33+
├─ Git 仓库页
34+
├─ 回收站
35+
├─ 本地终端 / 包管理
36+
└─ 新建菜单:文件、Notebook、文件夹、MiniApp、导入、扫码、外部文件夹、WebDAV
37+
```
38+
39+
关键条件入口:长按运行按钮显示“清空后运行/追加运行”;行上下文菜单提供重命名、复制、移动、压缩、打包 MiniApp、加密分享等;Swipe 负责置顶/取消置顶与删除。不能仅靠主工具栏发现这些能力。
40+
41+
## 编辑器跨页结构
42+
43+
`ContentView` 不是单一功能页:同一容器根据文件类型组合代码编辑、输出、Notebook、Web Preview、Git、AI Review、Debugger、Profiler、Widget Preview、参数与设置 Sheet。多文件 Tab、查找替换、断点、错误回溯跳转和键盘快捷键跨多个子视图协作。
44+
45+
## Agent 导航树
46+
47+
```text
48+
Agent
49+
├─ 新对话 / 历史 / 搜索 / 重命名 / 删除
50+
├─ 工作区选择(此 iPhone、iCloud、外部文件夹)
51+
├─ 输入:文本、相机、照片、文件、语音、Skill、MCP
52+
├─ 模型与推理强度 / 批准模式
53+
├─ 执行时间线:计划、工具请求、输出、Diff、验证、Apply
54+
└─ 设置
55+
├─ PythonIDE 账号 / 托管额度
56+
├─ 自定义服务商、模型与 API Key
57+
├─ Skills
58+
├─ MCP Servers
59+
├─ Shortcuts Connectors
60+
└─ Memory
61+
```
62+
63+
## 终端与远程导航树
64+
65+
`TerminalTabView.SSHNavDestination` 将同一 Tab 分为本地终端、服务器列表、SSH Terminal、SFTP、监控、部署、密钥和片段。WebDAV 从新建菜单或设置/文件流程进入独立浏览器。SSH 主机指纹通过根级 `SSHHostTrustSheet` 统一确认。
66+
67+
## 社区与网站
68+
69+
- 社区:搜索 → 最新投稿/官方精选/分类 → `ScriptDetailView` → 预览、运行、安装/保存、作者、互动。
70+
- 发布:社区右上角 `发布作品` → 类型/项目选择 → 内容、截图、说明、协议 → 上传/审核状态。
71+
- 个人中心:资料、头像、作品、投稿状态、获赞、退出与注销账号。
72+
- 网站:打开 HTML 文件 → 顶部 `部署`/`更新` → 登录与项目扫描 → 新建或关联已有网站 → 发布 → 打开/分享/下线/恢复/部署记录/回滚/删除。
73+
74+
证据:`ScriptLibraryNextPreviewView.swift:120-228,423-539``WebsiteOnlineView.swift:757-928``MyWebsitesView.swift:170-380``WebsiteManagementSheet.swift:45-161`
75+
76+
## 设置导航
77+
78+
一级真实 UI 名称:`AI 助手``我的网站``应用数据``外观``桌面开发``编辑器``终端``小组件``开发工具``隐私与安全``开发者文档``帮助与反馈``支持项目`。证据:`pythonide/Settings/SettingsHomeModels.swift:40-65`
79+
80+
## 系统外部入口
81+
82+
- URL Scheme:`pythonide://``minip://`
83+
- Universal Link:`https://link.pythonide.xin/...`
84+
- Home Screen Quick Actions:AI 对话、快速运行、运行剪贴板、新建文件。
85+
- App Shortcuts:运行代码/脚本/剪贴板、在 App 中运行、停止、状态、最后输出、新建、保存文本、打开脚本。
86+
- Spotlight:索引可运行脚本/实体(系统版本条件)。
87+
- Files / Document Picker:导入、外部文件夹、文档浏览。
88+
- Share Sheet:批量导入并打开/浏览/预览/解密,MiniApp 安装预览或仅保存。
89+
- Widget/Live Activity/Control Center:打开 App、刷新、运行、继续查看状态。
90+
91+
## 手势与辅助操作索引
92+
93+
| 手势/操作 | 页面 | 功能 |
94+
|---|---|---|
95+
| 行左/右 Swipe | 文件、回收站、社区会话、网站、下载等 | 置顶、删除、恢复、分享、上下线 |
96+
| 长按标题 2 秒 | 社区标题 | 打开管理员页;E 内部功能,不计普通用户功能 |
97+
| Context Menu | 文件、MiniApp、社区作品、网站、服务器 | 预览、复制、移动、分享、管理等 |
98+
| 拖放 | 文件/外部目录、Tab/Widget 预览、列表 | 移动/导入/排序/调整抽屉 |
99+
| 捏合 | 编辑器、终端、图片/图表/网页 | 字号或缩放(取决于页面) |
100+
| 双击 | 输出图片/图表等 | 快速预览/放大 |
101+
| 外接键盘 | 编辑器、Notebook、Agent、终端 | 运行、停止、发送、查找、Notebook Cell 操作 |
102+
| Accessibility Action | 多文件 Tab、列表动作、按钮 | 关闭、运行、移动等替代入口 |
103+
104+
## 无正常用户入口或受限页面
105+
106+
| 项目 | 分类 | 说明 |
107+
|---|---|---|
108+
| `ScriptAdminView` / `WebsiteAdminView` | E 内部功能 | 社区标题长按 2 秒可触发,但仍需管理员服务端验证;不作为普通用户教程 |
109+
| `WebsiteDeployUIPreviewHost` | E 内部功能 |`#if DEBUG` + `-WebsiteDeployUIPreview`/`-WebsiteManagementUIPreview` |
110+
| UI Test 脚本注入 | E 内部功能 | `PYTHONIDE_UI_TEST_*` 启动环境,仅测试/录制辅助候选 |
111+
| Debug 邀请深链 | E 内部功能 | `SettingsDeepLinkNavigator``#if DEBUG` 包围 |
112+
| `AgentRunFeatureFlags.backgroundRunnerEnabled` | C 待确认 | 默认关闭;不要宣传为所有用户可用的后台 Agent |
113+
114+
其余 Preview、Fixture、Seed、Mock 只作为证据或 Demo 数据候选,未计为用户页面。

0 commit comments

Comments
 (0)