rc-69f3895b-20c9 2026.04.30 25 KB

用网页呈现 Meridian/Vyane 研究报告的产品方案

原始 research campaign 输出，来自 may1 facade yi app product design research。这页保留报告结构和运行痕迹，正式文章会在写作区重写。

用网页呈现 Meridian/Vyane 研究报告的产品方案

Campaign: rc-69f3895b-20c9 · may1-facade-yi-app-product-design-research Topic: t03 — 分析现有 docs/research/campaigns、历史报告、Linear/Discord/Session 数据，设计可先在 Facade 中实现的 research archive/gallery 页面写作时间：2026-05-01 Status: 研究草稿（待 Maple 审阅）

0. 一句话结论

Facade 已有 6 个 content collection 和成熟的页面模式，新增一个 research collection + /research 路由即可把现有 119 份研究报告呈现为可浏览、可筛选的网页归档，第一版只需 5 个文件改动 + 1 个数据转换脚本。

1. 现状分析

1.1 研究报告资产盘点

来源	数量	组织方式	当前可访问性
`docs/research/autonomous-2026-04-09/`	102 份	按主题 A-Q 分组，INDEX.md + SUMMARY.md 做索引	只能在编辑器/终端里读
`docs/research/campaigns/`	7 个 campaign，约 10 份报告	`rc-{uuid}-{slug}/t{N}-{title}.md`	同上
`docs/research/_archive/`	若干已归档	平铺	同上
独立报告	2 份（`linear-best-practices.md` 等）	散落在 `docs/research/` 根	同上

总计 ~119 份 Markdown 文件，涵盖 Vyane daemon 架构、安全、运维、CLI 协议、Memory、Agent 协作、成本、前端、方法论等 17 个主题。

1.2 报告元数据现状

报告没有 YAML frontmatter，元数据嵌在 blockquote 中：

# MER-229 · Idea 裂变与 Session 路由 — 阶段方案

> Campaign: `rc-69f36007-0ec9` · meridian-runtime-architecture-research
> Topic: t01 — 结合当前 Vyane / Yi daemon...
> 写作时间：2026-04-30
> **Status**: 研究草稿（待 Maple 审阅）

可提取的字段：Campaign ID、Topic 编号、标题、日期、状态。 INDEX.md 额外提供：主题分组（A-Q）、价值评估（high/medium/archive）、一句话摘要。

1.3 campaign 运行时数据

data/research-campaigns/state.json 记录了每个 campaign 的结构化元数据：

{
  "id": "rc-69f36007-0ec9",
  "name": "Meridian runtime architecture research",
  "status": "succeeded",
  "model": "claude-opus-4-6",
  "topics": [{
    "id": "t01",
    "title": "MER-229 Idea 裂变与 Session 路由...",
    "status": "succeeded",
    "output_path": "docs/research/campaigns/rc-.../t01-....md",
    "last_summary": "报告已写入...488 行...",
    "started_at": 1777557512.479923,
    "finished_at": 1777558073.649078
  }]
}

这是比 blockquote 元数据更丰富的结构化数据源，包含运行时长、模型、摘要等。

1.4 Facade 现有架构

维度	现状
框架	Astro 6.1.2 + Tailwind 3.4 + MDX
内容管理	Astro Content Collections，Zod schema，文件驱动
现有集合	writing / moments / notes / projects / gallery / radar
路由	`/writing/[slug]`、`/notes/[slug]` 等标准模式
设计系统	3 主题（ink/edge/press），CSS 变量 + utility class
组件库	ArticleCard / NoteCard / TableOfContents / SeriesNav / Lightbox 等

关键发现：Facade 的内容系统专为 Astro Content Collections 设计，新增一个 collection 的成本极低——只需在 content.config.ts 加一个 schema，建对应的 src/content/research/ 目录和页面文件。

1.5 关联数据系统

系统	数据	连接方式
Linear	MER-xxx issue 状态、描述、评论	报告标题中嵌入 issue key，`tools/linear/` 脚本可查
Discord	campaign 通知 channel	state.json 中的 `channel_id`
Session Index	CC/Codex session 记录	`related_tasks` 字段提取 MER-xxx 关联
Memory Index	SQLite FTS + embedding	source 字段标记 “research” 来源

第一版不需要实时对接这些系统——报告文件本身已是完整的独立内容。这些关联留作后续增强。

2. 产品设计

2.1 核心定位

Research Archive —— Maple 个人的研究成果归档和回溯工具。

不是给外部读者的博客，是给自己（和 AI agent）快速找到"之前想过什么、结论是什么"的工具。这决定了几个设计方向：

信息密度 > 美观排版
筛选/搜索 > 社交分享
元数据完整 > 摘要精简
支持长文（1500-2300 行）的舒适阅读 > 卡片化截断

2.2 数据模型

新增 research content collection，schema 设计：

const research = defineCollection({
  type: 'content',
  schema: meta.extend({
    // 归属
    campaign: z.string().optional(),         // campaign ID, e.g. "rc-69f36007-0ec9"
    campaignName: z.string().optional(),      // 可读名称
    topicId: z.string().optional(),           // "t01", "t02"...

    // 分类
    section: z.enum([
      'architecture',    // A. 核心架构
      'security',        // B. 安全加固
      'operations',      // C. 运维
      'cli',             // D. CLI 协议
      'memory',          // E. 记忆 / 知识
      'collaboration',   // F. Agent 协作
      'cost',            // G. 成本监控
      'audit',           // H. 审计
      'frontend',        // I. 前端 / 交互
      'discord',         // J. Discord / Yi
      'methodology',     // K. 方法论
      'compliance',      // L. 合规
      'ecosystem',       // M. 外部生态
      'growth',          // N. 个人成长
      'product',         // O. 产品设计
      'data',            // P. 数据
      'misc',            // Q. 其他
    ]).default('misc'),

    // 状态
    status: z.enum([
      'draft',           // 研究草稿
      'reviewed',        // 已审阅
      'archived',        // 已归档 / 被新版替代
    ]).default('draft'),
    value: z.enum(['high', 'medium', 'archive']).default('medium'),

    // 关联
    linearIssues: z.array(z.string()).default([]),   // ["MER-229", "MER-214"]
    model: z.string().optional(),                     // "claude-opus-4-6"
    sources: z.array(z.object({
      title: z.string(),
      url: z.string(),
    })).default([]),

    // 阅读辅助
    readingTime: z.string().optional(),
    tldr: z.string().optional(),                      // 一句话结论
  }),
});

设计决策说明：

section 枚举直接复用 INDEX.md 的 A-Q 分组，这是 Maple 已经验证过的分类体系
value 字段保留 INDEX.md 的三级评估（high/medium/archive），用于筛选和排序
linearIssues 是字符串数组而不是对象，因为当前不需要实时拉取 issue 状态
tldr 从报告的"0. 一句话结论"段落提取，在列表页显示时有极高价值
继承 meta 基础字段（title, description, pubDate, tags, draft, cover 等），保持与其他 collection 的一致性

2.3 路由设计

/research/                   → 归档首页（列表 + 筛选）
/research/[slug]             → 单篇报告详情页

不做 campaign 独立路由（如 /research/campaigns/[id]）——campaign 作为筛选维度出现在首页即可，不值得额外维护一个页面。如果后续 campaign 数量显著增长，再加不迟。

slug 规则：文件名去掉 .md 后缀，与其他 collection 一致。长文件名（如 t01-mer-229-idea-裂变与-session-路由-...）在 URL 中不美观但可接受，因为这是个人工具不是公开博客。

2.4 首页设计（`/research/index.astro`）

布局结构

┌──────────────────────────────────────────────────────────┐
│  Research                                                │
│  section-kicker: "Research Archive"                      │
│  section-title: "研究归档"                                │
│  描述: "Meridian/Vyane 研究报告，每一份都是从代码和证据出发的判断。"  │
│  统计: "共 X 份报告"                                      │
├──────────────────────────────────────────────────────────┤
│                                                          │
│  ┌─ 筛选栏 ─────────────────────────────────────────┐    │
│  │ [全部] [架构] [安全] [运维] [CLI] [记忆] ...       │    │
│  │                                                   │    │
│  │ 价值: [全部] [high] [medium]  状态: [全部] [draft] │    │
│  └───────────────────────────────────────────────────┘    │
│                                                          │
│  ┌─ 报告卡片（full-width 列表，非网格）──────────────┐    │
│  │ ■ MER-229 · Idea 裂变与 Session 路由 — 阶段方案   │    │
│  │   architecture · high · 2026.04.30                │    │
│  │   MER-229 不缺新组件，缺的是串成闭环...            │    │
│  │                                         claude-opus-4-6 │
│  ├───────────────────────────────────────────────────┤    │
│  │ ■ Daemon Security Model                           │    │
│  │   security · high · 2026.04.09                    │    │
│  │   3 个 P0 漏洞（webhook/injection/bypass）        │    │
│  └───────────────────────────────────────────────────┘    │
│                                                          │
└──────────────────────────────────────────────────────────┘

关键设计选择：

Full-width 列表而非网格：研究报告标题长、元数据多，网格卡片放不下。参考 Radar 的 full-width 模式但信息密度更高
Section 筛选用 pill 标签：静态过滤，Astro 不需要客户端 JS——用 URL query param 或直接静态生成每个 section 的页面
TL;DR 作为摘要：比自动截断正文有意义得多
默认按日期降序：最新的报告最先看到，但可以切换为按 section 分组

筛选实现方案

推荐：静态分组 + 客户端 toggle

Astro 静态生成不支持服务端 query param，两个可行路径：

方案 A（推荐）：首页渲染所有报告，用少量 JS 做客户端 display: none 过滤。报告数量 <200，DOM 操作零延迟
方案 B：为每个 section 生成独立页面（/research/architecture/、/research/security/）。SEO 友好但维护成本高，对个人工具没必要

第一版用方案 A，约 20 行 vanilla JS。

2.5 详情页设计（`/research/[slug].astro`）

研究报告 1500-2300 行，阅读体验是核心挑战。

布局

┌──────────────────────────────────────────────────────────┐
│  ← 返回归档                                              │
│                                                          │
│  section-kicker: "Architecture · Research"               │
│  # MER-229 · Idea 裂变与 Session 路由 — 阶段方案         │
│                                                          │
│  ┌─ 元数据栏 ────────────────────────────────────────┐   │
│  │ 📅 2026.04.30  ⏱ 约 15 分钟  🏷 MER-229          │   │
│  │ Campaign: Meridian runtime architecture research   │   │
│  │ 模型: claude-opus-4-6  状态: 研究草稿  价值: high  │   │
│  └────────────────────────────────────────────────────┘   │
│                                                          │
│  ┌─ TL;DR ───────────────────────────────────────────┐   │
│  │ MER-229 不缺新组件，缺的是把现有组件串成闭环...     │   │
│  └────────────────────────────────────────────────────┘   │
│                                                          │
│  ┌─────────────────────────────┬── ToC sidebar ──────┐   │
│  │                             │ 0. 一句话结论       │   │
│  │    正文（prose-facade）      │ 1. 现状分析        │   │
│  │                             │ 2. 设计方案        │   │
│  │    支持：                    │ 3. 风险           │   │
│  │    - 代码块高亮              │ 4. 推荐后续       │   │
│  │    - 表格                   │                    │   │
│  │    - 目录锚点               │                    │   │
│  │                             │                    │   │
│  └─────────────────────────────┴────────────────────┘   │
│                                                          │
│  ┌─ 关联报告 ────────────────────────────────────────┐   │
│  │ 同 campaign 的其他报告：t02 · 跨 session 通信...   │   │
│  │                         t03 · 自主学习与记忆层...   │   │
│  └────────────────────────────────────────────────────┘   │
│                                                          │
└──────────────────────────────────────────────────────────┘

关键设计选择：

ToC sidebar：复用现有 TableOfContents.astro 组件，对 1500+ 行文档是必需品
TL;DR 突出显示：用 surface-panel 样式单独成块，让读者 5 秒内判断要不要深入
元数据栏：一行式，不占过多空间。Linear issue key 可以是纯文本（不做链接跳转，因为 Linear 需要认证）
关联报告：同 campaign 的报告自动列出，不需要手动维护关联
阅读时间：按中文字数估算（约 300 字/分钟），在数据转换时计算

2.6 导航集成

在 site.ts 的 nav 数组中插入：

nav: [
  { label: '写作', href: '/writing' },
  { label: '想法', href: '/moments' },
  { label: '笔记', href: '/notes' },
  { label: '研究', href: '/research' },   // ← 新增
  { label: '项目', href: '/projects' },
  { label: '画廊', href: '/gallery' },
  { label: '雷达', href: '/radar' },
  { label: '关于', href: '/about' },
]

放在"笔记"和"项目"之间——研究报告比笔记更重、比项目更偏调研。

3. 数据转换方案

现有报告没有 YAML frontmatter，需要一个一次性脚本把 blockquote 元数据 + INDEX.md 信息转为 frontmatter。

3.1 转换脚本设计

输入源：
├── docs/research/autonomous-2026-04-09/*.md + INDEX.md
├── docs/research/campaigns/rc-*/t*.md
└── data/research-campaigns/state.json

输出目标：
└── prototypes/facades/main/src/content/research/*.md
    （带 YAML frontmatter 的副本）

脚本职责：

遍历所有研究报告文件
从 blockquote 中提取：标题、Campaign ID、Topic、日期、状态
从 INDEX.md 匹配：section 分组、value 评估、一句话摘要
从 state.json 补充：模型名、运行时长、摘要
从标题正则提取：Linear issue key（/\b(MER-\d+)\b/g）
计算阅读时间：Math.ceil(charCount / 300) 分钟
生成 YAML frontmatter 并 prepend 到文件内容
写入 src/content/research/ 目录，文件名做 slug 化处理

3.2 Frontmatter 输出示例

---
title: "MER-229 · Idea 裂变与 Session 路由 — 阶段方案"
description: "设计个人优先的 idea capture、session routing、任务分发机制"
pubDate: 2026-04-30
tags: ["idea-capture", "session-routing", "vyane-daemon"]
draft: false
campaign: "rc-69f36007-0ec9"
campaignName: "Meridian runtime architecture research"
topicId: "t01"
section: "architecture"
status: "draft"
value: "high"
linearIssues: ["MER-229"]
model: "claude-opus-4-6"
readingTime: "约 15 分钟"
tldr: "MER-229 不缺新组件，缺的是把现有组件串成 capture → triage → route 闭环。"
---

3.3 文件名 slug 化

原始文件名	slug
`t01-mer-229-idea-裂变与-session-路由-...md`	`mer-229-idea-session-routing`
`daemon-security-model.md`	`daemon-security-model`
`adr003-deepening.md`	`adr003-deepening`

规则：

Campaign 报告：去掉 t{N}- 前缀，提取核心关键词，中文转拼音或保留（Astro 支持 Unicode slug）
归档报告：直接用原文件名

建议第一版保留中文 slug——Astro 完整支持，且这是个人工具，不需要 SEO 友好 URL。

3.4 增量同步

第一版不做自动同步。新报告产出后手动运行转换脚本。后续可以：

在 campaign runner 完成时自动触发转换
或把 Facade 的 content 目录 symlink 到 research 目录（需要 Astro loader 适配 blockquote 元数据）

4. 第一版开发任务

按依赖顺序排列，预估总工作量 1-2 个 CC session（约 2-4 小时）。

Task 1: 数据转换脚本

改动：新建 tools/research-to-facade.ts（或 .py）

读取所有研究报告
解析 blockquote 元数据 + INDEX.md + state.json
生成带 frontmatter 的 Markdown 文件到 src/content/research/
输出转换统计（成功/跳过/错误数量）

验收：运行脚本后 src/content/research/ 下有 ~100 个带 frontmatter 的 .md 文件。

Task 2: Schema 定义

改动：编辑 src/content.config.ts

新增 research collection 定义（如 2.2 节所述）
在 collections export 中注册

验收：astro check 或 astro build 不报 schema 错误。

Task 3: 工具函数

改动：编辑 src/lib/content.ts

新增 SECTION_LABELS 映射（如 architecture: '核心架构'）
新增 VALUE_LABELS 映射（high: '高价值' 等）
新增 RESEARCH_STATUS_LABELS 映射

验收：函数可导入，类型正确。

Task 4: 列表页

改动：新建 src/pages/research/index.astro

获取 research collection，排除 draft
渲染筛选 pill（section 维度）
渲染 full-width 报告列表（ResearchCard 组件）
客户端 JS 做 section/value 筛选

关联新建：src/components/ResearchCard.astro

显示：标题、section pill、value pill、日期、TL;DR 摘要、Linear issue tags、模型名

验收：/research 页面正确显示所有报告，筛选功能正常。

Task 5: 详情页

改动：新建 src/pages/research/[slug].astro

渲染完整报告内容（prose-facade 样式）
元数据栏（日期、阅读时间、Linear issues、campaign、模型、状态、价值）
TL;DR 高亮块
ToC sidebar（复用 TableOfContents 组件）
底部关联报告（同 campaign 的其他报告）

验收：点击列表页任意报告可进入详情页，ToC 锚点跳转正常，长文阅读体验流畅。

Task 6: 导航注册

改动：编辑 src/data/site.ts

在 nav 数组中插入 { label: '研究', href: '/research' }

验收：顶部导航出现"研究"入口，点击跳转正确。

任务依赖图

Task 1 (数据转换) ──→ Task 2 (Schema) ──→ Task 3 (工具函数)
                                              │
                                     ┌────────┴────────┐
                                     ▼                  ▼
                              Task 4 (列表页)     Task 5 (详情页)
                                     │                  │
                                     └────────┬─────────┘
                                              ▼
                                       Task 6 (导航)

Task 1 和 Task 2 可以并行做，Task 4 和 Task 5 也可以并行。

5. Evidence 汇总

证据	来源	置信度
研究报告 119 份，全部 Markdown	`find docs/research -name "*.md"` 直接计数	High
无 YAML frontmatter，元数据在 blockquote 中	读取 4 份报告内容确认	High
INDEX.md 有 A-Q 分组和三级价值评估	直接读取 INDEX.md	High
state.json 包含 campaign 结构化元数据	直接读取 state.json	High
Facade 用 Astro 6.1 + Content Collections	读取 package.json, content.config.ts	High
现有 6 个 collection 的 schema 模式	读取 content.config.ts 全文	High
报告长度 1500-2300 行	读取 3 份完整报告	High
客户端筛选方案可行（<200 DOM 节点）	报告总数 ~119，推断	Medium-High

6. Uncertainty

6.1 已知不确定

中文 slug 兼容性：Astro 文档说支持 Unicode slug，但未在 Facade 中实测。如果有问题，回退方案是用英文 slug + 映射表
报告正文与 frontmatter 的冲突：部分报告开头的 blockquote 元数据转为 frontmatter 后，正文第一段可能需要手动调整
阅读时间估算精度：中文 300 字/分钟是通用估算，技术报告含大量代码块，实际阅读时间可能更长
INDEX.md 覆盖率：INDEX.md 覆盖了 autonomous-2026-04-09 的 102 份，campaign 报告需要从 state.json 补充

6.2 不在第一版范围内

全文搜索（可后续集成 Pagefind）
Linear issue 实时状态展示（需要 API 认证）
自动同步（campaign runner 产出 → Facade 内容）
报告间的引用关系图
阅读进度持久化

7. 推荐后续工作

短期（第一版完成后）

集成 Pagefind：Astro 有官方 Pagefind 集成，可为 119 份报告提供毫秒级全文搜索
阅读进度指示器：对 1500+ 行文档，一个顶部进度条极大改善阅读体验
报告统计页面：按 section / 月份 / campaign 展示产出统计，帮助 Maple 回顾研究密度

中期

自动同步 pipeline：campaign runner 完成后自动触发转换脚本，新报告即时上线
Linear issue 侧边栏：在详情页展示关联 issue 的标题和状态（需要 build-time API 调用）
系列关联：利用 campaign 维度自动生成"系列导航"（类似 writing 的 SeriesNav）

长期

知识图谱可视化：报告之间的引用关系、共同 Linear issue、共同 section 形成网络图
AI 问答层：基于 Memory Index 的 embedding 搜索，“上次关于 daemon security 的结论是什么”

附录 A：现有 Facade Collection 对比

Collection	类型	特有字段	列表页布局	详情页
writing	content	series, category, readingTime	2 列网格	prose + ToC
moments	content	images, video, mood	时间线	无独立页
notes	content	topic, voice, bookTitle	按 topic 分组	prose
projects	content	status, year, stack, links	网格	prose
gallery	content	type, items	网格 + lightbox	lightbox
radar	data(JSON)	url, source, rating, comment	full-width 列表	无独立页
research (新)	content	campaign, section, value, linearIssues, tldr	full-width 列表	prose + ToC

Research 最接近 Writing（详情页） 和 Radar（列表页） 的混合体。

附录 B：Section 分类完整映射

代码	中文标签	INDEX.md 对应	报告数量（估）
architecture	核心架构	A	19
security	安全加固	B	5
operations	运维	C	9
cli	CLI 协议	D	13
memory	记忆 / 知识	E	9
collaboration	Agent 协作	F	2
cost	成本监控	G	4
audit	审计	H	4
frontend	前端 / 交互	I	3
discord	Discord / Yi	J	2
methodology	方法论	K	8
compliance	合规	L	2
ecosystem	外部生态	M	4
growth	个人成长	N	4+
product	产品设计	— (新增)	campaign 报告
data	数据	— (新增)	campaign 报告
misc	其他	Q	若干

用网页呈现 Meridian/Vyane 研究报告的产品方案

0. 一句话结论

1. 现状分析

1.1 研究报告资产盘点

1.2 报告元数据现状

1.3 campaign 运行时数据

1.4 Facade 现有架构

1.5 关联数据系统

2. 产品设计

2.1 核心定位

2.2 数据模型

2.3 路由设计

2.4 首页设计（/research/index.astro）

布局结构

筛选实现方案

2.5 详情页设计（/research/[slug].astro）

布局

2.6 导航集成

3. 数据转换方案

3.1 转换脚本设计

3.2 Frontmatter 输出示例

3.3 文件名 slug 化

3.4 增量同步

4. 第一版开发任务

Task 1: 数据转换脚本

Task 2: Schema 定义

Task 3: 工具函数

Task 4: 列表页

Task 5: 详情页

Task 6: 导航注册

任务依赖图

5. Evidence 汇总

6. Uncertainty

6.1 已知不确定

6.2 不在第一版范围内

7. 推荐后续工作

短期（第一版完成后）

中期

长期

附录 A：现有 Facade Collection 对比

附录 B：Section 分类完整映射

2.4 首页设计（`/research/index.astro`）

2.5 详情页设计（`/research/[slug].astro`）