1. 在Windows上跑任务，为什么必须把"完成通知"当回事
1.1 长任务消耗的是"注意力"，不是时间
在Windows上跑构建、批量转码、数据同步这类长任务，最大的痛点其实不是机器慢，而是你的注意力被绑死了。任务一跑十几分钟，你盯着终端看吧，什么也看不出来，纯属浪费时间；不盯着吧，又想知道什么时候跑完，结果怎么样，只能隔几分钟切回来扫一眼。我见过不少同事的做法是干脆把终端窗口拉大铺满副屏，美其名曰"监控任务"，实际就是在干等。
更麻烦的是有些任务跑完以后不会自己停下来，也不会喊你，就安安静静停在那里等你翻日志。等你想起来回去看的时候，可能已经过去半小时了，该处理的事全被耽误了。所以"任务完成之后主动通知你"这件事，看起来只是锦上添花，实际是把人从任务的等待循环里解放出来的关键一步。我尝试过Windows自带的任务计划程序弹窗、定时检查日志文件之类的土办法，都不够顺，直到把iFlow CLI的hook机制用起来，才算把整条链路真正打通。
1.2 iFlow CLI、hook、通知这三者各管什么
简单捋一下这三者的关系。iFlow CLI在这里承担的是任务编排和执行的入口，你用它的配置定义好一个任务里有哪几步，然后通过命令行跑起来。hook是iFlow在任务生命周期里预留的"钩子"，相当于任务跑到某一个节点时，框架主动喊你一声，让你有机会去执行一段额外的逻辑。通知则是hook里实际做的那件事——把"任务跑完了"这个事实，转化成你能感知到的信号。
用流水线的例子来类比：iFlow像是一条自动化流水线，任务往下走；hook是装在流水线出口的传感器；通知则是传感器触发的电铃。没有电铃的时候，你得时不时自己跑过去看一眼产品有没有出来；有了电铃，你该干嘛干嘛，听见响再过去就行。
这套玩意的核心思路就是：把"轮询"变成"回调"。轮询是人去问机器"你好了吗"，回调是机器主动告诉你"我好了，结果是这样"。在后者的模式里，你省下的是反复切窗口、反复瞄终端的隐性成本，积少成多，一天下来能省出不少精力。
2. iFlow CLI的hook机制：它在任务生命周期里到底插手了哪一环
2.1 事件模型：on_start / on_complete / on_fail 三个触发点
iFlow CLI的hook机制，本质上是围绕任务生命周期里的几个关键节点来做事件分发。我这边常用到的触发点有三个：on_start（任务开始时）、on_complete（任务正常结束时）、on_fail（任务失败时）。你可能会说，我只想加个完成通知，直接挂on_complete不就行了？话是这么说，但我建议你把on_fail也一起挂上，因为任务失败恰恰是最需要通知的场景之一。
我在这里用过的一个典型配置大概长这样：
hooks: on_start: - command: powershell args: ["-File", "C:\\iflow-hooks\\start.ps1", "$IFLOW_TASK_NAME"] on_complete: - command: powershell args: ["-File", "C:\\iflow-hooks\\done.ps1", "$IFLOW_TASK_NAME", "$IFLOW_EXIT_CODE"] on_fail: - command: powershell args: ["-File", "C:\\iflow-hooks\\fail.ps1", "$IFLOW_TASK_NAME", "$IFLOW_EXIT_CODE"]为什么推荐用框架的事件而不是自己在任务脚本末尾加一段通知逻辑？因为iFlow的hook能保证"任务无论从哪条路径结束都会触发"。你自己写，很容易漏掉异常分支、提前return的路径、还有被外部Ctrl+C中断的情况。用hook做，相当于让框架来兜底，通知覆盖更完整。
2.2 hook能拿到什么数据：任务名、退出码、耗时与摘要
我第一次写hook脚本时最困惑的一件事是：脚本里到底能拿到哪些信息？实际用下来，iFlow往hook脚本里注入的变量通常包含了任务名、退出码、耗时、以及输出摘要这几类。退出码尤其重要，它直接告诉你"这个任务到底成没成"——很多跑批任务不会因为报错就中断，照样给你返回一个非零退出码，所以拿退出码来判断结果远比拿"是否弹窗"更靠谱。
我在通知弹窗里显示的内容一般包括三行：
- 第1行：任务名，让你一眼知道是哪个任务跑完了；
- 第2行：退出码和耗时，一条信息同时讲清楚"结果"和"代价"；
- 第3行：输出摘要的前几句，比如"完成 12 个文件，其中 2 个跳过"。
这些内容在hook脚本里拿起来很直接，关键是你要在配置阶段就把你想用的变量明确定义好，并在脚本里接受对应的参数。不要只在脚本里写死"任务完成"四个字，那样通知的价值就少了一大半。
2.3 挂载方式：全局hook和任务级hook怎么选
iFlow的hook既可以在全局配置里挂，也可以在单个任务的定义里挂。全局hook的好处是"一次配置，所有任务通吃"，适合做统一的完成弹窗；任务级hook则适合给关键任务单独定制行为，比如"编译任务跑完要响Loud声音提醒，数据同步任务跑完要推手机通知"。
实际的选型逻辑，我是这么把握的。全局hook里只放通用的动作：弹窗、写统一日志、播放提示音。任务级hook放特殊化的动作：按任务名分流、指定不同的webhook推送地址、对失败任务做额外告警。两条链路共用同一套hook脚本目录，但脚本本身通过接收到的任务名做分支处理。这样既不重复，又灵活。
3. Windows端准备：把CLI、执行策略和通知脚本骨架一次搭好
3.1 安装iFlow CLI并解决PATH没生效的问题
在Windows上装iFlow CLI本身不复杂，下载对应的Windows版本压缩包，解压到固定目录，然后把可执行文件所在目录加进系统PATH即可。这里有一个所有人都容易踩的坑——加完PATH之后，当前已经开着的终端窗口不会自动生效，必须新开一个PowerShell窗口，iFlow这个命令才能被识别到。我因为没注意这个，曾经一度以为装失败了，反复重装了半天才发现是终端没重启。
装好之后，第一时间执行一下版本检查：
iflow --version能正常输出版本号，说明CLI本体没问题。然后再执行：
iflow --help简单扫一眼当前版本的命令结构。我之所以强调这个，是因为iFlow不同小版本之间，hook配置的字段名偶尔会有微调，以本地版本的帮助输出为准永远是最稳妥的。不要盲目照抄网上过时的配置。
3.2 PowerShell执行策略：为什么你的通知脚本可能直接被拦
Windows默认的PowerShell执行策略对脚本文件的运行限制很严。默认情况下，本机脚本可能直接被禁止运行，你辛辛苦苦写好了通知脚本，iFlow调用起来却可能被系统拦下，任务倒是正常跑完了，可你压根收不到任何通知，甚至日志里都看不出异常。
解决方式是在管理员PowerShell里修一下当前用户的执行策略：
Set-ExecutionPolicy -Scope CurrentUser RemoteSignedRemoteSigned的意思是：本机创建的脚本允许运行，从网络下载的脚本需要签名。对于自己写的通知脚本来说，这个程度刚刚好，既放开了本机脚本的限制，又保留了一定的安全校验，比一刀切设成Unrestricted要稳妥得多。
设置完以后，可以用Get-ExecutionPolicy确认一下当前值，显示RemoteSigned就说明策略生效了。这个步骤看着小，漏掉的人却不少，属于典型的"配置全对但完全不工作"。
3.3 通知脚本骨架：第一个能用的Windows弹窗
我习惯把所有hook脚本统一放在一个目录里，比如C:\iflow-hooks\，文件名直接按用途来。第一个通知脚本我建议先用最朴素的Windows弹窗实现，一步到位，后续再扩展别的渠道。
这是一个最基础的PowerShell弹窗脚本：
param( [string]$TaskName, [string]$ExitCode ) Add-Type -AssemblyName System.Windows.Forms Add-Type -AssemblyName System.Drawing [System.Windows.Forms.MessageBox]::Show( "任务 $TaskName 已完成，退出码: $ExitCode", "iFlow 任务通知", [System.Windows.Forms.MessageBoxButtons]::OK, [System.Windows.Forms.MessageBoxIcon]::Information )这段代码本身不复杂：Add-Type引入Windows窗体所需的程序集，然后调用MessageBox.Show弹出一个消息框。第一行显示任务名和退出码，第二行是标题，后面跟着的枚举参数控制按钮样式和图标。
光把这个脚本存成UTF-8编码的文件还不行——Windows PowerShell 5.1对无BOM的UTF-8文件识别有问题，中文大概率变成乱码，这个坑后面专门说。现在你只需要记住：保存脚本时选择"UTF-8 with BOM"编码，或者直接用GBK/ANSI编码保存，就不会出乱码。
4. 第一次接通：从任务完成到Windows弹窗的完整链路
4.1 在iFlow里挂on_complete钩子
现在进入正题：把上面的PowerShell脚本挂到iFlow的on_complete事件上。不管你是用全局配置文件还是任务定义文件，原理是一样的——找到hooks节点，把on_complete下面挂上一个命令调用。
我实际用的配置片段是这样：
tasks: build: command: "dotnet build MyApp.sln" hooks: on_complete: - command: powershell args: ["-File", "C:\\iflow-hooks\\done.ps1", "$IFLOW_TASK_NAME", "$IFLOW_EXIT_CODE"]在这个配置里，build任务执行dotnet build，任务一结束，iFlow就会调用PowerShell去执行done.ps1。$IFLOW_TASK_NAME和$IFLOW_EXIT_CODE是iFlow注入的两个变量，会在调用时替换成实际的值，传给脚本的参数。这一步做好以后，执行：
iflow run build任务跑完，你的屏幕上应该会弹出一个系统消息框。第一次看到这个弹窗的瞬间还是很有成就感的——说明"任务完成主动找你"这件事真的跑通了。
4.2 把任务名和退出码带进通知内容
通知内容里带上任务名和退出码，不是锦上添花，而是必需。我举个实际例子：我跑一个批量图片压缩任务，它处理100张图，中间有3张损坏的图被跳过了，但任务整体退出码是0。如果你只弹一个"任务完成"的窗，你会以为一切顺利；如果你的弹窗显示"退出码: 0，跳过: 3张"，你就知道该去把不够完美的地方修复一下。
所以我在hook脚本里通常还会做一个简单的判断，让不同退出码的弹窗颜色和图标不一样：
if ($ExitCode -eq "0") { $icon = [System.Windows.Forms.MessageBoxIcon]::Information } else { $icon = [System.Windows.Forms.MessageBoxIcon]::Warning } [System.Windows.Forms.MessageBox]::Show( "任务 $TaskName 结束（退出码: $ExitCode）", "iFlow 任务通知", [System.Windows.Forms.MessageBoxButtons]::OK, $icon )这样每次弹窗，不看内容光看图标，就知道这轮任务到底是顺顺利利还是出了岔子。别小看这个细节，任务跑多了以后，视觉上的快速区分比逐字读内容高效得多。
4.3 分层验证：先验脚本，再验hook，最后验通知
在第一次接通的过程中，最容易让人头大的问题是"配置了但什么都没发生"。这种时候不要慌，按照"脚本本身 → hook触发 → 通知送达"三层链路去排查，很快就能定位。
第一层，先手动执行hook脚本本身。直接打开PowerShell，调用你的通知脚本并传入假数据：
powershell -File C:\iflow-hooks\done.ps1 "test_task" "0"如果弹窗能正常出来，说明脚本本身没问题，问题出在iFlow的配置或者触发环节。第二层，跑一个最小的iFlow测试任务，故意让它成功结束，观察hook有没有被调到。第三层，如果hook触发了但通知没看到，检查执行策略、脚本编码、路径权限。这三个层次是逐层嵌套的，哪一层断掉直接去修哪一层，就不要整条链路推倒重来。
5. 让通知真正"个性化"：按任务分流、推手机、沉淀日志
5.1 用任务名做分支：不同任务用不同通知形式
一套通知脚本打天下，用久了难免觉得不爽——编译失败和文件同步完成，这两件事的紧急程度完全不同，怎么能用同一种方式通知呢？我的做法是写一个统一的"分发脚本"，根据传入的任务名决定走哪条通知分支。
switch ($TaskName) { "build" { # 编译类任务：弹窗 + 提示音 [System.Console]::Beep(800, 300) Show-MessageBox $TaskName $ExitCode } "sync_data" { # 同步类任务：写日志 + 手机推送 Write-LogEntry $TaskName $ExitCode Send-WebhookMessage $TaskName $ExitCode } default { # 其他任务：只弹窗 Show-MessageBox $TaskName $ExitCode } }这个设计的好处是，新加一种任务类型，只需要往switch里加一个分支，其他什么都不用动。我把常用分支写成PowerShell函数，放在脚本头部，后面就是一行一行逻辑清晰的分发调用。看起来很简单，但正是这种简单可扩展的框架让我在后续接任务时几乎不用再改通知体系。
5.2 手机端通知：把结果通过webhook推到微信/钉钉
弹窗再方便也有边界——你的视线必须停在Windows机器附近。真正解决"人不在电脑前"这个问题的，是把通知推到手机端。实现方式并不是多复杂，常见的做法是通过各类群机器人webhook，把消息推送到微信、钉钉或者企业微信群。
PowerShell里调用webhook的代码很短：
function Send-WebhookMessage { param([string]$TaskName, [string]$ExitCode) $payload = @{ msgtype = "text" text = @{ content = "任务 $TaskName 结束，退出码: $ExitCode" } } | ConvertTo-Json Invoke-RestMethod -Uri $env:IFLOW_WEBHOOK_URL -Method Post -ContentType "application/json; charset=utf-8" -Body $payload }把webhook地址放在环境变量里，而不是写死在脚本中，这样脚本既可以在不同机器上复用，又不会把敏感地址泄露到代码仓库里。我建议你给不同类型的任务配置不同的webhook地址，或者至少在消息内容里加上任务名前缀，方便在手机端快速过滤。
5.3 日志型通知：把每次结果沉淀成可统计的CSV
实时通知解决的是"当下要知道"，日志通知解决的是"以后要能回顾"。我跑的任务多了之后，慢慢发现一个需求：想知道这周任务失败率是多少、平均耗时多少、哪类任务最容易出问题。这些数据如果每次跑完顺手记一笔，积累下来就非常有价值。
在hook脚本里追加一行CSV记录，逻辑也很简单：
$logLine = "{0},{1},{2},{3}" -f ` (Get-Date -Format "yyyy-MM-dd HH:mm:ss") ` $TaskName $ExitCode $DurationSeconds Add-Content -Path "C:\iflow-hooks\task_history.csv" -Value $logLine -Encoding UTF8每次任务完成，这条记录就会追加到CSV文件里。后续用PowerShell的Import-Csv或者Excel打开，就能直接做统计。我觉得这一层很容易被人忽略，但它恰恰是通知体系里"长期主义"的那部分——短期看是通知，长期看是数据资产。
6. 避坑记录与排查链路：hook不触发、通知丢失、中文乱码
6.1 "hook没反应"的完整排查顺序
这个坑我踩过好几次，每次几乎都出在同样的环节。按我总结的顺序排查，基本十分钟内能定位：
第一步，确认iFlow确实跑的是你改的那份配置。有时候你改了任务定义，但执行时用的还是老的全局配置，或者终端的工作目录不对，iFlow压根没读到你的文件。用iflow run --debug跑一次，看看日志里加载了哪个配置文件，这一步能排掉大半问题。
第二步，确认hook事件名没写错。on_complete、on_fail这些都是有固定拼写的事件名，多一个字母少一个字母都会导致钩子静默失效。我在早期版本里遇到过写成onComplete导致完全不触发的情况，一屏日志翻下来毫无线索。
第三步，确认hook脚本路径是绝对路径，且PowerShell能够访问。路径里如果有空格，记得在配置里用引号包好；如果路径指向网络位置或者特殊权限目录，PowerShell可能根本没有读取权限。
第四步，看iFlow的调试日志。多数时候日志里会明确打印"hook executed"或者"hook failed"字样。看到failed就顺着去看具体异常，基本就是脚本路径、参数、执行策略这三类原因，没有更玄学的了。
6.2 弹窗一闪而过和通知静默失败
如果你配置完了，感觉什么反应都没有，但任务本身跑得正常，那十有八九是通知脚本执行时报错，但错误被静默吞掉了。PowerShell在非交互式调用时，脚本里的报错不会以弹窗形式跳出来给你看，只是默默地写进stderr，如果你没有查看hook日志，就会以为是"什么都没发生"。
我的解决办法很暴力但很有效：在hook脚本入口处，强制把所有输出写入日志文件：
Start-Transcript -Path "C:\iflow-hooks\hook_debug.log" -Append然后脚本里所有的输出、报错都会被记录下来。排查完以后把这行注释掉就行了。通过日志，你会迅速看到是脚本本身崩了，还是参数传错了，还是执行策略拦了脚本。这一步往往是整个排查链条里最省时间的一步。
另一个常见的"弹窗一闪而过"场景是：你的弹窗代码没问题，但脚本在弹窗显示前就先崩了。这时候加Start-Transcript比加各种try-catch更好使，因为你能直接看到崩在哪一行。
6.3 PowerShell读UTF-8无BOM脚本导致的中文乱码
Windows PowerShell 5.1默认读取脚本文件时，如果文件是UTF-8编码但没有BOM头，它就会按系统默认的ANSI编码去解码，中文字符直接变成一串乱码，严重时甚至会直接语法报错。这个问题只出现在Windows PowerShell 5.1及更早版本上，PowerShell 7及以后版本对UTF-8的处理已经好很多，但很多Windows机器默认装的还是5.1，不能忽略。
解决办法有两种。第一种是用支持UTF-8 BOM的编辑器保存脚本，比如VS Code里，右下角点击编码按钮，选择"通过编码保存"，选"UTF-8 with BOM"。第二种是给系统装PowerShell 7，直接用现代版本。我建议你至少把通知脚本统一用带BOM的UTF-8保存，一劳永逸，不依赖运行环境。
6.4 hook脚本的职责边界：只做通知，不干重活
最后要说的是hook脚本的职责边界。很多人一旦发现hook这么好用，就开始把各种逻辑往里塞，比如在hook里做数据备份、在hook里改数据库状态、在hook里触发下一个任务。我很不建议这么做。
原因有两点。第一，hook的执行会影响任务收尾的时长，如果hook里跑一个耗时的操作，任务在终止阶段会一直挂在那里，看起来就像"任务跑了半天还在结束中"。第二，hook本身的稳定性不该成为任务结果的负担。通知发不出去，最多是没收到消息，任务该完成的还是完成了；但如果你在hook里塞了业务逻辑，hook一崩，本来应该做的那件事也跟着丢了。
所以我的原则是：hook脚本里只做轻量的、尽力而为的通知动作——弹个窗、写行日志、发个webhook。需要做重活的时候，用Start-Process把重活丢进一个独立进程去异步执行，hook本身立刻返回。这也是我自己把通知体系跑了几个月之后总结出的最实在的一条经验：hook做得越轻，整条链路就越稳。
最后再分享一个小习惯：我已经把通知脚本全部收拢到C:\iflow-hooks\目录下，每个脚本名字对应一类通知动作，所有iFlow任务统一挂一个入口hook，由这个入口根据任务名分发。后续新任务接入时，复制配置、加一个switch分支就完事了。这套东西从第一次弹窗到跑通手机推送，我用了一个下午；但真正让我觉得值回票价的，是之后每次任务跑完都不用再回头盯着终端，该干嘛干嘛，通知自己会来。
