通用 AI Agent 项目快照编译器

核心定位

本项目是一个通用 AI Agent 项目快照编译器。它不做长期记忆，不做项目管理，不直接执行开发任务，而是把当前代码状态转换为结构化、可查询、可交接的项目基线。

生命周期

生命周期是快照型，不维护后续状态。每次生成都基于当前 worktree、配置和 Adapter 版本重新构建。

启动
→ 读取项目配置
→ 发现项目形态
→ 调度 Adapter
→ 提取代码事实
→ 构建 Canonical Graph
→ 生成治理基线
→ 写入 SQLite 本地缓存
→ 生成 checksum
→ 运行 Quality Gate
→ 生成 Handoff Package
→ 交给项目承接体系
→ 生命周期结束

仓库与缓存策略

SQLite 是当前工作区的本地查询缓存，不提交仓库。跨开发节点的一致性依赖确定性重建，而不是共享数据库。

.agent/cache/
.agent/snapshots/
*.snapshot.sqlite

总体架构

核心是平台无关 runtime。Codex、Claude Code、Cursor、Windsurf、Cline、OpenCode 都只是集成层，MCP 是推荐通用入口。

project-snapshot/
├── core/           平台无关核心能力
├── cli/            通用命令行入口
├── mcp/            通用 Agent 工具入口
├── contracts/      跨平台协议
├── integrations/   Codex / Claude Code / Cursor / Windsurf / Cline / OpenCode
├── templates/      配置模板
├── fixtures/       多技术栈测试项目
├── tests/          自动化测试
└── docs/           面向开发者文档

统一项目图模型

不同语言、框架、前端、后端、移动端和分布式项目都必须映射到同一套模型，框架差异进入 Facet。

Node

表示项目抽象对象。普通文件、函数、类默认不建 Node，只建 Locator；入口、契约、实体、核心流程、业务能力、治理目标才提升为 Node。

workspace | system | subsystem | package | boundary | surface
capability | flow | entity | state | integration | test

Edge

表示项目关系。关键 Edge 必须有 Evidence。

contains | exposes | triggers | calls | reads | writes
produces | consumes | depends_on | guards | validates
affects | verified_by | located_at

Locator、Contract、Evidence、Facet

分层目录索引与图关系索引

目录索引用于看全貌，图关系索引用于查影响面。全貌查询只返回高层摘要，细节必须按 node id 二次展开。

workspace
  system
    subsystem
      boundary
        surface
          capability
            flow
              locator

capability.order.cancel
  writes      -> entity.order.status
  calls       -> capability.inventory.release
  produces    -> contract.event.order-cancelled
  verified_by -> test.order.cancel
  affected_by -> governance_item.order.status-risk

SQLite Schema

采用核心表 + metadata_json / facets 扩展。表结构不跟框架走，框架差异由 Facet 承接。

派生视图

Agent 默认只能查询派生视图，不能直接 dump 全量 nodes/edges。视图是插件面向 Agent 的产品接口。

budget:
  max_nodes: 20
  max_edges: 40
  max_locators: 20
  max_evidence: 10
  max_depth: 2
  include_code_body: false

查询协议

Agent 不直接写 SQL，只通过语义查询访问派生视图。工具内部返回 JSON，聊天展示可以转 YAML。

root()
subsystem(id)
capability(id)
io_boundary(filter?)
impact(target, depth=2)
governance(filter?)
governance_item(id)
stale(changed_files)
adapter_health()
expand(id, depth=1)
evidence(id)
locate(id)
search(query)

治理基线

治理基线识别当前代码中的治理事实和候选项，但不维护长期任务状态、用户决策历史或正式优先级。

治理状态与不可绕过项

open | needs_user_decision | accepted | dismissed_by_user
deferred_by_user | fixed | blocked

高风险项不可人为绕过，只能通过复核降级。高风险包括安全漏洞、数据破坏、权限绕过、资金/订单/核心流程正确性风险、系统无法启动或部署风险。

Adapter Registry

Adapter 由注册表驱动，声明检测规则、依赖、能力、输出、证据策略、checksum 策略和失败策略。

name:
display_name:
type: language | framework | platform | structure | contract | governance
version:
maturity: experimental | stable | verified | deprecated
priority:
deterministic:
detect:
requires:
conflicts_with:
file_scope:
ignore_scope:
capabilities:
outputs:
evidence_policy:
checksum_policy:
failure_policy:

质量门禁

快照不是生成成功就可信，必须通过结构、证据、查询、确定性、安全和治理校验。

校验维度

项目承接交接契约

Handoff 不交全量内容，只交入口、规则、质量状态和治理摘要。

handoff_package:
  package_version:
  handoff_id:
  snapshot:
  storage:
  query:
  quality:
  governance:
  stale_policy:
  ownership:
  warnings:
  next_actions:

CLI 与 MCP

CLI 是所有平台的底座，MCP 是推荐的通用 Agent 工具入口。MCP 是 CLI/runtime 的薄封装，不重新实现扫描逻辑。

project-snapshot init-config
project-snapshot discover
project-snapshot rebuild
project-snapshot validate
project-snapshot query
project-snapshot handoff
project-snapshot status
project-snapshot clean-cache

rebuild_snapshot
validate_snapshot
query_snapshot
handoff_snapshot
snapshot_status
clean_cache

统一错误响应

{
  "code": "",
  "message": "",
  "severity": "info | warning | blocking | fatal",
  "retryable": true,
  "blocks_handoff": true,
  "suggested_action": "",
  "details": {}
}

项目配置

仓库提交 .agent/project-intake.config.yml，只描述扫描规则、Adapter 策略、治理策略、脱敏策略、确定性规则和质量门禁。

version:
project:
scan:
adapters:
contracts:
governance:
redaction:
determinism:
quality_gate:
cache:

安全与脱敏

快照中禁止保存 secret value、.env 值、token、password、private key、本机绝对路径和真实机器信息。

测试策略

第一版最重要的不是覆盖率数字，而是四个硬保证：可复现、可查询、不泄密、可交接。

MVP 范围

MVP 目标是能对真实老项目执行一次全量重建，生成本地 SQLite 项目图快照，支持基础查询、治理基线、质量校验和 handoff。

未来扩展