AgentFlow Console

AgentFlow Console 是一个面向 AI Agent 工作流的本地控制台。它用于管理 Agent 会话、执行轮次、审批请求、历史记录与实时状态，并通过浏览器仪表盘和结构化 API 把分散的 Agent 操作整理成一套可观察、可审计、可继续扩展的控制平面。

这个项目的重点不是把终端内容简单搬到网页里，而是把 AI Agent 的真实工作对象抽象出来：session、turn、approval、history、runtime state、event stream。这些对象可以被网页端查看，也可以被其他客户端、自动化脚本或后续移动端复用。

当前版本聚焦于本地优先的 Agent 工作台能力，适合管理 Codex、Claude Code 或其他编码 Agent 的会话状态、历史导入、审批流与任务执行记录。

项目目标

AI Agent 在本地开发环境中通常会产生几个问题：

会话分散在不同终端、目录和历史文件里，难以统一查看。
执行过程中的审批请求容易被打断，缺少集中的处理入口。
历史 transcript 与当前 runtime 状态混在一起，无法清楚区分哪些会话可继续接管，哪些只能作为历史记录查看。
Agent 的 plan、diff、回复、错误状态和最终结果缺少统一的数据结构，后续很难做复盘、展示或二次开发。
如果要做移动端、Web 控制台或自动化系统，需要一层稳定 API，而不是直接依赖终端文本。

AgentFlow Console 的目标是提供一层轻量、本地、结构化的控制平面，让 AI Agent 工作流从“散落的命令行过程”变成“可以被管理的任务系统”。

工作原理

整体链路如下：

Codex / Claude Code / Transcript Files / Custom Agent Runtime
        │
        │ session, turn, approval, history, runtime state
        ▼
AgentFlow Console
  - Session lifecycle model
  - Turn timeline model
  - Approval queue
  - Transcript import
  - Local JSON persistence
  - HTTP API + SSE event stream
        │
        │ browser / API client / future mobile client
        ▼
Dashboard & Integrations
  - 会话总览
  - 会话详情
  - 审批中心
  - 状态统计
  - 历史导出

这套设计的核心点是：

控制台不直接依赖终端截图或 OCR，而是使用结构化数据描述 Agent 工作流。
managed、runtime_available、history_only、ended 等生命周期状态被明确拆分。
审批请求从会话历史中独立出来，形成可集中处理的 approval inbox。
Web Dashboard 和外部系统都消费同一套 HTTP API 与 SSE 事件流。
本地状态默认持久化到 .agentflow/state.json，便于离线使用与恢复。

当前已实现的能力

1. 会话生命周期管理

AgentFlow Console 使用明确的生命周期阶段描述每个 Agent 会话：

managed：由控制台创建或接管的当前会话。
runtime_available：检测到可接管 runtime，但尚未正式纳入控制。
history_only：从 transcript 导入的历史记录，只用于查看与归档。
ended：已经结束的会话，可保留历史，也可重新附着为可管理状态。
discovered：预留给后续自动发现逻辑的会话状态。

通过这种拆分，控制台可以同时展示“正在运行的任务”“可继续接管的任务”和“仅用于复盘的历史任务”，避免把不同状态的会话混在一起。

2. Turn 时间线

每个会话包含多个 turn。一个 turn 可以记录：

用户 prompt
Agent 回复
执行状态：pending、running、completed、failed、interrupted
plan 与 plan explanation
diff 内容
timeline item
错误信息
开始时间、完成时间和持续时间

这让 Agent 的工作过程可以被完整复盘，而不是只留下最终回复。

3. 审批中心

AgentFlow Console 将审批请求作为一等对象处理。当前支持的审批类型包括：

command：命令执行审批
file_change：文件变更审批
permission：权限审批
input：结构化用户输入请求

每个 approval 都有独立 ID、所属 session、所属 turn、审批原因、审批摘要、候选选项和最终决策。决策支持：

approve
deny
defer
cancel

这使得审批流可以脱离单个终端窗口，被集中展示、处理和记录。

4. 历史导入

项目内置 transcript importer，可将 JSONL、Markdown 或纯文本形式的历史对话解析为 history-only session。

导入逻辑会尝试识别：

user / prompt 内容
assistant / agent 回复
timestamp
cwd
文件名标题
首轮 prompt 预览

这部分能力适合把过去的 Agent 工作记录整理进统一仪表盘。

5. 本地 Dashboard

仓库内置轻量浏览器控制台，默认由本地服务直接提供：

会话总览
会话详情
待审批列表
生命周期状态标签
统计卡片
doctor 检查入口
dashboard refresh

Dashboard 使用项目的 HTTP API 获取数据，不依赖 mock 数据或额外后端。

6. HTTP API 与 SSE 事件流

AgentFlow Console 暴露统一的 JSON API，用于创建会话、追加 turn、查询 dashboard、处理审批、结束会话、归档会话和导出状态。

同时提供 SSE 事件流，用于向浏览器或外部客户端推送控制台事件，例如：

session.created
session.imported
session.runtime_detected
turn.started
turn.updated
turn.finished
approval.queued
approval.resolved
session.ended
session.attached
session.archived

快速开始

1. 环境要求

Node.js 20+
npm
可选：本机已安装 codex 或 claude CLI，便于 doctor 检查

2. 安装依赖

npm install

3. 启动开发服务

npm run dev

默认会启动带 demo 数据的本地服务：

http://127.0.0.1:4318

浏览器打开该地址即可查看 Dashboard。

4. 构建并运行生产版本

npm run build
npm run start

生产模式默认不注入 demo 数据，如需 demo 数据可直接使用 CLI：

agentflow serve --demo

CLI 命令

启动控制台

agentflow serve

常用参数：

agentflow serve --port 4318 --host 127.0.0.1 --data-dir .agentflow

参数说明：

参数	默认值	说明
`--port`	`4318`	本地服务监听端口
`--host`	`127.0.0.1`	本地服务监听地址
`--data-dir`	`.agentflow`	状态文件保存目录
`--demo`	`false`	是否写入演示会话数据

环境检查

agentflow doctor

doctor 会检查：

本机 codex 命令是否存在
本机 claude 命令是否存在
常见 transcript 目录是否存在

当前检查路径包括：

~/.codex
~/.claude
~/Library/Application Support/Codex
~/Library/Application Support/Claude

输出 demo 快照

agentflow demo

该命令会直接打印一份 demo dashboard JSON，适合快速查看数据结构。

API 概览

服务默认监听：

http://127.0.0.1:4318

健康检查

Method	Endpoint	说明
`GET`	`/healthz`	服务健康检查
`GET`	`/api/v1/diagnostics`	返回 uptime 与 SSE 订阅数量

Dashboard

Method	Endpoint	说明
`GET`	`/api/v1/dashboard`	获取 dashboard 快照
`GET`	`/api/v1/export`	导出 sessions 与 approvals
`GET`	`/api/v1/events`	订阅 SSE 事件流

Sessions

Method	Endpoint	说明
`GET`	`/api/v1/sessions`	获取会话列表
`GET`	`/api/v1/sessions/:id`	获取会话详情
`POST`	`/api/v1/sessions`	创建 managed session
`POST`	`/api/v1/sessions/:id/turns`	在会话中开启新 turn
`POST`	`/api/v1/sessions/:id/end`	结束会话
`POST`	`/api/v1/sessions/:id/archive`	归档会话
`POST`	`/api/v1/sessions/:id/attach`	将会话重新附着为可管理状态

Approvals

Method	Endpoint	说明
`POST`	`/api/v1/sessions/:id/approvals`	为指定会话创建审批请求
`POST`	`/api/v1/approvals/:id/resolve`	处理审批请求

API 示例

创建会话

curl -X POST http://127.0.0.1:4318/api/v1/sessions \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "codex",
    "cwd": "/work/demo",
    "prompt": "Build a dashboard for AI agent sessions",
    "name": "Dashboard control plane"
  }'

创建审批请求

curl -X POST http://127.0.0.1:4318/api/v1/sessions/<session-id>/approvals \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "command",
    "reason": "Run focused test suite",
    "summary": "npm test -- dashboard",
    "choices": ["approve", "deny"]
  }'

处理审批请求

curl -X POST http://127.0.0.1:4318/api/v1/approvals/<approval-id>/resolve \
  -H "Content-Type: application/json" \
  -d '{ "decision": "approve" }'

数据模型

Dashboard Snapshot

Dashboard 返回的数据主要包含三部分：

agent：当前控制台实例信息
stats：总会话数、已加载会话数、活跃会话数、待审批数量等统计
sessions：会话摘要列表
approvals：当前待处理审批列表

Session Summary

每个 session summary 记录：

id
agentId
name
preview
cwd
source
status
lifecycleStage
loaded
runtimeAvailable
runtimeAttachMode
resumeAvailable
pendingApprovals
lastTurnId
lastTurnStatus
createdAt
updatedAt

Turn Detail

每个 turn detail 记录：

prompt
assistantText
status
diff
plan
items
error
startedAt
completedAt
durationMs

Approval View

每个 approval view 记录：

kind
sessionId
turnId
reason
summary
choices
decision
params
createdAt
resolvedAt

仓库结构

agentflow-console
├── public
│   ├── index.html        # Web dashboard 入口
│   ├── app.js            # Dashboard 前端逻辑
│   └── styles.css        # Dashboard 样式
├── scripts
│   └── copy-public.mjs   # 构建后复制静态资源
├── src
│   ├── cli.ts            # agentflow CLI
│   ├── core
│   │   ├── agent-flow-service.ts
│   │   └── types.ts
│   ├── importers
│   │   └── transcripts.ts
│   └── server
│       └── create-http-app.ts
├── tests                 # Vitest 测试
├── package.json
└── tsconfig.json

开发命令

npm run dev

启动带 demo 数据的本地开发服务。

npm run build

编译 TypeScript，并复制 Dashboard 静态资源到 dist/public。

npm run typecheck

执行 TypeScript 类型检查。

npm test

运行 Vitest 测试。

当前状态

当前版本已经实现：

本地 Agent control plane 基础模型
Session lifecycle 管理
Turn timeline 管理
Approval inbox 与审批处理
JSONL / Markdown transcript 导入器
Dashboard API
Browser Dashboard
SSE 事件流
本地 JSON 状态持久化
CLI：serve、doctor、demo
基础单元测试与 HTTP API 测试

当前尚未内置：

登录与设备配对
公网 relay
移动端客户端
自动审批策略引擎
与真实 Agent runtime 的完整双向协议桥接
多用户权限系统

这些部分适合作为后续版本继续扩展。

适用场景

AgentFlow Console 适合以下场景：

本地管理多个 AI Agent 工作会话
汇总 Codex / Claude Code 类工具的执行记录
将 Agent 审批流集中到一个 Web 页面处理
为作品集或内部工具展示 AI 工程化工作流
为后续移动端、桌面端或自动化平台提供统一 API
把历史 transcript 转成可浏览、可归档、可复盘的结构化记录

Roadmap

后续可扩展方向：

Codex runtime adapter
Claude Code runtime adapter
自动 transcript 目录扫描
更完整的实时刷新体验
移动端或桌面端客户端
远程安全访问方案
审批策略与规则引擎
会话搜索、筛选与标签管理
更细粒度的 diff / plan 可视化

License

MIT

Name		Name	Last commit message	Last commit date
public		public
scripts		scripts
src		src
tests		tests
.gitignore		.gitignore
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Latest commit

History

Folders and files

Repository files navigation