# Inline Predict — Obsidian 行内智能补全

[English](README.en.md)

Inline Predict provides context-aware AI autocomplete for Markdown notes in Obsidian, with inline suggestions, partial acceptance, and OpenAI-compatible providers.

在 Markdown 编辑器中，用灰色文字预览接下来可能要写的内容。按 **Tab** 接受，按 **Esc** 忽略，也可以只接受一个字词、一句或一行。

Inline Predict 专注于写作时的行内补全。你使用自己配置的 OpenAI-compatible 模型服务；插件负责选择触发时机、限制上下文、复用已有建议，并在本地记录用量。

**当前版本：0.1.3 测试版，需 Obsidian 1.13.0 或更新版本。**

## 功能

- **原生灰字预览**：基于 CodeMirror 6 装饰，接受之前不修改笔记。
- **光标前后文补全**：同时参考前文和后文，支持多行建议。
- **分步接受**：全部、下一字词、下一句、下一行；中日文的“字词”目前按单个字符推进。
- **自动与手动预测**：根据打字节奏、句段边界和近期请求延迟调整等待时间；默认从 2 个前文字符开始考虑预测，可在设置中调整。
- **缓存与连续复用**：输入与建议一致时显示剩余部分；原始前后文改变后失效。
- **结果检查**：拒绝重复、无效或无法修复的截断结果；可选本地跑题过滤和模型相关性复核。
- **本地诊断**：分别显示预测次数、模型调用次数、输入/输出用量、缓存复用和延迟；区分供应商用量、估算和未知用量。
- **中文 / English 界面**：跟随 Obsidian 界面语言。

## 安装

如果使用发布附件，将 `main.js`、`manifest.json`、`styles.css` 放入：

```text
你的仓库/.obsidian/plugins/inline-predict/
```

重新加载 Obsidian，在 **设置 → 第三方插件** 中启用 **Inline Predict**。

请从 GitHub Releases 下载上述独立附件。GitHub 自动生成的 Source code 压缩包是源码，不是可直接安装的插件包。

## 配置模型

打开 **设置 → Inline Predict → 模型**，填写：

| 配置 | 填写方式 |
| --- | --- |
| API 地址 | OpenAI-compatible 服务的基础地址，例如 `https://api.openai.com/v1`；不包含 `/chat/completions` |
| API Key | 服务商提供的密钥；免密本地服务也需要填占位值，例如 `local` |
| 模型 ID | 服务商支持的具体模型 ID |
| 推理强度 | 默认不发送此参数；仅在服务商支持时设置，具体值以服务商说明为准 |

点击 **测试连接**，成功后回到笔记输入。连接测试只发送固定短提示，不包含笔记内容；显示的是一次完整请求的往返耗时，包含服务端处理时间。

模型配置改变会立即清除旧候选和缓存，旧请求的迟到响应不会再显示。没有配置密钥或模型时，不发送补全请求。

## 使用

| 操作 | 效果 |
| --- | --- |
| 停顿输入 | 满足上下文条件时自动预测 |
| Tab | 接受全部灰字；无建议时保留原生行为 |
| Esc | 忽略建议；无建议时保留原生行为 |
| 命令：立即预测 | 手动预测，可为命令设置快捷键 |
| 命令：接受下一个字词 / 句子 / 行 | 只插入对应部分，保留剩余灰字 |
| 命令：切换行内预测 | 开关补全 |

### 自动与手动预测

自动预测默认开启，但不在每次按键时都请求模型。连续快速输入会延长等待；句尾、段落等边界会缩短等待。最近服务响应较慢时，也会适当增加等待时间。

默认至少有 2 个前文字符才考虑自动请求，普通笔记与临时缓冲区使用相同门槛。可在设置中调整该数值；已有配置会保留原来保存的值。使用“立即预测”命令可以绕过这个上下文门槛，但仍遵守总开关、输入法保护和错误退避。可以在 Obsidian 的快捷键设置中为该命令绑定按键。

如果只希望主动请求，在“补全”里关闭“自动预测”，保留补全总开关。

### 分步接受与输入法

- Tab 接受整段建议；没有建议时，插件不占用 Tab。
- Esc 忽略当前建议；没有建议时保留原生行为。
- “接受下一个字词”：拉丁文本按字词推进；汉字、假名目前每次接受一个字符。
- “接受下一句”：识别 `。！？` 等结束符；不执行日语词法分析。
- “接受下一行”：包含该行末尾的换行符。

连续输入与灰字相同的内容，会保留尚未输入的余文，不再请求模型。修改原始前后文、切换文件或更改模型配置后，旧建议会失效。

中文输入法组合输入期间隐藏灰字并暂停接受。移动端触控入口已经实现，但 iOS/Android 的键盘和触控行为尚未真机确认。

## 结果检查

光标位于文中时，模型会收到预算内连续的“前文 `<cursor/>` 后文”片段，并被要求只返回缺口的内容。过滤和可选模型复核也参考后文；是否需要插入、如何衔接已有后文由模型结合上下文判断，不按后文重词做本地拦截。连接后文所需的空格、换行会保留。若预算无法保留后文，该次预测会跳过。

输出会先检查完成状态、重复前文、控制标记和长度。达到输出 Token 上限而被截断的文本，只在能保留完整边界时降级使用，否则不展示。

本地跑题检查仅针对较短的中文上下文与较长建议，主要检查汉字词面重合；纯假名、英文和较长上下文不在这条规则的完整覆盖范围内。启用“模型复核”时，可疑建议会再通过一次 YES/NO 请求判断，增加模型调用和等待时间。两项开关修改后立即生效。

没有建议可能是合理结果。模型没有合适续写、候选被过滤或上下文预算不足时，插件会保持安静。生成内容仍需要用户判断事实与措辞。

## 用量与诊断

| 指标 | 含义 |
| --- | --- |
| 预测次数 | 已完成的逻辑预测，包含失败、取消和因编辑变化而过期的尝试 |
| 模型调用次数 | 实际调用适配器的次数，补全与相关性复核分别计数 |
| 调用失败 | 模型服务请求失败；主动取消不作为服务失败 |
| 输入 / 输出 Token | 已获得的供应商用量或明确标记的本地估算 |
| 用量未知 | 已调用但没有收到可用于统计的结果，例如超时或取消 |
| 缓存 / 前缀复用 | 使用已有建议的次数，不是新模型调用 |
| 接受率 | 被接受过的候选数 / 展示过的候选数；同一候选连续部分接受只计一次采纳 |
| 部分接受比例 | 部分接受操作在全部接受操作中的占比，与候选接受率不同 |
| 延迟 | 最近已完成、非失败预测的耗时分布；不包含自动触发前的等待 |

统计仅在当前插件会话内保留。过期结果不展示，但其已知用量仍会记入。取消请求无法保证服务商停止处理，未知用量也不等于零费用。存在未知用量时，不给出可能低估的总费用数字；当前设置界面尚无价格配置入口。

## 隐私与费用

- 配置并启用补全后，光标附近的笔记内容会发送到你选择的模型服务，受到上下文预算限制。
- 可疑结果启用模型相关性复核时，可能再发送一次包含少量上下文和候选的请求。
- **API Key 以明文保存在插件的 `data.json` 中**。同步或分享 Obsidian 配置目录时请注意这一点。
- 统计仅保存在本地内存，重启后重新计数；没有遥测上传。
- 拒绝、取消或丢弃建议不代表服务商没有计费。诊断会保留已知用量，并明确显示用量未知的调用。
- 不会扫描或上传整个笔记库。

## 已知限制

- 采用非流式生成，完整建议返回后一起显示。
- 多行灰字的换行布局可能与实际插入后的文本略有不同。
- Token 预算使用启发式估算，服务商返回的 usage 才是实际用量依据。
- 跑题过滤只覆盖特定短中文上下文；不保证事实正确，也没有完整日语分词。
- Windows、Linux、iOS、Android 及最低 Obsidian 版本尚未完整实测。`isDesktopOnly: false` 表示代码遵循移动端约束，不是兼容性保证。
- 目前没有路径排除列表。处理不希望发送给模型的笔记时，可以先关闭补全。

## 常见问题

**连接正常，但没有灰字**

检查补全总开关和自动预测开关。尝试在较长的测试笔记中手动预测。连接测试成功只说明短请求可用，不保证真实补全的上下文长度、输出上限和参数都合适。

**经常超时或输出为空**

检查模型和推理参数是否适合短续写。推理模型可能在生成可见文字前消耗输出额度；具体关闭方式以服务商文档为准。也可适当调整超时、输出上限和等待时间。

**刚修改了模型，旧结果又出现**

本版本会立即清缓存、隐藏旧候选并取消旧请求的展示资格。如仍可复现，请记录操作步骤、版本和本地诊断，不要提交 API Key。

**如何测试日文**

分别测试汉字假名混写与纯假名，并使用同一模型和相同触发方式。关注续写是否自然、是否保持文字形式，以及逐字/逐句接受是否顺手。当前没有“日文优于其他插件”的实测结论。

## 反馈

反馈问题时请附 Obsidian 版本、系统、编辑模式、模型服务和复现步骤。不要附 API Key 或私密笔记原文。

采用 [MIT License](LICENSE)。