计算机编程技巧与心得

Andrea Novel Helper - 专为小说创作者打造的 VS Code 写作增强扩展

Mon, 24 Nov 2025 00:00:00 GMT

官网: https://anh.sirrus.cc/ | 文档: https://blog.sirrus.cc > 最新版本: 0.4.35 (2025-11-21) | VS Code Marketplace: Andrea Novel Helper

Andrea Novel Helper - 专为小说创作者打造的 VS Code 写作增强扩展

Andrea Novel Helper（小说助手）是一个围绕"设定集/资料集"组织写作资产的 VS Code 小说写作增强扩展。它将传统的写作工具与现代编辑器技术完美结合，为小说创作者提供了一个功能强大、高度可定制的一站式写作环境。

✒️ 核心写作体验

智能统计与分析

小说助手提供全面的写作统计功能，帮助创作者更好地了解自己的写作状态：

实时字数统计：支持 CJK 字符与英文单词统计，提供多种统计标准（含标点/不含标点/词计）
写作速度监测：实时显示 CPM (每分钟字符数) 或 CPH (每小时字符数)
统计仪表板：可视化展示今日与历史写作时长、字数、平均速度及活跃度趋势
状态栏自定义：支持详细、半精简、精简三种显示模式

智能排版与辅助

为了让创作者专注于内容创作，小说助手提供了多项智能排版功能：

智慧回车：智能处理段落换行，自动调整格式
智慧括号：成对符号自动补全与快速跳出
自动空行：自动补充段间空行，保持版面整洁
版式设置：自定义段首/段尾标点规则，适应不同写作风格
错别字和语法检测：内置错别字和语法错误统计与识别功能
LLM 智能校对：基于大语言模型的错别字检测、语法修正和文本润色功能，提供专业的写作质量保障

快捷设置面板

通过命令 andrea.quickSettings 或者状态栏按钮，可以快速唤起聚合菜单，无需深入 VS Code 设置即可调整常用写作选项：

排版与外观：快速切换自动换行、首行缩进、段间空行、小地图及滚轮缩放
字体管理：提供图形化的编辑器字体家族管理工具
智能辅助：一键启停智慧回车、智慧括号、智能分组锁
统计配置：调整字数统计单位、状态栏模式及里程碑提醒
规则管理：图形化管理 .wcignore 忽略规则

🌍 设定集与世界观构建

统一对象模型 (Unified Object Model)

小说助手采用创新的统一对象模型来管理所有设定元素。无论是人物、敏感词、专有名词还是正则规则，本质上都是具有不同 type 属性的角色对象。

通用特性

全能别名支持：所有对象均支持定义别名 (Aliases)，在补全、高亮、引用查找时会自动识别主名与所有别名，并支持统一替换
代码级导航体验：
- 跳转到定义 (Go to Definition)：像查看代码定义一样，一键跳转到角色/词汇的源文件定义处
- 查看引用 (Find All References)：查找该角色在所有章节中的出现位置，支持列表跳转
智能补全与高亮：所有类型的对象均支持自动补全与文中高亮显示
可视化编辑：提供统一的图形化卡片编辑器
引用分析：支持引用索引、热力图与气泡图，分析对象在文档中的分布

多格式资源管理

小说助手通过"包"（Package）概念统一管理四大主资源类型：

资源	典型文件	支持格式	说明
角色	`character-gallery.json5` / `.md` / `.txt`	JSON5 / Markdown / TXT	角色设定、别名、颜色、类型、扩展字段
敏感词	`sensitive-words.json5` / `.md` / `.txt`	JSON5 / Markdown / TXT	内容安全或需要标识的词汇集合
词汇	`vocabulary.json5` / `.md` / `.txt`	JSON5 / Markdown / TXT	世界观专有名词、术语表
正则规则	`regex-patterns.json5`	JSON5	自定义正则高亮/着色规则

包结构建议

推荐的组织结构：

novel-helper/
  main/                         # 主设定包（集中核心/跨包共享设定）
    character-gallery.json5     # 主角色集合（结构化）
    world_roles.md              # 追加角色章节 (Markdown，多角色/字段)
    sensitive-words.json5       # 敏感词
    vocabulary.json5            # 词汇
    regex-patterns.json5        # 正则规则
  faction-a/                    # 阵营 / 派系 A（局部角色或补充）
    character-gallery.json5
  faction-b/                    # 阵营 / 派系 B
    character-gallery.json5

📂 项目与文件管理

写作资源管理器

替代原生资源管理器，提供专注的写作视图：

专注视图：仅显示写作相关文件，避免干扰
灵活排序：支持手动拖拽排序（生成稀疏索引）或自动排序
目录聚合：自动聚合计算目录下的总字数
文件追踪：基于分片数据库的高性能文件追踪系统

云端同步 (WebDAV)

支持多账户 WebDAV 同步，确保写作进度安全备份：

多账户支持：配置多个 WebDAV 账户
实时同步：状态栏实时显示同步进度与状态
可视化管理：独立的 WebDAV 文件树视图与同步控制面板
冲突处理：智能处理本地与云端文件冲突

项目配置

初始化向导：一键生成项目结构、配置文件及忽略规则（.gitignore, .wcignore）
项目配置文件：通过 anhproject.md 管理项目元信息

🤖 自动化与扩展

用户脚本与 MCP 运行时

用户脚本系统：内置脚本运行器，允许用户编写自定义脚本扩展功能
MCP (Model Context Protocol) 支持：
- 集成 MCP 运行时，可调用外部工具与服务
- 自动发布场景：结合浏览器自动化工具，可编写脚本实现章节自动发布到小说网站
- 侧边栏一键运行管理

Typst 排版导出

高质量输出：基于 Typst 引擎导出 PDF、图片（PNG/SVG）
模板系统：内置多种模板（如论坛体），支持自定义模板开发
智能转换：Markdown 语法自动转换为 Typst 格式，支持图片路径自动处理

📊 实时辅助功能

阅读与预览

侧边栏预览：支持 Markdown 和 TXT 格式的实时预览
个性化阅读：支持自定义预览界面的主题与字体设置
大纲视图：支持懒加载大纲生成，提供双重大纲辅助写作

批注系统

独立侧边栏：专用的批注管理视图，支持归总、跳转与快速处理
伏笔管理：便于记录和追踪剧情伏笔

LLM 智能辅助（润色和生成部分位于 ANH CHAT 附件中不随小说助手本体提供或者您可以使用任何 Code Agent 完成这部分工作）

集成大语言模型能力，为创作者提供智能化的写作辅助：

智能校对与润色：
- 错别字检测：基于 LLM 的智能错别字识别，比传统规则检测更准确（本体集成）
- 语法修正：自动检测语法错误并提供修改建议（本体集成）
- 文本润色：优化表达方式，提升文字质量和可读性（附加组件 Anh Chat 提供）
- 风格建议：根据小说类型提供风格化的修改建议（附加组件 Anh Chat 提供）
多语言翻译：基于大模型的快速翻译工具，支持替换选区或复制结果，帮助创作者进行多语言创作（本体集成）
内容生成辅助：（附加组件 Anh Chat 提供）
- 情节建议：根据当前内容提供情节发展建议
- 角色对话生成：生成符合角色性格的对话内容
- 场景描写：提供场景描写的参考和建议

🎯 核心优势

1. 统一的工作环境

在熟悉的 VS Code 环境中完成所有写作工作，无需切换多个应用程序。

2. 智能化的辅助功能

从自动补全到错误检测，从统计分析到格式化，特别是集成的 LLM 智能校对和润色功能，全方位提升写作效率和质量。

3. 强大的数据管理

"统一对象模型"让角色、词汇、敏感词等所有设定都能得到统一管理和高效检索。

4. 高度可定制性

支持用户脚本、自定义模板、个性化设置等，满足不同创作者的特殊需求。

5. 现代化的技术栈

基于 VS Code 扩展平台，享受现代化的编辑器技术和生态系统。

🆚 与传统写作软件对比

小说助手坚持"稿件可见宣言"，与传统闭源写作软件相比具有显著优势：

特性维度	Andrea Novel Helper (开源)	传统闭源写作软件	优势说明
数据存储	Markdown/TXT/JSON5 (开放格式)	私有数据库/封闭格式	文件可被记事本直接打开，完全掌控数据
备份与迁移	Git/压缩包/U 盘/网盘 (自由选择)	官方迁移工具 (依赖厂商) 或者根本不提供	无需特定工具，备份随心所欲
版本控制	原生支持 Git，完整的版本历史	有限版本控制或无	专业级的版本管理，支持分支和合并
协作能力	Git 协作，透明审阅，可 diff	专有协作系统 (锁定生态)	开放的协作流程，不限工具和平台
IDE 级辅助	智能补全、语法高亮、跳转定义、引用分析	基础编辑功能	享受现代 IDE 的强大辅助功能
定制扩展	用户脚本、MCP、VS Code 生态	有限插件或无	无限扩展可能性，社区驱动
云同步	WebDAV/Git (自由选择服务商)	官方云服务 (锁定)	可选择任何兼容的云存储服务
数据安全	数据完全本地，可选择在线服务	数据存储在厂商服务器	完全掌控数据流向和隐私安全
成本费用	完全免费 (开源 MPL-2.0)	订阅制或一次性购买	零成本使用，无功能限制
技术支持	社区支持 + 开源透明	官方支持 (依赖厂商响应)	透明的源码，社区共同维护
平台锁定	跨平台 (VS Code 支持)	可能限制特定平台	任何支持 VS Code 的平台都能使用

稿件可见宣言

我们主张：稿件一定要可读、可备份、可协作、可迁移；文件一定要归创作者所有，不做技术人质。

稿件一定要能被记事本直接打开与编辑
文件一定要用普通格式保存（Markdown / TXT / JSON5）
备份一定要随手可做（Git / 压缩包 / U 盘 / 网盘）
协作一定要透明（可 diff / 可审阅 / 可回滚）
迁移一定要不设门槛（换工具不做"迁移仪式"）

小说助手坚持开放文件与透明模型，拒绝私有封闭格式，让创作真正掌握在创作者手中。

🚀 快速开始

安装扩展

在 VS Code 扩展市场中搜索 "Novel Helper"
或访问 VS Code Marketplace
点击安装，或选择安装合集获得完整功能

创建新项目

打开命令面板（Ctrl+Shift+P）
搜索并执行 "Andrea Novel Helper: Initialize Project"
（前两步若您打开新空白工作区可自动弹出向导）
按照向导提示配置项目信息
自动生成项目结构和配置文件

基本使用流程

创建角色库：在包管理器中创建 character-gallery.json5 或 .md 文件
添加角色设定：使用可视化编辑器或直接编写 Markdown/JSON5
开始写作：在章节文件中享受智能补全和高亮功能
查看统计：通过统计面板监控写作进度
导出作品：使用 Typst 或者纯文本渲染器导出功能生成高质量文档

📈 发展历程

小说助手持续快速发展，近期重要更新包括：

v0.4.35 (2025-11-21)：支持快捷翻译和并行缓存校验
大幅重构异步加载与性能管线：提升整体性能和响应速度
独立组件发布：Anh Chat (小说助手聊天组件) 独立发布，提供生成式 AI 功能

💬 社区与支持

GitHub Issues：提交问题报告和功能请求
QQ 群：小说助手用户反馈和交流
Discord：加入社区讨论
GitHub Discussions：功能建议和经验分享

📄 许可证

本项目采用 MPL-2.0 许可证，允许自由使用、修改和分发。

Andrea Novel Helper 不仅仅是一个写作工具，它是现代技术与创作艺术的完美结合，为每一位小说创作者提供强大的创作支持。无论你是初出茅庐的新人，还是经验丰富的老手，都能在这里找到适合自己的创作方式。

立即体验，开启你的高效创作之旅！ ✨

一个Typst模板

Sun, 21 Sep 2025 00:00:00 GMT

模板下载

查看 Typst 模板源文件：查看 novel1.typ

点击下载模板源文件：<a href="/downloads/novel1.typ" download>下载 novel1.typ</a>

当您二次分享时希望您遵守模板的许可证使用无需遵守 MIT 许可证

模板预览

模板源码

#let theme = (
  text-font: "Noto Sans SC",
  heading-font: "Noto Sans SC",
  text-size: 20pt,
  category-size: 50pt,
  title-size: 30pt,
  separator-size: 50pt,
  sub-size: 12pt,
  color: rgb("#111"),
  gray: rgb("#6b7280"),
  line-height: 1,
  indent: 2em,
  para-spacing: 2em,
)

#let zh-paragraph() = {
  set par(justify: true, first-line-indent: theme.indent,
          leading: theme.line-height * 1em, spacing: theme.para-spacing)
  set text(lang: "zh", font: theme.text-font, size: theme.text-size, fill: theme.color)
}

#let article-card(
  title, body,
  category: none, subtitle: none,
  category-size: none, title-size: none, separator-size: none, body-size: none
) = block(
  // 用 block 而不是 box：block 是可分页的
  fill: white,
  inset: 22pt,      // 内边距
  radius: 8pt,      // 圆角
  stroke: none,
  width: 440pt,     // 版心宽度（可调）
  breakable: true,  // 显式允许跨页（缺省也是可分页）
)[
  // 标题
  #set text(font: theme.heading-font, weight: "bold")
  #if (category != none) [
    #text(size: if category-size != none { category-size } else { theme.category-size })[#category]
    #text(size: if separator-size != none { separator-size } else { theme.separator-size })[ ｜]
  ]
  #text(size: if title-size != none { title-size } else { theme.title-size })[#title]

  // 副标题（可选）
  #if (subtitle != none) [
    #v(6pt)
    #set text(font: theme.heading-font, size: theme.sub-size, fill: theme.gray)
    #subtitle
  ]

  #v(10pt)

  // 正文
  #set par(justify: true, first-line-indent: theme.indent,
           leading: theme.line-height * 1em, spacing: theme.para-spacing)
  #set text(lang: "zh", font: theme.text-font,
            size: if body-size != none { body-size } else { theme.text-size },
            fill: theme.color)
  #body
]


// 使用示例
#article-card(
  category: "模板",
  // subtitle: [可选的副标题写这里，注释去掉即可。],
  "这份 Typst 文章模板怎么用（小白向）",
  [
本模板用于排一个白底内容卡片：上方是“分类｜标题”，下面是正文。容器可自动分页，所以写长文也不用担心被截断。

一、写正文
把每个自然段直接放在这里，每两个段落之间留一个真正的空行即可。若从网页粘贴导致空行里混入全角空格，看起来空但其实不空，段落就不会分开；遇到这种情况，手动敲一个空行，或把光标放在空行里按删除直到行首没有任何字符。

二、改样式
想要无衬线风格（黑体），已默认使用 Noto Sans SC；若你电脑没有该字体，可以在上面的 theme 里把 text-font / heading-font 改成系统里存在的字体，例如 Source Han Sans SC 或 Microsoft YaHei。

三、改字号与间距
段内行距由 line-height 控制（数值越大越疏），段间距由 para-spacing 控制（例如 2em）。你也可以在调用 article-card 时单独覆盖 body-size（正文字号）。

四、改标题行
分类、标题和分隔竖线的字号分别受 category-size、title-size、separator-size 控制；留空就用 theme 里的默认值。不要分类时，把 category 参数去掉即可。

五、版心宽度
内容卡片的宽度是 440pt，可在 article-card 的 width 参数上调整；页面边距想更大，可在外部用 set page(margin: ...) 调整。

开始写作吧：把这段说明删掉，换成你的正文即可。
  ],

)

小说助手安装和基础功能使用说明

Mon, 08 Sep 2025 00:00:00 GMT

小说助手官网： https://anh.sirrus.cc

安装

便携安装（对于普通用户）

下载安装包

选择是

选择安装语言

设置用户名密码

最后会自动在桌面上创建图标根据提示启动两次就自动设置为中文

第一次启动

第二次启动

显示为中文即为便携安装完成

全量安装（对于专业用户）

第一步下载 Git 和编辑器

Git 官网：https://git-scm.com/downloads
加速下载（选普通下载）：https://pc.qq.com/detail/13/detail_22693.html
选择是
Next
根据情况选择
默认编辑器不会用 vim 可以用别的（推荐 vscode）
（如果选择 vscode）
Next
可选第二个或者第三个
Next
Next
Next
这个随便选
Next
Next
点击安装即可
Git 安装结束

安装 VSCode
1. 官网：https://code.visualstudio.com/
2. 我同意下一步
3. 建议全勾上
5. 安装
7. 安装完成（运行）

安装小说助手

点击扩展按钮搜索 Andrea Novel Editor
安装合集
Ctrl Shift P
配置语言为中文
配置图标主题
个人建议使用 Material（当然主题图标主题美化你可以自己在插件商店下载）

使用

新建书籍项目

使用打开文件夹打开一个空白文件夹（这会是一本书的存储地点）

我们打开一个新建文件夹

点击信任

第一次使用先配置 git 信息

输入用户名（任意（最好是英文））

邮箱（最好真的能用这个用来绑定云存储）

回车即可

选择全局

会看到提示运行向导来创建小说项目

选择初始化仓库

选择创建示例结构

需要云同步写作进度可以纳入但是没必要

根据推荐来选择即可

是创建初始提交

是执行

关闭即可初始化小说项目完成

写作资源管理器（全文字数统计）

新建文件夹新建新的一卷

右键第一卷可以选择章节排序方式（默认使用名称排序）

如

第一章

第二章

或者

1 xxx

2 xxx

点击切换手动排序可以切换成手动排序（类似传统码字软件）

点击新建文章选择章节格式（markdown（更强大）或者 txt）

输入文件名

手动排序模式下前面的数字是第几章

所有模式下后面的数字是字数

打开文件的情况下点击大纲按钮打开大纲

会自动创建文件夹和文件的大纲

所有的窗体都是一样的可以拖动

（编辑的时候记得保存！或者你开自动保存也行）

可以自定义工作区的形状

敏感词识别

点击警告按钮可以查看文章有什么问题

选择问题面板查看问题

点击问题可以转跳到问题出处

智能补全和提示

设置完设定集后输入时可以根据设定集补全

有设定集的内容可以高亮着色

具体描述和着色参照设定集

如果角色写了别名可以替换为别名

按住 Ctrl+鼠标左键可以转跳到设定集

当前文章角色的功能类似

设定集管理器

点击小说助手按钮打开设定集管理器

右键任意目录可以创建设定集（子目录/包）和设定集文件

以创建角色库为例子

会询问文件名

选择格式

Md 和 json5 功能比较强大

但是 md 更可读

以 md 为例

md 文件中选中文本可以快速指定格式

点击 MPE 预览按键打开预览

修改完设定集后会自动加载

本着万物皆角色的理念设定集可以描述任何东西

甚至支持插入图片

json5 格式的设定集

你可以把鼠标放在色块上改变颜色（记得保存）

每天写完记得保存进度这样你能出问题了恢复到上个版本！

写作统计

点击下面的字数统计可以打开码字统计面板

这是内容

导出预览和读稿器

点击 OpenPreview 打开预览和读稿器（测试版）

点击播放即可读稿

界面美化

百度查询 vscode 美化教程

VS Code Git集成与各大平台私有仓库使用指南（小说助手专用）

Mon, 08 Sep 2025 00:00:00 GMT

小说助手官网： https://anh.sirrus.cc

VS Code Git 集成使用指南（图解）

适用版本：VS Code 桌面版与 Web（大部分功能相同）。默认已安装 Git（建议 >= 2.0.0）。

🎯 特别说明：小说助手用户必读

什么是版本管理？

版本管理就像是您小说的"时光机"，可以：

保存写作进度：每次修改都会被记录，不会丢失
回退到任意版本：写错了可以回到之前的正确版本
比较修改内容：清楚看到每次修改了什么
多人协作：团队成员可以同时编辑，互不干扰

为什么小说助手需要 Git？

小说助手已经为您创建了本地仓库，但要实现：

✅ 云端备份：防止本地文件丢失
✅ 多设备同步：在家和公司都能继续写作
✅ 版本回溯：不满意的修改可以撤销
✅ 协作写作：多人共同创作同一部小说

📋 小说助手专用 Git 工作流程

步骤 1：查看更改

打开小说助手项目后，在 VS Code 中按 Ctrl+Shift+G 进入源代码管理视图：

您会看到：

CHANGES：您修改的文件列表
STAGED CHANGES：准备提交的文件
MESSAGE：提交信息的输入框

步骤 2：暂存更改

在 CHANGES 中点击文件旁的 + 按钮，将修改添加到暂存区：

💡 小贴士：绿色部分是新增内容，红色部分是删除内容

步骤 3：提交更改

在 MESSAGE 框中输入提交信息（如："更新第 5 章开头"）
点击 ✅ 提交按钮，或按 Ctrl+Enter

步骤 4：推送到云端

点击右上角的同步按钮 🔄
选择 Push 将本地提交上传到 GitHub
选择 Pull 从 GitHub 下载最新更新

🔄 小说助手用户日常同步操作

写作前：先执行 Pull 确保获取最新版本
写作中：每完成一个段落或章节就提交一次
写作后：执行 Push 保存到云端
多设备：在另一台设备上先 Pull 获取最新内容

这样您的小说永远不会丢失，还可以随时回到任何一个写作阶段！

🛠️ 通用 Git 操作指南

安装 Git 并确保终端能执行 git --version。
VS Code 通过活动栏左侧的“源代码管理”图标进入 Git 视图（快捷键：Windows/Linux：Ctrl+Shift+G；macOS：⌃⇧G）。

2) 打开或克隆仓库

打开项目或克隆

首次打开时，源代码管理视图会提供“Open Folder / Clone Repository”按钮：

Clone Repository：输入远程地址（例如 GitHub）即可克隆：

初始化本地仓库

若当前文件夹不是 Git 仓库，点击 Initialize Repository 初始化；也可一键 Publish to GitHub：

3. 暂存（Stage）与提交（Commit）

在“源代码管理”视图中会分为 CHANGES / STAGED CHANGES / MERGE CHANGES 三块。

选择文件可在内置 Diff 编辑器 中查看变更；右侧编辑器仍可直接修改未暂存内容。
在 Diff 中间栏可以逐块暂存/回退（Stage/Revert hunk）。

更多提交相关操作可在右上角 …（Views and More Actions） 菜单找到：

小贴士：你也可以使用 Copilot 生成提交信息（在提交输入框的按钮处），或在编辑器中查看 blame 信息（可通过设置模板自定义显示）。

4. 分支与标签（Branches & Tags）

通过命令面板：Git: Create Branch、Git: Checkout to… 创建/切换分支或检出标签；也可从状态栏分支指示器切换。

5. 源代码控制图（Graph）

配置了远端后，可在 Graph 里看到领先/落后、提交流向等；右键提交可执行 checkout / cherry-pick 等操作，点文件可直接打开该提交的 diff。

6. 查看历史：时间线（Timeline）

Timeline 视图（资源管理器底部）统一展示文件的时间序列事件（如 Git 提交）。选择某个提交即可打开当次变更的 diff。

7. VS Code 作为 Git 的编辑器/差异/合并工具

把 VS Code 配置为 Git 的外部工具（命令行执行）：

# 作为 Git 的编辑器（等待 VS Code 关闭）
git config --global core.editor "code --wait"

# 作为 difftool / mergetool
git config --global diff.tool default-difftool
git config --global difftool.default-difftool.cmd "code --wait --diff $LOCAL $REMOTE"

git config --global merge.tool code
git config --global mergetool.code.cmd "code --wait --merge $REMOTE $LOCAL $BASE $MERGED"

需要确保命令行可运行 code --help（macOS 可在命令面板执行 Shell Command: Install 'Code' command in PATH）。

8. 多仓库与其他 SCM

VS Code 可同时管理多个提供方与多个仓库：

在 … → Views 勾选 Source Control Repositories 显示多仓库面板：
通过扩展安装其他 SCM 提供方（如 SVN、Hg）：

9. 常用操作速查

打开源代码管理视图：Ctrl+Shift+G / ⌃⇧G（macOS）
命令面板：Ctrl+Shift+P / ⇧⌘P（macOS） → 输入 Git: ...
暂存/取消暂存：在文件/区块处点击 + / -
提交：在顶部输入框填写信息，Ctrl+Enter 提交
比较任意两文件：资源管理器中 右键文件 A → Select for Compare，再在文件 B 上 Compare with Selected

🌐 各大代码托管平台私有仓库使用攻略

适用平台：GitHub / GitLab.com / Bitbucket Cloud / Azure DevOps Repos / AWS CodeCommit / Gitee / Codeberg 重点覆盖：创建私有仓库、邀请协作者与权限、可见性/公开设置、CI/CD 在私有仓库的配额与注意事项。

📊 平台总览对比

平台	是否支持免费私有仓库	协作/成员（免费档）	可见性/公开设置	CI/CD（私有仓库）	中国大陆可访问性	备注
GitHub	✅ 支持	个人/组织免费计划可用	仓库可设为 Private / Public（企业还有 Internal）	私有库享有每月2,000 Actions 分钟（Free 账号；超出按量计费）	⚠️ 偶尔不稳定	私有库 Actions 配额与套餐关联。GitHub Docs
GitLab.com	✅ 支持	Free 组最多 5 人	项目可设 Private / Internal / Public	Free 组合计 400 计算分钟/月（可自带 Runner 不计限）	⚠️ 需要加速服务	公共/开源与付费档配额更高；可加购分钟。about.gitlab.com
Bitbucket Cloud	✅ 支持	Free 至多 5 用户	仓库一键勾选 "Private"	Pipelines 随套餐变动	⚠️ 偶尔不稳定	Free 限 5 用户但无限私有仓库。atlassian.com, Atlassian Support
Azure DevOps Repos	✅ 支持	（随 Azure DevOps 用户数）	项目/组织层可切换 Public/Private	Azure Pipelines 随订阅配额	✅ 访问顺畅	官方标注"无限量私有 Git 仓库"。Azure, [Microsoft Learn](https://learn.microsoft.com/en-us/azure/devops/repos/get-started/
AWS CodeCommit	✅ 支持	按 IAM 身份授权	默认私有，通过 IAM 控制访问	与 CodeBuild/CodePipeline 集成	⚠️ 需要加速服务	官方定义为"托管私有Git 仓库"。docs.aws.amazon.com
Gitee	✅ 支持	个人/组织可创建私有仓库	新建时选择"是否开源：公开/私有"	Gitee/第三方 CI 可用	✅ 访问顺畅	帮助中心有"创建仓库/可见性"指引。Gitee
Codeberg	⚠️ 有限支持	面向 FOSS 贡献者	可建私有库	自带 CI（Woodpecker/Forgejo Actions）	❌ 访问受限	私有内容建议 ≤ 100MB（以公益使命为准）。docs.codeberg.org

GitHub（私有仓库）

创建私有仓库

右上角 + → New repository → 选择 Visibility: Private → Create repository

修改可见性 仓库 Settings → Danger Zone → Change repository visibility，可在 Private / Public 间切换

邀请协作与权限 在仓库/组织下，添加协作者或通过团队授予权限

私有库 CI/CD（GitHub Actions）

公共库与自托管 Runner 免费
私有库按套餐享有每月分钟数与存储配额（Free：2000 分钟/500MB）
超额按量付费

GitLab.com（私有项目）

私有可见性 新建项目时选择 Private，或在项目设置切换 Private / Internal / Public

成员与权限 项目/组可邀请成员并配置角色；Free 组上限 5 用户

私有库 CI/CD（GitLab CI/CD）

Free：每顶级组每月400 计算分钟（共享 Runner）
可自带 Runner不占限额；可加购分钟或升级

Bitbucket Cloud（私有仓库）

创建私有库 Create → Repository，在仓库设置处勾选 This is a private repository

协作与权限 可对个人用户或用户组授予 Admin/Write/Read 等角色

计费/用户数 Free 方案最多 5 用户，但无限私有仓库

Azure DevOps Repos（私有 Git 仓库）

特性与创建 Azure Repos 提供无限量私有 Git 仓库；在项目内创建 Repo 即可

公开/私有 项目层支持 Public/Private；可在组织设置中调整可见性策略

AWS CodeCommit（企业级私有）

定位与访问控制 CodeCommit 官方定义为托管私有 Git 仓库，访问由 IAM 策略控制，默认私有

典型流程

通过控制台创建仓库
为开发者配置 IAM（或 SSO）
选择 HTTPS Git 凭据或 SSH 访问

Gitee（码云）

创建与可见性 右上角 + → 新建仓库，在新建页选择"是否开源：公开/私有"

权限与开源切换 企业工作台下可在"功能设置 → 可见性"里切换，并有角色/权限配置

Codeberg（社区公益托管）

私有仓库政策 以推动 FOSS 为使命：私有仓库可用但非主要用例；对活跃 FOSS 贡献者允许 ~100MB 私有内容

🔧 实操速查（通用 Git + 权限）

本地与远端连接

# 初始化并首次推送
git init
git add .
git commit -m "init"
git branch -M main
git remote add origin <你的私有仓库HTTPS或SSH地址>
git push -u origin main

常见权限/私有要点

最小权限原则：仅授予需要的读/写/管理员
保护主分支：启用保护规则（强制 PR、评审、状态检查）
密钥与凭据：使用 SSH Key 或平台令牌，CI 机密放入平台 Secrets/Variables
CI/CD 配额：私有库常与套餐挂钩（分钟/存储/并发），超额需加购或自托管 Runner

💡 选型建议

个人/小团队：

想要生态丰富与招聘友好 → GitHub
更强 DevSecOps 一体化 → GitLab.com
与 Atlassian（Jira/Trello）联动 → Bitbucket

企业/合规：

Azure 体系 → Azure DevOps Repos
AWS 体系与内网/IAM 严管 → CodeCommit

中国大陆网络体验： Gitee 作为镜像/私有托管备选

公益/开源情怀且仅少量私密需求 → Codeberg

📚 参考与延伸

VS Code Git 集成

各大代码托管平台

本文主要依据：VS Code 官方文档《Using Git source control in VS Code》，涵盖了 Git ≥ 2.0.0 的要求、Source Control 视图、Clone/Initialize、Diff/Stage/Revert、Branches/Tags、Graph、Timeline 等功能，以及 code --wait 作为编辑器/差异/合并工具的配置方法。

配图来源：所有插图均取自 VS Code 官方文档对应资源，包括 overview、first-run、clone、set-repo-url、initialize、branches、diff、graph、timeline、SCM 视图与扩展分类等页面。

小说助手 0.3.25 版本发布新功能介绍和教程

Sun, 07 Sep 2025 00:00:00 GMT

小说助手官网： https://anh.sirrus.cc

小说助手 0.3.25 版本发布新功能介绍和教程

[0.3.25] - 2025-09-07

✨ 新增

新增展开状态持久化功能：所有角色视图、当前文章角色视图（侧边栏和 Explorer）、包管理器视图现在都会记住用户的展开/折叠状态
新增跨文档展开状态继承：切换到新文档时，如果新文档尚无展开记录，可继承上个文档的展开集合（仅对共有的节点生效）
新增设置开关 AndreaNovelHelper.docRoles.inheritExpandedFromPrevious：控制是否启用跨文档展开状态继承（默认开启）
新增角色展开显示功能：角色节点支持展开显示详细信息，包括名称、类型、颜色等字段
优化角色显示：支持角色自带 SVG 图标、角色名彩色方块标记、颜色字段可视化显示
新增角色详情键图标映射：基于 JSON 配置为不同类型的角色字段显示对应的 VS Code 内置图标
写作资源管理器现在支持显示参考资料（如图片、PDF 等不计入字数统计的文件）
支持基于自定义分类的角色显示，可以按类型或归属进行更灵活的分组

🐛 修复

修复角色视图展开状态在重启 VS Code 后丢失的问题
修复切换文档时布局被重置的问题
略微优化了 Decorations 性能，减少大文件打开时的阻塞

🖋️ 更改

改进角色树视图的 ID 计算稳定性，确保展开状态正确持久化
优化展开状态的存储机制，使用 workspaceState 进行跨会话持久化

新功能预览

自定义分组

展开角色

教程部分

图文教程-创建自定义分组

打开角色显示设置选项卡点击管理自定义分组规则进入自定义分组规则页面

选择添加规则后输入分组名称选择匹配的类型（匹配归属还是类型）输入匹配的条件(分隔符是英文逗号) 创建完成页面手动刷新后即可看到新分组（这个版本暂未实现自动刷新）创建完成后即可看到新的分组

展开角色的描述多行文本换行的设置

受限于正常手段我们无法完全控制 TreeView 的 DOM，ANH 对于角色细节的描述形式是通过手动拆分为多行文本实现的，默认这个阈值是 20 字符。但是如果你使用了不同的侧边栏宽度你会需要手动设置这个参数。

不正确的宽度设置

宽度过窄，一行显示不完全宽度正常，显示正常宽度过宽，浪费空间

如何设置显示宽度

进入角色设置面板（当前文章角色设置步骤相同）选择详情折行行数设置为一个合适的数值设置完成后手动刷新查看结果（全部角色这边请来回切换是否跟随当前文章角色的设置来刷新，当前文章角色应该能自动刷新）

目前版本设置完宽度后需要手动刷新才能应用将会在下个版本修正

角色详情展开与颜色图标

角色详情展开

角色节点支持展开显示详细信息，便于快速查看和编辑角色属性：

展开机制：点击角色节点旁边的展开图标（▶），可查看该角色的所有属性（如名称、类型、颜色、描述等）。
属性排序：属性按键名排序，name 字段置顶，其余按字母顺序排列。
值显示：长文本自动截断显示，完整内容在悬停提示中查看；支持换行和折行显示，避免单行过长。
配置开关：通过 AndreaNovelHelper.roles.details.enableRoleExpansion 控制是否允许角色展开（默认开启）。

根据角色颜色设置图标

为角色提供视觉化的颜色标识，提升界面辨识度：

颜色图标：如果角色对象包含 color、colour 或 颜色 字段，系统会在角色名称前显示一个对应颜色的方块图标。
图标优先级：优先使用角色自带的 SVG 图标（如果启用 useRoleSvgIfPresent）；否则使用颜色方块；最后回退到文件类型图标。
配置开关：通过 AndreaNovelHelper.docRoles.display.colorizeRoleName 或 AndreaNovelHelper.allRoles.display.colorizeRoleName 控制是否启用颜色标记（默认关闭）。
视觉效果：颜色方块为 14x14 像素的圆角矩形，支持透明度和边框，提供良好的视觉反馈。

这些功能增强了角色管理的交互体验，使角色列表更加直观和易于导航。配置开关允许用户根据需要启用或禁用这些特性。

Andrea Novel Helper 自定义分组规则原理

注意在此处设置和上面通过向导设置的结果是一样的这边仅作为配置文件结构详解

1. 背景与作用

自定义分组功能允许你脱离内置“类型 → 归属 → 角色”三级结构，按照自己的规则（类型、归属或正则）来对角色进行分组，便于阅读、编辑和管理。

2. 打开与作用域

下列配置可分别作用于两种视图：
1. allRoles（全部角色视图）
2. docRoles（当前文章角色视图，侧边栏 & Explorer）

配置路径（settings.json）示例：

"AndreaNovelHelper.docRoles.useCustomGroups": true,
"AndreaNovelHelper.docRoles.customGroups": [ /* 自定义分组列表 */ ],
"AndreaNovelHelper.allRoles.syncWithDocRoles": false,
"AndreaNovelHelper.allRoles.useCustomGroups": true,
"AndreaNovelHelper.allRoles.customGroups": [ /* … */ ]

3. 分组规则项字段

每个分组项是一个 JSON 对象，关键属性：

name：组名，会展示在树视图顶层
matchType: “type” | “affiliation” | “regex”
pattern:
- 当 matchType=type 或 affiliation 时，支持 glob 模式（*Important*）或逗号分隔列表
- 当 matchType=regex 时，必须是一个 JS 正则字面量（/^.*魔法.*$/）
flat (可选，不常用)：布尔，true 则该组下不再按“类型/归属”二级分组，直接平铺。一般不手动设置此字段，而是通过全局开关控制扁平化。
ignoreType / ignoreAffiliation (可选)：布尔，若开启则该视图全局忽略二级“类型/归属”分层，仅在显示层面生效

{
  "name": "战斗角色",
  "matchType": "type",
  "pattern": "战斗*,Boss"
  // 注意：一般不设置 flat，而是通过全局开关控制
},
{
  "name": "魔法势力",
  "matchType": "affiliation",
  "pattern": "魔法森林,天空学院"
},
{
  "name": "自定义关键词",
  "matchType": "regex",
  "pattern": "/^Reimu|Marisa$/"
}

4. 匹配与分组流程

匹配阶段（Match）
依照 matchType，用真实的角色 type、affiliation 或 regex 去筛选整个角色列表，不受全局的 ignoreType/ignoreAffiliation 开关影响，保证匹配准确。
分组阶段（Group）
- 按配置项的顺序创建顶层组
- 匹配到的角色按全局开关决定是否在同一组内直接平铺，或继续按二级维度（类型或归属）拆分
其他角色（Other）
将所有未命中的角色归入一个内置 “其他” 分组

5. 忽略开关的效果（推荐使用）

全局开关是控制扁平化的主要方式：

ignoreType=true：展示时不显示二级“类型”节点，所有角色直接平铺到所属顶层组。
ignoreAffiliation=true：展示时不显示二级“归属”节点；若一个分组的 matchType=affiliation，并开启忽略，则所有匹配角色也会直接平铺到该组下。
这两个开关不影响匹配，只控制展示层级。

推荐做法：一般不手动设置每个分组的 flat 字段，而是通过全局的 ignoreType 和 ignoreAffiliation 开关来统一控制所有分组的扁平化行为。这样更简洁且易于管理。

6. 同步与独立

当 allRoles.syncWithDocRoles=true，全部角色视图使用同一套 docRoles.customGroups 规则；
若需两者分别管理，设为 false 并分别配置。

7. 示例配置

// settings.json
"AndreaNovelHelper.allRoles.syncWithDocRoles": false,
"AndreaNovelHelper.allRoles.useCustomGroups": true,
"AndreaNovelHelper.allRoles.customGroups": [
  {
    "name": "主角阵营",
    "matchType": "affiliation",
    "pattern": "勇者公会,救世教会"
  },
  {
    "name": "反派",
    "matchType": "type",
    "pattern": "Boss,精英*"
  }
],
// 推荐：通过全局开关控制扁平化，而不是手动设置 flat
"AndreaNovelHelper.allRoles.ignoreType": false,
"AndreaNovelHelper.allRoles.ignoreAffiliation": true  // 所有分组都会扁平化，不显示归属二级节点

8. 注意事项

正则模式要写完整字面量，不能省略 /.../；
flat 字段可选且不常用；一般通过全局 ignoreType/ignoreAffiliation 开关来控制扁平化；
如果一个角色同时命中多个组，按配置项先后顺序归入第一个匹配组；
未在 customGroups 中定义的字段会自动进入“其他”组；
修改分组配置后，可通过命令面板 “配置：全部角色显示” 或 “配置：当前文章角色显示” 立即刷新视图。

小说助手 0.3.24 版本发布新功能介绍和教程

Sat, 06 Sep 2025 00:00:00 GMT

小说助手官网： https://anh.sirrus.cc

小说助手 0.3.24 版本发布新功能介绍和教程

🎉 版本 0.3.24 发布成功！

功能预览

📋 完成的工作

✅ 版本更新

版本号: 0.3.23 → 0.3.24
发布日期: 2025-09-06

✅ Git 提交

提交信息: feat: v0.3.24 - 新增wcignore快速设置和gitignore语法高亮，优化TimeStats性能
包含 15 个文件更改，1406 行新增，126 行删除

🆕 新版本特性

✨ 新增功能

wcignore 快速设置: 新增了 wcignore 文件的快速设置功能
gitignore 语法高亮: 新增了 gitignore 文件的语法高亮支持

🐛 修复和优化

TimeStats 性能优化: 略微优化了 TimeStats 的性能，减少大文件打开时的阻塞
异步计算改进: 改进了异步计算的错误处理机制

🔗 相关链接

新版本已经成功发布到市场，用户现在可以更新到最新版本 0.3.24 来体验这些新功能和性能优化！

许可证系统测试

Thu, 04 Sep 2025 00:00:00 GMT

许可证系统测试

这篇文章用于测试新的许可证系统功能。

使用预配置许可证

这段代码使用 MIT 许可证：

function hello() {
  console.log("Hello, World!");
}

这段代码使用 MPL 2.0 许可证：

interface User {
  id: number;
  name: string;
}

class UserService {
  getUser(id: number): User | null {
    // 实现获取用户逻辑
    return null;
  }
}

使用自定义许可证配置

这段代码使用自定义许可证：

def process_data(data):
    """处理数据的函数"""
    return data.strip().upper()

这段代码使用带徽章的许可证：

function calculateSum(numbers) {
  return numbers.reduce((sum, num) => sum + num, 0);
}

手动配置许可证

使用键值对格式配置自定义许可证：

def proprietary_algorithm():
    """这是一个专有算法"""
    return "secret sauce"

使用完整手动配置：

public class InternalTool {
    public static void main(String[] args) {
        System.out.println("Internal company tool");
    }
}

纯文本许可证

使用简单文本许可证：

.example {
  color: red;
  font-weight: bold;
}

复杂示例

使用 CC BY-NC 4.0 许可证的代码：

<template>
  <div class="license-demo">
    <h3>{{ title }}</h3>
    <p>{{ description }}</p>
  </div>
</template>

<script>
export default {
  name: "LicenseDemo",
  props: {
    title: String,
    description: String,
  },
};
</script>

<style scoped>
.license-demo {
  padding: 1rem;
  border: 1px solid #ccc;
  border-radius: 8px;
}
</style>

没有许可证的代码

这段代码没有指定许可证：

echo "这段代码没有许可证信息"
ls -la

在 VS Code 扩展里安全嵌入 Vue SPA

Wed, 03 Sep 2025 00:00:00 GMT

在 VS Code 扩展里安全嵌入 Vue SPA

这篇文章以“角色卡管理器”为例，演示如何把一个由 Vite 构建的 Vue 单页应用（SPA）无缝嵌入到 VS Code 扩展的 Webview 中，并系统性解决三大痛点：

静态资源路径：确保脚本、样式、图片、动态导入都能正确加载
CSP 限制：在安全的前提下允许必需的资源与请求
Webview ↔ 扩展通信：与扩展后端可靠地交换数据

项目结构建议

packages/
  webview/                  # Vue + Vite 前端工程
    dist/spa/               # 产物目录（被扩展引用）
src/
  extension/                # 扩展端代码
  media/                    # 运行时辅助脚本（resource-mapper.js 等）

扩展端通过 localResourceRoots 允许访问 dist/spa 与 media，并把 index.html 读入后重写资源路径与注入 CSP。

创建与复用 WebviewPanel

// 代码示例 - 基于 CC BY-NC 4.0 许可证
// Code example - Licensed under CC BY-NC 4.0
const panel = vscode.window.createWebviewPanel(
  "andreaRoleCardManager",
  "角色卡管理器",
  vscode.ViewColumn.One,
  {
    enableScripts: true,
    retainContextWhenHidden: true,
    localResourceRoots: [
      spaRoot,
      vscode.Uri.joinPath(ctx.extensionUri, "media"),
    ],
  }
);

复用面板时只需 reveal() 并刷新 HTML；首次创建时请设置好 localResourceRoots 与 enableScripts。

资源路径：一切都走 asWebviewUri

Webview 是隔离环境，磁盘路径或相对路径都不可直接用，必须通过 webview.asWebviewUri(vscode.Uri) 转换成安全 URL。

典型做法：

读取构建后的 index.html
重写标签属性：把 <script|link|img|source|video|audio|iframe> 的 src/href 统一替换为 asWebviewUri 生成的 URL。
处理 JS/CSS 内的路径：补齐 /assets/...、./assets/...，以及 import()、url(...) 等动态引用。

核心思想是“构建期 + 运行时双保险”：

构建期：用正则或解析器把常见的 src/href、/assets/ 统一改写；
运行时：注入资源映射器，拦截后续动态插入的节点与网络请求，确保依旧指向可达的 URL。

运行时资源映射器（最小思路）

// 代码示例 - 基于 CC BY-NC 4.0 许可证
// Code example - Licensed under CC BY-NC 4.0

// 1) 注入全局映射：把 /assets/file → asWebviewUri 对应结果
window.__vscode_resource_map__ = { '/assets/app.js': 'https://.../app.js', ... }
window.__vscode_resource_baseUri__ = 'https://.../spa'

// 2) transformPath：把一切本地路径改写成上面的可达 URL
function transformPath(p) {
  // 放过 http/https/data/blob/javascript
  // /assets 与 ./assets、assets 统一拼成 baseUri + /assets/...
}

// 3) 挂钩常见入口：
// - 元素属性：HTMLScriptElement.src / HTMLLinkElement.href / HTMLImageElement.src...
// - fetch / XMLHttpRequest.open
// - MutationObserver 监听新增节点并重写

这样即使 Vue 组件在运行时动态创建 <img>、<script>，或用 fetch('/assets/x.json')，也能被自动修正。

内容安全策略（CSP）

推荐策略（根据需要裁剪）：

<!-- 代码示例 - 基于 CC BY-NC 4.0 许可证 -->
<!-- Code example - Licensed under CC BY-NC 4.0 -->
<meta
  http-equiv="Content-Security-Policy"
  content="
  default-src 'none';
  img-src {{webview.cspSource}} https: data: blob:;
  style-src {{webview.cspSource}} 'unsafe-inline';
  font-src {{webview.cspSource}} data:;
  script-src {{webview.cspSource}} https: 'unsafe-inline';
  connect-src {{webview.cspSource}} https:;
  frame-src 'none';
  worker-src {{webview.cspSource}} blob:;
  child-src {{webview.cspSource}} blob:;
"
/>

说明：

{{webview.cspSource}} 实际运行时由 webview.cspSource 替换
如必须使用内联脚本，尽量控制在“注入全局数据”等极少量场景
如果需要访问接口域名，请把域名加入 connect-src

Webview ↔ 扩展通信

前端（Webview）：

// 代码示例 - 基于 CC BY-NC 4.0 许可证
// Code example - Licensed under CC BY-NC 4.0
const vscode = acquireVsCodeApi();

// 请求数据
vscode.postMessage({ type: "requestRoleCards" });

// 接收数据
window.addEventListener("message", (e) => {
  if (e.data?.type === "roleCards") {
    render(e.data.list);
  }
});

// 保存
function save(list) {
  vscode.postMessage({ type: "saveRoleCards", list });
}

扩展端：

// 代码示例 - 基于 CC BY-NC 4.0 许可证
// Code example - Licensed under CC BY-NC 4.0
panel.webview.onDidReceiveMessage(async (msg) => {
  if (msg?.type === "requestRoleCards") {
    panel.webview.postMessage({ type: "roleCards", list });
  } else if (msg?.type === "saveRoleCards") {
    // 校验并持久化
    panel.webview.postMessage({ type: "saveAck", ok: true });
  }
});

开发与调试建议

前端使用 vite build --watch 连续输出到 dist/spa
扩展端 F5 启动 “Extension Development Host”，重载即可验证
不直接接入 Vite Dev Server（CSP 与源隔离更复杂，且与发布环境不一致）
打开 Webview 开发者工具观察 Network 与 CSP 报错

常见问题排查

图片/CSS 不加载：检查 localResourceRoots、路径重写、asWebviewUri 是否覆盖到了
前端路由 404：优先使用 Hash 路由，或自行把导航与内容托管在 Webview 内部状态
CSP 报错：按报错提示补齐 connect-src、script-src 等来源

实战：预处理 HTML 与动态注入 JS 劫持（MPL-2.0）

下面给出一套可直接落地的实现，分为：

扩展端：读取构建产物的 index.html，批量重写资源路径、注入 CSP 与运行时代码，并输出给 Webview。
Webview 端：动态资源映射器，拦截 DOM 属性、fetch/XMLHttpRequest、MutationObserver 等入口，统一把 /assets 等路径改写为可达 URL。

许可说明：本文非代码部分以 CC BY-NC 4.0 授权；本小节内的“示例代码”以 Mozilla Public License 2.0（MPL-2.0）授权，你可以复制、修改并在满足 MPL-2.0 的前提下分发。

扩展端：HTML 预处理与注入（TypeScript, MPL-2.0）

/*
 * This file is licensed under the Mozilla Public License 2.0 (MPL-2.0).
 * SPDX-License-Identifier: MPL-2.0
 */
import * as vscode from "vscode";
import * as fs from "fs";

export function buildHtml(
  webview: vscode.Webview,
  spaRoot: vscode.Uri,
  opts?: {
    connectSrc?: string[];
    resourceMapperScriptUri?: string; // 已通过 asWebviewUri 转换
  }
) {
  const indexHtmlPath = vscode.Uri.joinPath(spaRoot, "index.html").fsPath;
  if (!fs.existsSync(indexHtmlPath)) {
    return `<html><body><h3>Webview</h3><p>index.html 未找到：<code>${indexHtmlPath}</code></p></body></html>`;
  }

  let html = fs.readFileSync(indexHtmlPath, "utf-8");
  html = rewriteHtmlToWebviewUris(html, webview, spaRoot);
  html = fixAllAssetUrls(html, webview, spaRoot);
  html = injectResourceMapper(
    html,
    webview,
    spaRoot,
    opts?.resourceMapperScriptUri
  );
  html = stripBaseTag(html);
  html = applyCsp(html, webview, opts?.connectSrc ?? ["https:", "http:"]);
  return html;
}

type Attr = "src" | "href";
function rewriteHtmlToWebviewUris(
  html: string,
  webview: vscode.Webview,
  spaRoot: vscode.Uri
): string {
  const fixRelFromVscodeWebview = (u: string) =>
    u.replace(/^vscode-webview:\/\/[^/]+\//i, "");
  const replaceAttr = (tag: string, attr: Attr) => {
    const re = new RegExp(
      `<${tag}\\b([^>]*?)\\s${attr}\\s*=\\s*(?:"([^"]+)"|'([^']+)'|([^\\s>]+))([^>]*)>`,
      "gi"
    );
    html = html.replace(re, (m, pre, g1, g2, g3, post) => {
      const raw = g1 ?? g2 ?? g3 ?? "";
      if (/^(data:|mailto:|javascript:|#|https?:)/i.test(raw)) return m;
      const rel = fixRelFromVscodeWebview(raw).replace(/^\.\/?/, "");
      const fileUri = vscode.Uri.joinPath(spaRoot, rel);
      const webUri = webview.asWebviewUri(fileUri).toString();
      const quoted =
        g1 != null ? `"${webUri}"` : g2 != null ? `'${webUri}'` : webUri;
      return `<${tag}${pre} ${attr}=${quoted}${post}>`;
    });
  };
  ["script", "link", "img", "source", "video", "audio", "iframe"].forEach(
    (t) => {
      replaceAttr(t, t === "link" ? "href" : "src");
    }
  );
  return html;
}

function fixAllAssetUrls(
  html: string,
  webview: vscode.Webview,
  spaRoot: vscode.Uri
): string {
  const base = webview.asWebviewUri(spaRoot).toString().replace(/\/$/, "");
  html = html.replace(
    /(\s(?:href|src)\s*=\s*)(["'])\/assets\//gi,
    (_m, p1, q) => `${p1}${q}${base}/assets/`
  );
  html = html.replace(
    /(\s(?:href|src)\s*=\s*)(["'])(?:\.\/)?assets\//gi,
    (_m, p1, q) => `${p1}${q}${base}/assets/`
  );
  html = html.replace(
    /(import\s*\(\s*)(["'`])([^"'`]*\/assets\/[^"'`]*)\2/g,
    (_m, pre, q, p) => `${pre}${q}${base}/${p.replace(/^\.?\//, "")}${q}`
  );
  html = html.replace(/(["'`])\/assets\//g, `$1${base}/assets/`);
  html = html.replace(/(["'`])\.\/assets\//g, `$1${base}/assets/`);
  return html;
}

function injectResourceMapper(
  html: string,
  webview: vscode.Webview,
  spaRoot: vscode.Uri,
  mapperScriptUri?: string
): string {
  const baseUri = webview.asWebviewUri(spaRoot).toString().replace(/\/$/, "");
  // 扫描 dist/spa/assets 目录，生成最小映射
  const assetsDir = vscode.Uri.joinPath(spaRoot, "assets").fsPath;
  const resourceMap: Record<string, string> = {};
  if (fs.existsSync(assetsDir)) {
    for (const f of fs.readdirSync(assetsDir)) {
      const key = `/assets/${f}`;
      resourceMap[key] = webview
        .asWebviewUri(vscode.Uri.joinPath(spaRoot, "assets", f))
        .toString();
    }
  }
  const safeMap = JSON.stringify(resourceMap)
    .replace(/</g, "\\u003c")
    .replace(/>/g, "\\u003e");
  const injectedData = `<script>window.__vscode_resource_map__=${safeMap};window.__vscode_resource_baseUri__="${baseUri}";<\/script>`;
  const mapperTag = mapperScriptUri
    ? `\n<script src="${mapperScriptUri}"><\/script>`
    : "";
  return html.replace(
    /<head([^>]*)>/i,
    `<head$1>\n${injectedData}${mapperTag}`
  );
}

function applyCsp(
  html: string,
  webview: vscode.Webview,
  connectSrc: string[] = []
): string {
  const connect = [webview.cspSource, ...connectSrc].join(" ");
  const csp = [
    `default-src 'none';`,
    `img-src ${webview.cspSource} https: data: blob:;`,
    `style-src ${webview.cspSource} 'unsafe-inline';`,
    `font-src ${webview.cspSource} data:;`,
    `script-src ${webview.cspSource} https: 'unsafe-inline';`,
    `connect-src ${connect};`,
    `frame-src 'none';`,
    `worker-src ${webview.cspSource} blob:;`,
    `child-src ${webview.cspSource} blob:;`,
  ].join(" ");
  const tag = `<meta http-equiv="Content-Security-Policy" content="${csp}">`;
  return /<meta http-equiv="Content-Security-Policy"/i.test(html)
    ? html.replace(/<meta http-equiv="Content-Security-Policy"[^>]*>/i, tag)
    : html.replace(/<head([^>]*)>/i, `<head$1>\n  ${tag}`);
}

function stripBaseTag(html: string): string {
  return html.replace(/<base\s+[^>]*>/gi, "");
}

使用方式：在创建/复用 WebviewPanel 后，读取 dist/spa/index.html 并调用 buildHtml，把返回的 HTML 赋给 panel.webview.html 即可。

Webview 端：动态资源映射器（JavaScript, MPL-2.0）

/*
 * This file is licensed under the Mozilla Public License 2.0 (MPL-2.0).
 * SPDX-License-Identifier: MPL-2.0
 */
(function () {
  var resourceMap = window.__vscode_resource_map__ || {};
  var baseUri = (window.__vscode_resource_baseUri__ || "").replace(/\/$/, "");

  function transformPath(path) {
    if (!path || typeof path !== "string") return path;
    if (path.startsWith(baseUri)) return path;
    try {
      const u = new URL(path);
      if (
        u.protocol === "vscode-webview:" &&
        u.pathname.startsWith("/assets/")
      ) {
        const key = u.pathname;
        return resourceMap[key] || baseUri + key;
      }
      if (/^(https?:|data:|blob:|javascript:)/i.test(u.protocol + ""))
        return path;
    } catch (_) {}
    if (path.startsWith("/assets/")) return resourceMap[path] || baseUri + path;
    if (path.startsWith("./assets/") || path.startsWith("assets/")) {
      const normalized = path.startsWith("./") ? path.slice(1) : "/" + path;
      return resourceMap[normalized] || baseUri + normalized;
    }
    if (/^(https?:|data:|blob:|javascript:)/i.test(path)) return path;
    const full = path.startsWith("/") ? path : "/" + path;
    return baseUri + full;
  }

  function patchURLProp(Ctor, prop) {
    try {
      const proto = Ctor && Ctor.prototype;
      if (!proto) return;
      const desc = Object.getOwnPropertyDescriptor(proto, prop);
      if (!desc || !desc.set || !desc.get) return;
      Object.defineProperty(proto, prop, {
        configurable: true,
        enumerable: desc.enumerable,
        get() {
          return desc.get.call(this);
        },
        set(v) {
          try {
            v = transformPath(String(v));
          } catch (_) {}
          return desc.set.call(this, v);
        },
      });
    } catch (_) {}
  }

  patchURLProp(HTMLScriptElement, "src");
  patchURLProp(HTMLLinkElement, "href");
  patchURLProp(HTMLImageElement, "src");
  patchURLProp(HTMLSourceElement, "src");
  patchURLProp(HTMLIFrameElement, "src");
  patchURLProp(HTMLMediaElement, "src");

  const _setAttr = Element.prototype.setAttribute;
  Element.prototype.setAttribute = function (name, value) {
    try {
      if (
        typeof value === "string" &&
        /^(src|href|srcset)$/i.test(String(name))
      ) {
        value = transformPath(value);
      }
    } catch (_) {}
    return _setAttr.call(this, name, value);
  };

  function rewriteCssUrls(cssText) {
    if (!cssText) return cssText;
    cssText = cssText.replace(
      /url\(\s*(['"]?)(?!data:|blob:)(\/?\.?assets\/[^'")\s?#]+(?:[?#][^'")]*)?)\1\s*\)/gi,
      (_m, q, p) => {
        let path = p;
        if (path.startsWith("./")) path = path.slice(1);
        if (path.startsWith("assets/")) path = "/" + path;
        if (!path.startsWith("/assets/")) return _m;
        const mapped = resourceMap[path] || baseUri + path;
        return "url(" + (q || "") + mapped + (q || "") + ")";
      }
    );
    cssText = cssText.replace(
      /@import\s+(?:url\(\s*(['"]?)(\/?\.?assets\/[^'\")\s;]+)\1\s*\)|(['"])(\/?\.?assets\/[^'\")\s;]+)\3)\s*;/gi,
      (_m, q1, p1, q2, p2) => {
        let path = p1 || p2;
        if (path.startsWith("./")) path = path.slice(1);
        if (path.startsWith("assets/")) path = "/" + path;
        if (!path.startsWith("/assets/")) return _m;
        const mapped = resourceMap[path] || baseUri + path;
        const q = q1 || q2 || "";
        return "@import url(" + q + mapped + q + ");";
      }
    );
    return cssText;
  }

  async function inlineStylesheet(linkEl) {
    try {
      if (!linkEl || linkEl.dataset.__inlined_css__) return;
      if (!/stylesheet/i.test(linkEl.rel || "")) return;
      if (!linkEl.href) return;
      const href = transformPath(linkEl.href);
      const res = await fetch(href, { credentials: "same-origin" });
      if (!res.ok) throw new Error("css fetch " + res.status);
      const css = await res.text();
      const fixed = rewriteCssUrls(css);
      const style = document.createElement("style");
      style.setAttribute("data-vscode-webview-inlined", "1");
      style.textContent = fixed;
      linkEl.dataset.__inlined_css__ = "1";
      linkEl.parentNode && linkEl.parentNode.insertBefore(style, linkEl);
      linkEl.remove();
    } catch (e) {
      try {
        linkEl.href = transformPath(linkEl.href);
      } catch (_) {}
      console.warn("inlineStylesheet failed:", e);
    }
  }

  var originalFetch = window.fetch;
  if (originalFetch) {
    window.fetch = function (url, options) {
      if (typeof url === "string")
        return originalFetch.call(this, transformPath(url), options);
      if (url && typeof url.url === "string") {
        var req = url;
        var newUrl = transformPath(req.url);
        if (newUrl !== req.url) {
          try {
            url = new Request(newUrl, req);
          } catch (_) {
            return originalFetch.call(
              this,
              newUrl,
              options || { method: req.method, headers: req.headers }
            );
          }
        }
      }
      return originalFetch.call(this, url, options);
    };
  }

  var X = window.XMLHttpRequest && window.XMLHttpRequest.prototype;
  if (X && X.open) {
    var origOpen = X.open;
    X.open = function (method, url) {
      try {
        if (typeof url === "string") arguments[1] = transformPath(url);
      } catch (_) {}
      return origOpen.apply(this, arguments);
    };
  }

  if (typeof window.__vitePreload !== "undefined") {
    var origPreload = window.__vitePreload;
    window.__vitePreload = function (fn, deps, path) {
      if (deps && Array.isArray(deps)) deps = deps.map((d) => transformPath(d));
      if (path) path = transformPath(path);
      return origPreload.call(this, fn, deps, path);
    };
  }

  function rewriteEl(el) {
    const tag = el.tagName;
    if (tag === "LINK") {
      const rel = (el.rel || "").toLowerCase();
      if (rel.includes("stylesheet")) {
        inlineStylesheet(el);
        return;
      }
      if (el.href) {
        const next = transformPath(el.href);
        if (next !== el.href) el.href = next;
      }
      return;
    }
    if (tag === "SCRIPT" && el.src) {
      const next = transformPath(el.src);
      if (next !== el.src) el.src = next;
      return;
    }
    if (
      (tag === "IMG" ||
        tag === "SOURCE" ||
        tag === "VIDEO" ||
        tag === "AUDIO") &&
      el.src
    ) {
      const next = transformPath(el.src);
      if (next !== el.src) el.src = next;
    }
    if (el.hasAttribute && el.hasAttribute("srcset")) {
      try {
        const raw = el.getAttribute("srcset") || "";
        const parts = raw
          .split(",")
          .map((p) => p.trim())
          .filter(Boolean);
        const fixed = parts
          .map((p) => {
            const sp = p.split(/\s+/);
            sp[0] = transformPath(sp[0]);
            return sp.join(" ");
          })
          .join(", ");
        if (fixed !== raw) el.setAttribute("srcset", fixed);
      } catch (_) {}
    }
  }

  if (typeof MutationObserver !== "undefined") {
    const mo = new MutationObserver((muts) => {
      for (const m of muts) {
        if (m.type === "childList") {
          m.addedNodes &&
            m.addedNodes.forEach((n) => {
              if (n && n.nodeType === 1) {
                rewriteEl(n);
                n.querySelectorAll?.(
                  "link[rel],script[src],img[src],source[src],video[src],audio[src],[srcset]"
                ).forEach(rewriteEl);
              }
            });
        } else if (m.type === "attributes") {
          rewriteEl(/** @type {Element} */ (m.target));
        }
      }
    });
    const start = () => {
      mo.observe(document.documentElement || document, {
        childList: true,
        subtree: true,
        attributes: true,
        attributeFilter: ["href", "src", "srcset", "rel"],
      });
      document
        .querySelectorAll(
          "link[rel],script[src],img[src],source[src],video[src],audio[src],[srcset]"
        )
        .forEach(rewriteEl);
    };
    document.readyState === "loading"
      ? document.addEventListener("DOMContentLoaded", start, { once: true })
      : start();
  }

  console.log("VSCode Webview resource mapper initialized");
  console.log("Base URI:", baseUri);
})();

要点回顾：

扩展端始终以 webview.asWebviewUri 作为“真相源”；
Webview 端只做兜底修复，确保动态新增节点与网络请求同样可达；
两侧配合 CSP，既安全又稳定。

以上示例代码以 MPL-2.0 授权；若你在项目中使用，请保留许可头与变更说明。

小结

把 Vue SPA 嵌入 VS Code Webview 的关键是“资源可达且安全”。

通过：

全量走 asWebviewUri 暴露静态资源
运行时资源映射器兜底动态引用
严格且可控的 CSP 配置
明确的数据通信协议

即可实现稳定、安全的嵌入式前端体验。后续你可以叠加数据持久化（全局存储/工作区文件）、多语言与主题适配等能力。

Fuwari 博客模板使用指南(Koro Version)

Mon, 01 Apr 2024 00:00:00 GMT

封面图片来源: Source

这个博客模板基于 Astro 构建。对于本指南中未提及的内容，您可以在 Astro 文档中找到答案。

文章的 Front-matter

---
title: 我的第一篇博客文章
published: 2023-09-09
description: 这是我新 Astro 博客的第一篇文章。
image: ./cover.jpg
tags: [前端, 博客]
category: 技术
draft: false
lang: "zh_cn"

---

属性	描述
`title`	文章标题。
`published`	文章发布日期。
`description`	文章简短描述，显示在首页。
`image`	文章封面图片路径。<br/>1. 以 `http://` 或 `https://` 开头：使用网络图片<br/>2. 以 `/` 开头：使用 `public` 目录中的图片<br/>3. 无前缀：相对于 markdown 文件的路径
`tags`	文章标签。
`category`	文章分类。
`draft`	是否为草稿，草稿不会显示。
`lang`	文章语言（如 "zh_cn", "en", "ja"）。

文章文件放置位置

您的文章文件应放置在 src/content/posts/ 目录中。您也可以创建子目录来更好地组织您的文章和资源。

多语言支持

对于多语言文章，请使用以下命名约定：

src/content/posts/
├── guide/
│   ├── cover.jpeg
│   ├── index.md          # 默认语言（中文）
│   └── index.en.md       # 英文版本
├── hello-world/
│   ├── hello-world.zh_cn.md
│   └── hello-world.en.md
└── single-post.md        # 单语言文章

语言切换

在顶部 Header 中全局切换语言，会自动筛选。

支持的语言

此博客模板支持以下语言：

简体中文：zh_cn
英语：en
日语：ja
俄文：ru

计算机编程技巧与心得

Andrea Novel Helper - 专为小说创作者打造的 VS Code 写作增强扩展

Andrea Novel Helper - 专为小说创作者打造的 VS Code 写作增强扩展

✒️ 核心写作体验

智能统计与分析

智能排版与辅助

快捷设置面板

🌍 设定集与世界观构建

统一对象模型 (Unified Object Model)

通用特性

多格式资源管理

包结构建议

📂 项目与文件管理

写作资源管理器

云端同步 (WebDAV)

项目配置

🤖 自动化与扩展

用户脚本与 MCP 运行时

Typst 排版导出

📊 实时辅助功能

阅读与预览

批注系统

LLM 智能辅助（润色和生成部分位于 ANH CHAT 附件中 不随小说助手本体提供 或者您可以使用任何 Code Agent 完成这部分工作）

🎯 核心优势

1. 统一的工作环境

2. 智能化的辅助功能

3. 强大的数据管理

4. 高度可定制性

5. 现代化的技术栈

🆚 与传统写作软件对比

稿件可见宣言

🚀 快速开始

安装扩展

创建新项目

基本使用流程

📈 发展历程

💬 社区与支持

📄 许可证

一个Typst模板

模板下载

模板预览

模板源码

小说助手 安装和基础功能使用说明

安装

便携安装（对于普通用户）

全量安装（对于专业用户）

第一步 下载 Git 和编辑器

安装小说助手

使用

新建书籍项目

写作资源管理器（全文字数统计）

敏感词识别

智能补全和提示

设定集管理器

写作统计

导出 预览 和 读稿器

界面美化

VS Code Git集成与各大平台私有仓库使用指南（小说助手专用）

VS Code Git 集成使用指南（图解）

🎯 特别说明：小说助手用户必读

什么是版本管理？

为什么小说助手需要 Git？

📋 小说助手专用 Git 工作流程

步骤 1：查看更改

步骤 2：暂存更改

步骤 3：提交更改

步骤 4：推送到云端

🔄 小说助手用户日常同步操作

🛠️ 通用 Git 操作指南

2) 打开或克隆仓库

打开项目或克隆

初始化本地仓库

3. 暂存（Stage）与提交（Commit）

4. 分支与标签（Branches & Tags）

5. 源代码控制图（Graph）

6. 查看历史：时间线（Timeline）

7. VS Code 作为 Git 的编辑器/差异/合并工具

8. 多仓库与其他 SCM

9. 常用操作速查

🌐 各大代码托管平台私有仓库使用攻略

LLM 智能辅助（润色和生成部分位于 ANH CHAT 附件中不随小说助手本体提供或者您可以使用任何 Code Agent 完成这部分工作）

小说助手安装和基础功能使用说明

第一步下载 Git 和编辑器

导出预览和读稿器

小说助手 0.3.25 版本发布新功能介绍和教程

小说助手 0.3.25 版本发布新功能介绍和教程

小说助手 0.3.24 版本发布新功能介绍和教程

小说助手 0.3.24 版本发布新功能介绍和教程