@code2knowledge/skill 0.0.0-stage → 1.0.0

package/scripts/lib/notify.mjs

@@ -0,0 +1,90 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import crypto from 'node:crypto';
+import { parse } from 'yaml';
+
+const hash = value => crypto.createHash('sha256').update(JSON.stringify(value)).digest('hex');
+// Escape caller content before placing it in trusted card markdown.
+const escapeMarkdown = value => String(value).slice(0, 2400)
+  .replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
+  .replace(/([\\`*_\[\]~])/g, '\\$1').replace(/\r?\n/g, ' ');
+const inlineCode = value => "`" + String(value).slice(0, 2400).replace(/`/g, 'ˋ').replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/\r?\n/g, ' ') + "`";
+export function buildNotificationCard({ event, task, summary, details = [], test = false }) {
+  const completed = event === 'completed';
+  const section = (title, lines) => ({ tag: 'markdown', content: `**${title}**\n${lines.map(line => `- ${line}`).join('\n')}`, text_align: 'left', text_size: 'normal_v2' });
+  const labelLine = value => {
+    const raw = String(value);
+    const separator = raw.indexOf('：');
+    if (separator < 0 || separator > 30) return escapeMarkdown(raw);
+    const label = raw.slice(0, separator), content = raw.slice(separator + 1).trim();
+    const isLocation = /路径|位置|记录|版本|服务|步骤/.test(label);
+    return `${escapeMarkdown(label)}：${isLocation ? inlineCode(content) : escapeMarkdown(content)}`;
+  };
+  const locations = [], information = [];
+  for (const line of details.slice(0, 8)) {
+    (/^(本机输出位置|输出位置|报告路径|检查记录|产物版本)[：（]/.test(String(line)) ? locations : information).push(labelLine(line));
+  }
+  return {
+    schema: '2.0',
+    config: { update_multi: true, style: { text_size: { normal_v2: { default: 'normal', pc: 'normal', mobile: 'heading' } } } },
+    header: { template: completed ? 'green' : 'orange', title: { tag: 'plain_text', content: `${test ? '【测试】' : ''}Code2Knowledge 任务通知` } },
+    body: { direction: 'vertical', padding: '12px 12px 12px 12px', elements: [
+      section('任务摘要', [
+        `任务：${inlineCode(task)}`,
+        `状态：${completed ? '已导出 ✅ · 业务待审核' : '已暂停 ⏸ · 等待人工处理'}`,
+        ...(test ? ['用途：样式测试，非真实任务'] : []),
+      ]),
+      section(completed ? '任务结果' : '阻塞说明', [escapeMarkdown(summary), ...information]),
+      ...(locations.length ? [section(completed ? '交付位置' : '排查记录', locations)] : []),
+      section('下一步', [completed ? '查看交付物，复核业务口径和未核验项；导出不代表业务审核通过。' : '处理上述阻塞后，回到 Agent 会话回复“继续”，系统将重新检查前置条件。']),
+      { tag: 'markdown', content: '本机路径仅供定位，不是在线访问链接。', text_size: 'notation' },
+    ] },
+  };
+}
+
+export async function notify({ workspace, event, task, summary, details = [], test = false }, { configPath = path.join(os.homedir(), '.code2knowledge', 'config.yml'), fetchImpl = fetch } = {}) {
+  if (!['intervention', 'completed'].includes(event) || !task || !summary || !Array.isArray(details)) throw Error('通知必须包含有效 event、task、summary 和 details 数组');
+  // node:test propagates this context to spawned CLI children. Never use real transport in tests.
+  if ((process.env.NODE_TEST_CONTEXT || process.env.C2K_NOTIFICATIONS_DISABLED === '1') && fetchImpl === fetch) return { status: 'skipped', reason: 'test_or_disabled' };
+  const payload = { event, task, summary, details: details.filter(line => !String(line).startsWith('检查记录：')) };
+  const id = hash(payload);
+  const dir = path.join(workspace, 'notifications');
+  await fs.mkdir(dir, { recursive: true });
+  const recordPath = path.join(dir, `${id}.json`);
+  const lockPath = `${recordPath}.lock`;
+  let lock;
+  try { lock = await fs.open(lockPath, 'wx'); }
+  catch (error) { if (error.code === 'EEXIST') return { status: 'in_progress', recordPath }; throw error; }
+  try {
+    try {
+      const previous = JSON.parse(await fs.readFile(recordPath, 'utf8'));
+      if (previous.status === 'sent') return { ...previous, duplicate: true, recordPath };
+    } catch (error) { if (error.code !== 'ENOENT') throw error; }
+    let status = 'skipped', reason = 'not_configured';
+    try {
+      let config;
+      try { config = parse(await fs.readFile(configPath, 'utf8')); }
+      catch (error) { if (error.code !== 'ENOENT') throw error; }
+      const settings = config?.notification?.feishu;
+      if (settings?.enabled === true) {
+        const url = new URL(settings.webhook_url);
+        if (url.protocol !== 'https:' || !['open.feishu.cn', 'open.larksuite.com'].includes(url.hostname) || !url.pathname.startsWith('/open-apis/bot/v2/hook/')) throw Error('invalid_config');
+        const body = { msg_type: 'interactive', card: buildNotificationCard({ event, task, summary, details, test }) };
+        if (settings.secret) {
+          body.timestamp = String(Math.floor(Date.now() / 1000));
+          body.sign = crypto.createHmac('sha256', `${body.timestamp}\n${settings.secret}`).update('').digest('base64');
+        }
+        const response = await fetchImpl(url.href, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(body), signal: AbortSignal.timeout(10000), redirect: 'error' });
+        if (!response.ok) throw Error('http_error');
+        const result = await response.json();
+        if (result.code !== 0 && result.StatusCode !== 0) throw Error('provider_rejected');
+        status = 'sent'; reason = null;
+      }
+    } catch { status = 'failed'; reason = '配置、网络或飞书响应异常；请检查本机通知配置及机器人状态'; }
+    // Do not persist webhook, secret, response body or potentially sensitive error messages.
+    const record = { id, event, task, status, reason, timestamp: new Date().toISOString() };
+    await fs.writeFile(recordPath, JSON.stringify(record, null, 2), { mode: 0o600 });
+    return { ...record, recordPath };
+  } finally { await lock.close(); await fs.unlink(lockPath); }
+}

package/scripts/lib/preflight.mjs

@@ -0,0 +1,63 @@
+import { notify } from './notify.mjs';
+import crypto from 'node:crypto';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+const exec = promisify(execFile);
+export function requireDocumentChoice(payload) {
+  if (!Object.hasOwn(payload, 'rawDocsDir') || typeof payload.rawDocsDir !== 'string') throw Error('需要人工选择文档资料：显式提供 rawDocsDir（不添加时为空字符串）');
+}
+export async function syncMaster(repoDirs, { inspect, workspace }) {
+  const report = { checkedAt: new Date().toISOString(), status: 'running', repositories: [] };
+  const git = async (cwd, ...args) => (await exec('git', args, { cwd, timeout: 60000, maxBuffer: 1024 * 1024, env: { ...process.env, GIT_TERMINAL_PROMPT: '0' } })).stdout.trim();
+  let step = '工作区检查', current;
+  try {
+    for (const dir of [...new Set(repoDirs)]) {
+      current = { path: dir, status: 'pending' }; report.repositories.push(current);
+      const info = await inspect(dir);
+      if (info.worktreeStatus !== 'clean') throw Error('工作区不是 clean，保留改动并请求人工处理');
+      current.originalCommit = await git(dir, 'rev-parse', 'HEAD');
+      current.originalBranch = await git(dir, 'rev-parse', '--abbrev-ref', 'HEAD');
+      for (const marker of ['MERGE_HEAD', 'CHERRY_PICK_HEAD', 'REVERT_HEAD', 'rebase-merge', 'rebase-apply', 'sequencer']) {
+        const markerPath = await git(dir, 'rev-parse', '--git-path', marker);
+        try { await fs.access(path.resolve(dir, markerPath)); } catch (e) { if (e.code === 'ENOENT') continue; throw e; }
+        throw Error(`存在未完成 Git 操作：${marker}`);
+      }
+    }
+    for (const item of report.repositories) {
+      current = item; const dir = item.path;
+      step = 'fetch origin/master';
+      await git(dir, 'fetch', 'origin', '+refs/heads/master:refs/remotes/origin/master');
+      const remote = await git(dir, 'rev-parse', 'refs/remotes/origin/master');
+      let local;
+      try { local = await git(dir, 'rev-parse', '--verify', 'refs/heads/master'); } catch { /* Create tracking branch below. */ }
+      if (local) {
+        step = 'master 快进可行性检查';
+        await git(dir, 'merge-base', '--is-ancestor', local, remote);
+      }
+      step = '切换 master';
+      if (local) await git(dir, 'switch', 'master');
+      else await git(dir, 'switch', '--track', '-c', 'master', 'origin/master');
+      step = 'pull master'; await git(dir, 'pull', '--ff-only', 'origin', 'master');
+      step = '最终版本检查';
+      item.commit = await git(dir, 'rev-parse', 'HEAD');
+      if (item.commit !== await git(dir, 'rev-parse', 'refs/remotes/origin/master') || await git(dir, 'branch', '--show-current') !== 'master' || (await inspect(dir)).worktreeStatus !== 'clean') throw Error('master 版本或工作区状态不一致');
+      item.status = 'passed';
+    }
+    report.status = 'passed';
+  } catch (error) {
+    report.status = 'blocked';
+    if (current) { current.status = 'blocked'; current.step = step; }
+    // Keep credentials from remote URLs out of persisted diagnostics.
+    report.error = `master 检查失败：${step}；请人工检查仓库、分支、网络和权限，处理后重试`;
+  }
+  const dir = path.join(workspace, 'preflight'); await fs.mkdir(dir, { recursive: true });
+  const recordPath = path.join(dir, `${Date.now()}-${crypto.randomUUID()}.json`);
+  await fs.writeFile(recordPath, JSON.stringify(report, null, 2));
+  if (report.status !== 'passed') {
+    try { await notify({ workspace, event: 'intervention', task: current?.path || workspace, summary: report.error, details: [`仓库：${current?.path}`, `检查记录：${recordPath}`] }); } catch { /* Preserve the original blocker. */ }
+    throw Error(`${report.error}；仓库：${current?.path}；检查记录：${recordPath}`);
+  }
+  return { ...report, recordPath };
+}

package/scripts/lib/wizard.mjs

@@ -0,0 +1,205 @@
+import { syncMaster } from "./preflight.mjs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import crypto from "node:crypto";
+import {
+  workspaceDir, listMaterials, readMaterial, readRun, inspectRepository,
+  checkMaterial, buildKnowledgeBase, createCenterMaterial, inferBusinessSlug, assertBusinessSlug,
+} from "./knowledge.mjs";
+
+const wizardRoot = path.join(workspaceDir, "wizards");
+const intents = new Set(["new", "reuse", "resume", "material"]);
+const textFields = ["productName", "productSlug", "domainName", "domainSlug", "domainScope", "rawDocsDir", "outputRootDir", "contextMode"];
+const byRecent = (a, b) => String(b.updatedAt || b.createdAt || "").localeCompare(String(a.updatedAt || a.createdAt || ""));
+const isMissing = (value) => typeof value !== "string" || !value.trim();
+
+async function directoryEntries(dir) {
+  try { return await fs.readdir(dir, { withFileTypes: true }); }
+  catch (error) { if (error.code === "ENOENT") return []; throw error; }
+}
+
+export async function listRuns() {
+  const result = [];
+  for (const entry of await directoryEntries(path.join(workspaceDir, "runs"))) {
+    if (!entry.isDirectory()) continue;
+    try { result.push(await readRun(path.join(workspaceDir, "runs", entry.name))); }
+    catch { /* Incomplete/legacy directories must not prevent discovery. */ }
+  }
+  return result.sort(byRecent);
+}
+
+function wizardFile(id) {
+  if (typeof id !== "string" || !/^[a-zA-Z0-9-]{1,80}$/.test(id)) throw new Error("向导编号无效");
+  return path.join(wizardRoot, `${id}.json`);
+}
+
+export async function readWizard(id) {
+  const wizard = JSON.parse(await fs.readFile(wizardFile(id), "utf8"));
+  if (wizard.version !== 1 || wizard.wizardId !== id || !intents.has(wizard.intent)) throw new Error("向导记录无效");
+  return wizard;
+}
+
+async function listWizards() {
+  const result = [];
+  for (const entry of await directoryEntries(wizardRoot)) {
+    if (!entry.isFile() || !entry.name.endsWith(".json")) continue;
+    try {
+      const wizard = await readWizard(entry.name.slice(0, -5));
+      if (wizard.status !== "started") result.push(wizard);
+    } catch { /* Ignore incomplete checkpoint files. */ }
+  }
+  return result.sort(byRecent);
+}
+
+// Read local manifests only; no source extraction or whole-machine discovery.
+export async function discoverWorkspace() {
+  const [materials, runs, wizards] = await Promise.all([listMaterials(), listRuns(), listWizards()]);
+  const products = new Map();
+  for (const item of [...materials, ...runs]) {
+    if (!products.has(item.productSlug)) products.set(item.productSlug, {
+      productName: item.productName, productSlug: item.productSlug, domains: [],
+    });
+    const product = products.get(item.productSlug);
+    if (item.domainName && !product.domains.includes(item.domainName)) product.domains.push(item.domainName);
+  }
+  let currentRepository = null;
+  // Only consider the exact current directory; do not search parents or siblings for repositories.
+  if ((await directoryEntries(process.cwd())).some((entry) => entry.name === ".git")) {
+    try { currentRepository = await inspectRepository(process.cwd()); } catch { /* Optional candidate. */ }
+  }
+  const resumable = runs.filter((run) => run.status !== "exported");
+  const menu = [];
+  if (wizards.length || resumable.length) menu.push({ id: "resume", label: "继续上次任务", description: "保留已填信息和分析进度" });
+  if (materials.length) menu.push({ id: "reuse", label: "复用共享原料，整理业务域", description: "沿用业务中心和仓库，不重复填写" });
+  menu.push({ id: "new", label: "新建业务中心或共享原料", description: "使用当前仓库，或添加其他仓库" });
+  const limit = 8;
+  return {
+    workspaceDir, projectDir: process.cwd(), currentRepository, menu,
+    defaults: { outputRootDir: process.cwd(), rawDocsDir: "", contextMode: "repomix" },
+    products: [...products.values()],
+    materials: materials.slice(0, limit).map((item) => ({ materialId: item.materialId, materialDir: item.materialDir,
+      productName: item.productName, productSlug: item.productSlug, createdAt: item.createdAt, repositories: item.repositories.map((repo) => repo.name), freshness: "unchecked" })),
+    runs: resumable.slice(0, limit).map((run) => ({ runId: run.runId, runDir: run.runDir,
+      productName: run.productName, productSlug: run.productSlug, domainName: run.domainName, domainSlug: run.domainSlug, domainScope: run.domainScope,
+      status: run.status, updatedAt: run.updatedAt, materialDir: run.materialDir })),
+    wizards: wizards.slice(0, limit).map((wizard) => ({ wizardId: wizard.wizardId, intent: wizard.intent,
+      productName: wizard.answers.productName, domainName: wizard.answers.domainName,
+      nextStep: wizard.nextStep, updatedAt: wizard.updatedAt })),
+    totals: { materials: materials.length, runs: resumable.length, wizards: wizards.length },
+  };
+}
+
+async function persist(wizard) {
+  await fs.mkdir(wizardRoot, { recursive: true });
+  const file = wizardFile(wizard.wizardId);
+  const temporary = `${file}.${crypto.randomUUID()}.tmp`;
+  await fs.writeFile(temporary, JSON.stringify(wizard, null, 2) + "\n");
+  await fs.rename(temporary, file);
+  return { ...wizard, wizardPath: file };
+}
+
+// Save only choices the user actually made; missing answers are reported, never inferred.
+export async function saveWizard(input) {
+  if (!input || typeof input !== "object" || Array.isArray(input)) throw new Error("向导输入必须为对象");
+  for (const key of Object.keys(input)) {
+    if (!["wizardId", "intent", "answers", "materialDir", "runDir"].includes(key)) throw new Error(`未知向导参数：${key}`);
+  }
+  const previous = input.wizardId ? await readWizard(input.wizardId) : null;
+  if (previous?.status === "started") throw new Error("向导已启动，请继续对应任务或新建向导");
+  const intent = input.intent || previous?.intent;
+  if (!intents.has(intent)) throw new Error("请选择 new / reuse / resume / material");
+  const patch = input.answers || {};
+  if (typeof patch !== "object" || Array.isArray(patch)) throw new Error("answers 必须为对象");
+  for (const [key, value] of Object.entries(patch)) {
+    if (!textFields.includes(key) && key !== "repoDirs") throw new Error(`未知向导字段：${key}`);
+    if (key === "repoDirs") {
+      if (!Array.isArray(value) || value.some((dir) => typeof dir !== "string" || !dir.trim())) throw new Error("repoDirs 必须为路径列表");
+    } else if (typeof value !== "string") throw new Error(`${key} 必须为文本`);
+  }
+  const answers = { contextMode: "repomix", ...previous?.answers, ...patch };
+  // A domain change is a new scope decision unless the same answer supplies its scope.
+  if (previous?.answers.domainName && patch.domainName !== undefined &&
+      patch.domainName !== previous.answers.domainName && patch.domainScope === undefined) delete answers.domainScope;
+  for (const [nameField, slugField] of [["productName", "productSlug"], ["domainName", "domainSlug"]]) {
+    if (patch[nameField] !== undefined && patch[nameField] !== previous?.answers[nameField] && patch[slugField] === undefined) delete answers[slugField];
+    if (isMissing(answers[slugField])) {
+      const inferred = inferBusinessSlug(answers[nameField]);
+      if (inferred) answers[slugField] = inferred;
+      else delete answers[slugField];
+    }
+    if (answers[slugField] !== undefined) assertBusinessSlug(answers[slugField], slugField);
+  }
+  if (!["source-index", "repomix"].includes(answers.contextMode)) throw new Error("contextMode 无效");
+  // Discovery suggests a destination; only an explicit user answer selects it.
+  if (!isMissing(answers.outputRootDir)) answers.outputRootDir = path.resolve(previous?.projectDir || process.cwd(), answers.outputRootDir);
+  else delete answers.outputRootDir;
+  if (answers.rawDocsDir) answers.rawDocsDir = path.resolve(previous?.projectDir || process.cwd(), answers.rawDocsDir);
+  if (answers.repoDirs) answers.repoDirs = [...new Set(answers.repoDirs.map((dir) => path.resolve(previous?.projectDir || process.cwd(), dir)))];
+  const materialDir = input.materialDir ?? previous?.materialDir;
+  const runDir = input.runDir ?? previous?.runDir;
+  if (intent === "reuse" && materialDir) {
+    const material = await readMaterial(materialDir);
+    Object.assign(answers, { productName: material.productName, productSlug: assertBusinessSlug(material.productSlug, "productSlug"), repoDirs: material.repositories.map((repo) => repo.path),
+      rawDocsDir: material.rawDocsDir || "", contextMode: material.contextMode || "repomix" });
+  }
+  if (intent === "resume" && runDir) {
+    const run = await readRun(runDir);
+    Object.assign(answers, { productName: run.productName, productSlug: run.productSlug, domainName: run.domainName, domainSlug: run.domainSlug,
+      domainScope: run.domainScope, outputRootDir: run.outputRootDir });
+  }
+  const missingFields = [];
+  if (intent === "resume") { if (!runDir) missingFields.push("runDir"); }
+  else {
+    if (intent !== "reuse" && !Object.hasOwn(answers, "rawDocsDir")) missingFields.push("rawDocsDir");
+    if (intent === "reuse" && !materialDir) missingFields.push("materialDir");
+    if (intent !== "reuse" && isMissing(answers.productName)) missingFields.push("productName");
+    if (isMissing(answers.productSlug)) missingFields.push("productSlug");
+    if (intent !== "material" && isMissing(answers.domainName)) missingFields.push("domainName");
+    if (intent !== "material" && isMissing(answers.domainSlug)) missingFields.push("domainSlug");
+    if (intent !== "reuse" && !answers.repoDirs?.length && !answers.rawDocsDir) missingFields.push("repoDirs");
+    if (intent !== "material" && isMissing(answers.domainScope)) missingFields.push("domainScope");
+    if (intent !== "material" && isMissing(answers.outputRootDir)) missingFields.push("outputRootDir");
+  }
+  const wizard = {
+    version: 1, wizardId: previous?.wizardId || crypto.randomUUID(), intent,
+    status: missingFields.length ? "collecting" : "ready",
+    projectDir: previous?.projectDir || process.cwd(), createdAt: previous?.createdAt || new Date().toISOString(),
+    updatedAt: new Date().toISOString(), answers,
+    ...(materialDir ? { materialDir } : {}), ...(runDir ? { runDir } : {}),
+    ...(answers.outputRootDir && /^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(answers.productSlug || "") && /^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(answers.domainSlug || "") ? {
+      exportDirPreview: path.join(answers.outputRootDir, "code-knowledge", answers.productSlug, answers.domainSlug),
+    } : {}),
+    missingFields, nextStep: missingFields[0] || "start",
+  };
+  return persist(wizard);
+}
+
+export async function startWizard(id) {
+  const wizard = await readWizard(id);
+  if (wizard.status === "started") {
+    const result = wizard.intent === "material" ? await readMaterial(wizard.materialDir) : await readRun(wizard.runDir);
+    await syncMaster((await readMaterial(result.materialDir)).repositories.map(repo => repo.path), { inspect: inspectRepository, workspace: workspaceDir });
+    const freshness = await checkMaterial(result.materialDir);
+    if (!freshness.reusable) throw new Error("原料已过期，请刷新后继续");
+    return { wizard, result, alreadyStarted: true };
+  }
+  if (["new", "material"].includes(wizard.intent) && !Object.hasOwn(wizard.answers, "rawDocsDir")) throw new Error("请先选择是否添加文档资料（rawDocsDir）");
+  if (wizard.status !== "ready") throw new Error(`向导尚未完成：${wizard.missingFields.join(", ")}`);
+  let result;
+  if (wizard.intent === "resume") {
+    result = await readRun(wizard.runDir);
+    await syncMaster((await readMaterial(result.materialDir)).repositories.map(repo => repo.path), { inspect: inspectRepository, workspace: workspaceDir });
+    if (!(await checkMaterial(result.materialDir)).reusable) throw new Error("原料已过期，请刷新后继续");
+  }
+  else if (wizard.intent === "material") result = await createCenterMaterial(wizard.answers);
+  else {
+    if (wizard.intent === "reuse") {
+      const check = await checkMaterial(wizard.materialDir);
+      if (!check.reusable) throw new Error("共享原料版本已变化或工作区未核验，请选择刷新原料或其他原料；已填业务域信息已保留");
+    }
+    result = await buildKnowledgeBase({ ...wizard.answers, ...(wizard.intent === "reuse" ? { materialDir: wizard.materialDir } : {}) });
+  }
+  const updated = await persist({ ...wizard, status: "started", updatedAt: new Date().toISOString(),
+    ...(result.runDir ? { runDir: result.runDir } : {}), ...(result.materialDir ? { materialDir: result.materialDir } : {}) });
+  return { wizard: updated, result, alreadyStarted: false };
+}

package/scripts/postinstall.mjs

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+import { ensureConfig } from './lib/config.mjs';
+try {
+  const configPath = await ensureConfig();
+  console.log(`Code2Knowledge 通知配置已就绪（保留已有配置）：${configPath}；模板默认关闭通知。`);
+} catch {
+  console.warn('Code2Knowledge 无法初始化通知模板；运行 code2knowledge 注册时将重试。');
+}

package/scripts/register.mjs

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+import { ensureConfig } from "./lib/config.mjs";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { createInterface } from "node:readline/promises";
+
+const skillDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+export const supportedAgents = ["codex", "claude", "cursor", "gemini", "copilot"];
+const marker = "code2knowledge-managed-entry-v1";
+
+async function writeManaged(file, content, dryRun) {
+  let previous;
+  try { previous = await fs.readFile(file, "utf8"); }
+  catch (error) { if (error.code !== "ENOENT") throw error; }
+  if (previous !== undefined && previous !== content && !previous.includes(marker)) {
+    throw new Error(`已有同名入口，未覆盖：${file}`);
+  }
+  if (!dryRun) {
+    await fs.mkdir(path.dirname(file), { recursive: true });
+    await fs.writeFile(file, content);
+  }
+  return file;
+}
+
+async function linkSkill(target, source, dryRun) {
+  try {
+    const existing = await fs.realpath(target);
+    if (existing !== await fs.realpath(source)) throw new Error(`已有同名 Skill，未覆盖：${target}`);
+    return target;
+  } catch (error) { if (error.code !== "ENOENT") throw error; }
+  // Dangling symlinks are also existing entries; never replace them implicitly.
+  try { await fs.lstat(target); throw new Error(`已有损坏入口，未覆盖：${target}`); }
+  catch (error) { if (error.code !== "ENOENT") throw error; }
+  if (!dryRun) {
+    await fs.mkdir(path.dirname(target), { recursive: true });
+    await fs.symlink(source, target, process.platform === "win32" ? "junction" : "dir");
+  }
+  return target;
+}
+
+export async function register({ agent, scope = "user", projectDir = process.cwd(), userHome = os.homedir(), source = skillDir, dryRun = false }) {
+  if (!supportedAgents.includes(agent)) throw new Error(`不支持的 Agent：${agent}`);
+  if (!["user", "project"].includes(scope)) throw new Error("scope 必须为 user 或 project");
+  const root = scope === "user" ? userHome : path.resolve(projectDir);
+  const instruction = `读取 ${JSON.stringify(path.join(source, "SKILL.md"))} 并遵循其完整流程。用户已启动 code2knowledge；先只读发现当前工作区的历史任务和共享原料，按 SKILL.md 用宿主提问工具呈现轻量选择向导；选择优先贯穿所有步骤：有可靠候选且有可用结构化提问工具时必须调用，推荐答案和自定义入口统一呈现，最后的导出位置也不能降级成文本编号；选择自定义后才补问缺失文本，工具原生自由输入不重复添加其他项。只有工具确实不可用或失败且无替代时才能用编号兜底并说明原因。中心和域的命名选项同时展示中文名称与英文目录标识，目录禁用中文；将业务域名、业务域边界说明和知识库导出位置作为明确引导项；新建原料确定仓库后必须通过结构化选择询问是否添加 PRD、ERD 等文档资料，选择添加后收集本地资料目录；默认空值不是用户已拒绝，启动前须完成选择。已有信息不重复问，复用沿用原资料，导出位置需用户选定。正式逆向前按 execution.md 检查全部依赖仓库，自动切换 master 并从 origin 快进拉取；失败停止请求人工介入，不强制覆盖或清理改动。当前 Agent 直接执行分析，不要启动其他 Agent CLI。若用户已提供信息，沿用并只问缺失项。`;
+  const files = [];
+  let invocation = "/code2knowledge";
+  if (agent === "codex" || agent === "claude") {
+    const dir = agent === "codex" ? ".agents" : ".claude";
+    files.push(await linkSkill(path.join(root, dir, "skills", "code2knowledge"), source, dryRun));
+    if (agent === "codex") invocation = "$code2knowledge";
+  } else if (agent === "cursor") {
+    files.push(await writeManaged(path.join(root, ".cursor", "commands", "code2knowledge.md"),
+      `<!-- ${marker} -->\n# Code2Knowledge\n\n${instruction}\n`, dryRun));
+  } else if (agent === "gemini") {
+    files.push(await writeManaged(path.join(root, ".gemini", "commands", "code2knowledge.toml"),
+      `# ${marker}\ndescription = "启动代码业务知识库问答向导"\nprompt = ${JSON.stringify(instruction)}\n`, dryRun));
+  } else {
+    if (scope === "user") throw new Error("Copilot 入口按项目注册，请使用 --scope project --project <目录>");
+    files.push(await writeManaged(path.join(root, ".github", "prompts", "code2knowledge.prompt.md"),
+      `---\ndescription: "启动代码业务知识库问答向导"\nagent: "agent"\n---\n<!-- ${marker} -->\n${instruction}\n`, dryRun));
+    files.push(await linkSkill(path.join(root, ".github", "skills", "code2knowledge"), source, dryRun));
+  }
+  const configPath = await ensureConfig({ userHome, dryRun });
+  return { agent, scope, files, invocation, configPath, naturalLanguage: "code2knowledge", dryRun };
+}
+
+export async function main(argv = process.argv.slice(2)) {
+  const options = {};
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--dry-run") options.dryRun = true;
+    else if (["--agent", "--scope", "--project"].includes(arg) && argv[i + 1] && !argv[i + 1].startsWith("--")) options[arg.slice(2)] = argv[++i];
+    else if (arg === "--help") { console.log("code2knowledge --agent codex|claude|cursor|gemini|copilot|all [--scope user|project] [--project DIR] [--dry-run]"); return; }
+    else throw new Error(`参数无效：${arg}`);
+  }
+  if (!options.agent) {
+    if (!process.stdin.isTTY) throw new Error("非交互环境请指定 --agent codex|claude|cursor|gemini|copilot|all");
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+      console.log("选择 Agent：1 Codex（默认）  2 Claude Code  3 Cursor  4 Gemini CLI  5 Copilot  6 全部");
+      const answer = (await rl.question("输入编号：")).trim() || "1";
+      options.agent = [...supportedAgents, "all"][Number(answer) - 1];
+      if (!options.agent) throw new Error("请选择 1 至 6");
+      if (!options.scope) {
+        const answer = (await rl.question("注册范围：1 当前用户（默认，Copilot 使用当前项目）  2 当前项目：")).trim() || "1";
+        if (!["1", "2"].includes(answer)) throw new Error("请选择 1 或 2");
+        options.scope = answer === "2" ? "project" : "user";
+      }
+    } finally { rl.close(); }
+  }
+  options.scope ||= "user";
+  const agents = options.agent === "all" ? supportedAgents : [options.agent];
+  const results = [];
+  for (const agent of agents) {
+    results.push(await register({ agent, scope: agent === "copilot" && options.agent === "all" ? "project" : options.scope,
+      projectDir: options.project, dryRun: options.dryRun }));
+  }
+  console.log(JSON.stringify(results, null, 2));
+  console.log("注册完成后重新打开 Agent。在 Codex 输入 $code2knowledge，其他 Agent 使用 /code2knowledge。Codex/Claude 也可输入 code2knowledge 自然触发；未匹配时使用原生入口。按提问回答即可。");
+}
+
+if (process.argv[1] && await fs.realpath(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  main().catch((error) => { console.error(error.message); process.exitCode = 1; });
+}

package/scripts/setup.mjs

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+// npm bin wrapper: execute through global-bin symlinks as well as direct paths.
+import { main } from "./register.mjs";
+const args = process.argv.slice(2);
+if (args[0] === "register") args.shift();
+main(args).catch((error) => {
+  console.error(error.message);
+  process.exitCode = 1;
+});