Kiln 项目 Git 重新导入恢复的后端实现：remove_conflicting_id 与共享注销机制详解

人工智能AI 应用AI 评测RAG微调提示工程开发工具桌面应用【免费下载链接】KilnBuild, Evaluate, and Optimize AI Systems. Includes evals, RAG, agents, fine-tuning, synthetic data generation, dataset management, MCP, and more.项目地址https://gitcode.com/gh_mirrors/ki/Kiln点击查看免费下载导读本文围绕 Kiln 开源仓库中 git_auth_recovery 项目 的Phase 2后端 Git 重新导入恢复展开讲解如何通过提取共享的项目注销助手remove_project_from_config/_deregister_project并新增remove_conflicting_id标志让移除冲突项目并重新导入的恢复流程在后端落地。读完本文你将掌握 Kiln 三层架构下仅注销配置与注销配置 运行时注册表两种移除语义的区别理解POST /api/git_sync/save_config的 409 冲突处理路径并能对照源码与测试用例独立追踪这条恢复链路。1. 问题背景为什么需要重新导入恢复链路根据 project_overview.md 的记载Kiln 用户曾遇到一个不可恢复的错误状态某个项目通过 Git 同步当 Git 凭据Credentials过期后任务选择器task picker依赖的/tasksAPI 直接报错。原始错误被包装成了{detail: Cannot sync with remote. Check your connection.}——一个连通性提示掩盖了真实的认证失败原因同时前端把该对象渲染成Tasks failed to load: [Object object]用户既看不懂原因、也没有出路。更致命的是恢复路径被堵死当用户只有一个项目时应用会重定向到/setup/select_task而该页面没有移除项目 / 重新导入 / 重新认证的任何入口而重新导入又会因为你已经有一个相同 ID 的项目DuplicateProjectError被拒绝形成死锁。为此functional_spec.md 与 implementation_plan.md 将整个恢复方案拆成四个阶段阶段主题说明Phase 1错误封装 认证错误分类后端中间件错误体{detail: ...}→{message: ...}新增GitAuthError在GitSyncManager.fetch()中对 401/403 等认证类 pygit2 错误做分类并在ERROR_MAP中映射为 HTTP 401Phase 2Git 重新导入恢复后端本文主题共享注销助手 remove_conflicting_id打通save_config的先注销冲突、再保存新克隆路径Phase 3恢复 UI前端任务选择器错误态的Re-import project?链接、GitSyncRequestError类型化错误、导入向导末步的红色Remove existing and re-sync按钮Phase 4本地文件夹导入对等POST /api/import_project增加remove_conflicting_id查询参数本地导入获得与 Git 路径一致的重试能力本文严格聚焦Phase 2同时会引用 Phase 1 的GitAuthError分类与 Phase 3/4 的前端/对等实现作为上下文佐证详见 phase_1.md、phase_3.md、phase_4.md。2. 分层架构与设计约束为什么移除逻辑要拆成两层在展开具体代码前必须先理解 architecture.md 强调的分层约定。Kiln 的 Git 同步相关代码横跨三个层次且依赖只能自上而下流动libs/corekiln_ai持久的用户配置Configprojects列表、git_sync_projects字典与项目工具函数。它不知道任何运行时管理器。libs/serverkiln_server核心 REST API包括POST /api/import_project与custom_errors异常处理器。app/desktopgit_syncGit 同步中间件、GitSyncManager、GitSyncRegistry内存中的管理器 后台同步以及 Git 同步 APIsave_config、delete_project。由此推导出一个关键结论移除项目中涉及持久化配置的那部分必须放在libs/core这样libs/server本地导入与app/desktopgit 的save_config、delete_project两处都能调用运行时注册表拆除那部分则是app/desktop在核心助手之上包的一层异步包装。这正是 Phase 2 设计的骨架。此外git_sync_api.py 中的delete_project端点路径刻意放在/api/delete_project/{project_id}而非/api/projects/*源码注释git_sync_api.py写明该路径刻意避开GitSyncMiddleware的拦截因为删除只更新 Kiln 配置、不涉及任何 Git 操作即使在 Git 凭据已失效时也必须能成功执行——这是恢复链路可行性的前提之一。3. 核心助手一remove_project_from_config配置层Phase 2 的第一步是在 project_utils.py 中新增remove_project_from_config。其职责是从Config.shared().projects列表中移除该项目路径并从Config.shared().git_sync_projects字典中移除对应条目若该项目是 Git 同步项目则返回其clone_path否则返回None。def remove_project_from_config(project_path: str) - str | None: Remove a project from Kiln config. Does NOT delete files from disk. Returns the git-sync clone_path if the project was git-synced, else None. projects Config.shared().projects or [] Config.shared().save_setting(projects, [p for p in projects if p ! project_path]) git_sync Config.shared().git_sync_projects or {} clone_path None if project_path in git_sync: clone_path git_sync[project_path].get(clone_path) git_sync.pop(project_path) Config.shared().save_setting(git_sync_projects, git_sync) return clone_path逐段解读其行为与设计意图仅操作持久化配置它只调用Config.shared().save_setting(...)写回projects与git_sync_projects两个配置项不触碰任何运行时对象GitSyncManager、BackgroundSync也不会删除磁盘上的任何文件。文档字符串第一句就明确了这条不变量Does NOT delete files from disk.对None的容错Config.shared().projects or []与git_sync_projects or {}保证配置项尚未初始化时也能安全执行。返回值即是否 Git 同步的判据clone_path取自git_sync_projects[project_path][clone_path]。调用方上层_deregister_project正是依据返回值决定是否要做运行时注册表拆除。幂等性如果传入路径本就不在配置中projects列表过滤后内容不变、git_sync字典中也没有该键函数依然正常返回None——这是恢复流程中标志位无冲突时是 no-op的基础。底层数据结构可从 config.py 印证projects是项目文件路径列表git_sync_projects被声明为ConfigProperty(dict, default_lambdalambda: {}, sensitive_keys[pat_token, oauth_token])config.py即该字典中存有 PAT/OAuth 令牌这类敏感字段写入配置时会受到脱敏处理。配套的单测位于 test_project_utils.py 的TestRemoveProjectFromConfig类覆盖四个分支test_removes_project_and_git_sync同时更新projects与git_sync_projects并返回clone_pathtest_non_git_synced_project非 Git 同步项目返回None仅更新projectstest_missing_project_is_idempotent路径不在配置中时行为幂等不抛异常test_none_projects_listprojects/git_sync_projects为None时安全兜底。4. 核心助手二_deregister_project应用层包装第二步是在 git_sync_api.py 中新增_deregister_project。它是完整的应用层移除操作先调用核心助手下沉配置再根据返回的clone_path决定是否需要拆除运行时注册表async def _deregister_project(project_path: str) - None: Remove a project from config and unregister its git-sync manager. clone_path remove_project_from_config(project_path) if clone_path is not None: await GitSyncRegistry.unregister(Path(clone_path))其中GitSyncRegistry.unregisterregistry.py负责停止该路径的后台同步并关闭其 Git 执行器classmethod async def unregister(cls, path: Path) - None: Stop background sync and remove the manager for *path*. Idempotent: calling on an unregistered path is a no-op. resolved path.resolve() with cls._lock: bg_sync cls._background_syncs.pop(resolved, None) manager cls._managers.pop(resolved, None) if bg_sync is not None: await bg_sync.stop() if manager is not None: manager._git_executor.shutdown(waitFalse)这个设计体现了清晰的职责分层层次函数职责所在层配置层remove_project_from_config从projects/git_sync_projects中移除条目返回clone_pathlibs/core注册表层GitSyncRegistry.unregister停止后台同步、关闭 Git 执行器、移除内存管理器app/desktop应用层组装_deregister_project先配置后注册表按需串联app/desktop5. 重构delete_project复用共享助手外部契约不变第三步是把现有delete_project端点内联的配置移除逻辑替换为对_deregister_project的调用。重构后的实现git_sync_api.pyapp.delete( /api/delete_project/{project_id}, summaryDelete Project, tags[Projects], openapi_extraDENY_AGENT, ) async def delete_project( project_id: Annotated[ str, FastAPIPath(descriptionThe unique identifier of the project.) ], ) - dict: Removes the project from Kiln but does not delete the files from disk. project project_from_id(project_id) await _deregister_project(str(project.path)) return {message: fProject removed. ID: {project_id}}要点行为零变化此前delete_project的内联逻辑正是移除projects条目 移除git_sync_projects条目 注销GitSyncManager对应 functional_spec.md 中 C.3 的表述the body ofdelete_projectfactored into a shared helper现在被原样抽取为共享助手因此对外响应形状与状态码不变成功返回{message: fProject removed. ID: {project_id}}项目不存在时由project_from_id抛 404。两条路径共用一个实现设置页的移除项目与恢复流程中的先注销冲突项目现在共享同一份注销代码避免语义漂移。配套测试见 test_git_sync_api.pytest_delete_project_success、test_delete_project_cleans_up_git_sync验证 Git 同步项目的注销、test_delete_project_not_found验证 404 分支。6.SaveConfigRequest新增remove_conflicting_id字段第四步是为POST /api/git_sync/save_config的请求模型SaveConfigRequest增加可选布尔字段。Pydantic 模型定义git_sync_api.py中该字段的完整形态class SaveConfigRequest(BaseModel): Request to save a complete git sync configuration for a project. project_id: str Field(descriptionUnique project identifier.) project_path: str Field( descriptionRelative path to the project.kiln file within the clone. ) git_url: str Field(descriptionThe git remote URL.) clone_path: str Field(descriptionLocal filesystem path of the clone.) branch: str Field(descriptionBranch name to sync.) remote_name: str Field(defaultorigin, descriptionGit remote name.) pat_token: str | None Field(defaultNone, ...) oauth_token: str | None Field(defaultNone, ...) auth_mode: Literal[system_keys, pat_token, github_oauth] Field( defaultsystem_keys, ... ) sync_mode: Literal[auto, manual] Field(defaultauto, ...) remove_conflicting_id: bool Field( defaultFalse, descriptionWhen true and a duplicate project ID conflict is detected, remove the existing project registration before saving., ) trusted: bool Field( defaultFalse, descriptionMust be true to confirm trust before importing. Kiln projects can contain code that runs on your machine., )字段语义小结字段类型默认值含义project_idstr—项目唯一标识project_pathstr—project.kiln在克隆内的相对路径必须是相对路径见下文校验git_url/clone_path/branchstr—Git 远端 URL、本地克隆路径、同步分支remote_namestroriginGit 远端名称pat_token/oauth_tokenstr \| NoneNonePAT 或 OAuth 令牌auth_mode字面量system_keys认证方式system_keys/pat_token/github_oauthsync_mode字面量auto同步模式auto/manualremove_conflicting_idboolFalse检测到重复项目 ID 冲突时先移除已有项目注册再保存trustedboolFalse必须为true才能导入Kiln 项目可能包含在本机运行的代码值得注意的是trusted字段api_save_config的第一步就是校验trustedgit_sync_api.py不通过直接返回 400。同时端点还会校验clone_path必须位于默认项目目录内、project_path必须是相对路径且不得越出克隆目录_validate_clone_path与路径逃逸检查git_sync_api.py、git_sync_api.py这些是恢复链路得以安全落地的既有护栏。7.api_save_config的冲突处理先注销、后保存第五步也是最核心的一步是改造api_save_config的重复项目处理逻辑。完整实现git_sync_api.pyasync def api_save_config(request: SaveConfigRequest) - GitSyncConfigResponse: if not request.trusted: raise HTTPException( status_code400, detailImport cancelled: you must confirm you trust this project before importing. Kiln projects can contain code that runs on your machine., ) _validate_clone_path(request.clone_path) if Path(request.project_path).is_absolute(): raise HTTPException( status_code400, detailproject_path must be a relative path within the clone, ) clone_root Path(request.clone_path).resolve() resolved_project (clone_root / request.project_path).resolve() if not str(resolved_project).startswith(str(clone_root) os.sep): raise HTTPException( status_code400, detailproject_path must not escape the clone directory, ) full_project_path str(resolved_project) try: check_duplicate_project_id(request.project_id, full_project_path) except DuplicateProjectError as e: if not request.remove_conflicting_id: raise HTTPException(status_code409, detailstr(e)) conflicting project_from_id_core(request.project_id) if conflicting is not None: await _deregister_project(str(conflicting.path)) project_config GitSyncProjectConfig(...) save_git_sync_config(full_project_path, project_config) add_project_to_config(full_project_path) return GitSyncConfigResponse(...)7.1 冲突从何而来check_duplicate_project_id重复检测由 project_utils.py 的check_duplicate_project_id完成。它遍历Config.shared().projects逐个加载project.kiln比对project.id并区分两种冲突def check_duplicate_project_id(project_id: str, new_project_path: str) - None: project_paths Config.shared().projects if project_paths is None: return new_resolved str(Path(new_project_path).resolve()) for existing_path in project_paths: try: project Project.load_from_file(existing_path) except Exception: continue if project.id ! project_id: continue existing_resolved str(Path(existing_path).resolve()) if existing_resolved new_resolved: raise DuplicateProjectError( This project is already imported., same_pathTrue, ) else: raise DuplicateProjectError( fYou already have a project with this ID. You must remove project {project.name} before adding this., same_pathFalse, )DuplicateProjectErrorproject_utils.py携带same_path布尔属性用于区分同路径重复导入与不同路径但 ID 相同。重新导入恢复只针对same_pathFalse的场景因为向导总是克隆到全新目录旧克隆从未被覆盖。7.2 两个分支的行为remove_conflicting_idFalse默认直接raise HTTPException(status_code409, detailstr(e))行为与改造前完全一致——这正是测试test_remove_conflicting_false_still_409要守护的默认行为不变。remove_conflicting_idTrue且检测到冲突通过project_from_id_core(request.project_id)解析冲突项目——由于冲突项目与request.project_id共享同一 ID这正是它冲突的原因所以用请求中的 ID 就能定位到它调用await _deregister_project(str(conflicting.path))完成配置移除 注册表拆除不 return、不 break而是继续落入下方的正常保存路径save_git_sync_config(full_project_path, project_config)写入新的 Git 同步配置add_project_to_config(full_project_path)将新克隆注册进projects列表。从 functional_spec.md 的表述看这一步的净效果等价于删除项目 保存配置两个既有 API 调用被原子地合并为一次请求恢复路径没有发明任何新的移除语义而是完全复用了delete_project的仅注销行为。7.3 两个值得注意的实现细节project_from_id_core与project_from_id的区分git_sync_api.py 同时导入了两个同名函数——kiln_ai.utils.project_utils.project_from_id重命名为project_from_id_core纯 core 实现与kiln_server.project_api.project_from_id。前者用于冲突解析只依赖Config遍历后者用于delete_project的既有逻辑。这种显式命名区分了两个层次的同源函数避免了导入遮蔽。GitSyncManager的注销异步性_deregister_project是async函数因为GitSyncRegistry.unregister需要await bg_sync.stop()优雅停止后台同步。而配置层助手remove_project_from_config是纯同步的这正好对应持久化配置同步完成、运行时拆除异步协调的分层特性。8. 边界情况与错误处理策略Phase 2 的设计在 functional_spec.md 的 Edge cases error handling 一节有系统性论述结合源码可归纳为remove_conflicting_idTrue但实际无冲突check_duplicate_project_id根本不会抛异常标志位是no-op保存正常继续。对应测试test_remove_conflicting_no_conflict_is_nooptest_git_sync_api.py。冲突项目在 config 中已不存在project_from_id_core返回None跳过注销直接落入保存路径同样安全对应test_remove_conflicting_project_not_found_still_savestest_git_sync_api.py。same_path重复This project is already imported重新导入流程中不会出现总是克隆到新路径即便出现移除同路径注册再重新注册同一路径也只是良性 re-register。旧克隆文件保留在磁盘上这是有意的设计——与delete_project的不删除文件保证一致避免误删未推送的本地提交。项目 ID 保持稳定项目 ID 存储在仓库内的project.kiln中重新导入后 ID 不变因此用户持久化的选择ui_state.current_project_id在恢复后依然能解析不会出现悬空的选中状态。9. 测试矩阵Phase 2 的验证闭环Phase 2 规划的测试清单phase_2.md 的 Tests 一节与仓库中的实际测试一一对应构成完整的验证闭环规划中的测试实际实现test_git_sync_api.py / test_project_utils.py验证点test_remove_project_from_config_removes_project_and_git_syncTestRemoveProjectFromConfig.test_removes_project_and_git_sync两个配置项同时更新、返回clone_pathtest_remove_project_from_config_non_git_syncedtest_non_git_synced_project非 Git 同步返回Nonetest_remove_project_from_config_missing_projecttest_missing_project_is_idempotent路径不在配置中时幂等test_delete_project_uses_shared_helpertest_delete_project_success/test_delete_project_cleans_up_git_syncdelete_project走共享助手且响应不变test_save_config_remove_conflicting_deregisters_and_savestest_remove_conflicting_deregisters_and_savestest_git_sync_api.py完整流程remove_conflicting_idTrue时注销旧项目并保存成功test_save_config_remove_conflicting_false_still_409test_remove_conflicting_false_still_409L1309-L1336默认行为不变仍返回 409test_save_config_remove_conflicting_no_conflict_is_nooptest_remove_conflicting_no_conflict_is_noopL1338-L1361无冲突时标志位是 no-op以最核心的test_remove_conflicting_deregisters_and_saves为例它通过 mock 依次验证了整条调用链test_git_sync_api.pycheck_duplicate_project_id被模拟为抛出DuplicateProjectErrorsame_pathFalseproject_from_id_core返回conflicting_project路径为/old/clone/project.kiln请求体携带remove_conflicting_id: True与trusted: True断言最终响应为 200且remove_project_from_config被以/old/clone/project.kiln调用、GitSyncRegistry.unregister被以Path(/old/clone)异步调用——精确锁定了配置层 注册表层的双重注销。10. 与上下游的衔接从后端到前端、再到本地导入Phase 2 是整条恢复链路的后端主干理解它需要知道它与前后阶段的衔接点10.1 上游Phase 1 的认证错误分类恢复的信号源恢复动作之所以能触发前提是认证错误能被准确识别。Phase 1 在 git_sync_manager.py 的fetch()中实现了分类async def fetch(self) - None: try: await self._run_git(self._fetch_sync) except pygit2.GitError as e: if _is_auth_error(e): raise GitAuthError(fGit authentication failed: {e}) from e raise RemoteUnreachableError(fCannot sync with remote: {e}) from e_is_auth_error基于 git_sync_manager.py 的标记元组做最佳努力匹配_AUTH_ERROR_MARKERS ( authentication, authoriz, credential, 401, 403, too many redirects, invalid username or password, password authentication, ) def _is_auth_error(e: Exception) - bool: msg str(e).lower() return any(marker in msg for marker in _AUTH_ERROR_MARKERS)随后 middleware.py 的ERROR_MAP将GitAuthError映射为 HTTP 401 与提示文案 Git authentication failed or expired. Re-import the project to reconnect with fresh credentials.。前端拿到这条准确信息后才会引导用户走重新导入路线最终命中 Phase 2 的remove_conflicting_id。10.2 下游Phase 3 的前端对接后端契约就绪后前端在 api.ts 中做了三件事详见 phase_3.md手写的request()助手改为抛出带状态码的类型化错误export class GitSyncRequestError extends Error { status: number constructor(message: string, status: number) { super(message) this.name GitSyncRequestError this.status status } } export function is_duplicate_project_error(e: unknown): boolean { return e instanceof GitSyncRequestError e.status 409 }saveConfig的类型增加可选remove_conflicting_id透传到 POST body。导入向导末步 step_complete.svelte 将保存逻辑抽取为run_save(remove_conflicting_id false)L48-L89在 catch 中通过is_duplicate_project_error(e)识别 409并渲染红色按钮L130-L132{#if is_conflict} button classbtn btn-error btn-outline on:click{() run_save(true)} Remove existing and sync /button {/if}同时任务选择器 select_tasks_menu.svelte/select_tasks_menu.svelte) 在错误态L236-L251渲染准确的错误文案与低强调的 Re-import project? 链接其目标地址通过import_project_urlprop 按上下文注入setup 全屏场景为/setup/import_project应用内侧边栏为/settings/import_project。10.3 对等扩展Phase 4 的本地文件夹导入由于恢复导航落在通用的导入方式选择页用户可能选Local Folder而非Git Auto Sync因此 project_api.py 的POST /api/import_project也增加了同名查询参数走同一个 core 助手except DuplicateProjectError as e: if not remove_conflicting_id: raise HTTPException(status_code409, detailstr(e)) # Resolve and de-register the conflicting project before proceeding. # Layering caveat: libs/server cannot call GitSyncRegistry.unregister # (app layer), so if the removed project was git-synced and had a live # manager this session, its in-memory manager lingers until restart. conflicting project_from_id_core(project.id) if conflicting is not None: remove_project_from_config(str(conflicting.path))源码注释明确记录了分层告诫layering caveatlibs/server无法调用GitSyncRegistry.unregister应用层如果被移除的冲突项目恰好是 Git 同步且本会话存在活跃管理器其内存中的管理器/后台同步会一直残留到重启。这是本地文件夹导入的罕见边界可接受但必须文档化——而 Git 路径_deregister_project则能做完整的注册表拆除。这再次印证了第 2 节的三层依赖约定。11. API 合同变更汇总综合 functional_spec.md 的 API contract changes 一节Phase 2 及其衔接阶段带来的 API 层面变化如下端点变更POST /api/git_sync/save_configSaveConfigRequest新增可选字段remove_conflicting_id: bool False。为true且存在同 ID 不同路径的重复项目时先注销冲突项目文件留在磁盘再继续保存POST /api/import_project新增可选查询参数remove_conflicting_id: bool False语义同上Phase 4本地文件夹对等GitSyncMiddleware错误响应错误体由{detail: ...}统一改为{message: ...}Phase 1状态码不变Git 同步读错误经中间件新增GitAuthError→ HTTP401及认证专用文案既有RemoteUnreachableError(503)、SyncConflictError(409)、WriteLockTimeoutError(503)、CorruptRepoError(500) 不变DELETE /api/delete_project/{project_id}外部契约不变实现重构为共享助手_deregister_project12. 总结一条可独立追踪的恢复链路Phase 2 的价值不在于新增复杂逻辑而在于把既有行为正确地抽离与复用。回顾整条链路配置层助手remove_project_from_config下沉到libs/core成为仅注销配置的唯一事实来源应用层包装_deregister_project补上运行时注册表拆除delete_project与恢复路径共用同一实现SaveConfigRequest.remove_conflicting_id让api_save_config在 409 冲突时走解析冲突 → 注销 → 落回正常保存的原子路径以project_id不变、旧克隆保留、标志位幂等为三大不变量配合test_git_sync_api.py与test_project_utils.py的完整测试矩阵保证默认行为零回归上游 Phase 1 提供准确的GitAuthError信号下游 Phase 3/4 将恢复能力交付到 Git 与本地两条导入路径的 UI。如果读者想深入验证或继续追踪建议依次阅读phase_2.md本阶段计划→ architecture.md分层设计→ functional_spec.md完整行为契约→ project_utils.py 与 git_sync_api.py核心实现→ test_git_sync_api.py 与 test_project_utils.py测试闭环。赞分享人工智能AI 应用AI 评测RAG微调提示工程开发工具桌面应用【免费下载链接】KilnBuild, Evaluate, and Optimize AI Systems. Includes evals, RAG, agents, fine-tuning, synthetic data generation, dataset management, MCP, and more.项目地址https://gitcode.com/gh_mirrors/ki/Kiln点击查看免费下载相关推荐Kiln 内置 LLM 工具详解llm 与 llm_judge 的实现、注册表接线与 run_llm_call 共享调用链Kiln 内置 LLM 工具详解llm 与 llm_judge 的实现、注册表接线与 run_llm_call 共享调用链 本文以 Kiln 项目中 Cod人工智能AI 应用AI 评测RAG微调提示工程开发工具桌面应用MLOpsKiln 前端实战将 chat.svelte 重构为纯 UI 组件并接入共享 ChatSessionStoreKiln 前端实战将 chat.svelte 重构为纯 UI 组件并接入共享 ChatSessionStore 本文围绕 Kiln 仓库中 Chat Sess人工智能AI 应用AI 评测RAG微调提示工程开发工具桌面应用MLOps深入解析UE4SSHook注册与注销机制的设计与实现深入解析UE4SSHook注册与注销机制的设计与实现 引言为何Hook机制是UE4SS的核心 你是否曾在Unreal Engine虚幻引擎简称UE游戏游戏开发逆向工程上一篇Grafana Tempo 可观测性指南四大支柱、Trace 关联机制与落地实践下一篇LeetCode 73 Set Matrix Zeroes 全解从 O(m·n) 空间暴力法到 O(1) 原地标记leetcode 仓库多语言实现创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考