前言¶
在 DSH 的插件化使用方式中，定時任務通常有兩個具體需求：一是希望按 cron 週期自動執行一段寫好的 prompt，而不是每次從頁面手動觸發；二是執行過程最好落在真實 agent 會話裏，保留會話或項目上下文。
dsh-timer-agent 是一個 DSH Web GUI 插件，提供 host 常駐定時任務引擎：dsh web 服務啓動即生效，瀏覽器 GUI 關閉也照常觸發。下面介紹它的功能、安裝方式和需要注意的限制。
這是什麼¶
dsh-timer-agent 由 LouisHaoL 維護，許可證爲 MIT。它把 5 段 cron 調度、真實 agent 會話執行、模型工具 timer_agent 和 Web GUI 任務面板放在同一個插件裏，用於完成“到點自動執行 prompt，也能到點直接運行命令”的無人值守任務。
核心功能¶
定時調度¶
- 支持 5 段 cron：分、時、日、月、周。
- 支持
*、*/n、a-b、逗號列表。 - 提供 cron 預設下拉：每天 09:00、每小時、每 10 分鐘、每週一 09:00。
任務目標¶
- 指定已有會話：每次觸發繼續該對話，選中會話即釘住該對話。
- 指定項目 workdir：在該項目內新建會話運行。
- 兩者都留空：在默認工作空間新建會話發起新對話。
- 目標樹選擇器按項目分組，可摺疊，可選已有會話或新增會話。
管理入口¶
- Web GUI 側邊欄出現「定時任務」入口，任務面板提供列表、搜索過濾、詳情頁。
- 詳情頁支持 cron 編輯、執行歷史、跳轉會話 transcript、立即執行、重置、刪除。
- 對話中可通過
timer_agent模型工具管理任務，動作包括create/list/update/pause/resume/archive/restart/remove/run。 - 插件會註冊
plugin:timer-agent播報段，向 agent 告知本插件能力與協作方式。
普通命令任務¶
除 AI Agent 任務外，還支持普通任務（命令）：到點直接 spawn 命令+參數，可選工作目錄、超時，不經過 AI、不消耗額度。stdout / stderr 尾部（≤16k 字符）與退出碼隨執行記錄入賬。
安裝與啓用¶
先獲取插件目錄，再使用本機絕對路徑安裝：
dsh plugin --profile web add link:<本目錄絕對路徑>
安裝後重啓 dsh web。側邊欄出現「定時任務」入口即生效。
典型用法¶
創建 AI Agent 定時任務¶
1、在 DSH 對話中調用 timer_agent 工具，使用 create 動作創建任務。
2、填寫 5 段 cron，例如：
0 9 * * *
prompt 必須自包含，不能依賴現場提問。
3、選擇目標：已有會話、項目 workdir，或兩者都留空使用默認工作空間。
4、保存後等待到點觸發，也可以在任務詳情頁使用“立即執行”。
創建普通命令定時任務¶
1、使用 timer_agent 或 Web GUI 新建普通任務（命令）。
2、填寫命令+參數，必要時指定工作目錄和超時。
3、到點觸發後，執行記錄會保留 stdout / stderr 尾部（≤16k 字符）和退出碼。
適用場景與注意¶
dsh-timer-agent 適合在受控的本機或私有環境中使用。它適合把自包含的 prompt 定時交給 agent 會話執行，也適合定時運行自己審查過的腳本。
使用前請檢查源碼與許可證。該插件中普通任務會在你的機器上以當前用戶權限執行任意命令，沒有任何沙箱或白名單。API 路由僅迴環 + 同源可訪問，但仍需要注意以下限制：
- 任何能新建/編輯任務的人、能調用
timer_agent工具的 agent 會話、能訪問迴環 API 的本機進程，都可能讓任意程序定時運行。 - 任務臺賬
~/.dsh/timer-agent/jobs.json可被篡改即等價於本機任意代碼執行；謹慎使用。 - 不要把該插件暴露給不可信環境。
- 定時執行依賴
dsh web服務進程存活；服務停了不觸發，重啓後只跑已順延到期的任務，錯過即跳過。 - 任務運行中到點跳過本次，等下一個 cron 匹配點。
- AI Agent 任務執行消耗 API 額度；定時執行無人在場，prompt 必須自包含、不可提問。
結尾¶
dsh-timer-agent 的價值在於把 DSH 的定時執行從頁面操作變成 host 常駐引擎，並讓 agent 能在對話中直接創建和管理同一批任務。許可證爲 MIT。
GitHub 倉庫：https://github.com/LouisHaoL/dsh-timer-agent
社區目錄是獨立站點，與 DeepSeek / 幻方無官方從屬關係；本文不附未覈實的目錄頁 URL。
