Claude-Code-python 前端改造项目工作流程详解

文章目录

• • 1. 项目概述
  • 2. 完整流程（用户输入 → 最终输出）
  • • 第 1 步：入口点与初始化 (`src/tui/app.py`)
    • 第 2 步：用户输入处理
    • 第 3 步：查询执行 (`src/tui/query.py`)
    • 第 4 步：引擎核心 (`src/core/engine.py`)
    • 第 5 步：LLM 客户端 (`src/core/llm.py`)
  • 3. 提示词构建逻辑
  • • 系统提示 (`src/core/context.py`)
    • 计划模式提示注入
  • 4. 工具选择与执行机制
  • • 工具基类 (`src/core/tool.py`)
    • 工具注册与模式
    • 工具执行流程 (`src/core/engine.py`)
  • 5. 代码文件与关键函数参考
  • 6. 示例用户旅程
  • 7. 技能系统
  • • 技能发现与注册
    • 技能提示注入
    • 内置技能示例
  • 8. 记忆系统层级结构
  • • 8.1 存储层（底层）
    • 8.2 提取层（实时层）
    • 8.3 整合层（梦境层）
    • 表格转换结果
    • 8.4 访问层（接口层）
  • 9. 上下文压缩系统层级结构
  • • 9.1 监控层
    • 9.2 拆分层
    • 9.3 处理层
    • 9.4 压缩层
    • 9.5 重组层
  • 10. 记忆与压缩系统协作关系
  • • 维度对比表格
  • 11. 工作模式总结
  • • 正常工作模式
    • 计划模式

本文档对
claude-code-python 项目架构进行全面剖析，重点关注用户输入在系统中的完整流转过程。完整流程：

页面设计：

1. 项目概述

claude-code-python 是一个用 Python 构建的极简 claude-code AI 编程助手。在节省token方面，做了改造，解决用户输入你好，就要花几w token的问题，项目具有以下特性：

• 基于 prompt_toolkit 和 Rich 的交互式命令行界面（TUI）

• 支持与大语言模型（Anthropic Claude / OpenAI）进行工具化交互

• 计划模式，用于实现前探索

• 带"梦境"整合的记忆系统

• 伙伴（buddy）陪伴功能

• 成本追踪与会话管理

2. 完整流程（用户输入 → 最终输出）

第 1 步：入口点与初始化 (src/tui/app.py)

应用从 app.py:107 的 main() 函数启动。它会：

第 2 步：用户输入处理

在交互式 REPL 中：

• 用户通过 bordered_prompt() 输入内容 (app.py:483-490)

• 使用 parse_input() 解析输入 (app.py:634)

• 如果是命令（/help、/buddy 等），通过 parse_command() 和 handle_command() 处理 (app.py:537-585)

• 否则，进入 run_query() 流程 (app.py:634)

第 3 步：查询执行 (src/tui/query.py)

run_query() (query.py:21-145) 协调整个回合：

• 设置 EscListener 用于取消操作

• 启动加载指示器

• 调用 engine.submit(user_input) 并遍历事件：

  • "text": 通过 StreamingMarkdown 流式输出到控制台
  • "waiting": 显示加载指示器
  • "tool_call": 预览工具调用
  • "tool_executing": 更新加载指示器
  • "tool_result": 显示成功/失败状态

第 4 步：引擎核心 (src/core/engine.py)

Engine.submit() (engine.py:195-432) 是主循环：

第 5 步：LLM 客户端 (src/core/llm.py)

LLMClient (llm.py:112-226) 处理 API 通信：

• 同时支持 Anthropic 和 OpenAI 提供商

• stream_messages() 返回 _AnthropicStream 或 _OpenAIStream

• 将响应标准化为统一格式

3. 提示词构建逻辑

系统提示 (src/core/context.py)

build_system_prompt() (context.py:288-321) 组装以下部分：

计划模式提示注入

当处于计划模式时 (features/plan.py)：

• PlanModeManager.enter() (plan.py:110-178) 保存原始状态

• 将 get_plan_mode_section() 注入到系统提示中 (plan.py:166-168)

• 切换到只读工具 + 计划工具

4. 工具选择与执行机制

工具基类 (src/core/tool.py)

所有工具都继承自抽象 Tool 类 (tool.py:13-41)：

class Tool(ABC):
@property
@abstractmethod
def name(self) –> str: ...

@property
@abstractmethod
def description(self) –> str: ...

@property
@abstractmethod
def input_schema(self) –> dict: ...

@abstractmethod
def execute(self, **kwargs) –> ToolResult: ...

工具注册与模式

• 工具在 app.py 中通过 _build_tools_for_mode() 注册

• 每个工具的 to_api_schema() 转换为 LLM 兼容格式

• 模式包含 name、description、input_schema

工具执行流程 (src/core/engine.py)

5. 代码文件与关键函数参考

6. 示例用户旅程

让我们通过一个简单的交互来完整走一遍流程：

7. 技能系统

技能（Skills）是预定义的专业能力，用于处理特定类型的任务。

技能发现与注册

• 在 app.py:155-158 初始化：
  • register_bundled_skills() 注册内置技能
  • discover_skills(cwd) 发现项目/用户技能
  • build_skills_prompt_section() 构建技能提示部分

技能提示注入

技能信息会被添加到系统提示中（app.py:174-175），使 LLM 了解可用的专业能力。

内置技能示例

项目包含多个预定义技能：

• LifeWisdomGuide: 基于 100+ 经典生活故事的逆向思维与处世智慧
• ai-life-post-writer: 撰写贴近生活的 AI 个人故事帖子
• frontend-design: 创建高质量的前端界面

8. 记忆系统层级结构

记忆系统采用 4 层架构，基于 src/features/memory.py 实现：

8.1 存储层（底层）

文件系统结构：

• 每日日志：logs/YYYY/MM/YYYY-MM-DD.md – 追加式时间戳记录
• 记忆索引：MEMORY.md – 不超过 200 行的索引文件，只包含链接+简短描述
• 结构化记忆文件：*.md – 带 frontmatter 的记忆文件（name/description/type）
• 会话持久化：sessions/SESSION_ID.jsonl – JSONL 格式的完整会话记录

关键函数：

• ensure_memory_dir() – 创建目录结构
• daily_log_path() – 生成每日日志路径
• save_session() / load_session() – 会话持久化

8.2 提取层（实时层）

实时记忆捕获：

• <memory> 标签提取：extract_memory_tags() 自动从 LLM 响应中提取
• 追加机制：append_to_daily_log() 将提取的内容时间戳化后追加到当日日志

在 app.py 中的集成（第 688-690 行）：

# Post-turn: extract <memory> tags
text = engine.last_assistant_text()
for mem in extract_memory_tags(text):
append_to_daily_log(memory_dir, mem)

8.3 整合层（梦境层）

4 阶段梦境整合流程：

表格转换结果

并发控制：

• 锁文件：.consolidate-lock – 记录持有者 PID
• 锁过期：1 小时后自动回收
• 扫描节流：10 分钟内不重复扫描会话

自动触发条件（should_auto_dream()）：

• 时间 ≥ min_hours（默认 24 小时）
• 新会话数 ≥ min_sessions（默认 5 个）

8.4 访问层（接口层）

系统提示注入：build_memory_system_section() – 将记忆系统指令和 MEMORY.md 内容注入到系统提示中

4 种记忆类型：

命令接口：

• /dream – 手动触发梦境整合
• /remember <text> – 手动追加记忆
• /memory – 显示当前 MEMORY.md

9. 上下文压缩系统层级结构

上下文压缩系统采用 5 层架构，基于 src/features/compact.py 实现：

9.1 监控层

阈值判断：

关键函数：

• estimate_tokens() – 粗略估算（字符数 / 4）
• should_compact() – 判断是否需要压缩（优先用 API 返回的实际 token 数）

在 app.py 中的集成（第 595-605 行）：

# Auto-compact when approaching token limits
if should_compact(engine.get_messages(), model=app_config.model,
last_input_tokens=cost_tracker.last_input_tokens):
console.print("[dim]Auto-compacting conversation…[/dim]")
try:
new_msgs, _ = compact_service.compact(...)
engine.set_messages(new_msgs)
...

9.2 拆分层

消息智能拆分（_split_recent()）：

拆分逻辑：

• 从后往前遍历，累加保留的消息和 token
• 达到双约束后停止
• 如果切分点落在纯 tool_result 的用户消息上，往前多切一条（包含 tool_use）

9.3 处理层

预处理操作：

9.4 压缩层

LLM 摘要生成：

固定提示结构（COMPACT_PROMPT）：

系统提示（COMPACT_SYSTEM）：

• “你是一个对话摘要器。按照用户要求的格式生成结构化、详细的摘要。”

9.5 重组层

新消息列表构建：

[用户：摘要消息]
↓
[助手：确认消息]
↓
[近期保留的消息（6条+）]

摘要消息格式：

[This is a summary of the conversation so far — the original messages have been compacted to save context space.]

[结构化摘要内容]

10. 记忆与压缩系统协作关系

维度对比表格

11. 工作模式总结

正常工作模式

计划模式