@itradingai/aiwiki 0.2.5

package/dist/src/workspace.js

@@ -0,0 +1,495 @@
+import { promises as fs } from "node:fs";
+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 { CliError } from "./output.js";
+export const CONFIG_FILE = "aiwiki.yaml";
+export const REQUIRED_DIRS = [
+    "02-raw/articles",
+    "03-sources/article-cards",
+    "04-claims/_suggestions",
+    "05-wiki",
+    "06-assets/_suggestions",
+    "07-topics/ready",
+    "08-outputs/outlines",
+    "09-runs",
+    "dashboards",
+    "_system/templates",
+    "_system/schemas",
+    "_system/logs"
+];
+const WORKSPACE_SEEDS = [
+    {
+        path: "dashboards/AIWiki Home.md",
+        content: `# AIWiki 首页
+
+AIWiki 的 Obsidian 入口。Dataview 是可选增强；未安装时仍可使用下方普通链接、Properties、Backlinks 和 Graph View。
+
+## 原生链接入口
+
+- [[dashboards/Review Queue|待审队列]]
+- [[dashboards/Recent Runs|最近处理]]
+- [[dashboards/Topic Pipeline|选题管线]]
+- [[_system/schemas/aiwiki-frontmatter|字段说明]]
+
+## 最近收录
+
+\`\`\`dataview
+TABLE status, source_url, captured_at, run_summary
+FROM "03-sources/article-cards"
+WHERE type = "source_card"
+SORT captured_at DESC
+\`\`\`
+
+## 待审队列
+
+\`\`\`dataview
+TABLE type, status, source_card, raw_note, run_summary
+FROM "03-sources/article-cards" or "04-claims/_suggestions" or "06-assets/_suggestions" or "08-outputs/outlines"
+WHERE status = "to-review"
+SORT created_at DESC
+\`\`\`
+`
+    },
+    {
+        path: "dashboards/Review Queue.md",
+        content: `# 待审队列
+
+未安装 Dataview 时，可直接打开 [[03-sources/article-cards]]、[[04-claims/_suggestions]]、[[06-assets/_suggestions]] 和 [[08-outputs/outlines]] 手工审阅。
+
+## 待审内容
+
+\`\`\`dataview
+TABLE type, source_url, source_card, raw_note, claims_note, assets_note, outline_note
+FROM "03-sources/article-cards" or "04-claims/_suggestions" or "06-assets/_suggestions" or "08-outputs/outlines"
+WHERE status = "to-review"
+SORT captured_at DESC
+\`\`\`
+`
+    },
+    {
+        path: "dashboards/Recent Runs.md",
+        content: `# 最近处理
+
+处理记录用于追溯每次宿主 Agent 入库的 payload、产物和告警。
+
+\`\`\`dataview
+TABLE status, source_url, source_card, raw_note, created_at
+FROM "09-runs"
+WHERE type = "processing_summary"
+SORT created_at DESC
+\`\`\`
+`
+    },
+    {
+        path: "dashboards/Topic Pipeline.md",
+        content: `# 选题管线
+
+选题和大纲是从资料卡继续写作的入口。
+
+\`\`\`dataview
+TABLE status, source_card, outline_note, source_url, created_at
+FROM "07-topics/ready" or "08-outputs/outlines"
+WHERE type = "topic_candidates" or type = "draft_outline"
+SORT created_at DESC
+\`\`\`
+`
+    },
+    {
+        path: "_system/schemas/aiwiki-frontmatter.md",
+        content: `# AIWiki Frontmatter Schema
+
+AIWiki 使用 Obsidian 原生 Properties 作为基础数据库层，Dataview 只作为可选增强。
+
+## Shared Fields
+
+- \`aiwiki_id\`: AIWiki 内部稳定标识。
+- \`type\`: \`source_card\`, \`raw_article\`, \`claim_suggestions\`, \`asset_suggestions\`, \`topic_candidates\`, \`draft_outline\`, \`processing_summary\`。
+- \`status\`: \`to-review\`, \`ready\`, \`draft\`, \`reviewed\`, \`archived\`, \`fetch-failed\`。
+- \`slug\`: 来源标题或 URL 生成的 slug。
+- \`source_url\`: 原始 URL，若没有则为空。
+- \`source_type\`: \`url\`, \`file\`, \`text\` 等来源类型。
+- \`created_at\`: AIWiki 写入时间。
+- \`captured_at\`: 宿主 Agent 读取来源的时间。
+- \`run_id\`: 本次处理记录目录名。
+- \`source_card\`, \`raw_note\`, \`claims_note\`, \`assets_note\`, \`topics_note\`, \`outline_note\`, \`run_summary\`: Obsidian 内部链接字符串。
+- \`tags\`: AIWiki 类型标签。
+
+## Rule
+
+正文中的 wikilink 用于人工阅读；frontmatter 字段是 Dataview 查询和数据库筛选的来源。
+`
+    },
+    {
+        path: "_system/templates/source-card.md",
+        content: `---
+aiwiki_id: ""
+type: "source_card"
+status: "to-review"
+slug: ""
+title: ""
+source_url: ""
+source_type: ""
+created_at: ""
+captured_at: ""
+run_id: ""
+source_card: ""
+raw_note: ""
+claims_note: ""
+assets_note: ""
+topics_note: ""
+outline_note: ""
+run_summary: ""
+tags: ["aiwiki/source-card"]
+---
+
+# 资料卡
+
+## Obsidian 链接
+
+- 原文：
+- Claim 建议：
+- 素材建议：
+- 选题：
+- 大纲：
+- 处理记录：
+
+## 摘要
+
+`
+    },
+    {
+        path: "_system/templates/review-note.md",
+        content: `---
+type: "review_note"
+status: "draft"
+source_card: ""
+created_at: ""
+tags: ["aiwiki/review"]
+---
+
+# 审阅记录
+
+## 判断
+
+## 可复用结论
+
+## 后续动作
+
+`
+    }
+];
+export function resolveRoot(rootPath) {
+    return path.resolve(rootPath);
+}
+export function defaultConfig(createdAt = new Date().toISOString()) {
+    return [
+        "product: aiwiki",
+        "schema_version: 1",
+        `created_at: "${createdAt}"`,
+        "",
+        "knowledge_base:",
+        "  id: default",
+        "  name: AIWiki",
+        "  language: zh-CN",
+        "",
+        "agent:",
+        "  url_first: true",
+        "  fetch_owner: host_agent",
+        "  cli_fetch_webpage: false",
+        "",
+        "review:",
+        "  wiki_merge_policy: manual",
+        "  claim_policy: suggest_only",
+        "  asset_policy: suggest_only",
+        ""
+    ].join("\n");
+}
+export function defaultSetupPath() {
+    return path.join(os.homedir(), "AIWiki");
+}
+export function userConfigPath() {
+    const home = process.env.AIWIKI_HOME ? path.resolve(process.env.AIWIKI_HOME) : path.join(os.homedir(), ".aiwiki");
+    return path.join(home, "config.json");
+}
+export async function setDefaultWorkspace(rootPath) {
+    const root = resolveRoot(rootPath);
+    const configPath = userConfigPath();
+    await fs.mkdir(path.dirname(configPath), { recursive: true });
+    const config = {
+        defaultPath: root,
+        updatedAt: new Date().toISOString()
+    };
+    await fs.writeFile(configPath, `${JSON.stringify(config, null, 2)}\n`, "utf8");
+    return { configPath, defaultPath: root };
+}
+export async function readUserConfig() {
+    const configPath = userConfigPath();
+    if (!(await exists(configPath))) {
+        return {};
+    }
+    return JSON.parse(await fs.readFile(configPath, "utf8"));
+}
+export async function initWorkspace(rootPath) {
+    const root = resolveRoot(rootPath);
+    await fs.mkdir(root, { recursive: true });
+    const createdDirs = [];
+    for (const dir of REQUIRED_DIRS) {
+        const absolute = path.join(root, dir);
+        const existed = await exists(absolute);
+        await fs.mkdir(absolute, { recursive: true });
+        if (!existed) {
+            createdDirs.push(dir);
+        }
+    }
+    const configPath = path.join(root, CONFIG_FILE);
+    const createdConfig = !(await exists(configPath));
+    if (createdConfig) {
+        await fs.writeFile(configPath, defaultConfig(), "utf8");
+    }
+    const seededFiles = await seedWorkspaceFiles(root);
+    return { root, createdConfig, createdDirs, seededFiles };
+}
+async function seedWorkspaceFiles(root) {
+    const files = [];
+    for (const seed of WORKSPACE_SEEDS) {
+        const target = path.join(root, seed.path);
+        const alreadyExists = await exists(target);
+        if (!alreadyExists) {
+            await fs.mkdir(path.dirname(target), { recursive: true });
+            await fs.writeFile(target, seed.content, "utf8");
+        }
+        files.push({ path: seed.path, created: !alreadyExists });
+    }
+    return files;
+}
+export async function resolveWorkspace(optionalPath, startDir = process.cwd()) {
+    if (optionalPath) {
+        const root = resolveRoot(optionalPath);
+        if (!(await exists(path.join(root, CONFIG_FILE)))) {
+            throw new CliError(`未找到配置文件：${path.join(root, CONFIG_FILE)}。请先运行 aiwiki init --path "${root}" --yes。`);
+        }
+        return root;
+    }
+    const found = await findWorkspace(startDir);
+    if (found) {
+        return found;
+    }
+    const userConfig = await readUserConfig();
+    if (userConfig.defaultPath) {
+        const root = resolveRoot(userConfig.defaultPath);
+        if (await exists(path.join(root, CONFIG_FILE))) {
+            return root;
+        }
+        throw new CliError(`默认知识库不可用：${root}。请运行 aiwiki setup --path <知识库路径> --yes 重新设置。`);
+    }
+    throw new CliError("未找到 AIWiki 知识库。请先运行 aiwiki setup，或运行 aiwiki setup --path <知识库路径> --yes。");
+}
+export async function findWorkspace(startDir) {
+    let current = path.resolve(startDir);
+    while (true) {
+        if (await exists(path.join(current, CONFIG_FILE))) {
+            return current;
+        }
+        const parent = path.dirname(current);
+        if (parent === current) {
+            return undefined;
+        }
+        current = parent;
+    }
+}
+export async function promptForInitPath() {
+    const rl = createInterface({ input, output });
+    try {
+        const answer = await rl.question("AIWiki 知识库路径: ");
+        if (!answer.trim()) {
+            throw new CliError("路径不能为空。");
+        }
+        return answer.trim();
+    }
+    finally {
+        rl.close();
+    }
+}
+export async function promptForSetup(options) {
+    if (options.rootPath && options.yes) {
+        return { rootPath: options.rootPath, confirmed: true };
+    }
+    if (!input.isTTY) {
+        return promptForSetupFromPipe(options);
+    }
+    const rl = createInterface({ input, output });
+    try {
+        let rootPath = options.rootPath;
+        if (!rootPath) {
+            const defaultPath = defaultSetupPath();
+            const answer = await rl.question(`AIWiki 知识库路径（直接回车使用 ${defaultPath}）: `);
+            rootPath = answer.trim() || defaultPath;
+        }
+        if (!options.yes) {
+            const root = resolveRoot(rootPath);
+            output.write(`将创建或补齐 AIWiki 目录: ${root}\n`);
+            for (const dir of REQUIRED_DIRS) {
+                output.write(`  - ${dir}\n`);
+            }
+            const answer = await rl.question("确认创建？输入 y 继续: ");
+            if (answer.trim().toLowerCase() !== "y") {
+                return { rootPath, confirmed: false };
+            }
+        }
+        return { rootPath, confirmed: true };
+    }
+    finally {
+        rl.close();
+    }
+}
+async function promptForSetupFromPipe(options) {
+    const lines = await readInputLines();
+    const hasExplicitInput = lines.some((line) => line.trim().length > 0);
+    if (!options.yes && !hasExplicitInput) {
+        throw new CliError("Interactive setup requires a terminal. For scripts, run aiwiki setup --path <path> --yes.");
+    }
+    let lineIndex = 0;
+    let rootPath = options.rootPath;
+    if (!rootPath) {
+        const defaultPath = defaultSetupPath();
+        output.write(`AIWiki 知识库路径（直接回车使用 ${defaultPath}）: `);
+        rootPath = lines[lineIndex]?.trim() || defaultPath;
+        lineIndex += 1;
+    }
+    if (!options.yes) {
+        const root = resolveRoot(rootPath);
+        output.write(`将创建或补齐 AIWiki 目录: ${root}\n`);
+        for (const dir of REQUIRED_DIRS) {
+            output.write(`  - ${dir}\n`);
+        }
+        output.write("确认创建？输入 y 继续: ");
+        return { rootPath, confirmed: lines[lineIndex]?.trim().toLowerCase() === "y" };
+    }
+    return { rootPath, confirmed: true };
+}
+async function readInputLines() {
+    const chunks = [];
+    for await (const chunk of input) {
+        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+    }
+    return Buffer.concat(chunks).toString("utf8").split(/\r?\n/);
+}
+export async function confirmInit(rootPath) {
+    const root = resolveRoot(rootPath);
+    const rl = createInterface({ input, output });
+    try {
+        output.write(`将创建或补齐 AIWiki 目录: ${root}\n`);
+        for (const dir of REQUIRED_DIRS) {
+            output.write(`  - ${dir}\n`);
+        }
+        const answer = await rl.question("确认创建？输入 y 继续: ");
+        return answer.trim().toLowerCase() === "y";
+    }
+    finally {
+        rl.close();
+    }
+}
+export async function readConfig(rootPath) {
+    const root = resolveRoot(rootPath);
+    const configPath = path.join(root, CONFIG_FILE);
+    if (!(await exists(configPath))) {
+        throw new CliError(`未找到配置文件：${configPath}`);
+    }
+    const text = await fs.readFile(configPath, "utf8");
+    return {
+        product: readScalar(text, "product") ?? "unknown",
+        schemaVersion: readScalar(text, "schema_version") ?? "unknown",
+        createdAt: unquote(readScalar(text, "created_at") ?? "unknown")
+    };
+}
+export async function directorySummary(rootPath) {
+    const root = resolveRoot(rootPath);
+    const missing = [];
+    for (const dir of REQUIRED_DIRS) {
+        if (!(await exists(path.join(root, dir)))) {
+            missing.push(dir);
+        }
+    }
+    return { present: REQUIRED_DIRS.length - missing.length, missing };
+}
+export async function doctor(rootPath) {
+    const root = resolveRoot(rootPath);
+    const checks = [];
+    const configPath = path.join(root, CONFIG_FILE);
+    checks.push({
+        name: CONFIG_FILE,
+        status: (await exists(configPath)) ? "ok" : "missing",
+        detail: configPath
+    });
+    for (const dir of REQUIRED_DIRS) {
+        const absolute = path.join(root, dir);
+        checks.push({
+            name: dir,
+            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");
+        await fs.unlink(writeTarget);
+        checks.push({ name: "write_permission", status: "ok", detail: root });
+    }
+    catch {
+        checks.push({ name: "write_permission", status: "permission error", detail: root });
+    }
+    return checks;
+}
+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 };
+    }
+    const entries = await fs.readdir(runsRoot, { withFileTypes: true });
+    const dirs = entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name);
+    let failedCount = 0;
+    for (const dir of dirs) {
+        const payloadPath = path.join(runsRoot, dir, "payload.json");
+        try {
+            const payload = JSON.parse(await fs.readFile(payloadPath, "utf8"));
+            if (payload.source?.fetch_status === "failed") {
+                failedCount += 1;
+            }
+        }
+        catch {
+            if (dir.endsWith("-fetch-failed")) {
+                failedCount += 1;
+            }
+        }
+    }
+    const stats = [];
+    for (const dir of dirs) {
+        stats.push({ dir, mtimeMs: (await fs.stat(path.join(runsRoot, dir))).mtimeMs });
+    }
+    stats.sort((a, b) => b.mtimeMs - a.mtimeMs);
+    return {
+        root,
+        runCount: dirs.length,
+        failedCount,
+        lastRunId: stats[0]?.dir
+    };
+}
+export async function exists(target) {
+    try {
+        await fs.access(target);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function readScalar(text, key) {
+    const pattern = new RegExp(`^${key}:\\s*(.+)$`, "m");
+    return pattern.exec(text)?.[1]?.trim();
+}
+function unquote(value) {
+    return value.replace(/^["']|["']$/g, "");
+}

package/docs/AGENT_HANDOFF.md

@@ -0,0 +1,132 @@
+# AIWiki Agent 对接说明
+
+这份文档写给任何可以读取网页、生成结构化内容并调用本机命令的宿主 Agent。
+
+## 目标
+
+当用户说：
+
+```text
+入库 https://example.com/article
+```
+
+Agent 应自动读取网页，生成 payload，通过 AIWiki CLI 写入本地知识库，并把结果摘要回复给用户。
+
+## 职责边界
+
+```text
+Agent 负责：读取网页、整理正文、生成 payload、调用 CLI、回复用户
+AIWiki CLI 负责：校验 payload、写本地文件、输出入库结果
+用户负责：提供链接或正文，最后审阅结果
+```
+
+AIWiki CLI 不做通用网页抓取。网页读取失败时，Agent 仍然要调用 CLI 记录失败原因。
+
+## 标准流程
+
+1. 读取用户给的 URL、正文、附件或消息。
+2. 如果读取成功，生成 `fetch_status: "ok"` 的 payload。
+3. 如果读取失败，生成 `fetch_status: "failed"` 的 payload，并写清 `fetch_notes`。
+4. 不要让用户保存 payload。
+5. 不要让用户手动运行命令。
+6. 优先通过 stdin 调用：
+
+```bash
+aiwiki ingest-agent --stdin
+```
+
+7. 读取 CLI 输出，向用户回复入库状态、契合度、摘要、资料卡、处理记录和 Obsidian 审阅入口。
+
+## 成功 payload
+
+```json
+{
+  "schema_version": "aiwiki.agent_payload.v1",
+  "source": {
+    "kind": "url",
+    "url": "https://example.com/article",
+    "title": "文章标题",
+    "content_format": "markdown",
+    "content": "这里是宿主 Agent 读取到的正文内容。",
+    "fetcher": "host-agent",
+    "fetch_status": "ok",
+    "captured_at": "2026-05-07T10:00:00+08:00"
+  },
+  "request": {
+    "mode": "ingest",
+    "outputs": [
+      "source_card",
+      "creative_assets",
+      "topics",
+      "draft_outline",
+      "processing_summary"
+    ],
+    "language": "zh-CN"
+  }
+}
+```
+
+## 失败 payload
+
+```json
+{
+  "schema_version": "aiwiki.agent_payload.v1",
+  "source": {
+    "kind": "url",
+    "url": "https://example.com/article",
+    "title": "无法读取的文章",
+    "fetcher": "host-agent",
+    "fetch_status": "failed",
+    "fetch_notes": "网页需要登录或宿主 Agent 无法访问正文。",
+    "captured_at": "2026-05-07T10:00:00+08:00"
+  },
+  "request": {
+    "mode": "record_fetch_failure",
+    "outputs": [
+      "processing_summary"
+    ],
+    "language": "zh-CN"
+  }
+}
+```
+
+## 禁止事项
+
+- 不要在 payload 中包含输出路径。
+- 不要让用户手动保存 payload。
+- 不要让用户每次输入 `--path`。
+- 不要声称网页抓取是 AIWiki CLI 的能力。
+- 不要在 `fetch_status: "failed"` 时塞入正文内容。
+- 不要替用户安装 Dataview。
+- 不要修改 `.obsidian`、`community-plugins.json` 或 Obsidian 插件配置。
+
+## Obsidian + Dataview 边界
+
+AIWiki 生成的知识库不依赖 Dataview。用户不安装 Dataview 时，也可以用 Obsidian 原生 Properties、Backlinks、Search、Graph View 和普通 wikilink 审阅。
+
+Dataview 只是可选增强。用户自行在 Obsidian Community plugins 中安装并启用 Dataview 后，`dashboards/AIWiki Home.md`、`dashboards/Review Queue.md`、`dashboards/Recent Runs.md` 和 `dashboards/Topic Pipeline.md` 会渲染成表格。
+
+## Agent 回复模板
+
+成功时：
+
+```text
+已加入 Obsidian 审阅队列。
+契合度：<fit_score> / <fit_level>
+摘要：<summary>
+资料卡：<source_card>
+处理记录：<processing_summary>
+Obsidian 入口：<dashboard>
+待审队列：<review_queue>
+```
+
+失败但已记录时：
+
+```text
+未成功入库正文，但已记录失败原因。
+原因：<summary>
+记录目录：<run_dir>
+处理摘要：<processing_summary>
+Obsidian 入口：<dashboard>
+待审队列：<review_queue>
+```