raw-drop 部署助手 / raw-drop Setup Assistant

手机随手记（文字 / 截图 / 语音），记录先存手机本地，回到电脑前点一次「上传全部」，内容落进本地 Obsidian 知识库的 raw/inbox/。

Capture notes on your phone (text, screenshots, voice). They queue locally, then one tap uploads them into your local Obsidian vault's raw/inbox/ folder.

本技能是完整安装包，内置全部程序。用户说「帮我装 raw-drop」时，直接执行部署流程即可，不需要再去别处下载。

This skill is a self-contained installer. When a user asks to set up raw-drop, run the deployment flow below — no external downloads required.

一、用户第一次说「装一下」，你要做什么

第 1 步：检查 Obsidian 是否安装

python -c "import os,pathlib;print(pathlib.Path.home()/'AppData/Roaming/obsidian/obsidian.json').exists()"

若返回 False：

告诉用户 / Tell the user:

> 没有检测到 Obsidian。这个工具需要 Obsidian 作为笔记软件。
> 请先到官网下载安装：https://obsidian.md/download
> 装好之后跟我说一声，我继续帮你配置。

> Obsidian was not detected. This tool requires Obsidian as the note app.
> Please download and install it from https://obsidian.md/download
> Let me know once it's done and I'll continue the setup.

然后就此停下。不要代用户安装软件。

Then stop. Never install software on the user's behalf.

第 2 步：探测已有知识库

python -c "
import json,pathlib
reg=pathlib.Path.home()/'AppData/Roaming/obsidian/obsidian.json'
d=json.loads(reg.read_text(encoding='utf-8'))
for v in d.get('vaults',{}).values():
    p=v.get('path')
    if p and (pathlib.Path(p)/'.obsidian').is_dir(): print(p)
"

有结果就把候选列给用户挑，例如：

> 找到这些知识库：
> 1. D:\我的笔记
> 2. E:\obsidian\第二大脑
> 用哪个？

> Found these vaults:
> 1. D:\我的笔记
> 2. E:\obsidian\第二大脑
> Which one should I use?

不要自己替用户选。

Never pick for them.

第 3 步：部署

python <技能目录>/scripts/deploy.py --target <安装目录> --vault <库路径>

省略参数则进入交互式问答，用户自己选。

Installs to C:\Users\<用户名>\raw-drop by default.

第 4 步：把配对信息告诉用户

脚本会输出 / The script prints:

配对页：http://127.0.0.1:8787/pair/page
手机访问：http://192.168.x.x:8787/setup?t=<token>

要明确告诉用户这三件事 / Tell the user these three things:

1. 浏览器打开配对页（二维码在这里）
   Open the pairing page in a browser — the QR code is there
2. 手机要连同一个 WiFi
   The phone must be on the same WiFi as the computer
3. 手机连不上时，运行 python 解决手机连不上.py（会自动弹 UAC 放行防火墙）
   If the phone can't connect, run python 解决手机连不上.py (it requests admin rights to unblock the firewall)

第 5 步：告诉用户怎么在手机上用

服务自带网页端，扫码即用，不需要装任何 App：

• 浏览器打开配对页会自动填好令牌
• Chrome 菜单 →「添加到主屏幕」，桌面出现图标，跟原生 App 一样
• 若用户问「有没有更方便的入口」，可以提一句：存在微信小程序版本，但它需要单独发布，本技能不含小程序源码

The bundled web page works like an app — no installation needed. Open it in a browser, then use Chrome's "Add to Home screen".

Phone-side capabilities: text notes (with OS dictation), images, voice recording. Items queue locally; tap "upload all" when you're back at the computer. Uploaded items stay for 7 days, then auto-delete.

二、手机连不上时的排查顺序

先诊断，再动手。 绝大多数「连不上」不是代码问题。

python <技能目录>/scripts/check.py --deep

它会报出服务状态、库路径、局域网地址、收件箱数量、依赖情况和目录结构。

Diagnose first, then act. Most connection failures are not code bugs. The script reports service state, vault path, LAN address, inbox count, dependencies and directory structure.

按现象处理 / Handle by symptom:

网络四条（按序，不要跳）/ Four checks, in order:

1. 手机和电脑连的是同一个路由器 WiFi吗？
   Is the phone and computer on the same router WiFi?
   - 特别注意：电脑若连的是手机热点，很多手机会隔离热点上的设备
   - Note: if the computer is on a phone hotspot, many phones isolate hotspot clients
2. 防火墙放行了吗？/ Is the firewall rule in place?
3. 电脑上开着 VPN / 加速器 / 代理吗？临时关掉
   Is a VPN / accelerator / proxy running? Turn it off temporarily
4. 服务黑窗口还在吗？/ Is the console window still open?

关于 IP 的坑：若 ifconfig.me 返回公网地址（如 111.x.x.x），那是运营商 NAT 出口，不代表局域网不通，不要据此误判网络类型。

IP caveat: a public address from ifconfig.me is the ISP's NAT egress. It does not mean the LAN is unreachable — don't misdiagnose from it.

三、改配置

配置文件在安装目录下的 config.json：

Config lives at config.json inside the install directory:

改完必须重启服务。

Restart the service after editing.

换库最省事的做法是直接重新部署 / Easiest way to switch vaults:

python scripts/deploy.py --target <安装目录> --vault <新库路径>

四、知识库结构

如果用户的库还没有分层，建议用这个结构：

If the user's vault has no structure yet, suggest this layout:

<库根>/<vault root>/
├── raw/                事实源，只读不改 / Source of truth, write-once
│   ├── inbox/手机投递落在这里 / Phone captures land here
│   ├── sources/        登记过的来源 / Registered sources
│   └── assets/         图片、录音 / Images and audio
├── wiki/               结构化知识 / Structured knowledge
│   ├── concepts/ topics/ entities/
│   └── analyses/ comparisons/ questions/
├── outputs/            派生产物 / Derived artifacts
└── AGENTS.md           维护规则 / Maintenance rules

raw 层铁律：只读，不改写，不重命名，不删除。新资料先进 raw/inbox/，处理后才登记到 raw/sources/。

raw layer rule: append only — never rewrite, rename or delete. New material goes to raw/inbox/ first, gets registered into raw/sources/ only after processing.

投进来的笔记自带元数据：

Delivered notes carry metadata:

---
source: wechat
captured_at: 2026-10-09T21:50:22+08:00
drop_id: 312f99b9
batch_id: m1a2b3
status: inbox
tags: [inbox, raw-capture]
---

五、检查收到了什么

ls -lt "<vault>/raw/inbox/" | head -10
curl -s http://127.0.0.1:8787/health

六、安全边界（不得越界）

这个工具的设计刻意保守，任何改动都不能破坏这些性质：

The design is deliberately conservative. No change may break these properties:

• 不代用户安装软件 —— 遇到未装 Obsidian / Python，只给官网地址，让用户自己装
  Never install software for the user — if Obsidian or Python is missing, give the official URL and let them install it
• 不伪造第三方目录 —— 不自动创建 .obsidian
  Never fabricate third-party directories — never auto-create .obsidian
• 只写 raw/ —— 绝不读取、改写、重命名、删除用户既有笔记
  Write only inside raw/ — never read, rewrite, rename or delete existing notes
• 不暴露公网 —— 默认只监听局域网
  Never expose to the internet — LAN only by default
• 附件格式白名单 —— 仅放行图片与音频，拒绝可执行文件
  Extension allowlist — images and audio only; executables rejected
• 目录穿越防护 —— 落盘前校验目标路径必须在库内
  Path traversal guard — targets are validated to stay inside the vault
• 不把配对令牌发给第三方 —— 二维码本地生成；第三方扫码 API 默认关闭
  Never leak the pairing token to third parties — QR is generated locally; the third-party QR API is off by default

只创建 raw/inbox、raw/assets 这类本工具自身的目录是允许的。

Creating raw/inbox and raw/assets is fine — those belong to this tool.

网络访问与权限声明 / Network access and permissions

审核与用户都需要知道这个包会碰什么：

提权说明 / Elevation: 只有 解决手机连不上.py 需要管理员权限，用途单一——放行 8787 端口入站。不修改注册表、不安装服务、不写系统目录。

Only 解决手机连不上.py needs admin rights, for one purpose: allowing inbound TCP 8787. It does not touch the registry, install services, or write to system directories.

七、安装前的准备 / Before you install

部署脚本会尝试自动安装二维码库（qrcode），以便本地生成二维码。若你的环境无法联网或不允许自动装包，加 --no-deps 跳过：

The deploy script tries to auto-install the QR library (qrcode) so codes are generated locally. If your environment is offline or disallows automatic installs, pass --no-deps:

python scripts/deploy.py --no-deps

跳过后二维码回退到随包静态兜底图，其余功能不受影响。手动安装：

python -m pip install qrcode

特别提醒用户：任何拿到配对码的人都能往那台电脑的库里写东西（只能新增，不能改已有文件）。库里放敏感资料时要注意。

Warn users: anyone with the pairing code can write to that computer's vault (append-only, cannot modify existing files). Relevant if sensitive material is stored.

八、踩坑记录（勿重蹈）

自研标准算法前必须想清楚怎么验证。

本项目曾自研 QR 编码器，结构自检全过（定位图案、定时图案、PNG CRC 均正确），但微信扫一扫识别不出来。事后做「反向回读校验」——把数据区比特读回来与源数据比对，发现第 0 位就不一致。

> 结构自检通过 ≠ 结果正确。 涉及编码、加密、压缩这类必须与外部标准严格一致的实现，必须用现成库（现用 qrcode），或配解码器做往返验证。

Never hand-roll a standard algorithm without a plan for verification.

This project once shipped a hand-written QR encoder. Every structural self-check passed — finder patterns, timing patterns, PNG CRC — yet WeChat's scanner couldn't read it. A reverse read-back test showed bit 0 already wrong.

> Structural checks passing ≠ correct output. For anything that must match an external spec exactly (encoding, crypto, compression), use a battle-tested library (we now use qrcode) or round-trip it through a real decoder.

其他 / Others:

• 改 HTML 模板后要实际请求一次页面，字符串替换可能没命中写死的属性
  After editing an HTML template, actually request the page — string replacement can miss hard-coded attributes
• 服务改了代码要重启；若行为异常，先确认端口上跑的是不是新进程
  Restart after code changes; if behaviour is odd, first check whether the process on the port is actually the new one (netstat -ano | grep <port>)
• PowerShell 的 Get-NetFirewallProfile 在非管理员下返回空，改用 netsh 验证更可靠
  Get-NetFirewallProfile returns nothing without admin rights; netsh is more reliable here

九、目录结构 / Layout

raw-drop/                    本技能 / This skill (self-contained)
├── SKILL.md                 本文件 / This file
├── app/内置服务端            Bundled server (copied to the user's PC on deploy)
│   ├── raw_drop.py          主服务 / Main service
│   ├── qr_provider.py       二维码生成 / QR generation
│   ├── 设置向导.py            交互式配置 / Interactive setup wizard
│   ├── config.json          配置模板（vault 留空）/ Config template (vault blank)
│   ├── web/                 捕获页与配对页 / Capture page and pairing page
│   └── *.py                 启动/设置/防火墙 / Launch, setup, firewall
└── scripts/
    ├── deploy.py            一键部署 / One-command deployment
    └── check.py             状态诊断 / Status diagnosis

不包含小程序源码。 小程序体积大、且需单独发布审核，不适合打进技能包。需要小程序的用户请另行获取。

No mini program source is included. It's large and requires separate review before publishing, so it doesn't belong in this package. Point users elsewhere if they need it.

服务端只依赖 Python 3.13+ 标准库；另建议装 qrcode 用于本地生成二维码（缺失时回退静态兜底图）：

The server depends only on the Python 3.13+ standard library. Installing qrcode is recommended so QR codes are generated locally (falls back to a bundled static image if absent):

python -m pip install qrcode

deploy.py 会尝试自动安装它；用 --no-deps 可跳过。

deploy.py tries to install it automatically; pass --no-deps to skip.