agent-configs 1.0.0

package/skills/bk-chat-helper/references/api-reference.md

@@ -0,0 +1,606 @@
+# API 详细参考
+
+## useChatHelper 配置
+
+### 完整配置类型
+
+```typescript
+interface IUseChatHelperOptions {
+  // 必需：请求配置
+  requestData: {
+    urlPrefix: string;  // API 基础路径
+    headers?: (() => Record<string, string>) | Record<string, string>;
+    data?: (() => Record<string, unknown>) | Record<string, unknown>;
+  };
+  
+  // 可选：请求/响应拦截器
+  interceptors?: {
+    request?: (config: IRequestConfig) => IRequestConfig;
+    response?: (response: IResponse) => IResponse;
+  };
+  
+  // 可选：自定义协议
+  protocol?: ISSEProtocol;
+}
+```
+
+### 返回值类型
+
+```typescript
+interface IChatHelper {
+  agent: IAgentModule;
+  session: ISessionModule;
+  message: IMessageModule;
+  http: IHttpModule;
+  reset: (options: IUseChatHelperOptions) => void;
+}
+```
+
+---
+
+## Agent 模块
+
+### 响应式数据
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| `info` | `Ref<IAgentInfo \| null>` | Agent 信息 |
+| `isInfoLoading` | `Ref<boolean>` | 获取信息加载状态 |
+| `isChatting` | `Ref<boolean>` | 是否正在聊天 |
+
+### 方法
+
+#### getAgentInfo()
+
+获取 Agent 信息（名称、开场白、预设问题等）。
+
+```typescript
+await agent.getAgentInfo();
+
+// 使用
+console.log(agent.info.value?.agentName);
+console.log(agent.info.value?.conversationSettings?.openingRemark);
+console.log(agent.info.value?.conversationSettings?.predefinedQuestions);
+```
+
+#### chat(userInput, sessionCode, url?, config?, property?)
+
+发送消息并开始流式对话。
+
+```typescript
+// 基础用法
+await agent.chat('你好', 'session_123');
+
+// 自定义 URL
+await agent.chat('你好', 'session_123', 'custom_chat/');
+
+// 自定义请求配置
+await agent.chat('你好', 'session_123', undefined, {
+  data: { temperature: 0.7, max_tokens: 2000 },
+  headers: { 'X-Custom-Header': 'value' },
+});
+
+// 带消息属性（引用、快捷键等）
+await agent.chat('解释这段话', 'session_123', undefined, undefined, {
+  extra: {
+    cite: '这是引用的文本内容',
+    command: 'translate',
+  },
+});
+```
+
+**参数说明**：
+
+| 参数 | 类型 | 必需 | 说明 |
+|------|------|------|------|
+| `userInput` | `string` | 是 | 用户输入内容 |
+| `sessionCode` | `string` | 是 | 会话代码 |
+| `url` | `string` | 否 | 自定义接口地址，默认 `'chat_completion/'` |
+| `config` | `IRequestConfig` | 否 | 额外请求配置 |
+| `property` | `IMessageProperty` | 否 | 消息属性 |
+
+#### stopChat()
+
+停止当前聊天流式响应。
+
+```typescript
+agent.stopChat();
+```
+
+#### resumeStreamingChat(sessionCode, url?, config?)
+
+恢复流式聊天（用于页面刷新后继续接收响应）。
+
+```typescript
+// 如果最后一条消息处于流式传输中，重新建立连接
+agent.resumeStreamingChat(sessionCode);
+```
+
+---
+
+## Session 模块
+
+### 响应式数据
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| `list` | `Ref<ISession[]>` | 会话列表 |
+| `current` | `Ref<ISession \| null>` | 当前会话 |
+| `isListLoading` | `Ref<boolean>` | 列表加载状态 |
+| `isCurrentLoading` | `Ref<boolean>` | 当前会话加载状态 |
+| `isCreateLoading` | `Ref<boolean>` | 创建加载状态 |
+| `isUpdateLoading` | `Ref<boolean>` | 更新加载状态 |
+| `isDeleteLoading` | `Ref<boolean>` | 删除加载状态 |
+| `isRenameLoading` | `Ref<boolean>` | 重命名加载状态 |
+
+### 方法
+
+#### getSessions()
+
+获取会话列表。
+
+```typescript
+await session.getSessions();
+console.log(session.list.value);
+```
+
+#### chooseSession(sessionCode)
+
+选择会话。会自动：
+1. 停止当前聊天
+2. 设置 `current`
+3. 加载该会话的消息
+4. 如果最后一条消息是流式状态，恢复聊天
+
+```typescript
+await session.chooseSession('session_123');
+```
+
+#### getSession(sessionCode)
+
+获取单个会话详情。
+
+```typescript
+await session.getSession('session_123');
+console.log(session.current.value);
+```
+
+#### createSession(session)
+
+创建新会话。
+
+```typescript
+await session.createSession({
+  sessionCode: `session_${Date.now()}`,
+  sessionName: '新会话',
+  isTemporary: false,
+  model: 'gpt-4',
+});
+```
+
+#### updateSession(session)
+
+更新会话信息。
+
+```typescript
+await session.updateSession({
+  sessionCode: 'session_123',
+  sessionName: '更新后的名称',
+});
+```
+
+#### deleteSession(sessionCode)
+
+删除会话。如果删除的是当前会话，会自动切换到第一个会话。
+
+```typescript
+await session.deleteSession('session_123');
+```
+
+#### renameSession(sessionCode)
+
+AI 智能重命名会话。
+
+```typescript
+await session.renameSession('session_123');
+```
+
+#### postSessionFeedback(feedback)
+
+提交会话反馈（点赞/点踩）。
+
+```typescript
+await session.postSessionFeedback({
+  sessionCode: 'session_123',
+  rate: 1,  // 1=点赞, -1=点踩
+  labels: ['回答准确', '信息全面'],
+  comment: '很有帮助',
+  sessionContentIds: [1, 2],  // user message 的 ID
+});
+```
+
+#### getSessionFeedbackReasons(rate)
+
+获取反馈原因列表。
+
+```typescript
+const reasons = await session.getSessionFeedbackReasons(1);  // 点赞原因
+const reasons = await session.getSessionFeedbackReasons(-1); // 点踩原因
+```
+
+---
+
+## Message 模块
+
+### 响应式数据
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| `list` | `Ref<IMessage[]>` | 消息列表 |
+| `isListLoading` | `Ref<boolean>` | 列表加载状态 |
+| `isDeleteLoading` | `Ref<boolean>` | 删除加载状态 |
+
+### 方法
+
+#### getMessages(sessionCode)
+
+获取会话消息列表。
+
+```typescript
+await message.getMessages('session_123');
+```
+
+#### plusMessage(message)
+
+本地添加消息（不调用接口）。
+
+```typescript
+message.plusMessage({
+  role: MessageRole.User,
+  content: '你好',
+  status: MessageStatus.Complete,
+});
+```
+
+#### createAndPlusMessage(message)
+
+创建消息（调用接口）并添加到列表。
+
+```typescript
+await message.createAndPlusMessage({
+  role: MessageRole.User,
+  content: '你好',
+  status: MessageStatus.Complete,
+  sessionCode: 'session_123',
+});
+```
+
+#### modifyMessage(message)
+
+本地修改消息。
+
+```typescript
+const msg = message.getMessageByMessageId('msg_123');
+if (msg) {
+  msg.content = '修改后的内容';
+  message.modifyMessage(msg);
+}
+```
+
+#### deleteMessages(messages)
+
+批量删除消息。
+
+```typescript
+const messagesToDelete = [msg1, msg2, msg3];
+await message.deleteMessages(messagesToDelete);
+```
+
+#### getCurrentLoadingMessage()
+
+获取当前加载中的消息（状态为 Pending 或 Streaming）。
+
+```typescript
+const loadingMsg = message.getCurrentLoadingMessage();
+if (loadingMsg) {
+  console.log('正在响应中:', loadingMsg.content);
+}
+```
+
+#### getMessageByMessageId(id)
+
+根据 ID 查找消息。
+
+```typescript
+const msg = message.getMessageByMessageId('msg_123');
+```
+
+---
+
+## ISession 类型
+
+```typescript
+interface ISession<ITool = unknown, IAnchorPathResources = unknown> {
+  sessionCode: string;           // 会话代码（唯一标识）
+  sessionName: string;           // 会话名称
+  isTemporary?: boolean;         // 是否临时会话
+  model?: string;                // 使用的模型
+  createdAt?: string;            // 创建时间
+  updatedAt?: string;            // 更新时间
+  tools?: ITool[];               // 可用工具
+  rate?: number;                 // 评分
+  labels?: string[];             // 标签
+  comment?: string;              // 评论
+  anchorPathResources?: IAnchorPathResources;  // 锚点资源
+  roleInfo?: {                   // 角色信息
+    collectionId: number;
+    collectionName: string;
+    content: IMessage[];
+    variables: { name: string; value: string | IMessage[]; }[];
+  };
+  sessionProperty?: {            // 会话属性
+    isAutoCalcPrompt?: boolean;
+    isAutoClear?: boolean;
+  };
+}
+```
+
+---
+
+## IMessage 类型
+
+### 用户消息
+
+```typescript
+interface IUserMessage {
+  id?: string;
+  messageId?: string;
+  role: MessageRole.User;
+  status: MessageStatus;
+  content: string | IInputContent[];  // 文本或多媒体
+  property?: IMessageProperty;        // 引用、快捷键等
+}
+```
+
+### AI 助手消息
+
+```typescript
+interface IAssistantMessage {
+  id?: string;
+  messageId?: string;
+  role: MessageRole.Assistant;
+  status: MessageStatus;
+  content?: string;
+  toolCalls?: IToolCall[];  // 工具调用
+}
+```
+
+### 推理消息
+
+```typescript
+interface IReasoningMessage {
+  id?: string;
+  messageId?: string;
+  role: MessageRole.Reasoning;
+  status: MessageStatus;
+  content: string[];   // 思考步骤数组
+  duration?: number;   // 思考耗时 (ms)
+}
+```
+
+### 工具消息
+
+```typescript
+interface IToolMessage {
+  id?: string;
+  messageId?: string;
+  role: MessageRole.Tool;
+  status: MessageStatus;
+  content: string;       // 工具执行结果
+  toolCallId: string;    // 对应的工具调用 ID
+  duration?: number;     // 执行耗时 (ms)
+  error?: string;        // 错误信息
+}
+```
+
+### 活动消息
+
+```typescript
+interface IActivityMessage {
+  id?: string;
+  messageId?: string;
+  role: MessageRole.Activity;
+  status: MessageStatus;
+  activityType: ActivityType;  // 活动类型
+  content: IActivityContent;   // 活动内容
+}
+
+// 活动内容（如引用文档）
+type IActivityContent = Array<{
+  name: string;
+  url: string;
+  originFileUrl?: string;
+}>;
+```
+
+---
+
+## IAgentInfo 类型
+
+```typescript
+interface IAgentInfo {
+  agentName?: string;   // Agent 名称
+  saasUrl?: string;     // SaaS 地址
+  chatGroup?: {         // 聊天群组配置
+    enabled: boolean;
+    staff: string[];
+    username: string;
+  };
+  conversationSettings?: {      // 会话设置
+    enableChatSession?: boolean;
+    openingRemark?: string;              // 开场白
+    predefinedQuestions?: string[];      // 预设问题
+    commands?: IAgentCommand[];          // 快捷指令
+  };
+  promptSetting?: {     // Prompt 设置
+    content?: IMessage[];
+  };
+}
+```
+
+---
+
+## IToolCall 类型
+
+```typescript
+interface IToolCall {
+  id: string;
+  type: MessageType.Function;
+  function: {
+    name: string;          // 工具名称
+    arguments: string;     // 参数 JSON 字符串
+    description?: string;  // 工具描述
+    mcpName?: string;      // MCP 服务名称
+  };
+}
+```
+
+---
+
+## IMessageProperty 类型
+
+用于传递引用内容或快捷键相关信息。
+
+```typescript
+interface IMessageProperty {
+  [key: string]: unknown;
+  extra?: {
+    [key: string]: unknown;
+    cite?: string | {      // 引用内容
+      title: string;
+      type: string;
+      data: Array<{ key: string; value: string; }>;
+    };
+    command?: string;      // 快捷键命令
+    context?: Array<Record<string, unknown>>;  // 上下文
+  };
+}
+```
+
+---
+
+## IRequestConfig 类型
+
+```typescript
+interface IRequestConfig {
+  url?: string;
+  method?: string;
+  baseURL?: string;
+  headers?: (() => Record<string, string>) | Record<string, string>;
+  data?: (() => unknown) | unknown;
+  params?: Record<string, unknown>;
+  timeout?: number;
+  responseType?: 'json' | 'text' | 'blob' | 'arrayBuffer' | 'formData' | 'stream';
+  credentials?: 'include' | 'omit' | 'same-origin';
+  mode?: 'cors' | 'no-cors' | 'same-origin';
+  controller?: AbortController;
+  transformRequest?: (data: unknown, headers?: Record<string, string>) => unknown;
+  transformResponse?: (data: unknown) => unknown;
+  validateStatus?: (status: number) => boolean;
+}
+```
+
+---
+
+## 枚举类型
+
+### MessageRole
+
+```typescript
+enum MessageRole {
+  User = 'user',
+  Assistant = 'assistant',
+  System = 'system',
+  Tool = 'tool',
+  Activity = 'activity',
+  Reasoning = 'reasoning',
+  Developer = 'developer',
+  Guide = 'guide',
+  Info = 'info',
+  Pause = 'pause',
+  Placeholder = 'placeholder',
+  Hidden = 'hidden',
+  HiddenUser = 'hidden-user',
+  HiddenAssistant = 'hidden-assistant',
+  HiddenSystem = 'hidden-system',
+  HiddenGuide = 'hidden-guide',
+  TemplateUser = 'template-user',
+  TemplateAssistant = 'template-assistant',
+  TemplateSystem = 'template-system',
+  TemplateGuide = 'template-guide',
+  TemplateHidden = 'template-hidden',
+}
+```
+
+### MessageStatus
+
+```typescript
+enum MessageStatus {
+  Pending = 'pending',
+  Streaming = 'streaming',
+  Complete = 'complete',
+  Error = 'error',
+  Stop = 'stop',
+}
+```
+
+### MessageType
+
+```typescript
+enum MessageType {
+  Text = 'text',
+  Binary = 'binary',
+  Function = 'function',
+}
+```
+
+### ActivityType
+
+```typescript
+enum ActivityType {
+  ReferenceDocument = 'reference_document',
+}
+```
+
+### EventType
+
+```typescript
+enum EventType {
+  RunStarted = 'RUN_STARTED',
+  RunFinished = 'RUN_FINISHED',
+  RunError = 'RUN_ERROR',
+  TextMessageStart = 'TEXT_MESSAGE_START',
+  TextMessageChunk = 'TEXT_MESSAGE_CHUNK',
+  TextMessageContent = 'TEXT_MESSAGE_CONTENT',
+  TextMessageEnd = 'TEXT_MESSAGE_END',
+  ThinkingStart = 'THINKING_START',
+  ThinkingTextMessageStart = 'THINKING_TEXT_MESSAGE_START',
+  ThinkingTextMessageContent = 'THINKING_TEXT_MESSAGE_CONTENT',
+  ThinkingTextMessageEnd = 'THINKING_TEXT_MESSAGE_END',
+  ThinkingEnd = 'THINKING_END',
+  ToolCallStart = 'TOOL_CALL_START',
+  ToolCallChunk = 'TOOL_CALL_CHUNK',
+  ToolCallArgs = 'TOOL_CALL_ARGS',
+  ToolCallResult = 'TOOL_CALL_RESULT',
+  ToolCallEnd = 'TOOL_CALL_END',
+  StepStarted = 'STEP_STARTED',
+  StepFinished = 'STEP_FINISHED',
+  MessagesSnapshot = 'MESSAGES_SNAPSHOT',
+  StateSnapshot = 'STATE_SNAPSHOT',
+  StateDelta = 'STATE_DELTA',
+  ActivitySnapshot = 'ACTIVITY_SNAPSHOT',
+  ActivityDelta = 'ACTIVITY_DELTA',
+  Raw = 'RAW',
+  Custom = 'CUSTOM',
+}
+```