# 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
```

## 使用 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 会展示模型建议的操作，并在执行前要求确认。你仍然应该检查命令和补丁是否符合预期，尤其是删除文件、修改系统设置、上传数据、安装依赖这类操作。