> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.alephant.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.alephant.io/_mcp/server.

# 印象笔记（国内版）

> 使用 Developer Token 将指定的印象笔记笔记本以只读、增量方式接入艾维斯知识库。

印象笔记（国内版）连接器使用印象笔记官方 **Developer Token** 和 NoteStore API，不走 OAuth。连接器只索引 Developer Token 所属账号中指定的一个笔记本；笔记本附件可作为笔记的子文档进入索引。

## 适用范围与工作方式

* 服务地址必须使用印象笔记国内版 `app.yinxiang.com`（不要把国际版 Evernote 的地址与国内版 token 混用）。
* 连接器是只读的，不会修改印象笔记中的笔记、标签或附件。
* 首次同步从同步游标开始，后续通过 checkpoint 增量同步。
* **Yinxiang Notebook GUID** 是必填的范围字段；系统会先确认该 GUID 在当前 token 可访问的笔记本列表中，再同步该笔记本的笔记。
* 开启**包含附件**后，能读取到的资源会作为笔记的子文档索引；附件下载或解析失败会记录为单项失败，不会让其他笔记全部失效。

Developer Token 等同于访问个人印象笔记账户的钥匙。不要把 token 写入代码、Git、工单或截图；如果曾经泄露，请先在印象笔记 Developer Token 页面撤销并重新生成。

## 前置条件

1. 已有印象笔记国内版账号，并能登录 `https://app.yinxiang.com`。
2. 已确认要索引的笔记本及其内容可以被该账号访问。
3. 艾维斯部署运行在 Standard 模式，并且后端能够访问 `app.yinxiang.com` 的 NoteStore 地址。
4. 已准备管理员或有权创建连接器的账号。

## 第一步：获取 Developer Token

打开印象笔记国内版的官方 Developer Token 页面：

[印象笔记国内版 Developer Token 页面](https://app.yinxiang.com/api/DeveloperToken.action)

在页面中创建 token，并在离开页面前复制以 `S=` 开头的完整字符串。印象笔记官方文档说明，Developer Token 可以直接替代 API 调用中的 authentication token；产品环境和沙盒环境的获取地址不同，国内生产连接器应使用产品环境地址。

官方页面在没有 token 时会显示创建按钮：

![印象笔记官方 Developer Token 创建页面](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/alephantai.docs.buildwithfern.com/4a391c703afd496f2a67da3e054b05e46911e241e19ab4ea7a49359988232b5b/assets/aivis/yinxiang/developer-token-create.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260823%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260823T224406Z&X-Amz-Expires=604800&X-Amz-Signature=e53505d909117e7ab1531511a69d58c3999d51aa31a7c0c8ee0c8eb3991b9435&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

创建后页面会同时显示 Developer Token 和 NoteStore URL。下面截图来自实际的印象笔记国内版页面，token 内容已打码，不能将截图中的 token 当作示例凭据使用：

![印象笔记国内版 Developer Token 与 NoteStore URL 页面（敏感信息已打码）](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/alephantai.docs.buildwithfern.com/40c7f8222b1550bda188c9ed87ed4bfdd1182acc81a5aa64411ea4d3ce9c0216/assets/aivis/yinxiang/user-developer-token-page.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260823%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260823T224406Z&X-Amz-Expires=604800&X-Amz-Signature=2c3f976750c63777c1f09bc682b8503f8f3dfefefbfa6272300286a22b75cf10&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

官网提供的创建完成页面示例如下；它只用于说明页面位置，示例 token 不能用于连接器：

![印象笔记官方 Developer Token 创建完成页面示例](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/alephantai.docs.buildwithfern.com/eb4c01b38610b334a58c7608449d0e7d1413d9faaa50cb7bdec6db3f21aae14b/assets/aivis/yinxiang/developer-token-created.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260823%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260823T224406Z&X-Amz-Expires=604800&X-Amz-Signature=482b51d9dd1a7838c3599ae04af4bcd97c294c0ba225517cd314531886108857&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

官方开发者文档还提供了创建完成后的示例截图：[Developer Tokens 官方文档中的示例](https://dev.yinxiang.com/doc/articles/dev_tokens.php)。

## 第二步：填写 NoteStore URL

Developer Token 页面中的 **NoteStore URL** 是连接器调用 EDAM/Thrift NoteStore 的地址，请完整复制，不要改成普通网页地址。国内版通常形如：

```text
https://app.yinxiang.com/shard/{shardId}/notestore
```

其中 `{shardId}`（例如 `s7`）必须以 token 页面显示的值为准。不要把下面这些地址填入 NoteStore URL：

* `https://app.yinxiang.com`（普通网页首页）
* `https://app.yinxiang.com/api/DeveloperToken.action`（token 管理页）
* `https://sandbox.yinxiang.com/...`（沙盒地址，除非 token 也是沙盒 token）

## 第三步：获取 Notebook GUID

Notebook GUID 是印象笔记为笔记本分配的全局唯一标识符，不是笔记本名称、账号 ID 或 shard ID。官方数据模型文档说明，核心 NoteStore 对象在创建时都会获得 GUID，GUID 在对象生命周期内保持不变。

推荐使用下面任一方式获取：

### 方式 A：在本地调用 `listNotebooks`

使用与 token 页面相同的 NoteStore URL，调用官方 NoteStore API 的 `listNotebooks`，从返回的 `Notebook` 对象中复制目标笔记本的 `guid` 字段。Python 示例（仅展示读取，不会修改笔记）：

```python
from evernote.edam.notestore.NoteStore import Client
from thrift.protocol.TBinaryProtocol import TBinaryProtocol
from thrift.transport.THttpClient import THttpClient

token = "<developer-token>"  # 从印象笔记 Developer Token 页面复制；不要提交到代码库
note_store_url = "https://app.yinxiang.com/shard/s7/notestore"

transport = THttpClient(note_store_url)
note_store = Client(TBinaryProtocol(transport))
for notebook in note_store.listNotebooks(token):
    print(notebook.name, notebook.guid)
```

### 方式 B：通过官方 SDK/接口查看

官方 Python 快速入门使用 `EvernoteClient.get_note_store()` 获取 NoteStore，并通过返回对象的 `guid` 属性识别笔记本。官方 API 参考中的 `NoteStore.getNotebook(authenticationToken, guid)` 也明确把 notebook GUID 作为查询笔记本的参数。

如果账号只有一个可访问笔记本，连接器可以在旧配置中推断它；当前管理界面将 GUID 作为必填项，建议始终显式填写，避免误索引错误范围。

## 第四步：在艾维斯中创建连接器

打开管理后台：

`/admin/add-connector`

选择 **印象笔记**，按下表填写：

| 字段                       | 填写内容                     | 校验要点                                                      |
| ------------------------ | ------------------------ | --------------------------------------------------------- |
| 连接器名称                    | 便于管理员识别的名称，例如“印象笔记-产品文档” | 不要在名称中写 token。                                            |
| Yinxiang Developer Token | 完整粘贴 `S=` 开头的 token      | 必须与 NoteStore URL 属于同一环境和同一账号。                            |
| Yinxiang NoteStore URL   | 从 token 页面复制的完整 URL      | 通常为 `https://app.yinxiang.com/shard/{shardId}/notestore`。 |
| Yinxiang Notebook GUID   | 目标笔记本的 `guid` 字段         | 必填；必须存在于该 token 的 `listNotebooks` 返回结果。                   |
| 包含附件                     | 按需启用                     | 启用后附件作为笔记子文档索引。                                           |
| 文档访问权限                   | 按知识范围选择                  | 印象笔记账号权限不会自动变成艾维斯用户权限，仍需配置艾维斯访问范围。                        |

保存后，先运行一次索引尝试，再检查新文档数、文档总数和错误消息。

## 验证清单

1. 连接器创建成功，凭据字段保存后不以明文回显。
2. 索引尝试状态为成功，且文档总数大于 0（目标笔记本确实有笔记时）。
3. 用目标笔记本中已知的标题和正文关键词搜索，确认来源链接指向印象笔记。
4. 搜索另一个未配置 GUID 的笔记本中的独有关键词，确认不会命中。
5. 开启附件后，用一个小型、可解析的附件验证其作为子文档出现。
6. 修改测试笔记，等待下一次增量同步，确认更新可检索。

## 常见问题

| 现象                                               | 原因与处理                                                                          |
| ------------------------------------------------ | ------------------------------------------------------------------------------ |
| `Yinxiang Notebook GUID` 校验失败                    | GUID 不是笔记本名称、shard ID 或笔记 GUID；重新用 `listNotebooks` 获取，并确认 token 可访问该笔记本。       |
| `The authorized Yinxiang notebook was not found` | NoteStore URL、token、GUID 不属于同一账号/环境，或笔记本已删除/不可访问。                              |
| `DATA_CONFLICT` 与 `notebookFilter` 相关            | 国内 NoteStore 对带 notebook filter 的同步请求可能拒绝；连接器会先同步通用增量块，再在本地按 Notebook GUID 过滤。 |
| 创建连接器时报 token/URL 错误                             | 检查 token 是否完整、NoteStore URL 是否为 `/shard/.../notestore`，以及是否混用了 sandbox 与产品环境。  |
| 有笔记但附件缺失                                         | 确认已启用包含附件，并检查附件是否能被 NoteStore 返回及被艾维斯解析。                                       |

## 官方参考

* [印象笔记开发者文档](https://dev.yinxiang.com/doc/)
* [开发者 Tokens](https://dev.yinxiang.com/doc/articles/dev_tokens.php)
* [术语表：Dev Token、Notebook、NoteStore](https://dev.yinxiang.com/support/glossary.php)
* [数据模型与 GUID](https://dev.yinxiang.com/doc/articles/data_structure.php)
* [Python 快速入门](https://dev.yinxiang.com/doc/start/python.php)
* [NoteStore API 参考](https://dev.evernote.com/doc/reference/NoteStore.html)
* [产品环境 Developer Token 页面](https://app.yinxiang.com/api/DeveloperToken.action)

## 相关页面

* [连接器与索引](/aivis/knowledge/connectors)
* [索引设置](/aivis/knowledge/index-settings)
* [用户、群组与角色](/aivis/governance/users-and-groups)