Skip to content

docs: 扫码一键创建飞书机器人写进 README 亮点与文档首页,改掉 1.0 发布以后过时的说法 - #917

Merged
sunerpy merged 6 commits into
mainfrom
docs/feishu-highlight-post-1.0
Nov 19, 2026
Merged

sunerpy merged 6 commits into
mainfrom
docs/feishu-highlight-post-1.0

Conversation

@sunerpy

@sunerpy sunerpy commented Nov 19, 2026

Copy link
Copy Markdown
Owner

1.0.0 发布以后的文档更新。用户要求:「文档可以适当更新,一键创建飞书机器人也可以作为一个亮点和特色」。

扫码一键创建作为亮点

  • README(中英)「1.0 亮点」单独一条:扫码以后 pt-tools 在扫码人所在的企业里建好应用、预填权限与事件、建好并启用通道、扫码人直接成为管理员并绑定,不用开发者后台、不需要公网地址;开头导读补上飞书。
  • 文档站首页:通知那张卡片写明可以扫码一键创建(证据是界面上的「扫码一键创建(推荐)」),描述与标语补上飞书。
  • 1.0 新功能:飞书应用机器人挪到「通知与 AI 助手」第一条,开头一句也提到。
  • ChatOps 快速开始:「选择哪个通道?」写明飞书扫码以后通道已经建好并绑定,步骤最少;通道表「团队用飞书」改成「用飞书」(应用建在扫码人所在的企业,个人也能用)。
  • 快速开始「接下来」、飞书指南开头、更多通知通道里群机器人与应用机器人的取舍各补一句;飞书指南补上「只在登录以后的网页里有」这条限制,FAQ 里订阅方式与发布版本两步注明只对手动创建的应用。
  • 点击路径只写在快速开始与飞书指南里,README、首页、1.0 新功能只写做了什么,不重复同一串步骤。

1.0 发布以后过时或矛盾的说法

  • 绑定:6 处写着「只有用绑定码绑定的账号才能执行命令」,补上网页直接绑定与扫码时的自动绑定。
  • 通用 Webhook 去掉「实验性、尚未端到端验证」;固定 JSON 的说明以 0.48.0 为参照。
  • 数据与安全页:补上 1.0 加密的凭证、会主动连接的地址(含飞书账号服务)、Servarr 兼容入口。
  • 刷流的说法与 docs(guide): 1.0 新功能里刷流那一句改准:从种子列表里按条件挑免费新种 #916 一致;辅种、媒体库里按 rc 版本号写的「升级到这个版本」改成以 0.48.0 为参照;build/README 不再建议固定旧的 rc 标签;configuration 的代理说明补上扫码一键创建只认环境变量。
  • 设计文档写明哪些已随 1.0 实现;docs/README 的目录说明跟上文档站同步脚本(logo-dark.svg、free-expiry-safety.md 不发布)。
  • 文档站锚点:VitePress 给「扫码一键创建(推荐)」「11. 代理」「11. Proxy」生成的 id 与 GitHub 不同,站内链接只能打开页面顶部;三个标题加上同名的 <a id>,两边都能直接跳到这一节。

过程与验证

调研(两路调研 + 审稿逐条核实,采纳 31 条、补 4 条、驳回 4 条)→ 一个写者照着改 → 两路评审(事实与链接;读者体验、中英一致与措辞)→ 修完评审意见。make docs-check、文档措辞检查(README 两份另用同一组正则查过)、make fmt-check 通过;文档站首页 frontmatter 按 firlab 的 home-schema 校验通过。只改文档。

- 「1.0 亮点」第二条加上扫码一键创建飞书应用机器人:在「ChatOps → 消息通知」添加通道、点「生成二维码」、用飞书扫码确认以后,pt-tools 在扫码人所在的企业里建好应用并预填权限与事件,建好并启用通道,扫码的人成为管理员并直接绑定;不用去飞书开发者后台配置,也不需要公网地址。链接指向文档站的这一节,锚点按文档站实际的 id。
- 开头导读的「都能查看和操作」补上飞书,与亮点、通知通道、ChatOps 几条一致。
- 刷流一条照 1.0 新功能里改过的说法(3ec0ad4c):从站点的种子列表里按条件挑免费的新种,不是只读免费列表。
- 「用法」里 ChatOps 的绑定说法跟上 1.0:名单里的账号除了用绑定码,还能在「ChatOps 绑定」页直接绑定,扫码一键创建时扫码的人会被直接绑定。原来写的「用绑定码完成绑定的账号」漏了后两种。
- 英文版同样改;账号绑定沿用这份文件原有的 linked。
- ChatOps 快速开始:通用 Webhook 去掉「实验性」「尚未端到端验证」,照「更多通知通道」里的自定义 Webhook 写成 HTTP(可选 HMAC-SHA256 签名)、发给 n8n、Home Assistant、Discord、Slack 这类自己的服务,「选择哪个通道?」的最后一行一起改。它在 1.0 里是正式功能,界面上也没有实验性标记。
- IYUU 辅种「升级与回退」:正式版用户能回去的旧版本是 0.48.0,里面没有辅种,原来写的「回退到旧版本时辅种照原来的方式运行」对它不成立。改成先写回到 0.48.0 以后不再辅种,原来的说明限定在 1.0.0-rc.45 或更早的预览版(这些行为从 rc.46 起有),回退前打开站点开关的提醒保留。「统计」里补统计的那句同样限定。
- 整理入库:「升级到这个版本以前」改成具体的预览版:失败分类从 rc.53 起有,分类目录从 rc.37 起记着。
- 自定义 Webhook:固定 JSON 里的 event 改成与 0.48.0 对比着写,不再写「这一版新加的」,以后发版也不会过时。
- 绑定:ChatOps 快速开始、Telegram、QQ 页里的「要用绑定码完成绑定」改成「要完成绑定」。1.0 里还能在「ChatOps 绑定」页直接绑定名单里的账号,扫码一键创建飞书应用机器人时扫码的人也会被直接绑定。
- docs/README.md 的刷流一条照 1.0 新功能的说法改:从种子列表里按条件挑免费的新种。
- build/README.md:1.0.0 已经发布、latest 就是 1.0.0,删掉「1.0.0 发布前要固定 rc 标签」的说明。
- 英文页同样改;表格经 oxfmt 重新对齐。
- 首页:「QQ、Telegram、飞书与通知」卡片开头写明飞书应用机器人可以扫码一键创建,证据换成界面原文「扫码一键创建(推荐)」(英文用飞书页的译法);description 与 hero 的 tagline 补上飞书,与同页的卡片一致。
- 1.0 新功能:开头一句列上可以扫码一键创建的飞书应用机器人;飞书应用机器人一条移到「通知与 AI 助手」第一条,写明扫码以后 pt-tools 做了什么、扫码的人成为管理员并直接绑定、企业要求审核应用时可能建不成。
- ChatOps 快速开始:「选择哪个通道?」开头加一段,对比飞书应用机器人、QQ、Telegram 各要做哪些准备;决策树的「团队用飞书?」改成「用飞书?」,表格里的推荐场景同样不再限定团队(应用建在扫码人所在的企业,个人也可以另建一个企业)。
- 快速开始「接下来」:写出用飞书扫码一键创建的点击路径,QQ 与 Telegram 仍指向 ChatOps 快速开始。
- 飞书应用机器人页:开头写明两种建法;扫码一键创建的要点加一条:只在登录以后的网页里有,手机 App 与 MCP 里没有,AI 助手改配置时只能填 App ID 与 App Secret 建通道;「在群里用」第 1 步与 FAQ「发给机器人的消息没有反应」里订阅方式、发布版本两步写明只对手动创建的应用;「支持 Lark 国际版吗?」补上扫码人用 Lark 国际版时平台自动是 Lark 国际版。
- 更多通知通道:飞书群机器人一节末尾提到应用机器人可以扫码一键创建。
- 配置说明:环境变量代理的说明加上飞书应用机器人只读 HTTPS_PROXY 与 NO_PROXY,扫码一键创建时只按这两个环境变量。
- docs/README.md:飞书应用机器人一页的简介加上扫码一键创建与发布版本。
- 英文页同样改;账号绑定沿用各页原有的说法(ChatOps 快速开始与 1.0 新功能写 linked)。
- 「哪些内容会加密」补上 1.0 加进来、与站点 Cookie 用同一把 AES-256-GCM 密钥加密的凭证:AI 助手与语音输入,媒体识别(TMDB、Fanart.tv、OMDb、TheTVDB),媒体服务器与 ChineseSubFinder,IYUU 与 CookieCloud,NAS 监控的来源。站点 API Key 与 Passkey 仍是明文,那条提醒不变。
- 「会主动连接哪些地址」:扫码一键创建飞书应用机器人时连 accounts.feishu.cn(扫码人用 Lark 国际版时改连 accounts.larksuite.com);豆瓣与 Bangumi 写全什么时候会连(豆瓣想看、番剧日历);补上大模型服务、IYUU、填了地址才连的其他服务;relay 一行写明留空时连内置的托管 relay、勾了只直连就不连。与首页「数据去向」对得上。
- 令牌能访问的入口与监听的端口补上 Servarr 兼容入口:/servarr/ 在网页的端口上,只认令牌,要「Servarr 兼容」权限,Key 放在查询参数 apikey 或请求头 X-Api-Key 里。
- 部署建议里 ChatOps 的绑定补上「ChatOps 绑定」页直接绑定与扫码一键创建时的扫码人。
- 参与开发的「设计文档」一句:MCP Server 等设计已经随 1.0.0 发布,不再写「不表示相应能力已经发布」,改成以用户文档和 Release 说明为准。
- 英文页同样改;表格经 oxfmt 重新对齐。
- AI Agent 设计(phase5-agent.md):状态改成没有按本文实施,文首加一段说明:1.0.0 已经发布了 MCP Server,也内置了 AI 助手(接 OpenAI 兼容的大模型,经进程内的 MCP 工具工作,改动类操作要确认),正文里「MCP 只有静态工具契约」「不内嵌 LLM」等几处与 1.0.0 不符,以用户文档为准。正文不改,留作设计记录。
- ChatOps / MCP / Agent 架构第 14 节:表格按 1.0.0 写,加上飞书应用机器人与只出站的各通道,AI Agent 写成已实现为内置的 AI 助手;删掉提到 internal/mcp/contract.go 的那条提醒(这个文件早已删除,提醒与表格矛盾);用户指南列表加上飞书应用机器人与更多通知通道。
- docs/README.md:「开发与设计」里两份设计文档的简介和下面的 NOTE 不再写「后续实施契约」「不表示相应能力已经对外发布」;「目录与站点路径」表照 firlab 的同步脚本改:design/free-expiry-safety.md 不发布到文档站;logo-dark.svg 也会同步过去,是深色主题导航栏里的标志。
- 文档站(VitePress)给「扫码一键创建(推荐)」生成的 id 是「扫码一键创建-推荐」,给「11. 代理」「11. Proxy」生成的是「_11-代理」「_11-proxy」,与 GitHub 不同;站内按 GitHub 规则写的链接只能打开页面顶部。在这三个标题里加上同名的 <a id>,两边都能直接跳到这一节(标题文字不变,原来的 id 照旧可用)。
- README「1.0 亮点」里扫码一键创建那一条去掉菜单路径,只写扫码以后会发生什么;点击步骤留在快速开始与飞书指南里,界面改了以后少一处要跟着改。
- 英文飞书指南与快速开始把 bind/bound 改成和 Telegram、QQ 页一样的 Link/linked、Generate binding code;configuration 的「以前直连、现在按变量走」改成以 0.48.0 为参照;英文安全页的界面名补上中文。
@codecov

codecov Bot commented Nov 19, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
see 9 files with indirect coverage changes

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@sunerpy
sunerpy merged commit db125af into main Nov 19, 2026
14 checks passed
@sunerpy
sunerpy deleted the docs/feishu-highlight-post-1.0 branch November 19, 2026 07:57
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant