zago help zh tw
zago 是一套讓工作流程可以與 CLI AI Agent 輕鬆整合，因此設計的終端機 Markdown 編輯工作站。
理想中使用 zago 的方式是，當你開了一個 AI Agent 的終端機視窗之後，在旁邊用 zago 編輯相關的 Markdown 檔案，讓多個終端機視窗組合出一個專注的工作區，而不用再去開啟額外的軟體。
在使用 AI Agent 開發軟體或是其他工作的時候，我們不見得會打開 IDE 或是 Coding Editor，而是在終端機中讓 AI 撰寫程式。但，在終端機之外，我們往往還是得打開編輯器，查看或修改各種指示 AI 的 Markdown 檔案，像是 AGENT.md，或是專案中的其他架構設計、開發進度文件。這種給 AI 閱讀的 Markdown 其實並沒有 render 成 HTML 的需求，但各種 Markdown 編輯器都假設應該要有 HTML 預覽，所以用上了不怎麼必要的瀏覽器元件。
除了文字指示，AI Agent 又常常會仰賴用文字組成的圖表，大部分編輯器並不擅長編輯這類圖表，所以又往往需要打開 AsciiFlow、MonoDraw 等專門用來繪製文字圖表的網站或軟體，讓人更加分心—而中文使用者/開發者還有一個更大的問題，就是這些西方文字圖表軟體在製圖時，只要遇到中文，就會整個跑版。
zago 的最大目的，就是可以讓您不用離開終端機，而且加裝一套工具不造成負擔—編譯後的大小只有幾 MB。zago 本質上是一個輕量的 Markdown 編輯器，整合了用鍵盤輕鬆繪製框線的畫布模式，還有用簡單命令就可以打出方塊與框線的繪圖命令—而且不會跑版。
# 編輯指定檔案
zago AGENTS.md
# 也可以是目錄
zago .
# 直接開新檔
zago- 進入軟體後，預設處在一般模式下。您隨時可以按下
F1叫出選單，用ESC按鍵跳到命令列上。 - 這個模式就跟各種常見的編輯軟體一樣，直接打字即可。
- 請先記得：無論什麼時候，都可以用
Ctrl + Z的 Undo 功能，回到上一步。 -
F1選單中，也有重要的輔助說明。 - 您可以用
Shift 與左右鍵選擇文字，按下Ctrl+K剪下，Ctrl + U貼上，Meta (Alt) + W複製文字。Ctrl + O或Ctrl + S存檔，Ctrl + X離開。 - 除了 Markdown 之外，zago 也可以開啟各種文字檔，內建只支援少量格式的語法高亮。不過，zago 與語法高亮功能與 nano 編輯器相容，可以額外安裝 nano 的高亮語法檔案。
- 打了一些字之後，我們可以用
F8或是從F1選單上，從一般模式切換到畫布模式。在這個模式中，您可以把整個文字檔案想成是一張開展的畫布，您可以將游標移動到任何位置，甚至可以超過原本一行的限制—如果原本一行有 30 個字，也可以移動到 30 個字之後。 - 再按一次
F8可以離開畫布模式。 - 用
Meta (Alt) + V也可以切換畫布模式。 - 在畫布模式中，您可以按住
Shuft + 上下左右方向鍵，就可以畫出文字圖表用的框線。您可以在 F1 選單中，挑選目前想要使用的框線樣式。 - 如果按住
Ctrl + Shift + 上下左右方向鍵，就會畫出有箭頭的框線。在一些 Ascii 圖表中，可能會用<或>代表箭頭，其實只要直接用鍵盤輸入大於小於就好。
Tip
在 Windows Terminal 下，Ctrl + Shift 加上上下按鍵，可能會被當成 Windows Terminal 自己的快速鍵，可以在 Settings -> Actions 關閉預設的快速鍵設定
- 在畫布模式下，就沒有用
Shift + 左右選擇文字的功能，而是可以選擇方形的區塊—您可以用區塊包起一段文字圖表，去另外一個地方貼上。方法是：先用Ctrl + ^開始區塊的起點，移動游標後，去另一個地方再按一下Ctrl + ^設定終點。就可以用Ctrl + K，剪下這一段內容，然後用Ctrl + U貼上。
Tip
在 Windows Terminal 下，Ctrl + ^ 可能又被當做 Windows Terminal 的按鍵了。您可以改按 Meta + B 來設定選擇區塊。
- 按一下
ESC會移動到命令列上，我們可以簡單輸入一個命令box "Hello, zago!"。 - 我們可以看到畫面中出現一個框，裡頭是 Hello, zago!
┌──────────────┐
│ Hello, zago! │
└──────────────┘
- 命令框可以輸入很多種命令，但我們只需要記住這幾個
-
BOX: 建立一個框線組成的方塊，出現的時候會往右擠開其他內容 -
DRAWBOX: 也是建立方塊，但是這個方塊會蓋在原本的內容上 -
LINE: 畫一條橫線，後面可以指定長度，像是LINE 5，如果不加長度的話，zago 會嘗試偵測該畫的位置，自動畫到同一行中下一個文字或框線前方，用來結合圖形 -
VLINE: 畫一條直線，後面可以指定長度，像是VLINE 5，如果不加長度的話，zago 會嘗試偵測該畫的位置，自動畫到同一直行中下一個文字或框線前方，用來結合圖形
-
- 輸入命令時，大小寫均可
- 您可以嘗試先用
BOX畫一個框之後，用方向鍵、空白鍵或 tab，往右邊移動，建立下一個BOX，移動到左邊的 BOX，打一次LINE，就可以結合兩個 BOX
┌─────┐ ┌─────┐
│ BOX ├────────┤ BOX │
└─────┘ └─────┘
- 我們可以移動到一個 BOX 中，按下
Meta + T，就會進入表格模式。在表格模式下，輸入任何內容，都不會超過格子的框線。再按一次Meta + T退出。 - zago 還有很多功能，但您已經學會最重要的操作了！
在一般模式下，zago 強制啟動自動換行（soft-wrap），因為 zago 假設的行為就是用於文件寫作，而不是用來賺寫程式。
zago 有一些為了中文寫作而設計的功能
- 從 F1 選單上，可以改變每行要在多少個英文字時換行，像是 80 60、40 等，相當於 40、30、20 個中文字， 太長的中文往往閱讀困難，寫作時也容易視覺疲勞。按下 ESC 之後，也可以用
set wrap自訂換行字數。 - 從 F1 選單上，可以選擇要不要打開一個標尺列。標尺列除了可以視覺化呈現換行位置外，在畫布模式中，也可以是用來估算 LINE 命令要畫多長的工具。可以用
set ruler切換。 - 從 F1 選單上，可以決定要不要顯示子行號。子行號是一項比較特殊的設計，啟用之後，會在編輯區右方，額外顯示這一段文字當中有多少行，裡頭寫了多少字，方便作者知道一段是否寫得太長，不易讀者閱讀。
zago 提供簡繁轉換、拉丁轉日文假名等轉換功能。在使用 Shift 加上左右之後，按下 F1，Tool 選單中會出現額外的轉換功能。
在 ESC 命令列上，也有文字轉換相關命令，像是輸入
-
type tohans 繁體中文就會出「繁体中文」 -
type tohiragana sakura就會出現「さくら」
打這些指令感覺很花時間，不過，可以先打 to，按下 tab，就會自動補齊命令，然後移動到最前面打個 type 即可。
在 ESC 命令列中輸入 dir，就可以看到目前所在目錄的檔案列表。在檔案上按下 Enter 變可以開啟檔案。
zago 支援同時開啟多個檔案。標題列右側會顯示目前的總頁數（例如 [1/3]）：
- 按
Meta + .（或Meta + >）：切換到下一個檔案。 - 按
Meta + ,（或Meta + <）：切換到上一個檔案。 - 按
Ctrl + N：開啟一個新的空白頁。 - 在
ESC命令列上輸入buffer next、buffer prev或buffer 2亦可切換指定頁面。
編輯 Markdown、Org、AsciiDoc 或 reStructuredText 文件時：
- 按
Meta + \]：直接跳到下一個章節標題。 - 按
Meta + \[：直接跳到上一個章節標題。 - 按
Meta + \\：叫出完整的大綱模式選單，選擇後直接跳轉。
在 Markdown 檔案中的連結上按下 Meta + O，如果發現是本機檔案，就會嘗試跳轉到連結的檔案，開始編輯。
按下 Ctrl + T 或 F12，zago 會開啟互動式拼字檢查提示列，自動比對並標示檔案中的拼字疑慮，您可以直接選擇修正建議。在命令列設定 set spell-language en_US 亦可切換語系。
開啟文字檔案時，zago 會自動偵測 UTF-8、UTF-16、Shift-JIS (日文)、Big5 (繁體中文)、GB18030 (簡體中文) 與 ISO-8859-1 編碼，舊檔案開檔不再出現亂碼。
在畫布或繪圖模式下，按下 Meta + S 可以即時循環切換預設框線風格（圓角 ROUND DOUBLE +-|+ SINGLE）。
在 Markdown 檔案中，我們常需要插入一段 Mermaid 或是 PlantUML 圖表，雖然 Mermaid 與 PlantUML 的語法簡單，但是這種格式的開頭的一些標示，卻很難記住。如果在寫 Markdown 時，建立了一段 code block（輸入 ```），再按下 F1 叫出選單，就可以選擇一些常用的 Mermaid 與 PlantUML 範本。
您可以使用與 nano 相容的 Ctrl + / 跳到指定行，也可以直接在 ESC 命令列上輸入數字，一樣會跳到指定行。
您可以使用與 nano 相容的 Ctrl + W 與 F6 搜尋文字，也可以在 ESC 命令列上，用 / 搜尋關鍵字，像是輸入 /zago。也可以用 s/<原本的內容>/<取代的內容> 這樣的語法取代文字。在輸入了搜尋關鍵字之後，可以用 Meta + N 以及 Meta + P 按鍵，跳到前一個或下一個符合關鍵字的位置。
在 ESC 命令列輸入命令或檔名時，按下 Tab 鍵可以自動補齊指令名稱或檔案路徑。
zago 提供整份檔案的字數統計功能，包括所有的字元數、拉丁字數（words）、中日韓字數、Emoiji 字數等。
在 ESC 命令列上，可以輸入一些與其他編輯器相容的命令
-
w: 存檔 -
q: 離開 -
wq、wq!: 存檔並離開 -
e: 開啟檔案
zago 的大部分按鍵都比照 nano。所以也可以用 F3 存檔，F2 離開，F4 則會完全不詢問，就直接存檔並且退出編輯中的檔案。
進入畫布模式之後，zago 會額外顯示一個「檔案結尾」的提示符號。在一般模式下，如果游標到了檔案結尾，繼續按方向鍵的下，會停在原地，在畫布模式中，則會直接增加新行，方便畫圖。如果不知道檔案結尾位置，就很容易一直往下按，然後一直增加新行。
在使用 Ctrl + ^ 或是 Meta + B 選取一個區域之後，可以在 ESC 命令列上，輸入 fill 命令，像是 flll "zago，zago 就會用輸入的文字，填滿（flood-fill）這整個範圍。FILL 命令也可以用在任何用框線構成的格子中，也可以在表格模式中使用。
除了可以在畫布模式用 Shift + 方向鍵 拉出框線，用 BOX 與 DRAWBOX 命令畫框之外，也可以在 ESC 命令列輸入 TABLE 命令，就可以在畫面中產生表格。可以在 TABLE 命令後面接要產生的格子數量，格式是 TABLE 列數 行數，像是 TABLE 3 2，如果不加行數，就是產生一行。都不加，預設會產生 3x3 的表格。
如果直接按 F7 或是 Meta + T 進入表格模式，zago 也會問是否要建立一個 3x3 的表格。
┌────────────────┬────────────────┬────────────────┐
│ │ │ │
├────────────────┼────────────────┼────────────────┤
│ │ │ │
├────────────────┼────────────────┼────────────────┤
│ │ │ │
└────────────────┴────────────────┴────────────────┘
zago 的表格模式是為了由框線組成的視覺表格（Grid Table）設計，而不是 Markdown 的那種語意表格（所謂的 Pipe Table）。Markdown 表格在呈現資料時雖然很好用，但也有其限制：
- 不能合併儲存格
- 不能畫格子之間的關係
- 處理多行資料很麻煩
為此，zago 強化了視覺表格的相關功能。
進入表格模式後：
- 上下左右按鍵移動游標，但是不會超過儲存格
- Page Up/Page Down/Home/End 都不會超過儲存格
- 可以用
Tab按鍵，跳到下一個格子 - 如果游標到了邊緣，按了上下左右方向鍵，也會嘗試移動到相鄰的格子中
- 如果按下
Ctrl + J，就會將格子中的文字置中 - 如前所述，在表格模式下，也可以使用
FILL命令填入內容。
在表格模式下
- Ctrl + Shift + 左右方向鍵，可以調整格子寬度
- Ctrl + Shift + 上下方向鍵，可以調整格子高度
至於 Shift + 左右方向鍵，則可以用來選取文字內容，用於複製貼上。
zago 也支援 Markdown 的表格編輯，像是在這段文字中：
| This | is | a | Table |
| -
| Just | another | Table | 按下 Tab，就會形成排版過的 Markdown 表格。
| This | is | a | Table |
| ---- | ------- | ----- | ----- |
| Just | another | Table | |
zago 也包含簡單的計算功能。您可以按下 ESC 進入命令列之後，直接輸入四則運算，像是 1 + 2 * 3，按下 Enter，就會在底部狀態列顯示計算結果。如果您想將運算結果送入文字區，就在前面加上 Type，像是 Type 1 + 2 * 3，就會在游標位置打出 7。
Note
在這之後都是比較進階的內容，如果您沒有進階需求，可以跳過後面的部分。
zago 支援多種基礎邊框風格，可透過關鍵字或簡短的 Style DSL 符號 指定。而圓角（round 或 )） 是一個獨立的修飾參數，可加在任何基礎風格上：
-
單線（
single/-） 與 單線圓角（round或single round/-)）：┌────────┐ ╭────────╮ │ Single │ │ Round │ └────────┘ ╰────────╯ -
粗線（
heavy/+） 與 粗線圓角（heavy round/+)）：┏━━━━━━━━┓ ┏━━━━━━━━┓ ┃ Heavy ┃ ┃ Round ┃ ┗━━━━━━━━┛ ┗━━━━━━━━┛ -
雙線（
double/=） 與 雙線圓角（double round/=)）：╔════════╗ ╭════════╮ ║ Double ║ ║ Round ║ ╚════════╝ ╰════════╯ -
虛線系列（
dashed）：支援細虛線與粗虛線（二段--/++、三段---/+++、四段----/++++），亦可加上圓角修飾（如---)）：┌┄┄┄┄┄┄┄┄┐ ╭┄┄┄┄┄┄┄┄╮ ┆ Dashed ┆ ┆ Round ┆ └┄┄┄┄┄┄┄┄┘ ╰┄┄┄┄┄┄┄┄╯ -
ASCII 純文字（
ascii/a） 與 ASCII 圓角（ascii round/a)）：+--------+ /--------\ | ASCII | | Round | +--------+ \--------/
在 LINE 與 VLINE 中，可透過名稱或 Style DSL 符號指定多種箭頭外觀：
-
帶柄細線箭頭（
stemmed/<~或~>）：─────────→ -
實心三角箭頭（
solid/<<或>>）：─────────▶ -
空心三角箭頭（
hollow/<|或|>）：─────────▷ -
微型三角箭頭（
small/<.或.>）：─────────▸ -
ASCII 純文字箭頭（
ascii/<或>）：--------->
在指令中可直接帶入寬高、風格名稱或 Style DSL 符號：
-
BOX [寬] [高] [風格]：繪製文字方框（右側文字自動往右推擠）。例如：-
BOX 20 4 ROUND（20x4 圓角方框） -
BOX "Hello" -)（包含置中文字的單線圓角框） -
BOX "Alert" +（包含文字的粗線框）
-
-
DRAWBOX [寬] [高] [風格]：覆蓋繪製方框（不推擠右側文字）。例如DRAWBOX 10 5 -)。 -
LINE [長度] [風格]：向右繪製水平線。不給長度時會自動連接至下一個物件。例如：-
LINE 15 "-~>"（長度 15、單線向右帶柄箭頭─────────→） -
LINE 15 "->"（長度 15、單線向右 ASCII 箭頭--------->） -
LINE 20 "<<=>>"（長度 20、雙向實心箭頭的雙線◀═════════▶） -
LINE 18 "<|+++|>"（長度 18、雙向空心箭頭的三段粗虛線◁┅┅┅┅┅┅┅┅▷）
-
-
VLINE [高度] [風格]：向下繪製垂直線。不給長度時自動向下連接。例如VLINE 6 "++|>"。 -
TABLE [行] [列] [欄寬] [風格]：在游標處插入純文字表格。例如TABLE 3 3 8 -)。 -
FILL "文字：在選取區或封閉格子內文字填滿（Flood Fill）。 -
GOTO 行 欄：將游標精準移動到指定行與欄。
zago 支援使用設定檔來自訂編輯器行為、預設模式、快速鍵綁定以及啟動巨集。zago 會依序讀取兩個位置的設定檔：
-
~/.zagorc：使用者全域設定檔。 -
./.zagorc：專案目錄內的區域設定檔（會覆蓋全域設定）。
您可以在終端機執行以下命令，自動在 ~/.zagorc 產生帶有詳細註解的預設範本：
zago --init或是指定安裝在專案目錄：
zago --init ./.zagorc設定檔採用類似 GNU Nano 的簡潔行導向語法：
# 編輯器選項設定
set tabsize 4
set tabstospaces
set wrap 80
set canvas-mode on
set trim-trailing-whitespace on
set lang zh_TW
set spell-language en_US
# 載入額外 Nano 語法高亮檔
include "/opt/homebrew/share/nano/*.nanorc"常見的設定項目包括：
-
set wrap <數字>：設定自動換行欄數（預設 80）。 -
set canvas-mode on/off：設定開新檔案時是否預設啟動畫布模式。 -
set trim-trailing-whitespace on/off：存檔時自動清除行尾多餘空白。 -
set lang zh_TW / en：設定介面顯示語言。 -
set spell-language en_US：設定拼字檢查預設語系。
您可以使用 bind 指令自訂快速鍵。按鍵語法支援 Nano 風格：
- Control 鍵：
^O,^K,^U,^J等 - Alt / Meta 鍵：
alt-w,alt-r,M-W,M-V等 - 功能鍵與特殊鍵：
F1～F12,Esc,Tab,Enter,Backspace,Delete
快速鍵可以綁定到全域指令或 LOGO 巨集：
# 將 Alt+W 綁定到段落重排 (justify)
bind alt-w edit.justify
# 將 Alt+B 綁定到快速繪製 30x4 的圓角方框巨集
bind alt-b macro: BOX 30 4 ROUND
# 將 Alt+H 綁定到單行 LOGO 程式碼 (跳至行首並插入 Markdown 標題記號)
bind alt-h logo: MOVE HOME TYPE "# " MOVE END您可以在 .zagorc 中定義自訂的 LOGO 變數與程序 (Procedures)，這些定義會在 zago 啟動時自動載入，供日後在命令列或快速鍵中直接呼叫：
logo-prelude
MAKE "boxWidth 30
TO MYBOX :title
BOX :boxWidth 4 ROUND
MOVE LEFT (:boxWidth - 1) MOVE UP 2
FILL :title
END
endlogo您也可以使用 logo-script 定義具名巨集區塊並綁定到快速鍵：
logo-script insert-header
BOX 40 3 ROUND
MOVE LEFT 38 MOVE UP 1
FILL "Title
endlogo
bind alt-t logo:insert-headerzago 內建了一套完整的文字排版、海龜繪圖（Turtle Graphics）與自動化命令直譯器（Editor LOGO）。您可以透過命令列互動、自訂組合巨集、遞迴排版、高階清單處理函式，甚至是與 UNIX Pipe 管線結合進行自動化文字處理。
詳細的程式設計手冊與範例，請參閱： 👉 zago programming (進階繪圖與自動化程式設計)