AionUi 扩展 Agent 上下文文件实战指南以 hello-world-extension 的 hello-coder-context.md 为例【免费下载链接】AionUi免费、本地、开源的 24/7 全天候 Cowork 应用以及适用于 Gemini CLI、Claude Code、Codex、OpenCode、Qwen Code、Goose CLI、Auggie 等的 OpenClaw | 喜欢就点star吧项目地址: https://gitcode.com/iOfficeAI/AionUi导读本篇指南以开源仓库 iOfficeAI/AionUi 中示例扩展examples/hello-world-extension的 hello-coder-context.md 为切入点系统讲解 AionUi 扩展体系中Agent 上下文文件context file的编写规范、注册流程与运行时装配原理。读完本文你将掌握如何为扩展内建的 Agent 撰写结构化的系统提示词Capabilities Guidelines 范式、如何通过contributes/agents.json把 context 文件注册为可用的 Agent、如何将其绑定到 ACP 适配器与技能Skills上以及如何借助仓库中的 e2e 测试验证 Agent 是否正确加载。一、文档定位Agent 上下文文件在扩展体系中的角色在 AionUi 的扩展模型中agents/目录存放的是为扩展内建 Agent 提供的系统提示词system prompt上下文。与通用的系统提示词不同这类文件定义了 Agent 的身份你是谁、来自哪个扩展声明了 Agent 的能力边界Capabilities约束了 Agent 的行为准则Guidelines。以 hello-coder-context.md 为例全文分为三个层次区块内容作用身份声明You are a coding agent from the Hello World extension.让模型明确自身角色归属Capabilities代码生成与重构、代码审查与最佳实践、缺陷定位与修复声明能力范围引导模型选择任务Guidelines编写干净且有文档的代码、遵循项目编码规范、变更时解释推理过程约束行为边界提升输出质量同目录下的 hello-researcher-context.md 遵循同一套结构但身份、能力与准则分别面向信息分析与总结、对比研究、数据驱动洞察印证了该格式是扩展 Agent 上下文文件的通用模板身份 能力 准则三者一一对应、职责清晰。二、从上下文文件到可用 Agentcontributes/agents.json 注册仅放置 context 文件并不会让 Agent 生效还必须通过扩展清单声明注册。注册入口位于 contributes/agents.json它把hello-coder-context.md与一个 Agent 实体关联起来{ id: hello-coder, name: Hello Coder, description: A coding agent that helps with code generation and review, presetAgentType: hello-stdio-agent, contextFile: agents/hello-coder-context.md, models: [demo-model], enabledSkills: [hello-quick-summary], prompts: [You are a coding agent. Help users write clean, efficient code.] }各字段的含义与装配路径如下id/name/descriptionAgent 的唯一标识、展示名与描述。description会被模型用于 Agent 选择路由应精炼地概括职责contextFile指向 agents/hello-coder-context.md 的路径相对于扩展根目录即上一节解析的上下文文件——它是 Agent 系统提示词的主体presetAgentType预设运行时类型值为hello-stdio-agent指向 contributes/acp-adapters.json 中声明的 ACP 适配器 ID决定该 Agent 由哪个后端运行时驱动models允许使用的模型白名单此处为适配器声明的demo-modelenabledSkills默认挂载的技能列表此处为hello-quick-summary详见第四节prompts额外的静态提示词与 context 文件内容叠加共同构成完整系统提示。从源码结构看presetAgentType是连接 Agent 声明与底层运行时的关键纽带仓库中 migrateAssistants.ts 在迁移旧版内置助手数据时正是围绕presetAgentType做归一化处理例如通过normaliseLegacyAgentId(legacy.presetAgentType, ...)将旧值映射到当前清单默认值见 migrateAssistants.ts并收集用户对presetAgentType的覆盖设置见 migrateAssistants.ts。可以推断presetAgentType是运行时解析 Agent 归属、做兼容迁移的核心标识扩展内建 Agent 通过它复用主机端已有的运行时抽象。三、presetAgentType 的底层运行时ACP 适配器绑定hello-coder的presetAgentType为hello-stdio-agent它在 contributes/acp-adapters.json 中被声明为一个使用stdio 传输的 ACPAgent Client Protocol适配器{ id: hello-stdio-agent, name: Hello Stdio Agent, description: A demo ACP adapter using stdio transport, connectionType: stdio, cliCommand: echo, defaultCliPath: echo, acpArgs: [--acp], supportsStreaming: true, icon: assets/ocean-breeze-cover.svg, models: [demo-model], healthCheck: { versionCommand: echo 1.0.0, timeout: 3000 } }同一文件还给出了对照示例hello-http-agentHTTP 传输声明endpoint: http://localhost:8080/acp、apiKeyFields用于注入HELLO_API_KEY等密钥字段、supportsStreaming: false。两个适配器共同说明 ACP 适配器字段的要点connectionTypestdio或http决定进程内拉起 CLI 还是访问远端端点cliCommand/defaultCliPath/acpArgsstdio 模式下的可执行命令与参数示例用echo --acp模拟一个最简单的 ACP 服务端healthCheck.versionCommand运行时用于探测 CLI 是否可用的命令echo 1.0.0timeout: 3000为超时毫秒数supportsStreaming是否支持流式输出HTTP 适配器示例中为falsemodels该适配器暴露的模型 ID与agents.json中models字段对应形成Agent → 适配器 → 模型的闭合链路。也就是说一个扩展 Agent 的完整装配链是agents.jsonAgent 声明→contextFile提示词→presetAgentTypeACP 适配器→ 传输方式与模型stdio/http models四者缺一不可。四、技能挂载enabledSkills 与 skills 目录hello-coder的enabledSkills指定了hello-quick-summary该技能在 contributes/skills.json 中声明并指向技能提示词文件{ name: hello-quick-summary, description: Generate a short project summary with clear bullet points, file: skills/quick-summary.md }技能正文位于 skills/quick-summary.md采用与 Agent 上下文文件同构的条件触发 输出规则结构当用户请求总结时输出 3~6 条要点每条必须包含目标goal、当前状态current status与下一步行动next action且单条不超过 20 词。同目录的 skills/issue-breakdown.md 则定义了缺陷分诊流程一句话复述问题 → 最多 3 个可能根因 → 最小验证清单。这类文件本质上是可复用、可挂载的能力单元一个技能可以被多个 Agent 通过enabledSkills复用实现Agent 负责身份与准则、Skill 负责具体任务方法论的职责分离。五、多语言i18n 目录中的 Agent 展示文案agents.json中的name/description是默认英文文案多语言覆盖放在 i18n/zh-CN/agents.json 中{ coder: { name: Hello 编码助手, description: 帮助代码生成和代码审查的编码助手 }, researcher: { name: Hello 研究助手, description: 分析和总结信息的研究助手 } }i18n keycoder/researcher与agents.json中的id语义对应默认语言由 aion-extension.json 中的i18n.defaultLocale: en-US决定。注意i18n 只覆盖展示层文案contextFile指向的提示词正文默认使用英文撰写——对追求多语言提示词的扩展可自行规划各 locale 下的 context 文件版本。六、运行时验证e2e 测试中的 ext- 前缀扩展 Agent 是否正确装配仓库中的 e2e 测试给出了可验证的观测点。在 ext-ipc-queries.e2e.ts 中测试通过 IPC 查询扩展贡献的 Agent并断言test(returns agents from extensions, async ({ page }) { const ids snapshot.agents.map((a) a.id); expect(ids).toContain(ext-hello-coder); // ... const withMeta snapshot.agents.filter((a) a._source || a._kind); });关键事实有二其一扩展贡献的 Agent 在运行时会被加上ext-前缀hello-coder变为ext-hello-coder以此与内置 Agent 命名空间隔离其二Agent 快照会携带_source/_kind等元信息说明扩展来源可被追溯。开发者在排查扩展 Agent 未出现问题时可先确认扩展已启用、agents.json语法正确再通过 IPC 查询如extensions.get-agents见 ext-ipc-queries.e2e.ts核对返回的ext-前缀 ID 与元信息。七、编写高质量 Agent 上下文文件最佳实践清单综合 hello-coder-context.md 与配套文件编写扩展 Agent 上下文文件时可遵循以下实践保持身份 能力 准则三段式结构身份一句话锚定角色归属Capabilities 用条目式声明能力边界Guidelines 用祈使句约束行为使提示词既稳定又可维护Capabilities 具体而非宽泛Code generation and refactoring、Code review and best practices均为可执行的任务描述避免空泛的帮助用户Guidelines 可落地、可检查Follow the projects coding standards、Explain your reasoning when making changes均是可被模型执行、也可被用户检验的准则与注册元数据对齐context 文件描述的能力应与agents.json中description、enabledSkills挂载的技能保持语义一致避免声明能力与实际可用能力脱节善用 Skills 分担任务方法论把可复用的任务流程总结、缺陷分诊放进skills/*.md通过enabledSkills挂载保持 context 文件聚焦于 Agent 本体用 e2e 观测验证装配以ext-前缀 ID 与_source/_kind元信息作为运行时检查点确认注册链路端到端生效。结语hello-coder-context.md虽然只有十几行却是 AionUi 扩展 Agent 体系的最小完整样例它以身份 能力 准则的轻量结构定义 Agent 人格通过contributes/agents.json注册实体、presetAgentType绑定 ACP 适配器、enabledSkills挂载技能、i18n 完成多语言覆盖最终在运行时以ext-前缀暴露给宿主。理解这条从提示词文件到运行时 Agent 的完整装配链是编写任何 AionUi 扩展内建 Agent 的第一步。【免费下载链接】AionUi免费、本地、开源的 24/7 全天候 Cowork 应用以及适用于 Gemini CLI、Claude Code、Codex、OpenCode、Qwen Code、Goose CLI、Auggie 等的 OpenClaw | 喜欢就点star吧项目地址: https://gitcode.com/iOfficeAI/AionUi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 AionUi 扩展 Agent 上下文文件实战指南：以 hello-world-extension 的 hello-coder-context.md 为例
AionUi 扩展 Agent 上下文文件实战指南以 hello-world-extension 的 hello-coder-context.md 为例【免费下载链接】AionUi免费、本地、开源的 24/7 全天候 Cowork 应用以及适用于 Gemini CLI、Claude Code、Codex、OpenCode、Qwen Code、Goose CLI、Auggie 等的 OpenClaw | 喜欢就点star吧项目地址: https://gitcode.com/iOfficeAI/AionUi导读本篇指南以开源仓库 iOfficeAI/AionUi 中示例扩展examples/hello-world-extension的 hello-coder-context.md 为切入点系统讲解 AionUi 扩展体系中Agent 上下文文件context file的编写规范、注册流程与运行时装配原理。读完本文你将掌握如何为扩展内建的 Agent 撰写结构化的系统提示词Capabilities Guidelines 范式、如何通过contributes/agents.json把 context 文件注册为可用的 Agent、如何将其绑定到 ACP 适配器与技能Skills上以及如何借助仓库中的 e2e 测试验证 Agent 是否正确加载。一、文档定位Agent 上下文文件在扩展体系中的角色在 AionUi 的扩展模型中agents/目录存放的是为扩展内建 Agent 提供的系统提示词system prompt上下文。与通用的系统提示词不同这类文件定义了 Agent 的身份你是谁、来自哪个扩展声明了 Agent 的能力边界Capabilities约束了 Agent 的行为准则Guidelines。以 hello-coder-context.md 为例全文分为三个层次区块内容作用身份声明You are a coding agent from the Hello World extension.让模型明确自身角色归属Capabilities代码生成与重构、代码审查与最佳实践、缺陷定位与修复声明能力范围引导模型选择任务Guidelines编写干净且有文档的代码、遵循项目编码规范、变更时解释推理过程约束行为边界提升输出质量同目录下的 hello-researcher-context.md 遵循同一套结构但身份、能力与准则分别面向信息分析与总结、对比研究、数据驱动洞察印证了该格式是扩展 Agent 上下文文件的通用模板身份 能力 准则三者一一对应、职责清晰。二、从上下文文件到可用 Agentcontributes/agents.json 注册仅放置 context 文件并不会让 Agent 生效还必须通过扩展清单声明注册。注册入口位于 contributes/agents.json它把hello-coder-context.md与一个 Agent 实体关联起来{ id: hello-coder, name: Hello Coder, description: A coding agent that helps with code generation and review, presetAgentType: hello-stdio-agent, contextFile: agents/hello-coder-context.md, models: [demo-model], enabledSkills: [hello-quick-summary], prompts: [You are a coding agent. Help users write clean, efficient code.] }各字段的含义与装配路径如下id/name/descriptionAgent 的唯一标识、展示名与描述。description会被模型用于 Agent 选择路由应精炼地概括职责contextFile指向 agents/hello-coder-context.md 的路径相对于扩展根目录即上一节解析的上下文文件——它是 Agent 系统提示词的主体presetAgentType预设运行时类型值为hello-stdio-agent指向 contributes/acp-adapters.json 中声明的 ACP 适配器 ID决定该 Agent 由哪个后端运行时驱动models允许使用的模型白名单此处为适配器声明的demo-modelenabledSkills默认挂载的技能列表此处为hello-quick-summary详见第四节prompts额外的静态提示词与 context 文件内容叠加共同构成完整系统提示。从源码结构看presetAgentType是连接 Agent 声明与底层运行时的关键纽带仓库中 migrateAssistants.ts 在迁移旧版内置助手数据时正是围绕presetAgentType做归一化处理例如通过normaliseLegacyAgentId(legacy.presetAgentType, ...)将旧值映射到当前清单默认值见 migrateAssistants.ts并收集用户对presetAgentType的覆盖设置见 migrateAssistants.ts。可以推断presetAgentType是运行时解析 Agent 归属、做兼容迁移的核心标识扩展内建 Agent 通过它复用主机端已有的运行时抽象。三、presetAgentType 的底层运行时ACP 适配器绑定hello-coder的presetAgentType为hello-stdio-agent它在 contributes/acp-adapters.json 中被声明为一个使用stdio 传输的 ACPAgent Client Protocol适配器{ id: hello-stdio-agent, name: Hello Stdio Agent, description: A demo ACP adapter using stdio transport, connectionType: stdio, cliCommand: echo, defaultCliPath: echo, acpArgs: [--acp], supportsStreaming: true, icon: assets/ocean-breeze-cover.svg, models: [demo-model], healthCheck: { versionCommand: echo 1.0.0, timeout: 3000 } }同一文件还给出了对照示例hello-http-agentHTTP 传输声明endpoint: http://localhost:8080/acp、apiKeyFields用于注入HELLO_API_KEY等密钥字段、supportsStreaming: false。两个适配器共同说明 ACP 适配器字段的要点connectionTypestdio或http决定进程内拉起 CLI 还是访问远端端点cliCommand/defaultCliPath/acpArgsstdio 模式下的可执行命令与参数示例用echo --acp模拟一个最简单的 ACP 服务端healthCheck.versionCommand运行时用于探测 CLI 是否可用的命令echo 1.0.0timeout: 3000为超时毫秒数supportsStreaming是否支持流式输出HTTP 适配器示例中为falsemodels该适配器暴露的模型 ID与agents.json中models字段对应形成Agent → 适配器 → 模型的闭合链路。也就是说一个扩展 Agent 的完整装配链是agents.jsonAgent 声明→contextFile提示词→presetAgentTypeACP 适配器→ 传输方式与模型stdio/http models四者缺一不可。四、技能挂载enabledSkills 与 skills 目录hello-coder的enabledSkills指定了hello-quick-summary该技能在 contributes/skills.json 中声明并指向技能提示词文件{ name: hello-quick-summary, description: Generate a short project summary with clear bullet points, file: skills/quick-summary.md }技能正文位于 skills/quick-summary.md采用与 Agent 上下文文件同构的条件触发 输出规则结构当用户请求总结时输出 3~6 条要点每条必须包含目标goal、当前状态current status与下一步行动next action且单条不超过 20 词。同目录的 skills/issue-breakdown.md 则定义了缺陷分诊流程一句话复述问题 → 最多 3 个可能根因 → 最小验证清单。这类文件本质上是可复用、可挂载的能力单元一个技能可以被多个 Agent 通过enabledSkills复用实现Agent 负责身份与准则、Skill 负责具体任务方法论的职责分离。五、多语言i18n 目录中的 Agent 展示文案agents.json中的name/description是默认英文文案多语言覆盖放在 i18n/zh-CN/agents.json 中{ coder: { name: Hello 编码助手, description: 帮助代码生成和代码审查的编码助手 }, researcher: { name: Hello 研究助手, description: 分析和总结信息的研究助手 } }i18n keycoder/researcher与agents.json中的id语义对应默认语言由 aion-extension.json 中的i18n.defaultLocale: en-US决定。注意i18n 只覆盖展示层文案contextFile指向的提示词正文默认使用英文撰写——对追求多语言提示词的扩展可自行规划各 locale 下的 context 文件版本。六、运行时验证e2e 测试中的 ext- 前缀扩展 Agent 是否正确装配仓库中的 e2e 测试给出了可验证的观测点。在 ext-ipc-queries.e2e.ts 中测试通过 IPC 查询扩展贡献的 Agent并断言test(returns agents from extensions, async ({ page }) { const ids snapshot.agents.map((a) a.id); expect(ids).toContain(ext-hello-coder); // ... const withMeta snapshot.agents.filter((a) a._source || a._kind); });关键事实有二其一扩展贡献的 Agent 在运行时会被加上ext-前缀hello-coder变为ext-hello-coder以此与内置 Agent 命名空间隔离其二Agent 快照会携带_source/_kind等元信息说明扩展来源可被追溯。开发者在排查扩展 Agent 未出现问题时可先确认扩展已启用、agents.json语法正确再通过 IPC 查询如extensions.get-agents见 ext-ipc-queries.e2e.ts核对返回的ext-前缀 ID 与元信息。七、编写高质量 Agent 上下文文件最佳实践清单综合 hello-coder-context.md 与配套文件编写扩展 Agent 上下文文件时可遵循以下实践保持身份 能力 准则三段式结构身份一句话锚定角色归属Capabilities 用条目式声明能力边界Guidelines 用祈使句约束行为使提示词既稳定又可维护Capabilities 具体而非宽泛Code generation and refactoring、Code review and best practices均为可执行的任务描述避免空泛的帮助用户Guidelines 可落地、可检查Follow the projects coding standards、Explain your reasoning when making changes均是可被模型执行、也可被用户检验的准则与注册元数据对齐context 文件描述的能力应与agents.json中description、enabledSkills挂载的技能保持语义一致避免声明能力与实际可用能力脱节善用 Skills 分担任务方法论把可复用的任务流程总结、缺陷分诊放进skills/*.md通过enabledSkills挂载保持 context 文件聚焦于 Agent 本体用 e2e 观测验证装配以ext-前缀 ID 与_source/_kind元信息作为运行时检查点确认注册链路端到端生效。结语hello-coder-context.md虽然只有十几行却是 AionUi 扩展 Agent 体系的最小完整样例它以身份 能力 准则的轻量结构定义 Agent 人格通过contributes/agents.json注册实体、presetAgentType绑定 ACP 适配器、enabledSkills挂载技能、i18n 完成多语言覆盖最终在运行时以ext-前缀暴露给宿主。理解这条从提示词文件到运行时 Agent 的完整装配链是编写任何 AionUi 扩展内建 Agent 的第一步。【免费下载链接】AionUi免费、本地、开源的 24/7 全天候 Cowork 应用以及适用于 Gemini CLI、Claude Code、Codex、OpenCode、Qwen Code、Goose CLI、Auggie 等的 OpenClaw | 喜欢就点star吧项目地址: https://gitcode.com/iOfficeAI/AionUi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考