[{"slug":"index","title":"使用指南","group":"概览","lede":"住在终端里的 AI 编码助手。给它一个自然语言任务，它会自主读取、编辑、运行并自我验证。本文档带你从零开始，逐步掌握 AtomCode 的每一项能力。","sections":[{"id":"atomcode-使用指南","heading":"AtomCode 使用指南","body":"住在终端里的 AI 编码助手。给它一个自然语言任务，它会自主读取、编辑、运行并自我验证。本文档带你从零开始，逐步掌握 AtomCode 的每一项能力。 v4.24.2 许可证 MIT 语言 Rust 1.88+ 平台 macOS · Linux · HarmonyOS PC · Windows 100% AI 生成"},{"id":"三步开始","heading":"三步开始","body":"安装 —— 一条 curl 命令或者从源码构建，参见 快速开始 。 登录或配置模型 —— AtomGit OAuth 一键登录最省事，也支持任意 OpenAI 兼容 API Key，参见 登录方式 和 配置文件 。 开始提问 —— 在项目目录下运行 atomcode ，用自然语言描述你的任务即可。 Tip 如果只是想快速体验，跑一条命令即可： atomcode -p \"简要介绍一下这个仓库\" ，一次性执行并把结果输出到 stdout。"},{"id":"文档导览","heading":"文档导览","body":""},{"id":"快速开始","heading":"快速开始","body":"安装方式、首次运行的 3 步启动向导、完成第一个任务,以及 atomcode uninstall 卸载流程。"},{"id":"配置文件","heading":"配置文件","body":"~/.atomcode/config.toml 字段说明、各家 provider 配置示例,含视觉预处理器(非视觉模型也能问图)。"},{"id":"登录方式","heading":"登录方式","body":"AtomGit OAuth 一键登录(自动持久化)与 API Key 配置对比。"},{"id":"基本使用","heading":"基本使用","body":"如何描述任务、常用 CLI 参数、文件引用、多行输入,以及图片附件 / 截图(Ctrl+V / 拖拽)。"},{"id":"斜杠命令","heading":"斜杠命令","body":"30+ 个内置斜杠命令参考表,涵盖会话、模型、撤销、Issue、对话模式、扩展生态等操作。"},{"id":"快捷键","heading":"快捷键","body":"输入、导航、选区复制等全部 TUI 快捷键。"},{"id":"内置工具","heading":"内置工具","body":"21 个内置工具:文件/Shell、代码图谱、Web、自动化分类说明。"},{"id":"会话与撤销","heading":"会话与撤销","body":"持久化会话恢复、 /undo 回滚、清空与压缩上下文。"},{"id":"项目指令文件","heading":"项目指令文件","body":"用 .atomcode.md 给 AtomCode 定制项目级规范。"},{"id":"skills-扩展","heading":"Skills 扩展","body":"编写用户自定义 skill,扩展斜杠命令生态。"},{"id":"plugin-系统","heading":"Plugin 系统","body":"从 git 仓库一键安装别人写好的 skill / 命令 / hook 套件,与 Claude Code 生态兼容。"},{"id":"mcp-集成","heading":"MCP 集成","body":"通过 .mcp.json 接入外部 MCP server,把 GitHub、数据库、Playwright 等生态工具暴露给模型。"},{"id":"常见问题","heading":"常见问题","body":"安装、连不上模型、权限确认、上下文超限等常见疑问解答。"},{"id":"反馈与参与","heading":"反馈与参与","body":"AtomCode 是开源项目,欢迎提交 issue 或 PR: 开源仓库: https://atomgit.com/atomgit_atomcode/atomcode Issue:终端内直接运行 /issue 即可快速创建 许可证:MIT © 2026 AtomCode · MIT 报告问题"}]},{"slug":"getting-started","title":"快速开始","group":"开始","lede":"几分钟内完成安装、首次运行和第一个任务,体验 AtomCode 的完整流程。","sections":[{"id":"快速开始","heading":"快速开始","body":"几分钟内完成安装、首次运行和第一个任务,体验 AtomCode 的完整流程。"},{"id":"系统要求","heading":"系统要求","body":"操作系统 :macOS (Apple Silicon 或 Intel)、Linux、Windows、HarmonyOS PC Rust 工具链 :1.75+(仅在从源码构建时需要) LLM 模型 :任一支持的 provider 的 API Key,或一个 AtomGit 账号(用于 OAuth 登录)"},{"id":"安装","heading":"安装","body":""},{"id":"方式-1一键安装推荐","heading":"方式 1:一键安装(推荐)","body":"在 macOS 或 Linux 或 HarmonyOS PC 终端执行: curl -fsSL https://raw.atomgit.com/atomgit_atomcode/atomcode/raw/main/scripts/install.sh | sh 脚本会自动下载对应平台的预编译二进制,并放置到 ~/.local/bin/atomcode 。请确保该目录在 PATH 中。 在 Windows PowerShell 中执行: irm https://raw.atomgit.com/atomgit_atomcode/atomcode/raw/main/scripts/install.ps1 | iex 脚本会自动下载 Windows x64 预编译二进制,并完成 PATH 配置,新开终端即可使用 atomcode 命令。"},{"id":"方式-2通过-npm","heading":"方式 2:通过 npm","body":"已安装 Node.js 18+ 时,可以直接走 npm 全局安装: npm install -g @atomgit.com/atomcode 包会按当前平台从 optionalDependencies 自动解析对应的预编译二进制(macOS x64 / arm64、Linux x64 / arm64、Windows x64、HarmonyOS arm64),一行命令搞定跨平台安装。"},{"id":"方式-3通过-homebrew","heading":"方式 3:通过 Homebrew","body":"已安装 Homebrew 时,可以通过 cask 安装(支持 macOS x64 / arm64、Linux x64 / arm64): brew install --cask atomcode Homebrew 会自动下载对应平台的预编译二进制并配置 PATH 。"},{"id":"方式-4从源码构建","heading":"方式 4:从源码构建","body":"git clone https://atomgit.com/atomgit_atomcode/atomcode.git cd atomcode cargo build --release cp target/release/atomcode ~/.local/bin/ Release 构建编译时间较长,但生成的二进制体积小、运行速度快。开发调试时用 cargo build 即可。"},{"id":"验证安装","heading":"验证安装","body":"atomcode --version 你应该看到类似 atomcode 4.20.x (build-id) 的输出。"},{"id":"首次运行","heading":"首次运行","body":"直接在任意目录运行: atomcode 第一次启动会自动弹出 3 步首次启动向导 (也可以随时用 /welcome 重新打开):"},{"id":"第-13-步-欢迎","heading":"第 1/3 步 · 欢迎","body":"███ █████ ███ █ █ ████ ███ ████ █████ █ █ █ █ █ ██ ██ █ █ █ █ █ █ █████ █ █ █ █ █ █ █ █ █ █ █ █ ████ █ █ █ █ █ █ █ █ █ █ █ █ █ █ █ █ █ ███ █ █ ████ ███ ████ █████ AtomCode 版本 4.23.3 · 在终端里运行的 AI 编程代理 • 多步骤 agent loop · 内置代码图工具 • 兼容所有 OpenAI 风格 API • 通过 CodingPlan 获取免费额度 按 Enter 继续。 Ctrl+C 可随时退出。"},{"id":"第-23-步-语言-choose-your-language-选择语言","heading":"第 2/3 步 · 语言 (Choose your language / 选择语言)","body":"1. 自动检测 (LC_ALL / LANG) 2. English 3. 简体中文 (Simplified Chinese) 1-3 选择 · Enter 确认 · ← 返回 · Esc 跳过 选完会立即应用,并写回 ~/.atomcode/config.toml 的 locale 字段。之后任意时刻可以用 /language 再改。"},{"id":"第-33-步-配置-想怎么开始","heading":"第 3/3 步 · 配置 (想怎么开始?)","body":"1. 用 AtomGit CodingPlan 一键接入 (推荐 · 免费额度 + 自动配 provider) 2. 手动配置 provider (已有 API Key) 3. 跳过,先进 TUI 探索 (之后再 /login 或 /provider) 1-3 选择 · Enter 确认 · ← 返回 · Esc 跳过 CodingPlan —— 推荐路径,等价于在 TUI 内执行 /login :浏览器唤起 AtomGit OAuth,登录后自动申领免费额度,并把额度模型列表写成 provider 配置。 手动配置 —— 等价于 /provider ,进入 provider 管理界面填 Key / base URL / model。 跳过 —— 直接进 TUI 探索,之后再用 /login 或 /provider 完成配置。 更详细的选择参见 登录方式 。任何时候可以用 /welcome 重新打开这个向导。"},{"id":"第一个任务","heading":"第一个任务","body":"进入一个你熟悉的项目目录,启动 atomcode,然后直接描述你想做的事: cd ~/projects/my-web-app atomcode > 简要介绍一下这个项目的目录结构和技术栈 AtomCode 会自主地: 运行 list_directory 、 read_file 等工具探索代码 识别关键描述文件( package.json / Cargo.toml 等) 给出结构化的总结 Tip 不确定要问什么?试试:\" 修复 README 里所有的拼写错误 \"、\" 把 src/utils.ts 里的函数加上 TypeScript 类型 \"、\" 跑一下测试并修复失败用例 \"。"},{"id":"卸载","heading":"卸载","body":"不再需要 AtomCode 时,用内置的 uninstall 子命令一步清理。它会按组询问你是否删除以下三类内容:二进制本身 + 安装脚本写入的 PATH 编辑、 ~/.atomcode/auth.toml 等凭据、 ~/.atomcode/sessions/ 等运行状态。"},{"id":"交互式推荐","heading":"交互式(推荐)","body":"atomcode uninstall 每个组单独询问 y/N,按当前默认决策(二进制=是、凭据=否、状态=是)预填 — 直接回车也是合理选择。"},{"id":"非交互式","heading":"非交互式","body":"# 全自动:按默认决策走,不弹任何提示 atomcode uninstall --yes # 一键全清(包括 ~/.atomcode/ 整个目录) atomcode uninstall --purge # 只删二进制和 PATH 编辑,~/.atomcode/ 完整保留 atomcode uninstall --keep-data # 只打印执行计划,什么都不做 atomcode uninstall --dry-run 注意 --purge 会连带删除 所有会话历史、记忆、自定义 provider 配置、OAuth token ;不可逆。如果以后还可能用 AtomCode,优先用默认交互式或 --keep-data 。"},{"id":"下一步","heading":"下一步","body":"配置文件 —— 学会管理多个 provider 和模型。 基本使用 —— 熟悉 CLI 参数和描述任务的最佳实践。 斜杠命令 —— 掌握 /resume 、 /undo 、 /diff 等高频命令。 © 2026 AtomCode · MIT 报告问题"}]},{"slug":"login","title":"登录方式","group":"开始","lede":"AtomCode 支持两种方式接入 LLM:AtomGit CodingPlan(含免费额度)和传统 API Key。本页帮你选对方式,并完成绑定。","sections":[{"id":"登录方式","heading":"登录方式","body":"AtomCode 支持两种方式接入 LLM:AtomGit CodingPlan(含免费额度)和传统 API Key。本页帮你选对方式,并完成绑定。"},{"id":"两种方式速览","heading":"两种方式速览","body":"方式 命令 适合人群 AtomGit CodingPlan /login 推荐 — 一条命令完成 OAuth + 申领免费额度 + 自动配好 provider 和 model API Key /provider 或手动编辑配置 使用自有 OpenAI / Claude / DeepSeek Key 的用户 v4.24.2 起 /codingplan 已折进 /login ;旧的「纯 OAuth 不申领额度」入口已移除。"},{"id":"atomgit-codingplan推荐","heading":"AtomGit CodingPlan(推荐)","body":"AtomGit 是 CSDN / 开放原子开源基金会旗下的开源代码托管平台,AtomCode 原生集成了它的 OAuth 和 CodingPlan。 /login 是新用户最省事的入口,一次操作完成登录 → 申领免费 token 额度 → 自动根据额度内的模型列表写好 provider 配置。用完这条命令,直接就能开始聊天。已登录后再跑会幂等地同步最新模型列表,不会重复申领。"},{"id":"从首次运行启动向导接入","heading":"从首次运行启动向导接入","body":"首次启动 atomcode ,会自动弹出 3 步启动向导。 第 1 步(欢迎)按 Enter,第 2 步(语言)按 1 / 2 / 3 选语言。 第 3 步(配置)选 用 AtomGit CodingPlan 一键接入 (选项 1)。 浏览器会自动打开 AtomGit 授权页面,点击允许即可。 授权完成后 TUI 会自动申领 CodingPlan 并写入 provider 配置,无需再动 config.toml ,直接开始发消息。 如果跳过过了想重新跑一遍向导,任何时候执行 /welcome 即可。"},{"id":"在已有会话里接入","heading":"在已有会话里接入","body":"已经进入 TUI 后,任意时刻执行: /login 会唤起浏览器完成授权、申领 CodingPlan、更新 provider 列表。再次执行会重新同步模型列表,把本地的 AtomGit* provider 同步到最新的额度模型。"},{"id":"从命令行接入","heading":"从命令行接入","body":"atomcode login 适合在脚本、远程服务器、容器镜像等场景一次性完成接入。CLI 子命令和 TUI /login 走同一套流程,输出同样的报告。 注: atomcode codingplan 仍作为隐藏别名保留,老脚本和肌肉记忆都不会因为命令折叠而失效。"},{"id":"查看状态-退出","heading":"查看状态 / 退出","body":"atomcode status # 或 TUI 内 /status — 包含 CodingPlan 使用量和过期时间 atomcode logout # 或 TUI 内 /logout — 清除 OAuth token"},{"id":"api-key-方式","heading":"API Key 方式","body":"如果你想使用自有的 OpenAI / Claude / DeepSeek / GLM 等密钥,有三种做法:"},{"id":"方式-atui-内-provider","heading":"方式 A:TUI 内 /provider","body":"在 TUI 中输入 /provider 。 选择\"添加新 provider\",按提示填写 type、base URL、API Key、model 等。 配置会自动写回 ~/.atomcode/config.toml 。"},{"id":"方式-b手动编辑配置文件","heading":"方式 B:手动编辑配置文件","body":"直接编辑 ~/.atomcode/config.toml ,写入一个 [providers.*] 条目即可,字段参见 ProviderConfig 字段 。"},{"id":"方式-c命令行一次性覆盖","heading":"方式 C:命令行一次性覆盖","body":"不想改配置文件、只想临时用另一个 provider?启动时加参数即可: atomcode --provider deepseek --model deepseek-reasoner"},{"id":"选哪个","heading":"选哪个?","body":"第一次使用 &rarr; CodingPlan ( /login ),免费额度直接用。 已有自己的 API Key &rarr; 跳过 /login ,直接用 API Key ( /provider 或手动编辑配置)。需要 AtomGit 集成( /issue 等)再跑 /login ,但会顺带申领 CodingPlan 并注册 AtomGit-* provider。 需要在 CI / 脚本里跑 &rarr; API Key + 配置文件或环境变量。 完全离线 &rarr; 配置一个 Ollama provider,不需要任何登录。"},{"id":"下一步","heading":"下一步","body":"基本使用 —— 登录后第一件事:学怎么描述任务。 斜杠命令 —— /provider 、 /model 、 /status 详解。 © 2026 AtomCode · MIT 报告问题"}]},{"slug":"configuration","title":"配置文件","group":"开始","lede":"AtomCode 的配置采用 TOML 格式,支持多个 provider 并行存在、随时切换。本页讲清每一个字段的含义和常见 provider 的示例配置。","sections":[{"id":"配置文件","heading":"配置文件","body":"AtomCode 的配置采用 TOML 格式,支持多个 provider 并行存在、随时切换。本页讲清每一个字段的含义和常见 provider 的示例配置。"},{"id":"配置文件位置","heading":"配置文件位置","body":"默认路径: macOS / Linux / HarmonyOS PC: ~/.atomcode/config.toml Windows: %USERPROFILE%\\.atomcode\\config.toml 也可以通过 --config /path/to/config.toml 指定任意路径。首次运行时,若该文件不存在,3 步启动向导会引导你完成初始化。"},{"id":"最小示例","heading":"最小示例","body":"default_provider = \"deepseek\" [providers.deepseek] type = \"openai\" api_key = \"sk-xxxxxxxxxxxxxxxx\" model = \"deepseek-chat\" base_url = \"https://api.deepseek.com/v1\" context_window = 64000 这个配置已经可以启动 atomcode 并与 DeepSeek 对话。"},{"id":"顶层字段","heading":"顶层字段","body":"字段 类型 说明 default_provider string 启动时默认使用的 provider 名(必须是 [providers.*] 中定义过的 key) default_workdir string? 默认工作目录。用 /cd 切换目录时自动写回这里,下次启动恢复 providers table provider 名到 ProviderConfig 的映射 vision_preprocessor_provider string? 当主 provider 不支持图片但用户 attach 了图时,把图片转交给这里指定的 provider 做 OCR / 描述,结果以文本形式 splice 给主模型。详见 视觉预处理器"},{"id":"provider-config","heading":"ProviderConfig 字段","body":"每一个 [providers.xxx] 表下可用的字段: 字段 类型 必填 说明 type string 是 provider 协议类型,目前支持 openai 、 claude 、 ollama api_key string? 视情况 API Key。 ollama 可不填。OAuth 登录的 provider 不含此字段,token 从 ~/.atomcode/auth.toml 自动读取 model string 是 模型名,比如 deepseek-chat 、 gpt-4o 、 claude-sonnet-4-6 base_url string 是 API 基地址,需指向实际接口。例: https://api.deepseek.com/v1 、 http://localhost:11434 context_window integer 否 模型上下文窗口(tokens),默认 64000。 ollama 默认 8000 max_tokens integer? 否 单次响应的最大输出 token 数。留空则使用 context_window / 4 system_prompt string? 否 覆盖默认系统提示。大多数场景不需要 user_agent string? 否 覆盖 HTTP 请求的 User-Agent,当上游接口屏蔽通用 UA 时使用 为什么默认 64K 而不是 128K? 即便模型官方声称支持 128K+,其有效注意力窗口通常要小得多,过大上下文反而会触发\"迷失在中段\"的问题,并且阻止 AtomCode 的上下文压缩策略生效。64K 是经验上最稳的默认值,若你确定模型表现良好,可自行上调。"},{"id":"常见-provider-配置示例","heading":"常见 provider 配置示例","body":""},{"id":"claude-anthropic","heading":"Claude (Anthropic)","body":"[providers.claude] type = \"claude\" api_key = \"sk-ant-...\" model = \"claude-sonnet-4-6\" context_window = 128000"},{"id":"openai","heading":"OpenAI","body":"[providers.openai] type = \"openai\" api_key = \"sk-...\" model = \"gpt-4o\" context_window = 128000"},{"id":"deepseek","heading":"DeepSeek","body":"[providers.deepseek] type = \"openai\" api_key = \"sk-...\" model = \"deepseek-chat\" base_url = \"https://api.deepseek.com/v1\" context_window = 64000"},{"id":"智谱-glm","heading":"智谱 GLM","body":"[providers.glm] type = \"openai\" api_key = \"...\" model = \"glm-4-plus\" base_url = \"https://open.bigmodel.cn/api/paas/v4\" context_window = 128000"},{"id":"通义千问-qwen","heading":"通义千问 Qwen","body":"[providers.qwen] type = \"openai\" api_key = \"sk-...\" model = \"qwen-plus\" base_url = \"https://dashscope.aliyuncs.com/compatible-mode/v1\" context_window = 128000"},{"id":"siliconflow","heading":"SiliconFlow","body":"[providers.siliconflow] type = \"openai\" api_key = \"sk-...\" model = \"Qwen/Qwen2.5-72B-Instruct\" base_url = \"https://api.siliconflow.cn/v1\""},{"id":"ollama本地","heading":"Ollama(本地)","body":"[providers.ollama] type = \"ollama\" model = \"llama3.2\" base_url = \"http://localhost:11434\" context_window = 8000 注意 Ollama 模型 function calling 的兼容性参差不齐,弱一些的本地模型可能无法稳定触发工具调用。建议优先尝试 Qwen2.5 / Llama3.2 的 Instruct 版本。"},{"id":"多-provider-与快速切换","heading":"多 provider 与快速切换","body":"配置文件允许同时存在任意数量的 provider: default_provider = \"claude\" [providers.claude] type = \"claude\" api_key = \"sk-ant-...\" model = \"claude-sonnet-4-6\" [providers.deepseek] type = \"openai\" api_key = \"sk-...\" model = \"deepseek-chat\" base_url = \"https://api.deepseek.com/v1\" [providers.local] type = \"ollama\" model = \"qwen2.5:14b\" base_url = \"http://localhost:11434\" 在 TUI 中可以用 /provider 在这些条目之间切换,用 /model 只切换当前 provider 下的模型。命令行启动时也支持一次性覆盖: atomcode --provider deepseek --model deepseek-reasoner"},{"id":"vision-preprocessor","heading":"视觉预处理器","body":"当当前 active provider 的模型不支持图片输入(纯文本模型,比如 DeepSeek-V3 / Kimi),用户却 attach 了图片 时,AtomCode 不会直接拒绝,而是会把图片转给一个独立的\"视觉预处理 provider\"做 OCR + 描述,把结果以文本形式 splice 进用户消息里再发给主模型。 启用方式:在配置里指定一个支持图片的 provider key 作为 vision_preprocessor_provider : default_provider = \"deepseek\" vision_preprocessor_provider = \"qwen-vl\" [providers.deepseek] type = \"openai\" api_key = \"sk-...\" model = \"deepseek-chat\" base_url = \"https://api.deepseek.com/v1\" [providers.qwen-vl] type = \"openai\" api_key = \"sk-...\" model = \"Qwen/Qwen3-VL-32B-Instruct\" base_url = \"https://api.siliconflow.cn/v1\" 这里的 qwen-vl 必须是 [providers.*] 里已经定义过的 key,且对应的模型支持视觉输入(常见的有 Qwen3-VL-* / GLM-4V-* / claude-3+ / gpt-4o / gemini-* 等)。 当前 active provider 自身就支持图片时, 不会 走预处理器,直接发原始图片字节。 /login 流程会从下发的模型列表中自动挑选一个 VL/OCR 模型并写入这个字段(可在事后手动覆盖)。 VL 调用使用 无进展超时 (idle timeout):只要 stream 持续吐 chunk 不限总时长;30 秒没动静才超时。失败时主模型仍会收到带 \"图片识别失败\" 标记的消息,而不是静默吞掉。 用法层面的细节参见 基本使用 · 图片附件 / 截图 。"},{"id":"编辑配置的三种方式","heading":"编辑配置的三种方式","body":"手动编辑 —— 直接用你喜欢的编辑器打开 ~/.atomcode/config.toml 。 TUI 内 /config —— 在 atomcode 内部直接调用默认编辑器打开配置文件。 TUI 内 /provider —— 交互式地添加、编辑、删除 provider,改动会自动落盘。"},{"id":"下一步","heading":"下一步","body":"登录方式 —— 如果不想手动管理 API Key,用 AtomGit OAuth 一步到位。 基本使用 —— 看看 CLI 参数如何一次性覆盖配置。 © 2026 AtomCode · MIT 报告问题"}]},{"slug":"basic-usage","title":"基本使用","group":"使用","lede":"掌握 CLI 参数、如何描述任务、如何给模型提供上下文、如何在多个任务之间切换。","sections":[{"id":"基本使用","heading":"基本使用","body":"掌握 CLI 参数、如何描述任务、如何给模型提供上下文、如何在多个任务之间切换。"},{"id":"启动方式","heading":"启动方式","body":"# 在当前目录启动 TUI atomcode # 指定工作目录 atomcode -C /path/to/project # 指定 provider / 模型(一次性覆盖默认) atomcode --provider claude --model claude-sonnet-4-6 # 继续上一次会话 atomcode -c atomcode --continue # 使用指定的配置文件 atomcode --config ./custom.toml # 跳过所有权限确认,自动批准工具调用 atomcode -y atomcode --dangerously-skip-permissions"},{"id":"cli-参数总览","heading":"CLI 参数总览","body":"参数 简写 作用 --dir PATH -C 工作目录,不指定则使用当前目录 --continue -c 继续上一次会话,而不是新建 --provider NAME — 覆盖默认 provider --model NAME — 覆盖当前 provider 的 model --config PATH — 使用指定的配置文件 --prompt TEXT -p 非交互模式,单次执行并把回复写到 stdout --prompt-file PATH — 从文件读取 prompt(适合长文本,与 -p 互斥) --verbose -v 非交互模式下把工具调用、token 用量等信息打到 stderr --max-turns N — 强制限制 Agent 循环的最大轮数,防止无限跑下去 --disable-tools LIST — 逗号分隔,禁用某些工具。例如 --disable-tools bash,web_fetch --dangerously-skip-permissions -y 跳过所有权限确认,自动批准所有工具调用(bash、文件编辑、MCP 等)。TUI 模式下状态栏显示 ⚠ BYPASS 徽章 Tip --disable-tools 让被禁用的工具对模型完全不可见(不会出现在 schemas 中),模型就不会重复尝试调用它。在沙箱评测、离线环境、禁止联网的 CI 等场景里非常实用。 Warning -y / --dangerously-skip-permissions 会跳过所有权限确认,包括 bash 命令执行、文件写入和 MCP 工具调用等。Agent 可以不经确认直接执行任意操作。请仅在以下场景使用: CI/CD 流水线等自动化环境 沙箱或容器内的评测基准测试 你充分信任 Agent 内置安全约束的非关键项目"},{"id":"描述任务的原则","heading":"描述任务的原则","body":"AtomCode 的 Agent 循环能力主要取决于你给出的任务描述的质量。几条经验: 说目标,不说步骤 —— \"修复登录后跳 404 的 bug\",而不是\"打开 src/auth/callback.ts,删除第 27 行,再…\"。模型有足够的探索能力。 点明约束 —— 当你有偏好时明确说出:\"保持 API 兼容\"、\"不改动测试文件\"、\"用 TypeScript 而不是 JS\"。 给出验证方式 —— \"改完后跑 npm test 确认通过\",让模型完成自我验证闭环。 先问后改 —— 不确定方向时,先让它\"分析这个模块的结构并提出重构方案\",对齐之后再让它动手。"},{"id":"示例任务","heading":"示例任务","body":"# Bug 修复 > 修复 OAuth 回调后用户被重定向到 404 的问题,确保回调完整恢复原始路径 # 新增功能 > 在设置页增加深色模式切换,使用 Tailwind 的 dark: 前缀,并持久化到 localStorage # 重构 > 把 src/db/*.ts 重构成使用连接池,保持公有 API 不变,改完后跑 npm test # 测试 > 给 src/payment/processor.ts 写单元测试,覆盖所有异常分支 # 代码理解 > 简要说明这个仓库的目录结构、构建入口和核心模块职责"},{"id":"多行输入","heading":"多行输入","body":"在 TUI 中: Enter 发送消息 Shift+Enter / Ctrl+Enter / Ctrl+J 换行(需要 Kitty 键盘协议: kitty / WezTerm / Alacritty / iTerm2 ≥3.5 / Windows Terminal ≥1.21) Alt+Enter 换行(多数终端可用,但 Windows Terminal 默认绑给\"切换全屏\",需在设置里解绑) 输入框高度会随内容自动增长"},{"id":"at-mention","heading":"@ 引用文件","body":"在输入框里敲一个 @ (前面是空白或行首)就会弹出项目内文件/目录的候选菜单。这是把代码里某个具体路径\"指给模型看\"最快的方式 — 你只负责定位,要不要展开、读多少由模型按需调 read_file 决定。"},{"id":"交互","heading":"交互","body":"触发 —— @ 前面是空白或行首才生效。 email@host.com 这种中间出现的 @ 不会触发,避免误弹。 过滤 —— 继续敲字符做子串匹配(大小写不敏感)。例如 @cra 能命中 crates/ ; @toml 能命中所有 *.toml 。 下钻 —— 敲 / 进入某个目录,菜单收紧到该目录的内容。例如 @crates/ → @crates/atomcode-cli/ → ... 导航 —— ↑ / ↓ 切换候选, Enter 或 Tab 都可以选中。 Esc 关菜单不插入。 插入形式 —— 选中后,输入框里的 @xxx 部分被替换为 @完整相对路径 (目录会带 / )再加一个尾随空格,光标停在空格后,可以直接继续打字。 回退继续选 —— 删掉尾随空格后,菜单会就地重开,方便从当前目录继续往下钻。"},{"id":"候选来自哪里","heading":"候选来自哪里","body":"项目根目录下的 所有文件和目录 — 文件、目录都能选;目录用尾随 / 标识。 尊重 .gitignore (以及全局 ignore、 .git/info/exclude ),被忽略的路径不会出现在菜单里。 .git/ 内部内容 不出现在候选里 — 几乎没人想 @ 引用 git 元数据。 隐藏文件保留 — .env 、 .atomcode.md 这类点开头文件能正常命中(只要没被 gitignore 屏蔽)。 跨级模糊匹配 — 一旦你开始打过滤字符,匹配会穿透多级目录(不只是当前 scope 的直接子项)。空过滤时只显示当前 scope 的直接子项。 排序 :当前 scope 的直接子项优先 → 目录优先于文件 → 字母序。"},{"id":"对模型意味着什么","heading":"对模型意味着什么","body":"提交时, @crates/atomcode-cli/src/main.rs 作为 字面文本 一同发给模型 — AtomCode 不会 在前端预读文件内容并内联。模型看到这段路径后,会按需调用内置的 read_file 工具去读。这样: 大文件不会无脑塞进上下文,token 预算更可控。 引用目录时模型会先 list 再决定读哪些。 多次复读不会重复内联同一份内容。 Tip 如果想强制把文件内容直接喂进对话(比如让模型针对某段代码做精读、不希望它再走一次 read_file ),用粘贴 — 直接把内容粘进输入框,bracketed paste 会把它折叠成 [paste #N] 标记,提交时整段带入。"},{"id":"限制","heading":"限制","body":"候选菜单一次最多展示 30 条 ,继续打过滤字符可以缩小命中范围。 路径中含空格的文件不会出现在候选里 — 因为 @ 引用以空白作为终止符。 文件索引在会话内 一次性构建 ,会话期间新建的文件不会自动出现在菜单里;切换会话或重启会重新扫描。 不跟随符号链接。 没有大小、类型过滤 — 所有未被 ignore 的文件都会出现。"},{"id":"粘贴长文本","heading":"粘贴长文本","body":"AtomCode 支持 bracketed paste。当你粘贴一段很长的内容(比如一堆日志)时,TUI 会把它折叠成一个紧凑的 [paste #N · 132 lines] 指示器,避免输入框被撑爆。发送时会完整带入。"},{"id":"image-attach","heading":"图片附件 / 截图","body":"除了文本,你还能把 图片 带进对话 — 报错截图、UI mock、白板照片等。AtomCode 提供三条入口,任选其一: Ctrl+V — 系统剪贴板里有图片时(刚 Cmd+Shift+4 截图、从浏览器复制图等),按 Ctrl+V 直接 attach。这是 macOS + iTerm2 等终端默认 Cmd+V 不传图给 PTY 时的兜底方案,任何终端都通用。 Cmd+V(macOS / iTerm2,需简单配置) — iTerm2 → Settings → Profiles → Keys → Key Mappings,把 ⌘V 映射为 Send Hex Codes: 0x16 ,之后 Cmd+V 就跟 Ctrl+V 等价。 Finder 拖拽 / iTerm2 自动转路径 — 把一张图直接拖进终端窗口,iTerm2 / Wezterm 等会把文件路径以 plaintext 方式粘进来;AtomCode 识别到绝对路径 + .png / .jpg / .jpeg / .gif / .webp 扩展名 + 文件存在 + 大小 ≤ 20MB 时,会自动读取文件并 attach。原始路径字符串不会留在输入框里。 每次成功 attach 时,输入框会就地插入一个 [Image #N] 标记,提交时图片字节随消息一起发。状态栏右侧也会出现 Image in clipboard · ctrl+v to paste 的提示(剪贴板还有未粘的图时)。"},{"id":"非视觉模型怎么处理图片","heading":"非视觉模型怎么处理图片?","body":"当前 active provider 不支持图片输入(比如 DeepSeek-V3 / Kimi 等纯文本模型)时,AtomCode 不会直接拒绝,而是会自动调用一个独立的 VL preprocessor (视觉模型,比如 Qwen3-VL / GLM-4V)对图片做 OCR + 描述,把结果作为文本 splice 到用户消息里再发给主模型。这样无论主模型支不支持图片,你都能\"贴张截图问问题\"。 preprocessor 用哪个模型?由配置文件里的 vision_preprocessor_provider 决定 — 详见 配置文件 · 视觉预处理器 。 /login 流程会自动从模型列表里挑一个 VL/OCR 模型自动设置进去。 VL 调用使用 无进展超时 (idle timeout):只要 stream 持续吐 chunk,不限总时长;30 秒没动静才算超时。失败时会以 VL 预处理失败 的警告呈现,图片识别失败但消息照常发。 Tip 如果当前模型本身就支持视觉输入(Claude 3+ / GPT-4o / Gemini / Qwen-VL 等),会直接发原始图片字节,不走 preprocessor。"},{"id":"切换会话和目录","heading":"切换会话和目录","body":"/resume —— 在不同会话之间切换或恢复 /session —— 新建一个干净会话 /cd 或直接输入 cd /path —— 切换工作目录(状态栏实时更新) /clear —— 清空当前会话的消息 /compact —— 压缩历史消息以腾出上下文预算 详细行为见 会话与撤销 。"},{"id":"查看成本和-diff","heading":"查看成本和 diff","body":"/cost —— 本次会话输出 token 数和上下文用量(不支持 usage 的 API 会自动估算) /diff —— 当前工作目录未提交改动的 git diff /undo —— 回滚上一轮的所有文件编辑"},{"id":"下一步","heading":"下一步","body":"斜杠命令 —— 30+ 个命令的完整参考 快捷键 —— 熟练使用键盘将大幅提升效率 © 2026 AtomCode · MIT 报告问题"}]},{"slug":"slash-commands","title":"斜杠命令","group":"使用","lede":"在 TUI 输入框中以 / 开头即可触发命令,并获得自动补全菜单。按功能分类的 30+ 个内置命令如下;Skills 和 Plugin 加载的命令也会自动出现在补全菜单里。","sections":[{"id":"斜杠命令","heading":"斜杠命令","body":"在 TUI 输入框中以 / 开头即可触发命令,并获得自动补全菜单。按功能分类的 30+ 个内置命令如下;Skills 和 Plugin 加载的命令也会自动出现在补全菜单里。"},{"id":"核心功能","heading":"核心功能","body":"命令 作用 /login 推荐 — 一条命令完成 AtomGit OAuth + 申领 CodingPlan 免费额度 + 自动根据额度模型列表写好 provider 配置。首次启动最省事的入口;已登录后重跑会幂等地同步最新模型列表。 v4.24.2 起 /codingplan 已折进 /login ,旧入口已移除 /resume 打开会话选择器,恢复任意一个之前的持久化会话(含消息、目录和模型状态) /session 创建一个全新的、干净的会话 /bg 将当前会话放到后台并打开新的前台会话;子命令: /bg list 、 /bg <N> 、 /bg drop <N> 、 /bg help 。详见 后台会话 /background <task> 兼容入口:在一个 /bg 槽位中启动一次性后台任务( 详解 ) /rename <新名字> 重命名当前会话(影响 /resume 选择器里的显示名) /provider 打开 provider 管理界面,增删改切换 /model 在当前 provider 下切换模型,或跨 provider 切换 /cd 切换工作目录,并写回 default_workdir 。也可以直接输入 cd /path (无需斜杠前缀)"},{"id":"工具与实用操作","heading":"工具与实用操作","body":"命令 作用 /undo · /undo N 把对话记忆回退到上一轮(或第 N 轮)之前,并把那一轮的 prompt 还原回输入框;只回退记忆,不恢复磁盘文件 /diff 显示当前工作目录未提交改动的 git diff /cost 展示当前会话输出 token 数。不支持 usage 报告的 API 会自动估算 /context 显示本轮上下文预算分解:系统提示、工具定义、冷区压缩、总消息数、context window 占用 /compact 压缩历史消息,把早期对话压缩成摘要以腾出上下文预算 /clear 清空当前会话的消息(保留工作目录和模型) /init 扫描当前工作目录,生成 / 刷新 .atomcode.md 项目指令文件 — 内含 build / test 命令、技术栈摘要、目录结构等,后续每次启动都会作为系统提示注入 /background <任务> 把任务派发给一个隔离的后台 agent(只读为主的工具子集),不污染当前主对话上下文。用于\"顺手让它去查一下 X\"这类轻探索。详见 后台会话 /worktree <子命令> Git worktree 隔离: create 在新分支上拉一份独立 worktree、 list 查看现有 worktree、 done 把 worktree 改动 squash 回主分支、 cleanup 清理已完成的 worktree /issue 交互式向导:在当前 git 仓库对应的 AtomGit 仓库创建一个新 issue(需先 OAuth 登录,cwd 必须是 atomgit.com 仓库的 clone)"},{"id":"对话模式与思考","heading":"对话模式与思考","body":"命令 作用 /plan 切到 Plan 模式 :只读探索,模型可以调用 read_file / grep / list_directory 等不写盘的工具,但 edit_file / bash 等会被屏蔽。适合在动手之前让模型先理清方案 /build 切回 Build 模式 (默认):全部工具可用,可以读、写、执行。 /plan 和 /build 之间可随时来回切 /think on / off 开关 extended thinking(对支持的模型 — Claude / DeepSeek-R1 / GLM-4.5 等)。开启后模型会输出推理过程,代价是更慢更费 token /think budget <N> 给 thinking 设个 token 预算上限(对 Claude 系列生效),控制推理长度"},{"id":"永久记忆","heading":"永久记忆","body":"命令 作用 /remember <内容> 记一条到项目级记忆(默认作用域,绑定当前工作目录) /remember --global <内容> 记一条到全局记忆(所有项目共享) /forget <关键词> 删除全局 + 项目记忆中含该关键词的所有条目(大小写不敏感) /memory 查看当前生效的所有记忆,按 [Global] / [Project] 分组 详细使用与最佳实践见 永久记忆 。"},{"id":"扩展生态","heading":"扩展生态","body":"命令 作用 /setup 第一次执行时,把内置的 atomcode-automation-recommender skill 解压到 ~/.atomcode/skills/ ,在项目 .gitignore 追加 .atomcode/local/ ,并写 .atomcode/setup-state.json (signals 哈希 + atomcode 版本 + 已安装列表),全程持项目级锁。然后自动调用 recommender skill — 它会扫描项目(语言、框架、已有 hook 等)、联网检索并推荐适合该代码库的其他 atomcode skill 安装。后续执行会跳过 seed 安装、直接重跑 skill。命令后跟的文字会作为 steering 传给 skill,例如 /setup 重点关注测试 。CLI 形式 atomcode setup --force 会按内容哈希强制重装 seed 文件 /skills 浏览当前已加载的 skills(项目级 + 用户级)。每个 skill 也会以独立的斜杠命令形式出现在补全菜单里,可以直接 /<skill-name> 触发 /plugin 打开交互式插件管理器,可浏览 marketplace、安装/卸载插件、添加/移除 marketplace /plugin marketplace add|remove|update|list 管理 marketplace 注册(add 克隆 git 仓库,remove 移除,update 拉最新,list 列出) /plugin install <plugin>@<marketplace> 从指定 marketplace 安装插件 /plugin uninstall <plugin>@<marketplace> 卸载已安装的插件(保留 marketplace 注册) /plugin list 列出本地已安装的插件 /plugin reload 重新加载所有插件(扫描磁盘变更、刷新 skill/hook 注册) 详细配置与使用见 Skills 扩展 和 Plugin 系统 。"},{"id":"mcp-集成","heading":"MCP 集成","body":"命令 作用 /mcp 列出已成功连接的 MCP server 及其状态(连接失败的 server 不在此列表,只在会话区有红色错误行) /mcp tools <server> 异步列出某个 MCP server 实际暴露的远端 tools(若超时/失败会提示) /mcp reload 重新读取 .mcp.json / ~/.atomcode/mcp.json 并后台重连所有 server 详细配置与使用见 MCP 集成 。"},{"id":"webui-与同步","heading":"WebUI 与同步","body":"命令 作用 /webui 启动浏览器界面并自动打开浏览器(默认绑定 127.0.0.1:13457 ,仅本机)。当前 TUI 会话会自动接入实时同步 /webui --host <addr> 把服务绑定到指定地址; /webui lan 等价于 --host 0.0.0.0 (暴露到局域网)。配合蒲公英虚拟 IP 可远程访问,见 远程访问指南 /webui stop 关闭 webui 服务 /sync 把当前 TUI 接入正在运行的 webui 会话(需先 /webui )。两端实时双向同步,多个浏览器 / 终端可同时围观同一会话 /sync off 退出同步,回到独立会话 详细见 WebUI 界面 。"},{"id":"配置与帮助","heading":"配置与帮助","body":"命令 作用 /status 显示登录状态、当前 provider、模型、上下文预算、CodingPlan 用量和重置时间 /whoami 显示当前 AtomGit 登录用户的用户名 / 邮箱 /config 显示 ~/.atomcode/config.toml 的路径 /reload 从磁盘热加载 ~/.atomcode/config.toml ,不需要重启 atomcode 就能让外部修改(或另一个终端的 /login 带来的变更)生效 /language 切换界面语言:自动检测( LC_ALL / LANG )、English、或 简体中文。立即生效并写回 ~/.atomcode/config.toml /welcome 重新打开 3 步首次启动向导(欢迎页 → 语言 → 接入方式)。会话非空时会先弹 y/N 二次确认,确认后清屏。语言和默认接入方式都可以从这里再调一次 /logout 清除 AtomGit OAuth token /upgrade 自动升级到最新版本;子命令 /upgrade rollback 回滚到上一个版本 /guide 内置上手向导: /guide 列出可问的主题(快速开始、换模型、MCP、Skills、记忆、后台任务、上下文、快捷键、配置), /guide <主题> 直接在对话里讲解(首次会自动安装 atomcode-skills 插件) /help 展示所有可用斜杠命令的列表 /keys 展示键盘快捷键参考(分组列出输入 / 历史 / 会话 / 弹层导航,并标注 Shift+Enter 、 Alt+Enter 在不同终端的兼容性)。详见 键盘快捷键 /quit 退出 atomcode(也可以连按两次 Ctrl+C )"},{"id":"命令使用技巧","heading":"命令使用技巧","body":"自动补全 —— 输入 / 后会立刻弹出补全菜单,用 ↑↓ 选择, Tab / Enter 确认。 模糊匹配 —— 补全支持子串匹配,比如输入 /prov 就能命中 /provider 。 打断正在进行的操作 —— 模型正在流式输出时按 Esc 可以打断,然后再输入新的命令或 prompt。 Skills 也会出现在菜单里 —— 当你在 Skills 目录 中添加了自定义命令后,它们会以相同格式出现在补全菜单里。"},{"id":"典型工作流","heading":"典型工作流","body":""},{"id":"第一次启动-一键接入","heading":"第一次启动 — 一键接入","body":"> /login ✔ Logged in as alice (alice, alice@example.com) ✔ CodingPlan claimed — CodingPlan Free · expires 2026-05-22 (29d / 30d) ✔ 3 models registered as AtomGit-* providers ✔ Default provider set to AtomGit-GLM > 你好"},{"id":"做完一件事前把成本看一眼","heading":"做完一件事前把成本看一眼","body":"> 重构 src/db 使用连接池 ... (AI 执行) > /cost Session token usage - Total output tokens: 8342 - Current turn tokens: 2156 - Context: 42K / 128K"},{"id":"问歪了就回退重问","heading":"问歪了就回退重问","body":"> 给所有函数加 JSDoc ... (回复跑偏了) > /undo 已回退到第 3 轮(共 3 轮)。 ⚠ 仅回滚了对话记忆,磁盘文件未恢复。如需还原代码,请手动处理或用 /diff 查看。 (刚才那条 prompt 已还原到输入框,可改完重发)"},{"id":"模型表现不好换一个再试","heading":"模型表现不好换一个再试","body":"> /model > (在弹出的菜单里选择 claude-opus-4-6) > 再试一次,这次注意保留原有注释"},{"id":"下一步","heading":"下一步","body":"快捷键 —— 命令和快捷键配合使用效率翻倍 会话与撤销 —— /resume 、 /undo 、 /compact 的详细行为 © 2026 AtomCode · MIT 报告问题"}]},{"slug":"keybindings","title":"快捷键","group":"使用","lede":"AtomCode 的 TUI 是基于 ratatui + crossterm 构建的,常用快捷键尽量贴近主流终端工具的约定。在会话里输入 /keys 可以随时把这张表打印到当前 scrollback, /help 则查看所有斜杠命令。","sections":[{"id":"快捷键","heading":"快捷键","body":"AtomCode 的 TUI 是基于 ratatui + crossterm 构建的,常用快捷键尽量贴近主流终端工具的约定。在会话里输入 /keys 可以随时把这张表打印到当前 scrollback, /help 则查看所有斜杠命令。"},{"id":"输入编辑","heading":"输入编辑","body":"按键 动作 Enter 发送消息 Ctrl+J 换行(所有终端通用 — 发送的是 LF 字节,等同于 Enter 的换行作用) \\ 后接 Enter 换行(atomcode 自带兜底语法,所有终端通用 — 行尾反斜杠会被识别为续行) Alt+Enter 换行(多数终端可用;macOS Apple Terminal 需在 Settings → Profiles → Keyboard 启用 \"Use Option as Meta key\";Windows Terminal 默认占用,可在设置里释放) Shift+Enter 换行(仅以下终端区分 Shift+Enter 与 Enter :Kitty / WezTerm / iTerm2(需启用 Report Modifiers)/ Windows Terminal / Ghostty / Warp。Apple Terminal、xterm、GNOME Terminal、VS Code 集成终端不支持,请用 Ctrl+J 或 \\ + Enter ) Ctrl+Enter 换行(需启用 Kitty 键盘协议的终端,如 Kitty、WezTerm 等) Esc 清空当前输入 / 打断正在流式输出的回复 ↑ / ↓ 浏览输入历史 Tab 接受补全(斜杠命令菜单、文件路径等) Ctrl+U 清空整行 Ctrl+W 删除一个单词 Ctrl+K 删除从光标到行尾的内容 Ctrl+A 光标移到行首 Ctrl+E 光标移到行尾"},{"id":"浏览与滚动","heading":"浏览与滚动","body":"按键 动作 Shift+↑ / Shift+↓ 翻一行 PageUp / PageDown 翻一页(10 行) Alt+↑ / Alt+↓ 跳到上 / 下一条消息(macOS Apple Terminal 需先在 Settings → Profiles → Keyboard 启用 \"Use Option as Meta key\") Ctrl+↑ / Ctrl+↓ 跳到上 / 下一条 自己发的 消息 Home / End 跳到对话最顶端 / 最底端 鼠标滚轮 在聊天区上下滚(atomcode 接管) Ctrl+L 清空当前会话的消息"},{"id":"选区与复制","heading":"选区与复制","body":"按键 / 操作 动作 鼠标拖选 在聊天区选中文本(atomcode 接管,选区会自动滚动到边界) Shift+ 拖鼠标 用宿主终端原生选区(绕过 atomcode,适合跨视区多行复制) Ctrl+Shift+C 复制选区到系统剪贴板 /copy 复制 AI 的最后一条完整回复 右键菜单 在某些终端中可直接复制/粘贴(取决于终端而非 atomcode)"},{"id":"流程控制","heading":"流程控制","body":"按键 动作 Esc 取消当前正在进行的工具调用或流式输出 Ctrl+C 第一次:取消当前操作;连按第二次:退出程序 Ctrl+D 在输入框为空时,等同退出"},{"id":"工具权限对话框","heading":"工具权限对话框","body":"当模型准备执行危险操作(破坏性 bash 命令、写敏感文件、删除源码等)时,AtomCode 会弹出一个确认对话框,此时: 按键 动作 y / Enter 允许这一次 a 本次会话内始终允许这种模式 n / Esc 拒绝 别贪心 \"始终允许\"是按 工具名 + 参数模式 级别授予的,仅对当前会话生效,下次重启归零。如果你需要跨会话常驻的例外,请在配置层面处理(比如对某些路径做白名单)。"},{"id":"下一步","heading":"下一步","body":"斜杠命令 —— 记住了快捷键,也别忘记命令补全 会话与撤销 —— /undo 的精确含义 © 2026 AtomCode · MIT 报告问题"}]},{"slug":"sessions","title":"会话与撤销","group":"使用","lede":"AtomCode 默认持久化每一次对话,允许你随时恢复、继续、清空或压缩。一条 /undo 就能把对话记忆回退到此前任意一轮。","sections":[{"id":"会话与撤销","heading":"会话与撤销","body":"AtomCode 默认持久化每一次对话,允许你随时恢复、继续、清空或压缩。一条 /undo 就能把对话记忆回退到此前任意一轮。"},{"id":"会话的生命周期","heading":"会话的生命周期","body":"每次启动 atomcode 都会自动创建一个会话,会话包含: 完整消息历史(用户 prompt、AI 回复、工具调用) 关联的工作目录 关联的 provider / 模型 Token 消耗统计 该会话中所有文件编辑的 file-history 快照 会话数据落盘在 ~/.atomcode/sessions/ 下,按项目(工作目录 hash)分组存储。"},{"id":"恢复会话","heading":"恢复会话","body":""},{"id":"命令行继续上次","heading":"命令行继续上次","body":"atomcode -c # 或 atomcode --continue 最常见的需求:接着昨天停下来的地方继续。"},{"id":"tui-内切换会话","heading":"TUI 内切换会话","body":"/resume 弹出会话选择器,按时间倒序显示当前项目的历史会话,可以快速跳到任一会话。每一条都带有最近的用户提问作为标题,便于识别。"},{"id":"新开一个干净会话","heading":"新开一个干净会话","body":"/session 在不切换工作目录的前提下开启全新的上下文。适合\"刚刚那个任务已经收尾,我要开始完全不相关的另一件事\"。"},{"id":"bg","heading":"后台会话( /bg )","body":"需要同时跟进多条任务、又不想丢失当前对话上下文? /bg 把当前会话挪到后台、打开一个全新前台,随时可以切回去。最多 16 个并行后台槽位 。 命令 作用 /bg 把当前会话送到后台,打开新的前台 /bg list (别名 /bg ls ) 列出所有后台会话:编号、ID、状态、创建时间、摘要 /bg <N> 恢复第 N 号后台为前台(当前前台会被换下到后台) /bg drop <N> 丢弃第 N 号后台会话 /bg help (别名 -h 、 --help ) 显示内置帮助"},{"id":"会话状态","heading":"会话状态","body":"/bg list 的\"状态\"列对应会话在后台时的运行情况: 运行中 —— 模型还在执行,工具调用 / 输出在后台继续推进 空闲 —— 模型轮次跑完,等你的下一条 prompt 已完成 —— 会话已经显式结束 已取消 / 错误 —— 被中断或后台运行时出错 所以 /bg 后台并不只是\"挂起\"——模型真的会在后台继续干活,切回来时直接拿到结果。"},{"id":"background-任务-一次性后台派发","heading":"/background <任务> —— 一次性后台派发","body":"如果你不想专门切换前后台、只是\"顺手让它跑一下查个东西\",用 /background 兼容入口: /background 列出 src 下未使用的依赖 会在一个 /bg 槽位里启动一次性任务(默认配置为只读工具子集,不污染主对话上下文)。跑完后用 /bg list 看状态, /bg <N> 切过去读结果, /bg drop <N> 丢弃。 典型场景 主前台正在调试 A 模块,模型一边改一边跑 cargo check (耗时)。这时想到要顺便重构 B 模块——直接 /bg 切到新前台开始 B;A 那边的 build 在后台跑完状态切到\"已完成\", /bg 1 切回去拿结果。"},{"id":"清空-vs-压缩-vs-新建","heading":"清空 vs 压缩 vs 新建","body":"命令 保留历史 保留会话 ID 何时使用 /clear 否 是 想在同一会话里\"重置对话\",保留会话条目便于以后 /resume /compact 部分(摘要) 是 上下文快撑爆,但不想丢失之前的脉络 /session 另起一段 否(新 ID) 开始完全不相关的新任务"},{"id":"对话记忆回退-undo","heading":"对话记忆回退 /undo","body":"/undo 把 对话记忆 回退到某一轮之前,删除那一轮及其后的全部消息,并把那一轮你输入的 prompt 还原回输入框,方便你修改后重发。 /undo # 回退最后一轮 /undo N # 回退到第 N 轮(N 从 1 开始,只计你真实输入的轮次) 回退后,scrollback 里被删轮次的分隔线会一并清掉,会话也会立即落盘——下次 /resume 看到的就是回退后的状态。 注意边界 /undo 只 回滚对话记忆, 不会恢复磁盘上的文件 。如果那几轮里 AI 改过代码,这些改动仍保留在工作区——需要还原请用 /diff 查看后手动处理,或借助 git。当前回合进行中时无法 /undo ,请先按 Esc 取消。"},{"id":"查看和清理成本","heading":"查看和清理成本","body":"/cost 显示当前会话累计输入 / 输出 tokens。当数字逼近 provider 的 context_window 时: 用 /compact 压缩历史,让早期消息变成摘要 或者直接 /session 开新会话 不想用上下文窗口中的工具调用结果,可以让模型在 prompt 里明确\"别再读那些大文件\""},{"id":"多项目工作流","heading":"多项目工作流","body":"AtomCode 的会话是按工作目录分组的。切换目录的推荐方式: 从命令行启动时用 -C 指定 运行中用 /cd 切换, default_workdir 会自动落盘"},{"id":"下一步","heading":"下一步","body":"项目指令文件 —— 用 .atomcode.md 为每个项目固化上下文 © 2026 AtomCode · MIT 报告问题"}]},{"slug":"tools","title":"内置工具","group":"进阶","lede":"AtomCode 目前内置 21 个工具,按能力分成文件与 Shell、代码图谱、Web、自动化四类。模型会根据任务自动挑选,大多数情况下你不需要手动指定。","sections":[{"id":"内置工具","heading":"内置工具","body":"AtomCode 目前内置 21 个工具,按能力分成文件与 Shell、代码图谱、Web、自动化四类。模型会根据任务自动挑选,大多数情况下你不需要手动指定。"},{"id":"文件与-shell9-个","heading":"文件与 Shell(9 个)","body":"工具 作用 需要确认 read_file 读取文件内容,支持行号偏移与范围 否 write_file 写入完整文件内容(覆盖写) 敏感路径:是 edit_file 基于字符串匹配的局部编辑,返回编辑上下文 敏感路径:是 search_replace 批量字符串替换,适合跨行 / 多处模式 敏感路径:是 bash 执行 shell 命令,破坏性命令会触发权限对话框 破坏性命令:是 grep 基于 ripgrep 语义的正则搜索 否 glob 文件名通配符匹配(如 src/**/*.ts ) 否 list_directory 列出目录内容 否 change_dir 切换 agent 的当前工作目录 否 敏感路径 写入 /etc 、 ~/.ssh 、shell 配置文件等路径会强制触发权限对话框,无法用\"始终允许\"一次性跳过。源码文件的 rm 删除同样需要显式确认。 后台运行长任务 给 bash 传 run_in_background: true ,命令会以独立进程在后台启动并 立即返回 PID 与日志文件路径,进程在多轮对话间持续存活 —— 适合开发服务器、文件监听、隧道等长跑任务,不必阻塞会话。 破坏性命令拦截 rm -rf 、 dd 、 mkfs 、 sudo 等高危命令,以及会清库重建表的数据库迁移(如 migrate:fresh 、 db:reset )都会强制弹出权限确认。这类确认 始终 触发 —— 即便之前对 bash 选过\"始终允许\"也不能跳过。"},{"id":"代码图谱8-个","heading":"代码图谱(8 个)","body":"这是 AtomCode 区别于一般 agent 的最大亮点。借助代码图谱索引,模型无需读遍整棵代码树就能精准定位符号、引用和调用关系,在大型仓库上效果尤其明显。 工具 作用 list_symbols 列出某个文件或目录下定义的所有符号(函数、类、常量等) read_symbol 精准读取某个符号的完整定义片段,而不用把整个文件拉进上下文 find_references 查找某个符号被引用的所有位置 trace_callers 回溯某个函数的调用方链路 trace_callees 展开某个函数内部调用了哪些下游 trace_chain 在两个符号之间搜索可能的调用链 file_deps 分析某个文件的 import/依赖关系 blast_radius 评估修改某个符号可能影响到的文件 / 符号范围"},{"id":"典型使用场景","heading":"典型使用场景","body":"重构前评估风险 —— \"我想改 formatDate 的签名,影响面有多大?\"模型会调用 blast_radius + find_references 。 定位 Bug 根源 —— \"用户点击按钮为什么没响应?\" 从入口函数开始 trace_callees ,一路下探。 读懂陌生代码 —— \"帮我讲讲 AuthService.login 是怎么跑的\" &rarr; read_symbol + trace_callees 。"},{"id":"web2-个","heading":"Web(2 个)","body":"工具 作用 web_search 在 web 上搜索关键词,返回标题 / 摘要 / URL 列表 web_fetch 抓取某个 URL 的内容并转换为 markdown 供模型阅读 典型用途:查最新的文档、对比不同库的 API、读取一篇 GitHub issue。在离线环境或想省钱时可以用 --disable-tools web_search,web_fetch 关掉它们。"},{"id":"自动化2-个","heading":"自动化(2 个)","body":"工具 作用 auto_fix 运行项目的 lint / typecheck,按错误列表循环修复直到通过 use_skill 调用用户自定义的 skill,把一个多步流程打包成可复用的命令 详见 Skills 扩展 。"},{"id":"禁用特定工具","heading":"禁用特定工具","body":"用 --disable-tools 参数可以在启动时把某些工具对模型完全隐藏。例如在 SWE-bench 沙箱里: atomcode -p \"solve this issue\" --disable-tools web_search,web_fetch 禁用后的工具不会出现在 tool schemas 里,模型不会尝试去调用一个必然失败的工具。"},{"id":"下一步","heading":"下一步","body":"会话与撤销 —— 文件编辑工具都会走 file-history, /undo 可以回滚 Skills 扩展 —— 用 use_skill 包装你自己的工作流 © 2026 AtomCode · MIT 报告问题"}]},{"slug":"skills","title":"Skills 扩展","group":"进阶","lede":"Skill 是用户自定义的、可复用的命令,它本质上是一段带 frontmatter 的 markdown 指令,告诉 AI\"在这种任务下应该怎么做\"。写好 skill 之后,它会像内置斜杠命令一样出现在菜单里,或者被 use_skill 工具按需调用。","sections":[{"id":"skills-扩展","heading":"Skills 扩展","body":"Skill 是用户自定义的、可复用的命令,它本质上是一段带 frontmatter 的 markdown 指令,告诉 AI\"在这种任务下应该怎么做\"。写好 skill 之后,它会像内置斜杠命令一样出现在菜单里,或者被 use_skill 工具按需调用。"},{"id":"skill-能做什么","heading":"Skill 能做什么","body":"把常见工作流固化下来: 发布 release、写 changelog、跑回归测试、生成周报… 封装需要一步一步引导的复杂任务: 代码重构流程、bug 根因分析、性能调优 让模型在特定话题下遵循你定义的步骤和校验规则"},{"id":"skill-文件结构","heading":"Skill 文件结构","body":"一个 skill 通常是一个目录,里面至少包含一个 SKILL.md : my-skills/ ├── release/ │ └── SKILL.md ├── write-changelog/ │ └── SKILL.md └── debug-flaky-test/ ├── SKILL.md └── references/ └── pattern-library.md SKILL.md 的典型格式: --- name: release description: 发布一个新的 release tag,更新 changelog,并打包 --- ## 何时使用 当用户说\"发布新版本\"、\"出一个 release\"、\"打 tag\" 时使用。 ## 步骤 1. 通过 `git log` 确认上次发布以来的改动 2. 让用户确认 semver 版本号(patch / minor / major) 3. 更新 `CHANGELOG.md` 中新增条目 4. 运行 `pnpm build` 并确保构建通过 5. 创建 git tag `v<version>` 并写上发布说明 6. 运行 `pnpm publish`(或者对应的发布命令) ## 规则 - 版本号必须符合 semver - 不允许绕过测试,任何失败都必须先修复 - 发布失败时,回滚所有本地 tag 和 changelog 改动"},{"id":"skill-目录","heading":"Skill 目录","body":"AtomCode 会从若干约定位置加载 skills: 全局 : ~/.atomcode/skills/ 项目级 :当前工作目录及其上级的 .atomcode/skills/ (如有) 项目级会覆盖同名全局 skill,方便你在不同项目用同一个名字定义不同流程。"},{"id":"调用方式","heading":"调用方式","body":""},{"id":"通过斜杠命令","heading":"通过斜杠命令","body":"所有加载成功的 skill 会自动出现在斜杠命令补全菜单里: > /release > /write-changelog > /debug-flaky-test"},{"id":"通过-菜单","heading":"通过 $ 菜单","body":"在输入框行首打一个 $ ,会弹出一个 skills 菜单(和 /skills 列出的是同一批可调用技能);继续输入可过滤, Tab 补全高亮项的名字,提交 $<name> [参数] 即调用该 skill。它和斜杠命令是两套并行入口: / 走斜杠命令补全, $ 专门用来挑 skill,后面还能直接带参数,例如 $brainstorming 帮我想登录方案 。"},{"id":"模型自动触发","heading":"模型自动触发","body":"模型可以主动调用 use_skill 工具,把一个与任务相关的 skill 作为子流程运行。比如你说\"帮我发布新版本\",即便不显式打 /release ,模型也可能自动选择调用这个 skill。"},{"id":"写好一个-skill-的几条经验","heading":"写好一个 skill 的几条经验","body":"description 要具体 —— 它决定了菜单里的描述文本,也是模型判断\"要不要用这个 skill\"的主要依据。 步骤要有序 —— 模型会按顺序读,把强依赖步骤放在前面。 明确分支 —— \"如果 build 失败则…;否则…\",比让模型自己猜要可靠得多。 列出红线 —— 绝对不能做的事情放在独立的\"规则\"小节,提高顺从度。 必要时用子文档 —— 把很长的参考资料放到 references/*.md ,只在 SKILL.md 里留一句\"必要时参见…\"。"},{"id":"与项目指令的分工","heading":"与项目指令的分工","body":"场景 放在 始终生效的项目约定(技术栈、代码风格、命令) .atomcode.md 某个特定流程、需要被显式触发 Skill 只需要一次的临时要求 直接写在 prompt 里"},{"id":"下一步","heading":"下一步","body":"基本使用 —— 回到日常使用场景 常见问题 —— 为什么我的 skill 没出现在菜单里? © 2026 AtomCode · MIT 报告问题"}]},{"slug":"mcp","title":"MCP 集成","group":"进阶","lede":"MCP（Model Context Protocol）是一个开放协议,把外部程序或 HTTP 服务的「工具」接到 AtomCode,让模型像调用内置工具一样使用它们。从 v4.20.4 起 AtomCode 内置 MCP 客户端,直接复用 Cursor 等同样使用 mcpServers 配置块的生态。","sections":[{"id":"mcp-集成","heading":"MCP 集成","body":"MCP（Model Context Protocol）是一个开放协议,把外部程序或 HTTP 服务的「工具」接到 AtomCode,让模型像调用内置工具一样使用它们。从 v4.20.4 起 AtomCode 内置 MCP 客户端,直接复用 Cursor 等同样使用 mcpServers 配置块的生态。"},{"id":"它能做什么","heading":"它能做什么","body":"通过官方 MCP server 操作 GitHub、GitLab、Jira 等外部服务 接 Postgres / MySQL / DuckDB 等数据库 使用文件系统、Playwright 浏览器、Slack 消息等社区生态 server 把团队内部的领域工具暴露给模型,无需改 atomcode 源码"},{"id":"两个配置位置","heading":"两个配置位置","body":"路径 作用域 <项目根>/.mcp.json 仅当前项目可见,适合跟代码同仓库 ~/.atomcode/mcp.json 用户全局,跨所有项目共享 两份可同时存在; 同名 server 以项目级为准 (覆盖用户级)。仓库根目录的 .mcp.json.example 自带 stdio 与 HTTP 双模板和详细注释,推荐从它开始改。"},{"id":"配置-schema","heading":"配置 schema","body":"顶层键固定为 mcpServers (旧键 servers 仍兼容)。每个 server 建议只写一种 transport: stdio : command (必填)+ 可选 args 、 env 、 timeout_ms 、 disabled HTTP : url (必填)+ 可选 headers 、 auth 、 timeout_ms 、 disabled 如果同一个 server 同时写了 command 和 url ,当前实现会优先按 stdio( command )处理;为避免歧义,对外配置请不要双写。 字符串里支持 ${VAR} 与 ${VAR:-默认值} 的环境变量展开;敏感令牌不要写死,放到环境变量里。 disabled: true 可临时关掉某个 server 而不删条目。"},{"id":"stdio-示例本地子进程","heading":"stdio 示例(本地子进程)","body":"{ \"mcpServers\": { \"filesystem\": { \"command\": \"npx\", \"args\": [\"-y\", \"@modelcontextprotocol/server-filesystem\", \"/tmp\"], \"timeout_ms\": 10000 } } }"},{"id":"http-示例远程端点","heading":"HTTP 示例(远程端点)","body":"{ \"mcpServers\": { \"github\": { \"url\": \"https://api.githubcopilot.com/mcp/\", \"headers\": { \"Authorization\": \"Bearer ${GITHUB_TOKEN}\" }, \"timeout_ms\": 30000 } } }"},{"id":"github-remote-mcp-oauth","heading":"GitHub remote MCP + OAuth","body":"{ \"mcpServers\": { \"github\": { \"url\": \"https://api.githubcopilot.com/mcp/\", \"auth\": { \"type\": \"oauth\", \"provider\": \"github\" } } } } 首次使用前需准备 AtomCode 自己的 GitHub OAuth App client id,然后运行: atomcode mcp add-github-oauth --global ATOMCODE_GITHUB_MCP_CLIENT_ID=<client_id> atomcode mcp login github atomcode TUI 内也可在设置好环境变量后运行 /mcp login github ,登录成功后用 /mcp reload 重连。"},{"id":"一行命令添加-server","heading":"一行命令添加 server","body":"atomcode mcp add 自动把 stdio 配置写入 JSON,不用手动编辑: # 写入项目根 .mcp.json(默认当前目录) atomcode mcp add playwright npx @playwright/mcp@latest # 写入用户全局 ~/.atomcode/mcp.json atomcode mcp add playwright npx @playwright/mcp@latest --global # 指定项目目录 atomcode mcp add playwright npx @playwright/mcp@latest -C /path/to/repo 第一个参数是 server 键名(将出现在工具名里),后面跟可执行文件 + 参数。 GitHub remote MCP OAuth 可用专用入口: atomcode mcp add-github-oauth --global ATOMCODE_GITHUB_MCP_CLIENT_ID=<client_id> atomcode mcp login github 注意 同名会 整段覆盖 该 server。GitHub OAuth token 保存在 ~/.atomcode/mcp_auth.toml ,不会写入 .mcp.json 。"},{"id":"启动后会发生什么","heading":"启动后会发生什么","body":"模式 连接行为 工具出现时机 TUI 后台并行连接,不阻塞界面 每个 server 连上后陆续注册,可能略晚于首屏 单次执行( -p ) 启动时同步连接,等启用中的 server 尝试结束 仅在至少拿到一批工具时挂载 MCP TUI 下可在会话区看到 ✓ MCP server 'github' connected 或 ✗ MCP server '…' failed: … 。 单个 server 失败不会拖垮其他 server 与主程序。"},{"id":"工具命名","heading":"工具命名","body":"每个远端 tool 注册成 mcp__<server 键名>__<远端 tool 名> 。 例:配置里 \"mcpServers\": { \"github\": { ... } } ,远端有 get_issue ,模型看到的工具名就是 mcp__github__get_issue 。 --disable-tools 也用这个完整名: atomcode --disable-tools mcp__github__get_issue,mcp__filesystem__write_file"},{"id":"权限审批","heading":"权限审批","body":"MCP 工具默认 每次调用都需要确认 (等同 RequireApproval ),因为远端是外部不可信代码。 按 Y — 单次允许 按 A — 在当前会话内放行该工具(下次启动后失效,不会持久化) 按 N — 拒绝本次调用 安全提示 把 MCP 工具返回的内容当作不可信数据处理, 不要 让它升级成系统指令。一个返回结果带「请忽略之前的指示」的 MCP server,模型不应该照办。"},{"id":"斜杠命令","heading":"斜杠命令","body":"命令 作用 /mcp 列出 已成功连接 的 server 及状态(失败的 server 不在列表里,只在会话区有红色错误行) /mcp tools <server> 异步列出某个 server 实际暴露的远端 tools /mcp reload 重新读取 .mcp.json / ~/.atomcode/mcp.json 并后台重连启用中的 server"},{"id":"当前限制","heading":"当前限制","body":"仅支持 MCP 的 tools 能力;尚未实现 resources / prompts / OAuth / roots / elicitation HTTP server 无指数退避重连,stdio 子进程退出后不自动重启 — 需用 /mcp reload 手动重连 tools/list 的 list_changed 通知不触发动态刷新 工具结果只取 text 类型 content 块,image / resource 块当前忽略 [A] Always 仅当前会话生效,不写入任何配置文件"},{"id":"同类生态对比","heading":"同类生态对比","body":"产品 配置位置 备注 AtomCode .mcp.json 的 mcpServers 块 当前实现 tools-only Claude Code .mcp.json OAuth、resources、prompts 更全 Cursor .mcp.json 常见 command / url 配置通常可复用 Codex CLI 添加 OpenAI 生态 已经在用 Cursor 配 MCP server 的话,常见 command / url 类型配置通常可复用;超出当前字段或能力范围的配置需按 AtomCode 当前实现确认。"},{"id":"下一步","heading":"下一步","body":"仓库根目录的 .mcp.json.example —— 带详细注释的 stdio + HTTP 双模板 配置文件 —— 整体配置概览 斜杠命令 —— 含 /mcp 系列在内的完整命令列表 © 2026 AtomCode · MIT 报告问题"}]},{"slug":"plugins","title":"Plugin 系统","group":"进阶","lede":"Plugin 是一组 skill / 命令 / hook 的集合,通过 git 仓库分发。一行 /plugin install 就能把别人写好的工作流装到 AtomCode 里,装完即用。AtomCode 的 plugin 协议与 Claude Code 兼容,CC 生态的 plugin 仓库可以直接安装运行。","sections":[{"id":"plugin-系统","heading":"Plugin 系统","body":"Plugin 是一组 skill / 命令 / hook 的集合,通过 git 仓库分发。一行 /plugin install 就能把别人写好的工作流装到 AtomCode 里,装完即用。AtomCode 的 plugin 协议与 Claude Code 兼容,CC 生态的 plugin 仓库可以直接安装运行。"},{"id":"核心概念","heading":"核心概念","body":"Marketplace —— 一个 git 仓库,根目录有 .atomcode-plugin/marketplace.json 或 .claude-plugin/marketplace.json ,声明它包含哪些 plugin。 Plugin —— marketplace 里的一个条目,可以是同仓库的子目录,也可以指向**外部 git 仓库**( url / github / git )或**本地路径**( local )。 Skill / 命令 / Hook —— plugin 安装后会贡献的三类资产。skill 与命令带 plugin-name: 命名空间(避免冲突),hook 按事件触发。"},{"id":"命令速查","heading":"命令速查","body":"命令 作用 /plugin 打开 交互式插件管理器 (上/下选择,回车确认,Esc 返回),可在里面浏览 marketplace、安装/卸载插件、添加/移除 marketplace /plugin marketplace add <url> 克隆一个 git 仓库并注册为 marketplace /plugin marketplace remove <name> 移除已注册的 marketplace(若其下还有已装插件会拒绝) /plugin marketplace update <name> 拉取该 marketplace 仓库的最新提交,刷新可用插件列表 /plugin marketplace list 列出所有已注册的 marketplace /plugin install <plugin>@<marketplace> 从指定 marketplace 安装一个插件 /plugin uninstall <plugin>@<marketplace> 卸载已安装的插件(保留 marketplace 注册) /plugin list 列出本地已安装的所有插件 /plugin reload 重新加载所有插件(扫描磁盘变更、刷新 skill/hook 注册)"},{"id":"装一个-plugin","heading":"装一个 plugin","body":""},{"id":"方式-1交互式管理器推荐","heading":"方式 1:交互式管理器(推荐)","body":"在 TUI 中直接输入 /plugin (不带任何子命令),会打开一个全屏交互式管理器。通过方向键导航、回车确认: /plugin # → 打开管理器主菜单: # Browse & install — 浏览 marketplace 中的插件,回车安装/卸载 # Add marketplace… — 输入 git URL 添加新 marketplace # Remove marketplace… — 选择并移除已注册的 marketplace # Installed (N) — 查看已安装插件列表,回车卸载 安装插件时,已安装的会显示 ✓ 标记,回车即可切换安装/卸载。克隆和安装是异步的,操作期间底部会显示状态提示,完成后列表自动刷新。"},{"id":"方式-2命令行子命令","heading":"方式 2:命令行子命令","body":"# 1. 注册 marketplace(克隆其 git 仓库到本地) /plugin marketplace add https://gitcode.com/gmq123/ascend-model-agent-plugin # 2. 装其中的 plugin /plugin install ascend-model-agent-plugin@ascend-model-agent-plugin # 3. 列出已装 /plugin list"},{"id":"方式-3cli","heading":"方式 3:CLI","body":"atomcode plugin marketplace add <git-url> atomcode plugin install <plugin>@<marketplace> atomcode plugin list atomcode plugin uninstall <plugin>@<marketplace> atomcode plugin marketplace remove|update|list CLI 与 TUI 共享 ~/.atomcode/plugins/ 目录,任意一边装的另一边立即可见。"},{"id":"装完之后","heading":"装完之后","body":"plugin 贡献的 skill 出现在 / 菜单,带 <plugin-name>: 前缀。例如 /ascend-model-agent-plugin:ascend-model-verification 。 模型也能通过 UseSkill 工具自动调用这些 skill。 Hook 立即激活 —— v4.21.1 起 /plugin install 完成后自动重建 hook executor,不再需要 /cd 或重启。"},{"id":"目录布局","heading":"目录布局","body":"~/.atomcode/plugins/ ├── marketplaces.json # 注册的 marketplace 元数据 ├── installed_plugins.json # 已装 plugin 的状态记录 ├── marketplaces/ │ └── <marketplace-name>/ # marketplace 仓库克隆 │ ├── .claude-plugin/marketplace.json │ └── <plugin-subdir>/ # inline plugin └── installed/ └── <marketplace>/<plugin>/ # 外部 source 的 plugin 克隆"},{"id":"pluginjson-内嵌结构","heading":"plugin.json 内嵌结构","body":"每个 plugin 根目录(或 .claude-plugin/ / .atomcode-plugin/ 子目录)下的 plugin.json : { \"name\": \"my-plugin\", \"version\": \"1.0.0\", \"description\": \"干啥用的\", \"skills\": [\"./skills\"], // 也接受字符串 \"skills\" \"commands\": [\"./commands\"], \"hooks\": { // 也接受路径字符串 \"hooks.json\" \"UserPromptSubmit\": [{ \"hooks\": [{ \"type\": \"command\", \"command\": \"python \\\"${CLAUDE_PLUGIN_ROOT}/hook.py\\\"\", \"timeout\": 5 }] }] } }"},{"id":"hook-事件","heading":"Hook 事件","body":"plugin 可以挂以下事件(与 CC 一致): 事件 触发时机 用途 UserPromptSubmit 用户消息提交后,LLM 调用前 注入额外上下文 / 路由 / 阻断 PreToolUse 工具调用前 校验、阻断、改参 PostToolUse 工具调用后 审计、副作用 SessionStart session 启动 预热、记录 SessionEnd session 结束 清理、归档 Notification 系统通知 转发外部告警通道"},{"id":"userpromptsubmit-io-协议","heading":"UserPromptSubmit IO 协议","body":"Hook 通过 stdin 拿到 JSON,通过 stdout 决定如何处理: { \"session_id\": \"...\", \"hook_event_name\": \"UserPromptSubmit\", \"prompt\": \"用户输入的文本\", \"cwd\": \"/工作目录\" } Hook 可以用以下方式响应(优先级由高到低): 退出码非零 —— 阻断 prompt,reason 取自 stderr。 stdout 输出 JSON {\"decision\": \"block\", \"reason\": \"...\"} —— 阻断,显式给原因。 stdout 输出 JSON {\"hookSpecificOutput\": {\"additionalContext\": \"...\"}} —— 把 additionalContext 追加到用户消息后,作为 LLM 的额外上下文。 stdout 输出纯文本 —— 整段作为 additionalContext 注入。 空 stdout / 不可解析 JSON —— 放行,prompt 原样进入 LLM。 AtomCode 解析 stdout 时,优先用 最后一个非空行 试 JSON;失败再回退到整段文本注入 —— 让 hook 脚本可以前置打印 debug 输出而不影响最终决策。"},{"id":"路径变量","heading":"路径变量","body":"Hook 命令字符串中可以引用以下环境变量(由 executor 注入): ${CLAUDE_PLUGIN_ROOT} —— plugin 安装目录绝对路径(CC 兼容)。 ${ATOMCODE_PLUGIN_ROOT} —— 同上,atomcode 别名。 这些是 真实环境变量 由 shell 自身展开,不是字符串替换 —— 安装路径含空格、引号、 $ 、 ; 都不会破命令。"},{"id":"marketplace-管理","heading":"Marketplace 管理","body":"# 列出已注册的 marketplace /plugin marketplace list # 拉最新提交(更新该 marketplace 包含的 plugin 列表) /plugin marketplace update <name> # 移除(若该 marketplace 下还有 plugin 装着,会拒绝) /plugin marketplace remove <name>"},{"id":"实战装昇腾插件","heading":"实战:装昇腾插件","body":"/plugin marketplace add https://gitcode.com/gmq123/ascend-model-agent-plugin # > cloning marketplace from https://gitcode.com/... # > marketplace `ascend-model-agent-plugin` added at 7a59537 (1 plugins) /plugin install ascend-model-agent-plugin@ascend-model-agent-plugin # > installing `...`... # > installed `ascend-model-agent-plugin@ascend-model-agent-plugin` — 23 skills loaded, 5 skipped # 这个 plugin 装了一个 UserPromptSubmit hook(workflow_planner_hook.py), # 当你说\"帮我验证 Qwen3 在昇腾上的适配\"时,它会注入一份 workflow JSON, # 让模型按照 ascend-model-verification skill 链路执行。 帮我验证 Qwen3 在昇腾上的适配"},{"id":"已知限制","heading":"已知限制","body":"不支持的 CC 事件 : Stop / PreCompact / SubagentStop 当前会被静默跳过。 多行 indent JSON 输出 :hook 用 print(json.dumps(..., indent=2)) 输出多行 JSON 时,最后一行是 } ,我们的最后一行 JSON parser 会失败,回退到纯文本注入。功能上没问题(LLM 仍能读到内容),但不是结构化路径。建议 hook 作者用单行 json.dumps(...) 输出。 Skill 名校验严格 : [a-z0-9_-] ,与 CC 一致。带 / 或大小写混合的 skill 名会被 skip。"},{"id":"下一步","heading":"下一步","body":"Skills 扩展 —— 写自己的 skill,plugin 里也能用。 斜杠命令 —— 完整的 /plugin 命令列表。 MCP 集成 —— 接入外部工具的另一条路径,与 plugin 互补。 © 2026 AtomCode · MIT 报告问题"}]},{"slug":"memory","title":"永久记忆","group":"进阶","lede":"用 /remember 把零碎的偏好、约定、命令记下来,AtomCode 会在每一轮对话的系统提示里把它们带给模型。和 .atomcode.md 项目指令文件 互补:指令文件适合写整篇规范,记忆适合积累那些\"突然想起来该告诉它\"的零散事实。","sections":[{"id":"永久记忆","heading":"永久记忆","body":"用 /remember 把零碎的偏好、约定、命令记下来,AtomCode 会在每一轮对话的系统提示里把它们带给模型。和 .atomcode.md 项目指令文件 互补:指令文件适合写整篇规范,记忆适合积累那些\"突然想起来该告诉它\"的零散事实。"},{"id":"命令总览","heading":"命令总览","body":"命令 作用 /remember <内容> 记一条到 项目级 记忆(默认作用域,绑定当前工作目录) /remember --global <内容> 记一条到 全局 记忆(所有项目共享) /forget <关键词> 删除全局 + 项目记忆中含该关键词的所有条目(大小写不敏感),输出会列出删了哪些条目 /memory 查看当前生效的所有记忆,按 [Global] / [Project] 分组并显示磁盘路径"},{"id":"存储位置","heading":"存储位置","body":"作用域 路径 全局 ~/.atomcode/memory.md (或 $ATOMCODE_HOME/memory.md ) 项目 <project_root>/.atomcode/memory.md 格式是普通 Markdown,每行一条 - 开头的列表项。可以用 /remember 也可以直接手编辑——AtomCode 在下一轮会重新读取。 非 - 开头的行会被忽略 ,所以可以加注释、空行、标题分组,记忆条目本身不受影响。"},{"id":"模型怎么用这些记忆","heading":"模型怎么\"用\"这些记忆","body":"每次发请求时,AtomCode 会把 全局 + 项目记忆合并 注入到系统提示里( crates/atomcode-core/src/agent/prompt.rs:64 ),格式如下: === MEMORY === The user has asked you to remember these facts and preferences: [Global] - 用户偏好简洁回答,避免冗长解释 - 中文回复,但 commit message 用英文 [Project: atomcode] - 测试命令是 cargo test --workspace --no-fail-fast - CI 失败时先看 .github/workflows/ci.yml 第 78-92 行 模型每个 turn 都能看到这块。 没有\"语义检索\"或\"按需召回\" ——是无条件全量注入,所以记忆条目越多,每个 turn 消耗的 token 越多。务必删除过时的条目,保持精简。"},{"id":"容量限制","heading":"容量限制","body":"限制 数值 触发后行为 单个记忆文件大小 64 KB 只读末尾 64KB(按行边界对齐,不会切坏 UTF-8 字符) 注入提示的总字符 4000 字符 截断并附 [...truncated, run /memory to review] 提示 到上限就用 /forget 清理,把最近不再相关的条目删掉。"},{"id":"使用建议","heading":"使用建议","body":""},{"id":"1-项目特定的命令约定坑项目级","heading":"1. 项目特定的命令、约定、坑(项目级)","body":"> /remember 用 npm run check 跑类型检查(不是 npm run typecheck) > /remember CI 失败时先看 .github/workflows/ci.yml 第 78-92 行 > /remember 这个 repo 严禁用 sed -i 改文件(macOS/Linux 行为不一致) > /remember 数据库迁移 SQL 必须先在 staging 跑过才能上 main"},{"id":"2-全局编码偏好工作流全局","heading":"2. 全局编码偏好、工作流(全局)","body":"> /remember --global 改完代码先跑测试再 commit > /remember --global 不要主动 git push,让我手动确认 > /remember --global 中文回复,但 commit message 用英文 > /remember --global 优先编辑现有文件,不要擅自创建文档(*.md)"},{"id":"3-个人或团队信息全局","heading":"3. 个人或团队信息(全局)","body":"> /remember --global 我的 GitHub 用户名是 alice > /remember --global 默认时区 Asia/Shanghai > /remember --global 团队 standup 是周一周三周五 9:30"},{"id":"4-清理过时记忆","heading":"4. 清理过时记忆","body":"> /forget npm run check [project] - 用 npm run check 跑类型检查(不是 npm run typecheck) (removed 1 matching entry) > /memory [Global] (/Users/alice/.atomcode/memory.md) - 改完代码先跑测试再 commit - 不要主动 git push,让我手动确认 [Project] (/Users/alice/code/myrepo/.atomcode/memory.md) - CI 失败时先看 .github/workflows/ci.yml 第 78-92 行"},{"id":"记忆-vs-项目指令文件-vs-会话历史","heading":"记忆 vs 项目指令文件 vs 会话历史","body":"AtomCode 提供了三种持久化\"上下文\"的方式,各自定位不同: .atomcode.md 记忆(memory.md) 会话( /resume ) 适合内容 整篇规范、技术栈、详细约定 零散事实、个人偏好、命令速查 过去的对话和工具调用 作用范围 项目 项目 + 全局 具体某次会话 添加方式 手动编辑 /remember 或手动编辑 每次对话自动保存 注入机制 启动时注入系统提示 每轮注入系统提示 /resume 时整段恢复 token 预算 较大(整篇文档) 受 4000 字符上限 受上下文窗口限制 典型组合: 团队规范 写在 .atomcode.md 里(进 git,所有人共享) 个人偏好 用 /remember --global (只在你本机) 项目特定坑 用 /remember (留在项目本地的 .atomcode/memory.md ,可以选择是否进 git) 关于 .atomcode/memory.md 是否提交进 git:如果团队都用 AtomCode 且记忆是项目知识(如踩过的坑、约定),可以提交;如果是个人开发笔记,可以加进 .gitignore 。"},{"id":"下一步","heading":"下一步","body":"项目指令文件 —— 整篇规范的最佳入口 斜杠命令 —— 完整命令参考 会话与撤销 —— /resume 的细节 © 2026 AtomCode · MIT 报告问题"}]},{"slug":"project-instructions","title":"项目指令文件","group":"进阶","lede":"在项目根目录放一个 .atomcode.md ,可以把项目的技术栈、约定和偏好固化下来,AtomCode 启动时会自动把它注入系统提示,避免每次对话都要重复说一遍规则。","sections":[{"id":"项目指令文件","heading":"项目指令文件","body":"在项目根目录放一个 .atomcode.md ,可以把项目的技术栈、约定和偏好固化下来,AtomCode 启动时会自动把它注入系统提示,避免每次对话都要重复说一遍规则。"},{"id":"为什么需要它","heading":"为什么需要它","body":"设想这个常见场景:你的团队统一使用 Composition API,禁止 Options API。每次让 AtomCode 写新组件,你都得提醒一句\"用 Composition API\"。有了 .atomcode.md ,这类偏好会自动带进每一次对话。"},{"id":"文件位置","heading":"文件位置","body":"默认路径:项目根目录下的 .atomcode.md AtomCode 从当前工作目录向上逐级查找,直到找到或到达 $HOME 如果该文件不存在,系统提示中自然不会出现相关内容"},{"id":"示例","heading":"示例","body":"# Project Instructions 这是一个 Vue 3 + TypeScript 项目,使用 Pinia 做状态管理、 Tailwind 做样式、Vitest 做单元测试。 ## 约定 - 组件一律使用 `<script setup lang=\"ts\">` 风格的 Composition API - 样式只写 Tailwind,不写内联 style 和单独的 .css 文件 - 所有 API 调用走 `src/services/*`,不在组件里直接 fetch - 状态统一放进 Pinia store,组件内部不保留派生的全局状态 ## 常用命令 - 启动开发:`pnpm dev` - 类型检查:`pnpm typecheck` - 测试:`pnpm test` - 构建:`pnpm build` ## 注意事项 - 不要修改 `src/generated/*`,那是从 OpenAPI 自动生成的 - 测试覆盖率要求在 80% 以上,新增模块必须带单元测试"},{"id":"写好-atomcodemd-的几条经验","heading":"写好 .atomcode.md 的几条经验","body":"只写\"和一般情况不一样\"的部分 —— 通用最佳实践模型自己懂,不用在这里重复。 给出命令,而不是描述 —— \"跑测试用 pnpm test \",而不是\"请运行单元测试\"。 用祈使句 —— \"使用 X\"、\"不要 Y\",避免模棱两可的\"建议\"、\"尽量\"。 列出禁区 —— 哪些文件 / 目录不能动,点名就好。模型的顺从性很高。 控制长度 —— 每一行都会吃 token,保持在 30-80 行以内通常就够用了。 Tip 如果你有很多重复的工作流(比如每次修 bug 都要跑一套相同的命令),与其在 .atomcode.md 里长篇大论,不如写成一个 Skill ,更清晰也更可复用。"},{"id":"与-agentsmd-claudemd-geminimd-的关系","heading":"与 AGENTS.md / CLAUDE.md / GEMINI.md 的关系","body":"AtomCode 原生支持 AGENTS.md ——AI 编程代理持久化上下文的 开放标准 。如果你的项目已经在使用 AGENTS.md ,AtomCode 会自动识别,无需额外配置。查找顺序如下: .atomcode.md ATOMCODE.md AGENTS.md CLAUDE.md / claude.md 先找到的先生效。如果你在同一个项目里也用 Claude Code 或 Gemini CLI,它们各自有自己的指令文件: AtomCode &rarr; .atomcode.md 或 AGENTS.md Claude Code &rarr; CLAUDE.md Gemini CLI &rarr; GEMINI.md 这些文件互不冲突。使用 AGENTS.md 可以让遵循该开放标准的多种 AI 编程工具共享同一份指令文件,避免重复维护。"},{"id":"下一步","heading":"下一步","body":"Skills 扩展 —— 把可复用流程进一步抽象成命令 © 2026 AtomCode · MIT 报告问题"}]},{"slug":"webui","title":"WebUI 界面","group":"进阶","lede":"除了终端 TUI，AtomCode 还内置一个 浏览器界面 ：在 TUI 里输入 /webui 即可一键启动，在浏览器里聊天、翻看历史会话、增删改模型配置、上传图片，并通过 /sync 让终端与浏览器 实时同步 同一个会话。它复用本机的登录态、模型与会话历史，不需要另外配置。","sections":[{"id":"webui-界面","heading":"WebUI 界面","body":"除了终端 TUI，AtomCode 还内置一个 浏览器界面 ：在 TUI 里输入 /webui 即可一键启动，在浏览器里聊天、翻看历史会话、增删改模型配置、上传图片，并通过 /sync 让终端与浏览器 实时同步 同一个会话。它复用本机的登录态、模型与会话历史，不需要另外配置。"},{"id":"启动与关闭","heading":"启动与关闭","body":"在 AtomCode 的 TUI 输入框里运行： # 启动 webui 并自动打开浏览器（默认绑定 127.0.0.1:13457，仅本机可访问） /webui # 关闭 webui 服务 /webui stop 启动后 AtomCode 会在本机起一个 HTTP 服务，并自动打开浏览器到形如 http://127.0.0.1:13457/?token=<一次性令牌> 的地址。URL 里带的 token 用于鉴权， 等同于密码 ，请勿外传。同时，当前 TUI 会话会自动接入实时同步（见下文 多端实时同步 ）。 默认只监听本机 webui 默认绑定 127.0.0.1 ，只有本机能访问。要让手机等设备访问， 不要 直接用 --host 0.0.0.0 暴露到公网，请走蒲公英虚拟局域网方案 —— 见 远程访问指南 。"},{"id":"界面功能","heading":"界面功能","body":"浏览器界面把终端里的能力搬到了图形界面上，主要包括： 区域 能做什么 侧边栏 按项目分组的历史会话列表、搜索会话、新建对话、重命名 / 删除会话；可收起为图标栏，移动端为抽屉。 模型选择器 输入框下方直接切换 provider / 模型；同名模型会附带 provider 标识消歧。 模型配置 设置里增 / 删 / 改 provider：名称、类型（openai / claude / ollama）、模型、Base URL、API Key、上下文窗口，以及设为默认。 设置 主题（浅色 / 深色）、语言（中 / 英）、模型配置、远程访问入口。 图片附件 粘贴或选择图片随消息发送（单张上限 2MB），非视觉模型走 VL 兜底；历史里显示缩略图。 工具执行 实时展示工具调用的参数与输出，可逐行展开查看，历史回看同样可见。 附件菜单（+） 上传图片、选择文件作为上下文、插入技能（Skills）。 工作目录 切换工作目录、浏览目录、新建文件夹、设为默认工作目录。"},{"id":"多端实时同步","heading":"多端实时同步","body":"webui 背后是一个 LiveSession ：同一个会话可以同时被终端和多个浏览器标签页打开，任意一端的输入、AI 的增量回复、工具调用结果都会 实时广播 到所有连接的视图，晚加入的一端还会先收到快照回放。 运行 /webui 时，当前 TUI 会话会 自动接入 同步 —— 你在终端发的消息会出现在浏览器里，反之亦然。 在 另一个 TUI 里运行 /sync ，即可接入当前正在运行的 webui 会话（需先有 /webui 在跑）。 /sync off —— 退出同步，回到独立会话。 这让「终端里发起、手机 / 平板上盯进度」或「多人围观同一个 agent 会话」成为可能。"},{"id":"远程访问","heading":"远程访问","body":"想从手机等设备打开 webui，又不暴露公网？借助蒲公英（Oray PGY）组建的虚拟局域网，用 /webui --host <虚拟 IP> 把服务绑定到虚拟 IP，再在「远程访问」面板扫码即可。完整流程见 远程访问指南 。"},{"id":"下一步","heading":"下一步","body":"远程访问指南 —— 用蒲公英从手机安全打开 webui Headless 与 Daemon —— webui 背后的 daemon 与 HTTP/SSE 接口 斜杠命令 —— /webui 、 /sync 等命令速查 © 2026 AtomCode · MIT 报告问题"}]},{"slug":"webui-remote-access","title":"远程访问指南","group":"进阶","lede":"AtomCode 的 webui 默认只监听本机回环地址（ 127.0.0.1 ），手机等其他设备访问不到。借助 蒲公英（Oray PGY） 组建的虚拟局域网，你可以在不暴露公网、无需公网 IP 的前提下，从手机/平板安全地打开本机 webui。本页讲解完整的连接流程与安全须知。","sections":[{"id":"远程访问指南","heading":"远程访问指南","body":"AtomCode 的 webui 默认只监听本机回环地址（ 127.0.0.1 ），手机等其他设备访问不到。借助 蒲公英（Oray PGY） 组建的虚拟局域网，你可以在不暴露公网、无需公网 IP 的前提下，从手机/平板安全地打开本机 webui。本页讲解完整的连接流程与安全须知。"},{"id":"工作原理","heading":"工作原理","body":"蒲公英是一个异地组网工具：在本机和手机上安装并登录 同一账号 、加入 同一网络 后，两台设备就处在同一个虚拟局域网里，彼此可以用一个 蒲公英虚拟 IP 直接通信。webui 只要绑定到这个虚拟 IP，手机就能通过它访问。整个链路是点对点的私有网络， 不会把你的本机暴露到公网 。 为什么不直接开放公网 webui / daemon 没有内置鉴权，访问者相当于拿到本机所有工具的执行权（包括 bash 、 write 、 edit ）。所以请 不要 用 --host 0.0.0.0 把它直接暴露到公网或开放局域网。蒲公英虚拟局域网 + 一次性访问令牌（token），是为普通用户准备的安全远程方案。"},{"id":"前置条件","heading":"前置条件","body":"本机已经能正常启动 AtomCode 的 webui。 本机与手机都安装了 蒲公英 客户端： https://pgy.oray.com 。 两台设备登录 同一蒲公英账号 ，并加入 同一网络 。"},{"id":"操作步骤","heading":"操作步骤","body":""},{"id":"1-连接蒲公英拿到虚拟-ip","heading":"1. 连接蒲公英，拿到虚拟 IP","body":"在本机的蒲公英客户端里完成登录与组网，记下分配给本机的 虚拟 IP （形如 10.x.x.x ）。手机端同样登录同一账号、加入同一网络即可，无需记 IP。"},{"id":"2-让-webui-绑定到虚拟-ip","heading":"2. 让 webui 绑定到虚拟 IP","body":"默认 webui 只绑回环地址，手机访问不到。在 AtomCode 的 TUI 里用 --host 指定蒲公英虚拟 IP 重新启动 webui： /webui --host 10.x.x.x 把 10.x.x.x 换成上一步记下的本机虚拟 IP。绑定成功后，webui 就会在这个地址上对同一虚拟局域网内的设备开放。"},{"id":"3-在远程访问面板扫码连接","heading":"3. 在「远程访问」面板扫码连接","body":"打开 webui 右上角的 远程访问 （手机图标）面板，AtomCode 会自动检测蒲公英状态并生成： 一个可直接打开的 远程地址 （已带上访问令牌）； 对应的 二维码 。 用手机扫码，或把地址复制到手机浏览器打开即可。手机需登录同一蒲公英账号、处于同一网络。 访问令牌 = 密码 远程地址中带有一次性访问令牌（ ?token=… ）， 等同于密码 ：任何拿到这条完整链接的人都能操作你的本机。请勿把它发到群里、截图外传或贴到公开页面。"},{"id":"排错","heading":"排错","body":"「远程访问」面板会根据检测结果给出不同提示，对应处理如下： 面板提示 含义 怎么办 未检测到蒲公英 本机没装蒲公英，或客户端未运行。 在本机与手机都安装并登录蒲公英，加入同一网络后回到面板「重新检测」。 本机还没分配虚拟 IP 装了蒲公英但还没组网成功。 在蒲公英客户端里连接 / 加入网络，拿到虚拟 IP 后再「重新检测」。 webui 仅绑定了本机 检测到蒲公英，但 webui 还监听在回环地址。 按步骤 2 用 /webui --host <虚拟 IP> 重启 webui，再刷新本页。 手机打不开 / 一直转圈 两端不在同一网络，或防火墙拦截。 确认手机与本机登录同一蒲公英账号、加入同一网络；检查本机防火墙是否放行 webui 端口。"},{"id":"下一步","heading":"下一步","body":"Headless 与 Daemon —— 了解 webui 背后的 daemon 与 HTTP/SSE 接口 常见问题 —— 远程 / 登录相关的常见坑 © 2026 AtomCode · MIT 报告问题"}]},{"slug":"faq","title":"常见问题","group":"运维","lede":"把用户群和 issue 里反复出现的问题整理到这里。如果你遇到的问题不在列表里，欢迎在终端内直接运行 /issue 反馈，或到 AtomGit 仓库 提 issue。","sections":[{"id":"常见问题","heading":"常见问题","body":"把用户群和 issue 里反复出现的问题整理到这里。如果你遇到的问题不在列表里，欢迎在终端内直接运行 /issue 反馈，或到 AtomGit 仓库 提 issue。"},{"id":"安装与启动","heading":"安装与启动","body":""},{"id":"安装脚本失败网络超时怎么办","heading":"安装脚本失败、网络超时怎么办？","body":"一键安装脚本默认从 GitCode release 拉二进制。如果网络不通，可以： 直接到 releases 页面 手动下载对应平台的压缩包，解压后把 atomcode 放进 PATH ； 或者从源码构建： cargo install --path crates/atomcode （需要 Rust 1.80+）。"},{"id":"执行-atomcode-报-command-not-found","heading":"执行 atomcode 报 \"command not found\"","body":"说明安装目录不在 PATH 里。默认安装路径是 ~/.atomcode/bin ，把它加到 shell 启动脚本里即可： export PATH=\"$HOME/.atomcode/bin:$PATH\""},{"id":"macos-提示无法打开因为无法验证开发者","heading":"macOS 提示\"无法打开，因为无法验证开发者\"","body":"在系统设置 → 隐私与安全性里点\"仍要打开\"，或在终端执行： xattr -d com.apple.quarantine $(which atomcode)"},{"id":"登录与模型","heading":"登录与模型","body":""},{"id":"oauth-登录时浏览器打不开","heading":"OAuth 登录时浏览器打不开","body":"检查是否在无 GUI 的远程服务器上。远程环境推荐改用 API Key 登录（参见 登录方式 ），或在本地完成 OAuth 后把 ~/.atomcode/auth.json 拷贝到服务器同路径。"},{"id":"连不上模型-一直转圈-报-timeout","heading":"连不上模型 / 一直转圈 / 报 timeout","body":"先确认 ~/.atomcode/config.toml 里的 base_url 是否可达， curl 一下对应的 /v1/models 接口； 企业网络里常见是代理问题，设置 HTTPS_PROXY 环境变量后重试； 国内访问境外模型需要确认出口网络；可以先用 /model 切换到 AtomGit 官方通道确认整体链路是通的。"},{"id":"怎么切换模型","heading":"怎么切换模型？","body":"会话内直接 /model ，从菜单里选。如果想持久化，编辑 ~/.atomcode/config.toml 里的 model 字段。详见 配置文件 。"},{"id":"上下文超限-context-length-exceeded","heading":"上下文超限 / \"context length exceeded\"","body":"运行 /compact 让模型把已有对话压缩成摘要后再继续； 或 /clear 清空当前上下文重新开始（历史会作为 session 保留，可以随时 /resume ）； 避免一次性把整个巨型文件贴进 prompt，让 AtomCode 用文件工具按需读取即可。"},{"id":"权限与安全","heading":"权限与安全","body":""},{"id":"每次执行命令都要确认太烦了","heading":"每次执行命令都要确认，太烦了","body":"这是默认的安全策略。你可以： 临时放行：弹出确认时选\"一直允许此类操作\"； 配置级放行：在 config.toml 的 [permissions] 里加入白名单命令。"},{"id":"atomcode-会把我的代码发到哪里","heading":"AtomCode 会把我的代码发到哪里？","body":"只发到你在 config.toml 里配置的模型 endpoint。项目文件由本地的工具读取后作为 prompt 一部分发送，AtomCode 本身不会额外上传或遥测代码内容。"},{"id":"能禁用某些工具吗","heading":"能禁用某些工具吗？","body":"可以。在 config.toml 的 [tools] 段里用 disabled = [\"shell\", \"web_fetch\"] 禁用不希望模型使用的工具。"},{"id":"使用与交互","heading":"使用与交互","body":""},{"id":"怎么让它读某个文件","heading":"怎么让它读某个文件？","body":"在输入里用 @ 触发文件补全，例如 帮我看看 @src/main.rs 的入口逻辑 。也可以直接描述路径，工具会自己调用 read_file 。"},{"id":"如何换行输入多行-prompt","heading":"如何换行输入多行 prompt？","body":"Shift + Enter 、 Alt + Enter 或 Ctrl + Enter 换行， Enter 发送。完整快捷键见 快捷键 。"},{"id":"改错了怎么回滚","heading":"改错了怎么回滚？","body":"运行 /undo 把上一轮工具调用产生的文件改动回滚到修改前的状态。详见 会话与撤销 。"},{"id":"上一次的会话还能继续吗","heading":"上一次的会话还能继续吗？","body":"能。启动时加 --continue （或 -c ）继续上一次会话，或在新会话里运行 /resume ，从历史列表里挑一个继续。"},{"id":"skills-与项目指令","heading":"Skills 与项目指令","body":""},{"id":"我的-skill-没出现在菜单里","heading":"我的 skill 没出现在菜单里","body":"确认路径正确：全局在 ~/.atomcode/skills/<name>/SKILL.md ，项目在 .atomcode/skills/<name>/SKILL.md ； 确认 frontmatter 格式正确， name 和 description 两个字段必填； 重启 atomcode 或运行 /reload 重新扫描。"},{"id":"atomcodemd-和-skill-有什么区别","heading":".atomcode.md 和 skill 有什么区别？","body":"前者是项目级的\"始终生效\"约定，后者是可被显式触发的流程。详见 Skills 扩展 · 与项目指令的分工 。"},{"id":"排查思路","heading":"排查思路","body":"先看日志 出任何问题第一步都是看 ~/.atomcode/logs/ 。启动时加 --log-level debug 可以打印更详细的请求/响应日志。"},{"id":"提-issue-时请附上","heading":"提 issue 时请附上","body":"atomcode --version 的输出； 操作系统和架构； 报错时的最小复现步骤； 相关日志（记得脱敏 API Key）。"},{"id":"下一步","heading":"下一步","body":"返回概览 快速开始 —— 从零装一遍 配置文件 —— 所有可调项 © 2026 AtomCode · MIT 报告问题"}]}]