--- status-class: implementation-reference design-state: unshipped-implemented-v1 superseded-for-user-model-by: - specs/task/agent-space-convergence.md - specs/task/collaborator-policy.md - specs/message/delivery-ledger-optimization.md runtime-refs: - specs/collaboration/collaboration.md - specs/message/delivery-runtime.md - specs/agent-space/owner-private-agent-delivery.md - specs/task/agent-space-convergence.md historical-designs: - specs/agent-space/space-core-design.md - specs/agent-space/delivery-wake-design.md - specs/agent-space/share-publish-design.md - specs/agent-space/surface-projection-design.md --- # Shared Spaces and Agent Spaces 日期：2026-04-24 状态：unshipped implemented-v1 reference。当前 unshipped implementation 曾把 unified Space / Agent Space 主路径落到 schema、store、API、web 与 daemon tests；但 Agent Space 尚未作为正式产品 / schema baseline 上线。因此本文现在只描述unshipped implementation reference与问题域语义，不再定义最终用户心智模型或生产兼容义务。`owner-private-agent-delivery.md` 中的 legacy quote-flow 仅作为历史兼容参考，已不保留 hidden context-delivery 写入口。面向产品心智模型与 shipped contract 的 target 方向由 [`../task/agent-space-convergence.md`](../task/agent-space-convergence.md)、[`../task/collaborator-policy.md`](../task/collaborator-policy.md) 和 [`../message/delivery-ledger-optimization.md`](../message/delivery-ledger-optimization.md) 定义：Agent Space 用户能力由 Task + Scope Execution 承接，Agent Space 不作为主用户可见对象、public API baseline 或 delivery ledger baseline 暴露。 范围：作为一份 implementation reference，统一记录当前未上线 Space、public/private agent、Agent Space、mute / wake、share、publish 与 UI 语义，供 Task 收敛和迁移改写时对照。 非目标：schema、wire/storage contract、migration 步骤、target grammar、projection 实现、具体 UI 视觉稿、website / i18n 的实现细节。 迁移说明：本文中的用户可见 Agent Space 语言描述的是 unshipped implementation 事实，不是后续新 UX 的扩展方向，也不是 merge / release 后必须保留的兼容行为。后续新能力不得继续扩大 Agent Space 作为公开产品对象的范围；当实现触碰 share、publish、notification、wake、history、surface projection、collaborator 或 delivery ledger 时，应优先按 Task + Scope Execution 收敛 spec 补 task-native / scope-execution facade 和用户入口，并在 ship 前改写未上线 Agent Space API / schema / realtime / delivery 依赖。 2026-05-06 术语锁定：本文件里的 `Agent Space` 是当前未上线实现名。最终态内部概念是 **Scope Execution / owner-scoped private-agent execution context**，它不是可移除的旧功能；旧实现只指旧暴露面和 API 名称，例如 browser-facing Agent Space API、Agent Space panel/workflow、以及 agent-facing prompt/tool vocabulary。未发布分支不保留旧 Agent Space runtime target alias；daemon / agent API 使用 parent target，hidden scope context 只通过 authenticated session / current-delivery binding 传递。不要把“删除旧 Agent Space surface”理解为删除 Scope Execution 能力。 这份 implementation reference 记录一个统一抽象：**Space（空间）**。AgentTeam 当前分支实现中，`channel`、`thread`、`dm`、`agent_space` 都是 Space。基于这个抽象，未上线 Agent Space line 曾提供三种协作模式： - **shared collaboration**：public agent 作为某个 Space 的公开协作者。 - **private Agent Space**：private agent 作为 owner 在某个 Space 下的持续私人协作空间。 - **explicit sharing**：owner 显式把外部消息授权给 private Agent Space。 这 3 种模式只描述未上线 implementation line 的内部模型。对 shipped 用户心智、默认 UX、public API 和 docs，Task / owner_quote source refs / Task discussion / Task announcement / Notifications & output / Task collaborators 是当前 canonical model。 ## 1A. Authority / implementation matrix 为避免 `specs/` 下同时出现 legacy canonical、模块设计与 implementation bridge 时产生 source-of-truth 混淆，v1 显式锁定以下 authority 分层： | 文档层 | 当前 status | authority | 冲突规则 | |---|---|---|---| | `shared-spaces-and-agent-spaces.md` | unshipped implemented-v1 reference | **unshipped implementation reference与问题域语义** | 对用户心智模型、public API、Task collaborator、delivery ledger、shipped schema 的冲突，以 Task 收敛 specs 为准 | | `2026-04-24-agent-space-01..04-*.md` | superseded historical records | **未上线实现线的历史参考** | 不定义当前产品、schema、API、runtime 或用户可见 surface；与当前 Task / Scope Execution / storage 语义冲突时一律以后者为准 | | `runtime-api-design.md` | implemented-v1 implementation bridge | **store / API / runtime 分层说明** | 不单独改写产品语义；用于解释代码路径与 schema 职责 | | `../collaboration/collaboration.md` / `../message/delivery-runtime.md` / `owner-private-agent-delivery.md` | legacy-compatible canonical pieces | **非 Agent Space 主路径与兼容边界** | `../message/delivery-runtime.md` 的可靠性语义仍有效；`owner-private-agent-delivery.md` 只保留 legacy quote-flow 背景，不保留当前写入口 | 当前默认 surface / runtime 对齐结论（不是 shipped compatibility contract）： - 用户可见 Web 与 runtime 主路径已经由 Task / owner-private context facade + parent target 承接；browser-facing Agent Space API、Agent Space panel、Agent Space realtime event、publish 与 auto-publish workflow 不再作为当前 surface 暴露。 - private-agent execution 使用 parent channel/thread/task target 与 hidden owner-private context；parent timeline 是唯一聊天 transcript，context/source facts 只描述 private context visibility、wake、cursor 与 provenance。 - legacy owner-private context delivery API 已移除；不得恢复 hidden carrier 写入口，也不得把它当作新的产品入口或恢复 Agent Space transcript / publish surface 的理由。 - 尚未上线的 storage/migration remnants 可继续按 Task 收敛与 delivery ledger spec 在发布前改写；不得把 unshipped Agent Space browser/API/runtime shape 当作兼容 contract 扩大。 ## 1. Implementation Definitions ### 1.1 Shared Space `channel`、`thread`、`dm` 都是 **Shared Space**。一个 Shared Space 定义： - 谁是 participant - shared timeline 是什么 - 哪些消息对哪些 participant readable - 哪些消息会被 delivered / 进入 unread / runtime path ### 1.2 Public agent 把 agent 加成 `public`，表示： > **Add as public = make this agent a shared collaborator for the channel.** 它是 shared participant。它读取 shared timeline，遵循和 human 对称的 delivery 规则，并且任何有权限的 participant 都可以在该 Space 中 `@mention` 它。 ### 1.3 Private agent 把 agent 加成 `private`，表示： > **Add as private = make this agent part of the owner's private Agent Space for this channel.** 它不是 shared participant。它持续跟随 owner 在该 Space 下的私人协作，但默认不自动读取其他人的消息；在 parent channel/thread 中，别人对它没有直接 `@mention` 权限。**private 保护的是默认输入边界与直接操作边界，不是“别人看不见”这段 Agent Space transcript。** ### 1.4 Agent Space 当 owner 的 private agents 在某个 parent Space 下协作时，系统 materialize 一个 `agent_space`。在产品语义上，它就是： > **the owner's private Agent Space in that parent Space**。 它是一个**一等 Space**：有自己的 transcript、participants、delivery、history 与 lifecycle 规则，并且始终与 parent Space 保持显式关联。它不是一次性的 session，也不是 parent timeline 上的临时注释层。 ## 2. 核心对象 - **Space（空间）**：定义参与边界、shared timeline、delivery 规则、history 边界的协作单元。类型包括 `channel`、`thread`、`dm`、`agent_space`。 - **Surface（呈现位置）**：用户访问协作内容的界面承载位置。Channel、thread、DM 通常既是 Space 也是 surface；Agent Space 也是真实 Space，但它的 transcript 可以被渲染在一个或多个 surface 上（例如 inline、panel 或其它视图）。这些 surface 是同一份 Agent Space 内容的不同呈现方式，不是不同的 Agent Spaces。 - **Participant（参与者）**：真正属于某个 Shared Space 或 Agent Space 的 human / public agent / private agent。 - **Public Agent Entry**：agent 被加入 channel 且 `visibility = public`。它是 channel participant，也是 thread readable participant；在 thread 中的 delivery 仍受 thread-local 规则约束。 - **Private Agent Entry**：agent 被加入 channel 且 `visibility = private`。它显示在该 channel 及其 thread scopes 的成员面板中，但不是 channel/thread participant。它只进入 owner 的 private Agent Space。 - **Parent Observer（parent 观察者）**：parent participant 在浏览某个派生 Agent Space transcript 时的角色称呼。它不是额外权限、也不是额外规则；只要你是 parent participant，就默认能以 Parent Observer 身份浏览该 Agent Space transcript。Observer 不是 Agent Space participant。 - **Share / Attach（显式共享）**：owner 把 parent Space 中本来不自动进入 Agent Space 的消息，显式授权进入 Agent Space 的动作。 ## 3. 四个模块 这份 umbrella spec 覆盖四个强耦合模块： 1. **Space**：`channel / thread / dm / agent_space` 的统一抽象与派生关系。 2. **Mute / Wake**：delivery 与 runtime wake 的解耦，以及默认强度。 3. **Share**：private Agent Space 如何显式接收别人消息。 4. **UI**：如何把 public/private、active/quiet、share/exit 等边界表达给用户。 这四个模块不能拆成互不相干的 spec；它们共享同一套术语、边界与不变量。 ## 4. 核心不变量 ### 4.1 Shared Space visibility > Space participant 读取该 Shared Space 的完整 shared timeline；不按 owner / author 做 per-member redaction。 如果一个 human 或 public agent 是 `#feature` channel participant，它读取的就是完整 `#feature` timeline，以及该 channel 下 thread 的 readable timeline。不存在“同在一个 Shared Space 里却只看到一半 timeline”的 owner-filter。 ### 4.2 Delivery 与 wake 正交 > Readable / delivery / wake 是三件不同的事。 - **Readable**：这条消息对你可读。 - **Delivery**：这条消息是否进入你的 unread / feed / runtime input queue。 - **Wake**：这条 delivered 消息是否立即启动你的 runtime / notification。 这三层必须允许独立控制。尤其对 agent 来说，**delivery 不等于 runtime 立即唤醒**。 ### 4.3 Public agent 是 shared collaborator > Public agent 的 readable boundary 跟 Shared Space 一致；它和 human 共享同一套 channel/thread delivery 规则。 - Channel-level messages delivered 给 channel participants（包括 public agents）。 - Thread-level replies readable 给 channel participants，但只 delivered 给 thread participants / subscribers 和被 mention 的对象。 - 任意有权限的 participant 都可以 `@mention` public agent。 ### 4.4 Private agent 的默认输入边界 > Private agent 不能自动看到别人消息；它只能自动看到 owner 自己的消息。别人消息只有在 owner 显式 share / forward / attach 后，才能进入 Agent Space。 这是 private 的硬边界。它同时约束 channel-level 与 thread-level private collaboration。 这里的主语必须说清楚：这条硬边界约束的是 **parent Space 里的原始消息**。 换句话说，private 的含义不只是“别人不能 command 它”，还包括： - 它默认不自动读取别人在 parent Space 里的原始消息。 - 别人也不能直接 `@mention` 它。 - owner 如果希望它理解别人的发言，必须显式 share。 它**不**意味着 private agent 产出必须留在独立 transcript 中。当前模型下，private agent 一旦在 owner-private context 中被授权唤醒，它的回复直接写入对应 parent channel/thread/task target；private 锁住的是“哪些输入默认可见”和“谁能直接驱动它”，不是通过 publish gate 延迟对外产出。 ### 4.5 Channel-level private agent roster 是 membership 的单一真相源 > Parent channel 的 private agent roster 是 private agent eligibility 的单一真相源。 对 private agents 而言： - Channel-level Agent Space 的 private participants 跟随这份 active roster。 - Thread-level Agent Space 的 private participants 是这份 roster 中被该 thread 显式 mention / routed 进来的子集。 - Thread 不维护独立 private roster，也不能加入不在 host channel private roster 中的 private agent。 因此，不存在“这个 private agent 只在某个 thread-level Agent Space 里，但不在 parent channel 的 private roster 里”的状态；同时，把新的 private agent 加进 host channel 本身，不会 retroactively 把它同步进历史 thread-level Agent Spaces。 ### 4.6 历史规则分三层 必须明确区分三种不同的“历史”： 1. **Parent raw history -> Agent Space creation backfill** - thread-level first `@` 创建时，会 backfill owner 之前在该 thread 中的发言； - channel-level add 创建时，会 backfill owner 之前在该 channel 中的发言； - 无论 channel-level 还是 thread-level，都不会自动 backfill 其他人的既有消息。 2. **Agent Space transcript -> later joined private agent** - 后加入并实际进入某个 Agent Space 的 private agent 必须完整看到该 Agent Space 已有 transcript； - 这包括之前已经 attach / forward 进来的他人消息，因为它们已经是 Agent Space transcript 的一部分。 3. **Parent raw history 的后续自动流入** - 只适用于 owner-authored parent messages； - 不因为新 agent 加入而额外补灌别人之前的原始消息。 一句话： > **“No auto-history” 只约束 parent raw history -> Agent Space；不约束 Agent Space transcript -> later joined private agents。** ## 5. Space 模型 ### 5.1 Channel `channel` 是顶层 shared Space。它承载： - human participants - public agent participants - private/public agent roster - 它是其派生 thread 与 Agent Spaces 的 parent collaboration context ### 5.2 Thread `thread` 是从 channel 派生的 scoped shared Space： - 任何 channel participant 都能打开并阅读它； - 只有 thread participants / subscribers 和被 mention 的对象会收到 thread-level delivery； - 它是“干净的历史”边界，用来承载 scoped collaboration。 ### 5.3 DM `dm` 是独立 Space，不参与 channel/thread/agent_space 的派生链。对 owner 与自己的 agent 来说，DM 是前景对话空间。 ### 5.4 Agent Space `agent_space` 是从某个 parent Space 派生的私有协作 Space： - parent 可以是 `channel` 或 `thread` - 它按 `(owner, parent Space)` 聚合 - 一个 owner 在同一个 channel 中最多有一个 channel-level Agent Space - 一个 owner 在同一个 thread 中最多有一个 thread-level Agent Space - Agent Space 是真实 Space，并且始终与 parent Space 保持显式关联；具体 UI 呈现由后续 design 决定 - 同一个 parent Space 下可以并存多个 owners 的 Agent Spaces；每个 Agent Space 内也可以有多个 private agents。 支持的派生链： - `channel -> thread` - `channel -> agent_space` - `channel -> thread -> agent_space` - `dm` 独立 不支持： - `thread -> thread` - `agent_space -> thread` - `agent_space -> agent_space` - `dm -> agent_space` ## 6. Public agent 行为 ### 6.1 Add as public Add as public 是一个强动作： - agent 成为 channel participant； - 它读取 channel shared timeline； - 它可读该 channel 下的 thread timeline； - thread replies 只有在它参与、订阅或被 mention 时才 delivered 给它； - 任意有权限的 participant 都可以 `@mention` 它； - channel / thread delivery 进入它的上下文输入，不自动等于每条消息都立即 wake runtime。 v1 的权限边界： - 只有当前用户拥有 / 管理的 agent 才能被该用户以 `public` 方式加入 channel； - 邀请别人拥有 / 管理的 agent 进群只能使用 `private`，这样它会进入该 agent owner 的 Agent Space，而不会把别人 agent 变成 inviter 可操控的 shared collaborator； - `#all` 不允许 public agent entry，agent 在 `#all` 只能按 private-by-default 规则存在。 ### 6.2 Public agent 的价值 Public agent 的产品定义是： > **shared collaborator for the channel**。 它代表“这个 Space 里的公共协作能力”，而不是某个 owner 的私人工作区。 ### 6.3 Public agent 的默认 wake contract 对 public agent 来说，spec 需要把 readable / delivery / wake 三层闭合： - channel-level messages delivered 给 public agent，但默认 `quiet`，不因每条 channel 消息立即 wake runtime； - thread-level replies 只有在它参与、订阅或被 mention 时才 delivered；一旦它已经进入这个 thread-level collaboration scope，默认 `active`，相关 replies 会 wake runtime； - 被 `@mention` 的那条当然也会 wake； - delivered 但未 wake 的消息进入它的上下文输入队列，供下一次 wake 时读取；产品不需要为 public agent 引入单独的 unread 语义。 ## 7. Private agent 与 Agent Space ### 7.1 Add as private Add as private 也是一个强动作： > **Add as private = make this agent part of the owner’s private Agent Space for this channel.** 它的即时效果是： - 该 agent 出现在 channel 及其 thread scopes 的 private agent roster 中； - 在 parent channel/thread 中，只有 owner 可以直接 `@mention` 它； - 它不读取 shared channel/thread timeline； - 它开始进入 owner 在该 channel 下的持续 Agent Space。 ### 7.2 Channel-level Agent Space 的创建点 当 owner 把**第一个** private agent 加入某个 channel 时： - `(owner, channel)` Agent Space 被创建并激活； - owner 后续在该 channel 的消息会自动流入这个 channel-level Agent Space； - 但只限 owner-authored channel messages；其他人的 channel messages 不会自动流入； - owner 此前已经在该 channel 中发过的消息会 backfill 进这个 channel-level Agent Space；其他人的既有 channel 消息不会自动 backfill。 这对应的产品语义是： > **this agent can keep up with my own work in this channel, including what I have already said here.** 它不是由某一条消息临时触发出来的一次性上下文，而是 owner 在这个 channel 下的**持续 Agent Space**。 ### 7.3 Thread-level Agent Space 的创建点 Thread-level Agent Space 不是在 owner 首次 reply 时创建，而是： > **在 owner 于该 thread 中首次 `@mention` private agent 时创建。** 原因是 thread 是“干净的历史”边界： - owner 在 thread 中只和人讨论，不应意外 materialize 一个 private Agent Space； - 只有明确把 private agent 拉进这个 subtopic 时，才开始 scoped collaboration。 创建后： - 该 thread 中 owner 此前已经发过的消息会 backfill 进这个 thread-level Agent Space；其它人的既有 thread 消息不会自动 backfill。 - owner 在该 thread 的后续 owner-authored replies 会自动流入该 thread-level Agent Space； - 其他人的 thread replies 仍不会自动流入，除非 owner 显式 share。 ### 7.4 Later-added private agents 如果 owner 后来又把第二个 / 第三个 private agent 加入 parent channel： - 它们会自动加入该 owner 在该 channel 下的 channel-level Agent Space； - 它们不会自动加入历史 thread-level Agent Spaces；只有之后在某个 thread 中被 owner 显式 `@mention` / routed 进去时，才加入该 thread-level Agent Space； - 一旦加入某个 Agent Space，就能看到该 Agent Space 的完整已有 transcript。 这保证 Agent Space 真的是“共享的 private collaboration surface”，而不是 per-agent 的空壳容器。 ### 7.5 Remove / archive / recreate - Remove 某个 private agent 后，它从相关 Agent Spaces 中移除。 - 如果某个 channel 下 owner 的最后一个 private agent 被 remove： - 该 channel-level Agent Space 转为 archived； - 该 channel 下 owner 已存在的 thread-level Agent Spaces 也一并转为 archived； - transcript 保留为只读历史；自动流入停止，不再继续 active collaboration； - 这样不会因为 remove 最后一个 private agent 而直接销毁既有 Agent Space transcript。 - owner 离开 channel 时，效果等同于 remove 自己在该 channel 的全部 private agent entries：相关 Agent Spaces 一并 archived，而不是删除。 - 之后 owner 再 add 一个 private agent 时： - 按 §7.2 的创建规则新建 channel-level Agent Space； - thread-level Agent Space 仍按 §7.3 在 first `@mention` 时创建； - 新创建的 Agent Space 不继承之前 archived Agent Space 的 transcript。 - 如果未来需要真正 destructive delete，应作为单独显式动作，而不是 remove / owner leave 的隐含副作用。 ### 7.6 Non-owner 与 private agent Non-owner 在 channel/thread 中： - 能看到 private agent entry 的存在与 owner 标识； - 作为 parent participant，只能看到 parent timeline 上已经实际写入的消息；owner-private context/source facts 不向 non-owner 暴露为可浏览 transcript； - 在 parent channel/thread 中，non-owner 不能直接 `@mention` 该 private agent；即使该 private agent 已经通过 owner-private context 在 parent 中作为合法作者出现过，这条边界也不改变。**authorability** 与 **mentionability** 在这里是分离的； - 不能因为 raw API / Trigger / 旧客户端而绕过这条限制； - 即使消息文本里出现 unauthorized private-agent mention，也不能产生任何 routing side effect。 - 整条消息不会因为 unauthorized private-agent mention 被拒绝；除该 inert mention 外，其它合法 routing 照常进行。 ### 7.7 Private agent reply routing 当 owner 在 parent channel / thread 中 `@mention` private agent 并把它唤醒时： - owner 的那条 parent 消息仍然是 parent Space 中的 owner-authored 消息； - server/daemon delivery 对 agent 暴露的 target 是真实 parent target（例如 `#channel` 或 `#channel:short`），而不是 Agent Space / scope-execution target； - runtime/session 绑定隐藏 owner-private context，用于后续 parent-target tool/API 的 authorization、history filter、cursor/unread 与 wake； - private agent reply 直接写入对应 parent channel/thread/task timeline，作为普通 parent message 参与 unread、reaction、search、attachment 和 thread 行为； - private agent 可以成为 parent message author，但不因此成为 parent participant；non-owner 仍不能直接驱动该 private agent。 所以，owner 在 parent 里 `@mention` private agent 的产品语义是： > **use the parent Space as the visible entry point and write authorized private-agent output directly to that parent target, with owner-private context kept hidden in runtime/backend state.** #### 7.7.1 Hidden owner-private target mapping Private agent 的 effective tool target 是 parent target；hidden owner-private context 是 authorization/read/wake filter，不是 agent-facing target，也不是可由 agent 手动提交的授权凭据。 Forward mapping： - channel-level：`(workspace, owner, parent channel)` 定位 owner-private roster/context，用于决定该 parent channel 中哪些 source rows 和 delivery facts 对该 private agent 可见； - thread-level：`(workspace, owner, reply thread)` 定位同一 owner-private context 在 parent thread 上的 filtered view；host channel 提供 private roster 与权限来源； - task/runtime target 仍是 task-native surface；它不能通过 `scope-execution:` 暴露 source target。 Reverse mapping： - parent target 是 display/reply target； - hidden context 持有 owner、host channel/source scope、scope execution/source fact、delivery source event 等 backend-only metadata； - backend 只能从 authenticated runtime session/current delivery binding 取得 hidden context，不能信任 agent 传入的 scope id。 因此，private agent 即使已经在 parent 中成为合法 author，也不获得 generic `#channel` / `#channel:thread` full-access direct-send 权限；所有 agent-facing operation 都必须走 parent target + hidden owner-private visibility/authorization。 ### 7.8 Private agent output to parent `auto-publish` / manual publish is superseded in the current unshipped branch. Private-agent output no longer materializes from a separate Agent Space transcript row into a parent copy. When a private agent is authorized in an owner-private context, its reply is authored directly on the parent channel/thread/task target that the runtime exposes to the agent; unread, reaction, search, thread, and attachment behavior then follow the ordinary parent-surface rules. The durable model must therefore not depend on `scope_channel_profiles.auto_publish_*`, `agent_space_agent_auto_publish_settings`, `scope_share_cards`, or parent↔Agent Space transcript linkage. Owner-private visibility and wake behavior are enforced through private roster/context facts, parent-target authorization, and sparse targeted delivery events. ### 7.9 它到底是什么 由于 private agent 默认不能自动看到别人消息，所以它**不是完整理解整个 channel 的共享 copilot**。更准确地说，它是： > **the owner’s persistent private Agent Space inside a channel**。 它的价值在于： - continuity：持续记住 owner 自己的发言流 - persistent transcript：保留 owner 显式 share 进去的素材 - multi-agent private collaboration：多个 private agents 共享这份 transcript 这里的“持续”很重要：channel private Agent Space 不是围绕某一次 owner 消息临时生成的 prompt 容器，而是随 owner 在该 channel 中长期工作而持续存在的 Agent Space。 ## 8. Mute / Wake 机制 ### 8.1 为什么必须独立 如果不把 wake 从 delivery 里拆出来，就只能在“让 agent 看见更多上下文”和“避免它乱回复 / 烧成本”之间二选一。 因此本 spec 要求： > **The product must provide an independent mechanism to suppress runtime wake without changing delivery semantics.** ### 8.2 默认强度 本 spec 将默认 wake 强度定义为： - **public agent on channel-level delivery**：`quiet` - **public agent on thread-level delivery**：`active` - **channel-level private Agent Space**：`quiet` - **thread-level private Agent Space**：`quiet` - **dm**：`active` 语义是： - Public agent 在 channel-level shared timeline 中默认安静跟随；delivery 进入上下文输入，但不因每条 channel 消息立即唤醒 runtime； - Public agent 一旦进入 thread-level collaboration scope（参与 / 订阅 / 被 mention），默认就是 active； - Channel-level private Agent Space 默认安静跟随 owner 的消息，不因每条 channel 消息频繁唤醒 runtime； - Thread-level private Agent Space 默认仍是 scoped collaboration，但对 private agent runtime 维持 quiet / no-wake，只有被本次明确 mention 的 private agent 才因当前事件 wake；如果同空间里其他 private agent 被手动切成 `auto-wake`，它们也照常 wake； - DM 是前景对话，默认 active。 ### 8.3 `@mention` 覆盖默认静音 默认 quiet 不应压过显式唤醒信号： > **`@mention` always overrides quiet.** 当 participant 在 channel 中显式 `@mention` public agent 时，即使它默认 quiet，该 public agent 也应该 wake；在 thread 中，public agent 的参与 / 订阅 / `@mention` 本身都落在 active scope 内。与此同时，当 owner 在 channel / thread 中显式 `@mention` 自己的 private agent 时，即使 Agent Space 默认 quiet，该 private agent 也应该 wake；如果同一 Agent Space 中另一些 private agent 被手动设成 `auto-wake`，则本次事件的实际 wake set = `mentioned ∪ auto-wake`。Non-owner 仍然不能通过 `@mention` 穿透 private 边界（见 §7.6）。 ### 8.4 Override 具体如何 mute / unmute、如何把 public agent 或 channel-level Agent Space 从 quiet 升为 active、如何把 public agent 的 thread-level active scope 或 thread-level Agent Space 降为 quiet，属于这个模块的 design 细节；但“delivery 与 wake 正交”以及默认强度，属于本 spec 的产品语义。 ## 9. Share 机制 ### 9.1 为什么它是核心能力 private agent 默认看不到别人消息，因此如果没有 share，它只能跟踪 owner 自己的发言流。 所以 share 不是边角，而是 private Agent Space 成立的必要条件。 ### 9.2 最低产品要求 产品必须支持 owner 显式把 parent Space 中的消息授权进入 Agent Space。最低能力是： - **single-message attach / forward** 也就是说，owner 至少能把某一条他人的消息喂给自己的 private Agent Space。 这个动作的产品心智类似“把聊天记录转发给 Agent Space”，但它的产物不是把 source message 直接搬进 delivery pipeline，而是： > **在 Agent Space 中 author 一条 owner-authored quote message。** ### 9.3 Share 的产物 share / attach 的产物应当是： - 一条**属于 Agent Space transcript 的 owner-authored quote message**； - 这条 quote message 带有指向 parent source messages 的 **structured source refs**； - owner 可以附加 message，也可以只转发 source context 而不写额外说明；若附加了 message，则它应在目标 transcript 中 materialize 成一条独立的 owner-authored ordinary row，并排在 shared-context row 下方，而不是被塞进 shared-context row body； - source shared message 本身仍然留在 parent Space 中，不因为 share 而变成 private agent 的直接 delivery object。 产品心智上，它像“把聊天记录转发进 Agent Space”；但比普通转发更严格，因为： - 需要保留 durable source refs； - 需要支持 folded rendering / expand 查看完整引用内容； - 需要支持后续 trace / audit / explainability。 ### 9.4 更丰富的 share 更丰富的 share 粒度（例如 thread snapshot、消息区间、一次性授权某个 thread 的已有历史）属于后续扩展，但都必须遵守同一条语义： > **没有 owner 的显式授权，别人的消息永远不会进入 private Agent Space。** 并且，无论是单条 share、区间 share 还是 thread snapshot，产物都应保持同一模型： > **one or more owner-authored quote messages with source refs inside the Agent Space.** ### 9.5 Share 的 delivery / wake / trace 边界 share 是一个 **authoring act**，不是 source message 的直接 delivery act。 因此： - 真正进入 private agent delivery / wake pipeline 的，是 owner-authored quote message； - source shared message 本身不直接 delivery 给 private agent，也不直接 wake private agent； - structured source refs 是 Agent Space transcript 与 parent source messages 之间的 durable trace / audit link； - 如果 quote message 被渲染到 parent surface，那只是 Agent Space transcript 的 render / projection，不改变它属于 Agent Space 的事实； - folded summary、trace 标记与 diagnostics 的具体呈现形式属于 design，但这些能力都应建立在 owner-authored quote message + source refs 之上。 ### 9.6 Share 的结果 一旦某条外部消息通过 owner-authored quote message 被 share 进 Agent Space： - 这条 quote message 成为 Agent Space transcript 的一部分； - 当前与后来加入的 private agents 都可以看到其中引用的 source context； - 它不再只是一次性 prompt 材料，而是共享私人协作历史中的持久内容。 ## 10. UI 不变量 这份 spec 不定义视觉稿，但要求下面这些 UI 不变量成立： ### 10.1 Add affordance wording Add-as-public 与 add-as-private 的文案必须明确表达产品含义： - `public`：shared collaborator for this channel - `private`：owner’s private Agent Space / personal copilot for this channel 不能只写模糊的 “Add agent”。创建群聊与 add member 时，agent visibility 使用一个下拉框而不是两个并列按钮，默认值必须是 `private`；当目标 agent 不是当前用户可管理的 agent，或目标 channel 是 `#all` 时，`public` 选项必须不可选。 ### 10.2 Active signal 当某个 channel-level private Agent Space 正在跟随 owner 时，owner 必须在 parent Space 的 composer 或相邻位置持续看到清晰 signal，知道： - 哪些 private agents 正在跟随 - 当前是 quiet 还是 active - 这条消息是否会进入 private Agent Space ### 10.3 Exit affordance owner 必须能随时停止自动流入： - remove private agent - mute private Agent Space - 退出 thread-level scoped collaboration 这些入口必须是可发现的。 ### 10.4 Member panel channel/thread 的成员面板至少区分： - participants（humans + public agents） - private agents in this channel 并明确 private/public badge 与 owner 标识。 ### 10.5 Agent Space surface treatment 本 spec 不预设 Agent Space 必须 inline 呈现，也不预设它必须是 panel、drawer 或独立 view。无论最终 UI 采用哪种 surface treatment，都必须满足： - 当前 browser/runtime surface 不提供 Agent Space transcript panel / inline transcript 作为 shipped surface； - parent timeline 是唯一真实聊天 timeline，private agent reply 如果出现在 parent surface，它就是 parent message，而不是 transcript projection； - owner-private context/source facts 可以在后台用于 visibility、wake、cursor、unread 与 provenance，但不能渲染成第二份聊天 transcript 或 publish candidate； - surface treatment 只能围绕 parent messages 与 task-native surfaces 设计；不提供 Agent Space composer、manual publish、auto-publish、或把 Agent Space 继续派生成普通 thread 的入口。 ### 10.6 Primary vs secondary Agent Space emphasis 当一个 parent Space 下存在多个 Agent Spaces 时： - owner 自己的 Agent Space 应作为 primary surface； - 其他人的 Agent Spaces 应该是 discoverable 的，但默认处于 secondary 位置； - non-owner Agent Spaces 默认不应产生强 attention demand；产品不需要为它们默认做 unread / badge / urgency 提示。 ### 10.7 Compare is opt-in, not default 多 Agent Spaces 并存时： - 产品不需要默认把多个 foreign Agent Spaces 对等展开成并列主视图； - compare / split view 应是低频、显式 opt-in 的动作，而不是默认布局； - 常态应优先优化“看我的 Agent Space”，而不是“同时盯住所有 Agent Spaces”。 ### 10.8 Responsive panel placement 如果产品提供 panel 作为 Agent Space surface，则： - 桌面 / 宽屏默认使用 side panel； - 窄屏默认使用 bottom panel； - surface placement 由 viewport / device class 自动决定，而不是要求用户显式选择 side vs bottom。 ### 10.9 Parent ↔ Agent Space context alignment parent context 与 Agent Space transcript 之间必须是**可对齐、可导航**的： - 用户应能理解 parent 中哪段 context 演化成了 Agent Space 中哪段协作； - 产品应支持从 parent context 导航到对应的 Agent Space 锚点，也应支持从 Agent Space transcript 回到对应的 parent context； - 如果同时打开多个 Agent Spaces，这种上下文对齐应分别作用于每个当前打开的 Agent Space。 - 具体使用 hover、scroll、highlight、anchor fallback 还是其它机制，属于 design，但“上下文对齐可导航”本身是产品不变量。 ### 10.10 Share affordance owner 在 parent Space 的工作流中需要明显的 attach / forward 入口，把外部消息共享进 private Agent Space。 ## 11. 阶段（Phasing） 这是一份完整产品 spec；阶段是落地顺序，不是拆分成多份 spec 的理由。 ### Phase 1：基础模型 - Shared Spaces / Agent Spaces 统一抽象 - public / private agent entries - channel-level Agent Space - thread-level Agent Space - parent participants browse derived Agent Space transcripts by default - delivery vs wake orthogonality - quiet / active 默认强度 - single-message share - 核心 UI 不变量 ### Phase 2：更强的分享与可控性 - richer share（例如 thread snapshot / range attach） - 更完整的 mute / override controls - 更强的 active signal / Agent Space state UI ## 12. Out of scope 这份 spec 不覆盖： - schema、storage、wire contract、target grammar - migration / dual-write / compatibility 步骤 - website / i18n 的实现工作 - richer share 的具体 UI 粒度 - archived Agent Space 的 retention / notification / audit 细节 - future shared / multi-human Agent Space collaboration models - server-side echo suppression 的具体实现 这些属于后续 design 文档。 ## 13. 给用户的一句话解释 > AgentTeam 里的 channel、thread、DM 都是 Space。Public agent 是这个 Space 的公开协作者；private agent 则属于 owner 在这个 Space 下的持续 Agent Space。Private 的含义不是“别人看不见”，而是“别人消息不会自动流入、别人也不能直接驱动它”；parent participants 默认仍可以浏览派生出的 private Agent Space transcript。Channel-level 与 thread-level private Agent Space 都默认低噪声地跟随 owner；thread-level 只是在上下文边界上更聚焦，而不是默认更吵；所有这些都建立在同一套 Shared Spaces 模型之上。