QQ-dsh/vendor/dsh-brain/lib/tools.js

287 lines
14 KiB
JavaScript
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

/**
* Agent-facing memory tools.
*
* These definitions are hand-written `ToolDefinition` objects rather than
* `defineTool(...)` calls: `defineTool` only compiles an authoring DSL into the
* same raw JSON Schema, and importing `@deepseek-ai/dsh-tools` at runtime would
* risk a second module instance (and a second class identity) inside a linked
* plugin.
*
* Failure contract: `execute` throws and the registry turns that into
* `isError: true`. A missing token is a normal, explainable failure — never a
* crash in the host.
*/
import { randomUUID } from 'node:crypto';
import { describeError } from "./api.js";
/** Sectors the service accepts for `metadata.primary_sector`. */
export const SECTORS = ['semantic', 'episodic', 'procedural', 'emotional', 'reflective'];
/** Trim a memory body down to a display-sized snippet. */
function snippet(text, limit = 600) {
if (typeof text !== 'string')
return '';
if (text.length <= limit)
return text;
return `${text.slice(0, limit)}…`;
}
/** Project one hit into the compact shape returned to the model. */
function toHitView(hit) {
return {
id: hit.id,
content: snippet(hit.content),
tags: hit.tags ?? [],
project_id: hit.project_id ?? null,
sector: hit.primary_sector ?? null,
revision: hit.revision ?? null,
created_at: hit.created_at ?? null,
};
}
/** Render any tool value as one JSON text block. */
function renderJson(_args, value) {
const text = typeof value === 'string' ? value : JSON.stringify(value, null, 2);
return [{ type: 'text', text }];
}
/** Assert the memory scope is usable, or throw a message the model can act on. */
function requireMemoryToken(deps) {
if (!deps.settings().enabled) {
throw new Error('云端记忆插件当前已禁用(enabled=false)。请在 /dsh-brain 页面开启后再试。');
}
const token = deps.memoryToken();
if (token === '') {
throw new Error('未配置记忆令牌。请在 /dsh-brain 页面填入 mem_… 或 cmt_… 记忆令牌(需要 memory:read / memory:write 权限)。');
}
return token;
}
/** Search stored memories by keyword. */
function searchTool(deps) {
return {
name: 'memory_search',
description: '在云端长期记忆库中按关键词检索历史记忆片段。返回命中的记忆 id、内容摘要、标签与所属项目;' +
'需要更多正文时用 memory_read 按 id 取全文。纯关键词匹配,不会做语义相似度检索。',
parameters: {
type: 'object',
properties: {
query: { type: 'string', description: '检索关键词或短语(必填)。' },
k: { type: 'integer', description: '最多返回条数,默认取配置值(1..1000)。' },
project_id: { type: 'string', description: '可选:只在这些项目 id 内检索。' },
},
required: ['query'],
additionalProperties: false,
},
output: {
schema: {
type: 'object',
properties: {
query: { type: 'string' },
total: { type: 'number' },
search_mode: { type: 'string' },
matches: { type: 'array', items: { type: 'object' } },
},
required: ['query', 'matches'],
additionalProperties: true,
},
render: renderJson,
},
async execute(args) {
requireMemoryToken(deps);
const query = typeof args.query === 'string' ? args.query.trim() : '';
if (query === '')
throw new Error('query 不能为空。');
const requested = typeof args.k === 'number' && Number.isFinite(args.k) ? Math.trunc(args.k) : deps.settings().defaultK;
const k = Math.min(1000, Math.max(1, requested));
const project = typeof args.project_id === 'string' && args.project_id !== '' ? args.project_id : undefined;
const result = await deps.client().search(query, k, project);
if (!result.ok)
throw new Error(`检索失败:${describeError(result.error)}`);
const matches = result.data.matches ?? [];
return {
query,
total: result.data.total ?? matches.length,
search_mode: result.data.search_mode ?? 'keyword',
matches: matches.map(toHitView),
};
},
};
}
/** Read one memory by id. */
function readTool(deps) {
return {
name: 'memory_read',
description: '按 id 读取一条云端记忆的完整内容(正文、标签、项目、修订号与时间戳)。id 可先用 memory_search 或 memory_list 获得。',
parameters: {
type: 'object',
properties: {
id: { type: 'string', description: '记忆条目 id(必填)。' },
},
required: ['id'],
additionalProperties: false,
},
output: {
schema: { type: 'object', properties: { id: { type: 'string' }, content: { type: 'string' } }, required: ['id'], additionalProperties: true },
render: renderJson,
},
async execute(args) {
requireMemoryToken(deps);
const id = typeof args.id === 'string' ? args.id.trim() : '';
if (id === '')
throw new Error('id 不能为空。');
const result = await deps.client().read(id);
if (!result.ok) {
if (result.error.status === 404)
throw new Error(`没有找到 id=${id} 的记忆(可能已删除)。`);
throw new Error(`读取失败:${describeError(result.error)}`);
}
return result.data;
},
};
}
/** Store one new memory. */
function addTool(deps) {
return {
name: 'memory_add',
description: '向云端长期记忆库写入一条新记忆。content 上限 7000 字节,适合存结论、决策、待办与可复用事实;' +
'不要写入密钥、令牌或完整源码。写入用 operation_id 保证幂等,重复调用不会产生重复条目。',
parameters: {
type: 'object',
properties: {
content: { type: 'string', description: '要长期保存的正文(≤7000 字节)。' },
tags: { type: 'array', items: { type: 'string' }, description: '可选标签,最多 30 个,每个不超过 100 字符。' },
project_id: { type: 'string', description: '可选:归属项目 id(≤128 字符)。' },
sector: { type: 'string', enum: [...SECTORS], description: '可选:记忆分类(semantic/episodic/procedural/emotional/reflective)。' },
operation_id: { type: 'string', description: '可选:幂等键(uuid);省略时自动生成。重试同一次写入时请复用同一个值。' },
},
required: ['content'],
additionalProperties: false,
},
output: {
schema: {
type: 'object',
properties: {
id: { type: 'string' },
revision: { type: 'number' },
remote_saved: { type: 'boolean' },
state: { type: 'string' },
operation_id: { type: 'string' },
},
required: ['id'],
additionalProperties: true,
},
render: renderJson,
},
async execute(args) {
requireMemoryToken(deps);
const content = typeof args.content === 'string' ? args.content : '';
if (content.trim() === '')
throw new Error('content 不能为空。');
const bytes = Buffer.byteLength(content, 'utf8');
if (bytes > 7000)
throw new Error(`content 过大:${bytes} 字节,上限 7000 字节。`);
const rawTags = Array.isArray(args.tags) ? args.tags : [];
const tags = rawTags.filter((tag) => typeof tag === 'string' && tag !== '').slice(0, 30);
const project = typeof args.project_id === 'string' && args.project_id !== '' ? args.project_id : undefined;
const sector = typeof args.sector === 'string' && SECTORS.includes(args.sector) ? args.sector : undefined;
const candidate = typeof args.operation_id === 'string' ? args.operation_id.trim() : '';
const operationId = /^[0-9a-f-]{36}$/i.test(candidate) ? candidate : randomUUID();
const result = await deps.client().add({ content, tags, project, sector, operationId });
if (!result.ok) {
if (result.error.status === 409 && result.error.code === 'storage_not_configured') {
throw new Error('云端主存储尚未配置(WebDAV),服务端拒绝写入。请先在云端设置里完成存储配置。');
}
throw new Error(`写入失败:${describeError(result.error)}`);
}
return {
id: result.data.id,
revision: result.data.revision,
remote_saved: result.data.remote_saved,
state: result.data.state,
operation_id: result.data.operation_id ?? operationId,
};
},
};
}
/** List recent memories. */
function listTool(deps) {
return {
name: 'memory_list',
description: '按时间倒序列出云端记忆(可分页,可按项目过滤)。适合浏览最近保存了什么,再决定是否 memory_read 取全文。',
parameters: {
type: 'object',
properties: {
limit: { type: 'integer', description: '返回条数,默认 20,上限 100。' },
offset: { type: 'integer', description: '跳过条数,默认 0。' },
project_id: { type: 'string', description: '可选:只看某个项目。' },
},
additionalProperties: false,
},
output: {
schema: { type: 'object', properties: { total: { type: 'number' }, items: { type: 'array', items: { type: 'object' } } }, required: ['items'], additionalProperties: true },
render: renderJson,
},
async execute(args) {
requireMemoryToken(deps);
const rawLimit = typeof args.limit === 'number' && Number.isFinite(args.limit) ? Math.trunc(args.limit) : 20;
const limit = Math.min(100, Math.max(1, rawLimit));
const rawOffset = typeof args.offset === 'number' && Number.isFinite(args.offset) ? Math.trunc(args.offset) : 0;
const offset = Math.max(0, rawOffset);
const project = typeof args.project_id === 'string' && args.project_id !== '' ? args.project_id : undefined;
const result = await deps.client().list({ limit, offset, project });
if (!result.ok)
throw new Error(`列表读取失败:${describeError(result.error)}`);
const items = result.data.items ?? [];
return { total: result.data.total ?? items.length, items: items.map(toHitView) };
},
};
}
/** List projects known to the account. */
function projectsTool(deps) {
return {
name: 'memory_projects',
description: '列出云端账号下的记忆项目(project_id 与名称),用于给 memory_add 选择归属项目。',
parameters: { type: 'object', properties: {}, additionalProperties: false },
output: {
schema: { type: 'object', properties: { projects: { type: 'array', items: { type: 'object' } } }, required: ['projects'], additionalProperties: true },
render: renderJson,
},
async execute() {
requireMemoryToken(deps);
const result = await deps.client().projects();
if (!result.ok)
throw new Error(`项目列表读取失败:${describeError(result.error)}`);
return { projects: result.data.projects ?? [] };
},
};
}
/** Build every memory tool for one plugin instance. */
export function createMemoryTools(deps) {
return [searchTool(deps), readTool(deps), addTool(deps), listTool(deps), projectsTool(deps)];
}
/** List the cloud skill center inventory (skills sync keeps local copies current). */
function skillListTool(deps) {
return {
name: 'skill_list',
description: '列出云端技能中心的全部技能(名称、说明、版本)。技能会自动同步到本机技能目录,由 DSH 直接加载;此工具只用于查看云端有哪些技能。',
parameters: { type: 'object', properties: {}, additionalProperties: false },
output: {
schema: { type: 'object', properties: { skills: { type: 'array', items: { type: 'object' } } }, required: ['skills'], additionalProperties: true },
render: renderJson,
},
async execute() {
requireMemoryToken(deps);
const result = await deps.client().listSkills();
if (!result.ok)
throw new Error(`技能列表读取失败:${describeError(result.error)}`);
const skills = (result.data.items ?? []).map((item) => ({
name: item.name,
description: item.description ?? '',
revision: item.revision ?? null,
files: item.files ?? null,
enabled: item.enabled ?? true,
}));
return { skills };
},
};
}
/** Build the skill-facing tools for one plugin instance. */
export function createSkillTools(deps) {
return [skillListTool(deps)];
}