JStack 是一个独立的开源 AI 工程工作流、插件套件、MCP 控制平面以及专业 AI 辅助软件交付的刻意练习系统。它为单个工程师或受监督的团队提供了一致的运行模型，涵盖了规划、实施、审查、测试、安全、发布准备、持久化目标循环以及多阶段程序。目前 Codex 是完全打包的宿主。Claude Code 可以作为预览集成连接到 JStack 基于标准的 stdio MCP 工具平面；宿生（host-native）命令和长时间运行的续作明确特定于宿主，而不是表现为功能等效。 ## 为什么选择 JStack AI 可以快速生成代码。生产工程仍然依赖于范围控制、独立检查、可重现的证据和负责任的决策。JStack 将这些控制显式化。 | 常见故障模式 | JStack 控制 | | --- | --- | | Prompt 偏离实际目标 | 版本化的目标契约、非目标、策略底线和精确摘要确认 | | “测试通过”仅停留在口头描述 | 将 QA 和安全凭证绑定到精确的 Git 修订版、工作区、策略和命令 | | 多个代理发生冲突或重复工作 | 角色权限、写入范围、协调数据包和受控调度波次 | | 长时间任务丢失上下文或永远循环 | 持久化状态、受限迭代、租约、断路器和明确的停止条件 | | 大型项目被硬编码到一个巨大的 prompt 中 | 项目定义的 Program -> Phase 依赖图，带有独立验证的子目标 | | 发布信心变成发布许可 | 故障关闭（fail-closed）的就绪检查，加上用于提交、推送、部署和发布的独立人类权威 | ## 运行模式 选择适合工作的最小运行模式。命令具有权威性；JStack 从不悄悄增加人员配置。 | 命令 | 运行模型 | 最佳适用场景 | | --- | --- | --- | | `/j-stack-dev` | 一名首席工程师，无子代理 | 专注的实现、调试、维护和受限的发布 | | `/jstack-subagents` | 首席加上通常两到三名专家 | 受益于针对性安全、测试、架构或领域审查的跨领域工作 | | 需要全功能覆盖的高风险、广泛或发布关键的更改 | `/jstack-full-team` | 在受控波次中调度的十一个专业角色 | | `/jstack-loop` | 由一个选定的交付模式组成的受限持久目标循环 | 需要在多轮对话、人类批准、外部等待或多个阶段中进行验证迭代的工作 | | `/jstack-audit` | 独立的只读检查 | 受证据约束的正确性、安全性、架构、可维护性、性能和发布审查 | `/jstack-loop ` 默认使用单一主管交付。当明确需要该人员配置时，请在同一请求中声明 `use JStack Subagents` 或 `use JStack Full Team`。审查保持独立的检查边界，不编辑项目代码。 ## 工作原理 ``` flowchart LR A[Goal and context] --> B[Readiness and policy] B --> C[Selected delivery mode] C --> D[QA, security, review, and audit evidence] D --> E{Acceptance contract met?} E -- No --> F[Bounded revision or human gate] F --> C E -- Yes --> G[Completion receipt] G --> H[Separate human release authority] ``` JStack 分离了普通 prompt 倾向于混淆的四个关注点： 1. **意图**：确认目标、上下文、非目标、风险、范围和验收合同。 2. **执行**：选择规模合适的交付模式并限制谁可以更改什么。 3. **证据**：将测试、安全覆盖、审查、批准和输出绑定到当前项目状态。 4. **权限**：报告已验证的完成，但不将其视为提交、推送、部署或发布的许可。 ## v0.5 中发布的内容 | 能力 | 提供的内容 | | --- | --- | | 交付控制 | 规划、预检、健康、策略、团队调度、确定性审查和发布就绪工具 | | 证据平面 | 会话签名的 QA 和安全凭证、完整的覆盖检查、Git 状态绑定和残留风险报告 | | 审计系统 | 具有确定性最终确定和 SARIF 输出的只读快速、标准、深度和发布配置 | | 目标循环 | 版本化契约、私有原子状态、每个检出一次写入租约、断路器、检查点、修订和终结凭证 | | 程序编排 | 阶段数无关的依赖图、子目标证明、人类和外部门控、暂停感知预算、失效、恢复和最终集成证据 | | 团队协调 | 单一主管、专家团队和完整团队模式，具有经过验证的角色、权限、范围和受控波次 | | 精通系统 | 独立的十阶段工程、审计和循环工程课程，包含制品、协助上限、重复尝试和盲评顶点项目 | | 分发 | 五个专用命令插件、一个可选的伞形插件、一个独立的 MCP 服务器、事务性安装程序和跨平台 CI | 除了交付、证据、审计、循环、连续性、专家审查和掌握工具系列之外，MCP 目前还公开了 14 个规范的 `jstack_program_*` 工具，用于通用程序编排。旧的 `gstack_*` 别名仍可用于兼容。 ## 宿主兼容性 JStack 将其可移植的 MCP 控制平面与特定于宿主的命令和延续界面分开。 | 宿主 | 状态 | 目前可用 | | --- | --- | --- | | Codex Desktop 和 Codex CLI | 完全支持 | 五个命令插件、技能、prompt、MCP 工具、子代理工作流和原生 Goal 组合 | | Claude Code | MCP 预览版 | 手动本地 stdio MCP 连接到完整的 `jstack_*` 工具库；Claude 原生命令打包和延续对等性尚未发布 | | 其他支持 MCP 的编程代理 | 协议级别 | 可以手动连接 JSONL stdio 服务器，但未列出的宿主未经过发布测试或声明为受支持 | 只要 MCP 协议允许，控制平面就与模型无关。质量声明刻意范围更窄：只有当宿主的安装、命令、权限、延续语义和证据流被 JStack 的发布测试覆盖时，该宿主才受到完全支持。 ## 快速开始 ### 前置要求 - 适用于完全打包工作流的 Codex Desktop 或 Codex CLI - 适用于可选 MCP 预览版的 Claude Code - 适用于绑定提交证据和发布控制的 Git - Python 3.9 或更新版本 - macOS、Linux 或 Windows ### 1. 克隆 ``` git clone https://github.com/JarodFroneman/jstack.git cd jstack ``` ### 2. 验证 ``` python3 scripts/sync_artifacts.py --check python3 -m unittest discover -s tests -v python3 mcp/jstack/smoke_test.py ``` 在 Windows 上，如果需要，请将 `python3` 替换为 `python`。 ### 3. 在 Codex 中安装 对于最简单的事务性安装： ``` python3 scripts/install.py ``` PowerShell： ``` .\scripts\install.ps1 ``` 安装程序会暂存完整的 payload，更新 Codex MCP 配置，并在后续安装阶段失败时恢复先前的目标。 ### 4. 重启并验证 重启 Codex 或打开一个新任务，然后确认 JStack 命令和 `jstack_*` MCP 工具可用。在验证受管环境时，运行已安装的 MCP 冒烟测试。 有关干净的五插件命令布局、自定义 `CODEX_HOME` 位置、Claude Code MCP 预览、升级、回滚和重复命令预防，请阅读[安装指南](docs/installation.md)。 ## 架构 ``` flowchart TB U[AI coding-agent operator] --> H[Host command or MCP integration] H --> M[JStack MCP control plane] M --> P[Policy and project binding] M --> D[Delivery and team coordination] M --> E[QA, security, audit, and release evidence] M --> L[Bounded goal loops] M --> R[Program and phase orchestration] M --> T[Mastery and continuity] P --> G[(Git project state)] D --> G E --> G L --> X[(Private ~/.jstack state)] R --> X ``` 规范的 MCP 实现位于 [`mcp/jstack/jstack_mcp_server.py`](mcp/jstack/jstack_mcp_server.py)。在发布之前，会检查生成的插件副本是否存在偏差、BOM、版本不匹配和缺失的制品。 ### 控制层 - **项目绑定** 区分由 Git 支持的工作区和仅限制品的工作区。 - **策略** 定义不可覆盖的底线、受信任的命令、受保护的路径和发布要求。 - **交付** 负责计划、人员配置、权限、范围和实施。 - **证据** 负责当前的 QA、安全、审计、输出和批准证明。 - **循环** 负责一个受限的 Phase -> Iteration 收敛契约。 - **程序** 负责位于受限子循环之上的、由项目定义的 Program -> Phase 依赖图。 阅读 [ARCHITECTURE.md](ARCHITECTURE.md) 以获取完整的组件和信任模型。 ## 证据和发布模型 当所需的证据缺失、过时、不完整或绑定到不同的项目状态时，JStack 的发布路径会失败关闭。根据策略，发布门控可能需要： - 明确的发布前基准和干净的已提交候选版本； - 完整的已提交、暂存、未暂存和未跟踪的更改证据； - 当前的 QA、安全、确定性审查和审计凭证； - 完整的当前树和发布范围的密钥扫描； - 明确的外部批准、回滚、监控和冒烟测试参考； - 在任何实质性更改或下游失效后进行重新验证。 完成意味着验收合同已通过。它不授予受保护的操作权限。 ## 信任边界 - QA 运行器关闭 stdin，避免使用 shell，清理继承的变量，隔离 `HOME`，限制输出和时间，并杀死其进程组。项目代码仍以当前用户的文件系统和网络权限运行。 - 会话本地凭证减少了意外和调用方侧的证据篡改；它们无法防止同一操作系统帐户遭到入侵。 - `~/.jstack/` 下的循环和程序状态是私有的本地状态，而不是分布式锁或多租户安全边界。 - 签名的本地人类门控证明拥有已配置的密钥。它们不是企业身份、法律上的不可否认性或组织批准。 - 审计凭证证明了收集的范围、已验证的结构和结果计算。它们并不能使每个由模型生成的语义发现都成为事实。 - 仅限制品的项目可以使用规划和直接操作员证据，但无法接收绑定提交的 JStack 发布凭证。 对于不受信任的存储库，请使用容器、VM 或强化的执行宿主。在生产交付环境中采用 JStack 之前，请阅读 [SECURITY.md](SECURITY.md)。 ## 仓库地图 | 路径 | 用途 | | --- | --- | | [`mcp/jstack/`](mcp/jstack/) | 规范的 JSON-RPC 服务器、交付控制、审计、循环、程序、schema、课程和模板 | | [`skills/`](skills/) | 规范的单一主管、审计和循环技能 | | [`prompts/`](prompts/) | 规范的斜杠命令 prompt | | [`plugins/`](plugins/) | 五个专用命令插件 | | [`plugin/`](plugin/) | 带有可移植启动器的可选一体化插件 | | [`mastery/`](mastery/) | 工程、审计和循环课程 | | [`tests/`](tests/) | 单元、传输、对抗、发布、掌握、安装和编排测试 | | [`docs/`](docs/) | 操作模型、协议、迁移指南和架构决策 | | [`jstack.enterprise.json`](jstack.enterprise.json) | 此存储库的可执行 JStack 策略 | ## 开发与验证 ``` python3 scripts/sync_artifacts.py --write python3 scripts/sync_artifacts.py --check python3 -m compileall -q mcp scripts tests python3 -m unittest discover -s tests -v python3 mcp/jstack/smoke_test.py ``` CI 使用 Python 3.9 和 3.12 在 Ubuntu、macOS 和 Windows 上运行相同的发布关键检查。当前版本包含 148 个通过的单元和对抗测试。 ## 文档 | 从这里开始 | 深入了解 | | --- | --- | | [安装和宿主兼容性](docs/installation.md) | [架构](ARCHITECTURE.md) | | [企业工作流](docs/enterprise-workflow.md) | [代理协调协议](docs/agent-coordination-protocol.md) | | [团队运营模型](docs/team-operating-model.md) | [审计系统](docs/audit-system.md) | | [循环系统](docs/loop-system.md) | [程序系统](docs/program-system.md) | | [工程精通](docs/mastery-system.md) | [循环精通](docs/loop-mastery-system.md) | | [v0.5 迁移指南](docs/migration-0.5.md) | [架构决策](docs/adr/) | ## 治理 - 通过 [SECURITY.md](SECURITY.md) 报告安全问题。 - 在提议更改之前阅读 [CONTRIBUTING.md](CONTRIBUTING.md)。 - 在 [CHANGELOG.md](CHANGELOG.md) 和 [GitHub Releases](https://github.com/JarodFroneman/jstack/releases) 中查看发布历史。 - JStack 在 [MIT 许可证](LICENSE) 下分发。 ## 与 gstack 的关系 Stack 是一个独立的项目。上游的 gstack 可以提供可选的额外技能，但它不是运行时依赖项，任何 JStack 工作流都不需要它。

信心之前，先有证据。

由 Jay Froneman 创建并维护。

标签：网络安全研究, 逆向工具