@validflow/ccneed-cli 0.1.5 → 0.1.7

package/scripts/npm/plugin.mjs

@@ -0,0 +1,441 @@
+import { lstatSync, readFileSync, mkdirSync, writeFileSync, renameSync, unlinkSync } from 'node:fs';
+import { delimiter, dirname, isAbsolute, join, resolve } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+
+const hostDirs = { codex: '.codex', claude: '.claude', workbuddy: '.workbuddy' };
+const commands = ['ccneed', 'ccneed.cmd', 'ccneed.exe'];
+const exec = promisify(execFile);
+
+/** fileText 只读取普通配置文件，拒绝链接和过大的配置。
+ * Args:
+ *   path: 当前选中宿主的配置路径。
+ * Returns:
+ *   文件原文或 null。
+ * Errors:
+ *   特殊文件、链接或读取失败返回异常。
+ */
+function fileText(path) {
+  let stat;
+  try { stat = lstatSync(path); } catch (error) { if (error.code === 'ENOENT') return null; throw error; }
+  if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 1024 * 1024) throw new Error('Plugin config must be a bounded regular file: ' + path);
+  return readFileSync(path, 'utf8');
+}
+
+/** checkParents 禁止宿主目录通过链接重定向安装写入。
+ * Args:
+ *   home: 安装目标的明确用户目录。
+ *   directory: 当前文件的父目录。
+ * Errors:
+ *   越界路径、父目录链接或特殊文件返回异常。
+ */
+function checkParents(home, directory) {
+  const root = resolve(home);
+  const target = resolve(directory);
+  if (target !== root && !target.startsWith(root + (process.platform === 'win32' ? '\\' : '/'))) throw new Error('Plugin target is outside the selected home');
+  const paths = [];
+  for (let path = target; path !== root; path = dirname(path)) paths.push(path);
+  for (const path of [root, ...paths.reverse()]) {
+    let stat;
+    try { stat = lstatSync(path); } catch (error) { if (error.code === 'ENOENT') continue; throw error; }
+    if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error('Plugin parent must be a plain directory: ' + path);
+  }
+}
+
+/** hookHandler 重建旧安装器生成的 handler，仅用于识别可迁移配置。
+ * Args:
+ *   root: 固定全局 npm 包目录。
+ *   host: 明确选择的宿主。
+ *   node: 旧 handler 中的 Node 路径，不会执行。
+ * Returns:
+ *   不经动态 shell 插值的命令配置。
+ * Errors:
+ *   路径包含换行或 NUL 时拒绝生成配置。
+ */
+function hookHandler(root, host, node = process.execPath) {
+  const args = [node, join(root, 'skills', 'ccneed', 'scripts', 'acquisition.mjs'), '--host', host];
+  if (args.some(value => /[\r\n\0]/.test(value))) throw new Error('Invalid hook path');
+  const posix = args.map(value => "'" + value.replaceAll("'", "'\\''") + "'").join(' ');
+  const powershell = '& ' + args.map(value => "'" + value.replaceAll("'", "''") + "'").join(' ');
+  if (host === 'codex') return { type: 'command', command: posix, commandWindows: powershell, timeout: 10 };
+  return { type: 'command', command: process.platform === 'win32' ? powershell : posix, ...(process.platform === 'win32' ? { shell: 'powershell' } : {}), timeout: 10 };
+}
+
+/** sameConfig 比较配置语义，避免 JSON 键序或缩进影响自有配置识别。
+ * Args:
+ *   left: 待检查配置。
+ *   right: 已知安装器配置。
+ * Returns:
+ *   两份配置是否相同。
+ */
+function sameConfig(left, right) {
+  const canonical = value => Array.isArray(value) ? value.map(canonical) : value && typeof value === 'object' ? Object.fromEntries(Object.keys(value).sort().map(key => [key, canonical(value[key])])) : value;
+  return JSON.stringify(canonical(left)) === JSON.stringify(canonical(right));
+}
+
+/** ownedLegacyHandler 识别完整旧模板，不把路径包含关键字当作所有权证明。
+ * Args:
+ *   handler: 用户配置中的一条 handler。
+ *   root: 稳定全局包目录。
+ *   host: 当前宿主。
+ * Returns:
+ *   handler 是否为未定制的旧安装器输出。
+ */
+function ownedLegacyHandler(handler, root, host) {
+  if (!handler || typeof handler.command !== 'string') return false;
+  const match = /^(?:& )?'((?:[^']|'')*)'\s/.exec(handler.command);
+  const node = match?.[1]?.replaceAll("''", "'");
+  if (!node || !/(?:^|[\\/])node(?:\.exe)?$/i.test(node)) return false;
+  return sameConfig(handler, hookHandler(root, host, node));
+}
+
+/** removeOwnedHooks 只清理旧安装器原样生成的全局 hooks，保留定制 handler。
+ * Args:
+ *   settings: 当前用户配置对象。
+ *   root: 稳定全局包目录。
+ *   host: 当前宿主。
+ * Returns:
+ *   是否移除了旧安装器 handler。
+ * Errors:
+ *   hooks 配置格式无效时停止。
+ */
+function removeOwnedHooks(settings, root, host) {
+  if (settings.hooks === undefined) return false;
+  if (!settings.hooks || Array.isArray(settings.hooks) || typeof settings.hooks !== 'object') throw new Error('Plugin hooks must be a JSON object');
+  let removed = false;
+  for (const event of ['SessionStart', 'PreToolUse', 'PostToolUse']) {
+    const entries = settings.hooks[event];
+    if (entries === undefined) continue;
+    if (!Array.isArray(entries)) throw new Error('Plugin event hooks must be an array');
+    settings.hooks[event] = entries.flatMap(entry => {
+      const matcher = event === 'SessionStart' ? undefined : 'Bash|PowerShell|exec_command';
+      if (!entry || entry.matcher !== matcher || !Array.isArray(entry.hooks) || Object.keys(entry).some(key => !['matcher', 'hooks'].includes(key))) return [entry];
+      const hooks = entry.hooks.filter(handler => !ownedLegacyHandler(handler, root, host));
+      if (hooks.length === entry.hooks.length) return [entry];
+      removed = true;
+      return hooks.length ? [{ ...entry, hooks }] : [];
+    });
+    if (!settings.hooks[event].length) delete settings.hooks[event];
+  }
+  if (!Object.keys(settings.hooks).length) delete settings.hooks;
+  return removed;
+}
+
+/** removeOwnedAskRules 在存在旧安装器 hook 证据时清理其通用 ask 规则。
+ * Args:
+ *   settings: 当前用户配置。
+ * Errors:
+ *   permissions 配置格式无效时停止。
+ */
+function removeOwnedAskRules(settings) {
+  if (settings.permissions === undefined) return;
+  const permissions = settings.permissions;
+  if (!permissions || Array.isArray(permissions) || typeof permissions !== 'object') throw new Error('Plugin permissions must be a JSON object');
+  if (permissions.ask === undefined) return;
+  if (!Array.isArray(permissions.ask) || permissions.ask.some(value => typeof value !== 'string')) throw new Error('Plugin ask rules must be strings');
+  const owned = new Set(commands.flatMap(binary => ['Bash', 'PowerShell'].flatMap(tool => [`${tool}(${binary} kb start *)`, `${tool}(${binary} tasks reply *)`])));
+  permissions.ask = permissions.ask.filter(value => !owned.has(value));
+  if (!permissions.ask.length) delete permissions.ask;
+  if (!Object.keys(permissions).length) delete settings.permissions;
+}
+
+/** mergeSettings 清理自有旧 hooks，仅为 WorkBuddy 保留独立原生执行规则。
+ * Args:
+ *   before: 已有配置原文或 null。
+ *   root: 固定全局 npm 包目录。
+ *   host: 明确选择的宿主。
+ * Returns:
+ *   合并后的 JSON 配置原文；无变化时保留原文。
+ * Errors:
+ *   配置格式无效时停止；自定义 handler 原样保留。
+ */
+function mergeSettings(before, root, host) {
+  const settings = before === null ? {} : JSON.parse(before.replace(/^\uFEFF/, ''));
+  if (!settings || Array.isArray(settings) || typeof settings !== 'object') throw new Error('Plugin settings must be a JSON object');
+  const previous = JSON.stringify(settings);
+  if (removeOwnedHooks(settings, root, host) && host !== 'codex') removeOwnedAskRules(settings);
+  if (host === 'workbuddy') {
+    settings.permissions ??= {};
+    if (!settings.permissions || Array.isArray(settings.permissions) || typeof settings.permissions !== 'object') throw new Error('WorkBuddy permissions must be a JSON object');
+    const permissionAsk = settings.permissions.ask ?? [];
+    if (!Array.isArray(permissionAsk) || permissionAsk.some(value => typeof value !== 'string')) throw new Error('WorkBuddy ask rules must be strings');
+    const compatibleAsk = commands.flatMap(binary => ['Bash', 'PowerShell'].flatMap(tool => [`${tool}(${binary} kb start *)`, `${tool}(${binary} tasks reply *)`]));
+    settings.permissions.ask = [...new Set([...permissionAsk, ...compatibleAsk])];
+    settings.sandbox ??= {};
+    if (!settings.sandbox || Array.isArray(settings.sandbox) || typeof settings.sandbox !== 'object') throw new Error('WorkBuddy sandbox must be a JSON object');
+    settings.sandbox.commandSafety ??= {};
+    const safety = settings.sandbox.commandSafety;
+    if (!safety || Array.isArray(safety) || typeof safety !== 'object') throw new Error('WorkBuddy command safety must be a JSON object');
+    const ask = safety.ask ?? [];
+    if (!Array.isArray(ask) || ask.some(rule => !Array.isArray(rule?.prefix) || !rule.prefix.length || rule.prefix.some(value => typeof value !== 'string'))) throw new Error('WorkBuddy command safety ask rules must contain command prefixes');
+    const added = commands.flatMap(binary => [['kb', 'start'], ['tasks', 'reply']].map(words => ({ prefix: [binary, ...words] })));
+    safety.ask = [...ask, ...added.filter(rule => !ask.some(existing => JSON.stringify(existing.prefix) === JSON.stringify(rule.prefix)))];
+  }
+  return previous === JSON.stringify(settings) && before !== null ? before : JSON.stringify(settings, null, 2) + '\n';
+}
+
+/** codexRules 生成原生逐次确认策略，保留只读命令自动执行。
+ * Returns:
+ *   Codex Starlark 规则原文。
+ */
+export function codexRules() {
+  return '# Managed by the CCNeed installer; keep manual approvals enabled.\n' + [['kb', 'start'], ['tasks', 'reply']].map(words =>
+    'prefix_rule(pattern = ' + JSON.stringify([commands, ...words]) + ', decision = "prompt", justification = "Confirm this CCNeed operation after reviewing the final collection plan")\n').join('');
+}
+
+/** preparePluginIntegration 在 npm 替换包之前检查宿主配置冲突，不写文件。
+ * Args:
+ *   home: 当前用户的明确目录，测试可注入隔离目录。
+ *   agents: 用户明确选择的宿主名称。
+ *   root: 固定全局 npm 包目录。
+ * Returns:
+ *   自有迁移和权限配置目标；不会注册全局 hooks。
+ * Errors:
+ *   无效路径、已有配置冲突或非法 JSON 返回异常。
+ */
+export function preparePluginIntegration(home, agents, root) {
+  if (!isAbsolute(home) || !isAbsolute(root)) throw new Error('Plugin directories must be absolute');
+  return agents.flatMap(host => {
+    if (!Object.hasOwn(hostDirs, host)) throw new Error('Unsupported plugin host');
+    const directory = join(home, hostDirs[host]);
+    const target = join(directory, host === 'codex' ? 'hooks.json' : 'settings.json');
+    checkParents(home, dirname(target));
+    const before = fileText(target);
+    const files = before === null && host !== 'workbuddy' ? [] : [{ home, host, target, before, after: mergeSettings(before, root, host), root }];
+    if (host === 'codex') {
+      const target = join(directory, 'rules', 'ccneed.rules');
+      checkParents(home, dirname(target));
+      const before = fileText(target);
+      const after = codexRules();
+      if (before !== null && before !== after) throw new Error('Existing custom CCNeed rules will not be overwritten');
+      files.unshift({ home, host, target, before, after, root });
+    }
+    return files;
+  });
+}
+
+/** replaceText 原子替换已核对的配置，避免保留半份 JSON。
+ * Args:
+ *   path: 明确的宿主配置目标。
+ *   text: 完整新配置。
+ * Errors:
+ *   写入或发布失败时返回异常。
+ */
+function replaceText(path, text) {
+  const temporary = path + '.' + randomUUID() + '.tmp';
+  try {
+    writeFileSync(temporary, text, { flag: 'wx', mode: 0o600 });
+    renameSync(temporary, path);
+  } finally {
+    try { unlinkSync(temporary); } catch (error) { if (error.code !== 'ENOENT') throw error; }
+  }
+}
+
+/** attachPluginIntegration 发布明确选择的宿主配置，不修改安全模式或其他设置。
+ * Args:
+ *   plans: 无副作用预检得到的配置计划。
+ * Returns:
+ *   实际配置文件路径；仍需宿主信任和重新加载。
+ * Errors:
+ *   缺失 handler、并发配置修改或写入失败时撤回本次配置写入。
+ */
+export function attachPluginIntegration(plans) {
+  for (const plan of plans) {
+    if (!fileText(join(plan.root, 'skills', 'ccneed', 'scripts', 'acquisition.mjs'))?.trim()) throw new Error('Incomplete bundled CCNeed plugin');
+    checkParents(plan.home, dirname(plan.target));
+    if (fileText(plan.target) !== plan.before) throw new Error('Host settings changed during installation');
+  }
+  const written = [];
+  try {
+    for (const plan of plans) {
+      checkParents(plan.home, dirname(plan.target));
+      mkdirSync(dirname(plan.target), { recursive: true });
+      checkParents(plan.home, dirname(plan.target));
+      if (fileText(plan.target) !== plan.before) throw new Error('Host settings changed during installation');
+      if (plan.before === plan.after) continue;
+      replaceText(plan.target, plan.after);
+      written.push(plan);
+    }
+    return plans.map(plan => plan.target);
+  } catch (error) {
+    for (const plan of written.reverse()) {
+      if (fileText(plan.target) !== plan.after) continue;
+      if (plan.before === null) unlinkSync(plan.target); else replaceText(plan.target, plan.before);
+    }
+    throw error;
+  }
+}
+
+/** nativeLauncher 解析 Windows 的官方 npm launcher，不把参数拼成 shell 命令。
+ * Args:
+ *   host: claude 或 codex。
+ * Returns:
+ *   当前 Node 可执行的官方宿主脚本。
+ * Errors:
+ *   缺少官方 npm 布局时失败，不执行未知 cmd 文件。
+ */
+async function nativeLauncher(host) {
+  // Resolve PATH with Unicode-aware filesystem calls. Windows where.exe can
+  // fail on non-ASCII profile paths despite the shim being directly readable.
+  const paths = (process.env.PATH ?? process.env.Path ?? '').split(delimiter).filter(Boolean);
+  const shim = paths.map(value => join(value.replace(/^"(.*)"$/, '$1'), host + '.cmd')).find(path => {
+    try { return isAbsolute(path) && lstatSync(path).isFile(); } catch (error) { if (['ENOENT', 'ENOTDIR'].includes(error.code)) return false; throw error; }
+  });
+  if (!shim) throw new Error('Native plugin manager launcher unavailable');
+  const identity = host === 'codex' ? '@openai/codex' : '@anthropic-ai/claude-code';
+  const root = join(dirname(shim), 'node_modules', identity);
+  const manifest = JSON.parse(fileText(join(root, 'package.json')) ?? '{}');
+  const script = join(root, host === 'codex' ? 'bin/codex.js' : 'cli.js');
+  const stat = lstatSync(script);
+  if (manifest.name !== identity || !stat.isFile() || stat.isSymbolicLink()) throw new Error('Native plugin manager launcher unavailable');
+  return script;
+}
+
+/** runNative 调用宿主原生插件生命周期，不启动模型或自行写插件缓存。
+ * Args:
+ *   host: claude 或 codex；WorkBuddy 没有已验证的注册 CLI。
+ *   args: 固定的原生插件命令参数数组。
+ * Returns:
+ *   原生命令的 stdout 文本。
+ * Errors:
+ *   宿主缺失、超时或失败时返回不含 stderr 和凭证的异常。
+ */
+export async function runNative(host, args) {
+  if (!['claude', 'codex'].includes(host)) throw new Error('Native plugin manager unavailable');
+  const options = { timeout: 180_000, maxBuffer: 1024 * 1024, windowsHide: true, shell: false };
+  try {
+    if (process.platform !== 'win32') return (await exec(host, args, options)).stdout;
+    try { return (await exec(host + '.exe', args, options)).stdout; }
+    catch (error) { if (error.code !== 'ENOENT') throw error; }
+    const launcher = await nativeLauncher(host);
+    return (await exec(process.execPath, [launcher, ...args], options)).stdout;
+  } catch { throw new Error('Native plugin manager failed; check the selected host installation and retry'); }
+}
+
+/** samePath 规范本地来源路径，包括 Windows 原生工具返回的扩展路径前缀。
+ * Args:
+ *   actual: 原生工具报告的本地路径。
+ *   expected: 固定的全局包路径。
+ * Returns:
+ *   两个绝对路径是否指向同一词法位置。
+ */
+function samePath(actual, expected) {
+  if (typeof actual !== 'string') return false;
+  const clean = value => value.replace(/^\\\\\?\\UNC\\/i, '\\\\').replace(/^\\\\\?\\/, '');
+  if (!isAbsolute(clean(actual))) return false;
+  const left = resolve(clean(actual)), right = resolve(clean(expected));
+  return process.platform === 'win32' ? left.toLowerCase() === right.toLowerCase() : left === right;
+}
+
+/** validateNativePayload 确保原生管理器读取同版本包内的受限载荷路径。
+ * Args:
+ *   root: 稳定的全局 npm 包目录。
+ *   host: 所选宿主。
+ *   version: 本次已核验的 CLI 版本。
+ * Errors:
+ *   manifest、catalog 或 hooks 缺失、错版或越界时失败。
+ */
+function validateNativePayload(root, host, version) {
+  const directories = { claude: '.claude-plugin', codex: '.codex-plugin', workbuddy: '.codebuddy-plugin' };
+  const manifest = JSON.parse(fileText(join(root, directories[host], 'plugin.json')) ?? '{}');
+  if (manifest.name !== 'ccneed' || manifest.version !== version || manifest.skills !== './skills' || manifest.hooks !== './hooks/' + host + '.json') throw new Error('Native plugin payload does not match the CLI release');
+  const hooks = JSON.parse(fileText(join(root, 'hooks', host + '.json')) ?? '{}');
+  if (!hooks.hooks || typeof hooks.hooks !== 'object' || Array.isArray(hooks.hooks)) throw new Error('Native plugin hooks are missing');
+  const catalogDirectory = host === 'codex' ? '.agents/plugins' : directories[host];
+  const catalog = JSON.parse(fileText(join(root, catalogDirectory, 'marketplace.json')) ?? '{}');
+  const entry = Array.isArray(catalog.plugins) ? catalog.plugins.find(value => value.name === 'ccneed') : null;
+  const source = host === 'codex' ? { source: 'local', path: './' } : './';
+  if (catalog.name !== 'ccneed' || !entry || !sameConfig(entry.source, source) || (entry.version !== undefined && entry.version !== version)) throw new Error('Native marketplace source is invalid');
+}
+
+/** nativeJSON 读取有界原生 JSON 输出，不把人类提示误认为安装成功。
+ * Args:
+ *   native: 可注入的原生进程边界。
+ *   host: 当前宿主。
+ *   args: 原生命令参数。
+ * Returns:
+ *   解析后的原生 JSON 数据。
+ * Errors:
+ *   输出不是有界 JSON 时失败。
+ */
+async function nativeJSON(native, host, args) {
+  const stdout = await native(host, args);
+  if (typeof stdout !== 'string' || stdout.length > 1024 * 1024) throw new Error('Invalid native plugin response');
+  return JSON.parse(stdout.replace(/^\uFEFF/, ''));
+}
+
+/** ensureMarketplace 仅注册稳定包目录，拒绝接管同名的其他来源。
+ * Args:
+ *   native: 原生进程边界。
+ *   host: claude 或 codex。
+ *   root: 稳定全局包目录。
+ * Returns:
+ *   已核验的原生 marketplace 记录。
+ * Errors:
+ *   同名异源、输出无效或原生注册失败时停止。
+ */
+async function ensureMarketplace(native, host, root) {
+  const read = async () => {
+    const value = await nativeJSON(native, host, ['plugin', 'marketplace', 'list', '--json']);
+    const rows = host === 'claude' ? value : value.marketplaces;
+    if (!Array.isArray(rows)) throw new Error('Invalid native marketplace response');
+    const matches = rows.filter(value => value.name === 'ccneed');
+    if (matches.length > 1) throw new Error('Ambiguous native marketplace');
+    return matches[0];
+  };
+  let marketplace = await read();
+  if (!marketplace) {
+    await native(host, ['plugin', 'marketplace', 'add', root, ...(host === 'claude' ? ['--scope', 'user'] : ['--json'])]);
+    marketplace = await read();
+  }
+  const path = host === 'claude' ? marketplace?.path ?? marketplace?.installLocation : marketplace?.root;
+  if (!samePath(path, root) || (host === 'claude' && !['directory', 'local'].includes(marketplace?.source))) throw new Error('Existing CCNeed marketplace has another source');
+  return marketplace;
+}
+
+/** installedPlugin 读取原生用户级安装状态，不用缓存目录存在代替实际状态。
+ * Args:
+ *   native: 原生进程边界。
+ *   host: claude 或 codex。
+ * Returns:
+ *   当前插件记录，未安装时返回 null。
+ * Errors:
+ *   无效或重复的原生安装记录返回异常。
+ */
+async function installedPlugin(native, host) {
+  const value = await nativeJSON(native, host, ['plugin', 'list', '--json']);
+  const rows = host === 'claude' ? value : value.installed;
+  if (!Array.isArray(rows)) throw new Error('Invalid native plugin response');
+  const matches = rows.filter(row => host === 'claude' ? row.id === 'ccneed@ccneed' && row.scope === 'user' : row.pluginId === 'ccneed@ccneed');
+  if (matches.length > 1) throw new Error('Ambiguous native plugin installation');
+  return matches[0] ?? null;
+}
+
+/** installNativePlugin 委托宿主注册与升级，逐宿主报告实际版本和待完成操作。
+ * Args:
+ *   native: 原生进程边界，接收 host 和参数数组。
+ *   host: 当前选择的宿主。
+ *   root: 已验证的全局包目录。
+ *   version: 期望的同包版本。
+ * Returns:
+ *   原生安装结果；错误和 WorkBuddy 手动步骤不会伪装为 installed。
+ */
+export async function installNativePlugin(native, host, root, version) {
+  const base = { host, plugin_id: 'ccneed@ccneed', requested_version: version, version: null, marketplace_root: root };
+  try {
+    validateNativePayload(root, host, version);
+    if (host === 'workbuddy') return { ...base, status: 'action_required', next_steps: ['Open WorkBuddy desktop’s native plugin manager and register the local CCNeed marketplace at ' + root, 'Install and enable ccneed@ccneed version ' + version + '; verify that version in the desktop plugin manager', 'Trust the bundled hooks and restart WorkBuddy with default permissions; no supported desktop CLI registration API was used'] };
+    await ensureMarketplace(native, host, root);
+    let installed = await installedPlugin(native, host);
+    if (installed?.enabled === false) return { ...base, status: 'action_required', version: installed.version ?? null, next_steps: ['The native plugin is disabled; review and enable it in the host plugin manager before retrying'] };
+    if (!installed || installed.version !== version) {
+      if (host === 'claude' && installed) await native(host, ['plugin', 'marketplace', 'update', 'ccneed']);
+      await native(host, ['plugin', host === 'claude' ? (installed ? 'update' : 'install') : 'add', 'ccneed@ccneed', ...(host === 'claude' ? ['--scope', 'user'] : ['--json'])]);
+      installed = await installedPlugin(native, host);
+    }
+    const sourceMatches = host === 'claude' || (installed?.installed === true && installed?.source?.source === 'local' && samePath(installed.source.path, root));
+    if (!installed || installed.version !== version || installed.enabled !== true || !sourceMatches) return { ...base, status: 'action_required', version: installed?.version ?? null, next_steps: ['The native manager did not verify the requested enabled plugin version; complete installation in the host plugin manager and retry'] };
+    return { ...base, status: 'installed', version: installed.version, restart_required: true, hook_trust_required: true };
+  } catch { return { ...base, status: 'failed', error: 'native_plugin_registration_failed', next_steps: ['Check the selected host supports native plugin marketplaces and that ccneed is sourced from this exact package directory, then retry; existing custom configuration was preserved'] }; }
+}

package/scripts/npm/setup.mjs

@@ -1,10 +1,11 @@
 import { readFileSync, lstatSync, existsSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { dirname, isAbsolute, join, parse } from 'node:path';
+import { dirname, isAbsolute, join, parse, resolve } from 'node:path';
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
 import { installBinary, packageRoot } from './install.mjs';
-import { prepareSkillLinks, attachSkillLinks, parseAgents, validateBundledSkill } from './skills.mjs';
+import { prepareLegacySkillCleanup, removeLegacySkillLinks, parseAgents, validateBundledSkill } from './skills.mjs';
+import { preparePluginIntegration, attachPluginIntegration, installNativePlugin, runNative } from './plugin.mjs';
 
 const exec = promisify(execFile);
 const officialPackage = '@validflow/ccneed-cli';
@@ -97,22 +98,50 @@ function newerVersion(current, desired) {
   return BigInt(left[4]) > BigInt(right[4]);
 }
 
-/** installIntegration 全局安装精确版本 CLI，并将所选宿主指向同包技能。
+/** customNativeProfile 识别无法与默认权限配置一起自动安装的宿主 profile。
  * Args:
- *   options: 包来源、明确宿主、用户目录及可替换的 npm/程序验证边界。
+ *   host: 本次选择的宿主。
+ *   home: 安装器使用的用户目录。
+ *   env: 原生进程实际继承的环境，测试可随 native 边界注入。
  * Returns:
- *   版本、宿主路径和需要重新加载的真实安装结果。
+ *   非默认 profile 的环境变量名，默认 profile 返回 null。
+ */
+function customNativeProfile(host, home, env) {
+  const variable = { codex: 'CODEX_HOME', claude: 'CLAUDE_CONFIG_DIR' }[host];
+  const value = variable && env?.[variable];
+  if (!value) return null;
+  if (typeof value !== 'string') return variable;
+  const clean = path => path.replace(/^\\\\\?\\UNC\\/i, '\\\\').replace(/^\\\\\?\\/, '');
+  if (!isAbsolute(clean(value))) return variable;
+  const actual = resolve(clean(value));
+  const expected = resolve(join(home, host === 'codex' ? '.codex' : '.claude'));
+  const same = process.platform === 'win32' ? actual.toLowerCase() === expected.toLowerCase() : actual === expected;
+  return same ? null : variable;
+}
+
+/** installIntegration 全局安装精确版本 CLI，再逐宿主验证原生插件生命周期。
+ * Args:
+ *   options: 包来源、宿主、用户目录和可替换的 npm/程序/native(host,args)/env 边界。
+ * Returns:
+ *   CLI 版本、各宿主实际版本及信任、重启或自定义 profile 的手动设置要求。
  * Errors:
- *   自定义技能冲突在 npm 写入前失败；npm/版本/验证失败不会报告成功。
+ *   npm/CLI 完整性错误直接失败；原生宿主失败返回真实的逐宿主部分结果。
  */
-export async function installIntegration({ root = packageRoot, agents, home = homedir(), npm = runNpm, verify = verifyInstalledBinary }) {
+export async function installIntegration({ root = packageRoot, agents, home = homedir(), npm = runNpm, verify = verifyInstalledBinary, native = runNative, env = process.env }) {
   const desired = releaseManifest(root);
   const selected = parseAgents(agents);
+  // The real runner inherits process.env; injected runners may supply their
+  // own environment snapshot without changing the installer's process.
+  const nativeEnv = native === runNative ? process.env : env;
+  const customProfiles = new Map(selected.map(host => [host, customNativeProfile(host, home, nativeEnv)]));
+  const automatic = selected.filter(host => !customProfiles.get(host));
+  if (native === runNative && resolve(home) !== resolve(homedir()) && automatic.some(host => host !== 'workbuddy')) throw new Error('A custom home requires an injected native process boundary');
   validateBundledSkill(root);
   const globalRoot = (await npm(['root', '--global'])).trim();
   if (!isAbsolute(globalRoot) || globalRoot === parse(globalRoot).root || /[\r\n]/.test(globalRoot)) throw new Error('Invalid global npm directory');
   const globalPackage = join(globalRoot, '@validflow', 'ccneed-cli');
-  const plans = prepareSkillLinks(home, selected, globalPackage);
+  prepareLegacySkillCleanup(home, automatic, globalPackage);
+  preparePluginIntegration(home, automatic, globalPackage);
   const current = existingManifest(globalPackage);
   if (current) validateBundledSkill(globalPackage);
   if (current && newerVersion(current.version, desired.version)) throw new Error('Refusing to downgrade; use the current official installer');
@@ -123,8 +152,29 @@ export async function installIntegration({ root = packageRoot, agents, home = ho
   if (releaseManifest(globalPackage).version !== desired.version) throw new Error('Global package version mismatch');
   validateBundledSkill(globalPackage);
   await verify(globalPackage, desired.version);
-  const paths = attachSkillLinks(plans);
-  return { status: 'installed', version: desired.version, agents: selected, skill_targets: paths, restart_required: true, auth: 'not_started' };
+  const plugins = [];
+  for (const host of selected) {
+    const variable = customProfiles.get(host);
+    if (variable) {
+      plugins.push({ host, plugin_id: 'ccneed@ccneed', requested_version: desired.version, version: null, status: 'action_required', error: 'custom_profile', next_steps: [variable + ' selects a nondefault native profile; automatic registration, default-profile rules and legacy cleanup were not performed for this host', 'Use that profile’s native plugin manager to register ' + globalPackage + ' and install/enable ccneed@ccneed version ' + desired.version, 'Set up the required native permission rules in the same active profile, review and trust the hooks, and restart the host before collection'] });
+      continue;
+    }
+    const result = await installNativePlugin(native, host, globalPackage, desired.version);
+    if (result.status === 'installed' || (host === 'workbuddy' && result.status === 'action_required')) {
+      try {
+        // Native managers can update settings during registration. Re-read
+        // rather than overwriting their enabledPlugins or marketplace state.
+        result.configuration_targets = attachPluginIntegration(preparePluginIntegration(home, [host], globalPackage));
+        result.removed_legacy_skill_links = removeLegacySkillLinks(prepareLegacySkillCleanup(home, [host], globalPackage));
+      } catch {
+        result.status = 'action_required';
+        result.error = 'legacy_integration_cleanup_required';
+        result.next_steps = ['Native registration or manual import is not sufficient yet: review the retained custom or concurrently changed legacy configuration, then retry the installer'];
+      }
+    }
+    plugins.push(result);
+  }
+  return { status: plugins.every(plugin => plugin.status === 'installed') ? 'installed' : 'action_required', version: desired.version, agents: selected, plugins, restart_required: true, hook_trust_required: true, manual_approval_required: true, auth: 'not_started' };
 }
 
 /** installerMain 提供安装与更新共用的明确入口，帮助和参数错误不触发网络。
@@ -137,7 +187,7 @@ export async function installIntegration({ root = packageRoot, agents, home = ho
  */
 export async function installerMain(args) {
   if (args.length === 1 && ['--help', '-h'].includes(args[0])) {
-    return 'Install or update CLI + same-version Skill globally.\nUsage: npx @validflow/ccneed-cli@latest install --agent codex,workbuddy\nRC: npx @validflow/ccneed-cli@next install --agent codex,workbuddy\nHosts: codex, workbuddy, claude. Restart selected hosts after updating.\n';
+    return 'Install or update the global CLI and register same-version native plugins.\nUsage: npx @validflow/ccneed-cli@latest install --agent codex,workbuddy\nRC: npx @validflow/ccneed-cli@next install --agent codex,workbuddy\nHosts: codex, claude; WorkBuddy requires native desktop import. Check each host result, restart, trust hooks, and keep manual approvals enabled.\n';
   }
   if (args.length !== 2 || args[0] !== '--agent') throw new Error('Use install --agent codex,workbuddy,claude; see install --help');
   return JSON.stringify(await installIntegration({ agents: args[1] })) + '\n';

package/scripts/npm/skills.mjs

@@ -2,7 +2,7 @@ import { lstatSync, mkdirSync, readFileSync, readlinkSync, readdirSync, symlinkS
 import { isAbsolute, join, resolve } from 'node:path';
 import { createHash } from 'node:crypto';
 
-const hosts = { codex: '.agents', workbuddy: '.codebuddy', claude: '.claude' };
+const hosts = { codex: '.agents', workbuddy: '.workbuddy', claude: '.claude' };
 
 /** fingerprintSkill 为完整技能的文件名和字节生成稳定摘要，不跟随内部链接。
  * Args:
@@ -193,3 +193,49 @@ export function attachSkillLinks(plans, createLink = symlinkSync) {
     throw error;
   }
 }
+
+/** prepareLegacySkillCleanup 只识别旧安装器指向同一全局包的技能入口。
+ * Args:
+ *   home: 明确的用户目录，测试使用隔离目录。
+ *   agents: 本次明确选择的宿主。
+ *   root: 稳定的全局 npm 包目录。
+ * Returns:
+ *   可以删除的自有链接；不注册第二份独立技能。
+ * Errors:
+ *   自定义同名技能、非法宿主或父目录链接使预检失败，不更改文件。
+ */
+export function prepareLegacySkillCleanup(home, agents, root) {
+  if (!isAbsolute(home) || !isAbsolute(root)) throw new Error('Installation directories must be absolute');
+  const source = join(resolve(root), 'skills', 'ccneed');
+  return agents.flatMap(agent => {
+    if (!Object.hasOwn(hosts, agent)) throw new Error('Unsupported agent');
+    const directories = agent === 'workbuddy' ? [hosts[agent], '.codebuddy'] : [hosts[agent]];
+    return directories.flatMap(directory => {
+      const parents = [resolve(home), join(home, directory), join(home, directory, 'skills')];
+      checkParents(parents);
+      const target = join(parents[2], 'ccneed');
+      if (statOrMissing(target) && !sameLink(target, source)) throw new Error('Existing custom Skill must be resolved before native installation: ' + target);
+      return sameLink(target, source) ? [{ agent, parents, target, source }] : [];
+    });
+  });
+}
+
+/** removeLegacySkillLinks 移除仍然属于安装器的旧链接，不递归删除技能内容。
+ * Args:
+ *   plans: 已核对来源的旧技能链接。
+ * Returns:
+ *   实际移除的链接路径。
+ * Errors:
+ *   父目录或链接在预检后改变时停止，保留未知文件。
+ */
+export function removeLegacySkillLinks(plans) {
+  const removed = [];
+  for (const plan of plans) {
+    checkParents(plan.parents);
+    if (!statOrMissing(plan.target)) continue;
+    if (!sameLink(plan.target, plan.source)) throw new Error('Legacy Skill changed during installation');
+    unlinkSync(plan.target);
+    removed.push(plan.target);
+  }
+  return removed;
+}

package/skills/ccneed/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: ccneed
-description: 使用 ccneed CLI 连接 CCNeed，完成官网授权登录，管理会话、知识库与文件，提交和观察云端任务，处理用户确认并读取或下载报告；也可查询账号积分与订阅。适用于 Codex、Claude Code、WorkBuddy 等可执行命令的宿主 Agent；不用于本地 Agent 开发或平台 Skill/MCP 配置管理。
+description: 使用 ccneed CLI 连接 CCNeed，准备和确认采集方案，创建或补充知识库、导出 CSV/JSON 数据供本地分析，或把资料交给云端 Agent 分析并下载报告；也可管理登录、会话、文件与账号积分。适用于 Codex、Claude Code、WorkBuddy 等可执行命令的宿主 Agent。
 ---
 
 # CCNeed
 
-云端负责执行长程任务；宿主 Agent 通过已安装的 `ccneed` 提交、观察、收集用户确认并交付结果，不在本地复制 CCNeed runtime。
+需要数据时，由宿主准备方案，CCNeed 校验、计费和采集，导出后交给用户自己的 Agent 分析。需要平台分析时，继续把知识库交给 CCNeed 云端 Agent。两条路径都在正式采集前展示最终方案并请求用户确认。
 
 CLI 与本 Skill 已正式发行；**部分云端命令仍取决于 CCNeed 正式服务接口是否上线**。不能把本地契约测试当成线上能力已验收。平台自定义 Skill/MCP 的 CLI 管理暂不开放，云端仍按账号已有配置运行。
 
@@ -15,16 +15,19 @@ CLI 与本 Skill 已正式发行；**部分云端命令仍取决于 CCNeed 正
 | --- | --- |
 | 登录、验证或退出登录、处理凭证错误、切换开发环境 | [认证与环境](references/auth.md) |
 | 查看积分、订阅、近期使用记录 | [账号查询](references/account.md) |
+| 创建/补充知识库、调整采集方案与配额、处理采集 HITL | [采集方案与确认](references/acquisition.md) |
 | 开启或选择会话，提交、查询或观察回合，回答 HITL | [会话与任务](references/tasks.md) |
 | 选择知识库、上传/绑定文件，查看 findings/reports、下载报告 | [资源与产出](references/resources.md) |
 
-通常顺序：官网授权 → 上传/选择资料 → 用首句开启会话并绑定资料 → 有界观察 → 必要时交给用户确认 → 查看本轮结果/下载报告。已有会话则用真实 `thread_id` 继续；只执行用户此次要求的步骤，不自动创建付费任务。
+先确认用户要原始数据还是平台分析。已有数据可直接导出；需要新数据时先准备方案。平台分析才使用 `run` 开启或继续会话。已有会话用真实 `thread_id`，只执行用户此次委托，不自动创建付费任务。
 
 ## 调用约定
 
 - 不熟悉安装版本时先运行 `ccneed --help`、`ccneed version --no-update-check`，再看目标命令的 `--help`。缺少命令说明本版本不支持，不猜 flag 或绕过为未经确认的 HTTP 请求。
 - 产品命令默认 JSON；结果和错误均在 stdout，诊断及更新提醒在 stderr。先检查退出码，再解释业务状态：`pending`、`accepted`、`queued` 都不代表工作已完成。无需 Lark 的 `ok` 信封或 `--json` 参数。
 - 官网授权链接必须先展示并交还用户；用户确认后才运行完成登录步骤。任务 `waiting_user` 时原样说明问题和候选项，停下来等用户选择；不要为了验证流程而替用户选择、批准或补全答案。
+- 本 Skill 随原生插件加载，统一安装器逐宿主报告结果。安装 CLI 不等于插件已启用；`action_required`、`failed` 或待信任 hooks 时先完成宿主操作，不另外复制一份全局 Skill。
+- 采集方案的展示和执行授权由已加载的 plugin hooks 与宿主原生权限共同承担。不能用一句“用户已同意”、`--yes` 或 AskUserQuestion 代替工具执行前的原生权限确认；缺少 hooks、权限策略或可交互确认能力时停止正式采集，按[采集说明](references/acquisition.md)处理。
 - CLI 默认连接正式线上服务 `https://ccneed.ai`；普通用户不需要 `--api-url`。只有获授权的开发者才能用它连接 staging，并使用测试账号；它不是接口路径或环境访问凭证。同一流程保持同一 origin，认证错误不能通过切回生产绕过。
 - `--no-update-check` 关闭本次更新检查。更新提醒不取代当前任务；安装与升级以仓库 README 为准，不把源码构建或手工复制的 Skill 当成可自动联动更新的 npm 安装。
 - 凭证由 CLI 交给系统凭证库；不读取、输出或转交 token、网站 Cookie、设备秘密。只展示公开回答与 findings/reports，不要求原始工具日志、隐藏推理或任意沙箱路径。