zencode-cli 0.2.1 → 0.2.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 ZenCode Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -4,20 +4,20 @@
 
 ## 特性
 
-- 🤖 **双 Agent 协作** — 调度者（Orchestrator）收集上下文 + 编码者（Coder）专注编程
-- 📝 **Memo 协作桥** — 双 Agent 通过共享备忘录传递上下文，避免重复探索
-- ⚡ **并行子 Agent** — 用 spawn-agents 并行处理多文件任务
-- 📋 **Todo 计划** — 内置任务清单，跟踪多步骤项目
-- 🖥️ **全屏 TUI** — 交互式终端界面，支持流式输出、工具确认
+- **单 Agent 循环** — 理解需求 → 收集上下文 → 写代码 → 执行验证，一个 Agent 完成所有工作
+- **先读后改** — 系统级强制：未读取的文件无法编辑，杜绝盲改
+- **覆盖保护** — write-file 已存在的文件必须显式确认，防止误覆盖
+- **并行子 Agent** — spawn-agents 并行处理多文件任务
+- **可配置子 Agent** — dispatch 工具支持 YAML 定义的专用子 Agent
+- **自定义技能** — 用户可定义斜杠命令，展开为完整提示词
+- **全屏 TUI** — 交互式终端界面，流式输出、工具确认、实时进度
+- **跨平台** — 自动识别 Windows/Linux/macOS，命令提示适配当前平台
+- **deepseek-reasoner 兼容** — 支持 reasoning_content 思维链显示
 
 ## 安装
 
 ```bash
-# 从 npm 安装
 npm install -g zencode-cli
-
-# 或者用 yarn
-yarn global add zencode-cli
 ```
 
 ## 快速开始
@@ -26,6 +26,9 @@ yarn global add zencode-cli
 # 交互式 TUI 模式（推荐）
 zencode
 
+# 简单 REPL 模式
+zencode --simple
+
 # 单次执行
 zencode "帮我写一个 Hello World"
 
@@ -37,260 +40,171 @@ zencode --help
 
 ### 配置文件
 
-在 `~/.zencode/config.yaml`（Linux/Mac）或 `%USERPROFILE%\.zencode\config.yaml`（Windows）创建配置文件：
+`~/.zencode/config.yaml`（全局）或项目目录下 `.zencode/config.yaml`（项目级）：
 
 ```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
+model: deepseek-chat
+api_key: sk-xxx
+base_url: https://api.deepseek.com/v1
+temperature: 0.7
+max_tokens: 8192
 
 # 功能开关
 features:
-  parallel_agents: on       # on | off
-  todo: on                 # on | off
+  git: auto                  # auto | on | off
+  mcp: off                   # on | off（暂未实现）
+  planning_layer: on         # on | off
+  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
+  auto_approve:              # 自动执行的工具
+    - read-file
+    - glob
+    - grep
+    - spawn-agents
+    - todo
+    - dispatch
+  require_approval:          # 需用户确认的工具
+    - write-file
+    - edit-file
+    - bash
+    - git
+
+# 自定义提示词
+prompts:
+  - "始终使用中文回答"
+
+# 工具输出最大长度
+max_tool_output: 30000
 ```
 
+配置优先级（从低到高）：默认值 < 全局 `~/.zencode/config.yaml` < 项目 `.zencode/config.yaml` < 项目根 `.zencode.yaml` < 环境变量 < CLI 参数
+
 ### 环境变量
 
 | 变量 | 说明 |
 |------|------|
-| `ZENCODE_API_KEY` | API 密钥（优先级高于配置文件） |
+| `ZENCODE_API_KEY` | API 密钥 |
 | `ZENCODE_BASE_URL` | API 地址 |
 | `ZENCODE_MODEL` | 模型名称 |
 
 ### CLI 参数
 
-```bash
+```
 zencode [options] [prompt...]
 
 Arguments:
   prompt                直接执行的提示词（非交互式）
 
 Options:
-  -V, --version        output the version number
+  -V, --version        显示版本号
   -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
+  -h, --help           显示帮助
 ```
 
-## 使用模式
-
-### 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`）
+| 工具 | 默认权限 | 说明 |
+|------|---------|------|
+| `read-file` | auto | 读取文件 |
+| `write-file` | confirm | 写入文件 |
+| `edit-file` | confirm | 编辑文件 |
+| `bash` | confirm | 执行命令 |
+| `glob` | auto | 文件搜索 |
+| `grep` | auto | 内容搜索 |
+| `spawn-agents` | auto | 并行子 Agent |
+| `dispatch` | auto | 分派子 Agent |
+| `todo` | auto | 任务计划 |
 
-一个 Agent 完成所有工作：理解需求 → 收集上下文 → 写代码 → 执行验证。
+权限级别：`auto`（自动执行）、`confirm`（需确认）、`deny`（禁止）
 
-```bash
-zencode --single
-# 或
-zencode --single "修复 src/utils.ts 中的类型错误"
-```
+## 安全机制
 
-### 双 Agent 模式（默认）
+### 先读后改（ReadTracker）
 
-```
-用户请求
-    ↓
-Orchestrator（调度者）
-    ├── 评估任务复杂度
-    ├── 收集上下文（glob/read-file）
-    ├── 记入 memo（共享记忆）
-    └── 委派给 Coder
-            ↓
-        Coder（编码者）
-            ├── 读 memo 获取上下文
-            ├── write-file / edit-file
-            ├── 写 memo 记录改动
-            └── 返回结果
-```
+系统级强制：每个 Agent 会话中维护已读文件集合。
 
-#### 协作模式
+- `read-file` 成功 → 标记已读
+- `write-file` 成功 → 标记已读（刚写的文件 Agent 已知内容）
+- `edit-file` 调用前 → 检查是否已读，未读则拒绝
 
-| 模式 | 说明 | 适用场景 |
-|------|------|----------|
-| `delegated` | 调度者委派任务，Coder 有完整工具 | 大多数场景 |
-| `autonomous` | Coder 自主决策，适合强模型 | 简单任务、能力强模型 |
-| `controlled` | Coder 只返回代码，调度者执行 | 需要严格控制文件操作 |
+### 覆盖保护
 
-```bash
-# 切换协作模式
-zencode --mode delegated
-zencode --mode autonomous
-zencode --mode controlled
-```
+write-file 目标文件已存在时，要求设置 `overwrite: true` 才能覆盖。
 
-或在 TUI 中输入：
-```
-/mode delegated
-/mode autonomous
-/mode controlled
-```
+## TUI 命令
 
-## 功能
+| 命令 | 说明 |
+|------|------|
+| `/help` | 显示帮助 |
+| `/skills` | 列出所有可用技能 |
+| `/agents` | 列出所有可用子 Agent |
+| `/parallel` | 切换并行子 Agent on/off |
+| `/todo` | 切换 Todo 计划 on/off |
+| `/clear` | 清空对话历史 |
+| `/info` | 显示当前配置 |
 
-### Memo 共享备忘录
+## 快捷键
 
-双 Agent 协作的核心桥梁。
+| 快捷键 | 说明 |
+|--------|------|
+| `Ctrl+C` / `Escape` | 取消当前请求 |
+| `Ctrl+D` | 退出程序 |
+| `Enter` | 发送消息 |
 
-```bash
-# 写入
-memo write key="项目结构" value="使用 React + Vite"
+## 扩展
 
-# 读取
-memo read 项目结构
+### 自定义子 Agent
 
-# 列出所有
-memo list
+在 `~/.zencode/agents/` 或 `.zencode/agents/` 放置 YAML 文件：
 
-# 删除
-memo delete 项目结构
+```yaml
+name: reviewer
+description: 代码审查专家
+system_prompt: 你是代码审查专家，专注于发现潜在问题。
+tools:
+  - read-file
+  - glob
+  - grep
 ```
 
-**协作流程：**
-1. Orchestrator 收集上下文 → `memo write`
-2. 委派时引用 memo key
-3. Coder 先 `memo read` 获取上下文
-4. Coder 完成后 `memo write` 记录改动
-
-### Todo 计划
+使用时 Agent 会通过 `dispatch` 工具自动调度。
 
-多步骤任务管理。
-
-```
-# 在 TUI 中
-/todo              # 切换 todo 功能
-```
-
-```bash
-# 添加任务
-todo add "创建 HTML 结构"
+### 自定义技能
 
-# 查看计划
-todo list
+在 `~/.zencode/skills/` 或 `.zencode/skills/` 放置 YAML 文件：
 
-# 标记完成
-todo done <id>
-
-# 删除任务
-todo delete <id>
-```
-
-### Spawn Agents 并行子 Agent
-
-并行处理多文件任务。
-
-```
-# 在 TUI 中
-/parallel          # 切换并行功能
+```yaml
+name: review
+description: 审查当前项目代码
+prompt: |
+  请审查当前项目的代码质量，重点关注：
+  1. 潜在 bug
+  2. 安全问题
+  3. 代码规范
 ```
 
-让多个 Coder 子任务并行运行，适合：
-- 并行读取多个文件
-- 并行搜索代码
-- 多文件批量处理
-
-## 快捷键
-
-| 快捷键 | 说明 |
-|--------|------|
-| `Ctrl+C` | 取消当前请求 / 退出 |
-| `Ctrl+D` | 退出程序 |
-| `Enter` | 发送消息 |
-| `↑/↓` | 历史命令（简单模式） |
-
-### TUI 命令
-
-| 命令 | 说明 |
-|------|------|
-| `/help` | 显示帮助 |
-| `/mode [模式]` | 切换协作模式 |
-| `/single` | 切换到单 Agent |
-| `/dual` | 切换到双 Agent |
-| `/parallel` | 开关并行子 Agent |
-| `/todo` | 开关 Todo 计划 |
-| `/clear` | 清空对话历史 |
-| `/info` | 显示当前配置 |
+然后在 TUI 中输入 `/review` 即可触发。
 
 ## 支持的模型
 
-ZenCode 通过 OpenAI 兼容 API 连接各种模型。
-
-### 推荐模型
-
-| 模型 | API | 特点 |
-|------|-----|------|
-| DeepSeek Chat | deepseek.com | 性价比高，效果好 |
-| Qwen Turbo | dashscope.aliyun.com | 阿里出品 |
-| GPT-4o | openai.com | 能力强 |
-
-### 配置示例
+通过 OpenAI 兼容 API 连接各种模型：
 
 ```yaml
 # DeepSeek
 model: deepseek-chat
 base_url: https://api.deepseek.com/v1
 
+# DeepSeek Reasoner（支持思维链）
+model: deepseek-reasoner
+base_url: https://api.deepseek.com
+
 # 阿里 Qwen
 model: qwen-turbo
 base_url: https://dashscope.aliyuncs.com/compatible-mode/v1
@@ -300,99 +214,15 @@ 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
+npm run dev     # 开发模式
+npm run build   # 构建
+npm link        # 链接本地
 ```
 
 ## 许可证