mirror of
https://github.com/lllin000/PaperForge.git
synced 2026-07-22 06:50:53 +00:00
feat(skill): add capture-project-knowledge molecule and atoms
This commit is contained in:
Research Assistant
parent
6c458fb02a
commit
9109fa3fa3
6 changed files with 577 additions and 5 deletions
|
|
@ -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 "<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: <kebab-case-id>
|
||||
tags: [<tag1>, <tag2>]
|
||||
source_project: <project-name>
|
||||
status: active
|
||||
---
|
||||
|
||||
# <卡片标题（简短可搜索）>
|
||||
|
||||
## Use when
|
||||
<!-- 什么时候应该用 -->
|
||||
|
||||
## Procedure
|
||||
1. <步骤 1>
|
||||
2. <步骤 2>
|
||||
3. <步骤 3>
|
||||
|
||||
## Watch-outs
|
||||
- <常见陷阱>
|
||||
- <注意事项>
|
||||
|
||||
## Example
|
||||
来自 `<project>` 项目的具体例子（附 project-log 来源）
|
||||
---
|
||||
```
|
||||
|
||||
### Step 5: 确认写入
|
||||
|
||||
```
|
||||
即将创建方法论卡片到 System/PaperForge/methodology/archive/<id>.md:
|
||||
|
||||
标题: dc-parameter-audit
|
||||
来源: 综述写作
|
||||
步骤:
|
||||
1. 列出所有参数窗断言
|
||||
2. 逐句追溯文献来源
|
||||
3. 区分"文献说了什么"和"我推断什么"
|
||||
|
||||
确认写入？(y/n)
|
||||
```
|
||||
|
||||
### Step 6: 写入
|
||||
|
||||
```bash
|
||||
cat > "$VAULT/System/PaperForge/methodology/archive/<id>.md" << 'EOF'
|
||||
<卡片内容>
|
||||
EOF
|
||||
```
|
||||
|
||||
写入后确认文件已创建。
|
||||
|
||||
---
|
||||
|
||||
## 禁止
|
||||
|
||||
- 不要在没有 project-log 的情况下凭空创建卡片
|
||||
- 不要创建单次使用的方法——必须是可跨项目复用的模式
|
||||
- 不要使用与已有卡片重复的 id
|
||||
|
||||
---
|
||||
|
||||
## 参考
|
||||
|
||||
模板文件：`references/method-card-template.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 <query>` 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
|
||||
```
|
||||
|
|
|
|||
|
|
@ -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 "<project>" \
|
||||
--payload '<payload>'
|
||||
```
|
||||
|
||||
payload 为完整 JSON 对象（单行序列化）。
|
||||
|
||||
返回 `ok: true` → 写入成功；`ok: false` → 报错重试。
|
||||
|
||||
### Step 5: 确认渲染
|
||||
|
||||
```bash
|
||||
$PYTHON -m paperforge --vault "$VAULT" project-log --render --project "<project>"
|
||||
```
|
||||
|
||||
输出到 `Resources/Projects/<project>/project-log.md`。
|
||||
|
||||
---
|
||||
|
||||
## 禁止
|
||||
|
||||
- 不要在用户确认前写入
|
||||
- 不要只写"做了什么"而没有"弯路"和"可复用"部分
|
||||
|
||||
---
|
||||
|
||||
## 参考
|
||||
|
||||
详情请看 `workflows/project-log.md`。
|
||||
|
|
|
|||
|
|
@ -1,3 +1,98 @@
|
|||
# write-project-reading-log
|
||||
|
||||
Write a formatted reading log entry to the project README.
|
||||
将叙述性证据直接写入 `Resources/Projects/<project>/reading-log.md`。
|
||||
|
||||
**定位：丰富内容层**——完整段落、写作素材、按 claim 组织的叙述性记录。
|
||||
|
||||
---
|
||||
|
||||
## 核心原则
|
||||
|
||||
**由 Agent 直接写入 markdown，不从 JSONL 渲染，不自动生成。**
|
||||
|
||||
这是给你（人类作者）看的文档，不是给机器解析的数据。因此应该用自然段落写作，按论点和 claim 组织，而非逐条粘贴 JSON。
|
||||
|
||||
---
|
||||
|
||||
## 前置条件
|
||||
|
||||
- bootstrap 已完成（有 `$VAULT`、`$PYTHON`）
|
||||
- 已知 `project` 名称
|
||||
- 目标文件路径：`$VAULT/Resources/Projects/<project>/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/<project>/reading-log.md" << 'EOF'
|
||||
|
||||
## <Claim 标题>
|
||||
|
||||
<内容...>
|
||||
|
||||
---
|
||||
EOF
|
||||
```
|
||||
|
||||
```bash
|
||||
# 方法二：如果文件不存在，先创建
|
||||
New-Item -Force -ItemType File -Path "$VAULT/Resources/Projects/<project>/reading-log.md"
|
||||
```
|
||||
|
||||
### Step 5: 确认写入成功
|
||||
|
||||
读取目标文件最后几行，确认内容已正确追加。
|
||||
|
||||
---
|
||||
|
||||
## 与 JSONL 的关系
|
||||
|
||||
| | JSONL | Project reading-log |
|
||||
|---|-------|-------------------|
|
||||
| 粒度 | 单句/单点 | 段落/claim 级 |
|
||||
| 格式 | JSON 对象 | Markdown 叙述 |
|
||||
| 使用者 | 机器搜索/渲染 | 人类阅读/写作 |
|
||||
| 生成方式 | atom 写 | Agent 直接写 |
|
||||
| 频率 | 高频 | 低频（仅在材料累积到可成段时） |
|
||||
|
||||
两者互补——JSONL 是索引，project reading-log 是内容。
|
||||
|
||||
---
|
||||
|
||||
## 禁止
|
||||
|
||||
- 不要从 JSONL 自动渲染——这是人工写作区域
|
||||
- 不要只粘贴 JSON——这是给人看的文档
|
||||
- 不要用单句代替完整段落
|
||||
- 不要在用户确认前写入
|
||||
|
|
|
|||
|
|
@ -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_<YYYYMMDD>_<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 <paper_id> \
|
||||
--section "<section>" \
|
||||
--excerpt "<excerpt>" \
|
||||
--context "<context>" \
|
||||
--usage "<usage>" \
|
||||
--note "<note>" \
|
||||
--project "<project>" \
|
||||
--tags "<tag1>,<tag2>"
|
||||
```
|
||||
|
||||
返回 `ok: true` → 写入成功；`ok: false` → 报错重试一次。
|
||||
|
||||
### Step 5: 触发渲染
|
||||
|
||||
```bash
|
||||
$PYTHON -m paperforge --vault "$VAULT" reading-log --render --project "<project>"
|
||||
```
|
||||
|
||||
输出到 `Resources/Projects/<project>/reading-log.md`。
|
||||
|
||||
---
|
||||
|
||||
## 禁止
|
||||
|
||||
- 不要在用户确认前写入
|
||||
- `excerpt` 必须是原文逐字引用，不能是推断或改写
|
||||
- `context` 不能为空
|
||||
|
||||
---
|
||||
|
||||
## 参考
|
||||
|
||||
详情请看 `workflows/reading-log.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（它们是不同粒度的记录）
|
||||
|
|
|
|||
Loading…
Reference in a new issue