@dinoxx/dinox-cli 1.0.18 → 1.0.19

package/README.md

@@ -116,7 +116,7 @@ dino auth status
 dino note search "AI"
 dino note search "AI" --days 7
 dino note search "AI" --from 2026-02-01 --to 2026-02-28
-dino note search "AI" --box "Inbox"
+dino note search "AI" --boxes "Inbox"
 dino note search --sql 'type = "crawl" AND zettel_boxes IN ("Inbox","Project")'
 ```
 
@@ -209,7 +209,7 @@ dino box add --name "Inbox" --description "用于存放待整理的想法和资
 
 ```bash
 dino prompt list
-dino prompt add --name "周报助手" --cmd "请基于本周笔记输出一份简洁周报"
+dino prompt add --name "周报助手" --prompt "请基于本周笔记输出一份简洁周报"
 ```
 
 ## 5.5 配置
@@ -304,11 +304,12 @@ dino box add "你的卡片盒"
 
 ## 8.1 全局参数（适用于 CLI）
 
-以下参数可放在命令前后使用，例如：`dino --json auth status`。
+以下参数可放在命令前后使用，例如：`dino --format json auth status`。
 
 | 参数 | 类型 | 说明 |
 | --- | --- | --- |
-| `--json` | flag | 输出 machine-readable YAML（仅被支持该参数的命令读取）。 |
+| `--json` | flag | 兼容旧行为，输出 machine-readable YAML（历史保留写法）。 |
+| `--format <yaml\|json>` | string | 结构化输出格式。推荐 AI / 脚本使用 `--format json`。 |
 | `--offline` | flag | 跳过 connect/sync，仅用本地缓存（仅被支持该参数的命令读取）。 |
 | `--sync-timeout <ms>` | integer | 覆盖连接/同步超时毫秒，必须是正整数。 |
 | `--verbose` | flag | 预留 verbose 开关。 |
@@ -323,7 +324,7 @@ dino box add "你的卡片盒"
 | --- | --- | --- |
 | `<token>` | 是 | 登录 token，直接传 token 字符串（不需要 `Bearer` 前缀）。 |
 
-支持全局参数：`--json`、`--sync-timeout`
+支持全局参数：`--json`、`--format`、`--sync-timeout`
 
 ### `dino auth logout`
 
@@ -337,7 +338,7 @@ dino box add "你的卡片盒"
 
 查看当前登录与同步状态。
 
-支持全局参数：`--json`、`--offline`、`--sync-timeout`
+支持全局参数：`--json`、`--format`、`--offline`、`--sync-timeout`
 
 ## 8.3 `sync` 命令
 
@@ -345,9 +346,29 @@ dino box add "你的卡片盒"
 
 连接并执行同步。
 
-支持全局参数：`--json`、`--sync-timeout`
+支持全局参数：`--json`、`--format`、`--sync-timeout`
 
-## 8.4 `note` 命令
+## 8.4 `schema` 命令
+
+### `dino schema [path]`
+
+查看命令 schema，了解参数、风险级别、输出结构与示例。推荐 AI / 脚本在不确定调用方式时先查看。
+
+| 参数 | 必填 | 说明 |
+| --- | --- | --- |
+| `[path]` | 否 | 命令路径，例如 `note.search`、`todo.update`、`sync`。不传则列出所有可用 schema。 |
+
+支持全局参数：`--json`、`--format`
+
+示例：
+
+```bash
+dino schema
+dino schema note.search
+dino schema note.search --format json
+```
+
+## 8.5 `note` 命令
 
 ### `dino note search [query]`
 
@@ -363,11 +384,11 @@ dino box add "你的卡片盒"
 | `--from <date>` | 否 | 创建时间起点，支持 `YYYY-MM-DD` 或 ISO datetime。 |
 | `--to <date>` | 否 | 创建时间终点，支持 `YYYY-MM-DD` 或 ISO datetime。 |
 | `--days <n>` | 否 | 最近 N 天（按 `created_at`），不能与 `--from/--to` 同时使用。 |
-| `--box <string\|@file>` | 否 | 按卡片盒名称筛选（支持 JSON 数组或逗号/换行分隔）；会自动解析为 box id 查询。 |
+| `--boxes <string\|@file>` | 否 | 按卡片盒名称筛选（支持 JSON 数组或逗号/换行分隔）；会自动解析为 box id 查询。 |
 | `--sql <expr>` | 否 | SQL 风格条件表达式；仅支持字段 `id/content_md/summary/tags/zettel_boxes/created_at/type`，其中 `zettel_boxes` 按名称自动转 id。只支持只读 WHERE 条件（禁止 `INSERT/UPDATE/DELETE`、注释和多语句）。 |
 | `--include-deleted` | 否 | 包含软删除笔记。 |
 
-支持全局参数：`--offline`、`--sync-timeout`
+支持全局参数：`--json`、`--format`、`--offline`、`--sync-timeout`
 
 ### `dino note get <id>`
 
@@ -377,7 +398,7 @@ dino box add "你的卡片盒"
 | --- | --- | --- |
 | `[id]` | 否 | 单个笔记 ID（可与 `--ids` 组合，去重后批量更新）。 |
 
-支持全局参数：`--json`、`--offline`、`--sync-timeout`
+支持全局参数：`--json`、`--format`、`--offline`、`--sync-timeout`
 
 ### `dino note detail [id]`
 
@@ -393,7 +414,7 @@ dino box add "你的卡片盒"
 
 说明：`[id]` 与 `--ids` 至少提供一个。
 
-支持全局参数：`--offline`、`--sync-timeout`
+支持全局参数：`--json`、`--format`、`--offline`、`--sync-timeout`
 
 ### `dino note create --title <string> --content <string|@file> [options]`
 
@@ -405,9 +426,10 @@ dino box add "你的卡片盒"
 | `--content <string|@file>` | 是 | Markdown 内容，可传 `@文件路径`。 |
 | `--type <note\|crawl>` | 否 | 笔记类型，默认 `crawl`。 |
 | `--tags <string\|@file>` | 否 | 标签列表（JSON 数组或逗号/换行分隔）。 |
-| `--zettel_boxes <string\|@file>` | 否 | 卡片盒名称列表（JSON 数组或逗号/换行分隔）。 |
+| `--boxes <string\|@file>` | 否 | 卡片盒名称列表（JSON 数组或逗号/换行分隔）。 |
+| `--dry-run` | 否 | 仅预览将要创建的笔记，不实际写入。 |
 
-支持全局参数：`--json`、`--offline`、`--sync-timeout`
+支持全局参数：`--json`、`--format`、`--offline`、`--sync-timeout`
 
 ### `dino note update [id] [options]`
 
@@ -422,10 +444,12 @@ dino box add "你的卡片盒"
 | `--ids <string\|@file>` | 否 | 批量更新的笔记 ID 列表（JSON 数组或逗号/换行分隔）。 |
 | `--tags <string\|@file>` | 否 | 标签列表（JSON 数组或逗号/换行分隔）。传 `[]` 可清空标签。 |
 | `--boxes <string\|@file>` | 否 | 卡片盒名称列表（JSON 数组或逗号/换行分隔）。传 `[]` 可清空卡片盒。 |
+| `--starred <true\|false>` | 否 | 设置收藏状态。 |
+| `--dry-run` | 否 | 仅预览将要执行的变更，不实际写入。 |
 
 说明：`<id>` 与 `--ids` 至少提供一个；`--tags` 与 `--boxes` 至少提供一个。
 
-支持全局参数：`--json`、`--offline`、`--sync-timeout`
+支持全局参数：`--json`、`--format`、`--offline`、`--sync-timeout`
 
 ### `dino note delete <id>`
 
@@ -435,9 +459,13 @@ dino box add "你的卡片盒"
 | --- | --- | --- |
 | `<id>` | 是 | 笔记 ID。 |
 
-支持全局参数：`--json`、`--offline`、`--sync-timeout`
+| 选项 | 必填 | 说明 |
+| --- | --- | --- |
+| `--dry-run` | 否 | 仅预览将要执行的删除，不实际写入。 |
+
+支持全局参数：`--json`、`--format`、`--offline`、`--sync-timeout`
 
-## 8.5 `tag` 命令
+## 8.6 `tag` 命令
 
 ### `dino tag list`
 
@@ -445,7 +473,8 @@ dino box add "你的卡片盒"
 
 | 选项 | 必填 | 说明 |
 | --- | --- | --- |
-| `--json` | 否 | 输出 machine-readable YAML。 |
+| `--json` | 否 | 兼容旧行为，输出 machine-readable YAML。 |
+| `--format <yaml\|json>` | 否 | 结构化输出格式，推荐 AI / 脚本使用 `json`。 |
 | `--offline` | 否 | 跳过 connect/sync，仅用本地缓存。 |
 | `--sync-timeout <ms>` | 否 | 覆盖连接/同步超时毫秒。 |
 
@@ -461,13 +490,15 @@ dino box add "你的卡片盒"
 | --- | --- | --- |
 | `--name <string>` | 否 | 标签名/路径，可替代位置参数 `[name]`。 |
 | `--emoji <string>` | 否 | 标签 emoji。 |
-| `--json` | 否 | 输出 machine-readable YAML。 |
+| `--json` | 否 | 兼容旧行为，输出 machine-readable YAML。 |
+| `--format <yaml\|json>` | 否 | 结构化输出格式，推荐 AI / 脚本使用 `json`。 |
+| `--dry-run` | 否 | 仅预览将要创建或恢复的标签，不实际写入。 |
 | `--offline` | 否 | 跳过 connect/sync，仅用本地缓存。 |
 | `--sync-timeout <ms>` | 否 | 覆盖连接/同步超时毫秒。 |
 
 说明：`[name]` 与 `--name` 至少提供一个；若两者都提供且值不同会报错。
 
-## 8.6 `box` 命令
+## 8.7 `box` 命令
 
 ### `dino box list`
 
@@ -491,17 +522,19 @@ dino box add "你的卡片盒"
 | `--name <string>` | 否 | 卡片盒名称，可替代位置参数 `[name]`。 |
 | `--description <string>` | 否 | 用途说明（可帮助 AI 路由笔记）。 |
 | `--color <string>` | 否 | 卡片盒颜色。 |
-| `--json` | 否 | 输出 machine-readable YAML。 |
+| `--json` | 否 | 兼容旧行为，输出 machine-readable YAML。 |
+| `--format <yaml\|json>` | 否 | 结构化输出格式，推荐 AI / 脚本使用 `json`。 |
+| `--dry-run` | 否 | 仅预览将要创建或恢复的卡片盒，不实际写入。 |
 | `--offline` | 否 | 跳过 connect/sync，仅用本地缓存。 |
 | `--sync-timeout <ms>` | 否 | 覆盖连接/同步超时毫秒。 |
 
 说明：`[name]` 与 `--name` 至少提供一个；若两者都提供且值不同会报错。
 
-## 8.7 `prompt` 命令
+## 8.8 `prompt` 命令
 
 ### `dino prompt list`
 
-列出 Prompt（`name` 与 `cmd`）。
+列出 Prompt（`name` 与 `prompt`）。
 
 | 选项 | 必填 | 说明 |
 | --- | --- | --- |
@@ -515,16 +548,18 @@ dino box add "你的卡片盒"
 | 选项 | 必填 | 说明 |
 | --- | --- | --- |
 | `--name <string>` | 是 | Prompt 名称。 |
-| `--cmd <string>` | 是 | Prompt 指令内容。 |
-| `--json` | 否 | 输出 machine-readable YAML。 |
+| `--prompt <string>` | 是 | Prompt 文本内容。 |
+| `--json` | 否 | 兼容旧行为，输出 machine-readable YAML。 |
+| `--format <yaml\|json>` | 否 | 结构化输出格式，推荐 AI / 脚本使用 `json`。 |
+| `--dry-run` | 否 | 仅预览将要创建或恢复的 Prompt，不实际写入。 |
 | `--offline` | 否 | 跳过 connect/sync，仅用本地缓存。 |
 | `--sync-timeout <ms>` | 否 | 覆盖连接/同步超时毫秒。 |
 
-## 8.8 `config` 命令
+## 8.9 `config` 命令
 
 ### `dino config get [key]`
 
-读取配置（输出 YAML）。
+读取配置。推荐 AI / 脚本使用 `dino config get [key] --format json`。
 
 | 参数 | 必填 | 说明 |
 | --- | --- | --- |
@@ -551,15 +586,15 @@ sync.timeoutMs
 sync.timeoutMs    (必须为正整数)
 ```
 
-## 8.9 `info` 命令
+## 8.10 `info` 命令
 
 ### `dino info`
 
 显示 CLI 版本信息。
 
-支持全局参数：`--json`
+支持全局参数：`--json`、`--format`
 
-## 8.10 `todo` 命令
+## 8.11 `todo` 命令
 
 ### `dino todo search [query]`
 
@@ -585,7 +620,7 @@ sync.timeoutMs    (必须为正整数)
 - 顶层包含 `meta`（查询条件回显、返回数量、是否截断）与 `tasks`（任务数组）。
 - 每条任务包含 `task_key`、`note_id`、`note_title`、`status`、层级关系与时间字段。
 
-支持全局参数：`--offline`、`--sync-timeout`
+支持全局参数：`--json`、`--format`、`--offline`、`--sync-timeout`
 
 ### `dino todo append [task]`
 
@@ -606,10 +641,11 @@ sync.timeoutMs    (必须为正整数)
 | `--task <text>` | 否 | 任务文本（可重复传入）。 |
 | `--tasks <string\|@file>` | 否 | 任务列表（JSON 数组或逗号/换行分隔）。 |
 | `--note-id <id>` | 否 | 指定目标笔记 ID。 |
+| `--dry-run` | 否 | 仅预览将要追加的任务和目标笔记，不实际写入。 |
 
 说明：`[task]`、`--task`、`--tasks` 至少提供一个。
 
-支持全局参数：`--offline`、`--sync-timeout`
+支持全局参数：`--json`、`--format`、`--offline`、`--sync-timeout`
 
 ### `dino todo create [task]`
 
@@ -629,10 +665,11 @@ sync.timeoutMs    (必须为正整数)
 | `--task <text>` | 否 | 任务文本（可重复传入）。 |
 | `--tasks <string\|@file>` | 否 | 任务列表（JSON 数组或逗号/换行分隔）。 |
 | `--title <string>` | 否 | 自定义笔记标题。 |
+| `--dry-run` | 否 | 仅预览将要创建的待办笔记，不实际写入。 |
 
 说明：`[task]`、`--task`、`--tasks` 至少提供一个。
 
-支持全局参数：`--offline`、`--sync-timeout`
+支持全局参数：`--json`、`--format`、`--offline`、`--sync-timeout`
 
 ### `dino todo update <taskId> --status <status>`
 
@@ -651,8 +688,9 @@ sync.timeoutMs    (必须为正整数)
 | 选项 | 必填 | 说明 |
 | --- | --- | --- |
 | `--status <status>` | 是 | 目标状态。 |
+| `--dry-run` | 否 | 仅预览将要更新的任务状态，不实际写入。 |
 
-支持全局参数：`--offline`、`--sync-timeout`
+支持全局参数：`--json`、`--format`、`--offline`、`--sync-timeout`
 
 ---
 

package/dist/cli.js

@@ -9,12 +9,16 @@ import { registerMCPCommands } from './commands/mcp/index.js';
 import { registerMetaCommands } from './commands/meta/index.js';
 import { registerNoteCommands } from './commands/notes/index.js';
 import { registerPromptCommands } from './commands/prompt/index.js';
+import { registerSchemaCommands } from './commands/schema/index.js';
 import { registerSyncCommand } from './commands/sync.js';
+import { registerStorageCommands } from './commands/storage/index.js';
 import { registerUpdateCommand } from './commands/update.js';
 import { registerTagsCommand } from './commands/tags/index.js';
 import { registerTodoCommands } from './commands/todo/index.js';
 import { getPackageVersion } from './utils/version.js';
+import { clearRequestedStructuredOutputFormat, resolveStructuredOutputFormat, setRequestedStructuredOutputFormat, } from './utils/output.js';
 export function createCli() {
+    clearRequestedStructuredOutputFormat();
     const program = new Command();
     program
         .name('dino')
@@ -22,10 +26,18 @@ export function createCli() {
         .version(getPackageVersion())
         .showHelpAfterError();
     program
-        .option('--json', 'output machine-readable YAML')
+        .option('--json', 'legacy machine-readable YAML output (equivalent to --format yaml)')
+        .option('--format <format>', 'structured output format: yaml | json')
         .option('--offline', 'skip connect/sync and only use local cache')
         .option('--sync-timeout <ms>', 'override sync/connect timeout (milliseconds)')
         .option('--verbose', 'enable verbose logging');
+    program.hook('preAction', (_thisCommand, actionCommand) => {
+        const options = actionCommand.optsWithGlobals?.() ?? {};
+        setRequestedStructuredOutputFormat(resolveStructuredOutputFormat(options));
+    });
+    program.hook('postAction', () => {
+        clearRequestedStructuredOutputFormat();
+    });
     registerAuthCommands(program);
     registerBoxesCommand(program);
     registerConfigCommands(program);
@@ -37,6 +49,8 @@ export function createCli() {
     registerSyncCommand(program);
     registerUpdateCommand(program);
     registerPromptCommands(program);
+    registerSchemaCommands(program);
+    registerStorageCommands(program);
     registerTagsCommand(program);
     registerTodoCommands(program);
     registerNoteCommands(program);

package/dist/commands/auth/index.d.ts

@@ -1,2 +1,4 @@
 import { Command } from 'commander';
+import type { CommandGroupDescriptor } from '../descriptor/types.js';
+export declare const authCommandGroup: CommandGroupDescriptor;
 export declare function registerAuthCommands(program: Command): void;