# 普通用户建应用：方案

> 设计文档 · 草案，待拍板 · 2026-10-15
>
> - 本文档只定方案，不含代码改动。第五部分「实施组织」在本文签字后另行审批，再开工。
> - 代码位置按 **main@69c5c74**（应用平台合入后）标注，三路只读调研逐条核过。
> - 承接《应用平台与助手按需查看：总方案》（`docs/design/app-platform-and-look.md`，下称「总方案」）。本文不改它，引用写作「总方案 §x.y」。
> - 文中出现的数据源名、表名、应用名、人名都是虚构的。本文不含本机开发环境的计数。

## 目录

- 摘要
- 第一部分 现状与问题
- 第二部分 关键决定（N1–N11）
- 第三部分 规格
- 第四部分 界面
- 第五部分 实施组织
- 第六部分 验证与验收
- 第七部分 风险与对策
- 第八部分 待拍板
- 附录 A 代码位置索引 · B 术语

---

## 摘要

**问题。** 应用平台已经能做相当复杂的应用：多级审批、会签、时限与升级、写回外部系统、看板、按新口径补算。但能做出来的只有懂编排的人。普通人卡在这几处：

- 必须先在画布上搭好并发布工作流，应用只能从已发布版本生成；
- 从问数据出发要跳四次：做成应用 → 提取工作流 → 去画布发布 → 回来做成应用；
- 满屏专家词：固定版本、处置、岗位绑定、视图来源、出具契约、口径卡、`cell(nodes.fetch, 0, 'gmv')`、`PT48H`；
- 发布前看不到真数，判断不了「这是不是我要的」；
- 两类最常见的需求做不了：上传文件，以及「填报登记」（每次提交存一行，再汇总着看）。

**做法。** 把「搭应用」改成「说需求 → 看蓝图 → 用真数试 → 确认」，用的就是项目的路线「模板定骨架、助手填关节」：

1. **一条链路，两种终点**（N1）。说需求、蓝图、模板填关节、试运行，两类人走同一条链路，只在最后一步分开：
   - 搭建者：一次确认，发布成正式应用；
   - 使用者：存成**个人应用**，只自己看得见、只读、跑探索运行，想给别人用就提交给搭建者审核发布。
2. **应用蓝图**（N2）：用户的话和工作流、应用之间的中间件，用白话卡片呈现。卡片写的是看哪些数、谁发起谁审批、多久更新一次、要不要写回系统，用户逐张确认或修改。卡片的改动是确定性的操作，不是让模型重写。
3. **场景模板**（N3）：首批五个——周期看板、审批流程、异常处置、填报登记、核对写回。骨架锁住，助手只能填模板声明的「关节」：取数的 SQL、口径卡的指标式；其余关节由蓝图确定性地填。
4. **用真数试运行**（N4）：跑一次探索运行，草稿应用直接对着这次运行解析，印章写「试运行」。流程类的审批步骤派给试运行的人自己点，写入一律走测试环境或演练。
5. **一次确认发布**（N5）：服务端按「发布单」编排——保存版本、发布工作流、建应用、绑岗位、建定时任务、授权、跑第一次——每步可续做。确认前给一页白话摘要；查出的问题分成「你来定」「助手可以修」「要找管理员」三类。
6. **在页面上直接改**（N6）：应用页进入编辑状态后点哪改哪；改取数逻辑就回到蓝图，重走试运行和发布单，口径变不变用白话说清。
7. **补两个能力缺口**：
   - 记录表（N8）：平台托管、只许追加，用序号钉版本，按授权分行可见；
   - 文件（N9）：按哈希存，以引用进运行输入，可以交给 agent 读，也可以作为一期数据导入。
8. **白话层**（N10）和**生成的耗时与稳定性**（N11）：所有检查问题有一份白话说法；补上问数据和画布两端「助手反问」的收尾。

**已拍板**（2026-10-14、10-15）：

- 两类人都做，共用一条链路（N1）；
- 填报登记要做行级可见（N8）；
- 表单只许加字段，改字段或删字段就出新的表版本，旧记录照原样保留（N8）；
- 试运行只给有管理权限的人看（N4）；
- 先写设计文档，签字后实施；验收结束后实施（已结束）。

**待拍板**：见第八部分，共 8 项，每项附推荐。

---

## 第一部分 现状与问题

### 1.1 现在建一个应用要走的路

一个从零开始的看板应用，最少要按顺序做这些事，每步各自提交：

1. 在画布上搭工作流并保存，形成版本快照；
2. 发布工作流（受管级只有管理员能发）；
3. 建定时任务——必须在第 4 步之前，否则派生出来的视图不绑定时任务（`apps/derive.py:85-90`）；
4. 派生应用草稿（`POST /api/apps/derive`，不落库）；
5. 建应用（`POST /api/apps`）；
6. 绑岗位（`PATCH draft_bindings`）；
7. 授权（`PUT grants`，立即生效）；
8. 发布应用。

中途失败会留下半截状态：已发布但没有应用的工作流、按 cron 在跑的定时任务、停在草稿的应用。草稿应用的授权已经生效，使用者打开会得到 409「还没有发布」（`api/apps.py:83`）。这些步骤分散在画布、定时任务、应用编辑器三处。

### 1.2 普通人卡在哪

| 卡点 | 现象 | 出处 |
|---|---|---|
| 要会搭图 | 应用只能钉已发布版本 | 总方案 A1 |
| 术语 | 口径卡表达式、ISO 8601 时长、出具契约 JSON、视图来源、处置 | 端到端验收「普通用户视角」13 条 |
| 看不到真数 | 草稿预览只读钉住版本已有的封存运行，新应用没有 | `apps/resolve.py:454-476` |
| 路径长 | 问数据做成应用要跳四次 | `ChatPage.tsx:484-492` |
| 做不了 | 没有文件控件；没有平台托管的可写表 | `apps/spec.py:35-38`；`data/table_versions.py:1-33` |

### 1.3 现有零件（直接复用）

- **生成管线**：`Generation` 加 `Applier`/`Checker` 协议，新的生成目标插进来就能用（`api/copilot_gen.py:567`，`look/base.py:87-110`）。
- **按需查看**：表、能力、工作流版本三类对象（`look/service.py`）。
- **护栏**：
  - 润色边界 `polish_problem`（`apps/ops.py:264`）；
  - 自动修复的 `forbidden_changes`（`engine/autofix.py:1240`）。

  两者都是「只许改哪些」的确定性护栏，模板关节照这个写法。
- **确定性派生**：`derive_app`（`apps/derive.py`）。
- **从运行提取工作流**：`/copilot/from-run`，带来源记录 `workflows.origin`（`api/copilot.py:2468-2550`）。
- **数据目录**：表的中文名、粒度、业务日期、列的含义和度量类型（`data/catalog.py:12-21`），是把白话对到表的依据。
- **按运行解析**：视图来源 `instance` 已经能按给定的那次运行解析，不查类别和哈希（`apps/resolve.py:541-546`）。
- **所有运行都封存**，探索运行也一样（`engine/runner.py:1013-1045`）；探索运行的写入走测试环境或演练（`capabilities/endpoints.py:101`）。
- **问数据对使用者的约束**（`auth/chat_policy.py`）：
  - 节点和工具的白名单；
  - 强加 `MASK_RESULTS`、`READ_ONLY`（`api/runs.py:108-123`）；
  - 记忆隔离。
- **文件相关**：
  - 上传限额 `read_upload`（`api/datasources.py:905-918`）；
  - 按哈希存原件 `raw_store`（`data/raw_store.py:33-43`）；
  - 按配方导入「上传新一期」（`api/table_imports.py:160-486`）。
- **表版本链**：快照的版本链，以及「改列不兼容」的判定 `INCOMPATIBLE_KINDS`（`data/recipe_accumulate.py:38-41`）。
- **数据版本**：data_versions 进封存范围和印章（`engine/runner.py:242-262`，`apps/resolve.py:238-240`）。
- **名录**：`auth/directory.py`，按登录方式核对人和组。
- **白话分类的依据**：
  - 检查问题已经有 `code`；
  - 自动修复有 `kind: auto|choice|assist`（`engine/autofix.py:125-141`）；
  - 只能由人处理的有 `APP_HUMAN_ONLY`（`api/copilot_gen.py:416-421`）。

### 1.4 核实过的缺口

| # | 缺口 | 出处 |
|---|---|---|
| G1 | 没有带参数的模板，也没有「模板里哪些地方能改」的机制；GraphSpec 只有 nodes/edges/viewport/defaults；「以此模板新建」只是复制 | `engine/schema.py:115`；`WorkflowPicker.tsx:354`；`api/workflows.py:249` |
| G2 | 应用视图只认正式运行；印章没有「探索」「试运行」 | `apps/resolve.py:95,149,203-221` |
| G3 | 探索运行没有版本号和哈希，三种视图来源都取不到它 | `engine/launch.py:166-174` |
| G4 | 跨步没有事务：工作流发布撤不回（只能退役），应用只能归档、不能删 | `api/apps.py:273` |
| G5 | 检查问题只有技术说法，没有白话 | `engine/governance.py:217-271` |
| G6 | 只问不改的一轮：问数据的 store 没有 ask 分支，可能一直停在「进行中」、问题不进历史；画布也不记这一轮 | `store/chat.ts:1433`；`store/studio.ts:2149` |
| G7 | 使用者不能建应用；应用视图、印章、读权限都只认正式运行 | `api/apps.py:191`；`auth/access.py:74-96` |
| G8 | 工件库只存 JSON；运行输入不能引用文件；入口提交是 JSON | `core/artifact_store.py:45-115`；`engine/nodes/io.py:14-33` |
| G9 | 平台托管的表都是不可变快照，只能整期替换或按期累积；没有逐行追加，也没有行级可见 | `data/table_versions.py:1-33`；`engine/masking.py` |
| G10 | 没有按名字检索的口径库；复用口径只能逐级下拉选 caliber_from | `engine/schema.py:1460`；`Inspector.tsx:1065` |
| G11 | 组件没有「隐藏」字段，只能删掉或写可见性表达式；改动要先保存才看得到 | `apps/spec.py:97-107`；`apps/resolve.py:632` |
| G12 | 生成没有并行、没有提示缓存；问数据校验不过时前端整轮重来 | `look/service.py:192`；`store/chat.ts:1241` |

### 1.5 理念对照

本方案不加新理念，把总方案的八条用到「创建」上：

- **P1 照实说**：试运行、探索、个人应用的数都在印章上写明来历；检查问题用白话说清是什么、为什么、谁来改。
- **P2 留痕**：
  - 蓝图每一次改动都留痕；
  - 发布单每一步的结果都留痕；
  - 生成的工作流记下出自哪个蓝图、哪个模板。
- **P3 不挡生成**：模型失败时，模板照样能按蓝图确定性地实例化，缺的关节标「待填」交给人。
- **P4 只读与遮罩**：
  - 个人应用只读、结果遮罩；
  - 记录表按授权分行可见；
  - 文件只给读得到那次运行或那一行的人。
- **P5 一种说法**：白话层只有一份，按问题编号映射。
- **P6 模板定骨架**：模板的节点和连线锁死，助手只填声明过的关节。
- **P7 界面层不放逻辑**：卡片的修改是对蓝图的确定性操作；页面上直接改走的仍是应用操作。
- **P8 生效可查可对账**：记录表的写入走动作（生效记录、幂等键）；文件的哈希进封存。

不可回退决定的对照见 §2.12。

---

## 第二部分 关键决定

每个决定写四样：决定、理由、否决的做法、代价。

### 2.1 N1 一条链路，两种终点

**决定**

链路是：说需求 → 蓝图 → 选模板并实例化 → 试运行 → 终点。

- **起点三个**，都落到同一个蓝图：
  1. **说说你要什么**：开一段蓝图对话，助手先问清楚，再整理成卡片；
  2. **从场景模板开始**：选一个模板，卡片按模板预置；
  3. **从已有的开始**：从问数据的一轮回答（运行）开始，或者从一个已发布的工作流版本开始。前者用 from-run 提取，后者直接导入图，模板记为「自由形」。
- **终点两种**：
  - **搭建者**：发布单（N5）一次确认，产出已发布的工作流、正式应用、定时任务、授权；
  - **使用者**：存成个人应用（N7），自己用。想给别人用就「提交审核」，搭建者打开同一个蓝图，走试运行和发布单。

**理由**：一条链路只维护一份，「问 → 建」的沉淀路径是现成的（P2）。使用者沉淀出来的东西不绕过发布门禁：个人应用永远是探索，正式应用只能由搭建者发布（不可回退决定：正式运行只从已发布版本发起）。

**否决的做法**

- 给使用者一个简化版画布：等于让使用者搭图，权限和门禁都要另开口子；
- 使用者的应用也走正式发布：让 user 角色产出承诺，违背角色分层。

**代价**：个人应用和正式应用是两种对象状态，界面要说清区别。

### 2.2 N2 应用蓝图 `agentlab.blueprint/1`

**决定**

- **定位**：蓝图是用户的话和工作流、应用之间的结构化中间件，存成一个可变对象 `Blueprint`。它有：
  - 拥有者、可见范围（个人 / 共享）；
  - 状态：起草中 / 试运行过 / 已发布 / 个人应用 / 审核中；
  - 来源：对话、模板、运行、工作流版本。
- **一张蓝图由几张「卡片」组成**，每张卡片对应用户能理解的一件事：

| 卡片 | 内容 | 落到哪里 |
|---|---|---|
| 目的 | 一句话：这个应用解决什么问题、给谁用 | 应用名称、说明 |
| 场景 | 选定的模板（N3） | 骨架 |
| 看哪些数 | 每一项：白话名、对到哪个库哪张表（或复用哪张已发布的口径卡）、粒度、业务日期、筛选条件、单位 | SQL 关节、口径卡关节 |
| 多久更新 | 每天、每周一、每月 1 日……时区；统计哪一期（本周、上周、上月） | 定时任务、入口字段的模板值 |
| 谁来做 | 发起人、各步处理人（人、组、岗位）、几个人同意算通过、时限、超时给谁 | 人工节点配置、岗位绑定 |
| 填什么 | 表单字段：名称、类型、必填、上下限、选项、文件 | 入口表单、待办表单、记录表的列 |
| 写回哪里 | 目标能力（从能力登记里选）、字段对应、要不要人确认；能力没登记查询的，再定结果不明时谁去核实（只由人定，同「谁能看」） | 调用工具节点、应用的核实岗位 |
| 谁能看 | 使用、查看全部、管理三档的人和组 | 授权 |

- **每一项都带状态**，照数据目录项的写法 `{value, source, status}`：
  - `source`：用户填的 / 助手提的 / 模板默认 / 从目录或口径卡对到的；
  - `status`：已确认 / 待确认 / 缺。

  试运行前，所有「缺」都要补齐；「待确认」可以先试运行，但发布时必须确认。
- **助手只提议**：输出 `bp_*` 操作（`bp_set`、`bp_add`、`bp_remove`、`bp_ask`），由 `BlueprintApplier` 确定性落地。用户在卡片上改，走的也是同一组操作，只是 `source` 记成用户。
- **对到数据靠 look**：助手看「看哪些数」时，先查数据目录（表的中文名、粒度、业务日期、列的度量类型），再查已发布工作流里的口径卡（N2 新增 look 类别 `caliber`，补 G10）。对到已有口径卡时优先复用（caliber_from），不重写指标式。
- **反问**：缺的信息由助手用 `bp_ask` 问，一次问一件事、给出候选（例如「销售额按下单日还是支付日算？」并附两个选项）。这一轮就此结束，回答是下一轮（G6 一并修好，N11）。

**理由**

- 卡片是用户能判断对错的颗粒度（P1）；
- 模型产出的是提议，落地是确定性的（P7）；
- 每一项都有来源和状态，不会把模型猜的当成用户说的（P2）。

**否决的做法**

- 让模型直接生成工作流再给用户看图：普通人看不懂图；
- 一问一答的长表单向导：问题顺序固定，答不上来就卡住；
- 蓝图只存在前端：刷新就丢，也没法交给搭建者审核。

**代价**：多了一种对象和一套操作；模板变了，蓝图的卡片要跟着兼容（蓝图记下模板版本）。

### 2.3 N3 场景模板 `agentlab.template/1`：骨架锁住，关节可填

**决定**

- **模板是一份登记**，和组件目录同一种做法（总方案 A2）：
  - 后端 `app/apps/templates/`，每个模板一个模块；
  - 开发者扩展时，模板定义、实例化函数、测试三样都要给，缺一样启动即报错。
- **一个模板包含**：
  - **骨架**：带占位的图（节点和连线固定）；
  - **关节**：骨架里允许填的位置，每个都有类型、来源、校验；
  - **应用骨架**：页面布局，用派生规则加模板自带的组件排布；
  - **卡片映射**：蓝图的哪张卡片填哪些关节；
  - **说明和适用条件**：给用户和助手看。
- **关节分两种**：
  - **确定性关节**：由蓝图直接填，不经模型。包括：
    - 表单字段 → 入口节点 fields；
    - 处理人和策略 → 人工节点 assignee/policy/due/on_timeout；
    - 金额线这类规则 → 分支节点的比较条件，只许「字段 比较 常量」；
    - 更新频率 → 定时任务；
    - 写回目标 → 调用工具节点的 tool 和参数映射。
  - **生成关节**：只有两类交给模型——
    - 取数的 SQL（`sql`）；
    - 口径卡的指标式（`metric_expr`，只许 `cell()` 取格加口径卡的算术）。

    模型在 `TemplateApplier` 下工作，只收 `fill_joint` 操作，而且只收这个模板声明过的关节 id，别的一律拒绝并照实交回（照 `polish_problem` 的写法）。
- **护栏**：实例化后的图和骨架逐节点比对，只许关节位置不同，用 `forbidden_changes` 的同一套比对。之后照常走 validate、GraphChecker（SQL 猜列、数据源范围）和发布前检查。
- **来源记录**：生成的工作流写 `workflows.origin = {blueprint_id, template: "<id>@<version>", run_id?}`，补上「只写不读」的现状：WorkflowOut 和版本历史显示「出自蓝图 X、模板 Y」。
- **首批五个**（详见 §3.3）：周期看板、审批流程、异常处置、填报登记、核对写回。外加「自由形」：从已有的运行或工作流导入，没有关节，改图只能回画布。
- **模型失败时**（P3）：生成关节留空、标「待填」，蓝图卡片上提示「这一项助手没填上，请补充或换个说法」；确定性关节照样落地。

**理由**

- 模板定骨架、助手填关节，正是项目路线；
- 关节越少，生成越快、越稳（N11），检查也越有效；
- 锁骨架就锁住了治理关注的结构：出具契约、人工节点、写入位置。

**否决的做法**

- 模板只是一张样例图，复制了让助手随便改：等于自由生成，护栏全靠事后检查；
- 用模板引擎在 JSON 上做字符串替换：类型和校验都丢了；
- 一个模板覆盖所有场景、用大量开关：组合爆炸，测不过来。

**代价**：每个模板要写实例化和测试；用户的需求落在模板之外时，只能走「自由形」，或者由搭建者新增模板。

### 2.4 N4 用真数试运行

**决定**

- **试运行**是一次探索运行，跑的是蓝图实例化出来的、还没发布的图，来源记为 `origin_kind=trial`、`origin={blueprint_id}`。
- **草稿应用对着这次运行解析**：
  - 新增解析模式 `resolve_page(draft=True, trial=run)`；
  - 草稿里所有视图来源（最近封存、按需、本实例）都指向这次运行；
  - 钉住项记成 `{workflow_id, version: null, graph_hash: <这次运行的图哈希>}`。

  沿用 `instance` 分支「按给定运行解析」的路径（`apps/resolve.py:541-546`）。不改 `agentlab.app/1` 的视图来源种类，试运行只是解析时的旁路参数。
- **印章**：
  - 来源写「试运行」；
  - 注明「数据是真的；这不是正式结果，发布后才会按定时任务出数」；
  - 出具档位照实算；没封存的照实写。

  趋势只有一个点时写「试运行只有一次，没有趋势」，不报错（补 `_series` 拿不到钉住项就报错的问题，`apps/resolve.py:813`）。
- **输入**：
  - 看板类：按「多久更新」卡片算出最近一期（例如上一 ISO 周），用户可以改；
  - 流程类：由用户填一份示例表单。
- **流程类的试运行**：
  - 人工步骤派给试运行的人自己（来源记为 `trial`），按钮写「以试运行身份同意/驳回」；
  - 写入一律走测试环境；没有测试环境的演练，不发送；
  - 时限按真实设置显示，但试运行不触发升级——调度跳过 `origin_kind=trial` 的待办。
- **谁能看**：只有对这个蓝图有管理权的人（拍板项）：搭建者看自己的、有 manage 的看共享蓝图的；个人应用的试运行只有拥有者看。试运行是探索运行，遮罩按看的人的角色照常处理。
- **发布时对齐**：发布单按图哈希判断「发布的版本就是试运行过的那张图」：
  - 一致：钉住项直接换成版本，节点 id 一一对上；
  - 不一致（试运行之后又改过）：摘要里写明「发布的内容和最近一次试运行不同」，建议再试一次，不强拦。

**理由**：先看真数再决定（P1）；不发布就不产生正式运行（不可回退决定）；写入不出测试环境（总方案 A5）。

**否决的做法**

- 先发布一个隐藏版本再试：版本表里满是试验版本，退役和口径升版的判断都被污染；
- 用假数据预览：普通人恰恰要看真数才判断得了。

**代价**：试运行要花一次模型或查询的钱；流程类的试运行要人点一遍。

### 2.5 N5 一次确认发布：发布单

**决定**

- **发布单**（`PublishPlan`）是服务端的编排对象：先**算出**要做的每一步和白话摘要，用户确认后**按序执行**，每步的结果记下来；失败了停在那一步，修好后从那一步**接着做**。
- **步骤**（顺序就是为了让中途失败时留下的状态无害）：
  1. **保存版本**：按图哈希判断，已有相同的版本就复用；
  2. **全量预检**（只读）：工作流发布前检查 + 按将要生成的版本跑应用检查 + 定时任务预览 + 名录核对。任何 error 都在这一步停下，什么都没写；
  3. **发布工作流**（受管级只有管理员）；
  4. **建定时任务**（停用状态），这样派生时视图能绑上它；
  5. **建应用、派生、写岗位绑定**；
  6. **发布应用**：钉住项升版时按蓝图里的处置；第一次发布没有处置；
  7. **启用定时任务**；
  8. **授权**：最后一步，避免使用者先看到一个打不开的应用；
  9. **跑第一次**（看板类默认勾选）：立即运行一次，应用一打开就有数。
- **白话摘要**：每一步一句「会发生什么」，例如：
  - 「发布『门店周报』：此后每周一 09:00 按这一版自动出数」；
  - 「张三、李四可以使用；财务组的人负责审批」；
  - 「口径变了：以前的周报按新口径重算（recompute），旧数据留底」。
- **问题分三类**，按问题编号走白话层（N10）：
  - **你来定**：岗位没绑人、处置没选；
  - **助手可以修**：autofix 的 auto/assist、应用检查里不在 `APP_HUMAN_ONLY` 的；
  - **要找管理员**：受管级、降级、内网端点、能力治理。
- **补偿**：
  - 第 3 步之后的失败不撤回已发布的工作流（发布本来就撤不回），摘要照实说「工作流已发布，应用还没有」；
  - 停用的定时任务在应用发布前不会跑，不产生无主的正式运行；
  - 应用停在草稿时不授权，使用者看不到。
- **权限**：执行发布单的人要有其中每一步的权限，预检时就按角色算好（例如搭建者发不了受管级，摘要里直接说）。

**理由**：一次确认、照实摘要（P1）；每一步留痕（P2）；中途失败的状态无害、可续做。

**否决的做法**

- 一个大事务把八步包起来：跨定时任务、应用、工作流的事务在 SQLite 单进程下做得到，但出错后整体回滚会吞掉已经通过的检查结果，用户得从头来；而且发布动作本身就带审计，不应该回滚；
- 前端按顺序调现有接口：刷新页面就丢进度，权限和补偿都在客户端，不可靠。

**代价**：多一个对象和一张表；现有各接口的校验要能被发布单按「只检查不提交」的方式调用。

### 2.6 N6 在页面上直接改

**决定**

- **改呈现**：
  - 有 manage 的人在应用页点「编辑」进入编辑状态，ViewRenderer 叠一层编辑层：按 `data-node` 选中组件（`apps/ViewRenderer.tsx:75-84`），就地改文字、隐藏、上下挪、删除。
  - 落地走现有的应用操作 `app_update`、`app_move`、`app_remove`，自动存草稿，然后按草稿重新解析。
- **加「隐藏」**：组件加 `hidden: true` 字段（补 G11），解析时跳过、编辑状态下照常画成半透明。这和可见性表达式不是一回事：可见性是按运行时条件显示，隐藏是作者不要它。
- **加一张数据卡片**：候选从钉住版本里列，用同一份派生规则 `_results`（口径卡指标、报告、取数节点、趋势），新接口 `GET /api/apps/{id}/candidates`。用户挑一个，就落成一个 `app_add`。
- **改取数逻辑**（「销售额要去掉退款」）：
  - 不在页面上改，回到蓝图：改「看哪些数」卡片 → 重新实例化 → 试运行 → 发布单；
  - 发布单在摘要里用白话说清口径变了、以前的数怎么处理（处置），沿用总方案的口径升版规则。
- **改完要发布**：呈现的改动只进草稿，用户点「发布」走应用发布（不动工作流），沿用现有规则。

**理由**：普通人改看得见的东西最直接（P1）；改取数会动口径，必须经过试运行和处置（不可回退决定：口径升版须处置）。

**否决的做法**

- 页面编辑器允许拖拽任意布局：像素级设计不是目标（总方案 §1.3）；
- 页面上直接改 SQL：绕过试运行和处置。

**代价**：编辑状态和查看状态要共用一套渲染，交互细节要打磨。

### 2.7 N7 个人应用

**决定**

- **对象**：
  - 个人应用是 `scope=personal` 的 App，拥有者是创建它的使用者；
  - 它的图不进工作流表（使用者没有工作流权限），存在蓝图上，带图哈希；
  - 没有应用版本，改了就是改了，每次刷新按当前的图跑。
- **能用的东西**，与问数据同一份白名单（`auth/chat_policy.py`）：
  - 节点：input、llm、agent、report、output、retrieve、transform、branch、metrics、merge；
  - 工具：只读内置工具和只读数据源查询；
  - 运行时强加 `MASK_RESULTS`、`READ_ONLY`；
  - 不能有人工节点、不能写入、不能调写入能力。

  能用的模板因此只有：周期看板、异常处置的「只看」部分、填报登记的「只看自己的」汇总。
- **刷新**：
  - 打开时用最近一次成功的刷新；
  - 点「刷新」发起一次探索运行（`origin_kind=personal_app`），身份是拥有者；
  - 受每日上限约束，和按需视图共用设置项 `apps.on_demand_daily_limit`，按人计。
  - 是否允许每天自动刷新，见待拍板 Q4。
- **视图来源**：新增 `exploratory`，只在个人应用里合法——取这个应用、这个拥有者、这张图哈希下最近一次成功封存的探索运行。印章来源写「探索 · 未经发布审核」，档位照实写。
- **谁看得见**：只有拥有者。管理员在设置里看得到「谁有几个个人应用」，可以归档，但不看内容（P4）。
- **提交审核**：
  - 拥有者点「提交审核」，选一位搭建者，或者交给搭建者组；
  - 开一条待办（种类 `review`，派给对方）；
  - 搭建者打开时得到这个蓝图的一份**共享副本**（原个人应用不动），在副本上走试运行和发布单；
  - 发布后通知提交人，提交人自己决定个人应用留不留。
- **开关**：管理员设置 `apps.user_personal_apps`，默认关（同问数据的开关，待拍板 Q3）。

**理由**：使用者能自助（产品目标）；个人应用永远是探索、只读、遮罩（P4，不可回退决定：没发布的图只能跑探索）；共享必须经搭建者发布（承诺由搭建者签）。

**否决的做法**

- 给使用者开「个人工作流」：工作流表的权限、门禁、定时任务全要另开一套；
- 个人应用允许分享给别人：等于绕过发布门禁。

**代价**：视图来源多一种、印章多一种；个人应用的图和工作流的图是两种存法。

### 2.8 N8 记录表（填报登记）

**决定**

- **存储**：每个记录表一个平台托管的 SQLite 文件（`data/records/<表 id>.db`），只许追加。
  - 每行带系统列：`_seq`（自增序号）、`_id`、`_submitted_by`、`_submitted_at`、`_run_id`（哪次运行写的）、`_supersedes`（更正时指向被更正的行）、`_schema_version`。
  - 业务列由「填什么」卡片生成。
- **作为数据源**：登记成 `origin=records` 的只读数据源，看板照常用 `db_query__<名字>` 查，数据目录照常起草。
- **写入只经动作**：
  - 新增平台内置能力 `records.append`（效果：写入；允许无人值守，因为平台自己的表、幂等键就是动作键）；
  - 填报登记模板的骨架是：入口 → [可选的审批] → 调用工具节点 `records.append` → 成果；
  - 生效记录、幂等、审计全部沿用总方案 A5，一次提交只落一行，重放不会重复写。
- **更正不改原行**：更正是一次新的提交，带 `_supersedes`。默认查询看「当前有效」的行（没被更正过的），更正历史可查。
- **钉版本**：
  - 运行开始时，在 data_versions 里记下这张表的高水位 `_seq`；
  - 查询时连接上建同名的 **TEMP VIEW**（SQLite 解析不带库名的表名时，先找 temp 库），只露出 `_seq ≤ 高水位` 的行。

  于是同一次运行查几遍都是同一份数，印章写「数据截至第 N 条」，按需缓存键也带上它（P8）。
- **行级可见**：
  - 同一套临时视图再加一条按人过滤：`use` 只看 `_submitted_by = 自己`，`observe` 和 `manage` 看全部（拍板项）；
  - 过滤在查询工具的连接上做，模型和 SQL 都绕不过去。
  - **看板的汇总**：看板读的是正式运行的封存结果，正式运行以服务身份跑、看到全部行，所以汇总是全量的。这是作者的选择，发布单摘要里写明「使用者能看到全部提交的汇总数」。
  - **逐行列表**：用新组件 `records_list`，每次打开按看的人实时过滤（同 `instance_list`），不走封存。
- **表单变了**：
  - 只加可选字段：`ALTER TABLE ADD COLUMN`，同一表版本；
  - 改类型、删字段、加必填字段：出新的表版本（新文件 `<表 id>.v2.db`），旧记录照原样保留。不兼容的判定沿用 `INCOMPATIBLE_KINDS`。
  - 应用版本钉住表版本；看板要跨版本汇总时，由模板生成 `UNION ALL` 的视图，列对不上的补空。
- **遮罩**：业务列可以在「填什么」卡片里标「敏感」，进数据源的遮罩列表（`mask_columns`）。

**理由**：只追加加序号，在单进程 SQLite 下就能做到可复现（P8，不可回退决定：不上 Postgres、不加节点锁）；写入走动作，审批和对账都是现成的；行级可见在连接层做，模型和 SQL 都绕不过去（P4）。

**否决的做法**

- 每次提交出一个新快照（复用 table_versions）：一次提交一个文件，量一大就扛不住；
- 允许原地改行：数就不可复现了；
- 行级可见交给模型在 SQL 里加 where：靠不住。

**代价**：
- 多一种数据源和一个写入服务；写入走单进程锁，和导入的锁分开；
- 高频填报（每秒多次）不是目标场景，写在 README 里。

### 2.9 N9 文件

**决定**

- **存储**：
  - 按 sha256 内容寻址存，复用 `raw_store` 的做法：`data/files/<前 2 位>/<sha>`，文件只读（0444）；
  - 新表 `files` 记 id、sha256、原名、大小、类型、上传人、上传时间、绑定的运行或记录（可空）、用途；
  - 大小限额沿用 `max_upload_mb`；类型白名单见待拍板 Q5。
- **上传两步走**：
  1. `POST /api/files` 带上下文（应用 id 加入口，或者待办 id），先上传，拿回引用 `{file_id, name, size, sha256, type}`；
  2. 再提交表单。表单字段 `type: object`、`x-widget: file`，值就是引用。
- **提交时绑定**：服务端核对引用属于提交人、还没被别的提交用过，然后把它绑到这次运行（一次性），引用连同 sha256 进运行输入，随封存一起固定（P8）。没绑定的上传 24 小时后清理。
- **怎么用文件**：
  - **交给 agent 或报告读**：新增模板函数 `file_text(input.附件)`，运行时按类型抽文本（PDF、Word、表格、纯文本），沿用知识库上传的抽取，有长度上限，超出照实截断并标出；
  - **作为一期数据导入**：平台内置能力 `table_import.new_period(source, file)`，按这个上传源已有的配方导入，效果是写入（数据变了），走动作和确认；
  - **附在记录上**：记录表的文件列存引用。
- **下载**：`GET /api/files/{id}`，只给读得到绑定的那次运行、或那一行记录的人（复用 `can_read_run` 和记录的行级可见）。文件不做遮罩，界面在上传处写明「能看到这条记录的人都能下载附件」。
- **使用者**：个人应用里可以上传文件交给 agent 读（只读），不能导入。

**理由**：内容寻址加封存，证据站得住（P8）；上传和提交分开，表单仍是 JSON，人工节点的表单也能用；读权限跟运行走，没有新的权限面（P4）。

**否决的做法**

- 文件放进工件库：工件库只存 JSON，按运行归属，上传时还没有运行；
- base64 塞进表单值：撑爆输入和事件流。

**代价**：多一张表、一个清理任务；抽文本的质量受文件格式影响，照实标「抽取不完整」。

### 2.10 N10 白话层

**决定**

- 新增 `app/plain.py`：问题编号 → `{title 一句话, why 为什么要紧, who: you|assistant|admin, action 怎么办}`。覆盖：
  - 工作流发布门禁（`contract.*`、`governed.*`、`action.*`、`process.*`）；
  - 应用检查（`app.*`）；
  - 发布单的步骤失败。
- 没登记白话的问题照旧显示技术说法，并在检查脚本里报「有问题编号没有白话」，防止遗漏。
- 前端的发布摘要、蓝图卡片、试运行页都用白话；画布和应用编辑器保留技术说法，另加一行白话。
- `who` 的判定照这三样：自动修复的 `kind`、`APP_HUMAN_ONLY`、需要管理员的问题编号。

**理由**：P5 一种说法；P1 照实说给听得懂的人。

**否决的做法**：让模型临场解释——每次说法不同，还可能说错。

**代价**：每加一个问题编号都要写白话，检查脚本会提醒。

### 2.11 N11 生成：耗时与稳定性

**决定**

- **调用次数的预算**：
  - 起草蓝图：1 次主调用，加最多 2 次查看；
  - 填关节：每一组独立的关节（例如两组互不相干的指标）各 1 次调用，**并行**执行（新增，补 G12），各自最多 1 次查看；
  - 其余全部是确定性的。
- **模型**：蓝图和关节都用设置里的助手模型；首次使用时提示「推荐用快速模型」。验收按真实模型记录每一步的耗时（第六部分 W4）。
- **反问收尾**（补 G6）：
  - 问数据：store 加 ask 分支——这一轮记成「助手反问」，问题进历史；输入框提示「回答助手的问题」；
  - 画布：这一轮照样记下，问题进历史；
  - 蓝图对话：问题和候选画成可点的选项。
- **问数据校验不过时**：不再整轮重来，改为把问题交回同一轮的自查修正（Checker 已有），省一次完整生成。

**理由**：普通人等不了几分钟（验收里有模型在画布写 SQL 首个操作要 486 秒）；反问是蓝图的核心交互，不能丢。

**否决的做法**：一次调用生成整张图加应用——慢、不稳、难修。

**代价**：并行调用增加瞬时并发，受模型服务的限流约束，失败时退回串行。

### 2.12 和不可回退决定的对照

| 不可回退决定 | 本方案 |
|---|---|
| 正式运行只从已发布的不可变版本、按 graph_hash 发起 | 试运行和个人应用都是探索运行；发布单发布后才有正式运行；按图哈希对齐试运行和版本 |
| 口径升版必须处置 | 改取数回到蓝图，发布单要求处置，摘要用白话说明 |
| 叙述层不做算术 | 关节里的指标式只许 `cell()` 加口径卡算术；卡片上的数来自绑定 |
| 没发布的图只能跑探索 | 个人应用永远是探索；印章写明 |
| 不上 Postgres、不加节点锁 | 记录表单文件 SQLite、只追加、单进程锁；临时视图钉版本 |

---
## 第三部分 规格

### 3.1 数据模型

**新表**

| 表 | 主要字段 |
|---|---|
| `blueprints` | id、name、owner、scope（personal / shared）、status（drafting / trialed / published / personal / in_review）、spec（`agentlab.blueprint/1`）、template_id、template_version、source（conversation / template / run / workflow_version，带 id）、workflow_id、app_id、last_trial_run_id、graph（个人应用的图）、graph_hash、copied_from（审核副本指向原蓝图）、created_at、updated_at |
| `blueprint_events` | blueprint_id、seq、actor、verified、op（`bp_*`）、before、after、at——蓝图的留痕 |
| `publish_plans` | id、blueprint_id、actor、steps（每步 kind、status、result、error_code、at）、summary（白话摘要）、level、status（planned / running / stopped / done）、created_at |
| `files` | id、sha256、name、size、mime、uploaded_by、uploaded_at、context（app_id、entry 或 task_id）、bound_run_id、bound_record（表 id、`_id`）、purpose |
| `records_tables` | id、app_id、name、source_id（登记的数据源）、version（表版本）、columns（列定义 + 敏感标记）、created_at；表版本另起一行，旧版本只读保留 |

**新列**（走 `_COLUMN_MIGRATIONS`）

- `apps.scope`（默认 shared）、`apps.owner`、`apps.blueprint_id`；
- `runs.origin_kind` 新增取值 `trial`、`personal_app`（总方案 X3 的列表加两项，仍只能由服务端写）；
- `tasks.kind` 新增 `review`（个人应用提交审核）；
- 组件 spec 加 `hidden`（`apps/spec.py` 的组件模型，`extra=forbid` 下显式加字段）。

### 3.2 蓝图 `agentlab.blueprint/1`

```json
{
  "format": "agentlab.blueprint/1",
  "purpose": {"value": "每周看各门店销售额、订单数和退款率", "source": "user", "status": "confirmed"},
  "template": {"id": "periodic_board", "version": 1},
  "data": [
    {"id": "gmv", "label": {"value": "销售额"}, "unit": {"value": "元"},
     "table": {"value": {"source": "shop", "table": "orders"}, "source": "catalog", "status": "proposed"},
     "measure": {"value": "sum(amount)", "source": "assistant", "status": "proposed"},
     "date": {"value": {"column": "paid_at", "rule": "按支付日"}, "source": "catalog", "status": "confirmed"},
     "filter": {"value": "不含已退款", "source": "user", "status": "confirmed"},
     "reuse": null}
  ],
  "cadence": {"value": {"preset": "weekly", "weekday": 1, "time": "09:00", "tz": "Asia/Shanghai", "period": "last_iso_week"}},
  "people": [], "fields": [], "writeback": null,
  "access": {"use": [{"kind": "group", "name": "门店"}], "observe": [], "manage": []},
  "joints": {"sql_main": {"status": "filled", "by": "assistant"}, "metric_gmv": {"status": "pending"}}
}
```

- 每一项都是 `{value, source, status}`；`source` 取 user / assistant / template / catalog / caliber；`status` 取 confirmed / proposed / missing。
- `measure` 是白话或简单聚合的提议，**不是**最终表达式；最终的 SQL 和指标式在关节里，由 `TemplateApplier` 落地并经过检查。
- `reuse`：对到已发布口径卡时写 `{workflow_id, version, node_id, metric_id}`，实例化成 `caliber_from`。

**操作**：`bp_set(path, value)`、`bp_add(path, item)`、`bp_remove(path)`、`bp_ask(question, options[])`、`bp_template(id)`。路径用 JSON 指针。模型和用户共用这组操作；`BlueprintApplier` 按卡片的白名单校验（比如 `people[].policy.kind` 只能是 any / all / quorum）。

### 3.3 模板 `agentlab.template/1` 与首批五个

**模板定义**（后端模块）：

```text
id, version, label, description, applies_when（给助手看的适用条件）
cards: 用到哪些卡片、各自的约束
skeleton(bp) -> GraphSpec        # 带关节占位
joints: [{id, kind, node_id, field, from_card | generated, check}]
app_skeleton(bp, graph) -> agentlab.app/1   # 在 derive_app 的结果上按模板排布
schedule(bp) -> 定时任务参数 | None
tests: 每个模板至少一张完整蓝图的实例化 + 检查 + 运行
```

**首批五个**

| 模板 | 骨架 | 生成关节 | 确定性关节 | 应用页 |
|---|---|---|---|---|
| 周期看板 `periodic_board` | 入口（统计期）→ 取数（tool）→ 口径卡 → 成果（指标出具） | SQL、指标式 | 统计期字段、定时任务、出具契约的必需指标 | 印章、指标块、趋势、明细表、「按条件查看」（按需） |
| 审批流程 `approval` | 入口（表单）→ [按金额线分支] → 人工（一级或多级）→ [写回] → 已通过 / 已退回 | 无 | 表单、金额线、处理人与策略、时限与升级、写回目标 | 发起按钮、我发起的、实例进度、待办 |
| 异常处置 `exception_handling` | 定时：入口 → 取数（异常清单）→ 分支（有 / 无）→ 人工（负责人填处置说明，表格附在待办上）→ [复核] → 成果 | 异常的 SQL | 负责人、时限、复核策略 | 异常数指标、本期异常表、处置进度 |
| 填报登记 `records` | 入口（表单）→ [审批] → `records.append` → 成果；另配一张汇总看板（周期看板的骨架，查记录表） | 汇总的 SQL、指标式 | 表单与表结构、审批、行级可见 | 填报按钮、我的记录（`records_list`）、汇总看板 |
| 核对写回 `reconcile_writeback` | 定时：取数 → 口径卡（核对差异）→ 人工复核（确认要写回的）→ 写回 → 成果 | 取数的 SQL、差异的指标式 | 复核人、写回目标与字段对应、确认 | 差异指标、待复核清单、写回记录 |

- 每个模板都能被个人应用用到的部分（只读）标出来：周期看板全部、异常处置去掉人工步骤只看清单、填报登记只看汇总和「我的记录」。
- 「自由形」：从已有运行或工作流版本导入，没有关节，蓝图只有目的、谁能看、多久更新三张卡片；要改图只能回画布（搭建者）。

### 3.4 关节类型

| kind | 填什么 | 谁填 | 检查 |
|---|---|---|---|
| `sql` | 调用工具节点的 `args.sql` | 模型（look 表） | 只读守卫、SQL 猜列、数据源范围、目录检查（GraphChecker） |
| `metric_expr` | 口径卡一个指标的 `expression` | 模型 | 只许 `cell()`、口径卡算术、比较；静态追到原始数据（`engine/lineage.static_stops`） |
| `fields` | 入口或人工节点的表单 | 蓝图「填什么」 | `agentlab.form/1` 校验 |
| `assignee` / `policy` / `due` / `on_timeout` | 人工节点配置 | 蓝图「谁来做」 | 流程检查（`engine/lint_process.py`）、岗位派生 |
| `threshold` | 分支条件「字段 比较 常量」 | 蓝图 | 表达式解析器，禁止算术 |
| `capability` | 调用工具节点的 tool 和参数映射 | 蓝图「写回哪里」 | 能力登记、写入只在调用工具节点（总方案 A5）、参数按声明类型 |
| `contract` | 成果节点的出具契约（必需指标） | 蓝图「看哪些数」 | 出具契约检查（含指标出具） |

`TemplateApplier.apply(op)` 只收 `fill_joint {joint, value}`，`joint` 必须是这个模板声明的生成关节；`TemplateChecker.issues()` 跑上表的检查加骨架比对，交回模型改（最多 2 轮，沿用 `Generation` 的修正阶段）。

### 3.5 试运行解析

- `POST /api/blueprints/{id}/trial {inputs?}`：实例化 → 保存草稿图 → 发起探索运行（`origin_kind=trial`）→ 返回 run_id；结束后蓝图状态记 trialed、`last_trial_run_id`。
- `GET /api/blueprints/{id}/preview?page=…&run=…`：派生（或沿用）应用草稿，调 `resolve_page(draft=True, trial=run)`：
  - 所有视图来源解析到这次运行；趋势、按需视图只给这一个点；
  - 印章 `from = 试运行`、`trial = true`、notes 加「这不是正式结果」；
  - 流程组件（实例进度、待办）对着这次运行；待办卡按钮写「以试运行身份…」。
- 权限：蓝图的 manage（共享）或拥有者（个人）。

### 3.6 发布单

- `POST /api/blueprints/{id}/publish-plan {level}`：只读，返回 `{steps[], summary[], problems[{code, plain, who, fix?}], ok}`。
- `POST /api/publish-plans/{plan_id}/run`：按步执行；每步结束写 `steps[i]`；某步失败时状态 stopped，返回白话原因。
- `POST /api/publish-plans/{plan_id}/resume`：修好后从停下的那一步接着做；已完成的步骤按结果里的 id 核对，不重做。
- 每一步调用现有服务函数（发布、定时任务、派生、应用发布、授权），不经 HTTP；预检阶段这些函数以「只检查」方式调用。
- 审计：发布单的开始、每步、结束各写一条（`publish_plan.*`），和各对象自己的审计互相引用。

### 3.7 记录表

- **写入服务**：`records/store.py`。
  - `append(table, values, run_id, actor, action_key)`：在单进程锁内校验列、写一行、返回 `_seq` 和 `_id`；
  - 同一个 `action_key` 第二次调用返回第一次的结果（幂等）。
- **能力** `records.append`：
  - 内置登记；参数是 `{table, values}`；
  - 效果是写入，允许无人值守，查询能力是 `records.lookup(action_key)`。
- **查询连接**：
  - `data/engine.py` 打开 `origin=records` 的源时，在连接上建 TEMP VIEW：每张业务表一个同名视图；
  - 视图条件是 `_seq <= 高水位`，加 `_superseded = 0`，加行级过滤；
  - 高水位来自运行的 data_versions；行级过滤取自运行的发起人和这个应用的授权：正式运行以服务身份跑、不过滤；`records_list` 按看的人过滤。
- **表版本**：「填什么」卡片变化时，按 `INCOMPATIBLE_KINDS` 判定，兼容的就 ADD COLUMN，否则新建版本文件并登记一行 `records_tables`。

### 3.8 文件

- **接口**：
  - `POST /api/files`（multipart；context 必填）→ 引用；
  - `GET /api/files/{id}`（按绑定对象核对读权限）；
  - `DELETE /api/files/{id}`（只能删自己还没绑定的）。
- **控件**：`x-widget: file`，字段 `type: object`，属性 `{file_id, name, size, sha256, type}`；`accept`、`max_mb` 进 `x-file`。前后端校验同一份：`apps/forms.py`、`lib/schemaForm.ts`。
- **模板函数** `file_text(ref, max_chars=…)`：运行时抽文本，结果记进运行事件（字数、是否截断），抽取的文本按工件存，进证据。
- **清理**：调度循环每小时清一次 24 小时前上传、没有绑定的文件。

### 3.9 个人应用

- `POST /api/blueprints/{id}/save-personal`：校验图满足 `chat_policy`（节点、工具、无人工、无写入），建或更新 `scope=personal` 的 App，图存在蓝图上。
- `POST /api/apps/{id}/refresh`（个人）：发起探索运行（`origin_kind=personal_app`，身份是拥有者，强加 `MASK_RESULTS`、`READ_ONLY`），受每日上限约束。
- 视图来源 `exploratory`：只在 `scope=personal` 的应用里合法（应用检查拦），解析时取最近一次成功封存的 `personal_app` 运行。
- `POST /api/apps/{id}/submit-review {to}`：开 `review` 待办；搭建者处理时调 `POST /api/blueprints/{id}/copy` 得到共享副本。
- `can_read_run` 加一条：拥有者能读自己个人应用的运行（`auth/access.py:74-96`）。

### 3.10 接口一览

| 接口 | 权限 |
|---|---|
| `POST /api/blueprints`（起点：对话 / 模板 / 运行 / 版本） | builder；个人：user + 开关 |
| `GET/PATCH /api/blueprints/{id}`（PATCH 收 `bp_*` 操作数组） | 拥有者或共享蓝图的 manage |
| `POST /api/copilot/blueprint-stream` | 同上 |
| `POST /api/copilot/fill-joints-stream` | 同上 |
| `POST /api/blueprints/{id}/trial`、`GET …/preview` | 同上 |
| `POST /api/blueprints/{id}/publish-plan`、`/api/publish-plans/{id}/run|resume` | builder（受管级再要 admin） |
| `POST /api/blueprints/{id}/save-personal`、`/api/apps/{id}/refresh`、`/submit-review` | user + 开关，拥有者 |
| `POST /api/blueprints/{id}/copy` | builder |
| `GET /api/templates` | 登录即可 |
| `GET /api/apps/{id}/candidates` | manage |
| `POST/GET/DELETE /api/files…` | 见 §3.8 |
| `GET /api/apps/{id}/records`（`records_list` 用） | use（只看自己的）/ observe |

### 3.11 事件

- 运行事件：`run.origin` 的 kind 加 trial、personal_app；`file.extracted`（文件抽文本：字数、是否截断）；`records.appended` 是动作事件（`action.*`）的一种，不另起。
- 蓝图事件存 `blueprint_events`，不进运行事件。

### 3.12 权限矩阵（开登录时）

| 操作 | admin | builder | user |
|---|---|---|---|
| 建共享蓝图、试运行、发布单（已发布级） | ✓ | ✓ | ✗ |
| 发布单（受管级、降级） | ✓ | ✗ | ✗ |
| 建个人应用、刷新、提交审核 | ✓ | ✓ | 开关开着时 ✓ |
| 审核个人应用（得到共享副本） | ✓ | ✓ | ✗ |
| 看别人的个人应用内容 | ✗ | ✗ | ✗ |
| 上传文件 | 有对应入口或待办的人 | 同左 | 同左 |
| 下载文件 | 读得到绑定的运行或记录的人 | 同左 | 同左 |
| 记录表逐行查看 | 全部 | 全部（有 observe） | 只看自己的（use） |

关登录时全部放行，个人应用的开关照样生效（关着就没有入口）。

### 3.13 新增检查

- **蓝图**（`bp.*`，蓝图卡片和发布单预检里显示）：
  - `bp.missing`：缺必填卡片项；
  - `bp.unconfirmed`：待确认项未确认就发布；
  - `bp.data_unmapped`：看哪些数没对到表或口径；
  - `bp.people_unbound`：岗位没有人；
  - `bp.reconciler_unbound`：写回的能力没登记查询，结果不明时没人核实（同上，只挡发布；发布单上应用检查说同一件事的 `app.reconciler_unbound` 和核实岗位的 `app.slot_unbound` 不再重复列）；
  - `bp.template_mismatch`：卡片内容超出模板能力。
- **模板**（`tpl.*`）：
  - `tpl.skeleton_changed`：实例化的图改了骨架；
  - `tpl.joint_unfilled`：生成关节没填；
  - `tpl.joint_refused`：模型想改非关节的位置。
- **应用**：
  - `app.view_source_personal`：`exploratory` 来源出现在共享应用里，error；
  - `app.hidden_bound`：被隐藏组件是唯一绑定某个视图的组件，warning。
  - `app.records_rows_exposed`：看板的表格绑定的查询直接列出记录表的逐行（没有聚合），warning。正式运行看得到全部行，这样等于所有使用者都能看到别人的记录，绕过了行级可见；逐行查看请用 `records_list`。
- **个人应用**：`personal.policy`，图里有使用者不能用的节点或工具（沿用 `chat_graph_problem` 的说法）。
- **白话**：以上全部登记进 `app/plain.py`。

---

## 第四部分 界面

### 4.1 新建应用

- **入口**：应用首页右上「新建应用」。使用者在开关开着时也有这个入口，只能建个人应用。
- **三个起点卡片**：
  - 说说你要什么：大输入框加例句；
  - 从场景模板开始：五张模板卡，每张写适用场景、会产出什么、要准备什么；
  - 从已有的开始：最近的问数据回答，加上已发布的工作流（后者只给搭建者）。
- **问数据的「做成应用」按钮**：改为「做成应用（蓝图）」，直接带着这次运行进蓝图，不再跳画布发布框。

### 4.2 蓝图页

- **左侧**：对话。助手的反问画成可点的选项，「这一轮在等你回答」常显。
- **右侧**：卡片列，每张卡片头上标状态（已确认、待确认、缺）。卡片里每一项都可以点开改，改完标来源「你」。
- **对到数据的项**：显示对到的表、中文名、粒度、业务日期，带一句「为什么对到这张表」，来自 look 和目录。
- **底部**：「用真数试一次」（缺项时置灰，写清缺什么）；试过之后才有「发布」（搭建者）、「存成我的应用」（使用者）。

### 4.3 试运行页

- 就是应用的样子，顶部横幅写「试运行：数据是真的，但这不是正式结果」，配试运行的输入和「换一期再试」。
- 流程类：右侧列出试运行里的待办，自己点同意或驳回；写入步骤标「测试环境」或「演练」。
- 出错时用白话说哪一步、为什么，加「交给助手修」或「回到卡片改」。

### 4.4 发布摘要

- 一页：每一步一句白话。问题分三栏：你来定、助手可以修、要找管理员。
- 确认按钮写清结果，例如「发布并每周一 09:00 自动出数」。
- 执行时逐步打勾；停下时写在哪一步、为什么、修好后「接着做」。

### 4.5 页面上直接改

- 应用页右上「编辑」（manage）。
- 编辑状态下，组件悬停描边，点中出小工具条：改文字、隐藏、上移、下移、删除。
- 页底「加一张数据卡片」，弹出候选列表，按口径卡、报告、明细、趋势分组。
- 顶部「改取数」回到蓝图。
- 改动自动存草稿，顶部写「有未发布的改动」和「发布」。

### 4.6 个人应用

- 应用首页「我的应用」分组，卡片角标「个人」。
- 印章写「探索 · 未经发布审核」，顶部有「刷新」（写明今天还剩几次）和「提交审核」。
- 审核中写状态；审核发布后写「已有正式版本：去看看」。

### 4.7 新组件和控件

- **文件控件**：拖放或点选；显示文件名、大小、上传进度、类型和大小限制；上传失败照实说。
- **`records_list`**：列表、筛选、按时间排序；每行可以展开看全部字段和附件；被更正过的行显示「已更正」，可以展开看历史；使用者只看自己的，标题写「我的记录」。

### 4.8 文案与检查脚本

- **文案**：`termsApp.ts` 新增蓝图、模板、试运行、发布单、个人应用、记录、文件各组说法；后端白话层 `app/plain.py`。
- **新检查脚本**：
  - `check-blueprint`：起点、卡片、反问、试运行、发布摘要；
  - `check-personal`：使用者建、刷新、提交审核；
  - `check-records`：填报、行级可见、更正、表版本；
  - `check-files`：上传、绑定、下载权限。
- **要更新的**：`check-apps`（编辑状态、隐藏、候选）、`check-chat`（反问收尾、做成应用改道）、`check-studio`（反问记录）。
- **检查脚本的新约束**：每个问题编号都要有白话。

---

## 第五部分 实施组织（供下次审批，这一步不执行）

- **分支**：从最新 main 开集成分支 `feat/normal-user-apps`，所有包在同一分支、同一工作区。
- **第 0 步契约骨架**：编排者一次提交，包括：
  - 新表和新列、`agentlab.blueprint/1` 和 `agentlab.template/1` 的 pydantic 模型；
  - 关节类型和操作的白名单、`app/plain.py` 的框架；
  - 新路由的桩（501）、`records.append` 和 `table_import.new_period` 的能力登记；
  - 前端类型和接口桩、占位路由。

  之后冻结热点文件：`db/models*.py`、`db/base.py`、`core/events.py`、`typesApp.ts`。
- **一个 workflow，六个包**，每包一个完整代理，然后一个统一复核、一个集中修复：

| 包 | 范围 |
|---|---|
| B1 蓝图与模板（后端） | Blueprint 对象和操作、模板登记和五个模板、实例化和骨架比对、`BlueprintApplier`/`TemplateApplier` 与 Checker、两个生成入口、look 新类别 `caliber`、并行填关节 |
| B2 试运行与发布单（后端） | 试运行解析（`trial` 旁路）、派生自图、发布单的预检 / 执行 / 续做、白话层的内容、反问收尾的服务端部分 |
| B3 记录表与文件（后端） | 记录表存储与连接层的临时视图、`records.append`、表版本、`records_list` 解析、文件存储 / 接口 / 绑定 / 清理、`file_text`、`table_import.new_period` |
| B4 个人应用（后端） | scope 与拥有者、`exploratory` 视图来源与印章、刷新与上限、提交审核与副本、`can_read_run`、开关 |
| F5 创建链路（前端） | 新建应用三个起点、蓝图页、试运行页、发布摘要、问数据「做成应用」改道、反问在问数据和画布的收尾 |
| F6 页面编辑与新组件（前端） | 编辑层、隐藏、候选、文件控件、`records_list`、个人应用的界面 |

- **合并顺序**：B1 → B2 → B3 → B4 → F5 → F6，编排者做集成修正。
- **验证分层**（沿用）：代理只跑相关测试和 tsc、check-copy；完整关口由编排者在合并后跑一次。
- **真实模型验收和端到端验收**：都在关口之后跑。
- **合入 main 之前**：先问用户。

---

## 第六部分 验证与验收

- **W1 看板（搭建者，从一句话开始）**：「每周一看各门店上周销售额、订单数、退款率，不含退款单」。
  - 反问一次（按下单日还是支付日）；
  - 卡片对到正确的表和业务日期；
  - 试运行出真数，点数字追到单元格；
  - 发布摘要一页，确认后 9 步全部完成，应用打开就有数；
  - 从说完需求到看到试运行结果，记录用时和模型调用次数。
- **W2 审批（搭建者，从模板开始）**：报销审批，金额线 5000，财务组全员同意，48 小时升级给总监，通过后写到假外部系统。
  - 试运行里自己点完审批，写入走测试环境；
  - 发布后真实走一单；
  - 中途故意让岗位没绑人：发布单停在预检，白话说「谁来做」缺人。
- **W3 填报登记**：门店每日报损。
  - 两位使用者各提交几条，彼此看不到对方的记录；观察者看全部；汇总看板是全量的；
  - 更正一条：原行保留，汇总按更正后的算；
  - 改表单：加一个可选字段不出新版本；把数字字段改成文字，出 v2，旧记录还在。
  - 同一次运行查两遍，数一样（高水位）。
- **W4 真实模型**：本机助手模型、deepseek-v4.1-flash、glm-5.3，跑 W1、W2 的蓝图和关节，记录：
  - 调用次数、查看次数、首个操作时间、总用时；
  - 反问是否发生、关节检查的修正轮数。

  目标：
  - 起草蓝图 ≤ 3 次调用；
  - 填关节在快速模型上一分钟内完成；
  - 卡片和关节出错时，用户能看懂、能改。
- **W5 个人应用（使用者）**：
  - 开关打开后，使用者从问数据的一次回答建「我的退款周报」；
  - 刷新受每日上限约束；印章写「探索」；结果遮罩；
  - 提交审核后，搭建者在副本上发布，提交人收到通知；
  - 管理员看不到个人应用的内容。
- **W6 文件**：
  - 报销单附发票 PDF，agent 读出金额；
  - 门店上传本周报表 Excel，作为一期导入（需确认）；
  - 不能读那次运行的人下载 403；没绑定的上传 24 小时后被清理（用缩短的时间测）。
- **关口**：后端全量 pytest、tsc、check-copy、泄露扫描、`check-all --stacks 2`（含新增的四个检查）、check-auth；真浏览器端到端按 W1–W6 截图复核。

---

## 第七部分 风险与对策

| 风险 | 对策 |
|---|---|
| 蓝图对错数据（白话对到错的表） | 对到的项默认「待确认」，卡片上写为什么对到这张表；试运行看真数；数据目录越完整越准，卡片上提示补目录 |
| 模型慢或不稳 | 关节少、并行、确定性兜底（P3）；验收按真实模型记录耗时 |
| 模板覆盖不了需求 | 「自由形」加搭建者回画布；模板登记可扩展；收集落在模板外的需求 |
| 发布单中途失败 | 步骤顺序让失败无害；可续做；摘要照实说停在哪 |
| 记录表并发写 | 单进程锁、事务短；README 写明不面向高频写入 |
| 行级可见被绕过 | 在连接层建临时视图，模型和 SQL 都看不到底表；测试覆盖直接写 `main.<表>` 的 SQL 被只读守卫拒 |
| 看板把记录逐行列给所有人 | 正式运行看全部行是设计如此；应用检查对「逐行列出记录表」的表格给警告（`app.records_rows_exposed`），发布摘要写明使用者能看到什么 |
| 个人应用变成「影子正式应用」 | 永远探索、印章写明、不能分享；共享只能经审核发布 |
| 文件泄露 | 下载按绑定对象核对读权限；界面写明谁能下载；不做公开链接 |
| 白话说错 | 白话层只有一份，按编号映射，检查脚本防遗漏 |

---

## 第八部分 待拍板

| # | 问题 | 推荐 |
|---|---|---|
| Q1 | 记录表的存储 | 平台托管 SQLite、只追加、序号高水位钉版本、连接层临时视图做行级可见（N8） |
| Q2 | 填报提交走不走工作流 | 走：模板里 `records.append` 写入节点，可以加审批，沿用动作的幂等和对账 |
| Q3 | 使用者建个人应用的开关 | 管理员开关，默认关（同问数据） |
| Q4 | 个人应用的刷新 | 只手动刷新，加每日上限；不做定时自动刷新（自动刷新等于给使用者开定时任务） |
| Q5 | 文件的类型和大小 | 白名单：PDF、Word、Excel、CSV、图片（PNG/JPG）、纯文本；大小沿用 `max_upload_mb`（默认 50MB）；未绑定的 24 小时清理 |
| Q6 | 首批模板 | 五个：周期看板、审批流程、异常处置、填报登记、核对写回，外加自由形 |
| Q7 | 流程类试运行的审批 | 派给试运行的人自己点；写入走测试环境或演练；不触发超时升级 |
| Q8 | 发布单里「跑第一次」 | 看板类默认勾选，流程类不跑 |

---

## 附录 A 代码位置索引（main@69c5c74）

| 位置 | 内容 |
|---|---|
| `backend/app/api/copilot_gen.py:567` | Generation；`:589` 起草、`:593` 修正、`:38` 修正轮数 |
| `backend/app/look/base.py:22-27,87-110` | 查看上限；Applied / Applier / Checker 协议 |
| `backend/app/api/copilot.py:1679` | `/generate-stream`；`:1744` 只问不改的一轮；`:2364` `/app-stream`；`:2468-2550` from-run 与来源记录 |
| `backend/app/apps/ops.py:264` | `polish_problem`（护栏的写法） |
| `backend/app/engine/autofix.py:1240` | `forbidden_changes`（骨架比对的写法） |
| `backend/app/apps/derive.py:85-90` | 派生时视图绑定时任务 |
| `backend/app/apps/resolve.py:82-108,454-476,541-546,203-221,813` | 最近封存的规则；草稿解析；按运行解析；印章来源；趋势无钉住项报错 |
| `backend/app/apps/spec.py:35-42,47,82,97-107` | 表单控件、视图来源、组件模型 |
| `backend/app/engine/launch.py:95-176` | 运行类别的判定 |
| `backend/app/auth/chat_policy.py:25-73` | 使用者能用的节点和工具 |
| `backend/app/api/runs.py:108-123` | 使用者运行的限制 |
| `backend/app/auth/access.py:74-96` | `can_read_run` |
| `backend/app/data/catalog.py:12-21` | 数据目录项的形状 |
| `backend/app/data/raw_store.py:33-43` | 按哈希存原件 |
| `backend/app/data/table_versions.py:1-33,344-360` | 表的版本模型和存放 |
| `backend/app/data/recipe_accumulate.py:38-41` | 不兼容的列变化 |
| `backend/app/engine/runner.py:242-262,1013-1045` | data_versions 的固定；封存 |
| `backend/app/api/workflows.py:427-503` | 发布 |
| `backend/app/api/schedules.py:461`，`scheduler/service.py:39-56` | 建定时任务；模板变量 |
| `backend/app/api/apps.py:186,203,251,370,474,273` | 建应用、派生、草稿、发布、授权、归档 |
| `frontend/src/store/chat.ts:1241,1433` | 问数据整轮重来；没有反问分支 |
| `frontend/src/apps/ViewRenderer.tsx:75-84` | 组件包在 `data-node` 里 |
| `frontend/src/pages/ChatPage.tsx:479-523` | 问数据的「做成应用」 |

## 附录 B 术语

- **蓝图**：用户的需求被整理成的一组白话卡片，是生成工作流和应用的依据。
- **卡片**：蓝图里用户能判断对错的一件事（看哪些数、谁来做……）。
- **场景模板**：一类应用的骨架，带可填的关节。
- **关节**：模板骨架里允许填的位置；确定性关节按卡片填，生成关节由助手填。
- **试运行**：跑一次还没发布的图，用真数看应用的样子；不是正式结果。
- **发布单**：一次确认发布的编排，逐步执行、可续做。
- **个人应用**：使用者自己建、只有自己看得见的应用，永远是探索。
- **记录表**：平台托管、只许追加的表，填报登记的每次提交是一行。
- **高水位**：一次运行开始时记录表的最大序号，这次运行只看到这之前的行。
- **白话层**：问题编号到白话说法的唯一映射。