Tanka 内存与输出系统

三进程 + 一守护进程（由 supervisord.conf 生产 / supervisord.local.conf 本地定义，启动优先级递增）：

1. web_api（priority=100，先启动）

   uvicorn FastAPI，生产端口 80、本地 3080，承载所有同步 HTTP / SSE 接口。引导链：web/main.py 导入时 os.environ["DEBUG"]="1" → set_env() 写入 API key → Apollo EnvProxy 加载 web/config/{config_env}_config.yaml（默认 test）→ FastAPI(lifespan=...) 启动期初始化数据库 + 预热 Redis 池 → 注册路由与 monkey patch。

2. celery_beat（priority=200）

   RedBeat 调度器，把 schedule 存到 Redis，用 redbeat:lock 分布式锁做多实例故障切换（锁超时调优为 30s/150s）。驱动每小时 flow card 定时任务与 WaitTask 的 TIME_POINT/TIME_CRON。

3. celery_worker（priority=300）

   线程池 concurrency=16，订阅双队列 celery（核心任务）+ wait_task（异步任务），prefetch=1 防止任务囤积。

4. kafka_consumer（独立守护）

   必须单实例——其 Dispatcher 在内存里做防抖（debounce），不可分布式。订阅 im_message / vote / arena 等 topic，匹配 watch_target 后派发评估任务给 worker。

基础设施：PostgreSQL（读写分离，存聊天历史 + langgraph checkpoint）；5 个独立 MongoDB shard（Habitat / AI Memory / Workbench / ThirdParty / TankaLink）；Milvus（向量）；Elasticsearch（全文 + memory_cellular + ELK 日志）；Redis（按逻辑 db 分区 + RedBeat 锁）；Kafka（事件源）；外部 TankaServerAPI 后端（写操作与唤醒回调目标 /internal/assistant/post-data）。

自顶向下读法：请求从 View 层（web/src/view/，全部前缀 /api，聚合 tanka/relay/chat_analysis/apodex 子路由）进入；中间件层给每个请求挂上携带 trace_id 与用户身份的 Session ContextVar，写 ELK 日志，再交给 Controller。主干路径是 Tanka Agent 运行时（Flow）：从 PostgreSQL 按 room_id 加载 langgraph checkpoint，构建 ContextSchema，跑 astream 循环；每个回合经过 Phase A-G 的工具调用生命周期。围绕核心运行时挂着几个专门 Controller：Skills & MCP、检索、业务产出生成器、Apodex（自成一体的 DDD 限界上下文簇）。横切库（web/src/lib）提供事件 outbox、Redis 池、会话事件投递。DAO 层结构性强制 orgId 多租户。Celery 侧的 worker/beat 处理后台与定时工作，Kafka 消费者把外部事件派发给 worker。

逐步走读（详见 docs/tool_call_lifecycle/overview.md，最重要的一份文档）：

1. 进入与日志

   请求经 web/src/middleware/register.py 挂上 Session(trace_id, user_id)，按 endpoint 模式写 ELK；polling 路径（如 /work/watcher/tasks/）被静默以减噪。

2. 状态加载

   stream_chat_tanka()（agent.py:2749+）按 thread_id = room_id 从 PostgreSQL 加载 checkpoint，构建 ContextSchema，启动 agent.astream(stream_mode=['messages','custom','values'])。

3. Phase A — 模型出招

   进 LLM 前 abefore_model 跑压缩中间件（Claude 走 prompt caching；Gemini 走摘要）。模型在 AIMessage 中产出一个或多个 tool_call。

4. Phase B — 四阶段中间件（在 aafter_model 内执行）

   TankaPlatform（B.1）：守卫、校验、动作分类，写 _pending_confirmations。
   ActionResolve（B.2）：跑字段解析器（解析 @mention、邮箱、联系人），产出 card_data + processed_body + injected_params → _resolve_results。
   Precheck（B.3）：本地规则（如群最少成员数）+ 可选远程 dry_run，不合规直接拒绝、不弹卡。
   Permission（B.4）：先匹配 always_allow 跨回合授权（命中则自动放行、出 SUCCESS 卡）；否则 raise GraphInterrupt(hitl_requests)。
   关键陷阱：中间件 append() 顺序是执行顺序的逆序（langgraph 由外到内）。agent.py:1984-1989 注释里把意图顺序 Platform→Resolve→Precheck→Permission 映射成逆序 append。

5. Phase C-D — HITL

   GraphInterrupt 被外层 stream 循环捕获，PENDING 卡经 SSE 推给前端；用户点 approve/edit/reject/always_allow，前端回 resume_values，Command(resume=...) 从中断点恢复。一次中断对应一次恢复，决策数量不匹配会抛 ValueError。

6. Phase E-F — 执行

   决策收敛后，langgraph 工具节点调 tanka_api(method, path, body)，合并 _pending_injected，POST 到 TankaServerAPI，返回 XML ActionResult 的 ToolMessage。

7. Phase G — 回到模型

   ToolMessage 追加进消息序列，模型据此继续（更多 tool_call、文本或结束）。

8. 收尾

   循环结束保存 checkpoint，TurnSummaryMiddleware（栈中最后执行）写 outline.md + 原始 chunk 到 /workspace/turn_history/；流以 data: [DONE] 结束，响应完成再写一次 ELK。

6a · 运行时领域

核心是 Session——以 room_id 为键的对话/工作实例，room_id 同时就是 langgraph checkpointer 的 thread_id。一个 Session 展开为一串 Turn（一条用户消息 + Agent 直到停下的回应，由客户端 request_id 划界，是 turn_summary、压缩阈值、唤醒事件的边界）。回合内 Agent（tanka / relay / 统一 work_agent 变体）跑一个 langgraph StateGraph，行为由有序的 Middleware 栈塑形（再次强调：append 顺序是执行的逆序）。状态——权限授权、action_log、pending confirmation——以 CustomAgentState 形式 checkpoint 到 Postgres；瞬态信号（终止、限流）放 Redis。两个扩展面挂在 Agent 上：Skill（SKILL.md SOP 模板，挂载进 MongoBackend Workspace VFS，有 short_id 与发布后的 store_id）与 Tool（几乎全部经单一 tanka_api 路由汇聚，第三方经 MCP JSON-RPC）。异步性建模为 WaitTask：等事件（chat/email/arena/vote，经单实例 Kafka 消费者摄入）或等时间（TIME_POINT/TIME_CRON，经 RedBeat）；触发达 COMPLETE 时把 LifecycleEvent 发到 Redis 事件 outbox（真相源），并尽力唤醒 Session，把 Resume Text（system-reminder XML）注入 prompt。Flow 会话（DERIVED 子房间）让父 Agent 扇出有界并行子任务。

6b · Apodex IMP 章程域

Apodex 是一套教科书式 DDD 设计，完整地活在一个工具背后。8 个限界上下文组织 23 个聚合，围绕两个核心：Impact Ledger（ImpRecord + EmployeeProfile）和 Contribution Attribution（Mission/Version/Idea）。IMP（Impact Point）是唯一的价值单位，每次计分都是一条仅追加（append-only）的 ImpRecord，带幂等键 sourceType:sourceId:action，且必须落在 8 个合法 type×sourceType 对之一（验证器强制正交性）。归因链是模型的数学主干：Version 在 kickoff 锁定 vImpBase，retro 时按层级乘数算出 vImpFinal，扣减 enablement，再按 Idea（α×β×B 权重）分配，最后用角色系数分到贡献者。Version 一旦 retroed，其所有计分字段冻结以供审计。Supporting 上下文（Base Task、Compliance/Incumbency、People Operations、Research Execution）和 Generic 上下文（Identity、Governance）消费 IMP 做闸门——晋升查 3 年滚动阈值，S 级事故冻结晋升，连续两季不达标触发 PIP。

6c · 两个模型如何共存

二者占据同一 FastAPI + Celery 部署的不同层，只在一个接缝相遇：Agent 把 Apodex 当工具调用。运行时模型是通用执行底座，对 HR 语义一无所知；它的词汇（Session/Turn/Agent/Tool/Skill/Middleware/WaitTask/Flow/Checkpoint/LifecycleEvent）描述任何对话「怎么跑」。Apodex 模型是「某个工具做什么」。Apodex 以两种方式暴露：(1) apodex_action Agent 工具——ApodexActionMiddleware 把 {object, action, params} 派发给应用服务；(2) REST /api/apodex/*。两条路径中，运行时都从 Session 上下文注入 userId/orgId，派发器自动注入 xxxBy 审计字段。两模型不共享聚合边界：运行时的 Session/Agent 状态在 Postgres checkpoint 与 Redis；Apodex 聚合在自己的 Mongo collection，受服务层不变式约束（append-only、幂等、type×sourceType 正交、orgId 租户隔离）。唯一的概念重叠是 orgId——运行时注入，Apodex 的 BaseDAO 在每次查询/插入时防御性强制。把运行时当作宿主平台，Apodex 当作只能经服务层门面访问的客体子系统。