k3 protocol
应用在清单里声明,助手按声明工作。
清单随版本审核。助手需要知道「应用能做什么」,读清单;需要数据和结果,调应用的后端接口;界面消息只用来说明成员此刻在看什么,不承载写入。
01 · 声明
对象、操作和输入结构写进清单
应用声明有哪些页面和对象、能做哪些操作、每个操作的输入字段、风险等级、要成员做什么,以及权限点。
- 字段带名称与取值说明,审阅页和确认卡直接读它
02 · 预演
预演和执行跑同一段命令代码
应用实现操作的预演与执行接口,跑的是成员在页面上点按钮时的同一段代码,权限与审计相同。
- 预演返回应用自己写的后果,例如「将通知 2 人」
03 · 使用
助手以成员本人的身份调用
助手经应用网关读取,权限与数据范围照常生效;应用声明打码的字段,助手读到的是打码后的值。
- 不会替成员打开应用,也不会替成员点保存
"deleteAccount": {
"entity": "account",
"kind": "delete",
"risk": "high",
"agentDraftable": false,
"title": "删除客户",
"description": "Delete a customer (`id`) for good.",
"input": {
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"title": "客户",
"x-ref": "account"
}
}
},
"intervention": {
"confirm": "客户会被永久删除,无法恢复。"
}
}
高风险、助手不可用、确认文案用模板创建一个应用 →
// updateDry checks the change and says what it would do. BaseVersion is the version of the customer as it is now: if the customer
// changes between this preview and the person's click, the platform sees another version and does nothing ("stale"); the person
// looks again. Changes is the before → after, field by field.
func (s *Store) updateDry(_ context.Context, _ appkit.Caller, in json.RawMessage) (appkit.OpResult, error) {
a, err := parse(in, false)
if err != nil {
return appkit.OpResult{}, err
}
s.mu.Lock()
cur, ok := s.rows[a.ID]
s.mu.Unlock()
if !ok {
return appkit.OpResult{}, appx.Invalid(k3.Issue{Field: "id", Code: "not_found", Message: "客户不存在"})
}
after := map[string]any{}
for k, v := range map[string]string{"name": a.Name, "status": a.Status, "owner": a.Owner} {
if v != "" {
after[k] = v
}
}
return appkit.OpResult{
Base: cur.fields(), BaseVersion: appx.VersionOf(cur), Changes: appx.Changes(cur.fields(), after, accountLabels),
Consequences: []k3.Consequence{{Kind: "update", Text: "修改客户「" + cur.Name + "」"}},
}, nil
}
执行先调用同一个 updateDry开发文档 →
"entities": [
{
"type": "account",
"route": "/accounts/{id}",
"listRoute": "/accounts",
"schema": "#/components/schemas/Account",
"filterable": {
"status": [
"eq",
"in"
],
"owner": [
"eq"
]
},
"context": {
"expose": [
"name",
"status"
],
"redact": [
"phone"
]
}
}
],
redact:对助手的读取打码开发文档 →
| 接入等级 | 助手能做什么 | 应用要做什么 |
|---|---|---|
| L0 嵌入 | 应用在工作台面板里打开 | 清单与导航 |
| L1 可链接 | 给出链接,成员点开进入应用的页面 | 路由接受引用和筛选 |
| L2 感知 | 知道成员正在看哪一页、选中了哪条记录 | 上报当前页面与选中项;声明打码字段 |
| L3 可起草、可操作 | 起草表单变更,请求动作 | 声明操作,实现预演与执行 |
等级由契约测试证明。外部 Agent 经平台的 MCP 桥和开放接口接入,适用同一套权限规则。
Three outputs
助手给出的结果只有三种。
助手唯一的写入口是「提议修改」:填进未保存的表单、生成确认卡,或建一份草稿。真正写入由成员决定。
02 · 草稿
改动先进草稿,不进库
成员在应用自己的页面里逐条审阅,可以修改、只应用其中几条,也可以整份放弃。
草稿只有本人能应用。
把张伟和李娜的负责人都改成陈静
起草了 2 处改动
- 客户「张伟」的负责人改为陈静已接受
- 客户「李娜」的负责人改为陈静待你确认
1 处待你确认
放弃全部确认
03 · 确认卡
动作先出一张确认卡
卡上写明执行后会发生什么。成员确认才执行;取消或不处理,不会写入。
删除客户张伟
删除客户需要谨慎
- 对象
- 张伟
执行后将会
- 永久删除客户「张伟」
客户会被永久删除,无法恢复。
等你确认后才会执行
取消确认:删除客户
The gate
写入之前的闸门由平台的三条机制保证。
这些限制写在平台里,不依赖提示词,应用和助手都绕不过去。
- 草稿绑定修订号
平台签发的断言绑定成员、操作、输入摘要和记录的版本。确认时记录已经变了,判为过期,什么都不执行。
- 确认卡
高风险操作和删除永远要成员明确确认;关键操作还要求 5 分钟内重新验证过身份。助手的委托令牌调用「应用」返回 403。
- 只追加的审计链
每次写入记下途径:草稿、规则或确认。审计是哈希链,只追加触发器让任何角色都改不了。
仅具备读取与起草权限,修改需由人工确认后生效工作台输入框下方的默认脚注
Adoption
组织按自己的节奏从只读走到按规则自动执行。
在成员照常操作的业务系统之上,四级逐级叠加。每一级都可以退回上一级,已经写入的记录不受影响。
- 只读。助手回答问题,回答写明出处。
- 起草。改动进草稿,成员审阅后应用。
- 确认后执行。动作先出确认卡,成员点确认才执行。
- 按规则自动执行。成员为一类低风险变更签一条自动应用规则,校验通过就直接写入,记录来源标为「按预签名自动应用」。撤销规则后,这类变更重新逐条审阅。
高风险操作、删除和动作永远不能预签名。开发者可以把某个操作标为助手不可用;管理员可以开关助手生成组件和联网搜索。