refactor(ffi): 降级 FFI 为可选兼容层并整理文档

将 bat-ffi 明确收敛为无状态 C ABI 兼容层，默认集成路径改为 bat --json 进程边界或未来稳定 SDK。

同步 README、当前状态、项目计划、架构文档、开发指南和缺口清单，移除 FFI 作为主集成边界的表述。

新增 AGENTS.md 和 CONTRIBUTING.md，压缩 CLAUDE.md 为兼容入口，并归档阶段性报告、同步 .gitignore 规则。

internal/ffi/ffi.go

@@ -1,3 +1,8 @@
+// Package ffi is an optional CGO compatibility wrapper around bat-ffi.
+//
+// It is not the primary Go integration path. Product CLI orchestration should
+// prefer the Rust bat process boundary with --json output, or a future stable
+// SDK. Keep this package stateless and limited to coarse JSON helper calls.
 package ffi
 
 /*
@@ -13,45 +18,45 @@ extern char* bat_sync_plan_json(const char* current_json, const char* previous_j
 */
 import "C"
 import (
-    "errors"
-    "unsafe"
+	"errors"
+	"unsafe"
 )
 
 func Version() (string, error) {
-    ptr := C.bat_version()
-    if ptr == nil {
-        return "", errors.New("bat_version returned nil")
-    }
-    defer C.bat_free_string((*C.char)(unsafe.Pointer(ptr)))
-    return C.GoString(ptr), nil
+	ptr := C.bat_version()
+	if ptr == nil {
+		return "", errors.New("bat_version returned nil")
+	}
+	defer C.bat_free_string((*C.char)(unsafe.Pointer(ptr)))
+	return C.GoString(ptr), nil
 }
 
 func InspectManifest(rawJSON string) (string, error) {
-    cRaw := C.CString(rawJSON)
-    defer C.free(unsafe.Pointer(cRaw))
+	cRaw := C.CString(rawJSON)
+	defer C.free(unsafe.Pointer(cRaw))
 
-    ptr := C.bat_manifest_inspect_json(cRaw)
-    if ptr == nil {
-        return "", errors.New("bat_manifest_inspect_json returned nil")
-    }
-    defer C.bat_free_string((*C.char)(unsafe.Pointer(ptr)))
-    return C.GoString(ptr), nil
+	ptr := C.bat_manifest_inspect_json(cRaw)
+	if ptr == nil {
+		return "", errors.New("bat_manifest_inspect_json returned nil")
+	}
+	defer C.bat_free_string((*C.char)(unsafe.Pointer(ptr)))
+	return C.GoString(ptr), nil
 }
 
 func BuildSyncPlan(currentJSON, previousJSON string) (string, error) {
-    cCurrent := C.CString(currentJSON)
-    defer C.free(unsafe.Pointer(cCurrent))
+	cCurrent := C.CString(currentJSON)
+	defer C.free(unsafe.Pointer(cCurrent))
 
-    var cPrevious *C.char
-    if previousJSON != "" {
-        cPrevious = C.CString(previousJSON)
-        defer C.free(unsafe.Pointer(cPrevious))
-    }
+	var cPrevious *C.char
+	if previousJSON != "" {
+		cPrevious = C.CString(previousJSON)
+		defer C.free(unsafe.Pointer(cPrevious))
+	}
 
-    ptr := C.bat_sync_plan_json(cCurrent, cPrevious)
-    if ptr == nil {
-        return "", errors.New("bat_sync_plan_json returned nil")
-    }
-    defer C.bat_free_string((*C.char)(unsafe.Pointer(ptr)))
-    return C.GoString(ptr), nil
+	ptr := C.bat_sync_plan_json(cCurrent, cPrevious)
+	if ptr == nil {
+		return "", errors.New("bat_sync_plan_json returned nil")
+	}
+	defer C.bat_free_string((*C.char)(unsafe.Pointer(ptr)))
+	return C.GoString(ptr), nil
 }