LISP 任务：提交、回执与恢复

com.cad.task 在兼容 CAD 的 COM 命令通道之上执行 AutoLISP，并通过本地文件返回数据。它不依赖 Autos、特定窗口类名、Visual LISP COM 函数接口或 .NET 插件。回执确认的是程序执行和序列化结果，不代替几何或业务验收。

建议入口

cad.CreateLispTask(code,args,doc,options)：先创建任务，不提交。自动化优先使用，可在产生副作用前保存任务路径。
cad.SubmitLisp(...)：创建并尝试提交，返回 task,err。即使提交报错，也可能返回任务对象，应保留它。
cad.RunLisp(...)：创建、保存journal、唯一提交并等待，返回result,err,task。结果含taskPath/elapsed及实际journal；journal写失败不提交。
cad.ResumeLisp(path,timeout,doc)：恢复原回执，返回同一元组；省略doc可离线。
com.cad.task.open(path[,doc])：跨线程、跨会话恢复任务。读取回执不需要 CAD 正在运行。

增强实例入口可省略doc，此时只使用已有活动图纸，不自动新建；底层task.create仍要求显式doc。code 是原始 LISP 源码，不是 aardio 模板，也不是文件名。最后一个表达式的值为结果，args 是 LISP 中的局部变量。不要使用 ac$ 前缀的内部变量，也不要在任务中切换/关闭目标图纸或嵌套提交任务。

最小完整示例

import com.cad;
import com.cad.task;
var cad = com.cad();
if(!cad) error("无法连接或启动 CAD");
if(!cad.IsQuiescent()) error("CAD 当前忙碌，请先检查原任务");
var doc = cad.Documents.Add(); // 本例明确新建测试图纸。
var task,err = cad.CreateLispTask(
    `(list (cons "text" (car args)) (cons "answer" (+ (cadr args) 5)))`,
    ["中文",7],doc
);
if(!task) error(err);
// 在提交前持久化路径；进程意外退出也能重新查回执。
var recoveryFile = io.appData("aardio/com.cad/last-task.txt",task.path);
print("任务目录",task.path);
var sent,err = task.submit();
if(!sent) {
    print("提交未确认，勿重发",err,task.path);
    return;
}
var result,err = task.wait();
print(result,err); // completed 时 data 为 {text="中文";answer=12}

恢复时只读原任务，不另建 ID 重试：

import com.cad.task;
var path,err = string.load(io.appData("aardio/com.cad/last-task.txt"));
if(!path) error(err);
var task,err = com.cad.task.open(path);
if(!task) error(err);
var result,err = task.wait(5000);
print(result,err);

read() 和默认的 wait() 只读取任务目录，不读取 COM 文档；省略 doc 打开的任务始终可以离线等回执。wait() 泵送窗口/STA 消息，不使用长时间纯 sleep。只有创建时显式设 nudge=true 且仍持有原 doc 时，wait 才可能刷新命令队列（见下文）。收到回执后 CAD 仍可能正在退出包装器；后续 COM 查询如被暂时拒绝，可有限重试无副作用查询，不重放任务源码。

RunLisp与技能调用同一com.cad.task.run/runTask，journal位于 %LOCALAPPDATA%\aardio\com.cad\journal。底层create只指定doc时不猜产品，默认post/utf8；通常使用增强实例入口。详见兼容说明。

状态与返回值

state	意义
prepared	已创建，本机尚无提交标记
submitted	已认领一次提交机会；不证明 CAD 已接收或执行
running	CAD 已写 started 标记，尚无终态回执
completed	执行与结果序列化成功，`ok=true`、`terminal=true`
error	parse / execute / serialize / transport 等阶段失败，`terminal=true`
rejected	CAD 端发现不是原目标文档或实例
expired	超过最迟开始时间，未进入用户源码
cancelled	CAD 在执行用户源码前接受了取消请求
timeout	本次 wait 等待超时；`terminal=false`，`observedState` 保留实际快照

read() 失败返回 null,err。wait() 对非成功终态返回 result,err；超时也返回快照及错误说明，而不是伪造终态。请检查 result.ok 和 result.terminal，不要只检查 result 是否非 null。CAD 端语法检查会拒绝括号不完整、未闭合字符串/块注释、额外右括号，避免原始源码破坏传输表达式。

超时、去重与取消

同一路径的 submit() 只有一次提交认领。提交标记使用独占创建，多对象/线程/进程争用时只有一个可派发；该认领内对明确的 COM 拒绝接收可有限重试。
CAD 侧再次遇到同一请求的 started/result 标记会跳过执行。不要删除标记、复制命令后改请求 ID、或通过新建任务来“补发”未知操作。
仅 0x80010001 / 0x8001010A 这两类已识别的拒绝接收在同一次认领内重试，预算3秒。其他 COM 异常（包括普通 null 方法错误）保留提交标记，不重试、不推断没有执行；继续查原回执。
timeout 只限制等待回执；startTimeout 限制从创建任务到 CAD 开始执行的时间。两者都不强行中断已开始的 LISP。
cancel() 仅写执行前取消请求。返回 true 表示文件写入成功，只有 cancelled 回执才确认 CAD 接受。已经 running 的任务可以继续完成。
出错可能已有部分绘图。不是事务，不自动 UNDO，不保证跨进程崩溃的 exactly-once。
Esc 是另一条明确授权的 UI 恢复路径，见恢复与图像反馈。发送 Esc 不等于任务取消回执，更不等于回滚。

options

字段	默认值	说明
directory	`%LOCALAPPDATA%\aardio\com.cad\tasks`	其下创建唯一请求目录；应使用 CAD 和调用方都可读写的本地路径
method	AutoCAD/浩辰post，中望send	创建时按增强实例ProgId选择，显式值优先；提交失败后不换方法重放
timeout	10000	wait 默认等待毫秒数，0 表示立即查询；最大 86400000
startTimeout	30000	从创建时计算的最迟开始毫秒数；最大 86400000
nudge	false	true 才允许 wait 自动刷新未开始的 Post 队列；需要原 doc，会同步调用 SendCommand，可能阻塞
nudgeDelay	800	显式启用 nudge 时，从本次 wait 开始等候的毫秒数；0有效，最大86400000
resultEncoding	AutoCAD utf8，中望/浩辰 ansi	UTF-8要求支持三参数open；ANSI受代码页限制，先验证文字往返
codepage	本机系统 ANSI 代码页	`resultEncoding="ansi"` 时用于解码，应与 CAD 输出一致
idleTimeout	3000	RunLisp/runTask前后有限等空闲，0不额外等待；不能打断阻塞COM

method=send 的 COM 调用本身可能阻塞；wait 的超时无法打断一个尚未返回的 COM 方法。PostCommand 也不构成硬实时保证。 强隔离要求应由调用方使用独立工作进程实现，而不是让底层库绑定 Autos。对不兼容的 CAD 先做纯查询小探针，不静默降级或修改安全设置。

队列刷新是显式选项，不是默认兜底

PostCommand 排队到空闲时处理；向非活动文档提交时可能使目标文档成为活动文档，不保证保持当前文档不变。submitted 未开始也可能是交互输入、模态窗口、许可证或系统阻塞，不能一概归因命令通道。优先查原任务及环境，不重发业务源码。

确需刷新时，com.cad.task.open(path,doc) 得到原任务，再调用 task.nudge()。它只对仍 submitted 的 post 任务发送 (princ) 空操作；核对文档名称、文档/应用 HWND，要求原目标仍活动且 CAD 空闲。不激活其他文档，不发送任务源码；成功后记录 nudged。

创建时 nudge=true 可让每次 wait 在达到 nudgeDelay 后最多尝试一次；已有 nudged 标记不再刷新。默认false，旧请求缺少该字段同样不刷新。wait(0) 仅查询，不刷新；超时快照可能含 nudgeError 说明未能刷新的原因。成功刷新也不代表业务完成，仍以原终态回执为准。

nudge 使用同步 SendCommand，可能驱动该实例中其他已排队命令；COM 调用未返回时，wait 超时无法中断它。 如要求纯异步等待，请保持默认值。刷新不等于 Esc、任务取消或回滚。

性能：区分 CAD 内执行和端到端耗时

减少跨进程往返有利于批量工作，但不能把 LISP 循环耗时等同于任务总耗时。2026-09-19 本机 AutoCAD 2026 对照：均新建300个相同的圆、返回300个Handle、缓存ModelSpace、统一重生成一次，三轮交错测量：

优化前完整任务：5.008 / 4.563 / 4.878秒。
相邻短行合并后完整任务：2.497 / 1.620 / 1.590秒；中位数约为原来的三分之一。命令从180行减到49行，不增加缓存服务或CAD插件。
外部COM循环：5.006 / 4.849 / 5.107秒（包含逐个获取Handle）。

这里完整任务从创建到收到回执计时；当时版本LISP内绘图及重生成仅47–110毫秒，不能将它当作端到端耗时。这是2026-09-19传输优化时的runner与数据；后续增加结果类型支持后命令长度不同，不能把旧基准当作后续版本的新测量。

这是单机测量，不是性能保证。完整任务还包含代码生成、提交、CAD 排队、序列化和回执等待。适合批量合并操作，不宜把每个实体都拆成一次任务；少量对象可直接 COM。不要为了缩短等待时间而取消完成确认，也不要把 method=send 当作无条件更快、更安全的替代。

数据协议和限制

数字、字符串、T、nil、列表、点对、实体名可返回。实体名转为 {handle="..."}；句柄必须与原文档配对使用。
UTF-16 输入先统一为 UTF-8 再分块；Unicode 模式下返回的代理对以 JSON Unicode 转义保留，支持中文及非 BMP 字符。ANSI 模式仍受所选代码页限制，不能表示的字符不会因 JSON 封装而恢复。
所有元素都是“字符串键 . 值”的列表转为 JSON 对象，其他正规列表转为数组；重复对象键拒绝序列化。
nil 转 JSON null，T 转 true。LISP 中 false 与 nil、空列表没有独立区分；aardio 的 null 字段/数组项也不能完整保留。需要保留结构时显式使用标签对象。
具有 Handle 的 VLA-OBJECT 转为 {handle="..."}；应用对象等没有 Handle 的对象仍需自行提取属性。VARIANT 自动解包；SAFEARRAY 转正规数组；PICKSET 转 [{handle="..."},…]，受相同结果项数限制；普通符号转名称字符串，T/nil 规则不变。结果解析只用 JSON，不 eval 返回文本。
实数用 AutoLISP rtos 的科学计数模式、精度参数16输出，并去除尾数中冗余的零；不是所有 CAD 版本的 IEEE 754 无损往返承诺。几何检查按单位/量级用容差，精确ID用字符串。配套 JSON 库修复了长科学计数字面值被错误转为 size64 的问题；集成时同步更新 lib/JSON/_.aardio，纯大整数字面值的既有处理保留。
每次源码和参数各限制 128 KiB；结果嵌套最多 48 层/50000 个项，主机拒绝超过 8 MiB 的回执。结果并非流式传输，不适合大图像或巨大数组。
内嵌 NUL、循环数据、不支持的数据类型拒绝传输。二进制数据走文件，回传路径和必要元信息。
传输保留 CR，数据字符串按字符边界分块并用 strcat 组合。库将相邻短行合并到约160字节以内，减少命令行 Enter 开销；较长原分块独立保留，并仍检查768字节硬预算。两者都不是CAD官方上限，不能据此把整个命令压成长行。用户源码先编码为字符串，不因传输折行被改写；回执、去重与超时行为不变。

目录和恢复边界

目录保存 request.json、command.txt、submitted、started、result.json，以及可选 cancel/submit-error.txt/nudged。命令文件在发送前校验哈希，结果先关闭临时文件再改名发布。

目录内含代码、参数和结果，可能包含敏感信息；由调用方控制访问与保留期限。只在确认终态且不再需要审计/恢复后主动清理。禁止自动删除未知任务的目录。硬盘损坏、文件被手工修改、CAD 退出、身份句柄复用等不在“只执行一次”的保证范围内。

文档绑定同时检查文档名称、文档 HWND、应用 HWND；不依赖标题和窗口类名。关闭重开图纸、另存改名或重启 CAD 后，不应提交之前 prepared 的任务，应先人工/业务核对。若原任务 submitted/running，始终以核对回执和实际图纸为先，不能直接重放。

Markdown 格式