agentera

agentera

一次安装、一个入口点、一个可查询所有项目状态的接口。十二项能力集成在一个 Agentera 技能中。

---

共享协议

所有能力都引用 protocol.yaml 中定义的共享基元：

• 置信度刻度：0-100，分为五个等级，并明确界定边界
• 严重性级别：发现项和问题的词汇
• 视觉标记：状态、严重性、置信度和趋势符号
• 阶段模型：五个阶段及有效转换

各项能力按名称导入这些基元。架构契约可确保用法一致。

---

能力

	能力	主要路由	用途
⌂	hej	/agentera status	熟悉项目并进行路由
⛥	visionera	/agentera vision	明确项目方向
❈	resonera	/agentera discuss	结构化研讨
⬚	inspirera	/agentera research	外部模式分析
≡	planera	/agentera plan	制定包含验收标准的计划
⧉	realisera	/agentera build	自主开发
⎘	optimera	/agentera optimize	由指标驱动的优化
⛶	inspektera	/agentera audit	代码库健康状况审计
▤	dokumentera	/agentera document	文档编写
♾	profilera	/agentera profile	决策画像
◰	visualisera	/agentera design	视觉识别系统
⎈	orkestrera	/agentera orchestrate	多轮次编排

---

路由逻辑

收到请求时，使用决策 42 中的五层路由模型，将请求路由到相应能力。

前置条件：单次调用的已安装 CLI 检查

此检查为必需项，但检查与方向概览的数据来源是同一次已安装 CLI 调用。对于单独的 /agentera 或单独的 hej，先用单独的一条命令解析应用主目录，然后运行 prime：

RESOLVED_AGENTERA_HOME="$(uvx --from git+https://github.com/jgabor/agentera agentera app-home)"
uv run "$RESOLVED_AGENTERA_HOME/app/scripts/agentera" prime

在本地 Agentera 检出目录中，解析器可以使用 uv run scripts/agentera app-home 代替 uvx。切勿将应用主目录赋值与展开受管理应用脚本路径放在同一条 shell 命令中；否则，shell 展开可能会在赋值生效前，将未设置的 AGENTERA_HOME 转换为 /app/scripts/agentera。

按照应用主目录优先级解析 RESOLVED_AGENTERA_HOME：若已设置，则使用 AGENTERA_HOME；否则，使用 agentera app-home 返回的平台数据主目录。在 macOS 或 Windows 上，切勿以仅适用于 Linux 的 ${XDG_DATA_HOME:-$HOME/.local/share}/agentera 作为替代。调用此命令前，不要运行 glob、grep、read、ls、python、doctor、--help、registry.json 或 .agentera-bundle.json 预检。CLI 负责应用验证、v1 检测、配置文件检测、构件整理，以及告知调用方如何呈现概览的 source_contract。

如果命令成功退出，请检查 CLI 提供的 bundle.status 已安装应用状态对象。如果其值为 fresh，则在本次简报中视为已通过已安装应用检查，并根据输出呈现内容。该对象包含 expectedVersion、expectedVersionSource、appHome、managedAppRoot、userDataRoot、修复命令和审批文本。

面向用户的修复措辞

恢复和故障排除提示必须简单易懂，让非技术用户也能看明白。切勿要求用户在技术性的安装概念、内部目录状态、命令模式标记或软件包布局术语之间进行选择。这些应作为内部信息处理。 面向用户的文案必须依次回答以下四个问题：

1. 发生了什么：Agentera 找到了一个旧的或损坏的本地副本。
2. 预览执行了什么：未更改任何内容。
3. 推荐的修复会做什么：在 Agentera 的常规目录中安装一个全新的 Agentera 应用副本。
4. 修复不会做什么：不会修改你的项目文件、shell 启动文件或未知目录。 仅在无法避免选择时，才优先给出推荐选项。将安全的默认选项放在首位，并标明为推荐选项。好的标签示例：使用安全修复（推荐）、选择其他目录、停止。不好的标签示例：使用平台主目录、强制使用旧目录，或暴露内部标志和应用文件打包术语的标签。 先用通俗易懂的语言解释，之后才提及命令和路径等技术细节。

如果由于 AGENTERA_HOME 指向旧默认目录 $HOME/.agents/agentera，且 $AGENTERA_HOME/app/scripts/agentera 缺失，导致命令无法执行，请勿要求用户先尝试执行失败的 CLI 命令，也不要先要求用户取消设置 AGENTERA_HOME。请告知用户：Agentera 找到了自身的旧副本或损坏的本地副本。安全的修复方法是在 Agentera 的常规目录中安装一个全新的副本。 然后显示此预览命令，并说明它不会进行任何更改：

uvx --from git+https://github.com/jgabor/agentera agentera upgrade --dry-run

此预览不会写入任何内容。由于没有明确指定 --install-root，升级可以选择常规平台应用目录，并预览应用文件、托管运行时界面的修复，以及旧目录的清理。写入前请征求用户的明确批准，使用通俗易懂的措辞，例如 批准在 <directory> 中进行 Agentera 安全修复。获得批准后，执行同一路径的安全修复：

uvx --from git+https://github.com/jgabor/agentera agentera upgrade --yes

应用修复后，请从升级输出所报告的平台应用主目录重试已安装的命令，而不是从旧默认目录重试。如果命令能够执行，但在 argparse 之前失败、针对 prime 报告 invalid choice，或报告状态为 outdated、manual_review_needed、缺少命令或需要修复：

• 说明：Agentera 找到了自身的旧副本或损坏的本地副本。
• 说明预览是否更改了任何内容；预览命令不会进行任何更改。
• 在提及路径或命令之前，用通俗易懂的语言说明安全的建议。
• 如果存在 bundle.dryRunCommand，显示其中不需要克隆的预览命令：

uvx --from git+https://github.com/jgabor/agentera agentera upgrade --install-root "$RESOLVED_AGENTERA_HOME" --dry-run

写入前请征求用户的明确批准。只有在用户明确授权进行相同的 Agentera 修复并指定相同目录时，才可将通常的肯定答复视为批准。 如果获得批准，执行：

uvx --from git+https://github.com/jgabor/agentera agentera upgrade --install-root "$RESOLVED_AGENTERA_HOME" --yes

应用修复后，重试：

uv run "$RESOLVED_AGENTERA_HOME/app/scripts/agentera" prime

如果 AGENTERA_HOME 指向旧默认目录 $HOME/.agents/agentera，没有明确指定 --install-root，且 $AGENTERA_HOME/app/scripts/agentera 缺失或已过期，请将此情况视为可安全预览的情形，使用上述 Agentera 常规目录。不要先要求用户取消设置 AGENTERA_HOME；不要声称能够证明此环境变量值的来源。如果 AGENTERA_HOME 指向其他任何缺失的路径、文件，或包含未知文件的目录，且单条命令无法运行，请勿静默覆盖该路径，也不要回退到本地检出。请说明： Agentera 被指示使用一个无法安全使用的目录。请选择其他 Agentera 目录；或者，只有在检查确认该目录可以安全替换后，才批准使用 --force。

如果 shell 启动诊断报告存在遗留的 1.x 托管标记块（# agentera: AGENTERA_HOME (managed)），请明确说明 Agentera 不会编辑这些文件。清理工作由用户手动完成，不属于修复写入。升级不会扫描 shell 启动文件。

只有在已安装的 CLI 成功运行后，才继续执行步骤 -1 和下方的路由层。不要将本地检出作为权宜之计；上述 uvx 命令具有可移植性，且不需要本地检出。

步骤 -1：CLI 优先的顶层状态访问

agentera CLI 是访问项目状态的权威接口。日常访问应使用顶层状态命令。只有在没有常规命令能提供所需状态时，才使用 agentera query 检查高级／自定义构件。

在任何基于构件的简报、路由决策或能力状态读取之前，都要运行负责所需状态的顶层命令。上方的应用健康检查必须已确认已安装的 CLI 可用。 常规命令包括：prime、state plan、state progress、state health、 state todo、state decisions、state docs、state objective 和 state experiments。迁移期间，旧命令的顶层别名仍会保留，并通过标准错误流显示弃用提示；完整列表请参阅 audience-namespace-cli-migration.yaml。仍可通过 agentera schema --format json （带有旧版 describe 别名）进行发现和自定义检查， 也可使用 state query --list-artifacts 和 state query <artifact-name> --format json|yaml。 结构化发现包含一份资源位置约定，其中列有映射路径、 常规读取命令和原始访问边界；读取 .agentera/docs.yaml 或探查 .agentera/ 以发现路径之前， 请先使用该约定。

不要绕过 CLI，直接读取原始 .agentera/*.yaml 文件。如果 CLI 状态声明启动所需内容已完整覆盖，就不要在常规启动时执行防御性原始资源读取。如果 CLI 状态不可用或不完整， 请先尝试 CLI 提供的回退命令；只有这些路径失败或仍声明状态不完整时，才将原始资源读取作为最后的回退手段。 当 agentera state plan --format json 返回 source_contract.complete_for_plan_artifact=true 时，应将其 summary、 entries 和 source_contract 视为常规 PLAN.md 启动和评估上下文的完整内容；不要仅仅为了重新检查任务依赖项、验收标准、证据、总体验收情况、意外情况、先前计划的归档引用或计划元数据而读取 .agentera/plan.yaml。此禁止原始读取规则适用于常规只读启动和评估。对于写入、归档、验证、损坏诊断，或 CLI 回退后 CLI 状态仍不可用或不完整的情况，仍可访问映射后的原始计划资源。

当缺失的事实仅为资源路径时，优先使用 CLI 发现约定： agentera schema --format json 会公开 artifact_locations， 而 agentera state query --list-artifacts --format json 会公开相同的精简记录， 并附带 names 兼容列表。纯文本 state query --list-artifacts 仍会返回面向用户的名称列表。这些发现接口不能替代常规状态命令来读取常规资源内容。

对于单独的 /agentera 或内容恰好为 hej 的用户消息，首先运行 agentera prime，并根据该次组合结果生成 README 风格的 hej 仪表板。CLI 输出是源数据，不是面向用户的仪表板；不要将 agentera prime 的原始输出行直接作为最终简报。除非 agentera prime 失败或明确要求回退，否则不要运行单独的 state plan、state progress、state health、 state todo 或 state decisions 命令。最终回复必须 将 mode:、profile:、health:、issues:、 plan:、objective:、attention:、next_action:、app_home:、 v1_migration: 和 source_contract: 等源标签转换为下方的仪表板；绝不要在简报中原样粘贴这些标签。

单独的 /agentera 返回项目输出必须包含以下可见标记：

┌─┐┌─┐┌─┐┌┐┌┌┬┐┌─┐┬─┐┌─┐
├─┤│ ┬├┤ │││ │ ├┤ ├┬┘├─┤
┴ ┴└─┘└─┘┘└┘ ┴ └─┘┴└─┴ ┴

─── status ─────────────────────────────
  [metric lines: health, issues, plan, objective, profile as available]
  [1-2 sentence narrative read closing the status section]
─── attention ──────────────────────────
─── next ───────────────────────────────

采用 hej 第 1b 步的 README 风格布局：先展示指标，再在 status 中叙述解读，最后展示注意事项和下一步。问题摘要行按 prime 输出的顺序使用 critical · degraded · normal · annoying。仅当源内容没有注意事项时，才省略 attention。始终在仪表盘代码围栏下方包含必需的 ⌂ hej · <status> 标记，并在调用建议的下游能力前请求确认。对于 /agentera <capability-name> 或 /agentera <alias>，不要假定路由词是 CLI 命令。CLI 命令接口以状态为中心，而非以能力为中心： 使用拥有该能力所需工件的受支持常规状态命令；具体命令由该能力的工件架构声明。例如，resonera 通过 agentera state decisions 读取决策，而不是通过不受支持的能力名称命令 agentera resonera。绝不要将 agentera resonera、agentera planera 或 agentera realisera 等不受支持的能力名称命令用作引导步骤。相同词语在不同接口中的用途应保持区分：/agentera plan 路由到 planera，而 agentera state plan 从 CLI 读取计划状态。需要特定能力的启动上下文时，通过 agentera prime --context <capability> --format json 请求。直接使用返回的 capability_context.state.included；对于 capability_context.state.missing，在访问原始文件前运行列出的 capability_context.state.fallback_commands。历史 v2 路径 hej --capability-context 和 --context-profile 已在 3.0 中移除。 对于常规 ≡ planera 执行，先使用 agentera prime --context planera --format json 中的 capability_context.context.planning_context.startup_contract，再读取 skills/agentera/capabilities/planera/instructions.md。仅在编辑 Planera、解决矛盾或歧义、验证紧凑契约未涵盖的详细行为，或调查基准测试／读取触发证据时，才阅读 Planera 说明文档。这样既保留了 Planera 说明文档作为详细权威依据，也不会新增 agentera planera；/agentera plan 仍用于路由，而 agentera state plan 仍用于读取计划状态（顶层 agentera plan 是迁移别名）。 对于常规 DECISIONS.md 上下文，使用 agentera state decisions --format json 及其 source_contract。当 complete_for_normal_deliberation_context=true 时，应保留返回的 missing_fields、compacted、caveats 和 satisfaction.review_needed，而不要通过读取原始文件 .agentera/decisions.yaml 来重建缺失历史。原始决策工件访问仅限 Resonera 所属的写入／修复、工件损坏诊断或 CLI 缺陷调查。 读取某个能力的 instructions.md 文件本身不构成能力调用；能力调用是指路由到该能力、遵循其说明文档，并优先使用 CLI 状态层获取工件支持的状态。

能力交接使用字形加规范能力名称，例如 ⧉ realisera 或 ≡ planera。仅在明确说明斜杠路由时使用 /agentera <alias> 表述，不要使用 /realisera 或 /planera 等独立的斜杠能力名称作为交接标签。SG2 等 SG 优先级代码属于内部协议引用；不要将其呈现在面向用户的交接标签中。

交接动词为规范性要求：

• route：用户通过规范名称、主要别名或斜杠路由直接调用了某项能力。这表示用户同意调用该能力；不要再询问是否需要额外确认交接。
• suggest：推荐一项下游能力，并等待用户确认。
• handoff prompt：询问用户是否运行建议的能力。对于多选提示，以及单个会改变状态的继续／取消交接，请使用原生问题工具。会改变状态是指建议的下一步可能会写入制品、编辑代码、运行优化或编排周期、应用迁移、刷新应用／运行时状态，或以其他方式更改项目／运行时状态。优先遵循行为规则，并参考以下常见示例：创建或更新计划时使用 ⧉ realisera、≡ planera；编写文档时使用 ▤ dokumentera；运行或应用优化周期时使用 ⎘ optimera；调度周期时使用 ⎈ orkestrera。单个不会改变状态的建议可以使用自由格式提示；对于 yes、start、do it 或 run <capability> 等明确回复，视为确认所提议的能力。回复含糊时，提出一个澄清问题。
• dispatch：仅当当前能力明确负责该编排流程时，才自主调用另一项能力。
• chain：仅在明确编排的流程中自主调用多项能力；否则，建议下一项能力并等待确认。

在全新交互中，Agentera/hej 的首次回复应提供简要说明和自由格式的后续提示，而不是原生问题菜单；除非用户明确要求限定选项，或建议的下一步属于会改变状态的继续／取消交接。在对话过程中，仅当存在至少两个有意义的非终止后续操作，或需要做出影响重大的继续／取消决定时，才使用运行时的原生问题工具；即使只建议一个操作，会改变状态的能力交接也属于影响重大的继续／取消决定。不要将 Done 或自由格式／自定义回答选项计作替代选项。目前宿主示例包括 Claude Code 的 AskUserQuestion、Copilot 的 ask_user、Codex 的 request_user_input 和 OpenCode 的 question。将推荐选项放在首位，并在其标签中加入 (Recommended)，同时包含 Done。选择下游能力选项即表示确认调用该能力；选择 Done 则停止，不进行路由。这项通用的问题工具使用条件适用于 hej 和能力交接提示。调用某项能力后，是否必须使用运行时原生问题工具，则由该能力自身的交互规则决定。

步骤 0：V1 迁移处理

在正常的 prime 简报之前，不要单独查找 v1 Markdown/YAML 文件。 顶层 CLI 负责检测 v1。对于不带参数的 /agentera 或不带参数的 hej，请从 agentera prime 呈现任何 v1 artifacts detected 提醒项和受影响文件列表；不要额外调用工具来搜索 .agentera/*.md、.agentera/*.yaml 或 VISION.md 通配模式。

如果 CLI 报告存在 v1 状态，请使用它提供的 v1_migration.dry_run_command 预览。 任何应用命令之前，都必须先进行不写入的预览。告诉用户预览不会更改任何内容，然后在应用前征求确认。只有获得确认后，才能运行 v1_migration.apply_command。 绝不要根据存在 v1 文件就推断用户已同意。 预览命令的形式为 uvx --from git+https://github.com/jgabor/agentera agentera upgrade --project "$PWD" --dry-run 或者在 CLI 提供本地检出版本时，使用 uv run scripts/agentera upgrade --project "$PWD" --dry-run。 不要用手动检查文件、手写迁移步骤或直接读取 YAML 来替代由 CLI 负责的预览。只有应用步骤需要确认。

升级命令具有幂等性。通过 uvx 调用时，它会安装或更新 Agentera 应用文件、迁移 v1 文件、将运行时配置关联到该应用目录，并移除可修复的过时 v1 运行时文件。 文件迁移阶段会在预览并确认后，将受支持的 v1 Markdown 文件迁移为 YAML，并创建备份。执行 npx skills remove 删除 v1 技能条目并执行 npx skills add 添加 /agentera 的软件包刷新，必须通过 --update-packages 显式选择加入。单独运行 npx skills update 只会更新当前可见的技能；如果此后 /agentera 发现应用文件缺失或过时，请运行上文的普通语言修复预览，让升级更新应用，并在旧默认目录可恢复时将其清理。

第 1 层：不带参数的 /agentera 或 hej — 委托给 prime

如果请求是没有附加文本的 /agentera，或完整的用户消息恰好是 hej，请立即委托给 hej。Hej 会通过 agentera prime 组合结果，根据状态进行路由；该结果会汇总项目文件，并建议最有用的下一项能力。这种方式具有确定性，且绝不会出错。不得将不带参数的 hej 当作一般问候语处理。

第 2 层：能力名称或 /agentera <primary-alias> — 直接路由

如果请求文本与某个能力名称完全匹配（不区分大小写，例如“resonera”“planera”“hej”），请直接路由到该能力，不要评估自然语言触发模式。规范的瑞典语名称是协议标识，绕过自然语言匹配。

如果请求以规范能力名称开头，后面还有其他文本，或者使用 /agentera <capability-name> <topic>，请直接路由到该能力，并将剩余文本作为用户的主题或指令传递。例如，resonera decide whether to keep this API 会调用 ❈ resonera；不得给出通用分析回复，也不得尝试不受支持的 CLI 命令 agentera resonera。

如果请求文本与 capability_schema_contract.yaml 中 ROUTE_ALIASES.primary_aliases 的某个主别名完全匹配，请直接路由到该别名对应的能力，不要评估自然语言触发模式。每项能力恰好有一个主别名。次要用户措辞仍由本层以下的能力触发架构处理。例如：deliberate、brainstorm 和 rubber duck 仍是 resonera 的触发措辞；brief 和 what's next 仍是 hej 的触发措辞。这些都不是主别名。

第 3 层：高置信度匹配的自然语言

如果请求是自然语言（例如“帮我理清这件事”），请评估能力触发架构，并在架构所定义的语义产生高置信度匹配时进行路由。

第 4 层：边缘匹配 — 消歧

如果由架构所有的路由语义产生多个相互竞争的边缘匹配，请展示消歧提示，而不是悄然做出选择。列出匹配的能力及其简短说明，并请用户确认或澄清。

第 5 层：无匹配 — 回退到 hej

如果没有任何能力以足够的置信度匹配，则路由到 hej 进行引导。Hej 负责处理问候、状态请求和含糊不清的输入。

触发模式发现

第 3–4 层的触发词到能力映射根据各能力的 schemas/triggers.yaml 推导得出，而非在此处硬编码。模式匹配、优先级、阈值、回退和消歧元数据均归属于这些触发器架构和能力架构契约。这样，路由层便可专注于将请求路由到能力；能力目录和架构仍是详细接口的信息来源。

---

安全护栏

- 未经用户明确指示，绝不推送到远程仓库 - 在执行周期中绝不修改 `.agentera/vision.yaml` 或目标状态（只有用户或所属能力可以更改这些内容） - 绝不将机密或凭据提交到任何制品或文件 - 遵循制品路径解析规则：访问任何面向 Agent 的制品前，先检查 `.agentera/docs.yaml` 是否覆盖了路径

---

退出信号

所有能力均使用 protocol.yaml 中 EXIT_SIGNALS 定义的退出词汇。能力的 schemas/exit.yaml 文件引用该协议权威定义；路由层不会维护单独的退出信号表。

---

跨技能集成

十二技能套件已合并为一个 Agentera 技能。每项能力的架构都使用稳定 ID 定义跨能力制品引用。跨能力路由通过「路由逻辑」部分所述的能力触发器架构处理。各能力从同一制品存储区读取数据并写入其中（面向 Agent 的制品位于 .agentera/，面向用户的制品位于项目根目录），因此能力间的数据流通过共享制品传递，而非直接调用。

制品路径解析

在读取或写入任何制品之前，检查 .agentera/docs.yaml 是否存在。如果其中有制品映射部分，则使用为每个规范文件名指定的路径。如果 .agentera/docs.yaml 不存在，或未为某项制品指定映射，则使用默认布局：

• 面向用户的制品位于项目根目录：TODO.md、CHANGELOG.md、DESIGN.md
• 面向 Agent 的制品以 YAML 格式存放在 .agentera/ 中：progress.yaml、decisions.yaml、health.yaml、plan.yaml、docs.yaml、vision.yaml、objective.yaml、experiments.yaml

---

目录结构

skills/agentera/
  SKILL.md                          # This file
  protocol.yaml                     # Shared primitives
  capability_schema_contract.yaml   # Self-referential schema contract
  capabilities/
    hej/
      instructions.md
      schemas/
        triggers.yaml
        artifacts.yaml
        validation.yaml
        exit.yaml
    resonera/
      instructions.md
      schemas/
        triggers.yaml
        artifacts.yaml
        validation.yaml
        exit.yaml
    ... (12 capabilities total)

通过规范 CLI 根据契约验证任何能力：

uv run scripts/agentera validate capability <name-or-path>

自行验证契约：

uv run scripts/agentera validate capability-contract --format json