项目

接入由 AI 终端（Claude Code 或 Codex）自动完成：你把一句话发给它，它会读取接入剧本，一步步把项目接上中央工作台。你要做的是准备好下面几样东西，并在过程中确认几次。新项目、已经在做的项目都一样。

一、准备（每台设备做一次）

1. 拿到本端密钥。 向负责中央工作台的同事要一把密钥（以 whk_ 开头）。每台电脑或每个 AI 终端一把，不要共用，也不要发到群里。

2. 把密钥设成环境变量 WORKHUB_KEY，然后重新打开终端，再启动 Claude Code 或 Codex：

   • macOS / Linux：在 ~/.zshrc 或 ~/.bashrc 末尾加一行 export WORKHUB_KEY=whk_...
   • Windows：在 PowerShell 或命令提示符里执行 setx WORKHUB_KEY "whk_..."

   不要把密钥写进项目文件。

二、准备（每个项目）

1. 项目在 Git 服务上有仓库（Gitee、GitHub 或自建 Gogs），本地已经 clone 下来。还没有仓库的新项目，先在 Git 服务上建一个。
2. 你能在仓库设置里添加“部署公钥”（中央只读，不会提交代码）。没有这个权限的话，准备一个只读的访问令牌也可以。
3. 想好标尺分支。 前期每个项目只用一个分支，一般是 main 或 master，进度文件提交到这个分支，中央也只读这个分支。

三、发一句话给 AI

在项目根目录打开 Claude Code 或 Codex，发送：

请阅读 https://workhub.qianba.cc/onboarding.md，按它把当前项目接入 workhub。

四、过程中你要确认的事

AI 会问你	你要做的
标尺分支用哪个	确认 main 或 master
添加部署公钥	把 AI 给出的公钥加到仓库的“部署公钥 / Deploy keys”，只勾选只读；或者给它一个只读令牌
是否登记项目	确认
进度文件的内容	仔细看一遍：它会公开显示在本站，不能有客户信息、服务器地址、账号密码
目录按项目规范映射还是改造（已在建的项目）	目录已经稳定就选“映射”（不动文件，只写对照关系）；想统一成标准结构就选“改造”，AI 会先列迁移计划给你看
写入 AI 规则	在 AGENTS.md 里加一段 workhub 规则（CLAUDE.md 引用它），以后每次会话都按规范和流程干活；看一下内容，同意
安装 agent 和 skill	看一下清单（来自团队共享的能力库），没问题就同意
提交并推送	看一下改动清单，同意

五、接入之后

• 配置 webhook（可选，建议）： AI 会给你一个 webhook 地址（只出现一次），配到仓库的 WebHooks，触发事件选 push，不需要密码或 Secret。Gitee 在“仓库 → 管理 → WebHooks”，GitHub 在“Settings → Webhooks”。不配的话，中央每 5 分钟检查一次进度。
• 项目会出现在本页的列表里。
• 以后 AI 每次干活都会按项目规范和 Loop 视图执行，并随时更新进度。
• 接入要求（当前 v1）、项目规范或 Loop 视图更新后，再发一次同样的话，AI 会按最新要求更新项目。

常见问题

• AI 说密钥无效（401）： 密钥过期或已停用，找负责中央工作台的同事换一把。
• AI 说试拉失败： 部署公钥没加上、加错了仓库，或者分支名不对。
• 本页显示“进度文件解析错误”： 让 AI 按页面上的错误提示修正 .workhub/progress.yaml 并重新提交。
• 想看 AI 具体会做什么： 打开接入剧本。