convez.ai
AgenteDesenvolvimento WebAvançado
hongxinfeiyang

Y Claude Code — Agent de Programação com CLI e VS Code

hongxinfeiyang/y-claude-code

Agent IA para programação com CLI, VS Code e sandbox Docker

Ver no GitHub
InicialPluginScore · de 0 a 100

Sistema de Agent IA extensível que funciona como assistente de codificação em modo CLI terminal e plugin VS Code. Oferece roteamento de intenção, loop de agente robusto com 23 ferramentas internas, suporte a múltiplos provedores LLM (Anthropic, OpenAI, DeepSeek) e execução em sandbox Docker para isolamento de comandos.

Instalação

$npx convez-ai hongxinfeiyang/y-claude-code

1 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

Estrelas
0
Forks
0
Acompanhando
0
Saúde
28%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Assistência inteligente em refatoração e análise de código via terminal
  • Integração de IA no editor VS Code com execução de ferramentas aprovadas pelo usuário
  • Prototipagem e experimentação com diferentes modelos LLM em projetos
  • Isolamento seguro de execução de scripts Bash em sandbox Docker
  • Arquitetura de referência para entender padrões de AI Agents

Veredito

Implementação de alto nível para aprender arquitetura de AI Agents com TypeScript. Funcional para fins educacionais e prototipagem; produção exige melhorias em UX do CLI/VS Code e estabilidade. Excelente referência técnica com suporte a múltiplos provedores LLM e permissões granulares.

README

A tradução para o português deste README ainda está na fila.

Y Claude Code

AI 编程助手工具集 — 终端 CLI 与 VS Code IDE 插件双形态,可扩展的 AI Agent 系统

定位说明:Y Claude Code 是一个比较高质量的参考实现和实验平台,核心目标是帮助开发者深入理解 Claude Code 的底层原理与 AI Agent 架构。当前功能可以跑通全部核心流程,完全胜任学习用途;但如果用于生产环境,部分模块需要二次升级和稳定性加固,如:终端 CLI 与 VS Code IDE的交互比较简陋,很有必要二次升级。

架构

用户输入 → IntentRouter(意图路由) → Agent Loop(编排层, 775 行) → LLM Provider → 工具执行 → 输出
                │                       │
          内置命令/直接工具    Permission / Hook / Memory / Session
                │                       │
          22 个内置命令          子模块: PlanModeManager / LLMCallManager
                                    │    ToolExecutor / MiddlewarePipeline
       ┌────────────────────────────┼────────────────────────────┐
       │                            │                            │
  CLI 终端渲染               Observability            VS Code Webview
  (ANSI Markdown,       (Transcript / Metrics      (工具审批 Accept/Reject,
   spinner, writeLine,       / Tracing)              工具调用参数展示)
   空白行压缩)

模块

包说明
@y-claude-code/coreAgent Loop、23 个内置工具、LLM 适配、权限、上下文摘要、可观测性、中间件管道
@y-claude-code/clireadline 交互、ANSI Markdown、权限记忆、22 个命令、环境诊断
@y-claude-code/sandboxDocker 沙箱 — 命令隔离执行、安全策略、降级支持
@y-claude-code/mcpMCP 协议 — JSON-RPC 客户端 + Tool 适配器
@y-claude-code/vscodeVS Code 插件 — 内联补全、Webview 面板、流式 Agent Loop

技术栈

TypeScript 5.x strict + Node.js 20+ + pnpm workspace + readline + Anthropic SDK + OpenAI SDK + DeepSeek + Docker (沙箱) + vitest

快速开始

环境要求

  • Node.js >= 20
  • pnpm >= 8
  • Docker(可选,用于沙箱隔离执行 Bash 命令)

安装与运行

pnpm install
pnpm build
pnpm --filter @y-claude-code/cli dev

初次配置

首次启动自动进入 LLM 配置向导。配置文件采用多级合并(后者覆盖前者,嵌套对象深度合并):

优先级路径说明
1(最高)命令行参数--model、--provider 等
2环境变量ANTHROPIC_API_KEY、OPENAI_API_KEY 等
3.y-claude/settings.local.json项目级本地覆盖,不入版本管理
4.y-claude/settings.json项目级共享配置,团队共享
5(最低)~/.y-claude-code/config.json用户全局配置

用户全局配置 (~/.y-claude-code/config.json):

{
    "provider": "anthropic",
    "providers": {
        "anthropic": { "apiKey": "sk-ant-xxx" },
        "openai": { "apiKey": "sk-xxx", "baseURL": "https://api.openai.com/v1" }
    },
    "model": "claude-sonnet-4-6"
}

项目级配置 (.y-claude/settings.json),适合提交到仓库供团队共享:

{
    "model": "claude-opus-4-7",
    "permissions": {
        "defaultMode": "ask",
        "rules": [
            { "toolPattern": "Bash(npm test:*)", "action": "allow", "scope": "project" }
        ]
    }
}

本地覆盖 (.y-claude/settings.local.json),适合个人调试,应加入 .gitignore:

{
    "provider": "openai",
    "providers": {
        "openai": { "apiKey": "sk-local-xxx", "baseURL": "https://localhost:8080/v1" }
    }
}

或仅设置环境变量(适合 CI / 快速体验):

export ANTHROPIC_API_KEY="sk-ant-xxx"

使用

工具执行权限

Agent 执行 Bash/Write/Edit 等操作前需要终端确认:

按键行为有效期
y允许本次,记忆此具体操作(同命令基名/同文件路径)当前 session
n拒绝—
a本会话全允许此类操作(如所有 Bash)当前 session

工具调用展示具体参数, 如 ⚙ 读取文件 src/app.ts 执行中...、⚙ 执行命令 npm test 执行中...。

示例对话

> 帮我分析当前项目的代码结构
> 读取 src/app.ts
> 搜索 useState
> 执行 npm test

命令

对话与帮助:

命令说明
/help 或 /h显示所有可用命令
/clear 或 /cls清空终端屏幕
/exit 或 /q退出程序
/fast切换快速模式

模型与配置:

命令说明
/model <name>切换模型
/config查看/修改配置
/thinking切换 Thinking 内容展示

上下文与记忆:

命令说明
/compact手动触发上下文压缩
/context查看上下文使用情况
/memory管理持久记忆
/remember快速保存记忆

任务与状态:

命令说明
/tasks查看当前任务列表
/stats查看会话统计
/statusline配置状态栏

项目操作:

命令说明
/init初始化项目 CLAUDE.md
/review代码审查
/skills列出可用 Skill
/add-dir添加工作目录

诊断与调试:

命令说明
/doctor环境诊断
/hooks查看 Hook 配置
/pr-comments查看 PR 评论
/tmuxtmux 会话管理

项目结构

packages/
├── core/src/
│   ├── types/        # 消息、工具、Agent、配置、会话
│   ├── agent/        # ReAct 主循环 + PlanMode/LLMCall/ToolExec/中间件/压缩 + error-recovery
│   ├── router/       # 意图识别 + 分发
│   ├── llm/          # Anthropic / OpenAI Provider + Token 计数
│   ├── tools/        # 23 个内置工具 + 注册中心
│   ├── context/      # 上下文构建 + 渐进式 LLM 摘要 + 窗口监控
│   ├── permission/   # 权限检查 + 规则持久化
│   ├── session/      # 会话管理 + 文件存储
│   ├── skills/       # Markdown 技能加载(frontmatter + 多级优先级)
│   ├── hooks/        # 生命周期事件钩子
│   ├── memory/       # 用户/项目记忆(user/feedback/project/reference)
│   ├── observability/# JSONL Transcript + Metrics + Span Tracing
│   ├── config/       # cosmiconfig 多级配置加载(4 级合并)
│   └── utils/        # Logger / Cron / Security / AutoUpdate / Telemetry / Tmux
├── cli/src/
│   ├── commands/     # 22 个斜杠命令注册与处理
│   └── utils/        # 输入处理 / 启动器 / 终端渲染(ANSI Markdown) / 环境诊断
├── sandbox/src/      # Docker 容器管理 + 安全策略 + ISandbox 接口
├── mcp/src/          # JSON-RPC 客户端 + Tool 适配器
└── vscode/src/       # Extension + Webview Panel + 内联补全

测试

类别文件数用例数
core31460
cli373
vscode341
sandbox132
mcp225
合计40631

设计文档

文档说明
01-系统架构架构分层、数据流、模块依赖、安全模型、错误恢复
02-技术详设类型体系、Agent Loop、工具系统、LLM 适配、上下文
03-功能详设23 个工具、22 个命令、Plan Mode、Hook、Memory、Cron
04-用户手册安装、配置、命令参考、权限、Skill、tmux、FAQ
05-开发手册环境搭建、项目结构、添加工具/Provider、调试、发布
06-测试手册测试策略、覆盖率目标、CI 流水线、检查清单
07-功能差距与 Claude Code 差距对比、已/待实现事项
08-01-代码质量修复8 个代码质量问题的分析与修复
08-02-架构重构7 个架构问题的分析与修复
08-03-架构优化补充services 迁移、LLMCallManager、ToolExecutor
08-04-代码集成修复中间件集成、状态枚举、DRY 消除、AbortSignal

与 Claude Code 对比

维度y-claude-codeClaude Code
开源开源闭源(免费使用)
LLM ProviderAnthropic + OpenAI + DeepSeek 三后端仅 Anthropic
交互形态终端 CLI + VS Code 插件终端 CLI + VS Code / JetBrains 插件
沙箱执行Docker 容器隔离原生系统执行
工具数量23 个内置工具20+ 内置工具
权限控制五级权限(default → session → project → user → global)四级权限
配置层级5 级合并(CLI > 环境变量 > local > project > user)4 级合并
Plan ModeEnterPlanMode / ExitPlanMode原生支持
子代理4 种类型 + worktree 隔离原生支持
MCP 协议客户端 + Tool 适配器原生支持
定时任务Cron 调度 + ScheduleWakeup原生支持
可观测性JSONL Transcript + Metrics + Tracing原生支持
自动更新npm registry 检查原生支持
安全防护Prompt Injection + SSRF + 命令注入 + 输出脱敏原生内置
中间件5 个生命周期钩子 (beforeLLMCall / afterLLMCall / beforeToolExecution / afterToolExecution / afterRound)无
架构设计5 个子模块拆分 (PlanModeManager / LLMCallManager / ToolExecutor / MiddlewarePipeline / ContextCompactor)—

详细功能差距见 07-功能差距与待办事项

待优化

类别问题影响
IDE 支持仅 VS Code,无 JetBrains / Cursor 插件用户覆盖面受限
LLM ProviderAnthropic + OpenAI + DeepSeek,未接入 Ollama / 本地模型等无法使用本地部署或部分国产模型
沙箱仅 Docker,不支持 Podman / 原生隔离无 Docker 环境时退化为直接执行
分发方式需 Node.js + pnpm 源码构建,无二进制分发安装门槛较高
会话管理CLI 单会话,不支持多会话并发多任务并行能力弱
远程能力无 remote agent,不支持 SSH / 远程执行无法管理远程开发环境
文件系统无数据库 / API 直连,仅文件操作数据处理场景受限
测试覆盖631 用例,但缺乏大型项目 E2E 验证边缘场景稳定性待观察
国际化代码注释 / 文档均为中文非中文用户上手困难
离线模式必须联网调用 LLM API无网络时完全不可用

开发

pnpm install          # 安装依赖
pnpm typecheck        # 类型检查(全部包)
pnpm test             # 运行单测(40 文件 631 用例)
pnpm build            # 构建全部包
pnpm lint             # 代码检查
pnpm format           # 代码格式化

效果图

CLI

CLI 启动与对话CLI 工具调用与权限
CLI 代码编辑CLI 上下文管理
CLI 任务管理CLI 诊断与帮助
CLI 配置管理CLI 会话统计

VS Code 插件

VS Code 插件界面

Ver o original no GitHub

Bom para

Relacionados