@pi-claudian/auto-save-to-markdown 0.1.1 → 0.1.3

package/README.md

@@ -78,11 +78,15 @@ session_file: "~/.pi/agent/sessions/--Users-me-project-20260829-050500_ab12.json
 
 # Fix login redirect loop
 
-## User · 13:05:12
+User · 13:05:12
+===
 
 The login page redirects in a loop after the auth refactor...
 
-## Assistant · 13:05:40 · claude-sonnet-4-5
+---
+
+Assistant · 13:05:40 · claude-sonnet-4-5
+===
 
 <details>
 <summary>Thinking</summary>
@@ -98,6 +102,8 @@ I'll trace the middleware order first.
 - `read` — {"filePath":"/Users/me/project/src/auth/middleware.ts"}
 
 > **Tool · read** /Users/me/project/src/auth/middleware.ts — 120 lines …
+
+---
 ```
 
 The body renders user and assistant messages in full (assistant thinking is
@@ -105,6 +111,23 @@ kept in a collapsible `<details>` block) and summarizes each tool call and
 result in one line, so the file stays readable while still showing what the
 agent did.
 
+Each message block opens with a setext level-1 info header (`User · …`,
+underlined with `===`) — one level above the `##` headings AI content
+typically starts with, and distinguishable from content `#` headings when
+parsing — and 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.
+
+### Fragmented thinking repair
+
+Some upstream reasoning streams (observed with z-ai/GLM via OpenRouter) store
+thinking with every word — or every CJK character — on its own line: the
+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.
+
 `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
 with provider-side accounting (e.g. OpenRouter activity). Requests that never

package/README.zh.md

@@ -68,11 +68,15 @@ session_file: "~/.pi/agent/sessions/--Users-me-project-20260829-050500_ab12.json
 
 # 修复登录重定向死循环
 
-## User · 13:05:12
+User · 13:05:12
+===
 
 auth 重构之后登录页一直重定向死循环……
 
-## Assistant · 13:05:40 · claude-sonnet-4-5
+---
+
+Assistant · 13:05:40 · claude-sonnet-4-5
+===
 
 <details>
 <summary>Thinking</summary>
@@ -88,12 +92,27 @@ auth 重构之后登录页一直重定向死循环……
 - `read` — {"filePath":"/Users/me/project/src/auth/middleware.ts"}
 
 > **Tool · read** /Users/me/project/src/auth/middleware.ts — 120 lines …
+
+---
 ```
 
 正文完整渲染 user / assistant 消息（assistant 的 thinking 放在可折叠的
 `<details>` 块中），每个工具调用和结果各压缩成一行摘要，既可读又能看出
 agent 做了什么。
 
+每个消息块以 setext 一级信息头（`User · …`，下一行以 `===` 下划）开头——
+高于 AI 内容常见的 `##` 二级标题，解析时也能与内容中的 `#` 一级标题区分
+开——并以"上下各一个空行"包裹的 `---` 分隔线结尾（多余空行会被裁剪），
+无论是阅读还是程序化切分，都能清楚地区分每个消息块。
+
+### 碎片化 thinking 修复
+
+部分上游推理流（在 z-ai/GLM 经 OpenRouter 的场景中观察到）会把 thinking
+存成一词一行、甚至一字一行：原始空格塌缩成碎片行开头的单个空格，碎片之间
+被成串的换行拼接。扩展会检测这种损坏（依据带单个前导空格的行、或大量
+1–2 字符碎片行），把碎片重新接回通顺的文本，保存的 thinking 不再一行
+一词。正常的 thinking 块原样保存，不做任何改动。
+
 `cost` 和 token 字段统计整条已保存分支，且包含缓存 token（按供应商缓存
 价格计费），因此总计可与供应商侧账单（如 OpenRouter Activity）对照。未
 进入会话树的请求（失败重试、共用同一 API key 的其他会话）不在其中。

package/index.ts

@@ -20,6 +20,10 @@
  * - Frontmatter: title, session id, tree (branch key), model, provider,
  *   cumulative cost and tokens (input, output, cache read/write), message
  *   count, created/updated timestamps, project root and session file.
+ * - Body format: every message block opens with a setext-H1 info header
+ *   (`User · HH:MM:SS` / `Assistant · HH:MM:SS · model`, underlined with
+ *   `===`, distinct from the `#`/`##` ATX headings AI content uses) and
+ *   ends with a `---` separator wrapped in single blank lines.
  * - Branching: each file records exactly ONE branch (the root→leaf path
  *   returned by sessionManager.getBranch()). State is persisted via
  *   `pi.appendEntry()` custom entries, which are part of the session tree
@@ -32,6 +36,9 @@
  * - Compaction: files archive the ORIGINAL messages (getBranch() returns the
  *   raw tree path, not the compaction-aware context), so a compacted session
  *   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.
  *
  * Manual command: `/save-conversation` saves the current branch immediately
  * and reports the file path.
@@ -122,6 +129,59 @@ interface BranchMeta {
   projectRoot: string;
 }
 
+// ---------- thinking fragmentation repair ----------
+
+/**
+ * Some upstream reasoning streams (observed with z-ai/GLM via OpenRouter) store
+ * thinking as one word — or one CJK character — per line: the stream splits
+ * tokens into fragments joined by runs of newlines, and the original spaces
+ * survive only as leading spaces of the fragments. The saved markdown then has
+ * every token on its own line, which is miserable to read and bloats storage.
+ *
+ * Detection uses two signatures validated against ~520 real thinking blocks:
+ * lines starting with exactly one space (a survived word separator; blank-ish
+ * " " 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.
+ */
+
+/** Line whose single leading space is a survived word separator. */
+function isThinkingSigLine(line: string): boolean {
+  return line === " " || /^ [^ *+\-\d]/.test(line);
+}
+
+/** Non-blank line of 1–2 chars that is not a standalone list marker. */
+function isThinkingShortFragment(line: string): boolean {
+  const s = line.trim();
+  if (s.length === 0 || s.length > 2) return false;
+  return !/^([-*+]|\d+[.)])$/.test(s);
+}
+
+/** Whether a thinking block shows the newline-fragmentation corruption. */
+function isFragmentedThinking(s: string): boolean {
+  const lines = s.split("\n");
+  const nonBlank = lines.filter((l) => l.trim().length > 0);
+  if (nonBlank.length === 0) return false;
+  const sig = lines.filter(isThinkingSigLine).length;
+  if (nonBlank.length < 8) return nonBlank.length >= 3 && sig >= 3;
+  if (sig / lines.length >= 0.12) return true;
+  return nonBlank.filter(isThinkingShortFragment).length / nonBlank.length >= 0.4;
+}
+
+/** 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();
+}
+
 export default function (pi: ExtensionAPI) {
   /**
    * Resolve the target directory. The env var may hold a relative folder name
@@ -222,10 +282,21 @@ export default function (pi: ExtensionAPI) {
 
   // ---------- markdown rendering ----------
 
+  /**
+   * Strip leading blank lines and trailing whitespace from a rendered block,
+   * so joins and separators always keep exactly one blank line around them
+   * no matter what blank lines the content itself starts or ends with.
+   */
+  function tighten(s: string): string {
+    return s.replace(/^(?:[ \t]*\n)+/, "").replace(/\s+$/, "");
+  }
+
   function renderAssistant(m: AssistantMessage, t: string): string {
     // Render blocks in their original chronological order: thinking always
     // precedes the text it produced, instead of being grouped after the fact.
-    const header = `## Assistant · ${t}${m.model ? ` · ${m.model}` : ""}`;
+    // Setext H1 (`===` underline): one level above the `##` headings AI
+    // content typically starts with, and distinct from content `#` headings.
+    const header = `Assistant · ${t}${m.model ? ` · ${m.model}` : ""}\n===`;
     const parts: string[] = [];
     const thinkings: string[] = [];
     const flushThinking = () => {
@@ -242,7 +313,7 @@ export default function (pi: ExtensionAPI) {
         flushThinking();
         parts.push(b.text);
       } else if (b.type === "thinking") {
-        thinkings.push(b.thinking);
+        thinkings.push(repairThinking(b.thinking));
       } else if (b.type === "toolCall") {
         flushThinking();
         calls.push(`- \`${b.name}\` — ${previewArgs(b.arguments)}`);
@@ -276,7 +347,7 @@ export default function (pi: ExtensionAPI) {
       const m = e.message;
       const t = clock(e.timestamp);
       if (m.role === "user") {
-        blocks.push(`## User · ${t}\n\n${userText(m.content)}`);
+        blocks.push(`User · ${t}\n===\n\n${userText(m.content)}`);
       } else if (m.role === "assistant") {
         blocks.push(renderAssistant(m, t));
       } else if (m.role === "toolResult") {
@@ -285,7 +356,12 @@ export default function (pi: ExtensionAPI) {
       // Other roles (custom, bashExecution, branchSummary, compactionSummary)
       // are not part of the rendered conversation record.
     }
-    return blocks.join("\n\n");
+    if (blocks.length === 0) return "";
+    // Every block ends with a `---` separator wrapped in single blank lines
+    // (the blank line above also keeps `---` from turning the last content
+    // line into a setext H2). The trailing separator after the final block
+    // makes later appends uniform: new blocks simply continue after it.
+    return `${blocks.map(tighten).join("\n\n---\n\n")}\n\n---\n`;
   }
 
   // ---------- frontmatter ----------
@@ -504,8 +580,8 @@ export default function (pi: ExtensionAPI) {
 
     if (fullCreate) {
       const meta = computeMeta(ctx, plan.pathMessages, plan.branchKey, undefined);
-      const body = renderEntries(plan.pathMessages);
-      const content = `${frontmatter(meta)}\n\n# ${meta.title}\n\n${body}\n`;
+      const body = renderEntries(plan.pathMessages); // ends with the trailing separator
+      const content = `${frontmatter(meta)}\n\n# ${meta.title}\n\n${body}`;
       await atomicWrite(filePath, content);
       debug("created conversation file:", filePath);
       return {
@@ -528,10 +604,15 @@ export default function (pi: ExtensionAPI) {
 
     const existing = await fs.readFile(filePath, "utf-8");
     const meta = computeMeta(ctx, plan.pathMessages, plan.branchKey, parseCreated(existing));
-    const appended = renderEntries(plan.appendEntries);
+    const appended = renderEntries(plan.appendEntries); // ends with the trailing separator
     let updated = replaceFrontmatter(existing, frontmatter(meta));
-    if (!updated.endsWith("\n")) updated += "\n";
-    updated += `\n${appended}\n`;
+    // Collapse trailing blank lines to a single newline so the separator
+    // always has exactly one blank line above it, whatever earlier saves
+    // (or a manual edit) left behind.
+    updated = updated.replace(/\s*$/, "\n");
+    // Files written by the old format end without a `---` separator; add one
+    // at the boundary so old and new content stay delimited.
+    updated += updated.endsWith("---\n") ? `\n${appended}` : `\n---\n\n${appended}`;
     await atomicWrite(filePath, updated);
     debug("appended", plan.appendEntries.length, "entries to:", filePath);
     return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-claudian/auto-save-to-markdown",
-  "version": "0.1.1",
+  "version": "0.1.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",