【声明】本博客所有内容均为个人业余时间创作所述技术案例均来自公开开源项目如GithubApache基金会不涉及任何企业机密或未公开技术如有侵权请联系删除标题192、【Agent】【OpenCode】TuiThreadCommand handler从参数到 Worker 就绪背景上篇 blog【Agent】【OpenCode】TuiThreadCmd类型推导收尾分析了 TuiThreadCmd 命令背后 yargs 的类型推导infer D是必要的兜底当开发者省略type只写default时类型也能从默认值推断出来而一旦type与default同时出现type作为显式契约拥有最终解释权别名AliasO的值类型从同一个配置O推导保证别名与主参数名的类型永远一致最后还比较了.option()的两个重载——精确匹配在前、宽泛匹配在后顺序颠倒就会导致精确重载永远无法触发。上篇停在命令是怎么声明的本篇顺着handler往下走看看命令真正启动 TUI 前代码先做了哪些准备工作OpenCodethread.ts:101的handler是命令行参数 → TUI 界面的最后一公里。有意思的是它的第一段不是解析参数、也不是起 Worker而是两行 Windows 防御代码在 Windows 上ENABLE_PROCESSED_INPUT置位时 CtrlC 会变成CTRL_C_EVENT信号直接杀掉整个进程组所以 handler 一进来就把它关掉并装上**持续压制**的守卫退出时再通过unguard还原。这套机制完整原理FFI 加载 kernel32、三层守卫、unhook 还原涉及另一处源码本篇先简单带过后续文章再详细拆解。第一关fork 参数校验--fork的语义是在旧会话基础上分叉出新会话必须有--continue或--session提供来源。校验失败不抛异常而是UI.error提示 process.exitCode 1 直接return把退出码留给 shell 判断干净利落。️第二关工作目录解析这里有个容易被忽略的细节root用process.env.PWD优先、process.cwd()兜底。注释说明原因——相对--project路径要从启动时的目录解析而不是 chdir 之后。解析完成后chdir到项目目录再取 chdir 后的真实cwd作为后续所有操作的 directory key保证 thread 和 worker 看到的是同一个目录。⚙️第三关Worker 启动与三级回退启动 Worker 前先要决定 worker 脚本从哪来target()给了三个来源优先级从高到低构建期注入的环境变量OPENCODE_WORKER_PATH→ 打包产物worker.js→ 开发态源码worker.ts。也就是说生产环境直接用环境变量指定路径没指定就用编译产物只有裸开发环境才回退到源码。注意env的处理先把值为undefined的环境变量过滤掉避免空值污染子进程环境worker.onerror只负责把加载错误记进日志不中断主流程。第四关RPC 客户端与信号绑定client通过 RPC 协议与 worker 通信typeof rpc让client.call有完整类型推断。主线程挂了三个兜底未捕获异常、未处理 Promise 拒绝都只记日志SIGUSR2信号触发热重载——发一个reloadRPC 让 worker 自己重载。第五关幂等清理 stopstop用stopped标志保证只执行一次先撤掉前面挂的三个监听再发shutdownRPC 让 worker优雅退出——withTimeout(..., 5000)给 5 秒超时超时或失败只warn不抛错最后worker.terminate()兜底强杀。整个顺序是软关闭→超时兜底→强制终止三级递减。一句话记忆真正的 TUI 启动之前handler 要先过五关防 CtrlC、校验 fork、chdir 统一目录、target()三级回退拉起 Worker、挂上 RPC 与兜底监听最后备好一个幂等的 stop 兜底清理。到这里从参数到 Worker 就绪才算完成。OK本篇先到这里如有疑问欢迎评论区留言讨论祝各位功力大涨技术更上一层楼下篇 blog 继续拆 handler 的后半段——transport 双形态external / internal RPC 代理、延迟升级检测与 TUI 启动收尾【Agent】【OpenCode】TuiThreadCommand handlertransport 双形态与 TUI 启动 192、【Agent】【OpenCode】TuiThreadCommand handler：从参数到 Worker 就绪
【声明】本博客所有内容均为个人业余时间创作所述技术案例均来自公开开源项目如GithubApache基金会不涉及任何企业机密或未公开技术如有侵权请联系删除标题192、【Agent】【OpenCode】TuiThreadCommand handler从参数到 Worker 就绪背景上篇 blog【Agent】【OpenCode】TuiThreadCmd类型推导收尾分析了 TuiThreadCmd 命令背后 yargs 的类型推导infer D是必要的兜底当开发者省略type只写default时类型也能从默认值推断出来而一旦type与default同时出现type作为显式契约拥有最终解释权别名AliasO的值类型从同一个配置O推导保证别名与主参数名的类型永远一致最后还比较了.option()的两个重载——精确匹配在前、宽泛匹配在后顺序颠倒就会导致精确重载永远无法触发。上篇停在命令是怎么声明的本篇顺着handler往下走看看命令真正启动 TUI 前代码先做了哪些准备工作OpenCodethread.ts:101的handler是命令行参数 → TUI 界面的最后一公里。有意思的是它的第一段不是解析参数、也不是起 Worker而是两行 Windows 防御代码在 Windows 上ENABLE_PROCESSED_INPUT置位时 CtrlC 会变成CTRL_C_EVENT信号直接杀掉整个进程组所以 handler 一进来就把它关掉并装上**持续压制**的守卫退出时再通过unguard还原。这套机制完整原理FFI 加载 kernel32、三层守卫、unhook 还原涉及另一处源码本篇先简单带过后续文章再详细拆解。第一关fork 参数校验--fork的语义是在旧会话基础上分叉出新会话必须有--continue或--session提供来源。校验失败不抛异常而是UI.error提示 process.exitCode 1 直接return把退出码留给 shell 判断干净利落。️第二关工作目录解析这里有个容易被忽略的细节root用process.env.PWD优先、process.cwd()兜底。注释说明原因——相对--project路径要从启动时的目录解析而不是 chdir 之后。解析完成后chdir到项目目录再取 chdir 后的真实cwd作为后续所有操作的 directory key保证 thread 和 worker 看到的是同一个目录。⚙️第三关Worker 启动与三级回退启动 Worker 前先要决定 worker 脚本从哪来target()给了三个来源优先级从高到低构建期注入的环境变量OPENCODE_WORKER_PATH→ 打包产物worker.js→ 开发态源码worker.ts。也就是说生产环境直接用环境变量指定路径没指定就用编译产物只有裸开发环境才回退到源码。注意env的处理先把值为undefined的环境变量过滤掉避免空值污染子进程环境worker.onerror只负责把加载错误记进日志不中断主流程。第四关RPC 客户端与信号绑定client通过 RPC 协议与 worker 通信typeof rpc让client.call有完整类型推断。主线程挂了三个兜底未捕获异常、未处理 Promise 拒绝都只记日志SIGUSR2信号触发热重载——发一个reloadRPC 让 worker 自己重载。第五关幂等清理 stopstop用stopped标志保证只执行一次先撤掉前面挂的三个监听再发shutdownRPC 让 worker优雅退出——withTimeout(..., 5000)给 5 秒超时超时或失败只warn不抛错最后worker.terminate()兜底强杀。整个顺序是软关闭→超时兜底→强制终止三级递减。一句话记忆真正的 TUI 启动之前handler 要先过五关防 CtrlC、校验 fork、chdir 统一目录、target()三级回退拉起 Worker、挂上 RPC 与兜底监听最后备好一个幂等的 stop 兜底清理。到这里从参数到 Worker 就绪才算完成。OK本篇先到这里如有疑问欢迎评论区留言讨论祝各位功力大涨技术更上一层楼下篇 blog 继续拆 handler 的后半段——transport 双形态external / internal RPC 代理、延迟升级检测与 TUI 启动收尾【Agent】【OpenCode】TuiThreadCommand handlertransport 双形态与 TUI 启动