259 lines
5.3 KiB
Markdown
259 lines
5.3 KiB
Markdown
# NLProg
|
||
|
||
NLProg 是一个终端优先的自然语言编程 Agent。你可以用中文或英文描述任务，它会调用配置好的模型，检查项目、修改文件、运行验证命令，并在关键操作前请求确认。
|
||
|
||
## 功能
|
||
|
||
- 支持 `ask`、`chat`、`agent` 三种使用方式
|
||
- 支持 OpenAI、OpenAI-compatible、Anthropic、Gemini、opencode、mock
|
||
- 可通过 opencode 使用本机已授权的 ChatGPT Pro/Plus
|
||
- Agent 支持文件查看、搜索、补丁式修改、命令执行
|
||
- 写文件和高风险命令前会预览确认
|
||
- 支持 JSON 自动修复重试
|
||
- 支持项目规则、项目记忆、自动验证和运行日志
|
||
|
||
## 快速开始
|
||
|
||
```powershell
|
||
python -m pip install -e .
|
||
python -m nlprog init
|
||
python -m nlprog init-project --show
|
||
python -m nlprog doctor
|
||
python -m unittest discover
|
||
python -m nlprog agent "帮我检查这个项目"
|
||
```
|
||
|
||
Windows 一键安装：
|
||
|
||
```powershell
|
||
.\install.ps1
|
||
```
|
||
|
||
Windows 一键安装，并尝试安装 opencode：
|
||
|
||
```powershell
|
||
.\install.ps1 -InstallOpencode
|
||
```
|
||
|
||
安装脚本会优先使用 Scoop 安装 opencode；如果没有 Scoop 但有 npm，则使用 `npm install -g opencode-ai`。如果两者都没有，会提示手动安装命令。
|
||
|
||
## 配置管理
|
||
|
||
查看配置：
|
||
|
||
```powershell
|
||
python -m nlprog config show
|
||
```
|
||
|
||
修改配置：
|
||
|
||
```powershell
|
||
python -m nlprog config set provider opencode
|
||
python -m nlprog config set model ""
|
||
python -m nlprog config set json_repair_retries 3
|
||
```
|
||
|
||
快捷切换到 opencode：
|
||
|
||
```powershell
|
||
python -m nlprog config use-opencode
|
||
```
|
||
|
||
指定 opencode 路径：
|
||
|
||
```powershell
|
||
python -m nlprog config use-opencode --command "C:\Users\win\scoop\shims\opencode.exe"
|
||
```
|
||
|
||
## 模型注册表
|
||
|
||
查看已注册模型：
|
||
```powershell
|
||
python -m nlprog models list
|
||
```
|
||
|
||
添加并启用 opencode：
|
||
```powershell
|
||
python -m nlprog models add codex --provider opencode --use
|
||
```
|
||
|
||
添加 OpenAI-compatible 模型：
|
||
```powershell
|
||
python -m nlprog models add deepseek --provider openai-compatible --model deepseek-chat --base-url https://api.deepseek.com/v1 --api-key-env DEEPSEEK_API_KEY
|
||
```
|
||
|
||
切换模型：
|
||
```powershell
|
||
python -m nlprog models use deepseek
|
||
```
|
||
|
||
查看或删除模型：
|
||
```powershell
|
||
python -m nlprog models show deepseek
|
||
python -m nlprog models remove deepseek
|
||
```
|
||
|
||
## 自动更新
|
||
|
||
NLProg 默认在每次启动时检查更新。如果发现新版本，会询问是否立即更新。
|
||
|
||
手动检查更新：
|
||
```powershell
|
||
python -m nlprog update check
|
||
```
|
||
|
||
手动更新：
|
||
```powershell
|
||
python -m nlprog update self
|
||
```
|
||
|
||
关闭自动检测更新：
|
||
```powershell
|
||
python -m nlprog config set auto_update_check false
|
||
```
|
||
|
||
重新开启自动检测更新：
|
||
```powershell
|
||
python -m nlprog config set auto_update_check true
|
||
```
|
||
|
||
## 使用 opencode
|
||
|
||
先确认 opencode 已经登录：
|
||
|
||
```powershell
|
||
opencode auth list
|
||
```
|
||
|
||
然后运行：
|
||
|
||
```powershell
|
||
python -m nlprog config use-opencode
|
||
python -m nlprog agent "只列出项目根目录，不要修改文件"
|
||
```
|
||
|
||
## 项目规则和记忆
|
||
|
||
初始化项目配置：
|
||
|
||
```powershell
|
||
python -m nlprog init-project --show
|
||
```
|
||
|
||
它会生成：
|
||
|
||
```text
|
||
.nlprog/project.json
|
||
.nlprog/rules.md
|
||
.nlprog/memory.md
|
||
```
|
||
|
||
Agent 启动时会读取这些文件，用来了解项目类型、验证命令、保护目录、编辑规则和长期记忆。
|
||
|
||
## 自动验证和运行日志
|
||
|
||
Agent 修改文件后，会自动运行 `.nlprog/project.json` 里的验证命令，例如：
|
||
|
||
```powershell
|
||
python -m compileall src
|
||
python -m unittest discover
|
||
```
|
||
|
||
跳过自动验证：
|
||
|
||
```powershell
|
||
python -m nlprog agent "你的任务" --no-verify
|
||
```
|
||
|
||
每次 Agent 运行会保存 JSON 日志到：
|
||
|
||
```text
|
||
.nlprog/runs/
|
||
```
|
||
|
||
跳过日志：
|
||
|
||
```powershell
|
||
python -m nlprog agent "你的任务" --no-log
|
||
```
|
||
|
||
## Patch 修改
|
||
|
||
Agent 可以用 `apply_patch` 做多文件修改。补丁会先预览，确认后才应用。
|
||
|
||
```text
|
||
*** Begin Patch
|
||
*** Add File: notes.txt
|
||
+hello
|
||
*** Update File: README.md
|
||
@@
|
||
old line
|
||
-remove this
|
||
+add this
|
||
*** Delete File: obsolete.txt
|
||
*** End Patch
|
||
```
|
||
|
||
更新文件时，空格开头表示上下文，`-` 表示删除，`+` 表示新增。为了安全，旧代码块必须在文件中精确匹配一次。
|
||
|
||
## Doctor 诊断
|
||
|
||
检查本机配置、项目规则、验证命令和 opencode：
|
||
|
||
```powershell
|
||
python -m nlprog doctor
|
||
```
|
||
|
||
跳过 opencode 检查：
|
||
|
||
```powershell
|
||
python -m nlprog doctor --no-opencode
|
||
```
|
||
|
||
自动创建缺失的配置和项目文件：
|
||
|
||
```powershell
|
||
python -m nlprog doctor --fix
|
||
```
|
||
|
||
## 运行日志
|
||
|
||
列出最近运行：
|
||
|
||
```powershell
|
||
python -m nlprog runs list
|
||
```
|
||
|
||
查看最新日志：
|
||
|
||
```powershell
|
||
python -m nlprog runs show latest
|
||
```
|
||
|
||
## 版本
|
||
|
||
```powershell
|
||
python -m nlprog version
|
||
```
|
||
|
||
## 命令安全策略
|
||
|
||
Agent 和 `ask` 执行命令前会检查风险：
|
||
|
||
- 高风险系统命令会直接拦截，例如磁盘格式化、注册表修改、网络栈修改、关机重启
|
||
- 删除文件、安装依赖、执行下载脚本等命令会要求额外确认
|
||
- 普通验证命令，例如 `python -m compileall src`，会正常执行
|
||
|
||
## mock 模式
|
||
|
||
`mock` 不联网，适合验证程序流程：
|
||
|
||
```powershell
|
||
python -m nlprog config set provider mock
|
||
python -m nlprog ask "列出当前目录"
|
||
```
|
||
|
||
## 安全说明
|
||
|
||
NLProg 会展示模型建议的操作，并在执行前要求确认。你仍然应该检查命令和补丁是否符合预期，尤其是删除文件、修改系统设置、上传数据、安装依赖这类操作。
|