Question 1

如何修复在从 WSL 中使用的、由 Windows 创建的 Git 仓库中出现的 checkpoint COMMITTED_MODE_MISMATCH？

Accepted Answer

升级到 claude-obsidian v2.2.0 或更高版本。PR #177 使 `checkpoint` 遵循 `core.filemode=false`，因此当持久化的事务结果包含可执行的 POSIX 权限模式时，它不再要求 Git 模式 `100755`。升级后，请针对失败的操作重新运行 `checkpoint`。使用 `git config --get core.filemode` 验证仓库设置；对于由原生 Windows Git 创建或克隆的仓库，预期值为 `false`。请勿编辑 `changed-paths.json` 或使用 `git update-index --chmod=+x`，因为这些操作会伪造溯源信息，或创建 `checkpoint` 会拒绝的暂存状态。

Question 2

为什么 stop_status 会将超过 64 KiB 的已完成事务日志报告为不可读，以及为什么 `transaction recover` 无法清除该警告？

Accepted Answer

这是一个误报，由 `stop_status` 中 64 KiB 的读取上限导致。大小超过该限制的日志（journal）会在 JSON 解析之前被截断，因此带有 `"state": "complete"` 的有效日志会被计为不可读。推荐的 `claude-obsidian transaction recover` 无法清除它们，因为它只处理 `prepared`、`applying` 和 `rollback-failed` 状态的日志；已完成的日志会被有意跳过。

修复方法：升级到 `claude-obsidian` v2.2.0 或更高版本。PR #177 将日志读取上限提高到了 8 MiB。

在旧版本上的临时验证方法：

```python
import json
raw = open(journal_path, "rb").read()
print(len(raw), json.loads(raw)["state"])
```

如果输出以 `complete` 结尾，则在升级之前可以忽略该警告。对这些日志运行 `transaction recover` 是无操作（no-op）。

Question 3

如何修复 claude-obsidian 中由 `.raw/` 归档导致的 ambiguous-target lint 误报？

Accepted Answer

在 `claude_obsidian/lint_engine.py` 中，将 `.raw` 添加到 `_IGNORED_WALK_DIRS`：

```python
_IGNORED_WALK_DIRS = {
    ".git",
    ".obsidian",
    ".vault-meta",
    ".cache",
    ".pytest_cache",
    "__pycache__",
    "node_modules",
    ".raw",
}
```

然后重新运行：

```bash
python scripts/claude-obsidian.py lint --vault "$VAULT" --format markdown
```

这样可以防止已归档的捕获内容被当作 Obsidian 链接解析候选。Obsidian 会忽略以点号开头的文件夹，因此 `.raw/` 下的文件不应与 `wiki/sources/` 下的页面竞争。这个窄范围修复还会消除相关的 `stale_index_entries` 和 `orphans` 误报结果。来源（provenance）验证不受影响，因为它直接读取账本，而不是使用 `_walk_files()`。

一个更广泛的替代方案是跳过所有以点号开头的目录，使行为与 Obsidian 对所有隐藏文件夹的处理方式保持一致，但那是更大范围的行为变更。该问题报告于 claude-obsidian 2.1.0（引擎版本 1.1.1）。

Question 4

如何修复 Claude Code hook 错误 "NameError: name 'false' is not defined"？

Accepted Answer

在 Claude Code 2.1.49 中,命令钩子不支持 `hooks/hooks.json` 中单独的 `args` 字段。以 `"command": "python3"` 加 `args` 定义的钩子只会运行 `python3`,导致 Python 从 stdin 读取钩子的 JSON 负载,并在遇到小写的 `false` 时失败。

编辑 `hooks/hooks.json`,删除 `args` 数组,改用单个 `command` 字符串:

SessionStart:
`"command": "python3 \"${CLAUDE_PLUGIN_ROOT}/scripts/claude-obsidian.py\" hook session-start"`

Stop:
`"command": "python3 \"${CLAUDE_PLUGIN_ROOT}/scripts/claude-obsidian.py\" hook stop"`

保持原有的 `"type": "command"` 和 `"timeout"` 值不变,然后重启 Claude Code 或重新加载插件。适配器随后应能接收到 JSON 负载并以退出状态码 0 退出。尽管该 traceback 是非阻塞的,但在完成此更改之前,生命周期钩子不会运行。

Question 5

为什么 claude-obsidian lint 会对文件名中包含 %23（编码后的 #）的路径误报死链接？

Accepted Answer

这个误报是 3.0.0 之前版本的 lint 引擎中的一个 bug：`_parse_links()` 在拆分出 `#` 片段之前就对目标进行了 URL 解码，因此文件名中编码后的 `%23` 被误认为是片段分隔符，导致被截断的路径查找失败。修复方法：升级到 claude-obsidian v3.0.0 或更高版本（https://github.com/AgriciDaniel/claude-obsidian/releases/tag/v3.0.0）。该修复会从仍处于编码状态的目标中拆分出片段，并且只对路径解码一次，因此像 `[doc](../some%20folder%20%231/file.md)` 这样的链接能够解析到真实文件，不会再报告死链接。无需修改你的 Markdown —— 按照 RFC 3986 的百分号编码本来就是正确的。

claude-obsidian

项目简介

README 预览

常见问题 (5)

同类型项目

hermes-agent

firecrawl

go

markitdown