中文 | EN

一个本地优先的 AI Coding Agent，帮助你理解代码、修改项目、调用工具，并把开发任务接入终端、桌面端和自动化工作流。

NeoCode 是什么？

NeoCode 是一个运行在本地开发环境中的 AI Coding Agent。

它可以在工作区中读取项目、理解代码、调用工具、执行命令、管理会话，并通过本地 Gateway 暴露统一的 JSON-RPC / SSE / WebSocket 接口，方便终端、桌面端或第三方客户端接入。

核心闭环：

用户输入(TUI) -> 网关中继(Gateway) -> Agent推理(Runtime) -> 调用工具(Tools) -> 结果回传 -> UI展示

功能特性

• 本地优先：在你的工作区中运行，面向真实项目上下文。
• 终端交互：基于 TUI 的对话式 coding agent 体验。
• 工具调用：支持读取文件、分析项目、执行命令和调用系统工具。
• 多模型 Provider：支持 OpenAI、Gemini、ModelScope、Qiniu、OpenLL 以及自定义 Provider。
• 会话持久化：保存和恢复历史会话，减少重复沟通。
• 记忆能力：保存偏好、项目事实和跨会话上下文。
• Skills 系统：为不同任务启用专用行为和流程。
• MCP 接入：通过 MCP stdio server 扩展外部工具能力。
• Gateway 模式：通过本地 JSON-RPC / SSE / WebSocket 接口连接桌面端、脚本和第三方客户端。
• Feishu Adapter：支持 Webhook 与 SDK 长连接接入，并用单张状态卡片持续回传 run 状态。
• Local Runner：neocode runner 在本机执行工具，通过 WebSocket 主动连接云端 Gateway，无需开放入站端口。

预览

快速开始

1. 安装

macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/1024XEngineer/neo-code/main/scripts/install.sh | bash

Windows PowerShell:

irm https://raw.githubusercontent.com/1024XEngineer/neo-code/main/scripts/install.ps1 | iex

2. 从源码运行

git clone https://github.com/1024XEngineer/neo-code.git
cd neo-code
go run ./cmd/neocode

3. 配置 API Key

按你使用的 Provider 设置对应环境变量，例如：

export OPENAI_API_KEY="your_key_here"

Windows PowerShell:

$env:OPENAI_API_KEY = "your_key_here"

然后在项目目录中启动：

neocode --workdir /path/to/your/project

如果你希望使用浏览器 Web UI，可以直接运行：

neocode web

标签发布版会在缺少 web/dist 时自动使用发布包内的 web/ 源码执行 npm install 和 npm run build。这要求用户机器已安装 Node.js 和 npm；如果你使用源码仓库运行，也保留相同的自动构建行为。

4. 常用命令

/help                 查看帮助
/provider             切换 Provider
/model                切换模型
/compact              压缩当前会话上下文
/memo                 查看记忆
/remember <text>      保存记忆
/skills               查看可用 skills
/skill use <id>       启用 skill
/skill off <id>       停用 skill

5. CLI 路由速查

Provider 管理

用于新增、查看、删除自定义 provider，变更会落在 ~/.neocode/providers/。

# 新增自定义 provider（要求先设置好 --api-key-env 指向的环境变量）
neocode provider add <name> --driver <driver> --url <url> --api-key-env <env> [--discovery-endpoint <path>]

# 示例
export MOCK_KEY="sk-xxx"
neocode provider add my-openai --driver openaicompat --url https://api.openai.com/v1 --api-key-env MOCK_KEY --discovery-endpoint /v1/models

# 列出所有 provider
neocode provider ls

# 删除自定义 provider
neocode provider rm my-openai

Model 选择

用于查看当前 provider 的模型候选，并切换到指定模型。

# 列出当前 provider 可用模型（优先本地快照，必要时触发一次同步发现）
neocode model ls

# 切换当前模型（会校验模型是否属于当前 provider）
neocode model set <model-id>

# 示例
neocode model set gpt-4.1

Provider + Model 一步切换

用于切换 provider，并可通过 --model 覆盖自动选择的模型。

# 仅切换 provider（自动修正到可用模型）
neocode use <provider>

# 切换 provider 并指定模型（会做模型归属校验）
neocode use <provider> --model <model-id>

# 示例
neocode use openai --model gpt-4.1

Local Runner

在本机启动执行守护进程，主动连接云端 Gateway 接收工具执行请求。

# 启动 runner（默认连接 127.0.0.1:8080）
neocode runner

# 指定远程 Gateway 地址和 token
neocode runner --gateway-address "your-gateway.com:8080" --token-file ~/.neocode/auth.json

# 指定 Runner 名称与工作目录
neocode runner --runner-name "我的本机" --workdir /path/to/project

6. Shell 诊断代理

用于进入代理 shell、初始化 shell integration、手动触发诊断和控制自动诊断模式。

# 进入代理 shell（当前仅支持 Unix-like）
neocode shell

# 输出 shell integration 脚本（支持写法：--init <shell>）
neocode shell --init bash
neocode shell --init zsh

# 触发一次手动诊断（两种写法等价）
neocode diag
neocode diag diagnose

# 进入 IDM 交互式诊断沙盒（退出：输入 exit 或空闲态 Ctrl+C）
neocode diag -i

# 自动诊断开关与状态查询
neocode diag auto on
neocode diag auto off
neocode diag auto status

7. url scheme使用

详细指南链接： HTTP URL 唤醒使用指南（用户故事版）

# 启动本地 HTTP daemon（默认 127.0.0.1:18921）
go run ./cmd/neocode daemon serve

# 安装用户态自启动 + best-effort hosts 别名写入（127.0.0.1 neocode）
go run ./cmd/neocode daemon install

# 查看运行与安装状态
go run ./cmd/neocode daemon status

# 卸载自启动配置
go run ./cmd/neocode daemon uninstall

可点击链接示例：

http://neocode:18921/review?path=README.md
http://neocode:18921/run?prompt=写一个简单的HTTP服务器

当前支持动作：

• review：必须携带 path 参数。
• run：必须携带 prompt 参数，网关会返回 session_id 并触发终端接管链路。

会话接管启动方式：

go run ./cmd/neocode --session <session_id>

当传入 --session 时，TUI 会优先按会话历史中的 workdir 进行上下文接管；若该路径在本地失效，会保留当前工作区并显示告警。

Linux（及其他非 Windows/macOS）当前尚未接入自动弹窗终端；wake.run 会返回 not_supported，可手动执行 neocode --session <session_id> 接管。

daemon serve 不提供 --token-file，默认仅监听 127.0.0.1，并限制 Host 白名单为 neocode / localhost / 127.0.0.1。

Linux 自启动策略：优先 systemd --user，若不可用则回落到 ~/.config/autostart/neocode-daemon.desktop。

若未通过安装脚本安装（例如 go build / 裸二进制），请手动执行一次 neocode daemon install。

Gateway / MCP / Skills / Hooks

详细说明在文档内：

• Gateway 集成与协议（Reference）
• MCP 工具接入（Guide）
• Skills 使用（Guide）
• 飞书远程接入配置（Guide）
• 飞书本地 SDK 长连接（免公网，个人开发推荐）
• Hooks 使用（Guide）
• 工具与权限（Guide）
• Runtime / Provider 事件流（Repo Doc）

文档

• 官方文档站：https://neocode-docs.pages.dev/
• 快速引导（中文）：www/guide/index.md
• 配置指南
• 飞书远程接入配置
• 工具与权限
• Skills 使用
• MCP 工具接入
• 升级与版本检查
• 排障与常见问题

文档站源码位于 www/，本地预览：

cd www
pnpm install
pnpm docs:dev

参与贡献

欢迎通过 Issue、Discussion 或 Pull Request 参与 NeoCode。

建议流程：

1. 先在 Issue 中描述问题、需求或设计想法。
2. Fork 仓库并创建功能分支。
3. 保持改动聚焦，说明动机和影响范围。
4. 提交前运行基础检查：

gofmt -w ./cmd ./internal
go test ./...
go build ./...

License

MIT