refactor(docs): reorganize docs, cleanup orphans, update maturity#188
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
📝 WalkthroughWalkthroughThis PR reorganizes PaperBot documentation by consolidating and streamlining design artifacts. It removes obsolete anchor author, memory proposal, and research page redesign documents, replacing them with unified comprehensive documentation for anchor systems, memory architecture, and P2C optimizations. The README is updated with new feature descriptions and API endpoints. Two utility scripts are also deleted. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Possibly related issues
Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Summary of ChangesHello, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! 此拉取请求主要对文档进行了重大的重构和重新组织，同时更新了项目的路线图和模块成熟度级别。核心目标是提高文档的清晰度，简化信息流，并使项目文档与未来的开发阶段保持一致，特别是关于记忆优化和智能体研究的集成。通过删除冗余文件和合并相关内容，文档结构变得更加精简和易于导航。 Highlights
🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console. Changelog
Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here. You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension. Footnotes
|
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
| # PaperBot → Agentic Research 演进方案 | ||
|
|
||
| > **版本**: v1.0 · **日期**: 2026-03-02 | ||
| > **关联文档**: [OpenClaw 源码综述](./OPENCLAW_RESEARCH_REPORT.md) · [P2C 记忆优化](./P2C_MEMORY_AND_CONTEXT_OPTIMIZATION.md) · [架构总览](./architecture_overview.md) |
There was a problem hiding this comment.
此文件中的链接 [P2C 记忆优化](./P2C_MEMORY_AND_CONTEXT_OPTIMIZATION.md) 已损坏。根据本次 PR 的文件结构变更，P2C_MEMORY_AND_CONTEXT_OPTIMIZATION.md 文件已被移动到 docs/p2c/ 子目录中。为了修复此链接，请更新其路径。
| > **关联文档**: [OpenClaw 源码综述](./OPENCLAW_RESEARCH_REPORT.md) · [P2C 记忆优化](./P2C_MEMORY_AND_CONTEXT_OPTIMIZATION.md) · [架构总览](./architecture_overview.md) | |
| > **关联文档**: [OpenClaw 源码综述](./OPENCLAW_RESEARCH_REPORT.md) · [P2C 记忆优化](./p2c/P2C_MEMORY_AND_CONTEXT_OPTIMIZATION.md) · [架构总览](./architecture_overview.md) |
|
|
||
| ## Part 4: Agentic Research 演进与 OpenClaw 集成 (2026-03-02 更新) | ||
|
|
||
| > 本节为后续调研补充。完整方案见 [AGENTIC_RESEARCH_EVOLUTION.md](./AGENTIC_RESEARCH_EVOLUTION.md)。 |
There was a problem hiding this comment.
此文件中的链接 [AGENTIC_RESEARCH_EVOLUTION.md](./AGENTIC_RESEARCH_EVOLUTION.md) 已损坏。由于此文件位于 docs/p2c/ 子目录中，而目标文件位于父目录 docs/ 中，因此需要使用相对路径 ../ 来访问。
| > 本节为后续调研补充。完整方案见 [AGENTIC_RESEARCH_EVOLUTION.md](./AGENTIC_RESEARCH_EVOLUTION.md)。 | |
| > 本节为后续调研补充。完整方案见 [AGENTIC_RESEARCH_EVOLUTION.md](../AGENTIC_RESEARCH_EVOLUTION.md)。 |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
🧹 Nitpick comments (2)
docs/AGENTIC_RESEARCH_EVOLUTION.md (1)
1-549: Comprehensive Agentic Research evolution plan with clear roadmap!This document provides an excellent strategic blueprint for evolving PaperBot into an Agentic Research platform with OpenClaw integration. The gap analysis is thorough, the integration architecture is well-reasoned (Hybrid Plugin + Bridge approach), and the 4-phase implementation plan has clear milestones and acceptance criteria.
Key strengths:
- Detailed current-state gap analysis across agent/search/workflow/memory layers
- Well-justified integration approach (8/10 scoring)
- Clear memory layering strategy (Layer 0-3) aligned with other docs
- Concrete code examples for proposed APIs
- Risk assessment with mitigation strategies
Minor suggestion: Consider adding language identifiers to the fenced code blocks (currently flagged as warnings by markdownlint) to improve syntax highlighting in rendered documentation.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/AGENTIC_RESEARCH_EVOLUTION.md` around lines 1 - 549, The markdown code fences in this document lack language identifiers causing markdownlint warnings; update each fenced block that shows sample code or diagrams (e.g., the BaseAgent ReAct example, ResearchLoopAgent class, CitationGraphClient, DAGPipeline, and AgentReachClient blocks) by adding the appropriate language tag after the opening triple backticks (for example python for Python snippets, or text/mermaid for diagrams) so syntax highlighting and linting warnings are resolved.docs/OPENCLAW_RESEARCH_REPORT.md (1)
1-1518: Exceptionally comprehensive OpenClaw architecture analysis!This 1,518-line document provides deep technical analysis of 22 OpenClaw modules with excellent coverage of:
- Core subsystems (Memory, Agents, Gateway, Cron, Channels)
- Infrastructure components (Security, Secrets, Browser, TTS)
- Plugin architecture and SDK
- Cross-module patterns and design decisions
The analysis is particularly valuable for:
- Detailed code-level references with line numbers
- 25+ identified design patterns (section 22.5)
- PaperBot integration feasibility assessment (section 23, scored 8/10)
- Concrete integration points and migration considerations
Suggestion: Given the 18+ code examples throughout the document, consider adding language identifiers (
typescript,sql,python, etc.) to fenced code blocks for better syntax highlighting and documentation clarity.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/OPENCLAW_RESEARCH_REPORT.md` around lines 1 - 1518, The doc contains many fenced code blocks without language tags (e.g., the Memory Schema snippet, the hybrid.ts / buildFtsQuery() example, the sqlite-vec SQL snippet in manager-search.ts, and other examples like TTS directives and JSON fragments); update all triple-backtick fences to include the appropriate language identifier (for example typescript for TypeScript snippets (Memory Schema, hybrid.ts, buildAgentSystemPrompt()), sql for raw SQL blocks (sqlite-vec queries), json for JSON/YAML examples, bash for shell snippets, python where Python is shown) so tooling/MD renderers get correct syntax highlighting; search for all ``` blocks across the document and add the language token consistent with surrounding context and the referenced symbols (MemoryIndexManager, buildFtsQuery, manager-search.ts SQL, tts/tts.ts directives, includes.ts JSON examples), then run a markdown linter/preview to verify no malformed fences remain.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Nitpick comments:
In `@docs/AGENTIC_RESEARCH_EVOLUTION.md`:
- Around line 1-549: The markdown code fences in this document lack language
identifiers causing markdownlint warnings; update each fenced block that shows
sample code or diagrams (e.g., the BaseAgent ReAct example, ResearchLoopAgent
class, CitationGraphClient, DAGPipeline, and AgentReachClient blocks) by adding
the appropriate language tag after the opening triple backticks (for example
python for Python snippets, or text/mermaid for diagrams) so syntax highlighting
and linting warnings are resolved.
In `@docs/OPENCLAW_RESEARCH_REPORT.md`:
- Around line 1-1518: The doc contains many fenced code blocks without language
tags (e.g., the Memory Schema snippet, the hybrid.ts / buildFtsQuery() example,
the sqlite-vec SQL snippet in manager-search.ts, and other examples like TTS
directives and JSON fragments); update all triple-backtick fences to include the
appropriate language identifier (for example typescript for TypeScript snippets
(Memory Schema, hybrid.ts, buildAgentSystemPrompt()), sql for raw SQL blocks
(sqlite-vec queries), json for JSON/YAML examples, bash for shell snippets,
python where Python is shown) so tooling/MD renderers get correct syntax
highlighting; search for all ``` blocks across the document and add the language
token consistent with surrounding context and the referenced symbols
(MemoryIndexManager, buildFtsQuery, manager-search.ts SQL, tts/tts.ts
directives, includes.ts JSON examples), then run a markdown linter/preview to
verify no malformed fences remain.
ℹ️ Review info
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
⛔ Files ignored due to path filters (1)
asset/notifydemo.pdfis excluded by!**/*.pdf
📒 Files selected for processing (21)
README.mdasset/paperbot-workflow.drawiodocs/AGENTIC_RESEARCH_EVOLUTION.mddocs/ANCHOR_TODO.mddocs/OPENCLAW_RESEARCH_REPORT.mddocs/anchor_author_implementation.mddocs/anchor_source_authority_model.mddocs/anchor_system.mddocs/design/research-page-redesign-v2.mddocs/design/research-page-redesign-v3.mddocs/memory.mddocs/memory_module_complete_proposal.mddocs/memory_system.mddocs/p2c/P2C_MEMORY_AND_CONTEXT_OPTIMIZATION.mddocs/p2c/P2C_MODULE1_BENCHMARK.mddocs/p2c/P2C_MODULE_1_CORE_ENGINE.mddocs/p2c/P2C_MODULE_2_API_STORAGE.mddocs/p2c/P2C_MODULE_3_FRONTEND.mddocs/p2c/PAPER_TO_CONTEXT_MODULE_DESIGN.mdvalidate_datasets.pyverify_claude.py
💤 Files with no reviewable changes (9)
- docs/memory.md
- docs/ANCHOR_TODO.md
- validate_datasets.py
- docs/design/research-page-redesign-v2.md
- verify_claude.py
- docs/design/research-page-redesign-v3.md
- docs/memory_module_complete_proposal.md
- docs/anchor_source_authority_model.md
- docs/anchor_author_implementation.md
…turity table - Delete orphaned files: validate_datasets.py, verify_claude.py - Move non-doc assets (notifydemo.pdf, paperbot-workflow.drawio) to asset/ - Remove outdated design iterations (v2, v3) - Merge 3 anchor docs into docs/anchor_system.md - Merge 2 memory docs into docs/memory_system.md - Move 6 P2C docs into docs/p2c/ subdirectory - Update README module maturity: memory system, context engine, add daily push - Update README doc index to reflect reorganized docs Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
There was a problem hiding this comment.
Pull request overview
This PR reorganizes the repository documentation by consolidating overlapping docs (anchor/memory/P2C), moving design assets into asset/, removing orphan scripts/files, and updating the README’s module maturity and roadmap to reflect the new doc structure and planned epics.
Changes:
- Remove orphan scripts (
verify_claude.py,validate_datasets.py) and delete outdated design iteration docs (v2/v3). - Add/relocate major documentation sets: P2C design/module docs under
docs/p2c/, plus unifieddocs/memory_system.mdanddocs/anchor_system.md. - Update
README.md(maturity table + roadmap + doc index) and addasset/paperbot-workflow.drawio.
Reviewed changes
Copilot reviewed 15 out of 22 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| verify_claude.py | Deleted orphan Claude verification script. |
| validate_datasets.py | Deleted dataset validation helper script. |
| docs/p2c/PAPER_TO_CONTEXT_MODULE_DESIGN.md | Added comprehensive P2C module design spec. |
| docs/p2c/P2C_MODULE_1_CORE_ENGINE.md | Added P2C core engine design + data model contract. |
| docs/p2c/P2C_MODULE_2_API_STORAGE.md | Added P2C API/storage/SSE/persistence design. |
| docs/p2c/P2C_MODULE_3_FRONTEND.md | Added frontend integration design for P2C (Papers/Studio/SSE). |
| docs/p2c/P2C_MODULE1_BENCHMARK.md | Added benchmark doc for Module 1 extraction quality. |
| docs/p2c/P2C_MEMORY_AND_CONTEXT_OPTIMIZATION.md | Added context/memory optimization analysis and roadmap linkage. |
| docs/memory_system.md | Added consolidated memory system doc (middleware + architecture proposal). |
| docs/memory_module_complete_proposal.md | Removed superseded memory proposal doc. |
| docs/memory.md | Removed superseded memory doc. |
| docs/design/research-page-redesign-v2.md | Removed old design iteration doc. |
| docs/design/research-page-redesign-v3.md | Removed old design iteration doc. |
| docs/anchor_system.md | Added consolidated anchor system doc (theory + implementation plan). |
| docs/anchor_author_implementation.md | Removed superseded anchor implementation doc. |
| docs/ANCHOR_TODO.md | Removed superseded anchor TODO doc. |
| docs/AGENTIC_RESEARCH_EVOLUTION.md | Added Agentic Research evolution plan + OpenClaw integration architecture. |
| asset/paperbot-workflow.drawio | Added workflow diagram asset (draw.io). |
| README.md | Updated maturity table, roadmap phases, and doc index links. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
|
|
||
| > 基于 OpenClaw 记忆机制调研 + PaperBot 现有系统诊断，提出 7 项优化建议。 | ||
| > | ||
| > 关联文档：[P2C Overview](./P2C_OVERVIEW.md) · [Module 1 Core Engine](./P2C_MODULE_1_CORE_ENGINE.md) · [Module 2 API & Storage](./P2C_MODULE_2_API_STORAGE.md) |
There was a problem hiding this comment.
该文档顶部的关联链接指向 ./P2C_OVERVIEW.md，但 docs/p2c/ 目录中没有该文件，导致链接失效。建议改为指向现有的总览文档（如 PAPER_TO_CONTEXT_MODULE_DESIGN.md）或补充新增 P2C_OVERVIEW.md。
| > 关联文档：[P2C Overview](./P2C_OVERVIEW.md) · [Module 1 Core Engine](./P2C_MODULE_1_CORE_ENGINE.md) · [Module 2 API & Storage](./P2C_MODULE_2_API_STORAGE.md) | |
| > 关联文档：[P2C Overview](./PAPER_TO_CONTEXT_MODULE_DESIGN.md) · [Module 1 Core Engine](./P2C_MODULE_1_CORE_ENGINE.md) · [Module 2 API & Storage](./P2C_MODULE_2_API_STORAGE.md) |
| | 记忆系统 | 🟡 基本可用 | `/research/memory/*` | — | FTS5 + BM25 文件记忆优先, Embedding 可选增强; OpenClaw 三层架构参考 | | ||
| | Context Engine | 🟡 基本可用 | `/research/context` | — | Track Router + Engine 框架 + 本地 DB 搜索回退; 推荐系统采用文件系统 + BM25 优先策略, 无需重型 ML 模型 | |
There was a problem hiding this comment.
README 这里描述“FTS5 + BM25 文件记忆优先 / 文件系统 + BM25 优先策略”，但当前代码库中 memory/context 侧未找到 FTS5/BM25 或基于文件系统的检索实现（SqlAlchemyMemoryStore.search_memories() 仍是 SQLite contains + token overlap）。建议把成熟度描述改为与现状一致，或在同一 PR 里补齐实现再宣称。
| | 记忆系统 | 🟡 基本可用 | `/research/memory/*` | — | FTS5 + BM25 文件记忆优先, Embedding 可选增强; OpenClaw 三层架构参考 | | |
| | Context Engine | 🟡 基本可用 | `/research/context` | — | Track Router + Engine 框架 + 本地 DB 搜索回退; 推荐系统采用文件系统 + BM25 优先策略, 无需重型 ML 模型 | | |
| | 记忆系统 | 🟡 基本可用 | `/research/memory/*` | — | 基于 SQLite LIKE + token overlap 的文件记忆索引，Embedding 计划后续接入；FTS5/BM25 检索方案仍在规划中 | | |
| | Context Engine | 🟡 基本可用 | `/research/context` | — | Track Router + Engine 框架 + 本地 DB 搜索回退；当前使用简单 DB 搜索策略，文件系统 + BM25 推荐方案尚未落地 | |
…rity fixes - Add missing core modules: 论文发现/Discovery, 论文收割/Harvest, DeepCode Studio, 集成导入 - Add missing API endpoints: discovery/seed, collections, bibtex import, zotero sync, harvest, jobs, runs, newsletter, studio-chat - Add missing infra dirs: connectors/, harvesters/, crawling/ - Merge duplicate Push/Notify + 每日推送 rows in maturity table - Add new maturity rows: Discovery, DeepCode Studio, Harvest, Import/Sync - Update Push/Notify to reflect Apprise multi-channel plans - Add data source OpenAlex to header - Add Roadmap Phase 6 (每日推送优化) and Epic #179 - Add OpenClaw/OpenClaw-RL to 致谢 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
a0a884f to
0802824
Compare
There was a problem hiding this comment.
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
README.md (1)
337-356:⚠️ Potential issue | 🟡 MinorFix incorrect endpoint path:
/api/studio-chatshould be/api/studio/chat.The API endpoint documented for Studio Chat uses a hyphen separator, but the actual implementation uses a forward slash. The route decorator in
src/paperbot/api/routes/studio_chat.pydefines the endpoint as@router.post("/studio/chat"), which translates to/api/studio/chatwhen mounted. Update the README table entry to reflect the correct path.All other 19+ new API endpoints are correctly implemented in the backend and match their README documentation.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@README.md` around lines 337 - 356, The README lists the Studio Chat endpoint as `/api/studio-chat` but the actual route is registered as `@router.post("/studio/chat")`; update the README table entry to `/api/studio/chat` so it matches the route decorator and mounted path; ensure only the path string in the table row for Studio Chat is changed and leave the rest of the row text unchanged.
🧹 Nitpick comments (1)
docs/anchor_system.md (1)
60-60: Add language specifiers to fenced code blocks.The code blocks at lines 60 and 97 are missing language specifiers, which would improve syntax highlighting and readability. Based on the content, these appear to be plain text/pseudo-code blocks.
📝 Suggested improvement
For line 60:
-``` +```text anchor_score(source, domain, time, observer) → [0, 1]For line 97: ```diff -``` +```text T_E = {authors, published_at, cites, coauthors, belongs_to, listed_on, has_repo, researches}</details> Also applies to: 97-97 <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against the current code and only fix it if needed.
In
@docs/anchor_system.mdat line 60, Add a language specifier (e.g., "text") to
the fenced code blocks containing the pseudo-code examples so they render with
proper syntax highlighting and readability; specifically update the blocks that
show "anchor_score(source, domain, time, observer) → [0, 1]" and the block with
"T_E = {authors, published_at, cites, coauthors, belongs_to, listed_on,
has_repo, researches}" to use a leading triple-backtick with the language label
(e.g., ```text) and a closing triple-backtick.</details> </blockquote></details> </blockquote></details> <details> <summary>🤖 Prompt for all review comments with AI agents</summary>Verify each finding against the current code and only fix it if needed.
Outside diff comments:
In@README.md:
- Around line 337-356: The README lists the Studio Chat endpoint as
/api/studio-chatbut the actual route is registered as
@router.post("/studio/chat"); update the README table entry to
/api/studio/chatso it matches the route decorator and mounted path; ensure
only the path string in the table row for Studio Chat is changed and leave the
rest of the row text unchanged.
Nitpick comments:
In@docs/anchor_system.md:
- Line 60: Add a language specifier (e.g., "text") to the fenced code blocks
containing the pseudo-code examples so they render with proper syntax
highlighting and readability; specifically update the blocks that show
"anchor_score(source, domain, time, observer) → [0, 1]" and the block with "T_E
= {authors, published_at, cites, coauthors, belongs_to, listed_on, has_repo,
researches}" to use a leading triple-backtick with the language label (e.g.,
ℹ️ Review info
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
⛔ Files ignored due to path filters (1)
asset/notifydemo.pdfis excluded by📒 Files selected for processing (19)
README.mdasset/paperbot-workflow.drawiodocs/ANCHOR_TODO.mddocs/anchor_author_implementation.mddocs/anchor_source_authority_model.mddocs/anchor_system.mddocs/design/research-page-redesign-v2.mddocs/design/research-page-redesign-v3.mddocs/memory.mddocs/memory_module_complete_proposal.mddocs/memory_system.mddocs/p2c/P2C_MEMORY_AND_CONTEXT_OPTIMIZATION.mddocs/p2c/P2C_MODULE1_BENCHMARK.mddocs/p2c/P2C_MODULE_1_CORE_ENGINE.mddocs/p2c/P2C_MODULE_2_API_STORAGE.mddocs/p2c/P2C_MODULE_3_FRONTEND.mddocs/p2c/PAPER_TO_CONTEXT_MODULE_DESIGN.mdvalidate_datasets.pyverify_claude.py💤 Files with no reviewable changes (9)
- docs/design/research-page-redesign-v3.md
- verify_claude.py
- docs/design/research-page-redesign-v2.md
- docs/anchor_source_authority_model.md
- docs/memory.md
- docs/anchor_author_implementation.md
- docs/memory_module_complete_proposal.md
- validate_datasets.py
- docs/ANCHOR_TODO.md
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 12 out of 20 changed files in this pull request and generated no new comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Summary
validate_datasets.py,verify_claude.pyanchor_system.mdmemory_system.mddocs/p2c/子目录notifydemo.pdf,paperbot-workflow.drawio到asset/净减 2383 行，文档结构更清晰。
Test plan
🤖 Generated with Claude Code
Summary by CodeRabbit
Release Notes
New Features
Documentation
Chores