Altas — 飞书驱动的 Eve / Codex Orchestrator

Altas 让用户在飞书中与 Eve Orchestrator 对话，由 Eve 管理会话、TeamID、审批和任务调度；Context Platform 管理跨会话的长期业务上下文；Codex Worker 或 Local Bridge 执行代码与本地命令。

当前实现使用 eve@0.22.5、飞书官方长连接 SDK、DeepSeek OpenAI-compatible API、PostgreSQL 17 和 Codex CLI。

架构总览

flowchart LR
    U["飞书用户"] --> F["飞书开放平台<br/>WebSocket 长连接"]
    F --> FW["Feishu WS Daemon<br/>官方 Node SDK"]
    FW -->|"鉴权后的 localhost 事件"| E["Eve Orchestrator"]

    E -->|"Team 绑定、上下文工具"| C["Context Platform API"]
    C --> P[("PostgreSQL<br/>Team 长期上下文")]

    E -->|"云端代码任务 + HITL"| W["Codex Worker"]
    W --> X["Codex CLI / Git / Tests"]

    E -->|"本地任务 + HITL"| G["Local Bridge Gateway"]
    G <-->|"出站 WebSocket"| D["Developer Daemon"]
    D --> L["本地仓库 / 白名单 CLI"]

    E --> EV[(".workflow-data<br/>Eve 会话与工作流")]
    E -->|"回复"| F

系统被拆成四个职责边界：

会话与编排层 — Eve：接收飞书消息、维护会话状态、调用模型、选择工具、执行审批和调度。
业务上下文层 — Context Platform：以 TeamID 为聚合根，保存 Artifact Graph、冲突、决策、Context Bundle 和执行记录。
代码执行层 — Codex Worker：在受控仓库和文件范围内调用 Codex CLI、收集 diff、执行测试。
本地执行层 — Local Bridge：通过开发机主动建立的出站连接执行白名单命令，不向云端暴露任意 Shell。

组件与代码位置

组件	位置	职责
Eve Agent	`agent/`	Agent 指令、DeepSeek 模型、Feishu Channel、工具、审批、状态和子 Agent
Feishu WS Daemon	`services/feishu-ws/`	使用官方 SDK 接收 `im.message.receive_v1`，转发给 Eve
Context Platform	`src/`	Team Context API、PostgreSQL Store、冲突检测、Bundle、Console、CLI
Codex Worker	`services/codex-worker/`	调用 Codex CLI，限制仓库/文件范围，执行测试并返回结果
Local Bridge	`services/local-bridge/`	Gateway、开发机 Daemon、命令白名单、本地确认和输出脱敏
Team Context Skill	`skills/team-context/`	供本地 Codex 按 TeamID 拉取角色化 Context Bundle
Context Console	`GET /console`	Overview、Artifact Graph、Diff、Conflict、Decision、Bundle 和 Agent Run

消息处理链路

1. 飞书消息进入系统

飞书 im.message.receive_v1
  → Feishu WS Daemon
  → POST /internal/feishu/ws-event
  → Eve Feishu Channel
  → Eve durable session
  → DeepSeek / authored tools
  → 飞书消息 API 回复

Feishu WS Daemon 与 Eve 之间使用 FEISHU_WS_FORWARD_TOKEN 鉴权，并仅通过本机地址通信。长连接模式不需要公网回调、隧道、签名或消息加密配置。

Webhook 模式仍然可用：将飞书回调指向 POST <eve-origin>/webhooks/feishu，并配置 FEISHU_VERIFICATION_TOKEN；如启用加密，再配置 FEISHU_ENCRYPT_KEY。

2. TeamID 绑定

支持以下飞书命令：

/new T12345
/switch T12345
/team T12345
/status
/bundle frontend|backend|fullstack|qa

/new、/switch、/team 会把飞书 Chat 与 TeamID 的当前绑定写入 PostgreSQL。一个 Chat 可以关联多个 Team，但同一时间只有一个 Active Team。

3. 对话与长期上下文的写入边界

系统明确区分两类持久化：

数据	保存位置	写入时机
用户消息、模型回复、工具调用、工作流事件	`.workflow-data`	Eve 收到并处理消息时自动写入
TeamID、Artifact、Context Event、Conflict、Decision、Bundle、Agent Run	PostgreSQL	Eve 明确调用 Context Platform 工具时写入

收到飞书消息不等于写入 Team 长期上下文。 普通闲聊和机器人回复只进入 Eve 会话；只有调用 ingest_context_event 的内容才会成为 PostgreSQL 中的 ContextEvent / Artifact。这样可以避免把闲聊、重复回复或敏感内容无条件写入业务真相源。

当前需要注意：Orchestrator 是否调用 ingest 由 Agent 决策。若希望所有符合规则的需求消息自动归档，应在 Feishu Channel 增加确定性的分类与 ingest policy，而不能仅依赖模型自行选择工具。

持久化架构

Eve durable state

.workflow-data 保存 Eve 自己的会话和工作流恢复数据。它适合 continuation token、模型消息、工具步骤和执行状态，不承担跨会话业务知识库职责。

PostgreSQL Context Platform

PostgreSQL 是 Context Platform 唯一运行时存储；没有 JSON 文件回退。缺少 DATABASE_URL 或 CONTEXT_API_URL 时服务会明确失败。

聚合	表
Team Workspace	`teams`, `team_owners`, `team_chats`, `active_team_by_chat`
Artifact Graph	`artifacts`, `artifact_revisions`, `artifact_relations`
Context Intake	`context_events`, `context_event_artifacts`
Conflict	`context_conflicts`, `context_conflict_artifacts`
Decision	`decisions`, `decision_artifacts`
Context Bundle	`context_bundles`, `context_bundle_artifacts`
Execution	`cli_recipes`, `agent_runs`
Session / Audit	`orchestrator_sessions`, `audit_log`
Schema	`context_schema_migrations`

实体身份、Team 归属、图关系和证据来源使用关系表与外键。JSONB 只用于 structured_data、Bundle 快照、测试结果和审计 metadata 等文档型字段。完整规范见 docs/DATA_MODEL.md。

PostgresStore.transaction() 使用 PostgreSQL transaction-scoped advisory lock，确保多个 Context API 进程不会产生丢失更新；唯一约束、状态检查和外键是最终数据完整性边界。

Context Platform API

主要接口：

POST /v1/teams/:teamId/bind：创建/绑定 Team Workspace。
GET /v1/chats/:chatId/active-team：读取 Chat 当前 Team。
POST /v1/teams/:teamId/events：写入 Context Event 和 Artifact。
GET /v1/teams/:teamId：读取完整 Team Workspace。
POST /v1/teams/:teamId/artifacts/:artifactId/sync：同步并抽取外部 Artifact。
POST /v1/teams/:teamId/relations：建立 Artifact Graph 边。
POST /v1/teams/:teamId/detect-conflicts：检测结构化 claim 冲突。
POST|PATCH /v1/teams/:teamId/conflicts[/:conflictId]：创建或人工处理冲突。
POST /v1/teams/:teamId/decisions：记录人工确认的决策。
POST /v1/teams/:teamId/bundles：生成角色化、版本化 Context Bundle。
POST|PATCH /v1/teams/:teamId/agent-runs[/:runId]：记录执行任务及结果。

外部 Connector 只能访问 CONNECTOR_ALLOWED_HOSTS 中的 HTTPS Host。CONTEXT_EXTRACTOR_URL 可将外部内容抽取为摘要和结构化 claims；PRD 相关冲突会成为 blocking conflict。

Codex 执行链路

Cloud Worker

Eve 检查 Team / Bundle / blocking conflicts
  → 请求人工批准
  → POST Codex Worker /v1/tasks
  → Codex CLI 修改受控仓库
  → 检查 changed files 和 forbidden files
  → 执行 testCommands
  → Context Platform 记录 Agent Run
  → Eve 回传飞书

Local Bridge

Developer Daemon 主动连接 Gateway，只执行 .local-bridge.json 中的固定 recipe。Gateway 无法传入任意 Shell；非只读操作还需要开发机终端确认。输出会脱敏并限制大小。

本地启动

要求：Node.js 24、pnpm、PostgreSQL 17；也可以使用 Docker 启动 PostgreSQL。

pnpm install
cp .env.example .env
pnpm db:up
pnpm context:migrate     # 仅旧 JSON 数据首次迁移时执行

分别启动服务：

pnpm context:api         # :8787，Context API + /console
pnpm codex-worker        # :8790
pnpm bridge-gateway      # :8791
pnpm dev --no-ui         # Eve，默认 :2000
pnpm feishu:ws           # 飞书官方 WebSocket Client

本地 Bridge：

cp .local-bridge.example.json .local-bridge.json
# 配置绝对 repo 路径、TeamIDs、用户和 recipes
pnpm bridge:start

关键环境变量见 .env.example：

DATABASE_URL、CONTEXT_API_URL、CONTEXT_API_TOKEN
FEISHU_APP_ID、FEISHU_APP_SECRET、FEISHU_WS_FORWARD_TOKEN
DEEPSEEK_API_KEY、DEEPSEEK_MODEL
CODEX_WORKER_URL、CODEX_WORKER_TOKEN
LOCAL_BRIDGE_GATEWAY_URL、LOCAL_BRIDGE_GATEWAY_TOKEN

Developer Skill 与 Context CLI

开发者可以在本地 Codex 中使用 team-context Skill，也可以直接运行：

pnpm context:cli -- fetch T12345 --role frontend --purpose codegen

CLI 会生成：

.context/T12345/context.json
.context/T12345/context.md
.context/T12345/figma-diff.md
.context/T12345/api-contracts.md

存在 blocking conflict 时命令以状态码 2 退出，Coding Agent 不应绕过冲突继续实现。

安全与审批边界

Eve session state 不是 Team 业务真相源。
Context API、Codex Worker 和 Local Bridge Gateway 支持 Bearer Token。
Codex 调度、冲突处理、决策写入、本地执行和外部写回经过 Eve approval。
Subagent 只负责专业分析，不能充当 approval boundary。
Connector Host、Worker 仓库、文件范围和 Local Bridge recipe 分别独立白名单。
Local Bridge 不暴露远程任意命令入口。
Artifact 写回要求已有 Decision，并记录 Audit；AI 不应未经人工确认直接修改 PRD。
Secret 只放在未提交的 .env 或 Secret Manager 中。

验证与测试

pnpm typecheck
pnpm test
TEST_DATABASE_URL=postgresql:///altas_test pnpm test
pnpm run info
pnpm build

PostgreSQL 集成测试覆盖：实体完整往返、关联表、并发事务、外键和置信度约束。pnpm run info 应显示 Eve diagnostics 为 0 errors, 0 warnings。

当前边界与后续演进

Context Event 自动归档策略尚未固化，目前依赖 Eve 调用 ingest_context_event。
Codex Worker 和 Local Bridge 的运行中队列仍是进程内状态，生产多实例需要外部 durable queue/store。
本地 PostgresStore 通过兼容事务接口重建聚合快照；数据规模扩大后应将 ContextService 改为实体级 Repository/SQL mutation。
生产部署需要 TLS、Secret Manager、数据库备份、连接池监控和迁移发布流程。

设计需求与实现证据的逐项映射见 docs/IMPLEMENTATION.md。

Name		Name	Last commit message	Last commit date
Latest commit History 4 Commits
agent		agent
db		db
docs		docs
services		services
skills/team-context		skills/team-context
src		src
test		test
.env.example		.env.example
.gitignore		.gitignore
.local-bridge.example.json		.local-bridge.example.json
README.md		README.md
compose.yml		compose.yml
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Altas — 飞书驱动的 Eve / Codex Orchestrator

架构总览

组件与代码位置

消息处理链路

1. 飞书消息进入系统

2. TeamID 绑定

3. 对话与长期上下文的写入边界

持久化架构

Eve durable state

PostgreSQL Context Platform

Context Platform API

Codex 执行链路

Cloud Worker

Local Bridge

本地启动

Developer Skill 与 Context CLI

安全与审批边界

验证与测试

当前边界与后续演进

About

Uh oh!

Releases

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

Altas — 飞书驱动的 Eve / Codex Orchestrator

架构总览

组件与代码位置

消息处理链路

1. 飞书消息进入系统

2. TeamID 绑定

3. 对话与长期上下文的写入边界

持久化架构

Eve durable state

PostgreSQL Context Platform

Context Platform API

Codex 执行链路

Cloud Worker

Local Bridge

本地启动

Developer Skill 与 Context CLI

安全与审批边界

验证与测试

当前边界与后续演进

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages