@yorz/cli 0.3.6 → 0.4.1

package/dist/cli/index.js

@@ -3,9 +3,9 @@ import { homedir, platform, networkInterfaces } from "node:os";
 import { Command, Option } from "commander";
 import { stat, readFile, writeFile, rm, mkdir, access, rename, readdir, appendFile, copyFile } from "node:fs/promises";
 import { join, dirname, extname, resolve, sep, isAbsolute, basename as basename$1, relative, normalize } from "node:path";
-import { createHash, randomUUID } from "node:crypto";
+import { createHash, randomUUID, randomBytes } from "node:crypto";
 import { spawn, execFile } from "node:child_process";
-import { existsSync, statSync, mkdirSync, watch, createReadStream, openSync } from "node:fs";
+import { existsSync, openSync, closeSync, statSync, readSync, mkdirSync, watch, createReadStream } from "node:fs";
 import { serve } from "@hono/node-server";
 import { Hono } from "hono";
 import { promisify } from "node:util";
@@ -21,7 +21,7 @@ import { Codex } from "@openai/codex-sdk";
 import { createOpencode } from "@opencode-ai/sdk";
 import { createInterface as createInterface$1 } from "node:readline/promises";
 import MarkdownIt from "markdown-it";
-const version = "0.3.6";
+const version = "0.4.1";
 const pkg = {
   version
 };
@@ -55,9 +55,9 @@ function getAdapter(name) {
   if (name in ADAPTERS) return ADAPTERS[name];
   throw new Error(`Unknown agent: ${name}. Supported: ${Object.keys(ADAPTERS).join(", ")}`);
 }
-const __vite_glob_0_0 = '---\nname: yorz-debug\ndescription: 以资深工程师的调试纪律定位并修复疑难 bug——假设→取证→验证的证据闭环，靠 debug.md 活文档与 git 快照兜住污染。\n---\n\n# YorZ Debug 深度调试 Skill\n\n指导 Agent 以**资深工程师的调试纪律**逐步逼近疑难 bug 的根因：不凭猜测改代码，坚持「假设 → 取证 → 验证 → 缩小范围 → 再假设」的证据闭环。调试过程赋予更大的自由度（临时改代码、Mock 数据、加日志、建临时验证入口），同时用 `debug.md` 活文档 + `git stash create` 快照兜住"污染性改动不进入最终提交"。\n\n> 本 skill **不复用** yorz-spec 的 plan/tasks/execute 状态机。真相以 `debug.md` 为单一载体；Agent 持续推进直至需要用户回传证据（人在环路），或根因确认并收尾。\n\n## 何时进入本 skill\n\n- **独立触发（无需 spec / UI）**：用户在 Agent 对话中直接点名「用 yorz-debug 调这个 bug」。此时可能没有任何 spec 上下文——按下方「无 spec 场景」处理 `debug.md` 落点。\n- **追加任务勾选 Debug**：用户在 SpecDetail 追加 `fix` 任务时勾选「Debug 模式」，后端 prompt 指向本 skill。\n- **重入**：spec 目录已存在 `status: debugging` 的 `debug.md`（有未收尾记录块），run/append 路由自动切到本 skill。此时**不新建记录块**，定位活跃记录块（frontmatter `active: NNN`）续跑。\n\n## 输入约定\n\n- `spec_dir`（**可选**）：spec 目录路径（含 `spec.md`）。给出时 `debug.md` 建在此目录，与 `spec.md` 同级。\n- 待调试 bug 的描述：来自追加任务行 / 用户 prompt。\n\n### debug.md 落点\n\n- **有 spec 上下文**：`debug.md` 落 `spec_dir`（与 `spec.md` 同级）。\n- **无 spec 场景（独立触发）**：没有 `spec_dir` 时，`debug.md` 落**当前工作目录**；若用户在 prompt 中显式指定了路径，则以用户指定为准。其余多记录模型、快照、脚手架、收尾流程与有 spec 时**完全一致**。\n\n## debug.md：多记录活文档\n\n**一个 `debug.md` 承载同一 spec 生命周期内的多次调试**（某次收尾后又发现新 bug，就追加下一条记录，不覆盖历史）。它同时是：调试活文档、**Debug 模式的持久化标记**（存在未收尾记录 = 处于 Debug 模式）、脚手架是否清理干净的守卫。\n\n### 文件级 frontmatter\n\n```yaml\n---\nstatus: debugging # debugging（存在未收尾记录）| resolved（全部记录已收尾）\nactive: 2 # 当前活跃记录编号；resolved 时留空\nupdated_at: \'2026-07-19 15:54:37\' # 本地秒级，单引号包裹\n---\n```\n\n### 正文按「记录块」组织\n\n每次进入 Debug **在文末追加**一个记录块，编号 `NNN` 从 1 递增、**不复用**、不覆盖既有块：\n\n```markdown\n## Debug 1 · <bug 一句话简述>\n\n- 状态：debugging # debugging | resolved\n- 快照：<git stash create 得到的 SHA>\n- 进入时间：\'2026-07-19 15:54:37\'\n\n### 1. Bug 现象与复现\n\n...\n\n### 2. 关联链路分析\n\n...\n\n### 3. Debug 基线\n\n快照 SHA + 进入时间；`git diff <SHA>` 为退出闸门基准。\n\n### 4. 假设看板\n\n...\n\n### 5. 证据\n\n...\n\n### 6. 脚手架清单\n\n...\n\n### 7. 收尾核对\n\n...\n```\n\n### 生命周期\n\n- **创建 / 进入**：`debug.md` 不存在则创建（写文件 frontmatter + 第 1 个记录块）；已存在则追加 `## Debug <max+1>`，置文件 `status: debugging`、`active: <新编号>`。进入后**立刻**打快照（见「污染防线」）。\n- **单块收尾**：把该记录块块头 `状态` 置 `resolved`，脚手架逐条核销，`git diff <SNAP>` 校验只剩合法修复。\n- **文件 status 收敛**：单块收尾后，若**所有**记录块均 `resolved`，置文件 `status: resolved`、清空 `active`；否则保持 `debugging` 且 `active` 指向仍在调试的块。\n- **归档**：收尾**保留** `debug.md` 供复盘，绝不删除。\n\n## 核心调试循环\n\n**分析 → 规划 → 假设 → 实施 → 验证 → 缩小范围 → 再假设**，直至根因被硬证据锁定。\n\n```mermaid\nflowchart TD\n    Start["接手 bug"] --> Repro{"能稳定复现?"}\n    Repro -->|否| GetRepro["补齐复现步骤<br/>（问用户 / 自行构造）"]\n    GetRepro --> Repro\n    Repro -->|是| Analyze["分析关联链路<br/>写入 debug.md"]\n    Analyze --> Hypo["提出可证伪假设<br/>成立看到 X / 不成立看到 Y"]\n    Hypo --> Probe["写验证性代码 / 加日志<br/>登记脚手架清单"]\n    Probe --> Eval{"证据指向?"}\n    Eval -->|证伪| Exclude["记入已排除假设 + 依据"]\n    Exclude --> Narrow["缩小范围（二分/控制变量）"]\n    Narrow --> Hypo\n    Eval -->|坐实根因| Fix["写最终修复"]\n    Fix --> Verify{"重跑复现步骤<br/>问题消失?"}\n    Verify -->|否| Hypo\n    Verify -->|是| Close["进入收尾"]\n```\n\n### 方法层\n\n- **二分法**：在可疑区间（提交历史 / 代码路径 / 数据范围）二分定位，每次砍掉一半。\n- **控制变量法**：一次只改一个变量，隔离单一因素的影响。\n- **遍历可能分支**：对有限的分支/枚举/状态逐一验证，排除法收敛。\n\n## 硬约束（资深工程师容易做、Agent 容易漏）\n\n1. **先复现，再调试**：无法稳定复现，**不得进入修改阶段**——否则无从验证修没修好。复现不了就先构造复现路径或请用户提供。\n2. **假设必须可证伪**：提出假设时，同时写出"若成立会看到 X，若不成立会看到 Y"，再去取证。写进「假设看板」。\n3. **记录已排除假设 + 依据**：每否定一个假设，连同证据写入看板，**避免兜圈子反复验证同一已否定项**。\n4. **禁止无证据修复**：拿到指向根因的**硬证据**（日志 / 截图 / 可复现的最小用例）前，**只许写验证性代码，不许写最终修复**。\n5. **人在环路**：加日志后**停下**，请用户复现并回传日志 / 截图（MVP 复用现有 Chat 会话承接回传，无需新 UI）。回传前不臆断。\n6. **退出双条件**：根因有硬证据 **且** 修复后重跑复现步骤、证据显示问题消失——**缺一不可**。\n\n### 日志纪律\n\n- **可读可复制**：打印结构化字符串而非整个 object（如 拼接关键字段 k1=v1&k2=v2 或 `JSON.stringify(x)`），避免直接打印对象或复杂结构变量的引用。\n- **避免刷屏**：不要在循环/高频路径里打印大量日志；聚焦怀疑环节，必要时带唯一标记便于检索。\n- **可定位**：日志带上下文（哪个函数 / 哪个分支 / 关键变量值），让用户回传的一段就能判定假设成立与否。\n\n## 更大的自由度（Debug 模式内允许）\n\n- 编写临时代码（条件短路）或注释有意义代码，控制程序进入 / 屏蔽特定分支；\n- 临时篡改变量值、Mock API 返回，让程序走到特定分支；\n- 编写临时独立测试页面 / 入口，简化复现路径、直接验证怀疑环节；\n- 联网查询第三方 SDK 文档、向用户询问必要信息；\n- 允许 lint / typecheck / build / 单测出现错误，允许**临时**跳过这些检查。\n\n> 每一处临时改动都**必须**在「脚手架清单」登记一行（文件 + 位置 + 类型：短路 / Mock / 注释 / 临时页面 / 临时日志），收尾逐条核销。**未登记 = 会漏还原**。\n\n## 污染防线（强制流程）\n\n在**当前项目与分支就地调试**，不开 worktree；靠快照 + 脚手架清单 + diff 兜住污染。\n\n```mermaid\nflowchart TD\n    Enter["进入 Debug（新记录块）"] --> Snap["SNAP = git stash create<br/>零副作用快照当前脏工作区"]\n    Snap --> Record["把 SNAP 写入记录块 · Debug 基线"]\n    Record --> Loop["调试循环<br/>照常改代码 + 登记脚手架清单"]\n    Loop --> Fixed{"根因确认 + 硬证据?"}\n    Fixed -->|否| Loop\n    Fixed -->|是| Revert["按脚手架清单逐条还原"]\n    Revert --> Diff["git diff SNAP"]\n    Diff --> Gate{"仅剩合法修复?"}\n    Gate -->|否| Revert\n    Gate -->|是| Done["置本块 status: resolved<br/>跑变更文件单测/build/typecheck"]\n```\n\n- **进入即打快照**：`git stash create`（**不是** `git stash` / 临时 commit）生成一个记录当前脏工作区的 commit 对象，但**不动工作区 / index / HEAD**。它天然区分"进入前的既有未提交改动"与"调试引入的改动"，避免临时 commit 的还原风险。把返回的 SHA 写入记录块「Debug 基线」。\n  - 若 `git stash create` 无输出（工作区干净），以当前 `HEAD`（`git rev-parse HEAD`）作为快照基准并注明。\n- **git diff 是退出闸门**：宣告完成前，`git diff <SNAP>` 必须**只剩合法修复**——所有短路 / Mock / 注释 / 临时页面 / 临时日志都已还原。diff 里还有脚手架残留 = 不许收尾。\n\n## 收尾（退出 Debug 模式）\n\n根因确认且修复通过复现验证后：\n\n1. **还原脚手架**：按「脚手架清单」逐条还原临时代码与被注释代码，确保原有逻辑正确；清理不需要的 debug 日志。\n2. **退出闸门**：`git diff <SNAP>` 只剩合法修复（脚手架清单全部核销）。\n3. **常规完整性检查**：跑变更文件关联单测、构建、类型检查。\n4. **落状态**：把该记录块块头 `状态` 置 `resolved`；按「文件 status 收敛」更新文件 frontmatter（全部 resolved → 文件 `status: resolved`、清空 `active`）。\n5. **保留归档**：`debug.md` 保留，供复盘。\n\n> 收尾后如又发现**新** bug，回到本 skill 追加下一条 `## Debug NNN` 记录块（不覆盖历史），重新走一遍循环。\n\n## 写回纪律\n\n- 每次写回 `debug.md` 都更新文件 frontmatter 的 `updated_at`（本地秒级，单引号）。\n- `updated_at` 用 `YYYY-MM-DD HH:mm:ss`。\n- 记录块编号连续递增、不复用、不重排既有块。\n';
+const __vite_glob_0_0 = '---\nname: yorz-debug\ndescription: 以资深工程师的调试纪律定位并修复疑难 bug——假设→取证→验证的证据闭环，靠 debug.md 活文档与 git 快照兜住污染。\n---\n\n# YorZ Debug 深度调试 Skill\n\n指导 Agent 以**资深工程师的调试纪律**逐步逼近疑难 bug 的根因：不凭猜测改代码，坚持「假设 → 取证 → 验证 → 缩小范围 → 再假设」的证据闭环。调试过程赋予更大的自由度（临时改代码、Mock 数据、加日志、建临时验证入口），同时用 `debug.md` 活文档 + `git stash create` 快照兜住"污染性改动不进入最终提交"。\n\n> 本 skill **不复用** yorz-spec 的 plan/tasks/execute 状态机。真相以 `debug.md` 为单一载体；Agent 持续推进直至需要用户回传证据（人在环路），或根因确认并收尾。\n\n## 何时进入本 skill\n\n- **独立触发（无需 spec / UI）**：用户在 Agent 对话中直接点名「用 yorz-debug 调这个 bug」。此时可能没有任何 spec 上下文——按下方「无 spec 场景」处理 `debug.md` 落点。\n- **追加任务勾选 Debug**：用户在 SpecDetail 追加 `fix` 任务时勾选「Debug 模式」，后端 prompt 指向本 skill。\n- **重入**：spec 目录已存在 `status: debugging` 的 `debug.md`（有未收尾记录块），run/append 路由自动切到本 skill。此时**不新建记录块**，定位活跃记录块（frontmatter `active: NNN`）续跑。\n\n## 输入约定\n\n- `spec_dir`（**可选**）：spec 目录路径（含 `spec.md`）。给出时 `debug.md` 建在此目录，与 `spec.md` 同级。\n- 待调试 bug 的描述：来自追加任务行 / 用户 prompt。\n- 运行服务上下文（**可选**）：由 YorZ Service 注入的当前项目运行中命令服务列表，包含 `runId`、`name`、`cli`、`pid`、`startedAt`、`logFile` 等字段。\n\n### debug.md 落点\n\n- **有 spec 上下文**：`debug.md` 落 `spec_dir`（与 `spec.md` 同级）。\n- **无 spec 场景（独立触发）**：没有 `spec_dir` 时，`debug.md` 落**当前工作目录**；若用户在 prompt 中显式指定了路径，则以用户指定为准。其余多记录模型、快照、脚手架、收尾流程与有 spec 时**完全一致**。\n\n## debug.md：多记录活文档\n\n**一个 `debug.md` 承载同一 spec 生命周期内的多次调试**（某次收尾后又发现新 bug，就追加下一条记录，不覆盖历史）。它同时是：调试活文档、**Debug 模式的持久化标记**（存在未收尾记录 = 处于 Debug 模式）、脚手架是否清理干净的守卫。\n\n### 文件级 frontmatter\n\n```yaml\n---\nstatus: debugging # debugging（存在未收尾记录）| resolved（全部记录已收尾）\nactive: 2 # 当前活跃记录编号；resolved 时留空\nupdated_at: \'2026-07-19 15:54:37\' # 本地秒级字符串\n---\n```\n\n### 正文按「记录块」组织\n\n每次进入 Debug **在文末追加**一个记录块，编号 `NNN` 从 1 递增、**不复用**、不覆盖既有块：\n\n```markdown\n## Debug 1 · <bug 一句话简述>\n\n- 状态：debugging # debugging | resolved\n- 快照：<git stash create 得到的 SHA>\n- 进入时间：\'2026-07-19 15:54:37\'\n\n### 1.1 Bug 现象与复现\n\n...\n\n### 1.2 关联链路分析\n\n...\n\n### 1.3 Debug 基线\n\n快照 SHA + 进入时间；`git diff <SHA>` 为退出闸门基准。\n\n### 1.4 假设看板\n\n...\n\n### 1.5 证据\n\n...\n\n### 1.6 脚手架清单\n\n...\n\n### 1.7 收尾核对\n\n...\n```\n\n### 生命周期\n\n- **创建 / 进入**：`debug.md` 不存在则创建（写文件 frontmatter + 第 1 个记录块）；已存在则追加 `## Debug <max+1>`，置文件 `status: debugging`、`active: <新编号>`。进入后**立刻**打快照（见「污染防线」）。\n- **单块收尾**：把该记录块块头 `状态` 置 `resolved`，脚手架逐条核销，`git diff <SNAP>` 校验只剩合法修复。\n- **文件 status 收敛**：单块收尾后，若**所有**记录块均 `resolved`，置文件 `status: resolved`、清空 `active`；否则保持 `debugging` 且 `active` 指向仍在调试的块。\n- **归档**：收尾**保留** `debug.md` 供复盘，绝不删除。\n\n## 核心调试循环\n\n**分析 → 规划 → 假设 → 实施 → 验证 → 缩小范围 → 再假设**，直至根因被硬证据锁定。\n\n```mermaid\nflowchart TD\n    Start["接手 bug"] --> Repro{"能稳定复现?"}\n    Repro -->|否| GetRepro["补齐复现步骤<br/>（问用户 / 自行构造）"]\n    GetRepro --> Repro\n    Repro -->|是| Analyze["分析关联链路<br/>写入 debug.md"]\n    Analyze --> Hypo["提出可证伪假设<br/>成立看到 X / 不成立看到 Y"]\n    Hypo --> Probe["写验证性代码 / 加日志<br/>登记脚手架清单"]\n    Probe --> Eval{"证据指向?"}\n    Eval -->|证伪| Exclude["记入已排除假设 + 依据"]\n    Exclude --> Narrow["缩小范围（二分/控制变量）"]\n    Narrow --> Hypo\n    Eval -->|坐实根因| Fix["写最终修复"]\n    Fix --> Verify{"重跑复现步骤<br/>问题消失?"}\n    Verify -->|否| Hypo\n    Verify -->|是| Close["进入收尾"]\n```\n\n### 方法层\n\n- **二分法**：在可疑区间（提交历史 / 代码路径 / 数据范围）二分定位，每次砍掉一半。\n- **控制变量法**：一次只改一个变量，隔离单一因素的影响。\n- **遍历可能分支**：对有限的分支/枚举/状态逐一验证，排除法收敛。\n\n## 硬约束（资深工程师容易做、Agent 容易漏）\n\n1. **先复现，再调试**：无法稳定复现，**不得进入修改阶段**——否则无从验证修没修好。复现不了就先构造复现路径或请用户提供。\n2. **假设必须可证伪**：提出假设时，同时写出"若成立会看到 X，若不成立会看到 Y"，再去取证。写进「假设看板」。\n3. **记录已排除假设 + 依据**：每否定一个假设，连同证据写入看板，**避免兜圈子反复验证同一已否定项**。\n4. **禁止无证据修复**：拿到指向根因的**硬证据**（日志 / 截图 / 可复现的最小用例）前，**只许写验证性代码，不许写最终修复**。\n5. **人机协作**：优先主动复现 Bug、获取日志进行分析判断，如果无途径复现 Bug、获取日志，也可暂停执行，让用户配合复现 Bug、回传日志。\n6. **退出双条件**：根因有硬证据 **且** 修复后重跑复现步骤、证据显示问题消失——**缺一不可**。\n\n### 日志纪律\n\n- **可读可复制**：打印结构化字符串而非整个 object（如 拼接关键字段 k1=v1&k2=v2 或 `JSON.stringify(x)`），避免直接打印对象或复杂结构变量的引用。\n- **避免刷屏**：不要在循环/高频路径里打印大量日志；聚焦怀疑环节，必要时带唯一标记便于检索。\n- **可定位**：日志带上下文（哪个函数 / 哪个分支 / 关键变量值），便于判定假设成立与否。\n\n## 更大的自由度（Debug 模式内允许）\n\n- 编写临时代码（条件短路）或注释有意义代码，控制程序进入 / 屏蔽特定分支；\n- 临时篡改变量值、Mock API 返回，让程序走到特定分支；\n- 编写临时独立测试页面 / 入口，简化复现路径、直接验证怀疑环节；\n- 联网查询第三方 SDK 文档、向用户询问必要信息；\n- 允许 lint / typecheck / build / 单测出现错误，允许**临时**跳过这些检查。\n\n> 每一处临时改动都**必须**在「脚手架清单」登记一行（文件 + 位置 + 类型：短路 / Mock / 注释 / 临时页面 / 临时日志），收尾逐条核销。**未登记 = 会漏还原**。\n\n## 污染防线（强制流程）\n\n在**当前项目与分支就地调试**，不开 worktree；靠快照 + 脚手架清单 + diff 兜住污染。\n\n```mermaid\nflowchart TD\n    Enter["进入 Debug（新记录块）"] --> Snap["SNAP = git stash create<br/>零副作用快照当前脏工作区"]\n    Snap --> Record["把 SNAP 写入记录块 · Debug 基线"]\n    Record --> Loop["调试循环<br/>照常改代码 + 登记脚手架清单"]\n    Loop --> Fixed{"根因确认 + 硬证据?"}\n    Fixed -->|否| Loop\n    Fixed -->|是| Revert["按脚手架清单逐条还原"]\n    Revert --> Diff["git diff SNAP"]\n    Diff --> Gate{"仅剩合法修复?"}\n    Gate -->|否| Revert\n    Gate -->|是| Done["置本块 status: resolved<br/>跑变更文件单测/build/typecheck"]\n```\n\n- **进入即打快照**：`git stash create`（**不是** `git stash` / 临时 commit）生成一个记录当前脏工作区的 commit 对象，但**不动工作区 / index / HEAD**。它天然区分"进入前的既有未提交改动"与"调试引入的改动"，避免临时 commit 的还原风险。把返回的 SHA 写入记录块「Debug 基线」。\n  - 若 `git stash create` 无输出（工作区干净），以当前 `HEAD`（`git rev-parse HEAD`）作为快照基准并注明。\n- **git diff 是退出闸门**：宣告完成前，`git diff <SNAP>` 必须**只剩合法修复**——所有短路 / Mock / 注释 / 临时页面 / 临时日志都已还原。diff 里还有脚手架残留 = 不许收尾。\n\n## 收尾（退出 Debug 模式）\n\n根因确认且修复通过复现验证后：\n\n1. **还原脚手架**：按「脚手架清单」逐条还原临时代码与被注释代码，确保原有逻辑正确；清理不需要的 debug 日志。\n2. **退出闸门**：`git diff <SNAP>` 只剩合法修复（脚手架清单全部核销）。\n3. **常规完整性检查**：跑变更文件关联单测、构建、类型检查。\n4. **落状态**：把该记录块块头 `状态` 置 `resolved`；按「文件 status 收敛」更新文件 frontmatter（全部 resolved → 文件 `status: resolved`、清空 `active`）。\n5. **保留归档**：`debug.md` 保留，供复盘。\n\n> 收尾后如又发现**新** bug，回到本 skill 追加下一条 `## Debug NNN` 记录块（不覆盖历史），重新走一遍循环。\n\n## 写回纪律\n\n- 每次写回 `debug.md` 都更新文件 frontmatter 的 `updated_at`。\n- `updated_at` 用本地秒级 `YYYY-MM-DD HH:mm:ss` 字符串。\n- 记录块编号连续递增、不复用、不重排既有块。\n';
 const __vite_glob_0_1 = '{\n  "$schema": "https://json-schema.org/draft-07/schema#",\n  "version": 2,\n  "modules": [\n    {\n      "module": "SKILL",\n      "file": "SKILL.md",\n      "relatedCases": []\n    }\n  ]\n}\n';
-const __vite_glob_0_2 = '---\nname: yorz-spec\ndescription: Drive YorZ spec docs through plan / tasks / execute stages with deterministic state updates.\n---\n\n# YorZ Spec Drive Skill\n\n将单个 YorZ spec 文档作为状态机执行，围绕 `plan` / `tasks` / `execute` 三阶段推进，全部任务完成后进入终止态 `done`，把状态持续写回文档。md 是单一真相；Agent 持续推进直至阻塞（待确认项、决策、Review）或收尾为 `done` 才退出。\n\n## 如何使用本 skill\n\n本 skill 文档结构精简为 3 个文件；每次接到 spec 任务时，**按以下顺序**按需 Read：\n\n1. **本文档（SKILL.md）**：输入约定、frontmatter 规范、格式约定、自动模式判定、全局硬约束、lint 硬约束、持续推进约束。\n2. **[stages.md](./stages.md)**：plan / tasks / execute / new-spec 四阶段流程与正面示例。\n3. **[review.md](./review.md)**：Review / Git Ops 阶段（独立路径，低频使用）。\n\n[mermaid.md](./mermaid.md) 与 `references/` 目录**仅按需 Read**：只有在判断当前阶段需要输出 mermaid 图表「升维」时才加载，纯状态推进任务不必读取，以节省 context。**plan 阶段的「图形化补充」收尾子步骤**（见 stages.md）会针对 `现状分析`/`技术方案` 两节强制加载 mermaid.md 补图；补图须遵循其核心原则**「图优先、精确信息折叠」**——表层给图，精确细节折叠进 `<details>` 精确层。\n\n> 当 Agent 以 `mode=review` / `mode=git-ops` 启动时，按 [review.md](./review.md) 执行；该路径不进入 plan/tasks/execute 状态机，也不修改 spec.md 的 frontmatter。\n\n## 输入约定\n\n- `spec_path`：**可选**，目标 spec 文档路径。\n  - 显式给出时：典型位置 `docs/specs/*.md` 或 `.yorz/specs/<id>/spec.md`，直接更新该 spec。\n  - 缺省时按以下顺序解析：\n    1. **从 session 上下文恢复**：扫描当前会话历史中已出现/已读写过的 spec 文档路径；存在多个时优先选取最近一次被读写的；若仍有歧义，向用户确认。\n    2. **从当前 prompt 创建**：若上下文中没有任何 spec 文档，按 [新建 spec 流程](./stages.md#new-spec) 生成路径与骨架。\n- spec 目录默认为 `.yorz/specs`，可由 `<ProjectRoot>/.yorz/config.json` 的 `specsDir` 字段覆盖。\n- `mode`：可选，`plan|tasks|execute|auto`，默认 `auto`。\n- 批注前缀：`！！！`\n\n## frontmatter 规范\n\n每个 spec md 顶部必须有 YAML frontmatter：\n\n```yaml\n---\nstage: plan # plan | tasks | execute | done\nlast_action: 简述上一次动作\nupdated_at: \'2026-06-14 15:42:07\' # 秒级 + 单引号\nsummary: 一句话概要，≤ 200 字符\n---\n```\n\n- 字段顺序固定为 `stage` → `last_action` → `updated_at` → `summary`，每个字段独占一行，禁止嵌套与额外字段。\n- `updated_at` 使用本地秒级 `YYYY-MM-DD HH:mm:ss`，**写入时必须用单引号包裹**。\n- 缺失任意字段时，先补齐再继续。\n\n## Markdown 格式化约定\n\n- 每次写回 spec md 后，**应在仓库支持的条件下运行 Markdown formatter**（优先 `npx prettier --write <spec_path>`）；未配置则跳过。\n- formatter 必须保留 YAML frontmatter 不变。\n- 任务清单仅使用单层 `- [ ]` / `- [x]`，避免缩进与嵌套。\n- 二、三级标题必须带层级编号，便于外部按章节号定位：\n  - 每次写回前按 body 中 `## ` / `### ` 出现顺序重新编号。\n  - 二级标题 `## N. 标题`（N 从 1 起）；三级标题 `### N.M 标题`（M 在所属二级下从 1 起）。\n  - 该规则不影响 frontmatter 与一级标题（`# `）。\n\n## 自动模式判定顺序（严格按顺序）\n\n`mode=auto` 时，**严格按顺序**判定，命中即停：\n\n1. 若 `spec_path` 缺省：从 session 上下文恢复 spec 路径；恢复失败进入 [新建 spec 流程](./stages.md#new-spec) 并以 `plan` 起步。\n2. **优先扫描 `## 追加任务` 中是否存在 `[open]` 条目**：存在即视为"新输入"信号，进入 `plan`（重开流程）。\n3. 若识别到新增/扩展需求或新增 bug，进入 `plan`（重开流程）。\n4. 若文档存在任意 `！！！` 批注，进入 [tasks](./stages.md#tasks)。\n5. 若 `## 待确认项` 下存在有效条目（非空态 `_暂无_`），停止推进并等待人工批注。\n6. 若 `stage` 已是 `done` 且上述 1–5 均未命中（无新输入/批注/待确认项），直接停止：终止态不再自动推进。\n7. 若存在未完成的**非 `[manual]`** 任务（`- [ ]` 且非 `- [ ] [manual]`），进入 [execute](./stages.md#execute)。\n8. 若任务清单已就绪且不存在未完成的非 manual 任务（走到此处已排除 `[open]`/新需求/批注/待确认项）：将 `stage` 置为 `done` 并停止推进（终止态）。\n9. 若 `## 技术实现方案` 为空或明显不完整，进入 [plan](./stages.md#plan)。\n10. 进入 [tasks](./stages.md#tasks) 生成或刷新详细任务清单。\n\n> 章节名 `## 待确认项` 为新名，parser/lint 兼容旧名 `## 待确认问题`；存量 spec 保留旧名仍可识别，新建/重写一律用 `待确认项`。\n>\n> 待确认项判定：章节内存在任一 `### ` 三级标题即视为未决；仅有 `_暂无_` 或整章为空即视为无未决条目；存在未决条目时禁止进入 execute。\n>\n> `done` 判定忽略 `- [ ] [manual]` 人工确认项：即使 manual 项仍未勾选，只要其余任务全部完成、且无待确认项/批注/`[open]`，即可收尾为 `done`。\n\n## 全局硬约束\n\n### 通用\n\n- 仅更新目标 spec 文档，不修改无关文档。\n- 每次写回文档都必须更新 frontmatter 元信息。\n- 执行任务时若涉及代码改动，只改动与任务相关的最小范围。\n\n### 章节建议\n\n初始化 spec 时**建议**创建以下章节（`## 追加任务` `## 用户批注` 为可选，由用户触发追加时懒插入）：\n\n- `## 现状分析` / `## 技术实现方案` / `## 待确认项` / `## 任务清单` / `## 执行记录`\n\n> lint 不再强制校验章节齐全；但 routing 按章节名查找时，章节不存在视为空态。\n\n### 变更重开流程\n\n**触发条件：**\n\n- 在已有 spec 中识别到"新增/扩展需求"或"新增 bug"，将 `stage` 切回 `plan`，`last_action` 记录"变更重开流程"。\n- `## 追加任务` 存在 `- [open] [feat|refct|fix] ...` 条目时，将 `stage` 切回 `plan`。\n\n**重开后必须做的事：**\n\n- 仅针对新增内容重新走完 `plan → tasks → execute`。\n- 未受影响的既有结论/任务可保留，受影响任务必须重新评估。\n- plan 阶段消费追加任务条目时，**不修改** `[open]` 状态标记。\n\n## 输出优先级\n\n1. 先保证状态正确（frontmatter 元信息更新）。\n2. 再保证结构正确（列表格式、任务格式、候选项）。\n3. 最后保证内容质量（可执行、可验收、可追踪）。\n\n## 写回后的 lint 硬约束\n\n任何阶段完成对 `spec.md` / `review.md` 的写入后，Agent **必须**通过 Bash 运行 `yorz lint <path> --format json`，并 parse stdout。\n\n- `errorCount === 0` 时视为通过。\n- 存在 `severity: error` 时按 `ruleId` + `message` + `line` 定位并修改，然后重新运行 lint。\n- 同一文件 lint 连续失败达到 **3 次**，将偏差作为 `## 待确认项` 条目写入 spec.md 后退出，等待人工干预。\n- `warn` 级 finding 不阻断推进，但应尽力消除。\n\n## 持续推进硬约束\n\nAgent 在 plan / tasks / execute 任意阶段，**只允许**因以下"合法阻塞"退出当轮：\n\n1. `## 待确认项` 章节存在非 `暂无` 条目；\n2. spec md 内存在任何 `！！！` 批注；\n3. 识别到新增/扩展需求或新增 bug，按变更重开流程切回 `plan`；\n4. 执行外部命令 / 工具调用失败，需要用户做不可推断的决断。\n\n**显式禁止**以下"元确认"行为：\n\n- 以"任务很多 / 改动较大 / 范围广 / 时间长 / 风险高"为由询问"是否继续 / 是否执行 / 是否同意此方案"。\n- 在 execute 阶段中段汇报进度并要求用户确认下一步。\n- 反问类如"要不要我开始 / 是否继续下一项"等问句。\n\n替代约定：tasks/execute 阶段若产生新疑问，**必须**作为新条目写回 `## 待确认项` 并按变更重开流程退出。\n\n兜底：对外部世界有副作用、不可逆的命令（如 `git push`、`git reset --hard`、`rm -rf`、修改 CI 配置等破坏性操作）仍按系统默认安全准则处理。\n\n## 与 YorZ 工作流的关联\n\n- 本 skill 不依赖 YorZ Service / GUI 也能独立工作：Agent 直接读写 `spec_path` 即可。\n- 当 YorZ Service 在线时，Agent 写回 md 会被 Service 的 FS Watcher 感知并推送给 GUI。\n- 如需用户介入，Agent 把信息写回文档对应章节后立即退出，由用户人工补齐 `！！！` 批注，再由 CLI / Service 重新拉起 Agent 继续执行。\n';
+const __vite_glob_0_2 = '---\nname: yorz-spec\ndescription: Drive YorZ spec docs through plan / tasks / execute stages with deterministic state updates.\n---\n\n# YorZ Spec Drive Skill\n\n将单个 YorZ spec 文档作为状态机执行，围绕 `plan` / `tasks` / `execute` 三阶段推进，全部任务完成后进入终止态 `done`，把状态持续写回文档。md 是单一真相；Agent 持续推进直至阻塞（待确认项、决策、Review）或收尾为 `done` 才退出。\n\n## 如何使用本 skill\n\n本 skill 文档结构精简为 3 个文件；每次接到 spec 任务时，**按以下顺序**按需 Read：\n\n1. **本文档（SKILL.md）**：输入约定、frontmatter 规范、格式约定、自动模式判定、全局硬约束、lint 硬约束、持续推进约束。\n2. **[stages.md](./stages.md)**：plan / tasks / execute / new-spec 四阶段流程与正面示例。\n3. **[review.md](./review.md)**：Review / Git Ops 阶段（独立路径，低频使用）。\n\n[mermaid.md](./mermaid.md) 与 `references/` 目录**仅按需 Read**：只有在判断当前阶段需要输出 mermaid 图表「升维」时才加载，纯状态推进任务不必读取，以节省 context。**plan 阶段的「图形化补充」收尾子步骤**（见 stages.md）会针对 `现状分析`/`技术方案` 两节强制加载 mermaid.md 补图；补图须遵循其核心原则**「图优先、精确信息折叠」**——表层给图，精确细节折叠进 `<details>` 精确层。\n\n> 当 Agent 以 `mode=review` / `mode=git-ops` 启动时，按 [review.md](./review.md) 执行；该路径不进入 plan/tasks/execute 状态机，也不修改 spec.md 的 frontmatter。\n\n## 输入约定\n\n- `spec_path`：**可选**，目标 spec 文档路径。\n  - 显式给出时：典型位置 `docs/specs/*.md` 或 `.yorz/specs/<id>/spec.md`，直接更新该 spec。\n  - 缺省时按以下顺序解析：\n    1. **从 session 上下文恢复**：扫描当前会话历史中已出现/已读写过的 spec 文档路径；存在多个时优先选取最近一次被读写的；若仍有歧义，向用户确认。\n    2. **从当前 prompt 创建**：若上下文中没有任何 spec 文档，按 [新建 spec 流程](./stages.md#new-spec) 生成路径与骨架。\n- spec 目录默认为 `.yorz/specs`，可由 `<ProjectRoot>/.yorz/config.json` 的 `specsDir` 字段覆盖。\n- `mode`：可选，`plan|tasks|execute|auto`，默认 `auto`。\n- 批注前缀：`！！！`\n\n## frontmatter 规范\n\n每个 spec md 顶部必须有 YAML frontmatter：\n\n```yaml\n---\nstage: plan # plan | tasks | execute | done\nlast_action: 简述上一次动作\nupdated_at: \'2026-06-14 15:42:07\' # 本地秒级字符串\nsummary: 一句话概要，≤ 200 字符\n---\n```\n\n- 字段顺序固定为 `stage` → `last_action` → `updated_at` → `summary`，每个字段独占一行，禁止嵌套与额外字段。\n- `updated_at` 使用本地秒级 `YYYY-MM-DD HH:mm:ss` 字符串。\n- 缺失任意字段时，先补齐再继续。\n\n## Markdown 格式化约定\n\n- 每次写回 spec md 后，**应在仓库支持的条件下运行 Markdown formatter**（优先 `npx prettier --write <spec_path>`）；未配置则跳过。\n- formatter 必须保留 YAML frontmatter 不变。\n- 任务清单仅使用单层 `- [ ]` / `- [x]`，避免缩进与嵌套。\n- 二、三级标题必须带层级编号，便于外部按章节号定位：\n  - 每次写回前按 body 中 `## ` / `### ` 出现顺序重新编号。\n  - 二级标题 `## N. 标题`（N 从 1 起）；三级标题 `### N.M 标题`（M 在所属二级下从 1 起）。\n  - 该规则不影响 frontmatter 与一级标题（`# `）。\n\n## 自动模式判定顺序（严格按顺序）\n\n`mode=auto` 时，**严格按顺序**判定，命中即停：\n\n1. 若 `spec_path` 缺省：从 session 上下文恢复 spec 路径；恢复失败进入 [新建 spec 流程](./stages.md#new-spec) 并以 `plan` 起步。\n2. **优先扫描 `## 追加任务` 中是否存在 `[open]` 条目**：存在即视为"新输入"信号，进入 `plan`（重开流程）。\n3. 若识别到新增/扩展需求或新增 bug，进入 `plan`（重开流程）。\n4. 若文档存在任意 `！！！` 批注，进入 [tasks](./stages.md#tasks)。\n5. 若 `## 待确认项` 下存在有效条目（非空态 `_暂无_`），停止推进并等待人工批注。\n6. 若 `stage` 已是 `done` 且上述 1–5 均未命中（无新输入/批注/待确认项），直接停止：终止态不再自动推进。\n7. 若存在未完成的**非 `[manual]`** 任务（`- [ ]` 且非 `- [ ] [manual]`），进入 [execute](./stages.md#execute)。\n8. 若任务清单已就绪且不存在未完成的非 manual 任务（走到此处已排除 `[open]`/新需求/批注/待确认项）：将 `stage` 置为 `done` 并停止推进（终止态）。\n9. 若 `## 技术实现方案` 为空或明显不完整，进入 [plan](./stages.md#plan)。\n10. 进入 [tasks](./stages.md#tasks) 生成或刷新详细任务清单。\n\n> 章节名 `## 待确认项` 为新名，parser/lint 兼容旧名 `## 待确认问题`；存量 spec 保留旧名仍可识别，新建/重写一律用 `待确认项`。\n>\n> 待确认项判定：章节内存在任一 `### ` 三级标题即视为未决；仅有 `_暂无_` 或整章为空即视为无未决条目；存在未决条目时禁止进入 execute。\n>\n> `done` 判定忽略 `- [ ] [manual]` 人工确认项：即使 manual 项仍未勾选，只要其余任务全部完成、且无待确认项/批注/`[open]`，即可收尾为 `done`。\n\n## 全局硬约束\n\n### 通用\n\n- 仅更新目标 spec 文档，不修改无关文档。\n- 每次写回文档都必须更新 frontmatter 元信息。\n- 执行任务时若涉及代码改动，只改动与任务相关的最小范围。\n\n### 章节建议\n\n初始化 spec 时**建议**创建以下章节（`## 追加任务` `## 用户批注` 为可选，由用户触发追加时懒插入）：\n\n- `## 现状分析` / `## 技术实现方案` / `## 待确认项` / `## 任务清单` / `## 执行记录`\n\n> lint 不再强制校验章节齐全；但 routing 按章节名查找时，章节不存在视为空态。\n\n### 变更重开流程\n\n**触发条件：**\n\n- 在已有 spec 中识别到"新增/扩展需求"或"新增 bug"，将 `stage` 切回 `plan`，`last_action` 记录"变更重开流程"。\n- `## 追加任务` 存在 `- [open] [feat|refct|fix] ...` 条目时，将 `stage` 切回 `plan`。\n\n**重开后必须做的事：**\n\n- 仅针对新增内容重新走完 `plan → tasks → execute`。\n- 未受影响的既有结论/任务可保留，受影响任务必须重新评估。\n- plan 阶段消费追加任务条目时，**不修改** `[open]` 状态标记。\n\n## 输出优先级\n\n1. 先保证状态正确（frontmatter 元信息更新）。\n2. 再保证结构正确（列表格式、任务格式、候选项）。\n3. 最后保证内容质量（可执行、可验收、可追踪）。\n\n## 写回后的 lint 硬约束\n\n任何阶段完成对 `spec.md` / `review.md` 的写入后，Agent **必须**通过 Bash 运行 `yorz lint <path> --format json`，并 parse stdout。\n\n- `errorCount === 0` 时视为通过。\n- 存在 `severity: error` 时按 `ruleId` + `message` + `line` 定位并修改，然后重新运行 lint。\n- 同一文件 lint 连续失败达到 **3 次**，将偏差作为 `## 待确认项` 条目写入 spec.md 后退出，等待人工干预。\n- `warn` 级 finding 不阻断推进，但应尽力消除。\n\n## 持续推进硬约束\n\nAgent 在 plan / tasks / execute 任意阶段，**只允许**因以下"合法阻塞"退出当轮：\n\n1. `## 待确认项` 章节存在非 `暂无` 条目；\n2. spec md 内存在任何 `！！！` 批注；\n3. 识别到新增/扩展需求或新增 bug，按变更重开流程切回 `plan`；\n4. 执行外部命令 / 工具调用失败，需要用户做不可推断的决断。\n\n**显式禁止**以下"元确认"行为：\n\n- 以"任务很多 / 改动较大 / 范围广 / 时间长 / 风险高"为由询问"是否继续 / 是否执行 / 是否同意此方案"。\n- 在 execute 阶段中段汇报进度并要求用户确认下一步。\n- 反问类如"要不要我开始 / 是否继续下一项"等问句。\n\n替代约定：tasks/execute 阶段若产生新疑问，**必须**作为新条目写回 `## 待确认项` 并按变更重开流程退出。\n\n兜底：对外部世界有副作用、不可逆的命令（如 `git push`、`git reset --hard`、`rm -rf`、修改 CI 配置等破坏性操作）仍按系统默认安全准则处理。\n\n## 与 YorZ 工作流的关联\n\n- 本 skill 不依赖 YorZ Service / GUI 也能独立工作：Agent 直接读写 `spec_path` 即可。\n- 当 YorZ Service 在线时，Agent 写回 md 会被 Service 的 FS Watcher 感知并推送给 GUI。\n- 如需用户介入，Agent 把信息写回文档对应章节后立即退出，由用户人工补齐 `！！！` 批注，再由 CLI / Service 重新拉起 Agent 继续执行。\n';
 const __vite_glob_0_3 = "---\nstage: execute\nlast_action: 主任务完成，追加 1 项 [open] 待处理\nupdated_at: 2026-06-20\nsummary: HELLO.txt 已经创建；追加任务：在 HELLO.txt 末尾追加一行 `goodbye world\\n`。\n---\n\n# HELLO 占位\n\n## 1. 背景\n\n希望仓库根有占位文件，便于演示。\n\n## 2. 需求\n\n- 在仓库根创建 `HELLO.txt`，内容 `hello world\\n`\n\n## 3. 现状分析\n\n`HELLO.txt` 已经存在，内容 `hello world\\n`。\n\n## 4. 技术实现方案\n\n- 直接写入 `HELLO.txt`，内容 `hello world\\n`。\n\n## 5. 待确认问题\n\n- 暂无\n\n## 6. 任务清单\n\n- [x] 在仓库根新建 `HELLO.txt`，内容 `hello world\\n`，验收点：文件存在且字节数 = 12。\n\n## 7. 追加任务\n\n- [open] 在 `HELLO.txt` 末尾追加一行 `goodbye world\\n`，验收点：最终文件含 2 行、共 26 字节。\n\n## 8. 执行记录\n\n- 2026-06-20 创建 `HELLO.txt`，内容 `hello world\\n`。\n";
 const __vite_glob_0_4 = '{\n  "module": "execute"\n}\n';
 const __vite_glob_0_5 = "---\nstage: execute\nlast_action: 任务已就绪，等待执行\nupdated_at: 2026-06-20\nsummary: 在仓库根新增 HELLO.txt 占位文件，内容为 hello world。\n---\n\n# HELLO 占位\n\n## 1. 背景\n\n希望在仓库根有一个 HELLO.txt 占位文件，用于演示 execute 阶段的勾选行为。\n\n## 2. 需求\n\n- 在仓库根创建 `HELLO.txt`，内容固定为 `hello world\\n`\n\n## 3. 现状分析\n\n仓库根目前没有 `HELLO.txt`，需新建。\n\n## 4. 技术实现方案\n\n- 直接写入 `HELLO.txt`，内容 `hello world\\n`，无 BOM、无尾随空行。\n\n## 5. 待确认问题\n\n- 暂无\n\n## 6. 任务清单\n\n- [ ] 在仓库根新建 `HELLO.txt`，内容为 `hello world\\n`，验收点：文件存在且内容字节数 = 12。\n\n## 7. 追加任务\n\n- 暂无\n\n## 8. 执行记录\n\n- 暂无\n";
@@ -97,7 +97,7 @@ const __vite_glob_0_38 = '> **Warning**\n>\n> ## THIS IS AN AUTOGENERATED FILE.
 const __vite_glob_0_39 = '> **Warning**\n>\n> ## THIS IS AN AUTOGENERATED FILE. DO NOT EDIT.\n>\n> ## Please edit the corresponding file in [/packages/mermaid/src/docs/syntax/treemap.md](../../packages/mermaid/src/docs/syntax/treemap.md).\n\n# Treemap Diagram\n\n> A treemap diagram displays hierarchical data as a set of nested rectangles. Each branch of the tree is represented by a rectangle, which is then tiled with smaller rectangles representing sub-branches.\n\n> **Warning**\n> This is a new diagram type in Mermaid. Its syntax may evolve in future versions.\n\n## Introduction\n\nTreemap diagrams are an effective way to visualize hierarchical data and show proportions between categories and subcategories. The size of each rectangle is proportional to the value it represents, making it easy to compare different parts of a hierarchy.\n\nTreemap diagrams are particularly useful for:\n\n- Visualizing hierarchical data structures\n- Comparing proportions between categories\n- Displaying large amounts of hierarchical data in a limited space\n- Identifying patterns and outliers in hierarchical data\n\n## Syntax\n\n```\ntreemap-beta\n"Section 1"\n    "Leaf 1.1": 12\n    "Section 1.2"\n      "Leaf 1.2.1": 12\n"Section 2"\n    "Leaf 2.1": 20\n    "Leaf 2.2": 25\n```\n\n### Node Definition\n\nNodes in a treemap are defined using the following syntax:\n\n- **Section/Parent nodes**: Defined with quoted text `"Section Name"`\n- **Leaf nodes with values**: Defined with quoted text followed by a colon and value `"Leaf Name": value`\n- **Hierarchy**: Created using indentation (spaces or tabs)\n- **Styling**: Nodes can be styled using the `:::class` syntax\n\n## Examples\n\n### Basic Treemap\n\n```mermaid-example\ntreemap-beta\n"Category A"\n    "Item A1": 10\n    "Item A2": 20\n"Category B"\n    "Item B1": 15\n    "Item B2": 25\n```\n\n```mermaid\ntreemap-beta\n"Category A"\n    "Item A1": 10\n    "Item A2": 20\n"Category B"\n    "Item B1": 15\n    "Item B2": 25\n```\n\n### Hierarchical Treemap\n\n```mermaid-example\ntreemap-beta\n"Products"\n    "Electronics"\n        "Phones": 50\n        "Computers": 30\n        "Accessories": 20\n    "Clothing"\n        "Men\'s": 40\n        "Women\'s": 40\n```\n\n```mermaid\ntreemap-beta\n"Products"\n    "Electronics"\n        "Phones": 50\n        "Computers": 30\n        "Accessories": 20\n    "Clothing"\n        "Men\'s": 40\n        "Women\'s": 40\n```\n\n### Treemap with Styling\n\n```mermaid-example\ntreemap-beta\n"Section 1"\n    "Leaf 1.1": 12\n    "Section 1.2":::class1\n      "Leaf 1.2.1": 12\n"Section 2"\n    "Leaf 2.1": 20:::class1\n    "Leaf 2.2": 25\n    "Leaf 2.3": 12\n\nclassDef class1 fill:red,color:blue,stroke:#FFD600;\n```\n\n```mermaid\ntreemap-beta\n"Section 1"\n    "Leaf 1.1": 12\n    "Section 1.2":::class1\n      "Leaf 1.2.1": 12\n"Section 2"\n    "Leaf 2.1": 20:::class1\n    "Leaf 2.2": 25\n    "Leaf 2.3": 12\n\nclassDef class1 fill:red,color:blue,stroke:#FFD600;\n```\n\n## Styling and Configuration\n\nTreemap diagrams can be customized using Mermaid\'s styling and configuration options.\n\n### Using classDef for Styling\n\nYou can define custom styles for nodes using the `classDef` syntax, which is a standard feature across many Mermaid diagram types:\n\n```mermaid-example\ntreemap-beta\n"Main"\n    "A": 20\n    "B":::important\n        "B1": 10\n        "B2": 15\n    "C": 5\n\nclassDef important fill:#f96,stroke:#333,stroke-width:2px;\n```\n\n```mermaid\ntreemap-beta\n"Main"\n    "A": 20\n    "B":::important\n        "B1": 10\n        "B2": 15\n    "C": 5\n\nclassDef important fill:#f96,stroke:#333,stroke-width:2px;\n```\n\n### Theme Configuration\n\nYou can customize the colors of your treemap using the theme configuration:\n\n```mermaid-example\n---\nconfig:\n    theme: \'forest\'\n---\ntreemap-beta\n"Category A"\n    "Item A1": 10\n    "Item A2": 20\n"Category B"\n    "Item B1": 15\n    "Item B2": 25\n```\n\n```mermaid\n---\nconfig:\n    theme: \'forest\'\n---\ntreemap-beta\n"Category A"\n    "Item A1": 10\n    "Item A2": 20\n"Category B"\n    "Item B1": 15\n    "Item B2": 25\n```\n\n### Diagram Padding\n\nYou can adjust the padding around the treemap diagram using the `diagramPadding` configuration option:\n\n```mermaid-example\n---\nconfig:\n  treemap:\n    diagramPadding: 200\n---\ntreemap-beta\n"Category A"\n    "Item A1": 10\n    "Item A2": 20\n"Category B"\n    "Item B1": 15\n    "Item B2": 25\n```\n\n```mermaid\n---\nconfig:\n  treemap:\n    diagramPadding: 200\n---\ntreemap-beta\n"Category A"\n    "Item A1": 10\n    "Item A2": 20\n"Category B"\n    "Item B1": 15\n    "Item B2": 25\n```\n\n## Configuration Options\n\nThe treemap diagram supports the following configuration options:\n\n| Option         | Description                                                                 | Default |\n| -------------- | --------------------------------------------------------------------------- | ------- |\n| useMaxWidth    | When true, the diagram width is set to 100% and scales with available space | true    |\n| padding        | Internal padding between nodes                                              | 10      |\n| diagramPadding | Padding around the entire diagram                                           | 8       |\n| showValues     | Whether to show values in the treemap                                       | true    |\n| nodeWidth      | Width of nodes                                                              | 100     |\n| nodeHeight     | Height of nodes                                                             | 40      |\n| borderWidth    | Width of borders                                                            | 1       |\n| valueFontSize  | Font size for values                                                        | 12      |\n| labelFontSize  | Font size for labels                                                        | 14      |\n| valueFormat    | Format for values (see Value Formatting section)                            | \',\'     |\n\n## Advanced Features\n\n### Value Formatting\n\nValues in treemap diagrams can be formatted to display in different ways using the `valueFormat` configuration option. This option primarily uses [D3\'s format specifiers](https://github.com/d3/d3-format#locale_format) to control how numbers are displayed, with some additional special cases for common formats.\n\nSome common format patterns:\n\n- `,` - Thousands separator (default)\n- `$` - Add dollar sign\n- `.1f` - Show one decimal place\n- `.1%` - Show as percentage with one decimal place\n- `$0,0` - Dollar sign with thousands separator\n- `$.2f` - Dollar sign with 2 decimal places\n- `$,.2f` - Dollar sign with thousands separator and 2 decimal places\n\nThe treemap diagram supports both standard D3 format specifiers and some common currency formats that combine the dollar sign with other formatting options.\n\nExample with currency formatting:\n\n```mermaid-example\n---\nconfig:\n  treemap:\n    valueFormat: \'$0,0\'\n---\ntreemap-beta\n"Budget"\n    "Operations"\n        "Salaries": 700000\n        "Equipment": 200000\n        "Supplies": 100000\n    "Marketing"\n        "Advertising": 400000\n        "Events": 100000\n```\n\n```mermaid\n---\nconfig:\n  treemap:\n    valueFormat: \'$0,0\'\n---\ntreemap-beta\n"Budget"\n    "Operations"\n        "Salaries": 700000\n        "Equipment": 200000\n        "Supplies": 100000\n    "Marketing"\n        "Advertising": 400000\n        "Events": 100000\n```\n\nExample with percentage formatting:\n\n```mermaid-example\n---\nconfig:\n  treemap:\n    valueFormat: \'$.1%\'\n---\ntreemap-beta\n"Market Share"\n    "Company A": 0.35\n    "Company B": 0.25\n    "Company C": 0.15\n    "Others": 0.25\n```\n\n```mermaid\n---\nconfig:\n  treemap:\n    valueFormat: \'$.1%\'\n---\ntreemap-beta\n"Market Share"\n    "Company A": 0.35\n    "Company B": 0.25\n    "Company C": 0.15\n    "Others": 0.25\n```\n\n## Common Use Cases\n\nTreemap diagrams are commonly used for:\n\n1. **Financial Data**: Visualizing budget allocations, market shares, or portfolio compositions\n2. **File System Analysis**: Showing disk space usage by folders and files\n3. **Population Demographics**: Displaying population distribution across regions and subregions\n4. **Product Hierarchies**: Visualizing product categories and their sales volumes\n5. **Organizational Structures**: Representing departments and team sizes in a company\n\n## Limitations\n\n- Treemap diagrams work best when the data has a natural hierarchy\n- Very small values may be difficult to see or label in a treemap diagram\n- Deep hierarchies (many levels) can be challenging to represent clearly\n- Treemap diagrams are not well suited for representing data with negative values\n\n## Related Diagrams\n\nIf treemap diagrams don\'t suit your needs, consider these alternatives:\n\n- [**Pie Charts**](./pie.md): For simple proportion comparisons without hierarchy\n- **Sunburst Diagrams**: For hierarchical data with a radial layout (yet to be released in Mermaid).\n- [**Sankey Diagrams**](./sankey.md): For flow-based hierarchical data\n\n## Notes\n\nThe treemap diagram implementation in Mermaid is designed to be simple to use while providing powerful visualization capabilities. As this is a newer diagram type, feedback and feature requests are welcome through the Mermaid GitHub repository.\n';
 const __vite_glob_0_40 = '> **Warning**\n>\n> ## THIS IS AN AUTOGENERATED FILE. DO NOT EDIT.\n>\n> ## Please edit the corresponding file in [/packages/mermaid/src/docs/syntax/xyChart.md](../../packages/mermaid/src/docs/syntax/xyChart.md).\n\n# XY Chart\n\n> In the context of mermaid-js, the XY chart is a comprehensive charting module that encompasses various types of charts that utilize both x-axis and y-axis for data representation. Presently, it includes two fundamental chart types: the bar chart and the line chart. These charts are designed to visually display and analyze data that involve two numerical variables.\n\n> It\'s important to note that while the current implementation of mermaid-js includes these two chart types, the framework is designed to be dynamic and adaptable. Therefore, it has the capacity for expansion and the inclusion of additional chart types in the future. This means that users can expect an evolving suite of charting options within the XY chart module, catering to various data visualization needs as new chart types are introduced over time.\n\n## Example\n\n```mermaid-example\nxychart\n    title "Sales Revenue"\n    x-axis [jan, feb, mar, apr, may, jun, jul, aug, sep, oct, nov, dec]\n    y-axis "Revenue (in $)" 4000 --> 11000\n    bar [5000, 6000, 7500, 8200, 9500, 10500, 11000, 10200, 9200, 8500, 7000, 6000]\n    line [5000, 6000, 7500, 8200, 9500, 10500, 11000, 10200, 9200, 8500, 7000, 6000]\n```\n\n```mermaid\nxychart\n    title "Sales Revenue"\n    x-axis [jan, feb, mar, apr, may, jun, jul, aug, sep, oct, nov, dec]\n    y-axis "Revenue (in $)" 4000 --> 11000\n    bar [5000, 6000, 7500, 8200, 9500, 10500, 11000, 10200, 9200, 8500, 7000, 6000]\n    line [5000, 6000, 7500, 8200, 9500, 10500, 11000, 10200, 9200, 8500, 7000, 6000]\n```\n\n## Syntax\n\n> **Note**\n> All text values that contain only one word can be written without `"`. If a text value has many words in it, specifically if it contains spaces, enclose the value in `"`\n\n### Orientations\n\nThe chart can be drawn horizontal or vertical, default value is vertical.\n\n```\nxychart horizontal\n...\n```\n\n### Title\n\nThe title is a short description of the chart and it will always render on top of the chart.\n\n#### Example\n\n```\nxychart\n    title "This is a simple example"\n    ...\n```\n\n> **Note**\n> If the title is a single word one no need to use `"`, but if it has space `"` is needed\n\n### x-axis\n\nThe x-axis primarily serves as a categorical value, although it can also function as a numeric range value when needed.\n\n#### Example\n\n1. `x-axis title min --> max` x-axis will function as numeric with the given range\n2. `x-axis "title with space" [cat1, "cat2 with space", cat3]` x-axis if categorical, categories are text type\n\n### y-axis\n\nThe y-axis is employed to represent numerical range values, it cannot have categorical values.\n\n#### Example\n\n1. `y-axis title min --> max`\n2. `y-axis title` it will only add the title, the range will be auto generated from data.\n\n> **Note**\n> Both x and y axis are optional if not provided we will try to create the range\n\n### Line chart\n\nA line chart offers the capability to graphically depict lines.\n\n#### Example\n\n1. `line [2.3, 45, .98, -3.4]` it can have all valid numeric values.\n2. `line "series name" [2.3, 45, .98, -3.4]` adds the line to the legend.\n\n### Bar chart\n\nA bar chart offers the capability to graphically depict bars.\n\n#### Example\n\n1. `bar [2.3, 45, .98, -3.4]` it can have all valid numeric values.\n2. `bar "series name" [2.3, 45, .98, -3.4]` adds the bar to the legend.\n\n### Legend (v\\<MERMAID_RELEASE_VERSION>+)\n\nNamed line and bar plots are automatically shown in a legend. Unnamed plots are omitted from the legend.\n\n```mermaid-example\nxychart-beta\n  title "An Example Chart"\n  x-axis ["90d", "60d", "30d", "7d", "1d", "Current"]\n  y-axis "Seconds" 0 --> 198.2\n  line "avg" [48.1, 41.5, 45.7, 72.8, 67.7, 59.9]\n  line "p50" [38.2, 36.8, 39.7, 54.5, 49.0, 38.4]\n  line "p95" [112.2, 75.3, 103.0, 177.0, 180.2, 109.4]\n```\n\n```mermaid\nxychart-beta\n  title "An Example Chart"\n  x-axis ["90d", "60d", "30d", "7d", "1d", "Current"]\n  y-axis "Seconds" 0 --> 198.2\n  line "avg" [48.1, 41.5, 45.7, 72.8, 67.7, 59.9]\n  line "p50" [38.2, 36.8, 39.7, 54.5, 49.0, 38.4]\n  line "p95" [112.2, 75.3, 103.0, 177.0, 180.2, 109.4]\n```\n\n#### Simplest example\n\nThe only two things required are the chart name (`xychart`) and one data set. So you will be able to draw a chart with a simple config like\n\n```\nxychart\n    line [+1.3, .6, 2.4, -.34]\n```\n\n## Chart Configurations\n\n| Parameter                | Description                                                   | Default value |\n| ------------------------ | ------------------------------------------------------------- | :-----------: |\n| width                    | Width of the chart                                            |      700      |\n| height                   | Height of the chart                                           |      500      |\n| titlePadding             | Top and Bottom padding of the title                           |      10       |\n| titleFontSize            | Title font size                                               |      20       |\n| showTitle                | Title to be shown or not                                      |     true      |\n| showLegend               | Legend to be shown for named plots or not                     |     true      |\n| legendFontSize           | Legend font size                                              |      14       |\n| legendPadding            | Padding around the legend                                     |      10       |\n| xAxis                    | xAxis configuration                                           |  AxisConfig   |\n| yAxis                    | yAxis configuration                                           |  AxisConfig   |\n| chartOrientation         | \'vertical\' or \'horizontal\'                                    |  \'vertical\'   |\n| plotReservedSpacePercent | Minimum space plots will take inside the chart                |      50       |\n| showDataLabel            | Should show the value corresponding to the bar within the bar |     false     |\n| showDataLabelOutsideBar  | If showing data label then show it outside the bar.           |     false     |\n\n### AxisConfig\n\n| Parameter     | Description                                                  | Default value |\n| ------------- | ------------------------------------------------------------ | :-----------: |\n| showLabel     | Show axis labels or tick values                              |     true      |\n| labelFontSize | Font size of the label to be drawn                           |      14       |\n| labelPadding  | Top and Bottom padding of the label                          |       5       |\n| showTitle     | Axis title to be shown or not                                |     true      |\n| titleFontSize | Axis title font size                                         |      16       |\n| titlePadding  | Top and Bottom padding of Axis title                         |       5       |\n| showTick      | Tick to be shown or not                                      |     true      |\n| tickLength    | How long the tick will be                                    |       5       |\n| tickWidth     | How width the tick will be                                   |       2       |\n| showAxisLine  | Axis line to be shown or not                                 |     true      |\n| axisLineWidth | Thickness of the axis line                                   |       2       |\n| labelRotation | Label rotation in degrees (only applicable on bottom X axis) |       0       |\n\n## Chart Theme Variables\n\nThemes for xychart reside inside the `xychart` attribute, allowing customization through the following syntax:\n\n```yaml\n---\nconfig:\n  themeVariables:\n    xyChart:\n      titleColor: \'#ff0000\'\n---\n```\n\n| Parameter        | Description                                               |\n| ---------------- | --------------------------------------------------------- |\n| backgroundColor  | Background color of the whole chart                       |\n| titleColor       | Color of the Title text                                   |\n| dataLabelColor   | Color of the Data labels (if shown)                       |\n| legendTextColor  | Color of the legend text                                  |\n| xAxisLabelColor  | Color of the x-axis labels                                |\n| xAxisTitleColor  | Color of the x-axis title                                 |\n| xAxisTickColor   | Color of the x-axis tick                                  |\n| xAxisLineColor   | Color of the x-axis line                                  |\n| yAxisLabelColor  | Color of the y-axis labels                                |\n| yAxisTitleColor  | Color of the y-axis title                                 |\n| yAxisTickColor   | Color of the y-axis tick                                  |\n| yAxisLineColor   | Color of the y-axis line                                  |\n| plotColorPalette | String of colors separated by comma e.g. "#f3456, #43445" |\n\n### Setting Colors for Lines and Bars\n\nTo set the color for lines and bars, use the `plotColorPalette` parameter. Colors in the palette will correspond sequentially to the elements in your chart (e.g., first bar/line will use the first color specified in the palette).\n\n```mermaid-example\n---\nconfig:\n  themeVariables:\n    xyChart:\n      plotColorPalette: \'#000000, #0000FF, #00FF00, #FF0000\'\n---\nxychart\ntitle "Different Colors in xyChart"\nx-axis "categoriesX" ["Category 1", "Category 2", "Category 3", "Category 4"]\ny-axis "valuesY" 0 --> 50\n%% Black line\nline [10,20,30,40]\n%% Blue bar\nbar [20,30,25,35]\n%% Green bar\nbar [15,25,20,30]\n%% Red line\nline [5,15,25,35]\n```\n\n```mermaid\n---\nconfig:\n  themeVariables:\n    xyChart:\n      plotColorPalette: \'#000000, #0000FF, #00FF00, #FF0000\'\n---\nxychart\ntitle "Different Colors in xyChart"\nx-axis "categoriesX" ["Category 1", "Category 2", "Category 3", "Category 4"]\ny-axis "valuesY" 0 --> 50\n%% Black line\nline [10,20,30,40]\n%% Blue bar\nbar [20,30,25,35]\n%% Green bar\nbar [15,25,20,30]\n%% Red line\nline [5,15,25,35]\n```\n\n## Displaying individual values on a bar chart (v11.14.0+)\n\nTo show the value corresponding to a bar specify `showDataLabel: true`.\n\n```mermaid-example\n---\nconfig:\n    xyChart:\n        showDataLabel: true\n---\nxychart\n    title "Genres in top 100 book survey of 2025"\n    x-axis [comedy, romance, mystery, crime, "non fiction", other]\n    y-axis "Number of Books" 0 --> 30\n    bar [12,2,20,25,17,24]\n```\n\n```mermaid\n---\nconfig:\n    xyChart:\n        showDataLabel: true\n---\nxychart\n    title "Genres in top 100 book survey of 2025"\n    x-axis [comedy, romance, mystery, crime, "non fiction", other]\n    y-axis "Number of Books" 0 --> 30\n    bar [12,2,20,25,17,24]\n```\n\nLabels are shown within the bar by default. To show the labels outside the bar, specify `showDataLabelOutsideBar: true`.\n\n```mermaid-example\n---\nconfig:\n    xyChart:\n        showDataLabel: true\n        showDataLabelOutsideBar: true\n---\nxychart\n    title "Genres in top 100 book survey of 2025"\n    x-axis [comedy, romance, mystery, crime, "non fiction", other]\n    y-axis "Number of Books" 0 --> 30\n    bar [12,2,20,25,17,24]\n```\n\n```mermaid\n---\nconfig:\n    xyChart:\n        showDataLabel: true\n        showDataLabelOutsideBar: true\n---\nxychart\n    title "Genres in top 100 book survey of 2025"\n    x-axis [comedy, romance, mystery, crime, "non fiction", other]\n    y-axis "Number of Books" 0 --> 30\n    bar [12,2,20,25,17,24]\n```\n\n## Per-point text labels for line charts (v\\<MERMAID_RELEASE_VERSION>+)\n\nEach data point in a `line` can optionally include a quoted string label after the numeric value. Labels render above points in vertical orientation, or to the right in horizontal orientation, using the line\'s stroke color.\n\n```mermaid-example\nxychart\n    title "Smallest AI models scoring above 60% on MMLU"\n    x-axis "Date" ["Apr 2022", "Feb 2023", "Jul 2023", "Sep 2023", "Apr 2024"]\n    y-axis "Parameters (B)" 0 --> 600\n    line [540 "PaLM", 65 "LLaMA-65B", 34 "Llama 2 34B", 7 "Mistral 7B", 3.8 "Phi-3-mini"]\n```\n\n```mermaid\nxychart\n    title "Smallest AI models scoring above 60% on MMLU"\n    x-axis "Date" ["Apr 2022", "Feb 2023", "Jul 2023", "Sep 2023", "Apr 2024"]\n    y-axis "Parameters (B)" 0 --> 600\n    line [540 "PaLM", 65 "LLaMA-65B", 34 "Llama 2 34B", 7 "Mistral 7B", 3.8 "Phi-3-mini"]\n```\n\nLabels are optional per point — you can mix labeled and unlabeled values:\n\n```mermaid-example\nxychart\n    title "Quarterly Performance"\n    x-axis [Q1, Q2, Q3, Q4]\n    y-axis "Revenue ($M)" 0 --> 100\n    line [25 "Launch", 45, 72, 90 "Target Hit"]\n```\n\n```mermaid\nxychart\n    title "Quarterly Performance"\n    x-axis [Q1, Q2, Q3, Q4]\n    y-axis "Revenue ($M)" 0 --> 100\n    line [25 "Launch", 45, 72, 90 "Target Hit"]\n```\n\nExisting syntax without labels continues to work unchanged.\n\n> **Note**\n> Point labels use a fixed font size of 12px. In vertical charts, labels appear above each point. In horizontal charts, labels appear to the right. Labels are currently supported on `line` plots only; the syntax is accepted on `bar` plots but labels are ignored.\n\n## Example on config and theme\n\n```mermaid-example\n---\nconfig:\n    xyChart:\n        width: 900\n        height: 600\n        showDataLabel: true\n    themeVariables:\n        xyChart:\n            titleColor: "#ff0000"\n---\nxychart\n    title "Sales Revenue"\n    x-axis [jan, feb, mar, apr, may, jun, jul, aug, sep, oct, nov, dec]\n    y-axis "Revenue (in $)" 4000 --> 11000\n    bar [5000, 6000, 7500, 8200, 9500, 10500, 11000, 10200, 9200, 8500, 7000, 6000]\n    line [5000, 6000, 7500, 8200, 9500, 10500, 11000, 10200, 9200, 8500, 7000, 6000]\n```\n\n```mermaid\n---\nconfig:\n    xyChart:\n        width: 900\n        height: 600\n        showDataLabel: true\n    themeVariables:\n        xyChart:\n            titleColor: "#ff0000"\n---\nxychart\n    title "Sales Revenue"\n    x-axis [jan, feb, mar, apr, may, jun, jul, aug, sep, oct, nov, dec]\n    y-axis "Revenue (in $)" 4000 --> 11000\n    bar [5000, 6000, 7500, 8200, 9500, 10500, 11000, 10200, 9200, 8500, 7000, 6000]\n    line [5000, 6000, 7500, 8200, 9500, 10500, 11000, 10200, 9200, 8500, 7000, 6000]\n```\n';
 const __vite_glob_0_41 = '# Review / Git Ops 阶段说明\n\n本文件描述 service 端拉起 `mode=review` / `mode=git-ops`（带 `action`）时，Agent 应遵守的输入解析、输出格式与 git 安全约束。**这条路径不进入 plan/tasks/execute 状态机**，亦不修改 spec.md 的 frontmatter `stage`。\n\n## mode=review\n\n输入：\n\n- spec 文档路径（`<spec_path>`），同目录可能已存在 `review.md`。\n- 当前 git 仓库的未提交变更（`git status -sb` / `git diff` / `git diff --staged`）。\n\n行为：\n\n1. 读取 `<spec_path>` 与 git 变更，理解本次改动相对该 spec 的语义。\n2. 将结构化 review 报告**按时间降序插入**到 `<spec_dir>/review.md`（与 spec.md 同级），使**最新条目位于文件顶部**。\n   - 若 `review.md` 不存在：先写入一行 `# Review · <spec-id>` 作为一级标题，然后再追加本次条目。\n   - 若已存在：**禁止覆盖**历史条目；将本次二级标题及其正文块**插入到 `# Review · <spec-id>` 一级标题之后、既有第一个 `## ` 二级标题之前**，使 review 条目按时间降序（最新在顶）排列。一级标题与新条目之间保留 1 个空行，新条目与后续既有条目之间保留 1 个空行。\n3. 每次 review 的二级标题使用本机当前时间 `## YYYY-MM-DD HH:mm:ss`，时间格式与 spec frontmatter 一致。\n4. 每个二级标题下必须依次包含 4 个三级小节，顺序固定：\n\n   ```markdown\n   ## 2026-06-30 14:23:01\n\n   ### 变更总结\n\n   <内容>\n\n   ### 影响范围\n\n   <内容>\n\n   ### 风险提醒\n\n   <内容>\n\n   ### 变更文件清单\n\n   - path/to/a.ts\n   - path/to/b.tsx\n   ```\n\n5. 报告写完即结束本轮；不要修改 `spec.md`、不要执行任何 git 写操作。\n\n## mode=git-ops + action=commit\n\n- 输入：spec 文档 + 最近一次 `review.md` 条目（若存在）+ 当前 `git status`。\n- 由 Agent **自主决定**本次要提交的 spec 相关变更文件清单；优先以最近 review 的"变更文件清单"为锚，结合 `git status` 中实际存在的未提交文件做交集。\n- commit message 由 Agent 基于 review 总结自行生成；不附加 `[spec:<id>]` 锚点，不带 scope（遵循 `260630.refct.review-commit-msg-remove-scope`）。\n- 仅允许使用 `git add <paths>` + `git commit -m <message>`；**禁止** `git push` / `git reset --hard` / `git rebase` / 修改任何已提交历史。\n\n## mode=git-ops + action=discard\n\n- 使用 `git restore --staged --worktree -- <paths>` 丢弃已 tracked 的修改；untracked 新文件使用 `git clean -fd -- <paths>` 清理。\n- 对 untracked 文件先在终端输出待清理列表，再执行 clean，便于日志回溯。\n- **不**预先 `git stash` 作为"保险备份"（遵循用户显式意图，保持轻量）。\n- **禁止** `git reset --hard`、`git push`。\n\n## mode=git-ops + action=stash\n\n- 使用 `git stash push -m "yorz:<spec-id>" -- <paths>`，仅暂存 spec 相关变更文件。\n- 不要使用 `git stash --all` 之类会影响 untracked / ignored 文件的形式，除非明确需要。\n- **禁止** `git push`。\n\n## 通用硬约束\n\n- 仅操作 `<spec_path>`、`<spec_dir>/review.md` 与 git 工作区文件；不修改无关 spec、不修改本 skill 文件。\n- 任一 git 子命令失败时，把错误信息写入终端日志（service 端会落盘到 agent-logs），不要静默吞掉。\n- 元确认禁令同 SKILL.md「持续推进硬约束」：不向用户回问"是否继续 / 是否执行"等问题（GUI 已在按钮触发前做过必要的二次确认）。\n';
-const __vite_glob_0_42 = '# 阶段流程（plan / tasks / execute / done / new-spec）\n\n## plan\n\n理解文档，分析现有代码，编写技术实现方案，更新到当前文档中；需要用户介入的事项以三级标题写入 `## 待确认项`，待用户后续审阅批注；暂时只需更新文档，不要实施代码。\n\n**目标：** 输出 `## 现状分析`、`## 技术实现方案`、`## 待确认项` 三节；禁止输出任务清单格式 `- [ ]`。\n\n若 `## 追加任务` 存在 `- [open] [feat|refct|fix] ...` 条目，必须将其纳入分析范围；plan 阶段不修改 `[open]` 状态标记。\n\n### 待确认项的三种类型\n\n一个待确认项，要么让用户**抉择**，要么让用户**确认**，要么请用户**自由补充**：\n\n| 类型     | 标记                | 语义                                                                                    | 何时用                |\n| -------- | ------------------- | --------------------------------------------------------------------------------------- | --------------------- |\n| 抉择型   | `[choice]`          | 给用户**选择权**：存在多个都可行、优劣取决于你拿不到的信息（业务优先级/外部约束）的方案 | 多方案差异大、难取舍  |\n| 确认型   | `[confirm]`         | 给用户**否决权**：只有一个可行方案，但它有明显代价（技术债/影响面/不可逆）              | 单方案但影响重大      |\n| 自由文本 | `（自由文本）` 后缀 | 请用户补一段开放说明                                                                    | 需要主观文案/开放意见 |\n\n> 无标记且带有序候选，向后兼容视为 `[choice]`。\n\n### 准入门槛（写入待确认项前必过的自检）\n\n**第一道过滤器先于类型判断**：这个答案，你能否通过读代码、跑测试、查项目约定自己确定？\n\n- **能** → 禁止写成待确认项，自己去查、去定，把决策+理由写进 `## 技术实现方案`（决策说明），不要打断用户。\n- **不能**（决策依赖用户独有信息，或选错的返工不可逆）→ 才写成待确认项，并归入 choice/confirm。\n\n> 待确认项是压力释放阀，不是免责声明。被你砍掉的判断不该凭空消失，要落成 `## 技术实现方案` 里的决策说明（决策 + 理由 + 被否决的备选）。\n\n### 抉择型 [choice] 正确示例\n\n```\n### 5.1 [choice] 候选答案的展现形式应采用哪种？\n1. 嵌套子列表\n2. 表格 (推荐)\n```\n\n- 候选写一级有序列表；恰 1 个候选以 ` (推荐)` / ` （推荐）` 结尾。\n- 空态与格式由 lint 的 `pending-questions/*` 规则保证。\n\n### 确认型 [confirm] 正确示例\n\n```\n### 5.2 [confirm] 将 UserID 从 int 迁移为 uuid\n\n**方案**：一次性迁移，双写过渡 2 周。\n**影响**：🔴 需停机窗口；对外 /api/user 字段类型变更，客户端需同步。\n```\n\n- 只有 `**方案**` 与 `**影响**`（或 `**代价**`）两字段，**不列候选**。\n- 影响行用红/黄语义标注严重度：🔴 breaking（破坏性/不可逆）、🟡 affected（有影响但可控）。\n- 确认型 = "我要这么干了，除非你喊停" 的知会 + 急停按钮：放行是常态，用户否决才是例外。\n\n### 确认型的否决语义（用户在 GUI 上如何回应）\n\n用户对确认型只有两种回应：**确认放行** 或 **否决**。否决必须携带理由，并细分意图（GUI 渲染为嵌套单选）：\n\n| 用户决策                  | 回写 `！！！选择：…`                 | 含义                   |\n| ------------------------- | ------------------------------------ | ---------------------- |\n| 确认，按此推进            | `确认，按此推进`                     | 接受代价，继续         |\n| 否决·换方案               | `否决·换方案`                        | 原目标下另寻实现       |\n| 否决·补约束               | `否决·补约束`                        | 用户补充你漏掉的硬约束 |\n| 否决·弃目标·废弃当前目标  | `否决·弃目标·废弃当前目标，继续其余` | 该目标不做，其余照旧   |\n| 否决·弃目标·放弃整个 spec | `否决·弃目标·放弃整个 spec`          | 整条 spec 作废         |\n\n> 决策不改动 API：编码进批注的 `选择：…`（结构化意图）+ `备注：…`（理由）。tasks 阶段按下表消费。\n\n### 图形化补充（plan 收尾子步骤）\n\n方案文字定稿后、结束 plan 前，**必须**专门回看 `## 现状分析`、`## 技术实现方案` 两节做一次 mermaid 图形化补充（仅此两节，其它章节不动）：\n\n- 加载 [mermaid.md](./mermaid.md)，先服从其**核心原则「图优先、精确信息折叠」**：表层给图（认知层），精确细节（路径、行号、类型/源码全文）折叠进 `<details>` 精确层，图与折叠互补不重复。\n- 按选型表与「必须用图」触发词补图：分步/分支散文→flowchart，接口/类型定义→classDiagram；含「兼容性/影响范围」时出结构图并按红=breaking、黄=affected 语义配色。\n- 这是一道独立聚焦的工序（不新增 stage）：把「想清楚方案 / 写成文字」与「回看补图」分开，避免图形化被跳过。补图完成后再结束 plan。\n\n### 待确认项自检（plan 收尾子步骤）\n\n方案与图形化定稿后、结束 plan 前，**必须**专门回看 `## 待确认项` 做一次自检（与「图形化补充」同构：把"写方案"与"回看校验"分开，避免自检被跳过）：\n\n1. **准入过滤**：逐条问"能否自己查证？"——能则删除该条、把决策落进 `## 技术实现方案`（决策说明）。\n2. **类型归类**：留下的每条明确标 `[choice]` 或 `[confirm]`（或 `（自由文本）`）；单一类型，不兼具。\n3. **确认型补影响**：每个 `[confirm]` 必带 `**方案**` 与 `**影响**`（红/黄语义）；影响写不出来，说明它其实够不上确认型，降级或删除。\n\n自检完成后再结束 plan。\n\n空态整章仅一行斜体占位：\n\n```\n## 5. 待确认项\n\n_暂无_\n```\n\n> 格式由 lint 的 `pending-questions/*` 规则保证；不确定时运行 `yorz lint` 查看报错。\n\n## tasks\n\n根据批注内容（`！！！` 前缀）更新技术方案；审查批注是否正确解答了待确认项；若引入新增/扩展需求或新增 bug，切回 plan；若存在冲突或歧义，回退 plan 并写入待确认项后退出；否则将技术方案拆解为可执行任务，写入文档，然后进入 execute。\n\n### 批注消费规则\n\n- 读取并消费所有 `！！！` 批注，将批注意图合并进 `## 技术实现方案` 与 `## 任务清单`。\n- 处理完成后**删除对应 `！！！` 文本**，然后**整段删除** `## 用户批注` 章节。\n\n### 确认型答复的消费\n\n当批注含 `！！！选择：<决策>；备注：<理由>`（引用行的前缀 `待确认项`/`待确认问题` 皆可），按 `选择：` 分派下游行为，并**无论确认或否决都留痕**——在 `## 技术实现方案` 追加一行决策记录：`> 决策记录：<条目> —— 用户<决策>，理由：<理由>。`（决策记录不随 `## 用户批注` 删除而蒸发）：\n\n| `选择：`                           | 下游行为                                                                                       |\n| ---------------------------------- | ---------------------------------------------------------------------------------------------- |\n| 确认，按此推进                     | 接受代价，落决策记录，继续拆任务                                                               |\n| 否决·换方案                        | 切回 plan：原目标下另寻实现（新方案可能又产生 choice/confirm）                                 |\n| 否决·补约束                        | 切回 plan：把理由当硬约束重算方案                                                              |\n| 否决·弃目标·废弃当前目标，继续其余 | 从 `## 需求` 剔除该目标，落决策记录，继续其余目标                                              |\n| 否决·弃目标·放弃整个 spec          | 落决策记录（作废），将 `stage` 置 `done` 终止，`last_action` 记「用户放弃整个 spec，标记终止」 |\n\n### 任务清单正确示例\n\n```\n## 6. 任务清单\n\n- [ ] 删除 src/foo.ts 中的 deprecatedFunc（验收：grep 无残留引用）\n- [ ] 更新 index.ts 导出（验收：tsc --noEmit 通过）\n```\n\n> 每项任务包含"动作 + 对象 + 验收点"；仅使用单层 `- [ ]`；禁止泛化任务。\n\n### `[manual]` 人工确认任务标记\n\n对「需人工确认、Agent 不能自动完成」的事项，用 `- [ ] [manual] ...` 标注：\n\n```\n- [ ] [manual] 联系运维确认灰度窗口（验收：人工回复确认）\n```\n\n`done` 收尾判定**忽略**未勾选的 `[manual]` 项：只要其余非 manual 任务全部完成，即可收尾为 `done`，无需等待人工项被勾选（详见 execute 的「收尾为 done」）。\n\n### 自动衔接\n\n> 任务量不构成暂停理由：以下衔接规则与任务清单长度、改动半径无关。\n\n若待确认项为 `_暂无_` 且无新冲突，同一轮继续进入 execute，**同一轮衔接 execute 前后不得**向用户追加任何"是否执行/是否继续"询问。\n\n## execute\n\n顺序执行 `## 任务清单` 中未完成项（`- [ ]`）。执行中若发现新增/扩展需求或新增 bug，立即停止，切回 plan。\n\n> **执行过程中不得对用户做整批/中段元确认**：除"新需求/新 bug → 切回 plan"这一合法阻塞外，任务清单内部的任何疑问都必须以 `## 待确认项` 形式写回触发重开，禁止追加"是否继续 / 我是否应该执行下一项"等问句停顿。\n\n### 每完成一项后立刻\n\n- 将该项从 `- [ ]` 改为 `- [x]`。\n- 在 `## 执行记录` 增加一条结果（改动点、验证方式、阻塞项若有）。\n\n### 默认执行验证\n\n若仓库存在可用测试/构建命令，默认执行并记录结果；若当前环境无法执行，记录原因。\n\n### 追加任务 `[open] → [fixed]` 状态机\n\n若本轮起因是 `## 追加任务` 中的 `[open]` 条目：每完成一个追加项，把状态标记从 `[open]` 改为 `[fixed]`（位置和正文保留不变），在 `## 执行记录` 追加一条结果。已 `[fixed]` 的条目保留作为历史，不删除。\n\n### 收尾为 done\n\n当 `## 任务清单` 不存在未完成的**非 `[manual]`** 任务（`- [ ] [manual]` 人工确认项被忽略），且 `## 待确认项` 为 `_暂无_`、无任何 `！！！` 批注、无 `## 追加任务` 的 `[open]` 条目时，在 execute 收尾同一轮：\n\n- 将 `stage` 置为 `done`，`last_action` 记「任务全部完成，标记 done」。\n- 在 `## 执行记录` 追加一条收尾条目。\n\n`done` 是终止态：机器 / GUI 可据 `stage=done` 直接判定完成。此后不再自动推进；收到新增/扩展需求、新 bug，或 `## 追加任务` 出现 `[open]` 时，按「变更重开流程」切回 `plan`。\n\n## new-spec\n\n当 `spec_path` 缺省且无法从 session 上下文恢复时，自动生成路径与初始骨架。\n\n### 步骤\n\n1. **提炼摘要**：从用户输入提炼 kebab-case `summary-name`（≤ 40 字符，不以数字开头，必须语义化）。中文为主难以提炼时使用 `untitled-<NNN>` 占位。\n2. **判定 type**：`feat` / `refct` / `fix`；prompt 中已显式给出时直接使用；不确定时询问用户，兜底取 `feat`。\n3. **生成 id**：`YYMMDD.<type>.<summary-name>`（如 `260614.feat.spec-frontmatter`）。\n4. **生成路径**：`<specsDir>/<id>/spec.md`。id 冲突时追加 `-2`、`-3` 后缀。\n5. **初始化文档**：写入 frontmatter（`stage: plan`、`last_action: 新建 spec`、`updated_at` 秒级带单引号、`summary` ≤ 200 字符）；建议创建全部章节（背景 / 需求 / 现状分析 / 技术实现方案 / 待确认项 / 任务清单 / 执行记录），将用户原始需求写入背景或需求。\n6. **进入 plan**：初始化后在同一轮继续推进 plan，不要因为"文档已创建"就退出。\n\n### CLI 触发模式\n\nCLI/Service 同时给出 `类型：<type>` 与需求但未提供 `spec_path` 时，必须自动进入新建流程，不询问类型/路径；初始化后同一轮继续推进 plan，直到遇到真正阻塞才退出。\n';
+const __vite_glob_0_42 = '# 阶段流程（plan / tasks / execute / done / new-spec）\n\n## plan\n\n理解文档，分析现有代码，编写技术实现方案，更新到当前文档中；需要用户介入的事项以三级标题写入 `## 待确认项`，待用户后续审阅批注；暂时只需更新文档，不要实施代码。\n\n**目标：** 输出 `## 现状分析`、`## 技术实现方案`、`## 待确认项` 三节；禁止输出任务清单格式 `- [ ]`。\n\n若 `## 追加任务` 存在 `- [open] [feat|refct|fix] ...` 条目，必须将其纳入分析范围；plan 阶段不修改 `[open]` 状态标记。\n\n### 待确认项的三种类型\n\n一个待确认项，要么让用户**抉择**，要么让用户**确认**，要么请用户**自由补充**：\n\n| 类型     | 标记                | 语义                                                                                    | 何时用                |\n| -------- | ------------------- | --------------------------------------------------------------------------------------- | --------------------- |\n| 抉择型   | `[choice]`          | 给用户**选择权**：存在多个都可行、优劣取决于你拿不到的信息（业务优先级/外部约束）的方案 | 多方案差异大、难取舍  |\n| 确认型   | `[confirm]`         | 给用户**否决权**：只有一个可行方案，但它有明显代价（技术债/影响面/不可逆）              | 单方案但影响重大      |\n| 自由文本 | `（自由文本）` 后缀 | 请用户补一段开放说明                                                                    | 需要主观文案/开放意见 |\n\n> 无标记且带有序候选，向后兼容视为 `[choice]`。\n\n### 准入门槛（写入待确认项前必过的自检）\n\n**第一道过滤器先于类型判断**：这个答案，你能否通过读代码、跑测试、查项目约定自己确定？\n\n- **能** → 禁止写成待确认项，自己去查、去定，把决策+理由写进 `## 技术实现方案`（决策说明），不要打断用户。\n- **不能**（决策依赖用户独有信息，或选错的返工不可逆）→ 才写成待确认项，并归入 choice/confirm。\n\n> 待确认项是压力释放阀，不是免责声明。被你砍掉的判断不该凭空消失，要落成 `## 技术实现方案` 里的决策说明（决策 + 理由 + 被否决的备选）。\n\n### 抉择型 [choice] 正确示例\n\n```\n### 5.1 [choice] 候选答案的展现形式应采用哪种？\n1. 嵌套子列表\n2. 表格 (推荐)\n```\n\n- 候选写一级有序列表；恰 1 个候选以 ` (推荐)` / ` （推荐）` 结尾。\n- 空态与格式由 lint 的 `pending-questions/*` 规则保证。\n\n### 确认型 [confirm] 正确示例\n\n```\n### 5.2 [confirm] 将 UserID 从 int 迁移为 uuid\n\n**方案**：一次性迁移，双写过渡 2 周。\n**影响**：🔴 需停机窗口；对外 /api/user 字段类型变更，客户端需同步。\n```\n\n- 只有 `**方案**` 与 `**影响**`（或 `**代价**`）两字段，**不列候选**。\n- 影响行用红/黄语义标注严重度：🔴 breaking（破坏性/不可逆）、🟡 affected（有影响但可控）。\n- 确认型 = "我要这么干了，除非你喊停" 的知会 + 急停按钮：放行是常态，用户否决才是例外。\n\n### 确认型的否决语义（用户在 GUI 上如何回应）\n\n用户对确认型只有两种回应：**确认放行** 或 **否决**。否决必须携带理由，并细分意图（GUI 渲染为嵌套单选）：\n\n| 用户决策                  | 回写 `！！！选择：…`                 | 含义                   |\n| ------------------------- | ------------------------------------ | ---------------------- |\n| 确认，按此推进            | `确认，按此推进`                     | 接受代价，继续         |\n| 否决·换方案               | `否决·换方案`                        | 原目标下另寻实现       |\n| 否决·补约束               | `否决·补约束`                        | 用户补充你漏掉的硬约束 |\n| 否决·弃目标·废弃当前目标  | `否决·弃目标·废弃当前目标，继续其余` | 该目标不做，其余照旧   |\n| 否决·弃目标·放弃整个 spec | `否决·弃目标·放弃整个 spec`          | 整条 spec 作废         |\n\n> 决策不改动 API：编码进批注的 `选择：…`（结构化意图）+ `备注：…`（理由）。tasks 阶段按下表消费。\n\n### 图形化补充（plan 收尾子步骤）\n\n方案文字定稿后、结束 plan 前，**必须**专门回看 `## 现状分析`、`## 技术实现方案` 两节做一次 mermaid 图形化补充（仅此两节，其它章节不动）：\n\n- 加载 [mermaid.md](./mermaid.md)，先服从其**核心原则「图优先、精确信息折叠」**：表层给图（认知层），精确细节（路径、行号、类型/源码全文）折叠进 `<details>` 精确层，图与折叠互补不重复。\n- 按选型表与「必须用图」触发词补图：分步/分支散文→flowchart，接口/类型定义→classDiagram；含「兼容性/影响范围」时出结构图并按红=breaking、黄=affected 语义配色。\n- 这是一道独立聚焦的工序（不新增 stage）：把「想清楚方案 / 写成文字」与「回看补图」分开，避免图形化被跳过。补图完成后再结束 plan。\n\n### 待确认项自检（plan 收尾子步骤）\n\n方案与图形化定稿后、结束 plan 前，**必须**专门回看 `## 待确认项` 做一次自检（与「图形化补充」同构：把"写方案"与"回看校验"分开，避免自检被跳过）：\n\n1. **准入过滤**：逐条问"能否自己查证？"——能则删除该条、把决策落进 `## 技术实现方案`（决策说明）。\n2. **类型归类**：留下的每条明确标 `[choice]` 或 `[confirm]`（或 `（自由文本）`）；单一类型，不兼具。\n3. **确认型补影响**：每个 `[confirm]` 必带 `**方案**` 与 `**影响**`（红/黄语义）；影响写不出来，说明它其实够不上确认型，降级或删除。\n\n自检完成后再结束 plan。\n\n空态整章仅一行斜体占位：\n\n```\n## 5. 待确认项\n\n_暂无_\n```\n\n> 格式由 lint 的 `pending-questions/*` 规则保证；不确定时运行 `yorz lint` 查看报错。\n\n## tasks\n\n根据批注内容（`！！！` 前缀）更新技术方案；审查批注是否正确解答了待确认项；若引入新增/扩展需求或新增 bug，切回 plan；若存在冲突或歧义，回退 plan 并写入待确认项后退出；否则将技术方案拆解为可执行任务，写入文档，然后进入 execute。\n\n### 批注消费规则\n\n- 读取并消费所有 `！！！` 批注，将批注意图合并进 `## 技术实现方案` 与 `## 任务清单`。\n- 处理完成后**删除对应 `！！！` 文本**，然后**整段删除** `## 用户批注` 章节。\n\n### 确认型答复的消费\n\n当批注含 `！！！选择：<决策>；备注：<理由>`（引用行的前缀 `待确认项`/`待确认问题` 皆可），按 `选择：` 分派下游行为，并**无论确认或否决都留痕**——在 `## 技术实现方案` 追加一行决策记录：`> 决策记录：<条目> —— 用户<决策>，理由：<理由>。`（决策记录不随 `## 用户批注` 删除而蒸发）：\n\n| `选择：`                           | 下游行为                                                                                       |\n| ---------------------------------- | ---------------------------------------------------------------------------------------------- |\n| 确认，按此推进                     | 接受代价，落决策记录，继续拆任务                                                               |\n| 否决·换方案                        | 切回 plan：原目标下另寻实现（新方案可能又产生 choice/confirm）                                 |\n| 否决·补约束                        | 切回 plan：把理由当硬约束重算方案                                                              |\n| 否决·弃目标·废弃当前目标，继续其余 | 从 `## 需求` 剔除该目标，落决策记录，继续其余目标                                              |\n| 否决·弃目标·放弃整个 spec          | 落决策记录（作废），将 `stage` 置 `done` 终止，`last_action` 记「用户放弃整个 spec，标记终止」 |\n\n### 任务清单正确示例\n\n```\n## 6. 任务清单\n\n- [ ] 删除 src/foo.ts 中的 deprecatedFunc（验收：grep 无残留引用）\n- [ ] 更新 index.ts 导出（验收：tsc --noEmit 通过）\n```\n\n> 每项任务包含"动作 + 对象 + 验收点"；仅使用单层 `- [ ]`；禁止泛化任务。\n\n### `[manual]` 人工确认任务标记\n\n对「需人工确认、Agent 不能自动完成」的事项，用 `- [ ] [manual] ...` 标注：\n\n```\n- [ ] [manual] 联系运维确认灰度窗口（验收：人工回复确认）\n```\n\n`done` 收尾判定**忽略**未勾选的 `[manual]` 项：只要其余非 manual 任务全部完成，即可收尾为 `done`，无需等待人工项被勾选（详见 execute 的「收尾为 done」）。\n\n### 自动衔接\n\n> 任务量不构成暂停理由：以下衔接规则与任务清单长度、改动半径无关。\n\n若待确认项为 `_暂无_` 且无新冲突，同一轮继续进入 execute，**同一轮衔接 execute 前后不得**向用户追加任何"是否执行/是否继续"询问。\n\n## execute\n\n顺序执行 `## 任务清单` 中未完成项（`- [ ]`）。执行中若发现新增/扩展需求或新增 bug，立即停止，切回 plan。\n\n> **执行过程中不得对用户做整批/中段元确认**：除"新需求/新 bug → 切回 plan"这一合法阻塞外，任务清单内部的任何疑问都必须以 `## 待确认项` 形式写回触发重开，禁止追加"是否继续 / 我是否应该执行下一项"等问句停顿。\n\n### 每完成一项后立刻\n\n- 将该项从 `- [ ]` 改为 `- [x]`。\n- 在 `## 执行记录` 增加一条结果（改动点、验证方式、阻塞项若有）。\n\n### 默认执行验证\n\n若仓库存在可用测试/构建命令，默认执行并记录结果；若当前环境无法执行，记录原因。\n\n### 追加任务 `[open] → [fixed]` 状态机\n\n若本轮起因是 `## 追加任务` 中的 `[open]` 条目：每完成一个追加项，把状态标记从 `[open]` 改为 `[fixed]`（位置和正文保留不变），在 `## 执行记录` 追加一条结果。已 `[fixed]` 的条目保留作为历史，不删除。\n\n### 收尾为 done\n\n当 `## 任务清单` 不存在未完成的**非 `[manual]`** 任务（`- [ ] [manual]` 人工确认项被忽略），且 `## 待确认项` 为 `_暂无_`、无任何 `！！！` 批注、无 `## 追加任务` 的 `[open]` 条目时，在 execute 收尾同一轮：\n\n- 将 `stage` 置为 `done`，`last_action` 记「任务全部完成，标记 done」。\n- 在 `## 执行记录` 追加一条收尾条目。\n\n`done` 是终止态：机器 / GUI 可据 `stage=done` 直接判定完成。此后不再自动推进；收到新增/扩展需求、新 bug，或 `## 追加任务` 出现 `[open]` 时，按「变更重开流程」切回 `plan`。\n\n## new-spec\n\n当 `spec_path` 缺省且无法从 session 上下文恢复时，自动生成路径与初始骨架。\n\n### 步骤\n\n1. **提炼摘要**：从用户输入提炼 kebab-case `summary-name`（≤ 40 字符，不以数字开头，必须语义化）。中文为主难以提炼时使用 `untitled-<NNN>` 占位。\n2. **判定 type**：`feat` / `refct` / `fix`；prompt 中已显式给出时直接使用；不确定时询问用户，兜底取 `feat`。\n3. **生成 id**：`YYMMDD.<type>.<summary-name>`（如 `260614.feat.spec-frontmatter`）。\n4. **生成路径**：`<specsDir>/<id>/spec.md`。id 冲突时追加 `-2`、`-3` 后缀。\n5. **初始化文档**：写入 frontmatter（`stage: plan`、`last_action: 新建 spec`、`updated_at` 本地秒级字符串、`summary` ≤ 200 字符）；建议创建全部章节（背景 / 需求 / 现状分析 / 技术实现方案 / 待确认项 / 任务清单 / 执行记录），将用户原始需求写入背景或需求。\n6. **进入 plan**：初始化后在同一轮继续推进 plan，不要因为"文档已创建"就退出。\n\n### CLI 触发模式\n\nCLI/Service 同时给出 `类型：<type>` 与需求但未提供 `spec_path` 时，必须自动进入新建流程，不询问类型/路径；初始化后同一轮继续推进 plan，直到遇到真正阻塞才退出。\n';
 async function isGitRepo(cwd) {
   try {
     await stat(join(cwd, ".git"));
@@ -747,7 +747,12 @@ function createSpecsRoutes(resolveProject) {
     if (parsed.autoRun) {
       const { sessionId } = await p.sessions.ensureSessionForSpec(specId);
       const debugActive = await readDebugMdStatus(join(p.specsDir, specId)) === "debugging";
-      const prompt = parsed.debug ? buildDebugPrompt(p.specsDirRelative, specId, "new") : debugActive ? buildDebugPrompt(p.specsDirRelative, specId, "resume") : `请使用 yorz-spec skill 处理 spec：${p.specsDirRelative}/${specId}/spec.md`;
+      const prompt = parsed.debug ? buildDebugPrompt(p.specsDirRelative, specId, "new", await buildDebugRuntimeContext(p)) : debugActive ? buildDebugPrompt(
+        p.specsDirRelative,
+        specId,
+        "resume",
+        await buildDebugRuntimeContext(p)
+      ) : `请使用 yorz-spec skill 处理 spec：${p.specsDirRelative}/${specId}/spec.md`;
       const handle = await p.sessions.send(sessionId, prompt);
       return c.json({ ok: true, runId: handle.runId, sessionId });
     }
@@ -761,7 +766,7 @@ function createSpecsRoutes(resolveProject) {
     if (!detail) return c.json({ error: "spec not found" }, 404);
     const { sessionId } = await p.sessions.ensureSessionForSpec(specId);
     const debugActive = await readDebugMdStatus(join(p.specsDir, specId)) === "debugging";
-    const prompt = debugActive ? buildDebugPrompt(p.specsDirRelative, specId, "resume") : `请使用 yorz-spec skill 处理 spec：${p.specsDirRelative}/${specId}/spec.md`;
+    const prompt = debugActive ? buildDebugPrompt(p.specsDirRelative, specId, "resume", await buildDebugRuntimeContext(p)) : `请使用 yorz-spec skill 处理 spec：${p.specsDirRelative}/${specId}/spec.md`;
     const handle = await p.sessions.send(sessionId, prompt);
     return c.json({ runId: handle.runId, sessionId });
   });
@@ -850,13 +855,38 @@ async function readDebugMdStatus(specDir) {
   const val = statusLine.slice(statusLine.indexOf(":") + 1).trim().replace(/^['"]|['"]$/g, "");
   return val === "debugging" ? "debugging" : val === "resolved" ? "resolved" : null;
 }
-function buildDebugPrompt(specsDirRelative, specId, mode) {
+function buildDebugPrompt(specsDirRelative, specId, mode, runtimeContext = "") {
   const specPath = `${specsDirRelative}/${specId}/spec.md`;
   const debugPath = `${specsDirRelative}/${specId}/debug.md`;
   if (mode === "resume") {
-    return `请使用 yorz-debug skill 继续调试：spec 目录 ${specsDirRelative}/${specId}（含 ${specPath}）。该目录下已存在处于 debugging 状态的 ${debugPath}，请定位其活跃记录块（frontmatter active 指向的 ## Debug NNN）继续「假设 → 取证 → 验证」循环，勿新建记录块。`;
+    return `请使用 yorz-debug skill 继续调试：spec 目录 ${specsDirRelative}/${specId}（含 ${specPath}）。该目录下已存在处于 debugging 状态的 ${debugPath}，请定位其活跃记录块（frontmatter active 指向的 ## Debug NNN）继续「假设 → 取证 → 验证」循环，勿新建记录块。` + runtimeContext;
+  }
+  return `请使用 yorz-debug skill 进入 Debug 模式：spec 目录 ${specsDirRelative}/${specId}（含 ${specPath}）。若 ${debugPath} 不存在则创建，否则在文末追加新的 ## Debug 记录块；进入后立即 git stash create 打快照写入 Debug 基线，再开始「假设 → 取证 → 验证」循环。` + runtimeContext;
+}
+async function buildDebugRuntimeContext(project) {
+  return formatDebugRuntimeContext(await project.commands.listRuns());
+}
+function formatDebugRuntimeContext(runs) {
+  const running = runs.filter((r) => r.status === "running");
+  if (running.length === 0) {
+    return "\n\n当前项目运行服务上下文：暂无运行中的命令服务。若复现需要服务，请根据项目脚本自行启动，或请用户在 GUI 命令菜单启动后重试。";
+  }
+  const lines = ["\n\n当前项目运行服务上下文："];
+  for (const run of running) {
+    lines.push(
+      `- runId: ${promptScalar(run.runId)}`,
+      `  name: ${promptScalar(run.name)}`,
+      `  cli: ${promptScalar(run.cli)}`,
+      `  status: ${run.status}`,
+      `  pid: ${run.pid}`,
+      `  startedAt: ${new Date(run.startedAt).toISOString()}`,
+      `  logFile: ${promptScalar(run.logFile)}`
+    );
   }
-  return `请使用 yorz-debug skill 进入 Debug 模式：spec 目录 ${specsDirRelative}/${specId}（含 ${specPath}）。若 ${debugPath} 不存在则创建，否则在文末追加新的 ## Debug 记录块；进入后立即 git stash create 打快照写入 Debug 基线，再开始「假设 → 取证 → 验证」循环。`;
+  return lines.join("\n");
+}
+function promptScalar(value) {
+  return value.replace(/\r?\n/g, "\\n");
 }
 function parseCreateBody(body) {
   if (!body || typeof body !== "object") return { error: "body must be an object" };
@@ -2008,6 +2038,9 @@ class EventsHub {
     if (!project) throw new Error("project not found");
     if (rest === "specs") return this.attachSpecsList(s, topic, project);
     if (rest === "sessions") return this.attachSessionsStatus(s, topic, project);
+    if (rest === "commands") return this.attachCommandRuns(s, topic, project);
+    const cm = /^command:(.+)$/.exec(rest);
+    if (cm) return this.attachCommandRun(s, topic, project, cm[1]);
     let sm = /^spec:([^:]+):changes$/.exec(rest);
     if (sm) return this.attachSpecChanges(s, topic, project, sm[1]);
     sm = /^spec:([^:]+)$/.exec(rest);
@@ -2057,6 +2090,32 @@ class EventsHub {
       this.emit(s, topic, "session-msg", ev);
     });
   }
+  // Project-level topic: the running-commands container. Emits the full run
+  // list on every change — the list is short and the GUI renders it wholesale.
+  async attachCommandRuns(s, topic, project) {
+    this.emit(s, topic, "ready", {});
+    const runs = await project.commands.listRuns().catch(() => []);
+    this.emit(s, topic, "runs-updated", { runs });
+    return project.commands.subscribeRuns((next) => {
+      this.emit(s, topic, "runs-updated", { runs: next });
+    });
+  }
+  // Per-run topic: incremental stdout plus terminal status transitions.
+  async attachCommandRun(s, topic, project, runId) {
+    const run = await project.commands.getRun(runId);
+    if (!run) throw new Error("command run not found");
+    this.emit(s, topic, "ready", { run });
+    const unsubOutput = project.commands.subscribeOutput(runId, (chunk) => {
+      this.emit(s, topic, "output-appended", chunk);
+    });
+    const unsubRun = project.commands.subscribeRun(runId, (next) => {
+      this.emit(s, topic, "run-updated", { run: next });
+    });
+    return () => {
+      unsubOutput();
+      unsubRun();
+    };
+  }
   // Project-level topic: broadcasts which sessions have an in-flight turn, so
   // the Chat list can render a spinner on sessions other than the active one.
   attachSessionsStatus(s, topic, project) {
@@ -2174,7 +2233,12 @@ function createProjectRoutes(registry, worktreeManager) {
 const CURRENT_VERSION = 1;
 const DEFAULT_SPECS_DIR = ".yorz/specs";
 function defaultProjectConfig() {
-  return { version: CURRENT_VERSION, agent: { kind: "inherit" }, specsDir: DEFAULT_SPECS_DIR };
+  return {
+    version: CURRENT_VERSION,
+    agent: { kind: "inherit" },
+    specsDir: DEFAULT_SPECS_DIR,
+    commands: []
+  };
 }
 function configPath(cwd) {
   return join(cwd, ".yorz", "config.json");
@@ -2225,7 +2289,25 @@ function normalizeConfig(value) {
   const obj = value;
   const agent = normalizeAgent(obj.agent);
   const specsDir = normalizeSpecsDir(obj.specsDir);
-  return { version: CURRENT_VERSION, agent, specsDir };
+  const commands = normalizeCommands(obj.commands);
+  return { version: CURRENT_VERSION, agent, specsDir, commands };
+}
+function normalizeCommands(value) {
+  if (!Array.isArray(value)) return [];
+  const out = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const item of value) {
+    if (!item || typeof item !== "object") continue;
+    const obj = item;
+    const id = typeof obj.id === "string" ? obj.id.trim() : "";
+    const name = typeof obj.name === "string" ? obj.name.trim() : "";
+    const cli = typeof obj.cli === "string" ? obj.cli.trim() : "";
+    if (!id || !name || !cli || seen.has(id)) continue;
+    seen.add(id);
+    const createdAt = typeof obj.createdAt === "number" && obj.createdAt > 0 ? obj.createdAt : 0;
+    out.push({ id, name, cli, createdAt });
+  }
+  return out;
 }
 function normalizeAgent(value) {
   if (typeof value === "string") {
@@ -2274,10 +2356,12 @@ function createProjectConfigRoutes(registry) {
     }
     const parsed = parseBody$1(raw);
     if ("error" in parsed) return c.json({ error: parsed.error }, 400);
+    const current = await loadProjectConfig(entry.path);
     const cfg = {
       version: 1,
       agent: parsed.agent,
-      specsDir: parsed.specsDir
+      specsDir: parsed.specsDir,
+      commands: current.commands
     };
     let absSpecsDir;
     try {
@@ -2755,6 +2839,720 @@ function createProjectFilesRoutes(resolveProject) {
   });
   return app;
 }
+class CommandRunStore {
+  file;
+  cache = null;
+  loadPromise = null;
+  writeChain = Promise.resolve();
+  constructor(projectPath) {
+    this.file = join(projectPath, ".yorz", "tmp", "commands", "index.json");
+  }
+  /**
+   * The in-flight read is memoized, not just its result: concurrent callers
+   * must end up mutating the *same* array. Racing reads that each install a
+   * fresh cache would silently drop every upsert but the last.
+   */
+  load() {
+    if (this.cache) return Promise.resolve(this.cache);
+    if (!this.loadPromise) {
+      this.loadPromise = (async () => {
+        let items = [];
+        try {
+          const raw = await readFile(this.file, "utf8");
+          const parsed = JSON.parse(raw);
+          if (Array.isArray(parsed)) items = parsed;
+        } catch {
+          items = [];
+        }
+        this.cache ??= items;
+        return this.cache;
+      })();
+    }
+    return this.loadPromise;
+  }
+  async persist() {
+    this.writeChain = this.writeChain.then(async () => {
+      const body = JSON.stringify(this.cache ?? [], null, 2);
+      await mkdir(dirname(this.file), { recursive: true });
+      const tmp = `${this.file}.tmp-${process.pid}-${Date.now().toString(36)}`;
+      await writeFile(tmp, body, "utf8");
+      await rename(tmp, this.file);
+    });
+    await this.writeChain;
+  }
+  /** Newest run first. */
+  async list() {
+    const items = await this.load();
+    return [...items].sort((a, b) => b.startedAt - a.startedAt);
+  }
+  async get(runId) {
+    const items = await this.load();
+    return items.find((r) => r.runId === runId);
+  }
+  async upsert(run) {
+    const items = await this.load();
+    const idx = items.findIndex((r) => r.runId === run.runId);
+    if (idx >= 0) items[idx] = { ...items[idx], ...run };
+    else items.push(run);
+    await this.persist();
+  }
+  async remove(runId) {
+    const items = await this.load();
+    const idx = items.findIndex((r) => r.runId === runId);
+    if (idx < 0) return false;
+    items.splice(idx, 1);
+    await this.persist();
+    return true;
+  }
+  /** Bulk replace, used by the startup reap pass. */
+  async replaceAll(runs) {
+    await this.load();
+    this.cache = [...runs];
+    this.loadPromise = Promise.resolve(this.cache);
+    await this.persist();
+  }
+}
+const OUTPUT_TAIL_LIMIT = 256 * 1024;
+const RUN_RETENTION_MS = 7 * 24 * 60 * 60 * 1e3;
+function runLogRelPath(runId) {
+  return `.yorz/tmp/commands/${runId}.log`;
+}
+const log$2 = () => getLogger().child("commands");
+const TAIL_POLL_MS = 200;
+const STOP_GRACE_MS = 2e3;
+class CommandNotFoundError extends Error {
+  constructor(id) {
+    super(`command not found: ${id}`);
+    this.name = "CommandNotFoundError";
+  }
+}
+class RunNotFoundError extends Error {
+  constructor(id) {
+    super(`command run not found: ${id}`);
+    this.name = "RunNotFoundError";
+  }
+}
+class LogTailer {
+  constructor(file) {
+    this.file = file;
+  }
+  subscribers = /* @__PURE__ */ new Set();
+  timer = null;
+  offset = 0;
+  get subscriberCount() {
+    return this.subscribers.size;
+  }
+  get running() {
+    return this.timer !== null;
+  }
+  /**
+   * The first subscriber positions the tail at the current end of file: the GUI
+   * has already fetched everything up to there over REST. Any gap caused by
+   * writes landing between that fetch and this subscribe shows up as a
+   * non-contiguous offset, which the GUI heals with a refetch.
+   */
+  subscribe(cb, fromOffset) {
+    if (this.subscribers.size === 0) this.offset = fromOffset ?? currentSize(this.file);
+    this.subscribers.add(cb);
+    if (!this.timer) {
+      this.timer = setInterval(() => this.poll(), TAIL_POLL_MS);
+      this.timer.unref?.();
+    }
+    return () => {
+      this.subscribers.delete(cb);
+      if (this.subscribers.size === 0) this.stop();
+    };
+  }
+  stop() {
+    if (this.timer) clearInterval(this.timer);
+    this.timer = null;
+  }
+  poll() {
+    let size;
+    try {
+      size = statSync(this.file).size;
+    } catch {
+      return;
+    }
+    if (size <= this.offset) {
+      if (size < this.offset) this.offset = size;
+      return;
+    }
+    let fd = null;
+    try {
+      fd = openSync(this.file, "r");
+      const length = size - this.offset;
+      const buf = Buffer.alloc(length);
+      const read = readSync(fd, buf, 0, length, this.offset);
+      if (read <= 0) return;
+      const chunk = {
+        offset: this.offset,
+        chunk: buf.subarray(0, read).toString("utf8")
+      };
+      this.offset += read;
+      for (const cb of this.subscribers) {
+        try {
+          cb(chunk);
+        } catch {
+        }
+      }
+    } catch (err) {
+      log$2().warn("tail read failed", { file: this.file, err });
+    } finally {
+      if (fd !== null) closeSync(fd);
+    }
+  }
+}
+class CommandManager {
+  constructor(projectPath) {
+    this.projectPath = projectPath;
+    this.store = new CommandRunStore(projectPath);
+  }
+  store;
+  children = /* @__PURE__ */ new Map();
+  tailers = /* @__PURE__ */ new Map();
+  runsSubscribers = /* @__PURE__ */ new Set();
+  runSubscribers = /* @__PURE__ */ new Map();
+  /**
+   * Exits observed before `run()` finished persisting the record. A command
+   * that dies immediately (bad shell syntax, missing binary) emits `exit`
+   * before the first `upsert` lands; without this the terminal state would be
+   * dropped and the record would stay `running` forever.
+   */
+  pendingEnds = /* @__PURE__ */ new Map();
+  persisted = /* @__PURE__ */ new Set();
+  initPromise = null;
+  /** Idempotent startup pass: reap leftovers, drop expired records. */
+  init() {
+    if (!this.initPromise) this.initPromise = this.reap();
+    return this.initPromise;
+  }
+  // ---- definitions (persisted in .yorz/config.json) ----
+  async listDefs() {
+    const cfg = await loadProjectConfig(this.projectPath);
+    return cfg.commands;
+  }
+  async addDef(name, cli) {
+    const trimmedName = name.trim();
+    const trimmedCli = cli.trim();
+    if (!trimmedName) throw new Error("name is required");
+    if (!trimmedCli) throw new Error("cli is required");
+    const cfg = await loadProjectConfig(this.projectPath);
+    const def = {
+      id: shortId(),
+      name: trimmedName,
+      cli: trimmedCli,
+      createdAt: Date.now()
+    };
+    cfg.commands = [...cfg.commands, def];
+    await saveProjectConfig(this.projectPath, cfg);
+    return def;
+  }
+  async removeDef(commandId) {
+    const cfg = await loadProjectConfig(this.projectPath);
+    const next = cfg.commands.filter((c) => c.id !== commandId);
+    if (next.length === cfg.commands.length) return false;
+    cfg.commands = next;
+    await saveProjectConfig(this.projectPath, cfg);
+    return true;
+  }
+  // ---- runs ----
+  async listRuns() {
+    await this.init();
+    return this.store.list();
+  }
+  async getRun(runId) {
+    await this.init();
+    return this.store.get(runId);
+  }
+  /**
+   * Spawn a command. Idempotent per definition: if that command already has a
+   * live run, the existing record is returned instead of starting a second
+   * process (two dev servers would just fight over the same port).
+   */
+  async run(commandId) {
+    await this.init();
+    const defs = await this.listDefs();
+    const def = defs.find((d) => d.id === commandId);
+    if (!def) throw new CommandNotFoundError(commandId);
+    const existing = (await this.store.list()).find(
+      (r) => r.commandId === commandId && r.status === "running"
+    );
+    if (existing) return existing;
+    const runId = shortId();
+    const logRel = runLogRelPath(runId);
+    const logAbs = join(this.projectPath, ".yorz", "tmp", "commands", `${runId}.log`);
+    await mkdir(join(this.projectPath, ".yorz", "tmp", "commands"), { recursive: true });
+    const now = Date.now();
+    let fd;
+    try {
+      fd = openSync(logAbs, "a");
+    } catch (err) {
+      const failed = {
+        runId,
+        commandId,
+        name: def.name,
+        cli: def.cli,
+        pid: -1,
+        status: "failed",
+        startedAt: now,
+        endedAt: now,
+        exitCode: null,
+        signal: null,
+        logFile: logRel
+      };
+      log$2().error("failed to open command log", { runId, logAbs, err });
+      await this.store.upsert(failed);
+      this.notifyRuns();
+      return failed;
+    }
+    try {
+      const child = spawn(def.cli, {
+        shell: true,
+        cwd: this.projectPath,
+        env: process.env,
+        detached: true,
+        // No pipes: the child writes straight into the log fd. Keeps a chatty
+        // dev server from buffering through this process, and lets the REST
+        // first paint and the SSE tail read from one single source.
+        stdio: ["ignore", fd, fd]
+      });
+      child.unref();
+      const run = {
+        runId,
+        commandId,
+        name: def.name,
+        cli: def.cli,
+        pid: child.pid ?? -1,
+        status: "running",
+        startedAt: now,
+        logFile: logRel
+      };
+      if (!child.pid) {
+        run.status = "failed";
+        run.endedAt = Date.now();
+        run.exitCode = null;
+        run.signal = null;
+      } else {
+        this.children.set(runId, child);
+        child.on("exit", (code, signal) => {
+          this.children.delete(runId);
+          void this.handleExit(runId, signal ? "killed" : "exited", code, signal ?? null);
+        });
+        child.on("error", (err) => {
+          log$2().warn("command child error", { runId, err });
+          this.children.delete(runId);
+          void this.handleExit(runId, "failed", null, null);
+        });
+      }
+      await this.store.upsert(run);
+      this.persisted.add(runId);
+      const raced = this.pendingEnds.get(runId);
+      if (raced) {
+        this.pendingEnds.delete(runId);
+        await this.markRunEnded(runId, raced.status, raced.exitCode, raced.signal);
+        const settled = await this.store.get(runId);
+        if (settled) return settled;
+      }
+      this.notifyRuns();
+      log$2().info("command started", { runId, commandId, pid: run.pid, cli: def.cli });
+      return run;
+    } finally {
+      try {
+        closeSync(fd);
+      } catch {
+      }
+    }
+  }
+  /** Terminate the process but keep the run record and its log. */
+  async stop(runId) {
+    await this.init();
+    const run = await this.store.get(runId);
+    if (!run) throw new RunNotFoundError(runId);
+    if (run.status !== "running") return run;
+    await this.terminate(run);
+    return await this.store.get(runId) ?? run;
+  }
+  /** Terminate if needed, then drop the record and delete the log file. */
+  async clear(runId) {
+    await this.init();
+    const run = await this.store.get(runId);
+    if (!run) return false;
+    if (run.status === "running") await this.terminate(run);
+    this.tailers.get(runId)?.stop();
+    this.tailers.delete(runId);
+    await this.store.remove(runId);
+    await rm(join(this.projectPath, run.logFile), { force: true }).catch(() => {
+    });
+    this.runSubscribers.delete(runId);
+    this.persisted.delete(runId);
+    this.pendingEnds.delete(runId);
+    this.notifyRuns();
+    return true;
+  }
+  async readOutput(runId, offset) {
+    await this.init();
+    const run = await this.store.get(runId);
+    if (!run) throw new RunNotFoundError(runId);
+    return readLogSlice(join(this.projectPath, run.logFile), offset);
+  }
+  // ---- subscriptions (SSE) ----
+  subscribeRuns(cb) {
+    this.runsSubscribers.add(cb);
+    return () => this.runsSubscribers.delete(cb);
+  }
+  subscribeRun(runId, cb) {
+    let set = this.runSubscribers.get(runId);
+    if (!set) {
+      set = /* @__PURE__ */ new Set();
+      this.runSubscribers.set(runId, set);
+    }
+    set.add(cb);
+    return () => {
+      set.delete(cb);
+      if (set.size === 0) this.runSubscribers.delete(runId);
+    };
+  }
+  subscribeOutput(runId, cb, fromOffset) {
+    const file = join(this.projectPath, runLogRelPath(runId));
+    let tailer = this.tailers.get(runId);
+    if (!tailer) {
+      tailer = new LogTailer(file);
+      this.tailers.set(runId, tailer);
+    }
+    const unsub = tailer.subscribe(cb, fromOffset);
+    return () => {
+      unsub();
+      const t = this.tailers.get(runId);
+      if (t && t.subscriberCount === 0) this.tailers.delete(runId);
+    };
+  }
+  // ---- lifecycle ----
+  /**
+   * Stop every live child. Called on service shutdown: commands are tied to the
+   * service lifetime, so nothing outlives it.
+   */
+  async stopAll() {
+    const runs = await this.store.list().catch(() => []);
+    const live = runs.filter((r) => r.status === "running");
+    await Promise.all(live.map((r) => this.terminate(r).catch(() => {
+    })));
+    for (const t of this.tailers.values()) t.stop();
+    this.tailers.clear();
+  }
+  /** Last-resort synchronous kill for `process.on('exit')`, which cannot await. */
+  stopAllSync() {
+    for (const [runId, child] of this.children) {
+      const pid = child.pid;
+      if (!pid) continue;
+      try {
+        process.kill(-pid, "SIGKILL");
+      } catch {
+        try {
+          process.kill(pid, "SIGKILL");
+        } catch {
+        }
+      }
+      this.children.delete(runId);
+    }
+    for (const t of this.tailers.values()) t.stop();
+  }
+  /**
+   * Startup pass. Any record still marked `running` belongs to a previous
+   * service process: kill it if it somehow survived (service SIGKILLed), then
+   * mark it `killed`. Also drops records that finished long ago.
+   */
+  async reap() {
+    const runs = await this.store.list().catch(() => []);
+    if (runs.length === 0) return;
+    const now = Date.now();
+    const kept = [];
+    const dropped = [];
+    for (const run of runs) {
+      if (run.status === "running") {
+        if (run.pid > 0 && isAlive(run.pid)) {
+          killGroup(run.pid, "SIGKILL");
+          log$2().warn("reaped orphan command process", { runId: run.runId, pid: run.pid });
+        }
+        kept.push({ ...run, status: "killed", endedAt: run.endedAt ?? now, exitCode: null });
+        continue;
+      }
+      const endedAt = run.endedAt ?? run.startedAt;
+      if (now - endedAt > RUN_RETENTION_MS) dropped.push(run);
+      else kept.push(run);
+    }
+    await this.store.replaceAll(kept);
+    for (const run of dropped) {
+      await rm(join(this.projectPath, run.logFile), { force: true }).catch(() => {
+      });
+    }
+  }
+  async terminate(run) {
+    if (run.pid > 0) {
+      killGroup(run.pid, "SIGTERM");
+      const exited = await waitForExit(run.pid, STOP_GRACE_MS);
+      if (!exited) {
+        log$2().warn("command did not exit on SIGTERM, escalating", {
+          runId: run.runId,
+          pid: run.pid
+        });
+        killGroup(run.pid, "SIGKILL");
+        await waitForExit(run.pid, STOP_GRACE_MS);
+      }
+    }
+    this.children.delete(run.runId);
+    await this.markRunEnded(run.runId, "killed", null, "SIGTERM");
+  }
+  async handleExit(runId, status, exitCode, signal) {
+    if (!this.persisted.has(runId)) {
+      this.pendingEnds.set(runId, { status, exitCode, signal: signal ?? null });
+      return;
+    }
+    await this.markRunEnded(runId, status, exitCode, signal);
+  }
+  async markRunEnded(runId, status, exitCode, signal) {
+    const run = await this.store.get(runId);
+    if (!run || run.status !== "running") return;
+    const next = {
+      ...run,
+      status,
+      endedAt: Date.now(),
+      exitCode,
+      signal: signal ?? null
+    };
+    await this.store.upsert(next);
+    this.notifyRuns();
+    this.notifyRun(next);
+    log$2().info("command ended", { runId, status, exitCode, signal });
+  }
+  notifyRuns() {
+    if (this.runsSubscribers.size === 0) return;
+    void this.store.list().then((runs) => {
+      for (const cb of this.runsSubscribers) {
+        try {
+          cb(runs);
+        } catch {
+        }
+      }
+    });
+  }
+  notifyRun(run) {
+    const set = this.runSubscribers.get(run.runId);
+    if (!set) return;
+    for (const cb of set) {
+      try {
+        cb(run);
+      } catch {
+      }
+    }
+  }
+}
+const managers = /* @__PURE__ */ new Map();
+function getCommandManager(projectPath) {
+  let m = managers.get(projectPath);
+  if (!m) {
+    m = new CommandManager(projectPath);
+    managers.set(projectPath, m);
+  }
+  return m;
+}
+async function stopAllCommandManagers() {
+  const all = [...managers.values()];
+  managers.clear();
+  await Promise.all(all.map((m) => m.stopAll().catch(() => {
+  })));
+}
+function stopAllCommandManagersSync() {
+  for (const m of managers.values()) m.stopAllSync();
+  managers.clear();
+}
+function readLogSlice(file, offset) {
+  let size = 0;
+  try {
+    size = statSync(file).size;
+  } catch {
+    return { offset: 0, text: "", size: 0, truncated: false };
+  }
+  let start2 = offset ?? Math.max(0, size - OUTPUT_TAIL_LIMIT);
+  let truncated = offset === void 0 && start2 > 0;
+  if (start2 > size) start2 = size;
+  if (start2 < 0) start2 = 0;
+  if (size - start2 > OUTPUT_TAIL_LIMIT) {
+    start2 = size - OUTPUT_TAIL_LIMIT;
+    truncated = true;
+  }
+  const length = size - start2;
+  if (length <= 0) return { offset: start2, text: "", size, truncated };
+  let fd = null;
+  try {
+    fd = openSync(file, "r");
+    const buf = Buffer.alloc(length);
+    const read = readSync(fd, buf, 0, length, start2);
+    return { offset: start2, text: buf.subarray(0, read).toString("utf8"), size, truncated };
+  } catch {
+    return { offset: start2, text: "", size, truncated };
+  } finally {
+    if (fd !== null) closeSync(fd);
+  }
+}
+function currentSize(file) {
+  try {
+    return statSync(file).size;
+  } catch {
+    return 0;
+  }
+}
+function shortId() {
+  return randomBytes(8).toString("hex");
+}
+function isAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function killGroup(pid, signal) {
+  try {
+    process.kill(-pid, signal);
+  } catch {
+    try {
+      process.kill(pid, signal);
+    } catch {
+    }
+  }
+}
+async function waitForExit(pid, timeoutMs) {
+  const until = Date.now() + timeoutMs;
+  while (Date.now() < until) {
+    if (!isAlive(pid)) return true;
+    await sleep$1(50);
+  }
+  return !isAlive(pid);
+}
+function sleep$1(ms) {
+  return new Promise((resolve2) => setTimeout(resolve2, ms));
+}
+const MAX_NAME_LEN = 120;
+const MAX_CLI_LEN = 2e3;
+function createCommandsRoutes(resolveProject) {
+  const app = new Hono();
+  const need = async (c) => {
+    const id = c.req.param("projectId") ?? "";
+    if (!id) return c.json({ error: "projectId required" }, 400);
+    const project = await resolveProject(id);
+    if (!project) return c.json({ error: "project not found" }, 404);
+    return project;
+  };
+  app.get("/projects/:projectId/commands", async (c) => {
+    const p = await need(c);
+    if (p instanceof Response) return p;
+    return c.json(await p.commands.listDefs());
+  });
+  app.post("/projects/:projectId/commands", async (c) => {
+    const p = await need(c);
+    if (p instanceof Response) return p;
+    let body;
+    try {
+      body = await c.req.json();
+    } catch {
+      return c.json({ error: "invalid JSON body" }, 400);
+    }
+    const parsed = parseDefBody(body);
+    if ("error" in parsed) return c.json({ error: parsed.error }, 400);
+    const def = await p.commands.addDef(parsed.name, parsed.cli);
+    return c.json(def, 201);
+  });
+  app.delete("/projects/:projectId/commands/:commandId", async (c) => {
+    const p = await need(c);
+    if (p instanceof Response) return p;
+    const ok = await p.commands.removeDef(c.req.param("commandId"));
+    if (!ok) return c.json({ error: "command not found" }, 404);
+    return c.json({ ok: true });
+  });
+  app.get("/projects/:projectId/command-runs", async (c) => {
+    const p = await need(c);
+    if (p instanceof Response) return p;
+    return c.json(await p.commands.listRuns());
+  });
+  app.post("/projects/:projectId/command-runs", async (c) => {
+    const p = await need(c);
+    if (p instanceof Response) return p;
+    let body;
+    try {
+      body = await c.req.json();
+    } catch {
+      return c.json({ error: "invalid JSON body" }, 400);
+    }
+    const commandId = body && typeof body === "object" ? body.commandId : void 0;
+    if (typeof commandId !== "string" || !commandId.trim()) {
+      return c.json({ error: "commandId required" }, 400);
+    }
+    try {
+      const run = await p.commands.run(commandId.trim());
+      return c.json(run, 201);
+    } catch (err) {
+      if (err instanceof CommandNotFoundError) return c.json({ error: "command not found" }, 404);
+      return c.json({ error: err.message }, 400);
+    }
+  });
+  app.get("/projects/:projectId/command-runs/:runId", async (c) => {
+    const p = await need(c);
+    if (p instanceof Response) return p;
+    const run = await p.commands.getRun(c.req.param("runId"));
+    if (!run) return c.json({ error: "command run not found" }, 404);
+    return c.json(run);
+  });
+  app.get("/projects/:projectId/command-runs/:runId/output", async (c) => {
+    const p = await need(c);
+    if (p instanceof Response) return p;
+    const raw = c.req.query("offset");
+    let offset;
+    if (raw !== void 0 && raw !== "") {
+      const n = Number(raw);
+      if (!Number.isInteger(n) || n < 0)
+        return c.json({ error: "offset must be a non-negative integer" }, 400);
+      offset = n;
+    }
+    try {
+      return c.json(await p.commands.readOutput(c.req.param("runId"), offset));
+    } catch (err) {
+      if (err instanceof RunNotFoundError) return c.json({ error: "command run not found" }, 404);
+      throw err;
+    }
+  });
+  app.post("/projects/:projectId/command-runs/:runId/stop", async (c) => {
+    const p = await need(c);
+    if (p instanceof Response) return p;
+    try {
+      const run = await p.commands.stop(c.req.param("runId"));
+      return c.json({ ok: true, run });
+    } catch (err) {
+      if (err instanceof RunNotFoundError) return c.json({ error: "command run not found" }, 404);
+      throw err;
+    }
+  });
+  app.delete("/projects/:projectId/command-runs/:runId", async (c) => {
+    const p = await need(c);
+    if (p instanceof Response) return p;
+    const ok = await p.commands.clear(c.req.param("runId"));
+    if (!ok) return c.json({ error: "command run not found" }, 404);
+    return c.json({ ok: true });
+  });
+  return app;
+}
+function parseDefBody(value) {
+  if (!value || typeof value !== "object") return { error: "body must be an object" };
+  const obj = value;
+  const name = typeof obj.name === "string" ? obj.name.trim() : "";
+  const cli = typeof obj.cli === "string" ? obj.cli.trim() : "";
+  if (!name) return { error: "name required" };
+  if (name.length > MAX_NAME_LEN) return { error: `name too long (max ${MAX_NAME_LEN})` };
+  if (!cli) return { error: "cli required" };
+  if (cli.length > MAX_CLI_LEN) return { error: `cli too long (max ${MAX_CLI_LEN})` };
+  return { name, cli };
+}
 const MIME = {
   ".html": "text/html; charset=utf-8",
   ".js": "text/javascript; charset=utf-8",
@@ -3279,6 +4077,7 @@ function createApp(opts) {
   api.route("/", createSpecDraftsRoutes(resolveProject));
   api.route("/", createWorktreeRoutes(opts.registry, worktreeManager));
   api.route("/", createProjectFilesRoutes(resolveProject));
+  api.route("/", createCommandsRoutes(resolveProject));
   api.route("/", createEventsRoutes(resolveProject, opts.registry, projectsBus));
   app.route("/api", api);
   app.route("/", createStaticRoutes(opts.guiRoot));
@@ -4734,8 +5533,9 @@ function createSessionEndNotifier(opts = {}) {
     if (!sessionEnd.banner && !sessionEnd.sound) return;
     const os = opts.platform ?? platform();
     const run = opts.runCommand ?? defaultRunCommand;
+    const title = formatBannerTitle(opts.projectName);
     const tasks = [];
-    if (sessionEnd.banner) tasks.push(showBanner(os, run));
+    if (sessionEnd.banner) tasks.push(showBanner(os, run, title));
     if (sessionEnd.sound) tasks.push(playSound(os, run));
     await Promise.all(tasks.map((task) => task.catch(() => {
     })));
@@ -4747,9 +5547,19 @@ async function defaultRunCommand(cmd, args) {
     windowsHide: true
   });
 }
-async function showBanner(os, run) {
+function formatBannerTitle(projectName) {
+  const name = projectName?.trim();
+  return name ? `YorZ · ${name}` : "YorZ";
+}
+function appleScriptString(value) {
+  return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}
+function powershellSingleQuoted(value) {
+  return `'${value.replace(/'/g, "''")}'`;
+}
+async function showBanner(os, run, title) {
   if (os === "darwin") {
-    await run("osascript", ["-e", 'display notification "" with title "YorZ"']);
+    await run("osascript", ["-e", `display notification "" with title ${appleScriptString(title)}`]);
     return;
   }
   if (os === "win32") {
@@ -4763,14 +5573,14 @@ async function showBanner(os, run) {
         "$n = New-Object System.Windows.Forms.NotifyIcon",
         "$n.Icon = [System.Drawing.SystemIcons]::Information",
         "$n.Visible = $true",
-        "$n.ShowBalloonTip(5000, 'YorZ', '', [System.Windows.Forms.ToolTipIcon]::Info)",
+        `$n.ShowBalloonTip(5000, ${powershellSingleQuoted(title)}, '', [System.Windows.Forms.ToolTipIcon]::Info)`,
         "Start-Sleep -Milliseconds 5500",
         "$n.Dispose()"
       ].join("; ")
     ]);
     return;
   }
-  await run("notify-send", ["YorZ", ""]);
+  await run("notify-send", [title, ""]);
 }
 async function playSound(os, run) {
   if (os === "darwin") {
@@ -4908,11 +5718,15 @@ class ProjectRegistry {
     });
     const attachments = new AttachmentStore({ cwd: input.path });
     const sessionStore = new SessionStore(input.path);
-    const notifySessionEnded = createSessionEndNotifier({ globalConfigPath: this.globalConfigPath });
+    const notifySessionEnded = createSessionEndNotifier({
+      globalConfigPath: this.globalConfigPath,
+      projectName: basename(input.path)
+    });
     const defaultKind = resolveProjectAgentKind(cfg.agent, globalCfg.agent.defaultKind);
     const sessions = new SessionManager(input.path, defaultKind, sessionStore, {
       onSessionEnd: notifySessionEnded
     });
+    const commands = getCommandManager(input.path);
     let closed = false;
     const instance = {
       id: input.id,
@@ -4923,6 +5737,7 @@ class ProjectRegistry {
       watcher,
       sessions,
       attachments,
+      commands,
       async close() {
         if (closed) return;
         closed = true;
@@ -4936,6 +5751,8 @@ class ProjectRegistry {
       await attachments.ensureRoot();
       void attachments.cleanupExpired().catch(() => {
       });
+      void commands.init().catch(() => {
+      });
       await watcher.start();
     })();
     this.cache.set(input.id, { instance, startPromise });
@@ -4974,6 +5791,10 @@ async function maxSpecUpdatedAt(projectPath) {
 }
 const DEFAULT_PORT = 7423;
 const MAX_PORT_TRIES = 10;
+const DEFAULT_HOST = "127.0.0.1";
+function isLoopbackHost(host) {
+  return host === "127.0.0.1" || host === "localhost" || host === "::1";
+}
 const log$1 = () => getLogger().child("serve");
 async function start(opts = {}) {
   const registry = new ProjectRegistry({ globalConfigPath: opts.globalConfigPath });
@@ -4986,11 +5807,16 @@ async function start(opts = {}) {
   }
   const projects = await registry.list();
   const app = createApp({ registry, guiRoot: opts.guiRoot });
-  const port = await listen(app.fetch, opts.port ?? DEFAULT_PORT);
+  const host = opts.host?.trim() || DEFAULT_HOST;
+  const port = await listen(app.fetch, opts.port ?? DEFAULT_PORT, host);
   const url = `http://localhost:${port.port}/`;
   console.log(`YorZ Service ready at ${url} (${projects.length} project${projects.length === 1 ? "" : "s"})`);
-  for (const lanUrl of listLanUrls(port.port)) {
-    console.log(`  LAN: ${lanUrl}`);
+  if (!isLoopbackHost(host)) {
+    console.log(`  WARNING: bound to ${host} — reachable from the network.`);
+    for (const lanUrl of listLanUrls(port.port)) {
+      console.log(`  LAN: ${lanUrl}`);
+    }
+    log$1().warn("service bound to a non-loopback address", { host, port: port.port });
   }
   for (const p of projects) {
     console.log(`  - ${p.name} -> ${p.path}`);
@@ -5006,12 +5832,14 @@ async function start(opts = {}) {
     logFile: getLogger().filePath
   });
   installGlobalErrorHandlers();
+  installCommandExitGuard();
   if (opts.open) await tryOpenBrowser(url);
   return {
     url,
     port: port.port,
     registry,
     async close() {
+      await stopAllCommandManagers();
       await registry.closeAll();
       await new Promise((resolve2, reject) => {
         port.server.close((err) => err ? reject(err) : resolve2());
@@ -5020,7 +5848,7 @@ async function start(opts = {}) {
     }
   };
 }
-async function listen(fetchHandler, preferredPort) {
+async function listen(fetchHandler, preferredPort, hostname) {
   let lastErr = null;
   for (let i = 0; i < MAX_PORT_TRIES; i++) {
     const tryPort = preferredPort + i;
@@ -5028,7 +5856,7 @@ async function listen(fetchHandler, preferredPort) {
       return await new Promise(
         (resolve2, reject) => {
           const server = serve(
-            { fetch: fetchHandler, port: tryPort, hostname: "0.0.0.0" },
+            { fetch: fetchHandler, port: tryPort, hostname },
             (info) => {
               resolve2({ port: info.port, server });
             }
@@ -5083,6 +5911,14 @@ function logCrash(kind, payload) {
   const body = payload instanceof Error ? payload.stack ?? payload.message : String(payload);
   log$1().error(kind, { detail: body });
 }
+let commandExitGuardInstalled = false;
+function installCommandExitGuard() {
+  if (commandExitGuardInstalled) return;
+  commandExitGuardInstalled = true;
+  process.on("exit", () => {
+    stopAllCommandManagersSync();
+  });
+}
 function installGlobalErrorHandlers() {
   if (process.listenerCount("uncaughtException") > 0) return;
   process.on("uncaughtException", (err) => {
@@ -5120,23 +5956,28 @@ async function runServe(opts) {
   }
   const handle = await start({
     port: opts.port,
+    host: opts.host,
     open: opts.open,
     cwd: opts.cwd ?? process.cwd(),
     noRegisterCwd: opts.noRegisterCwd
   });
-  await upsertProcess({
-    pid: process.pid,
-    port: handle.port,
-    url: handle.url,
-    startedAt: (/* @__PURE__ */ new Date()).toISOString()
-  });
-  console.log(`Stop with: yorz serve stop`);
+  if (opts.recordRuntime) {
+    await upsertProcess({
+      pid: process.pid,
+      port: handle.port,
+      url: handle.url,
+      startedAt: (/* @__PURE__ */ new Date()).toISOString()
+    });
+    console.log(`Stop with: yorz serve stop`);
+  } else {
+    console.log(`Stop with: Ctrl-C`);
+  }
   const shutdown = async () => {
     console.log("\nShutting down YorZ Service…");
     try {
       await handle.close();
     } finally {
-      await removeRuntimeForPid(process.pid);
+      if (opts.recordRuntime) await removeRuntimeForPid(process.pid);
       process.exit(0);
     }
   };
@@ -5197,10 +6038,12 @@ function startBackgroundServe(opts) {
 function backgroundArgs(opts) {
   const args = ["--foreground"];
   if (opts.port !== void 0) args.push("--port", String(opts.port));
+  if (opts.host !== void 0) args.push("--host", opts.host);
   if (opts.open) args.push("--open");
   if (opts.cwd) args.push("--cwd", opts.cwd);
   if (opts.noRegisterCwd) args.push("--no-register-cwd");
   args.push("--skip-skill-check");
+  args.push("--record-runtime");
   return args;
 }
 async function ensureSkillsInstalledWithLog(cwd) {
@@ -5840,7 +6683,7 @@ const frontmatterRequiredFields = {
 };
 const frontmatterUpdatedAt = {
   id: "frontmatter/updated-at",
-  description: "updated_at 值应形如 YYYY-MM-DD HH:mm:ss，原文中带单引号。",
+  description: "updated_at 值应为 YAML 字符串，形如 YYYY-MM-DD HH:mm:ss。",
   check(ctx) {
     const findings = [];
     const fm = ctx.frontmatter;
@@ -5858,13 +6701,13 @@ const frontmatterUpdatedAt = {
       });
     }
     const afterColon = rawLine.slice(rawLine.indexOf(":") + 1).trim();
-    if (!(afterColon.startsWith("'") && afterColon.endsWith("'"))) {
+    const quoted = afterColon.startsWith("'") && afterColon.endsWith("'") || afterColon.startsWith('"') && afterColon.endsWith('"');
+    if (!quoted) {
       findings.push({
         ruleId: this.id,
         severity: "error",
-        message: "updated_at 写入时必须使用单引号包裹，避免 YAML 1.1 时间戳解析。",
-        line: lineNo,
-        hint: `updated_at: '${value}'`
+        message: "updated_at 必须写为 YAML 字符串，避免裸时间戳被 YAML 解析。",
+        line: lineNo
       });
     }
     return findings;
@@ -6572,12 +7415,15 @@ program.command("lint [paths...]").description("Lint spec.md / review.md files f
     if (result.exitCode !== 0) process.exit(result.exitCode);
   }
 );
-const serveCmd = program.command("serve").description("Start the YorZ Service (HTTP + SSE + static GUI; multi-project).").option("-p, --port <port>", "port to listen on", "7423").option("--open", "open the GUI in the default browser", false).option("--foreground", "run the service in the foreground", false).option("--background", "run the service in the background (default)", false).option(
+const serveCmd = program.command("serve").description("Start the YorZ Service (HTTP + SSE + static GUI; multi-project).").option("-p, --port <port>", "port to listen on", "7423").option(
+  "--host <address>",
+  "bind address (default: 127.0.0.1; the service runs shell commands, so exposing it to the network is opt-in)"
+).option("--open", "open the GUI in the default browser", false).option("--foreground", "run the service in the foreground", false).option("--background", "run the service in the background (default)", false).option(
   "--cwd <path>",
   "directory to auto-register when it contains .yorz/ (default: process.cwd())"
 ).option("--no-register-cwd", "do not auto-register the current directory").addOption(
   new Option("--skip-skill-check", "internal: skip the skill install/update check").hideHelp()
-).action(async (opts) => {
+).addOption(new Option("--record-runtime", "internal: record foreground process").hideHelp()).action(async (opts) => {
   if (opts.foreground && opts.background) {
     throw new Error("Use either --foreground or --background, not both");
   }
@@ -6587,11 +7433,13 @@ const serveCmd = program.command("serve").description("Start the YorZ Service (H
   }
   await runServe({
     port,
+    host: opts.host,
     open: opts.open,
     cwd: opts.cwd,
     noRegisterCwd: opts.registerCwd === false,
     foreground: opts.foreground === true,
-    skipSkillCheck: opts.skipSkillCheck === true
+    skipSkillCheck: opts.skipSkillCheck === true,
+    recordRuntime: opts.recordRuntime === true
   });
 });
 serveCmd.command("stop").description("Stop the background YorZ Service.").action(async () => {