npm - zencode-cli - Versions diffs - 0.1.0 → 0.2.1 - Mend

zencode-cli 0.1.0 → 0.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (5) hide show

package/README.md ADDED Viewed

@@ -0,0 +1,400 @@
+# ZenCode
+极简 CLI AI 编程工具 — 用最少的提示词，让模型把全部能力集中在编程本身。
+## 特性
+- 🤖 **双 Agent 协作** — 调度者（Orchestrator）收集上下文 + 编码者（Coder）专注编程
+- 📝 **Memo 协作桥** — 双 Agent 通过共享备忘录传递上下文，避免重复探索
+- ⚡ **并行子 Agent** — 用 spawn-agents 并行处理多文件任务
+- 📋 **Todo 计划** — 内置任务清单，跟踪多步骤项目
+- 🖥️ **全屏 TUI** — 交互式终端界面，支持流式输出、工具确认
+## 安装
+```bash
+# 从 npm 安装
+npm install -g zencode-cli
+# 或者用 yarn
+yarn global add zencode-cli
+```
+## 快速开始
+```bash
+# 交互式 TUI 模式（推荐）
+zencode
+# 单次执行
+zencode "帮我写一个 Hello World"
+# 查看帮助
+zencode --help
+```
+## 配置
+### 配置文件
+在 `~/.zencode/config.yaml`（Linux/Mac）或 `%USERPROFILE%\.zencode\config.yaml`（Windows）创建配置文件：
+```yaml
+# 模型配置
+model: deepseek-chat        # 模型名称
+api_key: sk-xxx            # API 密钥
+base_url: https://api.deepseek.com/v1  # API 地址
+# Agent 模式
+agent_mode: dual           # single | dual
+collaboration: delegated    # delegated | autonomous | controlled
+# 功能开关
+features:
+  parallel_agents: on       # on | off
+  todo: on                 # on | off
+# 高级选项
+max_tokens: 8192
+temperature: 0.7
+max_tool_output: 4000      # 工具输出最大字符数
+# 权限配置（可选）
+permissions:
+  bash: confirm            # auto | confirm | deny
+  write-file: confirm
+  read-file: auto
+```
+### 环境变量
+| 变量 | 说明 |
+|------|------|
+| `ZENCODE_API_KEY` | API 密钥（优先级高于配置文件） |
+| `ZENCODE_BASE_URL` | API 地址 |
+| `ZENCODE_MODEL` | 模型名称 |
+### CLI 参数
+```bash
+zencode [options] [prompt...]
+Arguments:
+  prompt                直接执行的提示词（非交互式）
+Options:
+  -V, --version        output the version number
+  -m, --model <model>  指定模型名称
+  -k, --api-key <key>  API 密钥
+  -u, --base-url <url> API 基础 URL
+  --single              使用单 Agent 模式
+  --dual               使用双 Agent 模式
+  --mode <mode>        协作模式 (delegated/autonomous/controlled)
+  --simple             使用简单 REPL 模式（非全屏 TUI）
+  -h, --help           display help for command
+```
+## 使用模式
+### 1. 交互式 TUI 模式（默认）
+```bash
+zencode
+```
+启动全屏终端界面：
+- 上半部分：对话历史（流式输出）
+- 下半部分：输入框 + 状态栏
+```
+┌─────────────────────────────────────────────────────────┐
+│ ◆ 你好，我想创建一个春节祝福网页                      │
+│                                                       │
+│ ⏳ + write-file demo/index.html                        │
+│   ✎ 生成中... 150 行                                  │
+│ ✓ + write-file demo/index.html  203 行               │
+│   <!DOCTYPE html>...                                  │
+├─────────────────────────────────────────────────────────┤
+│ > 创建马年春节祝福网页                                │
+│ ───────────────────────────────────────────────────── │
+│ dual(delegated) ▶ deepseek-chat │ ⚙ coder │ /help   │
+└─────────────────────────────────────────────────────────┘
+```
+### 2. 单次执行模式
+```bash
+zencode "帮我写一个 Python 脚本，批量重命名文件"
+```
+### 3. 简单 REPL 模式
+```bash
+zencode --simple
+```
+适合不支持全屏 TUI 的终端环境。
+## Agent 模式
+### 单 Agent 模式（`--single`）
+一个 Agent 完成所有工作：理解需求 → 收集上下文 → 写代码 → 执行验证。
+```bash
+zencode --single
+# 或
+zencode --single "修复 src/utils.ts 中的类型错误"
+```
+### 双 Agent 模式（默认）
+```
+用户请求
+    ↓
+Orchestrator（调度者）
+    ├── 评估任务复杂度
+    ├── 收集上下文（glob/read-file）
+    ├── 记入 memo（共享记忆）
+    └── 委派给 Coder
+            ↓
+        Coder（编码者）
+            ├── 读 memo 获取上下文
+            ├── write-file / edit-file
+            ├── 写 memo 记录改动
+            └── 返回结果
+```
+#### 协作模式
+| 模式 | 说明 | 适用场景 |
+|------|------|----------|
+| `delegated` | 调度者委派任务，Coder 有完整工具 | 大多数场景 |
+| `autonomous` | Coder 自主决策，适合强模型 | 简单任务、能力强模型 |
+| `controlled` | Coder 只返回代码，调度者执行 | 需要严格控制文件操作 |
+```bash
+# 切换协作模式
+zencode --mode delegated
+zencode --mode autonomous
+zencode --mode controlled
+```
+或在 TUI 中输入：
+```
+/mode delegated
+/mode autonomous
+/mode controlled
+```
+## 功能
+### Memo 共享备忘录
+双 Agent 协作的核心桥梁。
+```bash
+# 写入
+memo write key="项目结构" value="使用 React + Vite"
+# 读取
+memo read 项目结构
+# 列出所有
+memo list
+# 删除
+memo delete 项目结构
+```
+**协作流程：**
+1. Orchestrator 收集上下文 → `memo write`
+2. 委派时引用 memo key
+3. Coder 先 `memo read` 获取上下文
+4. Coder 完成后 `memo write` 记录改动
+### Todo 计划
+多步骤任务管理。
+```
+# 在 TUI 中
+/todo              # 切换 todo 功能
+```
+```bash
+# 添加任务
+todo add "创建 HTML 结构"
+# 查看计划
+todo list
+# 标记完成
+todo done <id>
+# 删除任务
+todo delete <id>
+```
+### Spawn Agents 并行子 Agent
+并行处理多文件任务。
+```
+# 在 TUI 中
+/parallel          # 切换并行功能
+```
+让多个 Coder 子任务并行运行，适合：
+- 并行读取多个文件
+- 并行搜索代码
+- 多文件批量处理
+## 快捷键
+| 快捷键 | 说明 |
+|--------|------|
+| `Ctrl+C` | 取消当前请求 / 退出 |
+| `Ctrl+D` | 退出程序 |
+| `Enter` | 发送消息 |
+| `↑/↓` | 历史命令（简单模式） |
+### TUI 命令
+| 命令 | 说明 |
+|------|------|
+| `/help` | 显示帮助 |
+| `/mode [模式]` | 切换协作模式 |
+| `/single` | 切换到单 Agent |
+| `/dual` | 切换到双 Agent |
+| `/parallel` | 开关并行子 Agent |
+| `/todo` | 开关 Todo 计划 |
+| `/clear` | 清空对话历史 |
+| `/info` | 显示当前配置 |
+## 支持的模型
+ZenCode 通过 OpenAI 兼容 API 连接各种模型。
+### 推荐模型
+| 模型 | API | 特点 |
+|------|-----|------|
+| DeepSeek Chat | deepseek.com | 性价比高，效果好 |
+| Qwen Turbo | dashscope.aliyun.com | 阿里出品 |
+| GPT-4o | openai.com | 能力强 |
+### 配置示例
+```yaml
+# DeepSeek
+model: deepseek-chat
+base_url: https://api.deepseek.com/v1
+# 阿里 Qwen
+model: qwen-turbo
+base_url: https://dashscope.aliyuncs.com/compatible-mode/v1
+# OpenAI
+model: gpt-4o
+base_url: https://api.openai.com/v1
+```
+## 工具
+ZenCode 内置以下工具：
+| 工具 | 说明 | 权限 |
+|------|------|------|
+| `read-file` | 读取文件内容 | auto |
+| `write-file` | 创建/覆盖文件 | confirm |
+| `edit-file` | 编辑文件 | confirm |
+| `glob` | 文件搜索 | auto |
+| `grep` | 代码搜索 | auto |
+| `bash` | 执行命令 | confirm |
+| `spawn-agents` | 并行子 Agent | confirm |
+| `memo` | 共享备忘录 | auto |
+| `todo` | 任务计划 | auto |
+权限级别：
+- `auto` — 自动执行
+- `confirm` — 需要用户确认
+- `deny` — 禁止执行
+## 提示词技巧
+### 1. 明确目标
+```
+❌ 帮我优化一下代码
+✅ 重构 src/utils.ts 中的 formatDate 函数，使用 dayjs
+```
+### 2. 提供上下文
+```
+✅ 在 demo/ 目录下创建 index.html，使用现有 weather.html 的样式
+✅ 修改 src/api/user.ts，增加获取用户头像的接口
+```
+### 3. 分步执行
+```
+✅ 第一步：创建数据模型
+✅ 第二步：实现 API 接口
+```
+### 4. 指定约束
+```
+✅ 用 TypeScript，不要 any
+✅ 保持现有代码风格，使用 React Hooks
+✅ 不要添加测试，只做核心功能
+```
+## 常见问题
+### Q: 工具执行被拒绝
+A: 检查配置文件的 `permissions` 设置，或在 TUI 中按 `y` 允许执行。
+### Q: 模型响应慢
+A: 尝试：
+1. 换更快的模型（如 qwen-turbo）
+2. 减少 `max_tokens`
+3. 使用 `--simple` 模式减少 UI 开销
+### Q: Windows 终端显示异常
+A: 确保使用支持 ANSI 的终端（如 Windows Terminal、PowerShell）。
+### Q: 如何更新
+```bash
+npm update -g zencode-cli
+```
+## 开发
+```bash
+# 克隆项目
+git clone https://github.com/your-repo/zencode.git
+cd zencode
+# 安装依赖
+npm install
+# 开发模式
+npm run dev
+# 构建
+npm run build
+# 链接本地
+npm link
+```
+## 许可证
+MIT