Bruce/DEMO-AGENT
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
bruce
2026-05-29 23:04:01 +08:00
parent e24d9804ba
commit b5ed5b6faa
3 changed files with 359 additions and 10 deletions
Download Patch File Download Diff File Expand all files Collapse all files

13
AGENTS.md
View File

@@ -88,10 +88,16 @@ Django 单体 + 独立 Agent Core + Docker Compose
docs/ docs/
``` ```
模块需求文档放在： 需求分析文档放在：
```text ```text
docs/modules/ docs/需求分析/
```
设计文档放在：
```text
docs/设计文档/
``` ```
场景配置放在： 场景配置放在：
@@ -103,7 +109,7 @@ configs/
重要设计变更需要同步更新： 重要设计变更需要同步更新：
- `README.md` - `README.md`
- `docs/requirements_v1.md` - `docs/需求分析/1.V1总需求文档.md`
- 相关模块需求文档 - 相关模块需求文档
## 测试与验证约定 ## 测试与验证约定
@@ -131,4 +137,3 @@ configs/
- 分布式任务队列。 - 分布式任务队列。
这些内容可以作为后续增强，不应影响 V1 快速成型。 这些内容可以作为后续增强，不应影响 V1 快速成型。

13
README.md
View File

@@ -20,7 +20,7 @@ V1 采用：
- Chroma - Chroma
- Django Templates - Django Templates
- Docker Compose - Docker Compose
- OpenAI API 兼容模型接口 - OpenAI API 兼容的 LLM 与 Embedding 接口
默认不强依赖 Dify。系统预留 Adapter 设计，后续可以接入 Dify、OpenAI Agents SDK 或其他 Agent 编排平台。 默认不强依赖 Dify。系统预留 Adapter 设计，后续可以接入 Dify、OpenAI Agents SDK 或其他 Agent 编排平台。
@@ -133,6 +133,7 @@ V1 暂不重点做：
本地启动： 本地启动：
```bash ```bash
pip install -r requirements.txt
python manage.py migrate python manage.py migrate
python manage.py runserver python manage.py runserver
``` ```
@@ -143,12 +144,12 @@ Docker 启动：
docker compose up --build docker compose up --build
``` ```
当前仓库处于需求和设计文档阶段，代码骨架尚未生成。 当前文档目标已统一为完整 V1 闭环：真实 Chroma RAG、OpenAI 兼容 LLM、OpenAI 兼容 Embedding、工具注册和审计日志。开发阶段可以用测试桩验证页面和边界，但不作为 V1 验收结果。
## 文档入口 ## 文档入口
- [V1 总需求文档](docs/requirements_v1.md) - [V1 总需求文档](docs/需求分析/1.V1总需求文档.md)
- [模块需求文档索引](docs/modules/00_module_requirements_index.md) - [模块需求文档索引](docs/需求分析/2.模块需求索引.md)
- [Agent 设计文档](docs/agent_design.md) - [智能体总体设计](docs/设计文档/1.智能体总体设计.md)
- [设计文档索引](docs/设计文档/0.设计文档索引.md)
- [协作与编码约定](AGENTS.md) - [协作与编码约定](AGENTS.md)

343
docs/superpowers/plans/2026-05-29-V1-Django基线实现计划.md Normal file
View File

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