企业官网建设流程全解析

• 人工智能
• AI Agent
• AI 应用
• 交互助手
• 本地部署
• 桌面应用
• MCP Clients

本篇技术指南以 OpenWorker 仓库中 surfaces/gui/e2e-live/fixtures/persona/e2e-tester.md 这份真实的人格清单（persona manifest）为样本，逐字段剖析 manifest 的 YAML frontmatter 格式与系统提示词正文的编写规范，并结合仓库源码（manifest 解析、注册表、安装快照、能力同意）与e2e:live冒烟测试用例，说明一个第三方人格从"本地目录安装 → 启用 → 出现在选择器 → 以该人格身份运行任务"的完整生命周期。读者读完可以掌握：如何编写一份可被 OpenWorker 合法安装的人格清单、manifest 中每个字段的取值约束与默认行为，以及这套机制如何被自动化测试当作"活体"验证对象。

一、e2e-tester.md 是什么：一份"用完即弃"的测试人格

e2e-tester.md是 OpenWorker GUI 实时端到端测试套件（e2e:live）的测试夹具。它的角色定位写得很直白——frontmatter 中的tagline与description：

tagline: Throwaway persona for the live install smoke test description: Installed by the persona-install e2e:live test; writes a file on request.

也就是说，这份人格不是给真实用户使用的产品功能，而是专门供自动化测试安装、启用并驱动其执行"写文件"这类最小任务，用来验证"人格安装 → 生命周期管理 → 会话执行"这条完整管线是否工作。它所在的目录fixtures/persona/也是测试专用目录，与仓库内置的 coworker/personas/builtin/ 下各产品化人格（appsec-worker、change-worker、security 等）在用途上有本质区别：后者是发布物，前者是测试探针。

二、Manifest 文件格式：YAML frontmatter + Markdown 正文

人格清单与技能清单（SKILL.md）采用同一种"frontmatter + markdown"的文件形态，但字段更结构化。解析逻辑在 coworker/personas/manifest.py 的_split_frontmatter()中实现：文件必须以---开头，包含 YAML 元数据块，---之后才是正文（即系统提示词）。解析是严格的——任何非法字段值都会抛出ManifestError，而不是静默生成一个残缺人格。

e2e-tester.md 的完整 frontmatter 如下：

--- id: e2e-tester name: E2E Tester icon: sparkle tagline: Throwaway persona for the live install smoke test description: Installed by the persona-install e2e:live test; writes a file on request. family: knowledge workspace: deliverable tools: - files default_permission_mode: auto ---

下面逐字段对照解析源码说明其含义与约束。

2.1id：文件系统安全的 slug

id是人格的唯一标识，会直接变成受管安装目录下的目录名和注册表键，因此被严格限制为文件系统安全的 slug：小写字母、数字、-、_，长度不超过 64 字符，且不能包含路径分隔符或..（防目录穿越），也不能含 Windows 非法字符:*?"<>|（见manifest.py中的_ID_RE正则）。若省略id，解析器会从文件名推导（如My Persona.md会被 slugify 为my-persona）。

2.2name/icon/tagline/description

这些是展示性字段：name为人格显示名（缺省时回退到id），icon是图标标识（e2e-tester 用的是sparkle），tagline显示在会话选择器的下拉项中，description用于安装时的同意摘要页与详情展示。在 persona-install.spec.ts 的测试里，测试正是靠 tagline 的独特性来定位下拉项——注释里明确说明：人格名 "E2E Tester" 在会话运行后也会出现在顶栏/侧边栏，只有 tagline "Throwaway persona" 只出现在下拉项上，因此用它作为选择器的定位锚点。

2.3family与workspace：遗留字段及其 shim 行为

family: knowledge与workspace: deliverable是旧版字段。从源码看，workspace枚举在新版本中已被忽略；family仅作为遗留 shim 存在（合法值code/knowledge，见manifest.py的VALID_FAMILIES）。shim 规则是：当新的工作区特征字段未声明时，family: code会映射到"需要文件夹门控"（requires_folder=true）的画像，让旧 bundle 保留原有门控；而family: knowledge则对应无文件夹门控的默认画像。

对 e2e-tester 而言，family: knowledge意味着其派生特征为requires_folder=false、subagents=false，而scheduling在未显式声明时默认取not requires_folder，即为true——即它不会要求用户绑定主文件夹，也不启用子代理扇出，但允许定时任务/自唤醒。

2.4tools：能力白名单

tools声明该人格可用的能力清单，解析时（_validate_tools）会与coworker/catalog.py中的CATALOG能力目录逐一比对，引用未知能力会直接报错并列出已知能力集合。e2e-tester 只声明了files一项，这与它的系统提示词（"用文件工具创建文件"）严格一致——最小权限的测试人格，不暴露 shell、git、搜索等任何多余能力。to_agent()会通过catalog.expand()把这些能力 ID 展开为真实的 Agent 工具工厂。

2.5default_permission_mode: auto：声明默认权限模式

default_permission_mode的合法值包括discuss、plan、interactive、custom、auto、bypass-approvals、auto-approve，其中auto是bypass-approvals的遗留拼写（VALID_MODES注释明确说明）。不过要注意一个重要安全设计：新安装的第三方人格并不会直接生效其声明的模式。在 persona-install.spec.ts 中有明确注释——"New sessions start in 'Ask for approval' regardless of the persona's declared mode (a safety default for freshly-installed personas)"。也就是说，即使 e2e-tester 声明了auto，新建会话仍默认处于"Ask for approval"（需要逐次审批）模式，测试必须手动切换为 "Full access" 才能让写文件任务一路跑完。这是一道面向第三方人格的强制安全默认值。

2.6 正文：系统提示词

frontmatter 之后的 Markdown 正文就是该系统提示词，parse_manifest()会校验其非空（"manifest needs anid(or a filename to derive one from)" 之外，"has no body" 同样报错）。e2e-tester 的正文只有三句话，是一个刻意最小化的提示词：

You are the E2E Tester, a persona used only by an automated live test. When the user asks you to write a file, use your file tools to create it exactly as specified, then confirm in one short sentence. Do nothing else.

它只规定了两件事：收到写文件请求时用文件工具精确创建、一句话确认；除此之外不做任何事。这保证了测试的可判定性——任务请求与人格行为之间的映射是确定性的，测试只需检查文件内容即可断言成功。

三、运行该测试人格：persona-install.spec.ts 全链路

真正"消费"这份 fixture 的是 surfaces/gui/e2e-live/persona-install.spec.ts，它属于e2e:live实时套件（区别于封闭式e2e套件，live 套件需要真实后端与真实模型，见 surfaces/gui/README.md 与 package.json 中的e2e:live脚本）。该测试被注释为"LIVE capstone"，在 CI 中排除，需手动执行npm run e2e:live运行。其断言链路对应了完整的人格管线：

1. 安装：打开 Settings ▸ Personas，选择dir安装源，填入FIXTURE_DIR（即fixtures/persona/），点击 Install，等待 "Installed N persona" 提示。
2. 启用 + 上架：在人格行上勾选 "Enabled"（启用）与 "In picker"（出现在选择器）；测试特意用了"点击并等待回勾"而非check()，因为这是受控 React 复选框，勾选会异步触发updatePersona重渲染。
3. 以该人格新建会话：离开设置页，通过 "New session" → "Choose a persona" → 按 tagline 选中 E2E Tester。
4. 权限模式切换：将新建会话从默认的 "Ask for approval" 切换到 "Full access"。
5. 派发任务并断言落盘：发送任务Write a file named <name> containing exactly: <token>，然后用expect.poll轮询 scratch 目录，等待目标文件出现且内容包含 token——以文件本身（ground truth）作为成功信号，而不是 UI 信号（注释说明非 Cowork 人格不渲染 Artifacts 栏）。

支撑测试的辅助函数在 surfaces/gui/e2e-live/helpers.ts 中：scratchBaseIfReady()通过http://127.0.0.1:8765侧车服务（带X-OpenWorker-Token认证头）检查后端可用性与模型就绪状态，未就绪则跳过测试；newestFile()跨各会话 scratch 子目录找出指定名字的最新文件——因为每个 live 会话都有自己的 scratch 目录。整体超时设置为 150 秒（轮询 15 万毫秒）。

四、安装与快照机制：manifest 如何进入受管区

测试点击 Install 后，后端调用的是PersonaRegistry.install_from_dir()（coworker/personas/registry.py），其关键行为是快照（snapshot）而非引用：把 manifest 复制到受管安装区（<state>/personas-installed/<id>/manifest.md，随行的skills/目录也会一并复制），使人格的定义与用户的源目录解耦、保持稳定自洽。重新安装同一 id 的人格会覆盖快照，且幂等。

安装返回的是每份人格的能力同意摘要（consent summary，见 coworker/personas/loading.py 的consent_summary()），内容包含：声明的工具列表、风险等级、连接器白名单、MCP 服务器、是否可发消息（由连接器推导）、team 角色、推荐权限模式、推荐模型与推荐连接等。测试中出现的 "Installed N persona" 提示背后就是这份摘要的 UI 呈现。第三方人格安装后一律先落地为"禁用 + 不上架"，直到用户在风险摘要页批准其声明能力后才被启用——测试中的勾选步骤正是模拟这一用户授权动作。

更新语义也值得注意：重装时若新旧能力集（capability_set()，含tool:*、mcp:*、connector:*、messaging、team:*等键）出现增长，会被视为"新的能力决策"，需要重新同意；能力不变或缩小的更新则保留用户已启用的状态。

五、从这份 fixture 延伸：如何编写自己的可安装人格

e2e-tester.md 本身就是一个可运行的第三方人格最小样例。参考它可以总结出编写一份合格 manifest 的检查清单：

1. frontmatter 必须合法：以---开头并有收尾---；id遵循 slug 规则；family（若用遗留写法）只能是code/knowledge；default_permission_mode必须属于VALID_MODES；connectors若是all保留给内置人格，第三方必须显式列出连接器 id（且recommends中推荐的连接器必须落在声明白名单内，否则安装时报错）。
2. 工具声明必须落在 CATALOG 内：声明未知能力会直接ManifestError。
3. 正文即系统提示词，必须非空：它决定了人格的行为契约；e2e-tester 的"最小契约"写法非常适合测试/验证场景——行为确定、边界清晰、断言容易。
4. 不要依赖声明的权限模式：新安装的人格永远从 "Ask for approval" 起步，用户需要显式授权才能切换为全访问模式。

如果希望深入探索更复杂的 manifest 形态，可以参考仓库内置的 change-worker/manifest.md（团队 worker 角色、requires_folder/subagents特征、模型白名单）与 appsec-worker/manifest.md（连接器授权 + 技能绑定），它们展示了生产级人格的完整字段组合；对应的人格清单解析、注册表生命周期与安装同意逻辑则分别在 coworker/personas/manifest.py、coworker/personas/registry.py 与 coworker/personas/loading.py 中。

六、小结

e2e-tester.md虽是一份只有十余行的"测试用一次性人格"，但它恰好是 OpenWorker 人格清单格式的完整缩影：严格的 frontmatter 解析、能力白名单校验、遗留字段 shim、权限模式声明与安装时安全默认值，再加上安装快照、能力同意、生命周期状态与 live 测试驱动，构成了一条可观察、可验证的完整人格管线。对于想要为 OpenWorker 编写或安装第三方人格的开发者，这份 fixture 连同其驱动的 persona-install.spec.ts，既是格式规范的最短示例，也是验证整条链路是否健康的最快路径。

• 人工智能
• AI Agent
• AI 应用
• 交互助手
• 本地部署
• 桌面应用
• MCP Clients