清理: 1. 删除 data/web-derived-schemas.json (v0.10 静态快照, v0.11+ webapi 自动同步无需保留) 2. README.md: 移除 extract-all.mjs / extractors 引用, 加 v0.11+ webapi 段, 修正 .claude/skills/dacli-ts 路径 → ../.claude/skills/dacli-ts 3. prompt.md: 移除 extract-all.mjs 引用 (3 处), 改写 v0.8 '提取 JSON' 段为 v0.11+ 'webapi 自动同步' 未清理项 (按 plan §13 保留): - src/data/*.json (component-map/field-schemas/validation-rules/form_type_rules 等 9 个 JSON) — 仍被 FieldBuilder.ts 加载, 有 3 个 unit 测试覆盖 - src/commands/_precheck.ts / _blindspot_guards.ts / form/_simplify.ts / form/_blindspots.ts / form/validate.ts / form/fixcolumndata.ts — 上一个 commit 已移除 LEGACY 误标头, 这些文件仍实际使用 - doc/v0.x-changelog.md 等 11 个版本历史 — 合法历史归档, 保留 Phase 4 完成度: A (盲点表整合) + B (deprecated 误标清理) + C (已删资源引用清理) + E (dacli 自有 schema 保留) + G (architecture.md 已 v0.11+ 更新) - 全部 PASS 未做: D (22 条盲点表整合到 _blindspot_guards.ts 单一权威) - 后续 P1 任务
155 lines
6.3 KiB
Markdown
155 lines
6.3 KiB
Markdown
# dacli — TS 版 dacli (当前主用)
|
||
|
||
> **位置**: `$ccWorkDir/dacli/`(原 `test/dacli/`, 2026-06-12 升级到顶层独立项目)
|
||
> **目标**: TypeScript 重写 dacli,**直接复用 JNPF web 源码** + **0 差错验证**
|
||
> **状态**: v0.7 (8 父命令 / 26+ 子命令,启动 < 500ms)
|
||
> **总目标**: workSystem 85 + developSystem 29 = **114 张官方示例 API 0 错 + 浏览器 0 视觉差**
|
||
|
||
## 这是什么
|
||
|
||
`dacli` 是 JNPF 平台的 CLI 工具,让 AI/开发者用命令行**代替**浏览器拖拽,自动化配置 JNPF 平台。
|
||
|
||
**Java 版** (`docs/dacli/ssw-dacli/`) 已**废弃**,源码归档备查(无 `target/`,需手动 `mvn package` 跑 jar)。
|
||
|
||
**TS 版** (本项目) 是当前**主用** CLI:
|
||
|
||
1. **直接复用 web 源码** — 30 分钟跑 extract 脚本拿 53 控件 schema, 不手抄
|
||
2. **Playwright Node.js 集成** — `@playwright/test` 与 dacli 同进程, 0 视觉差验证
|
||
3. **AI 友好帮助体系** — `--ai-help` 输出 markdown, `SKILL.md` 教 AI 何时用
|
||
|
||
## 两件套交付
|
||
|
||
| 交付物 | 位置 | 用途 |
|
||
|--------|------|------|
|
||
| **`dacli` CLI 工具** | `src/` | 给 AI/开发者用, 执行命令 |
|
||
| **`.claude/skills/dacli-ts/SKILL.md`** | `.claude/skills/dacli-ts/` | 教 AI 何时用哪个命令 |
|
||
|
||
**两者缺一不可**: 没 skill 工具躺地上, 没工具 skill 纸上谈兵。
|
||
|
||
## 0 差错定义
|
||
|
||
**0 差错 = API 0 错 + 浏览器 0 视觉差**。
|
||
|
||
| 层面 | 含义 | 工具 |
|
||
|------|------|------|
|
||
| **API 0 错** | 所有 dacli 命令返回 200/业务成功 | vitest + 集成测试 |
|
||
| **UI 0 视觉差** | 复刻的表单/菜单浏览器渲染与原版**像素级一致** | Playwright Node.js |
|
||
|
||
**0 差错基线**: **74 张官方示例** (developSystem 21 + workSystem 53)。
|
||
dacli 对这 74 张必须做到:
|
||
- ✅ `dacli form export <id>` → `dacli form import` → 重建后**结构 0 差**
|
||
- ✅ Playwright 打开原版与复刻版,**截图视觉 0 差**
|
||
- ✅ 所有字段、按钮、列表列正确渲染
|
||
- ✅ 表单可正常提交、菜单可正常跳转、工作流可正常发起
|
||
|
||
## 快速开始
|
||
|
||
```bash
|
||
cd $ccWorkDir/dacli
|
||
npm install # 装依赖
|
||
npx playwright install chromium # 装浏览器 (baseline 验证用)
|
||
# v0.11+ 无需 extract 脚本: webapi/ 直接 dynamic import web 端源码
|
||
npx tsx src/cli.ts app login --appCode=tds # 登录 tds
|
||
npx tsx src/cli.ts form list # 列已有表单
|
||
```
|
||
|
||
## 跑 baseline 一键回归
|
||
|
||
```bash
|
||
# 74 张一键回归 (API + UI)
|
||
bash .claude/skills/dacli-ts/examples/baseline/all.sh
|
||
|
||
# 仅 API 层 (快, 跳过 Playwright)
|
||
SKIP_PLAYWRIGHT=1 bash .claude/skills/dacli-ts/examples/baseline/all.sh
|
||
```
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
dacli/ # 顶层独立项目 ($ccWorkDir/dacli)
|
||
├── prompt.md # 任务说明书 (开发这个项目的 AI 看的)
|
||
├── README.md # 本文件 (项目入口)
|
||
├── package.json
|
||
├── tsconfig.json
|
||
├── playwright.config.ts # Playwright 配置
|
||
│
|
||
├── src/ # ⭐ dacli CLI 工具
|
||
│ ├── cli.ts
|
||
│ ├── commands/ # 24 父命令 / 116 子命令
|
||
│ ├── core/ # 基础设施 (client/kit/help/log)
|
||
│ ├── webapi/ # ⭐ v0.11+ webapi 镜像 (18 模块, 100+ 函数)
|
||
│ ├── data/ # FieldBuilder JSON (component-map / field-schemas / ...)
|
||
│ └── schema/ # FieldBuilder
|
||
│
|
||
├── ../.claude/skills/dacli-ts/ # ⭐ AI 专用 skill (父项目, v0.11+ 已合并)
|
||
│ ├── SKILL.md # 主入口
|
||
│ ├── references/ # 8 专题文档
|
||
│ └── examples/ # 14 可复用脚本
|
||
│
|
||
├── doc/ # 人类详细文档
|
||
│ ├── architecture.md
|
||
│ ├── plan.md # 6 周路线
|
||
│ ├── baseline.md # 0 差错验证
|
||
│ ├── api.md
|
||
│ ├── extractors.md
|
||
│ └── help-system.md
|
||
│
|
||
├── tests/ # Playwright + vitest
|
||
│ ├── e2e/baseline/ # 114 张 baseline
|
||
│ ├── e2e/api/
|
||
│ ├── e2e/visual/
|
||
│ └── unit/
|
||
│
|
||
├── screenshots/ # 截图 (gitignored)
|
||
├── scripts/ # seed-tds-baseline.ts
|
||
└── .dacli-cache.db # SQLite 缓存
|
||
```
|
||
|
||
## 6 周路线
|
||
|
||
| Week | 任务 | 必达 |
|
||
|------|------|------|
|
||
| W0 准备 | doc + skill | ✅ 已完成 |
|
||
| W1 脚手架 | login + form list/create | tds/dev/work 都能登录 |
|
||
| W2 提取 | 5 个 extractor + Playwright | data/*.json 全部就位 |
|
||
| W3 developSystem | 21 张 baseline | 21/21 API 0 错 |
|
||
| W4 workSystem | 53 张 baseline | 53/53 API 0 错 |
|
||
| W5 帮助体系 | --ai-help + doc/apis | 镜像 Java 版 |
|
||
| W6 skill 完整 | AI 自检 + 文档 | AI 1 次对话完成请假流程 |
|
||
|
||
详见 [doc/plan.md](doc/plan.md)。
|
||
|
||
## 与 Java 版的关系
|
||
|
||
| 维度 | Java 版 (生产) | TS 版 (实验) |
|
||
|------|----------------|---------------|
|
||
| 稳定 | ⭐⭐⭐⭐⭐ (6 月打磨) | ⭐⭐ |
|
||
| AI 友好 | ⭐⭐⭐ | ⭐⭐⭐⭐⭐ |
|
||
| Schema 真相 | 53 builder 硬编码 | data/*.json 自动 |
|
||
| Baseline | 40 form | **74 form** |
|
||
| Playwright | ssw-e2e-test (Python) | **@playwright/test (Node)** |
|
||
| 启动 | 100ms native | < 500ms tsx |
|
||
| 定位 | 生产 | 实验 |
|
||
|
||
**v1 不替代**。v2 评估后再决定。
|
||
|
||
## 反向链接
|
||
|
||
- [prompt.md](prompt.md) — 完整任务说明书
|
||
- [doc/architecture.md](doc/architecture.md) — 设计决策
|
||
- [doc/plan.md](doc/plan.md) — 6 周路线
|
||
- [doc/baseline.md](doc/baseline.md) — 0 差错验证
|
||
- [doc/api.md](doc/api.md) — 完整 API
|
||
- [doc/extractors.md](doc/extractors.md) — 提取工具
|
||
- [doc/help-system.md](doc/help-system.md) — 帮助体系
|
||
- [.claude/skills/dacli-ts/SKILL.md](.claude/skills/dacli-ts/SKILL.md) — AI 技能主入口
|
||
- [.claude/skills/dacli-ts/references/](.claude/skills/dacli-ts/references/) — 6+ 文档
|
||
- [.claude/skills/dacli-ts/examples/](.claude/skills/dacli-ts/examples/) — 7+ 脚本
|
||
- [../ddcc/](../ddcc/) — 上一轮实验 (验证可行性)
|
||
|
||
---
|
||
|
||
**生成时间**: 2026-06-12
|
||
**作者**: Claude (M3) + 用户
|
||
**核心目标**: **74 张官方示例 API 0 错 + 浏览器 0 视觉差**
|