@itradingai/aiwiki 0.2.20 → 0.2.21

package/README.md

@@ -64,7 +64,9 @@ aiwiki lint
 我的知识库路径：F:\knowledges
 
 请检查 Node.js >=20，执行 aiwiki setup --path "我的知识库路径" --yes，
-然后运行 aiwiki agent sync --yes 和 aiwiki agent check --json 完成宿主 Agent 对接。
+然后运行 aiwiki agent sync --yes、aiwiki agent check --json、
+aiwiki agent sync --path "我的知识库路径" --yes 和 aiwiki agent check --path "我的知识库路径" --json，
+完成宿主 Agent 与知识库根指导对接。
 最后执行 aiwiki doctor 和 aiwiki status，告诉我实际执行了哪些命令和还差什么手动步骤。
 ```
 
@@ -81,6 +83,8 @@ aiwiki agent check --json
 ```bash
 aiwiki agent sync --yes
 aiwiki agent check --json
+aiwiki agent sync --path "F:\knowledges" --yes
+aiwiki agent check --path "F:\knowledges" --json
 ```
 
 也可以直接输出通用协议：

package/dist/src/app.js

@@ -65,6 +65,7 @@ export async function runCli(argv, streams = { stdout: process.stdout, stderr: p
         if (command === "agent" && subcommand === "sync") {
             const result = await syncAgentSkills({
                 agentId: flagString(args, "agent"),
+                workspaceRoot: flagString(args, "path"),
                 yes: flagBool(args, "yes"),
                 dryRun: flagBool(args, "dry-run"),
                 json: flagBool(args, "json"),
@@ -79,7 +80,7 @@ export async function runCli(argv, streams = { stdout: process.stdout, stderr: p
             return 0;
         }
         if (command === "agent" && subcommand === "check") {
-            await printAgentCheckDetailed(streams.stdout, await discoverAgentTargets(), flagBool(args, "json"));
+            await printAgentCheckDetailed(streams.stdout, await discoverAgentTargets(flagString(args, "path")), flagBool(args, "json"));
             return 0;
         }
         if (command === "agent" && (subcommand === "list" || !subcommand)) {
@@ -287,10 +288,12 @@ function printAgentHelp(stream) {
     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 --path <workspace> --yes");
     writeLine(stream, "  aiwiki agent sync --json --yes");
     writeLine(stream, "");
     writeLine(stream, "Status:");
     writeLine(stream, "  aiwiki agent check");
+    writeLine(stream, "  aiwiki agent check --path <workspace> --json");
     writeLine(stream, "  aiwiki agent check --json");
     writeLine(stream, "");
     writeLine(stream, "Compatibility:");
@@ -324,7 +327,21 @@ function parseLintSeverity(value) {
     }
     throw new CliError("lint --severity must be error, warning, or info");
 }
-async function discoverAgentTargets() {
+const AIWIKI_AGENT_GUIDANCE_START = "<!-- AIWIKI:AGENT-GUIDANCE:START -->";
+const AIWIKI_AGENT_GUIDANCE_END = "<!-- AIWIKI:AGENT-GUIDANCE:END -->";
+const REQUIRED_AGENT_GUIDANCE_TERMS = [
+    "aiwiki setup",
+    "aiwiki agent sync",
+    "aiwiki agent check",
+    "aiwiki lint --json",
+    "aiwiki lint --fix-empty-dirs --json",
+    "aiwiki ingest-file",
+    "aiwiki ingest-agent",
+    "aiwiki status",
+    "aiwiki query",
+    "aiwiki context"
+];
+async function discoverAgentTargets(workspaceRoot) {
     const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
     const skillSource = path.join(packageRoot, "skill", "SKILL.md");
     const promptSource = path.join(packageRoot, "docs", "AGENT_HANDOFF.md");
@@ -334,7 +351,8 @@ async function discoverAgentTargets() {
     const claudeHome = process.env.CLAUDE_HOME ? path.resolve(process.env.CLAUDE_HOME) : path.join(os.homedir(), ".claude");
     const opencodeHome = process.env.OPENCODE_HOME ? path.resolve(process.env.OPENCODE_HOME) : path.join(os.homedir(), ".opencode");
     const hermesHome = process.env.HERMES_HOME ? path.resolve(process.env.HERMES_HOME) : path.join(process.env.LOCALAPPDATA ?? path.join(os.homedir(), "AppData", "Local"), "hermes");
-    return [
+    const workspace = workspaceRoot ? path.resolve(workspaceRoot) : undefined;
+    const targets = [
         {
             id: "codex",
             name: "Codex",
@@ -392,6 +410,18 @@ async function discoverAgentTargets() {
             note: "已检测到，但暂未确认稳定的 skill 目录。请先使用 aiwiki prompt agent。"
         }
     ];
+    if (workspace) {
+        targets.unshift({
+            id: "workspace",
+            name: "Workspace AGENTS.md",
+            detected: await exists(workspace),
+            installable: true,
+            kind: "root_guidance",
+            target: path.join(workspace, "AGENTS.md"),
+            note: "安装 marker-bounded 根指导，要求宿主 Agent 在整理、检查、入库、查询、复用时优先调用 aiwiki CLI。"
+        });
+    }
+    return targets;
 }
 function printAgentList(stream, targets) {
     writeLine(stream, "AIWiki 宿主 Agent 目标");
@@ -432,6 +462,7 @@ async function printAgentCheckDetailed(stream, targets, json = false) {
                 installable: target.installable,
                 installed: target.installed,
                 state: target.state,
+                suggested_action: suggestedAgentAction(target),
                 source: target.source,
                 target: target.target
             }))
@@ -441,14 +472,21 @@ async function printAgentCheckDetailed(stream, targets, json = false) {
     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");
+        const suggested = suggestedAgentAction(target);
+        if (suggested) {
+            writeLine(stream, `  suggested: ${suggested}`);
         }
     }
 }
+function suggestedAgentAction(target) {
+    if (target.detected && target.installable && (target.state === "missing" || target.state === "different")) {
+        return target.id === "workspace" ? `aiwiki agent sync --path "${path.dirname(target.target ?? ".")}" --yes` : `aiwiki agent sync --agent ${target.id} --yes`;
+    }
+    if (target.detected && !target.installable) {
+        return "aiwiki prompt agent";
+    }
+    return undefined;
+}
 async function installAgentSkill(options) {
     const targets = await discoverAgentTargets();
     const installable = targets.filter((target) => target.detected && target.installable);
@@ -503,7 +541,7 @@ async function askQuestion(streams, question) {
     }
 }
 async function syncAgentSkills(options) {
-    const targets = await discoverAgentTargets();
+    const targets = await discoverAgentTargets(options.workspaceRoot);
     const selected = options.agentId ? targets.find((target) => target.id === options.agentId) : undefined;
     if (!selected && options.agentId) {
         throw new CliError(`未知宿主 Agent: ${options.agentId}`);
@@ -546,6 +584,9 @@ async function copyInstallFileSafe(source, target, force) {
     return { action: targetExists ? "updated" : "installed", backupPath };
 }
 async function inspectAgentTarget(target) {
+    if (target.kind === "root_guidance") {
+        return inspectWorkspaceGuidanceTarget(target);
+    }
     if (!target.installable || !target.source || !target.target) {
         return "unsupported";
     }
@@ -567,7 +608,7 @@ async function syncAgentTarget(target, dryRun) {
         changed: false,
         dryRun
     };
-    if (state === "unsupported" || !target.source || !target.target) {
+    if (state === "unsupported" || !target.target || (!target.source && target.kind !== "root_guidance")) {
         return { ...base, action: "unsupported", note: target.note };
     }
     if (state === "current") {
@@ -576,9 +617,78 @@ async function syncAgentTarget(target, dryRun) {
     if (dryRun) {
         return { ...base, action: state === "missing" ? "would_install" : "would_update", changed: true };
     }
+    if (target.kind === "root_guidance") {
+        const result = await syncWorkspaceGuidanceTarget(target);
+        return { ...base, action: result.action, backupPath: result.backupPath, changed: result.action !== "current" };
+    }
     const result = await copyInstallFileSafe(target.source, target.target, true);
     return { ...base, action: result.action, backupPath: result.backupPath, changed: result.action !== "current" };
 }
+async function inspectWorkspaceGuidanceTarget(target) {
+    if (!target.target || !target.detected) {
+        return "missing";
+    }
+    if (!(await exists(target.target))) {
+        return "missing";
+    }
+    const content = await fs.readFile(target.target, "utf8");
+    const block = extractWorkspaceGuidanceBlock(content);
+    if (!block) {
+        return "different";
+    }
+    return block.trim() === workspaceGuidanceBlock().trim() && REQUIRED_AGENT_GUIDANCE_TERMS.every((term) => block.includes(term)) ? "current" : "different";
+}
+async function syncWorkspaceGuidanceTarget(target) {
+    if (!target.target) {
+        return { action: "unsupported" };
+    }
+    const targetExists = await exists(target.target);
+    const existing = targetExists ? await fs.readFile(target.target, "utf8") : "";
+    const next = mergeWorkspaceGuidance(existing);
+    if (targetExists && existing === next) {
+        return { action: "current" };
+    }
+    const backupPath = targetExists ? await backupFile(target.target) : undefined;
+    await fs.mkdir(path.dirname(target.target), { recursive: true });
+    await fs.writeFile(target.target, next, "utf8");
+    return { action: targetExists ? "updated" : "installed", backupPath };
+}
+function extractWorkspaceGuidanceBlock(content) {
+    const start = content.indexOf(AIWIKI_AGENT_GUIDANCE_START);
+    const end = content.indexOf(AIWIKI_AGENT_GUIDANCE_END);
+    if (start === -1 || end === -1 || end < start) {
+        return undefined;
+    }
+    return content.slice(start, end + AIWIKI_AGENT_GUIDANCE_END.length);
+}
+function mergeWorkspaceGuidance(existing) {
+    const block = workspaceGuidanceBlock();
+    const start = existing.indexOf(AIWIKI_AGENT_GUIDANCE_START);
+    const end = existing.indexOf(AIWIKI_AGENT_GUIDANCE_END);
+    if (start !== -1 && end !== -1 && end > start) {
+        return `${existing.slice(0, start)}${block}${existing.slice(end + AIWIKI_AGENT_GUIDANCE_END.length)}`;
+    }
+    const trimmed = existing.trimEnd();
+    return `${trimmed}${trimmed ? "\n\n" : ""}${block}\n`;
+}
+function workspaceGuidanceBlock() {
+    return `${AIWIKI_AGENT_GUIDANCE_START}
+# AIWiki Agent Command Contract
+
+When a user asks to organize, inspect, ingest, query, reuse, or maintain this AIWiki workspace, call the AIWiki CLI first. Do not start with generic file search, grep/find scans, or ad hoc note edits unless the AIWiki command cannot answer the request.
+
+Required command-first loop:
+
+1. Ensure the workspace exists with \`aiwiki setup --path <workspace> --yes\`.
+2. Keep host-Agent guidance current with \`aiwiki agent sync --path <workspace> --yes\` and verify with \`aiwiki agent check --path <workspace> --json\`.
+3. Inspect structure with \`aiwiki lint --json --path <workspace>\`; apply only safe fixes with \`aiwiki lint --fix-empty-dirs --json --path <workspace>\` when allowed, then rerun \`aiwiki lint --json --path <workspace>\`.
+4. Ingest local material with \`aiwiki ingest-file --file <file> --path <workspace>\` or structured Agent material with \`aiwiki ingest-agent --stdin --path <workspace>\`.
+5. Check progress with \`aiwiki status --path <workspace>\`.
+6. Retrieve reusable knowledge with \`aiwiki query <topic> --path <workspace>\` for human-readable output or \`aiwiki context <topic> --path <workspace>\` for Agent JSON.
+
+Use fallback shell/file search only after the relevant AIWiki command has been tried or when the command is unavailable. If you fall back, say which AIWiki command was insufficient and why.
+${AIWIKI_AGENT_GUIDANCE_END}`;
+}
 async function sameFileContent(source, target) {
     try {
         const [sourceText, targetText] = await Promise.all([fs.readFile(source, "utf8"), fs.readFile(target, "utf8")]);

package/docs/AGENT_HANDOFF.md

@@ -24,6 +24,32 @@ AIWiki CLI 不做通用网页抓取，也不调用 LLM。网页读取失败时
 
 证据和疑似风险要分开：`source_quote` 等能回到原文的字段是宿主提供的 evidence/provenance；`coverage_suspected_incomplete`、`unsupported_claims`、`needs_review` 是 AIWiki 的复核提示，不代表已经证明遗漏或错误。
 
+## 命令优先契约
+
+宿主 Agent 处理 AIWiki 任务时，必须先调用 AIWiki 自带命令，再考虑通用文件搜索或临时脚本。否则只是绕过了知识库能力，用户看不到 lint、status、query/context 和入库记录的价值。
+
+项目或知识库根目录先同步根指导：
+
+```bash
+aiwiki agent sync --path <workspace> --yes
+aiwiki agent check --path <workspace> --json
+```
+
+日常闭环按这个顺序执行：
+
+```bash
+aiwiki setup --path <workspace> --yes
+aiwiki lint --json --path <workspace>
+aiwiki lint --fix-empty-dirs --json --path <workspace>
+aiwiki ingest-file --file <file> --path <workspace>
+aiwiki ingest-agent --stdin --path <workspace>
+aiwiki status --path <workspace>
+aiwiki query <topic> --path <workspace>
+aiwiki context <topic> --path <workspace>
+```
+
+只有当对应 AIWiki 命令无法回答问题时，才退回到 `rg`、`find`、`grep` 或手工读取文件；退回时要说明哪个 AIWiki 命令不够用。
+
 ## 标准流程
 
 1. 读取用户给的 URL、正文、附件或消息。

package/docs/FAQ.md

@@ -55,6 +55,8 @@ AIWiki 是一个开源的 Agent-first 本地 LLM-wiki CLI。宿主 Agent 负责
 npx @itradingai/aiwiki@latest setup
 aiwiki agent sync --yes
 aiwiki agent check --json
+aiwiki agent sync --path <workspace> --yes
+aiwiki agent check --path <workspace> --json
 ```
 
 然后去看：
@@ -84,3 +86,15 @@ aiwiki lint
 ```
 
 如果只是清理旧版本留下的空可选增强目录，可以让 Agent 先运行 `aiwiki lint --json`，确认只有 safe fix 后再运行 `aiwiki lint --fix-empty-dirs --json`。
+
+## 为什么我的 Agent 还是在直接翻文件？
+
+通常是它没有加载 AIWiki skill，或者知识库根目录缺少 AIWiki 的 `AGENTS.md` 指导。先运行：
+
+```bash
+aiwiki agent sync --yes
+aiwiki agent sync --path <workspace> --yes
+aiwiki agent check --path <workspace> --json
+```
+
+之后再让 Agent 处理 AIWiki 任务。它应该优先调用 `aiwiki lint --json`、`aiwiki status`、`aiwiki query`、`aiwiki context`、`aiwiki ingest-file` 或 `aiwiki ingest-agent`。只有这些命令不够用时，才退回到通用文件搜索。

package/docs/USAGE.md

@@ -61,8 +61,12 @@ aiwiki status
 ```bash
 aiwiki agent sync --yes
 aiwiki agent check --json
+aiwiki agent sync --path <workspace> --yes
+aiwiki agent check --path <workspace> --json
 ```
 
+前两条同步本机宿主 Agent 的 skill/command，后两条在知识库根目录写入或刷新 marker-bounded `AGENTS.md` 指导。这样新的宿主 Agent 进入项目时，会先看到“必须调用 aiwiki CLI”的约束，而不是直接走默认文件搜索流程。
+
 旧的安装向导仍然兼容，但不再作为首选路径：
 
 ```bash
@@ -93,7 +97,9 @@ aiwiki prompt agent
 
 把输出内容安装成宿主 Agent 的 skill，或粘贴到宿主 Agent 的项目/会话说明里。不同 Agent 的安装入口不同，所以 AIWiki 提供自动安装向导和通用协议两条路径。
 
-`aiwiki agent check --json` 用来确认本机检测到哪些宿主 Agent、哪些已经安装 AIWiki 对接文件、哪些还需要运行 `aiwiki agent sync --agent <id> --yes`。
+`aiwiki agent check --json` 用来确认本机检测到哪些宿主 Agent、哪些已经安装 AIWiki 对接文件、哪些还需要运行 `aiwiki agent sync --agent <id> --yes`。`aiwiki agent check --path <workspace> --json` 会同时检查知识库根目录的 `AGENTS.md` 是否包含当前 AIWiki 命令优先指导，缺失或过期时会提示运行 `aiwiki agent sync --path <workspace> --yes`。
+
+如果宿主 Agent 只用 `rg`、`find`、`grep` 或手工读文件来回答 AIWiki 问题，而没有先运行 `aiwiki lint --json`、`aiwiki status`、`aiwiki query` 或 `aiwiki context`，就说明它没有真正使用 AIWiki 的知识库闭环。
 
 ## 3. 日常使用
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@itradingai/aiwiki",
-  "version": "0.2.20",
+  "version": "0.2.21",
   "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",

package/skill/SKILL.md

@@ -3,7 +3,7 @@ name: aiwiki
 description: Agent-first AIWiki workflow for turning one URL/body into local Wiki knowledge files.
 ---
 
-<!-- aiwiki-skill-version: 0.2.19 -->
+<!-- aiwiki-skill-version: 0.2.21 -->
 
 # AIWiki Skill
 
@@ -34,15 +34,42 @@ aiwiki agent sync --json --yes
 aiwiki agent check --json
 ```
 
+For a project or vault workspace, also sync root guidance so future Agents see the command contract before they inspect files:
+
+```bash
+aiwiki agent sync --path <workspace> --yes
+aiwiki agent check --path <workspace> --json
+```
+
 Sync behavior:
 
 - missing installed skill: install the packaged AIWiki skill
 - current installed skill: leave unchanged
 - different installed skill: backup the old file, then overwrite with the packaged skill
+- workspace `AGENTS.md`: append or refresh the marker-bounded AIWiki block without removing user instructions
 - unsupported host: do not write; use `aiwiki prompt agent` as a manual fallback
 
 After sync, tell the user the target path, any backup path, and that the target Agent may need to restart or reload before the new skill is active. Never edit Agent config during `npm install`; sync is the explicit safe step.
 
+## Required Command-First Loop
+
+When the user asks you to organize, inspect, ingest, query, reuse, or maintain an AIWiki workspace, run the AIWiki command surface before generic file search or ad hoc note edits:
+
+```bash
+aiwiki setup --path <workspace> --yes
+aiwiki agent sync --path <workspace> --yes
+aiwiki agent check --path <workspace> --json
+aiwiki lint --json --path <workspace>
+aiwiki lint --fix-empty-dirs --json --path <workspace>
+aiwiki ingest-file --file <file> --path <workspace>
+aiwiki ingest-agent --stdin --path <workspace>
+aiwiki status --path <workspace>
+aiwiki query <topic> --path <workspace>
+aiwiki context <topic> --path <workspace>
+```
+
+Use fallback shell/file search only after the relevant AIWiki command has been tried or when the command is unavailable. If you fall back, explain which AIWiki command was insufficient and why. If you skip the AIWiki commands entirely, the knowledge-base features are not being exercised.
+
 ## Knowledge Base Purpose
 
 Before ingesting, querying, linting, or reorganizing material, read `_system/purpose.md` in the target AIWiki workspace when it exists. Treat it as the local contract for: