visual-spec 0.1.11 → 0.1.12

package/README.md

@@ -1,6 +1,6 @@
 This repo provides a requirements analysis and delivery assistant Skill. It offers a `/vspec:*` command-driven workflow that turns raw requirements into reviewable artifacts: specs, data models, runnable prototypes, detailed design, acceptance cases, tests, and integrated implementation inputs.
 
-Version: 0.1.11 (2026-04-12)
+Version: 0.1.12 (2026-04-12)
 
 ## Installation
 

package/docs/en-US/workflows.md

@@ -50,7 +50,7 @@
 
 - Use when you need a deliverable Word doc for review/circulation/archiving based on current artifacts
 - Input: existing `/specs/**` artifacts (original/functions/details/models/flows, when available)
-- Output: `/docs/current/requirement_detail.doc` (Word-openable `.doc`, single-file HTML)
+- Output: `/docs/current/requirement_detail.docx` (Word-openable `.docx`, single-file HTML)
 - Note: this Word file is a read-only summary; make changes in the corresponding markdown files and rerun `/vspec:doc` to regenerate
 
 ### 7. Solution Verification (`/vspec:verify`)

package/docs/ja-JP/workflows.md

@@ -46,7 +46,7 @@
 
 - 既存成果物を集約してレビュー/回覧/保管用の Word 文書を生成する
 - 入力：既存の `/specs/**`（original/functions/details/models/flows など。存在するものを読む）
-- 出力：`/docs/current/requirement_detail.doc`（Word で開ける `.doc`、単一 HTML）
+- 出力：`/docs/current/requirement_detail.docx`（Word で開ける `.docx`、単一 HTML）
 - 注意：この Word は要約用（直接編集しない）。修正は対応する markdown を更新し、`/vspec:doc` を再実行して再生成する
 
 ### 7. 検証（`/vspec:verify`）

package/docs/zh-CN/complicated.md

@@ -57,4 +57,4 @@
 2. 如材料较多：先整理 `/docs/current/file_list.md`（按“权威性/优先级”排序）
 3. 运行 `/vspec:new`（生成 `/specs/background/original.md` 与问题清单）
 4. 需要继承 legacy/当前材料并生成新 specs：运行 `/vspec:upgrade`
-5. 需要汇总成 Word：运行 `/vspec:doc` 输出到 `/docs/current/requirement_detail.doc`
+5. 需要汇总成 Word：运行 `/vspec:doc` 输出到 `/docs/current/requirement_detail.docx`

package/docs/zh-CN/workflows.md

@@ -50,7 +50,7 @@
 
 - 适用场景：把当前已有的规格产物汇总成可交付的 Word 文档，用于评审/流转/归档
 - 输入：现有 `/specs/**` 产物（original/functions/details/models/flows 等，存在则读取）
-- 输出：`/docs/current/requirement_detail.doc`（Word 可打开的 `.doc`，HTML 单文件）
+- 输出：`/docs/current/requirement_detail.docx`（Word 可打开的 `.docx`，HTML 单文件）
 - 提示：该 Word 只是汇总，不建议直接修改；修改应回到对应的 markdown 文件，修改后重新 `/vspec:doc` 生成新版本
 
 ### 7. 方案验证（`/vspec:verify`）

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "visual-spec",
-  "version": "0.1.11",
+  "version": "0.1.12",
   "description": "AI skill: visual-spec (/vspec:* commands) for requirement analysis, prototyping, detailing, testing, and planning.",
   "license": "MIT",
   "type": "commonjs",

package/skills/visual-spec/SKILL-ja-JP.md

@@ -47,8 +47,9 @@ Flow:
 2. 入力を raw requirement として扱う
 3. `prompts/vspec_new/background.md` を読み込み、要件分析と背景補完を実行
 4. `/specs/background/original.md` に書き込み
-5. Open Questions/要確認事項の回答を促す（自己回答でも、AI の回答案→ユーザー確認でも可）
-6. 以降、`prompts/vspec_new/*` に従い `/specs/` 配下の成果物を生成
+5. `/specs/background/question_and_answer.html` を生成（`prompts/vspec_new/question_and_answer.html` をそのままコピー）。このページで `original.md` / `questions.md` の質問に回答し、md に書き戻せるようにする。
+6. Open Questions/要確認事項の回答を促す（`/specs/background/question_and_answer.html` を開き、`/specs/background/original.md` を選択して回答・保存）。この時点で必ず停止して待機し、回答が揃うまで次のステップへ進まない（「続けて/继续/continue」等で回答完了を明示してもらう）。
+6. ユーザーの回答後（または「続けて/继续/continue」等で回答完了を明示した後）、`prompts/vspec_new/*` に従い `/specs/` 配下の成果物を生成
 
 ### `/vspec:refine`
 
@@ -87,7 +88,7 @@ Flow:
 
 ### `/vspec:doc`
 
-要件成果物（`/specs/**`）を集約し、Word で直接開ける単一ファイルの Word 文書（HTML 形式の `.doc`）を `/docs/current/requirement_detail.doc` に生成します。
+要件成果物（`/specs/**`）を集約し、Word で直接開ける単一ファイルの Word 文書（HTML 形式の `.docx`）を `/docs/current/requirement_detail.docx` に生成します。
 
 ### `/vspec:verify`
 

package/skills/visual-spec/SKILL-zh-CN.md

@@ -42,7 +42,8 @@ description: "将原始需求分析为可评审的视觉规格，并生成相关
 3. 加载提示词文件 `prompts/vspec_new/background.md`。
 4. 使用该提示词分析需求并扩展业务背景。
 5. 将原始需求与背景分析写入 `/specs/background/original.md`。
-6. 提示用户回答“待确认问题/Open Questions/要確認事項”章节中的问题（按所选语言对应章节标题）。
+5.5 同时生成交互式问答页面：`/specs/background/question_and_answer.html`（从 `prompts/vspec_new/question_and_answer.html` 复制，单文件 HTML，内联 CSS/JS），用于回答 `original.md` 与 `questions.md` 并回写。
+6. 提示用户回答“待确认问题/Open Questions/要確認事項”章节中的问题（按所选语言对应章节标题），并要求通过 `/specs/background/question_and_answer.html` 完成（在页面中选择 `/specs/background/original.md`，填写并保存回写）。然后必须暂停并等待用户回复“继续/continue/続けて”。不得继续加载后续提示词或生成后续产物（不得越过问答直接进入 stakeholders/roles/terms 等阶段）。用户明确回复后再进入下一步。
 7. 用户回复后，加载 `prompts/vspec_new/stakeholders.md` 分析干系人。
 8. 将干系人结果写入 `/specs/background/stakeholder.md`（markdown 表格）。
 9. 加载 `prompts/vspec_new/roles.md` 分析系统用户角色（直接用户）及其工作任务。
@@ -178,7 +179,7 @@ description: "将原始需求分析为可评审的视觉规格，并生成相关
    - 外部依赖：`/specs/background/dependencies.md`
    - 数据模型：`/specs/models/*.md`
 3. 加载 `prompts/vspec_doc/doc.md`，生成 Word 可打开的单文件 HTML 文档。
-4. 将输出写入：`/docs/current/requirement_detail.doc`。
+4. 将输出写入：`/docs/current/requirement_detail.docx`。
 
 ### `/vspec:verify`
 
@@ -324,7 +325,7 @@ Note：Pro 版支持更广泛的质量检测能力（例如更完整的原型/
 - `prompts/vspec_new/questions.md`：生成 `/specs/background/questions.md` 的提示词。
 - `prompts/vspec_refine/refine.md`：`/vspec:refine` 使用的提示词。
 - `prompts/vspec_refine/refine_q.md`：`/vspec:refine-q` 使用的提示词。
-- `prompts/vspec_doc/doc.md`：`/vspec:doc` 使用的提示词，用于生成 Word 可打开的 `.doc`（HTML）需求详细文档到 `/docs/current/`。
+- `prompts/vspec_doc/doc.md`：`/vspec:doc` 使用的提示词，用于生成 Word 可打开的 `.docx`（HTML）需求详细文档到 `/docs/current/`。
 - `prompts/vspec_verify/model.md`：生成 `/specs/models/*.md` 的提示词。
 - `prompts/vspec_verify/prototype.md`：生成按选栈的可运行原型工程（`/specs/prototypes/`）的提示词（必须遵循 `scheme.yaml`）。
 - `prompts/vspec_verify/validation.md`：生成 `scenario.html` 场景评审页的提示词。

package/skills/visual-spec/SKILL.md

@@ -49,8 +49,9 @@ Flow:
 3. Load the prompt file at `prompts/vspec_new/background.md`.
 4. Use that prompt to analyze the requirement and expand the business context.
 5. Write the raw requirement and background analysis output to `/specs/background/original.md`.
-6. Ask the user to answer the questions from the Open Questions section (use the section title in the selected language).
-7. After the user replies, load `prompts/vspec_new/stakeholders.md` to analyze stakeholders.
+5.5 Create `/specs/background/question_and_answer.html` by copying `prompts/vspec_new/question_and_answer.html` (single-file HTML with inline CSS/JS) so the user can answer questions and write back to markdown.
+6. Ask the user to answer the questions from the Open Questions section (use the section title in the selected language). The user should answer via `/specs/background/question_and_answer.html` (select `/specs/background/original.md` in the page and save back), then reply with a continuation signal (e.g. `继续` / `continue`). Then STOP. Do not load any subsequent prompts or generate any further artifacts before that.
+7. After the user replies (answers or confirmed), load `prompts/vspec_new/stakeholders.md` to analyze stakeholders.
 8. Write the stakeholder result to `/specs/background/stakeholder.md` (markdown table).
 9. Load `prompts/vspec_new/roles.md` to analyze system user roles (direct users) and their work tasks.
 10. Write the roles result to `/specs/background/roles.md`.
@@ -185,7 +186,7 @@ Flow:
    - Dependencies: `/specs/background/dependencies.md`
    - Models: `/specs/models/*.md`
 3. Load `prompts/vspec_doc/doc.md` and generate the doc as a Word-openable single HTML file.
-4. Write the output file to: `/docs/current/requirement_detail.doc`.
+4. Write the output file to: `/docs/current/requirement_detail.docx`.
 
 ### `/vspec:verify`
 
@@ -333,7 +334,7 @@ Flow:
 - `prompts/vspec_mrd/mrd.md`: the prompt used by `/vspec:mrd` to generate market/user/competitor/product docs under `/docs/market/`.
 - `prompts/vspec_refine/refine.md`: the prompt used by `/vspec:refine` to refine the requirement based on `refine.md`.
 - `prompts/vspec_refine/refine_q.md`: the prompt used by `/vspec:refine-q` to refine the requirement based on answered questions.
-- `prompts/vspec_doc/doc.md`: the prompt used by `/vspec:doc` to generate a Word-openable `.doc` (HTML) requirement detail document under `/docs/current/`.
+- `prompts/vspec_doc/doc.md`: the prompt used by `/vspec:doc` to generate a Word-openable `.docx` (HTML) requirement detail document under `/docs/current/`.
 - `prompts/vspec_verify/model.md`: the prompt used by `/vspec:verify` to generate `/specs/models/*.md`.
 - `prompts/vspec_verify/prototype.md`: the prompt used by `/vspec:verify` to generate the stack-selected runnable prototype under `/specs/prototypes/` (must follow `scheme.yaml`).
 - `prompts/vspec_verify/validation.md`: the prompt used by `/vspec:verify` to generate the validation web page with a `scenario.html` entry.

package/skills/visual-spec/prompts/vspec_detail/index.html

@@ -319,13 +319,98 @@
         font-size: 13px;
         line-height: 1.5;
       }
+      .tree-sep {
+        height: 1px;
+        background: var(--border);
+        margin: 10px 6px;
+      }
+      .outline-title {
+        padding: 8px 10px 2px;
+        color: var(--muted);
+        font-size: 12px;
+      }
+      .outline {
+        padding: 6px 6px 0;
+      }
+      .outline a {
+        display: block;
+        padding: 6px 10px;
+        border-radius: 10px;
+        color: rgba(230, 238, 252, 0.92);
+        text-decoration: none;
+        border: 1px solid transparent;
+        font-size: 13px;
+      }
+      .outline a:hover {
+        background: rgba(255, 255, 255, 0.04);
+      }
+      .outline a.active {
+        background: rgba(34, 197, 94, 0.12);
+        border-color: rgba(34, 197, 94, 0.28);
+      }
+      .file.missing {
+        opacity: 0.55;
+        cursor: not-allowed;
+      }
+      .md-toolbar {
+        display: flex;
+        flex-wrap: wrap;
+        gap: 8px;
+        align-items: center;
+        justify-content: space-between;
+        padding: 10px 12px;
+        border: 1px solid var(--border);
+        border-radius: 14px;
+        background: rgba(10, 16, 28, 0.82);
+        margin-bottom: 12px;
+      }
+      .md-toolbar .left,
+      .md-toolbar .right {
+        display: flex;
+        flex-wrap: wrap;
+        gap: 8px;
+        align-items: center;
+      }
+      .md-toolbar .hint {
+        margin: 0;
+        color: var(--muted);
+        font-size: 12px;
+      }
+      .md-split {
+        display: grid;
+        grid-template-columns: 1fr 1fr;
+        gap: 12px;
+      }
+      @media (max-width: 980px) {
+        .md-split {
+          grid-template-columns: 1fr;
+        }
+      }
+      .md-text {
+        width: 100%;
+        min-height: calc(100vh - 330px);
+        border-radius: 14px;
+        border: 1px solid var(--border);
+        background: rgba(10, 16, 28, 0.78);
+        color: var(--text);
+        padding: 12px;
+        font-size: 13px;
+        line-height: 1.45;
+        outline: none;
+        font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New",
+          monospace;
+      }
+      .mode-btn.active {
+        background: rgba(59, 130, 246, 0.18);
+        border-color: rgba(59, 130, 246, 0.45);
+      }
     </style>
   </head>
   <body>
     <div class="top-banner">
       <div class="inner">
         <div class="msg">
-          <b>Word export:</b> run <b>/vspec:doc</b> to generate <b>/docs/current/requirement_detail.doc</b>
+          <b>Word export:</b> run <b>/vspec:doc</b> to generate <b>/docs/current/requirement_detail.docx</b>
         </div>
       </div>
     </div>
@@ -344,7 +429,12 @@
               <button id="collapseAll">Collapse</button>
             </div>
           </div>
-          <div class="tree" id="tree"></div>
+          <div class="tree">
+            <div class="outline-title">Outline</div>
+            <div id="outline" class="outline"></div>
+            <div class="tree-sep"></div>
+            <div id="nav"></div>
+          </div>
         </div>
 
         <div class="panel">
@@ -362,7 +452,7 @@
           <div class="content">
             <div class="doc" id="viewer">
               <div class="empty">
-                Select a file from the left tree. Supported:
+                Select a document from the left navigation. Markdown supports editing + live preview.
                 <ul>
                   <li><code>.md</code> rendered as markdown</li>
                   <li><code>.html</code> rendered via iframe</li>
@@ -381,7 +471,8 @@
       const PLANTUML_SERVER = "https://www.plantuml.com/plantuml/svg/";
 
       const dom = {
-        tree: document.getElementById("tree"),
+        nav: document.getElementById("nav"),
+        outline: document.getElementById("outline"),
         search: document.getElementById("search"),
         fileCount: document.getElementById("fileCount"),
         viewer: document.getElementById("viewer"),
@@ -396,6 +487,9 @@
         paths: [],
         activePath: null,
         activeButton: null,
+        handles: new Map(),
+        activeHeadings: [],
+        activeHeadingId: null,
       };
 
       function escapeHtml(str) {
@@ -446,6 +540,45 @@
         return s.length ? s[s.length - 1] : path;
       }
 
+      function firstHeadingTitle(md) {
+        const m = String(md || "").match(/^#{1,6}\s+(.+)\s*$/m);
+        return m ? m[1].trim() : "";
+      }
+
+      function displayTitle(path) {
+        const t = fileType(path);
+        if (t === "Markdown") {
+          const title = firstHeadingTitle(state.files[path] || "");
+          return title || basename(path);
+        }
+        return basename(path);
+      }
+
+      function slugify(text) {
+        return String(text || "")
+          .trim()
+          .toLowerCase()
+          .replace(/[`"'<>]/g, "")
+          .replace(/\s+/g, "-")
+          .replace(/[^a-z0-9\u4e00-\u9fff\u3040-\u30ff_-]/g, "");
+      }
+
+      function extractHeadings(md) {
+        const lines = String(md || "").replace(/\r\n/g, "\n").split("\n");
+        const out = [];
+        let idx = 0;
+        for (const line of lines) {
+          const m = line.match(/^(#{1,6})\s+(.+)\s*$/);
+          if (!m) continue;
+          idx++;
+          const level = m[1].length;
+          const text = m[2].trim();
+          const id = `h-${slugify(text) || "section"}-${idx}`;
+          out.push({ level, text, id });
+        }
+        return out;
+      }
+
       function filterMatch(filterLower, label, path) {
         if (!filterLower) return true;
         return `${label || ""} ${path || ""}`.toLowerCase().includes(filterLower);
@@ -524,13 +657,23 @@
         chapters.push({
           label: "Requirement",
           children: [
-            original ? { type: "file", label: "Original Requirement", path: original } : null,
-            stakeholder ? { type: "file", label: "Stakeholders", path: stakeholder } : null,
-            roles ? { type: "file", label: "Roles", path: roles } : null,
-            terms ? { type: "file", label: "Terms", path: terms } : null,
-            scenarios ? { type: "file", label: "Scenarios", path: scenarios } : null,
-            dependencies ? { type: "file", label: "Dependencies", path: dependencies } : null,
-            questions ? { type: "file", label: "Questions", path: questions } : null,
+            { type: "file", label: "Original Requirement", path: original || "/specs/background/original.md", missing: !original },
+            {
+              type: "file",
+              label: "Stakeholders",
+              path: stakeholder || "/specs/background/stakeholders.md",
+              missing: !stakeholder,
+            },
+            { type: "file", label: "Roles", path: roles || "/specs/background/roles.md", missing: !roles },
+            { type: "file", label: "Terms", path: terms || "/specs/background/terms.md", missing: !terms },
+            { type: "file", label: "Scenarios", path: scenarios || "/specs/background/scenarios.md", missing: !scenarios },
+            {
+              type: "file",
+              label: "Dependencies",
+              path: dependencies || "/specs/background/dependencies.md",
+              missing: !dependencies,
+            },
+            { type: "file", label: "Questions", path: questions || "/specs/background/questions.md", missing: !questions },
           ].filter(Boolean),
         });
 
@@ -553,7 +696,7 @@
 
         chapters.push({
           label: "Functions",
-          children: functions.map((p) => ({ type: "file", label: basename(p), path: p })),
+          children: functions.map((p) => ({ type: "file", label: displayTitle(p), path: p })),
         });
 
         chapters.push({
@@ -563,7 +706,7 @@
 
         chapters.push({
           label: "Models",
-          children: models.map((p) => ({ type: "file", label: basename(p), path: p })),
+          children: models.map((p) => ({ type: "file", label: displayTitle(p), path: p })),
         });
 
         return chapters.filter((c) => (c.children || []).length);
@@ -581,8 +724,14 @@
           if (!filterMatch(filterLower, node.label, node.path)) return;
           const btn = document.createElement("button");
           btn.className = "file";
-          btn.textContent = node.label;
-          btn.addEventListener("click", () => openFile(node.path, btn));
+          const title = exists(node.path) ? displayTitle(node.path) : node.label;
+          btn.textContent = title;
+          if (!exists(node.path) || node.missing) {
+            btn.classList.add("missing");
+            btn.disabled = true;
+          } else {
+            btn.addEventListener("click", () => openFile(node.path, btn));
+          }
           if (state.activePath === node.path) btn.classList.add("active");
           container.appendChild(btn);
           return;
@@ -602,11 +751,40 @@
       }
 
       function renderSidebar() {
-        dom.tree.innerHTML = "";
+        dom.nav.innerHTML = "";
         const filterLower = (dom.search.value || "").trim().toLowerCase();
         const chapters = buildChapters();
         for (const ch of chapters) {
-          renderNavNode({ type: "group", label: ch.label, children: ch.children }, dom.tree, filterLower);
+          renderNavNode({ type: "group", label: ch.label, children: ch.children }, dom.nav, filterLower);
+        }
+      }
+
+      function renderOutline(headings) {
+        dom.outline.innerHTML = "";
+        const hs = (headings || []).filter((h) => h.level >= 1 && h.level <= 4);
+        if (!state.activePath || fileType(state.activePath) !== "Markdown" || !hs.length) {
+          const a = document.createElement("a");
+          a.href = "javascript:void(0)";
+          a.textContent = "—";
+          a.style.cursor = "default";
+          dom.outline.appendChild(a);
+          return;
+        }
+        for (const h of hs) {
+          const a = document.createElement("a");
+          a.href = "javascript:void(0)";
+          a.textContent = h.text;
+          a.style.paddingLeft = `${10 + (h.level - 1) * 12}px`;
+          if (state.activeHeadingId === h.id) a.classList.add("active");
+          a.addEventListener("click", () => {
+            const el = document.getElementById(h.id);
+            if (el) {
+              state.activeHeadingId = h.id;
+              el.scrollIntoView({ block: "start", behavior: "smooth" });
+              renderOutline(state.activeHeadings);
+            }
+          });
+          dom.outline.appendChild(a);
         }
       }
 
@@ -762,9 +940,15 @@
       async function renderMarkdown(md) {
         const root = document.createElement("div");
         const blocks = parseMarkdown(md);
+        let hIndex = 0;
+        const headings = [];
         for (const b of blocks) {
           if (b.type === "heading") {
+            hIndex++;
+            const id = `h-${slugify(b.text) || "section"}-${hIndex}`;
+            headings.push({ level: b.level, text: b.text, id });
             const h = document.createElement("h" + b.level);
+            h.id = id;
             h.innerHTML = renderInline(b.text);
             root.appendChild(h);
             continue;
@@ -849,10 +1033,46 @@
             continue;
           }
         }
+        state.activeHeadings = headings;
+        state.activeHeadingId = null;
         return root;
       }
 
+      async function linkLocalFileForWriteBack(path) {
+        if (!("showOpenFilePicker" in window)) {
+          alert("Browser does not support File System Access API. Use Download instead.");
+          return;
+        }
+        const [handle] = await window.showOpenFilePicker({
+          multiple: false,
+          types: [{ description: "Files", accept: { "text/plain": [".md", ".puml", ".txt", ".html"] } }],
+        });
+        state.handles.set(path, handle);
+      }
+
+      async function saveToLinkedHandle(path, text) {
+        const handle = state.handles.get(path);
+        if (!handle) return false;
+        const writable = await handle.createWritable();
+        await writable.write(text);
+        await writable.close();
+        return true;
+      }
+
+      function downloadText(filename, text, type) {
+        const blob = new Blob([text], { type: type || "text/plain;charset=utf-8" });
+        const url = URL.createObjectURL(blob);
+        const a = document.createElement("a");
+        a.href = url;
+        a.download = filename;
+        document.body.appendChild(a);
+        a.click();
+        a.remove();
+        URL.revokeObjectURL(url);
+      }
+
       async function openFile(path, btn) {
+        if (!exists(path)) return;
         const content = state.files[path];
         setActive(path, btn);
         dom.viewer.innerHTML = "";
@@ -881,8 +1101,121 @@
           }
           return;
         }
+        if (t === "Markdown") {
+          const toolbar = document.createElement("div");
+          toolbar.className = "md-toolbar";
+          const left = document.createElement("div");
+          left.className = "left";
+          const right = document.createElement("div");
+          right.className = "right";
+
+          const modeSplit = document.createElement("button");
+          modeSplit.className = "mode-btn active";
+          modeSplit.textContent = "Split";
+          const modeEdit = document.createElement("button");
+          modeEdit.className = "mode-btn";
+          modeEdit.textContent = "Edit";
+          const modePreview = document.createElement("button");
+          modePreview.className = "mode-btn";
+          modePreview.textContent = "Preview";
+
+          const linkBtn = document.createElement("button");
+          linkBtn.textContent = "Link File";
+          linkBtn.addEventListener("click", async () => {
+            try {
+              await linkLocalFileForWriteBack(path);
+              alert("Linked. You can Save back now.");
+            } catch (e) {}
+          });
+
+          const saveBtn = document.createElement("button");
+          saveBtn.className = "primary";
+          saveBtn.textContent = "Save";
+
+          const dlBtn = document.createElement("button");
+          dlBtn.textContent = "Download";
+
+          const hint = document.createElement("div");
+          hint.className = "hint";
+          hint.textContent = "Edit markdown and preview on the right. Save requires linking a local file.";
+
+          left.appendChild(modeSplit);
+          left.appendChild(modeEdit);
+          left.appendChild(modePreview);
+          left.appendChild(hint);
+          right.appendChild(linkBtn);
+          right.appendChild(saveBtn);
+          right.appendChild(dlBtn);
+          toolbar.appendChild(left);
+          toolbar.appendChild(right);
+
+          const split = document.createElement("div");
+          split.className = "md-split";
+          const ta = document.createElement("textarea");
+          ta.className = "md-text";
+          ta.value = content || "";
+          const previewWrap = document.createElement("div");
+          previewWrap.className = "doc";
+          split.appendChild(ta);
+          split.appendChild(previewWrap);
+
+          let timer = null;
+          async function refresh() {
+            previewWrap.innerHTML = "";
+            const rendered = await renderMarkdown(ta.value || "");
+            previewWrap.appendChild(rendered);
+            renderOutline(state.activeHeadings);
+          }
+          await refresh();
+          ta.addEventListener("input", () => {
+            if (timer) clearTimeout(timer);
+            timer = setTimeout(() => refresh(), 180);
+          });
+
+          function setMode(mode) {
+            modeSplit.classList.remove("active");
+            modeEdit.classList.remove("active");
+            modePreview.classList.remove("active");
+            if (mode === "split") modeSplit.classList.add("active");
+            if (mode === "edit") modeEdit.classList.add("active");
+            if (mode === "preview") modePreview.classList.add("active");
+            if (mode === "split") {
+              ta.style.display = "";
+              previewWrap.style.display = "";
+            } else if (mode === "edit") {
+              ta.style.display = "";
+              previewWrap.style.display = "none";
+            } else {
+              ta.style.display = "none";
+              previewWrap.style.display = "";
+            }
+          }
+          modeSplit.addEventListener("click", () => setMode("split"));
+          modeEdit.addEventListener("click", () => setMode("edit"));
+          modePreview.addEventListener("click", () => setMode("preview"));
+
+          saveBtn.addEventListener("click", async () => {
+            try {
+              const ok = await saveToLinkedHandle(path, ta.value || "");
+              if (!ok) alert("No linked file. Click Link File first, or use Download.");
+              else alert("Saved.");
+            } catch (e) {
+              alert("Save failed.");
+            }
+          });
+          dlBtn.addEventListener("click", () => {
+            downloadText(basename(path), ta.value || "", "text/markdown;charset=utf-8");
+          });
+
+          dom.viewer.className = "";
+          dom.viewer.appendChild(toolbar);
+          dom.viewer.appendChild(split);
+          return;
+        }
+        dom.viewer.className = "doc";
         const rendered = await renderMarkdown(content || "");
         dom.viewer.appendChild(rendered);
+        renderOutline(state.activeHeadings);
       }
 
       function setFiles(files) {
@@ -892,6 +1225,7 @@
           .sort((a, b) => a.localeCompare(b));
         dom.fileCount.textContent = `${state.paths.length} files`;
         renderSidebar();
+        renderOutline([]);
         const fromHash = decodeURIComponent((location.hash || "").replace(/^#/, "")) || "";
         if (fromHash && state.files[fromHash] != null) {
           openFile(fromHash, null);
@@ -913,7 +1247,7 @@
         } catch (e) {}
       });
       dom.collapseAll.addEventListener("click", () => {
-        const ds = dom.tree.querySelectorAll("details");
+        const ds = dom.nav.querySelectorAll("details");
         for (const d of ds) d.open = false;
       });
 

package/skills/visual-spec/prompts/vspec_detail/index.md

@@ -19,8 +19,12 @@
 2. HTML 必须是完整单文件（包含内联 CSS 与内联 JS），不得依赖外部脚本/样式资源
 2.1 为了保证生成稳定性：`/specs/details/index.html` 必须以模板为基础生成——从 `prompts/vspec_detail/index.html` 复制整份内容作为起始模板，然后仅做必要的替换/填充（例如内嵌文件内容 JSON、默认打开文件等）。不要从零开始“自由发挥”生成 HTML。
 3. 页面布局：
-   - 左侧：章节导航（按“章节结构”分组，而不是按文件名；必须包含并链接到：原始需求、干系人、角色、术语、场景、功能清单，以及 details 下的各类细节文档）
-   - 右侧：阅读窗口（支持标题、列表、表格、代码块等基础 Markdown 渲染）
+   - 左侧：章节导航 + 标题层级目录（必须）
+     - 章节导航按“章节结构”分组，而不是按文件名；必须包含并链接到：背景（original.md）、干系人（stakeholders.md）、角色（roles.md）、术语（terms.md）、流程（flows）、场景（scenarios）、数据模型（models）、功能清单（functions）、以及 details 下的各类细节文档
+     - 对当前选中的 Markdown 文档：左侧必须展示该文档的“标题与层级结构目录”（基于 `#`~`####`），可点击跳转到右侧预览对应标题位置
+   - 右侧：Markdown Editor（必须）
+     - 必须支持在线编辑与预览（至少提供 Split/Edit/Preview 三种模式）
+     - 支持把编辑结果保存回本地文件（若浏览器不支持写入，则提供下载替换的兼容方案）
 4. 渲染规则：
    - `*.md`：以 Markdown 渲染方式显示（不是纯文本）
    - `*.html`：使用 `iframe srcdoc` 渲染（而不是当作文本显示）
@@ -39,7 +43,7 @@
    - 支持通过 URL hash 直接打开文件（例如 `index.html#module/a/b.md`）
 7. 文档导出提示（必须）：
    - 页面顶部必须有一个明显提示条（banner/notice），说明：可通过 `/vspec:doc` 生成 Word 版需求文档
-   - 提示条需要包含输出路径：`/docs/current/requirement_detail.doc`
+   - 提示条需要包含输出路径：`/docs/current/requirement_detail.docx`
    - 提示条文案要简短、醒目，不随目录滚动消失（建议固定在顶部）
 
 实现约束（必须）：

package/skills/visual-spec/prompts/vspec_doc/doc.md

@@ -1,4 +1,4 @@
-你是一名资深产品经理与交付文档编辑。你的任务是：把项目已有的需求产物（`/specs/**`）汇总成一份可直接用 Microsoft Word 打开的“需求详细文档”，并输出为 Word 可识别的单文件 `.doc`（HTML 格式），写入到 `/docs/current/` 目录下。
+你是一名资深产品经理与交付文档编辑。你的任务是：把项目已有的需求产物（`/specs/**`）汇总成一份可直接用 Microsoft Word 打开的“需求详细文档”，并输出为 Word 可识别的单文件 `.docx`（HTML 格式），写入到 `/docs/current/` 目录下。
 
 语言与本地化（必须）：
 - 读取 `/scheme.yaml` 的 `selected.language`（支持 `en`、`zh`、`ja`；若缺失/非法则按 `en` 处理；`zh-CN` 视为 `zh` 的别名）
@@ -16,8 +16,9 @@
 
 输出与写入要求（必须）：
 1. 确保目录 `/docs/current/` 存在（若不存在则创建）
-2. 仅写入 1 个 Word 文档文件（路径固定）：`/docs/current/requirement_detail.doc`
+2. 仅写入 1 个 Word 文档文件（路径固定）：`/docs/current/requirement_detail.docx`
 3. 该文件必须是完整的 HTML 文档（包含 `<!doctype html>`、`<html>`、`<head>`、`<body>`），并使用内联 CSS（不得依赖外部资源）
+   - 若 Word 弹出“文件格式与扩展名不匹配”的提示：允许打开（该文件内容为 HTML，扩展名为 `.docx`，用于便于传阅与归档）
 4. 文件内容必须保证在 Word 中可打开且排版可读：
    - 使用清晰的层级标题（H1/H2/H3）
    - 表格必须有边框与表头样式
@@ -40,7 +41,7 @@
 1. 封面
    - 文档标题：需求详细文档 / Requirement Detail / 要件詳細ドキュメント
    - 项目名称（若原始需求中可推断则填写；否则留空）
-   - 版本号：固定写 `0.1.11`
+   - 版本号：固定写 `0.1.12`
    - 生成日期：使用今天日期（YYYY-MM-DD）
 2. 目录（手工目录即可）
    - 以可点击的锚点链接到各章节

package/skills/visual-spec/prompts/vspec_more_q/more_q.md

@@ -23,6 +23,7 @@
    - 边界与范围（包含/不包含、上下限、默认值、空值、异常）
    - 状态与操作（暂停/继续/撤回/取消/驳回/变更/紧急叫停等的口径）
    - 数据口径（字段含义、单位、精度、舍入、时间口径、唯一性）
+   - 操作体验与交互模式（一步一步向导 vs 一次性表格/表单、列表/详情/批量操作、行内编辑/弹窗/抽屉、草稿/自动保存/撤销、Web 与 Mobile 的差异）
    - 权限与数据权限（角色、组织范围、越权处理、审计）
    - 外部依赖（系统职责边界、接口清单、失败策略、幂等、对账与补偿）
    - 资料与模板（导入/导出模板、通知文案、协议、证书等）
@@ -90,3 +91,7 @@
    - 建议的回答方式（在 `questions.md` 逐条填写“回答/回答者/回答时间/状态”）
    - 填写完成后执行 `/vspec:refine-q` 合并答案进入 `original.md`
    - 若暂时无法回答：允许先保留未回答，但需要标注原因/预计时间（写在“回答”里即可）
+5. 同时写入固定的 HTML 交互问答页面（用于更容易回答并回写 md 文件）：
+   - 写入：`/specs/background/question_and_answer.html`
+   - 该 HTML 必须为完整可直接打开的单文件（包含内联 CSS 与 JS），无需外部资源
+   - HTML 内容要求：从 `prompts/vspec_more_q/question_and_answer.html` 复制（保持一致），用于读取/编辑 `original.md` 与 `questions.md` 并回写

package/skills/visual-spec/prompts/vspec_new/background.md

@@ -542,7 +542,13 @@ catalog:
 写入要求：
 - 将本次完整输出（包含“原始需求、分析内容、待确认问题”）追加写入到：`/specs/background/original.md`
 - 文件中必须保留原始需求原文与本次分析结果，便于后续 stakeholders/roles 阶段引用
+- 同时写入固定的 HTML 交互问答页面（用于回答 `original.md` 中的“待确认问题/Open Questions/要確認事項”，并可回写 markdown）：
+  - 写入：`/specs/background/question_and_answer.html`
+  - 该 HTML 必须为完整可直接打开的单文件（包含内联 CSS 与 JS），无需外部资源
+  - HTML 内容要求：从 `prompts/vspec_new/question_and_answer.html` 复制（保持一致）
 - 交互提示（必须在对话中输出；不要写入 `/specs/background/original.md`）：
+  - 重要：在你输出并写入 `original.md` 之后，必须立刻停止；不要继续生成 stakeholders/roles/terms/flows/scenarios 等后续产物。必须等待用户先把“待确认问题/Open Questions/要確認事項”回答完毕（或用户明确回复“继续/continue/続けて”表示已完成问答）后，才能进入下一步。
+  - 告知用户：请打开 `/specs/background/question_and_answer.html`，选择 `/specs/background/original.md`，在 HTML 表单中回答“待确认问题”并保存回写；完成后再回复“继续/continue/続けて”
   - 告知用户：回答“待确认问题”可以自己逐条回答，也可以委托 AI 基于当前信息先给出一版“建议答案”，用户再逐条确认/修改
   - 给出可复制的建议话术（按所选语言输出对应版本）：
     - 语言=en：`Please propose suggested answers for the Open Questions based on current information. I will confirm or edit each answer.`

package/skills/visual-spec/prompts/vspec_new/questions.md

@@ -16,6 +16,7 @@
    - 角色与权限（谁能做什么，审批链路，越权处理）
    - 数据与口径（关键字段、主数据来源、术语歧义）
    - 流程与场景（取消/变更/驳回/紧急叫停/换人执行等）
+   - 操作体验与交互模式（必须明确“如何操作”而不只是“有什么功能”）：一步一步向导 vs 一次性表格/表单、列表/详情/批量操作、批量编辑与导入导出、表格行内编辑/弹窗/抽屉、是否支持草稿/自动保存/撤销、移动端与 Web 的差异体验
    - 约束与合规（管理制度、法律法规、留痕留存）
    - 外部依赖（对接系统、数据方向、失败处理、时效）
    - 交付物资料（需要业务提供的文档、模板、文案、协议等）
@@ -87,3 +88,14 @@
 
 4. 编号从 1 开始递增
 5. 提问者默认填“BA/系统分析”
+6. 操作体验强制覆盖（必须）：
+   - 至少生成 4 条与“操作体验/交互模式”相关的问题，且必须覆盖以下主题中的至少 3 个：
+     - 一步一步向导（Wizard）还是一次性表格/表单展示（Single-page）
+     - 核心列表是否需要支持批量操作（批量通过/批量驳回/批量分派/批量导出等）
+     - 表格编辑方式：行内编辑 vs 弹窗/抽屉；是否需要批量编辑
+     - 草稿/自动保存/恢复草稿/撤销（Undo）与二次确认（Confirm）的口径
+     - Web 与 Mobile 的差异：哪些步骤必须在移动端完成、哪些在 Web 完成、是否需要“只读提示/置灰”
+6. 同时写入固定的 HTML 交互问答页面（用于更容易回答并回写 md 文件）：
+   - 写入：`/specs/background/question_and_answer.html`
+   - 该 HTML 必须为完整可直接打开的单文件（包含内联 CSS 与 JS），无需外部资源
+   - HTML 内容要求：从 `prompts/vspec_new/question_and_answer.html` 复制（保持一致），用于读取/编辑 `original.md` 与 `questions.md` 并回写