Scholar Harness
使用指导手册
面向科研项目的 AI 工作台：从资料入库、句子级证据检索、研究规划，到章节写作、数据分析、R 作图和整篇导出。
适用版本：1.0.11
开始之前
本手册按真实任务组织。新用户建议先阅读第 1-4 节，再根据自己的研究任务进入对应模块。
1. 五分钟完成首次配置
2. 界面、模型与对话
3. 项目、工作目录与数据安全
4. AI 与本地插件配置
5. 建立文献库与 Embedding 检索
6. PDF Wiki 句子级证据库
7. Research Mission 研究准备
8. 写作、智能草稿与论文图片
9. 引用、尾注与目标期刊格式
10. 数据分析与 R 作图
11. Meta 分析与图像数字化
12. 文献计量分析
13. Skill、长期记忆与 Obsidian
14. 导出、更新与故障排查
最短上手路径：运行新手向导 → 选择一个 AI → 建立项目 → 上传文献或设置工作目录 → 直接在主页描述任务。
1. 五分钟完成首次配置
首次启动后，软件会检查本机可用的 Codex CLI、R、Python 和 OfficeCLI，并给出推荐设置。开始使用只需要一个可用 AI；R、Python、OfficeCLI 和 Embedding 可在需要时再配置。
注册或登录账号。使用邮箱完成注册和登录；如持有授权码，可在注册时填写，也可登录后从账户气泡中填写。
运行“新用户设置向导”。可在首次启动页进入，也可从右上角齿轮 → 配置 → 新用户设置重新打开。
选择一个 AI。可从 API 模型、Free corse 或 Agent corse 中选择一条运行路线；只需先配置真正要使用的项目。
创建项目。项目用于隔离文献、草稿、分析结果、图片和长期记忆。
完成第一个任务。可以直接提问、上传 PDF、上传 WoS/CNKI 导出文件，或设置工作目录让 AI 读取本地材料。
API 地址：兼容 OpenAI 的服务通常填写到 /v1，不要手工追加 /chat/completions。保存前先使用配置页的连接测试。
2. 界面、模型与对话
2.1 三条运行路线如何分工
| 运行路线 | 可选服务 | 适合任务 |
|---|
| API 模型 / Little corse | DeepSeek、OpenAI、Kimi、Qwen 等兼容服务 | 日常问答、段落写作、引用匹配和轻量数据解释 |
| 本地与开放模型 / Free corse | Ollama、llama.cpp、OpenRouter、Qwen 3.8 27B | 在自己的设备运行模型，或使用开放模型服务 |
| Agent 执行 / Agent corse | Pi、Codex、OpenCode、Reasonix | 读取和修改工作目录、运行工具、生成脚本和文档 |
在 Agent corse 中点击某个 Agent 后，页面只展开该 Agent 的配置。Pi、Codex、OpenCode 和 Reasonix 独立保存运行参数；Reasonix 由用户按需一键部署，软件不写死其版本号或安装路径。
2.2 输入框与任务队列
- 直接输入自然语言即可；运行中仍可继续发送，新任务会排队。
- 输入
@ 可选择当前工作目录中的文件或文件夹，将路径随问题发送给 AI。
- 可拖动文件到主页；松手后软件记录文件名与本地路径，并按用户问题处理，而不是只做固定的文件解析。
- 输入框上方可持续使用文献计量、Meta、Research Mission、Skill 等结果。
2.3 侧边栏和页面
左侧是功能导航，右侧用于文章写作进度和论文图片。左右侧栏互斥展开，避免遮挡正文。打开二级页面后，新建对话会关闭当前子页面并返回新会话。
2.4 账户、授权与剩余额度
左下角账户气泡显示当前授权的剩余天数，以及 PDF 和文献计量剩余额度。点击“填写码”可录入授权码并立即刷新授权状态。
- 剩余天数：表示当前授权有效期；到期前均可使用已开放功能。
- PDF 额度：用于需要云端计量的 PDF 处理任务，以实际成功处理的篇数结算。
- 文献计量额度：按实际成功处理的文献记录数结算。
- 任务启动时会临时预留额度；失败任务会释放预留额度，部分完成时只结算实际完成数量。
授权码可在两个位置填写：注册页面，或登录后的账户气泡。官网其他页面不会要求用户输入授权码。
3. 项目、工作目录与数据安全
3.1 项目管理
不同课题应建立不同项目。需要用同一主题写两篇文章时，可复制项目后分别修改，避免草稿和证据混用。
3.2 设置工作目录
点击主页输入框旁的文件夹按钮，粘贴或选择研究目录。
选择权限：只读、工作区可写或完全访问。
点击检查目录。软件会分类展示图片、Word、Excel、PDF、R、Python 及其他文件，并支持递归检索子文件夹。
勾选文件、从 @ 菜单选择文件，或直接在问题中写明路径和任务。
| 权限 | 能力 | 建议 |
|---|
| 只读 | 读取、检索、分析，不修改文件 | 首次检查陌生目录时使用 |
| 工作区可写 | 可在安全工作副本中创建和修改文件 | 常规写作、分析和作图推荐 |
| 完全访问 | 允许更广泛的本地工具操作 | 只在明确理解风险时启用 |
安全副本：启用工作目录后，软件会创建 ScholarHarness_AI_Workspaces/SH-... 工作文件夹。AI 优先复制所需材料到该目录并在副本上工作，原始目录主要作为读取来源。
注意：任何自动化工具都不能替代备份。重要原始数据仍应保留在独立磁盘、云盘或版本库中。
4. AI 与本地插件配置
4.1 AI 配置
- 进入右上角齿轮 → 模型/API 配置。
- 填写服务地址、API Key 和模型名称，先测试再保存。
- Codex 页面可设置 CLI 路径、模型和 Reasoning Effort。模型切换时，界面会按该模型实际支持的推理档位调整。
4.2 全局本地插件
| 插件 | 用途 | 配置方式 |
|---|
| R / Rscript | 统计分析、Meta、期刊图件、R 脚本运行 | 自动检测、一键安装或保存 Rscript.exe 路径 |
| Python | 数据处理、文档与图片辅助、脚本运行 | 自动检测、一键安装或保存 python.exe 路径 |
| OfficeCLI | 创建、检查和修改 Word/Excel/PPT | 一键安装或保存可执行文件路径 |
插件保存后全局可用，主页、讨论式写作、Meta、数据分析和工作目录 Agent 都应使用同一配置。
4.3 在主页按需安装 Skill 和插件
无需先进入配置页逐项寻找。可直接在主页聊天框描述需要的 Skill 或插件；运行中的 AI 发现能力缺失时，也可以检索候选并引导安装。新增内容会作为对应文件附件显示在聊天气泡下方，便于打开和核对来源。
批量选择 Skill 时：软件只把名称、摘要和当前任务真正需要的说明发送给 AI，不应一次塞入全部 Skill 正文。若上下文仍过长，应取消无关项后重试。
5. 建立文献库与 Embedding 检索
5.1 导入支持
可上传 WoS、CNKI 或文献管理软件导出的 RISBibTeXTXTCSVExcel 文件。系统统一解析题名、作者、年份、期刊、DOI、摘要和关键词。
上传导出文件解析与去重生成 Embedding语义检索写作引用
5.2 推荐操作
- 在新手向导选择“上传 WoS/CNKI 导出文件，建立句子级 Embedding 知识库”，或从 Embedding 文献库页面上传。
- 等待解析、去重和向量化完成；新会话会自动加载当前项目文献库状态。
- 在主页描述需要证据支持的句子或论点，或进入“快速句子级论点检索”。
- 检索会优先匹配摘要中的结论性内容，并按“支持、高质量相关、仅相关、相反、无关”组织结果。
Embedding 文献库适合广泛检索；PDF Wiki 适合精确回到原文句子。写作中可以同时使用，但两者的证据标识不能混淆。
6. PDF Wiki 句子级证据库
PDF Wiki 不是普通摘要工具。它把 PDF 原文拆成稳定编号的句子，并将句子级论点、来源页码、文内引用和参考文献索引关联起来。
上传 PDF，等待文本解析；扫描件可切换更强的 OCR/Marker 解析。
生成句子级 Wiki 论点库。PDF 较多时可在配置页增加 Codex CLI 并发数。
在快速检索中输入需要文献支撑的句子，查看支持、相反和相关证据。
打开原文核查上下文、页码、原始引用和参考文献。
6.1 编号与尾注对应
| 位置 | 规范 |
|---|
| 文中 | 使用该证据句的唯一编号，不能由 AI 根据相似度猜编号。 |
| 尾注 | 使用“编号 + 句子内容 + 来源信息”，与文中编号一一对应。 |
| 证据不足 | 保留“需核查”标记，回到 PDF 原文确认后再用于投稿。 |
7. Research Mission 研究准备
Research Mission 用于选题审查、研究边界锁定、证据矩阵和写作蓝图。它应在正式长文写作前运行，而不是代替用户定义科学问题。
输入主题拆解科学问题检索证据评估风险生成蓝图
主要产物
- 选题审查：论文类型、创新边界、证据缺口和不可过度声称的结论。
- Evidence Matrix：主张、变量、机制、结果与证据强度。
- 写作蓝图：中心论点、章节任务、支持主张、反证与局限。
- 内容增强报告：供 Results、Discussion 和 Conclusion 持续调用。
完成后的报告会出现在聊天气泡下方，可下载，也可勾选为后续对话的持续上下文。
8. 写作、智能草稿与论文图片
8.1 一键写论文
- 选择论文类型、语言、目标期刊、字数和可用资料。
- 系统先规划章节，再按段落检索证据并写作。
- 长任务会显示进度；完成后的 Word、PDF、Markdown 和图件直接放在气泡下方。
8.2 讨论式写作与智能保存
右侧“文章写作进度”动态展示当前项目的章节 TXT。保存时，系统根据用户明确选择的章节、正在写的章节和内容结构确定目标，不应把 Results 小节创建成与 Results 平行的主章节。
- 每个主章节只使用一个 TXT，例如
introduction.txt、results.txt、discussion.txt。
- 小节写入所属主章节 TXT，不再创建
results_33.txt 等碎片文件。
- 用户可勾选章节提问，章节路径和最新内容会随 query 发送给 AI。
- 可在右侧编辑、保存或删除章节；允许 AI 按写作要求创建新的合理章节。
- 章节 TXT 更新后，整篇导出文件自动同步，AI 读取的也是最新草稿和写作进度。
8.3 论文图片
上传图片时可填写 Figure 分组、名称、标题和图注；未填写分组时也可按普通任务让 AI 分析。已归档图片在右侧“论文图片”中展示，支持打开、编辑、多选删除和合并。AI 或工具新生成的图片也会作为最新文件附件显示。
9. 引用、尾注与目标期刊格式
9.1 文内引用
常规作者-年份制应写为 (Zhang et al., 2026)。正文中的引用标记与文末参考文献条目用途不同，不能把作者-年份标记重复放在文末条目前。
9.2 文末参考文献
在快速论点检索输入框上方设置“目标期刊参考文献尾注格式”，可上传或粘贴该期刊的真实参考文献样例。AI 应按样例输出全部作者、年份、题名、期刊、卷期页码和 DOI；样例没有的前缀不要自行添加。
提交前必须核查：作者是否完整、年份和题名是否正确、DOI 是否真实、正文每条引用是否在文末出现，以及文末是否存在未引用条目。
9.3 引用来源边界
- PDF Wiki：保留句子证据编号和可追溯来源。
- Embedding 文献库：使用正常作者-年份或编号制引用。
- AI 不得编造缺失的卷、页码、DOI 或作者；未知信息应明确标记待核查。
10. 数据分析与 R 作图
上传 Excel/CSV，或从工作目录选择数据文件与指定 sheet。
说明因变量、自变量、处理、时间、重复、单位和需要的统计方法。
确认各处理/分组颜色。AI 可推荐 Okabe-Ito、Nature、NEJM/Lancet、Cell 等常用配色。
运行分析与 R 脚本，检查统计输出、图件和脚本文件。
颜色确认会形成命名颜色向量；同一处理在不同图、panel、color 和 fill 中保持一致。AI 修复 R 代码时也应保留这套配置。
作图前应提供的信息
- 数据文件与 sheet 名；变量含义、单位和缺失值规则。
- 处理组顺序、对照组、误差类型（SD/SE/CI）和显著性标记。
- 目标图尺寸、期刊风格、颜色和输出格式（PNG/PDF/TIFF）。
11. Meta 分析与图像数字化
11.1 AI 驱动的 Meta 目标
Meta 页面输入框与主页一致，可选择模型、上传文件、停止运行。用自然语言说明因变量、处理、连续/分类调节变量、效应量和聚类字段，AI 会先检查数据结构再提出分析方案。
11.2 标准流程
导入编码表复核列与单位计算效应量拟合模型诊断与作图写作输出
- 检查 Study/Obs、处理组/对照组、均值、SD/SE、样本量和方向。
- 运行总体效应、异质性、调节变量、敏感性、漏斗图和发表偏倚检验。
- 下载效应量 CSV、模型结果、R 脚本、森林图和漏斗图。
11.3 图像数字化复核
先标定 X/Y 最小值和最大值，再采点、撤销或清空。采点结果可写入指定单元格、批量竖填或填入全部行；“确定”会保存处理后的最终数据，而不是只改变页面显示。
数字化结果必须抽样复核坐标、坐标轴变换和单位。对数轴、倒序轴和分组图不能按普通线性坐标处理。
12. 文献计量分析
- 导入 WoS/CNKI 导出文件，检查记录数、年份、作者、机构、关键词和来源期刊。
- 运行关键词共现、作者/机构合作、主题聚类、研究热点、主题演化和知识结构分析。
- 在写作准备区域查看：计量学论文草稿、10 项分析就绪度、方法可写内容、结果可写内容、讨论角度和局限性。
- 将结果勾选为持续上下文后，随 query 一起发送给 AI。
鼠标移动到写作准备气泡时，下方会展开相应内容。写作前应确认数据来源、检索式、检索日期、去重规则和软件参数均可复现。有限额度授权按实际成功处理的文献记录数结算，失败任务不会消耗已释放的预留额度。
13. Skill、长期记忆与 Obsidian
13.1 Skill
软件会把可用 Skill 的名称和功能发给 AI，由 AI 按用户意图自动调用；这与用户手动选择 Skill 不冲突。
- 内置章节写作、引用相关性、科研审稿、数据/文档处理等 Skill。
- Skill 发现器可根据需求联网检索候选，并列出来源后供用户安装。
- 支持从 GitHub 仓库、目录、
SKILL.md 或 raw 链接导入。
- 可直接在主页聊天中提出安装需求；安装完成后，Skill 或插件文件会显示在对应聊天气泡下方。
13.2 长期记忆
长期记忆按当前 query 检索筛选；历史会话主要发送最近 3-5 条摘要，并按先后顺序携带最近 15 条用户 query，帮助 AI 理解最新要求。不同项目的研究事实应分别维护。
13.3 Obsidian
内置 Obsidian 知识库用于整理 PDF Wiki 句子级论点，可一键生成并同步 Obsidian 兼容 Markdown Vault。该操作不会安装或启动 Obsidian 客户端；整理后的论点可在软件内检索，也可以把生成目录作为 Vault 在 Obsidian 中打开。
14. 导出、更新与故障排查
14.1 导出与打开文件
- AI 生成的 Word、PDF、Excel、R 脚本和图片会显示在对应气泡下方。
- “打开文件”由 Electron 使用本地绝对路径打开；不要把 Windows 路径当作网页 URL。
- Word 草稿默认使用 Times New Roman；中文字体可按期刊或学校模板进一步设置。
- 附件展示以最新路径和最新修改时间为准；同一路径更新后应刷新预览，避免旧缓存。
- 右侧文件预览支持双击内容区域进入编辑；CSV 会以结构化表格方式编辑和保存，不再切换成难以阅读的纯文本。
14.2 软件更新
客户端会检查官网的最新版本清单。发现更高版本后，页面左下角显示更新提示，点击即可下载最新安装包。升级前建议完成当前长任务并备份重要项目。
14.3 常见问题
| 问题 | 处理方法 |
|---|
| API 模型连接失败：fetch failed | 先在配置页测试 API；检查地址、Key、模型、代理、防火墙和服务商状态。查看本地日志中的真实网络错误。 |
| Reasonix 提示缺少 API Key | 在 Reasonix 配置中保存对应服务商的 Key 后重新检测；不要把 Key 直接发送到聊天记录。 |
| PDF 或文献计量额度不足 | 打开左下角账户气泡核对剩余数量；如有新的授权码，点击“填写码”更新额度后重试。 |
| R 未安装，但已经配置过 | 在配置 → 本地插件重新检测，确认保存的是可执行的 Rscript.exe；配置应全局生效。 |
| Codex 一直运行或工具失败 | 检查 Codex 日志、工作目录权限和本机 CLI；Notion MCP 等外部连接失败通常不影响本地文件读取。 |
| 找不到子文件夹中的 Word/数据 | 确认工作目录正确、索引已刷新，并通过 @ 或分类文件区直接选择；大型目录可缩小检索范围。 |
| 图片预览失败或还是旧图 | 点击刷新目录，确认文件存在且未被移动；同名图更新后按修改时间刷新，必要时重新打开会话。 |
| 右侧草稿没有更新 | 确认目标项目和主章节 TXT；刷新文章写作进度，检查保存结果是否明确返回章节 key 和文件路径。 |
| 新用户不知道如何配置 | 从右上角齿轮重新运行“新用户设置向导”，只配置一个可用 AI 后先完成示例任务。 |
14.4 投稿前检查清单
- 研究问题、方法和结果之间一致，没有 AI 擅自扩大结论。
- 统计方法、样本量、单位、误差线和显著性标记均已人工复核。
- 正文引用与文末参考文献逐条对应，作者、年份、DOI 可验证。
- PDF Wiki 证据已回到原文核查，不保留未经确认的“需核查”内容。
- 图表颜色、处理顺序、字体、尺寸和图注符合目标期刊要求。
- 最终 Word/PDF 已人工通读，并保存独立备份。