何时使用
- 多步骤操作中向用户提供实时视觉反馈
- 后台任务（构建、测试、同步）持续输出状态
- 需要同时追踪消息流和代办事项
首次配置
后台启动需知道 PySide6 环境的 python.exe 路径，运行一次：
conda run -n Nodejs python <script_path> --configure
手动指定：--set-python "C:\path\to\python.exe"。CLI 模式（stop/status/push）不需要配置。
操作
> 所有操作须在项目根目录（含 .opencode/）执行。
| 模式 | 参数 |
|---|---|
| 前台启动 | conda run -n Nodejs python <script_path> |
| 后台启动 | $py = conda run -n Nodejs python <script_path> --discover; Start-Process -WindowStyle Hidden -FilePath $py -ArgumentList '<script_path>' -WorkingDirectory '<项目根目录>' |
| stop | --stop |
| status | --status |
| push | --push <消息> |
| clear | --clear |
| push-todo | --push-todo <文本> |
| toggle-todo | --toggle-todo <索引> |
| clear-todos | --clear-todos |
| toggle-stats | --toggle-stats |
直接写 JSON（subagent 场景）
from pathlib import Path; import json; from datetime import datetime
fp = Path.cwd() / '.opencode/temp/notify.json'
fp.parent.mkdir(parents=True, exist_ok=True)
data = {'messages': []}
if fp.exists():
try: data = json.loads(fp.read_text('utf-8'))
except: pass
data['messages'].append({'t': datetime.now().strftime('%H:%M:%S'), 'm': '消息', 'level': 'info'})
if len(data['messages']) > 12: data['messages'] = data['messages'][-12:]
fp.write_text(json.dumps(data, ensure_ascii=False), 'utf-8')
代办用 .opencode/temp/notify-todos.json，格式 {"todos": [{"text": "...", "done": false, "t": "HH:mm:ss"}]}。
长任务工作流
- 后台启动 overlay →
--status确认 → 每步--push→ 完成--stop - 代办用
--push-todo添加，点击窗口内事项切换完成状态 - 注意：从 TODO.md 等来源推送代办时，AI 必须过滤已完成项（
- [x]），只推送未完成事项。cmd_todo_push会自动跳过空行、- [x]标记和重复项，但仍建议 AI 侧先做过滤。
文件
| 文件 | 用途 |
|---|---|
.opencode/temp/notify.json |
消息 IPC |
.opencode/temp/notify-todos.json |
代办 IPC |
.opencode/temp/notify.pid |
PID 文件 |
.opencode/notify-config.json |
配置（--configure 生成） |
