# VB6 技能包

<!-- autos.skill.namespace: autos.skills.vb6 -->
<!-- autos.skill.description: Visual Basic 6.0 编程开发；可编写 aardio 控件。 -->
<!-- autos.skill.version: 0.2.22 -->
<!-- autos.skill.minAutos: 4.15 -->
<!-- autos.skill.disabled: false -->

## 定位

当前首选是 **Direct2D/Canvas/AI 新工程**：用最薄的可编辑 VB6 Canvas 快速完成轻量 GUI、游戏和动画，再按真实需求扩展 ActiveX DLL/OCX 与 aardio 互操作。旧工程维护仍受支持，但迁移不是默认路线；生成的是可在 VB6 IDE 打开的普通源码工程，独立 VB 程序不依赖 aardio 宿主。

## 直接使用

```aardio
import autos.skills.vb6;
var vb = autos.skills.vb6;

var project = vb.createProject("/MyVb6Project",{kind="hello";name="MyVb6App"});
if(!project.ok) return project;
return vb.build(project.projectPath);
```

`build()` 调用真实 `VB6.EXE /MAKE`，自动检查和修复编译环境；无日志失败或编译器崩溃时只自动重试一次。正常开发不必预先定位编译器、运行 `selftest` 或枚举模板源码。

### 纯函数批测

需要快速验证几何、计分、文本处理等不依赖界面的 VB6 逻辑时，直接 `import autos.skills.vb6.pure`。它真实编译一次标准模块，随后在隔离的 32 位 EXE 中批量运行输入，并返回值、类型、ByRef 写回、VB6 错误号和源码位置；不把 `unsupported`、`skip` 或意外 `error` 当成通过。完整参数与报告字段见 `knowledge/pure.md`。

```aardio
import autos.skills.vb6.pure;
var source = /***
Private Function Clamp(ByVal n As Long) As Long
    Clamp = n
End Function
***/;
var report = autos.skills.vb6.pure.test(
    source, "Clamp", [{args=[-1];expected={kind="Long";value=0}}],
    {argKinds=["Long"];sourceName="Math.bas"}
);
if(!report.ok) return report;
```

### 按用途选模板

| kind | 用途 |
| --- | --- |
| `exe` | 空白 MainForm；支持 `/smoke` 报告后退出 |
| `task` | 无窗体 Sub Main 任务；读取 `Command$` 并演示文件输出，不是控制台程序 |
| `hello` | Hello World 按钮与标签 |
| `gui` | 整数乘二示例，含输入错误处理 |
| `dll` | Engine COM 类，含方法、属性、ByRef、数组和事件；不是 C ABI DLL |
| `ocx` | CounterPanel 可视控件，含按钮、属性和事件 |
| `canvas` | Direct2D + DirectWrite 薄画板，适合原创游戏和动画 |
| `pulse` | 完整的 Pulse Grid 谜题游戏 |
| `selftest` | 编译器故障诊断 |

`createProject(dir,{kind;name})` 默认 `kind="gui"`；name 为最长 40 字符的 ASCII 标识符。目标目录必须不存在。需要程序化清单时用 `vb.listTemplates()`。

游戏、动画和简单按钮优先 `canvas`，直接写规则、几何和绘图，不造控件框架；复杂输入、列表等密集界面可用网页。`canvas/pulse` 加 `assets=true` 可生成图片、透明贴图与渐变适配。使用时分别按需读 `knowledge/direct2d.md`、`knowledge/direct2d-assets.md`。旧工程迁移、ADO、复杂 COM/OCX 维护按具体用户阻塞再加载对应知识，不作为新项目的前置步骤。

## 源码编辑

保留 CRLF、Attribute、引用及 FRX/CTX 配对；二进制资源不交给文本工具。修改前备份，修改后编译并验证相关行为。

### ASCII 源码 + Unicode 字符串

新工程自动加入 ASCII-only `USTR.bas`，用 `USTR("\u4F60\u597D")` 表达 Unicode 文本。源码与注释保持 ASCII 后，可直接用 `read_text_file`、`patch_text_file`、`save_files` 等 UTF-8 工具编辑，保存为无 BOM、CRLF。

- 旧工程迁移先征得用户同意，说明迁移后可直接用 UTF-8 文本工具维护；调用 `vb.migrateProject(vbp,{dryRun=true})` 预览，再去掉 dryRun 执行。它改写代码字符串，保留 FRX/CTX，窗体设计区非 ASCII 文本会报告 warning。
- 只需加入模块、不改写现有字符串：`vb.ensureUSTR(vbp)`；同名非托管文件不会被覆盖。
- 大量文本或本地化：`vb.writeStringResources(vbp,entries)` 生成 `.res` 和 `ResourceIds.bas`，代码使用 `LoadResString(IDS_TITLE)`。

只有需要完整转义规则、迁移选项或资源条目示例时，再读 `knowledge/unicode.md`。

### 仍需保留的 ANSI 文本

新建或全文保存含本地文字的 ANSI 源文件，用 `save_files(charset="ansi",newline="crlf")`。局部编辑旧 ANSI 源码或窗体设计文本，用 `textkit.ansi`；不要对纯 ASCII 文件增加转码步骤。

```aardio
import textkit.ansi;
var path = "/MyVb6Project/MainForm.frm";
var view = textkit.ansi.read(path=path;lineNumbers=false);
if(!view.ok) return view;

return textkit.ansi.edit(
    path=path;
    operation="replace";
    oldText=`Caption         =   "旧标题"`;
    newText=`Caption         =   "新标题"`
);
```

`read/patch/edit/save` 都接受 `{path;...}`，输入及返回文本为 UTF-8，文件按系统默认 ANSI 读写。检查结果的 `ok`、`written`、`backupPath`；SEARCH 复制唯一原文，不模糊重试。

`read` 以 LF 展示；`patch/edit` 适配原文件换行；`save` 原样保留传入换行且要求父目录存在。代码内可用块注释字符串提供 CRLF，无需手动转码。备份是原始 ANSI 字节，恢复用 `io.copy(backupPath,path)`，不要通过 UTF-8 文本工具重写备份。

## 构建结果与运行

- `vb.build(vbp,{compilerPath;timeoutMs=30000;buildRoot})` 返回结果表；`ok` 才表示本次新产物非空、编译器退出码为 0 且清理成功。使用返回的 `artifact`、`logPath`、`attemptDir` 物理路径，不猜输出目录，不凭旧产物或日志字样判成功。
- `vb.inspectProject(vbp)` 清点源文件、引用和资源链接，返回 `files/references/resources/errors/warnings` 等字段；它不激活引用，也不验证依赖可用，`ok` 不等于可编译。
- 单独检查环境才用 `vb.ensureCompiler()`；只定位文件用 `vb.getCompiler()`，返回路径或 `null,error`。
- 编译失败先看 `status/failureKind/logPath`。普通源码错误按日志修复；自动修复后仍崩溃或无日志，再用 `selftest` 对照并读 `knowledge/diagnostics.md`。若返回 `cleanupPending`，按该文完成资源回收，不能当作成功。

构建后运行本次产物，覆盖正常路径和相关错误路径。GUI 的 `Form_Load` 不直接或经 Click 调用 `SetFocus`；隐藏 `/smoke` 只调用共享业务过程，焦点与模态 UI 等窗体显示后再验证。

VB6 DLL/OCX 用 `com.lite(path)` 磁盘免注册，不直接内存加载。嵌入资源先释放到自己的 `io.appData("厂商/应用/...")` 目录，勿占用 `aardio/std`。COM 测试用独立进程，退出整个加载进程后再重编译；已发布组件保留独立 Binary Compatibility 基准并验证旧客户端。详细用法见 `knowledge/interop.md`。

发布说明只写产品操作和必要的运行要求，开发 TLB 来源留在 TLB 旁的 `SOURCE.md`。

## 查询官方文档

```aardio
import autos.skills.vb6.docs;
var docs = autos.skills.vb6.docs;
return docs.lookup("AppActivate Statement"); // {title;url;text}；失败 null,error
```

- VB6 专属主题用英文标题 `lookup()`；标题不确定时 `resolve("TextBox Control")` 选候选，再 `fetch(url)`。
- 语言级搜索用 `docs.search("Format function VBA")`，不加 `VB6.0` 后缀。`samples(query,"vb")` 的 vb 标签不保证兼容 VB6，需排除 VBA7/VB.NET 和 Office 专属语法。
- 标题定位可离线，正文、搜索及示例需联网；缓存与刷新选项见 `knowledge/docs.md`。

## 按需参考

以下路径相对于技能包的 `.res/`，只读当前任务需要的文件；普通子库直接 import，无需再次加载技能。

| 任务 | 入口 |
| --- | --- |
| 自绘画板、游戏、动画 | `knowledge/direct2d.md`；`autos.skills.vb6.d2d` |
| 图片、内嵌 PNG、透明贴图、渐变 | `knowledge/direct2d-assets.md` |
| 独立 EXE、模板运行 | `knowledge/independent.md` |
| 编译器部署、修复、定制安装包 | `knowledge/setup.md`；`autos.skills.vb6.setup` |
| 旧工程、资源维护、GUI 生命周期、错误清理 | `knowledge/maintenance.md` |
| 转义详情、源码迁移、字符串资源 | `knowledge/unicode.md` |
| 构建、运行、IDE 故障 | `knowledge/diagnostics.md` |
| ADO 与 32 位 provider/DSN | `knowledge/ado.md` |
| DLL/OCX、回调、ByRef、事件、兼容升级 | `knowledge/interop.md` |
| aardio 宿主与独立 EXE 文件协作示例 | `examples/README.md` |
| 纯函数测试报告 | `knowledge/pure.md`；`autos.skills.vb6.pure` |
| 官方文档查询 | `knowledge/docs.md`；`autos.skills.vb6.docs` |

类型库探查用 `com.tlbDoc` / `com.typeAttrs`；需要图形查看器时可用 `dotNet.oleview`，不要默认随产品捆绑。IDL 编译可复用 `vc6` 的 MIDL 工具。VB 调用 aardio ActiveX EXE 时，用 `autos.skills.aardioProjectBuilder` 创建 ActiveX 工程，编辑 `/typelib/typelib.odl`，由 `/.build/default.init.aardio` 编译 TLB。
