ygl-trees 0.72.0 → 0.74.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 0.74.0（2026-10-17）export-markdown + v2 测试 + 技能同步
+- **db export-markdown**：一键生成工作区 Markdown 报告（Summary/Projects/Claims/Knowledge/Trees）
+- **v2 功能测试**：6 项新单测覆盖 time-travel/timeline/workspace/obsidian/help-suggestions/llms-sections
+- **技能同步 v0.73.0**：quickstart/knowledge/research/techtree 全部更新到最新命令面
+- **141 单测**（+6）
+
+## 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/天 + 实体里程碑）

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

@@ -272,6 +272,23 @@ 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 || "");

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,84 @@ function run$12(env, action, rest, args) {
 			});
 			return 0;
 		}
+		case "export-markdown": {
+			const lines = [];
+			lines.push(`# ygl-trees Workspace Report`);
+			lines.push(`> Generated: ${(/* @__PURE__ */ new Date()).toISOString()}`);
+			lines.push("");
+			const counts = {};
+			for (const t of [
+				"projects",
+				"sources",
+				"evidence",
+				"claims",
+				"kb_notes",
+				"skills",
+				"trees",
+				"nodes",
+				"artifacts",
+				"events"
+			]) try {
+				counts[t] = db.get(`SELECT COUNT(*) as n FROM ${t}`)?.n || 0;
+			} catch {
+				counts[t] = 0;
+			}
+			lines.push(`## Summary`);
+			lines.push("");
+			lines.push(`| Entity | Count |`);
+			lines.push(`|---|---|`);
+			const labels = {
+				projects: "项目",
+				sources: "来源",
+				evidence: "证据",
+				claims: "断言",
+				kb_notes: "知识",
+				skills: "技能",
+				trees: "树",
+				nodes: "节点",
+				artifacts: "产出",
+				events: "事件"
+			};
+			for (const [k, v] of Object.entries(counts)) lines.push(`| ${labels[k] || k} | ${v} |`);
+			lines.push("");
+			lines.push(`## Projects`);
+			const projects = db.all("SELECT name, question, created FROM projects ORDER BY created DESC LIMIT 10");
+			for (const p of projects) lines.push(`- **${p.name}**: ${p.question || "(no question)"}`);
+			lines.push("");
+			lines.push(`## Recent Claims`);
+			const claims = db.all("SELECT text, status, confidence FROM claims ORDER BY created DESC LIMIT 10");
+			for (const c of claims) lines.push(`- [${c.status}] ${String(c.text).slice(0, 80)}... (${c.confidence})`);
+			lines.push("");
+			lines.push(`## Knowledge Notes`);
+			const kb = db.all("SELECT title, tags, confidence FROM kb_notes ORDER BY created DESC LIMIT 10");
+			for (const k of kb) lines.push(`- **${String(k.title).slice(0, 50)}** ${k.tags ? `(${k.tags})` : ""} [${k.confidence}]`);
+			lines.push("");
+			lines.push(`## Trees`);
+			const trees = db.all("SELECT name FROM trees");
+			for (const t of trees) {
+				const nodes = db.get("SELECT COUNT(*) as n FROM nodes WHERE tree_id=(SELECT id FROM trees WHERE name=?)", [t.name])?.n || 0;
+				lines.push(`- **${t.name}** (${nodes} nodes)`);
+			}
+			lines.push("");
+			lines.push(`---`);
+			lines.push(`*Auto-generated by ygl-trees db export-markdown*`);
+			const md = lines.join("\n");
+			const outPath = rest[0];
+			if (outPath) {
+				node_fs.writeFileSync(outPath, md);
+				ok(ctx, `markdown report saved: ${outPath} (${md.length} chars)`);
+			} else {
+				if (ctx.json) {
+					console.log(JSON.stringify({
+						markdown: md,
+						chars: md.length
+					}, null, 2));
+					return 0;
+				}
+				out(ctx, md);
+			}
+			return 0;
+		}
 		case "time-travel": {
 			const when = rest[0];
 			if (!when) {
@@ -4736,6 +4816,13 @@ function run$12(env, action, rest, args) {
 				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;
@@ -5495,7 +5582,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,
@@ -5619,13 +5709,25 @@ function run$9(env, action, rest, args) {
 				const { execSync } = require("node:child_process");
 				const self = process.argv[1];
 				try {
-					out(ctx, execSync(`${JSON.stringify(process.execPath)} ${JSON.stringify(self)} --no-color ${cmdParts.map((c) => JSON.stringify(c)).join(" ")}`, {
-						env: { ...process.env },
+					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
-					}).trim());
+					});
+					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;
 				}
@@ -5708,7 +5810,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;
@@ -8911,7 +9016,7 @@ function run$3(env, action, rest, args) {
 				"confidence",
 				"reuse",
 				"updated"
-			]);
+			], "kb add --title ... --body ... | kb import <dir>");
 			return 0;
 		case "rm":
 		case "remove": {
@@ -10792,6 +10897,22 @@ 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) {

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/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,
@@ -99,16 +99,27 @@ function run(env, action, rest, args) {
                 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));
-                    // Execute via CLI sub-process
+                    // 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 }, encoding: "utf8", timeout: 10000 });
+                        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;
                     }
@@ -201,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

@@ -133,6 +133,76 @@ 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 "export-markdown": {
+            // v2: auto-generated workspace report in markdown
+            const lines = [];
+            lines.push(`# ygl-trees Workspace Report`);
+            lines.push(`> Generated: ${new Date().toISOString()}`);
+            lines.push("");
+            // Metrics
+            const counts = {};
+            for (const t of ["projects", "sources", "evidence", "claims", "kb_notes", "skills", "trees", "nodes", "artifacts", "events"]) {
+                try {
+                    counts[t] = db.get(`SELECT COUNT(*) as n FROM ${t}`)?.n || 0;
+                }
+                catch {
+                    counts[t] = 0;
+                }
+            }
+            lines.push(`## Summary`);
+            lines.push("");
+            lines.push(`| Entity | Count |`);
+            lines.push(`|---|---|`);
+            const labels = { projects: "项目", sources: "来源", evidence: "证据", claims: "断言", kb_notes: "知识", skills: "技能", trees: "树", nodes: "节点", artifacts: "产出", events: "事件" };
+            for (const [k, v] of Object.entries(counts))
+                lines.push(`| ${labels[k] || k} | ${v} |`);
+            lines.push("");
+            // Projects
+            lines.push(`## Projects`);
+            const projects = db.all("SELECT name, question, created FROM projects ORDER BY created DESC LIMIT 10");
+            for (const p of projects) {
+                lines.push(`- **${p.name}**: ${p.question || "(no question)"}`);
+            }
+            lines.push("");
+            // Recent claims
+            lines.push(`## Recent Claims`);
+            const claims = db.all("SELECT text, status, confidence FROM claims ORDER BY created DESC LIMIT 10");
+            for (const c of claims) {
+                lines.push(`- [${c.status}] ${String(c.text).slice(0, 80)}... (${c.confidence})`);
+            }
+            lines.push("");
+            // Knowledge
+            lines.push(`## Knowledge Notes`);
+            const kb = db.all("SELECT title, tags, confidence FROM kb_notes ORDER BY created DESC LIMIT 10");
+            for (const k of kb) {
+                lines.push(`- **${String(k.title).slice(0, 50)}** ${k.tags ? `(${k.tags})` : ""} [${k.confidence}]`);
+            }
+            lines.push("");
+            // Trees
+            lines.push(`## Trees`);
+            const trees = db.all("SELECT name FROM trees");
+            for (const t of trees) {
+                const nodes = db.get("SELECT COUNT(*) as n FROM nodes WHERE tree_id=(SELECT id FROM trees WHERE name=?)", [t.name])?.n || 0;
+                lines.push(`- **${t.name}** (${nodes} nodes)`);
+            }
+            lines.push("");
+            lines.push(`---`);
+            lines.push(`*Auto-generated by ygl-trees db export-markdown*`);
+            const md = lines.join("\n");
+            const outPath = rest[0];
+            if (outPath) {
+                fs.writeFileSync(outPath, md);
+                (0, fmt_1.ok)(ctx, `markdown report saved: ${outPath} (${md.length} chars)`);
+            }
+            else {
+                if (ctx.json) {
+                    console.log(JSON.stringify({ markdown: md, chars: md.length }, null, 2));
+                    return 0;
+                }
+                (0, fmt_1.out)(ctx, md);
+            }
+            return 0;
+        }
         case "time-travel": {
             // v2: query workspace state at a past moment using entity created_at
             const when = rest[0];
@@ -190,6 +260,11 @@ function run(env, action, rest, args) {
                 (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;

package/llms.txt

@@ -1,4 +1,4 @@
-# ygl-trees v0.72.0 — AI Agent Research Workbench
+# ygl-trees v0.74.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.72.0",
+  "version": "0.74.0",
   "description": "猿光 · 科技树 — database-centric CLI for research → production → knowledge reuse, built for AI agents.",
   "type": "commonjs",
   "main": "dist/apps/cli/index.js",
@@ -25,8 +25,8 @@
     "reflect-metadata": "^0.2.2",
     "typeorm": "^1.1.2",
     "@deepseek-ai/cordis": "~4.0.5-alpha.2",
-    "@deepseek-ai/cordis-plugin-timer": "~1.1.7-alpha.2",
     "@deepseek-ai/schemastery": "~3.18.5-alpha.2",
+    "@deepseek-ai/cordis-plugin-timer": "~1.1.7-alpha.2",
     "@deepseek-ai/cosmokit": "~1.8.6-alpha.2"
   },
   "devDependencies": {