zencode-cli 0.2.1 → 0.2.3

package/DESIGN.md

@@ -1,613 +0,0 @@
-# ZenCode 设计文档
-
-## 概述
-
-ZenCode 是一个极简的 CLI AI 编程工具，核心理念是「用最少的提示词，让模型把全部能力集中在编程本身」。
-
-### 设计目标
-
-1. **最小认知负担** — 用户只需告诉 AI 要做什么，AI 自动完成收集上下文、编写代码、验证结果
-2. **高效的 Agent 协作** — 通过 memo 作为共享记忆，实现 Orchestrator 与 Coder 的高效配合
-3. **优秀的终端体验** — 全屏 TUI，支持流式输出、实时进度、工具确认
-
-### 核心架构
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│                         用户 (User)                             │
-└────────────────────────────┬────────────────────────────────────┘
-                             │
-                             ▼
-┌─────────────────────────────────────────────────────────────────┐
-│                     CLI 入口 (bin/zencode.ts)                   │
-│                  createCli() → program.parse()                  │
-└────────────────────────────┬────────────────────────────────────┘
-                             │
-              ┌──────────────┼──────────────┐
-              ▼              ▼              ▼
-        ┌─────────┐   ┌──────────┐   ┌──────────┐
-        │ TUI 模式 │   │ 单次执行 │   │ 简单REPL │
-        │(默认)   │   │ 模式     │   │ 模式     │
-        └────┬────┘   └────┬─────┘   └────┬─────┘
-             │             │              │
-             └─────────────┼──────────────┘
-                           ▼
-┌─────────────────────────────────────────────────────────────────┐
-│                    Agent 层 (src/core/)                         │
-│  ┌───────────────┐         ┌────────────────┐                 │
-│  │   Agent       │◄──────►│ Orchestrator    │                 │
-│  │  (单Agent)    │         │ (双Agent调度者) │                 │
-│  └───────────────┘         └───────┬────────┘                 │
-│                                     │                          │
-│                                     ▼                          │
-│                            ┌────────────────┐                  │
-│                            │    Coder       │                 │
-│                            │ (双Agent执行者) │                  │
-│                            └────────────────┘                  │
-└────────────────────────────┬────────────────────────────────────┘
-                             │
-                             ▼
-┌─────────────────────────────────────────────────────────────────┐
-│                   LLM 层 (src/llm/)                            │
-│                     LLMClient                                   │
-│           chatStream() / chat()                                 │
-└────────────────────────────┬────────────────────────────────────┘
-                             │
-                             ▼
-┌─────────────────────────────────────────────────────────────────┐
-│                   工具层 (src/tools/)                           │
-│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────┐    │
-│  │ read-file│ │write-file│ │ edit-file│ │ spawn-agents │    │
-│  └──────────┘ └──────────┘ └──────────┘ └──────────────┘    │
-│  ┌──────────┐ ┌──────────┐ ┌──────────┐                      │
-│  │   bash   │ │   memo   │ │   todo   │                      │
-│  └──────────┘ └──────────┘ └──────────┘                      │
-└─────────────────────────────────────────────────────────────────┘
-```
-
-## 核心组件
-
-### 1. CLI 入口
-
-**文件**: `src/cli/index.ts`
-
-负责解析命令行参数、加载配置、选择运行模式。
-
-```typescript
-// 三种运行模式
-if (prompt) {
-  await runOnce(prompt, config);        // 单次执行
-} else if (opts.simple) {
-  await startRepl({ config });          // 简单 REPL
-} else {
-  await startTui({ config });           // 全屏 TUI (默认)
-}
-```
-
-### 2. Agent 层
-
-#### 单 Agent 模式
-
-**文件**: `src/core/agent.ts`
-
-适用于简单任务，一个 Agent 完成所有工作。
-
-```
-用户输入 → LLM → 工具调用 → 执行 → 结果 → LLM → ...
-```
-
-```typescript
-class Agent {
-  async run(prompt: string, callbacks: AgentCallbacks) {
-    while (true) {
-      const msg = await this.client.chatStream(prompt, tools, callbacks);
-      if (!msg.tool_calls) break;
-      // 执行工具循环
-    }
-  }
-}
-```
-
-#### 双 Agent 模式
-
-**文件**: `src/core/dual-agent/orchestrator.ts`
-
-调度者（Orchestrator）+ 编码者（Coder），通过 memo 共享上下文。
-
-```
-Orchestrator                    Coder
-    │                              │
-    ├── glob/read-file 收集      │
-    ├── memo write 记录          │
-    │                              │
-    ├── send-to-coder ──────────►│
-    │                              ├── memo read
-    │                              ├── write-file/edit-file
-    │                              ├── memo write
-    ◄─────────────────────────────┤
-```
-
-##### Orchestrator 系统提示词
-
-```markdown
-你是侦察兵 + 指挥官。你自己不写代码，你的职责是：
-收集情报 → 记入 memo → 委派编码 Agent。
-
-1. 评估：任务是否需要了解现有代码？
-2. 收集上下文：glob/read-file
-3. memo write：记录关键发现
-4. send-to-coder：任务 + 引用 memo key
-```
-
-##### Coder 身份
-
-```markdown
-1. 读 memo：如果任务提到 memo key，先 memo read
-2. 编码：新建 → write-file，修改 → read-file → edit-file
-3. 写 memo：记录改动摘要
-4. 回复：一句话说明结果
-```
-
-##### 协作模式
-
-| 模式 | Coder 工具 | 说明 |
-|------|-----------|------|
-| `delegated` | 有 | 调度者委派，Coder 独立执行 |
-| `autonomous` | 有 | Coder 自主决策 |
-| `controlled` | 无 | Coder 只返回代码 |
-
-### 3. 工具层
-
-#### 工具注册表
-
-**文件**: `src/tools/registry.ts`
-
-管理所有可用工具及其权限级别。
-
-```typescript
-class ToolRegistry {
-  private tools: Map<string, Tool> = new Map();
-  private permissions: Map<string, PermissionLevel> = new Map();
-
-  register(tool: Tool) { ... }
-  execute(name: string, params: Record<string, unknown>): Promise<ToolResult> { ... }
-  toToolDefinitions(filter?: string[]): ToolDefinition[] { ... }
-}
-```
-
-#### 权限级别
-
-```typescript
-type PermissionLevel = 'auto' | 'confirm' | 'deny';
-```
-
-- `auto` — 自动执行（如 read-file、glob）
-- `confirm` — 需要用户确认（如 write-file、bash）
-- `deny` — 禁止执行
-
-#### 内置工具
-
-| 工具 | 功能 | 权限 |
-|------|------|------|
-| `read-file` | 读取文件 | auto |
-| `write-file` | 创建/覆盖文件 | confirm |
-| `edit-file` | 编辑文件 | confirm |
-| `glob` | 文件搜索 | auto |
-| `grep` | 代码搜索 | auto |
-| `bash` | 执行命令 | confirm |
-| `spawn-agents` | 并行子 Agent | confirm |
-| `memo` | 共享备忘录 | auto |
-| `todo` | 任务计划 | auto |
-
-#### 自定义工具
-
-工具接口定义：
-
-```typescript
-interface Tool {
-  name: string;
-  description: string;
-  parameters: JSONSchema;
-  permissionLevel: PermissionLevel;
-  execute(params: Record<string, unknown>): Promise<ToolResult>;
-}
-```
-
-### 4. 记忆系统
-
-#### Memo 共享备忘录
-
-**文件**: `src/core/memo-store.ts`
-
-双 Agent 协作的核心桥梁。
-
-```typescript
-class MemoStore {
-  private memos: Map<string, string> = new Map();
-
-  write(key: string, value: string): void
-  read(key: string): string | undefined
-  delete(key: string): boolean
-  list(): Map<string, string>
-  buildIndex(): string  // 生成可嵌入任务的索引
-}
-```
-
-**协作流程**:
-
-```
-Orchestrator                          Coder
-    │                                   │
-    ├── glob/read-file 收集             │
-    ├── memo write("demo-structure",   │
-    │    "demo/ 下有 weather.html...")  │
-    │                                   │
-    ├── send-to-coder(                 │
-    │   "在 demo/newyear.html 创建..."  │
-    │   + "参考 memo key 'demo-structure'")          │
-    │                                   │
-    │                              memo read("demo-structure")
-    │                              write-file(...)
-    │                              memo write("done-newyear", "创建了...")
-    ◄───────────────────────────────┤
-```
-
-#### Todo 计划
-
-**文件**: `src/core/todo-store.ts`
-
-多步骤任务管理。
-
-```typescript
-interface TodoItem {
-  id: string;
-  content: string;
-  status: 'pending' | 'completed' | 'failed';
-  createdAt: number;
-}
-
-class TodoStore {
-  private items: TodoItem[] = [];
-
-  add(content: string): TodoItem
-  complete(id: string): void
-  delete(id: string): void
-  list(): TodoItem[]
-  subscribe(callback: (plan: TodoPlan) => void): () => void
-}
-```
-
-### 5. TUI 层
-
-**文件**: `src/cli/tui/`
-
-基于 Ink + React 的全屏终端界面。
-
-#### 架构
-
-```
-┌─────────────────────────────────────────────────────┐
-│                    App.tsx                           │
-│  ┌───────────────────────────────────────────────┐  │
-│  │              ChatArea.tsx                     │  │
-│  │   Static (已完成内容)  │  Dynamic (流式内容)  │  │
-│  └───────────────────────────────────────────────┘  │
-│  ┌──────────┐ ┌──────────┐ ┌────────────────┐   │
-│  │ InputArea│ │StatusBar │ │ ConfirmPrompt  │   │
-│  └──────────┘ └──────────┘ └────────────────┘   │
-└─────────────────────────────────────────────────────┘
-           │                │
-           ▼                ▼
-┌─────────────────────────────────────────────────────┐
-│                    bridge.ts                         │
-│    createBridgeCallbacks(dispatch) → TuiAction     │
-└─────────────────────────────────────────────────────┘
-           │
-           ▼
-┌─────────────────────────────────────────────────────┐
-│                    state.ts                         │
-│              tuiReducer(state, action)              │
-└─────────────────────────────────────────────────────┘
-```
-
-#### 渲染策略
-
-采用 **Log-Style** 渲染，面向 Windows 终端兼容性：
-
-1. **Static 区域** — 已完成的内容，推入 Ink `<Static>` 后写入 scrollback，永不重绘
-2. **Dynamic 区域** — 最小重绘面积（最多 1 行），用于流式输出
-
-```typescript
-// 渲染流程
-function extractFromBlocks(msg, staticItems, dynamicNodes, isStreaming) {
-  // 完整行 → Static
-  // 末尾部分行 → Dynamic (1 行)
-}
-```
-
-#### 工具调用显示
-
-```
-⏳ + write-file demo/index.html    ← Static (tool-header)
-    ✎ 生成中... 37 行             ← Dynamic (progress)
-✓ + write-file demo/index.html  203 行  ← Static (tool-done)
-    <!DOCTYPE html>              ← Static (代码预览)
-    ...
-```
-
-#### Windows 终端兼容性
-
-- 移除 `<Spinner>` 动画（定时器重绘导致残影）
-- 移除边框组件（borderStyle 会产生 3 行残影）
-- 实时进度用 Dynamic 区域（Static 在 Windows 上不实时刷新）
-- 使用 `seenIds` + `accumulated` ref 防止 Static 重复渲染
-
-### 6. LLM 层
-
-**文件**: `src/llm/client.ts`
-
-OpenAI 兼容 API 客户端。
-
-```typescript
-class LLMClient {
-  // 流式调用
-  async chatStream(
-    messages: Message[],
-    tools: ToolDefinition[] | undefined,
-    callbacks: StreamCallbacks
-  ): Promise<Message> { ... }
-
-  // 非流式调用
-  async chat(
-    messages: Message[],
-    tools?: ToolDefinition[]
-  ): Promise<Message> { ... }
-}
-```
-
-#### 流式回调
-
-```typescript
-interface StreamCallbacks {
-  onContent?: (text: string) => void;           // 文本内容
-  onToolCall?: (toolCall: ToolCall) => void;   // 完整工具调用
-  onToolCallStreaming?: (index, name, args) => void;  // 工具参数流式
-  onFinish?: (message: Message) => void;        // 完成
-  onError?: (error: Error) => void;             // 错误
-}
-```
-
-### 7. 配置系统
-
-**文件**: `src/config/loader.ts`
-
-支持多种配置方式（优先级从高到低）：
-
-1. CLI 参数 (`--api-key`)
-2. 环境变量 (`ZENCODE_API_KEY`)
-3. 配置文件 (`~/.zencode/config.yaml`)
-
-```typescript
-interface ZenCodeConfig {
-  model: string;
-  api_key: string;
-  base_url: string;
-  agent_mode: 'single' | 'dual';
-  collaboration: 'delegated' | 'autonomous' | 'controlled';
-  features: {
-    parallel_agents: 'on' | 'off';
-    todo: 'on' | 'off';
-  };
-  permissions: Record<string, PermissionLevel>;
-  max_tokens: number;
-  temperature: number;
-  max_tool_output: number;
-}
-```
-
-## 数据流
-
-### 1. 用户输入 → LLM
-
-```
-用户输入
-    │
-    ▼
-App.tsx: handleSubmit()
-    │
-    ▼
-Agent.run() / Orchestrator.run()
-    │
-    ▼
-LLMClient.chatStream()
-    │
-    ▼
-StreamCallbacks.onContent() → TUI 显示
-```
-
-### 2. LLM 工具调用
-
-```
-LLM 返回 tool_calls
-    │
-    ├── onToolCallStreaming() ──→ TUI: 工具参数流式更新
-    │
-    ▼
-检查权限 (registry.getPermissionLevel())
-    │
-    ├── auto → 直接执行
-    ├── confirm → 等待用户确认
-    └── deny → 拒绝
-    │
-    ▼
-registry.execute()
-    │
-    ▼
-onToolResult() ──→ TUI: 工具结果
-```
-
-### 3. 双 Agent 协作
-
-```
-Orchestrator LLM
-    │
-    ├── send-to-coder
-    │
-    ▼
-invokeCoder()
-    │ 构造任务 + 注入 memo
-    ▼
-Coder LLM
-    │
-    ├── memo read (获取上下文)
-    ├── write-file / edit-file
-    ├── memo write (记录改动)
-    │
-    ▼
-返回结果给 Orchestrator
-```
-
-## 关键设计决策
-
-### 1. 为什么用双 Agent？
-
-**问题**: 单 Agent 既要收集上下文，又要写代码，容易「既要又要」，效率低下。
-
-**解决**: 分离关注点
-- Orchestrator: 侦察兵 + 指挥官，不写代码，只负责收集信息和委派
-- Coder: 执行者，收到的任务已包含所有上下文，直接动手
-
-### 2. 为什么用 memo 作为协作桥梁？
-
-**问题**: Orchestrator 收集的上下文无法传递给 Coder，导致 Coder 重复探索。
-
-**解决**: memo 是共享记忆
-- Orchestrator 收集 → `memo write`
-- Coder 编码前 → `memo read`
-- Coder 完成 → `memo write` 记录改动
-
-### 3. 为什么用 TUI 而非纯文本？
-
-**问题**: 纯文本模式难以表达复杂信息（工具调用、确认、进度）。
-
-**解决**: 全屏 TUI
-- 流式输出，自然分段
-- 工具调用可视化
-- 用户确认交互
-- 实时进度显示
-
-### 4. 为什么 Log-Style 渲染？
-
-**问题**: Ink 的动态重绘机制在 Windows 终端上产生残影（ANSI 清除不生效）。
-
-**解决**: 只增不减的 Static
-- 已完成内容全部推入 `<Static>`，永不重绘
-- Dynamic 区域最小化（1 行）
-- 特殊处理：实时进度用 Dynamic
-
-## 扩展开发
-
-### 添加新工具
-
-1. 在 `src/tools/` 目录创建工具文件
-2. 实现 `Tool` 接口
-3. 在 `src/tools/register.ts` 注册
-
-```typescript
-// src/tools/my-tool.ts
-export const myTool: Tool = {
-  name: 'my-tool',
-  description: '我的工具描述',
-  parameters: {
-    type: 'object',
-    properties: {
-      input: { type: 'string' }
-    },
-    required: ['input']
-  },
-  permissionLevel: 'confirm',
-  async execute(params) {
-    // 实现逻辑
-    return { content: '结果' };
-  }
-};
-```
-
-### 添加新模型
-
-修改 `src/llm/client.ts`，确保兼容 OpenAI API 格式：
-
-```typescript
-// 只需 base_url 指向兼容端点
-const client = new OpenAI({
-  apiKey: 'your-key',
-  baseURL: 'https://your-model-api.com/v1'
-});
-```
-
-### 添加新功能
-
-1. 在对应模块添加逻辑
-2. 如需 TUI 支持，在 `src/cli/tui/state.ts` 添加 action
-3. 在对应组件处理渲染
-
-## 文件结构
-
-```
-zencode/
-├── bin/
-│   └── zencode.ts          # CLI 入口
-├── src/
-│   ├── cli/
-│   │   ├── index.ts        # CLI 主程序
-│   │   ├── repl.ts         # 简单 REPL
-│   │   ├── ui.ts           # 非 TUI 输出
-│   │   └── tui/
-│   │       ├── index.tsx   # TUI 入口
-│   │       ├── App.tsx     # 主组件
-│   │       ├── state.ts    # 状态管理
-│   │       ├── bridge.ts   # 回调桥接
-│   │       └── components/ # UI 组件
-│   │           ├── ChatArea.tsx
-│   │           ├── InputArea.tsx
-│   │           ├── StatusBar.tsx
-│   │           └── ...
-│   ├── config/
-│   │   ├── loader.ts       # 配置加载
-│   │   └── types.ts        # 类型定义
-│   ├── core/
-│   │   ├── agent.ts        # 单 Agent
-│   │   ├── conversation.ts # 对话管理
-│   │   ├── todo-store.ts  # Todo 存储
-│   │   ├── memo-store.ts  # Memo 存储
-│   │   ├── sub-agent-tracker.ts  # 子 Agent 追踪
-│   │   └── dual-agent/
-│   │       ├── orchestrator.ts   # 调度者
-│   │       ├── coder.ts          # 编码者
-│   │       └── modes.ts          # 协作模式定义
-│   ├── llm/
-│   │   ├── client.ts      # LLM 客户端
-│   │   └── types.ts       # 类型定义
-│   ├── tools/
-│   │   ├── registry.ts    # 工具注册表
-│   │   ├── permission.ts  # 权限检查
-│   │   ├── register.ts   # 内置工具注册
-│   │   ├── types.ts      # 工具类型
-│   │   ├── read-file.ts
-│   │   ├── write-file.ts
-│   │   ├── edit-file.ts
-│   │   ├── bash.ts
-│   │   ├── glob.ts
-│   │   ├── grep.ts
-│   │   ├── memo.ts
-│   │   ├── todo.ts
-│   │   └── spawn-agents.ts
-│   └── prompt/
-│       ├── builder.ts     # 提示词构建
-│       └── layers/        # 提示词分层
-├── dist/                  # 构建输出
-├── package.json
-├── tsconfig.json
-├── tsup.config.ts
-└── README.md
-```