ygl-trees 0.72.0 → 0.73.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # 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/天 + 实体里程碑）

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] ?? ""))));
@@ -4736,6 +4738,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 +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,
@@ -5619,13 +5631,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 +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;
@@ -8911,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": {
@@ -10792,6 +10819,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

@@ -190,6 +190,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.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.72.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",
@@ -26,8 +26,8 @@
     "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/cosmokit": "~1.8.6-alpha.2"
+    "@deepseek-ai/cosmokit": "~1.8.6-alpha.2",
+    "@deepseek-ai/schemastery": "~3.18.5-alpha.2"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",