AGENTS.md

最重要的三条

docs/ 是唯一事实来源。 所有代码按 docs/ 生成，不做反向推导。
代码与文档冲突时，以文档为准。 冲突的判定是"代码错了"，修代码或重新生成；不得改文档去迁就代码。
docs/ 下任何文件只读。 不得创建、修改、删除、格式化 docs/；需求变更由人类先改文档。见 docs/conventions.md 第二、五节。

遇到题面没覆盖的行为：不自己发明，写进回复里让人类决定补文档还是补禁令。

严格按 `TODO.md` 执行

根目录 TODO.md 是唯一的任务清单。按章节顺序（0 → 8）从上往下做，不要跳章节挑"有意思的"先做。
一次只做一个条目：改完、验证通过、把该条勾成 [x]（部分完成用 [~] 并在后面注明缺什么），再开始下一条。不要把多个章节的改动混在一次提交里。
不擅自扩充范围：TODO 没列的功能不做；确实需要的先提出来让人类加条目。
第 8 章「明确不做」永远不勾选，也不实现。
TODO.md 可以用 [x]/[~] 反映进度，但不得删除条目或改动其含义——需求变更走文档流程，由人类改。

开工前按任务读文档

永远：docs/overview.md、docs/architecture.md、docs/conventions.md（第四节是硬性禁令清单）
后端：再加 docs/api.md、docs/backend/{data-model,auth,audit}.md
前端：再加 docs/api.md、docs/frontend/frontend.md
README.md 只是索引，具体规则以它指向的文档为准；README 里写的 deploy/ 目录当前不存在。

硬性禁令（全部来自 `docs/conventions.md` 第四节，只摘最容易违反的）

不用 Docker / K8s；不引入 PG 之外的存储作为真值源。
不做 SSR / 预渲染；不做多用户（user_id 字段是预留，不实现注册）。
后端只用 Gin；不用 ORM / sqlc，手写 SQL（database/sql + pgx）。
*gin.Context 只出现在 handler 层，业务函数只收 context.Context。
创建笔记不接受 visibility；公开只走 publish。
本期不写任何 TUI / Neovim 代码，也不写 LLM 实现（internal/llm 只有接口，不加 SDK 依赖）。
读接口的 visibility 收敛统一由授权中间件注入，不在各 handler 里自己拼。

当前代码状态（先看这里再动手，别假设已实现）

仓库处于脚手架阶段：

backend/cmd/haven/main.go 只有 GET /api/health 和硬编码 r.Run(":8080")，与文档要求的 HAVEN_LISTEN_ADDR 等环境变量配置不符——按 docs/architecture.md 第四节重写，不要参考现有写法。
backend/internal/* 全是空目录；backend/migrations/ 为空。
frontend/ 是 Vite create-vue 模板（HelloWorld.vue、src/views|router|stores|api 空目录）；缺 vue-router、pinia 的实际接线。
frontend/dist/ 是上次构建产物，被 gitignore，不要手改、不要提交。

常用命令

后端（在 backend/ 下执行）：

go build ./...                  # 编译
go vet ./...
go test ./...                   # 单包：go test ./internal/auth/...
go test ./internal/auth -run TestLoginTotp -v

前端（在 frontend/ 下执行）：包管理器是 pnpm（有 pnpm-lock.yaml，不要用 npm/yarn 生成新 lockfile）。

pnpm install
pnpm dev                        # Vite dev server，需自行代理 /api 到后端
pnpm build                      # = vue-tsc -b && vite build → frontend/dist/

没有 lint / format / CI 配置，不要自造工具链。

认证相关的本地运行需要 PostgreSQL 并 CREATE EXTENSION IF NOT EXISTS pg_trgm;；其它 HAVEN_* 环境变量见 docs/architecture.md 第四节（缺必填项应拒绝启动）。

容易踩的约定

module 路径是 github.com/kairo/haven；go.mod 用 go 1.27.3，pgx 是 v5。
migration 用 golang-migrate 命名 0001_init.up.sql / .down.sql，放 backend/migrations/；顺序为 users → sessions/pending_logins/trusted_devices/tokens/audit_events → notes/tags/portfolio_items → note_tags/portfolio_repos。后端启动时不跑 migration。
后端分包按领域（notes、tags、search、portfolio、audit），禁止建 handlers/、services/、repositories/；跨领域公共代码只放 httpx / auth / config。
搜索只查生成列 notes.search_text，应用层不写该字段；ILIKE '%q%'，无中文分词。
公开可见条件唯一：visibility = 'public' AND published_at IS NOT NULL；撤回 public→private 时保留 published_at。
跨用户访问返回 404 而非 403；403 只留给"已登录但权限不足"（如 read Token 做写操作）。
JSON 一律 snake_case，不转 camelCase；列表响应固定 {items, total}（空列表不能是 null）；笔记列表 item 必须带后端截断好的 content_preview（按 rune 截 200）。
凭证类操作（Token / 授信设备 / 会话 / TOTP / 密码）Token 一律 403，只允许 Web 会话；其中 TOTP 关闭、改密码、增删改查 Token 需要会话已通过 TOTP。
cookie 名、有效期、bcrypt cost 等是代码常量，不从环境变量读取（清单在 docs/architecture.md 第四节）。
审计只在业务成功后写、失败只打日志不影响响应；笔记 CRUD 不写审计，只有 publish/unpublish 写。

Git 规范

提交信息沿用现有风格：feat(backend): ... / fix(frontend): ... / doc(docs): ...，中文描述，不加 AI 署名或 Co-Authored-By。
只提交自己本次改动的文件；不要 git add -A / git commit -a，以免带上别人未完成的改动。
未经用户明确要求，不要 commit / amend / push / rebase / reset；不要改写已有提交历史。
docs/ 只读，因此任何 AI 发起的提交都不应包含 docs/ 变更；若 git status 里 docs/ 有改动，视为人类未提交的编辑，必须原样保留。
提交前先跑与改动范围对应的验证（go build ./... + go test ./...，或 pnpm build）；node_modules/、frontend/dist/ 已在 .gitignore 中，不要强制添加。
不创建 PR、不推送到 main、不擅自切换或创建分支，除非用户要求。

AGENTS.md 6.3 KB Histórico Em bruto