介绍
# Confidant
安全地接收来自人员的机密信息 —— 无聊天暴露，无复制粘贴，无历史泄露。
## 🚨 关键流程 — 请先阅读此内容
这是一个 **人机协同** 过程。你无法自己检索机密信息。
1. **运行脚本** → 你将获得一个安全 URL 2. **在聊天中将 URL 发送给用户** ← 这是强制性的 3. **等待** 用户在浏览器中打开 URL 并提交机密信息 4. 脚本会处理剩下的工作（接收、保存到磁盘、确认）
``` ❌ DO NOT curl/fetch the secret URL yourself — it's a web form for humans ❌ DO NOT skip sharing the URL — the user MUST receive it in chat ❌ DO NOT poll the API to check if the secret arrived — the script does this ❌ DO NOT proceed without confirming the secret was received ✅ Share URL → Wait → Confirm success → Use the secret silently ```
## ⚡ 快速开始
你需要来自用户的 API 密钥？只需一条命令：
```bash {skill}/scripts/request-secret.sh --label "OpenAI API Key" --service openai ```
该脚本会处理一切： - ✅ 如果服务器未运行则启动它（或复用现有服务器） - ✅ 创建一个带有 Web 表单的安全请求 - ✅ 检测现有隧道（ngrok 或 localtunnel） - ✅ 返回用于分享的 URL
**如果用户是远程的**（不在同一网络上），请添加 `--tunnel`：
```bash {skill}/scripts/request-secret.sh --label "OpenAI API Key" --service openai --tunnel ```
这将自动启动 [localtunnel](https://theboroer.github.io/localtunnel-www/)（无需账户）并返回一个公共 URL。
**输出示例：** ``` 🔐 Secure link created!
URL: https://gentle-pig-42.loca.lt/requests/abc123 (tunnel: localtunnel | local: http://localhost:3000/requests/abc123) Save to: ~/.config/openai/api_key
Share the URL above with the user. Secret expires after submission or 24h. ```
分享 URL → 用户打开它 → 提交机密信息 → 完成。
## 脚本
### `request-secret.sh` — 创建安全请求（推荐）
```bash # Save to ~/.config/<service>/api_key (convention) {skill}/scripts/request-secret.sh --label "SerpAPI Key" --service serpapi
# Save to explicit path {skill}/scripts/request-secret.sh --label "Token" --save ~/.credentials/token.txt
# Save + set env var {skill}/scripts/request-secret.sh --label "API Key" --service openai --env OPENAI_API_KEY
# Just receive (no auto-save) {skill}/scripts/request-secret.sh --label "Password"
# Remote user — start tunnel automatically {skill}/scripts/request-secret.sh --label "Key" --service myapp --tunnel
# JSON output (for automation) {skill}/scripts/request-secret.sh --label "Key" --service myapp --json ```
| 标志 | 描述 | |------|-------------| | `--label <text>` | Web 表单上显示的描述 **（必需）** | | `--service <name>` | 自动保存到 `~/.config/<name>/api_key` | | `--save <path>` | 自动保存到指定的文件路径 | | `--env <varname>` | 设置环境变量（需要 `--service` 或 `--save`） | | `--tunnel` | 如果未检测到隧道则启动 localtunnel（用于远程用户） | | `--port <number>` | 服务器端口（默认：3000） | | `--timeout <secs>` | 启动的最大等待时间（默认：15） | | `--json` | 输出 JSON 而非人类可读的文本 |
### `check-server.sh` — 服务器诊断（无副作用）
```bash {skill}/scripts/check-server.sh {skill}/scripts/check-server.sh --json ```
报告服务器状态、端口、PID 以及隧道状态（ngrok 或 localtunnel）。
## Agent 规则
1. **切勿要求用户在聊天中粘贴机密信息** —— 始终使用此技能 2. **切勿在聊天中泄露接收到的机密信息** —— 即使是部分也不行 3. **切勿直接 `curl` Confidant API** —— 请使用脚本 4. **切勿终止现有服务器** 来启动新服务器 5. **切勿尝试直接暴露端口**（公共 IP、防火墙规则等）—— 请改用 `--tunnel` 6. **务必在聊天中与用户分享 URL** —— 这是该工具的全部意义 7. **务必等待用户提交** —— 不要轮询，不要重试，不要尝试自己检索机密信息 8. 当用户处于远程时（不在同一台机器/网络上）使用 `--tunnel` 9. 对于 API 密钥，优先使用 `--service` —— 这是最整洁的规范 10. 接收后：确认成功，静默使用该机密信息
## Agent 对话示例
交互过程应该是这样的：
``` User: Can you set up my OpenAI key? Agent: I'll create a secure link for you to submit your API key safely. [runs: request-secret.sh --label "OpenAI API Key" --service openai --tunnel] Agent: Here's your secure link — open it in your browser and paste your key: 🔐 https://gentle-pig-42.loca.lt/requests/abc123 The link expires after you submit or after 24h. User: Done, I submitted it. Agent: ✅ Received and saved to ~/.config/openai/api_key. You're all set! ```
⚠️ 注意：Agent 发送 URL 并等待。它不会尝试自己去访问该 URL。
## 工作原理
1. 脚本启动一个 Confidant 服务器（或在端口 3000 上复用现有的） 2. 创建一个带有唯一 ID 和安全 Web 表单的请求 3. 可选地启动 localtunnel 以便公共访问（或检测现有的 ngrok/localtunnel） 4. 用户在浏览器中打开 URL 并提交机密信息 5. 机密信息被接收，可选地保存到磁盘（`chmod 600`），然后在服务器上销毁
## 隧道选项
| 提供商 | 需要账户 | 方式 | |----------|---------------|-----| | **localtunnel**（默认） | 否 | `--tunnel` 标志或 `npx localtunnel --port 3000` | | **ngrok** | 是（免费层） | 如果在同一端口上运行则自动检测 |
该脚本会自动检测两者。如果两者都未运行且传递了 `--tunnel`，它将启动 localtunnel。
## 高级：直接 CLI 使用
对于脚本未涵盖的边缘情况：
```bash # Start server only npx @aiconnect/confidant serve --port 3000 &
# Create request on running server npx @aiconnect/confidant request --label "Key" --service myapp
# Submit a secret (agent-to-agent) npx @aiconnect/confidant fill "<url>" --secret "<value>"
# Check a specific request npx @aiconnect/confidant get <id> ```
⚠️ 仅在脚本无法涵盖你的情况时才使用直接 CLI。