docs(project): 更新项目说明和实现计划

2026-05-29 23:04:01 +08:00
parent e24d9804ba
commit b5ed5b6faa
3 changed files with 359 additions and 10 deletions
--- a/docs/superpowers/plans/2026-05-29-V1-Django基线实现计划.md
+++ b/docs/superpowers/plans/2026-05-29-V1-Django基线实现计划.md
@@ -0,0 +1,343 @@
+# V1 Django Baseline Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Build the smallest runnable Django baseline that satisfies the current Chinese requirements and design documents.
+
+**Architecture:** Use a Django monolith with four apps (`scenarios`, `documents`, `chat`, `audit`) plus an independent `agent_core` package. The first implementation returns deterministic mock Agent results so the UI, audit, documents and module boundaries can be verified before real RAG/LLM integration.
+
+**Tech Stack:** Python 3.13, Django 5.x, PyYAML, pytest, pytest-django, SQLite, Docker Compose.
+
+---
+
+## File Structure
+
+- Create `requirements.txt`: runtime and test dependencies.
+- Create `manage.py`, `config/settings.py`, `config/urls.py`, `config/wsgi.py`, `config/asgi.py`: Django project shell.
+- Create `apps/scenarios/`: YAML scenario loading, homepage, tests.
+- Create `apps/documents/`: upload model, upload/list/index views, text extraction, tests.
+- Create `apps/chat/`: message form, chat view, Agent Core call, audit write, tests.
+- Create `apps/audit/`: audit model, service, list/detail views, tests.
+- Create `agent_core/`: dataclasses, orchestrator, mock RAG ingest/retrieve, tool registry, structured output parser.
+- Create `configs/*.yaml`: five required scenarios.
+- Create `templates/`: minimal Django Templates for pages.
+- Create `Dockerfile`, `docker-compose.yml`, `.env.example`: one-command startup.
+
+## Task 1: Dependencies and Django Project Shell
+
+**Files:**
+- Create: `requirements.txt`
+- Create: `manage.py`
+- Create: `config/__init__.py`
+- Create: `config/settings.py`
+- Create: `config/urls.py`
+- Create: `config/wsgi.py`
+- Create: `config/asgi.py`
+- Test: `pytest.ini`
+
+- [ ] **Step 1: Write failing configuration test**
+
+Create `tests/test_project_configuration.py`:
+
+```python
+from django.conf import settings
+from django.urls import reverse
+
+
+def test_core_settings_expose_documented_paths():
+    assert settings.SCENARIO_CONFIG_DIR.name == "configs"
+    assert settings.CHROMA_PATH.name == "chroma"
+    assert settings.MEDIA_ROOT.name == "uploads"
+
+
+def test_home_url_is_registered(client):
+    response = client.get(reverse("scenarios:index"))
+    assert response.status_code == 200
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `pytest tests/test_project_configuration.py -q`
+Expected: FAIL because Django project and apps do not exist.
+
+- [ ] **Step 3: Implement minimal project shell**
+
+Add dependencies and project files with settings for installed apps, templates, SQLite, media paths, and URL includes.
+
+- [ ] **Step 4: Run test to verify progress**
+
+Run: `pytest tests/test_project_configuration.py -q`
+Expected: either PASS or fail only because `apps.scenarios` is not implemented yet.
+
+## Task 2: Scenarios Module and Five YAML Configs
+
+**Files:**
+- Create: `apps/scenarios/services.py`
+- Create: `apps/scenarios/views.py`
+- Create: `apps/scenarios/urls.py`
+- Create: `apps/scenarios/apps.py`
+- Create: `configs/knowledge_qa.yaml`
+- Create: `configs/document_review.yaml`
+- Create: `configs/ticket_assistant.yaml`
+- Create: `configs/quality_analysis.yaml`
+- Create: `configs/risk_audit.yaml`
+- Create: `templates/scenarios/index.html`
+- Test: `tests/test_scenarios.py`
+
+- [ ] **Step 1: Write failing scenario tests**
+
+```python
+from apps.scenarios.services import get_scenario, list_scenarios
+
+
+def test_list_scenarios_loads_five_configs():
+    scenarios = list_scenarios()
+    assert [scenario["id"] for scenario in scenarios] == [
+        "knowledge_qa",
+        "document_review",
+        "ticket_assistant",
+        "quality_analysis",
+        "risk_audit",
+    ]
+
+
+def test_get_scenario_returns_full_agent_config():
+    scenario = get_scenario("quality_analysis")
+    assert scenario["agent"]["role"]
+    assert scenario["rag"]["enabled"] is True
+    assert scenario["output"]["type"] == "quality_report"
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `pytest tests/test_scenarios.py -q`
+Expected: FAIL because services/configs are missing.
+
+- [ ] **Step 3: Implement scenario loader and homepage**
+
+Use `yaml.safe_load()`, validate required fields, and render scenario cards on `/`.
+
+- [ ] **Step 4: Run tests**
+
+Run: `pytest tests/test_scenarios.py tests/test_project_configuration.py -q`
+Expected: PASS.
+
+## Task 3: Agent Core Mock Orchestrator
+
+**Files:**
+- Create: `agent_core/results.py`
+- Create: `agent_core/orchestrator.py`
+- Create: `agent_core/structured_output.py`
+- Create: `agent_core/tool_registry.py`
+- Create: `agent_core/tools/builtin_tools.py`
+- Create: `agent_core/rag/ingest.py`
+- Create: `agent_core/rag/retriever.py`
+- Test: `tests/test_agent_core.py`
+
+- [ ] **Step 1: Write failing Agent Core tests**
+
+```python
+from agent_core.orchestrator import run_agent
+
+
+def test_run_agent_returns_structured_mock_result():
+    scenario = {
+        "id": "knowledge_qa",
+        "name": "知识库问答助手",
+        "rag": {"enabled": True, "collection": "knowledge_qa", "top_k": 3},
+        "tools": ["generate_action_items"],
+        "output": {"type": "general_answer"},
+    }
+    result = run_agent(scenario, "如何处理异常？")
+    assert result.status == "success"
+    assert result.answer
+    assert result.structured_output["output_type"] == "general_answer"
+    assert result.tool_calls[0]["tool_name"] == "generate_action_items"
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `pytest tests/test_agent_core.py -q`
+Expected: FAIL because `agent_core` is missing.
+
+- [ ] **Step 3: Implement deterministic mock AgentResult**
+
+Return stable answer, references, tool calls, model name `mock-model`, and latency.
+
+- [ ] **Step 4: Run tests**
+
+Run: `pytest tests/test_agent_core.py -q`
+Expected: PASS.
+
+## Task 4: Audit Module
+
+**Files:**
+- Create: `apps/audit/models.py`
+- Create: `apps/audit/services.py`
+- Create: `apps/audit/views.py`
+- Create: `apps/audit/urls.py`
+- Create: `apps/audit/admin.py`
+- Create: `templates/audit/log_list.html`
+- Create: `templates/audit/log_detail.html`
+- Test: `tests/test_audit.py`
+
+- [ ] **Step 1: Write failing audit tests**
+
+```python
+from apps.audit.models import AgentAuditLog
+from apps.audit.services import create_audit_log
+from agent_core.results import AgentResult
+
+
+def test_create_audit_log_records_success_result(db):
+    result = AgentResult(answer="回答", structured_output={"x": 1}, status="success")
+    log = create_audit_log("knowledge_qa", "知识库问答助手", "问题", result)
+    assert AgentAuditLog.objects.count() == 1
+    assert log.final_answer == "回答"
+    assert log.structured_output == {"x": 1}
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `pytest tests/test_audit.py -q`
+Expected: FAIL because audit app is missing.
+
+- [ ] **Step 3: Implement model, service, admin, views**
+
+Use JSONField defaults and avoid storing sensitive environment values.
+
+- [ ] **Step 4: Run migrations and tests**
+
+Run: `python manage.py makemigrations audit && pytest tests/test_audit.py -q`
+Expected: PASS.
+
+## Task 5: Documents Module
+
+**Files:**
+- Create: `apps/documents/models.py`
+- Create: `apps/documents/services.py`
+- Create: `apps/documents/forms.py`
+- Create: `apps/documents/views.py`
+- Create: `apps/documents/urls.py`
+- Create: `apps/documents/admin.py`
+- Create: `templates/documents/document_list.html`
+- Create: `templates/documents/upload.html`
+- Test: `tests/test_documents.py`
+
+- [ ] **Step 1: Write failing document tests**
+
+```python
+from django.core.files.uploadedfile import SimpleUploadedFile
+from django.urls import reverse
+
+from apps.documents.models import UploadedDocument
+
+
+def test_upload_txt_document_creates_uploaded_record(client, db):
+    file = SimpleUploadedFile("rules.txt", "hello".encode("utf-8"), content_type="text/plain")
+    response = client.post(reverse("documents:upload"), {"scenario_id": "knowledge_qa", "file": file})
+    assert response.status_code == 302
+    document = UploadedDocument.objects.get()
+    assert document.status == "uploaded"
+    assert document.file_type == "txt"
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `pytest tests/test_documents.py -q`
+Expected: FAIL because documents app is missing.
+
+- [ ] **Step 3: Implement upload/list/index flow**
+
+Support `.txt` and `.md`; index action calls `agent_core.rag.ingest.ingest_document()` and updates status.
+
+- [ ] **Step 4: Run migrations and tests**
+
+Run: `python manage.py makemigrations documents && pytest tests/test_documents.py -q`
+Expected: PASS.
+
+## Task 6: Chat Module
+
+**Files:**
+- Create: `apps/chat/forms.py`
+- Create: `apps/chat/views.py`
+- Create: `apps/chat/urls.py`
+- Create: `apps/chat/apps.py`
+- Create: `templates/chat/index.html`
+- Test: `tests/test_chat.py`
+
+- [ ] **Step 1: Write failing chat tests**
+
+```python
+from django.urls import reverse
+
+from apps.audit.models import AgentAuditLog
+
+
+def test_chat_post_returns_agent_result_and_audit_log(client, db):
+    response = client.post(reverse("chat:index", args=["knowledge_qa"]), {"message": "如何处理异常？"})
+    assert response.status_code == 200
+    assert "mock-model" in response.content.decode("utf-8")
+    assert AgentAuditLog.objects.count() == 1
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `pytest tests/test_chat.py -q`
+Expected: FAIL because chat app is missing.
+
+- [ ] **Step 3: Implement chat form and view**
+
+Validate message, call `get_scenario()`, `run_agent()`, then `create_audit_log()`.
+
+- [ ] **Step 4: Run tests**
+
+Run: `pytest tests/test_chat.py tests/test_audit.py tests/test_agent_core.py -q`
+Expected: PASS.
+
+## Task 7: Docker and Documentation Alignment
+
+**Files:**
+- Create: `.env.example`
+- Create: `Dockerfile`
+- Create: `docker-compose.yml`
+- Modify: `README.md`
+- Test: all tests and Django checks.
+
+- [ ] **Step 1: Add deployment files**
+
+Use a single web service, install `requirements.txt`, run migrations, and serve `0.0.0.0:8000`.
+
+- [ ] **Step 2: Verify Django and tests**
+
+Run:
+
+```bash
+python manage.py check
+pytest -q
+```
+
+Expected: all checks pass.
+
+- [ ] **Step 3: Verify docs path references**
+
+Run:
+
+```powershell
+$patterns = @('docs/需求分析', 'docs/设计文档', 'V1总需求文档', '智能体总体设计')
+Get-ChildItem -Recurse -File |
+  Where-Object {
+    $_.FullName -notlike '*\.git\*' -and
+    $_.FullName -notlike '*\.idea\*' -and
+    $_.FullName -notlike '*docs\superpowers\plans\2026-05-29-v1-django-baseline.md'
+  } |
+  Select-String -Pattern $patterns
+```
+
+Expected: no matches.
+
+## Self-Review
+
+- Spec coverage: The plan covers Chinese docs, five scenario configs, Django startup, homepage, chat, audit, documents, Agent Core, and Docker baseline.
+- Placeholder scan: No implementation step relies on an undefined placeholder; mock LLM/RAG is intentionally scoped as the first runnable baseline.
+- Type consistency: Tests use `AgentResult`, `run_agent`, `list_scenarios`, `get_scenario`, `UploadedDocument`, and `AgentAuditLog` consistently.