| name | alan-pipeline |
| description | 管理研究项目的 card（知识单元）和 run（执行单元）。当用户需要记录实验发现、提出假设、做出决策、创建/执行研究任务时使用。适用于 .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 分级
| 级别 | 含义 | 目录 |
|---|
p0 | 核心事实——已验证，长期有效，其他 card 依赖它 | cards/{category}/ |
p1 | 中间状态——合理但脆弱，待验证或可能修改 | cards/{category}/ |
p2 | 归档——被取代、被证伪、不再相关 | cards/archived/ |
变更：p1→p0（多次验证后升级）、p1→p2 / p0→p2（移入 archived/，写明原因）。
归档（降为 p2）
mkdir -p .pipeline/cards/archived
mv .pipeline/cards/{category}/{slug}.md .pipeline/cards/archived/{slug}.md
归档后不保留原类别目录，统一放 archived/。
修改规则
Slug 是身份。Slug 不变 = 同一张 card。
| 操作 | 允许？ |
|---|
| 改错别字、补格式 | ✅ |
| 补充/修改 section 内容 | ✅ |
| 新增 section（末尾追加新序号） | ✅ |
| 改变核心命题/主张 | ❌ 新建 card，旧 card 降为 p2 |
| 改变 category | ❌ 新建 card，mv 到对应目录 |
单一事实原则
同一事实只存在于一张 card 中。 创建新 card 前：
- 检查现有 active cards 是否已覆盖相关内容
- 如有重叠 → 提取重叠部分为独立小 card，原 card 改用引用：
见 method/debiased-sorting#1
- 不允许两张 card 说同一件事
维护
p0 和 p1 cards 必须保持不过时。 每当创建或修改 card 时：
- 检查 links 中引用的 active cards 是否因新信息过时
- 核心主张被取代 → 降为 p2，移入 archived/
- 只需补充 → 原地修改（新增 section 或更新已有 section）
查找 card
ls .pipeline/cards/method/
ls .pipeline/cards/exp/
grep -l "priority: p0" .pipeline/cards/method/*.md
grep -l "debiasing" .pipeline/cards/**/*.md
grep -rn "method/debiased-sorting#2" .pipeline/cards/
Run 操作
Run 通过 5 个专用工具管理（由 pi-alan 扩展提供）：
| 工具 | 用途 |
|---|
RunCreate | 创建 run：slug、description、checker 等 |
RunList | 列出所有 run，可按 status 过滤 |
RunGet | 查看 run 完整详情 |
RunUpdate | 追加 log、改 status/context/tags、加 blocked_by/result_of |
RunShow | 绑定 run 到当前 session，显示 widget |
创建 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 记录
| type | 记什么 | 示例 |
|---|
progress | 做了什么 | "3 seeds 全部跑完" |
observation | 任务级观测 | "seed=42 BLEU=33.5" |
issue | 遇到什么障碍 | "vllm 版本冲突" |
decision | 任务级决策 | "降级到 vllm 0.4.1" |
output | 产出了什么 | "产出 exp/bleu-baseline" |
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/ 下没有未提交的变更。
