marchen 0.8.0

package/dist/index.mjs

@@ -0,0 +1,1954 @@
+#!/usr/bin/env node
+import{a as e,c as t,i as n,o as r,r as i,s as a,t as o}from"./search-manager-zPFpsFnI.mjs";import{createRequire as s}from"node:module";import{Command as c}from"commander";import*as l from"@clack/prompts";import{dirname as u,join as d,resolve as f}from"node:path";import{promises as p}from"node:fs";import m from"js-yaml";import h from"picocolors";var g=class extends Error{constructor(e){super(e),this.name=`MarchenError`}},_=class extends g{constructor(e){super(e),this.name=`ValidationError`}},v=class extends g{constructor(e,t){super(e),this.hint=t,this.name=`StateError`}},y=class extends g{constructor(e,t,n){super(e),this.path=t,this.cause=n,this.name=`FileSystemError`}};const b={apply:{fileName:`apply.md`,content:`---
+name: "Marchen: Apply"
+description: 按变更的 tasks.md 逐个实现任务
+category: Workflow
+tags: [workflow, implementation]
+---
+
+按变更的 tasks.md 逐个实现任务，完成后勾选 checkbox。
+
+---
+
+**输入**：\`/marchen:apply\` 后面跟变更名称，或省略自动推断。
+
+**流程**
+
+1. **选择变更**
+
+   有名称就用，没有则：
+   - 从对话上下文推断
+   - 只有一个 open 变更时自动选择
+   - 多个变更时 \`marchen list --json\` + **AskUserQuestion** 让用户选
+
+   显示："使用变更: \`<name>\`"
+
+2. **获取实现指令**
+
+   \`\`\`bash
+   marchen instructions <name> apply --json
+   \`\`\`
+
+   返回 JSON 包含：
+   - \`state\`：\`"ready"\` / \`"blocked"\` / \`"all_done"\`
+   - \`progress\`：\`{ total, completed, remaining }\`
+   - \`context\`：所有 artifact 的信息数组，每项包含 \`id\`、\`status\`、\`path\`、\`content\`
+   - \`instruction\`：实现指引
+   - \`changeDir\`：变更目录绝对路径
+
+   根据 \`state\` 处理：
+   - \`"blocked"\` → 提示先完成 artifacts（\`/marchen:propose\`）
+   - \`"all_done"\` → 提示归档（\`/marchen:archive\`）
+   - \`"ready"\` → 继续
+
+3. **显示进度**
+
+   从返回的 JSON 读取并显示：
+   "变更: \`<name>\` | 进度: N/M | 下一个: <第一个未完成任务的描述>"
+
+4. **逐个实现任务**
+
+   从 \`context\` 中读取所有 artifact 内容作为上下文。
+
+   对每个未完成任务：
+   - 显示 "任务 N/M: <描述>"
+   - 实现代码改动
+   - 在 tasks.md 中勾选：\`- [ ]\` → \`- [x]\`
+     文件路径：\`<changeDir>/tasks.md\`
+   - 显示 "✓ 完成"
+   - 继续下一个
+
+   **暂停条件：**
+   - 任务不清晰 → 询问用户
+   - 发现设计问题 → 建议更新 artifact
+   - 遇到错误或阻塞 → 报告并等待
+   - 用户中断
+
+5. **显示结果**
+
+   全部完成时：
+   "全部完成 (N/N)，可以用 \`/marchen:review\` 检查实现，或直接 \`/marchen:archive\` 归档。"
+
+   暂停时：
+   "暂停于任务 N/M: <原因>"
+
+**护栏**
+
+- 实现前必须读 context 中的 artifact 内容
+- 每完成一个任务立即勾选 checkbox，不要攒着
+- 改动最小化，只做任务要求的事
+- 不确定就暂停问，不要猜
+- 如果实现过程中遇到不确定的设计决策，可以用 \`marchen search "<关键词>" --json\` 搜索历史变更中的相关方案
+- 使用 AskUserQuestion 时，选项不超过 4 个
+- \`instruction\` 是给你的指引，不要原样复制到代码注释中
+`},archive:{fileName:`archive.md`,content:`---
+name: "Marchen: Archive"
+description: 归档已完成的变更
+category: Workflow
+tags: [workflow, archive]
+---
+
+归档已完成的变更，检查完成度后执行归档。
+
+---
+
+**输入**：用户的请求可包含变更名称（如 \`/marchen:archive add-auth\`），也可不带。
+
+**流程**
+
+1. **确定变更名称**
+
+   有名称就用，没有则：
+   - 从对话上下文推断
+   - 只有一个 open 变更时自动选择
+   - 多个变更时 \`marchen list --json\` + **AskUserQuestion** 让用户选
+
+   **重要**：不要猜测或自动选择，必须让用户确认。
+
+2. **检查完成度**
+
+   \`\`\`bash
+   marchen status <name> --json
+   \`\`\`
+
+   解析 JSON，检查：
+   - \`artifacts\`：每个 artifact 的 \`status\` 是否为 \`filled\`
+   - \`tasks.completed\` vs \`tasks.total\`（\`tasks\` 为 null 时视为无任务，跳过检查）
+
+   **如果全部完成：** 直接进入下一步。
+
+   **如果有未完成的 artifact 或 task：**
+   - 显示警告，列出未完成项
+   - 用 **AskUserQuestion** 确认是否继续
+   - 用户确认后继续，不阻塞
+
+3. **生成摘要**
+
+   读取 \`marchen/changes/<name>/proposal.md\`，从中生成一句话中文摘要（≤50字），概括这次变更做了什么。摘要应包含关键语义词，便于后续 AI 检索。
+
+4. **执行归档**
+
+   \`\`\`bash
+   marchen archive <name> --summary "<生成的摘要>" --json
+   \`\`\`
+
+   解析返回的 JSON 获取归档结果。
+
+5. **显示结果**
+
+   \`\`\`
+   变更 "<name>" 已归档
+   Schema: <schema>
+   归档到: <archivedTo>
+   \`\`\`
+
+   如有警告（未完成项），一并显示。
+
+**护栏**
+
+- 未提供名称时必须用 AskUserQuestion 让用户选择
+- 用 \`status --json\` 检查完成度，不要自己读文件判断
+- 警告不阻塞归档，只提醒 + 确认
+- 使用 AskUserQuestion 时，选项不超过 4 个
+`},explore:{fileName:`explore.md`,content:`---
+name: "Marchen: Explore"
+description: 进入探索模式 — 思考想法、调查问题、厘清需求
+category: Workflow
+tags: [workflow, explore, thinking]
+---
+
+进入探索模式。深入思考，自由可视化，跟随对话走向任何方向。
+
+**重要：探索模式只用于思考，不用于实现。** 可以读文件、搜索代码、调查代码库，但绝不能写代码或实现功能。如果用户要求实现，提醒他们先退出探索模式并用 \`/marchen:propose\` 创建变更。可以创建 Marchen artifact（proposal、design、spec）——那是捕获思考，不是实现。
+
+**这是一种姿态，不是工作流。** 没有固定步骤、没有必须的顺序、没有强制输出。你是帮助用户探索的思考伙伴。
+
+**输入**：\`/marchen:explore\` 后面可以跟任何内容：
+- 模糊的想法："实时协作"
+- 具体的问题："auth 系统越来越难维护了"
+- 变更名称："add-dark-mode"（在该变更上下文中探索）
+- 方案比较："postgres vs sqlite"
+- 什么都不带也行
+
+---
+
+## 姿态
+
+- **好奇，不武断** — 提出自然涌现的问题，不按脚本走
+- **开放线索，不审问** — 展示多个有趣方向，让用户跟随感兴趣的。不要把他们引导到单一路径上
+- **视觉化** — 大量使用 ASCII 图表来辅助思考
+- **自适应** — 跟随有趣的线索，有新信息时及时转向
+- **耐心** — 不急于下结论，让问题的形状自然浮现
+- **接地气** — 在相关时探索实际代码库，不要空谈理论
+
+---
+
+## 你可以做什么
+
+根据用户带来的内容，你可能会：
+
+**探索问题空间**
+- 提出从用户所说内容中自然涌现的澄清问题
+- 挑战假设
+- 重新框定问题
+- 寻找类比
+
+**调查代码库**
+- 映射与讨论相关的现有架构
+- 找到集成点
+- 识别已有的模式
+- 发现隐藏的复杂性
+
+**比较方案**
+- 头脑风暴多种方案
+- 构建比较表
+- 勾勒权衡
+- 推荐路径（如果被问到）
+
+**可视化**
+\`\`\`
+┌─────────────────────────────────────────┐
+│     Use ASCII diagrams liberally        │
+├─────────────────────────────────────────┤
+│                                         │
+│   ┌────────┐         ┌────────┐        │
+│   │ State  │────────▶│ State  │        │
+│   │   A    │         │   B    │        │
+│   └────────┘         └────────┘        │
+│                                         │
+│   System diagrams, state machines,      │
+│   data flows, architecture sketches,    │
+│   dependency graphs, comparison tables  │
+│                                         │
+└─────────────────────────────────────────┘
+\`\`\`
+
+**发现风险和未知**
+- 识别可能出错的地方
+- 找到理解上的空白
+- 建议 spike 或调查
+
+---
+
+## Marchen 感知
+
+你了解 Marchen 系统。自然地使用它，不要强制。
+
+### 检查上下文
+
+开始时快速检查现有状态和历史：
+
+1. 当前变更：
+\`\`\`bash
+marchen list --json
+\`\`\`
+
+2. 变更历史概览：
+\`\`\`bash
+cat marchen/changelog.md
+\`\`\`
+这是所有已归档变更的索引，每条包含日期、变更名和一句话摘要。先扫一遍找到与用户话题相关的条目。如果找到，直接读对应 archive 目录下的 proposal.md 或 design.md 了解详情。
+
+3. 语义搜索：
+
+这是 RAG 搜索，不是 grep——构造语义完整的短语，不要用单个泛词。
+
+\`\`\`bash
+marchen search "<语义完整的查询短语>" --json
+\`\`\`
+
+**查询构造指引：**
+- 用描述性短语，不用单个词：
+  "初始化适配多个 agent 客户端" → \`"multi-agent provider 初始化"\`
+  "之前怎么处理错误的" → \`"错误处理 error handling 重构"\`
+  "暗色模式的设计决策" → \`"dark mode 设计方案"\`
+- 中英文混合效果更好（归档内容里中英都有）
+- 如果结果不理想，换个角度重新构造查询
+
+如果有匹配结果（score >= 0.4），读取对应 archive 目录下的 design.md 或 proposal.md 了解详细决策。
+
+如果 \`marchen search\` 不可用（命令报错），回退到 changelog.md + 手动读 archive 目录。
+
+这告诉你：
+- 是否有进行中的变更
+- 它们的名称、schema 和状态
+- 项目过去做过哪些变更
+- 用户可能在做什么
+
+如果用户提到了特定变更名称，读取它的 artifact 作为上下文。
+
+### 没有变更时
+
+自由思考。当洞察结晶时，根据复杂度推荐下一步：
+
+**判断标准：**
+- \`/marchen:lite\` — bug 修复、小改动、单一任务组、不需要设计文档
+- \`/marchen:propose\` — 新功能、多步骤、需要 design/specs、涉及多模块
+
+**推荐方式：** 直接在回复中输出推荐，说明理由，让用户自行输入命令。示例：
+
+> 想法差不多成型了。这个改动比较简单（只涉及一个文件的小调整），建议用 \`/marchen:lite\` 直接走轻量流程。
+>
+> 如果你觉得需要更完整的设计文档，也可以用 \`/marchen:propose\`。
+
+根据讨论内容给出你的推荐和理由，但让用户自己决定输入哪个命令。
+
+### 有变更时
+
+如果用户提到了变更或你发现某个变更相关：
+
+1. **读取已有 artifact 作为上下文**
+   - \`marchen/changes/<name>/proposal.md\`
+   - \`marchen/changes/<name>/design.md\`
+   - \`marchen/changes/<name>/tasks.md\`
+   - 等
+
+2. **在对话中自然引用**
+   - "你的 design 提到用 Redis，但我们刚发现 SQLite 更合适……"
+   - "proposal 把范围限定在付费用户，但我们现在觉得应该面向所有人……"
+
+3. **在做出决策时提议捕获**
+
+   | 洞察类型 | 捕获到哪里 |
+   |---------|-----------|
+   | 发现新需求 | \`specs/<capability>/spec.md\` |
+   | 需求变更 | \`specs/<capability>/spec.md\` |
+   | 做出设计决策 | \`design.md\` |
+   | 范围变更 | \`proposal.md\` |
+   | 发现新工作 | \`tasks.md\` |
+   | 假设被推翻 | 相关 artifact |
+
+   示例：
+   - "这是一个设计决策。要记录到 design.md 吗？"
+   - "这是新需求。要加到 specs 里吗？"
+   - "这改变了范围。要更新 proposal 吗？"
+
+4. **用户决定** — 提议后继续。不施压，不自动捕获。
+
+---
+
+## 不必做的事
+
+- 按脚本走
+- 每次问同样的问题
+- 产出特定 artifact
+- 得出结论
+- 如果有价值的岔路就不必守住话题
+- 简短（这是思考时间）
+
+---
+
+## 结束探索
+
+没有固定的结束方式。探索可能：
+
+- **流向下一阶段**：用 **AskUserQuestion** 提供 \`/marchen:lite\` 和 \`/marchen:propose\` 选项，附带推荐理由
+- **更新 artifact**："已将这些决策更新到 design.md"
+- **只是提供清晰度**：用户得到了需要的，继续前进
+- **稍后继续**："随时可以继续"
+
+当想法结晶时，你可以提供总结——但不是必须的。有时候思考过程本身就是价值。
+
+---
+
+## 护栏
+
+- **不实现** — 绝不写代码或实现功能。创建 Marchen artifact 可以，写应用代码不行
+- **不伪装理解** — 不清楚就深挖
+- **不催促** — 探索是思考时间，不是任务时间
+- **不强制结构** — 让模式自然浮现
+- **不自动捕获** — 提议保存洞察，不要直接做
+- **要可视化** — 一张好图胜过千言万语
+- **要探索代码库** — 让讨论扎根于现实
+- **要质疑假设** — 包括用户的和你自己的
+`},lite:{fileName:`lite.md`,content:`---
+name: "Marchen: Lite"
+description: 一键式轻量变更流程。创建 lite 变更、实现任务、询问归档，一气呵成
+category: Workflow
+tags: [workflow, lite]
+---
+
+一键式轻量变更 — 使用 lite schema 创建变更，自动实现任务，完成后询问归档。
+适合 bug 修复、小改动、explore 之后的快速执行。
+
+---
+
+**输入**：\`/marchen:lite\` 后面跟变更名称（kebab-case）或变更描述。
+
+**流程**
+
+1. **确定变更名称**
+
+   如果提供了输入，直接使用或从描述中提取 kebab-case 名称（如"修复登录 bug" → \`fix-login-bug\`）。
+
+   如果没有输入，用 **AskUserQuestion** 工具询问：
+   > "你想做什么变更？描述一下你要构建或修复的内容。"
+
+   从回答中提取 kebab-case 名称。
+
+   **重要**：必须理解用户想做什么才能继续。
+
+2. **创建变更目录**
+
+   \`\`\`bash
+   marchen new <name> --schema lite
+   \`\`\`
+
+   创建 \`marchen/changes/<name>/\` 目录，包含 \`.metadata.yaml\` 和 \`tasks.md\` 骨架。
+
+   如果同名变更已存在，用 **AskUserQuestion** 询问用户是继续已有变更还是换个名称。
+
+3. **获取 tasks 指令**
+
+   \`\`\`bash
+   marchen status <name> --json
+   \`\`\`
+
+   确认变更创建成功，然后获取 tasks 的创建指令：
+
+   \`\`\`bash
+   marchen instructions <name> tasks --json
+   \`\`\`
+
+   返回 JSON 包含：
+   - \`template\`：tasks.md 的骨架结构（含 \`## 背景\` 章节）
+   - \`instruction\`：如何填充 tasks 的指导文本
+   - \`outputPath\`：写入路径（\`tasks.md\`）
+   - \`context\`：上下文信息（lite schema 下为空数组）
+
+4. **填充 tasks.md**
+
+   根据用户描述 + \`instruction\` 指引 + \`template\` 结构，填充 tasks.md：
+   - \`## 背景\`：简要说明变更目的和方案
+   - 任务列表：按组分类，checkbox 格式
+
+   写入 \`marchen/changes/<name>/tasks.md\`。
+
+   如果用户描述太模糊，用 **AskUserQuestion** 澄清关键信息。
+
+5. **开始实现**
+
+   获取实现指令：
+
+   \`\`\`bash
+   marchen instructions <name> apply --json
+   \`\`\`
+
+   返回 JSON 包含：
+   - \`state\`：\`"ready"\` / \`"blocked"\` / \`"all_done"\`
+   - \`progress\`：\`{ total, completed, remaining }\`
+   - \`context\`：所有 artifact 的信息数组
+   - \`instruction\`：实现指引
+   - \`changeDir\`：变更目录绝对路径
+
+   显示："变更: \`<name>\` | 任务: 0/N | 开始实现..."
+
+   对每个未完成任务：
+   - 显示 "任务 N/M: <描述>"
+   - 实现代码改动
+   - 在 tasks.md 中勾选：\`- [ ]\` → \`- [x]\`
+     文件路径：\`<changeDir>/tasks.md\`
+   - 显示 "✓ 完成"
+   - 继续下一个
+
+   **暂停条件：**
+   - 任务不清晰 → 询问用户
+   - 发现设计问题 → 建议更新 artifact
+   - 遇到错误或阻塞 → 报告并等待
+   - 用户中断
+
+   暂停时显示："暂停于任务 N/M: <原因>"，流程结束。
+
+6. **全部完成 → 询问归档**
+
+   所有任务完成后，用 **AskUserQuestion** 询问：
+
+   > "全部任务已完成 (N/N)，是否归档这个变更？"
+   > - 归档
+   > - 暂不归档
+
+   **如果用户选择归档：**
+
+   读取 \`marchen/changes/<name>/tasks.md\` 的背景段，生成一句话中文摘要（≤50字）。
+
+   \`\`\`bash
+   marchen archive <name> --summary "<摘要>" --json
+   \`\`\`
+
+   显示：
+   \`\`\`
+   变更 "<name>" 已归档
+   归档到: <archivedTo>
+   \`\`\`
+
+   **如果用户选择暂不归档：**
+
+   显示："好的，后续可以用 \`/marchen:archive <name>\` 归档。"
+
+**护栏**
+
+- 必须使用 \`--schema lite\` 创建变更
+- tasks.md 的 \`## 背景\` 章节必须填写，不能留空
+- 任务粒度要小到一个会话内能完成
+- 如果上下文关键信息不清楚，询问用户；但小疑问优先做合理判断，保持节奏
+- 已存在同名变更时必须询问用户，不要覆盖
+- 实现前必须读 context 中的 artifact 内容
+- 每完成一个任务立即勾选 checkbox，不要攒着
+- 改动最小化，只做任务要求的事
+- 不确定就暂停问，不要猜
+- \`instruction\` 是给你的指引，不要把它原样复制到代码注释或 tasks.md 中
+- 使用 AskUserQuestion 时，选项不超过 4 个
+`},"propose-preview":{fileName:`propose-preview.md`,content:`---
+name: "Marchen: Propose Preview"
+description: 预览 propose 生成的变更摘要
+category: Workflow
+tags: [workflow, preview]
+---
+
+预览一个变更的浓缩摘要 — 纯终端输出，不写文件。
+
+适用于 propose 完成后人快速 review，避免来回翻 4~7 个 artifact 文件。
+
+---
+
+**输入**：\`/marchen:propose-preview\` 后面跟变更名称，或省略自动推断。
+
+**流程**
+
+1. **选择变更**
+
+   有名称就用，没有则：
+   - 从对话上下文推断
+   - 只有一个 open 变更时自动选择
+   - 多个变更时 \`marchen list --json\` + **AskUserQuestion** 让用户选
+
+   显示："Preview 变更: \`<name>\`"
+
+2. **获取 artifact 内容**
+
+   \`\`\`bash
+   marchen instructions <name> apply --json
+   \`\`\`
+
+   返回 JSON 包含：
+   - \`schemaName\`：\`"full"\` / \`"lite"\`
+   - \`state\`：\`"ready"\` / \`"blocked"\` / \`"all_done"\`
+   - \`progress\`：\`{ total, completed, remaining }\`
+   - \`context\`：所有 artifact 的内容数组（\`id\` / \`status\` / \`content\`）
+
+   **如果 state 为 \`blocked\`**：打印 "变更未填完，先用 /marchen:propose 补齐 artifact 再预览"，结束。不要强行摘要半成品。
+
+3. **生成卡片并直接打印**
+
+   根据 \`schemaName\` 选模板：
+   - \`full\` → 四段：改了什么 / 关键决策 / 影响范围 / 风险
+   - \`lite\` → 两段：改了什么 / 任务概览
+
+   严格按下面的"摘要规则"生成，输出为单个卡片，禁止加任何解释段落。
+
+4. **末尾追加一行下一步提示**
+
+   \`\`\`
+   /marchen:apply <name>           开始实现
+   /marchen:propose <name>         修改提案
+   \`\`\`
+
+---
+
+## 摘要规则（必须严格遵守）
+
+**通用约束：**
+
+- 卡片框宽 70 字符（含 \`│\` 边框），便于主流终端整齐显示
+- 每行内容（去掉边框后）≤ 60 字符；超出必须截断/合并/重写，不许折行
+- 禁止粘贴 artifact 原文片段，所有内容必须重新组织、压缩
+- 中文为主，技术名词保留英文（如 \`SearchManager\`、\`SDK\`）
+- 宁可少写，不要堆。摘不下就合并或截断，在框底加 \`更多详情见 marchen/changes/<name>/\`
+
+**full schema 段落上限：**
+
+| 段落     | 上限             | 来源                            |
+|---------|------------------|---------------------------------|
+| 改了什么 | 6 条 bullet      | proposal 的"能力"小节           |
+| 关键决策 | 5 条 bullet      | design 的"决策"小节             |
+| 影响范围 | 8 节点 ASCII 图  | proposal 的"影响范围" + design  |
+| 风险    | 3 条 bullet      | design 的"风险与权衡"           |
+
+**lite schema 段落上限：**
+
+| 段落     | 上限             | 来源                          |
+|---------|------------------|-------------------------------|
+| 改了什么 | 6 条 bullet      | tasks.md 任务组标题 + 推断    |
+| 任务概览 | 1 行/任务组      | tasks.md 一级标题 + 完成进度  |
+
+**影响范围图退化策略：**
+
+如果节点数超 8 个 / 关系不清晰 / 没有明显依赖结构 → 改用 bullet 列模块名，不要硬画歪斜的 ASCII。
+
+**任务进度条规则（lite）：**
+
+进度条固定 10 格宽，按 \`completed/total\` 比例画。例如 \`8/8\` → \`██████████\`，\`3/5\` → \`██████░░░░\`。
+
+---
+
+## 输出样例
+
+**full schema：**
+
+\`\`\`
+╭─ <name> ────────────────────────────── full · <N> 任务 ─╮
+│                                                          │
+│  <一句话动机，从 proposal "动机" 段提炼，≤ 55 字>         │
+│                                                          │
+│  ━━ 改了什么 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ │
+│   ✚ <capability-name>     <一句话能力描述>               │
+│   ...                                                    │
+│                                                          │
+│  ━━ 关键决策 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ │
+│   1. <决策内容>                                          │
+│   ...                                                    │
+│                                                          │
+│  ━━ 影响范围 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ │
+│      <ASCII 图 或 bullet 模块列表>                       │
+│                                                          │
+│  ━━ 风险 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ │
+│   • <风险>                                               │
+│                                                          │
+╰──────────────────────────────────────────────────────────╯
+\`\`\`
+
+**lite schema：**
+
+\`\`\`
+╭─ <name> ──────────────────────────── lite · <N> 任务 ─╮
+│                                                       │
+│  <一句话动机，从 tasks.md "背景" 段提炼>             │
+│                                                       │
+│  ━━ 改了什么 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ │
+│   • <推断的核心变更>                                  │
+│                                                       │
+│  ━━ 任务概览 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ │
+│   1. <任务组标题>      ██████████ N/M ✓             │
+│                                                       │
+╰───────────────────────────────────────────────────────╯
+\`\`\`
+
+**护栏**
+
+- 不写文件，纯 stdout 输出
+- 不调用 AskUserQuestion 询问"要打印什么"，遵守摘要规则即可
+- 不展开补全 artifact 信息——artifact 里没有的，摘要里就不该有
+- state 为 \`blocked\` 时拒绝生成，不强行摘要半成品
+- 不要在卡片外加解释段落，只打印卡片 + 下一步提示
+- \`instruction\` 字段（apply JSON 里有）是给 apply 用的，不是给 preview 的，忽略它
+`},propose:{fileName:`propose.md`,content:`---
+name: "Marchen: Propose"
+description: 提出新变更，创建并填充所有 artifact
+category: Workflow
+tags: [workflow, artifacts]
+---
+
+提出新变更 — 创建变更目录并按依赖顺序生成所有 artifact。
+
+将创建以下 artifact：
+- proposal.md（动机和变更内容）
+- specs/（每个能力的需求规格）
+- design.md（技术方案）
+- tasks.md（实现任务清单）
+
+完成后可用 /marchen:apply 开始实现。
+
+---
+
+**输入**：\`/marchen:propose\` 后面跟变更名称（kebab-case）或变更描述。
+
+**流程**
+
+1. **确定变更名称**
+
+   如果提供了输入，直接使用或从描述中提取 kebab-case 名称（如"添加用户认证" → \`add-user-auth\`）。
+
+   如果没有输入，用 **AskUserQuestion** 工具询问：
+   > "你想做什么变更？描述一下你要构建或修复的内容。"
+
+   从回答中提取 kebab-case 名称。
+
+   **重要**：必须理解用户想做什么才能继续。
+
+2. **创建变更目录**
+
+   \`\`\`bash
+   marchen new <name>
+   \`\`\`
+
+   创建 \`marchen/changes/<name>/\` 目录和 \`.metadata.yaml\`。
+
+   如果同名变更已存在，用 **AskUserQuestion** 询问用户是继续已有变更还是换个名称。
+
+3. **循环创建 artifact**
+
+   用 **TaskCreate** 工具创建任务列表追踪进度。
+
+   循环执行以下步骤：
+
+   a. **查询当前状态**
+      \`\`\`bash
+      marchen status <name> --json
+      \`\`\`
+      返回 JSON 包含：
+      - \`workflow.next\`：下一个应该创建的 artifact ID，全部完成时为 \`null\`
+      - \`workflow.ready\`：当前可以创建的 artifact 列表
+      - \`workflow.blocked\`：被阻塞的 artifact 列表
+      - \`artifacts\`：每个 artifact 的状态详情（\`id\`、\`status\`、\`path\`）
+
+      如果 \`workflow.next\` 为 \`null\` → 全部完成，跳到第 4 步。
+
+   b. **获取创建指令**
+      \`\`\`bash
+      marchen instructions <name> <workflow.next> --json
+      \`\`\`
+      返回 JSON 包含：
+      - \`template\`：artifact 的 markdown 骨架结构，用它作为输出文件的框架
+      - \`instruction\`：如何填充该 artifact 的指导文本
+      - \`outputPath\`：写入路径（相对于变更目录）
+      - \`context\`：上下文 artifact 的信息数组，每项包含 \`id\`、\`status\`、\`content\`（已填充的内容直接在这里，不需要额外读文件）
+      - \`unlocks\`：完成此 artifact 后解锁的 artifact 列表
+
+   c. **创建 artifact**
+
+      根据 artifact 类型处理：
+
+      **普通 artifact（proposal / design / tasks）：**
+      - 读取 \`context\` 中 \`status\` 为 \`filled\` 的 \`content\` 作为上下文
+      - 按 \`instruction\` 指引 + \`template\` 结构生成内容
+      - 写入 \`marchen/changes/<name>/<outputPath>\`
+      - 写入后验证文件存在
+
+      **specs（目录型 artifact，outputPath 为 \`specs/\`）：**
+      - 读取 proposal 内容（在 \`context\` 中，\`id\` 为 \`proposal\` 的 \`content\`）
+      - 从 proposal 的"能力"章节提取能力列表（kebab-case 名称）
+      - 为每个能力：
+        - 创建目录 \`marchen/changes/<name>/specs/<capability>/\`
+        - 按 \`template\` 结构 + \`instruction\` 指引生成 spec 内容
+        - 写入 \`specs/<capability>/spec.md\`
+      - 写入后验证每个 spec 文件存在
+
+      **如果 proposal 的上下文不够清晰**（用户描述太模糊）：
+      - 用 **AskUserQuestion** 澄清关键信息
+      - 然后继续创建
+
+   d. 显示进度："已创建 \`<artifact-id>\`"，标记任务完成，回到步骤 a。
+
+4. **显示最终状态**
+
+   \`\`\`bash
+   marchen status <name>
+   \`\`\`
+
+**输出**
+
+完成后显示：
+- 变更名称和目录位置
+- 已创建的 artifact 列表及简要说明
+- 用纯文字（不调用 AskUserQuestion，不自动执行）提示下一步两个并列选项，由用户自行决定：
+
+  \`\`\`
+  下一步：
+    /marchen:apply <name>           直接开始实现
+    /marchen:propose-preview <name> 先看一眼浓缩摘要再决定
+  \`\`\`
+
+**护栏**
+
+- 按依赖顺序创建，不跳过 artifact
+- 每次循环创建一个 artifact（specs 算一个，但包含多个文件）
+- 写入后验证文件存在再继续下一个
+- 如果上下文关键信息不清楚，询问用户；但小疑问优先做合理判断，保持节奏
+- 已存在同名变更时必须询问用户，不要覆盖
+- \`instruction\` 是给你的指引，不要把它原样复制到 artifact 文件中
+- 使用 AskUserQuestion 时，选项不超过 4 个；需要更多选项时合并或分步询问
+`},review:{fileName:`review.md`,content:`---
+name: "Marchen: Review"
+description: 对照变更意图检查代码实现，支持 chrome-devtools MCP 的 UI 场景验证
+category: Workflow
+tags: [workflow, review]
+---
+
+对照变更的 artifact 检查代码改动，必要时驱动浏览器验证 UI 行为，报告遗漏、偏差和阻塞。
+
+---
+
+**输入**：\`/marchen:review\` 后面跟变更名称，或省略自动推断。
+
+**流程**
+
+1. **选择变更**
+
+   有名称就用，没有则：
+   - 从对话上下文推断
+   - 只有一个 open 变更时自动选择
+   - 多个变更时 \`marchen list --json\` + **AskUserQuestion** 让用户选
+
+   显示："Review 变更: \`<name>\`"
+
+2. **嗅探 diff 中的 UI 改动**
+
+   执行 \`git diff --name-only HEAD\`，判断改动是否涉及前端 UI（组件、样式、模板、静态资源等）。命中则记下命中文件，用于下一步的提示。
+
+3. **AskUserQuestion 选择 review 模式**
+
+   用 **AskUserQuestion** 让用户三选一：
+
+   - **代码 review**（默认）：对照 artifact 检查 git diff，不跑代码
+   - **UI 验证**：用 chrome-devtools MCP 实际打开页面验证 specs 中的场景
+   - **两者都做**：先代码、再 UI
+
+   若上一步命中 UI 文件，在问题描述里附一句："检测到 diff 涉及 UI 文件（<列出命中文件>），建议选 UI 验证或两者都做。"
+   未命中时不附加提示，默认推荐"代码 review"。
+
+   保存用户选择为 \`<mode>\`。
+
+4. **获取意图与改动（公共前置）**
+
+   - 执行 \`marchen instructions <name> apply --json\`，从返回 JSON 的 \`context\` 数组里读取 \`status\` 为 "filled" 的 artifact（proposal/specs/design/tasks）作为变更意图
+   - 执行 \`git diff HEAD\`；为空则 \`git diff HEAD~1\`；仍为空则报告 "未检测到代码改动" 并结束
+
+   diff 大到可能挤占 context 时，先 \`git diff --stat HEAD\` 看摘要，再按需读单个文件 diff。
+
+5. **代码 review**（mode 为 "代码 review" 或 "两者都做" 时执行）
+
+   逐条对照变更意图和代码改动，输出报告：
+
+   **任务完成度** — tasks 中每个任务是否有对应改动：
+   - ✅ 任务: <描述> — 已实现
+   - ❌ 任务: <描述> — 未找到对应改动
+
+   **一致性检查** — 实现是否符合 design 决策：
+   - ✅ <决策> — 已遵守
+   - ⚠️ <决策> — 实现有偏差：<说明>
+
+   **需求覆盖** — specs 中需求是否被覆盖：
+   - ✅ <需求> — 已覆盖
+   - ❌ <需求> — 未覆盖
+
+   **发现的问题（如有）**
+   - <文件:行号> <问题描述>
+
+   全部通过：输出 "✅ 代码 review 通过。"
+
+   遇到无法判断的情况（tasks 描述与 diff 对不上但可能是改名了、spec 表述含糊等），直接用 **AskUserQuestion** 就地问用户，不要积攒到最后。
+
+6. **UI 验证**（mode 为 "UI 验证" 或 "两者都做" 时执行）
+
+   ### a. 检测 chrome-devtools MCP 可用性
+
+   尝试调用 chrome-devtools MCP 的只读探测工具（例如列出已打开的页面）。工具不存在或调用失败 → 在报告里写：
+
+   > ⏭ chrome-devtools MCP 不可用，跳过 UI 验证。
+   > 安装方法：\`npx chrome-devtools-mcp@latest\`，并参考所用 AI 工具的 MCP 配置文档将其注册。
+
+   然后跳过本节剩余步骤。
+
+   ### b. 提取待验证场景
+
+   优先从变更的 specs 文件中提取所有 \`#### 场景:\` 块（按 spec 文件分组）。
+   若 specs 不存在或不含场景 → 退化到从 tasks/proposal 推断 UI 相关验证点，并在报告中标注 "基于 tasks 推断，覆盖度可能不完整"。
+   两者都没有可提取场景 → 报告 "未找到可验证的 UI 场景" 并跳过本节。
+
+   ### c. 推断 dev server URL
+
+   从项目文件（脚本、框架配置、环境变量、README 等）推断 dev server 地址和启动命令，不要硬猜端口。
+
+   推出候选 URL 后用 chrome-devtools MCP 的导航工具打开，再用快照工具确认页面像被测应用（合理 title、含框架 root 节点或变更描述涉及的标志性内容）。看着不像被测应用 → 当作未能推断。
+
+   推不出 URL → 全部场景 ⏭ "URL unknown"，在报告里说明推断依据，提示用户确认地址后重新运行 review，跳过本节执行步骤。
+
+   ### d. 推断到 URL 但 dev server 未启动 → 询问是否帮忙起
+
+   推出来 URL 但导航失败（连接拒绝）→ 主会话 **AskUserQuestion**，附上推断依据和启动命令：
+
+   - **帮我起 dev server 然后继续**
+   - **我手动起，起完告诉你**
+   - **跳过 UI 验证**
+
+   选"帮我起"：
+   1. 用 Bash 的 \`run_in_background\` 执行推断到的启动命令（如 \`pnpm dev\`、\`npm run dev\`）
+   2. 轮询端口直到可访问；出现明显异常（进程退出 / 长时间无任何输出 / 报错日志）才判定启动失败，让用户手动检查
+   3. 启动成功后继续执行后续步骤，并在 review 结束时显式告知用户后台进程 PID 和端口，提示 "用完请自行 kill <PID>"——MUST NOT 自动 kill
+
+   选"我手动起"：等用户告知启动完成后继续；用户可以新会话执行 \`/marchen:review\` 重跑。
+
+   选"跳过 UI"：所有场景 ⏭ "dev server 未启动"，跳过后续步骤。
+
+   ### e. 乐观执行场景
+
+   对每个待验证场景：
+
+   1. 用 chrome-devtools MCP 的导航工具打开对应路径
+   2. 用快照工具观察页面状态
+   3. 把场景的 GIVEN/WHEN/THEN 翻译成具体交互（点击、填写、读取文本）并执行
+   4. 比对页面状态与场景预期
+
+   遇到阻塞（登录墙、权限不足、缺数据、表单需要真实输入等）：**主会话可以就地 AskUserQuestion**——例如"需要登录账号才能继续，提供测试账号？/ 跳过这个场景 / 暂停 review"，而不必积攒到最后。
+
+   仍无法继续的场景 → 记录 ⏭ + 阻塞原因，跳到下一个。
+   场景翻译不出具体操作（例如纯后端行为描述）→ ⏭ "不适合 UI 验证"。
+
+   ### f. UI 报告格式
+
+   \`\`\`
+   ## UI 验证（chrome-devtools MCP）
+
+   测试目标：<URL 或 "未确定">
+
+   ✅ <场景标题> — 通过
+        说明：<可选简述>
+   ❌ <场景标题> — 失败
+        证据：<console error 摘要 / 页面文案 / 关键截图路径>
+   ⏭ <场景标题> — 跳过：<阻塞原因>
+   \`\`\`
+
+7. **展示报告并按结果分支**
+
+   - **全部通过且无 ⏭**：提示 "可以用 \`/marchen:archive\` 归档。"
+   - **有 ❌ 失败**：提示用户修复后可以再次 \`/marchen:review\`。
+   - **有 ⏭ 跳过**：用 **AskUserQuestion** 让用户选择：
+     - **补信息后继续**：收集所需信息（账号、数据等），就地再跑被跳过的场景
+     - **跳过这些场景，继续归档**：保留报告，提示 \`/marchen:archive\`
+     - **暂停去修复**：什么都不做
+
+   如本次 review 启动了后台 dev server，再次提醒用户进程信息（PID/端口）。
+
+**护栏**
+
+- 不要修改任何代码，只报告（review 不是 apply）
+- UI 验证阻塞即停，不要硬闯（不登录、不猜数据、不绕权限）；要继续就向用户索取信息
+- 起 dev server 必须先获得用户授权（AskUserQuestion）；起完不自动 kill，告知 PID 让用户自行管理
+- 用户提供的凭据/账号等敏感数据：不写入任何 artifact，不在报告里复述明文，截图前对密码/token/邮箱等敏感字段脱敏或回避
+- 大 diff 先看 \`git diff --stat\`，按需读单个文件，避免灌爆 context
+- 使用 AskUserQuestion 时，选项不超过 4 个
+`}},x={antigravity:{id:`antigravity`,name:`Antigravity`,skillDir:`.agent/skills`},"claude-code":{id:`claude-code`,name:`Claude Code`,skillDir:`.claude/skills`,commandDir:`.claude/commands/marchen`},codex:{id:`codex`,name:`Codex`,skillDir:`.codex/skills`},copilot:{id:`copilot`,name:`GitHub Copilot`,skillDir:`.github/skills`},cursor:{id:`cursor`,name:`Cursor`,skillDir:`.cursor/skills`},"gemini-cli":{id:`gemini-cli`,name:`Gemini CLI`,skillDir:`.gemini/skills`},kilocode:{id:`kilocode`,name:`Kilo Code`,skillDir:`.kilocode/skills`},kiro:{id:`kiro`,name:`Kiro`,skillDir:`.kiro/skills`},opencode:{id:`opencode`,name:`OpenCode`,skillDir:`.opencode/skills`},windsurf:{id:`windsurf`,name:`Windsurf`,skillDir:`.windsurf/skills`}},S=[`claude-code`],C={full:{name:`full`,artifacts:[{id:`proposal`,generates:`proposal.md`,requires:[],template:`## 动机
+
+<!-- 说明这个变更的动机。解决什么问题？为什么现在做？ -->
+
+## 变更内容
+
+<!-- 描述具体变更内容。列出新增的能力、修改或移除的部分。 -->
+
+## 能力
+
+### 新增能力
+<!-- 新增的能力。使用 kebab-case 命名，每个会生成 specs/<name>/spec.md -->
+
+### 修改能力
+<!-- 需要修改的现有能力。仅当规范级别的行为发生变化时才列出。 -->
+
+## 影响范围
+
+<!-- 受影响的代码、API、依赖或系统 -->
+`,instruction:`根据用户的描述，填写 proposal 的各个部分。
+- 动机：说明为什么要做这个变更，解决什么问题
+- 变更内容：列出具体改动
+- 能力：列出需要创建 spec 的 capability（kebab-case 命名），每个会生成 specs/<name>/spec.md
+- 影响范围：说明涉及的代码和系统
+保持简洁，1-2 页。聚焦"为什么"和"做什么"，不要写实现细节。`},{id:`specs`,generates:`specs/`,requires:[`proposal`],template:`## 目的
+
+<!-- 这个能力的领域职责，一两句话 -->
+
+### 需求: <!-- 需求名称 -->
+
+<!-- 系统 SHALL/MUST 做什么（必须有描述文本） -->
+
+#### 场景: <!-- 场景名称 -->
+
+- **GIVEN** <!-- 前置条件/上下文 -->
+- **WHEN** <!-- 触发动作 -->
+- **THEN** <!-- 期望结果 -->
+- **AND** <!-- 追加条件或结果 -->
+`,instruction:`根据 proposal 中列出的能力，为每个能力创建 specs/<name>/spec.md。
+
+格式规则：
+- 以 '## 目的' 开头，一两句话说明这个能力的领域职责
+- 每个需求用 '### 需求:' 开头，标题后必须有描述文本（用 SHALL/MUST 表述行为）
+- 每个场景用 '#### 场景:' 开头（必须 4 个 #）
+- 场景内容用列表格式，关键字加粗：- **GIVEN** / - **WHEN** / - **THEN** / - **AND**
+- GIVEN 描述前置条件（可省略，但推荐写明）
+- 每个需求至少一个场景
+- 场景应该是可测试的（每个场景对应一个潜在的 test case）
+
+内容约束：
+- 只描述可观察行为，不描述实现方式
+- 不包含内部类名、函数名、框架/库选择等实现细节（这些属于 design.md）
+- 使用 RFC 2119 关键字表达需求强度：SHALL/MUST（必须）、SHOULD（推荐）、MAY（可选）`},{id:`design`,generates:`design.md`,requires:[`proposal`],template:`## 背景
+
+<!-- 背景和当前状态 -->
+
+## 目标与非目标
+
+**目标：**
+<!-- 这个设计要达成什么 -->
+
+**非目标：**
+<!-- 明确排除在范围之外的内容 -->
+
+## 决策
+
+<!-- 关键技术决策和理由 -->
+
+## 风险与权衡
+
+<!-- 已知风险和权衡 -->
+`,instruction:`根据 proposal 的动机和 specs 的需求，设计技术实现方案。
+- 背景：当前状态和约束
+- 目标与非目标：明确范围
+- 决策：关键技术选择和理由（为什么选 X 而不是 Y）
+- 风险与权衡：已知限制和可能出错的地方
+聚焦架构和方案，不要写逐行实现细节。`},{id:`tasks`,generates:`tasks.md`,requires:[`specs`,`design`],template:`## 1. <!-- 任务组名称 -->
+
+- [ ] 1.1 <!-- 任务描述 -->
+- [ ] 1.2 <!-- 任务描述 -->
+`,instruction:`根据 specs 的需求和 design 的技术方案，拆分实现任务。
+- 按任务组分组，每组用 ## 标题
+- 每个任务用 checkbox 格式：- [ ] X.Y 描述
+- 任务粒度要小到一个会话内能完成
+- 按依赖顺序排列（先做的在前）`}]},lite:{name:`lite`,artifacts:[{id:`tasks`,generates:`tasks.md`,requires:[],template:`## 背景
+
+<!-- 简要说明这个变更的目的和方案 -->
+
+## 1. <!-- 任务组名称 -->
+
+- [ ] 1.1 <!-- 任务描述 -->
+- [ ] 1.2 <!-- 任务描述 -->
+`,instruction:`根据背景描述，拆分实现任务。
+- 按任务组分组，每组用 ## 标题
+- 每个任务用 checkbox 格式：- [ ] X.Y 描述
+- 任务粒度要小到一个会话内能完成
+- 按依赖顺序排列（先做的在前）`}]}};function w(e){let t=C[e];if(!t)throw new _(`Schema "${e}" 不存在，可用的 schema: ${Object.keys(C).join(`, `)}`);return t}const T={apply:{dirName:`marchen-apply`,content:`---
+name: marchen-apply
+description: 按变更的 tasks.md 逐个实现任务。适用于用户想按任务清单逐步实现代码。
+---
+
+按变更的 tasks.md 逐个实现任务，完成后勾选 checkbox。
+
+---
+
+**输入**：用户的请求应包含变更名称，或可从上下文推断。
+
+**流程**
+
+1. **选择变更**
+
+   有名称就用，没有则：
+   - 从对话上下文推断
+   - 只有一个 open 变更时自动选择
+   - 多个变更时 \`marchen list --json\` + **AskUserQuestion** 让用户选
+
+   显示："使用变更: \`<name>\`"
+
+2. **获取实现指令**
+
+   \`\`\`bash
+   marchen instructions <name> apply --json
+   \`\`\`
+
+   返回 JSON 包含：
+   - \`state\`：\`"ready"\` / \`"blocked"\` / \`"all_done"\`
+   - \`progress\`：\`{ total, completed, remaining }\`
+   - \`context\`：所有 artifact 的信息数组，每项包含 \`id\`、\`status\`、\`path\`、\`content\`
+   - \`instruction\`：实现指引
+   - \`changeDir\`：变更目录绝对路径
+
+   根据 \`state\` 处理：
+   - \`"blocked"\` → 提示先完成 artifacts
+   - \`"all_done"\` → 提示归档
+   - \`"ready"\` → 继续
+
+3. **显示进度**
+
+   从返回的 JSON 读取并显示：
+   "变更: \`<name>\` | 进度: N/M | 下一个: <第一个未完成任务的描述>"
+
+4. **逐个实现任务**
+
+   从 \`context\` 中读取所有 artifact 内容作为上下文。
+
+   对每个未完成任务：
+   - 显示 "任务 N/M: <描述>"
+   - 实现代码改动
+   - 在 tasks.md 中勾选：\`- [ ]\` → \`- [x]\`
+     文件路径：\`<changeDir>/tasks.md\`
+   - 显示 "✓ 完成"
+   - 继续下一个
+
+   **暂停条件：**
+   - 任务不清晰 → 询问用户
+   - 发现设计问题 → 建议更新 artifact
+   - 遇到错误或阻塞 → 报告并等待
+   - 用户中断
+
+5. **显示结果**
+
+   全部完成时：
+   "全部完成 (N/N)，可以用 \`marchen review <name>\` 检查实现，或直接 \`marchen archive <name>\` 归档。"
+
+   暂停时：
+   "暂停于任务 N/M: <原因>"
+
+**护栏**
+
+- 实现前必须读 context 中的 artifact 内容
+- 每完成一个任务立即勾选 checkbox，不要攒着
+- 改动最小化，只做任务要求的事
+- 不确定就暂停问，不要猜
+- 如果实现过程中遇到不确定的设计决策，可以用 \`marchen search "<关键词>" --json\` 搜索历史变更中的相关方案
+- \`instruction\` 是给你的指引，不要原样复制到代码注释中
+`},archive:{dirName:`marchen-archive`,content:`---
+name: marchen-archive
+description: 归档已完成的变更。检查完成度后执行归档，适用于实现完毕后收尾。
+---
+
+归档已完成的变更，检查完成度后执行归档。
+
+---
+
+**输入**：用户的请求可包含变更名称（如 \`/marchen:archive add-auth\`），也可不带。
+
+**流程**
+
+1. **确定变更名称**
+
+   有名称就用，没有则：
+   - 从对话上下文推断
+   - 只有一个 open 变更时自动选择
+   - 多个变更时 \`marchen list --json\` + **AskUserQuestion** 让用户选
+
+   **重要**：不要猜测或自动选择，必须让用户确认。
+
+2. **检查完成度**
+
+   \`\`\`bash
+   marchen status <name> --json
+   \`\`\`
+
+   解析 JSON，检查：
+   - \`artifacts\`：每个 artifact 的 \`status\` 是否为 \`filled\`
+   - \`tasks.completed\` vs \`tasks.total\`（\`tasks\` 为 null 时视为无任务，跳过检查）
+
+   **如果全部完成：** 直接进入下一步。
+
+   **如果有未完成的 artifact 或 task：**
+   - 显示警告，列出未完成项
+   - 用 **AskUserQuestion** 确认是否继续
+   - 用户确认后继续，不阻塞
+
+3. **生成摘要**
+
+   读取 \`marchen/changes/<name>/proposal.md\`，从中生成一句话中文摘要（≤50字），概括这次变更做了什么。摘要应包含关键语义词，便于后续 AI 检索。
+
+4. **执行归档**
+
+   \`\`\`bash
+   marchen archive <name> --summary "<生成的摘要>" --json
+   \`\`\`
+
+   解析返回的 JSON 获取归档结果。
+
+5. **显示结果**
+
+   \`\`\`
+   变更 "<name>" 已归档
+   Schema: <schema>
+   归档到: <archivedTo>
+   \`\`\`
+
+   如有警告（未完成项），一并显示。
+
+**护栏**
+
+- 未提供名称时必须用 AskUserQuestion 让用户选择
+- 用 \`status --json\` 检查完成度，不要自己读文件判断
+- 警告不阻塞归档，只提醒 + 确认
+- 使用 AskUserQuestion 时，选项不超过 4 个
+`},explore:{dirName:`marchen-explore`,content:`---
+name: marchen-explore
+description: 进入探索模式 — 思考想法、调查问题、厘清需求。适用于用户想在动手之前先理清思路。
+---
+
+进入探索模式。深入思考，自由可视化，跟随对话走向任何方向。
+
+**重要：探索模式只用于思考，不用于实现。** 可以读文件、搜索代码、调查代码库，但绝不能写代码或实现功能。如果用户要求实现，提醒他们先退出探索模式并用 \`/marchen:propose\` 创建变更。可以创建 Marchen artifact（proposal、design、spec）——那是捕获思考，不是实现。
+
+**这是一种姿态，不是工作流。** 没有固定步骤、没有必须的顺序、没有强制输出。你是帮助用户探索的思考伙伴。
+
+**输入**：\`/marchen:explore\` 后面可以跟任何内容：
+- 模糊的想法："实时协作"
+- 具体的问题："auth 系统越来越难维护了"
+- 变更名称："add-dark-mode"（在该变更上下文中探索）
+- 方案比较："postgres vs sqlite"
+- 什么都不带也行
+
+---
+
+## 姿态
+
+- **好奇，不武断** — 提出自然涌现的问题，不按脚本走
+- **开放线索，不审问** — 展示多个有趣方向，让用户跟随感兴趣的。不要把他们引导到单一路径上
+- **视觉化** — 大量使用 ASCII 图表来辅助思考
+- **自适应** — 跟随有趣的线索，有新信息时及时转向
+- **耐心** — 不急于下结论，让问题的形状自然浮现
+- **接地气** — 在相关时探索实际代码库，不要空谈理论
+
+---
+
+## 你可以做什么
+
+根据用户带来的内容，你可能会：
+
+**探索问题空间**
+- 提出从用户所说内容中自然涌现的澄清问题
+- 挑战假设
+- 重新框定问题
+- 寻找类比
+
+**调查代码库**
+- 映射与讨论相关的现有架构
+- 找到集成点
+- 识别已有的模式
+- 发现隐藏的复杂性
+
+**比较方案**
+- 头脑风暴多种方案
+- 构建比较表
+- 勾勒权衡
+- 推荐路径（如果被问到）
+
+**可视化**
+\`\`\`
+┌─────────────────────────────────────────┐
+│     Use ASCII diagrams liberally        │
+├─────────────────────────────────────────┤
+│                                         │
+│   ┌────────┐         ┌────────┐        │
+│   │ State  │────────▶│ State  │        │
+│   │   A    │         │   B    │        │
+│   └────────┘         └────────┘        │
+│                                         │
+│   System diagrams, state machines,      │
+│   data flows, architecture sketches,    │
+│   dependency graphs, comparison tables  │
+│                                         │
+└─────────────────────────────────────────┘
+\`\`\`
+
+**发现风险和未知**
+- 识别可能出错的地方
+- 找到理解上的空白
+- 建议 spike 或调查
+
+---
+
+## Marchen 感知
+
+你了解 Marchen 系统。自然地使用它，不要强制。
+
+### 检查上下文
+
+开始时快速检查现有状态和历史：
+
+1. 当前变更：
+\`\`\`bash
+marchen list --json
+\`\`\`
+
+2. 变更历史概览：
+\`\`\`bash
+cat marchen/changelog.md
+\`\`\`
+这是所有已归档变更的索引，每条包含日期、变更名和一句话摘要。先扫一遍找到与用户话题相关的条目。如果找到，直接读对应 archive 目录下的 proposal.md 或 design.md 了解详情。
+
+3. 语义搜索：
+
+这是 RAG 搜索，不是 grep——构造语义完整的短语，不要用单个泛词。
+
+\`\`\`bash
+marchen search "<语义完整的查询短语>" --json
+\`\`\`
+
+**查询构造指引：**
+- 用描述性短语，不用单个词：
+  "初始化适配多个 agent 客户端" → \`"multi-agent provider 初始化"\`
+  "之前怎么处理错误的" → \`"错误处理 error handling 重构"\`
+  "暗色模式的设计决策" → \`"dark mode 设计方案"\`
+- 中英文混合效果更好（归档内容里中英都有）
+- 如果结果不理想，换个角度重新构造查询
+
+如果有匹配结果（score >= 0.4），读取对应 archive 目录下的 design.md 或 proposal.md 了解详细决策。
+
+如果 \`marchen search\` 不可用（命令报错），回退到 changelog.md + 手动读 archive 目录。
+
+这告诉你：
+- 是否有进行中的变更
+- 它们的名称、schema 和状态
+- 项目过去做过哪些变更
+- 用户可能在做什么
+
+如果用户提到了特定变更名称，读取它的 artifact 作为上下文。
+
+### 没有变更时
+
+自由思考。当洞察结晶时，根据复杂度推荐下一步：
+
+**判断标准：**
+- \`/marchen:lite\` — bug 修复、小改动、单一任务组、不需要设计文档
+- \`/marchen:propose\` — 新功能、多步骤、需要 design/specs、涉及多模块
+
+**推荐方式：** 直接在回复中输出推荐，说明理由，让用户自行输入命令。示例：
+
+> 想法差不多成型了。这个改动比较简单（只涉及一个文件的小调整），建议用 \`/marchen:lite\` 直接走轻量流程。
+>
+> 如果你觉得需要更完整的设计文档，也可以用 \`/marchen:propose\`。
+
+根据讨论内容给出你的推荐和理由，但让用户自己决定输入哪个命令。
+
+### 有变更时
+
+如果用户提到了变更或你发现某个变更相关：
+
+1. **读取已有 artifact 作为上下文**
+   - \`marchen/changes/<name>/proposal.md\`
+   - \`marchen/changes/<name>/design.md\`
+   - \`marchen/changes/<name>/tasks.md\`
+   - 等
+
+2. **在对话中自然引用**
+   - "你的 design 提到用 Redis，但我们刚发现 SQLite 更合适……"
+   - "proposal 把范围限定在付费用户，但我们现在觉得应该面向所有人……"
+
+3. **在做出决策时提议捕获**
+
+   | 洞察类型 | 捕获到哪里 |
+   |---------|-----------|
+   | 发现新需求 | \`specs/<capability>/spec.md\` |
+   | 需求变更 | \`specs/<capability>/spec.md\` |
+   | 做出设计决策 | \`design.md\` |
+   | 范围变更 | \`proposal.md\` |
+   | 发现新工作 | \`tasks.md\` |
+   | 假设被推翻 | 相关 artifact |
+
+   示例：
+   - "这是一个设计决策。要记录到 design.md 吗？"
+   - "这是新需求。要加到 specs 里吗？"
+   - "这改变了范围。要更新 proposal 吗？"
+
+4. **用户决定** — 提议后继续。不施压，不自动捕获。
+
+---
+
+## 不必做的事
+
+- 按脚本走
+- 每次问同样的问题
+- 产出特定 artifact
+- 得出结论
+- 如果有价值的岔路就不必守住话题
+- 简短（这是思考时间）
+
+---
+
+## 结束探索
+
+没有固定的结束方式。探索可能：
+
+- **流向下一阶段**：用 **AskUserQuestion** 提供 \`/marchen:lite\` 和 \`/marchen:propose\` 选项，附带推荐理由
+- **更新 artifact**："已将这些决策更新到 design.md"
+- **只是提供清晰度**：用户得到了需要的，继续前进
+- **稍后继续**："随时可以继续"
+
+当想法结晶时，你可以提供总结——但不是必须的。有时候思考过程本身就是价值。
+
+---
+
+## 护栏
+
+- **不实现** — 绝不写代码或实现功能。创建 Marchen artifact 可以，写应用代码不行
+- **不伪装理解** — 不清楚就深挖
+- **不催促** — 探索是思考时间，不是任务时间
+- **不强制结构** — 让模式自然浮现
+- **不自动捕获** — 提议保存洞察，不要直接做
+- **要可视化** — 一张好图胜过千言万语
+- **要探索代码库** — 让讨论扎根于现实
+- **要质疑假设** — 包括用户的和你自己的
+`},lite:{dirName:`marchen-lite`,content:`---
+name: marchen-lite
+description: 一键式轻量变更流程。创建 lite 变更、实现任务、询问归档，一气呵成。适合 bug 修复、小改动。
+---
+
+一键式轻量变更 — 使用 lite schema 创建变更，自动实现任务，完成后询问归档。
+适合 bug 修复、小改动、explore 之后的快速执行。
+
+---
+
+**输入**：用户的请求应包含变更名称（kebab-case）或变更描述。
+
+**流程**
+
+1. **确定变更名称**
+
+   如果提供了输入，直接使用或从描述中提取 kebab-case 名称（如"修复登录 bug" → \`fix-login-bug\`）。
+
+   如果没有输入，用 **AskUserQuestion** 工具询问：
+   > "你想做什么变更？描述一下你要构建或修复的内容。"
+
+   从回答中提取 kebab-case 名称。
+
+   **重要**：必须理解用户想做什么才能继续。
+
+2. **创建变更目录**
+
+   \`\`\`bash
+   marchen new <name> --schema lite
+   \`\`\`
+
+   创建 \`marchen/changes/<name>/\` 目录，包含 \`.metadata.yaml\` 和 \`tasks.md\` 骨架。
+
+   如果同名变更已存在，用 **AskUserQuestion** 询问用户是继续已有变更还是换个名称。
+
+3. **获取 tasks 指令**
+
+   \`\`\`bash
+   marchen status <name> --json
+   \`\`\`
+
+   确认变更创建成功，然后获取 tasks 的创建指令：
+
+   \`\`\`bash
+   marchen instructions <name> tasks --json
+   \`\`\`
+
+   返回 JSON 包含：
+   - \`template\`：tasks.md 的骨架结构（含 \`## 背景\` 章节）
+   - \`instruction\`：如何填充 tasks 的指导文本
+   - \`outputPath\`：写入路径（\`tasks.md\`）
+   - \`context\`：上下文信息（lite schema 下为空数组）
+
+4. **填充 tasks.md**
+
+   根据用户描述 + \`instruction\` 指引 + \`template\` 结构，填充 tasks.md：
+   - \`## 背景\`：简要说明变更目的和方案
+   - 任务列表：按组分类，checkbox 格式
+
+   写入 \`marchen/changes/<name>/tasks.md\`。
+
+   如果用户描述太模糊，用 **AskUserQuestion** 澄清关键信息。
+
+5. **开始实现**
+
+   获取实现指令：
+
+   \`\`\`bash
+   marchen instructions <name> apply --json
+   \`\`\`
+
+   返回 JSON 包含：
+   - \`state\`：\`"ready"\` / \`"blocked"\` / \`"all_done"\`
+   - \`progress\`：\`{ total, completed, remaining }\`
+   - \`context\`：所有 artifact 的信息数组
+   - \`instruction\`：实现指引
+   - \`changeDir\`：变更目录绝对路径
+
+   显示："变更: \`<name>\` | 任务: 0/N | 开始实现..."
+
+   对每个未完成任务：
+   - 显示 "任务 N/M: <描述>"
+   - 实现代码改动
+   - 在 tasks.md 中勾选：\`- [ ]\` → \`- [x]\`
+     文件路径：\`<changeDir>/tasks.md\`
+   - 显示 "✓ 完成"
+   - 继续下一个
+
+   **暂停条件：**
+   - 任务不清晰 → 询问用户
+   - 发现设计问题 → 建议更新 artifact
+   - 遇到错误或阻塞 → 报告并等待
+   - 用户中断
+
+   暂停时显示："暂停于任务 N/M: <原因>"，流程结束。
+
+6. **全部完成 → 询问归档**
+
+   所有任务完成后，用 **AskUserQuestion** 询问：
+
+   > "全部任务已完成 (N/N)，是否归档这个变更？"
+   > - 归档
+   > - 暂不归档
+
+   **如果用户选择归档：**
+
+   读取 \`marchen/changes/<name>/tasks.md\` 的背景段，生成一句话中文摘要（≤50字）。
+
+   \`\`\`bash
+   marchen archive <name> --summary "<摘要>" --json
+   \`\`\`
+
+   显示：
+   \`\`\`
+   变更 "<name>" 已归档
+   归档到: <archivedTo>
+   \`\`\`
+
+   **如果用户选择暂不归档：**
+
+   显示："好的，后续可以用 \`/marchen:archive <name>\` 归档。"
+
+**护栏**
+
+- 必须使用 \`--schema lite\` 创建变更
+- tasks.md 的 \`## 背景\` 章节必须填写，不能留空
+- 任务粒度要小到一个会话内能完成
+- 如果上下文关键信息不清楚，询问用户；但小疑问优先做合理判断，保持节奏
+- 已存在同名变更时必须询问用户，不要覆盖
+- 实现前必须读 context 中的 artifact 内容
+- 每完成一个任务立即勾选 checkbox，不要攒着
+- 改动最小化，只做任务要求的事
+- 不确定就暂停问，不要猜
+- \`instruction\` 是给你的指引，不要把它原样复制到代码注释或 tasks.md 中
+- 使用 AskUserQuestion 时，选项不超过 4 个
+`},"propose-preview":{dirName:`marchen-propose-preview`,content:`---
+name: marchen-propose-preview
+description: 预览 propose 生成的变更摘要。从 proposal/design/specs/tasks 浓缩为终端卡片，便于人快速 review，决定下一步是 apply 还是改 propose。
+disable-model-invocation: true
+argument-hint: <change-name>
+---
+
+预览一个变更的浓缩摘要 — 纯终端输出，不写文件。
+
+适用于 propose 完成后人快速 review，避免来回翻 4~7 个 artifact 文件。
+
+---
+
+**输入**：用户的请求应包含变更名称，或可从上下文推断。
+
+**流程**
+
+1. **选择变更**
+
+   有名称就用，没有则：
+   - 从对话上下文推断
+   - 只有一个 open 变更时自动选择
+   - 多个变更时 \`marchen list --json\` + **AskUserQuestion** 让用户选
+
+   显示："Preview 变更: \`<name>\`"
+
+2. **获取 artifact 内容**
+
+   \`\`\`bash
+   marchen instructions <name> apply --json
+   \`\`\`
+
+   返回 JSON 包含：
+   - \`schemaName\`：\`"full"\` / \`"lite"\`
+   - \`state\`：\`"ready"\` / \`"blocked"\` / \`"all_done"\`
+   - \`progress\`：\`{ total, completed, remaining }\`
+   - \`context\`：所有 artifact 的内容数组（\`id\` / \`status\` / \`content\`）
+
+   **如果 state 为 \`blocked\`**：打印 "变更未填完，先用 /marchen:propose 补齐 artifact 再预览"，结束。不要强行摘要半成品。
+
+3. **生成卡片并直接打印**
+
+   根据 \`schemaName\` 选模板：
+   - \`full\` → 四段：改了什么 / 关键决策 / 影响范围 / 风险
+   - \`lite\` → 两段：改了什么 / 任务概览
+
+   严格按下面的"摘要规则"生成，输出为单个卡片，禁止加任何解释段落。
+
+4. **末尾追加一行下一步提示**
+
+   \`\`\`
+   /marchen:apply <name>           开始实现
+   /marchen:propose <name>         修改提案
+   \`\`\`
+
+---
+
+## 摘要规则（必须严格遵守）
+
+**通用约束：**
+
+- 卡片框宽 70 字符（含 \`│\` 边框），便于主流终端整齐显示
+- 每行内容（去掉边框后）≤ 60 字符；超出必须截断/合并/重写，不许折行
+- 禁止粘贴 artifact 原文片段，所有内容必须重新组织、压缩
+- 中文为主，技术名词保留英文（如 \`SearchManager\`、\`SDK\`）
+- 宁可少写，不要堆。摘不下就合并或截断，在框底加 \`更多详情见 marchen/changes/<name>/\`
+
+**full schema 段落上限：**
+
+| 段落     | 上限             | 来源                            |
+|---------|------------------|---------------------------------|
+| 改了什么 | 6 条 bullet      | proposal 的"能力"小节           |
+| 关键决策 | 5 条 bullet      | design 的"决策"小节             |
+| 影响范围 | 8 节点 ASCII 图  | proposal 的"影响范围" + design  |
+| 风险    | 3 条 bullet      | design 的"风险与权衡"           |
+
+**lite schema 段落上限：**
+
+| 段落     | 上限             | 来源                          |
+|---------|------------------|-------------------------------|
+| 改了什么 | 6 条 bullet      | tasks.md 任务组标题 + 推断    |
+| 任务概览 | 1 行/任务组      | tasks.md 一级标题 + 完成进度  |
+
+**影响范围图退化策略：**
+
+如果节点数超 8 个 / 关系不清晰 / 没有明显依赖结构 → 改用 bullet 列模块名，不要硬画歪斜的 ASCII。
+
+**任务进度条规则（lite）：**
+
+进度条固定 10 格宽，按 \`completed/total\` 比例画。例如 \`8/8\` → \`██████████\`，\`3/5\` → \`██████░░░░\`。
+
+---
+
+## 输出样例
+
+**full schema：**
+
+\`\`\`
+╭─ <name> ────────────────────────────── full · <N> 任务 ─╮
+│                                                          │
+│  <一句话动机，从 proposal "动机" 段提炼，≤ 55 字>         │
+│                                                          │
+│  ━━ 改了什么 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ │
+│   ✚ <capability-name>     <一句话能力描述>               │
+│   ...                                                    │
+│                                                          │
+│  ━━ 关键决策 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ │
+│   1. <决策内容>                                          │
+│   ...                                                    │
+│                                                          │
+│  ━━ 影响范围 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ │
+│      <ASCII 图 或 bullet 模块列表>                       │
+│                                                          │
+│  ━━ 风险 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ │
+│   • <风险>                                               │
+│                                                          │
+╰──────────────────────────────────────────────────────────╯
+\`\`\`
+
+**lite schema：**
+
+\`\`\`
+╭─ <name> ──────────────────────────── lite · <N> 任务 ─╮
+│                                                       │
+│  <一句话动机，从 tasks.md "背景" 段提炼>             │
+│                                                       │
+│  ━━ 改了什么 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ │
+│   • <推断的核心变更>                                  │
+│                                                       │
+│  ━━ 任务概览 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ │
+│   1. <任务组标题>      ██████████ N/M ✓             │
+│                                                       │
+╰───────────────────────────────────────────────────────╯
+\`\`\`
+
+**护栏**
+
+- 不写文件，纯 stdout 输出
+- 不调用 AskUserQuestion 询问"要打印什么"，遵守摘要规则即可
+- 不展开补全 artifact 信息——artifact 里没有的，摘要里就不该有
+- state 为 \`blocked\` 时拒绝生成，不强行摘要半成品
+- 不要在卡片外加解释段落，只打印卡片 + 下一步提示
+- \`instruction\` 字段（apply JSON 里有）是给 apply 用的，不是给 preview 的，忽略它
+`},propose:{dirName:`marchen-propose`,content:`---
+name: marchen-propose
+description: 提出新变更，创建并填充所有 artifact。适用于用户想快速描述需求并生成完整的 proposal、specs、design、tasks。
+---
+
+提出新变更 — 创建变更目录并按依赖顺序生成所有 artifact。
+
+将创建以下 artifact：
+- proposal.md（动机和变更内容）
+- specs/（每个能力的需求规格）
+- design.md（技术方案）
+- tasks.md（实现任务清单）
+
+完成后可用 /marchen:apply 开始实现。
+
+---
+
+**输入**：用户的请求应包含变更名称（kebab-case）或变更描述。
+
+**流程**
+
+1. **确定变更名称**
+
+   如果提供了输入，直接使用或从描述中提取 kebab-case 名称（如"添加用户认证" → \`add-user-auth\`）。
+
+   如果没有输入，用 **AskUserQuestion** 工具询问：
+   > "你想做什么变更？描述一下你要构建或修复的内容。"
+
+   从回答中提取 kebab-case 名称。
+
+   **重要**：必须理解用户想做什么才能继续。
+
+2. **创建变更目录**
+
+   \`\`\`bash
+   marchen new <name>
+   \`\`\`
+
+   创建 \`marchen/changes/<name>/\` 目录和 \`.metadata.yaml\`。
+
+   如果同名变更已存在，用 **AskUserQuestion** 询问用户是继续已有变更还是换个名称。
+
+3. **循环创建 artifact**
+
+   用 **TaskCreate** 工具创建任务列表追踪进度。
+
+   循环执行以下步骤：
+
+   a. **查询当前状态**
+      \`\`\`bash
+      marchen status <name> --json
+      \`\`\`
+      返回 JSON 包含：
+      - \`workflow.next\`：下一个应该创建的 artifact ID，全部完成时为 \`null\`
+      - \`workflow.ready\`：当前可以创建的 artifact 列表
+      - \`workflow.blocked\`：被阻塞的 artifact 列表
+      - \`artifacts\`：每个 artifact 的状态详情（\`id\`、\`status\`、\`path\`）
+
+      如果 \`workflow.next\` 为 \`null\` → 全部完成，跳到第 4 步。
+
+   b. **获取创建指令**
+      \`\`\`bash
+      marchen instructions <name> <workflow.next> --json
+      \`\`\`
+      返回 JSON 包含：
+      - \`template\`：artifact 的 markdown 骨架结构，用它作为输出文件的框架
+      - \`instruction\`：如何填充该 artifact 的指导文本
+      - \`outputPath\`：写入路径（相对于变更目录）
+      - \`context\`：上下文 artifact 的信息数组，每项包含 \`id\`、\`status\`、\`content\`（已填充的内容直接在这里，不需要额外读文件）
+      - \`unlocks\`：完成此 artifact 后解锁的 artifact 列表
+
+   c. **创建 artifact**
+
+      根据 artifact 类型处理：
+
+      **普通 artifact（proposal / design / tasks）：**
+      - 读取 \`context\` 中 \`status\` 为 \`filled\` 的 \`content\` 作为上下文
+      - 按 \`instruction\` 指引 + \`template\` 结构生成内容
+      - 写入 \`marchen/changes/<name>/<outputPath>\`
+      - 写入后验证文件存在
+
+      **specs（目录型 artifact，outputPath 为 \`specs/\`）：**
+      - 读取 proposal 内容（在 \`context\` 中，\`id\` 为 \`proposal\` 的 \`content\`）
+      - 从 proposal 的"能力"章节提取能力列表（kebab-case 名称）
+      - 为每个能力：
+        - 创建目录 \`marchen/changes/<name>/specs/<capability>/\`
+        - 按 \`template\` 结构 + \`instruction\` 指引生成 spec 内容
+        - 写入 \`specs/<capability>/spec.md\`
+      - 写入后验证每个 spec 文件存在
+
+      **如果 proposal 的上下文不够清晰**（用户描述太模糊）：
+      - 用 **AskUserQuestion** 澄清关键信息
+      - 然后继续创建
+
+   d. 显示进度："已创建 \`<artifact-id>\`"，标记任务完成，回到步骤 a。
+
+4. **显示最终状态**
+
+   \`\`\`bash
+   marchen status <name>
+   \`\`\`
+
+**输出**
+
+完成后显示：
+- 变更名称和目录位置
+- 已创建的 artifact 列表及简要说明
+- 用纯文字（不调用 AskUserQuestion，不自动执行）提示下一步两个并列选项，由用户自行决定：
+
+  \`\`\`
+  下一步：
+    /marchen:apply <name>           直接开始实现
+    /marchen:propose-preview <name> 先看一眼浓缩摘要再决定
+  \`\`\`
+
+**护栏**
+
+- 按依赖顺序创建，不跳过 artifact
+- 每次循环创建一个 artifact（specs 算一个，但包含多个文件）
+- 写入后验证文件存在再继续下一个
+- 如果上下文关键信息不清楚，询问用户；但小疑问优先做合理判断，保持节奏
+- 已存在同名变更时必须询问用户，不要覆盖
+- \`instruction\` 是给你的指引，不要把它原样复制到 artifact 文件中
+- 使用 AskUserQuestion 时，选项不超过 4 个；需要更多选项时合并或分步询问
+`},review:{dirName:`marchen-review`,content:`---
+name: marchen-review
+description: 对照变更意图检查代码实现的完整性和一致性，支持基于 chrome-devtools MCP 的 UI 场景验证。
+---
+
+对照变更的 artifact 检查代码改动，必要时驱动浏览器验证 UI 行为，报告遗漏、偏差和阻塞。
+
+---
+
+**输入**：用户的请求应包含变更名称，或可从上下文推断。
+
+**流程**
+
+1. **选择变更**
+
+   有名称就用，没有则：
+   - 从对话上下文推断
+   - 只有一个 open 变更时自动选择
+   - 多个变更时 \`marchen list --json\` + **AskUserQuestion** 让用户选
+
+   显示："Review 变更: \`<name>\`"
+
+2. **嗅探 diff 中的 UI 改动**
+
+   执行 \`git diff --name-only HEAD\`，判断改动是否涉及前端 UI（组件、样式、模板、静态资源等）。命中则记下命中文件，用于下一步的提示。
+
+3. **AskUserQuestion 选择 review 模式**
+
+   用 **AskUserQuestion** 让用户三选一：
+
+   - **代码 review**（默认）：对照 artifact 检查 git diff，不跑代码
+   - **UI 验证**：用 chrome-devtools MCP 实际打开页面验证 specs 中的场景
+   - **两者都做**：先代码、再 UI
+
+   若上一步命中 UI 文件，在问题描述里附一句："检测到 diff 涉及 UI 文件（<列出命中文件>），建议选 UI 验证或两者都做。"
+   未命中时不附加提示，默认推荐"代码 review"。
+
+   保存用户选择为 \`<mode>\`。
+
+4. **获取意图与改动（公共前置）**
+
+   - 执行 \`marchen instructions <name> apply --json\`，从返回 JSON 的 \`context\` 数组里读取 \`status\` 为 "filled" 的 artifact（proposal/specs/design/tasks）作为变更意图
+   - 执行 \`git diff HEAD\`；为空则 \`git diff HEAD~1\`；仍为空则报告 "未检测到代码改动" 并结束
+
+   diff 大到可能挤占 context 时，先 \`git diff --stat HEAD\` 看摘要，再按需读单个文件 diff。
+
+5. **代码 review**（mode 为 "代码 review" 或 "两者都做" 时执行）
+
+   逐条对照变更意图和代码改动，输出报告：
+
+   **任务完成度** — tasks 中每个任务是否有对应改动：
+   - ✅ 任务: <描述> — 已实现
+   - ❌ 任务: <描述> — 未找到对应改动
+
+   **一致性检查** — 实现是否符合 design 决策：
+   - ✅ <决策> — 已遵守
+   - ⚠️ <决策> — 实现有偏差：<说明>
+
+   **需求覆盖** — specs 中需求是否被覆盖：
+   - ✅ <需求> — 已覆盖
+   - ❌ <需求> — 未覆盖
+
+   **发现的问题（如有）**
+   - <文件:行号> <问题描述>
+
+   全部通过：输出 "✅ 代码 review 通过。"
+
+   遇到无法判断的情况（tasks 描述与 diff 对不上但可能是改名了、spec 表述含糊等），直接用 **AskUserQuestion** 就地问用户，不要积攒到最后。
+
+6. **UI 验证**（mode 为 "UI 验证" 或 "两者都做" 时执行）
+
+   ### a. 检测 chrome-devtools MCP 可用性
+
+   尝试调用 chrome-devtools MCP 的只读探测工具（例如列出已打开的页面）。工具不存在或调用失败 → 在报告里写：
+
+   > ⏭ chrome-devtools MCP 不可用，跳过 UI 验证。
+   > 安装方法：\`npx chrome-devtools-mcp@latest\`，并参考所用 AI 工具的 MCP 配置文档将其注册。
+
+   然后跳过本节剩余步骤。
+
+   ### b. 提取待验证场景
+
+   优先从变更的 specs 文件中提取所有 \`#### 场景:\` 块（按 spec 文件分组）。
+   若 specs 不存在或不含场景 → 退化到从 tasks/proposal 推断 UI 相关验证点，并在报告中标注 "基于 tasks 推断，覆盖度可能不完整"。
+   两者都没有可提取场景 → 报告 "未找到可验证的 UI 场景" 并跳过本节。
+
+   ### c. 推断 dev server URL
+
+   从项目文件（脚本、框架配置、环境变量、README 等）推断 dev server 地址和启动命令，不要硬猜端口。
+
+   推出候选 URL 后用 chrome-devtools MCP 的导航工具打开，再用快照工具确认页面像被测应用（合理 title、含框架 root 节点或变更描述涉及的标志性内容）。看着不像被测应用 → 当作未能推断。
+
+   推不出 URL → 全部场景 ⏭ "URL unknown"，在报告里说明推断依据，提示用户确认地址后重新运行 review，跳过本节执行步骤。
+
+   ### d. 推断到 URL 但 dev server 未启动 → 询问是否帮忙起
+
+   推出来 URL 但导航失败（连接拒绝）→ 主会话 **AskUserQuestion**，附上推断依据和启动命令：
+
+   - **帮我起 dev server 然后继续**
+   - **我手动起，起完告诉你**
+   - **跳过 UI 验证**
+
+   选"帮我起"：
+   1. 用 Bash 的 \`run_in_background\` 执行推断到的启动命令（如 \`pnpm dev\`、\`npm run dev\`）
+   2. 轮询端口直到可访问；出现明显异常（进程退出 / 长时间无任何输出 / 报错日志）才判定启动失败，让用户手动检查
+   3. 启动成功后继续执行后续步骤，并在 review 结束时显式告知用户后台进程 PID 和端口，提示 "用完请自行 kill <PID>"——MUST NOT 自动 kill
+
+   选"我手动起"：等用户告知启动完成后继续；用户可以新会话执行 \`/marchen:review\` 重跑。
+
+   选"跳过 UI"：所有场景 ⏭ "dev server 未启动"，跳过后续步骤。
+
+   ### e. 乐观执行场景
+
+   对每个待验证场景：
+
+   1. 用 chrome-devtools MCP 的导航工具打开对应路径
+   2. 用快照工具观察页面状态
+   3. 把场景的 GIVEN/WHEN/THEN 翻译成具体交互（点击、填写、读取文本）并执行
+   4. 比对页面状态与场景预期
+
+   遇到阻塞（登录墙、权限不足、缺数据、表单需要真实输入等）：**主会话可以就地 AskUserQuestion**——例如"需要登录账号才能继续，提供测试账号？/ 跳过这个场景 / 暂停 review"，而不必积攒到最后。
+
+   仍无法继续的场景 → 记录 ⏭ + 阻塞原因，跳到下一个。
+   场景翻译不出具体操作（例如纯后端行为描述）→ ⏭ "不适合 UI 验证"。
+
+   ### f. UI 报告格式
+
+   \`\`\`
+   ## UI 验证（chrome-devtools MCP）
+
+   测试目标：<URL 或 "未确定">
+
+   ✅ <场景标题> — 通过
+        说明：<可选简述>
+   ❌ <场景标题> — 失败
+        证据：<console error 摘要 / 页面文案 / 关键截图路径>
+   ⏭ <场景标题> — 跳过：<阻塞原因>
+   \`\`\`
+
+7. **展示报告并按结果分支**
+
+   - **全部通过且无 ⏭**：提示 "可以用 \`marchen archive <name>\` 归档。"
+   - **有 ❌ 失败**：提示用户修复后可以再次 review。
+   - **有 ⏭ 跳过**：用 **AskUserQuestion** 让用户选择：
+     - **补信息后继续**：收集所需信息（账号、数据等），就地再跑被跳过的场景
+     - **跳过这些场景，继续归档**：保留报告，提示 \`marchen archive <name>\`
+     - **暂停去修复**：什么都不做
+
+   如本次 review 启动了后台 dev server，再次提醒用户进程信息（PID/端口）。
+
+**护栏**
+
+- 不要修改任何代码，只报告（review 不是 apply）
+- UI 验证阻塞即停，不要硬闯（不登录、不猜数据、不绕权限）；要继续就向用户索取信息
+- 起 dev server 必须先获得用户授权（AskUserQuestion）；起完不自动 kill，告知 PID 让用户自行管理
+- 用户提供的凭据/账号等敏感数据：不写入任何 artifact，不在报告里复述明文，截图前对密码/token/邮箱等敏感字段脱敏或回避
+- 大 diff 先看 \`git diff --stat\`，按需读单个文件，避免灌爆 context
+- 使用 AskUserQuestion 时，选项不超过 4 个
+`}};async function E(e){try{await p.mkdir(e,{recursive:!0})}catch(e){if(e.code!==`EEXIST`)throw e}}async function D(e){try{return await p.access(e),!0}catch{return!1}}async function O(e,t){try{await p.rename(e,t)}catch(t){throw t.code===`ENOENT`?new y(`目录不存在`,e):t}}async function k(e){try{return await p.readdir(e)}catch(t){throw t.code===`ENOENT`?new y(`目录不存在`,e):t}}async function A(e){try{return await p.readFile(e,`utf-8`)}catch(t){throw t.code===`ENOENT`?new y(`文件不存在`,e):t}}async function j(e,t){await E(u(e)),await p.writeFile(e,t,`utf-8`)}async function M(e,t){await E(u(e)),await p.appendFile(e,t,`utf-8`)}function N(e=process.cwd()){return f(e)}function P(e=process.cwd()){return f(e,t)}function F(e=process.cwd()){return f(P(e),n)}function I(e=process.cwd()){return f(P(e),i)}async function L(e){let t=await A(e);try{return m.load(t)}catch(t){throw new y(`YAML 解析失败`,e,t instanceof Error?t:void 0)}}async function R(e,t){await j(e,m.dump(t,{indent:2}))}const ee=/^[a-z0-9]+(?:-[a-z0-9]+)*$/;var te=class e{constructor(e){this.workspace=e}static isValidName(e){return ee.test(e)}async create(t,n){if(await this.ensureInitialized(),!e.isValidName(t))throw new _(`变更名称 "${t}" 不合法，请使用 kebab-case 格式（如 add-dark-mode）`);let r=d(this.workspace.changeDir,t);if(await D(r))throw new _(`变更 "${t}" 已存在`);let i=n??`full`,o=w(i);await E(r);for(let e of o.artifacts)e.generates.endsWith(`/`)&&await E(d(r,e.generates));let s={name:t,schema:i,createdAt:new Date().toISOString(),status:`open`};await R(d(r,a),s)}async archive(e,t){await this.ensureInitialized();let n=d(this.workspace.changeDir,e);if(!await D(n))throw new _(`变更 "${e}" 不存在`);let r=d(n,a),i=await L(r),o=new Date().toISOString(),s=o.slice(0,10),c=d(this.workspace.archiveDir,`${s}-${e}`);if(await D(c))throw new _(`归档目标 "${s}-${e}" 已存在`);return await R(r,{...i,status:`archived`,archivedAt:o}),await O(n,c),await this.appendChangelog(e,s,t?.summary),await this.updateSearchIndex(),{name:e,schema:i.schema,archivedTo:c,archivedAt:o}}async appendChangelog(e,t,n){let r=this.workspace.changelogPath;await D(r)||await j(r,`# 变更日志
+`);let i=`[${e}](./archive/${t}-${e}/)`,a=n?.trim().replace(/[\r\n]+/g,` `);await M(r,`${a?`- ${t}: ${i} — ${a}`:`- ${t}: ${i}`}\n`)}async updateSearchIndex(){try{await Promise.race([this.doUpdateSearchIndex(),new Promise(e=>setTimeout(e,3e4))])}catch{}}async doUpdateSearchIndex(){let{SearchManager:e}=await import(`./search-manager-zPFpsFnI.mjs`).then(e=>e.n),t=new e(this.workspace);await t.isAvailable()&&(await t.indexChange(),await t.close())}async list(){await this.ensureInitialized();let e=await k(this.workspace.changeDir),t=[];for(let n of e){let e=d(this.workspace.changeDir,n,a);if(await D(e))try{let n=await L(e);t.push(n)}catch{continue}}return t.sort((e,t)=>new Date(t.createdAt).getTime()-new Date(e.createdAt).getTime()),t}async status(e){await this.ensureInitialized();let t=d(this.workspace.changeDir,e);if(!await D(t))throw new _(`变更 "${e}" 不存在`);let n=await L(d(t,a)),r=w(n.schema),i=[];for(let e of r.artifacts){let n=d(t,e.generates);if(e.id===`specs`){let t=await this.detectSpecsStatus(n);i.push({id:e.id,path:e.generates,...t})}else{let t=await this.detectContentStatus(n);i.push({id:e.id,status:t,path:e.generates})}}let o=new Map(i.map(e=>[e.id,e.status])),s=this.computeWorkflow(r,o),c=i.find(e=>e.id===`tasks`),l=null;if(c&&c.status===`filled`){let e=await A(d(t,`tasks.md`)),n=this.parseTaskItems(e);l={total:n.length,completed:n.filter(e=>e.completed).length,items:n}}return{name:e,schema:n.schema,artifacts:i,workflow:s,tasks:l}}async getInstructions(e,t){await this.ensureInitialized();let n=d(this.workspace.changeDir,e);if(!await D(n))throw new _(`变更 "${e}" 不存在`);let r=await L(d(n,a)),i=w(r.schema),o=i.artifacts.find(e=>e.id===t);if(!o)throw new _(`Artifact "${t}" 不存在，可用的 artifact: ${i.artifacts.map(e=>e.id).join(`, `)}`);let s=o.template??``,c=o.instruction,l=[];for(let e of o.requires){let t=i.artifacts.find(t=>t.id===e);if(!t)continue;let r=d(n,t.generates);if(e===`specs`){let n=await this.detectSpecsStatus(r),i=n.status===`filled`?await this.readSpecsContent(r):null;l.push({id:e,status:n.status,path:t.generates,content:i})}else{let n=await this.detectContentStatus(r),i=n===`filled`?await A(r):null;l.push({id:e,status:n,path:t.generates,content:i})}}let u=i.artifacts.filter(e=>e.requires.includes(t)).map(e=>e.id);return{changeName:e,artifactId:t,schemaName:r.schema,changeDir:n,outputPath:o.generates,template:s,instruction:c,context:l,unlocks:u,state:null,progress:null}}async detectContentStatus(e){return await D(e)?(await A(e)).replace(/<!--[\s\S]*?-->/g,``).split(`
+`).filter(e=>e.trim()!==``).filter(e=>!/^#{1,6}\s/.test(e.trim())).join(`
+`).trim().length>20?`filled`:`empty`:`missing`}async detectSpecsStatus(e){if(!await D(e))return{status:`missing`,capabilities:[]};let t=await k(e);if(t.length===0)return{status:`no-content`,capabilities:[]};let n=!0;for(let r of t){let t=d(e,r,`spec.md`);if(!await D(t)){n=!1;continue}await this.detectContentStatus(t)!==`filled`&&(n=!1)}return{status:n?`filled`:`no-content`,capabilities:t}}async readSpecsContent(e){let t=await k(e),n=[];for(let r of t){let t=d(e,r,`spec.md`);if(await D(t)){let e=await A(t);n.push(`--- specs/${r}/spec.md ---\n${e}`)}}return n.join(`
+
+`)}computeWorkflow(e,t){let n=e=>t.get(e)===`filled`,r=[],i=[];for(let t of e.artifacts)n(t.id)||(t.requires.every(n)?r.push(t.id):i.push(t.id));return{next:r[0]??null,ready:r,blocked:i}}parseTaskItems(e){return[...e.matchAll(/^- \[([ x])\] (.+)$/gm)].map(e=>({description:e[2],completed:e[1]===`x`}))}parseTaskProgress(e){let t=this.parseTaskItems(e),n=t.filter(e=>e.completed).length;return{total:t.length,completed:n,remaining:t.length-n}}async getApplyInstructions(e){await this.ensureInitialized();let t=d(this.workspace.changeDir,e);if(!await D(t))throw new _(`变更 "${e}" 不存在`);let n=await L(d(t,a)),r=w(n.schema),i=[];for(let e of r.artifacts){let n=d(t,e.generates);if(e.id===`specs`){let t=await this.detectSpecsStatus(n),r=t.status===`filled`?await this.readSpecsContent(n):null;i.push({id:e.id,status:t.status,path:e.generates,content:r})}else{let t=await this.detectContentStatus(n),r=t===`filled`?await A(n):null;i.push({id:e.id,status:t,path:e.generates,content:r})}}let o=i.find(e=>e.id===`tasks`),s,c;return!o||!o.content||o.status!==`filled`?(s=`blocked`,c={total:0,completed:0,remaining:0}):(c=this.parseTaskProgress(o.content),s=c.remaining===0?`all_done`:`ready`),{changeName:e,artifactId:`apply`,schemaName:n.schema,changeDir:t,outputPath:null,template:null,instruction:`按 tasks.md 逐个实现任务，完成后勾选 checkbox。
+- 每完成一个任务立即将 - [ ] 改为 - [x]
+- 改动最小化，只做任务要求的事
+- 不确定就暂停问，不要猜
+- 如果发现设计问题，暂停并建议更新 artifact`,context:i,unlocks:null,state:s,progress:c}}async ensureInitialized(){if(!await this.workspace.isInitialized())throw new v(`Marchen 尚未初始化`,`运行 marchen init 初始化`)}},z=class{root;specDir;changeDir;archiveDir;changelogPath;searchDbPath;packageBoundaries=[{name:`@marchen/shared`,dependsOn:[]},{name:`@marchen/config`,dependsOn:[`@marchen/shared`]},{name:`@marchen/fs`,dependsOn:[`@marchen/shared`]},{name:`@marchen/core`,dependsOn:[`@marchen/config`,`@marchen/fs`,`@marchen/shared`]}];constructor(e){this.root=N(e),this.specDir=P(this.root),this.changeDir=F(this.root),this.archiveDir=I(this.root),this.changelogPath=d(this.specDir,`changelog.md`),this.searchDbPath=d(this.specDir,`.search`,`index.sqlite`)}async isInitialized(){return await D(this.specDir)}async initialize(t){let n=t?.providers??S,i=n.map(e=>x[e]).filter(e=>e!=null);await E(this.specDir),await E(this.changeDir),await E(this.archiveDir),await E(d(this.specDir,`.search`));let a=d(this.specDir,e),o={schema:`full`,providers:[...n]};t?.version&&(o.version=t.version),o.search={enabled:t?.searchEnabled??!1},o.models={endpoint:r},await R(a,o),await j(d(this.changeDir,`.gitkeep`),``),await j(d(this.archiveDir,`.gitkeep`),``),await D(this.changelogPath)||await j(this.changelogPath,`# 变更日志
+`);for(let e of i)await this.generateSkills(e.skillDir),e.commandDir&&await this.generateCommands(e.commandDir)}async readConfig(){return await L(d(this.specDir,e))}async update(t){let n=d(this.specDir,e),i=await L(n),a=i.version??null;if(a===t.version)return{previousVersion:a,currentVersion:t.version,providersUpdated:[],skillCount:0,commandCount:0};let o=i.providers,s=o&&o.length>0?o:[...S],c=s.map(e=>x[e]).filter(e=>e!=null),l=[],u=0,f=0,p=Object.keys(T).length,m=Object.keys(b).length;for(let e of c)await this.generateSkills(e.skillDir),u+=p,e.commandDir&&(await this.generateCommands(e.commandDir),f+=m),l.push(e.name);i.version=t.version,i.providers||=[...s];let h=i.search;h&&`mode`in h&&(i.search={enabled:h.mode===`semantic`}),i.search||={enabled:!1};let g=i.models;return g?g.endpoint??(i.models={...g,endpoint:r}):i.models={endpoint:r},await R(n,i),{previousVersion:a,currentVersion:t.version,providersUpdated:l,skillCount:u,commandCount:f}}async generateSkills(e){for(let t of Object.values(T)){let n=d(this.root,e,t.dirName);await E(n),await j(d(n,`SKILL.md`),t.content)}}async generateCommands(e){let t=d(this.root,e);await E(t);for(let e of Object.values(b))await j(d(t,e.fileName),e.content)}};function B(){let e=new z;return{workspace:e,changes:new te(e)}}function V(e){e instanceof v?(l.log.error(e.message),e.hint&&l.log.info(e.hint)):e instanceof _?l.log.warn(e.message):e instanceof y?l.log.error(`${e.message}: ${e.path}`):e instanceof g?l.log.error(e.message):l.log.error(`未知错误: ${e}`),process.exit(1)}function H(e){e.command(`archive`).description(`归档一个已完成的变更`).argument(`<name>`,`变更名称`).option(`--json`,`输出 JSON 格式`).option(`--summary <text>`,`变更摘要（写入 changelog）`).action(async(e,t)=>{try{let{changes:n}=B(),r=await n.archive(e,{summary:t.summary});if(t.json){console.log(JSON.stringify(r,null,2));return}l.intro(`Marchen CLI`),l.log.success(`变更 "${e}" 归档成功`),l.outro(`运行 marchen list 查看剩余变更`)}catch(e){V(e)}})}const U={embed:`Embedding`,generate:`Query Expansion`,rerank:`Reranker`};function W(e){let t=U[e.model]??e.model;switch(e.stage){case`checking`:return`检查模型 ${t}...`;case`downloading`:if(e.downloadedBytes&&e.totalBytes){let n=Math.round(e.downloadedBytes/e.totalBytes*100);return`下载模型 ${t}... ${(e.downloadedBytes/1024/1024).toFixed(1)}/${(e.totalBytes/1024/1024).toFixed(0)} MB (${n}%)`}return`下载模型 ${t}...`;case`verifying`:return`校验模型 ${t}...`;case`ready`:return`模型 ${t} 就绪`;default:return`准备模型 ${t}...`}}function G(e){e.command(`init`).description(`初始化 Marchen 目录结构`).option(`--force`,`强制覆盖已存在的目录`).action(async t=>{l.intro(`Marchen CLI`);let{workspace:n}=B();if(await n.isInitialized()&&!t.force){let e=await l.confirm({message:`Marchen 目录已存在，是否覆盖？`});(l.isCancel(e)||!e)&&(l.cancel(`操作已取消`),process.exit(0))}let r=Object.values(x).map(e=>({value:e.id,label:e.name})),i=await l.multiselect({message:`选择要安装的 AI 工具集成`,options:r,initialValues:[`claude-code`],required:!0});l.isCancel(i)&&(l.cancel(`操作已取消`),process.exit(0));let a=e.version(),s=await l.confirm({message:`是否启用搜索？（需下载约 2GB 模型）`,initialValue:!1});l.isCancel(s)&&(l.cancel(`操作已取消`),process.exit(0)),await n.initialize({providers:i,version:a,searchEnabled:s});let c=i.map(e=>x[e]?.name??e).join(`, `);if(l.log.success(`已为 ${c} 生成 skills 文件`),s){let e=new o(n),t=l.spinner();t.start(`下载搜索模型...`),await e.ensureModels({onProgress:e=>{t.message(W(e))}}),t.stop(`Hybrid Search 已启用`)}l.outro(`Marchen 初始化成功！`)})}function K(e){e.command(`instructions`).description(`获取 artifact 的创建指令`).argument(`<name>`,`变更名称`).argument(`<artifact-id>`,`artifact 标识符 (proposal/specs/design/tasks/apply)`).option(`--json`,`输出 JSON 格式（默认行为）`).action(async(e,t)=>{try{let{changes:n}=B(),r=t===`apply`?await n.getApplyInstructions(e):await n.getInstructions(e,t);console.log(JSON.stringify(r,null,2))}catch(e){V(e)}})}function q(e){let t=Math.floor((Date.now()-new Date(e).getTime())/1e3);return t<60?`刚刚`:t<3600?`${Math.floor(t/60)} 分钟前`:t<86400?`${Math.floor(t/3600)} 小时前`:`${Math.floor(t/86400)} 天前`}function J(e){e.command(`list`).description(`列出所有 open 状态的变更`).option(`--json`,`输出 JSON 格式`).action(async e=>{try{let{changes:t}=B(),n=await t.list();if(e.json){console.log(JSON.stringify(n,null,2));return}if(l.intro(`Marchen CLI`),n.length===0){l.log.info(`暂无 open 状态的变更`),l.outro(`运行 marchen new <name> 创建一个变更`);return}let r=Math.max(4,...n.map(e=>e.name.length)),i=Math.max(6,...n.map(e=>e.schema.length)),a=[`${`名称`.padEnd(r-2)}  ${`Schema`.padEnd(i)}  创建时间`,`${`─`.repeat(r)}  ${`─`.repeat(i)}  ${`─`.repeat(8)}`,...n.map(e=>`${e.name.padEnd(r)}  ${e.schema.padEnd(i)}  ${q(e.createdAt)}`)].join(`
+`);l.log.info(`共 ${n.length} 个 open 变更：\n\n${a}`),l.outro(`运行 marchen status <name> 查看变更详情`)}catch(e){V(e)}})}function Y(e){e.command(`new`).description(`创建一个新的变更`).argument(`<name>`,`变更名称（kebab-case，如 add-dark-mode）`).option(`--schema <name>`,`工作流 schema`,`full`).action(async(e,t)=>{if(l.intro(`Marchen CLI`),!C[t.schema]){let e=Object.keys(C).join(`, `);l.log.error(`Schema "${t.schema}" 不存在，可用的 schema: ${e}`),process.exit(1)}let n=l.spinner();n.start(`正在创建变更 "${e}"...`);try{let{changes:r}=B();await r.create(e,t.schema),n.stop(`变更 "${e}" 创建成功（schema: ${t.schema}）`)}catch(e){n.stop(`创建失败`),V(e)}l.outro(`运行 marchen list 查看所有变更`)})}function X(e){e.command(`search <query>`).description(`搜索归档变更历史`).option(`-n, --limit <number>`,`结果数量`,`5`).option(`--min-score <number>`,`最低分数阈值`,`0.3`).option(`--json`,`输出 JSON 格式`).option(`--rebuild`,`重建索引后搜索`).action(async(e,t)=>{let n=new z,r=new o(n),i=t.json?null:l.spinner();try{await r.isAvailable()||(l.log.error(`搜索功能不可用（qmd 加载失败）`),process.exit(1));let a=!1;try{a=(await n.readConfig()).search?.enabled??!1}catch{}a||(l.log.error(`搜索未启用。请在 config.yaml 中设置 search.enabled: true 后运行 marchen update`),process.exit(1)),i?.start(`准备搜索引擎...`),await r.prepare(),i?.stop(`搜索引擎就绪`),t.rebuild&&(i?.start(`正在重建索引...`),await r.index(),i?.stop(`索引重建完成`)),i?.start(`搜索中...`);let o=await r.search(e,{limit:Number(t.limit),minScore:Number(t.minScore)});if(i?.stop(`搜索完成`),t.json){console.log(JSON.stringify(o,null,2)),await r.close();return}if(o.length===0){l.log.info(`未找到匹配结果`),await r.close();return}for(let e of o){let t=Math.round(e.score*100),n=t>=70?h.green(`${t}%`):t>=40?h.yellow(`${t}%`):h.dim(`${t}%`);l.log.info(`${h.bold(e.path)}  ${n}`),e.snippet&&l.log.message(h.dim(e.snippet))}await r.close()}catch(e){i?.stop(`搜索失败`),V(e)}})}const Z={filled:`✅`,empty:`⬜`,missing:`⬜`,"no-content":`⬜`};function ne(e){switch(e){case`filled`:return h.green(e);case`empty`:return h.yellow(e);case`blocked`:return h.red(e);default:return h.dim(e)}}function Q(e,t){let n=t>0?Math.round(e/t*10):0,r=`[${`█`.repeat(n)+`░`.repeat(10-n)}] ${e}/${t} 完成`;return e===t?h.green(r):e>0?h.yellow(r):h.dim(r)}function re(e){e.command(`status`).description(`查看变更的 artifact 状态和工作流建议`).argument(`<name>`,`变更名称`).option(`--json`,`输出 JSON 格式`).action(async(e,t)=>{try{let{changes:n}=B(),r=await n.status(e);if(t.json){console.log(JSON.stringify(r,null,2));return}l.intro(`Marchen CLI`),l.log.info(`${h.bold(r.name)} · ${h.dim(r.schema)}`);let i=r.artifacts.map(e=>{let t=r.workflow.blocked.includes(e.id),n=t?`🔒`:Z[e.status],i=t?`blocked`:e.status,a=`${n} ${e.id.padEnd(12)} ${ne(i)}`;if(e.capabilities&&(a+=` (${e.capabilities.length} capabilities)`),t){let t=ie(e.id).filter(e=>r.artifacts.find(t=>t.id===e)?.status!==`filled`);t.length>0&&(a+=` (等待 ${t.join(`, `)})`)}return a});l.log.info(`Artifacts\n${i.join(`
+`)}`);let a=r.artifacts.filter(e=>e.status===`filled`).length,o=r.artifacts.length,s=`Artifacts: ${Q(a,o)}`;r.tasks&&(s+=`\nTasks:     ${Q(r.tasks.completed,r.tasks.total)}`),l.log.info(s),r.workflow.next?l.outro(`下一步: ${h.cyan(r.workflow.next)}`):l.outro(`所有 artifact 已就绪`)}catch(e){V(e)}})}function ie(e){return{proposal:[],specs:[`proposal`],design:[`proposal`],tasks:[`specs`,`design`]}[e]??[]}function ae(e){e.command(`update`).description(`更新 skill/command 文件到最新版本`).action(async()=>{l.intro(`Marchen CLI`);try{let{workspace:t}=B(),n=e.version();if(!await t.isInitialized())throw new v(`Marchen 尚未初始化`,`请先运行 marchen init`);let r=await t.update({version:n});if(r.providersUpdated.length===0)l.log.info(`已是最新版本 (${r.currentVersion})`);else{let e=r.previousVersion??`unknown`;l.log.info(`版本: ${e} → ${r.currentVersion}`);for(let e of r.providersUpdated)l.log.success(`已更新 ${e} skills`);l.log.success(`config.yaml 版本已更新`)}if((await t.readConfig()).search?.enabled??!1){let e=new o(t),n=!1,r=l.spinner();r.start(`检查搜索模型...`),await e.ensureModels({onProgress:e=>{e.stage===`downloading`&&(n=!0),r.message(W(e))}}),r.stop(n?`Hybrid Search 已启用`:`Hybrid Search 已就绪`)}l.outro(`更新完成！`)}catch(e){V(e)}})}const{version:oe}=s(import.meta.url)(`../package.json`);function $(){let e=new c;return e.name(`marchen`).description(`Workflow harness for AI coding agents`).version(oe,`-v, --version`),H(e),G(e),K(e),J(e),Y(e),X(e),re(e),ae(e),e}$().parse(process.argv);export{$ as buildCliProgram};
+//# sourceMappingURL=index.mjs.map