996 lines
29 KiB
Markdown
996 lines
29 KiB
Markdown
# Boss 聊天附件、双存储与 AI 处理 Implementation Plan
|
||
|
||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||
|
||
**Goal:** 为 Boss 原生聊天链路补齐图片/视频/文件发送、默认服务器文件存储、可选阿里 OSS、统一附件消息模型、主 Agent 附件分析，以及 Web 端 `我的 > 附件与存储` 简化配置页。
|
||
|
||
**Architecture:** 保持现有 `boss-state.json + Next API + BossApiClient + 原生 Android` 路线，不引入新的数据库或消息队列。服务端新增统一附件存储抽象层，默认走服务器文件存储，可按用户切到阿里 OSS；原生端只与统一上传/下载接口交互，AI 分析统一走主 Agent 任务链。
|
||
|
||
**Tech Stack:** Next.js App Router、TypeScript、Node.js `fs`、阿里云 OSS Node SDK、原生 Android `AppCompatActivity + ActivityResultContracts + HttpURLConnection`、现有 `boss-master-agent` 队列、文件型持久化 `data/boss-state.json`。
|
||
|
||
---
|
||
|
||
## File Structure
|
||
|
||
### 需要新增的主要文件
|
||
|
||
- `src/lib/boss-attachments.ts`
|
||
- 统一附件类型推断、大小阈值判断、文件名清洗、下载响应帮助函数。
|
||
- `src/lib/boss-storage.ts`
|
||
- 定义 `AttachmentStorageProvider` 接口、按用户配置选择 `server_file / aliyun_oss`。
|
||
- `src/lib/boss-storage-server-file.ts`
|
||
- 服务器本地文件存储实现。
|
||
- `src/lib/boss-storage-aliyun-oss.ts`
|
||
- 阿里 OSS 上传、签名 URL、配置校验。
|
||
- `src/app/api/v1/storage/config/route.ts`
|
||
- 当前登录用户的附件与存储配置读取/更新。
|
||
- `src/app/api/v1/storage/config/validate/route.ts`
|
||
- 阿里 OSS 配置有效性验证。
|
||
- `src/app/api/v1/projects/[projectId]/attachments/route.ts`
|
||
- 统一附件上传入口。
|
||
- `src/app/api/v1/attachments/[attachmentId]/download/route.ts`
|
||
- 统一预览/下载入口。
|
||
- `src/app/api/v1/projects/[projectId]/attachments/[attachmentId]/analyze/route.ts`
|
||
- 手动触发附件分析。
|
||
- `src/app/me/storage/page.tsx`
|
||
- Web 端 `我的 > 附件与存储` 页面。
|
||
- `android/app/src/test/java/com/hyzq/boss/AttachmentComposerStateTest.java`
|
||
- 原生附件入口与确认状态单测。
|
||
- `android/app/src/test/java/com/hyzq/boss/BossApiClientAttachmentTest.java`
|
||
- 原生上传/下载/手动分析 API 客户端测试。
|
||
|
||
### 需要修改的主要文件
|
||
|
||
- `src/lib/boss-data.ts`
|
||
- 扩展用户级存储配置、附件消息模型、分析状态、主 Agent 附件任务数据。
|
||
- `src/lib/boss-master-agent.ts`
|
||
- 补 `attachment_analysis` 任务类型、附件摘要结果回写。
|
||
- `src/app/api/v1/projects/[projectId]/messages/route.ts`
|
||
- 保持文本消息主链，但允许附件分析结果回写卡片。
|
||
- `src/lib/boss-projections.ts`
|
||
- 把附件消息和分析状态投影给 Web。
|
||
- `src/components/app-ui.tsx`
|
||
- Web 会话页补附件消息展示和 `我的 > 附件与存储` 入口。
|
||
- `src/app/me/page.tsx`
|
||
- 增加 `附件与存储` 菜单入口。
|
||
- `android/app/src/main/java/com/hyzq/boss/BossApiClient.java`
|
||
- 增加附件上传、下载、手动分析调用。
|
||
- `android/app/src/main/java/com/hyzq/boss/ProjectDetailActivity.java`
|
||
- 增加 `+` 按钮底部抽屉、图片/视频确认、文件发送、附件消息渲染与动作。
|
||
- `android/app/src/main/java/com/hyzq/boss/BossUi.java`
|
||
- 增加附件气泡 / 卡片 UI 构造。
|
||
- `android/app/src/main/res/layout/activity_project_chat.xml`
|
||
- 在输入区增加 `+` 和附件抽屉入口挂点。
|
||
- `android/app/src/main/AndroidManifest.xml`
|
||
- 如需文件打开/下载支持，补 `provider` 和系统选择权限声明。
|
||
- `android/app/build.gradle`
|
||
- 升版本号，必要时引入 Android 附件测试依赖。
|
||
- `README.md`
|
||
- `docs/architecture/current_runtime_and_deploy_status_cn.md`
|
||
- `docs/architecture/api_and_service_inventory_cn.md`
|
||
- `docs/architecture/ai_handoff_index_cn.md`
|
||
|
||
---
|
||
|
||
### Task 1: 扩展服务端数据模型与用户级存储配置
|
||
|
||
**Files:**
|
||
- Modify: `src/lib/boss-data.ts`
|
||
- Test: `src/lib/boss-data.ts`（先用 Node 侧最小读写回归；当前仓库没有单独 Vitest/Jest，先用 API 与状态读写验证）
|
||
|
||
- [ ] **Step 1: 先写 failing test 思路并用最小状态回归脚本表达预期**
|
||
|
||
在终端先确认当前状态模型还没有 `attachment` 和用户级存储配置。先准备一个最小断言脚本草稿，后面实现完成后执行：
|
||
|
||
```bash
|
||
node - <<'EOF'
|
||
const fs = require('node:fs');
|
||
const state = JSON.parse(fs.readFileSync('data/boss-state.json', 'utf8'));
|
||
if (!state.userAttachmentStorageConfigs) {
|
||
console.error('MISSING:userAttachmentStorageConfigs');
|
||
process.exit(1);
|
||
}
|
||
const accountConfig = state.userAttachmentStorageConfigs.find((item) => item.account === '17600003315');
|
||
if (!accountConfig) {
|
||
console.error('MISSING:account storage config');
|
||
process.exit(1);
|
||
}
|
||
console.log('OK');
|
||
EOF
|
||
```
|
||
|
||
- [ ] **Step 2: 运行脚本，确认当前会失败**
|
||
|
||
Run:
|
||
|
||
```bash
|
||
node - <<'EOF'
|
||
const fs = require('node:fs');
|
||
const state = JSON.parse(fs.readFileSync('data/boss-state.json', 'utf8'));
|
||
if (!state.userAttachmentStorageConfigs) {
|
||
console.error('MISSING:userAttachmentStorageConfigs');
|
||
process.exit(1);
|
||
}
|
||
EOF
|
||
```
|
||
|
||
Expected: FAIL，提示 `MISSING:userAttachmentStorageConfigs`。
|
||
|
||
- [ ] **Step 3: 在 `boss-data.ts` 增加附件类型和用户级存储配置模型**
|
||
|
||
把 `MessageKind`、`Message`、用户配置和分析状态补成如下结构：
|
||
|
||
```ts
|
||
export type MessageKind =
|
||
| "text"
|
||
| "voice_intent"
|
||
| "image_intent"
|
||
| "video_intent"
|
||
| "forward_notice"
|
||
| "forward_single"
|
||
| "forward_bundle"
|
||
| "attachment"
|
||
| "analysis_card";
|
||
|
||
export type AttachmentKind = "image" | "video" | "pdf" | "text" | "office" | "binary";
|
||
export type AttachmentStorageBackend = "server_file" | "aliyun_oss";
|
||
export type AttachmentAnalysisState =
|
||
| "not_applicable"
|
||
| "queued_auto"
|
||
| "ready_manual"
|
||
| "processing"
|
||
| "completed"
|
||
| "failed";
|
||
|
||
export interface MessageAttachment {
|
||
attachmentId: string;
|
||
fileName: string;
|
||
mimeType: string;
|
||
fileSizeBytes: number;
|
||
attachmentKind: AttachmentKind;
|
||
storageBackend: AttachmentStorageBackend;
|
||
storagePath: string;
|
||
previewAvailable: boolean;
|
||
uploadedAt: string;
|
||
uploadedBy: string;
|
||
analysisState: AttachmentAnalysisState;
|
||
analysisSummary?: string;
|
||
analysisCardId?: string;
|
||
}
|
||
|
||
export interface UserAttachmentStorageConfig {
|
||
account: string;
|
||
mode: "server_file" | "oss";
|
||
ossProvider?: "aliyun_oss";
|
||
aliyunOss?: {
|
||
enabled: boolean;
|
||
accessKeyId: string;
|
||
accessKeySecretEncrypted: string;
|
||
bucket: string;
|
||
endpoint: string;
|
||
region: string;
|
||
prefix?: string;
|
||
};
|
||
updatedAt: string;
|
||
validatedAt?: string;
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 4: 给默认状态补上 `server_file` 配置和读写 helper**
|
||
|
||
在默认状态初始化处加入：
|
||
|
||
```ts
|
||
userAttachmentStorageConfigs: [
|
||
{
|
||
account: "17600003315",
|
||
mode: "server_file",
|
||
updatedAt: nowIso(),
|
||
},
|
||
],
|
||
```
|
||
|
||
并增加 helper：
|
||
|
||
```ts
|
||
export async function getAttachmentStorageConfig(account: string) {
|
||
const state = await readState();
|
||
return (
|
||
state.userAttachmentStorageConfigs.find((item) => item.account === account) ?? {
|
||
account,
|
||
mode: "server_file" as const,
|
||
updatedAt: nowIso(),
|
||
}
|
||
);
|
||
}
|
||
|
||
export async function upsertAttachmentStorageConfig(config: UserAttachmentStorageConfig) {
|
||
return mutateState((state) => {
|
||
const index = state.userAttachmentStorageConfigs.findIndex((item) => item.account === config.account);
|
||
if (index >= 0) {
|
||
state.userAttachmentStorageConfigs[index] = config;
|
||
} else {
|
||
state.userAttachmentStorageConfigs.push(config);
|
||
}
|
||
return config;
|
||
});
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 5: 运行回归脚本，确认模型已经存在**
|
||
|
||
Run:
|
||
|
||
```bash
|
||
node - <<'EOF'
|
||
const fs = require('node:fs');
|
||
const state = JSON.parse(fs.readFileSync('data/boss-state.json', 'utf8'));
|
||
console.log(Array.isArray(state.userAttachmentStorageConfigs) ? 'OK' : 'FAIL');
|
||
EOF
|
||
```
|
||
|
||
Expected: 输出 `OK`。
|
||
|
||
- [ ] **Step 6: Commit**
|
||
|
||
```bash
|
||
git add src/lib/boss-data.ts
|
||
git commit -m "feat: add attachment storage config model"
|
||
```
|
||
|
||
---
|
||
|
||
### Task 2: 先把统一附件工具和服务器文件存储跑通
|
||
|
||
**Files:**
|
||
- Create: `src/lib/boss-attachments.ts`
|
||
- Create: `src/lib/boss-storage.ts`
|
||
- Create: `src/lib/boss-storage-server-file.ts`
|
||
- Create: `src/app/api/v1/projects/[projectId]/attachments/route.ts`
|
||
- Create: `src/app/api/v1/attachments/[attachmentId]/download/route.ts`
|
||
|
||
- [ ] **Step 1: 先写 failing API 验证脚本，确认上传接口还不存在**
|
||
|
||
```bash
|
||
tmpdir=$(mktemp -d)
|
||
cookie="$tmpdir/cookies.txt"
|
||
curl -sS -c "$cookie" -b "$cookie" -H 'Content-Type: application/json' -d '{}' http://127.0.0.1:3000/api/auth/login >/dev/null
|
||
curl -sS -o /dev/null -w '%{http_code}\n' -c "$cookie" -b "$cookie" -F "file=@README.md" http://127.0.0.1:3000/api/v1/projects/boss-console/attachments
|
||
```
|
||
|
||
- [ ] **Step 2: 运行脚本，确认当前是 404 或未实现失败**
|
||
|
||
Run:
|
||
|
||
```bash
|
||
tmpdir=$(mktemp -d)
|
||
cookie="$tmpdir/cookies.txt"
|
||
curl -sS -c "$cookie" -b "$cookie" -H 'Content-Type: application/json' -d '{}' http://127.0.0.1:3000/api/auth/login >/dev/null
|
||
curl -sS -o /dev/null -w '%{http_code}\n' -c "$cookie" -b "$cookie" -F "file=@README.md" http://127.0.0.1:3000/api/v1/projects/boss-console/attachments
|
||
```
|
||
|
||
Expected: 不是 `200`，说明接口尚未实现。
|
||
|
||
- [ ] **Step 3: 在 `boss-attachments.ts` 实现类型归类和自动/手动分析判定**
|
||
|
||
```ts
|
||
export function detectAttachmentKind(fileName: string, mimeType: string): AttachmentKind {
|
||
if (mimeType.startsWith("image/")) return "image";
|
||
if (mimeType.startsWith("video/")) return "video";
|
||
if (mimeType === "application/pdf") return "pdf";
|
||
if (mimeType.startsWith("text/")) return "text";
|
||
if (
|
||
mimeType.includes("officedocument") ||
|
||
mimeType.includes("msword") ||
|
||
mimeType.includes("spreadsheet") ||
|
||
mimeType.includes("presentation")
|
||
) {
|
||
return "office";
|
||
}
|
||
return "binary";
|
||
}
|
||
|
||
export function resolveAttachmentAnalysisState(kind: AttachmentKind, fileSizeBytes: number): AttachmentAnalysisState {
|
||
const isLarge = fileSizeBytes > 20 * 1024 * 1024;
|
||
if (isLarge) return "ready_manual";
|
||
if (kind === "image" || kind === "pdf" || kind === "text") return "queued_auto";
|
||
return "ready_manual";
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 4: 在 `boss-storage-server-file.ts` 实现本地文件上传与下载定位**
|
||
|
||
```ts
|
||
export async function storeServerFileAttachment(params: {
|
||
account: string;
|
||
messageId: string;
|
||
fileName: string;
|
||
buffer: Buffer;
|
||
}) {
|
||
const now = new Date();
|
||
const relativePath = path.join(
|
||
"data",
|
||
"uploads",
|
||
params.account,
|
||
String(now.getUTCFullYear()),
|
||
String(now.getUTCMonth() + 1).padStart(2, "0"),
|
||
`${params.messageId}-${sanitizeFileName(params.fileName)}`,
|
||
);
|
||
const absolutePath = path.join(resolveRuntimeRoot(), relativePath);
|
||
await fs.mkdir(path.dirname(absolutePath), { recursive: true });
|
||
await fs.writeFile(absolutePath, params.buffer);
|
||
return {
|
||
storageBackend: "server_file" as const,
|
||
storagePath: relativePath,
|
||
};
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 5: 在上传 route 里先实现 `server_file` 主链**
|
||
|
||
核心逻辑最小实现：
|
||
|
||
```ts
|
||
const form = await request.formData();
|
||
const file = form.get("file");
|
||
if (!(file instanceof File)) {
|
||
return NextResponse.json({ ok: false, message: "FILE_REQUIRED" }, { status: 400 });
|
||
}
|
||
const bytes = Buffer.from(await file.arrayBuffer());
|
||
const attachmentId = randomToken("att");
|
||
const messageId = randomToken("msg");
|
||
const attachmentKind = detectAttachmentKind(file.name, file.type || "application/octet-stream");
|
||
const analysisState = resolveAttachmentAnalysisState(attachmentKind, bytes.byteLength);
|
||
const stored = await provider.storeAttachment(...);
|
||
const message = await appendAttachmentMessage(...);
|
||
```
|
||
|
||
- [ ] **Step 6: 在下载 route 里实现 `server_file` 流式返回**
|
||
|
||
```ts
|
||
if (attachment.storageBackend === "server_file") {
|
||
const absolutePath = path.join(resolveRuntimeRoot(), attachment.storagePath);
|
||
const stream = createReadStream(absolutePath);
|
||
return new NextResponse(Readable.toWeb(stream) as ReadableStream, {
|
||
headers: {
|
||
"Content-Type": attachment.mimeType,
|
||
"Content-Disposition": `inline; filename="${attachment.fileName}"`,
|
||
},
|
||
});
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 7: 启动本地服务并验证上传/下载通过**
|
||
|
||
Run:
|
||
|
||
```bash
|
||
npm run build
|
||
npm start
|
||
```
|
||
|
||
再执行：
|
||
|
||
```bash
|
||
tmpdir=$(mktemp -d)
|
||
cookie="$tmpdir/cookies.txt"
|
||
curl -sS -c "$cookie" -b "$cookie" -H 'Content-Type: application/json' -d '{}' http://127.0.0.1:3000/api/auth/login >/dev/null
|
||
curl -sS -c "$cookie" -b "$cookie" -F "file=@README.md;type=text/plain" http://127.0.0.1:3000/api/v1/projects/boss-console/attachments
|
||
```
|
||
|
||
Expected: 返回 `ok:true` 且消息 `kind=attachment`。
|
||
|
||
- [ ] **Step 8: Commit**
|
||
|
||
```bash
|
||
git add src/lib/boss-attachments.ts src/lib/boss-storage.ts src/lib/boss-storage-server-file.ts src/app/api/v1/projects/[projectId]/attachments/route.ts src/app/api/v1/attachments/[attachmentId]/download/route.ts
|
||
git commit -m "feat: add server file attachment pipeline"
|
||
```
|
||
|
||
---
|
||
|
||
### Task 3: 接入阿里 OSS 私有桶与配置校验
|
||
|
||
**Files:**
|
||
- Create: `src/lib/boss-storage-aliyun-oss.ts`
|
||
- Create: `src/app/api/v1/storage/config/route.ts`
|
||
- Create: `src/app/api/v1/storage/config/validate/route.ts`
|
||
- Modify: `src/lib/boss-storage.ts`
|
||
- Modify: `package.json`
|
||
|
||
- [ ] **Step 1: 先写 failing config 路由验证**
|
||
|
||
```bash
|
||
tmpdir=$(mktemp -d)
|
||
cookie="$tmpdir/cookies.txt"
|
||
curl -sS -c "$cookie" -b "$cookie" -H 'Content-Type: application/json' -d '{}' http://127.0.0.1:3000/api/auth/login >/dev/null
|
||
curl -sS -o /dev/null -w '%{http_code}\n' -c "$cookie" -b "$cookie" http://127.0.0.1:3000/api/v1/storage/config
|
||
```
|
||
|
||
- [ ] **Step 2: 运行，确认当前是 404**
|
||
|
||
Run 同上。
|
||
Expected: `404`。
|
||
|
||
- [ ] **Step 3: 安装阿里 OSS SDK 并实现 provider**
|
||
|
||
```bash
|
||
npm install ali-oss
|
||
```
|
||
|
||
在 `boss-storage-aliyun-oss.ts` 最小实现：
|
||
|
||
```ts
|
||
import OSS from "ali-oss";
|
||
|
||
export function createAliyunOssClient(config: UserAttachmentStorageConfig["aliyunOss"]) {
|
||
if (!config?.enabled) throw new Error("ALIYUN_OSS_NOT_ENABLED");
|
||
return new OSS({
|
||
accessKeyId: config.accessKeyId,
|
||
accessKeySecret: decryptStorageSecret(config.accessKeySecretEncrypted),
|
||
bucket: config.bucket,
|
||
endpoint: config.endpoint,
|
||
region: config.region,
|
||
});
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 4: 实现 `GET/PATCH /api/v1/storage/config`**
|
||
|
||
要求：
|
||
|
||
- `GET` 返回当前用户配置
|
||
- `PATCH` 接受 `mode`、`ossProvider`、`aliyunOss`
|
||
- `PATCH` 时对 `AccessKey Secret` 做加密，不明文落库
|
||
|
||
最小返回结构：
|
||
|
||
```ts
|
||
return NextResponse.json({
|
||
ok: true,
|
||
config: sanitizeStorageConfig(savedConfig),
|
||
});
|
||
```
|
||
|
||
- [ ] **Step 5: 实现 `POST /api/v1/storage/config/validate`**
|
||
|
||
使用 OSS SDK 执行最小探针：
|
||
|
||
```ts
|
||
await client.getBucketInfo();
|
||
return NextResponse.json({ ok: true, provider: "aliyun_oss" });
|
||
```
|
||
|
||
失败时返回：
|
||
|
||
```ts
|
||
return NextResponse.json({ ok: false, message: normalizeStorageError(error) }, { status: 400 });
|
||
```
|
||
|
||
- [ ] **Step 6: 在 `boss-storage.ts` 中按用户配置分流到 `server_file / aliyun_oss`**
|
||
|
||
```ts
|
||
export async function resolveAttachmentStorageProvider(account: string): Promise<AttachmentStorageProvider> {
|
||
const config = await getAttachmentStorageConfig(account);
|
||
if (config.mode === "oss" && config.ossProvider === "aliyun_oss") {
|
||
return createAliyunOssStorageProvider(config);
|
||
}
|
||
return createServerFileStorageProvider();
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 7: 运行接口验证**
|
||
|
||
Run:
|
||
|
||
```bash
|
||
tmpdir=$(mktemp -d)
|
||
cookie="$tmpdir/cookies.txt"
|
||
curl -sS -c "$cookie" -b "$cookie" -H 'Content-Type: application/json' -d '{}' http://127.0.0.1:3000/api/auth/login >/dev/null
|
||
curl -sS -c "$cookie" -b "$cookie" http://127.0.0.1:3000/api/v1/storage/config
|
||
```
|
||
|
||
Expected: 返回默认 `mode=server_file`。
|
||
|
||
- [ ] **Step 8: Commit**
|
||
|
||
```bash
|
||
git add package.json package-lock.json src/lib/boss-storage.ts src/lib/boss-storage-aliyun-oss.ts src/app/api/v1/storage/config/route.ts src/app/api/v1/storage/config/validate/route.ts
|
||
git commit -m "feat: add aliyun oss storage config"
|
||
```
|
||
|
||
---
|
||
|
||
### Task 4: 打通附件消息创建、下载元数据和主 Agent 分析任务
|
||
|
||
**Files:**
|
||
- Modify: `src/lib/boss-data.ts`
|
||
- Modify: `src/lib/boss-master-agent.ts`
|
||
- Create: `src/app/api/v1/projects/[projectId]/attachments/[attachmentId]/analyze/route.ts`
|
||
- Modify: `src/app/api/v1/projects/[projectId]/attachments/route.ts`
|
||
|
||
- [ ] **Step 1: 先写 failing API 行为验证，确认分析接口未实现**
|
||
|
||
```bash
|
||
tmpdir=$(mktemp -d)
|
||
cookie="$tmpdir/cookies.txt"
|
||
curl -sS -c "$cookie" -b "$cookie" -H 'Content-Type: application/json' -d '{}' http://127.0.0.1:3000/api/auth/login >/dev/null
|
||
curl -sS -o /dev/null -w '%{http_code}\n' -c "$cookie" -b "$cookie" -X POST http://127.0.0.1:3000/api/v1/projects/boss-console/attachments/att-missing/analyze
|
||
```
|
||
|
||
- [ ] **Step 2: 运行，确认不是成功状态**
|
||
|
||
Expected: 404/400。
|
||
|
||
- [ ] **Step 3: 在 `boss-data.ts` 中增加附件消息 helper**
|
||
|
||
新增：
|
||
|
||
```ts
|
||
export async function appendAttachmentMessage(payload: {
|
||
projectId: string;
|
||
senderLabel: string;
|
||
body: string;
|
||
attachment: MessageAttachment;
|
||
}) {
|
||
return appendProjectMessage({
|
||
projectId: payload.projectId,
|
||
senderLabel: payload.senderLabel,
|
||
body: payload.body,
|
||
kind: "attachment",
|
||
attachment: payload.attachment,
|
||
});
|
||
}
|
||
```
|
||
|
||
并把 `appendProjectMessage` 扩展为支持：
|
||
|
||
```ts
|
||
attachment?: MessageAttachment;
|
||
```
|
||
|
||
- [ ] **Step 4: 在 `boss-master-agent.ts` 增加 `attachment_analysis` 任务类型**
|
||
|
||
最小接口：
|
||
|
||
```ts
|
||
export async function queueAttachmentAnalysisTask(params: AttachmentAnalysisTaskPayload) {
|
||
return queueMasterAgentTask({
|
||
taskType: "attachment_analysis",
|
||
projectId: params.projectId,
|
||
requestText: `请分析附件：${params.fileName}`,
|
||
payload: params,
|
||
});
|
||
}
|
||
```
|
||
|
||
并在任务完成回写时，新增：
|
||
|
||
```ts
|
||
await appendProjectMessage({
|
||
projectId: task.projectId,
|
||
sender: "master",
|
||
senderLabel: "主 Agent",
|
||
body: shortSummary,
|
||
kind: "text",
|
||
});
|
||
|
||
await appendProjectMessage({
|
||
projectId: task.projectId,
|
||
sender: "master",
|
||
senderLabel: "主 Agent",
|
||
body: cardTitle,
|
||
kind: "analysis_card",
|
||
});
|
||
```
|
||
|
||
- [ ] **Step 5: 在上传 route 中自动创建分析任务**
|
||
|
||
规则：
|
||
|
||
```ts
|
||
if (attachment.analysisState === "queued_auto") {
|
||
await queueAttachmentAnalysisTask(...);
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 6: 实现手动分析接口**
|
||
|
||
```ts
|
||
export async function POST(...) {
|
||
const attachment = await findProjectAttachment(projectId, attachmentId);
|
||
if (!attachment) return NextResponse.json({ ok: false, message: "ATTACHMENT_NOT_FOUND" }, { status: 404 });
|
||
if (attachment.analysisState !== "ready_manual" && attachment.analysisState !== "failed") {
|
||
return NextResponse.json({ ok: false, message: "ATTACHMENT_ANALYZE_NOT_ALLOWED" }, { status: 400 });
|
||
}
|
||
const task = await queueAttachmentAnalysisTask(...);
|
||
return NextResponse.json({ ok: true, taskId: task.taskId });
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 7: 验证自动/手动状态判定**
|
||
|
||
Run:
|
||
|
||
```bash
|
||
tmpdir=$(mktemp -d)
|
||
cookie="$tmpdir/cookies.txt"
|
||
curl -sS -c "$cookie" -b "$cookie" -H 'Content-Type: application/json' -d '{}' http://127.0.0.1:3000/api/auth/login >/dev/null
|
||
curl -sS -c "$cookie" -b "$cookie" -F "file=@README.md;type=text/plain" http://127.0.0.1:3000/api/v1/projects/boss-console/attachments
|
||
```
|
||
|
||
Expected: 返回的附件消息 `analysisState=queued_auto`。
|
||
|
||
- [ ] **Step 8: Commit**
|
||
|
||
```bash
|
||
git add src/lib/boss-data.ts src/lib/boss-master-agent.ts src/app/api/v1/projects/[projectId]/attachments/route.ts src/app/api/v1/projects/[projectId]/attachments/[attachmentId]/analyze/route.ts
|
||
git commit -m "feat: add attachment analysis task flow"
|
||
```
|
||
|
||
---
|
||
|
||
### Task 5: Web 端补 `我的 > 附件与存储`
|
||
|
||
**Files:**
|
||
- Create: `src/app/me/storage/page.tsx`
|
||
- Modify: `src/app/me/page.tsx`
|
||
- Modify: `src/components/app-ui.tsx`
|
||
- Modify: `src/app/api/v1/settings` only if existing menu projection needs an extra field (otherwise keep scope local)
|
||
|
||
- [ ] **Step 1: 先写 failing 路由访问验证**
|
||
|
||
```bash
|
||
tmpdir=$(mktemp -d)
|
||
cookie="$tmpdir/cookies.txt"
|
||
curl -sS -c "$cookie" -b "$cookie" -H 'Content-Type: application/json' -d '{}' http://127.0.0.1:3000/api/auth/login >/dev/null
|
||
curl -sS -o /dev/null -w '%{http_code}\n' -c "$cookie" -b "$cookie" http://127.0.0.1:3000/me/storage
|
||
```
|
||
|
||
- [ ] **Step 2: 运行，确认当前不是 200**
|
||
|
||
Expected: `404`。
|
||
|
||
- [ ] **Step 3: 创建页面并只做两层交互**
|
||
|
||
`page.tsx` 结构最小如下：
|
||
|
||
```tsx
|
||
export default async function StoragePage() {
|
||
const config = await getAttachmentStorageConfigForSession();
|
||
return (
|
||
<main className="space-y-4">
|
||
<section>
|
||
<h1>附件与存储</h1>
|
||
<p>默认使用服务器文件存储，也可以切到阿里 OSS。</p>
|
||
</section>
|
||
<StorageModeCard config={config} />
|
||
{config.mode === "oss" ? <AliyunOssForm config={config} /> : null}
|
||
</main>
|
||
);
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 4: 在 `我的` 根页加菜单入口**
|
||
|
||
```tsx
|
||
<Link href="/me/storage">附件与存储</Link>
|
||
```
|
||
|
||
保持它与 `账号与安全 / AI 账号 / 技能 / 关于` 同级，继续微信式简单列表，不引入大面板。
|
||
|
||
- [ ] **Step 5: 用最小表单接 `GET/PATCH/validate`**
|
||
|
||
至少支持：
|
||
|
||
- 选择 `服务器文件存储 / OSS`
|
||
- 选 `OSS` 后只显示 `阿里 OSS`
|
||
- 填 `AK / SK / Bucket / Endpoint / Region / Prefix`
|
||
- `测试并保存`
|
||
- `切回服务器文件存储`
|
||
|
||
- [ ] **Step 6: 验证页面和配置链**
|
||
|
||
Run:
|
||
|
||
```bash
|
||
curl -sS http://127.0.0.1:3000/api/health
|
||
curl -sS -H 'Content-Type: application/json' -d '{}' http://127.0.0.1:3000/api/auth/login
|
||
```
|
||
|
||
并在浏览器打开：
|
||
|
||
```text
|
||
http://127.0.0.1:3000/me/storage
|
||
```
|
||
|
||
Expected: 页面可访问，能显示默认 `server_file`。
|
||
|
||
- [ ] **Step 7: Commit**
|
||
|
||
```bash
|
||
git add src/app/me/storage/page.tsx src/app/me/page.tsx src/components/app-ui.tsx
|
||
git commit -m "feat: add attachment storage settings page"
|
||
```
|
||
|
||
---
|
||
|
||
### Task 6: 原生 Android 接入附件选择、上传和消息渲染
|
||
|
||
**Files:**
|
||
- Modify: `android/app/src/main/java/com/hyzq/boss/BossApiClient.java`
|
||
- Modify: `android/app/src/main/java/com/hyzq/boss/ProjectDetailActivity.java`
|
||
- Modify: `android/app/src/main/java/com/hyzq/boss/BossUi.java`
|
||
- Modify: `android/app/src/main/res/layout/activity_project_chat.xml`
|
||
- Create: `android/app/src/test/java/com/hyzq/boss/AttachmentComposerStateTest.java`
|
||
- Create: `android/app/src/test/java/com/hyzq/boss/BossApiClientAttachmentTest.java`
|
||
|
||
- [ ] **Step 1: 先写 failing 原生状态测试**
|
||
|
||
在 `AttachmentComposerStateTest.java` 先写：
|
||
|
||
```java
|
||
@Test
|
||
public void imageAndVideoRequireConfirmationButFileDoesNot() {
|
||
assertTrue(ProjectChatUiState.requiresAttachmentConfirmation("image"));
|
||
assertTrue(ProjectChatUiState.requiresAttachmentConfirmation("video"));
|
||
assertFalse(ProjectChatUiState.requiresAttachmentConfirmation("file"));
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 2: 运行测试，确认当前失败**
|
||
|
||
Run:
|
||
|
||
```bash
|
||
cd android
|
||
./gradlew testDebugUnitTest --tests com.hyzq.boss.AttachmentComposerStateTest --no-daemon
|
||
```
|
||
|
||
Expected: FAIL，提示 helper 未实现。
|
||
|
||
- [ ] **Step 3: 在 `ProjectChatUiState` / `ProjectDetailActivity` 实现附件入口状态**
|
||
|
||
最小 helper：
|
||
|
||
```java
|
||
static boolean requiresAttachmentConfirmation(String sourceType) {
|
||
return "image".equals(sourceType) || "video".equals(sourceType);
|
||
}
|
||
```
|
||
|
||
并在 `ProjectDetailActivity` 中增加：
|
||
|
||
- 左侧 `+` 按钮
|
||
- 底部抽屉容器
|
||
- 三个入口：图片 / 视频 / 文件
|
||
- `ActivityResultLauncher<String>` 或 `OpenDocument` 注册器
|
||
|
||
- [ ] **Step 4: 在 `BossApiClient` 增加 multipart 上传**
|
||
|
||
实现最小接口：
|
||
|
||
```java
|
||
public ApiResponse uploadAttachment(String projectId, String fileName, String mimeType, byte[] bytes, String sourceType) throws Exception
|
||
```
|
||
|
||
以及：
|
||
|
||
```java
|
||
public ApiResponse analyzeAttachment(String projectId, String attachmentId) throws Exception
|
||
```
|
||
|
||
- [ ] **Step 5: 在 `BossUi` 补附件消息卡片**
|
||
|
||
新增：
|
||
|
||
```java
|
||
buildAttachmentMessageCard(...)
|
||
buildAttachmentAnalysisStateChip(...)
|
||
```
|
||
|
||
要求：
|
||
|
||
- 图片：缩略图占位 + 文件名 + 状态
|
||
- 视频：封面占位 + 文件名 + 状态
|
||
- 文件：文件图标 + 文件名 + 大小 + 状态
|
||
|
||
- [ ] **Step 6: 运行原生测试和 debug 构建**
|
||
|
||
Run:
|
||
|
||
```bash
|
||
cd android
|
||
./gradlew testDebugUnitTest --tests com.hyzq.boss.AttachmentComposerStateTest --tests com.hyzq.boss.BossApiClientAttachmentTest :app:compileDebugJavaWithJavac assembleDebug --no-daemon
|
||
```
|
||
|
||
Expected: BUILD SUCCESSFUL。
|
||
|
||
- [ ] **Step 7: Commit**
|
||
|
||
```bash
|
||
git add android/app/src/main/java/com/hyzq/boss/BossApiClient.java android/app/src/main/java/com/hyzq/boss/ProjectDetailActivity.java android/app/src/main/java/com/hyzq/boss/BossUi.java android/app/src/main/res/layout/activity_project_chat.xml android/app/src/test/java/com/hyzq/boss/AttachmentComposerStateTest.java android/app/src/test/java/com/hyzq/boss/BossApiClientAttachmentTest.java
|
||
git commit -m "feat: add native chat attachment flow"
|
||
```
|
||
|
||
---
|
||
|
||
### Task 7: 原生端补附件动作、分析状态和下载/预览
|
||
|
||
**Files:**
|
||
- Modify: `android/app/src/main/java/com/hyzq/boss/ProjectDetailActivity.java`
|
||
- Modify: `android/app/src/main/java/com/hyzq/boss/BossUi.java`
|
||
- Modify: `android/app/src/main/AndroidManifest.xml`
|
||
- Test: `android/app/src/test/java/com/hyzq/boss/ProjectDetailActivityUiTest.java`
|
||
|
||
- [ ] **Step 1: 先写 failing UI 测试，验证附件状态动作**
|
||
|
||
在 `ProjectDetailActivityUiTest.java` 增补：
|
||
|
||
```java
|
||
@Test
|
||
public void manualAnalysisAttachmentShowsActionChip() {
|
||
// render 一个 analysisState=ready_manual 的 attachment message
|
||
// 断言 UI 中出现“让 AI 分析”
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 2: 运行测试，确认当前失败**
|
||
|
||
Run:
|
||
|
||
```bash
|
||
cd android
|
||
./gradlew testDebugUnitTest --tests com.hyzq.boss.ProjectDetailActivityUiTest --no-daemon
|
||
```
|
||
|
||
Expected: FAIL。
|
||
|
||
- [ ] **Step 3: 在消息卡片中增加动作**
|
||
|
||
规则：
|
||
|
||
- `queued_auto`：显示“自动分析排队中”
|
||
- `processing`：显示“AI 分析中”
|
||
- `ready_manual`：显示按钮“让 AI 分析”
|
||
- `completed`：显示摘要
|
||
- `failed`：显示“重试分析”
|
||
|
||
- [ ] **Step 4: 接通下载/预览行为**
|
||
|
||
最小行为：
|
||
|
||
- 图片：打开下载 URL
|
||
- 视频：打开下载 URL
|
||
- 文件：打开下载 URL
|
||
|
||
先用系统浏览器或下载器打开，不在这轮强做自定义预览器。
|
||
|
||
- [ ] **Step 5: 运行 UI 测试与编译**
|
||
|
||
Run:
|
||
|
||
```bash
|
||
cd android
|
||
./gradlew testDebugUnitTest --tests com.hyzq.boss.ProjectDetailActivityUiTest :app:compileDebugJavaWithJavac assembleDebug --no-daemon
|
||
```
|
||
|
||
Expected: BUILD SUCCESSFUL。
|
||
|
||
- [ ] **Step 6: Commit**
|
||
|
||
```bash
|
||
git add android/app/src/main/java/com/hyzq/boss/ProjectDetailActivity.java android/app/src/main/java/com/hyzq/boss/BossUi.java android/app/src/main/AndroidManifest.xml android/app/src/test/java/com/hyzq/boss/ProjectDetailActivityUiTest.java
|
||
git commit -m "feat: add attachment analysis states to native chat"
|
||
```
|
||
|
||
---
|
||
|
||
### Task 8: 文档、联调、发包、部署
|
||
|
||
**Files:**
|
||
- Modify: `README.md`
|
||
- Modify: `docs/architecture/current_runtime_and_deploy_status_cn.md`
|
||
- Modify: `docs/architecture/api_and_service_inventory_cn.md`
|
||
- Modify: `docs/architecture/ai_handoff_index_cn.md`
|
||
- Modify: `android/app/build.gradle`
|
||
- Modify: `public/downloads/*`（如果发 release）
|
||
|
||
- [ ] **Step 1: 本地完整验证**
|
||
|
||
Run:
|
||
|
||
```bash
|
||
cd /Users/kris/code/boss
|
||
npm run lint
|
||
npm run build
|
||
curl -sS http://127.0.0.1:3000/api/health
|
||
curl -sS http://127.0.0.1:4317/health
|
||
```
|
||
|
||
Expected:
|
||
|
||
- lint 通过
|
||
- build 通过
|
||
- 两个 health 都返回 `ok:true`
|
||
|
||
- [ ] **Step 2: Android 验证和打包**
|
||
|
||
Run:
|
||
|
||
```bash
|
||
cd /Users/kris/code/boss/android
|
||
./gradlew testDebugUnitTest :app:compileDebugJavaWithJavac assembleDebug --no-daemon
|
||
cd /Users/kris/code/boss
|
||
JAVA_HOME=$(/usr/libexec/java_home) npm run apk:release
|
||
JAVA_HOME=$(/usr/libexec/java_home) npm run aab:release
|
||
```
|
||
|
||
Expected:
|
||
|
||
- Android 测试和构建成功
|
||
- 产出新版本 APK / AAB
|
||
|
||
- [ ] **Step 3: 部署服务器并验证**
|
||
|
||
Run:
|
||
|
||
```bash
|
||
cd /Users/kris/code/boss
|
||
./scripts/deploy-server.sh
|
||
"$HOME/.codex/skills/boss-server-debug/scripts/server_ssh.sh" exec "curl -sS http://127.0.0.1:3000/api/health"
|
||
curl -sS https://boss.hyzq.net/api/health
|
||
```
|
||
|
||
Expected:
|
||
|
||
- 远端本机 health 正常
|
||
- 公网 health 正常
|
||
|
||
- [ ] **Step 4: 文档同步**
|
||
|
||
把以下事实写回文档：
|
||
|
||
- 默认服务器文件存储已可用
|
||
- `我的 > 附件与存储` 已上线
|
||
- 阿里 OSS 私有桶已接入
|
||
- 图片 / PDF / 文本自动分析
|
||
- 视频 / Office / 大文件手动分析
|
||
- 原生聊天附件入口和分析状态说明
|
||
|
||
- [ ] **Step 5: Commit**
|
||
|
||
```bash
|
||
git add README.md docs/architecture/current_runtime_and_deploy_status_cn.md docs/architecture/api_and_service_inventory_cn.md docs/architecture/ai_handoff_index_cn.md android/app/build.gradle public/downloads
|
||
git commit -m "chore: publish attachment storage release"
|
||
```
|
||
|
||
---
|
||
|
||
## Self-Review
|
||
|
||
### Spec coverage
|
||
|
||
- 原生附件入口：Task 6、Task 7 覆盖
|
||
- 默认服务器文件存储：Task 2 覆盖
|
||
- 阿里 OSS：Task 3 覆盖
|
||
- 用户级存储配置：Task 1、Task 3、Task 5 覆盖
|
||
- 统一下载入口：Task 2 覆盖
|
||
- 自动/手动分析：Task 4 覆盖
|
||
- 主 Agent 分析回写：Task 4 覆盖
|
||
- Web 简化配置页：Task 5 覆盖
|
||
- 文档、部署、发包：Task 8 覆盖
|
||
|
||
### Placeholder scan
|
||
|
||
- 没有 `TODO / TBD / implement later / similar to task N`
|
||
- 每个任务都给出了具体文件、命令和最小代码形状
|
||
|
||
### Type consistency
|
||
|
||
- `AttachmentStorageMode` 统一使用 `server_file | oss`
|
||
- `OssProvider` 统一使用 `aliyun_oss`
|
||
- `MessageKind` 统一新增 `attachment / analysis_card`
|
||
- `AttachmentAnalysisState` 统一使用 `queued_auto / ready_manual / processing / completed / failed`
|
||
|