1. 项目概述：为什么我们需要一个“会学习”的AI助手？

如果你用过Claude Code、Cursor或者任何宣称能理解你意图的AI编程助手，大概率经历过这样的挫败感：你满怀期待地告诉它“请按照我的风格重构这段代码”，结果它生成的东西要么过于啰嗦，要么完全跑偏，跟你习惯的简洁、模块化的写法相去甚远。然后你不得不停下来，花时间写一份长长的 CLAUDE.md 或 .cursorrules 文件，试图用文字去描述你那套复杂、微妙且时常变化的编码习惯。这本身就是一个悖论—— 我们往往最不擅长准确描述自己的行为模式 。

这就是Habitus要解决的核心问题。它不是一个教你如何写配置文件的工具，而是一个 静默的观察者与解读者 。它的理念非常直接：与其让你费力地、静态地告诉AI“我是谁”，不如让AI通过观察你日常工作的“数字痕迹”——你如何创建文件、如何编辑代码、如何组织目录、如何阅读文档——来自动学习并构建你的行为画像。这就像一位资深的结对编程伙伴，不需要你开口，仅仅通过观察你的键盘敲击和屏幕切换，就能逐渐摸清你的套路。

这个项目源自香港大学的FileGram研究框架，其学术基础相当扎实。它提出了一个六维度的行为模型（L/M/R分类）和三通道（程序性、语义性、情景性）的分析引擎，不是简单统计文件操作次数，而是结合统计特征与大语言模型（LLM）的语义理解，从底层文件事件中提炼出高层次的、可解释的工作风格。最终，它能自动生成那些你曾手动撰写的配置文件（如 CLAUDE.md ），让任何AI助手在与你合作时，都能“本能地”适应你的节奏。

简单来说，Habitus的目标是让AI适应人，而不是让人去适应AI。对于任何厌倦了反复调教AI、渴望获得真正个性化、上下文感知的辅助体验的开发者来说，这无疑是一个值得深入探索的方向。接下来，我将拆解它的核心设计、具体实现，并分享从部署到深度使用过程中的一系列实操心得与避坑指南。

2. 核心设计哲学：从“数字痕迹”到“行为智能”

Habitus的聪明之处在于，它承认人类行为的复杂性无法通过简单的规则或问卷来捕获。它的整个架构设计都围绕着“ 自底向上、数据驱动 ”这一核心哲学展开。我们通常认为的“工作风格”，其实是无数个微观决策（先读哪个文件、函数命名用驼峰还是下划线、注释写多详细）在时间维度上涌现出的宏观模式。Habitus做的就是捕捉这些微观事件，并通过一套严谨的流程将其“翻译”成可用的知识。

2.1 三通道输入：全方位捕捉工作现场

大多数行为分析工具只盯着一个数据源，比如代码提交历史（Git），但这丢失了大量实时、细粒度的上下文。Habitus同时从三个互补的通道收集信号，构建了一个立体的观察视角：

1. 文件系统监视器 ：这是最基础的通道。它利用操作系统级钩子（如macOS的FSEvents或Linux的inotify）实时监听所有文件操作。关键不在于它“看到”了你修改了 main.py ，而在于它记录了一系列元数据：你是先“读”了 utils.py 再“写” main.py 吗？两次编辑间隔了多久？你创建新目录的深度是几层？这些看似枯燥的日志，是构成你“程序性记忆”（Procedural Memory）的原材料。

2. 内容差异分析 ：这是Habitus的杀手锏之一。它不仅仅知道文件变了，还知道“怎么变的”。通过维护文件的影子副本（Shadow Copies）和内容寻址存储，它能计算出每次编辑的精确差异（Unified Diff）。这为“语义性记忆”（Semantic Memory）提供了燃料。LLM可以分析这些差异：你是在重写整个函数，还是只调整了参数？你新增的注释是解释复杂逻辑，还是简单的TODO？你的编辑是倾向于扩充细节，还是精简表达？这直接映射到行为模型中的“生产”和“迭代”维度。

3. 屏幕录制与分析 ：这是目前路线图中的功能，但设计思路非常前瞻。它计划通过视觉语言模型（VLM）分析屏幕录像，提取出文件操作序列、阅读模式（例如，是快速滚动浏览还是长时间凝视某段代码）、甚至在不同应用（IDE、浏览器、终端）间的切换习惯。这能捕捉到纯粹文件事件无法反映的“视觉工作流”，比如你是否有同时参考多个文档窗口的习惯。

实操心得：隐私与性能的平衡 看到“屏幕录制”，很多人会心头一紧。Habitus在设计上强调了“隐私优先”：所有原始数据（包括录像）都在本地处理，只有提取出的结构化事件（如“用户在VS Code和Chrome之间切换了3次”）才会被存储或用于分析。在实际部署时，务必在配置文件中确认相关开关，并根据自身舒适度选择启用哪些通道。对于性能，文件监视和内容差异计算会有一定开销，建议初期先针对关键项目目录进行观察，避免同时监控整个硬盘。

2.2 六维度行为模型：将行为量化为可操作的标签

收集了海量事件后，如何从中提炼出有意义的描述？Habitus没有使用黑箱神经网络直接输出结果，而是定义了一个可解释的 六维度L/M/R模型 。这个模型就像一把尺子，在每个维度上对你的行为进行定位：

维度	名称	衡量内容	光谱（L / M / R）
A	消费模式	你如何探索和阅读文件	顺序性 ←→ 目标性 ←→ 广度优先
B	生产模式	你的输出风格和详细程度	全面详尽 ←→ 平衡适中 ←→ 极简主义
C	组织模式	你如何构建目录和命名文件	深度嵌套 ←→ 灵活适应 ←→ 扁平结构
D	迭代模式	你如何修订和优化工作	增量小改 ←→ 平衡调整 ←→ 推倒重写
E	整理模式	你如何管理工作区整洁度	选择性清理 ←→ 实用主义 ←→ 保留一切
F	跨模态模式	你是否使用视觉材料	重度视觉依赖 ←→ 平衡使用 ←→ 纯文本

这个分类为何有效？ 因为它基于可观测的指标。例如，判断“组织模式”时，系统会统计你创建目录的平均深度、文件路径的长度方差等。如果你频繁创建 src/utils/helpers/validation/ 这样的路径，你就会被归类为“深度嵌套（L）”；如果你的项目根目录下总是堆满文件，那你就是“扁平结构（R）”。LLM的角色不是凭空猜测，而是基于这些统计特征，结合事件序列的上下文，给出最终的L/M/R分类，并生成一句像“该用户倾向于创建超过三层的目录结构，并使用日期前缀进行版本管理”这样的自然语言描述。

2.3 记忆架构：像维基百科一样积累行为知识

这是Habitus区别于简单统计工具的核心。它没有将每次分析视为独立任务，而是构建了一个持续进化的、类似维基百科的持久化记忆系统—— .habitus 目录。这不是一个简单的数据库，而是一组相互链接的Markdown文档（如 organization.md , editing.md ），由LLM在每次工作会话后增量更新。

关键在于“增量”和“无重算” 。传统RAG（检索增强生成）每次查询都要重新检索和合成碎片信息。而Habitus的记忆是“编译好”的知识资产。例如：

• 第1次会话 ：你整理了项目，创建了深层目录。 organization.md 被更新：“观察到用户偏好使用3层以上的目录结构。”
• 第5次会话 ：模式被再次确认。 organization.md 被强化：“深层嵌套模式稳定（5/5次会话，100%置信度）。”
• 第12次会话 ：你突然将一个项目扁平化。 organization.md 会记录：“⚠️ 行为漂移警告：在第12次会话中观察到扁平化组织，与已建立的深层嵌套模式矛盾。持续监控中。”

这种设计使得知识能够“复利增长”，并且能明确标识出你行为的转变点，这对于捕捉习惯的演化至关重要。

3. 从零部署与核心配置实战

理解了设计理念，我们进入实战环节。Habitus的安装和初步配置相对简单，但一些细节配置决定了它是否能稳定、高效、符合预期地运行。

3.1 环境准备与安装

项目推荐使用 uv 作为Python包管理器和运行器，这能很好地处理依赖隔离。如果你的系统没有，建议先安装它。

# 安装 uv (以macOS/Linux为例)
curl -LsSf https://astral.sh/uv/install.sh | sh
# 安装后重启终端或 source ~/.bashrc (或对应shell的配置文件)

# 克隆项目仓库
git clone https://github.com/choiszt/Habitus.git
cd Habitus

# 使用uv创建虚拟环境并安装依赖（开发模式）
uv pip install -e .

如果要从PyPI直接安装稳定版（可能功能稍旧），可以：

uv pip install habitus

注意事项：Python版本与依赖冲突 Habitus要求Python 3.10+。使用 uv 能最大程度避免依赖地狱。如果遇到诸如 watchdog 或 sqlalchemy 等底层库的安装错误，通常是系统环境问题。在纯净的虚拟环境中操作是最佳实践。另外，如果计划使用本地LLM（如通过Ollama），需要额外确保Ollama服务已安装并运行。

3.2 核心配置文件详解

安装后，在用户主目录或项目根目录创建 habitus.yaml 配置文件，这是控制其行为的“大脑”。我们来逐部分解析：

# habitus.yaml 示例与详解
watch_dirs:
  - ~/projects/my-ai-app  # 监控你的主要项目
  - ~/Documents/design-specs  # 也可以监控设计文档目录

ignore_patterns:
  - "**/.git/**"           # 必须忽略版本控制目录
  - "**/node_modules/**"   # 忽略依赖库，噪音极大
  - "**/__pycache__/**"    # 忽略Python缓存
  - "**/*.log"             # 忽略日志文件
  - "**/tmp/**"            # 忽略临时目录
  - "*.DS_Store"           # 忽略macOS系统文件

llm:
  provider: ollama         # 可选: openai, anthropic, azure, ollama
  model: gemma3:1b         # 如果使用Ollama，指定本地模型名
  # 若使用OpenAI:
  # provider: openai
  # model: gpt-4.1
  # api_key: ${OPENAI_API_KEY} # 建议从环境变量读取

profiling:
  snapshot_interval: 300   # 每300秒（5分钟）进行一次工作区快照
  consolidation_interval: 10 # 每10次会话后进行一次跨会话整合分析
  dedup_window: 2.0        # 2秒内的连续编辑事件去重为一个逻辑编辑
  min_session_duration: 60  # 少于60秒的活动不计为一个独立会话

export:
  auto_update: true        # 行为画像更新时，自动重写导出文件
  formats: [claude, cursor, json] # 导出的格式
  output_dir: .            # 导出文件存放目录（通常放在项目根目录）
  include_confidence: true # 在导出文件中包含置信度标记（如“通常”、“有时”）

配置要点解析：

• watch_dirs ：不宜过多。从一个核心项目开始，避免初期数据过杂。监控 ~/projects 这样的父目录可能产生大量无关事件。
• ignore_patterns ：这是 性能与准确性的关键 。像 node_modules 、 .git 、 __pycache__ 这类目录变动频繁且与你的工作习惯无关，必须忽略，否则会产生巨量噪音，拖慢分析速度并污染行为画像。
• llm ：对于隐私要求高的用户， Ollama等本地模型是首选 。虽然小模型（如 gemma3:1b ）的分析深度可能不如GPT-4，但足以完成分类和描述任务，且所有数据不出本地。如果追求更精准的语义分析，可以考虑更大的本地模型（如 qwen2.5:7b ），但这需要更强的硬件支持。
• dedup_window ：这个参数很实用。我们编码时经常快速连续地敲击保存，这应被视为一次“编辑意图”。2.0秒的窗口能很好地合并这些微操作。
• auto_update ：建议开启。这样你的 CLAUDE.md 总能保持最新，AI助手能实时感知你风格的变化。

3.3 启动观察与初步分析

配置完成后，就可以开始收集数据了。

# 在终端中，进入你想要监控的项目目录
cd ~/projects/my-ai-app

# 启动Habitus观察器，指定当前目录
uv run habitus watch .

# 或者直接指定路径
uv run habitus watch ~/projects/my-ai-app

启动后，Habitus会作为后台进程运行。此时，你就像平时一样工作：编写代码、创建文件、移动资源、撰写文档。让它安静地收集几个小时或几天的数据。

收集一段时间后，可以查看初步分析结果：

# 生成并查看当前的行为画像摘要
uv run habitus profile

# 查看更详细的分析报告，包括每个维度的得分和证据
uv run habitus profile --verbose

# 如果之前已有FileGram格式的events.json文件，可以直接分析
uv run habitus analyze ./path/to/session/events.json

第一次运行 profile 命令时，如果数据量不足，它可能会提示需要更多会话。通常，完成3-5个有明显工作内容的会话（每次持续30分钟以上）后，就能生成一份有参考价值的初步画像。

4. 深度使用：解读画像与导出应用

当Habitus积累了足够数据后，产生的行为画像和导出文件才是价值的体现。我们需要学会解读它，并有效地将其应用于AI助手。

4.1 解读行为画像报告

运行 habitus profile --verbose 会输出一份详细报告。它可能长这样：

=== Habitus Behavioral Profile (Session 3-15 consolidated) ===

Confidence: High (13 sessions over 12 days)

Dimensions (L/M/R):
[A] Consumption: M (Balanced) - You often start reading from entry points but quickly jump to specific functions when needed.
[B] Production: L (Comprehensive) - Your edits frequently add detailed comments and expand function documentation. New files often include extensive header blocks.
[C] Organization: L (Deeply Nested) - Strong preference for 3+ level directory structures (e.g., `src/features/auth/controllers/`). File names are descriptive with occasional date prefixes.
[D] Iteration: L (Incremental) - You make frequent, small commits. Diffs are typically under 50 lines, focusing on parameter tweaks and logic refinements.
[E] Curation: M (Pragmatic) - You clean up temporary debug files but leave older versions in a `_archive` folder.
[F] Cross-Modal: R (Text-only) - No evidence of incorporating diagrams or visual assets in the monitored directories.

Key Behavioral Signatures:
- **Sequential Explorer**: You typically read `README.md` first, then `src/main.py`.
- **Documentation-Driven Development**: High correlation between creating a `.md` file and subsequent code edits in related modules.
- **Safe Deleter**: You rarely use `rm` directly; moved files often appear in a `trash` or `old` directory first.

如何利用这份报告？

• 确认与反思 ：报告是否准确反映了你的自我认知？有时它会揭示你自己都没意识到的习惯（比如“安全删除者”模式）。
• 针对性优化 ：如果你发现自己属于“重度视觉依赖（L）”但项目缺少图表，或许可以有意地开始使用Mermaid或Excalidraw，让Habitus学习并最终让AI助手也倾向于建议图表。
• 团队协作 ：分享报告可以帮助团队成员相互理解工作风格，减少协作摩擦。

4.2 导出与应用到AI助手

这是最终的成果交付环节。Habitus可以将画像导出为多种AI助手能直接读取的格式。

# 导出为Claude Code使用的CLAUDE.md文件
uv run habitus export --format claude --output ./CLAUDE.md

# 导出为Cursor使用的.cursorrules文件
uv run habitus export --format cursor --output ./.cursorrules

# 导出为通用AI Agent的AGENTS.md文件
uv run habitus export --format agents --output ./AGENTS.md

# 导出为结构化JSON，用于其他工具集成
uv run habitus export --format json --output ./behavioral_profile.json

让我们看一下它可能生成的 CLAUDE.md 内容片段：

# 我的工作风格 (由Habitus自动生成)

## 代码与文件组织
- **深层嵌套偏好**：我习惯使用深度目录结构（通常3层或以上）来组织代码，例如 `src/domain/user/services/authentication.py`。请在与文件结构相关的建议中考虑这一点。
- **描述性命名**：我倾向于使用长而具描述性的文件名和变量名（如 `calculate_monthly_recurring_revenue` 而非 `calc_mrr`）。生成代码时请遵循此约定。
- **保留历史版本**：我经常将旧文件移动到 `_archive` 或 `old_versions` 目录，而不是直接删除。在建议重构或删除时，可以提议先移动。

## 开发与编辑习惯
- **增量迭代者**：我偏好进行小而频繁的更改。在提供代码建议时，请优先考虑可逐步应用的、模块化的重构方案，避免建议大规模、破坏性的重写。
- **文档先行**：我通常在编写新功能代码前，会先创建或更新相关的Markdown文档（`spec.md`, `api.md`）。当你发现我在编辑文档时，可以预见到后续相关的代码变更。
- **详尽的注释**：我为复杂的业务逻辑和公开API添加详细的注释。在生成代码时，请为关键函数和类包含清晰的文档字符串（Docstring）。

## 沟通与协作
- **文本为主**：在当前项目中，我主要依赖文本文件（代码、Markdown）。虽然不排斥图表，但较少主动创建。仅在逻辑极其复杂时，可以建议使用代码内联注释或简单的ASCII图表进行解释。

将这个文件放入你的项目根目录 ，Claude Code或支持该格式的AI助手在分析项目时就会读取它，并尝试调整其行为来匹配你的风格。例如，当你要求它“创建一个新的用户管理模块”时，它可能会自动建议一个符合你“深层嵌套”偏好的目录结构，并生成带有详细文档字符串的代码。

实操心得：导出文件的“磨合期” 最初生成的配置文件可能不完全准确，或者AI助手对其响应不完美。 不要期待立竿见影的完美适配 。这是一个迭代过程：

1. 观察 ：使用导出的配置工作几天。
2. 修正 ：如果AI助手的建议持续偏离你的真实偏好，可以手动微调 CLAUDE.md 文件。Habitus的自动更新不会覆盖你的手动修改（取决于配置），但你可以将手动调整视为对模型的“强化反馈”。
3. 再训练 ：在手动调整后继续工作，Habitus会学习你新的、更精确的行为模式，并在下一次整合更新时，将你的手动调整“吸收”进它的自动生成逻辑中。经过2-3个循环，匹配度会显著提升。

4.3 启动可视化仪表板

对于喜欢图形化分析的用户，Habitus提供了Web仪表板。

uv run habitus dashboard

执行后，通常在浏览器中打开 http://localhost:8420 。仪表板会展示：

• 雷达图 ：直观展示你在六个维度上的位置。
• 时间线 ：按会话展示行为事件，可视化你的工作节奏和模式。
• 漂移警报 ：如果检测到行为模式发生显著变化（如从“增量迭代”突然变为“推倒重写”），会在这里高亮提示。

仪表板对于宏观把握自己的习惯演变非常有帮助，尤其适合在尝试新的工作方法后，检验其是否真的改变了你的行为模式。

5. 高级技巧、问题排查与未来展望

5.1 高级使用技巧

1. 多工作区差异化配置 ：你可能有不同的项目类型（如前端React项目、后端API项目、数据分析Notebook）。你的工作风格在这些场景下可能不同。Habitus支持配置多个 watch_dirs ，但目前版本生成的是统一的全局画像。 变通方案 ：可以为不同类型的项目创建不同的配置文件（如 habitus.frontend.yaml , habitus.backend.yaml ），并分别运行独立的Habitus实例，指向不同的数据存储路径。这样就能生成针对特定场景的行为画像。

2. 利用 .habitus 记忆库进行自定义查询 ： .habitus 目录下的Markdown文件是纯文本，你可以直接阅读、编辑，甚至用脚本分析。例如，你可以写一个简单的脚本，提取 editing.md 中所有关于“注释”的描述，来量化自己添加注释的习惯变化。

3. 与CI/CD集成（实验性） ：你可以将 habitus export --format json 集成到你的CI流程中，将行为画像的JSON快照作为构件存档。这可以用于跟踪团队编码风格随时间的变化，或作为项目交接时的一份“开发者习惯说明书”。

5.2 常见问题与排查

Q1: Habitus进程占用CPU或内存过高。

• 原因 ：通常是因为监控了包含大量频繁变动文件（如 node_modules , log 目录）的路径。
• 解决 ：仔细检查并完善 habitus.yaml 中的 ignore_patterns 。使用 lsof 或 htop 命令确认Habitus正在监视的文件句柄数量。从一个更小、更干净的项目目录开始。

Q2: 导出的 CLAUDE.md 感觉泛泛而谈，不够具体。

• 原因 ：分析的数据量不足或过于单一。如果所有会话都是修bug，画像可能只反映了“调试模式”，而非全面的“开发风格”。
• 解决 ：确保收集了不同类型的工作会话（新功能开发、重构、文档编写、代码评审）。让Habitus观察你一个完整的工作周。同时，尝试使用更强大的LLM模型（如GPT-4）进行语义分析，可能会产生更深刻的洞察。

Q3: 行为画像看起来不准确，与我认知不符。

• 原因 ：可能是统计特征被异常值干扰，或LLM对某些行为模式的解读有偏差。
• 解决 ：首先，使用 habitus profile --verbose 查看具体是哪些事件被用作“证据”。检查这些事件是否具有代表性。其次，可以手动编辑 .habitus 记忆库中的相关Markdown文件，修正错误的描述。Habitus在后续整合时会考虑到这些手动修正。

Q4: 如何完全重置Habitus，重新开始收集数据？

• 解决 ：删除 ~/.habitus 目录（存储全局记忆和配置缓存）以及项目目录下由Habitus生成的任何导出文件（如 CLAUDE.md ）。然后从干净的配置重新启动 watch 。注意，这会丢失所有历史学习数据。

5.3 项目生态与未来展望

Habitus基于FileGram研究框架，这意味它有着坚实的学术背景和清晰的演进路线。从路线图看， 屏幕录制通道 和 更精细的漂移检测 是即将到来的重磅功能。前者将真正实现“多模态”行为捕捉，后者能让你像拥有健康监测手表一样，感知自己工作习惯的微妙变化。

此外， 与特定IDE/编辑器的深度集成 （如Claude Code扩展、Cursor插件）也值得期待。届时，行为学习与AI辅助的反馈循环将更紧密，甚至可能实现实时、上下文相关的提示词微调。

我个人在实际使用中的体会是 ，Habitus最大的价值不在于它立刻能生成完美的配置文件，而在于它提供了一种全新的视角——让工具来主动理解人。它迫使我去反思自己的 workflows，那些我习以为常甚至不自知的操作，被量化、被分析，有时会带来“原来我是这样工作的”的顿悟。初期需要一些耐心去调教和磨合，但一旦它“上了道”，那种AI助手仿佛读懂了你的心思、给出的建议愈发贴切的感觉，会显著提升开发的心流体验和效率。它不再是一个需要你不断发出精确指令的机器，而逐渐像一个真正了解你偏好的合作伙伴。