# 多维表格插件介绍与操作使用手册 > 适用版本：Duowei Table Pro `1.3.0 / releaseSequence=9` > > 最低 Obsidian 版本：`1.11.4` > > 版本变化请参阅同一安装包中的 `CHANGELOG.md`。 > > 文档修订：`2026-09-11`。相较上一线上版本 `1.2.0 / releaseSequence=8`，本版本新增个人微信收件箱同步、附件格粘贴剪贴板图片、整表浏览灯箱、手机端隐藏底部导航栏、子任务拖动排序、触屏长按菜单与拖拽、平板独立布局，以及绑定笔记的属性自动继承与写回保护。完整变化统一记录在 `CHANGELOG.md` 的 `1.3.0` 条目中。 本文档根据当前代码实现整理，面向实际使用者。插件仍在快速迭代中，若界面文案或入口名称有轻微变化，以 Obsidian 命令面板和当前插件界面为准。 ## 1. 插件定位 多维表格是一个 Obsidian 本地数据表插件。它把“记录、字段、视图、筛选、排序、分组、表单、仪表盘、笔记绑定、frontmatter 同步”等能力放进本地库中，适合在 Obsidian 内管理项目、内容、资料、任务、资产、客户、学习记录、读书清单、图片素材、文件台账等结构化信息。 当前插件有两条使用路线： 1. 独立 `.duowei` 表格文件 这是主推荐模式。一张表就是一个 `.duowei` 文件，数据、字段、视图配置都保存在该文件中。它不要求每条记录都有 Markdown 笔记，体验更接近飞书多维表格、Airtable 或 Notion 数据库的本地版本。 2. Obsidian Bases 兼容视图 插件注册了一个 Bases 自定义视图 `duowei-grid`，可在 `.base` 文件里使用“多维表格”布局查看和编辑 Markdown/frontmatter。这个模式适合已经在用 Obsidian Bases 的库，或者需要从 `.base` 迁移到独立 `.duowei` 文件。 建议新用户优先使用独立 `.duowei` 表格；已有 Bases 工作流的用户可先用兼容视图，再通过命令迁移。 ## 2. 适合哪些场景 多维表格适合“既需要结构化表格，又希望留在 Obsidian 本地库里”的场景： - 项目管理：需求、任务、状态、负责人、截止日期、优先级、进度、附件、复盘笔记。 - 内容运营：选题池、发布日历、平台、脚本、素材、链接、数据复盘。 - 资料库：论文、网页、书籍、标签、阅读状态、评分、摘要、原文附件。 - 个人生活：购物清单、旅行计划、账单、体检记录、习惯跟踪。 - 素材管理：图片、PDF、Word、音视频文件按文件夹实时进表，配合画廊视图查看。 - 笔记索引：把一个文件夹内的 Markdown 笔记导入成表格，并把 frontmatter 作为字段管理。 - 本地 CRM：联系人、客户、跟进记录、邮件、电话、关联项目。 - 小红书/公众号/B 站等内容规划：选题、封面、脚本、发布时间、状态、数据指标、素材附件。 不适合的场景： - 需要多人实时协同编辑同一张表。 - 需要云端数据库权限、多人审批和服务端常驻执行的企业流程。插件内本地自动化仍要求 Obsidian 处于运行状态。 - 需要 Excel 级复杂公式、透视表、宏、合并单元格。 - 需要把 `.duowei` 文件当作通用数据库供其他软件直接写入。 ## 3. 核心概念 ### 3.1 表格文件 独立表格使用 `.duowei` 扩展名。文件内容是 JSON，插件会通过专用视图打开它。 一个 `.duowei` 文件包含： - 字段：列定义，包括名称、类型、选项、格式、宽度、同步键等。 - 记录：每一行数据。 - 视图：表格、看板、画廊、日历、时间线、表单、仪表盘等展示方式。 - 当前视图状态：筛选、排序、分组、隐藏字段、颜色规则、列统计等。 - 元信息：创建时间、更新时间等。 ### 3.2 字段 字段就是列。字段类型决定单元格如何编辑、如何展示、如何筛选排序，以及能否参与公式、汇总或同步。 例如： - “标题”适合文本字段。 - “状态”适合单选字段。 - “完成”适合勾选字段。 - “截止日期”适合日期字段。 - “进度”适合进度字段。 - “相关任务”适合关联记录字段。 ### 3.3 记录 记录就是行。记录可以独立存在，也可以绑定到某篇 Markdown 笔记。 绑定笔记后，记录字段可通过 `syncKey` 与 frontmatter 属性同步。这样你可以在表格里改状态、标签、评分，也可以在笔记属性里改，插件会在打开的表格中做反向同步。 ### 3.4 视图 视图是同一份数据的不同呈现方式。一个 `.duowei` 文件可以有多个视图，每个视图可以有自己的字段顺序、隐藏字段、筛选、排序、颜色规则和展示配置。 当前支持： - 表格：类似电子表格，适合密集编辑。 - 看板：按状态、负责人、分类等字段分组。 - 画廊：适合图片、附件、封面、卡片式资料。 - 日历：按日期字段查看记录。 - 时间线：按开始/结束日期查看跨度。 - 表单：逐项录入新记录。 - 仪表盘：用数字卡片、柱状图、饼图做统计概览。 ### 3.5 独立表格与库数据源表格 普通 `.duowei` 表格会把记录保存在 `.duowei` 文件中。 库数据源表格是一种特殊 `.duowei` 表格。它不保存记录，而是运行时从 Obsidian 库里的文件树和 metadataCache 中实时生成记录。每个匹配文件是一条记录，适合做“全库笔记索引”“图片素材库”“PDF/文档台账”等。 > [!tip] 文件夹建表使用统一入口 > 命令面板中的“多维表格：从文件夹创建多维表格”提供两种方式： > - **可编辑独立表格**：导入现有 Markdown，记录保存在 `.duowei` 文件中，支持与笔记属性双向同步。 > - **实时只读索引**：记录不落盘，跟随文件夹内容变化，可索引 Markdown、图片、文档和音视频等文件。 ## 4. 安装与启用 ### 4.1 基本要求 - Obsidian 桌面端或移动端。 - `manifest.json` 中的最低 Obsidian 版本为 `1.11.4`。 - 插件不是 desktopOnly，移动端也可启用；移动端界面有触屏适配。 ### 4.2 启用插件 1. 将插件放入库的 `.obsidian/plugins/obsidian-multidimensional-table/` 目录。 2. 在 Obsidian 设置中打开“第三方插件”。 3. 找到“多维表格”并启用。 4. 打开命令面板，输入“多维表格”即可看到相关命令。 ### 4.3 插件设置 在 Obsidian 设置中进入“多维表格”设置页，可配置： - 显示保存状态：在视图右上角显示正在保存、已保存、冲突等状态。 - 手机端隐藏 Obsidian 底部导航栏：默认开启。仅在手机端且当前查看独立多维表格时隐藏 Obsidian 自身的底部导航栏，保留表格操作栏；切换到其他页面、关闭开关或停用插件后自动恢复。 - 图片单元格显示方式：可选“仅图片”“仅链接”或“图片 + 链接”。图片默认在单元格内居中；URL 字段可每行输入一个链接，多图时最多并排显示 4 张缩略图，其余以 `+N` 提示。单击缩略图进入灯箱，可滚轮或按钮缩放、拖动查看；灯箱按当前视图的行序、列序串起整张表的图片，方向键、两侧箭头或（未放大时）横向滑动即可切到上一张 / 下一张，底部显示来源记录与页码；双击缩略图可直接打开原图。 - 外部图片/附件保存路径：把外部图片或文件拖入附件、画廊封面等单元格时的保存文件夹。留空则沿用 Obsidian「文件与链接 → 附件文件夹路径」的设置。支持占位符 `{{table}}`（表格名）和 `{{folder}}`（表格所在文件夹），例如填 `附件/{{table}}` 会把每张表的图片分别收进以表格命名的子文件夹。缺失的文件夹自动创建，同名文件自动加序号而不会覆盖。 - 新建表格存放文件夹：“创建空白多维表格”命令生成的表格保存到这个文件夹，默认 `多维表格`。留空表示库根目录，支持多级路径（如 `资料库/表格`），缺失的文件夹会逐级自动创建。 - 备份存放文件夹：自动备份和冲突备份的保存文件夹。留空（默认）表示与原表格同目录。同样支持占位符 `{{table}}` 和 `{{folder}}`，例如填 `备份/{{folder}}` 可按原目录结构归类备份。缺失的文件夹自动创建；“备份恢复”面板会同时查找此文件夹和原表格同目录，因此改动设置后旧位置的备份依然可以找到和恢复。 - 自动备份 `.duowei` 表格：保存覆盖旧版本前生成可恢复快照。 - 自动备份最小间隔：连续编辑时至少间隔多少分钟才创建下一份自动备份，范围 1–240 分钟，默认 10 分钟。 - 每个表格保留自动备份数：默认 12，范围 1–100。只清理自动备份，不清理冲突备份。 - 持久化操作日志：把最近操作保存到插件数据中，重启 Obsidian 后仍可查看。操作日志不写入 `.duowei` 文件。 - 保留操作日志条数：默认 500，范围 50–2000。 - 显示收藏夹同步命令：默认开启。关闭后，命令面板中的收藏夹相关命令（同步 B 站/知乎/小红书收藏夹、同步全部、与平台对账、抓取收藏内容、登录收藏夹平台）即时隐藏。不使用收藏夹功能时可关闭以精简命令面板；不影响任何已配置的 Cookie 或数据，随时可开回。 - 显示外部服务命令：默认开启。关闭后，Notion、飞书、Zotero、Microsoft To Do、Google 日历与待办的连接、导入、绑定、同步、完整校验和解绑命令即时隐藏。这些命令原本就只在满足对应平台条件时出现，关闭开关可统一精简命令面板；不会删除已有连接或同步数据。 - Microsoft 与 Google 账户：插件已经内置 OAuth 应用，普通用户只需点击“连接账户”并登录自己的账号，不需要创建开发者应用，也不需要填写 Client ID 或 Client Secret。私有部署需要使用自有 OAuth 应用时，才展开“高级：自定义 OAuth 应用”。发布者配置、普通用户授权、表格绑定、同步边界和故障处理详见[[#21. 外部同步：Notion、飞书、日历与待办|第 21 章]]。 - 个人微信收件箱：连接本机微信收件服务，把发到绑定 ClawBot 会话的消息追加到指定 `.duowei` 表格。包含本机一键安装 / 自动连接本机服务、服务地址、目标多维表格、API Token（保存在 Obsidian SecretStorage）、测试连接、立即同步和自动同步间隔（秒）。完整安装与使用步骤见第 21.23 节和独立的《微信消息同步安装及使用手册》。 ## 5. 快速开始 ### 5.1 创建第一张空白多维表格 1. 打开 Obsidian 命令面板。 2. 执行“多维表格：创建空白多维表格”。 3. 插件会创建 `多维表格/未命名多维表格.duowei`，如果同名文件已存在，会自动追加序号。存放文件夹可在插件设置的“新建表格存放文件夹”中修改。 4. 新表默认包含字段： - 标题：文本 - 状态：单选，包含“待处理”“进行中”“已完成” - 完成：勾选 5. 新表默认包含视图： - 表格 - 看板 - 画廊 - 日历 - 时间线 创建后你可以直接新增行、添加字段、切换视图、筛选排序，不需要先创建 Markdown 笔记。 ### 5.2 从 Base 创建多维表格 1. 打开命令面板。 2. 执行“多维表格：从 Base 创建多维表格”。 3. 在选择器中搜索并选择库内的 `.base` 文件；当前打开的 Base 会排在最前并显示 ✓。 4. 插件会读取 Base 配置、视图字段、过滤条件和匹配的 Markdown/frontmatter 记录，并转换为独立 `.duowei` 文件。 5. 新表默认保存到设置中的“新建表格存放文件夹”，默认路径为 `多维表格/{Base 文件名}.duowei`；重名时自动追加序号。 转换后使用的是独立多维表格，不会创建 Bases 兼容视图或示例笔记。记录仍会绑定原 Markdown 笔记，字段也会尽量保留 frontmatter 同步键。 ### 5.3 从现有 `.base` 迁移到 `.duowei` 1. 打开一个 `.base` 文件。 2. 打开命令面板。 3. 执行“多维表格：从当前 Base 创建多维表格”。 4. 插件会读取 Base 配置、视图字段、过滤条件和匹配的 Markdown/frontmatter 记录。 5. 生成的 `.duowei` 文件会放到设置中的“新建表格存放文件夹”，名称类似 `{Base 文件名}.duowei`。 迁移后，记录会绑定原 Markdown 笔记，字段也会尽量带上 frontmatter 同步键。 ### 5.4 从文件夹创建可编辑独立表格 1. 打开命令面板。 2. 执行“多维表格：从文件夹创建多维表格”。 3. 选择“可编辑独立表格（导入现有 Markdown，属性双向同步）”。 4. 选择要导入的文件夹。 5. 插件会扫描该文件夹下的 Markdown 笔记。 6. 每篇笔记生成一条记录，第一列为“笔记”链接字段。 7. frontmatter 键会自动推断为字段，并设置同步键。 字段类型推断规则包括： - 布尔值推断为勾选。 - 数字推断为数字。 - `YYYY-MM-DD` 推断为日期。 - ISO 日期时间推断为日期时间。 - `http://` 或 `https://` 链接推断为 URL。 - 数组推断为多选。 - 重复的少量文本值推断为单选。 - 其他值推断为文本。 导入完成后，生成的 `.duowei` 文件会放在被导入文件夹内。 ### 5.5 创建实时只读索引（库数据源表格） 1. 打开命令面板。 2. 执行“多维表格：从文件夹创建多维表格”。 3. 选择“实时只读索引（跟随文件夹变化，可包含附件）”。 4. 选择来源文件夹，根目录表示全库。 5. 选择文件范围： - 笔记（Markdown） - 图片 - 文档（PDF / Office / 文本） - 音视频 - 全部文件 6. 插件生成一张 `.duowei` 数据源表格。 库数据源表格的记录来自库内真实文件。Markdown 文件会显示笔记、标签、创建/修改时间和推断出的 frontmatter 字段；非 Markdown 文件会显示文件、类型、大小、文件夹、创建/修改时间等内置信息。 注意：当前库数据源表格以只读索引为主。要编辑文件内容或属性，应回到原 Markdown 笔记或原文件中编辑。 ### 5.6 快速添加记录 1. 打开命令面板。 2. 执行“多维表格：快速添加记录到多维表格”。 3. 选择目标 `.duowei` 表格。 4. 输入标题。 5. 插件会把记录追加到表中，无需打开表格。 快速添加会优先写入第一个文本或长文本字段；如果没有文本字段，则写入第一个字段。 ## 6. 主界面说明 打开 `.duowei` 文件后，界面一般分为两个工具栏区域： ### 6.1 视图栏 视图栏用于切换和管理视图： - 点击视图标签切换。 - 视图过多时会折叠为 `+N` 菜单。 - 使用“新建视图”创建表格、看板、画廊、日历、时间线、表单或仪表盘。 - 使用当前视图菜单可重命名、复制或删除视图。 每个视图可以拥有自己的筛选、排序、隐藏字段、颜色规则和展示配置。 ### 6.2 工具栏 常用工具包括： - 字段：新增字段、编辑字段、调整字段配置。 - 筛选：按字段条件筛选记录。 - 分组：表格视图可按最多 3 个字段分组。 - 子任务：设置父任务字段并显示嵌套任务层级。 - 排序：按一个或多个字段排序。 - 显示：调整行高、自动换行、自动行高、列宽自适应、冻结列和统计概览。 - 样式：设置条件颜色规则或当前选区的单元格颜色。 - 撤销/重做：回退或恢复最近操作。 - 搜索：在当前表格内搜索。 - 更多操作：查找替换、同步、日志、备份、导入导出、快捷键等。 ### 6.3 更多操作菜单 更多操作菜单中常见入口： - 查找替换 - 在顶部新增行 - 导入 CSV/TSV - 导出 CSV - 导出 TSV - 笔记联动 - 同步所有绑定记录 - 同步中心 - 操作日志 - 备份恢复 - 冲突恢复（存在冲突备份时显示） - 键盘快捷键 ## 7. 表格视图 表格视图适合密集录入、批量编辑和结构化整理。 ### 7.1 新增、编辑和删除 - 新增记录有四条路径：表格内容末尾常驻的“+ 新增记录”行（点整行即可）、把鼠标移到两行之间时出现在行号列上的 `+`（在这条分隔线处插入，悬停 `+` 会亮出插入位置指示线）、右键菜单的“向上/向下插入 N 行”、以及 Shift+Enter。新增后会自动滚动到新行并把光标放进第一格。 - “在顶部新增行”在右上角“更多操作”菜单里；命令面板搜索“在当前多维表格新增记录”可绑定快捷键。 - 双击单元格或按 Enter/F2 进入编辑。触屏上改为点两下：第一下选中，再点一下已选中的单元格进入编辑。 - 输入普通字符也可直接开始编辑当前单元格。 - Delete/Backspace 清空选区内可编辑单元格。 - 右键单元格或选区的菜单按“打开详情 → 复制/粘贴 → 插入行/复制行 → 填充与批量修改、单元格样式 → 笔记联动 → 清空与删除”分组；当前用不到的项（如单行选区下的填充、未绑定笔记时的笔记操作）不会灰着占位，而是直接不显示。 系统字段、公式、查找、汇总、反向关联等只读字段不能直接编辑。 ### 7.2 选择和复制粘贴 支持类似电子表格的选择方式： - 单击单元格选中。 - Shift + 方向键扩展选区。 - Ctrl/Cmd + A 全选表格数据区域。 - Ctrl/Cmd + C 复制当前单元格或选区。 - Ctrl/Cmd + V 粘贴单元格或 TSV 矩阵。 - 粘贴图片：先截图或复制图片，再单击一个**附件**单元格，按 Ctrl/Cmd + V（也可右键 → 粘贴）。图片会自动保存到附件目录并追加到当前格，不覆盖已有附件；选中多个格时也只添加到当前活动格，不自动扩展行列。普通文本、数字等字段不接受图片。 - 重复粘贴同一图片会按文件内容去重：当前格已有相同图片时保留原引用，不重复添加；新粘贴保存的图片在同一附件目录下可供其他格复用。旧版随机命名的图片也能在当前格中识别；已经产生的重复引用和文件不会自动删除。去重比较文件字节，重新编码或修改过的图片会视为不同文件。 - 附件编辑框、记录详情和移动端编辑抽屉也支持粘贴图片；编辑框内先追加到草稿，沿用原有的回车、失焦或“保存”动作提交。图片保存途中提交会等待保存完成，取消则不写入单元格。已落盘的图片仍保留在附件目录，取消或撤销不会删除图片文件。 - 保存位置沿用插件“外部图片/附件保存路径”；未设置时使用 Obsidian 的附件目录。系统未提供图片数据（例如只复制了图片网址）时会按原有文字方式粘贴；右键无法读取图片时请使用 Ctrl/Cmd + V。 - 粘贴区域超出当前行列边界时，插件会自动增加行或列承接数据。 粘贴时只读字段会被跳过。 ### 7.3 填充和批量修改 表格支持： - 向上/向下填充。 - 拖拽填充柄（仅纵向）。右下角手柄可向下填充，左上角手柄可向上填充。 - 选中至少两行后右键选择“向上填充”或“向下填充”。 - 带预览的批量修改选区。 横向填充已关闭；跨字段批量改值请使用“批量修改选区”，避免把值写入不兼容的字段类型。适合批量设置状态、负责人、日期、分类、颜色等。 ### 7.4 列宽、冻结列和自动换行 - 拖拽表头边缘调整列宽。 - 拖动表头可调整列顺序，松手位置落在目标列头左半或右半决定插到它前面还是后面；触屏长按列头后移动即可。列顺序按视图分别保存。 - 拖动左侧行号可调整记录顺序；触屏长按行号后移动。搜索、筛选、排序或分组生效时不能拖动排序，请先清除相应条件；只读表格不可修改。 - 双击列宽拖拽手柄按当前列内容自适应；已经贴合内容时再双击一次会恢复该字段的默认宽度。字段菜单里的“自适应列宽（本列）”是同一个动作。 - 在“显示”菜单中选择“所有列自适应内容”或“列宽适应窗口”，也可以继续手动调整列宽。 - 在“显示”菜单中设置冻结前 N 列，便于横向浏览大表；移动端最多冻结首列。 - 表格视图支持自动换行。开启后可选择紧凑、标准或舒适行高；关闭时单行省略。 - 开启“自动行高（按内容）”后，换行行数会按每条记录的可见内容计算，当前手动拖过的行高优先于自动结果。 - 拖动行底部的行高把手可调整单行高度；已选中的连续行会一起调整，右键行号可选择“重置行高”。 - 长文本、URL 或 Markdown 内容放不下时，活动单元格会出现“展开”入口；展开可查看完整内容，双击仍可进入编辑。 ### 7.5 分组 表格视图支持最多 3 级分组。 使用方式： 1. 点击工具栏“分组”。 2. 选择第一级分组字段。 3. 可继续选择第二级、第三级字段。 4. 分组标题行显示分组名称和记录数量。 5. 分组可折叠，折叠状态会保存在视图中。 注意： - 分组状态下行拖拽排序会自动禁用。 - 分组标题可显示列统计信息。 - 分组菜单支持展开/折叠全部分组。 ### 7.6 列统计 表格底部可显示列统计栏，统计会跟随当前搜索和筛选结果变化。 不同字段可选统计方式不同： - 数字、评分、进度、汇总、公式：求和、平均、最小、最大、已填写、未填写、唯一值。 - 勾选：已勾选、已填写、未填写。 - 文本、日期、选项等：已填写、未填写、唯一值。 ### 7.7 查找替换 入口： - Ctrl/Cmd + H - 更多操作菜单中的“查找替换” 支持在文本、长文本、链接、邮箱、笔记链接等字段中查找和替换。可逐个替换，也可全部替换。 长文本或 Markdown 单元格在网格中会按当前行高显示摘要；点击活动单元格的展开按钮即可阅读完整内容，不必先进入编辑态。 ### 7.8 子任务拖动排序与层级调整 开启子任务嵌套显示后，按住左侧行号拖动任务；触屏可长按行号后移动。 - 拖到目标行顶部或底部，插到该任务之前或整棵子任务树之后，并与目标任务保持同级。 - 拖到目标行中部，将任务设为目标的子任务，追加到已有子任务之后。 - 向左拖动可逐级提升；也可以直接拖到某个顶层任务之前或之后，提升为顶层任务。以插入线和落点提示为准。 - 父任务的所有后代一起移动，包括已折叠的子任务。移入折叠的父任务后会展开目标，原有子任务折叠状态保留。 - 不允许拖入自己或自己的后代；放到表格外、按 Escape 或系统取消时不提交。顺序和父子关系一并保存，可撤销/重做。 - 搜索、筛选、自动排序或分组时暂不支持拖动，请先清除相应条件；只读表格不可修改。 ## 8. 看板视图 看板视图按字段分组显示卡片，适合任务状态、内容流程、销售阶段等场景。 ### 8.1 基本配置 看板视图可配置： - 分组字段：通常选择单选、勾选、负责人、阶段等字段。 - 标题字段：卡片标题来源。 - 卡片字段：卡片上展示哪些辅助字段。 默认新表的看板按“状态”分组，以“标题”为卡片标题。 ### 8.2 使用方式 - 点击卡片打开记录详情。 - 在看板中新增记录，记录会自动带上当前分组值。 - 桌面端可通过拖拽卡片改变分组字段值。 - 移动端可长按卡片，通过菜单移动到其他分组。 - 看板卡片会应用视图的颜色规则。 ### 8.3 性能说明 看板对大表做了分页渲染，每列首屏显示一部分卡片，可通过“显示更多”继续展开。 ## 9. 画廊视图 画廊视图适合图片素材、文章封面、书影音、文件资产、灵感库等卡片式内容。 ### 9.1 基本配置 画廊视图可配置： - 封面字段：可选择附件、URL、笔记链接等字段。 - 标题字段：卡片标题来源。 - 卡片字段：卡片下方显示的字段。 ### 9.2 封面操作 画廊支持： - 选择已有字段作为封面字段。 - 新建封面附件字段。 - 给卡片选择封面图片。 - 替换封面。 - 移除封面。 - 拖拽库内文件到画廊卡片作为附件。 当库数据源选择“图片”范围时，画廊可直接作为图片素材管理器使用。 ### 9.3 手机与窄容器布局 - 在手机或窄容器布局中，画廊固定使用单列卡片，避免卡片宽度不足时封面、按钮和属性互相挤压。 - 卡片封面会适当压缩高度；标题保持紧凑，属性摘要按单列逐行显示。 - 每条属性都按“图标、字段名、字段值”排列。字段名宽度会被限制，主要空间留给字段值；标签、笔记链接和长文本会在卡片内部安全收缩或换行，不再横向溢出。 - 可排序画廊只通过显式拖拽手柄启动排序；在卡片主体纵向滑动时不会轻易误触拖拽。 ### 9.4 性能说明 画廊对大表做了分页渲染，首屏渲染一部分卡片，可通过“显示更多”继续展开。 ## 10. 日历视图 日历视图按日期字段展示记录，适合发布计划、任务截止日期、复盘安排、课程表等。 ### 10.1 基本配置 日历视图可配置： - 日期字段：记录落在哪一天。 - 标题字段：日历项显示的标题。 - 卡片字段：日历项中显示的辅助字段。 - 当前月份。 - 显示模式：月、周或 30 天议程。 - 颜色规则：命中规则的记录会以对应颜色显示在日历卡片上。 如果表中没有日期或日期时间字段，日历会提示新增日期字段。 ### 10.2 使用方式 - 使用工具栏的“月 / 周 / 议程”切换显示密度；议程按锚点日期连续展示未来 30 天内有排期的记录。 - 使用上一时段、下一时段、今天按钮切换；切换步长会随显示模式变为一个月、一周或 30 天。 - 点击某天新增记录，日期字段会自动填入当天。 - 如果日期字段是日期时间，新建记录默认会带上 09:00。 - 点击日历项打开记录详情。 - 双击日历项会切回表格并定位该记录。 - 某天超过 5 条记录时，点击“还有 N 条”可查看当天全部记录。 - 工具栏出现“未排期 N”时，可查看没有日期的记录，将其拖到目标日期，或直接排到今天。 - 触屏上长按日历项或“未排期”记录即可拖动改期：月视图拖到目标日期，周视图可拖到全天栏或具体时段。长按前的滑动仍然是滚动。 ## 11. 时间线视图 时间线视图按开始日期和结束日期展示记录，适合项目周期、活动安排、内容排期、合同周期等。 ### 11.1 基本配置 时间线视图可配置： - 开始字段。 - 结束字段。 - 标题字段。 - 卡片字段。 - 当前月份。 - 缩放尺度：周、月或季度。 开始字段和结束字段通常选择日期或日期时间字段。 新建时间线会优先根据“开始/start/begin”和“结束/截止/end/due/deadline”等字段名自动匹配。已有视图如果疑似把开始、结束字段选反，会显示告警并提供“交换字段”操作；记录自身的结束日期早于开始日期时也会明确标记。 ### 11.2 使用建议 - 只有一个日期字段时，可把它作为开始字段使用。 - 有开始和截止两个字段时，时间线能表现跨度。 - 与筛选和颜色规则配合，可做“本月项目排期”“逾期任务视图”等。 - 使用工具栏的“周 / 月 / 季度”切换时间跨度，上一时段和下一时段会按当前尺度导航；季度视图连续展示三个月并标出月界。 - 单击时间条打开详情，双击会切回表格并定位记录。 - 没有开始日期的记录会汇总到“未排期”，可拖入时间线或快速排到今天。 - 触屏上长按时间条或“未排期”记录后即可拖动到目标日期；长按前的滑动仍然是滚动。 - 时间条两端支持拖动修改区间；聚焦缩放手柄后，可用方向键按天调整，按住 Shift 时按周调整。 - “今天”除了表头高亮，还会在所有时间线行中显示贯穿竖线。 - 单个时段匹配超过 200 条记录时先显示前 200 条，可用“再显示”继续加载，避免一次性创建过多时间条。 ## 12. 表单视图 表单视图用于按字段逐项录入新记录，适合减少表格噪音、给固定流程做快速录入。 ### 12.1 基本配置 表单视图可配置： - 表单包含哪些字段。 - 字段顺序。 - 表单说明。 - 必填字段校验。 如果没有指定字段，表单会展示全部可编辑字段。 ### 12.2 使用方式 1. 新建或切换到表单视图。 2. 按字段填写内容。 3. 提交后创建一条新记录。 4. 必填字段未填时会提示错误。 表单适合做“新选题录入”“新任务收集”“新客户登记”“新素材入库”等入口。 ## 13. 仪表盘视图 仪表盘视图用于对当前数据做概览统计。图表由插件内置 CSS 和 SVG 渲染，不依赖外部图表库。 ### 13.1 支持组件 当前支持四种图表类型： - 数字卡：显示记录数，或对某个字段做已填写、未填写、求和、平均、最大、最小、唯一值、已勾选等统计。可选的统计项随字段类型变化，例如求和只对数值型字段开放。 - 柱状图：按某个字段分组统计。 - 饼图：按某个字段分组统计，渲染为环形图。 - 折线图：按某个字段分组统计，绘制平滑趋势曲线。 柱状图、饼图、折线图的“数值”可选记录数、求和或平均。选求和或平均时需要再指定一个数值字段（数字、评分、进度、公式等数值型字段）。 ### 13.2 管理图表 - 点击仪表盘底部的“添加图表”新建图表。 - 点击图表卡片右上角的“…”按钮，选择“编辑图表”或“删除图表”。 - 编辑面板可设置：图表类型、标题、字段/分组、统计方式、数值方式、数值字段。 - 视图设置里的“排列”可在 4×4 和 9×9 两种密度之间切换，控制每行放几张卡片。 图表标题可以显示在卡片上方或下方。标题位置和图表数据源目前通过图表引用参数设置，详见“Markdown 笔记内嵌表格”一节。 ### 13.3 统计范围 仪表盘统计默认跟随当前仪表盘视图的筛选联动。你可以先做“仅未完成”“本月”“某个平台”等筛选，再在仪表盘里查看对应范围的统计。 单个图表也可以指定自己的数据源：全部记录，或另一个视图的筛选结果。这样同一个仪表盘里既能放“全库总量”，也能放“本月新增”。 ### 13.4 使用建议 - 项目表：记录数、已完成数、按状态柱状图。 - 内容表：按平台统计、按发布状态统计。 - 资料表：按类型、标签、阅读状态统计。 - 素材表：按文件类型、文件夹、创建月份统计。 ## 14. 字段类型参考 ### 14.1 文本 单行文本，适合标题、名称、短备注、分类编码等。 ### 14.2 长文本 多行文本，适合摘要、脚本、复盘、说明。记录详情中可用 Markdown 渲染预览，点击后进入原始文本编辑；在表格视图中，过长内容会提供展开预览入口，编辑时会临时扩展输入区域。 ### 14.3 数字 适合金额、数量、分数、阅读页数、播放量等。支持： - 普通数字。 - 千分位显示。 - 百分比显示。 - 货币显示。 - 小数位数。 - 货币符号。 - 最小值、最大值校验。 显示格式只影响展示，不改变存储值、搜索、排序、复制和导出。 ### 14.4 勾选 布尔开关，适合完成、是否发布、是否复盘等。可用于筛选“已勾选/未勾选”。 ### 14.5 日期 只记录年月日。适合截止日期、发布日期、购买日期等。支持日期格式预设、自定义格式和“相对日期（今天 / 昨天 / N 天前）”显示。格式只影响展示，不改变存储值、筛选、排序或导出。 ### 14.6 日期时间 记录日期和时间。适合会议时间、发布时间、提醒时间等。编辑时使用迷你日历和时间输入；日期格式面板可分别设置日期部分和时间部分，并提供实时预览。 ### 14.7 单选 从预设选项中选择一个。适合状态、优先级、平台、类型等。 支持： - 下拉搜索。 - 输入创建新选项。 - 选项颜色。 - 重命名选项。 - 删除选项。 - 在字段编辑面板中拖拽选项手柄，或使用上下方向键调整选项顺序。 ### 14.8 多选 从预设选项中选择多个。适合标签、适用平台、关联主题等。支持选项颜色、搜索和新增选项；已选标签可在下拉面板中拖拽或用左右方向键调整单条记录的显示顺序，字段编辑面板也支持调整全局选项顺序。 ### 14.9 链接 URL 字段，适合网页、参考链接、发布链接。点击可打开目标。 ### 14.10 邮箱 邮箱地址字段，点击可发信，并提供基础校验。 ### 14.11 电话 电话号码字段，点击可拨号，并提供基础校验。 ### 14.12 评分 星级评分字段，支持配置最大星数，范围 1–10，默认 5。适合书影音评分、优先级、满意度等。 ### 14.13 进度 0–100 的进度条字段，适合任务进度、完成比例等。 ### 14.14 笔记链接 指向 Obsidian 库内 Markdown 笔记。支持文件选择器、打开目标、原生页面预览。 ### 14.15 附件 指向 Obsidian 库内文件，可用于图片、PDF、Office 文档、音视频等。支持文件选择器、打开目标、原生页面预览。画廊封面通常使用附件字段。 ### 14.16 关联记录 关联本表或其他 `.duowei` 表中的记录。适合： - 项目关联任务。 - 文章关联素材。 - 客户关联跟进记录。 - 书籍关联笔记。 关联字段支持： - 同文件记录关联。 - 跨 `.duowei` 文件关联。 - 记录选择弹窗。 - chip 预览。 - 复制/粘贴标题解析。 - 删除记录时清理本文件内失效关联。 - 跨文件目标修改或重命名后的路径刷新。 配置方式：字段编辑面板中直接有"关联的表格"下拉行（默认"本表格内"）， 新建时选好目标再保存即可；编辑已有关联字段时改选目标会立即生效 （若已有关联值会先确认，切换目标将清空原有关联）。 **记录标题字段（对标飞书索引字段）**：关联 chip、记录选择弹窗、粘贴解析、 记录预览都用同一个"标题字段"来显示记录，默认是第一个非关联字段。 如果第一列是日期、编号等不便辨识的字段，可以在任意字段的"字段操作"菜单里 选择"设为标题字段"，把更有辨识度的列（如名称、标题）指定为记录标题； 表头会用一个小标记标出当前标题字段。标题字段被删除时自动回退到第一个非关联字段。 跨文件关联不会做实时多人协同，也不会自动反向清理目标文件中的所有关系。 ### 14.17 查找 查找字段基于关联记录读取目标字段值。它是只读自动字段，适合把关联任务的负责人、素材的链接、客户的名称等带到当前表中。 配置方式：编辑查找字段时，面板内直接显示"关联字段"和"目标字段"两个下拉行， 点击任意一行只改该项、立即生效，不需要重走完整向导。 目标字段可以是普通字段、公式、汇总，也可以是关联字段（此时显示关联记录的标题）； 只有查找字段本身不能作为目标（避免链式查找）。 目标表格新增字段后，下拉列表会即时读取最新字段清单。 查找字段可参与搜索、排序、复制和导出。 查找结果会保留目标字段的实际类型，而不是先转换成用于显示的字符串。例如，目标数字仍是数字、勾选仍是布尔值、单选/多选使用选项名称。查找多个关联记录时，结果是一个多值列表，可以继续交给公式处理： ```text sumitems([查找单价]) ``` ```text joinitems([查找标签], "、") ``` 如果目标字段是公式或汇总，查找会读取目标记录的最新计算结果，因此支持“跨表关联 → 查找目标公式 → 当前表公式 → 下游公式”的连续计算。为避免含义不明确，查找字段不能再以另一个查找字段为目标。 数字型或日期型查找结果可从字段操作菜单设置数字、货币、百分比或日期格式。格式只影响显示，不改变公式使用的原始值。 ### 14.18 汇总 汇总字段基于关联记录做聚合计算。支持： - 计数 - 求和 - 平均 - 最小值 - 最大值 适合统计一个项目下有多少任务、总预算是多少、平均评分是多少等。 汇总结果是可继续引用的数值计算结果。例如： ```text [任务总预算] * 1.06 ``` 汇总字段也可以设置数字、千分位、百分比或货币格式。 ### 14.19 公式 公式字段是只读派生字段，基于其他字段计算。 支持： - 字段引用：`[字段名]` 或字段 id。 - 数字、文本、布尔值。布尔常量写作 `true` / `false`（不区分大小写）；文本用单引号或双引号包裹。文本内要写引号时用 `\"` `\'` 转义，写反斜杠本身用 `\\`。其余 `\x` 保持字面量，因此 `"C:\data"`、`"\d+"` 可以直接写。 - 四则运算：`+ - * /` - 比较运算：`== != > < >= <=` - 括号。 - 聚合函数：`sum`、`min`、`max`、`avg`、`count` - 列聚合类函数：`sumabove`、`avgabove`、`minabove`、`maxabove`、`countabove` - 单元格聚合类函数：`sumcells`、`avgcells`、`mincells`、`maxcells`、`countcells` #### 计算链路与多值查找 公式结果可以继续被其他公式引用，不需要复制为普通字段。例如： ```text [小计] + [运费] ``` ```text if([含税总计] >= 1000, "大额订单", "普通订单") ``` 查找字段可能同时返回多个关联记录的值。为避免直接把多值列表当成单个数字或文本造成隐式错误，需要使用多值函数明确指定处理方式： | 函数 | 说明 | | --- | --- | | `first(列表)` | 取第一个值；空列表返回空文本 | | `last(列表)` | 取最后一个值；空列表返回空文本 | | `countitems(列表)` | 统计值的数量 | | `sumitems(数字列表)` | 数字列表求和；空列表返回 0 | | `avgitems(数字列表)` | 数字列表求平均 | | `minitems(数字列表)` / `maxitems(数字列表)` | 取数字列表的最小值 / 最大值 | | `joinitems(列表[, 分隔符])` | 拼接为文本；默认使用逗号和空格分隔 | 典型跨表订单计算： ```text sumitems([查找含税价]) * [数量] ``` 如果业务上只允许关联一条记录，可以使用： ```text first([查找单价]) * [数量] ``` 不使用多值函数而直接执行 `[查找单价] * [数量]` 时，公式会提示列表不能直接作为数字使用，避免系统擅自选择第一项或悄悄丢失其他值。 跨表目标字段是公式时，会在同一次计算链路中按需求值；同一个中间公式被多个下游公式引用时，会复用本次计算结果。 #### 布尔常量与勾选字段 勾选字段本身就是布尔值，可以直接作为条件： ```text and([库存] > 0, [上架]) ``` 也可以与布尔常量明确比较： ```text and([库存] > 0, [上架] == true) ``` `true` 表示“是/已勾选”，`false` 表示“否/未勾选”。它们不需要引号；写成 `"true"` 会变成普通文本。 #### 循环引用诊断 公式不能形成闭环。例如： ```text 循环A = [循环B] + 1 循环B = [循环A] + 1 ``` 编辑器会在保存前检查确定性的同记录公式依赖；发现闭环时禁用“确定”，并显示完整路径： ```text 公式存在循环引用：循环A → 循环B → 循环A ``` 已经存在于旧文件中的循环公式仍会被运行时保护拦截。表头显示错误图标和完整路径，点击图标可直接编辑对应公式；单元格只显示简短的“循环引用”，悬浮时可查看完整链路，避免每一行重复铺满长错误信息。 解决方法是让依赖保持单向，至少保留一个独立输入字段。例如： ```text 循环A = [基准值] + 1 循环B = [循环A] + 1 ``` 跨记录 Lookup 的依赖是否成环取决于实际关联记录，因此仍由运行时按真实数据检测，避免保存时误报合法的父子记录计算。 #### 结果类型与显示格式 公式会根据运算符、函数和引用字段推断结果类型，也可以在字段设置中手动指定数字、文本、布尔值或日期类型。数字型公式可设置普通数字、千分位、百分比或货币格式；日期型公式可设置日期格式。 查找、汇总和公式使用统一的结果格式入口。显示格式只影响界面展示，不会把数字变成带货币符号的文本，也不会影响下游公式计算。 #### 逻辑函数 | 函数 | 说明 | | --- | --- | | `if(条件, 成立结果, 不成立结果)` | 条件判断 | | `ifs(条件1, 结果1, 条件2, 结果2, …, 默认值)` | 多条件判断，返回第一个成立的结果 | | `switch(值, 匹配1, 结果1, 匹配2, 结果2, …, 默认值)` | 多分支匹配 | | `and(条件, …)` / `or(条件, …)` / `not(条件)` | 逻辑与 / 或 / 非，and/or 短路求值 | | `iferror(表达式, 出错结果)` | 表达式报错时返回兜底值，如 `iferror([金额] / [数量], 0)` | | `iserror(表达式)` | 表达式是否报错，如 `if(iserror([单价] * [数量]), "待补数据", "已就绪")` | | `isblank(值)` | 是否为空文本 | | `isnumber(值)` | 是否为数字，可筛出未填或填成文本的行 | | `xor(条件, …)` | 奇数个条件成立时返回是（恰好一个成立最常用） | | `blank()` | 空值，常与 if 搭配返回空 | #### 数学函数 | 函数 | 说明 | | --- | --- | | `round(数字)` / `round(数字, 保留位数)` | 四舍五入 | | `floor(数字)` / `ceil(数字)` | 向下 / 向上取整 | | `abs(数字)` | 绝对值 | | `mod(被除数, 除数)` | 取余数，结果符号跟随除数 | | `pow(底数, 指数)`（别名 `power`） | 乘方 | | `sqrt(数字)` | 平方根 | | `int(数字)` | 向零取整，`int(-1.7) = -1`（与 `floor(-1.7) = -2` 不同） | | `sign(数字)` | 取符号，正数 1、负数 -1、零 0 | | `roundup(数字[, 保留位数])` | 远离零进位 | | `rounddown(数字[, 保留位数])` | 朝零舍去 | | `value(文本)` | 文本转数字，容忍千分位与百分号：`value("1,234") = 1234`、`value("85%") = 0.85` | #### 文本函数 | 函数 | 说明 | | --- | --- | | `concat(a, b, …)` | 拼接文本 | | `len(文本)` | 文本长度 | | `upper(文本)` / `lower(文本)` | 转大写 / 小写 | | `left(文本, 个数)` / `right(文本, 个数)` | 取左侧 / 右侧字符 | | `mid(文本, 起始位置, 个数)` | 取中间字符，位置从 1 开始 | | `trim(文本)` | 去掉首尾空白 | | `replace(文本, 查找, 替换)` | 全部替换 | | `repeat(文本, 次数)` | 重复文本 | | `find(查找文本, 原文本)` | 查找位置，从 1 开始，找不到返回 0 | | `contains(原文本, 查找文本)` | 是否包含 | | `startswith(原文本, 前缀)` / `endswith(原文本, 后缀)` | 是否以…开头 / 结尾 | | `split(文本, 分隔符, 第几段)` | 按分隔符取一段，段号从 1 开始，越界返回空文本 | | `padstart(文本, 目标长度[, 填充字符])` / `padend(…)` | 左 / 右补齐，如 `padstart([编号], 5, "0")` 把 42 补成 00042；省略填充字符时用空格 | #### 日期函数 | 函数 | 说明 | | --- | --- | | `today()` | 今天的日期 | | `now()` | 当前日期时间（精确到分钟） | | `datediff(a, b)` | 相差天数（a - b） | | `dateadd(日期, 数量, 单位)` | 日期加减，单位为 `天/周/月/年`（也接受 `days/weeks/months/years`），数量可为负；月末溢出收敛到目标月最后一天 | | `dateformat(日期, 格式)` | 格式化，支持 `YYYY/YY/MM/M/DD/D/HH/mm/ss` 令牌，如 `dateformat([日期], "YYYY年M月D日")` | | `year(日期)` / `month(日期)` / `day(日期)` | 取年 / 月 / 日 | | `hour(日期时间)` / `minute(日期时间)` | 取小时（0-23）/ 分钟（0-59） | | `weekday(日期)` | 取星期，周一=1 … 周日=7 | | `date(年, 月, 日)` | 由年月日拼日期。月/日越界按进位收敛，`date(2026, 13, 1)` 得 `2027-01-01`，可用 `date([年], [月] + 1, 1)` 取下月 1 号 | | `eomonth(日期, 偏移月数)` | 月末日，`0` 本月、`-1` 上月、`1` 下月，自动处理闰年 | 示例： ```text [单价] * [数量] ``` ```text ifs([分数] >= 90, "优秀", [分数] >= 60, "及格", "不及格") ``` ```text switch([状态], "进行中", "🔵", "已完成", "🟢", "⚪") ``` ```text dateadd([开始日期], 2, "周") ``` ```text concat(dateformat([日期], "M月D日"), " 共 ", round([金额], 2), " 元") ``` 限制： - 公式不能引用自身或形成字段依赖闭环；编辑器会在保存前显示完整循环路径。 - 多值查找结果不能直接参与标量四则运算，需要先使用 `first`、`sumitems`、`avgitems` 等函数。 - 插件不使用 JavaScript `eval` 执行公式。 - 公式错误会显示为错误值，而不是阻止整个表格打开。 - `if` / `ifs` / `switch` 只求值命中的分支，`and` / `or` 短路求值；需要兜底错误时用 `iferror`。 ### 14.20 创建时间 系统字段，记录创建时间，只读。 ### 14.21 最后更新时间 系统字段，记录最后修改时间，只读。 ### 14.22 自动编号 系统字段，按记录顺序生成编号，可配置前缀和位数。 ## 15. 字段管理 ### 15.1 新增字段 在表格工具栏点击“字段”或表头右侧的 `+`，在“新建字段”面板里输入字段名并选择类型。类型选择是双列卡片，与“修改字段类型”面板一致；类型较多时可用上方的搜索框过滤，鼠标停在卡片上会显示该类型的说明。 新字段会加入当前表，并同步出现在各视图配置中。 在“字段”面板中拖动字段手柄可调整当前视图的列顺序；勾选框用于显示或隐藏列，顺序和隐藏状态按视图分别保存。 ### 15.2 编辑字段 字段编辑面板可配置： - 字段名称。 - 字段类型。 - 字段描述。 - 是否必填。 - 数字格式、范围。 - 日期格式。 - 单选/多选选项。 - 公式表达式。 - 关联目标。 - 查找目标。 - 汇总函数。 - 详情分组。 - frontmatter 同步键。 单选和多选选项可在字段编辑面板中拖动手柄调整全局顺序；多选单元格下拉面板中的“已选标签顺序”只调整当前记录的值顺序。 字段类型变更前，插件会尽量显示迁移影响，避免误改导致数据不可读。单选或多选改为文本、长文本或附件时，写入的是选项名而不是内部选项 ID，多选按逗号分隔；迁移预览不会修改记录，原字段的选项定义保持完整。 重命名字段时，插件会同步改写公式字段和单元格公式中的精确字段引用。例如把“单价”改为“销售单价”时，`[单价] * [数量]` 会更新为 `[销售单价] * [数量]`。引号中的普通文本以及名称相近的其他字段不会被误替换。字段名仍不允许重复。 ### 15.3 删除字段 删除字段会移除该列及对应单元格值。删除前应确认没有其他公式、查找、汇总或视图配置依赖该字段。 ### 15.4 必填字段 字段可设为必填。必填字段会在表头显示星号，未填写时单元格有视觉提示。 两种视图下的强度不同，这是刻意的： - **表单视图**：硬校验。必填项为空时提交被拒绝，并在该项下方显示错误。表单一次只提交一条记录，语义明确。 - **表格视图**：只提醒不拦截。单元格提交、按 Delete 清空选区、粘贴这三类操作若清空了必填格，会给一条汇总提示（"已清空 N 个必填单元格…"），但写入照常生效。表格是自由录入场景，中途拦下会让粘贴、填充、撤销这类批量操作变得难以预期——一格不合规就得整批回滚。 必填不会阻止整张表保存，也不会对存量数据做全表扫描，因此给已有表格加必填标记不会被历史空值刷屏。 ### 15.5 详情分组 字段可设置“详情分组”。打开记录详情时，同组字段会收进可折叠小节，适合把字段分成： - 基础信息 - 进度与状态 - 链接与附件 - 数据指标 - 复盘备注 详情分组折叠状态按视图保存。 ## 16. 筛选、排序、搜索和颜色规则 ### 16.1 筛选 筛选按字段类型提供不同运算符： - 文本类：包含、不包含、等于、不等于、为空、不为空。 - 数字类：等于、不等于、大于、大于等于、小于、小于等于、为空、不为空。 - 日期类：等于、早于、晚于、是今天、是本周、是本月、为空、不为空。 - 单选/多选：是其中任一、不是其中任一、为空、不为空。 - 勾选：已勾选、未勾选。 - 公式/查找：支持文本类和部分比较类运算。 筛选规则支持“且 / 或”整体切换。 ### 16.2 排序 排序可按字段升序或降序排列。可叠加多个排序规则。 ### 16.3 搜索 顶部搜索框用于在当前表格内快速查找。搜索命中时，单元格文字会高亮。 ### 16.4 条件颜色规则 颜色规则是视图级配置。你可以给符合条件的记录设置浅色行背景或色条。 典型用法： - 状态 = 逾期，显示红色。 - 优先级 = 高，显示橙色。 - 完成 = 已勾选，显示绿色。 - 发布日期 = 本月，显示蓝色。 手动单元格颜色与条件颜色可以并存，手动颜色优先。 ## 17. 记录详情 ### 17.1 打开记录详情 常见入口： - 点击行号悬浮出现的“展开记录”。 - 双击或右键记录后选择“打开详情”。 - 在看板、画廊、日历、时间线中点击卡片。 记录详情支持侧栏和居中大卡片两种展示模式。 ### 17.2 详情中可以做什么 记录详情里可以： - 查看和编辑所有字段。 - 查看长文本 Markdown 预览。 - 进入上一条/下一条记录。 - 绑定 Markdown 笔记。 - 打开绑定笔记。 - 同步当前记录到笔记 frontmatter。 - 查看字段分组并折叠/展开。 上一条/下一条基于当前视图可见记录顺序。 ## 18. 绑定笔记与 frontmatter 同步 ### 18.1 绑定笔记 记录可以绑定一篇 Markdown 笔记。绑定后，记录内部会保存 `notePath`。 绑定入口通常在记录详情或记录右键菜单中。 ### 18.2 字段同步键 字段可以设置 `syncKey`，表示它对应 Markdown frontmatter 中的哪个属性名。 例如： - 字段“状态”的同步键为 `status` - 字段“平台”的同步键为 `platform` - 字段“评分”的同步键为 `rating` 同步时，插件会把记录值写入绑定笔记的 frontmatter。 ### 18.3 同步所有绑定记录 更多操作菜单中有“同步所有绑定记录”。执行后，插件会遍历当前表中绑定笔记的记录，将带同步键的字段写入对应 Markdown frontmatter。 同步结果会进入同步日志，包含： - 已同步 - 已跳过 - 失败 失败项可在同步日志里查看并重试。 ### 18.4 反向同步 当绑定笔记的 frontmatter 在 Obsidian 中被修改后，如果对应字段有 `syncKey`，打开中的 `.duowei` 表格会把变化同步回记录值。 插件带有回环保护，避免自己写入 frontmatter 后又被误判为外部修改。 ### 18.5 自动继承笔记属性与写回保护 打开带绑定笔记的表格、给记录绑定笔记，或绑定笔记的属性在 Obsidian 中被修改时，插件会把笔记 frontmatter 里尚未映射到任何字段的属性自动作为新字段加入表格： - 新字段的同步键就是属性名，类型按现有值推断（没有值时为文本）；名称与现有字段重名时自动加序号。 - 新字段在所有视图中默认隐藏，不改变现有视图的显示；需要时在“字段”面板中勾选显示，或直接删除。删除字段不会修改笔记。 - 继承和读取只会更新表格，绝不会因此写笔记；库数据源表格、只读表格和关闭笔记联动的表格不会继承。 写回笔记遵循“先观察再写回”： - 只有你在表格里明确修改过的字段才会写回对应属性；打开表格、继承属性和“同步所有绑定记录”对尚未读取过的字段先从笔记导入现有值，不会把空值写回。 - 写回前会核对源笔记中该属性是否已经被别处改动。已改动时保留双方内容、不覆盖源笔记，并提示“属性在源笔记中已变化”；同一笔记的多个待写属性整体校验，不会只写一半。 - 读取笔记失败或元数据缓存缺失时不写回，并在右上角给出提示。 ### 18.6 查找当前笔记关联的多维表格 当你打开一篇 Markdown 笔记时，可以执行命令： “多维表格：查找当前笔记关联的多维表格” 插件会扫描库内 `.duowei` 文件，找出绑定了当前笔记的记录，并提供打开入口。 ## 19. 导入与导出 ### 19.1 导入 CSV/TSV 入口：更多操作菜单 -> 导入 CSV/TSV。 导入流程： 1. 选择或粘贴 CSV/TSV 数据。 2. 插件识别分隔格式。 3. 显示导入预览。 4. 映射源列到目标字段。 5. 确认字段类型。 6. 查看错误行。 7. 导入可成功行。 导入时可用 Ctrl/Cmd + Enter 确认。 ### 19.2 导出 CSV/TSV 入口： - 更多操作菜单 -> 导出 CSV - 更多操作菜单 -> 导出 TSV 导出适合把当前表格数据交给 Excel、Numbers、其他脚本或外部系统处理。 ### 19.3 从文件夹创建可编辑独立表格 这是面向 Obsidian 笔记库的导入方式，见“5.4 从文件夹创建可编辑独立表格”。 ### 19.4 从 Base 导入 这是从 Obsidian Bases 迁移的导入方式，见“5.3 从现有 `.base` 迁移到 `.duowei`”。 ## 20. Markdown 笔记内嵌表格 插件支持两种 Markdown 笔记内嵌方式： 1. 像 Obsidian Bases 一样使用文件嵌入语法（wikilink）。 2. 使用 `duowei` 代码块精确控制视图、行数和字段。 两种方式都能嵌入表格视图，也都能嵌入单张仪表盘图表。 ### 20.1 嵌入表格视图 文件嵌入示例： ```markdown ![[多维表格/项目管理.duowei]] ![[多维表格/项目管理.duowei#表格]] ``` `#表格` 可替换成目标视图名称。未指定视图时优先使用表格视图或第一个视图。 代码块示例： ````markdown ```duowei path: 多维表格/项目管理.duowei view: 表格 limit: 20 fields: 标题, 状态, 截止日期 ``` ```` 嵌入表格特点： - 只读展示，不在笔记内直接编辑。 - 会应用指定视图的筛选和排序。 - 默认展示视图前 6 个可见字段。 - 源 `.duowei` 文件修改或重命名后会自动刷新。 - 点击列头可临时排序（升序 → 降序 → 还原），头部放大镜可快速搜索，均不写回源文件。 - 链接、邮箱、电话、笔记链接渲染为可点击链接，进度字段渲染为迷你进度条。 - 双击才会跳转：双击绑定笔记的行打开该笔记，双击其余区域打开原表格。单击不跳转，避免查看时误触。 - 嵌入场景不解析关联目标文档，关联字段显示为“几条关联”。 - 笔记“导出为 PDF”时，嵌入的表格和图表会一并导出：表格自动展开全部行（不受屏幕内滚动高度限制）、隐藏搜索/筛选等交互按钮，并尽量避免在行中间分页。 ### 20.2 嵌入仪表盘图表 可以嵌入整个仪表盘视图，也可以只嵌入其中一张图表： ```markdown ![[项目管理.duowei#仪表盘]] ![[项目管理.duowei#图表:状态统计]] ![[项目管理.duowei#仪表盘/状态统计]] ![[项目管理.duowei#图表:状态统计?source=全部记录&type=pie]] ``` `图表:` 后面写图表标题，也可以写图表 id。`?` 后面可追加参数，临时覆盖图表的展示方式，**不会修改源表格里的图表定义**。多个参数用 `&` 或 `;` 分隔。 不必手写这串链接，有三种更省事的方式： - 命令面板执行“插入多维表格图表引用”，在弹窗里选表、选图表、调参数，右下角有实时预览。 - 在文件列表里右键 `.duowei` 文件，选择“复制图表引用…”，粘贴进任意笔记。 - 已经用 wikilink 嵌入的单张图表，鼠标移到卡片上会出现铅笔按钮，点它可直接改参数并写回笔记里的链接。代码块形式的嵌入没有这个按钮，直接改代码块即可。 嵌入的图表卡片上都有一个“复制为图片”按钮，可把当前图表复制到剪贴板。 ### 20.3 内嵌参数说明 代码块的参数写成 `键: 值`，wikilink 的参数写成 `?键=值&键=值`。同一个参数在两种语法里通用。 | 参数 | 别名 | 说明 | | --- | --- | --- | | `path` | — | 仅代码块必填，`.duowei` 文件路径，可省略扩展名 | | `view` | — | 视图名称或 id | | `widget` | `chart`、`图表`、`组件` | 仪表盘图表标题或 id（代码块里用它替代 `#图表:`） | | `source` | `datasource`、`数据源` | 图表数据源：`全部记录`、`当前视图`，或其它视图名/id | | `type` | `kind`、`图表类型` | 覆盖图表类型：`number`、`bar`、`pie`、`line` | | `title` | `name`、`标题` | 覆盖图表标题 | | `titlePosition` | `position`、`标题位置` | 标题位置：`top`、`bottom` | | `group` | `field`、`分组` | 覆盖分组字段（柱状图/饼图/折线图），或数字卡的统计字段 | | `summary` | `stat`、`统计` | 数字卡统计方式：`filled`、`unfilled`、`sum`、`avg`、`min`、`max`、`unique`、`checked` | | `aggregate` | `agg`、`聚合` | 图表数值方式：`count`、`sum`、`avg` | | `value` | `valueField`、`数值字段` | `sum` / `avg` 使用的数值字段 | | `limit` | — | 表格嵌入显示行数，1–500，默认 100 | | `fields` | — | 按字段名限定显示列，英文或中文逗号分隔 | 参数值支持中文写法，例如 `type=饼图`、`aggregate=求和`、`summary=已填写`、`source=全部记录`、`titlePosition=下方`。 代码块形式引用单张图表： ````markdown ```duowei path: 多维表格/项目管理.duowei widget: 状态统计 source: 全部记录 type: pie group: 状态 aggregate: sum value: 预算 ``` ```` ## 21. 外部同步：Notion、飞书、Zotero、日历、待办与微信收件箱 Microsoft 和 Google 的授权分为三层，三层缺一不可： 1. **应用注册**：插件发布者在 Microsoft Entra 和 Google Cloud 中一次性配置 OAuth 应用。 2. **用户授权**：每位用户在微软或 Google 官方页面登录自己的账号，允许插件访问指定范围的数据。 3. **表格绑定**：用户在每一张 `.duowei` 表格中选择要同步的 To Do 清单、Tasks 清单或日历。 普通用户只需要完成第 2、3 层，不需要进入开发者控制台。只有插件发布者、私有部署者或企业使用自有 OAuth 应用时才需要完成第 1 层。 > [!important] 同步的是当前登录用户自己的数据 > Client ID 只是公开的“应用编号”，不是开发者账号、密码或访问令牌。所有安装用户可以共用插件内置 Client ID，但每位用户仍要单独登录和授权。插件拿到的是当前登录用户的令牌，读取和修改的也是该用户有权访问的任务与日历；使用内置 Client ID 不会把数据同步到插件开发者账号。 ### 21.1 先理解账户、Client ID 和功能边界 #### 21.1.1 当前内置 OAuth 应用 | 平台 | 插件内置 Client ID | 用途 | 是否属于敏感凭据 | | --- | --- | --- | --- | | Microsoft | `1bc7fd64-8ff3-4a8b-94fe-65039ebee76c` | 标识 Duowei Table Pro 的 Entra 公共客户端 | 否，可以随插件分发 | | Google | `167261226329-edj6louks96bprao3a8tocarpo7k8pll.apps.googleusercontent.com` | 标识 Duowei Table Pro 的桌面 OAuth 客户端 | 否，可以随插件分发 | | 两个平台的访问令牌、刷新令牌 | 每位用户授权后单独生成 | 代表该用户访问获准的数据 | **是，禁止公开或共享** | 一个 Client ID 可以供很多用户使用，不是“一人一个 Client ID”： - Microsoft：只要应用的“支持的账号类型”允许，个人账号和组织账号都可以分别授权。实际使用仍受 Microsoft Graph 限流、组织同意策略和发布者验证策略约束。 - Google 测试状态：最多添加 100 个指定测试用户，未列入测试用户的账号不能完成授权。 - Google 正式发布：不再受“100 个测试用户”这一测试名单上限约束，但敏感权限需要完成 OAuth 验证，并继续受 API 配额和 Workspace 管理策略约束。 #### 21.1.2 当前版本实际支持什么 | 服务 | 当前同步能力 | 当前不包含的能力 | | --- | --- | --- | | Microsoft To Do | 一个 `.duowei` 表格绑定一个 To Do 清单；双向同步标题、完成状态、截止日期和重要性 | 不是完整的 Microsoft Planner 同步 | | Outlook 日历 | 可选地把已绑定 To Do 任务的标题与截止日期投影为默认 Outlook 日历中的全天事件 | 不能像 Google Calendar 一样独立选择任意 Outlook 日历，也不把普通 Outlook 日程完整导入表格 | | Google Tasks | 一个表格绑定一个 Tasks 清单；双向同步标题、备注、完成状态和截止日期 | Google Tasks 的截止时间只保留日期，不保留具体时分秒 | | Google Calendar | 一个表格绑定一个有写权限的日历；双向同步标题、开始、结束、全天、说明和地点 | 不同步循环事件实例、循环规则及非默认特殊事件类型 | | Zotero 本地文库 | 桌面端连接个人文库、群组文库或 Collection；同步文献元数据、PDF 附件和 Markdown 笔记，可按字段开启写回 | 只连接当前电脑的 Zotero Local API；移动端和远程云端 API 不可用 | > [!note] 当前任务与日历同步是手动触发 > 绑定时会执行一次首次同步；之后通过“同步中心”的“立即同步”或“同步任务与日历”触发。当前手册不把它描述为后台实时同步。 #### 21.1.3 不做正式版也可以 如果目前只供自己、小团队或测试用户使用，可以暂时不完成 Google 正式验证，也可以暂时不做 Microsoft 发布者验证： - Google 保持“测试”状态，把每位使用者的 Google 邮箱加入测试用户。 - Google 测试状态通常约 7 天后需要重新授权；重新登录不会删除 `.duowei` 数据或表格绑定。 - Microsoft 个人账号通常可直接测试；组织账号是否能授权取决于该组织的用户同意策略。未验证的多租户应用更容易被企业策略拦截。 - 准备公开分发给大量用户或企业客户时，再完成品牌页面、隐私政策、域名所有权、OAuth 验证和 Microsoft 发布者验证。 ### 21.2 发布者配置 Microsoft Entra OAuth 应用 普通用户跳过本节，直接阅读[[#21.4 插件设置页怎么配置|21.4]]和[[#21.5 普通用户授权全过程|21.5]]。 Microsoft 官方参考：[注册应用](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app)、[配置桌面公共客户端](https://learn.microsoft.com/en-us/entra/identity-platform/scenario-desktop-app-configuration)、[Graph 权限参考](https://learn.microsoft.com/en-us/graph/permissions-reference)。 #### 21.2.1 创建或检查应用注册 1. 打开 [Microsoft Entra 管理中心](https://entra.microsoft.com/)。 2. 进入“标识/Identity → 应用程序/Applications → 应用注册/App registrations”。 3. 新建应用时点击“新注册/New registration”；已有应用则打开当前 Duowei 应用。 4. 显示名称建议填写 `Duowei Table Pro`。 5. “支持的账号类型”按分发范围选择： - 需要同时支持个人 Outlook/Hotmail 和 Microsoft 365 工作或学校账号：选择“任何组织目录中的帐户和个人 Microsoft 帐户”。 - 只允许个人账号：选择仅个人 Microsoft 账户。 - 只在一个企业租户内使用：选择仅此组织目录中的账户，并在插件“登录租户”中填写该租户 ID。 6. 注册完成后，在“概述”页复制 **应用程序（客户端）ID**。当前内置值应为 `1bc7fd64-8ff3-4a8b-94fe-65039ebee76c`。 不要把以下字段误填到插件的 Client ID： - 对象 ID：只是当前租户中应用对象的内部编号。 - 目录（租户）ID：用于限定登录租户，不是 Client ID。 - Client Secret：本插件 Microsoft 登录使用公共客户端设备代码流，不需要也不应在桌面插件中嵌入 Secret。 #### 21.2.2 配置公共客户端和桌面平台 1. 在应用注册左侧打开“身份验证/Authentication”。 2. 点击“添加平台/Add a platform”。 3. 选择“移动和桌面应用程序/Mobile and desktop applications”。 4. 勾选或添加： ```text https://login.microsoftonline.com/common/oauth2/nativeclient ``` 5. 在“高级设置/Advanced settings”中把“允许公共客户端流/Allow public client flows”设为“是/Yes”。 6. 保存。 设备代码协议本身不依赖浏览器回调地址，但应用仍必须被识别为公共客户端。为兼容个人 Microsoft 账号和 Entra 的桌面应用配置，建议保留上述“移动和桌面应用程序”平台与 `nativeclient` 地址。不要把它配置成 Web 或 SPA 客户端，也不要创建 Client Secret。 > [!note] 当前版本的设备代码登录行为 > 插件统一引导用户打开 `https://microsoft.com/devicelogin`，登录范围包含 `openid profile offline_access` 以及实际启用的 Microsoft Graph 权限。设备代码请求本身不发送 `redirect_uri`；如果微软错误信息仍提到 `redirect_uri`，通常表示自有 Entra 应用尚未配置为公共桌面客户端，按本节补齐平台回复地址并开启公共客户端流后重新登录。 #### 21.2.3 添加 Microsoft Graph 委托权限 打开“API 权限/API permissions → 添加权限/Add a permission → Microsoft Graph → 委托的权限/Delegated permissions”，添加： | 权限 | 是否必需 | 插件用途 | | --- | --- | --- | | `Tasks.ReadWrite` | 必需 | 读取、新建和更新当前登录用户的 Microsoft To Do 清单与任务 | | `Calendars.ReadWrite` | 可选 | 开启“同步到 Outlook 默认日历”后，创建、更新和删除插件投影的全天事件 | | `offline_access` | 登录时动态请求 | 获取刷新令牌，访问令牌到期后继续使用；控制台中不一定作为普通 Graph 权限单独显示 | | `openid profile` | 登录时动态请求 | 建立标准登录会话；插件不依赖邮箱或通讯录权限 | `Tasks.ReadWrite` 和 `Calendars.ReadWrite` 的委托权限在微软权限目录中通常不要求管理员同意，但企业租户可以通过自己的用户同意策略阻止普通成员授权。这种情况下必须由该租户管理员审核或同意，插件发布者不能绕过。 > [!tip] 日历权限按需申请 > 插件只有在“同步到 Outlook 默认日历”开启时才把 `Calendars.ReadWrite` 加入登录范围。开关变化后，插件会清除旧 Microsoft 令牌并要求重新登录，以确保令牌权限与开关一致。 #### 21.2.4 品牌与发布者验证 个人测试可先不做发布者验证。准备面向企业或跨租户公开分发时，建议： 1. 在“品牌和属性/Branding & properties”填写应用名称、主页、隐私声明、服务条款和支持信息。 2. 配置自有且已验证的发布者域名。 3. 如果拥有 Microsoft AI Cloud Partner Program 资格，关联 Partner ID 完成[发布者验证](https://learn.microsoft.com/en-us/entra/identity-platform/publisher-verification-overview)。 4. 使用另一个租户的普通成员账号测试授权，确认没有被“未验证发布者”或组织策略拦截。 #### 21.2.5 Microsoft 发布前自测 1. 插件高级设置中填写自有 Microsoft Client ID，租户先用 `common`。 2. 关闭 Outlook 日历开关，使用个人账号登录，确认能列出 To Do 清单并完成任务同步。 3. 开启 Outlook 日历开关，按提示重新登录，确认授权页新增日历权限。 4. 给任务设置截止日期并同步，检查默认 Outlook 日历中是否生成全天事件。 5. 修改事件标题或日期后再同步，确认回写任务；删除该事件后同步，确认只清除任务截止日期。 6. 如果支持企业用户，再用不同租户的工作账号完成一次测试。 ### 21.3 发布者配置 Google OAuth 应用 普通用户跳过本节。Google 官方参考：[启用 Workspace API](https://developers.google.com/workspace/guides/enable-apis)、[配置 OAuth 同意屏幕](https://developers.google.com/workspace/guides/configure-oauth-consent)、[创建桌面客户端](https://developers.google.com/workspace/guides/create-credentials)、[桌面应用 OAuth/PKCE](https://developers.google.com/identity/protocols/oauth2/native-app)。 #### 21.3.1 创建项目并启用 API 1. 打开 [Google Cloud Console](https://console.cloud.google.com/)。 2. 在顶部项目选择器中创建或选择专门用于 Duowei Table Pro 的项目。 3. 进入“API 和服务 → 库/API Library”。 4. 分别搜索并启用： - **Google Calendar API** - **Google Tasks API** 5. 确认右上角仍是同一个项目；OAuth 品牌、受众、客户端和已启用 API 必须位于同一项目中。 #### 21.3.2 配置 Branding 进入“Google Auth Platform → 品牌/Branding”，至少完成： 1. 应用名称：建议 `Duowei Table Pro`。 2. 用户支持电子邮件：填写发布者可接收问题的邮箱。 3. 开发者联系信息：填写可接收 Google 通知的邮箱。 4. 测试阶段 Logo 可暂不上传；上传后可能触发品牌验证。正式发布时建议使用清晰的 120 × 120 方形 JPG、PNG 或 BMP，且不超过 1 MB。 5. 仅内部测试时，应用首页、隐私政策和服务条款可先留空（以控制台实际必填提示为准）。准备公开验证时必须使用真实、可访问且与应用一致的页面。 6. 正式填写网页链接前，先在“已获授权的网域/Authorized domains”添加根域名，并通过 Google Search Console 验证域名所有权。不要填写不存在的隐私政策或条款链接。 #### 21.3.3 配置 Audience：测试版推荐方案 1. 进入“Google Auth Platform → 受众/Audience”。 2. 面向普通 Gmail 或多个 Workspace 组织时选择“外部/External”。 3. 发布状态保持“测试中/Testing”。 4. 在“测试用户/Test users”中逐个添加允许登录的 Google 邮箱。 5. 保存后等待几分钟，再让用户授权。 > [!warning] Google 测试状态的两个限制 > 测试用户最多 100 个。由于本插件请求 Calendar/Tasks 数据权限，测试用户的授权和刷新令牌通常约 7 天后失效，需要在插件设置中点击“重新登录”。这是 Google 测试应用的行为，不是表格或绑定丢失。 #### 21.3.4 配置 Data Access 权限范围 进入“Google Auth Platform → 数据访问/Data Access”，添加并保存以下三个 scope： | Scope | 插件用途 | | --- | --- | | `https://www.googleapis.com/auth/tasks` | 读取和写入当前用户的 Google Tasks 清单与任务 | | `https://www.googleapis.com/auth/calendar.events` | 读取和写入用户有权访问的日历事件 | | `https://www.googleapis.com/auth/calendar.calendarlist.readonly` | 读取用户的日历列表，从中列出可写日历供绑定 | 当前版本连接 Google 账户时会一次申请这三个 scope，即使用户只打算使用 Tasks 或只打算使用 Calendar，也会看到完整授权范围。日历列表权限只用于列出日历；插件选择器仅显示用户角色为 Owner 或 Writer 的日历。 #### 21.3.5 创建 Desktop app 客户端 1. 进入“Google Auth Platform → 客户端/Clients”。 2. 点击“创建客户端/Create client”。 3. 应用类型选择“桌面应用/Desktop app”，名称可填 `Duowei Table Pro Desktop`。 4. 创建后复制 Client ID。当前内置值应为： ```text 167261226329-edj6louks96bprao3a8tocarpo7k8pll.apps.googleusercontent.com ``` 5. 插件使用系统浏览器、PKCE 和随机本机回环地址： ```text http://127.0.0.1:<随机端口>/oauth2callback ``` Desktop app 客户端不需要在控制台逐个登记这些随机端口。 6. 插件内置登录不需要填写 Google Client Secret；使用自有客户端时一般也应保持为空。只有自定义客户端明确要求且控制台确实提供时才填写。 不要把客户端创建成“Web 应用”。Web 客户端要求固定且完全匹配的重定向 URI，无法直接替代当前随机回环端口流程。 #### 21.3.6 测试状态与正式发布怎么选 | 使用场景 | 建议状态 | 需要做的工作 | 用户体验 | | --- | --- | --- | --- | | 仅自己使用 | Testing | 添加自己的 Google 邮箱 | 可用，但通常约 7 天重新登录 | | 小范围内测 | Testing | 逐个添加测试用户，最多 100 个 | 每位用户可能看到未验证提示，并周期性重新登录 | | 同一 Workspace 组织内部使用 | Internal（仅符合条件的 Workspace 项目） | 由组织管理员配置 | 仅本组织用户可用 | | 面向公众或大量用户 | In production + 验证 | 品牌、域名、首页、隐私政策、条款、scope 说明、演示视频等 | 不再依赖测试用户名单；敏感权限审核通过后警告减少 | 正式验证以 Google Verification Center 的实时清单为准。Calendar/Tasks 属于用户数据权限，通常需要解释最小权限用途，并提供展示完整授权与数据使用流程的演示视频。官方参考：[OAuth 应用验证](https://support.google.com/cloud/answer/13463073?hl=zh-Hans)、[验证要求](https://support.google.com/cloud/answer/13464321?hl=zh-Hans)。 #### 21.3.7 Google 发布前自测 1. 把测试账号加入 Test users。 2. 在插件高级设置中填写自有 Google Client ID，Client Secret 留空。 3. 在桌面端连接账号，确认系统浏览器打开且授权后自动返回 Obsidian。 4. 分别绑定一个 Google Tasks 清单和一个自己拥有的测试日历。 5. 创建、修改任务与日程后执行“立即同步”，确认双向更新。 6. 清除一个已绑定日程的开始、结束时间并同步，确认远端事件被删除；再用测试数据验证远端删除的处理。 7. 在 Google 账号的第三方访问页面撤销授权，再确认插件能提示重新登录。 ### 21.4 插件设置页怎么配置 打开“Obsidian 设置 → Duowei Table Pro → 外部同步”。这里管理的是**当前设备的账户凭据和命令入口**，不是某一张表的远端目标。 #### 21.4.1 通用开关 - **显示外部服务命令**：默认开启。关闭后隐藏 Notion、飞书、Zotero、Microsoft To Do、Google Tasks、Google Calendar 的连接、导入、发布、绑定、同步、完整校验和解绑命令；不会删除令牌、表格连接或任何业务数据。 - 如果只是不想在命令面板看到这些命令，可以关闭；以后重新开启即可恢复入口。 #### 21.4.2 Microsoft To Do 与 Outlook 日历 | 设置项 | 推荐值 | 说明 | | --- | --- | --- | | 同步到 Outlook 默认日历 | 只在确实需要任务日历投影时开启 | 开启后额外申请 `Calendars.ReadWrite`；开关变化会清除旧令牌并要求重新登录 | | Microsoft 账户 | 点击“连接账户” | 已连接时显示“重新登录”和“断开” | | Microsoft Client ID | 普通用户保持内置值 | 仅私有部署或自有 Entra 应用填写 | | 登录租户 | `common` | 同时允许个人和组织账号；`organizations` 只允许组织账号，`consumers` 只允许个人账号，也可填具体租户 ID | | 恢复内置 Microsoft OAuth | 需要回到官方内置应用时点击 | 只恢复 Client ID 与 `common`，不会自动断开当前账户 | #### 21.4.3 Google 日历与待办 | 设置项 | 推荐值 | 说明 | | --- | --- | --- | | Google 账户 | 在 Obsidian 桌面端点击“连接账户” | 首次登录必须通过系统浏览器完成；已连接时可重新登录或断开 | | Google Client ID | 普通用户保持内置值 | 仅自有 Google Cloud Desktop app 客户端填写 | | Google Client Secret | 留空 | 内置登录使用 PKCE，不需要 Secret | | 恢复内置 Google OAuth | 需要回到官方内置应用时点击 | 恢复内置 Client ID、清空自定义 Secret，但不会自动断开当前账户 | > [!warning] 更换 OAuth 应用的正确顺序 > 令牌与签发它的 Client ID 配套。需要在内置应用和自有应用之间切换时，先点击“断开”，再修改或恢复 Client ID/租户/Secret，最后重新连接。仅修改 Client ID 后继续使用旧令牌，可能产生刷新失败、权限不一致或账号状态判断错误。 ### 21.5 普通用户授权全过程 #### 21.5.1 授权前检查 - 确认插件来自可信渠道，授权页显示的应用名称与 Duowei Table Pro 一致。 - 确认登录的是准备同步数据的本人账号。 - 工作或学校账号受组织管理员策略约束；“普通委托权限不要求管理员同意”不等于组织一定允许用户自行授权。 - Google 应用处于 Testing 时，先让发布者把该邮箱加入 Test users。 - Google 首次授权必须在 Obsidian 桌面端完成；Microsoft 使用设备代码，可在同一台或另一台已联网设备的浏览器完成。 #### 21.5.2 授权 Microsoft 1. 打开“设置 → Duowei Table Pro → 外部同步”。 2. 展开“Microsoft To Do 与 Outlook 日历”。 3. 需要 Outlook 全天事件投影时，**先**打开“同步到 Outlook 默认日历”；不需要则保持关闭以减少授权范围。 4. 点击“连接账户”。已连接过时按钮显示为“重新登录”。 5. 插件显示 Microsoft 官方设备登录地址和一次性代码。 6. 点击弹窗中的链接，或手动打开 [https://microsoft.com/devicelogin](https://microsoft.com/devicelogin)。 7. 输入一次性代码，登录自己的 Outlook/Hotmail 或 Microsoft 365 账号。 8. 核对应用名称和权限：To Do 必须包含任务读写；启用日历投影时还应包含日历读写。 9. 点击接受/同意，然后返回 Obsidian。 10. 设置组右侧显示“已连接”即完成。代码过期或取消时，重新点击“连接账户”生成新代码。 #### 21.5.3 授权 Google 1. 如果应用仍处于 Testing，先确认当前 Google 邮箱已加入 Test users。 2. 在 Obsidian 桌面端打开“设置 → Duowei Table Pro → 外部同步”。 3. 展开“Google 日历与待办”，点击“连接账户”或“重新登录”。 4. 插件启动本机临时回调端口，并自动打开系统默认浏览器；弹窗中也有“打开 Google 登录”按钮。 5. 选择准备同步的 Google 账号。 6. 核对应用名称，查看 Google Tasks、Google Calendar 事件和日历列表权限。 7. 测试应用可能显示“Google 尚未验证此应用”。只有在确认插件来源、应用名称和 Client ID 均可信时才继续；来源不明时立即取消。 8. 同意后，Google 把结果返回 `127.0.0.1` 本机临时地址。该地址只在本机接收一次授权结果，不是上传数据的网站。 9. 浏览器显示授权完成后返回 Obsidian，设置组显示“已连接”即完成。 > [!note] 用户授权后能访问哪些数据 > 权限代表“当前登录用户允许插件做什么”，不是把账号所有权交给插件。插件只能访问该账号在授权范围内有权访问的数据。用户可随时在 Microsoft 或 Google 的账号安全页面撤销第三方应用授权。 ### 21.6 表格绑定、字段映射与同步规则 #### 21.6.1 绑定当前表格 账户“已连接”只说明插件拿到了当前设备的账号许可；每张表仍需单独选择远端目标： 1. 打开一张**可编辑的独立 `.duowei` 表格**。实时只读索引不能绑定任务或日历服务。 2. 点击右上角“更多操作 → 同步中心…”。 3. 打开“任务与日历”页签。 4. 按需点击： - Microsoft To Do → “绑定清单”。 - Google Tasks → “绑定清单”。 - Google Calendar → “绑定日历”。 5. 选择目标清单或日历。Google Calendar 选择器只显示当前账号拥有或有写权限的日历。 6. 绑定后会立即执行首次同步，并复用合适的现有字段或自动创建缺失字段。 7. 后续可在单个服务卡片点击“立即同步”，或点击顶部“同步任务与日历”一次处理当前表格的所有任务与日历绑定。 一张表可以同时绑定 Microsoft To Do、Google Tasks 和 Google Calendar。首次同时接入多个任务服务时，建议先只绑定一个并核对数据，再逐个增加，避免同名任务形成重复记录。 #### 21.6.2 自动字段映射 | 服务 | 自动识别或创建的字段 | 关键限制 | | --- | --- | --- | | Microsoft To Do | 标题、完成、截止日期、重要性 | 空标题不会创建远端任务 | | Google Tasks | 标题、备注、完成、截止日期 | 截止日期只同步 `YYYY-MM-DD`，不保存时间 | | Google Calendar | 日程、开始时间、结束时间、全天、日程说明、地点 | 没有有效开始时间时不会新建远端事件 | 插件会优先复用名称和类型兼容的字段，例如“标题/任务/任务名称”“完成/已完成”“截止日期/到期日期”。映射字段被删除或改成不兼容类型后，同步会提示“字段映射已失效”；重新执行“更换清单/更换日历”可重建映射。 #### 21.6.3 首次匹配与冲突处理 - Microsoft To Do 和 Google Tasks 会尝试按**唯一标题**自动绑定尚未绑定的本地任务与远端任务；标题重复时不会安全猜测。 - Google Calendar 全量同步时优先使用插件写入的稳定同步 ID；没有 ID 时才按“标题 + 开始时间”匹配。 - 两端都修改同一条记录时，插件记录为冲突并比较本地、远端更新时间，较新一侧覆盖较旧一侧。 - 为避免误配，首次同步前最好给任务设置唯一、非空标题，并先备份表格。 - “问题与日志”页签会显示一致性问题和同步日志；只有被判定为安全的重复任务才提供自动修复。 #### 21.6.4 Outlook 和 Google 的任务日历投影 **Outlook 投影：** - 在设置页开启“同步到 Outlook 默认日历”后，每个已绑定 Microsoft To Do 任务只要有截止日期，就会在当前账号的默认 Outlook 日历中创建一个全天、显示为“空闲”、无提醒的事件。 - 事件标题和日期与任务标题、截止日期双向更新。 - 清除任务截止日期会删除插件创建的 Outlook 事件；在 Outlook 删除该事件通常会清除任务截止日期，但不会删除 To Do 任务。若本地标题或截止日期同时发生变化，插件会按冲突规则保留较新内容并在同步摘要中提示冲突。 - 这是 To Do 的附加投影，不是独立 Outlook 日历同步。 **Google 投影：** - 当当前表格已绑定 Google Calendar，并且还绑定 Microsoft To Do 或 Google Tasks 时，“任务与日历”顶部出现“将任务截止日期投影为 Google 全天事件”。 - 开启后，有截止日期的任务可投影到所选 Google 日历；单条记录可保留自己的投影状态。 - 该投影与普通 Google Calendar 日程共用当前所选日历，正式使用前建议先在测试日历验证。 #### 21.6.5 删除、解除和远端缺失的规则 任务与日历同步不会把“删除本地整行”一律解释为“删除远端”，以免一次误删扩散到云端： - 删除本地任务行不会自动删除 Microsoft To Do 或 Google Tasks 任务；远端任务仍存在时，后续同步可能再次导入本地。 - 在 Microsoft To Do 或 Google Tasks 删除远端任务后，同步会保留本地行并记录远端缺失/已删除，不会静默删除本地资料。 - Google Calendar：清空一个已绑定普通日程的开始、结束时间并同步，会删除对应远端事件并解除该记录的日历绑定。 - Google Calendar 远端事件被删除后，普通日程会清空本地开始、结束时间并解除绑定；任务投影事件被删除后会关闭该记录的日历投影。若删除后本地记录又有更新，插件优先保留本地内容、解除旧绑定并记录冲突，后续同步可能按本地内容重建事件。 - Outlook 投影事件的删除规则见 21.6.4。 - “解除”只移除当前表格与服务的连接及记录绑定，不删除任一端业务记录。重新绑定会作为新的同步关系处理。 ### 21.7 断开、安全与故障排查 #### 21.7.1 “断开账户”和“解除绑定”不是同一件事 | 操作位置 | 影响范围 | 不会做什么 | | --- | --- | --- | | 设置页 Microsoft“断开” | 清除当前设备保存的 Microsoft 访问令牌和刷新令牌 | 不删除表格绑定，不主动撤销微软账号端授权，不删除任务或日历事件 | | 设置页 Google“断开” | 尝试向 Google 撤销当前令牌，然后清除本地令牌 | 不删除表格绑定、任务或日程；网络撤销失败时仍会清除本地令牌 | | 当前表格同步中心“解除” | 移除这一张表与所选清单/日历的连接及记录 ID | 不断开账号，不删除本地记录或远端数据 | 需要彻底停止使用时，建议先在每张表中“解除”，再在设置页“断开”，最后到 Microsoft/Google 账号安全页面撤销 Duowei Table Pro 的第三方应用访问。 #### 21.7.2 令牌和共享库安全 Microsoft 与 Google 的访问令牌、刷新令牌保存在当前 Obsidian 库的插件数据文件中，通常是： ```text .obsidian/plugins/duowei-table-pro/data.json ``` 令牌不会写入 `.duowei` 文件，也不会因为使用内置 Client ID 自动上传给插件开发者；`.duowei` 只保存表格级连接和远端记录 ID，以便重新登录后继续同步。 > [!warning] 不要共享插件数据文件 > 不要发送、公开、提交到 Git 或同步到多人可读配置目录中的 `data.json`。Client ID 可以公开，Client Secret、访问令牌和刷新令牌不可以。共享同一个 Obsidian 库时，建议每位用户使用独立配置目录或排除插件 `data.json`。 不要直接删除 `data.json` 代替正常断开；其中还包含插件其他设置。令牌疑似泄漏时，应立即到账号安全页撤销应用访问，再重新登录生成新令牌。 #### 21.7.3 常见问题对照表 | 现象 | 常见原因 | 处理方法 | | --- | --- | --- | | 已连接，但当前表格不能同步 | 账户授权和表格绑定是两步 | 打开表格“更多操作 → 同步中心… → 任务与日历”，确认对应服务显示“已绑定” | | 命令面板没有 Microsoft/Google 命令 | “显示外部服务命令”被关闭，或没有打开可编辑 `.duowei` 表格 | 在设置页打开该开关，并先打开目标表格 | | Microsoft 设备代码过期 | 登录等待时间过长 | 关闭弹窗，重新点击“连接账户”，使用新代码 | | Microsoft 提示公共客户端不允许 | Entra 应用未开启公共客户端流 | “身份验证 → 高级设置 → 允许公共客户端流”设为“是” | | Microsoft 提示缺少 `redirect_uri` 或个人账号跳到 `login.live.com` 后报错 | 自有应用未配置桌面平台兼容项 | 添加“移动和桌面应用程序”平台和 `https://login.microsoftonline.com/common/oauth2/nativeclient`，保存后重新登录 | | Microsoft 个人账号不受支持 | 应用账号类型或插件租户设置过窄 | 应用改为支持个人 Microsoft 账户；插件租户用 `common` 或 `consumers` | | Microsoft 企业账号拒绝授权 | 组织禁止用户同意未验证或第三方应用 | 联系该组织管理员审核/同意；必要时完成发布者验证 | | 开启 Outlook 日历后仍没有事件 | 旧令牌没有 `Calendars.ReadWrite`、任务无截止日期或同步未触发 | 切换开关后重新登录；给任务填写截止日期；执行“立即同步” | | Google 提示“访问被阻止”或 `access_denied` | 账号未加入 Test users，或 Workspace 管理员阻止第三方应用 | 添加准确的 Google 邮箱并等待配置生效；企业账号联系管理员 | | Google 约一周后要求重新登录 | OAuth 应用仍处于 Testing | 点击“重新登录”；表格、字段和绑定不会丢失。需要长期免频繁登录时完成正式发布与验证 | | Google 提示 Calendar/Tasks API 未启用 | API 与 OAuth 客户端不在同一项目，或 API 尚未启用 | 在当前 Client ID 所属项目启用 Google Calendar API 和 Google Tasks API | | Google 浏览器授权成功但没有返回 Obsidian | 本机回环端口被防火墙、安全软件或代理拦截 | 保持授权弹窗打开，允许 Obsidian 监听 `127.0.0.1` 临时端口，关闭占用/拦截后重试 | | Google `redirect_uri_mismatch` | 错用了 Web 客户端，或自有客户端类型不对 | 新建 OAuth“桌面应用/Desktop app”客户端；Client Secret 留空并重新登录 | | Google 列表里找不到某个日历 | 当前账号只有只读/忙闲权限，或日历未加入当前账号列表 | 给当前账号 Writer/Owner 权限，并确认日历已出现在 Google Calendar 左侧列表 | | 同步产生同名重复任务 | 两端原有同名记录不唯一，无法安全自动匹配 | 在一端先改成唯一标题；到“问题与日志”检查，只有安全重复项才使用自动修复 | | 修改 Client ID 后刷新失败 | 旧令牌由另一个 Client ID 签发 | 断开账户，确认新 Client ID/租户/Secret，再重新授权 | | 字段映射已失效 | 映射字段被删除或改成不兼容类型 | 在同步中心重新选择“更换清单”或“更换日历”以重建映射 | #### 21.7.4 最小验收清单 完成配置后，用测试清单和测试日历依次验证： - [ ] Microsoft 连接成功，能列出并绑定 To Do 清单。 - [ ] 本地新建、远端新建、两端修改都能在手动同步后出现。 - [ ] 开启 Outlook 投影时，带截止日期任务生成默认日历全天事件。 - [ ] Google 连接成功，能列出并绑定 Tasks 清单和可写日历。 - [ ] Google Tasks 的标题、备注、完成和日期双向同步。 - [ ] Google Calendar 的标题、时间、全天、说明和地点双向同步。 - [ ] 删除、清空日期/时间和解除绑定的结果符合 21.6.5，而不是误以为会级联删除。 - [ ] 断开并重新登录后，原有 `.duowei` 记录和表格绑定仍在。 - [ ] 同步日志没有持续的权限、API 未启用、刷新令牌或字段映射错误。 ### 21.8 Notion 与飞书同步方式总览 Notion 和飞书属于“多维表格”型连接，与 Microsoft To Do、Google Tasks、Google Calendar 分开运行。打开表格右上角“更多操作 → 同步中心…”，同步中心分为： - **多维表格**：连接、预览、同步 Notion 或飞书。 - **任务与日历**：管理 Microsoft 和 Google 连接。 - **问题与日志**：处理字段冲突、远端记录缺失、待审核删除和中断事务，查看同步日志与操作日志。 一张本地 `.duowei` 表格同一时刻只能连接一个表格型远端：Notion、飞书或 Zotero 只能选其一。需要更换远端时先解除原连接；解除只删除本地连接、记录绑定和同步基线，不会删除任一端的业务记录。 根据数据起点选择操作路径： | 你的现状 | 推荐入口 | 结果 | | --- | --- | --- | | Notion/飞书已有完整数据，本地还没有表 | 命令面板“从 Notion/飞书创建本地多维表格” | 新建 `.duowei`、导入记录并建立后续双向同步基线 | | 本地已有完整数据，远端还没有表 | 命令面板“将当前多维表格发布到新的 Notion/飞书…” | 新建远端结构、发布记录并建立连接 | | 本地表和远端表中只有一端有记录 | 同步中心“连接 / 新建” | 映射字段后，首次同步从非空一端建立另一端记录 | | 两端都有尚未绑定的记录 | 不建议直接连接 | 插件不会按标题猜测配对；预览会列出未匹配冲突。应先备份并清空一端，或用导入/发布路径重建连接 | > [!important] 首次连接不要把两份已有数据直接“撞”在一起 > 插件只有在一端为空时才会自动建立记录绑定。两端都有记录时，即使标题相同也不会自动认定为同一条，避免错误合并。 ### 21.9 准备 Notion Integration Notion 使用 Internal Connection 的静态 Installation access token。插件界面沿用较熟悉的“Integration Token”称呼；它不是 Notion 账号密码，也不是公开分享链接中的参数。该模式不需要配置 OAuth 回调、Client ID 或 Client Secret。 #### 21.9.1 Notion 所需能力 在 Notion Creator dashboard 的 Connection“Configuration → Capabilities”中配置。完整双向同步建议同时开启三个 Content capabilities： | Notion 能力 | 插件中的用途 | 不开启时的影响 | | --- | --- | --- | | `Read content` | 读取 Database、Data Source、字段结构、页面记录、视图和远端附件信息 | 无法读取字段、导入记录或计算同步差异 | | `Insert content` | 新建 Database、Data Source 页面记录和 File Upload | 无法从本地发布新数据库、创建远端记录或上传本地附件 | | `Update content` | 更新页面属性、补充 Data Source 属性、调整插件创建的目标视图、把页面移入回收站 | 无法推送修改、补齐远端字段或确认删除远端记录 | 本插件不读取评论，也不依赖 Notion 用户邮箱，因此无需开启 Read comments、Insert comments 或“User information with email addresses”。遵循最小权限原则： - 只做一次性远端读取时，API 本身至少需要 `Read content`。 - 保留“仅拉取”的长期连接时也只应映射为仅拉取；任何推送、新增记录或附件上传都会因缺少写能力失败。 - 使用完整双向同步时直接开启 Read、Insert、Update 三项，避免在首次写入时才遇到 403。 > [!important] 能力授权和内容授权是两道门 > 开启 Read/Insert/Update 只说明 Connection 可以执行这类 API；还必须把具体父页面或数据库授予该 Connection。缺少任意一层都无法同步。 #### 21.9.2 在 Notion 创建 Internal Connection 1. 使用目标工作区的 Workspace Owner 账号进入 Notion Creator dashboard。 2. 在左侧“Build → Internal connections”点击“Create a new connection”。 3. 填写名称，例如 `Duowei Table Sync`，并选择正确的工作区与安装范围。 4. 创建后打开“Configuration”页。 5. 在“Capabilities”开启 `Read content`、`Insert content`、`Update content`；用户信息选择“不读取用户信息”即可。 6. 在同页复制 Installation access token。Token 通常以平台当前格式显示，插件同时兼容常见的 `ntn_...` 与旧式 `secret_...`。 7. 把 Token 临时保存在密码管理器中。不要放入 Markdown、`.duowei`、Git 仓库、截图或群聊。 如果 Token 泄漏，应立即回到 Configuration 刷新/轮换 Token，并在插件连接向导输入新 Token。旧 Token 失效后，不需要重建本地表或远端数据库。 #### 21.9.3 授予目标页面或数据库访问权 可在两处授权，二选一即可： - Creator dashboard → 当前 Connection → `Content access` → `Edit access`，选择父页面或目标数据库。 - Notion 页面右上角 `•••` → `Connections` / `Add connections`，搜索并添加当前 Connection。 连接已有数据库： 1. 打开真正承载数据的原始数据库，而不是只包含 Linked view 的展示页面。 2. 把数据库添加给 Connection；授权父页面时，其子页面通常继承访问权。 3. 如果工作区使用数据库关系字段，相关数据库也必须单独授权才能让 API 读取完整关系信息。当前插件不会同步关系字段本身，但缺失授权可能让其他公式/汇总信息显示不完整。 由插件新建数据库： 1. 在 Notion 新建一个普通页面，例如“Duowei 同步数据库”。 2. 把这个普通页面添加给 Connection。 3. 复制普通页面链接，稍后作为“新建位置”或插件默认父页面。 4. 不要填写现有数据库链接作为父页面。当前插件使用 Internal Connection，不能在工作区根目录直接创建私有数据库。 #### 21.9.4 找到正确的 Data Source 当前插件使用 Notion API `2026-03-11`。在新版 API 中： - Database 是外层容器。 - Data Source 是真正包含字段和页面记录的数据源。 - 一个 Database 可能包含多个 Data Source。 获取目标时优先执行： 1. 打开 Notion 数据库设置。 2. 进入“Manage data sources / 管理数据源”。 3. 对准备同步的具体数据源使用“Copy data source ID”。 4. 把 Data Source ID 或对应数据库链接粘贴到插件向导。 连接向导接受： - Data Source ID。 - 只包含一个 Data Source 的普通 Database ID。 - 可访问的 Notion 数据库链接。 如果一个 Database 包含多个 Data Source，请直接填写具体 Data Source ID。插件不会替用户猜测应同步哪一个。 #### 21.9.5 配置插件端 Notion 设置 1. 打开“设置 → Duowei Table Pro”。 2. 展开“外部同步”。如命令面板里看不到发布/导入命令，确认“显示外部服务命令”已开启。 3. 在“Notion 新建数据库默认父页面”粘贴 21.9.3 中已授权的普通父页面链接或 Page ID。只连接已有数据库时可以留空。 4. 如果会拉取远端附件，可在通用设置“外部图片/附件保存路径”填写例如 `附件/{{table}}`；留空则沿用 Obsidian“文件与链接 → 附件文件夹路径”。 5. 打开任意 Notion 连接/导入/发布向导，第一次输入 Token。成功保存后同一设备的其他本地表会复用；更换 Connection 时再输入新 Token。 “Notion 新建数据库默认父页面”只保存目标位置，不保存 Token，也不会自动给该页面授权。更换父页面后要先在 Notion 中把新页面添加给同一个 Connection。 #### 21.9.6 Notion 权限验证 建议从低风险动作逐级验证： 1. 在一张测试表中点击“读取远端字段”。成功说明 Token、`Read content` 和目标内容授权基本正确。 2. 点击“预览”。确认记录与字段能够完整读取。 3. 新建一条测试本地记录并“立即同步”。成功说明 `Insert content` 可用。 4. 修改测试记录再同步。成功说明 `Update content` 可用。 5. 有附件时再测试一个小文件上传与远端拉取。 6. 最后删除测试本地记录，在“待审核删除”中选择“移入 Notion 回收站”，验证删除审核链路。 错误定位： - **401 Unauthorized**：Token 错误、已轮换或复制不完整。 - **403 Forbidden**：缺少 Read/Insert/Update 中对应能力。 - **404 Object not found**：最常见原因是目标页面/数据库没有添加给 Connection；Notion 会用 404 隐藏未授权资源。 - **能读取但不能补字段**：缺少 `Update content`，或当前成员/Connection 对目标数据库只有读取权限。 - **能导入但不能发布新数据库**：缺少 `Insert content`，父页面未授权，或把数据库误当作普通父页面。 Notion 官方参考： - [Internal connections](https://developers.notion.com/guides/get-started/internal-connections) - [Connection capabilities](https://developers.notion.com/reference/capabilities) - [Retrieve a data source](https://developers.notion.com/reference/retrieve-a-data-source) - [Create a database](https://developers.notion.com/reference/create-database) ### 21.10 准备飞书自建应用 飞书使用企业自建应用的 App ID 与 App Secret。插件有两种身份链路： - **应用身份**：通过 App ID / App Secret 获取 tenant access token，适合连接应用已经获权的现有飞书多维表格。 - **用户身份**：用户在浏览器完成 OAuth，插件取得 user access token 和刷新令牌，适合在该用户个人目录新建 Base，并处理需要用户权限的附件上传/下载。 只在开放平台申请 API 权限并不等于能访问某张具体表。最终权限是“应用已申请的 API 权限 ∩ 当前身份权限 ∩ 目标文档/高级权限范围”的交集。 #### 21.10.1 飞书权限码清单 在飞书开放平台“权限管理 / API 权限”中按权限码搜索 Base 与 media 权限。插件用户 OAuth 会请求以下 scope 集合；其中 `offline_access` 是授权链接中的特殊 OAuth scope，控制台可能不会把它显示为一项普通 API 权限，无需单独搜索。 | 权限码 | 插件用途 | 典型必需场景 | | --- | --- | --- | | `offline_access` | 获取刷新令牌，在用户访问令牌到期后静默刷新 | 个人目录 OAuth 长期使用 | | `base:app:read` | 读取多维表格 Base 信息 | 连接、导入、同步已有 Base | | `base:app:create` | 创建新的多维表格 Base | 从本地发布到新的飞书 Base | | `base:table:read` | 读取数据表信息 | 连接指定 Table、读取结构 | | `base:table:create` | 在 Base 中创建数据表 | 发布新 Base | | `base:field:read` | 列出字段与字段类型 | 读取远端字段、生成映射、预览 | | `base:field:create` | 新增字段 | 发布结构、“补齐缺失字段” | | `base:record:retrieve` | 读取记录 | 导入、预览、增量/完整同步 | | `base:record:create` | 新增记录 | 本地新记录推送、首次发布 | | `base:record:update` | 更新记录 | 双向同步中的本地修改推送 | | `base:record:delete` | 删除记录 | 待审核删除中确认“删除飞书” | | `docs:document.media:download` | 读取附件素材并换取临时下载地址 | 远端附件拉取 | | `docs:document.media:upload` | 上传 `bitable_file` 附件素材 | 本地附件推送 | | `wiki:node:read` | 把 `/wiki/` 知识库节点解析为实际 Base Token | 可选，仅应用身份使用 `/wiki/` 链接时需要 | 飞书控制台的中文权限名称可能随版本微调，优先按上表权限码搜索。`wiki:node:read` 不在插件默认用户 OAuth scope 中；当前版本优先使用最终 `/base/` 链接。必须使用 `/wiki/` 链接时，应让连接走已开通该权限的应用身份。 #### 21.10.2 按场景选择权限 | 场景 | 至少需要 | | --- | --- | | 只读取已有表，不含附件 | `base:app:read`、`base:table:read`、`base:field:read`、`base:record:retrieve`，并让应用可访问目标表 | | 已有表完整双向同步 | 上述读取权限 + `base:record:create`、`base:record:update`；需要从待审核删除远端时再加 `base:record:delete` | | 允许“补齐缺失字段” | 完整同步权限 + `base:field:create` | | 从本地发布新 Base | `base:app:create`、`base:table:create`、`base:field:create`、记录读写权限，以及用户 OAuth | | 拉取远端附件 | 读取权限 + `docs:document.media:download` | | 推送本地附件 | 写入权限 + `docs:document.media:upload` | | 使用 `/wiki/` 链接 | 应用身份的对应同步权限 + `wiki:node:read`；当前默认用户 OAuth 不包含该 scope | 为了启用插件全部飞书能力，建议一次开通 21.10.1 表中的 Base 权限和两个 media 权限；`offline_access` 由插件在 OAuth 时自动请求。不使用知识库链接时不申请 `wiki:node:read`。 #### 21.10.3 创建企业自建应用 1. 登录飞书开放平台，进入“开发者后台 / 开发者控制台”。 2. 点击“创建应用 → 企业自建应用”，填写应用名称、图标和描述。 3. 打开“凭证与基础信息”，复制 App ID 和 App Secret。App Secret 只输入插件连接向导，不要粘贴到表格字段、笔记或群聊。 4. 打开“权限管理 / API 权限”，按 21.10.1 搜索并申请 Base 与 media 权限；需要应用身份解析知识库链接时再申请 `wiki:node:read`。 5. 如果平台要求区分应用权限与用户权限，为连接已有企业资源配置对应 API 可用的应用身份权限；为个人目录发布和 media 能力配置用户身份权限。 6. 打开“版本管理与发布”，创建版本，确认新增权限和可用范围，提交发布或管理员审核。 7. 等版本状态显示已发布/已启用后，再回到 Obsidian 测试。仅保存草稿版本不会让新权限生效。 企业管理员可能需要在飞书管理后台审批应用、权限或可用范围。应用发布成功但当前用户不在可用范围内时，OAuth 页面可能无法授权，目标表也可能拒绝访问。 #### 21.10.4 配置 OAuth 回调并授权个人目录 1. 在 Obsidian 打开“设置 → Duowei Table Pro → 外部同步”。 2. 找到“飞书 OAuth 回调地址”，点击“复制”。默认值为 `http://localhost:17654/oauth/callback`。 3. 回到飞书开放平台当前应用，进入“开发配置 → 安全设置 → 重定向 URL”。 4. 粘贴完整回调地址。协议、主机、端口、路径必须逐字符一致；不要把 `localhost` 改成公网域名，也不要漏掉 `/oauth/callback`。 5. 保存安全设置，并再次创建、发布包含该重定向 URL 和最新权限的应用版本。 6. 回到 Obsidian，先打开任意飞书连接向导保存一次 App ID / App Secret。 7. 再到“飞书个人目录身份”点击“授权个人账户”。首次授权仅支持 Obsidian 桌面端。 8. 浏览器中登录准备存放 Base 的飞书账号，检查授权应用名称和权限，确认同意。 9. 回到设置页，状态显示“已授权”即完成。插件会保存刷新令牌并在后续自动刷新。 授权页缺少刚申请的权限时，通常是新应用版本尚未发布，或旧用户令牌未重新授权。先发布版本，再点击“重新授权”。 #### 21.10.5 让应用访问具体飞书多维表格 连接已有 Base 时，还要在目标文档内授权： 1. 打开目标飞书多维表格。 2. 在共享、更多菜单或文档应用入口中添加当前企业自建应用；不同飞书版本入口名称可能是“添加文档应用”“文档应用”或协作者管理。 3. 至少授予查看权限；需要推送、补字段或删除远端记录时授予可编辑权限。 4. 如果启用了高级权限，确认应用/授权用户能访问目标数据表、参与同步的字段和对应记录。API 总权限无法绕过高级权限规则。 5. 从浏览器地址栏复制包含 `table=tbl...` 的链接。`view=` 参数可以保留，插件会忽略它；`table=` 才决定同步哪张数据表。 6. 如果只有 App Token，可在数据表链接的查询参数中取得 Table ID，或在插件向导单独填写以 `tbl` 开头的 ID。 使用 `/wiki/` 链接时，插件会先调用知识库节点 API 解析真实 Base Token。若缺少 `wiki:node:read`，会提示“飞书未找到该多维表格”。当前默认用户 OAuth 不请求该 scope，最稳妥的处理是改用 `/base/` 直链；必须保留 `/wiki/` 链接时，先给应用身份申请并发布该权限，并让该连接使用应用身份而不是个人 OAuth 身份。 > [!note] 当前设备已授权飞书个人身份时 > 普通 Base 请求会优先使用个人 OAuth 身份。必须测试 `/wiki/` 应用身份连接时，可在插件设置“飞书个人目录身份”点击“断开”，再用 App ID / App Secret 连接；断开只清除用户令牌，不删除应用凭证和表格连接。若同时需要个人目录发布，仍建议直接换成 `/base/` 直链，避免两种身份反复切换。 #### 21.10.6 配置插件端飞书设置 “设置 → Duowei Table Pro → 外部同步”包含： | 设置项 | 如何填写 | 作用 | | --- | --- | --- | | 显示外部服务命令 | 开启 | 在命令面板显示飞书连接、导入、发布、同步相关命令 | | 飞书个人目录身份 | 点击“授权个人账户”或“重新授权” | 获得用户身份，用于个人目录新建 Base 和 media 权限 | | 飞书 OAuth 回调地址 | 保持默认或填写固定本机回调，并同步到开放平台重定向 URL | 接收浏览器 OAuth 授权结果 | | 飞书新建表格默认目录 | 粘贴个人云空间文件夹链接或 `folder_token` | 发布新 Base 时的默认目录；留空使用个人空间根目录 | | 外部图片/附件保存路径 | 例如 `附件/{{table}}`，或留空 | 远端附件下载到本地时的基础目录 | “飞书新建表格默认目录”只接受 `/drive/folder/...` 文件夹链接或原始 `folder_token`，不能填写 Base 链接。文件夹必须属于当前已授权用户可写的个人云空间。 #### 21.10.7 飞书权限验证 按以下顺序验证，便于定位是哪一层权限失败： 1. **应用凭证**：在连接向导输入 App ID / App Secret，点击“读取远端字段”。凭证错误通常在获取 access token 时失败。 2. **API 读取权限**：能列出字段，说明 Base/Table/Field 读取权限与目标资源授权基本正常。 3. **记录读取权限**：执行“预览”，确认能读取记录和远端更新时间。 4. **记录创建/更新权限**：用测试记录执行一次“立即同步”，分别验证新增和修改。 5. **字段创建权限**：只在测试 Base 中点击“补齐缺失字段”。 6. **附件权限**：先测试一个小于 20 MB 的本地文件上传，再测试一个远端附件拉取。 7. **删除权限**：删除测试本地记录后，在“待审核删除”中逐条确认“删除飞书”。 8. **个人目录发布**：最后测试创建一个新 Base，确认实际落在默认文件夹或个人空间根目录。 错误定位： - **App ID / App Secret 无效**：复制了其他应用凭证、Secret 已重置或包含空格。 - **权限已申请仍 403**：应用新版本未发布/未审批，当前用户不在可用范围，或目标表没有添加应用。 - **能读不能写**：缺少 record create/update/field create，或目标文档只给了查看权限。 - **普通 Base 可用、知识库链接失败**：缺少 `wiki:node:read`，或知识库节点不是多维表格。 - **附件下载/上传失败**：缺少对应 media 权限；旧令牌需要重新授权；高级权限表还需让应用/用户能访问目标记录。 - **OAuth 回调失败**：开放平台重定向 URL 与插件设置不完全一致，端口被占用，或首次授权不是在桌面端执行。 - **发布到了意外目录**：默认文件夹 Token 属于其他账号、无写权限或填写成了 Base Token；清空默认目录后先发布到个人空间根目录验证。 飞书官方 API 参考： - [创建多维表格 Base](https://open.feishu.cn/document/server-docs/docs/bitable-v1/app/create) - [创建数据表](https://open.feishu.cn/document/server-docs/docs/bitable-v1/app-table/create) - [列出记录](https://open.feishu.cn/document/server-docs/docs/bitable-v1/app-table-record/list) - [批量获取素材临时下载地址](https://open.feishu.cn/document/server-docs/docs/drive-v1/media/batch_get_tmp_download_url) - [上传素材](https://open.feishu.cn/document/server-docs/docs/drive-v1/media/upload_all) - [获取知识库节点信息](https://open.feishu.cn/document/server-docs/docs/wiki-v2/space-node/get_node) ### 21.11 路径一：把现有本地表连接到现有远端表 以下步骤适用于本地已有 `.duowei`，并且准备连接现有 Notion Data Source 或飞书数据表。 1. 先备份本地表和远端表，确认两端不是各自都有一批未绑定记录。 2. 打开本地 `.duowei`，进入“更多操作 → 同步中心… → 多维表格”。 3. 在 Notion 或飞书卡片点击“连接 / 新建”。 4. 填写凭证和目标： - Notion：Integration Token 与 Data Source / Database ID 或链接。 - 飞书：App ID、App Secret、飞书链接 / App Token；链接未包含数据表时再填写 Table ID。 5. 点击“读取远端字段”。成功后会显示远端名称、字段数量和字段映射表。 6. 逐行选择本地字段和同步方向；不参与同步的远端字段选择“不映射”。 7. 如本地字段在远端没有对应列，可点击“补齐缺失字段”。插件只新增可安全支持的字段，不会修改或删除已有远端字段。先阅读确认框和未处理原因。 8. 根据需要勾选“打开表格时自动同步”。自动同步遇到冲突时只提示，不自动选边，也不会弹出冲突选择窗口。 9. 点击“保存连接”。 10. 回到同步中心先点“预览”，确认本地新增、本地更新、远端新增、远端更新和冲突数量。 11. 预览无冲突后点击“立即同步”；有冲突时先按 21.17 节处理。 12. 同步完成后分别抽查一条新增记录、一条修改记录、一个选项字段和一个附件字段。 > [!note] 空本地表的便捷行为 > 当前表没有业务字段或记录时，读取 Notion 远端结构可以按可支持的远端属性补充本地字段。正式导入整张远端表时，仍推荐使用“从 Notion/飞书创建本地多维表格”命令。 ### 21.12 路径二：从 Notion 或飞书创建本地表 这条路径最适合“远端是主数据，本地还没有表”。它会保留远端记录 ID，后续可直接增量同步。 #### 从 Notion 创建 1. 打开命令面板，运行“多维表格：从 Notion 数据源创建本地多维表格”。 2. 填写或复用 Integration Token。 3. 粘贴 Data Source / Database 链接或 ID。 4. 设置“本地表格名称”和“本地文件夹”；文件夹留空时保存到库根目录。 5. 根据需要勾选“打开本地表格时自动同步”。 6. 点击“读取并创建本地表”。插件会读取属性和页面、下载可用附件、创建 `.duowei`，再建立同步基线。 #### 从飞书创建 1. 打开命令面板，运行“多维表格：从飞书多维表格创建本地多维表格”。 2. 填写或复用 App ID / App Secret。 3. 粘贴 `/base/`、`/wiki/` 链接或 App Token；必要时补充 Table ID。 4. 设置本地表格名称和本地文件夹。 5. 根据需要勾选自动同步，点击“读取并创建本地表”。 6. 插件会读取字段与记录、忽略真正的空白占位记录、下载可用附件、创建本地文件并初始化基线。 导入完成通知会给出记录数、跳过的不支持字段和基线问题。看到“本地文件已创建，但导入收尾失败”时不要重复导入；先打开已创建的表，在同步中心重试，避免生成重复本地文件。 ### 21.13 路径三：把本地表发布为新的 Notion 或飞书表 这条路径最适合“本地是主数据，远端还没有表”。发布前建议先清理空记录、确认标题字段、规范选项名称并处理附件错误。 #### 发布到新的 Notion 数据库 1. 打开要发布的可编辑 `.duowei`。 2. 运行命令“多维表格：将当前多维表格发布到新的 Notion 数据库”，或在同步中心点击 Notion“连接 / 新建 → 新建并发布”。 3. 填写新 Database 名称和普通父页面链接 / Page ID。父页面必须已连接给当前 Integration，不能填写数据库链接。 4. 选择是否打开表格时自动同步，点击“创建并发布”。 5. 插件先预检附件，再创建 Database、Data Source 和支持的属性，保存连接并按本地记录顺序写入页面。 6. 完成后使用通知中的入口或同步中心“打开 Notion”抽查结果。 #### 发布到新的飞书多维表格 1. 完成 21.10 节的个人账户授权。 2. 打开本地表，运行命令“多维表格：将当前多维表格发布到新的飞书多维表格”，或在同步中心点击飞书“连接 / 新建”。 3. 填写新 Base 名称、数据表名称；可覆盖默认文件夹 Token。 4. 选择自动同步后点击“创建并发布”。 5. 插件以用户身份创建 Base 和字段，保存连接并写入记录；成功后可点击“打开飞书”。 如果当前本地表已经连接同一提供方，发布命令会拒绝继续。需要另建远端表时，先确认业务记录已备份，再解除当前连接。 ### 21.14 字段映射与同步方向 每个映射由“远端字段、本地字段、方向”组成： | 方向 | 本地修改 | 远端修改 | 适合场景 | | --- | --- | --- | --- | | 双向 | 推送到远端 | 拉取到本地 | 两端都需要编辑的业务字段 | | 仅推送 | 推送到远端 | 不覆盖本地 | 本地计算结果、发布状态、只由 Obsidian 维护的字段 | | 仅拉取 | 不写远端 | 拉取到本地 | 远端维护字段、只读属性、远端采集信息 | | 不映射 | 忽略 | 忽略 | 不参与同步的字段 | 映射时遵守以下规则： - Notion 标题属性和飞书主字段必须映射为“双向”或“仅推送”，不能只拉取；它们用于创建远端记录。 - 同一个本地字段不能同时映射到多个远端字段。 - 只读远端字段只能“仅拉取”。 - 文本、长文本、数字、勾选、日期/日期时间、单选、多选、URL、邮箱、电话和附件可参与同步。 - 公式、汇总、关联、人员等复杂远端字段通常只读或不参与映射。 - 选项按显示名称匹配。远端出现本地没有的选项时会进入冲突或待补充流程，不会静默改写字段结构。 - 新建发布时附件默认“仅推送”；从远端导入时附件默认“仅拉取”。确认工作流后可在“更新映射”中调整。 字段映射变化后应先“预览”，再“立即同步”。不要在改映射的同时大批量修改两端数据。 ### 21.15 日常同步与完整同步 连接成功后，在“同步中心 → 多维表格”的服务卡片使用： - **更新映射**：重新读取远端结构，增删映射或改变方向。 - **打开 Notion / 打开飞书**：在浏览器打开已保存的远端目标。 - **预览**：只生成计划，不写本地、不写远端，适合首次连接、改映射或大改数据后检查。 - **立即同步**：执行正常增量同步。插件只处理相对同步基线发生的变化。 - **完整同步**：重新读取全部远端记录并校验绑定与附件，适合怀疑增量遗漏、远端批量改动、同名附件被覆盖或记录绑定异常时使用。它不是“远端强制覆盖本地”。 - **解除**：移除当前本地连接和基线；两端记录都保留。 推荐日常顺序： 1. 在一端完成一批编辑。 2. 第一次或高风险批次先点“预览”。 3. 冲突为 0 时点“立即同步”。 4. 在“问题与日志 → 同步日志”确认成功、跳过和失败数量。 5. 每隔一段时间或发生批量外部修改后运行一次“完整同步”。 开启“打开表格时自动同步”后，插件会在打开时运行增量同步。自动同步有冲突时只显示提示并保留现场；请进入“问题与日志”手动处理。 ### 21.16 首次同步、三方合并与记录匹配 连接建立后，插件为每条已绑定记录保存上次成功同步的字段基线。下一次同步比较“上次基线、本地当前值、远端当前值”： - 只有本地变化：按映射方向推送。 - 只有远端变化：按映射方向拉取。 - 两端值相同：更新基线，不重复写入。 - 同一映射字段两端都变且结果不同：生成字段冲突，由用户选边。 - 某一端新建记录：在另一端新建并保存记录 ID 绑定。 - 远端绑定记录消失：不会直接删除本地，进入“远端记录缺失”处理。 Notion 新建页面按本地记录顺序串行追加，API 拉取按创建时间升序，尽量保持自然顺序。Notion/飞书视图自身的筛选、排序和手动拖拽仍属于远端展示配置，不会作为本地记录排序依据同步。 ### 21.17 处理字段冲突、远端缺失与中断事务 同步发现问题后，打开“同步中心 → 问题与日志”。 #### 同一字段两端都修改 1. 点击同步后打开“解决外部同步冲突”。 2. 对每个字段比较本地值和远端值。 3. 选择“保留本地并推送”或“采用远端并拉取”；也可批量选择全部本地或全部远端。 4. 点击“重新验证并同步”。插件会再次拉取远端；如果确认期间数据又变化，会停止并要求重新处理。 #### 远端记录缺失 - 选择“重建远端记录”：以当前本地记录重新创建远端对象并绑定。 - 选择“删除本地”：确认远端删除是有意行为，并同步删除本地记录。 这两种操作都会在执行前再次确认远端仍然缺失。 #### 创建请求超时或应用中断 远端新建记录的请求可能已经成功，但插件未收到确认。为避免重复创建，系统不会盲目重试，而会显示事务问题： 1. 到 Notion/飞书按标题、创建时间和内容核对远端是否已创建。 2. 确认没有创建时，点击“确认未创建”，解除阻塞并重新规划。 3. 确认已经创建时，点击“填写远端 ID”，输入实际记录 ID。插件只恢复绑定和基线，不会再发创建请求。 判断错误可能在下一轮生成重复记录，因此不要仅凭本地错误提示猜测远端结果。 ### 21.18 本地删除与待审核删除 删除一条已绑定的本地记录时，插件保存删除前快照并把它放入“问题与日志 → 待审核删除”。这套流程适用于 Notion、飞书、Zotero、Microsoft To Do、Google Tasks 与 Google Calendar；本地删除不会自动级联删除远端。 逐条选择： - **恢复本地**：用删除前快照恢复本地记录和绑定。 - **保留远端**：确认只删除本地，远端记录继续保留，并结束审核。 - **删除远端**：在明确确认并再次校验记录身份后处理远端对象。Notion 会移入回收站；其他已开放删除能力的 Provider 会删除对应远端记录、任务或事件。 选择“保留远端”后，插件会记录抑制状态，下一轮同步不会把同一个远端对象重新导入成本地新记录。批量删除前先同步一次并备份。不要把“解除连接”当作远端删除：解除永远保留两端业务记录。 ### 21.19 Notion 与飞书附件同步 - 本地附件发布前会计算 SHA-256；相同内容只上传一次。单文件安全直传上限为 20 MB。 - 本地附件必须是 Obsidian 保管库内可以解析的文件。飞书附件不能只写一个外部 URL；Notion 可以保存 HTTPS 外部文件链接。 - Notion File Upload 只接受其白名单扩展名。不能只把 `.vsdm` 等不支持文件改后缀；应真正压缩成 `.zip` 或转换为 PDF，再在表格中重新选择附件。 - 远端附件拉取后立即保存到 Obsidian 的附件目录下 `外部同步附件/notion` 或 `外部同步附件/feishu`；配置了“外部图片/附件保存路径”时以该目录为基础。单文件下载上限为 100 MB。 - 落盘文件名前带内容哈希；相同内容幂等复用，同名不同内容不会互相覆盖，wiki link 别名保留远端原始文件名。 - 飞书返回 `file_token` 或仍需鉴权的 OpenAPI 地址时，插件每 5 个一批换取临时下载地址，并携带表格、字段、记录上下文以兼容高级权限。 - 远端使用相同文件名替换内容时，只要稳定文件身份或记录更新时间变化，插件会下载复核；内容哈希相同则不提交无意义更新。 - “完整同步”会强制重新校验本地与远端附件。极少数外部程序原地覆盖文件却同时保留大小和修改时间时，可重新选择该附件或执行完整同步重建指纹。 - 下载失败时整批本地变更保持未写入。修复网络、链接、表格权限或素材权限后直接重试，不会留下假的本地路径。 - 飞书旧用户令牌缺少附件权限时，先在开放平台开通 `docs:document.media:download` 与 `docs:document.media:upload`，发布新版本，再在插件设置点击“重新授权”。 ### 21.20 凭证、换设备与解除连接 - Notion Token、飞书 App ID/App Secret 和飞书用户令牌保存在当前设备的 Obsidian `SecretStorage`。 - 这些凭证不会写入 `.duowei`、插件 `data.json`、同步日志、操作日志或冲突提示。 - `.duowei` 保存连接目标、字段映射和记录绑定；恢复状态与附件指纹保存在保管库的 `.duowei/external-sync` 目录。不要手工编辑这些恢复文件。 - 把保管库复制到新设备后，表格连接仍可见，但需要在连接向导重新保存 Notion Token 或飞书凭证；飞书个人目录能力还要在新设备重新授权。 - “断开飞书个人账户”只清除用户令牌，App ID/App Secret 和表格连接仍保留。 - “解除”Notion/飞书连接只删除本地连接、绑定和基线；两端业务记录不删除。 ### 21.21 Notion 与飞书同步排错清单 按以下顺序检查，通常可以快速定位： 1. **确认目标**：是否打开了正确的本地表，Notion Data Source / 飞书 Table ID 是否对应正确数据表。 2. **确认具体资源授权**：Notion 数据库是否 Add connections 给 Integration；飞书目标表是否添加应用并授予可编辑权限。 3. **确认开放平台权限已发布**：飞书新增权限后是否创建并发布应用版本，是否重新授权个人账户。 4. **确认映射**：主字段是否为双向或仅推送；同一本地字段是否被重复映射；字段类型是否兼容。 5. **先点预览**：查看是字段冲突、未匹配记录、远端缺失、附件失败还是事务待核对。 6. **查看问题与日志**：同步日志给出当前批次结果；操作日志用于确认本地执行过哪些处理。 7. **必要时完整同步**：用于重读全部远端数据和附件，不用于强制选边。 8. **避免重复导入/发布**：如果通知明确说本地文件或远端结构已经创建，先在现有对象上恢复连接，不要立刻重跑创建命令。 常见现象： - **Notion 读取失败**：Token 不属于已连接到目标数据库的 Integration，或粘贴了多 Data Source Database 而非具体 Data Source。 - **Notion 新建位置无效**：填了数据库链接、父页面未连接给 Integration，或试图在工作区根目录创建。 - **飞书未找到表格**：应用未被添加到具体表格；`/wiki/` 路径还可能缺少 `wiki:node:read`。 - **飞书能读不能写**：应用在开放平台有 API 权限，但目标表内只有查看权限，或实际写权限尚未在首次写入时通过校验。 - **飞书附件失败**：用户令牌缺少 media scope，应用身份也没有目标素材权限；高级权限表还需让应用可访问对应记录。 - **自动同步只提示冲突**：这是安全设计；进入同步中心手动逐项选边。 - **两端出现未匹配冲突**：首次连接时两端都有未绑定记录。回到 21.8 节选择导入或发布路径，不要按标题强行猜测。 ### 21.22 Zotero 本地文库同步 Zotero Provider 直接访问当前电脑上的 Zotero Local API，不需要 zotero.org API Key，也不会把文献发送到插件发布者的服务器。它只在桌面端 Obsidian 中可用；手机和平板无法连接桌面电脑的 `localhost`，因此不会显示连接和自动同步入口。 #### 21.22.1 启用 Zotero Local API 1. 安装并启动较新的 Zotero 桌面版，确认目标个人文库、群组文库或 Collection 已经在本机可见。 2. 在 Zotero 打开“设置 → 高级”，启用“允许本机其他应用与 Zotero 通信”或含义相同的 Local API 选项。 3. 保持 Zotero 正在运行，再回到 Obsidian。插件连接地址固定为 `http://localhost:23119/api`，不需要手工填写端口。 4. 如果提示 Local API 未启用、无法连接或缺少 Server ID，先升级 Zotero、重启 Zotero，再检查防火墙或安全软件是否拦截本机回环连接。 #### 21.22.2 从 Zotero 创建表格 1. 打开命令面板，执行“多维表格：从 Zotero 文库创建本地多维表格”。 2. 选择“我的文库”或有权限访问的群组文库；如只需要一部分资料，再选择 Collection。 3. 保持默认“仅拉取”最安全。需要把本地修改写回 Zotero 时，点击“启用写回”，在 Zotero 授权框中选择“Always Allow（始终允许）”。 4. 检查字段映射。未授权写回时所有字段固定为仅拉取；授权后，业务字段可分别选择“仅拉取”“双向”或“仅推送”。 5. 按需开启“打开表格时自动同步变更”，然后保存连接。插件会在设置的多维表格目录创建 `.duowei` 文件并执行首次导入。 也可以先打开一张已有 `.duowei` 表格，在“同步中心 → 多维表格”中选择“Zotero 文库”并配置连接。同一张本地表同一时刻只能连接一个表格型远端；如果已经连接 Notion、飞书或 Zotero 的另一个范围，先解除旧连接。 #### 21.22.3 字段、范围与同步方向 一条本地记录对应一条 Zotero 顶层文献。默认字段包含标题、作者、文献类型、出版物、日期、卷期页、出版社、DOI、ISBN、ISSN、URL、摘要、标签、创建时间、修改时间、Zotero 打开链接、PDF 附件和 Zotero 笔记。 - 条目 Key、Zotero 打开链接等身份派生字段固定为仅拉取。 - 写回元数据前会携带规划阶段读取的 Zotero 对象版本；远端已被其他操作修改时，本次写入停止并进入冲突处理，不会覆盖新内容。 - Collection 用于限定同步范围。条目移出 Collection、移入回收站或被删除时会进入远端缺失/删除审核，不会直接删除本地资料。 - Server ID 用于隔离不同电脑或不同 Zotero 本地数据库。换库或换电脑时不要沿用旧基线，按连接向导重新连接。 #### 21.22.4 Zotero 笔记保存在哪里 “Zotero 笔记”在表格中是笔记链接字段。正文保存在表格同目录的 `Zotero 文献笔记` 文件夹中，`.duowei` 只保存 Markdown 路径、远端笔记身份和同步基线，不复制长正文。 插件只同步 Markdown 中以下标记包围的受管区块： ```markdown 这里是与 Zotero 同步的正文 ``` 标记区块外可以继续写“我的研究结论”“引用摘录”等个人内容，插件同步时不会覆盖。旧版本若把 Zotero 笔记保存在长文本字段，首次打开连接时会先把正文无损写入 Markdown，确认落盘成功后再把该字段升级为笔记链接；不要在迁移过程中强制关闭 Obsidian。 如果同一 Zotero 文献只有一条普通子笔记，首次写回可以认领它作为受管笔记；存在多条无法唯一判断的普通笔记时，插件会停止并要求人工处理，不会猜测目标或删除人工笔记。 #### 21.22.5 PDF 附件 - 从 Zotero 拉取的 PDF 显示为带文件名的 `zotero://open-pdf/...` 深链，点击后由 Zotero 打开。 - 把 Obsidian 保管库内的本地 PDF 加入该字段并同步，可将它作为当前父文献的子附件上传。 - HTTPS 文件链接可创建为 Zotero 链接附件；普通 HTTP、保管库外无法读取的本地路径和指向其他文献的附件不会被静默移动。 - 清空附件字段只处理当前文献下由该字段映射的直接 PDF 子附件。删除前先做同步预览并确认计划。 #### 21.22.6 日常同步、完整校验与删除审核 - “同步预览”只比较并生成计划，不写本地文件、不修改 Zotero。 - “立即同步”执行当前计划；开启“打开表格时自动同步变更”后，每次打开表格会自动执行一次。 - “完整校验”忽略上次增量水位，重新读取当前范围的顶层文献和子条目。由于 Zotero 子附件或子笔记变化不一定提升父文献版本，附件或笔记不一致时优先执行完整校验。 - 删除已绑定本地记录后，进入“问题与日志 → 待审核删除”。可以恢复本地、保留 Zotero，或在明确确认后删除对应远端条目。解除连接只移除本地连接和绑定，两端业务数据均保留。 #### 21.22.7 凭证、换设备与排错 - Zotero 只读连接不需要云端密钥。启用写回后得到的持久写入 Key 只保存在当前设备的 Obsidian `SecretStorage`，不会写入 `.duowei`、`data.json`、同步日志或 Markdown 笔记。 - 把 Vault 复制到另一台电脑后，表格连接仍可见，但必须在当地启动对应 Zotero 数据库并重新连接；需要写回时重新选择“Always Allow”。 - **能读取但不能写回**：重新点击“启用写回”，确认 Zotero 授权选择的是“Always Allow”，再检查字段方向是否仍为仅拉取。 - **条目修改后提示版本冲突**：先重新预览；核对两端后逐项选择保留本地或远端，不要重复强推。 - **PDF 或笔记没有更新**：执行完整校验；子条目变化可能没有提升父文献版本。 - **移动端没有 Zotero 入口**：这是预期行为。移动端可查看已经落盘的表格和 Markdown 笔记，但不能访问桌面 Zotero Local API。 ### 21.23 个人微信收件箱同步 把发给扫码绑定的 **ClawBot 会话** 的消息自动追加到本地 `.duowei` 表格。文字写入标题和内容字段；图片、文件、视频下载到库内附件目录并保存附件链接；语音在本机转换为 WAV，自带的转写文本写入“语音转写”字段。 使用前请先确认边界： - 需要在电脑上额外安装并扫码登录本机微信收件服务，插件本身不包含该服务；服务只接收绑定会话收到的消息，不读取完整微信聊天数据库，也不导入历史记录。 - 同步方向仅为微信 → 表格。编辑表格不会向微信发消息，删除表格行也不会撤回微信消息。 - 默认每 3 秒检查一次新消息；网络、附件下载和语音转换会增加实际延迟。设为 0 表示只手动同步。 主要步骤（普通用户走一键安装，全程不需要打开终端）： 1. **安装插件**：安装包含“个人微信收件箱”设置区块的 Duowei Table Pro 并完成授权。 2. **下载服务包**：从百度网盘下载与系统、芯片对应的安装包（https://pan.baidu.com/s/1mGpcOv6XZDmsJlYjP35dOw?pwd=etvg ，提取码 `etvg`，含 Windows `win32-x64` 与 Mac `darwin-arm64` / `darwin-x64`）。 3. **安装并扫码**：完整解压后双击 `Install.cmd`（Windows）或 `Install.command`（Mac），用自己的微信扫码确认，等待终端显示“安装完成”。服务只监听本机 `127.0.0.1:7341`，并自动配置当前用户登录后的后台任务。 4. **连接插件**：打开 **Obsidian 设置 → Duowei Table Pro → 个人微信收件箱**，点击“自动连接本机服务”，插件会自动保存 Token 到 Obsidian SecretStorage、创建专用收件箱表格并把自动同步设为 3 秒；随后点击“测试连接”确认通过。手动填写时依次设置服务地址、目标多维表格、API Token（点“保存 Token”）、“创建/检查表格”和自动同步间隔，不建议直接选一张已有业务表。 5. **首条消息验收**：给本次扫码绑定的 ClawBot 会话发一条文字、一张图片和一段短语音，表格应分别新增三条记录，图片可打开、语音显示 WAV 可播放；再点一次“立即同步”不应重复生成记录。 6. **日常运行**：保持 Obsidian 与电脑上的服务运行即可，关闭安装窗口不影响收件。升级时再次运行新包的 `Install`，重新扫码用 `Repair-login`，停止服务用 `Uninstall`。 命令面板提供“创建个人微信收件箱表格”“同步个人微信收件箱”“测试个人微信收件箱连接”三条命令。收不到消息时先点一次“立即同步”查看错误，再按独立手册第 11 节的顺序排查（消息有没有进服务 → 插件能不能连上服务 → 记录有没有写入表格），不要反复重建表格或重置密钥。手动部署、后台任务、升级换电脑。 ## 22. 自动化 自动化规则由“触发器 → 条件 → 动作 → 执行策略”组成，用于在已保存的数据发生变化后继续完成重复操作，例如同步任务状态、填写默认值、记录完成时间、批量修改记录、更新绑定笔记或调用外部服务。 最重要的使用原则是：先用真实记录预览，再发布运行版本。安全预览只生成计划，不写表格、不改笔记、不创建日历事件，也不发送 Webhook。 ### 22.1 规则引擎的四个组成部分 | 组成 | 作用 | 示例 | | --- | --- | --- | | 触发器 | 决定什么时候检查规则 | “完成”字段变为已勾选、到期日到达、新增记录、仅手动运行 | | 条件 | 决定本次是否继续 | 状态不等于“已取消”，负责人不为空 | | 动作 | 决定按什么顺序执行 | 更新字段、跨表新建记录、更新笔记、调用 Webhook | | 执行策略 | 决定哪些来源可触发、失败怎样停止和补偿 | 响应用户编辑，不响应导入；失败时补偿本地动作 | 规则只处理已经提交的数据变化。还停留在单元格编辑框中、尚未保存的值不会触发。多动作规则按从上到下执行，后面的动作可以读取主流程中前面动作已经计划好的字段结果。 ### 22.2 打开自动化中心 打开一张可编辑的 `.duowei` 表格，通过以下任一入口进入： - 表格右上角“更多操作” → “自动化规则”。 - 命令面板 → “多维表格：管理当前表格自动化”。 - 在文件列表中右键 `.duowei` 文件 → “自动化规则”。 自动化中心会显示当前规则、启用状态、最近运行和需要人工处理的异常。规则之间的连续触发关系收在“高级诊断”中，普通使用不需要配置。 ### 22.3 创建规则前的准备 创建规则前先检查： 1. 触发字段、条件字段和目标字段已经创建，字段类型正确。 2. 单选/多选字段已经配置将要使用的选项，例如“待处理、进行中、已完成”。 3. 表中至少有一条能代表真实情况的样本记录，用于安全预览。 4. 需要更新 Markdown 时，样本记录已经绑定笔记。 5. 需要跨表写入时，目标 `.duowei` 文件可编辑，且保管库中没有相同表 ID 的重复副本。 6. 需要创建 Google 日历事件时，已经在插件设置连接 Google 账号。 7. 需要 Webhook 时，已确认接收端支持固定的 `POST application/json`，并能按 `Idempotency-Key` 去重。 规则引用字段 ID。删除或重建被引用字段后，即使新字段名称相同，旧规则仍会显示“引用字段已不存在”，必须编辑规则重新选择。 ### 22.4 推荐：从场景创建 点击“从场景创建”，选择你希望得到的结果。当前内置场景包括： - 完成任务后同步状态，并可同步进度为 100。 - 状态完成后自动勾选完成。 - 完成时记录实际时间。 - 新记录自动填写初始状态。 - 填写负责人后开始处理。 - 任务重新处理时清空完成时间。 系统会根据字段类型以及“状态、完成、进度、负责人、完成时间”等常见名称自动匹配字段。创建前请检查每个下拉框；状态类场景还需要确认“已完成、进行中、待处理”等具体选项。 如果当前表格没有所需类型的字段，场景会显示“需要选择或补充字段”。先返回表格创建对应字段，再重新打开场景即可。可选字段可以选择“不使用”。 有测试记录时，可以直接点击“安全预览并启用”；空表可以先“保存草稿”，添加记录后再预览。 ### 22.5 极速模式：创建一条字段联动规则 点击“自定义规则”后默认进入极速模式，用一句话配置： > 当「完成」变为「已勾选」时，把「状态」设为「已完成」。 极速模式适合一个字段发生变化后，修改或清空当前记录的另一个字段。勾选和单选字段会使用可读选项，不需要填写内部 ID。 编辑器会自动选择一条可能发生变化的样本记录，并显示目标字段的修改前、修改后结果。点击“测试预览”不会写入表格；点击“发布并启用”会在预览确认后才让规则开始运行。 完整操作示例：完成任务时把状态改为“已完成”。 1. 先确认表中有勾选字段“完成”和单选字段“状态”，且状态包含“已完成”。 2. 打开自动化中心，点击“自定义规则”。 3. 规则名称填写“完成后更新状态”。 4. 在“当”一侧选择“完成”，变化方式选择“变为指定值”，目标值选择“已勾选”。 5. 在“就”一侧选择“状态”，写入内容选择“固定值”，固定值选择“已完成”。 6. 在“预览记录”选择一条尚未完成的任务。 7. 点击“测试预览”，确认触发命中，且状态预计从当前值变为“已完成”。 8. 点击“发布并启用”，确认“修改表格字段”能力。 9. 回表格勾选另一条记录进行真实验证，再到“最近运行”查看结果。 极速模式只适合“字段变化 → 修改或清空当前记录的一个字段”。需要多个动作、条件、日期触发、跨表、笔记、Webhook、分支或批处理时切换“高级模式”。 ### 22.6 高级模式的完整操作顺序 以下需求需要切换到高级模式： - 新增记录、日期到期、创建子任务或仅手动运行。 - 增加“仅在以下情况执行”的条件。 - 连续执行多个动作。 - 创建记录、跨表修改、批量更新。 - 更新绑定笔记属性或正文。 - 创建 Google 日历事件或调用 Webhook。 - 使用流程分支、遍历记录或修改执行与安全设置。 高级模式按以下顺序配置： 1. **规则名称**：使用“触发条件 + 结果”的名称，例如“到期前一天通知负责人”。 2. **何时触发**：选择触发方式和触发字段。 3. **仅在以下情况执行**：按需启用条件树。 4. **执行动作**：配置第一个动作，使用“添加步骤”追加动作、分支或遍历。 5. **预览记录**：选择一条应命中或应跳过的真实记录。 6. **执行与安全设置**：确认允许的来源、级联深度、失败策略和外部重试。 7. **保存草稿**：适合还没准备好样本、权限或外部服务的情况。 8. **测试预览**：查看触发、条件路径、动作顺序、字段前后值和所需能力。 9. **发布并启用**：确认能力后生成新的运行版本。 条件中的“且”表示全部满足，“或”表示满足任意一个。动作按流程结构从上到下执行；单条规则最多 50 个动作节点，条件树最多 4 层、50 个节点。 ### 22.7 触发器详细说明 | 触发方式 | 关键设置 | 使用说明 | | --- | --- | --- | | 字段变化 | 字段、变化方式、变化前/后值 | 适合状态联动；支持任意变化、变为指定值、从指定值变为指定值、变为空、从空变为有值 | | 新增记录 | 无额外字段 | 记录正式创建后触发；适合填写默认状态、编号之外的初始业务值 | | 日期字段到期 | 日期字段、时刻、偏移、补跑策略 | 日期字段按指定 `HH:mm`；日期时间字段使用自身时刻。负偏移表示提前，正偏移表示延后 | | 创建子任务 | 父子关系字段 | 只在通过关联关系创建子任务时使用；动作与条件可读取父任务字段 | | 仅手动运行 | 无自动触发 | 适合批处理、迁移、一次性修复和带安全续批的遍历 | #### 字段变化 - “任意变化”适合记录更新时间、同步派生字段，但容易频繁触发。 - “变为指定值”是最常用的稳定选择，例如完成变为勾选、状态变为已发布。 - “从指定值变为指定值”适合严格状态机，例如只允许“审核中 → 已发布”触发。 - “变为空 / 从空变为有值”适合清理和首次填写动作。 #### 日期字段到期 - 日期字段触发时刻使用 24 小时制 `HH:mm`。 - 偏移范围为 -10080～10080 分钟，即最多提前或延后 7 天。 - Obsidian 关闭时无法准点执行。可选择“在窗口内补跑”或“跳过错过的执行”。 - 补跑窗口为 1～365 天；每条规则每轮最多处理 100 条，剩余记录在后续轮次继续。 - 需要系统在预定时刻运行时，应保持 Obsidian 打开且插件已启用。 ### 22.8 条件树与比较运算 开启“仅在以下情况执行”后，可以添加条件、并列条件和子组： - **且（AND）**：组内每个条件都满足才继续。 - **或（OR）**：组内任一条件满足就继续。 - **子组**：把一组 AND/OR 作为上级条件的一部分，最多 4 层。 支持的运算：等于、不等于、为空、不为空、大于、大于等于、小于、小于等于、包含。 示例：“任务到期且未完成，并且优先级为高或紧急”可配置为： ```text 且 ├─ 完成 等于 未勾选 └─ 或 ├─ 优先级 等于 高 └─ 优先级 等于 紧急 ``` 条件值按字段类型解析。单选和勾选字段直接使用界面选项；“为空 / 不为空”不需要填写比较值。创建子任务触发器还可以选择父任务字段，其他触发器不能读取父任务条件。 预览时同时准备一条“应命中”和一条“应跳过”的记录，分别测试，能显著减少条件方向写反的问题。 ### 22.9 动作类型与适用场景 | 动作 | 作用 | 关键限制 | | --- | --- | --- | | 修改当前记录 | 写入或清空触发记录字段 | 只写可编辑字段 | | 修改指定记录 | 修改当前表或另一张表中的一条固定记录 | 目标记录在规则中固定 | | 批量更新记录 | 在目标表按条件查找并修改一个字段 | 每次最多 1～500 条，超出只计入预览 | | 新增记录 | 在当前表或另一张表创建记录 | 可配置多个字段映射；需要记录创建能力 | | 更新笔记属性 | 写入绑定笔记 frontmatter | 没有绑定笔记时失败或跳过，取决于计划校验 | | 更新笔记正文 | 更新本规则维护的 Markdown 标记块 | 不覆盖标记块之外的手写正文 | | 创建日历事件 | 在已连接 Google 账号的主日历创建事件 | 不邀请参与者、不创建循环事件、不自动删除远端事件 | | 调用 Webhook | 向 HTTPS 接口发送固定 JSON | 固定 POST；超时或结果不确定时不自动重发 | | 条件分支 | 分别配置满足路径和否则路径 | 预览确定路径后，正式执行不会在中途重新判断 | | 遍历记录 | 筛选当前表记录并逐条执行遍历体 | 每次最多选取 1～100 条；遍历体只允许修改当前迭代记录 | | 发送完成通知 | 主流程结束时显示 Obsidian 通知 | 只能放在主流程；可引用前面动作输出 | “修改指定记录”和“批量更新记录”不是同一种能力：前者目标 ID 固定，后者每次按条件重新查找。需要处理动态的一组记录时选择批量更新或遍历。 ### 22.10 写入内容、字段映射和动作结果 字段写入支持： - **固定值**：按目标字段类型填写或选择。 - **当前时间**：写入日期、日期时间、文本或长文本字段。 - **主流程中的字段值**：读取前面动作已经确定的计划结果。 - **触发记录的字段**：读取本次事件开始时的固定快照。 - **父任务的字段**：仅创建子任务触发器可用。 - **触发后的新值**：字段变化或日期到期触发器可用。 - **清空字段**：明确删除目标值；不要用空白固定值代替。 来源字段和目标字段必须兼容。选项字段只能安全映射回相同选项语义；创建记录的多个字段映射中，同一目标字段只能出现一次。 完成通知可引用主流程中前面动作的固定输出，例如新记录 ID、批量匹配数、实际变更数、Google 事件 ID 或计划写入值。分支内部输出只能在对应分支路径内使用。 ### 22.11 多动作、条件分支与流程顺序 在“流程结构”中使用“添加步骤”，新动作插入当前节点之后。可以上移、下移、删除或进入分支路径继续编辑。 配置条件分支： 1. 点击“添加步骤 → 条件分支”。 2. 点击该节点的“编辑条件”，建立分支条件树。 3. 点击“满足路径”添加命中时动作。 4. 点击“否则路径”添加未命中时动作；留空表示安全跳过。 5. 返回主流程，在分支后继续添加公共动作或完成通知。 正式执行时，分支条件基于预览/计划阶段的固定快照决定，不会因为分支中前一个动作改变字段而中途换到另一条路径。这保证预览和真实执行使用同一计划。 对外部副作用建议放在本地校验和本地字段更新之后，但要理解：Webhook 或日历一旦成功，后续失败不能自动撤回已经发生的外部副作用。 ### 22.12 遍历记录、批量更新与安全续批 #### 批量更新记录 适合“找到所有符合条件的记录，把同一个字段改成同一个值”。配置目标表、查找字段、条件、查找值、目标字段和最多处理数。上限 500 条；超出部分只在预览显示总匹配数，不会写入。 #### 遍历记录 适合“为每条匹配记录分别计算或执行动作”。配置： 1. “添加步骤 → 遍历记录”。 2. 设置最多选取记录数，范围 1～100。 3. 设置筛选条件；可选排序字段和升降序，空值总在末尾。 4. 点击“遍历体”，添加“修改当前迭代记录字段”。 遍历体限制写当前迭代记录，避免在嵌套流程中发生不可控的跨表副作用。 #### 安全续批 只有“仅手动运行”规则可以开启安全续批。它按已处理记录 ID 保存进度： - 成功后推进游标。 - 失败不推进。 - 本地动作补偿成功时回滚相应进度。 - 全部完成后不会自动从头再跑，必须在规则卡片显式重置续批游标。 不开安全续批时可以使用“跳过前几条匹配记录”，但若遍历动作会改变筛选或排序字段，不要通过递增偏移续批，否则记录顺序变化可能造成跳过或重复。 ### 22.13 Webhook 全流程 #### 创建安全凭证 1. 在动作类型选择“外部服务 · 调用 Webhook”。 2. 在“认证凭证”旁点击“管理凭证”。 3. 填写仅用于本机识别的凭证名称，选择： - Bearer Token：通过 `Authorization` 发送。 - API Key：固定通过 `X-API-Key` 发送。 - HMAC-SHA256：对 URL、时间戳、幂等键和完整 JSON 使用固定 v1 方案签名。 4. 输入密钥并保存。密钥正文存入 Obsidian `SecretStorage`，不会写入规则、插件设置或运行日志。 已被规则引用的凭证不能直接更改认证类型；要换类型请新建凭证并更新规则。删除仍被规则引用的凭证会被拒绝。 #### 配置请求 1. URL 只能使用 HTTPS；本机 `localhost`、`127.0.0.1`、`::1` 可以使用 HTTP。URL 不能嵌入账号或密码。 2. 方法固定为 `POST`，内容类型固定为 `application/json`。 3. 载荷可选“仅触发事件”“当前记录快照”“事件 + 当前记录”。记录快照包含当前主流程前序动作的计划投影；载荷超过 256 KiB 时拒绝执行。 4. 超时设置为 5～60 秒。 5. 系统自动发送稳定的 `Idempotency-Key`、事件 ID 和执行 ID；接收端仍应实现幂等处理。 #### 把成功响应写回字段 可添加最多 5 个“成功响应字段映射”： 1. 填写 JSON Pointer，例如 `/data/id`；空路径表示整个 JSON 响应。 2. 选择文本/长文本、数字或勾选目标字段。 3. 返回值必须是有效 JSON，且值类型严格匹配；不会在字符串、数字、布尔之间隐式转换。 4. 每个目标字段只能映射一次，文本响应单值最长 4096 字符。 5. 带响应映射的 Webhook 必须是当前路径最后一个非通知动作。 不要把接收端返回的访问令牌映射进表格。 #### 预览与失败处理 安全预览只显示 URL、载荷类型、JSON 大小、认证是否可用和响应映射，不发送请求、不显示密钥。请求发出后若超时、崩溃或返回非 2xx，系统不能安全确认远端是否处理，因此进入“需处理”，不会自动重发 Webhook。 ### 22.14 笔记与 Google 日历动作 #### 更新绑定笔记属性 - 填写 frontmatter 属性名和写入内容。 - 选择“清空字段”时会删除该属性。 - 先确保预览记录已有 `notePath` 绑定，并备份重要笔记。 #### 更新绑定笔记正文 - 设置“区块标题”和“区块内容”。 - 插件只维护带本规则标记的自动化区块，不覆盖区块外的人工正文。 - 多条规则不要复用相同用途的区块标题；规则 ID 仍会用于区分标记。 #### 创建 Google 日历事件 1. 先在插件设置连接 Google 账户。 2. 选择标题字段、开始字段；可选结束字段、说明字段和地点字段。 3. 日期字段创建全天事件；日期时间字段创建定时事件。结束为空时使用 1～1440 分钟的默认时长。 4. 预览不访问网络。真实执行使用稳定 Google Event ID；恢复时先按 ID 查询，确认不存在才安全重试。 当前动作固定写入 Google 主日历，不邀请参与者、不发送邮件、不创建循环事件，也不会在规则撤销时自动删除远端日程。 ### 22.15 草稿、预览、发布与停用 - 草稿：规则尚未运行，可以继续编辑。 - 已启用：满足触发条件后会自动执行。 - 已启用且有草稿：旧版本继续运行，新的修改尚未发布。 - 安全预览：显示是否命中、预计动作和字段前后值，不写数据，也不发送 Webhook 或创建日历事件。 修改已启用规则时，编辑器会自动保存草稿，但不会静默替换正在运行的版本。必须再次预览并发布，修改才会生效。 推荐发布流程： 1. 保存草稿。 2. 用“应命中”记录测试预览，检查每个动作的 before/after 和目标表。 3. 换“应跳过”记录预览，检查跳过原因。 4. 核对外部 URL、目标日历、目标笔记和跨表路径。 5. 点击“发布并启用”，逐项确认所需能力。 6. 用一条非关键真实记录触发。 7. 在最近运行查看详情，确认后再批量使用。 停用规则不会删除规则或历史；重新启用前仍会要求使用真实记录预览。规则有未发布草稿时，开关控制的仍是旧运行版本。 ### 22.16 执行来源、级联与循环保护 “执行与安全设置”决定哪些变更来源可以触发规则： - **响应用户编辑**：默认开启；表格、看板、表单和命令产生的人工提交。 - **响应其他自动化**：允许规则级联，仍受同链去重、最大深度和依赖图循环保护。 - **响应外部同步**：Google、Microsoft、Frontmatter 等同步写入可能一次改变多条记录。 - **响应批量导入**：CSV/TSV 等导入提交。 - **响应系统变更**：撤销、重做和内部维护提交，只在明确需要时开启。 - **响应定时调度**：日期到期规则必需，不能关闭。 - **手动运行**：始终可用。 默认只响应用户编辑和手动运行。不要一次打开所有来源；先明确规则是否应该被同步、导入或其他规则触发。 循环保护设置： - “每条规则只执行一次（推荐）”：同一触发链、同一目标记录不重复执行同一规则。 - “允许重复执行”：只有明确需要同一规则在同链中再次处理同一记录时使用。 - 最大级联深度范围 1～32，默认 8；超过后停止并写入历史。 - 自动化中心的“高级诊断 · 规则关联”显示可能的上下游关系和潜在循环。只有相关规则都启用且允许相应来源时才会实际级联。 ### 22.17 动作失败、补偿与外部重试 “动作失败时”有两种策略： - **补偿已完成动作并停止（推荐）**：尝试恢复仍保持自动化写入值的本地动作。 - **保留已完成动作并停止**：不回滚前面成功动作，适合必须保留处理痕迹的流程。 补偿采用比较后恢复：如果自动化写入后用户又手工改了同一字段，系统不会覆盖这次人工修改，而会把执行留给人工处理。已经发生的 Webhook、日历事件等外部副作用不能自动撤销。 “外部服务自动重试”目前只适用于能够确认尚未创建的 Google 日历事件： - 最大尝试次数 1～8，包含第一次。 - 首次延迟 5～3600 秒。 - 最大退避不超过 86400 秒，后续使用带稳定抖动的指数退避。 - Webhook 结果不确定时永不自动重发。 ### 22.18 运行历史与人工处理 自动化中心会按规则汇总最近运行。打开详情可以查看每个动作是否完成；仍保持自动化写入值的本地动作可以使用“撤销本次执行”。 常见状态： | 状态 | 含义 | 建议操作 | | --- | --- | --- | | 成功 | 所有计划动作完成 | 抽查结果即可 | | 跳过 | 触发或条件未命中，或没有实际变化 | 打开详情查看跳过原因 | | 已终止 | 策略或校验阻止继续 | 修正规则后重新预览 | | 已补偿 | 失败后已恢复可安全恢复的本地动作 | 核对外部副作用 | | 等待重试 | 可证明安全的外部动作等待重试 | 可“立即重试”或“停止重试” | | 已停止重试 | 达到上限或人工停止 | 打开详情核对后重新设计或运行 | | 需处理 | 无法确认外部结果或补偿发生冲突 | 使用“人工处理”，不要直接重复触发 | | 已人工处理 | 用户已记录处理决定 | 保留为审计记录 | “需处理”提供三种决定： - **确认远端已处理**：保留当前本地状态，关闭待处理项，不再次调用远端。 - **确认远端未处理并补偿**：在资源锁内补偿仍保持自动化写入值的本地动作；遇到后续人工修改会停止。 - **接受当前状态**：不改写数据，只记录用户接受当前结果。 处理备注建议记录远端对象 ID、工单号或核对时间，不要粘贴密钥。所有决定会写入运行历史。 ### 22.19 三个常用高级规则示例 #### 示例 A：到期前一天提醒高优先级未完成任务 1. 触发：日期字段到期，选择“截止日期”，偏移 `-1440` 分钟。 2. 条件：且组——“完成 = 未勾选”“优先级 = 高”。 3. 动作：发送完成通知，例如“高优先级任务将在明天到期”。 4. 执行策略：保持响应定时调度；补跑窗口根据团队假期设置 3～7 天。 5. 用截止日期为明天的样本记录预览。 #### 示例 B：状态变为已发布后更新绑定笔记 1. 触发：“状态”从任意值变为“已发布”。 2. 准备：选择一条已经绑定笔记的记录用于预览和首次验证。 3. 动作 1：更新笔记属性 `status` 为固定值 `published`。 4. 动作 2：更新笔记正文的“自动化发布信息”区块，写入发布说明。 5. 动作 3：发送完成通知。 6. 预览时确认目标笔记路径和自动化标记块，不要用重要笔记做第一次真实测试。 #### 示例 C：手动分批清理历史数据 1. 触发：仅手动运行。 2. 添加“遍历记录”，筛选“归档 = 未勾选且更新时间早于阈值”。 3. 最多选取 50 条，按更新时间升序，开启安全续批。 4. 遍历体：把“归档”设为已勾选。 5. 发布后每次手动运行一批；失败修复后重跑不会重复处理已成功记录。 6. 全部完成并核对后，使用规则卡片重置续批游标，或停用规则。 ### 22.20 规则不运行时的排错顺序 1. **看规则状态**：是“已启用”、 “草稿”还是“已启用 · 有草稿”？新修改是否已发布。 2. **看字段引用**：规则卡片是否显示缺失字段警告。 3. **看触发来源**：变化来自用户、同步、导入、系统还是其他自动化；对应来源是否允许。 4. **看触发细节**：变化方式、前值、后值是否与实际提交一致；把值写回相同值不会产生变化事件。 5. **看条件**：用真实记录预览，查看哪一个条件节点未命中。 6. **看样本**：预览记录是否具备绑定笔记、日期、父任务或目标字段。 7. **看目标资源**：跨表文件、Google 账号、Webhook 凭证是否可用。 8. **看最近运行**：打开详情区分“跳过、失败、需处理、等待重试”。 9. **看高级诊断**：是否存在循环、最大级联深度或同链去重阻止执行。 10. **日期规则确认 Obsidian 在线**：关闭期间只能按补跑策略处理。 常见错误： - **规则启用后没有反应**：正在运行的是旧版本，编辑内容仍在草稿；重新预览并发布。 - **预览显示未变化**：目标字段当前已经是目标值，或动作把字段写回自身。 - **外部同步后不触发**：默认不响应 `sync` 来源；只在确有需要并评估批量级联后开启。 - **Webhook 一直“需处理”**：网络请求已经发出但结果无法确认；先查接收端日志和幂等键，不要直接重跑。 - **笔记动作失败**：记录没有绑定笔记、笔记已移动，或属性名/正文标记配置无效。 - **跨表目标不显示**：目标表只读、未加载，或保管库存在相同表 ID 的副本。 - **安全续批不能开启**：触发方式不是“仅手动运行”。 - **日期规则错过**：Obsidian 当时关闭，且设置为跳过或已超出补跑窗口。 ### 22.21 规则设计最佳实践 - 一条规则只表达一个清晰业务目的；用具体名称描述触发和结果。 - 优先使用“变为指定值”，少用高频“任意变化”。 - 先限制触发来源，再考虑开启自动化级联；不要默认响应同步、导入和系统变更。 - 多动作流程先做本地、可补偿动作，再做外部副作用，并在最后发送通知。 - Webhook 接收端必须按 `Idempotency-Key` 幂等；密钥只放 SecretStorage，不放 URL、字段或通知。 - 批量更新先用较小上限验证；长期批处理使用“仅手动运行 + 遍历 + 安全续批”。 - 修改已启用规则后，保留旧运行版本直到新草稿完成正反两组预览。 - 定期查看“需要处理”“等待安全重试”“已停止重试”和高级诊断，不把异常长期积压。 - 删除字段、复制表文件或移动跨表目标前，先在自动化中心查看依赖影响。 - 对重要表保留自动备份；规则执行历史不是业务数据备份。 ## 23. Bases 兼容模式 ### 23.1 使用前提 需要启用 Obsidian 核心插件 Bases。 ### 23.2 使用方式 1. 新建或打开 `.base` 文件。 2. 在 Base 的视图布局中选择“多维表格”。 3. 插件会用 `duowei-grid` 自定义视图显示匹配到的 Markdown/frontmatter 数据。 ### 23.3 能力边界 Bases 兼容模式的底层数据仍是 Markdown 文件和 frontmatter，不是 `.duowei` 文件。 适合： - 查看和编辑已有 Bases 数据。 - 验证表格交互。 - 迁移到独立 `.duowei`。 如果你想使用完整的字段系统、记录详情、视图、公式、关联、表单、仪表盘、备份和冲突恢复，建议迁移到独立 `.duowei` 模式。 ## 24. 备份、冲突恢复和操作日志 ### 24.1 自动保存 `.duowei` 视图继承 Obsidian 文本文件视图能力。编辑后插件会自动保存，并在启用设置时显示保存状态。 ### 24.2 自动备份 启用自动备份后，插件在覆盖旧版本前会保留快照。你可以在“备份恢复”面板中查看、对比、打开或恢复备份。 自动备份按设置保留固定数量，超过后清理旧自动备份。 ### 24.3 冲突检测 如果你正在编辑 `.duowei` 文件，同时外部又修改了同一个文件，插件保存前会检测到磁盘版本与上次持久化版本不一致。 发生冲突时： - 插件不会静默覆盖原文件。 - 插件会生成冲突备份。 - 保存状态会提示外部修改或冲突。 - 可打开“冲突恢复”面板处理。 ### 24.4 冲突恢复 冲突恢复面板支持： - 查看原文件与当前编辑内容差异摘要。 - 打开冲突备份。 - 保留磁盘版本。 - 使用备份版本。 - 在冲突数量不太大时逐单元格合并。 逐单元格合并会按记录和字段列出差异，让你选择保留原文件值或当前编辑值。冲突项过多时会退化为摘要展示。 ### 24.5 操作日志 操作日志记录最近的关键操作，包括： - 编辑 - 撤销 - 重做 - 同步 - 冲突 - 导入 - 导出 - 系统事件 如果启用持久化，操作日志会保存在插件数据中，不写入 `.duowei` 表格文件。 ## 25. 移动端使用 插件按手机、平板、桌面三种布局分别适配： - 手机（宽度 640px 以内或 Obsidian 判定为手机）：筛选、字段、下拉、日期等面板变成底部抽屉，触摸目标更大；默认隐藏 Obsidian 底部导航栏，只保留表格操作栏（可在设置中关闭）。 - 平板（iPad 等，或宽度不超过 1100px）：保留桌面端的信息密度和工具栏，但触摸热区、浮层和拖拽按触屏处理；编辑抽屉收成对齐来源单元格的有界卡片，不铺满整屏。接上触控板或妙控键盘后，悬停预览、选中即打字、拖拽填充等桌面能力会实时恢复。 - 触摸拖动优先用于滚动：长按（约 0.3 秒）达成前的任何位移都视为滚动，不会误触拖拽。 - 长按单元格打开与桌面右键完全相同的菜单（插入行、复制、粘贴、清空、样式等）。 - 长按列头后移动可调整列顺序，长按行号后移动可调整记录顺序或子任务层级；长按原地松手则打开对应菜单。 - 看板卡片长按可移动到其他分组；日历、时间轴中的日程卡片、时间条和“未排期”记录长按后可拖到目标日期或时段。 - 图片灯箱在未放大时可横向滑动切换上一张 / 下一张，底部的来源说明常驻显示。 ### 25.1 手机端编辑单元格 触屏没有可靠的双击，手机端改为**点两下**：第一下选中单元格，再点一下已选中的单元格进入编辑。从已选中的单元格起手滑动不会触发编辑，仍然是滚动。 手机端不在单元格内就地编辑，而是从屏幕底部升起**编辑抽屉**： - 抽屉顶部显示字段名，中间是输入框，底部是“取消”和“保存”。 - 点“保存”或点抽屉外部的遮罩都会写入，点“取消”不写入。 - 多行文本字段在抽屉里回车换行，需要点“保存”提交；单行字段回车即保存。 - 日期和日期时间字段直接弹出日历抽屉点选，不弹软键盘。 - 附件和笔记链接字段的抽屉里有“选择文件”按钮。 - 勾选框点一下直接切换，单选/多选/关联字段各自弹出对应的选择抽屉。 之所以用抽屉而不是在单元格里就地编辑：手机软键盘弹出时会把 Obsidian 的视口压缩到键盘上方，表格网格随之塌缩成一条窄缝，行内输入框会被一起挤没。抽屉是固定定位的浮层，不参与网格高度计算，始终贴在键盘上方。 平板（iPad 等）同样使用编辑抽屉，但抽屉是宽度有限、横向对齐来源单元格的卡片，而不是铺满整屏；接了触控板或妙控键盘、不会弹出软键盘时，表格不再预先冻结，只有软键盘真的出现才补做适配。 移动端适合查看、轻量编辑、快速录入；大量字段配置和批量编辑仍建议在桌面端完成。 ## 26. 键盘快捷键 “更多操作 → 键盘快捷键”会打开一个可停留、可滚动的面板，按“移动与选择 / 编辑 / 剪贴板与历史”分组列出下表内容，便于对照操作。 表格视图支持以下快捷键： | 快捷键 | 作用 | | --- | --- | | Enter | 编辑当前单元格，或提交后下移 | | F2 | 编辑当前单元格 | | Tab | 移到右侧单元格 | | Shift + Tab | 移到左侧单元格 | | 方向键 | 移动当前单元格 | | Shift + 方向键 | 扩展选区 | | Ctrl/Cmd + 方向键 | 跳转到数据边界 | | Home / End | 跳到行首 / 行尾 | | Ctrl/Cmd + Home / End | 跳到表格开头 / 末尾 | | Ctrl/Cmd + A | 全选 | | Ctrl/Cmd + C | 复制 | | Ctrl/Cmd + V | 粘贴 | | Delete / Backspace | 清空选区 | | Ctrl/Cmd + D | 向下填充 | | Shift + Enter | 在当前行下方新增行 | | Ctrl/Cmd + H | 查找替换 | | Ctrl/Cmd + Z | 撤销 | | Ctrl/Cmd + Shift + Z | 重做 | | Ctrl/Cmd + Y | 重做 | | 空格 | 勾选当前勾选字段，或进入当前格编辑 | | Esc | 收起选区、取消编辑或关闭面板 | 在多行文本编辑中，Shift + Enter 可换行；普通 Enter 会提交编辑。 “更多操作 → 键盘快捷键”会打开可滚动的分组面板，便于随时查看完整快捷键。向上填充没有单独的键盘快捷键，请使用选区右键菜单或拖拽左上角填充手柄。 ## 27. 推荐工作流 ### 27.1 项目管理表 推荐字段： - 标题：文本 - 状态：单选，待处理 / 进行中 / 已完成 / 暂停 - 优先级：单选，高 / 中 / 低 - 截止日期：日期 - 负责人：文本或单选 - 进度：进度 - 相关笔记：笔记链接 - 附件：附件 - 复盘：长文本 推荐视图： - 表格：总览和批量编辑。 - 看板：按状态分组。 - 日历：按截止日期查看。 - 仪表盘：统计任务数量和完成情况。 ### 27.2 内容运营表 推荐字段： - 标题：文本 - 平台：单选，小红书 / 公众号 / B站 / 抖音 - 状态：单选，选题 / 脚本 / 制作 / 已发布 / 复盘 - 发布时间：日期时间 - 封面：附件 - 正文/脚本：长文本 - 发布链接：链接 - 数据指标：数字字段，如浏览、点赞、收藏、评论 - 标签：多选 推荐视图： - 看板：按状态推进。 - 日历：看发布排期。 - 画廊：看封面和素材。 - 仪表盘：按平台统计内容数量。 ### 27.3 资料阅读表 推荐字段： - 标题：文本 - 类型：单选，书籍 / 论文 / 网页 / 视频 - 状态：单选，待读 / 在读 / 已读 / 暂停 - 评分：评分 - 链接：链接 - 附件：附件 - 阅读日期：日期 - 摘要：长文本 - 笔记：笔记链接 推荐视图： - 表格：资料总索引。 - 画廊：书封或截图展示。 - 看板：按阅读状态分组。 - 仪表盘：按类型或状态统计。 ### 27.4 文件素材库 推荐做法： 1. 执行“从文件夹创建多维表格”。 2. 选择“实时只读索引”。 3. 文件范围选择“图片”或“全部文件”。 4. 切到画廊视图。 5. 用文件夹、类型、创建时间筛选素材。 这种方式不复制文件，只把库内文件实时物化进表。 ## 28. 常见问题 ### 28.1 `.duowei` 文件可以直接编辑吗？ 可以用文本方式打开，但不建议手动改。`.duowei` 是 JSON 文件，手动改错可能导致表格需要修复或丢失部分配置。 ### 28.2 表格记录必须对应 Markdown 笔记吗？ 不需要。普通记录可以只存在于 `.duowei` 文件中。绑定 Markdown 是可选能力。 ### 28.3 能否双向同步 frontmatter？ 普通绑定记录支持写入 frontmatter；打开中的表格也支持从绑定笔记的 frontmatter 变化反向同步回来。字段需要设置同步键。 ### 28.4 为什么库数据源表格不能像普通表一样随便改？ 库数据源表格的记录来自真实文件树和 metadataCache，不落盘保存。它更像 Obsidian Bases 的查询视图，用于索引和查看。需要改内容时，应编辑原笔记或原文件。 ### 28.5 支持合并单元格吗？ 不支持。插件采用“一行一条记录、一列一个字段”的数据库模型。合并单元格会破坏排序、筛选、分组、虚拟滚动和记录字段对应关系。 ### 28.6 支持多人实时协作吗？ 不支持实时协作。插件是本地 Obsidian 插件。通过同步盘同步时，如果同一文件被多端同时修改，插件会尽量检测冲突并生成冲突备份。 ### 28.7 大表性能如何？ 表格视图使用行列虚拟化；看板、画廊有分页渲染；公式、关联、查找、汇总也做了缓存、索引和依赖范围分析。 - 普通单元格变化时，只重算受影响的计算字段和记录。 - 同一次刷新中，相同的中间公式和整列聚合会复用计算结果。 - 跨表目标文件变化时，为保证结果正确，当前会对引用该文件的本地计算结果做一次保守刷新。 数据量增长后，计算链路不会因为多个下游公式反复引用同一中间结果而成倍重复求值。不过仍建议按业务边界拆成多张表，避免把所有数据和大量跨表关系集中到单一超大表。 ### 28.8 `.base` 和 `.duowei` 应该选哪个？ 新建数据建议选 `.duowei`。如果你已经依赖 Bases 查询 Markdown/frontmatter，可以继续使用 `.base` 兼容视图，或迁移到 `.duowei` 后获得完整表格能力。 ### 28.9 是否支持图片封面？ 支持。画廊视图可用附件、URL、笔记链接等字段作为封面。库数据源选择图片范围时，画廊可直接展示库内图片。 ### 28.10 操作日志会污染表格文件吗？ 不会。操作日志保存在插件数据中，不写入 `.duowei` 文件。 ### 28.11 手机上点单元格没反应，或编辑框一闪而过？ 请更新到最新版本。手机端编辑单元格的方式是：先点一下选中，再点一下已选中的单元格，从屏幕底部升起编辑抽屉。详见“移动端使用”一节。 如果仍然一闪而过，通常是插件文件没有完整替换。请确认 `main.js` 和 `styles.css` 都已更新，然后在 Obsidian 中重新加载插件（关闭再启用，或重启应用）。 ### 28.12 公式架构升级会修改原有数据吗？ 不会修改文本、数字、日期、关联记录等原始输入字段，也不要求迁移现有 `.duowei` 文件。旧公式仍可继续使用。 公式、查找和汇总属于派生结果。表格刷新时，这些字段保存的计算结果可能被重新生成；以前以展示字符串保存的数字型查找结果可能更新为真实数字类型，以便继续参与计算。这属于派生缓存修正，不会改写其来源字段或关联目标记录。 建议像其他版本升级一样保留自动备份。若表格存在大量历史公式，可先复制一份 `.duowei` 文件验证显示结果，再正式使用。 ### 28.13 如何让跨表查找结果继续计算？ 先创建关联字段，再创建查找字段读取目标表的数字或公式字段，最后在当前表公式中使用多值函数。例如： ```text sumitems([查找含税价]) * [数量] ``` 计算结果还可以继续被另一个公式引用： ```text [小计] + [运费] ``` 如果关联字段只允许选一条记录，可以使用 `first([查找含税价])` 明确取第一项。