Clude Code: 业界级本地编程代理 (Industry-Grade Local Code Agent)

Status (状态): Active Development (持续开发中)
Inspired by (灵感来源): Claude Code & Aider

Clude Code 是一个专注于本地化落地 (Local-First) 的编程代理 CLI。它通过一套闭环的 Agent 编排逻辑 (Orchestration)，使本地模型 (通过 llama.cpp) 能够理解代码库、规划任务、执行高精度补丁编辑、并进行审计追溯。

本仓库沉淀了从功能分析、架构设计到模块化实现的全过程文档与源码。

📖 技术白皮书与模块进度总览 (Technical Overview) (开发者必读)

1. 核心特性 (Key Features)

特性	说明	状态
本地优先 (Local-First)	深度集成 `llama.cpp` HTTP API，保护隐私，无须云端 Token。	✅ 已落地
精准编辑 (Patch Engine)	借鉴 Aider 的 `Search-Replace` 块逻辑，支持 `apply_patch` 与 `undo_patch`。	✅ 已落地
仓库感知 (Repo Map)	基于 `universal-ctags` 的符号拓扑，让 Agent 拥有全局架构视野。	✅ 已落地
语义 RAG (Vector Search)	集成 `LanceDB` + `fastembed`，支持对大规模代码库的异步索引与语义检索。	✅ 已落地
安全审计 (Audit Trace)	全量记录工具调用日志与执行轨迹，支持 Hash 级补丁完整性校验。	✅ 已落地
交互式修复 (Auto-Fix)	`doctor --fix` 能够自动诊断并跨平台安装 `rg`、`ctags` 等外部依赖。	✅ 已落地
可观测性 (Observability)	全面的性能指标监控、分布式追踪和性能分析功能。	✅ 已落地
性能监控	自动收集系统、应用和业务指标，支持 Prometheus 格式导出。	✅ 已落地
分布式追踪	基于 OpenTelemetry 标准的端到端追踪，支持采样和批量导出。	✅ 已落地
性能分析	CPU、内存、I/O 和函数级性能分析，支持装饰器和上下文管理器。	✅ 已落地

2. 快速开始 (Quick Start)

2.1 环境准备 (Prerequisites)

# 1. 创建环境 (Create Environment)
conda create -n clude_code python=3.11 -y
conda activate clude_code

# 2. 安装项目 (Install Package)
pip install -e ".[rag]"

# 3. 配置 LLM (Configure LLM)
$env:CLUDE_WORKSPACE_ROOT="D:\Work\AI\clude_code"
$env:CLUDE_LLM__BASE_URL="http://127.0.0.1:8899"
$env:CLUDE_LLM__API_MODE="openai_compat"

2.2 启动对话 (Start Chat)

# 1. 诊断环境 (Doctor)
clude doctor --fix

# 2. 初始化项目记忆 (Init Memory)
clude chat --select-model
/init

# 3. 启动 TUI (Start TUI)
clude chat --live --live-ui opencode

3. CLI 命令参考 (Command Reference)

完整参数说明请参考 clude --help。

3.1 `clude chat` (核心入口)

交互模式 (Interactive):
- clude chat --live --live-ui opencode: 推荐，多窗格 TUI。
- clude chat --live --live-ui enhanced: Claude Code 风格侧边栏。
非交互模式 (Non-Interactive):
- clude chat -p "Review code": 单次执行 (Print Mode)。
- clude chat -p --output-format json "...": 脚本集成模式。
会话管理 (Session Management):
- clude chat -c: 继续上一次会话 (Continue)。
- clude chat -r <session_id>: 恢复指定会话 (Resume)。

3.2 辅助命令 (Utility Commands)

clude tools: 查看可用工具清单 (Tools List)。
clude doctor: 环境诊断与修复 (Environment Check)。
clude models: 列出可用模型 (Models List)。

6. 文档导航 (Documentation Index)

本项目文档体系分为设计规范、进度报告与技术深挖三部分。

4.1 核心索引 (Core Index)

项目总览 (Overview): 完整的功能矩阵与架构图。
开发计划 (Roadmap): P0/P1/P2 迭代计划与审计结论。
模块进度 (Progress): 技术实现的计分卡与业界对比。

4.2 深度技术报告 (Deep Dive Reports)

业界 Code Agent 技术白皮书: 架构原理与最佳实践。
Agent 决策链路审计与评分: Trace ID、控制协议与重规划机制。
RAG 深度调优路线图: Hybrid Search 与 AST Chunking。
健壮性复盘报告: 系统稳定性分析。

5. 实现流程图 (Implementation Flow)

Core Implementation Flow

(注：动画展示了从 CLI 输入到 Agent 编排再到 LLM 反馈的完整闭环)