Kiko Workbench

Agent 负责智能，Workbench 负责能力执行。

Kiko Workbench 是一个让 Agent 按业务需求自进化能力的桌面工作台。传统模式下，Agent 的能力边界由人类决定：缺能力 → 提需求 → 排期开发；在这里，Agent 在执行业务时发现缺什么能力，就现场设计、开发、部署一个插件装进工作台，立即可用——全程零 shell、零人工介入。

• Agent 能力自进化：内置 Plugin SDK Distributor，SDK 物料、构建、部署、注册验证全部工具化。Agent 五步 WS 调用（file.write → sdk.build → sdk.deploy → plugins.rescan → verify）即可完成一个新能力从无到有的闭环。
• 任何 Agent 快速接入：标准 JSON-RPC over WebSocket / HTTP + Token 认证，能发网络请求的 Agent（Claude、Cursor、自定义脚本、自动化流程…）几分钟即可接入；另附 stdio 形态 MCP 适配器，Claude Desktop 等 MCP 客户端即插即用。

自进化闭环跑在一套安全、可观测的插件运行时之上：

• 插件化能力执行：每个插件运行在独立子进程（utilityProcess），懒启动、崩溃自动重启（指数退避 + 3 次熔断），插件崩溃不影响工作台。
• 统一协议层：HTTP JSON-RPC + WebSocket 双通道，首消息认证、Token 持久化，能力调用与事件推送共用一条协议。
• 插件 SDK：插件只面对 @kiko-workbench/plugin-sdk，禁止反向依赖；单文件 bundle 交付，支持第三方库。
• 声明式能力清单：manifest.json + capabilities.json 纯数据注册，主进程不加载插件 JS 即可完成发现与校验。
• 微应用 UI（双向桥）：插件可声明 contributes.ui，通过 kiko-plugin:// 自定义协议加载本地前端资产，源隔离 + CSP + 单实例窗口；前端经 kikoPluginUi.invoke() 向插件后端上报事件并等待回执，后端经 ctx.ui.onEvent 处理——支持待办清单等交互型应用：用户界面操作直达插件后端原子落盘，Agent 经能力调用读写同一数据源，双向闭环。上报面收窄：payload ≤256KB、令牌桶限频、超时兜底、窗口身份定向校验。
• 跨插件能力互调：能力在 capabilities.json 声明 callable_by: ["agent", "plugin"] 即开放给其他插件，经 ctx.services.call() 直接复用（同一闸门约束：自调用 / 嵌套深度 / 载荷上限 / 调用历史归属）。
• 数据变更信号与自动刷新（v1.5）：提供方写入成功后调用 ctx.events.notify("<能力id>") 广播数据变更；消费方在刷新能力上声明 refresh_on，宿主收到信号后以空输入自动执行该能力，刷新结果经 ctx.ui.send 推给自家微应用前端——待办清单更新后，已打开的仪表盘无需 Agent 介入即可自动更新。信号为 best-effort：在途刷新合并为一次补跑、跳过同插件与 disabled/error 插件、按 invocation 来源防环。
• 写能力：写操作就是普通能力，callable_by 含 "plugin" 即可被其他插件调用（如工作管理插件经 ctx.services.call("todo.add", {...}) 把任务列入待办清单），写成功后由提供方广播对应读能力的数据变更。
• 场景（组织层）：把相关插件组织成业务场景（纯标签 / 集合，不改变任何运行时行为）。侧边栏「场景」分组一键直达聚合页：成员状态、对外 API 数一览，支持一键打开成员微应用界面；同一插件可属于多个场景，成员被卸载后以占位卡片提示并可手动清理，配置原子写入工作区 .kiko/scenes.json（损坏容错、不阻断启动）。L1 场景感知：内置只读插件 scene 提供 scene.list / scene.get，外部 Agent 经 MCP 先读场景组织数据、再只用成员插件的能力（plugin_ids 对应 discover 摘要中的 plugin），场景页可一键复制引导提示词；tools/list 不变，收窄发生在 Agent 决策层。
• Bot 工作（无人值守自动化）：以「Bot」为管理维度定义可长期运行的自动化任务——每个 Bot 绑定一个场景（工具面 = 场景内全部插件能力）、一段任务定义与一组触发器（手动 + 频次化定时：仅一次 / 每小时 / 每天 / 每周 / 每月 / 自定义间隔，可附「首次执行时间」锚点）。调度器到点发起任务，任务在隔离执行进程中运行（relay 确定性链 / llm 工具循环双引擎，core 主进程零 LLM 代码）；Bot 列表实时展示运行状态，任务记录含逐步链路与引擎日志，支持分页浏览、一键清空（终态）与实时事件刷新。错过不补跑：宿主未运行时到点的定时触发自然跳过，重启后按频次语义排下一次。
• 内置插件：文件读写、docx 文档生成、长任务开发参考、SDK 分发自举、待办清单（交互型微应用，含 todo.list / todo.add）、宿主窗口控制、场景（只读，含 scene.list / scene.get）。

仓库结构

kiko-workbench/
├── apps/
│   └── desktop/            # Electron 桌面端（主进程 / 渲染进程 / 打包）
├── packages/
│   ├── core/               # 核心域逻辑（零 Electron 依赖）
│   ├── protocol/           # RPC 协议与类型定义
│   ├── plugin-sdk/         # 插件开发 SDK
│   ├── plugins/            # 内置插件（file / document / dev / sdk / todo-list / window / scene）
│   └── mcp-adapter/        # MCP 适配器
├── docs/
│   └── 插件开发规范.md      # 插件开发完整指南
└── scripts/                # 冒烟测试

快速开始

环境要求：Node.js ≥ 22，pnpm ≥ 9。

# 安装依赖
pnpm install

# 构建全部包
pnpm build

# 运行单元测试
pnpm test

# 桌面开发模式（shell + 热更新）
pnpm -C apps/desktop dev

# 无头模式（无窗口，服务形态）
pnpm -C apps/desktop headless

# 冒烟测试
pnpm smoke

插件开发

完整的插件开发指南见 docs/插件开发规范.md，包含：

• 架构模型与依赖方向铁律
• 最小插件五文件结构
• SDK 获取与双轨安装（Agent 轨 / Human 轨）
• 能力声明、配置、产物、事件
• 跨插件能力互调（ctx.services.call）与写能力约定
• 数据变更信号（ctx.events.notify）与 refresh_on 自动刷新
• 微应用（插件 UI）开发
• 验收清单

场景（Scene）

场景是组织层：把若干插件按业务归拢，形成「这个业务需要哪些能力」的单一入口。它只保存标签与成员关系，不改变插件启停、不改变 RPC 路由、不引入权限边界。

界面

• 侧边栏「场景」分组 → 点击场景直达聚合页
• 新建 / 编辑：名称（≤40 字）、描述（≤200 字）、成员插件（≤50 个，可搜索多选）
• 聚合页展示成员状态与对外 API 数，可一键打开成员微应用
• 成员被卸载后显示占位卡片，可手动清理；同一插件可属于多个场景
• 「复制场景提示词」把场景名、scene_id、成员 plugin_ids 与调用引导一起写进剪贴板

存储

配置位于 <workspaceRoot>/.kiko/scenes.json（version: 1，tmp + rename 原子写）：

• 文件缺失 / JSON 损坏 → 空列表并告警，不阻断启动
• 文件版本高于当前 → 只读，拒绝写入
• 字段非法（空名、超长、重复成员）→ 归一化或拒绝，参数错误码 -32602

Agent 如何用场景收窄上下文（L1）

内置只读插件 scene 暴露两个能力（callable_by: ["agent"]）：

外部 Agent 经 MCP 连接后：

1. 用户提到某个场景 → 调 scene.list 找到 scene_id
2. 调 scene.get 读取成员 plugin_ids
3. 在 discover 摘要里用 summary.plugin 与 plugin_ids 对照，只调用成员插件的能力

MCP 适配器的 instructions 已内置这段引导；tools/list 保持不变，收窄发生在 Agent 决策层。场景只回答「哪些插件」，具体能力清单仍需 discover / describe 获取。

边界

• 不做场景级工具集过滤（不按场景裁剪 tools/list）、不做跨插件连线 / 流程编排
• 不做场景控制插件启停、不做权限边界、不聚合业务数据

Bot 工作（自动化）

Bot 是工作台的无人值守执行单元：给它一个场景（可用工具面）、一段任务定义和一组触发器，它就按计划自己跑，跑完留下可追溯的任务记录。产品交互以 Bot 为中心（机器人列表 + 实时状态 + 任务记录），底层自动化调度语义对 Agent / WS / MCP 通道完全一致。

使用场景

组成

• Bot（自动化实例）：名称 / 描述 / 场景绑定 / 任务定义（引擎分支）/ 触发器。每个实例一个 JSON 文件落盘于 <workspaceRoot>/automation/instances/（原子写 + 损坏容错）。
• 触发器：手动（列表按钮 / automation.run / MCP）+ 定时（频次化：仅一次 once_at、每小时 / 每周 / 自定义间隔 every_ms、每天 daily_at、每月 monthly_at，均可附 start_at 首次执行时间锚点）。定时语义为错过不补跑——到点时宿主未运行则跳过，仅一次触发已过时刻即摘除。
• 任务与记录：调度器到点受理任务（task_ 前缀），步骤链与引擎日志逐条落盘 .jsonl；任务记录保留 200 条滚动上限（超限先压缩最旧终态任务的明细，仅留状态行）。界面支持状态过滤、按 Bot 聚焦、分页加载（默认 20 条）与一键清空（仅终态，在途任务保留）。
• 执行引擎（隔离执行进程，@kiko-workbench/plugin-sdk 提供）：relay 确定性链——按声明顺序逐个调用能力，上一步结果整包透传下一步；llm 工具循环——LLM 基于场景工具面自主决策调用，支持 system prompt 与工具轮次上限。
• 实时刷新：任务状态变迁（受理 / 开始 / 完成 / 失败 / 取消）经 automation.task.* 标准事件推送到界面，无需手动刷新。

边界

• 调度器中立：只做「到点 → 发起任务」，不理解实例业务语义；不做补跑队列 / 重试策略
• 每步工具调用都走 invocation 管线（调用方 automation:<id>），与其他通道同等受闸门约束
• core 主进程零 LLM / 推理代码——引擎恒在隔离执行进程中运行

License

MIT