@biaoo/tiangong-wiki 0.2.1 → 0.2.2

package/README.md

@@ -24,6 +24,21 @@
 npm install -g @biaoo/tiangong-wiki
 ```
 
+## Update
+
+Upgrade the npm package itself:
+
+```bash
+npm install -g @biaoo/tiangong-wiki@latest
+```
+
+Refresh workspace-local managed skills after upgrading the CLI or when upstream skill content changes:
+
+```bash
+tiangong-wiki skill status
+tiangong-wiki skill update --all
+```
+
 <details>
 <summary><strong>Use as an AI Agent Skill</strong></summary>
 
@@ -47,6 +62,7 @@ To manage workspace-local skills from arbitrary repo/path sources after setup:
 tiangong-wiki skill add ../my-skills --skill notes
 tiangong-wiki skill status
 tiangong-wiki skill update notes
+tiangong-wiki skill update --all
 ```
 
 </details>
@@ -61,7 +77,14 @@ tiangong-wiki init                                    # initialize workspace
 tiangong-wiki sync                                    # index Markdown pages
 ```
 
-`tiangong-wiki setup` creates `.wiki.env`. Subsequent commands such as `doctor`, `init`, and `sync` should be run from the workspace root containing that `.wiki.env`, or with `WIKI_ENV_FILE` pointing to it explicitly.
+`tiangong-wiki setup` creates a workspace-local `.wiki.env` and records it as your default workspace config. Command resolution now follows this order:
+
+1. `--env-file <path>`
+2. `WIKI_ENV_FILE`
+3. The nearest `.wiki.env` found by walking upward from your current directory
+4. The global default workspace config written by `tiangong-wiki setup`
+
+That means commands still work best from inside a workspace, but they can also run from outside the workspace after setup, or target a specific workspace explicitly with `--env-file`.
 
 ```bash
 tiangong-wiki find --type concept --status active     # structured query
@@ -71,11 +94,12 @@ tiangong-wiki graph bayes-theorem --depth 2           # graph traversal
 ```
 
 ```bash
-tiangong-wiki daemon run                              # start dashboard & HTTP API
+tiangong-wiki daemon start                            # start the daemon in the background
 tiangong-wiki dashboard                               # open dashboard in browser
+# or: tiangong-wiki daemon run                        # run the daemon in the foreground for debugging
 ```
 
-> Environment variables are managed via `.wiki.env` (created by `tiangong-wiki setup`). The CLI auto-discovers the nearest `.wiki.env` by walking upward from your current directory. See [references/troubleshooting.md](./references/troubleshooting.md) for the full reference.
+> Environment variables are managed via `.wiki.env` (created by `tiangong-wiki setup`). The CLI prefers the nearest local `.wiki.env`, then falls back to the global default workspace config. See [references/troubleshooting.md](./references/troubleshooting.md) for the full reference.
 
 ## CLI
 

package/README.zh-CN.md

@@ -24,6 +24,21 @@
 npm install -g @biaoo/tiangong-wiki
 ```
 
+## 更新
+
+升级 npm 包本身：
+
+```bash
+npm install -g @biaoo/tiangong-wiki@latest
+```
+
+升级 CLI 后，或上游 skill 内容有更新时，刷新工作区本地 managed skills：
+
+```bash
+tiangong-wiki skill status
+tiangong-wiki skill update --all
+```
+
 <details>
 <summary><strong>作为 AI Agent Skill 使用</strong></summary>
 
@@ -47,6 +62,7 @@ tiangong-wiki setup
 tiangong-wiki skill add ../my-skills --skill notes
 tiangong-wiki skill status
 tiangong-wiki skill update notes
+tiangong-wiki skill update --all
 ```
 
 </details>
@@ -61,7 +77,14 @@ tiangong-wiki init                                    # 初始化工作区
 tiangong-wiki sync                                    # 索引 Markdown 文件
 ```
 
-`tiangong-wiki setup` 会创建 `.wiki.env`。后续的 `doctor`、`init`、`sync` 等命令应在包含该 `.wiki.env` 的工作区根目录执行；如果不在该目录执行，则需要显式设置 `WIKI_ENV_FILE` 指向它。
+`tiangong-wiki setup` 会创建工作区本地 `.wiki.env`，并将其记录为默认工作区配置。CLI 的配置解析优先级如下：
+
+1. `--env-file <path>`
+2. `WIKI_ENV_FILE`
+3. 从当前目录向上查找最近的 `.wiki.env`
+4. `tiangong-wiki setup` 写入的全局默认工作区配置
+
+这意味着命令仍然最适合在 workspace 内执行；但 setup 之后，即使在 workspace 外运行，也可以通过默认配置正常工作，或者通过 `--env-file` 显式指定目标工作区。
 
 ```bash
 tiangong-wiki find --type concept --status active     # 结构化查询
@@ -71,11 +94,12 @@ tiangong-wiki graph bayes-theorem --depth 2           # 图遍历
 ```
 
 ```bash
-tiangong-wiki daemon run                              # 启动仪表盘和 HTTP API
+tiangong-wiki daemon start                            # 后台启动 daemon
 tiangong-wiki dashboard                               # 在浏览器中打开仪表盘
+# 或者：tiangong-wiki daemon run                      # 前台运行 daemon，适合调试
 ```
 
-> 环境变量通过 `.wiki.env` 管理（由 `tiangong-wiki setup` 创建）。CLI 会从当前目录开始向上自动发现最近的 `.wiki.env`。完整参考见 [references/troubleshooting.md](./references/troubleshooting.md)。
+> 环境变量通过 `.wiki.env` 管理（由 `tiangong-wiki setup` 创建）。CLI 会优先使用最近的本地 `.wiki.env`，找不到时再 fallback 到全局默认工作区配置。完整参考见 [references/troubleshooting.md](./references/troubleshooting.md)。
 
 ## CLI
 

package/dist/core/cli-env.js

@@ -1,4 +1,5 @@
 import path from "node:path";
+import { readGlobalConfig } from "./global-config.js";
 import { pathExistsSync, readTextFileSync } from "../utils/fs.js";
 export const DEFAULT_WIKI_ENV_FILE = ".wiki.env";
 const EMPTY_INFO = {
@@ -6,6 +7,10 @@ const EMPTY_INFO = {
     loadedPath: null,
     autoDiscovered: false,
     missingRequestedPath: false,
+    missingDefaultPath: false,
+    source: "none",
+    globalConfigPath: null,
+    defaultPath: null,
     loadedKeys: [],
 };
 let lastCliEnvInfo = EMPTY_INFO;
@@ -86,20 +91,40 @@ export function applyCliEnvironment(targetEnv = process.env, cwd = process.cwd()
     const requestedEnvFile = targetEnv.WIKI_ENV_FILE?.trim();
     const requestedPath = requestedEnvFile ? path.resolve(cwd, requestedEnvFile) : null;
     if (!requestedPath && hasExplicitCoreRuntimeEnv(targetEnv)) {
-        lastCliEnvInfo = { ...EMPTY_INFO };
+        lastCliEnvInfo = { ...EMPTY_INFO, source: "process-env" };
         return lastCliEnvInfo;
     }
-    const candidatePath = requestedPath ?? findNearestEnvFile(cwd);
+    const nearestPath = requestedPath ? null : findNearestEnvFile(cwd);
+    const globalConfig = requestedPath || nearestPath ? null : readGlobalConfig(targetEnv);
+    const defaultPath = globalConfig ? path.resolve(globalConfig.defaultEnvFile) : null;
+    const candidatePath = requestedPath ?? nearestPath ?? defaultPath;
+    const source = requestedPath
+        ? "explicit-env-file"
+        : nearestPath
+            ? "nearest-env-file"
+            : defaultPath
+                ? "global-default-env-file"
+                : "none";
     if (!candidatePath) {
-        lastCliEnvInfo = { ...EMPTY_INFO, requestedPath };
+        lastCliEnvInfo = {
+            ...EMPTY_INFO,
+            requestedPath,
+            source,
+            globalConfigPath: globalConfig?.configPath ?? null,
+            defaultPath,
+        };
         return lastCliEnvInfo;
     }
     if (!pathExistsSync(candidatePath)) {
         lastCliEnvInfo = {
             requestedPath: candidatePath,
             loadedPath: null,
-            autoDiscovered: false,
+            autoDiscovered: source === "nearest-env-file",
             missingRequestedPath: requestedPath !== null,
+            missingDefaultPath: requestedPath === null && source === "global-default-env-file",
+            source,
+            globalConfigPath: globalConfig?.configPath ?? null,
+            defaultPath,
             loadedKeys: [],
         };
         return lastCliEnvInfo;
@@ -118,8 +143,12 @@ export function applyCliEnvironment(targetEnv = process.env, cwd = process.cwd()
     lastCliEnvInfo = {
         requestedPath,
         loadedPath: candidatePath,
-        autoDiscovered: requestedPath === null,
+        autoDiscovered: source === "nearest-env-file",
         missingRequestedPath: false,
+        missingDefaultPath: false,
+        source,
+        globalConfigPath: globalConfig?.configPath ?? null,
+        defaultPath,
         loadedKeys,
     };
     return lastCliEnvInfo;

package/dist/core/global-config.js

@@ -0,0 +1,61 @@
+import os from "node:os";
+import path from "node:path";
+import { AppError } from "../utils/errors.js";
+import { ensureDirSync, pathExistsSync, readTextFileSync, writeTextFileSync } from "../utils/fs.js";
+export const GLOBAL_CONFIG_DIRNAME = "tiangong-wiki";
+export const GLOBAL_CONFIG_FILENAME = "config.json";
+function resolveConfigBaseDir(env = process.env) {
+    const xdgConfigHome = env.XDG_CONFIG_HOME?.trim();
+    if (xdgConfigHome) {
+        return path.resolve(xdgConfigHome);
+    }
+    const homeDir = env.HOME?.trim() || os.homedir();
+    return path.join(homeDir, ".config");
+}
+export function resolveGlobalConfigPath(env = process.env) {
+    return path.join(resolveConfigBaseDir(env), GLOBAL_CONFIG_DIRNAME, GLOBAL_CONFIG_FILENAME);
+}
+export function readGlobalConfig(env = process.env) {
+    const configPath = resolveGlobalConfigPath(env);
+    if (!pathExistsSync(configPath)) {
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(readTextFileSync(configPath));
+    }
+    catch (error) {
+        throw new AppError(`Failed to parse global CLI config JSON: ${configPath}`, "config", {
+            cause: error instanceof Error ? error.message : String(error),
+        });
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new AppError(`Global CLI config must be an object: ${configPath}`, "config");
+    }
+    const schemaVersion = parsed.schemaVersion;
+    if (!Number.isInteger(schemaVersion) || Number(schemaVersion) < 1) {
+        throw new AppError(`Global CLI config schemaVersion must be a positive integer: ${configPath}`, "config");
+    }
+    const defaultEnvFile = parsed.defaultEnvFile;
+    if (typeof defaultEnvFile !== "string" || defaultEnvFile.trim().length === 0) {
+        throw new AppError(`Global CLI config defaultEnvFile must be a non-empty string: ${configPath}`, "config");
+    }
+    return {
+        configPath,
+        defaultEnvFile: path.resolve(defaultEnvFile),
+    };
+}
+export function writeGlobalConfig(defaultEnvFile, env = process.env) {
+    const configPath = resolveGlobalConfigPath(env);
+    const normalizedEnvFile = path.resolve(defaultEnvFile);
+    const payload = {
+        schemaVersion: 1,
+        defaultEnvFile: normalizedEnvFile,
+    };
+    ensureDirSync(path.dirname(configPath));
+    writeTextFileSync(configPath, `${JSON.stringify(payload, null, 2)}\n`);
+    return {
+        configPath,
+        defaultEnvFile: normalizedEnvFile,
+    };
+}

package/dist/core/onboarding.js

@@ -5,6 +5,7 @@ import { confirm, input, password, select } from "@inquirer/prompts";
 import { DEFAULT_WIKI_ENV_FILE, getCliEnvironmentInfo, parseEnvFile, serializeEnvEntries } from "./cli-env.js";
 import { resolveTemplateFilePath, loadConfig } from "./config.js";
 import { EmbeddingClient } from "./embedding.js";
+import { writeGlobalConfig } from "./global-config.js";
 import { parseVaultHashMode, resolveAgentSettings } from "./paths.js";
 import { loadSynologyConfigFromEnv, normalizeSynologyRemotePath, withSynologyClient } from "./synology.js";
 import { ensureWikiSkillInstall, formatParserSkills, inspectSkillInstall, installParserSkill, OPTIONAL_PARSER_SKILLS, parseParserSkillSelection, parseParserSkills, resolveWorkspaceRootFromWikiPath, resolveWorkspaceSkillPath, resolveWorkspaceSkillPaths, } from "./workspace-skills.js";
@@ -672,9 +673,11 @@ export async function runSetupWizard(env = process.env, options = {}) {
             output,
         }));
         writeSetupEnvFile(values);
+        const globalConfig = writeGlobalConfig(values.envFilePath, env);
         output.write([
             "\ntiangong-wiki setup complete",
             `configuration file: ${values.envFilePath}`,
+            `default workspace config: ${globalConfig.configPath}`,
             `workspace root: ${workspaceRoot}`,
             `skills root: ${skillsRoot}`,
             `tiangong-wiki-skill: ${wikiSkillInstall.status}`,
@@ -687,8 +690,10 @@ export async function runSetupWizard(env = process.env, options = {}) {
                 : []),
             "",
             "Next steps:",
-            `- Run subsequent commands from the workspace root that contains .wiki.env: ${workspaceRoot}`,
+            `- Commands inside ${JSON.stringify(workspaceRoot)} will auto-discover the local .wiki.env first.`,
+            `- Commands outside the workspace will fall back to the default workspace config at ${globalConfig.configPath}.`,
             `- Example: cd ${JSON.stringify(workspaceRoot)} && tiangong-wiki doctor`,
+            `- Example: tiangong-wiki --env-file ${JSON.stringify(values.envFilePath)} doctor`,
             `- Example: cd ${JSON.stringify(workspaceRoot)} && tiangong-wiki init`,
             "- Run `tiangong-wiki doctor` to validate the generated configuration.",
             "- Run `tiangong-wiki init` to create index.db and perform the first sync.",
@@ -701,6 +706,7 @@ export async function runSetupWizard(env = process.env, options = {}) {
         ].join("\n"));
         return {
             envFilePath: values.envFilePath,
+            globalConfigPath: globalConfig.configPath,
             createdDirectories: bootstrap.createdDirectories,
             copiedConfig: bootstrap.copiedConfig,
             copiedTemplates: bootstrap.copiedTemplates,
@@ -1017,11 +1023,26 @@ export async function buildDoctorReport(env = process.env, options = {}) {
     if (envFile.missingRequestedPath && envFile.requestedPath) {
         collectDoctorCheck(checks, "error", "env-file", `Requested env file does not exist: ${envFile.requestedPath}`, "Create the env file or rerun `tiangong-wiki setup`.");
     }
+    else if (envFile.missingDefaultPath && envFile.defaultPath) {
+        collectDoctorCheck(checks, "error", "env-file", `The default workspace config points to a missing env file: ${envFile.defaultPath}`, envFile.globalConfigPath
+            ? `Fix or remove ${envFile.globalConfigPath}, rerun \`tiangong-wiki setup\`, or pass \`--env-file\` explicitly.`
+            : "Fix the default workspace config, rerun `tiangong-wiki setup`, or pass `--env-file` explicitly.");
+    }
     else if (envFile.loadedPath) {
-        collectDoctorCheck(checks, "ok", "env-file", `Loaded configuration from ${envFile.loadedPath}${envFile.autoDiscovered ? " (auto-discovered)." : "."}`);
+        const sourceLabel = envFile.source === "explicit-env-file"
+            ? "from --env-file or WIKI_ENV_FILE."
+            : envFile.source === "nearest-env-file"
+                ? "from the current workspace (auto-discovered)."
+                : envFile.source === "global-default-env-file"
+                    ? "from the global default workspace config."
+                    : ".";
+        collectDoctorCheck(checks, "ok", "env-file", `Loaded configuration from ${envFile.loadedPath} ${sourceLabel}`);
+    }
+    else if (envFile.source === "process-env") {
+        collectDoctorCheck(checks, "ok", "env-file", "Using runtime paths provided directly via process.env; no .wiki.env file was loaded.");
     }
     else {
-        collectDoctorCheck(checks, "warn", "env-file", "No .wiki.env file was loaded; using process.env only.", "Run `tiangong-wiki setup` to generate a portable `.wiki.env` file.");
+        collectDoctorCheck(checks, "warn", "env-file", "No workspace configuration was found from --env-file, WIKI_ENV_FILE, the current directory, or the global default workspace config.", "Run `tiangong-wiki setup`, set `WIKI_ENV_FILE`, or pass `--env-file` to point at a workspace explicitly.");
     }
     const wikiPath = env.WIKI_PATH ? path.resolve(env.WIKI_PATH) : null;
     const wikiRoot = wikiPath ? path.resolve(wikiPath, "..") : null;
@@ -1055,6 +1076,10 @@ export async function buildDoctorReport(env = process.env, options = {}) {
             loadedPath: envFile.loadedPath,
             autoDiscovered: envFile.autoDiscovered,
             missingRequestedPath: envFile.missingRequestedPath,
+            missingDefaultPath: envFile.missingDefaultPath,
+            source: envFile.source,
+            globalConfigPath: envFile.globalConfigPath,
+            defaultPath: envFile.defaultPath,
         },
         effectivePaths: {
             wikiPath,

package/dist/index.js

@@ -29,12 +29,39 @@ import { loadRuntimeConfig } from "./core/runtime.js";
 import { embedPendingPages } from "./core/sync.js";
 import { processVaultQueueBatch } from "./core/vault-processing.js";
 import { handleCliError, writeJson } from "./utils/output.js";
+function extractEnvFileOption(argv) {
+    const nextArgv = argv.slice(0, 2);
+    let envFile = null;
+    for (let index = 2; index < argv.length; index += 1) {
+        const arg = argv[index];
+        if (arg === "--env-file") {
+            const value = argv[index + 1];
+            if (!value || value.startsWith("-")) {
+                throw new Error("--env-file requires a value");
+            }
+            envFile = value;
+            index += 1;
+            continue;
+        }
+        if (arg.startsWith("--env-file=")) {
+            const value = arg.slice("--env-file=".length);
+            if (!value) {
+                throw new Error("--env-file requires a value");
+            }
+            envFile = value;
+            continue;
+        }
+        nextArgv.push(arg);
+    }
+    return { envFile, argv: nextArgv };
+}
 function buildProgram() {
     const program = new Command();
     program
         .name("tiangong-wiki")
         .description("Tiangong Wiki — local-first indexing and query CLI")
         .version(packageJson.version)
+        .option("--env-file <path>", "Load runtime environment from a specific .wiki.env file")
         .showHelpAfterError();
     let runtimeConfig;
     try {
@@ -81,9 +108,13 @@ function buildProgram() {
     return program;
 }
 try {
+    const { envFile, argv } = extractEnvFileOption(process.argv);
+    if (envFile) {
+        process.env.WIKI_ENV_FILE = envFile;
+    }
     applyCliEnvironment(process.env, process.cwd());
     const program = buildProgram();
-    await program.parseAsync(process.argv);
+    await program.parseAsync(argv);
 }
 catch (error) {
     handleCliError(error);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@biaoo/tiangong-wiki",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Local-first wiki index and query engine for Markdown knowledge pages (Tiangong Wiki).",
   "type": "module",
   "publishConfig": {

package/references/cli-interface.md

@@ -13,6 +13,13 @@ npx @biaoo/tiangong-wiki <command> [options]
 npm run dev -- <command> [options]
 ```
 
+Global workspace resolution priority:
+
+1. `--env-file <path>`
+2. `WIKI_ENV_FILE`
+3. nearest `.wiki.env` found by walking upward from the current directory
+4. the global default workspace config written by `tiangong-wiki setup`
+
 ---
 
 ## Command Overview
@@ -57,6 +64,7 @@ Interactive step-by-step wizard that:
 - Records `WIKI_PATH`, `VAULT_PATH`, `WIKI_DB_PATH`, `WIKI_CONFIG_PATH`, `WIKI_TEMPLATES_PATH`
 - Optionally configures `EMBEDDING_*` and Synology vault settings
 - Writes `.wiki.env` in the current working directory
+- Writes a global default workspace config pointing to that `.wiki.env`
 - Scaffolds `wiki/pages/`, `vault/`, `wiki.config.json`, and `templates/`
 
 After setup, run `tiangong-wiki doctor` then `tiangong-wiki init` to complete initialization.
@@ -64,11 +72,12 @@ After setup, run `tiangong-wiki doctor` then `tiangong-wiki init` to complete in
 ### doctor
 
 ```
-tiangong-wiki doctor [--probe] [--format text|json]
+tiangong-wiki doctor [--env-file <path>] [--probe] [--format text|json]
 ```
 
 | Option | Description |
 | --- | --- |
+| `--env-file` | Load a specific `.wiki.env` before running the command |
 | `--probe` | Additionally test remote services (embedding endpoint, Synology NAS) |
 | `--format` | Output format: `text` (default) or `json` |