# Mo Shared

> 墨问 CLI 共享规则：应用配置初始化、墨问 API Key 的配置与管理、墨问 CLI 响应的基础解析、墨问 CLI 的安全规则。当用户使用墨问 CLI 时触发。

- Skill: `mowenxd/mo-shared` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds add mowenxd/mo-shared`
- Raw SKILL.md: https://api.skillmd.com/api/skills/mowenxd/mo-shared/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: mowenxd (https://skillmd.com/u/mowenxd)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/mowenxd/mo-shared

---


# mocli - 墨问 CLI 共享规则

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

## 前置参考

* [如何获取墨问 API Key](references/api-key.md)
* [mocli 的输出协议](references/mocli-output-proto.md)
* [mocli 的共用输出字段](references/mocli-output-schema.md)

## 通用执行流程

1. 先判断用户意图对应的具体 `mocli` 子命令；不要用搜索类命令替代更精确的列表类命令。
2. 如果命令需要 UID，而用户给的是人名、昵称或备注名，优先使用 [`mo-remark`](../mo-remark/SKILL.md) 查找 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 展示
  - 如果数据比较少，就尽量详细的展示信息给用户
  - 如果数据比较多，可以通过表格/列表等形式，尽量清晰、明确、格式优美的展示给用户。表格的字段选择上：
    - 首先根据用户的要求，选择出用户关心的字段
    - 如果用户没有指定字段，就展示大多数数据条目都具备的字段，最大化利用展示空间，同时尽量避免某一列只有少数数据
  - 展示 `UserInfo.name` 时，如果客户端支持 Markdown 或 HTML 链接、且同一 `UserInfo` 的 `home_url` 非空，使用该链接包裹名称（如 `[name](home_url)`）；否则只展示名称，不编造或输出空链接。
  - 展示 `NoteInfo.title` 时，如果客户端支持 Markdown 或 HTML 链接、且同一 `NoteInfo` 的 `url` 非空，使用该链接包裹标题（如 `[title](url)`）；否则按原有标题规则展示，不编造或输出空链接。
  - 以上细则如果与用户的要求不一致，以用户的要求为准

**笔记列表展示建议：**

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

## 更新提醒

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

展示更新提醒时：

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

## 安全规则

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