draft-cli

Draft CLI 技能

使用 draft 执行 JSON Workspace 页面域操作和托管式 Secret Share 辅助功能。

当前运行时约定

• 默认页面目标优先使用已保存的 JSON Workspace。
• 执行页面命令前，先使用工作区元数据命令，以了解 CLI 正在使用哪个文件夹和来源。
• 在移除无头存储之前，对于必须操作 JSON Workspace 数据的页面命令，请传入解析后的工作区路径 --workspace-json <folder>。

页面命令的工作区优先模式

对于 draft page ls、draft page cat、draft page create、 draft page append、draft page replace、draft page patch、draft page annotate 和 draft page publish 等页面命令：

draft workspace status --json
draft workspace path --json

使用返回的 active_workspace_path，明确指定页面命令的目标：

draft --workspace-json <active_workspace_path> page ls --json
draft --workspace-json <active_workspace_path> page cat <page_id> --json

若要显式覆盖文件夹，请使用 --workspace-json 指定命令目标：

draft --workspace-json <folder> page ls --json
draft --workspace-json <folder> page cat <page_id> --json

如果用户希望将该文件夹设为默认工作区，请先进行设置：

draft workspace set-path <folder> --json
draft workspace status --json

在向用户说明结果前，使用工作区元数据确认 CLI 使用的是已保存的默认路径，还是显式覆盖路径。

版本检测和旧版 CLI 回退方案

较新的 CLI 可以提供如下工作区元数据命令：

draft workspace status --json
draft workspace path --json
draft workspace set-path <folder> --json

如果这些命令不可用，请检测一次并安全回退：

draft workspace --help
draft --workspace-json <folder> page ls --json

• 如果 draft workspace --help 或 draft workspace status --json 因未知命令类错误而失败，则假定 CLI 版本较旧。
• 对于旧版 CLI，必须指定文件夹，并使用 draft --workspace-json <folder> ... 运行页面命令。
• 如果用户未提供文件夹，且 CLI 不支持工作区命令，请询问 JSON Workspace 文件夹路径，或请用户升级 CLI。

页面命令

优先在 JSON Workspace 目标下使用显式的 draft page ... 命令。在过渡期间，请加入 --workspace-json <folder>，以免命令意外操作旧版无头存储：

draft --workspace-json <folder> page ls --json
draft --workspace-json <folder> page search "phrase" --json
draft --workspace-json <folder> page cat <page_id> --json
draft --workspace-json <folder> page create "Title" --json
draft --workspace-json <folder> page append <page_id> "More content" --json
draft --workspace-json <folder> page replace <page_id> --heading "Status" "Updated body" --json
draft --workspace-json <folder> page patch <page_id> --json < change.diff
draft --workspace-json <folder> page annotate <page_id> --anchor "exact text" --note "Reviewer note" --json
draft --workspace-json <folder> page comments <page_id> --json
draft --workspace-json <folder> page comment <comment_id> <page_id> --json
draft --workspace-json <folder> page insert-image <page_id> ./image.png --json
draft --workspace-json <folder> page update-image <page_id> <local_id> --width 320 --json
draft --workspace-json <folder> page delete-image <page_id> <local_id> --json
draft --workspace-json <folder> page publish <page_id> --json

面向 Agent 的读取指南

• 对于供人工审阅的页面渲染结果，优先使用 draft --workspace-json <folder> page cat <page_id>。与手动从 pages/*.json 渲染相比，Markdown 内容能更好地保留链接、标记、表格、图片、有序列表、换行和自定义块。
• 仅在需要结构化块数据以进行解析或自动化时，才使用 draft --workspace-json <folder> page cat <page_id> --json。其内容比 Markdown 读取结果更多。
• 将工作区原始 JSON 文件作为恢复或底层检查时的最后手段，而非默认读取方式。
• 查找内容时，如果 CLI 支持，优先使用 draft --workspace-json <folder> page search "phrase" --json。对于不支持页面搜索的旧版 CLI，仅使用 rg 搜索工作区页面文件，以查找候选页面 ID 或标题，然后切回 draft --workspace-json <folder> page cat <page_id>，获取权威的渲染结果。

补丁约定

draft page patch 仅将统一差异应用于页面正文 Markdown。请勿根据经过装饰、包含 Title:、ID: 或 --- 分隔线的人工可读 page cat 输出生成补丁，也不要根据 page cat --json 的块输出生成补丁。

补丁工作流：

draft --workspace-json <folder> page cat <page_id>
# Extract only the body markdown, build a unified diff against that body, then:
draft --workspace-json <folder> page patch <page_id> --json < change.diff
draft --workspace-json <folder> page cat <page_id> --json

在运行依赖编辑后文本的下游命令（例如 page annotate --anchor "new text"）前，请验证补丁输出或再次运行 page cat。如果补丁返回 PATCH_MISMATCH，请重新读取当前页面正文 Markdown，针对完全相同的正文内容重新生成差异，然后重试。

图片修改约定

draft page insert-image 会返回 local_id。后续执行 update-image 和 delete-image 命令时，请使用返回的 local_id。在 page cat --json 兼容输出中，同一标识符会作为图片块的 id 提供。

兼容期间仍可能存在顶层页面别名，但 Agent 应使用 draft page ... 命名空间。

公开预览反馈

公开 Draft 预览和已发布 URL 通过公开页面本身提供审核反馈，而不是通过 JSON Workspace 页面命令。对于公开审核工作流，应将公开预览或已发布 URL 视为主要的机器可读入口。如果任务从公开预览或已发布 URL 开始，请先获取该公开 URL，解析其元数据/frontmatter，然后按优先级使用返回的端点。

此直接读取公开页面反馈的路径不需要 draft、draft workspace status、draft status、JSON Workspace 文件夹、守护进程或浏览器配对。不要仅仅因为用户提供了公开 URL，就运行 draft --workspace-json <folder> page comments <page_id> --json。

“从此公开 Draft 预览 URL 读取反馈”的示例：

1. 获取提供的公开预览或已发布 URL。
2. 解析元数据/frontmatter，并将 comments_api_url 和 task_toggles_api_url 作为 P0 端点读取。
3. 直接获取 comments_api_url，读取人工反馈和评论。
4. 直接获取 task_toggles_api_url，读取审核切换状态和任务决策。
5. 如果存在 source_snapshot_url，则将其视为 P1 可选的结构化已发布内容快照，帮助将评论和切换项与准确的已发布正文对应起来。
6. 总结反馈和决策状态，仅在有助于消除审核中已发布内容的歧义时使用 source_snapshot_url。

读取公开审核内容的顺序：

1. 获取公开 URL。
2. 解析元数据/frontmatter。
3. 获取 comments_api_url。
4. 获取 task_toggles_api_url。
5. 可选地获取 source_snapshot_url。
6. 总结反馈和决策状态。

如果 JSON Workspace 评论命令对某个页面返回空结果，而该页面也有公开预览/已发布 URL，在检查该公开 URL 中的 comments_api_url 和 task_toggles_api_url 之前，不要断定没有反馈或决策。

CLI 评论命令（例如 draft --workspace-json <folder> page comments <page_id> --json）主要用于私有或本地 Draft 页面工作流、实时工作区页面或本地页面批注。它们不是预览或已发布 URL 的默认公开审核路径。

写入和分享安全防护

只读操作是安全的默认回退方案。除非用户明确要求执行确切操作并指定目标，否则不要运行写入/分享命令。

• 写入命令：draft --workspace-json <folder> page create、draft --workspace-json <folder> page append、draft --workspace-json <folder> page replace、draft --workspace-json <folder> page patch、draft --workspace-json <folder> page annotate
• 分享命令：draft --workspace-json <folder> page publish、draft secret create

返回公开或可分享的 URL 前，请检查命令输出，并确认它是用户要求的产物。

Secret Share

Secret Share 命令是托管式/本地加密辅助工具，不需要工作区检查、draft status 或 draft start-server。

配置 API 密钥：

draft auth set-key <secret-share-api-key>
draft auth status --json

创建 Secret Share：

draft secret create --file docs/brief.md --expires 1h --json

读取 Secret Share：

draft secret open '<secret_url_or_id>' --password "$DRAFT_SECRET_PASSWORD" --json

受密码保护的分享请使用 --password。仅当运行时已提供 DRAFT_SECRET_PASSWORD 时才使用它。

错误处理

• 未知的 draft workspace ... 命令：改用 draft --workspace-json <folder> ...，并在缺少文件夹路径时询问用户。
• 未配置工作区路径：如果用户需要默认路径，使用 draft workspace set-path <folder> --json；如果只是执行一次性命令，则使用 draft --workspace-json <folder> ...。
• PAGE_NOT_FOUND：运行 draft --workspace-json <folder> page ls --json，并使用有效的页面 ID 重试。
• PATCH_MISMATCH：使用 draft --workspace-json <folder> page cat <page_id> 重新读取，仅提取页面正文 Markdown，根据该正文的确切内容重新生成补丁，然后重试。
• ANCHOR_NOT_FOUND：添加批注前重新读取当前页面；不要为失败的补丁未创建的文本添加批注。
• 缺少 Secret Share API 密钥：使用 draft auth set-key、--api-key 或 DRAFT_SECRET_SHARE_API_KEY。