Agentic Control Framework (ACF)

代理控制框架（ACF）

作者 Abhilash Chadhar（未来原子） 存储库： 代理控制框架


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-1000ms，可靠性极佳
• 🛡️ 安全第一：文件系统护栏、权限系统和安全默认值
• 📋 符合MCP 2025-03-26标准：具有工具标题、注释和适当功能的默认协议

ACF如何解决上下文工程

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

• 任务图作为真理的来源

- 每个任务/子任务都有一个ID、状态、数字优先级（1-1000）、依赖关系、相关文件、活动日志、时间戳。 - 优先级引擎支持时间衰减和努力加权，以保持“下一步是什么”的动态正确性。

• 丰富的按需上下文界面

- getContext 返回确切的任务/子任务上下文块（包括相关文件元数据和活动日志）。 - generateTaskFiles 每个任务具体化一个Markdown文件（tasks/），以及 tasks-table.md 给出了项目概述。 - 命令行界面 context 为人类和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的Bootstrap

- 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 "..." 当更改状态以将human/LLM注释附加到活动日志时。 - 示例： - acf status 12 inprogress --message "Started implementing parser" - acf update 12 --priority 750 --message "Raised priority due to deadline" - MCP：通过 message 在工具/调用参数中 updateStatus 或 updateTask. - tools/call { name: "updateStatus", arguments: { id: "12", newStatus: "done", message: "Tests green; merging" } } - tools/call { name: "updateTask", arguments: { id: "12", priority: 820, message: "Escalated after stakeholder review" } }

• 如何消耗内存

- acf context （CLI）打印丰富的、人类可读的上下文，包括最近的 activityLog. - tools/call: getContext { id } （MCP）返回相同的结构化块，非常适合LLM提示。 - generateTaskFiles 生成降价快照； tasks-table.md 显示从同步的实时概览 .acf/tasks.json 通过文件监视器。

快速开始

• 需求

- Node.js 18+ - macOS for AppleScript工具（可选）。Playwright浏览器（如果使用浏览器工具）： npx playwright install.

• 安装

- cd agentic-control-framework && npm ci

• CLI（本地）

- ./bin/acf init --project-name "Demo" --project-description "Getting started" - ./bin/acf add -t "First task" -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 - 配置示例： - 克劳德代码（VS代码）： config/examples/claude_code.json - 光标（项目/全局）： config/examples/cursor.mcp.json - 食品法典委员会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 Tools
79 Total))
    Core ACF
      Task Management
        listTasks
        addTask
        updateStatus
        getNextTask
      Priority System
        recalculatePriorities
        getPriorityStatistics
        bumpTaskPriority
        prioritizeTask
      File Watching
        initializeFileWatcher
        stopFileWatcher
        forceSyncTaskFiles
      Templates
        getPriorityTemplates
        addTaskWithTemplate
    File Operations
      Basic Operations
        read_file
        write_file
        copy_file
        delete_file
      Directory Ops
        list_directory
        create_directory
        tree
        search_files
    Terminal
      Command Execution
        execute_command
        read_output
        force_terminate
      Process Management
        list_processes
        kill_process
    Browser Automation
      Navigation
        browser_navigate
        browser_navigate_back
        browser_close
      Interaction
        browser_click
        browser_type
        browser_hover
        browser_drag
      Capture
        browser_take_screenshot
        browser_pdf_save
        browser_snapshot
      Tab Management
        browser_tab_list
        browser_tab_new
        browser_tab_close
    Search & Edit
      search_code
      edit_block
    System Integration
      AppleScript
        applescript_execute
      Configuration
        get_config
        set_config_value

核心任务工具

• initProject、addTask、addSubtask、listTasks、updateTask、updateStatus、removeTask、getNextTask
• 生成任务文件，重新计算优先级，获取优先级统计，获取依赖性分析
• getPriorityTemplates，calculatePriorityFromTemplate，suggestPriorityTemplate，addTaskWithTemplate

公用事业

• 读文件、写文件
• execute_command（测试存根）

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

配置

• 核心环境变量

- WORKSPACE_ROOT：CLI/MCP使用的默认工作区路径 - ALLOWED_DIRS：允许的其他目录（路径分隔） - READONLY_MODE：设置为 true 禁用写入操作 - ACF_PATH：容器的项目根覆盖

• 可选/功能标志

- GEMINI_API_KEY：启用人工智能支持的工具(parsePrd, expandTask, reviseTasks) - ACF_SKIP_POSTINSTALL=1：跳过所有安装后步骤 - ACF_SKIP_PLAYWRIGHT=1：跳过繁重的Playwright浏览器下载 - ACF_INSTALL_SHARP=1 或 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
• 更新子任务、取消、推迟、优先排序、取消优先级
• 重新计算优先级、优先级统计、依赖性分析
• 启动文件监视器、停止文件监视器、文件监视器状态、强制同步
• 列出模板、建议模板、计算优先级、添加模板

终端工具（6个工具）✅

Command Execution:
- execute_command: Run shell commands with timeout
- read_output: Read from running processes
- force_terminate: Kill processes
- list_sessions: Show active terminal sessions
- list_processes: Show running processes
- kill_process: Terminate processes

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

Navigation:
- browser_navigate: Navigate to URLs
- browser_navigate_back: Go back
- browser_navigate_forward: Go forward
- browser_close: Close browser

Interaction:
- browser_click: Click elements
- browser_type: Type text
- browser_hover: Hover over elements
- browser_drag: Drag and drop
- browser_select_option: Select dropdown options
- browser_press_key: Keyboard input

Capture:
- browser_take_screenshot: Screenshots
- browser_snapshot: Accessibility snapshots
- browser_pdf_save: Save as PDF

Management:
- browser_tab_list: List browser tabs
- browser_tab_new: Open new tabs
- browser_tab_select: Switch tabs
- browser_tab_close: Close tabs
- browser_file_upload: Upload files
- browser_wait: Wait for time/conditions
- browser_resize: Resize window
- browser_handle_dialog: Handle alerts/dialogs
- browser_console_messages: Get console logs
- browser_network_requests: Monitor network

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

Code Operations:
- search_code: Advanced text/code search with ripgrep
- edit_block: Surgical text replacements

AppleScript工具（1个工具）✅

macOS Automation:
- applescript_execute: Run AppleScript for system integration

配置工具（2个工具）✅

Server Management:
- get_config: Get server configuration
- set_config_value: Update configuration values

](https://mseep.ai/app/futureatoms-agentic-control-framework)

项目结构

该存储库按照标准实践进行组织，并明确分离关注点：

agentic-control-framework/
├── 📁 bin/           # CLI executables and entry points
├── 📁 src/           # Core source code and tool implementations
├── 📁 docs/          # Comprehensive documentation (organized by category)
├── 📁 test/          # Testing infrastructure and test suites
├── 📁 config/        # Configuration files and examples
├── 📁 scripts/       # Setup, deployment, and maintenance scripts
├── 📁 deployment/    # Cloud deployment configurations
├── 📁 tasks/         # Task management files
├── 📁 templates/     # Project templates
├── 📁 public/        # Static assets
└── 📁 data/          # Data directory

另请参见：docs/PROJECT-STRUCTURE.md

集成

在中使用现成的复制模板 config/examples/.

• 克劳德桌面： claude.json
• 克劳德代码（VS代码）： config/examples/claude_code.json
• 光标： config/examples/cursor.mcp.json
• 食品法典： config/examples/codex.config.toml

更多详细信息：docs/INTEGRATIONS.md

☁️ 云部署

• 部署指导 -完整的部署概述

测试

• MCP测试： npm test
• CLI测试： npm run test:cli
• 新闻报道： npm run coverage:all

环境标志

• ACF_SKIP_POSTINSTALL=1 跳过所有安装后步骤
• ACF_SKIP_PLAYWRIGHT=1 安装时跳过Playwright浏览器下载
• ACF_INSTALL_SHARP=1 （或 ACF_INSTALL_ALL=1)安装可选 sharp
• ACF_ENABLE_BROWSER_TOOLS=1 启用Playwright浏览器测试（默认情况下仅限macOS）
• ACF_ENABLE_APPLESCRIPT=1 启用AppleScript测试（仅限macOS）

平台门控（默认CI安全）

• 默认情况下，在Windows/Linux上跳过浏览器和AppleScript MCP测试。
• 要在macOS上本地运行它们，请设置相应的 ACF_ENABLE_* env变量。
• 谷歌云运行 -GCP部署
• 码头工人 -容器部署
• 远程设置 -远程客户端配置

🧪 测试与质量

• 云MCP测试 -最新综合测试
• 工具验证 -所有79个工具均已验证
• 安全性测试 -安全验证
• 测试框架 -测试基础设施

🏗️ 技术参考

• 系统架构 -带图表的完整架构
• 工具参考 -完整的工具文档
• 优先级系统 -高级任务优先级
• MCP集成 -协议实施细节
• 项目结构 -存储库组织
• 快速参考 -基本命令

📋 完整文档索引

• 主文档索引 -所有文件的完整目录
• 文档索引 -快速参考索引

📊 当前状态

*所有测试均已通过！看 ACF-TESTING-SUMMARY.md 查看详细的测试结果*

🧪 测试结果和质量保证

最新测试运行：100%通过率（所有测试均通过）

✅ 全面测试覆盖

• CLI工具测试: ✅ 通过-所有任务管理操作均正常工作
• 本地MCP工具测试: ✅ 通过-3/3项核心测试，成功率100%
• stdio MCP工具测试: ✅ 通过-25/25综合测试，成功率100%
• 专用工具测试: ✅ PASSED-文件系统、浏览器、AppleScript、搜索、编辑工具
• 集成测试: ✅ PASSED-MCP代理、客户端配置、SSE端点
• 端到端测试: ✅ 通过-系统健康检查，所有模块正在加载

📊 性能指标

• 平均响应时间：24毫秒
• 最大响应时间：439毫秒
• 无慢速响应：0个响应>1秒
• 没有大的响应：0个大于10KB的响应
• 质量评估：优秀（通过率100%）

🔧 已验证的功能

• 具有依赖关系的任务管理工作流
• 优先权制度和重新计算
• MCP协议合规性和通信
• 使用Playwright实现浏览器自动化
• AppleScript集成（macOS）
• 带有安全护栏的文件系统操作
• 搜索和编辑工具功能
• 客户端配置生成（游标、克劳德桌面、VS代码）

🧪 测试与验证

综合测试完成（2025年1月）

ACF经过了广泛的测试，以确保生产准备就绪：

工具验证✅

• 广泛的工具测试：通过MCP协议验证核心工具
• 100%成功率：所有工具在所有类别中都能正常工作
• 性能已验证：平均4ms响应时间，无缓慢响应

IDE集成测试✅

• 克劳德代码：通过15/15兼容性测试
• 光标IDE：配置和工具发现已验证
• 克劳德桌面版：测试了SSE传输和mcp代理集成
• VS Code：已验证Cline and Continue扩展配置

协议遵从✅

• MCP 2025-03-26：默认协议版本；向后兼容2024-11-05
• JSON-RPC 2.0：全面实施协议
• 错误处理：标准错误代码和优雅降级

📊 查看完整的测试报告

🚀 快速开始

📋 需要详细的设置说明吗？ 查看我们的综合 平台设置指南 适用于Windows、macOS和Ubuntu，并附有分步说明。

先决条件

# Install Node.js 22+ (LTS)
node --version

# Install dependencies
npm install

# Install global MCP dependencies (for IDE integration)
npm install -g mcp-proxy @modelcontextprotocol/inspector

# Install browser dependencies (for automation tools)
npx playwright install

# Make CLI tools executable (macOS/Linux)
chmod +x bin/*

⚙️ 配置设置

复制和自定义配置模板：

# Copy configuration templates
cp config/examples/config.json ./config.json
cp config/examples/claude-mcp-config.json ./claude-mcp-config.json

# Update paths in configuration files
export ACF_PATH="$(pwd)"
export WORKSPACE_ROOT="$(pwd)"

# Replace placeholders (Linux/macOS)
sed -i 's|${ACF_PATH}|'$ACF_PATH'|g' *.json
sed -i 's|${WORKSPACE_ROOT}|'$WORKSPACE_ROOT'|g' *.json

# Or set environment variables instead
echo 'export ACF_PATH="'$(pwd)'"' >> ~/.bashrc
echo 'export WORKSPACE_ROOT="'$(pwd)'"' >> ~/.bashrc

📋 需要配置帮助吗？ 看 config/README.md 有关详细的设置说明。

🚀 启动ACF服务器

选择您喜欢的模式：

选项1:CLI模式（直接命令）

# Initialize project
./bin/acf init --project-name "My Project" --project-description "Getting started with ACF"

# Start using CLI commands
./bin/acf add --title "First Task" --description "Test ACF functionality" --priority high
./bin/acf list

MCP服务器（用于IDE）

node ./bin/agentic-control-framework-mcp --workspaceRoot $(pwd)

选项3：云MCP模式（远程访问）

# Terminal 1: Start ACF MCP Server
node ./bin/agentic-control-framework-mcp --workspaceRoot $(pwd)

# Terminal 2: Start mcp-proxy for HTTP/SSE access
mcp-proxy --port 8080 node ./bin/agentic-control-framework-mcp --workspaceRoot $(pwd)

# Server available at http://localhost:8080

✅ 验证安装

# Test CLI functionality
./bin/acf --help

# Test MCP server (in separate terminal)
curl -X POST http://localhost:8080/stream -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","id":1,"method":"ping"}'  # If using mcp-proxy

# Run test suite
npm test

📋 使用模式

使用模式比较

graph LR
    subgraph "CLI Mode"
        CLI1[Direct Commands]
        CLI2[Automation Scripts]
        CLI3[CI/CD Integration]
    end

    subgraph "Local MCP Mode"
        MCP1[Claude Code]
        MCP2[Cursor IDE]
        MCP3[Claude Desktop]
        MCP4[VS Code]
    end

    subgraph "Remote MCP Mode"
        REM1[Web Clients]
        REM2[Distributed Teams]
        REM3[Cloud Deployment]
        REM4[Multi-Client Access]
    end

    CLI1 --> |Fast & Direct| ACF[ACF Core]
    CLI2 --> |Scriptable| ACF
    CLI3 --> |Automated| ACF

    MCP1 --> |Natural Language| ACF
    MCP2 --> |IDE Integration| ACF
    MCP3 --> |AI Assistant| ACF
    MCP4 --> |Extension| ACF

    REM1 --> |HTTP/SSE| PROXY[mcp-proxy]
    REM2 --> |Remote Access| PROXY
    REM3 --> |Scalable| PROXY
    REM4 --> |Concurrent| PROXY

    PROXY --> ACF

    ACF --> TOOLS[80+ Tools]

    style CLI1 fill:#e1f5fe
    style MCP1 fill:#f3e5f5
    style REM1 fill:#e8f5e8
    style ACF fill:#fff3e0
    style TOOLS fill:#fce4ec

1.🖥️ CLI模式（100%工作）

非常适合：自动化脚本、本地开发、CI/CD集成

基本任务管理

# Initialize project
cd your-project
./path/to/acf/bin/acf init -n "My Project" -d "Project description"

# Add tasks
./path/to/acf/bin/acf add -t "Implement feature" -d "Add new functionality" -p high

# List tasks
./path/to/acf/bin/acf list

# Update task status
./path/to/acf/bin/acf status 1 inprogress -m "Started working"

# Add subtasks
./path/to/acf/bin/acf add-subtask 1 -t "Write tests"

# Get next actionable task
./path/to/acf/bin/acf next

# Generate task files
./path/to/acf/bin/acf generate

高级CLI使用

# Update task details
./path/to/acf/bin/acf update 1 -p medium --related-files "src/main.js,test/main.test.js"

# Get task context
./path/to/acf/bin/acf get-context 1

# Remove completed tasks
./path/to/acf/bin/acf remove 1

# Generate markdown table
./path/to/acf/bin/acf list --table

🎯 数字优先级系统（1-1000）

ACF具有一个复杂的数字优先级系统，它以灵活的1-1000规模取代了传统的4级优先级，提供了细粒度的控制和智能的依赖关系管理。

优先级系统架构

graph TD
    subgraph "Priority Ranges"
        CRIT[🚨 Critical
900-1000
Security, Blockers]
        HIGH[🔴 High
700-899
Important Features]
        MED[🟡 Medium
400-699
Standard Work]
        LOW[🟢 Low
1-399
Documentation]
    end

    subgraph "Priority Engine"
        PE[Priority Engine]
        DA[Dependency Analysis]
        TA[Time Decay]
        EW[Effort Weighting]
        UT[Uniqueness Tracker]
    end

    subgraph "Algorithms"
        DB[Dependency Boosts]
        CP[Critical Path]
        DO[Distribution Optimization]
        AR[Auto Recalculation]
    end

    subgraph "Operations"
        BUMP[Bump Priority]
        DEFER[Defer Priority]
        PRIO[Prioritize]
        DEPRIO[Deprioritize]
        RECALC[Recalculate All]
    end

    PE --> DA
    PE --> TA
    PE --> EW
    PE --> UT

    DA --> DB
    DA --> CP
    PE --> DO
    PE --> AR

    BUMP --> PE
    DEFER --> PE
    PRIO --> PE
    DEPRIO --> PE
    RECALC --> PE

    PE --> CRIT
    PE --> HIGH
    PE --> MED
    PE --> LOW

    style CRIT fill:#ffebee
    style HIGH fill:#fff3e0
    style MED fill:#f9fbe7
    style LOW fill:#e8f5e8
    style PE fill:#e3f2fd

优先级范围

• 🟢 低（1-399）：文档、清理、功能齐全
• 🟡 中等（400-699）：标准开发工作，常规功能
• 🔴 高（700-899）：重要功能、重大错误、紧急任务
• 🚨 关键（900-1000）：安全修复、阻塞问题、生产紧急情况

基本优先级使用

# Using numerical priorities (1-1000)
./bin/acf add "Critical security fix" --priority 950
./bin/acf add "Feature implementation" --priority 650
./bin/acf add "Documentation update" --priority 200

# Using string priorities (backward compatible)
./bin/acf add "Bug fix" --priority high
./bin/acf add "Cleanup task" --priority low

优先级操纵命令

# Increase priority by amount
./bin/acf bump 123 --amount 100

# Decrease priority by amount
./bin/acf defer 123 --amount 50

# Set to high priority range (700-899)
./bin/acf prioritize 123

# Set to low priority range (1-399)
./bin/acf deprioritize 123

# View priority statistics and distribution
./bin/acf priority-stats

# Analyze dependencies and critical paths
./bin/acf dependency-analysis

# Trigger intelligent priority recalculation
./bin/acf recalculate-priorities

高级优先级功能

• 🔄 自动唯一性：每个任务都有一个唯一的优先级值
• 📈 依赖性增强：有依赖项的任务会自动获得优先级增加
• 🔗 关键路径分析：识别瓶颈任务并确定其优先级
• ⚡ 智能重新计算：根据依赖关系和时间优化优先级
• 📊 分配优化：防止优先级分组并保持有意义的差异

优先级显示格式

# Clean table format (default)
./bin/acf list --table
┌─────┬────────────────────┬──────────┐
│ ID  │ Title              │ Priority │
├─────┼────────────────────┼──────────┤
│ 24  │ Critical Bug Fix   │ 950      │
│ 25  │ Feature Request    │ 650      │
└─────┴────────────────────┴──────────┘

# Human-readable with distribution stats
./bin/acf list --human
📊 Priority Distribution:
🚨 Critical (900+): 2 | 🔴 High (700-899): 5 | 🟡 Medium (500-699): 8 | 🟢 Low (<500): 3

有关完整文档，请参阅：

• 优先级系统指南 -全面的文件
• 迁移指南 -从字符串优先级升级

自动化示例

# Daily standup automation
#!/bin/bash
echo "📊 Daily Standup Report"
echo "======================="
./bin/acf list --status inprogress
echo ""
echo "Next Priority Tasks:"
./bin/acf next

# CI/CD Integration
#!/bin/bash
# In your CI pipeline
./bin/acf add -t "Deploy v$VERSION" -d "Deploy to production" -p high
./bin/acf status $TASK_ID done -m "Deployed successfully"

2.🔗 本地MCP模式（100%工作）

非常适合：IDE集成（游标、克劳德桌面、克劳德代码）、本地开发

光标配置

选项1：通过光标设置UI（推荐）

1. 打开的游标→ 设置→ MCP
2. 添加新服务器：

- 名字: acf-local - 命令: node - 参数: ["/path/to/agentic-control-framework/bin/agentic-control-framework-mcp", "--workspaceRoot", "/path/to/your/project"] - 环境:

     {
       "WORKSPACE_ROOT": "/path/to/your/project",
       "ALLOWED_DIRS": "/path/to/your/project:/tmp",
       "READONLY_MODE": "false"
     }

选项2：通过settings.json

{
  "mcp.servers": {
    "acf-local": {
      "command": "node",
      "args": [
        "/path/to/agentic-control-framework/bin/agentic-control-framework-mcp",
        "--workspaceRoot",
        "/path/to/your/project"
      ],
      "env": {
        "WORKSPACE_ROOT": "/path/to/your/project",
        "ALLOWED_DIRS": "/path/to/your/project:/tmp",
        "READONLY_MODE": "false"
      }
    }
  }
}

Claude桌面配置

⚠️ 重要提示：仅使用直接可执行方法-这是唯一被确认可靠工作的方法

配置文件位置：

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• 视窗: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

配置（替换为实际路径）：

{
  "mcpServers": {
    "agentic-control-framework": {
      "command": "/FULL/PATH/TO/agentic-control-framework/bin/agentic-control-framework-mcp",
      "env": {
        "ACF_PATH": "/FULL/PATH/TO/agentic-control-framework",
        "WORKSPACE_ROOT": "/FULL/PATH/TO/YOUR/WORKSPACE",
        "ALLOWED_DIRS": "/FULL/PATH/TO/YOUR/WORKSPACE:/tmp",
        "READONLY_MODE": "false",
        "BROWSER_HEADLESS": "false",
        "DEFAULT_SHELL": "/bin/bash"
      }
    }
  }
}

⚠️ 关键要求：

• 使用 完全绝对路径 -没有相对路径或 ~
• 集 ACF_PATH 到ACF安装目录
• 集 WORKSPACE_ROOT 到您的项目工作区
• 确保 bin/agentic-control-framework-mcp 可执行： chmod +x bin/agentic-control-framework-mcp
• ❌ 不使用 这 node + args 模式-在Claude Desktop中失败

Claude代码配置

选项1：使用Claude MCP命令（推荐）

使用Claude的内置命令将ACF配置为MCP服务器：

# Navigate to your project directory
cd your-project-directory

# Add ACF as an MCP server
claude mcp add acf-server \
  -e ACF_PATH="/path/to/agentic-control-framework" \
  -e WORKSPACE_ROOT="$(pwd)" \
  -e READONLY_MODE="false" \
  -e BROWSER_HEADLESS="false" \
  -e DEFAULT_SHELL="/bin/bash" \
  -e NODE_ENV="production" \
  -- node /path/to/agentic-control-framework/bin/agentic-control-framework-mcp --workspaceRoot "$(pwd)"

# Start Claude with ACF tools available
claude

选项2：手动配置

添加到您的Claude Code MCP设置中：

{
  "mcpServers": {
    "agentic-control-framework": {
      "type": "stdio",
      "command": "node",
      "args": [
        "/path/to/agentic-control-framework/bin/agentic-control-framework-mcp",
        "--workspaceRoot",
        "/path/to/your/project"
      ],
      "env": {
        "ACF_PATH": "/path/to/agentic-control-framework",
        "WORKSPACE_ROOT": "/path/to/your/project",
        "READONLY_MODE": "false",
        "BROWSER_HEADLESS": "false",
        "DEFAULT_SHELL": "/bin/bash",
        "NODE_ENV": "production"
      }
    }
  }
}

选项3：项目范围设置

对于共享MCP配置的团队协作：

# Navigate to your project directory
cd /path/to/your/project

# Add ACF as project-scoped MCP server (shared with team)
claude mcp add acf-project -s project \
  -e ACF_PATH="/path/to/agentic-control-framework" \
  -e WORKSPACE_ROOT="$(pwd)" \
  -e READONLY_MODE="false" \
  -- node /path/to/agentic-control-framework/bin/agentic-control-framework-mcp --workspaceRoot "$(pwd)"

# This creates a .mcp.json file that can be committed to version control
# Team members can then use: claude

# Start Claude with shared ACF tools
claude

IDE中的使用示例

配置后，您可以与AI助手一起使用自然语言：

"Add a new high-priority task for implementing user authentication"

"Create a critical priority task (950) for fixing the security vulnerability"

"List all tasks that are currently in progress"

"Show me priority statistics and distribution of all tasks"

"Bump the priority of task #123 by 100 points"

"Analyze dependencies and show me the critical path"

"Read the contents of src/main.js and create a task for adding error handling"

"Execute the test suite and create a task if there are failures"

"Search for all TODO comments in the codebase and create tasks for them"

"Take a screenshot of the application login page"

"Write a new file called docs/api.md with API documentation"

"Recalculate all task priorities with dependency boosts enabled"

MCP模式下的可用工具

3.☁️ 云MCP模式（100%工作）

非常适合：远程访问、web客户端、多客户端支持

设置云部署

使用mcp代理进行本地开发

# Install mcp-proxy
npm install -g mcp-proxy

# Start ACF with mcp-proxy
export WORKSPACE_ROOT="/path/to/your/project"
export ALLOWED_DIRS="/path/to/your/project:/tmp"

mcp-proxy --port 8080 node bin/agentic-control-framework-mcp --workspaceRoot "$WORKSPACE_ROOT"

测试HTTP/SSE端点

# Test connectivity (should return error about session ID - this is expected)
curl -X POST http://localhost:8080/stream \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"ping"}'

# MCP initialization (requires proper session handling)
curl -X POST http://localhost:8080/stream \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}'

# List available tools
curl -X POST http://localhost:8080/stream \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'

# Call a tool
curl -X POST http://localhost:8080/stream \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"listTasks","arguments":{}}}'

云模式的光标配置

{
  "mcp.servers": {
    "acf-cloud": {
      "transport": "sse",
      "endpoint": "http://localhost:8080/sse"
    }
  }
}

部署到谷歌云平台

# Authenticate
gcloud auth login

# Create project
gcloud projects create acf-your-name-$(date +%s)
export GCP_PROJECT_ID="your-project-id"

# Deploy
./quick-deploy.sh gcp --proxy-only

📚 示例用例

1.自动化项目设置

# CLI approach
./bin/acf init -n "E-commerce App" -d "Build online store"
./bin/acf add -t "Setup project structure" -p high
./bin/acf add -t "Configure database" -p high
./bin/acf add -t "Implement user auth" -p medium
./bin/acf add -t "Add payment integration" -p medium
./bin/acf add -t "Deploy to production" -p low

2.代码审查自动化

// MCP approach - ask your AI assistant:
"Search the codebase for any TODO comments and create tasks for each one"
"Read all JavaScript files in src/ and create tasks for any functions missing error handling"
"Take a screenshot of the app and create a task for any UI issues you notice"

3.CI/CD集成

#!/bin/bash
# In your GitHub Actions workflow
- name: Update project tasks
  run: |
    ./bin/acf add -t "Test release v${{ github.event.release.tag_name }}" -p high
    ./bin/acf status $TASK_ID inprogress -m "Running tests for ${{ github.sha }}"
    
    # Run tests
    npm test
    
    if [ $? -eq 0 ]; then
      ./bin/acf status $TASK_ID done -m "Tests passed"
    else
      ./bin/acf status $TASK_ID error -m "Tests failed"
    fi

4.浏览器测试自动化

// Via MCP in your IDE
"Navigate to our staging site and take screenshots of the login, dashboard, and profile pages"
"Fill out the contact form with test data and take a screenshot of the success page"
"Test the mobile responsiveness by resizing to phone dimensions and taking screenshots"

🔧 开发与测试

运行测试

# Comprehensive test suite
node test-simple-tools.js

# Individual component tests
./test-all-tools-comprehensive.sh

开发设置

# Clone repository
git clone https://github.com/your-org/agentic-control-framework.git
cd agentic-control-framework

# Install dependencies
npm install

# Setup development environment
chmod +x bin/*
export WORKSPACE_ROOT="$(pwd)"
export ALLOWED_DIRS="$(pwd):/tmp"

# Test CLI mode
./bin/acf list

# Test MCP mode
node bin/agentic-control-framework-mcp

🐛 故障排除

CLI模式问题

# Check if tasks.json exists
ls -la tasks.json

# Verify permissions
chmod +x bin/acf

# Check Node.js version
node --version  # Should be 22+

MCP模式问题

# Check environment variables
echo $WORKSPACE_ROOT
echo $ALLOWED_DIRS

# Test MCP server directly
node bin/agentic-control-framework-mcp --help

# Check file permissions
ls -la bin/agentic-control-framework-mcp

云模式问题

# Check mcp-proxy installation
npm list -g mcp-proxy

# Test proxy connectivity
curl -X POST http://localhost:8080/stream -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","id":1,"method":"ping"}'

# Check proxy logs
mcp-proxy --port 8080 --debug node bin/agentic-control-framework-mcp --workspaceRoot $(pwd)

🤝 贡献

1. 分叉 仓库
2. 创建 特征分支： git checkout -b feature/amazing-feature
3. 测试 您的更改： node test-simple-tools.js
4. 提交 您的更改： git commit -m 'Add amazing feature'
5. 推 到分行： git push origin feature/amazing-feature
6. 打开 拉取请求

测试指南

• 所有新工具都必须具有CLI、MCP和云测试
• 保持或提高当前的测试覆盖率（68%+）
• 在README中添加新功能的示例

📄 许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

🙏 致谢

• MCP协议：用于标准化的AI工具通信
• 剧作家：用于浏览器自动化功能
• 指挥官.js：用于出色的CLI界面
• mcp代理：用于HTTP/SSE网桥功能

______________________________________________________________________

🚀 准备好构建你的自主代理了吗？选择您的模式并开始！

有关详细的测试结果和改进路线图，请参阅 ACF-TESTING-SUMMARY.md.