Lacan Translation Helper

用于在 Obsidian 中阅读、编辑和对照拉康研讨班法中原译文的桌面端插件，提供逐段阅读、章节笔记、法语查词和本地 CLI 分段分析。

Obsidian 社区下载：Lacan Translation Helper

本仓库是从拉康中文翻译项目中迁出的独立插件源码仓库。插件名称为 Lacan Translation Helper，ID 为 lacan-translation-helper。插件代码在 kotoba-rin/LCTPlugin 维护，研讨班文本仍在原翻译项目维护；插件默认从 KotobaRin 的 WordPress 同域文库接口同步原项目的已发布内容。

研讨班专用功能按以下 Vault 目录及稳定分段 ID 工作：

texts/<seminar>/
  original/Leçon-01.md
  translation/Leçon-01.md
  notes/
  glossary.md

原译文通过 <!-- id: s8-01-0001 --> 等标记对齐；合并译文还可以声明 <!-- ids: ... -->。界面与生成的阅读辅助材料目前主要使用中文。

功能

• 法中双语阅读、文内搜索和按分段 ID 定位。
• 在阅读视图或双语阅读中就地编辑整段中文译文、注释和建言。粘贴图片遵循 Obsidian 附件设置；图片在粘贴时创建，取消编辑仍会保留该附件。
• 创建章节阅读笔记，收录当前分段的原文、译文、注释和建言。
• 创建译文骨架、按 <!-- untranslated --> 标记统计翻译进度；Obsidian Bases API 可用时提供课次状态浏览。
• 安装后创建 Base 和完整课次清单，按研讨班初始化目录和术语表，按课次同时同步原文、译文及引用附件；保留本地笔记和修改。
• 使用 Obsidian 内置 PDF 阅读器，并对 PDF 文字层进行法语取词。扫描 PDF 需先通过其他工具生成 OCR 文字层。
• 查询法语助手在线词典，通过所选 CLI 翻译选区，使用系统法语朗读，并收藏到所选欧路生词本。
• 在侧栏进行只读的译文解读或原文解析，支持流式回答、多会话、继续追问，支持 Codex CLI、Claude Code、DeepSeek Harness；Codex 可自动发现已安装 Skills。

使用条件

• Obsidian 桌面端，manifest 声明的最低版本为 1.8.0。依赖较新 Obsidian API 的功能有可用性检查，在旧版本上可能无法使用。
• 研讨班相关功能需要符合翻译项目格式的 Vault。已有项目用户可以继续使用当前文库。
• 文库下载和增量更新不需要 Git CLI。插件通过 HTTPS 获取发布清单，并按文件 SHA-256 比较变化。
• AI 功能支持 Codex CLI、Claude Code、DeepSeek Harness，适配 Windows 与 macOS。在「AI 功能 → CLI 工具」选择提供方，留空路径自动检测，也可指定此电脑的入口。先在终端完成相应 CLI 的安装和登录／API 配置。各工具的协议与能力差异见 CLI 适配说明。插件不会安装 CLI 或自动切换到其他模型服务。
• 只有读取、更新欧路生词本时才需要 欧路 API 授权码。公开词典查询不使用该授权码。
• 从源码开发和构建需要 Node.js 20+ 与 npm；使用已构建好的插件不需要另行安装 Node。

所选模型服务和欧路服务可能需要第三方账号、订阅或按量付费。相应服务自行管理权限与费用，插件不提供账号或服务额度。

从源码安装

将本仓库克隆到文库之外的开发目录，在本仓库根目录运行：

npm ci
npm run build
npm run install:plugin -- /绝对路径/你的文库

安装命令将三个运行文件复制到 <文库>/.obsidian/plugins/lacan-translation-helper/，保留已有插件设置和会话记录。随后在 Obsidian「第三方插件」设置中关闭再开启插件，加载新构建。

手动安装时，将 main.js、manifest.json 和 styles.css 复制到上述目录即可。个人 data.json、凭据和会话数据不应进入 Git 或分发包。

可在空的 Obsidian 文库中安装插件。首次安装会创建 Lacan-Chinese-Translation-Project.base 并读取课次和知识词条目录，不下载正文；已有同名 Base 仅补入缺少的知识库视图，保留原有筛选和自定义配置。已有本地翻译项目也可继续使用。

内容同步

默认同步地址为 https://kotoba-rin.com/wp-json/lctp/v1/project。所有用户使用同一种安全同步，不再区分 Reader 与 Editer，也不会初始化、切换或清理本地 Git 仓库。

打开 Base 可在尚未下载正文时查看全部已发布课次。点击研讨班旁的「初始化研讨班」只下载该研讨班术语表，并创建 original/、translation/、notes/、assets/ 目录。每课的「同步」会成对获取原文和译文，按需下载其引用图片或 PDF；右侧从 0% 显示同步进度，完成后为 100%。不会只同步原文或只同步译文，也不再整库下载 ZIP。

Base 的「知识库」视图展示完整已发布词条目录，可搜索标题、文件名、标签、别名和正文摘录，并按分类、主题、关联研讨班和同步状态筛选。未下载词条提供「同步」「同步并打开」，只下载本卡及引用图片／PDF，不递归下载关联卡或课文。阅读正文时点击未下载的知识卡链接，也可选择「同步并打开」，并保留目标锚点。已缓存目录和已下载词条可离线使用；未下载正文不进入 Obsidian 本地全文搜索。旧发布端没有词条元数据时，目录按文件名显示；已下载卡可使用本地标签筛选。

「更新目录」旁的「同步全部知识库」按完整目录顺序依次处理所有已发布词条，不受搜索或筛选条件影响。每张卡及其附件完成后才开始下一张，所有下载请求串行执行，整批共用一次发布清单。可查看处理进度并取消；取消或下载失败后停止后续任务，已完成的内容保留，本地修改仍会跳过。

设置中的「更新文库目录」和启动检查只读取目录。同步状态同时检查正文和引用附件，区分有更新、附件待补齐和本地已修改；共享附件变化会更新所有引用词条的状态。未发布的本地知识卡仍可检索打开，上游移除的已下载卡保留并提示。无变化的文件不重复下载。WordPress 文库来自 GitHub 的 reading 分支，移除建言并保留正文、段下注释、原目录、分段 ID 和相对链接；完整编辑原稿仍保存在 main。

• 本地文件与上次成功同步的版本不同，就视为有本地修改。改译文、添加备注、注释或建言，以及空白和格式变化，都会受到保护。原文和译文作为一课处理：其中一份或本课引用附件有本地修改，整课跳过，不自动合并、不覆盖。
• 知识卡以单张卡及其引用附件为一组，执行相同的本地修改、未保存编辑和同步期间变化保护；跳过时不推进同步基线。
• 跳过时提示具体文件，Base 显示「已跳过」，不把本次操作记为同步成功。再次同步仍保留这些修改，也不会推进被跳过文件的同步基线。
• 如需重新下载，请先保留修改副本，再删除提示中有改动的本地文件，重新点击同步。已删除的文件会重新下载，不再作为「本地删除冲突」阻止下载。
• 未保存的编辑、下载过程中发生的修改也会触发跳过；写入期间检测到变化时撤回本课已应用的更新，并保留用户的新修改。
• 第一次接管已有文库时，如果同名文件与发布版本不同且缺少可信基线，也会跳过，不猜测用户意图。没有选择的课次、私人笔记和其他附件不受影响。
• 插件设置、会话数据和其他 Obsidian 配置不属于文库同步范围。
• 下载和校验完成后才应用更新；取消、网络中断或应用失败可重试，未完成事务在下次同步时恢复。

「最近同步与跳过记录」列出本次跳过的文件及原因。旧版冲突记录继续保留供只读核对，不通过报告执行覆盖或合并；旧版基线正文不再保留，因此不再提供依赖该正文的三方比较。

同步基线保存在当前文库配置目录的 plugins/lacan-translation-helper/project-sync/state.json，记录每个文件上次成功同步的 SHA-256 校验值。Base 读取这些状态用于展示，不把校验值写入正文或 .base 配置。同步被跳过或失败时不推进校验值，继续保护本地修改。缺少可信校验值时保守跳过既有差异文件；恢复下载只需删除对应正文后同步，不需要清空同步状态。启动时自动检查清单默认关闭。

插件不再生成 bases/ 正文缓存，启动或同步时自动清理旧的 bases/<SHA-256>.bin 文件。清理仅针对这些正文副本，不删除文库正文、同步状态、旧版冲突记录或上游冲突副本。同步失败恢复所需的事务备份与日志单独管理，在事务安全完成后清理。

用户修改检测按文件字节比较，不裁剪空白、不移动分段 ID，也不尝试把上游新段落写进用户改过的文本。

已存在的 .git 不会被修改。参与贡献的维护者仍可自行使用 Git 管理版本，但客户端增量更新本身不调用 Git。公开分发协议见 内容快照协议。

在「项目与同步」中可开启「插件 HTTP 代理」并填写代理地址，例如 http://127.0.0.1:7890。代理用于文库同步、词典查询和生词本请求，通过独立网络会话生效；关闭时沿用 Obsidian 的网络设置。旧版 GitHub 代理的开关和地址会自动迁移。AI CLI 继续使用自身的网络配置，词典图片和外部网页使用 Obsidian 的网络设置。

联网、文件访问与隐私

在线功能和本机集成涉及以下数据及访问范围：

“本地 Agent”表示本机进程，不代表模型推理必定在本地完成。 按照你的模型服务配置与服务政策，交给 CLI 的文本可能离开本机。插件沿用已有 CLI 登录／凭据，不会静默回退到另一套模型 API。

分段 AI 默认关闭。其运行时请求只读沙箱、拒绝权限提升，并要求 Agent 不修改原文、译文、术语表或笔记。快速选区翻译不开放模型工具，其 Codex 会话为临时会话；分段解读使用可恢复的 Codex 会话。其他 CLI 的会话及原生 profile 行为见 CLI 适配说明。这些 AI 权限与用户主动操作的段落编辑、创建笔记和文库同步分别生效。

插件代理在接收响应时检查声明长度和实际字节数，并将文库取消／超时传递到底层请求；正文按需转换为文本或二进制。关闭插件代理时沿用 Obsidian 的 requestUrl，插件只能在主机返回完整响应后检查大小，无法控制主机内部的缓冲或强制中止该请求。

插件设置、分段会话历史和草稿保存在本地 data.json。每种 CLI 在文库之外管理自己的登录、配置与会话数据。三种提供方的插件会话和草稿分别保存；CLI 路径按操作系统与电脑名称保存，跨电脑不复用，电脑名称会明文保存在 data.json 的路径索引中。关闭会话标签不会删除历史。欧路授权码在支持时存入 Obsidian SecretStorage；旧版 Obsidian 只在当前运行期间保留，不写入 data.json。如果会话内容或电脑名称敏感，请同时检查文库同步与备份设置。

插件未包含客户端使用统计或开发者运营的遥测接口。第三方服务按照各自的条款与隐私政策处理请求。

桌面能力与权限提示

社区审核会根据使用的 API 列出以下能力。它们分别服务于具体功能：

上述能力需要桌面端，因此 manifest.json 声明 isDesktopOnly: true。fs 和 child_process 仍用于上述功能，静态审核仍可能显示这些能力提示。AI 的只读策略与插件的编辑、同步权限分别生效，不能据此认为整个插件或第三方 CLI 已被操作系统沙箱隔离。

开发与验证

npm ci
npm run build
npm run build:check
npm test
npm run package:plugin

• src/main.js 为插件入口，segment-ai/ 为 CLI 集成及领域模块。
• Obsidian 实际加载根目录的 main.js；提交时应保持它与源码一致。
• npm run package:plugin 在 dist/ 中生成三个可分发运行文件。
• 测试使用模拟环境与固定材料；通过测试不代表已经验证真实 CLI 登录、词典服务可用性或所有 Obsidian 交互。

详细说明

• 法语取词与欧路生词本
• PDF 阅读
• 原文解析
• 章节阅读笔记
• Skills 自动发现
• 分段 AI 架构
• 多会话架构与历史设计

部分架构文档保留历史决策；已注明后续替换的内容，以当前代码及 Skills 自动发现说明为准。

插件问题及功能建议请提交到本仓库 Issues；原译文修订仍提交至翻译项目。

许可与来源

本仓库的插件源码、样式、构建工具、测试和配套文档采用 MIT 许可证。分发时须保留版权声明和许可文本；构建后的 main.js 已包含完整许可。详见 LICENSE 和 来源说明。

研讨班原文、译文及第三方材料的授权安排独立于插件的软件许可证。