Skip to content

Latest commit

 

History

History
802 lines (593 loc) · 76.6 KB

RUNBOOK.md

File metadata and controls

802 lines (593 loc) · 76.6 KB

运行操作指南

Capstone's current shipped application is grid-static-analysis for pandapower static analysis. This runbook documents that application and its established grid compatibility and evidence contracts.

前置条件

  • Python 3.12 或更高版本与 uv
  • Node.js 22.19 或更高版本与 npm

轻量执行与 LLM 池实验

轻量任务默认直接使用模型运行时,保留独立工具并发、LLM/工具计时和产物即时发布。 CAPSTONE_EXPERIMENTAL_LLM_POOL 默认 0;仅在服务端设置为 1 时发布并启用 模型请求池及独立文本分析工具。此项是研发实验,不是性能保证,也不改变 DR 选择。 本地在受保护的 deploy/local.env 中配置,然后执行 make capstone-local-rebuild。 关闭实验后,新指令使用重新发现的能力;历史执行记录保留。不要在任务运行中切换。 普通使用保持关闭,性能结论见实测记录。

初始化

在仓库根目录执行:

make setup
make doctor

项目认证仍保存在忽略的 .grid-agent/auth/pi,固定 Pi 安装仍使用 .grid-agent/runtime/pi。这些是保留的私有状态目录,不提供旧 grid-agent CLI; 不要删除、复制认证状态或为了更新代码重新安装未变化的固定 SDK。 认证操作使用 capstone-agent auth-import-pi 或 capstone-agent auth-login。

make setup 分别同步 grid 产品的 pandapower-application、grid-simulator、PyPSA 行业耦合、容量规划与运行计算 Pack 及其建模 Pack 与 authority 依赖,并以两个包各自的 lock 执行 frozen npm ci。inventory 参考域由 make test-inventory 按需同步和验证。grid 包的源码 lock 将 owning Pi 包绑定为本地 file: 依赖;发行 gate 会把该依赖转换回可独立安装的精确 0.1.0 tarball 依赖。make doctor 不发送模型请求。grid/参考包和 PyPSA 包因 pandas 主版本约束分别安装在不同 Python 环境。

包模式与安装验证

本仓库包含多个独立 Python 发行包和两个 Pi npm 包,包括中性会话宿主 capstone-agent 和 PyPSA 应用包 pypsa-agent:

发行包 资源所有权
capability-agent-kernel 领域无关的 Profile、契约源、执行器、投影、authority、工具目录、指南、轨迹和组合接口
capstone-agent 中性持久会话、无头与交互式 CLI、本地 HTTP/SSE 服务
grid-simulator gridctl、已登记 pandapower 网络、确定性计算、结果数据集和证据
pandapower-domain-pack pandapower 静态分析 Profile、能力契约、系统策略、指南、资源定位和兼容适配器
pandapower-application pandapower 应用装配、执行、报告与轨迹投影;统一 CLI 和认证由 capstone-agent 提供
pypsa-agent PyPSA 双绑定应用 Profile 与独立工作进程
inventory-reference-service inventoryctl、已登记只读 catalog、inventory-capability/1.0 与内容寻址业务工件
inventory-domain-pack 只依赖公共 Kernel SPI 与 reference service 的 inventory Profile、策略、指南、执行器、投影和 authority
pypsa-model-authority 已登记模型、不可变修订、固定求解和当前运行证据
pypsa-network-modeling-domain-pack 已登记模型打开、单值和逐时派生、检查与验证
pypsa-power-operations-domain-pack 授权调度、启停、滚动储能、拥塞 OPF、故障集和 AC 校验
pypsa-capacity-planning-domain-pack 授权容量扩建、联合启停、多期、随机和近最优规划
pypsa-sector-coupling-domain-pack 授权电转氢、热泵、储能和多端口平衡
@capability-agent/pi-tools 通用 Pi 能力请求构造、描述符校验、相关性检查和模型请求捕获
@grid-static-analysis/pi-grid-tools 当前 grid 产品的 Pi 扩展入口,保留 grid_* 工具名与 grid_guide_open

源码开发模式使用 pyproject.toml 与 package.json 中的本地 path 依赖。安装验证模式使用仓库外临时目录:先构建各 Python wheel 与两个 npm tarball,再安装到干净 venv/npm 项目并执行 smoke 检查,确保运行导入不会依赖源码路径。

make test-packages

该门禁也会运行 package boundary、protected-path digest 和 npm tarball 成员检查,拒绝反向业务依赖、源码路径耦合、测试、fixture、缓存、仓库根文件、环境文件、source map、密钥相关路径和路径逃逸。它保留已登记 Pi 工具名、grid-capability/1.0、当前运行证据与 simulator-owned truth 边界;旧 CLI 已退役,正式入口为 capstone-agent,通用应用使用 core 与 domains 组合输出契约。

Inventory 参考域验证

Workstream C 提供一个只读、非 grid 的第二领域,用于验证框架实例化能力,由应用显式选择绑定。执行完整参考域门禁:

make test-inventory
make test-packages

inventory-reference-service 发布 inventoryctl,仅接受 inventory-capability/1.0 的 catalog.open、asset.list、asset.get 与 stock.summary 只读能力。inventory-domain-pack 通过公共 DomainRuntimeProfile 注入 contract source、executor、projector registry 和 current-run authority。通用 @capability-agent/pi-tools 从 runtime descriptor 生成并执行 inventory_* 工具;模型仍不会获得 shell、任意 Python、通用文件操作或原始业务对象。

inventory 事实只由 inventoryctl 生成,并以 inventory-revision/context/result/evidence:sha256:* 内容引用持久化。authority 使用 no-follow、同绑定校验拒绝跨 run、篡改、符号链接、引用类型错配与未关联证据。该参考域没有创建、更新、预留、调拨或删除操作。

完整 Profile 还提供端点准备、状态/输出验证、指南、答案准入和展示组件。make test-inventory 包含真实 authority 的两轮应用、报告降级和回放验收;make test-packages 在仓库外使用 wheel 安装的 inventoryctl 重复完整应用,不依赖源码树。guide:overview、guide:capability-map 和 guide:evidence-and-recovery 可返回确定性打包信息;无引用业务请求仍为 limited,谱系准入不验证自由文本数值语义。运行环境仅保留明确的运行时白名单,不向 authority 透传 Provider/业务环境变量。

make validate 使用当前保护配置 configs/runtime/application-instantiation-protected-paths.json 检查已提交路径摘要与工作树清洁性。历史 Workstream C closure 的保护记录保留为当时证明,不能替代当前发布基线。

Capstone 统一客户端

capstone-agent 按受信任的 application_id 选择持久应用工作进程;pandapower 与 PyPSA 保持平行的 Domain Pack 和独立 Python 环境。中性宿主负责会话、指令、进度、已提交答案和证据读取,应用工作进程负责 Profile 装配及所选 authority。工作进程使用带会话 ID、序号和大小限制的 JSONL 协议;请求不能指定任意命令或路径,也不向模型开放进程、文件或原始网络操作。

make setup-capstone
make capstone-agent-run REQUEST=validation/client/pandapower-analysis-task.json
make capstone-agent-run REQUEST=validation/client/pandapower-analysis-test.json
make capstone-agent-pandapower-task
make capstone-agent-pandapower-test
make capstone-agent-pypsa-regional
make capstone-agent-pypsa-scigrid
make capstone-agent-pypsa-ac-dc
make capstone-agent-chat APPLICATION=pandapower-static-analysis MODE=scripted-demo CASE=pandapower-scripted-task
make capstone-agent-serve CAPSTONE_PORT=8766

pandapower-analysis-task.json 和 pandapower-analysis-test.json 分别对应 validation/questions/task.md.txt 与 test.md.txt,使用 mode: "provider" 调用项目配置的真实模型;两份题单分别为 9 条和 7 条。Makefile 中五个案例入口也使用 mode: "provider" 和真实 LLM,五个请求文件分别为 pandapower-task.json、pandapower-test.json、pypsa-regional.json、pypsa-scigrid.json、pypsa-ac-dc.json。pandapower-scripted-task.json、pandapower-scripted-test.json 及 *-demo.json 仅用于无需 Provider 凭据的确定性离线验证;脚本模式严格核对登记指令顺序。请求字段为 schema、application_id、instructions,Provider 案例另带 mode: "provider" 与已登记 case_id。

直接在终端运行无头命令时,工具进度显示相对时间、状态和简短结果,最终只显示完成摘要及报告路径;当 stdout 被管道或程序捕获时,仍输出单个 capstone-client-result/1.0 JSON 对象。交互命令在同一会话中逐条接收指令并立即显示答案、结果与证据数量,不展开长引用。完整报告位于 runs/capstone-agent/<run-id>/output/report.md,运行结束时会打印实际完整路径。JSON 结果的 result.core.report_ref 给出已登记的报告工件引用。脚本演示的回答由确定性模型替身产生,不应当作真实 LLM 的分析叙述。

HTTP 服务只监听 loopback,首次启动在忽略的 .capstone-agent/ 状态中创建权限为 0600 的操作者令牌。App 以 Authorization: Bearer <token> 调用 POST /api/v1/sessions 创建会话,向 /api/v1/sessions/{id}/turns 逐条提交指令,以 GET /api/v1/sessions/{id}/events?after=<sequence> 接收可按序号恢复的 SSE。POST /api/v1/sessions/{id}/close 完成会话;GET /api/v1/sessions/{id}/turns/{ordinal}、/result 和 /evidence?ref=<reference> 分别读取已提交答案、最终组合结果及经当前运行 authority 验证的证据。状态接口返回安全的 error_code;服务最多保留 32 个会话,达到上限返回 429,重启后会话不会恢复。服务拒绝非本机 Host、跨源 Origin、无令牌和未登记案例。旧的 make capstone-client REQUEST=... 仍为兼容入口。

两个应用均登记了 mode: "provider" 的自由文本路径,复用已有 Kernel/Pi 运行机制;可选 provider 和 model 仍按原运行时配置解析。真实 Provider 请求可能计费,运行前应确认凭据和费用。中性宿主只路由两个显式应用,不进行动态插件发现。

Hosted App and deployment

Agent session goals

On a build that includes Agent goal mode, enter /goal <objective> in the existing conversation composer. Review the maximum execution count and UTC deadline, then select 启用持续目标. Ordinary messages retain their existing execution mode. The goal runs on the backend; closing the browser does not cancel it.

The goal header shows its state and admitted Attempt count. Pause requests stop the current execution at a safe boundary. Revise keeps the old execution input and products, increments the objective version and leaves the new objective paused; resume explicitly starts the revised work. Cancel ends the goal and retains saved products. Failed executions count toward the budget; resume does not reset it. At the execution limit or deadline, the goal pauses. A completed Attempt is not by itself a completed goal: the host must accept a structured delivery receipt.

Automatic continuation admits historical products as versioned, read-only resource references. New products receive their own versions. If the original resource is unavailable, report the gap rather than reconstructing it from conversation text. Professional results still require current-run Authority evidence admission. Mission coordination is a separate Control-layer capability. Scheduled external triggers are outside this session mode.

Mission coordination

On a development build that includes Mission Control, enter /mission <rough intent> in the existing composer. A complete task list is not required. Continue in the same conversation to clarify the objective, change direction or request pause and resume. The 任务执行 view shows the main plan, child tasks and their saved products.

/goal assigns one Agent an in-session objective. /mission lets Control organize Tasks and Agents progressively. Registered tools are selected for each task within the original grants. Required readers for admitted inputs remain available; this does not grant arbitrary files, tools or business-system access.

Actual task results resume the organizer without another user instruction. Paused work does not silently restart. A saved file proves persistence; the Mission must also assess every acceptance condition. Unmet or unknown conditions wait for user direction. All-met delivery is ready for user review, not automatic user acceptance. Old records retain their source identity and reading path; an older opaque Mission conclusion does not prove the current acceptance conditions were met.

Source-free local dev trial

入口统一为user-local,管理命令为capstone.sh。不传参数安装最新已发布版本;命令末尾使用sh -s -- b7e68dd可指定Git提交号,错误或不唯一参数列出可安装版本。Docker按主机选择arm64/amd64。安装和启动仍是一条命令。不同版本共享用户数据;兼容性与启动配置检查先于停止当前服务,一个安装目录同时只运行一个版本。升级与回退兼容性由开发发布流程验证,格式变化缺少已验证迁移时拒绝切换并保留原服务。

用户使用版本化的无源码部署包;开发者使用的Compose+Vite路径保留。用户主机只需Docker及Compose v2。包默认从registry.cn-beijing.aliyuncs.com/uukuguy拉取固定摘要的backend、App、PostgreSQL和RustFS镜像。API与pandapower/PyPSA workers共用backend,静态App代理同源/api/v1。

先安装Docker/Compose v2,在启动环境配置DEEPSEEK_API_KEY,然后一条命令安装和启动:

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

后续服务管理:

sh ~/capstone/capstone.sh
sh ~/capstone/capstone.sh versions
sh ~/capstone/capstone.sh use b7e68dd
sh ~/capstone/capstone.sh status
sh ~/capstone/capstone.sh logs
sh ~/capstone/capstone.sh stop

版本化install.sh一次完成下载、校验、安装和启动,默认目录~/capstone,用CAPSTONE_TRIAL_DIRECTORY覆盖。成功时显示安装目录、访问地址、运维命令与端口配置。正式包默认App入口http://127.0.0.1:19173/,与开发5173/demo15173隔离;端口已使用时,在安装目录.env修改CAPSTONE_APP_PORT。DeepSeek/deepseek-flash为默认;OpenAI示例在注释中,模型在生成包时从Provider注册表读取。切换Provider时同时修改Provider和模型,配置对应启动Key。启动LLM变量优先;发布镜像及内部数据库/存储/操作者凭据保持包或实例固定,不能由普通.env覆盖。Key只进入worker及配置检查容器,API/App不接收Key。

新安装使用与安装目录身份绑定的稳定项目名capstone-user-<identity>;接管原版安装时保留其capstone-user-local-dev或原项目名。不同安装目录使用独立项目并选择不同App端口;版本切换复用同一目录的项目和数据卷。每实例私有配置位于.capstone-trial/<instance>/,权限0600;保留整个目录以重新连接原数据。停止不会删卷;再次启动相同来源保留数据。使用capstone.sh install <Git>安装已发布版本,use <Git>切换已安装版本;缺省启动按本地精确镜像和版本记录选择最新可用版本。原7832134安装可原地接管,保留其项目、数据卷、私有配置及原安装记录。保留整个目录,包括versions/和.capstone-management/;不要手动改写冻结包或镜像绑定。运行失败的诊断保留在该私有目录,脚本不展开配置输出。

本包是固定dev的临时试用,不更新既有cloud-dev/demo或local-demo,不属于main稳定发布。镜像实际平台、Windows/WSL2目标验证和发布入口以版本台账为准。基础注册案例及服务就绪不代表整体科学验收;正常使用LLM由用户配置的Provider处理。操作员构建与发布步骤见试用打包说明。

Offline user-local installation

内网安装包面向linux/amd64。目标机器须先安装Docker与Compose v2; 安装包包含四类镜像、模型资源、部署文件和SHA256清单,不需要Git、Python、 Node或公网下载。离线包的精确来源与实际验收范围以版本台账和交付收据为准。

解压交付归档后,在其目录运行sh install-offline.sh。先在启动环境中设置:

export PROVIDER=openai
export OPENAI_BASE_URL='http://your-internal-llm/v1'
export OPENAI_MODEL=deepseek-flash
# Set OPENAI_API_KEY in the startup environment. Do not put a real Key in arguments.
sh install-offline.sh

地址须替换为容器可以访问的内网接口;容器中的localhost指向该容器自身。 缺省Provider为openai,模型为deepseek-flash,内网地址必须配置。 OPENAI_MODEL和OPENAI_BASE_URL用于已选openai Provider;Key只进入后端worker。 本地试用的自定义OpenAI地址使用Pi的Chat Completions兼容接口 (/chat/completions,包含流式输出和工具调用);官方OpenAI地址保留Responses接口。 OPENAI_BASE_URL填写API前缀,例如以/v1结尾,不填写完整的/chat/completions路径。 安装完成后可将非敏感地址与模型写入安装目录.env,后续启动仍须提供Key。

默认安装到~/capstone,可用CAPSTONE_TRIAL_DIRECTORY选择目录。 镜像导入校验完成后,安装器调用原版本管理与数据兼容检查。 若已有目录的数据格式缺少已验证兼容路径,拒绝切换并保留旧服务和数据; 不要删除数据卷绕过检查。新独立试用可选择另一个目录和App端口。 使用sh ~/capstone/capstone.sh status、logs、stop和start管理实例。 离线版追加版本须再次使用完整离线包;在线安装命令不是离线升级入口。

操作员打包入口为deploy/build_user_local_offline.py;详见 离线设计及 实施计划。

Isolated local demo

Recognition has separate backend settings: CAPSTONE_RECOGNITION_PROVIDER, CAPSTONE_RECOGNITION_MODEL, optional CAPSTONE_RECOGNITION_BASE_URL and CAPSTONE_RECOGNITION_API_KEY_ENV. Without overrides it uses the configured execution Provider/model. The restored standalone classifier uses thinking off and a15-second routing timeout. It selects ordinary or professional without compiling business requirements, checking capabilities or planning tools. Ordinary knowledge answers also use this configured lightweight role with thinking off, in a separate tool-free workspace. Professional execution retains its own Provider/model. Model information remains on the professional chain; this does not claim it is calculation-free or as fast as independent ordinary knowledge. Provider changes use that Provider's registered defaults, not execution endpoint/key settings. Supply credentials through protected backend environment variables; the key-name setting is not a secret value and creates no credential access. Restart workers after configuration changes. This rollback/restoration uses an isolated classifier process per route request. Task compilation, pooled recognition processes and API-triggered worker prewarm remain withdrawn. Ordinary answers still enter the existing model preparation path; record full elapsed time and do not claim zero initialization. The activity UI shows latest3 actions while running, uses a bounded160px full list and collapses after completion.

local-dev is the local development and release-verification target for cloud-dev. Local API and family workers keep /app/runs in three separate, Compose-project-scoped volumes. The canonical rebuild migrates records from an older container before replacing it: stop writers, retain an ignored backup, copy into an empty role volume, and restore service ownership. It refuses to overwrite a nonempty volume from a different migration. On failure, the original containers and backups remain; the rebuild does not replace them. Do not use docker compose down --volumes on an environment whose history must be kept.

local-dev is the local development and release-verification target for cloud-dev. local-demo is the local reproduction, emergency-repair and release-verification target for cloud-demo. At rest, select the accepted cloud-demo source and feature scope for local-demo. A frozen release candidate or demo repair may temporarily differ; record its baseline, purpose and source. Do not deploy ordinary local-dev changes into local-demo. Current deployment and pending alignment belong to the version register.

Use a clean checkout of the exact demo candidate, rather than the current main checkout. Set up its managed runtimes with make setup, make install-pi, and make doctor, and install its verified PyPSA assets. Then run from main:

CAPSTONE_DEMO_SOURCE_DIR=/path/to/demo-checkout make capstone-demo-local-rebuild

The default source is .worktrees/demo-baseline. The wrapper uses the selected checkout's canonical rebuild entrypoint. It creates a separate Compose project capstone-demo-local, image name, database and object-store volumes, private bucket, operator token and storage credentials. It does not copy user data or authentication state. Its App is http://127.0.0.1:15173/; its API uses port 18767. The App proxy points to that API. A phone may use the computer's LAN IP with port 15173.

First use creates ignored deploy/demo-local.env with mode 0600. Configure its backend Provider key for interactive questions; registered scripted cases need no Provider key. The file is retained on subsequent rebuilds. Existing local development and cloud stages remain separate. Keep the selected source clean, record its full commit and image identity, and refresh the browser before cases. This target does not deploy to the cloud or alter release lanes.

Capstone 委托与 Pi 直接入口

本节和下节“共享背景与角色资源”属于 feat/pi-skills-integration 的实验功能说明。 基线一的 main 与 demo 未启用这些扩展。先在该分支验证,按 多线版本控制流程合并,再决定发布范围。

对话空闲时可切换 Capstone 和 Pi。 Capstone 先由模型识别目标:专业目标交给 Domain Pack,通用目标委托给原生 Pi。 Pi 模式先用独立的语义选择节点确定公共业务背景,再交给同一个执行器,不准备专业计划或领域工具。 两个入口共享可见历史,保留当前模型;已接受的请求和重试沿用原模式、配置及识别决策。 配置变更、提交、未知提交结果和执行中不能切换或再提交;输入框仍可编辑下一条草稿。 默认联合对话没有装配 Case 执行服务,对应操作显示不可用。Case 是独立完整模块; 本次工作不增加 Case 装配。旧 /old 入口与 Case 模块保持各自契约。

本地 make capstone-local-rebuild 同时构建并启动独立的 general-pi 服务。 deploy/local.env 需设置独立的 CAPSTONE_GENERAL_CONTROL_TOKEN;不要写入 App 构建变量。 worker 使用私有 CAPSTONE_GENERAL_EXECUTOR_ORIGIN。执行器启动时通过原生 Pi 读取实际工具清单, 不调用 Provider;任务执行使用所选 Provider,可能计费。当前 relay 支持 API-key 的 chat-completions 传输,Anthropic 和 OAuth 配置会明确拒绝。没有配置执行器时不会退回受限 Pi 并声称通用任务已接通。

原生设置目录为 configs/runtime/general-pi/。每个任务按 Pi 约定复制受控 settings、 AGENTS、skills 和 extensions,加载有限的共享历史、公共业务投影与依赖观察,不加载专业策略或 Authority 句柄。 read/write/edit/bash 在独立 UID 和工作区中运行;宿主凭据通过可撤销 relay grant 隔离。 角色资源由版本化配置准备;任务不能自行安装依赖。

基础 Python、CLI、依赖锁、构建检查及环境收据见原生隔离编程环境。

PPT template library

启用模板库的会话缺省使用国网模板。可通过对话要求“这次使用上传的模板”“把模板保存到模板库” 或“恢复默认国网模板”。单次指定只影响本次生成;会话选择持续到下次明确更改。 模板导入缺省为 session 作用域,不能把导入成功当作跨会话入库成功。明确保存入库时, 须发布并核对实际目录的 library 作用域;同工作空间的其他会话才能复用。

生成后保存 PPTX、内容源包与渲染回执;成功转换时同时保存 PDF。换模板时使用源包, 不重新查询业务数据。旧 PPTX 若没有对应源包,只能先恢复内容,不能声称完全相同内容重生成。 每次生成使用新版本,保留旧成果。排版溢出需修改明确的内容或页计划;不要静默缩小字体。 PDF 转换失败或不可用时保留有效 PPTX,并明确报告 PDF 状态。渲染回执不认证业务结论。

本地 Compose 已为原生宿主设置 CAPSTONE_PRESENTATION_API_ORIGIN=http://api:8766。 其他环境在原生宿主的受保护环境中设置所选 API origin,并沿用后端保护的 operator token。 该 origin、令牌和私有对象存储凭据不放入 App 构建变量,也不交给模型选择。 宿主从当前任务绑定取得工作空间和 Thread,只向隔离任务提供已验证的模板文件。 库元数据使用共享 PostgreSQL,模板字节使用私有对象存储;API 与 worker 仍须同源码/镜像。 上传和存储配额与 PPTX 处理预算分开。现有无模板 capstone-report 命令保留为独立基线。 设计与接受标准见PPT 模板库设计。

企业生产数据 MCP

enterprise-research 可按应用授权使用 data-gateway 的远程工具。设置 CAPSTONE_DATA_GATEWAY_CONFIG_DIR 为运维连接目录,设置 CAPSTONE_DATA_GATEWAY_CONNECTION_FILE=/run/capstone-private/data-gateway/connection.json。 目录只读挂载至 general-pi,连接文件须为0600,包含 Streamable HTTP URL及Bearer头。 挂载位于镜像原生文件系统的0700宿主专用父目录下;不能仅依赖挂载文件的权限位, 部分宿主文件共享环境不会按任务UID执行其权限。验收须真实降权并尝试打开,不能只查mode。 凭据不进入App、模型上下文或原生任务环境;任务仅获得可撤销的本地宿主代理授权。 不要把连接文件提交到Git或作为研究附件上传。

本机研发的网关连接不绑定易变的局域网IP。宿主机可用 http://127.0.0.1:18001/mcp。本地Compose通过 CAPSTONE_GATEWAY_LOOPBACK_HOST=host.docker.internal把网关登记中的回环地址 转换为容器访问宿主机的地址;界面仍显示原登记地址。此转换不修改其它服务地址。 直接在宿主机运行时不设置该变量。研发服务器使用该环境的固定IP或固定服务名。 地址由用户或运维登记,不由智能体自行选择。

左栏“数据网关”浮窗显示当前会话的实例,并列出已知连接供查看。 只有空会话可以点“使用此网关”更换自己的实例;输入草稿不算提交。 首次有效指令与实例锁定在同一事务中保存,之后前端禁用切换,后端也拒绝切换。 切换会话时,左栏实例及切换权限跟随会话。更改默认连接不影响已有会话,切换失败保留原选择。 实例不可用时明确报错,不自动接用其他实例;需要其他实例时新建会话。 同一实例可以更新契约,已执行任务保留冻结目录与回执,模型视图和实际取数使用同一会话来源。 刷新图标异步检查全部实例;连通检测和目录验证的期限分别由 gateway_connections.py中的HEALTH_TIMEOUT_SECONDS与ADMISSION_TIMEOUT_SECONDS管理。 连通状态仅说明MCP连接检查结果,不证明业务数据齐全;数据离线标志单独显示。

“添加网关”接受URL和必要的认证令牌。先测试连接,再保存。MCP可发现实例身份、环境、 数据源标签和工具契约,不能发现认证秘密或服务端私有配置。地址若已登记,可复用后端 保存的认证;新地址缺少认证时需用户提供。同一已发现实例的地址别名不会重复登记。 令牌只在提交时经过前端内存,不写浏览器存储或公开列表。

连接登记与默认选择保存在general-pi的私有持久目录profiles/data-gateways/registry.json,目录0700、 文件0600。会话的实例标识和锁定状态保存在Thread数据库,不保存认证令牌。 连接挂载目录中的connection.json仍支持旧安装的首次引导;也可放置0600的 instances.json,其schema为capstone-gateway-seeds/1,可含selected_id; entries数组的每项含id、label和沿用原连接格式的connection对象。 这些文件属于受保护配置,不能提交Git。受保护种子按稳定ID更新认证和标签;已保存的 选择及用户新增项保留。服务暂时不可达时保留登记,后台恢复实际连接,而非只更新状态点。

configs/runtime/data-gateway.json声明准入策略。启动时发现实际schema并绑定执行器身份, 任务只调用已接纳的data_gateway_工具,研究子节点沿用同一目录与来源回执校验。 网关管理其数据后端,Capstone不增加数据库切换或副本选择流程。未配置时保持原研究 能力;已配置但连接失败时明确标记不可用,不回退合成数据或宣称生产数据访问成功。 新指令用轻量检查比较实例标识和契约发布时间;未变化复用目录,变化后更新后续任务。 检查失败不能当作未变化。工具schema变化不改变在途任务契约,也不改变会话绑定的实例。 模型工具是否可用以当前发布、权限和工具契约为准。登记范围不代表已生成或可计算模型。 超时、连接、认证或目录变更会停止本次任务的后续网关探测,下一条用户指令 可以重新检查;失败报告保留具体错误类型,不推断整个网关宕机。 更改源码或配置后使用规范本地重建入口。

共享背景与角色资源

/skills 打开资源选择器,显示来源、版本、可用状态与实际执行角色。 /skill:<name> <任务> 提交绑定技能的类型化输入;/context 打开背景选择面板, 保留原草稿。/skills 和 /context 只打开面板,不调用模型,也不创建假消息。未知斜杠文字需要明确按普通 文字提交;普通文字始终关闭原生 skill/template 展开。模式改变时,不兼容的技能显示原因, 不能静默改为其他角色。配置与提交共用同步操作约束;移动端与桌面均保留下一条草稿编辑。

两个入口共用 Thread 公共对象索引,按任务选择当前或历史对象。显式排除优先;必要资料 缺失时返回缺口或澄清。当前实际模型背景是身份、公共版本与历史,不含完整模型数据表。 技能附带的示例电网不能替代已选业务对象。公共资料只按已授权 ID 解析,副本进入只读 任务输入区,不能通过任意宿主文件路径取数;它们不会自动上传为新产物。

操作者在 configs/runtime/agent-resources.json 固定来源、版本与适用角色,原生配置位于 configs/runtime/general-pi/ 和 configs/runtime/capstone-pi/。安装入口:

make install-agent-resources
make capstone-local-rebuild

安装器校验固定源码、schema、依赖和实际 MCP 调用,成功后才发布当前不可变安装。 安装不是角色就绪证明:原生 SDK 加载、角色工具发布与专业适配分别检查。失败不覆盖 可用版本;任务启动不下载依赖。安装状态保留在忽略的 .grid-agent/runtime/agent-resources/。 Compose 的 general-pi-profiles 与 general-pi-resources 卷保存已接受配置及固定安装, 不迁移或删除原有任务、收据、数据库或对象存储。旧任务重试使用已接受版本,撤销或缺失 资源明确失败。不要复制或移动其他系统的 venv;后端与 general-pi 镜像各自在 Linux 最终路径安装。

原生 Pi 可加载固定 PowerSkills pandapower 内容,并通过受控扩展执行十项 PowerMCP 工具。 Harness 使用领域能力包原创适配指南,将结构检查映射到既有 analysis.run 的 diagnostic.structural 操作。Authority 导出当前模型,调用 load_network/audit_network, 保存有版本和来源的结果并经当前运行准入绑定证据。结构检查不证明潮流收敛或运行安全。 上游技能和所有 MCP 工具不会因安装自动兼容 Harness;版本、适配器、精确参数、模型修订 和结果/证据校验共同约束专业执行。领域映射仍由 Domain Pack/Authority 拥有,不进入 Kernel。

执行器将工具观察和文件产物保存为外部任务记录,不将其视为电网结果或证据。 文件字节先校验并保存,才提交成功;私有控制端支持按任务和产物 ID 读取。 App 提供生成文件的预览与下载。容量和保留期限由应用容量配置管理;使用初始化说明统一设置 API、worker、执行器和前端。容量满时明确报告实际值与上限,不能靠删除墓碑重做未知副作用。保存成功后释放任务工作区;保存失败保留文件、已验证元数据和工作目录,按正常保留期限清理。原生 token/cache 用量保留,费用标为未知,不能用合成的零价格估算真实费用。

离线真实 Pi 检查需要先构建本地 general-pi 镜像,再运行:

CAPSTONE_GENERAL_NATIVE_TESTS=1 uv run --project packages/capstone-agent pytest packages/capstone-agent/tests/test_general_pi_native.py -q

该检查只调用 loopback 假 Provider。它验证工具、隔离、取消和产物,不能证明真实新闻检索质量。 真实 Provider 的回答验收仍按单独授权进行。

App 根路径 / 默认进入智能体对话页;已有 ?thread=<id> 链接继续打开对应 Thread。App 先读取 /api/v1/thread-access:CAPSTONE_THREAD_OPEN_ACCESS=true 时直接进入工作台,不输入或保存浏览器令牌。本地 Compose 默认开启;cloud-dev 在本地验收后显式开启。设为 false 时保留原 operator token 入口。该接口返回访问模式和安全的有效容量快照,不返回操作员或 Provider 密钥。创建 Thread 后把其 ID 写入当前 URL,刷新时恢复同一 Thread。模型目录只提交“打开 模型 ID 电网模型”,拓扑由模型状态投影同步。已完成回答可重新提交原指令作为新的 Turn,保留原回答;失败回答沿用原 Turn 的重试 Attempt。原登记案例页移到 /old,下面的公开案例说明均指该页面;案例受限凭证不会授予智能体 Provider 权限。

企业工作台入口为 /enterprise。可用 /enterprise?workspace=<name>&thread=<id> 打开已授权的会话。切换会话会保留入口路径。刷新读取同一会话及成果,按当前工作空间和访问模式授权。

对话区的小型「新建对话」创建独立 Thread,不取消原有后台任务。用户系统、历史会话列表、归档恢复界面和 LLM 会话命名暂缓,后续计划记录在会话管理计划。当前 App 只管理已连接的 Thread;既有消息、结果和证据仍保留。

服务端模型准备缓存有容量和空闲期限。正在执行的 Attempt 固定其资源;空闲回收只释放进程对象、声明和端点,不删除数据库中的消息、结果与证据。下一条指令按已登记的模型重新准备资源。运行时在终态停止,RPC 请求有有限期限。API 对实时订阅总数及每个 Thread 的订阅数设上限,连接结束后释放名额;容量暂满时返回可重试的 503。缓存数量可在 worker 私有 /health 的 thread_contexts 中核对。阈值统一由共享运行配置管理,本地与云端必须一致。

Thread 是持久记录,不为每个打开的对话预留 worker。执行资源按 Attempt 分配;租约控制执行权。一个可见页面保持一个事件订阅;切走 Thread、关闭页面或切到后台时关闭订阅,返回时补读事件。空闲订阅逐步降低查询频率,最长间隔 2 秒,每 15 秒发送心跳;每次数据库操作后释放连接。旧 /old 会话的容量和闲置回收仍由兼容 host 管理。

临时网络或服务更新中断连接时,App 自动重连,重试间隔为 1、2、4、8、15 秒,上限 15 秒;认证或永久请求错误不持续重试。重连恢复快照和事件光标。未知提交结果只核对原始命令及幂等键,不生成重复指令;已失败或中断的 AI 执行仍需用户明确重试。当前浏览器会话保存每个 Thread 的草稿和最多一个待确认命令,按 API 原点和认证会话隔离;草稿和待确认命令使用应用初始化容量;超额明确报告,不静默截断或覆盖原草稿。浏览器禁止存储时保留内存草稿,但整页刷新无法保证恢复。

消息首次打开只读最近一页,点击小型文字入口「查看之前的对话」读取当前 Thread 的较早内容,点击「返回最新对话」回到最新内容。消息窗口和浏览器事件缓存使用应用初始化容量;单条事件仍受 API 的事件大小限制。当前电网视图通过同一 Model Context 的受限源事件投影恢复,不从旧模型借用图或证据。这些限制不删除服务端历史,也不改变 Kernel 的模型上下文或当前运行证据准入。

模型目录在打开前检查完整拓扑的可用性;超出容量、拓扑数据无效或模型服务未就绪的选项显示原因并禁用,服务端也拒绝这些切换。指令拒绝、执行失败和拓扑不可用均显示原因、下一步操作及安全诊断代码;输入草稿和已完成回答保留。完整操作视图的母线、支路、投影和事件容量使用同一应用初始化配置,不截断模型。较大事件按有效字节配额分页,刷新仍恢复完整底图。

独立的 packages/capstone-app/ 是公开访问操作台,当前开放已登记的三轮 Provider 案例。顶部电力科学AI主题图展示专业框架与科学计算模型,图下短文介绍 CAPSTONE 的领域能力与运行机制。目录浏览和打开案例不调用 Provider;选择案例即显示登记模型全图。点击「执行指令 1」会创建 mode: "provider" 会话并直接提交首条指令,后续可逐条提交,也可点击「自动完成」让同一会话按序提交剩余指令、等待每轮已提交答案和对应电网图层后继续,并在结束时生成报告;图层不可用时按有界等待继续。「停止自动执行」只停止后续步骤,已接受的当前指令会正常完成,并显示暂停说明。切换案例时,当前标签页保留各案例最近一次会话、完成步骤选择和仍在运行的自动流程;完成后可从分析过程标题旁点击「重置案例」回到初始状态,重新选择逐步执行或自动完成,不改变其他案例的当前状态。报告生成后显示在中栏分析流程底部;右栏查看运行状态与当前运行准入证据。页面加载与刷新时自动向 API 领取访问凭证并进入工作台,不持久化凭证;同一标签页的会话编号和创建防重复键保存在 sessionStorage,刷新后恢复各案例最近运行与所选案例。明确重置后才开始新一轮,断网重试不会重复创建会话;刷新不会恢复正在执行的自动提交循环,已提交的步骤仍可查看或手动继续。页面调用相同的 /api/v1 接口,不关心 API/worker 所在平台。报告与当前运行准入证据由 API 从私有工件存储读取,浏览器不直接访问 bucket 或本地运行目录。

API 启动时预热已登记案例的权威模型图,已认证的 GET /api/v1/cases/{application_id}/{case_id}/diagram 直接返回经过边界校验的完整底图,不创建运行或证据。运行中的 worker 仍从该次运行登记的 gridctl 或 PyPSA authority 读取完整元件和坐标,将底图与逐步骤图层分别写入持久事件;API 通过已认证的 GET /api/v1/sessions/{id}/network?ordinal=N 重建指定步骤的投影,并以当前运行视图覆盖案例预览。SciGRID-DE 使用模型地理坐标展示全部 585 个母线、852 条线路和 96 台变压器;IEEE-39 使用模型电气示意坐标展示 39 个母线、35 条线路和 11 台变压器。非电网步骤继续显示同一底图,图层数值回到中性;完成步骤可点击回看,执行任务时重新对焦。白底拓扑图支持拖动平移、Shift + 滚轮或按钮缩放、适配全图和回到任务;普通滚轮滚动页面。电气示意图用短母线符号,地理拓扑图用位置点;图例仅列实际存在的元件类型。线路负载率着色仅覆盖同修订、同本轮已准入的逐元件结果;本轮已返回线路中的最高值显示为红色,图例标明这是相对色阶以及实际数值范围,不代表越限。缺失的元件保持中性色。没有可验证底图时显示不可用状态,不影响已提交答案。模型面对的 PyPSA model.topology 仍只返回至多 50 个母线;完整底图只供操作视图使用。

本地使用一个后端镜像的 api、worker 两个角色,以及 PostgreSQL 和兼容 S3 的 RustFS:

cp deploy/local.env.example deploy/local.env
# 编辑 Git 忽略的 deploy/local.env,替换全部示例值。
docker compose --env-file deploy/local.env config --quiet
docker compose --env-file deploy/local.env up --build -d
curl -fsS http://127.0.0.1:8767/health/ready
make setup-capstone-app
make capstone-app-dev

日常修改后使用一键重构入口,避免 API/worker 继续使用旧镜像:

make capstone-local-rebuild

该入口读取 deploy/local.env,校验 Compose 配置,按当前源码重建并强制替换 API/worker,等待依赖与健康检查完成,确认两个角色使用同一镜像摘要,并确保 Vite App 已启动。App 未运行时会在忽略的 .capstone-agent/ 下后台启动并记录 PID/日志;设置 CAPSTONE_START_APP=0 可跳过。需要同时刷新基础镜像时设置 CAPSTONE_LOCAL_PULL=1。脚本会先校验本机 .grid-agent/runtime/pypsa-models 中的六个固定模型,并将它们放入本地构建上下文,因此本地重构不会重复下载模型。 重构后刷新浏览器,已有会话需要重置后才会开始新运行。

Native worker 的 CAPSTONE_NATIVE_MAX_CONCURRENT_ATTEMPTS 设置独立会话执行槽位, 必须为正整数,缺省为 1。本机候选可设为 2 验证两个会话并行和第三个等待; 该设置不提高单任务网关并发,也不启用实验模型请求池。槽位在任务运行及清理结束后 释放;尚未领取的任务取消后立即进入终态,已运行任务沿原有中止流程清理。 容量按 worker 进程生效,多副本的合计容量由部署配置决定。

构建依赖需要代理时,可设置 CAPSTONE_LOCAL_BUILD_PROXY 为构建容器可访问的 代理地址,例如 http://host.docker.internal:7897。该值仅传给镜像构建, 不写入镜像运行环境,也不改变应用的联网授权。容器内的 127.0.0.1 不是宿主机。

Local Capstone build-cache maintenance

Standing rule: after every local build and its validation/use, clean Capstone's unused images/cache while preserving all container-referenced images and user volumes/data. Do not add a background service or broaden cleanup automatically. If this build uses CAPSTONE_LOCAL_CACHE_CLEANUP=0 because a manual cleanup was already active, the operator must run the scoped helper with --apply once validation/use ends and the other cleanup has stopped.

After all readiness, image-identity and App checks pass, the canonical rebuild runs scoped maintenance. It removes only untagged, digest-free images with the exact Compose project label capstone that no running or stopped container references. Its image inventory includes intermediate images (--all). It reinspects tags and references before removal, never forces image removal and uses --no-prune to preserve unselected parent images. Other projects, tagged images, container data and volumes remain.

Build-cache ownership requires a direct explicit Capstone package/module/CLI build command in each selected record. Parent or child relationships never transfer ownership: another project can inherit a Capstone intermediate layer. Generic base/apt/WORKDIR records and unknown ancestors or descendants remain. Shared and non-reclaimable records are excluded. The helper reads dynamic Buildx JSON IDs, uses one anchored ID filter, and verifies that filter with a read-only du query before pruning. No global image/system/builder prune or volume cleanup is used. Buildx budget accounting can include the builder's other cache, but deletion remains restricted to the verified IDs; protected/unknown cache can prevent reaching the target.

Operator shell environment overrides (also accepted as helper CLI arguments):

Environment Default Meaning
CAPSTONE_LOCAL_CACHE_MAX_USED_SPACE 40GB Buildx cache retention target
CAPSTONE_LOCAL_CACHE_RESERVED_SPACE 20GB Buildx cache reserve; positive and no greater than target
CAPSTONE_LOCAL_CACHE_BUILDER current selected builder Explicit Buildx builder to inspect and maintain
CAPSTONE_LOCAL_CACHE_CLEANUP 1 Set 0 to skip post-rebuild maintenance, for example while an operator prune already runs

These are operator environment settings; the helper does not read credential files. Start with a dry run, which performs no deletion:

python3 deploy/cleanup_local_build_cache.py
# Explicit application of that scope after inspection:
python3 deploy/cleanup_local_build_cache.py --apply

The rebuild writes a unique receipt under .capstone-agent/cache-maintenance-*. Maintenance failure prints a visible warning and preserves successful deployment status. An apply-only nonblocking per-user lock prevents two helpers across worktrees from pruning concurrently. It cannot detect an unrelated manual prune; use CAPSTONE_LOCAL_CACHE_CLEANUP=0 during that operation. Do not retag images or change builders concurrently with maintenance. There is no background service.

本地重建和 make capstone-app-dev 显式选择 local-dev;本地演示重建入口 make capstone-demo-local-rebuild 选择 local-demo。直接运行 Vite 时可设置 非浏览器变量 CAPSTONE_APP_ENVIRONMENT=local-dev 或 local-demo;未设置时页头 显示「环境未配置」,不会根据端口或网址猜测。页头同时显示包版本与源码提交, * 和悬浮说明保留未提交修改状态。开发页每 30 秒及重新获得焦点时刷新源码身份。 重建脚本会拒绝复用标签不符的 App,须先停止旧 Vite 进程再重建。

公开演示模式必须在 deploy/local.env 中显式设置 CAPSTONE_PUBLIC_PROVIDER 和 CAPSTONE_PUBLIC_MODEL;Compose 不再为 LLM 后端注入隐式模型,缺少任一项会在启动前直接失败。为了让网页应用和本地案例 脚本使用同一模型,本地部署应将 CAPSTONE_PUBLIC_MODEL 与根目录 .env 中的 GRID_AGENT_LLM_MODEL 保持一致。

在电脑上打开 http://127.0.0.1:5173/ 直接进入智能体对话,打开 http://127.0.0.1:5173/old 进入原案例页。本地 App 默认监听 0.0.0.0,同一局域网的手机可打开 http://<电脑局域网 IP>:5173/。原案例页会自动获取服务端提供的访问凭证,该凭证只允许已登记案例,案例会话仍固定使用 Provider 模式。智能体对话默认使用开放访问模式,浏览器不需要 operator token。Vite 通过同源代理把浏览器请求转发到电脑的 127.0.0.1:8767,API 端口仍只绑定本机 loopback;数据库和 bucket 不发布主机端口。可用 CAPSTONE_APP_HOST=127.0.0.1 恢复仅本机访问,或用 CAPSTONE_APP_PUBLIC_HOST=<电脑局域网 IP> 指定脚本输出给手机使用的地址。若 8767 已被占用,可设置 CAPSTONE_API_PORT 更改 Compose 的发布端口,同时设置 CAPSTONE_API_PROXY_TARGET 为该 API 原点。make build-capstone-app 生成静态发布产物,make test-capstone-app 运行前端定向测试。

本地 Compose 与 cloud-dev 的普通工作台共用 host-runtime-v1.json 和同一个启动器。配置契约固定 Provider、模型、应用角色与启动依赖;环境仅提供数据库、存储、域名、凭据与容量。API 等待两个 worker 就绪,运行中的模型目录与指令准入实时更新 worker 健康状态。配置冲突会在启动前失败,日志只显示配置项。部署时比较三角色的 /app/.capstone-agent/host-runtime.json 与本地验收记录,契约和制品哈希必须一致,再验收真实 App、Provider 与证据。专项 M11 脚本验证需显式设置 CAPSTONE_RUNTIME_PROFILE=,不得作为普通工作台的验收记录。

启动器也以 Host runtime receipt: 前缀将同一份无秘密JSON回执写入stderr。容器文件访问失败时,可按精确的项目、环境、服务和部署ID筛选这条日志;核对角色、阶段、契约、源码与安装工件摘要后,再进行发布验收和标签登记。

镜像从已锁定的 grid/PyPSA/Capstone Python 环境与 npm 依赖构建,并在构建期安装、逐项校验六个官方 PyPSA 模型资产;运行时不会从宿主复制 .grid-agent/ 或下载模型。API/worker 的差别只在 /app/deploy/entrypoint.sh 的角色参数。会话、创建与命令幂等键、事件序号位于 PostgreSQL;报告和受限证据投影位于私有工件存储。worker 中途退出后租约到期会标记运行中断,先前已提交的答案仍可读取。worker 对等待下一条指令的旧式会话计时;空闲期限由共享运行配置中的 CAPSTONE_SESSION_IDLE_SECONDS 决定,可在 60–86400 秒间调整。本轮指令或报告仍在执行时不计时。到期后会话标记为「会话已超时」、释放 worker 名额,已提交的答案和证据保留,旧会话不可续交。名额已满且有新会话排队至少 1 秒时,worker 会从所有副本持有的会话中原子选取已空闲至少 30 秒的最久会话;正在计算或整理报告的会话不会被淘汰。访客可重置已中断的案例重新开始。刷新页面会重新取得演示凭证、回到该案例最近的运行状态;已超时或让位的会话可回看,但不会重连计算进程。CAPSTONE_WORKER_MAX_SESSIONS 默认每实例 8 个,可按内存实测在 1–64 间调整;云端通过增加 worker 副本扩容,每实例仍有独立上限。API 的 /health/ready 检查 PostgreSQL,依赖 bucket 的操作仍以实际读写结果为准。

云端部署说明分别位于 Cloud Run + Vercel 和 Railway。Cloud Run 使用服务加 worker pool、Cloud SQL 和 GCS;Railway 使用 API、按需唤醒的 worker、PostgreSQL、私有 S3 bucket,并可托管静态 App。两个后端角色须基于同一已验证源码修订,并共享账本/工件配置;可拉取时优先固定同一镜像 digest。Railway Hobby 无法配置私有镜像仓库凭证,当前演示部署使用同源代码构建。Railway 和本地 Compose 的 API 通过 CAPSTONE_WORKER_WAKE_URL 访问 worker 私有 HTTP 端点;Cloud Run 未设置该变量时保持原有轮询模式。App 构建变量 VITE_API_ORIGIN 是所选 API 的公开 HTTPS 原点,绝不能设置操作员或 Provider 凭据。API 设置 CAPSTONE_PUBLIC_DEMO=true 时,服务端为 /old 原案例页发放演示凭证;关闭该开关时原案例页显示连接失败与重试,私有操作员令牌仍可通过 API 使用。首页智能体对话由独立的 CAPSTONE_THREAD_OPEN_ACCESS 开关控制。CAPSTONE_ALLOWED_HOSTS 与 CAPSTONE_ALLOWED_ORIGINS 分别约束 API Host 和 App Origin;PORT 在服务角色启动时读取。云端数据库、bucket、密钥和域名须先准备好,实际部署另行授权。

云端 App 源码通过 python3 deploy/prepare_app_source.py --source-ref <完整提交SHA> --environment cloud-dev --api-origin https://<所选API域名> --output .capstone-agent/app-builds/<新目录名> 本地准备;用户试用选择 cloud-demo。 此工具只导出该提交的 App 文件,并生成公开的 build-revision.txt 和 build-environment.json,绑定环境、精确提交及 API 原点;不部署、不覆盖已有目录, 不导出 Git、凭据和运行数据。以新目录作为托管 App 项目根目录,仍只设置 VITE_API_ORIGIN,且须与收据一致。缺失收据、来源或原点不符时构建失败; 环境标签是部署配置身份,不代表环境已通过验收。详见上述云端部署指南。

Railway 的持续开发配置分为两个隔离阶段:现有 capstone-demo 保持用户试用,capstone-cloud-dev 承担开发版本的云端验证。两个阶段分别准备 API、worker、PostgreSQL、私有 bucket 和静态 App,并分别使用数据库、工件存储、操作员令牌和域名。Provider 凭据默认隔离;用户已允许当前功能验证阶段使用现有凭据,实际值仍只写入 worker 的受保护环境变量。开发版本通过本地门禁后部署到 cloud-dev;完成健康检查、登记案例、Provider、报告、证据回放及 API/worker 修订一致性检查后,经人工核验,使用同一已验证源码修订或镜像 digest 晋级 demo。晋级失败时回退到上一版已验证修订。变量清单见 Railway cloud-dev 和 Railway demo;文件只含占位符,不是凭据文件。

部署前用 python3 deploy/railway/control_plane.py --project-id <已有项目ID> --expected-project capstone-cloud-dev 读取目标项目,复用现有 Railway CLI 登录态。工具区分网络、认证、权限和证书错误;仅对读取请求的网络故障最多重试三次。上传或部署丢失响应时先查询实际状态,避免重复部署。该检查属于部署工具;App 根页面仍直接进入,不要求用户输入 token。具体规则见 Railway 连接检查。

PyPSA 电网模型库与本地案例

PyPSA 1.3.0 的六个官方 Network 示例与 15 个项目模型一起登记在模型库中。官方 NetCDF 只通过操作者命令下载,逐项核对固定文件大小和 SHA-256,保存于 Git 忽略的 .grid-agent/runtime/pypsa-models/。若要使用只读容器目录,可设置 CAPSTONE_PYPSA_MODEL_LIBRARY_DIR 指向已安装且校验过的资产目录。缺失或被改动的资产不能被 model.open 使用;案例运行中不会联网下载。

make setup-pypsa
make list-pypsa-models
make install-pypsa-models
make list-pypsa-cases
make run-pypsa-case CASE=regional-demand-stress
make run-pypsa-case CASE=ac-dc-interconnection
make run-pypsa-case CASE=scigrid-dispatch
make run-pypsa-case CASE=regional-demand-stress DEMO=1
make run-pypsa-case CASE=scigrid-dispatch DEMO=1
make run-pypsa-case CASE=ac-dc-interconnection DEMO=1

案例清单位于 validation/pypsa-cases/cases.json。runnable 表示已登记并通过本地应用链路的流程;catalog-only 表示模型已入库但相应的规划、储能价值或跨部门分析仍缺受控能力。validation/pypsa_cases.py 使用确定性脚本 Provider 验证 AgentApplication、两个 Domain Pack、授权模型交接、PyPSA 求解器和当前运行证据。它不检验真实 LLM 的问题理解和工具选择,也不代替需凭据且可能计费的 Provider 验证。

三个 runnable 条目各带 introduction 结构化字段,供 App 展示案例摘要、业务问题、PyPSA 框架支持、智能体交互变化、专业与框架价值、解读边界。introduction.markdown 指向同目录下的完整介绍:区域负荷增长、SciGRID-DE 调度、AC/DC 互联核查。介绍是静态案例说明,不含某次求解的数值结论;App 应从该次运行的展示 JSON 读取实际结果与证据。当前交互为选择已登记案例、由确定性脚本走完语义能力流程,尚未验收开放式 LLM 自主规划。

每个介绍另有 current_user_input 与按顺序排列的 demo_instructions。默认 run-pypsa-case 仍把案例清单中的单条固定 question 交给应用;DEMO=1 则在同一次 ApplicationRequest.questions 中提交三条登记指令,复用同一模型修订与应用运行。也可用 INSTRUCTIONS=path 提交每行一条指令的文本文件;脚本仅接受与该案例登记列表完全一致的内容。三个案例已在本地用确定性 Provider 完成多回合验收,展示 JSON 的 turns 按序提供指令、已提交答案及逐回合结果/证据引用;区域负荷比较还给出两次求解各自的结果引用。pypsa-agent 已登记正式双绑定 Application Profile;capstone-agent 逐条提交指令并返回本轮答案与证据。真实 LLM 对这些指令的理解与工具选择尚未验收。

每次 run-pypsa-case 的 stdout 为案例展示 JSON;完整副本写入 runs/pypsa-cases/<run_id>/presentation.json。其中包含模型来源与校验值、逐回合答案、情景、求解状态、带单位说明的目标或比较、受限拓扑、可追溯的答案/结果/证据引用。SciGRID-DE 只提供前 50 个母线及它们之间的分支预览,并明确给出省略数量。拓扑本身不代表求解后的潮流覆盖层;线路高负载列表来自独立的调度结果。官方示例的数据与假设需要结合原项目说明解释,不能用作运行许可。可参阅模型库与案例设计。

主路径:执行自然语言分析问题

通过统一客户端提交 Provider 请求,或在 App 中发送指令。专业分析由应用选择 Domain Pack 和 Authority;数值与证据来自注册 Authority。

make capstone-agent-run REQUEST=validation/client/pandapower-analysis-task.json

请求中的 provider/model 按当前配置解析。密钥仅留在受保护环境或项目认证状态中。

离线冒烟与回归路径

离线验证直接使用注册 Authority 或显式脚本替身,不调用旧 CLI。

make validate-application
make capstone-agent-run REQUEST=validation/client/pandapower-scripted-task.json

脚本回答用于验证执行契约,不等同于真实模型验收。

连续分析报告

统一客户端的请求文件包含有序 instructions,同一应用会话逐条执行并生成报告。

make capstone-agent-run REQUEST=validation/client/pandapower-analysis-task.json
make capstone-agent-run REQUEST=validation/client/pandapower-analysis-test.json

结果和报告路径由统一客户端返回。已提交答案、当前运行证据与报告按各自契约持久化。旧 analysis/report 命令已删除。

通用应用实例化路径

应用按 ApplicationProfile、DomainBinding 和所选 Domain Pack 装配。Kernel 负责中立执行与 core,Domain Pack 负责 domains.<binding_id>。

make validate-application
make capstone-agent-run REQUEST=validation/client/pandapower-task.json

公共 CLI 返回 capstone-client-result/1.0,内含应用组合结果。应用代码位于 packages/pandapower-application;不再安装 grid-agent 发行包。

本地轨迹工作台

轨迹投影、历史回放与只读 API 由 pandapower_application.trajectory 管理。正式任务报告与证据通过 App 和统一 /api/v1 接口读取;旧 make trajectory 服务命令已删除。历史事件的生产者标识保留以支持已有数据,不代表旧 CLI 仍可执行。

LLM 配置与 Pi RPC 路径

工作台原生 Pi 的上下文预算由应用层 configs/runtime/workbench-llm-profiles.json 的各模型 context_policy 配置。 可用 CAPSTONE_WORKBENCH_LLM_PROFILES 指定部署配置文件。四个字段为 context_window_tokens、max_output_tokens、compaction_reserve_tokens、 compaction_keep_recent_tokens;超过“窗口减预留”时自动压缩。 预留须不少于输出预算且小于窗口,近期保留量须小于触发阈值。 没有显式策略的自定义模型沿用应用容量默认值及 Pi 压缩设置。 策略参与模型配置版本校验,新指令按选中的模型生成独立的 Pi 模型与压缩设置, 不修改其他模型的全局容量,也不替换历史任务的冻结选择。

2026-11-01 依据DeepSeek 官方模型接口 和实际 /models 返回,Flash 配置为1,048,576窗口、65,536预留,触发阈值983,040。 Qwen3.8-27B按官方模型卡的原生262,144窗口, 配置32,768预留,触发阈值229,376。两者输出预算均为32,768、近期保留20,000。 内网端点未连通;按用户允许的近似配置采用上述规格,服务别名不改写。 如果部署实际窗口较小,在相应模型配置中调整,不改通用执行代码。

配置写在仓库根目录的 .env:它已被 Git 忽略。先复制模板,再只填写一个实际使用的密钥:

cp .env.example .env
# 编辑 .env:例如保留 GRID_AGENT_LLM_PROVIDER=openai,填写 OPENAI_API_KEY=...

可选的非密钥参数也写在 .env:GRID_AGENT_LLM_MODEL、GRID_AGENT_LLM_BASE_URL、GRID_AGENT_LLM_TIMEOUT_SECONDS 与 GRID_AGENT_LLM_MAX_RETRIES。后两项分别是单次 provider 请求的秒数和重试次数(0 禁用重试);每次专业 Provider 执行 都会写入项目私有的 Pi settings.json,同时作用于 Pi 的 HTTP 空闲时限、SDK 请求时限和自动重试。命令行参数优先于 .env,进程环境变量优先于 .env。支持的 provider 与默认密钥变量为:openai/OPENAI_API_KEY、openrouter/OPENROUTER_API_KEY、deepseek/DEEPSEEK_API_KEY、minimax/MINIMAX_API_KEY。openai-codex 使用 Pi OAuth,而不是 API key。

DeepSeek 模型名以其官方模型列表为准;项目只校验非空模型名,不维护 DeepSeek 模型白名单。当前项目统一使用 deepseek-flash。Pi 对尚未收录的显式模型名使用自定义模型 ID,最终是否可用由 DeepSeek API 验证。

本地 Pi 安装使用 make install-pi:已安装的受管版本通过身份和版本校验时直接复用。Docker 使用独立的固定安装层;普通源码变化复用该层。认证使用 make auth-import-pi 或 make auth-login,由 capstone-agent 处理。

Skill 与工具边界

以下边界适用于专业 Domain Pack 会话。隔离的 Pi 通用执行器使用原生工具, 其外部观察和产物通过应用委托契约返回;不进入专业权威系统的结果与证据准入。

Pi 只能访问项目发布的 grid domain tools 和 grid_guide_open。工具描述由发布的 capability 契约生成;skills/grid-static-analysis/ 说明如何组合不可变模型、完整网络/结果数据集、分析和证据。模型不得在回答正文中暴露内部 result/evidence/context/asset/constraint/path/nonce 标识;运行时根据当前回合已消费和已产生的 lineage 提交答案。

当前发布面覆盖 60 个注册网络、声明式创建与不可变修订、全静态表访问、拓扑、AC/DC/三相潮流、AC/DC OPF、IEC 60909、状态估计、诊断、AC/DC N-1、模型约束越限、风险排序、电网等值和静态保护。configs/capabilities/pandapower-3.4.0-static-analysis.json 是范围矩阵,environment.describe 是运行时权威;动态仿真、时序控制、任意文件导入、任意 Python/I/O 和未固定的外部求解器仍是明确排除项。

证据检查

每个 simulator-backed 单题 run 使用 canonical workspace;兼容根路径是应用发布的物理快照:

  • runs/<question_id>/core/events.jsonl:canonical Kernel 事件 trace;根 events.jsonl 是字节保持兼容副本。
  • runs/<question_id>/domains/grid/tool-results/:canonical domain 结果;根 tool-results/ 是兼容副本。
  • runs/<question_id>/domains/grid/evidence/:canonical 当前运行证据;根 evidence/ 是兼容副本。

根兼容副本不是 authority 输入,也不会创造证据。兼容发布失败会使 CLI 非零,但不会删除已提交的 canonical 答案;已经发布的完整兼容子树或私有暂存可保留用于诊断。

连续 analysis 额外写入 controller-owned 答案工件:runs/<analysis_id>/turns/NNN/answer-draft.json 是控制器根据当前回合最终文本和已消费/已产生 lineage 生成的提交草稿,turns/NNN/answer.json 是已接受的答案 envelope,output/answers.jsonl 汇总逐回合已接受答案。

在线运行不要求模型使用答案持久化工具。单题 run 与连续 analysis 都由控制器写入 answer_output、result_refs 和 claim_evidence_refs,并验证这些引用确实来自当前运行和当前回合 lineage。验证器不从 answer_output 文本中解析引用。result_refs 用来声明直接支撑最终结论的主结果,分析证据中已经关联的结果也会被自动定位、校验其当前运行归属和上下文一致性。拓扑事实可使用空 result_refs;AC、排序和 N-1 等结果型结论必须有当前运行的主结果或与其相连的分析证据。

连续分析的 stderr 应显示分析工具调用和一次正常模型完成;trace 不应包含模型发起的 grid_submit_answer 调用。若任一必需回合失败,运行状态为 failed、CLI 退出码为 1,且 report.md 必须在回答占位符之后保留该回合已经成功返回的可观察轨迹与工具结果摘要。

最终答案只能引用当前运行中实际存在的 evidence:sha256:* 或 result:sha256:*。迁移和清理不会删除用户主工作树中的既有 var/ 数据;本分支只使用新的 ignored runs/ 和 .grid-agent/ 布局。

保证范围:引用准入证明当前运行谱系和内容完整性,不逐句验证模型自由文本。确定性事实展示应回到已验证的 authority 结果核对。报告/观察器失败通过独立诊断体现,不撤销已接纳的主答案;排查时分别检查主答案和报告状态,不把报告缺失等同于业务计算失败。必需的证据、答案和上下文提交失败不按展示故障降级。

验证

需要逐项人工核验命令、stdout 边界、结构化工具轨迹和证据引用时,请使用 人工验证手册。该手册只使用本 Makefile 发布的入口。

make test
make test-e2e
make validate
make validate-application
make test-inventory
make test-packages

make test 是完整离线单元入口:分别运行十三个 Python 包、两个 Pi 包、workbench 与 verification-target 自检;其中 pandapower 应用单元命令显式排除 E2E,make test-e2e 验证统一客户端和注册应用执行链。make test-inventory 运行 reference service、Domain Pack 和 unchanged generic Pi transport,避免在 domain 子目标重复 transport 测试。make test-pypsa 聚焦 PyPSA authority、建模、运行计算、容量规划和行业耦合 Pack。make test-packages 构建并安装干净发行工件,验证十三个 Python distribution 与两个 Pi npm 包的源码路径隔离和兼容入口。make setup 同步 agent/simulator/Capstone/PyPSA/tools/workbench;inventory 测试通过各自 uv run 按需创建环境。

make check-types 使用锁定的 pyright 1.1.408,standard 模式、Python 3.12 最低版本,覆盖全部生产 src 树,并运行 workbench check。Kernel output.py 保留 3 个局部 Pydantic schema-attribute override,以维持现有公开 wire 属性;这不是整包忽略。make check-fast 为边界、类型和单元层,make check-integration 为 E2E 与两项 provider-free validation,make check-release 再加入 package 与 source-setup 检查。所有这些 gate 不调用 provider 或使用付费凭据。

仓库已配置 GitHub Actions:Linux/macOS × Python 3.12/3.14,Node 22.19.0,依次执行 setup、install-pi、doctor 和 check-release。这是配置说明,尚不代表远端 CI 已验证通过。

make validate 运行三层 deterministic validation:offline task-required、scripted-Pi static-analysis-core,以及绑定 docs/test_script/测试题目答案.jsonl 的 static-analysis-full 语义验收。报告分别写入 ignored runs/validation-offline.json、runs/validation-scripted.json 与 runs/validation-static-analysis-full.json;能力矩阵不足 100% 也会失败。语义验收比较真实工具结果事件和标准答案,不比较润色后的答案文字。 make validate-application 是独立的 provider-free generic application gate,报告写入 runs/validation-application-instantiation.json;它验证第一领域 pandapower 的完整 Profile/Binding/Domain Pack 实例化,不选择或宣称第二个生产领域。

make check-protected-paths 和 make validate 使用当前 C.1 repository gate:configs/runtime/application-instantiation-protected-paths.json。该运行时策略固定保护不可变的 acceptance 输入和 simulator truth boundary:configs/capabilities/pandapower-3.4.0-static-analysis.json、packages/grid-simulator、packages/inventory-domain-pack、packages/inventory-reference-service、validation/questions/task.md.txt 与 validation/questions/test.md.txt。每项 digest 均来自该路径的已提交 HEAD:<path> Git 对象;gate 同时拒绝这些路径的 working-tree 变更。

该 C.1 策略刻意不保护将在已批准后续任务中变更的 packages/capability-agent-kernel、packages/pi-capability-tools、packages/trajectory-workbench、packages/pandapower-application 和 packages/pandapower-domain-pack。这不会改写 Workstream C 的历史证据:docs/status/climb/config.yaml 继续以其记录的 source revision 与 protected-path baseline 证明当时的 closure。

Workstream C 的最终本地 release closure 必须从已提交且干净的 release-source revision 运行:

tools/climb/cycle.sh C-H005

该入口不接受 gate 或 command 覆盖。它按 docs/status/climb/config.yaml 中受固定 allowlist 校验的顺序,现场执行 inventory reference authority、Domain Pack SPI、通用 Pi transport、authority lineage、发行工件、make doctor、make test、make test-e2e 和 make validate 共九个门。策略文件本身、精确命令、权重、前置图、protected-path baseline 和 release pathspec 都进入 policy/source tree digest;每个门前后都重新检查 clean revision、tree digest 和 policy digest。只读 closure 链记录命令、rc、stdout/stderr digest 和完整输出 digest,最终 100 分不读取 carry-forward receipt。

tools/climb/gate-receipt.py <gate-key> 仍可为同一 revision 生成内容寻址的机械记录。其 mode-0600 HMAC 只用于发现意外损坏;密钥和验证器对同一 OS 用户可见,因此它不是独立信任根,也不能证明同一用户无法重签。release closure 会现场重跑全部门,不以这些 HMAC receipt 代替执行。该本地链只证明本次本机命令的可复核执行,不宣称具有 CI/外部签名者的跨主体不可伪造性。

可选 Provider 验证使用统一请求文件,凭据由后端配置提供:

make validate-provider REQUEST=validation/client/pandapower-task.json

请求可显式选择 provider/model。结果与报告由统一客户端返回,密钥不得进入参数或产物。

GitHub Issues 与小石身份

统一规则见 Issue 处理规程。用户可以在当前会话说“检查 Issues”或“处理 Issue #编号”。检查不启动修复;AI 在开发过程中主动建单也不启动后台任务。第一阶段没有定时执行,不另行调用付费模型。

小石使用独立 GitHub App,显示名称为“小石 · Capstone AI”。注册建议名称 Capstone Xiaoshi,实际技术账号以 GitHub 分配的 App slug 为准。未注册并核对身份前,AI 发布功能保持关闭。只读读取可以使用维护者已有 GitHub CLI 登录;AI 写入不能沿用该个人身份。

注册与安装范围仅选 uukuguy/capstone,不要求整个账户。仓库权限为 Issues、Contents、Pull requests 写入,Actions、Checks、Metadata 读取。不授予 Administration、Workflows 写入或发布权限。手动阶段不启用 webhook、用户 OAuth 或定时触发。具体权限可在 GitHub App 注册文档核对。

App 私钥保存在本仓库忽略目录 .capstone-agent/issue-automation/app-private-key.pem,仅文件所有者可读写(0600)。App ID、installation ID、实际账号及启用开关写入同目录的 operator.json(0600);不把私钥或 token 放进命令参数、源码、截图或 Issue。工具在每次发布前核对 App、安装和目标仓库,再申请短期安装 token。身份接入需要维护者在 GitHub 完成注册、安装及私钥配置;有名字不代表账号已经存在。

一次性接入助手可以预填注册资料,在后台交换 GitHub 返回的单次代码、保存受保护私钥并核对安装范围。以下命令只监听本机 127.0.0.1:18790,最长一小时;它不是后台修复服务。

python3 -m tools.issue_automation.bootstrap --root /absolute/path/to/capstone

在这台电脑打开命令输出的接入地址,确认创建 App,然后选择 Only select repositories → capstone。GitHub 的账号确认需要登录页面;其余配置和后续 Issue 处理使用后台 CLI/API。不要复制私钥或临时代码到会话中。助手只在核对 App、完整安装范围和实际发布账号后开启命令发布,模型调用保持关闭。已有 App 或私钥时拒绝覆盖,先核对原身份。

创建后如发生本地保存失败,保留原配置并恢复接入,避免重复创建 App。--resume 从仅所有者可读的暂存记录恢复同一个 App;必须使用原端口。

python3 -m tools.issue_automation.bootstrap --root /absolute/path/to/capstone --resume

接入完成后运行 make issues-doctor,确认仓库、身份、检查镜像及开关。接入成功不启动定时任务,不自动合并、部署或关闭 Issue。

工具的开发、测试与审查状态以实施计划为准。未通过审查的特性分支不代表已接入 main,也不代表 dev/demo 运行服务已经更新。

工具已通过审查并合入本地 main,常用入口如下。独立 GitHub App 尚未接入,AI 发布保持关闭。doctor 如实列出配置缺项;读取命令不调用模型,也不修复或发布。

make issues-doctor
make issues-scan
make issues-show ISSUE=1
make issues-status

AI 在当前会话准备中文正文和事实来源,再用 create 建单。正文文件不应包含秘密或未获授权的私有数据。身份未接入时保留草稿,不能改用个人账号绕过工具。

python3 -m tools.issue_automation.cli create \
  --title '开发中发现的问题' \
  --body-file runs/issue-draft.md \
  --provenance runs/issue-provenance.json

修复依次执行 triage、begin、record-verification、complete,由当前 AI 会话传入判断、有限源码选择和完整文件替换。工具固定记录输入、政策、源码及候选身份,独立检查原始版本的复现与候选通过情况,然后发布 draft PR。缺少受信检查或准备好的隔离镜像时不发布;不把配置缺项当作用户问题根因。两套真实入口及云发布仍按生命周期另行验证。

模型请求网络预算

configs/runtime/general-pi/model-transport.json 定义连接、读取静默、写入和连接池等待预算。 默认分别为15、90、30、15秒。读取预算限制单次等待网络数据的时间,不是模型生成总时长; 持续输出可以超过90秒,整项任务仍受原任务截止和取消控制。不同部署可调整该版本化配置, 不能用模型请求参数绕过。网络超时不自动重放工具或重跑整个任务,已有产物与来源继续保留。 流缺少正常结束、上游网络错误、内容过滤分别记录;HTTP200本身不代表模型请求成功。