Mo Note

前置约束

CRITICAL — 先阅读 [`共享规则`](../mo-shared/SKILL.md)，其中包含 `mocli` 初始化、认证、输出解析以及安全规则

mocli note - 墨问笔记

命令选择规则

• 用户要“创建/发布/写一篇墨问笔记”时，使用 mocli note create。这是写入操作，执行前必须确认用户确实要创建笔记，尤其是带 --publish 自动发布时。
• 用户要“编辑/修改/更新已有墨问笔记正文”时，使用 mocli note edit。这是写入操作，执行前必须确认目标笔记 ID、完整替换后的正文来源、已完成覆盖风险强制门禁，以及用户确实要覆盖原笔记正文。
• 用户要“设置/修改笔记隐私/公开或私有某篇笔记/设置部分公开规则”时，使用 mocli note set。这是写入操作，执行前必须确认目标笔记 ID 和隐私设置；当前 note set 只支持隐私设置，不用于修改正文、标签或发布内容。
• 用户要“查看某篇笔记当前有哪些标签”时，使用 mocli note tag --note-id <note-id>。这是读取操作，不会修改笔记标签。
• 用户要“设置/追加/移除/覆盖某篇笔记的标签”时，使用 mocli note tag。这是写入操作，执行前必须确认目标笔记 ID 和标签操作；--reset 是覆盖全量标签，会忽略同次命令里的 --append 和 --remove。
• 用户要“查看某篇笔记详情/笔记信息/引用笔记/评论”且已经有笔记 ID 时，使用 mocli note info --show-comment --show-refer。这是读取操作；只有在编辑笔记前需要获取当前 NoteAtom 时才额外添加 --show-atom，其它场景避免使用 --show-atom。
• 用户要“搜索某关键词相关笔记”时，使用 mocli notes search。
• 用户要“看某人的主页/公开笔记/热门笔记/付费笔记/合集”时，使用 mocli notes homepage。
• 用户要“看我自己的笔记/私有笔记/未公开笔记/我写过的笔记”时，使用 mocli notes mine。
• 用户要“看某个/某些标签下的笔记、按标签筛选我的笔记”时，使用 mocli notes tagged；只支持当前认证用户自己的标签，标签名称或 ID 不明确时，先用 `mo-tag` 的 mocli tag mine 获取候选。
• 用户提到人名、昵称、备注名但没有给 UID 时，优先用 `mo-remark` 查 UID；未命中再考虑 mocli user search 或询问用户补充 UID。
• 创建/编辑笔记正文时，如果需要把本地文件或远端 URL 转成墨问文件 ID，先使用 `mo-misc` 的 mocli misc upload 获取 reply.file_id。
• 展示笔记列表时，优先按 reply.note_ids 的顺序遍历，再到 reply.notes[note_id] 获取笔记详情，并用 reply.notes[note_id].uid 到 reply.users 获取作者信息。

正文资源引用处理流程

创建和编辑笔记时，如果源内容里包含图片、音频或 PDF 资源引用，应先确认用户希望“上传到墨问并引用 file_id”，还是“保留原始 URL/路径文本”。不要在未确认时自动上传用户文件或远端 URL。

需要触发确认的场景

• HTML 中出现 <img src="..."> 时，且 src 明确指向图片文件或可判断为图片资源。
• HTML 中出现 <a href="..."> 时，且 href 明确指向图片、音频或 PDF 文件。
• Markdown 中出现本地文件引用时，例如 ![](./image.png)、[报告](./report.pdf)、[音频](../audio.wav)，且文件格式为图片、音频或 PDF。

上传与转换规则

• 用户选择上传时，按 `mo-misc` 使用 mocli misc upload 获取上传结果。本地文件使用 --file，远端 URL 使用 --url；可用原始文件名、alt 文本或链接文本作为 --filename。
• 上传结果至少读取 reply.file_id；如果存在，也读取 reply.file_type、reply.file_name、reply.file_mime、reply.file_size、reply.file_meta。file_meta 是 JSON 字符串，可能包含音频 duration、图片 width/height、PDF format 等元信息；解析失败时不要阻断正文转换，只跳过对应增强属性。
• 上传成功后，将资源转换为正文语法树资源节点：图片使用 { "type": "image", "attrs": { "uuid": "<file_id>", "alt": "<可选描述>" } }；音频使用 { "type": "audio", "attrs": { "audio-uuid": "<file_id>" } }；PDF 使用 { "type": "pdf", "attrs": { "uuid": "<file_id>" } }。
• 生成音频节点时，尽量从 reply.file_meta.duration 读取音频时长；如果存在，写入 attrs.audio-duration，属性值使用字符串形式，例如 { "type": "audio", "attrs": { "audio-uuid": "<file_id>", "audio-duration": "236.878367" } }。
• 生成 PDF 节点时，尽量补充展示信息：attrs.name 优先使用 reply.file_name，attrs.size 优先使用 reply.file_size 的字符串形式；如果 file_meta 中有更明确的 PDF 元信息，可作为辅助参考，但不要覆盖用户明确指定的文件名。
• 用户选择保留原始 URL 时，不要生成资源节点；将 URL 作为普通链接文本保留在段落中，例如 text.marks 里的 link mark。对于本地路径，提醒用户本地路径在墨问正文中通常无法被其他人访问；用户仍要求保留时，再按普通文本或链接文本保留。
• 如果 HTML/Markdown 资源类型无法明确判断为图片、音频或 PDF，默认保留为普通链接，不调用上传。
• 如果同一正文中有多个资源，先列出资源清单并一次性询问用户哪些需要上传、哪些保留原始 URL/路径；获得决定后再执行上传和正文树转换。
• 如果用户选择了较多的文件进行上传，提醒用户文件上传是有配额的，“默认配额 20 次/天，Pro 会员用户 200 次/天”，避免超出限制。

mocli note create [--file] [--publish] [--tags]

本命令用于创建墨问笔记。创建笔记属于写入操作，执行命令前必须向用户确认要创建的内容来源、是否自动发布、以及标签。

mocli note create 接收的是墨问笔记正文语法树，不要把 Markdown、HTML、纯文本或自然语言描述直接交给命令。无论用户提供的是文件还是一段自然语言，都应先参考 `mo-note-content - 墨问笔记正文语法树` 格式化为正文树 JSON，再根据内容复杂度和后续编辑可能性，选择通过 --file 或 stdin 传入。

可选参数：

• --file string：从文件读取笔记内容。建议使用绝对路径，文件内容必须是格式化后的墨问笔记正文语法树 JSON。
• --publish：创建后自动发布笔记。只有用户明确要求“发布/公开/创建后发布”时才添加。
• --tags string：逗号分隔的标签列表，最多 5 个标签；创建后的标签管理参考 mocli note tag。

内容格式化流程

• 用户提供 Markdown 文件：读取 Markdown，转换为正文树 JSON。一级至三级标题分别转为 heading 节点，并写入 attrs.level 为字符串 "1"、"2"、"3"；任何超过三级的标题（包括 H4、H5、H6、H7、H8 及更高层级）都不生成 heading，改为带 bold mark 的 paragraph，保留标题文本和可表达的内联样式；普通段落转 paragraph，空行可转空 paragraph；加粗、链接、高亮、行内代码等可表达样式转为 marks；遇到本地图片、音频或 PDF 文件引用时，按“正文资源引用处理流程”确认是否上传并转换为资源节点；不支持的 Markdown 结构保守转为纯文本段落。
• 用户提供 HTML 文件：解析或提取正文内容，转换为正文树 JSON。<h1>、<h2>、<h3> 分别转为 attrs.level 为字符串 "1"、"2"、"3" 的 heading 节点；任何超过三级的标题（包括标准的 <h4>、<h5>、<h6>，以及上游解析出的 H7、H8 等更高层级标题）都改为带 bold mark 的 paragraph，保留标题文本和可表达的内联样式；支持的内联样式和链接转为 marks；遇到 <img> 或明确指向图片、音频、PDF 的 <a href> 时，按“正文资源引用处理流程”确认是否上传并转换为资源节点；不支持的标签应提取其中有用的可读文字并按原文语义转为文本节点，不要把 HTML 标签源码本身保存到笔记中。
• 用户提供 text 文件或直接粘贴正文：按段落拆分为 paragraph 和 text 节点；空行可转为空 paragraph。
• 用户只提供自然语言描述：先根据描述生成笔记正文，再转换为正文树 JSON；如果标题、标签、是否发布等关键信息不明确，先向用户确认。
• 正文块之间的段落间距按 `mo-note-content - 段落间距` 处理，相邻正文块之间默认插入一个空段落。
• 转换后的顶层必须是 { "type": "doc", "content": [...] }。生成后应尽量做 JSON 语法校验，再执行创建命令。

使用原则

• 用户只说“创建笔记/保存到墨问”，默认不加 --publish，避免意外公开。
• 用户明确要求“发布笔记/公开发布/创建后自动发布”时，才使用 --publish。
• 用户提供标签时，用英文逗号拼接到 --tags，并确保不超过 5 个。
• 用户提供的源内容不是正文树 JSON 时，先格式化为正文树 JSON，再按“输入方式选择规则”决定保存为文件还是通过 stdin 传入。
• 临时 JSON 文件只用于命令输入，不要把 API Key 或其它敏感信息写入正文文件。
• 执行后按共享规则解析顶层 code、status、reason；成功时展示返回的笔记 ID 或链接，失败时展示 reason、msg、meta.hints 等可执行信息。

输入方式选择规则

• 用户提供 Markdown、HTML、text 文件，且内容结构比较复杂、转换成正文树 JSON 后可能需要多次调用 mocli note create 调整时，应保存为文件并使用 --file <path>。这样可以保留转换结果，避免上下文压缩、会话中断或重复尝试时丢失要创建的内容。
• 用户提供的内容比较长，且当前是创作、整理、润色类场景，判断创建前后还会持续打磨修改时，应保存为文件并使用 --file <path>。
• 用户提供的内容比较简单、较短，例如随手记录一件事、纯文本自然语言短句时，可以通过 stdin 传入格式化后的正文树 JSON，避免产生较多零碎临时文件。
• 如果无法判断用户更看重可追溯的文件还是一次性快速创建，应简短征询用户意见。

使用示例

• 从文件(--file)创建一篇私有笔记 mocli note create --file /path/to/note-body.json
• 从文件(stdin)创建一篇私有笔记 mocli note create < /path/to/note-body.json
• 通过 stdin 创建一篇短文本笔记 printf '%s' '{"type":"doc","content":[{"type":"paragraph","content":[{"type":"text","text":"今天随手记录一件事"}]}]}' | mocli note create
• 从文件创建并自动发布笔记 mocli note create --file /path/to/note-body.json --publish
• 创建带标签的笔记 mocli note create --file /path/to/note-body.json --tags "AI,产品思考"
• 创建带标签并自动发布的笔记 mocli note create --file /path/to/note-body.json --publish --tags "AI,产品思考"

mocli note edit [--note-id] [--file]

本命令用于编辑已有墨问笔记的正文。编辑笔记属于写入操作，执行命令前必须向用户确认目标笔记 ID、完整替换后的正文来源，以及是否确认用新正文覆盖原正文。

mocli note edit 接收的是完整的新墨问笔记正文语法树，不是局部 diff，也不是 Markdown、HTML、纯文本或自然语言描述。无论用户提供的是文件、粘贴正文还是“把某段改成某段”的自然语言指令，都应先整理成完整的正文树 JSON，再通过 --file 或 stdin 传入。正文树格式仍参考 `mo-note-content - 墨问笔记正文语法树`。

墨问笔记也可以在 Web 端、小程序端创建或编辑，这些编辑器可能产生当前 CLI 正文语法树尚未支持的节点，例如视频、多图画廊等。mocli note edit 通过 OpenAPI 覆盖提交时，不支持的节点可能被服务端过滤，导致原笔记中的对应内容丢失。

覆盖风险强制门禁

• 执行任何 mocli note edit 前，必须先检查最终要提交的完整正文树；没有完成检查时，不要执行编辑命令。
• 支持节点类型仅包括：doc、paragraph、heading、text、quote、note、image、audio、pdf、codeblock；支持 marks 类型仅包括：highlight、link、bold、code。heading.attrs.level 只支持字符串 "1"、"2"、"3"，分别表示 H1、H2、H3。
• 检查范围包括正文树里所有节点的 type，以及所有 marks[].type；从 note info --show-atom 获取 reply.info.content.ast 后，也必须先做这一步。
• 如果发现不支持的 type 或 marks[].type，例如 gallery、video、h1、h2、h3，立即停止，不要执行 mocli note edit。先列出不支持节点类型和可识别的节点信息，明确提示“覆盖提交后这些节点可能被过滤并造成数据丢失”，等待用户明确确认仍要继续覆盖后，才可以执行编辑命令。
• 风险提示必须发生在首次执行 mocli note edit 之前；不要先覆盖提交，再事后解释或道歉。

可选参数：

• --note-id string：要编辑的目标笔记 ID。必填。
• --file string：从文件读取编辑后的完整笔记内容。文件内容必须是格式化后的墨问笔记正文语法树 JSON。

编辑前确认流程

• 用户已经提供明确笔记 ID 和完整新正文时，复述目标笔记 ID 和正文来源，确认会覆盖原笔记正文后再执行。
• 用户只提供笔记链接时，先从链接中提取笔记 ID；无法稳定提取时，请用户补充笔记 ID。
• 用户只说“修改我最新的笔记/修改某篇笔记”但没有给笔记 ID 时，先用 mocli notes mine 或用户指定的上下文帮助定位候选笔记，再让用户确认具体笔记 ID。
• 用户提出局部修改要求时，先获得完整正文树 JSON，再基于完整正文树生成替换后的新正文；不要把局部修改片段直接传给 mocli note edit。
• 编辑前必须完成“覆盖风险强制门禁”；发现不支持节点或 marks 时，必须先向用户做阻塞式风险确认，不能把该提示留到执行后。

内容格式化流程

• 用户提供已经格式化好的正文树 JSON：先做 JSON 语法校验，并确认顶层是 { "type": "doc", "content": [...] }。
• 用户提供 Markdown、HTML、text 文件或粘贴正文：按 mocli note create 的内容格式化流程转换为完整正文树 JSON；其中 Markdown/HTML 资源引用同样按“正文资源引用处理流程”处理。