# 06 — Features: Teddy

> Tài liệu **mô tả tính năng đã ship** trong Teddy (plugin hiện tại). Không phải roadmap hay kiến trúc — nếu muốn biết “sắp có gì”, xem `04-roadmap-prompt.md`. Nếu muốn biết “code nằm đâu”, xem `02` và `docs/modules/`.

**Phiên bản tài liệu:** GA / v1.x  
**Đối tượng:** chủ site, content writer, developer, QA.

---

## 1. Teddy là gì?

Teddy là lớp AI vận hành trên WordPress: hiểu yêu cầu bằng ngôn ngữ tự nhiên, chọn **tool** an toàn, thực thi (hoặc yêu cầu duyệt), rồi giải thích kết quả.

Teddy **không** lưu API key của OpenAI/Anthropic trong Settings. Provider đi qua **WordPress AI Client** + Connectors (cài riêng trên site).

Teddy **không** chỉ là chat box: có Copilot admin, widget khách, SEO/Writer, Woo tools, RAG, workflow, audit/security, và Extension SDK.

---

## 2. Đủ so với tài liệu Vision / Roadmap chưa?

| Mốc | Trạng thái |
|-----|------------|
| Roadmap **v0.1 → v1.0** (exit criteria trong `04`) | **Đạt** theo checklist đã tick |
| Vision “Jarvis đầy đủ” (mọi tool admin, mọi knowledge source, agency fleet…) | **Chưa** — nhiều ý chỉ hướng dài hạn |
| Enterprise / **v2.0+** (multisite fleet, vector DB ngoài, SSO/SIEM…) | **Chưa ship** — chỉ định hướng |

**Tóm lại:** đủ cho GA theo roadmap; chưa phủ hết mọi ví dụ trong Vision. Các tính năng “nặng” (RAG, Agent Pipeline, Workflows, SDK) **đã có code** nhưng **tắt mặc định** — bật trong Settings / Getting Started.

---

## 3. Nhanh theo nhóm người dùng

### Website Owner / Admin

| Tính năng | Mô tả ngắn | Bật mặc định? |
|-----------|------------|----------------|
| **Getting Started** | Wizard ~5 phút: backup, AI Client, provider, Copilot, RAG, widget, SEO draft | Có (menu ẩn sau khi dismiss) |
| **Teddy Copilot** | Chat trong wp-admin, dùng tool site / Woo / SEO | Có (`enable_admin_copilot`) |
| **Settings** | Provider preference, model, streaming, rate limit, feature flags | Có |
| **Comment moderation** | Giữ bình luận khách, phân tích AI nền, approve/spam | Không (`enable_comment_moderation`) |
| **Suggest Reply** | Gợi ý trả lời bình luận trong admin | Có (`enable_comment_suggest_reply`) |
| **Observability** | Audit log tool + AI usage (token/cost ước lượng, latency) | Khi bật Agent Pipeline |
| **Security** | Checklist tự kiểm + policy tool nguy hiểm / duyệt | Khi bật Agent Pipeline |
| **Workflows** | Chạy / resume luồng nhiều bước (vd Publish Product) | Không (`enable_workflows`) |

### Content Writer / SEO

| Tính năng | Mô tả ngắn | Bật mặc định? |
|-----------|------------|----------------|
| **SEO assistant** (block editor) | Meta, audit; adapters Yoast / Rank Math / AIOSEO / core | Có |
| **Content Classification** (block editor) | Gợi ý category/tag **có sẵn** từ nội dung bài | Có (`enable_content_classification`) |
| **Tool `seo.article.write`** | Sinh bài SEO (draft + FAQ JSON-LD khi áp dụng) | Có (SEO on) |
| **Teddy Writer** | Preview / generate / revise nội dung bài | Có (`enable_bean_writer`) |
| Onboarding “viết 1 bài SEO” | Hướng dẫn draft đầu tiên | Có trong Getting Started |

### Khách truy cập / Support

| Tính năng | Mô tả ngắn | Bật mặc định? |
|-----------|------------|----------------|
| **Widget chat** nổi trên frontend | Trả lời hỗ trợ | Có (`enable_support_chatbot`) |
| Shortcode `[teddy_chat]` / block Gutenberg | Nhúng chat | Có (cùng flag) |
| **Facebook Messenger** | Khách nhắn Page → Teddy (cùng RAG/public chat) | Không (`enable_facebook_messenger`) — cần Meta App + webhook |
| **RAG + citations** | Trả lời theo nội dung site, có `sources` URL | Không (`enable_rag`) — cần embedding + reindex |
| Tool công khai | Chỉ đọc (thống kê / tìm sản phẩm / …), không ghi | Luôn trong phạm vi public |

### Developer

| Tính năng | Mô tả ngắn | Bật mặc định? |
|-----------|------------|----------------|
| **Extension SDK** | `register_tool/workflow/prompt/resource/ai_action` | Không (`enable_extension_sdk`) |
| **Dev tools** | Scaffold CPT / taxonomy / REST (sinh code, không tự chạy code chưa review) | Cùng SDK |
| REST `teddy/v1` | Chat, tools, workflows, knowledge, onboarding, security… | Có (cap/nonce) |
| Demo extension | `examples/demo-extension/` + `docs/EXTENSION_GUIDE.md` | — |

---

## 4. Catalog tính năng chi tiết

### 4.1 Copilot & Chat

- **Admin Copilot** (`Teddy → Teddy Copilot`): hội thoại streaming (SSE), nhớ ngữ cảnh theo `memory_length`.
- Hai chế độ backend:
  - **Legacy** (mặc định): Abilities / tool legacy.
  - **Agent Pipeline** (`use_agent_pipeline`): Understand → Plan → Tools → Summarize, có audit + explainability (“Why this answer”).
- **Public chat**: widget / shortcode / block; rate limit theo Settings.

### 4.2 Tool System

Chuỗi sống: validate → permission → dry-run (nếu nguy hiểm) → approve → execute → audit.

**Domain tools (Agent Pipeline):**

| Nhóm | Tools |
|------|--------|
| Manager | `site.briefing`, `content.gaps`, `content.scheduled`, `comment.list`, `comment.set_status`, `ops.recent_changes`, `ai.usage.summary`, `knowledge.status` |
| Posts | `post.create`, `post.update` (incl. schedule/`post_date`), `post.list`, `post.delete` |
| Media | `media.find_missing_alt`, `media.generate_image` |
| System | `system.ping`, `system.backup.status`, `system.backup.run`, `system.clear_cache`, `system.optimize_db`, `system.send_email`, `system.wp_cli` |
| SEO | `seo.meta.generate`, `seo.article.write`, `seo.article.audit` |
| WooCommerce | `wc.product.list`, `wc.product.update_price`, `wc.product.related`, `wc.product.low_stock`, `wc.product.find_missing_images`, `wc.product.list_expired_promotions`, `wc.product.clear_expired_sales`, `wc.report.revenue`, `wc.order.list`, `wc.order.status` |
| Developer | `dev.cpt.create`, `dev.taxonomy.create`, `dev.rest_endpoint.create` (cần SDK) |

Playbooks: [docs/playbooks/](playbooks/). MCP + OpenClaw: [modules/mcp-bridge/](modules/mcp-bridge/).

**Legacy tools** (chat không Agent): site statistics, search posts/products/docs/users, categories, related/low-stock/orders…

Hành động nguy hiểm bắt buộc preview + `approval_token` (không bypass qua REST).

### 4.3 Knowledge / RAG

Khi `enable_rag`:

1. Index **Posts, Pages**, extra public CPT (`rag_indexable_post_types` / filter `teddy_indexable_post_types`), **Products**, and **PDF/CSV uploads** (chunk → embedding → lưu MySQL).
2. Cron cursor (`teddy_rag_ingest_cursor`) batch ~25; phases: content types → products → uploads; filters `teddy_indexable_products`, `teddy_indexable_posts`, `teddy_indexable_upload_mimes`.
3. `search` / `augment` đưa context vào prompt; chat trả `sources`.
4. ACF (`get_fields`) và Elementor (`_elementor_data`) được gộp vào text index khi plugin active.
5. Admin: panel Knowledge trên Settings + REST `GET/POST .../knowledge/status|reindex|ingest`.

Cần connector/embeddings khả dụng (hoặc filter `teddy_generate_embeddings`).

### 4.4 Workflow Engine

Khi `enable_workflows`:

- Định nghĩa workflow, persist từng bước, **resume** đúng bước fail (không bỏ bước đã success).
- Mẫu **`publish_product`**: validate → mô tả → SEO → apply → ensure image (brief + hook) → translation draft (nếu `target_language`) → publish → notify (`notify_email` tùy chọn).
- Queue: Action Scheduler nếu có, không thì WP-Cron.
- UI: `Teddy → Workflows` + REST `/workflows*`.

Hooks mở rộng ảnh: `teddy_workflow_generate_product_image`, `teddy_workflow_need_product_image` (mặc định Teddy thử AI image qua WP AI Client, fallback PNG placeholder GD).

### 4.5 SEO, Writer & Classification

- Panel SEO trong editor; ghi meta qua adapter SEO plugin hoặc fallback core.
- **Content Classification**: sidebar gợi ý category/tag có sẵn; Apply ghi vào draft qua editor store.
- `seo.article.write`: Markdown→HTML, meta SEO, FAQ schema (`_teddy_faq_schema` + `wp_head`).
- Writer REST: preview / generate / revise / content.

### 4.5b Comments

- **Moderation** (tắt mặc định): bình luận khách được giữ `hold`, job nền phân tích toxicity/sentiment → approve/hold/spam; metadata `_teddy_moderation`.
- **Suggest Reply**: action trên Comments + Dashboard activity; REST trả bản nháp, admin tự gửi.
- REST: `POST /teddy/v1/comments/suggest-reply`, `POST /teddy/v1/classify`.

### 4.6 WooCommerce

Khi Woo active + `enable_woocommerce`:

- Tool list / giá / related / low stock / orders.
- Index sản phẩm vào RAG (nếu RAG bật).

### 4.7 Onboarding

Trang **Getting Started**:

- Xác nhận backup.
- Kiểm tra AI Client / connector.
- One-click bật Copilot, RAG, widget, SEO…
- Gợi ý bài SEO đầu tiên.

Sau khi setup xong có thể dismiss (page vẫn đăng ký ẩn để tránh redirect “not allowed”).

### 4.8 Observability & Security

Khi `use_agent_pipeline`:

- **Observability**: audit tool executions, AI usage ước lượng.
- **Security**: `SecurityAuditService` + trang checklist.
- Copilot: Why / How / tools / errors trên UI.

Luôn có: `current_user_can`, rate limit public, option xóa data khi uninstall.

### 4.9 Provider & Streaming

- Preference `provider` / `model` / temperature / max_tokens trong Settings.
- Đổi connector/provider **không** cần deploy code Teddy.
- Streaming bật mặc định (`enable_streaming`).

### 4.10 Memory

- Scope hiện có: **Conversation**, **User** (Temporary trong domain).
- Chưa: Global / Website / Project (Vision dài hạn).

### 4.11 i18n

- Text domain `teddy`.
- UI: **English + Vietnamese** (`languages/`, Jed JSON cho React).

### 4.12 Extension SDK

Khi `enable_extension_sdk`:

```php
add_action( 'teddy_boot', function () {
    register_tool( new MyTool() );
    // register_workflow, register_prompt, register_resource, register_ai_action
} );
```

Tool thứ ba vẫn qua đầy đủ vòng đời an toàn — không có đường tắt. Chi tiết: `EXTENSION_GUIDE.md`.

---

## 5. Bảng Feature flags (Settings)

| Setting key | Mặc định | Ảnh hưởng chính |
|-------------|----------|-----------------|
| `enabled` | ON | Master switch |
| `enable_streaming` | ON | SSE chat |
| `enable_admin_copilot` | ON | Menu Copilot |
| `enable_support_chatbot` | ON | Widget / shortcode / block |
| `enable_facebook_messenger` | OFF | Facebook Page Messenger webhook |
| `enable_seo_assistant` | ON | SEO panel + tools |
| `enable_content_classification` | ON | Classification sidebar |
| `classification_max_suggestions` | 5 | Max terms per taxonomy |
| `enable_comment_moderation` | OFF | Guest hold + async AI moderation |
| `auto_moderate_guest_comments` | ON | Apply hold queue when moderation on |
| `enable_comment_suggest_reply` | ON | Suggest Reply admin action |
| `enable_bean_writer` | ON | Writer |
| `enable_woocommerce` | ON | Woo tools |
| `enable_database_access` | ON | Tool đọc DB legacy (read-only) |
| `enable_rag` | OFF | Knowledge index + grounding |
| `use_agent_pipeline` | OFF | Agent + menu Observability/Security |
| `enable_workflows` | OFF | Engine + menu Workflows |
| `enable_extension_sdk` | OFF | SDK + dev tools |
| `enable_logging` | OFF | Logging bổ sung |
| `delete_data_on_uninstall` | OFF | Xóa bảng/option khi gỡ plugin |

---

## 6. REST API (tóm tắt)

Namespace: **`/wp-json/teddy/v1`**

| Nhóm | Endpoint chính |
|------|----------------|
| Chat | `POST /chat`, `POST /chat/stream` |
| Conversations | `/conversations`, `/messages` |
| Settings | `/settings` |
| Tools | `GET /tools`, `GET /domain-tools`, dry-run/execute |
| Knowledge | `/knowledge/status`, `/knowledge/reindex` |
| Workflows | `/workflows`, `/workflows/{id}`, `.../resume` |
| Onboarding | `/onboarding/status`, `/onboarding/confirm-backup` |
| Security | `/security/audit` |
| Observability | `/audit-log`, `/ai-usage` |
| SEO / Writer | `/seo`, `/writer/*`, `/content` |
| Comments / Classification | `/comments/suggest-reply`, `/classify` |

Auth: cookie + REST nonce (admin). JWT tùy chọn nếu định nghĩa `BEAN_AI_JWT_SECRET`.

**MCP / OpenClaw:** stdio bridge tại `mcp-server/` — map `tools/list` → `GET /domain-tools`, `tools/call` → `POST /tools/{name}/execute`. Wizard cho buyer: `openclaw/` (`teddy-openclaw setup`). Xem [modules/mcp-bridge/openclaw-onboarding.md](modules/mcp-bridge/openclaw-onboarding.md).

---

## 7. Admin menu map

```
Teddy
├── Settings              (luôn)
├── Getting Started       (ẩn menu khi đã dismiss)
├── Teddy Copilot         (enable_admin_copilot)
├── Teddy Writer          (enable_bean_writer)
├── Observability         (use_agent_pipeline)
├── Security              (use_agent_pipeline)
└── Workflows             (enable_workflows)
```

---

## 8. Chưa có / ngoài phạm vi GA

Các mục sau **không** nằm trong GA hiện tại (Vision hoặc Enterprise). Lộ trình chi tiết: **[08-enterprise-roadmap.md](08-enterprise-roadmap.md)**.

- Multisite / Network Admin fleet / agency dashboard trung tâm → **E1 / E4**
- Vector store ngoài (Pinecone, Qdrant…) → **E2**
- Re-ranking / hybrid search nâng cao → **E2**
- Memory Global / Website / Project → **E2+**
- Tool “Jarvis đầy đủ”: email marketing bulk, WP-CLI shell đầy đủ, tạo promotion mới… → dần theo workflows + SDK
- SSO/SAML, xuất audit sang SIEM → **E3**
- Duyệt nhiều cấp (nhiều người approve) → **E3**

**Đã ship trong v1.0.5 / v1.1:** PDF/CSV upload + ingest, ACF/Elementor enrichment, `system.send_email`, `system.wp_cli` (whitelist), `media.generate_image`, AI image native (WP AI Client) với fallback GD placeholder.

---

## 9. Kiểm thử liên quan

| Loại | Lệnh / file |
|------|-------------|
| Unit + Integration | `composer test` |
| Domain coverage gate | `composer test:coverage` |
| PHPStan | `composer phpstan` |
| PHP E2E (WP thật) | `composer test:e2e` / `tests/e2e-all.php` |
| Playwright smoke | `TEDDY_E2E_PASS=… npm run test:e2e:playwright` |

---

## 10. Tài liệu liên quan

| Doc | Nội dung |
|-----|----------|
| [README.md](../README.md) | Cài đặt / build nhanh |
| [01-vision-prompt.md](01-vision-prompt.md) | Triết lý sản phẩm |
| [02-system-architecture-prompt.md](02-system-architecture-prompt.md) | Kiến trúc |
| [03-development-rules-prompt.md](03-development-rules-prompt.md) | Quy tắc code & test |
| [04-roadmap-prompt.md](04-roadmap-prompt.md) | Lộ trình & exit criteria |
| [05-ai-coding-rules.md](05-ai-coding-rules.md) | Quy tắc khi AI sinh code |
| [EXTENSION_GUIDE.md](EXTENSION_GUIDE.md) | Viết extension |
| [modules/](modules/) | Ghi chú từng module |

Index đầy đủ: [README.md](README.md) trong thư mục `docs/`.