dapei-cdr

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 bootstrap mall-order

(One-shot: runs cdr.profile + cdr.entries.candidate in a single call. The AI still owns cdr.entries.propose / confirm — see P3 red line.)

@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 suggest domains
@dapei synth capability map for E-Commerce Mall
@dapei render L1 portal

@dapei generate documentation portal

@dapei list assets

设计原则

三层知识结构

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

边界

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

路由能力

工作流

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 工作流。

v0.6 — Use structured calls

behavior.calls[] 现在接受两种形态：

# Legacy — 继续可用
calls: ["PaymentClient", "InventoryService"]

# Structured (v0.6 推荐) — 引擎会把 target_repo 提到 index
calls:
  - target: PaymentClient
    protocol: http
    target_repo: mall-payment
    evidence: { file: src/paymentClient.ts, line: 12, repo: mall-order }
  - target: order.events:order.created
    protocol: mq
    evidence: { file: src/events/publisher.ts, line: 3, repo: mall-order }

每个调用的字段：

• target（必填）：被调的 service / topic 名
• protocol（推荐）：http | grpc | mq | event | rpc | other
• target_repo（推荐）：被调方所属的 repo 名——AI 必须显式声明，引擎不做语义推断
• evidence（推荐）：单条 SourceRef，指向调用点（不是定义点）

为什么需要 target_repo：portal 渲染时，Cross-service calls 段只列有 target_repo 的调用；cognitive-index 的 target_repos 字段只从显式声明的调用中抽取。不声明 = 引擎无信息可记录，与 v0.5 的"AI 自由填写"行为相同。

从已确认的入口出发，沿调用链追踪：

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 5.5 — Cross-repo Business Rules（v0.5 跨仓库业务规则）

@dapei build cross-repo rules
@dapei build cross-repo portal

目标：把"一个仓库做完某动作，另一个仓库在什么业务语义下做什么动作"沉淀为业务规则——不是图，是规则。引擎读所有 business-rule 的 applies_to[]，按 (id, repo) 复合键反查 index.behaviors[]，输出 docs/as-is/cross-repo/cross-links.yaml，分组渲染到 portal /cross-repo/。

问自己（AI 主动识别）：

每识别出一条跨仓库关系，就调 cdr.business.compose 写一条规则：

• applies_to: [behavior_id_in_repo_a, behavior_id_in_repo_b, ...] —— 把两边的 behavior id 都填进去
• kind 按上表选
• confidence.kind = fact 时必须带 sources[]（指向被识别为订阅者的代码，例如 subscriber.handle(event) 的文件行号）

对引擎的要求：

引擎做的是只读计算——不写 behavior / 不写 business-rule。AI 端必须主动调 cdr.business.compose 把跨仓库关系先沉淀成业务规则，然后 cdr.business.crosslink 才能算出来。这是 v0.5 的本质：业务规则是 AI 端的责任，跨仓库视图是引擎端的呈现。

@dapei build cross-repo rules 调用的能力：cdr.business.crosslink @dapei build cross-repo portal 调用的能力：cdr.crossrepo.doc.generate

产物：

• docs/as-is/cross-repo/cross-links.yaml（引擎计算结果，分组 by kind）
• .dapei/docs-portal/cross-repo/（portal 渲染，按 kind 分组页面 + Mermaid 关系图）

Phase 5.7 — Reverse-cluster to L1（v0.8 反向聚类为 L1）

@dapei suggest domains
@dapei synth capability map for E-Commerce Mall
@dapei render L1 portal

目标：从已经写好的 behavior / business-rule 反向聚类出候选 domain 和候选 capability map，让 AI 端审阅、命名、调优后再 commit。引擎永远不直接写 domain.yaml —— compose 仍然是 AI 端的事。

两阶段流水线（建议调用顺序）：

cdr.domain.suggest
   ↓  写入 docs/as-is/cross-repo/domain-suggestions.yaml
   ↓  AI 审阅 clusters[], 选有用的
cdr.domain.compose (人工逐条)
   ↓  写入 docs/as-is/domains/<domain>.yaml
cdr.capability.map.synth
   ↓  读取 composed domains + suggestions, 回填 spans_repos/fact_ratio
   ↓  写入 docs/as-is/capabilities/product-map.yaml
cdr.reversecluster.doc.generate
   ↓  读取 product-map + suggestions
   ↓  渲染 .dapei/docs-portal/l1/

第一步：cdr.domain.suggest

引擎按 4 种边类型把 cognitive index 的 behaviors 聚类为连通分量：

聚类结果是只读建议，写到 docs/as-is/cross-repo/domain-suggestions.yaml。每个 cluster 带：

• suggested_name + suggested_domain_slug + naming_reason（从 events 高频主语推断）
• confidence: high | medium | low（high = shared-events + 跨 repo）
• behavior_keys[]、repos[]、evidence[]

AI 端做什么：读 yaml，挑出置信度够高的 cluster，逐个调 cdr.domain.compose 把它们落实成 domain。每个 compose 出来的 domain 才有 derived_from 红线保护。

第二步：cdr.capability.map.synth

引擎读 domain 来源（按优先级）：

1. input.manual_domains[]（AI 端预备的精选清单）
2. docs/as-is/domains/**/*.yaml（已 compose 的）
3. domain-suggestions.yaml（仅当 use_suggested_domains: true）

对每个 capability，引擎从 cognitive index 反查 spans_repos / behavior_count / fact_ratio —— 这是 AI 端没办法自己算的客观指标。结果写到 docs/as-is/capabilities/product-map.yaml（与 v0.3 的 cdr.capability.map.init 同文件，但字段更丰富）。

第三步：cdr.reversecluster.doc.generate

读 product-map + domain-suggestions，渲染 /l1/：

• l1/index.md — 产品全景 + Mermaid 总图（capability 子图 + 跨 repo 关系）
• l1/<capability-id>.md — 每个 capability 的详情页
• l1/cluster-suggestions.md — cdr.domain.suggest 的建议原文，方便 AI 对照

关键约束：

• cdr.domain.suggest 绝不调 cdr.domain.compose —— 这是 P1 红线的延伸：建议和 commit 分两步。
• cdr.capability.map.synth 是幂等可重入的；不传 manual_domains[] 时自动从 composed + suggested 拿。
• 空工作区是合法状态：synth 写 status: empty 头，doc gen 渲染 empty-state l1/index.md，AI 看得到明确的下一步指引。

@dapei suggest domains 调用的能力：cdr.domain.suggest @dapei synth capability map for X 调用的能力：cdr.capability.map.synth @dapei render L1 portal 调用的能力：cdr.reversecluster.doc.generate

产物：

• docs/as-is/cross-repo/domain-suggestions.yaml（建议清单，可覆盖重写）
• docs/as-is/capabilities/product-map.yaml（合成的功能地图）
• .dapei/docs-portal/l1/（L1 portal section，与 /cross-repo/ 平级）

Phase 6 — Documentation Portal（文档门户）

@dapei generate documentation portal

自动编译所有认知资产为 VitePress 静态站点：

• L1 功能地图 → 首页 + 能力页
• L2 领域模型 → 领域页 + Mermaid 模块关系图
• L3 行为/状态 → 流程页 + Mermaid 流程图/状态图
• 代码溯源链接 → 可点击跳转源文件

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

启动预览：

cd .dapei/docs-portal && npx vitepress dev

Phase 8 — Pipeline Status（编排状态查询）

@dapei what is the cdr pipeline status for mall-order

读出端 cdr.pipeline.status,read-only。给定 repo 后返回 8 阶段 (profile / entries / behavior / state / domain / rule / capability-map / doc) 的 status + artifacts_count + 下一个该调的能力和 input 形状。

• status 取值:
  • done — 阶段产物已存在
  • blocked — 还没产物,且下一步依赖未完成
  • skipped — 阶段可选(rule 默认 skipped)
• next_action:每个未完成阶段的 capability / input_template / hint。AI 应该把 next_action.capability 当作下次必调, input_template.required_fields 列出必填字段。
• up_to_phase 参数:截断报告(如只关心 entries 之前)。
• overall_status: empty / partial / complete (skip 算 complete 的一部分)

典型用法:

# 完整跑过 profile 后,问下一步
runCapability('cdr.pipeline.status', { repo: 'mall-order' })
# next_action: cdr.entries.candidate

# 已跑完 entries,只关心 state 之后
runCapability('cdr.pipeline.status', {
  repo: 'mall-order',
  up_to_phase: 'state'
})

rule 阶段:在用户未显式声明 business-rule 知识时默认 skipped。 AI 决定"这个 repo 确实没有跨仓 SLA / 授权规则"时,可直接跳过到 capability-map。

Phase 7 — Query（跨仓查询）

@dapei query behaviors that emit order.cancelled
@dapei find behaviors calling PaymentClient in mall-payment
@dapei list behaviors created by feature payment-refactor

读出端 cdr.query,read-only,跨仓/跨能力查找:

• 行为级过滤:event / writes_table / calls_target / target_repo (state-machines 在这类 filter 下自动隐藏——避免语义混淆)
• 通用过滤:entity(state-machine)/ id_contains(子串)/ repo(精确)/ created_by_feature(精确)/ target(behavior / state-machine / business-rule / domain / capability-map / any)
• 结果:{ results: [...], total, next_step },limit 默认 50,上限 500
• 永不变更 cognitive index 或 docs/as-is/——纯读

典型用法:

# 找出所有调用 mall-payment 的行为
runCapability('cdr.query', { target_repo: 'mall-payment' })

# 找出所有 order-cancel 行为的入口
runCapability('cdr.query', { id_contains: 'order-cancel', target: 'behavior' })

# 列出某个 feature 创建的所有资产
runCapability('cdr.query', { created_by_feature: 'payment-refactor' })

created_by_feature 来源:feature.close 自动调 cdr.feature.link 给本次 feature 接触到的所有 cognitive index / domain / capability-map 资产 打上 created_by_feature: <feature> 标签(也支持 feature.review 显式调)。 pre-v0.10 资产无该字段——filter 会保守返回空而不是 error。

当查询语义模糊时(比如行为 yaml 里 events 字段缺失),cdr.query 会保守返回空而不是猜测——这是 P1 红线的延伸。

产物目录结构

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 是扩展层,不是替代层。

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

测试侧迁移: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