上下文管理

wescode 的上下文管理系统决定了 AI 能"看到"哪些信息。通过精准的上下文组装，AI 能更好地理解你的代码和意图，给出更准确的回答和建议。

@ 引用系统

概述

在 Chat 面板中使用 @ 符号引用各种上下文资源：

@file         — 引用文件
@folder       — 引用文件夹
@symbol       — 引用代码符号（函数、类、变量等）
@web          — 搜索网络
@docs         — 搜索文档
@git          — 引用 Git 信息
@terminal     — 引用终端输出
@problems     — 引用当前问题列表

文件引用

# 引用整个文件
@user_service.go 这个文件的 CreateUser 方法有什么问题？

# 引用多个文件
@user_handler.go @user_service.go 这两个文件的数据流是怎样的？

# 引用文件中的特定行范围
@user_service.go:45-80 优化这段代码

符号引用

# 引用函数
@CreateUser 这个函数的参数设计合理吗？

# 引用类型
@UserService 这个 struct 应该拆分成更小的模块吗？

# 引用接口
@Repository 所有实现这个接口的类型有哪些？

文件夹引用

# 引用整个目录
@internal/handler/ 这些 handler 的错误处理模式一致吗？

# 引用项目结构
@src/ 分析一下项目的目录结构

Git 引用

# 引用最近的变更
@git:changes 审查我的未提交变更

# 引用特定分支的差异
@git:diff main 与 main 分支相比有什么变化？

# 引用提交历史
@git:log 最近10次提交做了什么？

文件卡片

什么是文件卡片

文件卡片是 wescode 的上下文管理单元。当你通过 @ 引用文件时，AI 不是简单地读取整个文件内容，而是创建一个文件卡片，其中包含：

文件元信息：路径、语言、大小、最近修改时间
结构摘要：文件中的函数、类型、接口列表
关键内容：与当前问题最相关的代码片段
依赖关系：文件的导入和被导入关系

文件卡片的优势

节省 Token：不需要发送整个文件内容
聚焦相关：只包含与问题相关的部分
可重生：文件变更后卡片自动更新
上下文感知：根据不同问题展示不同的文件切面

自动文件卡片

wescode 在以下场景自动创建文件卡片：

编辑器中当前打开的文件
Chat 中通过 @ 引用的文件
CKG 分析后发现与问题相关的文件
错误诊断时涉及的文件

代码片段引用

选中引用

选中代码后在 Chat 中提问，选中的代码会自动作为上下文：

1. 在编辑器中选中一段代码
2. 按 Ctrl+L 打开 Chat
3. 输入问题 — 选中的代码自动包含在上下文中

精确引用

使用 @ 精确引用代码中的特定部分：

@ValidateEmail 函数中，为什么不检查 @ 符号后面是否有域名？

@UserService.CreateUser:45-60 这段错误处理可以简化吗？

引用终端输出

@terminal 帮我分析刚才的编译错误

@terminal:last 最后一条命令的输出是什么意思？

引用问题列表

@problems 当前有哪些问题需要修复？优先修复哪些？

上下文窗口

上下文窗口概念

AI 模型有固定的上下文窗口大小（以 Token 数量计算）。wescode 需要在有限的窗口中合理分配空间：

┌─────────────────────────────────────┐
│ 系统提示词（技能、Agent 配置等）      │ ~10%
├─────────────────────────────────────┤
│ 项目上下文（CKG 摘要、文件卡片）     │ ~30%
├─────────────────────────────────────┤
│ 对话历史（之前的对话内容）           │ ~40%
├─────────────────────────────────────┤
│ 当前问题（用户输入 + @ 引用）        │ ~20%
└─────────────────────────────────────┘

上下文优先级

当上下文超出窗口大小时，wescode 按以下优先级裁剪：

最高：当前用户输入和显式 @ 引用
高：当前打开的文件（焦点文件）
中：CKG 分析的相关文件
中：最近的对话历史
低：较早的对话历史
最低：项目级别的背景信息

查看上下文状态

在 Chat 面板中可以查看当前上下文的使用情况：

# 点击 Chat 面板底部的 Token 计数器
# 会展开显示上下文详情：
#
# 上下文使用：45,200 / 128,000 tokens (35%)
# ├── 系统提示词：5,000 tokens
# ├── 技能(3)：8,200 tokens
# ├── 文件卡片(5)：12,000 tokens
# ├── 对话历史(8轮)：15,000 tokens
# └── 当前输入：5,000 tokens

上下文压缩

长对话会自动触发上下文压缩（CognitiveSettlement）：

早期对话内容被压缩为摘要
关键决策和代码变更保留
压缩对用户透明，不影响使用体验

最佳实践

高效使用 @ 引用

推荐做法：

# ✅ 精确引用相关文件
@user_service.go @user_repository.go
CreateUser 函数的错误处理需要改进

# ✅ 引用符号而非整个文件
@ValidatePassword 这个函数需要支持更多密码规则

# ✅ 结合多种引用
@git:changes @problems 这次变更引入了什么新问题？

避免做法：

# ❌ 引用过多文件（浪费上下文空间）
@file1 @file2 @file3 @file4 @file5 @file6 @file7 @file8
帮我看看代码

# ❌ 不提供上下文（AI 无法理解意图）
修复 Bug

# ❌ 在长对话中重复引用相同文件
（AI 已经有这些文件的上下文了）

长对话管理

# 对话太长时，建议开启新会话
# 每个会话聚焦一个具体任务

# 好的会话节奏：
1. 明确目标："我要重构 UserService"
2. 提供上下文：@user_service.go
3. 逐步推进：先分析 → 制定计划 → 执行 → 验证
4. 任务完成后开启新会话

利用 CKG 自动上下文

wescode 的 CKG 会自动分析你的代码并提供相关上下文：

# 当你在编辑 user_handler.go 时
# AI 自动"看到"：
# - user_handler.go 的完整内容
# - 被调用的 user_service.go 中的相关函数
# - 相关的类型定义
# - 相关的测试文件

# 你只需要直接提问，不必手动 @ 所有文件
"CreateUser handler 的错误码应该返回什么？"

上下文清理

# 当 AI 的回答不准确时，可能是上下文混乱
# 尝试：
1. 开启新的 Chat 会话（Ctrl+Shift+N）
2. 只引用最相关的文件
3. 清晰描述问题和期望

注意事项

@ 引用的文件内容会发送到 AI 模型，注意不要引用包含敏感信息的文件
引用过多文件会消耗上下文窗口，降低 AI 回答质量
CKG 索引完成后，自动上下文效果更好（查看状态栏索引进度）
长时间不相关的对话历史会被压缩，重要信息建议记录在代码注释或文档中
文件卡片是动态的，文件修改后下次引用会自动更新