Skip to content

dse120071750/m8m-harness-builder / skills/m8m/m8m-harness-builder

m8m-harness-builder

Flagged

Build and edit M8M harnesses that coordinate existing tools and FlowSteps, validate milestone outputs, and track progress and resume. Reuse working implementations in place. Compile workflow changes without runtime packaging; build portable packages when requested and deliver server installations through the dedicated M8M server installer.

FileKindSize
.gitattributesother112 B
.gitignoreother208 B
LICENSEother673 B
README.mdmarkdown29.8 KB
SKILL.mdskill md1.3 KB
agents/audit_complete.yamlconfig1.6 KB
agents/flow_generated.yamlconfig2.2 KB
agents/harness_validated.yamlconfig2.3 KB
agents/openai.yamlconfig4.6 KB
agents/skill_shipped.yamlconfig2.1 KB
agents/toolbox_ready.yamlconfig1.6 KB
conftest.pyscript275 B
contracts/conformance/expectation_first_runtime/candidate-cases.jsonconfig4.1 KB
contracts/conformance/expectation_first_runtime/common-linear.jsonconfig2.7 KB
contracts/conformance/expectation_first_runtime/schemas/judge-decision.schema.jsonconfig373 B
contracts/conformance/expectation_first_runtime/schemas/result.output.schema.jsonconfig589 B
contracts/conformance/expectation_first_runtime/schemas/source.output.schema.jsonconfig500 B
contracts/conformance/flowstep_flow_v4/invalid/judge-loop-unbound.jsonconfig483 B
contracts/conformance/flowstep_flow_v4/invalid/malformed-execution.jsonconfig571 B
contracts/conformance/flowstep_flow_v4/invalid/no-required-output.jsonconfig455 B
contracts/conformance/flowstep_flow_v4/invalid/nonjudge-bound.jsonconfig763 B
contracts/conformance/flowstep_flow_v4/invalid/unknown-field.jsonconfig469 B
contracts/conformance/flowstep_flow_v4/valid/authoring-union.jsonconfig4.3 KB
contracts/conformance/flowstep_flow_v4/valid/platform-dag.jsonconfig1.9 KB
contracts/file_ref_v2.schema.jsonconfig484 B
contracts/flow_sequence_action_v2.schema.jsonconfig1.5 KB
contracts/flowstep_flow_v4.schema.jsonconfig13.6 KB
contracts/flowstep_output_v2.schema.jsonconfig2.8 KB
contracts/flowstep_output_v3.schema.jsonconfig3.0 KB
contracts/flowstep_skill_audit_v1.schema.jsonconfig5.1 KB
contracts/m8m_builder_configuration_v1.schema.jsonconfig252 B
contracts/m8m_builder_input_v1.schema.jsonconfig183 B
contracts/m8m_builder_installation_receipt_v2.schema.jsonconfig2.9 KB
contracts/m8m_builder_output_v1.schema.jsonconfig453 B
contracts/m8m_builder_request_v3.schema.jsonconfig707 B
contracts/m8m_builder_result_v3.schema.jsonconfig422 B
contracts/m8m_builder_source_audit_v2.schema.jsonconfig6.1 KB
contracts/m8m_builder_source_bundle_v2.schema.jsonconfig8.6 KB
contracts/m8m_builder_toolbox_manifest_v2.schema.jsonconfig2.6 KB
contracts/m8m_builder_validation_report_v2.schema.jsonconfig3.4 KB
contracts/m8m_cache_receipt_v1.schema.jsonconfig1.2 KB
contracts/m8m_candidate_cache_entry_v1.schema.jsonconfig2.8 KB
contracts/m8m_chosen_output_v1.schema.jsonconfig2.3 KB
contracts/m8m_context_capsule_v1.schema.jsonconfig1.9 KB
contracts/m8m_contract_bundle_lock_v1.schema.jsonconfig648 B
contracts/m8m_goal_ledger_v1.schema.jsonconfig1.8 KB
contracts/m8m_milestone_agent_v1.schema.jsonconfig13.8 KB
contracts/m8m_milestone_expectation_v1.schema.jsonconfig1.9 KB
contracts/m8m_milestone_judge_receipt_v1.schema.jsonconfig1.7 KB
contracts/m8m_milestone_judge_request_v1.schema.jsonconfig3.0 KB
contracts/m8m_run_context_v1.schema.jsonconfig994 B
contracts/m8m_run_context_v2.schema.jsonconfig1.2 KB
contracts/m8m_run_storage_contract_v1.schema.jsonconfig894 B
contracts/m8m_runtime_lock_v1.schema.jsonconfig1.7 KB
contracts/m8m_runtime_release_v1.schema.jsonconfig2.2 KB
contracts/m8m_skill_canvas_v1.schema.jsonconfig4.0 KB
contracts/m8m_source_asset_manifest_v1.schema.jsonconfig1.2 KB
contracts/m8m_workflow_package_archive_v1.schema.jsonconfig1.1 KB
contracts/m8m_workflow_source_bundle_proof_v1.schema.jsonconfig1.6 KB
contracts/m8m_workflow_source_bundle_v1.schema.jsonconfig19.5 KB
contracts/tool_vs_intelligence_table_v1.schema.jsonconfig1.3 KB
docs/m8m-chart.jpgbinary172.2 KB
docs/m8m-task-builder-design.zh-HK.mdmarkdown66.9 KB
examples/article_infographic/README.mdmarkdown598 B
examples/article_infographic/planning/m8m-flowchart.jpgbinary186.0 KB
examples/article_infographic/planning/m8m-flowchart.mdmarkdown4.2 KB
flows/m8m_build_v2.yamlconfig9.9 KB
flowsteps/tools/audit_complete_judge/input.schema.jsonconfig190 B
flowsteps/tools/audit_complete_judge/output.schema.jsonconfig477 B
flowsteps/tools/audit_complete_judge/tests/test_tool.pyscript1.1 KB
flowsteps/tools/audit_complete_judge/tool.pyscript1.2 KB
flowsteps/tools/audit_skill/input.schema.jsonconfig250 B
flowsteps/tools/audit_skill/output.schema.jsonconfig136 B
flowsteps/tools/audit_skill/tests/test_tool.pyscript1.9 KB
flowsteps/tools/audit_skill/tool.pyscript2.9 KB
flowsteps/tools/flow_generated_judge/input.schema.jsonconfig190 B
flowsteps/tools/flow_generated_judge/output.schema.jsonconfig475 B
flowsteps/tools/flow_generated_judge/tests/test_tool.pyscript1.1 KB
flowsteps/tools/flow_generated_judge/tool.pyscript1.5 KB
flowsteps/tools/generate_from_audit/input.schema.jsonconfig562 B
flowsteps/tools/generate_from_audit/output.schema.jsonconfig137 B
flowsteps/tools/generate_from_audit/tests/test_tool.pyscript2.2 KB
flowsteps/tools/generate_from_audit/tool.pyscript3.0 KB
flowsteps/tools/harness_validated_judge/input.schema.jsonconfig193 B
flowsteps/tools/harness_validated_judge/output.schema.jsonconfig488 B
flowsteps/tools/harness_validated_judge/tests/test_tool.pyscript1.1 KB
flowsteps/tools/harness_validated_judge/tool.pyscript1.3 KB
flowsteps/tools/install_local_skill/input.schema.jsonconfig733 B
flowsteps/tools/install_local_skill/output.schema.jsonconfig144 B
flowsteps/tools/install_local_skill/tests/test_tool.pyscript2.1 KB
flowsteps/tools/install_local_skill/tool.pyscript3.0 KB
flowsteps/tools/install_toolbox/input.schema.jsonconfig400 B
flowsteps/tools/install_toolbox/output.schema.jsonconfig140 B
flowsteps/tools/install_toolbox/tests/test_tool.pyscript1.9 KB
flowsteps/tools/install_toolbox/tool.pyscript3.0 KB
flowsteps/tools/skill_shipped_judge/input.schema.jsonconfig189 B
flowsteps/tools/skill_shipped_judge/output.schema.jsonconfig484 B
flowsteps/tools/skill_shipped_judge/tests/test_tool.pyscript1.1 KB
flowsteps/tools/skill_shipped_judge/tool.pyscript1.3 KB
flowsteps/tools/toolbox_ready_judge/input.schema.jsonconfig189 B
flowsteps/tools/toolbox_ready_judge/output.schema.jsonconfig490 B
flowsteps/tools/toolbox_ready_judge/tests/test_tool.pyscript1.3 KB
flowsteps/tools/toolbox_ready_judge/tool.pyscript1.6 KB
flowsteps/tools/validate_harness/input.schema.jsonconfig563 B
flowsteps/tools/validate_harness/output.schema.jsonconfig141 B
flowsteps/tools/validate_harness/tests/test_tool.pyscript2.1 KB
flowsteps/tools/validate_harness/tool.pyscript3.0 KB
planning/upgrade.mdmarkdown16.2 KB
references/architecture.mdmarkdown28.1 KB
references/audit_complete.mdmarkdown739 B
references/builder-authoring.mdmarkdown9.8 KB
references/flow_generated.mdmarkdown1.2 KB
references/flowstep-development.mdmarkdown4.3 KB
references/harness-invocation.mdmarkdown2.9 KB
references/harness_validated.mdmarkdown786 B
references/master-prompts.mdmarkdown14.0 KB
references/milestone.mdmarkdown11.4 KB
references/output-lineage.mdmarkdown4.4 KB
references/runtime-packaging.mdmarkdown35.2 KB
references/server-delivery.mdmarkdown6.8 KB
references/skill_shipped.mdmarkdown798 B
references/tool-vs-intelligence.mdmarkdown10.0 KB
references/toolbox_ready.mdmarkdown612 B
requirements.txtmanifest150 B
scripts/audit_harness.pyscript80.7 KB
scripts/candidate_cache.pyscript27.6 KB
scripts/coordinate_workflow.pyscript4.3 KB
scripts/execution_identity.pyscript1.0 KB
scripts/flowchart_jpg.pyscript16.1 KB
scripts/flowstep_instruction.pyscript14.1 KB
scripts/flowstep_runtime.pyscript108.6 KB
scripts/flowstep_tools.pyscript5.7 KB
scripts/gem_text.pyscript5.7 KB
scripts/generate_harness.pyscript61.4 KB
scripts/humanize_chart.pyscript5.6 KB
scripts/humanize_chart_zh.pyscript5.2 KB
scripts/import_flow_v4.pyscript62.3 KB
scripts/m8m_build_steps.pyscript143.2 KB
scripts/m8m_cache.pyscript1.7 KB
scripts/m8m_delivery_common.pyscript3.8 KB
scripts/m8m_deploy.pyscript5.6 KB
scripts/m8m_factory.pyscript10.1 KB
scripts/m8m_flowchart.pyscript16.6 KB
scripts/m8m_local_bundle.pyscript4.5 KB
scripts/migrate_skill_source.pyscript34.2 KB
scripts/milestone_expectation.pyscript3.3 KB
scripts/milestone_pair.pyscript3.1 KB
scripts/package_archive.pyscript7.1 KB
scripts/project_imports.pyscript10.8 KB
scripts/run_flow.pyscript153.8 KB
scripts/run_goal.pyscript14.1 KB
scripts/run_m8m.pyscript3.8 KB
scripts/runtime_release.pyscript45.0 KB
scripts/schema_gate.pyscript5.6 KB
scripts/session_layout.pyscript74.4 KB
scripts/skill_source.pyscript65.3 KB
scripts/source_bundle.pyscript87.7 KB
scripts/teaching_contracts.pyscript8.9 KB
scripts/tool_vs_intelligence.pyscript9.3 KB
scripts/toolbox_plan.pyscript6.1 KB
scripts/validate_harness.pyscript24.1 KB
scripts/verify_platform_contract_parity.pyscript2.9 KB
seeds/branch_receipt/input.schema.jsonconfig1.0 KB
seeds/branch_receipt/output.schema.jsonconfig359 B
seeds/branch_receipt/tests/test_tool.pyscript2.0 KB
seeds/branch_receipt/tool.pyscript3.7 KB
seeds/cycle_receipt/input.schema.jsonconfig1.0 KB
seeds/cycle_receipt/output.schema.jsonconfig319 B
seeds/cycle_receipt/tests/test_tool.pyscript1.5 KB
seeds/cycle_receipt/tool.pyscript2.0 KB
seeds/hash_bind/input.schema.jsonconfig213 B
seeds/hash_bind/output.schema.jsonconfig288 B
seeds/hash_bind/tests/test_tool.pyscript814 B
seeds/hash_bind/tool.pyscript527 B
seeds/ledger_receipt/input.schema.jsonconfig278 B
seeds/ledger_receipt/output.schema.jsonconfig355 B
seeds/ledger_receipt/tests/test_tool.pyscript842 B
seeds/ledger_receipt/tool.pyscript747 B
seeds/ok_receipt/input.schema.jsonconfig280 B
seeds/ok_receipt/output.schema.jsonconfig280 B
seeds/ok_receipt/tests/test_tool.pyscript667 B
seeds/ok_receipt/tool.pyscript682 B
seeds/schema_validate/input.schema.jsonconfig265 B
seeds/schema_validate/output.schema.jsonconfig196 B
seeds/schema_validate/tests/test_tool.pyscript1.0 KB
seeds/schema_validate/tool.pyscript844 B
seeds/slot_write/input.schema.jsonconfig558 B
seeds/slot_write/output.schema.jsonconfig346 B
seeds/slot_write/tests/test_tool.pyscript1.2 KB
seeds/slot_write/tool.pyscript1015 B
tests/__init__.pyscript0 B
tests/support.pyscript668 B
tests/test_audit_harness.pyscript23.5 KB
tests/test_branch.pyscript14.4 KB
tests/test_builder3_templates.pyscript2.4 KB
tests/test_builder_install_integrity.pyscript30.6 KB
tests/test_builder_native_snapshot.pyscript5.0 KB
tests/test_builder_requirements.pyscript26.8 KB
tests/test_builder_self_dogfood.pyscript7.0 KB
tests/test_builder_self_source.pyscript10.3 KB

docs/m8m-task-builder-design.zh-HK.md

View on GitHub
# M8M Task Builder:為一個 Codex Session 保存任務

本文件記錄完整設計及分段實作。**2026-09-25 已在本機實作第 7.5 節的同 Session 提醒,並在獨立 PostgreSQL 測試庫執行 migration 和驗收;未部署。** 程式碼位置:`C:/NisanWorkspaces/m8m-platform-instagram-20260910`。第 7.6 節列出本次已完成範圍及尚未實作的完整 Task 功能;其餘章節仍是目標設計,不代表全部已提供。

**一個 Chat = 一個 Task = 現有的一個 Codex 對話 Session。** 使用者的新訊息直接交給這個 Session,Codex 按保存的 goal、完整工作指引及目前進度照常理解、回答和使用工具。同一 Task 可使用多個 M8M workflows,最後返回一個業務 JSON object;圖片及文件先存到 Server,再以實際 URL 放入 JSON。

M8M 要補的是 Session 的持久任務資料、結果讀取,以及把現有 scheduler 的到期動作接回原 Session。排程沿用 Server 已安裝的 `m8m-schedule-builder` skill 及 `WorkflowSchedules`,時間和重試由現有 scheduler 管理。Task Builder 是由同一 Codex Session 讀取的 skill,不是另一個 Agent。本文不設 coordinator Agent、Judge Agent、訊息分類模型、A2A 討論或 Task 交接。

```text
使用者訊息/已到達的工具結果/到期通知
                    ↓
            同一個 Codex Session
            goal + 工作指引 + 已保存進度
                    ↓
            現有工具及 M8M workflows
                    ↓
            保存進度/等待/最終 JSON
```

程式中的 `ChatCodexRunner` 及舊註解所稱的 coordinator,就是現有這個 Codex 對話。沿用目前 SDK 的 thread resume 路徑,毋須另啟 CLI process 或引入新的 Agent runtime。Workflow 原有的 milestone 執行方式保持不變。

## 1. 現有 codebase 已有甚麼,實際缺甚麼?

下表保留實作前的基線,方便對照改動;第 7.6 節是這次更新後的實際狀態。

| 位置 | 已核對的現況 | 本次要補的能力 |
| --- | --- | --- |
| `chat_workspace_store.py:ChatWorkspaceStore.__init__` | PostgreSQL 已有 rooms、messages、events、run intents、run links;room 有 `thread_id`,沒有 Task goal/definition/output | 在 room 保存任務定義、目前進度、等待及最終結果 |
| `chat_codex_runner.py:ChatCodexRunner._run` | 恢復原 Codex thread;prompt 加入新訊息及 linked run IDs | 每次另讀取持久 Task 定義及 state,作為本次任務上下文 |
| `chat_codex_runner.py:RESULT_INSTRUCTIONS / WorkspaceBridge` | 自動完成通知只有 `read_run`,明確禁止開始下一個 workflow | 已授權的 Task 增加可推進原任務的內部事件回合 |
| `chat_workspace_service.py:start / _assert_idle` | 同一 room 只容許一個 active workflow;run intent 可防止重複建立執行 | 保留串行,讓同一 Task 在前一步完成後接續下一步 |
| `workflow_schedules.py:WorkflowSchedules` | 已保存 schedule/occurrence,支援 once/daily/weekdays/weekly,目標目前是 workflow steps | 在原 scheduler 補 `resume_session` 目標,到期把訊息入列到原 room |
| `chat_workspace_worker.py:serve_workspace` | maintenance 已每五秒呼叫 `schedules.tick()` | 沿用這個 tick,不另設 Task timer/到期掃描 |
| `skills/m8m/m8m-schedule-builder/SKILL.md` | 現有 Codex 回合已載入此 skill,提供 list/save/control 工具 | 擴充指引及工具接線,讓同一 Session 可安排自己的後續喚醒 |
| `chat_workspace_store.py:claim` | 過期回合標記 `interrupted`,等重試;失敗/中斷訊息阻止 room 後續訊息被 claim | 為可恢復的 Task 中斷加入有限次自動恢復;不可恢復則顯示 blocked |
| `execution_lineage_reader.py:asset` | 已有產物索引及 Server 檔案;API 可返回 metadata 或分頁 base64 | 增加能存入最終 JSON 的穩定、受權限控制的下載 URL |

Goal 作為普通文字指引傳給 Codex。Task 保存等待甚麼及對應的 schedule_id;現有 scheduler 保存何時喚醒、是否啟用及 occurrence 歷史,讓 Session 不在運行時,任務仍然找得回來。

## 2. Goal、Session、sandbox 分別放在哪裏?

| 概念 | 保存位置 | 規則 |
| --- | --- | --- |
| Task 身份 | 現有 `m8m_chat_rooms.room_id` | API 的 `task_id` 直接等於 `room_id`,不用新增另一個 ID 或 Task 主表 |
| 持久 goal | 新增 `task_definition->>'goal'` | 由任務建立時保存;普通補件、結果通知及摘要不能覆寫 |
| 完整 playbook | `task_definition->>'master_prompt'` | 寫清楚 workflow 用法、條件、等待、完成與失敗處理 |
| 目前進度 | `task_state` | 保存已確認事實、目前等待及 schedule_id 引用 |
| 下次喚醒 | 現有 `m8m_workflow_schedules.next_due` | 由 scheduler 管理,Task 不另存到期時間 |
| 聊天及事件 | 現有 `m8m_chat_messages / m8m_chat_events` | 原始輸入、狀態改變及外部事件可重新讀取 |
| 模型 Session | 現有 `thread_id` | 用來續接 Codex 對話;業務 Task 不以它是否仍可恢復來定義 |
| 工作目錄 | 現有每回合 temporary directory;workflow 使用其原 runtime | 等待三日不需要保留一個運行中的 sandbox |
| 最終結果 | 新增 `task_output` | 一個 JSON object;產物用 Server URL |

`title` 只是顯示名稱,不能拿來做 goal。模型認為「目前重點變了」亦不能自行換掉 goal。使用者明確修正同一任務目標時,才更新 definition,並在現有 events 記錄來源訊息;毋須建立 revision chain。

例如原 goal 是「完成 app_1042 的按揭申請處理」。客戶三日後說「補交糧單」,只更新 context/等待。客戶說「另外幫我訂機票」,回覆這屬於另一件工作,原 Task 仍保留按揭進度;本功能不替它建立或交接另一個 Task。

## 3. PostgreSQL:沿用 room,只新增四個欄位

| 新欄位 | 型別 | 用途 |
| --- | --- | --- |
| `task_definition` | `JSONB NULL` | goal、完整 master prompt、已解析 workflows、output schema、來源訊息 |
| `task_status` | `TEXT NULL` | `drafting / running / waiting / blocked / completed / cancelled` |
| `task_state` | `JSONB NOT NULL DEFAULT '{}'` | 當前步驟、context、目前等待及 schedule_id 引用 |
| `task_output` | `JSONB NULL` | 最終業務 JSON;完成前為 SQL NULL |

`JSONB` 用來保存可變的 context;並不要求使用者輸入符合業務 schema。固定的是平台自己的幾個控制欄位。PostgreSQL 原生支援 JSONB 儲存及查詢,適合這個用途。[PostgreSQL JSON 文件](https://www.postgresql.org/docs/current/datatype-json.html)

### 建議 migration

以下是資料約束示意。四個欄位及等價的基本 constraints 已放進 Chat store 現有受 advisory lock 保護的初始化 migration,以新增欄位方式保留舊資料;只在獨立測試庫執行過,正式庫尚未 migration。

```sql
ALTER TABLE m8m_chat_rooms
    ADD COLUMN IF NOT EXISTS task_definition JSONB,
    ADD COLUMN IF NOT EXISTS task_status TEXT,
    ADD COLUMN IF NOT EXISTS task_state JSONB NOT NULL DEFAULT '{}'::jsonb,
    ADD COLUMN IF NOT EXISTS task_output JSONB;

-- 以下 constraints 由 migration 檢查 pg_constraint 後各安裝一次。
ALTER TABLE m8m_chat_rooms
    ADD CONSTRAINT m8m_chat_task_status_check CHECK (
        task_status IS NULL OR task_status IN
        ('drafting', 'running', 'waiting', 'blocked', 'completed', 'cancelled')
    ),
    ADD CONSTRAINT m8m_chat_task_json_check CHECK (
        (task_definition IS NULL OR jsonb_typeof(task_definition) = 'object')
        AND jsonb_typeof(task_state) = 'object'
        AND (task_output IS NULL OR jsonb_typeof(task_output) = 'object')
    ),
    ADD CONSTRAINT m8m_chat_task_definition_check CHECK (
        (task_status IS NULL) = (task_definition IS NULL)
    ),
    ADD CONSTRAINT m8m_chat_task_completion_check CHECK (
        task_status IS DISTINCT FROM 'completed' OR task_output IS NOT NULL
    );
```

DB checks 只保護平台資料型別及基本狀態。Codex 在原 Session 根據工作指引及實際工具結果判斷下一步;Server 沿用執行結果、權限和 output schema 的程式檢查,不再呼叫另一個模型判斷業務內容。

Task 不新增 `task_wake_at` 或另一個 due index。時間唯一以現有 schedule 的 `definition.timing` 及 `next_due` 為準;UI 透過 schedule_id 讀取 `next_run_at`。排程定義沿用現有 TEXT 欄位內的 JSON,毋須為此改成另一套儲存。

不新增 `tasks`、`task_sessions`、`task_workflows`、`task_outputs` 四張重複表。既有 tables 的分工:

| 現有表 | Task 內的角色 |
| --- | --- |
| `m8m_chat_rooms` | 一個 Task 的持久主記錄 |
| `m8m_chat_messages` | 使用者輸入及 Server 內部喚醒的執行佇列 |
| `m8m_chat_events` | 原始事件、goal 修正、等待/完成記錄及回覆關聯 |
| `m8m_chat_run_intents / m8m_chat_run_links` | 該 Task 啟動過哪些 workflow 執行 |
| `m8m_workflow_schedules` | 原有 schedule 定義、next_due、enabled/archived、revision |
| `m8m_workflow_schedule_occurrences` | 原有到期紀錄、去重、重試及投遞結果 |
| `m8m_chat_schedule_actions` | 原有排程動作的重送記錄;沿用並調整 Session 喚醒分支 |
| `m8m_execution_states` 及原 execution tables | 每個 workflow 的真實執行狀態;Task 不另存一份 roster |
| `m8m_release_input_requests` | workflow 本身提出的補件/問題及回覆 |
| `m8m_execution_output_index / m8m_execution_asset_index` | workflow 實際輸出及產物位置 |

## 4. Task 建立時的 schema

這是 **Builder/Server 的儲存格式**,不是客戶輸入表格。使用者仍只需說「幫我處理這份按揭申請」並附上資料。

```typescript
type JsonObject = Record<string, unknown>;

type TaskDefinition = {
  goal: string;
  master_prompt: string;
  workflows: Record<string, {
    import_id: string;
    release_id: string;
    expected_release_digest: string;
  }>;
  output_schema: JsonObject;
  source_message_id: string;
};

type TaskState = {
  current_step: string;
  context: JsonObject;
  waiting: null | {
    wait_id: string;
    schedule_id: string | null;       // 引用現有 scheduler;無定時跟進時為 null
    reason: string;
    match: Record<string, string>;
    on_wake: string;
    remaining_checks: number;
  };
};

type TaskRow = {
  room_id: string;                    // 同時就是 task_id
  thread_id: string | null;           // 現有 Codex Session
  task_definition: TaskDefinition;    // drafting 時可暫存部分欄位
  task_status: "drafting" | "running" | "waiting"
             | "blocked" | "completed" | "cancelled";
  task_state: TaskState;
  task_output: JsonObject | null;
};
```

`workflows` 是別名 → 實際已安裝 workflow release 的登記。Server 透過現有 catalog/readiness 填入這三個 execution admission 已需使用的識別欄位,不要求使用者填 hash,也不在 milestone 新增 hash 步驟。簡單客服 Task 可是空 object。

`source_message_id` 由 Server 從目前 claim 寫入,指向建立任務的使用者要求,模型不能任意指定另一則訊息。它記錄來源;執行權限仍按該要求的實際範圍及現有 Server 規則判斷。

`current_step` 可以是語意名稱,例如 `receive_credit_report`;不是另一份可執行 graph。`context` 可以增加 `application_id`、文件引用、已確認決定、分析摘要等任務所需資料,不逐項做業務 input schema 驗證。大型報告、完整聊天及 milestone 結果留在原本 storage,只保存引用。

### 建立流程

1. `POST /chat-rooms` 沿用現有 `client_room_id` 去重。新 room 初始化為 `drafting`,definition 為空 object,output 為 NULL。
2. 第一則語意訊息進入原 messages queue,直接交給原 Codex Session。該 Session 讀取 `m8m-task-builder` skill 及所需的真實 workflow catalog。
3. 同一 Session 整理 goal、完整 master prompt、workflow bindings 及 output schema;只有阻礙工作的資料才追問。這是正常的一個 Codex 回合,沒有 Builder Agent 到 Executor Agent 的交接。
4. `register_task` 在一個 DB transaction 內鎖住原 room、核對目前 message lease、保存 definition/初始 state,記錄 `task_created` event,再設成 `running`。
5. 已有清楚執行要求便接續工作;單純討論、要求建立方案或註冊 harness,不因此授權付款/發佈。
6. 重送同一個建立動作讀回同一份 Task。已有 Task 不以再次 register 默默覆蓋;真正的目標修正另記來源 event。

初始 state:

```json
{
  "current_step": "read_application",
  "context": {
    "request_message_id": "m8m_chat_message:example",
    "attachments": []
  },
  "waiting": null
}
```

附件 ID、message ID 都由 Server 提供,例子不是現有真實記錄。

### Goal 及完整 master prompt 範例

**Goal:** 完成本次按揭申請的資料收集、分析、人工決定及後續系統更新,交付實際處理結果 JSON。

**Master prompt:**

> 在這個 Task 內處理本次按揭申請。使用 read_application 讀取原申請,使用 request_credit_report 取得報告請求 ID。保存該 ID,等待報告;六小時後仍未收到便查詢原請求。取得報告後用 analyze_application 分析。缺文件時用 request_documents 提出具體補件要求並保存回覆關聯;三日後仍未收到便跟進,收到後帶入原申請、報告和新增文件重新分析。需要人工決定時保存精確要求,等待有權批准的人明確回覆;七小時後仍未收到便跟進。每種等待最多跟進兩次,仍無結果便標示 blocked,等待操作人員處理。批准分支依既有 process_payment workflow 處理付款;暫時性失敗沿用同一 execution 的有限重試,結果不明先查詢原操作,不建立另一筆付款。成功後用 update_crm 更新 CRM;CRM 失敗只恢復該工作。拒絕分支不付款,更新拒絕結果到 CRM。將所需文件上傳並取得 Server URL,最後返回符合 output schema 的 JSON。只有本分支必要操作有真實成功結果才算完成。補件及修正原申請屬於本 Task;獨立新工作不擴入本任務。

上述別名必須對應已存在、ready 的 workflows。這個例子不表示目前平台已具有按揭/付款能力。

Master prompt 的定時跟進部分使用已安裝的 `m8m-schedule-builder`:同一 Session 保存等待後,以現有 schedule 工具安排一次性喚醒並讀回確認;所需的 `resume_session` 接線見第 7 節。單寫「六小時後再檢查」不等於已保存排程。

## 5. 同一個 Codex Session 照常理解對話

不用為新訊息先做「補充/修正/問題/獨立要求」的分類,也不建立分類 JSON、分類 endpoint 或前置 LLM 呼叫。Codex 在原本的回答與工具使用過程中,自然理解內容是否與當前工作有關。

在 Task 的完整 master prompt 加入以下普通文字便足夠:

> 持續完成本次任務。按對話中的補充和修正繼續工作;原任務的相關問題可以直接回答。出現明顯獨立的新工作時,簡短說明適合另開對話,保留原任務的進度。只有真正不清楚使用者想怎樣改動時才詢問。完成有用步驟或要等待時保存必要進度,最後按指定格式返回 JSON。

例如「補返糧單」直接處理文件;「順便訂機票」由同一個 Codex 回覆一句範圍說明。Server 不為這兩句話各跑一次語意判定。若使用者清楚修正原任務,Codex 依指示更新相應資料。

在 `ChatCodexRunner._run()` 開始模型回合前,從 DB 重新讀取:

```text
目前 Task definition
  goal + 完整 master_prompt + workflows + output_schema
目前 Task state
  current_step + context + waiting;需要時間資訊時讀取原 schedule
本次輸入
  使用者訊息/附件引用/Server 事件
相關既有 run IDs
  實際狀態與結果使用 read_run 讀取
```

不要只在第一次 `thread_start` 傳入 goal。每次 `thread_resume`、context compaction 後的回合及 Server 事件回合都帶入目前保存的定義。平台指令規定必須圍繞此 goal;使用者內容、email 及 workflow 結果維持資料邊界,不能偽裝成新的平台指令。

上述內容由 Server 讀取並組成普通文字上下文,直接送入同一個 Codex 回合。這段讀取不呼叫模型、不先作計劃審核、不經過其他 Agent。

Codex 可更新「正在做甚麼」;goal 只有明確的使用者修正才改。模型生成的摘要是輔助記憶,Server 儲存及真實 execution 結果才是事實來源。

`thread_id` 無法恢復時,現有程式會報錯,不會自動換 Session。第一版保留這個行為並將 Task 顯示為 blocked。日後若提供重建模型 Session,必須從同一 room 的 definition、state、事件及 run 結果恢復;不得重新建立業務 Task 或重跑已成功操作。

### 供同一 Session 使用的保存工具

沿用 `WorkspaceBridge`,在 Server 安裝 `skills/m8m/m8m-task-builder/SKILL.md`,讓現有 Codex Session 讀取指引。Skill 是工作說明;下面三個工具是直接操作 storage 的小型函式,不會啟動 Agent 或呼叫另一個 LLM。

| 新工具/service 方法 | 可接受的變更 | Server 責任 |
| --- | --- | --- |
| `register_task` | goal、完整 prompt、workflow aliases、output schema | 核對真實 bindings,補 source_message_id,持久保存一次 |
| `checkpoint_task` | current_step、context 的 patch、等待內容 | 合併 state、產生 wait_id;時間交由既有 save_schedule 保存及回填 schedule_id |
| `finish_task` | 最終 JSON object 及必要結果引用 | 讀真實 run 結果/批准記錄,驗 output schema,原子保存 output + completed |

沿用 `find_workflows / inspect_workflow / start_workflow / read_run` 做實際工作。需要稍後繼續時,同一 Session 依照已安裝的 `m8m-schedule-builder` 使用 `list_schedules / save_schedule / control_schedule`。保存只發生在建立任務、有需要保留的進展、等待或完成時;普通問答不要求額外產生 state JSON 或執行 checkpoint。使用者輸入仍是普通聊天。

每次寫入用現有 room row lock + `_fence(claim)` 核對仍有效的執行權。Context 使用 patch,Server 保留它管理的 wait ID、訊息來源及 run identities。模型不能把整個舊 room snapshot 覆蓋回 DB。

### 現有自動完成通知必須調整

目前 `run_result` 回合只能摘要,`ChatWorkspaceService.start()` 亦明確拒絕它啟動 workflow。單加新 prompt 不會令多個 workflows 自動接續。

新增僅由 Server 入列的 destination:`{"kind":"task_event","event_key":"..."}`。對具完整 Task definition 的 room,workflow 結果、既有 scheduler 的到期 occurrence、可信外部回覆產生此類事件;legacy room 保留原 `run_result` 摘要。

同步調整 `dispatch_once()` 的分流、`WorkspaceBridge` 可用工具、`INSTRUCTIONS`、service 啟動檢查。已存在的 browser `destination()` 繼續拒絕客戶偽造 `task_event`。

`task_event` 只是佇列中的通知資料,例如「原信用報告請求有結果,請讀取」,不是另一個 Agent 發出的指令。Worker 把它交回原 Codex thread;同一個 Codex 讀結果並繼續已授權工作。通知內容本身不構成新的執行授權。

普通使用者訊息直接送入原 Session。現有 bridge 尚未提供在對話內回答 workflow 問題的工具;需要此能力時,增加 `reply_to_workflow(execution_id, milestone_id, question_id, text)` 作為既有 `deliver() / reply()` 的薄包裝,讓同一個 Codex 讀取問題後提交。Service 只核對精確 ID、權限及重送,不先判斷整句話的意圖;未加入此工具前保留原本的明確 reply UI。目的不清楚便在原對話問清楚,人工批准不能以「收到」代替明確決定。

## 6. 多個 workflows 的恢復,沿用現有 run intent

第一版仍是一個 Task 同時最多一個 active workflow。不要把每個 workflow 變成另一個 Task。

現有 `intent()` 的 action identity 通常跟目前 message 綁定;同一步若由幾日後的新 event 再啟動,不能換成新 operation。

實作方式:

- 在第一次進入某個 workflow 動作時,Server 生成並保存穩定 `step_key`,例如 `analyze_application:1`;放在原 run intent 的 payload metadata。
- Task 模式的 action ID 使用 `task-step:<step_key>`,由原 `intent()` 與 room_id 共同產生 intent identity。同一動作的重送、timeout 及恢復沿用它。
- `start()` 必須先找既有 intent:payload 相同便讀回/reconcile,不因新的觸發訊息而再建 run;參數變了則回報衝突。
- `intent()` 目前會拒絕同一 intent 配上另一個 initiating message。重試時保留第一次的 origin;把後續觸發另記在 chat event,而非改寫原 origin。
- 補件後需要第二次分析,是新的業務動作 `analyze_application:2`;付款 timeout 是原 `process_payment:1` 的恢復,不能取得新 key。
- 每回合最多啟動一個 workflow,完成事件再接續下一個。原 `_assert_idle()`、native admission、operation journal 及已接受輸出維持為執行權威。

`step_key` 只是同一 Task 操作的穩定身份,不是另一套 graph/revision。若已安裝完整按揭 harness,Task 可以只呼叫那個 harness,由原 milestones 處理內部次序。

## 7. 等待六小時/三日:沿用現有 scheduler 和 skill

### 7.1 已有能力及實際缺口

已核對 Server 使用的 [M8M schedule skill](C:/NisanWorkspaces/m8m-platform-instagram-20260910/skills/m8m/m8m-schedule-builder/SKILL.md)、`workflow_schedules.py` 及 workspace bridge:

| 能力 | 目前狀態 | Task 使用方式 |
| --- | --- | --- |
| 時間、時區、一次性排程 | 已有 `once / daily / weekdays / weekly`;IANA timezone、date、HH:MM | 三日後跟進使用一次性排程,明確換算日期及時間 |
| 儲存、列出、修改、pause/resume/archive | 已有三個 MCP schedule 工具及相同 HTTP service | 沿用原工具、schedule ID 及 revision 檢查 |
| 到期執行及重試 | 已有 scheduler tick、occurrence、穩定識別碼 | 沿用,不加另一個計時器 |
| 排程 workflow/有序 series | 已有;每步輸入獨立保存,不自動串接輸出 | 保持現有行為;Task 不把按揭聊天改成 schedule series |
| 喚醒同一 Codex Session | 本機已加入 `resume_session` 目標,尚未部署 | once 到期在原 room 入列 task_event,原 thread resume |
| 自動通知安排下一次跟進 | 本機的 task_event 已可修改原等待的提醒;legacy run_result 保持只讀 | 沿用同 schedule ID、revision 及有限跟進次數 |

現有 scheduler 已在本機擴充為兩種目標:「執行 workflow」及「向原 room 入列一則喚醒訊息」。以下格式已由更新後的 service/MCP 接受;線上 Server 在部署前仍維持舊能力。

### 7.2 同一個 save_schedule,增加 Session 目標

現有 workflow 定義 `{name, timing, steps}` 保持相容;新增另一種定義 `{name, timing, target}`。兩者擇一,不用假 workflow 或空 steps 假裝喚醒。

`save_schedule(definition_json=...)` 的格式範例:

```json
{
  "name": "按揭申請:三日後檢查補件",
  "timing": {
    "frequency": "once",
    "timezone": "Asia/Hong_Kong",
    "date": "2026-09-28",
    "time": "09:00",
    "weekdays": []
  },
  "target": {
    "kind": "resume_session",
    "room_id": "m8m_chat:example",
    "wait_id": "task_wait:documents_example",
    "message": "補件跟進時間已到。請先讀取目前任務及新收到的文件;若仍有缺件,按原任務指引跟進。"
  }
}
```

時間及 ID 都是示例,不是已建立的排程。Bridge 必須從目前 claim 綁定 room/tenant/operator,核對 wait_id;不能接受模型指向另一個 room。目的只存 room_id,由 Server 讀取原 room 的 thread_id,避免 schedule 另外保存失去同步的 Session ID。

`timing` 沿用目前能力:一次性 date + HH:MM + timezone。六小時/三日是先按要求換算成一次性的實際時間;現有精度是分鐘,不能聲稱已支援任意秒數 interval。「每日一次」仍是 daily,不能混為一次性跟進。

第一版 `resume_session` 只支援 once。需要再跟進時修改原 schedule 的下一次時間,沿用原 ID;不把無限 recurring reminder 當預設。

Task 的等待只保存:

```json
{
  "current_step": "receive_documents",
  "context": {
    "application_id": "app_1042",
    "document_request_id": "document_req_36"
  },
  "waiting": {
    "wait_id": "task_wait:documents_example",
    "schedule_id": "m8m_schedule:example",
    "reason": "等待客戶補交糧單",
    "match": {
      "connector_id": "mail_account_1",
      "request_id": "document_req_36"
    },
    "on_wake": "讀取新文件;仍缺件便按原要求跟進。",
    "remaining_checks": 2
  }
}
```

`schedule_id` 必須來自實際儲存結果並由 Server 回填,不由模型捏造。若只等外部回覆而毋須定時跟進,該欄為 null。

### 7.3 Codex 使用兩個 skills 的方式

仍然是同一個 Codex Session:

1. Task Builder 指引 Codex 保存目標及進度;需要等待時先保存 waiting,取得 wait_id。
2. Schedule Builder 指引 Codex 讀 `list_schedules`,找到該等待已有的排程,或用 `save_schedule` 儲存一次性 `resume_session` 排程。
3. Server 以同一 transaction 保存 schedule 並回填原 waiting.schedule_id;Codex 讀回原 schedule,確認時間、目標及啟用狀態後,才說「已安排跟進」。
4. 到期後原 scheduler 把通知入列到同一個 room,原 Codex Session 讀取現況並繼續工作。

Skill 不是另一個 Agent,兩個 skills 只是同一 Session 使用的工作指引。Task Builder 不複製 Schedule Builder 的時間規則或建立另一套 schedule 工具。

`skills/m8m/m8m-schedule-builder/SKILL.md` 已同步補上:

- workflow 目標仍須 find/inspect 真實 workflow;resume_session 目標核對原 room/wait,不要求虛構 workflow。
- 沿用 list → save/control → readback;保留一次性、時區、修改 revision、重送及既有授權規則。
- 已授權 Task 中明確寫明的補件跟進,可以由原 Session 的 task_event 安排;普通 run_result 通知保持原本只讀。
- 目前不支援的目標應清楚回報,不能因 prompt 寫了「三日後」就宣稱已排程。

`WorkspaceBridge.call()` 已按 steps/target 分流。`ChatWorkspaceStore.schedule_action()` 保留每則 message 一個排程變更,並讓本 Task 的 resume_session 使用共用 transaction;同訊息先 start 再安排本 Task 提醒亦可接受。一般 workflow 排程保留原執行限制。原 Task 的後續喚醒使用已保存的動作身份,重送讀回同一 schedule,不能每次產生另一個;單改 skill 文字不足以提供這些行為。

### 7.4 到期、提早收到文件及重啟

`serve_workspace().maintain_rooms()` 已有每五秒的 `schedules.tick()`,直接沿用。Schedule 的 resume_session 分支在 DB transaction 內:

1. 核對 schedule 啟用狀態、原 room 尚未完成/取消、目前 wait_id 和 schedule_id 仍匹配。
2. 沿用原 occurrence identity,在 chat events/messages 入列一次通知,event key 使用 occurrence_id。
3. 同一 transaction 保存 occurrence 投遞完成。其意義是「通知已存入原對話佇列」,不是 Task 已完成,也不是文件仍未收到。
4. Commit 後交由現有 chat worker 恢復原 thread。模型呼叫不放在 transaction 內。

不新增 schedule tables 或常駐 worker。沿用 chat 的 message/event 去重;occurrence history 可從 event key 找到已入列訊息,毋須新增一張投遞表。

目前 schedule save 經 schedule_action 持有 room lock,tick 則先持有 schedule lock。新增跨兩者的寫入時,resume_session 的 save/投遞/取消路徑須共用 DB transaction,統一先 room、後 schedule 的鎖順序;tick 在進入原 workflow 分支前分流。不要在持有 room lock 的連線內,再以另一連線更新同一 room。

提早收到文件時,處理回覆的原 Session 解決 waiting;service 透過相同 scheduler 的儲存邏輯取消該等待的未到期提醒。Goal 已完成/取消時亦相同。未來排程被停止,不代表已入列訊息消失,所以真正執行通知前再核對 wait_id;過期通知直接忽略。正常 workflow 排程的 pause/archive 不取消已 admitted run,維持原契約。

重啟有一個需要補的具體行為:現有 `_tick_schedule()` 會跳過遲了超過一小時的 occurrence。這適用於原 workflow 排程規則,但長期 Task 的一次性喚醒不能因此遺失。對 `resume_session` 改為重啟後補投遞一次,再檢查 Task 是否仍在等待;原 workflow 的一小時規則保持不變。

建立提醒失敗或 schedule 達到目前每 tenant/operator 100 個未 archive 上限時,回報未成功安排,不能只保存 waiting 便聲稱有提醒。重試沿用原排程動作身份。等待結束後由 scheduler 歸檔該任務提醒並保留 occurrence 歷史,避免已用完的一次性提醒一直佔名額。

需要再次跟進時,讀目前 schedule revision 後修改同一 ID 的未來時間。`remaining_checks` 在每次真正入列提醒的 transaction 內減一;重送同一 occurrence 不再扣減。次數用盡不能再安排提醒,原 Session 應標為 blocked 或解決等待。文件 arrival、scheduler 通知及 workflow 結果的目標都是回到原 Session,不啟動額外的判斷 Agent;外部 arrival 及 workflow 自動接續仍按後文另行實作。

### 7.5 Scheduler 模組、skill、MCP、HTTP API 的實作規格

本節是已落實的 scheduler 修改清單及介面契約,驗收與限制見第 7.6 節。各層使用同一份 schedule definition,資料最後仍由 `WorkflowSchedules` 保存;不新增 scheduler service 或 Agent。Session 分支的 transaction helper 放在 `session_schedules.py`,供同一個 `WorkflowSchedules` 呼叫。

#### 共用 definition:保留 workflow,增加 Session 目標

在 `frontend/lib/m8mSchedulesApi.ts` 將現有單一 `ScheduleDefinition` 改為以下 union。`ScheduleTiming` 和 `ScheduleStep` 沿用原型別;Python `validate()` 實作相同的兩個分支。

```typescript
type WorkflowScheduleDefinition = {
  name: string;
  timing: ScheduleTiming;
  steps: ScheduleStep[];
  target?: never;
};

type SessionResumeDefinition = {
  name: string;
  timing: ScheduleTiming & { frequency: "once"; date: string };
  target: {
    kind: "resume_session";
    room_id: string;
    wait_id: string;
    message: string;
  };
  steps?: never;
};

type ScheduleDefinition = WorkflowScheduleDefinition | SessionResumeDefinition;
```

這是 schedule API 的控制格式,並非 Task/milestone 的業務 input schema。使用者仍以「三日後跟進」輸入;Codex 透過已有工具儲存排程。

| `workflow_schedules.py` 方法 | 具體修改 |
| --- | --- |
| `normalize_timing()`、`next_run()` | 保留現有日期、分鐘精度及時區算法。Session 分支額外限定 once;原 workflow 的四種 frequency 保留 |
| `validate()` | 接受恰好 `{name,timing,steps}` 或 `{name,timing,target}`。Session 分支不查 workflow readiness;核對 kind、room 所屬 tenant/operator、目前 wait_id,以及尚未結束的 Task;message 使用有上限的普通文字,容許換行,建議沿用 chat 的 8,000 字元上限 |
| `save()` | 保留原 create 去重/edit revision。Session 分支在同一 transaction 保存 schedule 與 waiting.schedule_id;同一 wait 已有 schedule 時讀回相同定義,變更時間使用既有 ID 的 edit,不另建第二筆 |
| `control()` | pause/resume/archive 沿用原名稱及 revision。Session 分支核對原 wait 仍有效;已解決的等待不能 resume。一次性時間已過而使用者手動 resume,沿用先 edit 至未來時間的規則 |
| `_tick_schedule()` | 在取得原 workflow schedule lock 前識別 Session 分支,採第 7.4 節的 room → schedule 鎖順序;Session 喚醒逾時補投一次 |
| `_advance()` | 維持原 workflow 執行。Session 由 `_tick_schedule()` 分流至 `session_schedules.tick()`,不進入 `_advance()`;只將通知存入 chat queue,不呼叫 `release.start()`,不製造 execution_id |
| `project()` | 移除一律存取 `definition['steps']` 的假設;Session history 的 steps 為空陣列,另返回實際投遞訊息引用 |
| `list()` | 返回兩種排程;`supported_targets: ["workflow", "resume_session"]` 供 skill/UI 確認能力;`server_now_utc` 提供本次查詢的實際 UTC 時刻,供同一 Session 判斷日期 |

Session 通知沿用 occurrence 的 `attempts / retry_after / error` 記錄暫時投遞失敗。成功入列後便結束該 occurrence;後續模型 quota/thread 恢復失敗由 chat message 的原重試處理,scheduler 不再次建立通知。等待已失效時標示 skipped 並寫清原因。新增 helper 是 DB 操作,沒有 LLM 呼叫。

#### Skill:修改 Server 已有的 m8m-schedule-builder

主檔是 `skills/m8m/m8m-schedule-builder/SKILL.md`,目前由 `schedule_skill_instructions()` 讀入 Server Codex。修改這份 release-owned skill,再同步本機可發現的副本;不能只改桌面 skill 就宣稱 Server 已更新。

| Skill 現有段落 | 修改後指引 |
| --- | --- |
| description/Resolve the request | 同時說明「排 workflow」及「稍後回到本 Task」。先讀 list_schedules 的 supported_targets;欄位缺少或不含 resume_session,就回報這個 Server 版本未支援。使用新取得的 server_now_utc,轉成要求的時區後比較完整時間;同一天稍後亦有效,不能只比較日期 |
| find/inspect workflows | 只適用於 steps 分支;Session 喚醒使用目前 Task 的 wait_id,不尋找假 workflow |
| Save through MCP | 加入第 7.2 節的 Session 範例;保留 definition_json 字串及 edit 的 schedule_id/expected_revision |
| pause/resume/remove | 保留原工具用法;說明停止提醒不等於停止已開始的 Codex 回合,過時通知會按 wait_id 忽略 |
| Verify and report | 讀回同一 schedule,核對原 room/wait、時間、enabled、next_run_at;報告「已安排喚醒」,不能說文件仍未收到或 Task 已完成 |
| Automatic notifications | legacy run_result 仍只讀;已授權原 Task 的 task_event 可以儲存/修改本 Task 的 resume_session 提醒 |

Task Builder skill 只指示「需要稍後繼續時使用已安裝的 schedule skill」,不再抄一份時間算法、工具契約或排程規則。

#### MCP:沿用三個工具,修改 bridge 內部分流

對外工具名稱和參數保留:

```typescript
list_schedules({});
save_schedule({
  definition_json: JSON.stringify(definition),
  // 建立時省略以下兩項;修改時兩項必須同時提供。
  schedule_id: existingScheduleId,
  expected_revision: "3"
});
control_schedule({
  schedule_id: existingScheduleId,
  expected_revision: "3",
  action: "pause" // 或 resume、archive
});
```

上段是工具呼叫形式示意,definition 使用前述共用格式。MCP 的 revision 維持十進位字串;bridge 轉成整數交給 service。HTTP API 使用整數,兩者不要混用。

需要改 `chat_codex_runner.py:TOOLS / WorkspaceBridge.call()`:

1. 更新 save_schedule 的 description,列出 steps/target 二擇一;不能再無條件要求 `definition.steps` 或檢查所有 import 已 inspect。
2. steps 分支保留原 inspect 規則;resume_session 分支從 claim 綁定目前 room。MCP 可以省略 target.room_id,由 bridge 補入;若有提供但不符原 room,拒絕。共用 service 收到的永遠是完整 definition。
3. `list_schedules` 透過原 service 返回 supported_targets 及 server_now_utc;保留已有 defaults、schedule_url、worker_ready。每次新回合及 thread_resume 都注入 Server 當下完整 UTC 時刻,不能沿用建立 Session 時的日期或上次回合的時鐘。
4. `control_schedule` 先讀實際 schedule。task_event 只可控制自己的 resume_session 提醒,不能因工具已開放而修改其他 workflow 排程。

需要改 `chat_workspace_service.py:change_schedule()` 及 `chat_workspace_store.py:schedule_action()`:

- 對原 room 的 resume_session,允許有效 conversation/task_event claim;lease、stop_requested、原 Task 授權及 wait_id 必須仍有效。普通 run_result 維持禁止。
- 保留同一 message 的排程動作去重;重送相同動作讀回原 result。另一個回合再次安排同一 wait,也由 waiting.schedule_id 找到既有排程。修改必須帶目前 revision。
- 「同一訊息不能 start workflow 又 schedule」的舊限制,僅為原 Task 的 resume_session 跟進放寬。一般 workflow 排程仍不能被當成即時執行的額外授權。
- Session 分支把 schedule 寫入、wait 引用及動作 result 放在同一 DB transaction;沿用第 7.4 節的鎖順序。不要在 bridge 直接寫 SQL,也不要在持有 room lock 時調用另一連線更新該 room。

#### HTTP API:保留原路由,兩種 definition 共用 service

Backend prefix:`/v1/portfolios/<portfolio_id>/m8m/schedules`。現有 frontend proxy 已放行以下方法,不需要新增一組 Session scheduler 路由。

| 方法/相對路徑 | Request | Response/修改 |
| --- | --- | --- |
| `GET /` | 無 body | `{success:true,schedules,worker_ready,supported_targets,server_now_utc}`;加入 Session history 投遞引用;時鐘是帶 Z 的 ISO UTC timestamp |
| `GET /catalog` | 無 body | 保留 workflow catalog;Session 提醒不依賴此路由 |
| `POST /` | `{client_request_id,definition}` | `{success:true,schedule}`;definition 可為 steps 或 target |
| `PUT /<schedule_id>` | `{expected_revision,definition}` | `{success:true,schedule}`;expected_revision 是整數 |
| `POST /<schedule_id>/control` | `{expected_revision,action}` | `{success:true,schedule_id,action}`;action 仍為 pause/resume/archive |

建立 Session 提醒的 HTTP body 範例:

```json
{
  "client_request_id": "resume-documents-example-1",
  "definition": {
    "name": "按揭申請:三日後檢查補件",
    "timing": {
      "frequency": "once",
      "timezone": "Asia/Hong_Kong",
      "date": "2026-09-28",
      "time": "09:00",
      "weekdays": []
    },
    "target": {
      "kind": "resume_session",
      "room_id": "m8m_chat:example",
      "wait_id": "task_wait:documents_example",
      "message": "補件跟進時間已到。先讀取新收到的文件,仍缺件才跟進。"
    }
  }
}
```

這是示例請求,不是部署後的執行記錄。HTTP 沒有目前 Codex claim,因此必須提供 room_id;service 以既有登入身份/tenant 核對 room 權限。tenant/operator 不接受 body 覆寫。修改時保留同一種目標及原 room/wait,不能把舊 workflow schedule 換成另一個 Task 的提醒。

共用 schedule response 保留 `schedule_id / revision / enabled / definition / next_run_at / history`。Session occurrence 的讀取格式為:

```typescript
type SessionOccurrenceView = {
  occurrence_id: string;
  scheduled_for: string;              // UTC ISO timestamp
  status: string;                     // 沿用 running/completed/skipped/failed
  error: string | null;
  steps: [];                          // 沒有 workflow execution
  delivery: {
    room_id: string;
    message_id: string | null;        // 實際已入列才有值
  };
};
```

`delivery` 由 occurrence_id 對應的 chat event/message 讀出,不新增另一個投遞資料表。這裏 completed 表示通知入列完成;UI 標示「已送回原對話」,不顯示「Task 已完成」。Workflow occurrence 維持原 steps 格式。

沿用現有錯誤 envelope `{success:false,error,message}`:route 自身無身份檢查返回 401;部署的 native tenant policy 可能先返回 403,本次線上無 token 實測為 `native_tenant_access_forbidden`/403。不在可見 scope 的 room/schedule 404;舊 revision、已結束 Task 或失效 wait 409;混用 steps 和 target、未知 kind、非 once 的 Session 提醒、超長文字 422;暫時 service 故障 503。MCP 保持自身 isError 回傳方式,message 沿用相同的可讀原因。

在 `workflow_schedules_api.py` 保留原 JSON body 大小限制、認證及 no-store;新增目標的規則只實作在 service,避免 MCP 和 HTTP 各判一套。`frontend/lib/m8mSchedulesApi.ts:schedulePayload()` 依 union 分支序列化,不能一律 `.steps.map()`;`M8mSchedules.tsx` 同步修改列表、搜尋、history、editor,Session 編輯只顯示時間和提醒文字,原 room/wait 保持固定。

#### 更新次序及針對性驗收

先讓 service/worker/API 能讀寫新目標,再同步 MCP、Server skill 及 UI,最後才回傳支援 resume_session 的 capability。只更新 SKILL.md 不會令舊 validator 或 worker 理解新格式。

| 驗收位置 | 必須覆蓋 |
| --- | --- |
| `tests/test_m8m_workflow_schedules.py` | 舊 steps 定義相容;兩種 definition 互斥;Session once 限制;同 wait 去重;revision 衝突;到期入列且不呼叫 release.start |
| `tests/test_m8m_chat_schedules.py` | MCP 自動綁原 room;偽造 room 被拒;conversation/task_event 的有限支援;legacy run_result 只讀;readback 正確 |
| `tests/test_m8m_chat_workspace.py` | schedule/wait/message transaction 中斷後不重複;補件與到期同時發生;恢復原 thread |
| 原 schedule API/frontend tests | POST/PUT/control 的兩種目標、revision 型別、原認證;Session 列表不再存取不存在的 steps;正確顯示投遞結果 |

上述 scheduler 驗收已在本機執行。詳細 Session 情境集中於 `tests/test_m8m_session_schedules.py`,與原有三個 backend suites 一起跑;原 API handlers 及 frontend proxy 共用修改後的 service,不增加路由。

### 7.6 本次實作紀錄及邊界(2026-09-25)

| 層 | 已實作 |
| --- | --- |
| Scheduler | `workflow_schedules.py` 接受 steps/target;`session_schedules.py` 處理同 room、有效 wait、once、同 wait 去重、revision、提醒 quota、room → schedule lock、原 occurrence 身份及逾時補投 |
| PostgreSQL | Chat store 初始化新增四個 Task 欄位、基本 JSON/狀態 constraints;原 schedule actions 增加 `resume_room_id`,只標記該訊息已保存本 Task 提醒,沒有新計時表或投遞表 |
| Task 保存 | `chat_tasks.py` 提供 read/register/checkpoint/finish 的小型 storage 方法;來源訊息、wait_id 及 schedule_id 由 Server 管理,context 使用 patch;解決等待/blocked/cancelled/completed 會歸檔原提醒 |
| MCP | 三個原 schedule 工具名稱及參數保留。MCP 可省略 room_id 並由 claim 綁定;拒絕另一個 room。提醒/waiting/action receipt 同 transaction;workflow 排程保留每回合 inspect 及原執行限制 |
| Session | `task_event` 進入原 chat queue,執行前及工具寫入時核對等待;每回合重新讀 DB goal/state,使用原 `thread_resume`。排程沒有模型呼叫;真正回應由原 chat worker 執行 |
| HTTP API | 原 GET/POST/PUT/control 直接支援 Session target;GET 回傳 supported_targets。沿用身份、body limit、revision、錯誤 envelope;HTTP 必須提供 room_id |
| Server skill | 更新 release 內 `m8m-schedule-builder` 及其 metadata,並同步本機同名 skill;新增精簡的 `m8m-task-builder`,只引用已有 scheduler 指引。兩份 skill 均由同一 Codex 回合讀取 |
| 前端 | 同一 Schedules 清單搜尋/顯示兩種目標。提醒 editor 只修改日期、時間、時區及文字;room/wait 固定。History 顯示「Sent back to task」,提供原對話連結;chat transcript 標示 Task reminder |

一次性提醒成功入列後,`enabled` 保留,`next_run_at` 為 null;原 wait 仍可用同 schedule ID 安排下一次已授權跟進。等待結束才 archive,history 留在原表。Archive **對話**只是 UI 分類,仍保留其提醒;Task cancelled 才停止後續工作。

Task 未註冊的舊 room 保留原聊天行為;目前新 room 亦由同 Session 在真正需要持久任務時呼叫 register,而非強制替每段一般討論建立 Task。

**本次刻意限定為第 7.5 節。** Scheduler 的 task_event 只開放 read_task、read_run、checkpoint_task 及三個 schedule 工具,可整理原等待並安排有限跟進;沒有開放新 workflow 啟動、harness 編輯或外部傳送。普通 conversation 仍可使用原 workflow 工具。Legacy run_result 仍只有 read_run。

第 6 節跨回合穩定 workflow step identity、自動接續下一個 workflow、第 8 節 email ingress/附件、第 9–10 節完整資產下載與獨立 task/output API、goal 專用 UI,以及第 11 節自動恢復 interrupted message,**尚未實作**。finish_task 目前只提供 output schema 驗證、JSON 保存及提醒清理;完整結果引用/批准/資產可用性的 Server 驗證仍須與那些功能一同補上,不能將它描述為完整按揭系統已驗收。

本機驗收:

- 獨立 WSL PostgreSQL 16 cluster,測試使用各自 schema,沒有接觸正式資料庫。四個 backend suites 共 **79 passed**:`test_m8m_session_schedules.py`、`test_m8m_workflow_schedules.py`、`test_m8m_chat_workspace.py`、`test_m8m_chat_schedules.py`。
- 覆蓋同 wait 去重、revision、跨 scope、HTTP 身份及 MCP 綁 room、一次性限制、quota、有限跟進、停用 claim、原 workflow 相容、提醒/wait/receipt rollback、投遞 savepoint rollback、停機三日補投、並行 tick、補件與到期競態、取消及 archive 對話的分別。
- Codex SDK fixture 驗證恢復**同一 thread**及載入最新 goal/state;沒有呼叫真實模型、email、銀行或付款 provider。
- 前端四個 suites 共 **50 passed**:Schedules、ChatWorkspace、m8mChatApi、m8mRunProxy;`npm run typecheck` 通過。驗證提醒不查 workflow catalog、目標不變、JSON 不包含 steps、原 chat 連結及投遞完成標示。
- Server schedule/task skills 通過 `quick_validate.py`。Release builder 的既有 `skills/m8m` 與 `milestone_8_milestone` source roots 已涵蓋新增檔案。

#### Server 部署及真實 Session 驗收

2026-09-25 17:30 UTC 已將 backend、兩份 Server skills 及 frontend 一起部署至 Tencent 的獨立 M8M 服務,release 為 `20260925T171812Z-ad7fdc9c9d73`。前一版本 `20260925T160511Z-2fae56ede2e6` 保留。候選版本以當時線上版本加本功能建立,沒有夾帶共享工作樹中其他尚未部署的 harness/provider 修改。

- 候選版本在 Linux 的獨立 PostgreSQL 測試庫跑五個 backend suites:**81 passed**;測試庫隨後移除。前端四個 suites:**50 passed**;typecheck、Next production build、49 個 Codex Node worker 測試通過。
- 正式 M8M 資料庫已備份;既有 store 初始化套用增量欄位。切換只處理 M8M 服務,既有 10 個 execution 及 4 個 provider release 批准保持不變,BCL 設定保持不變。
- 使用 `m8m-cloud` tenant 的兩個專用 `[Deployment test]` 對話及真實 Server Codex `gpt-6-luna`,沒有新增租戶權限。不是 fixture 或手動直接寫入 Task state。

| 線上情境 | 實際結果 |
| --- | --- |
| 原 Session 使用 task/schedule skills | 實際呼叫 read/register/checkpoint、list/save schedule,讀回同一 room/wait 的提醒 |
| 同 wait 再次建立、暫停、修改、恢復 | HTTP API 讀回同 schedule ID;舊 revision 修改返回 409;維持同 room/wait |
| 等待期間重啟 worker | 兩個 Task 的 goal、state、wait、schedule 引用及 thread ID 保留 |
| 真實到期投遞 | 17:35 UTC 原 maintenance tick 產生一筆 task_event、一筆 completed occurrence;steps 為空,沒有 workflow execution |
| 真實 thread resume | 沿用原 thread `01a0d99e-95bc-7d10-82d3-a70e773a71b8`,read_task 後 checkpoint `reminder_seen=true`;remaining_checks 只減一次 |
| 收到測試補件後完成 | 同一 thread 呼叫 finish_task,保存 `{"received":true}`,waiting 清空、提醒歸檔 |
| 提早取消另一個 Task | 同一 thread 保存 cancelled,waiting 清空、提醒歸檔,沒有 task_event 或 occurrence |
| 前端 | 既有 Schedules 顯示 Original task、固定 room/wait 的提醒編輯器,以及 Sent back to task;完成/取消後提醒移出有效清單 |

初次上線的模型測試發現時區判讀問題:第一次只給 `2026-09-25 17:35 UTC` 時,模型拿香港的翌日日期比較,誤稱時間已過,沒有呼叫 save_schedule。於原對話補充等值 `Asia/Hong_Kong` 日期/時間後才成功保存;API 的 UTC 計算及投遞正常。其後 release `20260925T185248Z-3733ff493c79` 已加入每回合/list_schedules 的 Server UTC 時鐘及 skill 指引;新一輪真實 QA 首次便成功保存 UTC 今天稍後的提醒,舊 Session 也正確讀取新時鐘。這修正了已重現的跨日問題,並非對所有自然語言日期表達的全面保證。

17:36 UTC 的唯讀資料庫驗收確認:兩個測試 Task 分別 completed/cancelled;所有六則訊息有真實 turn_id 並完成;只有一則提醒,沒有重複 workflow 或未清理的測試提醒。原對話及 occurrence 歷史保留供查閱。

部署、備份及驗收紀錄存於 Server 的 `/var/lib/m8m-cloud/evidence/20260925T171812Z-ad7fdc9c9d73-promotion.json`、同目錄的 `20260925T171812Z-ad7fdc9c9d73-session-smoke.json`;資料庫備份位於 `/var/lib/m8m-cloud/backups/task-session-20260925T171812Z-ad7fdc9c9d73/`。這些是工程驗收紀錄,不是每個 Task/milestone 的執行要求。

#### 時區修正的第二輪部署及 QA(19:08 UTC)

目前線上 release 為 `20260925T185248Z-3733ff493c79`,於 19:01 UTC 切換;回退版本保留為 `20260925T173854Z-4eba451f8fb3`。以當時最新線上版本為基礎,只修改五個檔案:runner、scheduler、schedule skill、前端 response 型別及回歸測試;保留期間已上線的其他功能。

- **85 backend tests、50 frontend tests、49 Codex worker tests 通過**;typecheck、Linux production build、skill 格式驗證通過。Backend 使用獨立測試資料庫,完結後移除。
- 使用普通對話要求「UTC 今天稍後跟進一次」,不提供 Task input schema、wait ID 或排程 JSON。真實 Codex 首次便保存 `2026-09-25 19:07 UTC`,沒有要求使用者補充翌日的香港日期。
- 19:07 UTC 自然到期,原 scheduler 產生一筆提醒;同一 thread `01a0d9f2-4134-7422-afd9-452046c92f27` 恢復,保存 `reminder_seen=true`,跟進次數只減一次。補件後該 thread 以 finish_task 保存 `{"received":true}`,清空 wait 並歸檔提醒。
- 第二個 Task 使用 `Asia/Hong_Kong` 翌日日期,首次保存成功;使用者取消後變成 cancelled、清空 wait 並歸檔提醒,沒有任何投遞。
- 兩個等待中的 Task 經 worker 重啟後保留 goal/state/thread;部署前已有的 Session 亦以原 thread 恢復,透過 list_schedules 讀取新的 UTC 時鐘並正確回答 `future:true`,其 completed 狀態及原 JSON 沒有改變。
- Browser 實際顯示 UTC 日期/時間、Original task 連結及 Sent back to task 歷史。API 的 server_now_utc 與實際時鐘相符;無 token 請求被既有 native tenant policy 以 403 拒絕。
- 最後核對 1,973 個線上 source files 與候選版本一致;11 個原有 execution 沒有新增,沒有 unsettled execution 或 queued/running chat message。兩個新測試提醒均已歸檔,原對話及投遞歷史保留。

Server 開始時只有約 8 GB 可用空間,未達既有 10 GB build 門檻;先恢復服務,再清理約 2.5 GB 可重建的 M8M webpack/npm build cache 後部署。未刪除 release、資料庫、備份或 execution。M8M build 限制為 1 GB RAM;BCL 定義在切換前後一致。

新部署與真實模型驗收紀錄為 `/var/lib/m8m-cloud/evidence/20260925T185248Z-3733ff493c79-promotion.json` 及同目錄的 `20260925T185248Z-3733ff493c79-session-smoke.json`。本機完整紀錄見 [本輪部署 QA](C:/NisanWorkspaces/m8m-platform-instagram-20260910/output/task-session-scheduler/clock/QA.md)。第 7.6 節所列的多 workflow 自動接續、email ingress 等未實作邊界維持不變。

驗收過程保留兩項觀察:提醒回合曾有一次 checkpoint_task 失敗,模型自行重試成功;功能驗收後另一個 M8M build 暫停服務,Browser 短暫顯示 502,該 build 結束後三個服務及 API clock 讀取恢復。這些不代表資料遺失,亦不能把本次結果描述為所有工具呼叫零重試、部署期間零中斷。

## 8. 三日後的 email 如何回到這個 Task?

沿用現有 events 表保存本 Task 的回覆關聯,不建立跨 Task 傳遞協議。

提出文件要求時,記錄一個 `task_reply_binding` event,其 data 包含:

```json
{
  "connector_id": "mail_account_1",
  "correlation_key": "provider_thread:thread_812",
  "wait_id": "task_wait:documents_example",
  "request_id": "document_req_36"
}
```

`room_id` 已是 event 欄位,毋須再放一份。查詢以已驗證 connector/account 的穩定 thread/request ID,join rooms 限定 tenant/operator。必要時對 `task_reply_binding` 的 connector_id/correlation_key 加 expression index;第一版毋須新增 routing table。

外部 connector 必須驗證來源及租戶,再調用內部 `receive_task_event()`:保存原內容/附件引用,用 provider event ID 去重,與 queue 入列同一 transaction。普通 chat HTTP body 不能冒充 webhook。

回覆內容仍按語意理解,不要求客戶回覆 JSON。只有「收到文案」卻沒有可靠關聯,不猜是哪個 Task;留待入口確認。若存在多個匹配,也不能任選。歷史 binding 保留,遲到回覆可以回到原 room,但不得自動滿足已換掉的 wait_id。

目前核對的 chat 路徑只有文字 send 與原生 workflow reply,**沒有證實已具備一般 email ingress/任意附件 upload**。接入按揭時要補實際 connector;不能只寫 prompt 就宣稱可以接收外部回覆。人工批准還要核對回覆者有權批准及批准內容,匹配 thread 本身不代表批准。

## 9. 最終 JSON 及圖片/文件 URL

Task 完成的結果可以是:

```json
{
  "application_id": "app_1042",
  "decision": "approved",
  "payment_id": "payment_205",
  "crm_record_id": "crm_872",
  "documents": [
    {
      "name": "申請處理結果.pdf",
      "url": "https://m8m.example.com/m8m/api/assets/asset_result_example/download"
    }
  ]
}
```

上例 ID 與 URL 均為設計示例,並非已產出的結果或已存在的路由。最終 output schema:

```json
{
  "type": "object",
  "required": ["application_id", "decision", "payment_id", "crm_record_id", "documents"],
  "additionalProperties": false,
  "properties": {
    "application_id": {"type": "string", "minLength": 1},
    "decision": {"enum": ["approved", "declined"]},
    "payment_id": {"type": ["string", "null"], "minLength": 1},
    "crm_record_id": {"type": "string", "minLength": 1},
    "documents": {
      "type": "array",
      "items": {
        "type": "object",
        "required": ["name", "url"],
        "additionalProperties": false,
        "properties": {
          "name": {"type": "string", "minLength": 1},
          "url": {"type": "string", "format": "uri", "pattern": "^https://"}
        }
      }
    }
  }
}
```

Schema 只驗輸出格式。批准分支還要讀取實際批准、付款成功及 CRM 更新;拒絕分支不付款,payment_id 為 null。缺成功結果時,不能靠一份格式正確的 JSON 宣布完成。

`finish_task()` 需確認輸出所引用的 workflow/asset 屬於本 Task 和相同 tenant,且是已接受、可用的真實結果。完成時原子寫入 `task_output`、`task_status='completed'`,清除 waiting,透過現有 scheduler 停止該等待的提醒,寫一次完成 event。重試返回原結果;之後的普通問題不能覆寫它。

### Asset 現有能力及必要增量

目前 `execution_lineage_reader.asset()` 從既有索引定位 Server 保存的檔案,但 HTTP `GET /assets/<asset_id>` 返回 JSON metadata/分頁 base64。這不是使用者所需的圖片/文件下載 URL。

實作一個小型延伸:

1. 既有 workflow 產生的檔案沿用 registered asset 和持久 run storage,不重新生成或另存一套索引。
2. 在 `execution_lineage_api.py` 增加 authenticated `GET /v1/portfolios/<portfolio_id>/m8m/assets/<asset_id>/download`,經既有 tenant/operator、accepted output 及安全路徑核對後串流檔案;若檔案已在 object store,可轉到當次簽發的下載位置。
3. Frontend proxy 增加對應 binary response;既有 JSON route wrapper 不可直接包住檔案 bytes。由 Server 的 configured public origin 和路由建立 URL,不能由模型拼一個域名。
4. 最終 JSON 保存穩定 Server URL。下載時才做權限核對/簽名,因此不把幾小時便到期的 storage signed URL 當永久結果。
5. Worker 外部生成的檔案必須先 upload/register 成真實 Server asset,成功後才納入 output。上傳失敗保留持久檔案再試上傳,不重新生成圖片。

Task input 的附件不冒充 workflow output。第一版可在原 user message event.data 保存已驗證的持久附件引用,由實際 upload adapter 提供;不把它硬塞入需有 output_record_id 的 execution asset table。附件只有臨時本機路徑時,還未達到可恢復條件。

## 10. 現有檔案的具體修改清單

以下路徑以平台 repository root 為準。新增檔案已標示;本文件不直接修改它們。

| 檔案/方法 | 要做的修改 |
| --- | --- |
| `skills/m8m/m8m-task-builder/SKILL.md`(新增) | 同一 Codex Session 讀取的工作指引:語意輸入,保存 goal/完整 prompt/workflow bindings/output schema;一個 Chat 一個 Task |
| `milestone_8_milestone/m8m_engine/chat_workspace_store.py` | 四欄位 migration;Task 保存、scheduler 通知入列及去重;調整 schedule_action 的原 Session 分支,不加 Task due query |
| `milestone_8_milestone/m8m_engine/chat_workspace_service.py` | 實作 register/checkpoint/finish;沿用 schedules()/change_schedule(),保存與清理 wait 的 schedule 引用;run 狀態及外部回覆接回原 Session |
| `milestone_8_milestone/m8m_engine/chat_codex_runner.py` | 原 thread 讀 definition/state;保留已安裝 schedule skill,schedule 工具接受新 target;允許原 Task 的 task_event 跟進,legacy run_result 保持只讀 |
| `milestone_8_milestone/m8m_engine/chat_workspace_worker.py` | 沿用現有 schedules.tick();接通 Session 通知及原回合恢復,不新增另一個 timer loop |
| `milestone_8_milestone/m8m_engine/workflow_schedules.py` | validate/save/_tick_schedule/_advance 增加 resume_session 分支;投遞及 wait 引用同 transaction;project/list 顯示目標與訊息結果;Task 喚醒逾時補投遞 |
| `skills/m8m/m8m-schedule-builder/SKILL.md`(既有) | 補 resume_session 的一次性排程及 readback 指引;Task skill 引用它,不複製排程能力 |
| `milestone_8_milestone/m8m_engine/workflow_schedules_api.py` | 沿用原 schedule routes,令新目標通過同一 service 驗證及 tenant/operator 核對 |
| `milestone_8_milestone/m8m_engine/chat_workspace_api.py` | 新建 room 初始化 Task;原 GET/history 包含 Task 欄位;增加讀最終 JSON 與取消原 Task 的路由 |
| `milestone_8_milestone/m8m_engine/execution_lineage_api.py / execution_lineage_reader.py` | 沿用 asset registry,增加實際檔案 download;不把 metadata URL 當圖片 |
| `frontend/lib/m8mChatApi.ts` | 加入 Task 型別/狀態顯示;Task 狀態和目前模型 turn_status 分開 |
| `frontend/components/M8mChatWorkspace.tsx` | 顯示 goal、目前等待及原 schedule 的 next_run_at/連結、final JSON/URL;保留 Process tracker |
| `frontend/components/M8mSchedules.tsx / frontend/lib/m8mSchedulesApi.ts` | 同一 Schedules 清單識別 resume_session,顯示原任務連結及通知投遞結果;保留 workflow 排程編輯器 |
| `frontend/app/api/m8m/[...path]/route.ts` | 放行新 scoped endpoints;下載路由處理 binary,output route 保留 JSON 原貌 |
| `tests/test_m8m_chat_workspace.py / tests/test_m8m_workflow_schedules.py / tests/test_m8m_chat_schedules.py` 及既有 frontend tests | 補 Task 保存、同一 scheduler 的喚醒/逾時補投/取消競態及原 workflow 排程相容性 |

不修改 harness milestone 的語意輸入、完整 master prompt、FlowSteps、具名結構化輸出契約。Workflow 內進度及外部操作仍由原 execution repository 管理。

### HTTP 增量

路由前綴沿用 `/v1/portfolios/<portfolio_id>/m8m/chat-rooms`:

| Route | 行為 |
| --- | --- |
| `POST /`、`POST /<room_id>/messages` | 保留現有形式;輸入仍是 text 及可選 attachment references |
| `GET /<room_id>` | 原 history 加 Task 欄位,刷新頁面直接還原 goal/等待 |
| `GET /<room_id>/task/output`(新增) | 完成時 body 就是 task_output;不加 outputs/recipient envelope。未完成返回明確的 not-ready response |
| `POST /<room_id>/task/cancel`(新增) | 停止該 Task 後續推進並清理其 scheduler 提醒;取消已關聯 run 沿用原 execution cancel |

排程沿用現有 `/v1/portfolios/<portfolio_id>/m8m/schedules` API 與 room MCP 工具,不另新增 Task timer endpoints。

現有 message body 有精確欄位檢查。加入附件時須同步更新 API、service、store event data 及 frontend types,不能只把新欄位發到舊端點。內部 task_event 不向 browser 開放任意寫入。

## 11. 重啟及狀態:哪些行為必須一起改?

```text
drafting → running → waiting → running → completed
                  ↘ blocked → running
drafting / running / waiting / blocked → cancelled
```

`running` 表示任務可推進或正在執行,不表示模型永遠在線。`blocked` 表示需要客戶/操作人員處理具體問題;申請被拒絕是業務結果,可正常 completed。

| 情況 | 必須發生的行為 |
| --- | --- |
| Worker 在等待期間重啟 | DB 的 waiting.schedule_id 及原 schedule/occurrence 仍在;scheduler 恢復後向原 room 補投一次仍有效的喚醒 |
| Workflow 完成,但 browser 已關閉 | maintenance 讀取真實 run 狀態,入列 Task event,繼續原 Task |
| Workflow 變成 needs_reply/blocked/cancelled | 也要被 maintenance 觀察;現有 dispatch_results 只處理 completed,需要擴充,不能讓 Task 無限 running |
| Codex 回合在工具呼叫後中斷 | 先 reconcile 原 thread/turn/intent,再恢復同一動作;不能盲目建立新 run |
| 付款成功,回覆遺失 | 查原 execution/外部 operation,沿用原 idempotency;不知道結果則 blocked,不能再付一次 |
| 付款成功,CRM 失敗 | 保存付款成功事實,只恢復 CRM |
| Model quota/登入失效 | Task blocked 並保留輸入;恢復服務後重試同一 pending message |
| 任務完成後收到舊 callback | 保存為遲到事件;不再啟動 workflow,不覆寫 final output |
| Archive 對話 | 只是 UI 分類,不能當作取消;需要停止工作用 Task cancel |

`claim()` 目前把 expired turn 標為 interrupted,而且它會阻擋後續 queue。Task 模式要由 maintenance 對可安全 reconcile 的中斷回合做有限次重新入列,例如最多兩次;次數記在原 message events,不另建重試表。超出或結果不明時 blocked,顯示原因及原 message retry。使用者主動 stop 不自動重試。

首次註冊/checkpoint 已成功,但模型回合在下一步之前中斷,也要由相同恢復路徑續接;不能留下 running room 卻沒有 queue、active run 或有效等待。回合正常結束時,service 必須確認已完成、已等待、已有 run/下一個 durable continuation,或明確 blocked;需要定時跟進的等待必須有已成功保存的 schedule。

## 12. Migration 次序及驗收

1. **資料層**:先加四欄位及 store 方法;舊 rows 的 task_definition/status 留 NULL,保留原聊天,不從標題猜 goal。
2. **模型與 service**:加入 Task skill、三個工具、每回合上下文,以及 Task event/intent 恢復。新建立的 room 使用 Task 模式;舊 room 只在明確選定單一任務時轉換。
3. **沿用 scheduler**:在現有 schedule 模組、bridge 及已安裝 skill 增加 resume_session;補重啟後逾時投遞、提早解決等待後的取消。原 tick、資料表及排程工具保留;完成實際接線後才聲稱可喚醒同一 Session。
4. **交付與 UI**:完成 output endpoint、資產 URL、goal/等待顯示,再啟用完整 Task 入口。

在沿用 `M8M_TEST_DATABASE_URL` 的獨立 PostgreSQL 測試庫驗證,不在正式庫試 migration。現有工作樹有其他未提交變更,實作時只處理上述範圍。

| 驗收情境 | 預期 |
| --- | --- |
| 建立後刷新頁面/重啟 worker | 同一 room_id、goal、state、thread reference 仍在 |
| 零散補件/自然語言修正 | 直接交給原 Codex Session;有需要才更新 context,不需填 input schema |
| 相關問題或獨立新要求 | 原 Session 正常回答;沒有前置分類模型、額外 Agent 或 A2A 訊息 |
| 兩個 workflows 依次完成 | 同一 Task 自動接續;不需要多一則使用者「繼續」 |
| 到期、callback 與重送同時抵達 | 事件去重、同 room 串行;過時 wait 不再提醒 |
| 多日等待中斷後恢復 | 原 scheduler 補投一次;即使離線超過一小時仍不遺失 Task 喚醒 |
| 提早補件/取消與 scheduler 同時到期 | 同一 transaction/wait_id 核對阻止過時提醒;已入列者在執行前再檢查 |
| 既有 workflow 排程與 skill | once/daily/weekdays/weekly、獨立 steps、原逾時與權限規則保持;Session 提醒出現在同一 Schedules 清單 |
| 同一付款觸發重送或回應遺失 | 原 intent/operation 被讀回,不產生第二筆付款 |
| Asset 未上傳/URL 尚不可用 | 不宣告完成;恢復上傳後才返回真實 URL |
| 任務完成 | task_output 可單獨讀取為一個業務 JSON;schema 正確且所需操作真實成功 |
| 舊 room/tenant 邊界 | 舊資料可讀;別人的 room、run、asset 不能混入本 Task |

上表是完整 Task 產品的驗收目標,不能全部視為已完成。本次完成第 7.6 節列出的 scheduler 本機及線上同 Session 驗收,並修正已重現的 UTC/香港跨日判讀問題;其餘端到端能力仍按該節的邊界待實作。

## 程式碼查閱入口

- [Chat store:資料表、claim、intent、result queue](C:/NisanWorkspaces/m8m-platform-instagram-20260910/milestone_8_milestone/m8m_engine/chat_workspace_store.py)
- [現有 Codex Session:prompt 及工具](C:/NisanWorkspaces/m8m-platform-instagram-20260910/milestone_8_milestone/m8m_engine/chat_codex_runner.py)
- [Chat service:執行及結果派發](C:/NisanWorkspaces/m8m-platform-instagram-20260910/milestone_8_milestone/m8m_engine/chat_workspace_service.py)
- [現有 M8M scheduler](C:/NisanWorkspaces/m8m-platform-instagram-20260910/milestone_8_milestone/m8m_engine/workflow_schedules.py)
- [Server 使用的 schedule skill](C:/NisanWorkspaces/m8m-platform-instagram-20260910/skills/m8m/m8m-schedule-builder/SKILL.md)
- [現有 maintenance worker](C:/NisanWorkspaces/m8m-platform-instagram-20260910/milestone_8_milestone/m8m_engine/chat_workspace_worker.py)
- [Asset 讀取及可用性檢查](C:/NisanWorkspaces/m8m-platform-instagram-20260910/milestone_8_milestone/m8m_engine/execution_lineage_reader.py)
planning-and-task-breakdownaddyosmani/agent-skillsBreaks work into ordered tasks. Use when you have a spec or clear requirements and need to break work into implementable tasks. Use when a task feels too large to start, when you need to estimate scope, or when parallel work is possible.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
screenpipethedotmack/claude-memSearch screen and audio history recorded by Screenpipe and optionally save selected context into claude-mem. Use when the user asks to recall desktop activity, a meeting, or something seen in another app through Screenpipe.Stars: 118kUpdated Claude CodeCodexVerifiedInstall
contact-widgetnexu-io/open-designSelf-contained floating chat widget with welcome screen, social links, meeting button, and message input. Single HTML file, zero dependencies.Stars: 108kUpdated Claude CodeCodexVerifiedInstall
meeting-notesnexu-io/open-designMeeting notes page — title bar with attendees, agenda checklist, decisions block, action items table with owners + dates, and a "next meeting" footer. Use when the brief mentions "meeting notes", "minutes", "1:1 notes", "all-hands recap", or "会议纪要".Stars: 108kUpdated Claude CodeCodexVerifiedInstall