Feat/agent observability Improve agent observability and file sync resilience

.github/workflows/release.yml

@@ -30,6 +30,9 @@ jobs:
 
       - run: npm install
 
+      - name: Type check
+        run: node node_modules/typescript/bin/tsc -p tsconfig.main.json --noEmit && node node_modules/typescript/bin/tsc -p tsconfig.preload.json --noEmit && node node_modules/typescript/bin/tsc -p tsconfig.renderer.json --noEmit
+
       - run: npm run build
 
       - name: Build distributables

.gitignore

@@ -6,3 +6,7 @@ release/
 .claude/
 *.env
 log.md
+
+# Agent Loop logs (迭代日志，不提交到仓库)
+agent-loop-logs/
+agent-loop.yaml

CLAUDE.md

@@ -1,68 +1,89 @@
-# ColaMD
+# CLAUDE.md
 
-## 产品定位
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
-**Agent Native 的 Markdown 编辑器。**
+## Build & Development Commands
 
-面向 Agent-to-Agent、Agent-to-Human 之间的新型协作方式。当前 v1.0 聚焦于核心体验：AI Agent 修改 .md 文件时，ColaMD 自动检测变化并实时显示最新内容，让人类和 Agent 的协作像结对编程一样流畅。
+```bash
+npm run dev          # Start dev server with HMR (electron-vite dev)
+npm run build        # Compile all 3 bundles (main, preload, renderer)
+npm run preview      # Preview production build
+npm run dist         # Build + package for current platform
+npm run dist:mac     # macOS build (.dmg + .zip)
+npm run dist:win     # Windows build (.exe NSIS installer)
+npm run dist:linux   # Linux build (.AppImage + .deb)
+```
+
+No test framework, linter, or formatter is configured. Type checking: `npx tsc --noEmit`.
 
-后续会随着 Agent 生态的发展持续迭代。
+Release is triggered by pushing `v*` tags (see `.github/workflows/release.yml`).
 
-## 设计哲学
+## Architecture
 
-### 如非必要，勿增实体
+Electron 3-process model with a minimal, no-framework renderer:
 
-这是 ColaMD 的第一原则。每增加一个 UI 元素、一个功能、一行代码，都要问：这是绝对必要的吗？默认答案是否。
+```
+Main Process (src/main/index.ts)
+  Node.js APIs: fs.watch, dialog, shell, Menu
+  Responsibilities: window lifecycle, file I/O, file watching, agent detection,
+                    menus, PDF/HTML export, custom theme storage
+        ↕ IPC (ipcMain / ipcRenderer)
+Preload (src/preload/index.ts)
+  contextBridge.exposeInMainWorld → window.electronAPI
+  Defines typed ElectronAPI interface (invoke + event listener patterns)
+        ↕
+Renderer (src/renderer/)
+  Plain TypeScript, no React/Vue — Milkdown IS the UI
+  main.ts → wires IPC events to editor actions
+  editor/editor.ts → Milkdown setup (commonmark, gfm, history, listener, clipboard)
+  editor/html-view.ts → custom inline HTML node view
+  themes/base.css → ALL CSS: reset, layout, 4 built-in themes (via CSS custom properties)
+  themes/theme-manager.ts → theme switching & localStorage persistence
+```
 
-- 不要工具栏（用户会用快捷键和 Markdown 语法）
-- 不要侧边栏
-- 不要状态栏
-- 界面只有：标题栏（拖拽用）+ 编辑器
-- 追求极致的简单，一个功能做到极致
+### Key Mechanism: File Hot Update (Core Feature)
 
-### 核心功能优先级
+The main process uses `fs.watch()` on the open file. When external changes are detected:
 
-1. **文件热更新**（核心卖点）— 外部 Agent 修改 .md 时自动刷新，实时看到 Agent 的工作
-2. **所见即所得** — 输入 Markdown 即刻渲染为富文本
-3. **主题系统** — CSS 主题，可导入自定义主题
-4. **导出** — PDF、HTML
+1. Check `isInternalSave` flag — if true (our own save within 100ms), ignore to prevent feedback loops
+2. Agent activity state machine: `idle` → `active` (rapid writes, gap < 2s) → `cooldown` (3s after last write) → `idle` (2s later). Visual feedback via CSS animation on `#agent-dot`.
+3. Debounce 100ms → read file → send `file-changed` IPC to renderer → `setMarkdown()` replaces all content
 
-### 不做的事情
+Each BrowserWindow has independent `WindowState` (filePath, watcher, agent state). Opening a file already open in another window focuses that window instead.
 
-- 不做文件管理、文件树、工作区
-- 不做知识库管理
-- 不做云同步、协作编辑
-- 不做笔记组织和标签系统
-- 不加不必要的 UI 元素（工具栏、侧边栏等）
+### IPC Pattern
 
-## 技术栈
+- **Renderer → Main**: `ipcRenderer.invoke()` for request/response (openFile, saveFile, exportPDF, etc.)
+- **Main → Renderer**: `webContents.send()` for push events (file-changed, set-theme, agent-activity, menu-* actions)
+- All methods are typed via the `ElectronAPI` interface in `src/preload/index.ts`
 
-- Electron（桌面跨平台）
-- Milkdown（基于 ProseMirror 的 WYSIWYG Markdown 框架）
-- TypeScript 严格模式
-- electron-vite（构建）
-- electron-builder（打包）
+### Theme System
 
-## 项目结构
+- Built-in themes: `light`, `dark`, `elegant` (default), `newsprint` — switched by CSS class on `<body>`
+- Custom themes: stored as `.css` files in `~/.colamd/themes/`, injected via `<style>` element
+- Theme variables: `--bg-color`, `--text-color`, `--text-muted`, `--border-color`, `--link-color`, `--code-bg`, `--code-block-bg`, `--code-block-text`, `--blockquote-border`, `--blockquote-bg`, `--table-header-bg`, `--selection-bg`
+- Menu is rebuilt when custom themes change (scans themes dir synchronously)
 
-```
-src/
-├── main/           # Electron 主进程
-│   └── index.ts    # 窗口管理、文件 I/O、菜单、文件监听
-├── preload/        # 安全 IPC 桥接
-│   └── index.ts
-└── renderer/       # 渲染进程
-    ├── index.html
-    ├── main.ts     # 入口，连接编辑器和 IPC
-    ├── editor/     # Milkdown 编辑器核心
-    ├── themes/     # CSS 主题 + 主题管理器
-    └── env.d.ts
-```
+### Export
+
+- **PDF**: `win.webContents.printToPDF()` — temporarily injects CSS to expand editor to full content height
+- **HTML**: Renderer constructs standalone HTML with embedded theme CSS from computed styles, main process writes to disk
+
+## Design Principles
+
+**"如非必要，勿增实体"** — Do not add entities unless necessary. Every new UI element, feature, or line of code must justify itself. Default answer is no.
+
+No toolbars, sidebars, status bars. UI is title bar + editor only.
+
+Core priorities in order: file hot update → WYSIWYG → themes → export.
+
+Things explicitly NOT done: file management, knowledge base, cloud sync, collaborative editing, note organization.
 
-## 开发规范
+## Development Notes
 
-- TypeScript 严格模式
-- 编辑器核心与 UI 解耦
-- 主题 CSS 与编辑器逻辑完全分离
-- 代码简洁，不过度设计
-- 每个新功能先问：这是必要的吗？
+- TypeScript strict mode (`tsconfig.json` base, 3 project references for main/preload/renderer)
+- Main process is a single file (`src/main/index.ts`, ~450 lines). Keep it that way — simplicity is the point.
+- Renderer has no framework. Milkdown (ProseMirror-based) is the entire UI.
+- Only 2 runtime dependencies: `@milkdown/kit` and `remark-breaks`
+- Security: `contextIsolation: true`, `nodeIntegration: false`, CSP header in index.html
+- Custom themes dir: `~/.colamd/themes/` — auto-created on startup

package.json

@@ -16,6 +16,7 @@
   "scripts": {
     "dev": "electron-vite dev",
     "build": "electron-vite build",
+    "typecheck": "tsc -p tsconfig.main.json --noEmit && tsc -p tsconfig.preload.json --noEmit && tsc -p tsconfig.renderer.json --noEmit",
     "preview": "electron-vite preview",
     "dist": "electron-vite build && electron-builder",
     "dist:mac": "electron-vite build && electron-builder --mac",