@sanqianx/project-knowledge 4.6.1

package/_site/_test/kb-framework-test.js

@@ -0,0 +1,57 @@
+// Run: node _site/_test/kb-framework-test.js
+
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const temp = fs.mkdtempSync(path.join(os.tmpdir(), `kb-framework-${process.pid}-`));
+process.env.KB_DATA_DIR = path.join(temp, 'data');
+process.env.KB_SKIP_MIGRATION = '1';
+require('../lib/data-dir')._resetCache();
+const framework = require('../lib/kb-framework');
+
+(() => {
+  try {
+    const fresh = path.join(temp, 'knowledge', 'fresh');
+    const initialized = framework.initProjectDirs('fresh-project', fresh);
+    assert.strictEqual(initialized.lazy, true);
+    assert.deepStrictEqual(initialized.created, []);
+    assert.deepStrictEqual(fs.readdirSync(fresh), [], 'fresh import must not create guessed/TODO Markdown or empty collection indexes');
+    const second = framework.initProjectDirs('fresh-project', fresh);
+    assert.deepStrictEqual(second.created, [], 'lazy directory declaration should be idempotent');
+    assert.strictEqual(fs.existsSync(path.join(process.env.KB_DATA_DIR, '_ai', 'fresh-project')), false, 'unused AI workspace must not be created');
+
+    const legacy = path.join(temp, 'knowledge', 'legacy');
+    fs.mkdirSync(path.join(legacy, '_ai', 'runs'), { recursive: true });
+    fs.mkdirSync(path.join(legacy, 'commits'), { recursive: true });
+    fs.mkdirSync(path.join(legacy, 'features'), { recursive: true });
+    fs.writeFileSync(path.join(legacy, 'README.md'), '# Legacy Project\n\nVerified legacy overview.\n', 'utf8');
+    fs.writeFileSync(path.join(legacy, 'project-goal.md'), '# Legacy Goal\n\nA verified migrated goal.\n', 'utf8');
+    fs.writeFileSync(path.join(legacy, 'project-analysis.md'), '# Legacy Analysis\n\nA verified architecture fact.\n', 'utf8');
+    fs.writeFileSync(path.join(legacy, 'commits', 'old.md'), '# Old Commit\n\nVerified old change.\n', 'utf8');
+    fs.writeFileSync(path.join(legacy, '_ai', 'runs', 'old.json'), '{"runId":"old"}\n', 'utf8');
+    const migrated = framework.migrateToFramework({ slug: 'legacy-project', kbPath: legacy });
+    assert.strictEqual(migrated.ok, true);
+    assert(fs.existsSync(path.join(legacy, 'GOAL.md')));
+    assert(fs.existsSync(path.join(legacy, 'ARCHITECTURE.md')));
+    assert(fs.existsSync(path.join(legacy, 'changes', 'legacy-change-01.md')));
+    assert(fs.existsSync(path.join(legacy, 'changes', '00-index.md')));
+    assert(fs.existsSync(path.join(legacy, 'modules', '00-index.md')));
+    assert.strictEqual(fs.existsSync(path.join(legacy, '_ai')), false, 'internal AI data must be removed from user knowledge root after migration');
+    assert(fs.existsSync(path.join(process.env.KB_DATA_DIR, '_ai', 'legacy-project', 'runs', 'old.json')), 'legacy AI run should be preserved internally');
+    const allMarkdown = [];
+    const walk = current => {
+      for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+        const target = path.join(current, entry.name);
+        if (entry.isDirectory()) walk(target);
+        else if (entry.name.endsWith('.md')) allMarkdown.push(fs.readFileSync(target, 'utf8'));
+      }
+    };
+    walk(legacy);
+    assert(!allMarkdown.some(text => /TODO: confirm|TODO: summarize/.test(text)), 'migration must not introduce TODO facts');
+    console.log('kb-framework-test PASS');
+  } finally {
+    fs.rmSync(temp, { recursive: true, force: true });
+  }
+})();

package/_site/_test/kbpath-follow-test.js

@@ -0,0 +1,63 @@
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { StorageLayout } = require('../lib/storage-layout');
+const { SettingsStore } = require('../lib/settings-store');
+const { ProjectRegistryStore } = require('../lib/project-registry-store');
+const { ProjectStore } = require('../lib/project-store');
+
+const dataDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pkb-kbpath-v2-'));
+const projectId = 'project-kbpath-follow';
+const oldKnowledgePath = path.join(dataDir, 'knowledge-old');
+const newKnowledgePath = path.join(dataDir, 'knowledge-new');
+process.env.KB_DATA_DIR = dataDir;
+require('../lib/data-dir')._resetCache();
+
+(async () => {
+  try {
+    fs.mkdirSync(oldKnowledgePath, { recursive: true });
+    fs.mkdirSync(newKnowledgePath, { recursive: true });
+    const layout = new StorageLayout({ dataDir });
+    const settingsStore = new SettingsStore({ layout });
+    const registryStore = new ProjectRegistryStore({ layout });
+    const projectStore = new ProjectStore({ layout });
+    await settingsStore.initialize({ knowledge: { rootPath: path.join(dataDir, 'future') } });
+    await registryStore.initialize();
+    await projectStore.create(projectId, { displayName: 'KB path follow', storageName: 'kbpath', repoPath: dataDir, knowledgePath: oldKnowledgePath });
+    await registryStore.add(projectId, { displayNameSnapshot: 'KB path follow' });
+
+    const runner = require('../lib/claude-cli-runner');
+    const started = runner.startChatSession({
+      slug: projectId,
+      projectPath: dataDir,
+      kbPath: oldKnowledgePath,
+      aiProfile: { id: 'test', implementation: 'claude-code-agent', model: 'test-model' },
+    });
+    const recordPath = layout.getRuntimePath('claude-sessions', projectId, `${started.sessionId}.json`);
+    const persisted = JSON.parse(fs.readFileSync(recordPath, 'utf8'));
+    persisted.claudeSessionId = 'stale-conversation-id';
+    persisted.events.push({ type: 'claude/user-prompt', text: 'old conversation' });
+    fs.writeFileSync(recordPath, `${JSON.stringify(persisted, null, 2)}\n`, 'utf8');
+
+    await projectStore.updateConfig(projectId, { knowledgePath: newKnowledgePath }, { allowKnowledgePath: true });
+    delete require.cache[require.resolve('../lib/claude-cli-runner')];
+    const restoredRunner = require('../lib/claude-cli-runner');
+    const events = [];
+    restoredRunner.subscribe(started.sessionId, event => events.push(event));
+    const restored = restoredRunner.getSession(started.sessionId);
+    assert.strictEqual(restored.kbPath, newKnowledgePath);
+    assert.strictEqual(restored.claudeSessionId, null);
+    assert.strictEqual(restored.historyCleared, true);
+    assert.strictEqual(restored.turns, 0);
+    assert(events.some(event => event.type === 'claude/kbpath-updated' && event.fromKbPath === oldKnowledgePath && event.toKbPath === newKnowledgePath));
+    assert(!restored.outputBuffer.some(event => event.type === 'claude/user-prompt'), 'stale conversation events must be cleared');
+
+    const persistedAfter = JSON.parse(fs.readFileSync(recordPath, 'utf8'));
+    assert.strictEqual(persistedAfter.kbPath, newKnowledgePath);
+    assert.strictEqual(persistedAfter.claudeSessionId, null);
+    console.log('kbpath-follow-test PASS');
+  } finally {
+    fs.rmSync(dataDir, { recursive: true, force: true });
+  }
+})().catch(error => { console.error(error); process.exitCode = 1; });

package/_site/_test/knowledge-db-test.js

@@ -0,0 +1,144 @@
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { KnowledgeDatabase, sqlString, inPredicate } = require('../lib/knowledge-db');
+const { LocalEmbeddingService, QUERY_PREFIX } = require('../lib/embedding-service');
+const { EMBEDDING_DIMENSIONS, sha256 } = require('../lib/knowledge-schema');
+const { MarkdownKnowledgeIndexer, chunkMarkdown } = require('../lib/markdown-knowledge-indexer');
+
+function vectorAt(index) {
+  const vector = new Array(EMBEDDING_DIMENSIONS).fill(0);
+  vector[index] = 1;
+  return vector;
+}
+
+(async () => {
+  const temp = fs.mkdtempSync(path.join(os.tmpdir(), 'knowledge-db-test-'));
+  const db = new KnowledgeDatabase({ dbPath: path.join(temp, 'knowledge.lancedb') });
+  try {
+    assert.equal(sqlString("space'o"), "'space''o'");
+    assert.equal(inPredicate('space_id', ['a', 'a', 'b']), "space_id IN ('a', 'b')");
+    assert.throws(() => inPredicate('space_id', []), /must not be empty/);
+
+    const created = await db.replaceEntry('personal:alpha', 'modules/auth.md', [
+      {
+        chunkOrder: 0,
+        title: '登录设计',
+        chunkText: '系统使用短期访问令牌和可轮换刷新令牌。',
+        vector: vectorAt(0),
+        tags: ['auth'],
+        sourcePaths: ['src/auth.js'],
+        sourceCommit: 'abc123',
+      },
+      {
+        chunkOrder: 1,
+        title: '登录设计',
+        chunkText: '退出登录会撤销刷新令牌。',
+        vector: vectorAt(1),
+        sourceCommit: 'abc123',
+      },
+    ]);
+    assert.equal(created.action, 'created');
+    assert.equal(await db.count(), 2);
+
+    const same = await db.replaceEntry('personal:alpha', 'modules/auth.md', [
+      { chunkOrder: 0, title: '登录设计', chunkText: '系统使用短期访问令牌和可轮换刷新令牌。', vector: vectorAt(0), tags: ['auth'], sourcePaths: ['src/auth.js'], sourceCommit: 'abc123' },
+      { chunkOrder: 1, title: '登录设计', chunkText: '退出登录会撤销刷新令牌。', vector: vectorAt(1), sourceCommit: 'abc123' },
+    ]);
+    assert.equal(same.action, 'unchanged');
+
+    const updated = await db.replaceEntry('personal:alpha', 'modules/auth.md', [
+      { chunkOrder: 0, title: '登录设计', chunkText: '系统使用短期访问令牌。', vector: vectorAt(0), sourceCommit: 'def456' },
+    ]);
+    assert.equal(updated.action, 'updated');
+    assert.equal(updated.deleted, 1);
+    assert.equal(await db.count(), 1);
+
+    await db.replaceEntry('personal:beta', 'GOAL.md', [
+      { chunkOrder: 0, title: '目标', chunkText: '支付服务负责对账。', vector: vectorAt(1), sourceCommit: '999999' },
+    ]);
+    assert.equal(await db.count(['personal:alpha']), 1);
+    const scoped = await db.vectorSearch(vectorAt(0), { spaceIds: ['personal:alpha'], limit: 5 });
+    assert.equal(scoped.length, 1);
+    assert.equal(scoped[0].space_id, 'personal:alpha');
+    assert.deepEqual(scoped[0].tags, []);
+    assert.equal(scoped[0].content_hash, sha256('系统使用短期访问令牌。'));
+
+    const initialIndexes = await db.ensureSearchIndexes();
+    assert.equal(initialIndexes.ftsSchemaVersion, 2);
+    assert.equal(initialIndexes.ftsUpgradeRequired, false);
+    assert.equal(db.maintenanceState().ftsSchemaVersion, 2);
+    const keyword = await db.fullTextSearch('短期访问令牌', { spaceIds: ['personal:alpha'], limit: 5 });
+    assert.equal(keyword.length, 1);
+    const hybrid = await db.hybridSearch({ text: '短期访问令牌', vector: vectorAt(0), spaceIds: ['personal:alpha'], limit: 5 });
+    assert.equal(hybrid.length, 1);
+    assert.deepEqual(hybrid[0].match_channels.sort(), ['keyword', 'semantic']);
+
+    assert.equal((await db.deleteEntry('personal:alpha', 'modules/auth.md')).deleted, 1);
+    assert.equal((await db.deleteSpace('personal:beta')).deleted, 1);
+    assert.equal(await db.count(), 0);
+
+    let seenInput = null;
+    let seenOptions = null;
+    const embeddings = new LocalEmbeddingService({
+      remoteHost: 'https://models.example.test/',
+      pipelineFactory: async (task, model, options) => {
+        assert.equal(task, 'feature-extraction');
+        assert.equal(model, 'Xenova/bge-small-zh-v1.5');
+        assert.equal(options.dtype, 'fp32');
+        return async (input, embedOptions) => {
+          seenInput = input;
+          seenOptions = embedOptions;
+          return { data: Float32Array.from(vectorAt(2)) };
+        };
+      },
+    });
+    const embedded = await embeddings.embedQuery('登录怎么做');
+    assert.equal(embedded.length, EMBEDDING_DIMENSIONS);
+    assert.equal(seenInput, `${QUERY_PREFIX}登录怎么做`);
+    assert.deepEqual(seenOptions, { pooling: 'cls', normalize: true });
+    assert.equal(embeddings.status().loaded, true);
+    assert.equal(embeddings.status().remoteHost, 'https://models.example.test/');
+
+    const sections = chunkMarkdown('# 标题\n\n第一段。\n\n## 细节\n\n第二段。', { maxChars: 20, overlapChars: 2 });
+    assert.ok(sections.length >= 2);
+    assert.deepEqual(sections.at(-1).headingPath, ['标题', '细节']);
+
+    const markdownRoot = path.join(temp, 'legacy-markdown');
+    fs.mkdirSync(path.join(markdownRoot, 'modules'), { recursive: true });
+    fs.writeFileSync(path.join(markdownRoot, 'GOAL.md'), '# 项目目标\n\n建立可靠的支付知识库。\n', 'utf8');
+    fs.writeFileSync(path.join(markdownRoot, 'modules', 'pay.md'), '# 支付模块\n\n对账任务每天运行。\n', 'utf8');
+    fs.writeFileSync(path.join(markdownRoot, 'modules', '00-index.md'), '# Modules Index\n\nTags: duplicated, derived\n', 'utf8');
+    const deterministicEmbedder = {
+      embedPassage: async text => text.includes('对账') ? vectorAt(3) : vectorAt(4),
+    };
+    const indexer = new MarkdownKnowledgeIndexer({ database: db, embedder: deterministicEmbedder });
+    await db.replaceEntry('personal:migrated', 'modules/00-index.md', [
+      { chunkOrder: 0, title: 'Legacy index', chunkText: 'duplicated derived tags', vector: vectorAt(5) },
+    ]);
+    const firstIndex = await indexer.indexDirectory({ kbPath: markdownRoot, spaceId: 'personal:migrated', sourceProjectId: 'pay' });
+    assert.equal(firstIndex.files, 2);
+    assert.equal(firstIndex.indexed, 2);
+    assert.equal(firstIndex.deletedEntries, 1, 'previously indexed derived files should be removed as stale');
+    assert(!firstIndex.results.some(item => item.entryId.endsWith('00-index.md')), 'derived indexes must not be embedded');
+    assert.equal(firstIndex.maintenance.optimized, false, 'small updates must not optimize on every commit');
+    const secondIndex = await indexer.indexDirectory({ kbPath: markdownRoot, spaceId: 'personal:migrated', sourceProjectId: 'pay' });
+    assert.equal(secondIndex.unchanged, 2);
+    db.optimizeOperationsThreshold = 1;
+    fs.unlinkSync(path.join(markdownRoot, 'GOAL.md'));
+    const thirdIndex = await indexer.indexDirectory({ kbPath: markdownRoot, spaceId: 'personal:migrated', sourceProjectId: 'pay' });
+    assert.equal(thirdIndex.deletedEntries, 1);
+    assert.equal(thirdIndex.maintenance.optimized, true, 'maintenance should run after the configured mutation threshold');
+    assert.equal(db.maintenanceState().pendingOperations, 0);
+    assert.deepEqual(await db.entryIds('personal:migrated'), ['modules/pay.md']);
+
+    console.log('knowledge-db-test: PASS');
+  } finally {
+    await db.close();
+    fs.rmSync(temp, { recursive: true, force: true });
+  }
+})().catch(error => {
+  console.error(error);
+  process.exit(1);
+});

package/_site/_test/knowledge-language-control-test.js

@@ -0,0 +1,170 @@
+// _site/_test/knowledge-language-control-test.js
+//
+// T11: knowledge output language controls. Verifies:
+//   - import accepts knowledgeLanguage ('zh-CN' / 'en-US');
+//   - per-project PATCH updates knowledgeLanguage;
+//   - the value is persisted in config.knowledgeLanguage;
+//   - the value is what the next analyzer invocation would see (we
+//     verify it via the public state API which surfaces the same
+//     config object the reconciler reads);
+//   - changing language does NOT silently rewrite historical knowledge;
+//   - invalid values are rejected with 400.
+
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+const { spawnServer } = require('./helpers/spawn-server');
+
+const ROOT = path.resolve(__dirname, '..', '..');
+const sitePort = 7990 + (process.pid % 200);
+const dataDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pk-knowledge-language-' + process.pid + '-'));
+const repo = fs.mkdtempSync(path.join(os.tmpdir(), 'pk-knowledge-language-repo-' + process.pid + '-'));
+
+function git(args) {
+  const result = spawnSync('git', ['-C', repo, ...args], {
+    encoding: 'utf8', windowsHide: true,
+    env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+  });
+  if (result.status !== 0) throw new Error(result.stderr || `git ${args.join(' ')} failed: ${result.status}`);
+  return String(result.stdout || '').trim();
+}
+
+async function serverFetch(url, init, timeoutMs = 10000) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const response = await fetch(url, { ...init, signal: controller.signal });
+    const text = await response.text();
+    return { status: response.status, body: text ? JSON.parse(text) : {} };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+(async () => {
+  git(['init', '-q', '-b', 'main']);
+  git(['config', 'user.email', 'kl@example.local']);
+  git(['config', 'user.name', 'Knowledge Language']);
+  fs.writeFileSync(path.join(repo, 'README.md'), '# kl\n');
+  git(['add', 'README.md']);
+  git(['commit', '-q', '-m', 'baseline']);
+  const knowledgeRoot = path.join(dataDir, 'knowledge');
+  fs.mkdirSync(knowledgeRoot, { recursive: true });
+  const server = spawnServer({
+    root: ROOT, port: sitePort, dataDir, tag: 'knowledge-language',
+    extraEnv: { KB_AUTOMATION_FAKE_CLAUDE: '1', KB_EMBEDDING_FAKE: '1', KB_SKIP_MIGRATION: '1' },
+  });
+  try {
+    // waitForServer-equivalent
+    for (let attempt = 0; attempt < 100; attempt += 1) {
+      try {
+        const r = await serverFetch(`http://127.0.0.1:${sitePort}/api/health`);
+        if (r.body.ok) break;
+      } catch {}
+      await new Promise(resolve => setTimeout(resolve, 100));
+    }
+    await serverFetch(`http://127.0.0.1:${sitePort}/api/settings`, {
+      method: 'PATCH', headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ knowledge: { rootPath: knowledgeRoot } }),
+    });
+    await serverFetch(`http://127.0.0.1:${sitePort}/api/ai-profiles`, {
+      method: 'PUT', headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({
+        schema: 'ai-profiles/v1', defaultProfileId: 'fake',
+        profiles: [{ id: 'fake', name: 'Fake', enabled: true, vendor: 'anthropic', model: 'fake', apiKeyUpdate: { mode: 'replace', value: 'k' } }],
+      }),
+    });
+
+    // Case 1: import with zh-CN (default)
+    let r = await serverFetch(`http://127.0.0.1:${sitePort}/api/projects/import`, {
+      method: 'POST', headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ localPath: repo, aiProfileId: 'fake', knowledgeLanguage: 'zh-CN' }),
+    });
+    assert.strictEqual(r.status, 201, JSON.stringify(r.body));
+    assert.strictEqual(r.body.config.knowledgeLanguage, 'zh-CN');
+    const PROJECT_ID = r.body.projectId;
+
+    // Case 2: import with en-US
+    const repo2 = fs.mkdtempSync(path.join(os.tmpdir(), 'pk-kl-repo2-' + process.pid + '-'));
+    const git2 = (args) => git(['-C', repo2, ...args]);
+    git2(['init', '-q', '-b', 'main']);
+    git2(['config', 'user.email', 'kl2@example.local']);
+    git2(['config', 'user.name', 'KL2']);
+    fs.writeFileSync(path.join(repo2, 'README.md'), '# en\n');
+    git2(['add', 'README.md']);
+    git2(['commit', '-q', '-m', 'baseline']);
+    r = await serverFetch(`http://127.0.0.1:${sitePort}/api/projects/import`, {
+      method: 'POST', headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ localPath: repo2, aiProfileId: 'fake', knowledgeLanguage: 'en-US' }),
+    });
+    assert.strictEqual(r.status, 201);
+    assert.strictEqual(r.body.config.knowledgeLanguage, 'en-US');
+    fs.rmSync(repo2, { recursive: true, force: true });
+
+    // Case 3: invalid language rejected
+    r = await serverFetch(`http://127.0.0.1:${sitePort}/api/projects/import`, {
+      method: 'POST', headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ localPath: repo2, aiProfileId: 'fake', knowledgeLanguage: 'xx-INVALID' }),
+    });
+    assert.strictEqual(r.status, 400);
+    assert.strictEqual(r.body.error.code, 'INVALID_ARGUMENT');
+
+    // Case 4: per-project PATCH updates knowledgeLanguage
+    r = await serverFetch(`http://127.0.0.1:${sitePort}/api/projects/${PROJECT_ID}`, {
+      method: 'PATCH', headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ knowledgeLanguage: 'en-US' }),
+    });
+    assert.strictEqual(r.status, 200, JSON.stringify(r.body));
+    assert.strictEqual(r.body.config.knowledgeLanguage, 'en-US');
+    // Verify state-side persists
+    const readBack = await serverFetch(`http://127.0.0.1:${sitePort}/api/projects/${PROJECT_ID}`, undefined);
+    assert.strictEqual(readBack.body.project.config.knowledgeLanguage, 'en-US');
+
+    // Case 5: invalid value via PATCH also rejected
+    r = await serverFetch(`http://127.0.0.1:${sitePort}/api/projects/${PROJECT_ID}`, {
+      method: 'PATCH', headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ knowledgeLanguage: 'klingon' }),
+    });
+    assert.strictEqual(r.status, 400);
+
+    // Case 6: project status surfaces knowledgeLanguage in the public state.
+    // The CommitReconciler reads config.knowledgeLanguage via projectStore,
+    // so anything the UI sees the analyzer also sees.
+    const stateR = await serverFetch(`http://127.0.0.1:${sitePort}/api/state`, undefined);
+    assert.strictEqual(stateR.status, 200);
+    const project = stateR.body.projects.find(p => p.projectId === PROJECT_ID);
+    assert(project, 'project must appear in /api/state');
+    assert.strictEqual(project.config.knowledgeLanguage, 'en-US');
+
+    // Case 7: changing language does NOT silently rewrite historical files.
+    // We snapshot the knowledge directory before and after a language flip;
+    // the existing files (if any) must remain identical and only NEW
+    // commits should produce output under the new language.
+    const knowledgePath = readBack.body.project.config.knowledgePath;
+    fs.mkdirSync(knowledgePath, { recursive: true });
+    const marker = path.join(knowledgePath, 'marker.txt');
+    fs.writeFileSync(marker, 'do-not-touch\n');
+    const mtimeBefore = fs.statSync(marker).mtimeMs;
+    const contentBefore = fs.readFileSync(marker, 'utf8');
+    await new Promise(resolve => setTimeout(resolve, 20));
+    r = await serverFetch(`http://127.0.0.1:${sitePort}/api/projects/${PROJECT_ID}`, {
+      method: 'PATCH', headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ knowledgeLanguage: 'zh-CN' }),
+    });
+    assert.strictEqual(r.status, 200);
+    assert(fs.existsSync(marker), 'historical knowledge files must not be deleted by a language change');
+    assert.strictEqual(fs.readFileSync(marker, 'utf8'), contentBefore, 'historical content must remain intact');
+    assert.strictEqual(fs.statSync(marker).mtimeMs, mtimeBefore, 'historical files must not be touched');
+  } finally {
+    server.child.kill();
+    await new Promise(resolve => server.child.once('exit', resolve));
+    fs.rmSync(dataDir, { recursive: true, force: true });
+    fs.rmSync(repo, { recursive: true, force: true });
+  }
+  console.log('knowledge-language-control-test PASS');
+})().catch(error => {
+  console.error(error.stack || error.message);
+  process.exit(1);
+});

package/_site/_test/knowledge-maintenance-test.js

@@ -0,0 +1,40 @@
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { StorageLayout } = require('../lib/storage-layout');
+const { ProjectRegistryStore } = require('../lib/project-registry-store');
+const { ProjectStore } = require('../lib/project-store');
+const { IndexService } = require('../lib/index-service');
+
+(async () => {
+  const temp = fs.mkdtempSync(path.join(os.tmpdir(), 'knowledge-maintenance-v2-'));
+  const layout = new StorageLayout({ dataDir: path.join(temp, 'data') });
+  const registry = new ProjectRegistryStore({ layout });
+  const projects = new ProjectStore({ layout });
+  await registry.initialize();
+  const target = layout.getIndexPath();
+  fs.mkdirSync(target, { recursive: true });
+  fs.writeFileSync(path.join(target, 'version.txt'), 'old-index', 'utf8');
+  const adapter = {
+    validationOk: false,
+    async buildFull({ targetPath }) {
+      fs.mkdirSync(targetPath, { recursive: true });
+      fs.writeFileSync(path.join(targetPath, 'version.txt'), 'new-index', 'utf8');
+    },
+    async validateIndex(candidate) {
+      return { ok: this.validationOk, marker: fs.readFileSync(path.join(candidate, 'version.txt'), 'utf8') };
+    },
+  };
+  const service = new IndexService({ layout, registryStore: registry, projectStore: projects, adapter });
+  await assert.rejects(service.fullRebuild({ operationId: 'op-validation-failure' }), error => error.code === 'DATA_CORRUPT');
+  assert.strictEqual(fs.readFileSync(path.join(target, 'version.txt'), 'utf8'), 'old-index', 'failed validation must leave the live index untouched');
+  assert(!fs.existsSync(path.join(path.dirname(target), '.knowledge.rebuild.op-validation-failure')));
+
+  adapter.validationOk = true;
+  const rebuilt = await service.fullRebuild({ operationId: 'op-valid-rebuild' });
+  assert.strictEqual(fs.readFileSync(path.join(target, 'version.txt'), 'utf8'), 'new-index');
+  assert(rebuilt.backup && fs.existsSync(rebuilt.backup));
+  assert.strictEqual(fs.readFileSync(path.join(rebuilt.backup, 'version.txt'), 'utf8'), 'old-index', 'atomic swap must retain the previous live index');
+  console.log('knowledge-maintenance-test: PASS');
+})().catch(error => { console.error(error); process.exitCode = 1; });

package/_site/_test/knowledge-migration-test.js

@@ -0,0 +1,75 @@
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { StorageLayout } = require('../lib/storage-layout');
+const { SettingsStore } = require('../lib/settings-store');
+const { ProjectStore } = require('../lib/project-store');
+const { MigrationService } = require('../lib/migration-service');
+const { KnowledgeDatabase } = require('../lib/knowledge-db');
+const { EMBEDDING_DIMENSIONS } = require('../lib/knowledge-schema');
+
+(async () => {
+  const dataDir = fs.mkdtempSync(path.join(os.tmpdir(), 'knowledge-migration-v2-'));
+  const oldKnowledgeRoot = path.join(dataDir, 'old-knowledge');
+  const fixedKnowledgePath = path.join(oldKnowledgeRoot, 'api-fixed');
+  const legacyIndex = path.join(dataDir, 'knowledge.lancedb');
+  fs.mkdirSync(fixedKnowledgePath, { recursive: true });
+  fs.writeFileSync(path.join(fixedKnowledgePath, 'GOAL.md'), '# API goal\n\nAuthoritative Markdown remains external.\n', 'utf8');
+  fs.writeFileSync(path.join(dataDir, 'projects.json'), JSON.stringify({
+    api: {
+      displayName: 'API', localPath: dataDir, gitPath: dataDir, kbPath: fixedKnowledgePath,
+      trackingStartCommit: 'track-before', lastAnalyzedCommit: 'commit-before', enabled: true,
+    },
+  }, null, 2));
+  fs.writeFileSync(path.join(dataDir, 'knowledge-store.json'), JSON.stringify({ rootPath: oldKnowledgeRoot, configured: true }));
+  fs.writeFileSync(path.join(dataDir, 'ai-profiles.json'), JSON.stringify({ schema: 'ai-profiles/v1', profiles: [{ id: 'primary', apiKey: 'migration-secret-value' }] }));
+  fs.writeFileSync(path.join(dataDir, 'logging.json'), JSON.stringify({ levels: ['debug', 'info', 'error'], retentionDays: 0, maxTotalSizeMB: 128 }));
+  fs.writeFileSync(path.join(dataDir, '.hook-trigger-errors.log'), '2026-01-01 legacy hook error\n', 'utf8');
+
+  const vector = new Array(EMBEDDING_DIMENSIONS).fill(0);
+  vector[9] = 1;
+  const oldDatabase = new KnowledgeDatabase({ dbPath: legacyIndex });
+  await oldDatabase.replaceEntry('project:api', 'GOAL.md', [{ chunkOrder: 0, title: 'Legacy index', chunkText: 'A migrated derived row.', vector }]);
+  await oldDatabase.close();
+  const oldIndexRows = await (async () => {
+    const db = new KnowledgeDatabase({ dbPath: legacyIndex });
+    try { return await db.count(); } finally { await db.close(); }
+  })();
+
+  const layout = new StorageLayout({ dataDir });
+  const migration = new MigrationService({
+    layout,
+    legacyDataDir: dataDir,
+    indexValidator: async candidate => {
+      const db = new KnowledgeDatabase({ dbPath: candidate });
+      try { await db.open(); return { ok: (await db.count()) === oldIndexRows }; }
+      finally { await db.close(); }
+    },
+  });
+  const result = await migration.migrateIfNeeded({ migrationRunId: 'knowledge-index-v2' });
+  assert(result.ok && result.completed && result.migrated, JSON.stringify(result));
+  const projectId = result.projectMap.api;
+  const projectStore = new ProjectStore({ layout });
+  const config = projectStore.readConfig(projectId);
+  const state = projectStore.readState(projectId);
+  assert.strictEqual(config.knowledgePath, fixedKnowledgePath, 'legacy kbPath must be preserved exactly');
+  assert.strictEqual(state.trackingStartCommit, 'track-before');
+  assert.strictEqual(state.lastAnalyzedCommit, 'commit-before');
+  assert.strictEqual(new SettingsStore({ layout }).read().ai.profiles[0].apiKey, 'migration-secret-value');
+  const migratedDatabase = new KnowledgeDatabase({ dbPath: layout.getIndexPath() });
+  assert.strictEqual(await migratedDatabase.count(), 1, 'the validated legacy index should be copied to the one internal index path');
+  await migratedDatabase.close();
+  assert(fs.existsSync(legacyIndex), 'legacy index source must remain for rollback');
+  assert(fs.existsSync(path.join(result.recoveryDir, 'backup', 'knowledge.lancedb')), 'recovery must retain an index backup');
+  assert(fs.existsSync(path.join(dataDir, '.hook-trigger-errors.log')), 'legacy hook logs must remain at the source');
+  assert(fs.existsSync(path.join(result.recoveryDir, 'backup', '.hook-trigger-errors.log')));
+
+  const settings = new SettingsStore({ layout });
+  await settings.updatePatch({ knowledge: { rootPath: path.join(dataDir, 'new-knowledge-root') } });
+  assert.strictEqual(projectStore.readConfig(projectId).knowledgePath, fixedKnowledgePath, 'changing the global root must not move an imported project');
+  assert.strictEqual(layout.getIndexPath(), path.join(dataDir, 'index', 'knowledge.lancedb'), 'global root changes must not move the derived index');
+  const second = await migration.migrateIfNeeded();
+  assert.strictEqual(second.migrated, false);
+  console.log('knowledge-migration-test: PASS');
+})().catch(error => { console.error(error); process.exitCode = 1; });