Safe Rebase AI
Safe Rebase AI is a production-minded VS Code extension MVP that helps developers plan and apply conflict-resolution work on an isolated integration branch. It never applies AI-generated changes to the original source branch.
Safe Rebase AI 是一個以生產環境思維設計的 VS Code extension MVP，用來協助開發者在獨立的 integration branch 上規劃與套用 rebase / merge conflict resolution。它不會把 AI 產生的變更直接套用到原本的 source branch。
What It Does / 功能
English:
- Detects the current Git repository and source branch.
- Lets you choose a target branch.
- Finds merge bases, overlapping changed files, and likely conflict candidates.
- Builds a structured merge plan through a provider abstraction.
- Creates an integration branch from the target branch.
- Applies reviewable unified patches only on that integration branch.
- Runs configured build, test, and lint commands.
- Writes a JSON audit record for each session.
中文：
- 偵測目前的 Git repository 與 source branch。
- 讓使用者選擇 target branch。
- 找出 merge base、雙方都有修改的檔案，以及可能衝突的候選項目。
- 透過 AI provider abstraction 建立結構化 merge plan。
- 從 target branch 建立新的 integration branch。
- 只在 integration branch 上套用可審查的 unified patch。
- 執行設定好的 build、test、lint 指令。
- 每個 session 都會產生 JSON audit record。
Setup / 安裝與執行
npm install
npm run compile
English:
Open this folder in VS Code, press F5, and run the extension host. Use the Safe Rebase AI activity bar container or command palette commands.
中文：
在 VS Code 開啟此資料夾，按下 F5 啟動 Extension Host。接著可以使用 Safe Rebase AI activity bar 容器，或透過 command palette 執行指令。
API Keys / API 金鑰
English:
API keys must be stored through VS Code SecretStorage. Use Safe Rebase AI: Open Settings to open the provider setup form. The form supports:
- OpenAI Compatible: Base URL, API key, Model ID
- OpenAI: Base URL, API key, Model ID
- Anthropic: Base URL, API key, Model ID
Do not put API keys in settings.json.
中文：
API key 必須透過 VS Code SecretStorage 儲存。請使用 Safe Rebase AI: Open Settings 開啟 provider setup form。表單支援：
- OpenAI Compatible：Base URL、API key、Model ID
- OpenAI：Base URL、API key、Model ID
- Anthropic：Base URL、API key、Model ID
請不要把 API key 放在 settings.json。
Commands / 指令
Safe Rebase AI: Start AnalysisSafe Rebase AI: Create Integration BranchSafe Rebase AI: Apply Merge PlanSafe Rebase AI: Run ValidationSafe Rebase AI: Rollback IntegrationSafe Rebase AI: Open Settings
Step-by-Step Workflow / 從開始到完成的操作流程
1. Prepare Your Repository / 準備 Repository
English:
- Open the Git repository in VS Code.
- Checkout your current work branch, also called the source branch.
- Make sure your work is committed or safely stashed before starting.
- Fetch the latest remote refs if needed, for example
git fetch.
中文：
- 在 VS Code 開啟 Git repository。
- Checkout 到你目前工作的 branch，也就是 source branch。
- 開始前請確認你的變更已經 commit，或已安全地 stash。
- 如有需要，先取得最新 remote refs，例如執行
git fetch。
Example / 範例：
git checkout feature/my-work
git fetch
English:
- Open the command palette.
- Run
Safe Rebase AI: Open Settings.
- Select your provider.
- For OpenAI Compatible, fill in:
- Base URL
- API Key
- Model ID
- Click
Save.
中文：
- 開啟 command palette。
- 執行
Safe Rebase AI: Open Settings。
- 選擇你的 provider。
- 如果使用 OpenAI Compatible，請填入：
- Base URL
- API Key
- Model ID
- 點選
Save。
Common OpenAI Compatible examples / 常見 OpenAI Compatible 範例：
Base URL: https://api.openai.com/v1
Model ID: gpt-4.1-mini
Base URL: http://localhost:1234/v1
Model ID: local-model-id
API keys are stored in VS Code SecretStorage. They are not written to settings.json.
API key 會儲存在 VS Code SecretStorage，不會寫入 settings.json。
3. Start Analysis / 開始分析
English:
- Run
Safe Rebase AI: Start Analysis.
- Choose the target branch, for example
develop, main, or release.
- The extension detects:
- repository root
- source branch
- target branch
- merge base
- files changed on both branches
- likely conflict candidates
- A merge plan is shown in the sidebar and detailed webview.
中文：
- 執行
Safe Rebase AI: Start Analysis。
- 選擇 target branch，例如
develop、main 或 release。
- Extension 會偵測：
- repository root
- source branch
- target branch
- merge base
- 兩邊都有修改的檔案
- 可能發生 conflict 的候選項目
- Merge plan 會顯示在 sidebar 與詳細 webview 中。
Example / 範例：
Source branch: feature/my-work
Target branch: develop
4. Review the Merge Plan / 審查 Merge Plan
English:
Review every item in the Merge Plan view before applying changes. Pay special attention to:
manual_review items- high-risk files
- config files
- lockfiles
- migration files
- delete or rename operations
The default conservative mode blocks risky operations automatically.
中文：
套用變更前，請先審查 Merge Plan view 中的每個項目。特別注意：
manual_review 項目- 高風險檔案
- config files
- lockfiles
- migration files
- delete 或 rename 操作
預設 conservative mode 會自動阻擋高風險操作。
5. Create an Integration Branch / 建立 Integration Branch
English:
Run Safe Rebase AI: Create Integration Branch.
The extension creates a new branch from the target branch. The branch name looks like:
ai-rebase/<source>-onto-<target>-<timestamp>
Example:
ai-rebase/feature-my-work-onto-develop-20260422-120000
This is the only branch where AI-assisted patches are applied. Your original source branch is not modified.
中文：
執行 Safe Rebase AI: Create Integration Branch。
Extension 會從 target branch 建立新的 branch，名稱格式如下：
ai-rebase/<source>-onto-<target>-<timestamp>
範例：
ai-rebase/feature-my-work-onto-develop-20260422-120000
AI 輔助 patch 只會套用在這個 integration branch。原本的 source branch 不會被修改。
6. Apply the Merge Plan / 套用 Merge Plan
English:
Run Safe Rebase AI: Apply Merge Plan.
The extension will:
- Confirm the active branch is the integration branch.
- Request structured patch proposals from the selected AI provider.
- Validate AI output with Zod schemas.
- Reject invalid or ambiguous AI output.
- Enforce the change budget.
- Block restricted files and operations by default.
- Apply unified patches with
git apply.
If a patch is unsafe, the item is left for manual review instead of being applied.
中文：
執行 Safe Rebase AI: Apply Merge Plan。
Extension 會：
- 確認目前 active branch 是 integration branch。
- 向選定的 AI provider 要求結構化 patch proposal。
- 使用 Zod schema 驗證 AI output。
- 拒絕無效或不明確的 AI output。
- 執行 change budget 檢查。
- 預設阻擋受限制的檔案與操作。
- 使用
git apply 套用 unified patch。
如果 patch 不安全，該項目會保留為 manual review，不會被自動套用。
7. Resolve Remaining Manual Items / 處理剩餘 Manual Review 項目
English:
Some conflicts may still require manual work. For those items:
- Open the affected files.
- Review the source and target changes.
- Edit the files manually on the integration branch.
- Keep changes small and reviewable.
- Do not switch back to the source branch while applying fixes.
中文：
有些 conflict 仍可能需要人工處理。對於這些項目：
- 開啟受影響的檔案。
- 比對 source 與 target 的變更。
- 在 integration branch 上手動編輯檔案。
- 保持變更小且容易 review。
- 套用修正時不要切回 source branch。
8. Run Validation / 執行驗證
English:
Run Safe Rebase AI: Run Validation.
The extension runs the configured commands:
Configure these in VS Code settings:
{
"safeRebase.validation.buildCommand": "npm run build",
"safeRebase.validation.testCommand": "npm test",
"safeRebase.validation.lintCommand": "npm run lint"
}
Results are shown in the Validation view.
中文：
執行 Safe Rebase AI: Run Validation。
Extension 會執行已設定的指令：
可在 VS Code settings 中設定：
{
"safeRebase.validation.buildCommand": "npm run build",
"safeRebase.validation.testCommand": "npm test",
"safeRebase.validation.lintCommand": "npm run lint"
}
結果會顯示在 Validation view。
9. Review the Final Diff / 審查最終差異
English:
Before using the integration branch, review the final diff:
git diff develop...HEAD
git status
Replace develop with your actual target branch.
中文：
使用 integration branch 前，請審查最終 diff：
git diff develop...HEAD
git status
請將 develop 替換成你的實際 target branch。
10. Finish the Rebase or Merge Workflow / 完成 Rebase 或 Merge 流程
English:
After validation passes, you can use the integration branch as the reviewed result. Depending on your team workflow, you may:
- compare the integration branch against the target branch
- manually port the resolved changes back into your preferred workflow
- create a PR from the integration branch
- use the integration branch as a safe reference for completing a local rebase
The MVP intentionally does not create PRs or mutate remote branches.
中文：
驗證通過後，你可以把 integration branch 當作已審查的結果。依照團隊流程，你可以：
- 比較 integration branch 與 target branch 的差異
- 手動將解好的變更帶回你的既有流程
- 從 integration branch 建立 PR
- 將 integration branch 當作完成本機 rebase 的安全參考
這個 MVP 刻意不建立 PR，也不修改 remote branch。
11. Roll Back If Needed / 必要時回滾
English:
If the result is not useful, run Safe Rebase AI: Rollback Integration.
This deletes the integration branch for the current session. Your original source branch remains untouched.
中文：
如果結果不符合需求，執行 Safe Rebase AI: Rollback Integration。
這會刪除目前 session 的 integration branch。原本的 source branch 仍然不會被修改。
Safety Checklist / 安全檢查清單
English:
Before applying AI-assisted changes, confirm:
- You are on the intended source branch before analysis.
- You selected the correct target branch.
- An integration branch has been created.
- The active branch is the integration branch before applying patches.
- High-risk items have been manually reviewed.
- Validation commands are configured.
- Final diff has been reviewed.
中文：
套用 AI 輔助變更前，請確認：
- 分析前位於正確的 source branch。
- 已選擇正確的 target branch。
- 已建立 integration branch。
- 套用 patch 前，active branch 是 integration branch。
- 高風險項目已人工審查。
- Validation commands 已設定。
- 已審查最終 diff。
Safety Defaults / 預設安全策略
English:
The default mode is conservative:
- No source branch mutation.
- No delete or rename operations.
- No lockfile, config, or migration mutations.
- High-risk items require manual review.
- Change budget defaults to 10 files, 200 lines per file, and 500 total changed lines.
中文：
預設模式為 conservative：
- 不修改 source branch。
- 不允許 delete 或 rename 操作。
- 不允許修改 lockfile、config file 或 migration file。
- 高風險項目必須人工審查。
- 預設 change budget 為最多 10 個檔案、單一檔案最多 200 行變更、總計最多 500 行變更。
Tests / 測試
npm test
Publishing / 發佈到 VS Code Marketplace
English:
Marketplace publishing instructions are documented in docs/marketplace-publishing.md in this repository. The guide explains how to prepare metadata, create a publisher, configure a Personal Access Token, package a VSIX, inspect it, and publish when ready.
中文：
VS Code Marketplace 發佈流程請參考此 repository 中的 docs/marketplace-publishing.md。該文件說明如何準備 metadata、建立 publisher、設定 Personal Access Token、打包 VSIX、檢查 package，以及在準備完成後發佈。
