diff --git a/README.en.md b/README.en.md index 4cc803d..1fbf97d 100644 --- a/README.en.md +++ b/README.en.md @@ -1,249 +1,611 @@ -# code-terminator +
-[![Python](https://img.shields.io/badge/python-3.11%2B-blue.svg)](#) -[![LangGraph](https://img.shields.io/badge/LangGraph-enabled-7B61FF.svg)](#) -[![License](https://img.shields.io/badge/license-MIT-green.svg)](#) +Code Terminator hero -Language: [English](./README.en.md) | [简体中文](./README.zh-CN.md) +[![Typing SVG](https://readme-typing-svg.demolab.com?font=Orbitron&weight=800&size=24&duration=2200&pause=700&color=00E5FF¢er=true&vCenter=true&width=940&lines=Leader+Plans+%E2%9A%A1+Workers+Patch+%E2%9A%A1+Reviewer+Guards;Incidents+Wake+The+System+%E2%9A%A1+Agents+Fix+The+Repo;FastAPI+%2B+SSE+%2B+React+%2B+Docker+Codex+Workers)](https://git.io/typing-svg) -A minimal runnable multi-agent scaffold powered by LangGraph: +

+ 简体中文 + · + English + · + API Docs + · + Contributing +

-- `leader` main orchestrator -- concurrent `worker` sub-agents -- concurrent `reviewer` sub-agents -- role-scoped `tools` and `skills` extension interfaces -- role prompt template loader +

+ Python + LangGraph + FastAPI + React + Docker + MIT +

-## Prerequisites +

From a chat bot to an observable, resumable, event-driven software engineering runtime.

-- Python 3.11+ -- [uv](https://github.com/astral-sh/uv) +
-## Setup +--- -Choose one environment setup method and use it consistently for all Python commands. +## 🚀 Overview -### Option A: `uv venv` (project-local environment) +`code-terminator` is a multi-agent runtime for real software engineering workflows. It is not a toy chat demo. It is built around a practical engineering loop: -```bash -uv venv .venv -source .venv/bin/activate -uv sync +```text +detect problem -> plan work -> dispatch worker -> collect result -> review output -> resume when needed ``` -Optional (force uv to always use this local environment): +The project connects **LangGraph orchestration**, **FastAPI streaming APIs**, **React control console**, **Docker-isolated code workers**, **long-term memory**, **incident wakeup**, and **GitHub-native automation** into one runtime. + +--- + +## ✨ Feature Matrix + +| Module | Capability | Engineering Value | +| --- | --- | --- | +| 🧠 Leader Agent | Decomposes goals, maintains plans, calls tools | Turns one-shot chat into a stateful task machine | +| 🛠️ Worker Agent | Executes concrete code tasks | Handles implementation and repository-level work | +| 🛡️ Reviewer Agent | Reviews results and checks quality | Keeps the loop from blindly accepting generated output | +| 🌊 SSE Streaming | Streams runtime events to the web UI | Makes planning, logs, and results visible in real time | +| 🧩 Plan State Machine | Tracks pending / running / done items | Provides observable and recoverable progress | +| 🐳 Docker Codex Worker | Runs worker jobs in containers | Isolates real repository tasks from the host workspace | +| 🧬 Memory + Checkpoint | SQLite checkpoint + Chroma memory | Supports recovery, long context, and historical reuse | +| 🔔 Incident Wakeup | Converts incidents into repair work | Moves from passive chat to event-driven repair | +| 🔀 GitHub Flow | Token injection, PR fallback, automation hooks | Connects agent output with real collaboration workflows | +| ⚙️ Runtime Settings | Persists settings through UI/API | Allows runtime configuration without manual restarts | + +--- + +## 🌌 Capability Landscape + + + + + + + + + + + + + + +
+

🧠 Agentic Runtime

+

The Leader interprets goals, decomposes tasks, maintains plan items, invokes tools, and consumes runtime events. Worker and Reviewer agents complete the execution loop.

+ 		+

🌊 Observable Workflow

+

FastAPI + SSE streams conversations, plans, activity logs, and results into the React console. The runtime is designed to be watched while it works.

+
+

🐳 Isolated Code Worker

+

Worker tasks are packaged into job bundles and can run inside Docker. Inputs, outputs, stdout, stderr, and structured results are persisted for replay and debugging.

+ 		+

🔥 Incident-Driven Repair

+

The system accepts incident_new and incident_regressed events. An incident can wake the Leader, create a repair plan, and dispatch a Worker.

+
+

🧬 Memory & Resume

+

SQLite checkpoints preserve runtime state, Chroma stores long-term memory, and runtime-state keeps conversations, plans, and settings.

+ 		+

🔀 GitHub-Native Automation

+

Runtime settings can persist a GitHub token and inject it into Worker jobs as GITHUB_TOKEN / GH_TOKEN for branch, commit, and PR workflows.

+
+ +--- + +## 🏗️ Architecture + +```mermaid +flowchart TB + USER["👤 User / Developer"] --> WEB["🎛️ React + Vite Console"] + USER --> CLI["⌨️ CLI"] + + WEB --> API["⚡ FastAPI Runtime Service"] + CLI --> GRAPH["🧠 LangGraph Runtime"] + API --> GRAPH + + GRAPH --> LEADER["👑 Leader Agent"] + LEADER --> PLAN["📋 Plan State Machine"] + LEADER --> TOOLS["🧰 Tool Registry"] + LEADER --> REVIEWER["🛡️ Reviewer Agent"] + + TOOLS --> WORKER_TOOL["🚀 call_code_worker_tool"] + WORKER_TOOL --> DOCKER["🐳 Docker Codex Worker"] + DOCKER --> REPO["📦 Target Repository"] + + API --> SSE["🌊 SSE Event Stream"] + API --> SETTINGS["⚙️ Runtime Settings"] + API --> HOOK["🔔 Hook Event Bus"] + + GRAPH --> CHECKPOINT["💾 SQLite Checkpoint"] + GRAPH --> MEMORY["🧬 Chroma Long-Term Memory"] + + INCIDENT["🔥 Incident / Regression Event"] --> HOOK + HOOK --> GRAPH + + DOCKER --> RESULT["📨 Worker Result Bundle"] + RESULT --> HOOK +``` -```bash -export UV_PROJECT_ENVIRONMENT=".venv" +--- + +## 🧪 Runtime Flow + +> Open the web console, submit an engineering task, watch the Leader create a plan, let Workers execute isolated code jobs, stream progress through SSE, persist the state, and let the Reviewer inspect the output. If an incident event arrives, the same runtime can wake up and start a repair chain. + +```mermaid +sequenceDiagram + participant U as User + participant W as Web Console + participant A as FastAPI + participant G as LangGraph + participant L as Leader + participant D as Docker Worker + participant R as Reviewer + participant M as Memory + + U->>W: Submit task + W->>A: POST /api/chat/send/stream + A->>G: Start runtime graph + G->>L: Plan and dispatch + L->>D: Run isolated code task + D-->>A: Hook event result + A-->>W: Stream activity by SSE + L->>R: Review worker output + G->>M: Save checkpoint + memory + W-->>U: Final answer + visible plan ``` -### Option B: `conda` environment +--- + +## 🧰 Tech Stack + +| Layer | Stack | +| --- | --- | +| Agent Runtime | LangGraph, LangChain, OpenAI-compatible APIs | +| Backend | FastAPI, Pydantic, Uvicorn, SSE | +| Frontend | React, Vite, TypeScript | +| Worker | Docker, Codex-compatible CLI worker, isolated job bundle | +| Memory | SQLite checkpoint, Chroma long-term memory | +| Automation | GitHub token injection, hook event bus, runtime settings | +| Quality | pytest, black, isort, mypy | + +--- + +## ⚡ Quick Start + +### 1. Requirements + +- Python `3.11+` +- `uv` +- Node.js + npm +- Docker + +### 2. Install Dependencies ```bash -conda create -n code-terminator python=3.11 -y -conda activate code-terminator -pip install uv uv sync +npm install +npm --prefix web install ``` -Optional environment variables: +### 3. Configure Model Access ```bash -# Shared API endpoint for LLM and embeddings (leave empty for SDK default) -export OPENAI_BASE_URL="" - -# Embedding model used by long-term memory retrieval +export OPENAI_API_KEY="your-api-key" +export OPENAI_BASE_URL="https://your-openai-compatible-endpoint" +export DEFAULT_MODEL="gpt-4o-mini" export EMBEDDING_MODEL="text-embedding-3-small" ``` -## Run +### 4. Start Full Stack Dev -Activate your environment first: +```bash +npm run dev +``` -- Option A: `source .venv/bin/activate` -- Option B: `conda activate code-terminator` +Default endpoints: -Main command: +| Service | URL | +| --- | --- | +| Web Console | `http://127.0.0.1:5174` | +| FastAPI | `http://127.0.0.1:18000` | +| Swagger UI | `http://127.0.0.1:18000/docs` | -```bash -uv run python -m src.main --task "Build a TODO app backend" -``` +--- -## Web Dev Mode (Vite + FastAPI) +## 🖥️ Run Modes -Run from project root: +### CLI ```bash -npm install -npm --prefix web install -npm run dev +uv run python -m src.main --task "Build a TODO app backend" ``` -- Frontend: `http://127.0.0.1:5173` -- Backend: `http://127.0.0.1:8000` -- OpenAPI docs: `http://127.0.0.1:8000/docs` +Use a thread ID for recovery: -`npm run dev` invokes `scripts/dev-backend.sh`, which executes `conda activate code-terminator` before starting `uvicorn`. - -See API details in [`docs/api.md`](./docs/api.md). +```bash +uv run python -m src.main \ + --task "Build a TODO app backend" \ + --thread-id demo-001 +``` -Leader event mode examples: +Resume a previous run: ```bash -# User input event (default) -uv run python -m src.main --task "Create sprint plan and issue triage" - -# Mock subagent result event on existing thread uv run python -m src.main \ --task "resume" \ --thread-id demo-001 \ - --resume \ - --event-type subagent_result \ - --event-task-id task-abc \ - --event-status success \ - --event-role worker \ - --event-details "implementation finished" + --resume ``` -Memory-related runtime flags: +### API ```bash -uv run python -m src.main --task "Build a TODO app backend" --thread-id demo-001 +uv run uvicorn src.api.app:app --reload --host 127.0.0.1 --port 18000 ``` -Resume from latest checkpoint: +Common endpoints: -```bash -uv run python -m src.main --task "Build a TODO app backend" --thread-id demo-001 --resume -``` +| Endpoint | Description | +| --- | --- | +| `GET /api/health` | Health check | +| `GET /api/agents/status` | Agent status | +| `POST /api/chat/send` | Non-streaming task | +| `POST /api/chat/send/stream` | SSE streaming task | +| `GET /api/chat/history` | Chat history | +| `GET /api/conversations/{conversation_id}` | Conversation detail | +| `GET /api/conversations/{conversation_id}/plan` | Plan snapshot | +| `GET /api/settings/runtime` | Read runtime settings | +| `PUT /api/settings/runtime` | Persist runtime settings | + +--- + +## 🎛️ Web Console + +The web console is more than a chat box: + +- Conversation list and history recovery +- Streaming messages +- Plan panel +- Activity log +- GitHub token settings +- SSE-driven progress updates +- Persistent conversations and plan snapshots -Resume from a specific checkpoint id: +Run it with: ```bash -uv run python -m src.main --task "Build a TODO app backend" --thread-id demo-001 --resume --checkpoint-id +npm run dev ``` -## Test +`web/vite.config.ts` proxies `/api` to the backend port. The default backend port is `18000`. + +--- + +## 🐳 Docker Worker -Activate the same environment as in the Run section, then execute: +Build a worker image: ```bash -uv run pytest +docker build -t code-terminator/worker-codex -f docker/worker-codex/Dockerfile . +export CODEX_WORKER_DOCKER_IMAGE="code-terminator/worker-codex" ``` -Leader-specific regression suites: +Worker jobs are persisted as bundles: -```bash -uv run pytest tests/test_leader_event_runtime.py tests/test_leader_query_set.py +```text +.code-terminator/ + worker-jobs/ + / + leader-task.md + leader-task.json + stdout.log + stderr.log + result.json ``` -## Kimi Local Integration +Key settings: + +| Variable | Default | Description | +| --- | --- | --- | +| `CODEX_WORKER_DOCKER_IMAGE` | `mcr.microsoft.com/playwright:v1.58.2-noble` | Worker image | +| `CODEX_WORKER_TIMEOUT_SECONDS` | `1800` | Worker timeout | +| `CODEX_WORKER_CONTAINER_WORKDIR` | `/workspace` | Container workdir | +| `CODEX_WORKER_CODEX_BIN` | `codex` | Command inside container | +| `CODEX_WORKER_MODEL` | empty | Worker model override | +| `CODEX_WORKER_JOB_ROOT` | `.code-terminator/worker-jobs` | Job bundle root | +| `CODEX_WORKER_DOCKER_ARGS` | empty | Extra args for `docker run` | + +--- + +## 🔥 Incident Auto Dispatch + +The runtime can consume incident and regression events: + +1. Generate an incident fingerprint +2. Detect whether the problem is new or regressed +3. Create or update a plan item +4. Dispatch a Worker repair task +5. Receive results through hook events +6. Continue with Leader / Reviewer processing + +```mermaid +flowchart LR + LOG["Service Log / Error"] --> FP["Fingerprint"] + FP --> REG["Incident Registry"] + REG --> EVENT["Hook Event"] + EVENT --> LEADER["Leader Plan"] + LEADER --> WORKER["Worker Fix"] + WORKER --> RESULT["Result Bundle"] + RESULT --> REVIEW["Reviewer Check"] + REVIEW --> DONE["Plan Updated"] +``` + +--- + +## 🧪 Built-in Test Repository: Ecommerce Platform -This repository now includes a real local-only Kimi Docker integration case. +`ecommerce-platform/` is an independent microservice test repository used for traffic generation, fault injection, log collection, replay validation, and agent-driven repair. -It verifies: +It acts as a target environment for the main runtime: the runtime detects, plans, and dispatches work; the ecommerce platform provides services that can be loaded, broken, repaired, and regression-tested. -- the real async `call_code_worker` path -- Kimi execution inside Docker -- local file creation inside the isolated worker workspace -- structured JSON parsing from the Kimi response -- no GitHub usage and no remote repository usage +### Services -Config template: +- user service +- order service +- inventory service +- payment service +- nginx gateway +- prometheus config +- traffic simulator +- local reload scripts +- service-level tests + +### Local Startup ```bash -configs/kimi-local-integration.env.example +cd ecommerce-platform +python3 -m venv .venv +.venv/bin/pip install -r requirements.txt +bash scripts/run_local_reload_stack.sh ``` -Manual run: +Common endpoints: -```bash -set -a -source configs/kimi-local-integration.env.example -export OPENAI_BASE_URL="https://your-openai-compatible-endpoint" -export OPENAI_API_KEY="your-api-key" -set +a +| Entry | Description | +| --- | --- | +| `/` | Gateway home | +| `/monitor` | Local monitoring dashboard | +| `/api/monitor/summary` | Monitoring summary | +| `/api/monitor/stream` | SSE monitoring stream | +| `logs/ecommerce-debug.jsonl` | Unified structured runtime log | + +Stop the local stack: -uv run --python python3.12 python scripts/run_kimi_local_integration.py +```bash +bash scripts/stop_local_reload_stack.sh ``` -Optional pytest entrypoint: +--- + +## 🌊 Million-Traffic Logs & Replay + +`ecommerce-platform/` includes both online traffic simulation and offline million-scale JSONL dataset generation. + +### Online Traffic ```bash -RUN_KIMI_LOCAL_INTEGRATION=1 \ -OPENAI_BASE_URL="https://your-openai-compatible-endpoint" \ -OPENAI_API_KEY="your-api-key" \ -uv run --python python3.12 pytest -q tests/test_kimi_local_integration.py +cd ecommerce-platform +.venv/bin/python scripts/traffic_simulator.py --base-url http://127.0.0.1:58080 ``` -Detailed guide: +Locust traffic models: ```text -docs/kimi-local-integration.md +ecommerce-platform/traffic/locustfile.py +ecommerce-platform/traffic/shape.py ``` -Supporting files: +`shape.py` models a compressed daily access curve with morning, lunch, evening, and night traffic patterns. + +### Million-Scale Offline Dataset + +```bash +cd ecommerce-platform +.venv/bin/python scripts/generate_log_dataset.py \ + --output-dir logs/datasets/million-traffic-realistic \ + --gateway-records 1000000 \ + --shards 8 \ + --days 7 \ + --clean +``` + +The generated dataset includes: + +- normal traffic +- warning traffic +- error traffic +- service exceptions with traceback +- realistic `IndexError` +- realistic `KeyError` +- realistic `AttributeError` +- realistic `TypeError` + +Suggested output layout: ```text -docs/kimi-local-integration-checklist.md -docs/kimi-local-integration-troubleshooting.md -scripts/run_kimi_local_integration.sh -configs/kimi-local-integration.dashscope.env.example +ecommerce-platform/logs/datasets/million-traffic-realistic/ + manifest.json + traffic-shard-01.jsonl + traffic-shard-02.jsonl + ... + traffic-shard-08.jsonl ``` -## Memory Storage +### Replay -Memory files are stored in a local `.memory/` directory (created lazily by runtime code): +```bash +cd ecommerce-platform +.venv/bin/python scripts/replay_log.py \ + --input logs/ecommerce-debug.jsonl \ + --base-url http://127.0.0.1:58080 \ + --limit 500 +``` + +Fault switches: + +| Switch | Service | Typical Failure | Trigger | +| --- | --- | --- | --- | +| `BUG_INDEX_ERROR=true` | order | `IndexError` | `GET /api/v1/orders/user/{new_user}` | +| `BUG_ORDER_COUPON_KEY=true` | order | `KeyError` | Create order with unknown `coupon_code` | +| `BUG_RACE_CONDITION=true` | inventory | `InsufficientStockError` | High-frequency concurrent orders | +| `BUG_INVENTORY_MISSING_ROW=true` | inventory | `AttributeError` | Query broken product ID | +| `BUG_FLOAT_PRECISION=true` | payment | Money precision drift | `GET /api/v1/payments/calculate` | +| `BUG_PAYMENT_GATEWAY_KEY=true` | payment | `KeyError` | Payment calculation with coupon discount | +| `BUG_NULL_VIP=true` | user | `TypeError` | New user discount request | + +--- + +## 🧠 Memory & Recovery -- `.memory/checkpoints.sqlite` for LangGraph checkpoint persistence -- `.memory/chroma/` for long-term vector memory (ChromaDB) +```text +.memory/ + checkpoints.sqlite + chroma/ + +.code-terminator/ + runtime-state/ + conversations/ + plans/ + settings/runtime.json + hook-events/ + pending/ + processing/ + worker-jobs/ +``` + +Supported capabilities: -Long-term memory embeddings are generated via an OpenAI-compatible embeddings API, sharing the same `OPENAI_BASE_URL`. +- persistent conversation history +- persistent plan snapshots +- checkpoint recovery +- disk-backed hook events +- persisted GitHub token and runtime settings +- Chroma long-term memory -Default memory constants are centralized in `src/memory/config.py`. +--- -## Leader Plan State Machine +## ⚙️ Configuration -The leader keeps a project-management plan list with fields: +### Core Runtime -- `task_id` -- `content` -- `status` (`pending`, `in_progress`, `success`, `failed`, `rejected`) -- `details` +| Variable | Default | Description | +| --- | --- | --- | +| `OPENAI_API_KEY` | empty | API key for LLM / embeddings | +| `OPENAI_BASE_URL` | empty | OpenAI-compatible endpoint | +| `DEFAULT_MODEL` | `gpt-4o-mini` | Default chat model | +| `EMBEDDING_MODEL` | `text-embedding-3-small` | Long-term memory embedding model | +| `MEMORY_DATA_DIR` | `.memory` | Memory root | +| `CHECKPOINT_DB_NAME` | `checkpoints.sqlite` | Checkpoint SQLite filename | +| `CHROMA_DIR_NAME` | `chroma` | Chroma directory name | -State transitions are validated in `src/app/plan_state_machine.py`. Invalid transitions are blocked and recorded into graph `errors`. +### API / Runtime State -Minimal event-driven flow: +| Variable | Default | Description | +| --- | --- | --- | +| `CODE_TERMINATOR_API_STATE_ROOT` | `.code-terminator/runtime-state` | API runtime state root | +| `CODE_TERMINATOR_HOOK_ROOT` | `.code-terminator/hook-events` | Hook event root | +| `CODE_TERMINATOR_HOOK_STALE_SECONDS` | `30` | Stale processing event threshold | -1. user event creates or updates plan items -2. leader generates dispatch queue for worker/reviewer CLI agents -3. mock subagent event updates task state (`pending -> in_progress -> success/failed/rejected`) -4. snapshots are persisted in core memory and checkpointed state +--- -## Project Structure +## 📦 Project Layout ```text src/ - app/ - state.py # shared state contracts - graph.py # langgraph workflow - agents/ - leader.py # task decomposition - worker.py # concurrent worker execution - reviewer.py # concurrent reviewer execution - prompts/ - loader.py # role template rendering - templates/ - leader.md - worker.md - reviewer.md - tools/ - base.py # tool protocol + mock tools - registry.py # role-scoped tool registry - skills/ - base.py # skill protocol + noop skill - registry.py # role-scoped skill registry - main.py # CLI entrypoint -tests/ - test_graph_smoke.py + agents/ # leader / worker / reviewer + api/ # FastAPI routes, models, runtime service + app/ # graph, state, hook bus, incident, gitops, plan state machine + datagov/ # bootstrap package + memory/ # checkpoint + long-term memory + observability/ # logging helpers + prompts/ # role templates + skills/ # role-scoped skills + tools/ # tool registry + worker dispatch tools +web/ # React + Vite console +docker/worker-codex/ # Worker Dockerfile +configs/ # OpenAI-compatible / Kimi integration examples +scripts/ # dev / smoke / worker / regression scripts +docs/ # API / logging / smoke evidence +ecommerce-platform/ # microservice test repository and traffic lab +``` + +Key files: + +| File | Description | +| --- | --- | +| `src/app/graph.py` | Main LangGraph runtime | +| `src/agents/leader.py` | Leader Agent | +| `src/tools/call_code_worker_tool.py` | Worker dispatch tool | +| `src/api/services/runtime_service.py` | API runtime service | +| `src/app/hook_bus.py` | Hook event bus | +| `src/app/incidents.py` | Incident handling entry | +| `src/app/auto_review_merge.py` | Auto review / merge logic | +| `web/src/App.tsx` | Web console entry | + +--- + +## ✅ Verification + +```bash +uv run pytest +``` + +Full tests: + +```bash +uv run pytest tests/ +``` + +Format and type checks: + +```bash +uv run black --check src/datagov tests/bootstrap +uv run isort --check-only src/datagov tests/bootstrap +uv run mypy --strict src ``` + +Important runtime tests: + +```bash +uv run pytest \ + tests/test_api_integration.py \ + tests/test_hook_pump.py \ + tests/test_worker_runtime_config.py \ + tests/test_incident_auto_dispatch.py \ + tests/test_auto_review_merge.py +``` + +--- + +## 📚 Related Docs + +- [API Reference](./docs/api.md) +- [Logging Guide](./docs/logging.md) +- [Auto Review Server Checklist](./docs/auto-review-server-checklist.md) +- [Kimi Local Integration](./docs/kimi-local-integration.md) +- [Environment Status](./ENV_STATUS.md) +- [Contributing](./CONTRIBUTING.md) + +--- + +
+ +footer + +Code Terminator · Agentic software engineering runtime for real repositories. + +
diff --git a/README.md b/README.md index bfa5a2e..6e7c5fe 100644 --- a/README.md +++ b/README.md @@ -1,60 +1,252 @@ -# code-terminator +
-[![Python](https://img.shields.io/badge/Python-3.11%2B-3776AB?logo=python&logoColor=white)](#) -[![LangGraph](https://img.shields.io/badge/LangGraph-Orchestrated-0E9F6E)](#) -[![FastAPI](https://img.shields.io/badge/FastAPI-API%20%2B%20SSE-009688?logo=fastapi&logoColor=white)](#) -[![React](https://img.shields.io/badge/React-Vite%20Console-61DAFB?logo=react&logoColor=222)](#) -[![Docker Worker](https://img.shields.io/badge/Docker-Codex%20Worker-2496ED?logo=docker&logoColor=white)](#) -[![License](https://img.shields.io/badge/License-MIT-2EA043)](#) +Code Terminator hero -Language / 语言: [English](./README.en.md) | [简体中文](./README.zh-CN.md) +[![Typing SVG](https://readme-typing-svg.demolab.com?font=Orbitron&weight=800&size=24&duration=2200&pause=700&color=00E5FF¢er=true&vCenter=true&width=940&lines=Leader+Plans+%E2%9A%A1+Workers+Patch+%E2%9A%A1+Reviewer+Guards;Incidents+Wake+The+System+%E2%9A%A1+Agents+Fix+The+Repo;FastAPI+%2B+SSE+%2B+React+%2B+Docker+Codex+Workers)](https://git.io/typing-svg) -> 一个不只会聊天的多智能体运行时骨架。 -> 现在它已经具备了 CLI、FastAPI、SSE 流式前端、可恢复计划状态、Docker 中的真实 Codex Worker、以及本地持久化运行时设置。 +

+ English + · + 简体中文 + · + API Docs + · + Contributing +

-## Overview +

+ Python + LangGraph + FastAPI + React + Docker + MIT +

-`code-terminator` 是一个基于 LangGraph 的多智能体实验场，当前重点已经不再只是“最小骨架”，而是围绕下面这条真实链路打通： +

+ CLI ready + Web console + Checkpoint + Memory + GitHub PR + Incident dispatch +

-- `leader` 负责规划、拆解任务、维护计划项和 React trace -- `worker` / `reviewer` 负责并发执行与反馈 -- Web 控制台通过 FastAPI + SSE 实时展示对话、计划和活动日志 -- Docker Worker 可以在隔离工作区里调用 Codex 处理真实仓库任务 -- Memory、hook event、runtime settings 都会落盘，支持恢复和追踪 +

把“聊天机器人”升级成会规划、会派工、会修复、会复盘的软件自治系统。

+ +
+ +--- + +## 🚀 项目定位 + +`code-terminator` 是一个面向真实软件工程任务的多智能体运行时。它不是只会回答问题的玩具项目，而是围绕“发现问题 -> 规划任务 -> 派发 Worker -> 回传结果 -> Reviewer 审查 -> 可恢复运行”这条链路搭建的工程系统。 + +它把 **LangGraph 编排**、**FastAPI 流式服务**、**React 控制台**、**Docker 隔离 Worker**、**长期记忆**、**事件唤醒** 和 **GitHub 自动化协作** 串在一起，让 AI Agent 更像一个可以接入研发流程的自动化队友。 + +--- + +## ✨ 高能特性墙 + +| 模块 | 能力 | 工程价值 | +| --- | --- | --- | +| 🧠 Leader Agent | 拆解任务、维护计划、调度工具 | 从单轮问答升级为可推进的任务状态机 | +| 🛠️ Worker Agent | 执行具体代码任务 | 将复杂需求拆给独立执行单元处理 | +| 🛡️ Reviewer Agent | 反馈、审查、守住质量 | 让多智能体形成闭环，而不是盲目生成 | +| 🌊 SSE Streaming | Web 端实时流式输出 | 用户能看到任务推进过程、事件和计划变化 | +| 🧩 Plan State Machine | 计划项 pending / running / done | 支持可观测、可恢复、可追踪的任务运行 | +| 🐳 Docker Codex Worker | 容器化执行任务 | 隔离执行真实仓库任务，减少污染本地环境 | +| 🧬 Memory + Checkpoint | SQLite checkpoint + Chroma memory | 支持断点恢复、长期上下文和历史复用 | +| 🔔 Incident Wakeup | 事故事件触发自动修复链路 | 从日志/异常到自动派工修复，接近线上运维场景 | +| 🔀 GitHub Flow | Token 注入、PR fallback、自动化协作 | 连接真实研发协作流程 | +| ⚙️ Runtime Settings | UI/API 持久化运行时配置 | 可动态保存运行参数，不必每次重启重配 | + +--- + +## 🌌 核心能力全景 + + + + + + + + + + + + + + +
+

🧠 Agentic Runtime

+

Leader 负责理解目标、拆解任务、维护计划、调用工具和吸收事件；Worker 负责执行任务；Reviewer 负责审查输出。整个运行时不是简单 prompt chaining，而是一个可恢复的图式状态系统。

+ 		+

🌊 Observable Workflow

+

FastAPI + SSE 将对话、计划、事件、日志和结果流式推到 Web 控制台。每次任务推进都有状态可见，适合接入研发控制台、任务看板或自动化平台。

+
+

🐳 Isolated Code Worker

+

Worker 任务会被打包成 job bundle，并可在 Docker 中执行。输入、输出、stdout、stderr、结构化结果都会落盘，方便审计、复现和问题定位。

+ 		+

🔥 Incident-Driven Repair

+

系统支持 incident_new / incident_regressed 事件。异常进入 hook bus 后，Leader 可以生成修复计划并派发 Worker，让系统具备事件驱动的自动修复雏形。

+
+

🧬 Memory & Resume

+

SQLite checkpoint 保存运行状态，Chroma 承载长期记忆，runtime-state 保存会话、计划和设置。长任务可以中断后恢复，不必从零开始。

+ 		+

🔀 GitHub-Native Automation

+

运行时可保存 GitHub Token，并注入到 Worker 的 GITHUB_TOKEN / GH_TOKEN。后续可以连接分支、提交、PR、审查和自动合并等真实协作链路。

+
+ +--- + +## 🏗️ 系统架构 ```mermaid -flowchart LR - U[User / CLI / Web] --> API[FastAPI RuntimeService] - API --> LG[LangGraph Runtime] - LG --> LEADER[Leader] - LEADER --> PLAN[Plan State Machine] - LEADER --> WTOOL[call_code_worker_tool] - LEADER --> REVIEW[Reviewer] - WTOOL --> DKR[Docker Codex Worker] - API --> SSE[Streaming SSE] - API --> HOOK[Hook Event Bus] - LG --> MEM[Checkpoint + Chroma Memory] - API --> CFG[Runtime Settings] -``` - -## What's New - -相比早期版本，仓库里现在已经新增了这些值得写进 README 的内容： - -- Web 控制台：React + Vite，支持会话列表、流式回复、计划面板、活动日志、GitHub Token 设置 -- FastAPI Runtime：支持 `/api/chat/send`、`/api/chat/send/stream`、历史记录、计划快照、运行时设置 -- Hook 持久化总线：后台线程可通过磁盘事件把子代理结果安全回传给 API runtime -- Docker Worker 执行链路：Leader 可以把任务打包成 job bundle，在独立容器中执行 Codex -- 运行时设置持久化：支持从 UI/API 保存 `github_token`，Worker 会自动注入到 `GITHUB_TOKEN` / `GH_TOKEN` -- 可恢复运行时：支持 `thread_id`、checkpoint 恢复、事件注入 -- Python bootstrap：`uv` 管理依赖，`src/datagov/` 作为独立可导入包保留 -- 环境烟雾验证：`ENV_STATUS.md` 和 `docs/smoke/` 记录了环境检查结果 -- 附带参考目录：`cliagent/`、`opms-collab/` 作为实验/集成目录已纳入仓库 - -## Quick Start +flowchart TB + USER["👤 User / Judge / Developer"] --> WEB["🎛️ React + Vite Console"] + USER --> CLI["⌨️ CLI"] + + WEB --> API["⚡ FastAPI Runtime Service"] + CLI --> GRAPH["🧠 LangGraph Runtime"] + API --> GRAPH + + GRAPH --> LEADER["👑 Leader Agent"] + LEADER --> PLAN["📋 Plan State Machine"] + LEADER --> TOOLS["🧰 Tool Registry"] + LEADER --> REVIEWER["🛡️ Reviewer Agent"] + + TOOLS --> WORKER_TOOL["🚀 call_code_worker_tool"] + WORKER_TOOL --> DOCKER["🐳 Docker Codex Worker"] + DOCKER --> REPO["📦 Target Repository"] + + API --> SSE["🌊 SSE Event Stream"] + API --> SETTINGS["⚙️ Runtime Settings"] + API --> HOOK["🔔 Hook Event Bus"] + + GRAPH --> CHECKPOINT["💾 SQLite Checkpoint"] + GRAPH --> MEMORY["🧬 Chroma Long-Term Memory"] + + INCIDENT["🔥 Incident / Regression Event"] --> HOOK + HOOK --> GRAPH + + DOCKER --> RESULT["📨 Worker Result Bundle"] + RESULT --> HOOK +``` + +--- + +## 🧪 一句话运行路线 + +> 打开 Web 控制台，输入一个工程任务；Leader 生成计划，Worker 被派发到 Docker 中执行，过程通过 SSE 实时显示，任务状态落盘，结果回传后 Reviewer 进行审查；如果系统收到 incident 事件，还能自动唤醒修复链路。 + +```mermaid +sequenceDiagram + participant U as User + participant W as Web Console + participant A as FastAPI + participant G as LangGraph + participant L as Leader + participant D as Docker Worker + participant R as Reviewer + participant M as Memory + + U->>W: Submit task + W->>A: POST /api/chat/send/stream + A->>G: Start runtime graph + G->>L: Plan and dispatch + L->>D: Run isolated code task + D-->>A: Hook event result + A-->>W: Stream activity by SSE + L->>R: Review worker output + G->>M: Save checkpoint + memory + W-->>U: Final answer + visible plan +``` + +--- + +## 🧰 技术栈 + +| Layer | Stack | +| --- | --- | +| Agent Runtime | LangGraph, LangChain, OpenAI-compatible APIs | +| Backend | FastAPI, Pydantic, Uvicorn, SSE | +| Frontend | React, Vite, TypeScript | +| Worker | Docker, Codex-compatible CLI worker, isolated job bundle | +| Memory | SQLite checkpoint, Chroma long-term memory | +| Automation | GitHub token injection, hook event bus, runtime settings | +| Quality | pytest, black, isort, mypy | + +--- + +## 🧱 运行时组件 + +### Leader + +Leader 是系统的调度核心，主要负责： + +- 将用户目标转成可执行计划 +- 维护 `PlanItem` 状态 +- 读取 conversation turns 和 conversation summary +- 调用工具注册表里的工具 +- 根据 hook event 更新任务状态 +- 针对 incident 事件生成修复任务 +- 将 Worker / Reviewer 的输出合并成最终结果 + +### Worker + +Worker 面向具体执行任务，可以处理： + +- 代码修改任务 +- 文件分析任务 +- 测试修复任务 +- 回归验证任务 +- 目标仓库内的局部实现 + +当启用 Docker Worker 时，任务会被写入 `.code-terminator/worker-jobs/`，并在隔离容器里执行。 + +### Reviewer + +Reviewer 负责从工程质量角度检查结果，包括： + +- 是否满足原始目标 +- 是否有明显回归风险 +- 是否缺少验证 +- 是否需要继续派发任务 +- 是否可以生成最终回复 + +### Hook Bus + +Hook bus 是后端和异步 Worker 之间的事件桥。它通过磁盘目录传递事件，避免长任务和 API 请求强绑定。 + +典型事件： + +| Event | 说明 | +| --- | --- | +| `subagent_result` | Worker / Reviewer 返回结果 | +| `incident_new` | 新异常被发现 | +| `incident_regressed` | 已修复问题再次出现 | + +### Runtime Service + +FastAPI Runtime Service 封装了： + +- 会话创建 +- 流式对话 +- 历史读取 +- 计划快照读取 +- runtime settings 持久化 +- hook event pump +- agent status 查询 + +--- + +## ⚡ 快速启动 ### 1. 准备环境 +需要： + - Python `3.11+` - `uv` - Node.js + npm @@ -70,8 +262,6 @@ npm --prefix web install ### 3. 配置模型访问 -推荐先准备一个 `.env`，至少补齐 LLM 和 embedding 所需变量： - ```bash export OPENAI_API_KEY="your-api-key" export OPENAI_BASE_URL="https://your-openai-compatible-endpoint" @@ -79,150 +269,227 @@ export DEFAULT_MODEL="gpt-4o-mini" export EMBEDDING_MODEL="text-embedding-3-small" ``` -如果你只跑本地 UI 壳子、不触发真实模型调用，这些变量可以稍后再配。 +### 4. 启动全栈开发环境 -## Run Modes +```bash +npm run dev +``` -### CLI +默认地址： + +| 服务 | 地址 | +| --- | --- | +| Web Console | `http://127.0.0.1:5174` | +| FastAPI | `http://127.0.0.1:18000` | +| Swagger UI | `http://127.0.0.1:18000/docs` | + +--- + +## 🖥️ 运行方式 + +### CLI 模式 ```bash uv run python -m src.main --task "Build a TODO app backend" ``` -带线程与恢复： +带线程 ID，方便后续恢复： ```bash uv run python -m src.main \ --task "Build a TODO app backend" \ --thread-id demo-001 - -uv run python -m src.main \ - --task "resume" \ - --thread-id demo-001 \ - --resume ``` -注入子代理结果事件： +恢复一次历史运行： ```bash uv run python -m src.main \ --task "resume" \ --thread-id demo-001 \ - --resume \ - --event-type subagent_result \ - --event-task-id task-abc \ - --event-status completed \ - --event-role worker \ - --event-details "implementation finished" + --resume ``` -### API +### API 模式 ```bash uv run uvicorn src.api.app:app --reload --host 127.0.0.1 --port 18000 ``` -启动后可访问： +常用接口： + +| Endpoint | 说明 | +| --- | --- | +| `GET /api/health` | 健康检查 | +| `GET /api/agents/status` | Agent 状态 | +| `POST /api/chat/send` | 普通对话任务 | +| `POST /api/chat/send/stream` | SSE 流式任务 | +| `GET /api/chat/history` | 历史记录 | +| `GET /api/conversations/{conversation_id}` | 会话详情 | +| `GET /api/conversations/{conversation_id}/plan` | 计划快照 | +| `GET /api/settings/runtime` | 读取运行时配置 | +| `PUT /api/settings/runtime` | 保存运行时配置 | -- API: `http://127.0.0.1:18000/api` -- Swagger UI: `http://127.0.0.1:18000/docs` +--- -### Full Stack Dev +## 🎛️ Web Console + +Web 控制台不仅是一个聊天框，它更像一个轻量的 Agent 运行面板： + +- 左侧可以维护会话列表 +- 中间展示流式对话结果 +- 右侧展示计划项和任务状态 +- Activity Log 记录运行事件 +- Settings 可以保存 GitHub Token +- 后端通过 SSE 推送任务进度 +- 页面刷新后仍可读取历史会话和计划快照 + +推荐本地开发时直接运行： ```bash npm run dev ``` -这个命令会同时启动： - -- 前端 Vite：`http://127.0.0.1:5174` -- 后端 FastAPI：`http://127.0.0.1:18000` +`web/vite.config.ts` 会将 `/api` 代理到后端端口，默认后端端口是 `18000`。 -`web/vite.config.ts` 会把 `/api` 代理到 `BACKEND_PORT`，默认就是 `18000`。 +--- -## Real Docker Worker +## 🐳 Docker Worker -如果你希望 `leader` 真正把任务发给 Docker 中的 CLI Worker，建议先准备一个稳定的 Worker 镜像： +如果要让 Leader 真正把任务派发给容器里的 Worker： ```bash docker build -t code-terminator/worker-codex -f docker/worker-codex/Dockerfile . export CODEX_WORKER_DOCKER_IMAGE="code-terminator/worker-codex" ``` -如果你没有系统级 Docker daemon，也可以在工作区里启动独立 daemon： +Worker 执行时会生成 job bundle： -```bash -./scripts/start_workspace_docker.sh -export DOCKER_HOST="unix://$PWD/.docker/docker.sock" +```text +.code-terminator/ + worker-jobs/ + / + leader-task.md + leader-task.json + stdout.log + stderr.log + result.json ``` -Worker 执行时会： +这个设计的好处是：每一次 Agent 执行都有可追踪证据，方便审计、复盘、回放和定位失败原因。 -1. 在 `.code-terminator/worker-jobs/` 下生成任务 bundle -2. 写入 `leader-task.md` 和 `leader-task.json` -3. 启动 Docker 容器 -4. 把结果、stdout、stderr、内部日志都落盘 +### Worker 关键配置 -### Kimi Local Integration Case - -仓库现在附带一个真实的本地集成用例，专门验证： +| 变量 | 默认值 | 说明 | +| --- | --- | --- | +| `CODEX_WORKER_DOCKER_IMAGE` | `mcr.microsoft.com/playwright:v1.58.2-noble` | Worker 镜像 | +| `CODEX_WORKER_TIMEOUT_SECONDS` | `1800` | 单次 Worker 超时 | +| `CODEX_WORKER_CONTAINER_WORKDIR` | `/workspace` | 容器内工作目录 | +| `CODEX_WORKER_CODEX_BIN` | `codex` | 容器内执行命令 | +| `CODEX_WORKER_MODEL` | 空 | 指定 Worker 使用的模型 | +| `CODEX_WORKER_JOB_ROOT` | `.code-terminator/worker-jobs` | Worker job bundle 根目录 | +| `CODEX_WORKER_DOCKER_ARGS` | 空 | 额外传给 `docker run` 的参数 | -- `call_code_worker` 真实异步链路 -- Docker 内启动 Kimi -- 在隔离工作区写本地文件 -- hook 回传 `structured_output` -- 全程不触发 GitHub 或远端仓库操作 +### Kimi / OpenAI-Compatible Worker -样例配置文件： +项目也保留了 Kimi 本地集成相关配置，适合验证 OpenAI-compatible endpoint、容器执行和 hook 回传链路： -```bash +```text configs/kimi-local-integration.env.example +configs/kimi-local-integration.dashscope.env.example +docs/kimi-local-integration.md +docs/kimi-local-integration-checklist.md +docs/kimi-local-integration-troubleshooting.md ``` -手动运行： +运行脚本： ```bash -set -a -source configs/kimi-local-integration.env.example -export OPENAI_BASE_URL="https://your-openai-compatible-endpoint" -export OPENAI_API_KEY="your-api-key" -set +a - uv run --python python3.12 python scripts/run_kimi_local_integration.py ``` -如果你要把它作为真实 pytest 用例运行，需要显式打开： +--- -```bash -RUN_KIMI_LOCAL_INTEGRATION=1 \ -OPENAI_BASE_URL="https://your-openai-compatible-endpoint" \ -OPENAI_API_KEY="your-api-key" \ -uv run --python python3.12 pytest -q tests/test_kimi_local_integration.py -``` +## 🔥 Incident Auto Dispatch -详细说明见： +项目内置了 incident / regression 事件链路。系统收到异常事件后，可以： -```text -docs/kimi-local-integration.md +1. 生成 incident fingerprint +2. 判断是新问题还是回归问题 +3. 创建或更新计划项 +4. 自动派发 Worker 修复 +5. 通过 hook 事件回传结果 +6. 让 Leader / Reviewer 继续处理 + +这让项目从“被动问答”变成“事件驱动的软件修复系统”。 + +### Incident Payload 关注字段 + +| 字段 | 说明 | +| --- | --- | +| `fingerprint` | 异常指纹，用于去重和识别回归 | +| `service` | 出问题的服务名 | +| `exception_type` | 异常类型 | +| `traceback` | 完整堆栈 | +| `trace_id` | 请求链路追踪 ID | +| `path` | 请求路径 | +| `method` | 请求方法 | +| `error_message` | 错误信息 | +| `occurrence_count` | 出现次数 | + +### Incident 修复闭环 + +```mermaid +flowchart LR + LOG["Service Log / Error"] --> FP["Fingerprint"] + FP --> REG["Incident Registry"] + REG --> EVENT["Hook Event"] + EVENT --> LEADER["Leader Plan"] + LEADER --> WORKER["Worker Fix"] + WORKER --> RESULT["Result Bundle"] + RESULT --> REVIEW["Reviewer Check"] + REVIEW --> DONE["Plan Updated"] ``` -辅助文件： +--- + +## 🧠 Memory & Recovery ```text -docs/kimi-local-integration-checklist.md -docs/kimi-local-integration-troubleshooting.md -scripts/run_kimi_local_integration.sh -configs/kimi-local-integration.dashscope.env.example +.memory/ + checkpoints.sqlite + chroma/ + +.code-terminator/ + runtime-state/ + conversations/ + plans/ + settings/runtime.json + hook-events/ + pending/ + processing/ + worker-jobs/ ``` -## Configuration +支持能力： + +- 会话历史持久化 +- 计划快照持久化 +- checkpoint 恢复 +- hook event 落盘 +- GitHub token 等运行时配置保存 +- Chroma 长期记忆 + +--- + +## ⚙️ 配置速查 ### Core Runtime | 变量 | 默认值 | 说明 | | --- | --- | --- | | `OPENAI_API_KEY` | 空 | LLM / embedding 使用的 API Key | -| `OPENAI_BASE_URL` | 空 | OpenAI 兼容接口地址 | +| `OPENAI_BASE_URL` | 空 | OpenAI-compatible endpoint | | `DEFAULT_MODEL` | `gpt-4o-mini` | 默认对话模型 | | `EMBEDDING_MODEL` | `text-embedding-3-small` | 长期记忆 embedding 模型 | | `MEMORY_DATA_DIR` | `.memory` | memory 根目录 | @@ -237,18 +504,6 @@ configs/kimi-local-integration.dashscope.env.example | `CODE_TERMINATOR_HOOK_ROOT` | `.code-terminator/hook-events` | hook 事件目录 | | `CODE_TERMINATOR_HOOK_STALE_SECONDS` | `30` | processing 事件回收阈值，最小 5 秒 | -运行时设置文件默认位置： - -```text -.code-terminator/runtime-state/settings/runtime.json -``` - -当前持久化字段只有一个： - -- `github_token` - -它可以从 Web UI 或 `PUT /api/settings/runtime` 写入，随后会自动注入 Worker 的 `GITHUB_TOKEN` / `GH_TOKEN`。 - ### Leader Tuning | 变量 | 默认值 | 说明 | @@ -258,166 +513,292 @@ configs/kimi-local-integration.dashscope.env.example | `LEADER_ACTIVITY_LOG_LIMIT` | `60` | 活动日志最大保留条数 | | `LEADER_LLM_TIMEOUT_SECONDS` | `120` | Leader 模型调用超时 | -### Worker Runtime - -常用配置： +### Logging | 变量 | 默认值 | 说明 | | --- | --- | --- | -| `CODEX_WORKER_DOCKER_IMAGE` | `mcr.microsoft.com/playwright:v1.58.2-noble` | Worker 镜像 | -| `CODEX_WORKER_TIMEOUT_SECONDS` | `1800` | 单次 Worker 超时 | -| `CODEX_WORKER_CONTAINER_WORKDIR` | `/workspace` | 容器内工作目录 | -| `CODEX_WORKER_CODEX_BIN` | `codex` | 容器内 Codex 命令 | -| `CODEX_WORKER_MODEL` | 空 | 指定 Worker 使用的模型 | -| `CODEX_WORKER_JOB_ROOT` | `.code-terminator/worker-jobs` | Worker job bundle 根目录 | -| `CODEX_WORKER_HOST_NODE_ROOT` | 自动探测 | 挂载宿主机 Node/Codex 根目录 | -| `CODEX_WORKER_CONTAINER_NODE_ROOT` | `/opt/host-node` | 容器内挂载 Node 根目录 | -| `CODEX_WORKER_DOCKER_ARGS` | 空 | 额外透传给 `docker run` 的参数 | +| `APP_LOG_LEVEL` | `INFO` | 日志等级 | +| `APP_LOG_FILE` | `1` | 是否写入文件日志 | -Kimi 兼容别名： +日志默认写入： -| 变量 | 默认值 | 说明 | -| --- | --- | --- | -| `KIMI_WORKER_DOCKER_IMAGE` | 空 | 优先于 `CODEX_WORKER_DOCKER_IMAGE` | -| `KIMI_WORKER_BIN` | `kimi` | 优先于 `CODEX_WORKER_CODEX_BIN` | +```text +artifacts/logs/.log +``` -代理与网络相关的高级项： +--- -- `CODEX_WORKER_PASSTHROUGH_PROXY` -- `CODEX_WORKER_GIT_PROXY` -- `CODEX_WORKER_GIT_HTTP_PROXY` -- `CODEX_WORKER_GIT_HTTPS_PROXY` -- `CODEX_WORKER_TOOL_PROXY` -- `CODEX_WORKER_TOOL_HTTP_PROXY` -- `CODEX_WORKER_TOOL_HTTPS_PROXY` -- `CODEX_WORKER_TOOL_ALL_PROXY` -- `CODEX_WORKER_TOOL_NO_PROXY` +## 🧭 适用场景 -当前实现会把 Git 代理和通用工具代理分开处理；若代理指向 `127.0.0.1` / `localhost`，Linux 下会自动切到 `--network host` 或改写为 `host.docker.internal`。 +| 场景 | 可以怎么用 | +| --- | --- | +| 自动代码任务拆解 | 将一个大需求拆成多个 PlanItem，并逐步推进 | +| 仓库级修复 | Worker 在隔离环境中分析、修改和验证目标仓库 | +| 事故自动响应 | 接入日志事件，触发 incident_new / incident_regressed | +| 研发控制台 | 用 Web UI 查看会话、计划、日志和运行状态 | +| 长任务恢复 | 使用 thread_id 和 checkpoint 让任务断点续跑 | +| 自动审查 | Reviewer 检查 Worker 输出并决定是否继续修正 | +| GitHub 自动协作 | 将 Worker 的结果连接到分支、提交和 PR 流程 | -### Logging +--- -| 变量 | 默认值 | 说明 | -| --- | --- | --- | -| `APP_LOG_LEVEL` | `INFO` | 日志等级 | -| `APP_LOG_FILE` | `1` | 是否写入文件日志 | +## 🧪 内置测试仓库：Ecommerce Platform + +仓库中包含 `ecommerce-platform/`，它是一个独立的电商微服务测试仓库，用来承载真实流量、故障注入、日志采集、回放验证和 Agent 自动修复链路。 + +这个目录不是普通示例代码，而是系统的目标靶场：主运行时负责发现、规划和派工，`ecommerce-platform/` 负责提供可被压测、可被打坏、可被修复、可被回归验证的真实服务环境。 + +### 服务组成 + +- user service +- order service +- inventory service +- payment service +- nginx gateway +- prometheus config +- traffic simulator +- local reload scripts +- service-level tests -日志文件默认写到： +### 可以验证的工程能力 + +- incident 触发 +- service bug 定位 +- Worker 修复 +- 回归测试 +- 蓝绿切换脚本 +- 本地监控页面 +- JSONL 结构化日志采集 +- trace_id 串联 gateway 和 service 记录 +- traceback 驱动的问题定位 +- 真实请求回放 +- 百万级离线流量数据集生成 + +### 本地启动测试仓库 + +```bash +cd ecommerce-platform +python3 -m venv .venv +.venv/bin/pip install -r requirements.txt +bash scripts/run_local_reload_stack.sh +``` + +启动后会运行本地网关和多个服务。如果默认端口被占用，脚本会自动选择可用端口，并写入： ```text -artifacts/logs/.log +ecommerce-platform/.runtime/local-stack/ports.env ``` -## Web Console +常用入口： -当前前端不只是一个聊天框，还包括： +| 入口 | 说明 | +| --- | --- | +| `/` | 网关首页 | +| `/monitor` | 本地监控大屏 | +| `/api/monitor/summary` | 监控摘要 | +| `/api/monitor/stream` | SSE 实时监控流 | +| `logs/ecommerce-debug.jsonl` | 统一结构化运行日志 | -- 会话列表和历史恢复 -- SSE 流式消息展示 -- 计划项面板 -- Activity Log 面板 -- GitHub Token 保存和本地持久化 +停止本地测试仓库： -相关接口： +```bash +bash scripts/stop_local_reload_stack.sh +``` -- `GET /api/health` -- `GET /api/agents/status` -- `POST /api/chat/send` -- `POST /api/chat/send/stream` -- `GET /api/chat/history` -- `GET /api/conversations/{conversation_id}` -- `GET /api/conversations/{conversation_id}/plan` -- `GET /api/settings/runtime` -- `PUT /api/settings/runtime` +--- -## Useful Scripts +## 🌊 百万流量与日志回放 -```bash -# OpenAI 兼容接口连通性检查 -uv run python scripts/check_connectivity.py +`ecommerce-platform/` 内置了两类流量能力：在线流量模拟和离线百万级数据集生成。 -# 调用 Anthropic 兼容接口 -uv run python scripts/call_anthropic_api.py +### 在线持续流量 -# 20 条真实任务顺序回归 -uv run python scripts/run_20_queries_real.py --run-tag local-real +持续请求本地网关，模拟用户浏览库存、创建订单、查询订单、计算支付金额等行为： -# 20 条任务并发回归 -uv run python scripts/run_20_queries_concurrent.py --run-tag local-fast +```bash +cd ecommerce-platform +.venv/bin/python scripts/traffic_simulator.py --base-url http://127.0.0.1:58080 +``` + +Locust 版本的流量模型位于： + +```text +ecommerce-platform/traffic/locustfile.py +ecommerce-platform/traffic/shape.py ``` -## Verification +其中 `shape.py` 实现了压缩的一天访问曲线，包含早高峰、午间峰值、晚高峰和夜间低谷。它可以让系统在更接近真实业务节奏的负载下产生日志。 -基础安装与 bootstrap smoke： +### 百万级离线日志数据集 + +如果需要大规模样本，可以直接生成百万级 JSONL 日志数据集： ```bash -uv run black --check src/datagov tests/bootstrap -uv run isort --check-only src/datagov tests/bootstrap -uv run mypy --strict src -uv run pytest +cd ecommerce-platform +.venv/bin/python scripts/generate_log_dataset.py \ + --output-dir logs/datasets/million-traffic-realistic \ + --gateway-records 1000000 \ + --shards 8 \ + --days 7 \ + --clean ``` -如果你要显式跑当前主项目测试，而不只依赖 `pyproject.toml` 里的默认 smoke 范围，建议直接指定路径： +生成结果包含： -```bash -uv run pytest tests/ +- 正常访问流量 +- warning 流量 +- error 流量 +- 带 traceback 的服务异常 +- 与真实故障路径一致的 `IndexError` +- 与真实故障路径一致的 `KeyError` +- 与真实故障路径一致的 `AttributeError` +- 与真实故障路径一致的 `TypeError` + +推荐目录结构： + +```text +ecommerce-platform/logs/datasets/million-traffic-realistic/ + manifest.json + traffic-shard-01.jsonl + traffic-shard-02.jsonl + ... + traffic-shard-08.jsonl ``` -针对新增运行时能力，优先关注这些测试： +`manifest.json` 会记录总量、分片、时间范围和异常分布。`traffic-shard-*.jsonl` 则保存原始结构化流量记录。 + +### 日志回放 + +历史日志可以重新打回本地网关，用于复现问题或验证修复效果： ```bash -uv run pytest \ - tests/test_api_integration.py \ - tests/test_hook_pump.py \ - tests/test_main_runtime.py \ - tests/test_worker_runtime_config.py \ - tests/test_list_plan_tool.py +cd ecommerce-platform +.venv/bin/python scripts/replay_log.py \ + --input logs/ecommerce-debug.jsonl \ + --base-url http://127.0.0.1:58080 \ + --limit 500 ``` -## Project Layout +回放输出默认写入： + +```text +ecommerce-platform/logs/replay-results.jsonl +``` + +### 预埋故障类型 + +测试仓库内置多种可打开的故障开关，方便构造稳定的 traceback： + +| 开关 | 服务 | 典型异常 | 触发方式 | +| --- | --- | --- | --- | +| `BUG_INDEX_ERROR=true` | order | `IndexError` | `GET /api/v1/orders/user/{new_user}` | +| `BUG_ORDER_COUPON_KEY=true` | order | `KeyError` | 使用未知 `coupon_code` 创建订单 | +| `BUG_RACE_CONDITION=true` | inventory | `InsufficientStockError` | 高频并发下单 | +| `BUG_INVENTORY_MISSING_ROW=true` | inventory | `AttributeError` | 查询损坏商品 ID | +| `BUG_FLOAT_PRECISION=true` | payment | 金额精度偏差 | `GET /api/v1/payments/calculate` | +| `BUG_PAYMENT_GATEWAY_KEY=true` | payment | `KeyError` | 使用 coupon discount 计算支付 | +| `BUG_NULL_VIP=true` | user | `TypeError` | 新用户请求 discount | + +这些故障可以和主运行时的 incident 链路连接，形成： + +```mermaid +flowchart LR + TRAFFIC["百万流量 / 在线请求"] --> LOG["JSONL Logs"] + LOG --> INCIDENT["Incident Fingerprint"] + INCIDENT --> RUNTIME["Code Terminator Runtime"] + RUNTIME --> WORKER["Docker Worker Fix"] + WORKER --> TEST["Regression Test"] + TEST --> REPLAY["Replay Traffic"] +``` + +--- + +## 📦 项目结构 ```text src/ agents/ # leader / worker / reviewer api/ # FastAPI routes, models, runtime service - app/ # graph, state, hook bus, collaboration, plan state machine + app/ # graph, state, hook bus, incident, gitops, plan state machine datagov/ # bootstrap package memory/ # checkpoint + long-term memory + observability/ # logging helpers prompts/ # role templates skills/ # role-scoped skills tools/ # tool registry + worker dispatch tools -web/ # React + Vite 控制台 +web/ # React + Vite console docker/worker-codex/ # Worker Dockerfile +configs/ # OpenAI-compatible / Kimi integration examples scripts/ # dev / smoke / worker / regression scripts docs/ # API / logging / smoke evidence -cliagent/ # 额外 CLI agent 相关目录 -opms-collab/ # 协作实验目录 +ecommerce-platform/ # microservice test repository and traffic lab +``` + +### 关键文件 + +| 文件 | 说明 | +| --- | --- | +| `src/app/graph.py` | LangGraph runtime 主图 | +| `src/agents/leader.py` | Leader Agent | +| `src/tools/call_code_worker_tool.py` | Worker 派发工具 | +| `src/api/services/runtime_service.py` | API runtime service | +| `src/app/hook_bus.py` | hook event bus | +| `src/app/incidents.py` | incident 处理入口 | +| `src/app/auto_review_merge.py` | 自动 review / merge 相关逻辑 | +| `web/src/App.tsx` | Web 控制台主界面 | + +--- + +## ✅ 验证命令 + +基础 smoke： + +```bash +uv run pytest ``` -## Related Docs +更完整的测试： + +```bash +uv run pytest tests/ +``` + +格式与类型检查： + +```bash +uv run black --check src/datagov tests/bootstrap +uv run isort --check-only src/datagov tests/bootstrap +uv run mypy --strict src +``` + +重点链路测试： + +```bash +uv run pytest \ + tests/test_api_integration.py \ + tests/test_hook_pump.py \ + tests/test_worker_runtime_config.py \ + tests/test_incident_auto_dispatch.py \ + tests/test_auto_review_merge.py +``` + +--- + +## 📚 相关文档 - [API Reference](./docs/api.md) - [Logging Guide](./docs/logging.md) +- [Auto Review Server Checklist](./docs/auto-review-server-checklist.md) +- [Kimi Local Integration](./docs/kimi-local-integration.md) - [Environment Status](./ENV_STATUS.md) - [Contributing](./CONTRIBUTING.md) -
-Storage Cheatsheet +--- -```text -.memory/ - checkpoints.sqlite - chroma/ +
-.code-terminator/ - runtime-state/ - conversations/ - plans/ - settings/runtime.json - hook-events/ - pending/ - processing/ - worker-jobs/ -``` +footer + +Code Terminator · Agentic software engineering runtime for real repositories. -
+ diff --git a/README.zh-CN.md b/README.zh-CN.md index 21a203b..72b9666 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -1,472 +1,39 @@ -# code-terminator +
-[![Python](https://img.shields.io/badge/Python-3.11%2B-3776AB?logo=python&logoColor=white)](#) -[![LangGraph](https://img.shields.io/badge/LangGraph-Orchestrated-0E9F6E)](#) -[![FastAPI](https://img.shields.io/badge/FastAPI-API%20%2B%20SSE-009688?logo=fastapi&logoColor=white)](#) -[![React](https://img.shields.io/badge/React-Vite%20Console-61DAFB?logo=react&logoColor=222)](#) -[![Docker Worker](https://img.shields.io/badge/Docker-Codex%20Worker-2496ED?logo=docker&logoColor=white)](#) -[![License](https://img.shields.io/badge/License-MIT-2EA043)](#) +Code Terminator Chinese README -Language / 语言: [English](./README.en.md) | [简体中文](./README.zh-CN.md) +

+ 完整中文主页 + · + English + · + API Docs + · + Contributing +

-> 一个不只会聊天的多智能体运行时骨架。 -> 现在它已经具备了 CLI、FastAPI、SSE 流式前端、可恢复计划状态、Docker 中的真实 Codex Worker、以及本地持久化运行时设置。 +
-## Overview +# Code Terminator 简体中文文档 -`code-terminator` 是一个基于 LangGraph 的多智能体实验场，当前重点已经不再只是“最小骨架”，而是围绕下面这条真实链路打通： +完整中文 README 已放在仓库根目录： -- `leader` 负责规划、拆解任务、维护计划项和 React trace -- `worker` / `reviewer` 负责并发执行与反馈 -- Web 控制台通过 FastAPI + SSE 实时展示对话、计划和活动日志 -- Docker Worker 可以在隔离工作区里调用 Codex 处理真实仓库任务 -- Memory、hook event、runtime settings 都会落盘，支持恢复和追踪 +👉 [README.md](./README.md) -```mermaid -flowchart LR - U[User / CLI / Web] --> API[FastAPI RuntimeService] - API --> LG[LangGraph Runtime] - LG --> LEADER[Leader] - LEADER --> PLAN[Plan State Machine] - LEADER --> WTOOL[call_code_worker_tool] - LEADER --> REVIEW[Reviewer] - WTOOL --> DKR[Docker Codex Worker] - API --> SSE[Streaming SSE] - API --> HOOK[Hook Event Bus] - LG --> MEM[Checkpoint + Chroma Memory] - API --> CFG[Runtime Settings] -``` +当前中文主页包含： -## What's New +- 多智能体运行时介绍 +- Leader / Worker / Reviewer 架构 +- FastAPI + SSE + React Web Console +- Docker Codex Worker +- Incident Auto Dispatch +- Memory & Checkpoint +- 内置测试仓库 `ecommerce-platform/` +- 百万流量日志生成与回放 +- 配置速查 +- 验证命令 +- 项目结构 -相比早期版本，仓库里现在已经新增了这些值得写进 README 的内容： +英文版请查看： -- Web 控制台：React + Vite，支持会话列表、流式回复、计划面板、活动日志、GitHub Token 设置 -- FastAPI Runtime：支持 `/api/chat/send`、`/api/chat/send/stream`、历史记录、计划快照、运行时设置 -- Hook 持久化总线：后台线程可通过磁盘事件把子代理结果安全回传给 API runtime -- Docker Worker 执行链路：Leader 可以把任务打包成 job bundle，在独立容器中执行 Codex -- 运行时设置持久化：支持从 UI/API 保存 `github_token`，Worker 会自动注入到 `GITHUB_TOKEN` / `GH_TOKEN` -- 可恢复运行时：支持 `thread_id`、checkpoint 恢复、事件注入 -- Python bootstrap：`uv` 管理依赖，`src/datagov/` 作为独立可导入包保留 -- 环境烟雾验证：`ENV_STATUS.md` 和 `docs/smoke/` 记录了环境检查结果 -- 附带参考目录：`cliagent/`、`opms-collab/` 作为实验/集成目录已纳入仓库 - -## Quick Start - -### 1. 准备环境 - -- Python `3.11+` -- `uv` -- Node.js + npm -- Docker - -### 2. 安装依赖 - -```bash -uv sync -npm install -npm --prefix web install -``` - -### 3. 配置模型访问 - -推荐先准备一个 `.env`，至少补齐 LLM 和 embedding 所需变量： - -```bash -export OPENAI_API_KEY="your-api-key" -export OPENAI_BASE_URL="https://your-openai-compatible-endpoint" -export DEFAULT_MODEL="gpt-4o-mini" -export EMBEDDING_MODEL="text-embedding-3-small" -``` - -如果你只跑本地 UI 壳子、不触发真实模型调用，这些变量可以稍后再配。 - -## Run Modes - -### CLI - -```bash -uv run python -m src.main --task "Build a TODO app backend" -``` - -带线程与恢复： - -```bash -uv run python -m src.main \ - --task "Build a TODO app backend" \ - --thread-id demo-001 - -uv run python -m src.main \ - --task "resume" \ - --thread-id demo-001 \ - --resume -``` - -注入子代理结果事件： - -```bash -uv run python -m src.main \ - --task "resume" \ - --thread-id demo-001 \ - --resume \ - --event-type subagent_result \ - --event-task-id task-abc \ - --event-status completed \ - --event-role worker \ - --event-details "implementation finished" -``` - -### API - -```bash -uv run uvicorn src.api.app:app --reload --host 127.0.0.1 --port 18000 -``` - -启动后可访问： - -- API: `http://127.0.0.1:18000/api` -- Swagger UI: `http://127.0.0.1:18000/docs` - -### Full Stack Dev - -```bash -npm run dev -``` - -这个命令会同时启动： - -- 前端 Vite：`http://127.0.0.1:5174` -- 后端 FastAPI：`http://127.0.0.1:18000` - -`web/vite.config.ts` 会把 `/api` 代理到 `BACKEND_PORT`，默认就是 `18000`。 - -## Real Docker Worker - -如果你希望 `leader` 真正把任务发给 Docker 中的 Codex Worker，建议先准备一个稳定的 Worker 镜像： - -```bash -docker build -t code-terminator/worker-codex -f docker/worker-codex/Dockerfile . -export CODEX_WORKER_DOCKER_IMAGE="code-terminator/worker-codex" -``` - -如果你没有系统级 Docker daemon，也可以在工作区里启动独立 daemon： - -```bash -./scripts/start_workspace_docker.sh -export DOCKER_HOST="unix://$PWD/.docker/docker.sock" -``` - -Worker 执行时会： - -1. 在 `.code-terminator/worker-jobs/` 下生成任务 bundle -2. 写入 `leader-task.md` 和 `leader-task.json` -3. 启动 Docker 容器 -4. 把结果、stdout、stderr、内部日志都落盘 - -### Kimi 本地集成用例 - -仓库现在附带了一个真实的本地 Kimi Docker 集成用例，专门验证： - -- `call_code_worker` 的真实异步链路 -- Docker 内部能正常拉起 Kimi -- Worker 只在隔离工作区里写本地文件 -- hook 回传的 `structured_output` 可以被主流程正确解析 -- 全程不触发 GitHub 或远端仓库操作 - -配置样例： - -```bash -configs/kimi-local-integration.env.example -``` - -手动运行： - -```bash -uv run --python python3.12 python scripts/run_kimi_local_integration.py -``` - -如果你希望显式指定 API 参数： - -```bash -set -a -source configs/kimi-local-integration.env.example -export OPENAI_BASE_URL="https://your-openai-compatible-endpoint" -export OPENAI_API_KEY="your-api-key" -set +a - -uv run --python python3.12 python scripts/run_kimi_local_integration.py -``` - -如果你要把它作为真实 pytest 用例运行，需要显式开启： - -```bash -RUN_KIMI_LOCAL_INTEGRATION=1 \ -OPENAI_BASE_URL="https://your-openai-compatible-endpoint" \ -OPENAI_API_KEY="your-api-key" \ -uv run --python python3.12 pytest -q tests/test_kimi_local_integration.py -``` - -详细说明见： - -```text -docs/kimi-local-integration.md -``` - -辅助文件： - -```text -docs/kimi-local-integration-checklist.md -docs/kimi-local-integration-troubleshooting.md -scripts/run_kimi_local_integration.sh -configs/kimi-local-integration.dashscope.env.example -``` - -## Configuration - -### Core Runtime - -| 变量 | 默认值 | 说明 | -| --- | --- | --- | -| `OPENAI_API_KEY` | 空 | LLM / embedding 使用的 API Key | -| `OPENAI_BASE_URL` | 空 | OpenAI 兼容接口地址 | -| `DEFAULT_MODEL` | `gpt-4o-mini` | 默认对话模型 | -| `EMBEDDING_MODEL` | `text-embedding-3-small` | 长期记忆 embedding 模型 | -| `MEMORY_DATA_DIR` | `.memory` | memory 根目录 | -| `CHECKPOINT_DB_NAME` | `checkpoints.sqlite` | checkpoint SQLite 文件名 | -| `CHROMA_DIR_NAME` | `chroma` | Chroma 子目录名 | - -### API / Runtime State - -| 变量 | 默认值 | 说明 | -| --- | --- | --- | -| `CODE_TERMINATOR_API_STATE_ROOT` | `.code-terminator/runtime-state` | API 运行时状态根目录 | -| `CODE_TERMINATOR_HOOK_ROOT` | `.code-terminator/hook-events` | hook 事件目录 | -| `CODE_TERMINATOR_HOOK_STALE_SECONDS` | `30` | processing 事件回收阈值，最小 5 秒 | - -运行时设置文件默认位置： - -```text -.code-terminator/runtime-state/settings/runtime.json -``` - -当前持久化字段只有一个： - -- `github_token` - -它可以从 Web UI 或 `PUT /api/settings/runtime` 写入，随后会自动注入 Worker 的 `GITHUB_TOKEN` / `GH_TOKEN`。 - -同一个运行时设置里还包含： - -- `auto_review_merge_reload` - -开启后，worker 完成并返回 `pr_url` 时，系统会优先执行自动路径： - -1. 用 GitHub API 给 PR approve -2. 用 GitHub API 做 squash merge -3. 删除 worker 分支 -4. 将 incident 标记为 `approved` -5. 由 deploy watcher 拉取目标分支并触发热重载 - -如果自动路径失败，系统会回退到飞书 review 通知流程。 - -服务器侧建议补充配置： - -- `CODE_TERMINATOR_DEPLOY_BRANCH`：deploy watcher 要拉取的目标分支 -- `CODE_TERMINATOR_AGENT_ENABLE_INGEST=1`：保持日志监听开启 - -GitHub token 需要具备： - -- PR review 权限 -- PR merge 权限 -- 删除分支权限 -- 若仓库启用了分支保护，仍需满足对应保护规则 - -同一组运行时设置里还包含： - -- `auto_review_merge_reload` - -这个开关开启后，worker 完成并返回 `pr_url` 时，系统会优先走自动路径： - -1. 用 GitHub API 给 PR 执行 approve -2. 用 GitHub API 执行 squash merge -3. 删除 worker 创建的分支 -4. 将 incident 标记为 `approved` -5. 由 deploy watcher 拉取最新代码并触发热重载 - -如果自动路径失败，系统会回退到原来的飞书 review 通知流程。 - -服务器侧建议额外配置： - -- `CODE_TERMINATOR_DEPLOY_BRANCH`：热重载时要拉取的目标分支，默认优先使用当前检出分支，未能识别时回退到 `main` -- `CODE_TERMINATOR_AGENT_ENABLE_INGEST=1`：保持日志监听启用 - -注意： - -- GitHub token 需要具备 PR review / merge / delete branch 权限 -- 如果仓库启用了强制人工 review 或分支保护，自动 merge 仍可能被 GitHub 拒绝，这是仓库规则，不是本地代码问题 - -### Leader Tuning - -| 变量 | 默认值 | 说明 | -| --- | --- | --- | -| `LEADER_MAX_STEPS` | `8` | Leader 最大决策步数 | -| `LEADER_TRACE_STEPS` | `24` | React trace 保留步数 | -| `LEADER_ACTIVITY_LOG_LIMIT` | `60` | 活动日志最大保留条数 | -| `LEADER_LLM_TIMEOUT_SECONDS` | `120` | Leader 模型调用超时 | - -### Worker Runtime - -常用配置： - -| 变量 | 默认值 | 说明 | -| --- | --- | --- | -| `CODEX_WORKER_DOCKER_IMAGE` | `mcr.microsoft.com/playwright:v1.58.2-noble` | Worker 镜像 | -| `CODEX_WORKER_TIMEOUT_SECONDS` | `1800` | 单次 Worker 超时 | -| `CODEX_WORKER_CONTAINER_WORKDIR` | `/workspace` | 容器内工作目录 | -| `CODEX_WORKER_CODEX_BIN` | `codex` | 容器内 Codex 命令 | -| `CODEX_WORKER_MODEL` | 空 | 指定 Worker 使用的模型 | -| `CODEX_WORKER_JOB_ROOT` | `.code-terminator/worker-jobs` | Worker job bundle 根目录 | -| `CODEX_WORKER_HOST_NODE_ROOT` | 自动探测 | 挂载宿主机 Node/Codex 根目录 | -| `CODEX_WORKER_CONTAINER_NODE_ROOT` | `/opt/host-node` | 容器内挂载 Node 根目录 | -| `CODEX_WORKER_DOCKER_ARGS` | 空 | 额外透传给 `docker run` 的参数 | - -代理与网络相关的高级项： - -- `CODEX_WORKER_PASSTHROUGH_PROXY` -- `CODEX_WORKER_GIT_PROXY` -- `CODEX_WORKER_GIT_HTTP_PROXY` -- `CODEX_WORKER_GIT_HTTPS_PROXY` -- `CODEX_WORKER_TOOL_PROXY` -- `CODEX_WORKER_TOOL_HTTP_PROXY` -- `CODEX_WORKER_TOOL_HTTPS_PROXY` -- `CODEX_WORKER_TOOL_ALL_PROXY` -- `CODEX_WORKER_TOOL_NO_PROXY` - -当前实现会把 Git 代理和通用工具代理分开处理；若代理指向 `127.0.0.1` / `localhost`，Linux 下会自动切到 `--network host` 或改写为 `host.docker.internal`。 - -### Logging - -| 变量 | 默认值 | 说明 | -| --- | --- | --- | -| `APP_LOG_LEVEL` | `INFO` | 日志等级 | -| `APP_LOG_FILE` | `1` | 是否写入文件日志 | - -日志文件默认写到： - -```text -artifacts/logs/.log -``` - -## Web Console - -当前前端不只是一个聊天框，还包括： - -- 会话列表和历史恢复 -- SSE 流式消息展示 -- 计划项面板 -- Activity Log 面板 -- GitHub Token 保存和本地持久化 - -相关接口： - -- `GET /api/health` -- `GET /api/agents/status` -- `POST /api/chat/send` -- `POST /api/chat/send/stream` -- `GET /api/chat/history` -- `GET /api/conversations/{conversation_id}` -- `GET /api/conversations/{conversation_id}/plan` -- `GET /api/settings/runtime` -- `PUT /api/settings/runtime` - -## Useful Scripts - -```bash -# OpenAI 兼容接口连通性检查 -uv run python scripts/check_connectivity.py - -# 调用 Anthropic 兼容接口 -uv run python scripts/call_anthropic_api.py - -# 20 条真实任务顺序回归 -uv run python scripts/run_20_queries_real.py --run-tag local-real - -# 20 条任务并发回归 -uv run python scripts/run_20_queries_concurrent.py --run-tag local-fast -``` - -## Verification - -基础安装与 bootstrap smoke： - -```bash -uv run black --check src/datagov tests/bootstrap -uv run isort --check-only src/datagov tests/bootstrap -uv run mypy --strict src -uv run pytest -``` - -如果你要显式跑当前主项目测试，而不只依赖 `pyproject.toml` 里的默认 smoke 范围，建议直接指定路径： - -```bash -uv run pytest tests/ -``` - -针对新增运行时能力，优先关注这些测试： - -```bash -uv run pytest \ - tests/test_api_integration.py \ - tests/test_hook_pump.py \ - tests/test_main_runtime.py \ - tests/test_worker_runtime_config.py \ - tests/test_list_plan_tool.py -``` - -## Project Layout - -```text -src/ - agents/ # leader / worker / reviewer - api/ # FastAPI routes, models, runtime service - app/ # graph, state, hook bus, collaboration, plan state machine - datagov/ # bootstrap package - memory/ # checkpoint + long-term memory - prompts/ # role templates - skills/ # role-scoped skills - tools/ # tool registry + worker dispatch tools -web/ # React + Vite 控制台 -docker/worker-codex/ # Worker Dockerfile -scripts/ # dev / smoke / worker / regression scripts -docs/ # API / logging / smoke evidence -cliagent/ # 额外 CLI agent 相关目录 -opms-collab/ # 协作实验目录 -``` - -## Related Docs - -- [API Reference](./docs/api.md) -- [Logging Guide](./docs/logging.md) -- [Environment Status](./ENV_STATUS.md) -- [Contributing](./CONTRIBUTING.md) - -
-Storage Cheatsheet - -```text -.memory/ - checkpoints.sqlite - chroma/ - -.code-terminator/ - runtime-state/ - conversations/ - plans/ - settings/runtime.json - hook-events/ - pending/ - processing/ - worker-jobs/ -``` - -
+👉 [README.en.md](./README.en.md)