Alan Pipeline

Research Pipeline

用 card 和 run 两种原子单元驱动研究项目。

• Card — 一张说一件事的知识卡片，按类别存放，有结构性编号
• Run — 一个可执行的行动单元（跑实验 / 写章节 / 验证假设）

.pipeline/
  cards/
    method/<slug>.md       # 方法论 cards (p0, p1)
    exp/<slug>.md          # 实验与结果 cards (p0, p1)
    framing/<slug>.md      # 叙事框架 cards (p0, p1)
    archived/<slug>.md     # 归档 cards (p2，不分类别)
  runs/<slug>.yaml         # 执行单元，纯 YAML

Card 操作

Card 是普通 Markdown 文件，用 read/write/edit 直接操作。

创建 card

write .pipeline/cards/{category}/{slug}.md

文件结构：

---
category: method           # method | exp | framing
priority: p0               # p0 | p1 | p2
tags: [keyword1, keyword2]
links:
  - cards/method/other-card
  - runs/some-run
---

# 标题

1-3 句摘要。

## 1. 第一个要点
...

## 2. 第二个要点
...

完整 schema 和示例见 references/card-schema.md。

Section 编号与跨卡片引用

每个 ## section 必须有序号：## 1.、## 2.、…

跨卡片引用格式：{category}/{slug}#{section}

method/debiased-sorting#2    →  method/debiased-sorting.md 的 ## 2.
exp/bleu-baseline#1          →  exp/bleu-baseline.md 的 ## 1.

当用户说「改 method/debiased-sorting#2」，直接定位到对应文件的 ## 2. section。

Priority 分级

变更：p1→p0（多次验证后升级）、p1→p2 / p0→p2（移入 archived/，写明原因）。

归档（降为 p2）

mkdir -p .pipeline/cards/archived
mv .pipeline/cards/{category}/{slug}.md .pipeline/cards/archived/{slug}.md
# edit frontmatter: priority: p2
# body 末尾加归档原因

归档后不保留原类别目录，统一放 archived/。

修改规则

Slug 是身份。Slug 不变 = 同一张 card。

单一事实原则

同一事实只存在于一张 card 中。 创建新 card 前：

1. 检查现有 active cards 是否已覆盖相关内容
2. 如有重叠 → 提取重叠部分为独立小 card，原 card 改用引用：见 method/debiased-sorting#1
3. 不允许两张 card 说同一件事

维护

p0 和 p1 cards 必须保持不过时。 每当创建或修改 card 时：

1. 检查 links 中引用的 active cards 是否因新信息过时
2. 核心主张被取代 → 降为 p2，移入 archived/
3. 只需补充 → 原地修改（新增 section 或更新已有 section）

查找 card

ls .pipeline/cards/method/                                # method cards
ls .pipeline/cards/exp/                                   # exp cards
grep -l "priority: p0" .pipeline/cards/method/*.md        # p0 method cards
grep -l "debiasing" .pipeline/cards/**/*.md               # by tag
grep -rn "method/debiased-sorting#2" .pipeline/cards/     # who references this section

Run 操作

Run 通过 5 个专用工具管理（由 pi-alan 扩展提供）：

创建 run

RunCreate({
  slug: "verify-debiased-k1",
  description: "验证 method/debiased-sorting#2 的假设：debiased k=1 在 SynthWiki-32k 上匹配 k=5 精度",
  checker: "- 3 seeds 全部完成\n- BLEU mean±std 已记录\n- 产出 exp card",
  context: "方法见 method/debiased-sorting\n数据集：SynthWiki-32k",
  blocked_by: ["runs/setup-env"]
})

description = 为什么 + 大致怎么做（不可变）。可用 card 路径引用。 checker = done-when，不是 win-condition。即使假设被证伪，只要交付物齐全就是 done。

Log 记录

observation/decision 是任务级执行记录。 项目级发现和决策应升级为 card。

记录产出（provenance）

RunUpdate({
  slug: "verify-k1",
  add_result_of: ["cards/exp/bleu-baseline"],
  log_entry: { type: "output", detail: "产出 exp/bleu-baseline" }
})

完成 / 取消 / 取代

RunUpdate({ slug: "verify-k1", status: "done" })
RunUpdate({ slug: "old-run", status: "cancelled" })
RunUpdate({ slug: "old-run", status: "superseded" })

Run 完整字段见 references/run-schema.md。

Card 与 Run 的关系

method card ──── 定义方法 ────→ run（验证实验）
                                  │
                                  ▼ 产出 (result_of)
                               exp card
                                  │
                                  ▼ 支撑
framing card ←── 引用 exp card 的结果构建叙事
      │
      ▼ 驱动
   下一个 run

规则

• 一事一卡：一张 card 只说一件事。有重叠就拆分 + 引用。
• 不捏造：数据、引用不编造。不确定就标 TBD。
• 不重复：card 之间用路径引用（见 method/debiased-sorting#2），不复制内容。
• 不删除：不要的 card 降为 p2 移入 archived/，不要的 run 标 cancelled/superseded。
• Log 不沉淀知识：任务级记录留 log；项目级升级为 card。
• Active 不过时：新建/修改 card 时检查关联 cards，过时就降级。

Git 维护

每次修改 card（创建、编辑、归档）后，立即提交：

git add .pipeline/cards/
git commit -m "pipeline: update cards (<列出变更的 slug>)"

保持 .pipeline/cards/ 下没有未提交的变更。