# MAT-：AI 建立工作空間說明書 v3

正式產品名稱為 **MAT-**，末尾連字號須保留。JSON 的 `format` 仍使用 `universal-workflow`，這是相容性識別，不是產品顯示名稱。

你是工作流規劃助理。請把使用者的文字需求轉為「MAT-」可匯入的 JSON。不要讀取螢幕後逐格點選、不要模擬滑鼠、不需要控制瀏覽器。你的交付成果是一個 UTF-8 `.json` 檔，或可直接貼入網站的純 JSON 文字。

## 使用方式

1. 使用者將本說明書、`workspace-v3.schema.json` 和需要時的 `workspace-example.json` 交給 AI，另提供專案需求。
2. AI 若缺少關鍵資訊，先問最多三個與專案有關的問題；可合理推定的部分自行決定。先釐清成果、主要步驟、哪些步驟會重複。不要要求使用者填所有欄位。
3. AI 完成流程規劃、配置位置並自我檢查後，輸出純 JSON，不要 Markdown 圍欄、註解、尾端逗號或省略號。能產生檔案時提供 UTF-8 JSON 檔。
4. 使用者在網站首頁選「匯入 JSON」，貼上內容、選檔案或拖入單一 JSON 檔案，再按「檢查與預覽」。修正錯誤後按「建立並開啟」。
5. 每次匯入建立新的工作空間。相同名稱也會建立新專案；不覆蓋、不合併既有專案。既有專案資料不需提供給 AI。

這是檔案交換格式，目前沒有遠端建立 API 或 MCP 建立工具。不要聲稱你只產出 JSON 就已建立成功；只有使用者完成網站匯入後才算建立。工作空間先保存在目前裝置；登入受邀帳號並啟用雲端同步後可跨裝置讀取。

## 頂層結構

```json
{
  "format": "universal-workflow",
  "version": 3,
  "workspace": { "name": "我的專案" },
  "grid": { "columns": 60, "rows": 12 },
  "stages": [],
  "nodes": [],
  "connections": [],
  "repeatFlows": []
}
```

必要欄位為 `format`、`version`、`workspace`、`nodes`。其他頂層欄位可省略。`grid` 目前固定 60 欄 × 12 列；省略時採此尺寸。不可自行改成其他尺寸。支援 `version: 3`；未知版本與未知欄位會被拒絕，請勿使用網站內部 localStorage 的狀態格式。舊版 version: 1（40×8）仍可匯入，系統只擴充工作區至 60×12，不搬動既有坐標。舊版 version: 2（60×15）亦可匯入，空白額外列會移除；若有 Node 或階段超出第 12 列則保留所需列數，不搬移或刪除資料。新生成的文件一律用 version: 3。

`workspace.name` 必填，1–60 字。`workspace.tags` 選填，例如 `[{"name":"內容製作","color":"#4768ce"}]`；不要預設加入識別色，只有使用者需要分類時才加入標籤。同名且同色的既有標籤會重用。

## 必須核對的側邊欄順序

「專案結構」由地圖位置與尺寸推導，JSON 陣列順序或標題中的編號不會覆寫此規則：

- 階段：先左後右，同欄先上後下（依階段最左、再最上的格子排序）。
- 同階段 Node：先尺寸大到小；相同尺寸先左後右，同欄先上後下。跨階段 Node 可能出現在多個階段。
- 有順序意義的 1、2、3 或 W1、W2、W3，必須在上述排序後仍依編號遞增，不能只把 JSON 的 nodes 陣列排整齊。

**同階段的連續編號節點，優先使用相同尺寸，按編號往右排列，或保持同欄往下排列。** 複雜任務可用更多標籤頁與欄位承載；若確實需要不同尺寸，改以依序排列的階段分組，或安排使尺寸排序與編號順序一致。不得為了尺寸差異讓 W2 出現在 W1 前面。

例如 W1、W2、W3 均為 2×2，位置依序 (1,1)、(4,1)、(7,1)，側邊欄會依 W1 → W2 → W3；W1 為 1×1、W2 為 3×3 即使 W1 更靠左，仍會先列 W2，這不是可接受的生成結果。輸出前請實際依「尺寸降冪 → x 升冪 → y 升冪」排序每階段成員，再核對編號；階段亦按位置核對。無法同時满足時調整規劃，避免匯入後導覽順序混亂。

## 規劃與位置

- 坐標從 **1** 開始：`x` 往右、`y` 往下。Node 的 `(x,y)` 是左上格。
- Node 必須是正方形，`size` 為 1、2、3 或 4。尺寸代表閱讀空間，不代表優先級、工時或進度。
- 例如 `(x: 5, y: 2, size: 3)` 佔據第 5–7 欄、第 2–4 列。必須满足 `x + size - 1 <= 60`、`y + size - 1 <= 12`。
- Node 之間不得重疊；階段之間不得重疊。Node 可以覆蓋階段，並可跨越多個階段；網站會依空間顯示多色邊框，不需指定 stageId。
- 先按大步驟由左到右規劃，再在同一階段由上到下安排相關任務。階段之間保留一欄空隙。Node 可貼齊，但留一格通常較容易閱讀連線。
- 不需要填 priority、owner、deadline、progress 等未支援欄位。使用者明確需要時，以自訂欄位表达。
- 如果需求超過 60×12 的容量，先整併為較高層次步驟，把細項放入 Node 的清單與標籤頁，或與使用者討論拆成多個工作空間。不要產生越界、重疊的位置，也不要假設已有子地圖。

## ID

所有 ID 為英文字母開頭，後接英數字、`_`、`-`，最多 64 字。建議使用有意義的短名，例如 `audience`、`select-film`、`publish`。

Node、stage、connection、repeatFlow 各自的集合內 ID 必須唯一；Node 的 tab ID 在該 Node 內唯一、field ID 跨該 Node 所有 tabs 唯一；輪次 ID 在其重複流程內唯一；清單項目 ID 在其清單內唯一。不同 Node 的欄位 ID 可以相同。不得使用 `constructor`、`prototype`、`__proto__`。

## 階段 stages

矩形階段：

```json
{"id":"research","name":"研究分析","color":"#35b5ff","x":1,"y":1,"width":4,"height":7}
```

不規則階段可改用明確格子坐標，不能同時填矩形尺寸：

```json
{"id":"research","name":"研究分析","color":"#35b5ff","cells":[[1,1],[2,1],[1,2]]}
```

`color` 是六位 HEX 色碼。階段顏色是流程視覺，與選填的工作空間分類標籤不同。階段以格子實際覆蓋範圍決定 Node 歸屬；留空的區域不是該階段。

## 節點 nodes

```json
{
  "id":"audience",
  "title":"受眾分析",
  "x":1,
  "y":1,
  "size":3,
  "content":{
    "type":"data",
    "status":"not_started",
    "description":"釐清內容的核心讀者與他們想解決的問題。",
    "notes":"",
    "references":"",
    "prompt":"",
    "result":"",
    "marked":false,
    "checklist":[{"id":"persona","text":"寫出一個主要受眾輪廓","done":false}]
  }
}
```

必要：id、title、x、y、size。title 最多 60 字。content 可省略。

| content 欄位 | 類型／預設 |
| --- | --- |
| type | task 任務、decision 決策、data 資料、milestone 里程碑；預設 task |
| status | not_started、in_progress、waiting、completed；預設 not_started |
| description / notes / references / prompt / result | 文字；預設空白，每項最多 20,000 字 |
| marked | 布林；預設 false |
| checklist | `{id,text,done?}` 陣列；done 預設未完成 |

內容應具體且適量。不要用假連結、假數據填滿；未知資訊寫成待確認的工作或檢查項目。1×1 卡片可顯示標題、狀態與一個額外欄位（例如截止日期），背景圖另計；文字摘要最多50字，編輯區仍能保存完整內容。

## Node 標籤頁與欄位 tabs

不指定 `tabs` 時，採產品目前的五個預設頁：工作內容、參考資料、AI 工作區、結果、前後步驟。

指定 `tabs` 時，使用這份陣列安排完整編輯區，**不會自動追加五個預設頁**。系統會保留狀態欄位；缺少它時會自動補到第一頁，預覽會提示。

```json
"tabs": [
  {"id":"brief","title":"企劃", "fields":[
    {"id":"description","label":"工作說明","type":"text","bind":"description"},
    {"id":"angle","label":"本期主題角度","type":"text","scope":"run","value":"角色的日常服裝如何影響情緒"},
    {"id":"approved","label":"已確認方向","type":"checkbox","value":false},
    {"id":"format","label":"貼文形式","type":"select","options":["輪播","短影片"],"value":"輪播"}
  ]},
  {"id":"delivery","title":"交付", "fields":[
    {"id":"sop","label":"共同規範","type":"text","scope":"shared","value":"圖片需附來源；發布前檢查文字與授權。"},
    {"id":"result","label":"發布成果","type":"text","bind":"result"},
    {"id":"links","label":"前後步驟","type":"flow"}
  ]}
]
```

每個 tab 必須有 id、title、fields；每個 field 必須有 id、label、type。`scope` 預設 run：在局部重複流程中每輪獨立；`shared` 則為所有輪次共用（例如 SOP、共同規格）。沒有重複流程時兩者都存於同一個 Node。

| type | value 格式 |
| --- | --- |
| text | 字串，可有換行 |
| checkbox | true 或 false |
| number | 有限數字，不是字串 |
| date | 有效 YYYY-MM-DD 日期 |
| url | 完整 http:// 或 https:// 網址，不含帳密 |
| select | 字串，必須來自 options；options 為 1–50 個非空字串 |
| image | `{ "url":"https://…", "caption":"選填" }`；只參照外部圖像，不匯入二進位原圖或本機版本記錄 |
| checklist | `[{"id":"review","text":"檢查完成","done":false}]` |
| heading | 不填 value；label 是小標題 |
| flow | 不填 value；由 connections 自動列出前後步驟 |

製作狀態在 Node 上方獨立設定，不需要建立狀態欄位或保留標籤頁。舊格式的 bind:status 仍可匯入，開啟後會移至上方控制。

`bind` 只用來在自訂頁上呈現內建 content 欄位，允許 description、notes、references、prompt、result、status、type、checklist。文字內容綁定 text，status/type 綁定 select，checklist 綁定 checklist；同一 bind 只能出現一次。綁定時不填 value，實際值放在 Node 的 content。

status/type 的 select 仍需提供 options 字串陣列以符合 schema，例如 status 使用 `["not_started","in_progress","waiting","completed"]`。匯入會轉成系統的固定值與中文選項。不可自訂其他狀態或類型。

內建欄位的輪次歸屬依產品規則處理：description、references、notes、result、status、checklist 在重複流程中每輪獨立；type 與 prompt 共用。不要使用 bind 來改變此規則。自訂欄位才由 scope 決定歸屬。

## 連線 connections

```json
{"id":"audience-to-film","from":"audience","to":"select-film"}
```

引用已存在的 Node ID；表示工作順序，不阻擋使用者操作。不允許自我連線或相同方向的重複連線。畫面不顯示箭頭：來源 Node 統一由右側或下方輸出，終點 Node 統一由左側或上方輸入；系統依位置與障礙自動選擇接法。方向仍由 source 與 target 決定，不會因檢視轉向或自動接法而反轉。需要返回前一步時可以形成迭代回圈，並不代表輪次。不要新增 blocker、condition 等未支援欄位。

## 局部重複流程 repeatFlows

```json
{
  "id":"weekly-content",
  "name":"每期電影穿搭",
  "nodeIds":["select-film","outfit","publish"],
  "rounds":[{"id":"issue-1","name":"第一期：花樣年華"},{"id":"issue-2","name":"第二期：待選電影"}],
  "activeRoundId":"issue-1"
}
```

同一 Node 最多屬於一組重複流程。nodeIds 與 rounds 不可為空。rounds 按建立順序排列，**舊到新**；介面展示時會新到舊。activeRoundId 可省略，預設第一輪。

Node 的初始 content 與 scope=run 的自訂值存於**第一輪**。後面的輪次採空白內容、未開始狀態；檢查清單保留項目名稱但全部未完成。scope=shared 的自訂值、type、prompt 仍共用。選擇第二輪為 activeRoundId 時，打開看到的是第二輪空白值，第一輪初始值仍保留。

v3 不接受每輪個別內容資料或歷史版本匯入；要有不同初始內容，先匯入後在產品中逐輪編輯。

例：受眾分析只做一次，不放入 repeatFlows；選電影→穿搭→發布重複，才加入同一組。APP 開發中的修改與測試迭代通常用一般節點與回圈連線即可，不必把整個 APP 當成每輪重建的內容流程。

## 限制與檢查

- JSON 檔案／文字最多 2 MB；編譯後含輪次資料最多 8 MB，仍受瀏覽器儲存容量限制。
- 最多 720 個 Node（仍需符合格子占用）、40 個階段、1,000 條連線、40 組局部流程。
- 每個 Node 最多 12 個自訂 tab，每頁 30 個 field；整份 Node 欄位最多 1,000 個（包含預設頁），系統補入的狀態除外。
- 每個清單最多 100 項、每組重複流程最多 50 輪、workspace 最多 20 個標籤。
- 目前不匯入背景圖、原圖檔案、GIF 檔案、本機圖像資產 ID、圖片歷史版本、子地圖、多人權限、程式碼或自動化執行指令。image 欄位可接受完整 HTTP(S) 圖像網址；打開 Node 時瀏覽器會向該來源請求圖片。
- Schema 驗證只解決結構；還要檢查：ID 唯一、有效引用、位置邊界與重疊、選單值、日期、bind 對應、流程成員和輪次引用。
- 所有文字作為純文字；不要放需要執行的 HTML、JavaScript 或 CSS。不要把登入憑證、API key 等敏感值當成範例資料。

## 給 AI 的最後輸出要求

請依使用者的專案目標，產生一份完整且能通過本規格的 JSON。若使用者尚未指定專案，先詢問要建立什麼工作空間。不要把本文件的範例當成使用者自己的需求。不要逐格操作 UI，不要輸出網站內部儲存狀態，不要聲稱已自動匯入。最後僅輸出 JSON 或交付 JSON 檔案，讓使用者能一次貼上並預覽建立。

## 每個 Node 都要依任務設計版面

生成工作空間時，請為每個 Node 明確提供 `tabs`，不要一律省略而套用五個預設頁。先判斷任務需要輸入、執行紀錄、判斷依據與交付成果哪些資料，再選擇對應的欄位。简单任務可以只有一頁；複雜任務再分頁，避免空白頁與不必要的表單。

尺寸依「需要在地圖上閱讀的資訊」與任務複雜性安排：1×1 適合確認／發布等短步驟；2×2 適合單一產出；3×3 適合分析、比較與多項檢查；4×4 適合主企劃或需要較多資訊的核心任務。複雜但地圖上只需要短標題的任務仍可用小 Node，把完整內容放在編輯區。尺寸不代表優先級，也不會限制編輯區容量。不得為了變大而重疊其他 Node。

以下為不同 Node 的版面範例（片段需放入完整 JSON；每個 Node 必須另填 id/title/x/y/size）：

- 受眾分析（size:3）：`研究`頁含「工作說明」text/bind:description、「受眾假設」text、「訪談來源」url；`結論`頁含「核心洞察」text/bind:result、「是否已驗證」checkbox。
- 穿搭組合（size:3）：`搭配`頁含「造型概念」text、「服裝參考」image、「色彩方向」select/options、「單品清單」checklist；`拍攝交付`頁含「鏡頭與構圖」text、「成品連結」url。共同造型規範使用 scope:shared，本期搭配使用 scope:run。
- 貼文發布（size:1）：只建 `發布`頁，含「文案」text、「發布檢查」checklist、「發布連結」url、「發布日期」date。地圖只显示短標題與狀態，編輯區仍保存全部資料。
- APP 技術決策（size:2）：`比較`頁含「問題與限制」text/bind:description、「候選方案」text、「決策依據」text；`決定`頁含「採用方案」text/bind:result、「後續驗證」checklist。不要硬加入電影、穿搭或每期發布的欄位。

每個 Node 的欄位 ID 在自己所有頁面內唯一；不同 Node 可重用 ID。頁面與欄位陣列的順序就是顯示順序。請主動放入狀態欄位，以免系統補入。只有需要出現在卡片上的內建說明或類型才添加對應 bind；不必把所有內建欄位填滿。圖片欄位使用真實可存取網址或先留空，不捏造資源。文字、核取方塊、清單等欄位可放在同一頁，或按工作目的拆成多頁。

### 生成前自檢

逐個檢查：這個 Node 要做什麼、需要記錄什麼、完成時交付什麼；頁名與欄位是否符合這個任務；是否有不用填的多餘欄位；尺寸與排列是否易讀；所有佔用格是否在 60×12 之內。完成後用 workspace-v3.schema.json 與上述跨欄位規則驗證整份 JSON。

附件欄位可使用 `type: "attachment"`，例如 `{ "id":"deliverables", "label":"交付檔案", "type":"attachment", "scope":"run", "value":[] }`。AI只建立欄位；value省略或空陣列，由使用者在MAT-上傳原檔。不得編造asset ID、上傳成功、雲端確認或把binary塞入交換JSON。完整備份是另一份含原檔/hash的格式。