DESKTOP-72TV0V4\caoxiaozhu
6f594631e9
Align the brain prompts, graph view, and startup defaults with the latest phase 1 flow so local runs and navigation stay consistent.
556 lines
15 KiB
Markdown
556 lines
15 KiB
Markdown
# 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.
|