ygwa dapei.cognitive skill
Engineering Cognitive Runtime 行为认知工作流。只提供流程方法，不提供具体实现指导。
边界
| dapei 平台 | Agent |
|---|---|
| 目录脚手架、产物 schema、evidence 校验、索引 | 读代码、判断栈、选择入口策略、生成候选与事实 |
| 输出结构化 YAML 契约 | 理解「这个入口做什么」 |
禁止：平台用 grep/regex/语言特定关键字替 Agent 做语义理解。
禁止绕过：紧急情况（如生产故障）不是跳过 artifact 记录的理由。
- 快速定位调用点 + 立即创建 artifact 是同时进行的，不是先后的
- grep/search 找到位置后必须写入
docs/as-is/behavior/<id>.yaml - "先快速解决，回头再补文档" = 违反此 skill
路由能力
| 意图 | Capability |
|---|---|
| 准备 discover 工作区 | cognitive.discover |
| 校验认知产物 | cognitive.artifact.validate |
| 写入并索引 | cognitive.artifact.upsert |
| 列出已确认产物 | cognitive.artifact.list |
| state draft（可选） | cognitive.state.suggest |
工作流（方法，非实现）
Phase 1 — Orient（定向）
目标：判断这是什么项目、用什么语言/框架。
Agent 自行决定怎么做，常见起点包括：
- 看目录结构（如
tree） - 读栈 manifest（如
package.json、pom.xml、go.mod、Gemfile等——按实际存在的文件来）
产出：对 repo 的栈与布局判断（写在分析报告或 _candidates.yaml 的备注中）。
cognitive.discover 仅提供 directory_tree + manifest_files 路径，不替 Agent 下结论。
Phase 1.5 — Sub-agent 委派（多 repo 时）
当 workspace 含 ≥ 3 个 repo 或单个 repo > 1000 文件时，Phase 1-3 不应在主 agent context 内串行执行 —— 读代码量会把主 context 撑爆。正确做法：
- 主 agent 用 AI 客户端的 sub-agent 原语（OpenCode
task(subagent_type="explore", run_in_background=true)/ Claude CodeTask tool/ CursorExplore）唤起一个专门做"读代码 + 写候选"的 explore sub-agent。 - Sub-agent 在自己的 context 里跑 Phase 1-3 全部工作：
- 读
directory_tree+manifest_files - 决定入口策略（HTTP/RPC/事件/定时）
- 列出候选清单到
docs/as-is/behavior/_candidates.yaml
- 读
- Sub-agent 回主 agent 一份 ≤ 1KB 的结构化摘要（不要回代码原文）：
repo: <name> language: <lang> candidates_count: <n> top_candidates: - id: <entry-id> file: <path> why: "<一句话描述它做什么>" evidence_quality: high|medium|low risks_to_confirm: [<risk-id>, ...] - 主 agent 拿到摘要后逐个调
cognitive.artifact.upsert/cdr.entries.propose—— 这是 schema-validated 的小写入，留在主 context 是必要的。
80 repo workspace 的特殊模式：用一个 explore sub-agent 跑 repos.analyze --all，主 agent 只收汇总；如果其中有 ≥ 5 个 repo 触发 Phase 4（deep dive），按 repo 分组 fan-out 到 N 个 parallel sub-agent，每个负责一个 repo 的 Phase 4，主 agent 在收到所有 sub-agent 摘要后再统一生成 cross-repo 视图（domain.compose / capability.map.synth）。
工具映射：见 Router SKILL.md 的 ## Tool Delegation Protocol 与 ## Tool Support Matrix。本 skill 不重复定义工具调用约定，只声明 Phase 1-3 / 80+ repo 场景必须走 sub-agent。
Phase 2 — Strategy（入口策略）
目标：决定如何在本栈中定位行为入口。
由 Agent 根据 Phase 1 结论自行选择策略——平台不 prescribe 关键字、注解名、目录约定。
行为入口类型（概念层，非搜索关键词）：
- HTTP/RPC 入口
- 消息消费 / 事件订阅
- 定时任务
- 其他触发系统状态变化的外部边界
Phase 3 — Candidates（候选清单）
目标：列出待深析的行为入口。
- Agent 按 Phase 2 策略阅读代码
- 理解每个入口做什么（语义，非签名）
- 写入
docs/as-is/behavior/_candidates.yaml
候选允许 inference / unknown；深析后再升为 fact。
Phase 4 — Deep Dive（逐个深析）
对每个 candidate：
- 沿调用链追踪（Agent 自行决定读哪些文件）
- 回答：谁 / 在什么条件下 / 修改什么状态 / 产生什么事件
- 写入
docs/as-is/behavior/<id>.yaml cognitive.artifact.upsert校验并更新 index- 必要时同步
docs/as-is/state-machines/<entity>.yaml
Phase 5 — Report
输出 Conclusion / Risk / Needs Confirmation / Next Steps。
产物契约（schema，非实现指导）
以下字段是落盘格式，不是「怎么找代码」的教程。
Candidate 示例：
candidates:
- id: order-create-candidate
repo: sample-app
summary: "<Agent 用自然语言描述该入口做什么>"
entry: { type: api, method: POST, path: /orders }
confidence: { level: medium, kind: inference, evidence_type: code_reading }
derived_from: [agent.discover]
sources: [{ file: src/routes/orders.ts, line: 6 }]
Behavior 示例：
id: order-create
repo: sample-app
entry: { type: api, method: POST, path: /orders }
writes: [{ table: orders, operation: insert }]
events: [order.created]
calls: [PaymentClient]
risks: [partial_failure]
confidence: { level: high, kind: fact, evidence_type: direct_code }
sources: [{ file: src/routes/orders.ts, line: 12 }]
Evidence 规则：fact → sources[]；inference → derived_from[]；unknown → reason。
用户入口
@dapei analyze behavior for sample-app — orient the repo, build candidates from code reading, then deep-dive the highest-risk entries
@dapei list behaviors for sample-app
常见错误
| 错误 | 后果 |
|---|---|
| 用 grep/regex 替代语义分析 | 丢失调用链上下文，无法理解行为 |
| "紧急情况先用 grep，回头补文档" | 文档永远不会补，历史记录丢失 |
| Phase 1-3 没做完直接跳 Phase 4 | 候选清单不完整，深析方向错误 |
| inference 直接当 fact 使用 | confidence 降级，证据链断裂 |
红线 — 禁止行为
- 禁止用 grep 作为主要分析手段
- 禁止在紧急情况下跳过 artifact 创建
- 禁止跳过 Phase 直接输出 Report
与其他 skill 的协作
- feature：
analyze-current-state阶段产出 behavior / state-machine artifact,作为后续gap-analysis与solution-design的事实基础 - repos：
cognitive.discover依赖repos.add已注册的目标 repo,directory_tree/manifest_files来自 repo 本地文件 - validation：当
validation.run发现未覆盖行为时,触发cognitive.artifact.upsert补全 behavior 文档 - workflow：
context.build在 L3 阶段注入 cognitive 索引摘要到runtime-context.md - workspace：
workspace.init创建docs/as-is/behavior与docs/as-is/state-machines目录,cognitive artifact 落盘位置
工具调用
- Phase 1-3 在多 repo 场景必须用 AI 客户端的 sub-agent（详见 Phase 1.5）。
- 全局约定见 Router SKILL.md
## Tool Delegation Protocol。 - dapei 不提供 todo capability —— 用 AI 客户端原生的 TodoWrite / todowrite / Todo 工具。