zencode-cli 0.1.0 → 0.2.1

package/DESIGN.md

@@ -0,0 +1,613 @@
+# 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
+```