Files
dacli/README.md
T
ssw c98ad4f425 init: TS 版 dacli v0.7 baseline (8 父命令/26+ 子命令, 0.4MB, .claude/skills/dacli-ts)
参考 boot/ 仓库结构初始化, 同步到 gitea:3000/ssw/dacli (private).

包括:
- src/  8 父命令 (form/menu/dm/dict/di/apis/doc/workflow + login/status) + core (client/crypto/help/log/types/config)
- src/schema/ FieldBuilder (从 JNPF web 源码提取, 避免 53 个手写 builder)
- tests/ vitest 单元 + playwright E2E (含 workSystem/developSystem baseline regression)
- scripts/ extract-all.mjs (从 jnpf-web 源码生成 schema) + seed-tds-baseline.ts
- doc/  architecture/plan/api/extractors/baseline/RESUME/help-system + v0.6/v0.7 changelog
- .claude/skills/dacli-ts/  Claude 集成 skill (SKILL.md + 5 references + 7 examples + 3 baseline)
- CLAUDE.md (项目说明) + README.md + prompt.md (开发任务说明书)
- 配置文件: package.json/lock, tsconfig, vitest.config, playwright.config
2026-06-12 18:26:39 +08:00

155 lines
6.2 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 验证用)
node scripts/extract-all.mjs # 提取 web 源码到 data/*.json
npx tsx src/cli.ts 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/ # 嵌套子命令
│ ├── core/ # 基础设施
│ ├── extractors/ # web 源码提取
│ ├── data/ # 提取 JSON
│ └── schema/ # FieldBuilder
│
├── .claude/skills/dacli-ts/ # ⭐ AI 专用 skill
│ ├── SKILL.md # 主入口
│ ├── references/ # 6+ 文档
│ └── examples/ # 7+ 可复用脚本
│
├── 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/ # extract-all / verify-baseline
└── .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 视觉差**