AgentStrata 是一个面向外部应用的可定制 Agent 运行系统。它以自有四层架构承载应用接入、会话、上下文和 Agent 能力。项目自行实现能力装配、上下文组织、工具使用，以及基于 LangGraph 的执行循环与协作策略；这些自有实现都是 Harness 的主要优化对象。

你可以把 Agent 连接到 Live2D、QQ / NapCat，或其他提供 API、工具接口和消息渠道的项目，为应用配置独立的模型、人格、工具与记忆。Harness 根据需求开发适配、能力模块和运行策略，通过 Eval 与独立验收验证改进，再在授权范围内启用到指定实例。Codex 通过公开接口作为可选执行器接入，当前也是 Harness 的开发 worker。

外部应用提出能力需求，自有 Agent 据此改进：每次改动有目标，效果有对照，运行版本有来源。

第一次贡献可从未认领的新手任务和首次 PR 步骤开始。欢迎中文或英文交流。

项目特色

应用场景

让 Live2D 成为 Agent 的交互界面。 通过独立客户端完成文字、语音和角色呈现，Agent 负责理解任务、组织上下文与调用工具；表情和动作通过工具接口执行，并记录浏览器回执。角色生成器、角色库与 Windows 桌面壳作为可选组件配合使用。

让 QQ / NapCat 成为 Agent 的消息渠道。 沿 OneBot 接入消息收发，在宿主中统一处理身份、准入、会话与工具权限。Agent 的能力改进可以同时验证对 QQ 行为的影响，避免只改善一个入口，却破坏另一个入口。

把自己的项目接入 Agent。 提供接口说明或固定仓库版本、接入目标与可修改范围，由 Harness 调查已有能力，设计工具、插件或适配器。源码维护、构建和部署按具体需求展开，应用仍可以独立运行。

例如，你可以提出这样的需求：

让 Live2D 角色在任务完成后给出正确的动作反馈；任务失败时如实说明，避免误播完成动作。同时保留 QQ 原有的回复和权限行为。

围绕这个目标，框架组织候选修改和验收：核对 Agent 是否选用了合适的工具、动作是否真正执行、失败路径是否正确，以及 QQ 是否出现回归。评测、审核与启用结果分别保留，便于判断是否接受、继续返工或撤回版本。

框架总览

Channel → Gateway → Application → Agent 四层共同构成产品主体。 Agent 层内的 AgentRuntime 是统一执行入口与共享能力装配；自有 LangGraph Agent 实现模型与工具循环。Harness 和 Eval 在消息链之外工作，生成并验证下一版 Agent、配置或桥接。

flowchart TB
    subgraph SYSTEM["AgentStrata · 自有四层 Agent 运行系统"]
        CH["Channel · 平台事件与投递"] <--> GW["Gateway · 身份、准入与协调"]
        GW <--> APP["Application · 会话、资源与上下文准备"]
        subgraph AGENT["Agent 层 · 自有能力与执行设计"]
            AR["AgentRuntime · 统一入口与能力装配"]
            CAP["上下文与工具能力 · PromptPlan / ToolRegistry / 委托"]
            LG["自有 LangGraph Agent · 图、工具循环与停止策略"]
            CA["Codex Adapter · 公开协议适配"]
            AR <--> CAP
            AR --> LG
            AR --> CA
        end
        APP <--> AR
    end
    QQ["QQ / NapCat"] <--> CH
    LIVE["Live2D / 自定义客户端"] <--> GW
    PROFILE["独立 Agent Profile"] --> APP
    CAP <--> EXT["外部工具 / MCP / 应用接口"]
    CA <--> CX["Codex app-server · 可选业务执行器"]

    UI["Console / CLI"] --> H["Harness · 调查、开发、返工与审核"]
    AR -. "运行证据与反馈" .-> H
    H -- "当前开发 worker" --> CX
    H <--> E["Eval · 基线、候选与回归对照"]
    H --> ACCEPT["独立接受 · 绑定精确候选"]
    E -- "评测结果" --> ACCEPT
    ACCEPT -- "在授权范围内" --> V["版本管理 · 启用、核验与撤回"]
    V -. "更新自有 Agent 与策略" .-> AR
    V -. "更新应用配置与桥接" .-> APP

    classDef runtime fill:#eff6ff,stroke:#3b82f6,color:#172554;
    classDef improve fill:#ecfdf5,stroke:#10b981,color:#064e3b;
    class CH,GW,APP,AR,CAP,LG,CA,PROFILE runtime;
    class H,E,ACCEPT,V improve;
    style SYSTEM fill:#f8fafc,stroke:#64748b
    style AGENT fill:#eff6ff,stroke:#3b82f6

日常消息遵循 Channel → Gateway → Application → Agent 四层职责。Live2D 等独立客户端直接使用 Gateway；外部功能也可以作为工具被 Agent 调用。身份与权限由宿主确定，执行结果、服务方确认和用户可见交付分别记录。

自有 Agent 与可选执行器

项目统一定义身份、权限、上下文、工具、会话和结果契约。agents.runtime 保留 langgraph 和 codex 两种选择，一个正常回合由其中一种执行，模型连接与认证独立管理。LangGraph 路径是深度运行策略定制的主线。

应用描述引用独立的 Agent Profile，实例状态由各应用持有。近期 Harness 开发 worker 只使用 Codex，其模型与被优化应用分别绑定：Codex worker 可以修改和验证自有 LangGraph Agent。Codex 业务执行器自身的循环与压缩仍由其公开接口决定，不承诺修改未开放的内部行为。

模块职责和源码入口见架构总览、运行链和 Agent 执行契约。

改进闭环

自我优化的主要对象是项目拥有的 Agent 实现：能力装配、工具发现与执行、上下文组织、Skill、LangGraph 图和协作策略。应用需求决定修改位置，优先检查能力、上下文和应用策略；问题确实位于控制流程时，再修改循环、停止或委托策略。执行循环始终属于正式优化范围。

例如，外部工具已经提供正确接口，但 Agent 在相似工具中选错了能力，改进可以落在工具呈现、发现或上下文组织。比较时固定外部工具、任务、模型和环境，检验 Agent 侧修改是否提高任务完成与参数正确性，并保护权限和其他应用行为。配置调整、桥接功能扩展和自有 Agent 实现变更分别评价。

Harness：把需求变成可审查候选

Harness 编排直接复用 LangGraph 的 StateGraph、子图、检查点和中断恢复。它组织开发与验收；Agent 层的 LangGraph 图组织日常模型和工具执行，两者职责独立。AgentStrata 实现来源与授权、角色权限、隔离工作区、操作回执、预算和接受规则。

• 按职责协作。 Plan 调查和设计，Coding 修改获准代码，Test 提供独立验证，Review 审核精确候选；必要时重新规划或定向返工。
• 当前任务的规则保持冻结。 候选可以改进后续使用的实现，不能靠更改本轮评分、验收条件或宿主控制程序获得通过。
• 不同目标使用不同证据。 故障修复核对原问题，新功能验证新目标，代码熵治理要求实际改善与行为保持；可复用经验可以进入受限 Skill 学习。
• 恢复以事实为依据。 图检查点保存执行位置，操作回执记录外部动作。结果未知时先查询原执行，不重复创建任务或盲目重放副作用。

机制见 Harness 契约，使用见需求与修复指南。

Eval：回答“改动有没有用”

Eval 管理 Case、Target、Trial、隔离执行、评分、结果与证据。项目实现 IFEval、BFCL、GAIA 等公开 benchmark 的适配、执行与评分流程，并维护 Agent 任务、桥接、权限与红队用例。

评测分别检查三个层面：Agent 是否完成任务，桥接是否遵守接口与权限，外部项目是否实际执行或交付。 自有 Agent 改进重点检查工具选择、参数、上下文使用和实际效果；调用次数、上下文量、延迟与费用作为相应任务的辅助指标。原生评分、确定性事实和必要的语义评分分别保存，环境失败与证据缺失单独记录。基线、模型、题目或环境变化会影响可比性，关键行为退步不能由总分增长抵消。

机制见 Evaluation，运行步骤见评测指南。

版本管理：让接受结果对应到实际运行

通过验收的代码和配置以独立版本保存。启用时核对目标实例、运行条件和候选身份，等待已有执行收尾，再切换并检查实际进程的代码、配置和监听归属。失败尝试恢复上一版本，恢复结果未知时保留诊断。

候选通过、源码提交、版本启用和真实交付是不同事实。 凭据、会话、记忆与工作区留在原实例；依赖升级和持久数据迁移需要各自的验证与恢复依据。机制与操作见版本交付和实例运维。

产品界面

Console 将实例、运行任务、改进过程和评测证据集中呈现。以下为使用示例数据渲染的界面截图；图中任务状态与数字用于展示信息组织，实际效果以对应运行记录为准。点击图片可查看原图。

Harness：沿需求、基线候选对照和独立验收追踪一次改进。

Eval：选择评测对象与题目，查看评分方式和执行条件。

实例管理：查看 Gateway、渠道连接与进程状态。

代码治理：保留调查依据、问题范围与候选审核结论。

快速开始

准备源码环境

核心运行环境为 Linux / WSL2，Python 支持 3.12–3.13。安装 Git 与 uv 后：

git clone https://github.com/Ling-ye/AgentStrata.git
cd AgentStrata
uv sync --locked --extra agent --extra acp --extra dev --extra evaluation --extra weixin
uv run agentstrata --help

以上准备开发环境。模型连接、凭据、平台账号和运行组件按使用路径配置；秘密放在环境变量或私有环境文件中，不写入仓库。

选择一条路径

Console 是管理入口，应用运行与评测服务各自拥有生命周期。选配 Live2D 客户端使用独立 Python 环境；Windows 桌面壳通过 WSL 后端工作。各组件的安装条件、模型调用费用与第三方服务要求以对应指南为准。

从源码理解项目

Python 包命名空间保留为 chatcopilot，对外命令为 agentstrata。领域内部遵循 Types → Config → Repo → Service → Runtime → UI 的依赖约束；它描述源码依赖，与消息运行的四层架构是两个视角。

开源基础与设计参考

AgentStrata 优先复用成熟基础设施，自行实现四层运行系统、自有 Agent 能力与策略、应用桥接、评测证据和独立验收。

OpenClaw 与 Deep Agents / better-harness提供宿主、执行循环和评测驱动改进的设计参考。实际依赖、固定源码版本及采用边界见架构说明与源码复用依据。

参与开发

欢迎贡献应用桥接、Agent 能力、评测用例、Harness 改进和工作台体验。一个清楚的需求、一条有代表性的失败路径，或一组可复现的基线与候选证据，都可以成为贡献的起点。

普通社区 PR 通过对应检查与人工审查即可，不要求贡献者自行运行 Harness。欢迎 AI 辅助，作者负责理解改动、核实验证结果和回应审查。接入成果可在作品展示分享。

从贡献指南开始，按文档导航进入相关领域。架构与公共契约的改动遵循 SDD。AI 协作者先读 AGENTS.md，再沿当前任务的源码和测试核对事实。

问题与建议 · 使用支持 · 安全报告 · 行为准则 · 变更记录

版权、许可与源码

Copyright (C) 2026 Lingye · 联系：[email protected]。

项目自有代码和文档采用 AGPL-3.0-only，完整适用范围见 COPYRIGHT。第三方项目、模型、SDK 和改编材料保留各自许可，见第三方声明。Open-LLM-VTuber 前端补丁适用其上游条款。历史版本已授予的 MIT 权利不受许可迁移影响。

项目源码可公开获取。部署修改版时，将 CHATCOPILOT_SOURCE_URL 指向实际运行版本的完整源码获取地址；Console 的许可与源码入口、agentstrata source 和机器人 /source 使用同一来源。具体要求见公开与发布契约。