welder

一个本地优先、可观测、文件即真相（file-first）的 AI Agent 系统。

welder 的目标不是“黑盒聊天”，而是让 Agent 的记忆、上下文治理、工具调用、会话持久化都能被审计、被编辑、被复现。

1. 项目定位

• 本地优先：核心状态落盘到本地文件，便于长期维护与迁移。
• 透明可控：系统提示词组装、上下文裁剪、工具调用、记忆更新都可追踪。
• OpenClaw 风格：工作区模板、上下文注入顺序、记忆策略与 OpenClaw 理念对齐。
• 工程化可用：提供 API、前端、测试、启动脚本、状态检查与上下文诊断端点。

2. 当前技术亮点

• 分层上下文管理流水线：Bootstrap 限流、Token 预算预检、工具结果生命周期修剪、预压缩写回、压缩重试，最后输出上下文状态。
• 文件即真相 + 索引加速：workspace/MEMORY.md 与 workspace/memory/logs/*.md 作为唯一事实源；SQLite 仅做检索加速，可随时重建。
• 严格路径安全模型：后端文件 API 仅允许 workspace/skills/sessions 根路径，阻断路径穿越与越权读写。
• 可观测上下文事件：每次上下文治理都会落地事件，支持 /api/context/{session_id}/status|events|compact 诊断与人工干预。
• SSE 流式协议稳定化：前后端统一 content/tool_call/complete/error 事件模型，并做工具调用去重，减少 UI 重复噪声。
• 记忆抽取可解释：长期记忆抽取使用 LLM 严格 JSON 输出，不使用正则启发式“猜测记忆”。

3. 技术栈

• 后端：Python 3.10+、FastAPI、LangChain 1.x、langchain-openai。
• 前端：Next.js 14（App Router）、React 18、TypeScript、Tailwind、Monaco Editor。
• 持久化：本地 Markdown/JSON + SQLite（索引层）。
• 运行方式：uv 管理 Python 依赖，npm 管理前端依赖。

4. 快速开始

4.1 环境要求

• Python 3.10+
• Node.js 18+
• npm
• uv

4.2 安装

./install.sh

或手动执行：

uv sync
cd frontend && npm install && cd ..
cp backend/.env.example backend/.env

至少配置：

OPENAI_API_KEY=your-api-key
OPENAI_API_BASE=https://api.openai.com/v1

4.3 启动

一键启动：

./start.sh

手动启动：

uv run uvicorn backend.app:app --reload --port 8002
cd frontend && npm run dev

4.4 访问地址

• 前端：http://localhost:3000
• 后端：http://localhost:8002
• API 文档：http://localhost:8002/docs

5. 目录结构（核心）

welder/
├── backend/
│   ├── app.py                    # FastAPI 入口
│   ├── agent/                    # Agent 运行管理（含 SSE）
│   ├── context/                  # 上下文治理流水线
│   ├── memory/                   # 记忆与检索引擎代码
│   ├── tools/                    # 核心工具（terminal/read_file/memory_search...）
│   ├── workspace/                # 运行时工作区与记忆文件
│   │   ├── MEMORY.md             # 长期记忆（事实源）
│   │   └── memory/logs/*.md      # 每日日志（事实源）
│   ├── sessions/                 # 会话 JSON 与上下文状态事件
│   └── .env.example
├── frontend/
│   └── src/
│       ├── app/                  # 页面入口
│       ├── components/           # Chat/Sidebar/Editor
│       └── lib/api.ts            # SSE + HTTP API 客户端
├── docs/
│   └── TECH_ARCHITECTURE.md      # 详实技术架构文档
├── QUICKSTART.md
├── pyproject.toml
└── README.md

6. 核心 API（节选）

• POST /api/chat：聊天（支持 SSE 流式）。
• GET /api/files / POST /api/files：受限文件读写。
• GET /api/sessions / GET /api/sessions/{id}：会话查询。
• GET /api/context/{id}/status：上下文状态。
• GET /api/context/{id}/events：上下文事件。
• POST /api/context/{id}/compact：手动触发压缩。
• GET /api/health：健康检查。

7. 测试与校验

后端：

cd backend && pytest -q

前端类型检查：

cd frontend && npx tsc --noEmit

8. 架构文档

详见：docs/TECH_ARCHITECTURE.md

该文档包含：

• 系统分层与调用链
• 上下文治理细节
• 记忆持久化与检索机制
• 工具系统与安全边界
• 前端流式展示模型
• 技术亮点与演进建议