@yosai/cli 0.0.0-stage → 0.2.1-test.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "{}"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 YOS (Yuou)
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,67 @@
-# Temporary Holding Version
+# yos-cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+YOS 能力的 Agent 执行入口：终端直调 YOS 工具 + 知识库文件上传。
+
+## 安装
+
+- 本地开发：`npm install && npm run build`，用 `node dist/index.js <命令>` 或 `npm link` 后使用 `yos`
+- 公网安装：`npm install -g @yosai/cli`（需 Node ≥ 18；装完 `yos --version` 验证）
+
+## 快速开始
+
+```bash
+yos login                          # 配置访问令牌（客户端「个人设置-访问令牌」页创建并复制）与端点
+yos doctor                         # 诊断配置与连通（显示当前身份）
+yos ping                           # 探活：连接与令牌有效性（退出码即结论，客户端对接用）
+yos kb list                        # 我的知识库
+yos kb upload ./report.pdf --kb KBxxx   # 上传文件到知识库
+yos docs tree KBxxx                # 知识库目录树
+yos docs download NDxxx --out ./   # 下载上传文件类型的原文件
+yos retrieve search '关键词' --kb KBxxx   # 语义检索
+yos retrieve read 'cortex://kb/KBxxx/doc/NDxxx:1-50'   # 读原文（区间简写）
+yos <领域> --help                   # 域内全部命令（kb / docs / retrieve / support / transcript）
+yos tool list                      # 底层工具通道（领域命令未覆盖时兜底）
+```
+
+## 命令清单
+
+| 命令 | 说明 |
+|---|---|
+| `yos login` | 配置访问令牌与端点（校验身份后保存） |
+| `yos doctor` | 诊断配置、访问令牌、连通、Skill 状态与 CLI 版本 |
+| `yos ping` | 探活：检查连接是否成功、令牌是否有效（退出码 0/2/3/4 即结论，客户端检测对接用） |
+| `yos kb <动作>` | 知识库：`list` / `detail` / `update` / `upload`（建库、删库请到 YOS 客户端） |
+| `yos docs <动作>` | 文档与节点：`tree` / `content` / `download` / `count` / `mkdir` / `create` / `update` / `rename` / `move` / `delete` / `restore` |
+| `yos retrieve <动作>` | 检索：`search` / `grep` / `read`（支持 `<target>:起-止`） / `neighbors` / `outline` |
+| `yos support <动作>` | 支持：`manual` / `manual-read` / `manual-search` / `upgrade` / `upgrade-log` / `feedback` |
+| `yos transcript <动作>` | 转写：`list` / `detail` |
+| `yos tool list` / `schema` / `call` | 底层工具通道（领域命令未覆盖时兜底） |
+| `yos version [--check]` | CLI 版本（`--check` 比对 npmjs 最新版） |
+| `yos update [--check]` | 升级到 npmjs 最新版并自动重同步 Skill |
+| `yos skill install [--target <dir>]` | 安装内置 Skill |
+
+所有命令支持 `--json` 输出与统一退出码（0 成功 / 1 业务失败 / 2 参数错误 / 3 网络 / 4 鉴权）。
+
+## 给 Agent 使用
+
+```bash
+yos skill install      # 安装 7 个内置 Skill（总入口 + 领域 + 安装引导）到 Claude Code / Cursor / Codex / Qoder / WorkBuddy 等技能目录
+```
+
+安装后重启 Agent 工具，即可用自然语言驱动（如「把这份报告上传到知识库」）。`yos` 为能力总入口（何时使用 / 能力地图 / 命令使用方式），Agent 据此路由到各领域细则；`yos-shared` 收录跨领域约定（输出解析、退出码契约、仍需自行校验内容的场景、安全纪律）；`yos-install` 是自包含的安装配置引导，可单独下载到发布仓库供用户引导装机。
+
+需要让 Agent 宿主（Cursor / Claude Desktop 等）直连 YOS MCP 时，在宿主中配置远程 MCP 端点 `<endpoint>/mcp` 并携带 `Authorization: Bearer <密钥>`（CLI 不代写宿主配置）。
+
+## 配置
+
+- 配置文件：`~/.config/yos/config.json`（权限 0600；目录可用 `YOS_CONFIG_DIR` 覆盖）
+- 环境变量（均优先于配置文件，适合 CI/容器场景）：`YOS_API_KEY` 访问令牌、`YOS_ENDPOINT` 服务端点
+- 端点：默认生产环境 `https://yos-bff.linkduoo.com`，`yos login --endpoint <url>` 持久切换（本地联调可用 http://localhost:8080）；`yos doctor` 显示当前生效端点及其来源
+
+## 故障排查
+
+- 退出码 4（鉴权失败）：访问令牌无效/已吊销/已过期，重新 `yos login`
+- 退出码 2（参数错误）：CLI 本地拦截、未发请求，按 `提示:` 里的用法改写参数
+- 上传报 20MB 上限：单文件上限 20MB，更大文件暂不支持
+- 下载报「没有该资源的访问权限：DOWNLOAD.xxx」：只有阅读权限的库不支持下载原文件，需库管理员授权
+- 退出码 3（网络）：确认端点可达；`yos version --check` 报网络错则是 npm 或 registry 不可达

package/dist/cli.js

@@ -0,0 +1,188 @@
+import { parseArgs } from 'node:util';
+import { DOMAIN_META } from './domain-commands.js';
+import { CliError, EXIT, UsageError } from './errors.js';
+import { print, printErr, renderRows } from './output.js';
+const registry = [];
+const GROUP_ORDER = ['知识库 kb', '文档 docs', '检索 retrieve', '支持 support', '转写 transcript', '工具通道', 'Agent 接入', '基础'];
+const RISK_LABEL = { read: '只读', write: '写入', danger: '高危' };
+export function register(command) {
+    registry.push(command);
+}
+export function renderHelp() {
+    const lines = [
+        'yos - YOS 能力的 Agent 执行入口',
+        '',
+        '推荐流程:',
+        '  0. yos <领域> --help             按领域浏览能力（kb / docs / retrieve / support / transcript）',
+        '  1. yos tool list                 动态发现全部工具（领域命令未覆盖时）',
+        '  2. 领域命令未覆盖的场景用 yos tool schema / tool call 兜底',
+        '  3. yos skill install             安装内置 Skill，接入本机 AI 助手（Claude Code / Cursor / Qoder 等）',
+        '',
+        '约定:',
+        '  - 输出默认人类可读；--json 输出结构化结果（工具返回原文在 text 字段内）',
+        '  - 退出码：0 成功 / 1 业务失败 / 2 参数错误 / 3 网络错误 / 4 鉴权失败',
+        '  - 删除类操作前先用 yos docs count <node_code> 查询影响范围，并取得用户明确确认',
+        '',
+        '环境变量（均优先于配置文件，便于 CI 免落盘）:',
+        '  YOS_API_KEY     访问令牌',
+        '  YOS_ENDPOINT    BFF 服务地址',
+        '  YOS_CONFIG_DIR  配置目录（缺省 ~/.config/yos）',
+        '',
+        '示例:',
+        '  yos doctor',
+        '  yos kb list',
+        "  yos retrieve search '报销标准' --kb KBxxxx",
+        "  yos retrieve read 'cortex://kb/KBxxxx/doc/NDxxxx:10-60'",
+        '  yos docs create "周报" --kb KBxxxx --content "正文内容"',
+        '  yos kb upload ./报告.pdf --kb KBxxxx',
+        '  yos docs download NDxxxx --out ./报告.pdf',
+        '',
+    ];
+    for (const group of GROUP_ORDER) {
+        const commands = registry.filter((command) => command.group === group);
+        if (commands.length === 0) {
+            continue;
+        }
+        lines.push(`${group}:`);
+        lines.push(indentRows(renderRows(commands.map((command) => [command.name, command.description]))));
+        lines.push('');
+    }
+    const ungrouped = registry.filter((command) => !command.group);
+    if (ungrouped.length > 0) {
+        lines.push(indentRows(renderRows(ungrouped.map((command) => [command.name, command.description]))));
+        lines.push('');
+    }
+    lines.push("运行 'yos <命令> --help' 查看命令用法");
+    return lines.join('\n');
+}
+export function renderDomainHelp(domain) {
+    const meta = DOMAIN_META[domain];
+    if (!meta) {
+        return null;
+    }
+    const commands = registry.filter((command) => command.name.startsWith(`${domain} `));
+    return [
+        `yos ${domain} - ${meta.description}`,
+        '',
+        indentRows(renderRows(commands.map((command) => [command.name, command.description]))),
+        '',
+        `运行 'yos ${domain} <动作> --help' 查看子命令用法`,
+    ].join('\n');
+}
+export function listCommands() {
+    return [...registry];
+}
+export function renderCommandHelp(command) {
+    const lines = [`用法: ${command.usage}`, `说明: ${command.description}`];
+    if (command.paramNotes && command.paramNotes.length > 0) {
+        lines.push('', '参数:');
+        lines.push(indentRows(renderRows(command.paramNotes)));
+    }
+    if (command.risk) {
+        const dangerHint = command.risk === 'danger' ? '（删除类操作先执行 yos docs count <node_code> 确认影响面）' : '';
+        lines.push('', `风险: ${RISK_LABEL[command.risk]}${dangerHint}`);
+    }
+    return lines.join('\n');
+}
+function indentRows(text) {
+    return text.split('\n').map((line) => `  ${line}`).join('\n');
+}
+function matchCommand(argv) {
+    const two = argv.slice(0, 2).join(' ');
+    const hit = registry.find((c) => c.name === two) ?? registry.find((c) => c.name === argv[0]);
+    if (!hit) {
+        return null;
+    }
+    return { command: hit, rest: argv.slice(hit.name.split(' ').length) };
+}
+const PARSE_ERROR_RULES = [
+    { pattern: /Unknown option '([^']+)'/, rewrite: (matched) => `未知参数 ${matched[1]}` },
+    { pattern: /Option '([^' ]+)(?: <[^>]+>)?' argument missing/, rewrite: (matched) => `参数 ${matched[1]} 缺少取值` },
+    {
+        pattern: /Option '([^' ]+)' argument is ambiguous/,
+        rewrite: (matched) => `参数 ${matched[1]} 的取值以 - 开头，需写成 ${matched[1]}=<值>`,
+    },
+    { pattern: /Unexpected argument '([^']+)'/, rewrite: (matched) => `该命令不接受位置参数：${matched[1]}` },
+];
+function parseCommandArgs(command, rest) {
+    try {
+        const parsed = parseArgs({
+            args: rest,
+            options: command.options ?? {},
+            strict: true,
+            allowPositionals: true,
+        });
+        return { positionals: parsed.positionals, flags: parsed.values };
+    }
+    catch (e) {
+        const detail = e instanceof Error ? e.message : String(e);
+        throw new UsageError(describeParseError(detail), buildUnknownOptionHint(command, rest) ?? `用法: ${command.usage}`);
+    }
+}
+export function describeParseError(detail) {
+    for (const rule of PARSE_ERROR_RULES) {
+        const matched = rule.pattern.exec(detail);
+        if (matched) {
+            return rule.rewrite(matched);
+        }
+    }
+    return '参数格式有误';
+}
+export function buildUnknownOptionHint(command, rest) {
+    const known = new Set(Object.keys(command.options ?? {}));
+    for (const token of rest) {
+        const matched = /^--([a-z0-9_-]+)(?:=|$)/.exec(token);
+        if (!matched || known.has(matched[1])) {
+            continue;
+        }
+        const alias = command.paramAlias?.[matched[1]];
+        if (alias) {
+            return `--${matched[1]} 是底层工具参数名，命令内请用 --${alias}（yos ${command.name} --help 查看完整参数）`;
+        }
+        return `yos ${command.name} --help 查看完整参数`;
+    }
+    return null;
+}
+export async function dispatch(argv) {
+    if (argv.length === 0 || argv[0] === '--help' || argv[0] === '-h') {
+        print(renderHelp());
+        return EXIT.OK;
+    }
+    const normalized = argv[0] === '--version' ? ['version', ...argv.slice(1)] : argv;
+    const matched = matchCommand(normalized);
+    if (!matched) {
+        const domainHelp = renderDomainHelp(argv[0]);
+        if (domainHelp) {
+            if (argv.length > 1 && !argv.includes('--help') && !argv.includes('-h')) {
+                printErr(`未知子命令: ${argv.slice(1).join(' ')}`);
+                printErr(domainHelp);
+                return EXIT.USAGE;
+            }
+            print(domainHelp);
+            return EXIT.OK;
+        }
+        printErr(`未知命令: ${argv.join(' ')}`);
+        printErr(renderHelp());
+        return EXIT.USAGE;
+    }
+    const { command, rest } = matched;
+    if (rest.includes('--help') || rest.includes('-h')) {
+        print(renderCommandHelp(command));
+        return EXIT.OK;
+    }
+    try {
+        const exitCode = await command.run(parseCommandArgs(command, rest));
+        return typeof exitCode === 'number' ? exitCode : EXIT.OK;
+    }
+    catch (error) {
+        if (error instanceof CliError) {
+            printErr(`错误: ${error.message}`);
+            if (error.hint) {
+                printErr(`提示: ${error.hint}`);
+            }
+            return error.exitCode;
+        }
+        printErr(`错误: ${error instanceof Error ? error.message : String(error)}`);
+        return EXIT.BUSINESS;
+    }
+}

package/dist/commands/context.js

@@ -0,0 +1,6 @@
+import { loadConfig, resolveEndpoint, resolveKey } from '../config.js';
+import { OpenApisClient } from '../openapis-client.js';
+export function clientFromConfig() {
+    const config = loadConfig();
+    return new OpenApisClient(`${resolveEndpoint(config)}/open-apis`, resolveKey(config));
+}

package/dist/commands/docs-download.js

@@ -0,0 +1,85 @@
+import { mkdir, open, stat } from 'node:fs/promises';
+import { basename, dirname, resolve as resolvePath } from 'node:path';
+import { register } from '../cli.js';
+import { BusinessError, EXIT, NetworkError, UsageError } from '../errors.js';
+import { parseToolJson } from '../openapis-client.js';
+import { print, printJson } from '../output.js';
+import { clientFromConfig } from './context.js';
+register({
+    name: 'docs download',
+    description: '下载文档原文件到本地（仅上传文件类型；需下载权限，只读角色不可下载）',
+    usage: 'yos docs download <node_code> [--out <本地路径>] [--json]',
+    group: '文档 docs',
+    risk: 'read',
+    options: {
+        out: { type: 'string' },
+        json: { type: 'boolean' },
+    },
+    paramNotes: [
+        ['<node_code>', '文档节点编码（docType=file）'],
+        ['--out', '保存路径：已存在的目录则按原文件名落盘，否则视为目标文件路径（缺省当前目录 + 原文件名）'],
+        ['--json', '结构化输出（nodeCode、fileName、savedPath、size）'],
+    ],
+    async run({ positionals, flags }) {
+        const nodeCode = positionals[0];
+        if (!nodeCode) {
+            throw new UsageError('缺少文档节点编码', '用法: yos docs download <node_code> [--out <本地路径>]；节点编码可用 `yos docs tree <kb_code>` 查看');
+        }
+        const json = flags.json === true;
+        const out = flags.out;
+        const result = await clientFromConfig().callTool('docs_download', { node_code: nodeCode });
+        if (result.isError) {
+            throw new BusinessError(result.text);
+        }
+        const payload = parseToolJson(result);
+        if (!payload.downloadUrl) {
+            throw new BusinessError(`服务未返回下载地址：nodeCode=${nodeCode}`);
+        }
+        const savedPath = resolvePath(await resolveDownloadPath(out, payload.fileName, nodeCode));
+        const size = await downloadToFile(payload.downloadUrl, savedPath);
+        if (json) {
+            printJson({ nodeCode, fileName: payload.fileName ?? null, savedPath, size });
+        }
+        else {
+            print(`已下载：${basename(savedPath)} → ${savedPath}（${size} 字节）`);
+        }
+        return EXIT.OK;
+    },
+});
+export async function resolveDownloadPath(out, fileName, nodeCode) {
+    const name = (fileName === undefined ? '' : basename(fileName).trim()) || nodeCode;
+    if (out === undefined) {
+        return name;
+    }
+    const isDir = (await stat(out).catch(() => undefined))?.isDirectory() === true;
+    return isDir ? resolvePath(out, name) : out;
+}
+async function downloadToFile(url, filePath) {
+    let response;
+    try {
+        response = await fetch(url);
+    }
+    catch (e) {
+        throw new NetworkError(`无法连接文件存储：${e.message}`);
+    }
+    if (!response.ok) {
+        throw new BusinessError(`文件下载失败：HTTP ${response.status}`, '预签名地址有时效，请重新执行 yos docs download 获取新地址');
+    }
+    if (!response.body) {
+        throw new BusinessError(`文件下载失败：响应无内容，url=${url.slice(0, 120)}`);
+    }
+    await mkdir(dirname(filePath), { recursive: true });
+    const handle = await open(filePath, 'w');
+    try {
+        let size = 0;
+        for await (const chunk of response.body) {
+            const bytes = chunk;
+            await handle.write(bytes);
+            size += bytes.byteLength;
+        }
+        return size;
+    }
+    finally {
+        await handle.close();
+    }
+}

package/dist/commands/doctor.js

@@ -0,0 +1,102 @@
+import { register } from '../cli.js';
+import { loadConfig, maskKey, resolveEndpoint, resolveKey } from '../config.js';
+import { CliError, EXIT } from '../errors.js';
+import { formatIdentity, OpenApisClient } from '../openapis-client.js';
+import { print, printJson } from '../output.js';
+import { readPackageMeta } from '../npm-meta.js';
+import { loadVersionState } from '../version-state.js';
+register({
+    name: 'doctor',
+    description: '诊断配置、访问令牌、连通、Skill 状态与 CLI 版本',
+    usage: 'yos doctor [--json]',
+    group: '基础',
+    options: { json: { type: 'boolean' } },
+    paramNotes: [['--json', '结构化输出（检查项列表）']],
+    async run({ flags }) {
+        const checks = [];
+        const config = loadConfig();
+        checks.push({
+            name: '配置文件',
+            ok: config !== null,
+            detail: config ? '已找到' : '未找到，请执行 yos login',
+        });
+        checks.push({
+            name: '服务端点',
+            ok: true,
+            detail: `${resolveEndpoint(config)}（来自 ${endpointSource(config)}）`,
+        });
+        let key = null;
+        try {
+            key = resolveKey(config);
+            checks.push({ name: '访问令牌', ok: true, detail: maskKey(key) });
+        }
+        catch (e) {
+            checks.push({ name: '访问令牌', ok: false, detail: e.message });
+        }
+        let connectionFailure = null;
+        if (!key) {
+            checks.push({ name: '服务连通', ok: false, detail: '未配置访问令牌，未验证（先执行 yos login）' });
+        }
+        else {
+            try {
+                const identity = await new OpenApisClient(`${resolveEndpoint(config)}/open-apis`, key).whoami();
+                checks.push({ name: '服务连通', ok: true, detail: `身份 ${formatIdentity(identity)}` });
+            }
+            catch (e) {
+                const failure = e instanceof CliError ? e : new CliError(String(e), EXIT.BUSINESS);
+                connectionFailure = failure;
+                checks.push({ name: '服务连通', ok: false, detail: failure.message });
+            }
+        }
+        const skillDirs = config?.installedSkillDirs ?? [];
+        checks.push({
+            name: 'Skill 安装',
+            ok: skillDirs.length > 0,
+            detail: skillDirs.length > 0 ? skillDirs.join(', ') : '尚未安装，执行 yos skill install',
+        });
+        const meta = readPackageMeta();
+        checks.push({
+            name: 'CLI 版本',
+            ok: meta !== null,
+            detail: meta ? `${meta.version}（endpoint=${resolveEndpoint(config)}）` : 'unknown（未找到 package.json）',
+        });
+        const state = loadVersionState();
+        checks.push({
+            name: 'Skill 同步',
+            ok: meta !== null && state?.version === meta.version && skillDirs.length > 0,
+            detail: skillSyncDetail(meta, state, skillDirs),
+        });
+        if (flags.json) {
+            printJson({ checks });
+        }
+        else {
+            print(checks.map((c) => `${c.ok ? '✓' : '✗'} ${c.name}: ${c.detail}`).join('\n'));
+        }
+        const firstFail = checks.find((c) => !c.ok);
+        if (!firstFail) {
+            return EXIT.OK;
+        }
+        return connectionFailure?.exitCode ?? EXIT.USAGE;
+    },
+});
+function endpointSource(config) {
+    if (process.env.YOS_ENDPOINT) {
+        return 'YOS_ENDPOINT';
+    }
+    return config?.endpoint ? '配置文件' : '内置缺省';
+}
+function skillSyncDetail(meta, state, skillDirs) {
+    if (skillDirs.length === 0) {
+        return '尚未安装，执行 yos skill install';
+    }
+    if (meta === null) {
+        return '无法比对（CLI 版本未知）';
+    }
+    if (state === null) {
+        return `缺少版本状态（Skill 目录 ${skillDirs.length} 个），执行 yos update 重同步`;
+    }
+    if (state.version === meta.version) {
+        return `与 CLI 一致（${skillDirs.length} 个目录）`;
+    }
+    return `Skill 与 CLI 版本不一致（状态 ${state.version}，CLI ${meta.version}），执行 yos update`;
+}

package/dist/commands/domain.js

@@ -0,0 +1,16 @@
+import { register } from '../cli.js';
+import { DOMAIN_COMMANDS, DOMAIN_META } from '../domain-commands.js';
+import { buildOptionsForSpec, buildParamAliasForSpec, buildParamNotesForSpec, buildUsageForSpec, runDomainCommand } from '../domain-executor.js';
+for (const spec of DOMAIN_COMMANDS) {
+    register({
+        name: spec.name,
+        description: spec.description,
+        usage: buildUsageForSpec(spec),
+        group: DOMAIN_META[spec.domain].groupLabel,
+        risk: spec.risk,
+        options: buildOptionsForSpec(spec),
+        paramNotes: buildParamNotesForSpec(spec),
+        paramAlias: buildParamAliasForSpec(spec),
+        run: (context) => runDomainCommand(spec, context),
+    });
+}