# LoopForge

**Repository Path**: xiaorulai/agent-loom

## Basic Information

- **Project Name**: LoopForge
- **Description**: LoopForge (智能体织机)
寓意：Harness 本意是“马具/线束”，而 Loom（织布机）则是将无数根线（Prompt、Tools、Memory、API）编织成完整逻辑的机器。这个名字完美契合你“从零构建全链路”的过程，既有技术感又有工匠精神。
专注于编程的 Agent Harness
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-07
- **Last Updated**: 2026-08-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Warpcode

[![Node](https://img.shields.io/badge/node-%3E%3D22-brightgreen)](https://nodejs.org/)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-lightgrey)](#platform-support)
[![VS Code Marketplace](https://img.shields.io/badge/vscode-marketplace-blue)](https://marketplace.visualstudio.com/items?itemName=rushwola.warpcode)

> A from-scratch, local coding agent harness — no LangChain, no managed runtime. Read the source and understand how every part of a coding agent works.

**Warpcode** 是一个用 TypeScript 从零实现的本地编程智能体运行时。它不是聊天机器人，也不是对现成 agent 框架的封装，而是把 Claude Code / opencode 这类工具背后的核心机制（agent loop、tool use、权限系统、上下文管理、session、memory、skills、hooks、subagent）全部亲手实现一遍，目标是成为**可读、可改、可二次构建**的 coding agent harness 参考实现。

> **📌 主要界面：VS Code 扩展。** 日常使用推荐安装 [VS Code 扩展](https://marketplace.visualstudio.com/items?itemName=rushwola.warpcode)，在侧边栏里聊天、看 diff、审批命令、管理历史会话。CLI/TUI 仍可运行但**不再主动维护**，新功能只在 VS Code 扩展里提供。

---

## 5 分钟快速开始（VS Code 扩展）

### 1. 安装扩展

在 VS Code 里打开扩展面板（`Cmd+Shift+X` / `Ctrl+Shift+X`），搜索 **Warpcode**，点 Install；或直接访问 [Marketplace 页面](https://marketplace.visualstudio.com/items?itemName=rushwola.warpcode) 安装。

### 2. 配置 API Key

安装后：
1. 点右侧边栏的 **Warpcode** 图标打开聊天面板
2. 点右上角 **⚙️** 打开设置
3. 填入：
   - **Model** — 如 `deepseek-chat`、`gpt-4o`、你的模型名
   - **Base URL** — OpenAI 兼容的 endpoint，如 `https://api.deepseek.com/v1`
   - **API Key** — 你的服务商 API Key
4. 点 **Save**

配置保存在 `~/.warpcode/.env`，与 CLI 共用。Warpcode 使用 **OpenAI-compatible** 协议，可对接任何兼容该协议的模型服务（OpenAI、DeepSeek、Moonshot、本地 vLLM/Ollama 等）。

### 3. 开始聊天

在输入框里直接说话，按回车发送：

```
请阅读 src/main.ts，并用一句话告诉我它做了什么。
```

Agent 会请求工具权限——按提示点 Approve，它就读取并分析文件。

点标题栏的 **+ New** 新建会话、**📜** 查看历史会话、**⚙️** 改设置。`/help` 查看所有斜杠命令。

### 诊断问题

如果扩展启动失败，打开 VS Code 的 **Output** 面板，右上角选 **Warpcode** 频道查看日志。

---

## 命令行使用（不再维护，仅供参考）

### 安装与配置

```bash
npm install -g warpcode@beta
```

配置分两部分：可提交的 `warpcode.jsonc`（模型/provider/功能开关）+ `~/.warpcode/auth.json`（密钥，0600）：

```bash
warpcode config init                  # 生成 .warpcode/warpcode.jsonc
warpcode config set-key openai        # 交互式输入 key，写入 auth.json
# 在 warpcode.jsonc 里把 model 设为 "openai/gpt-4o"
```

VS Code 扩展用户直接在 Settings 页配置即可。详见 [配置参考](docs/configuration.md)。

启动：

```bash
warpcode            # 进入 TUI
warpcode session list   # 列出历史会话
warpcode doctor         # 诊断问题
```

CLI/TUI 的完整文档见 [docs/usage.md](docs/usage.md)。

> ⚠️ CLI/TUI 仍可运行，但已不再主动维护，新功能只在 VS Code 扩展中提供。


---

## 它能做什么

- **本地 agent loop**：手动实现的 tool-use 循环，流式接收模型输出
- **文件工具**：`read_file` / `list_files` / `glob` / `grep`（只读）+ `edit_file` / `write_file`
- **Bash 工具**：在 workspace 内执行命令，支持超时、输出截断、两阶段确认；危险命令（`rm -rf /`、`sudo` 等）硬拒绝
- **权限系统**：`default` / `acceptEdits` / `plan` / `bypassPermissions` / `dontAsk` 五种模式，每条命令按风险分级
- **Plan Mode**：只读规划模式，先探索再提交计划，批准后才动手
- **Session 持久化**：JSONL 会话日志，支持 `session list` / `resume` / `replay`
- **上下文管理**：自动 token 估算、按 API round 裁剪、工具结果压缩
- **Todo 任务追踪**：结构化任务列表，模型可规划和更新进度
- **Project Instructions**：自动发现并加载 `AGENTS.md`，支持父目录级联和全局配置
- **Auto-Memory**：模型提议、用户确认，写入项目本地记忆
- **Skills**：内置四个技能 + 项目级 `.warpcode/skills/`，按任务激活
- **Hooks**：生命周期扩展点（before/after tool call、file write、user turn）
- **Read-only Subagent**：并行只读子 agent，隔离上下文，只回传摘要
- **VS Code 扩展**（主要界面）：侧边栏 chat、会话历史、外观设置、bash 终端集成、文件工具一键打开（见 [vscode/README.md](vscode/README.md)，[Marketplace 安装](https://marketplace.visualstudio.com/items?itemName=rushwola.warpcode)）
- **TUI / CLI**（不再主动维护）：基于 Ink 的终端界面和命令行仍可使用，但新功能只在 VS Code 扩展里提供

## 它不是什么

- 不是一个"通用 agent 平台"——专注编码任务
- 不使用 LangChain / AutoGen / CrewAI 等 agent 框架
- 不做 OS 级沙箱（v1.1 规划中）；`bypassPermissions` 模式下不要跑不可信代码
- 不绑定特定模型服务商——任何 OpenAI-compatible endpoint 都行
- v0.17 是 beta 版本，PowerShell 支持为实验性，Windows 推荐 Git Bash 或 WSL2

## 基本用法

### TUI 操作

启动后默认进入 TUI（Ink 终端界面）：

- 直接输入消息回车发送
- `Shift+Enter` 换行
- `Shift+Tab` 循环切换权限模式
- 工具调用需要批准时按提示键确认/拒绝

### 斜杠命令

| 命令 | 作用 |
|------|------|
| `/help` | 显示帮助 |
| `/exit` | 退出 |
| `/clear` | 清空当前会话历史 |
| `/plan [text]` | 进入 Plan Mode（只读规划） |
| `/normal` | 回到默认权限模式 |
| `/mode <name>` | 切换到指定模式 |
| `/skill list` | 列出可用技能 |
| `/skill <name>` | 加载技能 |
| `/skill unload` | 卸载当前技能 |

### 权限模式

| 模式 | 行为 |
|------|------|
| `default` | 每个副作用操作都确认（安全默认） |
| `acceptEdits` | 文件编辑自动批准，bash/网络仍确认 |
| `plan` | 只读，禁止任何写操作 |
| `bypassPermissions` | 全部自动放行（**危险**） |
| `dontAsk` | 非交互，需要确认的操作自动拒绝 |

### CLI 模式

```bash
# 传统行模式（非 TUI）
npm run dev -- cli

# 会话管理
npm run dev -- session list
npm run dev -- session resume <session-id>
npm run dev -- session replay <session-id>
```

## 配置

v0.21 起配置由三部分组成，完整说明见 [配置参考](docs/configuration.md)：

- `.warpcode/warpcode.jsonc`（项目级，可提交）/ `~/.warpcode/warpcode.jsonc`（全局）：结构化主配置，用 `provider/model` 引用语法选择模型
- `~/.warpcode/auth.json`（0600，不提交）：API 密钥，用 `warpcode config set-key <id>` 写入
- `.env`：密钥兜底 + 临时环境覆盖（如 CI 用 `WARPCODE_MODEL` 切模型）

```jsonc
// .warpcode/warpcode.jsonc
{
  "$schema": "https://warpcode.dev/schemas/warpcode.json",
  "model": "openai/gpt-4o",
  "providers": { "openai": {} }   // 内置 provider 写空对象即可
}
```

```bash
warpcode config set-key openai    # 交互输入 OPENAI_API_KEY，写 auth.json
```

内置 catalog 支持 `openai` / `openrouter` / `deepseek` / `groq` / `ollama`，也可声明任意自定义 OpenAI-compatible 端点。

## 平台支持

| 平台 | Shell | 状态 | 备注 |
|------|-------|------|------|
| macOS | zsh/bash | ✅ 一等支持 | 作者主开发环境 |
| Linux | bash | ✅ 一等支持 | Ubuntu/Fedora |
| Windows | Git Bash | ✅ 支持 | **推荐**：安装 [Git for Windows](https://git-scm.com) |
| Windows | WSL2 | ✅ 支持 | 按 Linux 处理；建议把项目放在 `~/` 而非 `/mnt/c/` |
| Windows | PowerShell | ⚠️ 实验性 | 能跑简单命令，bash 语法不保证 |
| Windows | CMD | ❌ 不支持 | 请用 Git Bash 或 WSL |

可通过 `WARPCODE_SHELL` 环境变量强制指定 shell。

## 项目架构

Warpcode 采用三层架构：

```
┌──────────────────────────────────────────┐
│  交互入口 (src/entrypoints/)             │
│  TUI (Ink) / CLI (readline) / VSCode     │
│  只依赖 src/runtime/，不直接 import 内核  │
└─────────────────┬────────────────────────┘
                  ↓ createRuntime()
┌──────────────────────────────────────────┐
│  Runtime 契约层 (src/runtime/)           │
│  AgentRuntime + TypedEventEmitter       │
│  harness 对外唯一 public API             │
└─────────────────┬────────────────────────┘
                  ↓ 内部使用
┌──────────────────────────────────────────┐
│  内核 (agent/prompt/memory/tools/...)   │
└──────────────────────────────────────────┘
```

**构建产物**：

| 产物 | 目录 | 构建命令 | 发布方式 | 维护状态 |
|------|------|---------|---------|---------|
| **VS Code 扩展**（主要） | `vscode/dist/` | `npm run build:vscode` | [Marketplace](https://marketplace.visualstudio.com/items?itemName=rushwola.warpcode) | ✅ 活跃维护 |
| npm 包 `warpcode`（CLI/TUI） | 根 `dist/` | `npm run build` | `npm install -g warpcode` | ⚠️ 不再主动维护 |

两个产物共享同一份 runtime/内核代码，只是入口和打包方式不同。构建产物都不进 git（见 `.gitignore`）。新功能优先在 VS Code 扩展里提供。

详见 [docs/architecture.md](docs/architecture.md)。

## 文档

| 文档 | 内容 |
|------|------|
| [快速开始](docs/quickstart.md) | 安装、配置、第一个任务的详细步骤 |
| [配置参考](docs/configuration.md) | 所有环境变量、`.warpcode/` 目录结构 |
| [使用手册](docs/usage.md) | TUI/CLI 操作（不再维护）、斜杠命令、权限模式 |
| [VS Code 扩展发布指南](docs/vscode-publishing.md) | 如何构建、打包、发布 VS Code 扩展 |
| [安全说明](docs/security.md) | 权限模型、secret 脱敏、信任边界 |
| [FAQ](docs/faq.md) | 常见问题 |
| [故障排查](docs/troubleshooting.md) | 错误信息对照和解决方法 |
| [设计哲学](docs/philosophy.md) | 为什么从零写、不做什么 |
| [架构总览](docs/architecture.md) | 三层架构、模块职责 |
| [Roadmap](docs/roadmap.md) | 版本规划 |
| [阶段设计文档](docs/stages/) | 每个版本的设计决策记录 |

## 贡献

欢迎贡献！请先读 [CONTRIBUTING.md](CONTRIBUTING.md)——尤其注意：

- 代码注释用**中文**
- **不引入 agent 框架**（LangChain 等）
- 新功能要有测试，bug 修复要加回归测试
- 大改动先开 issue 讨论

## License

[MIT](LICENSE)