lanrtop 773f78a649 docs(blueprint): agent-infrastructure 模块拆解为 5 张任务卡（planned）

/architect + 复查自洽完成，拆出 A-E 五张 S/M 卡：
框架扫描 → 三件套生成 → 腐化评分 → 确认UI → 看板指示器

2026-06-29 18:02:57 +09:00

5.8 KiB

Raw Blame History

Agent 友好基础设施生成

接入包 v2 的核心扩展：从"分发固定模板"升级为"根据技术栈定制生成 Agent 友好基础设施"。炼境扫描项目技术栈 → 用户确认 → 生成三件套（元规则 + 契约映射 + 工具派生格式）。

定位

现有接入包（v1）解决了"让项目被炼境感知"的问题。本模块解决"让 agent 在项目里真正高效工作"的问题。

两者的关系：

v1 是注册入炼境飞轮的门票
v2 是项目内部 agent 工作环境的基础设施

生成的三件套

产物	用途	单一来源
`AGENTS.md`（元规则段落）	跨工具通用的防腐约定	炼境统一版本，接入时写入
`docs/ai-context/project-context.yaml`	技术栈特定的契约路径映射	炼境扫描后生成，技术栈变更时重新生成
`.claude/rules/doc-freshness.md`	Claude Code 的路径注入派生版	从 AGENTS.md 元规则自动派生

接入流程（扫描 → 确认 → 生成）

① 炼境扫描
   package.json / Cargo.toml / go.mod / Dockerfile
   → 识别框架、ORM、API 层、monorepo 结构

② 展示给用户确认（不跳过此步）
   "检测到：React 19 + Drizzle（drizzle/schema.ts）+ Hono（src/routes/）
    是否正确？"

③ 用户确认或手动修正

④ 定制化生成三件套

技术栈 → 契约路径映射规则

炼境内置识别表（示例，可扩展）：

识别条件	契约类型	默认路径
`prisma` in dependencies	数据库 schema	`prisma/schema.prisma`
`drizzle-orm` in dependencies	数据库 schema	`drizzle/schema.ts`
`hono` / `express`	API 接口	`src/routes/**`
`openapi` / `swagger`	API 接口	`openapi.yaml`
Rust + `axum`	API 接口	`src/routes/`
pnpm workspace	共享类型	`packages/types/**`

腐化监控（接入后持续运行）

炼境定期读取 git log，对比文档文件 vs 代码文件的最后修改时间：

风险级别	判断条件
🟢 正常	文档与代码同步更新
🟡 注意	核心代码改了，文档 14 天未动
🔴 高风险	外部契约类文件改了，AGENTS.md 30 天未动

技术栈变更感知：package.json / Cargo.toml 变化时主动提示"建议重新运行接入包生成"。

设计原则

元规则不含具体路径（技术栈无关），project-context.yaml 含路径（技术栈特定）
炼境生成，不要求用户手动维护多份格式
修复腐化永远是本地 agent 的事，炼境只检测和提醒

决策记录

元规则选用四支柱 + T1-T4 触发类型的双层结构：四支柱给 agent 判断"这个项目 ok 吗"，T1-T4 给 agent 判断"这次改动需要更新什么"
project-context.yaml 选 YAML 而非写进 AGENTS.md：技术栈映射是易变信息，独立文件符合防腐铁律（不写死进常驻文档）
确认步骤不可跳过：项目可能正在迁移技术栈，扫描结果不一定是当前权威状态

参考验证

2026-06-29 用 enterprise-system 做模拟验证：

技术栈识别准确（React + Drizzle + Hono + PostgreSQL）
最近 git log 有 "chore(db): 彻底移除 Prisma，全面统一 Drizzle"，完美复现 T3 工具链变更场景
project-context.yaml 不存在，验证了它需要炼境主动生成
.claude/rules/ 已有 6 个路径注入规则，验证了派生格式的可行性

任务卡

/architect 已完成（2026-06-29），复查自洽后拆为以下 5 张可执行卡。执行顺序：A 和 C 可并行 → B（依赖 A）→ D（依赖 A+B）→ E（依赖 C）

📋 A. 框架层扫描 + 契约路径推断

status: todo
complexity: M
files: src-tauri/src/commands/agent_infra.rs, src-tauri/src/commands/mod.rs, src-tauri/src/lib.rs, src/lib/commands.ts
acceptance: scan_agent_infra_stack(project_path, project_id) 能从 package.json（serde_json 解析 deps）和 Cargo.toml（字符串匹配）识别 Drizzle/Prisma/Hono/Axum 等框架，返回带 confidence 的 DetectedContract 列表；有单元测试覆盖 drizzle/prisma/hono 识别

📋 B. 三件套文件生成

status: todo
complexity: M
depends: A
files: src-tauri/src/commands/agent_infra.rs, src/lib/commands.ts
acceptance: generate_agent_infra_files(project_path, project_id, contracts) 正确写入 docs/ai-context/project-context.yaml（含实际契约路径）、向 AGENTS.md 注入元规则段落（已有则跳过）、生成含项目特定 globs 的 .claude/rules/doc-freshness.md；对同一项目重复执行幂等

📋 C. 文档腐化评分

status: todo
complexity: M
files: src-tauri/src/commands/agent_infra.rs, src-tauri/src/db.rs, src/lib/commands.ts
acceptance: scan_doc_freshness(project_path, project_id) 用 silent_cmd("git").current_dir(project_path) 读取契约路径 vs docs/ai-context/project-context.yaml 的最后 commit 时间戳，project-context.yaml 不存在直接返回 RED；结果写入 doc_freshness_cache 表（migration 补齐）；前端封装就绪

📋 D. 栈确认 UI + 生成按钮

status: todo
complexity: M
depends: A, B
files: src/components/dashboard/AgentInfraPanel.tsx, src/components/dashboard/BlueprintModal.tsx
acceptance: BlueprintModal 新增"Agent 基础设施"区块，展示 A 返回的检测结果（可编辑 contract 路径）、"生成三件套"按钮调用 B、展示写入结果（written/skipped/failed）；UI 无类型错误

📋 E. 看板腐化指示器

status: todo
complexity: S
depends: C
files: src/components/dashboard/ProjectCard.tsx, src/lib/commands.ts
acceptance: ProjectCard 右上角显示腐化评分小圆点（🟢🟡🔴），读取 doc_freshness_cache 缓存（无缓存则不显示）；不发起新的 git 扫描（仅读缓存）

5.8 KiB Raw Blame History Unescape Escape