Agent MCP 接入：stdio、HTTP 与连接管理
连接已有 MCP 服务，把目录与业务系统变成智能体工具。支持按服务器设置 toolAllowlist、按需发现与提前装载；连接生命周期可以跟随会话，也可以由应用集中持有。
import { createMcpHost, createSession } from '@tansr/sdk';
const host = createMcpHost({
servers: {
local: { transport: 'stdio', command: 'node',
args: [mcpServerEntry] },
knowledge: { transport: 'http',
url: 'https://mcp.example.com/mcp',
toolAllowlist: ['search'] },
},
});
const session = await createSession({ token, baseUrl, mcp: host });
// Reuse host across sessions; dispose when the application exits.
// await host.dispose();
白名单控制暴露的工具，不代替运行时审批。MCP 工具按第三方操作保守判定；应用需配置明确的权限规则或接 askUser。关闭会话不会替你销毁共享 host。
AI 本地文件处理与文件助手 SDK
读取、目录列举、Glob/Grep 检索以及按授权写入和编辑文件，可用于文档助手、项目分析或桌面自动化。给应用选择必要的工具，再决定哪些操作需要确认。
const session = await createSession({
token, baseUrl,
cwd: workspaceDir,
tools: { builtin: ['read', 'glob', 'grep', 'list'] },
});
write、edit、shell 可按需求显式选择，但必须先获得能力授权并通过执行权限。cwd 是工作目录，不是操作系统沙箱；宿主仍需约束进程权限与可访问数据。
Agent Skills：按需装载业务知识与流程
defineSkill 注入领域说明，dirs 装载你明确提供的 SKILL.md 目录。简要索引进入上下文，详细内容按需读取，适合把业务流程交给智能体，而不是把所有文档塞进每轮提示。
import { createSession, defineSkill } from '@tansr/sdk';
const review = defineSkill({
name: 'contract-review',
description: '合同审阅流程',
whenToUse: '用户要求检查合同风险时',
instructions: '# 审阅步骤\n先列出事实，再标记待人工确认项。',
});
const session = await createSession({
token, baseUrl,
skills: { custom: [review], dirs: ['./assets/skills'] },
});
SDK 不自动扫描终端用户的技能目录。Skills 是指引与知识，不会给工具增加权限，也不保证模型输出正确。应用需启用 skills 能力。
AI 流式输出与工具调用状态展示
createSessionView 将增量文本、工具执行状态和用量事件投影为不可变界面状态，可接 React 或其他 UI。createNarrator 可并行生成可读日志；AgentSession.events 的订阅者有独立游标。
import { createSessionView, createNarrator } from '@tansr/sdk';
const view = createSessionView(session, {
delivery: { text: 'stream', thinking: 'off' },
});
const unsubscribe = view.subscribe(state => render(state));
const narrator = createNarrator(session.events, {
verbosity: 'normal', onLine: line => logger.info(line),
});
view.appendUserMessage(text);
session.send(text);
// Host teardown: unsubscribe(); view.dispose(); narrator.dispose();
在发送前挂好需要的订阅者，避免晚订阅时误期待历史重放。用户消息由宿主显式追加到视图。关闭 thinking 展示不等于停止模型生成或计量思考 Token。
Electron AI 集成：主进程运行，IPC 传状态
桌面应用 AI SDK 的接入点是 Electron 主进程。主进程持令牌、运行会话和工具，renderer 接收投影状态；通过受控 preload 桥发送用户输入和确认结果。
// Electron main process: window is your BrowserWindow.
const session = await createSession({ token, baseUrl });
const view = createSessionView(session);
const unsubscribe = view.subscribe(state => {
window.webContents.send('agent:state', state);
});
// Handle input via a narrow IPC/preload bridge.
// Validate the sender and input before session.send(text).
在文档中查看 Electron 主进程、preload 和权限桥示例。Electron 需要匹配 SDK 的 Node 运行要求（样板采用 Electron ≥39）；不要向 renderer 暴露 appkey、通用文件系统或任意执行接口。
多轮对话、会话存储与恢复
Agent 会话管理可从内存起步，再注入 SessionStore。createFileSessionStore 提供文件存储实现；也可以实现自己的存储接口。恢复历史与继续保存是两个明确选项。
import { createFileSessionStore, createSession } from '@tansr/sdk';
const store = createFileSessionStore({ dir: userDataDir });
const session = await createSession({ token, baseUrl, store });
session.send('记住这次任务的要求');
await session.idle();
const sessionId = session.sessionId;
session.close();
const resumed = await createSession({
token, baseUrl,
resume: { sessionId, store },
store, // Continue persisting the resumed conversation.
});
没有注入 store 或回调时，会话默认保存在内存。也可用 initialMessages / onHistoryCommit 对接已有数据库；meta.rewritten=true 时须替换已存历史，不可只追加尾部。存储访问控制、加密与保留期由宿主负责。
上下文压缩与可恢复快照
运行时在已知模型上下文窗口时支持自动压缩，也提供手动 compact、checkpoint 与 restore。长期任务可保存上下文检查点，恢复或分支继续处理。
// A store with checkpoints has been wired into session.
await session.idle();
const mark = await session.checkpoint({ label: 'before-summary' });
const result = await session.compact({
instructions: '保留任务约束和未完成事项',
});
if (result.status === 'compacted') {
console.log(result.compactionId);
}
const restored = await session.restore(mark.checkpointId);
console.log(restored.status);
压缩是有损摘要，不承诺永久记住全部细节；快照恢复只恢复上下文，不撤销已经发生的文件写入、网络请求或外部业务动作。关键事实应写入你的可信业务存储。
多模型接入与会话中切换
平台令牌模式从应用授权目录取得模型，按可用别名切换后续轮次。Node.js 服务还可选本地配置托管模式；测试与特殊集成可成对注入 client 和 model。
const session = await createSession({ token, baseUrl });
// Use an alias/handle available in this app's authorized bundle.
session.setModel('main');
session.send('按新选择的模型继续处理');
不是任意填一个厂商模型名就能调用。setModel 对后续轮生效，不重写正在执行的请求；可用输入能力、上下文窗口与输出能力随所选模型而定。
Agent 权限控制与 AI 工具调用审批
能力开关决定应用能装配什么，运行时规则决定这一调用能否执行。askUser 把需要人工确认的调用交给你的界面；在平台令牌模式，还可结合已任命裁决人的判断。
const session = await createSession({
token, baseUrl,
permission: {
rules: {
deny: ['Shell'],
ask: ['Write', 'Edit', 'mcp__knowledge__*'],
},
askUser: async (call, signal) => {
const approved = await confirmTool(call.name, call.args, signal);
return approved ? 'allow' : 'deny';
},
},
});
需要 ask 但未接确认回调时不会默认执行。0.11.1 中显式 permission.mode 与已任命裁决人会发生装配冲突，因此示例省略 mode；不能依赖尚未发布的 0.12.0 兼容行为。审批不是操作系统隔离，也不替代业务授权。