【免费下载链接】OpenShellOpenShell is the safe, private runtime for autonomous AI agents.项目地址https://gitcode.com/gh_mirrors/op/OpenShell点击查看免费下载导读create-spike是 OpenShell 仓库内建的一套 Agent 技能位于 .agents/skills/create-spike/SKILL.md它的职责是把用户一句模糊的想法——新功能、疑似 Bug、性能疑虑、重构诉求——通过一次深度代码库调研映射为结构化的 GitHub Issue并给出可供人类评审的可行性结论与风险清单。读完本文你将掌握这套 spike探索性调研工作流的完整五步操作问题陈述提炼、principal-engineer-reviewer 深度调查、标签决策、结构化 Issue 创建与用户汇报并理解它与triage-issue、build-from-issue在 OpenShell 贡献流程中的衔接关系。Spike 是什么探索性调研的定位原文档对 spike 的定义非常明确Aspikeis an exploratory investigation. The user has a vague idea — a feature they want, a bug theyve noticed, a performance concern — but hasnt mapped it to code, assessed feasibility, or structured it as a buildable issue. This skill does that mapping.也就是说spike 解决的不是怎么写代码而是在动手之前把问题域摸清楚用户想做什么期望的结果或观察到的现象为什么想做动机、用例、触发点有哪些约束向后兼容、性能目标等。spike 的产出物是一份结构化的 GitHub Issue而不是实现方案。它把模糊想法映射为可构建的 Issue等待人来裁决与排期——这也是为什么它在技能元数据中被标注为build-from-issue的prequel前奏。在 AGENTS.md 的工作流链中可以看到它的正式位置社区流入triage-issue→ 人工裁决与排期 →必要时create-spike→build-from-issue内部开发create-spike→ 人工裁决与排期 →build-from-issue。spike 完成后将 Issue 标记为state:validated证据足以支撑人的接受/拒绝决策再由人来决定是否接受、是否纳入路线图只有接受之后build-from-issue才会接手编写实现计划。Spike 不做实现计划这是它与后续技能的根本分工。前置条件运行该技能前需要满足两个环境前提技能文档中明确列出ghCLI 必须已通过认证可用gh auth status校验当前必须位于一个带 GitHub remote 的 git 仓库中。这两条前提与仓库内其他 Issue 类技能如 .agents/skills/create-github-issue/SKILL.md一致因为整个贡献流程都依赖gh命令行工具与 GitHub 作为载体。工作流总览五步闭环技能文档给出如下流程示意User describes a problem │ ├─ Step 1: Gather the problem statement │ └─ Ask ONE round of clarifying questions if genuinely needed │ ├─ Step 2: Deep codebase investigation via principal-engineer-reviewer │ └─ Map the problem to code, assess feasibility, identify risks │ ├─ Step 3: Determine labels from the repo │ ├─ Step 4: Create a GitHub issue with structured findings │ └─ Step 5: Report to user with issue URL and next steps下面逐一展开每个步骤的实操要点。Step 1收集问题陈述用户的描述可能来自多种形态原文档给出四类典型输入功能想法我希望沙箱能够访问私有 IPBug 报告代理的重试逻辑似乎太激进了性能疑虑大型规则集下策略评估很慢重构目标配置解析分散在太多模块中。无论输入形态如何都需要从用户输入中提炼三要素What—— 他们想要什么期望结果或观察到的问题Why—— 为什么动机、用例或触发点Constraints—— 他们提到的约束向后兼容、性能目标等。澄清政策最多问一轮技能对追问采取克制态度核心原则是不要过度盘问Do not over-interrogate。判定标准以能否确定要调研的代码区域为准需要追问的例子让事情更快 —— 追问是哪个组件、哪个操作慢修复网络问题 —— 追问具体哪个行为不对。不需要追问的例子信息已足够直接开查代理的重试逻辑太激进了允许沙箱 egress 到私有 IP 空间OPA 策略评估需要缓存。这个一轮澄清上限也被列为技能的六条设计原则之一如果用户提供的信息足以定位代码区域就立刻开始调查不要把 spike 变成审讯。Step 2深度代码库调查核心步骤这是整个技能的核心。技能要求通过 Task 工具调用principal-engineer-reviewer子代理执行调查Task tool with subagent_typeprincipal-engineer-reviewer给评审子代理的调查指令12 项要求原文档明确要求传给评审者的 prompt必须包含以下指令每一项都是在 OpenShell 这类大型 Rust 工作区中做可行性调研的黄金准则确认涉及哪些组件/子系统—— 不能只凭名字猜测要读代码确认通读相关源文件—— 不只是 grep 关键词要真正阅读并理解逻辑从入口点一路追到相关行为的调用链绘制受影响区域的当前架构—— 组件如何交互、数据流如何流动、边界在哪里定位需要变更的确切代码路径—— 给出文件路径与行号点名函数、结构体与模块评估可行性与复杂度Low低孤立改动少于 3 个文件路径清晰Medium中涉及多个文件/组件有一些设计决策但范围可控High高跨切面改动需要架构决策存在显著未知项识别风险、边界情况与需要人类输入的设计决策—— 哪里可能出错、有什么权衡、哪些决策不该由 Agent 拍板检查代码库中应遵循的既有模式—— 如果相似功能已有实现惯例要指出来保证实现风格一致查看相关测试以理解测试覆盖预期—— 该区域有哪些测试模式、期望什么级别的覆盖查阅architecture/目录下的架构文档—— 了解受影响子系统的官方设计说明评估 gateway 配置文档影响—— 若改动会新增、删除、重命名或改变 gateway TOML 键或驱动专属配置选项的默认值必须点名 docs/reference/gateway-config.mdx 需要同步更新若改动经由 Helm 或 compute-driver 部署文档呈现也要点名相关部署文档评估 Linux 安全模块LSM影响—— 若改动涉及进程身份、/proc文件系统访问、文件标记、二进制执行或进程间可见性要判断在 SELinuxenforcing或 AppArmor 主机上行为是否不同。文档给出了一个非常具体的例子跨 SELinux 域边界读取/proc/pid/exe返回的是ENOENT而非EACCES在 enforcing 主机上forkexec 系统二进制不同 SELinux 标签的测试会失败。凡是涉及 LSM 敏感的代码路径都要标记并建议缓解措施判定 Issue 类型feat、fix、refactor、chore、perf或docs。好的调查 prompt 应包含什么技能文档建议传给评审者的 prompt 要包含用户的原始问题陈述逐字或轻度改写用户提到的约束明确的返回要求组件清单、带行号的文件引用、架构摘要、可行性评估、风险与 Issue 类型。拿到结果后怎么办评审者返回的分析将直接用于填充 Issue 正文Step 4。Issue 必须同时包含面向干系人可读的摘要与完整的技术调查两者放在同一处。与仓库实际的印证示例中的调查路径是真实存在的技能文档自带的 feature spike 示例中评审者对允许沙箱访问私有 IP的调查线索SSRF 检查、OPA 管道、protobuf 定义、四层防御模型在仓库源码中都能找到真实对应这恰好说明该技能设计的调查方法贴合项目实际SSRF 检查is_internal_ip()实现在 crates/openshell-core/src/net.rs其文档注释明确写着它Used by the proxys default SSRF path被代理的默认 SSRF 路径使用。函数覆盖 IPv4 的 loopback、RFC 1918 私有段、link-local、unspecified、文档地址段以及 IPv6 的 loopback、ULAfc00::/7、IPv4-mapped IPv6 映射检查同文件还提供is_internal_net()供 CIDR 网段层面的判断代理与 OPA 管道代理实现位于 crates/openshell-supervisor-network/src/proxy.rsOPA 策略引擎位于 crates/openshell-supervisor-network/src/opa.rsprotobuf 定义proto/sandbox.proto 中定义了沙箱相关的服务契约四层防御模型与架构文档architecture/security-policy.md 描述了网络流量决策顺序——先强制走代理、再识别调用二进制身份、拒绝硬阻断目标含默认不允许的内部 IP 段、匹配网络策略、应用 L7 规则、最终按策略放行/拒绝/审计/记录显式 deny 与加固检查优先于 allow 规则无规则匹配则默认拒绝。这种示例中的调查线索与仓库真实实现一一对应的一致性让技能的产出天然具有可验证性——调查者依据的是真实代码而非猜测。Step 3确定标签从仓库拉取可用标签列表gh label list --limit 100技能文档给出明确的标签决策规则这也是 OpenShell 治理体系见 AGENTS.md 的 Issue and PR Conventions在标签层面的落点不加 Issue 类型标签—— GitHub 内置的 issue 类型Bug/Feature/Task来自 issue 模板或人工后续处理不用标签模拟加 area 标签若仓库中存在例如area:sandbox、area:proxy、area:policy、area:cli绝不发明标签—— 只用仓库中已存在的标签加state:validated的前提证据足以支撑人工裁决——spike 已形成连贯的问题或提案并完成了人类做 yes/no 决策所需的全部事实评估改为加state:needs-info当关键证据缺失时——需在 Issue 正文中明确指出还缺哪些证据、复现细节或决策输入永不添加state:accepted、任何agent:*标签或roadmap标签 —— 接受、排期、请求 Agent 干活都必须由人类决定。这与 .agents/skills/triage-issue/SKILL.md 中disposition and roadmap placement are human-only裁决与排期仅限人类的核心约束完全一致且 OpenShell 没有priority:*标签排序只能通过路线图关联表达。Step 4创建结构化 GitHub Issue创建 Issue 时标题遵循 conventional commit 格式正文同时包含干系人可读摘要与完整技术调查。技能文档给出了可直接复制的完整命令与模板gh issue create \ --title type: concise description of the problem/feature \ --label area:component --label state:validated|state:needs-info \ --body $(cat EOF ## Problem Statement What and why — refined from the users description. 2-4 sentences. Written for stakeholders, not just engineers. ## Technical Context What the investigation found about the current architecture in the affected area. How things work today and why a change is needed. ## Affected Components | Component | Key Files | Role | |-----------|-----------|------| | component | file1, file2 | what this component does in the context of this change | | ... | ... | ... | ## Technical Investigation ### Architecture Overview How the affected subsystems work today. Include data flow, component interactions, and relevant design decisions. Reference architecture docs if applicable. ### Code References | Location | Description | |----------|-------------| | file:line | what this code does and why its relevant | | file:line | what this code does and why its relevant | | ... | ... | ### Current Behavior What happens today in the code paths that would change. Be specific — name functions, trace the flow. ### What Would Need to Change Detailed breakdown of modifications needed, organized by component. Include specific functions and structs, but stop short of writing an implementation plan — thats build-from-issues job. ### Alternative Approaches Considered If the investigation surfaced multiple viable approaches, describe them and note trade-offs. Flag which decisions need human input. ### Patterns to Follow Existing patterns in the codebase that the implementation should be consistent with. Reference specific examples. ## Proposed Approach High-level strategy — NOT a full implementation plan. Thats build-from-issues job. Describe the direction, not the steps. 3-6 sentences. ## Scope Assessment - **Complexity:** Low / Medium / High - **Confidence:** High — clear path / Medium — some unknowns / Low — needs discussion - **Estimated files to change:** count - **Issue type:** feat|fix|refactor|chore|perf|docs ## Risks Open Questions - risk or unknown that needs human judgment - design decision that could go either way - ... ## Disposition Readiness - **State:** state:validated|state:needs-info - **Assessment:** why the available evidence is or is not sufficient for a human accept/decline decision - **Missing evidence:** specific evidence still needed, or None ## Test Considerations - what testing strategy makes sense for this change - which test levels are needed: unit, integration, e2e - any test infrastructure that may need to be added - what tests exist for the affected area today, what patterns should be followed, any test infrastructure gaps --- *Created by spike investigation. state:validated means the issue is ready for human disposition; state:needs-info means specific evidence is still required. A human applies state:accepted or places the issue on the roadmap if OpenShell should pursue the work. To queue unattended agent planning, a human applies agent:plan-requested; on a direct request, the agent warns about missing expected workflow labels and continues without changing them.* EOF )模板中的几个小节在 AGENTS.md 的 Issue 规范中都能找到呼应bug 与 feature 报告必须包含 User Story、Problem Statement、Impact / Why This Matters、Acceptance Criteriafeature 还必须包含 Proposed Design 与 Alternatives Considered——spike 模板用一套更偏工程的章节Technical Investigation、Code References、Scope Assessment承载了同样的事实完整性要求同时把改动建议限定在组件与函数层面明确stop short of writing an implementation plan。两个硬性约束不要在 Issue 上追加后续评论所有发现必须一次性包含在 Issue 正文中展示 Issue URL便于点击Created issue [#number](https://github.com/OWNER/REPO/issues/number)Step 5向用户汇报Issue 创建完成后向用户汇报四项内容Issue URL可点击的 markdown 链接23 句调查结论摘要需要人类关注的关键风险或决策下一步指引分为两种状态分支state:validated时请评审该 Issue 并决定 OpenShell 是否推进。若推进应用state:accepted、将其关联到路线图项或两者都做——任一操作都记录接受关联路线图还额外记录排序。工作可保持人工主导。可应用agent:plan-requested为无人值守 Agent 排队规划或直接请 Agent 使用build-from-issue在直接请求场景下Agent 会警告缺失的预期工作流标签并继续执行而不改动它们。若不推进则将其以 not planned 关闭并记录理由。state:needs-info时收集 Issue 中指出的缺失证据暂不纳入路线图。一旦证据充分将state:needs-info替换为state:validated以等待人工裁决。六条设计原则技能文档在末尾总结的设计原则是整个 spike 方法论的浓缩值得逐条理解一切都在 Issue 正文中—— 不追加后续评论正文同时承载面向干系人的摘要与完整技术调查不做实现计划—— spike 界定问题空间并提出方向实现计划是build-from-issue在人工评审后的职责最多一轮澄清—— 信息足够定位代码区域就立即开始调查Issue 应为build-from-issue节省工作量—— 后续技能以 Issue 正文为输入上下文技术调查部分必须足够详细使其principal-engineer-reviewer能基于调查继续推进而非从零开始交叉引用build-from-issue—— 在 Issue 正文脚注中将其标注为自然的下一步把 validation 当作证据阈值而非 spike 的自动产出—— 只有证据足以支撑人类接受/拒绝决策时才标记state:validated否则标记state:needs-info、说明缺什么并让 Issue 留在路线图之外。这条证据阈值设计原则与 .agents/skills/triage-issue/SKILL.md 的分类逻辑validated-bug / validated-feature / needs-investigation / needs-information 等同构两者都坚持Agent 建立事实人类做决策的边界spike 与 triage 都不授权工作、不排期、不产出实现计划。命令速查表技能文档提供了一份常用命令参考覆盖 spike 全流程的日常操作命令说明gh issue create --title ... --body ... --label ...创建新 Issuegh label list --limit 100列出仓库可用标签gh issue edit id --add-label ...为 Issue 添加标签gh issue view id --json number,title,body,state,labels拉取 Issue 元数据其中gh issue view与 triage 技能的 Step 1gh issue view id --json title,body,state,labels,author,comments用法一致说明这两个技能共享同一套gh命令基座。三个端到端示例技能文档提供了三个覆盖典型场景的完整示例展示从用户一句话到 Issue 落地的全过程。示例一功能 spike用户说Allow sandbox egress to private IP space via networking policy允许沙箱通过网络策略访问私有 IP 空间。问题清晰——无需澄清触发principal-engineer-reviewer调查在代理的 SSRF 检查中发现is_internal_ip()拦截 RFC 1918 地址对应仓库 crates/openshell-core/src/net.rs 的真实实现阅读 crates/openshell-supervisor-network/src/opa.rs 与沙箱策略 Rego 中的 OPA 策略评估管道阅读 proto/sandbox.proto 中NetworkEndpoint的 protobuf 定义绘制四层防御模型netns、seccomp、OPA、SSRF 检查对应 architecture/security-policy.md 的决策顺序描述阅读 architecture/security-policy.md 与 architecture/sandbox.md定位精确插入点策略字段新增、SSRF 检查绕过路径、OPA 规则扩展评估Medium 复杂度、High 置信度、约 6 个文件拉取标签——选择area:sandbox、area:proxy、area:policy、state:validated创建 Issuefeat: allow sandbox egress to private IP space via networking policy——正文同时包含摘要与完整调查代码引用、架构上下文、备选方案汇报Created issue #59. 调查发现私有 IP 拦截在代理的 SSRF 检查层强制执行。提议方案增加策略级覆盖开关。现在必须由人接受或拒绝接受则纳入路线图。示例二Bug 调查 spike用户说The proxy retry logic seems too aggressive — Im seeing cascading failures under load代理重试逻辑太激进负载下出现级联失败。问题足够清晰——调查代理中的重试行为触发principal-engineer-reviewer在代理请求处理中定位重试配置阅读重试循环、退避策略与超时设置检查是否存在熔断逻辑绘制失败传播路径发现重试没有退避抖动jitter导致惊群效应评估Low 复杂度、High 置信度、约 2 个文件拉取标签——选择area:proxy、state:validated创建 Issuefix: proxy retry logic causes cascading failures under load——正文包含摘要与完整调查重试代码引用、当前行为追踪、与标准退避模式的对比汇报Created issue #74. 代理在无抖动、无熔断的情况下重试放大了负载下的失败。现在必须由人接受或拒绝接受则纳入路线图。示例三性能/重构 spike用户说Policy evaluation is getting slow — can we cache compiled OPA policies?策略评估越来越慢能否缓存编译后的 OPA 策略。问题清晰——调查 OPA 策略评估性能触发principal-engineer-reviewer端到端阅读 OPA 评估管道测量策略在何处加载与编译每次请求 vs 缓存检查是否已有缓存层阅读策略重载/热切换机制发现策略每次评估都重新编译评估Medium 复杂度、Medium 置信度缓存失效是设计决策、约 4 个文件拉取标签——选择area:policy、state:validated创建 Issueperf: cache compiled OPA policies to reduce evaluation latency——正文包含摘要与完整调查编译热路径、每次请求开销、带权衡的缓存失效策略汇报Created issue #81. 策略每次请求都重新编译且无缓存。主要设计决策是缓存失效策略。现在必须由人接受或拒绝接受则纳入路线图。三个示例共同演示了复杂度评估Low/Medium与置信度评估High/Medium如何随问题形态变化局部重试问题最轻量跨层的网络策略改动与性能缓存问题都需要设计决策因此被如实标注出来交给人类。与相邻技能的边界要正确使用 spike必须清楚它在 OpenShell 贡献流水线中的上下游Community issue filed | [GitHub Action: instant gate check] | triage-issue | state:validated | human decline OR state:accepted / roadmap placement | create-spike (if deeper investigation is approved) | human queues planning with agent:plan-requested OR directly requests planning | build-from-issue (creates implementation plan) | human queues implementation with agent:implementation-requested OR directly requests implementation | implementation各层职责源自 .agents/skills/triage-issue/SKILL.md 的 Relationship to Other Skills 一节triage-issue建立技术有效性与影响证据人类决定是否接受有效工作及其路线图位置create-spike仅在投入获得批准后深化调查build-from-issue可在特定 Issue 上被直接调用无人值守 Agent 用agent:plan-requested领取规划、用agent:implementation-requested领取实现。spike 是评估层之后的深化调查层它不排序、不接受、不规划、不构建——它的唯一使命是把问题域的事实整理到足以让人类做一次明确的是/否决策。小结把模糊想法变成可裁决事实的方法论create-spike本质上是一套问题→证据→裁决的工程化管道。它的核心价值在于三个坚持坚持读代码而非猜代码12 项调查指令、带行号的文件引用、从入口到行为的调用链追踪坚持证据阈值而非自动结论state:validated与state:needs-info的严格区分坚持人机边界Agent 建立事实人类做接受与排期决策。这套方法论与 OpenShell agent-first 的开发理念互为表里——项目用自己设计 Agent 工作流来驱动自身开发而 spike 正是其中把想法转化为可构建工作的第一道闸门。对于任何想在 OpenShell 上贡献功能、报告 Bug 或发起重构的开发者与 Agent 来说掌握这条工作流就等于掌握了进入项目正式开发管线的正确入口。赞分享【免费下载链接】OpenShellOpenShell is the safe, private runtime for autonomous AI agents.项目地址https://gitcode.com/gh_mirrors/op/OpenShell点击查看免费下载相关推荐OmX deep-interview用苏格拉底式提问与量化模糊度门控把模糊想法变成可执行规格OmX deep interview用苏格拉底式提问与量化模糊度门控把模糊想法变成可执行规格 导读 Deep Interview 是 OmXOh My c人工智能AI AgentAgent 编排Agent 工作流CLI开发工具AI 技能agentic-awesome-skills 之 Rex 分析师技能把模糊需求转成可执行规格说明agentic awesome skills 之 Rex 分析师技能把模糊需求转成可执行规格说明 导读 本篇文章围绕开源仓库 agentic awesomeAI 技能AI 插件Codewhale 维护者技能gh-file-issue 如何把“一条 Bug 发现”变成可执行、可验证、可归功的高质量 IssueCodewhale 维护者技能gh file issue 如何把“一条 Bug 发现”变成可执行、可验证、可归功的高质量 Issue 在 Codewhale人工智能AI Agent代码智能体CLI工具调用MCP Clients上一篇Socket.IO Cluster Engine 实战指南无需粘性会话的多进程横向扩展方案下一篇如何使用Sketchware Pro快速开发Java应用零基础入门教程创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
