An open-source, privacy-first, self-hosted knowledge workspace where humans and AI agents work together 开源、隐私优先、自托管的知识工作空间,让人与智能体在此协作
TypeScript agentic-aiai-agentknowledge-baselocal-firstmarkdownmcpmindmapnote-takingself-hostedsiyuanworkspace
export type AgentHistoryEntry = {
id?: string;
type: string;
status?: string;
content?: string;
result?: string;
callID?: string;
reasoningContent?: string;
roundID?: string;
duration?: number;
steps?: AgentHistoryThinkingStep[];
toolCalls?: Array<{
id?: string;
name?: string;
result?: string;
state?: string;
[key: string]: unknown
}>;
[key: string]: unknown;
};
export type AgentHistoryThinkingStep = {
reasoning?: string;
reasoningContent?: string;
roundID?: string;
toolNames?: string[];
toolCallIDs?: string[];
content?: string;
};
export const getAgentThinkingToolGroups = (steps: AgentHistoryThinkingStep[]): string[][] => {
return steps.map(step => (step.toolNames || []).filter(Boolean));
};
export const hasAgentThinkingStepDetails = (step: AgentHistoryThinkingStep): boolean => {
return !!step.content?.trim() || !!step.reasoningContent?.trim() ||
!!step.toolNames?.some(toolName => !!toolName.trim());
};
export const getAgentThinkingDisplaySeconds = (duration?: number): number | undefined => {
if (duration === undefined || !Number.isFinite(duration) || duration <= 0) {
return undefined;
}
return Math.max(1, Math.round(duration));
};
export type AgentHistoryReference = { id: string; title: string };
export type AgentHistoryUserEntry = {
content: string;
timestamp?: number;
blockHTML?: string;
references?: AgentHistoryReference[];
};
export type AgentHistoryEditData = {
text: string;
blockHTML: string;
references: AgentHistoryReference[];
};
export const applyAgentUserEdit = (entry: AgentHistoryUserEntry, data: AgentHistoryEditData) => {
entry.content = data.text;
entry.timestamp = Date.now();
entry.blockHTML = data.blockHTML;
entry.references = data.references.length > 0 ? data.references.slice() : undefined;
};
export const findAgentUserEntryIndex = (entries: AgentHistoryEntry[], userEntryID?: string): number => {
for (let i = entries.length - 1; i >= 0; i--) {
if (entries[i].type === "user" && (!userEntryID || entries[i].id === userEntryID)) {
return i;
}
}
return -1;
};
export const isAgentAssistantContentFinalInTurn = (
entries: Array<{ type: string; content?: string }>, entryIndex: number
): boolean => {
const entry = entries[entryIndex];
if (entry?.type !== "assistant" || !entry.content?.trim()) {
return false;
}
for (let i = entryIndex + 1; i < entries.length; i++) {
if (entries[i].type === "user") {
break;
}
if (entries[i].type === "assistant" && entries[i].content?.trim()) {
return false;
}
}
return true;
};
export const getAgentTurnContent = (entries: AgentHistoryEntry[], userEntryID: string): string => {
const userIndex = entries.findIndex(entry => entry.type === "user" && entry.id === userEntryID);
if (userIndex < 0) {
return "";
}
const contents: string[] = [];
for (let i = userIndex + 1; i < entries.length && entries[i].type !== "user"; i++) {
const entry = entries[i];
if (entry.type === "assistant" && entry.content?.trim()) {
contents.push(entry.content);
}
}
return contents.join("\n\n");
};
export const hasAgentExecutedToolsAfter = (entries: AgentHistoryEntry[], entryIndex: number): boolean => {
return entries.slice(entryIndex + 1).some((entry) => {
if (entry.type === "snapshot") {
return true;
}
if (entry.type === "confirm") {
return entry.status === "approved" || entry.status === "always";
}
return entry.type === "assistant" && !!entry.toolCalls?.some((call) =>
call.state === "executing" || call.state === "completed" || call.result !== undefined);
});
};
export const hasAgentModelSpecificContext = (entries: AgentHistoryEntry[]): boolean => {
return entries.some((entry) => {
if (entry.type === "assistant") {
return !!entry.reasoningContent?.trim() || !!entry.toolCalls?.length;
}
return entry.type === "thinking" && !!entry.steps?.some(step => step.reasoningContent?.trim());
});
};
const sameToolNames = (left: string[] | undefined, right: string[]): boolean => {
if (!left || left.length !== right.length) {
return false;
}
return left.every((name, index) => name === right[index]);
};
const enrichThinkingStep = (step: AgentHistoryThinkingStep, entry: AgentHistoryEntry) => {
// assistant.content 是面向用户的权威正文;匹配成功后从兼容用的旧思考步骤中移除副本。
if (entry.content?.trim()) {
delete step.content;
}
if (entry.reasoningContent?.trim()) {
step.reasoningContent = entry.reasoningContent;
}
if (entry.roundID) {
step.roundID = entry.roundID;
}
};
const enrichThinkingStepTools = (step: AgentHistoryThinkingStep, relatedSteps: AgentHistoryThinkingStep[],
entry: AgentHistoryEntry) => {
const calls = entry.toolCalls || [];
const toolNames = calls.map(call => call.name || "").filter(Boolean);
if (toolNames.length === 0) {
return;
}
const hasCallIDs = relatedSteps.some(item => item.toolCallIDs && item.toolCallIDs.length > 0);
if (hasCallIDs) {
const assignedCallIndexes = new Set<number>();
for (const relatedStep of relatedSteps) {
if (!relatedStep.toolCallIDs || relatedStep.toolCallIDs.length === 0) {
continue;
}
const resolvedNames: string[] = [];
for (const callID of relatedStep.toolCallIDs) {
const callIndex = calls.findIndex((call, index) =>
!assignedCallIndexes.has(index) && call.id === callID);
if (callIndex >= 0 && calls[callIndex].name) {
assignedCallIndexes.add(callIndex);
resolvedNames.push(calls[callIndex].name!);
}
}
if (resolvedNames.length > 0) {
relatedStep.toolNames = resolvedNames;
}
}
// 兼容一部分步骤尚未写入调用 ID 的过渡数据,先用已有名称认领对应调用。
for (const relatedStep of relatedSteps) {
if (relatedStep.toolCallIDs?.length || !relatedStep.toolNames?.length) {
continue;
}
for (const name of relatedStep.toolNames) {
const callIndex = calls.findIndex((call, index) =>
!assignedCallIndexes.has(index) && call.name === name);
if (callIndex >= 0) {
assignedCallIndexes.add(callIndex);
}
}
}
const remainingCalls = calls.filter((call, index) => !assignedCallIndexes.has(index) && !!call.name);
if (remainingCalls.length > 0) {
step.toolNames = (step.toolNames || []).concat(remainingCalls.map(call => call.name!));
const remainingIDs = remainingCalls.map(call => call.id || "").filter(Boolean);
if (remainingIDs.length > 0) {
step.toolCallIDs = (step.toolCallIDs || []).concat(remainingIDs);
}
}
return;
}
// 一个模型轮次可能被确认卡片拆成多个思考步骤。老数据没有调用 ID 时保留已有子集,
// 避免把整轮工具列表覆盖到第一个步骤后造成重复。
if (relatedSteps.length > 1 && relatedSteps.some(item => item.toolNames && item.toolNames.length > 0)) {
return;
}
step.toolNames = toolNames;
const toolCallIDs = calls.map(call => call.id || "").filter(Boolean);
if (toolCallIDs.length > 0) {
step.toolCallIDs = toolCallIDs;
}
};
const buildRecoveredThinkingStep = (entry: AgentHistoryEntry): AgentHistoryThinkingStep => {
const step: AgentHistoryThinkingStep = {
reasoning: "processing",
reasoningContent: entry.reasoningContent || "",
roundID: entry.roundID,
toolNames: entry.toolCalls?.map(call => call.name || "").filter(Boolean),
};
const toolCallIDs = entry.toolCalls?.map(call => call.id || "").filter(Boolean) || [];
if (toolCallIDs.length > 0) {
step.toolCallIDs = toolCallIDs;
}
return step;
};
const prepareAgentTurnPresentation = (entries: AgentHistoryEntry[]): AgentHistoryEntry[] => {
const prepared: AgentHistoryEntry[] = entries.map(entry => ({
...entry,
steps: entry.steps?.map(step => ({
...step,
toolNames: step.toolNames?.slice(),
...(step.toolCallIDs ? {toolCallIDs: step.toolCallIDs.slice()} : {}),
})),
toolCalls: entry.toolCalls?.map(call => ({...call})),
}));
const thinkingSteps = prepared.flatMap(entry => entry.type === "thinking" ? (entry.steps || []) : []);
const matchedSteps = new Set<AgentHistoryThinkingStep>();
const recovered: Array<{ entry: AgentHistoryEntry; step: AgentHistoryThinkingStep }> = [];
const questionEntries = prepared.filter(entry => entry.type === "question");
const matchedQuestionEntries = new Set<AgentHistoryEntry>();
const processContentInsertions: Array<{
sourceEntry: AgentHistoryEntry;
anchorStep?: AgentHistoryThinkingStep;
questionEntry?: AgentHistoryEntry
}> = [];
const todoInsertions: Array<{
sourceEntry: AgentHistoryEntry;
anchorStep?: AgentHistoryThinkingStep;
todoEntry: AgentHistoryEntry
}> = [];
for (const entry of prepared) {
if (entry.type !== "assistant") {
continue;
}
const isProcess = !!entry.toolCalls?.length;
const toolNames = entry.toolCalls?.map(call => call.name || "").filter(Boolean) || [];
const questionCallCount = entry.toolCalls?.filter(call => call.name === "question").length || 0;
const hasProcessContent = isProcess && !!entry.content?.trim();
let questionEntry: AgentHistoryEntry | undefined;
for (let i = 0; i < questionCallCount; i++) {
let matchedQuestion: AgentHistoryEntry | undefined;
if (entry.roundID) {
matchedQuestion = questionEntries.find(item =>
!matchedQuestionEntries.has(item) && item.roundID === entry.roundID);
}
if (!matchedQuestion) {
matchedQuestion = questionEntries.find(item =>
!matchedQuestionEntries.has(item) && (!entry.roundID || !item.roundID));
}
if (!matchedQuestion) {
break;
}
matchedQuestionEntries.add(matchedQuestion);
questionEntry = questionEntry || matchedQuestion;
}
let step: AgentHistoryThinkingStep | undefined;
let relatedSteps: AgentHistoryThinkingStep[] = [];
if (entry.roundID) {
relatedSteps = thinkingSteps.filter(item => item.roundID === entry.roundID);
step = relatedSteps.find(item => !matchedSteps.has(item));
}
if (!step && (isProcess || entry.reasoningContent?.trim())) {
step = thinkingSteps.find(item => !item.roundID && !matchedSteps.has(item) && (
(isProcess && !!entry.content?.trim() && item.content === entry.content) ||
sameToolNames(item.toolNames, toolNames) ||
(!!entry.reasoningContent?.trim() && item.reasoningContent === entry.reasoningContent)
));
}
let presentationStep = step;
if (step) {
enrichThinkingStep(step, entry);
enrichThinkingStepTools(step, relatedSteps.length > 0 ? relatedSteps : [step], entry);
matchedSteps.add(step);
} else if (isProcess || entry.reasoningContent?.trim()) {
presentationStep = buildRecoveredThinkingStep(entry);
recovered.push({entry, step: presentationStep});
}
if (hasProcessContent) {
if (presentationStep) {
delete presentationStep.content;
}
processContentInsertions.push({
sourceEntry: entry,
anchorStep: presentationStep,
questionEntry,
});
}
if (isProcess) {
const remainingToolCalls: NonNullable<AgentHistoryEntry["toolCalls"]> = [];
for (const call of entry.toolCalls || []) {
if (call.name === "todo_write" && call.result?.trim()) {
const callStep = call.id
? thinkingSteps.find(item => item.toolCallIDs?.includes(call.id!))
: undefined;
todoInsertions.push({
sourceEntry: entry,
anchorStep: callStep || presentationStep,
todoEntry: {
type: "todo",
result: call.result,
callID: call.id,
roundID: entry.roundID,
},
});
} else {
remainingToolCalls.push(call);
}
}
entry.toolCalls = remainingToolCalls;
}
}
if (recovered.length > 0) {
const roundOrder = new Map<string, number>();
let order = 0;
for (const entry of prepared) {
if (entry.type === "assistant" && entry.roundID && !roundOrder.has(entry.roundID)) {
roundOrder.set(entry.roundID, order++);
}
}
const synthetic: Array<{ entry: AgentHistoryEntry; step: AgentHistoryThinkingStep }> = [];
for (const item of recovered) {
const itemOrder = item.entry.roundID ? roundOrder.get(item.entry.roundID) : undefined;
let nextEntry: AgentHistoryEntry | undefined;
let nextStep: AgentHistoryThinkingStep | undefined;
let nextOrder = Number.MAX_SAFE_INTEGER;
if (itemOrder !== undefined) {
for (const entry of prepared) {
if (entry.type !== "thinking") {
continue;
}
for (const step of entry.steps || []) {
const stepOrder = step.roundID ? roundOrder.get(step.roundID) : undefined;
if (stepOrder !== undefined && stepOrder > itemOrder && stepOrder < nextOrder) {
nextEntry = entry;
nextStep = step;
nextOrder = stepOrder;
}
}
}
}
if (nextEntry && nextStep) {
const nextIndex = nextEntry.steps?.indexOf(nextStep) ?? -1;
nextEntry.steps?.splice(Math.max(nextIndex, 0), 0, item.step);
} else {
synthetic.push(item);
}
}
if (synthetic.length > 0) {
let pending: Array<{ entry: AgentHistoryEntry; step: AgentHistoryThinkingStep }> = [];
const flushPending = () => {
if (pending.length === 0) {
return;
}
const firstUnmatched = prepared.indexOf(pending[0].entry);
prepared.splice(firstUnmatched, 0, {
type: "thinking",
steps: pending.map(item => item.step),
});
pending = [];
};
for (const item of synthetic) {
pending.push(item);
// 实时界面会在模型输出正文后结束当前思考卡片,恢复时沿用同一边界保持思考与正文配套。
if (item.entry.content?.trim()) {
flushPending();
}
}
flushPending();
}
}
const contentOffsets = new Map<AgentHistoryEntry, number>();
for (const item of processContentInsertions) {
const anchorEntry = item.anchorStep
? prepared.find(entry => entry.type === "thinking" && entry.steps?.includes(item.anchorStep!))
: undefined;
if (anchorEntry && item.questionEntry) {
const anchorIndex = prepared.indexOf(anchorEntry);
const questionIndex = prepared.indexOf(item.questionEntry);
if (anchorIndex > questionIndex) {
prepared.splice(anchorIndex, 1);
prepared.splice(prepared.indexOf(item.questionEntry), 0, anchorEntry);
}
}
const sourceIndex = prepared.indexOf(item.sourceEntry);
if (sourceIndex < 0) {
continue;
}
const questionIndex = item.questionEntry ? prepared.indexOf(item.questionEntry) : -1;
if (questionIndex < 0 && anchorEntry) {
const anchorIndex = prepared.indexOf(anchorEntry);
const nextThinkingIndex = prepared.findIndex((entry, index) =>
index > anchorIndex && entry.type === "thinking");
if (sourceIndex > anchorIndex && (nextThinkingIndex < 0 || sourceIndex < nextThinkingIndex)) {
contentOffsets.set(anchorEntry, (contentOffsets.get(anchorEntry) || 0) + 1);
continue;
}
}
prepared.splice(sourceIndex, 1);
if (questionIndex >= 0) {
prepared.splice(prepared.indexOf(item.questionEntry!), 0, item.sourceEntry);
} else if (anchorEntry) {
const offset = contentOffsets.get(anchorEntry) || 0;
prepared.splice(prepared.indexOf(anchorEntry) + 1 + offset, 0, item.sourceEntry);
contentOffsets.set(anchorEntry, offset + 1);
} else {
prepared.splice(Math.min(sourceIndex, prepared.length), 0, item.sourceEntry);
}
}
const todoOffsets = new Map<AgentHistoryEntry, number>();
for (const item of todoInsertions) {
const anchorEntry = item.anchorStep
? prepared.find(entry => entry.type === "thinking" && entry.steps?.includes(item.anchorStep!))
: undefined;
if (anchorEntry) {
const offset = todoOffsets.get(anchorEntry) || 0;
prepared.splice(prepared.indexOf(anchorEntry) + 1 + offset, 0, item.todoEntry);
todoOffsets.set(anchorEntry, offset + 1);
} else {
const sourceIndex = prepared.indexOf(item.sourceEntry);
prepared.splice(sourceIndex >= 0 ? sourceIndex : prepared.length, 0, item.todoEntry);
}
}
// snapshot 事件先于当前思考卡片落盘。按 roundID 将其移到对应思考卡片之后;
// 老数据没有 roundID 时,优先使用原位置之后的第一张思考卡片。
for (const snapshot of prepared.filter(entry => entry.type === "snapshot")) {
const snapshotIndex = prepared.indexOf(snapshot);
const thinkingEntries = prepared.filter(entry => entry.type === "thinking" && entry.steps?.length);
let anchorEntry: AgentHistoryEntry | undefined;
if (snapshot.roundID) {
for (let i = thinkingEntries.length - 1; i >= 0; i--) {
if (thinkingEntries[i].steps?.some(step => step.roundID === snapshot.roundID)) {
anchorEntry = thinkingEntries[i];
break;
}
}
}
if (!anchorEntry) {
anchorEntry = thinkingEntries.find(entry => prepared.indexOf(entry) > snapshotIndex) || thinkingEntries[0];
}
if (!anchorEntry) {
continue;
}
prepared.splice(snapshotIndex, 1);
prepared.splice(prepared.indexOf(anchorEntry) + 1, 0, snapshot);
}
for (const entry of prepared) {
if (entry.type === "thinking") {
entry.steps = entry.steps?.filter(hasAgentThinkingStepDetails);
}
}
return prepared.filter(entry => entry.type !== "thinking" || !!entry.steps?.length);
};
// 将持久化协议消息投影为 UI 条目:reasoningContent 与工具调用归入思考卡片,
// assistant.content 始终作为正文展示,question 的同轮正文放在提问卡片前。
export const buildAgentPresentationEntries = (entries: AgentHistoryEntry[]): AgentHistoryEntry[] => {
const result: AgentHistoryEntry[] = [];
let turnEntries: AgentHistoryEntry[] = [];
const flushTurn = () => {
if (turnEntries.length > 0) {
result.push(...prepareAgentTurnPresentation(turnEntries));
turnEntries = [];
}
};
for (const entry of entries) {
if (entry.type === "user") {
flushTurn();
result.push({...entry});
} else {
turnEntries.push(entry);
}
}
flushTurn();
return result;
};
export const isAgentRegenerateStateCurrent = (requestSessionID: string, currentSessionID: string,
requestRevision: number, currentRevision: number,
isStreaming: boolean, mirrorLocked: boolean): boolean => {
return requestSessionID === currentSessionID && requestRevision === currentRevision &&
!isStreaming && !mirrorLocked;
};