架構圖一鍵生成
📖 技能介紹
ContextWeave Skill
本 Skill 是 ContextWeave 的繪圖請求客戶端：把使用者需求整理成自包含的繪圖意圖，通過本地指令碼與雲端後端協同生成結果。客戶端本身無狀態，會話狀態由後端託管。
常見觸發語包括：“畫圖”“畫個架構圖”“生成流程圖”“畫個思維導圖”“生成 CW 圖”“視覺化這段程式碼”。
一、三條不變式（核心心智模型）
新手可以先記住三個通俗結論：把背景說完整、把關係說清楚、一張圖只回答一個核心問題。下面的正式規則必須完整遵守，它們也是處理未列舉場景時的推理依據。
不變式 1：解引用一切（Dereference Everything）
新手理解： 不要只告訴後端“去參考某個東西”，要先把它真正需要的內容帶進本次請求。
後端執行在雲端/隔離沙盒中，看不見你本地的任何檔案、會話歷史與你腦中的任何背景知識。它只接收本次請求中顯式提供的純文本。因此，發出請求前必須把所有“引用”解引用為自包含的語義文本：
| 懸空引用 | 解引用動作 |
|---|---|
檔案路徑（“請參考 /path/to/x”） |
必須先自行使用本地工具讀取檔案，將其核心邏輯拍平（Flatten）成純文本寫入 # Request |
| 專有名詞/縮寫（未釋義的術語） | 補全最小資訊集：角色（物件型別與責任邊界）、層級（所屬模組/抽象層）、動作（關鍵行為）、上下游關係 |
| 舊圖上下文（“基於上一張圖修改”） | 把現有 CW 文本放入 input_file 的 # CW 段隨請求提交；session_id 從上一輪返回 JSON 中提取複用，不要求使用者重複輸入。具體操作見 高階操作 |
- 未釋義的術語不得直接作為節點標籤、分組標題或關係端點輸出（禁止“僅列詞成框”）。
- 若輸入僅包含術語清單，先補全最小資訊集，再進入結構決策。
不變式 2：論證而非展示
新手理解： 圖不是把名詞擺出來，而是要用結構證明它們之間的邏輯。
- 圖結構必須服務於語義論證：概念層級、因果關係、依賴鏈路是結構主線。
- 每條關係必須可複述為明確語句（如“A 依賴 B”“C 觸發 D”），禁止用“元素靠得近”替代關係定義。
- 同構校驗：移除文字標籤後，結構本身仍應能傳達核心邏輯。
不變式 3：一圖一主題（先定層級，再定粒度）
新手理解： 先決定這張圖回答什麼，再決定需要畫多細。
借鑑“多級抽象”原則：宏觀圖展示全域性脈絡與骨架，中觀圖展示子系統或模組間的互動結構，微觀圖展示具體的執行邏輯與落地細節。不要試圖在一張圖裡展示所有內容。
- 先識別資訊焦點與抽象層級，再決定畫多細。
- 單圖裝不下時必須進入多檢視判斷，按“四、多檢視觸發與確認門”及其參考文件處理。
- 輸出前自檢：關鍵模組是否標註了職責？連線關係是否明確？
二、普通單圖：六步完成
1. 解析材料
識別核心問題、資訊焦點與需要讀取的檔案。只讀取使用者明確指定且與繪圖有關的內容，並按不變式 1 補全上下文。
2. 寫出一句話重點
例如：
展示訂單從閘道器進入訂單服務、完成庫存校驗併發起支付的主鏈路；日誌與監控只作為支撐元件弱化展示。
3. 確定呈現方式與配色
使用“三、核心引數：先理解再對映”中的通俗判斷表。需求明確時直接使用使用者選擇；確有歧義時才提問。使用者說“隨便”或“你決定”時，自主選擇並繼續。
4. 寫入請求檔案
在當前工作區建立 .cw_skill/requests/request_<timestamp>.md，並使用絕對路徑：
# Request
[展示重點、繪圖意圖、必要背景、明確關係與已確認的展示要求，50-5000 字元]
# CW
```cw
首次生成允許 `# CW` 為空。修改已有圖時，將當前 CW 全文放進該程式碼塊。
### 5. 執行指令碼
```bash
node scripts/generate_contextweave.cjs --input_file "<絕對路徑>" --output_name "<語義化英文名>" --output_dir "docs/diagrams"input_file必須存在且為絕對路徑。output_name必填，例如order_payment_flow。user_request預設長度為 50-5000 字元，可由CONTEXTWEAVE_MIN_REQUEST_LENGTH/CONTEXTWEAVE_MAX_REQUEST_LENGTH調整。- 已確定的呈現邏輯、構圖範式和精確配色必須按第三節顯式傳參。
- 指令碼會儲存
<output_name>.cw，並下載 SVG/HTML 產物。
6. 按固定格式回覆
最終回覆必須是單個 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":"未完成落盤或未執行指令碼"}}三、核心引數：先理解再對映
這些術語和配色引數屬於核心能力。先按自然語言判斷，再使用表中的真實指令碼引數。
3.1 呈現邏輯：圖主要講什麼
呈現邏輯通過 --diagram_style 傳入。
| 使用者想看什麼 | 通俗解釋 | 引數 |
|---|---|---|
| 元件、系統或服務之間的關係 | 看“誰與誰相連” | --diagram_style topology |
| 步驟、分支、因果或時序 | 看“事情怎樣發生” | --diagram_style logic |
| 流程與元件歸屬同時重要 | 看“步驟發生在哪個系統” | --diagram_style hybrid |
| 從中心主題逐層展開 | 看“知識怎樣分支” | --diagram_style mindmap |
3.2 構圖範式：畫面怎樣組織
構圖範式通過 --morphology 傳入。
| 使用者希望怎樣呈現 | 通俗解釋 | 引數 |
|---|---|---|
| 用區域和底板強調邊界 | 強調模組歸屬 | --morphology container |
| 用連線和方向強調訊號 | 強調資料或控制流 | --morphology flow |
| 用排版和留白承載文字 | 強調說明與論述 | --morphology editorial |
兩組引數彼此獨立。例如：topology + container 適合分層架構，logic + flow 適合業務流程，hybrid + container 適合跨系統審批，topology + editorial 適合科研框架。
3.3 最少澄清問題
只有缺失資訊會顯著改變結果時才詢問，最多覆蓋四項：
- 想看元件關係、步驟流轉、兩者混合，還是思維導圖？
- 更強調區域分組、流向，還是文字說明？
- 希望使用什麼整體配色或主色？
- 是否需要高亮特定節點、分組、語義類別或鏈路？分別使用什麼顏色？
使用者已經明確圖型別、構圖範式和配色時跳過提問。使用者回答“你決定”時，自主選擇最匹配的組合，並在 # Request 中簡述依據。
3.4 整體配色：base_palette
- “科技藍”“暖色”“深色”等語義色調寫入
# Request。 - 使用者給出 6 位 Hex、受支援色名（紅/藍/綠/橙/紫/金及對應英文）或風格預設（
corporate_red/corporate_blue/tech_blue）時，組裝為base_palette，通過--base_palette傳入。 - Hex 色值只能出現在
base_palette或accent_targets中，不能寫入# Request或其他自由文本引數。
示例：
--base_palette '{"primary":"#C00000","style_preset":"corporate_red"}'3.5 區域性高亮：accent_targets
使用者指定高亮物件與顏色時，組裝為陣列並通過 --accent_targets 傳入：
這個技能的最新版本可以在7w4.net小蔥技能站找到。
--accent_targets '[{"name":"支付閘道器","color":"暖橙"},{"name":"訂單服務","color":"#2F6BFF"}]'name使用圖中實際應出現的節點、分組或語義物件名稱。- 使用者已明確物件和顏色時直接組裝，不能因為節點尚未生成而省略，也不能只把要求留在
# Request中。 - 只有物件或顏色確有歧義時才追問；使用者沒有高亮要求時不傳該引數。
3.6 展示意圖邊界
| 可以直接表達 | 必須翻譯或拒絕承諾 |
|---|---|
| 模組分組、層級、主次、語義色調 | 精確座標、字號、線寬、透明度、間距 |
| 通過結構化引數傳遞的主色與高亮色 | 在自由文本中散落 Hex、RGBA 或畫素值 |
把“放在右上角”翻譯成“作為邊緣支撐元件，與主鏈路分離”。圖元佈局和座標由後端決定；結構正確性優先於裝飾效果。
四、多檢視觸發與確認門
出現下列訊號時停止普通單圖流程，並讀取 多檢視與 Scenarios：
- 使用者同時要求全域性、模組和執行細節；
- 多個子系統需要獨立檢視；
- 同一套元件需要分別突出多條鏈路或狀態；
- 為了裝進單圖必須混合多個抽象層級或隱藏關鍵關係。
如果判斷需要拆分，在建立 input_file 和呼叫指令碼前，必須先向使用者給出拆分機制、檢視名稱、各檢視焦點、抽象層級和拆分理由，並阻塞等待明確確認。使用者原請求已明確指定拆分方式與檢視內容時可視為已確認。
核心入口只負責識別觸發條件和執行確認門。layers 與 scenarios 的判斷、案例、組合邊界及單一資料來源規則按需從參考文件讀取。
五、按需讀取的進階文件
| 觸發條件 | 必讀文件 |
|---|---|
| 需要拆模組、拆層級或在同一架構上切換鏈路 | 多檢視與 Scenarios |
| 修改已有圖、匯入/匯出 CW、新增檔案連結 | 高階操作 |
| 指令碼超時、報錯、等待專家處理、額度不足或提交反饋 | 異常恢復 |
只讀取當前任務相關的文件，不要預設載入全部參考資料。
六、協議與安全硬約束
- 任何繪圖意圖都必須真正落盤並執行指令碼；不能只輸出語義分析、提示詞或命令文本。
- 預設只向官方服務
https://pptx.chenxitech.site傳送繪圖必需資料。 - 只讀取使用者明確指定的輸入檔案；路徑限制在當前工作區，禁止遍歷使用者目錄或無關配置。
- 正常生成使用內建預設匿名憑據；禁止主動索要 API Key、要求使用者配置環境變數或提示鑑權。
- 遇到指令碼錯誤時讀取 異常恢復，不要憑錯誤名稱猜測恢復步驟。
七、完整反模式清單
| # | 反模式 | 違反 | 正確做法 |
|---|---|---|---|
| 1 | # Request 中出現“請參考檔案 /path/to/x” |
不變式 1 | 自行讀取檔案，拍平為純文本寫入 # Request |
| 2 | 術語未釋義直接作為節點或分組標籤 | 不變式 1 | 補全形色、層級、動作、上下游後再出圖 |
| 3 | 修改已有圖時不帶 # CW |
不變式 1 | 將現有 CW 放入 # CW 並複用 session_id |
| 4 | 用“元素靠得近”表達關係 | 不變式 2 | 使用明確、帶方向且可複述的關係 |
| 5 | 一張圖塞入所有細節 | 不變式 3 | 按受眾確定層級，複雜時進入多檢視判斷 |
| 6 | 承諾畫素級佈局或精確樣式 | §3.6 | 翻譯為語義級意圖，佈局交給後端 |
| 7 | 只輸出分析或命令而不呼叫指令碼 | §二、§六 | 落盤並實際執行對應指令碼 |
| 8 | 繪圖與 Link 注入合併為一次請求 | 高階操作 | 先生成結構，再批次注入連結 |
| 9 | 長耗時讓使用者乾等或直接拋錯 | 異常恢復 | 說明狀態並主動呼叫 recompile 輪詢 |
| 10 | 失敗後不給使用者留下反饋入口 | 異常恢復 | 說明原因，按需收集聯絡方式並提交反饋 |
| 11 | 未經確認擅自拆分多檢視 | §四 | 先給拆分方案並等待使用者確認 |
| 12 | 意圖不明確時把風格決策完全交給後端猜測 | §三 | 只補問會改變結果的選項，並顯式傳參 |
八、輸出前自檢
- [ ] 本地檔案和舊圖引用已展開為後端可理解的內容。
- [ ] 專有名詞已補充角色、層級、動作和上下游。
- [ ] 每條關鍵關係都能複述成明確語句。
- [ ] 圖只回答一個核心問題；需要拆分時已讀取參考文件並獲得確認。
- [ ]
--diagram_style與--morphology已按使用者意圖顯式設定。 - [ ] 精確主色和高亮色只通過
base_palette/accent_targets傳遞。 - [ ] 已真正落盤並執行指令碼，最終回覆是合法的單個 JSON 物件。
九、常見問題（FAQ）
1. 報錯如何處理？
- 生成超時或等待過長：遇到
WAITING_FOR_EXPERT_PROCESSING或生成耗時較長時，說明系統正在處理複雜結構。主動呼叫recompile_contextweave.cjs輪詢，同時簡短告知使用者仍在處理。 - 解析錯誤或執行失敗：檢查輸入文本、絕對路徑和請求長度。連續失敗時可簡化請求或引導重試。
- 額度不足：出現
PAYMENT_REQUIRED或RATE_LIMIT_EXCEEDED時，按 異常恢復 的驗證碼流程處理，不要提前索要憑據。
2. 網路超時怎麼辦？
API_ERROR已由指令碼執行 3 次指數退避重試。- 仍失敗通常表示雲端負載或本地網路異常。告知使用者當前服務繁忙；需要收集聯絡方式與提交反饋時，使用 異常恢復 的流程。
3. 不支援哪些圖表型別？
- 精確畫素級佈局：不支援指定元件的絕對座標、寬高、字號或間距。
- 純手繪或特殊向量插畫：不支援手繪插畫、複雜 3D 建模或動態動畫。
- 高度定製的統計圖表：複雜折線圖、柱狀圖、散點圖應使用專業資料分析工具。
遇到超出能力邊界的請求時，應直接說明限制，並在可能時建議更合適的工具型別。
🤖 AI 評測
這個 Skill 質量很好，文件寫得清晰易懂，核心規則明確。它告訴使用者怎麼把架構圖生成的需求說清楚，提供了標準的工作步驟和錯誤處理方法。優點是流程完整、引數對映直觀、異常處理到位；不足是文件較長，第一次閱讀可能需要花點時間消化。總體來說，這是一個認真設計的產品化技能，對使用者比較友好。
