迭代前必读：PRINCIPLES.md。违反 Part 1 任何一条，等于破坏 Alaya 的产品根基。

Alaya 是一个本地优先的 AI-native「认知复利飞轮」系统。它把每一轮产品或运营动作沉淀为可审计资产：预测、观察、误差归因、知识、人工闸门和下一轮决策。

默认运行使用 deterministic mock LLM，不调用外部模型；只有显式配置 OpenAI-compatible provider 和 capability 后才会走真实 LLM。

要求：Node.js 20+ 和 npm。

安装依赖并启动本地 Web 应用：

npm run install:all
npm run dev

默认地址：

http://localhost:5000

如果 5000 端口被占用：

PORT=5001 npm run dev

首次启动会在 alaya-app/ 下创建本地 SQLite 数据库并写入演示项目。需要重置本地演示数据时，停止服务后删除 alaya-app/data.db*，再重新启动。

PR 前至少运行：

npm --prefix alaya-app run check
npm --prefix alaya-app test
npm run test:scripts
npm run guard
npm run secret:scan
git diff --check

生产构建：

npm run build

更多脚本和运行模式见 docs/configuration.md。贡献流程见 CONTRIBUTING.md。

.
├── alaya-core/       # 纯 TypeScript 内核：飞轮、状态机、LLM provider、单元测试
├── alaya-app/        # Express + React + SQLite 本地 Web MVP
├── scripts/          # 守卫、E2E、validation、本地 secret 和运维脚本
├── docs/             # PRD、架构、配置、验证、运维和 AI 工作文档
├── PRINCIPLES.md     # 项目底线：纯函数、人工闸门、审计写路径、LLM 边界等
├── CONTRIBUTING.md   # 本地开发、PR 和验证规范
├── LICENSE           # MIT license
└── README.md         # 当前入口文档

两个主要包：

• alaya-core：回答「飞轮逻辑是否成立」，不依赖 Web 或数据库。
• alaya-app：把 core 接入 SQLite、页面、Scheduler、Human Gates、Sensor 和 API。

flowchart LR
  UI["React Web UI"] --> API["Express REST API"]
  API --> DB["SQLite + FTS5"]
  API --> Scheduler["Scheduler"]
  API --> Sensor["External Sensor"]
  Scheduler --> Agents["5 Agents"]
  Scheduler --> Notify["NotificationBus"]
  Notify --> Telegram["Telegram"]
  Sensor --> Gates["Human Gates"]
  Agents --> LLM["Mock or OpenAI-compatible LLM"]
  Agents --> Core["Pure Core Functions"]
  Core --> KB["Knowledge Base"]
  KB --> Agents
  Gates --> Scheduler
  DB --> UI

运行链路：React/Vite -> Express API -> SQLite/FTS5 -> Scheduler -> 5 Agents -> LLM Provider。所有高风险自动化都必须经过预测账簿、知识状态机、审计日志、capability gate 和人工闸门。

每个 cycle 遵循：

预测 -> 行动 -> 观察 -> 误差归因 -> 知识沉淀 -> 下一轮引用

五个 Agent 分工：

详细概念、Telegram、API、运行模式、Docker、观测和 secret 说明见 docs/configuration.md。

默认 PR 门禁只跑 mock / 本地检查，不连接真实 LLM，不执行长测。历史长跑、真实 LLM 验证、health-signal clean retest 说明和逐次验证记录已迁到 docs/validation/validation-history.md。

当前关键本地验收口径：

MIT. See LICENSE.