普通用户建应用的契约骨架(docs/design/normal-user-apps.md 第五部分):蓝图、蓝图留痕、发布单、文件、记录表的模型和迁移,应用的 scope / owner / blueprint_id;运行来源加 trial、personal_app;应用描述的固定版本可以没有版本号(试运行派生的草稿)或改钉蓝图(个人应用),视图来源加 exploratory,组件加 hidden,表单加文件控件;agentlab.blueprint/1 与 bp_* 操作、agentlab.template/1 与关节类型的定义;实例化、试运行、发布单、个人应用、记录表、文件、白话层的接口签名;蓝图、模板、文件、个人应用、蓝图助手的路由桩(501);前端约定 typesBlueprint.ts、接口桩、新建应用与蓝图页的占位路由、termsBlueprint.ts

This commit is contained in:
ThearchyHelios
2026-10-15 09:49:45 +08:00
parent 69c5c74806
commit 7088f4557e
35 changed files with 1144 additions and 17 deletions
+7
View File
@@ -27,6 +27,9 @@ import { EntryPage } from './pages/apps/EntryPage'
import { InstancePage } from './pages/apps/InstancePage'
import { TaskPage } from './pages/apps/TaskPage'
import { AppEditor } from './pages/apps/edit/AppEditor'
// 普通用户建应用:新建应用的起点、蓝图页(F5)
import { NewAppStart } from './pages/blueprints/NewAppStart'
import { BlueprintPage } from './pages/blueprints/BlueprintPage'
import { LoginPage } from './pages/LoginPage'
import { Logo } from './components/Logo'
import {
@@ -175,6 +178,10 @@ export default function App() {
<Route path="/schedules/:id" element={<SchedulesPage />} />
{/* 应用:固定路径(inbox)写在 /apps/:appId 前面,读的人一眼看出它不是应用 id */}
<Route path="/apps" element={<AppsHome />} />
{/* 要在 /apps/:appId 之前:create 不是应用 id */}
<Route path="/apps/create" element={<NewAppStart />} />
<Route path="/blueprints/:blueprintId" element={<BlueprintPage />} />
<Route path="/blueprints/:blueprintId/:section" element={<BlueprintPage />} />
<Route path="/apps/inbox/:taskId" element={<TaskPage />} />
<Route path="/apps/:appId" element={<AppPage />} />
<Route path="/apps/:appId/p/:pageId" element={<AppPage />} />
+58
View File
@@ -0,0 +1,58 @@
/**
* 普通用户建应用的接口(docs/design/normal-user-apps.md §3.10):蓝图、试运行、发布单、模板、文件、个人应用、页面编辑候选、记录。
* 约定在 typesBlueprint.ts。流式的蓝图助手、填关节走 store 里的 SSE(同 copilot),不在这里。
*/
import type { AppSpec } from '../typesApp'
import type {
AppCandidate, Blueprint, BlueprintScope, BlueprintSourceKind, BpOp, FileRef, PlainIssue, PublishPlanRow, RecordsPage,
TemplateInfo, TrialPage, TrialStart,
} from '../typesBlueprint'
import { del, get, patch, post, qs, upload, type UploadOptions } from './http'
export const blueprints = {
create: (body: { source: { kind: BlueprintSourceKind; id?: string; version?: number }; scope: BlueprintScope; name?: string;
template?: string }) => post<Blueprint>('/blueprints', body),
list: (q: { scope?: BlueprintScope } = {}) => get<{ items: Blueprint[] }>(`/blueprints${qs(q)}`),
get: (id: string) => get<Blueprint>(`/blueprints/${encodeURIComponent(id)}`),
/** 卡片上的修改:bp_* 操作,来源记成 user */
patch: (id: string, body: { ops?: BpOp[]; name?: string }) => patch<Blueprint>(`/blueprints/${encodeURIComponent(id)}`, body),
instantiate: (id: string) =>
post<{ blueprint: Blueprint; app_spec: AppSpec; problems: PlainIssue[] }>(`/blueprints/${encodeURIComponent(id)}/instantiate`, {}),
trial: (id: string, body: { inputs?: Record<string, unknown> } = {}) =>
post<TrialStart>(`/blueprints/${encodeURIComponent(id)}/trial`, body),
preview: (id: string, q: { page?: string; run?: string } = {}) =>
get<TrialPage>(`/blueprints/${encodeURIComponent(id)}/preview${qs(q)}`),
publishPlan: (id: string, body: { level: 'published' | 'governed'; first_run?: boolean }) =>
post<PublishPlanRow>(`/blueprints/${encodeURIComponent(id)}/publish-plan`, body),
plan: (planId: string) => get<PublishPlanRow>(`/publish-plans/${encodeURIComponent(planId)}`),
runPlan: (planId: string) => post<PublishPlanRow>(`/publish-plans/${encodeURIComponent(planId)}/run`, {}),
resumePlan: (planId: string) => post<PublishPlanRow>(`/publish-plans/${encodeURIComponent(planId)}/resume`, {}),
// ---- 个人应用(N7)
savePersonal: (id: string) => post<{ app_id: string; blueprint: Blueprint }>(`/blueprints/${encodeURIComponent(id)}/save-personal`, {}),
copyForReview: (id: string) => post<Blueprint>(`/blueprints/${encodeURIComponent(id)}/copy`, {}),
}
export const templates = {
list: () => get<{ items: TemplateInfo[] }>('/templates'),
}
export const files = {
/** 先上传拿引用,再把引用作为表单值提交(N9) */
upload: (file: File, context: Record<string, string>, opts?: UploadOptions) => {
const form = new FormData()
form.append('file', file)
form.append('context', JSON.stringify(context))
return upload<FileRef>('/files', form, opts)
},
url: (fileId: string) => `/api/files/${encodeURIComponent(fileId)}`,
remove: (fileId: string) => del(`/files/${encodeURIComponent(fileId)}`),
}
export const personal = {
refresh: (appId: string) => post<{ run_id: string; remaining: number }>(`/apps/${encodeURIComponent(appId)}/refresh`, {}),
submitReview: (appId: string, body: { to: { kind: 'user' | 'group'; name: string }[]; note?: string }) =>
post<{ task_id: string }>(`/apps/${encodeURIComponent(appId)}/submit-review`, body),
candidates: (appId: string) => get<{ items: AppCandidate[] }>(`/apps/${encodeURIComponent(appId)}/candidates`),
records: (appId: string, q: { table?: string; cursor?: string; history?: boolean } = {}) =>
get<RecordsPage>(`/apps/${encodeURIComponent(appId)}/records${qs(q)}`),
}
+8
View File
@@ -28,6 +28,8 @@ import { apps, ledger } from './apps'
import { actions, tasks } from './tasks'
import { auth, identity } from './auth'
import { capabilities, endpoints, notify } from './capabilities'
// 普通用户建应用(typesBlueprint.ts 是接口约定)
import { blueprints, files, personal, templates } from './blueprints'
// 请求层搬到了 http.ts(见那边的说明)。原先从这里导出的照旧从这里导出,调用方不用改;
// 请求函数也一并转出,给不在 api/ 下、又想直接发请求的地方用。api/ 下的命名空间文件请直接从 http.ts 导入
@@ -865,6 +867,12 @@ export const api = {
capabilities,
endpoints,
notify,
// ---- 普通用户建应用(typesBlueprint.ts 是接口约定) ----
blueprints,
templates,
files,
personal,
}
/**
+1
View File
@@ -5736,3 +5736,4 @@ export const CAPABILITY_REVIEW_TEXT: typeof CATALOG_REVIEW_TEXT = {
// 应用平台使用面的文案(FE-5 维护)。调用方照旧从 lib/terms 导入
export * from './termsApp'
export * from './termsBlueprint'
+12
View File
@@ -0,0 +1,12 @@
/**
* 普通用户建应用的文案(docs/design/normal-user-apps.md 第四部分):新建应用的起点、蓝图卡片、试运行、发布摘要。
* 包 F5 独占这个文件;页面编辑、文件控件、记录列表、个人应用的文案在 termsApp.ts(包 F6)。由 terms.ts 统一再导出。
*/
export const NEW_APP_TEXT = {
title: '新建应用',
}
export const BLUEPRINT_TEXT = {
title: '应用蓝图',
}
+2 -1
View File
@@ -60,7 +60,8 @@ export function backfillTargets(spec: AppSpec, current: AppVersionRow, previous:
if (!alias || v.source.kind === 'instance' || current.dispositions?.[alias] !== 'recompute') continue
const now = current.pins.find((p) => p.alias === alias)
const before = previous.pins.find((p) => p.alias === alias)
if (!now || !before || before.version === now.version) continue
// 已发布的应用版本里钉住项都有版本号;没有的(个人应用)谈不上升版
if (!now || !before || now.version == null || before.version == null || before.version === now.version) continue
const max = seriesDepth(spec, view)
if (max > 0) out.push({ view, alias, from: before.version, to: now.version, max })
}
@@ -361,11 +361,13 @@ function useViewNodes(view: string): { id: string; label: string }[] {
const pin = draft.pins.find((p) => p.alias === source?.pin) ?? (draft.pins.length === 1 ? draft.pins[0] : undefined)
const [nodes, setNodes] = useState<{ id: string; label: string }[]>([])
useEffect(() => {
if (!pin) { setNodes([]); return }
const key = `${pin.workflow_id}@${pin.version}`
// 还没发布的(试运行派生的草稿)、个人应用的钉住项没有工作流版本可取
if (!pin || !pin.workflow_id || pin.version == null) { setNodes([]); return }
const { workflow_id: wid, version } = pin
const key = `${wid}@${version}`
let p = graphCache.get(key)
if (!p) {
p = api.workflows.version(pin.workflow_id, pin.version)
p = api.workflows.version(wid, version)
.then((v) => (v.graph?.nodes ?? []).map((n) => ({ id: n.id, label: String(n.data?.label ?? n.id) })))
p.catch(() => graphCache.delete(key))
graphCache.set(key, p)
@@ -450,7 +452,7 @@ function ViewsPanel() {
<select className="field h-7 py-0 text-xs" value={v.source.pin ?? ''} aria-label={T.viewPin} title={APP_TERM_TEXT.pin}
onChange={(e) => set(key, { source: { ...v.source, pin: e.target.value || null } })}>
<option value="">{T.viewPin}</option>
{draft.pins.map((p) => <option key={p.alias} value={p.alias}>{p.alias} · v{p.version}</option>)}
{draft.pins.map((p) => <option key={p.alias} value={p.alias}>{p.alias}{p.version != null ? ` · v${p.version}` : ''}</option>)}
</select>
)}
{v.source.kind === 'latest_sealed' && (
+6 -3
View File
@@ -76,9 +76,12 @@ export function PinsSection() {
setDraft((s) => ({ ...s, pins: s.pins.map((p, j) => (j === i ? { ...p, ...patch } : p)) }))
const rederive = async (pin: AppPin) => {
// 还没发布的(试运行派生的草稿)、个人应用的钉住项没有工作流版本可派生
if (!pin.workflow_id || pin.version == null) return
const { workflow_id: wid, version } = pin
if (!(await confirmDialog({ title: T.rederiveTitle, body: T.rederiveBody, confirmLabel: T.rederive, danger: true }))) return
try {
const { spec } = await api.apps.derive({ workflow_id: pin.workflow_id, version: pin.version, name: draft.name })
const { spec } = await api.apps.derive({ workflow_id: wid, version, name: draft.name })
setDraft(() => ({ ...spec, name: draft.name, description: draft.description || spec.description }))
toast.ok(T.rederiveDone)
} catch (e) {
@@ -107,12 +110,12 @@ export function PinsSection() {
{(p) => <input {...p} className="field mono text-xs" value={pin.alias} onChange={(e) => update(i, { alias: e.target.value })} />}
</Field>
<div className="min-w-0 pb-1.5 text-xs">
<div className="truncate font-medium">{nameOf(pin.workflow_id)}</div>
<div className="truncate font-medium">{pin.workflow_id ? nameOf(pin.workflow_id) : '—'}</div>
<div className="mono text-2xs text-faint">{T.pinHash(pin.graph_hash || '')}</div>
</div>
<Field label={T.pickVersion}>
{() => (
<PublishedVersionPicker compact workflowId={pin.workflow_id} value={pin.version}
<PublishedVersionPicker compact workflowId={pin.workflow_id ?? ''} value={pin.version}
onChange={(v) => v && update(i, { version: v.version, graph_hash: v.graph_hash ?? '',
level: v.level ?? null })} />
)}
@@ -0,0 +1,12 @@
import { useParams } from 'react-router-dom'
import { EmptyState } from '../../components/ui'
import { BLUEPRINT_TEXT } from '../../lib/terms'
/**
* 蓝图页(docs/design/normal-user-apps.md §4.2–§4.4):左边对话、右边卡片;试运行;发布摘要(搭建者)/ 存成我的应用(使用者)。
* 骨架阶段是占位,包 F5 实现。
*/
export function BlueprintPage() {
const { blueprintId } = useParams()
return <EmptyState title={BLUEPRINT_TEXT.title} body={blueprintId ?? ''} />
}
@@ -0,0 +1,10 @@
import { EmptyState } from '../../components/ui'
import { NEW_APP_TEXT } from '../../lib/terms'
/**
* 新建应用的三个起点(docs/design/normal-user-apps.md §4.1):说说你要什么、从场景模板开始、从已有的开始。
* 骨架阶段是占位,包 F5 实现。
*/
export function NewAppStart() {
return <EmptyState title={NEW_APP_TEXT.title} body="" />
}
+17 -5
View File
@@ -67,6 +67,8 @@ export interface AuditRow {
export type FormWidget =
| 'text' | 'textarea' | 'number' | 'integer' | 'date' | 'datetime' | 'select' | 'radio' | 'multiselect'
| 'checkbox' | 'principal' | 'note' | 'json'
/** 文件(N9):字段 type 为 object,值是上传后拿回的引用 FileRef(typesBlueprint.ts) */
| 'file'
export interface FormField {
type: 'string' | 'number' | 'integer' | 'boolean' | 'array'
@@ -111,11 +113,14 @@ export type Disposition = 'recompute' | 'dual' | 'incomparable'
export interface AppPin {
alias: string
workflow_id: string
version: number
/** 共享应用钉工作流版本;个人应用(docs/design/normal-user-apps.md N7)写 blueprint,workflow_id 为空 */
workflow_id: string | null
/** 还没发布(蓝图试运行时派生的草稿)、或个人应用时为空 */
version: number | null
graph_hash: string
level?: string | null
use: PinUse
blueprint?: string | null
}
export interface AppEntry {
@@ -128,7 +133,8 @@ export interface AppEntry {
}
export interface AppViewSource {
kind: 'latest_sealed' | 'on_demand' | 'instance'
/** exploratory 只在个人应用里合法:最近一次成功封存的探索运行(N7) */
kind: 'latest_sealed' | 'on_demand' | 'instance' | 'exploratory'
pin?: string | null
from?: string | null
params?: FormSchema | { $ref: string } | null
@@ -146,6 +152,8 @@ export interface AppComponent {
bind?: AppBinding | null
visible?: string | null
scope?: string | null
/** 作者隐藏了它(N6):解析时跳过,编辑状态下画成半透明 */
hidden?: boolean
children?: AppComponent[]
}
@@ -216,6 +224,10 @@ export interface AppSummary {
/** 当前用户的授权(关登录时为 manage) */
my_role: GrantRole | null
updated_at: string
/** 个人应用(N7):只有拥有者看得见、跑探索运行;老服务端不给时按 shared */
scope?: 'shared' | 'personal'
owner?: string | null
blueprint_id?: string | null
}
export interface AppDetail extends AppSummary {
@@ -306,8 +318,8 @@ export interface Stamp {
}
export interface ViewSourceState {
/** 来源的种类:按需视图(on_demand)才有「刷新」 */
kind?: 'latest_sealed' | 'on_demand' | 'instance'
/** 来源的种类:按需视图(on_demand)才有「刷新」;试运行解析时为 trial,个人应用为 exploratory */
kind?: 'latest_sealed' | 'on_demand' | 'instance' | 'exploratory' | 'trial'
state: 'ok' | 'empty' | 'running' | 'stale' | 'error'
run_id: string | null
stamp: Stamp | null
+190
View File
@@ -0,0 +1,190 @@
/**
* 普通用户建应用的接口约定(docs/design/normal-user-apps.md 第三部分):蓝图、场景模板、试运行、发布单、文件、记录。
* 和后端 app/blueprints/spec.py、app/db/models_blueprints.py 一一对应。改这里要同时改后端(骨架阶段冻结)。
*/
import type { AppSpec, LintIssue, ViewModel } from './typesApp'
// ---------------------------------------------------------------- 蓝图 agentlab.blueprint/1
export type ItemSource = 'user' | 'assistant' | 'template' | 'catalog' | 'caliber'
export type ItemStatus = 'confirmed' | 'proposed' | 'missing'
/** 卡片上的一项:值、来源、状态,可选一句「为什么」 */
export interface BpItem<T = unknown> {
value: T | null
source: ItemSource
status: ItemStatus
why?: string | null
}
export interface BpDataItem {
id: string
label: BpItem<string>
unit: BpItem<string>
/** 对到 {source, table} */
table: BpItem<{ source: string; table: string }>
measure: BpItem<string>
date: BpItem<{ column: string; rule?: string }>
filter: BpItem<string>
grain: BpItem<string>
/** 复用已发布的口径卡 */
reuse?: { workflow_id: string; version: number; node_id: string; metric_id: string } | null
}
export interface BpPrincipal { kind: 'user' | 'group' | 'slot' | 'initiator'; name: string }
export interface BpStep {
id: string
label: BpItem<string>
who: BpItem<BpPrincipal[]>
policy: BpItem<{ kind: 'any' | 'all' | 'quorum'; m?: number }>
due: BpItem<string>
on_timeout: BpItem<{ action: 'remind' | 'escalate' | 'reject'; to?: BpPrincipal[] }>
threshold: BpItem<{ field: string; op: string; value: number | string }>
}
export interface BpField { name: string; spec: BpItem<Record<string, any>>; sensitive: boolean }
export interface BpWriteback {
capability: BpItem<string>
mapping: BpItem<Record<string, string>>
confirm: BpItem<boolean>
}
export interface BpAccess {
use: { kind: string; name: string }[]
observe: { kind: string; name: string }[]
manage: { kind: string; name: string }[]
}
export interface BpAsk { id: string; question: string; options: string[]; path?: string | null; answer?: string | null }
export interface BlueprintSpec {
format: 'agentlab.blueprint/1'
purpose: BpItem<string>
template: { id: string; version: number } | null
data: BpDataItem[]
cadence: BpItem<{ preset: 'daily' | 'weekly' | 'monthly'; weekday?: number; day?: number; time: string; tz: string; period?: string }>
people: BpStep[]
fields: BpField[]
writeback: BpWriteback | null
access: BpAccess
asks: BpAsk[]
}
export type BpOpName = 'bp_set' | 'bp_add' | 'bp_remove' | 'bp_ask' | 'bp_template'
export interface BpOp {
op: BpOpName
/** JSON 指针(/data/0/table) */
path?: string | null
value?: unknown
question?: string | null
options?: string[]
template?: { id: string; version: number } | null
}
export type BlueprintScope = 'personal' | 'shared'
export type BlueprintStatus = 'drafting' | 'trialed' | 'published' | 'personal' | 'in_review'
export type BlueprintSourceKind = 'conversation' | 'template' | 'run' | 'workflow_version'
export interface JointState { status: 'filled' | 'pending' | 'refused'; by: 'template' | 'assistant' | 'user'; note?: string | null }
export interface Blueprint {
id: string
name: string
owner: string | null
scope: BlueprintScope
status: BlueprintStatus
spec: BlueprintSpec
template_id: string | null
template_version: number | null
source: { kind: BlueprintSourceKind; id?: string | null; version?: number | null }
conversation_id: string | null
workflow_id: string | null
app_id: string | null
last_trial_run_id: string | null
graph_hash: string | null
joints: Record<string, JointState>
copied_from: string | null
/** 蓝图检查(bp.* / tpl.*),带白话 */
issues?: PlainIssue[]
created_at: string
updated_at: string
}
// ---------------------------------------------------------------- 白话层
export type ProblemWho = 'you' | 'assistant' | 'admin'
export interface Plain { title: string; why: string; who: ProblemWho; action: string }
/** 检查问题加上白话(后端 app/plain.with_plain);没登记白话的 plain 为空,照旧显示 message */
export type PlainIssue = LintIssue & { plain?: Plain | null }
// ---------------------------------------------------------------- 场景模板
export interface TemplateCard { card: string; note: string }
export interface TemplateInfo {
id: string
version: number
label: string
description: string
applies_when: string
cards: TemplateCard[]
/** 个人应用能用哪一部分;不能用为 null */
personal: string | null
tags: string[]
}
// ---------------------------------------------------------------- 试运行
export interface TrialStart { run_id: string; blueprint: Blueprint }
/** 试运行解析出来的一页:和应用页同一个视图模型,印章 trial=true */
export type TrialPage = ViewModel
// ---------------------------------------------------------------- 发布单
export type PlanStepKind =
| 'save_version' | 'preflight' | 'publish_workflow' | 'create_schedule' | 'create_app' | 'publish_app'
| 'enable_schedule' | 'grant' | 'first_run'
export interface PlanStep {
kind: PlanStepKind
status: 'pending' | 'done' | 'failed' | 'skipped'
/** 这一步产出的对象 id(工作流版本、定时任务、应用……) */
result?: Record<string, unknown> | null
error_code?: string | null
message?: string | null
at?: string | null
}
export interface PublishPlanRow {
id: string
blueprint_id: string
level: 'published' | 'governed'
graph_hash: string | null
status: 'planned' | 'running' | 'stopped' | 'done'
steps: PlanStep[]
/** 白话摘要:每一步一句 */
summary: { step: PlanStepKind; text: string }[]
problems: PlainIssue[]
options: { first_run?: boolean }
}
// ---------------------------------------------------------------- 文件、记录
/** 上传后拿回的引用,作为表单值提交 */
export interface FileRef { file_id: string; name: string; size: number; sha256: string; type: string }
export interface RecordRow {
_id: string
_seq: number
_submitted_by: string | null
_submitted_at: string
_supersedes: string | null
/** 被更正过(有更新的一行指向它) */
superseded?: boolean
values: Record<string, unknown>
}
export interface RecordsPage { table: string; version: number; columns: { name: string; label: string; type: string }[]; items: RecordRow[]; mine_only: boolean }
// ---------------------------------------------------------------- 页面编辑
/** 「加一张数据卡片」的候选(GET /api/apps/{id}/candidates) */
export interface AppCandidate { kind: 'metric' | 'report' | 'table' | 'series'; label: string; group: string; component: AppSpec['pages'][number]['body'][number] }