heptabase-cli

前置条件

• 从桌面应用安装 CLI。macOS/Linux 上的命令是 heptabase；Windows 会为 cmd/PowerShell 安装 heptabase.cmd，并为 POSIX shell 安装 heptabase shim。
• 使用前，通过 heptabase --version 检查版本兼容性。如果已安装的 CLI 版本不在此技能的兼容范围（0.8.x）内，你必须停止操作，并请用户更新 Heptabase 桌面应用或此技能包，然后再继续。

命令发现

运行 heptabase help 查看所有可用的顶层命令。该信息始终是最新的。每个命令都支持 --help，以查看详细用法：

heptabase help
heptabase note --help
heptabase note create --help

常用操作示例

以下是常见请求的快捷操作示例。对于不常用的标志，或命令执行失败时，请运行 heptabase help 或 <command> --help，以查看正确语法。

• 最近的卡片： heptabase card list --sort createdTime --direction descending --limit 20
• 今天的日志： heptabase journal read $(date +%Y-%m-%d)
• 按关键词搜索卡片： heptabase card list -q "<keyword>" --limit 20
• 从 Markdown 创建笔记： heptabase note create --content "# Title\n\nBody"（默认标记为由 AI 创建；对于人工创建的内容，添加 --no-created-by-ai）。
• 从 Markdown 创建今天的日志： heptabase journal create --content "Body"（默认标记为由 AI 创建；对于人工创建的内容，添加 --no-created-by-ai）。
• 将 Markdown 追加到笔记： heptabase note append <cardId> --content "More content"。
• 使用 JSON 保存笔记内容： 首先阅读 references/card-content-schema.md，然后使用 heptabase note read <cardId>，修改返回的 ProseMirror JSON，并使用 heptabase note save <cardId> --content-md5 <contentMd5> --content-file <path> 保存。
• 处理属性： 使用 heptabase tag cards <tagId> --include-properties 列出带有值的已标记卡片，或使用 heptabase card properties <cardIdOrDate> 查看单张卡片。写入前，请阅读 references/property-values.md，使用 heptabase tag properties <tagId> 查看定义，然后对于字符串或选项使用 heptabase card set-property <cardIdOrDate> --property-id <propertyId> --value "Published"，对于类型化的 JSON 值使用 --json-value ...。
• 读取已解析的 PDF 内容： 首先阅读 references/pdf-reading.md，然后使用 heptabase pdf metadata <pdfCardId> 获取 totalPages，并使用 heptabase pdf read <pdfCardId> --start-page N --end-page N 读取指定页面范围。
• 读取转录内容： 首先阅读 references/transcript-reading.md，然后使用 heptabase audio metadata <audioCardId> 或 heptabase video metadata <videoCardId> 获取 transcriptStatus 和 durationSeconds，再使用 heptabase audio read <audioCardId> --start-seconds 0 --end-seconds 300 或 heptabase video read <videoCardId> --start-seconds 0 --end-seconds 300 读取指定时间范围内有重叠的转录条目。
• 读取附件： 首先阅读 references/file-reading.md。如有需要，使用 heptabase file list --card-id <cardId> 查找其 ID，然后运行 mktemp -d 和 heptabase file export <fileId> --output-dir <scratchDir>。使用原生文件读取工具读取返回的 path。
• 向笔记添加本地图片： 首先阅读 references/image-import.md，然后运行 heptabase file import <path>，并通过 note read 和 note save 添加 image 节点：设置 fileId，并将 originalWidth 和 originalHeight 设为返回的 width 和 height。
• 检查白板： heptabase whiteboard read <whiteboardId> --mode structure，然后运行 heptabase whiteboard read-layout <whiteboardId>。
• 读取聊天消息： 从 whiteboard read 的输出中复制聊天 ID，然后使用 heptabase object read chat <chatId> --offset <n> --limit <n> 分页读取未移除的消息及其显示的作者、时间戳、引用内容和消息内容。对于白板聊天消息元素，使用 heptabase object read chatMessagesElement <elementId> --offset <n> --limit <n>。
• 检查或查看白板布局： 运行 heptabase whiteboard lint <whiteboardId>。如需进行视觉检查，请先阅读 references/whiteboard.md，然后使用 heptabase whiteboard screenshot <whiteboardId> --output <existingDirectory>/whiteboard.png，并检查返回的本地路径。
• 更改白板布局或思维导图： 首先阅读 references/whiteboard.md；对于思维导图，还要阅读 references/mind-maps.md。使用嵌套或批量输入的命令需通过 --input <path|-> 提供规范 JSON。

Heptabase URL（深层链接）

当用户分享 Heptabase URL（即深层链接）时，请使用 CLI 读取；除非用户明确要求，否则不要在浏览器中打开（该应用需要身份验证，而 Agent 使用的浏览器通常未登录）。

URL 模式及处理方式：

• 日志卡片： https://app.heptabase.com/<workspaceId>/card/<YYYY-MM-DD> → heptabase journal read <YYYY-MM-DD>
• 按 UUID 查找卡片： https://app.heptabase.com/<workspaceId>/card/<uuid> → 先运行 heptabase card properties <uuid> 以确定卡片类型，然后使用相应命令读取其内容（heptabase note read <uuid>、heptabase pdf metadata <uuid> 等）。
• 白板： https://app.heptabase.com/<workspaceId>/whiteboard/<uuid> → 运行 heptabase whiteboard read <uuid> --mode structure 和 heptabase whiteboard read-layout <uuid>。进行任何布局更改或视觉判断之前，请先阅读 references/whiteboard.md。

URL 中的 <workspaceId> 部分无需用于 CLI — 只提取卡片或白板 ID。

笔记和日志卡片内容编辑

普通写作请使用 create / append，并采用 Markdown。使用 ProseMirror JSON 调用 heptabase note save / heptabase journal save 之前，必须先阅读 references/card-content-schema.md。生成使用 Heptabase 专用扩展的 Markdown（例如卡片提及、白板提及、日期、视频、数学公式或折叠/待办列表）之前，也必须阅读该文件。

AI 创建标记

note create 和 journal create 默认会将内容标记为由 AI 创建。在决定是否传入 --no-created-by-ai 之前，必须先阅读 references/created-by-ai.md。

属性编辑

设置属性值之前，必须先阅读 references/property-values.md，并使用 heptabase card properties <cardIdOrDate> 和/或 heptabase tag properties <tagId> 检查目标属性。属性格式因类型而异，关系写入会替换整个关系值。对于关系属性，请使用 heptabase tag properties <sourceTagId> 获取属性定义中的 relationTargetTagId，然后在写入前列出有效的关联卡片。

文件读取

读取或列出文件，或导出文件之前，必须先阅读 references/file-reading.md。

图片导入

导入图片或将图片添加到笔记之前，必须先阅读 references/image-import.md。

PDF 读取

读取已解析的 PDF 内容之前，必须先阅读 references/pdf-reading.md。

转录内容读取

读取已解析的媒体转录内容之前，必须先阅读 references/transcript-reading.md。

白板操作

进行有意放置、移动、排列、调整大小、分区、连接、移除或视觉验证之前，必须先阅读 references/whiteboard.md。该文件定义了精确的放置参照、选择和目标形状、先读后写规则以及验证流程。

创建思维导图或进行结构性编辑时，还必须阅读 references/mind-maps.md。更新现有思维导图之前，请重新读取该导图，以确保结构节点 ID 是最新的。

现有的 whiteboard cards、add-card 和 remove-card 命令是用途有限的旧版命令。对于结构化白板操作，请优先使用 whiteboard read、read-layout 和规范的 --input 命令。

规范的修改命令涵盖白板层级和快捷方式、对象放置和跨白板移动、移动、排列、对齐、调整大小、着色和移除、分区和连接，以及思维导图的创建和更新。运行 heptabase whiteboard --help 查看当前命令列表，并阅读相关参考文档了解嵌套输入。

规范 JSON 输入

包含嵌套或批量数据的命令接受 --input <path|->；- 表示从 stdin 读取 JSON。使用 jq 构建 JSON，或将其写入临时文件。不要将不可信文本插入手动构建的 shell JSON 中。

检查每项变更操作的结果。已处理的顶层 status: "failed" 会打印出来，并以状态码 1 退出。即使条目结果中包含 failureReasonCode 字段，顶层结果成功时仍会以 0 退出，因此在报告完全成功之前，请先检查这些字段。

所有输出均为 JSON

每条命令都会将 JSON 打印到 stdout。你可以使用 jq 解析，也可以将其传递给其他工具。whiteboard screenshot 会将 PNG 写入 --output，并且只打印元数据；它不会打印图像字节。

故障排除

• 桌面应用必须正在运行。 CLI 会与应用内的本地服务器通信。如果应用已关闭，所有命令都会失败。运行 heptabase start 启动应用，并等待其就绪。
• Codex 沙箱可能会阻止本地 CLI 服务器。 如果 Heptabase 已启动，但 Codex 提示 CLI 服务器尚未就绪，请阅读 references/codex-sandbox.md；如果 Codex 支持权限提升，请在沙箱外重试 heptabase 命令。
• 变更操作会串行执行。 写入操作一次只运行一个，以防冲突。读取操作则会并发执行。
• 请求正文大小限制。 服务器会拒绝大于 1 MB 的 JSON 请求正文。file import 上传的文件最大可达 2000 MB。
• 请求超时。 对于发送正文耗时超过 10 秒的 JSON 请求，服务器会超时。

已知限制

• 不支持自动启用本地服务器或安装 CLI。 如果本地 CLI 服务器已禁用，或 CLI 配置缺失，该技能无法自行修复；请先让用户在桌面应用设置中启用 Local CLI Server 和 CLI install。
• 文件导出仅支持本地文件。 只有当文件元数据和原始文件已在桌面应用本地可用时，heptabase file export 才能正常工作。它不会从云存储下载缺失文件。
• 仅支持导入图像。 heptabase file import 可导入图像（不支持 HEIC、HEIF 或 TIFF）以供笔记使用。它无法导入 PDF、音频、视频或其他文件，不会创建卡片，也无法调用媒体处理 API。
• 白板功能范围有意受限。 CLI 无法删除白板或底层 Card、在空间之间移动内容、创建任意形状，也无法执行一个语义层面的全白板自动布局命令。remove-objects 移除的是画布上的放置项，而不是源 Card。
• 没有 CLI 撤销命令或 Agent 历史记录。 白板变更会使用应用常规的领域操作，但 CLI 不提供 Agent 聊天撤销、工具调用持久化或 Agent 截图检查清单。请先读取内容，并自行验证结果。
• 白板内容仅限本地。 白板读取使用运行中的桌面应用内可用的内容，不会执行仅限后端的 PDF、网页或 YouTube 内容补充。要获取完整源内容，请使用专用的 PDF 和媒体命令。CLI 无法获取完整的网页卡片内容；请使用白板输出中的源 URL。
• 截图仅为示意图。 它们可用于空间布局检查，但不能替代语义读取或确定性 lint。
• 目前不支持按属性筛选。 你可以读取标签属性架构、读取属性值，以及为卡片设置一个属性值，但无法按属性值查询卡片。

警告

• 只能通过 CLI 访问数据。 绝不要通过本地数据库文件、应用存储、缓存文件、内部端点或任何其他非 CLI 方式，直接读取、写入或修改 Heptabase 应用数据。如果 CLI 不支持所需操作，请停止并说明该操作不受支持。