Scholar Writing Assistant

Scholar Writing Assistant 是一个面向中文法学学术写作的 VS Code / CodeArts 插件。它把 Markdown 手稿、法学引注、中文排版、修辞诊断、提示词管理和写作技能调度放在同一个编辑器工作流里。

当前文档对应代码版本：0.4.13。

核心能力

• 中文排版：空白清理、中英文间距、智能引号配对。
• 法学引注：选区引注格式化、全文引注诊断与格式化。
• 学术分析：Prompt Studio、选区改写、论证审计、模板导入。
• 写作技能：导入本地技能目录，并根据选中文本生成技能 prompt。
• 修辞工具：修辞动作标注、句型检索、写作仪表盘。
• Flow Engine：语域断裂检测、语流预期检验，帮助检查段落从具体事实跳回抽象论断时是否缺少过渡。
• 导出：Markdown 手稿导出为 Word .docx。

Pilot 写作驾驶舱（v0.2+）

侧边栏的 Scholar 视图现在显示一个跟随活动编辑器的"驾驶舱"：

• 阶段：从路径 / 文件名 / 契约文件 / frontmatter 推断当前阶段（00_选题 → 07_成果）。
• 诊断条：实时运行《法学引注手册》排版、中英文间距、引号配对、引注核验、语流断裂、修辞动作识别——点击行跳到出错点，点 修复 一键应用。
• 契约：自动读取项目根的 THESIS-SPEC.md / OUTLINE.md / CONCEPTS.md 完成度。
• 下一步：根据阶段 + 契约状态推荐动作，缺 spec 时强制顶置「创建 THESIS-SPEC.md」。
• 范文检索改写：选中文本 → Cmd/Ctrl + Alt + Shift + Y → 选择目标（润色/论证加强/修辞替换）→ 系统从 Profile（必需）/ Zotero（可选）检索范文 → LLM 改写 → Diff 预览 → Cmd/Ctrl+Enter 接受。

配置

快速开始

npm install
npm run build
npm test
node test/test-basic.js
npm run test:e2e

在 VS Code 或 CodeArts 中打开本目录，按 F5 启动扩展开发宿主。也可以运行：

bash final-verify.sh

主界面

安装插件后，VS Code 左侧 Activity Bar 会出现 Scholar 图标。默认显示 Workspace (Dashboard)、LLM Inspector、Library 三个视图；启用 writingAgent.legacyViews 后，才会额外显示旧版 Diagnostics 与 Flow Engine TreeView。Library 把原先的 Skills / Templates / Prompts 合并成一个三段式树视图。

LLM Inspector 会显示当前 LLM 设置、最近一次最终发送给模型的 prompt、请求状态和返回结果落点，方便检查 Prompt Studio、模板和选区改写实际调用了哪个模型与接口。

韵律引擎（可选）

Flow Engine / 完整诊断中的 D1–D9 韵律指标默认走插件自带的 fallback 实现：依赖少、零配置即可用，但精度低于完整版（hanyu-prosody-lab）。

若你拥有 hanyu-prosody-lab 源码，可以在 VS Code 设置里指向它的 engine/ 目录：

• 设置项：writingAgent.prosody.enginePath
• 取值：完整版 engine/ 目录的绝对路径，例如 /Users/<you>/path/to/hanyu-prosody-lab/prosody-diagnose/engine
• 留空时使用 fallback。

修改设置后插件会自动重启 sidecar，无需重载窗口。

常用命令

• Scholar: Format Document (中文排版)
• Scholar: Import Sample Data (导入范文)
• Scholar: Format Selected Citation (法学引注)
• Scholar: Format All Citations in Document
• Scholar: Prompt Studio (学术分析)
• Scholar: 改写/审计选中文本
• Scholar: Run Full Diagnosis
• Scholar: Writing Dashboard (写作仪表盘)
• Scholar: Detect Register Shifts in Selection (选区语域断裂检测)
• Scholar: Expect-Next Flow Check (语流预期检验)
• Scholar: Save Prompt (保存提示词)
• Scholar: Export to Word (.docx)

快捷键

• Cmd/Ctrl + Alt + Shift + ;：格式化当前 Markdown 文档。
• Cmd/Ctrl + Alt + Shift + C：格式化选中引注。
• Cmd/Ctrl + Alt + Shift + K：根据选区调度写作技能。
• Cmd/Ctrl + Alt + Shift + L：把当前编辑器文件导入为范文 Profile 样本。
• Cmd/Ctrl + Alt + Shift + T：打开 Prompt Studio。
• Cmd/Ctrl + Alt + Shift + R：改写或审计选中文本。
• Cmd/Ctrl + Alt + Shift + E：导出 Word。
• Cmd/Ctrl + Alt + Shift + D：打开写作仪表盘。
• Cmd/Ctrl + Alt + Shift + N：对选中句子运行语流预期检验。
• Cmd/Ctrl + Alt + Shift + Y：范文检索改写。

API 配置

切换 provider/模型最快的方式：命令面板执行 「Scholar: 切换 LLM Provider…」（一次同时设定 provider + model）。

各 provider 默认 baseUrl + 推荐模型：

默认每家只启用最新旗舰大模型（如需 flash / mini 等，用 writingAgent.api.model 手填覆盖）：

• Qwen Token Plan — https://token-plan.cn-beijing.maas.aliyuncs.com/apps/anthropic · qwen3.7-plus（可切 qwen3.7-max / qwen3.6-flash）
• DeepSeek (按量计费) — https://api.deepseek.com/anthropic · deepseek-v4-pro
• 小米 MiMo Token Plan — https://token-plan-cn.xiaomimimo.com/anthropic · mimo-v2.5-pro（订阅后控制台发放专属 Base URL；模型 ID 加 [1m] 后缀启用 1M 上下文）
• Gemini (按量计费) — https://generativelanguage.googleapis.com/v1beta/openai · gemini-3.1-pro-preview（默认）/ gemini-3.5-flash（两者均可在 provider 选择器直接切换；密钥在 https://aistudio.google.com/apikey）

需要调用 LLM 的功能包括 Prompt Studio、选区改写、修辞动作识别、语域断裂检测和语流预期检验。

Embedding 配置（Style-RAG 向量库）

向量索引使用独立的 embedding provider；聊天用的 MiMo Token Plan 与 DeepSeek 按量端点都不提供 embedding，需走 Gemini 或阿里云百炼 Qwen Embedding。最快配置方式：命令面板执行 「Scholar: 切换 Embedding Provider…」。

各 embedding provider 默认 baseUrl + 推荐模型：

• 阿里云百炼 Qwen Embedding — https://dashscope.aliyuncs.com/compatible-mode/v1 · text-embedding-v4（默认 1024 维，最长 8192 tokens）/ text-embedding-v3
• Gemini Embedding — https://generativelanguage.googleapis.com/v1beta · gemini-embedding-001 / text-embedding-004

验证与打包

npm run build
npm test
node test/test-basic.js
npm run test:e2e
npm run package:vsix

构建链路说明：

• npm run compile：运行 TypeScript 编译，输出 out/，用于类型检查和 smoke test。
• npm run bundle：用 esbuild 将 VS Code 扩展入口打包为 dist/extension.js。
• npm run build：先 compile，再 bundle，也是调试和发布前的默认构建命令。
• npm run test:e2e：用本机 VS Code 运行 Extension Host smoke，验证扩展能真实激活并注册核心命令。
• npm run package:vsix：需要 Node.js 20+，运行 pinned 本地 @vscode/vsce 与 vscode:prepublish，生成只包含 bundle、资源文件和 Python sidecar 的 VSIX。

VSIX 产物路径：

dist/scholar-writing-assistant-<version>.vsix

发布包边界：

• 包含：dist/extension.js、resources/、python/、readme.md、LICENSE.txt、changelog.md、package.json。
• 不包含：src/、out/、test/、node_modules/、.vscode/、本地脚本和旧调试文件。

项目结构

• src/core/formatEngine/：中文排版、引号、引注。
• src/core/promptStudio/：学术分析模板。
• src/core/skillDispatcher/：本地技能导入与 prompt 生成。
• src/core/flowEngine/：语域断裂与语流预期检验。
• src/providers/：VS Code 命令、TreeView、webview、diagnostics。
• resources/：webview 静态资源。
• test/：Vitest 单元测试和 smoke test。

许可证

MIT