undefine-org/bl-org-dossier — 可互動回覆的 .bl.org 設計檔案

.bl.org 檔案 — 可互動回覆的設計文件

一份檔案就是一個 .bl.org 檔案。它同時是原始碼、頁面、可執行的規格以及答案卷。一個小型的 Beam Lisp 伺服器（kit，位於此檔案旁）使用真實的 bl.doc.spans 分割區來渲染它，將其發佈到 tailnet 上，並將讀者的每個回答寫入對應的區塊中。無需資料庫，沒有第二份拷貝：git diff 就能顯示 Othman 說了什麼。

範例，在撰寫新檔案前請先閱讀它： ~/projects/tiny-tools/mobile-app/dossier/pocket-harness.bl.org（於 2026-10-31 從 baton.bl.org 重新命名）。 一個含有桌面端及可執行生命週期的重量級桌面範例： ~/projects/knowledger-interface-review/docs/reports/interface-review-20261031/knowledger-interface.bl.org。 其風格源頭：~/code/undefine/omega/spikes/mobile/design-review/design-review.bl.org。

循環流程

1. 先進行研究。每一個主張都要有檔案路徑、執行過的指令或引用來源作為依據。
2. 撰寫 NAME.bl.org（結構如下）。程式碼區塊不需手寫 #+RESULTS — 讓 bl doc run 來寫入。
3. 執行 bl doc run FILE.bl.org，再執行 bl doc run FILE.bl.org --check（回傳 0 表示程式碼區塊為綠色且結果為最新）。
4. 在手機寬度下檢視它，然後再下任何結論（請參閱「檢視方式」）。
5. 發佈：

   work serve NAME --http auto --cwd ~/.claude/skills/bl-org-dossier/kit \
     --env-file ~/.config/baton-dossier/service.env --ready-timeout 120 \
     -- /etc/profiles/per-user/othman/bin/bl serve serve.bl -- /abs/path/NAME.bl.org
   

   env 檔包含 DOSSIER_OWNER=（檔案擁有者的 Tailscale 登入名稱）；只有該身分才能回答（Serve 會設定 Tailscale-User-Login，已於 2026-10-31 驗證）。 DOSSIER_HANDLE=timinou 是答案在 :by 中顯示的名稱；登入名稱（電子郵件）永遠不會被寫入檔案中。 伺服器會在每次請求時重新讀取檔案：編輯 .bl.org 不需要重新啟動。 編輯 kit 的 .bl 程式碼則需要重新啟動：work restart NAME。
6. 讀取答案：

   bl run ~/.claude/skills/bl-org-dossier/kit/answers.bl -- /abs/path/NAME.bl.org
   

   答案位於區塊標題上：:answer B :at "2026-10-31 17:14" :note "…"。 根據答案採取行動，更新檔案（將決策的 :status 改為 decided，將名單標題移至 DONE），並說明變更了什麼。

結構（Othman 的品味）

以主題句開頭，以他必須決定的內容結尾。中間的部分，逐步贏得每個章節。

• #+title: 命名事物及其承諾。#+subtitle: 一句話。#+kicker: 所在位置。#+status: 誠實的狀態（提案 · 尚未建置任何內容）。
• 一句話總結 — lede + stats。兩個短段落，四個數字。
• 定義詞彙 — terms 為你將要依賴的每個名詞定義。如果像「無縫」這樣的詞語承載了請求，請將其拆解為它所隱藏的多個獨立承諾，並說明它永遠不包含什麼（honest）。
• 工作 — 每個使用時刻對應一個 job，每個工作附帶參考產品的做法和一個決策。
• 畫面 — screen 區塊，從文字繪製而成。使用真實的名稱、真實的儲存庫、來自實際環境的真實機器 — 絕不使用 lorem ipsum。
• 實際運作方式 — sequence 用於任何跨越線路的事物；graph 用於拓撲；rosetta 用於跨越多個系統的單一概念。
• 模型，可執行 — 包含 assert 的 Beam Lisp 程式碼區塊，用於固定設計的不變量。每個區塊下方印出的結果就是證明。
• 先前作品 — matrix，列出來源，第三方聲明需標明來自文件。
• 決策（decision，需顯示被否決的選項）→ 問題（ask）→ 名單（* TODO/DONE 標題，附帶 :PROPERTIES: :JOBS: :AREA: :PROTO:）。
• 文案簡短。位置和權重傳達狀態。沒有行銷形容詞。說明什麼是未經驗證的。

元件

標題屬性：:key value 或 :key "quoted value"。主體是行語言；除非另有說明，否則使用 a | b | c 行。

區塊	主體	渲染效果
lede	散文	大型襯線開場
stats	value | label | note	統計磚
terms	term | meaning	定義列表
principles	title | text	編號卡片
note / warning / honest（:title）	散文	提示框（石板色 / 陶土色 / 赭色）
rosetta	第一行 = 標題	對齊表格；手機上為卡片
matrix	第一行 = 標題；儲存格 y、~、n + 選擇性文字	點陣圖 + 圖例
job :id :title :codex :claude :decision :screen	JTBD 句子	工作卡片 + 答案
decision :id :title :status proposed|decided	- [x] chosen、- [ ] rejected，然後是理由	決策卡片 + 同意/修改/不同意
ask :id :title :options "A|B|C"	背景	問題卡片 + 選項
screen :id :title :job :caption [:theme dark]	畫面語言（如下）	手機模擬圖 + 反應；連續畫面形成可滑動的條帶
desk :id :title :job :caption [:url]	桌面語言（如下）	桌面應用程式框架 + 反應；與畫面相同的答案按鈕
sequence :title	lanes a · sub | b · sub、a -> b : label（呼叫）、a --> b : label（回覆）、a => b : label（關鍵時刻）、note a, b : text、== divider	寬螢幕為 SVG，手機上為編號步驟
graph :title	node id | label | sub | col,row | tone（you door station builder foreign）、edge a -> b | label | style（baton solid dash none；也支援 <->、--）	SVG 拓撲
schema :id :title	未縮排的 entity @icon | gloss；縮排的 attr type | note。類型：text date、-> kind（參照）、->> kind（多個）、a > b / c（狀態流）、a, b, c（列舉）	實體卡片，參照連結到 #entity-NAME，顯示實體 · 屬性 · 狀態的數量；可回答
procedure :id :title :makes	step @icon Title | who | name · kind, …（產出；第三個 · draft 表示 harness 在任務開始時草擬它）、check @icon Title | who | name, …（驗證者的建議，代理人或人員）、gate @icon Title | who | name, …（等待移交）；who 命名一個角色；其他行是散文	步驟軌道，檢查項目為虛線，閘門為菱形；可回答

一個 schema 或 procedure 區塊也是程式碼區塊可以編譯的來源：bl doc run 將檔案傳入 (BeamLisp/argv)，因此程式碼區塊可以讀取自己的區塊並將其轉換為 datom 屬性或任務（範例：team-machine/design/work/WORK.bl.org，程式碼區塊 spine、procedure）。

畫面語言，每行一個動詞：bar Title | right（< Title 加入返回按鈕）、sub、chips a* | b（* = 已選取）、 section Label | count、card tone | title | meta | body（色調 turn approve run done fail idle）、 ask、actions Primary! | Plain | Quiet? | Danger^、msg you|agent | text、tool label | detail、 diff +12 −3 | path、code text、strip tone | text | button、row label | value、banner warn|ok | text、 dest icon | title | body、note、spacer、input placeholder | ↑、tabs A* | B、 lock time | date + notif app | title | body | Action, Action（搭配 :theme dark）、 sheet Title — 其後的所有內容都位於畫面底部的底部工作表內。 card tone | title | meta | body | @check! @x @next? — 第五欄將僅圖示的操作放在卡片上 （在卡片中說明需要的內容，將操作保留為圖示；Othman 發現按鈕行難以解析）、 machine tone | @server name | role | detail | right（色調 up busy asleep you）、 search placeholder + pick @folder name* | detail | right（專案選擇器，* = 已選擇）、 listen hint（麥克風 + 波形）、heard transcript、intent @send Verb | target | text（語音）、 choices A | B* | C（多選問題，* = 已選取）、reply placeholder（附帶麥克風和發送鍵的自由文字回答）。 pick 和 machine 的側邊資訊流入文字中；卡片操作位於文字下方。

桌面語言 — 每個畫面動詞，加上桌面區域和一份文件： nav @home Accueil* | @matter Affaires（側邊欄，* = 目前位置）、crumb a › b、 head Title | tone · Status | Action! | Other?（右上角的操作欄位）、meta a | b、tabs、 col doc|rail|main（欄位；doc 繪製紙張；重複 col main 以獲得一行卡片）、 page Title、para text 搭配 {+inserted+} {-deleted-} {~proposed~} {!to verify!} ‹P-01›（來源晶片）^1（註解錨點）、 point tone | @icon kind | title | body | Option* | Option、comment 1 | who | text（與其 ^1 相同的編號）、opts A* | B。 第一個 col 之前的行會跨越整個寬度。桌面端使用 Knowledger 的 Warm Signal 調色板（深色模式為燈籠色）。

圖示：在畫面或桌面行的任何位置使用 @name 會繪製一個線條圖示 — home matter library playbook people audit settings search plus send file word check x alert clock user bot chat comment link seal eye edit version diff filter more back next down up bell wait calendar scale flag play undo lock attach grid list board split spark。對於事物的種類，優先使用圖示而非文字。

可回答的區塊：ask decision screen desk job schema procedure。每個都需要一個唯一的 :id。

純 Org 語法也可以使用：帶有 TODO 關鍵字和標籤的標題、:PROPERTIES: 抽屜（晶片）、 表格、列表、[ ]/[X] 核取方塊、=code=、*bold*、/italic/、[[url][label]]、[[#screen-ID][label]]。

可執行的程式碼區塊

#+begin_src beam-lisp :id lifecycle
(ns project.model)           ; 第一個程式碼區塊命名命名空間；所有區塊共用它
(defn advance [s e] …)
(assert (= … …))             ; 失敗的 assert 會成為結果，且 --check 會回傳 1
{:what "the last value is the printed proof"}
#+end_src

僅使用小寫 #+begin_src beam-lisp（大寫永遠不會執行）。對設計的不變量進行建模（一個寫入者、效果的順序、映射的覆蓋範圍），而不是瑣碎的細節。

撰寫這些時遇到的 Beam Lisp 陷阱（已安裝 bl，2026-10-31）： 不在核心中 — ffirst、reductions、spit、replace、format、parse-long、prn。 請使用 File/read!、File/write!、File/rename!、String/replace、Regex/run|scan|split|replace、 erlang/binary_to_integer、(println (pr-str x))。參數從右到左求值。 永遠不要將公開函數命名為核心函數的名稱。Hiccup 子元素必須是序列（map/for），而不是向量： (map identity v)。

檢視方式

chromium --headless=new --no-sandbox --hide-scrollbars --window-size=412,16000 \
  --virtual-time-budget=5000 --screenshot=/tmp/d.png http://127.0.0.1:PORT/
nix shell nixpkgs#imagemagick --command magick /tmp/d.png -crop 412x1000+0+0 +repage /tmp/d0.png

頁面高度超過 16000 像素：使用先前的 section.part 隱藏來儲存 HTML，並對其進行截圖。 檢查：先檢查手機寬度、每個圖表是否可讀、兩種主題、沒有 ✗ failed 的程式碼區塊。

作為應用程式閱讀

在寬螢幕上，頁面會變成一個兩欄的應用程式，且無需修改檔案：每個一級標題都會變成側邊欄中的一個頁面（展開時其下的二級標題也會顯示）。一個章節會顯示它還等待多少個答案，回答完畢後顯示 ✓，以及其 DONE/總數的進度。一次只顯示一個章節，底部有上一個/下一個按鈕，並可透過 ←/→ 移動。#all（「整份文件」）顯示所有內容；任何 #anchor 都會開啟包含它的章節。在手機上，晶片會以相同方式切換章節。將一級標題撰寫為報告的頁面，二級標題則為其組成部分。

設計語言

模擬圖可以採用產品真實的設計語言。在檔案頂部加上 #+design: forest 會讓其中的每個 screen 和 desk 都採用該設計（單一區塊可以用 :design NAME 覆蓋，或使用 :design none 退出）；模擬圖的行不需要更改。當存在產品自己的語言時，優先使用它而非 kit 的預設調色板。

一種語言是一個文字模組，kit/dossier/design/NAME.bl.org，其中的程式碼區塊就是命名空間 dossier.design.NAME：包含代碼（淺色和深色）、字體比例、圓角、陰影、動畫代碼，以及重新綁定 kit 模擬圖變數的 CSS。在 kit/dossier/design.bl 中註冊它。同一個檔案也是其樣本頁面，透過四個從模組繪製自身的區塊來呈現：#+begin_palette、#+begin_type、#+begin_shape、#+begin_motion（每個都帶有 :design NAME，空白主體）。保留一個 parity 程式碼區塊，檢查代碼與產品發佈的 CSS 是否一致；kit 測試會斷言沒有偏差。

已發佈：forest — Nurturing Forest，Ora 的團隊機器（design/forest.bl.org，作為 forest-language 服務發佈）。

Kit

kit/serve.bl（路由 / /doc /rev /src /answers POST /answer）、kit/answers.bl、 kit/dossier/{org,attrs,ui,page,answer,design}.bl（純）、kit/dossier/design/*.bl.org、 kit/style.css、kit/live.js。 測試：bl test -p ~/.claude/skills/bl-org-dossier/kit kit/test/kit_test.bl。 一個新元件 = ui.bl 中的一個 -h 函數、block->h 中的一個案例、CSS、測試中的一個搜索點。 答案由 patch-line 寫入：只有 :answer :note :at :by 會變更；檔案的其他每個位元組都保持不變。

此技能位於 ~/projects/enchanted-skills/bl-org-dossier（公開的 undefine-org/enchanted-skills 儲存庫）；~/.claude/skills/bl-org-dossier 是指向它的符號連結。 它由使用此技能的每個工作階段共用。邊進行邊提交，一個想法一個提交，並且只暫存你自己的檔案（先執行 git status：另一個工作階段可能正在編輯中）。對檔案服務進行 work restart 會載入磁碟上的任何內容，包括未提交的編輯。將讀者的答案保留在檔案所屬儲存庫中的自己提交中，這樣 git diff 就能顯示他們說了什麼。