Traverse

[](https://enricopiovesan.com/) # Traverse [](https://github.com/enricopiovesan/Traverse/actions/workflows/ci.yml) [](https://github.com/enricopiovesan/Traverse/actions/workflows/ci.yml) [](LICENSE) [](https://www.rust-lang.org/) [](https://github.com/enricopiovesan/Traverse/releases) 您的业务逻辑在浏览器、服务器和云函数中运行。 它们漂移，您需要维护三个相同行为的版本。 Traverse 将其保留在一个契约中，并在任何地方运行 — 每次都有完整的执行跟踪。 Traverse 是 [通用微服务架构](https://www.universalmicroservices.com/) 的工作实现。 --- ## 快速开始 **要求**: Rust 1.94+ ```bash git clone https://github.com/enricopiovesan/Traverse.git cd Traverse cargo build cargo run -p traverse-cli -- bundle inspect examples/expedition/registry-bundle/manifest.json ``` 预期输出: ``` bundle_id: expedition.planning.seed-bundle version: 1.0.0 capabilities: 6 events: 5 workflows: 1 ``` 您刚刚检查了一个实时能力包 — 6 个能力、5 个事件、1 个工作流，都在运行时验证和执行的契约中定义。 准备好运行完整的浏览器演示吗？ → [快速开始](quickstart.md) --- ## 我可以构建什么？ ### 具有受控运行时行为的浏览器应用 构建 UI。Traverse 拥有执行、流程状态和跟踪输出。 相同的能力契约在本地开发和生产环境中运行 - 无需重写。 → [快速开始](quickstart.md) · [文档/应用可消费的入口路径](docs/app-consumable-entry-path.md) ### 受控的 MCP 服务器 通过 stdio 公开能力发现和执行。下游 AI 客户端和工具 发现和调用受控能力，无需接触您的内部。 → [文档/MCP-STDIO 服务器](docs/mcp-stdio-server.md) ### 便携式 WASM 能力 将可执行行为打包为 WASM。Traverse 验证、放置和运行它 — 浏览器、边缘或云 — 在相同的契约下。 → [文档/WASM 代理编写指南](docs/wasm-agent-authoring-guide.md) ### 工作流支持的业务逻辑 将多步骤业务行为建模为工作流。运行时遍历它 确定性地并生成一个结构化的跟踪，您可以检查和审计。 → [文档/工作流合成指南](docs/workflow-composition-guide.md) · [文档/入门](docs/getting-started.md) ### 您自己的应用包 ```bash cargo run -p traverse-cli -- app new my-app ``` 为受控应用包提供了一个脚手架。添加您的能力契约、工作流和 WASM 组件。 → [文档/远征示例编写](docs/expedition-example-authoring.md) --- ## 文档 ### 入门和教程路径 | 目标 | 从这里开始 | 继续 | |---|---|---| | 第一个可运行的流程 | [快速开始](quickstart.md) | [文档/应用可消费的入口路径](docs/app-consumable-entry-path.md) | | 学习核心路径 | [文档/入门](docs/getting-started.md) | [文档/远征示例编写](docs/expedition-example-authoring.md) | | 编写能力契约 | [文档/能力契约编写指南](docs/capability-contract-authoring-guide.md) | [文档/入门](docs/getting-started.md) | | 编写事件契约 | [文档/事件契约编写指南](docs/event-contract-authoring-guide.md) | [文档/事件发布教程](docs/event-publishing-tutorial.md) | | 构建 WASM 能力 | [文档/WASM 代理编写指南](docs/wasm-agent-authoring-guide.md) | [文档/WASM 微服务编写指南](docs/wasm-microservice-authoring-guide.md) | | 集成下游应用 | [文档/应用可消费的消费者包](docs/app-consumable-consumer-bundle.md) | [文档/youaskm3 集成验证](docs/youaskm3-integration-validation.md) | | 排查故障 | [文档/故障排除](docs/troubleshooting.md) | [文档/质量标准](docs/quality-standards.md) | ### 消费者和发布表面 - [文档/发布/v0.5.0.md](docs/releases/v0.5.0.md) — 当前发布说明 - [文档/应用可消费的消费者包](docs/app-consumable-consumer-bundle.md) — 版本化的消费者包 - [文档/应用可消费的包发布指针](docs/app-consumable-package-release-pointer.md) — 包发布指针 - [文档/打包的 Traverse 运行时工件](docs/packaged-traverse-runtime-artifact.md) — 打包的运行时工件 - [文档/打包的 Traverse MCP 服务器工件](docs/packaged-traverse-mcp-server-artifact.md) — 打包的 MCP 服务器工件 - [文档/youaskm3 规范的应用 HTTP 路径](docs/youaskm3-canonical-app-http-path.md) — 规范的 HTTP 应用路径 - [文档/youaskm3 规范的 MCP 客户端路径](docs/youaskm3-canonical-mcp-client-path.md) — 规范的 MCP 客户端路径 - [文档/youaskm3 集成验证](docs/youaskm3-integration-validation.md) — youaskm3 集成验证 - [文档/youaskm3 发布工件验证](docs/youaskm3-published-artifact-validation.md) — 发布工件验证 - [文档/youaskm3 兼容性一致性套件](docs/youaskm3-compatibility-conformance-suite.md) — 兼容性一致性套件 - [文档/youaskm3 真实 Shell 验证](docs/youaskm3-real-shell-validation.md) — 真实 Shell 验证 - [文档/MCP 真实代理练习](docs/mcp-real-agent-exercise.md) — MCP 真实代理练习 ### v0.3.0 消费者路径 - [文档/v0.3.0 公共表面兼容性](docs/v0.3.0-public-surface-compatibility.md) — v0.3.0 公共表面兼容性 - [文档/v0.3.0 源构建消费者打包](docs/v0.3.0-source-build-consumer-packaging.md) — v0.3.0 源构建打包 - [文档/v0.3.0 下游验证路径](docs/v0.3.0-downstream-validation-path.md) — v0.3.0 下游验证路径 - [文档/youaskm3 v0.3.0 集成就绪度](docs/youaskm3-v0.3.0-integration-readiness.md) — v0.3.0 集成就绪度索引 ### 参考 - [文档/适配器边界](docs/adapter-boundaries.md) — 适配器和可移植性边界 - [文档/兼容性策略](docs/compatibility-policy.md) — 版本和兼容性 - [文档/故障排除](docs/troubleshooting.md) — 常见故障的最短路径 - [文档/我可以构建什么](docs/what-can-i-build.md) — 具体应用和集成模式 - [文档/基准测试](docs/benchmarks.md) — 测量的延迟数字 - [文档/决策日志](docs/decision-log.md) — 综合架构决策 --- ## 架构 ### 货架 | 货架 | 角色 | |---|---| | `traverse-runtime` | 核心执行引擎 — 验证、放置和执行能力 | | `traverse-contracts` | 契约定义、解析和验证 | | `traverse-registry` | 能力注册表和事件注册表，具有确定性遍历 | | `traverse-cli` | 命令行界面：注册、列出、验证、运行 | | `traverse-mcp` | 模型上下文协议 stdio 服务器和受控 MCP 接口 | --- ## 贡献 在打开 PR 之前请阅读： - [CONTRIBUTING.md](CONTRIBUTING.md) - [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) - [SECURITY.md](SECURITY.md) - [文档/质量标准](docs/quality-standards.md) 所有工作都遵循以下治理工作流程。每個 PR 都必须有批准的规格支持。 [GitHub 项目 1](https://github.com/users/enricopiovesan/projects/1/) 是规范的看板。所有活跃的工作都有问题、项目项和 PR。 --- ## 建立在 UMA 之上 Traverse 是 [通用微服务架构](https://www.universalmicroservices.com/) 描述的运行时 — 通用微服务架构是浏览器、边缘、云、工作流和 AI 中执行可移植和受控的业务行为的答案。 | | UMA | Traverse | |---|---|---| | 它是什么 | 架构模型 + 书籍 | 工作运行时实现 | | 业务能力 | 定义概念 | 使用契约和规格执行 | | 可移植性 | 描述模式 | 通过 WASM 和适配器强制执行 | | 治理 | 指定规则 | 作为不可变的规格和 CI 门控实施 | | AI 安全 | 描述要求 | 通过可解释的运行时跟踪交付 | **如果您想了解这些想法：** [阅读 UMA 书籍](https://www.universalmicroservices.com/) 并探索 [UMA 代码示例](https://github.com/enricopiovesan/UMA-code-examples)。 --- ## 治理 Traverse 是基于规格驱动的。代码必须与批准的不可变规格一致，否则无法合并。 | 工件 | 位置 | 角色 | |---|---|---| | 规格 | [`specs/`](specs/) | 版本化、不可变、合并门控 | | 契约 | [`contracts/`](contracts/) | 运行时行为的源头 | | 宪法 | [`.specify/memory/constitution.md`](.specify/memory/constitution.md) | 覆盖所有便捷决策 | | CI 门控 | [`scripts/ci/spec_alignment_check.sh`](scripts/ci/spec_alignment_check.sh) | 确定性、与 AI 无关 | ### 已批准的规格 | ID | 规格 | 管理 | |---|---|---| | 001 | [基础-v0-1](specs/001-foundation-v0-1/spec.md) | 核心运行时、CLI、MCP 接口 | | 002 | [能力契约](specs/002-capability-contracts/spec.md) | 契约定义和验证 | | 003 | [事件契约](specs/003-event-contracts/spec.md) | 事件契约定义 | | 004 | [规格对齐门控](specs/004-spec-alignment-gate/spec.md) | CI 合并门控 | | 005 | [能力注册表](specs/005-capability-registry/spec.md) | 注册表行为 | | 006 | [运行时请求执行](specs/006-runtime-request-execution/spec.md) | 执行模型 | | 007 | [工作流注册表遍历](specs/007-workflow-registry-traversal/spec.md) | 工作流组合 | | 008 | [远征示例领域](specs/008-expedition-example-domain/spec.md) | 示例领域 | | 009 | [远征示例工件](specs/009-expedition-example-artifacts/spec.md) | 示例工件 | --- ## 为代理 该项目通过并行运行 Codex 和 Claude Code 支持 AI 辅助开发。 ### 入口点 | 代理 | 文件 | 目的 | |---|---|---| | Claude Code | [`CLAUDE.md`](CLAUDE.md) | 项目上下文、治理规则、speckit 工作流 | | Codex | [`AGENTS.md`](AGENTS.md) | 项目上下文、协调规则、speckit 工作流 | | 所有代理 | [`.specify/memory/constitution.md`](.specify/memory/constitution.md) | 治理宪法 v1.2.0 | ### 代理工作流 1. **阅读** 您的入口点文件（`CLAUDE.md` 或 `AGENTS.md`） 2. **认领** 票据 — 检查 `agent:claude` / `agent:codex` 标签和现有分支 3. **创建** 功能分支：`NNN-feature-name` 4. **运行** `.specify/scripts/bash/setup-plan.sh --json` 初始化规格目录 5. **编写** `specs/<branch>/spec.md` 和 `plan.md` 在任何代码之前 6. **实现** 满足规格和契约的最小更改 7. **打开** PR 与 `## 治理规格`、`## 项目项` 和 `## 验证` 部分 ### 代理协调 - `agent:claude` 标签 = 由 Claude Code 声称 — Codex 必须跳过 - `agent:codex` 标签 = 由 Codex 声称 — Claude Code 必须跳过 - 完整协调规则： [`docs/multi-thread-workflow.md`](docs/multi-thread-workflow.md) --- ## 许可证 Apache-2.0 — 见 [LICENSE](LICENSE) 和 [NOTICE](NOTICE)。 ## 相关工作 - [UMA-code-examples](https://github.com/enricopiovesan/UMA-code-examples) - [通用微服务架构 — 书籍](https://www.amazon.com/dp/B0GTTTTQH4) - [契约驱动的 AI 开发（C-DAD）— 白皮书](https://drive.google.com/file/d/1HC_ZWJl9aYaMeN78qiL3ZYBVY7mAGl3f/view) - [演讲](https://enricopiovesan.github.io/enricopiovesan/) - [github.com/enricopiovesan](https://github.com/enricopiovesan)