Files

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

2026-05-29 23:04:01 +08:00

11 KiB

Raw Blame History

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:

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

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

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

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

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

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:

python manage.py check
pytest -q

Expected: all checks pass.

Step 3: Verify docs path references

Run:

$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.

11 KiB Raw Blame History

V1 Django Baseline Implementation Plan

File Structure

Task 1: Dependencies and Django Project Shell

Task 2: Scenarios Module and Five YAML Configs

Task 3: Agent Core Mock Orchestrator

Task 4: Audit Module

Task 5: Documents Module

Task 6: Chat Module

Task 7: Docker and Documentation Alignment

Self-Review

11 KiB

Raw Blame History