任务管理台

概述

任务总控面板

这个技能解决什么

AI 助手的工作方式是对话流。任务一多，对话就多；想在几十个对话里找回上周那份产物，或者回到某个任务继续往下做，只能靠翻。

本技能把这些散落的对话收敛成一个本地网页面板：谁在跑、谁跑完了、产出了什么、按业务板块归位，点一下就能跳回原对话继续。

核心原则

只读，不干预。

面板以 mode=ro + PRAGMA query_only 打开状态库，只列目录不打开产出物本体。它不写WorkBuddy 任何数据、不改定时任务、不注册开机自启、不收集也不上传任何东西。

它是旁观者，不是管家。用户对 AI 的掌控力不因装了面板而改变。

服务只绑 127.0.0.1，外部网络访问不到。

何时用

• 用户说「我的任务太散了」「找不到上周那个产物」「做个面板看看我在跑什么」
• 任务数量已经多到对话流本身成为负担
• 需要一个统一视角看「哪些在跑、哪些有结果、哪些卡住了」

不适用：单个任务、临时问答、只需要看某一个产出物的场合。

部署

先预览，再落地。 不要跳过 --preview 直接装。

python scripts/install.py --preview

用户确认后再执行：

python scripts/install.py

常用参数：

部署做四件事：复制 10 个程序文件、生成 boards.py、生成 config.json、建桌面图标。不会覆盖已存在的 config.json 和 boards.py，重跑部署是安全的。

install.py 不覆盖已有配置，只在 db_path 为空时补填——用户的自定义不该被一次重装冲掉。

四个步骤走完

1. 环境检查

python scripts/check_environment.py

输出 ready / partial / needs_setup / unavailable 四种状态，按提示处理，不要一股脑把所有依赖都装上——可选依赖缺失不影响主功能。

2. 改板块配置

打开安装目录下的 boards.py，把 BOARDS 改成用户真实的工作板块：

{
    'name': '客户项目',
    'color': '#854F0B',
    'kw': ['客户', '合同', '方案','报价'],# 命中标题/文件名
    'path': ['clients/', 'projects/'],     # 命中产出物路径，权重更高
}

不确定怎么填就先跑一次分类看分布，再回来调。板块顺序即优先级（同分时靠前的赢），「未归类」会被强制移到末尾。

boards.py 语法错误或 BOARDS 为空时自动回退内置默认并给出警告，不会崩。

3. 首次分类

python classify.py

输出四个快照：out/tags.json（任务与归位）、out/pending.json（低置信度待复核）、out/artifacts.json（产物清单）、out/overrides.json（人工修正表，存在则优先采纳）。

低置信度的任务不硬归，进pending.json 等人工确认。宁可留白，不要给一个没有依据的归类结论。

4. 启动

python launch.py     # 打开 http://127.0.0.1:8899
python stop_all.py   # 停止

语音提醒

默认离线通道（Windows SAPI5），播报内容不出本机。

用户想要更自然的声音时，先告知在线通道会把播报文本提交给微软的语音服务，用户同意后才pip install edge-tts 并把 config.json 的 engine 改成 online。

用户没明确同意前保持 offline。不要为了声音好听就擅自外发文本。

举手提醒

面板内置举手协议：AI 遇到需要用户拍板的决策点时主动留痕并播报，用户在面板上看到并处理。

举手是 AI 的动作，不是用户的动作。 不要向用户索要举手入口，不要放「举手示意」按钮，不要让用户填表上报。

python scripts/raise_hand.py -S <会话id> -s 客户项目 "方案有 A/B 两版，请定夺"

raise_hand.py 写完记录立即同步播报一次即退出，不常驻。

详见内置的 task-raise-hand 技能。

必须带会话 id

深链 workbuddy://chat/{sessionId} 靠会话 id 才能跳回原对话。不带 id 就只是一段文字，用户看得到却点不动——等于没汇报。

会话 id 就是 workbuddy.db 的 sessions.id（标准 UUID）。拿不到就不要瞎填，不带 id举手仍然有效，只是用户无法一键跳回。

深链的一号坑

ELECTRON_RUN_AS_NODE=1 污染环境变量会导致深链静默失效——不报错、什么都不发生。

调用前必须清掉这个环境变量，然后直启 exe，不经由任何 node 包装层。

拿不到会话 id 时，面板不应显示跳转入口。有入口却点了没反应，是 bug，要报回来。

不做的事

以下任何一项若出现在代码里，都属于缺陷：

• 写 workbuddy.db 或 artifact-index/
• 创建或修改 WorkBuddy 的定时任务
• 注册开机自启
• 收集或上传任何数据
• 抢占已被占用的端口（改端口，不抢占）

数据源的诚实边界

workbuddy.db 的字段结构是逆向所得，不是官方承诺稳定的接口。WorkBuddy 升级后结构可能变化。

几个必须记住的坑：

• sessions.status 只有 working / completed / error，没有更细的状态
• 删掉的会话 status 不会改，只有 deleted_at 可信
• automations.last_run_at 不可信，不能用它判断定时任务状态
• automation_runs.thread_id ≠ sessions.id，不要直接 join

因此读不到预期结构时降级为展示上一次快照并标注生成时间，不要编造字段。全部字段用COALESCE 兜底。

完整说明见 references/data-and-gotchas.md。

排查

先看 python classify.py 输出，再看 python scripts/selfcheck.py。

逐条排查见 references/troubleshooting.md。

参考文件