project-knowledge 0.1.0

package/_site/lib/ai-adapter.js

@@ -0,0 +1,287 @@
+// AI analyzer adapter interface (TASK-005)
+// Each adapter implements the same shape so the orchestrator can swap implementations.
+//
+//   analyzeInitialProject({ project, contextPack }) -> { goalDraft, analysisDraft, modules, features }
+//   analyzeCommitBatch({ project, commits, contextPack }) -> { changes: [...] }
+//   validateOutput(output) -> { valid: boolean, errors: string[] }
+//
+// All adapters MUST return objects that pass validateOutput. The orchestrator never
+// writes drafts to disk unless the output validates.
+
+const fs = require('fs');
+const path = require('path');
+
+function isString(v) { return typeof v === 'string'; }
+function isNonEmptyString(v) { return isString(v) && v.length > 0; }
+function isStringArray(v) { return Array.isArray(v) && v.every(isString); }
+function isObject(v) { return v && typeof v === 'object' && !Array.isArray(v); }
+
+function normalizeKnowledgeLanguage(value) {
+  return value === 'en-US' ? 'en-US' : 'zh-CN';
+}
+
+function languageName(value) {
+  return normalizeKnowledgeLanguage(value) === 'en-US' ? 'English' : 'Simplified Chinese';
+}
+
+const initialProjectSchema = {
+  goalDraft: (v) => isObject(v) && isNonEmptyString(v.oneSentenceGoal || v.one_sentence_goal) && isStringArray(v.targetUsers || v.target_users),
+  analysisDraft: (v) => isObject(v) && isNonEmptyString(v.purpose) && isStringArray(v.capabilities),
+  modules: (v) => Array.isArray(v) && v.every(m => isObject(m) && isNonEmptyString(m.slug) && isNonEmptyString(m.role)),
+  features: (v) => Array.isArray(v) && v.every(f => isObject(f) && isNonEmptyString(f.slug) && isNonEmptyString(f.summary)),
+};
+
+const changeEntrySchema = {
+  commit: isNonEmptyString,
+  classification: (v) => ['new-feature', 'existing-feature-update', 'bug-fix', 'refactor', 'infrastructure', 'test-only', 'docs-only'].includes(v),
+  goalImpact: isNonEmptyString,
+  evidence: isStringArray,
+  proposedOps: (v) => Array.isArray(v) && v.every(op => isObject(op) && isNonEmptyString(op.op) && isNonEmptyString(op.path)),
+};
+
+function validateInitialOutput(output) {
+  const errors = [];
+  if (!isObject(output)) { errors.push('output is not an object'); return { valid: false, errors }; }
+  for (const [key, check] of Object.entries(initialProjectSchema)) {
+    if (!(key in output)) { errors.push(`missing field: ${key}`); continue; }
+    if (!check(output[key])) errors.push(`invalid field: ${key}`);
+  }
+  return { valid: errors.length === 0, errors };
+}
+
+function validateCommitBatchOutput(output) {
+  const errors = [];
+  if (!isObject(output)) { errors.push('output is not an object'); return { valid: false, errors }; }
+  if (!Array.isArray(output.changes)) { errors.push('missing or invalid: changes'); return { valid: false, errors }; }
+  for (let i = 0; i < output.changes.length; i++) {
+    const c = output.changes[i];
+    if (!isObject(c)) { errors.push(`change[${i}] is not an object`); continue; }
+    for (const [key, check] of Object.entries(changeEntrySchema)) {
+      if (!(key in c)) { errors.push(`change[${i}] missing: ${key}`); continue; }
+      if (!check(c[key])) errors.push(`change[${i}].${key} is invalid`);
+    }
+  }
+  return { valid: errors.length === 0, errors };
+}
+
+// ---- mock-agent: deterministic output for tests ----
+const mockAgent = {
+  id: 'mock-agent',
+  name: 'Mock Agent (deterministic)',
+  async analyzeInitialProject({ project, contextPack }) {
+    const slug = (project && project.slug) || 'unknown';
+    const zh = normalizeKnowledgeLanguage(project && project.knowledgeLanguage) === 'zh-CN';
+    return {
+      goalDraft: {
+        oneSentenceGoal: zh ? `[mock] ${slug} 提供自动化项目监督。` : `[mock] ${slug} provides automated project supervision.`,
+        targetUsers: zh ? ['开发者', '技术负责人'] : ['developer', 'tech-lead'],
+        coreScenarios: zh ? ['导入 Git 项目', '扫描提交', '审核草稿'] : ['import-git-project', 'scan-commits', 'review-drafts'],
+        successCriteria: zh ? ['草稿有证据支撑', '不会静默修改项目目标'] : ['drafts are evidence-backed', 'no silent goal edits'],
+        nonGoals: zh ? ['替代人工审核'] : ['replace human reviewers'],
+        priorityPrinciples: zh ? ['项目目标优先', '必须有证据'] : ['goal first', 'evidence required'],
+        prReviewPrinciples: zh ? ['引用证据', '不能自动覆盖 project-goal.md'] : ['cite evidence', 'never overwrite project-goal.md automatically'],
+      },
+      analysisDraft: {
+        purpose: zh ? `[mock] 根据上下文推断 ${slug} 的项目用途。` : `[mock] inferred purpose of ${slug} from context pack.`,
+        capabilities: zh ? ['Git 检查', '提交扫描', '草稿生成'] : ['git inspection', 'scanner', 'drafts'],
+        architecture: zh ? '分层结构：api -> scanner -> context -> adapter -> drafts' : 'layered: api -> scanner -> context -> adapter -> drafts',
+        modules: [
+          { slug: 'api', role: zh ? 'HTTP 接口层' : 'HTTP surface' },
+          { slug: 'scanner', role: zh ? 'Git 状态读取器' : 'git state reader' },
+        ],
+        dataFlow: zh ? 'HTTP -> api -> scanner -> context pack -> adapter -> drafts' : 'HTTP -> api -> scanner -> context pack -> adapter -> drafts',
+        goalSupport: zh ? '支撑 goalDraft.coreScenarios 中的核心场景' : 'supports each scenario in goalDraft.coreScenarios',
+        gaps: [],
+        evidence: (contextPack && contextPack.entries) ? contextPack.entries.slice(0, 3).map(e => e.path) : [],
+      },
+      modules: [
+        { slug: 'api', role: zh ? 'HTTP 接口层' : 'HTTP surface' },
+        { slug: 'scanner', role: zh ? 'Git 状态读取器' : 'git state reader' },
+      ],
+      features: [
+        { slug: 'git-validation', summary: zh ? '检查 Git 路径并报告仓库状态' : 'inspect a git path and report status' },
+        { slug: 'scanner', summary: zh ? '列出自上次应用以来待分析的提交' : 'enumerate pending commits since last apply' },
+      ],
+    };
+  },
+  async analyzeCommitBatch({ project, commits, contextPack }) {
+    const zh = normalizeKnowledgeLanguage(project && project.knowledgeLanguage) === 'zh-CN';
+    const changes = (commits || []).map(c => {
+      const subject = (c.subject || '').toLowerCase();
+      let classification = 'infrastructure';
+      if (/^feat[:\s]/.test(subject)) classification = 'new-feature';
+      else if (/^fix[:\s]/.test(subject)) classification = 'bug-fix';
+      else if (/^refactor[:\s]/.test(subject)) classification = 'refactor';
+      else if (/^test[:\s]/.test(subject)) classification = 'test-only';
+      else if (/^docs[:\s]/.test(subject)) classification = 'docs-only';
+      const slug = subject.replace(/^[^:]+:\s*/, '').replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '').slice(0, 40) || 'change';
+      return {
+        commit: c.hash,
+        classification,
+        goalImpact: zh ? `[mock] ${classification} 对 ${slug} 的影响` : `[mock] ${classification} for ${slug}`,
+        evidence: contextPack && contextPack.entries ? contextPack.entries.slice(0, 2).map(e => e.path) : [],
+        proposedOps: classification === 'new-feature'
+          ? [{ op: 'create-file', path: `features/${slug}.md`, fromTemplate: 'feature.md' }]
+          : [{ op: 'append-section', path: `changes/${c.short || (c.hash || '').slice(0,7)}.md`, fromTemplate: 'change.md' }],
+      };
+    });
+    return { changes };
+  },
+  validateOutput(output) {
+    if (output && Array.isArray(output.changes)) return validateCommitBatchOutput(output);
+    return validateInitialOutput(output);
+  },
+};
+
+// ---- claude-code-agent: real LLM via Anthropic-compatible API ----
+//
+// This adapter calls an Anthropic Messages API (real Anthropic or any
+// compatible proxy such as api.minimaxi.com/anthropic). The model returns
+// JSON that the KB orchestrator validates against the existing schemas.
+//
+// The adapter is intentionally minimal: it does ONE call per phase
+// (initial or commits) and asks the model to return a strict JSON object
+// matching the schema. Validation happens in `validateOutput`; if the
+// model misbehaves, the run is marked failed and the user can re-trigger.
+
+const { completeJson } = require('./llm-client');
+
+const INITIAL_SYSTEM = `You are a senior software architect analyzing a project's codebase to seed a knowledge base. You MUST respond with a single JSON object that matches the schema in the user message. Do not include commentary, prose, or markdown fences. Do not invent file paths. The project goal and analysis will be reviewed by a human before becoming trusted knowledge; aim for evidence-backed, concise claims.`;
+
+const COMMIT_SYSTEM = `You are a senior software architect reviewing a batch of git commits. For each commit, decide what change should be recorded in the project's knowledge base. Respond with a single JSON object matching the schema in the user message. Do not invent file paths. Cite the provided evidence (context pack entries) whenever possible. Do not propose operations that would write outside features/ or changes/ or modules/ or project-goal.md or project-analysis.md.`;
+
+function buildInitialUser({ project, contextPack }) {
+  const outputLanguage = languageName(project && project.knowledgeLanguage);
+  const ctx = (contextPack && contextPack.entries || []).slice(0, 50).map(e => `- ${e.path}: ${(e.summary || '').slice(0, 200)}`).join('\n');
+  return `Project slug: ${project.slug}
+Display name: ${project.displayName || project.slug}
+Primary language: ${project.primaryLanguage || 'unknown'}
+Tags: ${(project.tags || []).join(', ')}
+Knowledge output language: ${normalizeKnowledgeLanguage(project.knowledgeLanguage)} (${outputLanguage})
+
+Context pack (top entries, latest first):
+${ctx || '(no context pack available)'}
+
+Return a JSON object with these fields:
+{
+  "goalDraft": {
+    "oneSentenceGoal": string,
+    "targetUsers": [string],
+    "coreScenarios": [string],
+    "successCriteria": [string],
+    "nonGoals": [string],
+    "priorityPrinciples": [string]
+  },
+  "analysisDraft": {
+    "purpose": string,
+    "capabilities": [string],
+    "architecture": string,
+    "modules": [{ "slug": string, "role": string }],
+    "dataFlow": string,
+    "goalSupport": string,
+    "gaps": [string],
+    "evidence": [string]
+  },
+  "modules": [{ "slug": string, "role": string }],
+  "features": [{ "slug": string, "summary": string }]
+}
+
+Constraints:
+- All human-readable natural language string values MUST be written in ${outputLanguage}. Keep JSON keys and file paths exactly as specified.
+- All slugs MUST be kebab-case (a-z, 0-9, hyphen).
+- The first two fields (goalDraft, analysisDraft) MUST be present.
+- Do not include any text outside the JSON object.`;
+}
+
+function buildCommitUser({ project, commits, contextPack }) {
+  const outputLanguage = languageName(project && project.knowledgeLanguage);
+  const ctx = (contextPack && contextPack.entries || []).slice(0, 30).map(e => `- ${e.path}: ${(e.summary || '').slice(0, 200)}`).join('\n');
+  const list = (commits || []).map(c => `- full=${c.hash} | short=${c.short || c.hash.slice(0,7)} | ${c.date || ''} | ${c.author || ''} | ${c.subject || ''}`).join('\n');
+  return `Project slug: ${project.slug}
+Knowledge output language: ${normalizeKnowledgeLanguage(project.knowledgeLanguage)} (${outputLanguage})
+
+Pending commits (chronological order, oldest first). For each line, the "full=" value is the COMPLETE 40-character commit hash; you MUST copy that exact value into the JSON "commit" field:
+${list || '(no commits)'}
+
+Context pack excerpts:
+${ctx || '(no context pack available)'}
+
+Return a JSON object of the form:
+{
+  "changes": [
+    {
+      "commit": string,                // FULL 40-char commit hash copied from the input
+      "classification": "new-feature" | "existing-feature-update" | "bug-fix" | "refactor" | "infrastructure" | "test-only" | "docs-only",
+      "goalImpact": string,            // one short sentence
+      "evidence": [string],            // paths cited from the context pack
+      "proposedOps": [{ "op": "create-file" | "append-section" | "update-section", "path": string, "fromTemplate"?: string }]
+    }
+  ]
+}
+
+Constraints:
+- All human-readable natural language string values MUST be written in ${outputLanguage}. Keep JSON keys, enum values, file paths, and commit hashes exactly as specified.
+- One entry per commit in the input list, in the same order.
+- "commit" MUST be the full 40-character hash from the input (the value after "full="), NOT the short hash.
+- proposedOps[].path MUST be a relative path under features/, changes/, modules/, or project-goal.md (the latter only if the change is to the goal).
+- Do not include any text outside the JSON object.`;
+}
+
+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.',
+  async analyzeInitialProject({ project, contextPack }) {
+    const user = buildInitialUser({ project, contextPack });
+    const r = await completeJson({ system: INITIAL_SYSTEM, user, maxTokens: 3000 });
+    if (!r.parsed) {
+      const e = new Error(`LLM returned no parseable JSON (${r.parseError && r.parseError.message || 'no output'})`);
+      e.llmText = r.text;
+      throw e;
+    }
+    return r.parsed;
+  },
+  async analyzeCommitBatch({ project, commits, contextPack }) {
+    const user = buildCommitUser({ project, commits, contextPack });
+    const r = await completeJson({ system: COMMIT_SYSTEM, user, maxTokens: 4096 });
+    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'})`);
+      e.llmText = r.text;
+      throw e;
+    }
+    // Sanity log: how many changes did the LLM return, and what do the commits look like?
+    const changes = (r.parsed && r.parsed.changes) || [];
+    console.log(`[claude-code-agent] parsed ${changes.length} changes; first change: ${JSON.stringify(changes[0]).slice(0, 300)}`);
+    return r.parsed;
+  },
+  validateOutput(output) {
+    if (output && Array.isArray(output.changes)) return validateCommitBatchOutput(output);
+    return validateInitialOutput(output);
+  },
+};
+
+const ADAPTERS = {
+  'mock-agent': mockAgent,
+  'claude-code-agent': claudeCodeAgent,
+};
+
+function getAdapter(id) {
+  return ADAPTERS[id] || null;
+}
+
+function listAdapters() {
+  return Object.values(ADAPTERS).map(a => ({
+    id: a.id,
+    name: a.name,
+    description: a.description || null,
+  }));
+}
+
+module.exports = {
+  ADAPTERS,
+  getAdapter,
+  listAdapters,
+  validateInitialOutput,
+  validateCommitBatchOutput,
+};