Skip to content

first-use.md

Latest commit

 

History

History
97 lines (59 loc) · 2.6 KB

first-use.md

File metadata and controls

97 lines (59 loc) · 2.6 KB
Raw

首次使用

面向第一次接入 ContextAtlas 的用户，目标是在几分钟内选择接入模式并跑通闭环。

第一步：选择接入模式

ContextAtlas 提供两种互斥接入模式：

  • cli-skill：通过终端命令行和 agent skill 集成，适合本地开发和脚本自动化
  • mcp：通过 MCP 协议接入 Claude Desktop、Cursor 等 MCP 客户端

两种模式的 setup 互斥——选择一种后，setup:local 只会写入对应模式的配置文件。

cli-skill 路径

1. 安装

npm install -g @codefromkarl/context-atlas

2. 初始化配置

contextatlas init
contextatlas setup:local --mode cli-skill
contextatlas health:full

写入文件：~/.contextatlas/.env、prompt docs（CLAUDE.md、AGENTS.md、GEMINI.md）、Codex CLI skill

不写入：MCP 配置文件

3. 配置 API 密钥

编辑 ~/.contextatlas/.env 填入 Embedding 和 Rerank 的 API 密钥。

4. 索引代码库

contextatlas index /path/to/your/project

5. 搜索

contextatlas search --repo-path /path/to/project --information-request "你的问题"

health:full 是 setup 后的推荐自检入口，会汇总索引、记忆、图谱、契约和 MCP 进程状态。

mcp 路径

1. 安装

npm install -g @codefromkarl/context-atlas

2. 初始化配置

contextatlas init
contextatlas setup:local --mode mcp

写入文件：~/.contextatlas/.env、MCP 客户端配置（Claude Desktop、Cursor、Gemini、Codex）、prompt docs、Codex MCP skill

如果只需要只读能力，可使用：

contextatlas setup:local --mode mcp --toolset retrieval-only

该模式仅暴露只读检索、图谱、契约和记忆读取工具，降低 MCP 客户端的工具选择负担。

如果是从旧版升级，先用 CLI 完成迁移检查：contextatlas health:graph 检查旧 graph schema，contextatlas health:full 汇总索引、记忆、图谱、契约和 MCP 状态。retrieval-only 不包含索引重建、长期记忆写入或 memory hub 修复入口。

3. 配置 API 密钥

编辑 ~/.contextatlas/.env 或在 MCP 客户端配置中通过 env 字段传递。

4. 重启 MCP 客户端

确认工具列表中出现 ContextAtlas 的工具。

重启后建议运行或触发一次 contextatlas health:full，确认本地配置和运行时状态正常。

5. 在对话中使用

直接在 MCP 客户端中使用 find_memory、codebase-retrieval 等工具。

更多参考