ygl-trees 0.73.0 → 0.75.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.75.0（2026-10-17）npm 包修复——skills/ 进 tarball + 乱码修复 + fail-loud
+- **修复（P0）**：npm tarball 现在包含 skills/ 目录——9 个内置技能随包分发，db init 的 "auto-imported" 承诺兑现
+- **修复**：autoImportBuiltinSkills 找不到技能时不再静默返回 0——显式警告 "skills/ directory not found"
+- **修复**：Linux 管道/重定向输出乱码——ANSI 颜色严格检测（isTTY===true 才开色）+ NO_COLOR/FORCE_COLOR 环境变量支持
+- files 字段：dist + ygl.bundle.json + README + docs + CHANGELOG + llms.txt + **skills/**
+
+## 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）

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

@@ -251,7 +251,16 @@ async function main(argv) {
     const args = (0, types_1.parse)(argv);
     const ctx = {
         json: (0, types_1.bool)(args, "json"),
-        color: !(0, types_1.bool)(args, "no-color") && process.stdout.isTTY !== false,
+        // Color detection (strict): colors ONLY when we're sure the terminal
+        // supports ANSI. Fixes Linux garbled output when piped/redirected.
+        //   --no-color flag → always off
+        //   NO_COLOR env → off (https://no-color.org convention)
+        //   FORCE_COLOR env → always on (override for exotic terminals)
+        //   isTTY === true → on (real terminal)
+        //   isTTY === false/undefined → off (pipe, redirect, cron, etc.)
+        color: !(0, types_1.bool)(args, "no-color") &&
+            process.env.NO_COLOR === undefined &&
+            (process.env.FORCE_COLOR !== undefined || process.stdout.isTTY === true),
         quiet: (0, types_1.bool)(args, "quiet"),
     };
     const group = args._[0];

package/dist/bundle/bin.cjs

@@ -4670,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) {
@@ -10809,7 +10887,7 @@ async function main(argv) {
 	const args = parse(argv);
 	const ctx = {
 		json: bool(args, "json"),
-		color: !bool(args, "no-color") && process.stdout.isTTY !== false,
+		color: !bool(args, "no-color") && process.env.NO_COLOR === void 0 && (process.env.FORCE_COLOR !== void 0 || process.stdout.isTTY === true),
 		quiet: bool(args, "quiet")
 	};
 	const group = args._[0];

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

@@ -60,8 +60,17 @@ async function autoImportBuiltinSkills(env, dbFile) {
             }
         }
     }
-    if (!skillsDir)
+    if (!skillsDir) {
+        // Fail-loud (was silent return 0): the npm package MUST ship skills/ —
+        // if we can't find them, the user deserves to know why agent match
+        // returns nothing. This is a packaging bug indicator, not a valid state.
+        const { out: outFn, paint: paintFn, C: Cf } = require("../../../core/text/src/fmt");
+        if (env.ctx && !env.ctx.json) {
+            outFn(env.ctx, paintFn(Cf.yellow, "  ! built-in skills: 0 found (skills/ not shipped or not in package)", env.ctx.color));
+            outFn(env.ctx, paintFn(Cf.dim, "    this is a packaging bug — skills/ should be in the npm tarball", env.ctx.color));
+        }
         return 0;
+    }
     const { getOrm } = require("../../../core/database/src/orm");
     const writes = require("../../../research/pipeline/src/writes");
     const { parseFrontmatter } = require("../../../core/text/src/text");
@@ -108,6 +117,8 @@ function run(env, action, rest, args) {
             autoImportBuiltinSkills(env, file).then(async (n) => {
                 if (n > 0)
                     (0, fmt_1.ok)(ctx, `built-in skills:  ${n} imported (agent match ready)`);
+                else
+                    warn(ctx, "built-in skills:  0 imported — skills/ directory not found in package");
                 // Release the ORM connection so the lock doesn't linger
                 try {
                     const { closeOrm } = require("../../../core/database/src/orm");
@@ -133,6 +144,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];

package/llms.txt

@@ -1,4 +1,4 @@
-# ygl-trees v0.73.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.73.0",
+  "version": "0.75.0",
   "description": "猿光 · 科技树 — database-centric CLI for research → production → knowledge reuse, built for AI agents.",
   "type": "commonjs",
   "main": "dist/apps/cli/index.js",
@@ -13,7 +13,8 @@
     "README.md",
     "docs",
     "CHANGELOG.md",
-    "llms.txt"
+    "llms.txt",
+    "skills"
   ],
   "engines": {
     "node": ">=18"
@@ -26,8 +27,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/cosmokit": "~1.8.6-alpha.2",
-    "@deepseek-ai/schemastery": "~3.18.5-alpha.2"
+    "@deepseek-ai/schemastery": "~3.18.5-alpha.2",
+    "@deepseek-ai/cosmokit": "~1.8.6-alpha.2"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",

package/skills/ygl-trees-design-capture/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: ygl-trees-design-capture
+description: >-
+  ygl-trees design 捕获方法论（spec R12/R13.2）：三类 design 工件的捕获法——ui-ux 用 DESIGN.md
+  格式（google-labs-code：YAML tokens + rationale 节序 + lint 工具链）；arch/decision 用 ADR
+  三段（上下文/决策/后果）。produce design 命令 + design_type 信封 + rel 挂节点 + DESIGN.md
+  单一事实源纪律。触发词：design 捕获、设计决策、ADR、DESIGN.md、ui-ux、架构决策、
+  design_type、produce design、设计沉淀。
+version: 0.33.0
+tags: ygl-trees,methodology,design,adr,design-md
+---
+
+# Design 捕获方法论：三类工件三种写法
+
+## 1. 分型（用户裁定 2026-10-17）
+
+| design_type | 格式 | 工具链 |
+|---|---|---|
+| `ui-ux` | **DESIGN.md 格式**（[google-labs-code/design.md](https://github.com/google-labs-code/design.md)） | `npx -p @google/design.md designmd lint`（Windows 别名） |
+| `arch` | ADR 三段：上下文/决策/后果 | 无（Markdown 纪律） |
+| `decision` | ADR 三段（单点决策，比 arch 更小） | 无 |
+
+## 2. ui-ux：DESIGN.md 格式要点
+
+- **YAML front matter**（机器可读 tokens）：colors / typography / rounded / spacing / components（`{colors.primary}` 引用）
+- **节序固定**：Overview → Colors → Typography → Layout → Elevation → Shapes → Components → Do's and Don'ts
+- **lint 十一规则**：broken-ref(error) / contrast-ratio(WCAG AA) / orphaned-tokens / section-order…
+- 组件属性面有限（backgroundColor/textColor/typography/rounded/padding/size/height/width）——border 色等页级 token 会 orphan 警告，属格式 alpha 限制
+- **仓库纪律**：repo 根 `DESIGN.md` 是 WebUI token 单一事实源；`apps/web/src/tokens.css` 镜像它——改设计先改 DESIGN.md 再同步
+
+## 3. arch / decision：ADR 三段
+
+```markdown
+# <决策标题>
+## 上下文   （ Forces：约束、备选、为什么现在决定 ）
+## 决策     （ Chosen：一句话可执行的裁定 + 触发条件 ）
+## 后果     （ Consequences：正/负/中立，含推迟项 ）
+```
+
+判例参考本仓：WAL+NORMAL 双连接（docs/conventions.md §五）、Bun Windows 受阻（docs/bun-compat.md）。
+
+## 4. 捕获命令与挂接
+
+```bash
+ygl-trees produce design "<标题>" --design-type ui-ux|arch|decision --body|-f <file>
+ygl-trees rel add node:<tree>/<key> artifact:<id> --rel decided-by   # 挂到树
+```
+
+design_type 存 artifacts.meta JSON 信封（schema v8）；`produce list` 可按 kind 检索。
+
+## 5. 纪律
+
+- 设计先有 token 再有像素：ui-ux 捕获若引入新色/新字号，先改 DESIGN.md 并 lint 0 error
+- ADR 的"后果"必须含推迟项（没有推迟项的 ADR 多半没想清代价）
+- 每条 design 都应 `decided-by` 挂到 evolution 树的对应节点——设计孤岛 = 没捕获

package/skills/ygl-trees-eval-gates/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: ygl-trees-eval-gates
+description: >-
+  ygl-trees 决策模型门槛（spec R8）：语义型必检条件用 eval 题型声明——布尔 --op eval 判 P(true)、
+  多选一 --op eval-choice 判期望答案概率、等级评分 --op eval-score 判 ±1 灰带；node can --eval
+  把节点上下文包（父链+祖先链+条件+解锁集+state 袋）交给评估模型（TypeSafe jev via Vercel
+  AI Gateway）。三态映射 P≥0.7 通过 / P≤0.4 未通过 / 灰带 pending。离线安全：无凭证回落 pending。
+  触发词：决策模型、布尔判定、多选、评分、evaluation、P(true)、灰带、gray band、pending、
+  eval gate、语义门槛、quest 条件、AI 判定、jev、gateway、choice、score。
+version: 0.26.0
+tags: ygl-trees,eval,gate,decision-model,choice,score
+---
+
+# Gate 决策模型评估（boolean / choice / score）
+
+## 1. 何时用
+
+确定性条件（等级≥3、资源≥100、flag 有无）用普通 op（>=/==/has…），本地判定。
+**语义型门槛**——"前置任务完成了吗""情境是否满足"——状态袋里没有对应键，用 eval 题型：
+value 写判定问题（与上下文字面对齐，模型严格按字面读、不脑补；空 value 回落用条件名）。
+
+## 2. 三种题型
+
+```bash
+# 布尔：P(true) 三态
+ygl-trees node cond gate-node --name quest_done --kind quest --op eval \
+           --value "前置任务已完成且上下文满足门槛吗"
+
+# 多选一：期望答案的概率走同一三态（0.26.0）
+ygl-trees node cond gate-node --name team_pick --kind quest --op eval-choice \
+           --value "该派哪个团队处理" \
+           --options "proc=采购:ERP与供应商, ops=物流:账单核对" --answer proc
+
+# 等级评分：score∈[0,N-1] 概率加权均值，±1 灰带（0.26.0）
+ygl-trees node cond gate-node --name maturity --kind quest --op eval-score \
+           --value "实现成熟度如何" \
+           --levels "原型:仅演示, 可用:有测试, 成熟:有用户" --min-score 2
+
+ygl-trees node can gate-node --state x=1 --eval
+ygl-trees node can gate-node --eval --json     # evaluated[] 带 type 字段 + pending[]
+```
+
+选择/评分题面纪律（材料 §3）：选项/等级描述必须编码业务价值排序（裸用"轻微/中等/严重"
+与价值观系统性分歧，实测 ρ=0.25）；等级描述带 P0/节奏等语境词。
+
+## 3. 三态语义（材料纪律）
+
+| 题型 | 判定量 | pass | fail | pending |
+|---|---|---|---|---|
+| boolean | P(true) | ≥0.7 | ≤0.4 | 0.4–0.7 灰带 |
+| choice | P(期望答案) | ≥0.7 | ≤0.4 | 0.4–0.7 灰带 |
+| score | score | ≥min | ≤min−1 | [min−1, min) 灰带 |
+
+聚合行为：pass 从 missing_required 移除；fail 保留并标注；**pending 独立泳道——不放行、
+不报错、禁作终态**。
+
+实测谱系（真实网关 1.5s/次）：可证事实 P=0.97 / 未满足前提 P=0.39 / 歧义上下文 P=0.45——
+证据不足时概率塌向灰带而非硬答。
+
+## 4. 上下文包（模型看到什么）
+
+节点元数据（key/name/kind/tier/cost）+ 直接父（node_edges）+ 祖先链（node_closure）+
+该节点全部条件 + 已解锁集 + `--state` 袋。**state 必带上下文包**——裸 state 大概率落灰带。
+
+## 5. 凭证与端点（优先级：config > 环境变量/文件 > 默认网关）
+
+- **config 优先**：`ygl-trees config set decision_model_llm_token <t>` 与
+  `config set decision_model_llm_api_base <url>`（api_base 给主机名自动补
+  `/v4/ai/evaluation-model`，也可给完整端点——代理/自托管网关用它接管）
+- 回落：环境变量 `AI_GATEWAY_API_KEY` → `~/.vercel.ai-gateway.env`（`token=...`，vck_ 前缀）
+- **离线安全**：无 token/网络失败 → 该条件 pending（`no evaluator configured`）、rc=0——
+  评估器是增强不是依赖，别把 pending 当失败重试
+- `YGL_EVAL_OFFLINE=1` 强制离线（测试/demo 确定性；优先于 config 的 eval.offline）
+- 网关协议：v4 端点 + 四个协议头（缺一 400/404）；429/529 自动退避重试≤3，400/401 不重试
+
+## 6. 批量判定与留痕
+
+`node ready --eval`（0.16.0）：仅被 eval 门槛阻塞的节点逐节点**一次多题请求**（协议原生
+批量，同延迟）判定——全过提升进 ready（`eval_verified` 标记），其余进 `eval_pending`
+（逐题带 P）；离线全 pending、rc=0。
+
+每次 `--eval` 记 events：单节点 `eval.gate`（各条件 P/outcome）、批量 `eval.ready`
+（promoted/pending 键集），`agent log` 可审计。结果不落库——现评现判，保持无状态。

package/skills/ygl-trees-knowledge/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: ygl-trees-knowledge
+description: >-
+  ygl-trees 知识复用闭环：kb 笔记（add/import 批量 markdown/search 中文检索带标题加权/
+  link/ingest 报告入库）、promote 笔记提升为可复用 skill（L1/L2/L3 渐进披露）、agent match
+  技能命中。让研究报告沉淀为可被下次任务自动命中的技能。
+  触发词：知识库、knowledge、kb、笔记、note、批量导入、import、search、检索、promote、
+  技能、skill、复用、agent match。
+version: 0.61.0
+tags: ygl-trees,knowledge,kb,skill,reuse
+---
+
+# 知识复用闭环：报告 → 笔记 → skill → 自动命中
+
+## 1. 入库
+
+```bash
+ygl-trees kb ingest <reportId>                 # 报告入库
+ygl-trees kb add --title "..." --body "..." [--tags a,b]
+ygl-trees kb import <dir|file.md>              # 递归批量导入 markdown（frontmatter:
+                                               # title/tags/confidence/url；# 标题或文件名回退；
+                                               # 单事务批量，2189 条 <1s；内容 hash 幂等）
+ygl-trees kb link <a> <b> --rel related
+```
+
+## 2. 检索（中文原生）
+
+```bash
+ygl-trees kb rm <id>
+db obsidian [dir]（导出为 Obsidian vault）（删除笔记）
+kb search（--eval 语义重排：决策模型逐条评估相关性） "闭包表 索引"
+```
+
+排序语义：命中 token 数降序 → **标题含 token 优先** → bm25。写查询词时把最独特的关键词
+放进去；返回字段含 title_matched（标题命中数）。
+
+## 3. 提升为 skill（L1/L2/L3 渐进披露）
+
+```bash
+ygl-trees kb promote <noteId> --name my-skill   # L1 描述自动从正文提炼（含来源标注）
+ygl-trees skill refs add my-skill docs/x.md --body "..."   # L3 按需引用
+ygl-trees agent match "我要做 X 任务"           # Agent 靠 L1 命中技能
+```
+
+- L1 description 常驻上下文（做什么+何时触发+同义词），L2 body 激活才加载
+- 好的 L1 决定命中率：写清触发词；promote 的自动提炼已含来源标注
+- `skill import <SKILL.md>` 可直接导入带 frontmatter 的技能文件
+
+## 4. 闭环使用姿势
+
+任务开始 → `agent brief` + `agent match "<任务描述>"` → 命中则 `skill show <name>` 读 L2 →
+按 L2 干活；任务结束 → 产出报告 → `kb ingest` → 有复用价值就 `kb promote`。
+每命中一次 `hits+1`，热门技能自然浮出。

package/skills/ygl-trees-lifecycle/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: ygl-trees-lifecycle
+description: >-
+  ygl-trees 更新时机与维护节奏（何时动数据，而非怎么动）：事件→动作触发表——树侧（何时
+  node unlock / add / link / cond / index）、研究资产侧（何时 source / evidence / claim /
+  resolve / kb / promote / task / produce / rel）；节奏纪律（改结构后必 index+validate、
+  解锁后必挂证据、会话收口前必 brief+doctor、周期性 export 备份）；该不该动的判定口诀；
+  漂移反模式。机制细节见各专职技能，本技能只回答「什么时候」。
+  触发词：更新时机、什么时候更新、何时解锁、何时该动、何时挂、维护、节奏、cadence、
+  keep in sync、同步、漂移、stale、脏索引、收口、会话结束、下次做什么、lifecycle。
+version: 0.42.0
+tags: ygl-trees,lifecycle,cadence,maintenance,timing
+---
+
+# ygl-trees 更新时机与维护节奏
+
+专职技能回答「**怎么动**」（命令机制）与「**动成什么样**」（方法论）。本技能只回答
+「**什么时候动**」——这是 agent 用这套工具时最容易漏的一层：机制全会，却在该动的时刻不动，
+于是树和研究变成两条各自漂移的流水线。
+
+## 0. 核心判据：什么时候必须动
+
+三条铁律，任何一条成立就必须落库（不是"记在心里"）：
+
+1. **状态变了** → 落库。能力达成、判断成形、任务推进、结构改变，都必须在**同一轮工作内**写下去；
+   下一轮会话只读得到库里的东西，脑内状态等于不存在。
+2. **结构变了** → 立刻重建索引。任何 `node add/link/rm` 之后：`node index`（闭包+拓扑）+ `node validate`（环/悬空/脏索引）。
+3. **写了判断** → 同轮挂证据。`node`/`claim`/`design` 出来后，`rel` 把依据挂上；没有证据的节点是待验证假设，
+   不是结论。
+
+## 1. 事件 → 动作触发表（树侧）
+
+| 触发事件 | 立刻做 | 别做 |
+|---|---|---|
+| 一个里程碑/能力**真正达成**（有可指认的证据） | `node unlock <key>` + `rel add node:<key> evidence:<id>` | 只在心里认为"算做到了"，不 unlock |
+| 发现领域里还有**未建模的子能力** | `node add <child>` + `node link <parent> <child>`（先判定必检 or `--optional`） | 用 payload/备注描述层级关系（关系必须进 `node_edges`） |
+| 发现两条路线**互斥** | `node link a b --rel excludes --mode NOT`（或同父 XOR） | 靠文档写"这两个不能同时选" |
+| 出现**语义门槛**（"做到 X 才算过"，无客观阈值） | `node cond <key> --op eval --value "<判定问题>"`（判据题型见 eval-gates 技能） | 把主观判断硬凑成 `kind=level --value 3` |
+| 依赖**方向变了** | 先加新边 → `node index` → `node validate` → 再 `node unlink <parent> <child>`；**两次索引之间不要跨会话** | 直接删旧边（中间态可能成环，validate 会拦但状态已脏） |
+| 同一能力被**重新拆解** | 新节点先建、挂到父、`node index` 通过后再 `node unlink` 下线旧边 | 先删后建（树上出现空洞，后续会话看到断裂） |
+| 重复 `node link` 同一 (父,子,rel) | 幂等：原地更新并回执 `duplicate: true`（rc=0），**改 `--mode/--optional` 重连即改属性** | 以为重复 link 会新建边而反复确认（不会） |
+| 改了 tier/cost/kind 等**定义** | 一般无需重建索引；改的是 `node_state` 才需要留意 | 把定义改动误当结构改动而反复 index（无害但浪费） |
+| **解锁判定被质疑** | `node can <key> --state ...` 复算，看 `missing_required` / `blocked_by` / `cost_multiplier` | 凭印象回答"应该能解锁了" |
+
+## 2. 事件 → 动作触发表（研究资产侧）
+
+| 触发事件 | 立刻做 |
+|---|---|
+| 开始一个新研究问题 | `project new <name> -q "<question>"`（选定）；拆出的检索式 `research query add "<text>"` |
+| 找到外部依据（网页/文档/记录） | `source add`（`--url`/`--title`）；由检索式找回的额外 `query attach <qid> <sid>` |
+| 从原文里看到**关键句** | `evidence add <sid> --quote "..."`（**quote 必须是原文**，`--note` 放你的解读） |
+| 形成**一个可被反驳的判断** | `claim add "<text>"` + `claim link <cid> <eid> [--stance supports|refutes]` |
+| 判断**稳定下来**（支持/反对够了） | `claim resolve <cid> --as supported|refuted|contested`（人工仲裁，模型不代替） |
+| 需要**可交付结论** | `produce outline` → `section` → `report`（或 `export` 落盘） |
+| 需要**固化需求/设计** | `produce spec`；设计用 `produce design --design-type ui-ux|arch|decision` |
+| 出现**可复用知识**（换任务还有用） | `kb add` / `kb ingest <artifactId>`；成模式再 `promote <note>` 成 skill |
+| 出现**行动项** | `task add "<title>"` → `task doing <id>` → `task done <id>`（不建 task 的"待办"只活在本轮上下文） |
+| 资产与树节点**有关系了** | `rel add node:<key> <type>:<ref> --rel <词>`（词汇表与"何时挂"决策树见 relating 技能） |
+
+## 3. 节奏纪律（cadence）
+
+| 时机 | 必做 |
+|---|---|
+| **每轮会话开场** | `agent brief`（我在哪、有什么、下一步）→ 有 `next_actions` 就照做 |
+| **每轮会话收口前** | `doctor`（9 项）；有脏索引/重复/孤儿按其提示修；`node index` 若结构动过 |
+| **改树结构后**（同一轮内） | `node index` + `node validate`——**绝不留到下一轮** |
+| **解锁任何节点后** | 同轮 `rel` 挂依据；否则验尸时无法回答"凭什么解锁" |
+| **claim 状态变化后** | 建议 `produce report` 重生成（报告是状态的投影，不是手写副本） |
+| **一轮工作有结论** | `kb add` 沉淀；结论若与树相关，`rel` 双向挂上 |
+| **长时间未动（跨多轮）** | `agent brief` + `doctor` 先对账，再决定动不动树（避免基于过期认知改结构） |
+| **周期性**（可选） | `job add ... --every <min>` + `job tick`（cron 驱动）；`db export <file.sql>` 做完整备份 |
+| **结构性风险动作前**（批量 import、大批节点改写） | 先 `db export` 备份——`db import` 的替换语义会整表重写 |
+
+## 4. 该不该动：五个自问
+
+1. **这个状态换一个会话还成立吗？** 只有库里写着的成立 → 要落库。
+2. **这条边/条件是必检还是可选？** 答不出就别建——必检会阻塞解锁，可选只影响提示与折扣，语义不同。
+3. **这个节点有依据吗？** 没有就先补 `rel` 或把它降级为假设（不 unlock）。
+4. **改完索引还干净吗？** 不确定就跑 `node index && node validate`。
+5. **这属于"我在想"还是"已发生"？** 前者写 `--note`/`payload`，后者才 `unlock`/`resolve`/`done`。
+
+## 5. 反模式（漂移的六种长相）
+
+1. **心内解锁**：能力做完了但不 `node unlock`，下次会话看树仍以为没做到 → 重复劳动或误判前置。
+2. **裸节点**：`node add` 后从不挂 `evidence`/`claim` → 树退化成一厢情愿的愿望清单。
+3. **结构改了不重建**：`node link` 后跳过 `node index` → `can/ready/path` 按旧闭包回答，结论全错。
+4. **先删后建**：重构节点时不保留中间态 → 树出现断裂空洞，漂移期内的判断无法回溯。
+5. **状态在正文里**：把"已完成/已验证"写进 `--note` 而不是 `unlock`/`resolve` → 机器读不到，投影（报告/仪表盘）全失真。
+6. **研究资产不挂树**：evidence/claim/kb 散落在研究侧，树侧只有节点名 → 两条流水线各自演进，`rel` 就是为了防这个。
+
+## 6. 与专职技能的分工
+
+| 要回答的问题 | 去哪 |
+|---|---|
+| 什么时候动（本技能） | 这里——触发表 §1/§2、节奏 §3、判定 §4、反模式 §5 |
+| 命令怎么用 | `ygl-trees-techtree`（树机制）、`ygl-trees-research`（研究管线）、`ygl-trees-knowledge`（kb/skill） |
+| 树该长成什么样 | `ygl-trees-tree-building`（分解法、tier 语义、≥30 节点自检） |
+| 该挂什么关系 | `ygl-trees-relating`（rel 词汇表 + 何时挂决策树） |
+| 语义门槛怎么判 | `ygl-trees-eval-gates`（三题型、灰带、离线安全） |
+| 设计怎么沉淀 | `ygl-trees-design-capture`（DESIGN.md / ADR） |
+| 全局契约与入口 | `ygl-trees-quickstart` |

package/skills/ygl-trees-quickstart/SKILL.md

@@ -0,0 +1,171 @@
+---
+name: ygl-trees-quickstart
+description: >-
+  ygl-trees 工作台快速上手与全局契约：初始化（db init）、研究项目（project new）、
+  agent brief 定位下一步、--json 纯净纪律与退出码契约、健康检查（doctor）、
+  任务清单（task）、关联织物（rel）、用户插件（plugin install）、WebUI（webui serve）、
+  备份导出（db export）、PG 镜像/迁移、调度（job add/tick）、性能基准（pnpm bench）、
+  bundle 构建（build:bundle）、临时文件 tmp/ 规范。
+  触发词：ygl-trees 入门、初始化、quickstart、工作区、退出码、exit code、备份、export、
+  PostgreSQL、sync、migrate、镜像、job、tick、定时、doctor、健康检查、任务、task、
+  关联、rel、插件、plugin、WebUI、webui、仪表盘、dashboard、bench、基准、bundle。
+version: 0.73.0
+tags: ygl-trees,quickstart,backup,postgres,schedule,doctor,plugin,webui,bench
+---
+
+# ygl-trees 快速上手与全局契约
+
+单一 SQLite 文件是唯一事实源；PostgreSQL 只做单向导出。所有命令支持 `--json`。
+
+## 1. 冷启动三步
+
+```bash
+node dist/apps/cli/src/bin.js db init           # 建工作区（$YGL_HOME，默认 ~/.ygl-trees）
+node dist/apps/cli/src/bin.js project new <name> -q "<研究问题>"
+node dist/apps/cli/src/bin.js agent brief       # 我在哪、有什么、下一步做什么（从这里开始）
+```
+
+## 2. Agent API 契约（冻结，勿靠猜）
+
+- **退出码**：`0` 成功（含"重复已存在"）、`1` 运行错误/404、`2` 用法错误
+- **--json 纯净**：写 = 单个 JSON 对象（重复带 `duplicate: true`）；读 = 数组/对象
+- **写入幂等**：claim/evidence/query/kb/job 按内容 hash 判重；`--force` 显式保留重复
+- 输出字段名是冻结契约，snake_case
+
+## 2a. 技能发现（Agent 一键连接）
+
+```bash
+ygl-trees skill link              # 连接到 ./.agents/skills/（DSH/Claude 等 Agent 即刻可发现）
+ygl-trees skill link --global    # 连接到 ~/.agents/skills/（全局）
+```
+
+## 2a. v2 新命令（0.72+）
+
+```bash
+ygl-trees agent ask "<问题>"       # 自然语言路由（projects/search/tree/health/...）
+ygl-trees db time-travel "日期"    # 查询过去某时刻的工作区状态
+ygl-trees db timeline              # 增长时间线（events/天+里程碑）
+ygl-trees db workspace list        # 多工作区管理
+ygl-trees db obsidian [dir]        # 导出 Obsidian markdown vault
+ygl-trees skill init <name>        # 模板创建技能
+ygl-trees skill refs <name>        # 技能引用展示
+ygl-trees llms --section <name>    # 能力清单节选
+ygl-trees llms --json              # 结构化 JSON
+```
+
+## 2b. 运维命令速查
+
+```bash
+ygl-trees doctor           # 9 项健康检查
+ygl-trees doctor --fix     # 一键安全修复（脏索引标记 + 陈旧锁清理）
+ygl-trees kb rm <id>       # 删除笔记（与 skill rm 对称）
+ygl-trees webui serve --host 0.0.0.0 --port 8642  # LAN/WSL 可访问
+```
+
+PG 迁移预检：`db migrate pg` 前自动逐表扫描 INTEGER 列类型——非整数值会**点名 table.column rowid=N** 而非迁移时才爆。
+
+## 2c. DB 锁行为（0.68）
+
+- CLI 短命令：进程级锁（保护写窗口，退出自动释放）
+- webui serve：无锁（WAL 并发安全，与 CLI 共存）
+- 死锁自愈：下一进程探测持有者 PID，死则即时清（无需手动 rmdir）
+- YGL_TEST=1：全旁路（测试并行）
+
+## 3. 健康检查与任务
+
+```bash
+ygl-trees doctor                     # 9 项健康检查（schema/索引/FTS/重复/孤儿/config/锁/eval信封/插件）
+ygl-trees task add "<标题>"           # 建任务（todo 起步）
+ygl-trees task list                  # 按状态分组
+ygl-trees task done <id>             # 勾销（全程留痕）
+```
+
+## 4. 关联织物（把研究资产挂到树节点）
+
+```bash
+ygl-trees rel add node:<tree>/<key> claim:<id> --rel decided-by
+ygl-trees rel add node:<key> kb:<id> --rel evidenced-by
+ygl-trees rel add node:<key> artifact:<id> --rel tracked-by
+ygl-trees rel list --src node:<key>  # 双向过滤 + 对端显示名
+```
+
+八类引用：`node claim evidence source query kb artifact skill`。
+详细方法论见 `ygl-trees-relating` 技能。
+
+## 5. 用户插件（业务域扩展位）
+
+```bash
+ygl-trees plugin init                          # 建 $YGL_HOME/plugins profile
+ygl-trees plugin install <npm包|git地址|本地目录> # 本地目录自动 link:
+ygl-trees plugin list                          # 版本 / spec / 可解析态
+ygl-trees plugin remove <name>
+```
+
+插件契约：`export apply(ctx, config)` + 可选 `export commands = { <组名>: { run } }`
+贡献 CLI 命令组。编写指南：`docs/plugin-authoring.md`。示例：`examples/plugin-demo/`。
+
+## 6. WebUI
+
+```bash
+ygl-trees webui serve --port 8642   # React 客户端（xyflow 树 + 时间轴 + 产出渲染）
+ygl-trees webui export --out d.html # 零依赖单文件导出（离线可开）
+```
+
+构建 React 客户端：`pnpm --filter @ygl/web build`。设计系统：仓库根 `DESIGN.md`。
+
+## 7. 备份 / PostgreSQL / 调度
+
+```bash
+ygl-trees db export <file.sql>          # 全部数据表 + 行数摘要
+ygl-trees db sync pg <url>              # 可刷新 PK-only 镜像
+ygl-trees db migrate pg <url> [--fresh] # 一次性完整保真迁移
+ygl-trees job add <title> -- "<cmd>" --every 60   # cron 每分钟跑 job tick
+```
+
+禁止双后端同写：ygl-trees 永远只写 SQLite，PG 是单向出口。
+
+## 8. 性能基准
+
+```bash
+pnpm bench               # 7 席（startup/写入/检索/索引），结果 tmp/bench-results.json
+pnpm build:bundle        # tsdown 单文件 bundle（~323KB，10% 启动提速）
+```
+
+## 9. 临时文件铁律
+
+一切临时脚本/数据放 `<repo>/tmp/`（已 gitignore），**禁止**写系统临时目录。
+
+## 10. 用户配置（config 表）
+
+```bash
+ygl-trees config list                  # 全部键
+ygl-trees config set eval.pass_threshold 0.8   # 写入即校验 + 留痕
+ygl-trees config reset eval.pass_threshold
+```
+
+## 10b. 什么时候动数据（时机问题）
+
+本技能讲"怎么动"；**"什么时候动"看 `ygl-trees-lifecycle` 技能**——事件→动作触发表
+（树侧何时 unlock/add/link、研究侧何时写 source/evidence/claim/kb/task）、节奏纪律
+（改结构后必 `node index`+`validate`、解锁后必挂证据、会话收口前必 `agent brief`+`doctor`）、
+以及漂移反模式。开场先 `agent brief`，收口前 `doctor`。
+
+## 10c. 冻结契约五项（0.55 定契）
+
+| 契约 | 含义 | 门禁 |
+|---|---|---|
+| ① 退出码 | 0 成功 / 1 运行错误 / 2 用法错误 | contract 4 |
+| ② 写入幂等 | 同内容重跑 rc=0 + `duplicate:true` | contract 1+2 |
+| ③ 坏引用点名 | `xxx not found: <id>`（不裸异常） | contract 3 |
+| ④ --json 通道 | 成功+失败都可整体 `JSON.parse` | contract 5 |
+| ⑤ flag 校验 | 裸 flag / 枚举非法 → rc=2，不落库 | contract 6 |
+
+`pnpm contract:audit` 84 项机械化断言以上全部。
+
+## 11. 常见坑
+
+- 数据库打不开报 "database is locked"：可能残留 `<db>.lock` 目录
+- `job --force` 必须在 `--` 之前（之后都算命令内容）
+- 测试工作区：`YGL_HOME=<dir>` 指到临时位置
+- Windows 下 `.cmd` shim 需 shell 解析（plugin install 已处理）
+- CLI 入口是 `dist/apps/cli/src/bin.js`（自执行，rc 契约在此）；`dist/bundle/bin.cjs` 是 bundle 版（更快）

package/skills/ygl-trees-relating/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: ygl-trees-relating
+description: >-
+  ygl-trees 关联织物方法论（spec R9/R13.2）：用 rel 命令把研究资产挂到树节点——何时挂什么：
+  节点↔evidence（依据）、节点↔claim（决策）、节点↔kb（沉淀知识）、节点↔task（跟踪）、
+  节点↔artifact/spec/design（产出）。rel 词汇表与方向语义；防止"两条平行流水线"反模式。
+  触发词：关联、挂接、rel、evidenced-by、decided-by、tracked-by、关联织物、
+  relation fabric、cross-linking、研究资产挂节点。
+version: 0.33.0
+tags: ygl-trees,methodology,relations,fabric
+---
+
+# 关联方法论：让科技树不再孤岛
+
+## 1. 反模式先立靶
+
+**两条平行流水线**：研究管线（source→evidence→claim→report）和科技树各自发育、零缝合——
+检阅者看不出"这个节点依据什么证据、由什么断言决定、跟踪着什么任务"。`relations` 表就是缝合线。
+
+## 2. rel 词汇表（方向：src --rel→ dst）
+
+| rel | 语义 | 典型挂法 |
+|---|---|---|
+| `evidenced-by` | 节点的实现/成立有据可查 | node → evidence / kb |
+| `decided-by` | 节点由某个决策（claim/design）裁定 | node → claim / design artifact |
+| `tracked-by` | 节点的进展由任务跟踪 | node → task artifact |
+| `derived-from` | 节点从某知识/报告衍生 | node → kb / report artifact |
+| `related` | 兜底弱关联（能起更specific的rel就别用） | 任意 |
+
+## 3. 引用语法与验证
+
+```bash
+ygl-trees rel add node:<tree>/<key> kb:<id|title> --rel evidenced-by
+ygl-trees rel add node:<key> claim:<id> --rel decided-by
+ygl-trees rel add node:<key> artifact:<id|title> --rel tracked-by
+ygl-trees rel list --src node:<key>       # 双向过滤 + 对端显示名
+```
+
+八类引用：`node claim evidence source query kb artifact skill`（node 裸 key 在当前树解析）。
+404→rc1、坏类型→rc2、幂等 duplicate→rc0。
+
+## 4. 何时挂（决策树）
+
+- 写完一条 claim 并 resolve supported，且它解释了树上某节点为何这样设计 → `decided-by`
+- kb ingest 了报告且节点是该报告的主体 → `derived-from`
+- 建了 task（R12）且任务属于该节点的未来工作 → `tracked-by`
+- evidence 的原文直接支撑节点可行性 → `evidenced-by`
+- 拿不准 → 先 `related`，语义清楚了再 rm/add 换精确 rel
+
+## 5. 消费面
+
+WebUI 节点详情面板 related 区（React 与内嵌 dashboard 都有）；`rel list` CLI；未解锁节点挂上
+evidenced-by 后，检阅者能直接看到"它还差什么证据"。

package/skills/ygl-trees-research/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: ygl-trees-research
+description: >-
+  用 ygl-trees 研究管线做证据先行的研究：检索式登记（query add）、来源采集（source add（--relevance 只收整数 0-5，非整数 rc=2） /
+  source fetch 网页抓取）、原文摘录（evidence add）、断言与证据链接（claim add / link /
+  resolve 人工仲裁）、query↔source 召回关联（query attach）、产出证据支撑的报告
+  （produce outline/section/report/export）。
+  触发词：研究、调研、evidence、证据、claim、断言、来源、source、引文、仲裁、resolve、
+  报告、report、文献、抓取、fetch。
+version: 0.73.0
+tags: ygl-trees,research,evidence,claim,report
+---
+
+# 证据先行的研究管线
+
+核心循环：**来源 → 证据 → 断言 → 报告**。断言状态由证据链接自动推导
+（supported/refuted/contested/unverified），报告只把已证实的写成结论。
+
+> **什么时候动这些命令**（时机而非机制）见 `ygl-trees-lifecycle` 技能。
+
+## 1. 采集
+
+```bash
+ygl-trees research query add "邻接表 vs 闭包表"              # 登记检索式
+ygl-trees research source add --title t --url https://... \
+        --abstract "..." --relevance 4 --query "邻接表 vs 闭包表"   # 手工入库+关联检索式
+ygl-trees research source fetch https://example.com/page     # 自动抓取（title/meta/正文；
+                                                              # 非 html 拒收零副作用；薄内容打 needs_review）
+```
+
+来源按 `(project, url_hash)` 去重；`--query` 顺带建立召回关联（query list 显示召回数）。
+
+## 2. 摘录与断言
+
+```bash
+ygl-trees research evidence add <sourceId> --quote "原文片段" --locator "§2"
+ygl-trees research claim add "断言文本" --confidence A
+ygl-trees research claim link <claimId> <evidenceId> [--stance refutes]   # 状态自动推导
+ygl-trees research claim resolve <claimId> --as contested --note "矛盾待查"  # 人工仲裁出口
+```
+
+- 有支持有反对 → `contested`；仲裁后新证据链接会重新推导
+- 全部命令幂等：同内容重跑返回已存在行（`duplicate: true`，rc=0）
+
+## 3. 产出
+
+```bash
+ygl-trees produce outline          # 按 claim 状态生成骨架
+ygl-trees produce section "结论" --body "..."
+ygl-trees produce report           # 摘要→结论(带证据编号)→章节→证据清单→来源→局限
+ygl-trees produce export <reportId> report.md
+```
+
+未证实断言自动进"局限与未决问题"，不伪装成结论。
+
+## 4. Agent 检查清单
+
+- 先 `agent brief --json` 看 next_actions（它会告诉你缺来源/缺证据/缺断言）
+- 每条断言至少一条证据再进报告；contested 的要么补证据要么 resolve
+- `--json` 输出可直接 parse 拿 id；列表命令字段：source(id,title,url,relevance,…)、
+  claim(id,text,status,confidence,sup,ref)、evidence(id,source,locator,quote,used_by)

package/skills/ygl-trees-techtree/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: ygl-trees-techtree
+description: >-
+  用 ygl-trees 科技树数据模型建依赖图：节点与父子关联（node add/link，rel=prereq|unlock|
+  excludes|enables × mode=AND|OR|XOR|NOT）、必检与可选条件（node cond）、闭包与拓扑索引
+  （node index/validate 环检测）、解锁判定（can/ready/path）、状态与导入导出 round-trip
+  （node unlock/export/import）。
+  触发词：科技树、技能树、依赖图、DAG、tech tree、skill tree、解锁、unlock、前置、
+  prerequisite、拓扑、闭包、closure、互斥、节点、node。
+version: 0.73.0
+tags: ygl-trees,techtree,dag,unlock,gate
+---
+
+# 科技树节点模型
+
+`node_edges` 邻接表是唯一事实源；`node_closure`（祖先/后代闭包）与 `node_index`（拓扑序）
+是派生索引——`node index` 重建，遇到必检环直接报错。
+
+> **什么时候动这些命令**（时机而非机制）见 `ygl-trees-lifecycle` 技能。
+
+## 1. 建树
+
+```bash
+ygl-trees tree new demo
+ygl-trees node add mining --cost 5 --tier 0
+ygl-trees node link mining smelting                      # prereq/AND/必检（默认）
+ygl-trees node link bronze steel --optional              # 可选：不阻塞，进 missing_optional
+ygl-trees node link bronze iron --mode OR                # 任一父解锁即可
+ygl-trees node link a b --rel excludes                   # 互斥分支：父解锁则子被封死
+ygl-trees node cond steel --name lab_level --kind level --value 3          # 必检门槛
+ygl-trees node cond steel --name has_eng --kind flag --op has --optional \
+           --effect cost_mul --weight 0.8                                 # 可选打折
+# 语义型门槛（决策模型三题型 boolean/choice/score）→ 见 ygl-trees-eval-gates 技能
+ygl-trees node index && ygl-trees node validate
+```
+
+## 2. 判定与导航
+
+```bash
+ygl-trees node can steel --state "lab_level=3,has_eng=1"   # 三类失败分开列+成本系数
+ygl-trees node ready                                        # 当前可解锁集合
+ygl-trees node path steel                                   # 解锁顺序+累计成本（目标恒最后）
+ygl-trees node ancestors bronze                             # 闭包索引直查，depth=1 是直接父
+ygl-trees node unlock mining && ygl-trees node lock mining
+```
+
+- 写入时环守卫：门控边（prereq/unlock）成环当场拒绝
+- `node can` 输出：missing_required（阻塞）/ blocked_by（被排斥）/ missing_optional（不阻塞）
+
+## 3. 迁移与保真
+
+```bash
+ygl-trees node export --out tree.json
+ygl-trees node import --file tree.json --tree copy        # 严格校验+事务，坏文件零副作用
+ygl-trees node import --file tree.json --merge            # 按 (tree,key) upsert 进已有树
+```
+
+round-trip 语义等价有 demo 断言守护；同名树默认拒绝（防覆盖）。
+
+## 4. Agent 姿势
+
+改结构后必跑 `node index` + `node validate`（`agent brief` 也会提示脏索引）；
+解锁判定用 `can` 而不是自己遍历 parents——mode 组合语义（AND/OR/XOR/NOT）在 canUnlock 里。

package/skills/ygl-trees-tree-building/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: ygl-trees-tree-building
+description: >-
+  ygl-trees 树构建方法论（spec R13.2）：把一个领域分解成丰富科技树的实践法——能力域识别、
+  层级设定（tier=成熟度/里程碑轴）、必检 vs 可选边（prereq/unlock/enables/excludes × AND/OR/XOR/NOT）、
+  语义门槛挂 eval 三题型、未来节点用真实条件锁定而非空缺。防止"三节点演示链"反模式。
+  触发词：树构建、领域分解、节点设计、tier 规划、衍生、子节点、反模式、演示链、
+  tree building、decomposition、node design、derivation。
+version: 0.33.0
+tags: ygl-trees,methodology,tree,decomposition
+---
+
+# 树构建方法论：从领域到 30+ 节点的丰富树
+
+## 1. 反模式先立靶
+
+**三节点演示链**（a→b→c）是最常见的失败形态——它验证不了分叉、互斥、可选路径与门语义。
+真实领域树的特征：**多根或多干、每层 2-6 分叉、20% 可选边、未来节点带真实条件锁定**。
+
+## 2. 分解四步
+
+1. **能力域识别**：领域切成 5-8 个能力域（ygl-trees 例：架构/研究/知识/模型/运维/Web）——每个域一条生长干
+2. **tier = 里程碑轴**：t0 地基（不依赖别人的）、t1 架构、t2 模型层……tier 语义要在建树前说清楚（成熟度？时间？依赖深度？）
+3. **边三问**：必检吗（required prereq）？可选吗（--optional，只影响 cost）？互斥吗（excludes，分支死锁）？
+4. **未来节点锁定**：还没发生的里程碑也进树（npm-publish/bun-runtime），**用真实 eval 条件锁**——registry 选型用 `--op eval-choice`、就绪度用 `--op eval-score`，让门可以随现实翻转
+
+## 3. 节点命名与粒度
+
+- key 用短横线小写复合（`eval-mixed`、`webui-serve`），name 放中文全称
+- 一个节点 = 一个可独立陈述的里程碑（"采用 TypeORM" ✓；"数据库" ✗ 太泛）
+- 粒度判据：**这个节点的完成日期能被唯一回答吗**？
+
+## 4. 建树命令节奏
+
+```bash
+ygl-trees tree new <name>
+ygl-trees node add <key> --tier <t> --name "<全称>"     # 批量加完再连边
+ygl-trees node link <parent> <child> [--optional|--rel excludes]
+ygl-trees node cond <future-key> --op eval-choice ...    # 未来门
+ygl-trees node unlock <done-key>                         # 已完成里程碑
+ygl-trees node index && ygl-trees node validate
+ygl-trees tree use <name> && ygl-trees webui serve       # React 客户端 pan/zoom 检阅
+```
+
+## 5. 自检清单
+
+- [ ] ≥30 节点、≥5 层、≥4 条生长干
+- [ ] 可选边 ≥15%（--optional / effect cost_mul）
+- [ ] 未来节点 ≥2 个带真实 eval 条件（不是空缺）
+- [ ] doctor 全绿（信封有效）；node validate 无环
+- [ ] 已完成里程碑 unlock（时间轴布局能看到解锁弧）