OpenShell Agent 开发指南：Agent-First 工作流、OCSF 沙箱日志与仓库贡献规范

【免费下载链接】OpenShellOpenShell is the safe, private runtime for autonomous AI agents.项目地址https://gitcode.com/gh_mirrors/op/OpenShell点击查看免费下载OpenShell 是一个为自主 AI Agent 提供安全、私有沙箱运行时的开源项目而它的开发方式本身就是Agent 优先agent-first的团队使用 Agent 来设计并实现系统本文档仓库根目录的 AGENTS.md正是注入到每次贡献者交互中的主指令面约束了 Agent 在 OpenShell 仓库中应遵循的工作流、技能体系、代码规范与安全红线。本文以该文档为骨架结合仓库源码与技能目录完整解析 OpenShell 的 Agent 协作模型从四类端到端工作流链、双技能集合、Issue/PR 约定到沙箱 OCSF 结构化日志规范、网络套接字优化等具体工程准则帮助你无论人类还是 Agent 贡献者理解并合规地参与这个用 Agent 构建 Agent 运行时的项目。项目身份Agent-First而非vibe codingOpenShell 的定位是为自主 AI Agent 提供安全、沙箱化的运行时其产品本身通过策略引擎在文件系统、网络、进程与凭据注入四个维度实施纵深防御见 README.md 的 Protection Layers。这一产品理念被直接映射到研发方式上系统由 Agent 设计并实现且仓库的开发流程与产品赋予 Agent 的能力同构。这种身份对贡献者有两条硬性要求设计先行、实现紧随新功能必须先以 GitHub issue功能请求模板立项只有在 issue 存在之后才考虑开启 RFCRFC 编号由维护者分配。证据驱动Agent 必须基于当前代码与行为展开调查验证 issue 上已有的诊断信息而不是照搬早期诊断更不允许空想式编码vibe coding。双技能集合公共技能与贡献者技能OpenShell 维护两套相互隔离的 Agent 技能Skill集合路径面向对象约束公共、可安装技能skills/使用与运维 OpenShell 的用户/操作者必须能在源码检出目录之外工作以已安装 CLI 的帮助文本与已发布文档为事实来源内部贡献者/维护者技能.agents/skills/OpenShell 仓库的贡献者与维护者由仓库感知型 harness 原生发现与加载自动化仓库开发工作公共技能目录当前包含 4 个openshell-cliCLI 工作流、debug-openshell-cluster网关排障、debug-inference推理排障、generate-sandbox-policy策略生成内部技能则涵盖triage-issue、create-spike、build-from-issue、create-github-issue、create-github-pr、create-rfc、review-security-issue、fix-security-issue、review-github-pr、sync-agent-infra、update-docs-from-commits、sbom、tui-development等 18 个均为 .agents/skills/ 下各SKILL.md。AGENTS.md 不充当完整清单——详细的公共与贡献者技能表见 CONTRIBUTING.md。工作流链把技能串成端到端流水线单个技能文件不会描述技能之间的关系而 AGENTS.md 用四条工作流链Workflow Chains把它们连接成端到端流水线。这是 Agent 在仓库中行动的核心路线图。社区流入链triage-issue → 人工裁决 → create-spike → build-from-issue社区提交的 issue 先经triage-issue审查Agent 负责确立事实技术有效性与影响证据并把技术上成立的 issue 标记为state:validated。接受与否由人类决定——通过打上state:accepted或放置到路线图来表示项目应当推进该工作。无人值守场景由agent:*标签驱动形成严格的排队-回报-再排队协议人类用agent:plan-requested把计划任务入队Agent 扫描队列、产出计划并以agent:plan-ready回报人类审阅后用agent:implementation-requested把实现任务入队。一个重要的例外条款用户直接向 Agent 发出请求时即授权对应的阶段——即使预期的生命周期或工作流标签缺失或不完整Agent 也应警告用户存在差异然后继续执行且不擅自改动标签。内部开发链create-spike → 人工裁决 → build-from-issue面向内部需求的探索链。create-spike先验证可行性并在证据充分时将 issue 标记为state:validated。之后同样由人类以state:accepted或路线图放置接受或拒绝再视情况通过agent:*队列或直接指派给 Agent。直接请求的例外条款与社区链一致。安全链review-security-issue → fix-security-issue安全 issue 有严格隔离通用构建 Agent 一律不得处理topic:security的 issue。无人值守时人类用agent:plan-requested排队专门审查review-security-issue产出严重性评估与修复计划人类再用agent:implementation-requested排队修复。对专门技能的直接请求缺失工作流标签同样只产生警告、不阻断执行。安全漏洞本身不得以 GitHub issue 提交需走 SECURITY.md 渠道。策略迭代链openshell-cli → generate-sandbox-policy面向产品使用场景的链openshell-cli管理沙箱生命周期创建、连接、挂载 provider、应用策略generate-sandbox-policy编写 YAML 策略约束文件系统、网络、进程。前者管运行后者管授权边界共同构成沙箱策略的闭环迭代。仓库架构总览80 组件的职责地图AGENTS.md 用一张对照表定义了仓库的完整组件地图这是 Agent 定位改动范围的第一依据。以下按职能域归并呈现路径均为仓库根相对路径运行时与隔离层crates/openshell-sandbox/沙箱运行时——无能力capability-free的工作负载启动器、进程身份与 seccomp 介导的 I/Ocrates/openshell-supervisor/监督者运行时——网关会话、策略评估、凭据与上游网络crates/openshell-supervisor-middleware/通用中间件注册表、远程服务集成与链式执行crates/openshell-supervisor-network/网络监督——代理、L7 执行、策略评估与 provider 凭据注入crates/openshell-supervisor-process/进程监督——进程生命周期、命名空间与绕过bypass监控crates/openshell-isolation-interface/隔离后端接口——RFC 0012IsolationBackendtrait面向 supervisor 的运行时契约crates/openshell-sandbox-backend/OpenShellRuntimeBackend及与openshell-sandbox共享的经认证 Sandbox 协议crates/openshell-binary-identity/二进制身份——供隔离后端共享的可信 procfs 可执行身份解析crates/openshell-vfio/PCI 与 GPU 直通准备与生命周期。策略与日志crates/openshell-policy/策略引擎——文件系统、网络与进程约束crates/openshell-policy-schema/授权策略 schema——轻依赖的 YAML/JSON 表示、有界解析与纯授权语言语义crates/openshell-prover/策略验证与证明生成crates/openshell-prover-cli/独立的本地策略边界检查 CLIcrates/openshell-ocsf/OCSF v1.8.0 事件类型、builder、shorthand/JSONL 格式化器与 tracing layerscrates/openshell-otel/共享 OTLP trace provider、资源与 tracing layer 构建crates/openshell-otel-test-support/用于 tracing 测试的共享回环 OTLP 收集器 fixture。网关与控制面crates/openshell-server/网关服务器——控制面 API、沙箱生命周期、认证边界crates/openshell-gateway/网关二进制组合——把选定的第一方计算驱动链接进后端无关的服务器注册表crates/openshell-gateway-interceptors/在网关路由边界拦截并转换已配置的 gRPC 请求crates/openshell-bootstrap/网关元数据——注册元数据、认证 token 存储、mTLS 捆绑存储crates/openshell-server-macros/网关 RPC 授权的编译期辅助宏。计算驱动与凭据驱动crates/openshell-driver-kubernetes/K8s 沙箱 Pod 的进程内ComputeDrivercrates/openshell-driver-docker/本地 Docker 沙箱容器的进程内ComputeDrivercrates/openshell-driver-podman/本地 Podman 沙箱容器的进程内ComputeDrivercrates/openshell-driver-vm/独立的 libkrun 支撑ComputeDriver子进程内嵌自己的 rootfs 与运行时crates/openshell-driver-mxc/Microsoft MXC——Windows AppContainer 与隔离会话计算后端crates/openshell-driver-kubernetes-secrets/OpenShell 托管的 K8s Secret 存储凭据后端crates/openshell-driver-vault/Vault 兼容 KV 存储凭据后端crates/openshell-driver-db-credstore/网关数据库凭据存储后端。客户端、SDK 与工具crates/openshell-cli/面向用户的 CLIcrates/openshell-conformance/可复用的驱动无关场景与命令运行器crates/openshell-conformance-cli/可分发网关一致性list/run入口crates/openshell-sdk/异步 Rust 网关客户端gRPC、TLS、OIDC 刷新、edge tunnel供 CLI、TUI 与openshell/sdk使用crates/openshell-providers/凭据 provider 后端crates/openshell-tui/基于 Ratatui 的监控仪表盘crates/openshell-core/共享核心——通用类型、配置、错误处理crates/openshell-extension-core/扩展身份、JWT claims、bearer token 轮换与 TLS 传输原语python/openshell/Python SDK 与 CLI 打包sdk/typescript/TypeScript SDK——原生 Connect 客户端、精选沙箱 API 与生成的原生 protobuf 类型sdk/go/Go SDK。协议、部署与文档proto/gRPC 服务契约的 protobuf 定义deploy/Dockerfile、Helm chart 与 K8s manifestdocs/MDX 发布文档、导航与内容资产fern/Fern 站点配置、组件与主题资产architecture/设计决策与组件文档。公共 API 设计以 proto/README.md 为权威来源实体引用命名、工作区选择器、字段设计与 schema 演化均须遵循该文档。Issue 与 PR 约定模板、标签与 Vouch 门禁Issue 模板硬性要求Bug 报告与功能请求必须包含User Story用户故事、Problem Statement问题陈述、Impact / Why This Matters影响/为何重要、Acceptance Criteria验收标准。影响部分须说明当前行为的后果、现有 workaround 及其不足Bug 报告额外要求复现步骤与环境细节可附精简脱敏的日志。功能请求还须包含 Proposed Design拟议设计与 Alternatives Considered备选方案。设计应定义用户可见的工作流与外部可观察行为把内部实现选择留白Agent 调查是可选项。优先级标签OpenShell 不设priority:*标签。三权分离的裁决模型Issue 审查强调Agent 立据、人类裁决Agent 可标记state:validated技术有效性与影响证据已确立人类才能应用state:accepted、放置路线图、应用agent:plan-requested/agent:implementation-requested无人值守队列由生命周期与请求标签把关直接的用户指令可授权缺失标签的阶段但 Agent 必须警告并保持标签不变。PR 规范PR 必须遵循模板结构Summary、Related Issue、Changes、Testing、Checklist。贡献者应使用 Agent 调查当前代码与行为、验证 issue 上的既有诊断并报告自己提交的实现与验证结果而不是粘贴先前提交 issue 时的诊断。涉及特性、用户可见行为、公共 API、架构或多 PR 工程的 PR 必须关联已接受的 issue小型文档修复、机械维护与显而易见的局部 bug 修复可说明无需 issue 的理由。Vouch 系统首次参与的外部贡献者必须先被背书vouch否则其 PR 会被vouch-check工作流自动关闭组织成员与协作者自动绕过该门禁维护者在 Vouch Request 讨论下评论/vouchvouch-command工作流将用户名追加到.github/VOUCHED.td代表外部贡献者创建 PR 的技能create-github-pr、build-from-issue应主动提示这一要求。沙箱日志规范OCSF 结构化事件 vs 普通 tracingAGENTS.md 中技术密度最高的部分是在openshell-sandbox中新增或修改日志时应遵循的决策框架。核心问题是该事件该用 OCSF 结构化日志还是普通tracing何时用 OCSF凡代表可被运维人员、安全团队或监控沙箱的 Agent 观察到的沙箱行为必须使用 OCSF builder ocsf_emit!()网络决策allow/deny/bypass 检测HTTP / L7 执行决策SSH 认证接受、拒绝、nonce 重放进程生命周期启动、退出、超时、信号失败安全发现不安全策略、不可用控制、重放攻击配置变更策略加载/重载、TLS 设置、provider 附加、设置变更应用生命周期supervisor 启动、SSH 服务器就绪何时用普通 tracing凡属内部运维管道plumbing、不构成安全决策或可观察状态变化的事件使用info!()/debug!()/warn!()gRPC 连接尝试与重试即将执行 X且结果另行记录的事件内部 SSH 通道状态未知通道、PTY 尺寸变更僵尸进程回收、denial flush 遥测DEBUG/TRACE 级诊断OCSF 事件类选择表事件类型Builder适用场景TCP 连接、代理隧道、绕过NetworkActivityBuilderL4 网络决策、代理运维事件HTTP 请求、L7 执行HttpActivityBuilder按请求的 method/path 决策SSH 会话SshActivityBuilder认证、通道操作进程启停ProcessActivityBuilder入口点生命周期、信号失败安全告警DetectionFindingBuildernonce 重放、绕过检测、不安全策略。须与域事件双发dual-emit策略/配置变更ConfigStateChangeBuilder策略加载、Landlock 应用、TLS 设置、provider 附加、设置变更supervisor 生命周期AppLifecycleBuilder沙箱启动、SSH 服务器就绪/失败严重级别指南级别时机Informational允许的连接、成功操作、配置已加载LowDNS 失败、非致命运维告警、LOG 规则失败Medium拒绝的连接、策略违规、废弃配置High安全发现nonce 重放、Landlock 不可用Critical进程超时被杀死完整示例新增一个网络事件use openshell_ocsf::{ ocsf_emit, NetworkActivityBuilder, ActivityId, ActionId, DispositionId, Endpoint, Process, SeverityId, StatusId, }; let event NetworkActivityBuilder::new(crate::ocsf_ctx()) .activity(ActivityId::Open) .action(ActionId::Denied) .disposition(DispositionId::Blocked) .severity(SeverityId::Medium) .status(StatusId::Failure) .dst_endpoint(Endpoint::from_domain(host, port)) .actor_process(Process::new(binary, pid)) .firewall_rule(policy_name, engine_type) .message(format!(CONNECT denied {host}:{port})) .build(); ocsf_emit!(event);实现层面的关键要点crate::ocsf_ctx()返回进程级EventContext始终可用测试中回退到默认值ocsf_emit!()非阻塞且不会 panic——事件先存入线程局部thread-local再经tracing::info!()发出shorthand 层与 JSONL 层从线程局部取出事件shorthand 格式由 builder 字段自动派生安全发现必须双发同一事件同时发一个域事件如SshActivityBuilder与一个DetectionFindingBuilder绝不在 OCSF 消息中记录密钥、凭据或查询参数——OCSF JSONL 文件可能被送往外部系统message字段应是简洁、便于 grep 的摘要细节放 builder 字段dst_endpoint、firewall_rule等。源码佐证实现层面crates/openshell-ocsf/src/lib.rs 明确实现 OCSFv1.8.0常量OCSF_VERSION: str 1.8.0提供 8 个事件类Network/HTTP/SSH/Process Activity、Detection Finding、Application Lifecycle、Device Config State Change、Base Event、类型化枚举与对象、按类定制的 builder、双格式化器format_shorthand()与to_json()/to_json_line()、两个 tracing layerOcsfShorthandLayer、OcsfJsonlLayer以及ocsf_emit!宏。实际调用点遍布沙箱运行时。例如 crates/openshell-sandbox/src/sandbox/linux/landlock.rs 在 Landlock 不可用且compatibility为BestEffort时用DetectionFindingBuilder以SeverityId::High、ConfidenceId::High、is_alert(true)双发式上报landlock-unavailable并提示Set landlock.compatibility to hard_requirement to make this fatal随后应用 Landlock 时又以ConfigStateChangeBuilder发出Informational级、StateId::Enabled的配置变更事件同文件 L289-L299。进程侧则由 crates/openshell-sandbox/src/process.rs 的ProcessActivityBuilder记录入口点生命周期网络/SSH/生命周期事件散布于 crates/openshell-sandbox/src/boundary_server.rs 与 crates/openshell-sandbox/src/sandbox/mod.rs 等文件。这些调用点与本文档的选择表一一对应是判断该事件应走 OCSF 还是普通 tracing的最佳学习样本。网络套接字优化对延迟敏感 TCP 流禁用 Nagle对延迟敏感的 TCP 流必须禁用 Nagle 算法避免小请求/响应帧被延迟 ACKdelayed ACK卡住。统一的入口在共享核心 crate对已 accept 或已连接的流openshell_core::net::set_tcp_nodelay_best_effort拨号连接时openshell_core::net::connect_tcp_nodelay_best_effort三条约束值得注意loopback/localhost TCP 同样适用——delayed-ACK 停滞是定时器行为而非线路延迟回环连接也会踩坑Unix domain socket 应跳过——UDS 没有 Nagle 概念对仅用于测试的连接非强制但任何非 UDS 的 TCP 流测试亦然使用该函数是首选做法。源码层面crates/openshell-core/src/net.rs 中set_tcp_nodelay_best_effort在失败时仅tracing::debug!记录并继续best effort语义连接仍可用只是稍慢connect_tcp_nodelay_best_effort先TcpStream::connect再设置且文档明确返回的流不保证已设置 TCP_NODELAY。同一文件还实现了 IP 分类辅助函数is_always_blocked_ip、is_internal_ip、is_known_metadata_hostname等用于沙箱代理的 SSRF 强制与机制映射器属于同一网络硬化主题。提交、测试与工具链约定提交规范一律使用 Conventional Commits 格式type(scope): descriptionscope 可选常用 typefeat、fix、docs、chore、refactor、test、ci、perf每个提交都须--signoff以满足 DCOSigned-off-by页脚使用用户配置的邮箱提交信息中绝不提及 Claude 或任何 AI Agent——不署名、不写 Co-Authored-By、不在消息中引用。本地质量门命令用途mise run pre-commitLint、格式化、license 头检查每次提交前运行本地可装钩子mise generate git-pre-commit --write --taskpre-commitmise run test单元测试套件代码变更后运行mise run e2e针对运行中网关的端到端测试基础设施/沙箱/策略变更后运行mise run ci完整本地 CIlint 编译/类型检查 测试开 PR 前运行SDK 与语言约定Go SDKsdk/go/模块路径github.com/NVIDIA/OpenShell/sdk/gomise run go:ci跑完整 CIlint、build、test、proto-check、docs-checkprotobuf 绑定由mise run go:proto:gen从 proto/ 生成sdk/go/openshell/v1/types/中的域类型不得导入 proto 包sdk/go/openshell/v1/internal/converter/在边界深拷贝切片与 map测试用 bufconn 做进程内 gRPC testify 断言TypeScript SDKsdk/typescript/mise run sdk:ts:ci覆盖代码生成、proto lint、Biome lint、类型检查、单元测试、覆盖率与构建验证protobuf 绑定由mise run sdk:ts:proto按 sdk/typescript/buf.gen.yaml 生成sdk/typescript/src/gen/下文件是构建产物不得提交精选 API 不得暴露生成的 wire 类型完整消息与 RPC 通过nvidia/openshell-sdk/raw提供Python一律用uvuv pip install、uv run、uv venvDocker一律优先mise命令而非直接docker build如mise run docker:build。文档与技能维护的联动约束OpenShell 把行为变更与文档/技能更新绑定为同一变更的组成部分基础设施变更改动网关部署基础设施Helm values/templates、网关镜像打包、openshell-cli部署逻辑后须同步更新 skills/debug-openshell-cluster/SKILL.md技能维护行为、命令或开发工作流变化时审查同分支相关技能用sync-agent-infra技能获取维护映射并做一致性检查文档改动更新 architecture/影响用户可见行为的更新 docs/ 相应页面及 docs/index.yml 导航改动网关 TOML 字段、驱动配置项、配置默认值或 Helm 渲染的gateway.toml时同分支更新 docs/reference/gateway-config.mdxfern/ 含站点配置、预览工作流输入与发布设置详见 fern/README.md风格规范遵循 docs/CONTRIBUTING.mdx主动语态、最小化格式、无填充式引言、可复制命令用shell代码块、不重复正文 H1发布管道Fern PR 预览走.github/workflows/branch-docs.ymlRelease Dev 发布devRelease Tag 发布不可变稳定版加latest两条生产路径都调用一次.github/workflows/sync-docs.yml文档草稿用update-docs-from-commits技能扫描近期提交并起草文档更新。架构文档的写作纪律架构文档architecture/是简短权威的子系统概览而非穷尽式实现笔记新增文件前先更新现有顶层文档之一crate 级细节放相应 crate 的README.md仅在明确请求或 RFC 级设计需要稳定归属时新增顶层文档聚焦稳定边界、数据/控制流、不变量与运维约束默认删除过时细节而非保留不写测试记录、历史调试笔记、长源码清单或逐字段 schema 引用用户面向内容放 docs/宽泛设计提案放 rfc/临时计划放被 git 忽略的architecture/plans/该目录对人类更易访问只有当你没有其他特定落点时才用它计划文档直接写在那里、无需询问位置。安全红线绝不提交密钥、API key 或凭据疑似含敏感信息的文件.env、credentials.json等不暂存不做破坏性操作force push、hard reset、删库除非有明确的人工确认范围控制改动限定于当前 issue不在同一分支做无关变更。结语这套规范对 Agent 与人类的双重意义AGENTS.md 本质上是 OpenShell以 Agent 构建 Agent 运行时这一理念的可执行化它用agent:*标签与生命周期状态机把人类决策权显式保留接受、路线图、安全审查、背书同时用技能链、模板与标签协议把可自动化的工作triage、spike、实现、文档同步、日志规范、提交规范交给 Agent 自主完成。对贡献者而言阅读本指南后可立即上手四件事按工作流链和标签协议定位自己应处的阶段、按 CONTRIBUTING.md 找到完整技能表、在沙箱日志改动中按 OCSF 事件类与严重级别表做正确取舍、并严格遵守提交/安全红线——这正是 AGENTS.md 每次注入到 Agent 上下文中希望达成的效果。赞分享【免费下载链接】OpenShellOpenShell is the safe, private runtime for autonomous AI agents.项目地址https://gitcode.com/gh_mirrors/op/OpenShell点击查看免费下载相关推荐urql 文件上传实战基于 GraphQL Multipart Request 规范的 File Upload 指南urql 文件上传实战基于 GraphQL Multipart Request 规范的 File Upload 指南 导读 本指南围绕 examples/wi前端Cytoscape.js 开发指南AGENTS.md面向 AI Agent 的贡献者工作流、仓库架构与工程规范解析Cytoscape.js 开发指南AGENTS.md面向 AI Agent 的贡献者工作流、仓库架构与工程规范解析 导读 本文以仓库根目录下的 AGENT数据可视化std::expected()与std::unexpected()TypePHP新式错误处理指南std::expected 与std::unexpected TypePHP新式错误处理指南 TypePHP 是一个将 PHP 编译为原生二进制 的 AOT编译器开发工具编程语言上一篇WeChatMsg 一键把微信聊天记录导出成 HTML、Word、CSV还能生成年度聊天报告下一篇探索Neovim Lua调试新纪元one-small-step-for-vimkind创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考