fuli-context 0.2.0 → 0.3.0

package/README.md

@@ -19,10 +19,10 @@ Cursor 在会话之间复用个人偏好、项目约束、历史决策与 Runboo
 
 ```bash
 npm install --global fuli-context
-fl setup
+fuli setup
 ```
 
-`fl setup` 会先展示即将进行的操作，再请求确认。它会检查容器运行时、初始化本机
+`fuli setup` 会先展示即将进行的操作，再请求确认。它会检查容器运行时、初始化本机
 Graphiti / Neo4j、创建个人空间、安装配套 Agent Skills，并为检测到的 Agent 注册
 `fuli` MCP。Codex 接入还会在用户级 `AGENTS.md` 中合并一段很短的 Bootstrap：每个
 用户任务开始时先调用协作偏好工具，并把当前工作目录作为 `projectPath` 传给 Fuli。
@@ -32,59 +32,152 @@ Provider。
 初始化完成后：
 
 ```bash
-fl open
+fuli open
 ```
 
 管理界面默认位于 `http://127.0.0.1:2727`。
 
-## 常用命令
+## CLI 使用
+
+全局安装会提供两个等价命令：
+
+- `fuli`：完整命令名，文档默认使用它；
+- `fl`：短别名，例如 `fl status` 与 `fuli status` 完全相同。
+
+查看版本和内置帮助：
+
+```bash
+fuli --version
+fuli --help
+```
+
+### 本地服务与安装
+
+| 命令 | 用途 |
+| --- | --- |
+| `fuli setup [选项]` | 初始化 Provider、管理界面、Agent 接入和 Skills；可重复执行 |
+| `fuli start [选项]` | 启动本机服务 |
+| `fuli stop [--data-dir DIR]` | 安全停止本机服务并保留数据 |
+| `fuli restart [选项]` | 重启本机服务 |
+| `fuli status [--json]` | 查看服务状态；`--json` 输出机器可读结果 |
+| `fuli open` | 在浏览器中打开管理界面 |
+| `fuli update [setup 选项]` | 更新全局 npm 包，并用新版 CLI 刷新本机接入 |
+| `fuli uninstall [--yes]` | 清理 Agent 接入和服务，保留知识数据 |
+
+常用示例：
+
+```bash
+fuli start
+fuli start --open
+fuli status
+fuli status --json
+fuli restart
+fuli restart --rebuild
+fuli stop
+```
+
+`fuli stop` 只停止本机服务，不删除图谱数据。
+
+`start` 和 `restart` 可使用 `--data-dir DIR`、`--personal-space NAME`、`--port PORT`；
+`--open` 会在启动后打开管理界面，`--rebuild` 会重新构建本机 Provider 容器。
+
+### setup 选项
+
+| 选项 | 用途 |
+| --- | --- |
+| `--yes` | 跳过确认，适合无人值守执行 |
+| `--data-dir DIR` | 使用指定数据目录；后续命令应继续传入同一路径 |
+| `--personal-space NAME` | 设置首次初始化时的个人空间名称，默认是 `我` |
+| `--port PORT` | 设置管理界面端口，默认是 `2727` |
+| `--codex-only` | 只接入 Codex |
+| `--skip-agents` | 不修改 Agent 配置，也不刷新 Agent Skills |
+| `--no-start` | 初始化 Provider，但不启动管理界面 |
+| `--personal-only` | 只使用个人 Provider；这是默认模式 |
+| `--with-dev-public` | 同时启动本机开发用公共 Provider，仅用于开发或联调 |
+
+例如，无人值守地完成默认初始化：
 
 ```bash
-fl --version
-fl --help
-
-fl start
-fl start --open
-fl status
-fl status --json
-fl open
-fl restart
-fl restart --rebuild
-fl stop
+fuli setup --yes
 ```
 
-`fl stop` 只停止本机服务，不删除图谱数据。需要无人值守初始化时可以使用：
+使用自定义数据目录和管理界面端口：
 
 ```bash
-fl setup --yes
+fuli setup --data-dir "./fuli-data" --port 3727
 ```
 
 只初始化 Provider、不启动管理界面：
 
 ```bash
-fl setup --no-start
+fuli setup --no-start
 ```
 
 ## 更新
 
 ```bash
-fl stop
+fuli update
+```
+
+`fuli update` 默认先展示更新计划并请求确认。需要无人值守执行时：
+
+```bash
+fuli update --yes
+```
+
+更新流程会先查询 npm 的 `latest` 版本；确认不会降级后，才安全停止旧版服务、安装当时
+的 `fuli-context@latest` 对应版本，再直接使用新安装版本的 CLI 执行 `setup --yes`。
+既有知识数据、配置备份和 Neo4j 数据卷不会删除；即使 npm 上已经是当前版本，也会刷新
+Agent 接入和配套 Skills。`update` 支持上表中的全部 setup 选项；使用过自定义数据目录、
+端口或 Provider 模式时，应在更新时重复传入相同选项。
+
+如果当前 CLI 来自尚未发布的工作区版本，并且版本号高于 npm `latest`，更新会在停止服务
+和安装包之前退出，避免把开发版本降级。
+
+如果当前已安装版本尚不识别 `update`，需要先手动升级一次到包含该命令的版本：
+
+```bash
 npm install --global fuli-context@latest
-fl setup --yes
+fuli setup --yes
+```
+
+如果自动更新在 npm 安装或新版 setup 阶段失败，知识数据仍会保留。检查命令输出后可用
+上面两条命令恢复；使用过自定义 setup 选项时也要一并带上。
+
+## 兼容的本地知识命令
+
+以下命令面向旧版 SQLite 工作流和开发调试。`--db`、`--personal-space` 是全局选项，
+必须写在子命令之前：
+
+```bash
+fuli --db ./context.db --personal-space 我 search 我 "关键词"
 ```
 
-重复执行 setup 会保留既有知识数据，并刷新 Agent 接入和配套 Skills。
+| 命令 | 用途 |
+| --- | --- |
+| `space create NAME --kind personal\|public` | 创建个人或公共空间 |
+| `subscribe PERSONAL_SPACE PUBLIC_SPACE` | 订阅公共空间 |
+| `remember PERSONAL_SPACE --target SPACE --source-kind KIND --text TEXT` | 写入一段待归纳内容 |
+| `observe PERSONAL_SPACE --target SPACE` | 观察当前 Git 改动 |
+| `search PERSONAL_SPACE QUERY` | 搜索当前事实 |
+| `timeline SPACE SUBJECT` | 查看主题时间线 |
+| `rules SPACE` | 查看空间规则 |
+| `history SPACE PREDICATE` | 查看某个事实的修订历史 |
+| `context PERSONAL_SPACE SPACE QUERY` | 输出紧凑的 Agent 上下文包 |
+| `candidates PERSONAL_SPACE` | 列出待处理候选知识 |
+| `candidate ID sync\|personal_only\|ignore` | 处理候选知识 |
+| `migrate --from LEGACY_JSON --to SQLITE_DB` | 将旧 JSON 数据迁移到 SQLite |
 
 ## 卸载
 
 先清理 Agent 接入，再移除全局 npm 包：
 
 ```bash
-fl uninstall
+fuli uninstall
 npm uninstall --global fuli-context
 ```
 
-`fl uninstall` 会：
+`fuli uninstall` 会：
 
 - 停止本机 Fuli 服务；
 - 从 Codex、Claude Code 和 Cursor 中移除 Fuli MCP 接入；
@@ -170,8 +263,8 @@ docker compose -f compose.graphiti.yml config --quiet
 ```
 
 `npm run test:package` 会构建前端、生成真实 npm tarball、安装到隔离的全局前缀，并验证
-`fl`、版本号、帮助信息和已发布 Web UI。测试源码、QA 截图与内部设计文档都不会进入
-npm 包。
+`fuli` / `fl`、版本号、帮助信息和已发布 Web UI。测试源码、QA 截图与内部设计文档
+都不会进入 npm 包。
 
 ## License
 

package/graph-provider/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "fuli-graph-provider"
-version = "0.2.0"
+version = "0.3.0"
 description = "Graphiti-backed personal and shared project provider for Fuli."
 requires-python = ">=3.12"
 dependencies = [

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "fuli-context",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "fuli-context",
-      "version": "0.2.0",
+      "version": "0.3.0",
       "license": "Apache-2.0",
       "dependencies": {
         "@hono/node-server": "2.0.12",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fuli-context",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Local-first context graph for AI agents.",
   "type": "module",
   "files": [

package/skills/capturing-session-knowledge/SKILL.md

@@ -105,8 +105,9 @@ For the chosen marker, the final answer must begin with its `leadMarkdown` uncha
 before any heading or prose, and append its `markdown` unchanged after the answer. If
 any search supports the answer, choose `sourceMarker` from one supporting search. If
 none do, choose `noMatchSourceMarker`. Never show either marker when no search was
-called. Never fabricate, rewrite, omit, or wrap markers in HTML. A capture or write
-result is not a read citation.
+called. For a no-match search, `noMatchSourceMarker.markdown` is intentionally empty:
+show only its `leadMarkdown` and do not synthesize a footer. Never fabricate, rewrite,
+omit, or wrap markers in HTML. A capture or write result is not a read citation.
 
 ## Decide What Persists
 

package/src/cli/command-registry.js

@@ -32,7 +32,8 @@ export function isRegisteredCommand(command) {
 }
 
 export function isCliCommand(command) {
-  return command === 'setup' || command === 'uninstall' || command === 'migrate' ||
+  return command === 'setup' || command === 'update' ||
+    command === 'uninstall' || command === 'migrate' ||
     LOCAL_RUNTIME_COMMANDS.has(command) || isRegisteredCommand(command);
 }
 
@@ -41,25 +42,26 @@ export function isLocalRuntimeCommand(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]
+  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]
 
 Legacy local knowledge commands:
-  fl [--db SQLITE_DB] [--personal-space 我] <command>
+  fuli [--db SQLITE_DB] [--personal-space 我] <command>
   Global options must appear before the command.
 
 Commands:

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`);
+}

package/src/cli.js

@@ -13,6 +13,7 @@ import { runLocalRuntimeCommand } from './cli/local-runtime-command.js';
 import { migrateLegacyJson } from './cli/migrate-command.js';
 import { runSetupCommand } from './cli/setup-command.js';
 import { runUninstallCommand } from './cli/uninstall-command.js';
+import { runUpdateCommand } from './cli/update-command.js';
 import { FULI_VERSION } from './package-metadata.js';
 import { assertSupportedNodeVersion } from './setup/node-runtime.js';
 import {
@@ -52,6 +53,13 @@ export async function main(argv = process.argv.slice(2), env = process.env) {
     await runUninstallCommand(commandArgs, { env });
     return;
   }
+  if (command === 'update') {
+    if (runtimeArgs.length) {
+      throw new TypeError('Update options must appear after the update command');
+    }
+    assertSupportedNodeVersion();
+    return runUpdateCommand(commandArgs, { env });
+  }
   if (isLocalRuntimeCommand(command)) {
     if (runtimeArgs.length) {
       throw new TypeError(`${command} options must appear after the command`);

package/src/graphiti/source-marker.js

@@ -90,13 +90,7 @@ function sourceLeadMarkdown({ consoleUrl, citations }) {
 }
 
 function sourceMarkerMarkdown({ consoleUrl, citations }) {
-  if (!citations.length) {
-    return [
-      '**FULI 来源 · 未命中**',
-      '',
-      `- [打开 Fuli](${safeLoopbackOrigin(consoleUrl) ?? DEFAULT_CONSOLE_URL}/)`
-    ].join('\n');
-  }
+  if (!citations.length) return '';
   const shown = citations.slice(0, MAX_CITATIONS);
   const hidden = citations.length - shown.length;
   return [

package/src/http/static-handler.js

@@ -1,9 +1,10 @@
-import { existsSync, readFileSync } from 'node:fs';
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import { extname, isAbsolute, join, normalize, relative, resolve, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 const PROJECT_ROOT = resolve(fileURLToPath(new URL('../..', import.meta.url)));
 export const WEB_ROOT = join(PROJECT_ROOT, 'dist', 'web');
+const FULI_LOGO_PATTERN = /^fuli-logo(?:-[A-Za-z0-9_-]+)?\.png$/;
 const MIME_TYPES = {
   '.html': 'text/html; charset=utf-8',
   '.css': 'text/css; charset=utf-8',
@@ -18,8 +19,17 @@ const MIME_TYPES = {
 
 export function serveStatic(pathname, response) {
   if (pathname === '/favicon.ico') {
-    response.writeHead(204);
-    response.end();
+    const filePath = faviconFilePath();
+    if (!filePath) {
+      response.writeHead(204);
+      response.end();
+      return;
+    }
+    response.writeHead(200, {
+      'cache-control': 'public, max-age=86400',
+      'content-type': 'image/png'
+    });
+    response.end(readFileSync(filePath));
     return;
   }
 
@@ -50,6 +60,22 @@ export function serveStatic(pathname, response) {
   response.end(readFileSync(filePath));
 }
 
+function faviconFilePath() {
+  const directPath = join(WEB_ROOT, 'favicon.png');
+  if (existsSync(directPath)) return directPath;
+
+  const assetsPath = join(WEB_ROOT, 'assets');
+  if (!existsSync(assetsPath)) return null;
+  try {
+    const filename = readdirSync(assetsPath)
+      .sort()
+      .find((candidate) => FULI_LOGO_PATTERN.test(candidate));
+    return filename ? join(assetsPath, filename) : null;
+  } catch {
+    return null;
+  }
+}
+
 function shouldServeApplication(pathname) {
   return extname(pathname) === '' && !pathname.startsWith('/api/');
 }

package/src/mcp/instructions.js

@@ -6,5 +6,5 @@ export const MCP_INSTRUCTIONS = [
   'Changing/live: use monitoring or Git MCP',
   'Silently batch via capture_session_knowledge under personalProjectId. Never store secrets, transcripts, or guesses. Only human/source confirmed knowledge enters public review. Final checkpoint: flush or retain nothing.',
   'When personal knowledge affects the final answer/action, call record_knowledge_usage. Retrieval/injection never count; it creates at most agent_confirmed, never public eligibility.',
-  'Searches return terminal-safe Markdown. Final MUST begin with sourceMarker.leadMarkdown and append sourceMarker.markdown unchanged; without support use noMatchSourceMarker. Never wrap markers in HTML, rewrite them, or cite writes as reads.'
+  'Terminal-safe Markdown. Final MUST begin with sourceMarker.leadMarkdown; append sourceMarker.markdown unchanged only on match. On miss use noMatchSourceMarker leadMarkdown only (empty markdown). Never wrap markers in HTML or cite writes.'
 ].join(' ');

package/src/setup/options.js

@@ -16,6 +16,14 @@ const BOOLEAN_OPTIONS = Object.freeze({
 const PROVIDER_MODE_OPTIONS = new Set(['--personal-only', '--with-dev-public']);
 
 export function parseSetupOptions(args = []) {
+  return parseSetupLikeOptions(args, 'setup');
+}
+
+export function parseUpdateOptions(args = []) {
+  return parseSetupLikeOptions(args, 'update');
+}
+
+function parseSetupLikeOptions(args, command) {
   const result = {
     dataDir: null,
     personalSpaceName: '我',
@@ -47,7 +55,7 @@ export function parseSetupOptions(args = []) {
       continue;
     }
     const valueKey = VALUE_OPTIONS[flag];
-    if (!valueKey) throw new TypeError(`Unknown setup option: ${flag}`);
+    if (!valueKey) throw new TypeError(`Unknown ${command} option: ${flag}`);
     const value = args[index + 1];
     if (typeof value !== 'string' || !value.trim() || value.startsWith('--')) {
       throw new TypeError(`Missing value for ${flag}`);