@itradingai/aiwiki 0.2.15 → 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");

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/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. 高级调试
 

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.15",
+  "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",