@pencil-agent/nano-pencil 1.3.1 → 1.3.2

package/README.md

@@ -1,102 +1,398 @@
-# NanoPencil
+<div align="center">
 
-CLI writing agent with read, bash, edit, write tools and session management. Based on [pi](https://github.com/badlogic/pi-mono); supports DashScope Coding Plan only.
+# ✎ NanoPencil
 
-## 安装
+### 🤖 The Next-Generation AI Coding Agent for Chinese Developers
+
+**让 AI 成为你的编程助手** - 支持文件读写、代码编辑、Shell 命令、会话管理、持久记忆与性格进化
+
+[![npm version](https://badge.fury.io/js/%40pencil-agent%2Fnano-pencil.svg)](https://www.npmjs.com/package/@pencil-agent/nano-pencil)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node.js Version](https://img.shields.io/node/v/@pencil-agent/nano-pencil.svg)](https://nodejs.org)
+
+[English](./README_EN.md) | 简体中文
+
+</div>
+
+---
+
+## ✨ 特性
+
+NanoPencil 是一个为中文开发者优化的 AI 编程代理，基于 [pi-mono](https://github.com/badlogic/pi-mono) 构建，提供了更强大的功能：
+
+- 🛠️ **全功能工具集** - 支持文件读写 (`read`/`write`)、精准编辑 (`edit`)、搜索 (`grep`/`find`)、Bash 执行等
+- 💾 **智能会话管理** - 自动保存会话历史，支持分支、切换、树状浏览
+- 🧠 **持久记忆系统 (NanoMem)** - 自动学习项目知识、用户偏好、错误模式
+- 😊 **AI 性格进化 (NanoSoul)** - AI 性格随交互演化，形成独特风格
+- 🎨 **精美 TUI 界面** - 支持 warm/dark/light 主题，✎ 呼吸加载动画
+- 🔌 **MCP 协议支持** - 内置 Filesystem、Fetch、Puppeteer、SQLite、Git 等工具
+- 🌐 **多模型支持** - 阿里百炼、通义千问、OpenAI、Gemini、Ollama 等
+- 📦 **开箱即用** - 无需复杂配置，安装即用，默认使用百炼 Coding Plan
+
+---
+
+## 🚀 快速开始
+
+### 安装
 
 ```bash
 npm install -g @pencil-agent/nano-pencil
 ```
 
-## 首次使用
+### 首次运行
+
+```bash
+nanopencil
+```
+
+首次运行会提示输入**阿里百炼 Coding Plan API Key**（格式 `sk-sp-...`），输入后会自动保存到 `~/.nanopencil/agent/auth.json`，之后无需再输。
 
-配置目录为 `~/.nanopencil/agent/`，与官方 pi（`~/.pi`）互不干扰。
+> 💡 **提示**：百炼 Coding Plan 是专门为代码生成优化的模型，效果出色且价格实惠。
 
-首次运行（交互模式）会提示输入**百炼 Coding Plan API Key**（格式 `sk-sp-...`），输入后会持久化到 `~/.nanopencil/agent/auth.json`，之后直接使用无需再输。
+### 开始对话
 
-非交互模式（管道或 RPC）下若未配置 API Key，会报错并提示先交互运行 `nanopencil` 完成配置。
+进入交互界面后，直接输入你的需求即可：
 
-## 运行
+```
+你: 帮我写一个 Express 中间件来验证 JWT token
 
-```bash
-nanopencil
+AI: [自动创建 jwt-auth.middleware.ts 文件，包含完整实现]
 ```
 
-进入后可直接输入需求，模型会使用 read、write、edit、bash 等工具完成任务。
+---
+
+## 📖 核心功能
+
+### 1. 工具系统
 
-### MCP 支持
+NanoPencil 内置强大的工具系统，AI 可以自主调用：
 
-NanoPencil 内置支持 MCP (Model Context Protocol)，**默认启用**免费工具（Filesystem、Fetch、Puppeteer、SQLite、Git）。
+| 工具 | 功能 | 示例 |
+|------|------|------|
+| `read` | 读取文件内容 | "查看 package.json" |
+| `write` | 创建/覆盖文件 | "创建 utils/helpers.ts" |
+| `edit` | 精准编辑（基于行号） | "将第 15 行的 `console.log` 改为 `logger.info`" |
+| `grep` | 内容搜索 | "查找所有使用 `useState` 的地方" |
+| `find` | 文件名搜索 | "找到所有测试文件" |
+| `bash` | 执行 Shell 命令 | "运行 npm install 并安装 lodash" |
+
+### 2. 会话管理
+
+- **自动保存** - 所有对话自动保存，随时可恢复
+- **会话分支** - 在任意节点创建新分支进行探索
+- **会话切换** - `/resume` 快速切换历史会话
+- **会话树** - `/tree` 可视化浏览会话分支结构
+
+### 3. 记忆与性格 (NanoMem & NanoSoul)
+
+**NanoMem** - 项目记忆系统：
+- 📚 自动记录项目知识（API 端点、配置项、架构决策）
+- 💡 学习错误模式和解决方案
+- ❤️ 识别用户偏好和编码风格
+- 🔄 A-MEM 风格的动态关联网络
+
+**NanoSoul** - AI 性格系统：
+- 🎭 大五人格 + 编程特质（代码冗长度、抽象层级、安全边际）
+- 🎯 动态专长领域追踪（前端、后端、DevOps、AI 等）
+- 😊 情绪状态建模（信心、好奇心、挫败感、心流）
+- 📈 每次交互后自动进化
 
 ```bash
-nanopencil  # MCP 默认启用
+/soul     # 查看 AI 当前性格和统计
+/memory   # 查看项目记忆信息
 ```
 
+### 4. 斜线命令
+
+| 命令 | 功能 |
+|------|------|
+| `/model` | 切换 AI 模型 |
+| `/thinking` | 设置思考级别 (off/minimal/low/medium/high/xhigh) |
+| `/settings` | 打开设置菜单 |
+| `/clear` 或 `/new` | 清空当前会话 |
+| `/fork` | 从当前消息创建新会话分支 |
+| `/tree` | 浏览会话树 |
+| `/resume` | 恢复历史会话 |
+| `/compact` | 手动压缩上下文 |
+| `/soul` | 查看 AI 性格 |
+| `/memory` | 查看项目记忆 |
+| `/export` | 导出为 HTML |
+| `/login` | 配置 API Key |
+
+### 5. MCP 协议支持
+
+NanoPencil **默认启用** MCP (Model Context Protocol)，免费内置以下工具：
+
+- 📁 **Filesystem** - 文件系统操作
+- 🌐 **Fetch** - HTTP 请求
+- 🎭 **Puppeteer** - 浏览器自动化
+- 🗄️ **SQLite** - 数据库操作
+- 🔧 **Git** - Git 版本控制
+
 详见 [MCP 文档](docs/MCP_GUIDE.md) 和 [内置工具列表](docs/BUILTIN_MCP_TOOLS.md)。
 
-## 常用命令与快捷键
+---
 
-在输入框输入 `/` 可触发命令，例如：
+## 🎨 界面展示
 
-| 命令 | 说明 |
-|------|------|
-| `/model` | 切换模型（Qwen3 Coder Plus / Qwen3 Max） |
-| `/settings` | 思考级别、主题、会话等设置 |
-| `/resume` | 从历史会话中选择继续 |
-| `/new` | 新建会话 |
-| `/session` | 查看当前会话信息 |
-| `/hotkeys` | 查看全部快捷键 |
+### TUI 界面
 
-常用快捷键：`Ctrl+L` 选模型，`Ctrl+P` / `Shift+Ctrl+P` 在已选模型间切换，`Escape` 取消/中止。
+```
+                .-~~~~~~~~~-._       _.-~~~~~~~~~-.
+            __.'              ~.   .~              `.__
+          .'//                  \./                  \\`.
+        .'//                     |                     \\`.
+      .\'// .-~""~~~~-._     |     _,-~~~~""~-. \\\`.
+    .\'//.-"                 `-.  .-'                 \"-.\\\`.
+  .\'//______.============-..   \ | /   ..-============.______\\\`.
+.\'______________________________\|/______________________________`\.
 
-## 配置与数据
+  nano-pencil v1.3.1
+  DashScope Coding Plan · Qwen3 Coder Plus
+  C:\Users\Windows11\nanoPencil
 
-| 路径 | 说明 |
-|------|------|
-| `~/.nanopencil/agent/auth.json` | API Key 等认证信息 |
-| `~/.nanopencil/agent/models.json` | 模型配置（默认仅百炼 Coding Plan） |
-| `~/.nanopencil/agent/settings.json` | 全局设置 |
-| `~/.nanopencil/agent/sessions/` | 会话存储 |
+  /model to switch model
+
+────────────────────────────────────────────────────────────────
+
+✎▓ Working... (Ctrl+L to cancel)
+
+你> 帮我重构这个组件
+```
+
+### 主题支持
+
+- 🌙 **Dark** - 经典暗色主题
+- ☀️ **Light** - 明亮清新主题
+- 🧡 **Warm** - 温暖护眼主题（推荐）
+
+使用 `/settings` → `Theme` 切换主题。
+
+---
+
+## 💻 CLI 用法
+
+### 交互模式
 
-## CLI 示例
+```bash
+nanopencil                    # 启动交互界面
+nanopencil -c                 # 继续最近会话
+nanopencil -r                 # 选择历史会话
+nanopencil -m qwen3-max       # 指定模型启动
+```
+
+### 单次提问模式
+
+```bash
+nanopencil -p "解释这段代码"
+nanopencil -p "重构 src/app.ts" < src/app.ts
+```
+
+### 管道模式
 
 ```bash
-nanopencil                          # 交互模式
-nanopencil -p "总结这段代码"         # 单次提问并打印结果
-nanopencil -c                       # 继续最近会话
-nanopencil -r                       # 选择历史会话
-nanopencil --list-models            # 列出可用模型
-nanopencil -h                       # 帮助
+echo "添加 TypeScript 类型定义" | nanopencil
+cat code.js | nanopencil -p "转成 TypeScript"
 ```
 
-## 环境变量
+### RPC 模式
+
+为 IDE 集成提供 JSON-RPC 接口：
+
+```bash
+nanopencil --rpc
+```
+
+### 其他选项
+
+```bash
+nanopencil --list-models      # 列出可用模型
+nanopencil --version          # 显示版本
+nanopencil --help             # 显示帮助
+```
+
+---
+
+## ⚙️ 配置
+
+### 配置目录
+
+```
+~/.nanopencil/agent/
+├── auth.json              # API Keys 和 OAuth 凭证
+├── models.json            # 模型配置
+├── settings.json          # 全局设置
+├── sessions/              # 会话历史
+│   └── *.jsonl           # 会话文件
+├── memory/               # NanoMem 记忆存储
+│   ├── knowledge.json    # 项目知识
+│   ├── lessons.json      # 经验教训
+│   ├── preferences.json  # 用户偏好
+│   └── patterns.json     # 行为模式
+└── soul/                 # NanoSoul 性格存储
+    └── profile.json      # AI 性格档案
+```
+
+### 项目级配置
+
+在项目根目录创建 `.pi/settings.json` 可覆盖全局设置：
+
+```json
+{
+  "thinkingLevel": "high",
+  "theme": "warm",
+  "enableSkillCommands": true
+}
+```
+
+### 上下文文件
+
+NanoPencil 会自动加载以下文件作为上下文：
+
+- `.pencil-context.md` - 项目特定上下文
+- `.PENCIL.md` - 全局上下文（`~/.nanopencil/agent/.PENCIL.md`）
+- `CLAUDE.md` - Claude 项目指令
+- `AGENTS.md` - 多代理协作指令
+
+### 环境变量
 
 | 变量 | 说明 |
 |------|------|
-| `NANOPENCIL_CODING_AGENT_DIR` | 覆盖配置目录（默认 `~/.nanopencil/agent`） |
+| `NANOPENCIL_CODING_AGENT_DIR` | 覆盖配置目录 |
+| `PI_SKIP_VERSION_CHECK` | 跳过版本检查 |
+| `PI_OFFLINE` | 离线模式 |
+
+---
 
-## 开发
+## 🔧 开发
+
+### 克隆仓库
 
 ```bash
-# 克隆仓库
-git clone https://codeup.aliyun.com/67d1a8677564dc59f36547a9/nanoPencil.git
+git clone https://github.com/your-org/nanoPencil.git
 cd nanoPencil
+```
 
-# 安装依赖
+### 安装依赖
+
+```bash
 npm install
+```
 
-# 开发模式运行
-npm run dev
+### 开发模式
 
-# 构建
+```bash
+npm run dev              # 使用 tsx 直接运行
+npm run dev -- -p "test" # 传递参数
+```
+
+### 构建
+
+```bash
 npm run build
+npm run build:watch      # 监听模式
+```
+
+### 运行构建版本
+
+```bash
+npm start                # 等同于 node dist/cli.js
+npm start -- -p "test"
+```
+
+### 项目结构
 
-# 运行构建后的版本
-npm start
 ```
+nanopencil/
+├── cli/                  # CLI 参数解析
+├── core/                 # 核心逻辑
+│   ├── agent-session.ts  # 会话管理
+│   ├── extensions/       # 扩展系统
+│   ├── tools/           # 内置工具
+│   └── ...
+├── modes/                # 运行模式
+│   ├── interactive/      # TUI 交互模式
+│   ├── print-mode.ts     # 标准输出模式
+│   └── rpc/             # JSON-RPC 模式
+├── extensions/           # 内置扩展
+│   ├── simplify/         # MCP 集成
+│   └── ...
+└── packages/            # Monorepo 子包
+    ├── nanomem/         # 记忆系统
+    └── nanosoul/        # 性格系统
+```
+
+---
+
+## 🌟 对比其他 AI 编程工具
+
+| 特性 | NanoPencil | Cursor | Aider | Continue |
+|------|------------|--------|-------|----------|
+| 中文优化 | ✅ | ❌ | ❌ | ❌ |
+| 持久记忆 | ✅ NanoMem | ❌ | ❌ | ❌ |
+| AI 性格 | ✅ NanoSoul | ❌ | ❌ | ❌ |
+| 多模型支持 | ✅ | ✅ | ❌ | ✅ |
+| 会话管理 | ✅ 树状 | ✅ | ❌ | ✅ |
+| MCP 协议 | ✅ 内置 | ❌ | ❌ | 部分支持 |
+| 开源免费 | ✅ MIT | ❌ | ✅ GPL | ✅ Apache |
+| 百炼优化 | ✅ | ❌ | ❌ | ❌ |
+
+---
+
+## 🤝 贡献
+
+欢迎贡献！请遵循以下流程：
+
+1. Fork 本仓库
+2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
+3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
+4. 推送到分支 (`git push origin feature/AmazingFeature`)
+5. 开启 Pull Request
+
+### 开发指南
+
+- 遵循现有代码风格
+- 添加测试覆盖新功能
+- 更新相关文档
+- 确保 `npm run build` 成功
+
+---
+
+## 📄 许可证
+
+[MIT License](LICENSE)
+
+---
+
+## 🙏 致谢
+
+NanoPencil 基于 [pi-mono](https://github.com/badlogic/pi-mono) 构建，感谢原作者 [Mario Zechner](https://github.com/badlogic) 的卓越工作。
+
+同时感谢以下开源项目：
+
+- [@mariozechner/pi-agent-core](https://www.npmjs.com/package/@mariozechner/pi-agent-core)
+- [@mariozechner/pi-ai](https://www.npmjs.com/package/@mariozechner/pi-ai)
+- [@mariozechner/pi-tui](https://www.npmjs.com/package/@mariozechner/pi-tui)
+- [cli-highlight](https://github.com/felixfbecker/cli-highlight)
+- [chalk](https://github.com/chalk/chalk)
+
+---
+
+## 📚 相关资源
+
+- [MCP 协议指南](docs/MCP_GUIDE.md)
+- [内置 MCP 工具列表](docs/BUILTIN_MCP_TOOLS.md)
+- [记忆系统文档](docs/MEMORY_SYSTEM.md)
+- [更新日志](CHANGELOG.md)
+- [问题反馈](https://github.com/your-org/nanoPencil/issues)
+- [讨论区](https://github.com/your-org/nanoPencil/discussions)
+
+---
+
+<div align="center">
 
-## 依赖与许可
+**Made with ❤️ by Chinese Developers**
 
-依赖 [@mariozechner/pi-agent-core](https://www.npmjs.com/package/@mariozechner/pi-agent-core)、[@mariozechner/pi-ai](https://www.npmjs.com/package/@mariozechner/pi-ai)、[@mariozechner/pi-tui](https://www.npmjs.com/package/@mariozechner/pi-tui) 等。Node.js >= 20。
+[⭐ Star](https://github.com/your-org/nanoPencil) · [🐛 报告问题](https://github.com/your-org/nanoPencil/issues) · [💡 建议](https://github.com/your-org/nanoPencil/discussions)
 
-MIT License.
+</div>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pencil-agent/nano-pencil",
-  "version": "1.3.1",
+  "version": "1.3.2",
   "description": "CLI writing agent with read, bash, edit, write tools and session management. Based on pi; supports DashScope Coding Plan. Soul enabled by default for AI personality evolution.",
   "type": "module",
   "bin": {