@aafe/agent-runtime

@aafe/agent-runtime 是面向前端工程的项目级 AI 架构运行时。它把 AI Coding 从「直接改代码」升级为一条可审计的链路：

需求接入/分支判定 → SDD + 架构规划 → 实施 → 批判审查 → 影响分析/自测 → 提交/PR → TAPD 回填（按需） → 知识更新

AAFE 默认只做编排、分析和上下文交付；启用 Cursor developer execution 或 aafe task 后，才会通过 Cursor SDK / Cloud Agent 执行代码变更。

核心能力：

• 项目级 Runtime 初始化、更新和诊断
• Skill、Pipeline、Hook、Gate 和 Memory 编排
• Vue / React / Next / Monorepo 等项目识别
• 默认启用的 SDD 规格规划、OpenSpec 兼容 artifact、revision 与 traceability
• DDD 领域建模与前端设计模式组合，两者均为显式开启
• Planner + Orchestrator 的 Agent Platform，产出给 IDE Agent 的最小上下文包
• Task Manager + Cursor Cloud 的隔离任务、并发调度和进程重启恢复
• Knowledge Center 知识关系、影响分析和测试预测
• Knowledge Web 本地可视化
• 任务完成后自动更新 Knowledge、Runtime 和 Doctor

目录

• 快速开始
• 从 0.1.x 升级到 0.2.0
• CLI 命令
• 项目初始化
• Workspace Root 与编辑器分层配置
• 项目更新与诊断
• Memory
• DDD（显式开启）
• 前端设计模式（显式开启）
• SDD 与 Feature Pipeline
• Agent Platform
• 任务主流程（Task Spine）
• 隔离任务与 Cursor Cloud
• E2E
• Agent Setup（Cursor Agent 模式）
• Cloud Task Manager + 企微 Bot
• Agent 作用与配置指南
• Agent 内自主命中
• Knowledge Center
• Knowledge Web
• 任务完成自动同步
• 架构文档接入
• AI Runtime 执行
• 项目目录结构
• Agent Skills 分发
• 开发与验证
• 设计边界

快速开始

在目标前端项目根目录执行：

默认 npm 安装仅提供 AAFE CLI / Runtime，发布包不包含 ai-bots/wecom，也不安装企微 Bot SDK。init、update、doctor 等普通命令不加载 WeCom；默认 update 不安装、启动或更新 Bot。Bot 统一使用 aafe bot start --wecom 显式启动，后续其他 Bot 通过独立适配器扩展。企微 Bot 需在 AAFE 源码的 ai-bots/wecom 目录另行安装依赖；默认 npm 安装包执行启动命令会提示未安装，不自动下载 Bot。旧命令 aafe wecom 保留兼容。

npm install --save-dev @aafe/agent-runtime
npx aafe init --yes \
  --framework=vue \
  --scenarios=complex,admin,dashboard,workflow,graph \
  --template=complex \
  --editors=cursor
npx aafe doctor
npx aafe knowledge update
npx aafe knowledge-web --serve --port=4173   # 浏览器打开 http://127.0.0.1:4173/

常用项目类型与场景：

--framework=vue|react|next|monorepo|generic
--scenarios=complex,ddd,patterns,graph,admin,dashboard,workflow

SDD 默认启用并融合进 feature pipeline；DDD 与设计模式知识包始终会安装，但默认不激活——是否启用由每次请求的门禁判定，见 SDD 与 Feature Pipeline、DDD（显式开启） 与 前端设计模式（显式开启）。

从 0.1.x 升级到 0.2.0

线上已发布的最新版本是 0.1.22，0.2.0 是一次包含破坏性变更的升级。升级 npm 包之后必须执行 aafe update：.ai-agent/ 下的 Pipeline 和 Gate 是随包生成、留在项目里的文件，光升级包不会刷新它们。

一条命令完成迁移

npm install --save-dev @aafe/agent-runtime@latest
npx aafe update --yes
npx aafe doctor

子目录（Monorepo）安装：

cd bklog/web
npm install --save-dev @aafe/agent-runtime@latest
npx aafe update --yes --module-name=web --migrate-editors
npx aafe doctor

先看会改什么：

npx aafe update --dry-run

aafe update 会刷新生成物，并保留项目自有知识：.ai-agent/project.md、.ai-agent/project-skills/**、.ai-agent/rules/**、.aafe-memory/**（由 memory.path 指定）。

破坏性变更清单

| 变更 | 影响 | 迁移动作 | | --------------------------------------------- | ---------------------- | -------------------------------------------- | | aafe run 语义变更为 Planner + Orchestrator 全循环 | 依赖旧行为的脚本 | 改用 aafe pipeline，过渡期可用 aafe run --legacy | | 包内目录调整 | 深链导入的代码 | 见「包内目录调整」 | | DDD 改为显式开启 | 通用需求不再自动做领域建模 | aafe update，无需改代码 | | 设计模式改为显式开启 | feature 管线不再无条件跑模式步骤 | aafe update，无需改代码 | | architecture_gate 不再要求 pattern_selection | 自定义 gates.yaml | 见「自定义 Pipeline / Gate」 | | analyzeDDD 变为 async | 直接调用 API 的代码 | 加 await | | analyzePatternFit 不再返回 recommendation | 直接调用 API 的代码 | 改读 composition.patterns | | .aafe.config.json 的 analyze.llm.agents 废弃 | Agent 接线配置 | 迁到 .aafe.agents.json |

包内目录调整

src/analyze/   →  src/static-analysis/
src/runtime/   →  src/agent-platform/skill-runtime/

直接深链到这些路径的代码需要改导入。从包名根导入不受影响：

import { AgentRuntime, analyzePatternComposition } from '@aafe/agent-runtime';

DDD 与设计模式改为显式开启

0.1.x 的 feature 管线里，DDD 与模式步骤是无条件执行的，AgentRuntime.classify 也会因为请求里出现「领域」「策略」这类词就切到对应管线。结果是一个「加个订单列表页」的普通需求，也会被要求先产出限界上下文和模式选型。

0.2.0 起两者都由门禁把关，只有请求中明确表达了相应意图才会激活：

$ aafe ddd gate "加个订单列表页"
{ "enabled": false, "decision": "disabled",
  "reason": "no explicit DDD intent in the request", "scope": "none" }

$ aafe ddd gate "用 DDD 重构订单模块"
{ "enabled": true, "decision": "enabled",
  "reason": "explicit DDD intent: ddd", "scope": "partial",
  "requestedCapabilities": ["refactoring"] }

判定为 ambiguous 时会先反问，不会静默启用。代码库里本来就存在的 DDD 术语或 adapter、strategy 之类的类名，都不构成启用理由。

aafe update 会同时做三件事：

1. 重写 feature.yaml，移除无条件的 DDD 与模式步骤；
2. 写入新的 domain-feature.yaml（Gate → Scope → Discovery → Strategic → Tactical → Architecture → Validation）和 pattern-feature.yaml（Gate → Discovery → Selection → Composition → Audit → Validation）；
3. 生成 .ai-agent/ddd/（39 个文件）与 .ai-agent/frontend-engineering/（61 个文件）两棵知识树，并写入 aafe-ddd-gate.mdc、aafe-pattern-gate.mdc 两条编辑器指针规则。

自动迁移历史文件与配置

.ai-agent/、.aafe.config.json 和 .aafe.agents.json 都在你的仓库里，升级 npm 包搬不动它们；只重新生成也不够，因为新版本只会写自己知道的路径，不会去动一个它已经不认识的旧文件。所以 aafe init / aafe update / aafe sync 都会在写完新布局之后自动跑一遍迁移。

也可以单独执行：

npx aafe migrate --dry-run    # 只看会改什么
npx aafe migrate

当前包含四项：

| 迁移 | 从 | 到 | | ---------------------------- | --------------------------------------------- | ---------------------------------------- | | superseded-flat-ddd-skills | .ai-agent/skills/ 下 5 个扁平 DDD 技能文件 | 已由 .ai-agent/ddd/skills/ 取代，删除 | | file-license-memory-jsonl | .ai-agent/memory/file-license-ok.json | .ai-agent/memory/file-license-ok.jsonl | | analyze-output-key | .aafe.config.json → analyze.docsOut + 旧产物目录 | analyze.output + 现产物目录 | | analyze-llm-agents | .aafe.config.json → analyze.llm.agents | .aafe.agents.json |

几点值得说明：

• 扁平 DDD 技能文件必须清掉。 留着不只是多余——Skill Index 路由仍会读到它们，一个残留的 ddd-discovery.md 足以让 Agent 对一个从没要求过领域建模的需求做起限界上下文分析，正好绕开新门禁。这些文件每次 update 本来就会被整体覆盖，删除不会丢掉任何你该保留的东西。
• license 记忆是真实数据，做的是格式转换而非删除。 旧的单体 .json 会被逐条转成追加式 .jsonl，只搬运 ok: true 的记录，并保留旧文件自己的 fingerprint——如果 License 模板后来变过，这些记录就应该继续判定为不匹配。重新校验一个文件很便宜，错误地信任一个过期的头部不便宜。
• analyze 产物目录会合并，而不是二选一。 analyze.docsOut 和 analyze.output 同时存在时，配置值只能取其一：读取优先级本来就是 output ?? docsOut，而配置模板一直无条件写入 output，所以任何生成过的项目里 docsOut 其实从未生效——改用它会把分析悄悄指向一个项目可能从没用过的目录。磁盘上的产物则不同：当旧目录有产物、而 output 指向的目录还不存在时，产物会一并迁过去，让配置和磁盘重新对上；两个目录都有产物时不合并，因为那会把一次更旧的分析混进当前产物里且无从分辨新旧——分析产物随时可以用 aafe analyze 重建，此时只报告旧目录位置，由你确认后删除。指向项目外的旧路径只报告、不搬运。
• 迁移按「磁盘现状」判断，不看版本号。 跳过了好几个版本的项目、已经手工迁移过的项目、和完全最新的项目，跑完结果一致；重复执行是 no-op，中途失败也不需要回滚。
• 前置条件不满足时会推迟而不是硬来。 例如 .ai-agent/ddd/ 尚未安装时不会删旧技能文件，.aafe.agents.json 尚未生成时不会去写它——否则会写出一个残缺的 agents 配置，让项目永久失去 planner 和内置 Agent。这类情况下旧内容原地保留，下次再迁移。

自定义 Pipeline / Gate

如果改过 .ai-agent/pipelines/*.yaml 或 .ai-agent/runtime/gates.yaml，aafe update 会用新版本覆盖它们。请先备份，再把自定义步骤挪到新结构上。三处语义变化需要注意：

• architecture_gate 的 requires 去掉了 pattern_selection。架构合理与否，和有没有用设计模式是两件事。
• pattern_gate 的 requires 改为 pattern_problems / pattern_composition / pattern_anti_patterns。
• 新增 ddd_enablement_gate 与 pattern_enablement_gate。
• feature pipeline 默认融合 sdd-gate / explore / proposal / specs / design / tasks / approval，并在实施前经过 sdd_gate；sdd.enabled: false 时这些步骤发布空兼容 artifact 后跳过。

未执行 aafe update 时不会崩：模式技能在被门禁跳过时，仍会发布 pattern_interview、pattern_selection、module_pattern_selection 等旧 artifact 键（值为空），所以留在磁盘上的旧 pattern_gate 不会把管线卡死。但这只是兼容垫片，行为已经是新的——请尽快执行 update。

升级后验证

npx aafe doctor          # 期望 status: pass，missing 与 warnings 均为空
npx aafe migrate         # 期望 migrated: 0，即已无遗留内容
npx aafe ddd gate "加个列表页"        # 期望 disabled
npx aafe pattern gate "加个列表页"    # 期望 disabled

doctor 会校验 DDD/模式/SDD 知识入口、feature.yaml 的 SDD 融合及 DDD/模式 opt-in 约束、各 Gate 配置和 Cursor 指针；启用 Cloud Task readiness 时还会检查这些文件是否可被 Git clone 获取。

回滚

.ai-agent/ 全部纳入版本库时，回滚即：

npm install --save-dev @aafe/[email protected]
git checkout -- .ai-agent .aafe.config.json

CLI 命令

| 命令 | 用途 | | ----------------------- | ----------------------------------------------------------------------------------------- | | aafe init | 初始化项目 Runtime、Memory 和编辑器入口 | | aafe detect | 识别项目框架、编辑器和场景 | | aafe doctor | 检查 Runtime 文件和配置完整性 | | aafe sync | 同步生成的 Runtime 文件 | | aafe update | 更新已接入项目的 Runtime、Skills、Hooks 和 Knowledge | | aafe migrate | 把旧版本遗留的文件和配置迁移到当前位置；--dry-run 预览 | | aafe analyze | 生成项目架构定位 Skill、AST 分析产物和检索索引 | | aafe knowledge init | 初始化 Knowledge 关系视图 | | aafe knowledge update | 更新 .docs 下的 Knowledge 视图 | | aafe knowledge sync | knowledge update 的别名 | | aafe knowledge search | 在 analyze 产物里做排序检索（模块/文件/路由/组件/特性/符号） | | aafe knowledge index | 重建并落盘检索索引 | | aafe knowledge-web | 生成 Knowledge Web 可视化页面；加 --serve 启动本地服务 | | aafe task-completion | 执行任务完成后的自动同步链路 | | aafe memory | 管理项目 Memory（读写 memory.path，默认 .aafe-memory/） | | aafe e2e | 启用/关闭 Playwright E2E、安装依赖、采集登录态（产物只写配置里的目录） | | aafe ddd | DDD 门禁、范围、发现与领域模型分析 | | aafe pattern | 设计模式门禁、问题识别、选型与组合 | | aafe context | 为 IDE Agent 生成最小可追溯上下文包 | | aafe impact | 预测需求或 git diff 的影响范围 | | aafe plan | 查看 Planner 的决策轨迹 | | aafe run | 运行 Planner + Orchestrator 全循环 | | aafe pipeline | 运行旧的 Skill Pipeline（0.1.x 的 aafe run 行为） | | aafe task | 创建、查询、继续、取消和恢复隔离的持久化 Cursor Cloud Task | | aafe sdd | 管理 Task 绑定的 OpenSpec artifact、revision、审批、验证、同步和归档 | | aafe repo pr | 使用仓库 Token 创建或复用 GitHub PR | | aafe test | 规划并生成 YAML Case；--coverage 全量、--diff 任务变更、--pr=<url> PR 差异；--run 才用 Playwright 执行 | | aafe diagnose | 把失败报告定位成根因与修复方向 | | aafe license | 校验并补齐文件 License 头 | | aafe skills | 下载 GitHub Agent Skills，不用于项目初始化 |

查看帮助：

aafe --help

项目初始化

初始化 Runtime

aafe init --yes \
  --framework=vue \
  --scenarios=complex,ddd,patterns,graph \
  --template=complex \
  --editors=cursor,codebuddy,codex

常用编辑器：

--editors=cursor|codebuddy|claude|codex|trace|windsurf|vscode

子目录安装额外参数：

--module-name=web
--migrate-editors
--no-migrate-editors

Monorepo 子目录安装见 Workspace Root 与编辑器分层配置。

检查初始化结果

aafe detect
aafe doctor

doctor 期望结果：

{
  "status": "pass",
  "missing": [],
  "warnings": []
}

Workspace Root 与编辑器分层配置

当 AAFE 安装在 Git 仓库的子目录（例如 monorepo 中的 bklog/web）时，编辑器适配器必须写入 Workspace Root 才能生效；.ai-agent、.docs、.aafe.config.json 仍保留在安装目录，避免污染仓库根目录。

适用场景

仓库 Root（Workspace Root，Cursor / CodeBuddy / Claude 等在此读取编辑器配置）
└── bklog/web/          ← 安装目录（在此执行 aafe init / update）
    ├── .ai-agent/      ← Runtime 知识源，保留在此
    ├── .docs/          ← 模块文档，保留在此
    ├── .aafe.config.json
    └── package.json

aafe init / aafe update 会同时扫描 安装目录 与 Workspace Root，输出分析结果，并按当前 --editors 智能适配。

迁移策略

| 资源 | 位置 | 说明 | | ------------------------------------- | -------------- | ----------------------------------- | | .cursor / .codebuddy / .codex 等 | Workspace Root | 仅编辑器适配器迁移/合并到 Root | | .ai-agent | 安装目录 | Runtime、Skills、Pipelines | | .aafe-memory | 安装目录 | 项目 Memory（memory.path，update 不覆盖） | | .docs | 安装目录 | 架构文档与 Knowledge 视图 | | .aafe.config.json | 安装目录 | 项目配置，含 workspace 元数据 |

迁移时，编辑器文件内的路径引用会自动重写为安装目录实际路径，例如：

.ai-agent/skill-index.md  →  bklog/web/.ai-agent/skill-index.md
.docs/guide.md            →  bklog/web/.docs/guide.md
.cursor/hooks/...         →  .cursor/hooks/web/...

若安装目录已存在编辑器配置，CLI 会提示是否迁移到 Workspace Root（交互模式默认确认；--yes 时自动迁移）。

支持的编辑器与分层结构

| 编辑器 | 安装目录标记 | Workspace Root 分层结构 | | --------- | ---------------- | ------------------------------------------------ | | Cursor | .cursor/ | .cursor/{rules,skills,hooks,context}/{module}/ | | CodeBuddy | .codebuddy/ | .codebuddy/{module}/ + skills/ | | Claude | CLAUDE.md | 合并到 Root 的 CLAUDE.md（按模块块） | | Codex | .codex/ | .codex/{module}/aafe.md | | Trace | .trace/ | .trace/{module}/aafe.md | | Windsurf | .windsurfrules | 合并到 Root 文件（按模块块） | | VS Code | .vscode/ | .vscode/{module}/aafe.instructions.md |

只对 --editors 中启用的编辑器生成分层配置。

子目录安装示例

在模块目录下初始化（需以 仓库 Root 作为 IDE Workspace 打开）：

cd bklog/web
npm install --save-dev @aafe/agent-runtime

# 交互式：分析双目录、提示模块名、确认迁移
npx aafe init --editors=cursor,codebuddy

# 非交互式
npx aafe init --yes \
  --framework=vue \
  --scenarios=complex,ddd,patterns \
  --editors=cursor,codebuddy,codex \
  --module-name=web \
  --migrate-editors

相关 CLI 参数

| 参数 | 说明 | | ---------------------- | ---------------------------------- | | --module-name=<name> | 分层配置的模块名，默认取安装目录名（如 web） | | --migrate-editors | 将安装目录下的编辑器适配器迁移/合并到 Workspace Root | | --migrate-cursor | --migrate-editors 的别名 | | --no-migrate-editors | 跳过编辑器适配器迁移 | | --no-migrate-cursor | --no-migrate-editors 的别名 |

.aafe.config.json 中的 workspace 配置

子目录安装且启用分层后，安装目录下的 .aafe.config.json 会写入类似配置：

{
  "workspace": {
    "layeredEditors": true,
    "installRoot": ".",
    "workspaceRoot": "../..",
    "moduleName": "web",
    "moduleRelativePath": "bklog/web",
    "retainInInstallDir": [".ai-agent", ".docs", ".aafe.config.json"],
    "editorOnlyAtWorkspaceRoot": true,
    "agentPrefix": "bklog/web/.ai-agent",
    "docsPrefix": "bklog/web/.docs",
    "editorLayers": {
      "cursor": ".cursor/{rules,skills,hooks,context}/web",
      "codebuddy": ".codebuddy/web",
      "codex": ".codex/web"
    }
  }
}

aafe doctor 会校验 Workspace Root 下的分层编辑器文件，并警告安装目录仍残留 .cursor / .codebuddy 或 Root 下误放的 .ai-agent / .docs。

项目更新与诊断

升级 npm 包后执行：

npm install
npx --yes @aafe/agent-runtime@latest update
npx --yes @aafe/agent-runtime@latest doctor

aafe update 默认会：

• 刷新 .ai-agent Runtime、Skills、Pipelines 和 Gates；
• 刷新编辑器入口和 Hooks（含 Workspace Root 分层编辑器配置）；
• 迁移旧版本遗留的文件和配置（见 自动迁移历史文件与配置），结果在输出的 migration 字段；
• 保留 .ai-agent/project.md、.ai-agent/project-skills/**、.ai-agent/rules/** 和 memory.path 指向的 Memory 目录（默认 .aafe-memory/**）；
• TTY 下询问是否强制执行 aafe analyze（默认 Yes）；强制时覆盖 analyze 产物并迁移旧布局，保留 .aafe/e2e/ 与 .aafe/runs/；
• 自动刷新 Knowledge 关系视图；
• 执行 doctor 校验。

常用参数：

aafe update --dry-run              # 预览
aafe update --upgrade-package      # 只升级全局 npm 包
aafe update --no-knowledge         # 关闭本次 Knowledge 自动更新
aafe update --analyze              # 强制 analyze（默认；TTY 会询问）
aafe update --no-analyze           # 本次不跑 analyze
aafe update --yes --module-name=web --migrate-editors   # 子目录安装迁移编辑器配置

Memory

项目记忆已从 .ai-agent/memory/ 迁出。aafe init / aafe update 之后，必须先指定 Memory 目录，所有读写都走这个目录，不要再往 .ai-agent/memory/ 写学习记录。

目录由 .aafe.config.json → memory.path 指定，相对安装目录（子目录安装时是模块目录，不是仓库 Root）。默认 .aafe-memory/。aafe update 不会覆盖该目录。

{
  "memory": {
    "enabled": true,
    "path": ".aafe-memory",
    "remote": {
      "enabled": false,
      "url": null,
      "projectId": null,
      "tokenEnv": "AAFE_MEMORY_TOKEN",
      "timeoutMs": 15000
    }
  }
}

| 路径 | 用途 | | --------------------------------------------------------------------------------------------------- | -------- | | .aafe-memory/index.md | 目录入口 | | .aafe-memory/learnings.jsonl | 追加式结构化记忆 | | .aafe-memory/summary.md | 压缩摘要 | | .aafe-memory/{project-design,components,conventions,decisions,experience,project-architecture}.md | 分类主题 | | .aafe-memory/knowledge-sync.jsonl | 任务完成同步日志 |

aafe memory init
aafe memory add "列表筛选默认记住上次条件" --type=experience --tags=list,filter
aafe memory search "筛选"
aafe memory context "日志检索"
aafe memory summary
aafe memory compact
aafe memory scan --target=src
aafe memory remote-status
aafe memory sync --push

远程同步需要先打开 memory.remote.enabled 并注册 MCP adapter；未配置时 sync / upload 会失败。License 校验缓存仍在 .ai-agent/memory/file-license-ok.jsonl，那是 Runtime 内部文件，不是项目 Memory。

前端 OOM / 泄漏诊断是另一套 opt-in 能力（.ai-agent/frontend-memory/），与这里的项目记忆目录无关。

DDD（显式开启）

DDD 是 opt-in 的。在用户明确表达 DDD 意图之前，Agent 不会读取 .ai-agent/ddd/ 下的任何文件，也不做限界上下文、聚合和领域事件分析。代码库里恰好存在的 DDD 术语不构成启用理由。

门禁与范围

aafe ddd gate "用 DDD 重构订单模块"     # enabled | disabled | ambiguous
aafe ddd scope "用 DDD 重构订单模块"     # 命中的最小技能集与规则加载顺序

判定为 ambiguous 时先问用户，不静默启用。

发现与建模

aafe ddd ask "使用 DDD 实现多租户权限模块"
aafe ddd analyze "使用 DDD 实现多租户权限模块，支持角色、组织、权限策略和审计事件"

analyze 是证据驱动的：它读取 aafe analyze 的产物，把每个概念标注为 observed（项目里确有此物，附来源）或 inferred（从需求文本推断），各自带置信度和依据。没有证据的推断不会被伪装成事实。

aafe ddd analyze "..." --no-evidence   # 只从请求推断，不读项目知识
aafe ddd analyze "..." --force         # 门禁判定未启用时仍强制执行

输出包含：

ubiquitousLanguage  boundedContexts  aggregates  entities  valueObjects
domainEvents        repositories     domainServices        questions

管线

domain-feature 管线按 DDD 链路执行：

Gate → Scope → Discovery → Strategic → Tactical → Architecture → Validation

其中还包含 ddd-pattern-bridge：把聚合、领域事件等构造块映射到前端模式角色（Aggregate → State Machine / Command / Repository），但不因此激活整条模式链路。

前端设计模式（显式开启）

设计模式同样是 opt-in。最高优先级的两条原则：

• PATTERN-SYSTEM-001：一个项目不是「选一个设计模式」，而是针对具体问题选出最小充分的模式组合；
• PATTERN-SYSTEM-002：不用设计模式不是缺陷。

内置 16 个模式域、304 个模式、155 条规则，其中 82 个模式带完整评分元数据。

门禁

aafe pattern gate "用策略模式重构布局算法"

裸出现 strategy、factory、adapter 这类词不会触发；必须是明确的模式诉求。

问题识别与组合

先识别问题，再谈模式：

aafe pattern discover "..."    # 只输出问题与变化点，不给任何模式
aafe pattern select "..."      # 识别问题 → 评分候选 → 组合
aafe pattern modules "..."     # 按模块分别给出组合
aafe pattern audit "..."       # 反模式审计（不受门禁限制）
aafe pattern ask "..."         # 选型前需要澄清的问题
aafe pattern catalog --scorable

select 的实际输出（--summary）：

{
  "status": "pass",
  "problems": ["同一能力存在多种可替换实现，需要运行时选择或后续扩展", "用户操作需要撤销与重做"],
  "complexity": "high",
  "patterns": [
    { "pattern": "Strategy", "responsibility": "承担「algorithm-variation」…", "score": 8 },
    { "pattern": "Command",  "responsibility": "承担「user-operation」…",      "score": 5 }
  ],
  "flows": ["Strategy", "Undo/Redo → Command"],
  "conflicts": [],
  "redundant": ["chain-of-responsibility"],
  "rationale": ["识别到 2 个问题、1 个变化点，问题复杂度评级 2/3。", "剔除 1 个冗余模式（Rule 011：优先最小充分组合）。"]
}

每个入选模式都必须对应一个明确职责；冲突与冗余会被显式剔除并说明理由。

评分与过度设计

评分同时计算收益（ProblemFit、ChangeIsolation、ComplexityReduction、ReusePotential、PerformanceBenefit）与成本（Implementation、Cognitive、Coupling、Overengineering）。收益是上下文相关的：一个模式在它的 justifiedAt 复杂度阈值之下被使用，会被记为过度设计风险并直接扣分，从而落选。

管线

Gate → Discovery → Selection → Composition → Anti-Pattern Audit → Validation

aafe pattern audit 会区分 observed（项目现状里已存在的反模式）与 predicted（当前组合方案会引入的反模式），共 25 类。

SDD 与 Feature Pipeline

SDD 默认启用，并且是现有通用 feature pipeline 的规格规划层，不是与 feature 并列的任务类型。DDD 和设计模式仍是显式启用的分析维度。IDE Task Spine 可同时加载 SDD 与按需知识包；但当前声明式 domain-feature、pattern-feature、graph-feature pipeline 尚未复用这段 SDD steps，只有通用 feature.yaml 已完成融合。

{
  "sdd": {
    "enabled": true,
    "root": "openspec",
    "schema": "spec-driven",
    "approvalRequired": true
  }
}

项目可用 sdd.enabled: false 显式退出普通 feature 的 SDD 规划；明确执行 aafe sdd 命令仍会进入 SDD 引擎。

Feature Pipeline 中的融合位置

flowchart LR
  SG["sdd-gate"] --> MR["memory-recaller"]
  MR --> SE["sdd-explore"]
  SE --> AR["architect"]
  AR --> MD["module-decomposer"]
  MD --> EP["evolution-predictor"]
  EP --> AG{"architecture_gate"}
  AG --> SP["sdd-proposal"]
  SP --> SS["sdd-specs"]
  SS --> SD["sdd-design"]
  SD --> ST["sdd-tasks"]
  ST --> SA["sdd-approval policy"]
  SA --> SGATE{"sdd_gate"}
  SGATE --> ADR["adr-generator"]
  ADR --> IG{"implementation_gate"}
  IG --> RC["refactor-critic"]
  RC --> ER["experience-recorder"]
  ER --> MW["memory-writer"]
  MW --> MG{"merge_gate"}

这里的 sdd-approval 只把审批策略和待审批状态附着到 pipeline 结果，不代表人工审批已经完成。可执行的持久化审批由 SDDEngine 校验当前 revision 后完成；Task Manager 只接受“当前 revision 已验证且已审批”的 SDD 绑定任务。

Artifact 依赖、修订与归档

flowchart LR
  P["proposal.md"] --> S["specs/<capability>/spec.md"]
  P --> D["design.md"]
  S --> T["tasks.md"]
  D --> T
  T --> V["validate"]
  V --> A["approve current revision"]
  A --> I["implement / verify"]
  I --> SY["sync delta specs"]
  SY --> AC["archive change"]
  R["任一 artifact 修订"] -. "revision + 1；验证与审批失效" .-> V

共享 artifact 位于 openspec/changes/<changeId>/ 和 openspec/specs/；Task 私有状态位于 .aafe/tasks/<taskId>/sdd/，包含 change.json、revision 快照、traceability 和 verification evidence。一个 Task 最多绑定一个 active change，一个 change 只属于一个 Task。

stateDiagram-v2
  [*] --> draft
  draft --> waiting_approval: validate 有效且要求审批
  draft --> ready: validate 有效且免审批
  draft --> failed
  draft --> cancelled
  waiting_approval --> draft: artifact 修订
  waiting_approval --> ready: approve 当前 revision
  waiting_approval --> failed
  waiting_approval --> cancelled
  ready --> draft: artifact 修订
  ready --> implementing: apply-context
  ready --> synced: sync
  ready --> failed
  ready --> cancelled
  implementing --> draft: artifact 修订
  implementing --> verifying: recordVerification
  implementing --> synced: sync
  implementing --> failed
  implementing --> cancelled
  verifying --> draft: artifact 修订
  verifying --> implementing: 继续实现
  verifying --> verified: passed
  verifying --> synced: sync
  verifying --> failed: failed
  verifying --> cancelled
  verified --> draft: artifact 修订
  verified --> implementing: 继续实现
  verified --> synced: sync
  verified --> failed
  verified --> cancelled
  synced --> draft: artifact 修订
  synced --> implementing: 继续实现
  synced --> archived: archive
  synced --> failed
  synced --> cancelled
  failed --> draft: 修订并重试
  failed --> cancelled
  archived --> [*]
  cancelled --> [*]

常用持久化流程：

aafe task create --requirement="增加用户搜索" --repository=<repo-url> --no-run
aafe sdd create --task-id=<taskId>
aafe sdd propose <taskId> --file=proposal.md
aafe sdd spec <taskId> --capability=user-search --file=spec.md
aafe sdd design <taskId> --file=design.md
aafe sdd tasks <taskId> --file=tasks.md
aafe sdd validate <taskId>
aafe sdd approve <taskId>
aafe task continue <taskId> "按已审批 SDD 执行"
aafe sdd verify <taskId> --file=verification.json
aafe sdd sync <taskId> --dry-run
aafe sdd sync <taskId> --yes
aafe sdd archive <taskId> --yes

Agent Platform

从 0.2.0 起，静态分析之上多了一层 Agent Platform：Planner 决定「该做什么」，Orchestrator 负责「怎么可靠地做完」，专业 Agent 各自解决一类问题，最终由 Context Agent 产出交给 IDE Agent 的最小上下文包。

CLI → Planner → Orchestrator → AgentProvider → Agent → Knowledge → Context Package → IDE Agent

flowchart LR
  CLI["context / impact / plan / run / test / diagnose"] --> TASK["标准化 Task"]
  TASK --> STALE{"Knowledge 是否缺失或陈旧"}
  STALE -->|是| ANALYZE["project-analysis"]
  STALE -->|否| PLAN["Planner.decide"]
  ANALYZE --> PLAN
  PLAN --> ACTION{"invoke / parallel / complete<br/>fail / need_user_input / replan"}
  ACTION -->|invoke / parallel| GRAPH["ExecutionGraph 依赖就绪波次"]
  GRAPH --> POLICY["并发、超时、重试、网络与预算策略"]
  POLICY --> REGISTRY["Capability → AgentRegistry"]
  REGISTRY --> RUNTIME["AgentRuntime<br/>输入校验 → Provider → 修复 → 输出/evidence 校验"]
  RUNTIME --> STATE["ExecutionState + nodes input/output"]
  STATE --> PLAN
  ACTION -->|complete| PACKAGE["Context Package + run.json"]
  PACKAGE --> OVERLAY{"是否启用 Cursor developer execution"}
  OVERLAY -->|否| IDE["IDE handoff / 仅返回上下文"]
  OVERLAY -->|是| CURSOR["Cursor SDK implementation"]

默认 RulePlanner 按 Task kind 选择 capability：requirement/generic 走影响分析、知识校验和上下文打包；diff 走变更影响；failure 先定位失败；analysis 可并行执行架构、依赖、数据流、feature 与业务流；test 根据 requirement、diff、coverage 或 PR 规划、生成并按显式权限执行 E2E。

命令

# 给 IDE Agent 的上下文包（默认纯文本，便于直接粘进对话）
aafe context --requirement="增加用户手机号搜索"
aafe context --diff --format=md --out=.aafe/context.md

# 影响面分析：需求驱动或 diff 驱动
aafe impact --requirement="增加用户手机号搜索"
aafe impact --diff=main...HEAD

# 只看 Planner 打算怎么做，不真正调用 Agent
aafe plan --requirement="..." --dry-run

# Planner + Orchestrator 全循环，产物写入 <output>/runs/<runId>/
aafe run "增加用户手机号搜索"

# 规划测试 / 生成 YAML Case；加 --run 才真正用 Playwright 执行
aafe test --diff
aafe test --coverage
# 「分析此PR … 生成测试用例」走 aafe test --pr，不要安装 uitest / @aafe/ai-test
# 测试地址每次可能不同：缺地址时 Agent 询问用户，再 --run --base-url=<本次 URL>
aafe test --pr=https://github.com/acme/app/pull/12
aafe test --pr=https://github.com/acme/app/pull/12 --run --base-url=https://preview.example/app
aafe test --requirement="增加用户手机号搜索"

# E2E 启用、目录与登录态见「E2E」一节，不要把报告写到 playwright-report/

# 把一次失败的测试报告定位成根因
aafe diagnose --failure=<report.json|log.txt>

# 历史 run：列表与只读回放（含每步的 input / output 载荷）
aafe run --list
aafe run --replay=<runId>

加 --no-write 可以不落盘运行。aafe impact --format=md 输出可直接贴进 PR 或 TAPD 的影响分析报告。

任务主流程（Task Spine）

AAFE 的 Task Spine 是动态决策链，不是每个任务都固定执行四个阶段。每个节点都先根据任务来源、当前分支、代码变更、用户意图和工作流模式判断是否进入、跳过或询问。

ask 模式下，门禁不会自动推进：Agent 需要根据用户回复判断是否进入后续环节；用户拒绝或明确跳过时停止该分支。autonomous 模式下，LLM 根据上下文自主判定 proceed / skip / ask，只有缺少用户独有事实且会影响方案时才 Hard Ask。

默认开关：mode.workflow=ask、sdd.enabled=true、agent.enabled=false、agent.manager.enabled=false、e2e.enabled=true。因此默认会做 SDD 规划，但不会自动调用 Cursor SDK 或启动持久化 Cloud Task；这两类执行需显式启用或直接使用对应命令。Cursor Agent 模式的启用、API Key、模型列表和 aafe run --agent=cursor 见 Agent Setup。

flowchart TD
  START(["用户需求 / TAPD / PR / diff"]) --> SOURCE{"任务来源"}
  SOURCE -->|TAPD| TAPD["拉取详情与验收标准<br/>有 Figma 时取结构化设计和截图"]
  SOURCE -->|普通需求| SPEC["澄清目标、范围、验收、约束"]
  SOURCE -->|PR 或 diff| DIFF["读取变更并建立影响上下文"]

  TAPD --> BRANCH{"当前分支是否正确关联"}
  SPEC --> NEWTASK{"新任务或当前分支不匹配"}
  BRANCH -->|否| SWITCH["新建或切换关联分支"]
  BRANCH -->|是| HISTORY["检索历史与项目知识"]
  NEWTASK -->|是| SWITCH
  NEWTASK -->|否| HISTORY
  NEWTASK -->|无法判断| MODE{"workflow mode"}
  MODE -->|ask| HARDASK["询问用户"]
  MODE -->|autonomous 且高置信| HISTORY
  MODE -->|缺用户独有事实| HARDASK
  SWITCH --> HISTORY
  HARDASK --> HISTORY
  DIFF --> HISTORY

  HISTORY --> SIZE{"执行复杂度"}
  SIZE -->|纯问答或纯文档| ANSWER["回答或更新文档"]
  SIZE -->|小改| DIRECT["按项目约束直接实施"]
  SIZE -->|多方案或高风险| PLAN["Plan Gate"]
  SIZE -->|非平凡 feature| FEATURE["Feature Pipeline"]
  PLAN --> FEATURE

  FEATURE --> SDD["SDD Explore → Proposal → Specs/Design → Tasks"]
  SDD --> ARCH{"sdd_gate + architecture_gate"}
  ARCH -->|不通过| REVISE["补齐或修订 artifact/架构"]
  REVISE --> SDD
  ARCH -->|通过| IMPLEMENT["实施<br/>IDE Agent / 可选 Cursor Developer Agent"]
  DIRECT --> IMPLEMENT

  IMPLEMENT --> REVIEW["Critic / merge_gate"]
  REVIEW --> CHANGE{"是否有代码或运行时配置变更"}
  ANSWER --> CHANGE
  CHANGE -->|否| SUBMITDECIDE{"是否有提交意图"}
  CHANGE -->|是| IMPACT["aafe impact --diff"]
  IMPACT --> TESTPLAN["最小收敛自测 / aafe test --diff"]
  TESTPLAN --> UI{"是否需要 UI/E2E"}
  UI -->|否| SUBMITDECIDE
  UI -->|是且有本次 URL| E2E["Playwright E2E"]
  UI -->|缺 URL| URLASK["Hard Ask 获取 URL/URL 角色"]
  URLASK --> E2E
  E2E --> SUBMITDECIDE

  SUBMITDECIDE -->|否| DONE(["完成，不提交"])
  SUBMITDECIDE -->|是| COMMIT["Commit"]
  COMMIT --> PR["PR / MR"]
  PR --> LINK{"有关联 TAPD 且 tapd.enabled"}
  LINK -->|否| KNOWLEDGE["按需更新 Knowledge / Memory"]
  LINK -->|是| BACKFILL["回填结果、影响、自测和 PR/MR 链接<br/>状态最多推进到 doing"]
  BACKFILL --> KNOWLEDGE
  KNOWLEDGE --> DONE2(["完成"])

三个运行面及其衔接

当前实现提供三个相互协作但入口不同的运行面。它们共享 .ai-agent Rules/Skills 和 .aafe 持久化约定，但不能把其中一个入口的能力误认为另一个入口已经自动执行。

flowchart TB
  REQ["需求"] --> IDE["IDE Agent + Task Spine"]
  REQ --> PLATFORM["aafe run / context / impact / test"]
  REQ --> DURABLE["aafe sdd + aafe task"]

  subgraph PIPE["Feature Skill Pipeline"]
    IDE --> FP["router → feature.yaml"]
    FP --> FP_SDD["结构化 SDD 规划 + gates"]
  end

  subgraph AP["Planner + Orchestrator"]
    PLATFORM --> RP["RulePlanner / LlmPlanner"]
    RP --> ORCH["依赖图、并发、重试、预算、契约校验"]
    ORCH --> CAPS["专业 capability Agents"]
    CAPS --> CTX["Context Package"]
    CTX --> DEV{"agent.enabled / developer provider"}
    DEV -->|关闭| HANDOFF["交给当前 IDE Agent"]
    DEV -->|Cursor| CURSOR_ONE["Cursor SDK 单次实现"]
  end

  subgraph DT["Durable SDD + Cloud Tasks"]
    DURABLE --> TS["TaskStore"]
    TS --> SE["SDDEngine / OpenSpecAdapter"]
    SE --> READY["当前 revision validate + approve"]
    READY --> TM["TaskManager"]
    TM --> SCH["TaskScheduler"]
    SCH --> CLOUD["CursorTaskRuntime"]
  end

  FP_SDD -. "规划结果不会自动写 OpenSpec" .-> SE
  CTX -. "aafe run 不自动创建 durable Task" .-> TM
  CLOUD -. "Cloud clone 原生加载同一套 Rules/Skills" .-> FP

实际边界：

• aafe pipeline（或 aafe run --legacy）执行 .ai-agent/pipelines/*.yaml；默认 feature 已融合 SDD 规划。
• 明确 DDD、设计模式或 graph 请求会路由到各自专用 pipeline；当前这些专用 pipeline 仍未内嵌 SDD steps，这是现有实现边界。
• aafe run 执行 Planner + Orchestrator，先得到 Context Package；仅当 Agent 模式启用或 developer provider 为 Cursor 时再调用 Cursor SDK。
• aafe sdd 管理持久化 OpenSpec artifact、revision、审批、同步和归档；feature pipeline 的结构化结果不会自动落盘到 OpenSpec。
• aafe task 管理持久化 Cursor Cloud Task。Task 绑定 SDD 后必须通过当前 revision 的验证与审批；未绑定 SDD 的 Task 仍保持兼容，可直接调度。
• aafe task create 不会自动创建 SDD Change；aafe sdd apply-context 只返回上下文，TaskManager 当前不会自动把它注入 Cloud prompt。
• 当前没有“普通 aafe run 自动创建 SDD Change，再自动转为 durable Cloud Task”的隐式串联；由 IDE Agent 按 Task Spine 调用对应入口，或由上层代码组合公开 API。

[1] 需求与分支决策

任务开始后先确认来源与任务性质。若用户给的是 TAPD story / bug 链接或 ID，先通过 TAPD MCP 拉取详情，拿到标题、描述、验收标准、状态，并从 URL 最后一段数字提取末 9 位作为 tapd_short_id。若不是 TAPD 单，则按普通需求处理，但仍要澄清目标、范围、验收、约束和依赖。

TAPD 任务的分支判定：

| 当前分支 | 结果 | 下一步 | | --- | --- | --- | | feat|bug/<slug>/#<tapd_short_id> 且 ID 一致 | 已关联 | 进入需求分析 | | 有 #<digits> 但与当前 TAPD 不一致 | 关联错误 | 按规则新建或切换到正确分支 | | master / main / 无 #id | 未关联 | 按规则新建关联分支 | | 非 TAPD 任务 | 无需 TAPD 关联 | 跳过分支关联 |

TAPD 分支动作：

| submit.cli | 分支动作 | | --- | --- | | git | git fetch upstream master → git checkout -b feat|bug/<slug>/#<short_id> upstream/master | | gtm | gtm create issue → 关联已有 TAPD 单 → 目标分支 master → 按 TAPD 标题生成英文短名 |

非 TAPD 任务也要动态判断是否属于“新任务”。如果当前分支明显已经对应本任务，则继续使用；如果当前在 master / main，或当前分支主题与新任务无关，应新建或切换任务分支；如果无法从任务描述、分支名、历史上下文判断，ask 模式必须询问，autonomous 只有高置信时才自主判定。

分支决策闭合后，再查历史积累并做代码范围与根因分析。若预计影响超过小改范围（例如多文件/多函数或外部契约变化），进入 Plan Gate：ask 根据用户回复决定是否切到 Plan；autonomous 可按上下文直接切换，Hard Ask 只用于无法推断的产品选择。

[2] 任务执行决策

需求与分支决策闭合后才开始改代码。普通小改按项目既有模式实施；非平凡前端任务进入 .ai-agent/runtime/engine.md、runtime/router.yaml 和对应 pipelines/*.yaml；多方案或高风险改动进入 Plan Gate。DDD 与设计模式包是显式开启，用户没有明确表达时不自动加载。

执行中遵守最小改动原则：只改与需求、根因和影响范围相关的文件；新增源码文件加 License；已有 License 文件用 aafe license ensure <path> 校验。

[3] 影响范围 + 自测决策

任务完成前先判断是否有代码变更，再决定是否进入影响范围与自测：

| 任务类型 | 行为 | | --- | --- | | 纯问答 / 纯文档 / 需求分析-only | 跳过影响分析与自测 | | 代码或运行时配置变更 | 进入影响范围与自测门禁 |

ask 模式下，Agent 需要根据用户是否同意影响分析/自测来决定是否继续；用户明确跳过时记录跳过原因。autonomous 模式下，LLM 根据代码变更风险、影响面和提交意图自主判定是否 proceed。

代码变更流程：

aafe impact --diff --format=md
  → architecture-impact-test-forecast.md 生成影响范围与最小测试设计
  → minimal-convergent-self-test.md 执行最小收敛自测

自测分支：

| 影响类型 | 默认自测 | | --- | --- | | 纯函数 / 数据处理 / 缓存 / 排序 / 百分比 | 单元测试，Mock 输入输出 | | 组件 props / emit / store 契约 | 单元或组件层测试，Mock props/state/API | | 可见 UI / 路由 / 图表 / 交互 | aafe test --diff 生成 YAML；要执行时必须由用户提供本次 URL |

UI/E2E 的 URL 每次可能不同，缺 URL 时必须停下来问。禁止猜 http://localhost:8080，禁止把本次测试地址写死到 e2e.baseUrl。若 E2E 因无 Playwright blocked，且用户仍要看 UI，才允许浏览器 MCP 兜底；执行前必须先生成完整 ui_test_paths。

[4] 提交 / PR / MR / 回填决策

自测完成后不固定提交，而是进入提交意图判定。ask 模式下，用户同意 Commit/PR/MR 才执行；autonomous 模式下，LLM 根据当前 diff、分支、测试结果和工作流上下文判断是否提交。无 TAPD 关联时只做常规 Commit/PR/MR，不问 TAPD 回填；有 TAPD 关联时，在自测结束或用户触发提交后进入“是否回填 TAPD 单子”的门禁。

Commit / PR / MR 读取 .aafe.config.json：

{
  "submit": { "cli": "git" },
  "repo": {
    "githubAccessToken": "${GITHUB_TOKEN}",
    "gongfengAccessToken": "${GIT_PRIVATE_TOKEN}",
    "reviewers": ["alice", "bob"],
    "labels": ["frontend"]
  }
}

提交分支：

| submit.cli | Commit | PR/MR | | --- | --- | --- | | git | Git CLI stage + commit | repo-submit：优先 repo.githubAccessToken / GITHUB_TOKEN 调 GitHub API | | gtm | gtm commit | gtm pr，再用工蜂 Token 写入 reviewers / labels |

GitHub PR 流程：

有 repo.githubAccessToken / GITHUB_TOKEN
  → git 使用 http.extraheader 注入 Token push
  → aafe repo pr --title= --body= --base= --head=
  → GitHub REST API 创建或复用 PR
  → repo.reviewers 写 requested_reviewers
  → repo.labels 写 issue labels

无 Token 或 Token API 失败
  → 先提示降级原因
  → 降级 gh pr create
  → gh 未登录则如实报告，不阻断 TAPD 回填门禁

工蜂 MR 流程：

submit.cli=gtm
  → gtm commit
  → gtm pr
  → 若 repo.reviewers / repo.labels 非空：
      - labels 用逗号拼接写入 MR
      - reviewers：纯数字当 reviewer_ids；username 先查用户 id
      - 鉴权使用 repo.gongfengAccessToken / GIT_PRIVATE_TOKEN

TAPD 回填只在“任务有关联 TAPD 单且 tapd.enabled”时触发。回填内容只能通过 comments_create 追加评论，包含处理结果、影响范围、自测结果和 PR/MR 链接；如存在 PR 字段，可用 stories_update / bugs_update 只更新该字段。状态流转只允许逐步推进：backlog → todo → doing；不会自动提到 for_test。

知识检索

aafe analyze 会同时构建倒排索引（.aafe/knowledge/index/json/search.json），覆盖模块、文件、路由、组件、特性、业务流程和符号：

aafe knowledge search "用户手机号搜索"
aafe knowledge search "UserList" --kind=component,route --limit=10
aafe knowledge index --rebuild

路径与驼峰符号会归一到同一组词元，所以 userPhoneSearch、user-phone-search.js 和「用户手机号搜索」命中同一批结果。

内置 Agent 与 Capability

Planner 只认 capability，不认 Agent 名字，因此换实现不需要改 Planner。

| Agent | Capability | 状态 | | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | | code-intelligence | project-analysis / architecture-analysis / dependency-analysis / data-flow-analysis / feature-analysis / business-flow-analysis | 已实现 | | impact-analyzer | requirement-impact / change-impact / risk-analysis | 已实现 | | knowledge-validator | knowledge-validation / evidence-check | 已实现 | | context-agent | context-packaging / evidence-selection | 已实现 | | test-agent | test-planning / test-generation / e2e-execution | 已实现；YAML / 报告只写 e2e.casesDir / e2e.reportDir（见 E2E）；e2e-execution 需 allowTestExecution（或 aafe test --run） | | failure-analyzer | failure-analysis / root-cause-analysis / fix-analysis | 已实现 |

risk-analysis 与 evidence-check 两个 capability 已注册但尚无本地实现分支。

交给当前 IDE Agent（默认开启）

没有可用 Agent 的 capability 不会停在 no-agent-provides-capability——此时编辑器里正跑着一个完全有能力做这件事的 Agent。默认会包装成一次 handoff 交给它，已配置且启用的 Agent 永远优先，回退不顶掉真实接线。

{ "ideAgent": { "enabled": true, "mode": "current", "capabilities": [] } }

三级关闭窗口，范围越窄越优先：

AAFE_IDE_AGENT=0 aafe run "..."   # 单次命令 / CI，也接受 false / off / no
aafe run "..." --no-ide-agent      # 等价的 CLI 参数
# 项目级：.aafe.agents.json → "ideAgent": { "enabled": false }

CI 里建议关掉：没有交互式 IDE Agent 能接手，handoff 只会变成永远没人认领的 skipped，明确失败更有价值。要求结果完全可复现时同理。

ideAgent.capabilities 是白名单，列进去的 capability 总是走 IDE Agent，适合那些需要判断而非查表的分析。完整说明见 Agent 作用与配置指南。

Agent 契约与 Schema 校验

每个 Agent 都绑定一组契约：prompt + inputSchema + outputSchema，默认从 src/agents/<id>/ 装载，也可以在 .aafe.agents.json 里指向项目自己的文件或内联 schema。

Agent Platform 的 AgentRuntime 是所有 capability Agent 的唯一执行路径：

装载契约 → 校验入参 → 注入 prompt/schema → 调用 provider
        → 确定性纠错 → 校验输出 → 修复回路 → 校验 evidence

输出不合契约时先做本地确定性纠错（标量补成数组、字符串化 JSON 解开、数字/布尔强转），仍不合规才带着校验错误回问模型，最多 maxRepairAttempts 轮。

schemaMode 控制违约后果，默认按 provider 区分：

| 模式 | 行为 | 默认适用 | | --------- | --------------------------------- | ------------------------------------ | | enforce | 违约即 failed | http / cli / mcp / ide 等远程实现 | | warn | 保留结果但降级为 partial，绝不报成 success | local 内置 Agent | | off | 不校验 | 需要显式配置 |

指向不存在文件的 evidence 会被丢弃并计数——一条指不到任何地方的证据，比没有证据更糟。

.aafe.agents.json

Agent 接线独立成文件，避免把 .aafe.config.json 撑爆。aafe init / aafe update 只在缺失时生成，不覆盖已有配置；aafe doctor 会校验每个 capability 都能解析到启用的 Agent。

{
  "version": 1,
  "planner": { "provider": "rule", "maxSteps": 12,
    "llm": { "endpoint": null, "model": null, "apiKeyEnv": "AAFE_LLM_API_KEY", "temperature": 0 } },
  "agents": {
    "impact-analyzer": { "enabled": true, "provider": "local", "ref": "builtin:impact-analyzer" },
    "test-agent": { "enabled": true, "provider": "local", "ref": "builtin:test-agent" },
    "code-intelligence": {
      "provider": "http",
      "endpoint": "${AAFE_AGENT_ENDPOINT}",
      "model": "${AAFE_AGENT_MODEL}",
      "outputSchema": "./contracts/code-intelligence.output.json",
      "schemaMode": "enforce",
      "maxRepairAttempts": 2
    }
  },
  "ideAgent": { "enabled": true, "mode": "current", "capabilities": [] },
  "developer": { "provider": "ide", "mode": "current" },
  "policies": {
    "timeoutMs": 120000, "maxRetries": 1, "maxParallel": 4, "allowNetwork": false,
    "allowTestExecution": false, "tokenBudget": 12000, "maxTokens": null, "maxCost": null
  }
}

字段逐条说明、五种 provider 的配置示例和自定义 Agent 的写法见 Agent 作用与配置指南；协议层面的请求/响应结构见 AGENTS.SCHEMA.md。

Planner 默认是确定性的 RulePlanner，无需 API Key 即可离线运行。把 planner.provider 改成 "llm" 并填好 endpoint / model 即可启用 OpenAI 兼容的 LlmPlanner；它在网络异常、返回非 JSON 或请求了不存在的 capability 时会自动回退到 RulePlanner，所以开启 LLM 只会变慢，不会让流程中断。

provider 支持 local / http / cli / mcp / ide 五种传输方式。http 类型的 Agent 需要显式打开 policies.allowNetwork。endpoint / model / prompt / inputSchema / outputSchema 支持 ${ENV_VAR} 展开，密钥和内网地址不必进版本库；变量未设置时该字段置空并在 aafe doctor 报警，而不是把字面量 ${...} 当成地址去请求。

policies 里两种预算是不同的东西：tokenBudget 限制单个 Agent 的上下文包大小，maxTokens / maxCost 是整个 run 的花费上限，在步与步之间检查（调用中途中止并不会退还已花的 token）。cli 类型 Agent 的命令和 tools 会先过危险操作 denylist——rm -rf、git reset --hard、git push、sudo 之类在 spawn 前就被拒绝。

隔离任务与 Cursor Cloud

aafe task 是持久化、多任务的 Cursor Cloud 执行入口，与 aafe run 的一次性 developer Agent overlay 不同。每个 Task 拥有独立的 task.json、context.json、events.jsonl 和可选 sdd/，默认位于 .aafe/tasks/<taskId>/。

flowchart TD
  CREATE["task create"] --> STORE["TaskStore<br/>task/context/events"]
  STORE --> BOUND{"是否绑定 SDD"}
  BOUND -->|是| CHECK{"当前 revision<br/>validation.valid + approval"}
  CHECK -->|否| BLOCK_SDD["拒绝启动<br/>task-sdd-not-ready"]
  CHECK -->|是| READY["CloudProjectReadiness"]
  BOUND -->|否| READY
  READY -->|Rules/Skills 缺失、指针无效或未被 Git 跟踪| BLOCK["blocked"]
  READY -->|通过| QUEUED["queued"]
  QUEUED --> SCHED["TaskScheduler<br/>maxConcurrentTasks"]
  SCHED --> RUN["running"]
  RUN --> SDK["CursorTaskRuntime<br/>Agent.create/resume → send → stream → wait"]
  SDK --> RESULT{"Run 结果"}
  RESULT -->|成功且无 verify callback| COMPLETE["completed"]
  RESULT -->|成功且有 verify callback| VERIFY["verifying"]
  VERIFY -->|通过| COMPLETE
  VERIFY -->|失败| FAILED["failed"]
  RESULT -->|error / missing| FAILED
  RESULT -->|cancelled| CANCEL["cancelled"]
  RUN -->|进程重启| RECOVER["task recover<br/>Agent.getRun"]
  RECOVER --> SDK
  COMPLETE -->|continue| QUEUED
  FAILED -->|重试| QUEUED
  CANCEL -->|重试| QUEUED
  BLOCK -->|修复 readiness 后重试| QUEUED

Task 状态机：

stateDiagram-v2
  [*] --> created
  created --> queued
  created --> blocked
  created --> cancelled
  queued --> planning
  queued --> running
  queued --> blocked
  queued --> cancelled
  planning --> queued
  planning --> ready
  planning --> waiting
  planning --> failed
  planning --> cancelled
  planning --> blocked
  ready --> running
  ready --> queued
  ready --> cancelled
  ready --> blocked
  running --> waiting
  running --> verifying
  running --> completed
  running --> failed
  running --> cancelled
  running --> blocked
  waiting --> queued
  waiting --> running
  waiting --> cancelled
  waiting --> blocked
  verifying --> completed
  verifying --> failed
  verifying --> waiting
  verifying --> cancelled
  verifying --> blocked
  completed --> queued: continue/re-run
  completed --> blocked
  failed --> queued: retry
  failed --> blocked
  cancelled --> queued: retry
  cancelled --> blocked
  blocked --> queued: readiness restored
  blocked --> cancelled

并发与恢复规则：

• planning / ready / waiting 已定义为合法状态并纳入恢复扫描，但当前 TaskManager 没有主动写入这些状态的执行步骤；常规 CLI 主路径是 created → queued → running → completed/failed/cancelled。
• verifying 只在 API 调用方传入 options.verify 时进入，当前 aafe task CLI 尚未暴露该 callback。
• TaskScheduler 是进程内有界调度器，默认 maxConcurrentTasks: 4；持久化的是 Task 状态，不是内存队列。
• 并发上限只约束同一个 TaskManager 实例；多个独立 CLI 进程不共享内存 semaphore。task recover 会在单次进程内并发重排候选任务。
• recover() 扫描 queued / planning / ready / running。有 agentId + activeRunId 的 running Task 用 Agent.getRun 重连；其他候选重新入队。
• recoverOnStart 只在 API 调用 TaskManager.initialize() 时生效；当前 aafe task CLI 不会自动调用它，进程重启后需显式执行 aafe task recover。
• Cursor Cloud 启动前验证 .aafe.config.json、Skill Index、项目入口和 Cursor 指针均存在且被 Git 跟踪。SDD 启用时还要求 SDD Skill 与指针可被 Cloud clone 获取。
• agent.manager.enabled 目前控制初始化配置与 doctor 提示，但 aafe task 命令本身不以该值作为硬开关；显式调用仍会进入 TaskManager。
• 同一 Task 复用一个 Cursor Agent、可产生多个 Run；终态后关闭本地 session handle，持久化 Agent/Run ID 供恢复与审计。
• autoCreatePR 默认关闭；Task Manager 不替代 Task Spine 的 Commit、PR/MR 和 TAPD 回填判断。

E2E

Playwright E2E 与 Runtime 分开配置。aafe init / aafe update 之后，必须先指定用例和产物目录；执行、报告和登录态只认这些路径，不要散落到 test/ui/、playwright-report/、test-results/。

目录写在 .aafe.config.json → e2e，相对安装目录：

| 配置 | 默认 | 必须指定 | 用途 | | ------------------- | ------------------- | ---- | --------------------------------- | | e2e.casesDir | tests/ui-ai/cases | 是 | YAML 用例（源） | | e2e.reportDir | .aafe/e2e/reports | 是 | 统一报告 report.json / index.html | | e2e.specsDir | .aafe/e2e/specs | 是 | 由 YAML 编译出的 Playwright spec | | e2e.impactDir | .aafe/e2e/impact | 是 | 影响面 / inventory 中间产物 | | e2e.auth.stateDir | .aafe/e2e/auth | 是 | SSO / storageState |

{
  "e2e": {
    "enabled": true,
    "casesDir": "tests/ui-ai/cases",
    "reportDir": ".aafe/e2e/reports",
    "specsDir": ".aafe/e2e/specs",
    "impactDir": ".aafe/e2e/impact",
    "baseUrl": null,
    "baseUrlEnv": "AAFE_E2E_BASE_URL",
    "auth": {
      "mode": "reuse-or-headed",
      "stateDir": ".aafe/e2e/auth"
    }
  }
}

代码提交 / 拉取 / PR / MR 的 Token、Reviewers、Labels 写在根级 repo（代码仓库配置），不要再放进 e2e：

{
  "repo": {
    "githubAccessToken": "${GITHUB_TOKEN}",
    "gongfengAccessToken": "${GIT_PRIVATE_TOKEN}",
    "reviewers": ["alice", "bob"],
    "labels": ["frontend"]
  }
}

默认开启。关闭用 --no-e2e 或 aafe e2e disable。缺 Playwright 时再装：

aafe e2e enable
aafe e2e status
aafe e2e install --yes
aafe e2e auth --base-url='https://preview.example/app/#/list'

--run 必须带本次被测地址（--base-url=）。地址每次可能不同，不要写死 e2e.baseUrl，不要猜 http://localhost:8080。含 # 须加引号；有路径/查询参数时确认 A/B/C 并加 --url-role=target|origin|template。

aafe test --diff
aafe test --coverage
aafe test --pr=https://github.com/acme/app/pull/12
aafe test --pr=https://github.com/acme/app/pull/12 --run --base-url='https://preview.example/app/#/list' --url-role=template

报告只读 <e2e.reportDir>/<runId>/{report.json,index.html}。PR 令牌写在配置里（可用 ${ENV}），不要用 --token <值>。aafe update 强制 analyze 时会保留 .aafe/e2e/，不会清掉报告和登录态。

Knowledge Center

Knowledge Center 是基于项目代码、架构文档、Mermaid 图、Memory 和 Git 变更的 AI 项目知识管理能力。它不要求创建独立的深度文档站点，优先使用项目已有的 .docs 作为知识来源。

npx aafe knowledge init
npx aafe knowledge update
npx aafe knowledge sync            # update 的别名
aafe knowledge update --dry-run    # 预览

自定义架构文档目录：

aafe knowledge update \
  --architecture-docs=.docs \
  --knowledge-docs=.docs/aafe-generated

默认生成：

.docs/aafe-generated/
├── README.md
├── 组件关系.md
├── 业务关系与数据流.md
└── 影响范围与测试预测.md

这些是生成视图；原始 .docs 文档不会被覆盖。采集内容包括页面路由与模块、Vue/React 组件关系、Store/API/Worker/Storage、测试路径与变更关系、架构文档及 Mermaid 图、影响范围与测试预测，以及 Memory、版本、来源和审核状态。

Knowledge Web

knowledge-web 将当前项目的 Knowledge 数据生成一套本地只读可视化页面。

在 AAFE 安装目录（存在 .ai-agent 的目录，Monorepo 子模块则在对应子目录）执行：

npx aafe knowledge update                      # 建议先更新数据
npx aafe knowledge-web --serve --port=4173     # 生成并启动本地服务

浏览器访问 http://127.0.0.1:4173/。--serve 会占用当前终端，按 Ctrl+C 停止。

不加 --serve 时只生成静态 HTML，可直接打开 .docs/aafe-generated/knowledge-web/index.html。

常用参数

| 参数 | 说明 | | ---------------------------- | -------------------------------------------- | | --serve | 生成后启动内置 HTTP 服务 | | --port=<number> | 服务端口，默认 4173 | | --host=<host> | 服务主机，默认 127.0.0.1 | | --dry-run | 预览将生成的文件，不写入磁盘 | | --architecture-docs=<path> | 架构文档目录，默认 .docs | | --output=<path> | 输出目录，默认 .docs/aafe-generated/knowledge-web |

默认输出目录

.docs/aafe-generated/knowledge-web/
├── index.html          # 项目总览与扫描统计
├── modules.html        # 模块关系
├── routes.html         # 路由与页面
├── components.html     # 组件关系
├── sources.html        # 架构文档与 Mermaid 来源
├── impact.html         # 影响范围与 P0/P1/P2 测试预测
├── diagrams/*.html     # 每张 Mermaid 图独立预览，可跳转 Mermaid Live Editor
└── site.json           # 页面和图表索引

它是 Knowledge 的模块化可视化索引，不替代源码、.docs 原文或测试结果。

Agent 内自主命中

上面这些命令不需要你手动敲。项目初始化后，IDE Agent 有三条自主入口：

1. 会话钩子自动跑同步链。 sessionStart 触发 aafe task-completion，即 knowledge update → knowledge-web → update → doctor，历史文件迁移也在其中。钩子会依次尝试 node_modules/.bin/aafe（含 monorepo 向上查找）和全局 aafe；都找不到才静默退出，绝不会从网络拉包。

2. always-apply 规则替 Agent 做判定。 aafe-sdd-gate.mdc 默认把 SDD 融入 feature 工作流；aafe-ddd-gate.mdc 和 aafe-pattern-gate.mdc 要求显式意图后才运行对应分析；aafe-new-file-license.mdc 要求跑 aafe license ensure；影响分析规则要求先跑 aafe impact --diff 拿机器结果，而不是从零推断。

3. skill-index.md 里的命令表。 Agent 每个任务都先读这个文件，其中「Commands you may run yourself」列出了什么情况该跑什么：

| 情况 | 命令 | | ------------------------ | -------------------------------------- | | 定位模块 / 路由 / 组件 / 特性 / 符号 | aafe knowledge search "<terms>" | | 检索无结果且 .aafe/ 缺失或过期 | aafe analyze | | 改动前收集需求证据 | aafe context --requirement="..." | | 改动后报告影响面 | aafe impact --diff | | 规划测试 / 定位失败根因 | aafe test、aafe diagnose | | Runtime 文件看起来不一致 | aafe doctor、aafe migrate --dry-run |

这些命令除 analyze 和 migrate 外都只读，Agent 拿来验证假设的成本很低。定位代码时应优先用 aafe knowledge search 而不是盲目 grep——它跨模块、路由、组件、特性和符号排序，并把 userPhoneSearch、user-phone-search.js 和「用户手机号搜索」归一到同一组词元。

任务完成自动同步

项目初始化后默认启用。任务成功结束时自动执行：

aafe knowledge update → aafe knowledge-web → aafe update → aafe doctor

也可以手动执行：

aafe task-completion
aafe task-completion --dry-run

执行结果记录到 memory.path 下的 knowledge-sync.jsonl（默认 .aafe-memory/knowledge-sync.jsonl）。默认策略：任务失败时不写入 Knowledge；同步失败不阻断原任务，只记录日志。需要严格阻断时把 .aafe.config.json 的 taskCompletion.failClosed 改为 true。

{
  "taskCompletion": {
    "enabled": true,
    "command": "aafe task-completion",
    "steps": ["aafe knowledge update", "aafe knowledge-web", "aafe update", "aafe doctor"],
    "failClosed": false,
    "log": ".aafe-memory/knowledge-sync.jsonl"
  }
}

架构文档接入

如果项目存在 .docs 或其他架构文档目录，aafe analyze 会读取 Markdown / MDX 架构说明、Mermaid .mmd 图表，以及路由、模块、Store、API 和数据流说明。

aafe analyze --architecture-docs=.docs

生成：

.ai-agent/skills/project-architecture-locator.md
.aafe-memory/project-architecture.md
.ai-agent/skills/knowledge-center-architecture.md

使用原则：

1. 先读取架构文档和相关图表，再定位源码；
2. 文档与当前代码冲突时，以代码为事实并记录冲突；
3. Mermaid 图作为关系和流程证据，不作为可执行代码；
4. 需求、修复、重构完成后重新计算影响范围和测试范围；
5. 不把项目强行转换成不存在的业务领域模型。

AI Runtime 执行

# Planner + Orchestrator；按配置可继续调用 Cursor developer Agent
aafe run "实现一个支持取消、分页和缓存的日志检索功能"

# 声明式 Skill Pipeline
aafe pipeline "实现一个支持取消、分页和缓存的日志检索功能"

通用 feature 管线已融合 SDD，不包含默认关闭的 DDD 与设计模式步骤：

sdd-gate → memory-recaller → sdd-explore
→ architect → module-decomposer → evolution-predictor → [architecture_gate]
→ sdd-proposal → sdd-specs → sdd-design → sdd-tasks → sdd-approval → [sdd_gate]
→ adr-generator → [implementation_gate] → refactor-critic
→ experience-recorder → memory-writer → [merge_gate]

只有请求明确表达了相应意图，才会改走 domain-feature 或 pattern-feature 管线；graph 请求走 graph-feature。这些专用 pipeline 当前尚未复用通用 feature 的 SDD steps。

任务结束前，必须基于 .docs 和相关模块关系输出：直接/间接/潜在影响范围、架构证据、P0/P1/P2 测试预测、已执行与未覆盖的测试，以及未验证风险和人工确认项。

项目目录结构

标准安装（项目根目录即 Workspace Root）

.ai-agent/
├── runtime/                    # engine.md router.yaml gates.yaml protocol.md memory.md
├── skills/                     # 通用技能
├── pipelines/                  # feature / domain-feature / pattern-feature / refactor / performance …
├── scenarios/
├── ddd/                        # DDD 知识包（opt-in）
├── frontend-engineering/       # 设计模式知识包（opt-in）
├── frontend-memory/            # 前端 OOM 诊断包（opt-in，不是项目 Memory）
├── sdd/                        # SDD Skill 与 artifact/workflow rules（默认启用）
├── project.md                  # 项目自有，update 不覆盖
├── project-skills/             # 项目自有，update 不覆盖
└── rules/                      # 项目自有，update 不覆盖

.aafe-memory/                   # 项目 Memory（memory.path，必须指定目录；update 不覆盖）
├── index.md
├── learnings.jsonl
└── summary.md

.aafe/                          # analyze 与运行状态
├── tasks/<taskId>/             # task.json / context.json / events.jsonl
│   └── sdd/                    # change.json / revisions / traceability
├── runs/<runId>/               # Planner + Orchestrator 运行记录
└── e2e/                        # E2E 报告 / spec / auth（见 e2e.*Dir）

openspec/
├── changes/<changeId>/         # proposal / specs / design / tasks
└── specs/                      # sync 后的主规格

tests/ui-ai/cases/              # E2E YAML 用例（e2e.casesDir）

.cursor/                        # --editors=cursor 时，仅指针，不复制项目知识
├── rules/
├── skills/
└── hooks/

.docs/
└── aafe-generated/

.ai-agent/ 是项目 AI Runtime 入口；项目 Memory 在 memory.path（默认 .aafe-memory/）；Task/Run 状态在 .aafe/；共享 SDD artifact 在 openspec/。E2E 用例和报告只写 e2e.casesDir / e2e.reportDir。.docs/ 保留原始架构说明及 Knowledge 生成视图；编辑器目录只是指向 .ai-agent 的薄适配层。

子目录安装（Monorepo / 多模块）

Runtime 知识仍在安装目录；编辑器适配器在 Workspace Root 按模块分层：

# Workspace Root
.cursor/{rules,skills,hooks}/web/
.cursor/hooks.json
.codebuddy/web/
.codex/web/aafe.md
CLAUDE.md                  # 含 <!-- AAFE:module:web --> 模块块

# 安装目录 bklog/web/
.ai-agent/
.aafe-memory/              # memory.path，相对安装目录
.aafe.config.json          # 含 workspace / memory.path / e2e.*Dir
.docs/
package.json

Agent Skills 分发

AAFE 提供两条互不替代的链路：

| 场景 | 命令 | 写入位置 | | -------------- | ---------------------------------- | ----------------- | | 下载 Agent Skill | aafe skills install ... --github | Agent Skills 目录 | | 接入业务项目 Runtime | aafe init/update/analyze/doctor | 业务项目 .ai-agent/ |

npx --yes @aafe/agent-runtime@latest skills list --github
npx --yes @aafe/agent-runtime@latest skills install knowledge-center --github
npx --yes @aafe/agent-runtime@latest skills install aafe-vue-complex-runtime --github

不要使用 aafe skills install 替代业务项目的 aafe init/update/analyze/doctor。

开发与验证

项目根目录执行：

npm test                 # 全量：agent-platform / submit / license / tapd / workspace + doctor
npm run test:agent-platform
npm run doctor
node ./bin/aafe.js knowledge update --dry-run
node ./bin/aafe.js knowledge-web --dry-run

格式检查：

git diff --check

设计边界

• Runtime 核心提供通用编排能力，不承载具体业务 CMS 数据模型；
• SDD 是通用 feature 的默认规格层；sdd.enabled: false 是项目级退出，持久化验证与审批以当前 revision 为准；
• Skill Pipeline、Planner/Orchestrator 与 durable TaskManager 是三个协作运行面，不隐式共享 Task/Run 状态；
• DDD 与设计模式均为显式开启，不因代码库里的术语或需求里的裸关键词自动激活；
• 模式选型的产物是最小充分的模式组合，「不用设计模式」是合法结论；
• 领域模型区分 observed 与 inferred，没有证据的推断不伪装成事实；
• Knowledge Center 使用项目代码、.docs、Mermaid 图和 Memory；
• Knowledge Web 是本地可视化索引，不是独立深度文档站点；
• 子目录安装时，仅编辑器适配器写入 Workspace Root；.ai-agent / .aafe-memory / .docs 保留在安装目录；
• Memory 与 E2E 都必须先指定目录（memory.path、e2e.casesDir / e2e.reportDir 等），不要写到未配置路径；
• 自动生成内容必须保留来源、版本、置信度和审核状态；
• 不上传源码、密钥、Token、Cookie 或未脱敏业务数据；
• 自动更新不应覆盖人工维护的原始架构文档。
• ...