- 严格分层：
Domain / Application / Infrastructure / Host；API仅做宿主与组合，不承载业务编排。 - 统一投影链路：CQRS 与 AGUI 走同一套 Projection Pipeline，统一入口、一对多分发，禁止双轨实现。
- 投影编排 Actor 化：Projection 运行态（会话、订阅、关联）必须由 Actor 或分布式状态承载；禁止中间层进程内注册表/字典持有事实状态。
- 读写分离：
Command -> Event，Query -> ReadModel；异步完成通过事件通知，不在会话内拼装流程。 - 依赖反转：上层依赖抽象，禁止跨层反向依赖和对具体实现的直接耦合。
- 命名语义优先：
项目名 = 命名空间 = 目录语义；缩写全大写（LLM/CQRS/AGUI）；集合用复数。 - 核心语义强类型：影响业务语义、控制流、稳定读取且仓库内可控的数据，必须建模为
proto field / typed option / typed sub-message，禁止塞入通用 bag。 - API 字段单一语义：一个字段只表达一个含义，禁止双重语义（如"名称查找 + inline 内容"）。
- Actor 即业务实体：一个 actor = 一个业务实体（数据与方法同住）；禁止按技术功能（读/写/投影）拆分同一业务实体为多个 actor。
- 删除优先：空转发、重复抽象、无业务价值代码直接删除，不保留兼容空壳。
- 变更必须可验证：架构调整需同步文档，且
build/test通过。
- 单一主干，插件扩展：只保留一条权威业务主链路；新能力以插件/模块挂载，禁止平行"第二系统"。
- 内核最小化：核心层只承载稳定不变量与通用机制；波动能力下沉到扩展层。
- 扩展对称性：内建与扩展能力遵循同一抽象模型与生命周期协议。
- 边界清晰：协议适配、业务编排、状态管理分属不同层；禁止跨层偷渡语义。
- 事实源唯一：跨请求/跨节点一致性事实必须有唯一权威来源（Actor 持久态或分布式状态），不依赖进程内偶然状态。
- 渐进演进：开发期可用本地/内存实现，但生产语义必须能无缝迁移到分布式与持久化。
- 正确架构优先：选择正确的架构设计，因为正确的架构在增长时自然解决下游问题；如果架构无法在增长时解决问题，则架构本身不正确。
- 治理前置：架构规则必须可自动化验证（门禁、测试、文档一致性）。
判定顺序：
- 核心语义？ 影响业务语义/控制流/稳定查询 → 强类型
proto field / typed sub-message / typed option。不因"未来可能扩展"先放 bag。 - 开放扩展边界？ 生产方/消费方不完全同源、允许第三方追加、缺失不破坏主流程 → 允许 bag。
- bag 职责命名：command 头 →
Headers；业务完成注解 →Annotations；pipeline 临时共享上下文 →Items。 Metadata判定：看对象语义边界，不看"是否跨层"。request/response/event/command自身的正式开放扩展信息 → 可叫Metadata；middleware/hook/pipeline 执行过程的进程内临时上下文 → 叫Items，即使跨多个处理层。- 保留原则：边界扩展袋天然就是开放式 metadata 时，保留
Metadata，不硬改成缩窄含义的名字。 - 外部协议：第三方 SDK/外部协议原生
Metadata允许在 adapter/boundary 保留；进入仓库内部主模型后必须映射回 typed 字段或按职责命名结构。 - 演进路径：仓库内可控的稳定语义优先
proto field演进，不先用字符串 key 兜底。 - 不匹配时：新增按职责命名的字段/子消息，不硬塞现有 bag，不把明确语义降级回通用
Metadata。
Envelope是统一消息包络（command/reply/signal/event/query），但是否可持久化、可投影、可观察必须由消息契约显式定义，不因"都走 Envelope"混淆语义。- committed domain event 必须可观察：write-side 完成 committed event 后必须送入 projection 主链；禁止只落 event store 而不进入可观察流。
- 业务消息与查询语义分离：actor 间 event 链路是业务协议；readmodel 查询只读已物化事实；二者契约、一致性、完成判定不得混用。
- 禁止 generic actor query/reply：不得定义通用
Query*Requested -> *Responded协议或通用request-reply client兜底读取；查询走 readmodel，跨 actor 交互走 command/event。 - 禁止 stream request-reply 冒充 RPC：stream 用于事件分发与观察；"先发消息再等 reply"必须改 readmodel 查询或 continuation 事件协议。
- 命令骨架内聚：标准生命周期
Normalize -> Resolve Target -> Build Context -> Build Envelope -> Dispatch -> Receipt -> Observe；业务模块只负责目标解析与载荷/结果映射。 - 传输载体可替换：上层依赖投递契约（
IActorDispatchPort），不依赖具体载体；链路可从直投切换为异步传输而不污染应用语义。 - 投递语义 runtime-neutral：
publish/send统一表示"进入目标 inbox"；不因目标self或底层差异退化为 inline dispatch；需立即执行走独立dispatch契约，禁止绕过 publisher 直操底层传输对象。 - Runtime 与 Dispatch 分责：
Runtime负责 lifecycle/topology/lookup，Dispatch Port负责投递；禁止揉成全能接口。 - ACK 诚实：同步返回只承诺已达到阶段（默认
accepted + stable command id）；committed/read-model observed等强保证须通过独立契约或异步观察获取。 - 追踪标识与目标身份分离：
commandId/correlationId追踪请求，actorId标识实体；禁止混用或假设一一对应。 - 命名跟随职责：接口/类型/目录命名描述职责边界，不泄露
runtime/stream/protocol偶然细节。
- 单一权威拥有者：每个稳定业务事实有唯一 actor 拥有；
committed event store + actor state是唯一真相，readmodel 只是查询副本。 - 运行时形态不是业务事实：不得把本地实例类型、代理类型、对象可见结构当成业务绑定依据。
- 身份与事实分离：稳定 ID 只负责寻址与复用键；可变绑定必须显式建模、显式读取。
- 查询始终走 readmodel：对外查询只读 readmodel；不暴露 actor 内部状态、state mirror payload 或 event replay 为查询主路径。
- 写侧端口只负责 lifecycle/command；读取走窄 query contract 或 projection，禁止 Application/Infrastructure 直读 write-model 内部状态。
- 禁止侧读冒充 query：禁止直读其他 actor 的 event store、持久态快照或"事实重建器"拼装查询结果；跨 actor 读取走 readmodel 或 projection。
- 禁止 query-time replay/priming：
QueryPort/QueryService/ApplicationService不得在请求路径读IEventStore、重放 events、临时重建 state mirror；不得在 query 方法内同步补投影或补跑 ES/materialization。刷新须通过正式 projection 会话、后台 materializer 或写侧预挂接 projection 完成。
EventEnvelope是唯一投影传输壳：业务消息与投影消息都用EventEnvelope；区别由强类型 payload 表达，禁止引入第二层包络。- 业务一致性与查询一致性分层：actor 间链路对"消息已接收/事件已提交/协议已推进"负责；readmodel 对"某
StateVersion已物化可见"负责；禁止混用。 - 一权威状态 → 多 readmodel：不同 readmodel 表达同一 actor 当前态的不同查询形态，不得各自重算业务状态机。
- readmodel 按需创建：只有存在稳定消费场景（明确消费方、查询入口、返回 DTO）时才新增 readmodel。
- readmodel 根契约：仓库内
readmodel默认表示actor-scoped current-state replica；不符合的改名降级为artifact/export/log，或由 aggregate actor 拥有。 - 聚合必须 actor 化：跨 actor 聚合/汇总/关联若有稳定业务语义，建模为 aggregate actor；禁止长期放在 query-time 拼装层。
- projection 只消费 committed 事实：基于 committed domain event 或其同源 durable feed 构建；禁止订阅入站 command、self continuation 或 actor 运行时偶然结构。
- projection 负责物化，不负责推导：消费
EventEnvelope<CommittedStateEventPublished>的state_event + state_root物化到 document/index/search/graph store；actor 内已确定的当前态语义前移到 actor，projection 只做校验、覆盖写入、索引、分发。 - actor 不直接拥有存储实现：actor 发布
state_root作为 readmodel 统一 committed 输入，但 document store/graph store/query provider 等物化职责属于 projection/runtime/provider 边界。 - 正常路径禁止 replay：query path 和 projection path 不依赖
event replay/rebuild/backfill；replay 只属于后台修复/迁移/灾难恢复。 - 版本对齐权威源：readmodel 版本必须来自权威 actor 的 committed version 或等价水位；禁止本地 projection counter 或
StateVersion++冒充权威版本。 - 覆盖复制优先：readmodel 写入语义是"基于权威源版本的单调覆盖"；旧不覆盖新，重复幂等，冲突报错。
- 不默认保留历史视图：
timeline/audit/report/analytics不是默认 readmodel 形态；如有业务价值，降级为 artifact/export 或由专门 actor 拥有。 - 查询诚实：readmodel 可最终一致，但必须暴露权威源版本或刷新戳；禁止在弱读结果上暗示强一致。
- 状态镜像契约面向查询：state mirror payload 作为 readmodel 输入时须是面向读侧的稳定强类型契约，非 actor 内部 state 的原样 dump。
- 默认路径须定义资源语义：任何"缺失即创建"策略须同时定义归属、复用规则和清理责任。
- 本地可用不等于分布式正确：依赖本地 runtime 偶然细节才成立的实现视为未完成设计。
- 抽象一旦能被滥用即设计未完成：允许绕过读写分离/actor 边界/权威源的通用接口须继续收窄。
- Actor 以业务命名：actor 类型和 ID 描述业务实体（
UserConfigGAgent、ChatConversationGAgent），不描述技术角色；禁止WriteActor、ReadModelActor、StoreActor等技术功能命名。 - 读写分离在 Projection Pipeline 层面实现，不在 actor 层面实现：actor 拥有完整业务状态并处理命令；committed event 流入 Projection Pipeline 物化查询视图；禁止为同一业务实体创建"写 actor"和"读 actor"两个分身。
- 应用层契约以业务命名：读端口用
IXxxQueryPort（封装 projection 读取 + 业务映射），写命令通过IActorDispatchPort或等价命令分发机制发往 GAgent；禁止IXxxStore等存储导向命名出现在应用层。endpoint 不直接依赖IActorRuntime或IProjectionDocumentReader等基础设施抽象。应用层契约必须承载业务语义（验证、映射、默认值），禁止纯转发空壳。 - 面向对象内聚：actor 是数据与行为的统一体；同一业务实体的状态、命令处理、事件发布在同一个 actor 内完成；禁止将数据和方法拆分到不同 actor 再通过消息传递拼装。
- 默认短生命周期：一次执行/会话/编排即完成的能力，建模为
run/session/task-scoped actor；GAgent、workflow、scripting 只要协议一致均可作为实现来源。 - 长期 actor 限定事实拥有者：
definition/catalog/manager/index/checkpoint等需长期持有权威状态、串行推进事实的对象。 - 单线程 actor 不做热点共享服务：actor 用于维护状态边界和顺序语义，不用于承接无限扩张的共享吞吐。
- 升级前滚：默认"旧 run 留旧实现，新请求走新实现"；无状态迁移契约时禁止原地热替换。
actorId对调用方不透明：不得解析前缀/类型名/实现来源，不得把字面模式当业务判断条件。
- 单线程事实源：运行态只在事件处理主线程修改；禁止
lock/Monitor/ConcurrentDictionary作为并发补丁维护事实状态。无锁优先：需加锁 → 先判定为"破坏 Actor 边界"→ 重构为事件化串行模型。 - 回调只发信号：
Task.Run/Timer/线程池回调不直接读写运行态或推进业务；只发布内部触发事件（如 timeout/retry fired）。 - 业务推进内聚：工作流推进（成功/失败/分支/重试）在 Actor 事件处理流程内完成，保证顺序性与可重放性。
- self continuation 事件化：Actor 需"下一拍继续"时通过标准 self-message 进入自身 inbox 再消费；禁止绕过消息抽象的临时 helper 或依赖特定 runtime 的 self-dispatch 偶然行为。
- 延迟/超时事件化：
delay/timeout/retry backoff统一"异步等待 → 发布内部事件 → Actor 内消费并对账"；禁止回调线程直接改状态。 - 跨 actor 等待 continuation 化："发送请求 → 结束当前 turn → reply/timeout event 唤醒继续"；禁止当前 turn 同步等待，禁止本地快照读取、event store 侧读或伪 RPC 绕过。
- query 与 command 边界分清：读已提交事实 → 读 readmodel；需对方参与新业务交互 → 发 command/event + reply/timeout continuation。
- 显式对账：内部触发事件携带最小充分相关键（如
run_id + step_id），Actor 内做活跃态校验，拒绝陈旧事件。
- 禁止中间层维护
entity/actor/workflow-run/session等 ID → 上下文/事实状态的进程内映射（Dictionary<>/ConcurrentDictionary<>/HashSet<>/Queue<>）。 - Actor 内部运行态集合可保留在内存或 Actor
State（如module_runtime）；前提：不作为跨节点事实源，按生命周期及时清理。 - 跨 Actor/跨节点一致性状态：优先 Actor 持久态；无法放入时用抽象化分布式状态服务；禁止中间层进程内缓存作为事实源。
InMemory实现仅限开发/测试，不外溢到中间层业务语义。- 方法内局部临时集合可用，不得提升为服务级/单例级事实状态字段。
- 投影端口：禁止
actorId -> context反查管理生命周期，改为显式lease/session句柄传递。
- 统一 Protobuf：
State、领域事件、命令、回调载荷、快照、缓存载荷、跨 Actor/跨节点内部传输对象全部使用 Protobuf。 - 禁止 JSON/XML/自定义字符串格式用于 Actor State、WorkflowRun State、模块持久态、投影检查点等事实存储。
- 外部协议必须 JSON 时，仅在 Host/Adapter 边界做协议转换；进入应用/领域/运行时层后恢复为 Protobuf。
- 新增状态/事件/持久化载荷：先定义
.proto并生成类型，再接入实现；禁止先写临时结构后补 Protobuf。
docs/canon/是唯一权威参考；一个 topic 一个文件，不可有重复。docs/decisions/是 ADR（Architecture Decision Records），不可变，只可被新决策 supersede。docs/history/存放已归档的思考快照，按月份组织，明确标记非权威。- AI 生成的设计文档在会话结束后默认不保留到
docs/；需要保留的必须添加 frontmatter（title/status/owner）并放入对应目录。 - 所有
docs/canon/和docs/decisions/文件必须有 YAML frontmatter，包含title、status、owner字段。 - Lint 操作由
tools/docs/lint.sh执行，已集成到 CI 门禁。 - 根目录允许的
.md文件：CLAUDE.md、README.md、CHANGELOG.md、LICENSE、AGENTS.md。src/下各项目允许自身README.md。 docs/README.md由tools/docs/build-index.sh自动生成，不手动编辑。
src/：生产代码（Aevatar.Foundation.*、Aevatar.AI.*、Aevatar.CQRS.Projection.Core.Abstractions/Runtime/Stores.Abstractions、src/workflow/Aevatar.Workflow.*、Aevatar.Host.*）。test/：对应测试项目（单元、集成、API）。docs/：架构文档（canon/权威参考、decisions/ADR、history/归档、audit-scorecard/审计）。workflows/：YAML 工作流定义；tools/：开发工具；demos/：示例程序。- CLI 项目：
tools/Aevatar.Tools.Cli——提到"CLI 项目"或"cli 项目"时，均指此路径。
dotnet restore aevatar.slnx --nologo/dotnet build aevatar.slnx --nologo/dotnet test aevatar.slnx --nologodotnet run --project src/workflow/Aevatar.Workflow.Host.Api：启动 Workflow API（/api/chat、/api/ws/chat）。dotnet test test/Aevatar.Workflow.Host.Api.Tests/Aevatar.Workflow.Host.Api.Tests.csproj --collect:"XPlat Code Coverage"：单项目覆盖率。
bash tools/ci/architecture_guards.sh：CI 架构门禁主入口。- 分片构建/测试：
bash tools/ci/solution_split_guards.sh/bash tools/ci/solution_split_test_guards.sh
| 变更范围 | 门禁脚本 |
|---|---|
| workflow actor binding / definition identity / resume-signal | tools/ci/workflow_binding_boundary_guard.sh |
| query/read port / projection priming / projection lifecycle | tools/ci/query_projection_priming_guard.sh |
| current-state readmodel / state version | tools/ci/projection_state_version_guard.sh |
*CurrentState*Projector 回读同类 readmodel |
tools/ci/projection_state_mirror_current_state_guard.sh |
| 事件类型 → reducer 路由映射 | tools/ci/projection_route_mapping_guard.sh |
| CLI playground / Demo Web 静态资源 | tools/ci/playground_asset_drift_guard.sh |
| 测试新增/修改 | tools/ci/test_stability_guards.sh |
- 遵循
.editorconfig：UTF-8、LF、4 空格缩进、去除行尾空白。 - 推荐模式：
Aevatar.<Layer>.<Feature>。 - 先抽象后实现；优先接口注入；避免跨层直接调用。
- 公开 API 与领域对象命名表达业务意图，避免含糊词。
- 前端相关请求（页面、组件、控制台、playground、样式重构、视觉 polish）默认遵循
aevatar-frontend-design规范；若运行环境存在同名 skill，优先使用。 - 先确定一个明确审美方向，再开始编码；禁止把多个弱风格混在一起，禁止生成无记忆点的通用 SaaS 外观。
- 禁止默认回落到通用 AI 审美：避免把
Inter/Arial/Roboto/system-ui作为首选字体，避免紫白渐变、模板化卡片网格、无差异面板堆叠。 - 优先抽取 design tokens / CSS variables / theme tokens，统一颜色、字体、间距、圆角、阴影与动效，不接受大面积零散硬编码。
- 在现有信息架构和交互模型内提升层次、比例、对比、质感与动效；除非用户明确要求大改，否则不要破坏既有导航和工作流。
- 结果必须可用：响应式、键盘可达、基本可访问性达标，真实内容密度下仍可读。
- 测试栈：xUnit、FluentAssertions、
coverlet.collector。 - 测试文件命名：
*Tests.cs，单文件聚焦一个行为域。 - 行为变更必须补测试；重构不得降低关键路径覆盖率。自动生成代码不纳入覆盖率考核。
- 轮询等待门禁（
test_stability_guards.sh）强制：禁止随意Task.Delay(...)/WaitUntilAsync(...)。确属跨进程最终一致性探测且无法改为确定性同步时，须加入tools/ci/test_polling_allowlist.txt并说明原因。 - CI 守卫（full-scan）：
- 禁止
GetAwaiter().GetResult() - 禁止
TypeUrl.Contains(...)字符串路由 - 禁止
Aevatar.Workflow.Core依赖Aevatar.AI.Core - 禁止中间层 ID 映射 Dic 事实态字段（扫描 Projection/Application/Orchestration）
- 禁止投影端口回退
actorId反查上下文 - 新增非抽象
Reducer类必须被测试引用 - 事件类型 → reducer 路由须
TypeUrl派生 + 精确键路由（EventTypeUrl分组 +TryGetValue）
- 禁止
- 分支命名：
<type>/YYYY-MM-DD_<purpose>。type∈ {feat,fix,refactor,docs,test,chore}；日期定长YYYY-MM-DD；purpose小写字母+数字+连字符，简短单一目标。示例：feat/2026-03-12_gagent-protocol-first-plan。 - 提交信息：祈使句，聚焦单一目的。
- PR 必须包含：问题与方案、影响路径、验证命令与结果、相关文档更新。架构调整须同步
docs/。
- mermaid 默认指令（所有图首行）：
%%{init: {"maxTextSize": 100000, "flowchart": {"useMaxWidth": false, "nodeSpacing": 10, "rankSpacing": 50}, "themeVariables": {"fontSize": "10px"}}}%% - mermaid 标签用引号：
A2["RoleGAgent"]。 sequenceDiagram紧凑布局（收紧 margin 与文案长度）；禁止固定大宽度样式撑大时序图；需查看细节用外层overflow-x: auto横向滚动。- 文件名时间戳前置定长：日期
YYYY-MM-DD-，日期时间YYYY-MM-DD-HH-mm-ss-。示例：2026-03-09-workflow-architecture.md。 - 打分/审计文档 →
docs/audit-scorecard/。 - 工作文档不加入
aevatar.slnx。
Use the /browse skill from gstack for all web browsing. Never use mcp__Claude_in_Chrome__* tools directly.
Available skills:
/office-hours— YC-style brainstorming and idea validation/plan-ceo-review— CEO/founder-mode plan review/plan-eng-review— Eng manager-mode plan review/plan-design-review— Designer's eye plan review/design-consultation— Design system creation/design-shotgun— Multi-variant design exploration/review— Pre-landing PR review/ship— Ship workflow (test, review, PR)/land-and-deploy— Merge + deploy + verify/canary— Post-deploy canary monitoring/benchmark— Performance regression detection/browse— Headless browser for testing and dogfooding/connect-chrome— Launch real Chrome controlled by gstack/qa— QA test + fix bugs/qa-only— QA report only (no fixes)/design-review— Visual design audit + fix/setup-browser-cookies— Import browser cookies for auth/setup-deploy— Configure deployment settings/retro— Weekly engineering retrospective/investigate— Systematic debugging with root cause analysis/document-release— Post-ship documentation update/codex— Second opinion via OpenAI Codex/cso— Security audit/autoplan— Auto-review pipeline (CEO + design + eng)/careful— Safety guardrails for destructive commands/freeze— Restrict edits to a specific directory/guard— Full safety mode (careful + freeze)/unfreeze— Remove edit restrictions/gstack-upgrade— Upgrade gstack to latest version
When the user's request matches an available skill, ALWAYS invoke it using the Skill tool as your FIRST action. Do NOT answer directly, do NOT use other tools first. The skill has specialized workflows that produce better results than ad-hoc answers.
Key routing rules:
- Product ideas, "is this worth building", brainstorming → invoke office-hours
- Bugs, errors, "why is this broken", 500 errors → invoke investigate
- Ship, deploy, push, create PR → invoke ship
- QA, test the site, find bugs → invoke qa
- Code review, check my diff → invoke review
- Update docs after shipping → invoke document-release
- Weekly retro → invoke retro
- Design system, brand → invoke design-consultation
- Visual audit, design polish → invoke design-review
- Architecture review → invoke plan-eng-review
- Save progress, checkpoint, resume → invoke checkpoint
- Code quality, health check → invoke health
- 架构审计, architecture audit, architecture drift → invoke arch-audit