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