代理控制框架

Name: 代理控制框架
Author: FutureAtoms

作者：FutureAtoms23 星标更新：2025-09-20

安装使用来源：spider==github.com

项目介绍

【技术文档摘要】

Agentic Control Framework (ACF)

作者: Abhilash Chadhar (FutureAtoms) 仓库: agentic-control-framework

AI 原生编排层（CLI + MCP），带有超过80种工具用于上下文工程——检索、代码编辑、浏览器自动化、终端编排和持久记忆——专为 Claude Code、Cursor、Codex 和 VS Code 设计。此 README 反映了当前代码和已测试的集成。

CLI 入口：bin/acf
MCP 服务器：bin/agentic-control-framework-mcp → src/mcp/server.js
示例客户端配置：config/examples/
测试：npm run test:cli, npm test

包含内容

盒子里有什么

任务管理器，具有优先级、依赖关系、子任务和模板
功能丰富的 CLI
MCP 服务器（通过 stdio 的 JSON-RPC）与 Claude Desktop/Code、Cursor、Codex 测试过

关键特性：

🔧 80+ 专用工具：任务管理、文件系统、终端、浏览器自动化、AppleScript 集成
🎯 3 种使用模式：CLI、本地 MCP、云 MCP，以实现最大灵活性
🔗 通用兼容性：适用于 Claude Code、Cursor、Claude Desktop、VS Code 和任何 MCP 兼容客户端
☁️ 云就绪：部署到 GCP、Railway、Fly.io 并自动扩展
🚀 生产就绪：核心工具的全面测试套件覆盖
⚡ 高性能：平均响应时间 200-1000 毫秒，可靠性极佳
🛡️ 安全第一：文件系统护栏、权限系统和安全默认设置
📋 符合 MCP 2025-03-26：默认协议，带有工具标题、注释和适当的能力

ACF 如何解决上下文工程问题

ACF 将混乱的多文件、多步骤的软件工作现实转化为精确、可寻址的“上下文单元”，LLMs 可以请求、细化并采取行动。它通过结合任务图、丰富的上下文表面、检索/编辑工具和护栏来实现这一点——所有这些都可以通过 CLI 和 MCP 访问。

作为事实来源的任务图
- 每个任务/子任务都有一个 ID、状态、数字优先级（1-1000）、依赖关系、相关文件、活动日志、时间戳。
- 优先级引擎支持时间衰减和努力加权，以保持“下一步”的动态正确性。
丰富、按需的上下文表面
- getContext 返回确切的任务/子任务上下文块（包括相关文件元数据和活动日志）。
- generateTaskFiles 为每个任务生成一个 Markdown 文件（在 tasks/ 中），tasks-table.md 提供项目概览。
- CLI context <id> 打印人类总结，供人类和 LLM 使用。
检索和编辑工具（用于上下文构建和应用）
- 检索：search_code、tree、list_directory、get_file_info、read_file/read_multiple_files、read_url。
- 编辑：edit_block 使用明确的旧/新块进行手术替换（最小化意外漂移）。
- 执行：终端工具（execute_command、list_processes、会话）以验证上下文假设（测试、构建）。
同步与新鲜度
- 文件监视器同步 tasks.json 和每个任务文件；延迟变化检测；tasks-table.md 保持最新。
- 护栏：allowedDirectories 和 readonlyMode 限制可访问的文件系统范围。
从产品文档规划（可选）
- parsePrd、expandTask、reviseTasks 通过 Gemini 将 PRD 或变更请求转换为结构化任务，然后将其折叠回任务图中以进行可追溯执行。

这一起提供了可重复的“上下文循环”：计划 → 检索 → 编辑/验证 → 更新状态，每一步都可通过工具寻址，因此 MCP 客户端（Claude Code、Cursor、Codex、VS Code）可以可靠地驱动它。

端到端上下文配方

从 PRD 引导
- tools/call: parsePrd { filePath } → 创建具有优先级和依赖关系的任务 → generateTaskFiles 以供审查。
让模型专注于下一个动作
- tools/call: getNextTask → 获取考虑依赖关系/优先级的下一个可操作任务。
- tools/call: getContext { id } → 获取任务块；然后 read_file/search_code 查找周围代码。
安全、手术式代码更改
- 检索：search_code 以识别确切块；通过 read_file 验证。
- 应用：edit_block { file_path, old_string, new_string, normalize_whitespace }。
- 验证：execute_command { command: "npm test" } 或特定套件命令。
保持上下文新鲜
- start_file_watcher → 修改文件或任务 → file_watcher_status 获取统计信息 → 完成时 stop_file_watcher。

持久记忆（tasks.json 中的活动日志）

ACF 保存代理（或人类）做了什么、何时做的以及为什么做的持久、可查询的记忆。这种持久记忆存在于 .acf/tasks.json 和每个任务文件中：

存储的内容
- 对于每个任务和子任务：createdAt、updatedAt 和带有时间戳消息的 activityLog[] 条目。
- 每次更改任务（状态、标题、描述、优先级、依赖关系、相关文件）时都会追加日志条目并更新 updatedAt。
- AI 流程（parsePrd、expandTask、reviseTasks）也会写入清晰的活动消息。
LLM 如何写入记忆
- CLI：在更改状态时包含 --message "..." 以将人类/LLM 注释追加到活动日志中。
  - 示例：
    - acf status 12 inprogress --message "开始实现解析器"
    - acf update 12 --priority 750 --message "由于截止日期提高优先级"
- MCP：在 updateStatus 或 updateTask 的工具调用参数中传递 message。
  - tools/call { name: "updateStatus", arguments: { id: "12", newStatus: "done", message: "测试通过；合并"}`
  - tools/call { name: "updateTask", arguments: { id: "12", priority: 820, message: "经过利益相关者审查后升级"}`
如何消费记忆
- acf context <id>（CLI）打印一个丰富的、人类可读的上下文，包括最近的 activityLog。
- tools/call: getContext { id }（MCP）返回相同的结构化块，非常适合 LLM 提示。
- generateTaskFiles 生成 markdown 快照；tasks-table.md 显示从 .acf/tasks.json 同步的实时概述。

快速入门

要求
- Node.js 18+
- macOS（可选）用于 AppleScript 工具。如果使用浏览器工具，请安装 Playwright 浏览器：npx playwright install。
安装
- cd agentic-control-framework && npm ci
CLI（本地）
- ./bin/acf init --project-name "Demo" --project-description "开始使用"
- ./bin/acf add -t "第一个任务" -p high
- ./bin/acf list --format human
MCP 服务器（stdio）
- node ./bin/agentic-control-framework-mcp --workspaceRoot $(pwd)
- 使用 config/examples/ 中的示例客户端配置，适用于 Claude Code、Cursor 和 Codex。

文档

概述
- 主要文档索引：docs/README.md
- 项目结构：docs/PROJECT-STRUCTURE.md
- 架构概述：docs/architecture/overview.md
- MCP 集成细节：docs/architecture/mcp-integration.md
集成（MCP 客户端）
- 连接指南：docs/INTEGRATIONS.md
- 示例配置：
  - Claude Code（VS Code）：config/examples/claude_code.json
  - Cursor（项目/全局）：config/examples/cursor.mcp.json
  - Codex CLI（TOML）：config/examples/codex.config.toml
- Claude 辅助（开发笔记）：CLAUDE.md
参考
- CLI 完整示例：docs/reference/cli_examples.md
- MCP 请求/响应示例（自动生成）：docs/reference/mcp_examples.md
测试与验证
- 测试摘要和备注：docs/TESTING_SUMMARY.md
- 文档命令验证器：scripts/testing/validate-doc-commands.sh
建议与想法
- 工作区索引提案：docs/workspace-indexing-proposal.md

MCP 工具（已实现）

工具类别概述

mindmap
  root((ACF 工具<br/>总计 79 个))
    核心 ACF
      任务管理
        listTasks
        addTask
        updateStatus
        getNextTask
      优先级系统
        recalculatePriorities
        getPriorityStatistics
        bumpTaskPriority
        prioritizeTask
      文件监视
        initializeFileWatcher
        stopFileWatcher
        forceSyncTaskFiles
      模板
        getPriorityTemplates
        addTaskWithTemplate
    文件操作
      基本操作
        read_file
        write_file
        copy_file
        delete_file
      目录操作
        list_directory
        create_directory
        tree
        search_files
    终端
      命令执行
        execute_command
        read_output
        force_terminate
      进程管理
        list_processes
        kill_process
    浏览器自动化
      导航
        browser_navigate
        browser_navigate_back
        browser_close
      交互
        browser_click
        browser_type
        browser_hover
        browser_drag
      捕获
        browser_take_screenshot
        browser_pdf_save
        browser_snapshot
      标签管理
        browser_tab_list
        browser_tab_new
        browser_tab_close
    搜索与编辑
      search_code
      edit_block
    系统集成
      AppleScript
        applescript_execute
      配置
        get_config
        set_config_value

核心任务工具

initProject, addTask, addSubtask, listTasks, updateTask, updateStatus, removeTask, getNextTask
generateTaskFiles, recalculatePriorities, getPriorityStatistics, getDependencyAnalysis
getPriorityTemplates, calculatePriorityFromTemplate, suggestPriorityTemplate, addTaskWithTemplate

实用工具

read_file, write_file
execute_command（测试存根）

注意：工具通过 tools/list 从 src/mcp/server.js 发布，并且每个列出的工具在服务器中都有一个处理程序。

配置

核心环境变量
- WORKSPACE_ROOT：CLI/MCP 默认的工作空间路径
- ALLOWED_DIRS：额外允许的目录（路径分隔）
- READONLY_MODE：设置为 true 以禁用写操作
- ACF_PATH：覆盖项目的根路径
可选/功能标志
- GEMINI_API_KEY：启用 AI 支持的工具（parsePrd、expandTask、reviseTasks）
- ACF_SKIP_POSTINSTALL=1：跳过所有后安装步骤
- ACF_SKIP_PLAYWRIGHT=1：跳过沉重的 Playwright 浏览器下载
- ACF_INSTALL_SHARP=1 或 AC/ACF_INSTALL_ALL=1：安装可选的 sharp
- ACF_ENABLE_BROWSER_TOOLS=1：启用 Playwright 浏览器测试（macOS 默认）
- ACF_ENABLE_APPLESCRIPT=1：启用 AppleScript 测试（仅限 macOS）

安全与护栏

文件系统访问受 allowedDirectories 和 readonlyMode 限制。
URL 读取（read_url）是显式的；编辑使用 edit_block 与旧/新内容以尽量减少无意中的更改。
终端执行支持被阻止的命令和超时；会话可以列出/终止。

CLI 命令（高级）

init, add, list, add-subtask, status, next, update, remove, context
update-subtask, bump, defer, prioritize, deprioritize
recalculate-priorities, priority-stats, dependency-analysis
start-file-watcher, stop-file-watcher, file-watcher-status, force-sync
list-templates, suggest-template, calculate-priority, add-with-template

终端工具（6 个工具）✅

命令执行：
- execute_command: 运行带超时的 shell 命令
- read_output: 从运行进程读取
- force_terminate: 终止进程
- list_sessions: 显示活动终端会话
- list_processes: 显示运行进程
- kill_process: 终止进程

浏览器自动化工具（25 个工具）✅

导航：
- browser_navigate: 导航到 URL
- browser_navigate_back: 后退
- browser_navigate_forward: 前进
- browser_close: 关闭浏览器

交互：
- browser_click: 点击元素
- browser_type: 输入文本
- browser_hover: 悬停在元素上
- browser_drag: 拖放
- browser_select_option: 选择下拉选项
- browser_press_key: 键盘输入

捕获：
- browser_take_screenshot: 截屏
- browser_snapshot: 可访问性快照
- browser_pdf_save: 保存为 PDF

管理：
- browser_tab_list: 列出浏览器标签
- browser_tab_new: 打开新标签
- browser_tab_select: 切换标签
- browser_tab_close: 关闭标签
- browser_file_upload: 上传文件
- browser_wait: 等待时间/条件
- browser_resize: 调整窗口大小
- browser_handle_dialog: 处理警告/对话框
- browser_console_messages: 获取控制台日志
- browser_network_requests: 监控网络

搜索与编辑工具（2 个工具）✅

代码操作：
- search_code: 使用 ripgrep 进行高级文本/代码搜索
- edit_block: 手术式文本替换

AppleScript 工具（1 个工具）✅

macOS 自动化：
- applescript_execute: 运行 AppleScript 以进行系统集成

配置工具（2 个工具）✅

服务器管理：
- get_config: 获取服务器配置
- set_config_value: 更新配置值

项目结构

该存储库遵循标准实践，关注点分离干净：

agentic-control-framework/
├── 📁 bin/           # CLI 可执行文件和入口点
├── 📁 src/           # 核心源代码和工具实现
├── 📁 docs/          # 综合文档（按类别组织）
├── 📁 test/          # 测试基础设施和测试套件
├── 📁 config/        # 配置文件和示例
├── 📁 scripts/       # 设置、部署和维护脚本
├── 📁 deployment/    # 云部署配置
├── 📁 tasks/         # 任务管理文件
├──