ygl-trees 0.68.0 → 0.70.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.70.0（2026-10-17）`agent metrics`——从 R11 手动测量到自动化指标
+- **`ygl-trees agent metrics`**：一条命令输出工作台全量量化指标——冷启动（brief 耗时/next actions/可用技能）、知识（总量/7日增长/增长率）、研究（来源/证据/断言/验证率/证据密度）、技能（总数/命中/均命中）、科技树（棵数/节点/解锁率）、活动（7 日 events）
+- **来源**：R11 冷启动量化研究的手动测量 → 自动化——从 `time agent brief` + 手动 grep 统计变为一键输出
+- 135 单测全绿
+
+## 0.69.0（2026-10-17）MCP Server——R8 研究设计的工程落地
+- **`ygl-trees mcp`**：启动 stdio MCP 服务器（JSON-RPC 2.0），Claude Desktop / Cursor / VS Code 等 IDE Agent 可直接连接
+- **8 工具面**（三支柱理论驱动）：agent_brief · agent_match · kb_search · claim_evaluate · tree_state · produce_report · doctor · task_advance
+- **每个工具继承 CLI 冻结契约**（幂等写入、JSON 纯净、snake_case）——Agent 调用工具不需要解析命令行
+- **实现**：`packages/ops/tools/src/mcp.ts`——readline stdio + JSON-RPC 路由 + `cliJson()` 子进程调用（`process.argv[1]` 自引用，bundle/源码双兼容）
+- 实测：initialize ✓ · tools/list(8) ✓ · agent_brief(project) ✓ · kb_search(CJK 命中) ✓ · doctor(9 项) ✓
+
 ## 0.68.0（2026-10-17）锁设计修复——serve/CLI 共存 + PID 活锁检测 + JSON 纯净 + v9 时间纪律
 - **F1（P0）：webui serve 不再持排他锁**——原实现进程级锁让 serve 生命周期内挡掉一切 CLI 命令；现 serve 跳过锁（`YGL_SERVE=1` 旁路），SQLite WAL 天然支持并发读 + 序列化写；CLI 短命令仍锁（单写者保护写窗口）
 - **P1（用户反馈）：PID 活锁检测替代 15 分钟 mtime**——Windows 上 `process.on("exit")` 的 rmSync 句柄未释放时静默失败→锁残留→下进程撞白锁；现用 `process.kill(pid, 0)` 探测持有者是否存活（EPERM=活/ESRCH=死），死 PID **立即清锁**（不看 mtime），活 PID **如实报告**（不误报 stale）

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

@@ -116,132 +116,132 @@ function appVersion() {
 }
 // ── Usage text ──
 // (kept in apps/cli because it's presentation, not domain logic)
-const USAGE = `
-${(0, fmt_1.paint)(fmt_1.C.bold, "ygl-trees", true)}  猿光 · 科技树
-${(0, fmt_1.paint)(fmt_1.C.dim, "database-centric CLI: research → production → knowledge reuse", true)}
-
-  ygl-trees <group> <action> [args] [options]        add --json for machine output
-
-${(0, fmt_1.paint)(fmt_1.C.bold, "config", true)}      user-tunable settings (registry defaults + overrides)
-  list                       all keys: value + default + note
-  get <key>                  resolved value (config table > default)
-  set <key> <value>          validated against registry (type/range); events logged
-  reset <key>                drop override → back to default
-
-${(0, fmt_1.paint)(fmt_1.C.bold, "db", true)}
-  init                       create the workspace + schema
-  stats                      row counts per table
-  path                       print the database file path
-  export <file.sql> [--lean] dump ALL data tables (+ summary); --lean skips derived
-  sync pg <url>              one-way full mirror to PostgreSQL (L1, see docs/pg-compat.md)
-  migrate pg <url> [--fresh] one-time full-fidelity graduation (constraints + data, atomic)
-  dups                       list duplicate-content rows
-  reset                      delete the database (asks nothing, be careful)
-  sql "<sql>"                ad-hoc statement (can mutate — power tool, no guardrails)
-
-${(0, fmt_1.paint)(fmt_1.C.bold, "skill", true)}        L1 description / L2 body / L3 references
-  import <file.md>           import a SKILL.md (frontmatter = L1, body = L2)
-  add                        --name --description --body [-f file.md]
-  list | show <name> | rm <name> | enable <name> | disable <name>
-  match "<query>"            full-text match, prints L1 candidates for an agent
-  refs add <skill> <path> --body ...
-
-${(0, fmt_1.paint)(fmt_1.C.bold, "project", true)}
-  new <name> -q "<question>"  create + select
-  list | use <name> | show
-
-${(0, fmt_1.paint)(fmt_1.C.bold, "research", true)}    collect → screen → extract → claim
-  query add "<text>"          register a search query
-  query attach <qid> <sid>    link source to query (recalled count)
-  query list
-  source add --title --url [--abstract --content --relevance --confidence --query]
-  source fetch <url>          fetch page, extract title/meta/text (zero side-effect on failure)
-  source list | search "<q>" | show <id> | rm <id>
-  evidence add <sourceId> --quote "..." [--note --locator]
-  evidence list
-  claim add "<text>" [--confidence A|B|C]
-  claim link <claimId> <evidenceId> [--stance supports|refutes]
-  claim resolve <claimId> --as supported|refuted|contested [--note]
-  claim list
-
-${(0, fmt_1.paint)(fmt_1.C.bold, "produce", true)}     outline → section → report · spec/design（工程产出）
-  outline                    auto-outline from claims
-  section <title> --body|-f  add a section artifact
-  report                     assemble claims+evidence+sections into a report
-  spec <title> --body|-f     requirements spec artifact (R12)
-  design <title> --body|-f   design artifact (R12) --design-type ui-ux|arch|decision
-  list | show <id> | export <id> <file>
-
-${(0, fmt_1.paint)(fmt_1.C.bold, "task", true)}          任务清单（todo|doing|done 状态机，R12）
-  add "<title>" [--note ...] create a task (status todo)
-  list [--status todo|doing|done]
-  doing|done <id>            move along the state machine（勾销全程留痕）
-
-${(0, fmt_1.paint)(fmt_1.C.bold, "kb", true)}          long-term knowledge
-  add --title --body|-f [--tags --confidence]
-  import <dir|file.md>       batch markdown (frontmatter, idempotent, single tx)
-  search "<q>" | list | show <id>
-  link <a> <b> [--rel]
-  ingest <artifactId>        import a finished artifact
-  promote <noteId> [--name]  turn a note into a reusable skill
-
-${(0, fmt_1.paint)(fmt_1.C.bold, "job", true)}         batch + schedule (drive with cron: job tick)
-  add <title> -- <command> [--every <min>] [--at "YYYY-MM-DD HH:MM"]
-  list | run <id> | tick | enable <id> | disable <id> | logs
-
-${(0, fmt_1.paint)(fmt_1.C.bold, "tree / node", true)}   tech-tree node model
-  tree new <name> [--project p]      create a tree (nodes live in it)
-  tree list | tree use <name>
-
-  node add <key> [--name --kind --tier --cost --tags --payload]
-  node link <parent> <child>         [--rel prereq|unlock|excludes|enables]
-                                      [--mode AND|OR|XOR|NOT] [--optional]
-                                      [--min-level n] [--weight n]
-  node unlink <parent> <child> [--rel prereq]
-  node cond <key> --name <c>         [--kind flag|resource|level|quest|time|expr]
-                                      [--op >=|==|<=|!=|has] [--value v] [--optional]
-                                      [--op eval --value "<布尔问题>"]
-                                      [--op eval-choice --value "<问题>" --options "k=desc,..." --answer k]
-                                      [--op eval-score --value "<问题>" --levels "级0,..." --min-score n]
-                                      [--effect gate|cost_mul] [--weight n]
-  node index                         rebuild closure + topo order
-  node can <key> [--state k=v]       evaluate required vs optional gates
-                                     (--eval: eval 题型经决策模型判定；
-                                      boolean P / choice P(期望答案) / score ±1 灰带)
-  node ready [--state k=v] [--eval]  currently unlockable set
-  node path <key>                    dependency-order path to target (all locked ancestors; OR branches not optimized)
-  node parents|children <key>        direct relations
-  node ancestors|descendants <key>   transitive, via closure index
-  node list | show <key> | search "<q>" | unlock|lock <key>
-  node validate                      cycles, dangling edges, dirty index
-  node export [--out file.json]      portable JSON
-  node import --file <file.json>     [--tree name] [--merge] — strict, transactional
-
-  Writes are idempotent (claim/evidence/query/kb/job dedupe by content
-  hash); pass --force to keep a deliberate duplicate.
-
-${(0, fmt_1.paint)(fmt_1.C.bold, "webui", true)}            dashboard (zero-dependency)
-  export [--out <file>]     single-file dashboard.html (open in browser)
-  serve [--port N]          live dashboard at http://127.0.0.1:N/ (Ctrl+C to stop)
-
-${(0, fmt_1.paint)(fmt_1.C.bold, "rel", true)}             关联织物（spec R9：任意两类实体互相挂接）
-  add <src> <dst> [--rel t]   link two refs: node:key claim:id kb:id artifact:id
-                             skill:name evidence:id source:id query:id
-  rm <src> <dst> [--rel t]    unlink
-  list [--src r] [--dst r]    browse (either side filter, resolves displays)
-
-${(0, fmt_1.paint)(fmt_1.C.bold, "plugin", true)}          用户层插件分发（spec R14 L3，业务域扩展位）
-  init                       create $YGL_HOME/plugins profile
-  install <spec>             npm package / git url / local dir (auto link:)
-  remove <name> | list       manage the user layer ($YGL_HOME/ygl.user.bundle.json)
-  插件契约：export apply(ctx,config) + 可选 commands 贡献 CLI 命令组
-
-${(0, fmt_1.paint)(fmt_1.C.bold, "agent", true)}       agent-facing views
-  brief                      current project state + next actions (start here)
-  match "<task>"             which skill should handle this task
-  log                        recent events
-
-Global: --json  --no-color  --db <file>  --home <dir>
+const USAGE = `
+${(0, fmt_1.paint)(fmt_1.C.bold, "ygl-trees", true)}  猿光 · 科技树
+${(0, fmt_1.paint)(fmt_1.C.dim, "database-centric CLI: research → production → knowledge reuse", true)}
+
+  ygl-trees <group> <action> [args] [options]        add --json for machine output
+
+${(0, fmt_1.paint)(fmt_1.C.bold, "config", true)}      user-tunable settings (registry defaults + overrides)
+  list                       all keys: value + default + note
+  get <key>                  resolved value (config table > default)
+  set <key> <value>          validated against registry (type/range); events logged
+  reset <key>                drop override → back to default
+
+${(0, fmt_1.paint)(fmt_1.C.bold, "db", true)}
+  init                       create the workspace + schema
+  stats                      row counts per table
+  path                       print the database file path
+  export <file.sql> [--lean] dump ALL data tables (+ summary); --lean skips derived
+  sync pg <url>              one-way full mirror to PostgreSQL (L1, see docs/pg-compat.md)
+  migrate pg <url> [--fresh] one-time full-fidelity graduation (constraints + data, atomic)
+  dups                       list duplicate-content rows
+  reset                      delete the database (asks nothing, be careful)
+  sql "<sql>"                ad-hoc statement (can mutate — power tool, no guardrails)
+
+${(0, fmt_1.paint)(fmt_1.C.bold, "skill", true)}        L1 description / L2 body / L3 references
+  import <file.md>           import a SKILL.md (frontmatter = L1, body = L2)
+  add                        --name --description --body [-f file.md]
+  list | show <name> | rm <name> | enable <name> | disable <name>
+  match "<query>"            full-text match, prints L1 candidates for an agent
+  refs add <skill> <path> --body ...
+
+${(0, fmt_1.paint)(fmt_1.C.bold, "project", true)}
+  new <name> -q "<question>"  create + select
+  list | use <name> | show
+
+${(0, fmt_1.paint)(fmt_1.C.bold, "research", true)}    collect → screen → extract → claim
+  query add "<text>"          register a search query
+  query attach <qid> <sid>    link source to query (recalled count)
+  query list
+  source add --title --url [--abstract --content --relevance --confidence --query]
+  source fetch <url>          fetch page, extract title/meta/text (zero side-effect on failure)
+  source list | search "<q>" | show <id> | rm <id>
+  evidence add <sourceId> --quote "..." [--note --locator]
+  evidence list
+  claim add "<text>" [--confidence A|B|C]
+  claim link <claimId> <evidenceId> [--stance supports|refutes]
+  claim resolve <claimId> --as supported|refuted|contested [--note]
+  claim list
+
+${(0, fmt_1.paint)(fmt_1.C.bold, "produce", true)}     outline → section → report · spec/design（工程产出）
+  outline                    auto-outline from claims
+  section <title> --body|-f  add a section artifact
+  report                     assemble claims+evidence+sections into a report
+  spec <title> --body|-f     requirements spec artifact (R12)
+  design <title> --body|-f   design artifact (R12) --design-type ui-ux|arch|decision
+  list | show <id> | export <id> <file>
+
+${(0, fmt_1.paint)(fmt_1.C.bold, "task", true)}          任务清单（todo|doing|done 状态机，R12）
+  add "<title>" [--note ...] create a task (status todo)
+  list [--status todo|doing|done]
+  doing|done <id>            move along the state machine（勾销全程留痕）
+
+${(0, fmt_1.paint)(fmt_1.C.bold, "kb", true)}          long-term knowledge
+  add --title --body|-f [--tags --confidence]
+  import <dir|file.md>       batch markdown (frontmatter, idempotent, single tx)
+  search "<q>" | list | show <id>
+  link <a> <b> [--rel]
+  ingest <artifactId>        import a finished artifact
+  promote <noteId> [--name]  turn a note into a reusable skill
+
+${(0, fmt_1.paint)(fmt_1.C.bold, "job", true)}         batch + schedule (drive with cron: job tick)
+  add <title> -- <command> [--every <min>] [--at "YYYY-MM-DD HH:MM"]
+  list | run <id> | tick | enable <id> | disable <id> | logs
+
+${(0, fmt_1.paint)(fmt_1.C.bold, "tree / node", true)}   tech-tree node model
+  tree new <name> [--project p]      create a tree (nodes live in it)
+  tree list | tree use <name>
+
+  node add <key> [--name --kind --tier --cost --tags --payload]
+  node link <parent> <child>         [--rel prereq|unlock|excludes|enables]
+                                      [--mode AND|OR|XOR|NOT] [--optional]
+                                      [--min-level n] [--weight n]
+  node unlink <parent> <child> [--rel prereq]
+  node cond <key> --name <c>         [--kind flag|resource|level|quest|time|expr]
+                                      [--op >=|==|<=|!=|has] [--value v] [--optional]
+                                      [--op eval --value "<布尔问题>"]
+                                      [--op eval-choice --value "<问题>" --options "k=desc,..." --answer k]
+                                      [--op eval-score --value "<问题>" --levels "级0,..." --min-score n]
+                                      [--effect gate|cost_mul] [--weight n]
+  node index                         rebuild closure + topo order
+  node can <key> [--state k=v]       evaluate required vs optional gates
+                                     (--eval: eval 题型经决策模型判定；
+                                      boolean P / choice P(期望答案) / score ±1 灰带)
+  node ready [--state k=v] [--eval]  currently unlockable set
+  node path <key>                    dependency-order path to target (all locked ancestors; OR branches not optimized)
+  node parents|children <key>        direct relations
+  node ancestors|descendants <key>   transitive, via closure index
+  node list | show <key> | search "<q>" | unlock|lock <key>
+  node validate                      cycles, dangling edges, dirty index
+  node export [--out file.json]      portable JSON
+  node import --file <file.json>     [--tree name] [--merge] — strict, transactional
+
+  Writes are idempotent (claim/evidence/query/kb/job dedupe by content
+  hash); pass --force to keep a deliberate duplicate.
+
+${(0, fmt_1.paint)(fmt_1.C.bold, "webui", true)}            dashboard (zero-dependency)
+  export [--out <file>]     single-file dashboard.html (open in browser)
+  serve [--port N]          live dashboard at http://127.0.0.1:N/ (Ctrl+C to stop)
+
+${(0, fmt_1.paint)(fmt_1.C.bold, "rel", true)}             关联织物（spec R9：任意两类实体互相挂接）
+  add <src> <dst> [--rel t]   link two refs: node:key claim:id kb:id artifact:id
+                             skill:name evidence:id source:id query:id
+  rm <src> <dst> [--rel t]    unlink
+  list [--src r] [--dst r]    browse (either side filter, resolves displays)
+
+${(0, fmt_1.paint)(fmt_1.C.bold, "plugin", true)}          用户层插件分发（spec R14 L3，业务域扩展位）
+  init                       create $YGL_HOME/plugins profile
+  install <spec>             npm package / git url / local dir (auto link:)
+  remove <name> | list       manage the user layer ($YGL_HOME/ygl.user.bundle.json)
+  插件契约：export apply(ctx,config) + 可选 commands 贡献 CLI 命令组
+
+${(0, fmt_1.paint)(fmt_1.C.bold, "agent", true)}       agent-facing views
+  brief                      current project state + next actions (start here)
+  match "<task>"             which skill should handle this task
+  log                        recent events
+
+Global: --json  --no-color  --db <file>  --home <dir>
 `;
 function usage() {
     return USAGE;
@@ -276,6 +276,14 @@ async function main(argv) {
         (0, fmt_1.out)(ctx, generateLlmsManifest());
         return 0;
     }
+    // MCP: Model Context Protocol server (stdio) — 8-tool surface.
+    // Designed by the unified three-pillar theory (R8 research); each tool
+    // routes to CLI --json, inheriting frozen contracts.
+    if (group === "mcp") {
+        const { serveMcp } = await Promise.resolve().then(() => __importStar(require("../../../packages/ops/tools/src/mcp")));
+        serveMcp();
+        return new Promise(() => { });
+    }
     if (!group || group === "help" || group === "-h" || group === "--help") {
         if (!ctx.json)
             (0, fmt_1.out)(ctx, usage());