内容
# KSwitch 开发工具包
[](https://github.com/KswitchDev/kswitch-devkit/actions/workflows/ci.yml)
在不建立完整企业平台的情况下，构建受控的 AI 代理集成。
KSwitch 开发工具包为开发者提供了语言 SDK、本机运行时和示例，以便在笔记本电脑上尝试真实的代理控制流程：注册代理、评估策略、发出审计事件、触发终止开关，并测试工作负载身份作为默认服务间身份验证模型。它还包括 KSwitch MCP 服务器和用于 MCP 兼容开发工具的治理代理命令。
如果这有助于您构建或解释更安全的代理系统，请为该仓库点赞。点赞有助于我们了解哪些 SDK、示例和集成是下一步的投资重点。
## 功能
使用此仓库，您可以：
- 在 Python、TypeScript 或 Go 应用程序中添加 KSwitch 治理调用。
- 运行用于 SDK 集成的本地 DevKit 控制平面。
- 端到端测试策略决策、审计事件和终止开关流程。
- 通过 `kswitch-mcp` 连接 Claude Code、Cursor、Windsurf、Cline、OpenCode 或 OpenClaw，或使用 `kswitch-proxy` 包装现有的上游 MCP 服务器。
- 在本地使用可选的 SPIRE 服务尝试 SPIFFE/WIMSE 工作负载身份。
- 在连接企业部署之前，在本地学习生产环境中的身份验证概念。
DevKit 在 Apache-2.0 下开源。它旨在开始对话，让开发者和小团队真正感受到受控代理控制的氛围，并在平台上线之前使 SDK/MCP 集成具体化。KSwitch 授予此仓库 Apache-2.0 许可，用于从 ATCP 派生的功能和材料，仅限于源代码、配置、示例、运行时组件、策略样本、脚本、生成的工件和为此仓库发布的公共 DevKit 运行时镜像。授予不包括私有 ATCP 源代码、托管的 KSwitch 服务、企业独有功能、商标、支持或服务级别承诺。
当前 DevKit 运行时镜像：`ghcr.io/kswitchdev/kswitch:v1.39-pg`。公共运行时镜像必须匿名可拉取；`make up` 不需要 GitHub 或 GHCR 登录。
## 快速入门
前提条件：
- 带有 Compose 插件的 Docker
- `make`
- `openssl`
- `curl`
- `jq`
启动本地 DevKit 堆栈：
```sh
cd devkit
cp .env.example .env
# 在 .env 中设置 KEYCLOAK_ADMIN_PASSWORD 为强本地密码。
make up
```
如果 `make up` 报告 `ghcr.io/kswitchdev/*` 镜像不可公开拉取，则是 KSwitch 发布问题，而不是用户凭证问题。请勿在公共问题或本地快速启动命令中粘贴个人 GitHub 或 GHCR 令牌。
然后打开：
- 应用程序和本地 API：`https://localhost:5001`
- 本地文档：`https://localhost:5001/docs/`
- 健康和提示：`make doctor`
默认启用工作负载身份验证：`make up` 启动本地 SPIRE 服务器、代理和 JWT 物料处理器，供示例使用。
为本地 MCP 兼容工具安装 MCP 命令：
```sh
cd devkit
make mcp-install
```
该命令从捆绑的 `../mcp-server` 包中安装 `kswitch-mcp`、`kswitch-proxy`、`kswitch-brain-mcp` 和 `kswitch-service-mcp`。Docker网关仍然是网络代理路径；MCP 命令是本地开发工具使用的_stdio服务器。
## SDK
| 语言 | 包 | 路径 | 文档 |
| --- | --- | --- | --- |
| Python | `kswitch-sdk` | `python/` | [Python SDK](https://hub.kswitch.io/sdk/python.html) |
| TypeScript | `@kswitch/sdk` | `typescript/` | [TypeScript SDK](https://hub.kswitch.io/sdk/typescript.html) |
| Go | `github.com/KswitchDev/kswitch-devkit/go` | `go/` | [Go SDK](https://hub.kswitch.io/sdk/go.html) |
| MCP | `kswitch-mcp` | `mcp-server/` | [MCP 包](mcp-server/README.md) |
从源代码进行本地开发：
```sh
cd python
python -m pip install -e ".[dev]"
cd ../typescript
npm ci
cd ../go
go test ./...
```
## 服务身份验证姿态
KSwitch 优先使用工作负载身份进行服务间调用。
首选顺序：
1. 本地人工开发：使用捆绑的 DevKit CLI 的 OAuth2 PKCE。
2. 服务工作负载：来自 SPIRE 的 SPIFFE JWT-SVID 或 WIMSE 断言。
3. 传输身份：客户端证书是部署身份的 mTLS。
4. 兼容性回退：当工作负载身份不可用时，使用 OAuth2 客户端凭证。
WLID 是 KSwitch 服务身份验证路径：工作负载接收到一个短期的、绑定到工作负载的断言，而密钥保管和轮换则与身份提供者保持一致。OAuth2 客户端凭证仍然是环境无法发出绑定到工作负载的令牌的兼容性桥梁。
更多信息请参见 [docs/auth-model.md](docs/auth-model.md) 和 [docs/governed-invocation.md](docs/governed-invocation.md)。
## Apache-2.0 DevKit 边界
DevKit 旨在进行真实的本地测试，同时将公共 Apache-2.0 路径限制在此仓库中实际交付的功能范围内。官方未修改的制品强制执行这些本地限制：
| 资源 | 容量 |
| --- | ---: |
| 代理 | 10 |
| MCP 服务器 | 10 |
| 工具 | 100 |
| 技能 | 100 |
包括：
- 用于 SDK 评估的本地控制平面运行时。
- 用于 PKCE 的本地 Keycloak 领域。
- 用于工作负载身份示例的本地 SPIRE。
- OPA 支持的策略决策路径。
- 用于开发工具的本地 MCP 服务器和治理代理命令。
- 启动器策略、示例、烟雾测试和医生检查。
不包括：
- 私有 ATCP 源代码或私有 ATCP 发布历史。
- 托管的 KSwitch 服务或云控制平面操作。
- 企业独有功能包、托管合规性报告、商业支持、SLA、云部署包、HA、SIEM、fleet 操作、桌面硬隔离或企业强制附加组件。
- KSwitch 商标权（超出命名使用和 `TRADEMARKS.md`）。
- 除了 Apache-2.0 之外的任何保证、赔偿、支持、服务级别或生产适用性声明。
DevKit 证据是本地开发者证据，而不是生产环境证明。本地网关和 MCP 代理演示了通过它们路由的流量的控件；它们不提供主机级出口隔离或在没有托管运行时控件的情况下直接绕过 MCP 客户端。
请勿将 DevKit 作为业务关键或受监管工作负载的生产信任控制平面。对于生产工作负载，KSwitch 可以提供完整的平台作为 SaaS 或本地部署，具有生产控件、支持模型和 DevKit 故意省略的操作姿态。
参见 [LICENSE.md](LICENSE.md)、[LICENSES/Apache-2.0.txt](LICENSES/Apache-2.0.txt)、[LICENSES/ATCP-DEVKIT-GRANT.md](LICENSES/ATCP-DEVKIT-GRANT.md) 和 [COMMERCIAL-USE.md](COMMERCIAL-USE.md)。
## 仓库映射
| 路径 | 目的 |
| --- | --- |
| `python/` | Python SDK、测试、示例、框架适配器 |
| `typescript/` | TypeScript SDK、测试、包元数据 |
| `go/` | Go SDK、测试、示例 |
| `devkit/` | 本地 DevKit 运行时和生命周期脚本 |
| `mcp-server/` | KSwitch MCP 服务器、治理代理、服务 MCP 和客户端配置 |
| `docs/` | 身份验证和 DevKit 定位说明 |
| `reports/ep227/` | 公共 devkit 边界的发布门控证据 |
## 本地检查
Python：
```sh
cd python
python -m pip install -e ".[dev]"
pytest tests -q
```
TypeScript：
```sh
cd typescript
npm ci
npm test
```
Go：
```sh
cd go
go test ./...
```
发布门控：
```sh
python3 scripts/validate_legal_boundary.py
```
## 社区和安全
使用 [问题选择器](https://github.com/KswitchDev/kswitch-devkit/issues/new/choose) 进行错误、用法帮助、文档空白和 SDK 或示例请求。不要在公共问题中留下秘密、客户数据、生产日志或敏感环境详细信息。
通过 `security@kswitch.io` 私下报告疑似漏洞。
在 KSwitch 启用批准的 DCO、CLA 或无外部贡献工作流程之前，不接受外部代码贡献。
