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

package/dist/skills/yos-support/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: yos-support
+description: YOS 帮助与支持（manual/manual-read/manual-search 帮助手册，upgrade/upgrade-log 客户端版本，feedback 提交反馈）。用户问 YOS 怎么用、要客户端最新版本、要报问题时使用
+---
+
+# YOS 帮助与支持（support）
+
+五个只读命令 + 一个写命令。手册回答「YOS 怎么用」，`upgrade*` 回答「客户端最新版是什么」，`feedback` 把诉求登记给客服。
+
+**领域内 ID 精度坑（三条命令都涉及）**：`manual` 目录树里的 `id` 是**带引号的字符串**，可安全使用；`manual-read` 与 `manual-search` 返回的 `id` 是**无引号的 19 位数字**，一旦 `JSON.parse` 就丢精度（`2100513671581945858` → `2100513671581945900`）。因此节点 ID 一律**从 `yos support manual` 的目录树取**，不要把 search/read 输出解析后再回传给 `manual-read`。
+
+## 1. `support manual` — 手册目录树（先调这个）
+
+```bash
+yos support manual            # 无参数，返回完整树
+```
+
+真实响应（数组，非分页壳）：
+
+```json
+[{"id":"2100511993159897090","parentId":null,"type":"FOLDER","title":"开始使用","sortOrder":0,
+  "children":[{"id":"2100513671581945858","parentId":"2100511993159897090","type":"FILE","title":"YOS 是什么","sortOrder":0,"children":[]},
+              {"id":"2100511408478113794","type":"FILE","title":"快速开始","sortOrder":1,"children":[]}]}]
+```
+
+- `type`：`FOLDER`（无正文）/ `FILE`（文章）。只有 `FILE` 的 `id` 能传给 `manual-read`
+- 递归字段是 `children`（叶子为 `[]`，不是 `null`）；`parentId` 顶层为 `null`
+- 全文目录一次性返回，没有分页参数、没有关键字过滤 → 想按标题找文章就在本地遍历 `title`，或直接改用 `manual-search`
+
+## 2. `support manual-read <node_id>` — 读文章正文
+
+```bash
+yos support manual-read 2100513671581945858        # 「YOS 是什么」
+```
+
+| 位置参数 | 工具参数 | 说明 |
+|---|---|---|
+| `<node_id>` | `node_id` | 文章节点 ID，来自 `manual` 目录树的 `id` 字段（字符串那一份） |
+
+正常响应：
+
+```json
+{"id":2100513671581945858,"type":"FILE","title":"YOS 是什么","content":"YOS 是渝欧数智自主研发的企业级 AI 操作系统，……"}
+```
+
+- `content` 是**富文本清洗后的纯文本**：没有 Markdown 标题符号、列表符号和图片地址，向用户复述时可直接引用，但不要承诺格式还原
+- 传 `FOLDER` 节点的 ID **不报错（exit 0）**，返回 `{"id":…,"type":"FOLDER","title":"开始使用","content":"","message":"文件夹无正文，请根据目录树选择其下的文章节点"}` → 见到 `content:""` 就回目录树换 `FILE` 节点，别重复请求
+- ID 不存在：`工具执行失败：帮助手册节点不存在：999`（exit 1）→ 说明 ID 取错或精度已丢，重新从 `manual` 取
+
+## 3. `support manual-search <keyword>` — 关键词检索
+
+```bash
+yos support manual-search 登录
+yos support manual-search 知识库
+```
+
+| 位置参数 | 工具参数 | 说明 |
+|---|---|---|
+| `<keyword>` | `keyword` | 单个关键词。标题或正文命中其一即算，大小写不敏感；**没有分词/多词/正则能力** |
+
+真实响应：
+
+```json
+{"keyword":"登录","total":6,"records":[
+  {"id":2100513705551613953,"title":"常见问题","path":"帮助","snippet":"按主题分组。找不到答案时，通过问题反馈提交。\n\n安装与登录\n\n下载被浏览器拦截\n\n用 Chrome 下载；提示有害时点击 操作 → 保留 → …"}]}
+```
+
+- `path` 是**所在目录名**（如 `帮助`），不是完整路径链；要层级关系回到 `manual` 树里查
+- `snippet` 是正文摘录，**不等于全文**：确定要引用的操作细节必须再用 `manual-read`（ID 从 `manual` 取）
+- 实测各主题命中量：`转写=10`、`更新=9`、`设置=8`、`版本=7`、`登录=6`、`知识库=5`、`上传=4`
+- **`total:0` 是常见结论，不是失败**：实测 `令牌` 和 `访问令牌` 都是 `0`（手册里没有访问令牌主题）。此时直接按 `yos` 总入口的登录步骤回答（客户端「个人设置-访问令牌」），不要反复换近义词空转
+- 检索是**子串式关键词匹配**：`--` 之类符号、英文短语（`MCP`）请按用户原词与可能的中英文写法各试一次，两次为 `0` 就停手走 `feedback`
+
+## 4. `support upgrade` / `support upgrade-log` — 客户端版本
+
+```bash
+yos support upgrade --platform MAC_ARM64                     # 该平台对当前用户可见的最新版
+yos support upgrade-log                                       # 全部升级记录（新发布在前）
+yos support upgrade-log --platform WIN --page 1 --size 5
+yos support upgrade-log --start 2026-10-01 --end 2026-10-10   # 按发布日期区间
+```
+
+| flag | 工具参数 | 说明 | 缺省 |
+|---|---|---|---|
+| `--platform` | `platform` | `upgrade` **必填**；`upgrade-log` 可选（不传=全平台）。取值只有 `WIN` / `MAC_X64` / `MAC_ARM64`，**没有 LINUX** | — |
+| `--start` / `--end` | `start_date` / `end_date` | 严格 `yyyy-MM-dd`，含当日；中文时间表达需自行换算。格式非法 → `错误: --start 日期格式应为 yyyy-MM-dd：本周`；起晚于止 → `错误: 日期区间非法：--start 晚于 --end`（均 exit 2） | 不过滤 |
+| `--page` / `--size` | `page` / `size` | `size` 1~50，越界 → `错误: --size 低于下限 1：0` + `提示: 取值范围 1~50`（exit 2） | 1 / 10 |
+
+真实响应：
+
+```json
+// upgrade
+{"id":"2108510276780978177","version":"v0.2.0-test.14","platform":"MAC_ARM64","platformName":"macOS Apple Silicon 版",
+ "releaseDate":"2026-10-09","isForceUpdate":false,"content":null}
+
+// upgrade-log
+{"records":[{"id":"2108722559616446465","version":"v0.2.0-test.14","platform":"WIN","platformName":"Windows",
+             "releaseDate":"2026-10-10","isForceUpdate":false,"content":""}],
+ "total":107,"page":1,"size":2}
+```
+
+- 平台取值只有三个，写错由 CLI 本地拦下（不发请求，exit 2）：`错误: --platform 取值非法：NOSUCH` + `提示: 可选：WIN / MAC_X64 / MAC_ARM64`；`upgrade` 漏传 → `错误: 缺少 --platform`（exit 2）
+- `content` 是**公告全文纯文本**，但**可能为 `null` 或 `""`**（实测两平台同版本一为 `null` 一为 `""`）→ 没有公告时只报版本号与日期，不要编造更新内容；用户问「更新了什么」就换 `upgrade-log` 找有公告的记录
+- `upgrade` 只给三平台的当前可见最新版，**灰度中的版本仅白名单用户可见**：用户说「同事有 x 版本我没有」时，先 `upgrade-log` 确认该版本是否存在，再解释灰度，不要判定为版本不存在
+- `isForceUpdate` 对应客户端是否强制更新，回答升级建议时值得带上
+- 返回的 `version` 是 **YOS 桌面客户端**版本（形如 `v0.2.0-test.14`，测试环境带 `-test`），与 `@yosai/cli` 自身的 npm 版本是两回事（CLI 自身版本用 `yos version` 查），不要混用
+
+## 5. `support feedback '<内容>'` — 提交反馈（写操作）
+
+```bash
+yos support feedback '知识库上传 20MB 以上的 PDF 会失败，希望支持大文件分片'
+yos support feedback -- '转写结果说话人识别不准，希望提供纠错入口'      # 内容以 - 开头时必须加 --
+```
+
+- 位置参数 `content`（variadic，多个位置参数以空格拼接为一个字符串），上限 **2000 字**
+- **写入类操作**：内容会自动关联当前用户与其所属企业并进入客服工单流程。调用前必须把最终原文给用户看过并取得明确同意
+- 空内容：`错误: 反馈内容不能为空` + `提示: 用法: yos support feedback <内容...>`（exit 2）；超 2000 字：`错误: 反馈内容超长（实际 2001 字，上限 2000 字）`（exit 2）→ 压缩为一条诉求或拆成多次提交（先问用户）
+- 成功：`反馈提交成功，反馈编号：2108742524868513794` → 把编号回给用户，这是唯一可追溯凭证
+- **编号无法再查询**：CLI 没有反馈详情/进度/撤回命令，提交后不要承诺「帮你跟进这条反馈的状态」
+- 无附件：日志、截图只能靠用户在客户端内提交，CLI 路径只收文本
+
+## 6. 标准流程
+
+```bash
+# 用户问「YOS 怎么用 / X 功能在哪」
+yos support manual-search '<关键词>'        # 1. 定位候选文章
+yos support manual                          # 2. 从目录树取该文章 id（字符串形态那份）
+yos support manual-read <FILE 节点 id>       # 3. 读正文后再回答
+
+# 用户问「客户端最新版本 / 更新了什么」
+yos support upgrade --platform MAC_ARM64     # 单平台最新版
+yos support upgrade-log --platform MAC_ARM64 --size 5   # 公告 content 为 null 时改查这里
+
+# 用户报问题或提诉求
+先 manual-search 确认不是已有文档的用法问题 → 把手册答案给用户
+确认为缺陷/新需求 → 与用户确认原文 → yos support feedback '<原文>'
+```
+
+## 7. 做不到的事
+
+不提供手册编辑/新增；不把 `path` 展开为完整目录链；不按功能名反查版本号（只能按平台/日期过滤后人工比对公告）；不下载客户端安装包；不查询反馈进度、不撤回反馈；反馈不带附件。有这类诉求时说明边界，并可用 `yos support feedback` 登记。

package/dist/skills/yos-transcript/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: yos-transcript
+description: YOS 录音转写查询（transcript list 列表 / transcript detail 详情，含分段、纪要、思维导图、音频地址与字段坑）。用户想看会议录音转写、要纪要、查某次会议内容时使用
+---
+
+# YOS 录音转写（transcript）
+
+只读两个命令：`list` 拿记录 ID，`detail` 拿全文。**CLI 不提供转写正文的检索入口**，`retrieve` 域查不到会议内容。
+
+## 1. `transcript list` — 我的转写
+
+```bash
+yos transcript list                                    # 第 1 页，10 条
+yos transcript list --json                             # 需要 transcriptionUserId 时必须用这个
+yos transcript list --keyword 节前周会 --json           # 只匹配标题（不搜正文）
+yos transcript list --relation owner --json            # owner=我建的 / shared=别人分享的
+yos transcript list --start 2026-09-28 --end 2026-10-10 --json   # 必须 yyyy-MM-dd
+yos transcript list --page 2 --size 20 --json          # size 上限 50
+yos transcript list --status summarized --json          # 状态过滤（合法值见下）
+```
+
+| flag | 工具参数 | 说明 | 缺省 |
+|---|---|---|---|
+| `--page` | `page` | ≥1 | 1 |
+| `--size` | `size` | 每页条数，1~50；越界 → `错误: --size 超过上限 50：1000`（exit 2） | 10 |
+| `--status` | `status` | `recording`（录制中/转写中）\| `recorded`（待总结）\| `summarizing`（总结中）\| `summarized`（总结完成，实测 `statusName: 总结完成`）。非法值 → `错误: --status 取值非法：xxx` + `提示: 可选：recording / recorded / summarizing / summarized`（exit 2） | 不过滤 |
+| `--relation` | `relation_type` | `owner`（我创建）\| `shared`（他人分享给我）\| `all`（实测记录里 `relationType: "owner"`）。非法值 → exit 2 | `all` |
+| `--keyword` | `keyword` | **只按标题匹配**，正文/纪要里的词搜不到（实测：某词在纪要 JSON 中出现 6 次，但 `--keyword` 结果 `total=0`） | 无 |
+| `--start` / `--end` | `start_date` / `end_date` | 格式严格 `yyyy-MM-dd`，含当日；中文时间表达由 CLI 本地拒绝：`错误: --start 日期格式应为 yyyy-MM-dd：本周`；起晚于止 → `错误: 日期区间非法：--start 晚于 --end` + `提示: 起 … 应不晚于止 …`（均 exit 2，不发请求） | 无 |
+
+真实响应（注意：分页壳与 `kb list` 不同，用 `list` 字段而非 `records`）：
+
+```json
+{"current":1,"size":10,"pages":7,"total":67,"list":[
+  {"transcriptionUserId":"2105108032979103745","transcriptionCode":"TT00006601","title":"节前周会",
+   "transcriptionType":"realtime","status":"summarized","statusName":"总结完成",
+   "totalDurationMs":1778346,"createTime":"2026-09-30 09:30:40","creatorName":"张三","relationType":"owner"}]}
+```
+
+- 列表字段是 **`list`**，分页字段为 `current` / `size` / `pages` / `total`（`pages` 即总页数）；与 `kb list` / `upgrade-log` 的 `records` / `page` 壳不同，解析时不要套用
+- `transcriptionType` 实测值 `realtime`（实时录音）；时长 `totalDurationMs` 是毫秒，向用户表述要换算成分钟
+- **失败状态的记录恒被服务端排除**，在 CLI 里永远看不到，用户问「今天那个转写失败的会议」时直接说明该记录不可见，不要反复换过滤条件找
+- 不加 `--json` 也输出同一段 JSON 原文（本域没有人类渲染）
+
+## 2. `transcript detail` — 取全文与纪要
+
+```bash
+yos transcript detail 2105108032979103745 --json
+```
+
+位置参数是 **`transcriptionUserId`（19 位纯数字，来自返回体 `list[].transcriptionUserId` 字段）**，不是 `TT` 开头的 `transcriptionCode`：
+
+```
+$ yos transcript detail TT00006601
+错误: 转写归属记录 ID 需为数字，实际收到：TT00006601
+提示: TT 开头的是转写编码，本命令需要对应的数字 ID                 # exit 2，不发请求
+```
+
+真实响应字段（`--json` 二次解析后）：
+
+| 字段 | 形态与用途 |
+|---|---|
+| `summary` | **Markdown 字符串**（实测 3202 字），结构为「一、核心结论 / 二、整体概述 / 关键决策展开」。可直接落盘或摘录，是回答「这次会说了什么」的首选 |
+| `sentences[]` | 逐句：`globalStartMs` / `globalEndMs` / `speakerName` / `speakerLabel` / 文本。实测某会议 154 句 |
+| `speakers[]` | 仅 `userCode` / `userName` |
+| `mindMap` | **双重编码 JSON 字符串**（形如 `"{\"children\":[...]}"`），需再 `JSON.parse` 一次才能用；不解析就当它是空 |
+| `audioUrl` | COS 预签名下载地址（原音频可下载，注意有效期） |
+| `transcriptionCode` / `title` / `status` | 与 list 一致 |
+
+说话人可信度（表述时必须带保留）：
+
+- `speakerLabel`（声纹聚类编号）与人名是**多对多**：实测 label `3` 同时对应「张三/李四/王五/说话人」四个名字，label `1` 对应三个
+- 实测 154 句里 **41 句（27%）`speakerName` 是未解析的「说话人」**
+- 没有 `speakerLabel ↔ userCode` 的映射字段，也没有按说话人/时间戳过滤的参数：要「某人说了什么」就拉全量 `sentences` 在本地按 `speakerName` 过滤，并向用户说明未识别句段可能存在
+- 说话人纠错、纪要编辑 CLI 都不支持（转写域仅两个工具），需要改动请引导用户到客户端
+
+非「已完成」状态的转写调 `detail` 会被服务端拒绝（转写中/失败不可读）。
+
+## 3. 标准流程
+
+```bash
+yos transcript list --json                                  # 1. 取 transcriptionUserId
+yos transcript list --keyword '<标题关键词>' --json          #    或按标题缩小；--start/--end 缩小日期范围
+yos transcript detail 2105108032979103745 --json             # 2. 取纪要与逐句
+#                                          3. 回答：先给 summary 要点，需举证时引用 sentences 的毫秒时间戳（换算成 mm:ss）
+```
+
+「最近一次会议」= `list` 首条（实测按时间新在前），但用户给的是主题词时优先 `--keyword` + 标题人工确认，不要凭顺序猜是哪场会。
+
+## 4. 做不到的事
+
+不检索转写正文（`--keyword` 只搜标题）；不按说话人或时间点过滤；不导出（自行把 `summary` 落盘）；不查询转写进度；不纠错说话人、不改纪要；看不到失败记录。有这类诉求用 `yos support feedback '<诉求>'` 记录。

package/dist/tool-domains.js

@@ -0,0 +1,38 @@
+const DOMAIN_ORDER = [
+    '知识库管理',
+    'cortex 检索原语',
+    '帮助手册与客户端升级',
+    '转写查询',
+    '用户反馈',
+    '其他',
+];
+function matchDomain(name) {
+    if (name.startsWith('retrieve_')) {
+        return 'cortex 检索原语';
+    }
+    if (name.startsWith('kb_') || name.startsWith('docs_')) {
+        return '知识库管理';
+    }
+    if (name.startsWith('support_feedback')) {
+        return '用户反馈';
+    }
+    if (name.startsWith('support_')) {
+        return '帮助手册与客户端升级';
+    }
+    if (name.startsWith('transcript_')) {
+        return '转写查询';
+    }
+    return '其他';
+}
+export function groupTools(tools) {
+    const buckets = new Map();
+    for (const tool of tools) {
+        const domain = matchDomain(tool.name);
+        const list = buckets.get(domain) ?? [];
+        list.push(tool);
+        buckets.set(domain, list);
+    }
+    return DOMAIN_ORDER
+        .map((domain) => ({ domain, tools: buckets.get(domain) ?? [] }))
+        .filter((group) => group.tools.length > 0);
+}

package/dist/version-state.js

@@ -0,0 +1,30 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { configDir } from './config.js';
+function versionStatePath() {
+    return join(configDir(), 'version-state');
+}
+export function loadVersionState() {
+    const path = versionStatePath();
+    if (!existsSync(path)) {
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf8'));
+        if (typeof parsed.version !== 'string' || parsed.version === '') {
+            return null;
+        }
+        return {
+            version: parsed.version,
+            updatedAt: typeof parsed.updatedAt === 'string' ? parsed.updatedAt : '',
+        };
+    }
+    catch {
+        return null;
+    }
+}
+export function saveVersionState(version) {
+    mkdirSync(configDir(), { recursive: true, mode: 0o700 });
+    const state = { version, updatedAt: new Date().toISOString() };
+    writeFileSync(versionStatePath(), `${JSON.stringify(state, null, 2)}\n`, { mode: 0o600 });
+}

package/package.json

@@ -1,6 +1,32 @@
 {
   "name": "@yosai/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.1-test.0",
+  "description": "YOS 能力的 Agent 执行入口：工具调用、知识库管理与文件上传",
+  "type": "module",
+  "bin": {
+    "yos": "dist/index.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc && node scripts/copy-assets.mjs && chmod +x dist/index.js",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "release": "node scripts/release.mjs"
+  },
+  "license": "Apache-2.0",
+  "private": false,
+  "devDependencies": {
+    "@types/node": "^26.6.3",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.2"
+  }
+}