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

package/README.md

@@ -92,10 +92,10 @@ 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.3"
 session_id: "d0a4f541-976d-4d1b-8e1c-30a1f2b3c4d5"
 session_key: "c2088d77"
-last_entry_id: "019be3a2-1f4d-7c8a-9b01-d23e45f6a7b8"
+branch_last_entry_id: "019be3a2-1f4d-7c8a-9b01-d23e45f6a7b8"
 model: "z-ai/glm-5.3"
 provider: "openrouter"
 cost: 0.023401
@@ -105,8 +105,8 @@ tokens_output: 3515
 tokens_cache_read: 0
 tokens_cache_write: 0
 messages: 8
-created: "2026-08-29T05:05:12.000Z"
-updated: "2026-08-29T05:42:10.000Z"
+created: "2026-08-29T13:05:12+08:00"
+updated: "2026-08-29T13:42:10+08:00"
 project_root: "/Users/me/project"
 session_file: "~/.pi/agent/sessions/--Users-me-project-20260829-050500_ab12.jsonl"
 ---
@@ -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,10 +66,10 @@ PI_SAVE_CONVERSATION_DIR=notes/ai pi
 ---
 title: "修复登录重定向死循环"
 agent: "pi"
-format_version: "1.1"
+format_version: "1.3"
 session_id: "d0a4f541-976d-4d1b-8e1c-30a1f2b3c4d5"
 session_key: "c2088d77"
-last_entry_id: "019be3a2-1f4d-7c8a-9b01-d23e45f6a7b8"
+branch_last_entry_id: "019be3a2-1f4d-7c8a-9b01-d23e45f6a7b8"
 model: "z-ai/glm-5.3"
 provider: "openrouter"
 cost: 0.023401
@@ -79,8 +79,8 @@ tokens_output: 3515
 tokens_cache_read: 0
 tokens_cache_write: 0
 messages: 8
-created: "2026-08-29T05:05:12.000Z"
-updated: "2026-08-29T05:42:10.000Z"
+created: "2026-08-29T13:05:12+08:00"
+updated: "2026-08-29T13:42:10+08:00"
 project_root: "/Users/me/project"
 session_file: "~/.pi/agent/sessions/--Users-me-project-20260829-050500_ab12.jsonl"
 ---
@@ -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

@@ -25,11 +25,14 @@
  *   plugins for other runtimes would write their own value), format_version
  *   (the document format of the last write — additive frontmatter fields
  *   never bump it; see FORMAT_VERSION), session id, session key (the
- *   filename key), last entry id (the id of the deepest message entry on the
- *   saved branch — the file's position in the session jsonl tree at the last
- *   write), model, provider, cumulative cost and tokens (input, output,
- *   cache read/write), message count, created/updated timestamps, project
- *   root and session file.
+ *   filename key), branch last entry id (field `branch_last_entry_id` — the
+ *   id of the deepest message entry on the saved branch: the file's position
+ *   in the session jsonl tree at the last write, scoped to this file's
+ *   branch, not the session-wide last entry), model, provider, cumulative
+ *   cost and tokens (input, output,
+ *   cache read/write), message count, created/updated timestamps (tz-aware
+ *   ISO 8601 in the local timezone with its numeric UTC offset, e.g.
+ *   "2026-08-29T13:05:12+08:00"), project root and session file.
  * - Body format: every message block opens with a setext-H1 info header
  *   (`User <span …>YYYY-MM-DD HH:MM:SS</span>` /
  *   `Assistant <span …>YYYY-MM-DD HH:MM:SS · model</span>`, where the span
@@ -114,7 +117,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 +195,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.3";
 
 /**
  * Package version of this extension, read best-effort from the adjacent
@@ -245,8 +251,8 @@ interface SaveState {
   /**
    * Id of the session tree leaf at save time (getLeafId()) — may be a custom
    * state entry rather than a message; used to rank continuation candidates
-   * on the current path. Distinct from frontmatter `last_entry_id`, which is
-   * the deepest message entry (an id actually present in the file).
+   * on the current path. Distinct from frontmatter `branch_last_entry_id`,
+   * which is the deepest message entry (an id actually present in the file).
    */
   lastSavedEntryId: string | null;
   file: string;
@@ -385,10 +391,11 @@ interface BranchMeta {
   sessionKey: string;
   /**
    * Id of the deepest message entry on the saved branch at the last write
-   * (field name `last_entry_id`) — the file's exact position in the
-   * session jsonl tree. Updated on every append, like `updated`.
+   * (field name `branch_last_entry_id`) — the file's exact position in the
+   * session jsonl tree, scoped to this file's branch rather than the
+   * session-wide last entry. Updated on every append, like `updated`.
    */
-  lastEntryId: string;
+  branchLastEntryId: string;
   model: string | null;
   provider: string | null;
   cost: number;
@@ -416,10 +423,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 +463,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 ----------
@@ -1055,6 +1101,24 @@ export default function (pi: ExtensionAPI) {
     return `"${safe.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
   }
 
+  /**
+   * ISO 8601 timestamp in the machine's local timezone, with the numeric
+   * UTC offset appended (e.g. "2026-08-29T13:05:12+08:00"): tz-aware, so the
+   * value reads as local wall-clock time without assuming the reader's
+   * timezone. Legacy files written with UTC "Z" values parse identically.
+   */
+  function localIsoTimestamp(date: Date): string {
+    const pad = (n: number) => String(n).padStart(2, "0");
+    const offsetMin = -date.getTimezoneOffset();
+    const sign = offsetMin >= 0 ? "+" : "-";
+    const abs = Math.abs(offsetMin);
+    return (
+      `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}` +
+      `T${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())}` +
+      `${sign}${pad(Math.floor(abs / 60))}:${pad(abs % 60)}`
+    );
+  }
+
   function frontmatter(meta: BranchMeta): string {
     const lines: string[] = ["---"];
     lines.push(`title: ${yamlQuote(meta.title)}`);
@@ -1062,7 +1126,7 @@ export default function (pi: ExtensionAPI) {
     lines.push(`format_version: ${yamlQuote(FORMAT_VERSION)}`);
     if (meta.sessionId) lines.push(`session_id: ${yamlQuote(meta.sessionId)}`);
     lines.push(`session_key: ${yamlQuote(meta.sessionKey)}`);
-    lines.push(`last_entry_id: ${yamlQuote(meta.lastEntryId)}`);
+    lines.push(`branch_last_entry_id: ${yamlQuote(meta.branchLastEntryId)}`);
     if (meta.model) lines.push(`model: ${yamlQuote(meta.model)}`);
     if (meta.provider) lines.push(`provider: ${yamlQuote(meta.provider)}`);
     lines.push(`cost: ${meta.cost.toFixed(6)}`);
@@ -1135,14 +1199,14 @@ export default function (pi: ExtensionAPI) {
         tokensCacheWrite += usage.cacheWrite ?? 0;
       }
     }
-    const now = new Date().toISOString();
+    const now = localIsoTimestamp(new Date());
     return {
       title: displayTitle(ctx, firstUserText(pathMessages)),
       agent: agent ?? AGENT,
       sessionId: ctx.session.getSessionId(),
       sessionFile: ctx.session.getSessionFile() ?? null,
       sessionKey,
-      lastEntryId: pathMessages[pathMessages.length - 1].id,
+      branchLastEntryId: pathMessages[pathMessages.length - 1].id,
       model,
       provider,
       cost,
@@ -1405,7 +1469,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 +1485,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 +1716,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.4",
   "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",