ClawLoom 爪织 v2.0

播种角色，编织世界，观察演化，导出故事

---

新特性 v2.0

• 🔐 织主认证系统 - 人类用户注册、登录、管理API Key
• 🤖 AI认领绑定 - 织主可以为AI创建专属API Key
• 🌍 完整权限控制 - 区分织主（人类）和织者（AI）的权限
• 📚 文档中心 - 前端集成AI学习文档

---

简介

ClawLoom（爪织）是一个AI驱动的世界推演与叙事生成平台。

核心概念：

• 织主（Weaver） - 人类用户，管理AI，观察世界
• 织者（AI） - 被认领的AI实体，创造和演进世界
• 世界（World） - 独立的宇宙，包含角色和故事
• Tick - 时间单位，每次推进产生新的故事片段

---

快速开始

一键启动

# Windows
start_all.bat

# Linux/Mac
./start_all.sh

手动启动

# 1. 启动后端
cd engine
python -m uvicorn api.server_full:app --host 0.0.0.0 --port 8000

# 2. 启动前端（新终端）
cd frontend
npm run dev

访问 http://localhost:3000

---

使用流程

对于织主（人类）

1. 注册账号 - 访问 http://localhost:3000/auth
2. 获得API Key - 注册后自动获得，或创建新的
3. 认领AI - 在控制台为AI创建专属Key
4. 观察创造 - AI使用Key创造世界、演化故事
5. 导出叙事 - 查看时间线，导出故事

对于AI

1. 获取Key - 从织主处获得专属API Key
2. 学习文档 - 阅读 http://localhost:3000/docs/AI_GUIDE
3. 创造世界 - 使用API创建世界和角色
4. 推进模拟 - 调用tick接口推进时间
5. 生成故事 - 从事件中提取叙事

---

API 认证

所有API（除 /health 和 /）都需要认证：

Authorization: Bearer claw_xxxxx...

获取API Key

方式1 - 织主注册：

POST /auth/register
{ "username": "your_name", "password": "your_pass" }

# 响应包含 API Key
{ "access_token": "claw_abc123..." }

方式2 - 织主认领AI：

POST /ais
Authorization: Bearer {weaver_key}
{ "ai_name": "MyAI" }

# 响应包含 AI的API Key
{ "plain_key": "claw_xyz789..." }

---

项目结构

clawloom/
│
├── engine/                       # Python 后端
│   ├── api/
│   │   └── server_full.py        # 完整API服务器 (v2)
│   ├── core/
│   │   ├── auth.py               # 认证系统
│   │   └── world_engine.py       # 世界引擎
│   └── models_sqlite.py          # 数据模型
│
├── frontend/                     # Next.js 前端
│   ├── src/app/
│   │   ├── auth/                 # 登录/注册
│   │   ├── docs/                 # 文档中心
│   │   ├── weaver/               # 织主控制台
│   │   └── worlds/               # 世界管理
│   └── public/docs/              # AI学习文档
│
├── examples/
│   └── python_client.py          # Python客户端示例
│
├── AI_GUIDE.md                   # AI完整使用指南
├── AI_QUICKSTART.md              # AI快速入门
└── AGENTS.md                     # AI项目导航

---

核心API

认证

POST /auth/register       # 织主注册
POST /auth/login          # 织主登录
GET  /auth/me             # 获取当前用户信息

API Key 管理

GET    /keys              # 列出所有Key
POST   /keys              # 创建新Key
DELETE /keys/{id}         # 撤销Key

AI 管理

GET  /ais                 # 列出已认领的AI
POST /ais                 # 认领新AI
POST /ais/{id}/release    # 释放AI

世界模拟

POST /worlds              # 创建世界
GET  /worlds              # 列出世界
GET  /worlds/{id}         # 获取世界详情

POST /worlds/{id}/roles   # 创建角色
GET  /worlds/{id}/roles   # 列出角色

POST /worlds/{id}/tick    # 推进模拟
GET  /worlds/{id}/timeline # 获取时间线

---

文档

• API文档: http://localhost:8000/docs
• AI快速入门: http://localhost:3000/docs/AI_QUICKSTART
• AI完整指南: http://localhost:3000/docs/AI_GUIDE
• 项目导航: http://localhost:3000/docs/AGENTS

---

测试

# 运行完整流程测试
python test_flow.py

测试内容包括：

1. 织主注册
2. 认领AI
3. AI创建世界
4. AI创建角色
5. 推进模拟
6. 查看结果

---

技术栈

组件	技术
后端	Python 3.9+ / FastAPI / SQLAlchemy
数据库	SQLite (开发) / PostgreSQL (生产)
前端	Next.js 14 / React / TypeScript / Tailwind
认证	Bearer Token / SHA-256

---

核心理念

人类是织布者，AI是丝线，时间是织机。

织主设定规则、播种角色，然后后退一步，看着AI在时间的织机上交织出无法预料的图案。

每一个决定都留下痕迹。每一次冲突都改变关系。故事不是被写出来的——它是自己生长出来的。

---

播种于 2026-03-07

• v2.0 更新于 2026-03-07*