KnowledgeHub Mobile Capture

“云飞随手记”的手机端写入服务与 OpenAI 插件包。它把手机 ChatGPT 中的文字、语音转写和附件，以只新增、不覆盖的方式写入用户自己的 GitHub 私有 KnowledgeHub 仓库。

当前状态：代码与本地测试基线已具备；只有完成公网部署、OAuth 配置和手机实机验收后，个人 KnowledgeHub 才能把“手机随手记”标记为已启用。

系统边界

flowchart LR
    A["手机 ChatGPT\n云飞随手记"] -->|"OAuth + MCP"| B["Mobile Capture 服务"]
    B -->|"仅创建新文件"| C["GitHub 私有 KnowledgeHub"]
    C -->|"git pull"| D["本地 KnowledgeHub"]
    D --> E["Obsidian"]
    D --> F["Codex"]

服务只注册一个写工具：create_quick_capture。路径由服务端生成，客户端不能指定：

00-Inbox/Human/Quick-Captures/YYYY/MM/<时间戳>-<随机标识>.md
10-Sources/Attachments/Quick-Captures/YYYY/MM/<capture-key>/<文件名>

记录内容不会被当作命令执行，也不会自动整理、归档或创建任务。成功必须返回 stored: true、知识库路径和 Git commit SHA。

仓库组成

• src/：MCP HTTP 服务、OAuth/API Key 校验、GitHub create-only 写入。
• plugins/knowledgehub-mobile-capture/：可安装插件清单与手机捕获 Skill。
• test/：路径边界、附件限制、create-only、失败语义测试。
• docs/DEPLOYMENT.md：正式手机端部署和连接步骤。
• docs/ACCEPTANCE.md：启用前必须完成的验收。

本地开发验证

本地 API Key 模式只用于开发和 Codex 调试，不能作为 ChatGPT 手机端正式认证方案。

Copy-Item .env.example .env
# 编辑 .env 后，把变量导入当前终端
npm install
npm test
npm start

健康检查：GET http://localhost:8787/health。MCP 入口：POST http://localhost:8787/mcp，请求头为 Authorization: Bearer <CAPTURE_API_KEY>。

正式手机端

正式模式必须设置 AUTH_MODE=oauth-jwt，使用支持 MCP OAuth 2.1 的身份提供方，并部署到公网 HTTPS。ChatGPT 不支持用用户自定义 API Key 代替这一认证流程。完整步骤见 部署说明。

OpenAI 官方资料：

• 插件 MCP 认证
• 连接并测试插件
• 插件架构

安全原则

• GitHub Token 只存放在部署平台的 Secret 中，不进入仓库、插件或聊天。
• Token 仅授权目标私有 KnowledgeHub 仓库的 Contents 读写。
• 服务不提供修改、移动、覆盖或删除工具。
• OAuth 模式强制校验发行方、受众、权限范围和用户 sub 白名单。
• 附件默认最多 5 个、单个 10 MiB、合计 20 MiB；文字默认最多 1 MiB。
• 附件已创建而最终笔记失败时不自动删除，回执会列出待人工检查路径。

与 KnowledgeHub 的关系

• KnowledgeHub-Framework 定义契约。
• KnowledgeHub-Setup 负责可选安装和引导。
• 本仓库实现手机远程入口，不保存用户资料或凭据。
• 用户自己的私有 KnowledgeHub 是唯一资料权威。

License

MIT