# PageDesignerMcp

MCP Server 平台 + 多领域 Agent 插件系统，面向天工 aPaaS 平台的 **44 个业务域**。

## 项目初心（最高约束）

> **本项目是能力层，不是 harness。** 为外部 AI 客户端（opencode / Claude Desktop / Cursor 等）提供处理天工 aPaaS 平台业务问题的能力：**工具 + 知识库 + 说明书**，通过 MCP 协议消费。

```
项目   = 能力层（工具 + 知识库 + 说明书）
消费方 = 外部 AI 客户端（AI 在项目之外，是设计不是残缺）
协议   = MCP
价值   = 让任何 AI 客户端都能高效处理天工各业务域的问题
```

**边界约束（所有开发必须遵守）：**
1. **不是 Agent 运行时 / harness** — 不做 LLM 接入、决策循环、上下文管理、运行时编排 DSL、运行时持久化
2. **决策权在外部** — 编排是外部 AI 客户端的事，本项目不做自动编排
3. **能力优先** — 新增能力（工具/知识/说明书）优先于运行时机制建设
4. **契约稳定** — Domain Contract / VCSClient 接口一旦发布，只增不减，保证外部 AI 客户端持续可用

## 架构

```
opencode.json
  └── domains/AGENTS.md          ← 主路由（唯一入口）
        ├── page/                ← 页面设计器
        ├── report/              ← 报表
        ├── saas/                ← SaaS 多租户
        ├── flow/                ← 流程
        ├── approval/            ← 审批
        ├── ...                  ← 共 44 个业务域
        └── databack-rt/         ← 数据回写运行时
```

每个域包含：`index.js`（工具）、`AGENTS.md`（行为）、`knowledge/`（知识库）

平台结构：`src/core/`（加载机制：注册表/加载器/工厂）+ `src/tools/`（平台内置工具）+ `shared-skills/`（跨域技能包）+ `config/`（域配置与技能注册）。新增能力见 ARCHITECTURE.md §2.3 决策树。

## 快速启动

```bash
npm install
node src/index.js
```

### 环境变量（集中凭据，`.env` 文件，已被 gitignore）

复制 `.env.example` 为 `.env` 并填入真实值。所有凭据集中在此：

| 变量 | 用途 | 必选 |
|------|------|------|
| `GITLAB_TOKEN` | GitLab 代码搜索/诊断 | ✅ |
| `GITLAB_URL` | GitLab 实例地址 | 可选 |
| `ARCHERY_USERNAME` / `ARCHERY_PASSWORD` | 数据库查询（shared_db_query） | 用 db_query 时 |
| `SSO_USERNAME` / `SSO_PASSWORD` | 阿里云日志查询（shared_aliyun_query_log） | 用日志查询时 |

> ⚠️ **内网技能需先连接公司 VPN**：Archery / 阿里云 SLS 均为内网服务，未连 VPN 会报 `ERR_NAME_NOT_RESOLVED` 或卡在连接。

> 📄 完整凭据清单、读取优先级、换机步骤见 **[docs/credentials.md](docs/credentials.md)**。

## 脚本

| 命令 | 说明 |
|------|------|
| `npm start` | 启动 MCP Server |
| `npm test` | 运行测试 |
| `npm run create-domain <name>` | 创建新领域脚手架 |

## 文档

- **[ARCHITECTURE.md](ARCHITECTURE.md)** — 完整架构设计
- **`domains/AGENTS.md`** — 主路由表（44 域）
- **`domains/page/knowledge/README.md`** — 知识库导航（315 篇）