Signature 目錄¶

本文件記錄 Time Compass 系統各模組使用的 DSPy Signature 及其完整規格。

1. Router¶

RouterSignature¶

模組: RouterModule

目標: 判斷使用者意圖、情緒強度，決定後續 pipeline

輸入:

欄位	型別	說明
`dialog_history`	string	對話歷史（選填，預設空字串）
`user_input`	string	使用者這一輪的完整輸入文字（必填）

輸出:

欄位	型別	說明
`pipeline_description`	string	1~3 句話的流程說明，對使用者描述接下來會做的步驟（不在此展開具體內容）
`pipeline`	List[Literal]	要執行的模組名稱陣列，允許元素：`EmotionSupport`, `Summary`, `Scheduling`

決策流程: 詳見 USER-DIALOG-FLOW.md → Router 決策流程

2. EmotionSupport¶

EmotionSupportSignature¶

模組: EmotionSupportModule

目標: 承接語氣、點出情緒、正常化感受、溫柔銜接後續步驟

輸入:

欄位	型別	說明
`dialog_history`	string	對話歷史（選填，預設空字串）
`user_input`	string	使用者這一輪的完整輸入文字（必填）
`previous_module_outputs`	string	前面模組（如 Router）的輸出
`pipeline_history`	string	已執行的模組與後續步驟

輸出:

欄位	型別	說明
`emotion_reply`	string	一段溫柔、具體、正常化情緒的回應，並自然銜接 pipeline_history 的下一步

工作流程:

使用者輸入
  ↓
情緒偵測與共感
  ↓
正常化感受
  ↓
小建議或過渡語
  ↓
開放式小問題收尾
  ↓
輸出 emotion_reply

設計原則: - 台灣本地化口吻（像朋友/學長姊陪伴） - 不說教、不下指令、不講大道理 - 不再解釋「整個流程」（流程由 Router 說明） - 只在合適時順著 pipeline_history 自然提到「等等會一起回顧 / 安排」

3. Summary¶

SummaryWriterSignature¶

模組: SummaryModule

目標: 生成區間回顧文字

輸入:

欄位	型別	說明
`interaction_context`	InteractionContext	統一的上下文（user_input、dialog_history 等）
`time_interval_data`	string	時間段資訊（由 Python 邏輯取得）

輸出:

欄位	型別	說明
`summary_text`	string	總結文本內容

SummaryToolSignature¶

模組: SummaryModule

目標: 判斷時間段並取得相關資料

輸入:

欄位	型別	說明
`user_input`	string	使用者輸入

輸出:

欄位	型別	說明
`start_date`	string	開始日期
`end_date`	string	結束日期

4. Scheduling¶

Scheduling 為複合模組，由多個子 Signature 組成。

SchedulingRouterSignature¶

模組: SchedulingModule 內的 Router 層

目標: 判斷任務等級（L1/L2/L3）並路由至適當的子流程

輸入:

欄位	型別	說明
`interaction_context`	InteractionContext	統一的上下文

輸出:

欄位	型別	說明	可見性
`catch_and_rephrase`	string	路由簡短回覆並重述使用者意圖（便於接手模組持續對話）	使用者可見
`ai_can_do`	string	針對該輸入，AI 可立即執行的動作摘要（例如：提供候選時段、拆任務、追問參數）。詳見 USER-DIALOG-FLOW → AI 可做動作清單	使用者可見
`task_level`	string	判定的任務等級：`L1（想法級）` / `L2（方案級）` / `L3（行動級）`	內部

決策流程: 詳見 USER-DIALOG-FLOW.md → SchedulingRouter 任務等級判斷流程

DraftPlanSignature¶

模組: SchedulingModule 內的 DraftPlan 層（當判斷為 L2 方案級時）

目標: 產生對使用者可讀的排程草案與機器可讀的排程資料

輸入:

欄位	型別	說明
`interaction_context`	InteractionContext	統一的上下文（來自 SchedulingRouter）

輸出:

欄位	型別	說明	可見性
`draft_plan`	string	對使用者友善的草案說明（含候選時段與說明）	使用者可見
`constraints_and_missing_info`	string	誠實說明此方案缺少哪些資訊、所做的假設，以及可能的風險與其影響	使用者可見

設計原則: - 產出 2~5 個候選時段 - 每個時段標註風險與緩衝 - 誠實列舉缺資訊與假設（不隱暪）

DraftActionSignature¶

模組: SchedulingModule 內的 DraftAction 層（當判斷為 L3 行動級時）

目標: 生成具體可執行的行動項與啟動說明

輸入:

欄位	型別	說明
`interaction_context`	InteractionContext	統一的上下文（來自 SchedulingRouter）

輸出:

欄位	型別	說明	可見性
`action_description`	string	可直接執行的行動描述（以動詞開頭，含完成判準）	使用者可見
`start_instructions`	string	啟動該行動的第一步驟說明	使用者可見
`constraints_and_missing_info`	string	誠實說明此方案缺少哪些資訊、所做的假設，以及可能的風險與其影響	使用者可見
`action_metadata`	List[action_llm]	機器可讀的 LLM 生成紀錄清單（見 `docs/reference/DDD-ARCHITECTURE/` 的 `action_llm` 定義）	內部

設計原則: - 行動必須在 60 分鐘內可驗收 - 明確的完成判準 - 誠實列舉風險與缺資訊

AskQuestionSignature¶

模組: SchedulingModule 內的 AskQuestion 層（DraftPlan / DraftAction 之後）

目標: 在資訊不足時，產生追問題目以取得缺少參數，並建議後續步驟

輸入:

欄位	型別	說明
`constraints_and_missing_info_from_draft`	string	由 DraftPlan / DraftAction 傳入的限制與缺失摘要，供 AskQuestion 自動產生追問
`interaction_context`	InteractionContext	統一的上下文

輸出:

欄位	型別	說明	可見性
`questions`	string	由 `constraints_and_missing_info` 自動生成的一組追問（以文字呈現，供 UI 顯示或下一步處理）	使用者可見
`next_steps_suggestion`	string	在追問之後可做的下一步建議（例如：進到 L3（行動級）、繼續拆分）	使用者可見

設計原則: - 建議 3~5 個精準的追問（避免過多） - 每個追問應針對 constraints_and_missing_info 的具體缺項 - 提供清晰的下一步方向

Signature 通訊流¶

Orchestrator.forward(user_input, dialog_history)
  ↓
RouterSignature
  ├─ 輸出: pipeline_description, pipeline
  ↓
[依 pipeline 順序執行]
  ├─ EmotionSupportSignature（若在 pipeline）
  │   └─ 輸出: emotion_reply
  │
  ├─ SummaryToolSignature
  │   └─ 輸出: start_date, end_date
  │       ↓
  │   SummaryWriterSignature
  │   └─ 輸出: summary_text
  │
  └─ SchedulingRouterSignature
      ├─ 輸出: catch_and_rephrase, ai_can_do, task_level
      ├─ 判斷 task_level
      │
      ├─ 若 L2：DraftPlanSignature
      │   └─ 輸出: draft_plan, constraints_and_missing_info
      │
      └─ 若 L3：DraftActionSignature
          └─ 輸出: action_description, start_instructions, constraints_and_missing_info, action_metadata
          ↓
      (無論 L2 或 L3) AskQuestionSignature
      └─ 輸出: questions, next_steps_suggestion
  ↓
Orchestrator 蒐集所有輸出並組裝 final_reply

InteractionContext 定義¶

所有模組間的通訊均通過標準的 InteractionContext 物件。詳細欄位定義見 docs/reference/DDD-ARCHITECTURE/ 的相關文檔。

關鍵欄位: - user_input - 使用者輸入 - dialog_history - 對話歷史 - pipeline - Router 決定的模組執行清單 - current_pipeline_index - 當前執行位置 - previous_signature_output - 前一模組輸出（用於後續模組的上下文） - time_interval_data - 可用時間資訊（Scheduling 用）

流程決策詳解: USER-DIALOG-FLOW.md

整體架構: C4-DIAGRAM.md