auto(09213057c521): session end @ 2026-06-22T18:51:30 (+1f)

This commit is contained in:
ssw committed 2026-06-22 18:51:31 +08:00
1 parent 1b6bf7b247
commit 03eb5ff903
1 file changed
+66 -3
+66 -3
View File
@@ -11,6 +11,34 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
详细设计: `doc/architecture.md` (6 个关键决策)、`doc/plan.md` (6 周路线)、`doc/v0.7-changelog.md` (最新校准)。
## ⚠️ v0.10+ AI 防御体系 (强制)
**任何 AI 使用 dacli 前必读**:根因 G(舍近求远,读文档不读源码)+ B/C/D(盲猜参数/状态)已通过三层防御拦截。
| 层级 | 触发时机 | 文件 | 失败行为 |
|------|---------|------|---------|
| **L1 precheck** | form/dm create 执行前 | `src/commands/_precheck.ts` | exit 2 + 错误清单 + 修复建议 |
| **L2 guard** | pre-check 通过后、API 调用前 | `src/commands/_blindspot_guards.ts` | ERROR → exit 2;WARN → 仅打印 |
| **L3 diagnose** | API 返回模糊错误时 | `src/core/client.ts:225 diagnoseError()` | log.warn 输出 3 类可能原因 |
**新会话 4 步流程**(AI 必跑):
```bash
# Step 1: 拉环境快照(消除 B 类根因:凭"经验"猜 dbLinkId/enCode)
dacli app context --json
# Step 2: 看懂已有什么
dacli form list && dacli dm list
# Step 3: 看命令 AI 用途 + 权威来源(不猜参数/API)
dacli <cmd> --ai-help # 命令 AI 用途
dacli <cmd> --source # 权威源码/API/ref 链接
dacli <cmd> --example # JSON 参数示例
# Step 4: 执行 + 长任务自检(每 5 步)
bash /home/ubuntu/ccWorkDir/.claude/skills/dacli-ts/scripts/self-check.sh [form_id]
```
**权威参照规则**:参数/API/默认值不确定时,**优先读 web/ 源码**(`web/apps/jnpf-web-apps-main/src/views/onlineDev/` + `web/.../api/`),不读 dacli 文档。dacli 文档是导航索引,web/ 源码是事实。
完整文档:`.claude/skills/dacli-ts/SKILL.md` + `references/{errors,commands,patterns,web-source-map}.md`
## 启动 & 常用命令
```bash
@@ -21,10 +49,13 @@ npx playwright install chromium # 装浏览器 (baseline E2E 用)
# CLI 调用
npx tsx src/cli.ts --help # 入口 (启动 < 500ms)
npx tsx src/cli.ts app login --appCode=tds # 登录 (v0.9 归入 app 命名空间)
npx tsx src/cli.ts app context --json # ⭐ v0.10+ P0.1:AI 新会话第一步必跑
npx tsx src/cli.ts form list # 列已有表单
# 提取 web 源码到 src/data/*.json
node scripts/extract-all.mjs
# v0.10+ 新增:从 web/ Vue 源码提取 schema/API → data/web-derived-schemas.json
python3 scripts/extract-web-schema.py
```
**包脚本** (npm run ...):
@@ -111,9 +142,16 @@ output (JSON / table / --ai-help markdown)
## 子项目 skill
- `.claude/skills/dacli-ts/SKILL.md` — 主技能(v0.7 校准:form release 改 `/Actions/Release` 端点、dm create 改 web 真路径 `dataModel/Form.vue:218` 形态、menu create 退到低级 API 兜底等)
- `.claude/skills/dacli-ts/references/` — 6+ 专题文档(commands、playwright、troubleshooting、extraction 等)
- `.claude/skills/dacli-ts/SKILL.md` — 主技能(**v0.10+** 强制:三层防御体系 + 强制参照 web/ 源码 + 长任务自检)
- `.claude/skills/dacli-ts/references/` — 6 专题文档:
- `errors.md` — 错误决策树(26 段,**AI 报错唯一推荐入口**)
- `commands.md` — 命令完整用法(含 form→dm 字段映射 R5 表)
- `patterns.md` — 反模式 + 校准
- `web-source-map.md` — web/ 源码权威映射(**最高优先级**,参数不确定先查这里)
- `playwright.md` — 浏览器层使用指南
- `troubleshooting.md` — ⚠️ 历史归档(已全部吸收到 errors.md / 代码 guard,仅 debug 历史问题按编号查)
- `.claude/skills/dacli-ts/examples/` — 7+ 可复用脚本(baseline、create-simple-form、菜单挂载等)
- `.claude/skills/dacli-ts/scripts/self-check.sh` — v0.10+ 长任务自检脚本(每 5 步跑一次)
## 父项目约定
@@ -126,7 +164,32 @@ output (JSON / table / --ai-help markdown)
完整规则见 `$ccWorkDir/.claude/CLAUDE.md`。
## 已知盲点与兜底 (v0.9+, AI 必看)
## 已知盲点与兜底 (v0.10+, AI 必看)
> **v0.10+ 升级**:高频 22 条盲点已从文档 → 代码 guard(`src/commands/_blindspot_guards.ts`),AI 不需要"记住",dacli 在执行时自动检查(详见 SKILL.md "三层防御体系")。
>
> **完整错误决策树**: `.claude/skills/dacli-ts/references/errors.md`(26 段,按错误关键词查修复步骤)
> **历史归档**: `.claude/skills/dacli-ts/references/troubleshooting.md`(52 条盲点流水账,仅 debug 历史问题按编号查)
### 高频盲点速查(v0.10+ 三层防御已自动覆盖)
| # | 盲点 | 触发场景 | 自动兜底 |
|---|------|---------|---------|
| 48 | dbLinkId=0 或未设置 | `dacli form create --type=1` → "Database exception" | L2 guard BS-48: exit 2 + 从 context 取正确 dbLinkId |
| 49 | enCode 重复 | form create 失败后再用同 enCode → "Encoding cannot be repeated" | L1 pre-check 拒绝 + L2 guard BS-49 提示改名 `_v2`/clone/delete |
| 50 | menu --formId 报 "主表不存在" | form schema 缺主表信息 | L2 guard BS-50: 提示走低级 `--type=3 --urlAddress=model/{enCode}` |
| 51 | 浏览器层 list 白屏 | dacli 简化 columnList 缺完整 schema 字段 | L2 guard BS-51: 提示 `dacli form clone` / `--tables` / no-spa-page |
| 47 | dict 全平台唯一 | `dacli dict typeCreate` 报 "The name cannot be repeated" | L2 guard BS-47: 提示 `<app>_` 前缀 |
| 5 | AppContext 空 | AI 凭猜测操作 | L2 guard BS-5: 强制先跑 `dacli app context --json` |
| 8 | token 过期 | JNPF 下线后操作 | L2 guard BS-8: 提示 `dacli app init -- --appCode=X --restart` |
| 38 | f_description 系统列冲突 | dm create 字段重名 | L2 guard BS-38: 提示改名 `f_desc`/`f_remark` |
| 39 | f_version 关键字 | form create 业务字段用 f_version | L2 guard BS-39: 提示改名 `f_version_no` |
| 28 | bare flag 不生效 | `--autoRelease` 看似生效但 state=0 | L2 guard BS-28: WARN 提示 v12+ 已修 |
**完整 22 条**: `src/commands/_blindspot_guards.ts` (449 行, ERROR + WARN 两级)
**集成测试**: `tests/integration/blindspot_guards.spec.ts` (16/16 PASS)
详细反模式 + 完整代码示例见 `.claude/skills/dacli-ts/references/anti-patterns.md`。
| # | 盲点 | 触发 | 兜底 |
|---|------|------|------|