Docs 站批注 Onboarding¶

给新加入的 retaintive contributor 用 — 让你 5 分钟内能在 docs.retaintive.ai 留段落级批注。

这是什么¶

retaintive docs 站(docs.retaintive.ai / retaintive-docs.pages.dev)集成了 Hypothesis.is 私有 group 批注流。你登录后,任何文档段落都能高亮 + 留 comment,跟 PR comment / GitHub Issue 互补:

通道	适合
PR comment	代码 / 配置 / 短改动 review
GitHub Issue	方案讨论 / 长议题 / 跨 PR 议题
Hypothesis 批注(本指南)	docs 段落级精读 — 标"这段过时""这条不准""这里有疑问"

批注绑在段落本身,跟 commit / PR 解耦,适合长尾 docs review。

Setup(3 步,~5 min)¶

第 1 步 — 打开 docs.retaintive.ai¶

docs.retaintive.ai 已被 Cloudflare Access 保护。用任何 @retaintive.ai 工作邮箱或 insightureAI GitHub org 成员身份就能登入,无需联系 admin 加白(domain match + GitHub org 自动覆盖)。

如果你的邮箱不在以上两类(比如个人 gmail 但需要访问 docs),发邮箱给 Max,他跑:

./scripts/access-add-user.sh your-email@example.com

登录后 Cloudflare session 7 天免重认证。

第 2 步 — 注册 Hypothesis 账号 + 加入 group¶

去 https://hypothes.is/signup 注册(任意邮箱都行,注册账号跟工作邮箱无关)
注册完登入 hypothes.is
点这个 invite link 自动加入 retaintive private group(无需 admin approve):

https://hypothes.is/groups/ZAw8yPz8/retaintive

💡 Hypothesis 不支持 "email domain auto-join",但 invite link 等价效果 — 任何登入 hypothes.is 的人点 link 都能加。

第 3 步 — 留第一条批注¶

打开 docs.retaintive.ai 任一页(已经 Cloudflare Access 登过)
看右上角应该有 Hypothesis 浮动 sidebar 入口(白色羽毛 icon),点开
用 Hypothesis 账号登录(浏览器侧)
切换到 "retaintive" group(下拉菜单)
选中文字 → 点 "Annotate" → 写 comment → "Post to retaintive group"

✅ 留完一条批注就完成 onboarding。

日常用法¶

留批注¶

文档任一段落选中 → Hypothesis sidebar 弹出 → 写 comment → Post。

看别人的批注¶

文档页右上角 Hypothesis sidebar 直接列。或者从 hypothes.is 账号 dashboard 看 group 全部。

浏览器 extension(可选,更顺手)¶

Hypothesis Chrome extension — 比站点内嵌的 embed.js 体验更好,但不是必需(站点 embed.js 已经够用)。

常见问题¶

Q: docs 站打不开,Cloudflare Access 拒绝?¶

→ 检查你登录用的邮箱: - @retaintive.ai 工作邮箱 → 应该自动允许(domain match) - insightureAI GitHub org 成员 → 用 GitHub OAuth 登也允许 - 如果都不是,联系 Max 加白

Q: 我登 hypothes.is 但看不到 retaintive group?¶

→ 你需要点 invite link 加入:https://hypothes.is/groups/ZAw8yPz8/retaintive

→ 确保你已经登入 hypothes.is(不是只是访问站点)

Q: 我写的批注同事看不到?¶

→ 检查你 post 的目标 group。Hypothesis 默认是 "Public",必须切到 "retaintive" group 再 post,否则其他成员看不到。

Q: 离职 / 换岗后怎么 cleanup?¶

→ Cloudflare Access 这边:通知 docs admin 跑 ./scripts/access-remove-user.sh your-old-email@...(domain match 不需要单独移除,但如果你之前是被 enumerated 加的,需要这一步)

→ Hypothesis group 这边:由 Max(group owner max.retaintive)在 hypothes.is admin UI 移除

高级用法 — 批注归档¶

如果你想把团队批注 export 到本地(grep / 数据分析),用 scripts/hypothesis-fetch.sh:

# 先 setup token + env var(参考 scripts/README.md § Hypothes.is)
# Token: 从 https://hypothes.is/account/developer 生成
echo "<your-token>" > ~/.hypothesis-retaintive-token
chmod 600 ~/.hypothesis-retaintive-token
export HYPOTHESIS_RETAINTIVE_GROUP_ID=ZAw8yPz8  # 加进 ~/.zshrc

# 用法
./scripts/hypothesis-fetch.sh --pretty                          # 全部批注
./scripts/hypothesis-fetch.sh --pretty --uri "lead-funnel"      # 按 URI filter
./scripts/hypothesis-fetch.sh                                   # 原始 JSON,pipe 到 jq

详细配置见 scripts/README.md。

跟 GitHub PR review 的边界¶

不是 PR review 的替代,是补充:

场景	用 PR comment	用 Hypothesis 批注
改代码 / 配置	✅	❌
改 docs 内容(diff 阶段)	✅	❌(还是 PR comment 顺手)
已 merge docs 的"这段过时"	❌(原 PR 已闭)	✅
docs 段落级"这条逻辑不对"	⚠️(需要新开 issue 转述)	✅(直接绑段落)
跨多文档的方案讨论	❌	❌(用 GitHub Issue)

简单 rule:docs 内容已经 merged,你想点评具体某一段 → Hypothesis;其他全部走 PR / Issue。

现状(给 admin / future maintainer 看的)¶

资源	值
Cloudflare Access App	`Retaintive Docs`(自 2026-02-15 起,保护 `docs.retaintive.ai` + `retaintive-docs.pages.dev`)
Cloudflare 白名单	`@retaintive.ai` email domain + 2 个 enumerated emails(陈栋 / Victor 个人 gmail)+ `insightureAI` GitHub org
Cloudflare IdPs	GitHub OAuth + Email OTP
Hypothesis group	`ZAw8yPz8`("retaintive",private,owner `max.retaintive` / `max@retaintive.ai`)
Hypothesis fetch script	`scripts/hypothesis-fetch.sh`(env var `HYPOTHESIS_RETAINTIVE_GROUP_ID`)
Onboarding 来源	Issue #245(closed 2026-04-26)