@geminilight/mindos 0.5.62 → 0.5.64

package/skills/plugin-core-builtin-migration/SKILL.md

@@ -0,0 +1,178 @@
+---
+name: plugin-core-builtin-migration
+description: >
+  将 MindOS 渲染器插件从“可选插件”升级为“完全内置能力（core builtin）”的通用流程。
+  当用户要求“把某插件改成内置/核心”“插件不应可关闭”“插件主程序化”或需要将旧入口迁移到
+  新主流程并保留兼容迁移能力时触发。
+---
+
+# Plugin Core Built-in Migration
+
+把单个插件改造成“稳定、默认、不可缺席”的产品能力，并沉淀可复用迁移步骤。
+
+适用场景：
+- 某插件已经成为核心体验（例如 TODO、CSV、配置、变更中心）
+- 旧插件入口要退役，但历史数据要可迁移
+- 需要避免“某页面漏 import 导致插件空列表”这类注册漂移
+
+---
+
+## 目标定义（先对齐）
+
+在本项目中，“完全内置”建议同时满足：
+
+1. **注册稳定**：渲染器注册有且仅有一个**客户端根入口**（推荐 `SidebarLayout` / `ShellLayout`）
+2. **默认可用**：`manifest.builtin = true`
+3. **不可禁用**（如需真正 core）：`manifest.core = true`（`registry` 会强制启用）
+4. **可观测可维护**：插件页、设置页、文档、测试一致
+5. **历史兼容**：旧入口数据有迁移方案，不丢内容
+6. **表层语义清晰**：区分“插件（可管理）”和“应用内建能力（不在插件面板展示）”
+
+---
+
+## 质量闸门（必走）
+
+每次执行本 Skill 时，默认同时应用以下质量视角（按顺序）：
+
+1. **产品设计视角**（`product-designer`）
+   - 检查信息层级、任务路径、主次操作、反馈时机
+   - 明确“主路径 3 步内可完成”，避免迁移后流程变长
+
+2. **UI/UX 视角**（`ui-design-patterns`）
+   - 检查按钮层级、交互一致性、空状态/错误状态/加载状态
+   - 禁止无意义下划线链接滥用；主 CTA 与次级 CTA 视觉层级明确
+   - 深色模式可读性必须通过（按钮文字对比、tag 对比、focus 可见）
+
+3. **实现质量视角**
+- 迁移逻辑幂等（重复执行不重复导入）
+- 注册机制单点化（禁止多处散落 import 造成漂移）
+- 避免仅服务端注册导致客户端 `0/0` 空列表
+   - 兼容代码失败不阻断主流程（best-effort + 可观测）
+
+4. **验证视角**
+   - 最少通过：core/API 回归测试 + lint
+   - UI 变更至少进行一次人工检查（亮色/暗色）
+
+若任一步不满足，迁移不得判定完成。
+
+---
+
+## 执行流程（通用）
+
+### Step 1) 盘点现状与边界
+
+先确认插件的四类事实来源：
+
+- 代码入口：`app/components/renderers/<plugin>/manifest.ts`
+- 注册入口：`app/lib/renderers/index.ts`（自动生成）
+- 使用入口：`resolveRenderer()` 调用链（如 `ViewPageClient`）
+- 展示入口：插件面板/设置页（优先使用 `getPluginRenderers()`）
+
+并回答：
+- 该插件是否应 **core**（不可关闭）？
+- 是否存在旧文件协议/旧入口（如 `Agent-Diff.md`）需要迁移？
+
+### Step 2) 升级插件声明
+
+在 manifest 中设置：
+
+- `builtin: true`（内置）
+- `core: true`（若要完全内置且不可关闭）
+- `appBuiltinFeature: true`（若是“应用内建能力”且不应出现在插件管理面板）
+- `match` 保持明确，避免误匹配
+
+如果插件要被替换/下线：
+- 删除旧 renderer 文件
+- 重新生成 `app/lib/renderers/index.ts`
+
+### Step 3) 统一注册机制（防漂移）
+
+必须收敛为单点初始化（客户端）：
+
+- 在客户端根组件（推荐 `SidebarLayout`）引入 `@/lib/renderers/index`
+- 移除其他页面/组件分散 import（避免重复与遗漏并存）
+
+验收标准：
+- 任意路由进入插件页，插件列表不应出现 `0/0` 的假空状态
+- 在“应用内建能力”模式下，被标记能力应从插件面板消失但渲染仍正常
+
+### Step 4) 历史兼容迁移（关键）
+
+如果旧插件依赖旧文件格式：
+
+1. 在核心数据层实现“懒迁移”：
+   - 首次读取时自动导入旧格式
+   - 写入新格式（结构化 JSON）
+2. 迁移后清理旧入口文件（防止双写和重复导入）
+3. 提供一次性脚本（离线/手动修复）：
+   - `scripts/migrate-*.js`
+
+### Step 5) UI/UX 对齐
+
+- 插件页：状态、可开关策略与 core 语义一致
+- 设置页：显示 builtin/core 标签逻辑一致
+- 若设为 `appBuiltinFeature`：在插件页/设置页/首页 Extensions 一致隐藏
+- 新主流程页面补齐筛选、空状态、加载、已读等基本交互
+
+### Step 6) 文档与知识同步
+
+至少同步：
+
+- `wiki/plugins/README.md`
+- `wiki/60-stage-plugins.md`
+- 相关 spec / pitfalls / refs（若行为模型发生变化）
+
+并记录迁移决策：
+- 为什么从插件入口转主程序能力
+- 旧入口如何兼容、何时清理
+
+### Step 7) 测试与回归
+
+最低测试集合：
+
+- core 层迁移测试（旧格式 -> 新格式）
+- API 层筛选/查询测试（若有 changes/feed 类接口）
+- UI 基础 smoke（插件列表非空、核心按钮可用）
+- 分类测试（`appBuiltinFeature` 能否正确从插件表层隐藏）
+
+推荐命令：
+
+```bash
+npm --prefix app run test -- __tests__/core/content-changes.test.ts __tests__/api/changes.test.ts
+```
+
+---
+
+## AgentDiff -> Built-in 的参考映射
+
+这次迁移可作为样板：
+
+- 旧：`Agent-Diff.md` + ```agent-diff``` renderer
+- 新：`.mindos/change-log.json` + `/api/changes` + `/changes` 主页面 + 全局提醒
+- 兼容：读取旧 block 自动导入；导入后删除 `Agent-Diff.md`
+- 治理：删除 `diff-viewer` renderer 与文档旧入口，保留结构化审计链路
+
+---
+
+## 常见坑位清单
+
+1. **只删插件没迁移旧数据** -> 用户历史丢失
+2. **注册入口分散/仅服务端注册** -> 客户端插件面板出现 `0/0`
+3. **文档未同步** -> 用户看到过时入口
+4. **core/builtin/appBuiltinFeature 语义混淆** -> 本应“应用内建”的能力仍出现在插件面板
+5. **迁移不幂等** -> 每次读取重复导入同一批旧数据
+
+---
+
+## 交付 Checklist（可复制）
+
+- [ ] manifest 层完成 builtin/core 定义
+- [ ] 如需“非插件化”，manifest 增加 `appBuiltinFeature: true`
+- [ ] 全局注册单点化（客户端根入口统一引入）
+- [ ] 旧入口迁移逻辑已实现且幂等
+- [ ] 迁移后旧文件可清理
+- [ ] 提供一次性迁移脚本
+- [ ] 插件页/设置页状态正确（含 appBuiltinFeature 隐藏策略）
+- [ ] 文档已同步更新
+- [ ] 测试通过
+

package/app/components/renderers/diff/DiffRenderer.tsx

@@ -1,311 +0,0 @@
-'use client';
-
-import { useMemo, useState } from 'react';
-import { useRouter } from 'next/navigation';
-import { GitCompare, CheckCircle2, XCircle, FileEdit, ChevronDown } from 'lucide-react';
-import { apiFetch } from '@/lib/api';
-import type { RendererContext } from '@/lib/renderers/registry';
-
-// ─── Diff entry format ────────────────────────────────────────────────────────
-// Agent writes diff entries as fenced blocks:
-//
-// ```agent-diff
-// { "ts": "2025-01-15T10:30:00Z", "path": "Profile/Identity.md",
-//   "tool": "mindos_write_file",
-//   "before": "...full old content...",
-//   "after": "...full new content..." }
-// ```
-
-interface DiffEntry {
-  ts: string;
-  path: string;
-  tool: string;
-  before: string;
-  after: string;
-}
-
-// ─── Parser ───────────────────────────────────────────────────────────────────
-
-function parseDiffs(content: string): DiffEntry[] {
-  const entries: DiffEntry[] = [];
-  const re = /```agent-diff\n([\s\S]*?)```/g;
-  let m: RegExpExecArray | null;
-  while ((m = re.exec(content)) !== null) {
-    try {
-      const entry = JSON.parse(m[1].trim()) as DiffEntry;
-      if (entry.path && entry.ts) entries.push(entry);
-    } catch { /* skip */ }
-  }
-  return entries.sort((a, b) => new Date(b.ts).getTime() - new Date(a.ts).getTime());
-}
-
-// ─── Diff algorithm (line-level Myers-light) ──────────────────────────────────
-
-type LineChange = { type: 'equal' | 'insert' | 'delete'; text: string };
-
-function diffLines(oldText: string, newText: string): LineChange[] {
-  const oldLines = oldText.split('\n');
-  const newLines = newText.split('\n');
-
-  // LCS-based diff (simple patience-like for short files)
-  const result: LineChange[] = [];
-
-  // Build LCS table
-  const m = oldLines.length, n = newLines.length;
-  // For large files, limit context
-  if (m > 500 || n > 500) {
-    // Truncate and just show a summary
-    const added = newLines.filter(l => !oldLines.includes(l)).length;
-    const removed = oldLines.filter(l => !newLines.includes(l)).length;
-    result.push({ type: 'delete', text: `[... ${removed} lines removed, ${added} lines added — file too large for line diff ...]` });
-    return result;
-  }
-
-  const dp: number[][] = Array.from({ length: m + 1 }, () => new Array(n + 1).fill(0));
-  for (let i = m - 1; i >= 0; i--) {
-    for (let j = n - 1; j >= 0; j--) {
-      if (oldLines[i] === newLines[j]) {
-        dp[i][j] = 1 + dp[i + 1][j + 1];
-      } else {
-        dp[i][j] = Math.max(dp[i + 1][j], dp[i][j + 1]);
-      }
-    }
-  }
-
-  let i = 0, j = 0;
-  while (i < m || j < n) {
-    if (i < m && j < n && oldLines[i] === newLines[j]) {
-      result.push({ type: 'equal', text: oldLines[i] });
-      i++; j++;
-    } else if (j < n && (i >= m || dp[i][j + 1] >= dp[i + 1][j])) {
-      result.push({ type: 'insert', text: newLines[j] });
-      j++;
-    } else {
-      result.push({ type: 'delete', text: oldLines[i] });
-      i++;
-    }
-  }
-
-  return result;
-}
-
-// Collapse long equal runs — show 3 context lines around changes
-function collapseContext(changes: LineChange[], ctx = 3): Array<LineChange | { type: 'collapse'; count: number }> {
-  type AnyLine = LineChange | { type: 'collapse'; count: number };
-  const result: AnyLine[] = [];
-  const changed = new Set<number>();
-
-  changes.forEach((c, i) => { if (c.type !== 'equal') { for (let k = Math.max(0, i - ctx); k <= Math.min(changes.length - 1, i + ctx); k++) changed.add(k); } });
-
-  let skipStart = -1;
-  for (let i = 0; i < changes.length; i++) {
-    if (changed.has(i)) {
-      if (skipStart !== -1) {
-        result.push({ type: 'collapse', count: i - skipStart });
-        skipStart = -1;
-      }
-      result.push(changes[i]);
-    } else {
-      if (skipStart === -1) skipStart = i;
-    }
-  }
-  if (skipStart !== -1) result.push({ type: 'collapse', count: changes.length - skipStart });
-
-  return result;
-}
-
-// ─── Helpers ──────────────────────────────────────────────────────────────────
-
-function relativeTs(ts: string): string {
-  const diff = Date.now() - new Date(ts).getTime();
-  const m = Math.floor(diff / 60000);
-  const h = Math.floor(diff / 3600000);
-  const d = Math.floor(diff / 86400000);
-  if (m < 1) return 'just now';
-  if (m < 60) return `${m}m ago`;
-  if (h < 24) return `${h}h ago`;
-  return `${d}d ago`;
-}
-
-function stats(changes: LineChange[]): { added: number; removed: number } {
-  return {
-    added: changes.filter(c => c.type === 'insert').length,
-    removed: changes.filter(c => c.type === 'delete').length,
-  };
-}
-
-// ─── Diff card ────────────────────────────────────────────────────────────────
-
-function DiffCard({ entry, saveAction, fullContent }: {
-  entry: DiffEntry;
-  saveAction: (c: string) => Promise<void>;
-  fullContent: string;
-}) {
-  const router = useRouter();
-  const [expanded, setExpanded] = useState(false);
-  const [approved, setApproved] = useState<boolean | null>(null);
-
-  const changes = useMemo(() => diffLines(entry.before, entry.after), [entry]);
-  const collapsed = useMemo(() => collapseContext(changes), [changes]);
-  const { added, removed } = stats(changes);
-
-  const toolShort = entry.tool.replace('mindos_', '');
-
-  async function handleApprove() {
-    setApproved(true);
-    // Mark this diff as approved by updating the block in the source file
-    const updated = fullContent.replace(
-      `"ts": "${entry.ts}", "path": "${entry.path}"`,
-      `"ts": "${entry.ts}", "path": "${entry.path}", "approved": true`,
-    );
-    await saveAction(updated);
-  }
-
-  async function handleReject() {
-    setApproved(false);
-    // Revert: write the "before" content back to the target file
-    await apiFetch('/api/file', {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ op: 'save_file', path: entry.path, content: entry.before }),
-    });
-    const updated = fullContent.replace(
-      `"ts": "${entry.ts}", "path": "${entry.path}"`,
-      `"ts": "${entry.ts}", "path": "${entry.path}", "approved": false, "reverted": true`,
-    );
-    await saveAction(updated);
-  }
-
-  return (
-    <div style={{ border: '1px solid var(--border)', borderRadius: 10, overflow: 'hidden', background: 'var(--card)', marginBottom: 10 }}>
-      {/* header */}
-      <div style={{ display: 'flex', alignItems: 'center', gap: 9, padding: '10px 14px', borderBottom: expanded ? '1px solid var(--border)' : 'none' }}>
-        <FileEdit size={13} style={{ color: 'var(--amber)', flexShrink: 0 }} />
-        <span
-          className="font-display"
-          style={{ fontSize: '0.78rem', color: 'var(--amber)', flex: 1, minWidth: 0, overflow: 'hidden', textOverflow: 'ellipsis', whiteSpace: 'nowrap', cursor: 'pointer' }}
-          onClick={() => router.push('/view/' + entry.path.split('/').map(encodeURIComponent).join('/'))}
-          title={entry.path}
-        >
-          {entry.path}
-        </span>
-
-        {/* diff stats */}
-        <span className="font-display" style={{ fontSize: '0.7rem', color: 'var(--success)', flexShrink: 0 }}>+{added}</span>
-        <span className="font-display" style={{ fontSize: '0.7rem', color: 'var(--error)', flexShrink: 0 }}>−{removed}</span>
-
-        {/* tool badge */}
-        <span className="font-display" style={{ fontSize: '0.65rem', padding: '1px 7px', borderRadius: 999, background: 'var(--muted)', color: 'var(--muted-foreground)', flexShrink: 0 }}>
-          {toolShort}
-        </span>
-
-        {/* timestamp */}
-        <span className="font-display" style={{ fontSize: '0.65rem', color: 'var(--muted-foreground)', opacity: 0.6, flexShrink: 0 }}>
-          {relativeTs(entry.ts)}
-        </span>
-
-        {/* approve/reject — only if not yet decided */}
-        {approved === null ? (
-          <>
-            <button
-              onClick={handleApprove}
-              title="Approve this change"
-              style={{ background: 'none', border: 'none', cursor: 'pointer', padding: 2, color: 'var(--success)', display: 'flex', alignItems: 'center' }}
-            >
-              <CheckCircle2 size={15} />
-            </button>
-            <button
-              onClick={handleReject}
-              title="Reject & revert this change"
-              style={{ background: 'none', border: 'none', cursor: 'pointer', padding: 2, color: 'var(--error)', display: 'flex', alignItems: 'center' }}
-            >
-              <XCircle size={15} />
-            </button>
-          </>
-        ) : (
-          <span className="font-display" style={{ fontSize: '0.68rem', color: approved ? 'var(--success)' : 'var(--error)' }}>
-            {approved ? '✓ approved' : '✕ reverted'}
-          </span>
-        )}
-
-        <button
-          onClick={() => setExpanded(v => !v)}
-          style={{ background: 'none', border: 'none', cursor: 'pointer', padding: 2, color: 'var(--muted-foreground)', display: 'flex', alignItems: 'center' }}
-        >
-          <ChevronDown size={13} style={{ transform: expanded ? 'rotate(180deg)' : 'none', transition: 'transform .15s' }} />
-        </button>
-      </div>
-
-      {/* diff view */}
-      {expanded && (
-        <div className="font-display" style={{ fontSize: '0.72rem', lineHeight: 1.5, overflowX: 'auto' }}>
-          {collapsed.map((line, i) => {
-            if (line.type === 'collapse') {
-              return (
-                <div key={i} style={{ padding: '2px 14px', background: 'var(--muted)', color: 'var(--muted-foreground)', opacity: 0.6, fontSize: '0.65rem' }}>
-                  ··· {line.count} unchanged lines ···
-                </div>
-              );
-            }
-            const bg =
-              line.type === 'insert' ? 'rgba(122,173,128,0.12)' :
-              line.type === 'delete' ? 'rgba(200,80,80,0.10)' :
-              'transparent';
-            const color =
-              line.type === 'insert' ? 'var(--success)' :
-              line.type === 'delete' ? 'var(--error)' :
-              'var(--muted-foreground)';
-            const prefix =
-              line.type === 'insert' ? '+' :
-              line.type === 'delete' ? '−' :
-              ' ';
-            return (
-              <div key={i} style={{ display: 'flex', background: bg, borderLeft: line.type !== 'equal' ? `2px solid ${color}` : '2px solid transparent' }}>
-                <span style={{ width: 20, textAlign: 'center', color, opacity: 0.8, flexShrink: 0, userSelect: 'none' }}>{prefix}</span>
-                <span style={{ padding: '1px 8px 1px 0', color: line.type === 'equal' ? 'var(--muted-foreground)' : color, whiteSpace: 'pre', flex: 1 }}>
-                  {line.text || ' '}
-                </span>
-              </div>
-            );
-          })}
-        </div>
-      )}
-    </div>
-  );
-}
-
-// ─── Main renderer ────────────────────────────────────────────────────────────
-
-export function DiffRenderer({ content, saveAction }: RendererContext) {
-  const entries = useMemo(() => parseDiffs(content), [content]);
-
-  if (entries.length === 0) {
-    return (
-      <div className="font-display" style={{ padding: '3rem 1rem', textAlign: 'center', color: 'var(--muted-foreground)', fontSize: 12 }}>
-        <GitCompare size={28} style={{ margin: '0 auto 10px', opacity: 0.3 }} />
-        <p>No agent diffs logged yet.</p>
-        <p style={{ marginTop: 6, opacity: 0.6, fontSize: 11 }}>
-          Agent writes appear here as <code style={{ background: 'var(--muted)', padding: '1px 5px', borderRadius: 4 }}>```agent-diff</code> blocks.
-        </p>
-      </div>
-    );
-  }
-
-  const totalAdded = entries.reduce((acc, e) => acc + diffLines(e.before, e.after).filter(c => c.type === 'insert').length, 0);
-  const totalRemoved = entries.reduce((acc, e) => acc + diffLines(e.before, e.after).filter(c => c.type === 'delete').length, 0);
-
-  return (
-    <div style={{ maxWidth: 800, margin: '0 auto', padding: '1.5rem 0' }}>
-      {/* stats bar */}
-      <div className="font-display" style={{ display: 'flex', alignItems: 'center', gap: 12, marginBottom: '1.2rem', fontSize: 11, color: 'var(--muted-foreground)' }}>
-        <span>{entries.length} change{entries.length !== 1 ? 's' : ''}</span>
-        <span style={{ color: 'var(--success)' }}>+{totalAdded}</span>
-        <span style={{ color: 'var(--error)' }}>−{totalRemoved}</span>
-      </div>
-
-      {entries.map((entry, i) => (
-        <DiffCard key={i} entry={entry} saveAction={saveAction} fullContent={content} />
-      ))}
-    </div>
-  );
-}

package/app/components/renderers/diff/manifest.ts

@@ -1,14 +0,0 @@
-import type { RendererDefinition } from '@/lib/renderers/registry';
-
-export const manifest: RendererDefinition = {
-  id: 'diff-viewer',
-  name: 'Diff Viewer',
-  description: 'Visualizes agent file changes as a side-by-side diff timeline. Auto-activates on Agent-Diff.md with embedded agent-diff blocks.',
-  author: 'MindOS',
-  icon: '📝',
-  tags: ['diff', 'agent', 'changes', 'history'],
-  builtin: true,
-  entryPath: 'Agent-Diff.md',
-  match: ({ filePath }) => /\bAgent-Diff\b.*\.md$/i.test(filePath),
-  load: () => import('./DiffRenderer').then(m => ({ default: m.DiffRenderer })),
-};