提案：把能力提示词下沉到 Ornn —— aevatar-system tag 强制 system prompt overlay 方案

[eanzhao]

背景与目标

当前 aevatar NyxidChat agent 的系统提示词偏重：基础 system-prompt.md 约 255 行 / ~5,961 tokens，里面混了大量"能力相关"的 playbook / 能力清单。这类内容变动频繁，每次调整都要改代码、重新部署。

目标：

1. 让 system prompt 尽量小而稳定（只留内核：身份 / 行为准则 / 工具机制 / honest-success / 内部工具表）。
2. 把"能力相关"的提示词搬到 Ornn 上，由 curator 维护、改完无需重新部署。
3. system prompt 继续鼓励 LLM 按需主动拉取技能扩充自身（这一机制现已存在）。
4. 新增：在 Ornn 上设一个专用 tag（如 aevatar-system），归 ChronoAI 组织所有；每次 aevatar agent 处理任务时，都强制把这些 tagged 技能作为 system prompt 的补充——不交给模型自觉，而是由代码无条件注入。

---

一、现状 review

注：实际生产路径是 agents/Aevatar.GAgents.NyxidChat/Skills/system-prompt.md（另有独立的 ChatbotClassifier 分类器 prompt，纯 JSON 意图分类，不在本提案范围）。

1. 基础 system prompt

• 通过 NyxIdChatSystemPrompt.cs（GetManifestResourceStream，懒加载静态）作为嵌入资源加载（.csproj:63 <EmbeddedResource Include="Skills/**/*"/>）。
• 必须留在内核：身份/能力(1-3)、action-first(5-24)、tool 策略(25-31)、channel context + Lark 协议(32-62)、aevatar 内部工具(119-175)、honest-success(221-226)、working rules(242-256)。
• 应外置到 Ornn：skill discovery 段(63-96，这段本身就写了"刻意把 NyxID/Ornn 手册放在 Ornn 而非 system prompt")、长任务自动化 playbook(178-220)。

2. Lark bot 拼接

每轮在 ConversationReplyGenerator.BuildSystemPrompt()（:1030-1051，同步）按序拼接：

顺序	片段	来源
1	基础 prompt	LoadBaseSystemPrompt()（嵌入资源 :1053）
2	## Channel Runtime Configuration	NyxIdRelayPromptConfiguration.BuildChannelRuntimeConfigurationSection()
3	<channel-context> 块	ChannelContextMiddleware.BuildChannelContextSection()
4	## Available Skills（仅本地 skill）	LocalSkillCatalog.BuildSystemPromptSection()
5	附件可见性提示	inline

3. Lark relay 追加

relay 没有独立的一段 prompt，复用同一条 ChannelContextMiddleware，把 bot-owner 身份(operator_*)和发送者(subject_*)塞进同一个 <channel-context> 块（ChannelConversationTurnRunner.cs:1818、NyxIdRelayTransport.cs:1030）。即"relay 追加" = runtime 配置段 + 带 owner/sender 身份的 context 块，和 bot 路径同一套代码。

4. 现有 Ornn skill 拉取机制（"按需"，非注入）

• OrnnSkillClient.SearchSkillsAsync(token, query, scope="mixed") → OrnnSkillSummary[]；GetSkillJsonAsync(token, idOrName) → OrnnSkillJson(含 Files)。
• 工具 ornn_search_skills（scope 硬编码 mixed）、use_skill（本地优先，否则 OrnnRemoteSkillFetcher 拉远端、解析 SKILL.md frontmatter/workflows/scripts）。
• skill body 不进 system prompt；远端全靠模型自觉；用当前终端用户的 NyxID token 拉。
• DTO 无 org/owner 字段，只有 Tags / Category / IsPrivate。
• 无缓存（SkillRegistry+TTL 缓存已被刻意删除，iter27）。

---

二、决定方案形态的硬约束

1. 注入 hook 是同步的：AIGAgentBase.DecorateSystemPrompt(string)→string(:354)、BuildRequest、ChatRuntime._requestBuilder(Func<LLMRequest>)、ConversationReplyGenerator.BuildSystemPrompt(:1030) 全同步 → 不能在轮内同步发 HTTP。

2. CI 禁 GetAwaiter().GetResult()（tools/ci/architecture_guards.sh:322）→ overlay 必须离线异步物化、同步读。

3. 🔑 存在两条独立的 prompt builder（最关键的发现）：

   路径	触发	基础 prompt 源	注入 seam
   Channel/Lark	AgentRunReplyGenerationExecutor → ConversationReplyGenerator	LoadBaseSystemPrompt() 嵌入 md	BuildSystemPrompt(:1030)
   直聊 DM	NyxIdChatGAgent → RoleGAgent.BuildRequest	EffectiveConfig.SystemPrompt	DecorateSystemPrompt(:278)

   → 要"每轮强制"，必须两处都注入；只改一处会漏掉 Lark 或 DM。

4. 无 org 字段 → 组织 scoping 只能靠"用谁的 token 拉（服务端可见性）+ client 侧按 tag 过滤"。

5. host-fact 规则（FI-002 / CLAUDE.md:22）：tag 值、org token 必须 host config 注入，生产代码/类型/prompt 不得出现具体 skill/tag 名。iter27 删缓存的疤就在 DecorateSystemPrompt 注释里——任何进程内缓存都会被 review 挑战。

---

三、推荐方案：Actor-state Overlay + 双 seam 强制注入

把 aevatar-system tag overlay 建模为 NyxIdChatGAgent(RoleGAgent) 自身 config 身份的一部分：离线异步物化进 Protobuf 状态，每轮同步读 in-memory mirror，事件驱动 self-refresh，两条 seam 都注入。无 read-model/projector 塔，无进程内缓存；fetch/render 由无状态 builder 完成。

数据归属与存储

• owner：NyxIdChatGAgent（它本就拥有 RoleGAgentState.config_overrides.system_prompt）。
• 存储：ai_messages.proto 新增 SystemSkillOverlay { string overlay_markdown; string source_watermark; int64 materialized_at; } 作为 RoleGAgentState 字段；经 SystemSkillOverlayMaterializedEvent + reducer 提交（仿 ApplyInitializeRoleAgent RoleGAgent.cs:1296）。committed event + actor state = 唯一事实源。
• 同步读：actor 实例 string? _systemSkillOverlay mirror，激活时从已提交状态 hydrate——同构于已验证的 SkillRunnerGAgent._systemPromptOverride（离线写、同步读）。
• 不建 read-model/projector：overlay 只被自身 turn 消费，符合"readmodel 按需创建"。

刷新（事件驱动，无轮询，I/O 全离线）

1. OnActivateAsync：若 watermark 空或超 TTL，用 ScheduleSelfDurableTimeoutAsync(GAgentBase.cs:322) 排一次 self-refresh。
2. self-handler（仿 HandleRemoteApprovalStatusCheck RoleGAgent.cs:351）离线调 builder → 算 watermark → 变了才 PersistDomainEventAsync（幂等）。
3. 成功后 re-arm 下一次（self-continuation 事件化）。

组织/标签 scoping（无 org 字段下如何落地）

组织成员资格 = "配置的 org/service token 能看见" AND "带配置的 tag"

• 用 host 配置的 ChronoAI org/service token（模式同 SkillRunnerGAgent 取 OutboundConfig.NyxApiKey）调 SearchSkillsAsync(serviceToken, scope:"mixed")。
• client 侧按配置 tag 过滤 OrnnSkillSummary.Tags / Metadata.Tags（无需改 Ornn server）。
• 逐个 GetSkillJsonAsync(serviceToken, name) 取 body。
• 无 token / 未启用 → overlay 空，绝不回退到用户 token。

配置面（全部 host 注入，零字面量）

• 新 SystemSkillOverlayOptions { Tag; OrgServiceToken; RefreshTtl; MaxSkills; Enabled; }（仿 OrnnOptions.cs）。
• appsettings：Aevatar:SystemSkills:{Tag, OrgServiceToken(secret-ref), RefreshTtl, MaxSkills, Enabled}。
• 绑定链路复刻 Ornn：AevatarAIFeatureOptions 加字段 → AevatarPlatformHostBuilderExtensions.cs:51 绑定 → RegisterSystemSkillOverlay（仿 RegisterOrnnSkills）→ AddSystemSkillOverlay（仿 AddOrnnSkills）。
• Enabled=false 或无 tag → 整个特性 no-op，不影响非 ChronoAI host。

降级（永不阻塞/失败一轮）

• 同步读只碰 in-memory mirror；空 → 行为与现状一致（relay 段 + 本地 catalog），turn 照走。
• 离线刷新失败 → log、不提交（覆盖复制优先：坏拉取绝不覆盖好状态）、保留 last-known-good、带 backoff re-arm。
• 仅在离线 handler 里做一个有界 catch，OperationCanceledException 重抛（仿 ActorBackedUserMemoryStore:147）。

system-prompt.md 瘦身

搬出 → Ornn aevatar-system tag skills	留在内核（FI-003 小而可审计）
长任务自动化 playbook (178-220)	action-first / tool 策略 / channel-context 契约
分阶段 channel/Lark 能力清单 (112-166)	use_skill/ornn_search_skills 机制说明
provisioning 授权细则	honest-success 规则、aevatar 内部工具表
各域 how-to	新增一行 anchor：声明下方 auto-injected overlay 是强制组织策略

overlay 块由运行时 builder 用固定 header ## Organization System Capabilities (Auto-Injected) 拼出，不写进 .md。

---

四、已定决策

决策	选择
注入粒度	MaxSkills 以内全文 body注入（强制），超出转"名+一句话"目录、可 use_skill 展开
覆盖范围	双 seam——DM (DecorateSystemPrompt) + channel (BuildSystemPrompt) 都注入，真正"每轮强制"
刷新 TTL	~15min，事件驱动 self-refresh，watermark 不变不发事件
多租户	暂按 ChronoAI 单组织（单一 OrgServiceToken），后续如多组织再加 per-org resolver
per-role 覆盖	暂不可覆盖，对所有 NyxidChat actor 无条件 org-mandated

---

五、分阶段实施 + 测试 + guard

Phase	内容	关键测试
0	确认双 builder 事实（channel vs DM），锁定两个 seam	—
1	proto + 配置（无行为）：SystemSkillOverlay/事件、Options、DI、host 绑定	options 绑定、proto round-trip
2	无状态 ISystemSkillOverlayBuilder（Search→tag 过滤→fetch→render）	tag 过滤、MaxSkills、无 token 返回空、Cancel 重抛、异常→空
3	actor 状态 + 刷新：reducer（精确键路由）、self-handler、OnActivate arming、mirror hydrate	reducer 测试（新 reducer 必须有测试 guard）、watermark 幂等、stale 保 last-known-good、禁用即空
4	双 seam 注入：DecorateSystemPrompt(DM) + BuildEffectiveReplyPlanAsync→BuildSystemPrompt 传参(channel)	两条路径都注入 overlay 的回归测试（证明"每轮强制"）
5	瘦身 system-prompt.md + 加 anchor 行；裁 docs/canon	—
6	bash tools/ci/architecture_guards.sh + test_stability_guards.sh	确认无新增 GetAwaiter().GetResult()

最该加的回归 guard：断言"状态非空时 overlay 在两条 reply 路径都出现"——否则未来重构可能悄悄丢掉一条 seam，"强制"不变量就破了。

---

六、为什么这套设计合规

• 同步 seam 不碰 GetAwaiter().GetResult()：所有 Ornn I/O 在离线 self-handler，热路径只做同步字符串拼接。
• 非中间层缓存：overlay 是 actor 自有 committed Protobuf 状态，单一权威 owner，不重蹈 iter27 删缓存覆辙。
• host fact 注入：tag 值、org token 全 host config（FI-002）；生产代码/类型/prompt 零具体 skill/tag 字面量（CLAUDE.md:22）。
• 无需改 Ornn server：仅用现有 SearchSkillsAsync/GetSkillJsonAsync + client 侧 tag 过滤。
• Protobuf：新增 state/event 全部 proto。

---

待讨论

1. aevatar-system 这个 tag 字面值、以及 ChronoAI org/service token 的来源（secret 管理方式）——这是 host fact，需要确认。
2. MaxSkills 上限取值、overlay 字节预算。
3. 是否现在就要为多组织预留 per-org token resolver，还是 ChronoAI 单组织足够。

本提案由对现有代码的多轮探查 + 对抗式评审综合得出，关键事实均有 file:line 佐证，欢迎拍砖。

[JadeeeZh]

很喜欢这里“小而稳定的 system prompt + 异步物化 skill overlay”的思路，尤其是 hot path 只同步读 actor state、失败时保留 last-known-good，以及 DM / channel 双 seam 注入。
一个延伸问题是：skill 在进入这个 serving layer 前，应该经历怎样的 lifecycle？
我们在 EverOS 里做的是 run → case → supporting evidence → candidate skill → promotion，并保留 provenance、confidence、version history 和 supersession / rollback 信息，避免一次偶然成功直接变成组织级 skill。
这里的 overlay 很适合作为 serving layer。后续也许可以定义一个 portable contract，例如：
SKILL.md + source_case_ids + confidence + promotion_state + supersession metadata
这样上游 experience-to-skill pipeline 和下游 Ornn serving 可以保持解耦。