半透膜可见性路由

半透膜路由是控制普通生成 token“谁可读、谁可输出”的 alpha 接口。“半透膜”是路由类比：它不是 Half、加密或安全边界，也不会创建隐藏的隐空间思维通道。

两种流

assistant_public token 留在模型上下文中并可输出；assistant_inner 也仍是普通上下文 token，但会从面向用户的输出中过滤，并可通过显式可见性矩阵对非助手参与者隐藏。

import torch
from arti import (
    MEMBRANE_STREAM_ASSISTANT_INNER,
    MEMBRANE_STREAM_ASSISTANT_PUBLIC,
    MembraneRoutingConfig,
    MembraneVisibilityRouter,
    build_membrane_visibility,
    membrane_emit_tokens,
)

ASSISTANT, USER = 0, 1
router = MembraneVisibilityRouter(MembraneRoutingConfig(hidden_dim=8))

hidden = torch.randn(1, 3, 8)                  # [B, T, D]
targets = torch.tensor([[0, 1, 0]])            # [B, T]，监督路由
routed = router(hidden, stream_ids=targets)
assert routed.stream_logits.shape == (1, 3, 2)

token_ids = torch.tensor([[101, 202, 303]])    # [B, T]
assert membrane_emit_tokens(token_ids, routed.stream_ids) == [[101, 303]]

readable_by = torch.zeros(2, 2, dtype=torch.bool)  # [参与者, 流]
readable_by[:, MEMBRANE_STREAM_ASSISTANT_PUBLIC] = True
readable_by[ASSISTANT, MEMBRANE_STREAM_ASSISTANT_INNER] = True

visibility = build_membrane_visibility(
    routed.stream_ids, torch.tensor([USER]), readable_by
)
assert visibility.shape == (1, 3, 3)           # [B, 查询, 来源]

传入 stream_ids 时，路由器在监督训练或课程训练中强制采用目标路由；省略时，才从学到的二路 logits 取 argmax。路由器本身不生成 token ID。

hidden [B,T,D] → Linear(D,2) → 流 logits/probabilities [B,T,2]
                                  ↓ 路由 ID [B,T]
token ID [B,T] ──────────→ 公开输出 mask [B,T]
路由 ID + viewer policy ─→ visibility [B,T,T]

上下文与输出必须分离

membrane_emit_tokens 只过滤公开解码结果，不从模型上下文删除内部 token。append_membrane_tokens 可把 token ID、流元数据以及可选的参与者和相位 ID 一起追加。要实施读取契约，应把生成的 visibility 传给 ARTI 层。

运行时应明确拆成四个独立平面：

平面	输入 → 输出	职责
Router	hidden → stream logits / ID	学习 public 与 inner 的分配
Visibility	viewer + stream policy → `[B,T,T]`	决定每个 query 可读取哪些 source
模型上下文	token + stream metadata → 下一轮上下文	保留配置允许的两类流
用户 emit	token ID + stream ID → public ID	过滤外部解码结果

把模型上下文追加与用户输出合并成同一个过滤动作，会删除 inner feedback path；反过来，token 留在模型上下文也不代表它被授权输出。

训练与推理责任

训练时提供目标 stream_ids，让两路 stream_logits 与正常 token 目标共同优化。推理时省略 stream_ids，让已经训练的 router 选择 stream；所有生成 token 先追加回模型侧上下文，再只输出配置允许的 public stream。API 提供的是路由契约，不代表未经训练的基础模型已经知道何时使用 inner stream。

边界

API 验证的是张量路由不变量，不证明语言模型已经学会何时使用内部言语。
对能访问模型内存、张量、日志或 checkpoint 的代码而言，内部 token 并非秘密。
应用必须分开处理面向用户的输出过滤与模型上下文更新。
该接口在 ARTI 1.7.0 中仍属于 alpha；必须在目标模型和任务上验证。