跳转到内容

Implementation Roadmap

本文件保留的是“最初的分阶段实施草案”,方便理解为什么代码结构会这样拆分。

如果你要判断“当前已经做到了什么、还缺什么”,请优先看站点内的 当前进度。后者对应仓库持续维护的现状台账;本文件更多用于解释原始实施顺序。

对于 worker 执行层、扩缩容、控制面与商业化治理的后续路线,请看专门维护的文档:

在可信内网 / 自有环境前提下,交付一个可用的 Agent Engine 服务,满足:

  • 多用户共享一个实例
  • 多 workspace 自动发现本地能力
  • Agent 可在 workspace 中执行 shell、文件操作、Action、Skill、Tool
  • 提供 OpenAPI + SSE
  • 具备基础审计、队列、取消和超时能力

补充:

  • 上述目标中的大量能力已经落地
  • 当前真正尚未补完的重点,主要集中在文档真值同步、heartbeat / worker 恢复、外部 caller context 接入收敛
  • TypeScript + Node.js 服务端骨架
  • oah 终端客户端基础骨架
  • OpenAPI 3.1
  • PostgreSQL + Redis 基础设施
  • workspace / session / message / run 领域模型
  • workspace 根目录 AGENTS.md 加载
  • .openharness/settings.yaml 加载
  • .openharness/ 自动发现与校验
  • 服务端配置文件加载
  • AgentRegistry / ModelRegistry / ActionRegistry / SkillRegistry / ToolRegistry / HookRegistry
  • 平台内建 agent 注册与装配
  • LocalWorkspaceBackend
  • per-session 串行调度
  • SSE 事件流
  • SandboxBackend
  • 复杂 action DSL
  • 多级 AGENTS.md 继承
  • 图形化控制台
  • 公网多租户零信任安全体系
  • 建立 monorepo 或 packages 结构
  • 接入 OpenAPI 生成和校验
  • 初始化 PostgreSQL 和 Redis
  • 建立基础日志和错误处理
  • 定义服务端配置文件结构
  • 实现 workspace / session / message / run 数据模型
  • 提供创建 workspace、session、message、run 的 API
  • 实现 run 状态机
  • 实现 Redis session queue 和 session lock
  • 实现 Orchestrator worker
  • 实现取消、超时和 heartbeat

当前状态:

  • done session queue / lock 主链路
  • done 取消
  • done run / tool timeout
  • done heartbeat
  • partial worker 启动恢复当前已支持 stale run fail-closed 回收,但尚未支持自动续跑
  • 实现 workspace 根目录扫描
  • 收敛为单一 workspace_dir 扫描
  • 实现服务端 paths.workspace_dir 扫描
  • 解析 AGENTS.md
  • 加载平台内建 agent 注册表
  • 解析 .openharness/settings.yaml
  • 解析 .openharness/agents/*.md
  • 解析 agent frontmatter、正文 prompt 与 system_reminder
  • 实现 platform agent 与 workspace agent 的同名覆盖规则
  • 解析 mode、switch、subagents 配置
  • 解析 .openharness/models/*.yaml
  • 解析 .openharness/actions/*/ACTION.yaml
  • 解析 .openharness/skills/*/SKILL.md
  • 解析 settings.skill_dirs 并扫描额外 skill 目录
  • 实现 skill 同层冲突报错、跨层冲突 warning + 覆盖
  • 实现 skill catalog 注入与 Skill 工具
  • 解析 .openharness/tools/settings.yaml
  • 发现 .openharness/tools/servers/*
  • 解析 .openharness/hooks/*.yaml
  • 实现 agent 切换检测,以及在最新 user message 上附加 <system_reminder>
  • 实现 agent.switch 与 agent.delegate 的 allowlist 校验
  • 实现 agent.await 与并发 subagent 调度
  • 将 workspace 自动发现统一收敛到 paths.workspace_dir
  • 将 paths.workspace_dir 下子目录自动注册为 kind=project workspace

当前状态补充:

  • done platform built-in agent 注册与同名覆盖规则
  • done native tools 最小集
  • done agent policy 中 run_timeout_seconds、tool_timeout_seconds、parallel_tool_calls
  • partial subagent 并发治理仍有后续空间,尤其是恢复与一等父子 run 字段
  • 实现 LocalWorkspaceBackend
  • 实现 NativeToolExecutor
  • 实现 ActionExecutor
  • 实现 SkillExecutor
  • 实现 Tool Executor
  • 实现 invocation projection 与 dispatcher

Phase 6: 流式输出与前端接入协议

Section titled “Phase 6: 流式输出与前端接入协议”
  • SSE endpoint
  • 事件协议
  • 增量输出
  • 已有初版 oah tui 作为终端客户端入口
  • 已有初版 oah workspace:list / oah workspaces
  • 已有初版 oah catalog:show
  • 实现统一的 oah session inspect
  • 实现 oah action run
  • 实现 oah model generate
  • 实现 oah run inspect
  • 继续增强 TUI 的 run timeline、tool call、prompt compose 和 catalog 检视
  • Hook runtime
  • capability 校验
  • tool 审计
  • policy deny 基础机制
apps/
server/
packages/
api/
core/
orchestrator/
context/
agents/
actions/
skills/
tools/
hooks/
execution/
storage/
events/
sdk/
  • Web framework:Fastify 或 Hono
  • Validation:Zod 或 TypeBox
  • OpenAPI:基于 schema 自动生成
  • ORM / SQL:Drizzle ORM 或 Kysely
  • Queue / Lock:Redis
  • Logging:Pino
  • Tracing:OpenTelemetry

如果 YAML DSL 一开始做太强,会拖慢整体交付。建议先坚持单入口 action 模型。

Hook 如果能力边界过大,会让排障和安全控制都变差。建议当前阶段严格 capability 化。

当前使用本地 backend,默认前提是可信内网环境。若后续对外开放,需优先补 sandbox backend。

外部 tool server 可能存在延迟、失败或协议兼容性问题,需要:

  • 连接健康检查
  • 调用超时
  • 错误降级
  • SandboxBackend
  • workspace secrets 管理
  • action workflow DSL / matrix / 重试 / loop / DAG 分支
  • 多级 AGENTS.md
  • 更细粒度权限策略
  • 历史 run 回放
  • 管理后台与配置校验工具

建议先以“单实例服务 + 单 worker 进程”跑通闭环,再扩展到:

  • 多 worker
  • 横向扩展
  • 更强审计和 tracing

先确保系统抽象边界正确,再追求复杂部署形态。