@itradingai/aiwiki 0.2.15 → 0.2.18

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 已确认漏掉重点”。
@@ -225,3 +247,57 @@ aiwiki lint
 Before ingesting, querying, or reorganizing material, read `_system/purpose.md` in the target AIWiki workspace. Treat it as the local contract for what belongs in this knowledge base, what should stay out, and how future multi-knowledge-base routing should be handled.
 
 If the material does not fit the purpose file, do not force it into the knowledge base as confirmed knowledge. Record the mismatch, ask for review when needed, or keep it as a traceable source rather than a claim.
+
+## Context JSON for Retrieval
+
+When answering from AIWiki, prefer:
+
+```bash
+aiwiki context "<topic>" --limit 10
+```
+
+Use filters when the user intent is narrow:
+
+```bash
+aiwiki context "<topic>" --type wiki_entries --source-role input --wiki-type source_knowledge --status active
+aiwiki context "<topic>" --type source_cards --status to-review
+```
+
+`context` is local Markdown/frontmatter retrieval only. Do not describe it as vector search, RAG, a database query, or external web search.
+
+Read these fields before responding:
+
+- `query_scope`: what was searched and which filters were applied.
+- `result_quality.total_matches` and `result_quality.has_wiki_entry`: whether the answer is grounded in a Wiki Entry or only in supporting artifacts.
+- `recommended_next_action`: whether to answer, enrich, review grounding, or broaden the query.
+- `match_reasons`: why each result matched, such as title, body, tags, topics, relationships, or source URL.
+- `quality_signals`: scaffold, enriched, status, grounding, and relationship hints.
+- `related_refs`: local wikilinks and frontmatter relationships such as `source_card`, `raw_file`, and run artifacts.
+
+If `quality_signals` contains `quality:scaffold` or `grounding:needs_review`, tell the user the result is a traceable lead that needs enrichment or review. Do not present it as confirmed final knowledge.
+
+## Agent Skill Upgrade Flow
+
+When the user asks you to install, update, upgrade, or repair AIWiki integration, run:
+
+```bash
+aiwiki agent sync --yes
+aiwiki agent check
+```
+
+Use JSON when you need exact state:
+
+```bash
+aiwiki agent sync --json --yes
+aiwiki agent check --json
+```
+
+Interpret sync results:
+
+- `installed`: target did not exist and now has the packaged skill.
+- `current`: installed skill already matches the packaged skill.
+- `updated`: installed skill differed; the old file was backed up and replaced.
+- `would_install` / `would_update`: dry-run preview only.
+- `unsupported`: no safe automatic target is known; use `aiwiki prompt agent`.
+
+After sync, report the target path, backup path when present, and that the user may need to restart or reload the Agent. Do not claim the new skill is active until the Agent has reloaded it.