agentleFS
wlkerwong-boopwlkerwong-boop/family-ai-skills/skills/third-party-handover/SKILL.md

third-party-handover

Skill0 starsChanged 2 months agoMITView on GitHub

Use when handing a device to a non-technical person.

The file

Files
SKILL.md

交付给非技术用户(设备 / 账号 / 服务)

用于「帮朋友/家人/合作方把一台设备、一个服务、一个账号弄好,然后交出去」这类任务的最后一公里。对方不懂技术、出问题只会找你,所以交付物必须自带回滚路径。

触发场景:给朋友刷好的路由器、给家人的小工具/账号、给合作方的站点或服务、任何要求「做一张纸让对方照着用」的活。

硬规矩(每次都适用)

  1. 交付四件套,缺一不算交完:① 能用的东西 ② 一页纸说明书 ③ 回滚路径 ④ 当面演示一次回滚。
  2. 一页纸的第一步永远是「怎么回到原样」:写在“出问题怎么办”第一条,必须是一个动作(拔线/关掉/点某个按钮),不是排查步骤。
  3. 凭据只手写、当面给,或只让他看屏幕:账号、订阅、密钥不通过聊天工具发文字(聊天记录等于云备份)、不写进云端文档、不进公开仓库。他本人要用的本机服务,用「在他屏幕上显示」代替发密码:open -a Terminal <启动脚本>(把凭据打在窗口里,并告诉他“以后想看就双击这个脚本”),或 pbcopy 到剪贴板让他直接粘贴登录。
  4. 给对方的部分只留「够用」的信息:不写协议/实现细节、不写远程管理入口、不写你自己的其它资产。
  5. 不承诺你验证不了的事:给非技术用户的说法只能是实测过的现象(“能打开某页”“能连上”),不能是“理论上应该没问题”。交付前自己完整跑一次冷启动(先停掉它,再从零跑一遍启动脚本),并用你要交给他的那套凭据真的登录一次——自报“应该能用”不算验证。
  6. 敏感话题用能力名,不用话题名:一页纸同理,写法按对方能不能拿去求援来定,不按你自己的技术叫法。

流程

  1. 先确认对方环境:他现有的网络/设备是什么、哪一步绝对不能动。改别人家网络的代价不对称。
  2. 选最小侵入的接法:能旁挂就不替换、能只影响一台设备就不影响全屋——回滚成本越低越好。
  3. 装通,同时建档:固件/版本、后台地址、账号、密码、原厂(初始状态)包的位置,随手记下,不要靠回忆。
  4. 做一页纸(模板 templates/handover-onepager.html):
    • 一份文件、两个区:@media print 里隐藏 .private(只给自己看的档案/凭据/验收清单)。不要维护“给人版”和“自己版”两份文件——它们必然不同步。
    • 结构固定:它是什么(含“坏了不影响你”)→ 怎么用(含“能用”的可验证标准)→ 出问题怎么办(第一条回滚)→ 千万别做的三件事。
    • 凭据区明确写“手写、不留电子版”。
  5. 验证打印产物(scripts/verify_print_deliverable.sh):页数必须 1 页;私密关键词在 PDF 文本里 0 命中、正文关键词 ≥ 1;截图用视觉能力自己看一眼。
  6. 当面交付 + 演示回滚,三句话足够:这东西接在哪、坏了不影响你;万一不对第一件事是做 X,你看我做一次;记不住没关系,都写在纸上。
  7. 留档:把档案区填好,存在本机不公开的文档库(不进仓库、不进云盘),并记下交付日期与对方联系方式。

打印验证(HTML → PNG + PDF,可重复执行)

bash scripts/verify_print_deliverable.sh <绝对路径.html> \
     --private "线路信息,设备档案" --expect "使用说明"

脚本做的事(也可手工跑):

CH="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
# 路径含中文/空格要 URL 编码(空格 → %20)
"$CH" --headless=new --disable-gpu --hide-scrollbars --window-size=900,2400 \
      --screenshot="$OUT/page.png" "file:///绝对路径.html"
"$CH" --headless=new --disable-gpu --no-pdf-header-footer \
      --print-to-pdf="$OUT/page.pdf" "file:///绝对路径.html"
pdftotext "$OUT/page.pdf" - | grep -c "私密关键词"   # 必须 0
pdftotext "$OUT/page.pdf" - | grep -c "正文关键词"   # 必须 ≥1

截图交给视觉能力看(排版错位、文字重叠、填写横线断裂只能靠看);PDF 用来验页数与“该隐藏的确实没印出来”。

Pitfalls

  • 一键入口的 .command / .sh 必须自带 export PATH:双击启动的 GUI 脚本 PATH 极简(通常没有 /opt/homebrew/bin、没有用户级 bin),不导出就 command not found——而这是“对方用不了”的头号原因。
  • 解释用「一句比喻 + 三步 + 怎么关」:先讲“这东西相当于给你开了间小图书室”,再只给“你现在要做的”:双击哪个图标 → 浏览器里填哪两行 → 用哪句话试;体积、参数、接口名收进文件。非技术用户会直接说“我不太懂,我只想知道怎么操作”——那就是“说完结论就该停”的信号。
  • 别把“手机也要能用”当免费需求:跑在他电脑上、绑在 127.0.0.1 的服务与放在公网的页面天然接不上。先问清他在哪些设备上用,再定架构——否则只能在“把数据搬上公网服务器”(隐私/版权代价)和“装一条隧道”之间现选。
  • 只交付“屏幕上好看”的 HTML 不算完:必须跑一次 --print-to-pdf。为什么:一页纸的价值在“打印成一张交给对方”,屏幕渲染正常 ≠ 打印正常(分页、隐藏规则、虚线框断页都可能变)。
  • 别用 grep 原 PDF 字节做关键词断言:PDF 内容流是压缩的,正文和待排除内容都会搜不到(假阴性),必须 pdftotext(或 pypdf 提取)后再断言。
  • 别把私密区做成另一个文件、或要求对方“别看下半页”:只有“打印 CSS 隐藏 + 实测 0 命中”才算隔离;靠人自觉必然泄漏。
  • 别在没有演示回滚的情况下交付:对方出事的第一反应是“东西坏了”,而回滚动作是他唯一能自己做的。
  • 别写“理论上应该能”:非技术用户无法区分不确定与承诺;拿不准就写清“这一步如果不对给我微信”,号码留空让他自己填。
  • 凭据别过聊天工具:写纸、当面给;实在要发,也先提醒用户自己注意留存风险,不要代为发送。

相关

  • 上游(选型、刷机、验收)见 open-source-publishing 的 references/hardware-asset-credibility.md。
  • 有样式 HTML 转 PDF 的其它工具对比见 mac-pdf-generation(该技能为用户所有,未纳入自动维护)。

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.