workbuddy多仓库关联问题需通过四步解决：一、建立显式仓库关联并锁定版本；二、启用跨仓库符号解析实现智能跳转与类型推导；三、使用引用快照固化依赖状态；四、配置双向变更监听实现api变更自动联动。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您在使用WorkBuddy进行多仓库关联开发时，发现跨项目引用无法自动识别、字段映射失败或依赖更新不同步，则可能是由于仓库间未建立显式逻辑绑定或版本上下文隔离导致。以下是解决此问题的步骤：
一、通过「仓库关联」功能建立跨项目引用关系
该方式在WorkBuddy中模拟Git Submodule与Monorepo混合管理模式，允许主仓库声明对其他已授权仓库的强引用，并支持按分支/标签锁定依赖版本，避免因远程仓库HEAD漂移引发构建不一致。
1、进入工作区，点击左侧导航栏的「代码管理」→「仓库关联」。
2、点击「新增引用」，在弹窗中输入目标仓库的HTTPS克隆地址（如https://git.workbuddy.cloud/team/backend-core.git）或从已连接的Git平台（GitHub/GitLab/企业微信代码库）中选取。
3、在「引用配置」区域指定本地挂载路径（如./libs/backend-core）及绑定分支（如release/v2.3），勾选「启用版本锁定」以生成.lock文件记录确切提交哈希。
4、点击「验证连接」确认凭证有效且具备读取权限，保存后主仓库的package.json或build.gradle中将自动生成对应依赖声明。
二、启用「跨仓库符号解析」实现智能跳转与类型推导
该机制基于LSP（Language Server Protocol）扩展，在编辑器内实时索引被引用仓库的源码结构，使Ctrl+Click可直接跳转至远程仓库定义处，并支持跨仓库接口签名补全与类型校验，消除手动维护.d.ts或stub文件的需要。
1、在主仓库根目录下打开任意TS/JS文件，将光标置于一个来自被引用仓库的导入语句上（如import { AuthService } from '@team/backend-core'）。
2、右键选择「启用跨仓库符号解析」，系统自动扫描所有已关联仓库的tsconfig.json与export入口文件。
3、若检测到类型缺失，弹出提示框询问是否自动注入类型声明路径；点击确认后，.vscode/settings.json中将追加"workbuddy.symbolPaths": ["./libs/backend-core/types"]。
4、重启语言服务，此时对AuthService的方法调用将显示完整JSDoc注释与参数提示，错误检查覆盖跨仓库调用链。
使用 draw.io（.drawio 格式）和 SVG 生成兼容 Microsoft Visio 的架构图。当用户需要以下任一场景时触发： - 用于 Visio 或技术文档的架构/系统/网络图 - 带连接标注的分层控制系统图 - 将 draw.io XML 转换为稳定、可嵌入的 SVG - 修复 Visio 或 draw.io 无法打开的故障排查类图表 - 任何需专业级布局且文本可编辑的图表
三、使用「引用快照」机制固化开发时依赖状态
当多个开发者并行修改主仓库与被引用仓库时，常规引用易因本地未同步导致编译通过但CI失败。引用快照为每个主仓库提交生成被引用仓库的只读镜像副本，确保开发、测试、构建三阶段环境完全一致。
1、在主仓库提交前，执行命令行操作：workbuddy snapshot create --all。
2、系统遍历所有已关联仓库，拉取当前配置的分支HEAD，并压缩为.tar.gz存入./.workbuddy/snapshots/目录，文件名含时间戳与哈希（如backend-core_v2.3_20260410_8a3f9c2.tar.gz）。
3、在CI配置中添加步骤：workbuddy snapshot apply --auto，该命令自动解压匹配快照至对应挂载路径，覆盖当前软链接指向。
4、执行npm run build时，TypeScript编译器实际读取的是快照副本，完全规避远程仓库变更带来的不确定性。
四、配置「双向变更监听」实现跨仓库任务联动
当被引用仓库的关键接口发生BREAKING CHANGE（如删除方法、修改参数类型），主仓库需同步调整调用逻辑。该机制通过解析AST差异并触发预设工作流，自动创建Issue、标记待修复文件、甚至生成迁移脚本草案。
1、进入被引用仓库的「设置」→「变更通知」，开启「对外暴露API变更事件」开关。
2、在主仓库中，点击「自动化」→「新建监听规则」，选择触发源为「关联仓库：backend-core」，条件为「导出成员变更 > 严重等级：BREAKING」。
3、在动作配置中，添加三项操作：① 创建Issue，标题为“[BREAKING] backend-core 接口变更需适配”；② 扫描主仓库中所有调用该成员的文件路径；③ 运行内置脚本workbuddy migrate:api --from=backend-core@v2.2 --to=v2.3。
4、保存规则后，当backend-core推送含BREAKING变更的commit，主仓库的Issues列表将立即出现新条目，关联文件自动高亮标注于IDE侧边栏。
