AI 辅助应用模板开发

在平台内用自然语言生成 Knodo 应用模板：AI 写代码 → 实时预览 → 一键发布

AI 辅助开发应用

Knodo 提供一个内置的 「应用模板开发」 应用模板，让你不写一行代码就能做出自己的应用模板，发布后供团队复用。

背后的原理：在开发空间里，你用自然语言跟 AI 描述需求，AI 会写好 app.yaml 和 TSX 面板源码，平台在浏览器端实时编译并预览，满意后一键打包上传到应用模板库。

为什么这么做

传统做法开发一个前端应用要：搭脚手架 → 选组件库 → 写代码 → 调样式 → 打包 → 部署。对非程序员用户，这条路基本走不通。

Knodo 的做法是把开发环境做成一个工作空间，让 AI 完成所有技术细节：

知识库（= 代码目录）：AI 把源码写在这里
AI 对话：你用自然语言提需求、改样式、加功能
预览面板：浏览器端编译 + 三档预览，所见即所得
一键发布：AI 自动打包上传

整个过程你只需要：想清楚要什么 + 看预览说满意还是不满意。

开始使用

1. 创建开发空间

新建工作空间 → 选择 「应用模板开发」 应用模板 → 完成创建。

进入后左栏是预览面板，默认展开；还能看到代码面板（其实是知识库，专门为此模板重命名）。

2. 跟 AI 说需求

在对话里描述你要做什么，越具体越好：

做一个电影收藏管理应用，要能新增电影（名字、年份、评分）、按年份筛选、按评分排序

AI 会：

根据需求推导 slug（例如 movies）
写 app.yaml 定义面板和布局
写 src/panels/movies.tsx 实现 UI 逻辑
保存文件

几秒后预览面板会自动编译、自动挂载你的组件。

3. 三档预览模式

预览面板顶部有三个按钮，递进式切换查看效果：

模式	切换方式	效果
开发	默认	不改变布局，面板清单里展开看每个面板的组件（内嵌预览）
预览	点「预览」	侧边栏追加你的面板（带「预览」前缀），保留开发工具（对话、代码面板）
全真	点「全真」	完全切换为你的 App 布局，对话区也会隐藏

全真模式下右下角有 「返回开发」 悬浮球，双击 ESC 也能退出。即使 AI 写出了死循环代码，逃生球一样能点。

4. 迭代优化

看到预览后，可以继续跟 AI 说：

把电影卡片的背景改成渐变色

加一个「已看过」的筛选条件

把评分数字字体放大一点

AI 会 Read → Edit 现有文件。由于 AppPreview 监听了源码变化，保存后自动重新编译刷新。

5. 发布

满意后点预览工具栏的 「发布」 按钮。会弹出确认对话框，点击确认后：

指令会自动发到对话框（你不需要手动打字）
AI 执行 app-developer Skill 的 pack-and-upload.sh 脚本
脚本用 npx esbuild 编译 TSX → 打 ZIP → 直接调 POST /api/v1/apps
返回新 App ID

完成后：

此 App 出现在空间列表页 「应用模板」 管理弹窗里
任何成员创建工作空间时可以选择这个 App
你自己可以在设置里切换任意空间到此 App

覆盖发布（改了代码再发一次）

修改后再次点发布时，如果是同一个 slug，AI 会先发一次请求 → 后端返回 409 冲突 → AI 问你：

组织内已有同名应用「xxx」，这次发布会覆盖旧版本，所有绑定此应用的工作空间会立即使用新版。要覆盖吗？

你确认后 AI 再发一次带覆盖标识的请求，成功后告诉你「已覆盖更新」。

权限保护：只有原作者能覆盖。如果你在别人的空间里发布一个同 slug 的 App，会被后端拒绝（403），需要你改 slug 重试。

文件约定

AI 生成的文件结构（你能在「代码」面板里看到）：

<workspace-root>/
├── app.yaml                  # App Manifest（必需）
├── src/
│   └── panels/
│       ├── <view-key-1>.tsx  # 每个 view 对应一个 TSX 文件
│       └── <view-key-2>.tsx
└── dist/                     # 打包产物（脚本生成，无需手动编辑）
    └── <slug>.zip

严格命名约定

view key ⇄ entry 文件名 ⇄ 源码文件名必须三者对齐：

app.yaml 的 views.<key>.entry = ./panels/<key>.js（发布后的路径）
源码 src/panels/<key>.tsx

违反约定会导致预览报"源文件不存在"。AI 会严格遵守这个约定。

TSX 文件约束

AI 生成的面板组件需要满足：

export default 导出 React 组件
组件接收 { workspaceId: string } props
可以 import react（Hook 都能用）
可以 import 下列平台能力（详见下一节）：
- @knodo/api：调用平台前端行为（发对话消息等）
- @knodo/ui：复用平台复合组件（目前：ChatInterface）
可以直接 fetch 任何 /api/v1/... 后端接口（same-origin 自动带凭证）
不能 import 平台私有模块（@/components/...、@/stores/... 等）
Tailwind 类名可用

面板可用的平台能力

除了纯 React 组件能力，面板还可以调用平台暴露的三类能力做更复杂的事。

1. `@knodo/api` — 调用平台前端行为

用在「面板想让 AI 帮我做事」这类场景。这些能力不是后端 API（没有 HTTP endpoint），必须走 @knodo/api。

方法	作用
`chat.send(text)`	把一段文本直接作为用户消息发送到当前激活的对话 Tab，AI 立即开始回复
`chat.fill(text)`	把文本填进输入框（不自动发送），留给用户改完再点发送

示例：

import { chat } from '@knodo/api'

<button onClick={() => chat.send('帮我分析这条订单异常')}>
  交给 AI 分析
</button>

关于 send 和 fill 的选型、Tab 路由规则、未来会追加的能力等细节，AI 会从 Skill 的 references/panel-api.md 读到完整说明。

2. `@knodo/ui` — 复用平台组件

有些组件实现极复杂，自己写不划算。平台把它们以 @knodo/ui 形式对面板开放。

当前可用	说明
`ChatInterface`	完整的 AI 对话窗口。包含消息列表、流式渲染、命令选择、文件上传、模型切换等。面板可以直接嵌入用

示例（把对话嵌进自己的面板）：

import { ChatInterface } from '@knodo/ui'

export default function MyPanel({ workspaceId }) {
  return (
    <div className="flex h-full flex-col">
      <header>...我的业务内容...</header>
      <div className="flex-1">
        <ChatInterface
          workspaceId={workspaceId}
          welcomeMessage="💡 可以问我任何关于这份数据的问题"
          hideFileSelector
        />
      </div>
    </div>
  )
}

ChatInterface 暴露的 props 已经做过精简（隐藏 UI 控件、定制欢迎语、初始消息等），完整清单在 Skill 的 references/ui-components.md 里。

@knodo/ui 会随着平台迭代逐步增加新组件（看板、Markdown 查看器等）。

3. 直接 `fetch` 后端 API

面板运行在 same-origin，所有 /api/v1/... 接口都能用标准 fetch 调用，凭证自动携带：

fetch(`/api/v1/workspaces/${workspaceId}/tasks`, {
  credentials: 'include',
}).then((r) => r.json())

告诉 AI「我想从后端读任务列表」，AI 会生成这段代码。Skill 的 references/backend-fetch.md 里有常见场景（文件读写、任务列表、对话创建等）的完整示例。

注意事项

面板跑在平台主 React 树里，不是 iframe，所以样式和主题会自动跟随
@knodo/api 和 @knodo/ui 的类型提示需要编辑器支持，AI 直接写就行
所有能力都有版本承诺：@knodo/api 和 @knodo/ui 的破坏性变更会通过 Skill 文档和发版说明告知
不要尝试绕过去 import @/...，会编译失败

app.yaml 约束

字段	说明
`name`	必填
`slug`	必填，小写字母 + 数字 + 连字符
`version`	必填，x.y.z 格式
`views`	必填，至少一个面板定义
`layout.sidebar.hide`	可选，要隐藏的内置面板 ID 数组
`layout.sidebar.rename`	可选，内置面板重命名映射（如 `{ files: 代码 }`）

隐藏 / 重命名内置面板

默认平台空间有 7 个内置面板：

ID	默认文案	说明
`tasks`	任务	任务管理
`files` / `knowledge`	知识	知识库文件树（两个 ID 互为别名）
`changes`	变更	Git 变更视图
`views`	分析	数据视图
`automation`	自动化	定时任务
`guideline`	指引	工作指引
`chat`	——	右侧对话区

你可以告诉 AI：「不要任务和变更面板」→ AI 会在 manifest 加 hide: [tasks, changes]。

也可以重命名：「把知识改名为资料」→ AI 加 rename: { files: 资料 }。

完全沉浸式应用（只留一个面板）也可以：「只保留我的面板，其他全部隐藏，包括对话区」。

用 app-dev 空间能做什么

适合做纯前端的业务工具：

数据看板（内嵌 echarts / recharts 后可视化）
清单工具（待办、笔记、收藏）
表单类应用
轻量 CRM / 跟进工具
文档展示 / 知识库门户

目前不适合做的：

需要重度 UI 组件库的应用（暂不共享 shadcn/ui，但可以用 Tailwind + 原生 HTML）
需要服务端逻辑的应用（只支持纯前端，没有专属后端接口注册机制）
依赖 @knodo/ui 之外组件库的应用（第三方 npm 包需要自己在 TSX 里用 CDN import）

这些会在后续迭代中放开。

常见问题

Q: 预览报"未找到面板组件"？

A: 大概率是 view key 和源码文件名不对齐。让 AI 检查 app.yaml 里 views.<key>.entry 是否等于 ./panels/<key>.js，对应源码是否在 src/panels/<key>.tsx。

Q: 预览报"编译失败"？

A: AppPreview 顶部会显示编译错误，点击具体 view 的「失败」badge 看详细错误行。把错误原文发给 AI，让 AI 修。

Q: 面板里能发消息给对话区吗？

A: 能。import { chat } from '@knodo/api'; chat.send('你的消息') 就会把消息发到当前激活的对话 Tab。如果你只想预填入输入框让用户确认，用 chat.fill('...')。详见面板可用的平台能力章节。

Q: 面板里能调用平台后端 API 吗？

A: 可以，直接 fetch('/api/v1/...', { credentials: 'include' })，凭证会自动带，后端按当前登录用户鉴权。

Q: 发布失败 409 但我是作者？

A: 重启 backend 让 DTO 字段生效（overwrite 字段是新加的）。正常情况下会弹确认对话框让你点「覆盖」。

Q: 全真模式下页面崩了，怎么回去？

A: 右下角逃生悬浮球永远可点，或者双击 ESC。

Q: 发布的 App 别人看不到？

A: 检查可见性：默认是 PRIVATE（只有你自己）。在应用模板管理里编辑可见性为 INTERNAL（组织内）或 PUBLIC（跨组织）。