Skip to content
Python
35.6 KB
Raw Blame
import { MEMORY_STATUSES } from "./core-responses.js";
import {
  EXIT_FAILED,
  EXIT_OK,
  EXIT_PLAN_BLOCKED,
  EXIT_RUNTIME_STOPPED,
  EXIT_USAGE,
} from "./exit-codes.js";

export type CommandOption = {
  readonly flag: string;
  readonly summary: string;
};

export type CommandDescriptor = {
  readonly name: string;
  readonly summary: string;
  readonly usage: string;
  readonly alternative_usage?: string;
  readonly capability_aliases?: readonly string[];
  readonly options: readonly CommandOption[];
  readonly exit_codes: readonly number[];
};

/**
 * Product-level names that are intentionally represented by an existing
 * command rather than by a second command with duplicate Runtime semantics.
 * Keep this machine-readable so package acceptance can compare the declared
 * CLI surface to the product lifecycle requirements.
 */
export const CAPABILITY_ALIASES: Readonly<Record<string, readonly string[]>> = {
  daemon: ["start", "stop", "restart", "status"],
  "startup-service": ["service-plan", "service-install", "service-uninstall"],
};

const PLATFORM_OPTION: CommandOption = {
  flag: "--platform <darwin|linux|win32>",
  summary: "目标平台,默认当前平台。",
};
const HOME_OPTION: CommandOption = {
  flag: "--home <path>",
  summary: "用户主目录,默认当前用户主目录。",
};
const DATA_DIR_OPTION: CommandOption = {
  flag: "--data-dir <path>",
  summary:
    "MemHub 数据目录绝对路径;默认沿用 ONE_MEMORY_DATA_DIR,不改写已有数据。",
};
const UID_OPTION: CommandOption = {
  flag: "--uid <id>",
  summary: "macOS LaunchAgent 所属用户 ID,默认当前用户。",
};
const XDG_OPTION: CommandOption = {
  flag: "--xdg-config-home <path>",
  summary: "Linux systemd user 配置根目录。",
};
const CONFIRM_OPTION: CommandOption = {
  flag: "--yes",
  summary: "确认执行;不加该参数时只输出计划,不做任何改动。",
};
/** The one confirmation convention, for irreversible operations only. */
const DESTRUCTIVE_CONFIRM_OPTION: CommandOption = {
  flag: "--yes",
  summary:
    "确认这次不可逆操作;不加时只说明将要做什么,不做任何改动,exit 0。(旧的 --confirm 仍作为别名接受。)",
};
const JSON_OPTION: CommandOption = {
  flag: "--json",
  summary: "以 JSON 输出到 stdout,供脚本与 Agent 消费。",
};
/** Global to the memory commands: whose memories are read or written. */
const USER_ID_OPTION: CommandOption = {
  flag: "--user-id <id>",
  summary:
    "读写哪个用户的记忆,默认 local(App 用的就是 local)。1–64 位字母、数字、点、下划线或连字符;其他用户的记忆来自用 sources connect hermes --user-id 接入的 Hermes profile。",
};
const WATCH_OPTION: CommandOption = {
  flag: "--watch",
  summary: "串行持续刷新;Ctrl-C 只停止观察,不停止 Runtime。",
};
const INTERVAL_OPTION: CommandOption = {
  flag: "--interval <seconds>",
  summary: "刷新间隔,默认 5 秒,范围 1..300;必须与 --watch 一起使用。",
};
const SERVICE_OPTIONS: readonly CommandOption[] = [
  PLATFORM_OPTION,
  HOME_OPTION,
  {
    flag: "--install-root <path>",
    summary: "受管安装根目录(必填)。",
  },
  DATA_DIR_OPTION,
  UID_OPTION,
  XDG_OPTION,
];

const SERVICE_USAGE =
  "--install-root <path> [--platform <id>] [--home <path>] [--data-dir <path>] [--uid <id>] [--xdg-config-home <path>]";

const INSTALL_OPTIONS: readonly CommandOption[] = [
  {
    flag: "--source <path>",
    summary:
      "离线发行目录;提供时完全不访问网络。完整 Runtime 内的 CLI 默认推导同目录,npm CLI 默认下载同版本 Release。",
  },
  {
    flag: "--release-manifest-url <https-url>",
    summary:
      "远程 release-manifest.json;仅在未提供 --source 时使用。发行构建可注入同版本默认模板,源码构建不假定私有下载源。",
  },
  {
    flag: "--channel <stable|prerelease>",
    summary:
      "远程发布通道;SemVer prerelease 默认 prerelease,其余默认 stable。不会静默跨通道。",
  },
  {
    flag: "--install-root <path>",
    summary: "受管安装根目录,默认按平台推导。",
  },
  HOME_OPTION,
  {
    flag: "--bin-dir <path>",
    summary: "受管 CLI 链接所在目录,POSIX 默认 ~/.local/bin。",
  },
  DATA_DIR_OPTION,
  UID_OPTION,
  XDG_OPTION,
  {
    flag: "--no-shell-path",
    summary:
      "不改登录 shell profile(隔离/脚本安装用);短指令需自行把 --bin-dir 加入 PATH。",
  },
  {
    flag: "--shell-profile <path>",
    summary:
      "把 PATH 区块写到指定文件而不是默认 ~/.zprofile / ~/.profile,便于隔离安装。",
  },
  {
    flag: "--preserve-data-dir",
    summary:
      "uninstall 用:当 --data-dir 位于 <install-root>/versions/ 内时,显式声明本次不把该目录视为受管子目录;只改计划保护范围,永不删除数据。",
  },
  {
    flag: "--allow-downgrade",
    summary:
      "install/upgrade 用:显式允许安装低于当前 build_number 的发行包;默认拒绝。不会由环境变量或配置默认开启。",
  },
  CONFIRM_OPTION,
];

const INSTALL_USAGE =
  "[--source <path> | --release-manifest-url <https-url>] [--channel <stable|prerelease>] [--install-root <path>] [--home <path>] [--bin-dir <path>] [--data-dir <path>] [--uid <id>] [--xdg-config-home <path>] [--no-shell-path] [--shell-profile <path>] [--preserve-data-dir] [--allow-downgrade] [--yes]";

const USAGE_EXITS = [EXIT_OK, EXIT_FAILED, EXIT_USAGE] as const;
const RUNTIME_EXITS = [
  EXIT_OK,
  EXIT_FAILED,
  EXIT_USAGE,
  EXIT_RUNTIME_STOPPED,
] as const;

const KIND_OPTION: CommandOption = {
  flag: "--kind <chat|experience|fact>",
  summary:
    "记忆所在的命名空间;工作/编码场景的经验和事实需要同时给 --variant。list 输出里每条都带 kind/variant。",
};
const VARIANT_OPTION: CommandOption = {
  flag: "--variant <working|coding>",
  summary:
    "经验或事实属于工作还是编码场景;必须和 --kind experience|fact 一起用。",
};

export const COMMANDS: readonly CommandDescriptor[] = [
  {
    name: "serve",
    summary: "在前台启动完整 Runtime(Core 与 Host Gateway),不注册系统服务。",
    usage: "memhub serve",
    options: [],
    exit_codes: USAGE_EXITS,
  },
  {
    name: "start",
    summary:
      "启动本机 Runtime;已有通过身份校验的实例时只连接,不重复启动。受管服务会同时恢复登录时自动启动。",
    usage: "memhub start [--json]",
    options: [JSON_OPTION],
    exit_codes: USAGE_EXITS,
  },
  {
    name: "stop",
    summary:
      "停止通过身份校验的本机 Runtime;身份不明确时不发送信号。受管服务(launchd/systemd、App)停止后登录时也不会自动启动,直到再次运行 memhub start。",
    usage: "memhub stop [--json]",
    options: [JSON_OPTION],
    exit_codes: USAGE_EXITS,
  },
  {
    name: "restart",
    summary: "先停止再启动本机 Runtime,两步串行执行。",
    usage: "memhub restart [--json]",
    options: [JSON_OPTION],
    exit_codes: USAGE_EXITS,
  },
  {
    name: "status",
    summary: "只读查询 Runtime 运行状态;不启动服务、不迁移数据、不改配置。",
    usage: "memhub status [--watch] [--interval <seconds>] [--json]",
    options: [WATCH_OPTION, INTERVAL_OPTION, JSON_OPTION],
    exit_codes: RUNTIME_EXITS,
  },
  {
    name: "doctor",
    summary:
      "按诊断口径做只读检查并给出修复建议;默认不修复任何东西。Runtime 未运行时 exit 3。",
    usage: "memhub doctor [--json]",
    options: [JSON_OPTION],
    exit_codes: RUNTIME_EXITS,
  },
  {
    name: "logs",
    summary:
      "读取本机脱敏诊断日志;logs export 会把排查包(含系统崩溃报告)直接存到下载目录。默认显示最近一次会话的 200 条事件。",
    usage:
      "memhub logs export [--json]\n            memhub logs [--since <15m|2h|7d|RFC3339>] [--session <id>] [--trace <id>] [--incident <id>] [--operation <id>] [--request <id>] [--job <id>] [--task <id>] [--component <name>] [--event <name>] [--errors-only] [--tail <1..5000>] [--follow] [--json]",
    options: [
      {
        flag: "--since <time>",
        summary: "从相对时长或 RFC3339 时间开始读取。",
      },
      { flag: "--session <id>", summary: "只看一个运行会话。" },
      { flag: "--trace <id>", summary: "只看一次跨组件操作。" },
      { flag: "--incident <id>", summary: "查看问题时间点前后同实例的事件。" },
      { flag: "--operation <id>", summary: "只看一个持久操作。" },
      { flag: "--request <id>", summary: "只看一个模型或写入请求。" },
      { flag: "--job <id>", summary: "只看一个导入任务。" },
      { flag: "--task <id>", summary: "只看一个记忆处理任务。" },
      { flag: "--component <name>", summary: "按组件过滤。" },
      { flag: "--event <name>", summary: "按事件名过滤。" },
      { flag: "--errors-only", summary: "只显示错误事件。" },
      { flag: "--tail <n>", summary: "最多返回多少条,默认 200,上限 5000。" },
      { flag: "--follow", summary: "持续读取新事件;Ctrl-C 仅停止观察。" },
      {
        flag: "--json",
        summary:
          "以 NDJSON 输出到 stdout(每行一个脱敏事件;非单 JSON 文档),供脚本与 Agent 消费。",
      },
    ],
    exit_codes: USAGE_EXITS,
  },
  {
    name: "init",
    summary:
      "首次接入引导。在终端里(未加 --json)进入交互向导:选择来源 → 是否开启处理 → 配置模型。非终端或加 --json 时不读 stdin,只列出可接入的来源和下一步命令。脚本接入请用 sources connect。",
    usage: "memhub init [--json]",
    options: [JSON_OPTION],
    exit_codes: RUNTIME_EXITS,
  },
  {
    name: "sources",
    summary:
      "列出来源,直接接入来源,或按 request id 查接入回执。connect 不加 --import 只授权(处理保持冻结:不导入历史、不扫描新会话);加 --import 同时导入历史并开启持续同步,返回 request id。目录来自环境变量覆盖的来源必须加 --confirm-overrides。Hermes 的每个 profile 是一个独立用户:用 --user-id 和 --root 接入,授权并导入历史(会自动排除 ~/.hermes/profiles/**,各用户互不读取)。",
    usage:
      "memhub sources list [--json]\n            memhub sources connect <id> [<id> ...] [--import] [--confirm-overrides] [--request-id <uuid>] [--json]\n            memhub sources connect hermes --user-id <id> --root <path> [--import] [--request-id <uuid>] [--json]\n            memhub sources connect --all-detected [--import] [--confirm-overrides] [--json]\n            memhub sources receipt <request-id> [--json]",
    options: [
      {
        flag: "--import",
        summary:
          "接入后立即导入历史会话并开启持续同步;不加时只授权,处理保持冻结。",
      },
      {
        flag: "--user-id <id>",
        summary:
          "只用于 hermes:这条接入属于哪个用户(默认 local)。和 --root 一起接入一个 Hermes profile,例如 --user-id wife --root ~/.hermes/profiles/wife;其他来源只能是 local。",
      },
      {
        flag: "--root <path>",
        summary:
          "只用于 hermes:读取的根目录(~ 会展开为主目录)。默认是 Hermes 自己的目录 ~/.hermes。",
      },
      {
        flag: "--all-detected",
        summary:
          "接入全部已检测到(location_state=found)的来源;与具体来源互斥。",
      },
      {
        flag: "--confirm-overrides",
        summary:
          "确认接受目录来自环境变量覆盖的来源(如 DSH_HOME 指定的目录);不加时这些来源被拒绝(指定来源时)或跳过并列出(--all-detected 时)。",
      },
      {
        flag: "--request-id <uuid>",
        summary:
          "--import 的幂等键;用同一个 id 重试只会读回第一次的回执,不会重复导入。",
      },
      JSON_OPTION,
    ],
    exit_codes: RUNTIME_EXITS,
  },
  {
    name: "sync",
    summary: "查看 Harness 处理状态;直接 Freeze/Thaw 某个来源。",
    usage:
      "memhub sync status [--json]\n            memhub sync <pause|resume> --source <id> [--json]",
    options: [
      {
        flag: "--source <id>",
        summary: "暂停或恢复的目标来源。",
      },
      JSON_OPTION,
    ],
    exit_codes: RUNTIME_EXITS,
  },
  {
    name: "progress",
    summary: "只读查看导入与生成进度;状态和计数分开呈现,不编造完成百分比。",
    usage:
      "memhub progress [--job <job-id>] [--issues] [--limit <n>] [--watch] [--interval <seconds>] [--json]",
    options: [
      { flag: "--job <job-id>", summary: "只看一个导入任务。" },
      {
        flag: "--issues",
        summary: "同时读取该导入任务的问题;必须与 --job 一起使用。",
      },
      {
        flag: "--limit <n>",
        summary: "每个任务/问题列表最多输出多少条,默认 50,上限 100。",
      },
      WATCH_OPTION,
      INTERVAL_OPTION,
      JSON_OPTION,
    ],
    exit_codes: RUNTIME_EXITS,
  },
  {
    name: "jobs",
    summary:
      "查看或控制导入任务:start 创建 history/sync 任务;pause/resume/cancel 控制已有任务。都直接执行。",
    usage:
      "memhub jobs list [--json]\n" +
      "            memhub jobs show <job-id> [--json]\n" +
      "            memhub jobs start --source <id> [--operation <history|sync>] [--json]\n" +
      "            memhub jobs <pause|resume|cancel> --job <id> [--json]",
    options: [
      {
        flag: "--source <id>",
        summary: "start 要导入的来源;必须是已连接的来源。",
      },
      {
        flag: "--operation <history|sync>",
        summary:
          "start 的导入类型,默认 history;sync 与 scan --source 相同,立即增量同步一次。",
      },
      {
        flag: "--job <id>",
        summary: "pause/resume/cancel 的目标导入任务。",
      },
      JSON_OPTION,
    ],
    exit_codes: RUNTIME_EXITS,
  },
  {
    name: "models",
    summary:
      "管理生成模型配置。add/test 直接提交并返回操作 ID(异步,用 receipt 查结果);edit 直接执行;activate 换了向量模型(模型或维度)时先显示切换计划,需 --yes 确认后重新生成全部向量,switch 查看或取消、spaces 查看或清理旧向量数据;remove 不可逆,需 --yes。<profile-id>/<operation-id> 都是 UUID;脚本模式的凭据只从受控文件读取。",
    usage:
      "memhub models list [--json]\n            memhub models show <profile-id> [--json]\n            memhub models add --config-file <path> [--api-key-file <path>] [--activate [--yes] [--wait|--no-wait]] [--json]\n            memhub models test <profile-id> [--json]\n            memhub models receipt <operation-id> [--json]\n            memhub models edit <profile-id> --config-file <path> [--api-key-file <path>] [--json]\n            memhub models activate <profile-id> [--yes] [--wait|--no-wait] [--json]\n            memhub models switch <status|cancel> [--json]\n            memhub models spaces [--cleanup <space-id> --yes] [--json]\n            memhub models remove <profile-id> [--yes] [--json]",
    alternative_usage: "memhub models setup",
    options: [
      {
        flag: "--config-file <path>",
        summary:
          "有界 JSON 模型配置,不能含 api_key;edit 的补丁必须带 expected_revision。",
      },
      {
        flag: "--api-key-file <path>",
        summary: "从属主专用的普通文件读取凭据;内容不进入参数、输出或错误。",
      },
      {
        flag: "--activate",
        summary:
          "add 成功后先探测,再按 activate 的规则设为当前使用(向量模型变化时同样要确认切换)。",
      },
      {
        flag: "--wait | --no-wait",
        summary:
          "activate 开始向量模型切换后是否跟随进度;终端里默认跟随,Ctrl-C 只停止显示。",
      },
      {
        flag: "--cleanup <space-id>",
        summary: "spaces:立即删除一个已停用的向量空间(不可恢复,需 --yes)。",
      },
      DESTRUCTIVE_CONFIRM_OPTION,
      JSON_OPTION,
    ],
    exit_codes: RUNTIME_EXITS,
  },
  {
    name: "memories",
    summary:
      "列出、搜索、查看、添加、修改或物理删除记忆(对话、工作、编码三个场景)。add 和 App 的「添加记忆」是同一个入口;delete 不可逆,需 --yes。",
    usage:
      "memhub memories list [--scene <all|chat|working|coding>] [--source <id>] [--query <text>] [--status <state>] [--offset <n>] [--limit <n>] [--user-id <id>] [--json]\n            memhub memories show <memory-id> [--kind <kind>] [--variant <variant>] [--user-id <id>] [--json]\n            memhub memories add <text> [--request-id <uuid>] [--user-id <id>] [--json]\n            memhub memories add --content-file <path> [--request-id <uuid>] [--user-id <id>] [--json]\n            memhub memories add-status <request-id> [--user-id <id>] [--json]\n            memhub memories update <memory-id> --content-file <path> [--kind <kind>] [--variant <variant>] [--task <text>] [--user-id <id>] [--json]\n            memhub memories delete <memory-id> [--kind <kind>] [--variant <variant>] [--yes] [--user-id <id>] [--json]",
    options: [
      {
        flag: "--scene <all|chat|working|coding>",
        summary: "只列一个场景,默认 all。working/coding 列的是该场景的经验。",
      },
      { flag: "--source <id>", summary: "只列某个来源写入的记忆。" },
      {
        flag: "--query <text>",
        summary:
          "关键词搜索(只搜 active 记忆,在最相关的一批里匹配所有关键词,输出 search_window 时表示可能少计)。",
      },
      {
        flag: "--status <state>",
        summary: `记忆状态,取值 ${MEMORY_STATUSES.join("、")},默认 active。`,
      },
      { flag: "--offset <n>", summary: "跳过前 n 条,默认 0。" },
      {
        flag: "--limit <n>",
        summary: "本页最多返回多少条,默认 100,上限 500。",
      },
      KIND_OPTION,
      VARIANT_OPTION,
      {
        flag: "--content-file <path>",
        summary:
          "从有界普通文件读取正文:add 的新记忆(≤12000 字),或 update 的新内容(经验为 solution)。",
      },
      {
        flag: "--task <text>",
        summary: "update 经验(--kind experience)时同时改写 task。",
      },
      {
        flag: "--request-id <uuid>",
        summary:
          "add 的幂等键;用同一个 id 重试只会读回第一次的结果,不会重复添加。不给时自动生成并输出。",
      },
      DESTRUCTIVE_CONFIRM_OPTION,
      USER_ID_OPTION,
      JSON_OPTION,
    ],
    exit_codes: RUNTIME_EXITS,
  },
  {
    name: "profile",
    summary:
      "读取 SDK 组装后的用户长期画像(L0 + 已启用的长期画像补充);--versions 列出 L0 画像的版本链(最新在前,* 为当前版本)。",
    usage: "memhub profile [--versions] [--user-id <id>] [--json]",
    options: [
      {
        flag: "--versions",
        summary:
          "列出 L0 基本信息的版本链(get_user_basic_info),用于找出覆盖了正确值的错误版本。",
      },
      USER_ID_OPTION,
      JSON_OPTION,
    ],
    exit_codes: RUNTIME_EXITS,
  },
  {
    name: "settings",
    summary:
      "查看或切换记忆模式(lite / pro / ultra)。lite 不调用模型,只在原始对话里检索;pro 由模型提取记忆(System 1);ultra 在 pro 之上每晚自动进化(System 2,使用知识图谱)。任何模式都保留全部原始对话。切换不迁移数据:已处理的不会重做,排队中的和新的按新模式处理;需 --yes,不加时只显示计划。环境变量 ONE_MEMORY_GRAPH_STORE 会强制 ultra。settings features 查看或开关 SDK 的可选检索与提取功能(全局设置,默认全部保持 SDK 默认值):graph_rerank 图谱重排(仅 ultra)、same_series_timeline 同系列时间线(需 graph_rerank)、episode_recall 片段召回(pro / ultra,需先开 session_episodes 写入片段)、session_episodes 片段写入、episode_summary 片段摘要(每个片段一次模型调用)、intention 意图提取(默认开)、few_shot 提取示例;set 需 --yes,不加时只显示计划;reset 恢复默认值。settings language 查看或设置界面语言(App 切换语言时会自动设置):简体中文(zh-Hans)和 system 不指定 SDK 语言,SDK 照旧自动识别中文或英文;其余语言(en、zh-Hant、ja、es、de、pt、fr、ko、ru、id)会让提取等 SDK 提示使用该语言,立即生效。",
    usage:
      "memhub settings mode [lite|pro|ultra] [--yes] [--json]\n" +
      "            memhub settings features [--json]\n" +
      "            memhub settings features set <name>=<true|false> [...] [--yes] [--json]\n" +
      "            memhub settings features reset [<name> ...] [--json]\n" +
      "            memhub settings language [<code>|system] [--json]",
    options: [
      {
        flag: "mode [lite|pro|ultra]",
        summary: "不带模式只显示当前模式;带模式时先显示切换计划。",
      },
      {
        flag: "features set <name>=<true|false>",
        summary:
          "开关一个或多个 SDK 功能;功能在当前模式下不生效时会注明原因(例如 graph_rerank 需要 ultra)。",
      },
      {
        flag: "features reset [<name> ...]",
        summary: "把指定功能(不写则全部)恢复为 SDK 默认值。",
      },
      {
        flag: "language [<code>|system]",
        summary:
          "不带参数显示界面语言和 SDK 提示语言;带语言代码(en、zh-Hans、zh-Hant、ja、es、de、pt、fr、ko、ru、id)或 system 时设置。",
      },
      CONFIRM_OPTION,
      JSON_OPTION,
    ],
    exit_codes: RUNTIME_EXITS,
  },
  {
    name: "evolve",
    summary:
      "立即为一个用户运行记忆进化(System 2,仅 ultra 模式)。在后台运行并返回运行 ID;--wait 等待结果。同一用户同时只运行一次;每晚的自动进化由 Runtime 按设置安排。",
    usage:
      "memhub evolve [--user-id <id>] [--agent-id <id>] [--max-batches <n>] [--wait] [--json]",
    options: [
      USER_ID_OPTION,
      {
        flag: "--agent-id <id>",
        summary:
          "进化哪个 agent 的记忆,默认 all-apps(MemHub 写入记忆用的 agent)。",
      },
      {
        flag: "--max-batches <n>",
        summary: "每轮最多处理的批次数(1–1000),默认由 SDK 决定。",
      },
      { flag: "--wait", summary: "等待这次进化结束再返回。" },
      JSON_OPTION,
    ],
    exit_codes: RUNTIME_EXITS,
  },
  {
    name: "graph-width",
    summary:
      "嵌入维度变化、图谱宽度不匹配时的处置决定。keep_existing 与 export_first 直接执行;rebuild_with_new 会归档旧图谱并重建,需 --yes。",
    usage:
      "memhub graph-width --decision <keep_existing|export_first|rebuild_with_new> [--yes] [--json]",
    options: [
      {
        flag: "--decision <decision>",
        summary:
          "keep_existing(保持现有图谱)、export_first(先导出)、rebuild_with_new(导出后归档旧图谱并按新维度重建)。",
      },
      {
        ...DESTRUCTIVE_CONFIRM_OPTION,
        summary: "rebuild_with_new 必须加;其它决定不需要。",
      },
      JSON_OPTION,
    ],
    exit_codes: RUNTIME_EXITS,
  },
  {
    name: "host",
    summary:
      "宿主接入与被调用:列出本机宿主、查看接入状态、预览并安装/卸载召回注入。安装与卸载分两步:先预览出 fingerprint,再带 --approve 提交。",
    usage:
      "memhub host list [--json]\n            memhub host status --host <id> [--json]\n            memhub host install --host <id> [--json]\n            memhub host install --host <id> --approve <fingerprint> [--json]\n            memhub host uninstall --host <id> [--json]\n            memhub host uninstall --host <id> --approve <fingerprint> [--json]\n            memhub host sync skill --host <id> [--approve <fingerprint>] [--overwrite-modified] [--json]",
    alternative_usage:
      "memhub host install <id> [--approve <fingerprint>] [--json]\n            memhub host status <id> [--json]\n            memhub host uninstall <id> [--approve <fingerprint>] [--json]",
    options: [
      {
        flag: "--host <id>",
        summary:
          "目标宿主,如 cursor、claude-code、codex;也可直接写在动词后(memhub host install codex)。完整列表见 host list。",
      },
      {
        flag: "--approve <fingerprint>",
        summary:
          "提交预览给出的 fingerprint;缺少它 install/uninstall 只预览,不改动任何宿主文件。",
      },
      {
        flag: "--overwrite-modified",
        summary:
          "host sync skill 提交时允许覆盖本地被改过的 skill;默认不覆盖。",
      },
      JSON_OPTION,
    ],
    exit_codes: RUNTIME_EXITS,
  },
  {
    name: "recall",
    summary:
      "从原始对话与已沉淀记忆统一检索上下文;本地只读,不调用模型、不触发补索引。文本输出标明每条是「原始对话摘录」还是「记忆」(JSON 里是 kind: raw|memory)。",
    usage:
      "memhub recall <query> [--kind <raw|memory>] [--source <id>] [--limit <n>] [--character-budget <n>] [--timeout-ms <n>] [--user-id <id>] [--json]\n            memhub recall --query-file <path> [...]\n            memhub recall --stdin [...]",
    options: [
      {
        flag: "--query-file <path>",
        summary: "从有界普通文件读取查询,不进入 shell 历史。",
      },
      {
        flag: "--stdin",
        summary: "显式从管道读取一条有界查询;交互式 TTY 会拒绝,不等待输入。",
      },
      {
        flag: "--kind <raw|memory>",
        summary: "查询路径,可重复;默认同时查询 raw 与 memory。",
      },
      {
        flag: "--source <id>",
        summary: "只收窄 raw 原文来源,可重复;未请求 raw 时拒绝。",
      },
      { flag: "--limit <n>", summary: "最多返回 1..20 项,默认 8。" },
      {
        flag: "--character-budget <n>",
        summary: "总正文预算 200..20000 字符,默认 4000。",
      },
      {
        flag: "--timeout-ms <n>",
        summary: "Core 查询时限 50..30000 毫秒,默认 2000。",
      },
      USER_ID_OPTION,
      JSON_OPTION,
    ],
    exit_codes: RUNTIME_EXITS,
  },
  {
    name: "service-plan",
    summary: "生成用户级服务计划;只输出计划,不写文件也不执行命令。",
    usage: `memhub service-plan ${SERVICE_USAGE}`,
    options: SERVICE_OPTIONS,
    exit_codes: [EXIT_OK, EXIT_USAGE, EXIT_PLAN_BLOCKED],
  },
  {
    name: "service-install",
    summary: "预览用户级服务安装;只有 --yes 才写入服务文件并注册。",
    usage: `memhub service-install ${SERVICE_USAGE} [--yes]`,
    options: [...SERVICE_OPTIONS, CONFIRM_OPTION],
    exit_codes: [EXIT_OK, EXIT_FAILED, EXIT_USAGE, EXIT_PLAN_BLOCKED],
  },
  {
    name: "service-uninstall",
    summary:
      "预览用户级服务卸载;只有 --yes 才注销并删除逐字匹配的受管服务文件,不删数据。",
    usage: `memhub service-uninstall ${SERVICE_USAGE} [--yes]`,
    options: [...SERVICE_OPTIONS, CONFIRM_OPTION],
    exit_codes: [EXIT_OK, EXIT_FAILED, EXIT_USAGE, EXIT_PLAN_BLOCKED],
  },
  {
    name: "install",
    summary:
      "预览发行目录安装、memhub/memhub-cli/one-memory 短链接、PATH 条目与用户服务计划;只有 --yes 才执行。记忆数据迁移开始前失败会回滚;迁移开始后失败保留新版本、拒绝启动,并输出迁移日志与反馈地址。",
    usage: `memhub install ${INSTALL_USAGE}`,
    options: INSTALL_OPTIONS,
    exit_codes: [EXIT_OK, EXIT_FAILED, EXIT_USAGE, EXIT_PLAN_BLOCKED],
  },
  {
    name: "uninstall",
    summary:
      "卸载产品本身:停止服务、移除受管 CLI 链接与已安装版本文件;**不删数据**(dataDir 原样保留)。只有 --yes 才执行,默认只出计划。",
    usage: `memhub uninstall ${INSTALL_USAGE}`,
    options: INSTALL_OPTIONS,
    exit_codes: [EXIT_OK, EXIT_FAILED, EXIT_USAGE, EXIT_PLAN_BLOCKED],
  },
  {
    name: "upgrade",
    summary:
      "预览升级;只有 --yes 才切换受管版本并重启服务,不删数据。记忆数据迁移开始前失败会恢复旧版本;迁移开始后失败保留新版本、拒绝启动,并输出迁移日志与反馈地址(不会回滚到旧版本)。",
    usage: `memhub upgrade ${INSTALL_USAGE}`,
    options: INSTALL_OPTIONS,
    exit_codes: [EXIT_OK, EXIT_FAILED, EXIT_USAGE, EXIT_PLAN_BLOCKED],
  },
  {
    name: "delete-data",
    summary:
      "删除 MemHub 数据目录(记忆、来源、配置),不可逆。这是唯一会删除数据的命令;uninstall 不会。需要 Runtime 已停止;不加参数时只预览要删除的目录;删除需要 --yes 并用 --confirm 再写一遍同一个目录。",
    usage:
      "memhub delete-data [--data-dir <path>] [--yes --confirm <path>] [--json]",
    options: [
      {
        flag: "--data-dir <path>",
        summary: "要删除的数据目录绝对路径;默认当前使用的数据目录。",
      },
      {
        ...DESTRUCTIVE_CONFIRM_OPTION,
        summary:
          "删除时必须加,且要同时给出 --confirm <path>;不加时只预览,exit 0。",
      },
      {
        flag: "--confirm <path>",
        summary:
          "删除时必须加:再写一遍要删除的数据目录,与预览中的目录完全一致才执行。",
      },
      JSON_OPTION,
    ],
    exit_codes: [EXIT_OK, EXIT_FAILED, EXIT_USAGE, EXIT_PLAN_BLOCKED],
  },
  {
    name: "onboarding",
    summary:
      "onboarding reset 回到首次运行的引导流程。只清除引导完成状态:不删记忆数据,也不需要卸载重装。",
    usage: "memhub onboarding reset [--json]",
    options: [JSON_OPTION],
    exit_codes: RUNTIME_EXITS,
  },
  {
    name: "help",
    summary: "显示总帮助或单个命令的用法。",
    usage: "memhub help [command] [--json]",
    options: [JSON_OPTION],
    exit_codes: [EXIT_OK, EXIT_USAGE],
  },
  {
    name: "version",
    summary: "显示 CLI 版本。",
    usage: "memhub version [--json]",
    options: [JSON_OPTION],
    exit_codes: [EXIT_OK, EXIT_USAGE],
  },
  {
    name: "scan-roots",
    summary:
      "查看或登记被扫描的目录(scan roots)。add/remove 直接执行。(旧名 path 仍可用。)",
    usage:
      "memhub scan-roots list [--json]\n" +
      "            memhub scan-roots add --root <path> [--source <id>] [--no-recursive] [--json]\n" +
      "            memhub scan-roots remove --root <path> [--json]",
    options: [
      { flag: "--root <path>", summary: "要登记或移除的目录。" },
      {
        flag: "--source <id>",
        summary: "把目录绑定到某个来源;不给时由 Runtime 自动识别。",
      },
      { flag: "--no-recursive", summary: "只扫描该目录本身,不进入子目录。" },
      JSON_OPTION,
    ],
    exit_codes: RUNTIME_EXITS,
  },
  {
    name: "adapter",
    summary:
      "查看 Harness Adapter 的就绪状态与最近一次探测结果(list),或现场探测某个来源(probe --source <id>);两者均为只读。",
    usage:
      "memhub adapter list [--json]\n" +
      "            memhub adapter probe --source <id> [--json]",
    options: [
      { flag: "--source <id>", summary: "probe 的目标来源。" },
      JSON_OPTION,
    ],
    exit_codes: RUNTIME_EXITS,
  },
  {
    name: "scan",
    summary:
      "立即增量扫描一个已连接并开启同步的来源,返回导入任务(与 jobs start --operation sync 相同)。接入全部来源请用 sources connect --all-detected --import。",
    usage: "memhub scan --source <id> [--json]",
    options: [
      {
        flag: "--source <id>",
        summary: "要扫描的来源。",
      },
      JSON_OPTION,
    ],
    exit_codes: RUNTIME_EXITS,
  },
  {
    name: "write",
    summary:
      "提交一段 OpenAI 格式的对话(messages)到写入队列,异步加工成记忆;或按 request id 查询状态。request id 是幂等键:不给时自动生成并输出,重试请带上同一个。新增一条结论式记忆请用 memories add。",
    usage:
      "memhub write submit --messages-file <path> --session <id> [--source <id>] [--request-id <id>] [--memory-at <RFC3339>] [--live] [--user-id <id>] [--json]\n            memhub write status <request-id> [--user-id <id>] [--json]",
    options: [
      {
        flag: "--messages-file <path>",
        summary:
          "OpenAI messages 数组(或 {messages:[…]}),1..200 条,role 为 user/assistant/tool,至少一条 user。",
      },
      { flag: "--session <id>", summary: "会话 ID。" },
      { flag: "--source <id>", summary: "来源应用,默认 memhub-cli。" },
      {
        flag: "--request-id <id>",
        summary:
          "幂等键:同 id 同内容不会重复入队,同 id 不同内容被拒绝(409)。",
      },
      { flag: "--memory-at <RFC3339>", summary: "对话发生时间,必须带时区。" },
      { flag: "--live", summary: "优先处理。" },
      USER_ID_OPTION,
      JSON_OPTION,
    ],
    exit_codes: RUNTIME_EXITS,
  },
  {
    name: "backup",
    summary:
      "备份与恢复主库(来源、写入队列、配置)。注意:不包含记忆本身——SDK 记忆库 hy-memory/ 不在备份里,restore 也不会替换它。create 的目标要放在 <数据目录>/backups/ 下才能被 restore 使用;restore 覆盖现有主库,需 Runtime 已停止,并加 --yes 与 --confirm <同一个备份路径>。",
    usage:
      "memhub backup create --target <path> [--json]\n" +
      "            memhub backup restore --source <path> [--yes --confirm <path>] [--json]",
    options: [
      {
        flag: "--target <path>",
        summary: "create 的备份文件路径,必须在数据目录内。",
      },
      {
        flag: "--source <path>",
        summary:
          "restore 的备份文件,必须是 <数据目录>/backups/ 下的受管备份。",
      },
      {
        ...DESTRUCTIVE_CONFIRM_OPTION,
        summary:
          "restore 必须加,且要同时给出 --confirm <path>;create 不需要。",
      },
      {
        flag: "--confirm <path>",
        summary:
          "restore 必须加:再写一遍 --source 的备份路径,完全一致才执行。",
      },
      JSON_OPTION,
    ],
    exit_codes: [...RUNTIME_EXITS, EXIT_PLAN_BLOCKED],
  },
  {
    name: "ui",
    summary:
      "用系统默认浏览器打开 Runtime 托管的 Web Console:先向 Core 换取一次性 loopback 登录码,再交给系统浏览器由 Core 置 HttpOnly/SameSite=Strict session;CLI 不向浏览器暴露裸 Core token。Runtime 未运行时 exit 3;Core 未提供该合同时如实返回 ui_session_contract_unavailable(exit 4)。",
    usage: "memhub ui [--json]",
    options: [JSON_OPTION],
    exit_codes: [...RUNTIME_EXITS, EXIT_PLAN_BLOCKED],
  },
];

/** Old names that still run but are not listed: `path` → `scan-roots`,
 * `task` → `write status`, `graph width` → `graph-width`. */
export const HIDDEN_COMMAND_ALIASES: Readonly<Record<string, string>> = {
  path: "scan-roots",
  task: "write",
  graph: "graph-width",
};

export function findCommand(name: string): CommandDescriptor | undefined {
  return COMMANDS.find((command) => command.name === name);
}

/** A listed command, or the command a hidden alias now runs as. */
export function findCommandOrAlias(
  name: string,
): CommandDescriptor | undefined {
  return findCommand(HIDDEN_COMMAND_ALIASES[name] ?? name);
}