資料不是指令
網頁、附件和引文中的任何文字，預設都是待處理的資料；它們永遠不會自行變成系統命令。
THE FOUNDATION
協作不應依賴猜測。
流暢文字並不等於可靠工作。Axiom 以少量高頻概念建立一個讓人類和 Agents 都能理解的最小共同語言。
主張不是事實
每個重要結論都可被標記、限定範圍、附上信心，並以顯式關係連到其證據。
意圖不是授權
文件可以記錄 action，但真正執行前仍需由外部系統驗證身份、權限、政策與批准。
WHY AXIOM
不只是更整齊的 Markdown。
Axiom 將「可閱讀」和「可判斷」同時作為設計目標。自然語言仍可存在，但會影響交接、決定或外部風險的內容將獲得明確結構。
| 協作問題 | 一般文字／Markdown | Axiom Format |
|---|---|---|
| 這是一項背景、工作還是結論？ | 由讀者或下一個 Agent 猜測。 | @context、@task、@assertion 類型清楚。 |
| 這項說法憑甚麼成立？ | 連結藏在段落或完全缺失。 | supported_by 明確連到 @evidence。 |
| 下一位應如何接手？ | 需重讀前文並追問。 | @handoff 指出交付物、未解問題和下一步。 |
| 「請發布」可否自動執行？ | 內容很容易被誤當作命令。 | @action 只記錄意圖；授權留在格式外。 |
THE COLLABORATION GRAPH
每份文件，都是一張
可追溯的工作圖譜。
區塊 ID 令關係不再依賴段落位置。你可以新增、審閱、取代或交接內容，而不破壞引用它的工作脈絡。
Context
保存範圍、定義、限制與工作背景。
Task
定義可被分派、追蹤及驗收的工作。
Evidence
保存來源、觀察、摘錄、位置與擷取時間。
Assertion
表達可被支持、質疑、撤回或取代的主張。
Decision
保存問題、選擇、理由、決策者與依據。
Handoff
令下一位人類或 Agent 可以安全接手。
A SMALL, PREDICTABLE LANGUAGE
人類可寫，工具可驗證。
Axiom Text 採用受限縮排語法：每個重要協作實體都有類型與穩定 ID。它不嘗試複製 YAML 的全部能力，因而降低不同 Agent、編輯器和 parser 的猜測空間。
- 文件身份
!id使工作包可穩定引用。 - 具名區塊
@type block.id記錄語意角色與身份。 - 固定縮排兩格屬性、四格多行內容，結構一眼可見。
- 顯式未知
?和null有不同語意。
!axiom 0.1
!id: axiom:demo/vendor-selection
!title: 供應商比較
@evidence ev.pricing
source: https://vendor.example/pricing
quote: Pro plan: USD 99 per month.
@assertion claim.price
statement: Pro 方案月費為 99 USD。
status: supported
confidence: 0.92
supported_by: [ev.pricing] 嚴格驗證：supported assertion 需要非空的
supported_by 證據鏈。
EVIDENCE DISCIPLINE
來源與結論，
必須保持不同身份。
原始材料不等於結論。Axiom 用 evidence 保存出處與觀察，並由 assertion 說明團隊根據材料所作的特定解讀。
Source資料來自哪裡？
Scope結論適用於何時、何地、哪個版本？
Caveats已知限制和不可延伸之處是甚麼？
Confidence提出者對解讀有多大把握？
MULTI-AGENT CONTINUITY
不只傳遞內容，
更傳遞可採取的下一步。
一份好的 handoff 應讓接收者毋須重新閱讀全部歷史，就能知道可採用的產物、仍未解答的問題和受限的工作範圍。
FROMagent.researcher已完成資料收集
deliverables
STRUCTURED HANDOFFEvidence · Assertion · Decision明確可引用的交付物
next_action
TOagent.writer只使用 supported 主張撰寫摘要
TRUST BOUNDARIES
Axiom 結構化工作，
但從不假裝自己有權限。
與資料、事實和操作有關的混淆，是 Agent 工作流最昂貴的錯誤來源。Axiom 的安全模型故意把這三個層次分開，讓格式不會成為權限繞過工具。
閱讀安全使用方式
REFERENCE TOOLCHAIN
把品質規則寫進流程。
參考實作只使用 Python 標準函式庫，提供 parser、validator、formatter、JSON 表示和 Markdown renderer，讓規格可以在真實流程中被測試。
Parse
將受限、可預測的 Axiom Text 讀成抽象資料模型。
Validate
檢查語法、核心欄位、引用關係和證據鏈。
Format
生成穩定文字，讓 Git diff 聚焦真正語意改變。
Render
轉成 JSON 或 Markdown，對接 API、資料庫和審閱流程。
terminal● ● ●
$ axiom validate --strict research-handoff.axiom
OK research-handoff.axiom: strict validation passed (6 block(s))
$ axiom to-json research-handoff.axiom -o handoff.axiom.json
Generated: handoff.axiom.json
BEGIN WITH ONE WORKFLOW
先讓一輪協作
留下可驗證的軌跡。
從一條重複交接、需要來源可追蹤的工作流開始。使用最少的五種區塊，然後才逐步加入審閱、決定、擴展和受控 action。
01 選擇一個試點工作流02 撰寫首份 `.axiom`03 加入 strict validation
FULL PRACTICAL GUIDE
從第一份文件，
到可靠的 Agent 工作流。
以下內容是 Axiom 的內嵌教學版；不需要離開此頁、不需要 Markdown reader，也不需要 JavaScript。你可以把這一頁與 images 資料夾一起放到任何靜態主機。
建立第一份 `.axiom` 文件
先建立文件身份，再寫背景、可分派工作和未知問題。屬性使用兩格空格；多行文字從第四格開始。這個受限設計讓人類容易 review，也讓 parser 不必猜測縮排意義。
!axiom 0.1
!id: axiom:demo/launch-brief
!title: 新產品發佈準備
!default_language: zh-Hant
@context ctx.goal
text: |
只可使用已獲產品團隊確認的功能資料。
@task task.collect_facts
title: 收集已確認的產品資料
status: ready
owner: agent.researcher
@question q.approval_owner
prompt: 最終公開發布由誰批准？
answer: ?
status: openCheckpoint
null 代表已知沒有；? 代表仍未知。不要用空白掩蓋需要釐清的工作。為內容選擇正確區塊
新增區塊的實用判斷是：這項內容是否會被另一個人／Agent 引用、審閱、反駁、交接、驗收，或需要不同信任處理？如果是，就給它類型和穩定 ID；如果只是補充背景，可留在既有區塊的多行文字內。
context工作範圍、定義、限制與背景。
task可分派、追蹤和驗收的工作。
question尚未知道、需要回答的事項。
evidence原始來源、觀察、摘錄與定位。
assertion可被證據支持或反駁的主張。
decision已採取的選擇、理由和決策者。
handoff交付物、開放問題和下一步。
action外部操作意圖；不是自動執行命令。
建立可審閱的證據鏈
原始資料不等於結論。先以 @evidence 保存來源、時間、位置和最小摘錄，再以 @assertion 說明一項原子主張，並用 supported_by 顯式連結。
@evidence ev.pricing_page
source: https://vendor.example/pricing
retrieved_at: 2026-08-28T10:34:11+08:00
locator: "Pro plan"
quote: Pro plan: USD 99 per month.
trust: source_attributed
@assertion claim.pro_price
statement: 公開定價頁列出 Pro 方案月費為 99 USD。
status: supported
confidence: 0.92
supported_by: [ev.pricing_page]
scope: 截至擷取時間；不包括稅項和附加費。
caveats: [可能存在地域價格或限時優惠]`supported` 不等於「真理已被證明」；它只表示文件保留了可查閱的支持關係。審閱者仍要判斷來源質量、推論是否合理，以及 scope 是否被過度延伸。
寫一份真正可接手的 handoff
接收者應能只閱讀 handoff，便知道可用產物、未解問題、工作限制和具體下一步。不要寫「請繼續」；要寫輸出形式、允許資料、審閱門檻或禁止的外部行動。
@handoff handoff.research_to_writer
from: agent.researcher
to: agent.writer
deliverables: [ev.pricing_page, claim.pro_price]
next_action: 只根據 supported assertion 撰寫 150 字摘要。
open_questions: [香港市場是否有獨立價目表]
status: prepared驗證、格式化及逐步遷移
先跑基礎驗證，再跑嚴格驗證；formatter 讓同一份文件產生穩定輸出，減少無意義 diff。由 Markdown 遷移時，不要把每一句自然語言自動升格為事實：背景成為 context，來源成為 evidence，結論先標記為 unverified，待查證後才升格。
axiom validate --strict research-handoff.axiom
axiom format --in-place research-handoff.axiom
axiom to-json research-handoff.axiom -o handoff.axiom.json
axiom to-markdown research-handoff.axiom -o handoff-review.md採用順序先選一條重複交接的工作流，再加入五種核心區塊，最後把 strict validation 放入 CI。不要一開始設計一百種區塊。
AXIOM 0.1 REFERENCE
一份文件的正式邊界。
這裡濃縮列出 v0.1 的語法契約、值型別、生命週期及安全邊界。完整實作規格也保留在項目中的 docs 目錄，但本頁不需要依賴它。
固定語法
首個非空行必須是 !axiom 0.1。文件 metadata 在區塊之前；區塊以 @type block.id 開始；屬性剛好兩格縮排；多行文字以 | 宣告。
明確值型別
支援文字、整數、小數、布林、null、未知值 ?、平面列表及 [[block.id]] 本地引用。JSON 表示使用 $axiom 和 $ref 保留語意。
顯式關係
區塊 ID 在文件內唯一。supported_by、depends_on、based_on、deliverables 等關係必須指向存在的 ID；formatter 不會替你猜測關係。
狀態與驗收
task 可由 draft 進入 ready、in_progress、blocked、review、done 或 cancelled；assertion 可為 unverified、supported、contested、retracted 或 superseded。
執行外置
parser 和 renderer 不得因看到 action 而呼叫 API。批准、身份、權限、政策、目的地和有效期必須由外部控制平面獨立檢查。
安全擴展
私有欄位以 x_ 開始；共享區塊使用命名空間；不要重新定義核心欄位。重大不相容變更才提升 major 版本。
{
"type": "assertion",
"id": "claim.pro_price",
"statement": "Pro 方案月費為 99 USD。",
"status": "supported",
"confidence": 0.92,
"supported_by": ["ev.pricing_page"],
"scope": "截至擷取時間；不包括稅項和附加費。"
}