内容
# ARASAAC 社会化 MCP 平台
非商业化社会平台，用于准备可访问的带有 ARASAAC 真实图示的材料。包括官方搜索、议程和面板、编辑器、强制人工审核、属性导出、审计和可选的文本 AI 助手。
AI 绝不会生成、模仿或修改图示。它只建议结构和搜索术语；必须由人员选择每个真实的 ARASAAC 候选人、审核材料并在导出前批准。
## 服务
| 服务 | URL | 功能 |
| --- | --- | --- |
| 网页 | <http://localhost:3000> | 手动和 AI 辅助的引导流程 |
| API | <http://localhost:8000/health> | ARASAAC、材料、审核、导出和 AI |
| AI 状态 | <http://localhost:8000/api/ai/status> | 公共可用性和限制 |
| MCP | <http://localhost:8001/mcp/status> | HTTP 状态和允许列表；通过 stdio 的真实 MCP 协议 (`make mcp-stdio`) |
| PostgreSQL | 内部 | 材料持久性和审计 |
## 使用 Docker 启动
要求：带有 Compose v2 的 Docker。完整的 manual 流程在没有密钥的情况下工作。
```bash
make start
```
要停止服务：
```bash
make stop
```
`make start` 构建并在后台启动 web、API、MCP 和 PostgreSQL。如果指示 Docker 未启动，请打开 Docker Desktop 并重新运行。配置可以通过 `docker compose config --quiet` 验证。
图标和插图 Convergencia Serena 位于 `apps/web/assets/`，并在 `npm run build`（和 `npm run dev`）期间复制到 `apps/web/public/convergencia-serena/`。Web 服务的 Docker 镜像在最终容器中包含此 `public/` 文件夹。如果更改资产后 SVG 损坏，请重建 Web 服务：`docker compose up --build -d web`。
PostgreSQL 在执行 `make stop` 时保留材料和审计。要有意删除所有本地数据：
```bash
make reset-data
```
如果需要保留演示材料，请不要使用 `reset-data`。
## 启用 AI 层
集成使用带有结构化输出的 Responses API，密钥仅保存在服务器上。要进行真实 AI 演示：
```bash
cp .env.example .env
```
在本地编辑 `.env`:
```dotenv
AI_PROVIDER=openai
OPENAI_API_KEY=您的本地密钥
OPENAI_MODEL=gpt-5.4-mini
```
然后执行 `make start`。`.env` 被 Git 忽略。不要在截图、问题、材料或日志中粘贴密钥。没有密钥，`/api/ai/status` 将报告功能已禁用，手动流程仍然可用。
选择 `gpt-5.4-mini` 优先考虑延迟和成本，用于结构化任务；可以从环境更改。提供者仅接收确认的通用场景，不接收图示或工具。
在 Web 应用程序中，“使用 AI 提议结构”部分显示服务器状态、加载消息和错误。如果 AI 显示为未配置，启动后，请检查 `.env` 并咨询 <http://localhost:3000/backend/api/ai/status>（内部代理到 API）。
## 本地开发
要求：Python 3.11+、Node.js 20+ 和 npm。
```bash
make setup
make dev-api
make dev-mcp
make dev-web
```
每个 `dev-*` 命令占用一个终端。`make dev-api` 如果存在，会加载 `.env`。
如果环境中没有 `DATABASE_URL`，API 将使用内存存储库（数据不会持久）。为了与 Docker 保持一致，请启动 PostgreSQL 并配置 URL：
```bash
make dev-db # Postgres Docker 在 :5433（避免与本地 Postgres 在 :5432 冲突）
# 将 DATABASE_URL 添加到 .env（参见 .env.example）
```
要运行检查：
```bash
make test
make lint
make typecheck
make openspec-verify
make agent-packs-verify
```
`make agent-packs-verify` 检查生成的软件包（`.cursor/`、`.codex/`、`.claude/` 等）是否与规范源 `.agents/` 同步。在编辑目录或 `.agents/` 中的内容后，使用 `make agent-packs-sync` 重新生成。参见 [docs/agents/multi-ide-agent-packs.md](docs/agents/multi-ide-agent-packs.md)。
`make test` 运行单元覆盖率和所有 Playwright 流程。后端和前端分别应用最低 75% 的阈值。要隔离故障：
```bash
make test-unit
make test-e2e
```
计划和测试用例矩阵位于 [`docs/testing/test-plan-mvp0.md`](docs/testing/test-plan-mvp0.md)。最新记录的结果位于 [`docs/testing/test-report-mvp0.md`](docs/testing/test-report-mvp0.md)。
本地 MCP 服务器使用 **stdio** 传输（完整 MCP 协议）：
```bash
make mcp-stdio
```
在 Docker 中，`mcp` 容器仅公开一个信息性 HTTP 端点 (`/mcp/status`) 和工具允许列表。MCP 客户端（Cursor、Claude Code 等）必须使用 `make mcp-stdio` 或 `arasaac-mcp` 二进制文件连接到 stdio 服务器。
## Obsidian 知识库
文档、OpenSpecs 和规范知识可以与 iCloud 保险库 `ARASAAC_Project` 同步：
```bash
make obsidian-sync
make obsidian-sync-check
make obsidian-hooks-install
```
同步是单向的，从仓库到 Obsidian，不复制秘密或代码，并保留手动笔记。参见 [docs/obsidian/knowledge-sync.md](docs/obsidian/knowledge-sync.md)。
## 约束
- 仅使用从 ARASAAC 获取的真实图示。
- 不通过 AI 生成、模仿或修改图示。
- 不包含姓名、联系信息、诊断或敏感的个人数据。
- 材料不与特定个人绑定。
- 不自动创建、批准或导出。
- 此版本中没有身份验证。
- MCP 中没有任意执行、文件系统或 shell。
约束规则在 [AGENTS.md](AGENTS.md) 中。AI 层在 [openspec/changes/archive/0021-governed-ai-assistant](openspec/changes/archive/0021-governed-ai-assistant) 中指定。
