Kilo Agent Manager 多項目配置架構不可變綁定與版本化寫入的設計實踐【免費下載鏈接】kilocodeKilo is the all-in-one agentic engineering platform. Build, ship, and iterate faster with the most popular open source coding agent.項目地址: https://gitcode.com/GitHub_Trending/ki/kilocodeAgent Manager 為 Kilo 引入多項目管理后Settings 面板的讀寫目標從當前激活項目轉向顯式、不可變、帶版本的綁定契約避免 A 項目的草稿被錯誤寫入 B 項目的配置文件。本文以倉庫內設計規范文檔 .kilo/plans/agent-manager-multi-project-configuration.md 為骨架結合 Kilo 源碼中的綁定實現config-bindings.ts、webview 保存流程config.tsx與后端 overlay 沖突測試config-overlay.test.ts完整講解四層配置存儲的所有權劃分、設置標簽的目標映射、不可變綁定契約、后端 SHA-256 版本校驗與 CAS 寫入以及保證多項目發布的阻塞測試清單。讀完本文你將掌握 Kilo 多項目設置讀寫為何必須綁定目標、校驗版本以及這套契約在擴展端與后端各層的落地方式。背景多項目時代的 Settings 讀寫困境Kilo 當前維護著四個互不相同的配置存儲層存儲示例歸屬VS Code preferencesVS Codesettings.json當前 VS Code 用戶/安裝Kilo user config~/.config/kilo/kilo.json跨項目、跨 Kilo 客戶端的用戶默認值Kilo project configrepo/.kilo/kilo.jsonc倉庫行為與覆蓋項Runtime/session state內存中按目錄限定單個項目、worktree 或會話共享的 Settings 保存路徑目前調用splitConfigByScope()自動切分草稿config-scope.tscommit_message寫入項目配置indexing.enabled寫入項目配置其余通用 Settings 字段寫入用戶配置。問題在于這類隱藏的自動切分并不足以支撐多項目Indexing 標簽雖然提供了顯式的 Global/Project 選擇器卻可以把整個indexing對象寫入任意一層導致 provider/model/vector-store 憑據和基礎設施設置可能被塞進倉庫內的項目配置。而另一些控件autocomplete UI、browser automation、notifications、max auto-approve cost、commit-message 輸出語言、indexing 按鈕可見性則完全繞過 Kilo 配置屬于 VS Code preferences。確認的阻塞缺陷讀有目錄、寫無目標這是當前協議最根本的失效模式——讀取按目錄限定寫入卻沒有綁定到讀取目標KiloProvider.fetchAndSendConfig()解析一個可變的當前目錄發出不帶限定信息的configLoaded狀態KiloProvider.tswebview 持有唯一的 global/project/effective 草稿Agent Manager 把激活項目從 A 切換到 Bwebview 發出不帶限定信息的updateConfigKiloProvider.handleUpdateConfig()在保存時再次解析當前目錄可能把 A 的草稿寫入 BKiloProvider.ts。后端同樣缺少預期目標/版本前置條件外部編輯器或另一個窗口可以在讀取與保存之間覆蓋配置。這是多項目發布的 release blocker。配置所有權策略設計決策是保留用戶設置與項目設置的有用拆分但讓每次 Settings 讀寫的目標顯式、不可變、帶版本并且完全獨立于 Agent Manager 的激活狀態。絕不允許Settings 為項目 A 加載草稿卻從可變的激活項目 B 解析保存目標。VS Code preferences不參與項目配置以下項留在 VS Code settings 中擴展語言與展示偏好autocomplete 的啟用、快捷鍵、provider、modelbrowser automation 的啟用、系統 Chrome/headless 模式通知啟用與聲音最大自動批準成本max auto-approve costcommit-message 輸出語言indexing 禁用時的按鈕可見性多項目功能的啟用開關。Kilo user config個人默認值或安全策略以下項屬于 User 范圍編輯default、small、subagent 模型及變體provider 啟用、自定義 provider、憑據與端點用戶/全局 agent 與默認 agent權限默認值與用戶工具默認值sandbox 策略、網絡訪問、可寫路徑、允許的主機compaction、checkpoint/snapshot、tool-output 默認值用戶名與展示行為sharing、remote control、telemetry、實驗性功能用戶/全局 formatter、LSP、MCP、skills、instructions、commands、workflowsindexing 的 provider、model、憑據、向量存儲與全局調優默認值。可信項目可以在運行時覆蓋其中許多項但在 User 范圍編輯永遠不會寫入這些覆蓋項。Kilo project config倉庫行為以下項描述倉庫行為屬于合法的項目設置commit-message prompt倉庫索引的文件擴展名、include/ignore 規則與有意的項目調優覆蓋倉庫 instructions倉庫 skill 路徑倉庫 commands/workflows可信項目 agent可信項目 MCP servers倉庫 formatter/LSP 覆蓋倉庫 watcher ignores倉庫特定的工具限制與權限請求。項目配置可以覆蓋用戶層的 model/agent/tool 默認值但provider 憑據與削弱安全策略的內容絕不能被靜默寫入倉庫。機器本地的項目索引同意machine-local consent索引啟用本質上是隱私同意consent不是倉庫配置因此必須存到倉庫之外以規范的ProjectId為鍵存入機器本地擴展狀態新觀察到的項目默認索引禁用用戶在本機針對單個項目顯式啟用索引倉庫配置無法開啟索引倉庫配置只能描述索引什么而同意consent決定是否啟動索引規范的項目身份可以防止通過 symlink 或別名路徑繞過同意。有效索引需要同時滿足用戶全局索引配置有效 該項目的機器本地同意。設置標簽與寫入目標映射規范文檔給出了每個 Settings 標簽的正確可編輯目標Settings 標簽正確的可編輯目標Models默認 User顯式 Project 范圍可覆蓋 models/agentsProviders憑據/端點僅 User項目提供的條目需標記來源source-labelledAgent BehaviourUser 或顯式可信 Project 范圍Auto ApproveUser Kilo 配置max cost 仍是 VS Code preferenceBrowserVS Code preferencesCheckpointsUser 默認或顯式 Project 覆蓋DisplayUser 配置AutocompleteVS Code preferencesNotificationsVS Code preferencesContextUser 默認倉庫 watcher/instruction 規則在顯式 Project 范圍Commit MessagePrompt 在 Project 范圍語言仍是 VS Code preferenceIndexingProvider/model/憑據/存儲 在 User啟用走機器本地同意倉庫規則在 ProjectExperimentalUser 配置多項目還鏡像到 VS Code preferenceSandboxing僅 User 配置LanguageVS Code preferenceMCP/Commands/SkillsUser 默認或顯式可信 Project 范圍核心原則任何字段在保存時都不能靜默選擇文件UI 必須展示其 scope。Settings UX顯式范圍與項目選擇器UI 采用顯式 scope 與項目控件Scope: User | Project Project: backend Target: /projects/backend/.kilo/kilo.jsoncUser 范圍永遠指向用戶配置Project 范圍要求顯式選擇可信項目Settings 的項目選擇器與 Agent Manager 的激活項目相互獨立打開 Settings 時可以用當前項目初始化選擇器一次但之后 Agent Manager 的切換不會改變它臟的項目草稿不能遷移到另一個項目選擇器變更必須走 Save、Discard 或 Stay繼承值顯示來源徽標如User、Project: backend、ManagedProject 范圍提供 Override 與 Reset to inherited項目來源的 provider 不能被 User 范圍靜默地從項目配置中刪除。需要特別注意運行時配置與 Settings 目標的分離runtime config 仍精確跟隨會話目錄而 Settings 的 Project 范圍指向注冊的項目根registered project root不是激活的 worktree。worktree 配置編輯屬于需要顯式WorktreeRef的未來獨立功能。不可變綁定契約Immutable Binding ContractSettings 讀取返回一個不透明綁定opaque binding擴展端持有其權威副本interface SettingsBinding { id: string connectionGeneration: number scope: global | project project?: { projectId: string root: string generation: number } directory: string target: { scope: global | project path: string revision: string exists: boolean writable: boolean } }寫入只攜帶該不透明綁定與補丁interface WriteSettingsConfig { type: settingsConfig.write requestId: string bindingId: string set: Recordstring, unknown unset: string[][] }擴展端在寫入時必須拒絕未知/過期的綁定校驗項目存在性、generation 與信任狀態在第一個 await 之前捕獲綁定使用綁定中存儲的 directory 與 scope絕不調用getWorkspaceDirectory()、contexts.active()或使用 worktree/session 回退只在匹配的{ requestId, bindingId }響應中清除草稿。綁定在保存、重連、信任撤銷、項目移除或 context generation 變化后失效。這套契約在倉庫中已經有對應的落地實現config-bindings.ts 中的ConfigBindings類以Mapstring, ConfigBinding保存綁定create()會給每個綁定生成randomUUID()作為 id并在同一 scopedirectory 下丟棄被取代的舊綁定避免只讀刷新導致綁定無限增長get()校驗 id、connection代數以及項目合法性通過validConfigProject回調consume()在寫入成功后刪除綁定一次性語義clear()用于連接級清理。在 KiloProvider.ts 的handleUpdateConfig中擴展端正是通過configBindings.get(globalBindingId / projectBindingId, this.connectionGeneration, ...)來拒絕未知或過期綁定失敗時直接回發configUpdateFailedSettings changed or expired. Reload before saving.。后端版本契約Backend Revision ContractGET /config/overlay必須返回精確的 global/project 目標路徑、解析后的原始目標配置、有效配置/來源元數據以及一個revision。revision 是對規范目標路徑 存在標記 文件精確字節的 SHA-256 指紋。它能捕獲三類變化內容變化文件字節不同JSONC 僅注釋編輯字節不同 → revision 變化目標路徑變化路徑參與指紋。PATCH /config/overlay只接受一個 scope請求體{ scope: global | project set: Recordstring, unknown unset: string[][] expected: { path: string revision: string } }后端必須重新解析權威目標 → 在目標鎖target lock下校驗 path/revision → 修補原始目標層 → 校驗配置 →原子替換文件→ 返回全新快照。后端絕不接受任意的客戶端路徑。預期失敗類型包括過期綁定、未知/不可信項目、目標變化、版本沖突、非法配置、目標不可寫、I/O 失敗——每次失敗都必須保留草稿draft 不丟失。源碼側可以驗證這套契約已被擴展端采用handleUpdateConfig對 global/project 分別調用client.config.overlayUpdate(...)并攜帶directory: globalBinding!.directory與expected: { path, revision }寫入成功后再consume()綁定并回發configUpdatedKiloProvider.ts。版本沖突的測試證據config-overlay.test.ts 印證了 revision 契約的關鍵語義目標請求會自動回填expected: { path, revision }測試夾具層缺失文件具有穩定的 revision對同一不存在的項目配置連續兩次取 targetrevision 相同保存后 revision 必然變化僅注釋的外部編輯會被判為版本沖突先讀取 overlay讓外部把文件改成僅注釋不同的內容再用舊的expected提交 PATCH返回code: revision-conflict——這正是外部編輯器覆蓋讀-寫窗口這一阻塞缺陷的回歸防護項目 scope 支持按路徑unset如[[indexing, enabled]]并驗證保存后該字段確實從原始層消失而其余字段provider、ollama baseUrl保留。實施清單從協議到代碼的九項改造規范文檔要求落地以下九項為 Kilo 配置 overlay API 增加帶版本的 target 描述符與 compare-and-swap 寫入把與激活綁定的 runtime config 狀態與按綁定鍵控的 Settings 編輯器狀態分離用攜帶 request/binding ID 的 settings 讀/寫消息替換不帶限定的configLoaded/updateConfig用每個可編輯控件上的顯式 scope 替換隱藏的splitConfigByScope保存把 Indexing 的 Project 范圍限制為倉庫規則provider/model/憑據/存儲留在 User 范圍把索引啟用從項目配置遷移為按規范ProjectId鍵控的機器本地同意默認關閉審計保存條之外的直接配置修改者provider disconnect、imports/resets、自定義 provider、work styles、權限規則、索引操作讓 Open Project Config 接受ProjectRef解析不可變的注冊根并校驗信任按 scope、directory、target、revision 與 activation generation 分區配置緩存/事件。當前倉庫中第 13 項的擴展端骨架已經可見webview 端 config.tsx 維護bindings()global/project 兩個 binding、globalDraft/projectDraft分區草稿、configBindingExpired處理項目變化時提示 Discard or reload before saving、configUpdateFailed的部分成功處理按completedScopes保留未完成部分的草稿saveConfig()已把globalBindingId/projectBindingId隨updateConfig消息發送但仍在使用splitConfigByScope做隱藏切分——這正是實施清單第 4 項要繼續消除的部分。config-scope.ts中PROJECT_SCOPED_KEYS目前只有commit_message一個頂層鍵也印證了自動切分過于粗糙的現狀。阻塞測試清單Blocking Tests多項目配置可以發布的前提是以下測試全部通過為 A 加載 Settings切換到 B保存只有 A 綁定的目標發生變化同一測試在 A/B 的 worktree 與會話選擇下成立User 范圍保存只改用戶配置Project 范圍保存要求顯式可信項目且只改其注冊根配置臟草稿在 Agent Manager 切換后存活且不能遷移到其他 Settings 項目亂序的讀/寫只更新匹配的 request/binding外部文件修改觸發版本沖突但不丟失草稿配置目標路徑變化觸發目標沖突項目移除、generation 變化或信任撤銷會使綁定過期表單中的 indexing provider/model/憑據/存儲永不進入項目配置倉庫文件中出現indexing.enabled: true不能授予索引同意新項目默認索引禁用直到在本機顯式啟用同意跟隨規范項目身份跨越 symlink/路徑別名且絕不泄漏到另一項目commit_message.prompt與倉庫索引規則仍支持顯式項目寫入runtime worktree 配置使用 worktree 目錄而 Project Settings 仍綁定注冊項目根。發布門檻Release Gate在多項目默認關閉disabled by default之前必須完成不可變綁定/版本契約與上述阻塞測試。規范同時強調保留而非移除現有的項目本地行為——只是其寫入目標必須變為顯式且不可變。這既保護了現有用戶既有的repo/.kilo/kilo.jsonc工作流又為 Agent Manager 的多項目切換提供了確定性的讀寫語義讓Settings 草稿寫錯項目這類數據污染問題從架構上不再可能發生。小結Kilo 多項目配置架構的核心是把 Settings 從面向當前目錄的共享草稿重構為綁定目標 版本校驗的 CAS 寫入所有權上嚴格區分 VS Code preferences、用戶配置、項目配置與機器本地索引同意四層讀寫協議上引入不透明綁定與 SHA-256 revision讓擴展端無法在寫入時重新解析目標讓后端在目標鎖下原子替換文件并拒絕任何版本不一致的寫入測試上以跨項目切換不串寫、外部編輯觸發版本沖突、索引同意默認關閉且不可由倉庫授予等阻塞用例鎖死行為。這一契約在 .kilo/plans/agent-manager-multi-project-configuration.md 中定義在 config-bindings.ts、KiloProvider.ts、config.tsx 與 config-overlay.test.ts 中逐步落地感興趣的讀者可以沿著這條鏈路繼續深入。【免費下載鏈接】kilocodeKilo is the all-in-one agentic engineering platform. Build, ship, and iterate faster with the most popular open source coding agent.項目地址: https://gitcode.com/GitHub_Trending/ki/kilocode創作聲明：本文部分內容由AI輔助生成（AIGC），僅供參考