Skip to content

hc-tec/kitstudio

BranchesTags

Repository files navigation

KitStudio

编码：UTF-8
目标：一个类似“微信开发者工具”的 Function Kit / IME 调试器。
当前状态：Phase 1（Web Runner + Host Simulator + DevTools Panels + 可回放）。

快速开始

cd kit-studio
powershell -ExecutionPolicy Bypass -File .\scripts\dev.ps1

打开：

  • http://127.0.0.1:39001/

Electron（Phase 2 Runner）

说明：Electron 版本更接近“微信开发者工具”形态，并附带基础安全护栏（阻止远程导航/弹窗/权限请求、限制请求 origin）。 下载策略：Electron 会阻止所有下载；会话/Remote Attach 导出改为 Save Dialog 写文件（不会再走浏览器 download）。

cd kit-studio
npm install
npm run electron

可选：

  • 指定 Node 启动 server：$env:KITSTUDIO_NODE="C:\\Program Files\\nodejs\\node.exe"

UI（shadcn/ui + 主题）

  • UI 使用 shadcn/ui 风格（Tailwind + CSS variables tokens），并支持 Light / Dark / System 主题切换（右上角「主题」）。
  • 若你要改 UI 样式：先执行 npm install，然后执行 npm run css:watch（或 npm run css:build）。

Local-First（当前主路线）

  • 推荐主流程：Workspace → Host Input Lab → Inspector / Network / Files / Tasks。
  • 先在本地 Host Simulator 里把打字、权限、网络、文件、安装链路跑通，再看更低频的实验能力。
  • 当前本地优先缺口清单：LOCAL_FIRST_GAPS.md

IME 视角（手机预览）

  • 中间 Runner 右上角「视角」支持 IME 面板/Inline 的固定 viewport（更贴近“输入法功能件”的真实尺寸）。
  • Runner 右上角支持「缩放」（默认 90%）与「键盘」（mock，高度可选）以便做更逼真的比例验收；两者会持久化到 localStorage。
  • 默认 IME 视角会显示“假手机屏幕”（bezel + status bar + app placeholder），并将 IME 面板锚定在屏幕底部；桌面自适应 会自动还原为全尺寸。

Host Events（宿主主动推送）

  • 左侧 Host Events 支持模拟：
    • binding.invoke（用于 bridge-debugger 验收绑定触发链路）
    • send.intercept.ime_action.intent（用于拦截器/策略调试）

Experimental：Remote Attach（HTTP/SSE）

说明：Remote Attach 继续保留，但已降级为实验能力，不是当前日常开发主流程。

  • 左侧 Remote Attach：channel 可留空直接连接（会自动选择最近活跃 channel，或展开 Channels 列表引导你选择）。
  • 连接后会通过 SSE 订阅：GET /api/attach/stream?channelId=<channel>
  • 连接时会自动拉取最近 history（limit=200），并按 eventId 去重；日志时间戳使用 receivedAtEpochMs（更贴近真实发生时间）。
  • Remote Attach mode：
    • 抓包（只看）：只写入 Inspector
    • 镜像（kit→remote）：把本地 kit 的 ui->host/host->ui 写入 channel（供远端订阅）
    • 桥接（kit↔remote）：在镜像基础上，把 remote 的 host->ui 注入到当前 kit
    • Remote Host：绕过本地 Host Simulator（除 bridge.ready 外不再响应），由远端宿主负责回包
  • 外部宿主可推送 envelopes：POST /api/attach/envelope
    • body 最少：{ origin, clientId, direction, envelope }（channelId 可省略：会按 origin/clientId/envelope.kitId 自动推导）
  • Pair Code（一次性配对码，推荐）：DevTools「高级 / Channels」点击「生成」得到 KS-XXXXXXXX，粘贴到 Android 的 KitStudio attach token，会自动兑换为 bearer token（write scope），避免手抄长 token。
  • Channels 工具：
    • 列表：GET /api/attach/channels
    • 清空：DELETE /api/attach/channel?channelId=<channel>
    • UI 侧「高级 / Channels」支持：复制 SSE URL / 复制 POST 示例 / 导出当前 channel history（JSON）
    • 导入：工具栏「导入会话」也支持导入 kind=kitstudio.attach.channel（会把 events[] 转成 Inspector log，并尝试打开对应 kit）
  • 安全（可选）：
    • token（admin）：在 kitstudio.config.json 配置 attach.token（或 env KITSTUDIO_ATTACH_TOKEN）；UI「高级 / Channels」可填写 token 用于 SSE/fetch/curl 示例。
    • allowlist：在 kitstudio.config.json 配置 attach.allowOrigins/allowClientIds/allowKitIds（不配置则默认全允许）。
  • 版本标识：GET /api/health 会输出 version/gitCommit，并在 UI 顶部显示短 commit（用于排查“旧 server 常驻”）。

Workspace（项目化）

  • 顶栏「导出工作区 / 导入工作区」保存/恢复：主题、Runner 视角/缩放/键盘、可选的 Remote Attach 配置、以及当前会话快照（可回放）。
  • 若当前填写了 Remote Attach token，导出时会提示是否把这个实验能力的 token 明文写入工作区文件（取消=不包含）。

Kit Packages（Catalog / ZIP，对接 Android Download Center）

  • Catalog：GET /api/kit-packages（可直接粘贴到 Android Download Center 的 Catalog URL）。
  • ZIP：GET /api/kit-packages/<kitId>.zip（Android 下载中心「Install from URL」可直接安装）。
  • Metadata：GET /api/kit-packages/<kitId>.json（包含 sizeBytes/sha256，用于 Host 校验）。
  • UI：左侧 Packages 卡片提供「复制 Catalog URL」与每个 kit 的「复制 ZIP URL」。

端到端测试（agent-browser / vercel-labs）

cd kit-studio
powershell -ExecutionPolicy Bypass -File .\scripts\e2e.ps1

或：

npm run e2e

可视化（有头浏览器，便于调试）：

powershell -ExecutionPolicy Bypass -File .\scripts\e2e.ps1 -Headed
npm run e2e:headed

AI real -> replay smoke（可选）

这条用真实 provider 跑一次 runtime-lab 的 ai.request，然后保存为 replay 并再次命中。默认不进主 E2E，避免把 secret / 外网依赖强塞给所有开发机。

统一入口（只跑 AI smoke）：

$env:KITSTUDIO_E2E_AI_BASE_URL="https://api.deepseek.com/v1"
$env:KITSTUDIO_E2E_AI_API_KEY="<your-key>"
$env:KITSTUDIO_E2E_AI_MODEL="deepseek-chat"
npm run e2e:ai-real

低层脚本入口：

powershell -ExecutionPolicy Bypass -File .\scripts\e2e-ai-real.ps1 `
  -ProviderBaseUrl $env:KITSTUDIO_E2E_AI_BASE_URL `
  -ProviderApiKey $env:KITSTUDIO_E2E_AI_API_KEY `
  -ProviderModel $env:KITSTUDIO_E2E_AI_MODEL

若要把 AI smoke 串到完整 UI E2E 之后：

npm run e2e:full-plus-ai

说明：

  • 本脚本按 vercel-labs/agent-browser README 的 CLI 工作流跑 E2E（open/wait/select/click/upload/get/eval）。
  • scripts/e2e.ps1 -AiRealOnly 是统一入口里的 AI-only 模式；scripts/e2e.ps1 -IncludeAiReal 会在常规 UI E2E 之后继续调用 scripts/e2e-ai-real.ps1。两者若未显式传参，都会读取 env：KITSTUDIO_E2E_AI_BASE_URL / KITSTUDIO_E2E_AI_API_KEY / KITSTUDIO_E2E_AI_MODEL。
  • scripts/e2e-ai-real.ps1 会验证三件事：real 模式已配置、runtime-lab 首次请求拿到真实 ai.response、保存 replay 后二次请求命中 replay hit。
  • 为避免 Windows PowerShell 捕获输出导致 agent-browser daemon 首次启动卡住，脚本内部通过 cmd.exe 重定向输出文件来读取 --json 结果（详见 e2e/logs/，已忽略）。
  • kit UI 在同源 iframe 内，脚本用 eval -b 操作 iframe 内的 DOM，避免 frame 在该环境下偶发不稳定。
  • agent-browser 版本默认固定为 0.23.0（可通过 env KITSTUDIO_AGENT_BROWSER_VERSION 覆盖），避免 npx 因上游版本缺失报 ETARGET。
  • 若 39001 端口已有旧 KitStudio 常驻（但缺少新 endpoint），脚本会探测 GET /api/attach/history / GET /api/kit-packages / GET /api/e2e/delay?ms=0 并自动重启旧进程（仅匹配 node ... src\\server.mjs）。
  • 若 kitstudio.config.json 的 host 为 0.0.0.0（对外监听），E2E 会自动用 127.0.0.1 作为浏览器访问地址；需要指定其他地址时可设置 env KITSTUDIO_CLIENT_HOST（例如 192.168.1.10）。
  • scripts/e2e.ps1 与 scripts/e2e-ai-real.ps1 含中文提示，需以 UTF-8 BOM 保存以兼容 Windows PowerShell（仓库内已处理）。
  • 若机器上已有 Chrome/Edge，会自动使用；否则可先执行：npx --yes agent-browser@0.23.0 install
  • 当前覆盖：
    • UI：Light/Dark 主题切换；Runner 视角/缩放/键盘 mock；Workspace 导入/导出；Packages（Catalog/ZIP 复制、filter）
    • Host Simulator：权限 revoke/grant + sync；context editor sync/reset
    • Host Input Lab：selection、Shift+Enter 本地换行、Enter / IME action 差异
    • file-upload-lab：settings.open / storage.get/set / files.pick / network.fetch(bodyRef)（/api/e2e/echo）
    • task.cancel：对慢 network.fetch（/api/e2e/delay）发起取消，断言任务进入 canceled
    • DevTools Panels：Inspector/Storage/Network/Files/Tasks（含清空/同步/导出会话/导入会话/Reload Kit）
    • Experimental / Remote Attach：连接/Channels 列表/一次性 Pair Code
    • bridge-debugger：模拟 binding.invoke
    • ime-hooks：input.observe.best_effort + send.intercept.ime_action（intent→result→宿主落地）
  • 截图输出：e2e/screenshots/kitstudio-e2e*.png（包含 kitstudio-e2e-99-annotated.png 的可视化标注截图）

默认挂载

kitstudio.config.json 默认挂载当前工程里的：

  • ../../../function-kits（浏览器式 kit UI）
  • ../../../function-kit-runtime-sdk（浏览器 bundle）

如果你的目录结构不同，可以编辑 kitstudio.config.json，或用环境变量覆盖：

  • KITSTUDIO_FUNCTION_KITS_ROOT
  • KITSTUDIO_RUNTIME_SDK_ROOT

Capability allowlist（可选，安全）

如需按能力粒度禁用某些 server API（例如禁用 network.fetch / 文件上传），可在 kitstudio.config.json 增加：

{
  "capabilities": {
    "allow": ["network.fetch", "files", "kit-packages"],
    "deny": ["network.fetch"]
  }
}
  • allow 非空时为白名单；deny 永远优先生效。
  • 当前覆盖：/api/network/fetch、/api/files*、/api/kit-packages*。

文档

  • docs/ARCHITECTURE.md
  • docs/ANDROID_REMOTE_ATTACH_ACCEPTANCE.md
  • TODO.md
  • PROGRESS.md

本地数据

KitStudio 的 FileStore 会把上传文件落盘到：

  • .kitstudio-data/（已在 .gitignore 忽略）

About

No description, website, or topics provided.

Resources

Readme

License

Apache-2.0 license

Code of conduct

Code of conduct

Contributing

Contributing

Security policy

Security policy
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages