@getnote/mcp 1.8.0 → 1.9.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.github/workflows/release.yml +2 -2
- package/README.md +11 -0
- package/dist/client.d.ts +106 -25
- package/dist/client.d.ts.map +1 -1
- package/dist/client.js +18 -7
- package/dist/discovery.d.ts +101 -0
- package/dist/discovery.d.ts.map +1 -0
- package/dist/discovery.js +124 -0
- package/dist/index.js +52 -7
- package/package.json +1 -1
- package/src/client.ts +73 -27
- package/src/discovery.ts +91 -0
- package/src/index.ts +41 -7
- package/test/client.test.mjs +13 -0
- package/test/discovery-validation.test.mjs +19 -0
- package/test/discovery.test.mjs +70 -0
- package/test/original.test.mjs +46 -0
package/dist/index.js
CHANGED
|
@@ -131,14 +131,32 @@ function snowflakeID(value, field) {
|
|
|
131
131
|
throw new Error(`${field} must be a decimal string; only legacy integers within JavaScript's safe range are accepted`);
|
|
132
132
|
}
|
|
133
133
|
// ─── Tool Definitions ────────────────────────────────────────────────────────
|
|
134
|
+
const noteDiscoveryProperties = {
|
|
135
|
+
page: { type: "integer", minimum: 1, description: "知识库内可用页码;与 cursor 互斥" },
|
|
136
|
+
source: { type: "string", description: "来源平台精确筛选,如 dedao" },
|
|
137
|
+
note_type: { type: "string", description: "笔记真实类型精确筛选,如 ref" },
|
|
138
|
+
reference_resource_type: { type: "string", description: "引用资源类型,如 ebook、course_article、audio_book" },
|
|
139
|
+
reference_resource_id: { type: "string", description: "引用资源 ID,必须字符串;同时传 source 和 reference_resource_type" },
|
|
140
|
+
reference_article_url: { type: "string", description: "文章 URL 精确筛选,保留 query 和 fragment" },
|
|
141
|
+
topic_id: { type: "string", description: "知识库 ID,限定授权范围" },
|
|
142
|
+
page_size: { type: "integer", minimum: 1, maximum: 100, description: "每页 1–100 条,默认 20" },
|
|
143
|
+
...Object.fromEntries(["created_from", "created_to", "edited_from", "edited_to", "record_updated_from", "record_updated_to"].map(key => [key, { type: "string", description: "RFC3339 带时区,from 包含、to 不包含;三种时间轴独立" }])),
|
|
144
|
+
};
|
|
145
|
+
const knowledgeLookupProperties = {
|
|
146
|
+
query: { type: "string", description: "只匹配知识库名/书名,不匹配作者;与 author 同时传时为 AND。多候选须核对书名、作者和 book_id" },
|
|
147
|
+
author: { type: "string", description: "书籍作者,限 BOOKSPACE;只有作者线索时只传 author,不猜书名或把作者填进 query" },
|
|
148
|
+
book_id: { type: "string", description: "书籍 ID 字符串,限 BOOKSPACE" },
|
|
149
|
+
page_size: noteDiscoveryProperties.page_size,
|
|
150
|
+
};
|
|
134
151
|
const TOOLS = [
|
|
135
152
|
// ── Notes ──
|
|
136
153
|
{
|
|
137
154
|
name: "list_notes",
|
|
138
|
-
description: "
|
|
155
|
+
description: "按来源、引用资源或知识库查找笔记。列表只返回定位信息;需要正文和完整元数据时调用 get_note。新查询须核对 meta.capabilities、applied_filters,按 pagination.next_cursor 翻页到 has_more=false 才能说全量完成。total_count=null 表示未知,不能用本页条数代替全库总数。",
|
|
139
156
|
inputSchema: {
|
|
140
157
|
type: "object",
|
|
141
158
|
properties: {
|
|
159
|
+
...noteDiscoveryProperties,
|
|
142
160
|
cursor: {
|
|
143
161
|
type: "string",
|
|
144
162
|
description: "翻页游标。首次不传;后续将上一次响应的 cursor 字段原样传入即可,无需任何转换。",
|
|
@@ -149,7 +167,7 @@ const TOOLS = [
|
|
|
149
167
|
},
|
|
150
168
|
{
|
|
151
169
|
name: "get_note",
|
|
152
|
-
description: "获取指定笔记的详细内容,包括正文、标签、附件、音频转录、网页链接等。\n\n**字段语义说明(AI Agent 重要参考)**:\n`content` 通常是 AI 总结,不一定是原文。不同类型笔记的原文字段如下:\n- 普通文字笔记(plain_text):原文 = `note.content`\n- 链接/网页笔记(link):原文 = `note.web_page.content`,AI 总结 = `note.content`\n- 录音笔记(audio/local_audio
|
|
170
|
+
description: "获取指定笔记的详细内容,包括正文、标签、附件、音频转录、网页链接等。\n\n**字段语义说明(AI Agent 重要参考)**:\n`content` 通常是 AI 总结,不一定是原文。不同类型笔记的原文字段如下:\n- 引用笔记(ref):原文 = `note.ref_content`,`note.content` 是个人评论\n- 普通文字笔记(plain_text):原文 = `note.content`\n- 链接/网页笔记(link):原文 = `note.web_page.content`,AI 总结 = `note.content`\n- 录音笔记(audio/local_audio):转写原文 = `note.audio.original`,AI 总结 = `note.content`\n\n用户要求'读原文'时,先看 `note.note_type`,再按上述对应关系取字段。",
|
|
153
171
|
inputSchema: {
|
|
154
172
|
type: "object",
|
|
155
173
|
properties: {
|
|
@@ -168,7 +186,7 @@ const TOOLS = [
|
|
|
168
186
|
},
|
|
169
187
|
{
|
|
170
188
|
name: "get_note_original",
|
|
171
|
-
description: "
|
|
189
|
+
description: "直接读取笔记原文。引用笔记返回 ref_content,链接笔记返回网页原文,录音笔记返回转写原文,文字笔记返回正文;无原文或不支持的类型会报错。",
|
|
172
190
|
inputSchema: { type: "object", properties: { id: { type: ["string", "number"], description: "笔记 ID,推荐十进制字符串" } }, required: ["id"] },
|
|
173
191
|
},
|
|
174
192
|
{
|
|
@@ -351,6 +369,7 @@ const TOOLS = [
|
|
|
351
369
|
inputSchema: {
|
|
352
370
|
type: "object",
|
|
353
371
|
properties: {
|
|
372
|
+
...knowledgeLookupProperties,
|
|
354
373
|
page: {
|
|
355
374
|
type: "number",
|
|
356
375
|
description: "页码,从 1 开始(默认 1)",
|
|
@@ -390,10 +409,11 @@ const TOOLS = [
|
|
|
390
409
|
},
|
|
391
410
|
{
|
|
392
411
|
name: "list_topic_notes",
|
|
393
|
-
description: "
|
|
412
|
+
description: "列出知识库内可访问的笔记,支持来源、引用资源、时间筛选。列表只返回定位信息;需要正文和完整元数据时调用 get_note。按 pagination.next_page 翻页;去重 ID,重复游标/页码、无进展或中途失败不能声称全量完成。",
|
|
394
413
|
inputSchema: {
|
|
395
414
|
type: "object",
|
|
396
415
|
properties: {
|
|
416
|
+
...noteDiscoveryProperties,
|
|
397
417
|
topic_id: {
|
|
398
418
|
type: "string",
|
|
399
419
|
description: "知识库 ID",
|
|
@@ -710,6 +730,7 @@ const TOOLS = [
|
|
|
710
730
|
inputSchema: {
|
|
711
731
|
type: "object",
|
|
712
732
|
properties: {
|
|
733
|
+
...knowledgeLookupProperties,
|
|
713
734
|
page: {
|
|
714
735
|
type: "number",
|
|
715
736
|
description: "页码,从 1 开始,默认 1",
|
|
@@ -783,7 +804,7 @@ async function handleTool(name, input, client) {
|
|
|
783
804
|
// ── Notes ──
|
|
784
805
|
case "list_notes": {
|
|
785
806
|
const cursor = input.cursor;
|
|
786
|
-
return client.listNotes({ cursor: cursor === "0" ? undefined : cursor });
|
|
807
|
+
return client.listNotes({ ...input, cursor: cursor === "0" ? undefined : cursor });
|
|
787
808
|
}
|
|
788
809
|
case "get_note": {
|
|
789
810
|
return client.getNote(snowflakeID(input.id, "id"), input.image_quality);
|
|
@@ -791,10 +812,31 @@ async function handleTool(name, input, client) {
|
|
|
791
812
|
case "get_note_original": {
|
|
792
813
|
const result = await client.getNote(snowflakeID(input.id, "id"));
|
|
793
814
|
const note = result.note;
|
|
794
|
-
|
|
815
|
+
let original;
|
|
816
|
+
let original_source;
|
|
817
|
+
switch (note.note_type) {
|
|
818
|
+
case "ref":
|
|
819
|
+
original = note.ref_content;
|
|
820
|
+
original_source = "ref_content";
|
|
821
|
+
break;
|
|
822
|
+
case "plain_text":
|
|
823
|
+
original = note.content;
|
|
824
|
+
original_source = "content";
|
|
825
|
+
break;
|
|
826
|
+
case "link":
|
|
827
|
+
original = note.web_page?.content;
|
|
828
|
+
original_source = "web_page.content";
|
|
829
|
+
break;
|
|
830
|
+
case "audio":
|
|
831
|
+
case "local_audio":
|
|
832
|
+
original = note.audio?.original;
|
|
833
|
+
original_source = "audio.original";
|
|
834
|
+
break;
|
|
835
|
+
default: throw new Error(`Unsupported note type for original content: ${note.note_type}`);
|
|
836
|
+
}
|
|
795
837
|
if (!original)
|
|
796
838
|
throw new Error("Original content is not available for this note");
|
|
797
|
-
return { id: note.id, note_type: note.note_type, title: note.title, original };
|
|
839
|
+
return { id: note.id, note_type: note.note_type, title: note.title, original, original_source };
|
|
798
840
|
}
|
|
799
841
|
case "get_note_transcript": {
|
|
800
842
|
const result = await client.getNote(snowflakeID(input.id, "id"));
|
|
@@ -883,6 +925,7 @@ async function handleTool(name, input, client) {
|
|
|
883
925
|
// ── Knowledge ──
|
|
884
926
|
case "list_topics": {
|
|
885
927
|
return client.listTopics({
|
|
928
|
+
...input,
|
|
886
929
|
page: input.page,
|
|
887
930
|
scope: input.scope,
|
|
888
931
|
});
|
|
@@ -896,6 +939,7 @@ async function handleTool(name, input, client) {
|
|
|
896
939
|
}
|
|
897
940
|
case "list_topic_notes": {
|
|
898
941
|
return client.listTopicNotes({
|
|
942
|
+
...input,
|
|
899
943
|
topic_id: input.topic_id,
|
|
900
944
|
page: input.page,
|
|
901
945
|
});
|
|
@@ -1017,6 +1061,7 @@ async function handleTool(name, input, client) {
|
|
|
1017
1061
|
// ── Knowledge / Subscribe ──
|
|
1018
1062
|
case "list_subscribe_topics": {
|
|
1019
1063
|
return client.listSubscribeTopics({
|
|
1064
|
+
...input,
|
|
1020
1065
|
page: input.page,
|
|
1021
1066
|
scope: input.scope,
|
|
1022
1067
|
});
|
package/package.json
CHANGED
package/src/client.ts
CHANGED
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import axios, { AxiosInstance, AxiosError } from "axios";
|
|
2
|
+
import { discoveryContract, verifyDiscovery, NoteDiscoveryOptions, LookupOptions, DiscoveryKind } from "./discovery";
|
|
2
3
|
|
|
3
4
|
const DEFAULT_BASE_URL = "https://openapi.biji.com/open/api/v1";
|
|
4
5
|
|
|
@@ -21,12 +22,11 @@ function normalizeBaseURL(value?: string): string {
|
|
|
21
22
|
*/
|
|
22
23
|
export function parseJsonPreservingLargeIntegerStrings(data: unknown) {
|
|
23
24
|
if (typeof data !== "string" || data.trim() === "") return data;
|
|
25
|
+
// Match complete JSON strings first so numeric text inside note bodies is
|
|
26
|
+
// never rewritten. Consume full number tokens to preserve decimals/exponents.
|
|
24
27
|
const safe = data.replace(
|
|
25
|
-
/"(
|
|
26
|
-
|
|
27
|
-
).replace(
|
|
28
|
-
/([:[,]\s*)(-?\d{16,})(?=\s*[,}\]])/g,
|
|
29
|
-
'$1"$2"'
|
|
28
|
+
/"(?:\\[\s\S]|[^"\\])*"|-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?/g,
|
|
29
|
+
token => /^-?\d{16,}$/.test(token) ? JSON.stringify(token) : token
|
|
30
30
|
);
|
|
31
31
|
return JSON.parse(safe);
|
|
32
32
|
}
|
|
@@ -94,10 +94,14 @@ export class GetNoteClient {
|
|
|
94
94
|
params?: Record<string, unknown>,
|
|
95
95
|
data?: unknown
|
|
96
96
|
): Promise<T> {
|
|
97
|
+
const kinds: Record<string, DiscoveryKind> = { "/resource/note/list": "notes", "/resource/note/detail": "detail", "/resource/knowledge/notes": "topicNotes", "/resource/knowledge/list": "topics", "/resource/knowledge/subscribe/list": "topics" };
|
|
98
|
+
const contract = method === "GET" && kinds[path] ? discoveryContract(kinds[path], params || {}) : undefined;
|
|
99
|
+
if (contract) params = contract.params;
|
|
97
100
|
try {
|
|
98
101
|
const res = await this.http.request<{
|
|
99
102
|
success: boolean;
|
|
100
103
|
data: T;
|
|
104
|
+
meta?: { capabilities?: string[]; [key: string]: unknown };
|
|
101
105
|
error?: APIErrorBody;
|
|
102
106
|
request_id?: string;
|
|
103
107
|
}>({
|
|
@@ -122,6 +126,11 @@ export class GetNoteClient {
|
|
|
122
126
|
);
|
|
123
127
|
}
|
|
124
128
|
|
|
129
|
+
if (contract) verifyDiscovery(body, contract);
|
|
130
|
+
// Keep the verified envelope capabilities visible to the Agent.
|
|
131
|
+
if (body.meta?.capabilities && typeof body.data === "object" && body.data !== null && !Array.isArray(body.data)) {
|
|
132
|
+
return { ...body.data, meta: body.meta };
|
|
133
|
+
}
|
|
125
134
|
return body.data;
|
|
126
135
|
} catch (err) {
|
|
127
136
|
if (err instanceof GetNoteAPIError) throw err;
|
|
@@ -153,10 +162,8 @@ export class GetNoteClient {
|
|
|
153
162
|
|
|
154
163
|
// ─── Notes ───────────────────────────────────────────────────────────────
|
|
155
164
|
|
|
156
|
-
async listNotes(params:
|
|
157
|
-
return this.request<ListNotesResp>("GET", "/resource/note/list", {
|
|
158
|
-
...(params.cursor ? { cursor: params.cursor } : {}),
|
|
159
|
-
});
|
|
165
|
+
async listNotes(params: NoteDiscoveryOptions) {
|
|
166
|
+
return this.request<ListNotesResp>("GET", "/resource/note/list", { ...params });
|
|
160
167
|
}
|
|
161
168
|
|
|
162
169
|
async getNote(id: string | number, image_quality?: string) {
|
|
@@ -289,9 +296,9 @@ export class GetNoteClient {
|
|
|
289
296
|
|
|
290
297
|
// ─── Knowledge / Topics ─────────────────────────────────────────────────
|
|
291
298
|
|
|
292
|
-
async listTopics(params?:
|
|
299
|
+
async listTopics(params?: LookupOptions) {
|
|
293
300
|
return this.request<ListTopicsResp>("GET", "/resource/knowledge/list", {
|
|
294
|
-
|
|
301
|
+
...params,
|
|
295
302
|
scope: params?.scope ?? "DEFAULT",
|
|
296
303
|
});
|
|
297
304
|
}
|
|
@@ -305,11 +312,11 @@ export class GetNoteClient {
|
|
|
305
312
|
);
|
|
306
313
|
}
|
|
307
314
|
|
|
308
|
-
async listTopicNotes(params: { topic_id: string
|
|
315
|
+
async listTopicNotes(params: NoteDiscoveryOptions & { topic_id: string }) {
|
|
309
316
|
return this.request<ListTopicNotesResp>(
|
|
310
317
|
"GET",
|
|
311
318
|
"/resource/knowledge/notes",
|
|
312
|
-
{
|
|
319
|
+
{ ...params }
|
|
313
320
|
);
|
|
314
321
|
}
|
|
315
322
|
|
|
@@ -422,11 +429,11 @@ export class GetNoteClient {
|
|
|
422
429
|
);
|
|
423
430
|
}
|
|
424
431
|
|
|
425
|
-
async listSubscribeTopics(params:
|
|
432
|
+
async listSubscribeTopics(params: LookupOptions) {
|
|
426
433
|
return this.request<ListSubscribeTopicsResp>(
|
|
427
434
|
"GET",
|
|
428
435
|
"/resource/knowledge/subscribe/list",
|
|
429
|
-
{
|
|
436
|
+
{ ...params, scope: params.scope ?? "DEFAULT" }
|
|
430
437
|
);
|
|
431
438
|
}
|
|
432
439
|
|
|
@@ -455,21 +462,44 @@ export interface TagInfo {
|
|
|
455
462
|
type: "ai" | "manual" | "system";
|
|
456
463
|
}
|
|
457
464
|
|
|
458
|
-
export interface
|
|
465
|
+
export interface NoteReference {
|
|
466
|
+
source: string; resource_type: string; ptype: number; resource_id?: string;
|
|
467
|
+
title?: string; author?: string; url?: string; original_note_id?: string;
|
|
468
|
+
is_source_private: boolean; book_id?: string;
|
|
469
|
+
article?: { title?: string; url?: string };
|
|
470
|
+
location?: { chapter_id?: string; chapter_name?: string; page?: number; start_offset?: number; end_offset?: number };
|
|
471
|
+
}
|
|
472
|
+
export interface BookInfo { book_id: string; title: string; author: string; platform?: string; source?: string; isbn?: string }
|
|
473
|
+
export interface DiscoveryMetadata {
|
|
474
|
+
display_title?: string;
|
|
475
|
+
reference?: NoteReference;
|
|
476
|
+
timestamps?: { created_at?: string; edited_at?: string; record_updated_at?: string };
|
|
477
|
+
preview?: { text: string; source: string; truncated: boolean };
|
|
478
|
+
content_state?: { content: string; ref_content: string };
|
|
479
|
+
metadata_state?: { reference: string; topics: string };
|
|
480
|
+
}
|
|
481
|
+
export interface DiscoveryResponse {
|
|
482
|
+
meta?: { capabilities: string[]; timestamp?: number };
|
|
483
|
+
pagination?: { mode: "page" | "cursor"; page: number | null; page_size: number; returned_count: number; total_count: number | null; has_more: boolean; next_page: number | null; next_cursor: string | null };
|
|
484
|
+
applied_filters?: Record<string, unknown>;
|
|
485
|
+
warnings?: unknown[];
|
|
486
|
+
}
|
|
487
|
+
|
|
488
|
+
export interface NoteItem extends DiscoveryMetadata {
|
|
459
489
|
/**
|
|
460
490
|
* Note ID. Returned as string because the actual values exceed
|
|
461
491
|
* Number.MAX_SAFE_INTEGER. See parseJsonPreservingLargeIntegerStrings.
|
|
462
492
|
*/
|
|
463
493
|
id: string;
|
|
464
494
|
title: string;
|
|
465
|
-
content
|
|
495
|
+
content?: string;
|
|
466
496
|
ref_content?: string;
|
|
467
497
|
note_type: string;
|
|
468
498
|
source: string;
|
|
469
499
|
tags: TagInfo[];
|
|
470
500
|
parent_id?: string;
|
|
471
501
|
children_count?: number;
|
|
472
|
-
topics?: { id: string; name: string }[];
|
|
502
|
+
topics?: { id: string; name: string; scope?: string; book_info?: BookInfo }[];
|
|
473
503
|
is_child_note?: boolean;
|
|
474
504
|
created_at: string;
|
|
475
505
|
updated_at: string;
|
|
@@ -516,7 +546,7 @@ export interface NoteDetail extends NoteItem {
|
|
|
516
546
|
version?: number;
|
|
517
547
|
}
|
|
518
548
|
|
|
519
|
-
export interface ListNotesResp {
|
|
549
|
+
export interface ListNotesResp extends DiscoveryResponse {
|
|
520
550
|
notes: NoteItem[];
|
|
521
551
|
has_more: boolean;
|
|
522
552
|
/**
|
|
@@ -529,7 +559,7 @@ export interface ListNotesResp {
|
|
|
529
559
|
total: number;
|
|
530
560
|
}
|
|
531
561
|
|
|
532
|
-
export interface GetNoteResp {
|
|
562
|
+
export interface GetNoteResp extends DiscoveryResponse {
|
|
533
563
|
note: NoteDetail;
|
|
534
564
|
}
|
|
535
565
|
|
|
@@ -644,9 +674,11 @@ export interface KnowledgeTopic {
|
|
|
644
674
|
stats?: KnowledgeTopicStats;
|
|
645
675
|
created_at?: string;
|
|
646
676
|
updated_at?: string;
|
|
677
|
+
topic_id?: string;
|
|
678
|
+
book_info?: BookInfo;
|
|
647
679
|
}
|
|
648
680
|
|
|
649
|
-
export interface ListTopicsResp {
|
|
681
|
+
export interface ListTopicsResp extends DiscoveryResponse {
|
|
650
682
|
topics: KnowledgeTopic[];
|
|
651
683
|
has_more: boolean;
|
|
652
684
|
total: number;
|
|
@@ -660,10 +692,12 @@ export interface CreateTopicResp {
|
|
|
660
692
|
scope?: string;
|
|
661
693
|
}
|
|
662
694
|
|
|
663
|
-
export interface TopicNoteItem {
|
|
695
|
+
export interface TopicNoteItem extends DiscoveryMetadata {
|
|
664
696
|
note_id: string;
|
|
665
697
|
title: string;
|
|
666
|
-
content
|
|
698
|
+
content?: string;
|
|
699
|
+
ref_content?: string;
|
|
700
|
+
note_url?: string;
|
|
667
701
|
note_type: string;
|
|
668
702
|
tags: string[];
|
|
669
703
|
is_ai_generated?: boolean;
|
|
@@ -671,7 +705,7 @@ export interface TopicNoteItem {
|
|
|
671
705
|
edit_time: string;
|
|
672
706
|
}
|
|
673
707
|
|
|
674
|
-
export interface ListTopicNotesResp {
|
|
708
|
+
export interface ListTopicNotesResp extends DiscoveryResponse {
|
|
675
709
|
notes: TopicNoteItem[];
|
|
676
710
|
has_more: boolean;
|
|
677
711
|
total: number;
|
|
@@ -830,7 +864,7 @@ export interface ShareNoteResp {
|
|
|
830
864
|
|
|
831
865
|
// ─── List Subscribe Topics Types ──────────────────────────────────────────────
|
|
832
866
|
|
|
833
|
-
export interface ListSubscribeTopicsResp {
|
|
867
|
+
export interface ListSubscribeTopicsResp extends DiscoveryResponse {
|
|
834
868
|
topics: KnowledgeTopic[];
|
|
835
869
|
has_more: boolean;
|
|
836
870
|
total: number;
|
|
@@ -864,14 +898,26 @@ export interface UpdateNoteResp {
|
|
|
864
898
|
// ─── Recall / Search Types ───────────────────────────────────────────────────
|
|
865
899
|
|
|
866
900
|
export interface RecallResultItem {
|
|
867
|
-
note_id
|
|
901
|
+
note_id?: string;
|
|
902
|
+
resource_id?: string;
|
|
868
903
|
note_type: "NOTE" | "FILE" | "BLOGGER" | "LIVE" | "URL" | "DEDAO";
|
|
869
904
|
title: string;
|
|
870
905
|
content: string;
|
|
871
906
|
created_at: string;
|
|
872
907
|
page_no?: number;
|
|
908
|
+
resource_type?: string;
|
|
909
|
+
note?: NoteItem;
|
|
910
|
+
note_url?: string;
|
|
911
|
+
snippet?: string;
|
|
912
|
+
snippet_source?: string;
|
|
913
|
+
score?: number | null;
|
|
873
914
|
}
|
|
874
915
|
|
|
875
|
-
export interface RecallResp {
|
|
916
|
+
export interface RecallResp extends DiscoveryResponse {
|
|
876
917
|
results: RecallResultItem[];
|
|
918
|
+
result_mode?: string;
|
|
919
|
+
is_exhaustive?: boolean;
|
|
920
|
+
returned_count?: number;
|
|
921
|
+
distinct_note_count?: number;
|
|
922
|
+
partial?: boolean;
|
|
877
923
|
}
|
package/src/discovery.ts
ADDED
|
@@ -0,0 +1,91 @@
|
|
|
1
|
+
import { z } from "zod";
|
|
2
|
+
|
|
3
|
+
const text = z.string().trim().min(1);
|
|
4
|
+
const integer = z.number().int().positive();
|
|
5
|
+
const times = ["created_from", "created_to", "edited_from", "edited_to", "record_updated_from", "record_updated_to"] as const;
|
|
6
|
+
export const noteSelectors = {
|
|
7
|
+
source: text.optional(), note_type: text.optional(),
|
|
8
|
+
reference_resource_type: text.optional(), reference_resource_id: text.optional(),
|
|
9
|
+
reference_article_url: z.string().url().refine(v => /^https?:\/\//.test(v)).optional(),
|
|
10
|
+
topic_id: text.optional(), page_size: integer.max(100).optional(),
|
|
11
|
+
created_from: text.optional(), created_to: text.optional(), edited_from: text.optional(), edited_to: text.optional(),
|
|
12
|
+
record_updated_from: text.optional(), record_updated_to: text.optional(),
|
|
13
|
+
};
|
|
14
|
+
export type NoteDiscoveryOptions = z.infer<ReturnType<typeof noteSchema>>;
|
|
15
|
+
function noteSchema() { return z.object({ ...noteSelectors, page: integer.optional(), cursor: z.string().min(1).optional() }).strict(); }
|
|
16
|
+
const lookupSchema = z.object({ page: integer.optional(), scope: z.enum(["DEFAULT", "CUSTOMER", "BOOKSPACE", "TEAMSPACE"]).optional(), query: text.optional(), author: text.optional(), book_id: text.optional(), page_size: integer.max(100).optional() }).strict();
|
|
17
|
+
export type LookupOptions = z.infer<typeof lookupSchema>;
|
|
18
|
+
export type DiscoveryKind = "notes" | "topicNotes" | "topics" | "detail";
|
|
19
|
+
export type DiscoveryContract = { params: Record<string, unknown>; filters: Record<string, string>; capabilities: string[]; kind: DiscoveryKind };
|
|
20
|
+
|
|
21
|
+
export function normalizeLookup(value: string): string {
|
|
22
|
+
value = value.normalize("NFKC").trim();
|
|
23
|
+
for (const [left, right] of [["《", "》"], ["“", "”"], ['"', '"'], ["'", "'"]]) {
|
|
24
|
+
if (value.startsWith(left) && value.endsWith(right) && value.length >= left.length + right.length) { value = value.slice(left.length, -right.length).trim(); break; }
|
|
25
|
+
}
|
|
26
|
+
return value.toLowerCase();
|
|
27
|
+
}
|
|
28
|
+
|
|
29
|
+
// Keep nanoseconds: Date alone would round distinct reference/time boundaries.
|
|
30
|
+
function timestamp(value: string): { text: string; epoch: bigint } {
|
|
31
|
+
z.string().datetime({ offset: true }).parse(value);
|
|
32
|
+
const m = /^(\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2})(?:\.(\d{1,9}))?(Z|[+-]\d{2}:\d{2})$/.exec(value);
|
|
33
|
+
if (!m) throw new Error("time filters require RFC3339 with timezone");
|
|
34
|
+
const ms = Date.parse(m[1] + m[3]);
|
|
35
|
+
if (!Number.isFinite(ms)) throw new Error("invalid time filter");
|
|
36
|
+
const fraction = (m[2] || "").replace(/0+$/, "");
|
|
37
|
+
return { text: new Date(ms).toISOString().slice(0, 19) + (fraction ? "." + fraction : "") + "Z", epoch: BigInt(ms) * 1000000n + BigInt((m[2] || "").padEnd(9, "0")) };
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
export function discoveryContract(kind: DiscoveryKind, input: Record<string, unknown>): DiscoveryContract | undefined {
|
|
41
|
+
const values = Object.fromEntries(Object.entries(input).filter(([, v]) => v !== undefined));
|
|
42
|
+
const legacy = kind === "topics" ? ["page", "scope"] : kind === "detail" ? ["id", "image_quality"] : kind === "topicNotes" ? ["topic_id", "page"] : ["cursor"];
|
|
43
|
+
if (!Object.keys(values).some(k => !legacy.includes(k))) return undefined;
|
|
44
|
+
let params: Record<string, unknown>;
|
|
45
|
+
const filters: Record<string, string> = {};
|
|
46
|
+
if (kind === "detail") {
|
|
47
|
+
params = z.object({ id: z.union([text, z.number().int().safe()]), image_quality: z.enum(["original"]).optional() }).strict().parse(values);
|
|
48
|
+
return { params, filters, capabilities: ["note.reference.v1"], kind };
|
|
49
|
+
}
|
|
50
|
+
if (kind === "topics") {
|
|
51
|
+
params = { scope: "DEFAULT", page: 1, page_size: 20, ...lookupSchema.parse(values) };
|
|
52
|
+
if (params.scope !== "BOOKSPACE" && (params.author || params.book_id)) throw new Error("author and book_id require BOOKSPACE");
|
|
53
|
+
for (const key of ["query", "author"]) if (typeof params[key] === "string") params[key] = normalizeLookup(params[key] as string);
|
|
54
|
+
} else {
|
|
55
|
+
params = { page_size: 20, ...(kind === "topicNotes" ? { page: 1 } : {}), ...noteSchema().parse(values) };
|
|
56
|
+
if (kind === "topicNotes" && !params.topic_id) throw new Error("topic_id is required");
|
|
57
|
+
if (params.page && (!params.topic_id || params.cursor)) throw new Error("page requires topic_id and cannot be combined with cursor");
|
|
58
|
+
if (params.reference_resource_id) {
|
|
59
|
+
if (!params.source || !params.reference_resource_type) throw new Error("reference ID requires source and resource type");
|
|
60
|
+
const id = String(params.reference_resource_id);
|
|
61
|
+
if (!/^\d+$/.test(id) || BigInt(id) <= 0n || BigInt(id) > 9223372036854775807n) throw new Error("invalid reference ID");
|
|
62
|
+
}
|
|
63
|
+
const epochs: Record<string, bigint> = {};
|
|
64
|
+
for (const key of times) if (typeof params[key] === "string") { const t = timestamp(params[key] as string); params[key] = t.text; epochs[key] = t.epoch; }
|
|
65
|
+
for (const prefix of ["created", "edited", "record_updated"]) if (epochs[prefix + "_from"] !== undefined && epochs[prefix + "_to"] !== undefined && epochs[prefix + "_from"] >= epochs[prefix + "_to"]) throw new Error("time interval must have from < to");
|
|
66
|
+
}
|
|
67
|
+
for (const [key, value] of Object.entries(params)) if (!["cursor", "page", "page_size"].includes(key)) filters[key] = String(value);
|
|
68
|
+
const capabilities = ["pagination.v1"];
|
|
69
|
+
if (kind === "topics") capabilities.push("knowledge.lookup.v1");
|
|
70
|
+
else if (Object.keys(filters).length) capabilities.push("note.filters.v1");
|
|
71
|
+
if (kind !== "topics") capabilities.push("note.reference.v1");
|
|
72
|
+
return { params, filters, capabilities, kind };
|
|
73
|
+
}
|
|
74
|
+
|
|
75
|
+
export function verifyDiscovery(body: unknown, contract: DiscoveryContract): void {
|
|
76
|
+
const envelope = z.object({ meta: z.object({ capabilities: z.array(z.string()) }), data: z.record(z.unknown()) }).safeParse(body);
|
|
77
|
+
if (!envelope.success) throw new Error("server does not declare discovery capabilities; upgrade the server (unfiltered results not accepted)");
|
|
78
|
+
for (const cap of contract.capabilities) if (!envelope.data.meta.capabilities.includes(cap)) throw new Error(`server does not support ${cap}; unfiltered results not accepted`);
|
|
79
|
+
if (contract.kind === "detail") return;
|
|
80
|
+
const data = envelope.data.data;
|
|
81
|
+
// Responses also contain typed flags such as exclude_mine; only requested
|
|
82
|
+
// string selectors must match the contract, without coercion.
|
|
83
|
+
const applied = z.record(z.unknown()).safeParse(data.applied_filters);
|
|
84
|
+
if (!applied.success) throw new Error("server did not return applied_filters");
|
|
85
|
+
for (const [key, value] of Object.entries(contract.filters)) if (applied.data[key] !== value) throw new Error(`server did not apply ${key}`);
|
|
86
|
+
const p = z.object({ mode: z.enum(["page", "cursor"]), page: integer.nullable(), page_size: integer.max(100), returned_count: z.number().int().nonnegative(), total_count: z.number().int().nonnegative().nullable(), has_more: z.boolean(), next_page: integer.nullable(), next_cursor: z.string().min(1).nullable() }).parse(data.pagination);
|
|
87
|
+
const items = data[contract.kind === "topics" ? "topics" : "notes"];
|
|
88
|
+
const page = contract.params.page;
|
|
89
|
+
if (!Array.isArray(items) || p.mode !== (page ? "page" : "cursor") || p.page_size !== contract.params.page_size || p.returned_count !== items.length || items.length > p.page_size || (p.total_count !== null && p.total_count < items.length) || (page && p.page !== page)) throw new Error("invalid discovery pagination response");
|
|
90
|
+
if (p.has_more ? (page ? p.next_page !== Number(page) + 1 || p.next_cursor !== null : !p.next_cursor || p.next_page !== null) : p.next_page !== null || p.next_cursor !== null) throw new Error("invalid discovery continuation");
|
|
91
|
+
}
|
package/src/index.ts
CHANGED
|
@@ -121,15 +121,34 @@ function snowflakeID(value: unknown, field: string): string | number {
|
|
|
121
121
|
|
|
122
122
|
// ─── Tool Definitions ────────────────────────────────────────────────────────
|
|
123
123
|
|
|
124
|
+
const noteDiscoveryProperties = {
|
|
125
|
+
page: { type: "integer", minimum: 1, description: "知识库内可用页码;与 cursor 互斥" },
|
|
126
|
+
source: { type: "string", description: "来源平台精确筛选,如 dedao" },
|
|
127
|
+
note_type: { type: "string", description: "笔记真实类型精确筛选,如 ref" },
|
|
128
|
+
reference_resource_type: { type: "string", description: "引用资源类型,如 ebook、course_article、audio_book" },
|
|
129
|
+
reference_resource_id: { type: "string", description: "引用资源 ID,必须字符串;同时传 source 和 reference_resource_type" },
|
|
130
|
+
reference_article_url: { type: "string", description: "文章 URL 精确筛选,保留 query 和 fragment" },
|
|
131
|
+
topic_id: { type: "string", description: "知识库 ID,限定授权范围" },
|
|
132
|
+
page_size: { type: "integer", minimum: 1, maximum: 100, description: "每页 1–100 条,默认 20" },
|
|
133
|
+
...Object.fromEntries(["created_from", "created_to", "edited_from", "edited_to", "record_updated_from", "record_updated_to"].map(key => [key, { type: "string", description: "RFC3339 带时区,from 包含、to 不包含;三种时间轴独立" }])),
|
|
134
|
+
};
|
|
135
|
+
const knowledgeLookupProperties = {
|
|
136
|
+
query: { type: "string", description: "只匹配知识库名/书名,不匹配作者;与 author 同时传时为 AND。多候选须核对书名、作者和 book_id" },
|
|
137
|
+
author: { type: "string", description: "书籍作者,限 BOOKSPACE;只有作者线索时只传 author,不猜书名或把作者填进 query" },
|
|
138
|
+
book_id: { type: "string", description: "书籍 ID 字符串,限 BOOKSPACE" },
|
|
139
|
+
page_size: noteDiscoveryProperties.page_size,
|
|
140
|
+
};
|
|
141
|
+
|
|
124
142
|
const TOOLS: Tool[] = [
|
|
125
143
|
// ── Notes ──
|
|
126
144
|
{
|
|
127
145
|
name: "list_notes",
|
|
128
146
|
description:
|
|
129
|
-
"
|
|
147
|
+
"按来源、引用资源或知识库查找笔记。列表只返回定位信息;需要正文和完整元数据时调用 get_note。新查询须核对 meta.capabilities、applied_filters,按 pagination.next_cursor 翻页到 has_more=false 才能说全量完成。total_count=null 表示未知,不能用本页条数代替全库总数。",
|
|
130
148
|
inputSchema: {
|
|
131
149
|
type: "object" as const,
|
|
132
150
|
properties: {
|
|
151
|
+
...noteDiscoveryProperties,
|
|
133
152
|
cursor: {
|
|
134
153
|
type: "string",
|
|
135
154
|
description: "翻页游标。首次不传;后续将上一次响应的 cursor 字段原样传入即可,无需任何转换。",
|
|
@@ -140,7 +159,7 @@ const TOOLS: Tool[] = [
|
|
|
140
159
|
},
|
|
141
160
|
{
|
|
142
161
|
name: "get_note",
|
|
143
|
-
description: "获取指定笔记的详细内容,包括正文、标签、附件、音频转录、网页链接等。\n\n**字段语义说明(AI Agent 重要参考)**:\n`content` 通常是 AI 总结,不一定是原文。不同类型笔记的原文字段如下:\n- 普通文字笔记(plain_text):原文 = `note.content`\n- 链接/网页笔记(link):原文 = `note.web_page.content`,AI 总结 = `note.content`\n- 录音笔记(audio/local_audio
|
|
162
|
+
description: "获取指定笔记的详细内容,包括正文、标签、附件、音频转录、网页链接等。\n\n**字段语义说明(AI Agent 重要参考)**:\n`content` 通常是 AI 总结,不一定是原文。不同类型笔记的原文字段如下:\n- 引用笔记(ref):原文 = `note.ref_content`,`note.content` 是个人评论\n- 普通文字笔记(plain_text):原文 = `note.content`\n- 链接/网页笔记(link):原文 = `note.web_page.content`,AI 总结 = `note.content`\n- 录音笔记(audio/local_audio):转写原文 = `note.audio.original`,AI 总结 = `note.content`\n\n用户要求'读原文'时,先看 `note.note_type`,再按上述对应关系取字段。",
|
|
144
163
|
inputSchema: {
|
|
145
164
|
type: "object" as const,
|
|
146
165
|
properties: {
|
|
@@ -159,7 +178,7 @@ const TOOLS: Tool[] = [
|
|
|
159
178
|
},
|
|
160
179
|
{
|
|
161
180
|
name: "get_note_original",
|
|
162
|
-
description: "
|
|
181
|
+
description: "直接读取笔记原文。引用笔记返回 ref_content,链接笔记返回网页原文,录音笔记返回转写原文,文字笔记返回正文;无原文或不支持的类型会报错。",
|
|
163
182
|
inputSchema: { type: "object" as const, properties: { id: { type: ["string", "number"], description: "笔记 ID,推荐十进制字符串" } }, required: ["id"] },
|
|
164
183
|
},
|
|
165
184
|
{
|
|
@@ -347,6 +366,7 @@ const TOOLS: Tool[] = [
|
|
|
347
366
|
inputSchema: {
|
|
348
367
|
type: "object" as const,
|
|
349
368
|
properties: {
|
|
369
|
+
...knowledgeLookupProperties,
|
|
350
370
|
page: {
|
|
351
371
|
type: "number",
|
|
352
372
|
description: "页码,从 1 开始(默认 1)",
|
|
@@ -386,10 +406,11 @@ const TOOLS: Tool[] = [
|
|
|
386
406
|
},
|
|
387
407
|
{
|
|
388
408
|
name: "list_topic_notes",
|
|
389
|
-
description: "
|
|
409
|
+
description: "列出知识库内可访问的笔记,支持来源、引用资源、时间筛选。列表只返回定位信息;需要正文和完整元数据时调用 get_note。按 pagination.next_page 翻页;去重 ID,重复游标/页码、无进展或中途失败不能声称全量完成。",
|
|
390
410
|
inputSchema: {
|
|
391
411
|
type: "object" as const,
|
|
392
412
|
properties: {
|
|
413
|
+
...noteDiscoveryProperties,
|
|
393
414
|
topic_id: {
|
|
394
415
|
type: "string",
|
|
395
416
|
description: "知识库 ID",
|
|
@@ -724,6 +745,7 @@ const TOOLS: Tool[] = [
|
|
|
724
745
|
inputSchema: {
|
|
725
746
|
type: "object" as const,
|
|
726
747
|
properties: {
|
|
748
|
+
...knowledgeLookupProperties,
|
|
727
749
|
page: {
|
|
728
750
|
type: "number",
|
|
729
751
|
description: "页码,从 1 开始,默认 1",
|
|
@@ -811,7 +833,7 @@ async function handleTool(
|
|
|
811
833
|
// ── Notes ──
|
|
812
834
|
case "list_notes": {
|
|
813
835
|
const cursor = (input.cursor as string | undefined);
|
|
814
|
-
return client.listNotes({ cursor: cursor === "0" ? undefined : cursor });
|
|
836
|
+
return client.listNotes({ ...input, cursor: cursor === "0" ? undefined : cursor });
|
|
815
837
|
}
|
|
816
838
|
case "get_note": {
|
|
817
839
|
return client.getNote(snowflakeID(input.id, "id"), input.image_quality as string | undefined);
|
|
@@ -819,9 +841,18 @@ async function handleTool(
|
|
|
819
841
|
case "get_note_original": {
|
|
820
842
|
const result = await client.getNote(snowflakeID(input.id, "id"));
|
|
821
843
|
const note = result.note;
|
|
822
|
-
|
|
844
|
+
let original: string | undefined;
|
|
845
|
+
let original_source: string;
|
|
846
|
+
switch (note.note_type) {
|
|
847
|
+
case "ref": original = note.ref_content; original_source = "ref_content"; break;
|
|
848
|
+
case "plain_text": original = note.content; original_source = "content"; break;
|
|
849
|
+
case "link": original = note.web_page?.content; original_source = "web_page.content"; break;
|
|
850
|
+
case "audio":
|
|
851
|
+
case "local_audio": original = note.audio?.original; original_source = "audio.original"; break;
|
|
852
|
+
default: throw new Error(`Unsupported note type for original content: ${note.note_type}`);
|
|
853
|
+
}
|
|
823
854
|
if (!original) throw new Error("Original content is not available for this note");
|
|
824
|
-
return { id: note.id, note_type: note.note_type, title: note.title, original };
|
|
855
|
+
return { id: note.id, note_type: note.note_type, title: note.title, original, original_source };
|
|
825
856
|
}
|
|
826
857
|
case "get_note_transcript": {
|
|
827
858
|
const result = await client.getNote(snowflakeID(input.id, "id"));
|
|
@@ -906,6 +937,7 @@ async function handleTool(
|
|
|
906
937
|
// ── Knowledge ──
|
|
907
938
|
case "list_topics": {
|
|
908
939
|
return client.listTopics({
|
|
940
|
+
...input,
|
|
909
941
|
page: input.page as number | undefined,
|
|
910
942
|
scope: input.scope as "DEFAULT" | "CUSTOMER" | "BOOKSPACE" | "TEAMSPACE" | undefined,
|
|
911
943
|
});
|
|
@@ -919,6 +951,7 @@ async function handleTool(
|
|
|
919
951
|
}
|
|
920
952
|
case "list_topic_notes": {
|
|
921
953
|
return client.listTopicNotes({
|
|
954
|
+
...input,
|
|
922
955
|
topic_id: input.topic_id as string,
|
|
923
956
|
page: input.page as number | undefined,
|
|
924
957
|
});
|
|
@@ -1046,6 +1079,7 @@ async function handleTool(
|
|
|
1046
1079
|
// ── Knowledge / Subscribe ──
|
|
1047
1080
|
case "list_subscribe_topics": {
|
|
1048
1081
|
return client.listSubscribeTopics({
|
|
1082
|
+
...input,
|
|
1049
1083
|
page: input.page as number | undefined,
|
|
1050
1084
|
scope: input.scope as "DEFAULT" | "CUSTOMER" | "BOOKSPACE" | "TEAMSPACE" | undefined,
|
|
1051
1085
|
});
|
package/test/client.test.mjs
CHANGED
|
@@ -177,3 +177,16 @@ test("OSS multipart fields use the signed names and order", async () => {
|
|
|
177
177
|
server.close();
|
|
178
178
|
}
|
|
179
179
|
});
|
|
180
|
+
|
|
181
|
+
|
|
182
|
+
test("large-integer preservation never rewrites JSON-looking note text", () => {
|
|
183
|
+
const text = 'example: [1923625755277351496, -1923625755277351496] and "note_id":1923625755277351496, escaped \\"quote\\"';
|
|
184
|
+
const input = JSON.stringify({content:text,preview:text,nested:{quote:text}}).slice(0,-1)+',"ids":[1923625755277351496,-1923625755277351496],"decimal":1923625755277351.5,"exponent":1923625755277351496e-5}';
|
|
185
|
+
const parsed = parseJsonPreservingLargeIntegerStrings(input);
|
|
186
|
+
assert.equal(parsed.content,text);
|
|
187
|
+
assert.equal(parsed.preview,text);
|
|
188
|
+
assert.equal(parsed.nested.quote,text);
|
|
189
|
+
assert.deepEqual(parsed.ids,["1923625755277351496","-1923625755277351496"]);
|
|
190
|
+
assert.equal(parsed.decimal,1923625755277351.5);
|
|
191
|
+
assert.equal(parsed.exponent,1923625755277351496e-5);
|
|
192
|
+
});
|