show-me-the-story: Instructions file for Codex

AGENTS.md — AI 小说写手项目指南

修改代码、配置、前端、提示词或构建流程后，必须同步更新本文件；只记录长期有效的约束与当前架构，不记录单次修复历史或逐函数清单。

项目概览

• 单二进制 Go Web 应用；Go 后端只使用标准库，前端产物与内置 Skill 通过 embed.FS 嵌入。
• Go 1.25.1，模块 showmethestory；默认端口 :48090，可用 PORT 覆盖。
• 前端：Vite 5、Svelte 4、Tailwind CSS 4、DaisyUI 5、@xianii/design-system；Playwright 仅使用系统 Google Chrome 生成 README 截图。
• 当前项目格式固定为 v4；项目默认保存在程序目录的 storys/<项目名>/。
• 项目语言 zh / en 决定模型提示词、正文和内置 Skill；UI 语言由浏览器独立切换。
• 默认英文入口为 README.md，中文入口为 README.zh.md；语言导航保持独立的首行链接列表，便于继续增加语言。详细流程维护于 docs/guide.zh.md 与 docs/guide.en.md，按创作顺序提供双语步骤与故障排查；许可证为 MIT。

常用命令

task build                 # npm install + 前端构建 + Go 二进制
task build:go              # 只构建 Go；要求 frontend/dist 已存在
task dev                   # 构建并启动后端
task dev:frontend          # Vite 开发服务器 :5173，代理 /api 到 :48090
task screenshots           # 用固定离线样例重建 README 截图

go build ./...
go test ./...
go vet ./...
cd frontend && npm run build

node frontend/src/lib/projectRestore.check.js
node frontend/src/lib/forceGraphLayout.check.js
cd frontend && npm run check # 所有前端回归检查

提交前至少运行 go build ./...、go test ./...、go vet ./...；修改前端时再运行前端构建及受影响的 .check.js。

PR 与 main/v4 推送通过同一检查工作流在 Linux/Windows 原生执行构建、测试及 vet；Linux 额外运行 race 检查。发布复用该工作流，检查成功后才生成发布产物。

架构边界

main.go
└── internal/httpapi
    ├── internal/agent
    │   └── internal/story
    └── internal/story
        ├── internal/llm
        ├── internal/config
        ├── internal/sse
        ├── internal/i18n
        ├── internal/prose
        └── internal/fsutil

• main.go：程序目录、API 配置、开发日志、嵌入前端和服务装配。
• internal/httpapi/：路由、请求校验、项目管理、异步任务互斥、SSE 和本地化错误。
• internal/agent/：助理循环、工具解析与执行、危险操作确认。
• internal/story/：大纲、写作、事实与设定、伏笔、导入、Skill、会话、校订等领域逻辑。
• internal/llm/：OpenAI 兼容客户端、流式完整性、重试、token 统计、JSON 提取。
• internal/config/：API/项目配置和中英默认提示词。
• internal/sse/、i18n/、prose/、fsutil/、devlog/：领域无关基础能力。
• frontend/src/：Svelte 页面、组件、stores、API/SSE/i18n；生产产物仅在 frontend/dist/。

依赖必须保持单向：httpapi → agent → story → 基础包。sse 的事件负载保持 any，不得反向依赖领域包。不要恢复已废弃的根目录 static/ 单页实现。