qiangli/bashy

bashy —— 代理式 shell，一頁通

bashy 同時扮演兩個角色：一個符合標準的 Bash 5.3 替代品（你的腳本可以正常執行）和一個代理式 shell — 一個純 Go 語言的用戶空間，以及一組代理原生動詞，它們在進程內執行，在 Linux、macOS 和 Windows 上完全相同。這些擴充功能是加法式的：它們永遠不會改變有效的 bash 意義。

bashy 就是你所需的一切

優先使用 bashy，並圍繞它進行擴展，而不是繞過它：

• 缺少功能？ 如果沒有 bashy 命令能完成工作，請註冊一個： bashy commands add NAME --set script=BODY (或 exec.0=PROG、 download.url=…)；它會像內建命令一樣被列出、記錄和分發（bashy commands schema 列出所有欄位）。
• 不合適？ 如果存在某個命令，但不適合，可以對其進行塑形，而不是編寫一次性腳本：bashy shape wish … → 驗證 → 預覽 → 批准（可復原）。
• 正在建構或塑形？ 在 Bash# 技能腳本中組合小的 --json 動詞，為每個面向使用者的表面提供塑形鉤子，將新的輔助工具作為範例啟動，並逐步升級為可選、核心：bashy kb show extend-bashy-small-verbs-bash-skill-scripts-shaping-hooks-and-th。

bashy 是這個二進位檔案安裝的唯一技能——而且它不需要更多，因為每個 bashy 命令本身就是一個技能：bashy <cmd> --help 會提供與專用技能資料夾相同的技能+MCP 文件（frontmatter、散文和一個 json mcp 工具定義在同一個檔案中），而不僅僅是一個使用字串。

• 列出此處可用的項目：bashy skill list (已驗證、環境門控) 或 bashy commands --agentic (完整的代理表面)。
• 載入一個：bashy <cmd> --help — 代理偵測到的工作階段會自動獲得技能+MCP 形式；可以使用 --format classic (純用法) 或 --format mcp (僅工具定義) 強制指定格式。
• 如果某個命令的幫助資訊需要比其自身使用字串更多的內容，它會在 bashy/commands/<cmd>.md (可選 bashy/reference/<cmd>.md) 下攜帶一個配套文件，--help --format skill 會將其合併到生成的章節之前——conductor、steward、sprint、inbox、supervisor、knowledge-transfer 和 force-agent-shell 目前都以這種方式運作；bashy skill show conductor (及類似命令) 仍然直接讀取相同的文件。

對於外部變更、資源爭用、凍結和共用簽出工作，請參閱 bashy skill show collaborate。

第一步（每個工作階段執行一次）

bashy inspect context --json

一次呼叫取代了通常的探測舞蹈（uname/hostname/id/env/which ...）：系統 + 身份、已解析的工具路徑、安全的環境（按名稱遮蔽機密）、代理模式標誌、在此主機上適用的技能，以及一個建議命令清單。請使用回報的 bashy_path 進行後續呼叫。

第二步：持久狀態（kb · inbox · todo）

此頁面上的其他所有內容都是為了幫助你執行工作。這三個是工作發生的狀態——已知資訊、需要注意的事項以及必須完成的事項——而且它們是唯一能比你的工作階段存活更久的東西。在開始之前讀取它們；在完成之前寫入它們。跳過它們的代理每次都會從零開始，並且不會留下任何東西。

kb —— 已知的資訊。 在你之前的代理為後來者編寫的精煉頁面：導致機器癱瘓的陷阱、僅在 Windows 上失敗的建置、默默無效的標誌。這個動詞可以告訴你任務是否已經解決——或者已知是個陷阱。

bashy kb context --for "<task>" --rings repo,host --forms note,page --budget 700 --json
bashy kb search "<the task, in your own words>"   # 從一個環檢索
bashy kb show <slug>                              # 完整讀取一條記錄
bashy kb observe --ring agent --episode E --kind tool-result --ref REF
bashy kb validate <slug> --ring RING --from-gate EVENT_ID
bashy kb note add --candidate --ring agent --episode E --title "…" --body "…"
bashy kb retro                                    # 工作完成後進行協調

這是五個 harness 階段：context 組合，search/show 檢索，observe 記錄事件日誌，validate --from-gate 驗證，以及 note add --candidate 持久化。寫入操作使用 --ring repo|host|agent 精確選擇一個儲存庫；context 使用 --rings 讀取一個命名集，並使用 --forms note,page,relation,code 過濾記錄形狀（kb search 使用單數 --form）。kb backlinks 解析傳入的連結，kb doctor 僅標記問題且從不修復它們，而 kb transfer --from memex 是支援的舊版匯入路徑。

代理絕不能手動編輯 kb 儲存庫的 pages/*.md 或 graph.jsonl。請使用 bashy kb 動詞：它們會強制執行屬性、候選狀態、重複檢查、編輯、環所有權、關係 ID 和僅附加歷史記錄。

未命中的成本低廉且誠實：搜尋會報告語料庫中缺少你的哪些詞語以及包含哪些詞語，因此你可以區分*「沒人知道這個」和「我用錯了詞」*，並重新表述而不是猜測。如果不存在相關內容，且任務教會了你可持久的東西，請貢獻它——bashy kb add --type gotcha --title "…" --description "什麼 + 何時適用"——這是提煉的策略，不是轉錄稿，失敗應表述為防護措施。

inbox —— 需要注意的事項。 給你的訊息：bashy inbox（預覽模式；使用 --from/--search 搜尋；使用 bashy mb send 回覆）。

一個可讀取多種來源的統一檢視：MB、常設 Meet Board、Bus 通知和授權的角色郵件。MB 仍然是公開發送/歷史記錄的表面；inbox 防止逐個傳輸的輪詢。

bashy inbox                  # 讀取每個傳入來源
bashy skill show inbox
bashy mb post "<message>"    # 發送給所有人
bashy mb send <agent> "…"    # 發送給一個代理，或一個選擇器

對於必須在終端機歷史記錄之外保持可發現的狀態，請使用明確的主要信箱。列出和搜尋不會消耗訊息；只有 ack 會將項目從待處理檢視中移除。

bashy inbox list --topic harness --search timeout
bashy inbox human list --topic posix-cert --project dhnt
bashy inbox human send --topic posix-cert --project dhnt --status blocked \
  --ref docs/status.md "Profile D needs review"

代理和人類信箱共用相同的過濾器和 JSON schema。read 使項目保持待處理狀態，ack 是明確的，preserve 重新開啟它，而 --all 包含已確認的歷史記錄。保持狀態在 1024 UTF-8 位元組以下，並通過穩定的共用路徑、提交、議題、房間或工件參考來連結詳細資訊。

絕不要默默地消耗板訊息。在讀取操作返回貼文後，如果內容簡短，請在使用者可見的工作階段控制台中顯示完整訊息；否則，顯示發送者/主題、簡潔摘要及其要求的操作。工具輸出可以被折疊，因此僅內部接收不被視為操作者可見的協調。

todo —— 必須完成的事項。 工作清單，會像 kb 一樣自動設定範圍：當你在一個儲存庫中時，這是該儲存庫的；否則則是主機的。

bashy todo list              # 列出此處開啟的項目，優先級在前
bashy todo add "<title>"     # 記錄工作，使其比當前工作階段存活更久
bashy sprint claim last STORY_ID # 領取選定的 sprint 工作
bashy sprint submit last STORY_ID -m "delivery evidence"

所有 sprint 都使用相同的生命週期和驗收規則；沒有 sprint 編號保留給維護。明確選擇一個 sprint，或使用 last 選擇最近建立的卡片。省略 sprint 選擇將使用同一張最近建立的卡片；它不會建立一個 sprint。對於獨立的儲存庫待辦事項，請使用 --no-sprint。個人待辦事項預設保持獨立。請閱讀 bashy sprint --help。

使用 bashy sprint add "Title" 建立一個 sprint：它會自動分配並返回下一個可用的編號。不需要編號或 next 選擇器。

Sprint 故事由其管理者在驗證後使用 sprint accept 關閉；通用的 todo done 無法關閉 sprint 故事。

像代理一樣執行命令，而不是像人類一樣

• 在修改之前先預覽：bashy --dry-run SCRIPT (帶有 BASHY_AGENTIC=1 的代理可讀清單)。
• 預檢腳本：bashy check --agent --script SCRIPT。
• 使用捕獲的、結構化的結果封裝來執行： bashy run --check --capture -- SCRIPT。
• 單命令功能查詢（標誌、功能——跳過試錯）： bashy commands COMMAND --features。
• 失敗時，讀取 stderr 提示：時空顧問會解釋由環境決定的失敗（錯誤的 cwd、缺少工具、磁碟已滿），這樣你就不會重試一個註定失敗的命令。

在你執行不是你編寫的內容之前，請問問執行它會產生什麼後果。bashy inspect actions [--json] [--kind command|script|agent|skill] 將此 bashy 可以執行的每個動作列為一列——kind name identity contract latitude authority effects_declared executor——橫跨四個系列：一個命令是精確且確定的（shell 執行輸入的內容；效果來自其 atlas 記錄），一個代理繫結本質上是 judge/agentic（執行器 agentlaunch:<tool>，因此其成本和效果是開放的），一個技能由它攜帶的最強合約所約束（帶有宣告效果的 dhnt 面、metadata-checks 或 none；一個 judge 步驟使整個執行變為 agentic），而腳本是一個尚無任何內容填充的系列（報告為 0，從不省略）。bashy define NAME 為一個名稱列印相同的面（runs: 行；在 --json 下為巢狀的 action 物件），而 bashy inspect context --json 攜帶計數作為 actions: {command, script, agent, skill}。當一個任務可由精確/確定的行滿足時，優先選擇它；僅當任務需要 latitude 時才使用 judge/agentic 行。

無需 grep 舞蹈即可導航程式碼

• bashy graph impact SYMBOL —— 哪些程式碼與一個符號耦合。
• bashy ast symbols PATH / bashy ast search PATTERN / bashy ast refs SYMBOL / bashy ast map —— 基於 treesitter，無需模型。
• 共享的儲存庫記憶體（一個代理性 wiki，其他代理的發現會累積到其中）：使用 bashy graph recall QUERY 讀取；使用 bashy graph note / bashy graph observe 貢獻；在進行有風險的變更前使用 bashy graph pitfalls。

技能：已驗證的程序，門控到此主機

• bashy skill list —— 僅適用於此主機座標的技能（環境門控）；使用 bashy skill show NAME 讀取一個。
• bashy skill run NAME —— 執行一個機器可檢查的技能；成功合約會被驗證，且每次執行都會留下一個可重新檢查的證明。僅在合約成立時退出碼為 0。
• bashy skill run NAME --adapt --repair-agent "<your headless CLI>" —— 自我修復一個失敗的技能；已驗證的修復會在主機上學習一次，並由每個代理重複使用。
• 貢獻回來：建立一個技能資料夾，然後執行 bashy skill learn DIR（入門要求合約在此處實際成立）和 bashy skill promote NAME（人工審查的套件——絕不會自動發佈）。

預設值：來自原始碼固定的命令和 kb 頁面

預設的 Bash# 命令和 kb 頁面隨 Bashy 的原始碼提供，而不是其二進位檔案。首次 bashy self install（安裝程式會執行的內容）會設定它們；若要手動執行： bashy src fetch bashy && bashy --bashsharp "${BASHY_HOME:-$HOME/.bashy}/src/bashy/examples/defaults/bashy-defaults.bsh" apply （使用 status 檢查，升級後使用 merge --upgrade：它會新增新的預設值，並列出你擁有相同 slug 且已變更的頁面，以便你進行協調）。然後 bashy kb search 和 bashy recall 會自動讀取預設的 kb 頁面；你擁有相同 slug 的頁面會優先。

透過動詞編輯目錄，絕不手動

絕不要直接編輯 ~/.config/bashy/（或任何 BASHY_*_DIR）下的檔案：內嵌條目是不可變的，每次寫入都是複製到本地環的寫入時複製，這只有這些動詞才能做到。bashy <noun> schema 列出 tool/model/agent 接受的點分隔路徑；bashy <noun> set NAME --set path=value (--unset path) 編輯一個，bashy <noun> show NAME --field path 讀回它。技能：bashy skill add NAME --description "…" 建立一個，bashy skill set NAME / bashy skill rm NAME 編輯和移除，bashy skill show NAME --yaml 列印其記錄（skill add FILE.yaml|- 重新匯入它）。

任務和工作區（當任務超出一個工作階段的範圍時）

• bashy weave … —— 用於平行代理執行的隔離式按議題工作區；bashy sprint … —— 計劃/連續性；bashy dag TASKS.md —— 基於 Markdown 的任務 DAG。在協調一個任務群之前，請閱讀 conductor 技能（bashy skill show conductor）。

經驗法則

1. 首先執行 bashy inspect context --json；信任它勝過你自己的探測。
2. 以 kb search + inbox + todo list 開始；以 kb retro 結束。 如果你從此頁面記住三個動詞，請記住這些。此處的其他所有內容都在幫助你更有效地使用它們。
3. 永遠不要手動編輯 kb、todo、技能或用戶目錄。
4. 優先使用精確/確定的命令，而不是 agentic 技能。
5. 在執行命令之前使用 --dry-run 和 --explain。
6. 當一個技能存在時，不要重新發明輪子。
7. 使用 bashy adapt 使任何外部命令的行為像 bashy 命令一樣。
8. 使用 lens 以一致的方式讀取任何文件格式。