Synthesis Onboarding 是面向 synthesis 生态的安装与诊断工具,目标是把一台干净机器变成可用的 synthesis 环境,流程接近“一条命令加一次认证”。它同时服务两类人:需要可脚本化、可验证安装的工程师,以及不应面对复杂问题的非工程同事。
设计原则
- 一个引擎,组织清单:引擎保持通用,组织只在知识库仓库中提供 .agents/onboarding.yaml 配置,不写安装器代码;任何组织只需一个 YAML 文件和一行包装脚本即可拥有自己的安装器。
- 收敛而非脚本:每次运行都声明目标状态并推动机器向其靠近;重复运行始终安全,会更新、修复半完成的安装,并对用户编辑过的内容只报告不覆盖。
- 失败即停止并明确提示:缓存过期、清单键未知、状态无法验证时中止并给出通俗说明;无法运行的检查绝不会显示为通过。
两种入口
- 终端(除 macOS 外无需预装任何东西): curl -fsSL https://raw.githubusercontent.com/synthesisengineering/synthesis-skills/main/onboard.sh | sh
- 助手入口(当 Claude Code 或 Codex 已装本插件时):让助手“设置 synthesis 生态”,它会运行同一引擎: python3 <this-skill>/scripts/onboard.py install 组织成员则使用组织的包装脚本(在组织知识库仓库中一条命令),以组织清单调用同一引擎,详见 references/org-manifest.md。
命令 onboard.py install [--manifest PATH] [--dry-run] [--json] [--clients claude,codex] [--no-plugin-cli] [--with-personal-workspace NAME] onboard.py update # 显式刷新原生插件并收敛安装 onboard.py doctor [--manifest PATH] [--json] onboard.py init-workspace --workspace NAME [--remote URL] onboard.py uninstall [--dry-run] 退出码约定:0 表示完全收敛/健康;1 表示错误或需要用户操作的步骤(认证、git 身份),处理后重跑;2 表示引擎无法建立基准事实(无 git、清单无效)。
install 的执行顺序
- preflight:验证 git(缺失时引导执行 xcode-select --install);通过 SYNTHESIS_CLAUDE_BIN/SYNTHESIS_CODEX_BIN → PATH → 常见位置(含 ChatGPT 应用内置 codex)检测客户端;客户端缺失时跳过而非致命。
- ecosystem:install 会补装缺失的原生插件、检查已有插件而不替换其运行缓存;update 会显式刷新已有原生插件,在源码检出运行时校验版本,并说明是否需要新的 Claude Code 会话或 Codex 任务。首次安装时若客户端缺少插件 CLI,可使用仓库的直接复制回退方案;已安装的原生插件不会被重复副本替换。
- org-skills:对清单中每个 skills_repos 条目,优先用 SSH 克隆/刷新到引擎缓存,再以该缓存为源委托给对应仓库自己的安装器;缓存无法刷新时该步骤停止(可用 SYNTHESIS_ONBOARD_ALLOW_STALE=1 覆盖,但有醒目提示)。
- knowledge-bases:克隆到 ~/workspaces/<org-workspace>/<name>,或通过匹配远程地址认领已有克隆(从不移动);被取代的远程地址会重指向清单主仓库(git remote set-url);干净时快进拉取;仓库附带 .githooks 且无全局 hooks 引擎时,配置仓库级 core.hooksPath,使保护钩子在全新克隆上生效。认证失败时打印清单中的 auth_help 并将该步骤标记为“需要你”,运行继续,重跑可完成。
- workspace:生成 ~/workspaces/<org-workspace>/AGENTS.md(以及 CLAUDE.md = @AGENTS.md),包含欢迎语、可提问列表、知识库约定指引。
- migrations:将清单中的技能墓碑(移除/重命名/由公开版取代)应用到用户级技能副本,先归档后处理。
- doctor + welcome:验证所有内容后给出问候,说明可以尝试问什么、指南在哪里,以及重跑始终安全。
回执与不覆盖规则 状态保存在 ~/.synthesis/onboarding/receipts.json,记录每个生成文件的校验和、认领的仓库位置与运行历史。当前内容与回执一致的生成文件归引擎所有,可以更新(旧副本归档到 ~/.synthesis/onboarding/backups/);用户编辑过的文件绝不被覆盖,引擎会警告后继续。uninstall 只移除回执归属的文件(先归档),从不触碰知识库克隆或插件。
安全的插件升级 仅在关闭其他使用本市场的 Claude Code 会话和 Codex 任务后再运行 onboard.py update,并让它成为当前会话在开启新会话/任务前的最后一个动作。原生客户端会把插件钩子解析到带版本的缓存路径,替换该缓存可能使其他活跃会话已加载的钩子命令失效。普通 install 与 doctor 从不刷新已有原生插件。
脚手架个人知识工作区 onboard.py init-workspace --workspace alice [--remote git@github.com:alice/ai-knowledge-alice.git] 创建 ~/workspaces/<name>/ai-knowledge-<name>/,内含 projects/index.yaml、lessons/、AGENTS.md 及 CLAUDE.md 适配文件、README、git init 与首次提交,符合 synthesis-project-management 的容器形态;项目内容仍由智能体撰写,此命令只搭建容器,免去第一天手动接线。
配置项
- SYNTHESIS_ONBOARD_HOME:默认 $HOME,所有安装目标的根目录(测试用沙箱 home)。
- SYNTHESIS_ONBOARD_STATE_DIR:默认 ~/.synthesis/onboarding,回执与备份位置。
- SYNTHESIS_WORKSPACES_ROOT:默认 ~/workspaces,工作区与知识库位置。
- SYNTHESIS_ONBOARD_CACHE_DIR:默认 XDG 缓存目录,组织仓库缓存位置。
- SYNTHESIS_ONBOARD_SOURCE_DIR:默认本仓库,用于安装的 synthesis-skills 检出目录。
- SYNTHESIS_CLAUDE_BIN / SYNTHESIS_CODEX_BIN:默认自动,客户端二进制覆盖;设为空值表示“视为不存在”。
- SYNTHESIS_ONBOARD_ALLOW_STALE:默认未设置,接受无法刷新的缓存(有醒目提示)。
- SYNTHESIS_ONBOARD_NO_PLUGIN_CLI:默认未设置,强制使用文件复制回退。
与相邻工具的关系
- install.sh(仓库根):客户端不支持原生插件时,本引擎委托使用的逐技能复制回退方案。
- onboard.sh(仓库根):curl 引导脚本,确保 git 可用、克隆或刷新本仓库并交给本引擎。
- synthesis-skills-manager:面向技能作者(多仓库源管理、synthesis 合并)的智能体协议;本引擎是终端用户安装器,从不编辑源。
- synthesis-agent-conformance:面向维护者的深度一致性审计;onboard.py doctor 是终端用户健康检查,一致性审计仍是权威的源/运行时/交接验证。
- synthesis-project-management / context-lifecycle:定义 init-workspace 所搭建的工作区形态。
支持的客户端 Claude Code、ChatGPT Codex 桌面版和 Codex CLI 是一等原生插件平台。Codex IDE 被标记为 UNSUPPORTED:它不加载插件,且其共享用户技能根目录无法再放一份公开副本,否则会在桌面版/CLI 中产生重复定义。插件变更只会在新启动的会话/任务中可见;切换前请保留 synthesis 检查点,不要要求已存在的任务假装重新加载了启动注册表。
安全规则 删除前必先归档,绝不强制推送;绝不覆盖用户编辑过的文件(回执决定归属);绝不枚举或克隆清单未指定的仓库;组织清单校验失败即停止,未知键视为错误;引擎仅依赖 python3 标准库(PyYAML 可选),因此仅有命令行工具的全新 Mac 无需其他依赖。v1 面向 macOS,引擎避免 macOS 专属代码路径,以便 Linux 和 Windows(优先 WSL)后续无需重新设计即可支持。