Lite Code Agent
chuhezhe0807/lite-code-agent
Agent ReAct em TypeScript com sandbox nativo e controle de permissões
Ver no GitHubUm agente de código leve construído com LangGraph e TypeScript, inspirado no Claude Code, para aprender desenvolvimento de agentes. Executa em terminal com leitura/escrita de arquivos locais, execução de comandos em sandbox restrito e sistema de autorização em camadas.
Instalação
npx convez-ai chuhezhe0807/lite-code-agent1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Aprender padrões de desenvolvimento de agentes autônomos
- Automatizar tarefas de desenvolvimento local com segurança
- Prototipagem de assistentes de código com LangGraph
Veredito

Excelente projeto didático que implementa de verdade as peças de um agent (ReAct loop, tools, permissões, sandbox). A sandbox por mecanismos do SO é pragmática; recomendado para quem quer aprender arquitetura de agents, mas não para produção crítica sem avaliar riscos de segurança.
README
A tradução para o português deste README ainda está na fila.
Lite Code Agent
一个用于学习 Agent 应用开发的轻量级 code agent,参考 Claude Code 的核心交互模式, 用 LangGraph + TypeScript 实现。它在终端里与你对话,能读写本地文件、在受限沙箱中 执行命令和构建脚本,所有敏感操作都经过分级授权。
⚠️ 隔离强度:沙箱基于操作系统自带机制(macOS Seatbelt / Linux bubblewrap / Windows 进程组)+ 工作目录白名单 + 超时 + 进程树终止 + 环境变量清洗实现,强于纯
child_process,但仍不等同于容器/VM 级强隔离,不保证完全对抗恶意代码。缺少原生机制的 平台会自动降级为child_process+ 白名单 + 超时。详见下方「沙箱隔离」。
截图



特性
- 🔁 LangGraph 主循环:
StateGraph编排「思考 → 调用工具 → 观察 → 继续」的 ReAct 循环。 - 🧰 工具集:
read_file(分页)、list_dir、grep/glob(只读搜索)、write_file、edit_file(diff 局部编辑)、validate_file(多语言编译/语法校验)、run_command(沙箱执行)、update_todos(任务清单)。 - 🔐 分级授权 + 持久化:read 免询问;write/execute 需授权;规则按
工具名(参数模式)匹配, 支持「始终允许/拒绝」并写入.litecode/settings.local.json(参考 Claude Code)。 - 🖥️ Ink 终端 UI:回复按 Markdown 渲染富文本、块状渲染(已完成内容沉淀进终端 scrollback)、
思考动画、todo 实时勾选(最多 3 条)、方向键选择授权、中文输入法光标跟随、
Esc中断。 - 🧱 受限沙箱:命令锁定工作目录、超时强杀、可被
Esc中断(AbortSignal贯穿)。 - 🔌 可切换 Provider:默认 Anthropic(支持
apiKey/authTokenBearer /baseURL/model), 预留 OpenAI / Ollama 扩展点。 - 📊 可选 Langfuse 监控:配置即开,不配置不影响运行。
安装
需要 Node ≥ 22(Ink 7 要求)。
pnpm install
配置
所有配置只来自 环境变量 / .env(单一来源,未设置则用内置默认值)。完整变量清单见 .env.example。
复制 .env.example 为 .env,填入凭证(二选一):
# 方式一:官方 Anthropic,x-api-key
ANTHROPIC_API_KEY=sk-ant-xxxx
# 方式二:代理/网关(如 LiteLLM)或 Claude Code 习惯的 Bearer 方式
ANTHROPIC_LLM_AUTH_TOKEN=sk-xxxx
ANTHROPIC_BASE_URL=https://your-proxy/ # 可选,自定义网关
# LLM_MODEL=claude-sonnet-4-6 # 可选
# WORKDIR=./examples # 可选,agent 可操作的目录
常用运行参数(均可选,默认值见下):
| 环境变量 | 说明 | 默认 |
|---|---|---|
WORKDIR | agent 可操作的目录(所有文件/命令限制在此) | 当前目录 |
COMMAND_TIMEOUT_MS | 命令执行超时(毫秒) | 30000 |
READ_FILE_MAX_LINES | read_file 默认读取行数上限 | 2000 |
COMMAND_OUTPUT_MAX_BYTES | run_command 输出字节预算 | 30720 |
MAX_ITERATIONS | 单轮提交内 agent 执行次数的绝对上限(硬兜底) | 100 |
MAX_REPEATED_ACTIONS | 死循环检测阈值:连续重复同一动作达此次数即停止 | 4 |
运行
pnpm start # = tsx src/index.ts
pnpm typecheck # tsc --noEmit
启动后进入 REPL:输入任务即可,/exit 退出。建议先把 WORKDIR 指到 examples/ 练手:
WORKDIR=./examples pnpm start
架构
┌──────────────────────── CLI (Ink) ────────────────────────┐
│ app.tsx ←(events)── SessionController ──(submit)──► graph │
│ ▲ blocks / todos / auth / thinking │ │
└───┼───────────────────────────────────────┼────────────────┘
│ 用户输入 / Esc / 方向键 │ stream(updates)
│ ▼
┌────────── StateGraph ──────────┐
│ agent 节点 ⇄ tools 节点(条件边) │
└───────────────┬───────────────────┘
│ 执行前授权拦截
┌───────────────────┼───────────────────┐
│ PermissionManager │ 9 个工具 │
│ (allow/deny 匹配) │ read/write/exec │
└────────┬───────────┴─────────┬──────────┘
.litecode/settings.local.json 沙箱 (child_process)
主循环(src/agent/graph.ts):状态含 messages(累积)、iterations(迭代保护)、
todos。agent 节点调用 LLM;若产生 tool_calls 则进 tools 节点,否则结束。tools 节点
对每个调用先过授权再执行,结果以 ToolMessage 回传,然后回到 agent 成环。
授权(src/permissions/):read 默认放行;write/execute 先匹配规则
(deny 优先 → allow 免询问 → 都不命中则提示)。提示用方向键在
本次允许 / 本次拒绝 / 始终允许 / 始终拒绝 间选择,「始终」会把本次调用泛化成规则
(如 run_command(npx tsc *))写入 .litecode/settings.local.json。
沙箱(src/sandbox/):detect 按平台选隔离后端,exec 锁定 cwd,超时 SIGKILL,
支持外部 AbortSignal(Esc 中断时杀子进程)。
UI 桥接(src/cli/controller.ts):SessionController 既是 AuthPrompter
(用 promise-bridge 把授权请求推给 UI 等按键),又用 graph.stream 把每步转成渲染块事件,
并跨轮累积对话历史。
沙箱隔离
run_command 在受限沙箱里执行。启动时按平台自动探测最强可用后端,缺失则优雅降级为 none
并打印告警(启动概览会显示「沙箱后端 / 隔离等级」)。
| 平台 | 后端 | 隔离能力 |
|---|---|---|
| macOS | seatbelt(sandbox-exec) | 文件写仅限白名单、可切断网络 |
| Linux | bwrap(bubblewrap) | mount/pid namespace,只读根 + 白名单可写、可切网;需 apt/dnf install bubblewrap |
| Windows | jobobject | 弱隔离:文件越界靠应用层白名单;建议在 WSL2 中运行获得 Linux 级隔离 |
| 其它/降级 | none | 仅 cwd 锁定 + 超时 + 进程树终止 + env 清洗 |
与后端无关的通用加固(各平台都生效):
- 整棵进程树终止:超时与
Esc中断时,POSIX 杀进程组、Windows 用taskkill /T, 避免npm run→node等子进程残留。 - 环境变量清洗:只把白名单内的变量(
PATH/HOME/代理变量等)传给被执行命令,ANTHROPIC_API_KEY、LANGFUSE_*等密钥不会泄漏给子进程。 - 资源限制(POSIX):按配置注入
ulimit(进程数-u/ CPU 时间-t/ 内存-v), 缺省不限制;-u为 per-user 语义。
配置(环境变量;结构化字段用逗号分隔列表 / 独立整数变量表达):
SANDBOX_BACKEND=auto # auto | none | seatbelt | bwrap | jobobject
SANDBOX_ALLOW_NETWORK=true # 默认放行:npm install 等需联网;设 false 切断网络
SANDBOX_WRITABLE_PATHS=/a,/b # cwd + tmp + 包管理器缓存之外额外可写的绝对路径(逗号分隔)
SANDBOX_ENV_PASSTHROUGH=FOO,BAR # 默认白名单之外额外透传给子进程的环境变量名(逗号分隔)
SANDBOX_MAX_PROCESSES=512 # 资源上限,缺省即不限制
SANDBOX_CPU_TIME_SECONDS=60
SANDBOX_MAX_MEMORY_BYTES=1073741824
网络默认放行的权衡:代码 agent 常需
npm install/ 拉依赖,故allowNetwork默认true。 若要在其中跑不可信代码,建议设为false切断网络,并配合seatbelt/bwrap后端。
工具一览
| 工具 | 级别 | 说明 |
|---|---|---|
read_file(path, offset?, limit?) | read | 读取文件,分页,截断标注剩余 |
list_dir(path?) | read | 列目录,目录排前,超量截断 |
grep(pattern, path?, ...) | read | 按正则搜索文件内容 |
glob(pattern, path?) | read | 按文件名模式查找文件 |
write_file(path, content) | write | 创建/覆盖文件,授权前展示摘要 |
edit_file(path, old, new) | write | 精确替换(old 须唯一),授权前展示 diff |
validate_file(path) | read | 按扩展名校验编译/语法错误(TS/JS/Python/Ruby/Go/Java/Shell/JSON/YAML),缺校验器自动跳过 |
run_command(command) | execute | 沙箱执行,超时/中断保护,头尾截断输出 |
update_todos(todos) | read | 维护任务清单,UI 实时 ○/◐/✓ |
降低 token 消耗
多轮工具调用很费 token,本项目内置几项可选优化:
- 收紧系统提示:指示模型不复述工具返回内容、不写大段解说、只给一句话级结论,减少输出 token。
- prompt caching(
PROMPT_CACHING,默认关):给系统提示加cache_control,让 Anthropic 缓存 「tools + system」这段稳定前缀,多轮命中缓存可显著省输入 token。需 LLM 端点(官方或兼容网关, 如 LiteLLM)支持cache_control,不支持则被忽略、不报错;可在响应usage的cache_read_input_tokens/cache_creation_input_tokens确认是否命中。 - 历史工具结果压缩(
HISTORY_TOOL_RESULT_MAX_BYTES,默认 8192,0=关):重发给模型时把超预算的旧工具 结果做头尾截断(产生当轮仍完整可见),削减多轮重发的输入 token。 - 对话历史自动压缩(
HISTORY_COMPACTION_MAX_BYTES,默认 61440,0=关):跨轮历史超过阈值时,提交前用 LLM 把较旧历史摘要成精简上下文、保留最近若干轮,避免长会话撑爆 context window;压缩失败回退原历史。 - 工具输出预算可调:
COMMAND_OUTPUT_MAX_BYTES/READ_FILE_MAX_LINES可调小。
概念澄清:①工具结果是下一轮的输入 token(非模型输出);②工具调用参数是模型必需的输出,省不掉; ③模型每步的解说 prose 才是可省的输出 token;④多轮里重发全部历史是输入 token 大头,prompt caching 杠杆最大。注意:UI 里的展示裁剪(
clampCount)仅影响终端显示,不会减少发给模型的 token—— 两者是不同的东西。
配置(环境变量):
PROMPT_CACHING=false
HISTORY_TOOL_RESULT_MAX_BYTES=8192
HISTORY_COMPACTION_MAX_BYTES=61440
可选:Langfuse 监控
仓库内 docker-compose.yml 可一键自托管 Langfuse:
docker compose up -d # 首次较慢,等各服务 healthy
# 浏览器打开 http://localhost:3000 注册 → 建项目 → 拿 public/secret key
把 key 填进 .env:
LANGFUSE_PUBLIC_KEY=pk-lf-xxxx
LANGFUSE_SECRET_KEY=sk-lf-xxxx
LANGFUSE_BASE_URL=http://localhost:3000
启动后每轮对话的 LLM 调用与工具执行链路会上报到 Langfuse。不配置则自动关闭,不影响运行。
目录结构
src/
index.ts 入口:装配配置/模型/工具/控制器并启动 CLI
config.ts 配置加载与校验
provider.ts LLM provider 工厂(默认 Anthropic)
agent/ LangGraph 主循环(graph:agent/tools 节点 + 状态)/ 历史压缩(compaction)
tools/ read_file / list_dir / grep / glob / write_file / edit_file / validate_file / run_command / update_todos
permissions/ 授权:settings 读写 / 规则匹配 / prompter / manager
sandbox/ 沙箱:types / detect(后端选择)/ policy / exec / backends(seatbelt·bwrap·windows·none)
security/path.ts 工作目录路径白名单校验
util/ diff 格式化 / 输出头尾截断 / glob 匹配
observability/langfuse.ts 可选 Langfuse 回调
cli/ Ink UI:app / controller / thinking / types / 输入框(promptInput·promptBuffer)/
历史(history)/ 任务清单摘要(todoSummary)/ Markdown 渲染(markdown)
examples/ 示例工作目录(练手)
docker-compose.yml 本地自托管 Langfuse
学习要点
- LangGraph
StateGraph的状态/节点/条件边如何拼出 ReAct 循环。 - 工具调用循环 + human-in-the-loop 授权如何在
tools节点内拦截。 - 用依赖注入(
AuthPrompter接口)把授权逻辑与界面解耦。 AbortSignal如何贯穿 图 → 工具 → 子进程实现中断。- Ink/React 状态驱动渲染与命令式 agent 事件流如何通过 EventEmitter 桥接。