148 lines
8.6 KiB
Markdown
148 lines
8.6 KiB
Markdown
# 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: done
|
||
- 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: done
|
||
- 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: done
|
||
- 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: done
|
||
- 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: done
|
||
- complexity: S
|
||
- depends: C
|
||
- files: src/components/dashboard/ProjectCard.tsx, src/lib/commands.ts
|
||
- acceptance: ProjectCard 右上角显示腐化评分小圆点（🟢🟡🔴），读取 `doc_freshness_cache` 缓存（无缓存则不显示）；不发起新的 git 扫描（仅读缓存）
|
||
|
||
### ✅ F3. Agent 健康诊断 + 可复制修正指令
|
||
- status: done
|
||
- complexity: M
|
||
- depends: C, D
|
||
- files: src-tauri/src/commands/agent_infra.rs, src-tauri/src/lib.rs, src/lib/commands.ts, src/components/dashboard/AgentInfraPanel.tsx
|
||
- acceptance: `get_agent_health(project_path, project_id)` 聚合 infra stack + doc freshness，生成问题列表 + Markdown 修正文本；AgentInfraPanel 加载时从 cache 读健康徽章，「重新检测 & 生成修正指令」按钮触发完整诊断，结果显示健康状态+可复制 textarea（含复制按钮）
|
||
|
||
## 复盘笔记
|
||
|
||
【陷阱记录】腐化诊断修复指引死循环（2026-07-03）
|
||
任务类型: 前端组件（诊断指引缺陷）
|
||
是否返工: 是（用户按指引"重新生成三件套"操作两轮无效）
|
||
返工原因: 腐化评分基于 git 提交时间（防"改了不提交"假新鲜，设计正确），但修复指引只说"重新生成"未说"需 commit"——生成动作只改工作区文件，git 时间戳不变，诊断永远无法清除，形成指引死循环
|
||
有效策略: 修复指引文案显式说明评分依据（"必须 git commit 该文件——评分基于 git 提交时间而非文件修改时间"）；enterprise-system 实测 commit 后转绿
|
||
遗留风险: ~~生成三件套的结果提示未加"记得提交"引导~~（2026-07-03 已补：生成结果区显示琥珀色提示"需 git commit 后才对腐化评分生效"）
|
||
auto_applied_rules: R11
|
||
rule_effectiveness: R11=有效（首次实战触发：诊断建议执行后未解决问题 → 修指引 + 记录失败案例）
|
||
|
||
【陷阱记录】双工作区数据合并的诊断错误（2026-07-03，用户纠错）
|
||
是否返工: 是（诊断结论侥幸正确，推理过程错误，被用户当场抓住）
|
||
返工原因: 排查 enterprise-system 双 project_id 时，SQL 只 SELECT 了 win_path 未查 wsl_path，把 WSL 工作区（\wsl.localhost\...）误判为"无路径的废弃注册"。实际为同项目的 WSL 旧副本（56 commit 停在 2026-05-19，全部 ⊂ Windows 副本 302 commit，git 同源）。合并操作在"同源仓库"事实下恰好合理（同一套历史归主工作区），但若两副本真是独立项目，该操作会造成数据污染
|
||
有效策略: 用户质疑后用 git sha 集合交集取证（WSL 56 ∩ Windows 302 = 56 → 同源实锤），证据先于结论
|
||
遗留边界（记入设计约束）: commit_metrics 以 sha 为全局主键，隐含假设"一个 commit 归一个项目"——同源多工作区（win+wsl 双副本）打破该假设，无论数据怎么分配都无法两侧完整。当前裁决：同源归主工作区；若未来出现真·多工作区并行开发场景，需评估复合主键 (sha, project_id) + profile 级去重
|
||
auto_applied_rules: 无
|
||
rule_effectiveness: —（本条是 Claude 排查方法论的教训：查询字段不全就下结论 = 证据链断裂）
|
||
|