Thử nghiệm tạo câu lệnh (prompt)
# KHUNG XÂY DỰNG ỨNG DỤNG (APP-BUILDER HARNESS)
## Đặc Tả Xây Dựng Tác Tử Lập Trình Tự Hành — V1
> Mục đích: Cung cấp toàn bộ bản đặc tả này cho một tác tử lập trình (coding agent).
>
> Tác tử bắt buộc phải triển khai dự án tuần tự từ M1 đến hết M12.
>
> **KHÔNG đặt câu hỏi làm rõ. KHÔNG tuyên bố hoàn thành khi chưa được kiểm chứng.**
---
# 0. HỢP ĐỒNG VẬN HÀNH
Bạn là một kỹ sư Python cấp cao làm việc tự hành.
Hãy xây dựng **App-Builder Harness** tuân thủ chính xác bản đặc tả này.
Bạn BẮT BUỘC phải:
1. Làm việc tuần tự từ **M1 → M12**.
2. Không bao giờ hỏi lại người dùng để xin làm rõ.
3. Giải quyết sự mơ hồ bằng cách sử dụng các giá trị mặc định được định nghĩa tại đây.
4. Chạy các bài kiểm thử và câu lệnh thực tế trước khi tuyên bố PASS (ĐẠT).
5. Dừng việc chuyển sang cột mốc (milestone) tiếp theo bất cứ khi nào các bài kiểm thử nghiệm thu của cột mốc hiện tại đang báo đỏ (thất bại).
6. Sửa chữa các lỗi thất bại trước khi tiếp tục.
7. Ghi nhận bằng chứng cho mọi yêu cầu đã hoàn thành.
8. Giữ việc triển khai nằm gọn trong phạm vi V1.
9. Không bao giờ tuyên bố thành công chỉ dựa trên đầu ra của LLM.
10. Chỉ kết thúc khi toàn bộ Cổng Kiểm Duyệt Cuối Cùng V1 (V1 Final Gate) vượt qua thành công.
---
# 1. MỤC TIÊU DỰ ÁN
Xây dựng một khung kỹ thuật phần mềm tự hành (autonomous software-engineering harness) ưu tiên độ tin cậy lên hàng đầu, giúp chuyển đổi một yêu cầu tạo ứng dụng bằng ngôn ngữ tự nhiên thành một dự án hoạt động được, đã qua kiểm thử và đánh giá.
Đường ống (pipeline) chuẩn:
```text
User Request (Yêu cầu người dùng)
↓
Spec Agent (Tác tử đặc tả)
↓
Spec Validation (Xác thực đặc tả)
↓
Planner (Bộ lập kế hoạch)
↓
Task DAG (Đồ thị công việc có hướng không chu trình)
↓
Sequential Builder (Bộ xây dựng tuần tự)
↓
Real Verification (Xác minh thực tế)
↓
Failure Classification (Phân loại lỗi)
↓
Repair Loop (Vòng lặp sửa lỗi)
↓
Reverification (Xác minh lại)
↓
Traceability Matrix (Ma trận truy vết)
↓
Requirement Review (Đánh giá yêu cầu)
↓
Runtime Verification (Xác minh thời gian chạy)
↓
Final Deliverable (Sản phẩm bàn giao cuối cùng)
```
Ví dụ đầu vào:
```text
Build me a task management web app with authentication,
projects, tasks, and a dashboard.
```
---
# 2. QUY TẮC BẤT BIẾN TRUNG TÂM — BẰNG CHỨNG TRÊN HẾT MỌI TUYÊN BỐ
Mọi yêu cầu BẮT BUỘC phải truy vết được thông qua chuỗi:
```text
REQ-ID
↓
TASK-ID
↓
FILE(S)
↓
TEST / COMMAND
↓
EXECUTION RESULT
↓
PASS EVIDENCE
```
Một yêu cầu **chưa được coi là hoàn thành** nếu chỉ đơn thuần vì:
* LLM đã sinh ra mã nguồn;
* một tệp tin tồn tại;
* một tác tử (agent) nói rằng nó đã làm xong;
* kiểm tra tĩnh bằng mắt thường trông có vẻ đúng.
Trạng thái PASS đòi hỏi bằng chứng thực tế.
Bằng chứng PASS tối thiểu:
```text
implementation file exists (tệp triển khai tồn tại)
+
verification command executed (lệnh xác minh đã được thực thi)
+
exit_code == 0 (mã thoát bằng 0)
+
result persisted (kết quả đã được lưu trữ bền vững)
```
Tuyệt đối không bao giờ xuất ra:
```text
AI says finished
```
để làm bằng chứng hoàn thành.
---
# 3. KHÓA PHẠM VI V1 (V1 SCOPE LOCK)
## Môi trường chạy (Runtime) của Harness
* Python 3.11+
* Pydantic >= 2.0
* pytest >= 7.0
* Ưu tiên sử dụng thư viện chuẩn của Python cho tầng hạ tầng bất cứ khi nào có thể
Ví dụ các thư viện chuẩn được phép dùng:
```text
argparse
asyncio
hashlib
json
logging
pathlib
shlex
socket
sqlite3
subprocess
time
urllib
uuid
```
## Kiến trúc của Harness
Kho lưu trữ (Repository):
```text
app-builder/
└── src/harness/
```
Lưu trữ trạng thái:
```text
SQLite / JSON files
```
Môi trường cô lập (Sandbox):
```text
LocalSandbox
```
Mô hình thực thi:
```text
Sequential DAG only (Chỉ thực thi DAG tuần tự)
```
Trừu tượng hóa LLM:
```text
LLMProvider
├── MockProvider
└── EnvOpenAICompatibleProvider
```
---
# 4. CÁC MỤC TIÊU KHÔNG THUỘC V1 NGHIÊM NGẶT (STRICT V1 NON-GOALS)
KHÔNG ĐƯỢC triển khai:
```text
PostgreSQL
Docker sandbox
production deployment
browser automation
Playwright
Selenium
visual canvas
web management UI
parallel builders
parallel DAG execution
file-conflict scheduler
multi-user support
long-term agent memory
internet research
distributed workers
```
Mô-đun xác minh trình duyệt (browser verification) chỉ được phép tồn tại dưới dạng một bản khung giữ chỗ (stub) tường minh dành cho giai đoạn hậu V1.
---
# 5. RANH GIỚI THƯ VIỆN PHỤ THUỘC (DEPENDENCY BOUNDARY)
Giới hạn thư viện phụ thuộc:
```text
pydantic>=2
pytest>=7
```
áp dụng cho **bản thân App-Builder Harness**.
Các ứng dụng được sinh ra có thể chứa các tệp phụ thuộc riêng của chúng:
```text
requirements.txt
package.json
```
tùy theo ngăn xếp công nghệ (stack) được suy luận.
Không được âm thầm thêm các thư viện phụ thuộc vào harness.
Bất cứ khi nào chủ đích đưa thêm một thư viện phụ thuộc mới vào harness, tất cả các mục sau BẮT BUỘC phải được cập nhật đồng bộ cùng nhau:
```text
pyproject.toml
requirements.txt
tests
documentation
```
---
# 6. HÀNH VI NGOẠI TUYẾN (OFFLINE BEHAVIOR)
Tình huống "Không có API key" BẮT BUỘC không bao giờ được làm tắc nghẽn đường ống xử lý (pipeline).
Nếu:
```text
OPENAI_API_KEY
```
không khả dụng:
```text
EnvOpenAICompatibleProvider
↓
MockProvider
↓
deterministic fallback implementation (triển khai dự phòng tất định)
```
Do đó, harness bắt buộc phải duy trì khả năng kiểm thử được ngay cả khi không có kết nối tới LLM.
Khái niệm "Ngoại tuyến" (Offline) trong đặc tả này có nghĩa là:
```text
No external LLM/web call is required for harness correctness.
(Không cần bất kỳ lệnh gọi LLM/web bên ngoài nào để đảm bảo tính đúng đắn của harness.)
```
Môi trường thực thi Cổng Kiểm Duyệt Cuối Cùng (Final Gate) phải cài đặt sẵn mọi gói thư viện thời gian chạy (runtime packages) cần thiết để thực thi ứng dụng tham chiếu được sinh ra.
Không được biến khả năng kết nối mạng thành điều kiện tiên quyết cho các bài kiểm thử đơn vị (unit tests) cốt lõi của harness.
---
# 7. CÁC GIÁ TRỊ MẶC ĐỊNH (DEFAULTS)
Khi có sự mơ hồ, KHÔNG ĐƯỢC hỏi lại.
Hãy sử dụng các giá trị mặc định sau đây.
## Suy luận ngăn xếp công nghệ (Stack inference)
```text
"web app"
→ frontend=React
→ backend=FastAPI
→ db=SQLite
"API"
→ backend=FastAPI
→ db=SQLite
"todo"
→ FastAPI + SQLite + minimal HTML
unspecified
→ FastAPI + SQLite
```
## Mặc định cho ứng dụng
```text
app_type = "web"
```
Suy luận các trang (pages) từ các danh từ tường minh như:
```text
dashboard
login
projects
tasks
settings
```
Suy luận các thực thể dữ liệu (data entities) từ các danh từ miền nghiệp vụ (domain nouns).
Mọi danh từ chỉ tính năng tường minh đều trở thành một ứng viên bắt buộc phải có (`must_have`).
Các phi mục tiêu (non-goals) mặc định:
```text
deployment
mobile-app
browser-automation
```
trừ khi được yêu cầu một cách tường minh.
## Mặc định cho lập kế hoạch (Planning defaults)
Các ứng dụng nhỏ:
```text
5–12 tasks
```
Mỗi tác vụ (task) NÊN:
```text
touch <= 5 files (chạm tới tối đa 5 tệp)
have >= 1 requirement (có ít nhất 1 yêu cầu)
have >= 1 verification command (có ít nhất 1 lệnh xác minh)
```
## Thời gian chờ tối đa (Timeouts)
```text
sandbox command: 120 seconds (lệnh trong sandbox: 120 giây)
runtime startup: 15 seconds (khởi động runtime: 15 giây)
repair attempts: maximum 3 (số lần thử sửa lỗi: tối đa 3 lần)
```
---
# 8. HỢP ĐỒNG ĐỊNH DANH (IDENTIFIER CONTRACT)
Sử dụng các định dạng ID tất định (deterministic).
```text
REQ-001
REQ-002
TASK-001
TASK-002
TEST-001
TEST-002
run_XXXXXXXX
```
ID Yêu cầu (Requirement ID) và ID Tác vụ (Task ID) bắt buộc phải đánh số tuần tự trong phạm vi một lần chạy (run).
Không bao giờ tái sử dụng một ID cho một đối tượng khác.
---
# 9. HỢP ĐỒNG TẠO PHẨM LẦN CHẠY (RUN ARTIFACT CONTRACT)
Mỗi lần chạy được tạo ra sẽ nằm tại thư mục:
```text
runs/<run_id>/
```
Cấu trúc thư mục cuối cùng bắt buộc phải có:
```text
runs/<run_id>/
├── state.json
├── spec.json
├── tasks.json
├── verification.json
├── review.json
├── events.log
├── checkpoints/
│ ├── 001-spec_created.json
│ ├── 002-plan_created.json
│ └── ...
└── workspace/
├── source code
└── tests
```
Bộ sản phẩm bàn giao cuối cùng chuẩn mực cho mỗi lần chạy là:
```text
workspace/
spec.json
tasks.json
verification.json
review.json
events.log
state.json
```
---
# 10. HỢP ĐỒNG SỰ KIỆN (EVENT CONTRACT)
Tất cả các bước chuyển đổi trạng thái có ý nghĩa đều phải ghi nối tiếp (append) một đối tượng JSON vào tệp:
```text
runs/<run_id>/events.log
```
Các trường bắt buộc:
```text
run_id
trace_id
stage
agent
task_id
timestamp
duration_ms
model
tokens
tool
status
error
```
Các giá trị tùy chọn có thể để trống, nhưng các khóa (keys) bắt buộc phải tồn tại.
---
# 11. HỢP ĐỒNG TRẠNG THÁI (STATUS CONTRACT)
## TaskStatus (Trạng thái tác vụ)
```text
PENDING
READY
RUNNING
COMPLETED
FAILED
TIMED_OUT
BLOCKED
```
Trạng thái `READY` có thể được tính toán động bởi bộ máy DAG thay vì lưu cứng xuống đĩa.
Một tác vụ đã sẵn sàng nhưng chưa bắt đầu khi lưu xuống đĩa vẫn có thể giữ trạng thái:
```text
PENDING
```
## RunStatus (Trạng thái lần chạy)
```text
CREATED
SPEC_DONE
PLAN_DONE
BUILDING
VERIFYING
REPAIRING
REVIEW_DONE
PASS
FAIL
```
Bảo toàn sự phân biệt rõ ràng:
```text
FAILED != TIMED_OUT
```
---
# 12. THỨ TỰ XÂY DỰNG (BUILD ORDER)
Thứ tự các cột mốc (milestone) chính xác là:
```text
M1 Infrastructure (Hạ tầng)
M2 Specification (Đặc tả)
M3 Planning + DAG (Lập kế hoạch + DAG)
M4 Building (Xây dựng)
M5 Verification (Xác minh)
M6 Self-Repair (Tự sửa lỗi)
M7 Traceability (Truy vết)
M8 Requirement Review (Đánh giá yêu cầu)
M9 Recovery (Khôi phục)
M10 Runtime Verification (Xác minh thời gian chạy)
M11 CLI + Benchmarks (Giao diện dòng lệnh + Đo kiểm chuẩn)
M12 Final Gate (Cổng kiểm duyệt cuối cùng)
```
Không được thay đổi thứ tự.
Không được bắt đầu cột mốc `M(N+1)` khi `M(N)` vẫn còn các bài kiểm thử nghiệm thu bị lỗi.
Chạy lệnh:
```bash
pytest -q
```
sau mỗi cột mốc.
---
# M1 — HẠ TẦNG (INFRASTRUCTURE)
## Mục tiêu
Tạo một kho lưu trữ (repository) có thể cài đặt được, bao gồm:
* các mô hình dữ liệu (data models);
* trạng thái lần chạy (run state);
* các nhà cung cấp mô hình (providers);
* môi trường cô lập cục bộ (local sandbox);
* ghi nhật ký sự kiện (event logging);
* bộ sinh ID tất định (deterministic IDs).
Chưa triển khai các tác tử (agents) ở bước này.
## Cấu trúc bắt buộc
```text
app-builder/
├── src/harness/__init__.py
├── src/harness/models/spec.py
├── src/harness/models/tasks.py
├── src/harness/models/results.py
├── src/harness/models/run.py
├── src/harness/state/store.py
├── src/harness/providers/base.py
├── src/harness/providers/mock.py
├── src/harness/providers/env.py
├── src/harness/sandbox/local.py
├── src/harness/utils/logging.py
├── src/harness/utils/ids.py
├── tests/
├── runs/
├── examples/
├── pyproject.toml
├── requirements.txt
├── README.md
└── .gitignore
```
---
## Các mô hình cốt lõi (Core models)
### Stack
```python
frontend: str = "FastAPI"
backend: str = "FastAPI"
db: str = "SQLite"
```
### Requirement
```python
id: str
text: str
must_have: bool = True
acceptance: str = ""
```
### AppSpec
```python
app_type: str
stack: Stack
pages: list[Page]
components: list[Component]
data_model: list[DataEntity]
requirements: list[Requirement]
must_have: list[str]
explicit_non_goals: list[str]
acceptance_criteria: list[str]
```
Đặc tả nguồn không định nghĩa đầy đủ toàn bộ các trường của `Page`, `Component` và `DataEntity`.
Hãy sử dụng các mô hình Pydantic tối giản đủ đáp ứng cho các quy tắc xác thực đã chỉ định; không thêm sự phức tạp nghiệp vụ không liên quan.
### Task
```python
id: str
description: str
depends_on: list[str] = []
files_touched: list[str] = []
requirements: list[str] = []
verification: list[str] = []
status: TaskStatus = PENDING
```
### VerificationResult
```python
task_id: str
status: str
command: str
exit_code: int
stdout: str
stderr: str
duration_ms: int
failure_type: FailureType | None
```
### FailureType
```text
CODE_ERROR
TEST_FAILURE
TYPE_ERROR
DEPENDENCY_ERROR
CONFIG_ERROR
ENVIRONMENT_ERROR
TIMEOUT
UNKNOWN
```
### RequirementResult
```python
requirement_id: str
status: str
evidence: list[str] = []
missing: list[str] = []
```
### RunState
```python
run_id: str
trace_id: str
user_request: str
workspace: str
spec: AppSpec | None
plan: list[Task]
task_results: dict[str, Any]
verification_results: list[VerificationResult]
review: dict | None
checkpoints: list[str]
status: RunStatus
```
Tất cả các mô hình BẮT BUỘC phải sử dụng `BaseModel` của Pydantic v2.
Tất cả các kiểu liệt kê (enums) BẮT BUỘC phải kế thừa từ:
```python
str, Enum
```
---
## LocalSandbox
```python
LocalSandbox(root: Path)
```
Các phương thức bắt buộc:
```python
create_workspace(run_id) -> Path
write_file(rel, content) -> Path
read_file(rel) -> str
list_files(rel=".") -> list[str]
delete_file(rel)
execute(cmd, cwd=None, timeout_s=120) -> dict
```
Mọi đường dẫn BẮT BUỘC phải được phân giải đối chiếu với thư mục gốc của sandbox đã cấu hình.
Từ chối:
```text
../
absolute paths (đường dẫn tuyệt đối)
symlink escape (thoát ra ngoài qua liên kết tượng trưng)
resolved paths outside root (đường dẫn sau phân giải nằm ngoài thư mục gốc)
```
Ưu tiên thực thi câu lệnh dưới dạng:
```python
subprocess.run(list_args, shell=False)
```
Các câu lệnh xác minh bắt buộc phải được phân tích cú pháp bằng `shlex.split()`.
Không được sử dụng `shell=True` trong phiên bản V1.
Trả về:
```json
{
"exit_code": 0,
"stdout": "",
"stderr": "",
"duration_ms": 0
}
```
---
## RunStore
```python
RunStore(base=Path("runs"))
```
Các phương thức:
```python
create_run(user_request) -> RunState
save(state)
load(run_id) -> RunState
checkpoint(state, event_name, payload)
list_runs() -> list[str]
resume(run_id) -> RunState
```
---
## LLMProvider
Giao diện trừu tượng (Abstract interface):
```python
generate(prompt: str, system: str = "") -> str
generate_structured(
prompt: str,
schema: type[BaseModel]
) -> BaseModel
stream(prompt: str) -> Iterator[str]
```
Các tác tử (Agents) CHỈ phụ thuộc vào tầng trừu tượng này.
### MockProvider
Bắt buộc phải:
```text
deterministic (tất định)
offline-safe (an toàn khi ngoại tuyến)
test-friendly (thân thiện với việc kiểm thử)
```
### EnvOpenAICompatibleProvider
Đọc các biến môi trường:
```text
OPENAI_API_KEY
OPENAI_BASE_URL
```
Nếu không có API key:
```text
delegate to MockProvider (ủy quyền xử lý sang cho MockProvider)
```
---
## Nghiệm thu (Acceptance)
Bắt buộc phải vượt qua:
```bash
pip install -e .
pytest -q
```
Các bài kiểm thử bắt buộc phải bao gồm:
```text
AppSpec roundtrip (tuần tự hóa và giải tuần tự hóa AppSpec)
Task roundtrip (tuần tự hóa và giải tuần tự hóa Task)
sandbox ../ rejection (từ chối đường dẫn ../ trong sandbox)
sandbox absolute-path rejection (từ chối đường dẫn tuyệt đối trong sandbox)
RunStore save/load (lưu và tải lại bằng RunStore)
MockProvider deterministic behavior (hành vi tất định của MockProvider)
```
Không yêu cầu kết nối mạng.
## Nghiêm cấm (Forbidden)
Không được triển khai ở bước này:
```text
SpecAgent
Planner
Builder
Verifier
DAG execution
```
---
# M2 — TÁC TỬ ĐẶC TẢ + BỘ XÁC THỰC (SPECIFICATION AGENT + VALIDATOR)
## Mục tiêu
Chuyển đổi:
```text
user request (yêu cầu của người dùng)
```
thành:
```text
validated spec.json (tệp spec.json đã được xác thực)
```
Chưa thực hiện sinh mã nguồn ứng dụng ở bước này.
## Các tệp tin
```text
src/harness/agents/spec.py
src/harness/validation/spec_validator.py
tests/test_spec.py
examples/todo_spec.json
```
---
## SpecAgent
Giao diện (Interface):
```python
SpecAgent(llm: LLMProvider)
generate(user_request: str) -> AppSpec
```
Chỉ dẫn hệ thống (System instruction):
```text
Output ONLY JSON matching AppSpec.
No prose.
Infer stack, pages, data model, requirements,
must-have features, explicit non-goals and acceptance criteria.
```
Bước hậu xử lý (Post-processing) BẮT BUỘC phải:
```text
assign REQ-001..N (gán mã REQ-001..N)
ensure must_have is non-empty (đảm bảo must_have không rỗng)
ensure acceptance_criteria is non-empty (đảm bảo acceptance_criteria không rỗng)
populate default explicit_non_goals when absent (điền giá trị mặc định cho explicit_non_goals khi bị thiếu)
```
Nếu đầu ra của LLM không hợp lệ:
```text
use deterministic rule-based fallback (sử dụng cơ chế dự phòng tất định dựa trên tập luật)
```
Cơ chế dự phòng bắt buộc phải hiểu được tối thiểu các miền:
```text
auth
projects
tasks
dashboard
todo
```
---
## SpecValidator
Trả về:
```python
list[str]
```
Danh sách rỗng đồng nghĩa với PASS (ĐẠT).
### Kiểm tra cấu trúc (Structural checks)
Xác minh:
```text
app_type non-empty (app_type không rỗng)
stack fields non-empty (các trường của stack không rỗng)
requirements >= 1 (số lượng yêu cầu >= 1)
acceptance_criteria >= 1 (số tiêu chí nghiệm thu >= 1)
REQ IDs unique (các mã REQ không trùng lặp)
REQ IDs match ^REQ-\d{3}$ (mã REQ khớp biểu thức ^REQ-\d{3}$)
```
### Kiểm tra logic (Logical checks)
Xác minh:
```text
page.entity references known data entity when entity is present (page.entity tham chiếu đến thực thể dữ liệu đã biết khi trường entity có mặt)
requirement does not conflict with explicit non-goal (yêu cầu không mâu thuẫn với phi mục tiêu tường minh)
backend is defined when requirement mentions API/backend (backend phải được định nghĩa khi yêu cầu có nhắc tới API/backend)
requirement text is unique case-insensitively (nội dung yêu cầu là duy nhất không phân biệt hoa thường)
every must_have maps to >=1 requirement (mọi mục must_have đều ánh xạ tới >=1 yêu cầu)
```
---
## Chặng đường ống (Pipeline stage)
Triển khai:
```python
spec_stage(
store,
run_id,
llm,
max_attempts=2
)
```
Luồng xử lý:
```text
generate (sinh đặc tả)
→ validate (xác thực)
→ if invalid: regenerate with validation feedback (nếu không hợp lệ: sinh lại kèm theo phản hồi lỗi xác thực)
→ maximum 2 generation attempts (tối đa 2 lần thử sinh)
→ persist spec (lưu trữ đặc tả)
→ checkpoint spec_created (tạo điểm lưu trạng thái spec_created)
```
Lưu trữ tại:
```text
runs/<run_id>/spec.json
```
---
## Nghiệm thu (Acceptance)
Kiểm thử:
```text
valid Todo request → PASS (yêu cầu Todo hợp lệ → ĐẠT)
conflicting login non-goal → FAIL (phi mục tiêu đăng nhập bị mâu thuẫn → THẤT BẠI)
missing acceptance → FAIL (thiếu tiêu chí nghiệm thu → THẤT BẠI)
duplicate requirement → FAIL (yêu cầu bị trùng lặp → THẤT BẠI)
first generation invalid + second valid → PASS (lần sinh đầu không hợp lệ + lần thứ hai hợp lệ → ĐẠT)
```
Tạo tệp:
```text
examples/todo_spec.json
```
với bốn yêu cầu.
## Nghiêm cấm (Forbidden)
Chưa lập kế hoạch (No planning).
Chưa sinh mã nguồn (No code generation).
---
# M3 — BỘ LẬP KẾ HOẠCH + BỘ MÁY DAG (PLANNER + DAG ENGINE)
## Mục tiêu
Chuyển đổi:
```text
AppSpec
```
thành:
```text
validated sequential Task DAG (đồ thị Task DAG tuần tự đã được xác thực)
```
Lưu trữ tại:
```text
tasks.json
```
## Các tệp tin
```text
src/harness/agents/planner.py
src/harness/orchestration/dag.py
src/harness/orchestration/runner.py
tests/test_planner.py
tests/test_dag.py
```
---
## Quy tắc của Bộ lập kế hoạch (Planner rules)
Cưỡng chế thực thi các quy tắc này ngay trong mã nguồn.
KHÔNG ĐƯỢC chỉ phụ thuộc vào câu lệnh prompt gửi cho LLM.
### Thứ tự thực hiện (Ordering)
1. Cơ sở dữ liệu / lược đồ (DB/schema) phải đi trước logic ứng dụng phụ thuộc vào nó.
2. Các thành phần dùng chung (Shared components) phải đi trước các trang (pages).
3. Hạ tầng xác thực (Auth infrastructure) phải đi trước các tuyến đường yêu cầu xác thực (authenticated routes).
### Độ bao phủ (Coverage)
Mọi:
```text
REQ
```
bắt buộc phải ánh xạ tới ít nhất một Task.
Mọi Task bắt buộc phải chứa:
```text
>=1 requirement (ít nhất 1 yêu cầu)
>=1 file (ít nhất 1 tệp tin)
>=1 verification command (ít nhất 1 câu lệnh xác minh)
```
### Định danh (IDs)
Sinh mã theo định dạng:
```text
TASK-001
TASK-002
...
```
Các phụ thuộc (dependencies) chỉ được phép tham chiếu tới các tác vụ đứng trước đó.
Nếu đầu ra của LLM vi phạm thứ tự:
```text
repair deterministically (tự động sửa lại một cách tất định)
```
### Đường dẫn (Paths)
Mọi đường dẫn trong `files_touched` bắt buộc phải:
```text
relative (là đường dẫn tương đối)
POSIX-style (theo chuẩn dấu gạch chéo POSIX)
inside workspace (nằm bên trong thư mục workspace)
without .. (không chứa ký hiệu ..)
```
---
## Bộ lập kế hoạch dự phòng (Fallback planner)
Nếu việc lập kế hoạch bằng LLM thất bại, hãy sinh các tác vụ tất định bao phủ đại략 các phần:
```text
project/schema setup (thiết lập dự án/lược đồ)
auth if required (xác thực nếu có yêu cầu)
core entity CRUD (các thao tác CRUD cho thực thể cốt lõi)
API/pages (API/các trang giao diện)
tests/verification (kiểm thử/xác minh)
```
Đối với các ứng dụng nhỏ:
```text
5–12 tasks
```
---
## DagEngine
Hành vi bắt buộc:
```python
get_ready()
mark(task_id, status)
is_done()
blocked_propagation()
topological_order()
```
Một tác vụ đạt trạng thái READY khi và chỉ khi:
```text
status == PENDING
AND
all dependencies == COMPLETED
```
Nếu tác vụ phụ thuộc chuyển sang trạng thái:
```text
FAILED
TIMED_OUT
```
thì các tác vụ phụ thuộc vào nó sẽ chuyển sang trạng thái:
```text
BLOCKED
```
Nếu phát hiện chu trình (cycles), bắt buộc phải ném ra lỗi tường minh.
---
## PlanValidator
Phát hiện các lỗi:
```text
duplicate task IDs (trùng lặp ID tác vụ)
unknown dependency (phụ thuộc không xác định)
cycle (chu trình lặp)
orphan requirement (yêu cầu bị bỏ rơi không có tác vụ)
task without verification (tác vụ không có lệnh xác minh)
task without files (tác vụ không có tệp tin nào)
task without requirements (tác vụ không gắn với yêu cầu nào)
invalid paths (đường dẫn không hợp lệ)
```
Các tệp tin bị trùng chéo giữa các tác vụ (Overlapping files):
```text
WARNING only in V1 (Chỉ cảnh báo WARNING trong phiên bản V1)
```
---
## Nghiệm thu (Acceptance)
Đặc tả Todo với bốn yêu cầu:
```text
→ 5–8 tasks
```
Các bài kiểm thử:
```text
all requirements covered (toàn bộ yêu cầu đều được bao phủ)
dependency ordering valid (thứ tự phụ thuộc hợp lệ)
cycle rejected (từ chối khi có chu trình)
TASK-001 failure blocks dependent task (TASK-001 thất bại sẽ khóa các tác vụ phụ thuộc)
tasks.json persisted (lưu trữ thành công tasks.json)
plan_created checkpoint persisted (lưu trữ thành công điểm khôi phục plan_created)
```
## Nghiêm cấm (Forbidden)
Chưa thực thi Builder (No Builder execution).
Không xử lý đồng thời/song song (No concurrency).
---
# M4 — BỘ XÂY DỰNG + CÔNG CỤ TỆP TIN KIỂM SOÁT QUA SANDBOX (BUILDER + SANDBOX-GATED FILE TOOLS)
## Mục tiêu
Chuyển đổi một Task thành các tệp tin thực tế.
## Các tệp tin
```text
src/harness/agents/builder.py
src/harness/tools/files.py
tests/test_builder.py
```
---
## Ngữ cảnh của Builder (Builder context)
CHỈ cung cấp:
```text
current Task (Task hiện tại)
requirements referenced by Task (các yêu cầu được Task tham chiếu tới)
small spec summary (bản tóm tắt đặc tả ngắn gọn)
dependency verification results (kết quả xác minh của các tác vụ phụ thuộc)
allowed files (danh sách các tệp được phép tác động)
verification commands (các câu lệnh xác minh)
```
KHÔNG ĐƯỢC đổ toàn bộ lịch sử lần chạy vào ngữ cảnh.
Ví dụ đầu vào:
```python
task
requirements
spec_summary = {
"app_type": ...,
"stack": ...,
"data_model": ...
}
dependency_results
allowed_files
verification
```
---
## Đầu ra của Builder (Builder output)
LLM bắt buộc phải sinh ra:
```json
{
"relative/path.py": "full file contents"
}
```
Không có văn bản giải thích (No prose).
Không dùng hàng rào mã markdown (No markdown fences).
---
## Giới hạn quyền ghi (Write restrictions)
Builder CHỈ được phép ghi vào:
```text
task.files_touched
```
Bất kỳ nỗ lực ghi tệp nào nằm ngoài danh sách cho phép (allowlist) sẽ dẫn tới:
```text
PermissionError
+
event log (ghi nhận vào nhật ký sự kiện)
+
task failure (đánh dấu tác vụ thất bại)
+
CONFIG_ERROR
```
Builder chỉ được phép sử dụng các hàm đã qua kiểm soát sandbox:
```text
read_file
write_file
list_files
```
Builder KHÔNG ĐƯỢC phép thực thi tiến trình con (subprocesses).
---
## Cơ chế dự phòng tất định (Deterministic fallback)
Nếu không thể phân tích cú pháp đầu ra của LLM, hãy sử dụng một bản triển khai tất định cho tác vụ hiện tại.
Cơ chế dự phòng BẮT BUỘC phải tuân thủ cùng danh sách cho phép `files_touched`.
Do đó, bộ lập kế hoạch dự phòng BẮT BUỘC phải đảm bảo mọi tệp khung (scaffold files) tất định đều được liệt kê rõ ràng trong tác vụ liên quan.
Ứng dụng tham chiếu được sinh ra có thể bao gồm:
```text
src/main.py
src/models.py
requirements.txt
tests/test_health.py
```
Không được tạo thêm các tệp nằm ngoài tập hợp đã khai báo của Task hiện tại.
---
## Nghiệm thu (Acceptance)
Kiểm thử:
```text
allowed file write succeeds (ghi tệp nằm trong danh sách cho phép thành công)
outside-allowlist write fails (ghi tệp nằm ngoài danh sách cho phép thất bại)
../ escape fails (thoát thư mục bằng ../ thất bại)
MockProvider creates deterministic output (MockProvider tạo ra đầu ra tất định)
checkpoint created after task (điểm lưu trạng thái được tạo sau khi xong tác vụ)
```
Sau cột mốc này:
```bash
pytest -q
```
bắt buộc phải vượt qua (pass).
## Nghiêm cấm (Forbidden)
Không thực thi xác minh bên trong Builder.
Chưa thực hiện sửa lỗi (No repair).
---
# M5 — XÁC MINH THỰC TẾ + PHÂN LOẠI LỖI (REAL VERIFICATION + FAILURE CLASSIFICATION)
## Mục tiêu
Thực thi các câu lệnh xác minh thực tế và lưu trữ bền vững bằng chứng có cấu trúc.
## Các tệp tin
```text
src/harness/verification/verifier.py
src/harness/verification/classifier.py
tests/test_verifier.py
tests/test_classifier.py
```
---
## Bộ xác minh (Verifier)
Triển khai:
```python
verify_task(
task: Task,
workspace: Path
) -> list[VerificationResult]
```
Đối với mọi câu lệnh xác minh:
```text
shlex.split(command)
→ LocalSandbox.execute(...)
```
Giá trị mặc định khi bị thiếu:
```bash
pytest -q
```
Thu thập:
```text
exit_code
stdout[-4000:]
stderr[-4000:]
duration_ms
```
ĐẠT (PASS):
```text
exit_code == 0
```
THẤT BẠI (FAIL):
```text
exit_code != 0
```
Quá thời gian chờ (Timeout):
```text
Task status = TIMED_OUT
FailureType = TIMEOUT
```
Việc chỉ kiểm tra mã tĩnh (static inspection) không bao giờ được tính là đã xác minh.
---
## Xác minh không gian làm việc (Workspace verification)
Cung cấp hàm bổ trợ (helper):
```python
verify_workspace(workspace)
```
Hàm này có thể bao gồm các bước kiểm tra cấp độ dự án phù hợp với những tệp thực sự có mặt.
Không được mù quáng yêu cầu cài đặt qua mạng bên ngoài như một phần của các bài kiểm thử đơn vị (unit tests) ngoại tuyến của harness.
---
## Thứ tự ưu tiên của bộ phân loại lỗi (Failure classifier precedence)
Việc phân loại BẮT BUỘC phải mang tính tất định (deterministic).
Sử dụng thứ tự ưu tiên từ cao xuống thấp:
```text
1. TIMEOUT
2. ENVIRONMENT_ERROR
3. DEPENDENCY_ERROR
4. TYPE_ERROR
5. CODE_ERROR
6. CONFIG_ERROR
7. TEST_FAILURE
8. UNKNOWN
```
Thứ tự ưu tiên này rất quan trọng.
Ví dụ, một phiên chạy pytest có chứa lỗi `SyntaxError` của Python bắt buộc phải được phân loại là:
```text
CODE_ERROR
```
chứ không đơn thuần là `TEST_FAILURE`.
### TIMEOUT
Các mẫu nhận diện (Patterns):
```text
timed out
TimeoutExpired
duration >= configured timeout
```
### ENVIRONMENT_ERROR
Các mẫu nhận diện:
```text
EAI_AGAIN
ENOTFOUND
registry unavailable
Network is unreachable
HTTP 503
Could not fetch
```
### DEPENDENCY_ERROR
Các mẫu nhận diện:
```text
ModuleNotFoundError
ImportError
No module named
Could not resolve dependency
npm ERR 404
```
### TYPE_ERROR
Các mẫu nhận diện:
```text
mypy
Pydantic ValidationError
TypeError ... expected
TS2322
Property ... does not exist
```
### CODE_ERROR
Các mẫu nhận diện:
```text
SyntaxError
IndentationError
NameError
ReferenceError
```
### CONFIG_ERROR
Các mẫu nhận diện:
```text
missing configuration
missing pyproject
requirements file not found
port already in use
invalid path configuration
```
### TEST_FAILURE
Các mẫu nhận diện:
```text
AssertionError
FAILED
1 failed
FAIL tests/
```
Chỉ phân loại vào nhóm này sau khi tất cả các danh mục có độ ưu tiên cao hơn đã được loại trừ.
---
## Nghiệm thu (Acceptance)
Các bài kiểm thử:
```text
SyntaxError → CODE_ERROR
ModuleNotFoundError → DEPENDENCY_ERROR
AssertionError → TEST_FAILURE
network unavailable → ENVIRONMENT_ERROR
timeout → TIMEOUT
working scaffold → PASS
```
Lưu trữ bền vững bằng chứng xác minh.
## Nghiêm cấm (Forbidden)
Chưa thực hiện tự động sửa lỗi (No automatic repair yet).
---
# M6 — VÒNG LẶP SỬA LỖI + PHÁT HIỆN LẶP VÔ HẠN (REPAIR LOOP + LOOP DETECTION)
## Mục tiêu
Triển khai quy trình:
```text
FAIL
→ classify (phân loại)
→ repair (sửa lỗi)
→ verify (xác minh lại)
```
với số lần thử lại có giới hạn (bounded retries).
## Các tệp tin
```text
src/harness/orchestration/repair.py
src/harness/agents/repair_agent.py
tests/test_repair.py
```
---
## Chữ ký phát hiện vòng lặp (Loop signature)
```python
sha256(
command
+ exit_code
+ normalize(stderr[-2000:])
)
```
Chuẩn hóa (Normalization):
```text
lowercase (chuyển về chữ thường)
strip changing timestamps (loại bỏ các dấu thời gian thay đổi)
strip volatile numeric values (loại bỏ các giá trị số biến động)
normalize paths (chuẩn hóa đường dẫn)
collapse whitespace (gom gọn khoảng trắng)
```
Theo dõi:
```python
seen[signature] += 1
```
Nếu cùng một chữ ký lỗi đã chuẩn hóa xuất hiện ba lần:
```text
ESCALATE (báo cáo leo thang)
FAILED (đánh dấu thất bại)
BLOCK dependents (khóa các tác vụ phụ thuộc)
```
Tổng số lần thử sửa lỗi BẮT BUỘC KHÔNG BAO GIỜ vượt quá:
```text
3
```
---
## Chiến lược sửa lỗi (Repair strategy)
### ENVIRONMENT_ERROR
```text
Do not rewrite application code. (Không viết lại mã nguồn ứng dụng.)
Retry once. (Thử lại một lần.)
If still failing → FAILED. (Nếu vẫn thất bại → FAILED.)
```
### DEPENDENCY_ERROR
Chỉ sửa chữa các tệp phụ thuộc/cấu hình đã nằm sẵn trong danh sách cho phép của Task hoặc được liệt kê tường minh dưới dạng gợi ý xác minh.
### TYPE_ERROR
Chỉ vá (patch) phần mã nguồn có liên quan.
### CODE_ERROR
Chỉ vá phần mã nguồn có liên quan.
### TEST_FAILURE
Chỉ vá mã triển khai hoặc bài kiểm thử khi có căn cứ chính đáng từ bằng chứng yêu cầu.
Tuyệt đối không làm yếu bài kiểm thử chỉ để lấy kết quả PASS.
### CONFIG_ERROR
Chỉ vá các tệp cấu hình.
### TIMEOUT
Cho phép điều chỉnh/thử lại có giới hạn một lần duy nhất.
Không được tạo thời gian chờ vô hạn (unbounded timeout).
---
## Ngữ cảnh của RepairAgent (RepairAgent context)
Cung cấp:
```text
Task
relevant requirement slice (phần lát cắt yêu cầu có liên quan)
failing VerificationResult (kết quả VerificationResult bị lỗi)
FailureType (loại lỗi FailureType)
allowed files (các tệp được phép sửa)
current relevant file contents (nội dung hiện tại của các tệp liên quan)
```
Cắt bớt ngữ cảnh mã nguồn lớn ở mức khoảng:
```text
8000 chars per repair context (8000 ký tự cho mỗi ngữ cảnh sửa lỗi)
```
Đầu ra:
```json
{
"relative/path": "full corrected contents"
}
```
---
## Nghiệm thu (Acceptance)
Các bài kiểm thử:
```text
repair SyntaxError → PASS within <=3 attempts (sửa lỗi SyntaxError → ĐẠT trong vòng <=3 lần thử)
same failure 3 times → ESCALATE (cùng một lỗi lặp lại 3 lần → LEO THANG)
dependents become BLOCKED (các tác vụ phụ thuộc chuyển sang trạng thái BLOCKED)
ENVIRONMENT_ERROR does not modify code (ENVIRONMENT_ERROR không sửa đổi mã nguồn)
files outside allowlist cannot be repaired (không thể sửa các tệp nằm ngoài danh sách cho phép)
```
---
# M7 — MA TRẬN TRUY VẾT (TRACEABILITY MATRIX)
## Mục tiêu
Xây dựng bằng chứng cơ học:
```text
Requirement (Yêu cầu)
→ Tasks (Các tác vụ)
→ Files (Các tệp tin)
→ Verification (Lệnh xác minh)
→ Result (Kết quả)
```
## Các tệp tin
```text
src/harness/trace/matrix.py
tests/test_trace.py
```
---
## Cấu trúc ma trận (Matrix structure)
Đối với mọi yêu cầu:
```json
{
"REQ-001": {
"tasks": [],
"files": [],
"tests": [],
"evidence": [],
"status": "PASS|FAIL",
"missing": []
}
}
```
Tính toán:
```text
tasks
= tasks referencing REQ (các tác vụ tham chiếu tới REQ)
files
= union(task.files_touched) (hợp các tệp trong task.files_touched)
tests
= union(task.verification) (hợp các lệnh xác minh trong task.verification)
evidence
= existing files (các tệp đang tồn tại)
+ successful verification commands (các lệnh xác minh chạy thành công)
```
Chỉ đạt PASS nếu:
```text
>=1 expected implementation file exists (có ít nhất 1 tệp triển khai dự kiến tồn tại)
AND
>=1 relevant verification result PASS (có ít nhất 1 kết quả xác minh liên quan đạt PASS)
```
Không có bằng chứng:
```text
FAIL
```
Văn bản giải thích (prose) không bao giờ có thể thay thế cho bằng chứng.
---
## Nghiệm thu (Acceptance)
Lần chạy tham chiếu ứng dụng Todo:
```text
4/4 requirements traced (truy vết được 4/4 yêu cầu)
```
Khi xóa đi một tệp triển khai:
```text
associated requirement becomes FAIL (yêu cầu liên quan chuyển sang trạng thái FAIL)
```
---
# M8 — ĐÁNH GIÁ YÊU CẦU (REQUIREMENT REVIEW)
## Mục tiêu
Thực hiện bước kiểm toán cuối cùng ở cấp độ từng yêu cầu.
## Các tệp tin
```text
src/harness/agents/reviewer.py
tests/test_review.py
```
---
## ReviewAgent
Thẩm quyền quyết định mặc định:
```text
rule-based evidence (bằng chứng dựa trên tập luật)
```
Đánh giá của LLM là tùy chọn và chỉ mang tính chất giải thích bổ sung.
LLM ĐƯỢC PHÉP:
```text
add rationale (bổ sung lý giải)
summarize evidence (tóm tắt bằng chứng)
identify concerns (chỉ ra các điểm đáng lưu tâm)
```
LLM BẮT BUỘC KHÔNG ĐƯỢC:
```text
turn evidence-based FAIL into PASS (biến trạng thái FAIL dựa trên bằng chứng thành PASS)
```
---
## Đầu ra (Output)
Lưu trữ bền vững tại:
```text
runs/<run_id>/review.json
```
Cấu trúc dữ liệu:
```json
{
"requirements": [
{
"id": "REQ-001",
"status": "PASS",
"evidence": [],
"missing": []
}
],
"overall_status": "PASS"
}
```
Trạng thái tổng thể chỉ đạt PASS nếu:
```text
every requirement == PASS (mọi yêu cầu đều đạt PASS)
```
---
## Nghiệm thu (Acceptance)
Các bài kiểm thử:
```text
complete evidence → PASS (đầy đủ bằng chứng → PASS)
missing implementation file → FAIL (thiếu tệp triển khai → FAIL)
missing successful verification → FAIL (thiếu kết quả xác minh thành công → FAIL)
LLM cannot override FAIL (LLM không thể ghi đè trạng thái FAIL)
review JSON validates (JSON đánh giá hợp lệ theo lược đồ)
```
---
# M9 — LƯU ĐIỂM KHÔI PHỤC + PHỤC HỒI SAU SỰ CỐ (CHECKPOINTING + CRASH RECOVERY)
## Mục tiêu
Tiếp tục chạy lại các lần chạy bị gián đoạn mà không lặp lại những phần việc đã hoàn thành.
## Các tệp tin
```text
src/harness/state/checkpoints.py
src/harness/orchestration/pipeline.py
tests/test_recovery.py
```
---
## Các sự kiện điểm khôi phục bắt buộc (Required checkpoint events)
```text
spec_created
plan_created
task_started
task_completed
verification_completed
repair_started
review_completed
```
Quy ước đặt tên tệp:
```text
checkpoints/<sequence>-<event>-<optional-task>.json
```
Ví dụ:
```text
001-spec_created.json
002-plan_created.json
003-task_started-TASK-001.json
004-task_completed-TASK-001.json
```
---
## Thuật toán tiếp tục chạy (Resume algorithm)
```text
load state.json (tải tệp state.json)
↓
validate state (xác thực trạng thái)
↓
load latest checkpoint state (tải trạng thái điểm khôi phục mới nhất)
↓
reconstruct task statuses (tái tạo lại trạng thái của các tác vụ)
↓
keep COMPLETED (giữ nguyên COMPLETED)
keep FAILED (giữ nguyên FAILED)
keep BLOCKED (giữ nguyên BLOCKED)
convert interrupted RUNNING → PENDING (chuyển RUNNING bị gián đoạn → PENDING)
convert READY → PENDING (chuyển READY → PENDING)
↓
continue unfinished pipeline (tiếp tục chạy phần đường ống chưa hoàn thành)
```
Các tác vụ đã COMPLETED BẮT BUỘC KHÔNG ĐƯỢC thực thi lại.
Sử dụng mã băm tệp tin (file hashes) ở những nơi phù hợp để chứng minh rằng đầu ra đã hoàn thành không bị ghi đè lại trong quá trình khôi phục chạy tiếp.
---
## Xử lý hỏng dữ liệu (Corruption handling)
Khi bị hỏng dữ liệu ở:
```text
state.json
checkpoint JSON
```
bắt buộc phải đưa ra một thông báo lỗi rõ ràng, tường minh.
Không bao giờ được âm thầm khởi động lại lần chạy từ đầu.
---
## Nghiệm thu (Acceptance)
Mô phỏng sự cố sập chương trình sau:
```text
TASK-002
```
Quá trình khôi phục chạy tiếp (Resume) bắt buộc phải:
```text
finish remaining tasks (hoàn thành các tác vụ còn lại)
not rerun TASK-001 (không chạy lại TASK-001)
not alter completed file hashes (không làm thay đổi mã băm của các tệp đã hoàn thành)
```
Kiểm thử trình tự đánh số của các điểm khôi phục (checkpoint sequencing).
---
# M10 — XÁC MINH THỜI GIAN CHẠY (RUNTIME VERIFICATION)
## Mục tiêu
Chứng minh rằng ứng dụng được sinh ra thực sự khởi động được và phản hồi thành công.
Chỉ riêng các bài kiểm thử tĩnh là chưa đủ.
## Các tệp tin
```text
src/harness/verification/runtime.py
src/harness/verification/browser.py
tests/test_runtime.py
```
---
## RuntimeVerifier
### Nhận diện điểm vào (Entry detection)
Nhận diện tối thiểu các dạng:
```text
src/main.py:app
app.py:app
package.json
```
Khi không nhận diện được điểm vào nào:
```text
FAIL
CONFIG_ERROR
```
### Khởi động (Start)
Đối với FastAPI:
```bash
python -m uvicorn src.main:app --port <free_port>
```
Dự phòng đối với Node:
```bash
npm run dev -- --port <free_port>
```
Sử dụng một cổng cục bộ còn trống hoặc do hệ điều hành cấp phát.
Khởi chạy tiến trình bằng:
```python
subprocess.Popen
```
với:
```text
cwd jailed inside workspace (thư mục làm việc hiện tại bị giam cố định bên trong workspace)
shell=False
```
Tầng xác minh được phép nắm quyền thực thi tiến trình; các tác tử xây dựng ứng dụng thì không được phép.
### Thời gian chờ khởi động tối đa (Startup timeout)
```text
15 seconds (15 giây)
```
### Các bước kiểm tra (Checks)
Xác minh:
```text
process remains alive (tiến trình vẫn đang sống)
TCP port accepts connection (cổng TCP chấp nhận kết nối)
GET /health OR / returns 2xx (lệnh gọi GET /health HOẶC / trả về mã 2xx)
GET /docs or /api/health when available (lệnh gọi GET /docs hoặc /api/health khi có sẵn)
SQLite DB can be opened when expected (cơ sở dữ liệu SQLite có thể mở được khi dự kiến sử dụng)
```
### Dọn dẹp (Cleanup)
Luôn luôn chấm dứt (terminate) tiến trình đã khởi tạo.
Sử dụng khối `finally` để dọn dẹp.
Không bao giờ để sót lại các máy chủ phát triển mồ côi (orphan development servers) chạy ngầm.
### Kết quả (Result)
Trả về dữ liệu có cấu trúc:
```json
{
"status": "PASS",
"checks": [
{
"name": "health",
"ok": true,
"detail": "HTTP 200"
}
],
"evidence": []
}
```
Thu thập các đoạn nhật ký (log snippets) hữu ích.
---
## Bản giữ chỗ trình duyệt cho V1 (Browser V1 stub)
Chỉ triển khai:
```python
def verify_acceptance(...):
raise NotImplementedError(
"Browser verification deferred post-V1"
)
```
Kiểm thử để đảm bảo bộ xác minh trình duyệt vẫn được giữ ở trạng thái hoãn lại tường minh.
KHÔNG ĐƯỢC cài đặt Playwright hoặc Selenium.
---
## Nghiệm thu (Acceptance)
Ứng dụng tham chiếu:
```text
starts (khởi động được)
port opens (cổng mở thành công)
health endpoint returns 200 (điểm cuối kiểm tra sức khỏe trả về mã 200)
runtime verifier PASS (bộ xác minh thời gian chạy đạt PASS)
```
Khi khởi động bị lỗi:
```text
FAIL
diagnostics captured (thu thập được thông tin chẩn đoán)
repair hint available (có gợi ý sửa lỗi)
```
---
# M11 — GIAO DIỆN DÒNG LỆNH + ĐO KIỂM CHUẨN (CLI + BENCHMARKS)
## Mục tiêu
Cung cấp toàn bộ chức năng của harness thông qua một giao diện dòng lệnh tất định và cung cấp bài đo kiểm hồi quy nhanh (quick regression benchmark).
## Các tệp tin
```text
src/harness/cli.py
src/harness/orchestration/pipeline.py
src/harness/benchmarks.py
tests/test_cli.py
tests/test_benchmarks.py
```
Thêm điểm vào dòng lệnh (console entrypoint):
```toml
[project.scripts]
builder = "harness.cli:main"
```
Sử dụng:
```text
argparse only (chỉ sử dụng thư viện chuẩn argparse)
```
Không phụ thuộc vào Click hay Typer.
---
## Các câu lệnh CLI
### Tạo lần chạy mới (New run)
```bash
builder new "Build a Todo app"
```
Dạng chạy qua mô-đun tương đương:
```bash
python -m harness.cli new "Build a Todo app"
```
Câu lệnh này bắt buộc phải thực thi toàn bộ đường ống (pipeline).
### Tiếp tục chạy lại (Resume)
```bash
builder resume <run_id>
```
### Xem nhật ký (Logs)
```bash
builder logs <run_id>
```
In ra hoặc theo dõi phần cuối (tail) tệp nhật ký sự kiện có cấu trúc của lần chạy dưới định dạng dễ đọc.
### Chạy đo kiểm chuẩn (Benchmark)
```bash
builder bench --quick
```
---
## Đầu ra tiến độ (Progress output)
Lệnh `builder new` bắt buộc phải xuất ra năm chặng cấp cao hiển thị cho người dùng:
```text
[1/5] SPEC
[2/5] PLAN
[3/5] BUILD
[4/5] VERIFY
[5/5] REVIEW
```
Các cột mốc nội bộ chi tiết vẫn là M1–M12; chế độ hiển thị năm chặng trên CLI chỉ là phần trình bày giao diện.
Khi thành công:
```text
BUILD COMPLETE
```
Khi thất bại:
```text
BUILD FAILED
```
và trả về mã thoát khác không (non-zero exit status).
---
## Bài đo kiểm chuẩn nhanh (Quick benchmark)
Lệnh `builder bench --quick` chạy một kịch bản ứng dụng Todo nhỏ mang tính tất định.
Nó bắt buộc phải xác thực tối thiểu các mục:
```text
spec generated (đã sinh đặc tả)
plan generated (đã sinh kế hoạch)
files written (đã ghi các tệp tin)
verification executed (đã thực thi xác minh)
runtime checked (đã kiểm tra thời gian chạy)
review produced (đã tạo kết quả đánh giá)
required artifacts exist (tồn tại đầy đủ các tạo phẩm bắt buộc)
```
Trả về:
```text
0 → PASS
non-zero → FAIL
```
---
## Nghiệm thu (Acceptance)
Bắt buộc phải vượt qua:
```bash
builder new "Build a Todo app"
builder bench --quick
```
Cơ chế dự phòng LLM ngoại tuyến vẫn phải hoạt động bình thường.
Xác minh:
```text
all required artifacts exist (tất cả tạo phẩm bắt buộc đều tồn tại)
five-stage output matches expected format (đầu ra năm chặng khớp với định dạng mong đợi)
events.log contains required keys (events.log chứa đầy đủ các khóa bắt buộc)
quick benchmark passes (bài đo kiểm nhanh vượt qua thành công)
```
## Nghiêm cấm (Forbidden)
Không làm giao diện Web (No Web UI).
Không dùng môi trường Docker production.
---
# M12 — CỔNG KIỂM DUYỆT CUỐI CÙNG (FINAL GATE)
## Mục tiêu
Chứng minh độ tin cậy của phiên bản V1 trước khi tuyên bố hoàn thành.
Tất cả các cổng kiểm duyệt dưới đây đều là bắt buộc.
---
## Cổng 1 — Lát cắt dọc toàn trình (Vertical Slice)
Chạy lệnh:
```bash
builder new "Build a Simple Todo App with add/list/complete"
```
Đường ống xử lý kỳ vọng:
```text
SPEC
→ >=3 REQs
→ PLAN
→ >=3 tasks
→ BUILD
→ real files
→ VERIFY
→ pytest PASS
→ RUNTIME
→ PASS
→ REVIEW
→ PASS
```
Lưu lại một lần chạy trình diễn ổn định tại:
```text
runs/demo_todo/
```
Nếu bất kỳ chặng nào thất bại:
```text
fix the harness (sửa lỗi trong harness)
rerun (chạy lại)
do not proceed (không được phép đi tiếp)
```
---
## Cổng 2 — Tiêm lỗi thử nghiệm (Failure Injection)
Tiêm đoạn mã lỗi:
```python
SyntaxError
```
vào tệp:
```text
workspace/src/main.py
```
Harness bắt buộc phải thực hiện:
```text
DETECT (PHÁT HIỆN)
→ FAIL
CLASSIFY (PHÂN LOẠI)
→ CODE_ERROR
LOCALIZE (KHOANH VÙNG)
→ TASK-ID
CAPTURE (THU THẬP)
→ diagnostics (thông tin chẩn đoán)
REPAIR (SỬA LỖI)
→ relevant file only (chỉ sửa tệp có liên quan)
REVERIFY (XÁC MINH LẠI)
→ PASS
```
Sau đó mô phỏng cùng một lỗi lặp đi lặp lại bằng cách dùng bản triển khai sửa lỗi rỗng (no-op repair implementation).
Kết quả kỳ vọng:
```text
same signature x3 (cùng một chữ ký lỗi lặp lại 3 lần)
→ LOOP DETECTED (PHÁT HIỆN VÒNG LẶP)
→ ESCALATE (BÁO CÁO LEO THANG)
→ task FAILED (tác vụ chuyển sang FAILED)
→ dependents BLOCKED (các tác vụ phụ thuộc chuyển sang BLOCKED)
```
---
## Cổng 3 — Danh sách kiểm tra năng lực V1 (V1 Capability Checklist)
Tất cả BẮT BUỘC phải đạt dấu ✓:
```text
[ ] valid spec generated (sinh được đặc tả hợp lệ)
[ ] spec validated (đặc tả đã qua xác thực)
[ ] valid DAG generated (sinh được đồ thị DAG hợp lệ)
[ ] sequential execution (thực thi tuần tự)
[ ] real files created (tạo ra các tệp tin thực tế)
[ ] real verification executed (thực thi xác minh thực tế)
[ ] failures localized (khoanh vùng được lỗi)
[ ] failures classified (phân loại được lỗi)
[ ] failures repaired (sửa chữa được lỗi)
[ ] repair bounded <=3 (giới hạn số lần sửa <=3)
[ ] loop detection works (phát hiện vòng lặp hoạt động tốt)
[ ] checkpoints written (ghi được các điểm khôi phục)
[ ] crash resume works (khôi phục sau sự cố hoạt động tốt)
[ ] completed tasks not rerun (các tác vụ đã hoàn thành không bị chạy lại)
[ ] traceability matrix generated (sinh được ma trận truy vết)
[ ] requirement review generated (sinh được báo cáo đánh giá yêu cầu)
[ ] runtime verified (đã xác minh thời gian chạy)
[ ] final working project retained (lưu giữ được dự án hoàn chỉnh hoạt động tốt cuối cùng)
```
---
## Cổng 4 — Tài liệu hướng dẫn (Documentation)
Tệp README bắt buộc phải trình bày tài liệu về:
```text
quickstart (hướng dẫn bắt đầu nhanh)
builder new
builder resume
builder logs
builder bench --quick
architecture (kiến trúc hệ thống)
evidence principle (nguyên tắc dựa trên bằng chứng)
failure handling (cơ chế xử lý lỗi)
checkpoint recovery (khôi phục từ điểm lưu trạng thái)
```
Bao gồm một sơ đồ kiến trúc dạng ký tự ASCII.
Tạo thư mục mẫu:
```text
examples/todo_run/
├── spec.json
├── tasks.json
├── verification.json
└── review.json
```
---
## Cổng 5 — Bộ kiểm thử đầy đủ (Full Test Suite)
Chạy lệnh:
```bash
pytest -q
builder bench --quick
```
Cả hai lệnh đều bắt buộc phải vượt qua (pass).
---
## Kiểm toán các tính năng bị cấm trong V1 (V1 Forbidden-Feature Audit)
Khẳng định (assert) rằng bản triển khai KHÔNG chứa mã chức năng cho các mục:
```text
docker/
web_ui/
parallel workers
parallel DAG scheduler
Playwright
Selenium
PostgreSQL backend
web research
```
Bản giữ chỗ xác minh trình duyệt (browser verification stub) được phép tồn tại.
---
# ĐỊNH NGHĨA HOÀN THÀNH CUỐI CÙNG (FINAL DEFINITION OF DONE)
Phiên bản V1 chỉ hoàn thành khi và chỉ khi:
```text
M1 PASS
M2 PASS
M3 PASS
M4 PASS
M5 PASS
M6 PASS
M7 PASS
M8 PASS
M9 PASS
M10 PASS
M11 PASS
M12 PASS
```
Mọi bản sửa lỗi (bug fix) BẮT BUỘC phải đi kèm một bài kiểm thử hồi quy (regression test).
Mọi mô-đun mới BẮT BUỘC phải có bài kiểm thử.
Giữ cho các tệp mã nguồn luôn gọn gàng, tập trung.
Ưu tiên:
```text
<400 lines per file (dưới 400 dòng mỗi tệp)
```
Tách nhỏ các tệp lớn hơn khi hợp lý.
Tuyệt đối không lưu trữ:
```text
API keys
secrets
absolute host-specific paths (đường dẫn tuyệt đối phụ thuộc máy chủ)
```
Không bao giờ xóa các điểm khôi phục lịch sử (historical checkpoints) để che giấu lỗi thất bại.
---
# ĐỊNH DẠNG BÁO CÁO TÓM TẮT CUỐI LẦN CHẠY (FINAL RUN SUMMARY FORMAT)
Ở cuối mỗi lần chạy, hãy in ra bản tóm tắt ở cấp độ từng yêu cầu.
Ví dụ:
```text
REQ-001
Implemented: YES
Tested: YES
Runtime: YES
Evidence:
- src/main.py
- pytest -q → exit_code 0
Status: PASS
REQ-002
Implemented: YES
Tested: NO
Runtime: NO
Missing:
- successful verification result
Status: FAIL
```
Trạng thái cuối cùng (Final status):
```text
PASS
```
chỉ đạt được khi mọi yêu cầu đều có trạng thái PASS được hậu thuẫn bởi bằng chứng thực tế.
Tuyệt đối không bao giờ sử dụng:
```text
"AI says finished"
```
làm bằng chứng.
---
# LỆNH THỰC THI (EXECUTION COMMAND)
Hãy bắt đầu ngay bây giờ.
Triển khai:
```text
M1
```
Chạy các bài kiểm thử của nó.
Nếu đạt (xanh), hãy tiếp tục sang:
```text
M2
```
Tiếp tục tuần tự cho đến M12.
Không đặt câu hỏi.
Không dừng lại ở các cột mốc trung gian.
Không bỏ qua các cổng kiểm duyệt bị lỗi.
Không tuyên bố hoàn thành V1 cho đến khi Cổng Kiểm Duyệt Cuối Cùng (Final Gate) báo xanh hoàn toàn.