From 9109fa3fa3bbee117df9f0ade425a8bf6c796ec4 Mon Sep 17 00:00:00 2001 From: Research Assistant Date: Tue, 19 May 2026 14:54:05 +0800 Subject: [PATCH] feat(skill): add capture-project-knowledge molecule and atoms --- .../atoms/extract-methodology-card.md | 107 +++++++++++++- .../paperforge/atoms/retrieval-routing.md | 65 +++++++++ .../paperforge/atoms/write-project-log.md | 130 +++++++++++++++++- .../atoms/write-project-reading-log.md | 97 ++++++++++++- .../atoms/write-reading-log-jsonl.md | 107 +++++++++++++- .../molecules/capture-project-knowledge.md | 76 +++++++++- 6 files changed, 577 insertions(+), 5 deletions(-) diff --git a/paperforge/skills/paperforge/atoms/extract-methodology-card.md b/paperforge/skills/paperforge/atoms/extract-methodology-card.md index 57b39e5b..df7770b2 100644 --- a/paperforge/skills/paperforge/atoms/extract-methodology-card.md +++ b/paperforge/skills/paperforge/atoms/extract-methodology-card.md @@ -1,3 +1,108 @@ # extract-methodology-card -Extract a structured methodology card from a paper. +从项目日志中提取可复用的方法论，生成方法论卡片。 + +--- + +## 前置条件 + +- bootstrap 已完成（有 `$VAULT`、`$PYTHON`） +- 已知 project 名称 +- 目标项目有至少一条 `type: "session_summary"` 或 `type: "note"` 的日志 + +--- + +## 步骤 + +### Step 1: 读取项目日志 + +```bash +$PYTHON -m paperforge --vault "$VAULT" project-log --list --project "" --json +``` + +从返回的日志条目中筛选包含可复用方法论的内容（`reusable` 字段非空的条目）。 + +### Step 2: 识别可复用模式 + +逐条分析日志，找出： +- 重复出现的解决策略 +- 用户纠正的常见错误 +- 被多次验证有效的流程 + +### Step 3: 读取方法论卡片模板 + +从 `references/method-card-template.md` 读取模板： + +```bash +cat "$VAULT/System/PaperForge/references/method-card-template.md" +``` + +### Step 4: 填充模板生成卡片 + +按模板格式填充： + +```markdown +--- +id: +tags: [, ] +source_project: +status: active +--- + +# <卡片标题（简短可搜索）> + +## Use when + + +## Procedure +1. <步骤 1> +2. <步骤 2> +3. <步骤 3> + +## Watch-outs +- <常见陷阱> +- <注意事项> + +## Example +来自 `` 项目的具体例子（附 project-log 来源） +--- +``` + +### Step 5: 确认写入 + +``` +即将创建方法论卡片到 System/PaperForge/methodology/archive/.md: + +标题: dc-parameter-audit +来源: 综述写作 +步骤: + 1. 列出所有参数窗断言 + 2. 逐句追溯文献来源 + 3. 区分"文献说了什么"和"我推断什么" + +确认写入？(y/n) +``` + +### Step 6: 写入 + +```bash +cat > "$VAULT/System/PaperForge/methodology/archive/.md" << 'EOF' +<卡片内容> +EOF +``` + +写入后确认文件已创建。 + +--- + +## 禁止 + +- 不要在没有 project-log 的情况下凭空创建卡片 +- 不要创建单次使用的方法——必须是可跨项目复用的模式 +- 不要使用与已有卡片重复的 id + +--- + +## 参考 + +模板文件：`references/method-card-template.md` diff --git a/paperforge/skills/paperforge/atoms/retrieval-routing.md b/paperforge/skills/paperforge/atoms/retrieval-routing.md index b138b532..9855e059 100644 --- a/paperforge/skills/paperforge/atoms/retrieval-routing.md +++ b/paperforge/skills/paperforge/atoms/retrieval-routing.md @@ -1,3 +1,68 @@ # retrieval-routing Route between vector and memory retrievers based on query type. + +## 1. Authority principles + +- **bootstrap** provides convenience capability fields only; it is not the runtime truth source +- **runtime-health** is the runtime truth source; always check it before making retrieval decisions +- **Semantic/vector retrieval is optional and supplementary** -- metadata and fulltext search are the primary retrieval path + +## 2. Retrieval ladders + +### Ladder A -- Paper Discovery (for discover-papers molecule) + +1. Use `paperforge search` (metadata FTS) to find candidate papers +2. Enrich top hits with `paperforge paper-context` +3. Show candidate list to user + +### Ladder B -- Evidence Retrieval with rg + +1. Generate metadata candidates via `paperforge search` +2. Narrow to papers with OCR/fulltext available (check runtime-health or paper-context) +3. Run `rg` over resolved fulltext set to locate exact evidence +4. Verify top hits with `paperforge paper-context` and local snippet reads + +### Ladder C -- Evidence Retrieval without rg + +1. Same metadata generation as Ladder B +2. Fallback to `grep` / `findstr` / system search +3. If agent environment supports, try installing rg (not assumed by default) +4. If no fulltext search tool is available, degrade to metadata-only evidence + +### Ladder D -- Semantic Candidate Expansion (if `semantic_enabled` && `semantic_ready`) + +1. Use `paperforge retrieve ` to expand candidate set +2. Never treat semantic hits as final evidence +3. Verify every semantic hit with rg / fulltext / paper-context before use + +## 3. Fallback behavior when no OCR/fulltext exists + +When runtime-health indicates no papers have OCR or fulltext available: + +> Exact evidence verification is limited -- degrading to metadata-level support + +Present a candidate paper list only; no snippet verification is performed. + +## 4. Recommended default limits + +- Metadata candidate set: top 10-20 papers +- Fulltext/snippet verification: top 3-5 papers + +## 5. Semantic degradation rule + +```text +If semantic_enabled=false or semantic_ready=false: +- Do not call retrieve as primary path +- Fall back to metadata + rg/grep + paper-context + +If semantic is available: +- Use only for candidate expansion +- Every semantic hit must be verified by rg/fulltext/paper-context before use +``` + +## 6. Commit convention + +``` +feat(skill): add retrieval-routing atom +``` diff --git a/paperforge/skills/paperforge/atoms/write-project-log.md b/paperforge/skills/paperforge/atoms/write-project-log.md index bd73fbd5..d9873196 100644 --- a/paperforge/skills/paperforge/atoms/write-project-log.md +++ b/paperforge/skills/paperforge/atoms/write-project-log.md @@ -1,3 +1,131 @@ # write-project-log -Write a general project log entry. +记录会话/项目日志到 `project-log.jsonl`，包含决策、弯路、待办等。 + +--- + +## 前置条件 + +- bootstrap 已完成（有 `$VAULT`、`$PYTHON`） +- 已知 project 名称 +- 对话上下文中已有会话内容可回顾 + +--- + +## Schema + +```json +{ + "id": "plog_20260519_001", + "project": "综述写作", + "date": "2026-05-19", + "type": "session_summary", + "title": "DC 段参数窗审计", + "decisions": ["做了 X，因为 Y"], + "detours": [ + { + "wrong": "错误方向", + "correction": "用户如何纠正", + "resolution": "最终方案" + } + ], + "reusable": ["可复用的方法论或教训"], + "todos": [ + {"content": "待办事项", "done": false} + ], + "related_papers": ["ABC12345"], + "tags": ["DC", "参数窗", "审计"], + "agent": "opencode" +} +``` + +| 字段 | 必填 | 说明 | +|------|------|------| +| `id` | 是 | 自动生成 `plog_YYYYMMDD_NNN` | +| `project` | 是 | 项目名 | +| `date` | 是 | YYYY-MM-DD | +| `type` | 是 | `session_summary` / `decision` / `correction` / `milestone` / `note` | +| `title` | 是 | 简短标题 | +| `decisions` | 否 | 核心决策列表 | +| `detours` | 否 | 弯路与修正记录 | +| `reusable` | 否 | 可复用方法论 | +| `todos` | 否 | 待办事项 | +| `related_papers` | 否 | 相关 Zotero keys | +| `tags` | 否 | 分类标签 | +| `agent` | 否 | 记录者 | + +--- + +## 步骤 + +### Step 1: 确定 project 和 type + +从上下文获取。如果用户未指定 project，询问。 + +type 参考： + +| type | 使用场景 | +|------|---------| +| `session_summary` | 会话结束时的总结 | +| `decision` | 单独记录一个重要决策 | +| `correction` | 用户纠正了某个方向 | +| `milestone` | 项目里程碑 | +| `note` | 一般研究笔记 | + +### Step 2: 回顾本次会话 + +提取以下内容： +- **做了什么**（核心决策及其原因） +- **用户纠正了什么**（弯路与修正） +- **有什么可复用的发现** +- **待办事项** + +### Step 3: 展示确认 + +``` +即将记录: + 日期: 2026-05-19 + 类型: session_summary + 标题: DC 段参数窗审计完成 + 决策: + - 限定参数窗为 100Hz-1kHz + 弯路: + - 把推断当文献事实 → 用户要求逐句审计 → 5 处修正 + 可复用: + - 写完必须逐句过 source + +确认写入？(y/n) +``` + +### Step 4: 写入 + +```bash +$PYTHON -m paperforge --vault "$VAULT" project-log --write \ + --project "" \ + --payload '' +``` + +payload 为完整 JSON 对象（单行序列化）。 + +返回 `ok: true` → 写入成功；`ok: false` → 报错重试。 + +### Step 5: 确认渲染 + +```bash +$PYTHON -m paperforge --vault "$VAULT" project-log --render --project "" +``` + +输出到 `Resources/Projects//project-log.md`。 + +--- + +## 禁止 + +- 不要在用户确认前写入 +- 不要只写"做了什么"而没有"弯路"和"可复用"部分 + +--- + +## 参考 + +详情请看 `workflows/project-log.md`。 diff --git a/paperforge/skills/paperforge/atoms/write-project-reading-log.md b/paperforge/skills/paperforge/atoms/write-project-reading-log.md index 70b31bf0..67dfb6f0 100644 --- a/paperforge/skills/paperforge/atoms/write-project-reading-log.md +++ b/paperforge/skills/paperforge/atoms/write-project-reading-log.md @@ -1,3 +1,98 @@ # write-project-reading-log -Write a formatted reading log entry to the project README. +将叙述性证据直接写入 `Resources/Projects//reading-log.md`。 + +**定位：丰富内容层**——完整段落、写作素材、按 claim 组织的叙述性记录。 + +--- + +## 核心原则 + +**由 Agent 直接写入 markdown，不从 JSONL 渲染，不自动生成。** + +这是给你（人类作者）看的文档，不是给机器解析的数据。因此应该用自然段落写作，按论点和 claim 组织，而非逐条粘贴 JSON。 + +--- + +## 前置条件 + +- bootstrap 已完成（有 `$VAULT`、`$PYTHON`） +- 已知 `project` 名称 +- 目标文件路径：`$VAULT/Resources/Projects//reading-log.md` + +--- + +## 步骤 + +### Step 1: 确认项目 + +从上下文获取 project 名称。如果未指定，询问用户。 + +### Step 2: 组织叙述内容 + +按 claim/论点组织写作素材，而非按论文。每段包含： + +- **Claim 标题**（`##` 级别） +- **来源论文**（标题 + 年份 + 作者） +- **关键证据**（原文引用 + 你的解读） +- **与其他证据的关系**（支持/矛盾/补充） + +### Step 3: 展示确认 + +``` +即将写入 Resources/Projects/综述写作/reading-log.md: + +# PEMF 对 GAG 合成的影响 + +## PEMF 促进软骨基质合成 +Smith 2024 在体外软骨细胞实验中报告，PEMF 暴露后 GAG 含量增加 40%（原文：...）。 +这与 Jones 2023 的结果一致...... + +确认写入？(y/n) +``` + +### Step 4: 写入文件 + +```bash +# 方法一：直接附加到文件 +cat >> "$VAULT/Resources/Projects//reading-log.md" << 'EOF' + +## + +<内容...> + +--- +EOF +``` + +```bash +# 方法二：如果文件不存在，先创建 +New-Item -Force -ItemType File -Path "$VAULT/Resources/Projects//reading-log.md" +``` + +### Step 5: 确认写入成功 + +读取目标文件最后几行，确认内容已正确追加。 + +--- + +## 与 JSONL 的关系 + +| | JSONL | Project reading-log | +|---|-------|-------------------| +| 粒度 | 单句/单点 | 段落/claim 级 | +| 格式 | JSON 对象 | Markdown 叙述 | +| 使用者 | 机器搜索/渲染 | 人类阅读/写作 | +| 生成方式 | atom 写 | Agent 直接写 | +| 频率 | 高频 | 低频（仅在材料累积到可成段时） | + +两者互补——JSONL 是索引，project reading-log 是内容。 + +--- + +## 禁止 + +- 不要从 JSONL 自动渲染——这是人工写作区域 +- 不要只粘贴 JSON——这是给人看的文档 +- 不要用单句代替完整段落 +- 不要在用户确认前写入 diff --git a/paperforge/skills/paperforge/atoms/write-reading-log-jsonl.md b/paperforge/skills/paperforge/atoms/write-reading-log-jsonl.md index a0f65190..8b69cd14 100644 --- a/paperforge/skills/paperforge/atoms/write-reading-log-jsonl.md +++ b/paperforge/skills/paperforge/atoms/write-reading-log-jsonl.md @@ -1,3 +1,108 @@ # write-reading-log-jsonl -Append a structured reading entry to the JSONL reading log. +向 `reading-log.jsonl` 追加单条结构化阅读条目。 + +**定位：结构化索引层**——简短、可搜索、机器可解析。每条条文对应论文中的一句引用/发现。 + +--- + +## 前置条件 + +- bootstrap 已完成（有 `$VAULT`、`$PYTHON`） +- 已知 `paper_id`（zotero_key） +- 上下文中有待记录的 excerpt 和相关信息 + +--- + +## Schema + +```json +{ + "id": "rln_20260519_001", + "paper_id": "ABC12345", + "project": "综述写作", + "section": "Results Fig.3", + "excerpt": "原文关键句（逐字引用）", + "context": "包含 excerpt 的完整段落", + "usage": "这个信息在写作中的用途", + "note": "注意事项 / 待核查", + "tags": ["PEMF", "dose-response"], + "verified": false +} +``` + +| 字段 | 必填 | 说明 | +|------|------|------| +| `id` | 是 | 自动生成 `rln_YYYYMMDD_NNN` | +| `paper_id` | 是 | Zotero key（8位大写） | +| `project` | 否 | 关联的研究项目 | +| `section` | 是 | 文献位置 | +| `excerpt` | 是 | 逐字引用原文 | +| `context` | 是 | 完整段落供复核定位 | +| `usage` | 是 | 在写作中的用途 | +| `note` | 否 | 待核查事项 | +| `tags` | 否 | 分类标签 | +| `verified` | 否 | 默认 false | + +--- + +## 步骤 + +### Step 1: 收集必填字段 + +从对话上下文提取：`paper_id`、`section`、`excerpt`、`context`、`usage`。 + +### Step 2: 生成 id + +格式：`rln__<3位序号>`（序号从上下文已存在的条数推断） + +### Step 3: 展示确认 + +``` +即将记录: + 文献: ABC12345 | Smith 2024 + 位置: Results Fig.3 + 原文: "..." + 用途: 支撑 PEMF 基质合成的论证 + 项目: 综述写作 + 标签: PEMF, GAG + +确认写入？(y/n) +``` + +### Step 4: 写入 + +```bash +$PYTHON -m paperforge --vault "$VAULT" reading-log --write \ + --section "
" \ + --excerpt "" \ + --context "" \ + --usage "" \ + --note "" \ + --project "" \ + --tags "," +``` + +返回 `ok: true` → 写入成功；`ok: false` → 报错重试一次。 + +### Step 5: 触发渲染 + +```bash +$PYTHON -m paperforge --vault "$VAULT" reading-log --render --project "" +``` + +输出到 `Resources/Projects//reading-log.md`。 + +--- + +## 禁止 + +- 不要在用户确认前写入 +- `excerpt` 必须是原文逐字引用，不能是推断或改写 +- `context` 不能为空 + +--- + +## 参考 + +详情请看 `workflows/reading-log.md`。 diff --git a/paperforge/skills/paperforge/molecules/capture-project-knowledge.md b/paperforge/skills/paperforge/molecules/capture-project-knowledge.md index 3c2a6daa..b1c96baf 100644 --- a/paperforge/skills/paperforge/molecules/capture-project-knowledge.md +++ b/paperforge/skills/paperforge/molecules/capture-project-knowledge.md @@ -1,3 +1,77 @@ # capture-project-knowledge -Capture and persist knowledge gained from reading into project memory. +捕获和持久化从阅读中获得的知识到项目记忆。 + +--- + +## 触发模式 + +### 1. 直意模式（Direct intent） + +用户直接说"记一下"、"保存"、"记录这条"——不管从哪个上下文来，都路由到这里。 + +### 2. 后置模式（Post-action） + +在其他分子（`read-known-paper`、`find-supporting-evidence`）产出结果后，用户要求保存其中一部分内容。 + +--- + +## 捕获类型 + +| 类型 | 描述 | 对应 Atom | +|------|------|-----------| +| **Lightweight JSONL** | 单条结构化阅读笔记，可搜索、可机器解析 | `atoms/write-reading-log-jsonl.md` | +| **Rich reading-log** | 叙述性段落，直接写入项目 markdown，写作素材 | `atoms/write-project-reading-log.md` | +| **Session/project log** | 会话总结、决策记录、弯路修正、待办事项 | `atoms/write-project-log.md` | +| **Methodology card** | 从项目日志中提取可复用的方法论 | `atoms/extract-methodology-card.md` | + +--- + +## 步骤 + +### Step 1: 确定用户意图 + +从对话上下文中判断用户要保存哪类内容： + +- 用户提到单条论文片段 / 引用 → **Lightweight JSONL**（最快、最轻量） +- 用户说"写一段总结" / "记录到这个项目" → **Rich reading-log** +- 用户说"记一下今天的进展" / "记录决策" → **Session/project log** +- 用户说"这个方法值得复用" / "提取方法论" → **Methodology card** +- 不确定时：列出四个选项让用户选 + +### Step 2: 调用对应 Atom + +| 意图 | Atom | +|------|------| +| 单条阅读笔记 | `atoms/write-reading-log-jsonl.md` | +| 项目阅读记录 | `atoms/write-project-reading-log.md` | +| 会话/项目日志 | `atoms/write-project-log.md` | +| 方法论提取 | `atoms/extract-methodology-card.md` | + +### Step 3: 写入前确认 + +**必须**在写入前以交互方式展示给用户确认。 + +格式参考对应 workflow（`workflows/reading-log.md`、`workflows/project-log.md`）中的确认模板。 + +### Step 4: 写入后反馈 + +确认写入成功后，告知用户写入位置和主要内容摘要。 + +--- + +## 过渡路由 + +| 来源 | 路由方式 | +|------|---------| +| `read-known-paper` 保存讨论 | 用户说"保存" → Step 1 | +| `find-supporting-evidence` 保存证据 | 用户选择证据保存 → Step 1 | +| 用户直接说"记一下" | 直意触发 → Step 1 | + +--- + +## 禁止 + +- 不要在用户未要求时自动保存内容 +- 不要绕过确认步骤直接写入 +- 不要用 project-reading-log 替代 lightweight JSONL（它们是不同粒度的记录）