project-knowledge 0.1.0 → 1.0.1

package/_site/lib/ai-adapter.js

@@ -230,10 +230,10 @@ Constraints:
 const claudeCodeAgent = {
   id: 'claude-code-agent',
   name: 'Claude Code Agent (Anthropic-compatible)',
-  description: 'Real LLM via ANTHROPIC_BASE_URL + ANTHROPIC_AUTH_TOKEN. Used by post-commit hook when projects.json sets aiProfileId=claude-code-agent.',
+  description: 'Real LLM through an Anthropic-compatible Messages API. AI profiles can reuse this implementation with different model providers.',
   async analyzeInitialProject({ project, contextPack }) {
     const user = buildInitialUser({ project, contextPack });
-    const r = await completeJson({ system: INITIAL_SYSTEM, user, maxTokens: 3000 });
+    const r = await completeJson({ system: INITIAL_SYSTEM, user, maxTokens: 3000, profileId: project && project.aiProfileId });
     if (!r.parsed) {
       const e = new Error(`LLM returned no parseable JSON (${r.parseError && r.parseError.message || 'no output'})`);
       e.llmText = r.text;
@@ -243,7 +243,7 @@ const claudeCodeAgent = {
   },
   async analyzeCommitBatch({ project, commits, contextPack }) {
     const user = buildCommitUser({ project, commits, contextPack });
-    const r = await completeJson({ system: COMMIT_SYSTEM, user, maxTokens: 4096 });
+    const r = await completeJson({ system: COMMIT_SYSTEM, user, maxTokens: 4096, profileId: project && project.aiProfileId });
     if (!r.parsed) {
       console.error(`[claude-code-agent] LLM did not return valid JSON. text head: ${r.text.slice(0, 500)} ... text tail: ${r.text.slice(-500)}`);
       const e = new Error(`LLM returned no parseable JSON (${r.parseError && r.parseError.message || 'no output'})`);

package/_site/lib/ai-workspace.js

@@ -0,0 +1,120 @@
+const fs = require('fs');
+const path = require('path');
+
+const APP_ROOT = path.resolve(__dirname, '..', '..');
+const SITE_ROOT = path.resolve(__dirname, '..');
+const AI_ROOT = path.join(SITE_ROOT, '_ai');
+const STANDARD_SUBDIRS = ['drafts', 'runs', 'context-packs', 'backups', 'claude-workbench'];
+
+function safeSlug(slug) {
+  return typeof slug === 'string' && /^[a-z0-9][a-z0-9-]{0,40}$/.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 draftDir(slug, runId) {
+  return path.join(projectAIPath(slug), 'drafts', runId);
+}
+
+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`);
+  if (fs.existsSync(primary)) return primary;
+  const legacy = path.join(legacyAIPath(kbPath), 'runs', `${runId}.json`);
+  if (fs.existsSync(legacy)) return legacy;
+  return primary;
+}
+
+function findExistingDraftDir({ slug, kbPath, runId }) {
+  const primary = path.join(projectAIPath(slug), 'drafts', runId);
+  if (fs.existsSync(primary)) return primary;
+  const legacy = path.join(legacyAIPath(kbPath), 'drafts', runId);
+  if (fs.existsSync(legacy)) return legacy;
+  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,
+  draftDir,
+  contextPackDir,
+  findExistingRunPath,
+  findExistingDraftDir,
+  listProjectDirs,
+};

package/_site/lib/analysis-orchestrator.js

@@ -15,6 +15,33 @@ const { getAdapter } = require('./ai-adapter');
 const { buildContextPack } = require('./context-pack-builder');
 const { execGit } = require('./git-runner');
 const { scanProject } = require('./scanner');
+const aiWorkspace = require('./ai-workspace');
+const { isV3Kb, frontmatter } = require('./kb-v3');
+
+const AI_PROFILES_PATH = path.resolve(__dirname, '..', '..', 'ai-profiles.json');
+
+function readAiProfiles() {
+  try {
+    const cfg = JSON.parse(fs.readFileSync(AI_PROFILES_PATH, 'utf-8'));
+    return Array.isArray(cfg.profiles) ? cfg.profiles : [];
+  } catch {
+    return [];
+  }
+}
+
+function validateUsableProfile(profileId) {
+  const profile = readAiProfiles().find(item => item && item.id === profileId);
+  if (!profile && profileId === 'mock-agent') {
+    const mockAdapter = getAdapter('mock-agent');
+    if (mockAdapter) return { ok: true, adapter: mockAdapter };
+  }
+  if (!profile) return { ok: false, status: 400, error: `AI profile not configured: ${profileId}` };
+  const implementation = profile.implementation || profile.id;
+  const adapter = getAdapter(implementation);
+  if (!adapter) return { ok: false, status: 400, error: `unknown adapter: ${implementation}` };
+  if (profile.enabled === false) return { ok: false, status: 400, error: `AI profile disabled: ${profileId}` };
+  return { ok: true, adapter };
+}
 
 function readTemplate(name) {
   const p = path.join(__dirname, '..', '..', 'templates', name);
@@ -89,6 +116,25 @@ function labels(project) {
   };
 }
 
+function isV3Project(project, kbPath) {
+  return project.kbSchemaVersion === 'v3' || isV3Kb(kbPath);
+}
+
+function sourceMeta(project, headCommitAtRun = null) {
+  return {
+    sourceBranch: project.currentBranch || null,
+    sourceDefaultBranch: project.defaultBranch || null,
+    sourceRemote: project.remoteUrl || null,
+    sourceRunId: null,
+    sourceHeadCommit: headCommitAtRun || project.headCommit || null,
+  };
+}
+
+function prependDraftFrontmatter(text, meta) {
+  const clean = String(text || '').replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n/, '');
+  return `${frontmatter(meta)}${clean}`;
+}
+
 function renderGoalDraft(project, draft) {
   const tpl = readTemplate('project-goal.md');
   if (!tpl) return null;
@@ -160,15 +206,19 @@ async function runInitialAnalysis(project, options = {}) {
   const slug = project.slug;
   const kbPath = path.resolve(project.kbPath);
   const aiProfileId = project.aiProfileId || 'mock-agent';
-  const adapter = getAdapter(aiProfileId);
-  if (!adapter) return { ok: false, status: 400, error: `unknown adapter: ${aiProfileId}` };
+  const profileCheck = validateUsableProfile(aiProfileId);
+  if (!profileCheck.ok) return profileCheck;
+  const adapter = profileCheck.adapter;
   if (!fs.existsSync(kbPath)) return { ok: false, status: 400, error: 'project KB not initialized' };
+  const v3 = isV3Project(project, kbPath);
 
   const runId = `initial-${shortRunId(Date.now().toString(36) + Math.random().toString(36))}`;
-  const draftsDir = path.join(kbPath, '_ai', 'drafts', runId);
-  const runsDir = path.join(kbPath, '_ai', 'runs');
+  const aiRoot = v3 ? aiWorkspace.ensureProjectAIPath(slug) : path.join(kbPath, '_ai');
+  const draftsDir = path.join(aiRoot, 'drafts', runId);
+  const runsDir = path.join(aiRoot, 'runs');
   fs.mkdirSync(draftsDir, { recursive: true });
   fs.mkdirSync(runsDir, { recursive: true });
+  const meta = sourceMeta(project);
 
   const runRecord = {
     schema: 'ai-run/v1',
@@ -183,6 +233,9 @@ async function runInitialAnalysis(project, options = {}) {
     drafts: [],
     goalAccepted: false,
     headCommitAtRun: project.headCommit || null,
+    sourceBranch: meta.sourceBranch,
+    sourceDefaultBranch: meta.sourceDefaultBranch,
+    sourceRemote: meta.sourceRemote,
   };
 
   try {
@@ -193,7 +246,7 @@ async function runInitialAnalysis(project, options = {}) {
       trigger: 'initial',
       commits: [],
     });
-    runRecord.contextPackPath = path.relative(kbPath, path.join(kbPath, '_ai', 'context-packs', runId, 'context-pack.json'));
+    runRecord.contextPackPath = path.relative(aiRoot, path.join(aiRoot, 'context-packs', runId, 'context-pack.json')).replace(/\\/g, '/');
 
     // 2. Run analyzer
     const output = await adapter.analyzeInitialProject({ project, contextPack: pack });
@@ -214,18 +267,20 @@ async function runInitialAnalysis(project, options = {}) {
     const analysisText = renderAnalysisDraft(project, output.analysisDraft || {});
     const featureTexts = (output.features || []).map(f => ({ slug: f.slug, text: renderFeatureDraft(project, f) }));
 
-    const goalPath = path.join(draftsDir, 'project-goal.md');
-    const analysisPath = path.join(draftsDir, 'project-analysis.md');
-    fs.writeFileSync(goalPath, goalText || '', 'utf-8');
-    fs.writeFileSync(analysisPath, analysisText || '', 'utf-8');
-    runRecord.drafts.push({ op: 'create-file', path: 'project-goal.md', fromDraft: 'goalDraft' });
-    runRecord.drafts.push({ op: 'create-file', path: 'project-analysis.md', fromDraft: 'analysisDraft' });
+    const draftMeta = { ...meta, sourceRunId: runId, sourceHeadCommit: runRecord.headCommitAtRun };
+    const goalRel = v3 ? 'GOAL.md' : 'project-goal.md';
+    const analysisRel = v3 ? 'ARCHITECTURE.md' : 'project-analysis.md';
+    fs.writeFileSync(path.join(draftsDir, goalRel), prependDraftFrontmatter(goalText || `# ${slug} Goal\n`, draftMeta), 'utf-8');
+    fs.writeFileSync(path.join(draftsDir, analysisRel), prependDraftFrontmatter(analysisText || `# ${slug} Architecture\n`, draftMeta), 'utf-8');
+    runRecord.drafts.push({ op: 'create-file', path: goalRel, fromDraft: 'goalDraft', sourceBranch: meta.sourceBranch });
+    runRecord.drafts.push({ op: 'create-file', path: analysisRel, fromDraft: 'analysisDraft', sourceBranch: meta.sourceBranch });
 
     for (const f of featureTexts) {
-      const featurePath = path.join(draftsDir, 'features', `${f.slug}.md`);
+      const rel = v3 ? `modules/${f.slug}.md` : `features/${f.slug}.md`;
+      const featurePath = path.join(draftsDir, rel);
       fs.mkdirSync(path.dirname(featurePath), { recursive: true });
-      fs.writeFileSync(featurePath, f.text || '', 'utf-8');
-      runRecord.drafts.push({ op: 'create-file', path: `features/${f.slug}.md`, fromDraft: 'feature' });
+      fs.writeFileSync(featurePath, prependDraftFrontmatter(f.text || '', draftMeta), 'utf-8');
+      runRecord.drafts.push({ op: 'create-file', path: rel, fromDraft: v3 ? 'module' : 'feature', sourceBranch: meta.sourceBranch });
     }
     runRecord.outputPaths = runRecord.drafts.map(d => d.path);
 
@@ -278,9 +333,11 @@ async function runCommitAnalysis(project, options = {}) {
   const slug = project.slug;
   const kbPath = path.resolve(project.kbPath);
   const aiProfileId = project.aiProfileId || 'mock-agent';
-  const adapter = getAdapter(aiProfileId);
-  if (!adapter) return { ok: false, status: 400, error: `unknown adapter: ${aiProfileId}` };
+  const profileCheck = validateUsableProfile(aiProfileId);
+  if (!profileCheck.ok) return profileCheck;
+  const adapter = profileCheck.adapter;
   if (!fs.existsSync(kbPath)) return { ok: false, status: 400, error: 'project KB not initialized' };
+  const v3 = isV3Project(project, kbPath);
 
   // Run the scanner to discover pending commits since lastAnalyzedCommit.
   const scan = await scanProject({ slug, ...project }, { maxCommits: options.maxCommits || 200 });
@@ -292,10 +349,12 @@ async function runCommitAnalysis(project, options = {}) {
   }
 
   const runId = `commits-${shortRunId(Date.now().toString(36) + Math.random().toString(36))}`;
-  const draftsDir = path.join(kbPath, '_ai', 'drafts', runId);
-  const runsDir = path.join(kbPath, '_ai', 'runs');
+  const aiRoot = v3 ? aiWorkspace.ensureProjectAIPath(slug) : path.join(kbPath, '_ai');
+  const draftsDir = path.join(aiRoot, 'drafts', runId);
+  const runsDir = path.join(aiRoot, 'runs');
   fs.mkdirSync(draftsDir, { recursive: true });
   fs.mkdirSync(runsDir, { recursive: true });
+  const meta = sourceMeta(project, scan.headCommit || null);
 
   const runRecord = {
     schema: 'ai-run/v1',
@@ -311,6 +370,9 @@ async function runCommitAnalysis(project, options = {}) {
     commitCount: scan.commits.length,
     headCommitAtRun: scan.headCommit || null,
     lastAnalyzedCommitBefore: project.lastAnalyzedCommit || null,
+    sourceBranch: meta.sourceBranch,
+    sourceDefaultBranch: meta.sourceDefaultBranch,
+    sourceRemote: meta.sourceRemote,
     drafts: [],
     outputPaths: [],
   };
@@ -323,7 +385,7 @@ async function runCommitAnalysis(project, options = {}) {
       trigger: 'commits',
       commits: scan.commits,
     });
-    runRecord.contextPackPath = path.relative(kbPath, path.join(kbPath, '_ai', 'context-packs', runId, 'context-pack.json'));
+    runRecord.contextPackPath = path.relative(aiRoot, path.join(aiRoot, 'context-packs', runId, 'context-pack.json')).replace(/\\/g, '/');
 
     // 2. Run analyzer
     const output = await adapter.analyzeCommitBatch({ project, commits: scan.commits, contextPack: pack });
@@ -350,11 +412,12 @@ async function runCommitAnalysis(project, options = {}) {
       const shortCommit = (commit.short || commit.hash || '').slice(0, 7);
       const draftChangePath = path.join(draftsDir, 'changes', `${shortCommit}.md`);
       fs.mkdirSync(path.dirname(draftChangePath), { recursive: true });
-      fs.writeFileSync(draftChangePath, renderChangeDraft(project, change, commit), 'utf-8');
-      runRecord.drafts.push({ op: 'create-file', path: `changes/${shortCommit}.md`, fromDraft: 'change' });
+      const draftMeta = { ...meta, sourceRunId: runId, sourceHeadCommit: runRecord.headCommitAtRun };
+      fs.writeFileSync(draftChangePath, prependDraftFrontmatter(renderChangeDraft(project, change, commit), draftMeta), 'utf-8');
+      runRecord.drafts.push({ op: 'create-file', path: `changes/${shortCommit}.md`, fromDraft: 'change', sourceBranch: meta.sourceBranch });
       runRecord.outputPaths.push(`changes/${shortCommit}.md`);
 
-      if (change.classification === 'new-feature') {
+      if (!v3 && change.classification === 'new-feature') {
         const featureSlug = featureSlugFromSubject(commit.subject);
         const featurePath = path.join(draftsDir, 'features', `${featureSlug}.md`);
         fs.mkdirSync(path.dirname(featurePath), { recursive: true });
@@ -364,8 +427,8 @@ async function runCommitAnalysis(project, options = {}) {
             ? `${shortCommit} 引入的新功能：${commit.subject}`
             : `New feature introduced by ${shortCommit}: ${commit.subject}`,
         });
-        fs.writeFileSync(featurePath, featureText, 'utf-8');
-        runRecord.drafts.push({ op: 'create-file', path: `features/${featureSlug}.md`, fromDraft: 'feature' });
+        fs.writeFileSync(featurePath, prependDraftFrontmatter(featureText, draftMeta), 'utf-8');
+        runRecord.drafts.push({ op: 'create-file', path: `features/${featureSlug}.md`, fromDraft: 'feature', sourceBranch: meta.sourceBranch });
         runRecord.outputPaths.push(`features/${featureSlug}.md`);
       } else if (change.classification === 'refactor' || change.classification === 'infrastructure') {
         // Note a goal-impact line so the reviewer can see this changed the implementation shape.
@@ -396,28 +459,50 @@ function writeRun(runsDir, runRecord) {
 }
 
 function readRun(kbPath, runId) {
-  const p = path.join(kbPath, '_ai', 'runs', `${runId}.json`);
+  const slug = path.basename(kbPath);
+  const p = aiWorkspace.findExistingRunPath({ slug, kbPath, runId });
   if (!fs.existsSync(p)) return null;
   return JSON.parse(fs.readFileSync(p, 'utf-8'));
 }
 
 function listRuns(kbPath) {
-  const runsDir = path.join(kbPath, '_ai', 'runs');
-  if (!fs.existsSync(runsDir)) return [];
-  return fs.readdirSync(runsDir).filter(f => f.endsWith('.json')).map(f => {
-    try { return JSON.parse(fs.readFileSync(path.join(runsDir, f), 'utf-8')); } catch { return null; }
-  }).filter(Boolean);
+  const slug = path.basename(kbPath);
+  const dirs = [path.join(aiWorkspace.projectAIPath(slug), 'runs'), path.join(kbPath, '_ai', 'runs')];
+  const byId = new Map();
+  for (const runsDir of dirs) {
+    if (!fs.existsSync(runsDir)) continue;
+    for (const f of fs.readdirSync(runsDir).filter(file => file.endsWith('.json'))) {
+      try {
+        const run = JSON.parse(fs.readFileSync(path.join(runsDir, f), 'utf-8'));
+        byId.set(run.runId || f, run);
+      } catch {}
+    }
+  }
+  return [...byId.values()];
 }
 
 function listDrafts(kbPath, runId) {
-  const dir = path.join(kbPath, '_ai', 'drafts', runId);
+  const slug = path.basename(kbPath);
+  const run = readRun(kbPath, runId) || {};
+  const dir = aiWorkspace.findExistingDraftDir({ slug, kbPath, runId });
   if (!fs.existsSync(dir)) return [];
   const out = [];
   const walk = (d) => {
     for (const e of fs.readdirSync(d, { withFileTypes: true })) {
       const full = path.join(d, e.name);
       if (e.isDirectory()) walk(full);
-      else out.push({ path: path.relative(dir, full).replace(/\\/g, '/'), size: fs.statSync(full).size });
+      else {
+        const rel = path.relative(dir, full).replace(/\\/g, '/');
+        out.push({
+          path: rel,
+          size: fs.statSync(full).size,
+          sourceBranch: run.sourceBranch ?? 'unknown (pre-TASK-016)',
+          sourceDefaultBranch: run.sourceDefaultBranch ?? null,
+          sourceRemote: run.sourceRemote ?? null,
+          sourceRunId: run.runId || runId,
+          sourceHeadCommit: run.headCommitAtRun || null,
+        });
+      }
     }
   };
   walk(dir);