---
name: dapei-cdr
description: Cognitive Discovery Runtime — Code-to-Knowledge extraction, domain composition, capability mapping, and documentation portal generation. Use when the user mentions "profile", "discover entries", "discover behaviors", "discover states", "compose domain", "capability map", "generate documentation", or "knowledge portal".
---

# dapei.cdr skill

Cognitive Discovery Runtime (CDR) 通过代码逆向推导，构建从微观到宏观的三层资产型知识体系。

## 用户入口

```
@dapei profile repo mall-order
```

```
@dapei discover entries for mall-order
```

```
@dapei discover behaviors for mall-order
```

```
@dapei discover states for Order in mall-order
```

```
@dapei compose domain Transaction from mall-order behaviors
```

```
@dapei compose business rule order-amount-positive for order-create
```

```
@dapei init capability map for E-Commerce Mall
```

```
@dapei generate documentation portal
```

```
@dapei list assets
```

## 设计原则

| 原则 | 规则 |
|------|------|
| P0 **AI 是扫描器,引擎是校验器** (v0.3) | 引擎**不**用 regex/annotation 预设入口候选;返回代码文件清单后由 AI 决定入口;引擎仅校验 AI 提交的事实证据(file 存在、line 在范围) |
| P1 行为先于领域 | `domain` 产物必须携带 `derived_from: [behavior-id, …]`;禁止仅凭包名命名领域 |
| P2 入口驱动 | 深析仅从 `status: confirmed` 的入口开始 |
| P3 证据优先 | `kind=fact` 必须附带 `sources[]`(file/line/repo);`kind=inference` 必须有 `derived_from[]`;`kind=unknown` 必须有 `reason` |
| P4 增量更新 | `profile` / `entries` 携带 `revision`;代码变更 → `stale` 标记 |

## 三层知识结构

```
L1 宏观层 — 产品功能地图 (Capability Map)
  ↑ 聚类自
L2 领域层 — 领域模型 + 入口目录 (Domain + Entries)
  ↑ 推导自
L3 流程层 — 行为链路 + 状态机 + 业务规则 (Behavior + State + Rules)
```

## 边界

| dapei 平台 | Agent |
|------------|-------|
| **代码文件清单**(cdr.entries.candidate)、schema 校验、YAML 索引、**evidence 落盘校验** | **代码阅读、入口识别**、业务语义理解、行为追踪、规则提炼 |
| 目录管理、增量 stale 检测 | 确认入口、生成 fact 级产物 |
| VitePress 站点编译 | 不涉及(自动化生成) |

**关键不变量**:AI 永远不直接落盘。所有 `cdr.*.upsert` 路径必须先经引擎校验 evidence(`sources[].file` 必须存在于 `repos/<repo>/<file>`,`line` 必须在文件行数范围内)后才能写入 YAML。这是 P3 红线。

## 路由能力

| 用户意图 | Capability | v0.3 说明 |
|----------|------------|----------|
| 生成 repo 技术画像 | `cdr.profile` | 移除 `frameworks` 字段(扫描器职责移交给 AI) |
| 列出代码文件供 AI 读取 | `cdr.entries.candidate` | **新增** — 廉价文件清单 + 内容切片 |
| AI 提交一条入口(含 evidence) | `cdr.entries.propose` | **新增** — 引擎校验 file:line |
| 发现入口候选(薄封装) | `cdr.entries.prepare` | 退化为 `cdr.entries.candidate` 的别名,加 workflow 提示 |
| 确认入口 | `cdr.entries.confirm` | **要求 sources[]**;缺证据拒绝 |
| 发现行为链路 | `cognitive.discover` → `cognitive.artifact.upsert` | 不变 |
| 写入行为产物(结构化字段) | `cdr.behavior.upsert` | fact 级 sources 强校验 |
| 推导状态机 | `cdr.state.derive` | inference 草稿;sources 可选 |
| 聚合领域模型 | `cdr.domain.compose` | derived_from 强校验 |
| 组合业务规则 | `cdr.business.compose` | **新增(在 v0.2)** — 5 种 rule kind |
| 初始化功能地图 | `cdr.capability.map.init` | 不变 |
| 列出所有资产 | `cdr.index.list` | 不变 |
| 生成文档门户 | `cdr.doc.generate` | 不变 |

## 工作流

### Phase 0 — Profile（技术画像）

```
@dapei profile repo mall-order
```

**目标**：生成 repo 级技术画像，包含语言栈、框架、目录结构、测试命令。

**产出**：`docs/as-is/profiles/<repo>.yaml`

### Phase 1 — Entry Discovery（入口发现，v0.3 重设计）

```
@dapei discover entries for mall-order
```

**目标**：列出 repo 中的代码文件,让 AI 读取并识别入口,**引擎不做框架预设**。

**新流程**:

1. **引擎**: `runCapability('cdr.entries.candidate', {repo: 'mall-order'})`
   - 返回 `files[]`,每项含 `relpath` / `language` / `content`(已 inline)
   - 没有 framework 字段,没有 pattern 匹配
2. **AI** (在 chat session 中): 阅读 `content`,用 LLM 的理解力识别入口
   - 找出 Spring `@RestController` / NestJS `@Controller` / FastAPI `@app.get` / Express (app.get) / Quarkus / Ktor / Hapi / Axum / gRPC / GraphQL / 自定义路由 / 动态注册
3. **AI**: 对每个识别出的入口,调 `runCapability('cdr.entries.propose', {repo, id, type, file, line, method, path, sources: [{file, line, repo}]})`
   - 引擎校验 `sources[].file` 存在于 `repos/<repo>/<file>`
   - 引擎校验 `line` 在文件行数范围内
   - 通过则写入 `docs/as-is/entries/<repo>.yaml`(`status: candidate`)
4. **人 / AI**: 调 `runCapability('cdr.entries.confirm', {repo, entry_id, summary, priority, sources: [...]})` 标记为 `status: confirmed`
   - `sources[]` 是**必填**的——确认入口也必须指 evidence

**旧版(v0.2)废弃路径**: `cdr.entries.prepare` 现在退化为薄封装,内部调用 `cdr.entries.candidate` 后返回 workflow 描述;不再返回平台自动识别的 entry 列表。新代码请直接用 `cdr.entries.candidate` + `cdr.entries.propose`。

**产出**:`docs/as-is/entries/<repo>.yaml`(`status: candidate` → `status: confirmed`)

### Phase 2 — Behavior Mining（行为深析）

```
@dapei discover behaviors for mall-order
```

使用已有的 `cognitive.discover` + `cognitive.artifact.upsert` 工作流。

**从已确认的入口出发**，沿调用链追踪：
1. 识别数据库写入 (`writes`)
2. 识别事件发布 (`events`)
3. 识别外部调用 (`calls`)
4. 识别潜在风险 (`risks`)

**产出**：`docs/as-is/behavior/<id>.yaml`

### Phase 3 — State Mining（状态推导）

```
@dapei discover states for Order in mall-order
```

**从已有 behavior 中推导实体状态机**。

**产出**：`docs/as-is/state-machines/<entity>.yaml`

### Phase 4 — Domain Composition（领域聚类）

```
@dapei compose domain Transaction from mall-order behaviors
```

**将零散的 behavior 聚类为领域模型**，必须携带 `derived_from`。

**产出**：`docs/as-is/domains/<domain>.yaml`

### Phase 5 — Capability Map（功能地图）

```
@dapei init capability map for E-Commerce Mall
```

**初始化产品级功能大图**，关联已有领域。

**产出**：`docs/as-is/capabilities/product-map.yaml`

### Phase 6 — Documentation Portal（文档门户）

```
@dapei generate documentation portal
```

**自动编译所有认知资产为 VitePress 静态站点**：
- L1 功能地图 → 首页 + 能力页
- L2 领域模型 → 领域页 + Mermaid 模块关系图
- L3 行为/状态 → 流程页 + Mermaid 流程图/状态图
- 代码溯源链接 → 可点击跳转源文件

**产出**：`.dapei/docs-portal/`（VitePress 项目）

启动预览：
```bash
cd .dapei/docs-portal && npx vitepress dev
```

## 产物目录结构

```
docs/as-is/
├── profiles/           ← L0 技术画像
├── entries/            ← L2 入口目录
├── behavior/           ← L3 行为链路
├── state-machines/     ← L3 状态机
├── business-rules/     ← L3 业务规则
├── domains/            ← L2 领域模型
└── capabilities/       ← L1 功能地图

.dapei/
├── cognitive/index.yaml ← 统一资产索引
└── docs-portal/         ← VitePress 生成站点
```

## 红线

- **禁止**跳过 Entry 确认直接生成 behavior
- **禁止** domain 产物缺少 `derived_from`
- **禁止**用 grep 替代语义分析
- **禁止**将 CodeGraph 静态拓扑直接作为业务事实
- **禁止**(v0.3)在引擎里写 framework-specific regex/annotation 扫描器——AI 已经会读代码,引擎只需要校验 AI 提交的 evidence
- **禁止**(v0.3)`cdr.entries.confirm` / `cdr.behavior.upsert` 在 `kind=fact` 时不带 `sources[]`——引擎直接拒收
- **禁止**(v0.3)AI 直接写 YAML 文件——必须通过 `runCapability` 让引擎校验后再落盘

## 兼容性

原有 `cognitive.*` 能力保持不变。CDR 是扩展层,不是替代层。

| 旧意图 | 映射 |
|--------|------|
| `@dapei analyze behavior for X` | → `cognitive.discover` (不变) |
| `@dapei list behaviors` | → `cognitive.artifact.list` (不变) |
| `@dapei cognitive validate` | → `cognitive.artifact.validate` (不变) |

## v0.3 迁移指南(从 v0.2 升级)

| v0.2 | v0.3 |
|------|------|
| `@dapei discover entries for X` → `cdr.entries.prepare` 返回 `entries[]` 平台扫描结果 | `@dapei discover entries for X` → `cdr.entries.candidate` 返回 `files[]`,**AI 读 content 后**调 `cdr.entries.propose` |
| `entries[].framework` = "spring" / "nestjs" / "fastapi" / "express" | 字段**不存在**——AI 不需要这个分类 |
| `entries[].discovered_by` = "platform" / "platform-annotation" | `discovered_by` = "ai" 统一 |
| `cdr.entries.confirm` 仅需 `summary` | `cdr.entries.confirm` **必须**带 `sources[]` |
| `cdr.profile` 包含 `frameworks: [...]` | `frameworks` 字段**移除**——AI 从 `manifest_files` 推断 |
| 引擎硬编码 4 套 framework regex(150 行) | 引擎 0 行 framework 知识——AI 处理 |

测试侧迁移:`tests/unit/cdr.test.mjs` 中 35 个"扫到 @GetMapping" 类断言被替换为"拒收 line 99999" / "拒收 file 不存在" / "kind=fact 无 sources 拒收" 三类 evidence-validation 断言;`tests/ai-behavior/cdr-ai-as-scanner.yaml` 新增 L4 transcript fixture 覆盖完整 candidate → propose → confirm 流程。

## 与其他 skill 的协作

- **feature**：`feature.create` 注入 CDR 索引摘要到 `related-cdr-context.md`
- **repos**：`cdr.profile` 替代 `repos.analyze` 中的语义 grep 部分
- **workflow**：`context.build` v3 注入 profile + entries + behavior 摘要表
- **validation**：未来 COG-001 门禁：进入 `solution-design` 前需 ≥1 confirmed entry + ≥1 fact behavior