# @soulwaxx/obsidian-second-brain 中文文档 规范地址：https://npmcn.com/package/%40soulwaxx/obsidian-second-brain/ 版本：3\.4\.0 npm 元数据更新时间：2026-11-02T12:19:33.123Z 中文译文更新时间：2026-11-02T13:07:55.125Z 软件包许可：MIT 本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40soulwaxx/obsidian-second-brain 原文对照：https://npmcn.com/package/%40soulwaxx/obsidian-second-brain/?lang=original 项目主页：https://github.com/soulwaxx/obsidian-second-brain#readme 源码仓库：https://github.com/soulwaxx/obsidian-second-brain ## 关键信息（来自 npm 元数据） - 包体积（解压后）：897 kB，74 个文件 - 模块格式：ES Module - TypeScript 类型：未声明 - Node.js 要求：\>=18\.0\.0 - 运行依赖：0 个 - peer 依赖：@earendil-works/pi-coding-agent \* - 首次发布：2026-10-02T22:44:04.837Z - 最新版本发布：2026-11-02T12:19:32.753Z - 已发布版本数：22（近 12 个月 22 个） ## 中文简介 OKF wiki技能和vault范围的生命周期集成，用于Obsidian、Pi和Claude Code ## 安装 ```sh npm install @soulwaxx/obsidian-second-brain ``` 也可以使用：`pnpm add @soulwaxx/obsidian-second-brain`、`yarn add @soulwaxx/obsidian-second-brain`、`bun add @soulwaxx/obsidian-second-brain` ## README # obsidian-second-brain 维护一个 [开放知识格式（OKF） v0.2](https://npmcn.com/package/%40soulwaxx/obsidian-second-brain/skills/wiki/SKILL.md) 维基百科 《克劳德密码》或《圆周率》中的黑曜石拱顶，不把特工移出 当前的存储库。这个包提供了一个wiki技能，基于目标的文件 保护、生命周期维护和本地检索工具。 **Obsidian Git拥有提交、拉取和推送。** 的安装和启用它 配置工作流;代理集成永远不会执行这些操作。 Markdown、本地检索和页面维护在Obsidian时仍然可用 是关闭的。自动同步需要运行应用程序和插件。 金库还是你的。设置在确认之前预览提议的更改； 保留现有的注释和不相关的设置，并拒绝冲突。看到 [NOTICE.md](https://npmcn.com/package/%40soulwaxx/obsidian-second-brain/NOTICE.md) 和 [许可证](https://npmcn.com/package/%40soulwaxx/obsidian-second-brain/LICENSE) 关于归属和许可条款。 ## 要求 - 克劳德代码或圆周率；使用PyYAML的Python 3.14或更新版本；标记它-py证据报告，大纲和部分选择的阅读； `jq` 用于生命周期命令。 - Node.js 18或更新的包CLI启动器。使用支持的Node.js LTS 释放;节点18的生命周期已结束。Pi有自己的Node.js需求，它可以 高于这个包的最低限度。 - Obsidian与所有者安装的Obsidian Git插件版本控制。 安装程序在应用程序之前验证其安装的清单和启用的插件列表 配置文件；它不下载插件二进制文件。 - Git用于仓库存储库和包安装。存储库创建, 远程选择、身份和身份验证仍然由所有者控制。 - 用于安装命令的存储库签出或安装包目录。 安装包不会在shell路径中添加setup命令行。 确保 `python3 --version` 报告Python 3.14或更新版本。从活动包签出（或解包）安装Python运行时依赖项： ```sh python3 -m venv "$HOME/.venvs/obsidian-second-brain" . "$HOME/.venvs/obsidian-second-brain/bin/activate" python3 -m pip install -r requirements.txt ``` `markdown-it-py` 是由 `evidence-report`， `outline`，以及分段选择 `read` 命令。医生、搜索和显式跨读不需要它。如果一个 解析器依赖命令不能导入它，命令行打印安装 指令，而不是静默地使用不完全标记扫描。 在Linux上，安装您的发行版 `python3-venv` 必要时包装。保持 运行Python命令时，使环境处于活动状态。 ## 安装代理包 对于Pi，安装已发布的npm版本： ```sh pi install npm:@soulwaxx/obsidian-second-brain ``` 要跟踪未发布的源代码，请使用 `pi install git:github.com/soulwaxx/obsidian-second-brain`. 对于Claude Code： ```sh claude plugin marketplace add soulwaxx/obsidian-second-brain claude plugin install obsidian-second-brain@obsidian-second-brain --scope user ``` GitHub市场是一个目录；Claude从同一个插件中获取插件 版本化npm工件为Pi。目录故意不固定插件 的版本。Claude Code和npm必须支持npm插件源代码。 现有的git支持的安装保留相同的插件标识。刷新 编目和更新插件一次即可迁移： ```sh claude plugin marketplace update obsidian-second-brain claude plugin update obsidian-second-brain@obsidian-second-brain --scope user ``` 更新后重新启动Claude Code。对于未发布的本地开发，请加载 付款用 `claude --plugin-dir /absolute/path/to/obsidian-second-brain`； 添加其市场仍然选择已发布的NPM插件。 使用现有的签出或创建一个签出，用于以下设置示例： ```sh git clone https://github.com/soulwaxx/obsidian-second-brain.git cd obsidian-second-brain PLUGIN_DIR="$(pwd -P)" VAULT="$HOME/Notes/MyVault" # Replace with the selected absolute vault path. ``` ## 脚手架，然后配置 首先预览最小的wiki脚手架： ```sh python3 "$PLUGIN_DIR/scripts/bootstrap-vault.py" --vault "$VAULT" ``` 检查计划，然后使用它的精确散列： ```sh python3 "$PLUGIN_DIR/scripts/bootstrap-vault.py" --vault "$VAULT" --apply --confirm 'PASTE_SCAFFOLD_HASH_HERE' ``` 这就造成了缺失 `.obsidian/`， `wiki/quickstart.md`，并生成导航。 它保留现有的笔记、日志和设置。脚手架可以放在插件之前 安装;它还没有创建或迁移代理集成配置。 打开目录作为Obsidian vault，故意创建/使用它的Git 并安装/启用Obsidian Git。审查 [Git安装](https://npmcn.com/package/%40soulwaxx/obsidian-second-brain/skills/wiki/references/git-setup.md) 在第一次备份之前。然后 预览支持的配置文件： ```sh python3 "$PLUGIN_DIR/scripts/bootstrap-vault.py" --vault "$VAULT" --configure ``` 检查所选的配置/插件差异并忽略添加的内容。 然后确认这个单独的计划： ```sh python3 "$PLUGIN_DIR/scripts/bootstrap-vault.py" --vault "$VAULT" --configure --apply --confirm 'PASTE_CONFIGURE_HASH_HERE' ``` 经过审查的配置选择保险库并设置已弃用的代理 `features.autoCommit` 字段 `false`。它保留了不相关的设置， 现有的插件时间表，以及现有的禁用推送选项。禁用 插件提交压缩是一个明确的建议，而不是一个隐藏的重置。私人 Settings /preimages绑定到计划散列，但不会在预览中转储。 默认配置为 `~/.config/obsidian-second-brain/properties.json`. `OBSIDIAN_AGENT_CONFIG` 选择另一个文件； `OBSIDIAN_VAULT_PATH` 选择一个 用于调用的Vault。安装程序永远不会静默地重新定位指向 不同的库。当检查的文件更改时重新预览。看到 [安装指南](https://npmcn.com/package/%40soulwaxx/obsidian-second-brain/docs/setup.md) 用于迁移和先决条件诊断。 ## 从任意文件夹工作 在主任务所属的存储库或文件夹中启动代理。 使用 `/obsidian-second-brain:wiki` 克劳德代码或 `/skill:wiki` 在圆周率中 一般入口点。有焦点的意图可作为 `/obsidian-second-brain:wiki-query`， `/obsidian-second-brain:wiki-save`， `/obsidian-second-brain:wiki-ingest`， `/obsidian-second-brain:wiki-research`， 和 `/obsidian-second-brain:wiki-health` 在克劳德代码中，或者 `/skill:wiki-query`， `/skill:wiki-save`， `/skill:wiki-ingest`， `/skill:wiki-research`, `/skill:wiki-health` 在π。查询和运行状况为只读；只保存文件 明确选择对话洞察力；摄取/研究并不意味着生的 源捕获或自动归档。每个意图都遵循共享的wiki 编写规则。该技能解析配置的保险库并使用绝对运行时 必要时的路径。普通的相对编码路径保持其 当前目录的意思。较大的协调wiki编辑可以选择使用 复核可恢复批CLI；小的编辑保留正常的生命周期。一个 明确选择的本地UTF-8文本源也可以通过 单独评审，不可变捕获成 `.raw/agent-captures/`;选择 源可以选择使用审查的字节观察和页面协调 没有存档源内容的基线。两者都不是强制性的，捕获 不提供web/媒体提取或授权维基文件。看到 [重点工作流程参考](https://npmcn.com/package/%40soulwaxx/obsidian-second-brain/skills/wiki/references/focused-workflows.md) 和 [基线的合同](https://npmcn.com/package/%40soulwaxx/obsidian-second-brain/docs/source-baselines.md) 查看审批和恢复细节。 Startup提供一个小的保险库定位器，而不是注入整个 个人索引成无关的工作。该技能搜索和阅读相关内容 在任务需要时分页。批准的摄入或研究通行证可能会更新 相关规范页面；普通问题保持只读，除非归档 是要求。每次只保留一个wiki作者。 无论代理cwd如何，文件工具保护都应用于选定的保险库目的地。 它们保护生成的 `index.md` 和lifecycle-owned `log.md` 在每一个维基 深度、策划源、设置和不安全路径。Shell写不是 沙箱;遵循该技能的显式保护/验证工作流，如果文件 工具生命周期不可用。 生命周期验证更改的页面，并使用 导航、日志记录，以及每个经过验证的更改批处理一次可选的BM25刷新。 刷新失败会留下一个持久的仅检索的重试；内容/导航/日志 出版物和搜索新鲜度分别报告。被允许的作家 最终化或显式BM25构建可以在不复制日志的情况下解决这个问题。 与 `features.retrievalRefresh: false`，则不会发生自动构建。Outside-lifecycle Obsidian/manual/shell编辑被诊断为过时，不自动维护。 失败的更改页将保留以供修复；一个不相关的历史缺陷并不是整个金库的否决。 无关的启动/只读关闭不会重新生成保险库。黑曜石 Git独立处理版本控制，包括遗留配置 `autoCommit: true`. ## 查询和诊断 Pi也注册了四个直接的，只读的 `wiki_search`， `wiki_outline`， `wiki_read`, `wiki_doctor` 工具。它们调用当前安装的 包的Python检索/读取操作，并且不会将wiki内容注入 提示;看到 [Pi工具契约](https://npmcn.com/package/%40soulwaxx/obsidian-second-brain/docs/pi-tools.md). 当 `obsidian-second-brain` 宾在讲话 `PATH`，使用包所属的命令行 对于任何文件夹中的只读结构化搜索和医生命令： ```sh obsidian-second-brain search "query terms" --json obsidian-second-brain doctor --json obsidian-second-brain evidence-report --json obsidian-second-brain source-check --root-id research-notes --source-root "/absolute/path/to/selected sources" --json ``` 安装Pi和Claude插件并不一定要打开npm bin 壳牌 `PATH`。如果 `command -v obsidian-second-brain` 失败，不安装 第二个副本：调用活动包的Node启动器，使用它的package-relative 路径。这个 [共享工作流引用](https://npmcn.com/package/%40soulwaxx/obsidian-second-brain/skills/wiki/references/focused-workflows.md#run-the-package-cli) 展示了如何从Claude加载的技能库中派生绝对包根 目录或Pi加载的技能位置；这可以从任何调用者CWD中工作，并选择 该客户端已加载的版本。 搜索使用选定的索引库，不重建索引；医生的报告 配置、依赖项、保管库、缓存排除、生命周期和检索 状态而不修复它们。 `evidence-report` 也是只读的；可选 来源/索赔记录不迁移或不需要，其结构， 新鲜感和关系输出不建立事实真相或来源 验证。 `source-check` 单独的、显式选择的是只读的吗 本地来源记录的比较；它报告的是审查信号，而不是真相或 和解。看到 [source-check合同](https://npmcn.com/package/%40soulwaxx/obsidian-second-brain/docs/source-drift.md)。引用 扫描遵循markdown-it-py的CommonMark解析；它不启用 黑曜石特定的Markdown扩展。使用生成的wiki 当搜索不可用或没有有用结果时，索引层次结构。重点工作流程限制和 中记录了选定对话保存规则 [共享工作流引用](https://npmcn.com/package/%40soulwaxx/obsidian-second-brain/skills/wiki/references/focused-workflows.md). 对于显式请求的Obsidian兼容性审计，请运行单独的 只读 `scripts/obsidian_compat.py` 报告。它保持OKF分辨率不变 并将文件系统结果与本机解析器证据分开标记。 [已审查的链路迁移](https://npmcn.com/package/%40soulwaxx/obsidian-second-brain/docs/link-migration.md) 封面撰写Markdown 批处理、可选择的生命周期拥有的历史目的地，以及最终的图形检查。 诊断和正常终结都不会隐式迁移旧的历史。 ## 当地的检索 检索船与包；没有安装保险库本地助手，奥拉玛 或者需要网络服务。从任何文件夹： ```sh python3 "$PLUGIN_DIR/scripts/bm25-index.py" build --vault "$VAULT" python3 "$PLUGIN_DIR/scripts/retrieve.py" "query terms" --vault "$VAULT" ``` 派生缓存位于 `.vault-meta/retrieval/`。留着吧。 `.vault-meta/lifecycle/` 在Git中被有效地忽略。生命周期刷新使用 package-owned脚本;丢失/损坏的缓存回退到生成的索引 导航。不再支持库本地帮助器复制；使用活动包的 脚本。包更新永远不会删除现有的vault-local文件。 当前检索保守地屏蔽了清晰的单行Markdown划线 在文字/代码/链接上下文中；撰写的历史和原始源偏移 保持不变。iso日期查询使用历史词法视图。没有标记的 矛盾仍然需要人来巩固。搜索/医生永远不会重建 旧缓存：显式地为新缓存重建BM25和可选的语义块 假设目前覆盖范围之前的预测/输入方案。 文档嵌入构建包括 **手动和增量输入**：兼容的 原始单元输入重用经过编辑/移动/重复的验证向量；只有失踪 输入被发送到已安装的模型。块池/边界和RRF仍然存在 不变。遗留的池缓存不能恢复单个单位向量；他们的 第一个显式兼容构建填充输入缓存。构建报告真实 输入/字符计数，持续时间和缓存大小。缓存语义搜索嵌入 只有查询，永远不会丢失文档或遗留页头候选列表。 这个 [只读的评估者](https://npmcn.com/package/%40soulwaxx/obsidian-second-brain/docs/retrieval-evaluation.md) 私下审查的用途 配对EN/IT金色和准备一次性快照。它的生活质量结果 与确定性CI分开，并且不授权模型/融合更改。 嵌入操作默认为 `qwen3-embedding:4b`； `--ollama-model` 选择 另一个已经安装的模型。更改模型不会使旧模型缓存 向量兼容：在所选模型之后显式重建语义块 是可用的。嵌入重新排名是一个单独的选择。安装/启动Ollama和 查询前显式下载模型： ```sh ollama pull qwen3-embedding:4b python3 "$PLUGIN_DIR/scripts/retrieve.py" "query terms" --vault "$VAULT" --rerank ``` 正常检索不需要任何Ollama请求。重新排序接受环回端点。 忽略代理，拒绝重定向，并在失败时退回到BM25。确切的 主题比赛获得排名提升；iso日期查询保持词法和 更喜欢匹配日期的笔记/相关的日期部分。看到 [获取详细信息](https://npmcn.com/package/%40soulwaxx/obsidian-second-brain/docs/setup.md#local-retrieval). ## 可选的专业 Claude Code支持 `@agent-obsidian-second-brain:wiki-vault`。对于Pi，可选 安装 `pi-subagents` 与 `pi install npm:pi-subagents`，然后请家长 运行 `obsidian-second-brain.wiki-vault`，或使用 `/run obsidian-second-brain.wiki-vault "your task"`。专家解决了问题 相同配置的保险库；它不要求父节点从那里开始。 包装专家都没有固定模型或努力。Claude Code 2.292 +添加 `/obsidian-second-brain:wiki-agent "your task"`:选择 **Vault代理工作** 在插件的 `/config` 请求设置 `low` 对于明确的委托 不改变父母的努力。默认值为 `inherit`;直接代理提及 绕过首选项。该插件的选项选择器需要Claude Code 2.1.271+。 Pi使用它现有的每个代理 `thinking` 重写而不是包设置。 看到 [代理配置](https://npmcn.com/package/%40soulwaxx/obsidian-second-brain/docs/setup.md#configure-the-vault-agent) 对于优先级, 模型限制和未经验证的实时客户端检查。没有子代理的Pi Runner仍然支持技能和生命周期。 ## 验证包 从仓库签出运行： ```sh npm run release:check npm test npm run test:release npm run test:package npm run test:pi-runtime -- --require-runtime claude plugin validate . bash tests/install-smoke.sh bash -n hooks/obsidian-session.sh tests/install-smoke.sh shellcheck tests/install-smoke.sh ``` 安装测试使用临时代理设置和一次性保管库，而不是 真实的配置文件，不发送模型提示。CI检查macOS/Linux与Node 26 和Python 3.14/3.15。使用传统的提交PR标题： `feat:` 释放未成年人 版本，主要版本的突破性更改，以及其他类型的补丁。完整代码 合并前进行检查；标题/正文编辑只运行元数据验证。后 压缩合并，发布验证合并树是否通过了PR - CI，冒烟测试 准备好的版本，并使用npm OIDC发布出处。没有 重复主测试矩阵或手动客户端验证门。 需要 **CI传递** 和 **公关职称通过** 在主规则集中。出版 拒绝直接推送和不匹配或过期的验证证据。看到 [CI / CD维护](https://npmcn.com/package/%40soulwaxx/obsidian-second-brain/docs/ci-cd.md) 对于推出，锁定释放工具，临时 关键阻断审计策略，以及部分发布标签的恢复。 ## 常见问题 ### @soulwaxx/obsidian-second-brain 是什么？ OKF wiki技能和vault范围的生命周期集成，用于Obsidian、Pi和Claude Code ### 如何安装 @soulwaxx/obsidian-second-brain？ 在项目目录运行 npm install @soulwaxx/obsidian-second-brain，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 obsidian-second-brain，可以用 npx obsidian-second-brain 直接运行。 ### @soulwaxx/obsidian-second-brain 支持 TypeScript 吗？ 该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/soulwaxx\_\_obsidian-second-brain 是否存在。 ### @soulwaxx/obsidian-second-brain 支持 ESM 还是 CommonJS？ 以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。 ### @soulwaxx/obsidian-second-brain 需要什么版本的 Node\.js？ package\.json 的 engines 字段要求 Node\.js \>=18\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。 ### @soulwaxx/obsidian-second-brain 可以商用吗？ @soulwaxx/obsidian-second-brain 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。 ### @soulwaxx/obsidian-second-brain 还在维护吗？ 最新版本 3\.4\.0 发布于 2026/11/02（1 天前）；至今共发布 22 个版本，其中过去 12 个月发布了 22 个；首次发布于 2026/10/03。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。