@itradingai/aiwiki 0.2.16 → 0.2.19

package/README.md

@@ -23,7 +23,7 @@ AIWiki 是一个开源的 Agent-first 本地 LLM-wiki CLI。
 用户给 URL / 正文 / 文件
   -> 宿主 Agent 读取内容并尽量生成 analysis / wiki_entry
   -> aiwiki ingest-agent --stdin
-  -> AIWiki 写入 Raw / Source Card / Wiki Entry / Claim / Topic / Outline / Run Log
+  -> AIWiki 写入 Raw / Source Card / Wiki Entry / Run Summary；有明确内容或请求时再写 Claim / Topic / Outline / Asset
 ```
 
 ### Query：从 Wiki 调度知识
@@ -55,7 +55,7 @@ aiwiki lint
 我的知识库路径：F:\knowledges
 
 请检查 Node.js >=20，执行 aiwiki setup --path "我的知识库路径" --yes，
-然后运行 aiwiki agent list / aiwiki agent install 完成宿主 Agent 对接。
+然后运行 aiwiki agent sync --yes 和 aiwiki agent check --json 完成宿主 Agent 对接。
 最后执行 aiwiki doctor 和 aiwiki status，告诉我实际执行了哪些命令和还差什么手动步骤。
 ```
 
@@ -63,16 +63,15 @@ aiwiki lint
 
 ```bash
 npx @itradingai/aiwiki@latest setup
-aiwiki agent list
-aiwiki agent install
+aiwiki agent sync --yes
+aiwiki agent check --json
 ```
 
 ### 第二步：接入宿主 Agent
 
 ```bash
-aiwiki agent list
-aiwiki agent install
-aiwiki agent check
+aiwiki agent sync --yes
+aiwiki agent check --json
 ```
 
 也可以直接输出通用协议：
@@ -118,15 +117,11 @@ aiwiki query "xxx"
 ```text
 02-raw/articles/
 03-sources/article-cards/
-04-claims/_suggestions/
 05-wiki/source-knowledge/
-06-assets/_suggestions/
-07-topics/ready/
-08-outputs/outlines/
 09-runs/<run-id>/
 ```
 
-其中 `05-wiki/source-knowledge/<slug>.md` 是默认 Wiki Entry。
+其中 `02-raw/articles/`、`03-sources/article-cards/`、`05-wiki/source-knowledge/` 和 `09-runs/<run-id>/` 是核心产物。`04-claims/_suggestions/`、`06-assets/_suggestions/`、`07-topics/ready/`、`08-outputs/outlines/` 只在 payload 有对应内容或 `request.outputs` 明确请求时生成。
 
 ### Agent-Enriched Wiki Entry
 
@@ -247,3 +242,37 @@ aiwiki lint --path "F:\knowledge_data\aiwiki-test"
 ## License
 
 MIT. See [LICENSE](LICENSE).
+
+## Query Filters
+
+AIWiki retrieval is local Markdown/frontmatter search. It is intentionally lightweight: no vector search, no database, no external search, and no RAG-over-wiki.
+
+```bash
+aiwiki context "AI Agent" --type wiki_entries --source-role input --wiki-type source_knowledge --status active --limit 5
+aiwiki query "AI Agent" --type source_cards --status to-review --limit 3
+```
+
+`context` returns Agent-readable JSON with `query_scope`, `result_quality`, `recommended_next_action`, `match_reasons`, `quality_signals`, and `related_refs`. `query` uses the same retrieval path and shows the match reasons and quality hints for humans.
+
+## Agent Skill Sync and Upgrade
+
+AIWiki is Agent-first: after installing or upgrading the npm package, sync the packaged AIWiki skill into the local Agent environment.
+
+First install and later upgrades use the same safe command:
+
+```bash
+npm install -g @itradingai/aiwiki@latest
+aiwiki agent sync --yes
+aiwiki agent check
+```
+
+For one Agent:
+
+```bash
+aiwiki agent sync --agent codex --yes
+aiwiki agent sync --agent claude --yes
+```
+
+`agent sync` is idempotent. Missing targets are installed, current targets are left unchanged, and changed old skill files are backed up before overwrite. Use `--dry-run` to preview and `--json` when an AI Agent needs stable machine-readable status.
+
+After sync, restart or reload the target Agent so it reads the new AIWiki skill. To roll back, copy the generated `.bak-<timestamp>` file back over the target skill file.

package/dist/src/app.js

@@ -6,7 +6,7 @@ import { fileURLToPath } from "node:url";
 import { flagBool, flagString, parseArgs } from "./args.js";
 import { buildContext } from "./context.js";
 import { deriveFileTitle, ingestFile, ingestPayload } from "./ingest.js";
-import { filterLintReport, lintWorkspace, renderLintReport, renderLintSummary, writeLintReport } from "./lint.js";
+import { attachAppliedSafeFixes, filterLintReport, lintWorkspace, removeEmptyOptionalDirs, renderLintReport, renderLintSummary, writeLintReport } from "./lint.js";
 import { CliError, writeLine } from "./output.js";
 import { confirmInit, directorySummary, doctor, exists, initWorkspace, promptForSetup, promptForInitPath, readConfig, resolveWorkspace, setDefaultWorkspace, statusSummary } from "./workspace.js";
 export async function runCli(argv, streams = { stdout: process.stdout, stderr: process.stderr }) {
@@ -17,6 +17,14 @@ export async function runCli(argv, streams = { stdout: process.stdout, stderr: p
             writeLine(streams.stdout, `aiwiki ${await packageVersion()}`);
             return 0;
         }
+        if (command === "agent" && (subcommand === "help" || args.flags.has("help"))) {
+            printAgentHelp(streams.stdout);
+            return 0;
+        }
+        if ((command === "context" || command === "query") && args.flags.has("help")) {
+            printContextHelp(streams.stdout);
+            return 0;
+        }
         if (args.flags.has("help") || !command || command === "help" || command === "-h") {
             printHelp(streams.stdout);
             return 0;
@@ -36,8 +44,8 @@ export async function runCli(argv, streams = { stdout: process.stdout, stderr: p
             writeLine(streams.stdout, `默认知识库: ${defaultConfig.defaultPath}`);
             writeLine(streams.stdout, `用户配置: ${defaultConfig.configPath}`);
             writeLine(streams.stdout, "Obsidian 入口: dashboards/AIWiki Home.md");
-            writeLine(streams.stdout, "下一步: 运行 `aiwiki agent install`，把 AIWiki 安装到宿主 Agent。");
-            writeLine(streams.stdout, "Agent 设置完成后: 向 Agent 发送 `入库 <url>`");
+            writeLine(streams.stdout, "下一步: 运行 `aiwiki agent sync --yes`，同步 AIWiki 宿主 Agent 对接文件。");
+            writeLine(streams.stdout, "Agent 设置完成后: 让宿主 Agent 提供正文并调用 `aiwiki ingest-agent --stdin`，或运行 `aiwiki ingest-file --file <file>`。");
             return 0;
         }
         if (command === "agent" && subcommand === "install") {
@@ -54,8 +62,24 @@ export async function runCli(argv, streams = { stdout: process.stdout, stderr: p
             }
             return 0;
         }
+        if (command === "agent" && subcommand === "sync") {
+            const result = await syncAgentSkills({
+                agentId: flagString(args, "agent"),
+                yes: flagBool(args, "yes"),
+                dryRun: flagBool(args, "dry-run"),
+                json: flagBool(args, "json"),
+                streams
+            });
+            if (flagBool(args, "json")) {
+                writeLine(streams.stdout, JSON.stringify(result, null, 2));
+            }
+            else {
+                printAgentSyncResult(streams.stdout, result);
+            }
+            return 0;
+        }
         if (command === "agent" && subcommand === "check") {
-            await printAgentCheck(streams.stdout, await discoverAgentTargets());
+            await printAgentCheckDetailed(streams.stdout, await discoverAgentTargets(), flagBool(args, "json"));
             return 0;
         }
         if (command === "agent" && (subcommand === "list" || !subcommand)) {
@@ -137,7 +161,7 @@ export async function runCli(argv, streams = { stdout: process.stdout, stderr: p
             if (!query) {
                 throw new CliError("请提供查询主题。");
             }
-            writeLine(streams.stdout, JSON.stringify(await buildContext(root, query), null, 2));
+            writeLine(streams.stdout, JSON.stringify(await buildContext(root, query, contextOptions(args)), null, 2));
             return 0;
         }
         if (command === "query") {
@@ -146,7 +170,7 @@ export async function runCli(argv, streams = { stdout: process.stdout, stderr: p
             if (!query) {
                 throw new CliError("请提供查询主题。");
             }
-            writeLine(streams.stdout, renderQuery(await buildContext(root, query)));
+            writeLine(streams.stdout, renderQuery(await buildContext(root, query, contextOptions(args))));
             return 0;
         }
         if (command === "next") {
@@ -160,7 +184,8 @@ export async function runCli(argv, streams = { stdout: process.stdout, stderr: p
         if (command === "lint") {
             const root = await resolveWorkspace(flagString(args, "path"));
             const severity = parseLintSeverity(flagString(args, "severity"));
-            const report = filterLintReport(await lintWorkspace(root), severity);
+            const appliedSafeFixes = flagBool(args, "fix-empty-dirs") ? await removeEmptyOptionalDirs(root) : [];
+            const report = filterLintReport(attachAppliedSafeFixes(await lintWorkspace(root), appliedSafeFixes), severity);
             if (flagBool(args, "json")) {
                 writeLine(streams.stdout, JSON.stringify(report, null, 2));
                 return 0;
@@ -244,23 +269,51 @@ function printHelp(stream) {
     writeLine(stream, "用法:");
     writeLine(stream, "  aiwiki setup");
     writeLine(stream, "  aiwiki setup --path <path> --yes");
-    writeLine(stream, "  aiwiki agent list");
-    writeLine(stream, "  aiwiki agent install");
-    writeLine(stream, "  aiwiki agent install --agent codex --yes");
-    writeLine(stream, "  aiwiki prompt agent");
+    writeLine(stream, "  aiwiki agent sync --yes");
+    writeLine(stream, "  aiwiki agent check --json");
+    writeLine(stream, "  aiwiki ingest-agent --stdin");
+    writeLine(stream, "  aiwiki ingest-file --file <file>");
     writeLine(stream, "  aiwiki doctor");
     writeLine(stream, "  aiwiki status");
     writeLine(stream, "  aiwiki context <query>");
     writeLine(stream, "  aiwiki query <query>");
-    writeLine(stream, "  aiwiki next");
     writeLine(stream, "  aiwiki lint");
-    writeLine(stream, "  aiwiki ingest-agent --stdin");
-    writeLine(stream, "  aiwiki ingest-file --file <file>");
-    writeLine(stream, "  aiwiki init --path <path> --yes --set-default");
-    writeLine(stream, "  aiwiki config show");
-    writeLine(stream, "  aiwiki ingest-agent --payload <file>");
-    writeLine(stream, "  aiwiki ingest-url <url> --content-file <file>");
+    writeLine(stream, "  aiwiki lint --fix-empty-dirs --json");
+}
+function printAgentHelp(stream) {
+    writeLine(stream, "AIWiki Agent commands");
+    writeLine(stream, "");
+    writeLine(stream, "Agent-first setup and upgrade:");
+    writeLine(stream, "  aiwiki agent sync --yes");
+    writeLine(stream, "  aiwiki agent sync --agent codex --yes");
+    writeLine(stream, "  aiwiki agent sync --agent codex --dry-run");
+    writeLine(stream, "  aiwiki agent sync --json --yes");
+    writeLine(stream, "");
+    writeLine(stream, "Status:");
     writeLine(stream, "  aiwiki agent check");
+    writeLine(stream, "  aiwiki agent check --json");
+    writeLine(stream, "");
+    writeLine(stream, "Compatibility:");
+    writeLine(stream, "  aiwiki agent install --agent codex --yes");
+    writeLine(stream, "  aiwiki agent install --agent codex --yes --force");
+    writeLine(stream, "");
+    writeLine(stream, "sync is idempotent: missing targets are installed, current targets are left unchanged, and different targets are backed up before overwrite.");
+}
+function printContextHelp(stream) {
+    writeLine(stream, "AIWiki context/query");
+    writeLine(stream, "");
+    writeLine(stream, "Local Markdown/frontmatter retrieval for host Agents and humans:");
+    writeLine(stream, "  aiwiki context <topic> --limit 10");
+    writeLine(stream, "  aiwiki query <topic> --type wiki_entries --status active");
+    writeLine(stream, "");
+    writeLine(stream, "Filters:");
+    writeLine(stream, "  --type wiki_entries|source_cards|claims|topics|outlines|raw_refs");
+    writeLine(stream, "  --source-role input|processing|output");
+    writeLine(stream, "  --wiki-type source_knowledge|personal_knowledge");
+    writeLine(stream, "  --status active|to-review|ready|draft");
+    writeLine(stream, "  --limit <1-50>");
+    writeLine(stream, "");
+    writeLine(stream, "context JSON includes query_scope, result_quality, recommended_next_action, match_reasons, quality_signals, and related_refs.");
 }
 function parseLintSeverity(value) {
     if (value === undefined) {
@@ -362,6 +415,40 @@ async function printAgentCheck(stream, targets) {
         }
     }
 }
+async function printAgentCheckDetailed(stream, targets, json = false) {
+    const checked = await Promise.all(targets.map(async (target) => ({
+        ...target,
+        state: await inspectAgentTarget(target),
+        installed: target.target ? await exists(target.target) : false
+    })));
+    if (json) {
+        writeLine(stream, JSON.stringify({
+            schema_version: "aiwiki.agent_check.v1",
+            generated_at: new Date().toISOString(),
+            targets: checked.map((target) => ({
+                id: target.id,
+                name: target.name,
+                detected: target.detected,
+                installable: target.installable,
+                installed: target.installed,
+                state: target.state,
+                source: target.source,
+                target: target.target
+            }))
+        }, null, 2));
+        return;
+    }
+    writeLine(stream, "AIWiki Agent check");
+    for (const target of checked) {
+        writeLine(stream, `${target.id}: ${target.name} | detected=${target.detected ? "yes" : "no"} | installed=${target.installed ? "yes" : "no"} | installable=${target.installable ? "yes" : "no"} | state=${target.state}`);
+        if (target.detected && target.installable && (target.state === "missing" || target.state === "different")) {
+            writeLine(stream, `  suggested: aiwiki agent sync --agent ${target.id} --yes`);
+        }
+        else if (target.detected && !target.installable) {
+            writeLine(stream, "  suggested: aiwiki prompt agent");
+        }
+    }
+}
 async function installAgentSkill(options) {
     const targets = await discoverAgentTargets();
     const installable = targets.filter((target) => target.detected && target.installable);
@@ -400,8 +487,8 @@ async function installAgentSkill(options) {
             return undefined;
         }
     }
-    await copyInstallFile(selected.source, selected.target, options.force);
-    return selected;
+    const result = await copyInstallFileSafe(selected.source, selected.target, options.force);
+    return { ...selected, ...result };
 }
 async function askQuestion(streams, question) {
     if (!process.stdin.isTTY) {
@@ -415,7 +502,28 @@ async function askQuestion(streams, question) {
         rl.close();
     }
 }
+async function syncAgentSkills(options) {
+    const targets = await discoverAgentTargets();
+    const selected = options.agentId ? targets.find((target) => target.id === options.agentId) : undefined;
+    if (!selected && options.agentId) {
+        throw new CliError(`未知宿主 Agent: ${options.agentId}`);
+    }
+    const syncTargets = selected ? [selected] : targets.filter((target) => target.detected && target.installable);
+    if (!syncTargets.length) {
+        throw new CliError("No detected installable Agent targets. Run aiwiki agent list or aiwiki prompt agent.");
+    }
+    if (!options.yes && !options.dryRun) {
+        throw new CliError("agent sync modifies Agent skill files. Re-run with --yes, or use --dry-run to preview.");
+    }
+    return {
+        schema_version: "aiwiki.agent_sync.v1",
+        generated_at: new Date().toISOString(),
+        dry_run: options.dryRun,
+        results: await Promise.all(syncTargets.map((target) => syncAgentTarget(target, options.dryRun)))
+    };
+}
 async function copyInstallFile(source, target, force) {
+    return copyInstallFileSafe(source, target, force);
     await fs.access(source);
     if (!force && (await exists(target))) {
         throw new CliError(`目标文件已存在: ${target}。如需覆盖，请加 --force。`);
@@ -423,6 +531,84 @@ async function copyInstallFile(source, target, force) {
     await fs.mkdir(path.dirname(target), { recursive: true });
     await fs.copyFile(source, target);
 }
+async function copyInstallFileSafe(source, target, force) {
+    await fs.access(source);
+    const targetExists = await exists(target);
+    if (!force && targetExists) {
+        throw new CliError(`目标文件已存在: ${target}。如需覆盖，请运行 aiwiki agent sync --agent <id> --yes，或为 install 加 --force。`);
+    }
+    if (targetExists && await sameFileContent(source, target)) {
+        return { action: "current" };
+    }
+    await fs.mkdir(path.dirname(target), { recursive: true });
+    const backupPath = targetExists ? await backupFile(target) : undefined;
+    await fs.copyFile(source, target);
+    return { action: targetExists ? "updated" : "installed", backupPath };
+}
+async function inspectAgentTarget(target) {
+    if (!target.installable || !target.source || !target.target) {
+        return "unsupported";
+    }
+    if (!(await exists(target.target))) {
+        return "missing";
+    }
+    return await sameFileContent(target.source, target.target) ? "current" : "different";
+}
+async function syncAgentTarget(target, dryRun) {
+    const state = await inspectAgentTarget(target);
+    const base = {
+        id: target.id,
+        name: target.name,
+        detected: target.detected,
+        installable: target.installable,
+        state,
+        target: target.target,
+        source: target.source,
+        changed: false,
+        dryRun
+    };
+    if (state === "unsupported" || !target.source || !target.target) {
+        return { ...base, action: "unsupported", note: target.note };
+    }
+    if (state === "current") {
+        return { ...base, action: "current" };
+    }
+    if (dryRun) {
+        return { ...base, action: state === "missing" ? "would_install" : "would_update", changed: true };
+    }
+    const result = await copyInstallFileSafe(target.source, target.target, true);
+    return { ...base, action: result.action, backupPath: result.backupPath, changed: result.action !== "current" };
+}
+async function sameFileContent(source, target) {
+    try {
+        const [sourceText, targetText] = await Promise.all([fs.readFile(source, "utf8"), fs.readFile(target, "utf8")]);
+        return sourceText === targetText;
+    }
+    catch {
+        return false;
+    }
+}
+async function backupFile(target) {
+    const parsed = path.parse(target);
+    const stamp = new Date().toISOString().replace(/[-:]/g, "").replace(/\.\d{3}Z$/, "Z");
+    const backupPath = path.join(parsed.dir, `${parsed.base}.bak-${stamp}`);
+    await fs.copyFile(target, backupPath);
+    return backupPath;
+}
+function printAgentSyncResult(stream, report) {
+    writeLine(stream, "AIWiki Agent sync");
+    writeLine(stream, `dry_run: ${report.dry_run ? "yes" : "no"}`);
+    for (const item of report.results) {
+        writeLine(stream, `${item.id}: ${item.name} | state=${item.state} | action=${item.action} | changed=${item.changed ? "yes" : "no"}`);
+        if (item.target) {
+            writeLine(stream, `  target: ${item.target}`);
+        }
+        if (item.backupPath) {
+            writeLine(stream, `  backup: ${item.backupPath}`);
+        }
+    }
+    writeLine(stream, "next: restart or reload the target Agent so it reads the synced AIWiki skill.");
+}
 function printAgentPrompt(stream) {
     writeLine(stream, "AIWiki Agent 中文提示");
     writeLine(stream, "");
@@ -439,7 +625,7 @@ function printAgentPrompt(stream) {
     writeLine(stream, "回复措辞：成功时说“AIWiki 已完成入库，并生成 Wiki 条目。” 如果 wiki_entry_quality=scaffold，说明该条目只是可追溯脚手架，仍需宿主 Agent 后续补全。Dataview 是可选增强，不要替用户安装插件或修改 .obsidian。");
     writeLine(stream, "");
     writeLine(stream, "查询：当用户要求从 AIWiki 里了解某个主题时，调用 `aiwiki context <主题>`。");
-    writeLine(stream, "整理：当用户要求检查或整理知识库时，调用 `aiwiki lint`。");
+    writeLine(stream, "整理：当用户要求检查或整理知识库时，先调用 `aiwiki lint --json`；若只有 safe fix 且用户允许整理，再调用 `aiwiki lint --fix-empty-dirs --json`，随后重跑 `aiwiki lint --json`。");
     writeLine(stream, "");
     writeLine(stream, "禁止：让用户保存 payload；让用户每次输入 --path；声称 AIWiki CLI 负责网页抓取；声称 AIWiki CLI 会在没有 Agent 分析字段时自动高质量总结。");
 }
@@ -508,7 +694,7 @@ async function printNext(stream, root, runCount, checks, targets, report) {
     if (runCount === 0) {
         writeLine(stream, "");
         writeLine(stream, "No ingest records yet.");
-        writeLine(stream, "- aiwiki agent install");
+        writeLine(stream, "- aiwiki agent sync --yes");
         writeLine(stream, "- Then ask the host Agent to ingest a URL.");
         writeLine(stream, "- AIWiki CLI does not fetch webpages; the host Agent supplies content.");
         writeLine(stream, "- repair_order: empty_workspace");
@@ -535,12 +721,25 @@ function recommendedNextAction(runCount, lintStatus, hasMissingSystemFiles) {
         return "next_action: aiwiki lint";
     }
     if (runCount === 0) {
-        return "next_action: aiwiki agent install";
+        return "next_action: aiwiki agent sync --yes";
     }
     return "next_action: aiwiki query <topic>";
 }
+function contextOptions(args) {
+    const limit = flagString(args, "limit");
+    return {
+        filters: {
+            type: flagString(args, "type"),
+            source_role: flagString(args, "source-role"),
+            wiki_type: flagString(args, "wiki-type"),
+            status: flagString(args, "status")
+        },
+        limit: limit === undefined ? undefined : Number(limit)
+    };
+}
 function renderQuery(context) {
     const lines = [`AIWiki 查询: ${context.query}`, ""];
+    lines.push(`结果质量: matches=${context.result_quality.total_matches}, best_score=${context.result_quality.best_score}, has_wiki_entry=${context.result_quality.has_wiki_entry ? "yes" : "no"}`, `下一步建议: ${context.recommended_next_action}`, `查询范围: groups=${context.query_scope.searched_groups.join(",") || "none"}, limit=${context.query_scope.limit}, filters=${JSON.stringify(context.query_scope.filters)}`, "");
     appendQueryGroup(lines, "Wiki 条目", context.matches.wiki_entries);
     appendQueryGroup(lines, "资料卡", context.matches.source_cards);
     appendQueryGroup(lines, "选题", context.matches.topics);
@@ -561,9 +760,13 @@ function appendQueryGroup(lines, label, items) {
     }
     for (const item of items.slice(0, 5)) {
         lines.push(`- ${item.title} (${item.path})`);
+        lines.push(`  score=${item.score}; reasons=${item.match_reasons.join(",") || "unknown"}; quality=${item.quality_signals.join(",") || "none"}`);
         if (item.summary) {
             lines.push(`  ${item.summary}`);
         }
+        if (item.related_refs.length) {
+            lines.push(`  related: ${item.related_refs.slice(0, 5).join("; ")}`);
+        }
         if (item.warnings.length) {
             lines.push(`  提示: ${item.warnings.join("；")}`);
         }