@itradingai/aiwiki 0.2.14 → 0.2.16

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 { lintWorkspace, renderLintReport, writeLintReport } from "./lint.js";
+import { filterLintReport, lintWorkspace, 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 }) {
@@ -159,10 +159,16 @@ export async function runCli(argv, streams = { stdout: process.stdout, stderr: p
         }
         if (command === "lint") {
             const root = await resolveWorkspace(flagString(args, "path"));
-            const report = await lintWorkspace(root);
-            const reportPath = await writeLintReport(root, report);
+            const severity = parseLintSeverity(flagString(args, "severity"));
+            const report = filterLintReport(await lintWorkspace(root), severity);
+            if (flagBool(args, "json")) {
+                writeLine(streams.stdout, JSON.stringify(report, null, 2));
+                return 0;
+            }
+            const reportPath = flagBool(args, "no-write") ? undefined : await writeLintReport(root, report);
+            writeLine(streams.stdout, renderLintSummary(report, reportPath));
+            writeLine(streams.stdout, "");
             writeLine(streams.stdout, renderLintReport(report));
-            writeLine(streams.stdout, `report: ${reportPath}`);
             return 0;
         }
         if (command === "ingest-agent") {
@@ -256,6 +262,15 @@ function printHelp(stream) {
     writeLine(stream, "  aiwiki ingest-url <url> --content-file <file>");
     writeLine(stream, "  aiwiki agent check");
 }
+function parseLintSeverity(value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (value === "error" || value === "warning" || value === "info") {
+        return value;
+    }
+    throw new CliError("lint --severity must be error, warning, or info");
+}
 async function discoverAgentTargets() {
     const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
     const skillSource = path.join(packageRoot, "skill", "SKILL.md");
@@ -430,18 +445,29 @@ function printAgentPrompt(stream) {
 }
 async function printStatusDetails(stream, root, runCount) {
     const counts = await contentCounts(root);
+    const summary = await statusSummary(root);
     const lintPath = path.join(root, "dashboards", "Lint Report.md");
     writeLine(stream, "");
-    writeLine(stream, "内容统计:");
-    writeLine(stream, `Wiki 条目: ${counts.wikiEntries}`);
-    writeLine(stream, `资料卡: ${counts.sourceCards}`);
-    writeLine(stream, `原文: ${counts.rawFiles}`);
-    writeLine(stream, `选题: ${counts.topics}`);
-    writeLine(stream, `大纲: ${counts.outlines}`);
-    writeLine(stream, `最近 lint: ${await exists(lintPath) ? await relativeMtime(root, lintPath) : "无"}`);
+    writeLine(stream, "Content stats:");
+    writeLine(stream, `Wiki entries: ${counts.wikiEntries}`);
+    writeLine(stream, `Source cards: ${counts.sourceCards}`);
+    writeLine(stream, `Raw files: ${counts.rawFiles}`);
+    writeLine(stream, `Topics: ${counts.topics}`);
+    writeLine(stream, `Outlines: ${counts.outlines}`);
+    writeLine(stream, `fallback_entries: ${summary.fallbackCount}`);
+    writeLine(stream, `grounding_review_entries: ${summary.groundingReviewCount}`);
+    writeLine(stream, `recent_lint: ${await exists(lintPath) ? await relativeMtime(root, lintPath) : "none"}`);
+    writeLine(stream, `lint_status: ${summary.lintStatus}`);
+    if (summary.lastSuccessRunId) {
+        writeLine(stream, `last_success: ${summary.lastSuccessRunId}`);
+    }
+    if (summary.lastFailureRunId) {
+        writeLine(stream, `last_failure: ${summary.lastFailureRunId}`);
+    }
+    writeLine(stream, `system_files: ${summary.systemFiles.map((item) => `${item.path}=${item.status}`).join(", ")}`);
     writeLine(stream, "");
-    writeLine(stream, "下一步建议:");
-    writeLine(stream, runCount === 0 ? "运行 `aiwiki agent install` 接入宿主 Agent，然后发送 `入库 <url>`。" : "运行 `aiwiki query <主题>` 查询知识，或运行 `aiwiki lint` 检查结构。");
+    writeLine(stream, "Next action:");
+    writeLine(stream, recommendedNextAction(runCount, summary.lintStatus, summary.systemFiles.some((item) => item.status !== "ok")));
 }
 async function printNext(stream, root, runCount, checks, targets, report) {
     const missing = checks.filter((check) => check.status !== "ok");
@@ -452,42 +478,67 @@ async function printNext(stream, root, runCount, checks, targets, report) {
         }
     }
     writeLine(stream, "AIWiki 下一步建议");
-    writeLine(stream, `知识库路径: ${root}`);
+    writeLine(stream, `workspace: ${root}`);
     if (missing.length) {
         writeLine(stream, "");
-        writeLine(stream, "先修复知识库结构:");
+        writeLine(stream, "Repair workspace structure first:");
         writeLine(stream, `- aiwiki setup --path "${root}" --yes`);
+        writeLine(stream, "- repair_order: structure");
         return;
     }
-    if (runCount === 0) {
+    const actionableIssues = report?.issues.filter((issue) => issue.severity !== "info") ?? [];
+    const errorCount = actionableIssues.filter((issue) => issue.severity === "error").length;
+    const warningCount = actionableIssues.filter((issue) => issue.severity === "warning").length;
+    if (errorCount > 0) {
         writeLine(stream, "");
-        writeLine(stream, "还没有入库记录。");
-        writeLine(stream, "- aiwiki agent install");
-        writeLine(stream, "- 然后向宿主 Agent 发送 `入库 <url>`");
-        writeLine(stream, "- CLI 不抓网页；网页正文由宿主 Agent 提供。");
+        writeLine(stream, `结构检查发现 ${errorCount} 个 error 问题。`);
+        writeLine(stream, "- aiwiki lint");
+        writeLine(stream, "- report: dashboards/Lint Report.md");
+        writeLine(stream, "- repair_order: lint_errors");
         return;
     }
-    const actionableIssues = report?.issues.filter((issue) => issue.severity !== "info") ?? [];
-    if (actionableIssues.length) {
+    if (warningCount > 0) {
         writeLine(stream, "");
-        writeLine(stream, `结构检查发现 ${actionableIssues.length} 个需要处理的问题。`);
+        writeLine(stream, `结构检查发现 ${warningCount} 个 warning 问题。`);
         writeLine(stream, "- aiwiki lint");
-        writeLine(stream, `- 查看报告: dashboards/Lint Report.md`);
-        writeLine(stream, "- 先处理 error / warning，再继续扩展查询或入库。");
+        writeLine(stream, "- report: dashboards/Lint Report.md");
+        writeLine(stream, "- repair_order: lint_warnings");
+        return;
+    }
+    if (runCount === 0) {
+        writeLine(stream, "");
+        writeLine(stream, "No ingest records yet.");
+        writeLine(stream, "- aiwiki agent install");
+        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");
         return;
     }
     writeLine(stream, "");
-    writeLine(stream, "已有入库记录，可以继续：");
-    writeLine(stream, "- aiwiki query <主题>");
+    writeLine(stream, "Workspace is healthy enough for retrieval:");
+    writeLine(stream, "- aiwiki query <topic>");
     writeLine(stream, "- aiwiki lint");
+    writeLine(stream, "- repair_order: healthy_query");
     if (installableMissing.length) {
         writeLine(stream, "");
-        writeLine(stream, "可补充宿主 Agent 接入:");
+        writeLine(stream, "Optional host Agent setup:");
         for (const target of installableMissing) {
             writeLine(stream, `- aiwiki agent install --agent ${target.id} --yes`);
         }
     }
 }
+function recommendedNextAction(runCount, lintStatus, hasMissingSystemFiles) {
+    if (hasMissingSystemFiles) {
+        return "next_action: aiwiki setup --path <workspace> --yes";
+    }
+    if (lintStatus === "needs_attention") {
+        return "next_action: aiwiki lint";
+    }
+    if (runCount === 0) {
+        return "next_action: aiwiki agent install";
+    }
+    return "next_action: aiwiki query <topic>";
+}
 function renderQuery(context) {
     const lines = [`AIWiki 查询: ${context.query}`, ""];
     appendQueryGroup(lines, "Wiki 条目", context.matches.wiki_entries);

package/dist/src/lint.js

@@ -19,14 +19,17 @@ export async function lintWorkspace(rootPath, now = new Date().toISOString()) {
         ...await readNotes(root, "08-outputs/outlines")
     ];
     const issues = [];
+    issues.push(...await systemFileIssues(root));
     const wikiSourceCards = new Set(wikiEntries.map((note) => frontmatterString(note.frontmatter, "source_card")).filter(Boolean));
     for (const card of sourceCards) {
         if (!wikiSourceCards.has(card.path)) {
             issues.push({
                 severity: "warning",
                 path: card.path,
-                message: "Source Card 没有对应 Wiki Entry。",
-                suggestion: `重新入库或生成 05-wiki/source-knowledge/${path.basename(card.path)}`
+                category: "isolated_source_card",
+                action: "reingest",
+                message: "Source Card has no matching Wiki Entry.",
+                suggestion: `Reingest or create a matching 05-wiki/source-knowledge/${path.basename(card.path)} entry.`
             });
         }
     }
@@ -35,26 +38,68 @@ export async function lintWorkspace(rootPath, now = new Date().toISOString()) {
         const rawFile = frontmatterString(entry.frontmatter, "raw_file");
         const mode = frontmatterString(entry.frontmatter, "generation_mode");
         if (!sourceCard) {
-            issues.push({ severity: "warning", path: entry.path, message: "Wiki Entry 缺少 source_card。", suggestion: "补写 source_card vault 路径。" });
+            issues.push({
+                severity: "warning",
+                path: entry.path,
+                category: "missing_source",
+                action: "reingest",
+                message: "Wiki Entry is missing source_card.",
+                suggestion: "Add the vault path of the source card."
+            });
         }
         if (!rawFile) {
-            issues.push({ severity: "warning", path: entry.path, message: "Wiki Entry 缺少 raw_file。", suggestion: "补写 raw_file vault 路径。" });
+            issues.push({
+                severity: "warning",
+                path: entry.path,
+                category: "missing_source",
+                action: "reingest",
+                message: "Wiki Entry is missing raw_file.",
+                suggestion: "Add the vault path of the raw source file."
+            });
         }
         if (mode === "deterministic_fallback") {
-            issues.push({ severity: "info", path: entry.path, message: "Wiki Entry 是 deterministic fallback，仅包含来源和正文预览。", suggestion: "让宿主 Agent 基于原文补充 analysis 或 wiki_entry。" });
+            issues.push({
+                severity: "info",
+                path: entry.path,
+                category: "stale_scaffold",
+                action: "enrich",
+                message: "Wiki Entry is a deterministic fallback and only contains source trace plus a content preview.",
+                suggestion: "Ask the host Agent to enrich it with analysis or a full wiki_entry."
+            });
             const createdAt = Date.parse(frontmatterString(entry.frontmatter, "created_at") ?? "");
             if (Number.isFinite(createdAt) && Date.parse(now) - createdAt > 7 * 24 * 60 * 60 * 1000) {
-                issues.push({ severity: "warning", path: entry.path, message: "fallback Wiki Entry 超过 7 天未补全。", suggestion: "重新运行宿主 Agent 生成 enriched Wiki Entry。" });
+                issues.push({
+                    severity: "warning",
+                    path: entry.path,
+                    category: "stale_scaffold",
+                    action: "enrich",
+                    message: "Fallback Wiki Entry is older than 7 days.",
+                    suggestion: "Reingest with a host Agent to generate an enriched Wiki Entry."
+                });
             }
         }
         if (mode === "agent_enriched") {
-            const hasSummary = /## 一句话总结/.test(entry.body) || Boolean(frontmatterString(entry.frontmatter, "summary"));
-            const hasKeyPoints = /## 核心观点[\s\S]*-\s+/.test(entry.body);
+            const hasSummary = /##\s+.+/.test(entry.body) || Boolean(frontmatterString(entry.frontmatter, "summary"));
+            const hasKeyPoints = /-\s+/.test(entry.body);
             if (!hasSummary) {
-                issues.push({ severity: "warning", path: entry.path, message: "agent_enriched Wiki Entry 缺少 summary。", suggestion: "让宿主 Agent 提供 analysis.summary。" });
+                issues.push({
+                    severity: "warning",
+                    path: entry.path,
+                    category: "weak_entry",
+                    action: "enrich",
+                    message: "agent_enriched Wiki Entry is missing a summary.",
+                    suggestion: "Ask the host Agent to provide analysis.summary."
+                });
             }
             if (!hasKeyPoints) {
-                issues.push({ severity: "warning", path: entry.path, message: "agent_enriched Wiki Entry 缺少 key_points。", suggestion: "让宿主 Agent 提供 analysis.key_points。" });
+                issues.push({
+                    severity: "warning",
+                    path: entry.path,
+                    category: "weak_entry",
+                    action: "enrich",
+                    message: "agent_enriched Wiki Entry is missing key points.",
+                    suggestion: "Ask the host Agent to provide analysis.key_points."
+                });
             }
         }
         if (frontmatterBoolean(entry.frontmatter, "grounding_needs_review") === true) {
@@ -62,15 +107,24 @@ export async function lintWorkspace(rootPath, now = new Date().toISOString()) {
             issues.push({
                 severity: "warning",
                 path: entry.path,
-                message: `Wiki Entry 需要 grounding 复核${markers.length ? `: ${markers.join(", ")}` : "。"}`,
-                suggestion: "检查 source_quote 是否能在 Raw 中找到；coverage_suspected_incomplete 仅代表启发式疑似风险。"
+                category: "grounding_review",
+                action: "mark_reviewed",
+                message: `Wiki Entry needs grounding review${markers.length ? `: ${markers.join(", ")}` : "."}`,
+                suggestion: "Check whether source quotes are present in Raw. Heuristic coverage risks are not confirmed facts."
             });
         }
         if (frontmatterBoolean(entry.frontmatter, "represents_user_view") === true && frontmatterString(entry.frontmatter, "source_role") !== "output") {
-            issues.push({ severity: "warning", path: entry.path, message: "只有 output 角色应标记为代表用户观点。", suggestion: "将 represents_user_view 改为 false，或将 source_role 改为 output。" });
+            issues.push({
+                severity: "warning",
+                path: entry.path,
+                category: "metadata_boundary",
+                action: "mark_reviewed",
+                message: "Only output source_role entries should represent the user's view.",
+                suggestion: "Set represents_user_view to false, or change source_role to output when it is user-authored output."
+            });
         }
     }
-    issues.push(...duplicateIssues(sourceCards, "source_url", "重复 URL"));
+    issues.push(...duplicateIssues(sourceCards, "source_url", "Duplicate URL"));
     issues.push(...duplicateTitles(allNotes));
     issues.push(...brokenLinkIssues(root, allNotes));
     return {
@@ -84,6 +138,15 @@ export async function lintWorkspace(rootPath, now = new Date().toISOString()) {
         issues
     };
 }
+export function filterLintReport(report, severity) {
+    if (!severity) {
+        return report;
+    }
+    return {
+        ...report,
+        issues: report.issues.filter((issue) => issue.severity === severity)
+    };
+}
 export async function writeLintReport(rootPath, report) {
     const root = path.resolve(rootPath);
     const target = safeJoin(root, "dashboards", "Lint Report.md");
@@ -92,6 +155,8 @@ export async function writeLintReport(rootPath, report) {
     return relativePath(root, target);
 }
 export function renderLintReport(report) {
+    const counts = severityCounts(report.issues);
+    const topIssue = report.issues[0];
     return [
         "# AIWiki Lint Report",
         "",
@@ -103,17 +168,49 @@ export function renderLintReport(report) {
         `- Source Cards: ${report.summary.source_cards}`,
         `- Raw Files: ${report.summary.raw_files}`,
         `- Runs: ${report.summary.runs}`,
+        `- Errors: ${counts.error}`,
+        `- Warnings: ${counts.warning}`,
+        `- Info: ${counts.info}`,
+        `- Top Issue: ${topIssue ? formatIssueLine(topIssue) : "none"}`,
         "",
-        "## Issues",
+        "## Suggested Handling Order",
         "",
-        ...(report.issues.length ? report.issues.map((issue) => {
-            const suffix = issue.path ? ` (${issue.path})` : "";
-            const suggestion = issue.suggestion ? `\n  - Suggested Fix: ${issue.suggestion}` : "";
-            return `- [${issue.severity}] ${issue.message}${suffix}${suggestion}`;
-        }) : ["- none"]),
+        "- Fix error issues first.",
+        "- Review warning issues next.",
+        "- Use info issues for enrichment and cleanup backlog.",
+        "",
+        ...renderIssueGroup("Errors", report.issues.filter((issue) => issue.severity === "error")),
+        ...renderIssueGroup("Warnings", report.issues.filter((issue) => issue.severity === "warning")),
+        ...renderIssueGroup("Info", report.issues.filter((issue) => issue.severity === "info")),
         ""
     ].join("\n");
 }
+export function renderLintSummary(report, reportPath) {
+    const counts = severityCounts(report.issues);
+    const topIssue = report.issues[0];
+    return [
+        `lint_summary: errors=${counts.error} warnings=${counts.warning} info=${counts.info}`,
+        `top_issue: ${topIssue ? formatIssueLine(topIssue) : "none"}`,
+        ...(reportPath ? [`report: ${reportPath}`] : [])
+    ].join("\n");
+}
+async function systemFileIssues(root) {
+    const issues = [];
+    for (const systemFile of ["_system/purpose.md", "_system/index.md", "_system/log.md"]) {
+        if (await exists(path.join(root, systemFile))) {
+            continue;
+        }
+        issues.push({
+            severity: "error",
+            path: systemFile,
+            category: "workspace_structure",
+            action: "repair_structure",
+            message: `Required system file is missing: ${systemFile}`,
+            suggestion: `Run aiwiki setup --path "${root}" --yes`
+        });
+    }
+    return issues;
+}
 async function readNotes(root, dir) {
     const absolute = path.join(root, dir);
     if (!(await exists(absolute))) {
@@ -163,7 +260,13 @@ function duplicateIssues(notes, field, label) {
         seen.set(value, [...(seen.get(value) ?? []), note.path]);
     }
     return Array.from(seen.entries()).flatMap(([value, paths]) => paths.length > 1
-        ? [{ severity: "warning", message: `${label}: ${value}`, suggestion: paths.join(", ") }]
+        ? [{
+                severity: "warning",
+                category: "duplicate",
+                action: "mark_reviewed",
+                message: `${label}: ${value}`,
+                suggestion: paths.join(", ")
+            }]
         : []);
 }
 function duplicateTitles(notes) {
@@ -175,7 +278,13 @@ function duplicateTitles(notes) {
         seen.set(note.title, [...(seen.get(note.title) ?? []), note.path]);
     }
     return Array.from(seen.entries()).flatMap(([title, paths]) => paths.length > 1
-        ? [{ severity: "info", message: `重复标题: ${title}`, suggestion: paths.join(", ") }]
+        ? [{
+                severity: "info",
+                category: "duplicate_title",
+                action: "archive",
+                message: `Duplicate title: ${title}`,
+                suggestion: paths.join(", ")
+            }]
         : []);
 }
 function brokenLinkIssues(root, notes) {
@@ -185,12 +294,43 @@ function brokenLinkIssues(root, notes) {
         for (const link of note.body.matchAll(/\[\[([^\]|]+)(?:\|[^\]]+)?\]\]/g)) {
             const target = link[1].replace(/\\/g, "/").replace(/\.md$/i, "");
             if (!existing.has(target) && !isRunLocalLink(target)) {
-                issues.push({ severity: "error", path: note.path, message: `内部链接断裂: ${target}`, suggestion: "检查目标文件是否存在或更新 wikilink。" });
+                issues.push({
+                    severity: "error",
+                    path: note.path,
+                    category: "broken_link",
+                    action: "fix_link",
+                    message: `Broken wikilink: ${target}`,
+                    suggestion: "Check whether the target file exists or update the wikilink."
+                });
             }
         }
     }
     return issues;
 }
+function renderIssueGroup(title, issues) {
+    return [
+        `## ${title}`,
+        "",
+        ...(issues.length ? issues.map((issue) => {
+            const suggestion = issue.suggestion ? `\n  - Suggested Fix: ${issue.suggestion}` : "";
+            const action = issue.action ? `\n  - Action: ${issue.action}` : "";
+            return `- ${formatIssueLine(issue)}${action}${suggestion}`;
+        }) : ["- none"]),
+        ""
+    ];
+}
+function formatIssueLine(issue) {
+    const suffix = issue.path ? ` (${issue.path})` : "";
+    const category = issue.category ? ` {${issue.category}}` : "";
+    return `[${issue.severity}]${category} ${issue.message}${suffix}`;
+}
+function severityCounts(issues) {
+    return {
+        error: issues.filter((issue) => issue.severity === "error").length,
+        warning: issues.filter((issue) => issue.severity === "warning").length,
+        info: issues.filter((issue) => issue.severity === "info").length
+    };
+}
 function isRunLocalLink(target) {
     // Run-local notes are valid trace links but are not part of the long-term note set.
     return target.startsWith("09-runs/");

package/dist/src/workspace.js

@@ -3,7 +3,9 @@ import os from "node:os";
 import path from "node:path";
 import { createInterface } from "node:readline/promises";
 import { stdin as input, stdout as output } from "node:process";
+import { frontmatterBoolean, frontmatterString, parseMarkdown } from "./frontmatter.js";
 import { CliError } from "./output.js";
+import { relativePath } from "./paths.js";
 export const CONFIG_FILE = "aiwiki.yaml";
 export const REQUIRED_DIRS = [
     "02-raw/articles",
@@ -551,6 +553,14 @@ export async function doctor(rootPath) {
             detail: absolute
         });
     }
+    for (const file of REQUIRED_FILES) {
+        const absolute = path.join(root, file);
+        checks.push({
+            name: file,
+            status: (await exists(absolute)) ? "ok" : "missing",
+            detail: absolute
+        });
+    }
     const writeTarget = path.join(root, "_system", "logs", ".doctor-write-test");
     try {
         await fs.writeFile(writeTarget, "ok", "utf8");
@@ -566,7 +576,16 @@ export async function statusSummary(rootPath) {
     const root = resolveRoot(rootPath);
     const runsRoot = path.join(root, "09-runs");
     if (!(await exists(runsRoot))) {
-        return { root, runCount: 0, failedCount: 0 };
+        return {
+            root,
+            runCount: 0,
+            failedCount: 0,
+            fallbackCount: await countWikiEntries(root, "deterministic_fallback"),
+            groundingReviewCount: await countGroundingReviewEntries(root),
+            lintStatus: await readLintStatus(root),
+            lintReportPath: await lintReportPath(root),
+            systemFiles: await systemFileSummary(root)
+        };
     }
     const entries = await fs.readdir(runsRoot, { withFileTypes: true });
     const dirs = entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name);
@@ -590,11 +609,20 @@ export async function statusSummary(rootPath) {
         stats.push({ dir, mtimeMs: (await fs.stat(path.join(runsRoot, dir))).mtimeMs });
     }
     stats.sort((a, b) => b.mtimeMs - a.mtimeMs);
+    const successDirs = dirs.filter((dir) => !dir.endsWith("-fetch-failed"));
+    const failureDirs = dirs.filter((dir) => dir.endsWith("-fetch-failed"));
     return {
         root,
         runCount: dirs.length,
         failedCount,
-        lastRunId: stats[0]?.dir
+        lastRunId: stats[0]?.dir,
+        lastSuccessRunId: await newestDir(root, successDirs),
+        lastFailureRunId: await newestDir(root, failureDirs),
+        fallbackCount: await countWikiEntries(root, "deterministic_fallback"),
+        groundingReviewCount: await countGroundingReviewEntries(root),
+        lintStatus: await readLintStatus(root),
+        lintReportPath: await lintReportPath(root),
+        systemFiles: await systemFileSummary(root)
     };
 }
 export async function exists(target) {
@@ -613,3 +641,73 @@ function readScalar(text, key) {
 function unquote(value) {
     return value.replace(/^["']|["']$/g, "");
 }
+const REQUIRED_FILES = ["_system/purpose.md", "_system/index.md", "_system/log.md"];
+async function systemFileSummary(root) {
+    const files = [];
+    for (const file of REQUIRED_FILES) {
+        files.push({ path: file, status: await exists(path.join(root, file)) ? "ok" : "missing" });
+    }
+    return files;
+}
+async function newestDir(root, dirs) {
+    const stats = [];
+    for (const dir of dirs) {
+        stats.push({ dir, mtimeMs: (await fs.stat(path.join(root, "09-runs", dir))).mtimeMs });
+    }
+    stats.sort((a, b) => b.mtimeMs - a.mtimeMs);
+    return stats[0]?.dir;
+}
+async function countWikiEntries(root, generationMode) {
+    const files = await markdownFiles(path.join(root, "05-wiki", "source-knowledge"));
+    let count = 0;
+    for (const file of files) {
+        const parsed = parseMarkdown(await fs.readFile(file, "utf8"));
+        if (frontmatterString(parsed.frontmatter, "generation_mode") === generationMode) {
+            count += 1;
+        }
+    }
+    return count;
+}
+async function countGroundingReviewEntries(root) {
+    const files = await markdownFiles(path.join(root, "05-wiki", "source-knowledge"));
+    let count = 0;
+    for (const file of files) {
+        const parsed = parseMarkdown(await fs.readFile(file, "utf8"));
+        if (frontmatterBoolean(parsed.frontmatter, "grounding_needs_review") === true) {
+            count += 1;
+        }
+    }
+    return count;
+}
+async function readLintStatus(root) {
+    const reportPath = await lintReportPath(root);
+    if (!reportPath) {
+        return "missing";
+    }
+    const text = await fs.readFile(path.join(root, reportPath), "utf8");
+    if (/\[(error|warning)\]/.test(text)) {
+        return "needs_attention";
+    }
+    return "ok";
+}
+async function lintReportPath(root) {
+    const absolute = path.join(root, "dashboards", "Lint Report.md");
+    return await exists(absolute) ? relativePath(root, absolute) : undefined;
+}
+async function markdownFiles(dir) {
+    if (!(await exists(dir))) {
+        return [];
+    }
+    const entries = await fs.readdir(dir, { withFileTypes: true });
+    const files = [];
+    for (const entry of entries) {
+        const target = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            files.push(...await markdownFiles(target));
+        }
+        else if (entry.isFile() && entry.name.toLowerCase().endsWith(".md")) {
+            files.push(target);
+        }
+    }
+    return files;
+}

package/docs/AGENT_HANDOFF.md

@@ -199,6 +199,28 @@ aiwiki query "<主题>"
 aiwiki lint
 ```
 
+需要机器读取时用：
+
+```bash
+aiwiki lint --json
+```
+
+只想看某一级别时用：
+
+```bash
+aiwiki lint --severity error
+aiwiki lint --severity warning
+aiwiki lint --severity info
+```
+
+只做临时检查、不改 dashboard 时用：
+
+```bash
+aiwiki lint --no-write
+```
+
+Lint 输出会包含摘要、最高优先级问题、分级报告，以及建议动作。把 `error` 当作必须先修的结构问题，把 `warning` 当作需要处理或复核的维护问题，把 `info` 当作富集、归档或后续整理 backlog。
+
 `context` 返回 JSON，注意其中的 `generation_mode`、`quality` 和 `warnings`。如果结果是 `deterministic_fallback` / `scaffold`，回复时要说明它只是可追溯脚手架，不是高质量知识提炼。
 
 `context` 也可能返回 grounding 字段。回复用户时可以把 `grounding_needs_review: true` 解释为“这条资料需要复核证据或覆盖度”，不要说成“AIWiki 已确认漏掉重点”。

package/docs/README.md

@@ -9,6 +9,7 @@ AIWiki 是一个 Agent-first 的本地知识库工具，用来把宿主 Agent
 - 示例展示：[SHOWCASE.md](SHOWCASE.md)
 - 常见问题：[FAQ.md](FAQ.md)
 - 路线图：[ROADMAP.md](ROADMAP.md)
+- 开发记录：[development-log.md](development-log.md)
 
 ## Quick Start
 

package/docs/USAGE.md

@@ -318,13 +318,23 @@ aiwiki query "AI Agent"
 aiwiki lint
 ```
 
+常用工作台模式：
+
+```bash
+aiwiki lint --severity warning
+aiwiki lint --json
+aiwiki lint --no-write
+```
+
+`lint` 会先输出 `lint_summary`、`top_issue` 和报告路径，再按 Errors / Warnings / Info 分组展示问题。每个问题会尽量给出建议动作，例如 `enrich`、`fix_link`、`reingest`、`archive` 或 `mark_reviewed`。`--severity` 只查看指定级别，`--json` 给宿主 Agent 使用，`--no-write` 只在终端检查而不更新 `dashboards/Lint Report.md`。
+
 查看下一步建议：
 
 ```bash
 aiwiki next
 ```
 
-`lint` 输出报告并写入 `dashboards/Lint Report.md`。
+默认情况下，`lint` 输出报告并写入 `dashboards/Lint Report.md`。
 
 ## 8. 高级调试
 
@@ -410,3 +420,17 @@ aiwiki status
 # System Purpose Files
 
 `aiwiki setup` now also seeds `_system/purpose.md`, `_system/index.md`, and `_system/log.md` when they are missing. These files give humans and host Agents a stable entry point for the knowledge-base goal, scope, common folders, common commands, and lightweight event notes. Re-running setup preserves user edits.
+
+## Diagnostic Commands
+
+`aiwiki doctor` checks the workspace directories, write permission, and required system files: `_system/purpose.md`, `_system/index.md`, and `_system/log.md`.
+
+`aiwiki status` keeps the existing run-count summary and also reports:
+
+- `fallback_entries`: Wiki entries generated as deterministic fallback/scaffold.
+- `grounding_review_entries`: Wiki entries marked for grounding review.
+- `lint_status`: whether a lint report is missing, clean, or needs attention.
+- `system_files`: readiness of purpose, index, and log files.
+- `next_action`: the recommended next command.
+
+`aiwiki next` uses the same repair order: fix workspace structure first, then lint errors, lint warnings, empty-workspace onboarding, and finally healthy-state query guidance.

package/docs/development-log.md

@@ -0,0 +1,97 @@
+# AIWiki Development Log
+
+This log records queue-driven AIWiki development milestones that should remain visible to future maintainers, not only in automation chat history.
+
+## 2026-06-05 - AIWIKI-004 lint workbench
+
+Status: implemented, locally verified, pushed to GitHub, blocked on npm OTP before publication.
+
+Version target: `@itradingai/aiwiki@0.2.16`
+
+Commit: `932386c` (`Turn lint into an actionable maintenance workbench`)
+
+### Goal
+
+Turn `aiwiki lint` from a plain report writer into a practical structure-maintenance workbench for humans and host Agents.
+
+The scoped acceptance criteria were:
+
+- summarize lint output in the terminal with errors, warnings, info, top issue, and report path;
+- group the markdown report by severity and provide a handling order;
+- support `--severity error|warning|info`;
+- support `--json` for machine-readable Agent use;
+- support `--no-write` for temporary checks that do not update `dashboards/Lint Report.md`;
+- add lightweight knowledge-gap signals where feasible;
+- attach advisory review actions such as `enrich`, `fix_link`, `archive`, `reingest`, and `mark_reviewed`.
+
+### Implemented
+
+- `src/lint.ts`
+  - Added `LintSeverity` and advisory `LintAction`.
+  - Added issue `category` and `action` fields.
+  - Added system-file checks for `_system/purpose.md`, `_system/index.md`, and `_system/log.md`.
+  - Added signals for isolated Source Cards, stale deterministic fallback entries, grounding-review entries, metadata-boundary issues, duplicate URLs/titles, and broken wikilinks.
+  - Added severity filtering, terminal summary rendering, and severity-grouped report rendering.
+
+- `src/app.ts`
+  - Added `aiwiki lint --severity error|warning|info`.
+  - Added `aiwiki lint --json`.
+  - Added `aiwiki lint --no-write`.
+  - Kept the default behavior of writing `dashboards/Lint Report.md`.
+
+- `tests/cli.test.ts` and `tests/ingest.test.ts`
+  - Covered lint summary output, severity filtering, JSON output, no-write behavior, and updated lint issue text assertions.
+
+- `docs/USAGE.md` and `docs/AGENT_HANDOFF.md`
+  - Documented human and Agent-facing lint modes.
+
+### Verification
+
+- `npm test`: passed, 53 tests.
+- `npm run release:check`: passed, including 53 tests and release-check.
+- `npm pack --dry-run`: passed for `@itradingai/aiwiki@0.2.16`.
+- Clean export pack from `C:/tmp/aiwiki-004-publish`: passed, 31 files, shasum `945c70d3d4cf20c9550deaaf92036786b75e62cf`.
+
+### Release State
+
+GitHub push succeeded:
+
+```text
+2e4b253..932386c main -> main
+```
+
+npm publication is blocked by a one-time password challenge:
+
+```text
+npm error code EOTP
+npm error This operation requires a one-time password from your authenticator.
+```
+
+Current registry version remains `0.2.15`, so remote smoke tests for `0.2.16` have not run yet.
+
+### Resume Steps
+
+From the clean publish directory:
+
+```powershell
+cd C:\tmp\aiwiki-004-publish
+npm publish --access public --otp=<code>
+npm view @itradingai/aiwiki version
+```
+
+After `npm view` returns `0.2.16`, run remote smoke tests for:
+
+```bash
+aiwiki lint --path <tmp-vault>
+aiwiki lint --severity warning --path <tmp-vault>
+aiwiki lint --json --path <tmp-vault>
+aiwiki lint --no-write --path <tmp-vault>
+```
+
+Then update the queue through `published`, `remote_verified`, and `done`.
+
+### Notes For Future Changes
+
+- Lint actions are advisory only. Do not make `archive`, `reingest`, `mark_reviewed`, or related actions mutate files without a separate explicit task.
+- Keep lint local-file-only. Do not add crawling, vector search, RAG-over-wiki, RBAC, RSS, scheduled collection, or browser plugins under this queue item.
+- The original working tree had unrelated `skill/SKILL.md` changes. Publication must use a clean commit export until that WIP is resolved.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@itradingai/aiwiki",
-  "version": "0.2.14",
+  "version": "0.2.16",
   "type": "module",
   "description": "Agent-first AI knowledge base CLI for turning articles, links and notes into Obsidian-ready source cards, topics, outlines and reusable knowledge assets.",
   "license": "MIT",