# muse-studio 智能体、市场、个人中心实现留痕

## 任务背景

继续执行 `docs/superpowers/plans/2026-05-24-P2-muse-studio.md` 的 P2 用户端搭建任务。接手时，`muse-studio` 已经完成脚手架、基础设施、写作台、作品工作区和知识库工作台；本次重点补齐剩余三个用户端功能域：

- 智能体工作台
- 创作市场
- 个人中心

同时修复当前代码基线的 TypeScript / ESLint 阻断，补齐对应 Hook 测试和页面冒烟验证。

## 已完成内容

### 1. 智能体工作台

新增智能体功能域：

- `src/features/agent/hooks/useAgents.ts`
- `src/features/agent/components/AgentList.tsx`
- `src/features/agent/components/AgentCreateForm.tsx`
- `src/features/agent/components/SlotBindingPanel.tsx`
- `src/features/agent/hooks/useAgents.test.tsx`
- `src/pages/AgentPage.tsx`

实现能力：

- 查询系统默认与用户自建智能体列表。
- 创建用户自建配置型智能体。
- 在沙盒上下文中试用智能体，结果只进入预览，不写作品事实。
- 查询作品开放智能体槽位。
- 执行槽位预检，再消费预检凭证绑定槽位，避免直接写槽位事实。
- 保护节点只读展示，不允许前端发起替换。

对应 Mock API 在 `src/api/mocks/handlers/ai.ts` 中补齐：

- `GET /app-api/muse/agents`
- `POST /app-api/muse/agents`
- `POST /app-api/muse/agents/:agentId/test`
- `GET /app-api/muse/works/:workId/agent-slots`
- `POST /app-api/muse/works/:workId/agent-slots/:slotKey/prechecks`
- `POST /app-api/muse/works/:workId/agent-slots/:slotKey/bind`

### 2. 创作市场

新增市场功能域：

- `src/features/market/hooks/useMarket.ts`
- `src/features/market/components/MarketBrowse.tsx`
- `src/features/market/hooks/useMarket.test.tsx`
- `src/pages/MarketPage.tsx`

实现能力：

- 按作品、智能体、知识库三类资产筛选市场列表。
- 支持关键词搜索。
- 展示分类摘要。
- 获取市场资产授权。
- 安装已授权的智能体或知识库到账户可用资产列表。
- 明确区分“授权获取”和“安装”，不暗示自动绑定作品或写入作品事实。

对应 Mock API 在 `src/api/mocks/handlers/market.ts` 中补齐：

- `GET /app-api/muse/marketplace/assets`
- `GET /app-api/muse/marketplace/categories`
- `GET /app-api/muse/marketplace/assets/:assetId`
- `POST /app-api/muse/marketplace/assets/:assetId/purchase`
- `POST /app-api/muse/marketplace/assets/:assetId/install`

### 3. 个人中心

新增个人中心功能域：

- `src/features/account/hooks/useAccount.ts`
- `src/features/account/components/PersonalCenter.tsx`
- `src/features/account/components/UsageStats.tsx`
- `src/features/account/hooks/useAccount.test.tsx`
- `src/pages/AccountPage.tsx`

实现能力：

- 展示账户资料、账号状态、邮箱和手机号验证状态。
- 支持保存昵称和公开署名。
- 展示账户级 Token 用量、待归属数量、计量异常数量。
- 展示权益、配额和资源使用进度。
- 展示用量归属分布。

对应 Mock API 在 `src/api/mocks/handlers/account.ts` 中补齐：

- `GET /app-api/muse/profile`
- `PATCH /app-api/muse/profile`
- `GET /app-api/muse/account/entitlements`
- `GET /app-api/muse/account/usage`

## 关键工程实践与避坑

### 1. 以当前 OpenAPI 为准，不沿用旧计划里的简化路径

P2 计划中的部分路径仍是早期简化版，例如：

- `/agents/:agentId/slots`
- `/market/assets`
- `/account/profile`

当前真实 OpenAPI 已经演进为：

- `/app-api/muse/agents`
- `/app-api/muse/works/{workId}/agent-slots`
- `/app-api/muse/marketplace/assets`
- `/app-api/muse/profile`
- `/app-api/muse/account/usage`
- `/app-api/muse/account/entitlements`

后续继续 P2 或 P3 时，应优先以 `docs/api-contracts/generated/typescript/*`、`muse-studio/src/types/*` 和当前产品规格为准，不直接照抄旧 plan 路径。

### 2. `exactOptionalPropertyTypes` 下不能显式传 `undefined`

新增测试和 Mock 时多次遇到该问题：

- 可选字段如果值可能是 `undefined`，不要写进对象字面量。
- 需要先构造基础对象，再按条件追加字段。
- 测试中如果字段必填，应先用 `if (!slot) throw new Error(...)` 做显式收窄，再传 `slot.revision`。

典型写法：

```typescript
const dto: AgentCreateDTO = { name: name.trim() };
if (trimmedDescription) {
  dto.description = trimmedDescription;
}
```

### 3. React 新 lint 规则更严格

之前 `MuseEditor` 中使用 `useCallback(debounce(...))` 会触发 React Hooks 静态规则。已调整为 `useMemo(() => debounce(...), deps)`。

组件文件中导出非组件函数也会触发 Fast Refresh 规则，因此将知识库类型守卫移到：

- `src/features/knowledge/utils/typeGuards.ts`

### 4. 市场和智能体必须保持 owner 边界

市场获取授权不等于安装，安装不等于作品绑定。智能体槽位绑定必须先预检，再绑定：

1. 调用 `prechecks` 获取短期 `agentSlotPrecheckId`。
2. 调用 `bind` 消费该凭证。
3. Mock 中会校验槽位 revision，避免直接跳过预检写入槽位。

这符合产品规格中“市场不拥有最终业务事实，目标 owner 空间最终确认”的边界。

## 验证记录

本次收口执行过以下验证：

```bash
pnpm exec tsc -b --pretty false
pnpm exec vitest run
pnpm lint
pnpm build
```

结果：

- TypeScript 编译通过。
- Vitest：7 个测试文件、23 个测试全部通过。
- ESLint：退出码 0；仅 `public/mockServiceWorker.js` 生成文件存在 unused eslint-disable warning。
- Vite build 通过；存在 chunk > 500KB 提示，后续可做路由级 code splitting。

还启动过开发服务器：

```bash
pnpm dev --host 127.0.0.1
```

并使用 Playwright + 本机 Chrome 冒烟访问：

- `http://127.0.0.1:5173/agents`
- `http://127.0.0.1:5173/market`
- `http://127.0.0.1:5173/account`

截图检查结论：

- 页面非空。
- 主要标题、列表、卡片、用量和权益面板可见。
- 未发现明显文字重叠、空白页或加载失败状态。

## 后续建议

1. 如果继续 P2，可补 Playwright E2E 用例，覆盖作品创建、写作台 AI 生成、智能体试用、市场授权安装、个人资料保存。
2. 当前构建包提示超过 500KB，后续可以按路由拆分 `AgentPage`、`MarketPage`、`AccountPage` 等功能域。
3. `public/mockServiceWorker.js` 的 lint warning 来自生成文件，可通过 ESLint ignore 或生成文件豁免处理，不建议手改生成文件。
4. P2 plan 清单仍未同步真实完成状态，后续可以单独更新计划文档，明确 Feature 3 实际已演进为“知识库列表 + 资料管理”形态，而不是旧版“实体/草稿/图谱”。