zen-gitsync 2.17.8 → 2.17.10

package/src/cli/ai/mcp.test.js

@@ -0,0 +1,275 @@
+// Copyright 2026 xz333221
+//
+// 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.
+//
+// MCP stdio 客户端的回归测试。
+//
+// 这里最值钱的一条是 buildSpawnSpec 的转义用例 —— Windows 上
+// `spawn(cmd, args, { shell: true })` 会把含空格的参数拆碎(实测 C:\a b\proj
+// 会变成 "C:a" + "bproj"),而直接 spawn .cmd 又会被 Node 拒绝(EINVAL)。
+// 项目路径带空格是常态,这两条任一回归都会让"装了 MCP 但连不上"变成玄学问题。
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { promises as fs } from 'node:fs';
+import { spawn } from 'node:child_process';
+import os from 'node:os';
+import path from 'node:path';
+
+const sandboxHome = await fs.mkdtemp(path.join(os.tmpdir(), 'zen-mcp-home-'));
+const sandboxProject = await fs.mkdtemp(path.join(os.tmpdir(), 'zen-mcp-project-'));
+process.env.USERPROFILE = sandboxHome;
+process.env.HOME = sandboxHome;
+delete process.env.HOMEDRIVE;
+delete process.env.HOMEPATH;
+
+const { buildSpawnSpec, loadMcpServers, McpManager } = await import('./mcp.js');
+const { AI_MCP_FILE } = await import('../../paths.js');
+
+const IS_WIN = process.platform === 'win32';
+
+// ── buildSpawnSpec ────────────────────────────────────────────
+
+test('buildSpawnSpec: 解析到可执行文件时不经 shell,参数原样保留', () => {
+  const spec = buildSpawnSpec(process.execPath, ['-e', 'console.log(1)', 'C:\\a b\\proj'], {});
+  assert.equal(spec.file, process.execPath);
+  assert.deepEqual(spec.argv, ['-e', 'console.log(1)', 'C:\\a b\\proj']);
+  assert.notEqual(spec.options.shell, true, '绝不能用 shell:true —— 含空格的参数会被拆碎');
+  assert.equal(spec.options.windowsVerbatimArguments, undefined, '直接 spawn 时不应开启 verbatim');
+});
+
+test('buildSpawnSpec: 批处理走 cmd.exe,反斜杠与元字符按 cmd 规则转义', { skip: !IS_WIN }, () => {
+  const spec = buildSpawnSpec('npx', ['-y', 'pkg', 'C:\\a b\\proj', 'trail\\', 'a&b'], {});
+  assert.match(spec.file, /cmd\.exe$/i, '批处理必须交给 cmd.exe');
+  assert.deepEqual(spec.argv.slice(0, 3), ['/d', '/s', '/c']);
+  assert.equal(spec.options.windowsVerbatimArguments, true, '整行由我们自己转义,不能再让 Node 加引号');
+
+  const line = spec.argv[3];
+  assert.match(line, /"C:\\a b\\proj"/, '含空格的路径必须整体加引号,否则会被拆成两段');
+  assert.match(line, /"trail\\\\"/, '行尾反斜杠必须加倍,否则会被 cmd 当转义符吃掉');
+  assert.match(line, /a\^&b/, '元字符 & 必须加 ^ 前缀,否则会被当成管道/顺序执行');
+  // 整行外层再加一层引号,配合 /s 的"去掉首尾引号"规则
+  assert.ok(line.startsWith('""') && line.endsWith('""'), `整行需要被引号包裹: ${line}`);
+});
+
+test('buildSpawnSpec: 含空格的 .cmd 实参能原样到达子进程(端到端)', { skip: !IS_WIN }, async () => {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'zen-mcp-cmd-'));
+  const script = path.join(dir, 'echo-args.cmd');
+  // %* 会把收到的参数原样回显,是最直接的"参数有没有被拆碎"探针
+  await fs.writeFile(script, '@echo off\r\necho ARGS:%*\r\n', 'utf8');
+
+  const spaced = 'C:\\a b\\proj';
+  const spec = buildSpawnSpec(script, [spaced, 'plain'], {});
+  const output = await new Promise((resolve, reject) => {
+    const child = spawn(spec.file, spec.argv, { ...spec.options });
+    let text = '';
+    child.stdout.on('data', chunk => { text += chunk; });
+    child.on('error', reject);
+    child.on('exit', () => resolve(text.trim()));
+  });
+
+  assert.match(output, /ARGS:.*a b.*proj/, `参数被拆碎了,实际情况: ${output}`);
+  assert.match(output, /plain/);
+});
+
+// ── loadMcpServers ────────────────────────────────────────────
+
+test('loadMcpServers: 项目级覆盖全局同名 server,坏的 JSON 只当没有配置', async () => {
+  const project = await fs.mkdtemp(path.join(os.tmpdir(), 'zen-mcp-merge-'));
+  await fs.mkdir(path.dirname(AI_MCP_FILE), { recursive: true });
+  await fs.writeFile(AI_MCP_FILE, JSON.stringify({
+    mcpServers: {
+      shared: { command: 'npx', args: ['global'] },
+      onlyGlobal: { command: 'npx', args: ['g'] },
+      broken: { args: ['no-command'] },
+    },
+  }), 'utf8');
+  await fs.writeFile(path.join(project, '.mcp.json'), JSON.stringify({
+    mcpServers: { shared: { command: 'npx', args: ['project'] } },
+  }), 'utf8');
+
+  const { servers, sources } = await loadMcpServers({ cwd: project });
+  assert.deepEqual(servers.shared.args, ['project'], '项目级应覆盖全局级');
+  assert.ok(servers.onlyGlobal);
+  assert.equal(servers.broken, undefined, '没有 command 的条目应被丢弃');
+  assert.equal(sources.length, 2);
+
+  // 坏文件:整个文件当空配置,不抛错
+  await fs.writeFile(path.join(project, '.mcp.json'), '{ this is not json', 'utf8');
+  const broken = await loadMcpServers({ cwd: project });
+  assert.deepEqual(broken.servers.shared.args, ['global'], '坏的项目配置应回落到全局配置');
+});
+
+// ── 真实 stdio 往返 ───────────────────────────────────────────
+
+// 一个最小可用的 MCP server:换行分隔 JSON-RPC,只实现握手 + tools/list + tools/call。
+const FAKE_SERVER = `
+let buffer = '';
+const send = (message) => process.stdout.write(JSON.stringify(message) + '\\n');
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', chunk => {
+  buffer += chunk;
+  let index;
+  while ((index = buffer.indexOf('\\n')) >= 0) {
+    const line = buffer.slice(0, index).trim();
+    buffer = buffer.slice(index + 1);
+    if (!line) continue;
+    const message = JSON.parse(line);
+    if (message.method === 'initialize') {
+      send({ jsonrpc: '2.0', id: message.id, result: { protocolVersion: '2024-11-05', capabilities: { tools: {} }, serverInfo: { name: 'fake', version: '0' } } });
+    } else if (message.method === 'tools/list') {
+      send({ jsonrpc: '2.0', id: message.id, result: { tools: [
+        { name: 'echo', description: '回显输入', inputSchema: { type: 'object', properties: { text: { type: 'string' } } } },
+        { name: 'weird-name/with spaces', description: '', inputSchema: { type: 'object' } },
+        { name: 'boom', description: '永远失败', inputSchema: { type: 'object' } },
+      ] } });
+    } else if (message.method === 'tools/call') {
+      if (message.params.name === 'boom') {
+        send({ jsonrpc: '2.0', id: message.id, result: { isError: true, content: [{ type: 'text', text: '炸了' }] } });
+      } else if (message.params.name === 'weird-name/with spaces') {
+        send({ jsonrpc: '2.0', id: message.id, result: { content: [{ type: 'image', mimeType: 'image/png' }] } });
+      } else {
+        send({ jsonrpc: '2.0', id: message.id, result: { content: [{ type: 'text', text: 'echo:' + (message.params.arguments?.text ?? '') }] } });
+      }
+    }
+  }
+});
+`;
+
+async function startFakeManager({ servers }) {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'zen-mcp-fake-'));
+  const script = path.join(dir, 'fake-mcp.mjs');
+  await fs.writeFile(script, FAKE_SERVER, 'utf8');
+  return await McpManager.create({
+    cwd: sandboxProject,
+    servers: servers ?? { fake: { command: process.execPath, args: [script] } },
+  });
+}
+
+test('McpManager: 握手后把工具挂成 mcp__<server>__<tool>,名字收敛到安全字符集', async () => {
+  const manager = await startFakeManager({});
+  try {
+    assert.deepEqual(manager.status().map(s => s.error), [null], 'server 应连接成功');
+    const names = manager.toolDefinitions.map(tool => tool.function.name);
+    assert.ok(names.includes('mcp__fake__echo'));
+    // OpenAI function name 只允许 [A-Za-z0-9_-],空格与斜杠必须被替换
+    assert.ok(names.some(name => name === 'mcp__fake__weird-name_with_spaces'), names.join(','));
+    for (const tool of manager.toolDefinitions) {
+      assert.match(tool.function.name, /^[a-zA-Z0-9_-]+$/);
+      assert.ok(tool.function.parameters, '每个工具都要带 inputSchema');
+    }
+  } finally {
+    await manager.close();
+  }
+});
+
+test('McpManager: tools/call 的 content 数组被拍平成字符串回喂给模型', async () => {
+  const manager = await startFakeManager({});
+  try {
+    assert.equal(await manager.call('mcp__fake__echo', { text: '你好' }), 'echo:你好');
+    // isError 的结果也要变成可读字符串,而不是把异常抛进 agent 循环
+    assert.match(await manager.call('mcp__fake__boom', {}), /^错误: 炸了/);
+    // 非文本 part 用占位符表示,不能让模型看到 undefined
+    assert.match(await manager.call('mcp__fake__weird-name_with_spaces', {}), /\[image image\/png/);
+    // 不认识的名字返回 null,由调用方回落到内置工具
+    assert.equal(await manager.call('mcp__nope__nope', {}), null);
+  } finally {
+    await manager.close();
+  }
+});
+
+test('McpManager: 未知工具不进入 registry,describe 只描述真实工具数', async () => {
+  const manager = await startFakeManager({});
+  try {
+    assert.equal(manager.has('mcp__fake__echo'), true);
+    assert.equal(manager.has('read_file'), false, '内置工具不该被扩展层接管');
+    assert.equal(manager.toolCount, 3);
+
+    const zh = manager.describe({ locale: 'zh-CN' });
+    assert.match(zh, /已接入的 MCP 服务/);
+    assert.match(zh, /fake: 3 个工具/);
+    assert.doesNotMatch(manager.describe({ locale: 'en' }), /已接入/);
+  } finally {
+    await manager.close();
+  }
+});
+
+test('McpManager: 启动失败只记录错误,不抛异常也不拖垮其他 server', async () => {
+  const manager = await McpManager.create({
+    cwd: sandboxProject,
+    servers: {
+      good: { command: process.execPath, args: ['-e', 'process.stdin.resume()'] },
+      missing: { command: IS_WIN ? 'definitely-not-a-real-command-xyz' : 'definitely-not-a-real-command-xyz', args: [] },
+    },
+  });
+  try {
+    const status = manager.status();
+    assert.equal(status.length, 2);
+    const missing = status.find(item => item.id === 'missing');
+    assert.ok(missing.error, '起不来的 server 必须有可读错误');
+    assert.equal(missing.tools, 0);
+  } finally {
+    await manager.close();
+  }
+});
+
+test('McpManager: server 中途退出时调用立刻失败,而不是干等到超时', async () => {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'zen-mcp-die-'));
+  const script = path.join(dir, 'die.mjs');
+  // 握完手就退出,模拟 server 崩溃
+  await fs.writeFile(script, `
+let buffer = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', chunk => {
+  buffer += chunk;
+  let index;
+  while ((index = buffer.indexOf('\\n')) >= 0) {
+    const line = buffer.slice(0, index).trim();
+    buffer = buffer.slice(index + 1);
+    if (!line) continue;
+    const message = JSON.parse(line);
+    if (message.method === 'initialize') {
+      process.stdout.write(JSON.stringify({ jsonrpc: '2.0', id: message.id, result: { protocolVersion: '2024-11-05', capabilities: {}, serverInfo: { name: 'die', version: '0' } } }) + '\\n');
+    } else if (message.method === 'tools/list') {
+      process.stdout.write(JSON.stringify({ jsonrpc: '2.0', id: message.id, result: { tools: [{ name: 'later', description: '', inputSchema: { type: 'object' } }] } }) + '\\n');
+      setTimeout(() => process.exit(1), 30);
+    }
+  }
+});
+`, 'utf8');
+
+  const manager = await McpManager.create({ cwd: sandboxProject, servers: { die: { command: process.execPath, args: [script] } } });
+  try {
+    assert.equal(manager.toolCount, 1);
+    await new Promise(resolve => setTimeout(resolve, 120)); // 等子进程真的死掉
+    const started = Date.now();
+    const result = await manager.call('mcp__die__later', {});
+    assert.ok(Date.now() - started < 5000, '应在子进程退出后立即返回,不该等满 120s 超时');
+    assert.match(result, /错误: MCP 工具/);
+    assert.match(String(result), /已退出|不可写/, `错误信息应说明原因,实际: ${result}`);
+  } finally {
+    await manager.close();
+  }
+});
+
+test('McpManager: 没有配置任何 server 时是空管理器,不影响内置工具', async () => {
+  const manager = await McpManager.create({ cwd: sandboxProject, servers: {} });
+  try {
+    assert.equal(manager.toolCount, 0);
+    assert.deepEqual(manager.toolDefinitions, []);
+    assert.equal(manager.describe({ locale: 'zh-CN' }), '', '没有连接成功任何 server 时不应往提示词里塞标题');
+    assert.equal(await manager.call('mcp__x__y', {}), null);
+  } finally {
+    await manager.close();
+  }
+});

package/src/cli/ai/runtime.test.js

@@ -78,6 +78,10 @@ test('timeout and explicit cancellation have different outcomes', async () => {
 })
 
 const call = n => ({ id: `call${n}`, type: 'function', function: { name: 'read_file', arguments: '{}' } })
+const askCall = (id = 'ask1') => ({ id, type: 'function', function: {
+  name: 'ask_user',
+  arguments: JSON.stringify({ question: 'Which option?', options: ['A', 'B'], allow_free_text: false }),
+} })
 const strings = { waiting: '', toolRunning: x => x, toolIterLimit: n => String(n), llmError: x => x, emptyResponse: 'empty' }
 const noop = () => {}
 const quiet = { startSpinner: () => ({ stop: noop }), createAssistantWriter: () => ({ writeContent: noop, writeThinking: noop, finish: noop }),
@@ -133,6 +137,34 @@ test('turn aggregates all model calls, persists progress and records response ti
   assert.equal(s.sessionStats.usage.totalTokens, 24)
 })
 
+test('ask_user pauses a turn until the answer arrives, then continues the model loop', async () => {
+  const s = state()
+  let resolveAnswer
+  let asked
+  s.ctx.askUser = args => {
+    asked = args
+    return new Promise(resolve => { resolveAnswer = resolve })
+  }
+  let round = 0
+  const turnPromise = runAgentTurn(s, 'task', strings, [], {
+    ui: quiet,
+    chat: async () => (++round === 1
+      ? { content: '', toolCalls: [askCall()] }
+      : { content: 'finished', toolCalls: [] }),
+  })
+
+  await new Promise(resolve => setImmediate(resolve))
+  assert.deepEqual(asked, { question: 'Which option?', options: ['A', 'B'], allowFreeText: false })
+  assert.equal(round, 1)
+  resolveAnswer('B')
+
+  const stats = await turnPromise
+  assert.equal(stats.status, 'completed')
+  assert.equal(round, 2)
+  assert.equal(s.messages.at(-1).content, 'finished')
+  assert.equal(s.messages.find(message => message.role === 'tool').content, 'B')
+})
+
 test('cancellation during a tool skips the remaining batch and keeps valid tool history', async () => {
   const s = state(), executed = []
   const stats = await runAgentTurn(s, 'task', strings, [], { ui: quiet,

package/src/cli/ai/skills.js

@@ -0,0 +1,207 @@
+// Copyright 2026 xz333221
+//
+// 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.
+//
+// g ai 的 Skill 加载层。
+//
+// Skill 的形态就是「一个目录 + 内含 SKILL.md(YAML frontmatter: name / description)」,
+// 与 Claude Code、Cursor 等工具共用同一套约定 —— 所以智能体页面里从广场装下来的
+// skill 不需要任何转换就能被 g ai 直接读。
+//
+// 两级作用域(与安装目标一一对应):
+//   - 项目级 <cwd>/.claude/skills/<id>/SKILL.md   仅该项目可见
+//   - 全局级 ~/.zen-gitsync/ai/skills/<id>/SKILL.md  所有项目可见
+// 同名时**项目级覆盖全局级**(与本仓库其他"项目配置优先"的口径一致)。
+//
+// 渐进式披露(progressive disclosure):
+//   这里只把「名字 + 描述 + SKILL.md 路径」塞进系统提示词(每个 skill 约 30~50 token),
+//   不注入正文。模型判断某个 skill 与当前任务相关时,自己用 read_file 去读那个路径。
+//   这样装 50 个 skill 也不会把上下文撑爆,而且是本仓库已有工具集的零成本复用。
+
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { AI_SKILLS_DIR } from '../../paths.js';
+
+// 单个 skill 目录下必须存在的入口文件名
+export const SKILL_ENTRY = 'SKILL.md';
+
+// 名字/描述的长度上限 —— 防止某个仓库里的 SKILL.md 写了 500 字的 description
+// 把系统提示词挤爆。截断而不是丢弃,保证 skill 至少还能被看到。
+const MAX_NAME_CHARS = 80;
+const MAX_DESCRIPTION_CHARS = 400;
+// 一次注入的最大 skill 数。超出的按 name 排序截断,并在提示词里说明还有多少个。
+const MAX_SKILLS_IN_PROMPT = 60;
+
+/**
+ * 极简 frontmatter 解析。
+ *
+ * 只用支持 SKILL.md 里实际出现的形状:
+ *   ---
+ *   name: pdf
+ *   description: "带引号的描述"
+ *   description: 不带引号的描述
+ *   description: >-
+ *     折叠成一行
+ *     的长描述
+ *   ---
+ * 刻意不引入 yaml 依赖(本包 dependencies 保持精简),
+ * 也对不合法 frontmatter 保持宽容:解析不出来就退回空对象,由调用方用目录名兜底。
+ *
+ * @param {string} raw - 文件全文
+ * @returns {{ attrs: Record<string,string>, body: string }}
+ */
+export function parseFrontmatter(raw) {
+  const text = String(raw || '').replace(/^\uFEFF/, '');
+  const match = /^---[ \t]*\r?\n([\s\S]*?)\r?\n---[ \t]*(?:\r?\n|$)/.exec(text);
+  if (!match) return { attrs: {}, body: text };
+
+  const attrs = {};
+  const lines = match[1].split(/\r?\n/);
+  for (let i = 0; i < lines.length; i++) {
+    const kv = /^([A-Za-z_][A-Za-z0-9_-]*)\s*:\s*(.*)$/.exec(lines[i]);
+    if (!kv) continue;
+    const key = kv[1].toLowerCase();
+    let value = kv[2].trim();
+
+    // 折叠标量(> 或 >-):把后续所有缩进行用空格拼起来
+    if (/^[>|][+-]?$/.test(value)) {
+      const parts = [];
+      while (i + 1 < lines.length && /^\s+\S/.test(lines[i + 1])) {
+        parts.push(lines[++i].trim());
+      }
+      value = parts.join(value.startsWith('|') ? '\n' : ' ');
+    } else {
+      // 行内可能是个多行序列的开头(description: 后直接换行缩进),同样收进来
+      const parts = [value];
+      while (i + 1 < lines.length && /^\s+\S/.test(lines[i + 1]) && !/^\s*[A-Za-z_][A-Za-z0-9_-]*\s*:/.test(lines[i + 1])) {
+        parts.push(lines[++i].trim());
+      }
+      value = parts.filter(Boolean).join(' ').trim();
+    }
+
+    // 去掉包裹的引号
+    value = value.replace(/^(['"])([\s\S]*)\1$/, '$2').trim();
+    if (value) attrs[key] = value;
+  }
+  return { attrs, body: text.slice(match[0].length) };
+}
+
+function clamp(value, max) {
+  const text = String(value || '').trim();
+  return text.length > max ? `${text.slice(0, max - 1)}…` : text;
+}
+
+// 目录名兜底转可读名:my-cool-skill → my cool skill
+function prettifyDirName(dirName) {
+  return String(dirName || '').replace(/[-_]+/g, ' ').trim();
+}
+
+/**
+ * 读取一个 skills 根目录下的所有 skill。
+ * 单个 skill 读失败只跳过它,不影响同目录下其他 skill(一个坏文件不该让整批消失)。
+ *
+ * @param {string} root - skills 根目录(其下每个子目录是一个 skill)
+ * @param {'project'|'global'} scope
+ * @returns {Promise<Array<object>>}
+ */
+async function readSkillRoot(root, scope) {
+  const entries = await fs.readdir(root, { withFileTypes: true }).catch(() => []);
+  const found = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    if (entry.name.startsWith('.') || entry.name === 'node_modules') continue;
+    const file = path.join(root, entry.name, SKILL_ENTRY);
+    const raw = await fs.readFile(file, 'utf8').catch(() => '');
+    if (!raw.trim()) continue;
+    const { attrs } = parseFrontmatter(raw);
+    found.push({
+      id: entry.name,
+      name: clamp(attrs.name || prettifyDirName(entry.name) || entry.name, MAX_NAME_CHARS),
+      description: clamp(attrs.description || '', MAX_DESCRIPTION_CHARS),
+      dir: path.join(root, entry.name),
+      file,
+      scope,
+    });
+  }
+  return found;
+}
+
+/**
+ * 加载项目级 + 全局级 skill,项目级覆盖同名全局 skill。
+ *
+ * @param {{ cwd?: string }} [options]
+ * @returns {Promise<{ skills: Array<object>, errors: Array<{ root: string, message: string }> }>}
+ */
+export async function loadSkills({ cwd } = {}) {
+  const roots = [];
+  if (cwd) roots.push({ root: path.join(path.resolve(cwd), '.claude', 'skills'), scope: 'project' });
+  roots.push({ root: AI_SKILLS_DIR, scope: 'global' });
+
+  const skills = [];
+  const errors = [];
+  for (const { root, scope } of roots) {
+    try {
+      skills.push(...await readSkillRoot(root, scope));
+    } catch (err) {
+      errors.push({ root, message: err.message });
+    }
+  }
+
+  // 项目级优先:全局的先放,项目级后放覆盖同 id 的
+  const byId = new Map();
+  for (const skill of skills) {
+    const existing = byId.get(skill.id);
+    if (!existing || skill.scope === 'project') byId.set(skill.id, skill);
+  }
+  const merged = [...byId.values()].sort((a, b) => a.name.localeCompare(b.name));
+  return { skills: merged, errors };
+}
+
+/**
+ * 把已安装的 skill 渲染成系统提示词片段。
+ * 没有 skill 时返回空串,调用方直接拼接到提示词末尾即可(不会留下空标题)。
+ *
+ * @param {Array<object>} skills
+ * @param {{ locale?: string }} [options]
+ * @returns {string}
+ */
+export function buildSkillsPrompt(skills, { locale } = {}) {
+  if (!Array.isArray(skills) || skills.length === 0) return '';
+  const zh = !String(locale || '').startsWith('en');
+  const shown = skills.slice(0, MAX_SKILLS_IN_PROMPT);
+  const omitted = skills.length - shown.length;
+
+  const lines = shown.map(skill => {
+    const scope = skill.scope === 'project' ? (zh ? '项目' : 'project') : (zh ? '全局' : 'global');
+    const desc = skill.description || (zh ? '(无描述)' : '(no description)');
+    return `- **${skill.name}** [${scope}] — ${desc}\n  ${zh ? '说明书' : 'instructions'}: ${skill.file}`;
+  });
+
+  if (zh) {
+    return `
+
+# 已安装的 Skill(技能说明书)
+用户可以随时给 g ai 装新的 Skill。下面是当前可用的清单,**只列出了名字、用途和说明书路径**。
+当某个 Skill 明显贴合当前任务时,先用 read_file 读它的说明书,再严格按说明书的步骤执行 —— 不要凭名字猜测它的做法。
+${lines.join('\n')}${omitted > 0 ? `\n(还有 ${omitted} 个 Skill 未列出,用户可以缩小范围或自行告知)` : ''}`
+  }
+
+  return `
+
+# Installed skills
+The user can install new skills for g ai at any time. Below is the current list — **name, purpose and the path to its instructions only**.
+When a skill clearly matches the current task, read its instruction file with read_file first, then follow it literally. Never guess what a skill does from its name.
+${lines.join('\n')}${omitted > 0 ? `\n(${omitted} more skills are not listed; the user can narrow it down or name one directly)` : ''}`
+}
+
+export default { loadSkills, buildSkillsPrompt, parseFrontmatter, SKILL_ENTRY };

package/src/cli/ai/skills.test.js

@@ -0,0 +1,126 @@
+// Copyright 2026 xz333221
+//
+// 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.
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { promises as fs } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+// paths.js 在加载时求值 homedir,必须在 import 之前把 HOME 指到沙箱
+const sandboxHome = await fs.mkdtemp(path.join(os.tmpdir(), 'zen-skills-home-'));
+const sandboxProject = await fs.mkdtemp(path.join(os.tmpdir(), 'zen-skills-project-'));
+process.env.USERPROFILE = sandboxHome;
+process.env.HOME = sandboxHome;
+delete process.env.HOMEDRIVE;
+delete process.env.HOMEPATH;
+
+const { loadSkills, buildSkillsPrompt, parseFrontmatter } = await import('./skills.js');
+const { AI_SKILLS_DIR } = await import('../../paths.js');
+
+async function writeSkill(root, name, body) {
+  await fs.mkdir(path.join(root, name), { recursive: true });
+  await fs.writeFile(path.join(root, name, 'SKILL.md'), body, 'utf8');
+}
+
+test('parseFrontmatter: 覆盖 SKILL.md 里实际会出现的几种写法', () => {
+  assert.deepEqual(
+    parseFrontmatter('---\nname: pdf\ndescription: 处理 PDF\n---\n# body\n').attrs,
+    { name: 'pdf', description: '处理 PDF' },
+  );
+
+  // 带引号
+  assert.equal(
+    parseFrontmatter('---\ndescription: "带: 冒号的描述"\n---\n').attrs.description,
+    '带: 冒号的描述',
+  );
+
+  // 折叠标量(>):续行拼成一行
+  const folded = parseFrontmatter('---\ndescription: >-\n  第一行\n  第二行\nname: x\n---\n');
+  assert.equal(folded.attrs.description, '第一行 第二行');
+  assert.equal(folded.attrs.name, 'x', '折叠块之后的键仍要能解析出来');
+
+  // 没有 frontmatter:整体当正文,不报错
+  const none = parseFrontmatter('# just markdown\n');
+  assert.deepEqual(none.attrs, {});
+  assert.equal(none.body, '# just markdown\n');
+
+  // 坏 frontmatter(没闭合)不应抛错
+  assert.deepEqual(parseFrontmatter('---\nname: x\n').attrs, {});
+
+  // BOM 不能挡住 frontmatter 识别
+  assert.equal(parseFrontmatter('\uFEFF---\nname: bom\n---\n').attrs.name, 'bom');
+});
+
+test('loadSkills: 项目级覆盖同名全局级,并保留 scope 标记', async () => {
+  await writeSkill(AI_SKILLS_DIR, 'shared', '---\nname: 全局版\ndescription: from global\n---\n');
+  await writeSkill(AI_SKILLS_DIR, 'only-global', '---\nname: 只有全局\ndescription: g\n---\n');
+  await writeSkill(path.join(sandboxProject, '.claude', 'skills'), 'shared', '---\nname: 项目版\ndescription: from project\n---\n');
+  await writeSkill(path.join(sandboxProject, '.claude', 'skills'), 'only-project', '---\nname: 只有项目\ndescription: p\n---\n');
+
+  const { skills } = await loadSkills({ cwd: sandboxProject });
+  const byId = new Map(skills.map(skill => [skill.id, skill]));
+
+  assert.equal(byId.size, 3, 'shared 只应出现一次(被项目级覆盖)');
+  assert.equal(byId.get('shared').name, '项目版');
+  assert.equal(byId.get('shared').scope, 'project');
+  assert.equal(byId.get('only-global').scope, 'global');
+  assert.equal(byId.get('only-project').scope, 'project');
+});
+
+test('loadSkills: 没有 frontmatter 时用目录名兜底,坏目录不影响其他 skill', async () => {
+  await writeSkill(AI_SKILLS_DIR, 'no-frontmatter', '# 只有正文\n');
+  await writeSkill(AI_SKILLS_DIR, 'my-cool-skill', '---\ndescription: d\n---\n');
+  // 有目录但没有 SKILL.md:应被跳过而不是产生一条空记录
+  await fs.mkdir(path.join(AI_SKILLS_DIR, 'empty-dir'), { recursive: true });
+
+  const { skills } = await loadSkills({ cwd: sandboxProject });
+  const byId = new Map(skills.map(skill => [skill.id, skill]));
+
+  assert.equal(byId.get('no-frontmatter').name, 'no frontmatter', '无 frontmatter 时用目录名兜底并转成可读形式');
+  assert.equal(byId.get('my-cool-skill').name, 'my cool skill', '目录名应转成可读形式');
+  assert.equal(byId.has('empty-dir'), false);
+});
+
+test('loadSkills: 没有配置任何 skill 时返回空数组而不是抛错', async () => {
+  const empty = await fs.mkdtemp(path.join(os.tmpdir(), 'zen-skills-empty-'));
+  const { skills, errors } = await loadSkills({ cwd: empty });
+  // 全局目录里上面已经写了 skill,所以这里只断言"不抛错且结构正确"
+  assert.ok(Array.isArray(skills));
+  assert.ok(Array.isArray(errors));
+});
+
+test('buildSkillsPrompt: 没有 skill 时返回空串(拼到提示词里不留空标题)', () => {
+  assert.equal(buildSkillsPrompt([], { locale: 'zh-CN' }), '');
+  assert.equal(buildSkillsPrompt(undefined, { locale: 'en' }), '');
+});
+
+test('buildSkillsPrompt: 只注入名字/描述/路径,不注入正文(渐进式披露)', () => {
+  const skills = [
+    { id: 'a', name: 'pdf', description: '处理 PDF', file: 'C:/x/pdf/SKILL.md', scope: 'project' },
+    { id: 'b', name: 'docx', description: '', file: 'C:/y/docx/SKILL.md', scope: 'global' },
+  ];
+  const zh = buildSkillsPrompt(skills, { locale: 'zh-CN' });
+  assert.match(zh, /已安装的 Skill/);
+  assert.match(zh, /pdf/);
+  assert.match(zh, /\[项目\]/);
+  assert.match(zh, /\[全局\]/);
+  assert.match(zh, /C:\/x\/pdf\/SKILL\.md/);
+  assert.match(zh, /\(无描述\)/, '空描述要有占位,不能让模型以为描述丢了');
+
+  const en = buildSkillsPrompt(skills, { locale: 'en-US' });
+  assert.match(en, /Installed skills/);
+  assert.match(en, /project/);
+  assert.doesNotMatch(en, /已安装/);
+});

package/src/cli/ai/termui.js

@@ -156,6 +156,7 @@ export const SLASH_COMMANDS = [
   { cmd: '/think compact', descZh: '预览前 12 行思考', descEn: 'Preview the first 12 thinking lines' },
   { cmd: '/think off', descZh: '隐藏思考（不影响模型推理）', descEn: 'Hide thinking (model still reasons)' },
   { cmd: '/tools',    descZh: '切换工具结果：精简 / 完整', descEn: 'Toggle compact / full tool output' },
+  { cmd: '/skills',   descZh: '查看已装 Skill 与 MCP', descEn: 'List installed skills / MCP' },
   { cmd: '/stats',    descZh: '查看耗时与 Token 用量', descEn: 'Show timing and token usage' },
   { cmd: '/new',      descZh: '开启新对话',            descEn: 'Start a new chat' },
   { cmd: '/resume',   descZh: '恢复之前的对话',         descEn: 'Resume a previous chat' },