常见问题

WesCraft 使用过程中的常见疑问解答。

WesCraft 和普通笔记工具有什么区别？

WesCraft 不是传统笔记工具，而是 AI 原生信息工作台。核心差异：

维度	普通笔记工具	WesCraft
定位	记录与整理	写、收、理、查、出、追——六字闭环
引擎	无	wesgine v1.0 多租户 AI Agent 引擎驱动
文件理解	不理解本地文件	FileIntelligence 引擎索引并理解本地文件
知识处理	手动分类	6-Stage 知识管线自动处理
AI 能力	外挂插件	原生集成五种 AI 交互模式
隔离性	单用户	Cell 物理隔离（个人/团队）

什么是 FileIntelligence？

FileIntelligence（文件智能引擎）是 WesCraft 的本地文件索引系统。它让 AI 能够理解你电脑上已有的所有文件，而不需要手动上传。

核心设计约束

约束编号	内容	说明
FI-1	文件原地不动，只建索引	不复制、不搬移用户文件
FI-4	渐进触发	元数据 → FTS → 向量 → 理解，按需深入
FI-5	永远只读	绝不修改用户本地文件
FI-AP-04	HNSW 索引	向量检索使用 HNSW 索引
FI-AP-07	路径前缀校验	符号链接逃逸防护
FI-AP-08	后台自动索引	fsnotify 监听 + 定期扫描
FI-AP-09	AgenticRAG	模型主动 tool_call 检索，不是 Pre-retrieval

使用方式

在设置中添加关注目录
系统自动建立索引
在对话中直接提问关于本地文件的问题
AI 通过 search_files、read_local_file 等工具自动检索

什么是知识管线？

知识管线（Knowledge Pipeline）是 WesCraft 的 6-Stage 内容处理管线，将原始内容自动转化为结构化知识：

Stage 1: 原始内容采集
Stage 2: 内容清洗与标准化
Stage 3: 自动分块（Chunking）
Stage 4: 索引建立（FTS5 全文 + 语义向量）
Stage 5: 标签生成与分类
Stage 6: 关联检测与知识图谱

每个 Stage 完成后都会记录日志（slog.Info），方便排查问题。

什么是 AI 交互模式？

WesCraft 提供五种 AI 交互模式，覆盖不同使用场景：

模式	触发方式	工具集	典型场景
Ghost Write	光标停留 >800ms	无	写作续写
Selection Action	选中文字	无	润色、翻译
Inline Command	Ctrl+K	Block 操作 6 个	局部编辑
Sidebar Chat	Ctrl+L	全部 19 个	深度对话
后台 AI	页面保存/文件变更	知识管线 + FI	自动处理

所有模式都通过 activeCell.Runtime() 执行，保证 Cell 级隔离。

什么是 Tab 系统？

WesCraft 的核心交互范式："所有内容都是 Tab"。

侧边栏 = 打开 Tab 的触发器
页面、收集箱、任务、数据库、设置等都以 Tab 形式展现
切换 Cell（团队 vs 个人）时，Tab 集独立
同一内容不会重复打开多个 Tab（单例检查）

什么是收集箱（Inbox）？

收集箱是 WesCraft 的多源输入统一入口：

浏览器扩展：网页剪藏 → Inbox
剪贴板：粘贴内容 → Inbox
邮件：邮件转发 → Inbox
文件拖拽：文件 → Inbox
截图：wescraft_screenshot() → Inbox
URL 抓取：capture_url → Inbox

所有采集内容归属当前 Cell，团队版中不同部门的 Inbox 物理隔离。

什么是输出引擎？

输出引擎支持将 WesCraft 内容导出为多种格式：

格式	工具	说明
PDF	`export_pdf`	生成高质量 PDF 文档
Word	`export_docx`	生成 .docx 格式
Markdown	原生支持	直接导出 .md
公众号	`export_wxpub`	微信公众号格式

什么是数据库功能？

WesCraft 内置结构化数据表功能，配合 AI 工具使用：

db_query：查询数据表
db_insert：插入数据行
db_update：更新数据行

使用场景包括项目管理、客户记录、资产清单等需要结构化存储的内容。

个人版和团队版有什么区别？

维度	个人版	团队版
Cell ID	`personal`	`team-<id>`
用户数	1 用户 = 1 Cell	1 团队 = 1 Cell
Actor	恒为 `"local"`	SSO user_id
KB/Memory/Skills	个人独享	团队共享
Provider 策略	`own_only`	可配置
Compliance	`standard`	可选 `pii-strict` / `financial`
Tab 系统	单 Cell	切换 Cell 时 Tab 集独立

如何导出内容？

单页导出

# Sidebar Chat 中使用
请把这个页面导出为 PDF
请把这个页面导出为 Word
请把这个页面导出为公众号格式

Cell 整体迁移

# 导出整个 Cell（含所有数据）
GET /cells/{cellID}/export → tar.gz

# 导入 Cell
POST /admin/cells/import → 恢复

Cell Export 包含：workspace、sessions、memory、knowledge、skills 全部数据。

浏览器扩展怎么用？

安装

从 WesCraft 设置页下载浏览器扩展
安装到 Chrome 或 Edge
确保 WesCraft 桌面端正在运行

使用方式

操作	说明
右键菜单 → 发送到 WesCraft	选中文字或页面 → Inbox
扩展按钮 → 剪藏	整页剪藏 → Inbox
快捷键	自定义快捷键 → 快速剪藏

所有剪藏内容自动归属当前活跃的 Cell。

文件智能和知识库有什么区别？

维度	FileIntelligence	Knowledge（知识库）
数据来源	索引本地已有文件	上传文件到知识库
原始文件	原地不动、只读	分块存储到 Cell 内
可编辑性	不可编辑原文件	可编辑、可删除
搜索方式	文件级搜索 + 语义检索	分块语义搜索
适用场景	理解本地大量已有文档	构建精选知识库
互补关系	两者互补，不互斥	—

Block 编辑器是什么？

WesCraft 使用 BlockNote 块编辑器，页面由 Block 组成。AI 通过 6 个 Block 工具操作页面：

工具	功能
`read_block`	读取 Block 内容
`write_block`	写入新 Block
`edit_block`	编辑现有 Block
`delete_block`	删除 Block
`move_block`	移动 Block 位置
`transform_block`	转换 Block 类型

Block 类型包括：段落、标题、列表、代码、引用、表格、图片等。

Device Agent 是什么？

Device Agent 是 WesCraft Electron 主进程内嵌的设备代理，通过 MCP 协议向 Cell 暴露本地能力：

MCP 工具	功能
`wescraft_screenshot()`	截屏保存到当前 Cell Inbox
`wescraft_clipboard_read/write()`	剪贴板读写
`wescraft_show_file(path)`	Finder/Explorer 定位文件
`wescraft_open_app(bundleID)`	打开外部应用
`wescraft_notify(title, body)`	系统通知

Device Agent 在应用关闭时自动断开，工具从 Cell 视图消失。

CycleDetector 怎么配？

CycleDetector 防止 AI 陷入死循环。WesCraft 的 19 个工具分为三类：

ExtraCategories（10 个只读 → exploration）

list_pages / read_page / search_pages / query_blocks / db_query
search_files / read_local_file / find_related_files / file_overview / export_doc

ExtraProgressAware（5 个写入 → halving）

参数变化时 streak 减半：

write_block / edit_block / delete_block / move_block / transform_block

默认 action 类（4 个写入工具）

create_doc / db_insert / db_update / assemble_from_files

这意味着只读操作阈值更宽松（允许大量探索），写入操作会根据参数变化智能降低 streak 计数，减少误判。