zen-gitsync 2.17.8 → 2.17.10

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

@@ -0,0 +1,117 @@
+// context.js 是 CLI(`g ai`)与 Web 智能体面板共用的**唯一**一份上下文准备实现。
+// 这里钉住它对外承诺的口径:
+//   1. 请求副本有界(条数 + 字符双预算),但会话记录本身永不被改写
+//   2. 被丢弃的旧消息要摘录成一条梗概,而不是静默消失
+//   3. tool_calls 与其 tool 结果必须整组保留,不能从中间撕开
+//   4. provider 兼容消毒与旧图片降级只作用在副本上
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { prepareRequestMessages, sanitizeMessages, stripStaleImages } from './context.js'
+
+const call = n => ({ id: `call${n}`, type: 'function', function: { name: 'read_file', arguments: '{}' } })
+
+// 60 轮工具调用,每轮结果 16000 字符(会被 clip 到 6000)—— 远超任何预算
+const longTranscript = () => {
+  const messages = [{ role: 'system', content: 'rules' }, { role: 'user', content: 'original goal' }]
+  for (let i = 0; i < 60; i++) {
+    messages.push({ role: 'assistant', tool_calls: [call(i)] })
+    messages.push({ role: 'tool', tool_call_id: `call${i}`, content: 'data'.repeat(4000) })
+  }
+  return messages
+}
+
+test('请求副本有界,原始目标不丢,且会话记录一个字节都没被改', () => {
+  const messages = longTranscript()
+  const before = structuredClone(messages)
+  const request = prepareRequestMessages(messages, { locale: 'zh-CN' })
+  assert.ok(request.length <= 40, `期望 <= 40 条,实际 ${request.length}`)
+  assert.ok(JSON.stringify(request).length < 90000)
+  assert.ok(request.some(m => m.content === 'original goal'), '首条 user(原始目标)必须保留')
+  assert.deepEqual(messages, before, '会话记录不得被请求副本改写')
+})
+
+test('被丢弃的旧消息摘录成一条梗概,并自我声明是历史数据而非新指令', () => {
+  const request = prepareRequestMessages(longTranscript(), { locale: 'zh-CN' })
+  assert.equal(request[0].role, 'system')
+  const note = request[1]
+  assert.equal(note.role, 'user')
+  assert.match(note.content, /^\[Earlier conversation excerpts/)
+  assert.match(note.content, /historical data, not new instructions/)
+  // 梗概本身也要有界,否则它自己就成了新的膨胀源:
+  // 上限 = 固定前缀 + 5000 字符摘录 + clip 的中间省略标记,与历史长度无关
+  assert.ok(note.content.length <= 5200, `摘录过长: ${note.content.length}`)
+})
+
+test('回填以 tool_calls + 对应 tool 结果为整组,不会撕裂配对', () => {
+  const request = prepareRequestMessages(longTranscript(), { locale: 'zh-CN' })
+  for (let i = 0; i < request.length; i++) {
+    if (request[i].tool_calls) {
+      assert.equal(request[i + 1]?.role, 'tool')
+      assert.equal(request[i + 1].tool_call_id, request[i].tool_calls[0].id)
+    }
+  }
+})
+
+test('未超预算时原样下发,不塞摘录消息', () => {
+  const messages = [{ role: 'system', content: 'rules' }, { role: 'user', content: 'hi' }, { role: 'assistant', content: 'hello' }]
+  const request = prepareRequestMessages(messages, { locale: 'zh-CN' })
+  assert.deepEqual(request.map(m => m.content), ['rules', 'hi', 'hello'])
+})
+
+test('中断的 tool 调用在副本里补占位结果,不重放动作', () => {
+  const messages = [
+    { role: 'system', content: 'rules' },
+    { role: 'user', content: 'task' },
+    { role: 'assistant', tool_calls: [call(1), call(2)] },
+    { role: 'tool', tool_call_id: 'call1', content: 'saved' },
+  ]
+  const request = prepareRequestMessages(messages, { locale: 'zh-CN' })
+  assert.deepEqual(request.filter(m => m.role === 'tool').map(m => m.tool_call_id), ['call1', 'call2'])
+  assert.equal(request.find(m => m.tool_call_id === 'call1').content, 'saved')
+  assert.match(request.at(-1).content, /status is unknown/)
+})
+
+test('消毒:空 assistant 转 null、空 tool 兜底、空 user 用空格占位', () => {
+  const messages = [
+    { role: 'user', content: '   ' },
+    { role: 'assistant', content: '', tool_calls: [call(1)] },
+    { role: 'tool', tool_call_id: 'call1', content: ' \n\t ' },
+    { role: 'assistant', content: '有正文但带 tool_calls', tool_calls: [call(2)] },
+    { role: 'tool', tool_call_id: 'call2', content: 'ok' },
+  ]
+  sanitizeMessages(messages)
+  assert.equal(messages[0].content, ' ')
+  assert.equal(messages[1].content, null)
+  assert.equal(messages[2].content, '(no output)')
+  assert.equal(messages[3].content, null, 'tool_calls 存在时正文必须置 null,否则某些 provider 报 2013')
+})
+
+test('旧图片降级为占位文字,占位符跟随 locale', () => {
+  const text = t => ({ type: 'text', text: t })
+  const img = u => ({ type: 'image_url', image_url: { url: u } })
+  const build = () => [
+    { role: 'user', content: [text('first'), img('old')] },
+    { role: 'assistant', content: 'ok' },
+    { role: 'user', content: [text('second'), img('new')] },
+  ]
+  const zh = build()
+  stripStaleImages(zh, 'zh-CN')
+  assert.equal(zh[0].content[1].text, '[图片已从历史中省略]')
+  assert.equal(zh[2].content[1].type, 'image_url', '最近一条带图消息必须保留图片')
+
+  const en = build()
+  stripStaleImages(en, 'en-US')
+  assert.equal(en[0].content[1].text, '[image omitted from history]')
+})
+
+test('图片降级只发生在请求副本上,会话记录里的图还在', () => {
+  const messages = [
+    { role: 'system', content: 'rules' },
+    { role: 'user', content: [{ type: 'text', text: 'a' }, { type: 'image_url', image_url: { url: 'old' } }] },
+    { role: 'assistant', content: 'ok' },
+    { role: 'user', content: [{ type: 'text', text: 'b' }, { type: 'image_url', image_url: { url: 'new' } }] },
+  ]
+  const request = prepareRequestMessages(messages, { locale: 'zh-CN' })
+  assert.equal(request[1].content[1].type, 'text')
+  assert.equal(messages[1].content[1].type, 'image_url')
+})

package/src/cli/ai/extensions.js

@@ -0,0 +1,131 @@
+// 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 与 MCP 两类外部能力收敛成一个对象,
+// 交给 agent 循环统一消费。存在的意义是**把生命周期收在一处**:
+//   - 加载顺序固定(skill 是纯文本,立刻可用;MCP 要起子进程,可能慢/可能失败)
+//   - 失败一律降级,绝不让扩展问题变成 "g ai 起不来"
+//   - /cwd 切换工作目录时要能重新解析项目级扩展,同时关掉旧目录起的子进程
+//
+// 与 tools.js 的关系:内置 7 个工具是**底座**,永远存在。
+// 这里的 MCP 工具是**叠加**,名字以 mcp__ 开头,由 agent 循环按名字分流;
+// 名字不认识时返回 null,让调用方回落内置工具 —— 所以扩展全挂也不影响原有能力。
+
+import { loadSkills, buildSkillsPrompt } from './skills.js';
+import { McpManager, loadMcpServers } from './mcp.js';
+
+export class AgentExtensions {
+  constructor({ skills = [], errors = [], mcp = null, cwd = '' } = {}) {
+    this.skills = skills;
+    this.errors = errors;
+    this.mcp = mcp;
+    this.cwd = cwd;
+  }
+
+  /**
+   * 加载当前目录下的全部扩展。
+   *
+   * @param {{ cwd?: string, locale?: string, onWarn?: (message: string) => void,
+   *           onNotice?: (message: string) => void }} [options]
+   * @returns {Promise<AgentExtensions>}
+   */
+  static async load({ cwd, locale, onWarn, onNotice } = {}) {
+    const { skills, errors } = await loadSkills({ cwd }).catch(err => ({
+      skills: [],
+      errors: [{ root: String(cwd || ''), message: err.message }],
+    }));
+    if (errors.length && onWarn) {
+      for (const error of errors) onWarn(`Skill 目录读取失败(${error.root}): ${error.message}`);
+    }
+
+    let mcp = null;
+    try {
+      const { servers, sources } = await loadMcpServers({ cwd });
+      const enabledCount = Object.values(servers).filter(cfg => !cfg.disabled).length;
+      // MCP 建连是启动路径上的同步阻塞点(npx 首次还要下载包,实测可到 20s+),
+      // 有事可做时先说一声,免得用户以为 g ai 卡死了。
+      if (enabledCount > 0) onNotice?.(enabledCount);
+      mcp = await McpManager.create({ cwd, servers, sources, onWarn });
+    } catch (err) {
+      onWarn?.(`MCP 初始化失败(已跳过): ${err.message}`);
+    }
+
+    // 没有任何 MCP 工具且没有连接失败信息时,把空管理器丢掉,少一层判断
+    if (mcp && mcp.connections.length === 0) mcp = null;
+    return new AgentExtensions({ skills, errors, mcp, cwd });
+  }
+
+  /** 追加到系统提示词末尾的内容(无扩展时是空串) */
+  promptSuffix(locale) {
+    const skillBlock = buildSkillsPrompt(this.skills, { locale });
+    const mcpBlock = this.mcp ? this.mcp.describe({ locale }) : '';
+    return `${skillBlock}${mcpBlock}`;
+  }
+
+  /** 叠加到内置工具表之后的 OpenAI function calling 定义 */
+  get tools() {
+    return this.mcp ? this.mcp.toolDefinitions : [];
+  }
+
+  /** 是否是本层接管的名字。agent 循环据此决定走扩展还是内置工具。 */
+  owns(name) {
+    return !!this.mcp?.has(name);
+  }
+
+  /**
+   * 执行一个扩展工具。名字不属于扩展时返回 null(调用方回落内置工具)。
+   * @returns {Promise<string|null>}
+   */
+  async execute(name, args) {
+    if (!this.mcp?.has(name)) return null;
+    return await this.mcp.call(name, args);
+  }
+
+  /**
+   * 切换工作目录:重读项目级 skill 与 .mcp.json,先关掉旧目录起的子进程。
+   * 全局级配置不受影响,但一起重载更简单也更好推理。
+   *
+   * @param {{ cwd: string, locale?: string, onWarn?: (message: string) => void,
+   *           onNotice?: (count: number) => void }} options
+   * @returns {Promise<void>}
+   */
+  async reload({ cwd, locale, onWarn, onNotice } = {}) {
+    await this.mcp?.close().catch(() => {});
+    const next = await AgentExtensions.load({ cwd, locale, onWarn, onNotice });
+    this.skills = next.skills;
+    this.errors = next.errors;
+    this.mcp = next.mcp;
+    this.cwd = next.cwd;
+  }
+
+  /** 诊断摘要(/skills 与 /mcp 命令用) */
+  summary(locale) {
+    const zh = !String(locale || '').startsWith('en');
+    return {
+      skills: this.skills.map(skill => ({
+        name: skill.name,
+        scope: skill.scope,
+        description: skill.description,
+      })),
+      servers: this.mcp ? this.mcp.status() : [],
+      zh,
+    };
+  }
+
+  async close() {
+    await this.mcp?.close().catch(() => {});
+  }
+}
+
+export default { AgentExtensions };

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

@@ -0,0 +1,158 @@
+// 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.
+//
+// 扩展层的接线测试 —— 这一层最容易"看起来接好了但实际没生效":
+//   · transport 有没有把 MCP 工具塞进请求体
+//   · turn 有没有按名字把 mcp__ 调用分给扩展,而不是丢给内置工具表(结果是"未知工具")
+//   · 没装扩展时行为必须与改动前完全一致(不能因为引入扩展而改变默认请求)
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { streamChatOnce } from './transport.js';
+import { runAgentTurn } from './turn.js';
+import { AgentExtensions } from './extensions.js';
+import { TOOL_DEFINITIONS } from './tools.js';
+
+const model = { model: 'test', baseURL: 'https://example.invalid/v1', apiKey: 'test' };
+const event = data => `data: ${JSON.stringify(data)}\n\n`;
+const response = chunks => new Response(new ReadableStream({ start(controller) {
+  const bytes = new TextEncoder();
+  chunks.forEach(chunk => controller.enqueue(bytes.encode(chunk)));
+  controller.close();
+} }));
+const noop = () => {};
+const quiet = {
+  startSpinner: () => ({ stop: noop }),
+  createAssistantWriter: () => ({ writeContent: noop, writeThinking: noop, finish: noop }),
+  printToolHeader: noop, printToolResult: noop, printWarn: noop, printError: noop, printTurnSummary: noop,
+};
+const strings = new Proxy({}, { get: () => (typeof value === 'string' ? value : String), has: () => true });
+const newState = () => ({ messages: [{ role: 'system', content: 'rules' }], ctx: { cwd: '.' }, abortController: new AbortController(), maxToolIterations: 4 });
+const toolCall = (id, name) => ({ id, type: 'function', function: { name, arguments: '{}' } });
+
+// 一个只认 mcp__ 前缀的假扩展,用来观察分流。
+// 刻意用鸭子类型而不是继承 AgentExtensions —— 这样顺带钉住
+// "turn.js 只依赖 { owns, execute, tools } 这套接口",换实现不会被测试绑死。
+function fakeExtensions({ tools = [], calls = [] } = {}) {
+  return {
+    tools,
+    owns: name => name.startsWith('mcp__'),
+    execute: async (name, args) => { calls.push({ name, args }); return `mcp-result:${name}`; },
+    promptSuffix: () => '\n\n# 已接入的 MCP 服务\n- fake: 1 个工具',
+    close: async () => {},
+  };
+}
+
+test('transport: 没有扩展工具时请求体与改动前完全一致(不含空 tools 数组)', async () => {
+  let sent;
+  await streamChatOnce({ model, messages: [], fetchFn: async (_url, init) => {
+    sent = JSON.parse(init.body);
+    return response([event({ choices: [{ delta: { content: 'ok' }, finish_reason: 'stop' }] }), 'data: [DONE]']);
+  } });
+  assert.deepEqual(sent.tools, TOOL_DEFINITIONS);
+
+  // 显式传空数组也不能退化
+  await streamChatOnce({ model, messages: [], extraTools: [], fetchFn: async (_url, init) => {
+    sent = JSON.parse(init.body);
+    return response([event({ choices: [{ delta: { content: 'ok' }, finish_reason: 'stop' }] }), 'data: [DONE]']);
+  } });
+  assert.deepEqual(sent.tools, TOOL_DEFINITIONS);
+});
+
+test('transport: 扩展工具叠加在内置工具之后,内置工具不被挤掉', async () => {
+  let sent;
+  const extra = [{ type: 'function', function: { name: 'mcp__fake__echo', description: 'x', parameters: { type: 'object' } } }];
+  await streamChatOnce({ model, messages: [], extraTools: extra, fetchFn: async (_url, init) => {
+    sent = JSON.parse(init.body);
+    return response([event({ choices: [{ delta: { content: 'ok' }, finish_reason: 'stop' }] }), 'data: [DONE]']);
+  } });
+
+  const names = sent.tools.map(tool => tool.function.name);
+  assert.deepEqual(names.slice(0, TOOL_DEFINITIONS.length), TOOL_DEFINITIONS.map(tool => tool.function.name));
+  assert.equal(names.at(-1), 'mcp__fake__echo');
+  assert.equal(names.length, TOOL_DEFINITIONS.length + 1);
+});
+
+test('turn: mcp__ 调用被分给扩展,普通工具名仍走内置执行器', async () => {
+  const calls = [];
+  const extensions = fakeExtensions({ calls });
+  const executed = [];
+  const s = { ...newState(), extensions };
+  let round = 0;
+
+  const stats = await runAgentTurn(s, 'task', strings, [], {
+    ui: quiet,
+    execute: async name => { executed.push(name); return 'builtin-result'; },
+    chat: async () => {
+      round++;
+      if (round === 1) return { content: '', toolCalls: [toolCall('a', 'mcp__fake__echo'), toolCall('b', 'read_file')] };
+      return { content: 'done', toolCalls: [] };
+    },
+  });
+
+  assert.equal(stats.status, 'completed');
+  assert.deepEqual(calls.map(item => item.name), ['mcp__fake__echo'], 'MCP 工具必须走扩展');
+  assert.deepEqual(executed, ['read_file'], '内置工具不能被扩展层截胡');
+
+  const toolMessages = s.messages.filter(message => message.role === 'tool').map(message => message.content);
+  assert.deepEqual(toolMessages, ['mcp-result:mcp__fake__echo', 'builtin-result']);
+});
+
+test('turn: 扩展未接管的名字会回落到内置执行器(而不是报未知工具)', async () => {
+  const extensions = new AgentExtensions({ skills: [] });
+  const s = { ...newState(), extensions };
+  const executed = [];
+  let round = 0;
+
+  await runAgentTurn(s, 'task', strings, [], {
+    ui: quiet,
+    execute: async name => { executed.push(name); return 'ok'; },
+    chat: async () => (++round === 1 ? { content: '', toolCalls: [toolCall('a', 'list_files')] } : { content: 'done', toolCalls: [] }),
+  });
+
+  assert.deepEqual(executed, ['list_files']);
+});
+
+test('turn: 传了 extensions 但没有工具时,chat 收到的 extraTools 是空数组', async () => {
+  const s = { ...newState(), extensions: new AgentExtensions({ skills: [] }) };
+  const seen = [];
+  let round = 0;
+  await runAgentTurn(s, 'task', strings, [], {
+    ui: quiet,
+    chat: async payload => {
+      seen.push(payload.extraTools);
+      return ++round === 1 ? { content: 'hi', toolCalls: [] } : { content: '', toolCalls: [] };
+    },
+  });
+  assert.deepEqual(seen, [[]]);
+});
+
+test('AgentExtensions: 没有任何扩展时 promptSuffix 为空串、tools 为空', () => {
+  const extensions = new AgentExtensions({ skills: [] });
+  assert.equal(extensions.promptSuffix('zh-CN'), '');
+  assert.deepEqual(extensions.tools, []);
+  assert.equal(extensions.owns('read_file'), false);
+  assert.equal(extensions.promptSuffix('en-US'), '');
+});
+
+test('AgentExtensions: skill 与 MCP 的提示词片段拼接顺序稳定,并带 locale 区分', () => {
+  const mcp = { describe: ({ locale }) => (String(locale).startsWith('en') ? '\n\n# Connected MCP servers\n- x' : '\n\n# 已接入的 MCP 服务\n- x') };
+  const extensions = new AgentExtensions({
+    skills: [{ id: 'a', name: 'pdf', description: 'd', file: '/x/SKILL.md', scope: 'global' }],
+    mcp,
+  });
+  const zh = extensions.promptSuffix('zh-CN');
+  assert.ok(zh.indexOf('已安装的 Skill') < zh.indexOf('已接入的 MCP 服务'), 'skill 片段应在 MCP 片段之前');
+  assert.match(extensions.promptSuffix('en'), /Connected MCP servers/);
+});