Mo Shared

mocli - 墨问 CLI 共享规则

本技能是墨问 CLI 技能库的前置技能，指导你如何通过 mocli 完成配置初始化、API Key配置、与 mocli 的交互响应解析、展示规则以及安全规则。

前置参考

• 如何获取墨问 API Key
• mocli 的输出协议
• mocli 的共用输出字段

通用执行流程

1. 先判断用户意图对应的具体 mocli 子命令；不要用搜索类命令替代更精确的列表类命令。 2. 如果命令需要 UID，而用户给的是人名、昵称或备注名，优先使用 `mo-remark` 查找 UID；未命中时再使用用户搜索或询问用户补充 UID。 3. 执行 mocli 后先读取顶层 code、status、reason，确认成功后再解析 reply。 4. 展示列表类结果时，优先使用 reply 中的有序 ID 列表（如 note_ids、uids、events）；再到对应的 Map（如 notes、users）取详情，避免直接遍历 Map 导致顺序错误。

配置初始化

首次使用，用户需提供墨问 API Key， 使用 mocli auth init --apik <api-key> 来完成初始化。

API Key 配置与管理

• 使用过程中，如果 mocli 响应 AUTH 错误（用户可能在墨问平台重置了 API Key 或者 本地配置丢失），可提醒用户重新提供 API Key，使用 mocli auth init --apik <api-key> [--force] 来重新初始化或更换(--force) API Key。
• 可以使用 mocli auth info [--profile] 查看当前的配置信息，使用 --profile 额外获取当前 API Key 对应的账户，在墨问平台上的 Profile 信息。

响应解析规则

• code=0 且 status=OK 表示成功；业务数据通常在 reply 中。
• meta.alerts 表示重要提示，成功或失败时都可能出现；应优先关注，并按提示类型决定展示位置，例如 CLI 新版本提醒通常附在业务结果之后。
• status=FAIL 或 code!=0 表示失败，应优先展示 reason、msg 和 meta.hints 中的可执行建议。
• reason=AUTH：提醒用户重新提供 API Key，并使用 mocli auth init --apik <api-key> --force 更新配置；不要输出旧 API Key。
• reason=VALIDATE：说明参数不合法，并根据当前 skill 的参数范围给出可选修正。
• reason=NETWORK：说明网络或代理失败；如果是在受限环境里执行，可提示需要网络/代理权限。
• reason=API 且存在 api_error.trace_id：展示 trace_id 便于反馈问题，但不要泄露认证信息。
• 如果返回为空列表或空 Map，明确说明“没有找到符合条件的数据”，不要编造结果。

响应展示规则

<a id="reply-display-rules"></a>

总则：根据用户的要求，基于数据条目的数据多少，尽量清晰、明确、格式优美的展示给用户

细则：

• 避免数据枯燥，适当增加一些 emoji 来增加数据的趣味性
• 时间戳格式化为可读的时间
• Bool 值尽量用 emoji 展示
• 如果数据比较少，就尽量详细的展示信息给用户
• 如果数据比较多，可以通过表格/列表等形式，尽量清晰、明确、格式优美的展示给用户。表格的字段选择上：
• 首先根据用户的要求，选择出用户关心的字段
• 如果用户没有指定字段，就展示大多数数据条目都具备的字段，最大化利用展示空间，同时尽量避免某一列只有少数数据
• 以上细则如果与用户的要求不一致，以用户的要求为准

笔记列表展示建议：

• 数据较少时，逐条展示核心信息：时间、作者、笔记标题、摘要。若用户关注某个字段（如阅读数、是否付费、公开状态），优先补充该字段。
• 数据较多时，先给出简短概览（数量、时间范围、主要作者或主题），再列出若干条最相关或最新的重点笔记；不要只做概括而省略具体条目。
• 笔记标题优先使用 note.title，如果标题本身不包含「」 或『』，就用『』包裹；作者优先使用 users[note.uid].name；摘要优先使用 note.brief。
• 字段缺失时不要编造内容。可省略缺失字段，或用“无标题”“未知作者”“无摘要”等明确占位。

更新提醒

当 mocli 检测到 CLI 有新版本可用时，会通过 meta.alerts 返回更新提醒。该提醒属于重要信息，应该明确的、显式的展示给用户，同时避免反复展示造成打扰。

展示更新提醒时：

• 保留当前版本、最新版本、构建时间和更新命令等关键信息。
• 可以用一个醒目的 emoji + 简短文字说明这是 CLI 更新提醒，但不要改写或省略具体更新命令。
• 如果已在当前会话中明确的、显式的展示过同一更新提醒（优先按当前版本+构建时间、最新版本+构建时间进行判断），后续响应中仍然可以继续提醒，但是要弱化为简短尾注、不占用主要内容区域。
• 不要自动执行更新命令，除非用户明确要求更新。
• 如果响应中同时存在业务数据和更新提醒，先展示用户请求的业务结果，再附上更新提醒。

安全规则

• 禁止输出密钥（user_key、api_key）到终端明文。
• 写入/删除操作前必须确认用户意图。

mocli - 关于墨问 API Key

API Key 是调用墨问 API 的私密凭证，墨问不会明文保存任何用户的私密凭证，所以获取了之后用户需要自行保存好。

如何获取

墨问小程序 -> 右下角我的 -> 找到开发者选项 -> 我的 API Key

遗失与更换

一旦遗失，墨问无法再次提供之前的 API Key，只能再次重新生成。一旦重新生成新的 API Key，旧有的 API Key 即时失效。

mocli - 输出协议

默认输出格式为 JSON 格式，分为成功响应 和 失败响应 两种情况。

字段说明

关键字段

code / status / reason 枚举

api_error 字段

meta 字段

hints 偏向可选的下一步建议；alerts 偏向重要状态或风险提醒。展示响应时，应优先保留并展示 alerts，不要因为 code=0 或业务请求成功而忽略。

响应示例

成功响应-无数据返回（操作类型）

{
  "code": 0, 
  "status": "OK",
}

成功响应-有数据返回（操作类型）

{
  "code": 0,
  "status": "OK",
  "reply": {
    "profile": {
      "UID": "KBqt7yiVrXBa9DJIJuUm3",
      "Name": "精卫鸟",
      "Member": {
        "IsMember": true,
        "Plans": {
          "pro": {
            "Type": "pro",
            "Status": 64,
          }
        }
      }
    }
  }
}

成功响应-带重要提示

{
  "code": 0,
  "status": "OK",
  "meta": {
    "alerts": [
      "UPDATE: new version available! current=v0.1.5 (build: 2026-04-30T14:53:45), latest=v0.1.6 (build: 2026-04-28T18:22:18). you can run `npm install -g @mowenxd/cli && npx skills add mowenxd/cli -y -g` to update."
    ]
  },
  "reply": {
    "profile": {
      "UID": "KBqt7yiVrXBa9DJIJuUm3",
      "Name": "精卫鸟",
      "Member": {
        "IsMember": true,
        "Plans": {
          "pro": {
            "Type": "pro",
            "Status": 64,
          }
        }
      }
    }
  }
}

失败响应-认证失败

{
  "code": 1,
  "status": "FAIL",
  "reason": "AUTH"
  "meta": {
    "hints": [
      "re-confirm, if need change api key, use --force to overwrite"
    ]
  }
}

失败响应-网络错误

{
  "code": 3,
  "status": "FAIL",
  "reason": "NETWORK",
  "msg": "data [AuthRepo.Ping]: auth ping fail."
}

失败响应-API 错误

{
  "code": 1,
  "status": "FAIL",
  "reason": "AUTH",
  "msg": "data [AuthRepo.Ping]: auth ping fail.",
  "api_error": {
    "code": 400,
    "reason": "LOGIN",
    "message": "service.v1 [login]: invalid api key.",
    "trace_id": "11bd5ca54ba723435ed671a7b8f66d7a"
  },
  "meta": {
    "hints": [
      "invalid api key, maybe it's changed in another thread.",
      "checkout latest api key and use 'mocli auth init' to change."
    ]
  },
}

mocli - 共用的输出字段

<a id="auth-info"></a>

AuthInfo - 认证信息

---

<a id="user-info"></a>

UserInfo - 用户信息

---

<a id="user-member-info"></a>

UserMemberInfo - 用户会员信息

---

<a id="note-info"></a>

NoteInfo - 笔记信息

---

<a id="note-content"></a>

NoteContent - 笔记正文

注：列表场景，只返回字数信息

---

<a id="note-status"></a>

NoteStatus - 笔记状态

---

<a id="note-flag"></a>

NoteFlag - 笔记标记

---

<a id="note-stat"></a>

NoteStat - 笔记计数