首页开发

Developers

在 Raise 上开发业务系统，开发者只写业务。

身份、权限、审计、多端和助手由平台提供。开发者用 Go 或 TypeScript SDK 写后端，用 React 应用 SDK 写页面，按 k3 协议声明对象、操作和权限点；契约测试证明应用遵守协议，之后装进组织，或在应用市场上架。

阅读开发文档进入开放平台

Toolchain

两个服务端 SDK、一个应用 SDK 和一个命令行，覆盖从写代码到发布。

SDK

Go SDK 与 TypeScript SDK 版本号相同，一起发布。

换令牌、重试、分页、幂等键和 Webhook 验签都在 SDK 里，开发者不用自己拼签名和重试。

Go SDK：raise-go。模块 github.com/21stware/raise-go，要求 Go 1.26 及以上。公共模块代理可装，平台也带一个只读的模块代理。
TypeScript SDK。@21stware/raise-sdk，零运行时依赖，跑在 Node.js 18+、Deno、Bun 和 Cloudflare Workers 上，从平台的开发者门户下载安装。
React 应用 SDK。应用页面用 @21stware/raise-app-sdk 与套件包 @21stware/raise-app-kit。平台自带应用的页面用的也是这个套件包。

5 分钟第一次调用注册开发者组织

GET /open/v1/whoami

package main

import (
	"context"
	"fmt"
	"log"
	"os"

	"github.com/21stware/raise-go"
)

func main() {
	c := raise.New(os.Getenv("CLIENT_ID"), os.Getenv("CLIENT_SECRET"),
		raise.WithTenant(os.Getenv("TENANT")),
		raise.WithBaseURL("https://api."+os.Getenv("DOMAIN")+"/open/v1"),
	)
	me, err := c.Platform.Whoami(context.Background())
	if err != nil {
		log.Fatal(err) // *raise.Error：err.Code、err.RequestID
	}
	fmt.Println(me.Tenant, me.App, me.Scopes)
}

import { Raise } from '@21stware/raise-sdk'

const raise = new Raise({
  clientId: process.env.CLIENT_ID!,
  clientSecret: process.env.CLIENT_SECRET!,
  tenant: process.env.TENANT,
  baseUrl: `https://api.${process.env.DOMAIN}/open/v1`,
})

const me = await raise.platform.whoami()
console.log(me.tenant, me.app, me.scopes)

客户端密钥只放在服务端，不打进浏览器页面或小程序前端。

k3 CLI

从 `k3 app init` 到 `k3 publish`。

01 · k3 app init

应用模板

k3 app init 从 Go 后端加 React 前端的模板生成项目。模板随平台一起构建，并跑契约测试。

02 · manifest.json

清单

应用在清单里声明对象、操作和权限点，助手按声明使用它。清单随版本审核；接入等级写在清单的 level 里，由契约测试证明。

03 · k3 dev

k3 CLI 与本地 devkit

k3 dev 在本机起身份服务、草稿服务和预览工作台；k3 dev --test-enterprise 让本机进程以测试企业里那个应用的身份运行。

04 · k3 contract

契约测试

契约测试证明应用遵守协议，之后装进组织，或在应用市场上架。

05 · k3 publish

调试与发布

k3 logs 看调用日志和脱敏后的错误；k3 listen、k3 trigger 收发测试事件；k3 publish 上传版本、跑检查、提交审核。

我的应用

k3 app init

k3 app init my-app --module example.com/my-app
cd my-app
go build ./...

生成 Go 服务端、React 页面和清单 manifest.json快速开始 →

manifest.json

{
  "protocol": "k3/0.5",
  "id": "crm",
  "name": "客户管理（模板）",
  "version": "0.1.0",
  "level": 3,
  "embed": "iframe",
  "web": {
    "url": "http://localhost:8080",
    "capabilities": [
      "presence",
      "ui.toast"
    ]
  },
  "nav": [
    {
      "label": "客户",
      "route": "/accounts"
    }
  ],
  "ops": {
    "updateAccount": {
      "entity": "account",
      "kind": "update",
      "risk": "low",
      "title": "修改客户",
      …
    },
    …
  },
  "opsApi": "http://localhost:8080/k3",
  "dryRun": "full"
}

模板的清单（节选）；k3 app init 把 id 换成目录名

k3 dev

k3 dev --app http://localhost:8080 &      # devkit + preview Shell on :7700
go run ./api                              # your App on :8080

k3 dev --test-enterprise ${SANDBOX_ID} --app my-app -- go run ./api

子进程拿到 RAISE_BASE_URL、RAISE_CLIENT_ID、RAISE_CLIENT_SECRET、RAISE_TENANT本地开发 →

k3 contract

k3 contract --app http://localhost:8080   # must be green before publishing
k3 lint .                                 # manifest and brand check

在 CI 中可使用容器镜像 k3-contract（任何语言的 App 都适用）

k3 publish

k3 login --url "https://dev.${DOMAIN}" --client-id "${K3_CLIENT_ID}" --secret-stdin
k3 publish --wait
k3 status my-app

k3 logs my-app --env test --status 4xx
k3 listen --app my-app --forward-to http://localhost:8080/k3/events
k3 trigger customer.created --app my-app --tenant ${SANDBOX_ID}

首次会创建应用；上传版本、自动检查、提交审核本地开发 →

k3 protocol

应用在清单里声明对象、操作和权限点，助手按声明使用它。

清单随版本审核。助手需要知道「应用能做什么」，读清单；需要数据和结果，调应用的后端，以成员本人的身份。接入等级写在清单的 level 里，由契约测试证明。

等级	应用得到什么	应用要做什么
L0 嵌入	在工作台面板里打开	清单与导航
L1 可链接	助手给出链接，成员点开进到应用的页面	路由接受引用和筛选，声明对象的页面
L2 感知	助手知道成员正在看什么	报告当前页面与选中的 `k3://` 引用，声明哪些内容要遮盖
L3 可起草、可操作	助手起草变更、请求动作，成员在应用自己的页面里审阅	声明操作，提供预演与执行接口，每个操作声明审阅方式

等级不由开发者自报：审核人员用 k3 contract 实测，记下实测等级，组织按实测等级启用应用。

Interfaces

两个接口、一种事件、一座 MCP 桥，约定处处一样。

开放接口与应用接口用同一种错误信封。

同一个 Idempotency-Key、同样的限流响应头。两份接口参考都由接口描述文件生成，可以下载导入自己的工具。

接口约定

HTTP ≥ 400 · 错误信封

{
  "error": {
    "code": "scope_required",
    "message": "this call needs the scope platform:ping",
    "requestId": "9f2c7a3b4e1d5f60",
    "docUrl": "https://dev.${DOMAIN}/docs/errors#scope_required",
    "details": {}
  }
}

接口	给谁用	能做什么
开放接口 `/open/v1`	组织授权的集成、代表组织的应用	读多维表和组织通讯录，读写客户档案；也可以代表一位终端客户（小程序用户）调用
应用接口 `/app/v1`	已安装的应用	调用平台能力：客户中心、站点访客、经营记账、审计链、成员、事件、记录链接；范围在清单里声明
Webhook	任何接了事件的后端	平台把事件推到 https 地址，同一个信封、同一种签名，失败重试
MCP	外部 Agent	以登录成员的委托令牌调用平台的工具；已安装应用声明的操作出现在工具列表里，调用结果进草稿

平台调用应用时（操作的预演与执行、事件、服务）带签名断言，应用用平台公布的公钥验签。

Test & live

测试与正式两套密钥，测试在测试企业里做。

密钥前缀决定环境。

测试密钥只能用在开发者组织自己的测试企业，正式密钥只能用在真实的组织；拿错了，平台返回 wrong_environment。

两种前缀。kwo_test_ 与 kwo_live_；每个应用每个环境最多 5 把，可限 IP，轮换有重叠期。
测试企业。数据独立、不计费，可以带示例客户、多维表和测试员工；草稿版本也能试装。
以测试员工身份进入。测试店长、测试前台、测试员工各一位，用一次性的登录地址进到工作台。
期限。每个开发者组织同时最多 3 个测试企业，每个存活 30 天，可延期到 90 天。

在开放平台打开测试企业

k3 test-enterprise

k3 test-enterprise create "分销联调" --email sbx-admin@example.com --sample general
k3 test-enterprise list

k3 test-enterprise users ${SANDBOX_ID}
k3 test-enterprise signin ${SANDBOX_ID} ${USER_ID}

k3 credentials create my-app --env test --name laptop
k3 credentials list my-app --env test
k3 credentials rotate my-app ${CREDENTIAL_ID} --overlap-days 7
k3 credentials revoke my-app ${CREDENTIAL_ID}

密钥只打印一次本地开发与测试企业 →

Run & ship

应用可以由平台托管运行，也可以由开发者自己运行。

由谁运行不在创建时选，由每个版本的清单决定。分发方式由开发者组织决定：只给自己的组织用，或在应用市场上架。

托管运行
清单写了 runtime.image 的版本由平台运行。有自己数据的应用有自己的模式 app_<id> 和同名角色，迁移在发布时执行。
自建应用
属于某个组织的开发者组织建的应用，只在这个组织里用。版本提交后自动通过，不经审核。
应用市场上架
版本提交后不可变，先过自动检查（清单、版本、界面地址、运行配置），再经人工审核，通过后由开发者决定何时上架。

在开放平台打开我的应用

在 Raise 上开发的业务系统可以作为自己的产品售卖：经应用市场上架、计费与结算，或带许可证交付。商业授权

Data boundary

开发者看得到自己的应用，看不到任何组织的数据。

开发者组织在身份中心里是独立的组织，它的令牌不带组织，所以没有任何组织接口会接受它。运行信息只经三条路径给到开发者。

应用级的指标。按应用汇总，不按组织列出。
脱敏后的错误。不含请求体、字段值、令牌。
限时诊断。组织明确批准后才有：只读，写进组织的审计链，可撤销。
没有的。生产环境的 shell、数据库凭据、原始日志。

三层隔离

第一次调用从测试密钥开始。

注册开发者组织，建一个应用和一个测试企业，拿一把测试密钥，用 Go 或 TypeScript SDK 调用第一个接口。开发文档从这一步讲起。

阅读开发文档注册开发者组织