agent-research-aggregator

agent-research-aggregator

---

是否运行？（决策关卡）

开始第 1 阶段前，请先检查是否确实需要聚合：

情况	操作
workspace/inputs/idea.md 和 workspace/inputs/experimental_log.md 均存在且非空	完全跳过此技能。 直接继续运行 paper-orchestra。
任一文件缺失或为空，且用户提供了目录路径	使用该目录作为 --search-roots 运行此技能。
任一文件缺失或为空，且用户未提供目录	默认扫描 cwd 和 ~；继续之前向用户展示发现摘要。
输入文件存在，但内容似乎不足（例如，idea.md 少于 5 行，experimental_log.md 中没有数值数据）	询问用户是要通过聚合补充内容，还是按现有内容继续。

此技能刻意设计为前置处理步骤——跳过它的成本很低，只有在结构化输入尚不存在时才应运行。

---

PaperOrchestra（arXiv:2604.05018）的预处理技能。读取 AI 编码 Agent 缓存目录中零散的实验产物，并将其综合为 PaperOrchestra 流水线所需的结构化 (I, E) 输入对。

[.claude/]  [.cursor/]  [.antigravity/]  [.openclaw/]
      │            │              │               │
      └────────────┴──────────────┴───────────────┘
                          │
                    Phase 1: Discovery
                  (discover_logs.py)
                          │
                    discovered_logs.json
                          │
                    Phase 2: Extraction
                  (LLM call per log batch)
                          │
                    raw_experiments.json
                          │
                    Phase 3: Synthesis
                  (LLM call — consolidate)
                          │
                    synthesis.json
                          │
                    Phase 4: Formatting
                  (format_po_inputs.py)
                          │
             ┌────────────┴────────────┐
      workspace/inputs/         workspace/ara/
        idea.md                   aggregation_report.md
        experimental_log.md       discovered_logs.json
                                  raw_experiments.json
                                  synthesis.json

输出会直接写入 workspace/inputs/，用户可以立即在同一工作区运行 paper-orchestra。

---

输入

参数	必填	默认值	说明
--search-roots	否	cwd, ~	要扫描以查找 Agent 缓存的逗号分隔目录
--agents	否	all	逗号分隔的子集：claude,cursor,antigravity,openclaw
--workspace	否	./workspace	PaperOrchestra 工作区根目录
--depth	否	4	最大目录扫描深度（防止在大型主目录中无休止地扫描）
--since	否	none	仅包含此日期之后修改的日志（ISO 8601：2025-01-01）

用户在调用此技能时指定这些参数；如果当前目录中没有可检测到的 Agent 缓存，也可以向用户询问 --search-roots。

---

第 1 阶段 — 发现（确定性）

运行发现脚本，为所有相关日志文件编目：

python skills/agent-research-aggregator/scripts/discover_logs.py \
    --search-roots <roots> \
    --agents <agents> \
    --depth <depth> \
    --since <since> \
    --out workspace/ara/discovered_logs.json

未设置 --project 筛选条件时，脚本会以代码 2 退出（首次运行时属于预期情况）。脚本会向标准输出打印 “Projects found” 列表——请立即向用户展示。

如果完全没有找到日志： 停止操作，并请用户指定 --search-roots，或提供一个包含 Agent 缓存文件夹的目录。

---

第 1.5 阶段 — 项目选择（必需）

论文只能基于单个项目撰写。在开始任何大模型处理之前，必须询问用户要使用哪个项目。

1. 显示发现摘要中的编号项目列表，例如：

   Projects found:
     [1] /home/alice/projects/my-rl-experiment  (42 files)
     [2] /home/alice/projects/llm-eval-suite    (17 files)
     [3] /home/alice/projects/old-demo          (3 files)
   

2. 询问：“这篇论文应基于哪个项目？请选择一个编号，或粘贴项目路径。”
3. 用户回答之前，不要继续第 2 阶段。
4. 使用选定的项目重新运行发现脚本，以筛选清单：

python skills/agent-research-aggregator/scripts/discover_logs.py \
    --search-roots <roots> \
    --agents <agents> \
    --depth <depth> \
    --since <since> \
    --project "<chosen project path>" \
    --out workspace/ara/discovered_logs.json

这会覆盖 discovered_logs.json，仅保留所选项目的文件。成功时脚本以 0 退出。

如果发现结果中只有一个项目： 跳过提问，并告知用户：“只找到一个项目：<path>。将使用此项目撰写论文。”——然后自动使用 --project 重新运行。

如果筛选后的发现摘要中仍显示无关文件： 继续第 2 阶段之前，询问用户要包含还是排除这些文件。倾向于包含——提取提示词较为保守。

---

阶段 2 — 提取（LLM 辅助）

分批次处理已发现的日志（按 Agent 类型分组；每批原始文本控制在约 50 KB 以下，以免超出上下文限制）：

对于每个批次：

1. 读取该批次中的日志文件（脚本的 --list 输出会告知要读取哪些文件路径）。
2. 将 references/extraction-prompt.md 中的提取提示词用作系统消息。
3. 将原始日志文本作为用户消息传入。
4. 收集 LLM 返回的结构化 JSON（参见提示词中的架构）。
5. 追加到 workspace/ara/raw_experiments.json。

所有批次处理完成后：

python skills/agent-research-aggregator/scripts/extract_experiments.py \
    --discovered workspace/ara/discovered_logs.json \
    --out workspace/ara/raw_experiments.json \
    --validate-only

使用 --validate-only 模式运行，以检查合并后的 JSON 格式正确且符合最低架构要求（experiments 数组非空，且每个条目都包含 hypothesis、method 或 results）。在进入阶段 3 之前修复所有格式错误的条目。

---

阶段 3 — 综合（LLM 辅助）

将来自多个 Agent 缓存的、可能冗余的实验记录整合为连贯统一的研究叙述。这是一次 LLM 调用。

系统消息： 原样使用 references/synthesis-prompt.md。

用户消息：

<raw_experiments>
{contents of workspace/ara/raw_experiments.json}
</raw_experiments>

LLM 必须返回包含以下键的 synthesis.json：

• research_question — 正在研究的总体问题
• hypothesis — 核心拟议解决方案 / 主张
• method_summary — 方法的工作原理（简洁，不泄露数据）
• key_contributions — 2–5 个项目符号字符串
• experimental_setup — 数据集、指标、基线、实现说明
• results_tables — {title, headers[], rows[]} Markdown 表格对象数组
• qualitative_observations — 自由格式文本块（有效之处、无效之处、失败模式、消融分析见解）
• iteration_history — 如果检测到多次迭代，则按顺序列出 {iteration_id, change_description, outcome} 条目
• open_questions — 日志中仍未解答的问题

保存到 workspace/ara/synthesis.json。

注意： 此时，用户已在阶段 1.5 中选择了一个项目。综合内容应体现一条连贯的研究主线。如果 LLM 仍提出多个互不相关的研究问题，请在审计报告（阶段 5）中将其标记为数据质量警告，但不要再次要求用户选择项目——该决定已在之前作出。

---

阶段 4 — 格式化（确定性）

将 synthesis.json 转换为 PaperOrchestra 输入文件：

python skills/agent-research-aggregator/scripts/format_po_inputs.py \
    --synthesis workspace/ara/synthesis.json \
    --out workspace/inputs/

这会生成两个文件：

workspace/inputs/idea.md（稀疏版）

遵循 PaperOrchestra 稀疏构想格式（arXiv:2604.05018, §3.1）：

# [Synthesized Research Title]

## Problem
<2–4 sentence problem statement derived from research_question>

## Hypothesis
<hypothesis from synthesis>

## Method
<method_summary from synthesis>

## Key Contributions
<key_contributions as bullet list>

## Open Questions
<open_questions, if any>

workspace/inputs/experimental_log.md

遵循 PaperOrchestra 实验日志格式（附录 D.3）：

## 1. Experimental Setup
<experimental_setup from synthesis, formatted as prose + sub-bullets>

## 2. Raw Numeric Data
<results_tables converted to GitHub-Flavored Markdown tables>

## 3. Qualitative Observations
<qualitative_observations from synthesis>

### Iteration History
<iteration_history as an ordered narrative, if present>

运行脚本后，与用户一起审阅这两个文件：

1. 大声读出 workspace/inputs/idea.md，并询问：“这是否准确体现了你的研究问题和方法？”
2. 读出 workspace/inputs/experimental_log.md 中的表头，并询问：“这些指标和基线是否正确？”

根据反馈进行修改，然后再继续使用 PaperOrchestra。

---

阶段 5 — 审计报告（确定性）

python skills/agent-research-aggregator/scripts/format_po_inputs.py \
    --synthesis workspace/ara/synthesis.json \
    --out workspace/inputs/ \
    --report workspace/ara/aggregation_report.md

--report 标志会让脚本同时写入 aggregation_report.md，其中包含：

• 扫描的 Agent 缓存数、读取的文件数、处理的批次数
• 按 Agent 划分的明细（每种 Agent 类型找到的文件数）
• 提取的实验记录（数量、日期范围）
• 检测到的迭代（数量、收敛方向）
• 数据质量警告（缺失、低置信度提取、数值冲突）
• 写入的文件及其大小

向用户展示该报告。如果数据质量部分列出了警告，请在运行 paper-orchestra 之前与用户讨论——垃圾进，垃圾出。

移交给 PaperOrchestra

用户确认 idea.md 和 experimental_log.md 后，工作区即可用于 paper-orchestra 流水线。你仍需要：

文件	状态	操作
workspace/inputs/idea.md	✓ 已生成	建议用户审核
workspace/inputs/experimental_log.md	✓ 已生成	建议用户审核
workspace/inputs/template.tex	缺失	请用户提供其会议 LaTeX 模板
workspace/inputs/conference_guidelines.md	缺失	请用户提供（页数限制、截止日期、格式规则）

准确告知用户还需要哪两个文件，然后表示用户提供文件后，你可以运行 paper-orchestra。

---

错误处理

情况	操作
缓存目录不存在	静默跳过；在报告中注明
文件是二进制文件或非文本文件	跳过；在报告中注明
文件 > 200 KB	截断至 200 KB；在报告中注明路径
LLM 提取返回格式错误的 JSON	附上解析错误后重新提示一次；如果仍然格式错误，则将该批次记录为 status: failed 并继续
综合结果包含多个 research_question	在审计报告中将其记录为数据质量警告；不要再次询问项目（已在 Phase 1.5 中选定）
综合后 results_tables 为空	警告用户——PaperOrchestra 的章节撰写 Agent 需要数值数据

---

硬性规则（绝不违反）

1. 绝不写入 Agent 缓存目录。 此技能对 .claude/、.cursor/、.antigravity/、.openclaw/ 只读。
2. 绝不在生成的 idea.md 或 experimental_log.md 中包含个人信息（电子邮件、姓名、凭据、API 密钥）。提取提示词要求 LLM 清除 PII；移交前请再次检查。
3. 绝不捏造结果。 如果某项指标只出现在一份日志中且置信度较低，请在表格中将其标记为 [UNVERIFIED]，而不要悄然将其纳入。
4. 如果扫描发现 > 50 个文件，未经用户确认发现的文件列表，绝不进入 Phase 1 之后的阶段。

---

快速参考

# Phase 1: discover all projects (exits with code 2 — project selection required)
python skills/agent-research-aggregator/scripts/discover_logs.py \
    --search-roots . ~ --out workspace/ara/discovered_logs.json

# Phase 1.5: re-run with chosen project (exits 0)
python skills/agent-research-aggregator/scripts/discover_logs.py \
    --search-roots . ~ \
    --project "/home/user/projects/my-chosen-project" \
    --out workspace/ara/discovered_logs.json

# ... (Phase 2: LLM extraction calls, see above) ...

python skills/agent-research-aggregator/scripts/extract_experiments.py \
    --discovered workspace/ara/discovered_logs.json \
    --out workspace/ara/raw_experiments.json --validate-only

# ... (Phase 3: LLM synthesis call, see above) ...

python skills/agent-research-aggregator/scripts/format_po_inputs.py \
    --synthesis workspace/ara/synthesis.json \
    --out workspace/inputs/ \
    --report workspace/ara/aggregation_report.md