Skip to content

Commit 237c47f

Browse files
jinwandalaohu66jinwandalaohu66
committed
docs: 升级 README 新增 Agent/Plan 模式说明，创建 8 个模块完整 API 文档
- README.md: AI 助手部分新增 Agent 模式（14 个工具详情）和 Plan 模式说明 - README.md: 各模块部分新增指向 docs/*.md 的文档链接 - 新增 docs/ui-module.md — 30+ 控件、手势、绘图、Image 完整 API - 新增 docs/scene-module.md — 节点、Action、物理引擎、Classic 绘图完整 API - 新增 docs/widget-module.md — Widget DSL 完整 API - 新增 docs/photos-module.md — 相册/相机/Asset 完整 API - 新增 docs/dialogs-module.md — 6 个弹窗函数完整 API - 新增 docs/clipboard-module.md — 剪贴板 API - 新增 docs/console-module.md — 控制台样式 API - 新增 docs/objc_util-module.md — ObjC 运行时桥接完整 API
1 parent 0edf7ab commit 237c47f

9 files changed

Lines changed: 2656 additions & 10 deletions

‎README.md‎

Lines changed: 69 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -89,7 +89,7 @@
8989

9090
### 🤖 AI 助手
9191

92-
AI 助手**深度融入编辑器工作流**，不是简单的聊天窗口，而是真正的代码协作伙伴。
92+
AI 助手**深度融入编辑器工作流**，不是简单的聊天窗口，而是真正能操作文件、运行代码、自动修复的编程搭档。
9393

9494
#### 三种使用方式，随心选择
9595

@@ -101,25 +101,64 @@ AI 助手**深度融入编辑器工作流**，不是简单的聊天窗口，而
101101

102102
内置一键预设：**DeepSeek**、**OpenAI**、**OpenRouter**，以及任意兼容 OpenAI 格式的服务。支持保存多套预设并随时切换。
103103

104-
#### 行内修改模式
104+
#### ✨ 行内修改模式
105105

106106
- 点击编辑器顶部 ✨ 或键盘上方 ✨ 按钮，用自然语言描述需求
107107
- AI **直接修改当前文件**，以 **Diff 差异对比** 展示每一处改动（绿色新增 / 红色删除）
108108
- 支持**逐条采纳 / 拒绝**，或一键全部接受 / 放弃
109109
- 按文件类型自动切换角色：Python 专家 / JS 专家 / HTML 开发者 / Markdown 编辑
110110

111-
#### AI 聊天模式
111+
#### 🤖 Agent 模式 — AI 直接操作你的项目
112112

113-
- 底部滑出对话面板，支持多轮连续对话
114-
- 当前编辑文件内容**自动作为上下文**传入，无需手动粘贴代码
115-
- AI 回复中的代码块**一键应用到编辑器**
116-
- 支持代码解释：选中任意代码段，弹出 AI 解释面板
113+
Agent 模式下 AI 不只是回答问题，而是**真正动手**：创建文件、编辑代码、运行脚本、安装库，全部自动完成。
117114

118-
#### 智能联动
115+
**14 个内置工具：**
116+
117+
| 工具 | 功能 |
118+
|------|------|
119+
| `create_folder` | 创建文件夹 |
120+
| `create_file` | 创建新文件并写入内容 |
121+
| `write_file` | 覆写已有文件（大面积重写时使用） |
122+
| `edit_file` | 精确局部编辑（查找 old_text → 替换为 new_text） |
123+
| `read_file` | 读取文件内容（支持指定行范围） |
124+
| `list_files` | 列出目录内容 |
125+
| `delete_file` | 删除文件/文件夹（会弹窗确认） |
126+
| `rename_file` | 重命名文件 |
127+
| `move_file` | 移动文件到另一个目录 |
128+
| `run_python` | 执行 Python 脚本（30 秒超时，支持 `stdin_input` 预填输入） |
129+
| `install_package` | 从 PyPI 安装纯 Python 包 |
130+
| `search_in_files` | 在工作区内搜索关键词 |
131+
| `get_file_info` | 获取文件元信息（大小、行数、修改时间） |
132+
| `get_module_docs` | 获取 App 内置模块的完整 API 文档 |
133+
134+
**自动测试与自修复：**
135+
创建或修改 Python 脚本后，AI 会**主动运行脚本测试**。如果 stderr 中出现错误，自动分析原因、修复代码、重新运行，直到成功——无需你手动操作。
136+
137+
**多步执行计划：**
138+
当任务涉及多个步骤时，AI 先输出 `===PLAN===` 结构化计划，再逐步执行工具调用，过程完全透明。
139+
140+
#### 📋 Plan 模式 — 先规划再动手
141+
142+
Plan 模式是纯对话模式，适合复杂需求的前期规划：
143+
144+
- **结构化计划输出**：AI 使用 `===PLAN===` 格式列出编号步骤，对每一步展开详细说明
145+
- **交互式确认选项**：AI 使用 `===CONFIRM===` 格式向你提问，支持：
146+
- `( )` 单选（只能选一个）
147+
- `[ ]` 多选（可选多个）
148+
- `[input]` 自定义输入
149+
- **智能模式切换**：当你在 Agent 模式中发送复杂需求（>200 字 或包含「计划」「设计」「重构」等关键词），App 会智能建议切换到 Plan 模式先规划
150+
- 两种模式可**随时切换**，Plan 确认后可直接切到 Agent 执行
151+
152+
#### 🔗 智能联动
119153

120154
- **报错一键修复**：脚本出错后，控制台底部自动弹出错误卡片，点击 ✨ 将报错上下文直接发给 AI，一键生成修复方案
121155
- **智能装库**：AI 发现代码中缺少第三方库时，自动弹出安装提示，确认后**自动下载安装**，无需手动操作
122-
- **iOS 感知 System Prompt**：AI 内置 iOS 沙盒环境知识，不会给出在手机上无法运行的建议
156+
- **代码解释**：选中任意代码段，弹出 AI 解释面板，快速理解陌生代码
157+
- **一键应用代码**：AI 回复中的代码块可**一键替换到编辑器**
158+
- **iOS 环境感知**：AI 内置 iOS 沙盒环境完整知识（所有模块 API、可用库、限制），不会给出在手机上无法运行的建议
159+
- **模块文档按需注入**：当检测到你使用 `scene`、`ui`、`widget` 等模块时，AI 自动加载对应模块的完整 API 文档到上下文
160+
- **多会话管理**：支持创建多个独立对话，各自保持上下文
161+
- **图片附件**：支持发送图片给 AI 进行分析
123162

124163
---
125164

@@ -275,16 +314,20 @@ dialogs.hud_alert("操作完成！")
275314

276315
还支持 `clipboard`（读写系统剪贴板）和 `console`（彩色输出、清屏、粗体）模块。
277316

317+
> **完整 API 文档：** [photos 模块](docs/photos-module.md) · [dialogs 模块](docs/dialogs-module.md) · [clipboard 模块](docs/clipboard-module.md) · [console 模块](docs/console-module.md)
318+
278319
#### 📐 ui 模块 — 原生界面
279320

280321
Pythonista 兼容的 UI 模块，用 Python 创建原生 iOS 界面（View、Button、Label、TextField、ScrollView、TableView、WebView 等），支持 `present()` 全屏/半屏展示、自绘、load_view 等。
281322

282-
- **[UI 模块完整文档（中文）](docs/ui-module-zh.md)** · [Full docs (English)](docs/ui-module-en.md)
323+
> **完整 API 文档：** [ui 模块完整文档](docs/ui-module.md)
283324
284325
#### 🎮 scene 模块 — 2D 游戏引擎
285326

286327
Pythonista 兼容的 Scene 模块，用 Python 开发 2D 游戏和动画。底层基于 SpriteKit，提供**两种开发模式**：经典逐帧绘制（`draw()`）和现代节点树（Node + Action）。
287328

329+
> **完整 API 文档：** [scene 模块完整文档](docs/scene-module.md)
330+
288331
##### 节点体系
289332

290333
| 节点 | 说明 |
@@ -386,6 +429,8 @@ run(MyGame())
386429

387430
用 Python 创建 **iOS 桌面小组件**，脚本运行后自动渲染到主屏幕。支持声明式布局 DSL 和快捷模板两种模式。
388431

432+
> **完整 API 文档：** [widget 模块完整文档](docs/widget-module.md)
433+
389434
##### 支持的组件（14 种）
390435

391436
| 组件 | 方法 | 说明 |
@@ -449,6 +494,20 @@ w.render()
449494

450495
应用内置 **8 款小组件示例**，包括健身环、习惯追踪、学习计时、货币汇率、音乐播放器等，可直接运行体验。
451496

497+
#### 🔧 objc_util 模块 — ObjC 运行时桥接
498+
499+
通过 `objc_util` 可以在 Python 中直接调用 iOS Objective-C API，访问系统框架（UIKit、Vision、AVFoundation 等），创建 ObjC 类，注册回调。
500+
501+
```python
502+
from objc_util import ObjCClass, on_main_thread
503+
504+
UIDevice = ObjCClass('UIDevice')
505+
device = UIDevice.currentDevice()
506+
print(device.systemVersion())
507+
```
508+
509+
> **完整 API 文档：** [objc_util 模块完整文档](docs/objc_util-module.md)
510+
452511
---
453512

454513
### 🔒 隐私与个性化

‎docs/clipboard-module.md‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
# clipboard 模块 — 系统剪贴板
2+
3+
Pythonista 兼容的剪贴板模块，直接通过 ObjC 运行时访问 iOS 系统剪贴板（UIPasteboard）。
4+
5+
## 完整 API
6+
7+
### get() → str
8+
获取剪贴板中的文字内容。没有内容时返回空字符串。
9+
10+
```python
11+
import clipboard
12+
text = clipboard.get()
13+
print(f'剪贴板内容：{text}')
14+
```
15+
16+
### set(text: str) → None
17+
将字符串写入剪贴板。
18+
19+
```python
20+
clipboard.set('Hello, World!')
21+
```
22+
23+
### clear() → None
24+
清空剪贴板（等同于 `set('')`）。
25+
26+
```python
27+
clipboard.clear()
28+
```
29+
30+
### 兼容别名
31+
- `get_text()` — 等同于 `get()`
32+
- `set_text(text)` — 等同于 `set(text)`
33+
34+
## 完整示例
35+
```python
36+
import clipboard
37+
38+
# 读取剪贴板
39+
old = clipboard.get()
40+
print(f'之前的内容：{old}')
41+
42+
# 写入新内容
43+
clipboard.set('Python IDE 是最好的 iOS 编程 App！')
44+
45+
# 验证
46+
print(f'现在的内容：{clipboard.get()}')
47+
48+
# 清空
49+
clipboard.clear()
50+
print(f'清空后："{clipboard.get()}"')
51+
```
52+
53+
## 注意事项
54+
- 仅支持文本内容的读写
55+
- 底层通过 ctypes 直接调用 UIPasteboard，无需额外依赖
56+
- `get()` 返回空字符串而非 None（即使剪贴板为空）

‎docs/console-module.md‎

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
# console 模块 — 控制台样式控制
2+
3+
Pythonista 兼容的控制台模块，通过 ANSI 转义序列控制输出颜色和样式。
4+
5+
## 完整 API
6+
7+
### clear() → None
8+
清除控制台所有输出。
9+
10+
```python
11+
import console
12+
console.clear()
13+
```
14+
15+
### set_color(r=-1, g=-1, b=-1) → None
16+
设置后续 `print()` 输出的前景色。参数为 0.0~1.0 的 RGB 值。不传参数或 r<0 时重置为默认颜色。
17+
18+
```python
19+
console.set_color(1, 0, 0) # 红色
20+
print('这是红色文字')
21+
console.set_color(0, 1, 0) # 绿色
22+
print('这是绿色文字')
23+
console.set_color() # 重置
24+
print('这是默认颜色')
25+
```
26+
27+
### set_bold(flag=True) → None
28+
开启或关闭粗体输出。
29+
30+
```python
31+
console.set_bold(True)
32+
print('粗体文字')
33+
console.set_bold(False)
34+
```
35+
36+
### set_font(name='', size=0) → None
37+
设置控制台字体（兼容接口，本 App 固定等宽字体，无实际效果）。
38+
39+
### reset_style() → None
40+
重置所有样式（颜色、粗体），等同于 `set_color()` + `set_bold(False)`。
41+
42+
### hud_alert(message, duration=1.0) → None
43+
显示短暂的 HUD 提示（委托给 dialogs.hud_alert 实现）。
44+
45+
```python
46+
console.hud_alert('操作成功！')
47+
```
48+
49+
### alert(title, message='', *button_titles, hide_cancel_button=False)
50+
弹出确认框（委托给 dialogs.alert，兼容接口）。
51+
52+
### input_alert(title, message='', input_text='', ok_button_title='OK', hide_cancel_button=False) → str
53+
弹出输入框（委托给 dialogs.input_alert，兼容接口）。
54+
55+
### print_raw(text) → None
56+
直接输出文本（不带换行），等同于 `sys.stdout.write(text)`。
57+
58+
## 完整示例
59+
```python
60+
import console
61+
62+
console.clear()
63+
64+
# 彩色输出
65+
console.set_color(0.2, 0.6, 1.0)
66+
print('=== 天气预报 ===')
67+
68+
console.set_bold(True)
69+
console.set_color(1, 0.3, 0)
70+
print('🌡️ 温度：28°C')
71+
72+
console.set_color(0, 0.8, 0.4)
73+
print('💧 湿度：65%')
74+
75+
console.reset_style()
76+
print('数据更新于 2025-01-01')
77+
78+
console.hud_alert('数据已刷新')
79+
```
80+
81+
## 注意事项
82+
- set_color 使用 0.0~1.0 的 RGB 浮点值（与 Pythonista 一致）
83+
- 颜色通过 ANSI 256 色转义序列实现
84+
- App 控制台支持完整 ANSI 彩色（16/256/RGB）
85+
- set_font 为兼容接口，无实际效果
86+
- hud_alert 和 alert 内部委托给 dialogs 模块

0 commit comments

Comments
 (0)