@sanqianx/project-knowledge 4.6.1

package/_site/lib/ai-workspace.js

@@ -0,0 +1,104 @@
+const fs = require('fs');
+const path = require('path');
+const { getDataDir } = require('./data-dir');
+
+const APP_ROOT = getDataDir();
+const SITE_ROOT = path.resolve(__dirname, '..');
+const AI_ROOT = path.join(APP_ROOT, '_ai');
+const STANDARD_SUBDIRS = ['runs', 'context-packs', 'backups', 'claude-workbench'];
+
+function safeSlug(slug) {
+  return typeof slug === 'string' && /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(slug);
+}
+
+function projectAIPath(slug) {
+  if (!safeSlug(slug)) throw new Error(`invalid slug for AI workspace: ${slug}`);
+  return path.join(AI_ROOT, slug);
+}
+
+function ensureProjectAIPath(slug) {
+  const root = projectAIPath(slug);
+  for (const sub of STANDARD_SUBDIRS) {
+    fs.mkdirSync(path.join(root, sub), { recursive: true });
+  }
+  return root;
+}
+
+function legacyAIPath(kbPath) {
+  return path.join(kbPath, '_ai');
+}
+
+function copyDir(src, dest) {
+  fs.mkdirSync(dest, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const from = path.join(src, entry.name);
+    const to = path.join(dest, entry.name);
+    if (entry.isDirectory()) copyDir(from, to);
+    else if (entry.isFile()) fs.copyFileSync(from, to);
+  }
+}
+
+function migrateAIWorkspace({ slug, kbPath, preserveOriginal = true }) {
+  const legacy = legacyAIPath(kbPath);
+  const target = ensureProjectAIPath(slug);
+  const result = {
+    ok: true,
+    slug,
+    legacyPath: legacy,
+    targetPath: target,
+    copied: false,
+    preservedOriginal: preserveOriginal,
+  };
+  if (!fs.existsSync(legacy)) return result;
+  copyDir(legacy, target);
+  result.copied = true;
+  if (!preserveOriginal) {
+    fs.rmSync(legacy, { recursive: true, force: true });
+    result.preservedOriginal = false;
+  }
+  return result;
+}
+
+function runPath(slug, runId) {
+  return path.join(projectAIPath(slug), 'runs', `${runId}.json`);
+}
+
+function contextPackDir(slug, runId) {
+  return path.join(projectAIPath(slug), 'context-packs', runId);
+}
+
+function findExistingRunPath({ slug, kbPath, runId }) {
+  const primary = path.join(projectAIPath(slug), 'runs', `${runId}.json`);
+  return primary;
+}
+
+function listProjectDirs(projectSlug = null, projects = null) {
+  if (projectSlug) return [projectAIPath(projectSlug)];
+  const dirs = [];
+  if (fs.existsSync(AI_ROOT)) {
+    for (const entry of fs.readdirSync(AI_ROOT, { withFileTypes: true })) {
+      if (entry.isDirectory() && safeSlug(entry.name)) dirs.push(path.join(AI_ROOT, entry.name));
+    }
+  }
+  if (projects) {
+    for (const [slug] of Object.entries(projects)) {
+      if (safeSlug(slug)) dirs.push(projectAIPath(slug));
+    }
+  }
+  return [...new Set(dirs.map(d => path.resolve(d)))];
+}
+
+module.exports = {
+  APP_ROOT,
+  SITE_ROOT,
+  AI_ROOT,
+  STANDARD_SUBDIRS,
+  projectAIPath,
+  ensureProjectAIPath,
+  legacyAIPath,
+  migrateAIWorkspace,
+  runPath,
+  contextPackDir,
+  findExistingRunPath,
+  listProjectDirs,
+};

package/_site/lib/atomic-file.js

@@ -0,0 +1,204 @@
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const { DomainError } = require('./contracts');
+
+const DEFAULT_LOCK_TIMEOUT_MS = 10_000;
+const DEFAULT_STALE_LOCK_MS = 120_000;
+
+function delay(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+function isProcessAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error && error.code === 'EPERM';
+  }
+}
+
+function readLockOwner(lockPath) {
+  try { return JSON.parse(fs.readFileSync(lockPath, 'utf8')); } catch { return null; }
+}
+
+function canBreakStaleLock(lockPath, staleMs) {
+  let stat;
+  try { stat = fs.statSync(lockPath); } catch { return false; }
+  const owner = readLockOwner(lockPath);
+  // A complete owner record lets us recover immediately after a process
+  // crash. The age threshold is only needed for an incomplete/unreadable
+  // file that another process may still be creating.
+  if (owner && Number.isInteger(Number(owner.pid))) return !isProcessAlive(Number(owner.pid));
+  return (Date.now() - stat.mtimeMs) >= staleMs;
+}
+
+async function acquireFileLock(lockPath, options = {}) {
+  const timeoutMs = Number.isFinite(options.timeoutMs) ? options.timeoutMs : DEFAULT_LOCK_TIMEOUT_MS;
+  const staleMs = Number.isFinite(options.staleMs) ? options.staleMs : DEFAULT_STALE_LOCK_MS;
+  const retryMs = Number.isFinite(options.retryMs) ? options.retryMs : 25;
+  const started = Date.now();
+  const nonce = crypto.randomBytes(12).toString('hex');
+  fs.mkdirSync(path.dirname(lockPath), { recursive: true });
+  while (true) {
+    try {
+      const fd = fs.openSync(lockPath, 'wx', 0o600);
+      const owner = { pid: process.pid, startedAt: new Date().toISOString(), nonce };
+      fs.writeFileSync(fd, `${JSON.stringify(owner)}\n`, 'utf8');
+      fs.fsyncSync(fd);
+      fs.closeSync(fd);
+      return async function release() {
+        const current = readLockOwner(lockPath);
+        if (!current || current.nonce !== nonce) return;
+        try { fs.unlinkSync(lockPath); } catch (error) { if (!error || error.code !== 'ENOENT') throw error; }
+      };
+    } catch (error) {
+      if (!error || error.code !== 'EEXIST') throw error;
+      if (canBreakStaleLock(lockPath, staleMs)) {
+        try { fs.unlinkSync(lockPath); continue; } catch (unlinkError) {
+          // A competing process may recover the same stale lock first; retry through the normal wait path.
+        }
+      }
+      if ((Date.now() - started) >= timeoutMs) {
+        throw new DomainError('PROJECT_BUSY', 'Timed out waiting for a file lock.', {
+          status: 409,
+          retryable: true,
+          details: { lockCategory: path.basename(lockPath) },
+        });
+      }
+      await delay(retryMs);
+    }
+  }
+}
+
+async function withFileLock(lockPath, fn, options = {}) {
+  const release = await acquireFileLock(lockPath, options);
+  try { return await fn(); } finally { await release(); }
+}
+
+function syncDirectoryBestEffort(directory) {
+  let fd;
+  try {
+    fd = fs.openSync(directory, 'r');
+    fs.fsyncSync(fd);
+  } catch {
+    // Directory fsync is unsupported on some filesystems; the file replace is already durable.
+  } finally {
+    if (fd != null) try { fs.closeSync(fd); } catch {
+      // Closing a best-effort directory descriptor cannot invalidate the completed file replace.
+    }
+  }
+}
+
+function replaceWithRetry(tempPath, targetPath, options = {}) {
+  const retries = Number.isInteger(options.renameRetries) ? options.renameRetries : 8;
+  const waitBuffer = new Int32Array(new SharedArrayBuffer(4));
+  let lastError;
+  for (let attempt = 0; attempt <= retries; attempt += 1) {
+    try {
+      fs.renameSync(tempPath, targetPath);
+      return;
+    } catch (error) {
+      lastError = error;
+      if (!error || !['EPERM', 'EACCES', 'EBUSY', 'EEXIST'].includes(error.code) || attempt === retries) break;
+      Atomics.wait(waitBuffer, 0, 0, Math.min(250, 10 * (2 ** attempt)));
+    }
+  }
+  throw lastError;
+}
+
+function writeFileAtomic(filePath, content, options = {}) {
+  const directory = path.dirname(filePath);
+  fs.mkdirSync(directory, { recursive: true });
+  const tempPath = path.join(directory, `.${path.basename(filePath)}.${process.pid}.${Date.now()}.${crypto.randomBytes(6).toString('hex')}.tmp`);
+  let fd;
+  try {
+    fd = fs.openSync(tempPath, 'wx', options.mode || 0o600);
+    fs.writeFileSync(fd, content, options.encoding || 'utf8');
+    fs.fsyncSync(fd);
+    fs.closeSync(fd);
+    fd = null;
+    if (typeof options.beforeRename === 'function') options.beforeRename(tempPath, filePath);
+    replaceWithRetry(tempPath, filePath, options);
+    syncDirectoryBestEffort(directory);
+    return { path: filePath };
+  } catch (error) {
+    if (fd != null) try { fs.closeSync(fd); } catch {
+      // Preserve the original write error.
+    }
+    try { if (fs.existsSync(tempPath)) fs.unlinkSync(tempPath); } catch {
+      // Preserve the original write error; stale temp files are never treated as live data.
+    }
+    throw error;
+  }
+}
+
+function writeJsonAtomic(filePath, value, options = {}) {
+  return writeFileAtomic(filePath, `${JSON.stringify(value, null, 2)}\n`, options);
+}
+
+function readJsonStrict(filePath, options = {}) {
+  let raw;
+  try { raw = fs.readFileSync(filePath, 'utf8'); }
+  catch (error) {
+    if (error && error.code === 'ENOENT' && options.allowMissing) return options.defaultValue;
+    throw error;
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    if (typeof options.validate === 'function') options.validate(parsed);
+    return parsed;
+  } catch (error) {
+    if (error instanceof DomainError) throw error;
+    throw new DomainError('DATA_CORRUPT', 'A JSON data file is corrupt.', {
+      status: 500,
+      cause: error,
+      details: { category: options.category || 'json' },
+    });
+  }
+}
+
+async function appendJsonlLocked(filePath, value, options = {}) {
+  const lockPath = options.lockPath || `${filePath}.lock`;
+  return withFileLock(lockPath, async () => {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    const fd = fs.openSync(filePath, 'a', options.mode || 0o600);
+    try {
+      fs.writeFileSync(fd, `${JSON.stringify(value)}\n`, 'utf8');
+      fs.fsyncSync(fd);
+    } finally {
+      fs.closeSync(fd);
+    }
+    return value;
+  }, options);
+}
+
+function cleanupStaleTemps(directory, options = {}) {
+  if (!fs.existsSync(directory)) return [];
+  const olderThanMs = Number.isFinite(options.olderThanMs) ? options.olderThanMs : 24 * 60 * 60 * 1000;
+  const now = Date.now();
+  const removed = [];
+  for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+    if (!entry.isFile() || !/^\..+\.\d+\.\d+\.[a-f0-9]+\.tmp$/i.test(entry.name)) continue;
+    const absolute = path.join(directory, entry.name);
+    const stat = fs.statSync(absolute);
+    if ((now - stat.mtimeMs) < olderThanMs) continue;
+    fs.unlinkSync(absolute);
+    removed.push(absolute);
+  }
+  return removed;
+}
+
+module.exports = {
+  DEFAULT_LOCK_TIMEOUT_MS,
+  DEFAULT_STALE_LOCK_MS,
+  acquireFileLock,
+  withFileLock,
+  writeFileAtomic,
+  writeJsonAtomic,
+  readJsonStrict,
+  appendJsonlLocked,
+  cleanupStaleTemps,
+};

package/_site/lib/automation-config.js

@@ -0,0 +1,140 @@
+const path = require('path');
+
+const PERMISSION_MODES = new Set(['plan', 'default', 'acceptEdits', 'auto', 'bypassPermissions']);
+const PROMPT_TEMPLATE_VERSION = 2;
+
+const DEFAULT_COMMIT_PROMPT_TEMPLATE = `你正在根据一个 Git Commit 的冻结证据维护项目知识库。
+
+用户需求：
+{{userRequirement}}
+
+Commit 信息：
+{{commitMetadata}}
+
+Commit 实际变更文件：
+{{actualChanges}}
+
+Commit 实际 Patch：
+{{actualPatch}}
+
+现有相关知识：
+{{existingKnowledge}}
+
+请完成以下判断，并只输出符合 staging manifest 合同的知识变更：
+1. 比较用户需求与实际实现是否一致；没有可靠需求时不得猜测业务目的。
+2. 只记录 Commit、Patch 和现有知识能够证明的事实。
+3. 明确需要新增、更新或删除哪些知识；删除必须有实际变更证据。
+4. 不得修改源码、最终知识目录、其他项目或派生索引。
+5. Patch 使用 chunk evidence 时，必须从只读 manifest 按序读取所需 chunk；不得从源码工作树补读或猜测。`;
+
+const READ_TOOLS = ['Read'];
+const WRITE_TOOLS = ['Edit', 'Write', 'MultiEdit'];
+
+function normalizePermissionMode(value) {
+  return PERMISSION_MODES.has(value) ? value : 'default';
+}
+
+function normalizeAutomationConfig(input) {
+  const source = input && typeof input === 'object' ? input : {};
+  const explicit = typeof source.commitPromptTemplate === 'string' && source.commitPromptTemplate.trim();
+  const legacy = typeof source.hookPromptTemplate === 'string' && source.hookPromptTemplate.trim();
+  return {
+    enabled: source.enabled !== false,
+    commitPromptTemplate: explicit || legacy || DEFAULT_COMMIT_PROMPT_TEMPLATE,
+    promptTemplateVersion: PROMPT_TEMPLATE_VERSION,
+    legacyPromptOverride: !explicit && Boolean(legacy),
+  };
+}
+
+function normalizeClaudeWorkbenchConfig(input) {
+  const source = input && typeof input === 'object' ? input : {};
+  return { permissionMode: normalizePermissionMode(source.permissionMode) };
+}
+
+function renderTemplate(template, vars) {
+  const source = typeof template === 'string' && template.trim() ? template : DEFAULT_COMMIT_PROMPT_TEMPLATE;
+  const safeVars = vars && typeof vars === 'object' ? vars : {};
+  return source.replace(/\{\{\s*([A-Za-z][A-Za-z0-9_]*)\s*\}\}/g, (match, name) => {
+    if (!Object.prototype.hasOwnProperty.call(safeVars, name)) return match;
+    const value = safeVars[name];
+    return value == null ? '' : String(value);
+  });
+}
+
+function normalizePathForCompare(value) {
+  if (!value || typeof value !== 'string') return '';
+  const normalized = path.resolve(value).replace(/[\\/]+$/, '');
+  return process.platform === 'win32' ? normalized.toLowerCase() : normalized;
+}
+
+function pathsReferToSameLocation(leftValue, rightValue) {
+  const left = normalizePathForCompare(leftValue);
+  const right = normalizePathForCompare(rightValue);
+  return Boolean(left && right && left === right);
+}
+
+function isInsidePath(root, target) {
+  if (!root || !target) return false;
+  const rootAbs = path.resolve(root);
+  const targetAbs = path.resolve(rootAbs, target);
+  const relative = path.relative(rootAbs, targetAbs);
+  return relative === '' || Boolean(relative && !relative.startsWith('..') && !path.isAbsolute(relative));
+}
+
+function extractToolPaths(toolName, input) {
+  if (!input || typeof input !== 'object') return [];
+  const candidates = [];
+  for (const key of ['file_path', 'path', 'notebook_path']) {
+    if (typeof input[key] === 'string') candidates.push(input[key]);
+  }
+  if (toolName === 'MultiEdit' && typeof input.file_path === 'string') candidates.push(input.file_path);
+  return [...new Set(candidates)];
+}
+
+function buildAutomationToolPolicy(options = {}) {
+  const stagingPath = options.stagingPath || options.kbPath || '';
+  const evidenceRoot = options.evidenceRoot || '';
+  return {
+    kind: 'knowledge-staging',
+    stagingPath,
+    evidenceRoot,
+    readRoots: [evidenceRoot, stagingPath].filter(Boolean),
+    writeRoot: stagingPath,
+    allowedTools: [...READ_TOOLS, ...WRITE_TOOLS],
+    canWriteKb: false,
+    canWriteStaging: true,
+    allowReadOnlyBash: false,
+  };
+}
+
+function evaluateAutomationToolUse(policy, toolName, input) {
+  if (!policy || policy.kind !== 'knowledge-staging') return { behavior: 'ask', reason: 'no staging policy' };
+  if (!policy.allowedTools.includes(toolName)) return { behavior: 'deny', reason: `tool is not allowed: ${toolName}` };
+  const paths = extractToolPaths(toolName, input);
+  if (!paths.length) return { behavior: 'deny', reason: `${toolName} has no explicit file path` };
+  for (const filePath of paths) {
+    if (toolName === 'Read') {
+      if (!(policy.readRoots || []).some(root => isInsidePath(root, filePath))) {
+        return { behavior: 'deny', reason: `path outside read-only evidence/output roots: ${filePath}` };
+      }
+    } else if (!isInsidePath(policy.writeRoot || policy.stagingPath, filePath)) {
+      return { behavior: 'deny', reason: `path outside writable run output: ${filePath}` };
+    }
+  }
+  return { behavior: 'allow', reason: toolName === 'Read' ? 'path is inside an isolated read root' : 'path is inside the isolated writable output root' };
+}
+
+module.exports = {
+  PERMISSION_MODES,
+  PROMPT_TEMPLATE_VERSION,
+  DEFAULT_COMMIT_PROMPT_TEMPLATE,
+  normalizePermissionMode,
+  normalizeAutomationConfig,
+  normalizeClaudeWorkbenchConfig,
+  renderTemplate,
+  normalizePathForCompare,
+  pathsReferToSameLocation,
+  isInsidePath,
+  buildAutomationToolPolicy,
+  evaluateAutomationToolUse,
+};