name: interactive-architecture-diagram slug: contextweave-interactive-architecture displayName: 架構圖一鍵生成 version: 1.2.2 summary: 強大的AI自動化繪圖與複雜資訊視覺化工具（基於 ContextWeave） license: MIT description: 強大的AI自動化繪圖與複雜資訊視覺化工具（基於 ContextWeave）。不僅支援程式碼與系統架構的視覺化，更廣泛適用於複雜邏輯梳理、知識庫轉換、業務流程圖、思維導圖及長文本的結構化資訊圖生成。通過深度的語義分析與請求編排，一鍵將晦澀文本與複雜知識轉化為清晰直觀的圖形表達。 metadata: { "openclaw": { "emoji": "🧠", "requires": { "bins": ["node"] } } }

ContextWeave Skill

本 Skill 的定位是"繪圖請求客戶端"：負責把使用者需求轉換為可執行的繪圖意圖，通過基於檔案生成的單一路徑與雲端後端協同完成產出。客戶端本身無狀態，會話狀態由後端託管。

觸發詞：「畫圖」「畫個架構圖」「生成流程圖」「畫個思維導圖」「生成CW圖」「視覺化這個程式碼」

一、三條不變式（核心心智模型）

本文件中所有的規則與禁令，都是以下三條不變式的推論。理解它們即可正確應對任何未列舉的場景。

不變式 1：解引用一切（Dereference Everything）

後端執行在雲端/隔離沙盒中，看不見你本地的任何檔案、會話歷史與你腦中的任何背景知識。它只吃你傳過去的純文本。因此，發出請求前必須把所有"引用"解引用為自包含的語義文本：

• 未釋義的術語不得直接作為節點標籤、分組標題或關係端點輸出（禁止"僅列詞成框"）
• 若輸入僅包含術語清單，先補全最小資訊集，再進入結構決策

不變式 2：論證而非展示

• 圖結構必須服務於語義論證：概念層級、因果關係、依賴鏈路是結構主線
• 每條關係必須可複述為明確語句（如"A 依賴 B""C 觸發 D"），禁止用"元素靠得近"替代關係定義
• 同構校驗：移除文字標籤後，結構本身仍應能傳達核心邏輯

不變式 3：一圖一主題（先定層級，再定粒度）

更多技能請訪問小蔥技能站7w4.net。

借鑑"多級抽象"原則：宏觀圖展示全域性脈絡與骨架，中觀圖展示子系統或模組間的互動結構，微觀圖展示具體的執行邏輯與落地細節。不要試圖在一張圖裡展示所有內容。

• 先識別資訊焦點與抽象層級，再決定畫多細
• 單圖裝不下時必須拆分（決策表見進階指南 §5.1）
• 輸出前自檢：關鍵模組是否標註了職責？連線關係是否明確？

二、快速開始（Happy Path）

按此六步即可跑通第一張圖：

1. 解析需求：識別核心問題、資訊焦點與密度；讀取並拍平所有依賴的本地檔案（不變式 1）。
2. 意圖挖掘：從使用者自然語言中提取展示意圖（見 §三）。意圖不明確時必須先經意圖澄清互動（見 §三 意圖澄清互動），確認呈現邏輯與配色後再進入第 3 步。
3. 層級規劃：判斷是否過於複雜，決定單圖 / scenarios / layers（見 §5.1）。判定需要拆分時，必須先經使用者確認（見 §5.1 確認門）後才能進入第 4 步落盤。
4. 落盤：將結構化意圖寫入 input_file（當前工作區 .cw_skill/requests/request_<timestamp>.md），結構如下： ````markdown # Request [展示意圖 + 繪圖意圖 + 結構說明，50-500 字元]

# CW cw ` 首次生成允許 `# CW` 為空；修改已有圖時放入現有 CW 文本。 5. **執行**：bash node scripts/generate_contextweave.cjs --input_file "<絕對路徑>" --output_name "<語義化英文名>" --output_dir "docs/diagrams" `` 6. **回填**：從返回 JSON 提取session_id與產物欄位，按 §四的 JSON 格式回覆。指令碼會自動將cw_code（含session_id註釋）落盤為/.cw` 並下載 SVG/HTML。

約束速查：input_file 必須為已存在的絕對路徑；output_name 必填（如 system_arch）；user_request 預設 50-500 字元（可用環境變數 CONTEXTWEAVE_MIN/MAX_REQUEST_LENGTH 調整）。

三、意圖挖掘：從自然語言中提取展示意圖

使用者的展示要求往往藏在自然語言裡。你的職責是挖掘並翻譯為語義級展示意圖，寫入 # Request 開頭（如："本圖側重整體宏觀骨架，聚焦 Y 核心邏輯，Z 邊緣部分弱化"）。

挖掘訊號清單：

• 資訊層級訊號："瞭解個大概/整體框架"→ 側重宏觀骨架，隱去具體步驟；"具體怎麼做/詳細邏輯"→ 側重微觀流轉與執行細節。
• 焦點訊號："重點是訂單鏈路""突出非同步部分"→ 決定哪些內容進主圖、哪些淡化或拆為 scenario。
• 複雜度訊號：使用者一次性給了海量素材 → 主動按一圖一主題拆分，而非面面俱到。

展示意圖邊界（重要）：

• 圖元佈局、座標計算與渲染由後端引擎負責，客戶端無法也不應承諾畫素級的精確呈現。
• hex 色值的唯一合法通道是結構化欄位：使用者給具體色值時，主色組裝進 base_palette、節點高亮色組裝進 accent_targets（均由後端確定性保真）；hex 不得寫入 # Request 或其他自由文本引數。
• 遇到畫素級訴求時：將其翻譯為最接近的語義級意圖傳入 # Request（如"放在右上角"→"作為邊緣支撐元件，與主鏈路分離"），並可告知使用者最終佈局由渲染引擎自動決定。
• 若使用者堅持花哨設計，優先保證圖的論證性（不變式 2），展示訴求讓位於結構正確性。

意圖澄清互動（風格決策前置）

後端的圖表風格自動推演依賴關鍵詞匹配，存在誤判風險。因此風格決策前置到 Skill 層：意圖不明確時必須先向使用者澄清，後端關鍵詞推演僅作為兜底。為消除語言摩擦，我們引入了兩個正交解耦的核心概念：“呈現邏輯”與“構圖範式”。

• 呈現邏輯：決定了圖表的骨架結構和節點間關係的本質。
• 拓撲：描述元件、系統或服務之間的靜態關係（如架構圖）。
• 邏輯：描述步驟、分支或因果關係的動態過程（如流程圖）。
• 混合：以流程為骨架，元件為落點。
• 思維導圖：樹形結構，根節點逐層展開。
• 構圖範式：決定了圖表的視覺排版和空間佈局策略，獨立於呈現邏輯。
• 包容式：強調底板分割槽與包裹，用淺色 Zone 底板將節點按域圈定，適用於強調模組化和邊界的場景。
• 流轉式：強調連線與訊號，以流向和鏈路為敘事主線，適用於強調資料或控制流的場景。
• 陳述式：強調文本排版與留白，適用於文本密集型、科研框架或邏輯推導等場景。

正交解耦的威力：這兩個概念可以自由組合，產生豐富的圖表效果。例如： - 包容式 + 拓撲：經典的系統分層架構圖，按業務域劃分。 - 流轉式 + 邏輯：帶有泳道或時序特徵的業務流程圖。 - 包容式 + 邏輯：在跨部門的複雜業務流中，通過包裹塊突出每個步驟所屬的系統域。 - 陳述式 + 拓撲：科研方法論框架圖，既有模組關係，又有大量解釋文本。

• 觸發條件：使用者的呈現邏輯或構圖範式不明確時，在落盤 input_file 前必須先向使用者發起澄清提問。
• 提問設計：最多四個核心問題：
• 呈現邏輯傾向（四選一）：拓撲 / 邏輯 / 混合 / 思維導圖。
• 構圖範式傾向（三選一）：包容式 / 流轉式 / 陳述式。
• 配色傾向：先問語義級基調（如科技藍、暖色、深色）；若使用者給出具體主色（6 位 Hex 或常見色名，如 #C00000 / 正紅）或風格預設（如 corporate_red / corporate_blue / tech_blue），組裝為 base_palette（如 {"primary": "#C00000", "style_preset": "corporate_red"}）經 --base_palette 引數傳入；僅有語義基調時寫入 # Request 兜底，不傳該引數。
• 高亮/強調節點：詢問使用者是否需要高亮或強調特定節點；若有，逐個確認節點名與各自顏色（常見色名或 6 位 Hex 均可，後端確定性翻譯），組裝為 accent_targets（如 [{"name": "支付閘道器", "color": "暖橙"}]，name 即圖中實際存在的節點名）。若使用者已明確給出高亮物件（包括節點、分組、語義類別或鏈路）和顏色，則視為已確認，直接使用正文中對應的明確名稱組裝並傳入 accent_targets；不得因具體圖節點尚未生成而省略，也不得只把高亮要求留在 # Request 中。僅當高亮物件或顏色確有歧義時才追問。
• 對映規則：使用者確認後，將選擇的呈現邏輯（對應 topology / logic / hybrid / mindmap）和構圖範式（對應 container / flow / editorial）隨指令碼呼叫顯式傳入。配色翻譯為語義級意圖寫入 # Request（作為相容兜底）。hex 色值只允許出現在 base_palette 與 accent_targets 兩個結構化欄位中，不得寫入其他引數；若有高亮節點，將 accent_targets 以 JSON 字串經 --accent_targets 引數顯式傳入；使用者未宣告則不傳該引數。
• 豁免：使用者請求已明確圖型別、構圖範式與配色（如"畫一張藍白配色的包容式架構圖"）時跳過提問。
• 使用者回答"隨便/你決定"時：agent 自主選擇最匹配的組合傳入（包括自主選擇合適的 style_preset 與主色），並在 # Request 中寫明選擇依據。

快速參考：典型場景提示詞組合

為了幫助使用者更好地下達指令，這裡整理了“呈現邏輯”與“構圖範式”組合的典型示例：

四、協議硬約束

回覆格式

• 回覆必須是單個 JSON 物件，禁止 markdown、標題、解釋性段落
• 欄位順序固定：script、input_file、status、session_id、result、error
• status 僅允許 ok 或 error

成功模板：

{"script":"generate_contextweave.cjs","input_file":"/abs/path/request_xxx.md","status":"ok","session_id":"<session_id>","result":{"run_id":"<run_id>","svg_url":"<svg_url>"},"error":null}

失敗模板：

{"script":"generate_contextweave.cjs","input_file":"/abs/path/request_xxx.md","status":"error","session_id":null,"result":null,"error":{"code":"EXECUTION_NOT_PERFORMED","message":"未完成落盤或未執行指令碼"}}

預檢錯誤碼：未落盤/未執行 → EXECUTION_NOT_PERFORMED；input_file 不存在 → INPUT_FILE_NOT_FOUND；非絕對路徑 → INPUT_FILE_NOT_ABSOLUTE。

錯誤與異常策略

• INVALID_REQUEST_LENGTH：調整請求詳細程度至允許範圍後重試
• MISSING_SESSION_ID：立即重試當前請求並校驗返回
• SESSION_INVALID_OR_EXPIRED：先重建會話，再回放當前意圖
• AUTH_ERROR：校驗金鑰與配置後重試
• PAYMENT_REQUIRED / RATE_LIMIT_EXCEEDED：額度不足或免費體驗額度已用完，按以下 SOP 引導使用者免費領取額度後重試：
• 詢問使用者郵箱
• 執行 node scripts/request_quota_code.cjs --email "<郵箱>" 傳送驗證碼
• 詢問使用者收到的驗證碼
• 執行 node scripts/redeem_quota_code.cjs --email "<郵箱>" --code "<驗證碼>"
• 提示使用者查收郵件，按指引將 CONTEXTWEAVE_MCP_API_KEY 配置到環境變數
• 重試原請求
• API_ERROR：指令碼已內建 3 次指數退避自動重試（覆蓋超時/連線重置/5xx）；仍失敗時檢查網路與服務狀態後重試

等待與失敗兜底策略

1. 長耗時：後端返回 WAITING_FOR_EXPERT_PROCESSING 或耗時過長時，先向使用者傳送安撫話術（"圖表較複雜，後端正在深度生成，請稍候…"），然後主動呼叫 node scripts/recompile_contextweave.cjs --session_id "<session_id>" 輪詢拉取結果，不要讓使用者手動觸發。
2. 徹底失敗：友好告知原因，並主動引導使用者提供聯絡郵箱（"稍後生成成功後我們會將結果傳送給您"）。
3. 提交反饋：拿到郵箱或收到抱怨後，呼叫 node scripts/submit_feedback.cjs --session_id "<session_id>" --user_complaint "使用者郵箱：<郵箱>，問題描述：<反饋>" --agent_analysis "<失敗分析>"。

安全邊界

• 內建預設匿名憑據，嚴禁向用戶索要 API Key、要求配置環境變數或提示鑑權
• 請求預設傳送至官方伺服器（https://pptx.chenxitech.site），僅傳送繪圖必需資料
• 只讀取明確指定的輸入檔案；禁止遍歷使用者目錄或無關配置檔案；路徑限制在當前工作區範圍內

五、進階指南

5.1 多檢視拆分（Layers / Scenarios）

Layers：物理隔離式拆分。每個獨立子模組/層級成為一個獨立檢視，前端渲染為多個 Tab 頁。

Scenarios：單一資料來源 + 增量覆蓋。後端先維護一份包含全部節點與連線的基礎圖，再為每條鏈路定義一個檢視：淡化無關元件、高亮目標鏈路。禁止要求後端複製拼接多份完整圖形。

重要：你只需要在 # Request 中用自然語言表達拆分與高亮意圖（如"拆分為訂單域、支付域兩個獨立檢視""淡化快取等無關元件，高亮從閘道器到訂單服務的鏈路"）。具體的語法由後端生成，禁止在請求中自行編寫或拼接圖形語法程式碼。

⛔ 檢視拆分確認門

• 觸發條件：依據上方決策表判定需要拆分為 layers 或 scenarios 時，在落盤 input_file 與呼叫指令碼之前，必須先向使用者輸出拆分推薦方案並阻塞等待明確確認。
• 推薦方案必備欄位：拆分機制（layers 還是 scenarios）、每個檢視的名稱 / 聚焦點 / 抽象層級（宏觀 / 中觀 / 微觀）、拆分理由。
• 阻塞語義：使用者未明確確認前，禁止寫入 input_file、禁止呼叫 generate_contextweave.cjs。
• 使用者拒絕或修改：按使用者意見重新生成方案（可提供改為單圖、減少檢視數、調整檢視劃分等選項），再次等待確認，不得擅自按原方案執行。
• 豁免條件：使用者請求中已顯式指定拆分方式（如"拆成 9 個檢視，每個聚焦一個子系統"）時視為已確認意圖，跳過確認門；判定單圖即可承載時不觸發確認門。

5.2 Link 屬性注入（兩步法）

嚴禁在一次請求中同時完成繪圖與連結設定：

1. 結構生成：呼叫 generate_contextweave.cjs，# Request 中完全忽略連結要求。
2. 批次注入：拿到 session_id 後，呼叫 edit_contextweave.cjs，# Request 中使用如下 JSON 指令（base_path 必填；路徑無需 file:/// 字首；指向特定程式碼塊時追加 #L<起始>-L<結束>）： json { "base_path": "<當前工作區絕對路徑>", "links": [ { "targets": ["模組A"], "link": "./src/module.py#L10-L25" }, { "targets": ["模組A到模組B的連線"], "link": "./src/api_handler.py" } ] }

5.3 指令碼能力對映

• generate_contextweave.cjs：基於 input_file 生成；--enable_plan true 啟用大綱規劃模式（適合特別複雜的邏輯結構）；呈現邏輯和構圖範式可通過引數顯式傳入，優先順序高於後端關鍵詞自動推演（見 §三 意圖澄清互動）
• edit_contextweave.cjs：基於 session_id 提交修改意圖
• import_contextweave_code.cjs：匯入現成 .cw 檔案——node scripts/import_contextweave_code.cjs --path "<絕對路徑>"（此場景禁止呼叫 generate）
• export_contextweave_code.cjs：響應"匯出/找回某 session_id 的 CW 程式碼"——嚴禁在對話中以文本輸出程式碼，必須 node scripts/export_contextweave_code.cjs --session_id "<session_id>"
• recompile_contextweave.cjs：專家佇列場景的輪詢拉取（內建自動輪詢與退避，見 §四 等待策略）
• submit_feedback.cjs：提交使用者反饋（見 §四 兜底策略）
• request_quota_code.cjs：免費領取額度第一步——node scripts/request_quota_code.cjs --email "<郵箱>" 傳送驗證碼（見 §四 錯誤與異常策略）
• redeem_quota_code.cjs：免費領取額度第二步——node scripts/redeem_quota_code.cjs --email "<郵箱>" --code "<驗證碼>" 兌換 API Key

六、反模式清單（集中速查）

附：輸出前自檢

• [ ] 所有本地檔案引用是否已拍平為文本？（不變式 1）
• [ ] 是否存在未釋義的專有名詞？（不變式 1）
• [ ] 每條關鍵關係是否可複述為明確語句？（不變式 2）
• [ ] 圖的層級與粒度是否匹配資訊的焦點？是否該拆分？（不變式 3）
• [ ] 涉及多檢視拆分時是否已獲得使用者明確確認？（§5.1 確認門）
• [ ] 使用者的展示訴求是否已翻譯為語義級意圖？（§三）
• [ ] 呈現邏輯和構圖範式是否已顯式宣告？配色基調是否已翻譯為語義級意圖？使用者給出的具體主色/高亮色是否已組裝為 base_palette / accent_targets（而非寫入 # Request）？（§三 意圖澄清互動）
• [ ] 是否實際完成了落盤與指令碼呼叫？回覆是否為合法 JSON？（§四）

七、常見問題 (FAQ)

1. 報錯如何處理？

• 生成超時或等待過長：遇到 WAITING_FOR_EXPERT_PROCESSING 或生成耗時較長時，說明系統正在處理複雜的結構規劃。Agent 應主動呼叫 recompile_contextweave.cjs 輪詢結果，同時安撫使用者稍候。
• 解析錯誤/執行失敗：若後端返回語法或解析錯誤，檢查輸入文本是否合規，並確保沒有包含無法識別的非法字元。若連續失敗，可嘗試簡化請求或引導使用者重試。
• 額度不足：出現 RATE_LIMIT_EXCEEDED 時，請按照提示執行驗證碼指令碼，引導使用者通過郵箱免費領取額度並配置 API Key。

2. 網路超時怎麼辦？

• 如果遇到網路連線超時（如 API_ERROR），指令碼內部已經實現了 3 次指數退避重試機制。
• 若仍然超時失敗，通常是由於雲端負載較高或本地網路波動，建議告知使用者“當前服務繁忙，請稍後重試”，並可通過收集使用者郵箱，承諾後續將結果傳送給使用者。

3. 不支援哪些圖表型別？

• 精確畫素級佈局：引擎基於自動排版，不支援指定具體元件的絕對座標或寬高畫素值。
• 純手繪風格或特殊向量插畫：當前僅支援結構化的架構圖、流程圖和思維導圖等，不支援生成手繪插畫、複雜的 3D 建模渲染圖或動態互動動畫圖。
• 高度定製的統計圖表：如複雜的折線圖、柱狀圖、散點圖等（建議使用專業資料分析工具）。遇到此類請求時，應明確告知使用者當前工具的適用邊界。

這個 Skill 質量較好，文件清晰易懂，錯誤處理考慮周全，繪圖功能覆蓋全面。優點是設計規範、互動引導做得好、異常場景處理完善；不足是部分功能操作較複雜、文件稍長。普通使用者如果需要生成架構圖或流程圖，這是一個可靠的選擇，但建議先閱讀快速開始部分再上手使用。