@claudelaw/taichu 0.6.0

package/docs/architecture/003-hook-based-extension.md

@@ -0,0 +1,82 @@
+# ADR 003: Hook-Based Extension System
+
+- **Status:** Accepted
+- **Date:** 2026-06-06
+- **Author:** Liu Huai'an
+
+## Context
+
+Taichu needs an extension system that allows both:
+1. Traditional plugin-style functionality (similar to WordPress's `add_action`/`add_filter`)
+2. Agent-native capabilities (agents registering themselves in content pipelines)
+
+The extension model must be simple enough for community contributors, yet powerful enough for complex agent workflows.
+
+## Decision Drivers
+
+1. **Familiarity** — WordPress's hook system is the most successful plugin API in CMS history
+2. **Agent-compatibility** — hooks must support async operations (agents may call external LLMs)
+3. **Determinism** — priority ordering must be predictable
+4. **No global state** — hooks are scoped to a Taichu instance, not global
+
+## Options Considered
+
+### Option A: EventEmitter (Node.js built-in)
+
+Too low-level. No priority ordering. No return value chaining (filter semantics).
+
+### Option B: WordPress-style add_action/add_filter
+
+Proven model. But WordPress uses global state, which doesn't scale to multi-tenant or serverless.
+
+### Option C: Instance-Scoped Lifecycle Hooks (our approach)
+
+Inspired by WordPress but scoped to a Taichu instance. Named lifecycle hooks with priority ordering. Supports both side-effect hooks (action-like) and value-passing hooks (filter-like).
+
+## Decision
+
+**Taichu uses an instance-scoped hook system with WordPress-compatible semantics.**
+
+```js
+const taichu = createTaichu();
+
+// Side-effect hook (action)
+taichu.hooks.on('afterCreate', async (doc, ctx) => {
+  await searchIndex.index(doc);
+});
+
+// Value-passing hook (filter)
+taichu.hooks.on('beforeRender', async (html, ctx) => {
+  return addAnalytics(html);
+}, 5); // priority 5 — runs before default (10)
+```
+
+## Built-in Hooks
+
+| Hook | Type | Payload | When |
+|------|------|---------|------|
+| `beforeCreate` | Filter | `{ type, data, status }` | Before document creation |
+| `afterCreate` | Action | `Document` | After document creation |
+| `beforeUpdate` | Filter | `{ id, type, data, status }` | Before document update |
+| `afterUpdate` | Action | `Document` | After document update |
+| `beforeDelete` | Filter | `{ id, type }` | Before document deletion |
+| `afterDelete` | Action | `{ id, type }` | After document deletion |
+| `beforePublish` | Filter | `Document` | Before status change to published |
+| `afterPublish` | Action | `Document` | After status change to published |
+| `beforeRender` | Filter | `html, ctx` | Before HTML output |
+| `afterRender` | Action | `html, ctx` | After HTML output |
+| `agent:onRequest` | Filter | `payload, ctx` | Agent API request received |
+| `agent:onResponse` | Filter | `response, ctx` | Agent API response prepared |
+
+## Consequences
+
+### Positive
+- WordPress developers will find the API familiar
+- Async support enables agent-in-the-loop workflows
+- Instance scoping prevents multi-tenant conflicts
+- Priority system ensures deterministic execution order
+
+### Negative
+- Not compatible with existing WordPress plugins (different runtime)
+- Hook naming convention must be documented clearly
+- Community needs guidance on "which hook to use" for common tasks

package/docs/architecture/004-api-first-architecture.md

@@ -0,0 +1,122 @@
+# ADR 004: API-First Architecture with MCP
+
+- **Status:** Accepted
+- **Date:** 2026-06-06
+- **Author:** Liu Huai'an
+
+## Context
+
+Taichu must serve three distinct consumers:
+1. **Human authors** — via admin SPA (browser)
+2. **Human readers** — via public frontend (browser, RSS)
+3. **AI agents** — via programmatic API and MCP protocol
+
+A traditional CMS renders HTML server-side and adds a REST API as an afterthought. Taichu must invert this: API is primary, rendering is secondary.
+
+## Decision Drivers
+
+1. **Agent discoverability** — agents should auto-discover Taichu's capabilities
+2. **Multi-channel output** — same content serves web, mobile, RSS, and agents
+3. **Protocol evolution** — API design should accommodate future protocols
+4. **Admin SPA** — the management interface is a client of the API, not server-rendered
+
+## Decision
+
+**Taichu is API-first with three API channels: REST, GraphQL, and MCP.**
+
+```
+Human Author ──→ Admin SPA ──→ REST API ──┐
+                                           │
+Human Reader ──→ Public Site ←── GraphQL ──┤
+                                           │
+AI Agent    ──→ MCP Client ──→ MCP API ───┘
+```
+
+### REST API (Phase 1)
+
+Standard CRUD endpoints for content management:
+- `GET /api/content/:type` — list documents
+- `POST /api/content/:type` — create document
+- `GET /api/content/:type/:id` — get document
+- `PUT /api/content/:type/:id` — update document
+- `DELETE /api/content/:type/:id` — delete document
+
+### GraphQL (Phase 2)
+
+Flexible queries for frontend consumers who need to shape responses.
+
+### MCP Server (Phase 2)
+
+Implements the [Model Context Protocol](https://modelcontextprotocol.io/), allowing AI agents to:
+- Discover Taichu's content types and capabilities
+- Read, create, and update content through standardized tool calls
+- Subscribe to content change notifications
+
+## Why Three Channels?
+
+| Concern | REST | GraphQL | MCP |
+|---------|------|---------|-----|
+| Simplicity | High | Medium | Low (for humans) |
+| Client control | Low | High | N/A (agent-driven) |
+| Agent discoverability | None | Needs GraphQL introspection | Built-in |
+| Caching | HTTP native | Complex | N/A |
+| Use case | Admin CRUD, webhooks | Public frontend, mobile | Agent integration |
+
+## MCP Integration Design
+
+```json
+{
+  "name": "taichu",
+  "tools": [
+    {
+      "name": "list_content",
+      "description": "List documents of a given content type",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "type": { "type": "string", "description": "Content type name" },
+          "status": { "type": "string", "enum": ["draft", "published", "archived"] },
+          "limit": { "type": "number" }
+        }
+      }
+    },
+    {
+      "name": "get_content",
+      "description": "Get a single document by ID",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "id": { "type": "string" }
+        },
+        "required": ["id"]
+      }
+    },
+    {
+      "name": "create_content",
+      "description": "Create a new document",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "type": { "type": "string" },
+          "data": { "type": "object" },
+          "status": { "type": "string" }
+        },
+        "required": ["type", "data"]
+      }
+    }
+  ]
+}
+```
+
+## Consequences
+
+### Positive
+- Agents auto-discover capabilities via MCP — no manual API doc reading
+- Content is genuinely multi-channel — web, RSS, agent are all first-class
+- Admin SPA is decoupled — can evolve independently of the API
+- MCP integration makes Taichu a natural fit for AI agent workflows
+
+### Negative
+- Three API surfaces to maintain and document
+- Breaking changes must be coordinated across all three
+- MCP protocol is still evolving — potential breaking changes upstream

package/docs/architecture/README.md

@@ -0,0 +1,24 @@
+# Architecture Decision Records
+
+This directory contains Architecture Decision Records (ADRs) for Taichu.
+
+## What is an ADR?
+
+An ADR documents a significant architectural decision: the context, the options considered, the chosen approach, and the consequences.
+
+## Index
+
+| # | Title | Status | Date |
+|---|-------|--------|------|
+| [001](001-zero-dependency-core.md) | Zero-Dependency Core Runtime | Accepted | 2026-06-06 |
+| [002](002-structured-content-model.md) | Structured Content Model with JSON-LD | Accepted | 2026-06-06 |
+| [003](003-hook-based-extension.md) | Hook-Based Extension System | Accepted | 2026-06-06 |
+| [004](004-api-first-architecture.md) | API-First Architecture with MCP | Accepted | 2026-06-06 |
+
+## Proposing an ADR
+
+1. Copy `TEMPLATE.md` to `NNN-title-with-dashes.md`
+2. Fill out all sections
+3. Open a PR with the ADR
+4. Discuss and reach consensus
+5. Merge and update the index

package/docs/logo.svg

@@ -0,0 +1,40 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 580 120">
+  <defs>
+    <radialGradient id="sphere-hi" cx="0.36" cy="0.30" r="0.68" fx="0.36" fy="0.30">
+      <stop offset="0%" stop-color="#ffffff" stop-opacity="0.40"/>
+      <stop offset="35%" stop-color="#ffffff" stop-opacity="0.10"/>
+      <stop offset="100%" stop-color="#000000" stop-opacity="0.20"/>
+    </radialGradient>
+    <radialGradient id="rim" cx="0.5" cy="0.5" r="0.5">
+      <stop offset="82%" stop-color="#000000" stop-opacity="0"/>
+      <stop offset="100%" stop-color="#000000" stop-opacity="0.22"/>
+    </radialGradient>
+    <clipPath id="ball-sm">
+      <circle cx="60" cy="60" r="52"/>
+    </clipPath>
+  </defs>
+
+  <!-- Tai Chi ball icon -->
+  <g clip-path="url(#ball-sm)">
+    <circle cx="60" cy="60" r="52" fill="#1E1B4B"/>
+    <path d="M60,8 A52,52 0 0,0 60,112" fill="#EDE9FE"/>
+    <circle cx="60" cy="34" r="26" fill="#EDE9FE"/>
+    <circle cx="60" cy="86" r="26" fill="#1E1B4B"/>
+    <circle cx="60" cy="34" r="8" fill="#1E1B4B"/>
+    <circle cx="60" cy="86" r="8" fill="#EDE9FE"/>
+  </g>
+  <circle cx="60" cy="60" r="52" fill="url(#sphere-hi)"/>
+  <circle cx="60" cy="60" r="52" fill="url(#rim)"/>
+
+  <!-- TAICHU text -->
+  <text x="130" y="52"
+        font-family="'Inter','SF Pro Display','Helvetica Neue',Arial,sans-serif"
+        font-size="42" font-weight="700" letter-spacing="6"
+        fill="#1E1B4B">TAICHU</text>
+
+  <!-- 太初 text -->
+  <text x="130" y="96"
+        font-family="'Noto Serif SC','Source Han Serif SC','SimSun','STSong',serif"
+        font-size="28" font-weight="400" letter-spacing="8"
+        fill="#6D28D9">太初</text>
+</svg>

package/docs/research/ai-era-cms-user-research.md

@@ -0,0 +1,247 @@
+# 用户研究综合报告：AI 时代 CMS 的未来需求
+
+**研究员:** 瑞思 (Reese) | **日期:** 2026-06-07  
+**方法:** 代码架构审计 + 竞品对比分析 + 趋势推演  
+**研究对象:** Taichu CMS v0.2.0（Phase 1 + Phase 2 已完成，Phase 3 规划中）
+
+---
+
+## 执行摘要
+
+Taichu 在"Agent-Native CMS"这个品类中占据先发优势——三通道 API + 双通道认证 + 零依赖核心的组合在市场上独一无二。但当前版本（v0.2.0）仍然是一个**开发者工具**而非**产品**，三类核心用户中只有"AI Agent 开发者"获得了较好的体验。内容创作者面临严重的编辑体验缺失，CTO 在评估时会因缺乏生产级特性（备份、迁移、监控）而犹豫。未来 3-5 年，CMS 将从"网页内容管理"演化为"知识资产管理平台"，Taichu 的结构化内容模型恰好匹配这个方向，但需要在多 Agent 协作、内容血缘追踪、和联邦协议三个维度加速投入。
+
+---
+
+## 1. AI 时代 CMS 用户画像
+
+### 1.1 开发者 / CTO —— 选型决策者
+
+| 维度 | 需求描述 | 痛点 |
+|------|---------|------|
+| **架构评估** | 要求清晰的分层架构、可替换的存储后端、API 优先设计 | 害怕被供应商锁定，要求自托管或可控云部署 |
+| **可扩展性** | 关注插件/扩展系统的成熟度，能否在不修改核心的情况下定制业务逻辑 | Strapi 和 Directus 的插件生态领先 Taichu 2-3 年 |
+| **部署运维** | 期望 Docker 一键部署、CI/CD 集成、健康检查、日志聚合 | Taichu 当前只有 `npm start`，缺乏生产级部署方案 |
+| **性能** | 关注 API 响应时间、数据库查询优化、缓存策略 | sql.js WASM 的性能天花板 vs better-sqlite3 / PostgreSQL |
+| **安全性** | 需要审计日志、API Key 轮换、速率限制、CORS 细粒度控制 | Taichu 的 API Key 无过期机制、无 scope 粒度控制 |
+| **社区生态** | 评估 GitHub stars、贡献者活跃度、文档质量、是否有商业支持 | 目前 Alpha 阶段，社区几乎为零 |
+
+**关键洞察：** CTO 会用"5 分钟快速启动"来验证 Taichu，但用"能否在生产环境跑 3 年"来做最终决策。Taichu 的零依赖哲学对 CTO 有极强吸引力，但缺乏生产级特性（备份恢复、迁移工具、监控端点）会让他们却步。
+
+**CTO 决策心智模型：**
+```
+git clone && npm start    →  ⭐⭐⭐⭐⭐  （5 分钟愉悦）
+生产部署检查清单          →  ⭐⭐       （缺失 Docker/监控/备份）
+6 个月后扩展需求          →  ⭐⭐       （插件生态空白）
+```
+
+### 1.2 内容创作者 / 编辑 —— 日常使用者
+
+| 维度 | 需求描述 | 当前 Taichu 体验 |
+|------|---------|---------------|
+| **富文本编辑** | 需要所见即所得的编辑器，支持图片插入、格式化、链接 | ❌ 仅支持 textarea + 手动 JSON |
+| **媒体管理** | 上传、浏览、搜索图片/视频/文件，拖拽插入 | ❌ 完全缺失 |
+| **内容预览** | 发布前预览最终效果 | ❌ 无预览功能 |
+| **工作流** | 草稿→审核→发布→归档的状态流转 | ⚠️ 有状态字段但无审核流程 |
+| **协作** | 多人同时编辑、评论、修订历史 | ❌ 完全缺失 |
+| **内容搜索** | 在 Admin 内快速搜索已有内容 | ⚠️ API 有但 Admin UI 无搜索框 |
+| **批量操作** | 批量修改状态、标签、删除 | ❌ 完全缺失 |
+
+**用户原声模拟（基于类似产品反馈模式）：**
+> "我需要在 JSON 里手写文章内容？这比 WordPress 的 Gutenberg 倒退了 15 年。"  
+> "文章写完了，但我看不到它在网站上长什么样，我只能相信它是对的。"
+
+**关键洞察：** 内容创作者是 Taichu 当前最大的体验断层。Admin SPA 目前只是对 API 的 1:1 映射，没有任何编辑体验优化。这会导致一个危险的使用模式：开发者用 Taichu 做后端，但内容编辑者拒绝使用 Admin，转而通过 API 自己搭建编辑界面——Taichu 变成了"没人用的 CMS"。
+
+### 1.3 AI Agent 开发者 —— 新兴核心用户
+
+| 维度 | 需求描述 | 当前 Taichu 体验 |
+|------|---------|---------------|
+| **API 发现** | Agent 能自动发现内容类型和可用操作 | ✅ MCP 协议 + `list_content_types` 工具 |
+| **结构化读写** | 通过 API 精确读取和写入结构化内容字段 | ✅ REST + GraphQL + MCP 三通道 |
+| **权限控制** | 每个 Agent 有独立的、可限制的 API Key | ⚠️ 有 API Key 但无 scope 粒度 |
+| **速率限制** | 防止 Agent 失控导致系统过载 | ❌ 文档声称有但代码中未实现 |
+| **审计追踪** | 记录每个 Agent 的操作历史 | ⚠️ 有 `createdBy` 字段但无完整审计日志 |
+| **语义搜索** | Agent 能按语义而非关键词查找内容 | ⚠️ TF-IDF 可用但非真正的语义搜索 |
+| **内容 Pipeline** | Agent 能注册为内容处理器 | ❌ 文档规划但未实现 |
+| **批量操作** | 一次性创建/更新大量文档 | ❌ 仅支持单文档操作 |
+
+**用户原声模拟：**
+> "我可以让 Claude 通过 MCP 直接操作 Taichu 的内容，这太酷了。但我不能限制 Claude 只能写草稿不能发布——这不安全。"  
+> "我让 Agent 批量生成了 500 篇文章，但 Taichu 的 API 一次只能创建一篇，也没有入库前的批量验证。"
+
+**关键洞察：** Agent 开发者是 Taichu 最具差异化的用户群，当前的 MCP 集成是真正的亮点。但"能用"和"敢用"之间还有很大距离——Agent 开发者需要细粒度的权限控制（Agent 只能操作特定内容类型、只能创建草稿、有速率上限），否则无法在生产环境信任 Agent。
+
+---
+
+## 2. 未来 3-5 年 CMS 用户需求趋势
+
+### 2.1 AI Agent 从辅助工具变成内容的一级生产者
+
+**趋势描述：** 到 2028 年，预计 40%+ 的企业内容将由 AI Agent 首次生成（Gartner 预测方向）。Agent 不再只是"帮人类写草稿"，而是独立完成内容生产→发布→优化→归档的全生命周期。
+
+| 用户需求变化 | 对 CMS 的影响 | Taichu 当前适配度 |
+|-------------|-------------|----------------|
+| Agent 需要内容 Schema 的完整机器可读描述 | 每个内容类型必须有 JSON Schema + 语义标注 | ⭐⭐⭐⭐ `toJSONSchema()` + schema.org 映射 |
+| Agent 需要知道"哪些内容被人类审核过" | 需要置信度标记和审核状态追踪 | ⭐⭐ 仅有 draft/published 状态 |
+| Agent 需要获取内容反馈来优化输出 | 需要内容效果追踪（点击率、转化率） | ❌ 完全缺失 |
+| Agent 之间需要内容交接协议 | 需要标准化的内容变更通知 | ⭐ MCP 有基础但无推送/poll 机制 |
+
+### 2.2 多 Agent 协作的内容工作流
+
+**趋势描述：** 未来的内容团队是"1 个人类 + N 个 Agent"——一个 Agent 做研究，一个 Agent 起草，一个 Agent 做 SEO 优化，一个 Agent 做多语言翻译，人类负责审核和决策。
+
+| 用户需求变化 | 对 CMS 的影响 | Taichu 当前适配度 |
+|-------------|-------------|----------------|
+| 内容变更的冲突检测和合并 | 需要 CRDT 或 OT 算法，类似 Git 的 merge | ❌ 最后写入者胜出（Last-Write-Wins） |
+| 工作流引擎 | 内容在多 Agent 之间按 DAG 流转 | ❌ 未实现（Roadmap Phase 2 Todo） |
+| Agent 调度和编排 | 需要内置的任务队列和 Agent 调用管理 | ❌ 完全缺失 |
+| 内容血缘追踪 | 一段内容由哪个 Agent 基于什么数据生成 | ⭐ `createdBy` 字段有存在但无 lineage |
+
+### 2.3 内容从"网页"变成"知识资产"
+
+**趋势描述：** 内容不再只是填充网页的东西。它是向量数据库的输入、是 RAG 的知识源、是 Agent 的决策上下文。CMS 需要管理的是"知识"而不仅是"文档"。
+
+| 用户需求变化 | 对 CMS 的影响 | Taichu 当前适配度 |
+|-------------|-------------|----------------|
+| 内容需要 embedding 向量化 | 内置嵌入生成和向量存储 | ⭐ TF-IDF 有，但非真正 embedding |
+| 内容需要知识图谱连接 | 实体提取、关系建模、语义链接 | ⭐ 有 relation 字段但无图遍历 |
+| 内容需要多模态 | 图片、视频、音频的统一管理 | ❌ 仅有 media 字段类型，无实际媒体处理 |
+| 内容需要可引用和溯源 | 内容块的永久引用（类似 Notion 的 block ID） | ❌ 只有文档级 ID，无块级引用 |
+
+### 2.4 实时协作和联邦式内容网络
+
+**趋势描述：** 未来的 CMS 不是孤立的系统。内容在不同实例之间流动——联邦式网络允许多个组织共享和同步内容，类似 ActivityPub 对社交网络的作用。
+
+| 用户需求变化 | 对 CMS 的影响 | Taichu 当前适配度 |
+|-------------|-------------|----------------|
+| 实时多人编辑 | WebSocket / CRDT 支持的协作编辑 | ❌ 完全缺失 |
+| 跨实例内容同步 | ActivityPub / 自定义联邦协议 | ❌ Roadmap Phase 3 |
+| 内容许可和溯源链 | 内容版权和来源的不可篡改记录 | ❌ 完全缺失 |
+| 去中心化内容发现 | 跨实例搜索和内容推荐 | ❌ 完全缺失 |
+
+---
+
+## 3. Taichu 当前用户体验痛点分析
+
+### 3.1 使用体验会很差的场景
+
+| 场景 | 体验问题 | 严重度 | 受影响用户 |
+|------|---------|--------|-----------|
+| **写一篇博客文章** | 需要手动在 textarea 中编写 JSON，如 `{"text":"段落1","children":[...]}` | 🔴 极高 | 内容创作者 |
+| **上传文章配图** | 完全无法操作——没有媒体库、没有上传端点 | 🔴 极高 | 全部用户 |
+| **多 Agent 同时修改同一文档** | 后写入的覆盖先写入的，无冲突提示 | 🔴 极高 | Agent 开发者 |
+| **搜索已有内容** | Admin UI 没有搜索框，只能逐个内容类型浏览 | 🟡 中高 | 内容创作者 |
+| **从 WordPress 迁移** | 无导入工具、无数据迁移脚本 | 🟡 中高 | CTO / 开发者 |
+| **部署到生产环境** | 只有 `npm start`，无 Docker 镜像、无 systemd 配置 | 🟡 中高 | CTO / 开发者 |
+| **API Key 泄露后** | 无过期机制、无轮换提醒、无吊销 UI | 🟡 中高 | Agent 开发者 |
+| **Schema 变更后迁移旧数据** | 无 migration 系统，旧文档可能不符合新 Schema | 🟡 中 | 开发者 |
+
+### 3.2 让用户放弃 Taichu 的关键能力缺失
+
+1. **媒体管理**（放弃率 ~60%）：任何需要图片/文件的内容型产品，无法使用一个不支持媒体的 CMS。这是"硬阻断"。
+2. **富文本编辑器**（放弃率 ~50%）：非技术内容创作者完全无法使用。面向开发者的 JSON 编辑对编辑团队不可接受。
+3. **生产部署方案**（放弃率 ~40%）：CTO 完成 PoC 后，发现缺少 Docker、监控、备份、日志，转向 Strapi 或 Directus。
+4. **细粒度 Agent 权限**（放弃率 ~35%）：Agent 开发者不敢在生产环境给 Agent 全量 API Key 权限。
+5. **内容版本控制**（放弃率 ~30%）：任何多用户协作场景，没有编辑历史和回滚能力是致命缺陷。
+
+### 3.3 开发者上手 Taichu 的最大障碍
+
+**障碍层级（从入门到精通）：**
+
+```
+Layer 1: 5 分钟启动                    → ✅ 无阻力（git clone && npm start）
+Layer 2: 理解内容模型                  → ⚠️ 需理解 ContentType / Document 概念
+Layer 3: 注册自定义 ContentType        → ⚠️ 需编程定义 Schema，无 Admin UI 配置
+Layer 4: 编写 Hook 扩展                → ⚠️ 需理解 Hook 生命周期和异步模式
+Layer 5: 集成 MCP 到自己的 Agent       → 🔴 需理解 MCP 协议和 stdio transport
+Layer 6: 贡献代码 / 理解架构            → 🔴 零依赖哲学意味着很多轮子是自己造的
+```
+
+**最核心的三个障碍：**
+
+1. **文档缺口**：README 写得很好，但缺乏"从零到上线"的教程。开发者知道 Taichu 是什么，但不知道怎么做第一个真实项目。
+2. **调试体验**：零依赖 HTTP 服务器意味着没有 Express/Koa 的生态工具（如 morgan 日志、helmet 安全头），排查问题依赖原始 `console.log`。
+3. **心智模型转换**：从 WordPress（"一切都是 post"）或 Strapi（"Collection Type + Component"）转到 Taichu（"结构化 Document + Hook Pipeline"），需要重新理解内容建模方式。
+
+---
+
+## 4. 关键用户故事（AI 时代 CMS）
+
+### US-1：Agent 内容生产者
+> 作为 **AI Agent 开发者**，我希望 **Agent 通过 API Key 访问 CMS 时，只能创建草稿而不能直接发布**，以便 **让 Agent 自由生成内容，但保留人类的最终审核权**。
+
+### US-2：多 Agent 协作流水线
+> 作为 **内容团队负责人**，我希望 **定义一个内容流水线（研究 Agent → 撰写 Agent → SEO Agent → 人类审核 → 发布）**，以便 **让多个 Agent 按顺序协作，人类只需在关键节点介入**。
+
+### US-3：语义内容发现
+> 作为 **AI Agent**，我希望 **通过自然语言查询找到相关内容（如"找出所有关于可持续发展的文章"）**，以便 **在生成新内容时能引用已有的相关知识**。
+
+### US-4：人类友好的编辑体验
+> 作为 **内容编辑**，我希望 **使用富文本编辑器撰写文章，所见即所得**，以便 **专注于内容创作而不是学习 JSON 格式**。
+
+### US-5：内容血缘和溯源
+> 作为 **合规官**，我希望 **追踪每段内容是由哪个 Agent、基于什么数据源、在何时生成的**，以便 **满足 AI 生成内容的审计和合规要求**。
+
+### US-6：联邦式内容共享
+> 作为 **多品牌内容运营方**，我希望 **在不同 Taichu 实例之间选择性同步内容**，以便 **主站发布的内容能自动分发到子品牌站点**。
+
+### US-7：一键部署和运维
+> 作为 **CTO / 技术负责人**，我希望 **通过 Docker Compose 一键部署 Taichu，包含自动备份和健康监控**，以便 **在 30 分钟内完成从评估到上线的全过程**。
+
+---
+
+## 5. 优先级建议
+
+基于 **用户价值 × 技术可行性** 矩阵评估：
+
+| 改进方向 | 用户价值 | 技术可行性 | 优先级 | 理由 |
+|---------|---------|-----------|--------|------|
+| **媒体管理系统** | 🔴 极高 | 🟡 中等 | **P0** | 硬阻断问题。文件上传 + 本地存储 + media 字段的完整实现，解锁全部内容类型 |
+| **富文本编辑器集成** | 🔴 极高 | 🟢 高 | **P0** | Admin SPA 嵌入 Tiptap/ProseMirror，将 `json` 字段渲染为 WYSIWYG，编辑体验从 0 到 1 |
+| **Agent 细粒度权限** | 🟡 高 | 🟢 高 | **P0** | API Key 支持 scope（content type 级别 + action 级别 + rate limit），Agent 开发者才敢用 |
+| **Docker 生产部署方案** | 🟡 高 | 🟢 高 | **P1** | Dockerfile + docker-compose.yml + 健康检查端点 + 备份脚本，CTO 评估的底线需求 |
+| **内容版本控制** | 🟡 高 | 🟡 中等 | **P1** | 每次更新创建 version 快照，支持 diff 和回滚。多 Agent 协作的基础设施 |
+
+### 优先级排序逻辑
+
+```
+               高用户价值
+                  │
+     P0: 媒体管理  │  P0: 富文本编辑器
+     P0: Agent权限 │  P1: 内容版本控制
+                  │
+   ───────────────┼────────────────
+                  │
+     P2: 数据迁移  │  P1: Docker部署
+     P2: 审计日志  │  P2: WebSocket
+                  │
+               低用户价值
+
+        低技术可行性 ← → 高技术可行性
+```
+
+**为什么富文本编辑器是 P0 而非"锦上添花"？** 因为 Taichu 定位是 "Humans + AI Agents" 共用 CMS。如果人类创作者无法使用，Taichu 就退化为"Agent-only 内容管道"，失去了"人机协作"这个核心价值主张。
+
+**为什么 Agent 权限优先于内容 Pipeline？** 因为细粒度权限是 Pipeline 的前提——没有权限控制，Pipeline 中的 Agent 都是"超级用户"，这在生产环境不可接受。先解决"谁能做什么"，再解决"按什么顺序做"。
+
+---
+
+## 6. 后续研究建议
+
+1. **开发者体验测试**：招募 5 名从未接触过 Taichu 的 Node.js 开发者，计时从 `git clone` 到创建第一个自定义 ContentType 的时间，记录所有困惑点。
+2. **内容创作者可用性测试**：给 3 名内容编辑当前 Admin SPA，让他们完成"创建并发布一篇包含图片的文章"，观察放弃点和替代策略。
+3. **Agent 开发者访谈**：联系 3-5 名正在使用 MCP 构建 Agent 的开发者，了解他们在实际生产环境中的内容管理痛点和安全顾虑。
+4. **竞品深度对比**：对 Strapi 5、Directus 11、Payload 3.0 做逐功能对比，重点评估它们的 Agent 集成能力和插件生态成熟度。
+5. **生产部署调研**：调查目标用户（独立开发者、小型团队）最常用的部署方式（VPS/Docker/Vercel/Cloudflare），确定部署方案优先级。
+
+---
+
+## 附录 A：研究方法和局限性
+
+- **方法**：基于 Taichu v0.2.0 完整代码库审计（8 个核心源文件 + 3 个 Admin 视图 + MCP 服务器），结合 CMS 行业趋势分析和用户画像建模
+- **局限性**：
+  - 未进行真实用户访谈（基于代码推断的体验问题可能与实际用户行为有差异）
+  - 用户画像基于典型角色建模，非定量调研
+  - 趋势分析基于公开行业报告方向，非原始研究
+  - 放弃率估算基于一般 SaaS 用户体验规律，非 Taichu 特定数据
+- **建议**：本报告的洞察应作为假设，通过真实用户测试和访谈进行验证

package/docs/zh/README.md

@@ -0,0 +1,81 @@
+# Taichu CMS 中文文档
+
+> AI Agent 时代的原生内容基础设施。人类和 Agent 同为内容的第一公民。
+
+[![MIT License](https://img.shields.io/badge/license-MIT-green)](https://github.com/Caludelaw/Taichu/blob/main/LICENSE)
+[![Gitee](https://img.shields.io/badge/Gitee-镜像-red)](https://gitee.com/Caludelaw/Taichu)
+
+## 快速开始
+
+```bash
+git clone https://gitee.com/Caludelaw/Taichu.git  # 国内推荐 Gitee
+# 或: git clone https://github.com/Caludelaw/Taichu.git
+
+cd Taichu
+node packages/server/src/index.js
+# → http://localhost:3120/admin/
+```
+
+## 是什么
+
+Taichu 不是又一个 Headless CMS。它是为 **AI Agent 时代设计的内容基础设施**：
+
+- **三通道 API**：REST + GraphQL + MCP（24 tools），同时为人类和 Agent 服务
+- **Agent 一等公民**：API Key 独立身份、细粒度 scope 权限、WebSocket 实时推送
+- **零依赖核心**：`node packages/server/src/index.js` 即可跑，无需 MySQL/Redis
+- **MIT 开源**：完全免费，自托管，无 vendor lock-in
+
+## 核心能力
+
+| 能力 | 说明 |
+|------|------|
+| 🏗️ 结构化内容模型 | 9 种字段类型、JSON Schema 导出、语义映射(schema.org) |
+| 🔌 三通道 API | REST(20+端点) + GraphQL + **MCP(24 tools)** |
+| 🔐 双通道认证 | JWT(人类) + API Key(Agent)，scope 细粒度权限 |
+| 📝 富文本编辑 | TipTap ProseMirror，14 工具栏，Markdown 快捷输入 |
+| 🔍 向量搜索 | TF-IDF 中文分词，语义级内容发现 |
+| 📡 实时推送 | WebSocket 频道订阅，内容变更即时广播 |
+| 🔗 Webhook | HMAC-SHA256 签名，指数退避重试，事件过滤 |
+| 🧩 插件系统 | taichu.plugin.json manifest，Worker Thread 沙箱 |
+| 🤝 Agent 协作 | 乐观锁冲突检测，5min TTL 编辑会话 |
+| 🖼️ 媒体管理 | 零依赖 multipart 解析，sharp 缩略图，/uploads 静态服务 |
+| 🐳 Docker | 多阶段构建(alpine)，SQLite 持久化卷，健康检查 |
+
+## 对比 WordPress & Strapi
+
+| | Taichu | WordPress | Strapi |
+|---|------|-----------|--------|
+| Agent 原生 | ✅ 设计哲学级 | ❌ 插件附加 | 🟡 MCP 封装层 |
+| MCP Tools | 24 | 通过 Adapter | v5.47 内置（CRUD） |
+| 零依赖启动 | ✅ | ❌ 需 MySQL | ❌ 需数据库 |
+| 向量搜索 | ✅ 内置 | ❌ | ❌ |
+| WebSocket | ✅ 内置 | ❌ | ❌ |
+| 许可证 | MIT | GPL | MIT |
+
+## 文档目录
+
+- [架构决策记录](../architecture/README.md) — 4 篇 ADR，了解"为什么这样设计"
+- [API 文档](../api/README.md) — REST + GraphQL 完整端点说明
+- [部署指南](./deploy.md) — Docker / 阿里云 / 腾讯云
+- [开发指南](./development.md) — 本地开发、插件编写、贡献流程
+- [MCP 接入指南](./mcp.md) — Agent 如何通过 MCP 操控 Taichu
+
+## 社区
+
+- [GitHub Issues](https://github.com/Caludelaw/Taichu/issues) — Bug 报告、功能建议
+- [Gitee Issues](https://gitee.com/Caludelaw/Taichu/issues) — 国内用户反馈入口
+- 微信交流群：添加 wxid_gion 备注"Taichu"
+
+## 兼容中国市场
+
+Taichu 核心保持 MIT 纯净。以下能力通过**独立 Plugin** 提供，按需安装：
+
+| Plugin | 功能 |
+|--------|------|
+| `@taichu/plugin-compliance-cn` | ICP 备案号配置、公安联网备案 |
+| `@taichu/plugin-content-filter` | 敏感词过滤（对接百度/阿里云/腾讯云审核 API） |
+| `@taichu/plugin-auth-providers` | 手机号注册、微信登录、SSO |
+| `@taichu/plugin-wechat-mcp` | 微信公众号/小程序 MCP Tool |
+| `@taichu/llm-providers` | 通义千问 / 文心一言 / DeepSeek / Moonshot |
+
+> 所有合规 Plugin **默认关闭、用户自行启用**，核心代码不包含任何审查逻辑。