# Codex 对话入口显示规则

## 产品规则与已实现范围

第二栏 Codex 入口默认隐藏，不因登录、加入团队、打开团队页、查看同事任务、生成/复制接入指令或开启上传而出现。

以下任一有效证据可激活当前账号的入口：

1. 本机团队接入实际收到有效 Hook 事件。仅写入配置、尚待信任或尚未收到事件，不算接入成功。
2. 当前账号的云端 `connection/status` 返回经过校验的历史接入资格，或日常读取 `tasks/list` 时自然查到有效的本人任务。换电脑只读无需重新配置采集或开启上传，也不必等待首条云端任务。

已确认的入口状态按账号存入环境隔离的本机日志数据库，只记布尔资格和确认时间，不保存对话正文。暂停、离线或断开采集不隐藏已有入口。切换账号/退出登录立即隔离，迟到响应不能激活另一个账号。入口状态只控制导航，不能替代任务读取权限或上传授权。

## 实现

- 新增插件本机只读桥接操作 `team.codex.entry-availability`，入参 `expectedUserId`，返回 `{userId,visible,checked}`。
- 新用户未知/失败时隐藏，不把网络失败解释为绑定成功。
- 本机已确认状态直接读取；未确认时使用 `POST /api/v1/team-codex/connection/status`，请求严格为空对象 `{}`，沿用当前登录 JWT。严格校验 `owner_ref`、布尔状态与 `first_connected_at`（true 对应正整数毫秒，false 对应 null）。不再为入口额外查询任务列表。
- 同一账号的并发检查合并为一个请求，false/失败的远端检查间隔至少 30 秒。页面可见且对话列表激活时检查本机状态，确认 true 后停止本轮界面轮询；后续直接使用持久化资格。
- false 只代表本次成功查询无远端来源，不能清除本机已有 true；错误或不完整响应保持未知，不能伪装成成功的 false。切换账号取消旧请求并拒绝迟到响应。

## 来源确认：无需上传任务

按后端提供的 2026-10-01 正式目标契约接入 `POST /api/v1/team-codex/sources/confirm`，基地址 `https://team.jotmo.cc`。契约不代表生产已经部署，需发布后联调。

- 仅在真实有效 Hook 证据与当前账号/团队明确云端授权同时存在时确认，两者先后顺序不限。只有本地授权不上报元数据；复制指令、写配置、查看同事任务或开启上传均不能单独触发确认。
- 请求仅包含 `expected_owner_ref`、`team_ref`、`source_id`、`source_name`；不包含任务、正文、事件、环境或虚构的 `hook_verified`。
- `team_ref` 使用授权时从 `list-mine` 的 `arkme_cn` 团队核实的真实 team_id。确认使用原绑定，不在重试时重新猜测团队。
- 与现有 Sync 共用同一个来源 UUID；确认先于/晚于 Sync 均不更换身份。重试、重启保持 ID 和首次名称；不会使用空 `tasks` 同步来制造来源。
- 已暂停采集、有 Hook 历史但没有待上传任务时，仍可在已有云端授权下确认元数据。来源确认不会自动恢复采集、开启正文上传或扩大团队可见范围。
- HTTP 和业务 code 均成功、响应 owner/source 与发送上下文完全一致才记为成功。暂时失败持久化退避：30 秒起，最多 5 分钟；每轮最多处理 20 个待确认来源，避免重叠请求。
- `TEAM_FORBIDDEN`、`ACCOUNT_OR_DESTINATION_MISMATCH` 等明确拒绝停止该来源确认，不能换归属兜底；只有用户重新授权才重置失败重试。元数据接口暂不可用不会阻断原有正常任务同步。
- 本地数据库新增来源确认记录，并给原授权记录增加来源别名；不迁移旧来源/历史任务。新账号和团队仍使用新来源。

## 来源名称与权限边界

现有云端授权面板增加一行「来源名称」，默认「本机 Codex」，用户可修改。新来源名称非空、不含控制字符，最多 128 UTF-8 字节；不自动读取或上传 hostname。已创建来源保留原 ID 和首次名称，包括旧版本已保存的名称，避免重试改变身份。

账号历史资格与当前团队权限、设备在线状态、采集状态和正文上传授权独立。离队/团队解散后的历史 true 不允许绕过任务读取权限；再次确认仍可被后端拒绝。正式/测试缓存按原环境目录隔离，目前云端传输仍只开放已有正式环境能力。

本轮不改 Hook 信任流程，不扩展排队、Token 统计或远程控制权限；不改安装中的 Arkme 客户端、Codex 配置或系统隐私权限。

## 验证边界

自动化覆盖真实 Python Hook（临时 Codex 目录）、两种授权先后顺序、来源确认与 Sync 共用 UUID、原团队归属、持久化退避/永久拒绝、账号切换/迟到响应、状态响应类型校验、HTTP 200 业务失败、非 JSON 403、稳定入口缓存，以及来源名称界面校验。测试使用模拟云端，未发送真实业务数据或绕过 Hook 信任。

后端上线后还需跨设备验收：A 获得 Hook＋授权但不上传任务，B 同账号 status 为 true、入口显示而任务仍为空；同时核实离队后的历史资格与团队数据权限互不混淆。自动化、构建通过不等于完成生产联调。

2026-10-01 合并前验证：不含工作区频道预览改动的独立副本全量回归 849 个文件通过、11 个文件跳过，10,028 项通过、15 项跳过、0 失败。类型检查、构建、打包和差异检查通过。3100 独立预览已更新，保留登录与原有记录；未修改安装中的客户端，未开启真实云端上传。生产跨设备验收仍遵循上述边界。