pi-auto-save-to-markdown 0.7.2 → 0.7.3

package/README.md

@@ -92,7 +92,7 @@ changes never touch the filename, and manually renamed files are left alone.
 ---
 title: "Fix login redirect loop"
 agent: "pi"
-format_version: "1.1"
+format_version: "1.2"
 session_id: "d0a4f541-976d-4d1b-8e1c-30a1f2b3c4d5"
 session_key: "c2088d77"
 last_entry_id: "019be3a2-1f4d-7c8a-9b01-d23e45f6a7b8"
@@ -156,13 +156,21 @@ assistant messages) sits in a small faint `<span>` (`0.5em`, Obsidian's
 `--text-faint` color), so the role stays visually dominant while the details
 remain a glance away. Each block ends with a `---` separator wrapped in single
 blank lines (extra blank lines are trimmed), so blocks are easy to tell apart
-both when reading and when splitting the file programmatically.
+both when reading and when splitting the file programmatically. The document
+heading sits directly after the frontmatter with no blank line between them;
+appends heal the blank line that older versions wrote there.
 
-A saved file rendered in Obsidian — the `<title>-<key>-<time>.md` filename on
-top, the frontmatter folded into the Properties panel, and the Thinking and
-Tool Calls callouts collapsed:
+Two views of the same saved file rendered in Obsidian — the
+`<title>-<key>-<time>.md` filename on top, message blocks with role headers
+and timestamps, and the Thinking and Tool Calls callouts collapsed. First
+with the Properties panel expanded, showing all frontmatter fields:
 
-![A saved conversation file rendered in Obsidian: filename in the title-key-time pattern, frontmatter folded into the Properties panel, message blocks with role headers and timestamps, and collapsed Thinking and Tool Calls callouts](https://raw.githubusercontent.com/licongy/pi-claudian/master/packages/auto-save-to-markdown/screenshot.png)
+![A saved conversation file rendered in Obsidian with the Properties panel expanded: filename in the title-key-time pattern, all frontmatter fields visible as properties (title, agent, format version, session id, cost, tokens, timestamps, project root, session file), and the beginning of the message body](https://raw.githubusercontent.com/licongy/pi-claudian/master/packages/auto-save-to-markdown/screenshot-1.png)
+
+Then with the Properties panel folded away and the full conversation body in
+view:
+
+![A saved conversation file rendered in Obsidian: filename in the title-key-time pattern, frontmatter folded into the Properties panel, message blocks with role headers and timestamps, and collapsed Thinking and Tool Calls callouts](https://raw.githubusercontent.com/licongy/pi-claudian/master/packages/auto-save-to-markdown/screenshot-2.png)
 
 ### Fragmented thinking repair
 
@@ -172,7 +180,13 @@ original spaces collapse into leading spaces of one-word fragments joined by
 runs of newlines. The extension detects this corruption (lines starting with a
 single leading space, or a majority of 1–2-character fragment lines) and
 re-joins the fragments into flowing text, so saved thinking reads normally
-instead of one word per line. Clean thinking blocks are written untouched.
+instead of one word per line. Paragraph breaks survive the repair: a separator
+run of 3+ newlines that follows a sentence-final character is a real paragraph
+break about three times out of four in corrupted blocks, so exactly those
+separators are restored to blank-line paragraphs while every other separator
+joins — a break is never inserted mid-sentence; worst case, one lands between
+two complete sentences, which still reads fine. Clean thinking blocks are
+written untouched.
 
 `cost` and the token fields cover the whole saved branch and include cached
 tokens (priced at the provider's cache rates), so the totals are comparable

package/README.zh.md

@@ -66,7 +66,7 @@ PI_SAVE_CONVERSATION_DIR=notes/ai pi
 ---
 title: "修复登录重定向死循环"
 agent: "pi"
-format_version: "1.1"
+format_version: "1.2"
 session_id: "d0a4f541-976d-4d1b-8e1c-30a1f2b3c4d5"
 session_key: "c2088d77"
 last_entry_id: "019be3a2-1f4d-7c8a-9b01-d23e45f6a7b8"
@@ -126,12 +126,19 @@ Markdown 解析。
 浅色 `<span>` 中（`0.5em`，Obsidian 的 `--text-faint` 颜色），角色名因此保持
 醒目，细节又触手可及。每个消息块以"上下各一个空行"包裹的 `---` 分隔线结尾
 （多余空行会被裁剪），无论是阅读还是程序化切分，都能清楚地区分每个消息块。
+文档标题紧跟在 frontmatter 之后，中间没有空行；追加保存时会顺带修复旧版本
+在两者之间写下的空行。
 
-保存的文件在 Obsidian 中的渲染效果——顶部为 `<标题>-<key>-<时间>.md`
-文件名，frontmatter 折叠在 Properties 面板中，Thinking 与 Tool Calls
-两个 callout 处于折叠状态：
+同一个保存文件在 Obsidian 中的两种渲染视图——顶部为
+`<标题>-<key>-<时间>.md` 文件名，消息块带角色信息头和时间戳，Thinking
+与 Tool Calls 两个 callout 处于折叠状态。首先是 Properties 面板展开、
+展示全部 frontmatter 字段的效果：
 
-![保存的对话文件在 Obsidian 中的渲染效果：文件名呈"标题-key-时间"格式，frontmatter 折叠在 Properties 面板中，消息块带角色信息头和时间戳，Thinking 与 Tool Calls callout 处于折叠状态](https://raw.githubusercontent.com/licongy/pi-claudian/master/packages/auto-save-to-markdown/screenshot.png)
+![保存的对话文件在 Obsidian 中渲染、Properties 面板展开的效果：文件名呈"标题-key-时间"格式，全部 frontmatter 字段以属性形式可见（title、agent、format_version、session_id、cost、tokens、时间戳、project_root、session_file），下方为消息正文开头](https://raw.githubusercontent.com/licongy/pi-claudian/master/packages/auto-save-to-markdown/screenshot-1.png)
+
+然后是 Properties 面板折叠、完整对话正文的效果：
+
+![保存的对话文件在 Obsidian 中的渲染效果：文件名呈"标题-key-时间"格式，frontmatter 折叠在 Properties 面板中，消息块带角色信息头和时间戳，Thinking 与 Tool Calls callout 处于折叠状态](https://raw.githubusercontent.com/licongy/pi-claudian/master/packages/auto-save-to-markdown/screenshot-2.png)
 
 ### 碎片化 thinking 修复
 
@@ -139,7 +146,10 @@ Markdown 解析。
 存成一词一行、甚至一字一行：原始空格塌缩成碎片行开头的单个空格，碎片之间
 被成串的换行拼接。扩展会检测这种损坏（依据带单个前导空格的行、或大量
 1–2 字符碎片行），把碎片重新接回通顺的文本，保存的 thinking 不再一行
-一词。正常的 thinking 块原样保存，不做任何改动。
+一词。段落分隔在修复后得以保留：句末标点之后紧跟 3 个以上换行的分隔串，
+在损坏块中约四分之三是真实的段落边界，因此恰好这类分隔被还原成空行段落，
+其余全部拼接——断行永远不会插进句子中间，最坏也只是落在两个完整句子
+之间，阅读不受影响。正常的 thinking 块原样保存，不做任何改动。
 
 `cost` 和 token 字段统计整条已保存分支，且包含缓存 token（按供应商缓存
 价格计费），因此总计可与供应商侧账单（如 OpenRouter Activity）对照。未

package/index.ts

@@ -114,7 +114,9 @@
  *   still exports its complete history.
  * - Thinking repair: reasoning blocks stored with the upstream
  *   newline-fragmentation corruption (one word per line) are detected and
- *   re-joined into flowing text before saving; clean thinking is untouched.
+ *   re-joined into flowing text before saving, keeping paragraph breaks
+ *   where they survive as long separator runs after sentence ends; clean
+ *   thinking is untouched.
  *
  * Manual commands:
  * - `/save-conversation` saves the current branch immediately and reports
@@ -190,10 +192,11 @@ const SAVE_STATE_SCHEMA = "1.2";
  * structural breaks that change how a parser or migration tool must match
  * blocks (message header structure, `---` separators, callout syntax);
  * MINOR for parse-invariant tweaks and bugfixes (header styling, content
- * transforms like the thinking repair); additive frontmatter fields do NOT
- * bump it — they are invisible to any within-major parser.
+ * transforms like the thinking repair, the blank line once written between
+ * the frontmatter and the document heading); additive frontmatter fields do
+ * NOT bump it — they are invisible to any within-major parser.
  */
-const FORMAT_VERSION = "1.1";
+const FORMAT_VERSION = "1.2";
 
 /**
  * Package version of this extension, read best-effort from the adjacent
@@ -416,10 +419,21 @@ interface BranchMeta {
  * " " lines included), and an excess of 1–2-char non-list-marker lines (CJK
  * fragments carry no leading space). Clean thinking never matches either.
  *
- * Repair strips all newlines — run length carries no recoverable meaning (the
- * same paragraph boundary appears as 1, 2 or 3 newlines, while 4–7 can sit
- * mid-sentence) — and collapses the doubled spaces left by lone-space
- * fragments. Clean blocks pass through untouched.
+ * Repair re-joins the fragments into flowing text. Word separators — the
+ * whitespace runs between two fragments — lose their newlines: run length
+ * alone carries no recoverable meaning, because the same word separator
+ * appears as 1, 2 or 3 newlines depending on the block. Original paragraph
+ * boundaries survive as a faint but strong signal: a separator run of 3+
+ * newlines that follows a sentence-final character (closing quotes and
+ * brackets skipped when looking) marks a real paragraph break 73–93% of the
+ * time in corrupted blocks, while plain word separators sit mid-sentence —
+ * so exactly those separators become blank-line paragraph breaks and
+ * everything else is joined. The sentence-final guard means a break is never
+ * inserted mid-sentence: worst case, one lands between two complete
+ * sentences, which still reads fine. Join spacing comes from the separator
+ * itself: a separator containing a surviving space joins with one space, a
+ * bare one (CJK fragments, attached punctuation) joins with nothing. Clean
+ * blocks pass through untouched.
  */
 
 /** Line whose single leading space is a survived word separator. */
@@ -445,14 +459,42 @@ function isFragmentedThinking(s: string): boolean {
   return nonBlank.filter(isThinkingShortFragment).length / nonBlank.length >= 0.4;
 }
 
+/** Sentence-final characters: a long separator run after one may be a paragraph break. */
+const THINKING_SENTENCE_END = /[.!?。！？…]/;
+/** Closing punctuation skipped when looking for the sentence end behind it. */
+const THINKING_CLOSING = /[)\]}"'”』」）】》]/;
+/** Newlines a separator run needs before it can count as a paragraph break. */
+const THINKING_PARAGRAPH_RUN = 3;
+
 /** Repair newline-fragmented thinking; clean thinking is returned unchanged. */
 function repairThinking(s: string): string {
   if (!isFragmentedThinking(s)) return s;
   debug("repairing fragmented thinking block:", s.length, "chars");
-  return s
-    .replace(/\n+/g, "")
-    .replace(/[ \t]{2,}/g, " ")
-    .trim();
+  let out = "";
+  let i = 0;
+  while (i < s.length) {
+    let end = i;
+    while (end < s.length && !/\s/.test(s[end])) end++;
+    out += s.slice(i, end);
+    let next = end;
+    while (next < s.length && /\s/.test(s[next])) next++;
+    if (next >= s.length) break; // trailing whitespace: drop
+    const sep = s.slice(end, next);
+    if (!/[\n\r]/.test(sep)) {
+      out += " "; // plain spaces: a single word separator
+    } else {
+      const newlines = sep.match(/[\n\r]/g)!.length;
+      let p = out.length - 1;
+      while (p >= 0 && THINKING_CLOSING.test(out[p])) p--;
+      const sentenceEnd = p >= 0 && THINKING_SENTENCE_END.test(out[p]);
+      if (newlines >= THINKING_PARAGRAPH_RUN && sentenceEnd) out += "\n\n";
+      else if (/[ \t]/.test(sep)) out += " ";
+      // A bare newline separator attached CJK fragments or punctuation:
+      // join with nothing.
+    }
+    i = next;
+  }
+  return out.replace(/[ \t]{2,}/g, " ").trim();
 }
 
 // ---------- foreign sessions for /save-conversation-all ----------
@@ -1405,7 +1447,14 @@ export default function (pi: ExtensionAPI) {
 
   function replaceFrontmatter(existing: string, fm: string): string {
     if (/^---\r?\n[\s\S]*?\r?\n---\r?\n/.test(existing)) {
-      return existing.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n/, fm + "\n");
+      const rest = existing.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n/, "");
+      // Heal the old layout's blank line(s) between the frontmatter and the
+      // document heading (new files write the heading directly after the
+      // frontmatter). Only blank lines immediately followed by a `#` heading
+      // at the very start of the body are stripped — anything the user
+      // reorganized stays untouched.
+      const healed = rest.replace(/^(?:[ \t]*\r?\n)+(#[^\r\n]*)/, "$1");
+      return fm + "\n" + healed;
     }
     return `${fm}\n\n${existing}`;
   }
@@ -1414,10 +1463,12 @@ export default function (pi: ExtensionAPI) {
    * Rewrite the document heading (the `# title` line written at file
    * creation) to the current title. Only called on rename-on-title saves.
    * The heading is located as the first non-blank line after the frontmatter
-   * closing delimiter (file creation writes exactly one blank line before
-   * it) rather than "the first # line anywhere", so a manually deleted
-   * heading (whose place would otherwise be taken by some content heading
-   * further down) cannot be mis-rewritten.
+   * closing delimiter — new files write it directly after the frontmatter
+   * with no blank line, legacy files wrote exactly one blank line before it
+   * (replaceFrontmatter heals that away on appends) — rather than "the
+   * first # line anywhere", so a manually deleted heading (whose place
+   * would otherwise be taken by some content heading further down) cannot
+   * be mis-rewritten.
    */
   function rewriteDocumentHeading(content: string, title: string): string {
     const fm = /^---\r?\n[\s\S]*?\r?\n---\r?\n/.exec(content);
@@ -1643,7 +1694,7 @@ export default function (pi: ExtensionAPI) {
       const target = path.join(plan.dir, plan.filename);
       const meta = computeMeta(ctx, plan.pathMessages, plan.sessionKey, undefined, undefined);
       const body = renderEntries(plan.pathMessages); // ends with the trailing separator
-      const content = `${frontmatter(meta)}\n\n# ${meta.title}\n\n${body}`;
+      const content = `${frontmatter(meta)}\n# ${meta.title}\n\n${body}`;
       await atomicWrite(target, content);
       debug("created conversation file:", target);
       return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-auto-save-to-markdown",
-  "version": "0.7.2",
+  "version": "0.7.3",
   "description": "Pi extension that automatically saves each completed conversation turn as a markdown file with YAML frontmatter, one file per session-tree branch.",
   "type": "module",
   "license": "MIT",