@yosai/cli 0.2.1-test.14 → 0.2.1-test.15

package/README.md

@@ -45,7 +45,7 @@ yos tool list                      # 底层工具通道（领域命令未覆盖
 ## 给 Agent 使用
 
 ```bash
-yos skill install      # 安装 9 个内置 Skill（总入口 + 领域 + 安装引导）到 Claude Code / Cursor / Codex / Qoder / WorkBuddy 等技能目录
+yos skill install      # 按当前令牌权限安装内置 Skill（总入口 + 领域 + 安装引导）到 Claude Code / Cursor / Codex / Qoder / WorkBuddy 等技能目录
 ```
 
 安装后重启 Agent 工具，即可用自然语言驱动（如「把这份报告上传到知识库」）。`yos` 为能力总入口（何时使用 / 能力地图 / 命令使用方式），Agent 据此路由到各领域细则；`yos-shared` 收录跨领域约定（输出解析、退出码契约、仍需自行校验内容的场景、安全纪律）；`yos-install` 是自包含的安装配置引导，可单独下载到发布仓库供用户引导装机。
@@ -58,6 +58,7 @@ yos skill install      # 安装 9 个内置 Skill（总入口 + 领域 + 安装
 - 环境变量（均优先于配置文件，适合 CI/容器场景）：`YOS_API_KEY` 访问令牌、`YOS_ENV` 服务环境（prod / test / dev）
 - 版本检查：命令执行前会检查对应通道最新版（后台进程查询、结果缓存 10 分钟），落后时以 stderr 提示「请先执行 yos update 升级再继续任务」；升级通道自动跟随服务环境（测试环境跟 test 通道）。CLI 不静默安装，升级由用户或 Agent 按提示显式执行
 - 服务环境（测试/开发用）：`yos login --env test` 切到测试环境，`--env dev` 指向本机开发服务（http://localhost:8080）
+- Skill 按令牌权限安装：`yos login` / `yos skill install` 从 `whoami` 取令牌 scope 并缓存，只安装有权限的技能（外部令牌仅 `yos`、`yos-shared`、`yos-install`、`yos-retrieval`），并按 scope 裁剪技能正文中无权限的段落；换令牌登录后自动重新同步，`yos doctor` 的「Skill 权限」项校验一致性。技能源文件用 `<!-- @scope a,b -->` / `<!-- @else -->` / `<!-- @end -->`（frontmatter 内用 `# @scope …` 注释形式）标记受限段落，新增技能须在 `src/skill-scope.ts` 登记所需 scope
 - 托管模式（YOS 客户端内置 CLI 专用）：`YOS_MANAGED=1` 时安装、升级、登录与 Skill 由客户端统一管理——不做版本检查与升级提示，拒绝 `update` / `install` / `login` / `skill install`，令牌只认客户端注入的 `YOS_API_KEY`（不读配置文件），`doctor` 跳过配置文件与 Skill 检查；客户端应同时以 `YOS_CONFIG_DIR` 指向自身私有目录，与用户自行安装的 CLI 配置隔离
 
 ## 故障排查

package/dist/commands/doctor.js

@@ -6,6 +6,8 @@ import { isManaged } from '../managed.js';
 import { formatIdentity, OpenApisClient } from '../openapis-client.js';
 import { print, printJson } from '../output.js';
 import { readPackageMeta } from '../npm-meta.js';
+import { describeScopes, isSkillAllowed } from '../skill-scope.js';
+import { listInstalledSkills, listSourceSkills } from '../skill-sync.js';
 import { loadVersionState } from '../version-state.js';
 register({
     name: 'doctor',
@@ -39,13 +41,18 @@ register({
             checks.push({ name: '访问令牌', ok: false, detail: e.message });
         }
         let connectionFailure = null;
+        let identity = null;
         if (!key) {
             checks.push({ name: '服务连通', ok: false, detail: '未配置访问令牌，未验证（先执行 yos login）' });
         }
         else {
             try {
-                const identity = await new OpenApisClient(`${endpoint}/open-apis`, key).whoami();
-                checks.push({ name: '服务连通', ok: true, detail: `身份 ${formatIdentity(identity)}` });
+                identity = await new OpenApisClient(`${endpoint}/open-apis`, key).whoami();
+                checks.push({
+                    name: '服务连通',
+                    ok: true,
+                    detail: `身份 ${formatIdentity(identity)}，${describeScopes(identity.tokenType, identity.scopes ?? null)}`,
+                });
             }
             catch (e) {
                 const failure = e instanceof CliError ? e : new CliError(String(e), EXIT.BUSINESS);
@@ -76,6 +83,18 @@ register({
                 detail: skillSyncDetail(meta, state, skillDirs),
             });
         }
+        if (!managed && identity && skillDirs.length > 0) {
+            const scopes = identity.scopes ?? null;
+            const expected = listSourceSkills().filter((skill) => isSkillAllowed(skill, scopes));
+            const mismatched = skillDirs.filter((dir) => listInstalledSkills(dir).join(',') !== expected.join(','));
+            checks.push({
+                name: 'Skill 权限',
+                ok: mismatched.length === 0,
+                detail: mismatched.length === 0
+                    ? `与令牌权限一致（${expected.length} 个 Skill）`
+                    : `${mismatched.length} 个目录的 Skill 与令牌权限不一致，执行 yos skill install`,
+            });
+        }
         if (flags.json) {
             printJson({ checks });
         }

package/dist/commands/login.js

@@ -5,6 +5,8 @@ import { UsageError } from '../errors.js';
 import { formatIdentity, OpenApisClient } from '../openapis-client.js';
 import { print } from '../output.js';
 import { readHiddenLine } from '../prompt.js';
+import { describeScopes } from '../skill-scope.js';
+import { installSkillsTo } from '../skill-sync.js';
 register({
     name: 'login',
     description: '配置访问令牌与服务环境（校验身份后保存）',
@@ -29,8 +31,14 @@ register({
             throw new UsageError('令牌格式不正确（应为 40 位小写 hex）', '请在客户端「个人设置-访问令牌」页创建并复制完整令牌');
         }
         const identity = await new OpenApisClient(`${endpoint}/open-apis`, key).whoami();
-        saveConfig({ ...config, env, apiKey: key });
+        saveConfig({ ...config, env, apiKey: key, tokenType: identity.tokenType, scopes: identity.scopes });
         const envNote = env === DEFAULT_ENV ? '' : `环境=${envLabel(env)}，`;
-        print(`已保存配置：${envNote}key=${maskKey(key)}，身份 ${formatIdentity(identity)}`);
+        const scopes = identity.scopes ?? null;
+        print(`已保存配置：${envNote}key=${maskKey(key)}，身份 ${formatIdentity(identity)}，${describeScopes(identity.tokenType, scopes)}`);
+        const skillDirs = config?.installedSkillDirs ?? [];
+        if (skillDirs.length > 0) {
+            const skills = installSkillsTo(skillDirs, scopes);
+            print(`已按新令牌权限重新同步 ${skills.length} 个 Skill，重启 Agent 工具后生效`);
+        }
     },
 });

package/dist/commands/skill.js

@@ -1,6 +1,8 @@
 import { register } from '../cli.js';
 import { UsageError } from '../errors.js';
 import { print } from '../output.js';
+import { loadConfig } from '../config.js';
+import { describeScopes, resolveSkillScopes } from '../skill-scope.js';
 import { detectSkillTargets, installSkillsTo } from '../skill-sync.js';
 register({
     name: 'skill install',
@@ -15,8 +17,9 @@ register({
         if (targets.length === 0) {
             throw new UsageError('未发现已安装的 Agent 技能目录', '请用 --target <dir> 指定（如 ~/.claude/skills）');
         }
-        const skills = installSkillsTo(targets);
-        print(`已安装 ${skills.length} 个 Skill 到：\n${targets.join('\n')}`);
+        const scopes = await resolveSkillScopes();
+        const skills = installSkillsTo(targets, scopes);
+        print(`已安装 ${skills.length} 个 Skill（${describeScopes(loadConfig()?.tokenType, scopes)}）到：\n${targets.join('\n')}`);
         print('提示：重启 Agent 工具以确保 Skill 加载');
     },
 });

package/dist/commands/update.js

@@ -4,6 +4,7 @@ import { BusinessError } from '../errors.js';
 import { ensureVersionExists, INSTALLABLE_VERSION, installGlobal } from '../npm-install.js';
 import { compareVersions, detectGlobalInstall, fetchLatestVersion, PUBLIC_REGISTRY, readPackageMeta, resolveInstallPrefix } from '../npm-meta.js';
 import { print, printJson } from '../output.js';
+import { resolveSkillScopes } from '../skill-scope.js';
 import { installSkillsTo } from '../skill-sync.js';
 import { saveVersionState } from '../version-state.js';
 register({
@@ -45,13 +46,13 @@ register({
             return;
         }
         if (!outdated) {
-            syncSkills();
+            await syncSkills();
             saveVersionState(meta.version);
             print(`已是最新（${meta.version}）`);
             return;
         }
         await installGlobally(meta, `${meta.name}@${channel}`);
-        syncSkills();
+        await syncSkills();
         saveVersionState(latest);
         print(`已升级 ${meta.version} → ${latest}`);
         print('提示：重启 Agent 工具以加载刷新后的 Skill');
@@ -62,14 +63,14 @@ async function installVersion(meta, version) {
         throw new BusinessError(`版本格式非法：${version}`, '示例：0.2.0 或 0.2.1-test.9；安装通道最新版请直接执行 yos update');
     }
     if (compareVersions(version, meta.version) === 0) {
-        syncSkills();
+        await syncSkills();
         saveVersionState(meta.version);
         print(`已是指定版本（${version}）`);
         return;
     }
     await ensureVersionExists(meta.name, version);
     await installGlobally(meta, `${meta.name}@${version}`);
-    syncSkills();
+    await syncSkills();
     saveVersionState(version);
     print(`${compareVersions(version, meta.version) > 0 ? '已升级' : '已回退'} ${meta.version} → ${version}`);
     print('提示：重启 Agent 工具以加载刷新后的 Skill');
@@ -87,14 +88,23 @@ async function installGlobally(meta, spec) {
     }
     await installGlobal(spec);
 }
-function syncSkills() {
+async function syncSkills() {
     const dirs = loadConfig()?.installedSkillDirs ?? [];
     if (dirs.length === 0) {
         print('未记录 Skill 安装目录，跳过 Skill 同步（需要时执行 yos skill install）');
         return;
     }
+    let scopes;
     try {
-        installSkillsTo(dirs);
+        scopes = await resolveSkillScopes();
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        print(`无法确认令牌权限，跳过 Skill 同步（${reason}），恢复后执行 yos skill install`);
+        return;
+    }
+    try {
+        installSkillsTo(dirs, scopes);
     }
     catch (error) {
         const reason = error instanceof Error ? error.message : String(error);

package/dist/skill-scope.js

@@ -0,0 +1,111 @@
+import { endpointOfEnv } from './endpoints.js';
+import { AuthError, UsageError } from './errors.js';
+import { loadConfig, resolveEnv, resolveKey, updateConfig } from './config.js';
+import { OpenApisClient } from './openapis-client.js';
+export const ALL_SCOPES = ['knowledge:retrieve', 'knowledge:manage', 'transcript:read', 'support'];
+const SKILL_SCOPES = {
+    yos: null,
+    'yos-shared': null,
+    'yos-install': null,
+    'yos-retrieval': 'knowledge:retrieve',
+    'yos-knowledge': 'knowledge:manage',
+    'yos-doc': 'knowledge:manage',
+    'yos-sheet': 'knowledge:manage',
+    'yos-transcript': 'transcript:read',
+    'yos-support': 'support',
+};
+const SCOPE_LABEL = {
+    'knowledge:retrieve': '知识库检索',
+    'knowledge:manage': '知识库管理',
+    'transcript:read': '转写查询',
+    support: '帮助与支持',
+};
+const TOKEN_TYPE_LABEL = { EXTERNAL: '外部令牌', INTERNAL: '内置令牌' };
+const BODY_MARKER = /^\s*<!--\s*@(scope|else|end)\b\s*(.*?)\s*-->\s*$/;
+const FRONTMATTER_MARKER = /^\s*#\s*@(scope|else|end)\b\s*(.*?)\s*$/;
+export function isSkillAllowed(skill, scopes) {
+    if (scopes === null) {
+        return true;
+    }
+    if (!(skill in SKILL_SCOPES)) {
+        return ALL_SCOPES.every((scope) => scopes.includes(scope));
+    }
+    const required = SKILL_SCOPES[skill];
+    return required === null || scopes.includes(required);
+}
+export function renderScoped(text, scopes) {
+    const lines = text.split('\n');
+    const output = [];
+    let inFrontmatter = lines[0]?.trim() === '---';
+    let block = null;
+    lines.forEach((line, index) => {
+        if (inFrontmatter && index > 0 && line.trim() === '---') {
+            inFrontmatter = false;
+        }
+        const matched = (inFrontmatter ? FRONTMATTER_MARKER : BODY_MARKER).exec(line);
+        if (matched) {
+            const [, kind, args] = matched;
+            if (kind === 'scope') {
+                if (block) {
+                    throw new Error(`Skill 标记不支持嵌套（第 ${index + 1} 行）`);
+                }
+                const required = args.split(',').map((scope) => scope.trim()).filter(Boolean);
+                block = { satisfied: scopes === null || required.some((scope) => scopes.includes(scope)), inElse: false };
+            }
+            else if (!block) {
+                throw new Error(`Skill 标记 @${kind} 缺少对应的 @scope（第 ${index + 1} 行）`);
+            }
+            else if (kind === 'else') {
+                block.inElse = true;
+            }
+            else {
+                block = null;
+            }
+            return;
+        }
+        if (block && block.inElse === block.satisfied) {
+            return;
+        }
+        output.push(block?.inElse && inFrontmatter ? line.replace(/^(\s*)# /, '$1') : line);
+    });
+    if (block) {
+        throw new Error('Skill 标记 @scope 未闭合（缺少 @end）');
+    }
+    return output.join('\n');
+}
+export function describeScopes(tokenType, scopes) {
+    const typeLabel = (tokenType && TOKEN_TYPE_LABEL[tokenType]) ?? '令牌';
+    if (scopes === null) {
+        return `${typeLabel}（全部能力）`;
+    }
+    const labels = scopes.map((scope) => SCOPE_LABEL[scope] ?? scope);
+    return `${typeLabel}（${labels.length > 0 ? labels.join('、') : '无可用能力'}）`;
+}
+export async function resolveSkillScopes() {
+    const config = loadConfig();
+    let key = null;
+    try {
+        key = resolveKey(config);
+    }
+    catch {
+        key = null;
+    }
+    if (key) {
+        try {
+            const endpoint = endpointOfEnv(resolveEnv(config));
+            const identity = await new OpenApisClient(`${endpoint}/open-apis`, key).whoami();
+            updateConfig({ tokenType: identity.tokenType, scopes: identity.scopes });
+            return identity.scopes ?? null;
+        }
+        catch (error) {
+            if (error instanceof AuthError || !config?.scopes) {
+                throw error;
+            }
+            return config.scopes;
+        }
+    }
+    if (config?.scopes) {
+        return config.scopes;
+    }
+    throw new UsageError('未登录，无法确定可安装的 Skill', '先执行 yos login 配置访问令牌');
+}

package/dist/skill-sync.js

@@ -1,9 +1,10 @@
-import { cpSync, existsSync, mkdirSync, readdirSync, rmSync } from 'node:fs';
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { readPackageMeta } from './npm-meta.js';
 import { updateConfig } from './config.js';
+import { isSkillAllowed, renderScoped } from './skill-scope.js';
 import { saveVersionState } from './version-state.js';
 const DEPRECATED_SKILLS = ['yos-doc-sheet'];
 const AGENT_SKILL_DIRS = ['.claude/skills', '.workbuddy/skills', '.cursor/skills', '.codex/skills', '.qoder/skills', '.qoder-cn/skills', '.agents/skills'];
@@ -24,17 +25,19 @@ export function detectSkillTargets() {
         .map((rel) => join(homedir(), rel))
         .filter((dir) => existsSync(dir));
 }
-export function installSkillsTo(targets) {
+export function installSkillsTo(targets, scopes) {
     const source = skillsSourceDir();
-    const skills = listSourceSkills();
+    const allSkills = listSourceSkills();
+    const skills = allSkills.filter((skill) => isSkillAllowed(skill, scopes));
     for (const target of targets) {
         for (const skill of skills) {
             const skillTarget = join(target, skill);
             mkdirSync(skillTarget, { recursive: true });
             cpSync(join(source, skill), skillTarget, { recursive: true });
+            renderMarkdownFiles(skillTarget, scopes);
         }
-        for (const deprecated of DEPRECATED_SKILLS) {
-            rmSync(join(target, deprecated), { recursive: true, force: true });
+        for (const removed of [...allSkills.filter((skill) => !skills.includes(skill)), ...DEPRECATED_SKILLS]) {
+            rmSync(join(target, removed), { recursive: true, force: true });
         }
     }
     updateConfig({ installedSkillDirs: targets });
@@ -44,3 +47,17 @@ export function installSkillsTo(targets) {
     }
     return skills;
 }
+export function listInstalledSkills(target) {
+    return listSourceSkills().filter((skill) => existsSync(join(target, skill, 'SKILL.md')));
+}
+function renderMarkdownFiles(dir, scopes) {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        const path = join(dir, entry.name);
+        if (entry.isDirectory()) {
+            renderMarkdownFiles(path, scopes);
+        }
+        else if (entry.name.endsWith('.md')) {
+            writeFileSync(path, renderScoped(readFileSync(path, 'utf8'), scopes), 'utf8');
+        }
+    }
+}

package/dist/skills/yos/SKILL.md

@@ -1,6 +1,10 @@
 ---
 name: yos
+# @scope knowledge:manage
 description: YOS 企业 AI 能力总入口：公司/部门/工作/个人等各类知识的检索与文档管理、云文档/云表格编写、录音转写、帮助手册、客户端升级与反馈。用户提到 yos/YOS 即使用本技能；用户问制度/流程/规范、要查或整理资料文档、要写云文档/云表格、要看会议录音转写、需要 YOS 客户端帮助时使用；不确定该用哪个 YOS 能力时先读本文件
+# @else
+# description: YOS 企业知识检索入口：公司/部门/工作/个人等各类知识的检索与带出处的原文作答。用户提到 yos/YOS 即使用本技能；用户问制度/流程/规范、要查资料或引用原文时使用；不确定该用哪个 YOS 能力时先读本文件
+# @end
 ---
 
 # YOS 能力总入口
@@ -23,30 +27,52 @@ yos ping        # 只要探活，退出码即结论（0 通 / 3 网络 / 4 鉴
 | 用户在问什么 | 用哪个命令 | 先读哪本 skill |
 |---|---|---|
 | 「公司制度/流程/规范/报销标准/产品资料」等**要一个公司里的答案** | `retrieve search` → `retrieve grep` 定位 → `retrieve read` 读原文 | yos-retrieval |
+<!-- @scope knowledge:manage -->
 | 「有哪些文档 / 共几份 / 文档目录结构」 | `retrieve outline`（检索层）或 `docs tree`（管理层） | yos-retrieval / yos-knowledge |
+<!-- @else -->
+| 「有哪些文档 / 共几份 / 文档目录结构」 | `retrieve outline` | yos-retrieval |
+<!-- @end -->
 | 找**配套/相关**材料、跨文档关系 | `retrieve neighbors`、`retrieve search --entity/--topic` | yos-retrieval |
+<!-- @scope knowledge:manage -->
 | 浏览/搜索自己的知识库与文档内容 | `kb list` `kb detail` `docs tree` `docs content` | yos-knowledge |
 | 把知识库里的上传文件取回本地 | `docs download <node_code> --out <路径>` | yos-knowledge |
 | 上传本地文件或目录、新建文档/文件夹、改名、移动、删除、回收站恢复 | `kb upload` `docs create` `docs mkdir` `docs update` `docs rename` `docs move` `docs delete` `docs restore` | yos-knowledge |
 | 往知识库**写云文档**（在线文档；非办公文件） | `docs create --type cloud`、`docs update` | **先读 yos-doc**（正文是结构化 JSON，结构与编写规范都在这本） |
 | 往知识库**写云表格**（在线表格；非办公文件） | `docs create --type sheet`、`docs update` | **先读 yos-sheet**（正文是结构化 JSON，结构与列宽等推荐做法都在这本） |
+<!-- @end -->
+<!-- @scope transcript:read -->
 | 会议录音转写、纪要、逐句发言 | `transcript list` → `transcript detail` | yos-transcript |
+<!-- @end -->
+<!-- @scope support -->
 | 「YOS 怎么用」、客户端最新版本、提交问题反馈 | `support manual*` `support upgrade*` `support feedback` | yos-support |
+<!-- @end -->
 | 领域命令没覆盖的能力 | `tool list` → `tool schema <name>` → `tool call <name> --params '{...}'` | yos-shared |
 
+<!-- @scope knowledge:manage -->
 五个领域共 28 个命令（kb 4 / docs 11 / retrieve 5 / support 6 / transcript 2）。服务端工具清单以 `yos tool list` 动态获取为准，命令与工具基本 1:1，例外是 `docs download` 与 `kb upload`——两者因需读写本地文件而单独实现（后者走开放接口上传通道，不对应 MCP 工具）。`yos <领域> --help` 列出该域全部命令，`yos <领域> <动作> --help` 给出用法、参数说明与风险标注（只读 / 写入 / 高危）。
+<!-- @else -->
+服务端工具清单以 `yos tool list` 动态获取为准：当前令牌仅开放知识库检索（`retrieve *` 与 `kb list`），其余领域命令会被服务端拒绝（`当前令牌仅支持知识库检索`），遇到时直接告知用户该能力需在 YOS 客户端内使用，不要换写法重试。`yos <领域> <动作> --help` 给出用法、参数说明与风险标注。
+<!-- @end -->
 
+<!-- @scope knowledge:manage -->
 **新建与删除知识库都不在 CLI 与服务端工具集内**：用户提到建库或删库时，引导其到 YOS 客户端手动操作，不要尝试 `yos kb create` / `yos kb delete`（会被拒绝，exit=2）。建好库之后用 `yos kb list` 取知识库编码即可继续上传与整理。
 
-## 2. 七条硬规则（违反必出错）
+<!-- @end -->
+## 2. 硬规则（违反必出错）
 
 1. **`--json` 是双层包装**：外层 `{"text":"<JSON 字符串>","isError":false}`，要拿字段必须对 `text` 再 `JSON.parse` 一次；`isError:true` 时 `text` 是错误文案而非数据
 2. **参数错误一律 exit=2 且不发请求**：非法枚举、越界 `--size`、日期格式非法或区间倒置、URN 非法、必填缺失都由 CLI 本地拦下，照 `提示:` 改参数即可，不要重试原命令。exit=0 仍需自行校验内容的场景见 yos-shared
 3. **引用作答必须读原文**：`retrieve search` 的 `snippet` 只是线索，不能作为引用依据；未 `retrieve read` 之前不下结论
+<!-- @scope knowledge:manage -->
 4. **写操作先复述再执行**：`kb update`、`docs create/update/mkdir/rename/move`、`kb upload`、`support feedback` 都要让用户确认最终文案；`docs update` 是**整体覆盖**（正文传什么就替换什么）；写云文档/云表格（`--type cloud/sheet`）的正文前**先读 yos-doc（云文档）/ yos-sheet（云表格）技能**——正文是结构化 JSON 且服务端不校验，写错要到客户端打开才暴露
 5. **删除必须两步**：`yos docs count <node_code>` 查受影响文档数 → 展示给用户 → 用户明确同意后才 `yos docs delete`。未经确认不得调用
+<!-- @end -->
 6. **令牌不出现在任何输出里**：不写进日志、命令、对用户的回复；只以掩码形式（`xxxxxxxx****xxxx`，即前 8 位 + `****` + 后 4 位）引用
+<!-- @scope transcript:read,support -->
 7. **日期参数分两类，别混用**：`transcript list --start/--end`、`support upgrade-log --start/--end` **只收 `yyyy-MM-dd`**，中文表达由 CLI 本地拒绝（`错误: --start 日期格式应为 yyyy-MM-dd：本周`，exit 2），须自己换算；`retrieve search/outline` 的 `--occurred-*`/`--effective-*` **收自然语言**（`上季度`、`8 月` 直接传，由服务端解析），`retrieve search` 还会把 `--query` 文本里的时间表达解析为时间窗并在 `time_window` 回显
+<!-- @else -->
+7. **检索的日期参数收自然语言**：`retrieve search/outline` 的 `--occurred-*`/`--effective-*` 直接传 `上季度`、`8 月` 等表达，由服务端解析；`retrieve search` 还会把 `--query` 文本里的时间表达解析为时间窗并在 `time_window` 回显
+<!-- @end -->
 
 ## 3. 登录与配置
 
@@ -64,6 +90,7 @@ yos kb list --scope created --json                        # 需要 kbCode 时
 yos retrieve search '报销标准' --kb KB20261009000001        # 语义检索拿候选与命中行号
 yos retrieve read 'cortex://kb/KB20261009000001/doc/ND20261009000012:1-60'  # 读原文再作答
 
+<!-- @scope knowledge:manage -->
 # 整理知识库
 yos docs tree KB20261009000001                            # 目录树（资源编码字段是 resourceCode）
 yos docs mkdir '会议纪要' --kb KB20261009000001             # 返回新节点编码
@@ -78,13 +105,18 @@ yos docs create "值班排期表" --kb KB20261009000001 --type sheet --file draf
 yos docs content ND20261010000030 --json                     # 写后自查：读回确认正文完整落库、结构未变形
 yos docs update ND20261010000030 --file edited.yosdoc.json    # 改正文=整体覆盖：先读回全文，本地编辑后整体回传
 
+<!-- @end -->
+<!-- @scope transcript:read -->
 # 会议内容
 yos transcript list --json                                 # 取 transcriptionUserId（不是 TT 开头编码）
 yos transcript detail 2105108032979103745 --json           # 取 summary / sentences
 
+<!-- @end -->
+<!-- @scope support -->
 # 帮助与版本
 yos support manual-search '登录'                            # 手册检索
 yos support upgrade --platform MAC_ARM64                    # 客户端最新版
+<!-- @end -->
 ```
 
 ## 5. 输出与兜底

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

@@ -220,7 +220,11 @@ yos retrieve neighbors 'cortex://kb/KB20260921000001/doc/ND20260921000307' --kin
 
 ### 做不到的事（别反复试）
 
+<!-- @scope transcript:read -->
 - 无跨转写全文检索：`retrieve` 不覆盖会议记录，转写正文走 `yos transcript detail`。
+<!-- @else -->
+- 无跨转写全文检索：`retrieve` 不覆盖会议记录。
+<!-- @end -->
 - 无 `--min-score` 相关度阈值；无按编辑时间排序。
 - 不能把检索结果的 `score` 当成可信度百分比对外表述。
 

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

@@ -66,8 +66,12 @@ yos kb list --json | node -e 'let d="";process.stdin.on("data",c=>d+=c).on("end"
 | 知识库 `kbCode` | `KB` + yyyyMMdd + 6 位序号 | `KB20260921000001` |
 | 节点 `resourceCode` / `nodeCode` | `ND` + yyyyMMdd + 6 位序号 | `ND20260921000307` |
 | 检索 URN | `cortex://kb/{kbCode}/doc/{nodeCode}` | `cortex://kb/KB20260921000001/doc/ND20260921000307` |
+<!-- @scope transcript:read -->
 | 转写记录 ID | 19 位数字字符串 `transcriptionUserId` | `2105108032979103745` |
+<!-- @end -->
+<!-- @scope support -->
 | 手册节点 ID | 19 位数字（`support manual` 目录树里的 `id`） | `2100513671581945858` |
+<!-- @end -->
 
 **两套编码命名空间不互通**（跨域引用时的硬约束）：
 
@@ -100,7 +104,9 @@ exit=1 的文案偶有服务端内部字段名（如 `kb_code`、`output_mode`
 | 命令 | 行为 | 必做的校验 |
 |---|---|---|
 | `retrieve search` | 低分候选照常返回（实测 score 0.016 的不相关文档也在列表里） | 看 `score`，低于 0.3 的结果不要当依据；必要时 `retrieve read` 核对原文 |
+<!-- @scope knowledge:manage -->
 | `docs content`（上传的 file 类型节点） | `content` 为空，返回体带 `contentHint` 说明该节点无内联正文 | 读上传文件正文改用 `retrieve read`，取原文件用 `docs download` |
+<!-- @end -->
 | `retrieve grep --mode count` | `matchCount` 可能为 null（cortex 侧未回该字段） | 需要命中数时用 `--mode content` 数 `matches` 长度 |
 | 任何检索/查询 | 空结果与「参数写错但恰好合法」不可区分（如 `--kb` 传了无权限的库） | 结果为空时先确认编码与权限，再回答「没有相关资料」 |
 
@@ -128,14 +134,21 @@ exit=1 的文案偶有服务端内部字段名（如 `kb_code`、`output_mode`
 
 ```bash
 yos kb list                          # → kbCode（表格左列；末尾有「还有 M 条」尾注时须先翻页拿全）
+<!-- @scope knowledge:manage -->
 yos docs tree KB20260921000001         # → resourceCode（树里每个节点的编码）
+<!-- @end -->
 yos retrieve outline 'cortex://kb/KB20260921000001'   # → 文档 URN（含行号，检索决策用）
+<!-- @scope transcript:read -->
 yos transcript list                     # → transcriptionUserId
+<!-- @end -->
+<!-- @scope support -->
 yos support manual                      # → 手册节点 id
+<!-- @end -->
 ```
 
 `--keyword` 缩小范围：`yos kb list --keyword 报销`。
 
+<!-- @scope knowledge:manage -->
 ## 6. 权限与写操作规则
 
 服务端按知识库角色校验，CLI 不做本地校验，权限不足直接返回业务失败（退出码 1）：
@@ -149,8 +162,15 @@ yos support manual                      # → 手册节点 id
 - `kb list` / `docs tree` 返回的 `role` 字段实测取值：`owner`（所有者）/ `admin` / `edit` / `read`（只读分享），无直接角色时为 `null`
 - 权限不足是**运行时**返回的业务失败（exit 1），文案形如 `没有该资源的访问权限：MOVE_DELETE_RESOURCE.ND20261010000018`：含节点编码但不告诉你缺什么角色。正确做法：先 `yos kb detail <kbCode>` 看 `role`，再决定是否执行；只有 `read`/`null` 时直接告知用户需要申请编辑或管理权限
 - **建库与删库都不在 CLI 内**（服务端未提供 `kb_create` / `kb_delete` 工具）：用户要新建或删除知识库，引导其去 YOS 客户端手动操作；建好库后用 `yos kb list` 取编码继续后续动作
+<!-- @else -->
+## 6. 权限范围
+
+当前令牌仅开放知识库检索（`retrieve *` 与 `kb list`）。文档管理、转写查询、帮助与反馈等能力会被服务端拒绝（`当前令牌仅支持知识库检索，该能力请在 YOS 客户端内使用`），遇到时直接告知用户需在 YOS 客户端内操作，不要换写法重试。
+
+<!-- @end -->
 - `retrieve` 只能命中当前用户可见的文档：跨库检索范围随登录身份变化，换令牌结果就不同
 
+<!-- @scope knowledge:manage -->
 ## 7. 删除与安全纪律（强制）
 
 1. 删除前必须先查影响面并向用户报告，拿到明确确认才执行：
@@ -162,18 +182,31 @@ yos support manual                      # → 手册节点 id
 3. 写入类命令（`kb update`、`docs mkdir/create/update/rename/move/restore`、`kb upload`、`support feedback`）在用户没有明确要求时不擅自执行；`support feedback` 会真实提交工单，必须原文让用户确认内容后再发
 4. 正文内容含用户数据时注意：`--content` 会进入 shell 历史，长文本/多行文本一律改走 `--file <路径>`
 
+<!-- @end -->
 ## 8. 底层工具通道（领域命令覆盖不到时才用）
 
 ```bash
 yos tool list                                  # 全部工具，按领域分组（动态获取，以实际输出为准）
 yos tool schema retrieve_search                 # 完整描述 + 入参表 + 返参 + 调用示例
+<!-- @scope knowledge:manage -->
 yos tool call docs_tree --params '{"kb_code":"KB20260921000001"}'
+<!-- @else -->
+yos tool call kb_list --params '{"keyword":"报销"}'
+<!-- @end -->
 ```
 
 - `tool schema` 的入参说明会截断到 50 字，要全文用 `--json`：`yos tool schema retrieve_search --json`
 - `tool call` 的 `--params` 必须是合法 JSON 字符串，参数名用工具 schema 里的 **snake_case**
+<!-- @scope knowledge:manage -->
 - 工具名容忍空格与连字符写法：`yos tool schema docs tree` / `support manual-read` 都会归一化为 `docs_tree` / `support_manual_read`
+<!-- @else -->
+- 工具名容忍空格与连字符写法：`yos tool schema retrieve search` 会归一化为 `retrieve_search`
+<!-- @end -->
+<!-- @scope knowledge:manage -->
 - 域命令是工具的一一映射（`kb upload` 除外，走 multipart 直传），能用域命令就别用 `tool call`
+<!-- @else -->
+- 域命令是工具的一一映射，能用域命令就别用 `tool call`
+<!-- @end -->
 
 ## 9. 升级与版本更新约定
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yosai/cli",
-  "version": "0.2.1-test.14",
+  "version": "0.2.1-test.15",
   "description": "YOS 能力的 Agent 执行入口：工具调用、知识库管理与文件上传",
   "type": "module",
   "bin": {