# 课栈：harness 安装与连接指南 本文供能够运行命令、编辑配置或连接 MCP 的助手阅读。执行范围以用户当前请求和运行环境授权为准。面向用户的入口只需提供复制安装提示词和手动配置两种选择。 ## 完成条件 1. 检测实际执行工具的系统、架构、账号和配置位置，区分桌面、WSL、SSH 与容器。 2. 安装或升级官方 CLI，校验 SHA-256，保留未知来源的现有文件和其他 MCP 服务。 3. 建立身份连接，或把用户已经说明的笔记任务合并到初次授权中。 4. 实际执行 `auth status` 和 `capabilities`；配置 MCP 后再完成协议初始化、工具发现和有效调用。 5. 需要客户端重新加载时，明确报告安装和配置状态，重新加载后再确认 MCP 可用。 首次安装验证使用身份连接和状态查询。笔记访问、修改及托管任务由用户的实际任务决定。向用户报告简短结果，保留诊断用于排错，不复制凭据或私人正文到聊天。 ## 官方入口 - 统一入口：https://kezhan.five-plus-one.com - CLI 安装清单：https://cli.kezhan.five-plus-one.com/install.json - Windows 安装器：https://cli.kezhan.five-plus-one.com/install.ps1 - Linux / macOS 安装器：https://cli.kezhan.five-plus-one.com/install.sh - Python 备用安装器：https://cli.kezhan.five-plus-one.com/install.py - 运行指南：https://mcp.kezhan.five-plus-one.com/harness.md - 契约：https://mcp.kezhan.five-plus-one.com/openapi.json - API origin：https://api.kezhan.five-plus-one.com - 远程 MCP：https://api.kezhan.five-plus-one.com/api/v1/mcp - 用户管理授权：https://notebook.kezhan.five-plus-one.com/connections ## 安装 CLI 先检查已有程序的绝对路径和版本。下载并阅读官方安装器后，在当前用户范围执行。安装器选择系统与架构，校验固定制品 SHA-256，并安装到 Windows 的 `%LOCALAPPDATA%/KeZhan/bin` 或 Unix 的 `~/.local/bin`。安装清单同时提供六种目标制品和摘要。 Windows PowerShell： ```powershell irm https://cli.kezhan.five-plus-one.com/install.ps1 | iex ``` Linux / macOS： ```sh curl -fsSL https://cli.kezhan.five-plus-one.com/install.sh | sh ``` 原生安装器维护用户 PATH。当前 harness 进程的环境可能仍缓存旧 PATH，配置 MCP 和后续命令优先使用安装结果中的绝对路径。检查 `kezhan version` 与清单一致。来源不明的同名文件保留，按具体冲突处理。Python 备用安装器只依赖标准库，也会校验摘要；路径和安装结果以其 JSON 为准。 ## 选择 MCP 方式 客户端支持 Streamable HTTP、OAuth 和自动登记时，优先配置远程 MCP URL： ```text https://api.kezhan.five-plus-one.com/api/v1/mcp ``` 使用客户端自身的配置工具或已确认的格式。保留其他连接，按自动发现文档完成 public client 登记、S256 PKCE 和授权。浏览器完成身份连接后，在任务中调用 `request_access`。MCP 的 resource / audience 是完整 MCP URL。 本地 stdio 使用已安装 CLI；CLI 与 harness 必须处于相同账号和凭据环境： ```json {"mcpServers":{"kezhan":{"command":"/absolute/path/to/kezhan","args":["mcp","serve"]}}} ``` Windows 使用完整 `.exe` 路径并正确转义。按当前客户端的实际配置结构合并，不猜测其他产品的配置位置。桌面客户端的 command 指向桌面能够启动的程序；容器内路径只供该容器使用。普通 CLI / API audience 为 `https://api.kezhan.five-plus-one.com/api/v1`，与远程 MCP 分别授权。 ## 身份连接与任务授权 基础连接默认只有 `connections.request`。本机可运行： ```sh kezhan auth login ``` 远程、容器或浏览器不在同一机器时： ```sh kezhan auth login --device --no-browser ``` 从 stderr 的 `authorization_url` JSON 事件取得授权地址，交给用户打开并核对设备代码；保持登录进程运行，等待真实成功退出。用户在第一方页面确认，由助手查询结果并继续。 默认使用操作系统凭据服务。无此服务的 POSIX 环境可明确选择 `--credential-store file`：文件位于用户配置目录，权限为 0600，目录为 0700，采用原子写入。MCP 配置使用相同选项或 `KEZHAN_CREDENTIAL_STORE=file`。令牌不放进项目、MCP JSON 或聊天。Windows 使用系统凭据存储。 若用户已经说明具体任务，可以把首次连接与笔记权限合并为一次确认： ```sh kezhan --context course-notes auth login --notebook-title "用户指定的笔记本完整名称" --profile organize --duration 2h --purpose "按用户要求整理笔记" ``` 多对象使用 `auth login --input task.json`，格式见后文任务授权。该流程采用设备授权，用户确认后 CLI 保存默认任务授权。普通笔记命令会自动携带；也可显式传 `--authorization ID`。基础连接、任务有效期、当前权限从状态查询读取。 已有连接可使用 `auth request --wait --use` / MCP `request_access` 提交任务申请。CLI 用 `--context` 或 `KEZHAN_CONTEXT` 固定任务上下文；`auth switch` 切换已批准任务。返回授权链接后等待用户确认，调用 `get_access_request` 取得批准状态、`authorizationId` 和已批准目标。通过名称申请时，同名对象由用户选择，批准后再使用返回的真实标识。基础身份连接不提供私人目录；优先使用用户给出的完整名称、笔记链接和已有授权上下文。 请求阅读与修改时申请 `notes.read` 与 `notes.edit`；改名另加 `notes.rename`，移动另加 `notes.move` 及目标位置的 `notes.create`。按需要申请附件及历史权限。托管 AI 使用独立授权和明确预算。具体范围、有效期、后续新增内容及新建笔记的处理见下文。 ## 实际调用与恢复 MCP 列出支持的工具，实际调用始终检查当前授权。确认工具发现后调用 `get_auth_status` / `get_capabilities`，核对契约版本、schemaHash 和有效任务；按用户任务取得授权后再读取对应笔记。初始连接验证不以创建笔记或付费任务代替。 整理任务先盘点元数据，再有选择地读取正文；先完成目录分页，再修改。批量读取按大小与续读位置处理，不把整个笔记库一次塞入上下文。读取最新版本和凭据，原子创建完整正文，局部编辑保留原生内容。 涉及大幅删减、附件移除、回收站或跨笔记本移动时，生成准确预览并让用户确认。多篇笔记用 `prepare_changes` 集中核对，再 `commit_changes`；检查逐项结果及 `complete`。重试保留同一请求身份，使用回执判断已经完成的内容。 字段、权限、能力限制、错误恢复、示例和完整操作 schema 见下文。只报告已经验证的状态。卸载时仅处理本次安装的程序及配置条目，笔记由平台管理。 ## 本机课栈服务 CLI 自动发现同一系统账号运行的课栈桌面版，并优先通过本机服务调用，授权在桌面版的任务确认窗口打开。未运行时可尝试唤起桌面版；无本机服务时使用 HTTPS。远程 MCP 使用服务器连接，WSL、SSH 和容器中的服务发现以实际执行环境为准。本机服务仍要求助手自己的访问凭据和用户批准的任务，不能借用桌面登录读取笔记；服务在线不代表离线可用。 ## 本机客户端发现 Windows 先执行 `kezhan desktop status`。检测到客户端时，向用户说明找到的实际位置；使用默认 `kezhan auth login` 或任务授权命令，在课栈内确认。CLI 的 `desktop_status` 诊断事件也提供位置与运行状态。不要猜测 C 盘、D 盘或要求用户按固定目录安装。 `installed:false` 时先告知未找到，再询问实际安装路径，或让用户选网页授权。用户给出路径后以 `--desktop-path "实际路径\课栈笔记.exe"` 核对并传给授权命令；`KEZHAN_DESKTOP_PATH` 也可用于 stdio MCP。不要为了获取链接给本机默认登录附加 `--print-url`；该选项与 `--no-browser` 都由用户自行打开地址。远程环境继续使用设备授权链接。 ## CLI 与任务工作流 ## 任务授权 可以直接按名称申请一篇笔记的权限： ```sh kezhan auth request --notebook-title "笔记本的完整名称" --note-title "笔记的完整标题" --profile edit --purpose "整理这篇笔记" --wait --use ``` 初次登录也可合并具体任务，在同一授权页面确认： ```sh kezhan auth login --notebook-title "笔记本的完整名称" --note-title "笔记的完整标题" --profile edit --duration 2h --purpose "补充例题" ``` 合并任务的初次登录采用设备授权，适用于本机及远程环境。用户确认后，CLI 记录这项默认任务授权，后续笔记命令自动携带。任务到期后，基础身份连接仍可用于申请新任务。 多项不同权限使用 JSON： ```json { "purpose": "整理复习笔记并创建总纲", "durationSeconds": 3600, "targets": [ {"notebookTitle":"笔记本的完整名称","noteTitle":"笔记的完整标题","scopes":["notes.read","notes.edit","notes.rename"]}, {"notebookId":"my-notebook","categoryId":"notes","scopes":["notes.read","notes.create","notes.edit"]} ] } ``` CLI 使用 `auth request --input task.json`，MCP 调用 `request_access`。返回 `requestId`、`authorizationUrl` 和状态；由用户在第一方授权页确认。之后查询 `auth request-status --request REQUEST_ID` / `get_access_request`。批准后返回 `authorizationId` 和已批准目标的真实标识；CLI 使用 `--wait --use` 将批准结果保存到当前上下文，后续命令自动携带。API 与远程 MCP 在后续调用中使用 `authorizationId`，CLI 也可用 `--authorization ID` 显式选择。 名称查询使用完整名称，忽略英文大小写。同名对象由用户在授权页选择；未批准前，接口不向助手返回匹配目录。也可以直接使用已有笔记链接中的标识。申请、批准、实际执行都检查当前账号的业务权限。 授权可精确到单篇笔记，也可以覆盖分类或笔记本。容器默认只覆盖批准时已有的笔记；`includeFuture:true` 明确包含后续新增内容。允许新建的目标也纳入本次任务新建的笔记。有效期默认一小时，可设为五分钟至八小时，且不超过基础连接有效期。 `read/edit/create/rename/move/delete/history/attachments/upload` 是 CLI 快捷名称，对应 `notes.read/notes.edit/notes.create/notes.rename/notes.move/notes.delete/history.read/resources.read/resources.upload`。移动同时需要来源的 `notes.move` 与目标位置的 `notes.create`。托管任务使用独立的笔记本授权和预算。 [外部连接管理](https://notebook.kezhan.five-plus-one.com/connections) 分别展示连接和任务授权，可随时撤销。`auth logout` 撤销当前 CLI 连接并移除本机凭据。 ## CLI 调用 选项可放在命令前后。`--input file.json` 读取结构化参数，`--input -` 从 stdin 读取；`--content-file note.md` 读取 UTF-8 正文。业务结果输出 JSON，诊断写入 stderr。`kezhan notes patch --help` 等子命令帮助列出当前契约、权限、必填字段及条件。 | 操作 | CLI | MCP / API | | --- | --- | --- | | 查看有效权限 | `capabilities` | `get_capabilities` | | 授权状态 | `auth status` | `get_auth_status` | | 笔记本与分类 | `notebooks list` / `categories list` | `list_notebooks` / `list_categories` | | 盘点与检索 | `notes list` / `notes search` | `list_notes` / `search_notes` | | 读取 / 批量读取 | `notes read` / `notes read-many` | `read_note` / `read_notes` | | 新建 / 修改 | `notes create` / `notes patch` | `create_note` / `patch_note` | | 改名 / 移动 | `notes rename` / `notes move` | `rename_note` / `move_note` | | 回收站 / 恢复 | `notes delete` / `notes restore` | `delete_note` / `restore_note` | | 历史 / 版本 / 对比 | `notes history` / `notes version` / `notes diff` | `list_note_versions` / `read_note_version` / `diff_note_versions` | | 批量整理 | `changes prepare` / `changes commit` | `prepare_changes` / `commit_changes` | | 回执 / 预览状态 | `operations get` / `operations preview` | `get_operation` / `get_preview` | 列表返回标题、位置、版本、更新时间、正文规模和已落库正文的 contentHash / nativeHash；`sort` 可为 `path`、`updatedAt` 或 `title`，默认 `path`。默认每页 100 篇，最多 100 篇。分页期间目录或可见内容版本变化会返回 `list_changed`，应重新盘点，避免漏项。先完成目录分页，再开始修改。 读取默认至多 500 行，单个片段至多 1 MB，返回 `totalLines`、`truncated`、`revision`、`readToken` 与摘要。批量读取接受 `notes:[{notebookId,categoryId,noteId,startLine?,endLine?}]`，一次最多 20 篇，总结果预算为 2 MB；逐项返回成功或错误，通过 `nextIndex` 续取，并按每篇 `truncated` 与 `nextLine` 继续读取。读取结果包含编辑能力和保留原生内容的说明。 新建直接携带正文，失败时不留下空笔记，初始版本即为完整内容： ```json {"notebookId":"my-notebook","categoryId":"notes","title":"复习总纲","content":"# 复习总纲\n\n正文。","idempotencyKey":"review-outline-001","authorizationId":"TASK_ID"} ``` 追加需要读取凭据： ```json {"notebookId":"my-notebook","categoryId":"notes","noteId":"note-example","expectedRevision":2,"readToken":"最新读取结果中的凭据","append":"## 补充例题\n\n完整例题。","idempotencyKey":"example-append-001","authorizationId":"TASK_ID"} ``` 替换使用 `patches:[{"readToken":"...","content":"替换内容"}]`。删除片段使用 `patches:[{"readToken":"...","remove":true}]`，也可明确提供空 `content`。一次可处理一至 32 个不重叠片段。读取凭据有效期 20 分钟，绑定连接、账号、笔记、版本与原文摘要。 ## 变更预览与确认 对修改、改名、移动、回收站操作或新建设置 `dryRun:true`，取得 `previewId`、变更内容、风险原因、有效期及确认链接。预览不修改正文，不消耗正式写入的幂等键。 普通修改可直接提交。大幅精简、整篇替换、附件引用移除、移入回收站、跨笔记本移动，需要用户确认准确的预览。守卫策略从 `get_capabilities.editPolicy` 读取：正文达到 400 个 Unicode 字符时，保留量低于基线的 60% 需要确认；同一任务的连续精简会累计检查。附件保护独立于文字比例。已确认并完成的精简建立新的基线。 将 `confirmationUrl` 交给用户，确认后通过 `get_preview` 查询状态，再使用原参数及 `previewId` 提交。确认绑定账号、连接、任务、对象、原版本和具体变更，至多有效 20 分钟。版本变化、方案变化、授权撤销或确认到期都需要重新核对。 原生复杂内容可以保留并追加新块；局部修改会保留未改动的原生块。不支持的修改返回 `unsupported_content`，带 `nodeType`、`nodePath`、原因和下一步。遵照读取结果的能力与限制，避免反复试探。 ## 批量整理与回执 `prepare_changes` 接受 `operations:[{"operation":"patch_note","input":{...}}]`，最多 50 项；每篇笔记每批一个操作。同一任务的调用在外层携带 `authorizationId`，各操作保留自己的版本、读取凭据和幂等键。返回整组预览，用户可一次核对。预览正文总大小限制为 2 MB。 `commit_changes` 接受 `previewId`。每篇笔记的保存为原子操作，遇到错误停止，返回已完成结果、失败项和 `nextIndex`；已经提交的修改继续保留。恢复时使用同一预览，已完成项目返回幂等回执；需要改变计划时，重新读取并预览未完成部分。 笔记写入回执中的 `committed` 表示已提交，`changed` 表示内容或位置实际发生变化，`replayed` 表示此次取得此前操作的结果。`revision` / `committedRevision` 是提交版本，`currentRevision` 是查询时的版本；`verified` 表示两者一致。内容一致的操作也保留回执，`changed:false`。 幂等键为 8–128 个字符，使用字母、数字及 `._:-`。同一次写入的重试保留参数和键；`dryRun`、`previewId` 不参与操作身份。网络中断后重试原请求或使用 `get_operation` 查询。不要因超时重新生成新键。真实笔记整理先列出重复候选，由用户确认回收站操作，不能仅按同名自动删除。 错误包含 `code/message/requestId/retryable`，参数错误另有 `details:[{field,reason}]` 和可选 `nextAction`。常见处理： | 错误 | 下一步 | | --- | --- | | `invalid_request` | 按字段路径修正参数 | | `read_token_required` / `read_token_invalid` / `read_token_expired` | 读取目标片段，获取新凭据 | | `read_token_scope_mismatch` | 使用正确连接和笔记重新读取 | | `version_conflict` / `list_changed` | 重新读取或盘点，再比较 | | `confirmation_required` | 生成预览并等待用户确认 | | `preview_mismatch` / `preview_expired` | 重新预览 | | `task_authorization_required` / `task_scope_denied` | 查询授权状态，按任务申请需要的范围 | | `unsupported_content` | 查看节点限制，使用可支持的操作或在课栈编辑 | | `rate_limited` | 遵守 Retry-After 后重试 | 退出码：0 成功，2 参数或普通请求错误，3 身份失效，4 权限不足，5 冲突，6 可重试错误。批量结果还必须检查 `complete` 和逐项 `ok`；CLI 会输出逐项结果，并在批次未完成时以退出码 5 结束。服务限制为每个连接每分钟 120 次请求、同时四项笔记修改；批量能力及限制以 `get_capabilities` 为准。 ## 资料与托管任务 ```sh kezhan --input target-note.json --file ./source.pdf resources upload kezhan --input resource.json resources inspect kezhan --input pages.json resources pages kezhan --input resource.json resources text kezhan --input job.json jobs create kezhan --input job-id.json jobs get kezhan --input job-id.json jobs cancel kezhan --input answer.json jobs answer ``` 上传参数指定目标笔记。CLI 计算文件 SHA256，服务端核对摘要和大小后上传到私有存储，完成阶段复用课栈的冻结快照、配额和资源登记。单文件至多 512 MB。上传会话有效期 20 分钟，失败时可重传同一会话。MCP 可以创建及完成上传会话，文件字节通过返回的上传路径传输。 页面索引仅用于选页，真实页面通过 `read_resource_pages` 返回，单次一至六页。区域参数为 `[x,y,width,height]`，数值采用零至一的比例。MCP 返回原生图像内容，CLI 返回包含页码的图像数据。音视频已完成的转写包含来源定位；尚未转写时通过有预算的任务处理。 任务提交示例： ```json { "notebookId": "my-notebook", "categoryId": "notes", "title": "本章资料导航", "resourceIds": ["已上传且已就绪的资源标识"], "budgetMilli": 10000, "idempotencyKey": "chapter-navigation-001" } ``` 预算单位为千分之一积分，10000 表示 10 积分。任务需要 `jobs.create`、`notes.create` 和 `resources.read`。当前托管整理使用本人拥有、位于已授权笔记本的资料，结果保存到指定分类，自动关联更新关闭。任务在客户端离线时持续运行，状态和问题持久化。 模型调用先按保守用量估计检查剩余预算，实际积分结算在事务内检查预算上限；平台付费服务也检查同一预算。用户自配供应商向其账户收取的费用由供应商管理。任务取消停止后续处理，已提交的结果继续保留。执行期间授权撤销或资料权限变化会停止外部任务。 正式课程产物使用课栈现有 SOP、独立来源核验和媒体验收。只提交稿件或媒体引用不会使正式产物自动达标。 ## 授权上下文与自动化 `--profile read` 允许阅读；`edit` 允许阅读与修改；`organize` 允许阅读、新建、修改、改名和移动。删除、历史和附件权限按需要显式添加，例如 `--profile organize --permissions delete,history`。单篇目标不附带新建权限；移动仍需为目标分类或笔记本申请 `notes.create`。模板不会扩大目标范围。 ```sh kezhan auth login --notebook-title "概率论" --profile organize --duration 2h --context probability --purpose "整理复习笔记" kezhan --context probability notes list --notebook BOOK_ID kezhan auth request --notebook-title "概率论" --profile edit --wait --use --context probability kezhan auth list kezhan auth switch --authorization TASK_ID --context probability kezhan auth renew --request TASK_ID --duration 2h --wait --use --context probability kezhan auth revoke --request TASK_ID ``` 未指定 `--context` 时，CLI 使用当前工作目录；也可设置 `KEZHAN_CONTEXT`。上下文共享同一身份连接，分别保存任务选择和待批准请求。切换目录不会自动继承另一目录的任务。`auth request-status --wait --use` 续接当前上下文保存的请求；也可显式指定 `--request`。`auth status` 展示当前上下文、默认任务与有效期。任务到期后重新申请，`auth renew` 复制原任务目标与权限供用户再次核对，批准前不能继续写入。 首次登录支持在同一页确认身份连接和任务；已有身份连接时直接申请任务权限。具体变更仍按风险预览：普通授权内编辑可直接提交，批量方案可一次核对；删除、附件移除或大幅删减需确认实际内容。 短期自动化凭据用于已经批准的任务： ```sh kezhan auth token --name "复习笔记整理" --duration 1h --context probability ``` 返回的 `access_token` 只在签发时展示，应直接存入 CI 的秘密存储，再通过 `KEZHAN_TOKEN` 注入。不要写进聊天、项目文件、日志或 MCP 配置。凭据绑定原连接、任务、目标、权限与 API 受众，截止时间取申请时长、任务期限及连接期限中的最早值；不支持刷新、申请新权限或再次委派。`auth list` 只列元数据；`auth revoke --token TOKEN_ID` 可撤销。撤销原任务或连接同样使凭据失效。发给 stdio MCP 的令牌使用 API 受众；远程 HTTP MCP 需要在其自身受众下取得凭据，两者不能互换。 `auth status` 同时返回 `contexts`，列出本机保存的各上下文、默认任务、待确认申请与当前选中项。这些是本机映射，任务是否仍有效以服务端 `auth list` 或 `request-status` 为准；退出或更换身份连接会清除原映射。 `auth token --name NAME` 返回 `name`、`tokenId`、`authorizationId`、`expiresAt`、`audience`、`refreshable:false`、`token_type:Bearer` 和 `access_token`。`access_token` 是仅在签发时返回的凭据秘密，用于 `KEZHAN_TOKEN`；`tokenId` 是查询与撤销用的标识。`auth list` 只返回元数据，使用 `auth revoke --token TOKEN_ID` 撤销。 ## 本机服务 先运行 `kezhan desktop status` 查看 `installed`、`running`、`executablePath`、`source` 和 `launchAvailable`。这些信息来自用户实际安装位置，不限定盘符。正常执行 `kezhan auth login` 时也会输出 `desktop_status` 诊断事件，授权优先在已运行或找到的客户端中打开。 如果没有找到客户端，助手应告知检测结果，再询问用户实际安装路径，或由用户选择网页授权。用户提供程序位置后，可运行 `kezhan desktop status --desktop-path "实际路径\课栈笔记.exe"` 核对，再给授权命令传入同一选项。也可设置 `KEZHAN_DESKTOP_PATH`。路径必须指向实际存在的课栈程序。桌面版 0.5.73 在安装、升级和启动时登记实际位置。 Windows 桌面版 0.5.70 起，CLI 和 stdio MCP 优先发现当前用户启动的课栈服务。任务确认在桌面版独立授权窗口中打开，使用课栈现有账号会话，页面列出对象、操作、用途与有效期。Windows CLI 1.2.2 起通过当前用户和全体用户的安装记录、应用路径与课栈协议查找实际程序，跳过不存在的旧路径，再启动客户端；本机服务不可用时，在请求发送前改用云端。已有本机服务明确拒绝请求时返回错误供核对账号，不会换入口重复写入。 本机服务用于授权呈现和传输，数据保存仍由课栈服务端完成，离线时不能提交云端笔记。CLI 使用自己的外部访问凭据，桌面 Cookie 不交给助手；首次身份连接仍需用户确认。远程 MCP、CI 与容器使用云端；本机桥接仅监听 127.0.0.1，使用每次启动生成的当前用户凭据并拒绝浏览器来源。`--no-browser` 可输出链接供用户自行打开，`--redirect-port` 保留浏览器回环登录方式。 Windows 桌面版 0.5.71 起，桌面版运行并登录时，会检查当前账号的任务申请及需要确认的变更，通常在 15 秒内发出原生 Windows 通知。点击通知在课栈授权窗口核对对象、操作、用途与有效期；仍由用户同意。通知不展示笔记标题或正文，同一申请在有效期内只提示一次。 本机 CLI 打开授权窗口时也会提示。远程 MCP 的首次身份连接尚未绑定课栈账号，使用客户端给出的链接完成连接；绑定账号后的任务申请可由桌面版提醒。桌面版关闭时，远程申请不会自行启动电脑上的程序。 系统关闭通知或开启免打扰时，可从课栈托盘菜单“待确认的授权”打开。关闭通知不等于拒绝申请。完成、撤销、到期或退出账号后，待确认入口随检查更新；点击已处理通知会重新校验并展示当前状态。 ## 盘点、回收与定位 ```sh kezhan notes outline --notebook BOOK_ID --category notes --note NOTE_ID kezhan notes list --notebook BOOK_ID --trash kezhan notes restore --last --notebook BOOK_ID --idempotency-key restore-latest-001 kezhan notes search --all --query "条件概率" kezhan locations resolve --notebook BOOK_ID --path "讲解/第二章" kezhan notes duplicates --notebook BOOK_ID kezhan operations list --since 2026-10-27T00:00:00Z --limit 20 kezhan notes activity --notebook BOOK_ID --category notes --note NOTE_ID ``` 大纲一次最多 20 篇，包含顶层块类型、标题层级、字数、链接与附件引用；每篇通过 `startBlock` / `maxBlocks` 续取，整批以 `nextIndex` 续取。需要具体段落时再按行读取。读取中不能可靠往返的块在 `editCapabilities.details` 给出类型与路径；`append` 与局部 `patch` 的适用性分别表示。 回收站列表返回删除时间、版本和 `canRestore`。`notes restore --last` 选择当前授权范围内删除时间最新且可恢复的笔记，使用回收站返回的版本恢复，可恢复先前任务删除的内容；提交时发生并发变化则重新盘点。恢复优先回到删除前的文件夹；原文件夹已不存在时回到分类根目录，回执给出 `locationAdjusted`。读取已回收且有权访问的笔记返回 `in_trash`。 移动可用 `--target-path "讲解/第二章"` 解析位置；跨笔记本再指定 `--target-notebook`。路径重名返回候选，须明确选择目标。全范围搜索只遍历已批准的可读笔记本，逐页使用返回游标。重复检测核对 Markdown 和原生内容、资源引用，返回完全相同的候选供复核，不自行删除。一次最多盘点 5000 篇；结果随内容变化应重新取得。 `operations list` 按提交时间从新到旧分页，只列当前连接与所选任务且仍有权限的结果。正文版本使用 history / version / diff；名称、位置、回收和恢复使用 `notes activity`，需要 `history.read`。活动与增量变更记录保存 30 天，本次版本起产生名称和位置事件，历史正文版本沿用原有版本接口。 ### 授权回收站内容 新任务默认只包含批准时选中的现有笔记；`includeFuture` 允许该范围以后新增的内容。要找回先前任务删除的笔记，应明确申请 `includeTrash:true`，用户确认页会显示“包含回收站中现有的笔记”。该选项只纳入批准时已有的回收站笔记，不自动扩展其他任务授权。原任务授权的笔记随后被删除时，原任务仍可在权限允许时恢复。 ```sh kezhan auth request --notebook-title "课程笔记" --include-trash --permissions read,delete,history --purpose "找回误删的课堂笔记" --context recovery --wait --use kezhan notes list --notebook BOOK_ID --trash --context recovery kezhan notes activity --notebook BOOK_ID --category CATEGORY_ID --note NOTE_ID --context recovery kezhan notes restore --notebook BOOK_ID --last --context recovery --idempotency-key restore-lesson-01 ``` MCP 对应 `request_access` 的 `targets:[{notebookId:"…",includeTrash:true,scopes:["notes.read","notes.delete","history.read"]}]`，批准后携带 `authorizationId`。也可通过 `noteId` 或 `noteTitle` 精确申请回收站中的一篇笔记。恢复使用 `notes.delete`；查看活动另需 `history.read`。 回收站按删除时间从新到旧分页，响应游标绑定任务；升级后重新开始一次分页。`canRestore:true` 要求当前授权可阅读及恢复该笔记、账号仍具备恢复权限、原分类可访问、服务端允许外部修改。`canRestore:false` 时读取 `restoreBlockedReason.code/message/nextAction`：补充权限或在课栈中选择恢复位置。最终提交仍校验最新权限、笔记版本和任务有效期。 `notes search --all` 必须选择已批准的阅读任务，未选择时返回 `task_authorization_required` 和 `nextAction:select_or_request_access`。检索只覆盖该任务，空页可能表示该页没有命中；当 `hasMore:true` 时必须继续 `nextCursor`，直至 `hasMore:false` 才能判断检索完成。 ## 增量盘点 1. 先调用 `notes changes` / `list_changes`，保存初始 `cursor`。 2. 完成 `notes list` 全部分页与必要摘要读取；列表变化时按提示重新盘点。 3. 用初始游标读取变更，直至 `hasMore:false`，保存最终游标。 4. 后续携带最后游标取得增量，应用正文、名称、移动、删除和恢复事件。 游标绑定连接、任务及筛选范围，有效期 7 天。`cursor_expired` 要求重新盘点；列表的 `snapshot` 是同一轮分页一致性标识，不是增量游标，不能用作 `changed-since`。跨笔记本移动要同时处理原位置和新位置，最终以最新目录与正文为准。 ## 回执字段与恢复 所有新写入回执保留原字段，并提供 `operationId`、`operation`、`status`、`target`、`committed`、`committedRevision`、`replayed`、`verified`。`replayed:true` 表示同一幂等请求的既有结果。`committed` 表示事务已提交；`verified` 表示已完成随后回读。`get_operation` 可以重新核验结果。 | 操作 | 主要业务字段 | | --- | --- | | create | 目标标识、title、revision | | patch | changed、changes、revision、currentRevision | | rename | title、revision，保留原来源字段 | | move | 新目标标识、来源标识、paths、revision | | delete / restore | deleted、revision；restore 可含 locationAdjusted | | changes commit | 逐项回执、complete，跨篇结果独立处理 | 参数校验错误给出字段和原因。写入超时后用原幂等键重试或查询回执，不能换键猜测提交结果。任务授权与预览不同：预览查询会按当前连接追溯原任务，无需记住额外 ID；已提交预览保持 `consumed`，已拒绝保持 `denied`。任务到期后只返回必要状态，不返回正文。提交仍要求有效任务和匹配的未到期预览。 每连接每分钟最多 120 次请求；响应头 `RateLimit-Limit`、`RateLimit-Remaining`、`RateLimit-Reset` 给出上限、剩余次数与本窗口剩余秒数，429 附带 `Retry-After`。批量调用也遵守正文和并发预算。 兼容字段 `writesEnabled` 在 v1 中继续保留，标为 deprecated；新接入使用 `writeScopesGranted`、`serverWritesEnabled` 及 `allowedOperations`。移除只会发生在下一主版本，提前至少 90 天公告并更新公开契约；当前没有确定的移除日期。新增回执字段是向后兼容扩展，调用方应忽略未知字段。 ## 升级与恢复 ```sh kezhan self-update --check kezhan self-update ``` 三个官方安装器与 self-update 使用官方清单及 SHA-256 验证，支持识别已发布的旧版，保留相邻的摘要命名备份，再安装新版本。校验失败或文件来源无法确认时保留现有文件；先核对错误再重试。Python 备用安装器提供相同升级路径，`--dest` 可指定用户目录。PowerShell 用 `-InstallDirectory`，Shell 用 `KEZHAN_INSTALL_DIR`。 升级完成后运行 `kezhan version` 和 `auth status`。需要回退时关闭相关 CLI / stdio 进程，核对备份摘要与上一版安装清单后恢复备份，或将官方旧版安装到独立目录；不要把凭据复制到二进制目录。Windows 自更新若受到正在运行的其他进程或权限限制，关闭相关命令后使用官方安装器重试。 ## 完全权限授权 助手可以用 `kezhan auth request-full --purpose "整理课程笔记" --duration 24h --wait --use` 申请完全权限。MCP 对应 `request_full_access`。用户在课栈授权页查看用途和时长，点击继续后，在弹窗中确认授权。 授权最长 24 小时，并受当前连接期限约束。有效期内可直接执行当前账号有权执行的 CLI/MCP 操作，包含读取、新建、修改、移动、回收笔记和附件操作。托管 AI 整理仍需明确预算。正文版本、并发修改和账号权限照常校验。授权绑定当前连接，不能转给另一连接。 重新申请会返回同一连接仍有效的完全权限授权及其剩余期限。延长时间通过 `renew_access` 创建新的确认请求。用户可在“外部连接”随时撤销；到期、连接撤销或账号停用后立即停止后续访问与写入。普通任务授权继续按选择的内容和操作生效。 已经确认的变更重新打开时显示已批准；已提交的变更显示提交结果。批次中的全部操作分别批准后，整批也显示已批准。 ## 验证范围 Windows x64 在本机运行验证，Linux x64 在正式容器验证；macOS、Windows ARM64 和 Linux ARM64 已构建及校对摘要，实机运行与系统凭据服务仍需验证。官方 MCP SDK 已完成 stdio 和正式 HTTPS 验证；具体第三方 harness 需要完成自身配置、OAuth 回调和工作流验收。 ## 工具参数参考 ### answer_job 回答整理任务当前提出的问题。 权限：jobs.create。 ```json { "additionalProperties": false, "properties": { "authorizationId": { "maxLength": 4096, "type": "string" }, "choiceId": { "maxLength": 4096, "type": "string" }, "jobId": { "maxLength": 4096, "type": "string" } }, "required": [ "jobId", "choiceId" ], "type": "object" } ``` ### begin_upload 为指定笔记创建私有附件上传会话，文件通过上传接口传输。 权限：resources.upload。 ```json { "additionalProperties": false, "properties": { "authorizationId": { "maxLength": 4096, "type": "string" }, "categoryId": { "maxLength": 4096, "type": "string" }, "mediaType": { "maxLength": 4096, "type": "string" }, "name": { "maxLength": 4096, "type": "string" }, "noteId": { "maxLength": 4096, "type": "string" }, "notebookId": { "maxLength": 4096, "type": "string" }, "sha256": { "maxLength": 4096, "type": "string" }, "size": { "maximum": 536870912, "minimum": 1, "type": "integer" } }, "required": [ "notebookId", "categoryId", "noteId", "name", "mediaType", "size", "sha256" ], "type": "object" } ``` ### cancel_job 停止整理任务；已保存的笔记通过结果查看。 权限：jobs.create。 ```json { "additionalProperties": false, "properties": { "authorizationId": { "maxLength": 4096, "type": "string" }, "jobId": { "maxLength": 4096, "type": "string" } }, "required": [ "jobId" ], "type": "object" } ``` ### commit_changes 执行已预览的整理方案；逐篇原子提交，遇到失败停止，可使用同一预览恢复并查询逐项回执。 权限：当前连接。 ```json { "additionalProperties": false, "properties": { "authorizationId": { "maxLength": 4096, "type": "string" }, "previewId": { "maxLength": 4096, "type": "string" } }, "required": [ "previewId" ], "type": "object" } ``` ### complete_upload 验证并完成附件上传，返回可插入笔记的引用。 权限：resources.upload。 ```json { "additionalProperties": false, "properties": { "authorizationId": { "maxLength": 4096, "type": "string" }, "uploadId": { "maxLength": 4096, "type": "string" } }, "required": [ "uploadId" ], "type": "object" } ``` ### create_job 提交课栈托管整理任务，需明确预算与资料范围。 权限：jobs.create。 ```json { "additionalProperties": false, "properties": { "authorizationId": { "maxLength": 4096, "type": "string" }, "budgetMilli": { "maximum": 100000000, "minimum": 1, "type": "integer" }, "categoryId": { "maxLength": 4096, "type": "string" }, "idempotencyKey": { "maxLength": 128, "minLength": 8, "pattern": "^[A-Za-z0-9._:-]+$", "type": "string" }, "instruction": { "maxLength": 4096, "type": "string" }, "notebookId": { "maxLength": 4096, "type": "string" }, "resourceIds": { "items": { "maxLength": 4096, "type": "string" }, "maxItems": 12, "minItems": 1, "type": "array" }, "title": { "maxLength": 4096, "type": "string" } }, "required": [ "notebookId", "categoryId", "title", "resourceIds", "budgetMilli", "idempotencyKey" ], "type": "object" } ``` ### create_note 在指定分类中新建笔记，重复调用使用同一幂等键。 权限：notes.create。 ```json { "additionalProperties": false, "properties": { "authorizationId": { "maxLength": 4096, "type": "string" }, "categoryId": { "maxLength": 4096, "type": "string" }, "content": { "maxLength": 1000000, "type": "string" }, "dryRun": { "type": "boolean" }, "idempotencyKey": { "maxLength": 128, "minLength": 8, "pattern": "^[A-Za-z0-9._:-]+$", "type": "string" }, "notebookId": { "maxLength": 4096, "type": "string" }, "parentId": { "maxLength": 4096, "type": "string" }, "previewId": { "maxLength": 4096, "type": "string" }, "title": { "maxLength": 4096, "type": "string" } }, "required": [ "notebookId", "categoryId", "title", "idempotencyKey" ], "type": "object" } ``` ### delete_note 将笔记移入回收站；先预览并由用户确认。 权限：notes.delete。 ```json { "additionalProperties": false, "properties": { "authorizationId": { "maxLength": 4096, "type": "string" }, "categoryId": { "maxLength": 4096, "type": "string" }, "dryRun": { "type": "boolean" }, "expectedRevision": { "maximum": 9007199254740991, "minimum": 0, "type": "integer" }, "idempotencyKey": { "maxLength": 128, "minLength": 8, "pattern": "^[A-Za-z0-9._:-]+$", "type": "string" }, "noteId": { "maxLength": 4096, "type": "string" }, "notebookId": { "maxLength": 4096, "type": "string" }, "previewId": { "maxLength": 4096, "type": "string" } }, "required": [ "notebookId", "categoryId", "noteId", "expectedRevision", "idempotencyKey" ], "type": "object" } ``` ### diff_note_versions 比较笔记历史版本与另一版本或当前正文。 权限：history.read。 ```json { "additionalProperties": false, "properties": { "authorizationId": { "maxLength": 4096, "type": "string" }, "categoryId": { "maxLength": 4096, "type": "string" }, "fromVersionId": { "maxLength": 4096, "type": "string" }, "noteId": { "maxLength": 4096, "type": "string" }, "notebookId": { "maxLength": 4096, "type": "string" }, "toVersionId": { "maxLength": 4096, "type": "string" } }, "required": [ "notebookId", "categoryId", "noteId", "fromVersionId" ], "type": "object" } ``` ### find_duplicates 列出授权笔记本中内容完全相同的候选，分别核对正文、原生内容及附件；删除前预览。 权限：notes.read。 ```json { "additionalProperties": false, "properties": { "authorizationId": { "maxLength": 4096, "type": "string" }, "categoryId": { "maxLength": 4096, "type": "string" }, "cursor": { "maxLength": 4096, "type": "string" }, "limit": { "maximum": 100, "minimum": 1, "type": "integer" }, "notebookId": { "maxLength": 4096, "type": "string" } }, "required": [ "notebookId" ], "type": "object" } ``` ### get_access_request 查询任务授权结果；批准后的 authorizationId 仅适用于当前连接。 权限：当前连接。 ```json { "additionalProperties": false, "properties": { "authorizationId": { "maxLength": 4096, "type": "string" }, "requestId": { "maxLength": 4096, "type": "string" } }, "required": [ "requestId" ], "type": "object" } ``` ### get_auth_status 查看当前连接的授权范围、有效期和任务授权。 权限：当前连接。 ```json { "additionalProperties": false, "properties": { "authorizationId": { "maxLength": 4096, "type": "string" } }, "required": [], "type": "object" } ``` ### get_capabilities 查看当前连接允许的操作和笔记本。 权限：当前连接。 ```json { "additionalProperties": false, "properties": { "authorizationId": { "maxLength": 4096, "type": "string" } }, "required": [], "type": "object" } ``` ### get_job 查询持久整理任务、结果和待补充问题。 权限：jobs.read。 ```json { "additionalProperties": false, "properties": { "authorizationId": { "maxLength": 4096, "type": "string" }, "jobId": { "maxLength": 4096, "type": "string" } }, "required": [ "jobId" ], "type": "object" } ``` ### get_operation 查询已提交操作的结果。 权限：当前连接。 ```json { "additionalProperties": false, "properties": { "authorizationId": { "maxLength": 4096, "type": "string" }, "operationId": { "maxLength": 4096, "type": "string" } }, "required": [ "operationId" ], "type": "object" } ``` ### get_preview 查询具体变更的预览和用户确认状态。 权限：当前连接。 ```json { "additionalProperties": false, "properties": { "authorizationId": { "maxLength": 4096, "type": "string" }, "previewId": { "maxLength": 4096, "type": "string" } }, "required": [ "previewId" ], "type": "object" } ``` ### inspect_resource 读取资料页数与文字索引；索引不代表已阅读原页。 权限：resources.read。 ```json { "additionalProperties": false, "properties": { "authorizationId": { "maxLength": 4096, "type": "string" }, "notebookId": { "maxLength": 4096, "type": "string" }, "resourceId": { "maxLength": 4096, "type": "string" }, "startPage": { "maximum": 2000, "minimum": 1, "type": "integer" } }, "required": [ "notebookId", "resourceId" ], "type": "object" } ``` ### issue_automation_token 为当前已批准任务签发受限短期凭据；继承目标、权限和截止时间，不能再次委派。 权限：当前连接。 ```json { "additionalProperties": false, "properties": { "authorizationId": { "maxLength": 4096, "type": "string" }, "durationSeconds": { "maximum": 28800, "minimum": 60, "type": "integer" }, "name": { "maxLength": 4096, "type": "string" } }, "required": [ "name" ], "type": "object" } ``` ### list_access 列出当前连接的任务授权与受限自动化凭据。 权限：当前连接。 ```json { "additionalProperties": false, "properties": { "authorizationId": { "maxLength": 4096, "type": "string" } }, "required": [], "type": "object" } ``` ### list_categories 列出已授权的笔记分类和文件夹。 权限：notes.read。 ```json { "additionalProperties": false, "properties": { "authorizationId": { "maxLength": 4096, "type": "string" }, "notebookId": { "maxLength": 4096, "type": "string" } }, "required": [ "notebookId" ], "type": "object" } ``` ### list_changes 读取授权范围内的增量变更，包含移动、删除与恢复；游标到期后重新盘点。 权限：notes.read。 ```json { "additionalProperties": false, "properties": { "authorizationId": { "maxLength": 4096, "type": "string" }, "cursor": { "maxLength": 4096, "type": "string" }, "limit": { "maximum": 100, "minimum": 1, "type": "integer" }, "notebookId": { "maxLength": 4096, "type": "string" } }, "required": [], "type": "object" } ``` ### list_note_versions 查看笔记历史版本。 权限：history.read。 ```json { "additionalProperties": false, "properties": { "authorizationId": { "maxLength": 4096, "type": "string" }, "beforeRevision": { "maximum": 9007199254740991, "minimum": 1, "type": "integer" }, "categoryId": { "maxLength": 4096, "type": "string" }, "noteId": { "maxLength": 4096, "type": "string" }, "notebookId": { "maxLength": 4096, "type": "string" } }, "required": [ "notebookId", "categoryId", "noteId" ], "type": "object" } ``` ### list_notebooks 列出已授权且当前可访问的笔记本。 权限：notes.read。 ```json { "additionalProperties": false, "properties": { "authorizationId": { "maxLength": 4096, "type": "string" }, "cursor": { "maxLength": 4096, "type": "string" }, "limit": { "maximum": 100, "minimum": 1, "type": "integer" } }, "required": [], "type": "object" } ``` ### list_notes 浏览指定笔记本目录，按游标继续读取。 权限：notes.read。 ```json { "additionalProperties": false, "properties": { "authorizationId": { "maxLength": 4096, "type": "string" }, "cursor": { "maxLength": 4096, "type": "string" }, "limit": { "maximum": 100, "minimum": 1, "type": "integer" }, "notebookId": { "maxLength": 4096, "type": "string" }, "sort": { "enum": [ "path", "updatedAt", "title" ], "type": "string" }, "trash": { "type": "boolean" } }, "required": [ "notebookId" ], "type": "object" } ``` ### list_operations 查询当前连接的近期提交回执；可按时间与笔记本筛选。 权限：当前连接。 ```json { "additionalProperties": false, "properties": { "authorizationId": { "maxLength": 4096, "type": "string" }, "cursor": { "maxLength": 4096, "type": "string" }, "limit": { "maximum": 100, "minimum": 1, "type": "integer" }, "notebookId": { "maxLength": 4096, "type": "string" }, "since": { "maxLength": 4096, "type": "string" } }, "required": [], "type": "object" } ``` ### list_resources 列出此连接在指定笔记本可读取的资料。 权限：resources.read。 ```json { "additionalProperties": false, "properties": { "authorizationId": { "maxLength": 4096, "type": "string" }, "cursor": { "maxLength": 4096, "type": "string" }, "limit": { "maximum": 100, "minimum": 1, "type": "integer" }, "notebookId": { "maxLength": 4096, "type": "string" } }, "required": [ "notebookId" ], "type": "object" } ``` ### move_note 将笔记移动到指定笔记本、分类或文件夹。 权限：notes.move。 ```json { "additionalProperties": false, "properties": { "authorizationId": { "maxLength": 4096, "type": "string" }, "categoryId": { "maxLength": 4096, "type": "string" }, "dryRun": { "type": "boolean" }, "expectedRevision": { "maximum": 9007199254740991, "minimum": 0, "type": "integer" }, "idempotencyKey": { "maxLength": 128, "minLength": 8, "pattern": "^[A-Za-z0-9._:-]+$", "type": "string" }, "noteId": { "maxLength": 4096, "type": "string" }, "notebookId": { "maxLength": 4096, "type": "string" }, "previewId": { "maxLength": 4096, "type": "string" }, "targetCategoryId": { "maxLength": 4096, "type": "string" }, "targetNotebookId": { "maxLength": 4096, "type": "string" }, "targetParentId": { "maxLength": 4096, "type": "string" } }, "required": [ "notebookId", "categoryId", "noteId", "expectedRevision", "idempotencyKey", "targetNotebookId", "targetCategoryId" ], "type": "object" } ``` ### note_activity 查询笔记正文和名称、位置、回收与恢复的活动记录。 权限：history.read。 ```json { "additionalProperties": false, "properties": { "authorizationId": { "maxLength": 4096, "type": "string" }, "categoryId": { "maxLength": 4096, "type": "string" }, "cursor": { "maxLength": 4096, "type": "string" }, "limit": { "maximum": 100, "minimum": 1, "type": "integer" }, "noteId": { "maxLength": 4096, "type": "string" }, "notebookId": { "maxLength": 4096, "type": "string" } }, "required": [ "notebookId", "categoryId", "noteId" ], "type": "object" } ``` ### outline_notes 批量读取结构摘要；返回标题层级、内容块、链接、附件与续取位置，不返回整篇正文。 权限：notes.read。 ```json { "additionalProperties": false, "properties": { "authorizationId": { "maxLength": 4096, "type": "string" }, "maxBlocks": { "maximum": 200, "minimum": 1, "type": "integer" }, "notes": { "items": { "additionalProperties": false, "properties": { "categoryId": { "maxLength": 4096, "type": "string" }, "noteId": { "maxLength": 4096, "type": "string" }, "notebookId": { "maxLength": 4096, "type": "string" } }, "required": [ "notebookId", "categoryId", "noteId" ], "type": "object" }, "maxItems": 20, "minItems": 1, "type": "array" }, "startBlock": { "maximum": 1000000, "minimum": 0, "type": "integer" } }, "required": [ "notes" ], "type": "object" } ``` ### patch_note 按已读片段局部替换，或追加正文。dryRun 预览修改摘要；版本冲突时重新读取。 权限：notes.edit。 ```json { "additionalProperties": false, "oneOf": [ { "not": { "required": [ "patches" ] }, "required": [ "append", "readToken" ] }, { "not": { "required": [ "append" ] }, "required": [ "patches" ] } ], "properties": { "append": { "maxLength": 1000000, "type": "string" }, "authorizationId": { "maxLength": 4096, "type": "string" }, "categoryId": { "maxLength": 4096, "type": "string" }, "dryRun": { "type": "boolean" }, "expectedRevision": { "maximum": 9007199254740991, "minimum": 0, "type": "integer" }, "idempotencyKey": { "maxLength": 128, "minLength": 8, "pattern": "^[A-Za-z0-9._:-]+$", "type": "string" }, "noteId": { "maxLength": 4096, "type": "string" }, "notebookId": { "maxLength": 4096, "type": "string" }, "patches": { "items": { "additionalProperties": false, "oneOf": [ { "not": { "required": [ "remove" ] }, "required": [ "content" ] }, { "not": { "required": [ "content" ] }, "required": [ "remove" ] } ], "properties": { "content": { "maxLength": 1000000, "type": "string" }, "readToken": { "maxLength": 4096, "type": "string" }, "remove": { "const": true, "type": "boolean" } }, "required": [ "readToken" ], "type": "object" }, "maxItems": 32, "minItems": 1, "type": "array" }, "previewId": { "maxLength": 4096, "type": "string" }, "readToken": { "maxLength": 4096, "type": "string" } }, "required": [ "notebookId", "categoryId", "noteId", "expectedRevision", "idempotencyKey" ], "type": "object" } ``` ### prepare_changes 预览一组笔记整理操作，生成集中确认链接。每篇笔记每批只接受一个操作。 权限：当前连接。 ```json { "additionalProperties": false, "properties": { "authorizationId": { "maxLength": 4096, "type": "string" }, "operations": { "items": { "additionalProperties": false, "properties": { "input": { "additionalProperties": true, "type": "object" }, "operation": { "enum": [ "create_note", "patch_note", "rename_note", "move_note", "delete_note", "restore_note" ], "type": "string" } }, "required": [ "operation", "input" ], "type": "object" }, "maxItems": 50, "minItems": 1, "type": "array" } }, "required": [ "operations" ], "type": "object" } ``` ### read_note 读取最新正文片段及短期读取凭据；修改前调用。 权限：notes.read。 ```json { "additionalProperties": false, "properties": { "authorizationId": { "maxLength": 4096, "type": "string" }, "categoryId": { "maxLength": 4096, "type": "string" }, "endLine": { "maximum": 1000000, "minimum": 1, "type": "integer" }, "noteId": { "maxLength": 4096, "type": "string" }, "notebookId": { "maxLength": 4096, "type": "string" }, "startLine": { "maximum": 1000000, "minimum": 1, "type": "integer" } }, "required": [ "notebookId", "categoryId", "noteId" ], "type": "object" } ``` ### read_note_version 读取指定历史版本。 权限：history.read。 ```json { "additionalProperties": false, "properties": { "authorizationId": { "maxLength": 4096, "type": "string" }, "categoryId": { "maxLength": 4096, "type": "string" }, "noteId": { "maxLength": 4096, "type": "string" }, "notebookId": { "maxLength": 4096, "type": "string" }, "versionId": { "maxLength": 4096, "type": "string" } }, "required": [ "notebookId", "categoryId", "noteId", "versionId" ], "type": "object" } ``` ### read_notes 批量读取最多二十篇笔记，受总大小限制，逐项返回结果或错误。 权限：notes.read。 ```json { "additionalProperties": false, "properties": { "authorizationId": { "maxLength": 4096, "type": "string" }, "notes": { "items": { "additionalProperties": false, "properties": { "categoryId": { "maxLength": 4096, "type": "string" }, "endLine": { "maximum": 1000000, "minimum": 1, "type": "integer" }, "noteId": { "maxLength": 4096, "type": "string" }, "notebookId": { "maxLength": 4096, "type": "string" }, "startLine": { "maximum": 1000000, "minimum": 1, "type": "integer" } }, "required": [ "notebookId", "categoryId", "noteId" ], "type": "object" }, "maxItems": 20, "minItems": 1, "type": "array" } }, "required": [ "notes" ], "type": "object" } ``` ### read_resource_pages 读取真实页面图像，支持一至六页和局部放大。 权限：resources.read。 ```json { "additionalProperties": false, "properties": { "authorizationId": { "maxLength": 4096, "type": "string" }, "notebookId": { "maxLength": 4096, "type": "string" }, "pages": { "items": { "maximum": 2000, "minimum": 1, "type": "integer" }, "maxItems": 6, "minItems": 1, "type": "array" }, "region": { "items": { "maximum": 1, "minimum": 0, "type": "number" }, "maxItems": 4, "minItems": 4, "type": "array" }, "resourceId": { "maxLength": 4096, "type": "string" } }, "required": [ "notebookId", "resourceId", "pages" ], "type": "object" } ``` ### read_resource_text 读取资料已提取的文字与时间定位；付费转写通过整理任务完成。 权限：resources.read。 ```json { "additionalProperties": false, "properties": { "authorizationId": { "maxLength": 4096, "type": "string" }, "notebookId": { "maxLength": 4096, "type": "string" }, "resourceId": { "maxLength": 4096, "type": "string" }, "startChunk": { "maximum": 1000000, "minimum": 1, "type": "integer" } }, "required": [ "notebookId", "resourceId" ], "type": "object" } ``` ### rename_note 修改笔记名称。 权限：notes.rename。 ```json { "additionalProperties": false, "properties": { "authorizationId": { "maxLength": 4096, "type": "string" }, "categoryId": { "maxLength": 4096, "type": "string" }, "dryRun": { "type": "boolean" }, "expectedRevision": { "maximum": 9007199254740991, "minimum": 0, "type": "integer" }, "idempotencyKey": { "maxLength": 128, "minLength": 8, "pattern": "^[A-Za-z0-9._:-]+$", "type": "string" }, "noteId": { "maxLength": 4096, "type": "string" }, "notebookId": { "maxLength": 4096, "type": "string" }, "previewId": { "maxLength": 4096, "type": "string" }, "title": { "maxLength": 4096, "type": "string" } }, "required": [ "notebookId", "categoryId", "noteId", "expectedRevision", "idempotencyKey", "title" ], "type": "object" } ``` ### renew_access 为原任务申请新的确认；不会自行延长用户批准的截止时间。 权限：当前连接。 ```json { "additionalProperties": false, "properties": { "authorizationId": { "maxLength": 4096, "type": "string" }, "durationSeconds": { "maximum": 86400, "minimum": 300, "type": "integer" }, "requestId": { "maxLength": 4096, "type": "string" } }, "required": [ "requestId" ], "type": "object" } ``` ### request_access 为任务申请指定笔记和操作的权限，返回用户确认链接。批准后在调用中携带 authorizationId。 权限：当前连接。 ```json { "additionalProperties": false, "properties": { "authorizationId": { "maxLength": 4096, "type": "string" }, "durationSeconds": { "maximum": 28800, "minimum": 300, "type": "integer" }, "profile": { "enum": [ "read", "edit", "organize" ], "type": "string" }, "purpose": { "maxLength": 500, "minLength": 1, "type": "string" }, "targets": { "items": { "additionalProperties": false, "oneOf": [ { "not": { "required": [ "notebookTitle" ] }, "required": [ "notebookId" ] }, { "not": { "required": [ "notebookId" ] }, "required": [ "notebookTitle" ] } ], "properties": { "categoryId": { "maxLength": 4096, "minLength": 1, "type": "string" }, "includeFuture": { "type": "boolean" }, "includeTrash": { "description": "Explicitly include notes already in the trash when the user approves. Existing grants are not expanded.", "type": "boolean" }, "noteId": { "maxLength": 4096, "minLength": 1, "type": "string" }, "noteTitle": { "maxLength": 4096, "minLength": 1, "type": "string" }, "notebookId": { "maxLength": 4096, "minLength": 1, "type": "string" }, "notebookTitle": { "maxLength": 4096, "minLength": 1, "type": "string" }, "scopes": { "items": { "enum": [ "notes.read", "notes.create", "notes.edit", "notes.rename", "notes.move", "notes.delete", "history.read", "resources.read", "resources.upload" ], "type": "string" }, "maxItems": 16, "minItems": 1, "type": "array" } }, "required": [], "type": "object" }, "maxItems": 100, "minItems": 1, "type": "array" } }, "required": [ "purpose", "targets" ], "type": "object" } ``` ### request_full_access 申请最长24小时的完全权限，由用户在弹窗确认；有效期内当前连接可执行账号允许的全部CLI/MCP操作，无需逐项确认。返回的authorizationId用于后续调用，支持随时撤销。 权限：当前连接。 ```json { "additionalProperties": false, "properties": { "authorizationId": { "maxLength": 4096, "type": "string" }, "durationSeconds": { "maximum": 86400, "minimum": 300, "type": "integer" }, "purpose": { "maxLength": 500, "minLength": 1, "type": "string" } }, "required": [ "purpose" ], "type": "object" } ``` ### resolve_location 按笔记本内完整文件夹路径解析移动目标；同名路径返回候选。 权限：notes.read。 ```json { "additionalProperties": false, "properties": { "authorizationId": { "maxLength": 4096, "type": "string" }, "notebookId": { "maxLength": 4096, "type": "string" }, "path": { "maxLength": 4096, "type": "string" } }, "required": [ "notebookId", "path" ], "type": "object" } ``` ### restore_note 恢复回收站中的笔记。 权限：notes.delete。 ```json { "additionalProperties": false, "properties": { "authorizationId": { "maxLength": 4096, "type": "string" }, "categoryId": { "maxLength": 4096, "type": "string" }, "dryRun": { "type": "boolean" }, "expectedRevision": { "maximum": 9007199254740991, "minimum": 0, "type": "integer" }, "idempotencyKey": { "maxLength": 128, "minLength": 8, "pattern": "^[A-Za-z0-9._:-]+$", "type": "string" }, "noteId": { "maxLength": 4096, "type": "string" }, "notebookId": { "maxLength": 4096, "type": "string" }, "previewId": { "maxLength": 4096, "type": "string" } }, "required": [ "notebookId", "categoryId", "noteId", "expectedRevision", "idempotencyKey" ], "type": "object" } ``` ### revoke_access 撤销当前连接的一项任务或自动化凭据。 权限：当前连接。 ```json { "additionalProperties": false, "oneOf": [ { "required": [ "requestId" ] }, { "required": [ "tokenId" ] } ], "properties": { "authorizationId": { "maxLength": 4096, "type": "string" }, "requestId": { "maxLength": 4096, "type": "string" }, "tokenId": { "maxLength": 4096, "type": "string" } }, "required": [], "type": "object" } ``` ### search_notes 在指定笔记本检索正文，结果包含定位和版本。 权限：notes.read。 ```json { "additionalProperties": false, "properties": { "all": { "type": "boolean" }, "authorizationId": { "maxLength": 4096, "type": "string" }, "cursor": { "maxLength": 4096, "type": "string" }, "limit": { "maximum": 100, "minimum": 1, "type": "integer" }, "notebookId": { "maxLength": 4096, "type": "string" }, "query": { "maxLength": 4096, "type": "string" }, "sort": { "enum": [ "path", "updatedAt", "title" ], "type": "string" } }, "required": [ "query" ], "type": "object" } ```