@sanqianx/project-knowledge 4.6.1

package/bin/project-knowledge.js

@@ -0,0 +1,439 @@
+#!/usr/bin/env node
+
+// project-knowledge CLI — start in background by default (auto-opens browser).
+// Pattern modeled on tokmeter's bin.js: detached child + PID file + port fallback.
+// Run `project-knowledge --help` for usage.
+
+const path = require('path');
+const { spawn, spawnSync, exec, execSync } = require('child_process');
+const { existsSync, readFileSync, writeFileSync, unlinkSync, mkdirSync, openSync } = require('fs');
+const net = require('net');
+const os = require('os');
+const { getDataDir } = require('../_site/lib/data-dir');
+const runtimeEndpoint = require('../_site/lib/runtime-endpoint');
+
+const pkg = require('../package.json');
+const DEFAULT_PORT = parseInt(process.env.KB_SITE_PORT || '5757', 10);
+const PORT_RANGE = 20;
+const PID_FILE = path.join(os.tmpdir(), '.project-knowledge.pid');
+const DATA_DIR = getDataDir();
+
+function readPid() {
+  try {
+    if (!existsSync(PID_FILE)) return null;
+    const lines = readFileSync(PID_FILE, 'utf8').trim().split('\n');
+    return parseInt(lines[0], 10);
+  } catch { return null; }
+}
+
+function readPort() {
+  try {
+    if (!existsSync(PID_FILE)) return null;
+    const lines = readFileSync(PID_FILE, 'utf8').trim().split('\n');
+    return lines[1] ? parseInt(lines[1], 10) : null;
+  } catch { return null; }
+}
+
+function writePid(pid, port) {
+  try {
+    writeFileSync(PID_FILE, `${pid}\n${port}`, 'utf8');
+  } catch (err) {
+    console.error(`Warning: failed to write PID file at ${PID_FILE}: ${err.message}`);
+  }
+}
+
+function removePid(expectedPid) {
+  try {
+    if (expectedPid != null && readPid() !== Number(expectedPid)) return;
+    unlinkSync(PID_FILE);
+  } catch { /* ignore */ }
+}
+
+function isProcessAlive(pid) {
+  if (!pid || Number.isNaN(pid)) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function openBrowser(url) {
+  let cmd;
+  if (process.platform === 'win32') {
+    cmd = `start "" "${url}"`;
+  } else if (process.platform === 'darwin') {
+    cmd = `open "${url}"`;
+  } else {
+    cmd = `xdg-open "${url}"`;
+  }
+  try { exec(cmd); } catch { /* best-effort */ }
+}
+
+function isPortFree(port, host = '127.0.0.1') {
+  return new Promise((resolve) => {
+    const tester = net.createServer();
+    let settled = false;
+    const finish = (free) => {
+      if (settled) return;
+      settled = true;
+      tester.removeAllListeners();
+      tester.close(() => resolve(free));
+    };
+    tester.once('error', () => finish(false));
+    tester.once('listening', () => finish(true));
+    tester.listen(port, host);
+    // Under AV scan / cold cache a listen() can be slower than the probe
+    // timeout; a false "busy" cascades into "No free port found". 3s is slow
+    // enough for one probe while still bounding the 20-port scan.
+    setTimeout(() => finish(false), 3000);
+  });
+}
+
+async function findFreePort(start, host = '127.0.0.1') {
+  for (let offset = 0; offset < PORT_RANGE; offset++) {
+    const port = start + offset;
+    if (await isPortFree(port, host)) return port;
+  }
+  throw new Error(`No free port found in range ${start}-${start + PORT_RANGE - 1}`);
+}
+
+// Find PIDs whose TCP socket is LISTENING on `port`. Cross-platform wrapper
+// around netstat / lsof / ss. Returns a deduped list, possibly empty.
+function findListeningPids(port) {
+  try {
+    let cmd;
+    if (process.platform === 'win32') {
+      cmd = `netstat -ano | findstr ":${port} " | findstr "LISTENING"`;
+    } else if (process.platform === 'darwin') {
+      cmd = `lsof -nP -iTCP:${port} -sTCP:LISTEN -t 2>/dev/null`;
+    } else {
+      cmd = `ss -tlnpH 'sport = :${port}' 2>/dev/null | grep -oP 'pid=\\K[0-9]+'`;
+    }
+    const stdout = execSync(cmd, { windowsHide: true, encoding: 'utf8', timeout: 3000 });
+    const pids = stdout.split(/\r?\n/).map((line) => {
+      const nums = line.match(/\d+/g);
+      return nums && nums.length ? parseInt(nums[nums.length - 1], 10) : null;
+    }).filter(Boolean);
+    return Array.from(new Set(pids));
+  } catch {
+    return [];
+  }
+}
+
+// Read another process's command line so we can verify it's ours before
+// killing it. Returns '' on any failure (permissions, process gone, etc).
+function getProcessCommandLine(pid) {
+  try {
+    let cmd, stdout;
+    if (process.platform === 'win32') {
+      stdout = execSync(`wmic process where "ProcessId=${pid}" get CommandLine /value`,
+        { windowsHide: true, encoding: 'utf8', timeout: 3000 });
+      const m = stdout.match(/CommandLine=(.+)/);
+      return m ? m[1].trim() : '';
+    }
+    stdout = execSync(`ps -p ${pid} -o args= 2>/dev/null`,
+      { encoding: 'utf8', timeout: 3000 });
+    return stdout.trim();
+  } catch {
+    return '';
+  }
+}
+
+// Scan DEFAULT_PORT..+PORT_RANGE for a LISTENING PID whose command line looks
+// like our server. Used as a fallback when the PID file is missing/stale so the
+// CLI isn't blind to long-running orphans.
+function findOrphanProcess() {
+  const startPort = readPort() || DEFAULT_PORT;
+  for (let offset = 0; offset < PORT_RANGE; offset++) {
+    const port = startPort + offset;
+    for (const candidate of findListeningPids(port)) {
+      const cmdline = getProcessCommandLine(candidate).toLowerCase();
+      if (cmdline.includes('project-knowledge') && cmdline.includes('node')) {
+        return { pid: candidate, port };
+      }
+    }
+  }
+  return null;
+}
+
+// ── Subcommands ──
+function cmdStop() {
+  const endpoint = runtimeEndpoint.readLiveEndpoint(DATA_DIR);
+  if (endpoint) {
+    try {
+      process.kill(endpoint.pid);
+      runtimeEndpoint.clearEndpoint(DATA_DIR, { pid: endpoint.pid });
+      if (readPid() === endpoint.pid) removePid(endpoint.pid);
+      console.log(`project-knowledge stopped (PID ${endpoint.pid}).`);
+    } catch {
+      console.error(`Failed to stop process ${endpoint.pid}`);
+      process.exit(1);
+    }
+    process.exit(0);
+  }
+  const pid = readPid();
+  if (pid && isProcessAlive(pid)) {
+    try {
+      process.kill(pid);
+      removePid();
+      console.log(`project-knowledge stopped (PID ${pid}).`);
+    } catch {
+      console.error(`Failed to stop process ${pid}`);
+      process.exit(1);
+    }
+    process.exit(0);
+  }
+  if (pid) {
+    // Stale PID file — record pointed at a dead process. Drop it so the
+    // orphan-scan below can take over without being misled.
+    removePid();
+    console.log('Process already stopped.');
+  }
+
+  // Fallback: the PID file can disappear (manual cleanup, antivirus, OS temp
+  // cleanup) while the server keeps running. Without this scan the CLI has no
+  // way to stop an orphan whose PID it never recorded.
+  const orphan = findOrphanProcess();
+  if (orphan) {
+    try {
+      process.kill(orphan.pid);
+      console.log(`Stopped orphan project-knowledge (PID ${orphan.pid}) on port ${orphan.port}.`);
+      process.exit(0);
+    } catch {
+      console.error(`Found PID ${orphan.pid} on port ${orphan.port} but failed to stop it.`);
+      process.exit(1);
+    }
+  }
+  console.log('No background process found.');
+  process.exit(0);
+}
+
+function cmdStatus() {
+  const endpoint = runtimeEndpoint.readLiveEndpoint(DATA_DIR);
+  if (endpoint) {
+    console.log(`project-knowledge is running (PID ${endpoint.pid}) at http://${endpoint.host}:${endpoint.port} [${endpoint.mode}]`);
+    process.exit(0);
+  }
+  const pid = readPid();
+  if (pid && isProcessAlive(pid)) {
+    const port = readPort() || DEFAULT_PORT;
+    console.log(`project-knowledge is running (PID ${pid}) at http://localhost:${port}`);
+    process.exit(0);
+  }
+  if (pid) removePid();
+
+  // PID file is gone or stale — check the port directly.
+  const orphan = findOrphanProcess();
+  if (orphan) {
+    console.log(`project-knowledge is running (orphan, PID ${orphan.pid}) at http://localhost:${orphan.port}`);
+    console.log('(No PID file on disk — recovered via port scan. Run "project-knowledge stop" to clean up.)');
+    process.exit(0);
+  }
+  console.log('project-knowledge is not running.');
+  process.exit(0);
+}
+
+function printHelp() {
+  console.log(`project-knowledge ${pkg.version}
+
+Local knowledge-base dashboard manager.
+
+Usage:
+  project-knowledge              Start in background (default), auto-open browser
+  project-knowledge --fg         Start in foreground (Ctrl+C to stop)
+  project-knowledge stop         Stop the background process
+  project-knowledge status       Check if running
+  project-knowledge install      Install coding-agent integrations
+  project-knowledge update       Update coding-agent integrations
+  project-knowledge uninstall    Remove coding-agent integrations
+  project-knowledge integrations status
+                                Check Claude Code, OpenCode, and Codex integrations
+
+Options:
+  -p, --port <port>   Port to run on (default: ${DEFAULT_PORT}, auto-fallback ±${PORT_RANGE})
+      --host <host>   Host to bind on (default: 127.0.0.1)
+      --no-open       Don't auto-open browser
+      --fg            Run in foreground
+  -v, --version       Print version and exit
+  -h, --help          Show this help message
+
+Runtime data lives next to the npm global root; PID file at ${PID_FILE}.
+`);
+  process.exit(0);
+}
+
+// ── Parse args ──
+const args = process.argv.slice(2);
+
+const integrationCommands = new Set(['install', 'update', 'uninstall', 'integrations']);
+if (integrationCommands.has(args[0])) {
+  const forwarded = args[0] === 'integrations'
+    ? (args.slice(1).length ? args.slice(1) : ['status'])
+    : args;
+  const result = spawnSync(
+    process.execPath,
+    [path.join(__dirname, 'project-knowledge-integrations.js'), ...forwarded],
+    { stdio: 'inherit', windowsHide: true }
+  );
+  process.exit(result.status == null ? 1 : result.status);
+}
+
+// Subcommands first
+if (args[0] === 'stop') cmdStop();
+if (args[0] === 'status') cmdStatus();
+
+let port = DEFAULT_PORT;
+let host = '127.0.0.1';
+let shouldOpen = true;
+let foreground = false;
+let portExplicit = false;
+let hostExplicit = false;
+
+for (let i = 0; i < args.length; i++) {
+  const arg = args[i];
+  if (arg === '--help' || arg === '-h') {
+    printHelp();
+  } else if (arg === '--version' || arg === '-v') {
+    console.log(pkg.version);
+    process.exit(0);
+  } else if ((arg === '--port' || arg === '-p') && args[i + 1]) {
+    const parsed = parseInt(args[i + 1], 10);
+    if (Number.isNaN(parsed)) {
+      console.error('Error: --port must be a number');
+      process.exit(1);
+    }
+    port = parsed;
+    portExplicit = true;
+    i++;
+  } else if (arg === '--host' && args[i + 1]) {
+    host = args[i + 1];
+    hostExplicit = true;
+    i++;
+  } else if (arg === '--no-open') {
+    shouldOpen = false;
+  } else if (arg === '--fg') {
+    foreground = true;
+  } else if (arg.startsWith('-')) {
+    console.error(`Unknown option: ${arg}\nRun \`project-knowledge --help\` for usage.`);
+    process.exit(1);
+  }
+}
+
+// ── Background launch ──
+if (!foreground) {
+  const endpoint = runtimeEndpoint.readLiveEndpoint(DATA_DIR);
+  if (endpoint) {
+    const url = `http://${endpoint.host}:${endpoint.port}`;
+    console.log(`Already running (PID ${endpoint.pid}) at ${url}`);
+    if (shouldOpen) openBrowser(url);
+    process.exit(0);
+  }
+  const existingPid = readPid();
+  if (existingPid && isProcessAlive(existingPid)) {
+    const actualPort = readPort() || DEFAULT_PORT;
+    const url = `http://localhost:${actualPort}`;
+    console.log(`Already running (PID ${existingPid}) at ${url}`);
+    if (shouldOpen) openBrowser(url);
+    process.exit(0);
+  }
+  removePid();
+
+  // Re-spawn self with --fg so the child owns the PID file
+  const forwarded = [];
+  if (portExplicit) forwarded.push('--port', String(port));
+  if (hostExplicit) forwarded.push('--host', host);
+  if (!shouldOpen) forwarded.push('--no-open');
+
+  // The parent doesn't know the final port (the child may fall back when the
+  // default is busy), so it must not print a URL or open the browser — the
+  // child does both once it is actually listening. The child's output goes to
+  // a log file: a detached child with stdio:'ignore' is undiagnosable when
+  // startup fails or the port falls back.
+  const LAUNCH_LOG = path.join(DATA_DIR, 'launcher.log');
+  let logFd;
+  try {
+    mkdirSync(path.dirname(LAUNCH_LOG), { recursive: true });
+    logFd = openSync(LAUNCH_LOG, 'a');
+  } catch { /* best-effort: fall back to discarding output */ }
+  const stdio = logFd == null ? 'ignore' : ['ignore', logFd, logFd];
+
+  const child = spawn(
+    process.execPath,
+    [...process.argv.slice(1), '--fg', ...forwarded],
+    { detached: true, stdio, windowsHide: true }
+  );
+  child.unref();
+
+  console.log('project-knowledge starting in background');
+  console.log(`Diagnostics: ${LAUNCH_LOG}`);
+  console.log(`Use "project-knowledge status" to check, "project-knowledge stop" to stop.`);
+  process.exit(0);
+}
+
+// ── Foreground: start server ──
+process.env.KB_SITE_HOST = host;
+
+async function main() {
+  const existingEndpoint = runtimeEndpoint.readLiveEndpoint(DATA_DIR);
+  if (existingEndpoint && existingEndpoint.pid !== process.pid) {
+    console.log(`Already running (PID ${existingEndpoint.pid}) at http://${existingEndpoint.host}:${existingEndpoint.port}`);
+    process.exit(0);
+  }
+  const actualPort = portExplicit ? port : await findFreePort(port, host);
+  process.env.KB_SITE_PORT = String(actualPort);
+
+  const claim = runtimeEndpoint.claimEndpoint(DATA_DIR, {
+    pid: process.pid,
+    host,
+    port: actualPort,
+    mode: process.env.KB_RUNTIME_MODE || 'cli',
+  });
+  if (!claim.claimed) {
+    const active = claim.endpoint;
+    if (active) {
+      console.log(`Already running (PID ${active.pid}) at http://${active.host}:${active.port}`);
+    } else {
+      console.error('Another project-knowledge process is starting. Please try again in a moment.');
+    }
+    process.exit(active ? 0 : 1);
+  }
+  writePid(process.pid, actualPort);
+  const cleanup = () => {
+    removePid(process.pid);
+    runtimeEndpoint.clearEndpoint(DATA_DIR, { pid: process.pid });
+  };
+  process.on('exit', cleanup);
+  process.on('SIGINT', () => { cleanup(); process.exit(0); });
+  process.on('SIGTERM', () => { cleanup(); process.exit(0); });
+  // Windows console-close sends SIGBREAK; Node doesn't run exit handlers after
+  // a forceful TerminateProcess, but SIGBREAK does fire before the process is
+  // torn down, so we can still clean up here.
+  if (process.platform === 'win32') {
+    process.on('SIGBREAK', () => { cleanup(); process.exit(0); });
+  }
+
+  const url = `http://localhost:${actualPort}`;
+  if (actualPort !== port) {
+    console.log(`(Port ${port} was busy, using ${actualPort} instead)`);
+  }
+  console.log(`project-knowledge ${pkg.version}`);
+  console.log(`Listening at ${url}`);
+  // Resolve data dir the same way server.js will, so we can show the user
+  // where their config and KB files live BEFORE the server boots.
+  try {
+    console.log(`Data dir: ${getDataDir()}`);
+  } catch {}
+
+  require(path.join(__dirname, '..', '_site', 'server.js'));
+
+  if (shouldOpen) setTimeout(() => openBrowser(url), 500);
+}
+
+main().catch((err) => {
+  console.error(err.message);
+  removePid(process.pid);
+  runtimeEndpoint.clearEndpoint(DATA_DIR, { pid: process.pid });
+  process.exit(1);
+});

package/claude-prompts.json

@@ -0,0 +1,21 @@
+{
+  "schema": "claude-prompts/v1",
+  "prompts": {
+    "initial-analysis": {
+      "description": "Initial project analysis. Claude runs from the KB workspace and reads the source project via PROJECT_PATH.",
+      "model": "sonnet",
+      "permissionMode": "bypassPermissions",
+      "allowedTools": ["Read", "Grep", "Glob"],
+      "systemPrompt": "You are an expert project analyst building a knowledge base. The current working directory is the knowledge-base workspace, not the source project. Read source code from PROJECT_PATH and treat KB_PATH as the write target for knowledge-base drafts and updates. Output STRICT JSON only: no prose and no markdown fences. The JSON must match this shape:\n\n{\n  \"goalDraft\": {\n    \"oneLine\": \"one-sentence description of what this project is\",\n    \"positioning\": \"paragraph describing the project's role and core value\",\n    \"coreValue\": [\"bullet points of core value to developers / teams\"],\n    \"painPoints\": [{\"pain\": \"...\", \"legacyApproach\": \"...\", \"projectApproach\": \"...\"}]\n  },\n  \"analysisDraft\": {\n    \"framework\": \"primary framework / language / stack\",\n    \"modules\": [{\"name\": \"...\", \"responsibility\": \"...\", \"keyFiles\": [\"path/to/file\"]}],\n    \"architecture\": \"paragraph describing the architecture and data flow\",\n    \"evidence\": [{\"claim\": \"...\", \"file\": \"path:line\"}]\n  },\n  \"features\": [{\"slug\": \"kebab-case-slug\", \"name\": \"...\", \"summary\": \"...\"}]\n}\n\nUse the Read, Grep, and Glob tools to investigate PROJECT_PATH. Cite real source file paths in evidence. Do not invent modules that do not exist. Do not modify the source project unless the user explicitly asks for source changes.",
+      "userPrompt": "Analyze the source project at PROJECT_PATH. The current working directory is KB_PATH.\n\nProject context:\n- Slug: {{SLUG}}\n- Source project path: {{PROJECT_PATH}}\n- Knowledge-base path: {{KB_PATH}}\n- Primary language: {{PRIMARY_LANGUAGE}}\n- Knowledge language: {{KNOWLEDGE_LANGUAGE}}\n\nTasks:\n1. Identify the framework, main tech stack, and language distribution.\n2. List the core modules / top-level directories and their responsibilities.\n3. Describe the architecture and data flow at a high level.\n4. Identify 3-6 user-facing features.\n5. Capture 4-8 evidence-backed claims with file:line citations.\n\nWrite the knowledge-base content in {{KNOWLEDGE_LANGUAGE}} where natural, but keep code identifiers, file paths, and JSON keys in English.\n\nReturn ONLY the JSON object described in the system prompt."
+    },
+    "commit-analysis": {
+      "description": "Batch analysis of one or more commits. Claude runs from the KB workspace and reads the source project via PROJECT_PATH.",
+      "model": "sonnet",
+      "permissionMode": "bypassPermissions",
+      "allowedTools": ["Read", "Grep", "Glob", "Bash"],
+      "systemPrompt": "You are a commit analyst building a knowledge base. The current working directory is the knowledge-base workspace, not the source project. Read source code from PROJECT_PATH and treat KB_PATH as the write target for knowledge-base drafts and updates. For each commit provided, output a structured change description. STRICT JSON only: no prose.\n\nOutput shape:\n{\n  \"changes\": [\n    {\n      \"hash\": \"<full-or-short-hash>\",\n      \"subject\": \"<original commit subject>\",\n      \"type\": \"feat|fix|refactor|docs|test|chore|infra\",\n      \"classification\": \"feature|bugfix|infrastructure|documentation|test\",\n      \"summary\": \"one-paragraph description of what changed and why\",\n      \"files\": [\"paths/touched\"],\n      \"evidence\": [{\"claim\": \"...\", \"file\": \"path:line\"}]\n    }\n  ]\n}\n\nUse git commands against PROJECT_PATH and Read for inspecting changed files. Cite real source file paths. Do not modify the source project unless the user explicitly asks for source changes.",
+      "userPrompt": "Analyze the following commits in the source project at PROJECT_PATH. The current working directory is KB_PATH.\n\nProject: {{SLUG}} ({{PROJECT_PATH}})\nKnowledge-base path: {{KB_PATH}}\nCommit range: {{COMMIT_RANGE}}\nCommits to analyze:\n{{COMMIT_HASHES}}\n\nFor each commit, produce one entry in the changes array. Use git commands against {{PROJECT_PATH}} and Read for inspecting changed source files. Summarize in {{KNOWLEDGE_LANGUAGE}}; keep identifiers and paths in English.\n\nReturn ONLY the JSON object."
+    }
+  }
+}

package/docs/README.zh-CN.md

@@ -0,0 +1,175 @@
+# project-knowledge
+
+本地、由 Git Commit 驱动的项目知识服务。Markdown 是知识事实源；LanceDB
+只是位于内部数据目录、可随时重建的派生索引。
+
+## 安装与运行
+
+新机器完整安装只需三条命令：
+
+```bash
+npm install -g project-knowledge
+project-knowledge-integrations install
+project-knowledge
+```
+
+1. `npm install -g project-knowledge` 安装知识库 CLI,内置
+   `ai-coding-event-bridge` 依赖,无需再装其它包。
+2. `project-knowledge-integrations install` 是一次性的 Integration Setup,
+   对检测到的每个客户端(Claude Code / Codex / OpenCode)同时安装两类
+   相互独立、分别上报状态的能力:
+   - **Knowledge Integration**:插件 / MCP / Skill,让外部 Agent 能查询知识库;
+   - **Development Capture**:托管的 Bridge hooks / notify / plugin,把真实
+     Git 工作区里的 Agent 对话捕捉进已导入项目的「开发对话」。
+   同时注册 host 级 `project-knowledge` Bridge consumer。全程无需打开任何
+   客户端 UI;第三方 hooks 与配置完整保留;Codex notify 冲突只上报不覆盖。
+3. `project-knowledge` 启动本地服务。旧版本导入的项目会在第一次 drain 时
+   自动升级(补写 canonical workspace 身份 + 建立对话 baseline),无需手工迁移。
+
+注意事项:
+
+- 装完 Development Capture 后,已在运行的 Claude Code 会话需重启一次
+  (hooks 在会话启动时加载)。只捕捉配置之后的对话,历史不回填。
+- 按需收窄安装范围:`--ide claude` / `--capture-only` / `--knowledge-only`;
+  按客户端移除捕捉:`uninstall --capture-only`;全局禁用捕捉(含注销 Bridge
+  consumer):`disable-capture`。
+
+默认只监听 `127.0.0.1:5757`。CLI 会记录实际 loopback endpoint，托管 Git
+Hook 不依赖写死端口。
+
+```bash
+project-knowledge
+project-knowledge --fg
+project-knowledge status
+project-knowledge stop
+```
+
+需要 Node.js 18+ 与 `PATH` 中的 Git。Windows 桌面安装包与 npm CLI 共享同一
+数据目录和 backend owner 记录，不会同时启动两个 LanceDB writer。
+
+## 唯一分析流程
+
+公开分析入口只有两个：
+
+```text
+post-commit Hook ----+
+                     +--> reconcileProjectCommits(projectId, trigger)
+程序 startup --------+      trigger: git-hook | startup
+```
+
+导入只建立 Git tracking baseline、创建项目元数据并安装/验证 Hook；不运行 AI、
+不扫描全仓推测需求、不生成 TODO 知识。空仓库导入后的第一个 Commit会被处理。
+
+Hook 只向本地主程序发送 `hook-event/v2` 通知。主程序离线时 Hook 仍返回成功，
+不阻塞 `git commit`，也不写离线任务 spool；下次启动从当前 Git 历史补查可达
+Commit。同项目严格串行、失败即停；不同项目可并行；Hook 与 startup 重叠时复用
+同一个 in-flight reconciliation。
+
+## 知识与索引安全
+
+每个 Commit 的 claim 会冻结 Commit SHA、真实 patch、绑定的 requirement IDs、
+prompt hash 与固定 knowledgePath。AI 只能写内部 per-run staging，不能写源码或
+final knowledgePath。产物 manifest 必须通过路径、UTF-8、Markdown、hash、证据与
+操作类型验证。
+
+Promotion 使用 backup、hash 与 durable journal。只有 Markdown promotion 验证
+成功后才推进 lastAnalyzedCommit 并把 index 标为 dirty。索引失败不会回滚真实
+Markdown，也不会重跑 AI；启动和维护流程会重试 dirty index。
+
+`IndexService` 是唯一生产 LanceDB writer。增量更新和 full rebuild 共用一个全局
+FIFO。完整重建先生成独立临时 DB，验证后原子替换，并在 recovery 中保留旧索引。
+
+应用不会创建、修改、刷新或删除 `CLAUDE.md`。
+
+## 需求记录与查询
+
+Claude Code、Codex、OpenCode 集成可在编码前追加用户真实需求元数据。记录写入
+项目 `requirements.jsonl`，不会触发分析或写知识。
+
+MCP 提供只读 `resolve/search/ask/get/history`，以及唯一写能力
+`record_requirement`。CLI 示例：
+
+```bash
+project-knowledge-kb search --project <projectId> --query "令牌轮换" --json
+project-knowledge-kb ask --project <projectId> --query "登录方案如何决定？"
+project-knowledge-kb get --project <projectId> --entry modules/auth.md --json
+project-knowledge-kb history --project <projectId> --json
+```
+
+只读查询不会创建或修改配置。索引缺失、dirty 或不可用时，会明确回退到当前项目
+以及显式 related projects 的 Markdown。
+
+## 存储合同
+
+内部数据默认在 `~/.project-knowledge/`，可用 `KB_DATA_DIR` 修改。用户必须先设置
+global knowledge root，再导入项目；它只影响未来导入。每个项目导入时固化绝对
+knowledgePath，修改 global root 不会移动已有项目。
+
+```text
+~/.project-knowledge/
+├── settings.json
+├── projects.json                         # 仅 ID、顺序、最小显示快照
+├── projects/<projectId>/
+│   ├── config.json                       # 固定 repoPath/knowledgePath
+│   ├── state.json                        # tracking/claim/index/Hook 状态
+│   └── requirements.jsonl                # 按需创建
+├── index/knowledge.lancedb               # 唯一派生索引
+├── cache/
+├── runtime/
+├── logs/{app,projects,hooks}/
+└── recovery/
+
+<用户选择的知识根>/
+└── <项目 storage name>/
+    ├── README.md
+    ├── GOAL.md
+    ├── ARCHITECTURE.md
+    ├── modules/*.md
+    └── changes/*.md
+```
+
+Team knowledge 是显式例外：项目可绑定已经 checkout 的 team store 子目录。路径
+仍必须位于所选 store 内并固化到 config；删除项目注册时不会删除这类外部知识。
+
+## 迁移
+
+`layout-v2` 迁移先只读发现旧资产，创建 journal 和集中 recovery backup，再 staging
+settings、per-project config/state、最小 registry 与旧 index。验证路径、secret、
+Commit pointer、日志和索引后才激活，completion marker 最后写。任何阶段中断都
+保留旧 reader、用户知识、历史日志、配置与 backup，允许安全重试。
+
+## 日志 UI
+
+生产 UI 只保留一套结构化日志控制台，支持：
+
+- trace/debug/info/warn/error/fatal 六级；
+- 本地日期、项目、component、event、operation、Commit、全文过滤；
+- newest-first cursor 分页、暂停/自动刷新、按当前条件导出；
+- operation flow、结构化 error/stack、logger degraded 状态；
+- Hook/index/项目只读状态、浅色/深色与窄屏布局。
+
+日志使用 `log/v2` JSONL，按天和 50 MiB segment 轮转；默认保留 365 天，`0`
+表示不按时间删除，并受总容量策略约束。写入、查询、error 与 export 全部递归脱敏。
+日志根固定在内部数据目录，不能由 API 修改。
+
+## API 安全
+
+默认 loopback + same-origin，不使用 wildcard CORS。非回环绑定必须配置
+`KB_SITE_AUTH_TOKEN` 并通过 Origin 校验。AI profile GET 只返回 masked metadata；
+通用错误不返回 stack；不存在 raw-file、通用项目覆盖、手动 Hook 或手动分析接口。
+
+## 验证
+
+```bash
+npm ci
+npm test -- --no-report
+npm test --prefix desktop
+npm pack --dry-run --json
+```
+
+Windows E2E 覆盖真实 Git Hook、空格/非 ASCII 路径、在线 Commit、停服期间多个
+Commit、重启顺序补查、crash lock 恢复、promotion/index、查询与完整日志链路。
+
+## 许可证
+
+[Apache-2.0](../LICENSE)，另见 [NOTICE](../NOTICE)。