# 个人电脑助手 & 编程助手 — 可行性分析

> 对标 Claude Code 的 60+ 内置工具，分析 lambdagentpaas 平台实现同等能力所需的工作。

---

## 一、Claude Code 能力全景 vs 平台现状

### 1. 工具能力对照

| 能力域 | Claude Code 工具 | lambdagentpaas 现状 | 差距 |
|--------|-----------------|---------------------|------|
| **文件读取** | `Read` (行号、分页、PDF、图片、Notebook) | ShellTool(`cat`/`head`) | **大** — 无结构化读取、无二进制文件支持 |
| **文件编辑** | `Edit` (精确字符串替换、replace_all) | ShellTool(`sed`) | **大** — 无原子替换、无唯一性校验 |
| **文件写入** | `Write` (覆盖写入、自动创建目录) | ShellTool(`echo >`) | **中** — 可用但无安全检查 |
| **文件搜索** | `Glob` (ripgrep 驱动、按修改时间排序) | ShellTool(`find`) | **中** — 性能和输出格式差距 |
| **内容搜索** | `Grep` (ripgrep、正则、多行、上下文、类型过滤) | ShellTool(`grep`/`rg`) | **中** — 功能等价但无结构化输出 |
| **Shell 执行** | `Bash` (沙盒、超时、后台运行) | ShellTool + SandboxedTool | **小** — 核心能力已有 |
| **Git 操作** | 内置 commit/PR/branch 流程 | ShellTool(`git`) | **中** — 命令可用但无流程封装 |
| **Notebook** | `NotebookEdit` (cell 级编辑) | 无 | **大** — 完全缺失 |
| **Web 搜索** | `WebSearch` | MCP 可扩展 | **中** — 需 MCP 服务器 |
| **Web 获取** | `WebFetch` (HTML→Markdown) | MCP 可扩展 | **中** — 需 MCP 服务器 |
| **子任务代理** | `Agent` (Worktree 隔离、并行) | AsyncPar + IsolatedWorkspace | **小** — 基础设施已有 |
| **任务管理** | `TaskCreate/Update/List` | 无 | **中** — 需新建模块 |
| **上下文管理** | 自动压缩、History snip | ContextManager (Phase 2) | **小** — 已实现基础版 |
| **流式输出** | 全链路 streaming | AsyncExecutor + LLM stream | **小** — 已实现 |
| **取消机制** | AbortController 层级 | CancellationToken | **小** — 已实现 |

### 2. 非工具能力对照

| 能力 | Claude Code | lambdagentpaas | 差距 |
|------|-------------|----------------|------|
| **权限系统** | 用户审批每次工具调用 | ToolGateway 风险分级 + 审计 | **小** — 架构不同但等效 |
| **Hook 系统** | pre/post 钩子、用户自定义 | 无 | **大** — 完全缺失 |
| **CLAUDE.md** | 项目级持久化指令 | Memory + Checkpoint | **中** — 机制不同 |
| **Memory** | 文件系统持久化记忆 | Memory Term + MemoryBackend | **小** — 已有 |
| **多模型** | 自动 fallback model | LLMAdapter 多 Provider | **中** — 无自动 fallback |
| **IDE 集成** | VS Code / JetBrains 扩展 | 无 | **大** — 完全缺失 |
| **OAuth/MCP** | 内置 MCP 服务器管理 | MCPServer + MCPTool | **小** — 基础已有 |

---

## 二、目标产品形态

### 形态 A：个人电脑助手

> 面向普通用户，管理文件、自动化日常任务、信息检索。

核心场景：
- "帮我整理下载文件夹，按类型分类"
- "找到所有大于 100MB 的文件"
- "把这个 PDF 的内容总结一下"
- "搜索邮件中关于项目 X 的讨论"
- "设置一个定时提醒"

### 形态 B：编程助手

> 面向开发者，等价于 Claude Code 的能力。

核心场景：
- "阅读这个项目的代码结构"
- "修复这个 bug"（Read → 分析 → Edit → 验证）
- "写一个新功能并测试"
- "提交代码并创建 PR"
- "运行测试并修复失败的用例"

---

## 三、需要实现的能力模块

### Tier 1：基础工具层（必须）

#### 1.1 结构化文件操作工具集

**需要新建**: `lambdagent/builtin_tools/file_tools.py`

| 工具 | 功能 | 复杂度 | 说明 |
|------|------|--------|------|
| `ReadFile` | 读取文件（行号、offset、limit、PDF、图片描述） | 中 | 核心能力，需处理编码、大文件、二进制 |
| `EditFile` | 精确字符串替换（old_string→new_string） | 中 | 需唯一性校验、原子操作、备份 |
| `WriteFile` | 创建/覆盖写入 | 小 | 需自动创建目录、权限检查 |
| `ListFiles` | 按 glob 模式搜索文件 | 小 | 需按修改时间排序、忽略 .git 等 |
| `SearchContent` | 正则搜索文件内容 | 中 | 需上下文行、类型过滤、多行模式 |

**可行性**: **高** — 纯 Python 实现，无外部依赖。

**核心设计决策**: 工具作为 `ValidatedTool` 子类实现，自带 Pydantic Schema，通过 ToolGateway 进行权限管控。每个工具是一个 Lambda 项 `λx. file_op(x)`，可自然组合到 ReAct loop 中。

```
ReadFile  = ValidatedTool("ReadFile",  read_fn,  ReadFileSchema)
EditFile  = ValidatedTool("EditFile",  edit_fn,  EditFileSchema)
WriteFile = ValidatedTool("WriteFile", write_fn, WriteFileSchema)
```

**工作量**: ~3-4 天

#### 1.2 增强 Shell 执行

**需要修改**: `lambdagent/cli/shell_tool.py` + `sandbox.py`

| 能力 | 说明 | 复杂度 |
|------|------|--------|
| 后台执行 | `run_in_background=True`，非阻塞 | 中 |
| 工作目录持久化 | 跨命令保持 CWD | 小 |
| 环境变量继承 | 继承用户 shell 环境 | 小 |
| 输出限制 | 智能截断（头尾保留） | 小 |
| 交互检测 | 拒绝需要交互的命令（如 `vim`） | 小 |

**可行性**: **高** — ShellTool 已存在，增量改进。

**工作量**: ~2 天

#### 1.3 Git 工作流封装

**需要新建**: `lambdagent/builtin_tools/git_tools.py`

| 工具 | 功能 | 复杂度 |
|------|------|--------|
| `GitStatus` | 状态查看 + diff | 小 |
| `GitCommit` | 智能 commit（分析变更、生成消息） | 中 |
| `GitBranch` | 分支管理 | 小 |
| `GitLog` | 查看历史 | 小 |
| `GitDiff` | 查看变更详情 | 小 |

**可行性**: **高** — 封装 `subprocess.run(["git", ...])` 即可，IsolatedWorkspace 已有 git 操作基础。

**工作量**: ~2 天

### Tier 2：智能层（编程助手必须）

#### 2.1 代码理解引擎

**需要新建**: `lambdagent/builtin_tools/code_tools.py`

| 工具 | 功能 | 复杂度 | 说明 |
|------|------|--------|------|
| `CodeSearch` | 语义代码搜索（类/函数/变量定义） | 高 | 可基于 tree-sitter 或 ripgrep + 正则 |
| `ProjectMap` | 项目结构概览（目录树 + 关键文件摘要） | 中 | 递归扫描 + LLM 摘要 |
| `SymbolLookup` | 查找符号定义和引用 | 高 | 需 AST 解析或 LSP |

**可行性**: **中** — `CodeSearch` 和 `ProjectMap` 可用 ripgrep + glob 实现，`SymbolLookup` 需要 AST 解析器。

**替代方案**: 不做 AST，纯正则 + LLM 理解。80% 的场景足够。

**工作量**: ~4-5 天（无 AST 版本）

#### 2.2 测试运行器

**需要新建**: `lambdagent/builtin_tools/test_tools.py`

| 工具 | 功能 | 复杂度 |
|------|------|--------|
| `RunTests` | 执行测试套件（pytest、jest、go test 等） | 中 |
| `ParseTestOutput` | 解析测试输出，结构化失败信息 | 中 |

**可行性**: **高** — 本质是 ShellTool + 输出解析。

**工作量**: ~2 天

#### 2.3 任务管理系统

**需要新建**: `lambdagent/task_manager.py`

| 工具 | 功能 | 复杂度 |
|------|------|--------|
| `TaskCreate` | 创建任务（subject, description） | 小 |
| `TaskUpdate` | 更新状态（pending → in_progress → completed） | 小 |
| `TaskList` | 列出所有任务 | 小 |

**可行性**: **高** — 内存数据结构 + JSON 持久化。

**工作量**: ~1 天

### Tier 3：交互层（产品化必须）

#### 3.1 权限审批 UI

**当前**: ToolGateway 的 `confirm_callback` 是空实现。

**需要**: 
- CLI 模式：终端 prompt 确认（`y/n`）
- Web 模式：WebSocket 推送 → 前端弹窗 → API 回调

| 组件 | 复杂度 | 说明 |
|------|--------|------|
| CLI confirm prompt | 小 | `input("Allow? [y/n]")` |
| WebSocket confirm | 高 | 需前端配合 |
| 权限记忆 | 中 | "始终允许 X" / "本次会话允许" |

**可行性**: CLI 版 **高**，Web 版 **中**。

**工作量**: CLI ~1 天，Web ~5 天

#### 3.2 流式终端 UI

**当前**: AsyncReActEngine.run_stream() 已返回 StreamEvent。

**需要**: 终端渲染层（类似 Claude Code 的 rich terminal UI）。

| 组件 | 复杂度 | 说明 |
|------|--------|------|
| Token 逐字输出 | 小 | 消费 TokenEvent |
| Spinner + 状态栏 | 中 | 类似 `rich.live` |
| 工具调用展示 | 中 | 折叠/展开工具输入输出 |
| 多 Agent 面板 | 高 | 并行 Agent 的分栏显示 |

**可行性**: 基础版 **高**（用 `rich` 库），完整版 **中**。

**工作量**: 基础 ~3 天，完整 ~8 天

#### 3.3 项目级配置文件

**类似 Claude Code 的 CLAUDE.md**。

**需要**: Agent 启动时自动加载项目目录下的 `.lambdagent.md` 作为额外 system prompt。

**可行性**: **高** — 在 `from_config` 编译时读取并拼接到 systemPrompt。

**工作量**: ~0.5 天

### Tier 4：扩展层（竞争力）

#### 4.1 Hook 系统

**类似 Claude Code 的 pre/post hook。**

| Hook | 触发时机 | 用途 |
|------|----------|------|
| `pre_tool_call` | 工具调用前 | 自定义权限检查、日志 |
| `post_tool_call` | 工具调用后 | 结果过滤、审计 |
| `pre_llm_call` | LLM 调用前 | prompt 注入、成本控制 |
| `post_llm_call` | LLM 调用后 | 输出过滤、安全检查 |
| `on_error` | 出错时 | 自定义恢复逻辑 |

**可行性**: **高** — 在 Executor/AsyncExecutor 的 reduce 方法中插入 hook 点。

**工作量**: ~2 天

#### 4.2 Notebook 编辑

| 组件 | 复杂度 | 说明 |
|------|--------|------|
| 读取 .ipynb | 小 | JSON 解析 |
| Cell 级编辑 | 中 | 按 cell index 增删改 |
| 执行 cell | 高 | 需 Jupyter kernel 连接 |

**可行性**: 读取/编辑 **高**，执行 **中**（需 `jupyter_client` 依赖）。

**工作量**: ~3 天

#### 4.3 Web 工具

| 工具 | 功能 | 复杂度 | 依赖 |
|------|------|--------|------|
| `WebSearch` | 搜索引擎查询 | 中 | SerpAPI / Brave Search API |
| `WebFetch` | 获取网页内容 → Markdown | 中 | `markdownify` + `requests` |

**可行性**: **高** — 可作为 MCP 服务器实现，也可作为内置 Tool。

**工作量**: ~2 天

---

## 四、技术架构方案

### 整体架构

```
┌─────────────────────────────────────────────────────────┐
│                    Terminal UI (rich)                     │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌────────┐  │
│  │ Streaming│  │Permission│  │  Task    │  │ Status │  │
│  │ Output   │  │ Prompt   │  │ Tracker  │  │  Bar   │  │
│  └──────────┘  └──────────┘  └──────────┘  └────────┘  │
├─────────────────────────────────────────────────────────┤
│              Agent Runtime (AsyncExecutor)                │
│  ┌────────────────────────────────────────────────────┐  │
│  │  ReAct Loop (Y combinator)                         │  │
│  │  think → route → invoke → observe → check          │  │
│  │       ↓                                             │  │
│  │  CancellationToken + ContextManager + TokenBudget  │  │
│  └────────────────────────────────────────────────────┘  │
├─────────────────────────────────────────────────────────┤
│                    Built-in Tools                         │
│  ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ ┌──────┐  │
│  │  File  │ │  Code  │ │  Shell │ │  Git   │ │ Web  │  │
│  │ R/W/E  │ │ Search │ │  Exec  │ │ Commit │ │Search│  │
│  └────────┘ └────────┘ └────────┘ └────────┘ └──────┘  │
│  ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐           │
│  │Notebook│ │  Test  │ │  Task  │ │  MCP   │           │
│  │ Edit   │ │ Runner │ │ Manage │ │ Tools  │           │
│  └────────┘ └────────┘ └────────┘ └────────┘           │
├─────────────────────────────────────────────────────────┤
│                   Security Layer                         │
│  ToolGateway → SandboxPolicy → IsolatedWorkspace        │
│  Hook System → Permission Prompt → Audit Log            │
├─────────────────────────────────────────────────────────┤
│                   LLM Providers                          │
│  Anthropic | OpenAI | DashScope | Ollama | DeepSeek     │
│  RetryPolicy + CircuitBreaker + RateLimiter             │
└─────────────────────────────────────────────────────────┘
```

### 工具注册机制

```python
# 所有内置工具统一注册为 ValidatedTool + GatewayPolicy
BUILTIN_TOOLS = {
    # 文件操作
    "ReadFile":      ValidatedTool("ReadFile",      read_file,      ReadFileSchema),
    "EditFile":      ValidatedTool("EditFile",      edit_file,      EditFileSchema),
    "WriteFile":     ValidatedTool("WriteFile",     write_file,     WriteFileSchema),
    "ListFiles":     ValidatedTool("ListFiles",     list_files,     ListFilesSchema),
    "SearchContent": ValidatedTool("SearchContent", search_content, SearchSchema),
    # Shell
    "Bash":          ValidatedTool("Bash",          run_bash,       BashSchema),
    # Git
    "GitStatus":     ValidatedTool("GitStatus",     git_status,     GitStatusSchema),
    "GitCommit":     ValidatedTool("GitCommit",     git_commit,     GitCommitSchema),
    # ...
}

# from_config 编译时自动注入
tools = {**BUILTIN_TOOLS, **_compile_mcp_tools(cfg), **overrides.get("tools", {})}
tools = {name: gateway.wrap(tool) for name, tool in tools.items()}
```

---

## 五、可行性评估总结

### 分阶段实施路线

| 阶段 | 内容 | 工作量 | 产出形态 |
|------|------|--------|----------|
| **MVP** | 文件工具 + Shell 增强 + Git 封装 + 流式 CLI | ~10 天 | 可用的编程助手 CLI |
| **V1** | + 代码搜索 + 测试运行 + 任务管理 + 权限 UI | ~12 天 | 对标 Claude Code 核心功能 |
| **V2** | + Hook 系统 + Notebook + Web 工具 + 项目配置 | ~10 天 | 完整个人助手 |
| **V3** | + IDE 插件 + Web UI + 多 Agent 协作面板 | ~20 天 | 产品化 |

### 核心优势（已有基础设施可复用）

| 已有模块 | 复用于 | 节省工作量 |
|----------|--------|-----------|
| `ToolGateway` 5 级风险分类 | 所有工具的权限管控 | ~5 天 |
| `SandboxedTool` 进程隔离 | Shell/Code 执行安全 | ~3 天 |
| `IsolatedWorkspace` Git Worktree | 子 Agent 文件隔离 | ~4 天 |
| `AsyncExecutor` + `CancellationToken` | 异步执行 + 取消 | ~6 天 |
| `LLMAdapter` 多 Provider | 模型灵活切换 | ~3 天 |
| `RetryPolicy` + `CircuitBreaker` | 工具调用弹性 | ~2 天 |
| `ValidatedTool` + Pydantic | 工具输入校验 | ~2 天 |
| `ContextManager` | 长会话上下文管理 | ~3 天 |
| `TokenBudget` | 成本控制 | ~1 天 |
| `RateLimiter` | API 调用限流 | ~1 天 |
| MCPServer/MCPTool | 第三方工具生态 | ~5 天 |

**已有基础设施可节省约 35 天工作量。**

### 核心风险

| 风险 | 影响 | 缓解策略 |
|------|------|----------|
| 文件编辑精度 | EditFile 的字符串匹配不唯一 → 误编辑 | 编辑前备份、唯一性校验、diff 预览 |
| 安全性 | Agent 可执行任意命令 → 破坏系统 | ToolGateway 已有 50+ 规则；增加 path ACL |
| 性能 | 大项目文件搜索慢 | 依赖 ripgrep (rg) 而非纯 Python |
| LLM 成本 | 长会话 token 爆炸 | TokenBudget 已实现；ContextManager 已实现 |
| macOS 沙盒 | POSIX rlimit 在 macOS 部分失效 | 已有 monkey-patch fallback；可升级到 sandbox-exec(1) |

### 结论

**可行性: 高。**

lambdagentpaas 的 Lambda 演算架构天然适合构建工具组合型助手：
- 每个工具是一个 Lambda 项 (`λx. tool(x)`)
- 工具组合是函数组合 (`>>`)
- ReAct 循环是 Y 组合子
- 权限控制是依赖类型 (`Guard`)

Phase 1-4 已经建好了异步执行、流式输出、取消机制、重试弹性、安全网关、文件隔离等核心基础设施。**剩余工作主要是"填充工具实现"而非"搭建框架"**——这是最有利的位置。

MVP（文件工具 + Shell + Git + 流式 CLI）预计 **10 天**可交付可用的编程助手原型。