更新

.gitignore

@@ -28,7 +28,6 @@ app/.test-tmp-stream/
 /.codex
 /.agents
 /server/.spool
-/server/knowledge/tcm-ancient-books/
 /server/knowledge/tcm-ancient-books-index.json
 /server/knowledge/tcm-ancient-books-index/
 /server/.claude

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "server/knowledge/tcm-ancient-books"]
+	path = server/knowledge/tcm-ancient-books
+	url = https://github.com/xiaopangxia/TCM-Ancient-Books.git

server/knowledge/TCM_ANCIENT_BOOKS.md

@@ -1,13 +1,14 @@
 # 古籍参考库接入
 
-数据源：[xiaopangxia/TCM-Ancient-Books](https://github.com/xiaopangxia/TCM-Ancient-Books)，固定提交 `db0155dc7c42b9c6b3736896661f317c7110038f`。该提交有 701 个 TXT 文件。原仓库没有 LICENSE 文件或其他明确的再分发许可，因此本项目不复制原文到自身 Git 历史；由每个部署环境直接从原仓库安装。请在使用或对外分发前自行确认数据权利。
+数据源：[xiaopangxia/TCM-Ancient-Books](https://github.com/xiaopangxia/TCM-Ancient-Books)，作为 Git 子模块固定在提交 `db0155dc7c42b9c6b3736896661f317c7110038f`。该提交有 701 个 TXT 文件。拉取项目时初始化子模块，原文就会随项目检出。
 
 部署时先执行 `server/database/migrations/2026_10_08_tcm_ancient_book_sources.sql`，然后在项目根目录运行：
 
 ```bash
+git submodule update --init -- server/knowledge/tcm-ancient-books
 php server/scripts/install_tcm_ancient_books.php
 ```
 
-脚本将固定提交检出到 `server/knowledge/tcm-ancient-books/`，按 GB18030 读取 701 个原文文件，并建立 `server/knowledge/tcm-ancient-books-index.json` 及按需读取的 `server/knowledge/tcm-ancient-books-index/`。这些数据文件已被 Git 忽略。安装完成后重启 PHP 服务或工作进程，使索引生效。部署镜像若不运行此步骤，古籍检索不会启用；已有的倪海厦参考仍照常工作。
+安装脚本也会在子模块尚未初始化时自动初始化。它按 GB18030 读取 701 个原文文件，并建立 `server/knowledge/tcm-ancient-books-index.json` 及按需读取的 `server/knowledge/tcm-ancient-books-index/`。生成的索引文件已被 Git 忽略。安装完成后重启 PHP 服务或工作进程，使索引生效。部署镜像若不运行建索引步骤，古籍检索不会启用。
 
 索引保留每段的书名、篇名、原文件名和行号，模型只收到与患者病症词匹配的至多两条短原文。来源链接固定到上述提交的具体行。古籍只是文献参考，不能代替病历证据、现代临床判断、急症处理和医生审核。历史报告不自动补标古籍来源；新报告保存生成时实际传给模型的片段清单。

server/scripts/install_tcm_ancient_books.php

@@ -3,8 +3,7 @@
 declare(strict_types=1);
 
 // Run from the project checkout: php server/scripts/install_tcm_ancient_books.php
-// The upstream corpus is fetched directly into this deployment. Its source text
+// Initialize the pinned corpus submodule and build its local search index.
-// is intentionally not committed to this application's repository.
 
 require dirname(__DIR__) . '/vendor/autoload.php';
 
@@ -16,6 +15,7 @@ if (PHP_SAPI !== 'cli') {
 }
 
 $root = dirname(__DIR__) . '/knowledge/tcm-ancient-books';
+$projectRoot = dirname(__DIR__, 2);
 $indexPath = TcmAncientBooksReference::indexPath();
 
 function runGit(array $arguments): string
@@ -31,9 +31,19 @@ function runGit(array $arguments): string
 }
 
 try {
-    if (!is_dir($root)) {
+    if (!is_dir($root . '/.git') && !is_file($root . '/.git')) {
+        if (is_file($projectRoot . '/.gitmodules')
+            && (is_dir($projectRoot . '/.git') || is_file($projectRoot . '/.git'))) {
+            runGit(['-C', $projectRoot, 'submodule', 'update', '--init', '--', 'server/knowledge/tcm-ancient-books']);
+        } else {
             runGit(['clone', '--depth', '1', TcmAncientBooksReference::REPOSITORY_URL . '.git', $root]);
         }
+    }
+    $checkoutRoot = runGit(['-C', $root, 'rev-parse', '--show-toplevel']);
+    if (strtolower(str_replace('\\', '/', (string) realpath($checkoutRoot)))
+        !== strtolower(str_replace('\\', '/', (string) realpath($root)))) {
+        throw new RuntimeException('Corpus checkout is missing or points to the parent repository');
+    }
     $head = runGit(['-C', $root, 'rev-parse', 'HEAD']);
     if ($head !== TcmAncientBooksReference::COMMIT) {
         runGit(['-C', $root, 'fetch', '--depth', '1', 'origin', TcmAncientBooksReference::COMMIT]);