AgentFlux

AgentFlux 是基于 pi 的多 Agent 调度扩展。日常任务在 Main Agent 中直接执行，需要时可派发子代理；Workflow（固定 DAG）与 Community（Issue/Claim 协作）是两种可选的执行方法，由 Main Agent 按任务需要调用。同一时间只允许一个项目级执行空间（main / workflow / community）活跃。

安装

AgentFlux 是 npm 上的 pi 包，安装后自动注册 /flux 命令族和调度工具：

pi install npm:agentflux            # 从 npm registry 安装（推荐）
pi install git:github.com/bluelightgit/AgentFlux   # 从 git 仓库安装
pi install git:github.com/bluelightgit/[email protected]  # 固定 tag

未安装时临时试用：pi -e npm:agentflux。

开发本仓库时，先执行 npm run build 生成 dist/extension/entry.js，然后在项目内直接运行 pi（.pi/settings.json 已配置本地扩展）或手动加载：pi -e ./dist/extension/entry.js。发布包只携带 dist，不携带 src。

核心概念

• 执行：任务在 Main Agent 中直接完成，或按需派发子代理（flux_agent）。AgentFlux 不预设执行方式。
• Agent 实体：单一子代理模型。三种创建路径——默认模板、角色模板、从既有会话树分叉（继承源会话记忆）；可重名（自动 xxx(1) 后缀）；三层作用域（global / project / session，会话结束清理 session 作用域）。run 携带指令与超时并返回对话的最近消息，delete 硬删除，自动 GC 保留最近 k 个（默认 10）。创建与单次运行可按任务指定 model/thinking 覆盖（未知模型拒绝；运行覆盖不修改记录）。TUI 会话中 run 默认后台执行（立即返回、完成时通知、/flux agent stop 可中断），--sync 或 headless 模式同步等待结果；运行过程实时显示（working 行逐条刷新消息与工具调用）；TUI 底部状态行显示运行中的子代理。直接对话：/flux agent list 的 Agent 详情最下方显示 npx pi --session "<会话文件>" 启动命令，在新窗口打开子代理会话完整对话（与主 Agent 能力一致，对话写回会话记忆，run 仅受 running 状态阻塞）。
• Workflow：保存的固定 DAG 定义（含版本历史），按需创建执行；节点可并行、可挂质量门，执行支持断点续跑（resume）。
• Community：Issue/Claim 协作。提案（propose/support/oppose）可多提案绑定认领，claim → submit → review（pass/rework）→ resolve，带轮次、成本与停摆门禁。
• 消息：Message V2 提供 Agent 间直接消息、群组与投递确认（send/poll/ack/lease 重投）。
• 互斥：.agentflux/runtime/active-context.json 是权威互斥状态，一个空间活跃时阻止其他空间启动；空间内并行允许。
• 权限：角色模板定义上界，注册实例与单次运行逐层收窄，下层不能扩大上层能力。子代理的 edit/write 拒绝修改未声明文件；文件锁防并行编辑冲突。此门禁提供进程与文件级保护，覆盖 OS 级沙箱。

TUI 命令

| 命令 | 作用 | |---|---| | /flux | 打开 Workbench 菜单；/flux 可补全子命令 | | /flux task list\|show\|new\|reuse\|resume\|continue\|retry | 任务注册表：查询、新建、复用、恢复、继续、重试（保留父任务谱系，不修改历史任务） | | /flux workflow list\|show\|reuse\|modify\|delete | 已保存 Workflow 定义：列出、查看 DAG、按原版本执行、生成新版本并执行、删除 | | /flux agent list\|create\|run\|stop\|retry\|delete\|gc | 子代理生命周期：列出、创建（默认/角色模板）、对话、停止、重跑上次任务、删除、自动回收 | | /flux issue list\|create\|show\|comment\|propose\|support\|oppose\|claim\|submit\|review\|resolve\|delete | Community 协作全流程 | | /flux message send\|inbox\|ack | 直接消息：发送、收件箱、确认 | | /flux message group list\|create\|send | 消息群组 | | /flux fork [last\|index\|entryId] | 从当前 pi 会话创建真实分支 | | /flux status | 当前任务、活跃运行、Agents 与 Issues 概览 | | /flux space | 活跃空间、Workflow/Community 定义与最近 Agent 活动时间线 | | /flux usage | Main 会话逐轮 token、缓存命中与成本 | | /flux gc [dry-run] | 预览或执行终态 Agent、消息与孤儿 session 回收 | | /flux cancel [taskId] | 取消运行中的 Workflow | | /flux compact | 查看上下文压缩建议 |

Main Agent 可通过工具直接调度：flux_task（历史查询与任务操作）、flux_agent（子代理）、flux_workflow（DAG 执行）、flux_issue（Community）、flux_message（消息）。用户只需描述目标（如“继续最近的 Workflow”“恢复刚才超时的任务”），无需提供内部 ID。

数据目录

.agentflux/
├── agentflux.json       # 预算、缓存、通信、回收等配置
├── models.json          # 模型表、角色模板与共享 Skills
├── issues.json          # Community Issues 与 Claims
├── events.jsonl         # task/agent/message telemetry
├── runtime/             # 任务注册表、Workflow 定义、会话与运行状态
│   ├── tasks.json       # Task Registry
│   ├── workflows.json   # Workflow 定义及历史版本
│   ├── runs/<id>/       # 执行 DAG、checkpoint 与产物
│   └── sessions/        # 子代理会话文件
└── shared/              # Message V2、文件锁与协作数据

验证

npm run verify                        # 类型检查 + 全部确定性回归（25 组，622 断言）
npm run test:live                     # DeepSeek 全链路 smoke
npm run test:live:history             # 同一会话两轮任务：自动继续与父任务关系
npm run test:live:workflow-reuse      # 创建并精确复用已保存 Workflow
npm run test:live:workflow-modify     # 修改得到 v2，保留 v1，再精确复用 v2

Live 测试默认使用本机 ~/.pi/agent 凭据与 octopus-anthropic provider；通过 AGENTFLUX_LIVE_* 环境变量可指向任意 OpenAI/Anthropic 兼容端点（baseUrl、api、apiKey、模型、thinking、用例子集、provider id，详见 tests/live/）。CI 中由 .github/workflows/live.yml 手动或定时触发。

文档导航

| 文档 | 内容 | |---|---| | docs/26-implementation-status.md | 当前实现状态、测试证据与已知限制 | | docs/33-workstyle-redesign.md | 执行模型与空间互斥设计 | | docs/31-live-test-report-2026-08-12.md | 真实链路测试报告 | | docs/32-code-review-2026-08-14.md | 代码评审与修复记录 | | docs/design-spec.md 与 docs/00-overview.md | 设计与总览 |