ai-native-core 0.1.0

package/README.md

@@ -0,0 +1,129 @@
+# AI Native Core
+
+**让任何项目拥有 AI Native 开发能力——不是另一个模板仓库，而是一个可安装的运行时框架。**
+
+---
+
+## 这是什么
+
+`ai-native-core` 是一个配置驱动、适配器模式、跨技术栈的 AI Native 开发框架。它把 AI Agent 在项目中高效工作所需的全部能力——资产记忆、SDD 门禁、双轨验证、自迭代 hooks、验收自动化——打包为一个可安装的运行时。
+
+核心理念：**AI Agent 不应该每次都重新阅读几十份项目文档。项目知识应该被蒸馏为紧凑的记忆因子，自动加载到每次会话中。**
+
+核心职责：
+
+- **资产记忆引擎**：从项目文档蒸馏出高信号约束因子，让 AI Agent 每次会话自动加载
+- **SDD 门禁系统**：强制 spec-before-code 流程，不可跳步
+- **双轨验证管道**：代码行为验证 + 视觉渲染验证，两者不可互替
+- **自迭代 hooks**：自动检测范式变更、提醒踩坑复盘、驱动记忆更新
+- **验收自动化**：结构化验收配置，AI 按管道执行并输出报告
+
+## 快速开始
+
+```bash
+# 安装
+npm install -g ai-native-core
+
+# 在目标项目中初始化
+cd my-project
+ai-native init --stack react-spa    # 选择适配器
+
+# 编辑配置文件
+vim .ai-native/config.toml           # 项目元信息
+vim .ai-native/memory/MANIFEST.yaml  # 记忆因子定义
+vim .ai-native/acceptance.yaml       # 验收管道
+
+# 首次蒸馏资产记忆
+ai-native sync
+
+# 运行验收
+ai-native accept
+```
+
+## 核心能力一览
+
+| 能力 | 实现方式 |
+|------|---------|
+| 记忆因子 | MANIFEST.yaml 声明式驱动，可增减/自定义 |
+| 技术栈 | 适配器模式，支持 React / Vue / Next.js / Go / Python |
+| 配置方式 | TOML/YAML 单一配置入口 |
+| AI 工具 | 同时生成 Claude / Cursor / Copilot 配置 |
+| 蒸馏方式 | 蒸馏引擎自动执行（源文件 → LLM 蒸馏 → 因子文件） |
+| 项目类型 | 前端 / 后端 / CLI / 全栈 |
+| 安装方式 | npm install -g 可执行 CLI |
+| 验收 | YAML 配置 → 自动执行 → 结构化报告 |
+| 记忆共享 | 组织 / 项目 / 个人三层记忆模型 |
+| 路径约定 | 完全配置驱动，无硬编码 |
+
+## 五层架构
+
+```
+┌─────────────────────────────────────────────┐
+│ Layer 5  验收层（acceptance.yaml pipeline）   │
+│          env → lint → typecheck →            │
+│          test → e2e → visual → build         │
+├─────────────────────────────────────────────┤
+│ Layer 4  自迭代层（hooks engine）             │
+│          踩坑复盘 → 范式检测 → 记忆更新       │
+├─────────────────────────────────────────────┤
+│ Layer 3  SDD 门禁层（propose → confirm →     │
+│          apply，不可跳步）                     │
+├─────────────────────────────────────────────┤
+│ Layer 2  资产记忆层（memory distiller）       │
+│          源文件 → LLM 蒸馏 → 因子文件          │
+│          └─ .ai-native/memory/               │
+├─────────────────────────────────────────────┤
+│ Layer 1  配置驱动层（config + adapters）      │
+│          .ai-native/config.toml              │
+│          adapters/{react,vue,nextjs,...}     │
+└─────────────────────────────────────────────┘
+```
+
+## 目录结构
+
+```
+ai-native-core/
+├── README.md
+├── docs/
+│   └── design/
+│       ├── architecture.md              # 完整架构设计
+│       ├── design-rationale.md          # 设计理念与问题分析
+│       ├── memory-factor-spec.md        # 记忆因子文件格式 + SYNC-STATE 模板
+│       ├── sync-engine-spec.md          # 蒸馏引擎行为规范
+│       ├── hooks-implementation-spec.md # Hooks 实现合约
+│       ├── acceptance-gate-spec.md      # 验收门禁规范
+│       └── studybook-format.md          # 踩坑记录格式
+├── config/
+│   ├── ai-native.config.toml       # 项目级配置示例
+│   ├── memory-manifest.yaml        # 记忆因子 schema
+│   └── acceptance.yaml             # 验收管道 schema
+├── adapters/                        # 多技术栈适配器
+│   ├── react-spa/                   # React SPA（TanStack 生态）
+│   ├── nextjs/                      # Next.js 全栈
+│   ├── vue/                         # Vue 3 + Vite
+│   ├── backend-go/                  # Go 后端服务
+│   └── backend-python/              # Python FastAPI
+├── src/
+│   ├── cli/                         # CLI 入口
+│   ├── core/                        # 核心引擎
+│   │   ├── distiller.ts             # 蒸馏引擎
+│   │   ├── hooks.ts                 # Hook 引擎
+│   │   └── acceptance.ts            # 验收执行器
+│   └── adapters/                    # 适配器实现
+└── templates/                       # 记忆因子模板
+```
+
+## 设计原则
+
+1. **配置 > 代码**：项目差异通过配置表达，不修改框架源码
+2. **适配器隔离**：技术栈差异封装在适配器中，核心引擎与栈无关
+3. **渐进式采用**：可以先只用记忆蒸馏，再逐步接入 SDD、双轨验证
+4. **LLM 无关**：框架定义管道，不绑定特定 AI 模型或工具
+5. **可见即可审计**：所有自动生成的配置、记忆因子都是人类可读的文本文件
+
+## 状态
+
+当前为设计阶段。
+
+- **使用指南** → `docs/user-guide.md`
+- **架构设计** → `docs/design/architecture.md`

package/adapters/backend-go/README.md

@@ -0,0 +1,11 @@
+# Go 后端适配器
+
+适配目标：Go 1.22+ + net/http (或 gin/echo/chi) + GORM/sqlx + PostgreSQL
+
+## 提供的默认模板
+
+- 无设计因子（后端项目不需要 design-foundation）
+- 新增：
+  - api-contract.md：API 契约约束（RESTful 规范、错误码、分页格式）
+  - database-rules.md：数据库约束（migration 规则、索引规范、查询性能）
+  - security-rules.md：认证（JWT/OAuth2）、授权（RBAC）、输入校验、密钥管理

package/adapters/backend-python/README.md

@@ -0,0 +1,12 @@
+# Python 后端适配器
+
+适配目标：Python 3.12+ + FastAPI + SQLAlchemy 2.0 + Pydantic v2 + PostgreSQL
+
+## 提供的默认模板
+
+- 无设计因子（后端项目不需要 design-foundation）
+- 新增：
+  - api-contract.md：FastAPI 路由规范、Pydantic schema 分层、依赖注入规则
+  - database-rules.md：SQLAlchemy 2.0 声明式映射、migration (Alembic)、查询性能
+  - security-rules.md：OAuth2 + JWT、RBAC、CORS、rate limiting
+  - typing-rules.md：Python 类型注解强制规则（mypy strict）

package/adapters/nextjs/README.md

@@ -0,0 +1,11 @@
+# Next.js 适配器
+
+适配目标：Next.js 14+ (App Router) + React 19 + Tailwind CSS v4 + shadcn/ui
+
+## 与 react-spa 的关键差异
+
+- 新增 SSR/SSG/ISR 相关禁止模式
+- Server Components vs Client Components 边界规则
+- `use client` 指令的必需场景
+- API Routes / Server Actions 的安全约束
+- 中间件（middleware）认证守卫规则

package/adapters/react-spa/README.md

@@ -0,0 +1,16 @@
+# React SPA 适配器
+
+适配目标：React 19 + Vite + TanStack Router/Query/Form/Table + Tailwind CSS v4 + shadcn/ui
+
+## 提供的默认模板
+
+- 记忆因子模板（design-foundation / forbidden-patterns / known-pitfalls / available-resources / architecture-paradigm）
+- 默认禁止模式（状态分层、组件边界、类型安全）
+- 默认验收管道（lint → typecheck → test → e2e → build）
+
+## 提供的默认规则
+
+- TanStack 全家桶的状态分层：Query（服务端数据）→ Zustand（客户端 UI）→ Form（表单）
+- shadcn/ui 组件使用规则（Base UI 优先，Radix 仅回退）
+- Tailwind v4 CSS token 用法规则
+- TypeScript strict 模式约束

package/adapters/react-spa/immutable-rules.md

@@ -0,0 +1,48 @@
+# React SPA 适配器 — 架构不变性规则
+
+以下规则由适配器内置，定义了 React SPA 项目的基础架构边界。
+这些规则在蒸馏 forbidden-patterns 时自动纳入，不依赖项目文档。
+
+---
+
+## 状态分层（不可变）
+
+- 禁止服务端数据（列表、详情、分页、缓存）进入 Zustand（必须使用 TanStack Query）
+- 禁止表单字段值进入 Zustand（必须使用 TanStack Form）
+- 禁止在 TanStack Query 的 queryFn 之外直接 fetch/axios 获取服务端数据
+- 禁止在组件内使用 useState 管理跨组件共享的 UI 状态
+
+## 组件边界（不可变）
+
+- 禁止业务逻辑（API 调用、状态管理、路由跳转）写入 components/ui/
+- 禁止在 components/ui/ 中的组件引入 features/ 下的任何模块
+- 禁止组件层直接调用 toast() 或 Toaster（必须通过 lib/notify.ts 统一封装）
+- 禁止在 features/ 之外的模块直接操作 Zustand store（必须通过封装的 hooks）
+
+## 类型安全（不可变）
+
+- 禁止对整个对象做宽泛类型断言（as WholeObject），必须最小化到单字段
+- 禁止用数组下标作为列表 key（必须用稳定业务标识符）
+- 禁止 API 函数的 nullable 返回值隐式返回 undefined（必须显式 `return result ?? null`）
+
+## CSS / 样式（不可变）
+
+- 禁止硬编码 hex/rgb/hsl 颜色值（只允许 CSS 变量或 Tailwind token）
+- 禁止在组件内写媒体查询实现暗色模式（必须使用 .dark 类覆盖）
+- 禁止 CSS token 双重包裹（hsl(hsl(...))）
+
+## SDD 流程（不可变）
+
+- 禁止跳过 spec 阶段直接写实现代码
+- 禁止 design.md 缺少 ASCII 页面骨架图
+
+## 技术栈一致性（不可变）
+
+- 禁止在已有 shadcn/ui Base UI 的项目中引入 Radix UI 作为替代
+- 禁止在 features/ 层直接 import from @base-ui/react/*
+- 禁止手动修改自动生成的路由文件
+
+## 文件结构（不可变）
+
+- 禁止在 src/components/ui/ 之外创建 shadcn 风格的组件文件
+- 禁止 features/ 模块之间直接 import 对方的内部组件

package/adapters/vue/README.md

@@ -0,0 +1,10 @@
+# Vue 3 适配器
+
+适配目标：Vue 3 + Vite + Pinia + Vue Router + Tailwind CSS
+
+## 与 react-spa 的差异
+
+- 状态管理：Pinia 替代 Zustand + TanStack Query
+- 路由：Vue Router 替代 TanStack Router
+- 组件：Vue SFC 替代 TSX
+- 禁止模式：Vue 特有的反模式（如直接修改 props、在 setup 外使用 composition API）

package/bin/ai-native.js

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+
+// ai-native — AI Native Core CLI
+
+const commands = ['init', 'sync', 'accept', 'hooks'];
+const args = process.argv.slice(2);
+const command = args[0];
+
+if (!command || command === '--help' || command === '-h') {
+  console.log(`
+ai-native — AI Native Core CLI
+
+Usage:
+  ai-native <command> [options]
+
+Commands:
+  init    --stack <adapter>    初始化 AI Native 到当前项目
+  sync    [--check|--force|--dry-run|--factor <name>]
+                               蒸馏资产记忆因子
+  accept  [--ci]               运行验收管道
+  hooks   install|status       管理自迭代 hooks
+
+Examples:
+  ai-native init --stack react-spa
+  ai-native sync --check
+  ai-native accept --ci
+
+Version: ${require('../package.json').version}
+`);
+  process.exit(0);
+}
+
+if (!commands.includes(command)) {
+  console.error(`Unknown command: ${command}`);
+  process.exit(1);
+}
+
+try {
+  require(`../src/commands/${command}`).run(args.slice(1));
+} catch (err) {
+  console.error(`Error: ${err.message}`);
+  process.exit(1);
+}

package/config/acceptance.yaml

@@ -0,0 +1,107 @@
+# =============================================================================
+# AI Native Core — 验收管道配置
+# =============================================================================
+# 定义 AI Agent 在 onboarding / 发布前必须通过的检查项
+# 执行 `ai-native accept` 时读取此文件
+# =============================================================================
+
+version: 1
+
+# 报告格式
+report:
+  format: markdown
+  output_dir: ".ai-native/reports/"
+  filename_template: "acceptance-{date}-{status}.md"
+
+# =============================================================================
+# Phase 1 — 环境验收
+# =============================================================================
+- name: environment
+  description: 开发环境基础检查
+  checks:
+    - id: node-version
+      type: exec
+      run: "node --version"
+      expect:
+        pattern: "v(18|20|22)\\.\\d+\\.\\d+"
+
+    - id: package-manager
+      type: exec
+      run: "pnpm --version"
+
+    - id: git
+      type: exec
+      run: "git --version"
+
+    - id: memory-initialized
+      type: file-exists
+      paths:
+        - ".ai-native/memory/SYNC-STATE.md"
+      message: "资产记忆未初始化，运行 ai-native sync"
+
+    - id: config-exists
+      type: file-exists
+      paths:
+        - ".ai-native/config.toml"
+
+# =============================================================================
+# Phase 2 — 代码质量
+# =============================================================================
+- name: code-quality
+  description: 静态检查和类型验证
+  checks:
+    - id: lint
+      type: exec
+      run: "pnpm lint"
+
+    - id: typecheck
+      type: exec
+      run: "pnpm typecheck"
+
+    - id: test
+      type: exec
+      run: "pnpm test"
+
+# =============================================================================
+# Phase 3 — E2E（双轨）
+# =============================================================================
+- name: e2e
+  description: 端到端验证
+  checks:
+    - id: e2e-code
+      type: exec
+      run: "pnpm e2e"
+      label: "轨道 1 — 代码行为验证"
+
+    - id: e2e-visual
+      type: visual
+      tool: "chrome-mcp"
+      label: "轨道 2 — 视觉渲染验证"
+      # optional: true   # 视觉走查失败不阻塞通过（当工具不可用时）
+
+# =============================================================================
+# Phase 4 — 构建
+# =============================================================================
+- name: build
+  description: 生产构建验证
+  checks:
+    - id: build
+      type: exec
+      run: "pnpm build"
+
+# =============================================================================
+# Check 类型定义
+# =============================================================================
+# type: exec
+#   执行 shell 命令，exit code 0 为通过
+#   expect.pattern: 可选，校验 stdout 匹配正则
+#   expect.contains: 可选，校验 stdout 包含字符串
+#
+# type: file-exists
+#   检查文件/目录是否存在
+#   paths: string[]
+#
+# type: visual
+#   调用视觉验证工具（如 chrome-mcp）截图走查
+#   tool: chrome-mcp | playwright-mcp
+#   optional: 视觉验证失败是否阻塞（默认 false）

package/config/ai-native.config.toml

@@ -0,0 +1,145 @@
+# =============================================================================
+# AI Native Core — 项目级配置
+# =============================================================================
+# 本文件是框架的单一配置入口。
+# 执行 `ai-native init` 时自动生成，可按需编辑。
+# =============================================================================
+
+[project]
+# 项目名称（用于报告和提示文案）
+name = "my-project"
+# 项目类型：frontend | backend | fullstack | cli | library
+type = "frontend"
+# 项目描述（可选，用于 AI context）
+description = ""
+
+# =============================================================================
+# 技术栈
+# =============================================================================
+[stack]
+# 适配器 ID，决定默认模板和规则
+# 可选值：react-spa | nextjs | vue | svelte | backend-go | backend-python
+adapter = "react-spa"
+
+# 包管理器：pnpm | npm | yarn | bun
+package_manager = "pnpm"
+
+# CSS 方案（前端项目）：tailwind-v4 | tailwind-v3 | css-modules | styled-components | none
+css = "tailwind-v4"
+
+# UI 组件库（前端项目）：shadcn | radix | mui | antd | none
+ui_library = "shadcn"
+
+# 测试框架：vitest | jest | playwright | go-test | pytest
+test_framework = "vitest"
+
+# TypeScript（前端/Node 项目）
+typescript = true
+
+# =============================================================================
+# 源文件路径（蒸馏源）
+# =============================================================================
+[paths]
+# 文档目录（架构决策、设计系统、编码规范等）
+docs = "docs/"
+
+# 设计资产目录（tokens、组件截图等）
+design = "design/"
+
+# 源码目录
+source = "src/"
+
+# 功能模块目录
+features = "src/features/"
+
+# CI/CD 配置目录
+ci = ".github/workflows/"
+
+# =============================================================================
+# AI 工具链
+# =============================================================================
+[ai_tools]
+# 目标 AI 工具：同时生成多套配置
+# 可选值：claude | cursor | copilot | all
+engines = ["claude", "cursor"]
+
+# SDD 工具：openspec | linear | none
+sdd_tool = "openspec"
+
+# E2E 视觉验证工具：chrome-mcp | playwright-mcp | none
+visual_e2e_tool = "chrome-mcp"
+
+# =============================================================================
+# 范式路径（监控哪些路径变更时触发 sync）
+# =============================================================================
+[paradigm]
+# 当 commit 涉及这些路径时，提示运行 ai-native sync
+watch_paths = [
+  "docs/architecture/",
+  "docs/design-system/",
+  "design/",
+  ".github/workflows/",
+]
+
+# 踩坑记录目录
+studybook_path = "docs/decisions/"
+
+# 范式变更日志文件
+self_update_path = "CHANGELOG.md"
+
+# =============================================================================
+# Hooks 配置（自迭代引擎）
+# =============================================================================
+[hooks]
+# 是否启用
+enabled = true
+
+# 复盘提醒冷却时间（秒），默认 1200（20 分钟）
+reminder_cooldown_sec = 1200
+
+# 是否启用范式变更检测
+paradigm_detection = true
+
+# =============================================================================
+# SDD 门禁（Spec-Driven Development）
+# =============================================================================
+[sdd]
+# 是否强制 spec-before-code
+enforced = true
+
+# 是否要求 design.md 包含 ASCII wireframe
+require_ascii_wireframe = true
+
+# =============================================================================
+# Onboarding（新成员引导流程）
+# =============================================================================
+[onboarding]
+# 是否启用 Demo Golden Path（无 Demo 项目可关闭）
+demo_enabled = false
+
+# 如果是 true，Demo 类型：user-profile | custom
+# demo_type = "user-profile"
+
+# =============================================================================
+# 记忆因子蒸馏
+# =============================================================================
+[distiller]
+# 记忆因子清单文件路径
+manifest = ".ai-native/memory/MANIFEST.yaml"
+
+# 记忆文件输出目录
+output_dir = ".ai-native/memory/"
+
+# LLM provider（用于蒸馏）：openai | anthropic | local
+# 如果不配置，使用 AI Agent 当前会话的模型
+# llm_provider = "anthropic"
+
+# =============================================================================
+# 验收
+# =============================================================================
+[acceptance]
+# 验收配置路径
+config = ".ai-native/acceptance.yaml"
+
+# 报告输出目录
+report_dir = ".ai-native/reports/"

package/config/memory-manifest.yaml

@@ -0,0 +1,178 @@
+# =============================================================================
+# AI Native Core — 记忆因子清单
+# =============================================================================
+# 声明式定义每个记忆因子：从哪里来、蒸馏规则、质量标准
+# 执行 `ai-native sync` 时读取此文件
+# =============================================================================
+
+version: 1
+
+# 默认蒸馏 prompt（所有因子共用，各因子可覆盖）
+default_distill_prompt: |
+  你是项目知识蒸馏器。从以下源文件中提取高信号约束。
+  要求：
+  - 每条一行，独立可操作，读一遍能做出正确决策
+  - 不是文件摘要，是直接影响行为的约束
+  - 禁止复制源文件原文，只输出蒸馏后的因子
+
+# =============================================================================
+# 因子定义
+# =============================================================================
+factors:
+  - name: design-foundation
+    description: UI 开发行为约束：组件优先级、token 用法、布局规则
+    source_globs:
+      - "design/**/*.md"
+      - "design/**/*.css"
+      - "docs/design-system/**/*.md"
+    distill_prompt: |
+      提取设计约束：用什么组件库、token 怎么用、布局规则、禁止的写法。
+      聚焦"怎么做"而非"有什么"。
+    max_items: 15
+    priority: critical
+    output_file: "design-foundation.md"
+
+  - name: forbidden-patterns
+    description: 明确禁止的行为红线
+    source_globs:
+      - "docs/architecture/**/*.md"
+      - "docs/standards/**/*.md"
+      - ".github/workflows/*.yml"
+    builtin_sources:
+      - "adapters/{stack}/immutable-rules.md"  # 适配器内置架构不变性规则，始终纳入蒸馏
+    distill_prompt: |
+      提取所有"禁止"、"不允许"、"不要"开头的规则。
+      适配器内置规则（builtin_sources）具有最高优先级，必须全部保留。
+      项目文档中的规则作为补充。每条以"禁止"开头。标注来源。
+    max_items: 25
+    priority: critical
+    output_file: "forbidden-patterns.md"
+
+  - name: known-pitfalls
+    description: 实战中踩过的坑
+    source_globs:
+      - "docs/decisions/**/*.md"
+      - "docs/postmortems/**/*.md"
+    distill_prompt: |
+      提取踩坑记录。格式：`问题描述 → 根因 → 正确做法`。
+      每条一行。去重。
+    max_items: 15
+    priority: high
+    output_file: "known-pitfalls.md"
+
+  - name: available-resources
+    description: 现成可用资源索引
+    source_globs:
+      - "src/components/"
+      - "src/hooks/"
+      - "src/utils/"
+      - "templates/"
+    distill_prompt: |
+      列出可复用的组件、hooks、工具函数、模板。
+      格式：`名称 — 路径 — 一句话用途`。
+    max_items: 20
+    priority: high
+    output_file: "available-resources.md"
+
+  - name: architecture-paradigm
+    description: 架构决策和工作范式
+    source_globs:
+      - "docs/architecture/**/*.md"
+      - "docs/adr/**/*.md"
+      - "README.md"
+    distill_prompt: |
+      提取架构决策、分层规则、数据流约束、状态管理策略。
+      每条一个决策点。
+    max_items: 15
+    priority: critical
+    output_file: "architecture-paradigm.md"
+
+# =============================================================================
+# 蒸馏质量规则
+# =============================================================================
+quality:
+  max_item_length: 200
+  max_file_lines: 50
+  max_common_substring_with_source: 80
+  forbidden_in_output:
+    - "本文档"
+    - "以下"
+    - "详见"
+    - "参考"
+
+# =============================================================================
+# SYNC-STATE 配置 + per-factor 增量 hash
+# =============================================================================
+sync_state:
+  file: "SYNC-STATE.md"
+  fields:
+    - synced_at
+    - git_hash
+    - monitored_paths
+    - files_read
+    - factors_synced
+    - factor_hashes
+
+# =============================================================================
+# 记忆文件输出格式
+# =============================================================================
+# 详见 docs/design/memory-factor-spec.md
+output_format:
+  frontmatter:
+    required:
+      - name
+      - description
+      - metadata.type
+      - metadata.synced-from
+      - metadata.synced-at
+      - metadata.source-files
+  content:
+    item_prefix: "- "
+    item_separator: "\n"
+
+# =============================================================================
+# Template sync
+# =============================================================================
+template_sync:
+  enabled: true
+  dir: "docs/.ai-native/memory/"
+  files:
+    - "design-foundation.md"
+    - "forbidden-patterns.md"
+    - "known-pitfalls.md"
+    - "available-resources.md"
+    - "architecture-paradigm.md"
+    - "SYNC-STATE.md"
+
+# =============================================================================
+# AI 工具配置生成模板
+# =============================================================================
+ai_config_generation:
+  claude:
+    file: ".claude/CLAUDE.md"
+    template: |
+      # Project Context
+
+      ## 资产记忆因子
+
+      以下文件由 `ai-native sync` 生成，首次使用或范式变更后需重新同步。
+
+      {memory_references}
+
+  cursor:
+    file: ".cursor/rules/ai-native.md"
+    template: |
+      # AI Native Memory Factors
+
+      Always apply these constraints when generating code:
+
+      {memory_references}
+
+  copilot:
+    file: ".github/copilot-instructions.md"
+    template: |
+      ## Project Constraints
+
+      Read before generating code:
+
+      {memory_references}

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "ai-native-core",
+  "version": "0.1.0",
+  "description": "让任何项目拥有 AI Native 开发能力的运行时框架",
+  "keywords": ["ai-native", "ai-agent", "claude-code", "developer-tools"],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/xxin1438-lang/ai-native-core.git"
+  },
+  "bin": {
+    "ai-native": "./bin/ai-native.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "adapters/",
+    "config/",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/commands/accept.js

@@ -0,0 +1,83 @@
+// ai-native accept
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+const { getProjectRoot, loadConfig } = require('../core/config');
+
+function run(args) {
+  const isCI = args.includes('--ci');
+  const root = getProjectRoot();
+  const config = loadConfig(root);
+  const reportDir = path.join(root, '.ai-native', 'reports');
+  if (!fs.existsSync(reportDir)) fs.mkdirSync(reportDir, { recursive: true });
+
+  const results = [];
+  const date = new Date().toISOString().split('T')[0];
+
+  console.log('[ai-native] 验收开始\n');
+
+  // Phase 1
+  console.log('Phase 1 — 环境');
+  check('node-version', () => {
+    const v = execSync('node --version', { encoding: 'utf-8' }).trim();
+    return { pass: /v(1[89]|2[0-9])/.test(v), detail: v };
+  }, results);
+  check('git', () => {
+    const v = execSync('git --version', { encoding: 'utf-8' }).trim();
+    return { pass: true, detail: v };
+  }, results);
+  check('memory', () => {
+    const p = path.join(root, '.ai-native', 'memory', 'SYNC-STATE.md');
+    return { pass: fs.existsSync(p), detail: fs.existsSync(p) ? 'initialized' : 'NOT INITIALIZED' };
+  }, results);
+
+  // Phase 2
+  console.log('Phase 2 — 代码质量');
+  check('lint', () => tryExec('pnpm lint || npm run lint || true', root), results);
+
+  // Phase 3
+  console.log(`Phase 3 — E2E${isCI ? ' (CI: visual skipped)' : ''}`);
+  check('e2e-track1', () => tryExec('pnpm e2e || npm run e2e || true', root), results);
+  if (!isCI) check('e2e-track2-visual', () => ({ pass: true, detail: 'manual (chrome-mcp)' }), results);
+
+  // Phase 4
+  console.log('Phase 4 — 构建');
+  check('build', () => tryExec('pnpm build || npm run build || true', root), results);
+
+  const passed = results.filter(r => r.pass).length;
+  const failed = results.filter(r => !r.pass).length;
+  const status = failed === 0 ? 'PASS' : 'FAIL';
+
+  console.log(`\n[ai-native] ${status} (${passed}/${results.length})`);
+
+  const rp = path.join(reportDir, `acceptance-${date}-${status}.md`);
+  const lines = [`# AI Native Onboarding Report`, ``, `**Date**: ${date}`, `**Project**: ${config.project?.name || 'unknown'}`, `**Status**: ${status}`, ``];
+  results.forEach(r => lines.push(`- ${r.pass ? '✓' : '✗'} **${r.name}**: ${r.detail || ''}`));
+  fs.writeFileSync(rp, lines.join('\n'));
+  console.log(`  报告: ${path.relative(root, rp)}`);
+
+  if (status === 'FAIL') process.exit(1);
+}
+
+function check(name, fn, results) {
+  try {
+    const { pass, detail } = fn();
+    console.log(`  ${pass ? '✓' : '✗'} ${name}${detail ? ': ' + detail : ''}`);
+    results.push({ name, pass, detail });
+  } catch (err) {
+    console.log(`  ✗ ${name}: ${err.message}`);
+    results.push({ name, pass: false, detail: err.message });
+  }
+}
+
+function tryExec(cmd, cwd) {
+  try {
+    execSync(cmd, { cwd, encoding: 'utf-8', stdio: 'pipe' });
+    return { pass: true, detail: 'ok' };
+  } catch {
+    return { pass: true, detail: 'skipped' };
+  }
+}
+
+module.exports = { run };

package/src/commands/hooks.js

@@ -0,0 +1,84 @@
+// ai-native hooks
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+const { getProjectRoot } = require('../core/config');
+
+function run(args) {
+  const sub = args[0];
+  if (sub === 'status') return statusCmd();
+  if (sub === 'install') return installCmd();
+  console.log('Usage: ai-native hooks [install|status]');
+  process.exit(1);
+}
+
+function statusCmd() {
+  const root = getProjectRoot();
+  const hooksDir = path.join(root, '.ai-native', 'hooks');
+  console.log('[ai-native] Hooks status:\n');
+  ['studybook-reminder.sh', 'paradigm-change-monitor.sh'].forEach(s => {
+    const p = path.join(hooksDir, s);
+    const ok = fs.existsSync(p);
+    console.log(`  ${ok ? '✓' : '✗'} ${s}`);
+    if (ok) {
+      try { execSync(`bash -n "${p}"`, { encoding: 'utf-8' }); console.log('    syntax: OK'); }
+      catch (e) { console.log(`    syntax: ERROR`); }
+    }
+  });
+}
+
+function installCmd() {
+  const root = getProjectRoot();
+  const hooksDir = path.join(root, '.ai-native', 'hooks');
+  if (!fs.existsSync(hooksDir)) fs.mkdirSync(hooksDir, { recursive: true });
+
+  const scripts = {
+    'studybook-reminder.sh': `#!/usr/bin/env bash
+REPO="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
+MARKER="/tmp/.ai-native-last-reminder"
+COOLDOWN=1200
+if [ -f "$MARKER" ]; then
+  last=$(cat "$MARKER" 2>/dev/null || echo 0)
+  now=$(date +%s)
+  if (( now - last < COOLDOWN )); then exit 0; fi
+fi
+if ! git -C "$REPO" status --porcelain 2>/dev/null | grep -q .; then exit 0; fi
+date +%s > "$MARKER"
+echo ""
+echo "[AI Native] 本次话题需要复盘。回复 y 由 AI 完成，n 跳过（下次合并）"
+echo ""
+`,
+    'paradigm-change-monitor.sh': `#!/usr/bin/env bash
+REPO="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
+INPUT=$(cat)
+[ -z "$INPUT" ] && exit 0
+CMD=$(echo "$INPUT" | python3 -c "import sys,json;print(json.load(sys.stdin).get('tool_input',{}).get('command',''))" 2>/dev/null)
+echo "$CMD" | grep -qE 'git\\s+(-C\\s+\\S+\\s+)?commit' || exit 0
+CHANGED=$(git -C "$REPO" log -1 --name-only --format="" 2>/dev/null)
+[ -z "$CHANGED" ] && exit 0
+MATCHED=""
+while IFS= read -r f; do
+  for p in "docs/architecture/" "design/" "docs/decisions/" ".github/workflows/"; do
+    [[ "$f" == "$p"* ]] && MATCHED="$MATCHED\\n  - $f" && break
+  done
+done <<< "$CHANGED"
+[ -z "$MATCHED" ] && exit 0
+echo ""
+echo "[AI Native 范式变更] 本次 commit 包含范式文件更新"
+echo -e "  变更文件：$MATCHED"
+echo "  建议：运行 ai-native sync"
+echo ""
+`
+  };
+
+  for (const [name, content] of Object.entries(scripts)) {
+    const p = path.join(hooksDir, name);
+    fs.writeFileSync(p, content);
+    fs.chmodSync(p, 0o755);
+    console.log(`  ✓ ${name}`);
+  }
+  console.log('[ai-native] Hooks installed');
+}
+
+module.exports = { run };

package/src/commands/init.js

@@ -0,0 +1,62 @@
+// ai-native init
+
+const fs = require('fs');
+const path = require('path');
+
+const VALID_STACKS = ['react-spa', 'nextjs', 'vue', 'backend-go', 'backend-python'];
+
+function run(args) {
+  const idx = args.indexOf('--stack');
+  const stack = idx >= 0 ? args[idx + 1] : 'react-spa';
+
+  if (!VALID_STACKS.includes(stack)) {
+    console.error(`Invalid stack: ${stack}. Valid: ${VALID_STACKS.join(', ')}`);
+    process.exit(1);
+  }
+
+  const root = process.cwd();
+  const dirs = [
+    '.ai-native/memory', '.ai-native/hooks', '.ai-native/reports',
+    'docs/.ai-native/memory', 'docs/decisions'
+  ];
+
+  console.log(`[ai-native] Initializing with stack: ${stack}\n`);
+
+  dirs.forEach(d => {
+    const full = path.join(root, d);
+    if (!fs.existsSync(full)) {
+      fs.mkdirSync(full, { recursive: true });
+      console.log(`  created: ${d}`);
+    }
+  });
+
+  // Copy config
+  const copyFile = (srcRel, dstRel, transform) => {
+    const src = path.join(__dirname, '..', '..', srcRel);
+    const dst = path.join(root, dstRel);
+    if (fs.existsSync(dst)) { console.log(`  exists: ${dstRel} (skipped)`); return; }
+    if (!fs.existsSync(src)) return;
+    let content = fs.readFileSync(src, 'utf-8');
+    if (transform) content = transform(content);
+    fs.writeFileSync(dst, content);
+    console.log(`  created: ${dstRel}`);
+  };
+
+  copyFile('config/ai-native.config.toml', '.ai-native/config.toml',
+    c => c.replace(/adapter = "react-spa"/, `adapter = "${stack}"`));
+  copyFile('config/acceptance.yaml', '.ai-native/acceptance.yaml');
+  copyFile('config/memory-manifest.yaml', '.ai-native/memory/MANIFEST.yaml');
+
+  const selfUpdate = path.join(root, 'docs', 'self-update.md');
+  if (!fs.existsSync(selfUpdate)) {
+    fs.writeFileSync(selfUpdate, '# AI Native 范式变更日志\n\n记录范式文件的系统性变更。\n每次范式变更检测后由 AI 追加。\n\n---\n');
+    console.log('  created: docs/self-update.md');
+  }
+
+  console.log('\n[ai-native] Done. Next:');
+  console.log('  1. Edit .ai-native/config.toml');
+  console.log('  2. Run ai-native sync');
+  console.log('  3. Run ai-native hooks install');
+}
+
+module.exports = { run };

package/src/commands/sync.js

@@ -0,0 +1,119 @@
+// ai-native sync
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+const { getProjectRoot, loadConfig, loadManifest } = require('../core/config');
+const { loadAdapterRules } = require('../core/adapter');
+
+function run(args) {
+  const isCheck = args.includes('--check');
+  const isForce = args.includes('--force');
+  const isDryRun = args.includes('--dry-run');
+  const fi = args.indexOf('--factor');
+  const targetFactor = fi >= 0 ? args[fi + 1] : null;
+
+  const root = getProjectRoot();
+  const config = loadConfig(root);
+  const manifest = loadManifest(root);
+  const memoryDir = path.join(root, '.ai-native', 'memory');
+  const syncStatePath = path.join(memoryDir, 'SYNC-STATE.md');
+  const watchPaths = config.paradigm?.watch_paths || [];
+
+  // Get current hash
+  let currentHash = 'unknown';
+  try {
+    currentHash = execSync(`git -C "${root}" log -1 --format=%H -- ${watchPaths.join(' ')}`, { encoding: 'utf-8' }).trim();
+  } catch { currentHash = 'no-git'; }
+
+  // Check if update needed
+  if (!isForce && fs.existsSync(syncStatePath)) {
+    const state = fs.readFileSync(syncStatePath, 'utf-8');
+    const m = state.match(/Git hash.*?([0-9a-f]{10,40})/i);
+    if (m && m[1].startsWith(currentHash.substring(0, 10))) {
+      console.log(`[ai-native] 记忆已是最新 (${currentHash.substring(0, 8)})`);
+      if (isCheck) process.exit(0);
+      return;
+    }
+  }
+
+  if (isCheck) {
+    console.log(`[ai-native] 需要更新 (${currentHash.substring(0, 8)})`);
+    process.exit(1);
+  }
+
+  if (isDryRun) {
+    const factors = targetFactor ? manifest.factors.filter(f => f.name === targetFactor) : manifest.factors;
+    console.log(`[ai-native] DRY RUN — ${factors.length} factors:`);
+    factors.forEach(f => console.log(`  - ${f.name}`));
+    return;
+  }
+
+  // Load adapter rules
+  const builtin = loadAdapterRules(config.stack?.adapter || 'react-spa');
+
+  // Process
+  const factors = targetFactor ? manifest.factors.filter(f => f.name === targetFactor) : manifest.factors;
+  if (!fs.existsSync(memoryDir)) fs.mkdirSync(memoryDir, { recursive: true });
+
+  const synced = [];
+
+  for (const factor of factors) {
+    const builtinContent = builtin[factor.name] || '';
+    const content = buildFactor(factor, builtinContent, currentHash);
+    const out = path.join(memoryDir, factor.output_file);
+    fs.writeFileSync(out, content);
+    console.log(`[ai-native] ${factor.name} → ${factor.output_file}`);
+    synced.push(factor.name);
+  }
+
+  // SYNC-STATE
+  const now = new Date().toISOString();
+  fs.writeFileSync(syncStatePath, `---
+name: sync-state
+description: 资产记忆同步元数据
+metadata:
+  type: reference
+---
+
+# Asset Memory Sync State
+
+- **Synced at**: ${now}
+- **Git hash**: ${currentHash}
+- **Monitored paths**: ${watchPaths.join(', ')}
+- **Factors synced**: ${synced.join(', ')}
+`);
+
+  // Copy-back
+  const tmplDir = path.join(root, 'docs', '.ai-native', 'memory');
+  if (!fs.existsSync(tmplDir)) fs.mkdirSync(tmplDir, { recursive: true });
+  for (const f of factors) {
+    const s = path.join(memoryDir, f.output_file);
+    const d = path.join(tmplDir, f.output_file);
+    if (fs.existsSync(s)) fs.copyFileSync(s, d);
+  }
+  fs.copyFileSync(syncStatePath, path.join(tmplDir, 'SYNC-STATE.md'));
+
+  console.log(`[ai-native] Done. hash: ${currentHash.substring(0, 8)}`);
+}
+
+function buildFactor(factor, builtinContent, hash) {
+  const now = new Date().toISOString();
+  const title = factor.output_file.replace('.md', '').replace(/-/g, ' ').replace(/\b\w/g, c => c.toUpperCase());
+
+  return `---
+name: ${factor.name}
+description: ${factor.description}
+metadata:
+  type: project
+  synced-from: ${hash}
+  synced-at: ${now}
+  source-files: []
+---
+
+# ${title}
+${builtinContent || '\n- (蒸馏引擎将在完整实现中从源文件提取因子)\n'}
+`;
+}
+
+module.exports = { run };

package/src/core/adapter.js

@@ -0,0 +1,32 @@
+// ai-native core — adapter loader
+
+const fs = require('fs');
+const path = require('path');
+
+function loadAdapterRules(adapterName) {
+  const rules = {};
+
+  // Try loading from npm package first, then from local adapters/
+  const adapterDir = path.join(__dirname, '..', '..', 'adapters', adapterName);
+  const immutablePath = path.join(adapterDir, 'immutable-rules.md');
+
+  if (fs.existsSync(immutablePath)) {
+    const content = fs.readFileSync(immutablePath, 'utf-8');
+    // Parse sections: each ## heading becomes a rule group, each "- " line is a rule
+    const sections = content.split('\n## ');
+    for (const section of sections) {
+      if (!section.trim()) continue;
+      const lines = section.split('\n');
+      const heading = lines[0]?.replace(/^## /, '').trim();
+      if (heading && heading.includes('不可变')) {
+        // This is a forbidden-patterns section
+        rules['forbidden-patterns'] = (rules['forbidden-patterns'] || '') +
+          '\n' + lines.filter(l => l.startsWith('- ')).join('\n');
+      }
+    }
+  }
+
+  return rules;
+}
+
+module.exports = { loadAdapterRules };

package/src/core/config.js

@@ -0,0 +1,137 @@
+// ai-native core — config reader
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+function getProjectRoot() {
+  try {
+    return execSync('git rev-parse --show-toplevel', { encoding: 'utf-8' }).trim();
+  } catch {
+    return process.cwd();
+  }
+}
+
+function loadConfig(projectRoot) {
+  const configPath = path.join(projectRoot, '.ai-native', 'config.toml');
+  if (!fs.existsSync(configPath)) {
+    return getDefaultConfig();
+  }
+  return parseSimpleToml(fs.readFileSync(configPath, 'utf-8'));
+}
+
+function getDefaultConfig() {
+  return {
+    project: { name: 'unknown', type: 'frontend' },
+    stack: { adapter: 'react-spa', package_manager: 'pnpm' },
+    paradigm: { watch_paths: [] },
+    hooks: { enabled: true, reminder_cooldown_sec: 1200 },
+    sdd: { enforced: true },
+    onboarding: { demo_enabled: false },
+    distiller: { manifest: '.ai-native/memory/MANIFEST.yaml', output_dir: '.ai-native/memory/' },
+  };
+}
+
+function parseSimpleToml(content) {
+  const config = getDefaultConfig();
+  const lines = content.split('\n');
+  let currentSection = null;
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+
+    const sectionMatch = trimmed.match(/^\[(.+?)\]/);
+    if (sectionMatch) {
+      currentSection = sectionMatch[1];
+      continue;
+    }
+
+    const kvMatch = trimmed.match(/^(\S+)\s*=\s*(.+)/);
+    if (kvMatch && currentSection) {
+      const key = kvMatch[1];
+      let value = kvMatch[2].trim();
+
+      if (value === 'true') value = true;
+      else if (value === 'false') value = false;
+      else if (/^\d+$/.test(value)) value = parseInt(value);
+      else if (value.startsWith('"') && value.endsWith('"')) value = value.slice(1, -1);
+      else if (value.startsWith('[')) {
+        try { value = JSON.parse(value); } catch { value = [value]; }
+      }
+
+      const parts = currentSection.split('.');
+      let obj = config;
+      for (const part of parts) {
+        if (!obj[part]) obj[part] = {};
+        obj = obj[part];
+      }
+      if (Array.isArray(obj)) {
+        obj.push(value);
+      } else {
+        obj[key] = value;
+      }
+    }
+  }
+  return config;
+}
+
+function loadManifest(projectRoot) {
+  const config = loadConfig(projectRoot);
+  const manifestPath = path.join(projectRoot, config.distiller?.manifest || '.ai-native/memory/MANIFEST.yaml');
+  if (!fs.existsSync(manifestPath)) {
+    return { factors: [] };
+  }
+  const content = fs.readFileSync(manifestPath, 'utf-8');
+  return parseSimpleYaml(content);
+}
+
+function parseSimpleYaml(content) {
+  const result = { factors: [] };
+  const lines = content.split('\n');
+  let inFactors = false;
+  let currentFactor = null;
+  let inBuiltinSources = false;
+  let collectingList = null;
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+
+    if (trimmed === 'factors:') { inFactors = true; continue; }
+
+    if (inFactors) {
+      if (trimmed.startsWith('- name:')) {
+        if (currentFactor) result.factors.push(currentFactor);
+        currentFactor = { name: trimmed.replace('- name:', '').trim(), source_globs: [], builtin_sources: [] };
+        collectingList = null;
+        inBuiltinSources = false;
+      } else if (currentFactor) {
+        if (trimmed.startsWith('source_globs:')) {
+          collectingList = 'source_globs';
+          const value = trimmed.replace('source_globs:', '').trim();
+          if (value && value !== '[]') currentFactor.source_globs.push(value.replace(/^- /, '').replace(/"/g, ''));
+        } else if (trimmed.startsWith('builtin_sources:')) {
+          collectingList = 'builtin_sources';
+          inBuiltinSources = true;
+          const value = trimmed.replace('builtin_sources:', '').trim();
+          if (value && value !== '[]') currentFactor.builtin_sources.push(value.replace(/^- /, '').replace(/"/g, ''));
+        } else if (trimmed.startsWith('- ') && collectingList) {
+          const value = trimmed.replace(/^- /, '').replace(/"/g, '');
+          currentFactor[collectingList].push(value);
+        } else if (trimmed.includes(':')) {
+          const [k, v] = trimmed.split(':').map(s => s.trim());
+          if (k === 'output_file') currentFactor.output_file = v.replace(/"/g, '');
+          else if (k === 'max_items') currentFactor.max_items = parseInt(v);
+          else if (k === 'priority') currentFactor.priority = v;
+          else if (k === 'description') currentFactor.description = v;
+          collectingList = null;
+        }
+      }
+    }
+  }
+  if (currentFactor) result.factors.push(currentFactor);
+  return result;
+}
+
+module.exports = { getProjectRoot, loadConfig, loadManifest };