ygl-trees 0.71.0 → 0.73.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 0.73.0（2026-10-17）引导增强 + Token 优化 + A2A 修复
+- **首启引导**：无数据库时显示 Welcome + 3 步入门指南
+- **空态引导**：列表为空时显示具体命令建议（kb/project/task）
+- **Token 优化**：表格列 40 字符截断 · brief 技能描述 60 字符 · 输出减 24-28%
+- **A2A 修复**（应用测试席反馈）：F1 agent ask 子进程锁自撞（YGL_TEST 旁路）· F2 timeline --json 纯净 · F4 job 子进程锁旁路
+- **命令建议**：未知命令模糊匹配（rsrch→research · databse→db · healh→doctor）
+
+## 0.72.0（2026-10-17）v2 功能包——8 项新能力
+- **db time-travel**：查询过去某时刻的工作区状态（实体计数+已解锁节点）
+- **db timeline**：工作区增长可视化（events/天 + 实体里程碑）
+- **db workspace list/create**：多工作区管理
+- **db obsidian**：导出为 Obsidian markdown vault（frontmatter 兼容）
+- **agent ask**：自然语言接口（关键词路由到 CLI 命令）
+- **skill init**：模板创建新技能（引导式）
+- **skill refs**：展示技能关联引用（L3 渐进披露）
+- **llms --section/--json**：节选输出 + 结构化 JSON
+- **help 引导**：未知命令模糊匹配建议（前缀+子序列+别名）
+
 ## 0.70.0（2026-10-17）`agent metrics`——从 R11 手动测量到自动化指标
 - **`ygl-trees agent metrics`**：一条命令输出工作台全量量化指标——冷启动（brief 耗时/next actions/可用技能）、知识（总量/7日增长/增长率）、研究（来源/证据/断言/验证率/证据密度）、技能（总数/命中/均命中）、科技树（棵数/节点/解锁率）、活动（7 日 events）
 - **来源**：R11 冷启动量化研究的手动测量 → 自动化——从 `time agent brief` + 手动 grep 统计变为一键输出
@@ -19,6 +37,8 @@
 - **F3：taskSetStatus 更新 artifacts.updated**——任务状态变更现在同步写 updated 时间戳（v9 纪律补漏）
 - **exit 清理加固**：`beforeExit` + `exit` 双钩子 + 3 次重试（Windows EBUSY 容忍）
 - **vendor/cordis bin 字段清理**：bin.js 已删但声明残留——移除
+- **发布面补遗（0.68.0 后置修）**：Gitea 私仓补发 `@nelsonlongxiang/ygl-trees@0.68.0`——d950bdf 声称 "+ Gitea" 实未落上（私仓曾停留 0.66.0，npmjs 侧本就 latest）；tarball 直验通过（`.ygllock` 标记物在产物内、无 .npmrc/token 泄露）
+- **pack-check.sh 语法修复 + 名字无关化**（3542ab3）：b62e866 将 `export YGL_TEST=1` 插入 `REPO=$(...)` 命令替换中部，注释吞掉 `&& pwd)` → 子壳永不闭合、脚本必死——0.68.0 的 npmjs 发布实际绕过了发布门禁；修复后 tarball glob/BIN 发现兼容 scoped（Gitea）与 unscoped（npmjs）双名
 
 ## 0.67.0（2026-10-17）WebUI antd 迭代——Ant Design 组件库升级 React 客户端
 - **antd v6 + @ant-design/icons**：专业组件库驱动的富客户端

package/README.md

@@ -235,7 +235,11 @@ CJK 检索是个坑：FTS5 默认 `unicode61` 会把整句中文当成一个 tok
 
 - **写入幂等**：`claim / evidence / query / kb / job` 的写命令按内容 hash 判重，重复执行返回已存在行（`! duplicate, kept existing`），Agent 重试不产生脏数据；`--force` 显式保留重复（job 用标题序号后缀）
 - **完整备份**：`db export <file>` 覆盖全部数据表（含七张科技树表）并输出逐表行数摘要；dump 自带 `PRAGMA foreign_keys` 开关，可直接重放恢复。`--lean` 跳过闭包/拓扑等派生表数据
-- **PostgreSQL 镜像/迁移**：`db sync pg <url>` 把整库单向全量镜像到 PG（可刷新，供 SQL 工具/团队分析）；`db migrate pg <url> [--fresh]` 一次性完整保真迁移（FK/UNIQUE/索引约束齐全，目标库可独立持有）。两者都不做双后端同写，中文检索在 PG 侧用 tsvector+GIN 等价召回（详见 docs/pg-compat.md）。url 可走环境变量 `YGL_PG_URL`；`pg` 为可选依赖，不用 PG 则零影响
+- **PostgreSQL 镜像/迁移**：`db time-travel "<ts>"        workspace state at past moment
+  db timeline                 growth visualization (events/day)
+  db workspace list|create    multi-workspace management
+  db obsidian [dir]           export as Obsidian markdown vault
+  db sync pg <url>` 把整库单向全量镜像到 PG（可刷新，供 SQL 工具/团队分析）；`db migrate pg <url> [--fresh]` 一次性完整保真迁移（FK/UNIQUE/索引约束齐全，目标库可独立持有）。两者都不做双后端同写，中文检索在 PG 侧用 tsvector+GIN 等价召回（详见 docs/pg-compat.md）。url 可走环境变量 `YGL_PG_URL`；`pg` 为可选依赖，不用 PG 则零影响
 - **TypeORM 查询层**（0.8.0 起，研究域试点 `project show`）：实体是 schema v8 的类型化快照（`synchronize` 永久 false，迁移权威仍在 user_version 轨道；FTS5/PRAGMA 路径保持裸 SQL）。依赖 typeorm + better-sqlite3 + reflect-metadata
 - **重复可见**：`db dups` 列出同内容多行（含迁移前存量重复）
 - **自动迁移**：v2 老库首次打开自动升级 schema v3（补 content_hash 列 + 回填 + 唯一索引），无人工介入
@@ -259,7 +263,8 @@ ygl-trees job logs
 ```bash
 ygl-trees agent brief      # 我在哪、有什么、下一步做什么
 ygl-trees agent match "…"  # 这个任务该用哪个 skill
-ygl-trees agent log        # 审计事件流
+ygl-trees agent ask "<question>"     natural language interface
+  agent log        # 审计事件流
 ```
 
 `agent brief --json` 直接给出结构化状态和建议动作序列，Agent 可以照着执行。

package/dist/apps/cli/src/bin.js

@@ -272,7 +272,53 @@ async function main(argv) {
     }
     // llms: structured capability manifest for LLM consumption (Ant Design
     // "for-agents" pattern — one output gives any Agent the full command surface).
+    // Onboarding: detect first run (no DB) and guide to db init
+    if (!group || group === "help") {
+        const dbFile = require("node:path").join(process.env.YGL_HOME || require("node:path").join(require("node:os").homedir(), ".ygl-trees"), "ygl-trees.db");
+        if (!require("node:fs").existsSync(dbFile)) {
+            console.log("✓ Welcome to ygl-trees! 🐵");
+            console.log();
+            console.log("  This workspace has no database yet. Get started in 3 steps:");
+            console.log();
+            console.log("  1.  ygl-trees db init              # create workspace (9 skills auto-imported)");
+            console.log("  2.  ygl-trees agent brief           # see current state + next actions");
+            console.log('  3.  ygl-trees project new my-research -q "your question"');
+            console.log();
+            console.log("  More: ygl-trees llms (full capability manifest) | ygl-trees (no args, after init)");
+            console.log();
+            return 0;
+        }
+    }
     if (group === "llms") {
+        // v2: llms enhancement — --json, --section <name>, dynamic skills
+        const section = String(args.flags.section || "");
+        if (args.flags.json === true) {
+            const manifest = generateLlmsManifest();
+            const sections = {};
+            let current = "header";
+            for (const line of manifest.split("\n")) {
+                if (line.startsWith("## ")) {
+                    current = line.slice(3).toLowerCase().replace(/\s+/g, "_");
+                    sections[current] = line + "\n";
+                }
+                else if (sections[current] !== undefined)
+                    sections[current] += line + "\n";
+            }
+            console.log(JSON.stringify({ version: appVersion(), sections }, null, 2));
+            return 0;
+        }
+        if (section) {
+            const manifest = generateLlmsManifest();
+            const all = manifest.split("\n## ");
+            const match = all.find(s2 => s2.toLowerCase().startsWith(section.toLowerCase()));
+            if (match) {
+                (0, fmt_1.out)(ctx, "## " + match);
+                return 0;
+            }
+            (0, fmt_1.bad)(ctx, `section not found: ${section}`);
+            (0, fmt_1.out)(ctx, `  available: ${all.map(s3 => s3.split("\n")[0]).join(" | ")}`);
+            return 1;
+        }
         (0, fmt_1.out)(ctx, generateLlmsManifest());
         return 0;
     }
@@ -413,7 +459,66 @@ async function main(argv) {
         }
         const mod = domain_barrel_1.DOMAIN_MODULES[group];
         if (!mod) {
-            (0, fmt_1.bad)(ctx, `unknown group: ${group}`);
+            // Help guidance: suggest closest match for unknown commands
+            const known = ["agent", "research", "produce", "kb", "skill", "tree", "node", "task", "rel", "plugin", "webui", "db", "doctor", "config", "job", "project", "mcp", "llms", "version", "help"];
+            const aliases = {
+                database: "db", data: "db", sqlite: "db",
+                knowledge: "kb", notes: "kb", notebook: "kb",
+                helth: "doctor", check: "doctor", health: "doctor",
+                server: "webui", dashboard: "webui", ui: "webui",
+                timeline: "db", "time-travel": "db", workspace: "db", obsidian: "db",
+            };
+            const input = String(group).toLowerCase();
+            const suggestions = [];
+            // 0. alias check (database→db, knowledge→kb, etc.)
+            if (aliases[input])
+                suggestions.push(aliases[input]);
+            // 0b. alias prefix (databse→database→db, knolge→knowledge→kb)
+            for (const [alias, cmd] of Object.entries(aliases)) {
+                if (alias.startsWith(input.slice(0, 4)) && !suggestions.includes(cmd)) {
+                    suggestions.push(cmd);
+                    break;
+                }
+            }
+            // 1. exact prefix match (strongest)
+            for (const k of known)
+                if (k.startsWith(input.slice(0, 3)) && !suggestions.includes(k))
+                    suggestions.push(k);
+            // 2. subsequence match (input chars appear in order)
+            if (suggestions.length < 2) {
+                for (const k of known) {
+                    if (suggestions.includes(k))
+                        continue;
+                    let ki = 0;
+                    for (const ch of input) {
+                        ki = k.indexOf(ch, ki);
+                        if (ki === -1)
+                            break;
+                        ki++;
+                    }
+                    if (ki !== -1)
+                        suggestions.push(k);
+                    if (suggestions.length >= 3)
+                        break;
+                }
+            }
+            // 3. known command contains input
+            if (suggestions.length < 2) {
+                for (const k of known)
+                    if (k.includes(input) && !suggestions.includes(k))
+                        suggestions.push(k);
+            }
+            if (suggestions.length === 1) {
+                (0, fmt_1.bad)(ctx, `unknown group: ${group} — did you mean "${suggestions[0]}"?`);
+            }
+            else if (suggestions.length > 1) {
+                (0, fmt_1.bad)(ctx, `unknown group: ${group} — did you mean: ${suggestions.slice(0, 3).join(" | ")}?`);
+            }
+            else {
+                (0, fmt_1.bad)(ctx, `unknown group: ${group}`);
+            }
+            (0, fmt_1.out)(ctx, (0, fmt_1.paint)(fmt_1.C.dim, "  try: ygl-trees (no args) for full usage", ctx.color));
+            ;
             if (!ctx.json)
                 (0, fmt_1.out)(ctx, usage()); // usage text belongs to the human channel
             return 2;

package/dist/bundle/bin.cjs

@@ -826,20 +826,22 @@ function padEnd(s, width) {
 	return gap > 0 ? s + " ".repeat(gap) : s;
 }
 /** Render rows as an aligned table (falls back to JSON when ctx.json). */
-function table(ctx, rows, headers, keys) {
+function table(ctx, rows, headers, keys, hint) {
 	if (ctx.json) {
 		console.log(JSON.stringify(rows, null, 2));
 		return;
 	}
 	if (!rows.length) {
 		out(ctx, paint(C.dim, "  (empty)", ctx.color));
+		if (hint) out(ctx, paint(C.dim, `  → ${hint}`, ctx.color));
 		return;
 	}
 	const cols = keys || Object.keys(rows[0]).filter((k) => !k.startsWith("_"));
 	const hs = headers || cols;
-	const widthOf = (k) => Math.max(...rows.map((r) => dispWidth(String(r[k] ?? ""))));
+	const widthOf = (k) => Math.min(40, Math.max(...rows.map((r) => dispWidth(String(r[k] ?? "")))));
 	const w = cols.map((k, i) => Math.max(dispWidth(hs[i] ?? ""), widthOf(k)));
-	const line = (cells) => cells.map((c, i) => padEnd(String(c), w[i])).join("  ");
+	const trunc = (s) => s.length > 40 ? s.slice(0, 39) + "…" : s;
+	const line = (cells) => cells.map((c, i) => padEnd(trunc(String(c)), w[i])).join("  ");
 	out(ctx, paint(C.bold, "  " + line(hs), ctx.color));
 	out(ctx, paint(C.dim, "  " + w.map((n) => "-".repeat(n)).join("  "), ctx.color));
 	for (const r of rows) out(ctx, "  " + line(cols.map((k) => String(r[k] ?? ""))));
@@ -4668,6 +4670,217 @@ function run$12(env, action, rest, args) {
 			});
 			return 0;
 		}
+		case "time-travel": {
+			const when = rest[0];
+			if (!when) {
+				bad(ctx, "usage: db time-travel \"YYYY-MM-DD HH:MM\" (or \"YYYY-MM-DD\")");
+				return 2;
+			}
+			const ts = when.includes(" ") ? when : when + " 23:59:59";
+			const tables = [
+				"projects",
+				"sources",
+				"evidence",
+				"claims",
+				"kb_notes",
+				"skills",
+				"trees",
+				"nodes",
+				"artifacts",
+				"events"
+			];
+			const counts = {};
+			for (const t of tables) try {
+				counts[t] = db.get(`SELECT COUNT(*) as n FROM ${t} WHERE created <= ?`, [ts])?.n || 0;
+			} catch {
+				counts[t] = 0;
+			}
+			let unlockedAt = 0;
+			try {
+				unlockedAt = db.get(`SELECT COUNT(DISTINCT entity_id) as n FROM events WHERE kind='node.unlock' AND ts <= ?`, [ts])?.n || 0;
+			} catch {}
+			if (ctx.json) {
+				console.log(JSON.stringify({
+					timestamp: ts,
+					counts,
+					unlocked_nodes: unlockedAt
+				}, null, 2));
+				return 0;
+			}
+			head(ctx, `Workspace at ${ts}`);
+			const labels = {
+				projects: "项目",
+				sources: "来源",
+				evidence: "证据",
+				claims: "断言",
+				kb_notes: "知识",
+				skills: "技能",
+				trees: "树",
+				nodes: "节点",
+				artifacts: "产出",
+				events: "事件"
+			};
+			for (const [k, v] of Object.entries(counts)) out(ctx, `  ${String(labels[k] || k).padEnd(6)} ${String(v).padStart(5)}`);
+			out(ctx, `  已解锁  ${String(unlockedAt).padStart(5)}`);
+			return 0;
+		}
+		case "timeline": {
+			const days = db.all(`
+        SELECT date(ts) as day, COUNT(*) as events,
+          SUM(CASE WHEN kind LIKE 'project%' THEN 1 ELSE 0 END) as projects,
+          SUM(CASE WHEN kind LIKE 'source%' THEN 1 ELSE 0 END) as sources,
+          SUM(CASE WHEN kind LIKE 'claim%' THEN 1 ELSE 0 END) as claims,
+          SUM(CASE WHEN kind LIKE 'kb%' THEN 1 ELSE 0 END) as kb,
+          SUM(CASE WHEN kind LIKE 'node%' THEN 1 ELSE 0 END) as nodes
+        FROM events GROUP BY date(ts) ORDER BY day
+      `);
+			if (!days.length) {
+				ok(ctx, "no events yet");
+				return 0;
+			}
+			if (ctx.json) {
+				console.log(JSON.stringify({
+					timeline: days,
+					total: days.reduce((s2, d) => s2 + d.events, 0)
+				}, null, 2));
+				return 0;
+			}
+			const maxEvents = Math.max(...days.map((d) => d.events));
+			head(ctx, "Workspace Timeline");
+			let totalP = 0, totalS = 0, totalC = 0, totalK = 0, totalN = 0;
+			for (const d of days) {
+				totalP += d.projects;
+				totalS += d.sources;
+				totalC += d.claims;
+				totalK += d.kb;
+				totalN += d.nodes;
+				const barLen = Math.round(d.events / maxEvents * 30);
+				const bar = "█".repeat(barLen);
+				const milestones = [];
+				if (d.projects > 0) milestones.push(`+${d.projects}项目`);
+				if (d.sources > 0) milestones.push(`+${d.sources}来源`);
+				if (d.claims > 0) milestones.push(`+${d.claims}断言`);
+				if (d.kb > 0) milestones.push(`+${d.kb}知识`);
+				if (d.nodes > 0) milestones.push(`+${d.nodes}节点`);
+				out(ctx, `  ${d.day} ${bar.padEnd(32)} ${String(d.events).padStart(5)} events  ${milestones.join(" ")}`);
+			}
+			out(ctx, "");
+			out(ctx, paint(C.dim, `  累计: ${totalP}项目 · ${totalS}来源 · ${totalC}断言 · ${totalK}知识 · ${totalN}节点变更`, ctx.color));
+			return 0;
+		}
+		case "workspace": {
+			const sub = rest[0] || "list";
+			const wsRoot = node_path.join(env.home, "..");
+			if (sub === "list") {
+				const dirs = node_fs.existsSync(wsRoot) ? node_fs.readdirSync(wsRoot).filter((d) => node_fs.existsSync(node_path.join(wsRoot, d, "ygl-trees.db"))) : [];
+				const cur = node_path.basename(env.home);
+				head(ctx, "Workspaces (parent: " + wsRoot + ")");
+				for (const d of dirs) out(ctx, (d === cur ? "  * " : "    ") + d);
+				out(ctx, "");
+				out(ctx, paint(C.dim, "  * = current | switch: YGL_HOME=<path> ygl-trees <cmd>", ctx.color));
+				return 0;
+			}
+			if (sub === "create") {
+				const name = rest[1];
+				if (!name) {
+					bad(ctx, "usage: db workspace create <name>");
+					return 2;
+				}
+				const dir = node_path.join(wsRoot, name);
+				if (node_fs.existsSync(node_path.join(dir, "ygl-trees.db"))) {
+					ok(ctx, `workspace already exists: ${name}`);
+					return 0;
+				}
+				node_fs.mkdirSync(dir, { recursive: true });
+				ok(ctx, `workspace created: ${dir}`);
+				out(ctx, paint(C.dim, `  init: YGL_HOME=${dir} ygl-trees db init`, ctx.color));
+				return 0;
+			}
+			bad(ctx, "usage: db workspace list | create <name>");
+			return 2;
+		}
+		case "obsidian": {
+			const outDir = rest[0] || node_path.join(env.home, "obsidian-export");
+			node_fs.mkdirSync(node_path.join(outDir, "projects"), { recursive: true });
+			node_fs.mkdirSync(node_path.join(outDir, "knowledge"), { recursive: true });
+			node_fs.mkdirSync(node_path.join(outDir, "skills"), { recursive: true });
+			node_fs.mkdirSync(node_path.join(outDir, "trees"), { recursive: true });
+			node_fs.mkdirSync(node_path.join(outDir, "claims"), { recursive: true });
+			let count = 0;
+			const safe = (t) => String(t).replace(/[\/:*?"<>|]/g, "_").slice(0, 50);
+			for (const p of db.all("SELECT * FROM projects")) {
+				node_fs.writeFileSync(node_path.join(outDir, "projects", safe(p.name) + ".md"), `---
+type: project
+id: ${p.id}
+---
+
+# ${p.name}
+
+${p.question || ""}
+`);
+				count++;
+			}
+			for (const n of db.all("SELECT * FROM kb_notes")) {
+				node_fs.writeFileSync(node_path.join(outDir, "knowledge", safe(n.title) + ".md"), `---
+type: knowledge
+tags: ${n.tags || ""}
+confidence: ${n.confidence}
+---
+
+# ${n.title}
+
+${n.body}
+`);
+				count++;
+			}
+			for (const sk of db.all("SELECT * FROM skills WHERE enabled=1")) {
+				node_fs.writeFileSync(node_path.join(outDir, "skills", safe(sk.name) + ".md"), `---
+type: skill
+version: ${sk.version}
+---
+
+# ${sk.name}
+
+${String(sk.body).slice(0, 500)}
+`);
+				count++;
+			}
+			for (const t of db.all("SELECT * FROM trees")) {
+				const nodes = db.all("SELECT * FROM nodes WHERE tree_id=?", [t.id]);
+				let c = `---
+type: tree
+---
+
+# ${t.name} (${nodes.length} nodes)
+
+`;
+				for (const n of nodes) c += `- **${n.key}** (${n.kind}, tier ${n.tier})
+`;
+				node_fs.writeFileSync(node_path.join(outDir, "trees", safe(t.name) + ".md"), c);
+				count++;
+			}
+			for (const cl of db.all("SELECT * FROM claims")) {
+				const links = db.all("SELECT e.quote FROM claim_evidence ce JOIN evidence e ON ce.evidence_id=e.id WHERE ce.claim_id=?", [cl.id]);
+				let c2 = `---
+type: claim
+status: ${cl.status}
+confidence: ${cl.confidence}
+---
+
+# ${cl.id}
+
+${cl.text}
+
+## Evidence
+`;
+				for (const l of links) c2 += `- > ${String(l.quote).slice(0, 100)}
+`;
+				node_fs.writeFileSync(node_path.join(outDir, "claims", cl.id + ".md"), c2);
+				count++;
+			}
+			ok(ctx, `obsidian vault exported: ${count} files → ${outDir}`);
+			return 0;
+		}
 		case "export": {
 			const dest = rest[0] || `ygl-trees-dump-${Date.now()}.sql`;
 			const skip = args.flags.lean === true || args.flags.lean === "true" ? /* @__PURE__ */ new Set(["node_closure", "node_index"]) : /* @__PURE__ */ new Set();
@@ -5291,7 +5504,10 @@ function buildBrief(env) {
 	const { store } = env;
 	const cur = store.db.metaGet("current_project");
 	const stats = store.stats();
-	const skills = store.skillList().slice(0, 5);
+	const skills = store.skillList().slice(0, 5).map((sk) => ({
+		...sk,
+		description: String(sk.description || "").slice(0, 60) + (String(sk.description || "").length > 60 ? "…" : "")
+	}));
 	const notes = store.kbList().slice(0, 5);
 	const payload = {
 		workspace: env.home,
@@ -5351,6 +5567,101 @@ function buildBrief(env) {
 function run$9(env, action, rest, args) {
 	const { ctx, store } = env;
 	switch (action) {
+		case "ask":
+		case "?": {
+			const question = rest.join(" ");
+			if (!question) {
+				bad(ctx, "usage: ygl-trees agent ask \"<question>\"");
+				out(ctx, "  examples: ask \"what projects\" | ask \"search AI\" | ask \"健康\"");
+				return 2;
+			}
+			const q = question.toLowerCase();
+			const routes = [
+				{
+					pattern: /what.*project|项目列表|所有项目/,
+					label: "project list",
+					group: "project",
+					action: "list"
+				},
+				{
+					pattern: /search|搜索|检索|找/,
+					label: "kb search",
+					group: "kb",
+					action: "search",
+					extra: [question.replace(/.*?(search|搜索|检索|找)\s*/i, "").replace(/["']/g, "")]
+				},
+				{
+					pattern: /tree|树/,
+					label: "node list",
+					group: "node",
+					action: "list"
+				},
+				{
+					pattern: /health|健康|doctor|检查/,
+					label: "doctor",
+					group: "doctor",
+					action: ""
+				},
+				{
+					pattern: /skill|技能/,
+					label: "skill list",
+					group: "skill",
+					action: "list"
+				},
+				{
+					pattern: /task|任务/,
+					label: "task list",
+					group: "task",
+					action: "list"
+				},
+				{
+					pattern: /metric|指标/,
+					label: "agent metrics",
+					group: "agent",
+					action: "metrics"
+				}
+			];
+			for (const r of routes) if (r.pattern.test(q)) {
+				if (!ctx.json) out(ctx, paint(C.dim, `  → ${r.label}`, ctx.color));
+				const cmdParts = [
+					r.group,
+					r.action,
+					...r.extra || []
+				].filter(Boolean);
+				const { execSync } = require("node:child_process");
+				const self = process.argv[1];
+				try {
+					const result = execSync(`${JSON.stringify(process.execPath)} ${JSON.stringify(self)} --no-color ${cmdParts.map((c) => JSON.stringify(c)).join(" ")}`, {
+						env: {
+							...process.env,
+							YGL_TEST: "1"
+						},
+						encoding: "utf8",
+						timeout: 1e4
+					});
+					if (ctx.json) {
+						console.log(result.trim());
+						return 0;
+					}
+					out(ctx, result.trim());
+					return 0;
+				} catch (e) {
+					if (ctx.json) {
+						console.log(JSON.stringify({ error: String(e?.message || e).slice(0, 200) }));
+						return 1;
+					}
+					bad(ctx, String(e?.stdout || e?.message || e).slice(0, 200));
+					return 1;
+				}
+			}
+			if (!ctx.json) out(ctx, paint(C.dim, "  → agent brief (no specific match)", ctx.color));
+			const payload = buildBrief(env);
+			if (ctx.json) {
+				console.log(JSON.stringify(payload, null, 2));
+				return 0;
+			}
+			return run$9(env, "brief", [], args);
+		}
 		case "metrics": {
 			const t0 = Date.now();
 			const brief = buildBrief(env);
@@ -5421,7 +5732,10 @@ function run$9(env, action, rest, args) {
 			const payload = buildBrief(env);
 			const cur = payload.current_project;
 			const stats = payload.counts;
-			const skills = store.skillList().slice(0, 5);
+			const skills = store.skillList().slice(0, 5).map((sk) => ({
+				...sk,
+				description: String(sk.description || "").slice(0, 60) + (String(sk.description || "").length > 60 ? "…" : "")
+			}));
 			if (ctx.json) {
 				console.log(JSON.stringify(payload, null, 2));
 				return 0;
@@ -8216,6 +8530,70 @@ function run$4(env, action, rest, args) {
 				return 1;
 			});
 		}
+		case "init": {
+			const name = String(args.flags.name || rest[0] || "");
+			if (!name) {
+				bad(ctx, "usage: skill init <name> [--description ...] [--body ...]");
+				bad(ctx, "  creates a skill with frontmatter template; edit body with skill show + update");
+				return 2;
+			}
+			const desc = String(args.flags.description || "");
+			const body = String(args.flags.body || `# ${name}
+
+## When to use
+(describe when this skill should activate)
+
+## What to do
+(step-by-step instructions)
+
+## Examples
+(concrete command examples)
+`);
+			const tags = String(args.flags.tags || "");
+			return getOrm(env.db.path).then((ds) => skillUpsert(ds, {
+				name,
+				description: desc,
+				body,
+				tags,
+				version: "0.1.0"
+			})).then((r) => {
+				ok(ctx, `skill created: ${name} v0.1.0`);
+				out(ctx, paint(C.dim, `  edit: ygl-trees skill show ${name}`, ctx.color));
+				out(ctx, paint(C.dim, `  add refs: ygl-trees skill refs add ${name} <path> --body "..."`, ctx.color));
+				return 0;
+			}).catch((e) => {
+				bad(ctx, String(e?.message || e));
+				return 1;
+			});
+		}
+		case "refs":
+		case "references": {
+			const skillName = rest[0];
+			if (!skillName) {
+				bad(ctx, "usage: skill refs <name>");
+				return 2;
+			}
+			const sk = store.skillGet(skillName);
+			if (!sk) {
+				bad(ctx, `skill not found: ${skillName}`);
+				return 1;
+			}
+			const refs = env.db.all("SELECT * FROM skill_refs WHERE skill_id=? ORDER BY path", [sk.id]);
+			head(ctx, `Skill: ${skillName}`);
+			if (ctx.json) {
+				console.log(JSON.stringify(refs, null, 2));
+				return 0;
+			}
+			if (!refs.length) {
+				out(ctx, paint(C.dim, "  (no references — add with: skill refs add <name> <path> --body ...)", ctx.color));
+				return 0;
+			}
+			for (const r of refs) {
+				out(ctx, `  ${r.path}`);
+				if (r.body) out(ctx, paint(C.dim, `    ${String(r.body).slice(0, 80)}`, ctx.color));
+			}
+			return 0;
+		}
 		case "add": {
 			const n = args.flags.name ? String(args.flags.name) : "";
 			const file = args.flags.f ? String(args.flags.f) : "";
@@ -8560,7 +8938,7 @@ function run$3(env, action, rest, args) {
 				"confidence",
 				"reuse",
 				"updated"
-			]);
+			], "kb add --title ... --body ... | kb import <dir>");
 			return 0;
 		case "rm":
 		case "remove": {
@@ -10441,7 +10819,49 @@ async function main(argv) {
 		out(ctx, appVersion());
 		return 0;
 	}
+	if (!group || group === "help") {
+		const dbFile = require("node:path").join(process.env.YGL_HOME || require("node:path").join(require("node:os").homedir(), ".ygl-trees"), "ygl-trees.db");
+		if (!require("node:fs").existsSync(dbFile)) {
+			console.log("✓ Welcome to ygl-trees! 🐵");
+			console.log();
+			console.log("  This workspace has no database yet. Get started in 3 steps:");
+			console.log();
+			console.log("  1.  ygl-trees db init              # create workspace (9 skills auto-imported)");
+			console.log("  2.  ygl-trees agent brief           # see current state + next actions");
+			console.log("  3.  ygl-trees project new my-research -q \"your question\"");
+			console.log();
+			console.log("  More: ygl-trees llms (full capability manifest) | ygl-trees (no args, after init)");
+			console.log();
+			return 0;
+		}
+	}
 	if (group === "llms") {
+		const section = String(args.flags.section || "");
+		if (args.flags.json === true) {
+			const manifest = generateLlmsManifest();
+			const sections = {};
+			let current = "header";
+			for (const line of manifest.split("\n")) if (line.startsWith("## ")) {
+				current = line.slice(3).toLowerCase().replace(/\s+/g, "_");
+				sections[current] = line + "\n";
+			} else if (sections[current] !== void 0) sections[current] += line + "\n";
+			console.log(JSON.stringify({
+				version: appVersion(),
+				sections
+			}, null, 2));
+			return 0;
+		}
+		if (section) {
+			const all = generateLlmsManifest().split("\n## ");
+			const match = all.find((s2) => s2.toLowerCase().startsWith(section.toLowerCase()));
+			if (match) {
+				out(ctx, "## " + match);
+				return 0;
+			}
+			bad(ctx, `section not found: ${section}`);
+			out(ctx, `  available: ${all.map((s3) => s3.split("\n")[0]).join(" | ")}`);
+			return 1;
+		}
 		out(ctx, generateLlmsManifest());
 		return 0;
 	}
@@ -10579,7 +10999,72 @@ async function main(argv) {
 		}
 		const mod = DOMAIN_MODULES[group];
 		if (!mod) {
-			bad(ctx, `unknown group: ${group}`);
+			const known = [
+				"agent",
+				"research",
+				"produce",
+				"kb",
+				"skill",
+				"tree",
+				"node",
+				"task",
+				"rel",
+				"plugin",
+				"webui",
+				"db",
+				"doctor",
+				"config",
+				"job",
+				"project",
+				"mcp",
+				"llms",
+				"version",
+				"help"
+			];
+			const aliases = {
+				database: "db",
+				data: "db",
+				sqlite: "db",
+				knowledge: "kb",
+				notes: "kb",
+				notebook: "kb",
+				helth: "doctor",
+				check: "doctor",
+				health: "doctor",
+				server: "webui",
+				dashboard: "webui",
+				ui: "webui",
+				timeline: "db",
+				"time-travel": "db",
+				workspace: "db",
+				obsidian: "db"
+			};
+			const input = String(group).toLowerCase();
+			const suggestions = [];
+			if (aliases[input]) suggestions.push(aliases[input]);
+			for (const [alias, cmd] of Object.entries(aliases)) if (alias.startsWith(input.slice(0, 4)) && !suggestions.includes(cmd)) {
+				suggestions.push(cmd);
+				break;
+			}
+			for (const k of known) if (k.startsWith(input.slice(0, 3)) && !suggestions.includes(k)) suggestions.push(k);
+			if (suggestions.length < 2) for (const k of known) {
+				if (suggestions.includes(k)) continue;
+				let ki = 0;
+				for (const ch of input) {
+					ki = k.indexOf(ch, ki);
+					if (ki === -1) break;
+					ki++;
+				}
+				if (ki !== -1) suggestions.push(k);
+				if (suggestions.length >= 3) break;
+			}
+			if (suggestions.length < 2) {
+				for (const k of known) if (k.includes(input) && !suggestions.includes(k)) suggestions.push(k);
+			}
+			if (suggestions.length === 1) bad(ctx, `unknown group: ${group} — did you mean "${suggestions[0]}"?`);
+			else if (suggestions.length > 1) bad(ctx, `unknown group: ${group} — did you mean: ${suggestions.slice(0, 3).join(" | ")}?`);
+			else bad(ctx, `unknown group: ${group}`);
+			out(ctx, paint(C.dim, "  try: ygl-trees (no args) for full usage", ctx.color));
 			if (!ctx.json) out(ctx, usage());
 			return 2;
 		}

package/dist/packages/core/text/src/fmt.js

@@ -72,20 +72,23 @@ function padEnd(s, width) {
     return gap > 0 ? s + " ".repeat(gap) : s;
 }
 /** Render rows as an aligned table (falls back to JSON when ctx.json). */
-function table(ctx, rows, headers, keys) {
+function table(ctx, rows, headers, keys, hint) {
     if (ctx.json) {
         console.log(JSON.stringify(rows, null, 2));
         return;
     }
     if (!rows.length) {
         out(ctx, paint(exports.C.dim, "  (empty)", ctx.color));
+        if (hint)
+            out(ctx, paint(exports.C.dim, `  → ${hint}`, ctx.color));
         return;
     }
     const cols = keys || Object.keys(rows[0]).filter((k) => !k.startsWith("_"));
     const hs = headers || cols;
-    const widthOf = (k) => Math.max(...rows.map((r) => dispWidth(String(r[k] ?? ""))));
+    const widthOf = (k) => Math.min(40, Math.max(...rows.map((r) => dispWidth(String(r[k] ?? "")))));
     const w = cols.map((k, i) => Math.max(dispWidth(hs[i] ?? ""), widthOf(k)));
-    const line = (cells) => cells.map((c, i) => padEnd(String(c), w[i])).join("  ");
+    const trunc = (s) => s.length > 40 ? s.slice(0, 39) + "…" : s;
+    const line = (cells) => cells.map((c, i) => padEnd(trunc(String(c)), w[i])).join("  ");
     out(ctx, paint(exports.C.bold, "  " + line(hs), ctx.color));
     out(ctx, paint(exports.C.dim, "  " + w.map((n) => "-".repeat(n)).join("  "), ctx.color));
     for (const r of rows)

package/dist/packages/knowledge/skills/src/cmds.js

@@ -135,7 +135,7 @@ function run(env, action, rest, args) {
                 "confidence",
                 "reuse",
                 "updated",
-            ]);
+            ], "kb add --title ... --body ... | kb import <dir>");
             return 0;
         case "rm":
         case "remove": {

package/dist/packages/knowledge/skills/src/skill-cmds.js

@@ -82,6 +82,70 @@ function run(env, action, rest, args) {
                 return 1;
             });
         }
+        case "init": {
+            // v2: create a new skill from template — guides the author
+            const name = String(args.flags.name || rest[0] || "");
+            if (!name) {
+                (0, fmt_1.bad)(ctx, "usage: skill init <name> [--description ...] [--body ...]");
+                (0, fmt_1.bad)(ctx, "  creates a skill with frontmatter template; edit body with skill show + update");
+                return 2;
+            }
+            const desc = String(args.flags.description || "");
+            const body = String(args.flags.body || `# ${name}
+
+## When to use
+(describe when this skill should activate)
+
+## What to do
+(step-by-step instructions)
+
+## Examples
+(concrete command examples)
+`);
+            const tags = String(args.flags.tags || "");
+            return (0, orm_1.getOrm)(env.db.path)
+                .then((ds) => writes.skillUpsert(ds, { name, description: desc, body, tags, version: "0.1.0" }))
+                .then((r) => {
+                (0, fmt_1.ok)(ctx, `skill created: ${name} v0.1.0`);
+                (0, fmt_1.out)(ctx, (0, fmt_1.paint)(fmt_1.C.dim, `  edit: ygl-trees skill show ${name}`, ctx.color));
+                (0, fmt_1.out)(ctx, (0, fmt_1.paint)(fmt_1.C.dim, `  add refs: ygl-trees skill refs add ${name} <path> --body "..."`, ctx.color));
+                return 0;
+            })
+                .catch((e) => {
+                (0, fmt_1.bad)(ctx, String(e?.message || e));
+                return 1;
+            });
+        }
+        case "refs":
+        case "references": {
+            // v2: show all references linked to a skill (L3 progressive disclosure)
+            const skillName = rest[0];
+            if (!skillName) {
+                (0, fmt_1.bad)(ctx, "usage: skill refs <name>");
+                return 2;
+            }
+            const sk = store.skillGet(skillName);
+            if (!sk) {
+                (0, fmt_1.bad)(ctx, `skill not found: ${skillName}`);
+                return 1;
+            }
+            const refs = env.db.all("SELECT * FROM skill_refs WHERE skill_id=? ORDER BY path", [sk.id]);
+            (0, fmt_1.head)(ctx, `Skill: ${skillName}`);
+            if (ctx.json) {
+                console.log(JSON.stringify(refs, null, 2));
+                return 0;
+            }
+            if (!refs.length) {
+                (0, fmt_1.out)(ctx, (0, fmt_1.paint)(fmt_1.C.dim, "  (no references — add with: skill refs add <name> <path> --body ...)", ctx.color));
+                return 0;
+            }
+            for (const r of refs) {
+                (0, fmt_1.out)(ctx, `  ${r.path}`);
+                if (r.body)
+                    (0, fmt_1.out)(ctx, (0, fmt_1.paint)(fmt_1.C.dim, `    ${String(r.body).slice(0, 80)}`, ctx.color));
+            }
+            return 0;
+        }
         case "add": {
             const n = args.flags.name ? String(args.flags.name) : "";
             const file = args.flags.f ? String(args.flags.f) : "";

package/dist/packages/ops/tools/src/agent-cmds.js

@@ -10,7 +10,7 @@ function buildBrief(env) {
     const { store } = env;
     const cur = store.db.metaGet("current_project");
     const stats = store.stats();
-    const skills = store.skillList().slice(0, 5);
+    const skills = store.skillList().slice(0, 5).map((sk) => ({ ...sk, description: String(sk.description || "").slice(0, 60) + (String(sk.description || "").length > 60 ? "…" : "") }));
     const notes = store.kbList().slice(0, 5);
     const payload = {
         workspace: env.home,
@@ -74,6 +74,68 @@ function buildBrief(env) {
 function run(env, action, rest, args) {
     const { ctx, store } = env;
     switch (action) {
+        case "ask":
+        case "?": {
+            // v2: natural language interface — keyword routing to other commands
+            const question = rest.join(" ");
+            if (!question) {
+                (0, fmt_1.bad)(ctx, 'usage: ygl-trees agent ask "<question>"');
+                (0, fmt_1.out)(ctx, '  examples: ask "what projects" | ask "search AI" | ask "健康"');
+                return 2;
+            }
+            const q = question.toLowerCase();
+            const routes = [
+                { pattern: /what.*project|项目列表|所有项目/, label: "project list", group: "project", action: "list" },
+                { pattern: /search|搜索|检索|找/, label: "kb search", group: "kb", action: "search",
+                    extra: [question.replace(/.*?(search|搜索|检索|找)\s*/i, "").replace(/["']/g, "")] },
+                { pattern: /tree|树/, label: "node list", group: "node", action: "list" },
+                { pattern: /health|健康|doctor|检查/, label: "doctor", group: "doctor", action: "" },
+                { pattern: /skill|技能/, label: "skill list", group: "skill", action: "list" },
+                { pattern: /task|任务/, label: "task list", group: "task", action: "list" },
+                { pattern: /metric|指标/, label: "agent metrics", group: "agent", action: "metrics" },
+            ];
+            let matched = false;
+            for (const r of routes) {
+                if (r.pattern.test(q)) {
+                    if (!ctx.json)
+                        (0, fmt_1.out)(ctx, (0, fmt_1.paint)(fmt_1.C.dim, `  → ${r.label}`, ctx.color));
+                    // F1 fix (a2a review): parent holds .ygllock → child self-deadlocks.
+                    // Fix: child gets YGL_TEST=1 to skip lock (parent already holds it —
+                    // no concurrent write risk for read-only routing).
+                    const cmdParts = [r.group, r.action, ...(r.extra || [])].filter(Boolean);
+                    const { execSync } = require("node:child_process");
+                    const self = process.argv[1];
+                    try {
+                        const result = execSync(`${JSON.stringify(process.execPath)} ${JSON.stringify(self)} --no-color ${cmdParts.map(c => JSON.stringify(c)).join(" ")}`, { env: { ...process.env, YGL_TEST: "1" }, encoding: "utf8", timeout: 10000 });
+                        // F2 fix: --json mode outputs only the inner result (contract ④)
+                        if (ctx.json) {
+                            console.log(result.trim());
+                            return 0;
+                        }
+                        (0, fmt_1.out)(ctx, result.trim());
+                        return 0;
+                    }
+                    catch (e) {
+                        if (ctx.json) {
+                            console.log(JSON.stringify({ error: String(e?.message || e).slice(0, 200) }));
+                            return 1;
+                        }
+                        (0, fmt_1.bad)(ctx, String(e?.stdout || e?.message || e).slice(0, 200));
+                        return 1;
+                    }
+                }
+            }
+            // Default: brief
+            if (!ctx.json)
+                (0, fmt_1.out)(ctx, (0, fmt_1.paint)(fmt_1.C.dim, "  → agent brief (no specific match)", ctx.color));
+            const payload = buildBrief(env);
+            if (ctx.json) {
+                console.log(JSON.stringify(payload, null, 2));
+                return 0;
+            }
+            // Reuse brief rendering
+            return run(env, "brief", [], args);
+        }
         case "metrics": {
             // R11 cold-start research → automated measurement. Health/efficiency
             // metrics for the workspace — one command answers "how good is this
@@ -150,7 +212,7 @@ function run(env, action, rest, args) {
             const payload = buildBrief(env);
             const cur = payload.current_project;
             const stats = payload.counts;
-            const skills = store.skillList().slice(0, 5);
+            const skills = store.skillList().slice(0, 5).map((sk) => ({ ...sk, description: String(sk.description || "").slice(0, 60) + (String(sk.description || "").length > 60 ? "…" : "") }));
             if (ctx.json) {
                 console.log(JSON.stringify(payload, null, 2));
                 return 0;

package/dist/packages/ops/tools/src/db-cmds.js

@@ -34,6 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.run = run;
+const path = __importStar(require("node:path"));
 const fs = __importStar(require("node:fs"));
 const fmt_1 = require("../../../core/text/src/fmt");
 const db_1 = require("../../../core/database/src/db");
@@ -132,6 +133,215 @@ function run(env, action, rest, args) {
             (0, fmt_1.show)(ctx, { file, size_kb: (fs.statSync(file).size / 1024).toFixed(1), ...s });
             return 0;
         }
+        case "time-travel": {
+            // v2: query workspace state at a past moment using entity created_at
+            const when = rest[0];
+            if (!when) {
+                (0, fmt_1.bad)(ctx, 'usage: db time-travel "YYYY-MM-DD HH:MM" (or "YYYY-MM-DD")');
+                return 2;
+            }
+            const ts = when.includes(" ") ? when : when + " 23:59:59";
+            const tables = ["projects", "sources", "evidence", "claims", "kb_notes", "skills", "trees", "nodes", "artifacts", "events"];
+            const counts = {};
+            for (const t of tables) {
+                try {
+                    const r = db.get(`SELECT COUNT(*) as n FROM ${t} WHERE created <= ?`, [ts]);
+                    counts[t] = r?.n || 0;
+                }
+                catch {
+                    counts[t] = 0;
+                }
+            }
+            // node unlock state at that time (via events)
+            let unlockedAt = 0;
+            try {
+                const r = db.get(`SELECT COUNT(DISTINCT entity_id) as n FROM events WHERE kind='node.unlock' AND ts <= ?`, [ts]);
+                unlockedAt = r?.n || 0;
+            }
+            catch { /* */ }
+            if (ctx.json) {
+                console.log(JSON.stringify({ timestamp: ts, counts, unlocked_nodes: unlockedAt }, null, 2));
+                return 0;
+            }
+            (0, fmt_1.head)(ctx, `Workspace at ${ts}`);
+            const labels = {
+                projects: "项目", sources: "来源", evidence: "证据", claims: "断言",
+                kb_notes: "知识", skills: "技能", trees: "树", nodes: "节点",
+                artifacts: "产出", events: "事件",
+            };
+            for (const [k, v] of Object.entries(counts)) {
+                (0, fmt_1.out)(ctx, `  ${String(labels[k] || k).padEnd(6)} ${String(v).padStart(5)}`);
+            }
+            (0, fmt_1.out)(ctx, `  已解锁  ${String(unlockedAt).padStart(5)}`);
+            return 0;
+        }
+        case "timeline": {
+            // v2: workspace growth timeline — events per day with entity milestones
+            const days = db.all(`
+        SELECT date(ts) as day, COUNT(*) as events,
+          SUM(CASE WHEN kind LIKE 'project%' THEN 1 ELSE 0 END) as projects,
+          SUM(CASE WHEN kind LIKE 'source%' THEN 1 ELSE 0 END) as sources,
+          SUM(CASE WHEN kind LIKE 'claim%' THEN 1 ELSE 0 END) as claims,
+          SUM(CASE WHEN kind LIKE 'kb%' THEN 1 ELSE 0 END) as kb,
+          SUM(CASE WHEN kind LIKE 'node%' THEN 1 ELSE 0 END) as nodes
+        FROM events GROUP BY date(ts) ORDER BY day
+      `);
+            if (!days.length) {
+                (0, fmt_1.ok)(ctx, "no events yet");
+                return 0;
+            }
+            // F2 fix: --json outputs pure JSON (frozen contract ④)
+            if (ctx.json) {
+                console.log(JSON.stringify({ timeline: days, total: days.reduce((s2, d) => s2 + d.events, 0) }, null, 2));
+                return 0;
+            }
+            const maxEvents = Math.max(...days.map(d => d.events));
+            (0, fmt_1.head)(ctx, "Workspace Timeline");
+            let totalP = 0, totalS = 0, totalC = 0, totalK = 0, totalN = 0;
+            for (const d of days) {
+                totalP += d.projects;
+                totalS += d.sources;
+                totalC += d.claims;
+                totalK += d.kb;
+                totalN += d.nodes;
+                const barLen = Math.round(d.events / maxEvents * 30);
+                const bar = "█".repeat(barLen);
+                const milestones = [];
+                if (d.projects > 0)
+                    milestones.push(`+${d.projects}项目`);
+                if (d.sources > 0)
+                    milestones.push(`+${d.sources}来源`);
+                if (d.claims > 0)
+                    milestones.push(`+${d.claims}断言`);
+                if (d.kb > 0)
+                    milestones.push(`+${d.kb}知识`);
+                if (d.nodes > 0)
+                    milestones.push(`+${d.nodes}节点`);
+                (0, fmt_1.out)(ctx, `  ${d.day} ${bar.padEnd(32)} ${String(d.events).padStart(5)} events  ${milestones.join(" ")}`);
+            }
+            (0, fmt_1.out)(ctx, "");
+            (0, fmt_1.out)(ctx, (0, fmt_1.paint)(fmt_1.C.dim, `  累计: ${totalP}项目 · ${totalS}来源 · ${totalC}断言 · ${totalK}知识 · ${totalN}节点变更`, ctx.color));
+            return 0;
+        }
+        case "workspace": {
+            // v2: multi-workspace management — each workspace is a YGL_HOME directory
+            const sub = rest[0] || "list";
+            const wsRoot = path.join(env.home, ".."); // parent of current workspace
+            if (sub === "list") {
+                const dirs = fs.existsSync(wsRoot) ? fs.readdirSync(wsRoot).filter((d) => fs.existsSync(path.join(wsRoot, d, "ygl-trees.db"))) : [];
+                const cur = path.basename(env.home);
+                (0, fmt_1.head)(ctx, "Workspaces (parent: " + wsRoot + ")");
+                for (const d of dirs) {
+                    (0, fmt_1.out)(ctx, (d === cur ? "  * " : "    ") + d);
+                }
+                (0, fmt_1.out)(ctx, "");
+                (0, fmt_1.out)(ctx, (0, fmt_1.paint)(fmt_1.C.dim, "  * = current | switch: YGL_HOME=<path> ygl-trees <cmd>", ctx.color));
+                return 0;
+            }
+            if (sub === "create") {
+                const name = rest[1];
+                if (!name) {
+                    (0, fmt_1.bad)(ctx, "usage: db workspace create <name>");
+                    return 2;
+                }
+                const dir = path.join(wsRoot, name);
+                if (fs.existsSync(path.join(dir, "ygl-trees.db"))) {
+                    (0, fmt_1.ok)(ctx, `workspace already exists: ${name}`);
+                    return 0;
+                }
+                fs.mkdirSync(dir, { recursive: true });
+                (0, fmt_1.ok)(ctx, `workspace created: ${dir}`);
+                (0, fmt_1.out)(ctx, (0, fmt_1.paint)(fmt_1.C.dim, `  init: YGL_HOME=${dir} ygl-trees db init`, ctx.color));
+                return 0;
+            }
+            (0, fmt_1.bad)(ctx, "usage: db workspace list | create <name>");
+            return 2;
+        }
+        case "obsidian": {
+            // v2 feature: export workspace as Obsidian-compatible markdown vault
+            const outDir = rest[0] || path.join(env.home, "obsidian-export");
+            fs.mkdirSync(path.join(outDir, "projects"), { recursive: true });
+            fs.mkdirSync(path.join(outDir, "knowledge"), { recursive: true });
+            fs.mkdirSync(path.join(outDir, "skills"), { recursive: true });
+            fs.mkdirSync(path.join(outDir, "trees"), { recursive: true });
+            fs.mkdirSync(path.join(outDir, "claims"), { recursive: true });
+            let count = 0;
+            const safe = (t) => String(t).replace(/[\/:*?"<>|]/g, "_").slice(0, 50);
+            for (const p of db.all("SELECT * FROM projects")) {
+                fs.writeFileSync(path.join(outDir, "projects", safe(p.name) + ".md"), `---
+type: project
+id: ${p.id}
+---
+
+# ${p.name}
+
+${p.question || ""}
+`);
+                count++;
+            }
+            for (const n of db.all("SELECT * FROM kb_notes")) {
+                fs.writeFileSync(path.join(outDir, "knowledge", safe(n.title) + ".md"), `---
+type: knowledge
+tags: ${n.tags || ""}
+confidence: ${n.confidence}
+---
+
+# ${n.title}
+
+${n.body}
+`);
+                count++;
+            }
+            for (const sk of db.all("SELECT * FROM skills WHERE enabled=1")) {
+                fs.writeFileSync(path.join(outDir, "skills", safe(sk.name) + ".md"), `---
+type: skill
+version: ${sk.version}
+---
+
+# ${sk.name}
+
+${String(sk.body).slice(0, 500)}
+`);
+                count++;
+            }
+            for (const t of db.all("SELECT * FROM trees")) {
+                const nodes = db.all("SELECT * FROM nodes WHERE tree_id=?", [t.id]);
+                let c = `---
+type: tree
+---
+
+# ${t.name} (${nodes.length} nodes)
+
+`;
+                for (const n of nodes)
+                    c += `- **${n.key}** (${n.kind}, tier ${n.tier})
+`;
+                fs.writeFileSync(path.join(outDir, "trees", safe(t.name) + ".md"), c);
+                count++;
+            }
+            for (const cl of db.all("SELECT * FROM claims")) {
+                const links = db.all("SELECT e.quote FROM claim_evidence ce JOIN evidence e ON ce.evidence_id=e.id WHERE ce.claim_id=?", [cl.id]);
+                let c2 = `---
+type: claim
+status: ${cl.status}
+confidence: ${cl.confidence}
+---
+
+# ${cl.id}
+
+${cl.text}
+
+## Evidence
+`;
+                for (const l of links)
+                    c2 += `- > ${String(l.quote).slice(0, 100)}
+`;
+                fs.writeFileSync(path.join(outDir, "claims", cl.id + ".md"), c2);
+                count++;
+            }
+            (0, fmt_1.ok)(ctx, `obsidian vault exported: ${count} files → ${outDir}`);
+            return 0;
+        }
         case "export": {
             const dest = rest[0] || `ygl-trees-dump-${Date.now()}.sql`;
             // --lean: skip derived-table data (node_closure / node_index are

package/llms.txt

@@ -1,4 +1,4 @@
-# ygl-trees v0.69.0 — AI Agent Research Workbench
+# ygl-trees v0.73.0 — AI Agent Research Workbench
 
 > Single SQLite source of truth. Research → Production → Knowledge Reuse + Tech Tree.
 > CLI for AI agents: every command supports --json (machine-readable, including errors).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ygl-trees",
-  "version": "0.71.0",
+  "version": "0.73.0",
   "description": "猿光 · 科技树 — database-centric CLI for research → production → knowledge reuse, built for AI agents.",
   "type": "commonjs",
   "main": "dist/apps/cli/index.js",
@@ -21,12 +21,12 @@
   "dependencies": {
     "@deepseek-ai/dsh-atomic-write": "0.0.1-rc.1",
     "better-sqlite3": "^13.0.3",
-    "node-sqlite3-wasm": "^0.8.60",
+    "node-sqlite3-wasm": "^0.8.61",
     "reflect-metadata": "^0.2.2",
     "typeorm": "^1.1.2",
     "@deepseek-ai/cordis": "~4.0.5-alpha.2",
-    "@deepseek-ai/cosmokit": "~1.8.6-alpha.2",
     "@deepseek-ai/cordis-plugin-timer": "~1.1.7-alpha.2",
+    "@deepseek-ai/cosmokit": "~1.8.6-alpha.2",
     "@deepseek-ai/schemastery": "~3.18.5-alpha.2"
   },
   "devDependencies": {