1. 为什么新手配 Archify 总在 Cursor 和 Claude Code 上翻车Archify 是一个把存量代码转成可检索、可解释架构地图的工具适合刚接手老项目、或者用 AI 结对编程但越写越乱的开发者。它能做什么简单说你给它一个代码仓库它输出模块依赖、调用链路、循环依赖这些结构化信息让 AI 在回答“这个函数该放哪”之前先知道“这个函数现在被谁调用”。适合谁适合那些用 Cursor 写代码飞快、但三周后改核心模块时不知道谁会挂的人。问题出在接入环节。Archify 本身不绑定模型它需要宿主环境提供两样东西文件系统访问权限和模型 API 通道。Cursor 和 Claude Code 的配置格式完全不同一个用 JSON一个用 TOML新手最容易在这两个文件里填错字段名或者把 Key 放错位置。更麻烦的是很多人把 Archify 当成普通插件以为装完就能跑结果遇到权限拒绝、上下文溢出、动态导入解析失败这三类报错卡在第一步就放弃了。我实测下来配置本身不复杂关键是知道每个字段对应什么、报错对应哪一层。下面按 Cursor 和 Claude Code 两条线给出可复制的配置骨架再统一走一遍连通性验证和排错。2. TaoToken 统一 Key 的前置准备Archify 在分析代码时需要把压缩后的依赖矩阵发给大模型生成摘要。这一步走的是 OpenAI 兼容接口所以你需要一个能同时给 Cursor 和 Claude Code 用的 API 通道。TaoToken 的作用就是提供这个统一入口一个 Key 覆盖两个宿主环境省得你在两个平台分别申请、分别记额度。先拿到 Key。打开 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentarchify_cursor_claudeutm_campaignrewrite 登录后创建一个 API Key复制保存。这个 Key 后面会填进 Cursor 的 settings.json 和 Claude Code 的 config.toml两处用的是同一个值。然后确认两件事。第一你的项目根目录下有没有 .archifyignore 文件没有就建一个语法和 .gitignore 一样先把 node_modules、dist、.env、*.key、secrets/ 这些排除掉。第二确认你用的模型名TaoToken 的模型列表在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentarchify_cursor_claudeutm_campaignrewrite 可以查到Archify 做架构摘要建议用上下文窗口大一点的模型比如 128k 以上的否则十万行项目会截断。注意Key 只填一次不要在两个配置文件里用不同的 Key否则排查问题时你会分不清是哪个通道出的错。3. Cursor 侧 settings.json 可复制骨架Cursor 的配置走 JSON路径在用户设置里。打开 Cursor按 CtrlShiftPMac 是 CmdShiftP输入 Open Settings (JSON)回车。你会看到一个 settings.json 文件把下面这段合并进去注意不要覆盖你已有的其他配置。{ cursor.ai.apiKey: 你的TaoTokenKey, cursor.ai.baseUrl: https://taotoken.net/api, cursor.ai.model: claude-3-5-sonnet, cursor.ai.maxTokens: 8192, cursor.ai.contextWindow: 128000, archify.enabled: true, archify.ignoreFile: .archifyignore, archify.scanDepth: 3, archify.outputFormat: html }逐字段说明。apiKey 填你刚才复制的 TaoToken Key。baseUrl 固定填 https://taotoken.net/api 注意结尾不要加斜杠加了会 404。model 填你要用的模型名Archify 做架构摘要时对模型的理解能力要求高建议用 Sonnet 级别。maxTokens 控制单次生成上限8192 够用。contextWindow 要和模型实际窗口一致填小了 Archify 会提前截断填大了请求会被拒。archify.scanDepth 是扫描深度新手先填 3太深会拖慢首次扫描。outputFormat 选 html生成可视化报告。填完保存重启 Cursor。重启后打开你的项目在命令面板输入 Archify: Scan如果配置正确底部状态栏会显示扫描进度。这一步先别急着看结果先确认没有报权限错误。4. Claude Code 侧 config.toml 可复制骨架Claude Code 走 TOML配置文件在用户目录下的 .claude/config.toml。如果你没建过这个文件直接新建。下面这段是完整骨架把 Key 替换成你自己的。[api] provider openai-compatible base_url https://taotoken.net/api api_key 你的TaoTokenKey model claude-3-5-sonnet max_tokens 8192 context_window 128000 [archify] enabled true ignore_file .archifyignore scan_depth 3 output_format html local_parser tree-sitter [archify.advanced] stream true timeout 300 retry 2和 Cursor 的差异点在于Claude Code 是 CLI 环境可以调用本地静态分析工具。local_parser 填 tree-sitter这样依赖关系提取在本地完成只把结构化 JSON 发给模型Token 消耗能降一大截。stream 开 true长任务不会卡死。timeout 给 300 秒十万行项目全量扫描大概四分钟留足余量。retry 给 2网络抖动时自动重试。保存后在终端进入你的项目目录运行 claude 进入交互模式然后输入 /archify scan。如果配置正确你会看到它先读 .archifyignore然后开始 AST 解析最后输出报告路径。提示Claude Code 的 config.toml 里 base_url 和 Cursor 的 baseUrl 写法不同一个是下划线一个是驼峰别抄错。5. 连通性验证与成功结果确认配置填完不等于通了得做一次最小验证。分两步走。第一步验证 API 通道。在终端跑一条 curl确认 TaoToken 的 Key 能正常返回。curl -X POST https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer 你的TaoTokenKey \ -H Content-Type: application/json \ -d { model: claude-3-5-sonnet, messages: [{role: user, content: ping}], max_tokens: 10 }返回里如果有 choices 字段和内容说明 Key 和通道没问题。如果返回 401检查 Key 有没有复制全返回 404检查 base_url 有没有多写斜杠返回 429说明额度或频率受限去 console 看一下。第二步验证 Archify 在宿主里的实际调用。Cursor 里跑 Archify: ScanClaude Code 里跑 /archify scan。成功的结果长这样终端或状态栏先显示“读取忽略规则”然后“解析 N 个文件”接着“构建依赖图谱”最后输出一行报告路径类似 ./archify-report/index.html。打开这个 HTML你能看到模块层级、依赖连线、以及被标红的循环依赖。如果卡在某一步不动或者报告里模块是孤立的往下看排错部分。6. 本篇常见报错排查6.1 Permission denied 或 Access restricted现象是扫描到一半报权限拒绝部分核心模块没进报告。原因是宿主环境对 .env、密钥目录做了沙箱限制Archify 递归扫描时撞上了。解决办法优先用 .archifyignore 显式排除而不是去改系统权限。在项目根目录建 .archifyignore写入.env *.key secrets/ node_modules/ dist/ .venv/保存后重新扫描。如果还有个别目录报错在 Cursor 设置里把项目根目录加到允许访问列表Claude Code 则在 config.toml 的 archify 段加一行 allow_paths [./src, ./lib]只放需要分析的目录。6.2 上下文溢出导致报告截断或幻觉现象是报告只生成了一半或者 AI 摘要里出现了不存在的模块关系。原因是依赖矩阵拼接后超过了模型窗口。解决办法是分层扫描不要一次性全量。先跑顶层/archify scan --depth 1拿到模块列表后对每个核心模块单独跑/archify scan --module order-service最后把子报告合并。另一个办法是确保 local_parser 开着让 tree-sitter 在本地把依赖关系压成 JSON只把 JSON 发给模型Token 消耗能降 60% 以上。6.3 动态导入导致模块孤立现象是架构图里某些模块没有连线但代码里确实有调用。原因是静态分析追不到 importlib.import_module 或 require(variable) 这类动态导入。解决办法是在代码里加显式标注比如在调用处上方加一行注释// archify-depends-on: payment-service const svc require(serviceName);Archify 会读取这个标记并建立连接。如果动态导入特别多可以在测试环境跑一次覆盖率工具把真实调用链导出成 JSON在 config.toml 里加 runtime_trace ./coverage/trace.json让 Archify 参考运行时数据。6.4 模型名填错导致 400现象是请求直接返回 400提示 model not found。原因是模型名和 TaoToken 文档里的不一致比如把 claude-3-5-sonnet 写成了 claude-3.5-sonnet。去 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentarchify_cursor_claudeutm_campaignrewrite 复制准确的模型名粘贴回配置文件重启宿主。7. 配置完成后怎么继续用配置跑通之后日常使用就三件事。第一每次 AI 批量生成代码后跑一次 Archify 扫描检查有没有引入新的循环依赖或跨层调用这是防止架构腐化最省力的办法。第二定期生成架构快照对比不同版本的依赖变化技术债的累积趋势会直观很多。第三新人入职时把 HTML 报告当培训材料比让人逐层跳转 IDE 快得多。如果你后面要长期在 Cursor 或 Claude Code 里做编码和 Agent 任务可以看一下 Coding Plan额度更稳https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentarchify_cursor_claudeutm_campaignrewrite 。想先验证模型对话效果用 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentarchify_cursor_claudeutm_campaignrewrite 。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentarchify_cursor_claudeutm_campaignrewrite Key 管理在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentarchify_cursor_claudeutm_campaignrewrite 。Claude Code 的专项配置参考 https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentarchify_cursor_claudeutm_campaignrewrite 。最后说一个我踩过的坑两个宿主不要同时跑全量扫描内存峰值会叠加16GB 的机器容易卡死。分时跑或者一个跑全量一个只跑单模块稳得多。
