compozy

CompozyOS

此主体会路由到匹配的参考资料。启用工具和技能时，启动过程会包含此路由器，而不是完整的参考手册。启用工具但禁用技能时，由于无法通过原生技能读取功能获取参考资料，有能力的会话会在内联内容中保留两份完整的工具手册。由守护进程负责的标题生成会省略工具路由器，因为其职责是使用提供的输入并返回输出；其他启用工具的会话会保留相应的指南。

若要在受管理的会话中读取参考资料，请通过当前运行框架解析 compozy__skill_view，并使用下方的准确路径，调用返回的工具引用，参数为 {"name":"compozy","file":"references/<file>.md"}。加载这些参考资料所需的工具发现、描述符读取、技能读取和保留结果读取，是读取前置要求的例外。调用其他工具前，请检查实时描述符；使用 compozy__tool_search 发现可用能力。保留现有的工具授权：缺少指南不会授予或撤销访问权限，技能读取遭拒也不代表可以通过 CLI 或文件系统访问绕过策略。

如果参考资料结果被截断且包含一个制品，请通过当前运行框架解析 compozy__tool_artifact_read。将返回的制品 URI 原样作为 artifact_uri 传入，从 offset: 0 开始，并使用每次返回的 next_offset 继续读取，直到 eof。解码并拼接 data_base64 页面，以读取保留结果封套，包括其完整的结构化 content；保留显示文本中的任何删节内容。使用当前工作区范围。仅有预览并不构成完整的参考资料。如果结果中没有可用的制品，或续读请求被拒绝，请报告该参考资料不可用；不要通过 CLI 或文件系统访问绕过限制。

必需的阅读路由器

将任务与表格中的行匹配。在生成输出前，完整阅读列出的文件，除非“错误处理”部分中的有界描述符回退规则适用。它们不是附录。本文件中的内联提醒仅用于防止遗漏。

任务	必须阅读
在隔离分支上委派代码更改、检查子 Agent 的 Git/PR 事实，或交付其工作	references/native-tools.md；references/worktrees.md
启动、检查、提示、停止、恢复、压缩或调试 CompozyOS 会话和守护进程状态	references/runtime-operations.md
打开、检查、重试、诊断或恢复桌面应用；更新主机运行时和应用	references/desktop.md
检查或配置由守护进程管理的后台角色、角色诊断、内置身份或角色回退路由	references/runtime-operations.md + references/agent-definitions.md
检查、刷新、整理或配置提供商模型、运行时策略、ACP 选项、推理、Fast 或定价	references/runtime-operations.md + references/native-tools.md
读取或刷新提供商用量（订阅限额、重置时间、额度、余额），或配置其收集与许可	references/runtime-operations.md + references/native-tools.md
配置提供商身份验证，或运行提供商身份验证登录	references/agent-definitions.md + references/native-tools.md
使用 compozy mcp serve 向外部 MCP 客户端公开一个 CompozyOS 工作区	references/runtime-operations.md
通过原生工具、CLI、HTTP 或 UDS 检查、更改或监视虚拟桌面、受管理窗口或工作区布局	references/window-management.md + references/native-tools.md
打开、检查、连接到 CompozyOS 终端，在其中执行或与之交互；回答终端输入或审计终端命令	references/terminal.md + references/native-tools.md
创建或审查 CompozyOS Agent 定义、提供商默认设置、权限或 MCP 辅助进程	references/agent-definitions.md + references/tools-and-skills.md
发现或调用 CompozyOS 原生工具、检查原生工具 ID、查看技能，或选择工具而非 CLI	references/tools-and-skills.md + references/native-tools.md
列出、检查或调用命令面板命令；检查或取消待处理的面板审批	references/native-tools.md
担任协调者、任务工作者或任务审查者；阻止或恢复任务，或唤醒任务创建者	references/tasks-and-orchestration.md
将任务委派给使用其他 Agent、提供商或模型的子 Agent；读取、列出或取消子 Agent	references/native-tools.md + references/tasks-and-orchestration.md
编写、配置、运行、观察、批准或停止 CompozyOS Loop 或 Goal；使用 /goal；读取 Loop 终端结果或事件	references/loops.md + references/native-tools.md
安装、启用、更新、开发链接、构建、发布或移除扩展；管理扩展套件、密钥或钩子	references/extensions.md + references/native-tools.md
编写或搭建扩展代码：清单、权限、提供的界面、贡献的命令或命令面板条目	references/extension-authoring.md + references/extensions.md
创建或管理自动化（作业和触发器）、读取其上次运行记录，或审查建议	references/native-tools.md + references/configuration.md
创建、检查、绑定会话、退出、发布、移除或恢复工作区 worktree	references/worktrees.md + references/native-tools.md
检查或管理 Gateway 安全态势、层级界面、设备配对、连接配置文件、SSH 转发或流票据	references/runtime-operations.md + references/configuration.md
列出、选择、创建、更新、重命名、归档、取消归档、删除或重试配置文件生命周期操作	references/profiles.md + references/native-tools.md
使用 TypeScript 或 Go 客户端构建外部应用，或创建、审计、更新和撤销应用令牌	references/app-sdk.md
读取或更改 CompozyOS 配置：config.toml 键、默认值、作用域和设置应用生命周期	references/configuration.md

参考索引

• references/runtime-operations.md - 守护进程、会话、Gateway 配置文件/SSH、后台角色、运维、生命周期诊断和运行时故障排查。
• references/desktop.md - 桌面应用命令、附件与所有权、运行时和应用更新、诊断与恢复。
• references/window-management.md - 由守护进程权威管理的桌面、窗口、布局、修订版本、客户端、资源、钩子、恢复和公共接口。
• references/terminal.md - 有意激活终端、本机工具 ID、审批与共享输入、输入请求、不可信输出、日志、配置文件和平台规则。
• references/agent-definitions.md - AGENT.md 结构、保留的内置角色身份、提供方默认值、权限、类别路径、MCP 侧车和安全设置工作流。
• references/tools-and-skills.md - CompozyOS 原生工具发现、技能视图/搜索、捆绑资源、市场和 MCP 安装流程，以及管理界面的例外情况。
• references/native-tools.md - 守护进程原生工具集、稳定的 CompozyOS 工具 ID、何时检查描述符，以及在 CompozyOS 内运行的 Agent 的 CLI 后备方案。
• references/tasks-and-orchestration.md - 协调者、工作者和审核者循环、子 Agent 与生成的工作者、任务权限边界、类型化区块与解除阻塞循环断路器、唤醒创建者、完成声明、审核裁决规则和敏感数据限制。
• references/loops.md - Loop 和 Goal 的编写/操作、/goal 命令、原生工具、终端和上下文状态、审批/恢复语义、参考语法、钩子和监视行为。
• references/extensions.md - 扩展套件、安装信任、编写和开发循环、实例作用域、开发覆盖层、日志和钩子管理。
• references/extension-authoring.md - 基于代码和仅含资源的扩展编写：模板、SDK 声明、静态清单、权限、提供接口、贡献的命令、命令面板条目和结构化工作流。
• references/app-sdk.md - 外部 TypeScript 和 Go 应用、守护进程发现、提示词/事件流、本地应用令牌管理、浏览器源边界和运行时 OpenAPI。
• references/configuration.md - 分层的 config.toml 期望状态、配置文件凭据、设置应用生命周期，以及 Gateway、调度器、Loop、Goal、自动化、会话重建、角色和窗口管理器设置的键参考。
• references/worktrees.md - 工作区工作树生命周期、会话绑定、退出计划和操作、Forge 集成、清理证据和公共管理接口。
• references/profiles.md - 操作员配置文件选择、不可变的会话绑定、生命周期计划、仅限本地的变更、错误、事件和公共管理接口。

运行循环

1. 执行操作前，阅读路由器选定的每份参考文档，或符合下方有界描述符后备方案的条件。
2. 管理 CompozyOS 时，优先使用 CompozyOS 原生工具和结构化输出，而非散文、日志或直接内部访问。
3. 权限应由守护进程掌握：任务状态、审核裁决、会话生命周期、扩展生命周期、钩子和工具调用都必须使用 CompozyOS 公共接口。绝不直接编辑 SQLite 数据库、进程内部数据或生成的投影。
4. 完成变更后，通过结构化读取确认结果，而不是假定操作成功。

错误处理

如果读取必需资源失败，请使用准确的路由路径重试一次 compozy__skill_view。重试前修正 tool_not_found 或 tool_invalid_input；对于 tool_backend_failed，不更改请求并重试一次。第二次失败后，只有当一次原生调用的实时描述完整定义了所请求的操作、风险和结果处理方式时，才可继续。可见的 terminal_exec 符合单命令终端演示的条件；多步骤终端交互仍需读取 references/terminal.md。否则，停止受影响的操作并报告准确路径。保留结构化运行时错误，遵循 references/runtime-operations.md 中的诊断顺序，并以守护进程拥有的状态为准。

**在进行操作性工具调用或修改工具/技能之前，请完整阅读 references/tools-and-skills.md 和 references/native-tools.md。**可先执行发现、描述符检查、参考资料读取及其保留结果的后续操作，以加载这些指南。此文件中的目录仅用于路由。

**停止。作为协调者、工作者或审查者开展工作之前，请完整阅读 references/tasks-and-orchestration.md。**任务权限和审查判定属于运行时契约，而非提示词约定。