forked from ChaiHao/BPOS-MVP
ChaiHaoandClaude Opus 5
1fd215cf40
用户定的两件,一并落地。
**一、活动不再分 flow 和 loop —— 彻底退役 flow**
· `flow-engine` 模块整个删除(runner 379 行 + step-sequence 184 行 + 测试);
· `paradigm` 从清单身份、`activity_package`/`task` 两张表、任务卡与活动库一并退场;
`businessModel` 不再是判别联合 —— 只有案例模型(CMMN + 说明书 + DMN)一形;
· task 的引擎分派从「按 paradigm 取两个之一」收成**唯一的引擎**;
· `activities/` 四个 flow 活动(A1 受理 / A4 定价 / A6 议价 / A7 归档)各写了一份
案例模型:阶段照原来的步分,触达世界的项一律 manualActivationRule,
能算的交 DMN(A1 的三分类 P-03、A4 的 P-01/P-02)不交 Agent;
· 六个占位槽位的骨架从「机器步落台账 + 一张验收单」改成案例骨架,包版本 0.8.0 → 0.9.0。
**代价写在明处,不假装没有**:`turn-runner` 每一拍都要 `agent.decide` ——
环境里没有模型 key,案例活动一步也走不动。三套端到端(统一报价 / 新建流程包 / 测试台
Trace)整套跳过,文件头写明恢复条件:①有可用模型 ②走法改写成按 Enabled 集推进。
**不许把断言改松让它变绿** —— 绿得不诚实比红着更坏。debt.md 已记。
**二、审批活动可管**(新能力)
· `sys.approval_template`:审批点**可复用的那一半** —— 审批人看哪几项、按什么名字看、
怎么催、说什么话。谁来审不在里面(与活动点同口径,运营时轮值);驳回回哪个节点
也不在里面(那是每张图自己的事,留在节点上);
· 三条路由 + 引用反查:还被审批点引着就不许删(409),删了那些节点会**静默**退回旧行为;
· 运行时 `basisOf`:引了模板就按模板筛与改名,没引即旧行为(载荷全摊开)。
模板改了只影响新发出的审批单 —— 在途单的依据在发出那一刻已定形。
**三、活动库重做**:一区两格 —— 「活动(装进来的)」与「审批活动(配出来的)」,
都用流程卡那套两段式卡片(头 + 四格数据板),幽灵卡当入口(装入活动 / 新建审批活动);
「标准/案例」那一维随范式一起撤,业务分类成了唯一的一维,以行内小签呈现。
迁移 0020:两张表 drop paradigm、建 approval_template。已在开发库跑过并重播种。
实测(丁子乔账号):建「定价审批」模板 → 流程包 A5 属性里选得到 → 引用反查计数正确。
四闸绿(api:check 随本提交)。
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KeDBx2PHLavbURXB8LJJ7m
183 lines
15 KiB
Markdown
183 lines
15 KiB
Markdown
# JCAI 任务操作系统 · MVP 规格包
|
||
|
||
这个目录是「企业级 AI Native 任务操作系统」的**完整规格包**：两卷语义规范 + 一份工程结构契约 +
|
||
一份业务验收样例。交给编码 Agent，即可从零实现 MVP。
|
||
|
||
> 一句话系统：组织的工作被定义为可编排的工作流，工作流由活动编排而成；一个活动是一个完成一项
|
||
> 任务的 Agent 机制，像小程序一样在系统外开发、安装即用；人只在责任点与放行点上出现——
|
||
> 确定交系统，临场交 AI，落地交人。
|
||
|
||
---
|
||
|
||
## 启动提示词（编码仓库的 Agent 从这里启动）
|
||
|
||
```text
|
||
你是本仓库的开发 Agent，任务：从零实现「JCAI 任务操作系统」的 MVP。
|
||
|
||
【第 0 步 · 建立权威——写任何代码之前必须完成】
|
||
1. 读 docs/编码规范.md 的前言与 §0–§5 —— 先知道代码长什么样、放在哪、谁能依赖谁；
|
||
2. 通读 docs/操作系统.html（V2.15，系统侧）—— 五层总图 / 工作台五要素与治理台九功能 /
|
||
流程层（流程包·工作流·触发器·审批点·网关·边映射）/ 引擎（流程引擎 + 活动基座六件）/
|
||
人类工具 / 统一事件标准 / 调用层与工具箱 / 记忆与度量 / 运行拓扑与写三分 / 基座与治理 /
|
||
系统不变量——最后的不变量清单要能默写要点；
|
||
3. 通读 docs/活动模型.html（V2.0，活动侧）—— 契约七件 / loop（CMMN+DMN·语义引擎×Agent 回路·
|
||
双向驱动）/ flow（步序声明·四种步型）/ 人类工具的调用 / 交互内容 / 技能 / 记忆与迭代 /
|
||
Harness 与验收分级 L1–L5 / 活动包与开发 / 合规判据（通用 17 + loop 8 + flow 6）；
|
||
4. 回头读完 docs/编码规范.md 全文（§6–§17）；
|
||
5. 读 docs/MVP示例工作流.html —— MVP 要跑通的那单生意（统一报价），
|
||
按本 README 的《归一化对照表》把业务素材映射成系统概念。
|
||
|
||
【权威分工——冲突时的裁决顺序】
|
||
- 语义（系统做什么、什么语义）：以两卷规范为准；
|
||
- 结构（代码长什么样、模块边界、依赖方向）：以 编码规范.md 为准；
|
||
- 业务内容（MVP 做哪单生意、字段与规则）：以 MVP示例工作流.html 为准；
|
||
- 前端 UI：**不是参照，是 1:1 平移**。两台高保真原型的前端代码就是 UI 的实现规格，
|
||
原型仓库在本机（用户已授予读取权限）：`~/coding/JCAI_PRD/workbench`（员工面工作台）与
|
||
`~/coding/JCAI_PRD/governance`（管理面治理台）。按本 README《前端 UI · 原型 1:1 平移》
|
||
一节的清单与规则执行——CSS 与 DOM 结构原样搬、组件按编码规范 §9 重排、mock 数据层换成
|
||
真实 API；**只平移不 import**，编码仓与原型仓零依赖；
|
||
- 发现两类权威打架：停下来报告，不得自行仲裁（编码规范·前言）。
|
||
- 谨记双层边界：范式（loop / flow / skill）是后端实现逻辑的模型，只存在于引擎层；
|
||
交互模型（工单两模式 + 对话卡族）是前端呈现协议——两层不冲突，前端永远感知不到范式
|
||
（编码规范 §9 注记）。UI 文案用两卷术语（标准活动 / 案例活动 / 审批点），
|
||
SOP / CMMN / BPMN 等字样只出现在代码与内部文档，不出现在界面上。
|
||
|
||
【实施纪律】
|
||
- 严格按 编码规范.md §15 的里程碑序 M0→M6 推进；每个里程碑先立骨架
|
||
（index / contract / port / CONTRACT.md + 空测试）再填实现；
|
||
- 机器门禁（tsc / eslint / depcruise / 契约快照 / test）从 M0 起全绿，红了先修门禁再前进；
|
||
- 遵守 §12 AI 协作协议（多 Agent 并行 · 主 Agent 编排制）：**你即主 Agent（唯一集成人）**，
|
||
按 §12.0 授权矩阵组织子 Agent 并行承包——分支即工单、合入唯经你（§12.7）、契约面由你单写；
|
||
§12.5 禁止清单按矩阵授权，三类保留项（破坏性契约 / 新依赖 / 改门禁规则）永远上升用户；
|
||
- 本 docs/ 即规格包原件，整包置于仓库 docs/ 下；另建 docs/debt.md 与 docs/adr/
|
||
（ADR 编号从 005 续，001–004 已在编码规范 §14）；
|
||
- 四个落地裁量点已由用户裁定（见本 README《已裁定的落地决策》），照此实现、不必再问；
|
||
实现中出现**新的**裁量点仍照前言规矩停下报告。
|
||
|
||
【MVP 完成判据——统一报价全链路验收场景】
|
||
以下场景在真实运行的系统上从头到尾走通（mock 只允许出现在外界：邮件通道与外部系统可用
|
||
模拟通道 / 录制回放替身，系统内部机制不得 mock）：
|
||
1. 治理台：录入五名员工与岗位、绑定 LLM 实例（任一 OpenAI 兼容端点）、
|
||
编排「统一报价」流程包 v1 并发布（边映射闭合校验通过）、
|
||
配置「客户RFQ询价」事件触发器与邮件通道实例；
|
||
2. 一封样例 RFQ 邮件入站 → 归属解析 → 触发器命中起单：生成一条工作流，
|
||
A1 任务落到 BD 冯兵的工作台任务清单；
|
||
3. A1 受理归一（flow）：步序推进，LLM 步抽取归一 → 台账「统一受理记录」（任务级草稿层），
|
||
缺关键字段走补全卡，逐条打标走 DMN（三分类规则 P-03），放行通过 → 草稿合并正式版、
|
||
数据事件发射，G2 网关按 Type 分流；
|
||
4. B 类条目 → A3 渠道寻源（loop，林佩萱）：CMMN 装载、Agent 回路推进、发询后登记
|
||
数据监听 + 时限；供应商回价（模拟入站）→ 数据事件续跑；寻源比价表交付放行；
|
||
5. C 类条目 → A2 替代选型（loop，王梓名）：含一次跨人卡（向 BD 补全），
|
||
替代对标表放行交回；
|
||
6. A4 成本定价（flow）：取价基准 → DMN 定价（利润模型 P-01）→ 底价自检（底价门禁 P-02）
|
||
→ 报价草案；
|
||
7. AP 定价审批（审批点）：审批单卡到 PM 丁子乔工位——通过放行进 A6；
|
||
驳回按声明走向回 A4 重开新实例；
|
||
8. A6 报价议价（flow）：生成正式报价单（写类动作登记为动作意向）→ 落地预检 →
|
||
放行通过即落地（台账回写 + 出站发送）→ 输出口发射；建 D+3 跟进监听；
|
||
9. 客户拒绝（模拟）→ A7 情报归档：历史价格情报回写、落地率统计落账，工作流「已完成」；
|
||
10. 全程可审计：任务记忆只追加、信封盖戳、归侧标注；工作台五要素齐活
|
||
（任务 / 审批 / 消息 / 纪要 / 汇报聚合自任务日志）；治理台·任务管理可在途监控、
|
||
叫停并恢复一单任务；终态封卷触发蒸馏钩子产出活动记忆候选条目（可为最小实现）。
|
||
|
||
【种子数据】
|
||
- 员工五人：丁子乔（PM·项目经理）· 冯兵（BD·商务）· 王梓名（FAE·现场应用）·
|
||
林佩萱（采购/寻源）· 李元初（OP·运营）；登录者 = 冯兵；
|
||
- 单次部署 ≤50 人、单组织、不做多租户——一切机制复杂度以此为预算。
|
||
|
||
现在从【第 0 步】开始。读完四份文档后，先提交 M0 的变更申请，不要直接写代码。
|
||
```
|
||
|
||
---
|
||
|
||
## 文件清单与权威分工
|
||
|
||
| 文件 | 版本 | 权威范围 |
|
||
| --- | --- | --- |
|
||
| `操作系统.html` | V2.15 · 2026-07-24 | **系统侧语义权威**：五层、交互两面、流程层、引擎与活动基座六件、人类工具、统一事件标准、调用层、记忆与度量、运行拓扑、边界四象限、基座与治理、系统不变量 |
|
||
| `活动模型.html` | V2.0 · 2026-07-25 | **活动侧语义权威**：契约七件、loop（CMMN+DMN）、flow（步序声明）、人类工具的调用、交互内容、技能、记忆与迭代、Harness 与 L1–L5、活动包与开发、合规判据 17+8+6 |
|
||
| `编码规范.md` | V0.1 · 2026-07-26 | **工程结构权威**：技术选型定案、monorepo 唯一形态、模块层级 L1–L8 与依赖门禁、Mastra 映射、持久层、前端 features、AI 协作协议、里程碑 M0–M6。服从两卷，只管「代码长什么样」 |
|
||
| `MVP示例工作流.html` | 2026-07-26 导出 | **业务验收样例**：统一报价流程全套素材——7 节点（SOP×5 + Case×2）、3 网关、13 张流转单据、16 张静态库表、5 条规则判定表 + 经验。是原始业务素材，需按下表归一化 |
|
||
|
||
两卷互为关联卷（系统供给 vs 活动定义是镜像同表）；编码规范前言载有仲裁规则：
|
||
**语义冲突以两卷为准，结构冲突以编码规范为准，两类权威打架停下来报告**。
|
||
|
||
## 归一化对照表（MVP 素材 → 系统概念）
|
||
|
||
样例是业务分析会话的原始导出，术语与两卷未对齐；实现时按此表映射：
|
||
|
||
> **2026-07-29 范式退役**:用户定「活动不再分 flow 和 loop,内部实现都是 Loop」——
|
||
> `flow-engine` 模块整个删除,`paradigm` 字段从清单与两张表退场,活动的业务模型只剩案例模型。
|
||
> 下表提到「标准活动(flow)」的行为**历史记述**;今天 A1/A4/A6/A7 也已改写成案例模型。
|
||
> 后果见 docs/debt.md。
|
||
|
||
| 样例里的物件 | 归一化为 |
|
||
| --- | --- |
|
||
| 流程「统一报价」 | **流程包** v1：治理台编排五要素、边映射闭合、发布；运行即工作流 |
|
||
| 触发器「客户RFQ询价」 | **事件触发器**：通道入站命中规则 → 字段映射 → 经调用接口起单 |
|
||
| SOP 节点（A1/A4/A6/A7） | **标准活动（flow）**：任务定义卡→契约七件；作业指导书 S1…Sn→步序声明（四种步型）；步内判断（如 A1 的 D1 完整度）→条件谓词或人类工具步；SLA→Harness 时限与预算 |
|
||
| Case 节点（A2/A3） | **案例活动（loop）**：案例图→CMMN XML；案例说明书→同版本叙事面；`!必做`→entryCriterion 常项、`看情况`→discretionary、`#可反复`→repetitionRule、`▶需拍板`→manualActivation + 放行；`⏱时限/回价到期/✋客户改需求`→时间/数据/人监听（时限必配） |
|
||
| A5 定价审批 | **审批点**（流程层内置人裁节点，功能属性四件）；G3「审批结果」网关并入审批点的驳回走向（回 A4 重开新实例）。见裁量点 ① |
|
||
| 规则五件（P-01 利润模型 / P-02 底价门禁 / P-03 三分类 / P-04 有效期 / 受理规范） | 判定表部分→ **DMN 决策表**（确定性求值、命中行留痕）；「经验」段落→**技能 / 活动记忆种子**（载方法不载权力） |
|
||
| 动态数据（流转单据 13 张） | **台账对象**（活动自持域，schema 声明自生长）+ **输出口载荷 schema**（流转的事实经边映射拼接） |
|
||
| 静态底座（16 张库表） | **共享域对象 / 主数据**（客户资料库、PN物料主库、供应商渠道目录等）；写授权按域.对象在契约申报 |
|
||
| 「转订单履约（ORM）」 | 流程包**显式终点**的输出声明；MVP 以回执与日志代真实 ORM 对接 |
|
||
| 角色 BD / PM / PRM / FAE | **岗位**；PRM=采购 → 林佩萱，FAE → 王梓名，负责人四策略解析起单 |
|
||
|
||
## 已裁定的落地决策（2026-07-26 用户拍板，照此实现）
|
||
|
||
1. **A5 定价审批 = 审批点**（流程层内置人裁节点，功能属性四件）：样例里的「策略决策」落审批
|
||
意见与批注；G3「审批结果」网关并入审批点的驳回走向（驳回 → 回 A4 重开新实例）。
|
||
2. **G2 料号分流 = 并行网关**：三道并行、每边载荷按 Type 过滤条目子集；某类条目为空的分支
|
||
按「容忍」处置，A4 汇合处的必填映射不得依赖可空分支。
|
||
3. **A4 成本定价 = flow**（从样例）：取价→查表定价→自检的判断全部装进 DMN 决策表确定性
|
||
求值；实现中一旦出现「由 AI 决定怎么办」，按活动模型 2.1 的上升规则改 loop 或上升为
|
||
流程层编排。
|
||
4. **议价回环「有异议 → 返回调整 → A4」= 流程层回边**：人裁决后重开新任务实例
|
||
（同节点、新任务 ID、留痕关联），不复活旧任务。
|
||
|
||
## 前端 UI · 原型 1:1 平移（强制）
|
||
|
||
`apps/web` 的界面**不重新设计**：两台原型的前端代码就是实现规格，逐屏平移，
|
||
验收标准 = 与原型逐屏对照、视觉不可辨差异。平移清单：
|
||
|
||
**员工面（workbench，浅色三栏工作面）** —— 源根 `~/coding/JCAI_PRD/workbench/src/app/(proto)/`
|
||
|
||
| 源文件 | 是什么 |
|
||
| --- | --- |
|
||
| `page.tsx` | 外壳（左轨五要素 + 冯兵徽标）+ 任务四区骨架（任务列表 / 标题区 / 工作区 / 对话区、收展把手） |
|
||
| `_components/ViewRegion.tsx` | 标题区 + 工作区四页签：待处理（HTML 工单翻页，验收=可修订报告 / 执行=指导书+空表单）、工作成果、任务详情（KPI 带 + 流程链 + 模型扇形图 + 上下文档案）、工作日志 |
|
||
| `_components/TaskChat.tsx` | 对话区（任务助理）：气泡二元制、对话卡族（决策/补全/评价/验收单）、composer 锁、跨栏定位 |
|
||
| `_components/ModuleWorkspace.tsx` | 审批 / 消息 / 纪要 / 汇报四要素（各配助理对话壳） |
|
||
| `_components/`（其余） | FileViewer / Ico / ChatAvatar / ScrollArea / Markdown / SettingsButton |
|
||
| `app.css` + `proto.vendor.css` | **整文件搬**：设计令牌（`.proto-root .app-shell`）+ 全部 `jc-*` 组件样式 + vendor 皮肤（布局骨架，类名被它占用，`jc-` 前缀因此必须保留） |
|
||
| `_data/model.ts` | 交互模型类型——`@contracts/card.ts` 的参照原型（正式版以 @contracts 为准） |
|
||
| `public/samples/` | 样例 PDF 报价单等资产（演示用，可选） |
|
||
|
||
**管理面（governance，深轨浅面控制台）** —— 源根 `~/coding/JCAI_PRD/governance/src/app/`
|
||
|
||
| 源文件 | 是什么 |
|
||
| --- | --- |
|
||
| `_components/Governance.tsx` | 九区全体：区头 + 区内页签 + 整页下钻 + 就地确认带（AskBand·影响预览三必答）+ 事件流 + 数据区记录管理器 |
|
||
| `_flow/`（六文件） | 编排画布：diagram-js 布局引擎（蛇形折行）+ 画笔（三色 skin + 琥珀审批点）+ 编辑器核 |
|
||
| `theme.css` + `console.css` | 设计令牌 + 治理台组件层（`g-*` + 色调字典 `t-*`），整文件搬 |
|
||
| `_components/Ico.tsx` · `_data/gov-data.ts` | 图标；mock 数据（字段口径与文案的参照，替换为真实 API） |
|
||
|
||
**平移规则**：
|
||
|
||
1. **DOM 结构与类名原样保留**（`jc-*` / `g-*` 前缀、vendor 皮肤一并搬）；CSS 整文件搬，不重写不「优化」；
|
||
2. **代码组织按编码规范 §9 重排**（拆进 features、路由改 TanStack Router、数据改 typed-fetch + SSE）——重排只动模块边界与数据来源，**渲染输出保持 1:1**；
|
||
3. 原型是 Next.js、正式系统是 Vite SPA：去掉 `"use client"` 等 Next 专有件即可，组件均为纯 React 19；
|
||
4. 原型内嵌的 mock 数据与内存状态（`_data/*`、doneMap 等）全部换成服务端投影；「刷新即重置」的原型缺陷不得带入——正式系统零过程状态、刷新从投影重建（§9.2）；
|
||
5. 平移中发现原型与两卷/编码规范冲突（如原型 `/api/chat` 直连 DeepSeek），以规范为准并报告，不照搬。
|
||
|
||
## MVP 之外（明确不做）
|
||
|
||
多租户 / 移动端 / 真实 ERP·CRM 对接（用调用契约 + 录制回放替身）/ 活动市场与多组织分发 /
|
||
两卷中标注「可选」的高级项（如叙述性小结可后置）。治理台九功能在 MVP 里以支撑验收场景为度：
|
||
每区可用、不追求满配。
|
||
|
||
---
|
||
|
||
*规格包整理于 2026-07-26。四份文件的任何改动都应回到源头（PRD 工作区）同步，勿在编码仓单方改规格。*
|