GrowthMap

GrowthMap HUMAN 成長圖譜白皮書

讀者： GrowthMap 使用者、專案負責人與負責審核 Agent 工作的人員

文件定位： 人類圖形介面、資料管理、AI 與協作指南

版本邊界： 本文依現行 GrowthMap 程式碼與既有功能契約撰寫。封裝桌面版若有少量文字或排列差異，請以實際畫面為準。

1. GrowthMap 是什麼

GrowthMap 是一套以「成長中的知識圖譜」為核心的專案規劃工具。它不只畫出分類，而會保存節點的正式欄位、內容區塊、主線、平行方案、非樹狀關係、操作歷史，以及人類與外部 AI Agent 的協作證據。

它適合軟體與產品開發、商業計畫、研究與寫作、個人成長、長期目標、多方案比較，以及人類與 AI 的結構化協作。每一項想法、任務、決策、問題和風險都能有清楚的位置、脈絡與狀態。

1.1 六個核心概念

  1. 專案 Project：最高層資料容器；每個專案有自己的根節點、圖譜、方案線、關係與歷史。
  2. 節點 Node：基本工作單位；一個節點宜只表達一項任務、決策、問題、風險或主題。類型包括 idea、concept、task、question、decision、risk、resource、note、module。
  3. 父子樹與主線 Mainline：父子關係表示拆解；同一父節點可有多個子節點，其中一個可標為主線，代表目前優先閱讀與執行的路徑，不會刪除其他方向。
  4. 內容區塊 Content Block：可重複新增和排序的筆記、規格、決策、待辦及風險卡片。它與摘要、描述、規則等正式欄位分開保存，不會自動互相搬移或改寫。
  5. 方案線 Scenario：從既有節點開出的平行方案，用於探索替代方向而不直接改動主線；成熟後可比較並合併，或封存。
  6. 關係 Relation：補充樹狀隸屬以外的影響，例如 depends_on、supports、contradicts、references、blocks、relates_to。

2. 第一次開始使用

2.1 選擇介面語言

用頂端語言選單切換「繁體中文」「簡體中文」或「英文」。這只改變介面文字，不會翻譯專案內容。

2.2 確認授權狀態

頂端會顯示目前狀態：

  • 付費／已啟用：可依 License 權限編輯。
  • 免費：顯示目前使用中的專案數量。
  • 唯讀：可檢視、搜尋、匯出及備份，但不能建立或修改資料。
  • 檢查中：後端尚未回報權威狀態，修改控制暫時關閉。

2.3 建立第一個專案

  1. 點擊「新增專案」。
  2. 填寫「專案名稱」。
  3. 視需要填寫「專案描述」。
  4. 按「建立」；也可按 Enter 送出。

名稱不可只含空白。宜使用可辨識名稱，如「GrowthMap 官方使用白皮書」或「2026 年產品上市計畫」，避免「新專案」「其他」等模糊名稱。

3. 主畫面導覽

3.1 頂端工具列

由左至右主要包括：GrowthMap 標誌、語言選擇、專案選擇、方案線選擇、授權狀態、「新增專案」、「設定」、「搜尋節點」、桌面版「資料庫工作區」及「鍵盤快捷鍵」。

3.2 中央圖譜

節點卡片可顯示類型圖示、標題、摘要、成熟度顏色、子節點數量、MAIN 主線標記；方案線使用紫色虛線外觀。

  • 單擊節點：選取並開啟右側面板。
  • 單擊空白：取消選取。
  • 雙擊節點：進入或退出聚焦模式。
  • 圖面控制器：縮放、置中、適應畫面。
  • MiniMap：在大型專案中快速定位。

3.3 聚焦模式

雙擊節點後會顯示該節點、其祖先、最多三層後代及同層兄弟節點，適合降低大型圖譜的視覺干擾。按「退出聚焦」或再次雙擊即可離開。

4. 專案管理

4.1 切換、封存與恢復

從「選擇專案」選取目標；封存專案前方會有封存圖示。切換時等待同步完成，不要在同步中快速重複切換或編輯。

在「設定」使用：

  • 封存專案：保留資料及讀取、匯出能力，但退出日常活動清單。
  • 恢復專案：把封存專案恢復為 active。

封存不是刪除，適合完成、暫停或暫時不需要的專案。

4.2 匯出與匯入

「設定」提供：

  • 匯出規格：{專案名稱}_spec.md，偏向結構化執行規格。
  • 匯出 Markdown：{專案名稱}.md，適合閱讀、分享或發布。
  • 匯出 JSON：{專案名稱}.json，保留機器可讀結構，適合交換或專案級備份。

匯入 JSON：選「設定 → 匯入 JSON」，選擇 GrowthMap JSON，等待成功訊息與清單刷新。這是專案資料匯入；「匯入既有 DB」會替換整個工作區，風險完全不同。

5. 建立與管理節點

5.1 新增子節點

選取父節點，在右側「內容 → 內容工具」選擇類型、輸入標題，再按 + 或 Enter。新節點加入目前路徑；這不等於開新方案線。

5.2 移動、主線與刪除

  • 移動：在樹狀模式連接節點等於重新指定父節點；來源及其後代會移至目標父節點下，操作前確認方向。
  • 設為主線：在「方案工具」的子節點清單對非主線子節點按「設為主線」。它只標示優先路徑，不刪除其他子節點。
  • 刪除：用右側垃圾桶或 Delete／Backspace，並確認提示。刪除前檢查子樹、外部關係、內容區塊、是否宜改用方案線或保留，以及是否已有備份。

5.3 右側面板

四個頁籤：

  • 內容：正式資料、內容區塊、文件、子節點與方案。
  • AI：展開或深化節點。
  • 對話：用目前節點脈絡與 AI 討論。
  • 歷史：操作歷史與 Agent 實作回報。

底部「編輯」進入正式欄位與區塊編輯；「儲存」保存標題、摘要及正式欄位；「取消」退出本次正式欄位編輯；垃圾桶刪除節點。內容區塊自己的「儲存」是獨立操作，不等同底部的節點「儲存」。

6. 節點欄位完整字典

6.1 標題 Title

圖上的主要名稱。一個標題只表達一件事；任務用動詞，如「完成登入流程測試」；決策明寫結論，如「採用 SQLite 作為本機資料庫」。

6.2 節點類型 Node type

建立子節點時選擇，用於圖示與語意分類，不會自動啟動工作流。可用類型見 1.1 節。

6.3 成熟度 Maturity

表示內容由想法到定稿的程度：

  • Seed／種子：剛出現、資訊少。
  • Rough／粗胚：已有輪廓，缺驗證或細節。
  • Developing／發展中：正在補充與實作。
  • Stable／穩定：可靠，可日常使用。
  • Finalized／定稿：已裁決完成，修改應更審慎。

成熟度不是任務百分比；「發展中」也不等於工作流 in_progress。

6.4 摘要 Summary

用一至三句說明這是什麼、為何重要、目前結論或下一步，讓讀者不展開全部內容也能理解。

6.5 節點狀態 Status

保存節點生命週期；現行介面為自由文字，預設 active。團隊宜約定 active、archived、blocked、deprecated 等固定值，避免混用 done、completed、finish。

6.6 工作流狀態 Workflow status

描述執行階段；現行介面為自由文字，預設 draft。建議 draft、ready、in_progress、waiting_review、completed。節點狀態偏生命週期，工作流狀態偏執行階段。

6.7 優先級 Priority

以數字表示相對優先順序，預設 0，介面不強制範圍。可統一為 0 未排序、1 最高、2 高、3 一般、4 低。

6.8 信心值 Confidence

判斷或內容可信程度，範圍 0–1、步長 0.01、預設 0.5。例如 0.20 多為猜測、0.50 有部分證據、0.80 大致可靠、1.00 僅用於明確可驗證內容。

6.9 Description

完整背景與目的，回答「這個節點在處理什麼問題」。

6.10 Rules

必須遵守的規則與不變條件，例如「所有資料寫入都必須留下操作歷史」。

6.11 Constraints

外部、技術、時間、預算或權限限制，例如「只支援 Windows 本機磁碟」。

6.12 Examples

正例、反例、輸入輸出範例或具體使用案例。

6.13 Questions / acceptance

待回答問題或可驗證驗收條件，例如「安裝後能否讀取既有專案？」。

6.14 Decision notes

記錄最終決策、理由、替代方案，以及未採用其他方向的原因。

6.15 檔案路徑 File paths

每行一筆相關檔案位置。它只保存文字，不代表 GrowthMap 或 Agent 自動取得檔案讀寫權。

7. 內容區塊與綁定文件

7.1 內容區塊

支援筆記 note、規格 spec、決策 decision、待辦 todo、風險 risk。

新增時進入節點編輯模式，選區塊類型，填「區塊標題（選填）」及內容，按「新增內容區塊」；標題和內容至少填一項。修改後按該區塊「儲存」；用 ↑、↓ 排序；按「刪除」移除。區塊刪除會提示不可復原，不要只依賴全域復原。

7.2 綁定文件

「已綁定文件」只保存引用，不會自動複製文件內容。

  • 文件標題：顯示名稱。
  • URL／路徑：網址或路徑文字。
  • 文件摘要（選填）：用途或內容說明。

標題和 URL 至少填一項。建立後可按「開啟」；編輯模式可「移除」。綁定路徑不等於授予 Agent 權限，也不保證另一台裝置可開啟同一路徑。

8. 方案線完整流程

當方案尚未確定、要保護主線、比較架構／策略，或讓 Agent 探索但暫不寫入正式方向時使用方案線；普通擴充請新增子節點。

  1. 選取已有子節點的來源節點。
  2. 在「方案工具」按「開新方案線」。
  3. 填必填名稱及選填描述。
  4. 從頂端 🌿 main 旁的方案選單切換。

介面會顯示「方案線模式」。要合併時按「檢視並合併」，比較來源主線與方案根節點的標題、摘要、成熟度及節點／區塊數量，選「合併到主線節點」，再按「確認合併」。合併會結束方案線並把完整方案子樹接到指定主線節點下，不是逐欄位覆寫來源。

主線不能封存。切到方案線後，可在設定的危險操作區封存目前方案；「方案線歷史」顯示操作與時間。

9. 搜尋、熱力圖與關係圖

9.1 搜尋

在頂端輸入節點名稱；圖上標記匹配項，下拉最多十筆。點結果選取，Enter 跳第一筆，Esc 清除。

9.2 熱力圖

依最後更新時間著色：綠色少於 1 天、黃色 1–3 天、橘色 3–7 天、紅色超過 7 天、紫色從未更新。它用於發現久未維護區域，不代表品質或緊急度。

9.3 樹狀與圖譜模式

  • 樹狀模式：連線會重新指定父節點。
  • 圖譜模式：連線只建立非樹狀關係，不改父子結構。

拖線前務必確認模式。建立關係時切到「圖譜模式」、選類型、由來源連到目標，再在左下關係面板檢查及調整權重和備註。方向例如：「發布正式版本」 depends_on 「完成 Windows 驗收」。

9.4 關係篩選欄位

  • 搜尋節點：按標題縮小範圍。
  • 關係範圍：全部、1 跳、2 跳。
  • 方向：雙向、上游、下游。
  • 最低權重：只顯示達門檻關係。
  • 顯示關係：勾選類型。
  • 權重：0–1，步長 0.05。
  • 關係依據／備註：記錄理由。

10. AI 功能與 LLM Provider

10.1 建立 Provider

開啟「設定 → LLM 設定」。建立設定檔後，AI 頁籤才有可選 Provider。Mock 不呼叫外部 API；真實模型的展開、深化與對話可能消耗第三方 API 額度。

10.2 展開、深化與對話

  • 展開分支：由目前節點產生多個子節點建議。模式有「聚焦主線」「探索延伸」「挑戰假設」，並可填「給 AI 的指示」。逐項「採用」或「忽略」，也可「全部採用」；建議逐項審閱。
  • 深化內容：補充摘要和內容區塊。可只套用摘要、個別接受或忽略區塊、或全部接受；選擇後才正式寫入。
  • 對話：祖先路徑作為脈絡；輸入後按 Enter 或「發送」。切換節點會重設畫面聊天；回答不會自動成為正式資料，重要結論應人工整理到欄位或區塊。

AI 最長等待約 62 秒，介面不顯示虛假百分比。請求期間若設定檔改變須重送；錯誤時保留 Request ID。修改模型名稱後要先按「儲存模型」。

10.3 Provider 欄位字典

  • 已儲存 Provider：選既有設定檔或「建立新的 Provider」；圓點表示啟用狀態。
  • 顯示名稱：人類辨識名稱，必填。
  • Provider：OpenAI、Anthropic、Google Gemini、OpenClaw、Custom、OpenAI-compatible、Mock（Demo）。
  • Base URL：API 基礎網址；Mock 可留空，自架或相容服務須填正確路徑。
  • API key 的環境變數名稱：憑證語意名稱，預設 GROWTHMAP_LLM_KEY_DEFAULT。
  • API Key：真實模型需要；編輯既有 Provider 時留空代表保留現有 key。桌面版使用作業系統安全儲存，不把密鑰放入畫面、localStorage 或 SQLite；安全儲存不可用時拒絕保存。
  • 模型：模型名稱；留空可使用 Provider 預設值。
  • 新增：清空表單以建立新 Provider。
  • 儲存並使用：依序儲存 metadata、安全保存憑證、設為目前選用、重新讀取權威設定。部分步驟失敗會明示，不會假裝全成功。
  • 憑證復原：更新中斷時可重新輸入並完成，或重試移除。

11. 操作歷史、復原與快捷鍵

在「歷史」按「查看操作歷史」，可看到建立／編輯節點、建立專案、成熟度提升、AI 展開／深化、操作者類型與時間。底部另有節點 ID 縮寫、建立／更新時間及 Agent 實作追蹤（如有 readback）。歷史是稽核資料，不是任意時間點完整還原。

快捷鍵：Esc 取消選取或關閉部分浮層；Delete／Backspace 刪除並確認；Ctrl+Z／Cmd+Z 復原可復原操作；介面列出 E 為 AI 展開、D 為 AI 深化。內容區塊刪除、DB 還原等高風險操作不可只依賴復原。

12. 資料庫工作區與備份

桌面版頂端「DB」顯示目前 DB 完整路徑、專案數、大小、SHA-256 摘要前綴及最近備份時間。

  • 選擇既有工作區：切換另一個 GrowthMap 工作區，成功後應用程式重啟。
  • 立即備份：建立 GrowthMap 管理的備份；大型修改、匯入、合併或升級前使用。
  • 匯入既有 DB：先備份，再用選取 DB 取代整個目前工作區，不是附加單一專案。
  • 開啟備份資料夾：在作業系統顯示備份位置。
  • 還原：從指定備份還原；系統先備份目前資料，期間不要關閉程式。

工作區必須位於 Windows 本機磁碟。為保護 SQLite，不支援 WSL 檔案系統、UNC、網路磁碟或雲端同步資料夾。WSL 中的 Agent 應使用 Agent Port／API，不可直接開 SQLite。

必備份的時機：匯入 JSON／DB、還原、大量重組、方案合併、長時間直接協作、應用程式升級前，以及重要里程碑後。建議同時保留受管理 DB 備份、重要專案 JSON、可閱讀 Markdown／規格；GrowthMap 不取代 Git、異地備份或正式災難復原。

13. 人類如何管理 Agent 協作

13.1 先分清兩項功能

Agent 工作階段是人工追蹤與審核面板，記錄委派目標、範圍、模式、進度、待審產物與結案摘要；它不會自動啟動外部 Agent 或呼叫 LLM。

Agent Access／Agent Port是讓外部 MCP 相容 Agent 經 localhost 圖譜 API 讀取或有限修改 GrowthMap 的連接層。它不授予檔案系統、Git repository、shell、Provider 憑證、部署或付款權限。

13.2 啟用 Agent Access

在桌面版「設定 → Agent Access／Agent Port」：

  1. 選存取模式。
  2. 選有效期限。
  3. 啟用並等待後端顯示 enabled。
  4. 複製或下載通用 MCP 設定。
  5. 將 MCP server 加入外部 Agent 客戶端。
  6. 執行連線測試。

同一工作區同時只有一個有效 workspace master grant；切換 GrowthMap 專案不需重建授權。使用應用程式產生的設定，不要猜路徑，也不要把憑證貼到聊天或一般設定檔。

13.3 三種模式

  • 唯讀 Read only：可列出／讀取專案、圖譜及節點脈絡，不能提案或直接寫入；適合分析、稽核、搜尋。
  • 先審閱 Review first：可讀取並提交待審提案，人類核准後才寫入；適合新 Agent、高風險專案與嚴格審查，是一般推薦起點。
  • 直接協作 Direct collaboration：在授權範圍內直接套用有限、具型別、原子的建立／更新節點、關係、內容區塊與方案線操作。它不包含任意改寫、刪除、DB 操作、shell 或授權變更。

13.4 有效期限、撤銷與輪替

可選「工作階段期間」「24 小時」「7 天」「30 天」「直到手動停用」。工作階段期間仍有有限期限；只有「直到手動停用」是持續授權。完成後停用不需要的存取；懷疑外洩時用「重新產生」原子輪替。

13.5 審閱、進度與 readback

在先審閱模式，逐項檢查 Agent 提案的目的、目標節點、預期變更、關係方向及是否超出範圍；核准後才生效，拒絕不修改正式圖譜。直接協作也應使用短期限、小批次，完成後在人類介面的歷史重新檢查。

Agent 可回報開始、進度、阻塞、完成或失敗事件。readback 是外部工作證據，可包含摘要、commit、檔案、測試、決策、風險、待辦與證據；它只記錄結果，不會替 Agent 執行 repository 工作，也不等於修改正式圖譜。

13.6 Agent 工作階段面板欄位

  • 工作目標：可驗收交付成果，而非模糊指令。
  • 範圍：節點或方案線根節點。
  • 目標：實際負責節點／方案根。
  • 工作模式：「一次性」「協作」「背景追蹤」；只是追蹤標籤，不改外部執行環境。
  • Provider（選填）：記錄預期 Provider，不會自動呼叫。
  • 工作階段狀態：「待開始」「進行中」「待審核」「已完成」「已取消」。
  • 結果／結案摘要：完成結果、剩餘問題或取消原因。
  • 產物提案：GUI 可提出待核准子節點標題；核准才寫入，退回只保留審核結果。

14. 人類與 Agent 協作範例

情境 A：只分析

人類建好目標，啟用「唯讀」；Agent 讀取專案與脈絡後在外部提供分析或 readback；人類自行決定是否修改。

情境 B：提案後核准

啟用「先審閱」；Agent 讀取最新狀態並提交有理由的提案；人類逐項核對後核准或拒絕。這是新 Agent 或重要專案的推薦方式。

情境 C：可信 Agent 直接協作

先備份，啟用有限期限「直接協作」；要求 Agent 小批次工作並回報里程碑；完成後查看 readback 與歷史，再停用或輪替授權。

完整例：登入功能測試計畫

  1. 人類建立「登入功能」節點，在 Rules、Constraints、Questions / acceptance 填妥安全規則、平台與驗收條件。
  2. 建立 DB 備份，啟用 24 小時「先審閱」。
  3. Agent 提案建立「正常登入測試」「過期 session 測試」任務、「暴力嘗試限制」風險與測試規格區塊。
  4. 人類檢查並核准。
  5. Agent 若在外部 repository 完成測試，以 readback 回報真實 commit、檔案、測試結果、風險與待辦。
  6. 人類在節點「歷史」核對證據，更新成熟度與工作流狀態，最後停用 Agent Access。

15. 安全原則與常見問題

安全原則

AI 建議須由人類審閱；不在聊天中分享 token／API key；綁定路徑和 file_paths 都不授權檔案存取；Agent Access 僅限本機圖譜 API。即使直接協作，Agent Port 也不提供刪除、DB 匯入／還原、破壞性合併／封存、授權變更、檔案／repository／shell、Provider key、付款或部署。授權到期或撤銷後應關閉存取。

FAQ

為何不能編輯／新增專案按鈕灰色？ 檢查授權；唯讀或檢查中會關閉修改。 為何 AI 按鈕不可用？ 可能無已啟用 Provider、Provider 不存在／停用、憑證未完成、模型未儲存或請求仍進行。 AI 錯誤怎麼辦？ 保留代碼與 Request ID，檢查 Provider、Base URL、模型和 API Key。 換節點後對話消失？ 畫面對話隨節點重設；重要結論請寫入正式資料。 內容區塊排序後載入失敗？ 若提示已儲存，先重新整理，不要立即重複搬動。 方案合併後如何？ 完整方案子樹接到指定主線節點，不逐欄位覆寫來源。 Agent 看不到 GUI 當前專案？ 刻意如此；外部 Agent 必須明確選擇專案。 Agent 寫入衝突？ 表示資料已更新；Agent 應重新讀取並重建變更，不應覆蓋新資料。 MCP 設定為何沒有 token？ 桌面版使用本機 discovery 與作業系統安全憑證儲存。 WSL Agent 可直接開 SQLite？ 不可；使用 Agent Port／API。

16. 功能與版本邊界

本文涵蓋現行 GUI 的專案、節點樹與主線、聚焦與搜尋、正式欄位、內容區塊、文件引用、方案線、關係圖、熱力圖、AI 展開／深化／對話、Provider 管理、三種匯出與 JSON 匯入、桌面 DB 工作區／備份／還原、人工 Agent 工作階段、Agent Access、歷史及 readback。

原始碼倉庫可能另有 thin CLI 與 MCP source adapter；不可把它們描述為所有桌面安裝必然附帶。桌面正式路徑以封裝的 growthmap-mcp.exe 及應用程式產生的通用設定為準。

GrowthMap 不會自動啟動外部 Agent、不因路徑引用授予檔案權、不因 Agent Access 授予 shell／repository 權、不自動把 AI 對話寫入正式資料、不保證 AI 正確，也不自動付款或部署。

17. 快速上手與填寫模板

  1. 建專案與第一層節點；指定主線。
  2. 為重要節點填摘要、規則、限制、驗收。
  3. 用內容區塊補規格與風險。
  4. 不確定方向用方案線；依賴和阻塞用關係圖。
  5. 設 Provider 後使用 AI，逐項審閱。
  6. 大型修改前備份。
  7. 初次 Agent 合作使用唯讀或先審閱；完成後檢查歷史／readback 並停用存取。
標題：
節點類型：
成熟度：Seed
摘要：

Description：
Rules：
Constraints：
Examples：
Questions / acceptance：
Decision notes：

節點狀態：active
工作流狀態：draft
優先級：0
信心值：0.50
檔案路徑：

18. 給外部 LLM 的獨立指南

本白皮書是給人類使用者的完整指南。若要讓外部 LLM／Agent 連接 GrowthMap，請另外開啟 [Agent／LLM 操作指南](/zh-TW/whitepaper/agent)，並把那份獨立指南提供給外部 LLM；其中包含 Agent 應遵守的實際連線、工具與安全規範，不應以本篇人類 GUI 教學代替。

Personal v1 live 協作邊界

Agent Access 是 Windows 使用者、workspace-global 的 master grant；每次操作仍必須有明確 project_id 與 scoped intent。建議 review-first；Direct collaboration 必須明確授權。shared canonical revisions 與 CAS 會拒絕 stale write；SSE journal 只提示可能 stale state，不是 mutation truth 或 cloud DB。Windows 安裝程式未簽章且更新採手動覆蓋；請核對 release evidence 並備份。project SQLite 留在本機；activation 只處理授權相關資料，不接收 project DB。