Sunwood-ai-labs/SourceSage

SourceSage CLI

概述

從此儲存庫檢查點使用 SourceSage CLI 為當前儲存庫或另一本地儲存庫生成摘要。

優先使用本地檢查點，而非假設 sourcesage 已全域安裝。在此儲存庫佈局中，SourceSage 工具根目錄為包含此 SKILL.md 的文件夾。

工作流程

1. 確定 SourceSage 工具根目錄與目標儲存庫。

   • 若使用者未指定其他儲存庫，則分析當前工作區。
   • 若當前工作區不是 SourceSage 儲存庫，則從其自身的檢查點執行 SourceSage：uv run --directory <sourcesage-root> sage ...。

2. 選擇能滿足需求的最小命令。

   • 當前儲存庫摘要：uv run sage
   • 當前儲存庫摘要（精簡模式）：uv run sage --lite
   • 當前儲存庫摘要（日文）：uv run sage -l ja
   • 其他儲存庫，輸出位於該儲存庫預設目錄：uv run --directory <sourcesage-root> sage --repo "<target-repo>"
   • 其他儲存庫（精簡模式）：uv run --directory <sourcesage-root> sage --repo "<target-repo>" --lite
   • 其他儲存庫，指定輸出目錄：uv run --directory <sourcesage-root> sage --repo "<target-repo>" -o "<output-dir>"
   • 已棄用的差異報告：uv run --directory <sourcesage-root> sage --repo "<target-repo>" --diff

3. 每次執行後驗證生成的產出物。

   • 儲存庫摘要：<output-dir>/.SourceSageAssets/Repository_summary.md
   • 已棄用的差異報告：<output-dir>/.SourceSageAssets/RELEASE_REPORT/Report_<latest-tag>.md
   • 開啟生成的 Markdown 檔案，並總結重要結果，而不僅回報命令已執行。
   • 在 --lite 模式下，確認摘要保留了目錄樹、Git 資訊、統計資料及根目錄 README 檔案，同時省略了 ## File Contents 部分。

4. 回報副作用與命令不匹配。

   • 預期 SourceSage 會建立 <repo>/.SourceSageignore（若該檔案不存在）。
   • 將 --ignore-file 視為支援的忽略規則覆寫參數。
   • 除非 CLI 已更新並重新驗證，否則不要依賴 --use-ignore，因為目前 CLI 並未公開該選項。

命令備註

• 在 SourceSage 儲存庫內優先使用 uv run sage，因為 pyproject.toml 定義了 sage 與 sourcesage 兩個進入點。
• 在 SourceSage 儲存庫外部優先使用 uv run --directory <sourcesage-root> sage ...，這樣命令會使用此檢查點，而無需全域安裝。
• 僅在套件已安裝且無法使用 uv 時，才直接使用 sourcesage 或 sage。
• 使用 -l ja 或 -l en 指定輸出語言。
• 使用 --lite 進行首次探索（當忽略規則尚未調整，或完整檔案摘錄會使摘要過大時）。
• 當使用者希望產出物位於儲存庫根目錄之外時，使用 -o。
• 使用 --repo 從此檢查點分析其他儲存庫。

驗證

• 執行所選的命令，而不是僅描述它。
• 確認預期的 Markdown 檔案確實存在。
• 讀取生成的輸出，回報路徑並提供簡短的產出摘要。
• 修改任何執行指令或相關文件後，重新執行確切的命令。

避免事項

• 當 README 範例與 sourcesage/cli.py 不一致時，不要將 README 範例視為權威。
• 當使用者指定了特定目的地且該位置已存在結果時，不要靜默覆寫現有的產出物。
• 不要憑記憶描述 SourceSage 的使用方式，而應檢查此儲存庫中的 pyproject.toml 與 sourcesage/cli.py。