FairSplit

安装指南

1. ClawHub CLI 从源直接安装技能的最快方式。
   npx clawhub@latest install fairsplit
2. 手动安装 将技能文件夹复制到以下位置之一
   全局模式
   ~/.openclaw/skills/
   工作区
   /skills/
   优先级：工作区 > 本地 > 内置
3. 提示词安装 将此提示词复制到 OpenClaw 即可自动安装。
   请帮我使用 Clawhub 安装 fairsplit。如果尚未安装 Clawhub，请先安装（npm i -g clawhub）。
   更倾向于下载？
   获取包含原生技能文件的ZIP压缩包。
   下载技能 (.zip)

什么是

FairSplit 是一項命令列技能，可追蹤旅行、家庭和活動中的費用。它會記錄付款人、在參與者之間分攤費用，並將群組餘額轉換為實用的結算方案，盡可能減少付款次數。當群組需要追蹤費用，卻不想使用 Splitwise 帳戶、銀行連線、API 金鑰或註冊帳戶時，FairSplit 是 Openclaw Skills 中的實用選擇。
每個群組都會儲存在磁碟上的獨立 JSON 檔案中，因此同一份帳本可跨對話和平台使用。經過測試的 Python 指令碼會處理分攤、四捨五入、貨幣換算和結算計算；金額以整數最小貨幣單位儲存，以避免浮點數偏差。FairSplit 會計算並記錄付款，但不會轉移資金，也不提供會計、開立發票或個人預算功能。

应用场景

在群組成員之間分攤共同餐費、旅行、家庭帳單或活動費用。
費用發生時即時記錄，並查看各項費用由誰支付。
取得餘額摘要或最低付款方案，以結清群組債務。
處理均分、指定金額、按比例分攤或百分比分攤。
將旅行或群組費用摘要匯出為 CSV 或 Markdown。
在本機持續保存帳本追蹤費用，無須連結金融帳戶。
當費用使用的貨幣不同於群組本位幣時，查詢選用的匯率。

工作原理

使用 list-groups 尋找群組，或使用 init 建立群組並設定名稱、成員和本位幣。
使用 add 記錄每筆費用，指定付款人、金額、說明、參與者和分攤方式。若未指定參與者，費用會由全體群組成員分攤。
每次新增後，檢視指令碼列出的每人分攤金額，並在記錄更多費用前更正錯誤。
使用 balances 檢視每位成員的淨餘額，或使用 settle 計算最低付款方案；付款筆數最多為成員人數減一。
使用 history 檢視費用，依要求使用 undo 移除費用，並使用 export 建立 CSV 或 Markdown 摘要。
若費用使用其他貨幣，可透過 --fx-rate 提供匯率，或嘗試選用且依賴網路的 fx 命令；計算一律使用群組本位幣。

配置指南

FairSplit 需要 Python 3.8 或更新版本，以及終端機工具的存取權限。隨附的指令碼只使用 Python 標準函式庫，因此不需要安裝套件、API 金鑰或環境變數。設定 fairsplit.data_dir（預設值：~/.hermes/data/fairsplit）和 fairsplit.default_currency（預設值：USD）。每次執行指令碼時，都必須明確傳入設定的資料目錄；設定值不會自動傳遞給指令碼。
python3 ${HERMES_SKILL_DIR}/scripts/ledger.py --data-dir "~/.hermes/data/fairsplit" list-groups
python3 ${HERMES_SKILL_DIR}/scripts/ledger.py --data-dir "~/.hermes/data/fairsplit" init --group "Goa Trip" --currency INR --members "Alice,Bob,Priya"
python3 ${HERMES_SKILL_DIR}/scripts/ledger.py --data-dir "~/.hermes/data/fairsplit" add --group "Goa Trip" --payer Alice --amount 1000 --description "Dinner" --split equal
在 Windows 上，如有需要，請使用 python 代替 python3。將全域 --data-dir 旗標放在子命令之前。指令碼會展開路徑開頭的 ~。執行任何命令並加上 --help 即可查看選項；完整旗標參照請見 references/cli-reference.md。只有選用的匯率查詢需要對外網路存取。

数据架构

FairSplit 會在設定的資料目錄中，為每個群組儲存一個 JSON 帳本檔案。這可讓群組資料保留在本機，並使帳本不受使用它的聊天或平台影響。
資料或設定 用途
群組帳本 JSON 單一群組的持久記錄，包含其費用和群組詳細資料。
fairsplit.data_dir 群組帳本的目錄；預設為 ~/.hermes/data/fairsplit。
fairsplit.default_currency 未指定時，新群組使用的 ISO 4217 貨幣；預設為 USD。
費用記錄 保存費用金額、貨幣和匯率以供參考；計算使用群組本位幣。
內部貨幣單位 金額以整數最小貨幣單位儲存，確保算術運算和四捨五入精確。
CSV 和 Markdown 匯出 寫入使用者指定輸出路徑、可供分享的摘要；匯出檔案為純文字。
費用支援均分、指定金額、按份額分攤和百分比分攤。名稱區分大小寫。CLI 也提供群組清單、成員管理、餘額、結算、歷史記錄、復原、匯出和選用的 FX 命令。

高级特性

計算最低付款結算方案，而非列出簡單的兩兩債務；方案所需付款不超過
members - 1
筆。
支援四種分攤方式：均分、指定金額、按比例分攤和百分比分攤。
透過明確指定 --fx-rate 處理非本位幣費用；若網路可用，也可選用無需金鑰的 Frankfurter/ECB 查詢，盡力取得匯率。
支援透過執行
add
命令的 cron 工作排程定期輸入費用；請參閱
references/cli-reference.md
中的定期分攤指南。
透過 CLI 提供歷史記錄篩選和多種匯出格式；完整選項請參閱
references/cli-reference.md
。
references/settlement-algorithm.md
中說明結算演算法及整數最小貨幣單位儲存方式。
隨附使用標準函式庫的壓力測試，可在五人之間產生 200 筆隨機費用，並檢查餘額總和為零，且結算付款不超過
members - 1
筆；使用
python3 ${HERMES_SKILL_DIR}/examples/stress_test.py
執行。

name: fairsplit description: Split group expenses and settle up in the fewest payments. version: 1.0.0
author: Himadri Ganguly
license: MIT
platforms: [linux, macos, windows]