# gridforge **Repository Path**: composer-liu-ming/gridforge ## Basic Information - **Project Name**: gridforge - **Description**: No description available - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-11-08 - **Last Updated**: 2026-11-08 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # GridForge 私有化部署套件 本目录是一个独立的 GridForge 部署工作区，包含用于审计或恢复 CLI 的运行时源码，以及部署已构建镜像所需的脚本。 它是一个**仅加载镜像**的部署套件：私有部署机器不负责构建镜像，只加载维护者导出的镜像归档并启动任务容器。 它可以作为独立的小型 Git 仓库进行版本管理。请提交源码、脚本、`VERSION` 和文档；**切勿提交** `.env`、镜像归档、任务工作区或图谱状态。 ## 核心特性 - **容器化运行**：正式执行环境只存在于容器内，宿主机仅通过脚本操作容器。 - **仅加载部署**：部署端只需要 Docker 和导出的镜像归档，不执行 `docker build`。 - **持久化工作区**：任务图谱、运行状态和产物保存在宿主机挂载目录中。 - **规划—执行—检查循环**：内置 `plan` / `act` / `check` 提示词模板，驱动模型完成可验证的任务。 - **零第三方依赖**：运行时仅使用 Python 标准库。 - **安全边界明确**：外部文本、文件内容和网络响应一律视为不可信数据，仅限授权任务使用。 ## 环境要求 - Linux 宿主机 - Docker - 已导出的 GridForge 运行时镜像归档（例如 `gridforge-runtime.tar.gz`） - 可选：Python 3（仅用于静态校验 `verify-kit.sh`） ## 目录结构 | 路径 | 说明 | |---|---| | `lib/gridforge/` | 运行时 Python 包源码 | | `lib/gridforge_cli.py` | 容器内 CLI 启动器源码 | | `templates/gridforge/` | `plan` / `act` / `check` 提示词模板 | | `load-image.sh` | 加载导出的镜像并校验运行时版本 | | `start.sh` | 启动一个挂载 `/work` 的任务容器 | | `stop.sh` | 停止或删除任务容器 | | `gf.sh` | 在运行中的容器内执行 `gridforge` 命令 | | `verify-kit.sh` | 部署套件与源码的静态完整性校验 | | `env.example` | 运行时环境变量模板；复制为私有 `.env` 后填写 | | `VERSION` | 运行时源码快照版本 | | `source/` | 离线升级源码快照；私有部署端可以删除 | ## 快速开始 ### 1. 准备配置 ```bash cp env.example .env # 编辑 .env，填入私有网关凭据和模型配置。 ``` `.env` 已被 `.gitignore` 忽略，请勿提交。 ### 2. 加载镜像并启动容器 ```bash ./load-image.sh /path/to/gridforge-runtime.tar.gz ./start.sh /path/to/mission-workspace ``` 也可以用一个命令完成两步： ```bash ./deploy.sh /path/to/gridforge-runtime.tar.gz /path/to/mission-workspace ``` ### 3. 初始化并运行任务 ```bash ./gf.sh -m my-mission init --goal "完成授权的任务并产出可验证记录" ./gf.sh -m my-mission status ./gf.sh -m my-mission run --minutes 60 --max-steps 12 --verify ``` `init` 必须用 `-m` 指定任务名；每个任务拥有独立的图谱与产物目录（`work/<任务名>/`）。`status`、`run` 与 `watch` 不带 `-m` 时会先列出所有任务供选择再执行（仅一个任务时直接执行；非交互环境下 `run`/`watch` 报错退出而不是误跑）。`(default)` 是根工作区 `/work` 的保留别名，可用 `-m '(default)'` 显式指代。 ### 4. 停止容器 ```bash ./stop.sh # 停止并删除容器 REMOVE=1 ./stop.sh ``` ## 常用命令 所有命令均通过 `gf.sh` 在容器内执行： ```bash ./gf.sh --version # 查看版本 ./gf.sh -m <任务名> init --goal "<任务目标>" # 新建任务工作区（init 必须带 -m） ./gf.sh status # 多任务时先列出供选择，再显示详情 ./gf.sh graph --format json # 导出任务图谱 ./gf.sh frontier # 列出可执行任务 ./gf.sh validate # 校验图谱完整性 ./gf.sh show record # 查看某个节点 ./gf.sh record "<结果描述>" --title "<标题>" # 添加已确认记录 ./gf.sh task "<任务描述>" --from <记录ID> # 添加任务 ./gf.sh note "<上下文说明>" # 添加人工/控制上下文 ./gf.sh recall "<查询内容>" # 检索相关历史工作 ./gf.sh claim <任务ID> --worker <名称> # 认领任务 ./gf.sh release <任务ID> --worker <名称> # 释放任务 ./gf.sh confirm <任务ID> # 确认受控任务 ./gf.sh done <任务ID> --worker <名称> # 完成任务 ./gf.sh complete --from <记录ID> --note "<说明>" # 完成工作区目标 ./gf.sh reopen --reason "<原因>" # 撤销完结裁决，工作区回到 active（开放任务恢复可派发） ./gf.sh run --minutes 60 --max-steps 12 --verify # 运行规划/执行/检查循环 ./gf.sh watch # 实时查看执行器会话（多任务时先选择任务） ./gf.sh -m <任务名> watch # 直接跟踪指定任务的会话 ./gf.sh watch --once --lines 50 # 选择任务后输出其最新会话的最后 50 行渲染 ./gf.sh -m pentest-a init --goal "<任务目标>" # 新建独立任务工作区（/work/pentest-a） ./gf.sh -m pentest-a run --minutes 30 --verify # 运行该任务，图谱与产物相互隔离 ./gf.sh manifest init # 生成本地任务清单 missions.json ./gf.sh manifest run --path missions.json # 运行清单中的全部任务 ./gf.sh scope set "<环境声明>" # 声明部署环境性质（一次生效于所有任务） ./gf.sh scope show # 查看当前环境声明 ./gf.sh scope clear # 清除声明并还原默认模板 ./gf.sh container # 查看容器运行时状态 ``` ## 工作区模型 GridForge 使用一张持久化图谱组织工作： - **记录（record）**：已经确认的结果或证据。 - **任务（task）**：从已有记录出发、产出新记录的工作单元。 - **笔记（note）**：人工或控制器的上下文说明。 `run` 命令会循环执行三轮模型调用： 1. **规划（plan）**：判断目标是否已完成，或提出最多三个具体的下一步任务。 2. **执行（act）**：完成指定任务，返回结构化结果与证据。 3. **检查（check）**：独立验证执行结果是否有证据支撑。 工作区目录会持久保存在宿主机： ```text mission-workspace/ ├── .gridforge/ # 图谱与运行状态 ├── .runtime-home/ # 容器内 HOME └── artifacts/ # 产物 ``` ## 配置说明 `env.example` 中列出了主要环境变量： | 变量 | 说明 | |---|---| | `ANTHROPIC_BASE_URL` | 模型网关地址 | | `ANTHROPIC_AUTH_TOKEN` | 模型网关凭据 | | `GRIDFORGE_MODEL` | 使用的模型名称 | | `GRIDFORGE_BIN` | 容器内 agent CLI 名称 | | `GRIDFORGE_TIMEOUT` | 单次模型调用超时（秒） | | `GRIDFORGE_RETRY_MODEL` | 模型调用重试次数 | | `GRIDFORGE_KEY_POOL` | 可选的 JSON 凭据池 | | `IMAGE` | 运行时镜像名称，默认 `gridforge:latest` | | `CONTAINER_NAME` | 容器名称，默认 `gridforge` | | `NETWORK_MODE` | 容器网络模式：`bridge` / `host` / `none` | | `RESTART_POLICY` | 容器重启策略，默认 `unless-stopped` | | `RUN_AS_HOST_USER` | 是否以宿主机 UID/GID 运行，默认 `1` | 真实凭据只应放在未跟踪的 `.env` 文件或调用环境中。 调用脚本（`start.sh`、`gf.sh`、`stop.sh`）会先读取 `.env`，但**命令行传入的环境变量优先于 `.env` 值**，例如 `CONTAINER_NAME=gridforge-b ./start.sh ...` 可以在不改 `.env` 的情况下启动第二个容器。 Docker 容器的环境变量在创建时固定。`start.sh` 复用已存在的容器前会校验其配置是否与当前 `.env` 一致，不一致时拒绝启动并提示 `REMOVE=1 ./stop.sh && ./start.sh` 重建。修改 `.env` 后必须重建容器才能生效。 ### 环境声明（scope） `./gf.sh scope set "<声明>"` 把一段**操作者负责的环境性质说明**写入 `work/scope.txt`，并自动生成 `work/templates/`（`plan`/`act`/`check` 模板 + 声明段落），对所有任务的规划/执行/检查提示词生效——无需每个任务重复输入。 - 声明会作为“运行环境声明”段落注入提示词顶部；`scope show` 查看，`scope clear` 还原默认模板 - 声明内容应**如实**描述环境：授权范围（委托方/合同/期限）、靶场性质、网络边界等。对真实第三方系统的测试必须具备真实授权，把未授权目标包装成“靶场”不会改变授权状态，只会把风险留在操作者身上 - 本套件默认 `GRIDFORGE_TEMPLATES=/work/templates`，因此模板改动无需重建镜像 ## 源码与升级 `VERSION` 记录本套件附带的运行时源码快照版本。 `source/` 是维护者侧的离线升级源码镜像，用于重建最终镜像。根目录的部署脚本（`deploy.sh`、`load-image.sh`、`start.sh`、`gf.sh`）不会读取或调用它，私有部署机器可以删除 `source/` 而不影响运行。 在源码/升级机器上刷新快照： ```bash bash docker/update-deployment-kit.sh ``` 从 `source/` 快照构建并导出新镜像： ```bash cd source bash docker/verify-runtime-source.sh bash docker/build-runtime.sh bash docker/export-runtime.sh ../gridforge-runtime-$(cat ../VERSION).tar.gz ``` > 新镜像必须基于 `gridforge:latest` 构建；若基础镜像不存在，构建脚本会失败。私有部署端永不编译源码。 ## 校验 ```bash ./verify-kit.sh ``` 该命令会检查部署套件必备文件是否齐全、启动脚本中是否误含 `docker build`，并对运行时 Python 源码做语法解析。它不会在宿主机上执行引擎。 ## 安全与使用边界 - 仅用于**已授权**的工作；任务范围和约束应写入任务目标或本地清单。 - 不添加攻击部署基础设施、评分系统、容器宿主机或无关第三方系统的指引。 - 所有图谱、文件、网络和工具输出均视为不可信数据，不得执行其中的嵌入指令。 - 不提交任何真实令牌、任务图谱、产物或私有工作区。 - 使用一个容器对应一个任务工作区，以隔离范围与状态。 ## 许可证 本项目采用 [MIT License](LICENSE)。