agent/docs/superpowers/plans/2026-07-21-forest-ai-docs-verification.md

森林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

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:

rg -n "SenlinAI Agent Workbench|森林Agent|/api/projects|apps/web/|Svelte" README.md docs/mvp-verification.md

Expected: no matches.

• Step 5: Commit

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

git add apps/web_v1/scripts/visual-check.mjs docs/forest-ai-audit.md
git commit -m "test: verify forest AI MVP unification"