☰

企业官网建设流程全解析

首页 / 建站日记 / 企业官网建设流程全解析
AionUi 扩展 Agent 上下文文件实战指南：以 hello-world-extension 的 hello-coder-context.md 为例
2026/9/19 3:48:52 网站建设 项目流程

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 上下文文件的通用模板：身份 + 能力 + 准则，三者一一对应、职责清晰。

二、从上下文文件到可用 Agent：contributes/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/description：Agent 的唯一标识、展示名与描述。description会被模型用于 Agent 选择路由，应精炼地概括职责；
  • contextFile：指向 agents/hello-coder-context.md 的路径（相对于扩展根目录），即上一节解析的上下文文件——它是 Agent 系统提示词的主体；
  • presetAgentType：预设运行时类型，值为hello-stdio-agent，指向 contributes/acp-adapters.json 中声明的 ACP 适配器 ID，决定该 Agent 由哪个后端运行时驱动；
  • models：允许使用的模型白名单（此处为适配器声明的demo-model）；
  • enabledSkills：默认挂载的技能列表（此处为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 传输的 ACP（Agent 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-agent（HTTP 传输，声明endpoint: http://localhost:8080/acp、apiKeyFields用于注入HELLO_API_KEY等密钥字段、supportsStreaming: false）。两个适配器共同说明 ACP 适配器字段的要点：

  • connectionType：stdio或http，决定进程内拉起 CLI 还是访问远端端点；
  • cliCommand/defaultCliPath/acpArgs：stdio 模式下的可执行命令与参数，示例用echo --acp模拟一个最简单的 ACP 服务端；
  • healthCheck.versionCommand：运行时用于探测 CLI 是否可用的命令（echo 1.0.0），timeout: 3000为超时毫秒数；
  • supportsStreaming：是否支持流式输出，HTTP 适配器示例中为false；
  • models：该适配器暴露的模型 ID，与agents.json中models字段对应，形成"Agent → 适配器 → 模型"的闭合链路。

也就是说，一个扩展 Agent 的完整装配链是：agents.json（Agent 声明）→contextFile（提示词）→presetAgentType（ACP 适配器）→ 传输方式与模型（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 key（coder/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 上下文文件时可遵循以下实践：

  1. 保持"身份 + 能力 + 准则"三段式结构：身份一句话锚定角色归属，Capabilities 用条目式声明能力边界，Guidelines 用祈使句约束行为，使提示词既稳定又可维护；
  2. Capabilities 具体而非宽泛：Code generation and refactoring、Code review and best practices均为可执行的任务描述，避免空泛的"帮助用户"；
  3. Guidelines 可落地、可检查：Follow the project's coding standards、Explain your reasoning when making changes均是可被模型执行、也可被用户检验的准则；
  4. 与注册元数据对齐：context 文件描述的能力应与agents.json中description、enabledSkills挂载的技能保持语义一致，避免"声明能力"与"实际可用能力"脱节；
  5. 善用 Skills 分担任务方法论：把可复用的任务流程（总结、缺陷分诊）放进skills/*.md，通过enabledSkills挂载，保持 context 文件聚焦于 Agent 本体；
  6. 用 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），仅供参考

标签： 网站建设 企业官网 项目流程 UI设计 前端开发

热门文章

文章分类

标签云

网站建设 响应式设计 用户体验 SEO优化 前端开发 小程序 电商平台 性能优化

相关文章

您可能感兴趣的其他内容

终于把AI Agent讲明白了：大模型、记忆、规划、工具，到底是怎么配合的？
2026/9/19 3:45:19 网站建设

终于把AI Agent讲明白了：大模型、记忆、规划、工具，到底是怎么配合的？

这两年大家都在聊AI Agent，很多人其实还停留在“它是不是更聪明的 ChatGPT”这个理解上。 Agent和普通大模型最大的区别是能围绕目标去规划、记忆、调用工具，再一步步把事情执行完。 这组图就从定义、核心组成到Agent和 LLM的区别，帮你把整…...

阅读更多 →
π型滤波实战指南：高频纹波抑制与元件协同选型
2026/9/19 3:44:49 网站建设

π型滤波实战指南：高频纹波抑制与元件协同选型

/* MD / 富文本中的 .toc（含博客园搬家等嵌套结构）；.toc-box 在侧栏，不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p（:empty 仍占 20px），一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views …...

阅读更多 →
CANN Runtime 模型运行实例（Model RI）实战：用 aclrtSwitchStream 与 aclrtActiveStream 实现图内 Stream 条件跳转与激活
2026/9/19 3:44:33 网站建设

CANN Runtime 模型运行实例（Model RI）实战：用 aclrtSwitchStream 与 aclrtActiveStream 实现图内 Stream 条件跳转与激活

CANN Runtime 模型运行实例（Model RI）实战：用 aclrtSwitchStream 与 aclrtActiveStream 实现图内 Stream 条件跳转与激活 【免费下载链接】runtime 本项目提供CANN运行时组件和维测功能组件。 项目地址: https://gitcode.com/cann/runtime …...

阅读更多 →

需要专业的网站建设服务？

联系我们获取免费的网站建设咨询和方案报价，让我们帮助您实现业务目标

立即咨询