Add local project snapshots and plans

Capture the current local data snapshot and planning artifacts alongside
this development batch so the workspace state matches the code changes.
This preserves the reference materials and generated files that were
kept in the working tree.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

backend/data/uploads/1aa193ee-7f60-4dba-b8cf-03c5a21d7547.docx

@@ -0,0 +1 @@
+bad

backend/data/uploads/4eb88bb9-12e7-4239-a628-875e05a4fbc5.pdf

@@ -0,0 +1 @@
+%PDF-1.4 bad

backend/data/uploads/5b1081ac-e190-4d02-ba0c-2d3f6830fbb2.docx

@@ -0,0 +1 @@
+bad

backend/data/uploads/65f4a975-fa8f-4832-869e-d44f02352bc0.docx

@@ -0,0 +1 @@
+bad

backend/data/uploads/83f23fad-0d31-4383-8416-9651244db1d3.pdf

@@ -0,0 +1 @@
+%PDF-1.4 bad

backend/data/uploads/84514070-b949-4fc8-9d23-f1c9aa66df93.pdf

@@ -0,0 +1 @@
+%PDF-1.4 bad

backend/data/uploads/a6d57f51-7de5-4e8b-b7af-9a00a64f1a08.docx

@@ -0,0 +1 @@
+bad

backend/data/uploads/a7a26404-d785-468d-a59f-835fb443bcbd.docx

@@ -0,0 +1 @@
+bad

backend/data/uploads/b3405365-1dd3-41ff-a928-758c0bef2c32.docx

@@ -0,0 +1 @@
+bad

backend/data/uploads/c53861cd-9eca-485c-9048-80e93cfee8b2.txt

@@ -1,119 +0,0 @@
-远光软件股份有限公司科技项目可行性研究报告
-
-项目名称：大模型微调技术研究与应用
-
-申请部门：
-
-起止时间：年至年
-
-项目负责人：
-
-联系电话：
-
-申请日期：年 月
-
-大模型微调技术可行性研究报告
-
-远光软件股份有限公司科技项目可行性研究报告
-
-项目名称： 大模型微调技术研究与应用
-
-申请部门：
-
-起止时间： 年 月至 年 月
-
-项目负责人：
-
-联系电话：
-
-申请日期： 年 月
-
-一、目的和意义
-
-1.1 项目背景与需求
-
-近年来，以深度学习为基础的大型预训练语言模型（Large Language Models,
-LLMs）如GPT系列、BERT、LLaMA等在自然语言处理领域取得了突破性进展，通过海量数据的预训练和超大规模参数量，这些模型展现出强大的通用语言理解与生成能力，在机器翻译、文本摘要、问答系统、内容创作等众多任务中表现出色，引领了人工智能技术的新浪潮。然而，这些通用大模型在面对特定专业领域任务时，往往存在知识覆盖不足、专业术语理解偏差、领域特定逻辑推理能力欠缺、输出风格不符合行业特点等问题，难以直接满足垂直场景的应用需求。
-
-模型微调（Fine-tuning）技术作为将通用大模型适配到特定场景的关键手段，通过在领域相关数据上进一步训练模型参数，使模型能够吸收领域知识、适应特定任务要求，从而显著提升模型在目标任务上的性能表现。随着大模型参数规模的不断扩大，传统的全参数微调方式面临着计算资源消耗大、存储成本高、容易产生灾难性遗忘等挑战，因此，参数高效微调（Parameter-Efficient
-Fine-Tuning,
-PEFT）方法如LoRA、Adapter、Prefix-tuning等技术应运而生，为低成本、高效率的大模型领域适配提供了新的技术路径。
-
-本项目旨在探索适合特定领域特点的高效微调策略，解决数据稀缺性、专业术语理解、领域知识融合等关键技术问题，提升模型在特定场景下的准确性、可靠性和实用性。
-
-项目成果将对该现状和技术发展的作用主要体现在技术推动作用和应用落地支撑两方面。
-
-二、国内外研究水平综述
-
-2.1 技术发展历史简要回顾
-
-大模型微调技术的发展历程分为四个阶段：
-
-第一阶段（2018年前）：传统迁移学习与微调雏形阶段。模型适配多采用传统迁移学习思路，将通用数据集上训练的基础模型迁移至特定任务场景。
-
-第二阶段（2018-2020年）：预训练-微调范式确立阶段。2018年谷歌提出BERT模型，首次构建"预训练通用知识+下游任务微调"的技术框架。
-
-第三阶段（2020-2022年）：高效微调技术爆发阶段。LoRA、QLoRA、Adapter等参数高效微调技术相继出现，将微调参数规模大幅降低。
-
-第四阶段（2022年至今）：垂直领域深化与协同优化阶段。"基座模型+领域微调"的架构成为主流，微调技术与知识图谱进一步融合。
-
-2.2 国内外研究水平现状和发展趋势
-
-国际层面，Hugging
-Face、DeepSpeed等开源社区为参数高效微调技术的普及提供了重要支撑。国内层面，阿里云基于通义千问进行财税领域定制微调，验证了微调技术在财务领域的应用价值。
-
-三、项目的理论和实践依据
-
-3.1 项目研究内容原理简述
-
-本项目采用"基座模型+领域适配"分层微调架构，选取开源基座模型，针对财务问答场景特性采用LoRA参数高效微调策略。
-
-3.2 项目研究内容理论和实践依据
-
-理论依据包括国家战略层面的政策支持和成熟的技术理论体系。实践依据包括大模型微调技术在财务等垂直领域的成功案例。
-
-3.3 项目研究的关键和难点
-
-关键点包括高质量数据集构建、高效微调策略适配、知识精准注入与幻觉抑制、效果评估体系建设。难点集中在数据处理、微调策略、知识注入和评估体系四个方面。
-
-四、项目研究内容和实施方案
-
-4.1 项目研究内容详细说明
-
-本项目研究内容包括数据格式研究、微调框架研究、模型微调后评估体系研究三个方面。
-
-4.2 理论研究步骤和试验计划
-
-包括数据处理流程、训练数据生成流程、数据验证流程三个主要环节。
-
-4.3 项目组织方式和协作分工
-
-本项目由项目负责人统筹协调，下设数据组、算法组、应用组三个工作小组。
-
-五、预期目标和成果形式
-
-5.1 项目研究预期达到的目标
-
-技术目标：问答准确率达到85%以上。应用目标：开发财务智能知识问答原型系统。效益目标：替代财务专家70%以上的重复性咨询工作。
-
-5.2 明确叙述提高研究成果的形式
-
-包括技术方案文档、原型系统、训练数据集、微调模型、技术论文/报告等成果形式。
-
-六、项目承担团队的条件
-
-项目团队具备人工智能、大数据等领域的技术背景，具备财务信息系统开发经验，具备充足的GPU计算资源和完善的开发测试环境。
-
-七、项目进度安排
-
-第1-2月：项目启动、需求分析；第3-4月：数据收集、清洗；第5-7月：数据集生成；第8-10月：模型训练；第11-12月：系统开发；第13-14月：优化整理；第15-16月：验收转化。
-
-八、项目经费预算
-
-本项目经费预算根据实际研究工作需要编制，包括人工费、设备使用费、业务费、场地使用费、专家咨询费等科目。
-
-分管领导审核意见：
-
-（对经费预算是否合理，有无其他经费来源，能否保证研究计划实施所需的人力，工作时间等基本条件提出具体意见）
-
-分管领导（签字）： 年 月 日

backend/data/uploads/e21928b2-18ab-495a-98c0-e5bc88a62922.pdf

@@ -0,0 +1 @@
+%PDF-1.4 bad

backend/data/uploads/e55607ca-2d0e-416a-8219-bb603055b354.pdf

@@ -0,0 +1 @@
+%PDF-1.4 bad

brain_phase1_blueprint.md

@@ -0,0 +1,427 @@
+# Jarvis Knowledge Brain Phase 1 Blueprint
+
+## 1. Phase 1 Goal
+Phase 1 establishes the first production-ready version of Jarvis's event-driven knowledge brain. The objective is not to finish the entire intelligence system, but to create the minimum architecture that lets Jarvis ingest key user actions from across the product, learn from them on a daily schedule, store only high-value knowledge, and retrieve that knowledge during future conversations.
+
+Phase 1 should make the brain real in six ways:
+1. unify source events across core modules;
+2. create an intermediate candidate-learning layer;
+3. promote durable knowledge into long-term brain memory;
+4. maintain tags and time-aware traceability;
+5. expose APIs for inspection and management;
+6. allow the chat system to retrieve brain knowledge during answers.
+
+---
+
+## 2. Scope Boundaries
+
+### In scope
+- New persistence models for brain events, candidates, memories, tags, and relationships.
+- Ingestion of source signals from conversations, knowledge documents, todos, kanban tasks, and forum posts.
+- A daily autonomous learning pipeline that tags, scores, deduplicates, and upgrades knowledge.
+- Retrieval integration for future responses.
+- Brain dashboard APIs.
+- A new frontend brain module structure replacing the current graph-only mental model.
+
+### Out of scope for phase 1
+- Full graph-native reasoning engine.
+- Fully autonomous suggestion orchestration across all screens.
+- Complex reinforcement-learning style adaptation.
+- Fine-grained user-tunable learning policy UI.
+- Automatic deletion and archival heuristics beyond simple status transitions.
+
+---
+
+## 3. Target Architecture
+Phase 1 should introduce a four-layer brain pipeline:
+
+1. **Source Records**
+   Existing domain tables remain the source of truth: messages, documents/chunks, todos, tasks, forum posts/replies.
+
+2. **BrainEvent**
+   A normalized event layer representing meaningful user/system actions. This is the single intake format for downstream learning.
+
+3. **BrainCandidate**
+   AI-generated candidate knowledge distilled from one or more events. Candidates are scored, tagged, typed, and traced back to source events.
+
+4. **BrainMemory**
+   Durable long-term memory that Jarvis can retrieve during future interactions. This becomes the brain's core persistence layer.
+
+Graph visualization should be treated as a **projection layer**, not the primary storage model. In later phases, graph nodes and edges can be generated from BrainMemory records and their relationships.
+
+---
+
+## 4. Data Model Additions
+
+### 4.1 BrainEvent
+Purpose: normalized raw learning input.
+
+Recommended fields:
+- `id`
+- `user_id`
+- `source_type` (`conversation`, `document`, `todo`, `task`, `forum_post`, `forum_reply`)
+- `source_id`
+- `event_type` (`created`, `updated`, `completed`, `mentioned`, `uploaded`, `resolved`, `marked_important`, etc.)
+- `occurred_at`
+- `event_date`
+- `title`
+- `content_summary`
+- `raw_excerpt`
+- `metadata_` (JSON; source-specific facts such as conversation_id, task status, folder path)
+- `importance_signal` (numeric seed score)
+- `is_user_pinned`
+- `processed_at`
+- `status` (`pending`, `processed`, `ignored`)
+
+Indexes:
+- `(user_id, event_date)`
+- `(user_id, source_type, source_id)`
+- `(user_id, status, occurred_at)`
+
+### 4.2 BrainCandidate
+Purpose: intermediate learned knowledge awaiting acceptance into durable memory.
+
+Recommended fields:
+- `id`
+- `user_id`
+- `candidate_type` (`preference`, `habit`, `project_fact`, `decision`, `solution`, `topic`, `goal`, `temporary_focus`)
+- `title`
+- `summary`
+- `importance_score`
+- `confidence_score`
+- `time_scope` (`short_term`, `phase`, `long_term`)
+- `valid_from`
+- `valid_to`
+- `source_event_ids` (JSON array)
+- `reasoning_trace` (short explanation of why the system extracted it)
+- `status` (`new`, `promoted`, `rejected`, `merged`)
+- `created_at`
+- `reviewed_at`
+
+### 4.3 BrainMemory
+Purpose: durable brain knowledge used at retrieval time.
+
+Recommended fields:
+- `id`
+- `user_id`
+- `memory_type` (`preference`, `habit`, `goal`, `project_fact`, `decision`, `solution`, `topic_profile`)
+- `title`
+- `content`
+- `importance`
+- `confidence`
+- `timeline_date`
+- `first_learned_at`
+- `last_reinforced_at`
+- `reinforcement_count`
+- `status` (`active`, `archived`, `deleted`)
+- `origin_candidate_id`
+- `origin_source_types` (JSON array)
+- `metadata_` (JSON)
+
+### 4.4 BrainTag
+Purpose: independent tagging layer for brain browsing, filtering, and scoring.
+
+Recommended fields:
+- `id`
+- `user_id`
+- `name`
+- `category` (`topic`, `value`, `time`, `source`)
+- `priority` (`important`, `secondary`)
+- `score`
+- `last_seen_at`
+- `created_at`
+
+### 4.5 Link Tables
+Add many-to-many link tables:
+- `brain_event_tags`
+- `brain_candidate_tags`
+- `brain_memory_tags`
+- optional `brain_memory_events` for direct memory-to-event traceability beyond JSON arrays
+
+These link tables are critical because phase 1 needs tag filters and timeline tracing before advanced graph projection exists.
+
+---
+
+## 5. Ingestion Strategy
+Phase 1 should not rewrite existing modules. Instead, it should add thin ingestion hooks near existing write paths.
+
+### Conversation ingestion
+Trigger points:
+- after user message creation
+- after assistant completion
+- after memory extraction / summary creation
+
+Event examples:
+- important user instruction
+- explicit “remember this” request
+- repeated topic cluster
+- conversation-derived decision or unresolved goal
+
+### Document ingestion
+Trigger points:
+- after upload success
+- after indexing completes
+- after manual chunk edits
+
+Event examples:
+- document uploaded
+- document indexed
+- high-value section discovered
+- document summary available
+
+### Todo ingestion
+Trigger points:
+- todo created
+- todo completed
+- AI-generated todo created
+
+Event examples:
+- planned work item
+- recurring operational duty
+- completion signal reflecting actual user focus
+
+### Task/Kanban ingestion
+Trigger points:
+- task created
+- task status changed
+- task completed
+- priority changed
+
+Event examples:
+- declared project goal
+- active workstream
+- resolved milestone
+
+### Forum ingestion
+Trigger points:
+- post created
+- reply created
+- forum instruction executed or referenced
+
+Event examples:
+- public project decision
+- repeated operational issue
+- reusable explanation or solution
+
+Implementation note: source ingestion should create BrainEvent rows synchronously or via lightweight background tasks, but should not block the original user flow.
+
+---
+
+## 6. Learning and Promotion Pipeline
+Phase 1 should add a new daily scheduler workflow dedicated to the brain.
+
+### New scheduler job: `brain_daily_learning_task`
+Suggested run: once daily after the bulk of user activity, for example 01:00 or configurable per user later.
+
+Pipeline steps:
+1. collect unprocessed `BrainEvent` rows for the target date;
+2. cluster by source, topic, and repeated patterns;
+3. ask the LLM to produce candidate knowledge with tags and importance explanations;
+4. deduplicate against existing `BrainMemory` by semantic and rule-based matching;
+5. promote high-confidence candidates into `BrainMemory`;
+6. mark low-value candidates rejected or retained as observation-only;
+7. refresh tag scores and priority levels;
+8. mark consumed events as processed.
+
+### Promotion rules for phase 1
+Promote automatically when any of these are true:
+- user explicitly requested the system to remember something;
+- the same topic appears across multiple sources;
+- a solution/decision was formed and looks reusable;
+- a stable preference or habit is seen repeatedly;
+- a task/todo/forum thread confirms relevance with user action.
+
+Keep as candidate-only when:
+- information is recent but not yet stable;
+- importance is uncertain;
+- it appears only once without reinforcement.
+
+Reject when:
+- content is obviously transient;
+- it is too generic to help future answers;
+- it duplicates active memory without adding new value.
+
+---
+
+## 7. Retrieval Integration
+Phase 1 must let chat use the brain in a controlled way.
+
+### New retrieval service
+Add a dedicated `brain_retrieval_service` or extend `memory_service` with brain-aware retrieval APIs.
+
+Responsibilities:
+- retrieve top relevant `BrainMemory` rows by query, tags, time context, and importance;
+- optionally retrieve recent `BrainEvent` summaries for recency-sensitive answers;
+- merge existing `UserMemory` and `MemorySummary` into one retrieval result shape;
+- support limits to avoid prompt bloat.
+
+### Retrieval policy
+At answer time:
+- always consider long-term `BrainMemory`;
+- include recent event summaries only when the question appears time-sensitive or project-state-sensitive;
+- cap injected brain context to a small curated set.
+
+Recommended first integration path:
+- extend `build_memory_context()` to append a new `【知识大脑】` block built from `BrainMemory` retrieval.
+- keep existing conversation summary logic intact.
+
+This gives immediate product value without requiring a full prompt orchestration rewrite.
+
+---
+
+## 8. Backend Services to Add or Refactor
+
+### New services
+1. `brain_event_service.py`
+   - normalize incoming source data into BrainEvent rows
+   - provide source-specific helper constructors
+
+2. `brain_learning_service.py`
+   - run daily candidate extraction
+   - score, dedupe, and promote memories
+
+3. `brain_tag_service.py`
+   - manage tags, scoring, priority updates, and cleanup suggestions
+
+4. `brain_retrieval_service.py`
+   - retrieve relevant memories and recent events for chat and UI
+
+### Existing services to extend
+- `memory_service.py`: integrate BrainMemory retrieval and possibly migrate `UserMemory` into the new model later
+- `scheduler_service.py`: register brain daily learning job
+- `agent_service.py`: inject retrieved brain context into chat pipeline
+- `document_service.py`, `todo_service.py`, task/forum write paths: emit BrainEvent rows
+
+---
+
+## 9. API Plan
+Phase 1 should add a dedicated `/api/brain` router.
+
+### Read APIs
+- `GET /api/brain/overview`
+  - counts: active memories, candidates, important tags, recent events
+  - today's learning summary
+
+- `GET /api/brain/memories`
+  - filters: tag, type, status, date range, source type
+
+- `GET /api/brain/candidates`
+  - filters: status, date, score threshold
+
+- `GET /api/brain/tags`
+  - segmented into important and secondary
+
+- `GET /api/brain/timeline`
+  - grouped by day/week; includes events, candidate promotions, reinforced memories
+
+- `GET /api/brain/memory/{id}`
+  - full traceability including linked events and tags
+
+### Write/management APIs
+- `POST /api/brain/memory/{id}/promote`
+- `POST /api/brain/memory/{id}/archive`
+- `DELETE /api/brain/memory/{id}`
+- `POST /api/brain/tag/{id}/promote`
+- `POST /api/brain/tag/{id}/demote`
+- `DELETE /api/brain/tag/{id}`
+- `POST /api/brain/learn/run`
+  - manual trigger for daily learning pipeline
+
+### Compatibility note
+Do not remove `/api/graph` in phase 1. Keep it as a legacy projection route while the new brain module is introduced.
+
+---
+
+## 10. Frontend Module Structure
+The current `知识大脑` nav item should stop meaning “graph only” and become a real brain dashboard.
+
+### Route strategy
+Preferred phase 1 structure:
+- `/brain` → new knowledge brain dashboard
+- `/graph` → graph view tab or subview under the brain module, retained for relation visualization
+
+### Brain dashboard sections
+1. **Overview header**
+   - total active memories
+   - today's learned items
+   - important tags count
+   - last learning run
+
+2. **Important tags panel**
+   - AI-ranked important tags
+   - click to filter related memories and timeline entries
+
+3. **Secondary tags panel**
+   - lower-priority tags with cleanup actions
+
+4. **Recent learned knowledge**
+   - newly promoted memories
+   - reasons and source badges
+
+5. **Timeline panel**
+   - daily grouped events and promotions
+   - support time-based backtracking
+
+6. **Graph subview**
+   - optional tab or secondary panel for relation projection
+
+### User actions in phase 1
+- delete memory
+- archive memory
+- promote/demote tag priority
+- manually trigger learning run
+- inspect why a memory exists
+
+This is enough to make the brain visible and manageable even before advanced graph reasoning exists.
+
+---
+
+## 11. Suggested Delivery Breakdown
+
+### Step 1: Persistence foundation
+- add brain models and migrations
+- add SQLAlchemy registrations and schemas
+
+### Step 2: Event ingestion
+- emit BrainEvent rows from conversation/document/todo/task/forum flows
+
+### Step 3: Learning workflow
+- implement daily learning job and manual trigger API
+
+### Step 4: Retrieval integration
+- wire BrainMemory into chat context assembly
+
+### Step 5: Brain dashboard backend
+- add overview, memories, tags, timeline endpoints
+
+### Step 6: Brain dashboard frontend
+- add `/brain` page and move graph into a subview or separate tab
+
+---
+
+## 12. Risks and Guardrails
+
+### Main risks
+- over-collection leading to noisy memories;
+- prompt bloat from injecting too much brain context;
+- duplicate memory creation across repeated daily runs;
+- unclear distinction between candidate and durable memory;
+- UI becoming graph-centric again instead of brain-centric.
+
+### Guardrails
+- enforce candidate layer before promotion;
+- cap retrieval size strictly;
+- keep source traceability for every promoted memory;
+- make tag cleanup explicit in UI;
+- treat graph as a projection, not the source of truth.
+
+---
+
+## 13. Phase 1 Success Criteria
+Phase 1 is successful when all of the following are true:
+- the system creates normalized BrainEvent rows from all five major source domains;
+- a scheduled daily learning job produces candidates and promotes high-value memories;
+- Jarvis can retrieve durable brain memories during future answers;
+- the frontend exposes a real brain dashboard with tags, recent knowledge, and timeline;
+- users can inspect and clean what the system learned;
+- the old graph page is no longer the only visible representation of the brain.

brain_phase1_task_breakdown.md

@@ -0,0 +1,555 @@
+# Jarvis Knowledge Brain Phase 1 Task Breakdown
+
+## Goal
+Turn the phase-1 knowledge brain blueprint into an execution-ready development task list tied to the current codebase.
+
+---
+
+## A. Backend Persistence Tasks
+
+### A1. Add new brain models
+Create new SQLAlchemy models under `backend/app/models/`:
+- `brain_event.py`
+- `brain_candidate.py`
+- `brain_memory.py`
+- `brain_tag.py`
+- optional link-table definitions in `brain_relations.py` or colocated within the above files
+
+Core entities to add:
+- `BrainEvent`
+- `BrainCandidate`
+- `BrainMemory`
+- `BrainTag`
+- `BrainEventTag`
+- `BrainCandidateTag`
+- `BrainMemoryTag`
+- optional `BrainMemoryEvent`
+
+Acceptance criteria:
+- All models inherit from the project base model pattern.
+- All required enums/status fields are defined.
+- User ownership and timeline fields exist.
+- Link tables support tag filtering and source traceability.
+
+### A2. Register models in model exports
+Update:
+- `backend/app/models/__init__.py`
+
+Acceptance criteria:
+- New brain models are imported and available during metadata initialization.
+
+### A3. Add migration / schema evolution support
+Depending on current project migration approach, add the required DB migration path for the new tables.
+
+Acceptance criteria:
+- New tables can be created in local/dev environments without breaking existing tables.
+- Indexes for `user_id`, status, and date-based access patterns are included.
+
+### A4. Add Pydantic schemas
+Create new schema files under `backend/app/schemas/`:
+- `brain.py`
+
+Schema groups to add:
+- overview response
+- memory list/detail response
+- candidate list response
+- tag response
+- timeline response
+- manual learning trigger response
+- memory/tag management payloads
+
+Acceptance criteria:
+- Schemas match the intended `/api/brain` response shapes.
+- Timeline and traceability structures are explicit, not loosely typed blobs.
+
+---
+
+## B. Backend Service Tasks
+
+### B1. Create brain event ingestion service
+Add:
+- `backend/app/services/brain_event_service.py`
+
+Responsibilities:
+- normalize source records into `BrainEvent`
+- expose helpers such as:
+  - `record_conversation_event(...)`
+  - `record_document_event(...)`
+  - `record_todo_event(...)`
+  - `record_task_event(...)`
+  - `record_forum_event(...)`
+
+Acceptance criteria:
+- Each helper accepts current source-domain inputs without forcing those modules to understand brain internals.
+- Event creation is idempotent enough to avoid obvious duplicate rows for the same source update.
+
+### B2. Create brain learning service
+Add:
+- `backend/app/services/brain_learning_service.py`
+
+Responsibilities:
+- load pending `BrainEvent`s for a given date/user scope
+- cluster related events
+- call the LLM to create candidate knowledge
+- score and dedupe candidates
+- promote high-confidence candidates into `BrainMemory`
+- mark processed events and candidate statuses
+
+Acceptance criteria:
+- Service supports both manual run and scheduler run.
+- Promotion/rejection decisions are explicit and testable.
+- Source event traceability is preserved.
+
+### B3. Create brain tag service
+Add:
+- `backend/app/services/brain_tag_service.py`
+
+Responsibilities:
+- attach and score tags
+- split tags into important vs secondary
+- update tag scores after learning runs
+- support cleanup recommendations
+
+Acceptance criteria:
+- Important/secondary classification is persisted, not only computed in the UI.
+- Tag lookups support filtering memories and timeline entries.
+
+### B4. Create brain retrieval service
+Add:
+- `backend/app/services/brain_retrieval_service.py`
+
+Responsibilities:
+- retrieve relevant `BrainMemory` records by query
+- optionally retrieve recent events for recency-sensitive prompts
+- format results for chat injection and API responses
+
+Acceptance criteria:
+- Retrieval has strict limits to prevent prompt bloat.
+- Results support filtering by tags, source type, and time range.
+
+### B5. Refactor or extend memory service
+Update:
+- `backend/app/services/memory_service.py`
+
+Tasks:
+- keep existing summary and `UserMemory` behavior intact
+- extend `build_memory_context()` to append a `【知识大脑】` block from `BrainRetrievalService`
+- keep memory context size bounded
+
+Acceptance criteria:
+- Existing conversation summary behavior continues to work.
+- Chat can consume `BrainMemory` without requiring a full prompt architecture rewrite.
+
+---
+
+## C. Source Ingestion Integration Tasks
+
+### C1. Conversation → BrainEvent
+Update likely files:
+- `backend/app/services/agent_service.py`
+- possibly `backend/app/services/memory_service.py`
+
+Hook points:
+- after user message persistence
+- after assistant response persistence
+- after summary/memory extraction
+
+Acceptance criteria:
+- Important conversation actions produce normalized `BrainEvent`s.
+- Explicit “remember this” signals are captured as stronger events.
+
+### C2. Document → BrainEvent
+Update likely files:
+- `backend/app/routers/document.py`
+- `backend/app/services/document_service.py`
+- `backend/app/services/knowledge_service.py`
+
+Hook points:
+- upload success
+- indexing completion
+- chunk edit / reindex
+
+Acceptance criteria:
+- Document lifecycle milestones become `BrainEvent`s.
+- Source metadata includes document identity and folder context.
+
+### C3. Todo → BrainEvent
+Update likely files:
+- `backend/app/routers/todo.py`
+- `backend/app/services/todo_service.py`
+
+Hook points:
+- todo creation
+- completion
+- AI-generated todo creation
+
+Acceptance criteria:
+- Todo events reflect both planning and completion signals.
+- AI-generated todos are distinguishable from manual ones.
+
+### C4. Task/Kanban → BrainEvent
+Update likely files:
+- `backend/app/routers/task.py`
+
+Hook points:
+- task creation
+- status change
+- completion
+- priority change
+
+Acceptance criteria:
+- Task state changes create meaningful workstream events.
+- Duplicate writes are avoided on no-op updates.
+
+### C5. Forum → BrainEvent
+Update likely files:
+- `backend/app/routers/forum.py`
+- optionally `backend/app/services/scheduler_service.py`
+
+Hook points:
+- post created
+- reply created
+- forum instruction execution
+
+Acceptance criteria:
+- Forum posts/replies that matter to project state become brain events.
+- Source traceability includes whether the event came from a post, reply, or executed instruction.
+
+---
+
+## D. Scheduler and Daily Learning Tasks
+
+### D1. Add daily brain learning job
+Update:
+- `backend/app/services/scheduler_service.py`
+
+Add:
+- `brain_daily_learning_task()`
+
+Responsibilities:
+- run daily for pending events
+- invoke `BrainLearningService`
+- log promoted/rejected counts
+
+Acceptance criteria:
+- Job is registered in `start_scheduler()`.
+- Job can run safely when there are no pending events.
+
+### D2. Add manual trigger path
+Update or add:
+- `backend/app/routers/scheduler.py` or the new `backend/app/routers/brain.py`
+
+Acceptance criteria:
+- Developers/users can manually run learning for testing.
+- Trigger returns a useful summary, not only a started flag.
+
+### D3. Decide scheduler ownership model for phase 1
+Current scheduler is global. Decide whether phase 1 runs:
+- for all users in one job, or
+- per user loop inside one job
+
+Acceptance criteria:
+- No hard-coded `user_id="default"` behavior remains in new brain learning flow.
+- User iteration strategy is explicit.
+
+---
+
+## E. Backend API Tasks
+
+### E1. Add brain router
+Create:
+- `backend/app/routers/brain.py`
+
+Register in:
+- `backend/app/main.py`
+- `backend/app/routers/__init__.py` if needed
+
+### E2. Implement overview endpoint
+Endpoint:
+- `GET /api/brain/overview`
+
+Should return:
+- active memory count
+- candidate count
+- important tag count
+- recent event count
+- last learning run info
+- today’s promoted/rejected summary
+
+### E3. Implement memory endpoints
+Endpoints:
+- `GET /api/brain/memories`
+- `GET /api/brain/memory/{id}`
+- `POST /api/brain/memory/{id}/archive`
+- `DELETE /api/brain/memory/{id}`
+- optional `POST /api/brain/memory/{id}/promote` if candidate-to-memory management is exposed here
+
+Acceptance criteria:
+- Memory detail shows source traceability and tags.
+- List endpoint supports pagination/filters needed by UI.
+
+### E4. Implement candidate endpoints
+Endpoints:
+- `GET /api/brain/candidates`
+- optional promote/reject endpoints if candidates are user-manageable in phase 1
+
+Acceptance criteria:
+- Candidate status and scoring are inspectable.
+
+### E5. Implement tag endpoints
+Endpoints:
+- `GET /api/brain/tags`
+- `POST /api/brain/tag/{id}/promote`
+- `POST /api/brain/tag/{id}/demote`
+- `DELETE /api/brain/tag/{id}`
+
+Acceptance criteria:
+- API groups tags by important vs secondary.
+- Manual cleanup actions are supported.
+
+### E6. Implement timeline endpoint
+Endpoint:
+- `GET /api/brain/timeline`
+
+Acceptance criteria:
+- Timeline groups records by day or returns a structure easily grouped by day in UI.
+- Includes event entries and memory promotion entries.
+
+### E7. Implement learning trigger endpoint
+Endpoint:
+- `POST /api/brain/learn/run`
+
+Acceptance criteria:
+- Supports manual learning run for current user or all users, depending on phase-1 policy.
+- Returns meaningful run stats.
+
+---
+
+## F. Chat Integration Tasks
+
+### F1. Inject knowledge brain into chat context
+Update:
+- `backend/app/services/agent_service.py`
+- `backend/app/services/memory_service.py`
+
+Acceptance criteria:
+- Relevant `BrainMemory` items appear in prompt context.
+- Context remains concise and bounded.
+- Existing response flow remains stable.
+
+### F2. Add retrieval policy guardrails
+Tasks:
+- define per-query memory limits
+- choose when to include recent events
+- prefer important/high-confidence memories
+
+Acceptance criteria:
+- Brain retrieval does not overwhelm standard conversation context.
+- Time-sensitive answers can still include recent context when needed.
+
+---
+
+## G. Frontend Route and Navigation Tasks
+
+### G1. Introduce a real brain route
+Update likely files:
+- `frontend/src/app/router/routes.ts`
+- `frontend/src/app/navigation/nav.ts`
+
+Tasks:
+- add `/brain`
+- make `知识大脑` point to `/brain`
+- keep `/graph` available as a subview or secondary route
+
+Acceptance criteria:
+- Brain is no longer represented only by the graph page.
+
+### G2. Define frontend brain API client
+Add:
+- `frontend/src/api/brain.ts`
+
+Methods:
+- `getOverview`
+- `getMemories`
+- `getMemoryDetail`
+- `getCandidates`
+- `getTags`
+- `getTimeline`
+- `runLearning`
+- memory/tag management actions
+
+Acceptance criteria:
+- API client matches backend router contract.
+
+---
+
+## H. Frontend Brain Dashboard Tasks
+
+### H1. Create new brain page
+Add:
+- `frontend/src/pages/brain/index.vue`
+
+Core page sections:
+- overview header
+- important tags panel
+- secondary tags panel
+- recent learned knowledge section
+- timeline section
+- graph tab/subview entry
+
+Acceptance criteria:
+- Page is useful even before graph projection is upgraded.
+- Dashboard reflects the brain, not just visualized relationships.
+
+### H2. Add page composable/state logic
+Add:
+- `frontend/src/pages/brain/composables/useBrainView.ts`
+
+Responsibilities:
+- fetch overview/tags/memories/timeline
+- manage filters and selected tags
+- trigger manual learning run
+- manage loading/error states
+
+Acceptance criteria:
+- Page logic stays separate from template complexity.
+
+### H3. Add memory list/detail components
+Suggested additions:
+- `frontend/src/components/brain/BrainMemoryList.vue`
+- `frontend/src/components/brain/BrainMemoryDetail.vue`
+- `frontend/src/components/brain/BrainTagPanel.vue`
+- `frontend/src/components/brain/BrainTimeline.vue`
+
+Acceptance criteria:
+- User can inspect why a memory exists.
+- User can archive/delete memories and promote/demote tags.
+
+### H4. Reposition graph as brain subview
+Possible approaches:
+- keep current `frontend/src/pages/graph/index.vue` but link it from `/brain`
+- or wrap the graph page as one tab inside the brain page
+
+Acceptance criteria:
+- Existing graph functionality remains accessible.
+- Product framing changes from “brain = graph” to “brain includes graph”.
+
+---
+
+## I. Testing Tasks
+
+### I1. Backend model/service tests
+Add tests for:
+- event creation
+- candidate generation status changes
+- promotion into `BrainMemory`
+- tag priority updates
+- timeline aggregation
+
+Suggested locations:
+- `backend/tests/backend/app/services/`
+- `backend/tests/backend/app/routers/`
+
+### I2. Retrieval integration tests
+Add tests for:
+- memory context injection
+- retrieval limits
+- recency-sensitive event inclusion
+
+### I3. API tests
+Add tests for:
+- `/api/brain/overview`
+- `/api/brain/memories`
+- `/api/brain/tags`
+- `/api/brain/timeline`
+- `/api/brain/learn/run`
+
+### I4. Frontend tests
+Add tests for:
+- brain composable fetch flow
+- filter behavior
+- manual learning run UI flow
+- tag grouping and memory rendering
+
+---
+
+## J. Recommended Execution Order
+
+### Wave 1: Foundation
+1. A1-A4 persistence and schemas
+2. B1 brain event service
+3. E1 add router skeleton
+
+### Wave 2: Ingestion
+4. C1-C5 connect all source domains to `BrainEvent`
+
+### Wave 3: Learning
+5. B2 brain learning service
+6. B3 brain tag service
+7. D1-D3 scheduler/manual learning
+
+### Wave 4: Retrieval
+8. B4 brain retrieval service
+9. B5 memory service integration
+10. F1-F2 chat injection and guardrails
+
+### Wave 5: Product surface
+11. E2-E7 complete `/api/brain` endpoints
+12. G1-G2 routing + API client
+13. H1-H4 dashboard and graph repositioning
+
+### Wave 6: Reliability
+14. I1-I4 tests and refinement
+
+---
+
+## K. Files Most Likely to Change in Phase 1
+
+### Backend new files
+- `backend/app/models/brain_event.py`
+- `backend/app/models/brain_candidate.py`
+- `backend/app/models/brain_memory.py`
+- `backend/app/models/brain_tag.py`
+- `backend/app/schemas/brain.py`
+- `backend/app/services/brain_event_service.py`
+- `backend/app/services/brain_learning_service.py`
+- `backend/app/services/brain_tag_service.py`
+- `backend/app/services/brain_retrieval_service.py`
+- `backend/app/routers/brain.py`
+
+### Backend existing files
+- `backend/app/models/__init__.py`
+- `backend/app/main.py`
+- `backend/app/services/memory_service.py`
+- `backend/app/services/agent_service.py`
+- `backend/app/services/scheduler_service.py`
+- `backend/app/routers/document.py`
+- `backend/app/routers/todo.py`
+- `backend/app/routers/task.py`
+- `backend/app/routers/forum.py`
+- possibly `backend/app/services/document_service.py`
+- possibly `backend/app/services/knowledge_service.py`
+
+### Frontend new files
+- `frontend/src/api/brain.ts`
+- `frontend/src/pages/brain/index.vue`
+- `frontend/src/pages/brain/composables/useBrainView.ts`
+- brain-related components under `frontend/src/components/brain/`
+
+### Frontend existing files
+- `frontend/src/app/router/routes.ts`
+- `frontend/src/app/navigation/nav.ts`
+- optionally `frontend/src/pages/graph/index.vue`
+
+---
+
+## L. Phase 1 “Definition of Done” Checklist
+- [ ] Brain persistence models exist and are queryable.
+- [ ] All five core domains emit `BrainEvent`s.
+- [ ] Daily learning creates `BrainCandidate`s and promotes durable `BrainMemory`s.
+- [ ] Tag priority is stored and manageable.
+- [ ] Chat can retrieve relevant brain knowledge.
+- [ ] `/api/brain` endpoints support dashboard and management actions.
+- [ ] `/brain` dashboard exists and is usable without relying on the graph page.
+- [ ] Graph remains available as a secondary/projection view.
+- [ ] Automated tests cover ingestion, promotion, retrieval, and UI basics.

frontend/notes.md

@@ -0,0 +1,45 @@
+# Notes: Dual Telemetry Control Panel
+
+## Working Assumptions
+- The chat page already has a persistent right-side `OrchestrationPanel`.
+- Existing chat streaming already emits real `progress`, `chunk`, and `error`-style events.
+- The user wants the panel to feel like an active system console, not a static status card.
+
+## Design Intent
+- Upper telemetry block: real machine metrics with micro line charts
+- Lower telemetry block: session activity waveform tied to current chat execution
+- Keep the visual language in the current sci-fi / HUD style
+- Avoid heavy chart libraries or full dashboard aesthetics
+
+## Constraints
+- Do not invent fake system numbers
+- Do not persist telemetry history into conversation history
+- Keep the main chat surface dominant
+- MVP should use the fewest new moving parts possible
+
+## Current Code Findings
+
+### `src/components/chat/OrchestrationPanel.vue`
+- Already owns the visual shell for the right-side control panel
+- Has logical places to insert additional stacked sections above the agent bus and event feed
+- Current UI is text-forward and would benefit from live numeric/sparkline blocks
+
+### `src/pages/chat/composables/useChatView.ts`
+- Already maintains transient orchestration state per request
+- Is the right place to derive a session activity waveform from `progress`, `tool`, and `chunk` events
+- Can own polling lifecycle for system metrics if we want chat page-local state
+
+### Backend status route
+- No dedicated system metrics endpoint has been confirmed yet
+- Minimal new backend contract can be a polling endpoint like `/api/system/status`
+- Suggested payload:
+  - `cpu_percent`
+  - `memory_percent`
+  - `disk_percent`
+  - `timestamp`
+
+## Planning Implications
+- Add a tiny backend router/service for system telemetry rather than overloading conversation APIs
+- Add a reusable lightweight sparkline component in frontend for consistent rendering
+- Keep system telemetry and session telemetry separate in state and UI
+- Limit retained chart points (for example 20-30) to keep rendering simple and responsive

frontend/orchestration_panel_plan.md

@@ -0,0 +1,124 @@
+# AI Control Orchestration Panel Plan
+
+## Goal
+Add a minimal viable right-side `JARVIS CONTROL` panel to the chat page that visualizes real-time agent orchestration from existing stream progress events while keeping the main conversation as the primary reading surface.
+
+## Scope
+- Frontend-only V1
+- Reuse existing stream payload fields: `stage`, `agent`, `tool_name`, `step`, `steps`
+- No persistence into conversation history
+- Auto-open on send, auto-close shortly after success or error
+
+## Recommended implementation
+
+### 1. Add a dedicated orchestration panel component
+Create a presentational component, e.g. `frontend/src/components/chat/OrchestrationPanel.vue`, responsible only for rendering:
+- Header: `JARVIS CONTROL`, current phase, status chip (`ACTIVE`, `COMPLETE`, `ERROR`)
+- Vertical agent bus:
+  - `JARVIS`
+  - `planner`
+  - `executor`
+  - `analyst`
+  - `librarian`
+- Recent event feed limited to the latest 3-5 items
+
+Keep rendering logic out of `index.vue` as much as possible so the page stays manageable.
+
+### 2. Expand transient chat-view state in `useChatView.ts`
+Replace the single `thinkingState`-only UX with a richer transient orchestration session owned by the composable. Suggested state shape:
+- `thinkingState`: preserve current raw progress snapshot for compatibility
+- `orchestrationPanelVisible: boolean`
+- `orchestrationStatus: 'idle' | 'active' | 'complete' | 'error'`
+- `activeAgent: string | null`
+- `visitedAgents: string[]`
+- `eventFeed: Array<{ id: string; label: string; kind: 'info' | 'tool' | 'success' | 'error' }>`
+- `panelPhaseLabel: string`
+- `closeTimer` handle for delayed auto-close
+
+This state should be reset at the start of each `sendMessage()` call and never written into the conversation store.
+
+### 3. Map existing stream events into panel state
+Inside `conversationApi.chatStream(...).onProgress`:
+- Open the panel on the first progress event if not already visible
+- Update `thinkingState` as today
+- Derive a display phase from `payload.stage`
+- Set `activeAgent` from `payload.agent`
+- Add `payload.agent` to `visitedAgents` if new
+- Push short event-feed items using priority:
+  1. `payload.step`
+  2. `payload.tool_name` -> `调用工具 · {tool}`
+  3. `payload.label`
+- If `payload.steps` exists, only surface the first meaningful item as an event instead of dumping the whole list into the panel
+- Trim event feed to latest 5 entries
+
+### 4. Change completion behavior
+Current code clears `thinkingState` immediately after stream completion or error. For the new experience:
+- On success:
+  - set panel status to `complete`
+  - add a final event like `响应已生成`
+  - append assistant message to store as today
+  - keep panel visible for ~1000-1500ms, then hide and reset transient panel state
+- On error:
+  - set panel status to `error`
+  - add error event using the error message
+  - keep panel visible slightly longer (e.g. ~1600ms), then hide and reset
+
+This preserves the cinematic finish while keeping the panel ephemeral.
+
+### 5. Update page layout in `src/pages/chat/index.vue`
+Restructure the main chat area so the central chat surface and right-side orchestration panel can coexist:
+- Keep existing left session sidebar unchanged
+- Wrap the current chat section and new panel in a horizontal content shell
+- Mount `<OrchestrationPanel ... />` to the right of the message/input area
+- Only show the panel when `orchestrationPanelVisible` is true
+- Keep the inline thinking bubble minimal or remove most of its detail once the side panel is active, so the UI does not duplicate orchestration information in two places
+
+### 6. Styling direction
+V1 styling should match the approved “AI control center” concept:
+- narrow right panel (`~340px`)
+- dark glass background, subtle cyan edge glow
+- vertical bus with one large `JARVIS` node and four smaller agent nodes
+- active node: bright border + pulse
+- visited node: low residual glow
+- event feed: compact short system phrases
+- entrance/exit: slide + fade
+
+## File-level change plan
+
+### `frontend/src/pages/chat/composables/useChatView.ts`
+- Add orchestration session state and reset helpers
+- Add progress-to-panel mapping helper
+- Add delayed close helper
+- Preserve existing send/stream logic while extending transient UI state
+
+### `frontend/src/pages/chat/index.vue`
+- Import panel component
+- Bind panel props from `useChatView()`
+- Adjust layout to support central chat + right panel
+- Reduce duplication between inline thinking bubble and right-side orchestration UI
+
+### `frontend/src/components/chat/OrchestrationPanel.vue`
+- New component for header, agent bus, event feed, and status visualization
+
+## Suggested event text mapping
+- `thinking` -> `请求接入`, `语义解析中`
+- `planning` -> `任务拆解中`, `生成执行路径`
+- `tool` + tool name -> `调用工具 · {tool_name}`
+- `responding` -> `正在汇总响应`
+- success -> `响应已生成`
+- error -> `任务执行中断`
+
+## Risks and mitigations
+- **Duplicate cognition with inline thinking bubble**: keep the bubble lightweight once panel exists
+- **Too many events**: cap the feed to 5 and dedupe consecutive identical labels
+- **Panel state leaking across conversation switches**: reset on `newConversation()` and `selectConversation()` when appropriate
+- **Abrupt close**: use short delayed close timers and clear any existing timer before starting a new request
+
+## Verification checklist
+1. Send a message and confirm the right panel slides in before the final assistant bubble appears.
+2. Confirm active agent highlighting changes as stream progress changes.
+3. Confirm event feed shows short orchestration phrases, not raw backend payload dumps.
+4. Confirm the panel auto-closes shortly after success.
+5. Confirm the panel shows error state briefly, then closes on failure.
+6. Confirm switching conversations or starting a new one does not preserve the previous request's orchestration state.
+7. Confirm the main chat remains the dominant reading surface and the panel does not push message content into unreadable widths.

frontend/task_plan.md

@@ -0,0 +1,28 @@
+# Task Plan: Dual Telemetry Control Panel
+
+## Goal
+Add a minimal viable dual telemetry module to the chat page right-side JARVIS CONTROL panel so it shows real system metric sparklines (CPU/MEM/DISK) and live session activity telemetry from chat progress events, while staying consistent with the current sci-fi UI.
+
+## Phases
+- [x] Phase 1: Plan and setup
+- [x] Phase 2: Research existing chat panel and data flow
+- [ ] Phase 3: Define implementation approach and data contracts
+- [ ] Phase 4: Review and deliver
+
+## Key Questions
+1. Which metrics should be real machine telemetry versus session-derived telemetry?
+2. What is the smallest backend contract needed to make the panel feel actually alive?
+3. How should the new chart blocks fit into the current control panel without overwhelming the chat area?
+
+## Decisions Made
+- Use a mixed telemetry model: system metrics from backend polling, session activity from existing stream events.
+- Prefer lightweight SVG or custom-rendered sparklines instead of adding a charting library.
+- Keep the current right-side control panel and insert telemetry blocks into it rather than creating a second dashboard.
+- Make system metrics real: CPU, memory, and disk values must come from backend runtime state.
+- Make session activity real: derive the waveform from actual progress, tool, and chunk events from the current chat stream.
+
+## Errors Encountered
+- Existing plan file reflected the earlier orchestration-panel-only scope: replaced it with the new telemetry-focused plan so current goals stay in attention.
+
+## Status
+**Currently in Phase 3** - Finalizing the implementation plan, file touch points, and minimal data contracts for the dual telemetry panel.

knowledge_ingestion_plan.md

@@ -0,0 +1,210 @@
+# Knowledge Ingestion Normalization Plan
+
+## Goal
+Introduce a unified structured-markdown ingestion pipeline for the knowledge center: MinerU for PDF, existing parsers for DOCX/XLSX/CSV/MD/TXT, persisted normalized content, and lightweight hierarchical chunk semantics.
+
+## Scope
+- Backend document parsing and normalization flow
+- Document persistence model updates
+- Incremental retrieval/indexing integration
+- Backfill/reindex strategy for existing documents
+- Test strategy for parser, router, and migration behavior
+
+## Non-Goals
+- Full parent-child chunk graph tables in this phase
+- Rewriting all chunking logic to markdown-first immediately
+- Replacing all non-PDF parsers with a new framework
+- Solving every OCR/image-understanding case in the first pass
+
+## Architecture Decisions
+- **PDF parser:** MinerU
+- **Other parsers:** keep current implementations for DOCX/XLSX/CSV/MD/TXT
+- **Canonical intermediate representation:** `ParsedDocument + structured_markdown`
+- **Canonical persisted content:** add `normalized_content` to `documents`
+- **Hierarchy model:** metadata-based lightweight semantics, not hard foreign-key parent-child chunk tables
+- **Migration strategy:** additive schema change + on-demand rebuild/reindex
+
+## Target Flow
+1. Upload file
+2. Parse by type
+   - PDF -> MinerU -> normalize to ParsedDocument
+   - Other formats -> current parser -> ParsedDocument
+3. Render `ParsedDocument` into `structured_markdown`
+4. Persist document record including `normalized_content`
+5. Build chunks (initially still from nodes, enriched with lightweight hierarchy metadata)
+6. Index into vector store
+7. Serve preview from `normalized_content`
+
+## Data Model Changes
+### documents table
+Add fields:
+- `normalized_content TEXT NULL`
+- `normalized_format VARCHAR(50) NULL` (value like `structured_markdown`)
+- optional later: `normalization_version VARCHAR(50) NULL`
+
+### document_chunks metadata
+Enrich chunk metadata with lightweight hierarchy keys:
+- `chunk_level`
+- `parent_key`
+- `block_key`
+- existing structural metadata remains (`section_path`, `section_title`, `page_number`, `sheet_name`, `row_start`, `row_end`, `content_type`)
+
+Rationale:
+- Supports grouped retrieval and contextual reconstruction
+- Avoids introducing a relational chunk tree prematurely
+
+## Backend Implementation Steps
+### Phase 1: Schema and persistence
+Files:
+- `backend/app/models/document.py`
+- `backend/app/database.py`
+- `backend/app/schemas/document.py`
+- tests under `backend/tests/backend/app`
+
+Changes:
+- Add `normalized_content` and `normalized_format` to `Document`
+- Extend `ensure_document_columns()` to backfill the new columns for existing databases
+- Expose `normalized_content` only where needed for preview/read APIs (avoid broad API expansion if not required yet)
+
+### Phase 2: Introduce structured markdown renderer
+Files:
+- `backend/app/services/document_service.py`
+- possibly a new helper module if the renderer gets too large, but prefer keeping it local initially
+
+Changes:
+- Add `_render_structured_markdown(parsed: ParsedDocument) -> str`
+- Keep current per-format parsing functions
+- After parsing, render once and store into `document.normalized_content`
+- Add `normalized_format='structured_markdown'`
+
+Rendering guidance:
+- headings -> markdown headings
+- paragraphs/text -> plain markdown paragraphs
+- CSV/XLSX tables -> markdown table blocks or fenced structured table blocks when tables are too large/wide
+- PDF page boundaries -> explicit page markers
+- preserve contextual markers in metadata even if markdown cannot express everything perfectly
+
+### Phase 3: MinerU integration for PDF
+Files:
+- `backend/app/services/document_service.py`
+- `backend/pyproject.toml` / lockfile if dependencies are added
+- config if MinerU requires configurable paths/options
+
+Changes:
+- Replace PDF branch with MinerU-backed parsing
+- Map MinerU output into internal `ParsedNode`/`ParsedDocument`
+- Preserve page and block order
+- Represent image blocks as markdown placeholders plus metadata
+
+Image policy:
+- First pass: extract image block references, page number, nearby text, and optional captions
+- Do not perform full image understanding for every image in phase 1
+- Design metadata so high-value image understanding can be added later
+
+### Phase 4: Chunk metadata enrichment
+Files:
+- `backend/app/services/document_service.py`
+- `backend/app/services/knowledge_service.py`
+- tests
+
+Changes:
+- Extend `_build_chunks()` to include lightweight hierarchy metadata:
+  - section headings become natural parent keys
+  - row batches / sheet blocks get stable block keys
+  - PDF page/section blocks preserve ordered grouping
+- Keep current retrieval behavior, but let `_get_related_chunks()` benefit from richer metadata if helpful
+
+### Phase 5: Preview and rebuild behavior
+Files:
+- `backend/app/routers/document.py`
+- `backend/app/services/document_service.py`
+
+Changes:
+- `get_document_content()` should prefer `normalized_content`
+- Fallback to legacy file reading only when normalized content is absent
+- Rebuild/reindex paths should regenerate normalized content before chunk rebuild/indexing
+
+### Phase 6: Backfill strategy
+Approach:
+- Add a rebuild endpoint or reuse existing reindex flow to backfill `normalized_content`
+- Existing documents can be migrated lazily:
+  - when opened
+  - when reindexed
+  - or via an admin/batch rebuild command later
+
+This avoids a risky one-shot migration.
+
+## Error Handling Changes
+Current issue:
+- Upload route can leak parser/dependency problems as generic 500s.
+
+Changes:
+- Convert expected parser/business errors to explicit 4xx responses where appropriate
+- For missing optional parser dependencies, return clear messages such as:
+  - `DOCX parsing dependency missing: python-docx`
+  - `PDF parsing dependency missing/configuration invalid`
+- Keep true unexpected exceptions as 500s
+
+Files:
+- `backend/app/routers/document.py`
+- `backend/app/services/document_service.py`
+
+## Testing Plan
+### Backend unit/integration tests
+1. Schema migration test for new `documents` columns
+2. Renderer tests:
+   - markdown headings preserved
+   - section paths retained in metadata
+   - xlsx/csv table blocks rendered predictably
+   - pdf page markers preserved from MinerU mapping
+3. Upload tests:
+   - successful DOCX/XLSX/CSV/MD/TXT upload stores `normalized_content`
+   - PDF upload stores `normalized_content`
+   - missing dependency returns clear error instead of generic 500 where applicable
+4. Rebuild/reindex tests:
+   - normalized content regenerated
+   - chunks rebuilt with hierarchy metadata
+5. Retrieval tests:
+   - related chunk lookup still works with enriched metadata
+
+### Frontend tests
+Only if the UI surfaces normalized preview directly in this phase:
+- knowledge view preview prefers normalized content from API
+- no regression in upload and refresh persistence behavior
+
+## Suggested Execution Order
+1. Add schema fields + migration guard
+2. Add structured markdown renderer for current parsers
+3. Store normalized content on upload
+4. Update content preview to read normalized content first
+5. Enrich chunk metadata with lightweight hierarchy keys
+6. Integrate MinerU for PDF
+7. Add rebuild/backfill path
+8. Expand tests
+
+## Risks and Mitigations
+### Risk: MinerU integration complexity
+Mitigation:
+- isolate MinerU to PDF branch only
+- keep internal ParsedDocument contract stable
+
+### Risk: markdown rendering loses structure
+Mitigation:
+- preserve critical structure in metadata
+- use explicit block markers for page/sheet/table boundaries
+
+### Risk: broad retrieval regressions
+Mitigation:
+- keep chunking source node-based initially
+- change one layer at a time
+
+### Risk: old documents lack normalized content
+Mitigation:
+- lazy backfill during preview/reindex
+
+## Deliverable Recommendation
+Implement in small PR-sized slices:
+1. schema + normalized renderer + preview fallback
+2. hierarchy metadata enrichment
+3. MinerU PDF integration
+4. rebuild/backfill tooling

notes.md

@@ -0,0 +1,42 @@
+# Notes: Jarvis Knowledge Brain Blueprint
+
+## Current-State Findings
+- Existing source domains already exist separately: conversations, documents, todos, tasks, forum posts.
+- Current long-term memory only comes from conversation extraction via `UserMemory`.
+- Current graph build path only uses indexed document chunks.
+- Scheduler infrastructure already exists and can host daily brain-learning jobs.
+- Frontend already exposes a `知识大脑` navigation entry, but it currently points to the graph page.
+
+## Synthesized Findings
+
+### What can be reused
+- `memory_service` as a seed for conversation extraction and recall.
+- `scheduler_service` as the base for daily learning workflows.
+- `tag_service` as an early foundation for brain tags.
+- Existing business tables as authoritative raw source records.
+
+### What is missing
+- Unified event layer across all source systems.
+- Candidate memory layer between raw events and durable brain memory.
+- Timeline-aware memory model with reinforcement / archival states.
+- Retrieval path that combines long-term memory with recent relevant events.
+- Brain-specific APIs and a dedicated frontend dashboard module.
+
+### Phase 1 objective
+- Build the minimum architecture needed for a real event-driven brain:
+  - BrainEvent
+  - BrainCandidate
+  - BrainMemory
+  - BrainTag and link tables
+  - ingestion services
+  - daily learning job
+  - retrieval integration
+  - brain dashboard APIs
+
+## Additional Findings: Knowledge Parsing Normalization
+- Current document ingestion parses each format separately and builds chunks directly from ParsedNode items.
+- Current chunks already carry structural metadata, but there is no explicit parent-child chunk graph.
+- The agreed direction is to use MinerU for PDF only, keep existing parsers for DOCX/XLSX/CSV/MD/TXT, and converge all outputs into structured markdown.
+- normalized_content should be persisted on documents so preview, rebuild, and future chunking can reuse the same canonical text.
+- Lightweight hierarchy should be represented in chunk metadata first, not in a new relational tree schema.
+- Current DOCX upload failure in the running environment is caused by a missing python-docx installation in the active backend environment.

task_plan.md

@@ -0,0 +1,27 @@
+# Task Plan: Jarvis Knowledge Brain Phase 1 Blueprint
+
+## Goal
+Create a practical phase-1 implementation blueprint for the event-driven knowledge brain, covering backend models, services, scheduler jobs, retrieval integration, APIs, and frontend brain module structure.
+
+## Phases
+- [x] Phase 1: Plan and setup
+- [x] Phase 2: Research/gather information
+- [x] Phase 3: Draft blueprint
+- [x] Phase 4: Review and deliver
+
+## Key Questions
+1. Which new persistence models are required for an event-driven knowledge brain?
+2. How should existing conversation, document, todo, task, and forum data flow into the brain?
+3. What should phase 1 include versus defer to later phases?
+4. How should the frontend brain module be structured before full graph intelligence exists?
+
+## Decisions Made
+- Use an event-driven brain architecture instead of extending the current graph-only flow.
+- Keep the current graph as a projection/view layer, not the brain source of truth.
+- Phase 1 should prioritize unified ingestion, candidate generation, long-term memory storage, and retrieval integration.
+
+## Errors Encountered
+- None yet.
+
+## Status
+**Completed** - Separate implementation plan drafted in `knowledge_ingestion_plan.md` and supporting notes updated.