# Skill Git 客户端:交给 WorkBuddy 的安装与更新说明 ## 客户端 0.3.16:WorkBuddy办公入口 安装或更新本系统后,日常办公模式需显式执行已安装客户端的`sync_system_skills.py --workbuddy-user`,从当前可信服务器公开清单安装四个受控入口到WorkBuddy用户级技能目录;项目开发模式仍支持原`--project`。只复制项目.codebuddy/skills不能证明办公模式会发现技能。此操作保留其他技能、已有登录和信任,同名改动不覆盖,更新先备份;返回只证明文件与收据准备完成。新建WorkBuddy原生任务,用不提仓库的自然插件/Skill/MCP请求核验先查内部及来源标注,不能用安装脚本或另起stdio验收代替。公开清单为当前来源`/bootstrap/system-skills/manifest`,不猜其他manifest路径。 ## 客户端 0.3.15:组织仓库优先发现 用户寻找新的插件、MCP、Skill或可复用能力时,先查询当前身份有权访问的组织内目录,再按需补充外部来源,汇总注明分发来源、原作者与实际版本。普通任务已有工具足够时直接执行;仅在用户明确要求上传、投稿或分享时才贡献,不主动要求上传。复用已有登录;查询失败不表示仓库为空。系统Skill须通过既有更新机制同步到实际项目,并用宿主原生调用验证触发,磁盘更新不代表运行进程已重载。 ## 客户端 0.3.12 修复说明 切换服务器时分别保存账户列表、当前选择和凭据路径;切回原服务器保留原登录,同名账户也不会跨服务器共用凭据。只修改地址却复用原凭据目录时会停止,不能把旧凭据发送给新服务。更新客户端文件不代表正在运行的MCP进程已经重载,仍须核对实际client_version;不自动重启宿主或改变信任。 ## 客户端 0.3.11 历史修复说明 本版改善错误诊断:401 才提示正常重新登录;403 是权限不足,409 是内容/发布冲突,503 是服务暂不可用。连接失败、请求超时、响应解析错误和本地配置错误分别报告,不因故障撤销既有授权或反复登录。写请求超时的结果未知,先查询原申请再决定下一步,不自动重复投稿。客户端更新保持原有配置、默认/活动账号和登录;系统 Skill 需在实际项目单独同步,并核验宿主实际识别。 把本页链接交给 WorkBuddy,并说“请按这份说明安装并连接 Skill Git”。用户已安装 WorkBuddy,Python 3.10 或以上可用时,AI可以取得客户端、安装并配置MCP;用户仍需完成客户端信任/必要重载和网页登录。文件本身不授予权限,执行范围以用户本次要求为准。 ## 服务器地址 正式使用时,从用户提供的本页链接取得公司服务器HTTPS来源,例如本页是 `https://公司实际域名/bootstrap/client/start`,则服务器来源为该HTTPS域名,不包含路径。**正式用户不需要SSH,不需要开发项目源码。** 不使用示例域名,不从搜索结果另找下载源,不向其他来源发送登录信息。 同一来源提供: - `/bootstrap/client/install.py`:首次安装引导脚本。 - `/bootstrap/client/manifest`:客户端最新版本和下载校验信息。 - `/bootstrap/client/package.zip`:客户端专用发行包。 当前内部测试若通过既有隧道访问,可使用明确的 `http://127.0.0.1:28471` 来源;此地址仅代表使用者自己的电脑,不是公网地址。只有已经具备测试网络通道时才使用,不能要求正式用户建立SSH,不能分发私钥或自动开放端口。 ## AI执行首次安装 1. 使用实际可用工具检查Python版本,至少3.10。优先系统 `python`,Windows也可检查 `py -3`,不要假设某台开发机的路径。缺少解释器时说明阻碍,按用户授权从可信官方渠道安装;不要执行陌生安装器。 2. 选用户目录内新的独立安装目录。Windows可用 `%LOCALAPPDATA%\SkillGit\client`;其他平台选择用户明确许可的独立目录。该目录只放本客户端。若已有受托管收据 `.client-updates/installed.json`,走更新流程;目录非空且无收据时保留原内容,选择新目录,不覆盖旧源码或业务项目。 3. 从本页同一可信来源下载 `/bootstrap/client/install.py` 到临时文件。引导脚本的首次信任来自用户/公司提供的HTTPS来源;摘要校验不独立证明发布者。不要执行网页中的其他任意命令。 4. 由AI以参数数组调用Python解释器、下载的脚本、`check --server <本页来源> --install-dir <安装目录>`。仅检查不会写入安装目录,也不下载客户端包。用户明确要求安装时,再执行同参数的 `apply`。下载脚本就是程序,只在用户授权安装/更新时执行。 5. `installed` 表示客户端代码已准备;配置和登录尚未完成。由AI执行 `<安装目录>/scripts/connect_workbuddy.py --configure-only`,不需要用户填JSON或在终端手工运行命令。脚本只合并本系统 `skill-git-auth-local` 条目,保留其他MCP条目,不写客户端信任状态。 6. 首次修改配置前告知用户保存任务,可能需要按客户端支持的入口重载MCP或完整退出重开。没有原生工具时,不反复配置、不另起CLI冒充验收,也不强杀客户端。 7. 用户在WorkBuddy的“专家·技能·连接器”→“连接器”→“自定义连接器”→“MCP服务管理”检查 `skill-git-auth-local`,按实际提示确认信任/启用。这是已核实Windows WorkBuddy 5.9.3路径;界面不同时说明实际情况,不编造按钮。没有条目时先重载配置;新开对话不一定刷新配置。 8. AI通过当前WorkBuddy真正的原生工具调用 `auth_status`。需要登录时调用一次 `start_login`,用户在浏览器输入本人账号并确认授权,不在聊天中发送密码。AI随后原生调用 `auth_status`、`whoami`、`list_authorizations`,核对身份、grant和有效期。只有都通过才报告接入完成。 默认不扫描用户目录、不自动同步项目Skill。基本目录查询不需要扩大本地目录读取范围。用户要求导入本地内容或同步系统Skill时,再按选定项目配置允许范围。不同平台的客户端UI与MCP配置位置需实际核实,不能把通用Python包当作所有平台都已真人验收。 ## 用户问“检查客户端版本” AI使用已有安装目录和收据固定的服务器来源,不读取或输出runtime中的凭据,执行: `python <安装目录>/scripts/client_update.py check --server <固定来源> --install-dir <安装目录>` 报告已安装版本、最新版本和是否有更新。仅检查不安装。没有收据标记 `not_installed`,不要推测版本。 ## 如何判断“已更新” 请分开报告三个对象,不用一个版本号代表整个系统: - 服务器:网页/远程工具的实际功能由服务器当前部署决定;本地客户端更新成功不证明服务器已升级。拿不到服务器发行信息时写“未知”,不要把 A6/A7 开发快照名当产品版本。 - 客户端 MCP:由 `client_update.py check` 报告本机安装版本与服务器提供的最新客户端包版本。相同表示客户端代码无需更新,不代表业务 Skill 已更新,也不代表运行中的 MCP 已重载。 - Skill:逐个按服务器返回的组件版本与目标项目的安装收据核对。没有实际同步/本机识别证据时,分别写“服务器已发布”“本地未核验”,不能只凭客户端版本称 Skill 已更新。不得覆盖用户自行编写的同名 Skill;本地冲突须保留并报告。 后续 Skill/MCP 发布按各自 patch +1(例如0.3.2→0.3.3),系统整体发布按 minor +1、patch归零。历史版本不追溯重编号;未变组件不跟着系统改号。更新完成说明至少列出:服务器状态 / 客户端安装与重载状态 / 本次相关 Skill 版本与本地识别状态。没有证据就注明待核验,不虚构升级成功。 ## 用户说“检查并更新客户端” 先check,当前已最新就结束;确有新版本再apply。更新前提醒保存当前任务、按客户端支持方式暂停/重载本MCP,不自动结束用户工作。更新只替换受托管scripts目录;config、runtime、登录凭据、项目Skill、其他MCP配置都不覆盖。它不是更新WorkBuddy本体,也不更新业务Skill。 安装器从固定来源下载固定路径,拒绝重定向、换源、降级、同版本换包;校验大小、ZIP内容与摘要。本地托管代码被改动或含未知文件时停止,不覆盖用户修改。 代码成功后仍报告 `client_reload=not_performed`,这只表示安装器未手动重载,不排除宿主自动重启 MCP。先检查原生工具是否已加载更新;已加载就直接验证上述三个工具,无需再手动重载。仅未加载时才按宿主支持方式重载。缺少客户端证据只能说“代码更新完成,待核验工具加载”,不能假称已登录或可用。不建立后台轮询、推送或定时更新。 ## 失败和旧客户端 普通更新失败会自动恢复旧代码;进程意外中断后,scripts目录可能暂时不存在,不能依赖其中的更新脚本。AI须重新从原来可信来源的 `/bootstrap/client/install.py` 下载引导脚本到安装目录之外的临时位置,使用这个临时脚本执行 `recover --server <原来源> --install-dir <原安装目录>`,恢复后再check。不从备份中挑任意程序执行,不改配置/凭据。备份留在安装目录 `.client-updates`,不自动删除。本版本没有任意历史版本一键降级功能。 旧源码型安装没有收据,需首次迁移到新的专用目录,保留旧目录,核对公司来源和项目设置后重新配置/登录。不复制或公开旧凭据,不把新安装目录指向服务器或开发源码。 最终输出:安装版本、配置状态、原生工具发现、登录结果和仍需用户完成的具体一步。脚本运行成功与真人客户端验收必须分开报告。 ## 用户说“退出登录”或“切换账号” 原生 `switch_account(account="标签")` 切换本地已保存账户,不撤销其他账户;不传标签则列出可选项。增加账户用 `add_local_account` 创建空槽,再切换并 `start_login`,成功后 `whoami` 核实实际身份。`set_default_account` 只影响新连接与默认 CLI,运行中的连接保持原选择。原生 `logout` 明确退出当前槽,其他独立槽保留;共享同一授权的连接会一起失效。旧 CLI `--switch-account` 仍是撤销后登录,不要代替新的原生账户切换。 ## 首次同步系统 Skill:只配置用户选定目录 用户要求同步某个项目时,由 AI 运行 `python scripts/sync_system_skills.py --project <用户指定项目绝对路径> --configure-project`,只授权该项目,不扩大到其父目录或整个用户目录。用户级扫描没有可用根目录时,可在同一次配置中加 `--user-root <用户指定的技能目录>`,例如用户明确选定的 `.agents/skills`。保留原有配置并生成备份,不扫描、不上传、不下载。 目标目录默认沿用现有配置,不根据客户端名字猜目录。如果已核实客户端使用 `.workbuddy/skills`,同一次配置加 `--target-directory .workbuddy/skills`,收据和备份路径同步切换;其他支持的目标见命令帮助。未经核实不能宣称 WorkBuddy 已识别。切换目标不会删除或迁移旧目录,旧副本保留,后续仅在用户明确要求时处理。 然后运行 `python scripts/sync_system_skills.py --project <项目> --check`,用户已要求同步且预检无冲突时,再去掉 `--check` 执行。分别报告文件同步与客户端实际识别,不能把 installed_files 当识别成功。 注意:更新仅替换 scripts,已有 config 不自动覆盖。旧安装也必须执行上述显式配置步骤,不能仅升级包就声称目录问题已修复。 ## 客户端 0.3.5:WorkBuddy 账户与登录状态 当前交付与验收只聚焦 WorkBuddy。命名账户配置用 `prepare_workbuddy.py --profile <名称> --agents workbuddy` 显式生成;默认无操作只显示帮助,旧单账户配置须加 `--prepare`。配置生成不等于宿主加载或登录完成,不自动改真实宿主设置。不同 WorkBuddy 会话不会天然隔离身份。其他宿主接入暂不推进。 `start_login` / `switch_account` 返回 pending 后,主动调用原生 `login_status` 查看 succeeded、timeout、rejected、failed 或 unknown,不靠 sleep 猜测成功,不重复发起登录。succeeded 后仍须 whoami 核对当前身份;桥接进程重启后进度未知。CLI 授权辅助可以使用 `connect_workbuddy.py --client-config <对应配置> --login-only --wait`,不能冒充宿主验收。 ## 一次查看整体状态 `python scripts/client_update.py status --all --install-dir <安装目录> --server <已确认来源> --config <该Agent实际运行时client.json> --project <项目路径>` 汇总客户端已装/最新版本、服务端版本与连通、工具数、身份与到期、有权限的待审总数、系统 Skill 发布及收据版本。缺失信息是 unknown,不是 0。此命令不登录、不更新、不同步;收据不代表宿主已加载,未执行逐文件完整性校验。只查询,不订阅通知。 ### status 配置与更新后的重载 `--config` 不是 `config/*.example.json`。从该 Agent 的 MCP 启动参数 `--config` 取实际 `client.json`:默认是 `<安装目录>/runtime/workbuddy/client.json`;命名账户则是 `runtime/account-profiles/.../client.json`。省略参数时优先默认路径;不存在时仅可采用唯一同源槽,多个账户不猜测或切换。配置错误时身份是 unknown,不代表用户已退出。 更新器返回 updated 只表示磁盘脚本更新完成。先检查宿主原生工具是否已加载本次新工具;WorkBuddy 可以自动重启 MCP 并加载,已加载时直接通过原生 auth_status、whoami、list_authorizations 核验,无需重复重载。仅未加载时先保存当前工作,再使用宿主支持的“重载/重新连接 MCP”;无此入口时由用户完整退出并重开宿主。新建聊天或再次 check=current 本身不证明工具加载成功。不得绕过宿主授权或自动结束用户工作。 ### 配置自动识别与中文状态 status --all 的 --config 可以省略:先使用 runtime/workbuddy/client.json;没有默认文件时,只在本安装目录 runtime/account-profiles 中寻找与 --server 同源的有效 client.json。只有唯一候选才自动采用;多个账户时不猜身份,必须显式指定。输出 client.configuration 显示实际配置路径及识别来源,不含凭据。 错误会说明缺少字段、错误配置类型、来源不一致或 login_timeout_seconds 的合法区间(30~300 秒整数,省略默认 180)。summary_zh 提供中文摘要,原有机器字段仍保留。unknown 表示未知,不是零或未登录;状态查询不改配置、不启动登录、不更新文件。 ### 当前账户与默认账户 status --all 查询所选 client.json 的注册表默认账户,输出 account_scope=default_for_new_connections。它不能读取运行中 WB bridge 的进程内选择,不能把 CLI 默认账户当成 WB 当前账户。当前会话应原生调用 list_local_accounts 查看 active_account,并用 whoami 核实真实身份;账户标签不是角色或真实用户名。 ## 系统 Skill 文件/收据对账(客户端 0.3.9) 用户要求核对实际安装情况时,可执行 `python scripts/sync_system_skills.py --project <已允许的实际项目> --audit`。只读取线上系统组件 manifest、本地收据和组件文件,不下载ZIP、不更新、不改登录或目录配置。分别报告线上版本、收据版本、文件完整性和版本关系;无收据、缺文件、改动或换源不冒充已正确安装。host_loaded=unknown,仍须由 WorkBuddy 原生发现证据确认加载。只覆盖系统 Skill,不声称已核对任意业务扩展或MCP。 服务端版本撤回只阻止新的获取,不删除或卸载用户已保存副本;不自动降级。只有用户明确指定确切版本和原因,且服务端授权允许时才调用 yank_release。