常见问题
本文适合所有 xAgent 文档读者。 本文集中回答使用 xAgent 和阅读手册时的常见问题。 当你无法判断从哪里开始、某个能力是否稳定、或不知道应该看哪个页面时，先查看本文。
按现象快速定位
| 当前遇到的问题 | 优先阅读 |
|---|---|
| 第一次登录，不知道从哪开始 | 第一个任务 |
| 模型连接通过，但工具任务失败 | 模型验证 |
| 找不到文件或结果只有文字 | 工作区文件 |
| 卡在等待审批或审批范围不清 | 审批与安全边界 |
| 子会话没有回传 | 协作消息与回执 |
| 定时任务没有按预期启动 | 触发器状态与时区 |
| 记忆不准确或不该长期保留 | 长期记忆管理 |
从其他页面整理的问题
这些问题来自入门、使用、部署、架构、开发和参考页面，现按任务归类，问题与技术细节继续保留。
开始使用与产品范围
应该先读哪些页面？
先读 什么是 xAgent、功能导览与菜单入口，然后按需要进入 第一个任务 或 任务。
为什么有些页面标记为 experimental 或 planned？
因为这些能力仍可能变化。使用手册会说明可用边界，但不会把未稳定接口写成承诺。
普通用户需要理解 AI 技术吗？
不需要。普通用户只需要说明目标、提供材料、确认必要动作并查看结果。模型、协议、底层实现和扩展细节由管理员或维护者处理。
为什么有些页面会出现英文名称？
有些菜单本身使用英文名称，例如 Agent会话、Skill 管理、MCP 配置。使用手册会按页面用途解释，不要求普通用户理解技术含义。
文档站是否包含登录、评论或插件市场？
不包含。文档站是静态手册。
当前版本稳定吗？
截至 2026-10-01，最新公开二进制发行版是 v0.0.21.beta（2026-09-22），仍适合部署体验、场景验证和反馈。本文涉及的更新源码行为会注明核对时间；公开发行版、源码和具体部署不应混为同一状态。
一定要先创建智能体才能开始吗？
不需要。大多数首次任务可以直接在默认会话中完成。
xAgent 是一个聊天机器人吗？
不是。聊天只是入口之一，xAgent 更关注把任务做完：读取材料、生成文件、等待确认、接入外部系统、归档结果。它可以聊天，但产品目标不是陪聊，而是完成工作。
xAgent 需要安装在每台电脑上吗？
不需要。xAgent 部署在服务器端，用户通过 Web 或已接入的 AgentPlugin 访问。任务执行过程中不要求用户电脑一直开机，用户也可以通过微信等 IM 入口远程提交任务。
xAgent 是单一专用智能体吗？
不是。xAgent 可以承载多个专用智能体入口。管理员可以为不同工作场景准备不同的智能体、Skill、工具、外部连接和安全策略，普通用户进入对应入口后直接使用。
xAgent 会自动自我进化吗？
默认不会。xAgent 可以通过提示词或自进化 Skill 对特定技能进行持续优化，但这需要明确目标、测试样例、验收标准和发布流程。自进化很有价值，但也有风险，所以 xAgent 对这件事保持克制。
免费二进制版本意味着什么？
免费二进制版本目前是 v0.0.21.beta 测试版，是了解和评估 xAgent 的入口。用户可以先部署标准版本，体验任务提交、文件工作区、工具、技能和外部连接等核心能力。
免费二进制发布不等同于源码开源。xAgent 未来会视产品成熟度、社区反馈、安全边界和商业可持续性，评估是否开放源码或开放更多生态协作方式。
如果需要企业内部系统接入、统一身份认证、复杂权限、审计合规、专属 AgentPlugin 或深度业务流程改造，通常应按实际需求进行定制集成。
商业版与免费版有什么区别？
未安装企业授权证书时，xAgent 会直接进入免费版，不需要申请或续期免费证书。免费版可以使用核心产品能力，固定额度为 2 个用户、30 个会话、1 个 WorkGroup、5 个 AgentPlugin VChannel 和 5 个定时任务。
企业版通过外部授权证书提供更高的数量权益，并继续校验签名、设备绑定和有效期。它更适合需要扩大团队规模、配套支持或定制集成的组织。
xAgent 会提供官方 SaaS 吗？
目前暂无 SaaS 发布计划。xAgent 不希望用户把自己的任务文件、业务数据和外部系统连接存储到官方平台。自行部署时，数据安全、备份、权限和保密责任由部署方负责。
xAgent 适合大型企业平台吗？
xAgent 可以作为企业智能工作门户和业务智能化入口的基础能力，用来承接统一任务入口、文件工作区、工具调用、技能沉淀和外部系统连接等场景。
如果用于大型公司或复杂组织，通常需要结合企业现有系统做定制集成，例如统一身份认证、权限体系、内部业务系统连接、审计要求、数据边界、安全策略、模型网关和专用外部连接。这类场景不是简单安装后立即覆盖全部企业流程，而是以 xAgent 为基础，根据企业已有基础设施逐步接入和扩展。
xAgent 能替代所有业务系统吗？
不能。xAgent 负责组织任务入口和能力调用，外部系统的权限、登录态、业务数据和审计规则仍应由对应系统或外部连接管理。
为什么有些术语保留英文？
Session、Task、Tool、Skill、AgentPlugin、Workspace、Memory 是产品和代码中都会出现的固定概念，文档中保留英文可以减少 UI、日志和代码之间的理解偏差。
普通用户需要创建智能体吗？
通常不需要。管理员准备公共入口后，普通用户直接使用即可。如果用户已经熟悉自己的固定工作流程，也可以在个人范围内创建或调整智能体。
为什么我的菜单比其他用户少？
先确认自己的部署版本、账号角色，以及正在会话工作面、用户设置还是管理后台。旧版简洁模式确实隐藏会话列表、触发器、智能体、Skill、Tool、MCP 和个人策略；2026-10-01 的用户菜单已不按高级开关过滤。管理员功能仍需要管理员身份，不能通过个人设置获得。
第一次使用应该打开哪个菜单？
先进入 Agent 会话，写清楚目标、材料、约束和交付要求。需要查看文件时进入工作区文件，需要绑定消息渠道时进入“插件连接”。
主题和显示密度在哪里？
打开账号管理，在界面相关设置中切换亮色、暗色或跟随系统，并调整显示密度。它们不再是独立侧边栏菜单。
安装、模型与部署
应该如何安装或升级？
推荐运行官方安装脚本：
curl -fsSL https://downloads.xagent.xiagaogao.com/scripts/install.sh | bash
脚本会识别系统与架构、校验发布包，并支持版本固定、无人值守安装和 AgentPlugin 选择。Linux 激活失败时会尝试恢复上一版本。完整流程见开始安装。
Office 转 PDF 或 Excel 重算需要另外安装什么？
需要管理员在服务器上安装 LibreOffice；其系统依赖未包含在 xAgent 发布包中。Debian/Ubuntu 可执行 sudo apt-get update && sudo apt-get install -y libreoffice，再用 soffice --headless --version 验证。参见安装说明。
是否必须使用 Qwen3.6-27B？
不必须。Qwen3.6-27B 是旧版开发测试记录中的一个模型，不是推荐配置或当前唯一选择。应根据模型上下文、工具调用、推理质量与自己的任务验收结果配置。
小模型可以使用吗？
可以评估。旧版测试记录包括 Gemma4-12B 执行长任务的样本，但这不保证所有部署或任务质量。模型越小，越应核对复杂推理、多工具规划、长上下文保持和 Skill 创建的稳定性，再开放给普通用户。
64k 上下文够用吗？
64k 可以作为既有最低建议，复杂任务更建议 100k 以上，但不是所有任务的固定门槛。旧版初始上下文曾接近 20k；实际长度随版本、能力和材料变化。旧测试中出现过 90% 以上前缀缓存率，这只说明该样本环境，不能替代足够的上下文窗口。v0.0.21.beta 压缩使用 90% 请求预算线，具体含义见模型要求。
为什么需要工具调用能力？
xAgent 不是聊天的系统。它需要读取文件、写入工作区、调用 MCP、使用 AgentPlugin、处理触发器和生成产物。没有稳定工具调用能力，很多任务无法可靠完成。
上下文压缩会影响结果吗？
可能会。上下文压缩用于让长任务继续执行，但压缩后的内容是摘要，不等同于完整原文。因此长上下文模型更适合复杂任务，可以减少过早压缩带来的信息损失。
数据可以完全私有化吗？
如果使用本地模型或自有模型服务，可以让任务数据留在团队自己的环境中。是否能做到完全私有化，还取决于模型、外部连接、部署方式和管理员配置。
可以自己调整配置吗？
可以。模型、提示词、Skill、工具、外部连接和审批策略等配置可以在系统内维护。很多设置无需重启服务或重建会话；正在运行的执行轮保持当前配置，后续执行再使用新设置。
xAgent 使用什么数据库？
当前版本默认使用内置 SQLite 数据库，目的是降低部署和维护难度。xAgent 具备升级到 PostgreSQL 等数据库的能力，适合在团队规模、并发、审计或运维要求提高后再按实际需要升级。
高级设置改错了怎么办？
先回到会话里说明问题，或重新打开高级设置恢复原来的提示词、模型、Skill、Tool 和密钥选择。系统级配置仍由管理员维护。
中途切换模型会立即影响正在执行的一轮吗？
不会立即改写当前正在运行的同一轮模型与工具循环。本轮会固定已经选定的模型，新配置会在后续执行轮生效。切换模型不需要创建新会话，已有历史和文件会保留。
普通用户需要自己配置模型吗？
通常不需要。管理员配置好后，普通用户直接在会话中使用。
后续统一模型管理和任务路由完善后，普通用户会更少感知具体模型选择，只需要说明任务目标。
测试连接成功就代表所有任务都能完成吗？
不一定。测试连接只说明模型服务可用。任务能否完成还取决于能力开关、工具、Skill、外部连接和审批策略。
为什么会话里要切换模型？
不同模型适合不同任务。比如有的适合快速总结，有的适合复杂推理，有的适合工具协作。切换模型不代表要重新开始整个会话。
任务、会话与协作
SubAgent 是否使用独立 Session？
当前实现通过独立子会话承载 SubAgent 的目标、状态、工具和结果，并由主会话按任务需要创建和收束。
SubAgent 是否可以直接绕过主 Agent？
不应这样描述。长任务拆分仍需受平台治理。
SubAgent 是否稳定？
当前仍按实验性能力处理。
会话和任务是一回事吗？
不是。会话是持续工作上下文，任务是要完成的目标。一个会话里可以推进多个任务。
智能体和会话是什么关系？
智能体负责执行，会话承载上下文。一个智能体可以在会话中工作，但当前会话里的文件、历史、工具状态和用户补充仍属于会话上下文。
什么时候需要多个智能体？
当不同任务需要不同角色、工具组合、权限边界或输出习惯时，可以拆成多个智能体或专家会话。
任务是否一定会拆成很多步骤？
不一定。简单任务通常会直接完成。只有材料很多、步骤复杂或需要中途确认时，才可能分阶段推进。
任务是否等同于一次用户消息？
不等同。一次用户消息可以创建新任务，也可以只是补充材料、修正要求或确认某个步骤。
一个好任务应该包含什么？
至少包含目标、材料、约束和交付格式。越需要工具或文件处理，越应该写清楚输入来源和结果形式。
会话事件从哪里来？
会话事件可以来自外部接口、触发器、AgentPlugin，也可以来自其他会话。xAgent 会通过内置事件队列把事件投递到对应的智能体会话中。
会话之间可以互相通信吗？
可以，当前会话协作仍限定同一用户。旧版常用“通知/协助”概括事件；当前需要同时检查消息类型与 context_scope，不能只凭“通知”二字判断是否进入上下文或唤醒执行。session_send 的接受回执也不是目标任务已完成的证据。需要回传时明确目标、产物引用和回复要求，并检查真实结果。详见多会话协作。
为什么看到了工具调用？
这表示 xAgent 正在执行具体动作，例如读文件、查网页、生成文件或调用外部系统。普通用户重点看最终结果和是否需要确认。
为什么任务没有继续？
常见原因是缺少材料、等待审批、等待你补充信息、工具不可用、外部系统未连接，或任务描述不够明确。先看会话里的提示，再补充信息。
可以中途换要求吗？
可以。建议直接说明新的要求，例如“前面的结果保留，但输出格式改成表格”。
什么时候开新会话？
当目标已经变成另一件事，或不希望延续当前上下文时，再新建会话。只是在同一个目标内调整格式、补充材料、换模型或换 Skill，不需要新开会话。
子 Agent 是否需要用户手动管理？
不一定需要逐个手动管理。主会话可以创建子会话并发送任务，但发送一次不等于自动完成、自动回传或自动汇总。明确交付要求后仍要观察子会话状态，必要时补充指令，并由主会话核对回传文件。
长任务会自动拆分吗？
不一定。你可以明确要求“先列计划，确认后再继续”，这样更容易控制过程。
长任务状态在哪里看？
优先在原来的 Agent会话 中查看。生成的文件通常在工作区文件中查看。
中途可以改方向吗？
可以，但要说明哪些结果保留、哪些废弃。例如“保留主题分类，报告结构改成管理层汇报版”。
为什么不写命令示例？
因为普通用户主要通过网页提交长任务。底层接口和内部组织方式不作为使用手册主线。
会话是否只是聊天记录？
不是。聊天记录只是入口。会话还包含任务上下文、能力选择、文件产物和执行状态。
会话是否可以被子任务执行单元复用？
长任务或拆分任务可能创建独立执行单元。普通用户只需要关注主会话中的状态和回传结果。
任务是否必须一次完成？
不必须。复杂任务可以分阶段推进。你可以要求 xAgent 先列计划，确认后再执行。
任务是否等同于工具调用？
不是。工具只是完成任务的手段。普通用户不需要指定工具名，只要说明想完成的动作。
什么时候需要拆分任务？
当材料很多、步骤复杂、需要等待外部结果或需要多次确认时，建议拆分。
文件、工作区与交付
文件可以生成公开链接吗？
可以，但管理员必须先在“存储管理 > 文件分享”开启策略；默认关闭。链接必须限时，公开预览带水印，原文件下载需单独授权。参见文件外链分享。
ProcessSandbox 和工作区隔离是一回事吗？
不是。工作区隔离决定用户和 Session 可以看到、读写哪些文件；ProcessSandbox 负责外部命令实际挂载哪些文件、继承哪些环境，以及进程树和资源限制。
任务文件保存在哪里？
任务文件和产物集中保存在服务端工作区，并按用户做隔离。用户只能看到自己的工作区和授权范围内的文件。
可以让 xAgent 自动保存结果吗？
可以。在任务里明确写“保存为 Markdown / CSV / HTML 报告”等格式。
工具可以直接访问我的本机文件吗？
不可以。工具通常只能访问工作区和授权范围内的文件。
工作区是否等同于本机任意目录？
不是。工作区有明确可见性和权限边界。用户只能看到授权范围内的文件。
上传后的文件会自动被处理吗？
不一定。上传只是提供材料。你还需要在任务里说明“请阅读这个文件”或“请分析这个表格”。
为什么找不到生成的文件？
可能任务只在会话里回复了结果，没有保存文件。可以继续要求“请把结果保存为 Markdown 文件”。
可以把工作区文件发给外部系统吗？
可以，但通常需要工具、连接和审批。发送前应检查内容是否适合外发。
技能、工具与能力扩展
AgentPlugin 是否必须提供 Skill？
可以提供，但不是唯一职责。
Tool 是否可以绕过 Session 执行？
不应这样设计。Tool 调用应在明确上下文和治理边界内发生。
Tool 是否应保存业务事实？
通常不应。业务事实应归属于明确 owner。
Tool 错误应该在哪里查看？
先查看当前会话中的 Tool 结果和错误提示；部署维护者还可以结合服务日志定位。当前没有稳定的公共错误码表。
AgentPlugin 是否就是 Skill？
不是。AgentPlugin 可以提供 Skill，但插件本身是外部系统接入边界。
Skill 是否等同于插件？
不等同。Skill 更偏向任务方法和工具使用规范。
Skill 是否能直接执行代码？
不应这样描述。执行能力应属于 Tool 或 RuntimeConnection。
Skill 是否可以来自 AgentPlugin？
可以作为 AgentPlugin 给 Agent 的运行时说明；插件可通过 /skill.json 发布目录清单，xAgent 按 revision 下载并原子替换，不下载或执行脚本文件。
技能和工具有什么区别？
工具是可以被调用的具体动作。技能是完成某类任务的方法说明，可能会指导智能体组合多个工具。
xAgent 有内置知识库吗？
目前没有内置知识库。知识类能力可以通过 Skill + MCP 扩展：Skill 负责描述如何使用知识和组织回答，MCP 负责连接外部知识库、检索服务或团队已有资料系统。
xAgent 能帮我做新的专用智能体吗？
可以。通常先明确任务场景，再准备专用智能体入口、Skill、工具、外部连接和审批策略。如果只是沉淀一套固定工作方法，可以先让 xAgent 辅助生成 Skill 草稿，再测试、优化和发布。
每个会话都要预先加载所有 Skill 和 Tool 吗？
不需要。xAgent 会话默认具备发现和加载 Skill、Tool 的核心能力。任务执行过程中如果发现当前能力不够，会尝试查找并加载合适的 Skill 或 Tool。这样既节省上下文，也让智能体能按任务需要扩展自身能力。
普通用户需要自己配置工具和技能吗？
通常不需要。管理员可以先配置通用场景、专用智能体、工具、技能和外部连接，普通用户直接在会话里使用。
智能体和 Skill 有什么区别？
智能体是工作入口，Skill 是完成某类任务的方法。一个智能体可以关联多个 Skill。
为什么我只能看到公共智能体？
可能当前账号没有个人智能体，或权限只允许查看公共入口。以页面显示为准。
技能是否等同于工具？
不是。工具执行动作，技能沉淀方法。技能可以指导 xAgent 使用工具，但不替代工具权限。
技能越多越好吗？
不是。技能太多会让用户难以选择。应优先沉淀高频、稳定、有明确价值的流程。
普通用户必须选择技能吗？
不必须。管理员可以把技能关联到智能体，普通用户直接提交任务即可。
技能修改后是否立即生效？
草稿修改只影响当前草稿测试。发布到私人库后，后续任务可以使用新的个人 Skill。公共库 Skill 需要经过管理员审批和维护流程，已经运行中的任务是否采用新内容，以当前页面和会话行为为准。
工具和 Skill 有什么区别？
工具负责执行动作，Skill 负责记录方法。比如“读取 Excel”是工具动作，“如何分析销售数据”更像 Skill。
工具调用失败怎么办？
先看失败原因。常见处理方式是补充文件、完成授权、启用连接、调整任务范围，或联系管理员开启工具。
为什么有些工具我看不到？
工具会受账号权限、管理员配置、连接状态、个人 MCP 配置、AgentPlugin 授权状态和个人开关影响。
插件、远端 Agent 与触发器
如何调用远端 Agent？
在“运行治理 > A2A”添加并发现远端 Agent Card，配置对端认证，然后发起任务并在任务列表与收件箱核对结果。参见 A2A Client。
AgentPlugin 是否由 xAgent 保存目标系统 token？
不应这样描述。目标系统 token 属于 AgentPlugin 或目标系统边界。
AgentPlugin 的协议是否已经完全稳定？
当前标记为实验性，接口可能变化。
xAgent 是否保存目标系统登录态？
不应这样设计。目标系统登录态属于 AgentPlugin 或目标系统。
Agent 是否能看到内部 AgentPlugin Channel ID？
不应让 Agent 看到系统级和通道级内部 ID。
RuntimeConnection 是否等同于 AgentPlugin？
不等同。AgentPlugin 连接外部系统，RuntimeConnection 更关注执行环境。
RuntimeConnection 是否一定暴露给 Agent？
不一定。Agent 通常看到 Tool，而不是底层执行环境。
AgentPlugin 是什么？
AgentPlugin 负责把微信、Telegram、飞书、钉钉、Database、SSH 等外部系统接入 xAgent；浏览器能力由内置 Runtime 提供。插件可双向传递消息、文件引用和外部工具。普通用户通过“插件连接”管理自己的通道，管理员通过“AgentPlugin Connector”管理插件服务与安全策略。
Connector 与 AgentPlugin 是什么关系？
v0.0.16.beta 起原 Connector 领域统一改名为 AgentPlugin。旧 Connector 附件和早期更新日志是历史名称；当前产品菜单和安装目录使用 AgentPlugin。它也不是任意代码可直接装入 xAgent 进程的通用插件。
智能体是否直接管理外部系统登录态？
不管理。外部系统登录态属于外部连接或目标系统。
插件连接和 AgentPlugin Connector 有什么区别？
“运行治理 > 插件连接”用于绑定当前用户自己的外部账号；“Agent 治理 > AgentPlugin Connector”由管理员维护系统级插件服务。
AgentPlugin 工具会自动对所有用户可用吗？
不会。可用性取决于 AgentPlugin 是否在线、用户是否完成认证、连接状态、工具治理和审批策略。
为什么能收到消息但不能回复？
先检查 AgentPlugin health、用户认证和平台权限。微信还需要有效的收件人上下文；context_token 过期后，发送会被阻止，直到上下文重新建立。
触发器会一直等待任务完成吗？
不会。触发器负责启动任务，任务执行过程和结果仍在会话中查看。
为什么触发器没有运行？
先检查是否启用、调度与时区、目标会话、最近触发记录和错误。当前源码固定时间调度按 Asia/Shanghai（UTC+8）；目标忙碌时会延后重试。触发次数增加只代表任务消息被接受，不代表任务成功完成。外部连接、配置保存和后续审批也需分别核对，见触发器。
定时任务能不能直接发送消息？
能否发送取决于工具、连接和审批策略。建议默认先生成草稿，确认后再发送。
什么时候应该删除触发器？
确认不再需要且不会复用时再删除。只是暂停任务时，优先禁用。
审批、权限与敏感资料
密钥会被发送给模型提供商吗？
正常不会。xAgent 的工具配置使用密钥占位符，实际密钥只在内部调用工具时替换。模型提供商不需要看到密钥实际值。用户也不要把密钥、token 或密码明文写进任务消息。
可以把真实密钥作为示例吗？
不可以。示例只能使用占位值。
智能体是否总是自动执行所有工具？
不会。工具调用需要遵守当前会话、能力选择、权限和审批规则。
审批会阻止所有危险操作吗？
审批能降低风险，但不能替代账号权限、外部系统权限和管理员管理。敏感连接仍应按最小权限配置。
为什么同一个动作有时需要审批、有时不需要？
可能命中了不同资源范围、会话类型或个人策略。应以当前工具参数和个人、系统策略共同计算出的有效判定为准。
审批会阻止整个任务开始吗？
不会。任务可以先执行，只有命中策略的具体工具操作会暂停并等待审批。
可以从微信或 Telegram 处理审批吗？
可以。2026-10-01 核对的实现会尝试向当前用户可用的 IM 通道发送审批通知，不限于任务原始通道；具体到达仍取决于连接、认证和渠道发送状态。按通知中的 @{approval:id} 加明确同意或不同意回复，首个有效意见生效。旧的裸 #id 回复不再是当前标准。
普通用户能改系统审批策略吗？
通常不能。普通用户可能只能配置个人审批策略，系统级策略由管理员维护。
截图能不能保留 Base URL 和 API Key？
不建议。公开文档或公开渠道中的截图应遮盖内部地址、密钥和账号信息。
长期记忆与上下文
长期记忆和会话历史、上下文压缩一样吗？
不一样。长期记忆用于跨会话延续明确保留的偏好、决策和边界；会话历史记录当前交互，上下文压缩用于让长会话继续执行。
xAgent 会自动把聊天内容写入长期记忆吗？
旧版仅提供显式登记。2026-10-01 核对的实现有三条入口：用户明确要求记住、在“我的记忆”直接管理，以及压缩完成或会话闲置后的后台历史提炼。后台只接受有来源的偏好、已接受决策、事实和事件，不能自动产生长期规则或禁止项，也不是保存所有消息。旧部署是否包含这些入口，请核对版本。完整说明见长期记忆。
旧记忆会覆盖当前要求吗？
不会。当前用户输入、工具结果、权限和系统规则优先于旧记忆；过期、冲突或低置信度记忆也不能直接当作已确认事实。
记忆是否等同于聊天历史？
不是。聊天历史属于当前会话，记忆面向长期上下文和跨任务复用。
xAgent 有记忆能力吗？
有。xAgent 具备基础记忆能力，记忆在用户范围内共享，用于保存偏好、长期背景和反复使用的信息。用户也可以通过 MCP 扩展自己的记忆系统。后续也会考虑开放记忆接口，让第三方记忆系统可以和 xAgent 直通。
可以把 Memory 叫历史记录吗？
不可以。Memory 和 Session 历史是不同概念。
智能体是否直接保存长期记忆？
不直接保存。记忆是独立能力，智能体只在上下文中使用被投影出来的内容。
记忆是否自动保存所有消息？
不会。长期记忆需要有价值、可追溯，并且适合未来复用。
记忆是否替代会话历史？
不替代。会话历史用于当前会话上下文，记忆用于长期复用。
记忆规则是否已经完全稳定？
还没有完全稳定。使用时应把它视为辅助上下文，而不是唯一事实来源。
会话是否保存所有长期事实？
不应该。需要跨会话复用的偏好、决策或背景应进入记忆或其他明确位置。
协议、架构与文档维护
是否可以把所有能力都写成 Agent 的职责？
不可以。Agent 是执行主体，但不同事实有各自 owner。
架构文档是否等同于当前实现？
不一定。标记为 experimental 的内容可能包含目标架构或仍在收口的边界。
新增架构术语要做什么？
必须同步 术语表。
是否可以参考其他项目的 manifest 字段？
可以参考，但不能直接写入 xAgent 官方文档，除非 xAgent 已实现。
Manifest 是否只用于 Skill？
不应提前限定。具体归属以实现为准。
新增字段是否需要更新术语表？
如果字段引入新术语，需要同步更新术语表。
是否可以先写接入协议？
已有公开的 AgentPlugin 4.4 协议；实现前应核对目标 Server 版本、Card/Descriptor schema 及能力边界。旧 Connector 附件不是现行协议定义。
是否需要为 Markdown 写单元测试？
当前不要求。构建和链接检查是最低要求。
搜索插件如何验证？
先确认 npm run build 通过，再在本地启动或预览页面中验证搜索框可用。
文档内容正确性如何验证？
涉及功能行为、命令、配置或 API 时，应回查 xAgent 主仓库代码或已有文档。
这里会包含技术实现细节吗？
主线是使用手册。普通使用者优先阅读“开始使用”和“使用手册”；技术资料只作为维护和定制时的补充。
为什么这里只有少量命令？
使用手册只记录已核对、用户常用的入口。测试、评估、迁移类命令应放到更具体的维护文档中。
CLI 是否等同于 API？
不是。CLI 是命令行入口，API 是程序化调用接口。
为什么不列出 config.yml 的所有字段？
使用手册只列用户高频字段。完整字段应以当前代码和配置管理页面为准。
可以先写常见错误文案吗？
可以写排查方向，但不能编造错误码。
错误码是否需要稳定格式？
需要。稳定后应在本文集中维护。