warp-context/rightStage

aiflow – 在終端間同步 AI 提示上下文

是什麼

• 一個輕量級的 shell 腳本工具，允許你儲存單一的 Markdown 檔案（.ai/progress.md）來描述專案的當前狀態，並自動為任何你正在對話的 LLM 注入簡潔、高效能的上下文區塊。
• 無需背景守護程序、伺服器或複雜設定——只需三個腳本（ai_inject、ai_progress、ai_done）和一個 Markdown 檔案即可運作。

為何重要

• 當你在終端間切換時，常常會忘記自己在做什麼，不得不為 AI 模型重複輸入相同的上下文。aiflow 透過將上下文作為所有 shell 都能讀取的單一真實來源，消除這種摩擦。
• 它還透過解析你的 Git 提交訊息來自動更新任務清單，因此「目前/下一個」任務能保持準確，無需手動編輯。

主要指令

指令	功能
ai_inject [選項] [專案目錄] ["提示"]	讀取 .ai/progress.md 和 .ai/ctx/ 中的自動產生檔案，建構簡短的上下文區塊（CURRENT, NEXT, GOAL, API, CONSTRAINT, ISSUES）並輸出。選項可讓你將輸出複製到剪貼簿（-c）或跳過 Git 基礎的自動更新（-n）。
ai_progress [專案目錄]	掃描 Git 日誌中的任務編號（例如 [2]），並更新 progress.md：將已完成的任務標記為 done，第一個未完成的任務標記為 doing，其餘為 todo。由 ai_inject 自動呼叫。
ai_done [專案目錄]	手動將目前的 doing 任務標記為 done，並將下一個 todo 任務提升為 doing。

典型工作流程

1. 建立任務清單（每個倉儲只需一次）：

   mkdir -p .ai && cat > .ai/progress.md <<'EOF'
   [1] 登入介面        done
   [2] API 整合        doing
   [3] 錯誤處理        todo
   [4] 單元測試        todo
   EOF
   

2. 注入上下文（每次需要與 LLM 對話時）：

   ai_inject .                     # 輸出上下文
   ai_inject -c .                  # 輸出並複製到剪貼簿
   ai_inject -c . "幫我修復重試邏輯"  # 包含你的提示
   

3. 在提交訊息中使用任務編號來保持清單同步：

   git commit -m "[2] API 整合完成"
   

   下次執行 ai_inject 時，任務 2 會自動標記為 done。

檔案結構

project/
└── .ai/
    ├── progress.md          # 你手寫的任務清單
    └── ctx/
        ├── 00_goal.md       # 可選：專案目標（寫一次）
        ├── 02_current.md   # 產生 – 目前任務
        ├── 03_next.md      # 產生 – 下一個任務
        ├── 04_constraint.md# 可選：限制條件
        ├── 05_api.md       # 可選：API 規格
        └── 07_issue.md     # 可選：已知問題

全域備用目錄（~/.ai/ctx/）可用於儲存跨專案共享的預設值。

安裝

curl -fsSL https://raw.githubusercontent.com/warp-context/rightStage/main/install.sh | bash

或克隆倉儲並手動執行 bash install.sh。

支援平台

• macOS (zsh/bash)
• Linux (bash)
• Windows Git Bash

整合

• 與任何接受純文字的 LLM（Warp AI、Claude、ChatGPT、Cursor、GitHub Copilot 等）相容。
• 正在討論一個基於 Rust 的移植版本，用於在 Warp 終端中實現原生整合，這將讓終端能直接讀取 .ai/progress.md 而無需呼叫 shell 腳本。

設計原則

1. 上下文是模型的執行時狀態，而非人類文件。
2. 首先顯示目前任務，接著是下一個任務，再是最少的支援資訊。
3. 從 Git 自動更新，避免過時的手動編輯。
4. 保持注入區塊在約 100 行以內，以維持 Token 效率。

卸載

rm ~/.local/bin/ai_inject ~/.local/bin/ai_progress ~/.local/bin/ai_done
rm -rf ~/.ai   # 可選，移除全域備用

授權：MIT。

---

總結：aiflow 是一個輕量級的 shell 腳本工具包，透過維護一個單一、自動同步的上下文檔案，簡化了開發終端與任何 LLM 之間的交接流程。對經常使用 AI 助手進行程式碼撰寫、除錯或設計任務的開發者非常實用，可避免重複複製貼上專案狀態。