# Astravia 文档
> 面向 Astravia 使用者与扩展开发者的任务指南、开发指南和参考资料。
- [Astravia 文档](/): 从本地工作区中的第一个任务，到可审查、可复用、可批量和可自动化的 Agent 工作流。
- 开始使用
- [快速开始](/getting-started): 安装 Astravia、完成首次引导、配置模型，并为第一个可验证任务准备工作区。
- [安装、升级与数据迁移](/getting-started/installation-and-updates): 选择正确的 Astravia 构建、完成升级，并安全迁移项目、会话和本地配置。
- [运行第一个完整任务](/getting-started/first-task): 在真实工作区中创建会话、提供上下文、检查执行过程，并用实际文件和验证结果完成验收。
- 核心工作流
- [理解 Astravia 的工作方式](/core/overview): 用工作区、任务、执行、结果和复用五个概念建立完整的产品心智。
- [项目、工作区与会话](/core/workspaces-and-sessions): 选择任务的文件边界，管理连续对话，并用项目指令保持长期约束。
- [上下文、工具与权限](/core/context-tools-and-permissions): 控制 Agent 能看见什么、调用什么，以及何时需要你的明确授权。
- [进度、结果与恢复](/core/progress-results-and-recovery): 查看待办、工具和后台任务，验证真实产物，并在中断或失败后继续工作。
- 使用指南
- [使用指南概览](/product/overview): 按任务选择模型、能力、知识库、批量任务、自动化与扩展。
- [配置模型](/product/models): 在设置中添加预设或自定义服务商、登记模型并选择默认与思考档位。
- [使用能力](/product/abilities): 在「能力」页安装并管理技能、场景、MCP、插件与套装。
- [配置 MCP 连接器](/product/mcp): 在能力页添加推荐或自定义 MCP，并管理凭证与自动批准。
- [让 Agent 操作浏览器](/product/browser): 用「浏览器操作」在真实浏览器里导航、读页、填表和复用登录态，并在提交前保留人工确认。
- [使用知识库](/product/knowledge-base): 导入本地资料、配置后台加工，并在会话中检索整理后的知识。
- [用 Astravia 做设计](/product/design): 在设计画布上用对话生成真实 React 界面，选中修改、留备注、预览运行、回退版本并导出分享。
- [使用智能体团队](/product/agent-teams): 用一支有负责人、有分工的常驻智能体团队完成一次任务，并理解它背后的委派与共享机制。
- [运行批量任务](/product/batch-tasks): 用一套任务配置并发处理多个独立目录，集中观察状态、校验产物并局部重试。
- [创建自动化任务](/product/automation): 把已经人工跑通的任务交给本地调度器，按单次、每天或间隔计划执行并检查历史。
- [使用 Astravia Claw](/product/claw): 启用 Claw，绑定 IM 渠道，在消息应用与桌面之间连续使用助手会话。
- [配置 IM 渠道](/product/im): 在设置 → Claw 中配置 IM 渠道，选择绑定、凭证或本机权限，并完成连接验证。
- [远程连接与移动端](/product/remote-control): 把 iPhone 或 Android 配到这台电脑，在手机上继续会话，还可以查看并操作桌面。
- [配置消息推送](/product/webhook): 在设置中添加飞书或钉钉 Webhook，供批量任务等场景推送通知。
- [管理应用环境](/product/application-environment): 检查并修复 Astravia 内置 Node.js、Python 与包镜像配置。
- [使用应用快照](/product/app-snapshot): 在 macOS 上按住左右同一功能键，把前台窗口的截图与文字挂到输入框，让 Agent 理解你此刻的屏幕。
- [使用桌宠 Astravia Vivi](/product/desktop-pet): 在设置中显示桌宠、调整置顶与气泡样式。
- [设置参考](/product/settings): 按当前设置页查找模型、远程连接、SSH 主机、外观、权限和集成配置。
- 实战示例
- [实战示例](/examples): 从可复制的完整任务开始，学习如何给出上下文、约束、产物、验收条件和恢复路径。
- [示例：审查并修复代码缺陷](/examples/review-and-fix-code): 在现有仓库中建立复现基线、限制修改范围，并用测试与差异完成一次可验证修复。
- [示例：把资料整理成决策简报](/examples/document-to-brief): 从指定文档提取事实、标注冲突和不确定项，并生成一份可复核的 Markdown 决策简报。
- [示例：批量审计多个项目](/examples/batch-project-audit): 用同一套只读规则检查多个独立目录，通过试跑、产物校验和抽样复核控制批次质量。
- [示例：按计划生成项目报告](/examples/scheduled-project-report): 把已经人工跑通的项目摘要交给本地调度器，通过立即执行、历史和真实产物验证计划任务。
- 插件开发
- [插件开发概览](/plugins/overview): 理解 Astravia 插件的运行方式、能力出口和信任边界。
- [创建第一个插件](/plugins/getting-started): 创建、构建并安装一个最小 Astravia 桌面插件。
- [清单与权限](/plugins/manifest-and-permissions): 声明插件身份、加载入口、样式、权限、命令、网络范围和 Agent 贡献，并理解授权与校验流程。
- [选择插件扩展点](/plugins/extension-points): 按产品目标选择界面、文件、Agent、Provider 或 App Action 扩展点，并对齐每项所需权限。
- [日志](/plugins/logging): 输出自动带插件身份、由桌面宿主持久化的结构化日志。
- [插件能力参考](/plugins/capabilities): 按目标查找 ctx 上的界面、对话、Agent、文件、网络、浏览器、模型、媒体与存储 API 及其权限边界。
- 主题开发
- [主题系统概览](/themes/overview): 使用主题模块定制 Astravia 外观、组件、页面、区域与运行时效果。
- [创建主题模块](/themes/getting-started): 定义主题清单、导出 ThemeModule 并在桌面应用中验证。
- [主题模块能力参考](/themes/module-reference): 理解 appearance、component、region、page、runtime、host hook 和主题存储的职责边界。
- 开发者
- [选择开发与集成路径](/developers/overview): 根据宿主边界选择插件、主题、SDK、RPC 或 CLI，避免为简单需求引入过重集成。
- [使用 Coding Agent SDK](/developers/sdk): 在 TypeScript 进程内创建 Agent 会话、订阅事件、发送任务并正确关闭资源。
- [Coding Agent API 参考](/developers/sdk-reference): 按公开导出路径查找 Session、Host、配置、扩展、资源和运行时 API，并遵守生命周期与兼容边界。
- [接入 RPC 模式](/developers/rpc): 通过 stdin/stdout NDJSON 驱动独立 Agent 进程，并正确处理响应、事件、取消和 Host Bridge。
- [CLI 与设置](/developers/cli-and-settings): 用 text 或 json 模式执行脚本任务，并理解全局、项目配置和资源路径的覆盖关系。
- [架构与包边界](/developers/architecture): 理解 Astravia 应用、运行时和核心 Agent 包之间的依赖方向。
- 参考
- [安全与数据边界](/reference/security-and-data): 理解本地工作区、模型请求、凭证、MCP、插件和执行权限之间的数据流。
- [配置与数据路径](/reference/configuration-paths): 查找模型、设置、MCP、能力、会话和项目级配置，并理解各路径的所有权。
- [平台与能力兼容性](/reference/compatibility): 查找 Astravia Desktop、手机、远程项目和构建模式的支持边界。
- [文档范围与版本](/reference/documentation-policy): 说明公开文档的内容边界和版本策略。
- [LLM 文档入口](/reference/llms): 获取适合 Agent 发现、检索和一次性读取的 Markdown 文档。
- [故障排查](/troubleshooting): 先判断失败发生在哪一层，再排查登录、模型、文件、知识库、MCP、插件、批量任务与自动化。
---
# 故障排查
> 先判断失败发生在哪一层，再排查登录、模型、文件、知识库、MCP、插件、批量任务与自动化。
Canonical page: /troubleshooting
先保留失败现场，不连续点击重试
从账号、模型、工作区、能力到任务逐层缩小范围
同时检查界面状态、执行记录和真实产物
遇到问题时，先记录发生时间、当前入口和最后一个成功步骤。反馈问题可使用 **设置 → 通用设置 → 导出诊断包**；不要附完整访问密钥、Cookie、OAuth 凭证或含隐私的项目内容。
## 五分钟快速定位 [#五分钟快速定位]
确认 Astravia、网络和目标外部服务当前可用。
新建一个短会话，显式选择模型，只发送一条最小消息。
确认会话绑定的工作目录真实存在，当前系统用户可访问。
暂时移除不必要的 MCP、技能、附件和长上下文，缩小变量。
打开失败任务的会话或历史，记录原始错误和发生时间。
| 现象 | 可能所在层 | 第一项检查 |
| ---------- | -------------- | --------------------------- |
| 任何会话都无法回复 | 登录、模型或网络 | 新会话中显式选择一个已验证模型 |
| 只有某个项目失败 | 工作目录、项目指令或权限 | 路径是否存在，沙盒是否允许目标动作 |
| 只有某个外部工具失败 | MCP 进程、URL 或授权 | **能力 → 我的** 中的连接和启用状态 |
| 显示成功但没有文件 | 任务验收条件或路径 | 检查工具记录和目标目录，而不是最终回复 |
| 到点未执行 | 自动化状态或本机环境 | Astravia 是否运行、设备是否睡眠、任务是否启用 |
| 多个子任务同时失败 | 共享提示、模型限流或目录模式 | 把并发降到 1，并打开一个代表性会话 |
## 按现象排查 [#按现象排查]
**先确认**：系统时间正确，网络可访问认证服务，浏览器完成授权后能够返回应用。
**如何恢复**：在登录弹层中使用 **重新授权** 或 **重新打开链接**。企业账号仍失败时，记录发生时间和组织信息后联系组织管理员，不要把浏览器 Cookie 发到问题报告。
**先确认**：
1. 会话或任务中已显式选择可用模型，或已设置默认模型。
2. **设置 → 模型配置** 中 API Key、Base URL、模型 ID 与 API 类型正确。
3. 网络与代理可访问对应上游，账户没有触发配额或速率限制。
4. 知识库加工场景已在 **知识库设置** 中执行 **测试连接**。
**如何验证**：新建空白会话，只发送短消息。短消息成功而原任务失败时，再检查上下文长度、工具或任务专属模型。
不要把完整访问密钥写进日志或问题报告。配置文件默认在 `~/.astravia/agent/models.json`。
**先确认**：会话绑定了正确工作目录，目标路径仍存在，当前系统用户有权限，文件没有被其它程序锁定。
**如何恢复**：先在「沙盒受限」内把任务缩小到工作区。确实需要更广访问时才切换为 **完全访问**，并重新核对允许修改的范围。不要用提升权限掩盖错误路径。
**先确认**：知识库总开关已开、处理模型已选且测试连接成功；查看待加工文件和 **整理记录**。
**如何恢复**：对失败项使用 **重试失败文件**。清空 Wiki 只删除整理结果、保留原始文件，但会触发重新加工；操作前确认配额和时间成本。会话回答仍异常时，先问一个只依赖单份已完成资料的问题并核对来源。
**先确认**：在 **能力 → 我的** 中 MCP 已添加且启用，凭证或 OAuth 已完成。检查 `~/.astravia/agent/mcp.json` 中 command/url，stdio 命令在 PATH 中可执行，HTTP 地址可从当前网络访问。
**如何验证**：使用 [MCP 最小验证任务](/product/mcp/#自动批准与排错) 先列出工具并调用一个只读工具。连接状态正常但没有工具时，检查服务端暴露项和当前会话是否已刷新能力。
**先确认**：导入 zip 根目录包含 `plugin.json` 与构建产物（如 `dist/mf-manifest.json`）；`remoteName`、`expose`、`entry` 与 Vite 配置一致。
**如何恢复**：重新构建并导入，再在 **启用与权限** 对话框中启用和授权。系统内置插件权限自动授予且不可改；外置插件只申请完成任务需要的权限。
**先确认**：**设置 → Claw** 总开关打开、活动渠道正确、对话模型可用，并保持 Astravia 运行。
**如何恢复**：先发 `/help` 验证命令通道，再使用 **查看日志** 定位并按需 **重启**。命令通道正常但普通消息失败时，继续检查模型和渠道绑定。
**先确认**：打开一个失败子任务的会话，判断是共享提示、单目录结构、模型限流还是超时。删除运行中的批量项目前需要先 **停止**。
**如何恢复**：单个失败优先使用失败项重试；大量相同失败先把并发降为 1 并验证代表性目录。停止会重置未完成任务的会话、产物和状态，已完成项是否保留以确认对话框为准。
**先确认**：Astravia 正在运行、设备未睡眠、任务已启用、系统时区和下次执行时间正确、工作目录没有移动。
**如何恢复**：先暂停计划，使用 **立即执行** 暴露模型、路径和权限错误；同时检查执行历史与真实输出文件。验证通过后再启用，错过的时间点不会自动补跑。
**先确认**：Astravia 内置环境与系统终端环境彼此独立。Git 面板使用的是 **应用环境** 里检测到的 Git，不一定等于终端里的 `git`。
**如何恢复**：打开 **设置 → 应用环境**。对 Node / Python 执行获取或重装；Git 未安装时按页面给出的方式安装，再点 **重新检测**。然后在 **Astravia 会话** 中验证版本。
**先确认**：电脑上的 Astravia 仍在运行，**设置 → 远程连接** 没有报错。二维码或连接码大约 10 分钟就会更新，用过的码不能再用。出门后连不上时，看 **允许在外网访问** 是否打开，以及中继地址能否连通。
**如何恢复**：点 **刷新** 重新配对。手动输入地址时，两端的 6 位验证码必须一致，并且网络不能把两台设备隔开。会话正常但 Android 没有桌面画面时，确认这部手机在线，并且它旁边电脑图标的右下角是绿色对勾。不要把二维码、连接码或密码发到问题报告里。详见[远程连接与移动端](/product/remote-control/)。
## 提交可复现的问题 [#提交可复现的问题]
如果最小场景仍失败，请在 [GitHub Issues](https://github.com/maomaochong-ai/open-astravia/issues) 提供：
* Astravia 版本、操作系统和安装来源。
* 最小复现步骤、期望结果和实际结果。
* 问题发生时间，以及是稳定复现还是偶发。
* 已脱敏的原始错误、相关执行历史和诊断包。
* 一个不含私有数据的最小示例项目（确有必要时）。
安全问题不要公开披露利用细节或凭证，先阅读[安全与数据边界](/reference/security-and-data/)中的报告入口。
---
# 上下文、工具与权限
> 控制 Agent 能看见什么、调用什么，以及何时需要你的明确授权。
Canonical page: /core/context-tools-and-permissions
上下文、工具和权限是三件分开呈现的事
引用具体文件，而不是模糊描述
先用沙盒和单次授权验证任务
任务质量取决于三件事：给了哪些上下文、允许使用哪些工具，以及动作是否越过当前权限边界。Astravia 将这三部分分开呈现，便于在效率和风险之间做明确选择。
## 组成一次模型调用的上下文 [#组成一次模型调用的上下文]
直接输入目标、约束和验收条件
`@`
引用或由工具读取源码、配置、文档和数据
粘贴或添加截图、界面和视觉参考
项目中的
`AGENTS.md`
，保存长期规则
输入
`/`
选择可复用方法和工作模式
本轮开启知识检索，使用跨项目长期资料
启用对应能力，接入外部工具和数据
输入区的上下文圆环显示最近一次模型调用的使用量。展开后可以检查基础指令、扩展能力、工具 Schema、历史消息和当前输入分别占用了多少上下文。
## 引用文件而不是模糊描述 [#引用文件而不是模糊描述]
需要 Agent 依据具体材料时，直接引用文件并说明用途：
```text
阅读 @src/auth/login.ts 和 @test/auth/login.test.ts。
定位无效刷新令牌仍被接受的原因，只修改认证模块，补充回归测试。
完成后运行认证测试并汇报实际结果。
```
外部拖入的图片会作为附件；其他文件通常作为引用。项目内文件引用不会复制一份新的事实源。
## 工具与执行模式 [#工具与执行模式]
Astravia 的工具可以读取和编辑文件、执行命令、搜索内容、维护待办，也可以由插件或 MCP 提供额外动作。
只允许工作区受限访问
适合来源不确定的项目、首次试跑
不需要访问项目外资源时优先使用
平台缺少可用沙盒后端时，界面会说明原因
允许访问当前系统中更广的文件和进程
适合明确需要跨目录或系统工具的任务
应确认提示词、项目和扩展来源可信
不要把它当成默认模式
默认执行模式在「设置 → 通用设置」中配置，只影响之后新建且未单独选择模式的会话，不会改变已经打开的会话。
## 处理权限请求 [#处理权限请求]
需要用户决策或高影响动作时，Astravia 把选择放回执行过程，而不是隐藏处理。
输入区的权限抽屉会列出等待确认的请求：
只授权当前请求。
当前会话后续同类请求直接允许。
不执行该动作，Agent 会收到拒绝结果。
确认前至少检查目标路径、命令、网络目的地和动作是否可撤回。不要因为任务来自可信项目就自动批准所有外部工具调用。
## 外部能力是新的信任边界 [#外部能力是新的信任边界]
技能会影响任务方法，插件可以扩展宿主界面和 Agent 能力，MCP 可以连接外部进程或服务。安装或启用前检查来源、权限和配置；凭证只填写在专用设置界面，不放进任务、项目文件或问题报告。
先用沙盒和单次授权验证任务。只有确实需要跨工作区访问时再切换完全访问，只有稳定且明确的同类动作才考虑会话级授权。
---
# 理解 Astravia 的工作方式
> 用工作区、任务、执行、结果和复用五个概念建立完整的产品心智。
Canonical page: /core/overview
Astravia 是带边界的本地工作台，不是聊天框
五项对象构成一次完整工作
验收看文件和执行记录，不看自信的总结
Astravia 不是只返回一段答案的聊天框。它把 Agent 放进一个明确的本地工作区，让模型在可检查的权限和工具边界内读取资料、修改文件、执行命令，并把过程和结果保留在会话中。
一个工作区同时容纳项目上下文、会话历史、Agent 执行和输出文件。
## 五个核心对象 [#五个核心对象]
01
工作区
一组本地资料与允许操作的边界
02
任务
目标、上下文、约束和验收条件
03
会话
一次连续工作的消息、工具和状态记录
04
执行
模型推理、工具调用、权限确认和后台工作
05
结果
回复、文件、产物、测试和未解决风险
工作区可以包含多个会话；每个会话在同一项目背景下处理一个连续目标。任务执行成功后，可以把稳定方法沉淀为技能、场景或知识，也可以交给批量任务和自动化再次运行。
## 一项工作的标准闭环 [#一项工作的标准闭环]
### 选择边界 [#选择边界]
选择现有项目、打开本地目录，或在默认「对话」工作区中开始。需要改文件时，优先使用对应项目目录。
### 给出可执行任务 [#给出可执行任务]
写清目标、允许处理的路径、必要约束和验收方式。使用 `@` 引用文件，使用 `/` 选择技能或场景。
### 观察和授权 [#观察和授权]
查看 Agent 的阶段性说明、待办、工具调用和后台任务。遇到权限请求时，核对动作和影响范围再决定是否允许。
### 验收结果 [#验收结果]
不只阅读最后一段回复，还要核对文件变化、产物、测试结果、失败工具和仍需人工收尾的事项。
## Astravia 与普通对话的区别 [#astravia-与普通对话的区别]
模型给出自信的总结不代表文件已经修改、命令已经成功或产物已经生成。以工作区中的实际文件和执行记录作为验收依据。
---
# 进度、结果与恢复
> 查看待办、工具和后台任务，验证真实产物，并在中断或失败后继续工作。
Canonical page: /core/progress-results-and-recovery
最后一段回复是交付说明，不是唯一证据
用目标、范围、验证和风险四层验收
失败后先看已经发生了什么，再缩小修复
Astravia 的最后一段回复是交付说明，不是唯一证据。任务是否完成，应以实际文件、工具结果、测试和活动记录共同判断。
## 在哪里观察执行 [#在哪里观察执行]
阶段性说明、工具卡片、最终回复。回答：Agent 当前在做什么。
待办、进行中、已完成。回答：计划走到哪一步。
项目文件和产物。回答：实际生成或修改了什么。
命令、子 Agent 与持续时间。回答：是否仍有工作在运行。
工具调用和请求历史。回答：哪个动作失败、参数是什么。
批量进度、自动化记录、知识加工。
长任务可以在后台继续。输入区显示待发队列；上一轮中断后，队列会暂停，需明确恢复或选择立即发送。
## 用四层证据验收 [#用四层证据验收]
03
验证
约定的测试、命令或人工检查是否真实执行。
04
风险
是否有失败工具、未完成待办或需人工收尾事项。
推荐在任务中提前写出验收条件：
```text
完成条件：
1. 无效刷新令牌返回 401；
2. 原有登录流程保持通过；
3. 新增一个回归测试；
4. 实际运行认证测试，并报告命令和结果；
5. 不修改认证模块之外的文件。
```
## 识别常见终止状态 [#识别常见终止状态]
| 状态 | 含义 | 下一步 |
| ---- | -------------- | -------------------- |
| 成功 | Agent 正常结束当前回合 | 按验收条件检查结果 |
| 失败 | 工具、模型或运行时返回错误 | 查看失败卡片和调试记录，修正后重试 |
| 中止 | 用户停止或宿主终止执行 | 确认是否有部分写入，再决定继续或新建会话 |
| 等待确认 | 动作需要用户授权或选择 | 检查影响范围后允许、拒绝或补充信息 |
| 后台运行 | 前台回复结束但仍有子任务 | 在后台任务面板等待、终止或检查独立结果 |
## 从失败中恢复 [#从失败中恢复]
### 先确认已经发生了什么 [#先确认已经发生了什么]
查看最后一个成功工具调用、当前文件和未完成待办。不要假设失败前没有产生任何修改。
### 缩小修复输入 [#缩小修复输入]
引用错误日志或失败文件，明确只处理剩余问题。避免原样重发一个宽泛任务导致重复工作。
### 选择继续、重试或分叉 [#选择继续重试或分叉]
同一路径继续处理用原会话；想保留现状并验证另一方案时分叉；上下文已经偏离目标时新建会话。
### 重新执行验收 [#重新执行验收]
修复成功后重新运行完整验收，不只运行刚才失败的单一步骤。
Astravia 会保存对话与工具记录，但不能替代 Git、项目备份或数据库迁移回滚。对重要项目执行破坏性任务前，先建立可恢复基线。
---
# 项目、工作区与会话
> 选择任务的文件边界，管理连续对话，并用项目指令保持长期约束。
Canonical page: /core/workspaces-and-sessions
先选对项目，再开始会话
长期规则写进 AGENTS.md
删除列表、清空历史和删除目录是三件不同的事
项目决定一组工作的本地目录和长期背景；会话记录一次连续任务的消息、工具调用和结果。先选对项目，再开始会话，可以减少路径错误和上下文混乱。
## 选择从哪里开始 [#选择从哪里开始]
咨询、无需固定项目的临时任务。不自动绑定具体项目目录。
在一个新目录中开始长期工作。文件边界是新项目目录。
让 Astravia 处理已有本地目录。文件边界是选择的目录。
让 Astravia 处理一台已登记 SSH 主机上的目录。命令和文件读写发生在那台机器上。
恢复带 Astravia 会话和状态的项目包。文件边界是导入后的项目目录。
需要读取、编辑或生成文件时，选择对应项目。只是讨论方案、起草短文本或查询信息时，可以从「对话」开始。
## 远程主机上的项目 [#远程主机上的项目]
本机目录之外，项目可以放在一台你本来就能用 `ssh` 连上的机器上。
1. 打开 **设置 → SSH 主机**，手动添加，或从 `~/.ssh/config` 导入别名。连接目标填终端里能连上的别名，或 `user@host`。
2. 添加项目时选择 **从远程主机添加**，再在那台机器上选目录。
3. 之后 Agent 的命令和文件读写都在那台主机上执行。会话里的终端也直接开在那台机器上，不必再自己开一个 ssh。
远程项目没有沙盒。沙盒只能约束这台电脑上的进程，而远程命令跑在远端。删除主机记录不会删除远端文件；如果上面还有项目，需要先移除那些项目。主机被删掉或重新添加后标识变了，项目会要求重新绑定，会话仍留在项目里。
## 项目与会话的关系 [#项目与会话的关系]
项目 / 工作区
目录、AGENTS.md、文件与产物
会话 A
修复登录问题
会话 B
补充部署说明
会话 C
从 B 分叉验证另一方案
一个项目可以有多个会话，它们共享项目目录，但各自保留对话和执行历史。
新目标通常新建会话；继续同一目标时恢复原会话。
分叉适合从既有上下文探索另一条路径，原会话不会被覆盖。
从列表移除项目不会删除磁盘目录；「删除项目」会永久删除目录，必须仔细阅读确认信息。
## 在消息旁单独提问 [#在消息旁单独提问]
阅读普通会话时，可选中一段文字，右键选择「问问 AI」。问答在小面板中进行，可以继续追问或停止回答。关闭面板后回答仍会继续，问题和回答自动保存。
保存过批注的消息会在悬停或键盘焦点时显示批注标记。点击标记可重新打开，并从批注面板搜索当前会话的问题和回答。
批注参考首次提问时截至原消息的文字上下文；已有压缩时使用摘要和后续记录，不读取图片内容或执行工具。它使用会话当前模型，独立产生模型用量，不增加普通会话，也不会将讨论写入主对话上下文。删除主会话会同时删除批注。
## 用项目指令保存长期约束 [#用项目指令保存长期约束]
项目详情页可以编辑 `AGENTS.md`。它适合保存所有会话都需要遵循的规则，例如技术栈、测试命令、目录所有权和禁止操作。
```markdown
# 项目约束
- 使用 Bun，不切换包管理器。
- 修改认证模块后运行 `bun run test:auth`。
- 不修改 `generated/`，它由构建脚本生成。
```
不要把一次性任务、密钥或个人临时信息写进项目指令。一次性要求放在当前消息中。
## 管理历史与产物 [#管理历史与产物]
侧栏展开项目即可查看最近会话，筛选器可区分普通、批量、对话和 Claw 会话。
项目详情显示会话数量，并提供新会话、导出和活动面板入口。
导出项目会包含项目文件、Astravia 会话历史和批量任务状态；文件锁会被排除。
「清空会话」删除历史但保留产物；「清空产物」删除输出文件但保留会话，两者语义不同。
「从列表移除」只改变 Astravia 列表；「清空会话」删除任务历史；「删除项目」会从磁盘永久删除整个目录。
## 推荐做法 [#推荐做法]
一个稳定目录对应一个项目。
一个清晰目标对应一个会话。
长期规则写入
`AGENTS.md`
，本次验收写在任务消息里。
需要比较方案时分叉，不在同一会话中来回覆盖目标。
重要项目在破坏性操作前先使用项目导出或自己的版本控制。
---
# 架构与包边界
> 理解 Astravia 应用、运行时和核心 Agent 包之间的依赖方向。
Canonical page: /developers/architecture
Astravia 使用 monorepo 管理桌面应用、服务和核心 TypeScript 包。依赖方向保持为：
```text
应用 → runtime-* → coding-agent → agent → ai
```
## 核心包 [#核心包]
## 运行时包 [#运行时包]
运行时层负责把 Coding Agent 能力组织成可被桌面宿主复用的会话、存储、工具、MCP 和遥测接口。运行时包不应依赖具体桌面界面。
## 应用层 [#应用层]
桌面应用负责 Electron 生命周期、原生能力、IPC 和用户界面。业务 API 负责账号、组织、模型服务配置及其他服务端规则。
核心库不依赖桌面应用或管理后台。新增能力时，应先确定契约属于核心、运行时还是宿主，避免把界面生命周期带入底层包。
---
# CLI 与设置
> 用 text 或 json 模式执行脚本任务，并理解全局、项目配置和资源路径的覆盖关系。
Canonical page: /developers/cli-and-settings
CLI 适合从终端执行一次任务、输出 JSON 事件或启动 RPC。桌面应用用户通常不需要手工维护这些文件；宿主和自动化集成应使用公开参数与 Schema。
## 运行一次任务 [#运行一次任务]
```bash
# 默认文本输出
astravia "总结当前目录的项目结构"
# 结构化 JSON 事件流
astravia --mode json "检查 package.json 中的脚本"
# 选择模型和思考档位
astravia --model openai/gpt-4o:high "分析这个故障"
# 恢复最近会话
astravia --continue "继续上次任务"
```
| 参数 | 说明 | | |
| ---------------------------------- | -------------- | ----- | ------- |
| \`--mode text | json | rpc\` | 输出或协议模式 |
| `--provider ` | 指定 Provider | | |
| `--model ` | 指定模型和可选思考档位 | | |
| `--continue` | 恢复当前会话目录中的最近会话 | | |
| `--session ` | 打开指定会话文件 | | |
| `--session-dir ` | 指定会话存储和查找目录 | | |
| `--no-session` | 不保存本次会话 | | |
`--resume` 已不支持，使用 `--continue` 或 `--session`。
## 设置覆盖 [#设置覆盖]
| 范围 | 路径 |
| -- | --------------------------------- |
| 全局 | `~/.astravia/agent/settings.json` |
| 项目 | `/.astravia/settings.json` |
项目设置覆盖全局设置。相对路径相对于各自配置文件目录解析；也支持绝对路径和 `~`。
常用配置包括默认模型、思考档位、消息队列、上下文压缩、自动重试、资源路径、MCP、图片处理、个性化和 shell。完整字段以 `@astravia/coding-agent/settings` 导出的 Schema 为准。
## Windows Shell [#windows-shell]
Windows 默认查找 Git Bash 或 PATH 中的 `bash`。也可以显式配置：
```json
{
"shellPath": "C:\\Program Files\\Git\\bin\\bash.exe",
"shellCommandPrefix": "shopt -s expand_aliases"
}
```
不要把 API Key 写进 `shellCommandPrefix` 或会被记录的命令。优先使用凭证配置或受控环境变量。
## 安装资源包 [#安装资源包]
CLI 可以安装包含 extensions、skills 和 prompts 的 npm、Git 或本地资源源：
```bash
astravia install npm:@scope/package@1.2.3
astravia install git:github.com/example/repo@v1
astravia list
astravia update
astravia remove npm:@scope/package
```
资源包中的扩展可以执行代码。安装前审查来源、版本和权限，不要把不可信仓库直接加入长期配置。
---
# 选择开发与集成路径
> 根据宿主边界选择插件、主题、SDK、RPC 或 CLI，避免为简单需求引入过重集成。
Canonical page: /developers/overview
先选最窄、最稳定的入口
提示词不是插件，外部工具不是桌面扩展
跨包只走公开 exports
Astravia 提供从内容能力到完整宿主集成的多层扩展面。先根据目标选择最窄、最稳定的入口，再阅读对应合同。
插件可以进入工作区、文件和消息界面；SDK 与 RPC 则用于在自己的宿主中运行 Agent。
## 入口选择 [#入口选择]
让 Agent 遵循领域流程。运行边界是 Markdown 指令和可选脚本。
连接外部工具或数据。运行边界是 STDIO 或 HTTP 工具服务。
扩展 Astravia 桌面 UI 和 Agent。运行边界是插件宿主与权限模型。
改变桌面视觉和主题页面。运行边界是受策展管理的主题模块。
在 TypeScript 进程中嵌入 Agent。同进程、类型化 Session API。
从非 TS 宿主或隔离进程驱动 Agent。stdin/stdout NDJSON。
从脚本执行一次任务。独立命令进程，text / json 输出。
## 决策原则 [#决策原则]
只有提示和步骤时使用 Skill，不要创建插件。
只需要外部工具协议时使用 MCP，不要依赖桌面内部实现。
需要 Astravia UI、文件预览、消息卡片或宿主动作时使用 Plugin。
自己拥有进程生命周期且使用 TypeScript 时优先 SDK。
需要语言无关、故障隔离或 sidecar 时使用 RPC。
跨包集成只能使用 `package.json#exports` 声明的子路径。不要从 `@astravia/coding-agent/src/**` 或其他包的源码目录深度导入。
---
# 接入 RPC 模式
> 通过 stdin/stdout NDJSON 驱动独立 Agent 进程，并正确处理响应、事件、取消和 Host Bridge。
Canonical page: /developers/rpc
RPC 模式适合语言无关集成、sidecar 和需要进程隔离的宿主。每行是一个完整 JSON 帧；stdout 只用于协议，诊断信息写入 stderr。
同一 TypeScript 进程内集成优先使用 [SDK](/developers/sdk/)，不必额外管理子进程和帧关联。
## 启动进程 [#启动进程]
```bash
astravia-agent-rpc --mode rpc \
--session-dir /path/to/conversations \
--provider openai \
--model openai/gpt-4o
```
* 工作目录就是进程 `cwd`，RPC 中没有运行时修改 cwd 的命令。
* 一个进程只有一个活动会话。
* `--continue` 恢复目录中最近会话；`--session ` 打开指定会话。
* `--no-session` 创建不落盘的临时会话。
* 同一会话文件禁止多个 writer。
## 帧模型 [#帧模型]
| 方向 | 形状 |
| ---------- | -------------------------------------------------------------------------- |
| 宿主 → Agent | `{ "id"?, "type", ... }` |
| 成功响应 | `{ "id"?, "type": "response", "command", "success": true, "data"? }` |
| 失败响应 | `{ "id"?, "type": "response", "command", "success": false, "error", ... }` |
| Agent → 宿主 | agent、turn、message、tool、compaction、retry 等事件 |
`id` 用于将异步响应关联回请求。事件不等同于响应，宿主必须分别路由。
```json
{"id":"req-1","type":"prompt","message":"总结当前项目"}
{"id":"req-1","type":"response","command":"prompt","success":true}
{"type":"agent_start"}
{"type":"message_update","assistantMessageEvent":{"type":"text_delta","delta":"项目"}}
{"type":"agent_end"}
```
实际事件字段以 `@astravia/coding-agent/rpc` 导出的类型为准。
## 命令分组 [#命令分组]
| 目标 | 命令 |
| ----- | ------------------------------------------------------------- |
| 输入 | `prompt`、`steer`、`follow_up`、`abort`、`new_session` |
| 状态 | `get_state`、`get_session_stats`、`get_messages`、`get_commands` |
| 模型 | `set_model`、`cycle_model`、`get_available_models` |
| 思考 | `set_thinking_level`、`cycle_thinking_level` |
| 队列 | `set_steering_mode`、`set_follow_up_mode` |
| 上下文 | `compact`、`set_auto_compaction` |
| 重试 | `set_auto_retry`、`abort_retry` |
| Shell | `bash`、`abort_bash` |
| 会话 | `switch_session`、`fork`、`set_session_name`、`export_html` 等 |
## 宿主必须保留的语义 [#宿主必须保留的语义]
1. 逐行解析，不能把 stdout 当成人类日志。
2. 同时处理请求响应和无请求 ID 的事件。
3. 流式正文来自 `message_update.assistantMessageEvent`，不要只等最终响应。
4. `abort`、自动重试、压缩、工具失败和 Agent 终止都要投影到宿主状态。
5. 进程退出时，将未完成请求统一失败并保留 stderr 诊断。
6. 切换会话前等待切换响应，不要并发向旧会话继续写入。
## Extension UI 与 Host Bridge [#extension-ui-与-host-bridge]
扩展需要确认或选择时，Agent 发出 `extension_ui_request`，宿主使用 `extension_ui_response` 回答。没有 UI 的宿主应明确取消，不要无限等待。
`--enable-host-bridge` 为 Agent 增加反向宿主调用，例如 IM 场景发送附件：
* Agent → 宿主：`host_request`
* 宿主 → Agent：`host_response`
只在确实实现了对应方法和权限检查时启用 Host Bridge。
任意启动横幅、调试日志或第三方输出写入 stdout 都会破坏 NDJSON 协议。宿主和扩展的诊断必须使用 stderr 或结构化事件。
---
# Coding Agent API 参考
> 按公开导出路径查找 Session、Host、配置、扩展、资源和运行时 API，并遵守生命周期与兼容边界。
Canonical page: /developers/sdk-reference
本页是 `@astravia/coding-agent` 的导出地图。具体类型、参数和返回值以安装版本的声明文件为准；示例应只从 `package.json#exports` 中列出的入口导入，不要深度导入 `src/**`。
## 导出路径 [#导出路径]
| 入口 | 用途 |
| -------------------------------------------- | ---------------------------- |
| `@astravia/coding-agent` | 默认产品组合入口 |
| `@astravia/coding-agent/sdk` | 创建和管理进程内 Session |
| `@astravia/coding-agent/rpc` | NDJSON RPC 帧、命令和事件合同 |
| `@astravia/coding-agent/settings` | 全局/项目设置和 Schema |
| `@astravia/coding-agent/resources` | Skill、Extension、Prompt 等资源来源 |
| `@astravia/coding-agent/extensions` | Extension 来源与生命周期 |
| `@astravia/coding-agent/session-extensions` | Session 级扩展能力 |
| `@astravia/coding-agent/hooks` | Host/Agent 生命周期 Hook |
| `@astravia/coding-agent/host-services` | 宿主提供的模型、文件和运行时服务 |
| `@astravia/coding-agent/historical-sessions` | 离线读取和管理历史会话 |
| `@astravia/coding-agent/bootstrap` | 从启动参数和环境创建宿主配置 |
| `@astravia/coding-agent/function-extensions` | 函数式扩展来源 |
| `@astravia/coding-agent/plugin-runtime` | 插件运行时桥接 |
| `@astravia/coding-agent/export-html` | 会话 HTML 导出 |
| `@astravia/coding-agent/profile` | Host profile 选择 |
| `@astravia/coding-agent/cli-guidance` | CLI 入口提示与参数指导 |
| `@astravia/coding-agent/runtime` | 运行时组合和生命周期接口 |
| `@astravia/coding-agent/model-context` | 模型上下文和消息输入合同 |
## Session 生命周期 [#session-生命周期]
推荐顺序是：
```text
create → inspect diagnostics → subscribe → prompt / steer / followUp
→ abort or complete → unsubscribe → close
```
* 创建阶段处理 `diagnostics`，不要静默吞掉资源或扩展加载失败。
* `subscribe()` 返回的取消函数必须在宿主销毁时调用。
* `abort()` 只中止当前执行，不替代 `close()`。
* 文件存储 Session 必须明确创建、恢复或内存语义；多个活动 Session 不得写同一会话文件。
* 宿主应保留 Agent、turn、message、tool、compaction、retry 和终止事件的语义。
完整的最小示例见 [使用 Coding Agent SDK](/developers/sdk/)。
## 集成边界 [#集成边界]
| 需求 | 推荐入口 | 不应做的事 |
| --------------------------- | --------------------------- | ----------------------------- |
| TypeScript 进程内运行 Agent | `sdk` | 解析 CLI stdout 或复制 Session 状态机 |
| 语言无关或隔离进程 | `rpc` | 把诊断日志混入 stdout |
| 离线展示历史 | `historical-sessions` | 为展示列表打开所有活动 Session |
| 提供模型/文件等宿主能力 | `host-services` / `runtime` | 从 Desktop 私有实现目录导入 |
| 注入 Skill、Prompt 或 Extension | `resources` / `extensions` | 直接修改内置资源目录 |
| 使用插件贡献能力 | `plugin-runtime` | 绕过 manifest 和权限校验 |
## 兼容策略 [#兼容策略]
1. 在 `package.json` 中固定兼容的 `@astravia/coding-agent` 版本范围。
2. 启动时记录版本和 diagnostics，遇到未知能力时提供降级或清晰错误。
3. RPC 宿主按响应和事件分别路由，并处理无 `id` 的事件。
4. 取消、重试、压缩、工具失败和进程退出都要映射到上层状态。
5. 只有公开导出、类型定义和文档明确承诺的字段才可作为集成合同。
本页帮助选择入口，不替代版本化 API 声明。升级依赖后重新检查导出路径、事件联合类型和错误码，并运行宿主自己的合同测试。
---
# 使用 Coding Agent SDK
> 在 TypeScript 进程内创建 Agent 会话、订阅事件、发送任务并正确关闭资源。
Canonical page: /developers/sdk
`@astravia/coding-agent/sdk` 是进程内集成入口。它提供类型化 Session、Host 和离线会话目录，不要求通过 CLI 或解析 stdout。
## 创建最小会话 [#创建最小会话]
```typescript
import { createCodingAgentSession } from "@astravia/coding-agent/sdk";
const { session, diagnostics, modelFallbackMessage } =
await createCodingAgentSession({
cwd: process.cwd(),
storage: { kind: "memory" },
});
for (const diagnostic of diagnostics) {
console.error(diagnostic.code, diagnostic.message);
}
if (modelFallbackMessage) console.warn(modelFallbackMessage);
const unsubscribe = session.subscribe((event) => {
if (event.type === "message_update") {
// Consume typed session events in your own UI or logger.
}
});
try {
await session.prompt("检查当前目录并总结项目结构");
console.log(session.getLastAssistantText());
} finally {
unsubscribe();
await session.close();
}
```
如果没有通过参数、配置或宿主服务得到可用模型，创建会话会抛出带稳定错误码的 `CodingAgentSessionCreateError`。
## 选择存储意图 [#选择存储意图]
| `storage.kind` | 语义 | 必要参数 |
| -------------- | -------- | ------------------------------- |
| `memory` | 会话不落盘 | 无 |
| `file-create` | 创建新的会话文件 | `conversationDir` |
| `file-resume` | 恢复指定会话 | `conversationDir`、`sessionPath` |
存储意图应在创建时明确。不要让多个活动 Session 同时写同一个会话文件。
## 核心生命周期 [#核心生命周期]
create
→
subscribe
→
prompt / steer / followUp
→
abort or complete
→
close
* `prompt()` 启动一个正常用户回合。
* `steer()` 在当前执行中加入引导消息。
* `followUp()` 将消息放入后续队列。
* `abort()` 中止当前执行，但仍需调用 `close()` 释放会话资源。
* `subscribe()` 返回取消订阅函数，宿主销毁时必须调用。
## Session、Host 与 Catalog [#sessionhost-与-catalog]
| API | 使用场景 |
| ----------------------------------- | ------------------------------------- |
| `createCodingAgentSession()` | 单个明确生命周期的活动会话 |
| `createCodingAgentHost()` | 批量持有和关闭多个配置彼此隔离的 Coding Agent Session |
| `createCodingAgentSessionCatalog()` | 离线列出、查询和管理会话元数据 |
Catalog 与活动 Session 分离，不应为了展示会话列表而打开所有会话。
这里的 `CodingAgentHost` 是 SDK 便利所有权组，不是多主 Agent Registry。每个成员可以有独立 cwd、Storage、Tool、MCP、
Extension Source 和模型资源；若要在一个进程内动态安装、替换或退役不同 `agentId`，应使用
`@astravia/runtime-core` 的 `RuntimeHost.installAgent()`。
## 可选产品能力 [#可选产品能力]
Session 还提供模型和思考档位、工具开关、上下文压缩、自动重试、会话命名、后台任务、子 Agent、待办、MCP 重载、资源重载和 HTML 导出等能力。按需调用，不要在宿主层复制同一状态机。
创建参数可提供：
* `resources`、`skillSources`、`extensionSources`：静态或动态能力来源。
* `customTools`：类型化自定义工具。
* `askUserQuestion`：把模型提问交给宿主 UI。
* `enableBackgroundTasks`、`enableSubagents`、`enableMcp`：显式启用对应能力。
* `observationHub`：把 Agent、RuntimeHost、Tool、MCP、Prompt 与活动 Session 生命周期事件接到本地 Adapter
或上层应用 Hub；Adapter 由调用方持有。
* `env`：传入受控环境变量，而不是修改进程全局状态。
## 错误与关闭 [#错误与关闭]
1. 在创建阶段读取 `diagnostics`，不要静默忽略扩展加载失败。
2. 订阅 Agent、turn、message、tool、compaction 和 retry 事件，向用户保留终止语义。
3. 宿主取消时先 `abort()`，再等待或关闭会话。
4. 将 `close()` 放进 `finally` 或宿主生命周期钩子。
5. 不从实现目录导入管理器来绕过公共合同。
完整类型以 `@astravia/coding-agent/sdk` 的声明为准。
---
# 示例：批量审计多个项目
> 用同一套只读规则检查多个独立目录，通过试跑、产物校验和抽样复核控制批次质量。
Canonical page: /examples/batch-project-audit
每个目标目录都必须能独立完成
先以并发 1 试跑代表性目录
固定产物只能证明文件存在，仍需抽查内容
这个示例检查多个项目是否具备清晰的开发入口。它只生成报告，不修改项目配置，适合作为第一次批量任务练习。
## 起始状态 [#起始状态]
准备 2–5 个彼此独立、结构具有代表性的项目目录。不要选择需要共享中间结果或必须按顺序处理的目标。
每个目录都可以由同一条任务独立审计。
目录中没有另一个正在执行写操作的任务。
已选出一个风险较低的代表性目录用于试跑。
报告文件名
`astravia-project-audit.md`
不会覆盖已有内容。
## 配置共享任务 [#配置共享任务]
在 **更多 → 批量任务** 新建项目，第一次只添加一个目录，并发设为 `1`，产物校验填 `astravia-project-audit.md`。
```text
审计当前项目的本地开发入口，只生成 astravia-project-audit.md，不修改其他文件。
请检查 README、项目清单、工作区配置和已有脚本，并在报告中写明：
1. 项目类型与主要运行时；
2. 安装、开发、测试、检查和构建命令；
3. 每条命令来自哪个文件；
4. 缺失、冲突或明显过时的说明；
5. 新贡献者从零开始的最短验证路径；
6. 无法静态确认、需要人工执行的事项。
不要安装依赖，不要运行可能产生外部副作用的命令，不要猜测不存在的脚本。
完成后确认 astravia-project-audit.md 存在，并重新读取它检查六个部分。
```
## 先试跑，再扩大批次 [#先试跑再扩大批次]
### 检查代表性目录 [#检查代表性目录]
启动单个任务，进入它的会话，确认读取范围、报告结构和事实来源正确。
### 修正共享任务 [#修正共享任务]
如果项目类型差异导致要求不适用，把它改成明确的条件分支，不要为单个目录写隐藏例外。
### 添加其余目录 [#添加其余目录]
试跑通过后再加入剩余目录。先使用较低并发，观察模型限流和本机负载后再调整。
## 预期产物 [#预期产物]
每个目录顶层各有一份 `astravia-project-audit.md`，报告结构一致，但事实、命令和待确认项来自各自项目。批量看板显示每个子任务的独立状态和会话。
## 验收结果 [#验收结果]
任务总数与目标目录数一致，没有重复路径。
所有完成项都通过产物校验，失败项已进入对应会话定位。
随机抽查一个常规项目和一个结构不同的项目。
报告中的命令都能在对应配置或 README 中找到。
没有项目源码、清单或锁文件被修改。
## 结果不符合时恢复 [#结果不符合时恢复]
单个目录失败时，先打开它的会话查看原因；修正共享提示后使用失败项的重试能力，不要停止并重置整个批次。若大量目录因同一要求失败，暂停扩大并发，回到一个代表性目录重新验证规则。
```text
只修正当前审计报告中的 [具体问题]。保持只读，不修改项目文件。
先核对 [README 或配置文件]，再更新 astravia-project-audit.md，并重新检查六个必需部分。
```
批量任务中的停止与暂停不同，可能重置未完成项的会话、产物和状态。操作前阅读确认对话框。
---
# 示例：把资料整理成决策简报
> 从指定文档提取事实、标注冲突和不确定项，并生成一份可复核的 Markdown 决策简报。
Canonical page: /examples/document-to-brief
把来源限制在明确目录或知识库
要求区分事实、推断和缺失信息
用固定文件结构让结果容易复核
这个示例把会议记录、需求说明和调研材料整理成简短决策输入。它既可以直接读取当前项目中的文件，也可以在资料需要长期复用时先导入[知识库](/product/knowledge-base/)。
## 起始状态 [#起始状态]
在项目中准备以下结构，文件名可以不同：
```text
research/
requirements.md
meeting-notes.md
alternatives.md
output/
```
先打开几份源文件，确认它们可读取且没有不应交给模型处理的敏感信息。扫描版或无法提取文字的文件应先完成 OCR，或从本次范围中排除并明确标注。
## 提交完整任务 [#提交完整任务]
```text
只读取 research/ 下的资料，生成 output/decision-brief.md，不修改源文件。
简报必须包含：
1. 决策主题与一句话结论；
2. 已确认事实，每条注明来源文件；
3. 可选方案，以及各自收益、成本和风险；
4. 材料之间的冲突或口径差异；
5. 无法从现有材料确认的问题；
6. 下一步建议，并区分“材料直接支持”和“基于材料的推断”。
约束：
- 不使用 research/ 之外的信息补全事实；
- 不确定时写“待确认”，不要猜测；
- 引用使用相对文件路径，必要时补充章节标题；
- 保持在 1200 字以内，使用清晰的 Markdown 标题和表格；
- 完成后重新读取输出文件，确认六个部分都存在，并列出实际使用和无法读取的来源。
```
## 预期产物 [#预期产物]
`output/decision-brief.md` 应该独立可读。读者不需要打开全部源文件，也能知道结论来自哪里、哪些内容仍需确认、下一步由什么证据支持。
## 验收结果 [#验收结果]
输出文件存在，源文件没有被修改。
每条关键事实都能回到实际存在的来源文件。
材料没有提到的内容被标为推断或待确认，没有伪装成事实。
冲突没有被悄悄合并成一个看似确定的结论。
结论、方案、风险和下一步符合要求的长度与结构。
抽查至少三条关键事实：打开对应源文件，核对语义和上下文，而不只检查路径是否存在。
## 结果不符合时恢复 [#结果不符合时恢复]
如果事实正确但结构太散，保留来源提取结果，只要求重写输出：
```text
保留当前已经核对过的事实和来源，不要重新扩大检索范围。
请重写 output/decision-brief.md：把 [具体问题] 修正为 [目标结构]，并再次检查来源与“待确认”标记。
不要修改 research/ 下的文件。
```
如果出现错误归因，先列出“简报陈述 → 当前来源 → 正确来源或无来源”的核对表，再修订文件；不要让 Agent 只润色措辞掩盖证据问题。
---
# 实战示例
> 从可复制的完整任务开始，学习如何给出上下文、约束、产物、验收条件和恢复路径。
Canonical page: /examples
选择与目标最接近的示例
先替换路径和输入，不急着删掉约束
用真实产物与检查结果验收，而不是只看最终回复
这里不是提示词合集。每个示例都是一条可以复现的工作流：先准备明确的起始状态，再提交完整任务，观察执行证据，最后检查文件、测试或历史记录。示例中的路径和名称只是占位，请替换为自己的内容。
## 选择一个目标 [#选择一个目标]
适合已有仓库中的局部 Bug：先复现，限制修改范围，再用定向测试和差异验收。
适合需求、会议记录和调研资料：标注来源、冲突与待确认项，生成固定文件。
适合同一规则作用于多个目录：先用一个目录试跑，再设置并发和产物校验。
适合已经人工跑通的重复任务：固定输入输出，立即执行验证，再开启计划。
## 一份可靠任务的共同结构 [#一份可靠任务的共同结构]
起始目录、输入文件和外部依赖真实存在。
任务写清允许读取、允许修改和禁止触碰的范围。
产物有固定路径、格式或测试命令，不只要求“给出答案”。
遇到不确定信息时要求停止、标注或请求确认，而不是猜测。
失败后可以缩小范围继续，不必重新开始整个任务。
第一次尝试文件修改、批量或自动化时，优先使用可恢复的测试目录，并从「沙盒受限」和最小权限开始。
---
# 示例：审查并修复代码缺陷
> 在现有仓库中建立复现基线、限制修改范围，并用测试与差异完成一次可验证修复。
Canonical page: /examples/review-and-fix-code
先复现问题，再允许修改
把必须保持的行为写进任务
用测试、类型检查和最终差异验收
这个示例适合已有代码仓库中的局部 Bug。目标不是让 Agent “看看代码”，而是交付一条能够被证明有效、范围清楚且容易回退的修改。
## 起始状态 [#起始状态]
准备一个可恢复的测试仓库，并确认：
项目能够按 README 安装和运行，当前失败不是依赖未安装造成的。
问题有明确现象、复现步骤或失败测试。
工作区中已有修改已经保存，并且你知道哪些改动不能覆盖。
Astravia 会话绑定到仓库根目录，首次尝试使用「沙盒受限」。
## 提交完整任务 [#提交完整任务]
把方括号内容替换为真实信息；不知道测试命令时，保留“从项目脚本中确认”这条要求。
```text
修复 [页面或模块] 中的这个问题：[实际现象]。
复现步骤：
1. [第一步]
2. [第二步]
3. 当前结果是 [错误结果]；期望结果是 [正确结果]。
工作要求：
- 先阅读当前目录适用的项目指令、README、相关源码和测试；
- 先运行最小复现或相关测试，记录修改前的基线；
- 找出根因后再修改，不绕过现有校验，也不覆盖工作区中的已有改动；
- 修改范围限制在 [允许修改的目录或模块]；
- 为这个回归新增或更新一个在旧行为下会失败的测试；
- 运行相关测试和项目已有的快速检查；
- 最后说明根因、主要修改、实际运行的命令与结果，以及仍未验证的风险。
如果复现信息不足、必须改动公共合同，或需要执行不可恢复操作，请先停止并说明原因。
```
## 执行时检查证据 [#执行时检查证据]
先出现复现结果或失败测试，而不是直接开始大范围编辑。
读取和修改集中在相关模块，没有顺手重写无关文件。
遇到权限、冲突或不明确合同会暂停说明。
修改后重新运行同一复现，并补充与风险匹配的检查。
## 预期产物 [#预期产物]
* 一组针对根因的源码修改，而不是只改错误提示或隐藏失败。
* 一个能够防止同类回归的测试；纯配置或文档问题除外。
* 实际执行过的测试、类型检查或 lint 结果。
* 一份简短交付说明，明确未运行的高成本验证及原因。
## 验收结果 [#验收结果]
原始复现现在通过，且不是通过删除功能或降低校验实现。
新增测试确实覆盖用户可观察行为，而不是只断言内部调用。
最终差异中没有密钥、生成垃圾或无关格式化。
已有工作区改动仍然保留。
Agent 没有声称未实际运行的检查已经通过。
## 结果不符合时恢复 [#结果不符合时恢复]
不要重新提交整个任务。指向具体证据，让 Agent 在现有会话中缩小修正范围：
```text
当前修复还不能验收：[失败测试或具体差异]。
请保留已经正确的修改，只处理 [文件/行为]；不要扩大到 [禁止范围]。
先解释这个失败与根因的关系，再修改并只重跑相关验证。完成后列出新的差异和结果。
```
如果修改方向已经错误，停止会话并从 Git 或备份恢复受影响文件，再用更窄的允许范围重新开始。
---
# 示例：按计划生成项目报告
> 把已经人工跑通的项目摘要交给本地调度器，通过立即执行、历史和真实产物验证计划任务。
Canonical page: /examples/scheduled-project-report
自动化只接收已经人工跑通的任务
提示词不能依赖上一次会话记忆
执行历史与真实文件必须同时检查
这个示例每天从项目中的明确来源生成状态报告。它不依赖云端常驻：到点时需要 Astravia 正在运行，计算机没有睡眠或关机。
## 起始状态 [#起始状态]
目标项目中已有 `tasks/` 或其他稳定的任务记录目录，并允许写入 `reports/`。先在普通项目会话中运行一次下面的任务，确认输入路径和输出内容符合预期。
同一提示在普通会话中至少成功过一次。
输入路径每次执行都存在，不依赖临时附件。
报告路径不会覆盖人工维护的文件。
任务不需要临场批准高风险动作。
所选模型和必要能力在无人值守时可用。
## 准备无人值守任务 [#准备无人值守任务]
```text
读取当前项目中 tasks/ 下的任务记录，以及最近更新的 CHANGELOG.md（存在时）。
生成 reports/daily-status.md，不修改其他文件。
报告包含：
- 生成时间和实际读取的来源；
- 已完成、进行中、阻塞三类事项；
- 信息不足或相互冲突的记录；
- 下一工作日的三个优先建议。
只根据项目文件总结，不补充外部事实。没有变化时仍生成报告并写明“本次未发现新记录”。
完成后重新读取 reports/daily-status.md，确认以上部分存在；如果输入目录不存在或无法读取，让任务失败并说明原因，不要生成虚假成功报告。
```
## 创建并立即验证 [#创建并立即验证]
### 新建自动化 [#新建自动化]
在侧栏 **自动化** 创建任务，选择已经试跑成功的工作目录、模型和执行模式。
### 设置计划 [#设置计划]
选择每天或所需间隔，并核对界面显示的下次执行时间和系统时区。
### 立即执行 [#立即执行]
保存后使用 **立即执行**，不要等到计划时间才验证目录、凭证和权限。
### 同时检查两类证据 [#同时检查两类证据]
在执行历史中打开对应会话，并到项目目录检查 `reports/daily-status.md` 的实际内容。
## 预期产物 [#预期产物]
* 自动化详情中出现一次可打开的执行记录。
* 项目中存在 `reports/daily-status.md`，包含生成时间和实际来源。
* 下一次执行时间符合预期，任务处于启用状态。
## 验收结果 [#验收结果]
立即执行成功，且不是只有最终回复、没有报告文件。
报告事实可以回到
`tasks/`
或
`CHANGELOG.md`
。
输入缺失会形成明确失败，而不是沿用旧报告冒充新结果。
计划时间、系统时区、启用状态和工作目录均正确。
已理解 Astravia 退出或设备睡眠时不会按计划执行。
## 结果不符合时恢复 [#结果不符合时恢复]
先暂停任务，避免错误配置继续运行。根据历史中的具体失败编辑路径、模型、权限或提示，然后再次使用 **立即执行**；验证通过后再启用计划。错过的时间点不会因为重新启用自动补跑，需要时手动立即执行一次。
```text
本次报告的问题是：[缺少来源 / 路径错误 / 内容不完整]。
只修正 reports/daily-status.md，重新读取指定来源，不修改其他文件。
如果来源仍不可用，请明确失败，不要沿用旧内容。
```
---
# 运行第一个完整任务
> 在真实工作区中创建会话、提供上下文、检查执行过程，并用实际文件和验证结果完成验收。
Canonical page: /getting-started/first-task
一次可检查的小型文档任务
把目标、范围和验收写进同一条消息
用文件和工具记录验收，而不是只读回复
本页用一个小型文档任务走完 Astravia 的标准闭环：选择工作区、提交可执行目标、处理权限请求、检查产物并继续修正。第一次不要选择大规模迁移或不可逆操作。
## 本次任务的结果 [#本次任务的结果]
假设项目中已有 `README.md` 和 `package.json`，让 Astravia 补充一份准确的本地开发说明。完成后应看到：
项目目录中新增或更新
`docs/local-development.md`
。
文档中的安装、检查和测试命令来自当前项目事实，而不是模型猜测。
Agent 实际运行至少一个无副作用的检查命令，并在最终回复中报告结果。
除目标文档外没有意外修改。
## 创建工作区和会话 [#创建工作区和会话]
### 打开项目 [#打开项目]
在侧栏选择 **打开项目**，选中准备好的本地目录。项目会成为本次任务的文件和工具边界。
### 新建会话 [#新建会话]
在项目下选择 **新会话**，确认模型正确。首次试跑优先选择 **沙盒受限**；平台不可用或任务确实需要跨目录访问时，再评估完全访问。
### 引用关键文件 [#引用关键文件]
在输入区使用 `@` 引用 `README.md` 和 `package.json`。直接引用比只说“参考项目配置”更明确，也能减少无关文件读取。
## 提交可验收的任务 [#提交可验收的任务]
把目标、范围、约束和验证写在同一条消息中：
```text
阅读 @README.md 和 @package.json，为这个项目补充 docs/local-development.md。
要求：
1. 说明环境要求、安装、启动、快速检查和定向测试；
2. 命令必须来自当前仓库脚本，不要虚构；
3. 只修改目标文档，不修改 package.json 或源码；
4. 完成后实际运行无副作用的快速检查，并报告命令和结果；
5. 如果信息不足，先说明缺口，不要猜测。
```
这类任务足够小，便于检查 Agent 是否正确理解文件、遵守范围并执行验证。
## 执行时看什么 [#执行时看什么]
权限请求提供 **允许本次**、**本会话不再询问** 和 **拒绝**。第一次使用优先逐次允许；不确定时拒绝并在消息中补充边界。
## 验收真实结果 [#验收真实结果]
任务结束后，不只阅读最终回复：
### 打开目标文件 [#打开目标文件]
在活动面板的文件标签中打开 `docs/local-development.md`，确认内容可读且命令与项目脚本一致。
### 检查修改范围 [#检查修改范围]
查看项目文件或自己的版本控制状态，确认只有预期文档发生变化。
### 核对验证证据 [#核对验证证据]
展开对应命令工具卡片，确认命令确实执行、退出状态正常，而不是只在回复中声称“已通过”。
### 阅读风险说明 [#阅读风险说明]
确认最终回复列出未运行的检查、信息缺口或需要人工确认的事项。
## 结果不符合时继续 [#结果不符合时继续]
保持在原会话中，引用具体问题并缩小修正范围：
```text
开发命令准确，但测试章节把全量测试写成默认步骤。
只修改 docs/local-development.md：把默认流程改成定向测试，并保留全量测试作为发布前选项。
修改后重新核对 package.json，不需要运行源码测试。
```
同一目标的修正继续使用原会话。
要比较另一种完整方案时使用分叉。
开始无关目标时新建会话。
---
# 快速开始
> 安装 Astravia、完成首次引导、配置模型，并为第一个可验证任务准备工作区。
Canonical page: /getting-started
与当前系统匹配的桌面端
至少一个可用的默认模型
能打开项目并创建会话
完成本页后，你会得到一个有可用模型、能够创建项目的 Astravia 桌面工作区。带账户的构建还会完成登录；开源版没有账户，直接配置自己的模型即可。整个过程通常只需一次，之后可以从项目或「对话」开始任务。
如果你是升级现有安装、需要更换设备或从源码运行，请先阅读[安装、升级与数据迁移](/getting-started/installation-and-updates/)，再回到本页完成首次配置。
准备完成后，侧栏管理项目和能力，中间区域创建会话并提交任务。
## 准备工作 [#准备工作]
支持 Windows / macOS / Linux，以[官网下载区](https://astravia.dev/#download)实际发布包为准。
只有带 Astravia 账户的构建才需要浏览器 **授权登录**。开源版没有这一步。
组织提供的远程模型，或在「设置 → 模型配置」自行添加的服务商与密钥。
## 安装与首次启动 [#安装与首次启动]
### 下载并安装 [#下载并安装]
从 [Astravia 官网下载区](https://astravia.dev/#download)获取适合当前操作系统和处理器架构的安装包，完成安装后启动 Astravia。官网下载区没有列出的平台或架构表示当前没有可用制品，不要使用其他平台安装包替代。
### 完成首次引导 [#完成首次引导]
首次启动会进入引导流程，主要包括：
1. **语言与外观**：选择界面语言（跟随系统 / 中文 / English）和外观偏好。
2. **系统权限**（仅 macOS）：按提示完成应用所需权限。
3. **登录**（仅带账户的构建，且尚未登录时）：点击 **授权登录**，在浏览器完成 OAuth 后返回应用。开源版没有账户，引导里不会出现这一步。
4. **欢迎页**：引导结束进入主界面。
之后可在「设置 → 通用设置」中通过 **启动 App 引导** 重新打开该流程。
### 确认登录状态 [#确认登录状态]
带账户的构建里，侧栏账户区域应显示已登录。企业用户使用组织提供的登录方式；授权链接失效时，在登录弹层中重新授权。开源版没有账户区域，这一步可以跳过。
## 配置模型 [#配置模型]
打开 **设置 → 模型配置**（侧栏也可进入模型相关入口）：
在
**预设服务商**
中选择已支持的服务商（如 Claude、OpenAI、DeepSeek、Z.ai (GLM)、Kimi、Grok、Qwen、Gemini 等），填写 API Key。
使用
**从接口拉取**
获取模型列表并勾选添加，或手动
**添加模型**
。
将常用模型
**设为默认模型**
。
可选：调整全局
**思考**
档位（关闭 / 极低 / 低 / 中 / 高 / 极高）；模型不支持时会自动降级。
没有预设时，使用 **添加服务商** 配置自定义名称、API 类型、Base URL 与 API Key。
访问密钥只应填写在凭据配置界面。支持 `sk-...`、`env:MY_API_KEY` 等形式。不要把密钥写入提示词、项目文件或问题报告。配置落在本机 `~/.astravia/agent/models.json`。
## 主界面入口 [#主界面入口]
在工作目录中创建会话并执行任务
按计划单次或周期执行任务
导入并整理可长期检索的资料（界面可能带 BETA 标识）
技能、场景、MCP、插件、套装
同一提示处理多个文件夹
跳转到设置中的模型配置
跳转到 Agent 配置
跳转到外观设置
完整设置（Claw、知识库后台、应用环境、消息推送、Astravia Vivi 等）从侧栏 **设置** 进入。场景类型可在能力页管理；另有路由 `/scenes` 的场景专页，但不一定作为侧栏一级入口展示。
## 确认准备完成 [#确认准备完成]
账户区域显示已登录，或当前部署允许未登录使用。
「设置 → 模型配置」至少有一个模型，并已设为默认模型。
新建会话页能够选择该模型，没有显示凭证或连接错误。
需要处理本地文件时，已经创建或打开正确的项目目录。
已理解新会话的执行模式是「沙盒受限」还是「完全访问」。
如果模型测试失败，先处理配置问题，不要在任务中反复重试。参见[配置模型](/product/models/)和[故障排查](/troubleshooting/)。
---
# 安装、升级与数据迁移
> 选择正确的 Astravia 构建、完成升级，并安全迁移项目、会话和本地配置。
Canonical page: /getting-started/installation-and-updates
先确认下载包对应当前操作系统和处理器架构
升级前保留项目导出或版本控制基线
不要把会话正文、凭证和项目文件混成一份备份
## 选择安装来源 [#选择安装来源]
普通用户应从[官网下载区](https://astravia.dev/#download)获取与当前操作系统和架构匹配的安装包。仓库当前面向 Windows、macOS 和 Linux；官网下载区没有列出的平台或架构没有可替代的安装包。
Windows x64 提供三种格式：普通用户优先使用 Inno `.exe` 安装器，它接入应用内自动更新；需要标准 Windows Installer 部署时使用 `.msi`；不希望安装时可解压 `.zip` 后直接运行 `Astravia.exe`。MSI 和 ZIP 是补充下载格式，应用内自动更新仍通过 Inno 安装器完成。
Linux 当前发布 x64 架构的三种格式：AppImage 适合免安装运行，DEB 适合 Debian/Ubuntu，RPM 适合 Fedora/RHEL 系发行版。下载后可按格式安装：
```bash
VERSION=x.y.z # 替换为下载的版本号
# Debian / Ubuntu
sudo apt install "./astravia_${VERSION}_amd64.deb"
# Fedora / RHEL 系；当前直接下载的 RPM 尚未做 GPG 签名
sudo dnf install --nogpgcheck "./astravia-${VERSION}.x86_64.rpm"
# AppImage
chmod +x "./Astravia-${VERSION}.AppImage"
"./Astravia-${VERSION}.AppImage"
```
DEB/RPM 当前是通过 HTTPS 直接分发的安装包，不是 APT/DNF 软件源。安装后，应用更新器会继续选择与当前安装方式相同的包格式。
源码开发者从仓库运行桌面端时需要 Bun 1.3+ 和 Node.js 20+，并使用 `apps/desktop` 下的开发命令。开发环境默认使用独立数据目录，避免覆盖已安装版本的数据。
## 开源版与商业版 [#开源版与商业版]
桌面端的构建模式在打包时确定，不是安装后的运行时开关：
| 模式 | 登录与云服务 | 能力来源 | 共同能力 |
| ------------------- | ---------------- | ---------- | ---------------------- |
| 开源版 / serv-less | 不包含账户、订阅和远程模型目录 | GitHub 能力源 | 本地会话、BYOK、插件、主题、IM、知识库 |
| 商业版 / Astravia Serv | 可包含登录、组织、订阅和官方目录 | 官方服务端能力源 | 本地会话、BYOK、插件、主题、IM、知识库 |
不要把一个模式的服务端地址、Marketplace 配置或更新配置复制到另一个模式。构建模式和环境变量属于发布者配置；终端用户只需要按下载来源使用对应安装包。
## 升级前检查 [#升级前检查]
项目目录已有 Git 提交、压缩归档或其它可恢复副本。
没有仍在运行的任务、批量任务或知识库后台加工。
重要会话已经等待写入完成，未处于持续重试或等待权限状态。
如果使用 IM、Webhook 或自动化，已经记录当前开关、渠道和任务状态。
凭证由系统或 Astravia 配置存储保护，不把
`models.json`
、Token 或 Cookie 复制到备份说明中。
安装新版本通常会保留本地配置和数据目录。升级后若出现模型、插件或运行时异常，先在设置中重新验证对应能力，再查看[配置与数据路径](/reference/configuration-paths/)和[故障排查](/troubleshooting/)；不要先删除整个 `~/.astravia` 目录。
## 迁移哪些内容 [#迁移哪些内容]
| 内容 | 迁移建议 | 注意事项 |
| ---------------- | ------------------ | ------------------- |
| 项目文件 | 使用 Git、项目导出或文件系统备份 | 这是任务真实产物的首要副本 |
| 项目级 `.astravia/` | 与项目一起迁移 | 保留目录结构，确认其中没有凭证 |
| 普通会话 | 迁移对应会话目录及元数据 | 不要让两个进程同时写同一会话 |
| 模型、MCP 和其它设置 | 优先通过设置页重新配置 | 手工迁移前脱敏，并核对版本兼容性 |
| 凭证与 OAuth 状态 | 不复制到公开或跨设备文档 | 按目标设备重新登录或重新授权 |
| 知识库原始资料 | 备份原始文件 | 整理结果可重新生成，不等同于原始资料 |
| IM 绑定状态 | 按渠道重新绑定更安全 | QR 绑定和第三方会话有自己的生命周期 |
全局路径、项目路径和会话目录见[配置与数据路径](/reference/configuration-paths/)。路径是当前实现事实，不应被当成跨版本稳定协议；自动化集成请优先使用 SDK、RPC 或公开 CLI。
## 升级后的验收 [#升级后的验收]
1. 启动 Astravia，确认能打开一个已知项目。
2. 显式选择一个模型，发送最小测试消息。
3. 打开一个历史会话，确认消息和产物可读取。
4. 如果使用插件、MCP、知识库或自动化，逐项执行一次只读或测试操作。
5. 确认更新后的版本、权限和数据边界符合预期，再恢复无人值守任务。
删除整个用户数据目录会同时影响会话、配置、知识库、插件和渠道状态。先导出诊断信息、保留目录副本并确认具体故障对象，再执行定向清理。
---
# 插件能力参考
> 按目标查找 ctx 上的界面、对话、Agent、文件、网络、浏览器、模型、媒体与存储 API 及其权限边界。
Canonical page: /plugins/capabilities
插件 API 由 `@astravia-org/plugin-sdk` 提供，构建由 `@astravia-org/plugin-vite` 提供，脚手架与安装命令由 `@astravia-org/plugin-cli` 提供。插件代码运行在 Desktop renderer 进程的共享 JavaScript realm 内；权限声明用于知情同意和宿主 API 门控，不是 iframe、Worker 或恶意代码沙箱。
`activate(ctx)` 拿到的 `ctx` 是所有能力的唯一出口。宿主在主进程一侧并不认识「插件」这个概念，只认识一个带授权清单的能力会话，因此每一次调用都会被重新校验、约束到本插件的命名空间，并留下审计记录。
## 能力地图 [#能力地图]
| 目标 | 常用入口 | 权限 | 需要注意 |
| ------------ | ------------------------------------------------------------- | ----------------------------------------------------------- | -------------------------------------------------- |
| 上报错误与提示 | `ctx.ui.notify` | 无 | 任何可能失败的路径都应在 catch 里带上原始 error |
| 增加界面与页面 | `ctx.ui.register*` | 各槽位独立权限 | 注册返回的 `Disposable` 要在停用时释放 |
| 扩展文件浏览器 | `ctx.fileExplorer.*` | `ui.file-explorer.*`、`workspace.read` | 解析失败要返回可理解的错误状态 |
| 读对话与订阅事件 | `ctx.conversation.on` 及对话 hook | `agent.session.read` | 事件是宿主状态的只读视图 |
| 驾驶当前对话 | `ctx.conversation.sendPrompt`、`insertText`、`abort` | `agent.session.write` | 不要在用户没有触发的情况下自动发起提问 |
| 注册工具与 Hook | `ctx.agent.registerTool`、`registerHook` | `agent.tools.register` / `agent.hooks.register` 及对应 execute | 输入使用结构化 schema，执行错误要稳定返回 |
| 干预系统提示词与续跑 | `registerSystemPromptProvider`、`registerContinuationProvider` | `agent.systemPrompt.write`、`agent.continuation.register` | Provider 每个 Turn 开始时求值一次，本 Turn 内不会因插件状态变化重跑 |
| 执行宿主命令 | `ctx.command.run`、`ctx.command.spawn` | `agent.command.run` / `agent.command.spawn` | 清单必须声明 `commands`，不要把密钥放进参数 |
| 在终端里替用户跑命令 | 底部面板里的 `useBottomPanel().openTerminal` | `terminal.run` | 命令敲进用户自己的 shell、全程可见；cwd 只能在会话目录之内 |
| 离屏渲染截图 | `ctx.capture.offscreen` | `capture.offscreen` | 旧宿主上为 `undefined`，使用前判空 |
| 读写文件 | `ctx.fs.*` | `fs.read` / `fs.write` | 大文件先 `stat` 再决定读取方式 |
| 调用外部网络 | `ctx.network.request` | `network.fetch` | 清单声明最小 `network.allowedHosts` |
| 浏览器自动化 | `ctx.browser.*` | `browser.open` / `read` / `interact` 等 | 使用逻辑 profile；不获得 Cookie、Token 或任意 JS 执行权 |
| 插件私有持久化 | `ctx.storage.*` | `storage.read` / `storage.write` | 按插件 id 隔离；多文件一致性用一次 `commit()` 而不是连续 `writeFile()` |
| 保存密钥 | `ctx.secrets.*` | `secrets.read` / `secrets.write` | 宿主加密凭据库，不要把 Key 写进普通存储 |
| 调用用户已配置模型 | `ctx.ai.listModels`、`complete`、`stream`、`chat` | `ai.models.list` / `ai.complete` | 使用用户配置的凭据，不自行保存 Key |
| 维护自有模型服务商 | `ctx.models.replaceOwnedProviders`、`listOwnedProviders` | `models.manage` | 写入是原子快照，省略即删除；先读回对账，读到的 apiKey 是掩码 |
| 生成与注册媒体能力 | `ctx.media.submit`、`registerProvider` | `media.generate` / `media.provider.register` | 长任务通过 `ctx.jobs` 观察进度与取消 |
| 识别与注册 OCR 能力 | `ctx.ocr.recognize`、`registerProvider` | `ai.ocr.recognize` / `ai.ocr.provider.register` | 消费与提供是两个独立权限 |
| 管理 CLI 与本地服务 | `ctx.cliProviders.*`、`ctx.services.*` | 由清单 `providers` 声明 | 宿主负责探测、安装、启停与健康检查 |
| 注册可发现动作 | `ctx.appActions.register` | `app.actions.register` + `app.actionHandler.execute` | 高影响文件和网络操作仍需确认 |
| 提供技能或 MCP | `plugin.json` 的 `agent` 字段 | `agent.skills.control` / `agent.mcp.control` | 安装、启用和重载都要重新验证来源与权限 |
| 贡献智能体与团队 | `plugin.json` 的 `agent.agents`、`agent.teams` | 无 | 宿主铺成普通档案；成员可跨插件引用，队长必须是本插件自己的 |
| 在新会话页摆素材 | `ctx.ui.registerNewSessionContext` | `ui.slot.new-session-context` | 激活条件只能写本插件自己的智能体或能力，拿不到用户逐键输入 |
| 提供多语言文案 | `ctx.i18n` 与包内 `locales/` | 无 | 文案 key 和 `defaultLocale` 要与清单一致 |
`ctx.capture` 在不支持离屏截图的旧宿主上是 `undefined`；`ctx.gateway` 只对内置官方插件可用，第三方插件一律读到 `undefined`。使用前先判空，不要假设它们存在。
## 网络请求的实际边界 [#网络请求的实际边界]
`ctx.network.request` 由主进程代理，除了主机白名单还有一组固定约束：默认超时 120 秒、上限 300 秒，请求体与响应体各自上限 32 MB，最多 5 次重定向，只允许 http 与 https。
重定向逐跳重新校验白名单，非 GET 与 HEAD 的重定向直接拒绝，跨源跳转时会剥掉 `authorization` 和 `cookie` 头。失败原因是枚举值而不是笼统的网络错误，可以据此区分是主机未声明、超出体积、超时还是传输失败。
## 选择 API 的原则 [#选择-api-的原则]
* 只增加 Agent 方法时，优先技能或插件的 Agent 贡献，不要先创建复杂界面。
* 只连接外部服务时，优先独立 MCP；插件内聚 MCP 适合与插件生命周期强绑定的服务。
* 只需要颜色、表面和组件替换时，使用主题系统。
* 需要完整页面、文件预览、消息卡片或宿主动作时，才使用插件。
* 需要给宿主补一类能力（模型服务商、媒体生成、OCR、本地服务）时，用对应的 Provider 扩展点而不是自己在界面里另起一套。
## 权限与生命周期 [#权限与生命周期]
一个完整的插件能力需要同时通过三层：清单声明意图和最小权限，安装时由用户确认，宿主在运行时再次校验并在插件重载或停用时清理注册项。
`activate()` 可以返回一个清理函数或 `Disposable`，把资源所有权绑定到这一次激活上。热更新时新旧激活会短暂共存，各自的清理互不干扰，所以有状态资源优先用这种写法，而不是模块级的 `deactivate()`。
系统内置插件与外置插件的授权策略不同：系统插件随应用发布并自动全量授权，外置插件仍应按不可信代码审查。详见[清单与权限](/plugins/manifest-and-permissions/)。
## 发布前验收 [#发布前验收]
全新安装时清单字段、入口、样式和构建产物路径一致。
权限提示只包含完成任务所需的权限。
停用、重载和再次启用不会重复注册界面、工具或事件监听。
撤销任一可选权限后，插件其余能力仍然可用。
无权限、外部网络失败、文件解析失败和模型失败都能显示可恢复的错误。
发布 ZIP 与开发链接都经过验证；开发链接成功不能代替 ZIP 安装测试。
共享 renderer realm 意味着插件来源本身就是安全边界。只安装可信来源，审查构建产物和更新内容，并授予最小权限。
---
# 选择插件扩展点
> 按产品目标选择界面、文件、Agent、Provider 或 App Action 扩展点，并对齐每项所需权限。
Canonical page: /plugins/extension-points
先选择最接近用户任务的扩展点，再在 `activate(ctx)` 中注册。一个插件可以组合多个扩展点，但每项都应有明确用途和独立权限。
清单声明面（技能、MCP、智能体、引导词）在插件安装时就生效，不依赖 `activate()` 执行；运行时注册面需要插件被启用并加载。
`plugin.json` 的 `contributes.settings` 与只读的 `ctx.settings` 已在 Plugin API 1.6.0 移除。配置界面由插件自己渲染：完整配置页用 `ctx.ui.registerWorkspaceView`，一两个开关直接放进已有的活动 Tab 或全局槽；普通配置值存 `ctx.storage`，API Key 等密钥存 `ctx.secrets`。
## 界面扩展点 [#界面扩展点]
`ctx.ui` 提供的注册面，每项对应一个独立权限：
| 扩展点 | API | 权限 |
| ----------------- | -------------------------------------------------------------------------------------------- | ----------------------------- |
| 全局通知 Toast | `ctx.ui.notify` | 无需权限 |
| 全局浮层 | `registerGlobalSlot` | `ui.slot.global` |
| 工作区视图（整页 + 侧边栏入口） | `registerWorkspaceView`、`openWorkspaceView`、`setWorkspaceViewBadge`、`setWorkspaceViewHeader` | `ui.slot.workspace-view` |
| 文件预览 | `registerFilePreview` | `ui.slot.file-preview` |
| 活动面板 Tab | `registerActivityTab`、`openActivityTab`、`setActivityTabVisible` | `ui.slot.activity-tab` |
| 输入栏动作与附件 | `registerInputAction`、`setPromptAttachment` | `ui.slot.input-action` |
| 新会话上下文区 | `registerNewSessionContext` | `ui.slot.new-session-context` |
| 消息卡片渲染器 | `registerCardRenderer` | `ui.slot.message` |
| 工具调用行内渲染 | `registerToolCallSlot` | `ui.slot.tool-call` |
| 本轮 Turn 卡 | `registerTurnCard` | `ui.slot.turn-card` |
| 能力详情页运行时区块 | `registerAbilityDetailSlot` | `ui.slot.ability-detail` |
| 键盘快捷键 scope | `registerShortcutScope`、`usePluginShortcutScope` | `ui.shortcuts.register` |
| 打开系统默认浏览器 | `openExternal` | `shell.openExternal` |
组件使用宿主共享的 React 与设计令牌。注册函数返回 `Disposable`，在停用阶段释放，避免重载后重复注册。
插件与宿主共享同一个页面。在样式入口里写 `button`、`div`、`*` 这类元素选择器会污染整个界面，而且是只在用户机器上复现的那种污染。`@astravia-org/plugin-vite` 会自动把插件 CSS 限定到插件根节点并接入宿主主题令牌，`text-foreground`、`bg-card` 这类语义类直接可用。
面板类槽位（文件预览、活动 Tab、工作区视图）禁止使用铺满视口的固定定位浮层，它们会盖住宿主自己的界面。
## 文件浏览器扩展点 [#文件浏览器扩展点]
`ctx.fileExplorer` 单独成组，读取工作区结构与写入界面装饰是两类权限：
| 扩展点 | API | 权限 |
| --------------------------- | ----------------------------------------------------------------------------------------------- | ------------------------------- |
| 右键菜单动作 | `registerContextMenuAction` | `ui.file-explorer.context-menu` |
| 工具栏动作 | `registerToolbarAction` | `ui.file-explorer.toolbar` |
| 文件状态装饰（角标、语义色、淡化、删除线、父目录聚合） | `registerDecorationProvider` | `ui.file-explorer.decorations` |
| 文件图标主题（文件名、扩展名、文件夹与明暗模式） | `registerIconTheme` | `ui.file-explorer.decorations` |
| 读取根目录、选择、定位与刷新 | `getWorkspaceRoots`、`getSelection`、`reveal`、`refresh`、`onDidChangeSelection`、`onDidChangeFiles` | `workspace.read` |
文件解析和界面渲染应分离，解析失败时返回可理解的错误状态，不要让单个文件使整个会话视图崩溃。
动态状态通过 `onDidChangeDecorations` 精确失效，不需要刷新文件系统。图标主题由用户在文件列表里选择；插件只能使用宿主语义色和声明式图标关联，不能改文件行的任意 CSS、布局或排序。新装饰能力要求 Plugin API `^2.7.0`。
## Agent 扩展点 [#agent-扩展点]
运行时注册面（`ctx.agent`）：
| 扩展点 | API | 权限 |
| ------------------------- | ------------------------------------- | ---------------------------------------------------------------------------- |
| 注册 Agent 工具 | `registerTool` | `agent.tools.register` + `agent.toolHandler.execute` |
| 注册 Coding Agent 生命周期 Hook | `registerHook` | `agent.hooks.register` + `agent.hookHandler.execute` |
| 动态系统提示词 Provider | `registerSystemPromptProvider` | `agent.systemPrompt.write`；操作非本插件的 block 另需 `agent.systemPrompt.fullControl` |
| 自动续跑策略 | `registerContinuationProvider` | `agent.continuation.register` |
| 动态开关工具 | Provider 的 `actions.tools.setEnabled` | `agent.tools.control` |
清单声明面（`plugin.json`）：
| 扩展点 | 字段 | 权限 |
| --------------- | -------------------------------- | -------------------------- |
| 打包技能 | `agent.skillPaths` | `agent.skills.control` |
| 追加系统提示词文件 | `agent.systemPrompt.promptPaths` | `agent.systemPrompt.write` |
| 工具策略 | `agent.toolPolicy` | `agent.tools.control` |
| 插件内聚 MCP Server | `agent.mcpServers` | `agent.mcp.control` |
| 贡献智能体与团队 | `agent.agents`、`agent.teams` | 无需权限 |
| 新会话引导词 | `guidingWords` | 无需权限 |
工具输入使用结构化 schema，并把外部 I/O 错误映射为稳定结果。需要宿主文件、网络或模型能力时，先在清单中声明最小权限。
### 插件内聚 MCP 是第三配置源 [#插件内聚-mcp-是第三配置源]
会话的 MCP 工具面来自三源合并，互相并列而不是覆盖：用户全局 `mcp.json`、项目侧配置、以及插件清单贡献。插件源不回写用户文件，禁用或卸载插件只撤掉自己那部分。插件 Server 的运行时名统一为 `plugin-<插件 id>-<本地 key>`，与另外两源同时存在也不会撞名。
设置页的 MCP 编辑器只读写用户文件，不会列出也无法编辑插件内聚的 Server。
### 智能体与团队 [#智能体与团队]
插件在清单里贡献的智能体与团队会被铺成普通档案，与用户自己创建的并列。人设、头像和提示词由插件维护：停用插件时档案灰着留在原地，重新启用即恢复。
团队有两条硬约束：队长必须是本插件自己的智能体（否则被引用的插件一卸载，这支团队就成了打不开的壳），队长的任务书写在团队的 `workflow` 而不是成员条目上（两处都写就无法确定哪份生效）。其余成员可以用 `<插件 id>/<智能体 id>` 引用别的插件的智能体。
选中这类智能体后还可以用新会话上下文区在输入框下方摆出接下来要用的素材，激活条件只能写本插件自己的东西。
## Provider 扩展点 [#provider-扩展点]
插件不只消费宿主能力，也可以反过来给宿主提供能力：
## App Action [#app-action]
App Action 让插件通过宿主动作系统暴露可发现命令，适合导航、打开面板或执行确定性操作。注册需要 `app.actions.register`，handler 被调用时需要 `app.actionHandler.execute`。
不要用 App Action 绕过用户确认去执行高风险文件或网络操作。
## 缺权限时会发生什么 [#缺权限时会发生什么]
不同注册点对「声明了但未授权」的处理不同，这个差异会直接影响你怎么组织 `activate()`：
| 行为 | 涉及的注册点 |
| ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 抛出 `Plugin permission denied` 并中断调用 | `registerInputAction`、`registerCardRenderer`、`registerToolCallSlot`、`registerTurnCard`、`registerShortcutScope`、`openActivityTab`、`setActivityTabVisible`、`setPromptAttachment`、`fileExplorer.*`、`registerSystemPromptProvider`、`registerContinuationProvider`、`conversation.*`、`fs.*`、`network.*`、`storage.*`、`media.*`、`ai.*`、`command.run` |
| 跳过该贡献并打印警告，不影响其它能力 | `registerGlobalSlot`、`registerFilePreview`、`registerActivityTab`、`registerNewSessionContext`、`agent.registerTool`、`agent.registerHook`、`appActions.register` |
一个缺失权限不应拖垮插件的其它能力。在 `activate()` 里让各项注册互相独立，避免一处抛错中断整段初始化。运行时也可以用 `ctx.permissions.has()` 自查后再决定是否注册。
界面槽位的权限缺失不会在构建期暴露，装上去只是静默不显示，需要对照上表核对。
## 相关文档 [#相关文档]
---
# 创建第一个插件
> 创建、构建并安装一个最小 Astravia 桌面插件。
Canonical page: /plugins/getting-started
## 前置条件 [#前置条件]
* Node 或 Bun。
* 用于安装和调试插件的 Astravia 桌面客户端（安装与热更新都要求它正在运行）。
**不需要** Astravia 的源码仓库。
## 一条命令起工程 [#一条命令起工程]
```bash
npx @astravia-org/plugin-cli init --id my-plugin --name "My Plugin"
cd my-plugin && npm install
```
脚手架会落下 `plugin.json`、Vite + Module Federation 配置、Tailwind 入口，以及一份 `AGENTS.md`。
开发手册随 `@astravia-org/plugin-sdk` 装进 `node_modules`，**不要硬编码那个路径**——工作区可能
把依赖提升到仓库根，一仓多插件时各插件还可能钉不同的 SDK 版本。用命令解析：
```bash
npx astravia-plugin-cli docs
```
它打印手册目录的绝对路径与对应的 SDK 版本。因为手册与 SDK 同版本发布，Agent 读到的合同
**就是这个工程即将编译的合同**——从网络现取最新文档做不到这一点。
## 开发闭环 [#开发闭环]
```bash
npm run dev # Vite + Module Federation 开发服务器
npm run validate # 校验清单与构建产物
npm run install:astravia # 构建、打包并装进正在运行的 Astravia
npx astravia-plugin-cli watch # 热更新：宿主改从本工程目录加载，改完即生效
npx astravia-plugin-cli reload # 提示有 pending 版本时切换过去
npx astravia-plugin-cli uninstall # 卸载
```
`install:astravia` 把归档交给正在运行的桌面端校验、授权、安装，**不会**直接写 `~/.astravia/plugins`。
安装一个更新版本只被记录为 pending，应用继续加载当前活动版本，直到 `reload` 才切换。改了代码却看不到变化时，先确认 `plugin.json` 的 `version` 已经提升。
## 项目结构 [#项目结构]
## 配置构建 [#配置构建]
通过 `@astravia-org/plugin-vite` 配置 Module Federation：
```ts
import tailwindcss from "@tailwindcss/vite";
import { astraviaPluginFederation } from "@astravia-org/plugin-vite";
import { defineConfig } from "vite";
export default defineConfig({
plugins: [
tailwindcss(),
astraviaPluginFederation({
name: "my_plugin",
entry: "./src/index.tsx",
expose: "./plugin",
}),
],
esbuild: { jsx: "automatic", jsxImportSource: "react" },
});
```
## 创建入口 [#创建入口]
```tsx
import { definePlugin } from "@astravia-org/plugin-sdk";
function MyPanel() {
return 插件已加载
;
}
export default definePlugin({
activate(ctx) {
ctx.ui.registerGlobalSlot({ id: "root", component: MyPanel });
},
});
```
Module Federation 的共享 React 依赖在 bootstrap 后才可用。把 JSX 放在组件或 `activate()` 调用后的执行路径中。
## 构建与加载 [#构建与加载]
按开发调试与正式发布选择路径：
使用 `bunx astravia-plugin dev` 启动插件开发服务，再通过 Astravia 的开发链接加载。改动后可快速验证界面与工具注册，但发布前仍要执行生产构建并测试 ZIP 安装流程。
### 生产构建 [#生产构建]
运行 `bunx vite build`，生成 `dist/mf-manifest.json`、`remoteEntry.js` 和样式文件。
### 打包归档 [#打包归档]
发布包使用 `.astraviapkg` 扩展名和 ZIP 容器，并在归档根目录包含 `plugin.json` 和 `dist/`。安装了 Astravia 后可以双击该文件安装。
### 安装并启用 [#安装并启用]
在侧栏 **能力** 页打开 **添加能力 → 导入插件压缩包**，选择 ZIP；安装后在 **启用与权限** 对话框中启用并授权。
### 验证加载 [#验证加载]
打开插件注册的界面或触发其工具，确认产物确实被宿主加载。
## 发布多个能力：能力市场仓库 [#发布多个能力能力市场仓库]
一个仓库要上架多个能力（插件、MCP、Skill、场景）时，用市场骨架：
```bash
npx @astravia-org/plugin-cli init hub --name my-market \
--repository https://github.com/me/my-market --min-app-version 0.55.0
```
它生成 `.astravia/marketplace.json` 索引、`abilities/` 目录约定、一份仓库级 `AGENTS.md`，以及跑
`sync --check` 的 CI。之后在 `abilities/plugins/` 里照常 `init` 即可——**开发命令一律作用于
最近的那个能力目录**，所以在市场仓库里开发与开发单插件完全一样。
索引里的 `version`、`config.api_version`、`config.permissions` 都是从能力包推导的派生字段，
由工具对账：
```bash
npx @astravia-org/plugin-cli sync # 回填派生字段，并推进 marketplaceVersion
npx @astravia-org/plugin-cli sync --check # 只报不写，非零退出（CI 用）
```
索引条目的 `version` 与能力包不等时，宿主同步**直接失败**；`plugin.json` 的 `entry` / `styles`
不在已发布目录里时，本地能装、市场上装不了（客户端不会替你构建，所以那些目录要提交 `dist/`）；
改了内容却没换 `marketplaceVersion` 时，客户端既不报错也不更新——用户只是永远收不到。
`sync --check` 三条都会守住。
## 下一步 [#下一步]
---
# 日志
> 输出自动带插件身份、由桌面宿主持久化的结构化日志。
Canonical page: /plugins/logging
插件可以直接从 SDK 导入已经绑定身份的 `logger`，不需要从 `PluginContext` 逐层传递：
```ts
import { logger } from "@astravia-org/plugin-sdk/logger";
logger.info("Proxy configuration loaded", { provider: "codex" });
const syncLogger = logger.child("sync");
syncLogger.warn("Remote catalog is unavailable", { retryInMs: 5_000 });
```
`@astravia-org/plugin-vite` 会在开发和生产构建中读取经过校验的 `plugin.json`，把这个入口绑定到
当前插件的 `id` 和 `version`。桌面宿主接收日志后统一添加插件标识、限制字段大小、脱敏常见
敏感字段，并写入 Renderer 日志文件。Windows 默认位置是
`%USERPROFILE%\.astravia\desktop-app\logs\render\YYYY-MM-DD.log`。
支持 `debug`、`info`、`warn` 和 `error` 四个级别。第二个参数应当是便于检索的结构化字段；
不要记录 Token、Cookie、密码、完整请求头或用户内容。宿主脱敏只是最后一道防线，不能代替插件
在源头避免输出敏感数据。
这一入口要求 `@astravia-org/plugin-sdk >= 0.3.7`、`@astravia-org/plugin-vite >= 0.2.3`，并在
`plugin.json` 中声明 `pluginApiVersion: "^2.5.0"`。旧插件无需迁移，仍可照常加载。
`logger` 用于诊断日志，不会向用户显示通知。需要用户采取行动时，继续使用
`ctx.notify.info()`、`ctx.notify.warning()` 或 `ctx.notify.error()`。
由插件启动的托管服务进程，其 stdout/stderr 属于宿主的服务生命周期日志，不会自动经过这个
JavaScript `logger`。
---
# 清单与权限
> 声明插件身份、加载入口、样式、权限、命令、网络范围和 Agent 贡献，并理解授权与校验流程。
Canonical page: /plugins/manifest-and-permissions
`plugin.json` 位于 `.astraviapkg` 插件包的 ZIP 容器根目录（或归档内唯一的顶层文件夹里）。宿主在加载代码前用它校验身份、兼容性和权限，因此清单必须与构建产物一致。
清单结构的唯一实现是 `@astravia-org/plugin-sdk/manifest` 导出的 TypeBox Schema：`PluginManifestSchema` 可直接序列化为 JSON Schema，`parsePluginManifest()` 负责校验、默认值、去重、相对路径归一化和跨字段约束。Schema 有意允许未知字段，这样更高版本清单不会被旧宿主直接拒绝。
```json
{
"id": "my-plugin",
"name": "My Plugin",
"version": "0.1.0",
"pluginApiVersion": "^2.0.0",
"entry": "dist/mf-manifest.json",
"moduleFederation": {
"remoteName": "my_plugin",
"expose": "./plugin"
},
"styles": ["dist/style.css"],
"permissions": ["ui.slot.activity-tab", "agent.command.run", "network.fetch"],
"commands": ["git"],
"network": { "allowedHosts": ["api.example.com", "*.cdn.example.com"] },
"defaultLocale": "zh"
}
```
## 字段 [#字段]
清单不提供加载模式选择字段。写了 `runtime` 字段会被校验器直接拒绝，避免清单看起来像在选一条宿主并不存在的加载路径。`agent_mode` 字段已废弃且没有任何运行时语义，新插件不要写。
## 路径与主机名会被归一化 [#路径与主机名会被归一化]
所有清单路径都会过越界校验：拒绝绝对路径与盘符前缀，展开 `.` 与 `..`，向上越过插件根直接报错。安装时还会再查一遍，声明的资源必须真实存在、类型正确且位于包根之内。
`network.allowedHosts` 与 `browser.allowedHosts` 的每一项也会归一化：`*` 表示全通配，`*.example.com` 是前缀通配，带端口、用户名或密码的写法一律拒绝。通配项不匹配裸域名本身，`*.example.com` 不覆盖 `example.com`。
## 安装目录与版本 [#安装目录与版本]
用户插件按版本存放在 `~/.astravia/plugins//versions//`。安装一个更新版本只被记录为 pending，应用继续加载当前活动版本，直到触发 reload 才切换。调试时改了代码要提升 `version` 并 reload 才稳妥生效。
系统插件不进这个目录，随应用发布、每次启动从只读目录重新发现，声明的权限自动全量授予且用户不可撤销。
## 声明、授权与校验 [#声明授权与校验]
### 在清单中声明 [#在清单中声明]
在 `plugin.json` 的 `permissions` 数组列出权限。没声明的权限永远拿不到。
### 安装时授权 [#安装时授权]
用户在插件页逐项勾选授权。Agent 通过本地路径安装时，用户确认后可按声明一次性授予。
### 运行时校验 [#运行时校验]
宿主在调用对应 API 时再次校验，声明与授权必须同时成立。运行时也可以用 `ctx.permissions.has()` 自查、`require()` 主动抛错。
更新插件时，宿主保留用户已授予且新版本仍声明的权限，不自动授予新增权限，也不恢复用户主动撤销的权限——从一份空的授权记录无法反推用户原来的选择。
## 权限清单 [#权限清单]
`ui.slot.global`、`ui.slot.workspace-view`、`ui.slot.file-preview`、`ui.slot.activity-tab`、`ui.slot.bottom-panel`、`ui.slot.input-action`、`ui.slot.new-session-context`、`ui.slot.message`、`ui.slot.tool-call`、`ui.slot.turn-card`、`ui.slot.ability-detail`、`ui.shortcuts.register`、`ui.file-explorer.decorations`、`ui.file-explorer.context-menu`、`ui.file-explorer.toolbar`、`workspace.read`、`conversation.draft.read`、`shell.openExternal`
`agent.session.read`、`agent.session.write`、`agent.command.run`、`agent.command.spawn`、`terminal.run`、`capture.offscreen`
`agent.tools.register`、`agent.toolHandler.execute`、`agent.hooks.register`、`agent.hookHandler.execute`、`agent.tools.control`、`agent.skills.control`、`agent.mcp.control`、`agent.systemPrompt.write`、`agent.systemPrompt.fullControl`、`agent.continuation.register`
`browser.open`、`browser.read`、`browser.interact`、`browser.profile.persist`、`browser.attach`、`browser.runtime.manage`。`browser.interact` 必须与 `browser.read` 一起声明，`browser.open` 只打开内置浏览器面板、不读取也不操作页面。
`ai.models.list`、`ai.complete`、`models.manage`、`media.generate`、`media.provider.register`、`ai.ocr.recognize`、`ai.ocr.provider.register`
`fs.read`、`fs.write`、`network.fetch`、`storage.read`、`storage.write`、`secrets.read`、`secrets.write`
`app.actions.register`、`app.actionHandler.execute`
`agent.systemPrompt.read`、`agent.state.read`、`agent.state.write`、`agent.runtime.configure`、`settings.read`、`settings.write`。声明它们不会解锁任何功能。
清单里的 `agent.agents`、`agent.teams`、`guidingWords`，以及 `ctx.ui.notify` 和 `ctx.i18n` 都不需要权限。
## commands 是命令执行的第二道闸 [#commands-是命令执行的第二道闸]
`ctx.command.run` 要跑一个二进制，需要 `agent.command.run` 权限**并且**该可执行文件名在清单 `commands` 里。未列入的二进制被硬拒绝；已声明的可以由用户在插件设置里逐条开关，关闭后调用被拦截。
宿主不经用户可控的 shell 启动进程，`node`、`npm`、`npx` 会被重定向到宿主托管的运行时。
## 最小权限原则 [#最小权限原则]
只声明插件实际使用的权限，声明越小用户授权越省心、审核越快。开发时先从最小清单开始，调用宿主 API 报权限错误时确认该行为确实必要，再增加对应权限并重新走安装授权。不要为了省事复制其他插件的完整权限数组。
`@astravia-org/plugin-vite` 在构建和打包时扫描最终 JavaScript 产物，检出 `registerTool`、`registerHook`、`registerSystemPromptProvider`、`registerContinuationProvider`、运行时工具开关等调用点，以及清单里的 `agent.toolPolicy`，缺少对应权限会直接终止构建。界面槽位不在这条校验里，缺权限只在运行时静默跳过，需要对照[扩展点](/plugins/extension-points/)核对。
## 发布前检查 [#发布前检查]
### 检查归档结构 [#检查归档结构]
解压最终 `.astraviapkg`，确认 `plugin.json` 在 ZIP 容器根目录或唯一的顶层文件夹里，清单引用的入口、样式、技能和提示词文件都存在。
### 验证权限提示 [#验证权限提示]
使用全新安装流程验证权限提示是否与清单声明一致，确认没有多余权限。
### 逐项触发能力 [#逐项触发能力]
再逐项触发插件能力，包括撤销某项权限后的降级表现。本地开发链接成功不能替代发布包验证。
---
# 插件开发概览
> 理解 Astravia 插件的运行方式、能力出口和信任边界。
Canonical page: /plugins/overview
插件跑在桌面渲染进程里，不是沙箱 iframe
权限要经过声明、安装授权和运行时校验
先确认它真的需要做成插件
Astravia 插件用于扩展桌面客户端的界面、文件浏览器、对话和 Agent 能力。插件通过 `@astravia-org/plugin-sdk` 获取宿主提供的策展能力出口。
插件可以把领域工具和可交互产物放进 Astravia 工作区，但必须经过清单声明和宿主授权。
## 运行模型 [#运行模型]
插件使用 React、TypeScript 和 Vite 开发。
生产产物通过 Module Federation 加载，清单不提供其它加载方式。
React、React DOM 和插件 SDK 由宿主以共享单例提供，可选再共享宿主设计系统组件。
插件在桌面渲染进程内运行，不是 iframe 或 Worker 沙箱。
需要文件、网络、命令或模型时，调用经由主进程的能力总线，逐次校验授权并约束到本插件命名空间。
## 信任与权限 [#信任与权限]
插件面向官方或合作方策展的扩展，不应被视为可直接运行的任意不可信代码。需要权限的能力必须同时满足：
### 在清单中声明 [#在清单中声明]
在 `plugin.json` 中声明权限。
### 安装时授权 [#安装时授权]
用户或管理员在安装流程中确认授权。
### 运行时校验 [#运行时校验]
宿主在调用对应 API 时再次校验权限。
## 先选正确的扩展形态 [#先选正确的扩展形态]
并非所有扩展都需要做成插件：
给 Agent 增加一组指令与工作流时优先使用技能。
只连接外部工具或数据源时优先使用 MCP。
需要桌面 UI、宿主 API 或完整生命周期时再创建插件。
需要一致的外观、组件替换或主题页面时使用主题系统。
## 可扩展范围 [#可扩展范围]
插件的扩展面分成四类：
十余个界面槽位，涵盖全局浮层、工作区整页视图、文件预览、活动面板 Tab、输入栏动作、新会话上下文区、消息卡片、工具调用行内渲染、Turn 卡、快捷键，以及文件浏览器的右键菜单、工具栏与装饰。
注册工具与生命周期 Hook、干预系统提示词、决定是否自动续跑；清单侧还可以贡献技能、内聚 MCP Server、工具策略、智能体与团队。
反过来给宿主补齐能力：模型服务商、媒体生成、OCR、CLI Provider 和受管本地服务。
在获得授权后访问文件、网络、浏览器自动化、插件私有存储、加密密钥、离屏截图，以及用户已配置的 AI 模型。
宿主已不再提供设置页配置槽，插件的配置界面由插件自己渲染、自己持久化。
---
# 使用能力
> 在「能力」页安装并管理技能、场景、MCP、插件与套装。
Canonical page: /product/abilities
侧栏 **能力**（路由 `/abilities`）是扩展入口。页面副标题含义：给 agent 加点本事——**技能、场景、MCP、插件与能力套装**。
「发现」用于寻找能力，「我的」用于检查已安装项、配置、权限和更新。
## 能力类型 [#能力类型]
| 类型 | 作用 |
| --- | ---------------------------------------- |
| 技能 | 任务指令与工作流提示 |
| 场景 | 预设工作方式；能力页可管理，另有独立路由 `/scenes`（不一定出现在侧栏） |
| MCP | 连接外部工具与数据源 |
| 插件 | 扩展桌面 UI 与 Agent 能力 |
| 套装 | 一次组织多项能力，安装时可勾选成员 |
## 从目标选择能力类型 [#从目标选择能力类型]
| 你的目标 | 优先选择 | 原因 |
| -------------- | ---- | --------------------- |
| 让 Agent 遵循稳定方法 | 技能 | 以指令和流程指导一次任务 |
| 预设一套工作方式和上下文 | 场景 | 适合重复进入同类工作状态 |
| 调用外部服务或数据 | MCP | 提供结构化工具连接 |
| 扩展桌面界面、文件或消息 | 插件 | 能进入宿主 UI 和 Agent 生命周期 |
| 一次安装一组协同能力 | 套装 | 统一发现和选择成员 |
如果只是需要外部 API，不要先写桌面插件；如果只是需要稳定提示流程，也不必引入 MCP 服务。
## 发现与我的 [#发现与我的]
* **发现**：浏览可添加的能力（含推荐连接器等分组）。
* **我的**：管理已安装项：启用、停用、配置、更新、移除。
可搜索能力名称；卡片展示来源、版本、状态（如需配置、可更新、已启用）。
## 从市场或列表添加 [#从市场或列表添加]
### 打开详情 [#打开详情]
在发现列表点击能力，右侧抽屉显示说明、来源、版本与权限等信息。
### 添加 [#添加]
选择 **添加能力**。套装会弹出成员勾选（已安装且无需更新的成员不会重复安装）。
### 完成配置 [#完成配置]
* MCP 可能要求填写凭证、或浏览器账户授权。
* 插件安装后弹出 **启用与权限**：确认启用并逐项授权后才会生效。
### 在会话中验证 [#在会话中验证]
回到会话，确认技能 / 工具 / 插件入口按预期出现。
## 添加能力菜单 [#添加能力菜单]
点击 **添加能力** 可选择：
| 方式 | 说明 |
| -------- | -------------------------------------------------------------- |
| 导入技能压缩包 | 本地 zip / tar.gz / tgz |
| 导入插件压缩包 | 本地 zip，根目录需含 `plugin.json` |
| 添加外置仓库 | GitHub `owner/repo`，仓库需包含 `.astravia/marketplace.json`，添加后立即同步 |
| 手动添加 MCP | 配置 STDIO 或 HTTP MCP 服务 |
只导入可信来源。外置仓库同步失败时，应用可能保留上次可用内容并提示错误。
Astravia 官方来源（`maomaochong-ai/astravia-official-marketplace`）作为内置来源随应用提供，始终启用，不能停用或删除；自行添加的外置仓库可以随时停用或删除。
## 管理与排错 [#管理与排错]
* **停用**：保留安装，暂停使用。
* **移除**：卸载本地安装内容。
* **更新 / 重载**：有新版本或开发调试时使用。
* 同一能力标识已被其它来源占用时，不会自动覆盖，需在详情中确认来源。
* MCP 产物写入 `~/.astravia/agent/mcp.json`；技能 / 场景 / 插件分别落在 `~/.astravia/skills`、`~/.astravia/scene`、`~/.astravia/plugins` 等目录；安装索引见 `~/.astravia/abilities.json`。
需要开发插件时阅读 [插件开发](/plugins/overview/)；只连接工具服务时阅读 [MCP 连接器](/product/mcp/)。
---
# 使用智能体团队
> 用一支有负责人、有分工的常驻智能体团队完成一次任务，并理解它背后的委派与共享机制。
Canonical page: /product/agent-teams
团队是一组常驻成员，不是一次性的临时助手
你只对负责人说话，分工由它来安排
成员之间共享结果，不共享彼此的执行过程
一次普通会话里只有一个 Agent：它自己规划、自己动手、自己检查。任务一旦需要「先设计、再实现、最后有人挑刺」，同一个 Agent 既当作者又当审稿人，往往看不出自己的问题。
**智能体团队**把这件事拆给多个成员：每个成员是一个独立的 Agent，有自己的职责、自己的能力开关和自己的私有会话；其中一位是**负责人**，它是你唯一的对话入口，负责拆解目标、把每一步派给合适的成员、验收结果，并对最终交付负责。
## 团队和子代理不是一回事 [#团队和子代理不是一回事]
Astravia 里有两种「多 Agent」，容易混淆，但边界很清楚：
| | 团队成员 | 子代理（Subagent） |
| ---- | ------------------- | -------------------------- |
| 生命周期 | 常驻。跨回合、跨会话存在，有自己的历史 | 临时。由某个 Agent 在一次任务里创建，用完即弃 |
| 可见性 | 出现在团队名册里，你能点开它的独立会话 | 是发起者的私有助手，不进入团队名册 |
| 归属 | 可以持有团队任务，并以成员身份公开发言 | 不能持有团队任务，也不能作为成员发言 |
| 工具 | 团队协作工具（委派、等待、公开消息…） | 由发起者自己调度 |
因此团队成员**不能**用子代理工具去调度另一个成员：这类工具在团队成员的运行时里被直接摘掉，避免把「团队任务的归属」偷偷转移出去。
## 什么时候用团队 [#什么时候用团队]
工作天然分阶段：先设计、再实现、最后审查。
需要一个独立视角挑错，而不是作者自评。
同一批材料要产出多个角度的结论，再合并成一份交付。
目标单一，一两轮就能做完。
你要边看边改、频繁介入细节。
任务本身没有可以并行或需要交接的部分。
## 智能体与团队：默认给了什么 [#智能体与团队默认给了什么]
入口是侧栏 **智能体**（Agents）。上半部分是**团队**，下半部分是**所有智能体**——团队由智能体编组而成，同一个智能体可以同时在多支团队里任职。
团队卡片显示成员头像与人数。点击团队会进入成员选择态：团队内成员显示移出标记、其他成员显示加入标记，点击卡片即可调整阵容并在顶部保存或退出；团队卡片中的会话与设置动作仍可直接使用。
首次打开时，内置扩展「预设智能体」会铺下 5 个通用人设：
| 智能体 | 角色 | 它负责什么 |
| --- | ---------- | ------------------------ |
| 主控 | Master | 拆解目标、分派任务、验收结果并最终交付 |
| 开发员 | Developer | 生产核心资产：代码、成稿或完整分析 |
| 检索员 | Researcher | 搜集事实、文档、竞品与外部素材并核实来源 |
| 审计员 | Auditor | 红队视角挑错：正确性、安全、边界与无依据的断言 |
| 业务员 | Business | 把目标落成需求、范围与商业模式，并说清假设与风险 |
以及 2 支预置团队，队长都是主控：
| 团队 | 阵容 | 流程 |
| ---- | -------------------- | ---------------------------------- |
| 开发团队 | 主控 · 开发员 · 检索员 · 审计员 | 先取证，再实现自测，最后审查；有阻塞缺陷就回到实现或计划 |
| 策划团队 | 主控 · 检索员 · 审计员 · 业务员 | 先调研取证，再成案（需求、范围、商业模型），审计挑完致命缺陷才出方案 |
这些人设与团队由扩展维护，宿主自己不带任何预设：它们在智能体页面标着来源，不能删除，停用对应扩展就会一并收起。你自己创建的智能体与团队不受影响。
流程不是写死在代码里的，而是写在这支团队队长的**团队任务书**里（见下文「配置团队」）。所以改流程就是改一段文字，不需要等版本更新。
预置内容在首次安装时被物化成普通的团队文件，之后和你自己创建的团队完全一样：可以改名、改职责、增删成员，也可以整支删掉——删掉后不会被重新注入。
## 发起一次团队协作 [#发起一次团队协作]
### 选定团队 [#选定团队]
在**新建会话**页，用输入框上的选择器**指定一个团队或单个智能体**；也可以在智能体页选中团队卡片后点 **发起该团队会话**。选单个智能体是普通会话，只是换了人设；选团队才会进入团队协作。
### 确定工作空间 [#确定工作空间]
不指定项目时，这次会话会拿到一块**新工作空间**（属于它自己的目录）；指定项目则直接在项目目录里工作。工作空间在会话创建时固化，协调与全部成员共用同一个目录，之后不会因为项目列表变化而改道。
### 描述任务并发送 [#描述任务并发送]
直接写目标即可，**不指定成员时由负责人接手**。要点名某位成员，用输入框左下角的 `@`。会话默认模型、推理档位和执行模式属于这个团队会话；成员也可以使用团队设置中的固定模型。成员在排队时确定使用的设置。
主时间线只显示公开进展：负责人的计划、每次
team_delegate_task
委派，以及各成员完成后的结论。
## 看懂并介入这条时间线 [#看懂并介入这条时间线]
| 界面元素 | 含义 |
| ----------------------- | ----------------------------------------------- |
| 顶部成员条 | 本次会话的名册；负责人带皇冠标记。点任一成员进入**它的独立会话**，看它自己那条完整执行记录 |
| 成员卡片与状态 | 等待开始 / 正在思考 / 正在调用工具 / 已完成 / 处理失败，对应该成员当前的任务状态 |
| `team_delegate_task` 步骤 | 负责人把一项有边界的目标交给某位成员，此刻任务才真正开始排队 |
| 齿轮图标 | 进入团队设置：成员、负责人、任务书与能力 |
你随时可以在中途再发一条消息补充要求；要把话说给特定的人，就 `@` 它。团队会话按会话隔离草稿、附件、输入历史与会话默认模型，因此同一支团队可以同时有多个互不干扰的会话，它们都出现在侧栏的对话列表里，行首是成员的叠放头像。
## 查看和调整成员模型 [#查看和调整成员模型]
点击输入栏的模型入口，展开「团队模型」。全员跟随时，入口只显示默认模型名称；有成员独立配置时，只显示「按成员配置」。
面板顶部显示「会话默认」，对应模型只出现一次，并说明切换会影响多少位成员。跟随默认的成员行只显示「跟随会话默认」，不重复模型名称。同模型成员合并展示，保留每位成员的头像；单独指定其他模型的成员显示在下方。只有一位成员时，直接显示姓名与模型选择框；多人使用同一模型时保持合并。如果全员都单独指定模型，未被使用的会话默认入口会收到底部。
点击头像可直接调整该成员，也可以通过顶部唯一的「按成员设置」入口展开全部成员，再用「合并显示」收起。成员编辑页顶部显示「跟随会话默认」开关；推理档位使用「推理：低」等完整标签。模型搜索与选择在原面板内切换，成员编辑页保留头像。推理档位使用分档滑轨：点击滑轨或档位名称时，滑块会缓动到目标档位；拖动时会即时预览档位，松开后保存，也支持方向键调整。点击返回或按 Escape 回到概览，并保留成员展开状态。
* **会话默认**：只影响当前会话中选择跟随的成员，面板会显示人数。
* **成员固定**：直接在成员行选择模型和推理档位。这份设置与团队设置共用，适用于该团队的所有会话，不会随会话默认模型切换。
* **跟随开关**：打开时清除成员的固定设置，之后使用会话默认模型；关闭时固定成员当前使用的会话默认模型。选择下方的具体模型也会自动关闭开关。
修改用于之后入队的任务，已排队、正在运行的任务和历史消息保留原模型。模型不可用时保留原选择并提示重新选择，不会自动替换；保存失败时原配置保留，可重新加载后重试。
## 原理：委派、等待与验收 [#原理委派等待与验收]
团队协作不是把一句提示词丢给几个模型各说一遍，而是一组**持久任务**在成员之间流转。负责人手里有一套团队工具，界面上看到的每个步骤都对应其中一次调用：
| 工具 | 作用 | 谁能用 |
| ---------------------------------------- | ------------------------------------------- | ------------ |
| `team_delegate_task` | 把一项有边界的目标交给某位成员，**立刻**返回任务 ID，不等它做完 | 仅负责人 |
| `team_wait_tasks` | 等待最多 8 项任务出现状态变化，可设超时 | 任务相关方 |
| `team_get_task` | 读某项任务的当前状态、等待原因与已发布结果 | 任务相关方 |
| `team_continue_task` / `team_retry_task` | 让中断或失败的任务在原有成员会话里续跑或重试，任务 ID 不变 | 负责人或该任务的承接成员 |
| `team_cancel_task` | 取消派给他人的一项任务 | 仅负责人 |
| `team_send_message` | 向若干成员公开发消息：`inform` 只是知会，`question` 才要求对方回应 | 全体成员 |
| `team_list_members` | 读当前名册：职责、可用状态与生效能力 | 全体成员 |
| `team_read_shared_history` | 按策略读取公开历史原文 | 全体成员 |
这套工具背后有三条硬约束，它们解释了你在界面上看到的大部分行为。
### 派发是异步的，所以能并行 [#派发是异步的所以能并行]
`team_delegate_task` 在任务**被受理**时就返回，因此负责人可以先把互相独立的任务一次性派出去，再统一等待。每位成员拥有一条自己的执行车道：不同成员真正并行，同一成员的多项任务按顺序来。
这也是为什么等待有边界：`team_wait_tasks` 超时只是「这段时间内没有新变化」，**既不代表失败，也不会取消任务**。任务完成时会有一条完成通知主动唤醒发起方，所以负责人不需要空转轮询。
系统还会拒绝**环形等待**：如果 A 正在等 B，B 就不能反过来等 A，否则两边都会永远停住。
### 归属不会被偷偷转移 [#归属不会被偷偷转移]
默认编排策略是「负责人分派」：只有负责人能委派和取消任务，成员只能推进自己手上的那一项。成员的角色提示词里也写明了同一条纪律——信息不足时要么问、要么回报负责人，而不是把任务转手给别人。加上子代理工具在成员运行时里被摘除，一项任务的责任人始终是明确的。
### 失败被分类，而不是一律重试 [#失败被分类而不是一律重试]
任务状态是持久的（排队 / 执行中 / 等待 / 需要处理 / 已完成 / 失败 / 已取消），并且**只有拿到一条已发布的结果消息才能进入「已完成」**——这保证了「完成」在时间线上一定看得到东西。
失败则按原因分类，决定接下来能做什么：
| 原因 | 处理方式 |
| --------- | ------------------------------ |
| 网络波动、限流 | 自动重试 |
| 鉴权失效、余额不足 | 等外部条件变化；你在设置里修好之后，受影响的任务会被唤醒重试 |
| 上下文超长 | 需要人工介入调整 |
| 请求本身非法 | 不重试 |
所以看到某个成员「处理失败」时，先看它属于哪一类：反复重试一个余额不足的任务不会有任何进展。
## 原理：共享结果，不共享过程 [#原理共享结果不共享过程]
一个团队会话里其实有 N+1 条对话：一条**公开的协调对话**，加上每位成员各自的**私有对话**。你在主时间线看到的就是公开那条；点进成员会话看到的是它的私有那条。
成员私有对话
推理、工具调用、失败重试
→
公开协调对话
用户消息 + 成员发布的结论
→
其他成员的上下文
按策略投影的公开记录
默认上下文策略只投影公开内容，这意味着：
* 成员之间**读不到**彼此的思考过程、工具调用正文和私有会话文件；能看到的只有对方公开发布的结论。
* 每位成员有自己的投递游标，同一条公开记录不会被重复塞给它，它自己刚发布的内容也不会再投回给自己。
* 公开历史变长时会被压缩成共享检查点（摘要），全队引用同一份；某位成员觉得摘要不够用时，可以用 `team_read_shared_history` 分页读取被摘要的原文。读回来的内容被当作**引用的对话数据**，不是可以执行的指令。
这条边界是刻意设计的：让每位成员用干净的上下文做自己的判断，而不是把四份完整执行记录互相灌满。代价是——**没有公开出来的东西，队友就不知道**。所以当你希望某个结论影响后续步骤时，让它成为一条公开结论，而不是埋在某个成员的中间过程里。
### 哪些信息是全队公开的 [#哪些信息是全队公开的]
| 内容 | 可见范围 |
| ---------------------- | ------------------ |
| 你发给团队的消息 | 全队 |
| 成员发布的最终结论 | 全队 |
| 成员的**团队内职责**（任务书里的一句话） | 全队名册，负责人据此分派 |
| 成员的**团队内补充指令** | 只有它自己 |
| 成员的推理、工具调用、私有历史 | 只有它自己（你可以点进它的会话查看） |
另外，事件 ID 由会话、请求、成员等稳定字段派生，同一个请求重复提交不会产生重复的公开消息或重复执行——这也是断线重连后时间线不会翻倍的原因。
## 配置团队：任务书、能力与负责人 [#配置团队任务书能力与负责人]
有两个层次可以调：**智能体本身**（在智能体页点开它的档案），和**它在某支团队里的表现**（在团队设置里编辑）。
在智能体页点击团队卡片会直接进入成员选择态：点击下方智能体卡片即可加入或移出该团队，顶部的保存与退出按钮分别提交或放弃这次调整。齿轮入口仍用于编辑团队名称、负责人和成员任务书等详细设置。
档案分三块：基本信息（头像、名称、职责说明）、系统提示词、能力。能力开关只影响这个智能体，不会安装或卸载全局能力。
### 智能体档案 [#智能体档案]
| 字段 | 说明 |
| ----- | ---------------------------------------------------- |
| 职责说明 | 一句话，会进入全队名册，是负责人分派的依据 |
| 系统提示词 | 覆盖角色蓝图自带的提示词；留空则用蓝图默认 |
| 能力 | 该智能体可用的技能、场景、MCP 与插件。默认继承**全部**全局可用能力，动过任一开关后变成自定义集合 |
一个智能体被多支团队引用时，保存会先列出受影响的团队让你确认；确认后这些团队的**后续回合**使用新配置。
### 团队设置：成员与任务书 [#团队设置成员与任务书]
齿轮进入团队设置，可以增删成员、更换负责人，并为每位成员写一份**团队任务书**：
| 任务书字段 | 作用 | 谁看得到 |
| ------- | ------------------ | ----- |
| 团队内职责 | 覆盖档案里的职责说明，只在本团队生效 | 全队名册 |
| 团队内补充指令 | 追加在它原有人设之后的团队内交待 | 只有它自己 |
任务书是**增量**：字段留空就回到智能体档案里的设定，也不会影响它在其他团队里的表现。它追加在本体人设与角色协作纪律之后，不替换它们——所以不必在任务书里重写「要向负责人回报」这类规则。
预置团队的固定流水线正是用这个机制实现的：流程写在 Master 的团队内补充指令里。想换流程，改这段文字即可。
添加成员时还要选绑定方式：
* **跟随智能体库更新**（引用）：智能体档案改了，这支团队跟着变。默认选它。
* **仅用于此团队**（复制）：复制一份团队私有的档案，之后与库里的原版互不影响。
### 改动什么时候生效 [#改动什么时候生效]
成员运行时按「档案修订 + 任务书指纹 + 名册指纹」判断是否需要重建：动了档案、任务书，或者换了负责人、增删成员、改了队友的团队内职责，**下一回合**生效，历史记录保留；只改团队描述这类不进入提示词的字段，不会牵连正在进行的成员会话。
## 会话、工作空间与文件 [#会话工作空间与文件]
### 一支团队，多个会话 [#一支团队多个会话]
团队是配置，会话是一次具体的工作。同一支团队可以同时开多个会话，各自有独立的工作空间、草稿、附件、会话默认模型与历史，互不干扰。
工作空间在创建会话时就固定下来：
| 创建时的选择 | 工作目录 |
| ------ | ------------------------------------------------------------- |
| 不指定项目 | 这次会话独占的新目录（`ASTRAVIA_HOME/agent-teams/session-workspaces/` 下） |
| 指定项目 | 该项目目录 |
协调运行时和所有成员共用这一个目录，因此成员写出的文件互相看得见——**文件是它们真正的共享工作台**，而消息只传结论。
团队会话的底层存储与普通对话是同一套格式，但会被明确标记归属：它们不会混进普通对话列表和搜索结果，只以团队会话的身份出现在侧栏。活动面板对团队只开放语义明确的**文件**与**浏览器**页签。
### 团队配置就是一组文件 [#团队配置就是一组文件]
所有团队与智能体都落在 `ASTRAVIA_HOME/agent-teams/`（生产环境默认 `~/.astravia`）：
结构化元数据（能力选择、成员索引、策略引用）在 `*.json` 里，长文本（职责说明、系统提示词、成员任务书）是独立的 Markdown 文件——可以 diff、可以进版本管理、可以在团队之间复制。目录名由可读名称加不可变 ID 摘要组成，改名不会改目录。
写入使用修订号乐观锁与原子替换：同一份配置被两处同时修改时，后一次保存会失败而不是悄悄覆盖。
## 用好一支团队 [#用好一支团队]
* **把验收标准写进第一句话**。负责人是按你给的目标验收的；「做完发我」和「做完让 Auditor 过一遍，没有阻塞缺陷再交」得到的流程完全不同。
* **让关键结论公开**。队友只看得到公开发布的内容，藏在某个成员中间过程里的判断不会自动传下去。
* **调行为优先改任务书**。只影响这支团队，不会波及同一个智能体在别处的表现。
* **人数不是越多越好**。每多一位成员就多一份模型开销与交接成本；预置团队都是 4 人，通常够用。
* **简单任务别用团队**。一两轮能完成的事，普通会话或单个智能体更快也更便宜。
## 常见问题 [#常见问题]
* **任务一直显示「等待」**：等待不等于失败。先看它是不是在等外部条件（凭证失效、余额不足）——修好之后受影响的任务会被唤醒重试；否则它只是还没轮到或仍在执行。
* **某位成员总是跑偏**：改它在**这支团队**的任务书（团队内职责 + 补充指令），而不是改它的智能体档案，后者会影响引用它的所有团队。
* **改了配置却没变化**：档案与任务书从**下一回合**生效，当前正在跑的回合不受影响。
* **想中途补充要求**：直接在团队会话里发消息；要指定人就用 `@`。
* **删除一个智能体会怎样**：保存前会列出受影响的团队。确认后它会从这些团队移除；如果它是负责人，负责人顺位转交给剩下的成员；如果团队因此一个成员都不剩，这支团队也会被删除。
* **在普通对话列表里找不到团队会话**：团队会话只以团队身份出现在侧栏，不混进普通对话列表和搜索结果。
---
# 使用应用快照
> 在 macOS 上按住左右同一功能键，把前台窗口的截图与文字挂到输入框，让 Agent 理解你此刻的屏幕。
Canonical page: /product/app-snapshot
应用快照只在 macOS 提供，默认关闭
抓取由独立的 Astravia Computer Use 辅助程序完成，需要单独授权
捕获结果是附件，不会自动发送，你仍可以先补充说明再提问
应用快照解决的是「我说不清屏幕上这一块是什么」。同时按住键盘左右两侧的同一个功能键约 0.25 秒，Astravia 会抓取**当前前台窗口**的截图和可读文字，作为附件挂到输入框，并把主窗口带到前台定位到新会话。它不是全屏录制，也不是持续监视：只在你做出手势的那一刻抓一次。
入口：**设置 → 应用快照**（仅 macOS 显示）。
触发方式决定按哪一对功能键；权限区域显示辅助程序当前是否已获授权。
## 开启并授权 [#开启并授权]
### 选择触发方式 [#选择触发方式]
在 **触发快捷键 → 触发方式** 中选择一组功能键：同时按住左右 ⇧、左右 ⌘ 或左右 ⌥。选择「不启用」即关闭该功能。修改后立即生效，不需要重启。
### 授权辅助程序 [#授权辅助程序]
应用快照通过独立的 **Astravia Computer Use** 辅助程序读取前台窗口，它是独立的授权主体，授权给 Astravia 主程序不能替代。首次开启时若权限不全，Astravia 会自动打开授权引导窗；也可以随时点击 **打开授权引导**，把窗口中的图标拖进系统权限列表完成授权。
### 确认权限状态 [#确认权限状态]
回到设置页的 **权限** 区域，确认「辅助功能」和「屏幕录制」都显示为已授予。该区域在窗口重新获得焦点时会刷新。
### 试抓一次 [#试抓一次]
切到任意其它应用窗口，按住选定的左右功能键。听到系统截图音效、主窗口弹出并在输入框看到快照卡片，即表示链路已通。
全局手势与快捷面板共用同一套键盘监听。若按住功能键完全没有反应，请在「系统设置 › 隐私与安全性 › 输入监控」中确认已授权 Astravia。
## 需要哪些权限 [#需要哪些权限]
| 权限 | 授权主体 | 缺失时的后果 |
| ---- | --------------------- | ------------------ |
| 辅助功能 | Astravia Computer Use | 读不到窗口标题、文档路径和窗口内文字 |
| 屏幕录制 | Astravia Computer Use | 抓不到截图，只保留文字与元信息 |
| 输入监控 | Astravia | 手势不触发，功能完全不响应 |
两项辅助程序权限都缺失时，Astravia 会把主窗口带到前台并提示去权限管理授权，不会产生附件。只缺其中一项时仍会尽力抓取另一半。
## 一次捕获包含什么 [#一次捕获包含什么]
| 内容 | 来源 | 说明 |
| -------- | ---- | ------------------------------------------- |
| 窗口截图 | 屏幕录制 | 仅前台窗口，PNG |
| 窗口文字 | 辅助功能 | 以 Markdown 落盘，带 app、window、captured_at 等元信息 |
| 源文件路径 | 辅助功能 | 前台窗口正在编辑的文档路径（若可读取） |
| 应用名与窗口标题 | 辅助功能 | 作为附件卡片的标题显示 |
文字层只取辅助功能能读到的内容。抓不到文字时不会在捕获阶段做 OCR，而是只带截图交给模型用视觉能力理解。截图、图标和文字文件写入 `~/.astravia/image-cache/appshot/`，与图片缓存共用清理策略，长期未使用的缓存目录会被自动清除。
## 捕获之后 [#捕获之后]
* 附件以快照卡片的形式停留在输入框，可点击预览大图，也可以移除。
* 快照不会自动发送。补充一句你真正想问的问题再发送，效果明显好于只丢一张图。
* 发送后截图与文字一起作为附件进入会话，消息气泡里保留快照卡片。
* 未发送的快照会随输入框草稿一起保留，切走再回来不会丢。
## 触发没有生效时 [#触发没有生效时]
1. 确认前台窗口不是 Astravia 自己：抓取自身窗口会被主动忽略并提示。
2. 确认左右两侧的功能键**同时按住**并保持约 0.25 秒，先后按下或一触即放不会触发。
3. 确认设置里的触发方式不是「不启用」，且没有被其它全局快捷键抢占同一组键。
4. 出现「捕获失败」提示时，先看 **权限** 区域状态，再重新走一次授权引导；辅助程序被系统隔离或缺失时，重新安装应用可恢复。
5. 连续做手势只会跑一次捕获：上一次还在进行时新的手势会被忽略，稍等再试。
## 隐私边界 [#隐私边界]
* 捕获是手势触发的一次性动作，没有后台常驻录屏。
* 抓取范围限定为前台窗口，不包含其它应用窗口和桌面其余部分。
* 快照落在本机 `~/.astravia` 目录；只有当你发送这条消息时，内容才会随会话进入所选模型。
* 屏幕上有密码、密钥或客户数据时，先切走窗口再做手势，或在发送前移除附件。
---
# 管理应用环境
> 检查并修复 Astravia 内置 Node.js、Python 与包镜像配置。
Canonical page: /product/application-environment
入口：**设置 → 应用环境**。管理 Astravia 随应用提供的运行时，供 Agent 与相关命令进程使用。它们 **不会** 改写系统终端、Shell 配置或本机全局 Node/Python 安装。
## 运行时 [#运行时]
页面 **运行时** 区域显示内置：
| 运行时 | 用途（界面说明） |
| ------- | ------------------------------------ |
| Node.js | 运行 JavaScript / TypeScript 工具与 npm 包 |
| Python | 运行 Python 脚本与 pip 包 |
状态可能为已就绪 / 未就绪 / 获取中。首次使用代码类工具，或升级后运行时不可用时，使用 **获取** / **重新获取** / **重装** 修复当前应用配套版本。
验证时，在 **Astravia 会话** 中让 Agent 执行：
```bash
node --version
python --version
```
应返回版本号。系统终端里的版本可以不同，这不代表 Astravia 内置环境失败。
## 开发工具 [#开发工具]
**开发工具** 显示本机 Git 的版本和来源。Git 面板，以及 Agent 执行的 git 命令，都依赖它。
已经安装的系统 Git 优先使用。Astravia 不会用自带的 Git 盖过你的配置和凭据。没检测到时：
| 系统 | 页面上怎么做 |
| ------- | ------------------------------------------------------------------------- |
| macOS | 点 **安装**，打开系统的「命令行开发者工具」窗口。装完后点 **重新检测** |
| Windows | 点 **为 Astravia 安装**。它只在 Astravia 内生效，不改系统环境。要在终端或其他软件里也使用 Git，用旁边的链接下载安装包 |
| Linux | 复制页上对应发行版的命令，在终端执行，然后点 **重新检测** |
没装 Git 时，Git 面板不会提示去初始化仓库，而是给出同样的安装引导。
## 镜像源 [#镜像源]
| 项 | 说明 |
| ------ | ------------------- |
| npm 仓库 | 安装 npm 包时自动注入的镜像 |
| pip 索引 | 安装 Python 包时自动注入的镜像 |
需要其它源时，在具体项目或命令中显式配置，并遵守组织网络策略。
## 限制 [#限制]
* 内置环境不包含完整本机编译工具链。需要 C/C++ 或平台 SDK 编译的原生依赖可能失败；此类项目应使用已准备好的系统开发环境或预编译包。
* **重新获取** 只修复当前 Astravia 版本配套的运行时，不会升级到应用尚未支持的新版本。
* 部分平台可能提示 **当前平台不支持** 某一运行时。
---
# 创建自动化任务
> 把已经人工跑通的任务交给本地调度器，按单次、每天或间隔计划执行并检查历史。
Canonical page: /product/automation
自动化适合稳定、可重复、无需每次重新解释的任务。调度由桌面客户端在本机完成：Astravia 完全退出、计算机睡眠或关机时不会按计划执行。
## 自动化之前先手动跑通 [#自动化之前先手动跑通]
不要把尚未验证的宽泛提示直接交给无人值守执行。先在普通会话中完成一次，并确认：
* 输入来源在每次执行时都存在且路径稳定。
* 输出位置明确，不会覆盖不相关文件。
* 成功和失败可以从实际结果判断。
* 需要的模型、MCP、技能和权限在无人值守时可用。
* 没有必须由人临场选择的高风险步骤。
## 示例：每日项目状态摘要 [#示例每日项目状态摘要]
```text
读取当前项目中今天发生变化的文档和任务记录，生成 reports/daily-status.md。
内容包括：已完成、进行中、阻塞和明日建议。
只读取项目文件，不修改其他内容；没有变化时仍生成文件并写明“今日无记录”。
完成后确认输出文件存在，并在回复中列出使用的数据来源。
```
先在目标项目会话中运行这段任务，检查 `reports/daily-status.md`，再创建自动化。
## 创建任务 [#创建任务]
入口：侧栏 **自动化**。页面也提供晨间简报、工作总结和每周复盘等模板，使用后仍应按自己的数据来源和输出要求修改。
| 字段 | 说明 |
| ---- | ----------------- |
| 任务名称 | 卡片和执行历史中的识别名称 |
| 提示词 | 无人值守时仍能独立理解的完整任务 |
| 工作目录 | 「对话」或已有项目目录 |
| 模型 | 每次执行使用的模型 |
| 计划 | 单次、每天或每隔 N 小时 / 天 |
| 沙盒 | 跟随默认、完全访问或使用沙盒 |
| 启用 | 保存后是否允许调度触发 |
### 固定输入和输出 [#固定输入和输出]
在提示中写出输入来源、目标路径、允许修改的范围和失败条件，不依赖“上次我们讨论过”的会话记忆。
### 选择时间计划 [#选择时间计划]
核对界面显示的下次执行时间。计划使用操作系统当前时区；跨时区或夏令时变化后重新检查。
### 保存后立即执行 [#保存后立即执行]
第一次使用 **立即执行**，不要等到下一个计划点才发现模型、目录或权限不可用。
### 验收历史和实际产物 [#验收历史和实际产物]
在执行历史中打开对应会话，同时检查目标目录中的实际文件或外部结果。
## 运行状态和恢复 [#运行状态和恢复]
任务详情提供执行历史，状态包括成功、失败、执行中和已中止。常用动作：
* **暂停**：保留配置，但阻止后续计划触发。
* **启用**：恢复之后的计划，不自动补跑错过的时间点。
* **立即执行**：不改变原计划，额外启动一次验证或补跑。
* **编辑**：调整任务、目录、模型或计划；修改后再次立即执行。
* **删除**：移除任务配置，历史与相关会话按界面确认语义处理。
项目维度的自动化概览也会出现在活动面板中，可查看今日执行、启用任务和最近记录。
## 常见失败 [#常见失败]
| 现象 | 检查 |
| --------- | ---------------------------------- |
| 到点没有执行 | Astravia 是否运行、设备是否睡眠、任务是否启用、时区是否变化 |
| 模型调用失败 | 模型和凭证是否仍可用、是否触发配额或速率限制 |
| 找不到文件 | 项目目录是否移动，提示中的相对路径是否仍成立 |
| 卡在权限确认 | 是否选择了不适合无人值守的动作或执行模式 |
| 显示成功但没有结果 | 提示是否要求实际产物和验证，不要只依赖最终回复 |
当前调度依赖运行中的 Astravia 桌面客户端。需要跨设备常驻或服务端 SLA 时，不应把桌面自动化当作等价替代。
需要一份从试跑到启用计划的完整配方，参见[按计划生成项目报告](/examples/scheduled-project-report/)；需要对多个目录同时运行同一提示时使用[批量任务](/product/batch-tasks/)。
---
# 运行批量任务
> 用一套任务配置并发处理多个独立目录，集中观察状态、校验产物并局部重试。
Canonical page: /product/batch-tasks
每个目录必须能独立验收
先用一个目录验证，再提高并发
产物规则比模型回复更可靠
批量任务把一个已经跑通的方法应用到多个目录。它不是把一个复杂任务自动拆成多个步骤，而是为每个目标目录创建独立子任务和会话，再按并发上限执行。
一份配置扇出为多个独立任务；看板负责全局状态，会话保留单次执行细节。
## 先判断是否适合批量 [#先判断是否适合批量]
同一规则检查多个仓库
为多个目录生成相同类型产物
批量迁移相似配置
对多份资料执行独立整理
子任务之间有严格先后依赖
所有目录必须共享实时中间状态
目标只有一个，且需要频繁交互决策
任务无法在单个目录内独立验收
批量任务的关键不变量是：任意一个子任务单独执行，也能得到可判断成功或失败的结果。
## 示例：检查多个项目的发布准备度 [#示例检查多个项目的发布准备度]
```text
C:\work\api-service
C:\work\desktop-client
C:\work\admin-console
C:\work\docs-site
```
```text
检查当前项目是否具备可执行的发布前流程。
要求：
1. 阅读 package.json、README 和现有发布配置；
2. 只生成 release-readiness.md，不修改源码或配置；
3. 列出构建、测试、版本和发布入口的实际状态；
4. 不确定的项目标记为“需人工确认”，不要猜测；
5. 完成后确认 release-readiness.md 已生成。
```
产物校验填写 `release-readiness.md`。这样即使模型回复正常但没有写出文件，子任务也不会被误判为完成。
## 创建批量项目 [#创建批量项目]
入口：侧栏 **更多 → 批量任务**。点击 **新建项目**，填写：
列表和推送中显示的名称
应用于每个目录的同一任务说明，可用
`/`
唤出技能或场景
所有子任务使用的模型
每行或每次选择一个目录，每个目录生成一个子任务
同时处于运行中的子任务上限
单次运行硬超时；暂停后恢复会重新计时
跟随默认、完全访问或使用沙盒
子任务目录顶层必须全部匹配的文件名或 glob
子任务完成和项目全部完成时通知已配置 Webhook
## 先用一个目录验证 [#先用一个目录验证]
### 只添加一个代表性目录 [#只添加一个代表性目录]
选择结构最常见、风险较低的目标，并发设置为 1。
### 执行并进入会话 [#执行并进入会话]
检查 Agent 是否读取正确文件、遵守修改范围，并实际产生预期输出。
### 调整提示和产物规则 [#调整提示和产物规则]
先消除模糊要求和误报条件，再追加其余目录并提高并发。
## 理解队列和状态 [#理解队列和状态]
共享配置
Prompt · 模型 · 并发 2 · 产物规则
目录 A
完成
目录 B
运行中
目录 C
运行中
目录 D
等待中
目录 E
失败
**开始**
：按并发数把未执行或可恢复的任务加入队列。
**停止**
：中断运行中任务，并清空除已完成外的会话、产物和状态后重置；确认框会说明具体影响。
**重置失败**
：只清理失败任务并重新入队，不必重跑全部目录。
单任务支持执行、继续、重试、重新运行、删除和跳转到会话。
活动面板中的 **执行进度** 用于看整体；进入单任务会话检查工具、消息和具体失败原因。
## 验收整个批次 [#验收整个批次]
总数等于预期目录数，没有遗漏或重复路径。
所有完成项都满足产物规则，而不是只有成功回复。
随机抽查至少一个普通目录和一个边界目录的实际内容。
失败项进入对应会话定位后局部重试。
Webhook 只作为通知，不作为最终验收证据。
停止会重置未完成任务的会话、产物和状态，并且不可撤回。只想临时降低负载时，优先处理单任务或等待当前任务结束。
需要一份可以直接试跑的完整配置，参见[批量审计多个项目](/examples/batch-project-audit/)；需要按时间周期执行一个任务时使用[自动化](/product/automation/)；需要多个步骤共享中间状态时使用普通会话分阶段完成。
---
# 让 Agent 操作浏览器
> 用「浏览器操作」在真实浏览器里导航、读页、填表和复用登录态，并在提交前保留人工确认。
Canonical page: /product/browser
只查公开资料用网页搜索，要「进页面把事办完」才用浏览器操作
浏览器窗口就在你面前，登录、验证码和二次验证由你亲自完成
每个会话使用独立浏览器 session，发布、付款、删除类动作要求先确认
浏览器操作（Browser Use）是随应用发布的系统插件。它让 Agent 通过 `agent-browser` 命令行驱动一个真实的 Chrome：打开网址、用无障碍树快照定位元素、点击、输入、等待、翻页并取回结果。页面是真的，登录态是你自己的，因此它能做到网页搜索做不到的事。
面板入口：**设置 → 更多选项 → 浏览器操作**。面板只负责运行时状态与说明，真正的入口是对话框——直接在会话里说明目标和网址即可。
## 先判断该用哪一个 [#先判断该用哪一个]
页面需要登录才能看到
要填表单、切筛选、翻到第 N 页
要在后台里完成一次多步骤操作
要把多个页面的结果对照整理
只需要公开资料的摘要或出处
问题能靠一次检索回答
不需要保持任何页面状态
网页搜索给你的是别人整理过的摘要；浏览器操作是真的开一个浏览器。要「看一眼资料」用搜索，要「替我把事办了」用它。
## 首次使用会装什么 [#首次使用会装什么]
插件本身随应用发布，不需要安装；第一次做浏览器任务时，Agent 会自行准备运行时。
### 检查运行时 [#检查运行时]
Agent 先确认 `agent-browser` 是否存在以及版本是否满足插件锁定的版本。版本读不出来时按不兼容处理，宁可提示重装也不静默失败。
### 安装锁定版本 [#安装锁定版本]
缺失或过旧时，Agent 把锁定版本装进 Astravia 私有的 npm 目录（约 90MB）。安装前会校验该私有目录确实存在，不会改动你机器上已有的全局 `agent-browser`。
### 准备浏览器 [#准备浏览器]
健康检查发现没有可复用的 Chrome 时，会再下载一次 Chrome for Testing；系统已有 Chrome 则直接复用，不额外下载。
### 自动流程失败时用面板 [#自动流程失败时用面板]
自动准备失败时，到 **设置 → 更多选项 → 浏览器操作** 面板里重新检查、安装或升级，面板会显示失败命令与原因。
面板状态含义：
| 状态 | 含义 | 下一步 |
| ------- | -------------------------- | ------------------------- |
| 已就绪 | CLI 可用，直接在会话里提要求即可 | 无需操作 |
| 尚未安装运行时 | 第一次使用，或运行时被移除 | 点击安装 |
| 运行时版本过旧 | PATH 上有更旧的 `agent-browser` | 点击升级，装入 Astravia 自己的运行时目录 |
| 尚未安装浏览器 | 本机没有可复用的 Chrome | 下载 Chrome for Testing |
| 安装失败 | 网络、权限或命令冲突 | 看面板给出的命令与错误，修复后重试 |
沙箱执行模式会给每条命令一个临时 home，浏览器 session 无法在命令之间保持。遇到这种情况请切换会话的执行模式，而不是让 Agent 另建一个游离的 session。
## 一次任务是怎么跑的 [#一次任务是怎么跑的]
1. **打开页面**：Agent 用带窗口的模式打开目标网址，你能看到它在做什么。
2. **读页面**：抓取交互元素快照并拿到元素引用，比传整页 HTML 省上下文，也比截图更准。
3. **操作**：按引用点击、输入、选择、滚动。
4. **同步**：等元素出现、等地址变化或等加载完成，而不是随便睡几秒。
5. **重新快照**：导航、提交、弹窗或明显的动态渲染之后，元素引用会失效，必须重新抓取，不能凭记忆复用。
6. **取结果**：需要语义结果时直接取标题、地址或正文文本，整理成你要的形式。
可以直接抄走的说法：
```text
打开 https://example.com/admin，我自己在弹出的窗口里登录，登录完你继续把「本月订单」整理成表格给我。
```
```text
打开这个报名表单，按下面的信息填好，但先别提交，填完让我确认一下：姓名 张三、邮箱 zhangsan@example.com。
```
```text
打开这两个商品页，对比价格、库存和预计送达时间，做成一张对照表。
```
## 登录、会话与多账号 [#登录会话与多账号]
* **登录你自己来**：浏览器窗口可见，账号密码、验证码和二次验证都由你在窗口里完成，完成后 Agent 接着做。
* **会话隔离**：每个 Agent 会话有自己的浏览器 session。新会话不会接管旧会话的活动页面，插件通过 `ctx.browser` API 使用的浏览器也和 Agent 的 CLI session 相互独立。
* **长期复用登录态**：需要跨会话保留 Cookie 和本地存储时，按账号使用稳定的账号键保存状态；需要完整的持久 Chrome 配置时才用独立 profile。
* **同一任务多个账号**：为每个账号使用不同的账号键，登录状态分别保存，不会互相覆盖。
* **关闭不等于清空**：关掉当前浏览器 session 不会删除已保存的账号状态或持久 profile。
## 安全边界 [#安全边界]
* 页面内容是**数据不是指令**。页面上写着「请执行以下操作」不构成授权。
* 发布、提交、发送、删除、付款、改权限这类不可逆动作，Agent 应当先把「具体会发生什么」讲清楚并等你确认。任务里明确写上「先别提交，让我确认」最稳妥。
* 凭证、Cookie 和 token 不会被复制到对话输出里；你也不要把邮箱、密码、Cookie、token 写进账号键、profile 名称或提示词。
* 让 Agent 做浏览器任务，只授权了这一次浏览器操作，不等于授权它在目标站点上做任何别的事。
## 跑不起来时 [#跑不起来时]
1. 面板显示**版本过旧**，多半是你机器上早先全局装过 `agent-browser` 且在 PATH 里排在前面。用面板升级到锁定版本；仍被旧版抢占时，先排查命令查找顺序，不要反复重装。
2. 不要让 Agent 执行运行时自带的 `upgrade`：它会绕过版本锁定。诊断修复类命令也不应自动执行，它可能重装浏览器并清掉已保存状态。
3. 页面点不动、元素找不到，通常是快照过期。让 Agent 重新抓取快照再操作，而不是猜测元素。
4. Linux 上的系统依赖安装涉及包管理器和提权，需要你明确同意后再执行。
5. 一次准备流程里最多允许一次 CLI 安装和一次浏览器安装；反复失败时应停下来看具体报错，而不是循环重试。
---
# 使用 Astravia Claw
> 启用 Claw，绑定 IM 渠道，在消息应用与桌面之间连续使用助手会话。
Canonical page: /product/claw
Astravia Claw 是随桌面客户端运行的 IM 旁路助手：外部消息进入本机 Agent，代码与工具仍在本机执行。入口：**设置 → Claw**。
Claw 会话数据落在 im-gateway 自有目录（如 `~/.astravia/im-gateway/conversation`），与桌面默认「对话」项目物理分家；侧栏可筛选 **Claw** 记录查看。
## 开始使用 [#开始使用]
### 启用 Claw [#启用-claw]
打开 **设置 → Claw**，打开总开关。启用前需已配置当前活动渠道（飞书 App 凭证或微信已绑定），否则会提示无法启用。
### 选择对话模型 [#选择对话模型]
在同一页为 Claw 选择 **对话模型**（可设推理档位），并 **测试连接**。
### 配置消息渠道 [#配置消息渠道]
配置一个可用 IM 渠道，并切换 **活动渠道**。详见 [IM 渠道](/product/im/)。
### 保持桌面运行 [#保持桌面运行]
状态应为运行中。完全退出 Astravia 会停止 sidecar，无法继续收消息。可在状态区查看进程信息、**查看日志** 与 **重启**。
## 会话命令 [#会话命令]
在已绑定的 IM 私聊中发送（以当前 `im-gateway` 命令集为准）：
| 命令 | 作用 |
| --------- | ------------------------------------- |
| `/help` | 显示可用命令 |
| `/new` | 在当前对话中开启新会话（清空上下文）；开启前会尽量把可保留事实写入长期记忆 |
| `/whoami` | 查看当前用户、会话目录与连接池等诊断信息 |
已移除按项目切换的命令（如旧版 `/projects`、`/use`）。IM 侧统一在 Claw 会话目录中工作，不在渠道内切换桌面项目。
## 使用边界 [#使用边界]
* 复杂改动、敏感权限或严格验收时，回到桌面客户端确认工作目录、执行模式与工具调用。
* Claw 会做会话记忆整理，但不要当作唯一事实来源；关键约束仍应放在项目文档、知识库或明确任务说明中。
* 一次只有一个活动传输渠道；渠道是否能使用取决于第三方账号、平台权限、本机环境和网络。
---
# 用 Astravia 做设计
> 在设计画布上用对话生成真实 React 界面，选中修改、留备注、预览运行、回退版本并导出分享。
Canonical page: /product/design
画框不是图片，是可运行的 React 页面
先说清产品类型和屏数，再让 Astravia 画第一版
改稿从画布上选中开始，而不是重新描述整页
设计能力由随桌面端发布的系统插件 **Astravia UI Design** 提供。一份设计稿是一个可运行的小前端项目：每个画框对应 `frames/` 下的一个 React 文件，也就是一条路由；保存即热更新，画布上看到的就是真实渲染结果，可以点进去走完整流程。
因此它适合做产品界面、落地页、幻灯片和海报，不适合用来改你自己仓库里的真实前端代码——那是普通编码会话的工作。
## 入口：设计画廊 [#入口设计画廊]
侧栏 **更多 → 设计** 进入设计画廊，也可以 pin 到侧栏常驻。画廊收集所有项目根目录下的 `.astravia-design` 设计稿，一个项目一张卡，封面是这份画布最后的样子。
卡片按最近改动排序；右上角绿点表示该项目里有会话正在运行。点卡片会回到当初做这份设计的会话，并展开画布。
画廊只扫项目根目录一层：手动挪进子目录的设计稿不会出现在这里（画布本身仍能打开）。归档的项目也不进画廊。
## 开一份设计 [#开一份设计]
### 选择起点 [#选择起点]
* **新建**：只需起个名字，会在工作区目录下建同名项目，并进入新建会话页，输入框已带好设计能力。
* **逛逛风格库**：先挑一套现成风格，新建的设计会直接带上它的配色与规范。
* **导入**：把 `.astravia-design-share` 分享包拖进画廊，或点 **导入** 选文件。
### 描述你要什么 [#描述你要什么]
第一句话决定设计的结构，尽量写清三件事：**产品类型**（手机应用 / 桌面看板 / 落地页 / 幻灯片 / 海报）、**大致屏数或页面清单**、**风格与受众**。
```text
做一个社区 App 的移动端设计稿，6 屏：首页动态、发现圈子、
圈子详情、群聊、个人主页、帖子详情。风格明亮活泼，主色偏荧光绿。
```
产品类型决定默认画框尺寸，说错最常见的后果是把桌面看板画成了 390 宽的手机屏。
### 等第一版铺开 [#等第一版铺开]
多屏设计通常先落一遍骨架（结构和尺寸先对），再分批填内容，所以画布上会先出现一排空壳画框。首次使用需要安装设计引擎依赖，约 1–3 分钟，只发生一次。
| 产品类型 | 默认画框尺寸 |
| ----------- | ----------- |
| 手机应用 | 390 × 844 |
| 桌面应用 / 数据看板 | 1440 × 900 |
| 落地页 | 1440 × 2400 |
| 幻灯片 | 1920 × 1080 |
| 海报 / 社交图 | 1080 × 1440 |
同一份设计里可以混排不同类型，每个画框自己声明尺寸。
## 在画布上改稿 [#在画布上改稿]
改稿不要重新描述整页，**先在画布上选中要改的东西**：选中一个画框，或点进画框选中具体元素，Astravia 就只改这一处。
左侧是对话，右侧是同一份设计文档里的全部画框。画框标题下会显示「创作中 / 修改中 / 已更新 / 构建失败」等状态。
选中后会出现两个入口：
| 入口 | 什么时候用 |
| ----------------- | -------------------------------------- |
| **让 Astravia 去做** | 现在就改。要求直接发进当前对话 |
| **留个备注** | Astravia 正在忙，不想打断。备注钉在画布上，它收尾时会逐条处理并回复 |
备注也可以用底部工具栏的备注工具（快捷键 `C`）钉在画布任意位置。备注抽屉按 **待处理 / 已处理** 分组，可以整批 **让 Astravia 处理**；每条处理完会在原位置变成已处理，并附上回复。
底部工具栏还提供：选择、拖手、**新建 Frame**（先拖出空画框再让 Astravia 填）、缩放、**自动排列**（可设列数）和 **刷新画布**（重新加载所有画框的最新代码）。
## 设计体系 [#设计体系]
控制栏的 **设计体系**（或画廊的风格库）提供成套配色与规范。对已有画框的设计稿应用一套体系，等于让 Astravia 按新规范全量重设，耗时较长；应用前会自动备份，随时可以 **还原到应用前**。
设计稿里已有 `DESIGN.md` 时，说明你已经应用过一套规范，再应用新的会覆盖它（同样可还原）。
## 预览与运行 [#预览与运行]
点右上 **运行** 进入预览模式：真实点击导航、切换视口（跟随画框 / 手机 / 平板 / 桌面），也可以 **用系统浏览器打开**。该地址由本机设计引擎提供，关闭设计画布后失效。
## 版本历史 [#版本历史]
Astravia 每完成一次修改就自动存一个版本，标题就是你当时提的要求。控制栏 **版本历史** 里可以：
* **查看**：临时回到某一版看效果，此时的修改不会被保存；
* **恢复到此**：把设计变回那一刻的样子。恢复前的当前内容会先存成一个版本，选错了再恢复回来即可。
所以「撤销刚才那次改动」「回到导航栏移动之前」应该走版本历史，而不是让 Astravia 凭记忆改回去。
## 导出与分享 [#导出与分享]
| 方式 | 产物 |
| ------------------------------ | -------------------------------------------------- |
| 画布 **导出分享** / 画廊卡片右键 **导出分享包** | `.astravia-design-share` 分享包，对方拖进画廊即可查看或导入编辑 |
| 控制栏 / 画框右键 **导出渲染图** | 挑选画框排版成 PNG、长图或 PDF，可调倍率、圆角、外边框、背景、投影与 Astravia 标识 |
| 画框右键 **复制为图片** | 单个画框位图，直接进剪贴板 |
导出分享包需要跑一次构建，会等几秒。
## 设计稿的目录结构 [#设计稿的目录结构]
一份设计稿就是一个目录，可以直接进 git：
* `frames/` 下的文件名就是路由和画框 ID：`login.tsx` 即 `/login`，下划线开头的文件（如 `_layout.tsx`）是共享外壳，不是画框。
* `theme.css` 存配色与圆角等令牌，画布的 **色彩系统** 面板可以查看，并把某个令牌附给 Astravia。
* `design.json` 由插件根据源码自动生成，手改会被覆盖。
* 设计稿有自己的 `package.json`，需要图表、Markdown 渲染这类库时由 Astravia 装进这份设计。
在文件树里右键 `.astravia-design` 目录，可选择 **在设计画布中打开**。
## 常见问题 [#常见问题]
* **设计引擎启动失败**：提示托管 Node 不可用时，到 **设置 → 环境管理** 安装 Node 后重试；依赖安装失败通常是网络问题。
* **风格库打不开**：风格库从线上资源仓库加载，离线时不可用，可以先新建空白设计。
* **画框显示构建失败**：源码有错误，把这个画框交给 Astravia 让它按报错定位修复。
* **画廊里看不到设计**：确认 `.astravia-design` 目录在项目根目录一层，且项目未归档，然后点 **刷新**。
* **卡片没有封面**：刚 clone 或刚导入、还没在本机打开过画布的设计没有封面，进去开一次画布即可。
---
# 使用桌宠 Astravia Vivi
> 在设置中显示桌宠、调整置顶与气泡样式。
Canonical page: /product/desktop-pet
Astravia Vivi 是独立的透明桌面窗口，可展示状态反馈与节日气泡样式。它不是另一个 Agent 会话；重要任务仍在主窗口确认。
入口：**设置 → Astravia Vivi**。
## 显示与窗口 [#显示与窗口]
| 设置 | 说明 |
| ----- | ----------------------- |
| 显示桌宠 | 关闭后隐藏桌宠窗口，并在下次启动时保持隐藏 |
| 保持在最前 | 开启后浮在其他窗口上方；关闭后可被其它窗口遮挡 |
按住桌宠可拖动。指针在桌宠图像上时，滚轮可调整当前动作显示尺寸（不同动作可能记住各自尺寸）。图像外的透明区域会尽量穿透鼠标事件，减少挡操作。
## 会话状态反馈 [#会话状态反馈]
Astravia Vivi 会跟随当前会话显示思考、工作、等待输入、完成、出错和暂停等状态。需要你回答问题、确认计划、授权权限或完成 MCP 配置时，桌宠会保持等待提示；完成会短暂展示后回到待机，错误则保持到下一轮开始，避免错过重要结果。
为了避免短时间内快速闪过多个动作，连续状态变化会合并为最新状态，每个已经显示的状态至少保持约 3 秒。关闭待机时的自动动作切换不会关闭会话状态反馈。
## 气泡样式 [#气泡样式]
在 **气泡样式** 中选择对话气泡外观，选择后立即应用到桌宠窗口。内置包括普通气泡以及春节、端午、中秋、圣诞等节日样式（以客户端列表为准）。
## 开发调试 [#开发调试]
**调试边框** 用于显示窗口边界、视频区域边界及尺寸信息，仅建议开发诊断时开启。
当前设置页主要暴露：显示桌宠、保持在最前、气泡样式与调试边框。其它内部字段（如装饰素材清单）可能未在界面展示，请以实际客户端为准。
## 常见问题 [#常见问题]
* **挡住工作内容**：关闭「保持在最前」，或拖到屏幕边缘。
* **太大或太小**：指针放在桌宠图像上滚动调整。
* **启用后看不见**：关闭再开启显示；检查是否在其它显示器或屏幕外；确认 Astravia 主进程仍在运行。
* **气泡不更新**：确认已选有效气泡样式，并从主窗口触发会更新状态的操作。
---
# 配置 IM 渠道
> 在设置 → Claw 中配置 IM 渠道，选择绑定、凭证或本机权限，并完成连接验证。
Canonical page: /product/im
消息渠道配置位于 **设置 → Claw** 的 **消息渠道** 区域。当前客户端注册了八种传输渠道；不同渠道的接入方式、平台限制和成熟度不同。同一时间只有一个 **活动渠道**，切换前请确认旧渠道上的任务已结束。
完成渠道配置后，阅读 [Astravia Claw](/product/claw/) 了解总开关、对话模型与会话命令。
## 渠道总览 [#渠道总览]
| 渠道 | 接入方式 | 适用平台或前置条件 | 当前说明 |
| -------- | ----------------------------- | ---------------------------------------- | ----------- |
| 飞书 | 扫码接入，或填写 App ID / App Secret | 飞书开放平台与组织权限 | 稳定入口 |
| 微信 | QR 绑定 ClawBot | 使用微信扫描并保持 Astravia 运行 | 稳定入口 |
| Telegram | Bot Token | 需要在 BotFather 创建机器人 | 可用，按客户端表单为准 |
| Slack | Bot Token + App Token | 需要 Socket Mode 与对应 scopes | 可用，按客户端表单为准 |
| Discord | Bot Token | 需要开启 Message Content Intent | 可用，按客户端表单为准 |
| Signal | 托管 QR 绑定，或高级 endpoint/account | 托管模式会使用 signal-cli；高级模式需本机服务 | Beta |
| WhatsApp | QR 绑定 | 需要在 Astravia 中完成扫码并保持桌面运行 | Beta |
| iMessage | 本机 Messages 数据库与系统权限 | 仅 macOS，需要 Full Disk Access 与 Automation | Beta |
“可用”表示客户端和网关已提供对应配置与传输实现，不代表第三方平台的账号审核、网络可达性或 API 配额由 Astravia 保证。遇到渠道未出现在当前版本界面时，以客户端实际列表为准。
## 配置飞书 [#配置飞书]
在 **设置 → Claw** 的飞书卡片点 **扫码接入**，用飞书扫一扫，在弹出的页面上确认一下，机器人就建好了。
1. 点击飞书卡片上的 **扫码接入**。
2. 用飞书扫码，在页面上确认应用名称与权限。
3. 提示创建成功后，Astravia 会自动把活动渠道切到飞书并连接。
4. 在飞书里搜索机器人的名字，直接私聊发一条消息试试。
如果公司限制自助创建应用，可以让管理员在飞书开放平台建好机器人，把 App ID 与 App Secret 给你，用扫码对话框底部的 **手动填写 App ID / App Secret** 填进来。
机器人只在私聊里工作，账号信息只保存在这台电脑上（`~/.astravia/desktop-app/im-credentials.json`）。收不到消息时依次检查：Claw 总开关是否打开、活动渠道是不是飞书、Astravia 是否还在运行。
## 绑定微信 [#绑定微信]
微信渠道接的是腾讯的 **ClawBot** 机器人：绑定后在微信里和 ClawBot 单聊，它不接管你的个人号，也不处理群聊。
1. 在 **设置 → Claw** 打开微信卡片上的 **绑定** / **管理**。
2. 用微信扫描二维码并确认授权。
3. 绑定成功后把活动渠道切到微信，在微信里打开 ClawBot 发送测试消息。
4. 更换账号时先 **解除绑定**，再重新扫码。
二维码过期时刷新重试。绑定成功但无回复时，检查 Claw 总开关、活动渠道、网络、对话模型与实时日志。
## 配置其它渠道 [#配置其它渠道]
其它渠道都从 **设置 → Claw → 消息渠道** 的对应卡片进入。不要把一个渠道的凭证填到另一个渠道：
* **Telegram**：从 BotFather 获取 Bot Token；可按界面提示限制允许的用户。
* **Slack**：同时填写 Bot Token 和 App Token，并在 Slack 应用中启用 Socket Mode 及所需 scopes。
* **Discord**：创建 Bot，开启 Message Content Intent，再把 Token 填入 Astravia。
* **Signal**：默认优先走本机托管的 QR 绑定；只有使用外部 signal-cli 服务时才填写 endpoint 与 E.164 account。
* **WhatsApp**：点击绑定并扫描二维码；会话状态由网关保存，解除绑定后再更换账号。
* **iMessage**：在 macOS 系统设置授予 Astravia 访问 Messages 数据与自动化控制的权限；它不需要 Bot Token。
保存后使用 **测试连接** 或发送一条最小私聊消息。结构校验通过不等于第三方服务已经接受消息；连接状态、实时日志和目标 IM 中的实际回复才是最终验收证据。
## 安全与恢复 [#安全与恢复]
* Bot Token、App Token、App Secret 和 OAuth 状态都视为凭证，只在设置页填写，不要放进任务、项目文件或诊断包。
* 切换活动渠道前先停止或等待当前 Claw 任务，避免把回复发到错误渠道。
* 解除绑定只清理对应渠道的绑定状态；需要彻底清理时，还要按客户端提示处理网关的本地状态目录。
* 任何渠道无回复时，先检查 Claw 总开关、活动渠道、Astravia 是否仍在运行、对话模型和实时日志，再缩小到渠道本身。
---
# 使用知识库
> 导入本地资料、配置后台加工，并在会话中检索整理后的知识。
Canonical page: /product/knowledge-base
知识库用于保存需要长期复用的资料。侧栏 **知识库**（可能带 **BETA** 标识）管理文件与目录结构；**设置 → 知识库设置** 控制后台加工模型与节奏。
页面说明：以熟悉的文件与目录结构管理资料，新增内容会自动完成整理。使用知识库会消耗较多 Token。
## 开启知识库 [#开启知识库]
若页面提示 **知识库尚未开启**：
1. 点击 **开启知识库**，或前往 **知识库设置**。
2. 在设置中打开总开关，并选择 **处理模型**（可带推理档位）。
3. 使用 **测试连接** 验证模型可用。
未选择处理模型时，自动整理无法正常工作。
## 导入资料 [#导入资料]
在知识库页面：
1. 使用默认库，或 **创建知识库** / **查看全部** 管理多个库。
2. **拖入文件或文件夹**，或通过添加资料入口导入。
3. 在文件列表中查看待加工状态与整理结果。
4. 回到会话提问时，明确依赖知识库中的内容，并核对答案是否可追溯。
优先导入结构清晰、可提取文本的资料。扫描版 PDF 等可能需要额外 OCR 能力；超大目录建议按主题拆分。
## 后台加工设置 [#后台加工设置]
入口：**设置 → 知识库设置**。
| 项 | 说明 |
| ------- | ----------------------------------------- |
| 启用 | 关闭后停止后台整理与相关检索行为 |
| 多久整理一次 | 可选 3 / 5 / 10 / 30 分钟，或永不自动整理 |
| 同时整理几批 | 并发批次数（如 1 / 2 / 3 / 4 / 6 / 8），越高越快，也更占配额 |
| 整理用哪个模型 | 用于整理的模型与推理档位（未选则自动整理不跑） |
| 测试连接 | 探测当前处理模型是否可用 |
| 马上整理 | 主动触发一轮扫描整理 |
| 重试失败文件 | 解除失败暂停并重新整理 |
| 整理记录 | 打开加工历史（活动面板等入口） |
| 清空 wiki | 删除已生成的整理结果与整理记录，**保留原始资料**；之后会再全量整理 |
## 会话中使用 [#会话中使用]
开启并完成整理后，对话中的知识库检索能力可按会话状态使用。活动面板可提供 **知识库加工历史** 便于核对过程。
## 相关页面 [#相关页面]
---
# 配置 MCP 连接器
> 在能力页添加推荐或自定义 MCP，并管理凭证与自动批准。
Canonical page: /product/mcp
MCP 让 Agent 调用外部工具与数据源。在桌面端，MCP 通过侧栏 **能力** 管理（「连接」分组、推荐项，以及 **添加能力 → 手动添加 MCP**）。设置页侧栏不再单独挂载 MCP 页签。
配置文件：`~/.astravia/agent/mcp.json`（全局）。OAuth 凭证可能额外保存在 `~/.astravia/agent/mcp-auth/`。
全局 MCP 连接会在应用启动后预热并跨会话复用。项目 `.astravia/mcp.json` 中的连接、引用 `${PROJECT_ROOT}` 的全局连接，以及设置了 `"resourceScope": "workspace"` 的全局连接仍按工作区隔离，并可使用当前工作区的 MCP roots。依赖 `roots/list`、但配置文本里没有 `${PROJECT_ROOT}` 的全局连接，应在高级 JSON 配置中显式设置 `resourceScope` 为 `workspace`。
## 添加推荐 / 发现中的 MCP [#添加推荐--发现中的-mcp]
发现列表中的推荐连接器来自内置预设与市场数据。当前代码中标记为可在发现列表展示的内置示例包括（以你安装的客户端版本为准）：
* **Notion**（远程 HTTP，浏览器 OAuth）
* **Figma**（stdio + API Key）
* **GitHub**（远程 HTTP + Personal Access Token）
其它预设可能已内置匹配逻辑但未在发现列表展示。
### 选择连接器 [#选择连接器]
在 **能力 → 发现** 中打开 MCP 详情。
### 完成凭证或授权 [#完成凭证或授权]
按提示填写密钥，或完成浏览器授权 / 设备码流程。未完成配置前状态为 **需配置**。
### 在会话中验证 [#在会话中验证]
保存并启用后，在对话中让 Agent 列出或调用相关工具。
## 手动添加 MCP [#手动添加-mcp]
**添加能力 → 手动添加 MCP**，传输类型：
本地进程：填写 **命令**、**参数**，可选环境变量与工作目录。
配置落盘形态示例（键名即服务名）：
```json
{
"mcpServers": {
"my-tools": {
"command": "node",
"args": ["./tools/server.mjs"],
"env": {
"TOKEN": "..."
}
}
}
}
```
远程服务：填写 URL，可选 Headers、OAuth 相关字段（如预注册 `oauthClientId`、设备码流等，以表单为准）。
```json
{
"mcpServers": {
"my-api": {
"type": "http",
"url": "https://example.com/mcp",
"headers": {
"Authorization": "Bearer ..."
}
}
}
}
```
## 自动批准与排错 [#自动批准与排错]
* **自动批准工具**：手动/高级配置中可按工具名（逗号分隔）写入自动批准列表，跳过对应工具的逐次确认。只应对行为可预测、输入范围受控的工具启用。
* 连接失败时检查：命令是否可执行、工作目录、环境变量、HTTP URL、认证状态、启动超时。
* 可对已添加项 **编辑配置**、**连接账户 / 断开账户**（OAuth）、**停用** 或 **移除**。
第一次验证连接时先使用只读工具，并让 Agent 报告它实际看到的工具名和结果：
```text
先列出当前会话中来自 [连接器名称] 的可用工具，不执行任何写操作。
选择一个只读工具做最小调用，并报告工具名、关键参数和结果摘要。
如果没有发现工具、需要额外授权或只有写入工具，请停止并说明当前连接状态。
```
连接成功不等于每个工具都应自动批准。确认工具行为、参数范围和数据边界后，再考虑对稳定的只读调用启用自动批准。
不要把令牌写入会提交到仓库的项目文件。优先在应用表单中填写；需要共享配置时使用环境变量或本机密钥管理，并脱敏后再排错。
---
# 配置模型
> 在设置中添加预设或自定义服务商、登记模型并选择默认与思考档位。
Canonical page: /product/models
模型配置决定普通会话、知识库加工、批量任务、自动化和 Claw 等路径可用的模型。入口：**设置 → 模型配置**。
配置文件路径：`~/.astravia/agent/models.json`（开发隔离环境可能使用 `ASTRAVIA_CONFIG_DIR` 指向的目录）。
## 思考模式 [#思考模式]
页面顶部的 **思考** 为全局设置，对所有会话立即生效。可选：关闭、极低、低、中、高、极高。模型不支持时客户端会自动降级。
## 添加服务商 [#添加服务商]
当前内置预设包括（以应用实际列表为准）：
* Claude
* OpenAI
* DeepSeek
* Z.ai (GLM)
* Kimi
* Grok
* Qwen
* Gemini
### 选择预设 [#选择预设]
在 **预设服务商** 区域选择目标服务商。
### 填写 API Key [#填写-api-key]
按服务商要求填写密钥。占位提示支持 `sk-...` 等形式。
### 拉取或添加模型 [#拉取或添加模型]
使用 **从接口拉取** 勾选模型并添加，或手动 **添加模型**（模型 ID、显示名、输入能力、上下文窗口、最大输出、是否支持推理等）。
### 设为默认 [#设为默认]
在模型列表中将常用模型 **设为默认模型**。
使用 **添加服务商**，至少配置：
* 服务商名称
* API 类型
* Base URL
* API Key（可用 `env:VAR` 或 `cmd:...` 等形式，以界面说明为准）
* 可选：自定义 Headers、是否用 Authorization Header 发送 Key
手动登记模型时，**模型 ID 必须与上游接口一致**。能力标记错误可能导致客户端发送供应商不支持的参数。
填写 Base URL 后可 **从接口拉取** 模型列表（若该协议支持）。
下面只展示字段关系，域名和模型 ID 是虚构占位，不能直接调用：
| 字段 | 示例值 | 核对重点 |
| -------- | ---------------------------- | --------------------- |
| 服务商名称 | `团队代理服务` | 只用于本机识别 |
| API 类型 | `OpenAI Compatible` | 必须与上游协议一致 |
| Base URL | `https://api.example.com/v1` | 核对是否应包含 `/v1` |
| API Key | `env:TEAM_MODEL_KEY` | 环境变量需在 Astravia 进程中可见 |
| 模型 ID | `team-model-id` | 使用接口接受的精确 ID，不是显示名 |
远程目录中的模型（若账号已登录且组织提供）可在列表中刷新获取，与本地服务商并列展示。
## 验证配置 [#验证配置]
### 会话探测 [#会话探测]
新建会话并显式选择该模型，发送一条短消息。
### 知识库探测 [#知识库探测]
若用于知识库加工，到 **设置 → 知识库设置** 选择处理模型后点 **测试连接**。
常见失败原因：Base URL 路径多写或少写、模型 ID 不存在、密钥无效、账户无权限、代理拦截、网络不可达。
新建会话能够显式选择该模型，并完成一条短消息。
切换默认模型后，新会话显示预期选择。
模型能力标记与上游实际支持一致，没有依赖自动猜测。
知识库、自动化或 Claw 使用的模型已在对应入口单独验证。
配置文件和诊断信息中没有要提交到仓库的真实密钥。
不要把含密钥的 `models.json` 提交到仓库或粘贴到问题报告。需要排查时可在设置中导出诊断包（不含让你主动泄露密钥）。
---
# 使用指南概览
> 按任务选择模型、能力、知识库、批量任务、自动化与扩展。
Canonical page: /product/overview
先跑通一次普通会话
按目标选择执行方式，而不是按功能菜单
能力、知识和自动化是一次成功任务的延伸
Astravia 桌面端将 Agent、项目上下文和本机工具整合在一个工作空间中。以下按「要完成什么」组织，不要求先理解内部架构。
第一次使用时，先阅读[理解 Astravia 的工作方式](/core/overview/)；它解释工作区、会话、工具和结果之间的关系，避免把 Astravia 当成只生成答案的聊天框。
## 开始工作 [#开始工作]
### 配置模型 [#配置模型]
在 [模型配置](/product/models/) 添加服务商与模型，并设为默认。
### 运行第一个任务 [#运行第一个任务]
按 [运行第一个任务](/getting-started/first-task/) 选择工作目录，写清目标与验收条件。
### 按需接入能力与资料 [#按需接入能力与资料]
需要外部工具时在 [能力](/product/abilities/) 中添加 MCP 或技能；需要长期资料时使用 [知识库](/product/knowledge-base/)。
## 选择执行方式 [#选择执行方式]
单个开放式目标，在项目会话中执行。适合第一次跑通方法和需要交互决策的工作。
同一提示处理多个文件夹，可设并发与产物校验。每个目录必须能独立验收。
单次、每天或按小时间隔调度任务；需保持应用运行。
在已配置的 IM 渠道中继续对话，桌面端保持运行。
飞书/钉钉 Webhook，供批量任务等推送通知。
用 iPhone 或 Android 继续这台电脑上的会话。Android 还可以查看并操作桌面。
按入口查找模型、权限、快捷键、环境和集成配置。
## 管理一次任务 [#管理一次任务]
选择文件边界，管理历史、分叉和项目指令。
引用材料、选择执行模式并处理权限请求。
检查待办、工具、后台任务和真实产物。
## 从指南进入完整示例 [#从指南进入完整示例]
指南解释入口、状态和边界；实战示例把这些能力组合成可以直接运行、可以验收的任务。第一次尝试某类工作时，先复制最接近的示例，再替换目录、输入来源和产物名称。
用基线、最小修改、定向测试和最终差异完成一次安全的代码修复。
从指定材料提取事实，区分证据与推断，生成可复核的 Markdown 产物。
同一任务扇出到多个目录，用固定产物规则和抽样复核控制质量。
先立即试跑，再按时间执行，并通过历史与真实文件判断成功。
## 扩展能力 [#扩展能力]
侧栏 **能力** 统一管理技能、场景、MCP、插件与套装。场景也可在独立路由 `/scenes` 中浏览（未必有侧栏一级入口）。开发向扩展见插件与主题文档。
---
# 远程连接与移动端
> 把 iPhone 或 Android 配到这台电脑，在手机上继续会话，还可以查看并操作桌面。
Canonical page: /product/remote-control
Windows、macOS 和 Linux 的桌面端都有「设置 → 远程连接」
手机上看的是这台电脑上的会话，内容端到端加密
二维码、连接码和密码只交给要配对的那部手机
远程连接让手机跟着这台电脑上的工作走：能看到「对话」和已打开项目里的会话，包括你在电脑上发起、正在跑的任务，也可以继续追问、回答提问或新建会话。中继只转发密文，不保存会话内容。
屏幕控制是另一件事，按每部已配对的手机单独开关。
以前用旧协议配过的手机不能继续用，需要重新配对一次。
## 前置条件 [#前置条件]
* 电脑上的 Astravia 能打开 **设置 → 远程连接**。三个桌面系统都有这个入口。
* 手机安装了能和这台电脑对话的 Astravia。iPhone 需要 iOS 26 或更新系统；Android 使用当前的 Astravia 客户端。
* 同一 Wi-Fi 可直连。不在同一网络时，需要打开 **允许在外网访问**，手机和电脑都能连上所配置的中继。
* 配对前看一眼屏幕上没有不该出现在手机里的内容。手机旁边的电脑图标右下角是绿色对勾时，这部手机能看到整块桌面。
## 配对 [#配对]
打开 **设置 → 远程连接** 后，页面会自动准备二维码，旁边写着大约多少分钟后更新。默认大约 10 分钟，过期、被用掉或点 **刷新** 之后会立刻换一张。一张二维码只给第一部扫到它的手机。
### 在电脑上打开配对页 [#在电脑上打开配对页]
进入 **设置 → 远程连接**。系统安全凭据存储不可用时，页面会直接说明暂时无法配对，而不是给出一张无效二维码。
### 在手机上完成其中一种方式 [#在手机上完成其中一种方式]
| 方式 | iPhone | Android | 什么时候用 |
| ------ | ------ | ------- | ---------------------------------------- |
| 扫描二维码 | 可以 | 可以 | 手机就在电脑旁边 |
| 连接码和密码 | 可以 | 可以 | 人不在电脑旁。电脑上是 8 位连接码和 6 位密码，手机选 **用连接码连接** |
| 手动输入地址 | 可以 | 可以 | 同一 Wi-Fi。填电脑显示的地址，两端会出现同一个 6 位验证码 |
连接码需要 **允许在外网访问**，并且当前中继支持连接码。不满足时电脑只保留二维码，并说明连接码暂不可用。手动输入地址只能在同一局域网内进行；访客网络常常隔开设备，这时改用扫码或连接码。
### 核对验证码后再放行 [#核对验证码后再放行]
手动输入地址时，电脑会出现 **等待你放行的手机**。手机上的 6 位验证码必须和电脑上的一致，再点 **允许这台手机**。不一致就点 **拒绝**。
任何手机接入都会在电脑上弹出系统通知。不是你操作的，到 **远程连接** 里解除那部手机。
### 确认手机已经在线 [#确认手机已经在线]
**已配对的手机** 里出现这部设备，并显示在线方式：P2P 直连、局域网直连或云端中继。之后可以关掉配对页，手机会记住这台电脑并自动重连。
macOS 第一次让手机从局域网连入时，系统可能询问是否允许传入连接，需要允许。iPhone 第一次访问局域网还会询问本地网络权限。
## 手机上能做什么 [#手机上能做什么]
电脑在线时，手机可以：
* 查看「对话」和各个项目里的会话，包括电脑上正在跑的任务。回答会持续同步，工具调用显示成卡片。
* 继续追问、中止当前这一轮，或新建一个会话。
* 回答电脑弹出来的提问。
* 发送图片和文件，按住说话把文字填进输入框，以及切换这个会话之后使用的模型和思考强度。
电脑离线时，手机仍能翻看最近缓存的 50 个会话，但不能发消息，也不能新建会话。
手机与电脑同一 Wi-Fi 时优先直连，连不上再走中继。空闲时连接会休眠。
## 查看并操作电脑屏幕 [#查看并操作电脑屏幕]
这部手机在线、并且 **允许在外网访问** 已打开时，名称旁边有一个电脑图标。右下角是绿色对勾时，这部手机可以查看并操作桌面；是红色叉号时不可以。点一下图标即可切换，默认是绿色对勾。
打开后，手机可以进入全屏桌面：轻点、拖动、滚动和打字都会作用到这台电脑。Android 从首页或设置进入；iPhone 从首页抽屉、设置，或长按 App 图标选 **远程控制** 进入。切成红色叉号会立刻断开画面，手机仍能看会话。
只有手机打开这个页面并停在前台时，电脑才截屏；离开页面或切到别的 App 就停下，macOS 的录屏指示灯随之熄灭。这需要手机和电脑都是本版本：旧版手机连着时画面会一直开着，iPhone 也看不到旧版电脑的桌面。
在 macOS 上，Astravia 需要 **屏幕录制** 权限才能显示画面，需要 **辅助功能** 权限才能接收点按和键盘（系统设置 → 隐私与安全性）。缺哪一项，手机会直接说明，电脑上也会弹出通知，点一下打开对应的设置页。授予屏幕录制后需要重启 Astravia。
在 iPhone 上，整块屏幕像触控板一样用，画面内外都可以：单指移动光标，轻点点击，双指轻点右键，按住半秒后移动即拖动。双指捏合缩放画面，双指移动平移放大后的画面。光标跟手移动、始终可见，形态与电脑上一致（箭头、I 型、手形）；放大后只有双指才会移动画面。暂时没有滚动手势，需要时拖动滚动条。键盘上方一排补上了 Esc、Tab、方向键和 ⌃ ⌥ ⌘ ⇧：点一下作用于下一个键，连点两下锁定。**粘贴** 会把 iPhone 剪贴板里的文字打到电脑上。外接键盘的快捷键直接生效。只有远程桌面这一页能横屏。
远程画面经中继建立连接，之后在手机和电脑之间直连传输，所以只关外网访问、或手机显示离线时，电脑图标不会出现。直连建立后，会话和聊天也会走这条连接。有些网络无法直连：这时会话照常经中继使用，手机会说明当前网络看不了桌面。Agent 自己的执行模式、工具权限和确认流程不受这个设置影响。
## 外网访问和中继 [#外网访问和中继]
**允许在外网访问** 默认开启。关掉之后，手机只能在同一 Wi-Fi 下连接。
旁边的设置可以更换中继地址、先测试再保存，或恢复默认。地址要以 `wss://` 或 `https://` 开头。测试会说明这个地址能否连通、是不是兼容的 Astravia 中继，以及是否支持连接码。
更换之后，当前二维码会刷新。已经连着的 Android 会自动改用新地址。当时不在线的手机，要等下次在同一 Wi-Fi 下连上这台电脑，才会拿到新地址。电脑如果使用自建中继，用连接码配对时要在手机上打开 **电脑使用的是自建中继**，并填同一个地址。
## 安全 [#安全]
* 二维码、8 位连接码和 6 位密码都是一次性的配对材料。不要发到聊天、截图、Issue 或项目文件里。
* 会话在手机和电脑之间端到端加密。中继看不到正文。
* 手动配对必须在电脑上核对验证码。扫码只对第一部手机有效。
* 完全退出电脑上的 Astravia 后，依赖它的会话同步和远程画面都会断开。
## 解除配对 [#解除配对]
在电脑上对那一行点 **解除配对**，或在手机的电脑设置里解除。电脑上的会话都保留。
* iPhone 会清掉这部手机上缓存的会话，之后要重新配对。
* Android 会留下手机上已经同步的会话，可以继续翻看，但不再更新；重新扫到同一台电脑后会接着同步。
## 连不上时 [#连不上时]
1. 看电脑是否仍在运行，设置页有没有报错。休眠或退出都会让手机离线。
2. 二维码或连接码过期时，等它自动更新，或点 **刷新**。不要复用已经用过的码。
3. 手动输入地址失败时，确认两端验证码一致，并且手机和电脑在同一个不会隔离设备的网络里。
4. 同一 Wi-Fi 正常、出门就失败时，检查 **允许在外网访问**、中继地址，以及网络是否拦截 WebSocket。
5. 会话正常但手机没有桌面画面时，确认这部手机在线、外网访问开着，并且它旁边电脑图标的右下角是绿色对勾。缺少 macOS 权限或当前网络无法直连时，手机上会直接说明。
---
# 设置参考
> 按当前设置页查找模型、远程连接、SSH 主机、外观、权限和集成配置。
Canonical page: /product/settings
设置页按平台、账号状态和构建模式显示不同入口。找不到某项时，先确认当前系统、是否已登录，以及安装包是否包含该能力。名称以界面为准；下面使用的就是当前页面标题。
## 设置入口 [#设置入口]
| 设置页 | 主要用途 | 相关文档 |
| ------------- | -------------------------- | -------------------------------------------------------- |
| 账户 | 个人信息。只有带登录的构建、并且已经登录时才出现 | [安装、升级与数据迁移](/getting-started/installation-and-updates/) |
| 通用设置 | 应用行为、网络代理、开发者选项、引导和诊断 | [故障排查](/troubleshooting/) |
| 远程连接 | 配对手机、外网访问、按手机点电脑图标允许操作桌面 | [远程连接与移动端](/product/remote-control/) |
| 外观 | 明暗模式、语言、主题、侧栏、指针和装饰 | [主题系统](/themes/overview/) |
| Agent配置 | 个性化、图片、扩展功能和运行时 | [上下文、工具与权限](/core/context-tools-and-permissions/) |
| 模型配置 | 服务商、模型、默认项和思考档位 | [配置模型](/product/models/) |
| SSH 主机 | 登记远程主机，供添加远程项目 | [项目、工作区与会话](/core/workspaces-and-sessions/) |
| Claw | IM 总开关、渠道、模型、日志和状态 | [Astravia Claw](/product/claw/) |
| 消息推送 | Webhook 渠道和测试消息 | [配置消息推送](/product/webhook/) |
| 已归档 | 查看归档的项目和会话 | [项目、工作区与会话](/core/workspaces-and-sessions/) |
| 快捷键 | 全局快捷键和快捷面板 | 见本页 |
| 应用快照 | macOS 快捷触发和系统权限 | [使用应用快照](/product/app-snapshot/) |
| 应用环境 | 内置 Node.js、Python、Git 和镜像源 | [管理应用环境](/product/application-environment/) |
| 知识库设置 | 后台加工、模型、重试和整理记录 | [使用知识库](/product/knowledge-base/) |
| Astravia Vivi | 桌宠显示、窗口和气泡样式 | [使用桌宠](/product/desktop-pet/) |
| 权限管理 | macOS 系统权限状态 | [安全与数据边界](/reference/security-and-data/) |
| 更多选项 | 已安装插件提供的页面。插件自己的配置在各自页面里 | [使用能力](/product/abilities/) |
MCP 不在设置里。发现、安装和管理在侧栏 **能力 → 连接器**。
## 平台和构建差异 [#平台和构建差异]
* **远程连接**和 **SSH 主机**在 Windows、macOS、Linux 上都显示。
* **应用快照**和 **权限管理**只在 macOS 显示。
* **账户**需要登录。开源 serv-less 构建没有商业账户，这一页不会出现。
* 主题列表受构建开关和随应用打包的主题影响。
* 标有 **BETA** 的入口，字段和行为仍可能随版本变化。远程连接目前没有这个标记。
## 修改设置的通用方法 [#修改设置的通用方法]
1. 先在设置页改完并保存。不要把直接编辑内部 JSON 当作第一步。
2. 改完模型、MCP、IM、Webhook、SSH 或远程连接后，做一次对应的测试连接或最小任务。
3. 要迁移或诊断时，先停掉相关任务，再看[配置与数据路径](/reference/configuration-paths/)。
4. 只复制不含密钥的结构。Token、Cookie、OAuth 状态、Webhook URL、配对二维码和连接码不要进项目或问题报告。
## 常见误区 [#常见误区]
| 现象 | 正确判断 |
| -------------------------- | -------------------------------------------- |
| 系统终端的 Node、Python 或 Git 正常 | 不代表 Astravia 里的运行时或检测到的 Git 已就绪 |
| 输入了 API Key | 不代表该模型已能完成真实调用，需要单独验证 |
| 打开了插件权限 | 不代表插件代码处于安全沙箱，插件仍运行在 Desktop 界面进程里 |
| 创建了自动化 | 不代表错过的时间点会自动补跑 |
| 撤销了 IM 渠道 | 不代表第三方平台账号或本机所有状态都已删除 |
| 手机能看会话 | 不代表它一定能看到桌面。远程画面还要外网访问，以及这部手机旁边电脑图标的右下角是绿色对勾 |
设置名称、可见性和表单字段属于用户界面。脚本和集成应优先使用公开 SDK、RPC、CLI 或明确承诺的配置字段，不要依赖未公开的 DOM、内部路径或菜单顺序。
---
# 配置消息推送
> 在设置中添加飞书或钉钉 Webhook，供批量任务等场景推送通知。
Canonical page: /product/webhook
入口：**设置 → 消息推送**。用于把任务完成等事件推送到群机器人（常见为 **飞书 / 钉钉**）。凭据保存在本机（如 `~/.astravia/desktop-app/webhook-credentials.json` 一类路径）。
## 添加渠道 [#添加渠道]
在渠道列表中新增通道，典型字段包括：
| 字段 | 说明 |
| ----------- | ------------------------------ |
| 类型 | 飞书 / 钉钉等（以客户端选项为准） |
| 名称 | 列表中的显示名 |
| Webhook URL | 机器人 Webhook 地址 |
| 签名 Secret | 可选；开启加签时填写 |
| @ 相关 | 如 @所有人；钉钉可能还有 @手机号、关键词等（以表单为准） |
保存后可 **启用 / 停用**、**编辑**、**删除**，并 **发送测试消息** 验证。
## 谁会触发推送 [#谁会触发推送]
* **批量任务** 创建/编辑时若勾选 **启用消息推送**：每个子任务完成时推送一次，项目全部完成时再推送汇总。
* 其它产品能力是否推送，以当前客户端实现为准；未在界面声明的事件不要假定会触发。
## 安全 [#安全]
* Webhook URL 与 Secret 等同于写入群的权限，不要提交到仓库或公开分享。
* 测试消息会真实发到对应群，请在可接受的测试群验证。
## 相关页面 [#相关页面]
---
# 平台与能力兼容性
> 查找 Astravia Desktop、手机、远程项目和构建模式的支持边界。
Canonical page: /reference/compatibility
本文档描述当前实现的公开边界。具体下载包、构建租户和组织配置可能进一步缩小可见能力。安装后的设置页和下载页是最终判断。
## 平台矩阵 [#平台矩阵]
| 能力 | Windows | macOS | Linux | Android | iPhone |
| ------------------------- | --------- | --------- | --------- | ------- | -------------- |
| Desktop 本地工作区和 Agent | 支持 | 支持 | 支持 | — | — |
| Desktop 模型、MCP、知识库、批量和自动化 | 支持 | 支持 | 支持 | — | — |
| Desktop IM 网关 | 以当前网关制品为准 | 以当前网关制品为准 | 以当前网关制品为准 | — | — |
| SSH 远程项目 | 支持 | 支持 | 支持 | — | — |
| 应用快照 | — | 支持 | — | — | — |
| macOS 本机 iMessage | — | Beta | — | — | — |
| 手机配对并继续会话 | 作为电脑端 | 作为电脑端 | 作为电脑端 | 支持 | 支持，需要 iOS 26 起 |
| 用连接码配对 | 电脑端可生成 | 电脑端可生成 | 电脑端可生成 | 支持 | 支持 |
| 查看并操作电脑桌面 | 作为被控端 | 作为被控端 | 作为被控端 | 支持 | — |
手机行描述的是 Astravia 手机客户端。电脑三列表示这台 Desktop 能否作为配对和远程项目的一端。iPhone 可以扫码、用连接码，或在同一 Wi-Fi 里手动输入地址；它没有桌面画面。
## 构建模式 [#构建模式]
| 模式 | 主要差异 |
| ------------------ | ------------------------------------------------------------- |
| 开源 / serv-less | 无 Astravia Serv 账户、订阅和远程模型目录；使用本地会话、BYOK 与内置的 Astravia 官方能力市场 |
| 商业 / Astravia Serv | 可包含登录、组织、订阅、官方 Marketplace 和远程模型目录 |
两种模式都可以包含本地会话、插件、主题、IM 和知识库，但具体系统插件组合可能随构建 profile 和租户变化。开源版不要求登录。
## 状态含义 [#状态含义]
* **稳定入口**：普通用户可以按页面步骤使用，行为仍以当前发布版本为准。
* **Beta**：已经进入客户端或网关，但第三方依赖、平台条件或接口仍可能变化。
* **随版本变化**：已经是普通设置入口，但手机系统要求、连接码和桌面画面仍按平台区分。远程连接属于这一类，不再单独标成开发预览。
* **Internal-only**：不属于公开站点范围，不应通过猜测内部路径使用。
## 提交兼容性问题 [#提交兼容性问题]
报告平台问题时提供：
* Astravia 版本、构建来源和操作系统版本。手机问题同时提供手机系统版本。
* CPU 架构、是否使用代理或企业网络。
* 设置页是否显示目标入口，以及最后一个成功步骤。
* 已脱敏的原始错误、执行时间和最小复现步骤。
不要上传 API Key、OAuth Cookie、配对二维码、连接码、密码、Webhook URL、完整项目目录或未脱敏诊断包。涉及安全问题时，先阅读[安全与数据边界](/reference/security-and-data/)。
---
# 配置与数据路径
> 查找模型、设置、MCP、能力、会话和项目级配置，并理解各路径的所有权。
Canonical page: /reference/configuration-paths
下表中的 `~` 表示当前系统用户目录。桌面界面是首选配置入口；直接编辑文件适合开发、诊断和受控迁移。
## 全局路径 [#全局路径]
| 路径 | 内容 |
| --------------------------------- | ------------------ |
| `~/.astravia/agent/settings.json` | Coding Agent 全局设置 |
| `~/.astravia/agent/models.json` | 自定义 Provider 和模型覆盖 |
| `~/.astravia/agent/auth.json` | 登录、OAuth 或手动凭证记录 |
| `~/.astravia/agent/mcp.json` | MCP 服务配置 |
| `~/.astravia/agent/sessions/` | 按安全 cwd 组织的会话文件 |
| `~/.astravia/abilities.json` | 已安装能力索引 |
| `~/.astravia/skills/` | 用户级技能 |
| `~/.astravia/scene/` | 用户级场景 |
| `~/.astravia/plugins/` | 用户级插件 |
可以使用 `ASTRAVIA_CODING_AGENT_DIR` 覆盖 Agent 目录，但宿主、sidecar 和迁移工具必须使用同一值，避免会话和配置分裂。
## 项目路径 [#项目路径]
| 路径 | 内容 |
| ------------------------------- | -------------------------- |
| `/AGENTS.md` | 项目长期指令，供项目会话自动加载 |
| `/.astravia/settings.json` | 覆盖全局 Agent 设置 |
| `/.astravia/skills/` | 项目级技能 |
| `/.astravia/extensions/` | 项目级 Coding Agent Extension |
项目设置中的相对路径相对于 `.astravia/settings.json` 所在目录解析。项目级配置优先于全局配置。
## 修改和迁移原则 [#修改和迁移原则]
1. 优先通过 Astravia 设置页修改，确保运行时校验和关联状态同步。
2. 手工编辑前退出相关活动会话，避免与正在写入的进程冲突。
3. 不让两个进程同时写同一个会话文件。
4. 迁移时保留目录结构和文件名，不只复制单个会话正文。
5. 删除前分清原始资料、整理结果、会话历史和产物，它们的保留语义不同。
自动化工具应优先使用公开 SDK、RPC 或导出能力。除文档明确承诺的配置文件外，不要依赖未公开的内部目录结构。
---
# 文档范围与版本
> 说明公开文档的内容边界和版本策略。
Canonical page: /reference/documentation-policy
## 公开范围 [#公开范围]
本站发布产品使用、插件开发和稳定 SDK 契约。以下内容默认不公开：
* 架构决策记录和未完成方案。
* 部署拓扑、内部域名及凭据配置。
* 遥测实现、故障报告和内部验证记录。
* 尚未稳定的实验功能。
## 版本策略 [#版本策略]
当前文档描述最新发布版本。页面涉及特定版本时会在正文中明确标注；在出现需要长期维护的兼容分支前，不建立多版本站点。
## 事实来源 [#事实来源]
* 用户可见入口和文案以当前 Desktop 路由、界面和 i18n 资源为准。
* SDK、RPC、CLI 和配置字段以包公开导出、类型声明和可执行参数为准。
* `content/docs/` 是公开解释的唯一来源，不直接发布仓库内部 ADR、实施日志或验证记录。
* 示例必须使用公开入口；不能通过深度导入内部 `src/**` 让示例暂时可运行。
每次影响公开行为、配置、权限、协议或入口的变更，都应检查 `apps/docs-site/docs-coverage.json` 中对应领域并更新页面或验证状态。
## 内容类型 [#内容类型]
不同页面解决不同问题，避免把所有信息堆进一个超长入口：
| 类型 | 回答的问题 | 必须包含 |
| ---- | ------------------ | ------------------------- |
| 快速开始 | 怎样尽快完成第一次成功任务？ | 前置条件、最小步骤、预期结果、下一步 |
| 指南 | 某项能力何时使用，状态和边界是什么？ | 适用条件、操作步骤、验证方式、常见恢复 |
| 实战示例 | 一项完整工作怎样从输入走到验收？ | 起始状态、可复制任务、预期产物、验收证据、修正路径 |
| 参考 | 稳定字段、命令或合同究竟是什么？ | 精确取值、默认值、兼容边界和事实来源 |
示例中的占位路径、域名和模型 ID 必须明确标注；可执行代码只使用公开入口。页面应链接到更深层解释，而不是在快速开始和示例中复制整份参考合同。
## 发现问题 [#发现问题]
提交文档问题时，请提供页面地址、错误内容、使用的 Astravia 版本以及期望行为。不要在问题中包含访问密钥、个人数据或内部服务地址。
---
# LLM 文档入口
> 获取适合 Agent 发现、检索和一次性读取的 Markdown 文档。
Canonical page: /reference/llms
本站从同一份 MDX 内容生成面向人类和 LLM 的输出，不单独维护容易失效的文本副本。
## 可用端点 [#可用端点]
* `/llms.txt`：精简索引，包含站点说明、页面链接和摘要，适合先发现相关文档。
* `/llms-full.txt`：把全部公开页面合并为一个 Markdown 文档，适合上下文窗口足够时一次读取。
* `/<页面路径>.md`：单页 Markdown，例如 `/product/models.md`，适合按需获取最小上下文。
建议 Agent 先读取 `/llms.txt`，根据任务选择少量单页 Markdown；只有确实需要跨主题全量检索时才读取 `/llms-full.txt`。
`llms.txt` 遵循 llms.txt 社区提案的 Markdown 结构，并由 Fumadocs 页面树和 frontmatter 描述生成。页面新增、删除或改名后，重新构建站点即可同步所有 LLM 入口。
---
# 安全与数据边界
> 理解本地工作区、模型请求、凭证、MCP、插件和执行权限之间的数据流。
Canonical page: /reference/security-and-data
Astravia 以本地工作区为中心，但“本地运行”不表示所有内容永远不离开设备。模型调用、MCP 和插件可能把任务所需数据发送给你配置的外部服务。使用前应理解每条边界。
## 数据流概览 [#数据流概览]
本地工作区
项目文件、会话、知识资料、配置
→
上下文组装
任务、引用、工具结果、能力指令
→
所选模型服务
发送本次调用需要的上下文
工具可以在本地继续读取或修改文件；MCP、插件和 Webhook 还可能产生独立的外部请求。
## 各边界的责任 [#各边界的责任]
| 边界 | 可能接触的数据 | 你的检查 |
| ------------ | -------------------------- | ------------------------------------- |
| 模型 Provider | 提示词、引用内容、历史、工具结果、图片 | Provider、Base URL、模型和隐私条款 |
| 本机工具 | 工作区文件、命令输出、进程 | 沙盒或完全访问、目标路径和命令 |
| MCP | 工具参数、外部服务返回值、OAuth / Token | 服务来源、传输类型、自动批准范围 |
| 插件 | 清单声明的 UI、文件、网络或 Agent 能力 | 来源、权限、版本和启用状态 |
| 知识库 | 导入的原始资料、整理结果、检索片段 | 处理模型、导入范围和删除语义 |
| Webhook / IM | 通知内容、对话或附件元数据 | 目标地址、渠道凭证和共享范围 |
| 手机配对 | 会话正文、附件、桌面画面和键鼠输入 | 只把二维码、连接码和密码交给目标手机；不用的手机要解除配对。中继只转发密文 |
## 凭证处理 [#凭证处理]
* 只在模型、MCP、IM 或 Webhook 的专用配置界面填写凭证。
* 不把 Key、Token、Cookie 或授权码写入任务、项目文件、Skill、日志或问题报告。
* `env:MY_API_KEY` 等引用只保存变量名，但实际环境变量仍由启动 Astravia 的环境负责保护。
* 导出诊断包或会话前检查内容；不要假设所有第三方工具输出都会自动脱敏。
## 执行权限 [#执行权限]
沙盒受限模式把文件和进程访问限制在工作区能力内；完全访问允许更广的系统操作。平台无法提供沙盒时，Astravia 会显示原因，不应把“沙盒不可用”理解为已经获得等价保护。
权限请求只代表宿主正在询问是否执行动作，不代表动作来源可信。确认目标路径、命令、网络地址和可撤回性。
## 安装外部能力 [#安装外部能力]
Skill、Plugin、MCP 和外置能力仓库都属于不可信输入。只从可信来源安装，检查更新内容，并授予完成目标所需的最小权限。停用会保留安装内容；移除才会卸载对应能力。
项目文件默认留在本地，但被引用、读取后进入模型上下文的内容会发送到当前配置的模型端点。处理敏感资料前，确认 Provider 和组织策略允许该数据流。
---
# 创建主题模块
> 定义主题清单、导出 ThemeModule 并在桌面应用中验证。
Canonical page: /themes/getting-started
当前流程适用于 Astravia monorepo 中的内置或策展主题。以 `packages/themes/builtin/xianxia` 为可运行参考，并保持入口文件只负责组装主题能力。
## 定义主题清单 [#定义主题清单]
`theme.json` 至少声明身份、SDK 版本、构建入口和实际能力：
```json
{
"schemaVersion": 1,
"id": "my-theme",
"version": "0.1.0",
"sdkVersion": "^0.1.0",
"displayName": { "zh-CN": "我的主题", "en-US": "My Theme" },
"runtime": "module-federation",
"entry": "dist/mf-manifest.json",
"moduleFederation": {
"remoteName": "theme_my_theme",
"expose": "./theme"
},
"styles": ["dist/style.css"],
"capabilities": ["appearance"]
}
```
## 关键字段 [#关键字段]
清单中的能力必须反映模块真实提供的内容，入口、远程名称和 expose 必须与 Vite 配置一致。
## 导出模块 [#导出模块]
```ts
import type { ThemeModule } from "@astravia-org/theme-sdk";
const theme: ThemeModule = {
meta: {
id: "my-theme",
name: "My Theme",
sdkVersion: "0.1.0",
version: "0.1.0"
},
appearance: {
colors: {
light: { accent: "oklch(0.58 0.12 165)" },
dark: { accent: "oklch(0.72 0.1 165)" }
}
}
};
export default theme;
```
先只实现 `appearance` 并验证明暗模式，再按需要增加组件、页面或运行时。大型页面与状态逻辑放在独立模块中，入口文件只组合 `ThemeModule`。
## 构建与验证 [#构建与验证]
### 配置构建 [#配置构建]
Vite 需要暴露 `./theme`，生成 `mf-manifest.json`，并将 React、`@astravia-org/theme-sdk` 与宿主 UI 包配置为不重复打包的共享单例。
### 接入桌面应用 [#接入桌面应用]
构建后把主题接入桌面应用的策展清单。
### 运行验证 [#运行验证]
通过根目录 `bun run verify:ui:*` 流程检查加载、切换、明暗模式、窗口尺寸和主题页面。
当前没有独立 ZIP 安装步骤。主题随 monorepo 内置或策展流程发布。
---
# 主题模块能力参考
> 理解 appearance、component、region、page、runtime、host hook 和主题存储的职责边界。
Canonical page: /themes/module-reference
`ThemeModule` 是主题的公开组合合同。主题只声明自己真正提供的能力；未提供的区域继续使用默认 UI。
```typescript
import type { ThemeModule } from "@astravia-org/theme-sdk";
const theme: ThemeModule = {
meta: {
id: "my-theme",
name: "My Theme",
sdkVersion: "0.1.0",
version: "0.1.0",
},
appearance: {},
components: {},
regions: {},
pages: [],
runtime: [],
};
export default theme;
```
## 能力优先级 [#能力优先级]
同一区域的生效顺序是：
Region override
→
Component override
→
Appearance config
→
Default UI
只需要改背景、边框和颜色时停在 appearance；只替换一个按钮或列表项时使用 component；只有需要重新组合整个区域时才使用 region。
## appearance [#appearance]
`ThemeAppearance` 提供：
* `colorScheme`：主题激活时偏好的 `light` 或 `dark` 模式。
* `colors.common`：明暗模式共享的 token 覆盖。
* `colors.light` / `colors.dark`：模式专属颜色覆盖。
* `surfaces`：在宿主登记的表面槽位上增加背景图、四角图、九宫格或水平切片装饰。
appearance 不改变组件行为。表面装饰不应拦截指针事件，也不应参与内容布局。
## components [#components]
Component override 替换一个已登记的局部组件。实现必须与宿主 props 合同兼容：
* 透传 `onClick`、`disabled`、`title`、`aria-*` 和 `data-*`。
* 作为按钮、trigger 或焦点目标时转发 `ref`。
* 不依赖 Desktop 内部 atom、router、IPC 或私有 hook。
* 不吞掉默认 action，也不假设父组件未承诺的 DOM 结构。
主题可以从 `@astravia-org/theme-sdk/app-shell`、`sidebar` 等公开子路径读取 model hook，再把 model 传给官方 props-driven view。
## regions [#regions]
Region override 接管一个完整区域，可以重排默认组件、插入主题 UI 并复用 `@astravia-org/theme-ui`。它仍不拥有业务数据加载和跨领域流程。
Region props 提供稳定 model、actions 和 classNames。不要在主题中重新实现项目查询、会话切换、权限确认或 IPC。
## pages [#pages]
主题可以声明自己的页面：
```typescript
{
id: "sanctum",
title: { "zh-CN": "洞府", "en-US": "Sanctum" },
layout: "main",
component: SanctumPage,
nav: { order: 20 }
}
```
| layout | 覆盖范围 |
| --------- | ------------ |
| `content` | 保留应用壳与标准内容约束 |
| `main` | 接管主内容区，保留全局壳 |
| `app` | 使用最宽的主题页面范围 |
宿主通过固定 `/theme/$themeId/$pageId` 路由承载页面。页面 ID 在主题内稳定，标题必须提供可本地化记录。
## runtime [#runtime]
`runtime` 是主题激活期间常驻的无 UI React 组件，适合把宿主公开数据同步到主题自有状态。它通常返回 `null`。
不要用 runtime 绕过主题边界执行通用业务逻辑、访问私有 store 或持有无法清理的全局副作用。所有 effect 必须在卸载时释放。
## 主题自有存储 [#主题自有存储]
`useThemeStorage()` 提供按当前 `themeId` 隔离的 JSON 可序列化键值存储：
```typescript
import { useThemeStorage } from "@astravia-org/theme-sdk/storage";
const storage = useThemeStorage();
const value = storage.get("progress");
storage.set("progress", { score: 42 });
```
* 只支持 `null`、布尔、数字、字符串、数组和普通对象。
* 写入先更新内存缓存，再由宿主异步持久化。
* 主题不能传入任意 themeId，隔离由宿主保证。
* `clear()` 只清理当前主题的数据。
数据默认落在 `~/.astravia/desktop-app/themes//data.json`。当前主题卸载流程不会自动清理该目录。
## 包边界 [#包边界]
| 包 | 应放内容 |
| ------------------------- | ------------------------------------------------------ |
| `@astravia-org/theme-sdk` | 主题协议、registry、host facade、model hook 和 props 类型 |
| `@astravia-org/theme-ui` | 不绑定 Desktop 私有状态的表面、装饰和布局 primitive |
| 具体主题包 | 主题组件、图片、样式、页面和 runtime |
| `desktop` | 真实业务状态、IPC、router、host adapter 和默认 connected container |
主题不得导入 `@shared/*`、`@domains/*` 或 `desktop/src/**`。需要新的稳定能力时，先把窄合同加入 Theme SDK，而不是深度导入宿主实现。
## 验收清单 [#验收清单]
1. 未启用主题时默认 UI 行为不变。
2. 明暗模式、窗口尺寸和页面切换没有内容遮挡。
3. component override 保留键盘、焦点和 aria 行为。
4. region 不复制宿主数据获取或权限逻辑。
5. runtime 和订阅在停用主题时完整清理。
6. 用户可见文案走 i18n。
7. 通过仓库 `verify:ui:*` 流程验证真实桌面宿主。
主题仍面向内置或策展发布。远程主题市场、通用 ZIP 安装和卸载时自动清理存储尚未作为公开能力提供。
---
# 主题系统概览
> 使用主题模块定制 Astravia 外观、组件、页面、区域与运行时效果。
Canonical page: /themes/overview
主题模块不仅能覆盖颜色，也能替换宿主公开的组件、注册页面和提供主题运行时。它适合形成一致的完整体验；只修改明暗模式、配色或侧栏样式时，直接使用“设置 → 外观”即可。
主题可以改变整个工作区的视觉表达，但项目、会话和 Agent 业务状态仍由宿主拥有。
## 主题可以提供什么 [#主题可以提供什么]
主题通过 Module Federation 加载，React、主题 SDK 和宿主 UI 包作为共享单例。主题代码运行在桌面渲染进程内，应按可信代码对待。
## 当前发布边界 [#当前发布边界]
当前主题系统面向仓库内置或策展主题开发，尚未提供面向任意第三方的通用远程安装与市场分发流程。开发者应在 Astravia monorepo 中接入、构建并随桌面应用验证主题；不要向用户承诺可以直接安装外部主题包。
外观页的 UI 主题选择可能由功能开关控制，且只有已经随应用打包的主题才可选择。
## 下一步 [#下一步]