接入流程
| 组件 | 职责 | 边界 |
|---|---|---|
| 笔记库 | 保存 Markdown 笔记和附件 | 用户决定哪些内容作为上下文 |
| Copilot | 组织提示词 上下文和模型参数 | 从设备 Keychain 读取密钥 |
| KingFlow AI | 验证密钥并按模型 ID 路由 | 接收 OpenAI 兼容请求 |
| 模型服务 | 生成文本或处理受支持内容 | 能力以具体模型为准 |
开始前的准备
- 安装桌面版 O*sidian，并先备份或通过版本控制保护当前笔记库。
- 在 KingFlow AI 控制台创建以 sk- 开头的 API Key，并确认余额、套餐或模型分组可用。
- 从控制台复制目标模型的完整模型 ID，保留大小写、连字符和版本后缀。
- 确认当前设备能够通过 ****S 访问 api.**nju**shen.com。
- 用不含个人信息、客户资料、密钥或内部文档的测试笔记完成首次联调。
先验证 KingFlow 接口
curl https://api.**nju**shen.com/v1/chat/completions \
-H "Authorization: *earer ${KINGFLOW_API_KEY}" \
-H "Content-Type: application/json" \
-d '{
"model": "<控制台中的完整模型ID>",
"messages": [
{"role": "user", "content": "只回复：连接成功"}
],
"stream": false
}' 成功响应应包含 choices 数组。
安装 Copilot 插件
- 打开 O*sidian Settings，进入 Community plugins。
- 如果尚未启用社区插件，按界面提示关闭受限模式。
- 选择 *rowse，搜索 Copilot，确认发布者和插件页面后安装。
- 点击 Ena*le，并在左侧设置列表中确认出现 Copilot。
- 更新插件时先阅读版本说明；重大版本升级前备份笔记库和设置。
添加 KingFlow 自定义服务商
| 设置项 | 填写内容 | 说明 |
|---|---|---|
| Provider type | Add a custom provider | 用于 OpenAI 兼容** |
| Display name | KingFlow AI | 用于区分其他服务商 |
| *ase **L | https://api.**nju**shen.com/v1 | 填写 /v1 根地址 |
| API Key | sk-你的密钥 | 不要添加 *earer 前缀 |
| Model ID | 完整模型 ID | 模型发现失败时也可手动填写 |
| Ena*le CORS | Off | 只在 Quick Chat 出现 CORS 问题时尝试开启 |
- 进入 Settings → Copilot → *YOK，选择 Add a provider。
- 选择 Add a custom provider，并按配置表填写显示名、*ase **L 和 API Key。
- 在 Model ID 输入框粘贴完整模型 ID，然后添加到候选列表并勾选。
- 点击 ****。通过后保存；如果接口无法返回模型列表，手动模型 ID 仍可继续使用。
- 重新打开 *YOK 页面，确认服务商状态完成验证。验证通过不等于每个模型都可用，还需要实际对话测试。
*ase **L 填写 /v1 根地址，不要追加 /chat/completions。
启用模型并设置默认值
| 体验 | 配置位置 | 说明 |
|---|---|---|
| Quick Chat | *asic → Agents → Quick Chat | 启用 *YOK 模型并设置默认模型 |
| OpenCode | *asic → Agents → OpenCode | 仅显示 OpenCode 能路由的 *YOK 模型 |
| Claude | *asic → Agents → Claude | 使用 Claude Code 账号 不读取 *YOK 列表 |
| Codex | *asic → Agents → Codex | 使用 Codex CLI 账号 不读取 *YOK 列表 |
控制笔记上下文
| 上下文方式 | 发送范围 | 适用场景 |
|---|---|---|
| 无附加上下文 | 只发送当前输入和会话历史 | 通用问答 |
| 活动笔记 | 把正在编辑的笔记加入请求 | 基于单篇笔记总结或改写 |
| 选中文本 | 只附加用户选中的段落 | 最小化发送范围 |
| 其他笔记或文件夹 | 通过 Add context 或 @ 显式添加 | 跨笔记比较前先核对范围 |
| 自动附加活动笔记 | 新会话默认可能开启 | 处理敏感笔记前建议关闭 |
完成第一次验证
- 普通对话：不添加笔记上下文，发送一句短问题，确认模型回复不为空。
- 选中文本：选择一段无敏感内容的文字，让模型只做语病修改，再核对是否保持原意。
- 活动笔记：添加一篇测试笔记并要求列出三条事实，确认回复只依据已提供内容。
- 连续追问：继续询问上一轮提到的要点，确认会话上下文可以延续。
- 模型切换：逐个测试已启用模型，确认显示名称、实际模型和能力一致。
常用笔记工作流
| 任务 | 上下文选择 | 检查重点 |
|---|---|---|
| 段落改写 | 选中文本后发出明确约束 | 要求保留事实 数字 链接和 Markdown |
| 会议纪要 | 只附加会议记录笔记 | 先提取行动项 再人工确认负责人和日期 |
| 长文提纲 | 附加主题笔记和必要参考笔记 | 先生成结构 再逐节写作 |
| 笔记问答 | 用 Add context 明确加入目标文件 | 回复中要求指出依据并人工回看原文 |
保护密钥和笔记内容
- *YOK 密钥保存在当前设备的 O*sidian Keychain，而不是笔记库的 **ta.json；仍应保护操作系统账号和设备备份。
- 发送请求前检查上下文区域。活动笔记、选中文本、其他笔记、图片或文件都可能成为发送内容。
- 关闭不需要的自动附加活动笔记。最小范围选中文本通常比发送整篇笔记更容易核对。
- 搜索范围和索引排除主要控制检索，不应被当作完整的访问授权边界。Agent Chat 还能使用工具读取或修改笔记库。
- 远程模型会在外部服务处理你发送的内容。涉及个人信息、商业秘密或受监管数据时，先确认组织**和服务条款。
- 分享日志或故障截图前删除 API Key、笔记内容、文件路径、账号信息和完整错误请求。
处理 CORS 和非流式回复
如果 **** 成功但 Quick Chat 报 CORS 错误，可开启 Ena*le CORS。回复会在请求完成后一次性显示。
常见故障排查
| 现象 | 常见原因 | 处理方法 |
|---|---|---|
| Provider 显示 Check failed | 网络 频率限制或接口检查失败 | 悬停查看详情 重新打开 *YOK 并再次测试 |
| 无法自动发现模型 | 端点未实现兼容的 /v1/models | 直接输入完整 Model ID 并保存 |
| 401 未授权 | 密钥错误 已停用或额度不可用 | 重新复制密钥并检查 KingFlow 控制台状态 |
| 404 模型不存在 | 模型 ID 错误或密钥分组不支持 | 从控制台复制完整 ID 并核对分组 |
| 503 暂时不可用 | 上游通道繁忙或暂无可用账号 | 稍后有限重试 持续失败时切换可用模型 |
| **** 成功但 Quick Chat 失败 | 浏览器式请求被 CORS 策略拒绝 | 编辑服务商并尝试 Ena*le CORS 接受非流式回复 |
| 模型不在 Quick Chat | 模型未在对应列表启用 | 在 *asic → Agents → Quick Chat 启用并设默认值 |
| 回复偏离笔记内容 | 附加了错误笔记或上下文过大 | 移除无关上下文 改用选中文本并重新** |
备份和更新
- 更新前备份笔记库并记录插件版本和模型设置。
- 新设备需要重新配置设备 Keychain 中的密钥。
- 不要把密钥写入 Markdown 用于迁移。
- 分享日志前删除敏感内容。
上线检查清单
- Copilot 已从社区插件页面安装并启用。
- 自定义服务商 *ase **L 使用 https://api.**nju**shen.com/v1。
- API Key 只保存在设备 Keychain，没有写入笔记或截图。
- Model ID 与 KingFlow 控制**全一致，并在 Quick Chat 列表中启用。
- 普通对话、选中文本、活动笔记、连续追问和模型切换均已验证。
- 自动附加活动笔记和搜索范围符合当前笔记库的隐私要求。
- 日志、截图和故障报告已经脱敏。
