fuli-context 0.2.0 → 0.4.0

package/src/agent-tools/graph-definitions.js

@@ -14,6 +14,12 @@ const label = boundedString(512);
 const shortText = boundedString(2048);
 const longText = boundedString(8192);
 const dateTime = { ...boundedString(64), format: 'date-time' };
+const sourceUri = {
+  type: ['string', 'null'],
+  minLength: 1,
+  maxLength: 2048,
+  pattern: '^[Hh][Tt][Tt][Pp][Ss]?://\\S+$'
+};
 const attributes = { type: 'object', additionalProperties: true };
 const epistemicQuadrant = enumSchema([
   'known_known', 'known_unknown', 'unknown_known', 'unknown_unknown'
@@ -29,6 +35,10 @@ const confirmationActor = objectSchema({
   kind: enumSchema(['user', 'agent', 'authoritative_source', 'import']),
   label: nullableStringSchema()
 }, ['kind']);
+const decisionActor = objectSchema({
+  kind: enumSchema(['user', 'agent', 'authoritative_source']),
+  label: nullableStringSchema()
+}, ['kind']);
 const confirmationBasis = objectSchema({
   existenceReason: boundedString(4096),
   quadrantReason: boundedString(4096),
@@ -155,12 +165,70 @@ const personalProjectActionIntent = {
 const personalProjectActionRequired = [
   'personalSpaceId', 'itemKind', 'itemId', 'mode', 'reason'
 ];
+const commonKnowledgePromotionIntent = {
+  personalSpaceId: id,
+  parentProjectId: id,
+  itemKind: knowledgeItemKind,
+  canonicalItemId: id,
+  duplicateItemIds: arraySchema(id, { minItems: 1, maxItems: 31 }),
+  reason: boundedString(2000),
+  humanConfirmationReason: boundedString(2000)
+};
+const commonKnowledgePromotionRequired = [
+  'personalSpaceId', 'parentProjectId', 'itemKind', 'canonicalItemId',
+  'duplicateItemIds', 'reason', 'humanConfirmationReason'
+];
+const captureEpisodeFields = {
+  idempotencyKey: id,
+  name: label,
+  sourceKind: boundedString(128),
+  sourceDescription: boundedString(1024),
+  sourceUri,
+  sourceApplication,
+  sourceTurnId: { type: ['string', 'null'], minLength: 1, maxLength: 256 },
+  sourceExcerpt: { type: ['string', 'null'], minLength: 1, maxLength: 2048 },
+  referenceTime: dateTime,
+  summary: longText,
+  sensitivity: enumSchema(['normal', 'private', 'restricted']),
+  entities: arraySchema(entity, { minItems: 1, maxItems: 128 }),
+  relationships: arraySchema(relationship, { maxItems: 256 })
+};
+const captureEpisodeRequired = [
+  'idempotencyKey', 'name', 'sourceKind', 'sourceDescription',
+  'referenceTime', 'entities', 'relationships'
+];
 
 export const GRAPH_TOOL_DEFINITIONS = [
+  {
+    name: 'begin_task_context',
+    title: 'LIFECYCLE · Begin a Fuli-aware task',
+    description: 'Lifecycle entry used by supported Agent hooks before the model processes a user prompt. It resolves the exact local project from projectPath, loads effective collaboration preferences, and returns an opaque taskContextToken. It never stores projectPath. Claude Code setup installs this as a deterministic UserPromptSubmit hook; manual Agent calls are a fallback.',
+    inputSchema: objectSchema({
+      sessionId: id,
+      projectPath: boundedString(4096)
+    }, ['sessionId', 'projectPath'])
+  },
+  {
+    name: 'checkpoint_task_knowledge',
+    title: 'LIFECYCLE · Finish knowledge review',
+    description: 'Complete exactly one end-of-task knowledge review. Use capture_candidates only for a small durable batch supported by the task; captured Agent proposals remain pending unless the payload contains valid human or authoritative-source confirmation. Use retain_nothing when the turn produced no reusable knowledge. Never store raw transcripts, guesses, temporary logs, credentials, or disposable output.',
+    inputSchema: objectSchema({
+      taskContextToken: id,
+      disposition: enumSchema(['capture_candidates', 'retain_nothing']),
+      reason: boundedString(2000),
+      capture: objectSchema(captureEpisodeFields, captureEpisodeRequired)
+    }, ['taskContextToken', 'disposition', 'reason'])
+  },
+  {
+    name: 'verify_task_checkpoint',
+    title: 'LIFECYCLE · Verify end-of-task review',
+    description: 'Hook-facing read that returns a Claude Code Stop decision. It blocks stopping only when begin_task_context succeeded for the session and checkpoint_task_knowledge has not yet recorded capture_candidates or retain_nothing.',
+    inputSchema: objectSchema({ sessionId: id }, ['sessionId'])
+  },
   {
     name: 'get_collaboration_preferences',
     title: 'READ FIRST · Load task collaboration preferences',
-    description: 'Call this exact tool name at the start of every user task before any other tool or answer; never substitute a project action tool. Pass projectPath as the current working directory; Fuli uses it transiently, never stores or returns it, and layers preferences only for one exact registered local project match. Returns effective_preferences plus deferred_conflicts intentionally queued for AI. Apply effective_preferences before answering or constructing tool arguments. Human-confirmed preferences outrank explicitly marked agent-confirmed preferences. If the current task would use a deferred conflict, call resolve_deferred_preference_conflict before applying either side; ignore unrelated deferred conflicts. For write tools, enforce preferences in the actual payload; mentioning them only in the final answer is not compliance. Personal-global preferences always apply; other conflicted, pending, invalid, ambiguous-project, and unrelated-project items never auto-apply. Automatic injection does not count as usage evidence. personalProjectId remains an explicit compatibility override.',
+    description: 'Fallback for Agents or tasks without begin_task_context hook context. When no hook context was supplied, call this exact tool name at the start of every user task before any other tool or answer; never substitute a project action tool. Do not call it redundantly when the entry hook already supplied preferences. Pass projectPath as the current working directory; Fuli uses it transiently, never stores or returns it, and layers preferences only for one exact registered local project match. Returns effective_preferences plus deferred_conflicts intentionally queued for AI. Apply effective_preferences before answering or constructing tool arguments. Human-confirmed preferences outrank explicitly marked agent-confirmed preferences. If the current task would use a deferred conflict, call resolve_deferred_preference_conflict before applying either side; ignore unrelated deferred conflicts. For write tools, enforce preferences in the actual payload; mentioning them only in the final answer is not compliance. Personal-global preferences always apply; other conflicted, pending, invalid, ambiguous-project, and unrelated-project items never auto-apply. Automatic injection does not count as usage evidence. personalProjectId remains an explicit compatibility override.',
     inputSchema: objectSchema({
       projectPath: boundedString(4096),
       personalProjectId: nullableStringSchema(),
@@ -185,34 +253,64 @@ export const GRAPH_TOOL_DEFINITIONS = [
   },
   {
     name: 'capture_session_knowledge',
-    description: 'Silently batch durable session knowledge when the user-enabled capture policy allows it. Every item records its discovery quadrant, structured confirmation basis, and pending or confirmed state. A disabled policy returns capture_disabled without writing. Personal profile knowledge stays personal; only project knowledge with an auditable confirmation can enter public review.',
+    description: 'Silently batch durable session knowledge when the user-enabled capture policy allows it. When knowledge was read from an online source, sourceUri preserves the exact original HTTP(S) link so a capable Agent can re-read it later and refresh Fuli knowledge; it does not authorize source-document writeback. Every item records its discovery quadrant, structured confirmation basis, and pending or confirmed state. A disabled policy returns capture_disabled without writing. Personal profile knowledge stays personal; only project knowledge with an auditable confirmation can enter public review.',
     inputSchema: objectSchema({
       targetKind: enumSchema(['personal', 'project']),
       spaceId: id,
       personalProjectId: nullableStringSchema(),
       providerUrl: nullableStringSchema(),
-      idempotencyKey: id,
       sessionId: id,
-      name: label,
+      ...captureEpisodeFields
+    }, [
+      'targetKind', 'spaceId', 'sessionId', ...captureEpisodeRequired
+    ])
+  },
+  {
+    name: 'record_decision_trace',
+    title: 'WRITE · Store a decision with its rationale',
+    description: 'Store one bounded, searchable project decision as a linked Decision, selected and rejected DecisionOption nodes, a DecisionRationale, and optional ValidationResult nodes. reason is mandatory: do not store a bare conclusion. User or authoritative-source decisions are confirmed with their audit basis; Agent-only proposals remain pending. Do not copy raw transcripts, credentials, private contact details, or disposable deliberation.',
+    inputSchema: objectSchema({
+      personalSpaceId: id,
+      personalProjectId: nullableStringSchema(),
+      sessionId: id,
+      idempotencyKey: id,
+      decisionKey: id,
+      title: label,
+      question: shortText,
+      selectedOption: objectSchema({
+        key: id,
+        label,
+        summary: nullableStringSchema()
+      }, ['key', 'label']),
+      rejectedOptions: arraySchema(objectSchema({
+        key: id,
+        label,
+        summary: nullableStringSchema()
+      }, ['key', 'label']), { maxItems: 16 }),
+      reason: boundedString(4096),
+      validationResults: arraySchema(objectSchema({
+        key: id,
+        outcome: enumSchema(['pass', 'fail', 'inconclusive']),
+        summary: shortText
+      }, ['key', 'outcome', 'summary']), { maxItems: 16 }),
+      decidedBy: decisionActor,
+      referenceTime: dateTime,
       sourceKind: boundedString(128),
       sourceDescription: boundedString(1024),
+      sourceUri,
       sourceApplication,
       sourceTurnId: { type: ['string', 'null'], minLength: 1, maxLength: 256 },
-      sourceExcerpt: { type: ['string', 'null'], minLength: 1, maxLength: 2048 },
-      referenceTime: dateTime,
-      summary: longText,
-      sensitivity: enumSchema(['normal', 'private', 'restricted']),
-      entities: arraySchema(entity, { minItems: 1, maxItems: 128 }),
-      relationships: arraySchema(relationship, { maxItems: 256 })
+      sensitivity: enumSchema(['normal', 'private', 'restricted'])
     }, [
-      'targetKind', 'spaceId', 'idempotencyKey', 'sessionId', 'name',
-      'sourceKind', 'sourceDescription', 'referenceTime', 'entities', 'relationships'
+      'personalSpaceId', 'sessionId', 'idempotencyKey', 'decisionKey',
+      'title', 'question', 'selectedOption', 'reason', 'decidedBy',
+      'referenceTime', 'sourceKind', 'sourceDescription'
     ])
   },
   {
     name: 'search_knowledge_graph',
     title: 'READ · Search the scoped knowledge graph',
-    description: 'Search durable context before saying you do not know when a task may depend on remembered URLs, routes, requirements, architecture, prior decisions, runbooks, rationale, or personal preferences. Pending knowledge is searchable and explicitly marked; agent-confirmed knowledge ranks below human-confirmed knowledge. The bounded scope includes the personal-global profile, exact active local project, selectively inheritable knowledge reached through PART_OF or USES_KNOWLEDGE_FROM, explicitly selected additional personal projects, and selected subscribed team projects. Generic RELATED_TO links never expand scope. Use all_local_confirmed only after explicit user confirmation; it searches registered local personal projects for this query and never expands public projects. If that still has no support, use read-only local file search in the current repository or workspace files within a safe root. The response includes sourceMarker for supporting results, noMatchSourceMarker when returned items do not support the answer, and retrievalGuidance with the required next action.',
+    description: 'Search durable context before saying you do not know when a task may depend on remembered URLs, routes, requirements, architecture, prior decisions, runbooks, rationale, or personal preferences. Supporting facts and entities expose bounded source_uris when their evidence came from online sources, allowing a capable Agent to re-read the original source before refreshing Fuli knowledge. Pending knowledge is searchable and explicitly marked; agent-confirmed knowledge ranks below human-confirmed knowledge. The bounded scope includes the personal-global profile, exact active local project, selectively inheritable knowledge reached through PART_OF or USES_KNOWLEDGE_FROM, explicitly selected additional personal projects, and selected subscribed team projects. Generic RELATED_TO links never expand scope. Use all_local_confirmed only after explicit user confirmation; it searches registered local personal projects for this query and never expands public projects. If that still has no support, use read-only local file search in the current repository or workspace files within a safe root. The response includes sourceMarker for supporting results, noMatchSourceMarker when returned items do not support the answer, and retrievalGuidance with the required next action.',
     inputSchema: objectSchema({
       personalSpaceId: id,
       query: shortText,
@@ -240,6 +338,76 @@ export const GRAPH_TOOL_DEFINITIONS = [
       }, ['itemId', 'itemKind', 'useKind']), { minItems: 1, maxItems: 200 })
     }, ['personalSpaceId', 'taskId', 'items'])
   },
+  {
+    name: 'record_knowledge_feedback',
+    title: 'WRITE · Record negative knowledge evidence',
+    description: 'Record bounded negative evidence when retained knowledge is rejected, fails validation, is contradicted, or becomes outdated. Each event requires a reason and evidence summary and is idempotent per task, item, feedback kind, and content generation. It lowers ranking signals and marks the item requires_attention. It never deletes evidence or silently overrides human-confirmed authority; trusted human/source contradiction can return agent-confirmed knowledge to pending.',
+    inputSchema: objectSchema({
+      personalSpaceId: id,
+      taskId: id,
+      sessionId: nullableStringSchema(),
+      toolName: nullableStringSchema(),
+      items: arraySchema(objectSchema({
+        itemId: id,
+        itemKind: knowledgeItemKind,
+        feedbackKind: enumSchema([
+          'rejected', 'validation_failed', 'contradicted', 'outdated'
+        ]),
+        reason: boundedString(2000),
+        evidenceSummary: boundedString(4096),
+        reportedByKind: enumSchema([
+          'user', 'agent', 'authoritative_source'
+        ]),
+        sourceUri
+      }, [
+        'itemId', 'itemKind', 'feedbackKind', 'reason',
+        'evidenceSummary', 'reportedByKind'
+      ]), { minItems: 1, maxItems: 200 })
+    }, ['personalSpaceId', 'taskId', 'items'])
+  },
+  {
+    name: 'search_current_project_knowledge',
+    title: 'READ · Search current project and its knowledge sources',
+    description: 'High-level project search for normal Agent work. Pass projectPath plus one or more focused queries; Fuli resolves the exact local project, searches its local knowledge first, then follows outgoing PART_OF or USES_KNOWLEDGE_FROM relations to authorized parent/source knowledge. An exact current-project item with the same stable key overrides an inherited item. The tool never guesses an ambiguous project and never traverses RELATED_TO.',
+    inputSchema: objectSchema({
+      projectPath: boundedString(4096),
+      queries: arraySchema(shortText, { minItems: 1, maxItems: 10 }),
+      limitPerQuery: integerSchema({ minimum: 1, maximum: 50 }),
+      includeHistorical: booleanSchema(),
+      includePending: booleanSchema()
+    }, ['projectPath', 'queries'])
+  },
+  {
+    name: 'discover_common_knowledge_candidates',
+    title: 'READ · Find possible parent-project knowledge',
+    description: 'Read-only governance aid for one parent personal project. It searches each direct PART_OF child independently, excludes inherited and personal-global results, and groups lexically similar knowledge found in multiple children. Similarity is only an inferred candidate signal: the tool never merges, promotes, rewrites, or invalidates knowledge, and every candidate requires explicit human confirmation before a separate promotion action.',
+    inputSchema: objectSchema({
+      personalSpaceId: id,
+      parentProjectId: id,
+      query: shortText,
+      minChildProjects: integerSchema({ minimum: 2, maximum: 32 }),
+      similarityThreshold: numberSchema({ minimum: 0, maximum: 1 }),
+      limitPerProject: integerSchema({ minimum: 1, maximum: 50 })
+    }, ['personalSpaceId', 'parentProjectId', 'query'])
+  },
+  {
+    name: 'preview_common_knowledge_promotion',
+    title: 'CONFIRM · Preview parent-project promotion',
+    description: 'Validate the exact common-knowledge promotion after a human has explicitly chosen the canonical item, duplicates, parent project, and rationale. The preview is read-only, requires items from distinct direct PART_OF children, and returns a short-lived token binding the exact intent. Do not treat inferred lexical similarity as human confirmation.',
+    inputSchema: objectSchema(
+      commonKnowledgePromotionIntent,
+      commonKnowledgePromotionRequired
+    )
+  },
+  {
+    name: 'apply_common_knowledge_promotion',
+    title: 'WRITE · Atomically promote parent knowledge',
+    description: 'Apply one human-confirmed preview as a single Provider mutation. It moves the canonical item to the parent, enables descendants inheritance, invalidates selected child duplicates with replacement links, and stores both the scope reason and human-confirmation reason in permanent revision history. A valid one-time previewToken is mandatory.',
+    inputSchema: objectSchema({
+      ...commonKnowledgePromotionIntent,
+      previewToken: id
+    }, [...commonKnowledgePromotionRequired, 'previewToken'])
+  },
   {
     name: 'get_knowledge_graph',
     description: 'Return a bounded node-edge graph for a personal space, one exact local personal project, or a team-shared project.',

package/src/agent-tools/graph-handlers.js

@@ -1,6 +1,10 @@
 import { ApplicationError } from '../app/application-error.js';
 
 const HANDLERS = Object.freeze({
+  begin_task_context: (app, input) => app.beginTaskContext(input),
+  checkpoint_task_knowledge: (app, input) =>
+    app.checkpointTaskKnowledge(input),
+  verify_task_checkpoint: (app, input) => app.verifyTaskCheckpoint(input),
   get_collaboration_preferences: (app, input) => app.getCollaborationPreferences({
     ...input,
     agentInvocation: true,
@@ -12,12 +16,27 @@ const HANDLERS = Object.freeze({
       operationActor: 'agent'
     }),
   capture_session_knowledge: (app, input) => app.captureSessionKnowledge(input),
+  record_decision_trace: (app, input) => app.recordDecisionTrace(input),
   search_knowledge_graph: (app, input) => app.searchKnowledge({
     ...input,
     agentInvocation: true,
     agentToolName: 'search_knowledge_graph'
   }),
   record_knowledge_usage: (app, input) => app.recordKnowledgeUsage(input),
+  record_knowledge_feedback: (app, input) => app.recordKnowledgeFeedback(input),
+  search_current_project_knowledge: (app, input) =>
+    app.searchCurrentProjectKnowledge(input),
+  discover_common_knowledge_candidates: (app, input) =>
+    app.discoverCommonKnowledgeCandidates(input),
+  preview_common_knowledge_promotion: (app, input) =>
+    app.previewCommonKnowledgePromotion(input),
+  apply_common_knowledge_promotion: (app, input) => {
+    const { previewToken: _previewToken, ...promotion } = input;
+    return app.applyCommonKnowledgePromotion({
+      ...promotion,
+      operationActor: 'agent'
+    });
+  },
   get_knowledge_graph: (app, input) => app.getKnowledgeGraph({
     ...input,
     agentInvocation: true,

package/src/cli/command-registry.js

@@ -1,78 +1,25 @@
-import { candidate, candidates } from './commands/candidates.js';
-import { observe, remember } from './commands/ingestion.js';
-import { context, history, rules, search, timeline } from './commands/reads.js';
-import { createSpace, subscribe } from './commands/spaces.js';
-
-const COMMANDS = Object.freeze({
-  space: createSpace,
-  subscribe,
-  remember,
-  observe,
-  search,
-  timeline,
-  rules,
-  history,
-  context,
-  candidates,
-  candidate
-});
-
 const LOCAL_RUNTIME_COMMANDS = new Set(['start', 'stop', 'restart', 'status', 'open']);
 
-export function dispatchCommand(app, command, args) {
-  const handler = COMMANDS[command];
-  if (!handler) throw new Error(`Unknown command: ${command}`);
-  return handler(app, args);
-}
-
-export function isRegisteredCommand(command) {
-  return command === '--help' || command === '-h' ||
-    command === '--version' || command === '-v' ||
-    Object.hasOwn(COMMANDS, command);
-}
-
-export function isCliCommand(command) {
-  return command === 'setup' || command === 'uninstall' || command === 'migrate' ||
-    LOCAL_RUNTIME_COMMANDS.has(command) || isRegisteredCommand(command);
-}
-
 export function isLocalRuntimeCommand(command) {
   return LOCAL_RUNTIME_COMMANDS.has(command);
 }
 
 export function printHelp() {
-  console.log(`fl <command>
+  console.log(`fuli <command>  (short alias: fl)
 
 General:
   --help, -h
   --version, -v
 
 Local service:
-  start [--port 2727] [--open] [--rebuild] [--data-dir DIR]
+  start [--port 2727] [--open] [--rebuild] [--data-dir DIR] [--personal-space NAME]
   stop [--data-dir DIR]
-  restart [--port 2727] [--open] [--rebuild] [--data-dir DIR]
+  restart [--port 2727] [--open] [--rebuild] [--data-dir DIR] [--personal-space NAME]
   status [--json] [--data-dir DIR]
   open [--data-dir DIR]
 
 Install and Agent connection:
-  setup [--yes] [--codex-only] [--data-dir DIR] [--personal-space NAME] [--port PORT] [--skip-agents] [--no-start] [--with-dev-public]
-  uninstall [--yes] [--data-dir DIR]
-
-Legacy local knowledge commands:
-  fl [--db SQLITE_DB] [--personal-space 我] <command>
-  Global options must appear before the command.
-
-Commands:
-  space create NAME --kind personal|public
-  subscribe PERSONAL_SPACE PUBLIC_SPACE
-  remember PERSONAL_SPACE --target SPACE --source-kind prd --text TEXT
-  observe PERSONAL_SPACE --target SPACE
-  search PERSONAL_SPACE QUERY
-  timeline SPACE SUBJECT
-  rules SPACE
-  history SPACE PREDICATE
-  context PERSONAL_SPACE SPACE QUERY
-  candidates PERSONAL_SPACE
-  candidate CANDIDATE_ID sync|personal_only|ignore
-  migrate --from LEGACY_JSON --to SQLITE_DB`);
+  setup [--yes] [--codex-only] [--data-dir DIR] [--personal-space NAME] [--port PORT] [--skip-agents] [--no-start] [--personal-only|--with-dev-public]
+  update [setup options]
+  uninstall [--yes] [--data-dir DIR]`);
 }

package/src/cli/update-command.js

@@ -0,0 +1,293 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { posix, win32 } from 'node:path';
+import { createInterface } from 'node:readline/promises';
+
+import {
+  FULI_PACKAGE_NAME,
+  FULI_VERSION
+} from '../package-metadata.js';
+import { quoteShellArgument } from '../runtime-options.js';
+import { parseUpdateOptions } from '../setup/options.js';
+import { runLocalRuntimeCommand } from './local-runtime-command.js';
+
+const LATEST_PACKAGE = `${FULI_PACKAGE_NAME}@latest`;
+
+export async function runUpdateCommand(args = [], dependencies = {}) {
+  const options = parseUpdateOptions(args);
+  const env = dependencies.env ?? process.env;
+  const platform = dependencies.platform ?? process.platform;
+  const nodePath = dependencies.nodePath ?? process.execPath;
+  const npmCommand = dependencies.npmCommand ??
+    (platform === 'win32' ? 'npm.cmd' : 'npm');
+  const confirm = dependencies.confirm ?? confirmInTerminal;
+  const write = dependencies.write ?? writeLine;
+  const stopRuntime = dependencies.stopRuntime ?? runLocalRuntimeCommand;
+  const runInherited = dependencies.runInherited ?? spawnInherited;
+  const runCaptured = dependencies.runCaptured ?? spawnCaptured;
+  const fileExists = dependencies.fileExists ?? existsSync;
+  const resolveLatestVersion = dependencies.resolveLatestVersion ??
+    (() => queryLatestVersion(npmCommand, runCaptured, env));
+
+  write(formatUpdatePreview(options));
+  if (!options.yes && !await confirm()) {
+    write('已取消，没有修改任何内容。');
+    return { status: 'cancelled' };
+  }
+
+  const latestVersion = resolveLatestVersion();
+  if (compareSemanticVersions(latestVersion, FULI_VERSION) < 0) {
+    const result = {
+      status: 'ahead',
+      previousVersion: FULI_VERSION,
+      version: FULI_VERSION,
+      latestVersion
+    };
+    write(formatUpdateResult(result));
+    return result;
+  }
+
+  const stopArgs = options.dataDir ? ['--data-dir', options.dataDir] : [];
+  const stopped = await stopRuntime('stop', stopArgs, { env, write });
+  if (stopped.status === 'partial') {
+    throw new Error([
+      '无法安全确认旧版界面进程已停止，更新尚未开始。',
+      '请先运行 fuli status 检查本地状态，再重试 fuli update。'
+    ].join('\n'));
+  }
+
+  const selectedPackage = `${FULI_PACKAGE_NAME}@${latestVersion}`;
+  write(`正在安装 ${selectedPackage}（npm latest）…`);
+  const installed = runInherited(npmCommand, [
+    'install',
+    '--global',
+    selectedPackage,
+    '--no-audit',
+    '--no-fund'
+  ], { env });
+  if (!processSucceeded(installed)) {
+    throw new Error([
+      `全局包安装失败（${describeProcessFailure(installed)}）。知识数据未删除。`,
+      `请先运行 npm install --global ${LATEST_PACKAGE}，再运行 fuli setup --yes。`
+    ].join('\n'));
+  }
+
+  const globalRootResult = runCaptured(npmCommand, ['root', '--global'], { env });
+  if (!processSucceeded(globalRootResult)) {
+    throw postInstallError(
+      `无法定位 npm 全局安装目录（${describeProcessFailure(globalRootResult)}）`,
+      args,
+      platform
+    );
+  }
+  const globalRoot = String(globalRootResult.stdout ?? '').trim();
+  const cliPath = resolveGlobalCliPath(globalRoot, platform);
+  if (!cliPath || !fileExists(cliPath)) {
+    throw postInstallError('新版 CLI 文件不存在，请重新安装全局包', args, platform);
+  }
+
+  const versionResult = runCaptured(nodePath, [cliPath, '--version'], { env });
+  if (!processSucceeded(versionResult)) {
+    throw postInstallError(
+      `新版 CLI 无法启动（${describeProcessFailure(versionResult)}）`,
+      args,
+      platform
+    );
+  }
+  const version = String(versionResult.stdout ?? '').trim();
+  if (!version) throw postInstallError('新版 CLI 未返回版本号', args, platform);
+  if (compareSemanticVersions(version, latestVersion) !== 0) {
+    throw postInstallError(
+      `新版 CLI 版本 ${version} 与更新前确认的 npm latest ${latestVersion} 不一致`,
+      args,
+      platform
+    );
+  }
+
+  write('正在使用新版 CLI 刷新本机服务、Agent 接入和 Skills…');
+  const setupArgs = ['setup', '--yes', ...args.filter((arg) => arg !== '--yes')];
+  const setupResult = runInherited(nodePath, [cliPath, ...setupArgs], { env });
+  if (!processSucceeded(setupResult)) {
+    throw postInstallError(
+      `新版已安装，但 setup 未完成（${describeProcessFailure(setupResult)}）`,
+      args,
+      platform
+    );
+  }
+
+  const result = {
+    status: version === FULI_VERSION ? 'current' : 'updated',
+    previousVersion: FULI_VERSION,
+    version
+  };
+  write(formatUpdateResult(result));
+  return result;
+}
+
+export function formatUpdatePreview(options) {
+  return [
+    '准备更新复利',
+    `npm 包：${LATEST_PACKAGE}`,
+    options.noStart
+      ? '本地界面：安全停止；更新后保持关闭'
+      : '本地服务：安全停止；更新后由新版重新启动',
+    options.dataDir ? `数据：保留 ${options.dataDir}` : '数据：保留当前默认数据目录',
+    `Agent 接入与 Skills：${options.skipAgents ? '按参数跳过刷新' : '由新版 setup 刷新'}`
+  ].join('\n');
+}
+
+export function formatUpdateResult(result) {
+  if (result.status === 'ahead') {
+    return [
+      `当前 CLI 版本 ${result.version} 高于 npm latest ${result.latestVersion}；`,
+      '为避免降级，未停止服务、未安装包，也未修改 Agent 接入。'
+    ].join('');
+  }
+  if (result.status === 'current') {
+    return `复利已是最新版本 ${result.version}；本机接入已刷新。`;
+  }
+  return `复利已从 ${result.previousVersion} 更新到 ${result.version}。`;
+}
+
+export function compareSemanticVersions(left, right) {
+  const parsedLeft = parseSemanticVersion(left);
+  const parsedRight = parseSemanticVersion(right);
+  for (let index = 0; index < 3; index += 1) {
+    if (parsedLeft.core[index] > parsedRight.core[index]) return 1;
+    if (parsedLeft.core[index] < parsedRight.core[index]) return -1;
+  }
+  if (!parsedLeft.prerelease.length && !parsedRight.prerelease.length) return 0;
+  if (!parsedLeft.prerelease.length) return 1;
+  if (!parsedRight.prerelease.length) return -1;
+  const length = Math.max(parsedLeft.prerelease.length, parsedRight.prerelease.length);
+  for (let index = 0; index < length; index += 1) {
+    const leftPart = parsedLeft.prerelease[index];
+    const rightPart = parsedRight.prerelease[index];
+    if (leftPart === undefined) return -1;
+    if (rightPart === undefined) return 1;
+    if (leftPart === rightPart) continue;
+    const leftNumeric = /^\d+$/.test(leftPart);
+    const rightNumeric = /^\d+$/.test(rightPart);
+    if (leftNumeric && rightNumeric) {
+      return BigInt(leftPart) > BigInt(rightPart) ? 1 : -1;
+    }
+    if (leftNumeric !== rightNumeric) return leftNumeric ? -1 : 1;
+    return leftPart > rightPart ? 1 : -1;
+  }
+  return 0;
+}
+
+export function resolveGlobalCliPath(globalRoot, platform = process.platform) {
+  const path = platform === 'win32' ? win32 : posix;
+  if (typeof globalRoot !== 'string' || !path.isAbsolute(globalRoot.trim())) return null;
+  return path.join(globalRoot.trim(), FULI_PACKAGE_NAME, 'src', 'cli.js');
+}
+
+function postInstallError(message, args, platform) {
+  return new Error([
+    `${message}。知识数据未删除。`,
+    `请重新运行：${formatSetupRecoveryCommand(args, platform)}`
+  ].join('\n'));
+}
+
+function queryLatestVersion(npmCommand, runCaptured, env) {
+  const result = runCaptured(
+    npmCommand,
+    ['view', LATEST_PACKAGE, 'version', '--json'],
+    { env }
+  );
+  if (!processSucceeded(result)) {
+    throw new Error([
+      `无法检查 ${LATEST_PACKAGE}（${describeProcessFailure(result)}）。`,
+      '本地服务尚未停止，也没有安装或修改任何包。'
+    ].join('\n'));
+  }
+  const raw = String(result.stdout ?? '').trim();
+  let version = raw;
+  try {
+    const parsed = JSON.parse(raw);
+    if (typeof parsed === 'string') version = parsed;
+  } catch {
+    // npm can also return one unquoted version line.
+  }
+  parseSemanticVersion(version);
+  return version;
+}
+
+function parseSemanticVersion(value) {
+  const text = String(value ?? '').trim();
+  const match = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/
+    .exec(text);
+  if (!match) throw new TypeError(`Invalid package version: ${text || '<empty>'}`);
+  const numeric = match.slice(1, 4);
+  if (numeric.some((part) => part.length > 1 && part.startsWith('0'))) {
+    throw new TypeError(`Invalid package version: ${text}`);
+  }
+  return {
+    core: numeric.map((part) => BigInt(part)),
+    prerelease: match[4]?.split('.') ?? []
+  };
+}
+
+function formatSetupRecoveryCommand(args, platform) {
+  const forwarded = args
+    .filter((arg) => arg !== '--yes')
+    .map((arg) => formatCommandArgument(arg, platform));
+  return ['fuli', 'setup', '--yes', ...forwarded].join(' ');
+}
+
+function formatCommandArgument(value, platform) {
+  const simple = platform === 'win32'
+    ? /^[A-Za-z0-9_./\\:@+-]+$/
+    : /^[A-Za-z0-9_./:@+-]+$/;
+  if (simple.test(value)) return value;
+  try {
+    return quoteShellArgument(value, platform);
+  } catch {
+    return '<复用原参数>';
+  }
+}
+
+function processSucceeded(result) {
+  return result?.status === 0 && !result.error && !result.signal;
+}
+
+function describeProcessFailure(result) {
+  if (result?.error?.message) return result.error.message;
+  if (result?.signal) return `signal ${result.signal}`;
+  if (Number.isInteger(result?.status)) return `exit code ${result.status}`;
+  return 'unknown process error';
+}
+
+function spawnInherited(command, args, { env }) {
+  return spawnSync(command, args, {
+    env,
+    stdio: 'inherit',
+    windowsHide: true
+  });
+}
+
+function spawnCaptured(command, args, { env }) {
+  return spawnSync(command, args, {
+    env,
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+    windowsHide: true
+  });
+}
+
+async function confirmInTerminal() {
+  const input = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const answer = (await input.question('将修改全局 npm 安装，继续？[Y/n] '))
+      .trim()
+      .toLowerCase();
+    return answer === '' || answer === 'y' || answer === 'yes';
+  } finally {
+    input.close();
+  }
+}
+
+function writeLine(value) {
+  process.stdout.write(`${value}\n`);
+}