145 lines
5.4 KiB
Markdown
145 lines
5.4 KiB
Markdown
# 森林AI Documentation And Verification 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:** 统一开发配置、演示数据、README 和最终验证，使新开发者能够按文档启动森林AI并复现验收结果。
|
||
|
||
**Architecture:** Docker Compose、YAML 配置和 README 使用同一组开发默认值；本地数据通过显式 seed 命令创建。最终验证脚本只读取环境配置，不携带真实凭据。
|
||
|
||
**Tech Stack:** Docker Compose、PostgreSQL 16、Go、Node.js、Vite、Tauri。
|
||
|
||
## Global Constraints
|
||
|
||
- 不提交真实凭据、本地数据库、文件存储、日志、审计截图或构建产物。
|
||
- 开发配置可以包含明确标注的非生产默认值。
|
||
- 程序启动不得自动 drop 表或清空生产数据。
|
||
- README 必须为 UTF-8 中文，名称统一为“森林AI”。
|
||
|
||
---
|
||
|
||
### Task 1: 开发配置与演示数据一致性
|
||
|
||
**Files:**
|
||
- Modify: `infra/docker-compose.yml`
|
||
- Modify: `backend/etc/agent.dev.yaml`
|
||
- Modify: `backend/internal/config/config.go`
|
||
- Modify: `backend/internal/config/config_test.go`
|
||
- Modify: `backend/internal/seed/demo.go`
|
||
- Modify: `backend/internal/seed/demo_test.go`
|
||
- Modify: `.gitignore`
|
||
|
||
**Interfaces:**
|
||
- Produces: one PostgreSQL DSN shared by Compose and development YAML; explicit `go run ./cmd/seed` reset-safe seed workflow.
|
||
|
||
- [ ] **Step 1: Write failing configuration tests**
|
||
|
||
Assert the loaded development config uses port 9150, `/api/v1` compatible CORS origins, a non-empty storage dir, and that seed is idempotent while preserving project-scoped tags.
|
||
|
||
- [ ] **Step 2: Verify failures**
|
||
|
||
Run: `go test ./internal/config ./internal/seed -v`
|
||
|
||
Expected: FAIL where config lacks allowed origins or seed contracts.
|
||
|
||
- [ ] **Step 3: Align Compose and YAML**
|
||
|
||
Use the same development values in both files: user `agent`, password `agent`, database `agent`, host `localhost`, port `5432`. Keep secrets explicitly marked as development-only. Add `.superpowers/`, `backend/tmp/`, `backend/data/`, `apps/web_v1/test-results/` and build outputs to `.gitignore`.
|
||
|
||
- [ ] **Step 4: Verify config and seed**
|
||
|
||
Run: `go test ./internal/config ./internal/seed -v`
|
||
|
||
Expected: PASS.
|
||
|
||
- [ ] **Step 5: Commit**
|
||
|
||
```powershell
|
||
git add infra/docker-compose.yml backend/etc/agent.dev.yaml backend/internal/config backend/internal/seed .gitignore
|
||
git commit -m "chore: align forest AI development setup"
|
||
```
|
||
|
||
### Task 2: 重写 README
|
||
|
||
**Files:**
|
||
- Modify: `README.md`
|
||
- Modify: `docs/mvp-verification.md`
|
||
|
||
**Interfaces:**
|
||
- Produces: authoritative local setup and verification guide.
|
||
|
||
- [ ] **Step 1: Check every documented command before writing**
|
||
|
||
Run the exact commands that README will contain: Compose startup, backend API startup, seed, Web dev server, backend tests, visual check, build and lint. Record only commands that actually succeed.
|
||
|
||
- [ ] **Step 2: Replace README with the approved structure**
|
||
|
||
Use these exact top-level sections: `产品定位`, `MVP 范围`, `技术栈`, `目录结构`, `快速开始`, `配置`, `API v1 概览`, `验证`, `桌面端`, `常见问题`, `安全说明`.
|
||
|
||
Document `POST /api/v1/auth/login`, project/workspace, task/tag/source/cron, Inbox, search and AI session endpoints without embedding tokens or real secrets.
|
||
|
||
- [ ] **Step 3: Update verification documentation**
|
||
|
||
Include the current expected commands and artifact paths; remove stale Svelte references, old API paths, old product names and deprecated ports.
|
||
|
||
- [ ] **Step 4: Verify text consistency**
|
||
|
||
Run:
|
||
|
||
```powershell
|
||
rg -n "SenlinAI Agent Workbench|森林Agent|/api/projects|apps/web/|Svelte" README.md docs/mvp-verification.md
|
||
```
|
||
|
||
Expected: no matches.
|
||
|
||
- [ ] **Step 5: Commit**
|
||
|
||
```powershell
|
||
git add README.md docs/mvp-verification.md
|
||
git commit -m "docs: update forest AI setup and verification"
|
||
```
|
||
|
||
### Task 3: 全量验证与前后截图对比
|
||
|
||
**Files:**
|
||
- Modify: `apps/web_v1/scripts/visual-check.mjs`
|
||
- Create: `docs/forest-ai-audit.md`
|
||
|
||
**Interfaces:**
|
||
- Produces: repeatable desktop/mobile audit summary with final screenshots.
|
||
|
||
- [ ] **Step 1: Run backend verification**
|
||
|
||
Run: `go test ./...`
|
||
|
||
Expected: PASS for every package.
|
||
|
||
- [ ] **Step 2: Run frontend verification**
|
||
|
||
Run: `node scripts/structure-check.mjs; $env:VISUAL_CHECK_PORT='4174'; node scripts/visual-check.mjs; npm run build; npm run lint`
|
||
|
||
Expected: PASS; build may report a size warning but no error.
|
||
|
||
- [ ] **Step 3: Run PostgreSQL integration checks when DATABASE_URL is present**
|
||
|
||
Run: `go test ./internal/models -run TestPostgresPing -v`
|
||
|
||
Expected: PASS when `DATABASE_URL` is configured; otherwise the test reports its documented skip.
|
||
|
||
- [ ] **Step 4: Capture final evidence**
|
||
|
||
Capture and inspect 1440×1024 login, workspace, project overview and tasks, plus 390×844 login and project navigation. Compare against the five accepted audit screenshots from the design phase and document visible fixes and remaining limits in `docs/forest-ai-audit.md`.
|
||
|
||
- [ ] **Step 5: Verify repository cleanliness**
|
||
|
||
Run: `git status --short`
|
||
|
||
Expected: only intended source/docs changes are present; no logs, test screenshots, database files or secrets.
|
||
|
||
- [ ] **Step 6: Commit**
|
||
|
||
```powershell
|
||
git add apps/web_v1/scripts/visual-check.mjs docs/forest-ai-audit.md
|
||
git commit -m "test: verify forest AI MVP unification"
|
||
```
|
||
|