## 4. 技术设计（Technical Spec） > 本版技术设计基于最新产品设计重写： > > - 身份模型使用「human: `targetId=member.id + displayName`，agent: `targetId=agents.name + principalId=agents.id + hidden member_id + displayName=members.display_name`」，其中默认 human-visible Web UI 统一显示 canonical display label；detail / inspect surface 可展示带标签的 id metadata；`users.name` 只保留为 legacy alias > - 产品模型按 `Role / Agent / Instance` 理解：Role 是可版本化资产，Agent 是 workspace actor，Instance 是 machine-bound runtime；Instance 的临时状态由 daemon runtime 管理 > - 消息系统按 **IM + append-only thread log** 来建模；严格受限的 rewind 通过服务端 `rewound` lifecycle tombstone/scrub 让 target+suffix 从普通读路径消失，而不是裁剪主 transcript 行 > - 消息存储采用 **TiDB 热数据 + 冷历史归档（Archive Storage：filesystem / S3）** 的双层结构，目标是明显降低数据库长期负载与成本 > - daemon 一方实现与外部 daemon 差异分析边界统一由 `specs/daemon/daemon.md` 约束 ### 4.1 架构总览（单体优先，围绕 append-only log 简化） 单个 Go 服务（`agentteam-server`）同时提供： - **HTTP API（public）**：给 Web / CLI 使用，负责 workspace / member / channel / dm / machine / agent 管理 - **HTTP API（internal）**：给 agent runtime（经本机 MCP chat-bridge）使用：`/api/v1/workspaces/:workspaceId/agents/:agentId/runtime/*` - **WebSocket（control plane）**：给 machine daemon 使用：`/api/v1/workspaces/:workspaceId/daemon/connect?key=...` - 冷历史对象和读取兼容能力继续由 Archive Storage（filesystem / S3）提供；消息写入侧当前不运行冷归档 worker #### 4.1.1 当前实现代码位置索引（As-Is） > 目的：把本文“技术设计”与仓库真实落地点绑定在一起，避免后续演进导致文档漂移。 - 进程入口：`cmd/agentteam-server/main.go` → `internal/app/app.go` - 显式数据库 schema 初始化入口：`cmd/agentteam-schema/main.go` - 配置与环境变量：`internal/config/config.go` - HTTP 路由装配 + 健康检查：`internal/api/router/router.go` - Public HTTP API（`/api/*`）：`internal/appapi`（路由：`internal/appapi/handlers.go`；handlers：`internal/appapi/handlers_*.go`） - Owner-private agent context uses parent channel/thread/task targets plus authenticated server-side context. User-facing entry points are channel private-agent collaboration and Task execution surfaces. - Socket.IO realtime（`/socket.io/*`）：`internal/appws`（路由：`internal/appws/routes.go`；rooms：`internal/appws/rooms.go`） - Internal Agent API（workspace-scoped Agent Runtime，daemon/chat-bridge）：`internal/api/agent`（路由：`internal/api/agent/routes.go` + `internal/api/agent/api_*.go`） - Workflow canonical object chain：`Plan → Binding → Invocation → Run`；HTTP ownership 位于 `internal/api/workflow/{plan,binding,invocation,run}`，持久层位于 `internal/store/workflow/{plan,binding,invocation,run}`，领域与执行器位于 `internal/workflow/{plan,binding,invocation,run,orchestrator}`，共享 Web Builder/运行页位于 `web/src/agentteam/workflow`。Web collection surface 由 `WorkflowHubLayout` 持有固定 Header 和 Overview/Workflows/Schedules/Runs Router Tabs，四个一级集合页同步提供真实 Filter Bar，路由或数据 Loading 只替换下方 Body；一级 Workflow rail 不再拥有二级 sidebar。`GET /api/v1/workspaces/:workspaceId/workflow/calendar?from&to` 由 `internal/api/workflow/run`、`internal/workflow/calendar` 与 `internal/store/workflow/calendar` 实现：在一个只读一致性快照内读取窗口 Run 和 active Schedule cursor，返回真实 Run 与未接受的 Schedule occurrence；31 天/5000 项预算超限时显式拒绝而不截断。Web Overview 直接读取该完整窗口，按 Invocation occurrence 排列 Run 与未来 Schedule occurrence；“仅我的”范围遍历 Plan 游标并按 `createdBy.memberId` 解析，不继承 Run/Plan 单页上限。旧 Workflow document/API/worker/runtime、task-event activation 和旧 ledger tables 已退出产品边界，不保留 fallback；完整契约见 `specs/workflow/agentteam-workflow-platform.md`。Run 冻结 `workflow_run_instances.team_id`（varchar(255)）来自服务端唯一受权来源：Team-linked Plan 的 approved+activated+非删除 `workspace_team_workflows` relation，或 unlinked/dynamic `invoke` 的显式、服务端校验调用者成员身份的 `teamId`（linked relation 冲突即拒绝）；不可从可见文本/callback 伪造。成员上下文在消息写事务内、任何持久化/fan-out/wake 副作用前对 responder 授权并原子写入 metadata/outbox receipt（零副作用 fail-closed），callback/retry/recovery/replay/fan-out 复用同一 frozen snapshot；最小 per-responder 上下文（team identity/purpose、`teamMemberId`、role label、role overlay，空 roster，不含 wake/分工）经 delivery TeamContext 与 Step get DTO/CLI/Desktop 贯通。 - Schedule execution / management（definition polling、automation run dispatch、browser routes）：`internal/schedule` + `internal/store/schedule` + `internal/api/schedule`；稳定的 Trigger API facade 由 `internal/trigger` 转发到 canonical Schedule store，不读取旧 Trigger 表或解析旧 id - AgentTeam MCP schedule facade tools：`desktop/internal/channel/agentteam/mcp_tools_schedule_compat.go`（保留旧 `trigger_*` tool wire names，内部只转发到 canonical Schedule API） - Schedule Web management UI：`web/src/agentteam/workspace/triggers-route/TriggersRoute.tsx`（canonical route：`/schedules`；稳定 `/triggers` facade；共享 helpers：`web/src/agentteam/workspace/triggers-route/triggers.ts`、`web/src/agentteam/workspace/triggers-route/messageSourcePresentation.ts`） - Service Actor substrate（App 统一安装态、能力、授权、target binding、webhook endpoint 基础表）：`service_definitions`、`service_installations`、`service_members`、`service_connections`、`service_grants`、`service_principal_authorizations`、`service_capabilities`、`service_target_bindings`、`service_webhook_endpoints`；当前 App API 仍是 facade，后续逐步切到这些 service_* 表。 - Service Actor store：`internal/store/serviceactor` 是 service_* 表的主数据访问层，并已挂到 `internal/store.Graph.ServiceActor`；它直接读写 service actor 表，不从 App 旧 store 反向取真值。 - App service-event subscription API：App page main path uses `/api/apps/.../service-event-subscriptions` and `internal/store/app` canonical `ServiceEventSubscription*ForUser` methods；stable `/provider-watches` routes and DTO aliases remain product facades over the same canonical service-event rows. Create/list/lifecycle and webhook dispatch read `service_event_*` rows directly with no Trigger-table replay, alias, or projection. - Historical Service Actor backfill：`00166_service_actor_app_backfill.sql` remains migration history for onboarding existing App rows into `service_*` tables; current runtime does not invoke it, reverse-project, or depend on old App tables during rollout. - Daemon WebSocket（`/api/v1/workspaces/:workspaceId/daemon/connect?key=...`，control plane）：`internal/api/daemon`（路由：`internal/api/daemon/routes.go`；Hub：`internal/daemonws/hub.go`） - Core shared primitives：`agentteam-core/domain`（messaging / identity types + validation）、`internal/core/identifiers`（ID generation）、`internal/core/secrets`（token/hash helpers）、`agentteam-core/access`（workspace membership / channel / DM / reply-thread / visible-thread lookup、`workspace` / `channel` / `dm` / `thread` 等稳定 human authz 动作，以及 `AuthorizationRequest/Decision` + decision source / deny code contract）、`internal/store/message`（channel/DM/reply-thread access、channel/DM/member projection、DM create/reuse、agent target resolution、reply-thread open/list）、`agentteam-core/workspace`（workspace bootstrap rules，包括 slug 与 `#all` seed）、`internal/store/agent`（daemon control plane 的 machine/agent auth + start/disconnect primitives） - 数据访问层（TiDB + 冷历史读取）：以 `internal/store` 为主（消息写入位于 message/store domain，冷历史对象与 driver 位于 `internal/archive`）；workspace bootstrap 与 daemon runtime auth/start/disconnect 已迁到 `internal/store/{workspace,agent}`，message-space access/target resolution 与 channel/DM projection/open-list 已迁到 `internal/store/message`，`internal/store` 保留兼容 adapter - Task board 领域：`internal/store/taskboard/*`（list/get/create/update/set-claim/checkpoint、Task detail/review/activity），运行时使用 `coredb.DB` 与当前 Task schema。 - TiDB test helper + request-path regressions：`internal/coredb/testkit/tidb.go` / `internal/coredb/testkit/tidb_runtime.go`（优先复用 `AGENTTEAM_TIDB_TEST_DSN`；若裸跑单个 `go test` 包且未显式提供 DSN，则检查本机 `~/.tiup/components/{pd,tikv,tidb}/` 二进制是否完整，必要时用 bounded `tiup install --force` 补齐，再自举共享 `TiUP playground` 的 `TiDB + TiKV + PD` runtime，并继续给每个测试创建隔离 TiDB database）、`internal/tidb/*_test.go`（admin/migration）、`internal/app/tidb_integration_test.go`（app startup）、`internal/store/taskboard/tidb_integration_test.go`（Task create/list/detail/update/claim/review/activity）、`internal/store/tidb_integration_test.go`（human send + list/sync + agent delivery/history）、`internal/api/org/*_integration_test.go`（org member/team/unit/grant/credential/Feishu sync 主链路） - Org provider runtime：`agentteam-org/service.go`、`agentteam-org/verify.go`、`internal/app/app.go` 已把 org service construction / verify / startup wiring 收敛到 TiDB-only `coredb` seam；当前 main-path 与 enabled `agentteam-org` 已统一走 TiDB - Agent local memory：runtime-local recovery memory 位于 agent workspace，布局为 `MEMORY.md` + `state/` + `kb/` + `archive/`；可迁移角色知识属于 Role package（`IDENTITY.md`、Skills、Knowledge），不与 local memory 混用。 - Core schema：`internal/tidb/bootstrap.sql` + `internal/tidb/migrations/*.sql`（fresh DB 先用 bootstrap snapshot，后续再应用 baseline 之后的 versioned migrations；`VerifySchema` 继续对 core + enabled provider 做完整性校验） - Workspace placement cutover：`workspace_placements` 缺失时 data-plane admission fail-closed；历史 workspace 由 versioned migration 与 `agentteam-tidb-admin workspace-placement-backfill` 只补缺口，现有 placement 不被覆盖。production/staging activation 及 legacy `deploy-main` 均在 service restart/traffic 前执行 `agentteam-schema init → workspace-placement-backfill → workspace-placement-verify`，verify 失败即停止部署。 - 冷归档存储（filesystem/S3）：`internal/archive`（drivers：`internal/archive/filesystem.go`、`internal/archive/s3.go`） - Web E2E 专用后端：`cmd/agentteam-e2e-server/main.go`（Playwright 通过 `make e2e-web` 启动；当前注入 Schedule execution service，并保留稳定 Trigger-shaped API facade 以覆盖浏览器回归） - 仓库内置 desktop client 模块：`desktop/`（入口：`desktop/cmd/agentteam/main.go`；使用说明：`desktop/README.md`） - 共享 Browser/Desktop 业务前端：根 `web/` 是唯一 React 业务应用；Browser/Desktop 通过薄 entry 注入 Runtime contract，共享页面统一调用 server API。Electron 将 Desktop renderer 打包进 `app.asar`，Go daemon 不嵌入 Web 静态资源。 补充说明： - `desktop/` 是随仓库追踪的一方 desktop client 实现；用户默认接入命令是 `agentteam daemon`。 - Desktop 本地 HTTP 控制面只使用 `/api/internal/*`。active server 由 `GET/PUT/DELETE /api/internal/servers/active` 按认证后的窗口/UI session 隔离并携带递增 generation；它不是 daemon 进程全局状态。 - Desktop UI session 由 Go daemon 持有稳定 logical identity 和短期 bearer lease；Electron main 是唯一 lifecycle owner，统一处理 bootstrap、定时续租、息屏恢复、解锁、窗口聚焦及 renderer 上报的本地 `401`/`4401`。同一 daemon 下 bearer 更新只热替换 Web transport，不重建 Router、QueryClient 或业务 UI；旧 bearer 仅保留到原到期时间，logout/revoke 撤销同一 logical session 的全部 generations。daemon instance/base URL 变化才受控 reload，失败请求不自动重放 mutation。退出先关闭 reconcile admission、join 已开始的 daemon recovery，再 revoke。 - Electron 与 daemon 的本地控制协议为 Desktop API v2；新版只把已退役 v1 receipt 用于认证升级：无存活 Electron owner 时 adopt、shutdown 并替换 sidecar，owner 仍存活时要求用户完全退出旧版后重试，CLI/service owner 不由 Electron 替换。 - Desktop gateway 依次匹配构建 manifest 静态资源、`/api/internal/*`、HTML SPA navigation，最后把其余 HTTP/WS/SSE 按原 path/query 转发到当前登记 server。该 catch-all 覆盖 AgentTeam、MeshX、Git、文件等 server 路径，不引入 `/api/remote/*` 或 `/api/v1/*` 白名单。 - Browser 与 Desktop 的 Machine、Agent、消息、统计、activity、files 数据都使用同一 server API 语义。远程本机数据由 Server 通过 typed daemon transport 获取；客户端不直连远端 `/api/internal/*`。稳定边界见 `specs/daemon/desktop-architecture.md` 与 `specs/web/runtime-host-boundaries.md`。 运维健康检查端点（As-Is，**非**公开产品契约的一部分）： - `GET /healthz`：进程存活检查，固定返回 `200 { "status": "ok" }` - `GET /readyz`：就绪检查（2s 超时）；要求当前 core backend 可连通、没有 pending migration，且 schema 校验通过（`coredb.Admin.RequireSchemaCurrent`）；失败返回 `503 { "status": "degraded", "error": "..." }`，成功返回 `200 { "status": "ready" }` 核心原则： - **消息的权威状态在服务端**，但不等于“所有历史永远放数据库里” - **每个 thread 本质上就是 append-only log**：Channel 是一条日志，DM 也是一条日志；服务端协调成功的 rewind 会把目标热后缀写成 `rewound` lifecycle tombstone 并 scrub 派生投影，普通 edit/recall/rewind 都不依赖客户端本地删缓存 - **TiDB 只保留元数据 + 热消息正文**；冷历史是不可变归档对象，存到冷历史归档存储（生产部署建议 S3，本地开发/测试常用 filesystem） - **不做多副本，不做高可用，不做分布式锁**；首版按单实例做扎实 - **不引入 Redis / SQS / Kafka / DynamoDB / OpenSearch**，避免把一个简单 IM 做复杂 - daemon 只负责本机 agent 生命周期与工作区；`deliver` 只做提示/唤醒，不承载可靠消息队列语义 这个模型特别适合本项目的原因： - 最近消息几乎永远是热数据 - 消息默认 immutable：不支持普通原地 edit / delete；reaction 作为消息附属状态单独建模，不直接回写消息行；严格受限的 rewind 只通过 `rewound` lifecycle tombstone/scrub 让热后缀不可见 - channel access 仍刻意保持简单：`#all` 自动加入，普通 channel 以 membership 为唯一读写边界；`public` 只额外开放 discover/join metadata，不引入每消息 ACL - 默认访问路径是“看最新一页、再向前翻”，而不是“从头扫完整个历史” - 因此没有必要把数据库当作永久消息仓库 ### 4.2 AWS 最小部署方案（面向 solo-maintainer） 首版推荐最小 AWS 组合： - **EC2 单机**：跑 `agentteam-server` - **TiDB（单集群）**：存元数据与热消息 - **S3**：存冷消息归档对象 - **SES**：注册 / 邀请 / 邮件验证 可选但非必须： - **SSM Parameter Store**：放应用配置 - **CloudWatch Logs / Metrics**：集中日志与基础监控 首版明确不使用： - ECS / Fargate - ALB / API Gateway - Cognito - Redis / ElastiCache - SQS / EventBridge - DynamoDB - OpenSearch - Kafka 为什么这样更合适： - 你已经明确接受**单实例、可中断升级**，那就没必要为了“未来也许会扩容”先上容器编排与负载均衡 - daemon 和 agent 本身就会反复重连 / pull，天然比传统 request/response Web 更能容忍短暂中断 - 把复杂度留在应用内可控边界，比把复杂度外包给一堆 AWS 服务更符合这个项目的规模 部署建议： - EC2 上用 `systemd` 管理 `agentteam-server` - TLS 直接在实例上的反向代理终止（例如 Caddy / Nginx）；这样不需要 ALB / ACM - EC2、RDS、S3 放同一 Region，减少延迟与跨 Region 传输成本 - S3 bucket 使用通用 bucket 即可，不需要引入额外 S3 变种能力 - 冷消息归档对象默认放 `S3 Standard`，成本已经足够低，先不需要使用 S3 Lifecycle 降低复杂度 ### 4.3 鉴权与身份（Human vs Machine vs Agent） 实现位置（As-Is）： - Auth HTTP：`internal/appapi/handlers_auth.go`（路由：`internal/appapi/handlers.go`） - Auth store：`internal/store/app_auth.go`（会话/refresh/token/用户变更） - 密码哈希：`internal/passwords/argon2id.go` - Token/secret：`internal/core/secrets/*` - Mail driver：`internal/mailer/mailer.go`（driver 装配：`internal/app/app.go`；是否要求验证：`internal/config/config.go`） #### 4.3.0 权限边界约束（Aligned） 按 `docs/architecture-spec.md` 与 `specs/organization/organization.md`，当前 core 的权限边界必须保持收敛： - core 只负责： - human 认证与 session/token - workspace membership - channel / DM / thread 可见性 - act-as 规则 - agent / service capability issuance - 当前权威事实仍然是： - `users.is_admin` - `members.workspace_role` - `scope_memberships` - DM scope 的 canonical `identity_key` 与双方 membership - `machines` / `agents` - 新的 org ownership 目标要求 core schema 承载最小 organization ownership： - `workspaces.organization_id` 是 workspace owning organization 的唯一事实来源 - `organization_settings.default_workspace_id` 是 organization 默认 workspace 指针 - 完整 enterprise governance provider 仍然可选；core 不应引入通用 `roles` / `role_bindings` 或覆盖全系统的 `authz_resources` - 当前 org 目标模型已明确为：最小 ownership 属于 core storage baseline；`organization -> member/team/unit -> workspace grant` 作为治理能力叠加到现有 workspace runtime primitive 之上。 - 当前代码落点已完成 ownership refactor 的 binding 清理阶段：TiDB schema / bootstrap 已引入 `workspaces.organization_id` 与 `organization_settings.default_workspace_id`，workspace 创建 helper、organization store 读写路径、auth 默认 workspace bootstrap、organization workspace 创建 API、`POST /api/v1/workspaces` 显式 `organizationId` 创建、Web 组织工作区创建 UI 已切到 owning organization；`organization_workspace_bindings` 仅作为历史迁移 `00108` 的输入存在，并由后续 cleanup migration 删除，不再是 runtime schema 或兼容写入表。 - 当前仓库里的 `agents` 表仍然是 workspace-scoped installation projection；组织成员授权不会隐式创建或安装 org 级 agent。 - workspace switch 继续以 `/api/v1/workspaces/:workspaceId/*` path identity 为准；org provider 只影响“哪些 workspace 对当前 human 可见”，不引入额外 org 级 request context。 - 当前 org 实现状态（As-Is）： - organization store 已落地 organization/member/team/unit/provider schema 与 workspace ownership / effective grant / revoke-reconcile / status-gate 逻辑；`workspaces.organization_id` 是业务 source of truth，workspace binding 表已从 runtime schema 清理 - organization human membership 的事实源已收敛到 `organization_members`；workspace invite 会显式创建 owning org membership，但不会重新启用已停用的 org member；active workspace human member 必须拥有其 owning organization 下的 active organization member - authflow 已通过 organization store 执行默认 workspace bootstrap；identity store 不再直接创建 workspace，也不再持有 workspace 创建依赖 - `agentteam-org/` 现已补齐 provider 侧 org governance backend 基线：`organization_invites` schema、invite create/list/revoke、token-based accept、org admin/member role update；加入 organization 仍不自动加入全部 workspace，workspace access 继续由 member/team/grant 编排 - `internal/appapi` 已暴露 `/api/orgs/*` 管理已有 organization 的入口；web 端已具备 Organizations route、workspace Settings 中的 “Add from Organization”、workspace picker/sidebar org attribution、direct/team grant revoke、organization-owned workspace 创建；浏览器用户不再自助创建 organization，workspace bind/unbind UI/API 已从组织工作区主路径移除，workspace chooser 的创建入口也要求选择 organization - `/api/auth/invite-info` 与 `/api/auth/accept-invite` 现同时支持 workspace invite 与 organization invite token，保持统一 `/?invite=` 入口；但 org invite 的发送/管理 UI 与对应 Web E2E 仍属于 post-MVP 治理收尾项 - Web 回归已覆盖 org 主旅程、回收旅程与状态门禁旅程；repo 级 `make e2e-web` 当前保持 green baseline - 当前 TiDB org portability 已完成：app startup、provider construction、schema verify、以及 `/api/orgs/*` 主链路都已经可以在 TiDB-backed deployment 上复用同一套 business path；本地 org-enabled smoke、rollback recipe、以及 performance/release-gate evidence 也已补齐。当前 canonical 口径需要写成：TiDB 已支持 `core main-path + enabled agentteam-org`；当前仓库还不能把 deployment 叫成 `operator-ready` 的原因仍是外部 operator gate：socket-capable org-enabled rollback live rerun transcript + target-deployment owner / observability / backup-restore sign-off - JWT 只承载认证事实；跨服务信任的长期方向是短期 capability token，而不是把授权快照塞进 human token。 - `agentteam-core/access` 当前已固化 `AuthorizationRequest` / `AuthorizationDecision`：human 侧除了 workspace/channel/dm/thread 以外，也开始显式覆盖 `machine.manage`、`agent.operate`、`agent.read_workspace`；`users.is_admin` 也开始通过显式 `system_admin` break-glass request 固化 `workspace.access` contract，而不是默认混进普通 human membership 路径；runtime token 主语则通过 `agent_self` / `machine_self` decision source 固化 `agent.act_as_member` 与 `machine.connect` 语义；service capability 路径也已开始通过 `service_grant` decision source 固化 `service_installation.invoke` 的 installation / scope / act-as contract。store 适配层仍然向上翻译为兼容 API 的 `ErrForbidden/ErrNotFound`，但 core 内部决策已经带上 `decision_source`、`deny_code`、resolved principal/member，用于后续 act-as 与 provider/capability 收敛。 - `internal/store/access/scope_target_contract.go` 是当前消息域 target/access typed contract 基座：`ResolvedScopeTarget` 显式区分 requested target、storage/delivery/read/parent scope、authority subject 和 permission basis，供后续 attachment、agent send/history、service-event delivery、reaction/activity resolver 逐步替换旧的 generic `spaceID` / fallback 链。 #### 4.3.1 Human（人类用户） 人类用户鉴权完全走 **AgentTeam 自己的服务 + SES**，不依赖 Cognito。 首版建议直接采用最朴素的邮箱密码模型： - 注册：`email + password + name`；系统初始化后默认由 `AGENTTEAM_AUTH_REGISTRATION_MODE=invite_only` 控制为邀请制，可用 `AGENTTEAM_AUTH_REGISTRATION_ALLOWLIST_EMAILS` 放行少量邮箱 - 密码存储：服务端只保存 `password_hash`，使用 `Argon2id` - 邮箱验证：当配置要求验证时，服务端生成一次性 verification token，经 SES 发邮件 - 登录：校验邮箱密码；当配置不要求验证时，允许未验证用户在首次登录时自动补齐 `email_verified_at` - PingCAP / AgentTeam User Center OIDC：userinfo 可通过 `email` 或已验证 `phone_number` 识别账号；当邮箱缺失但手机号已验证时，本地用户允许 `email=NULL`，并保存规范化后的 `users.mobile` 与 `mobile_verified_at` - 会话：登录/注册成功后签发 `accessToken` + `refreshToken` - public API：`Authorization: Bearer ` - 刷新：`POST /api/auth/refresh` 轮换 `refreshToken` 并签发新的 `accessToken` + `refreshToken` - 退出：`POST /api/auth/logout` 撤销当前 session（若提供 `refreshToken` 也会一并撤销） - 二维码登录的移动端 token 归属于 `user_session_families` 会话族；刷新继承原会话族，主动退出或账户端远程撤销会立即阻断该族的 access/refresh token - 账户安全入口通过 `GET /api/v1/me/mobile-sessions` 列出当前用户的有效移动端登录，通过 `DELETE /api/v1/me/mobile-sessions/:sessionFamilyId` 远程退出指定设备 - 密码找回：`POST /api/auth/forgot-password` 发起重置，`POST /api/auth/reset-password` 消费 token 重置密码（重置会撤销该用户的所有 session/refresh token） - 登录/注册成功后会确保个人 workspace + `#all` + human member 存在（幂等） public HTTP API（`/api/*`）约定（当前实现）： - 鉴权：`Authorization: Bearer ` - workspace 选择： - `/api/v1/workspaces/:workspaceId/*`：workspaceId 在 path 中 - `X-Workspace-Id` 只作为仍需要它的业务上下文 header；不再作为旧的无版本 workspace route fallback - 当前 workspace 选择与 workspace members/usage 等入口已统一走 `agentteam-core/access` 的 `workspace.access`，不再在入口层重复手写 human membership 查询 - workspace member role update 也已收敛到 core 的 `workspace.manage_member_roles`，保持 owner-only 语义而不再依赖 store 层特判 - 错误体：`{ "error": "..." }`（少数场景额外带 `code`） - public config：`GET /api/public/config`（无需鉴权）返回 `{ passwordAuthEnabled, pingcapAuthEnabled, registrationMode, messageHistoryDays }` - `messageHistoryDays` 为当前 public config 的稳定 wire 字段名；其值对应内部的“hot message retention window”，仍由 `AGENTTEAM_MESSAGES_RETENTION_DAYS` 提供（见 4.4.4） - 当前实现额外提供一个 product-specific thread inbox 入口： - `GET /api/threads`：返回当前 human member 已订阅的 reply thread scopes 及其父消息/父频道元信息 - `POST /api/threads/:threadChannelId/subscribe`：为当前 human member 主动恢复 / 建立该 reply thread 的 inbox 订阅 - `POST /api/threads/:threadChannelId/unsubscribe`：将当前 human member 从该 reply thread 的 inbox 中移除 - 这组接口是 additive divergence，不改变已有 `/api/channels/:channelId/threads` 的 open/list 语义 为什么这里不用 magic link 作为主方案： - 产品设计（`SPECS.md`）已明确首版登录方式是“邮箱 + 密码” - magic link 当然也能做，但它会把登录、设备切换、邮件时效、重复点击等细节重新引入为主链路复杂度 - 对当前项目来说，自建邮箱密码 + SES 验证邮件是更直接、更稳定的最小方案 推荐的 auth 相关表（token 均以 `SHA-256` 存 `*_hash`）： - `users` - `id`, `email`（PingCAP phone-only 用户可为 `NULL`）, `name`, `display_name`, `avatar_url`, `is_admin` - `password_hash`, `email_verified_at`, `mobile`, `mobile_verified_at`, `created_at`, `updated_at` - `user_email_verification_tokens` - `user_id`, `token_hash`, `expires_at`, `consumed_at`, `created_at` - `user_sessions`（access token） - `id`, `user_id`, `session_family_id`, `token_hash`, `expires_at`, `created_at`, `revoked_at` - `user_refresh_tokens`（refresh token） - `id`, `user_id`, `session_family_id`, `token_hash`, `expires_at`, `created_at`, `revoked_at` - `user_session_families`（二维码登录的移动端会话族） - `id`, `user_id`, `client_type`, `installation_id`, `device_name`, `device_platform`, `expires_at`, `created_at`, `revoked_at` - `user_password_reset_tokens` - `user_id`, `token_hash`, `expires_at`, `consumed_at`, `created_at` 系统初始化（bootstrap admin）： - DB 中是否存在 `users.is_admin=TRUE` 视为系统是否已初始化 - 若未初始化，`/api/auth/register` 会创建首个 admin（`is_admin=TRUE`，且直接视为已验证邮箱） - 初始化完成后，后续注册均为普通用户（`is_admin=FALSE`） 本技术设计后续章节只依赖以下事实： - 除 `/api/auth/*` 外，public API 的主要路由默认要求用户已完成邮箱验证（`email_verified_at != NULL`） - 服务端可识别稳定的 `user_id` - 一个 user 可以属于多个 workspace，并在每个 workspace 下拥有一个 human member #### 4.3.2 Machine（daemon） - daemon 通过 WS：`/api/v1/workspaces/:workspaceId/daemon/connect?key=` - `machineApiKey` 是长随机串，只用于 machine 鉴权 - 当前实现将 key 明文存储在 DB（刻意简化），但 public API **不提供 reveal 旧 key**：完整 key 仅在创建/rotate 时返回（列表只返回 prefix） 因此第一版 `machines` 表对 key 的持久化直接使用单一字段： - `api_key` 服务端行为： - 创建 machine 时生成高熵随机 `machineApiKey`，原样写入 `machines.api_key` - 校验 workspace-scoped daemon connect 时，直接按 `api_key` 精确查询 machine 并核对 path workspace - 创建与 rotate 时返回完整 `machineApiKey`；平时列表/详情仅返回 `apiKeyPrefix`（避免把旧 key 反复暴露在 UI/API） - daemon 收到 `401 {"error":"invalid machine api key"}` 时，将该 machine connection 视为本地 credential 已失效并停止该连接循环； 用户需要通过 Web connect flow 或新的 `agentteam daemon --server-url ... --api-key ...` 重新写入有效 key。 为什么这版可以接受： - 你已经明确要求第一版优先简化，不再引入 key 加密与 master key 管理 - `machineApiKey` 是服务端生成的高熵随机串，不是用户口令，不存在被穷举验证的产品路径 - 当前系统是单实例、低运维复杂度优先，直接明文存储能显著降低实现与运维心智负担 需要明确写下的代价： - 数据库一旦泄露，所有 machine key 都会直接暴露 - 因此这只是**第一版的刻意简化**，不是长期理想状态 - 如果未来风险要求提高，优先升级为“可 reveal 的加密存储”；到那时再引入主密钥管理 安全约束： - 生产环境必须强制 `wss` - 访问日志必须脱敏 query string - 同一个 `machineApiKey` 同时只允许一条活动 WS 连接 - owner 可以 rotate key；rotate 后旧 key 立即失效 - 注意：仅更新 DB 不能让“已建立的 WS 会话”立即失效；rotate key 必须**主动断开**该 machine 的现有 WS 连接，迫使 daemon 用新 key 重连 #### 4.3.3 Agent / Instance（runtime data plane） chat-bridge 会对 workspace-scoped Agent Runtime 请求带上： - `Authorization: Bearer ` 当前实现里，各 runtime 的驱动实现和能力如下： | 能力 | `claude` | `codex` | `opencode` | `kimi` | |------|----------|---------|------------|--------| | 进程模型 | stream-json CLI process | 长生命周期 app-server JSON-RPC 进程 | headless `opencode serve` process | 长生命周期 Wire JSON-RPC stdio process (`kimi --wire`) | | 消息投递 | idle 时 stdin；active-turn 可走 ack-aware pending stdin | state-aware `turn/start` / `turn/steer` / single resume，以 `clientUserMessageId` 绑定 durable ownership，等 `userMessage.clientId` surfaced ack | 仅在 authoritative idle 后调用 headless `prompt_async`，以 fresh monotonic `messageID` 绑定 ownership，等 exact assistant `parentID` ack | idle/new-turn 使用 Wire `prompt`；`TurnBegin` 确认对应输入已进入 runtime | | busy-turn 投递 | pending stdin + `--replay-user-messages` correlated ack 后完成 ownership | durable pending/uncertain steer；只在 correlated ack 或 authoritative absent reconciliation 后结束 ownership | 不直接写 OpenCode；保留在 daemon durable FIFO，待 idle 后作为新 turn 递交 | Wire `steer` 入队，后续 `SteerInput` applied event 才完成 correlated surfaced ack | | rewind | capability-gated `--resume-session-at` | deprecated `thread/rollback` compatibility；迁移目标为 `thread/fork` + session-id rebind | capability-gated native revert | capability-gated completed-turn restore | | rewind restore 方式 | 原生 `--resume-session-at`，before-first-input 用 fresh session boundary | 当前兼容路径使用 deprecated `thread/rollback`；不能把会生成新 id 的 `thread/fork` 原地替换，需先升级 restore/session persistence contract | 原生 `/session/:id/revert`；fork 不是 rewind strategy | detached-only、fail-closed 原子截断同一 session 的 `wire.jsonl` / `context.jsonl` | | idle-compaction checkpoint | overflow 后 `/compact`；普通 idle no-op | 普通 idle 达共享 active-context threshold 后对同 thread 调用 `thread/compact/start`；overflow 也复用该 mutation 但保持 emergency purpose | 普通 idle 可按 active-context signal 调用 `/session/:id/summarize`；overflow 也复用 summarize | 仅 runtime-native compaction lifecycle | | 流式输出 | stdout stream-json | 原生 notification（`item/agentMessage/delta` 等） | SSE translated events | Wire `event` notification translated events | - proactive idle-compaction 的 Workflow boundary 由 `desktop/internal/agent` 的 `WorkflowCompactionGate` 随 exact Process generation 持有，并通过同一对象连接 model-visible runtime surface 与 Exec 的 Server-authoritative terminal result。Awaiting Step（包括穿插普通 turn）禁止 proactive check；只有 `workflow step complete` 成功或同结果 replay 允许随后 quiescent `TurnEnd` 检查一次。Fail、已确认 cancel 与权威 terminal error 只清 gate 并跳过对应 boundary；validation、not-ready、pause/park 和 ambiguous failure 继续保持 awaiting。该 gate 不属于 callback authorization、delivery gate 或 `isIdle`，不阻塞后续消息/Workflow Step，也不影响 overflow recovery。 - connector lifecycle：`serverconn.Manager` 在 terminal admission fence 下维护 per-server mutation generation 和 manager-owned lifetime context；Register/Enable/Reconcile 的旧 generation 不得发布或回滚覆盖新 generation，输掉 publication 的 runtime 必须 compensating stop。Stop 的短 deadline 只能让当前 waiter 返回，不能降级 immutable drain owner；同一 drain 会在后台继续并允许后续 strong waiter join。Wire 的每次 Session Link 也有唯一 run owner：所有 pump/handler/refresh/ticker/elastic-link/remote-assignment child 必须先注册再启动，断线或 shutdown 先关闭 admission 并 cancel，strong-join 后再 drain `sendCh`，旧 connection generation 不得向下一代发布 frame 或 catalog mutation - profile persistence：每个 AgentTeam server snapshot 持有单调 revision；update/delete/补偿恢复均使用 exact-revision CAS，避免 A→B→C→B 的值相同 ABA 让陈旧 rollback 覆盖新配置。Dashboard 的 runtime/config transaction 与 Wire 的 workspace/status field-local persistence 都在 revision conflict 后重读 durable file、只重建目标字段并 bounded retry；内存状态只在 durable commit 后更新。Delete 先 suspension exact runtime generation，再按 revision 删除；配置失败时也只能恢复同一 generation，不能复活已被并发操作替换的 runtime - `codex` - daemon 持有的长生命周期 Codex host 进程，通过 stdio transport 与 Codex app-server 建立 JSON-RPC 连接；app-server 是内部实现机制，公开 runtime ID 只有 `codex` - 握手协议：`initialize` request + `initialized` notification（两步必须完成） - 线程管理：通过 `thread/start` 创建新线程或 `thread/resume` 恢复已有线程；维护 `threadID`、`threadStatus`（含 `activeFlags`）、`activeTurnID`、completed-turn/non-steerable/compaction fence 等协议派生状态；Codex 声明 explicit turn lifecycle，只有 authoritative `turn/started` / terminal boundary 改变 root busy/idle - prompt surface：fresh thread 把平台级核心规则与 agent-specific 指令分别放到 `baseInstructions` / `developerInstructions`，只把可被 compact 的 skill reference 和动态消息内容放进首个 turn input；真正 resume 时重放同一 launch-generation policy snapshot，空 optional override 不发送。当前 instructions 发生变化时由 fingerprint 触发 fresh thread，不能把 resume 当成 thread 内热更新 - prompt compiler：`desktop/internal/promptcompiler/*` 现在是 prompt canonical boundary；它负责把 thread contract / turn context / live delivery 统一编译成 `RuntimeInputEnvelope`、`PromptBundle`、`DeliveryEnvelope`，并由 `desktop/internal/dispatcher/prompt_compiler.go` 收集输入后调用 compile/render - Token 诊断：`desktop/internal/tokenanalysis` 是 daemon-owned report/compare owner，`desktop/internal/api/tokenanalysis` 只提供 Human owner 与 Agent self-only adapter，`desktop/internal/cmd/token.go` 提供唯一的 `agentteam token analyze|compare|ui` 入口。详细高基数采集默认关闭、仅属于 daemon lifetime；Human analyze 自动开启，UI 使用同一开关，普通 per-Agent usage 不受影响。存活 Process 只保留无正文 launch attribution 以便开启时补记；delivery attribution 只在 surfaced 或可能已入模时提交。Runtime usage 复用 driver 统一口径：input 是包含 cache read/create/write 的 inclusive total，cached 只是 cache-read 子集，total 不重复加 cached；OpenCode 用 `step-finish` part ID、Kimi 在存在时用 root `StatusUpdate.message_id` 作为 invocation identity，并把 Process active semantic blocks 记录为 invocation exposure；OpenCode 成功 compaction 会先淘汰 `compactable` block，Kimi subagent 不套用 root Context。Codex turn 与 Claude result 不冒充 provider call identity，因此其调用次数和 exposure 仍为 `unsupported`。当前 Run 是 launch-level 聚合，task outcome 与 parent/child edge 仍不支持 - prompt packs：compiler-owned repo prompt sources 已落到 `desktop/prompts/{platform,agent,events,notices,channel}/*.md`，由 `desktop/prompts/prompts.go` embed + render；channel skill docs 与 identity notice wording 也已迁到这些 prompt packs，trace/source-map 现在可直接回指对应 markdown template 路径，而不是继续把 `text.go`、`skilldoc.go` 或独立 formatter 当 source of truth - session migration：daemon 持久化 `baseInstructions + developerInstructions` 的 fingerprint；legacy 无 fingerprint thread 或 fingerprint 已变化的 thread 会直接 cut over 到 fresh `thread/start`，避免已有 thread 继续执行 stale pre-split instructions - 消息投递：router 从 app-server state 选择动作：regular active + turn id 走 `turn/steer`，idle/systemError 走 `turn/start`，notLoaded 最多 resume 一次，unknown/active-no-turn 最多做一次 `thread/read(includeTurns=true)`；read 后仍 active-no-turn 保持 ordered boundary，绝不把 `turn/start` 当 active probe。non-steerable/compaction fence 不被 refresh 绕过。所有 routed start/steer（包括 interrupt-based transient recovery）都把 daemon delivery id 写入 `clientUserMessageId`。单个 concrete input 最多一次 refresh、两次 mutation；ambiguous timeout/EOF/decode/transport failure 第一次 mutation 后立即停止，interrupt expected/found mismatch 最多用 actual id 重试一次。 - delivery ownership：daemon 使用 `queued`、`inflight(dispatching|outcome_unknown)`、`terminal(surfaced|failed)` 三态 journal。同步刷盘只守住三条不可逆边界：daemon ACK 前 durable queued、runtime mutation 前 durable inflight、释放 owner 前 durable terminal；retry/backoff/wake UI 等过程状态不要求磁盘快照持续最新。凡带 concrete `MessageID` 的 default dispatch、`agent:start` wake 和 hidden workflow 都使用这条边界。当前 routed MessageID 是 foreground admission lane：历史 queued/inflight restore 与 reconcile 不能把当前 wake 替换成空 launch或拒绝 durable admission；workflow callback、wake lifecycle 与 transient recovery 仍是 runtime mutation 前的安全 fence，受阻的新 owner 留在 durable queue。Journal 容量为 512 live/8 MiB、512 terminal/2 MiB、1024 total/10 MiB、单条 live 512 KiB；新 MessageID 的首次 live admission（queued 或 direct-mutation 前的 inflight）与 oldest-live→terminal failed reclaim 在同一 state transaction/fsync 中完成，已有 owner 状态转换不选择 reclaim victim，failure code 为 `ownership_backlog_reclaimed`，随后 Process 投影删除 queued owner、保留 inflight 晚到 correlated ack 并发 wake/runtime diagnostic。terminal tombstone 去掉 replay body，failed 可被迟到 authoritative surfaced 升级但不可恢复 live。旧 unversioned ownership schema 在加载时迁移，未知未来版本不做语义猜测。 - 可见回复边界：`turn_direct` 只描述消息进入 runtime 的投递方式，不表示 runtime 纯文本会自动成为 AgentTeam 消息；正常可见回复仍以 `send_message` 成功写入为准。daemon 会记录 `reply_sent` / `completed_without_visible_reply` 证据，不会把 stdout、final text 或本地 transcript 自动 relay 成普通消息。可见回复契约（VisibleReplyContract）始终启用（always-on），prompt compiler 会在后续 wake / resume / delivery 的动态输入中增加可见回复契约指引；该投影不是 runtime policy / thread contract identity，不触发 runtime restart 或 fresh_start。历史 per-account / per-agent 关闭值不再作为有效配置输入，服务端不会基于其下发或响应 false；对仍声明 `agent:visible-reply-contract-v1` capability 的旧 desktop 固定投影 `enabled=true`，历史 DB 中残留的关闭值不再产生有效关闭效果。Daemon 为每条 concrete delivery 保留 `MessageID`、canonical `TargetKey`、target-local `TargetSeq`、delivery class 与终态，但普通 visible-reply obligation 按 target 聚合，不使用逐消息本地凭据结算。只有服务端成功响应 `sent` / `already_sent` 携带 `TargetKey` + `SeenUpToSeq` 时，才批量结算该 target 下已 surfaced 且不超过 frontier 的 obligations；held、失败、本地 AcceptedSeq、旧 frontier 与其他 target 都不结算。更高 seq 在后续边界重新触发 fresh final check；signal-only delivery 不触发普通 final check。若最终仍未 send，相关消息一次性 terminalize 为 `completed_without_visible_reply`（或 `failed`）并释放状态。Context recovery 的 target 规则见 [`specs/daemon/wake-visible-reply-contract.md`](../specs/daemon/wake-visible-reply-contract.md)。 - freshness / reconcile surface：start/steer transport accept 不包含“已入模”语义、不推进 observed；只有 correlated `userMessage.clientId` surfaced ack、daemon 自动递交 fallback target messages、或显式 `read_history` 返回 target coverage 才推进 observed。Ambiguous/restart reconciliation 每次只读一次 old thread 的 full turns/items：matching id=surfaced，active missing id=pending，incomplete history=unknown/pending，只有 complete inactive history missing id=absent；reconciler 不 resume old thread、不内部 poll，且只调度 oldest live head。每个 attempt 捕获 record generation/store attachment epoch；late surfaced 或 phase transfer 递增 generation，陈旧 read 结果不得覆盖 live mutation。unknown/error 有六次短预算，authoritative pending 使用 15 分钟 safety ceiling而不是短 ACK timeout；耗尽只 durable fail，不 blind replay。同 target pending refresh 的 held-like result 仍按 local coverage 提示等待 input boundary 或 exact-target `read_history`；server 不提供 agent `/receive`，daemon journal/inbox 不暴露 agent pull tool - MCP freshness final-hop transaction：本次 freshness page 不再提前写 surfaced。它在同一锁/持久化临界区把 FIFO head 从 queued 变为带 128-bit opaque receipt 的 uncertain，保留原 AgentTeam MessageID/正文作为 canonical owner，并在移出 inbox 前安装 bounded final-hop lease；熵失败或 receipt collision 保留 queued，live receipt 又会阻止第二页 q2 越序。本次 claims 与历史 message-id dedup 分流，receipt marker 前置到 tool text，validated receipts 放入 MCP `_meta` 且穿过 result budget/held-send 外层包装。普通 MCP 只有完整 HTTP response write 才 commit surfaced；Codex HTTP 只返回 Deferred，必须等同 generation 的 app-server JSON-RPC child write 完整成功后才 emit surfaced。short/partial write、stale generation、callback/transport failure转 uncertain；claim-time lease覆盖“claim 返回到 HTTP callback”窗口，Deferred只续租，丢失 callback 在六分钟（长于 Codex 五分钟 request timeout）后进入 exact-thread marker reconciliation。`thread/read(includeTurns=true)` 中 exact marker=surfaced，active missing=pending，incomplete=unknown，只有 complete inactive missing=absent 后才 exact replay - 显式打断：用户希望 agent 停止当前工作时必须通过 UI / API 显式 interrupt 入口，不从消息正文推断；规范见 [`specs/message/agent-interrupt-control.md`](../specs/message/agent-interrupt-control.md) - lifecycle fence：root delta/item/error、async MCP/dynamic callback 与 terminal notification 共享 turn-event serialization；只有 current primary、current turn 且未 completed 的 activity 可发布。`error(willRetry=false)` 保留错误证据并合成一次 TurnEnd，后到 completed 被 consume；late `userMessage.clientId`、usage/settings、subagent control-plane metadata 仍可完成 ownership/观测且不重开 root turn - protocol 状态刷新：daemon 维护 `threadID`、`threadStatus`、`activeTurnID` 等协议派生状态，用于 state-aware delivery、recovery、legacy rollback 和 compaction；本地状态不确定时通过 bounded `thread/read(includeTurns=true)` 刷新。新 `turn/started` 可替换 stale active cache，但 completed same-id started 与 late completed-turn activity 必须被 fence - rewind：额外维护稳定的 app-server `threadId` 与 checkpoint。当前 live/detached restore 仍是 deprecated `thread/rollback` compatibility path；OpenAI Codex 推荐 `thread/fork(lastTurnId|beforeTurnId)`，但 fork 产生新 id，因此完整迁移必须原子 rebind Process/dispatcher/session projection/ownership 后才能删除 rollback - recovery / restart safety：在 `NewProcess`/driver `Spawn`/任何首个 turn mutation 之前先持久化 unsafe baseline；live ownership upsert 同事务置 unsafe，safe promotion 事务再次拒绝任何 live journal owner。Live recovery 优先用 `thread/read` 分层判断状态，必要时 `turn/interrupt` 中断 active turn后调用兼容 rollback；detached recovery 启动临时 app-server 进程后固定走 `thread/resume(excludeTurns=true)` → authoritative `thread/read(includeTurns=true)` → 必要时 interrupt +再次 read →兼容 rollback。`thread/read(includeTurns=true)` 虽可读取 persisted/notLoaded 历史，却不会装载 live ThreadManager；fresh/detached rollback 因此必须在兼容 mutation 前 resume，而 exclude-turns 的 resume response又不能替代 detailed read。Restore 与 delivery 共用 `deliveryGate`，rollback 前同时证明本地容器和 durable journal 无 owner；cleanup 只事务清 resume/recovery 字段并递增 epoch，保留 ownership、deferred、task 与 runtime policy。SessionInit/TurnStarted/handoff/compaction 标 resume-unsafe，只有 no inbox/pending/reserved handoff 的 quiescent authoritative terminal boundary才能标 safe；surfaced ACK清掉最后 pending 后再次尝试 safe promotion。callback 用 versioned snapshot replay防注册竞态。Daemon restart遇到同一 saved Codex thread仍 unsafe时 fail closed创建 fresh thread，但 ownership reconciler可用 record中的 old thread id做read-only查询 - compaction：Codex runtime 仍可根据 active history/model limit 自行 auto-compact；AgentTeam 同时在 quiescent ordinary `TurnEnd` 使用 primary thread 最新 `thread/tokenUsage/updated.last.totalTokens`、共享绝对阈值与 cooldown 做 proactive due check。Driver 用当前 launch、root `threadId + turnId + contextCompaction item.id` 的 exact started/completed pair 观测 boundary：匹配普通 root turn 为 `runtime_native`，匹配 AgentTeam proactive/manual turn 为 `agentteam_proactive`，匹配 terminal-overflow queue 为 `agentteam_emergency`，缺失/冲突为 `unknown`。Started 保存最近 root usage，active item 保存最后 exact-turn usage；completed 后只有第一条 root usage 获得 `ContextCompacted`，foreign/stale usage 不能消费 latch。`contextWindowExceeded && willRetry=false` 只 queue emergency purpose，并把 overflow cause turn 贯穿 queue/start/result/item diagnostics；proactive purpose 不产生 continuation，matching terminal failure 也不重新 queue overflow。App-server 可先发 `thread/status/changed idle`、后发 matching `turn/completed`；driver 只在当前 generation/compaction turn 上 latch 前者，并由精确 matching completion 消费后依次 emit `RuntimeCompacted` 与 `RuntimeIdle`，Activity 明确记录 compact 成功后再进入 idle；exact before/after usage 可用时 completion detail 同时带 active-context token count。Wrong/duplicate/old completion 与 ordinary turn 不消费。Compact mutation 一旦可能写出，timeout/EOF/decode 等 ambiguous 结果保持 fence/non-idle/resume-unsafe，直到 authoritative idle；不能回滚状态后重发第二次 compact - 流式输出：通过原生 JSON-RPC notification 驱动，包括 `item/agentMessage/delta`（文本流）、`item/reasoning/summaryTextDelta`（可见 thinking summary 流）、`PlanDeltaNotification`（plan 增量）、`item/commandExecution/outputDelta`（shell 输出）、`item/fileChange/outputDelta`（文件变更）等；输入 reader 用 `ReadSlice` 累积完整行并执行含换行的硬 `32 MiB` 上限。Translated event 先按最终 JSON wire bytes 计量，再进入 generation-scoped lossless bounded queue；饱和时 backpressure，replacement/cleanup 先 abort 旧 queue，source EOF/malformed 则 seal 并 drain 已接纳输出，Process exit 要等 reader、flusher 与 final-EOF consumption fence，oversize/encode/short-write failure 不能静默 drop。AgentTeam 启动 Codex turn 时按 `AGENTTEAM_CODEX_REASONING_SUMMARY`、用户 Codex `model_reasoning_summary`、`auto` fallback 的顺序解析 summary mode，避免覆盖显式用户配置但仍保持默认 summary 可见。`item/reasoning/textDelta` 是 raw reasoning 流，默认不进入 AgentTeam activity，只在显式开启 raw reasoning 调试时展示 - 原生 thread/turn 协议接入设计见 [`docs/codex-app-server-native-protocol.md`](./codex-app-server-native-protocol.md) - `opencode` - Desktop release artifact 内包含平台对应的 AgentTeam-managed OpenCode 可执行文件；daemon 解析 `builtin` runtime 时使用该 managed binary。缺失、不可执行或 build-time expected version 不匹配时，错误语义是 AgentTeam Desktop 安装不完整，而不是提示用户安装 npm/opencode。`opencode` runtime 表示外部 OpenCode binary，通过 PATH 或手动 binary path 配置使用。 - `builtin` runtime 的 XDG data/state/cache 持久化在 `~/.agentteam/agents//.runtime/opencode/`，每个 agent 独立；dispatcher 通过独立于 launch workdir 的 `RuntimeStateDir` 显式传入该路径，因此 session、ephemeral 与 detached recovery workdir 不会改变或回收 SQLite。启动前按环境变量名大小写不敏感地移除 `OPENCODE_DB`、`OPENCODE_TEST_HOME` 及全部 managed key 别名，再以 canonical key 写回强制配置；其 SQLite 位于对应 `data/opencode/` 下，不与用户安装的 OpenCode 数据库或其他 agent 共用。AgentTeam-managed config 继续使用 agent workdir 内的专属目录。外部 `opencode` 保留用户原生存储与 `OPENCODE_DB` 语义。 - 当前 driver 运行 `opencode serve` headless server，经 HTTP `prompt_async` 投递 prompt，并通过 SSE 翻译 text/tool/status/usage 事件 - headless permission 由共享的不可变 launch policy 在启动时直接配置：full-access（含归一化为 full-access 的旧别名）写入 wildcard `allow`；内部 `DisableNativeTools` restricted launch 写入 wildcard `deny`、只允许 Knowledge namespace。已退役的 `knowledge_qa_scratch` permission mode 不是兼容别名，driver 必须拒绝；server-hosted Knowledge Q&A 不启动 Desktop Agent runtime。正常路径不产生 ask。串行 SSE `permission.asked` handler 仅作为上游变化或异常配置的协议兜底，按同一 policy 单次批准或拒绝；任何非成功 reply 都发出 bounded runtime error 并停止 OpenCode process，由既有 process lifecycle 负责失败、turn end、重启与 queued input 恢复。runtime diagnostics 只记录 request/session/tool correlation、permission 与失败结果，不记录 permission metadata、raw pattern 或 tool input - `prompt_async` 仅在 driver 已观察到 authoritative idle、没有 unresolved correlated input 且没有未确认的 Runner-admission reservation 时提交新正文；active turn 期间消息继续由 daemon durable FIFO 持有。原因来自 OpenCode v1.17.11 源码：`createUserMessage` 的 row/parts 是分开写入，而 `Runner.ensureRunning` 在已有 runner 时等待旧 run 后会丢弃第二个 caller 传入的 work，因此 active `prompt_async` 的 204 不能充当可靠 enqueue。idle 提交时 driver 在 HTTP mutation 前安装通用 Runner-admission reservation，并给正文分配 OpenCode-compatible、不会随本地时钟回拨的 monotonic `messageID`；只有后续 `busy` / `retry` 或 exact assistant `parentID == messageID` 才证明 fork 已进入 Runner。旧 turn 的 prune/tool/part/delta/assistant 更新不能清掉新 reservation。Runner admission 后也不能只凭同 session 或 logical busy 接受 activity。driver 为当前 Runner 维护 user/assistant/compaction/summary message-id 集，assistant 必须 parent 到当前 prompt、当前 compaction 或 source-bound synthetic/replay continuation，tool/step/text part 则必须引用已接纳的 assistant id；不能用 message-id 数值顺序替代这些绑定，因为 OpenCode 的 ascending ID generator 在 wall-clock 回拨时也会回拨。这样上游在 `Runner.finishRun` 后异步发布的旧 `compaction.prune` part，即使晚于下一 turn 的 fresh busy，也不会重新把 driver 置 busy、泄漏旧 tool output 或清掉 late-error fence。204、matching user `message.updated`、`session.error`、`/abort` 200 或 admission 前的 `idle` 都不能清掉 reservation、合成 turn end 或开放第二次 prompt。普通输入只由 assistant 的 exact parent 结算 surfaced ownership；但上游也可能在新 root user 进入 Runner 后先根据上一 finished assistant 触发 automatic compaction，因而永远不创建 parent=root 的 assistant。此时 current-Runner `auto=true` compaction part 是 source proof，driver 原子地把 pending correlation 从 root user 迁移到 compaction user，仍由后续 summary assistant 的 exact parent ACK 结算；即使插件关闭 autocontinue，也不会留下永久 owner。`session.error` 会先作为 nonterminal diagnostic 发出，因为 OpenCode 会在 file/directory 读取失败后把错误转换为 synthetic text 并继续 runAgentTeam；后续 correlated positive activity 会清掉 terminal candidate。若 generic fatal error 保留到 authoritative Runner idle，或仍有 exact-parent correlated owner，driver 会先 invalidate 并停止整个 server generation，再发 terminal error，不把它当成可复用 idle：Runner 可能在创建 assistant parent 之前失败，而 `Runner.finishRun` 还会先发 idle、随后 `prompt_async` 外层 `catchCause` 才发 wrapping error；继续复用会分别造成 correlated owner 永久悬挂或 post-boundary error 把 Process 永久改回 busy。context overflow 是 source-derived 双 idle 状态机：`compaction.auto=false` 时 processor 先发 idle，随后持久化 matching completed/error assistant cleanup，最后 Runner 再发 idle；driver 在第一 idle 保持 logical busy 并 suppress cleanup，只有第二 idle 才发 terminal Error+TurnEnd并允许 native summarize。OpenCode 自动 compaction 成功则以 `session.compacted` 继续原 Runner，不触发 AgentTeam summarize；所有 `summary:true` current-Runner assistant 的 text delta 只用于 OpenCode 内部上下文、不会作为 AgentTeam 回复输出，而后续非 summary continuation 仍正常可见；matching summary assistant 失败会带 `context_compaction_failed` retire/fallback。若 accepted prompt 在 30 秒内始终没有 correlated Runner 证据（包括只有 `session.error` 且没有真实 Runner idle 的 `catchCause` 路径），watchdog 同样停止整个 generation，绝不开放第二次 mutation。native interrupt 在 Runner admission 或 exact-parent ack 未决时 fail closed；其余 interrupt 吞掉上游 `MessageAbortedError → processor idle → cleanup → Runner idle` 整段，cleanup drain 穿过 live revert，直到新 prompt 的 fresh busy/retry 才开放新事件 generation。response-less mutation 保持 `outcome_unknown`；当前 generation 没有 authoritative read reconciler 时等待迟到 exact parent，Process 替换后的 restored owner则 fail closed，任何路径都不 blind replay。 - OpenCode SSE 不提供 replay cursor；driver 从 Spawn 到首个 data frame都关闭新 prompt mutation，并允许在尚未 ready 时重试连接。一旦 ready 后的 stream 丢失，driver 立即停止整个 server generation，而不是连回一个无法补帧的新 stream；若已 dispatch prompt 的 parent/status frame 在断线窗口丢失，其 reservation/owner 保持 fail closed，不能推断 absent 或重发正文，由 Process generation replacement 收敛。所有 retirement 都在同一锁内推进 session/summarize generation、关闭 in-flight summarize retired fence，并在任何可能阻塞的 translated event 投递前执行 process cancel，旧 HTTP/SSE callback 因此不能为 replacement generation 伪造 idle/error/turn end。 - ordinary `TurnEnd` 会在 visible-reply final-check、delivery terminalization、context-overflow recovery 和 inbox drain 之后进入一次 proactive idle-compaction checkpoint。Process 持有与 delivery 相同的 admission gate，并要求无 inbox、pending/uncertain runtime input 或 handoff owner；因此 due check 与 compaction mutation 之间到达的消息只能排在 compaction 后，不能并发写 runtime。OpenCode 与 Codex 都实现同一 capability interface，并使用共享的 active-context 绝对阈值（默认 150,000，`AGENTTEAM_PROACTIVE_COMPACTION_TOKENS=0` 可禁用）和两分钟 cooldown；公共 Process 不按 runtime name 分支。OpenCode 从最新 `message.updated` 读取 input context 并执行 same-session summarize；Codex 从 primary thread 最新 `thread/tokenUsage/updated.last.totalTokens` 读取 active context，在权威 idle 时对同一 thread 调用 `thread/compact/start`，且 runtime-native compaction completion 进入同一 cooldown，避免立即重复 manual compact。Codex overflow queue 始终优先并保留独立 emergency purpose/continuation；matching proactive terminal failure 只作为 maintenance failure 回到同 thread idle，不 queue overflow recovery。成功 compaction 先发 `RuntimeCompacted` Activity/trajectory 记录，再由 `RuntimeIdle` 恢复 idle 并优先投递排队 input；两者都不注入 continuation，也不再次触发 checkpoint。OpenCode proactive failure 在 retire generation 后以 maintenance-tagged、bounded `context_compaction_failed` Error+TurnEnd 收敛；maintenance attribution 要等本次 summarize 的 fresh busy/retry，之前到达的 delayed `prompt_async` wrapper 仍归属上一 turn。Process 不把真正的 maintenance failure 解释成 overflow recovery，不 rotation、不重试已经成功的普通工作。Claude 当前缺少可信 active-context signal，Kimi 缺少 AgentTeam-triggered same-session compact API，因此保持 no-op/native lifecycle。 - OpenCode native summarize 的 HTTP response 与 SSE 是独立证明：driver 从启动到结束持续持有 `summarizeInProgress`，只有 HTTP 200、本 generation 的 `auto=false` compaction part + matching summary assistant、fresh `busy → Runner idle`、以及成功专属的 `session.compacted` 全部出现后才发 `runtime_idle` 并重新开放 prompt。要求本次 summarize 自己的 busy/compaction identity 是因为 Process 消费上一 turn_end 后，SSE transport 里仍可能有重复的旧 idle/compacted frame；旧帧不能提前满足新 fence。HTTP/transport failure、缺任一 SSE success proof、summary/session error、超时或 stream loss一律先 retire generation，再发 `context_compaction_failed` Error+TurnEnd，不把 HTTP 200 或 processor idle当成 compaction success。未能由 Process 启动的 stale `compactQueued`（例如 recovery disabled 或 preflight failure）不会永久挡住后续 prompt；一个成功的新 prompt reservation会消费该废弃请求，之后若再次 overflow 可重新排队。serve 退出前所有 SSE/summarize producer 先完成，translated output 再 lossless drain，并等 `parseStdout` 处理最后一行后请求 EOF，Wait 才向 Process 暴露退出；显式 Stop 可 abort drain，超出 process line limit 的事件则 fail closed retire，避免 terminal boundary 丢失或 writer deadlock。 - resumed session 在任何新 message id capture/initial prompt 之前分页扫描完整 raw message history并提升本地 id high-water；这一步不能用 `limit=1` 代替，因为 OpenCode page 按 `time_created` 排序、`MessageV2.latest()` 却按 id 最大值选择。raw high-water 覆盖所有行；resume candidate 则先按上游 `MessageV2.filterCompacted` 的 newest-first membership 去掉 completed compaction boundary 之外的旧历史，再只在 effective membership 内选 lexicographic max id，避免旧 compacted row 因时钟回拨反而被选中。scan 对非标准 ascending message id 或 effective max assistant/max user 失配 fail closed，不能在无法证明新 id 排序时继续 mutation。无新 turn input 的真实 resume 中，unanswered max-id user 使用自身 `messageID`，unfinished assistant/tool 使用其 parent user `messageID` 单次 empty-parts bootstrap，terminal assistant 不 kick；若 max user 是未完成的 compaction task，scan 同时保留其完整 part 与 `auto` mode，并在 bootstrap HTTP mutation 前预先绑定 current-Runner compaction root。新 server 的 runAgentTeam 会从 DB 继续该 task、却不会重新发布旧 compaction part；预绑定因此是 summary suppression、auto continuation、失败归类和最终 idle 收敛所必需。缺失 `auto`、summary 无 compaction parent、bootstrap 或 high-water scan 失败都直接使 Spawn 失败。 - rewind strategy 为 `opencode_session_revert`：使用 OpenCode 原生 `/session/:id/revert`，recovery ref 绑定实际 `prompt_async.messageID`；AgentTeam-managed OpenCode 强制 context-only 配置，发布前通过源码检查和 LAN E2E 固化该语义 - `claude` - 当前保留正常消息 / tool use 行为 - 支持 stdin idle delivery：daemon 在进程存活且处于 idle 时，可直接通过 stdin 投递下一条消息 - active-turn delivery 使用 commit-aware pending stdin：daemon 以消息 ID 作为 `uuid` 写入 Claude stream-json stdin，并使用 `priority: "next"`；Claude 以 `--replay-user-messages` 在真正把该 user message/queued command 纳入 query boundary 时回放 `type=user,isReplay=true,uuid=...`。AgentTeam 在 transport 写入成功后立即按正常 `prompt_input` activity 展示消息正文（不暴露 pending/queue/boundary 文案，且作为 background notice 不替换现有 command activity）；它不推进 observed、不标记 surfaced。surfaced ack 到达后追加轻量 agent-ack activity、记录 recovery surface、标记 surfaced message，并推进该 target 的 observed freshness frontier。 - active-turn surfaced ack 消费前会重新检查 freshness 与 session identity：若同 target seq 已经通过自动 fallback delivery 或 `read_history` 观察，daemon 只清理 pending 状态；若 ack 来自不同 session，daemon 不把该 ack 当成 surface，并把原消息放回 local continuation inbox 走自动 fallback delivery。两种情况都不会重复展示具体 `prompt_input`、不会重置 wake lifecycle、也不会推进 freshness。 - ack-aware active-turn contract 当前适用于 Claude (`--replay-user-messages`/`uuid`)、Codex (`turn/steer`/`clientUserMessageId`/`userMessage.clientId`) 与 Kimi Wire (`steer`/`SteerInput`)；OpenCode 明确不声明 active-turn capability，而是在 idle/new-turn 上使用 `messageID`/assistant `parentID` correlated ownership。若对应 runtime 的 acked delivery 不可用、写入失败或 session mismatch，daemon 保留 durable continuation 并在安全 input boundary / idle 自动重试；transport accepted 的 pending input 不使用固定 ack timeout - `claude_session_resume_at` 是 Claude Code 的 rewind strategy：使用原生 `--resume-session-at`，before-first-input 用 fresh session boundary；发布前通过 driver restore/verify 与 LAN E2E 验收 - `kimi` - daemon 启动 `kimi --wire --session --work-dir `，使用同一 JSON-RPC transport 完成 initialize、prompt、steer、cancel、resume 与 runtime event 翻译；AgentTeam 预生成 session id，并在显式 controlled resume 时要求恢复同一 session。 - idle delivery 的 `prompt` response 和 busy delivery 的 `steer` response都只表示 transport accepted；`TurnBegin` / `SteerInput` event 才按 daemon delivery id 完成 surfaced。crash reconciliation 只读该 session 的 `wire.jsonl`，完整 inactive history 缺少 correlation 才可判 absent，不确定或 active history保持 pending/unknown。 - `StatusUpdate.token_usage`、content、thinking、plan、tool、approval、`TurnBegin` / `TurnEnd` 映射到公共 runtime event；approval 与未知 server request fail closed。显式 interrupt 使用 Wire `cancel` request，不能用 cancel + prompt 冒充 steer。 - rewind strategy 为 `kimi_session_turns`。recovery point 记录输入入模前的 completed-turn count 与真实 user-input count；detached restore 在路径校验后通过可恢复 journal 原子截断 `wire.jsonl` 和 `context.jsonl`，context 统计排除 synthetic checkpoint，并保留同一 turn 内的 steer input。Kimi 不声明 live restore。 - Kimi tool-restricted launch 为每个 session generation 使用稳定的私有 `KIMI_SHARE_DIR`：每次 launch 只临时复制允许的 runtime config/OAuth credentials，不复制 plugins，退出时删除 config、credentials 和 launch files，但保留 provider session transcript 供普通 controlled recovery；launch-scoped `--agent-file` 按 `DisableNativeTools` 生成允许的 builtin tool surface，并通过显式 MCP config 只加载当次 launch 的 MCP。Kimi Wire 的 prompt、steer、cancel、usage、activity 与 generic recovery 继续使用同一 session-bound transport。 - `builtin` 选择解析到 AgentTeam-managed OpenCode，并沿用 OpenCode 当前的 full-access launch policy；builtin rewind capability 跟随 OpenCode `opencode_session_revert`，发布前同样通过 LAN E2E 验收。 - 外部 OpenCode、Claude Code、Codex、Kimi Code 仍可检测和使用，但 Desktop 只负责 detect/use/configure，不再提供 runtime install、upgrade、SSE installer、install command API、launch-time auto-install 或 app-build auto-install。Codex 检测和启动仍要求 `codex app-server` capability；Kimi 检测和启动要求 `kimi --wire` capability。 因此当前服务端判断 rewind eligibility 时，必须按**有效 runtime implementation** 判断，而不是只看”是不是 Codex”。 补充边界说明： - internal data plane 当前仍以 workspace-scoped `agentId` 为入口，因为 act-as、mention、delivery、channel membership 都锚定在 `Agent` / agent member 上 - 与该入口绑定的 runtime token 仍存于 `agents`。`session_id`、`status/activity`、`activity_detail`、`current_instance_id` 和 `agent_instances` 属于 legacy runtime mirror；目标 contract 不再把它们作为当前 runtime source of truth。daemon-local state 与当前 WS 连接负责 session/resume、running set、activity 和 trajectory，server 只转发 realtime 或保留必要的 ephemeral routing state Live runtime read-model overlay（As-Is contract）： - Canonical daemon ownership is defined in `specs/daemon/daemon.md`; Desktop package layering is defined in `specs/daemon/desktop-architecture.md`. - `internal/api/daemon/protocol.go` owns the server in-memory projection keyed by the authenticated daemon WebSocket connection. It consumes `ready.runningAgents`, `agent:status`, `agent:activity`, and `agent:session` messages without writing those transient fields to TiDB, except for the explicitly documented sparse legacy `agents.session_id` mirror for daemons that do not support local session resume. - Durable store queries such as `internal/store/app/app_runtime.go`, `internal/store/app/app_agent_detail.go`, and `internal/store/app/agent_messages.go` remain responsible for bounded authorization and identity/machine rows. They may return offline placeholders for live-only fields. - API handlers that already have bounded result sets overlay the daemon hub projection before converting to DTOs: browser agent list/detail/runtime snapshots under `internal/api/webagent`, machine agent/workspace views under `internal/api/workspace/api_machines.go`, and agent-facing MCP workspace snapshots under `internal/api/agent/api_messages.go`. - The overlay must not add agents that the durable query did not return, must not widen list/query scope, must not add polling, and must not persist status/activity/current-instance telemetry. If the daemon disconnects, the server-side in-memory projection disappears with that connection and subsequent reads show offline/unknown until reconnect and `ready` replay. 当前实现（按更严格方案落地）： - 每次 server 准备下发 `agent:start` 时生成新的 `agentAuthToken`，并将其 `SHA-256` 写入 `agents.auth_token_hash`（旧 token 立即失效） - agent 首次 `start` 前，`agents.auth_token_hash` 允许为空；此时对 workspace-scoped Agent Runtime 的请求一律返回 `401` - server 在下发 `agent:start` 的 `config.authToken` 时带上该 token；daemon 会把它透传给本机 chat-bridge - **不提供 machineApiKey 作为 internal API fallback** 理由： - machine key 是机器级权限，agent token 是 agent 级权限，不能混用 - 当前系统并不缺 fallback；增加 fallback 只会掩盖配置错误 - 去掉 fallback 也更符合“尽早暴露问题”的工程原则 长期记忆接入约束： - runtime-local recovery memory 仍然是 agent workspace 本地文件：`MEMORY.md`、`state/*`、`kb/*`、`archive/*`。 - 这些文件由 daemon/runtime 与 agent 直接读写，用于 deterministic resume、local knowledge 和历史追溯；它们不是 metadata-backed product surface。 - MeshX managed Memory 是独立的 workspace resource surface。它不替代 runtime-local recovery memory；human visibility/manage 通过 `memory_grants` fail-closed 授权，agent access 则通过 `memory_agent_bindings` 的显式单绑定模型解析。当前 agent 绑定不使用 `memory_grants(subject_type=agent)`，也不提供 workspace-wide fallback access。 - 当前系统不提供 semantic/vector memory 服务，也不暴露 memory MCP 工具。 权限最小化： - Agent token 只用于 internal agent HTTP API（当前实现包含）： - 消息：Agent Runtime 下的 `/send`、`/history`、`/search`、`/messages/:messageId/read-check`、`/workspace`（server 不再提供 `/receive`） - Task Board：`/api/v1/workspaces/:workspaceId/agents/:id/runtime/tasks*`（list/get/create/update/set-claim/checkpoint） - `internal/store/agent` runtime auth 现在会把这条 internal data-plane 身份显式编译成 `AuthorizationRequest{ resource=agent, action=act_as_member }`，并要求 `act_as_member` 只能命中 agent 自己的 member（decision source=`agent_self`） - Machine token 仅允许： - 建立 WS 控制连接 - 不允许访问 internal agent HTTP API - machine WS 认证同样显式落到 `machine.connect`（decision source=`machine_self`），避免 machine token 语义继续停留在隐式“查到这台机器就算通过” ### 4.4 数据模型：元数据在 TiDB，冷历史在归档存储（Archive Storage：filesystem / S3） 实现位置（As-Is）： - TiDB schema：`internal/tidb/bootstrap.sql` + `internal/tidb/migrations/*.sql` - Release activation 在运行 `agentteam-schema init` 前停止旧 `agentteam-server`，schema 与 workspace placement gate 全部通过后才启动新 binary；contract migration 失败时保持服务停止，避免旧 binary 在部分升级的 schema 上继续写入。 - 消息写入与访问原语：`internal/store/app/message_append.go`、`internal/store/app/app_messages.go`、`internal/store/message/append.go` 与 `internal/store/message/scope_store.go` - 消息冷归档 worker 当前未运行；冷历史读取仍使用 `internal/archive/*` - 冷归档存储 driver：`internal/archive/*` #### 4.4.1 先定一个简单模型 统一抽象： - **scope = channel、DM、reply thread、Task、Service Account 或 Workflow 等产品消息容器**；外部 target 仍保留各产品语义，存储层不再维护并行 legacy thread 拓扑。 - 每个 scope 有自己的单调递增 `seq`。 - scope 的消息默认是 append-only 的，不支持普通修改与删除；严格受限的 rewind 成功后会把目标热 suffix 写成 `rewound` lifecycle tombstone 并 scrub 派生投影。 数据分两层： - **热层（TiDB）**： - 元数据 - 读状态 - 最近消息正文（`scope_messages`） - **冷层（Archive Storage）**： - 不再频繁读取的历史归档对象（按 `scope_id + seq` 直接推导 object key；storage driver 可为 filesystem 或 S3） 数据库不再有“永久 `messages` 大表”。 首版最关键的取舍： - 写入路径必须简单可靠，因此**新消息先写 TiDB** - 冷历史异步归档到归档存储（filesystem / S3），归档后再从 TiDB 删除 - 这样写入仍然是单事务、强一致、容易调试 - 同时数据库规模可以保持在“热消息窗口”内，而不需要永久承载全部历史正文 #### 4.4.2 主要表（概念级） > 说明：完整 schema 以 `internal/tidb/bootstrap.sql` + `internal/tidb/migrations/*.sql` 为准；本节只列出理解当前实现所需的关键列/约束/语义。 基础元数据： - `users` - `id`, `email`（PingCAP phone-only 用户可为 `NULL`）, `name`, `display_name`, `avatar_url`, `is_admin` - `password_hash`, `email_verified_at`, `mobile`, `mobile_verified_at`, `created_at`, `updated_at` - `user_email_verification_tokens` - `user_id`, `token_hash`, `expires_at`, `consumed_at`, `created_at` - `user_sessions`（access token） - `id`, `user_id`, `session_family_id`, `token_hash`, `expires_at`, `created_at`, `revoked_at` - `user_refresh_tokens`（refresh token） - `id`, `user_id`, `session_family_id`, `token_hash`, `expires_at`, `created_at`, `revoked_at` - `user_session_families`（二维码登录的移动端会话族） - `id`, `user_id`, `client_type`, `installation_id`, `device_name`, `device_platform`, `expires_at`, `created_at`, `revoked_at` - `user_password_reset_tokens` - `user_id`, `token_hash`, `expires_at`, `consumed_at`, `created_at` - `workspaces` - `id`, `organization_id`, `slug`, `name` - `organization_id` 是 owning organization 的唯一事实来源；旧 workspace binding 表已由 cleanup migration 删除 - `latest_message_seq`（workspace 内全局单调递增消息序列） - `created_at`, `updated_at` - `workspace_invites` - `workspace_id`, `email`, `role=member` - `token_hash`, `created_by_user_id`, `created_at`, `expires_at`, `accepted_at`, `revoked_at` - `members` - `id`：稳定 `member.id`，shortid 风格字符串；对 human 它直接就是公开协议标识，对 agent / service 它是隐藏内部关联键 - `workspace_id` - `type = human | agent | service` - `display_name` - `user_id`（human only） - `workspace_role`（human only）= `owner | admin | member` - 关键约束（以 `internal/tidb/bootstrap.sql` + `internal/tidb/migrations/*.sql` 为准）： - `type` 仅允许 `human|agent|service` - human 必须有 `user_id` 且必须有 `workspace_role IN ('owner','admin','member')` - agent / service 必须 `user_id IS NULL` 且 `workspace_role IS NULL` - `members_workspace_human_user_unique`：同一 workspace 内 `(workspace_id, user_id)` 仅对 human 做唯一约束 - `channel_sidebar_preferences` - 以 `(workspace_id, member_id)` 为主键保存 Human 的个人频道分类聚合状态；`member_id` 通过 human member 唯一映射当前 workspace 中的 user，确保跨客户端同步但不跨成员共享 - `state_json` 原子保存有序分类、名称、图标、频道归属和折叠状态；Browser 通过同一个 `/api/v1/workspaces/:workspaceId/sidebar/channel-sections` URL 执行 GET/PUT，未部署或暂时不可用时只使用按 workspace+user 隔离的 localStorage 缓存 Scope message model： - `scopes` - `id`, `workspace_id`, `type = channel | dm | thread | task | service_account | workflow` - `parent_scope_id`, `root_message_id`, `root_message_short_id`, `identity_key` - `latest_seq`, `latest_global_seq`, `latest_message_at`, `archived_until_seq`, `visible_message_count`, `visible_last_message_at`, `status`, `created_by_member_id`, `created_at`, `updated_at`, `archived_at` - channel、DM、reply thread 都是 first-class scope rows；reply-thread scope 指向 parent scope 与 root message；DM 唯一性通过 canonical `identity_key` 表达。 - `scope_channel_profiles` - `scope_id`, `slug`, `display_name`, `description`, `visibility`, `subsystem`, `owner_member_id`, `is_all_channel`, `created_at`, `updated_at` - 只有 `type='channel'` 的 scope 有 profile；`#all`、ordinary channel governance 与 public/private discover metadata 都在这里。`subsystem` 默认为 `im`，`kb` 为历史兼容的隐藏 agent-thread/session carrier channel 值，`project` 预留给 Project 内部讨论 carrier；普通频道列表/发现/配额默认只读取 `im`。 - `scope_memberships` - `scope_id`, `member_id`, `visibility`, `owner_member_id`, `last_read_seq`, `last_read_global_seq`, `owner_context_dismissed_through_global_seq`, `effective_from_seq`, `effective_to_seq`, `removed_at`, `archived_at`, `updated_at` - owns dense readability, member/participant projection, read cursors, private membership intervals, and owner-context dismiss cursor. - `scope_notification_settings` - `scope_id`, `member_id`, `state = active | quiet | mute | auto-wake | no-wake`, `created_at`, `updated_at` - owns current wake/read notification preference; per-message execution truth stays in fanout payload/outbox rather than notification history rows. - `scope_messages` - `id`, `workspace_id`, `scope_id`, `seq`, `workspace_global_seq`, `author_member_id`, `author_type`, `client_message_id`, `message_type`, `content`, `metadata`, `created_at`, `updated_at` - stores canonical live transcript rows for explicitly supported product scopes, including channel / DM / reply-thread and Workflow Builder history; owner-private execution does not create a separate user-visible transcript. - `scope_share_cards` - `id`, `workspace_id`, `scope_id`, `message_id`, `source_scope_id`, `source_message_id`, `target_scope_id`, `created_by_member_id`, `revoked_at`, `revoked_by_member_id`, `payload`, `created_at`, `updated_at` - share-card action state belongs to the owning `channel_share_card` message; lifecycle and authorization stay out of message metadata. - `scope_activity_events` - `id`, `workspace_id`, `scope_id`, `activity_type`, `activity_ref_type`, `activity_ref_id`, `activity_global_seq`, `source_message_id`, `actor_member_id`, `reason`, `payload`, `created_at`, `suppressed_at` - durable fact table only for non-message activities such as reaction signals and task typed activity projections; message-backed mention / explicit / broadcast reasons stay in fanout payload and outbox status. Task typed activities are written through `internal/store/tasktimeline` rather than taskboard/app feature-local inserts. - `scope_message_sources` - source refs for concrete `owner_quote` message provenance and source attribution; current parent-target/private-context runtime does not write separate task-owned source entries, second transcript copy rows, or publication mirrors - `scope_message_reactions` / `scope_activity_events` reaction rows - `scope_message_reactions` carries current reaction state for a scope message; reaction activities use `scope_activity_events.activity_ref_type = 'reaction'`, so reactions can generate agent-facing daemon delivery signals / diagnostics without a separate delivery table 读状态： - `scope_memberships` - `last_read_seq`, `last_read_global_seq`, and `owner_context_dismissed_through_global_seq` are the canonical live read-state fields for scope reads. activity 与 rewind 状态： - `scope_activity_events` - `id`, `source_message_id`, `scope_id`, `activity_global_seq` - `activity_type`, `activity_ref_type`, `activity_ref_id`, `reason`, `created_at`, `suppressed_at` - 作为 reaction 等非消息 activity 和 task typed activity projection 的 durable fact；task typed activity 通过 `internal/store/tasktimeline` 统一写入，message-backed mention / explicit wake 只影响 outbox fanout reason。普通 channel / DM / reply-thread 的 dense unread/readability 使用 `scope_memberships` cursor 与 current `scope_notification_settings` 偏好；每条消息的 agent execution truth 使用 `scope_fanout_outbox`。 - `message_recovery_points` - `workspace_id`, `message_id`, `agent_id` - `scope_id`, `recovery_strategy`, `recovery_ref`, `prepared_at` - 只在消息实际会通过 rewind-capable runtime 投递给 agent，且消息仍位于 hot history 时写入 - `rewind_operations` - `id`, `workspace_id`, `scope_id`, `message_id`, `agent_ids`, `status`, `created_at`, `updated_at` - `status = preparing | repair_required | completed | failed` - 用于串行化单个会话面的 rewind，并在 restore 成功但 DB apply 失败时留下 repair ledger 机器与 agent： - `machines` - `id`, `workspace_id`, `created_by_user_id` - `name` - `api_key` - `hostname`, `os`, `daemon_version`, `runtimes`（last-known diagnostic metadata；runtime decisions use the current daemon connection） - `status = active | revoked` - `connected_at`, `disconnected_at`（legacy presence mirror；machine online/offline must come from daemon WS presence, not these columns） - `created_at`, `updated_at` - `agents` - `id`, `workspace_id`, `machine_id`, `member_id`, `name`, runtime settings - `UNIQUE(workspace_id, name)` - `agent_role_bindings` - binds each Agent to a Role version and active identity document - `role_package_manifest_items` - canonical package manifest for identity, skills, knowledge, KB, and Memory grants Role never replaces `members` / `agents` as the message identity. Materialization reads only canonical bindings and manifest items. 消息热层： - `scope_messages` - `id`, `workspace_id`, `scope_id` - `seq`（scope 内序列），`workspace_global_seq`（workspace 内全局序列） - `author_member_id`, `author_type`, `message_type`, `content`, `metadata`, `created_at`, `updated_at` - `UNIQUE(scope_id, seq)` - `UNIQUE(workspace_id, workspace_global_seq)` - `metadata`：bounded JSONB（当前上限 `16KiB`），用于附加 machine-readable sender/event metadata，例如 App sender kind/slug - `content` 是 Markdown 源文本；正文内附件用 `attachment://` 引用。引用在 `content` 中出现的位置和顺序是排版事实来源，不依赖 attachment 查询顺序 - `attachments` - `id`, `workspace_id`, `scope_id`, `message_id` - `uploaded_by_member_id` - `filename`, `content_type`, `size_bytes`, `blob`, `created_at` - 备注：当前实现直接把二进制内容存 TiDB（便于最小化依赖与实现复杂度）；message attachment 通过 `scope_id + message_id` 绑定到 scope message，task discussion attachment 绑定到 task scope 的 `scope_messages(message_type='task_discussion')`，未 claim 上传保留 `scope_id` 以便 GC。发送请求中的 `attachmentIds` 负责 claim 集合与权限边界，不定义正文内的展示顺序；正文引用只有在 ID 属于当前 message sidecar 时才可解析。若未来需要保留历史附件，应优先迁移到对象存储（S3/FS）并仅在 DB 存元数据/引用。 - 备注：当前实现会通过后台 GC 定期删除未 claim 附件（`message_id IS NULL` 且 `created_at < now - 24h`，实现：`internal/app/app.go` + `internal/store/attachment_gc.go`）；因此“弃发附件”不会无限占用 TiDB，但上传后若长时间未发送，需要重新上传 序列字段（两套 cursor）： - desktop/internal：以 scope-local `seq` 为主；普通 channel / DM / reply-thread 的 human unread 由 `scope_memberships` cursor 推导；agent runtime delivery 由写入时 routing plan + `scope_fanout_outbox` payload/status 下发到 daemon，本地 continuation inbox 保存 daemon 已接受但尚未在 runtime surface 的 payload - web/app：以 `workspace_global_seq` 为准（`workspaces.latest_message_seq` / `scope_messages.workspace_global_seq`） - 写入时由 `workspaces.latest_message_seq` 在事务内自增分配，保证 `UNIQUE(workspace_id, workspace_global_seq)` - `GET /api/messages/sync?since_seq=...` 与人类端未读计数依赖 `last_read_global_seq` 命名变化的关键点： - 原 `actors` 改为 `members` - human 的原 `actor.name` 语义改为 `members.id` - agent 的原 `actor.name` 在 protocol / target 语义上改为 `agents.name`；默认 human-visible label 改由 `members.display_name` 承担，`agents.member_id` 退回隐藏 relation key - `sender_name` / DM `channel_name` 对 internal 协议来说，human 传 `member.id`，agent 传 `agents.name`，service 传安装态公开 handle（当前 App v1 即 slug） workspace 角色也刻意不单独再起一张 `workspace_memberships` 表，而是直接落在 human member 行上的 `workspace_role`。 原因是： - 当前模型里，一个 user 在一个 workspace 下恰好只有一个 human member - public API 的权限判断最终也总要先定位这个 human member - 因此把 `workspace_role` 直接落在 human member 行上，能让权限判断有单一事实来源，同时不把 agent 运行态混进来 这里刻意不采用“只有 `members` 一张表，再加 `is_agent` 布尔字段”的方案。 原因不是它做不到，而是它并不会真的让模型更简单： - `members` 表达的是**消息身份**：谁在发言、被 @mention、被用作 DM 对端 - `agents` 表达的是**运行实体**：它属于哪台 machine、用什么 runtime、当前 session / status / activity 是什么 因此首版采用： - `members.type = human | agent | service`：把成员类型表达清楚，而不是塞进语义更弱的 `is_agent` 布尔值 - `agents.member_id`：让运行实体单向指向自己的消息身份 - `members` **不反向存 `agent_id`**：避免双向引用和重复约束 新增的 service sender 也遵循同一原则：core 只把它当作 `members.type = service` 的消息身份；App 安装、manifest、grant、subscription 等附加语义留在 `app_*` 表，不回灌成新的 core principal。 #### 4.4.3 为什么这个模型能明显减轻 DB 负担 因为首版几乎所有核心读写都只需要这些元数据，不需要扫完整历史： - 未读： - desktop/internal：普通 scope human unread 以 member/scope cursor 为边界；non-message activity 保留为 durable fact / diagnostics / direct fanout evidence，不再通过 server `/receive` 推进 agent activity cursor - web/app：基于 `scope_messages.workspace_global_seq` 与 `scope_memberships.last_read_global_seq` 增量计算（热窗口内） - 最新页：只查 `scope_messages` 末尾几十条 - agent 当前事件投递：写入时根据 message routing plan 计算 durable/wake recipients，事务提交后由 `scope_fanout_outbox` worker 下发 `agent:start` / `agent:deliver`；daemon-local continuation inbox 保存并自动递交已被 daemon 接受的 pending payload - 翻冷历史：只用 `scopes.archived_until_seq` 判断是否落到冷层；落到冷层后，由 `scope_id + seq` 直接推导要读哪个归档对象（chunk） - 冷层按随机 `message_id` 或 reply-thread short id 定位时不能从 seq 推导入口；当前用窄表 `scope_archived_messages` 存 `message_id / message_short_id -> seq`，命中后按固定 chunk 策略派生对象并校验内容 因此数据库的角色是： - **活跃 tail 的读写引擎** - **边界元数据与读状态存储** - **不是冷归档对象内容目录，也不是永久历史文件柜**；仅保留随机 id / short id 这类无法由 `scope_id + seq` 推导的窄定位索引 #### 4.4.4 热层边界与消息尺寸约束（保持简单） 首版只需要： - `scope_messages` 的两组唯一序列： - `UNIQUE(scope_id, seq)`：支撑 desktop/internal 的按 scope 历史分页与归档分块 - `UNIQUE(workspace_id, workspace_global_seq)`：支撑 web/app 的跨 scope 增量同步（`/api/messages/sync`） - `scope_archived_messages(scope_id, message_id)` 与 `(scope_id, message_short_id, message_id)`：支撑已归档消息按随机 message id / reply-thread short id 定位到单个 chunk；读取内容仍以归档对象为准 - `scopes.latest_message_at`：支撑 channel / DM / reply-thread 列表与 inbox 排序 - `scopes.archived_until_seq`：支撑冷热边界判断 - `scope_memberships(scope_id, member_id)` 主键：支撑 human unread/read-state（含 `last_read_seq` 与 `last_read_global_seq`）；agent runtime delivery 不再从该 cursor 派生 `/receive` backlog 当前实现依赖的关键索引（非穷举，完整见迁移文件）： - `scope_messages` 的 `(scope_id, seq)` 索引：scope 维度读取最近消息（最新页与向前翻页） - `scope_messages` 的 `(workspace_id, workspace_global_seq)` 索引：`/api/messages/sync` 增量拉取 - `tasks_channel_status_task_number_idx`：task board 列表（按 `status` 过滤） 首版把单条消息大小限制死（当前实现：写入路径已强制校验；按字节长度计）： - `message.max_bytes = 32 KiB`（实现：`internal/store/privateagent/conversation_write.go`） 理由： - message `content` 仍是有界 text 字段，只承载 Markdown 源文本而不引入 rich-text AST；web/app 可在其中用 `attachment://` 引用 sidecar 附件 - 固定大小上限能显著降低异常大消息把热层、归档对象和 agent prompt 一起拖垮的风险 - 也让后面的固定消息块归档策略保持可控 同时建议对附件做硬限制（当前实现已落地在 public API 层）： - `attachments.max_files_per_message = 10` - `attachments.max_bytes_per_file = 20 MiB` - 实现：`internal/api/media/api_attachments.go`（web/app 上传） - 正文媒体表示：图片持久化为 Markdown image；视频/音频持久化为标准 Markdown attachment link，Web 根据当前 message sidecar 的 `content_type` 升级为 `