自动化工作区框架

该框架提供一个可配置的临时工作区根目录（默认 ./workspace_temp），用于集中存放任务相关的所有资料（文档、数据、图表、数据库、配置等），并由脚本自动创建所需子目录：

• documents：说明文档、表格、报告等；
• datasets：原始数据、结构化表格；
• artifacts：生成的模型、图表、压缩包；
• databases：SQLite/Access 等数据库文件；
• configs：MCP、API、Agent 配置；
• scripts：与任务相关的执行脚本；
• logs：运行日志；
• reports：最终的总结或中间报表；
• state：运行状态 JSON（默认 run-state.json）；
• cache：临时缓存。

可以通过 CLI 参数 --rootDir <path> 或配置文件覆盖默认根目录，脚本会在每次运行前自动创建缺失的目录结构。

快速开始（Python）

1. 复制并填写认证/配置：
   • cp automation_framework/config/claude.env.example automation_framework/config/claude.env
   • cp automation_framework/config/mcp/claude.mcp.example.json automation_framework/config/mcp/claude.mcp.json（可按需修改）
2. 安装依赖：脚本基于 Python 3.9+ 标准库，无需额外第三方依赖。
3. 运行（使用 python3）：

   python3 automation_framework/agent_runner.py \
     --providers claude-code,openai-gpt \
     --rootDir /tmp/any/workspace

   不传 --providers 时默认取 config/framework.config.json 中的 defaultProviders。

配置说明

• config/framework.config.json 定义：
  • defaultRoot：默认工作根（可通过 CLI 覆盖）。
  • directories：会在工作根下自动创建的子目录。
  • statusFile：状态 JSON 相对路径，运行成功/失败都会记录。
  • providers：支持 cli 与 api 两类执行器，已内置 claude-code、openai-gpt、deepseek 示例。
• CLI runner 支持 commandTemplate 与 envFile，脚本会把 {{rootDir}}、{{documents}}、{{mcpConfig}} 等占位符替换为实际路径。
• API runner 当前写入占位 JSON，可在 providers[xxx] 上再扩展真实 HTTP 调用逻辑。

Claude Code & MCP

• config/claude.env.example：填写 ANTHROPIC_API_KEY、CLAUDE_CLI_COOKIES_PATH 等变量，脚本运行时会自动加载。
• config/mcp/claude.mcp.example.json：内含 {{rootDir}} 占位符，执行前会被渲染成实际的 *.mcp.generated.json，可继续添加更多 filesystem/shell/HTTP/sql server。
• 详细步骤参考 docs/claude_setup.md。
• commandTemplate 示例：

  claude-code headless \
    --workspace {{rootDir}} \
    --input {{documents}} \
    --output {{artifacts}} \
    --mcp {{mcpConfig}} \
    --allow-all
  

  真实环境中可替换为你的 CLI 调用方式，并根据业务需要开启所有权限。

多 API 扩展

• agent_runner.py 已内置 OpenAI/DeepSeek 兼容的 API runner：会根据 userPrompt/systemPrompt 渲染请求体，并在缺少 Key 或 callApiWhenKeyPresent=false 时输出请求预览 JSON。
• 只有在配置了 callApiWhenKeyPresent: true 且提供了对应 envVar 时才会真实发起 HTTP POST（默认关闭，避免误调用）。
• 在 providers 中新增条目即可，例如：

  "my-gpt": {
    "type": "openai",
    "runner": "api",
    "endpoint": "https://api.openai.com/v1/chat/completions",
    "model": "gpt-4.1-mini",
    "envVar": "OPENAI_API_KEY",
    "systemPrompt": "You are my automation helper.",
    "userPrompt": "请分析 {{documents}} 并输出 JSON。",
    "callApiWhenKeyPresent": true
  }

• 生成的响应/预览/错误都会写入 reports/*.json，便于审计与后续流水线读取。

状态与后续流程

• 每次运行都会更新 state/run-state.json，结构示例：

  {
    "runs": [
      {
        "id": "claude-code-1710000000000",
        "provider": "claude-code",
        "status": "succeeded",
        "output": "/path/to/log.log",
        "workspace": "/tmp/workspace",
        "createdAt": "...",
        "finishedAt": "...",
        "details": "退出码 0"
      }
    ]
  }

• 脚本结束时会打印摘要并输出最后一次运行的 JSON，可直接作为“下一步流程”输入，例如再交给其他 Agent 或自动档案系统继续处理。
• 额外地，脚本会在 state/last-run.json 写入最近一次运行的完整快照，方便后续流程直接读取文件而无需解析整个状态列表。