# AI Term Research

## English

AI Term Research is a desktop-only plugin for explaining unfamiliar companies, technologies, and supply-chain terms. Select a term in a note and use Search and Deep Research from the editor context menu. Review the cited results in the side panel, then decide whether to insert a link or save a knowledge card.

The plugin supports OpenAI Responses, OpenAI-compatible Chat Completions endpoints (including CPA accounts with `web_search`), and GLM. Configure the provider and API key in the plugin settings. Keys are stored through Obsidian SecretStorage and are never written to prompts, logs, or `data.json`.

AI Term Research 是仅支持 Obsidian 桌面端的术语研究插件。选中公司、技术、产业链等陌生名词后，可从右键菜单执行“搜索”或“深入研究”，结果在侧边面板的“概览 / 报告 / 来源”中展示，再由用户决定是否插入当前笔记或保存成知识卡片。

## 环境与安装

- Obsidian 1.13.0 或更高版本。
- Node.js 22.22.2 LTS 或更新的受支持版本用于本地构建。
- 已发布到 Obsidian Community Directory 时，可在设置 → 社区插件中搜索 `AI Term Research` 并安装；开发或测试时，也可以把 `manifest.json`、`main.js`、`styles.css` 三个文件手动放入 Vault 的 `.obsidian/plugins/ai-term-research/`。
- 开发命令：`npm install`、`npm test`、`npm run build`、`npm run verify`。

## 配置与工作流

设置页可选择默认 Provider（OpenAI 或智谱 GLM），并配置对应模型、Base URL、搜索上下文、超时、最大查询数和知识卡片目录。OpenAI 配置还有两种明确的接口模式：`OpenAI Responses（官方）` 调用 Responses API；`CPA Chat Completions（兼容）` 调用 Chat Completions 并声明 `web_search`。默认仍是官方 Responses，不会自动根据 Base URL 猜测或切换模式。

API Key 只能通过 Obsidian 的 SecretComponent 选择或创建，并由 SecretStorage 读取。它不会进入提示词、日志或 `data.json`；`data.json` 只保存 secret ID。联网请求时，密钥只作为 `Authorization` 认证头发送给用户配置的 endpoint。源码和测试夹具也不能包含真实密钥。解除 SecretComponent 关联会保存为空 ID，下一次研究在联网前提示缺少 Key。搜索超时的可设范围是 10–120 秒；CPA 联网搜索可能等待更久，建议设为 120 秒。

“搜索”执行一次带来源的快速检索，适合即时名词解释。“深入研究”按查询计划多轮检索、核对来源并整理冲突与待验证项，通常约需 1–3 分钟。两种工作流都只默认发送选中的术语；仅当用户明确开启设置时才附带当前段落。深入研究的综合阶段仍会联网调用 Provider，并在请求正文中发送本次已收集的证据；该请求不再声明或执行 `web_search`。综合失败时会复用已完成查询。若整套查询没有得到有效来源，点击重试会从初始查询重新开始，避免重复使用已耗尽的检查点。

CPA 搜索的来源是模型在严格 JSON 内返回的元数据，而不是独立的工具注解。插件只接受可解析、可去重的 HTTP(S) URL，并会限制报告中的引用；若 CPA 没有返回任何可验证 URL，本次搜索会失败，不会把无来源内容当作已联网结果。

分类置信度低于 60% 时，快速搜索和深入研究都会先归入“其他”，并在保存前提示人工确认；60% 及以上保留模型分类。侧边栏修改分类后，建议路径和保存预览会同步使用人工选择。Provider 报告中未出现在已验证来源元数据里的 Markdown 链接、图片、URI 和 Obsidian wikilink/embed 会在代码块之外被去链接化，并写入“待验证与不确定性”。

## 六类知识卡片

研究结果会分类并保存到对应目录：

- 公司：定位、市场与代码、收入结构、产业链位置、竞争力、风险和跟踪指标。
- 技术：定义、问题、原理与指标、成熟度与替代路线、产业链参与者和风险。
- 产业链：范围、上中下游、价值量、供需驱动、主要公司和风险指标。
- 人物：身份、组织、贡献、时间线、公开观点和争议。
- 概念：定义边界、易混淆概念、例子、场景、当前笔记关系和相关条目。
- 其他：一句话解释、背景、核心要点、关注原因、相关实体和不确定性。

保存前始终展示完整目标路径、分类、文件名、wikilink 替换 diff，以及引用不完整、来源冲突和 Provider 警告。目标不存在时只能“创建卡片”或“取消”；同名目标存在时只能选择“打开已有卡片”“追加本次研究”“另存副本”或“取消”。追加使用原子读改写并保留旧内容；副本从 `-研究-2` 起寻找空闲名称；任何路径都不会自动覆盖已有文件。只有创建成功后且原选区仍未变化，才会把原词替换为 wikilink；追加和副本不替换原文。

## 隐私、费用与限制

插件不会在提示词中发送整篇笔记、Vault 中其他文档、目录索引、历史卡片全文或 API Key；API Key 只在 `Authorization` 头中发送给配置的 endpoint。联网调用可能产生供应商费用，所有事实和引用仍需人工核验。取消会立即停止本地编排、忽略迟到结果并阻止写入，但 Obsidian `requestUrl` 没有稳定的传输级中止合同，因此不能保证已发出的请求停止或不再计费。

真实 Obsidian、真实 Provider、网络与账户配额的端到端验收必须由用户手动执行。本仓库自动测试只覆盖隔离夹具和本地合成 Vault。详见 [隐私说明](docs/privacy.md) 与 [测试和人工验收](docs/testing.md)。