57 lines
6.5 KiB
Markdown
57 lines
6.5 KiB
Markdown
---
|
||
name: dever-language
|
||
description: 开发、检查或维护 Dever 语言应用（.dever、.dever.md），创建项目，安装更新 dever，接入 Package 或 Python/JS/Go Lib 时使用。涵盖目录、语法、权限、租户与代码质量约束。不用于 Go Dever 框架或 dever-go。
|
||
---
|
||
|
||
# Dever 语言开发
|
||
|
||
Dever 是独立语言。应用源码使用 `.dever` 或 `.dever.md`，不沿用 Go Dever 的 service、Page JSON 或 Provider 目录；第三方语言实现经 Port/Adapter 接入。
|
||
|
||
## 先确定版本和范围
|
||
|
||
1. 读取用户项目的 `AGENTS.md`、现有目录和 `config/setting.json`。回答、分析、诊断只做只读检查；用户要求修改时再实施，不擅自安装软件、改服务或改全局命令。
|
||
2. 已有项目运行 `dever skill path <project-root>`，新项目运行 `dever skill path`。完整读取返回目录中的 `SKILL.md` 与本次需要的参考；已在该目录读取时不重复加载。项目可用 `dever.version` 锁定编译器版本，规则随该版本选择。
|
||
3. 尚无 `dever` 时按 [安装与更新](references/install.md) 引导安装；不能把 `dever-go` 当作 Dever 语言命令。先核对主机平台和安装前提，安装失败时保留真实错误，不用缺少运行资源的源码开发二进制冒充完整安装。
|
||
4. 新项目使用 `dever new <new-directory>`；Markdown 项目加 `--markdown`。它会自动生成 `AGENTS.md`。已有项目需要接入或刷新规则时，在项目根目录运行 `dever skill install`，无需指定技能目录。不要手工猜模板或覆盖已有项目。
|
||
|
||
开发、重构或审查应用代码前，必须读取 [项目开发](references/development.md) 中的文件与函数组织、配置与硬编码、禁止绕过检查、验证范围。安装或纯语法问答只加载与请求相关的参考。
|
||
|
||
## 按需要阅读
|
||
|
||
| 工作 | 先读 |
|
||
| --- | --- |
|
||
| 新项目、目录、命名、测试与交付 | [development.md](references/development.md) |
|
||
| 类型、分句、函数、集合、失败和并发 | [language.md](references/language.md) |
|
||
| HTTP/CMD、Model、权限、租户、Job | [application.md](references/application.md) |
|
||
| 标准能力、外部生态、Package | [libraries.md](references/libraries.md) |
|
||
| HTTP/REST、Job、集合、Port fake 的完整项目 | [examples.md](references/examples.md)，只读所需示例 |
|
||
| 常用调用的参数、返回值与失败边界 | [signatures.md](references/signatures.md) |
|
||
| Python/JS/Go 外部 Lib 的同一 Port 合同 | [external-lib.md](references/external-lib.md) |
|
||
| Markdown 源码 | [markdown.md](references/markdown.md) |
|
||
| 安装命令、安装 skill、更新 | [install.md](references/install.md) |
|
||
|
||
只加载当前任务相关参考。完整项目与常用签名随此 skill 一起提供，不需要源码 checkout。当前版本的编译器检查和已验证资产决定语法；索引未覆盖的能力再查官方对应版本源码，不能按其它语言习惯杜撰方法。
|
||
|
||
## 必须遵守
|
||
|
||
- 默认只实现当前接口与语法。除非用户明确要求，禁止加旧参数、旧接口、旧配置的兼容分支、别名或备用实现。改接口时同步本项目调用方，删除本次废弃路径。项目锁定编译器版本不等于保留兼容代码。
|
||
- 配置只在 `config/setting.json`；不通过环境变量读取配置、密码、数据库 URL 或选择工具链。不要把 Dever 的官方仓库地址、更新配置写入业务项目。
|
||
- 业务数据放 Model；用户、租户与权限来自可信上下文。不按特殊账号、租户或记录的 ID 开业务特例，不把测试数据当生产兜底。正常字面量与稳定业务常量可以保留。
|
||
- 应用目录是 `module/<component>/<domain>/<role>.dever`；role 只有 `app/domain/model/port/adapter/api/job`。复杂职责再按主题拆分，不机械地每个函数建一个文件，不建 `common/utils/helper/base/service` 杂物目录。
|
||
- 不写 `package/import/exposes/main`。应用入口由 API、CMD、Job 声明生成。App 是对外领域能力；跨领域只调用目标 App，不直接调用其私有 Model、Domain、Adapter。
|
||
- API 只声明绑定或 REST，App 编排，Domain 保存内聚的业务规则，Model 声明持久化合同，Port/Adapter 隔离外部 I/O。已有标准能力直接复用，禁止重复手写 ID 解析、分页裁剪、JSON 拼装等碎片函数。
|
||
- 函数使用命名输出和互斥、穷尽的相邻分句；没有 `if/else/switch/match/return`、任意循环或递归。不要靠分句顺序隐藏重叠规则。
|
||
- HTTP 默认有权限，匿名入口才写 `public`。不添加 `auth.require`、客户端自报身份/权限或每个 API 重复鉴权。站点按配置里的 API 目录匹配，租户按数据库隔离。
|
||
- 测试放在 `test/<component>/<domain>/<topic>.dever`，入口为文件同名 `topic() ()`。外部调用使用 case-local Port fake，不在普通测试启动真实 Lib 或访问真实业务数据库。
|
||
- `run/build` 离线。依赖准备使用显式 `dever package` / `dever lib` 命令；已有锁在新机器用 `dever lib install`，ARM 应用目标用 `dever target add linux-aarch64`。这些命令按需准备机器共享资源，不扫描宿主 Python、Node、Go 或 PATH 来充当运行环境。
|
||
|
||
## 工作方式
|
||
|
||
1. 修改前查相关领域、实际调用链、标准能力和既有实现。对非平凡改动简要说明缺少什么行为、应该由哪一层负责、哪些文件需要改变；已有实现满足要求时保留它。
|
||
2. 实施时以完整业务职责组织文件和函数。抽取须有业务含义、明确不变量、实际复用或降低复杂流程理解成本的作用；不按行数或函数个数机械拆分。只清理本次引入或废弃的重复与死代码，保留无关改动。
|
||
3. 完成后审查新增调用链、公开合同、配置与可信身份来源，检查本次引入的诊断并执行范围内验证。禁止假调用、吞错、假成功、擅自修改接口基线或弱化测试来通过检查；详见开发指引。
|
||
|
||
`fmt --check` 查格式，`check` 查源码、配置及无法从业务入口调用到的代码，`test` 执行测试。具体见 [验证范围](references/development.md#验证范围)。已有项目优先 `dever test <root> --filter component.domain.case`；筛选仍检查全部源码，每例默认 60 秒，可用 `--timeout-ms` 调整。执行已授权的检查；启动服务、接真实数据库或改系统安装遵守用户限制。
|
||
|
||
交付说明实际改动、验证结果与未验证边界。规则写入 skill 不等于新增编译器检查，能编译不等于业务验收、性能验收或已发布。
|