# 上游关键更新同步

本次选择性同步 [Ar9av/obsidian-wiki v2026.10.4](https://github.com/Ar9av/obsidian-wiki/releases/tag/v2026.10.4)，固定提交 `4f457e154653756b04802d5aeb25c20f42b4770c`。这是核心维护能力的移植，不表示本分支完整等同于该版本。来源哈希、移植的 CLI 函数和未纳入的测试范围记录在 `upstream-sync.json`。

| 纳入能力 | 实际作用 |
| --- | --- |
| `cache-check` / `cache-update` / `cache-hash` | 用内容哈希识别变化；manifest 锁和原子写入；兼容列表/字典及旧哈希格式 |
| `projects-check` | 按已记录提交检查项目资料是否落后 |
| `memory` | 统一维护 index、log、hot；提供只读检查、显式迁移及备份 |
| `lint` / `graph-analyse` | 正确区分不同项目中的同名页，解析相对链接，忽略代码示例里的伪链接；检查结构、时效与来源信息 |
| `staging` | 暂存晋升前校验已审阅的 staged/live 内容哈希；冲突时退出并保留文件 |

同步了 `llm-wiki`、`wiki-ingest`、`wiki-lint`、`wiki-stage-commit` 的相关执行指引，详细协议见 `.skills/llm-wiki/references/CORE-MAINTENANCE.md`。图分析是显式调用的维护工具，不接入远程问答或自动调度。

## 本地兼容

- 保留 `~/.obsidian-wiki/config`、现有 setup、file-index、bot-view 和 MCP 命令。
- 保留 `_sources/archive` / `_sources/catalog`、原文件索引、结构化产品字段及 ACL。知识页遍历排除原始资料、元数据、收件箱和导出副本；归档文件仍可被引用。
- `cache-update` 未传 `--pages` 时保留已有页面关联；显式传入时替换 `pages_produced`。自定义元数据需在同一个 manifest 锁内读取、合并并原子写回。registry 和 SQLite 索引仍由本地 ingest 流程维护。
- 未改动已有知识页面、manifest、registry、SQLite 或 index/hot；未启动 Wiki MCP，未修改独立订单项目。
- 未导入上游 HTTP 服务、MCP 2.x 依赖、会话 hooks、session brain、GraphRAG 查询链路或全量数据迁移。

## 使用与迁移

从本项目虚拟环境执行，避免误用系统中另一个版本：

```bash
.venv/bin/python -m obsidian_wiki lint /path/to/vault --json
.venv/bin/python -m obsidian_wiki memory status --vault /path/to/vault --json
.venv/bin/python -m obsidian_wiki memory migrate --vault /path/to/vault --json
.venv/bin/python -m obsidian_wiki staging list --vault /path/to/vault --json
```

这些检查不重写知识库。`memory migrate` 默认只预览；只有明确决定迁移数据格式后才加 `--apply`，届时先备份旧 index/hot。未迁移的库继续保留现有布局，使用共享锁合并必要修改。框架升级本身不触发该迁移。

lint 的旧库模式把 trust ledger 缺失等问题报告为警告。若以后启用严格审阅，需要独立设计实际审阅流程，不能为了消除警告伪造置信度。自定义归档目录可加入 `.okignore`，其非标准引用需单独核查。

## 验证与下次同步

```bash
uv sync --extra mcp --group dev
PYTHONPATH="$PWD" .venv/bin/python -m pytest tests -q
```

测试包括原有文件检索、ACL、MCP query/ingest 和运维回归，以及本次核心模块的上游测试；另有本地兼容测试验证归档排除、引用解析与 manifest 字段保留。测试使用临时知识库，不启动实际服务。

本次验证结果：**609 项测试通过**。实际知识库只执行了 `memory status` 只读检查，index/hot/log、manifest、registry、SQLite 的前后 SHA-256 一致。Wiki MCP 保持 inactive，独立订单 MCP 保持 active。

下次以 `upstream-sync.json` 的提交和源文件哈希作比较基线，逐模块检查新提交，再重放列出的本地适配。不要直接覆盖 `.skills`、运行上游 setup、切换服务依赖或批量改写知识库。上游未纳入模块的测试明确列入排除清单，不能把它们的缺席解释为整版上游已通过验证。