常见问题
从任务准备到结果验收，查找你遇到的问题。点击问题展开答案，操作细节与截图可通过“参阅”进入对应章节。
入门与任务准备#
JoyCode 是什么？适合做哪些工作？
JoyCode 是一款面向开发场景的自主决策 Code Agent。你说明目标、范围和验收标准，JoyCode 围绕项目分析问题、推进实现与验证，你跟进关键决策并验收结果。
可以从理解代码、修复问题、实现功能、补充测试或整理研发文档开始；复杂工作可通过多任务并行、子智能体和 Git 工作树分工推进，并按需使用代码图谱与 CodeWiki。
参阅：产品介绍
支持 macOS 和 Windows 吗？
支持。从组织发布渠道下载对应系统的安装包：macOS 将应用放入“应用程序”，Windows 按安装程序提示完成安装。启动后按登录页提示完成认证。
参阅：安装指南
第一次使用，要先配置模型和插件吗？
项目、会话和任务有什么区别？
项目是本次读取和修改文件的本机目录；会话保存要求、执行过程和结果；任务是你希望完成的工作。
一项任务可以在同一会话中多轮推进，不需要每发一条消息就新建项目。发送前确认当前项目，尤其是名称相似或同时打开多个项目时。
参阅：开始新任务
什么时候继续原会话，什么时候新建？
安装后打不开，或无法登录怎么办？
先检查安装包是否对应当前系统，再根据登录页的具体提示处理。
- 确认安装包来自组织发布渠道，且已完成安装。
- 重新启动应用，按登录页提示使用对应账号认证。
- 仍失败时，保留错误原文、发生时间、系统和应用版本，按文末的反馈清单整理信息。
能进入 JoyCode 工作台，才表示已完成这一步；安装成功不等于登录成功。
参阅：问题排查
对话与上下文#
怎样提要求，更容易得到符合预期的结果？
写清目标、允许修改的范围和验收标准，再提供与问题直接相关的文件或截图。
例如：
修复欢迎页按钮点击后状态不更新的问题。只修改这个页面及对应测试，保留现有布局。完成后运行相关测试，返回修改说明、文件链接和验证结果。
已有代码、设计稿和报错日志应分别说明用途。涉及删除、发布或外部写入时，把允许执行的操作写清楚。
参阅：任务要求与上下文
@、附件和 / 分别什么时候用？
输入 @ 后找不到想用的插件怎么办？
选择计划模式后，为什么没有修改文件？
计划模式用于先制定方案。选择菜单项只是选好了工作方式，还需要写明要求并发送。
在输入框输入 /，选择“计划模式”，确认出现“计划”标记，再说明规划目标。收到方案后检查涉及文件、实施步骤和验证方法。出现“实施此计划？”时，准备实施可选择“是，实施此计划”；需要调整时填写修改要求。
只有方案不代表已经完成代码修改。
参阅：Plan 模式
“初始化项目”会做什么？已有项目可以用吗？
初始化指令要求分析当前项目并创建 AGENTS.md，记录项目说明和工作约定；已有同名文件时，要求跳过并说明。
使用前确认项目目录，并保留现有文件。完成后打开文件，核对项目结构、启动和验证命令、编码约定。需要修改已有说明时，在会话中另行写清修改范围和保留要求。
参阅：初始化项目
模型与权限#
怎么选择模型和推理强度？档位越高越好吗？
点击会话输入区右下方的模型名称，选择当前可用模型及其支持的推理强度。
首次使用可保留当前可用选项，先完成一个简单任务。较高推理档位通常需要更多等待，不保证所有任务都更好；选择后检查输入区显示的模型与档位，再发送要求。
参阅：模型选择器
什么时候需要配置自定义模型？
只有需要接入自己的模型服务或调整现有连接时，才需要配置。会话中已有可用模型时，可以直接使用。
入口是“设置 → 自定义模型”。接入新模型点击“添加模型”，修改已有条目点击“编辑”；准备完整请求地址、API Key 和模型 ID。需要声明思考档位时使用“JSON 配置”，修改前保留副本，并按该模型服务实际支持的档位填写。
API Key 只填入指定配置，不要贴到普通消息、截图或反馈材料中。
参阅：自定义模型配置
配置保存了，为什么还是不能聊天？
保存配置只表示内容已保存，不能证明模型请求成功。
- 重新打开配置，确认目标模型已启用，地址和模型标识与服务方资料一致。
- 在“已保存模型”中点击目标模型旁的“测试”，查看具体返回提示。
- 回到会话选择该模型，发送一个最小请求。
- 如果仍失败，记录失败步骤和原始错误，再检查相应的连接或账号条件。
会话实际返回回答，才说明这次聊天链路跑通。
参阅：自定义模型配置
三种权限模式怎么选？
普通任务可先选“每次询问”，不要为了排除未知错误直接扩大权限。
- 每次询问：菜单说明为执行命令、修改工作区以外文件或访问网络前询问。
- 自动审批：对检测到的风险操作请求审批，不代表每一步都手动确认。
- 完全访问：允许更广的操作范围，适合范围明确的可信任务。
出现提示时，核对路径、命令和联网对象后再决定。系统和外部服务可能仍需单独授权。消息里写“只读”能表达意图，但不等于设置了系统权限。
参阅：权限与安全边界
执行、多任务并行与恢复#
任务看起来没有进展，是不是卡住了？
先看任务是在运行、等待输入，还是等待批准，再判断是否异常。
展开“已处理 N 秒”等过程区域，检查最近的命令、工具状态和输出。有确认提示时先核对并处理；有错误时保留原始提示。需要停止时，先留意已有文件改动和已执行的外部操作，再决定如何继续。
参阅：执行与调整
停止任务后还能继续吗？之前的修改会撤销吗？
结果不符合要求，怎么让 JoyCode 修改？
在原会话指出具体位置、实际现象和预期结果，并说明哪些内容不要动。
例如：“欢迎页按钮点击后没有更新状态。只修复这个交互，保留布局；补充对应测试，返回最新文件和验证结果。”界面问题可以附截图；文件已更新后，从最新结果重新打开并验收。
参阅：结果验收
哪些工作适合多任务并行？
输入齐全、可以独立执行和分别验收的工作适合并行，例如一项整理文档，另一项只读检查测试覆盖。
在当前会话中分别写清目标、文件范围、是否允许修改和返回格式。共享文件或有先后依赖的工作，要先约定顺序与范围。完成后逐项检查结果，再汇总交付。
“独立任务”指工作可分开执行，不代表每项都会新建独立会话；子智能体是实现分工的一种方式。
参阅：多任务并行
什么时候需要使用 Git 工作树（Worktree）？
同一个 Git 代码库有多项独立代码任务，需要隔离各自的工作目录和修改时，使用 Git 工作树。新建任务时打开“在本地处理”，选择“新工作树”并核对起始分支；发送任务后检查实际工作目录与 Git 状态。
每个工作树的差异和测试要分别检查，再按项目流程整合需要保留的改动。工作树不会自动合并分支，也不能替代冲突检查。
参阅：Git 工作树
怎么使用子智能体？显示“已结束”就算完成了吗？
在主会话中说明“请委派一名子智能体”，并写清独立工作、文件范围、读写权限和返回内容。
出现子任务状态后，可以跟进执行；进入“已结束”分组后仍需阅读摘要，区分成功结果、失败或遗漏。主任务要检查回传内容，不能把一个子任务结束当作整项工作验收通过。
参阅：子智能体
目标驱动、多任务并行和定时任务有什么区别？
命令或测试执行失败，该检查什么？
先看实际命令、运行目录、退出码和错误输出，再处理对应原因。
可以请 JoyCode 解释错误，并检查项目依赖、启动方式或权限要求。需要手动复核时，可使用底部面板的内置终端，或从顶部“选择打开工具”中选择可用的外部终端。使用项目实际提供的命令，不要套用其他项目的命令。
修改后重新运行相关检查，保留本次输出；不要只用一句“已经修好”代替验证。
参阅：终端与运行验证
结果验收与交付物#
JoyCode 回复“已完成”，怎样判断真的完成了？
有文件链接，为什么没有渲染预览？
文件链接可打开文件内容，但不保证能直接渲染为页面。需要运行服务的项目，让 JoyCode 按项目运行方式提供预览地址，再打开页面检查。
文件更新后，使用最新文件或刷新对应预览地址，确认当前页面与交付内容一致。
参阅：结果验收
怎么指出预览页面中需要修改的位置？
打开页面预览，再点击批注入口，确认出现“正在批注”。
选择需要调整的页面元素，填写评论并核对位置与内容，再确认发送。回到原会话检查反馈是否出现，跟进修改；结束后重新打开最新交付物，检查对应位置和交互。
参阅：交付物预览与批注
项目没有使用 Git，还能做代码审查吗？
可以提出只读检查指定文件的要求，并让 JoyCode 返回问题位置、影响和建议，再运行项目提供的验证命令。
/ 菜单中的“查看变更”和“代码审查”涉及未提交变更或分支比较，需要项目使用 Git 且存在可比较内容。非 Git 项目不要照搬分支比较流程。
参阅：代码审查与 Diff
历史会话#
归档的会话在哪里？归档会删除项目文件吗？
找不到以前的会话怎么办？
先核对项目和筛选条件，再到“已归档的聊天”中搜索，不要立即把列表中未显示理解为会话丢失。
找到后确认标题、历史消息和最后状态是否对应原任务。如果仍找不到，记录原项目、会话标题或关键词及大致时间，随问题反馈一并提供。
参阅：任务管理
扩展能力#
技能、插件和 MCP 有什么区别？
插件已经添加，为什么任务里没有生效？
MCP 找不到、反复认证，或连接正常却调用失败怎么办？
到“设置 → 扩展管理 → MCP”找到目标服务，根据当前状态分别检查：
- 找不到：核对服务名称与配置，按需刷新后重新查看。手动添加时，STDIO 要把启动命令和参数分开填写，并核对环境变量与工作目录；Streamable HTTP 要核对完整 URL、Bearer Token 环境变量名和 Header。
- 保存后未生效：查看页面反馈，按提示重启运行时；没有对应入口时，重启 JoyCode 后再检查。
- 反复认证：核对服务、账号和运行 JoyCode 的环境变量，重新完成身份认证。
- 开关已开但调用失败：核对连接、认证和工具调用所需权限，再检查本机命令或远程地址，并读取工具返回的具体错误。“项目配置 · 只读”限制配置编辑，不表示不能调用该服务。
保存、启用、认证与实际调用是不同环节。回到对话，用一个自己有权访问的对象发起只读请求，并核对返回内容，才能判断本次调用是否成功。
参阅：MCP 扩展
研发辅助工具是不是都要安装？
不需要。先根据代码分析、界面实现或测试等具体工作选择工具，再到“设置 → 扩展管理 → 插件”查找已有条目；需要添加时进入侧栏“插件中心”，按说明完成必要配置。
判断工具是否有用，要看它是否返回了本次所需结果，例如代码位置、实际页面或测试记录，而不只是看列表中是否出现了名称。
参阅：研发辅助工具
代码图谱与 CodeWiki 在哪里？
Hooks 在哪里查看？
从“设置 → 编码 → 钩子”查看来自配置和插件的钩子及待审核项。显示“未检测到钩子”时，先清空搜索，再核对配置或插件来源；空状态不能确认审核、启用或执行结果。
参阅：Hooks（钩子）
RepoWiki 返回的仓库文档怎样用于理解代码？
先说明目标仓库和研发问题，阅读相关文档，再打开源码引用核对实现。文档不存在或索引未就绪时先处理对应状态；文档返回不能替代当前代码与测试。
参阅：RepoWiki
执行安排与工作台设置#
如何创建定时任务？频率怎么选？
点击左侧带时钟图标的“定时任务”。直接点击“创建”，会进入对话，由 JoyCode 协助设置；需要自己填写表单时，点击“创建”右侧的下拉箭头，选择“手动设置”。
手动表单中填写任务要求、运行位置、频率和时间。频率包括间隔、每天、工作日、每周和自定义；自定义频率可打开“编辑计划规则”填写 RRULE。创建后回到列表核对计划与下次执行；运行后打开对应聊天核对实际输出。
参阅：定时任务
计划保存了，为什么到时间没有拿到结果？
保存计划只表示完成了执行安排，不表示任务已经运行或成功完成。
先检查计划是否已开启，而不是处于暂停状态；再核对绑定项目、运行范围、频率、时间和“下次执行”。查看实际运行状态及返回错误，任务执行后还要检查产物是否满足要求。定时任务不等于云端离线托管，运行会受到应用与工作环境影响。
参阅：定时任务
长任务运行时，怎样减少电脑休眠带来的中断？
外观设置会改变模型或权限吗？
不会。外观设置只调整显示方式；选择模型或权限需使用各自的设置入口。
进入“设置 → 外观”，选择系统、浅色或深色模式，并分别配置浅色和深色主题；在“偏好设置”中调整 UI 字号与代码字体大小，再检查实际显示。
参阅：外观设置
导入页能看到哪些来源和内容？
当前页面列出本机检测到的聊天工具来源。选择来源后，会显示当前可选的内容分类；实际分类和数量随来源及本机状态变化。
导入前核对来源、分类和影响范围，保留现有配置；导入后逐项检查聊天或设置。导入范围仅为页面提供的内容，不包括来源工具的全部云端数据。
参阅：导入来源与内容分类
更新 JoyCode 前后需要检查什么？
怎样开启长期记忆并判断引用是否适用？
在“设置 → 个性化 → 记忆”开启本地记忆，并选择可用国产模型。记忆后台更新，不一定即时生成；回复出现引用时查看记忆主题和来源，再对照当前任务、代码和配置核对。
参阅：长期记忆
问题反馈#
反馈问题时，提供哪些信息最有帮助？
提供能够复现问题的最小信息，保留原始错误，不必发送整个项目。
- 环境：JoyCode 版本、操作系统；模型或扩展相关问题再补对应名称。
- 时间：问题发生时间，以及是否每次都会出现。
- 步骤：从哪个入口开始，进行了哪些操作。
- 预期与实际：本来希望发生什么，实际出现了什么。
- 证据：错误原文、必要截图、相关命令、退出码及关键输出。
提交前遮挡账号、API Key、令牌和无关业务内容。截图应保留出错位置、标题、入口及必要状态，不要只截取一小段报错。
参阅：问题排查