Skip to content

Latest commit

 

History

History
245 lines (166 loc) · 18.1 KB

README.zh-CN.md

File metadata and controls

245 lines (166 loc) · 18.1 KB

Capstone Agent Framework

开发与发布版本遵循固定的多线版本控制台账。 共同研发运行时包含原生 Pi、skills 与受管理资源,验收范围和精确部署来源以台账为准。 dev 是默认开发集成主线,保存当前项目控制记录; 功能与文档 PR 面向 dev。main 保存已接受的发布基线与发布快照, demo 只接收经过发布验收的功能范围。详见分支生命周期。

用户可在 GitHub Issues 提交截图和简短说明, 未说明环境时默认 cloud-demo。AI 按Issue 处理规程 由用户命令发起处理;不启用定时或无人值守。

使用 CAPSTONE_DEMO_SOURCE_DIR=/path/to/clean-checkout make capstone-demo-local-rebuild 运行独立数据的本地 demo。App 端口为 15173,API 为 18767;原有 local-dev 端口仍为 5173 和 8767。 local-dev 对应 cloud-dev 的开发测试和发布验证;local-demo 跟随 cloud-demo, 用于线上复现、紧急修复和发布验证,仅在已登记的修复或发布候选验证时临时偏离。

已实现、已验证、已合并与已部署范围分别记录于多线版本控制台账。 demo 发布遵循独立的发布验收流程。

简体中文 | English | 打开在线 Demo

正式应用入口为 capstone-agent。旧 grid-agent 发行包与 CLI 已删除;可独立安装的 pandapower-application 拥有正式 pandapower 入口、worker 和报告。 v1.1.0 版本基线包含统一框架、原生执行、资源处理及国网 PPT 模板库。 范围、验证和兼容说明见发布说明。

连接智能体推理、领域能力、权威计算与可核查证据。

Capstone 是面向已登记业务系统与科学计算系统的领域中立智能体框架。应用选择 Domain Pack 和权威系统,智能体组合其中已发布的语义工具,权威系统负责模型事实与计算。框架将结果、证据和模型修订绑定到每次运行,再通过对话、报告和交互视图呈现。

首个正式应用是通过智能体对话开展电网静态分析。工作台连接 pandapower 与 PyPSA 模型,支持连续分析:提出问题、执行领域工具、检查回答,再在电气拓扑图上定位相关元件。

企业研究可通过已配置的生产数据 MCP 网关探索数据、查询已登记服务、保存有来源的报告, 并基于保留产物继续追问。凭据保留在受保护宿主,连接方式见运行手册。 左栏网关组件支持查看实例详情、明确切换、添加连接和后台异步连通检测。

设计遵循四个原则:

  • 以契约组合能力。 工具描述可复用的领域动作;选定的 Domain Pack 提供 schema、策略和指南。
  • 由权威系统产生事实。 登记系统访问模型、执行计算、产生结果数据集与证据;智能体组织分析并解释返回的事实。
  • Kernel 保持领域中立。 上下文、步骤、执行轨迹、工件和回放属于共享框架服务;领域语义保留在独立安装的包中。
  • 回答关联模型与证据。 已准入引用保留运行和修订来源,使 App 能联动回答、结果表、拓扑图和执行记录。

当前 Capstone 智能体对话工作台:左侧 IEEE-39 拓扑图,右侧包含潮流结果的智能体回答

上图来自在线 App 对已完成 IEEE-39 分析的回看,数值属于对应运行。

架构与执行机制

四层结构规定职责归属和依赖方向:

flowchart LR
    A[Application] --> P[Domain Pack]
    P --> K[Kernel]
    K --> R[Registered Authority]
Loading
层 负责什么
Application 选择配置、领域绑定与 Provider;拥有公开对话、API、CLI 和兼容输出
Domain Pack 拥有语义工具、契约、策略、指南、执行、领域状态、结果与证据准入,以及投影
Kernel 组合选定能力;管理受限上下文、步骤、轨迹、类型化提交、工件与回放
Registered Authority 拥有模型访问、修订、计算或来源事实、结果数据集与证据

职责图不要求调用或导入逐层经过每个相邻层。实际执行时,Application 进入 Kernel 生命周期,Kernel 调用注入的 Domain Pack 执行器,由执行器访问权威系统。结果返回时,Domain Pack 准入并投影权威结果,Kernel 提交类型化状态,Application 呈现回答和视图。Kernel 不导入权威系统的实现。

智能体看到的是白名单中的语义工具及其明确契约。原始 pandapower/PyPSA 对象、任意 Python、shell 命令和通用文件访问位于这一接口之外。数值结论通过登记权威系统的契约返回;结果和证据引用必须经过当前运行与所需模型修订的准入检查,模型写出的引用本身不能确立证据。模型目录等信息性回答不创建计算证据。

契约与生命周期见框架架构,首个应用的权威边界见 pandapower 能力组合架构。

领域包接入与组合

Domain Pack 通过公开 Kernel SPI,封装一个领域的工具目录、schema、策略、指南、执行器、权威适配器、状态和结果投影。Application Profile 选择具名绑定和工具前缀。各绑定拥有自己的领域状态和凭据范围;通用输出将框架 core 与 domains.<binding_id> 分开。

当前 PyPSA Application Profile 展示了实际组合方式:

绑定 Domain Pack 工具前缀 职责
source PyPSA 网络建模 pypsa_model_ 检查登记模型,派生模型修订
operations PyPSA 运行计算 pypsa_ops_ 执行调度、运行优化和交流潮流校验

应用显式授权运行计算绑定使用来自建模绑定的类型化模型引用。来源权威系统校验模型修订,交接收据持久化以支持回放,目标绑定准入引用后再执行。组合领域包不会自动共享原始 Network、凭据或可变状态。

仓库还提供 PyPSA 容量规划与行业耦合包。这些能力分别选择接入;当前托管的 PyPSA 对话绑定网络建模和运行计算。只读库存参考包则在电网领域之外验证同一 SPI。

新增领域时,登记权威系统契约,基于公开 SPI 实现独立安装的领域包,再在应用中选择绑定与所需引用授权。接入验证覆盖打包资源、契约、执行、结果与证据准入,以及真实权威系统下的回放。Domain Pack 接入指南 给出实现步骤与一致性检查。

从一句指令开始

打开在线 Demo,或在本地运行 App。首页直接进入智能体对话。在模型菜单中选择已登记的电网模型,也可以通过自然语言打开模型,然后围绕它提出分析请求。

例如,分析 IEEE-39 时可以连续发送:

有哪些 pandapower 的电网模型?
打开 ieee39 电网模型。
执行一次交流潮流,报告收敛状态和全网有功损耗。
基于刚才的结果,筛查负载率最高的三条线路。
查看这些线路的端点母线,以及支持回答的结果与证据。

在同一段对话中继续追问结果或细化分析。每条指令都绑定到一个模型上下文和运行。新建对话会创建独立的 Thread;保存其链接后,刷新页面仍能回到同一段对话。

Capstone 模式先由模型识别专业目标和通用目标:专业目标使用启用的 Domain Pack, 通用目标委托给隔离运行的原生 Pi 智能体。Pi(纯 Pi)模式先选择相关公共业务背景,再把任务交给同一个执行器。 Thread 空闲时可切换模式;会话历史、草稿和模型选择保留。 通用输出不创建权威系统结果或证据,实时新闻或天气仍需要实际可访问的信息源。 详见共享执行器设计。 真实模型的回答质量需单独验收,离线检查不能代替这一验收。

在包含目标控制能力的本地开发版本中,使用 /goal <目标> 让一个 Agent 在会话内持续推进; 使用 /mission <大致目标> 由控制层逐步组织任务与执行 Agent。无需先填完整任务表, 可继续在主会话补充方向。工具按任务配备,最终成果由用户验收。见使用说明。

在 CLI 中使用 /skills 查看可用技能及执行角色,使用 /skill:<name> <任务> 选择本轮技能, 使用 /context 包含或排除公共背景。当前模型背景提供身份、版本与历史,不提供完整模型表。 托管的 PowerSkills/PowerMCP 资源分别使用原生 Pi 与专业适配器。 安装方法见资源配置说明。

通用执行预置六项按需调查方法:目标探索、规划与跟踪、系统调试、完成核验、 数据调查及质量与可比性检查。技能加载和模型报告的应用阶段进入现有过程记录; 加载方法不表示验证通过。见技能设计。 Hosted App 提供只读技能目录。就绪技能缺省可用,由模型选择相关方法,无需用户先手动选择。

启用 PPT 模板库后,新 PPT 缺省使用国网模板。会话选择持续生效,单次覆盖不改变会话选择。 上传模板缺省仅用于当前会话,明确要求保存入库后才供库内复用。 保存的内容源包支持换模板重生成,PDF 从同一份 PPTX 派生。 使用与配置见模板库运行说明。

智能体对话是主要入口。Case 是独立模块;默认联合对话尚未装配 Case 执行服务。 已登记引导流程与验证样例保留在早期的 /old 入口。

可以分析什么

模型家族 当前对话提供的能力
pandapower 登记模型检查、母线与支路查询、拓扑、交流与直流潮流、网损、负载率、模型约束检查和 N−1 分析
PyPSA 登记模型检查与负荷派生、固定容量经济调度、机组启停、滚动储能调度、拥塞 OPF、登记故障集的安全调度,以及调度后的交流潮流校验

可用操作取决于选定模型和已发布的能力契约。完整拓扑不可用时,模型菜单会说明原因。准确的执行范围见 pandapower 能力矩阵、PyPSA 建模目录和 PyPSA 运行计算目录。

对话、结果与拓扑图联动

拓扑图呈现权威系统拥有的模型,并通过明确引用关联分析。App 接收受限的几何投影,与智能体读取的模型上下文分开;模型坐标保留登记的电气示意或地理结构。

智能体列出负载率最高的三条线路,左侧拓扑图突出对应线路及负载率图层

让智能体“列出负载率最高的三条线路”。回答呈现排名、端点母线、功率与损耗,对应电网图突出本次分析的线路及负载率。截图展示已完成的分析,名称和数值保留该次运行记录的模型修订。

例如,得到“负载率最高的三条线路”后,可以沿关联视图检查:

  1. 使用回答下方的电网图操作,回到该指令对应的模型视图。
  2. 展开结构化分析结果;结果行包含元件引用时,点击该元件即可在拓扑图中定位。
  3. 平移、缩放并查看元件。标注使用模型名称与 bus、line、trafo 前缀,PyPSA 的 Link 使用 link,图中名称与回答、结果表中的元件引用一致。
  4. 查看证据和执行步骤,追溯计算过程。历史指令视图保留对应模型上下文,选择结果时恢复与它匹配的视图。

数值图层只使用匹配模型修订和当前运行的已准入结果,缺失值保持中性。线路负载率色阶描述返回数值的分布;是否越限由约束评估判断。模型变更与历史结果通过修订和运行引用保持可区分。

结果、报告和证据可经 API 回看;浏览器读取私有存储中的受限投影。对话、结果表与拓扑图因此具备共同的模型身份和证据链。

在本地运行

需要 Python 3.12+、uv、Docker Compose、Node.js 22.19+ 和 npm。首次检出仓库时执行:

git clone https://github.com/uukuguy/capstone.git
cd capstone
make setup
make install-pi
make install-pypsa-models
cp deploy/local.env.example deploy/local.env

编辑 Git 忽略的 deploy/local.env,替换数据库、存储、操作员和 Provider 的示例凭据。运行时选择项应与共享宿主运行配置一致。Provider 凭据仅保留在后端配置中;普通智能体对话使用已配置的 LLM,可能产生 Provider 费用。具体配置见运行手册。

使用仓库统一入口启动 API、pandapower worker、PyPSA worker 和 App:

make capstone-local-rebuild

打开 http://127.0.0.1:5173/。本地 Compose 直接开放对话访问,无需浏览器令牌。重建入口检查依赖与服务就绪状态,确认 API 和两个 worker 使用同一镜像,并在需要时启动 Vite App。它复用本地已校验的 PyPSA 模型资产。修改 API、worker 或 App 源码后,再运行这一入口。

打开 http://127.0.0.1:5173/enterprise 进入企业工作台。该入口恢复所选会话,并使用共享的对话和成果阅读组件。

页头显示所选环境(local-dev、local-demo、cloud-dev 或 cloud-demo)、包版本与源码提交。* 表示本地源码含未提交修改。未配置的 App 显示 环境未配置,不会根据网址推断环境。

App 默认也监听局域网接口,同一网络中的手机可打开 http://<电脑局域网 IP>:5173/。设置 CAPSTONE_APP_HOST=127.0.0.1 可限制为本机访问。需要在前台查看 Vite 日志时,使用 make capstone-app-dev。

CLI 与兼容入口

无源码本地dev试用

临时dev试用包通过Docker Compose v2运行。包内只有部署文件,使用阿里云北京仓库的四类镜像;用户无需Git、Python、Node、源码工作区或Vite。先安装Docker/Compose v2并在启动环境设置DEEPSEEK_API_KEY,然后一条命令完成安装和启动:

curl -fsSL https://raw.githubusercontent.com/uukuguy/capstone/dev/deploy/dev-trial/install.sh | sh

不传参数安装最新已发布版本;将命令末尾sh改为sh -s -- b7e68dd可指定Git版本,参数错误或不唯一时列出可安装版本。Docker自动选择arm64/amd64。不同版本共享数据,停止当前服务前先检查兼容性和启动配置。

默认目录~/capstone,可用CAPSTONE_TRIAL_DIRECTORY覆盖。App入口http://127.0.0.1:19173/;端口冲突时,在~/capstone/.env修改CAPSTONE_APP_PORT。安装成功显示实际目录、地址、端口配置和运维命令。

包内.env默认DeepSeek/deepseek-flash,并提供注释掉的OpenAI示例。切换时同时更改Provider和模型;OpenAI使用OPENAI_API_KEY。启动LLM环境变量优先于文件默认值。sh ~/capstone/capstone.sh启动本地最新可用版本;versions查看版本、use <Git>切换,status、logs、stop管理同一实例,停止保留数据。保留部署目录及私有.capstone-trial/状态。已验证来源、分发入口与平台状态见试用运行说明和版本台账。

内网可使用Linux AMD64离线包,内含部署文件、四类镜像和模型资源。默认PROVIDER=openai,通过OPENAI_BASE_URL、OPENAI_MODEL和OPENAI_API_KEY配置内网兼容服务。本地试用自定义地址使用Pi的Chat Completions接口;官方OpenAI地址保留Responses接口。目标机器须先安装Docker及Compose v2。配置步骤和数据兼容限制见离线安装,实际验收以版本台账为准。

CLI 可用于自动化和定向检查。完成安装后,可执行不调用 Provider 的 pandapower 查询:

make doctor
make run QUESTION="IEEE-39节点系统中线路11连接哪两个母线?"

需要 LLM 编排时,先按运行手册配置 CLI 的 Provider,再执行:

make run-llm QUESTION="对 IEEE-39 执行交流潮流,并报告有功损耗。"

现有 pandapower 答案、报告和标准输出契约见 pandapower 应用说明。正式支持的 capstone-agent CLI 和引导案例命令见运行手册。旧 grid-agent CLI 已删除;应用代码与测试归属 pandapower-application;退役计划记录最终验收。确定性脚本样例用于离线验证,与普通 LLM 对话分开。

开发与部署

本地 Compose 加 Vite 用于日常迭代,cloud-dev 用于远端集成验证,demo 提供已验证的用户试用版本。cloud-dev 与 demo 分别使用自己的数据库、工件存储、凭据和公开域名。demo 晋级使用在 cloud-dev 验收过的同一源码版本或工件。

App 定向检查使用 make test-capstone-app 和 make build-capstone-app。仓库离线门禁为:

make doctor
make test
make test-e2e
make validate

Provider 验证是需要单独授权的检查。部署步骤和运行配置集中在操作文档中: