dsh-brain/lib/tools.js

287 行
14 KiB
JavaScript
原始文件 Blame 文件历史

此文件含有模棱两可的 Unicode 字符

此文件含有可能会与其他字符混淆的 Unicode 字符。 如果您是想特意这样的,可以安全地忽略该警告。 使用 Escape 按钮显示他们。

/**
* 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)];
}