# KnowledgeHub Mobile Capture

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

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

## 系统边界

```mermaid
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`。路径由服务端生成，客户端不能指定：

```text
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 手机端正式认证方案**。

```powershell
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 代替这一认证流程。完整步骤见 [部署说明](docs/DEPLOYMENT.md)。

OpenAI 官方资料：

- [插件 MCP 认证](https://developers.openai.com/plugins/build/auth)
- [连接并测试插件](https://developers.openai.com/plugins/deploy/connect-chatgpt)
- [插件架构](https://developers.openai.com/plugins/concepts/plugins)

## 安全原则

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

## 与 KnowledgeHub 的关系

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

## License

[MIT](LICENSE)