mo-shared

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

mocli - 墨问 CLI 共享规则

mocli - Mowen CLI Shared Rules

本技能是墨问 CLI 技能库的前置技能，指导你如何通过

mocli

完成配置初始化、API Key配置、与

mocli

的交互响应解析、展示规则以及安全规则。

This skill is a prerequisite skill for the Mowen CLI skill library, guiding you on how to complete configuration initialization, API Key configuration, interaction response parsing with

mocli

, display rules, and security rules through

mocli

前置参考

Prerequisite References

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

How to Obtain Mowen API Key
mocli Output Protocol
mocli Common Output Fields

通用执行流程

General Execution Flow

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

First determine the specific
```
mocli
```
subcommand corresponding to the user's intent; do not use search commands instead of more precise list commands.
If the command requires a UID and the user provides a name, nickname, or alias, prioritize using
```
mo-remark
```
to find the UID; if not found, use user search or ask the user to supplement the UID.
After executing
```
mocli
```
, first read the top-level
```
code
```
,
```
status
```
, and
```
reason
```
; only parse
```
reply
```
after confirming success.
When displaying list results, prioritize using ordered ID lists in the reply (such as
```
note_ids
```
,
```
uids
```
,
```
events
```
); then retrieve details from the corresponding Map (such as
```
notes
```
,
```
users
```
) to avoid order errors caused by directly traversing the Map.

配置初始化

Configuration Initialization

首次使用，用户需提供墨问 API Key，使用

mocli auth init --apik <api-key>

来完成初始化。

For first-time use, users need to provide a Mowen API Key and use

mocli auth init --apik <api-key>

to complete initialization.

API Key 配置与管理

API Key Configuration and Management

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

During use, if
```
mocli
```
returns an
```
AUTH
```
error (the user may have reset the API Key on the Mowen platform or lost local configuration), remind the user to re-provide the API Key and use
```
mocli auth init --apik <api-key> [--force]
```
to re-initialize or replace (
```
--force
```
) the API Key.
You can use
```
mocli auth info [--profile]
```
to view current configuration information; use
```
--profile
```
to additionally obtain the Profile information of the account corresponding to the current API Key on the Mowen platform.

响应解析规则

Response Parsing Rules

```
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，明确说明“没有找到符合条件的数据”，不要编造结果。

```
code=0
```
and
```
status=OK
```
indicate success; business data is usually in
```
reply
```
.
```
meta.alerts
```
represents important prompts, which may appear on success or failure; prioritize attention and determine the display position based on the prompt type. For example, CLI new version reminders are usually attached after business results.
```
status=FAIL
```
or
```
code!=0
```
indicates failure; prioritize displaying
```
reason
```
,
```
msg
```
, and executable suggestions in
```
meta.hints
```
.
```
reason=AUTH
```
: Remind the user to re-provide the API Key and use
```
mocli auth init --apik <api-key> --force
```
to update the configuration; do not output the old API Key.
```
reason=VALIDATE
```
: Indicates invalid parameters, and provide optional corrections based on the parameter range of the current skill.
```
reason=NETWORK
```
: Indicates network or proxy failure; if executed in a restricted environment, prompt that network/proxy permissions are required.
```
reason=API
```
and
```
api_error.trace_id
```
exists: Display the
```
trace_id
```
to facilitate problem feedback, but do not disclose authentication information.
If an empty list or empty Map is returned, clearly state "No data matching the criteria found" and do not fabricate results.

响应展示规则

Response Display Rules

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

细则：

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

笔记列表展示建议：

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

General Rule: Based on the user's requirements and the amount of data entries, display the content as clearly, explicitly, and beautifully formatted as possible

Detailed Rules:

Avoid dull data; appropriately add emojis to increase data interest
Format timestamps into readable time
Display Bool values with emojis as much as possible
If there is little data, display information in detail
If there is a lot of data, use forms/lists and other formats to display it as clearly, explicitly, and beautifully formatted as possible. For table field selection:
- First, select fields that the user cares about according to their requirements
- If the user does not specify fields, display fields that most data entries have to maximize display space while avoiding columns with only a small amount of data
If the above detailed rules are inconsistent with the user's requirements, the user's requirements take precedence

Note List Display Suggestions:

When there is little data, display core information item by item: time, author, note title, abstract. If the user focuses on a certain field (such as reading count, paid status, public status), supplement that field first.
When there is a lot of data, first give a brief overview (quantity, time range, main authors or topics), then list several of the most relevant or latest key notes; do not only summarize and omit specific entries.
Prioritize using
```
note.title
```
for note titles; if the title itself does not contain 「」 or 『』, wrap it with 『』; prioritize using
```
users[note.uid].name
```
for authors; prioritize using
```
note.brief
```
for abstracts.
Do not fabricate content when fields are missing. You can omit missing fields or use clear placeholders such as "Untitled", "Unknown Author", "No Abstract".

更新提醒

Update Reminders

当

mocli

检测到 CLI 有新版本可用时，会通过

meta.alerts

返回更新提醒。该提醒属于重要信息，应该明确的、显式的展示给用户，同时避免反复展示造成打扰。

展示更新提醒时：

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

When

mocli

detects that a new version of the CLI is available, it will return an update reminder via

meta.alerts

. This reminder is important information and should be clearly and explicitly displayed to the user while avoiding repeated displays that cause annoyance.

When displaying update reminders:

Retain key information such as current version, latest version, build time, and update command.
You can use a prominent emoji + short text to indicate that this is a CLI update reminder, but do not rewrite or omit the specific update command.
If the same update reminder has been clearly and explicitly displayed in the current session (judged by current version + build time, latest version + build time first), you can continue to remind in subsequent responses, but weaken it to a short footnote that does not occupy the main content area.
Do not automatically execute the update command unless the user explicitly requests an update.
If there are both business data and update reminders in the response, display the user's requested business results first, then attach the update reminder.

安全规则

Security Rules

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

Prohibited from outputting keys (user_key, api_key) in plain text to the terminal.
Must confirm user intent before performing write/delete operations.