# JCAI-WOS —— 企业级 AI Native 任务操作系统

> 一句话:组织的工作定义为可编排的工作流,工作流由**活动**编排而成;活动是完成一项任务的
> Agent 机制,系统外开发、安装即用。人只在责任点与放行点出现 —— 确定交系统,临场交 AI,落地交人。

## 现状快照(2026-07-30)

- **三面一体**:设计中心 `/design`(九区:蓝图/触发器/流程包/活动库/工具箱/数据域/知识库/
  大模型/测试台)· 运营中心 `/ops`(六区:驾驶舱/工作流/任务/员工/台账/系统)· 工作台 `/`。
  `/gov` 302 → `/ops`。
- **编排层与流程引擎已跑通并测死**:起单宽进(门口不拒缺项)、数据按字段名流动(无强制
  类型)、边只表达顺序与条件(对齐 Mastra)、闭合校验只查结构闭合 + 活动装载、一条流恰一个
  生效版本、在途按启动版本跑完、版本号与名归设计人员自己定。
- **活动一律案例模型**(2026-07-29 范式退役):flow-engine 已删,业务模型只有
  CMMN + 说明书 + DMN 一形;`turn-runner` 每拍要 `agent.decide` —— **环境无模型密钥时
  案例活动一步走不动**,三套端到端(unified-quote-flow / new-package-flow / testbed-trace)
  整套跳过,恢复条件写在各文件头。
- **模型实例**:只留 `deepseek-v4-flash` / `deepseek-v4-pro` 两条;种子读不到
  `JCAI_DEEPSEEK_API_KEY` 就**不绑密钥**(卡上如实显示不可用),去治理台大模型区补。
- **下一件大事:实现活动与工具调用逻辑** —— 规范已写死在 `docs/活动开发规范.md`,
  按其**第 12 章待实现清单**顺序销账(第一优先级:写类动作意向落地断链、工具未命中转人)。
- 后端 19 模块 + 6 活动包 + 前端 features;五道门禁全绿(2026-07-30)。

## 文档权威地图

| 层 | 文件 | 说明 |
|---|---|---|
| **活文档**(冲突时以代码现状为准) | `docs/编码规范.md` | 工程结构权威:模块层级 L1-L8、依赖门禁、AI 协作协议 §12 |
| | `docs/产品设计.md` | 三面一体的产品形态与决策记录 |
| | `docs/活动开发规范.md` | **开发活动照这份**:基座六件、清单六区、工具声明式调用、验收放行、工作台视图逻辑;第 12 章 = 待实现清单 |
| | `docs/debt.md` | 欠账台账(只增,销账划线) |
| | `docs/adr/` · 各模块 `CONTRACT.md` | 架构决策与模块级不变量 |
| 语义源(历史语境) | `docs/操作系统.html` `docs/活动模型.html` `docs/MVP示例工作流.html` | 两卷规范 + 业务样例;flow 相关章节为历史记述 |
| 前端语义权威 | `~/coding/JCAI_PRD/workbench` `~/coding/JCAI_PRD/governance` | 原型 1:1 平移(只平移不 import);工作台视图逻辑以 `workbench/.../\_data/model.ts` 统一建模为准 |
| 归档 | `docs/archive/` | 已完成使命的文档(旧 README 规格包、PROGRESS、旧计划),只读 |

## 铁规矩(违者返工)

1. **五道门禁以退出码验**,不许以 echo 验:`pnpm -s typecheck && pnpm -s lint &&
   pnpm -s depcruise && pnpm -s api:check && pnpm -s test`(或 `pnpm gates`)。
2. **契约变更四步**(§12.4):depcruise 反查下游 → 同步 CONTRACT.md →
   `pnpm api:check --update && git add api-report` → 破坏性走三步弃用。
3. **§12.5 禁止清单**:no `any` / `as unknown as` / `@ts-ignore`;domain 零 IO;
   不删测试;不动门禁配置;不绕写三分/两缝。
4. **mock 只许出现在外界**(邮件通道、外部系统的录制回放替身);系统内部机制不得 mock。
5. **密钥只从环境读**:`JCAI_DEEPSEEK_API_KEY`(模型)、`JCAI_SEED_PASSWORD`(种子口令)、
   `JCAI_SECRET_KEY`(凭证密封);不入源码、不入包、不入留痕;E2E 永不回退开发库。
6. **试跑一律用 AI 账号**(密码 `jcai-dev-2026`),绝不派到用户工作台;测完
   `pnpm --filter @app/api reset-runs` 清运行数据(清跑出来的,留配置好的)。
7. **安装恒新增**:活动/工具改了内容必须升版本号,同版重装是 no-op(静默丢失,踩过)。
8. **界面不撒谎**:状态如实(未绑就写未绑)、错误带厂商原话、不可用不摆假数字。

## 常用命令

```bash
pnpm gates            # 五道门禁(gen:tiers → typecheck → lint → depcruise → api:check → test)
pnpm db:up            # docker compose 起 PG16
pnpm db:migrate       # 应用迁移(新迁移写 db/migrations/ 并登记 meta/_journal.json)
pnpm db:seed          # 播种(五员工 + AI 账号;登录者 = 冯兵)
pnpm dev:api          # :8787        pnpm dev:web   # :5173(/api 反代)
pnpm --filter @app/api reset-runs   # 清运行数据,留配置
```

## 结构速查

```
apps/api/src/modules/<m>/{index,contract,port,CONTRACT.md,internal/{domain,usecase,adapter}}
apps/api/src/app/          # 唯一组装层:container / wiring/engines / routes / workers / seed
apps/web/src/features/     # desk-*(工作台)· gov-*(设计+运营)· auth
packages/{contracts,activity-sdk,sfeel,ui-kit,testing}
activities/<id>/src/{index,manifest,case-model,skills,views/}   # 活动包(只准 import @sdk/@contracts)
```