lab-report-assistant

Imported from YiFanAWA/lab-report-assistant (AGENTS.md). Install upstream with npx skills add YiFanAWA/lab-report-assistant. Copyright stays with the author.

实验报告助手 Agent 宪法

本文件是本项目的根级 agent 宪法。任何进入本仓库的 agent，必须先读取本文件，再读取 dev-docs/README.md，然后才能进行分析、计划、编码、验收或文档修改。

除非项目负责人明确要求英文输出，所有对话、项目自有文档、交接记录、验收记录和决策记录都必须使用中文。技术名词、路径、命令、代码标识符、包名、文件格式名和产品名可以保留原文，但必须处在中文语境中。

CLAUDE.md、Cursor rules 或其他等价入口不得维护第二套规则；它们只能指向本文件。

当前项目真相

项目名称：实验报告助手。

项目主线：本地单用户 Web MVP 工作台，用证据化工作流辅助学生完成数据分析类实验报告和 PPT。核心价值不是“一键代写”，而是让实验要求、资料证据、数据处理、代码执行、图表结果和最终交付物保持一致并可追溯。

当前阶段：

• 代码阶段已正式启动。
• SPEC 0001 已完成并由项目负责人确认。
• SPEC 0002“实验要求输入与结构化任务单”已完成实现、复核验收并由项目负责人确认收口。
• 在编写并确认下一切片 SPEC 前，不得进入下一切片实现。
• 下一切片只能先编写并确认“公开资料与证据工作流”SPEC，再进入实现。

当前技术主线：

• 前端：apps/web/，TypeScript、React、Vite、React Router、TanStack Query。
• 后端：server/，Python、FastAPI、Pydantic、SQLAlchemy、Alembic、SQLite。
• 文件存储：本地项目工作区目录。
• 长任务：数据库任务表加独立 Worker 进程，后续切片逐步实现。
• Python 执行：应用托管的受控执行环境，V1 不要求用户手动配置分析依赖。
• 大模型：V1 暂定 DeepSeek，但业务模块只能通过统一 LLM Gateway 接入，不得写死模型名或供应商私有接口。

当前真源

事实冲突时按以下顺序判断：

1. 当前源码、测试、脚本、迁移、运行日志、实际命令输出、当前 git 状态。
2. 根目录 AGENTS.md。
3. dev-docs/README.md 指向的当前真源文档。
4. dev-docs/project-charter.md、dev-docs/architecture.md、dev-docs/implementation-plan.md、dev-docs/acceptance.md、当前 SPEC。
5. dev-docs/decisions/ 中的决策记录。
6. 历史对话、旧草稿、archive 文档和未索引文档只能作为线索，不能覆盖当前真源。

dev-docs/README.md 是内部真源索引。新增、失效、完成或替换任何当前真源文档时，必须同步更新该索引。

产品边界

第一版必须坚持以下边界：

• 只做本地单用户 Web MVP，不做 App、小程序、在线多用户账号体系和多人协作。
• 不做注册登录。
• 首个标准演示课题为“胃病数据分析”。
• 第一版聚焦数据分析与可视化类实验，不承诺支持所有学科实验。
• 公开资料处理只能面向公开可访问 URL 和用户提供的本地辅助文件。
• 不绕过登录、验证码、付费墙或访问控制。
• 不自动登录知网等受限制平台。
• 不把 L1/L2 方法参考包装成 L3 完整论文复现。
• 第一版不支持 L3 完整复现；必须识别为超范围或建议降级。
• 医学相关内容只作为教学数据分析，不提供诊断或治疗建议。
• Word 和 PPT 必须来自同一份已确认大纲、证据卡片、执行记录和图表索引，不得各自从模型临时上下文生成。

被项目负责人明确否定的方向，必须从代码、文档、计划和命名中删除，禁止换个名字继续保留。

阶段闸

每个开发切片必须按以下顺序推进：

确认当前真源
  -> 编写或确认本切片 SPEC
  -> 项目负责人批准进入该切片实现
  -> 测试先行或至少先补风险测试
  -> 核心 owner 层实现
  -> API / UI / Worker 薄接线
  -> 针对性验收
  -> 文档回写
  -> git 边界复核
  -> 项目负责人确认收口

当前 SPEC 0002 已由项目负责人确认收口。此后允许：

• 进行 SPEC 0002 的版本控制收口；
• 修复 SPEC 0002 收口复核发现的阻断问题；
• 编写并确认下一切片 SPEC。

此期间禁止：

• 进入公开资料与证据工作流的代码实现；
• 新增 URL 采集、PDF 解析、证据卡片、数据集工作区、Python 执行、Word/PPT 生成等下一切片能力；
• 安装与下一切片有关的新依赖；
• 只凭对话口头变更范围。

推理闸

编码前必须先回答并在必要时向用户说明：

• 实际要解决的问题是什么？
• 该概念由谁创建、谁调用、谁消费？
• 当前真源在哪里？
• 是否已有同职责模块、合同、schema、状态机、服务或文档？
• 唯一 owner 是哪一层或哪一个模块？
• 哪些层禁止成为 owner？
• 最保守且符合现有系统的做法是什么？
• 最大回归风险是什么，用什么命令、测试、日志、截图或用户侧证据阻断？

推理闸没有闭合，不得开始实现。

唯一 owner

共享业务语义必须进入唯一 owner 层。API、UI、Worker、脚本和大模型提示词只能做接线、展示或候选生成，不能拥有业务真相。

当前 owner 边界：

• 项目工作区核心：server/app/modules/projects/，拥有项目、课题、项目状态、项目工作区。
• 实验要求核心：server/app/modules/requirements/，拥有要求来源、结构化任务单、L0-L3、未知项、超范围项、最小变更记录。
• 大模型网关：server/app/modules/llm/，只返回可校验候选结果，不拥有业务状态。
• 数据库基础设施：server/app/infrastructure/database/，拥有引擎、会话和迁移接线。
• 文档解析基础设施：server/app/infrastructure/documents/，拥有 .docx 等文件解析适配能力。
• API 适配层：server/app/api/routers/，只做 HTTP 协议映射和结构化错误返回。
• 前端工作台：apps/web/src/，只展示状态、收集输入、触发命令、展示结果，不私造业务状态机。

后续切片的 owner 预留：

• 来源与证据核心：公开 URL、本地资料、解析文本、证据卡片、来源位置、采集状态。
• 数据集与分析核心：数据集、数据版本、字段概览、质量检查、清洗方案、分析方案、图表方案。
• 执行核心：Python 代码任务、执行请求、执行日志、表格输出、图表输出、失败状态。
• 后台任务核心：后台任务记录、任务状态、重试策略、取消状态、任务日志和 Worker 领取边界。
• 大纲与交付物核心：统一实验大纲、Word/PPT 生成请求、交付物版本、追溯关系。

创建这些 owner 前，必须先确认对应 SPEC。

设计规则

• 架构优先、设计优先、真源优先、严格验收。
• 不从 UI、HTTP handler、prompt、临时脚本或兼容分支倒推核心业务语义。
• 先定义合同、schema、状态、错误和 owner，再做 adapter 接线。
• 抽象只在减少真实复杂度、定义必要边界或匹配现有模式时引入。
• 禁止补丁式开发：不得用散落 if、临时硬编码、全局 flag、固定 sleep、假数据、伪健康状态或 prompt 文案绕过架构问题。
• 禁止无意义兼容旧路线。旧字段、旧接口或旧产品残影污染当前合同前，必须先和项目负责人确认取舍。
• 不为了速度删除对账、变更记录、确认点、追溯字段、错误原因、执行日志或用户可见状态。
• 生成物只读不手改。发现 dist/、迁移生成物、schema/codegen 输出或带有“不要编辑”标识的文件时，必须找到源文件和生成命令。
• 外部输入、文件大小、请求体、响应体、队列、缓存、重试、超时、后台任务和执行产物必须有上界或降级策略。

技术栈适配规则

前端

• 遵守 Vite 项目结构，index.html 位于 apps/web/ 根目录。
• React Router 只负责页面路由。
• TanStack Query 负责接口请求、缓存、刷新和任务状态轮询。
• 前端不得判断 L0-L3、任务归类、实验结果真实性或项目阶段推进。
• 前端错误展示必须消费后端结构化错误，不得把裸异常当用户提示。
• UI 改动必须尽可能做真实页面加载或浏览器验收；没有可用浏览器工具时，必须记录替代证据和未执行项。

后端

• FastAPI 路由只做协议映射。
• Pydantic 合同负责请求、响应和大模型结构化输出校验。
• SQLAlchemy 模型和 Alembic 迁移必须同步。
• 可恢复错误必须使用 AppError 或等价结构化错误返回，不得裸异常、静默吞错或向前端返回堆栈。
• 不在业务模块中直接调用 DeepSeek SDK、HTTP 接口或写死模型名。
• .docx、PDF、HTML、CSV、Excel 等解析必须通过基础设施适配器或后续明确 owner 承载，不得散落在路由中。

数据库与文件

• V1 使用 SQLite；不得把核心业务绑定到 SQLite 私有能力。
• 迁移必须通过 Alembic 管理。
• 本地文件必须写入项目受控工作区，不允许用户指定任意宿主机路径。
• 路径、文件名和上传内容必须做边界校验。

Python 执行

• V1 Python 执行必须是应用托管的受控环境。
• 用户不应手动安装 pandas、numpy、matplotlib 等分析依赖作为正常路径。
• 执行必须限制工作目录、运行时间、依赖白名单、输出大小和日志大小。
• 禁止 shell=True 和任意宿主机目录访问。
• 没有真实执行记录时，不得生成或宣称实验结论。

测试与验收

声明“完成”“通过”“修好”前，必须有本轮实际运行过的证据。

当前基础验收命令：

server/.venv/Scripts/python.exe -m pytest
server/.venv/Scripts/python.exe -m alembic upgrade head
npm.cmd run lint
npm.cmd run build

验收规则：

• 后端业务合同变化必须有服务层或 API 层测试。
• API 行为变化必须验证结构化错误、成功响应和状态推进。
• 数据库变化必须跑 Alembic 迁移，最好使用全新临时 SQLite 文件。
• 前端变化必须跑类型检查和构建。
• UI 行为变化应做浏览器点击或截图验收；若工具不可用，必须说明原因和替代证据。
• warning、类型告警、lint warning、生成物漂移、文档索引缺失和未闭合占位项都按缺陷处理；除非明确记录为非本轮债务，否则不能带着它们声称完成。

当前已知非阻断债务：

• SPEC 0002 后端测试中存在第三方 fastapi.testclient 对 httpx 的弃用提示，已在 dev-docs/acceptance.md 记录为非本轮阻断债务（TD-001 已于 2026-07-22 关闭：安装 httpx2 2.7.0 并在 dev 依赖新增 httpx2>=2.0.0，验证 569 passed 0 warnings）。
• V1.0 端到端验收已于 2026-07-22 用 browser_use agent 完成真实浏览器点击截图验收，截图保存在 dev-docs/e2e-screenshots/，详见 dev-docs/e2e-acceptance-report-v1.0.md（TD-003 已关闭；TD-005 本身已于 SPEC 0016 清理本章节过时表述）。

文档规则

• 项目自有文档必须中文。
• 代码行为、架构边界、API 合同、schema、验收标准、依赖和产品语义变化后，必须同步回写 dev-docs/。
• 影响产品方向、功能边界、技术路线或验收标准的变更，必须更新 project-charter.md 并新增或更新 dev-docs/decisions/。
• 影响阶段、任务状态或切片收口的变更，必须更新 dev-docs/README.md、dev-docs/acceptance.md 和相关 SPEC。
• 内部架构、验收、实施计划、决策记录、漂移控制和交接进入 dev-docs/。
• 外部用户文档只写使用、部署、配置、公开 API、运维和排障，不混入内部治理历史。
• skills/ 下下载的第三方 skill 或 plugin 源码属于外部 vendored 资料，不受“项目自有文档必须中文”的自动改写要求约束。

依赖与网络

• 新增依赖前必须确认它属于当前已批准切片。
• 新增依赖必须更新 dev-docs/dependency-review.md 或新增依赖决策记录。
• 真实密钥不得写入仓库，只能通过环境变量或本地未提交配置读取。
• SPEC 0001 和 SPEC 0002 不访问真实 DeepSeek，DEEPSEEK_API_KEY 可留空。
• 若命令因沙箱网络或权限失败，必须记录失败证据；需要宿主权限时按工具权限流程请求，不得绕过。

版本控制

• 提交或发布前必须确认 git root、git status --short --untracked-files=all、忽略规则和 staged 列表。
• 禁止 git add .。
• 只 stage 与当前任务相关的文件。
• 不得 force-add ignored 文件，除非项目负责人明确点名路径并要求。
• 不得回滚、覆盖或吸入用户未授权改动。
• 不使用破坏性 git 命令，除非项目负责人明确要求并确认风险。
• .obsidian/、2026-06-16.md、*.canvas、*.base、.tmp/、dist*/、.venv/、*.egg-info/ 必须留在 git 外。

版本收口上传规则

• 每完成一版或一个已确认开发切片，必须进行一次 git 版本控制收口。
• “完成一版”必须同时满足：本版范围或 SPEC 已确认、实现已完成、验收证据已记录、相关文档已回写、项目负责人已确认收口。
• 收口顺序必须是：复核当前真源与 SPEC -> 运行匹配风险面的验收命令 -> 更新 dev-docs/acceptance.md、dev-docs/implementation-plan.md、相关 SPEC 或决策记录 -> 执行 git 边界复核 -> 精确 stage -> commit -> push 到已配置远程仓库。
• commit 前必须查看 git status --short --untracked-files=all、staged 列表和关键 diff；禁止在未确认 diff 的情况下提交。
• commit 信息必须使用中文，并包含本版或切片编号，例如 完成 SPEC 0002 实验要求输入与结构化任务单。
• push 只能在项目负责人确认本版收口后执行；如果远程仓库未配置、鉴权失败或网络不可用，必须保留本地 commit，并在验收记录或交接中说明未上传原因。
• 默认不自动打 tag；只有项目负责人明确要求发布版本号时，才创建 tag 并上传。
• 不得把运行产物、本地配置、密钥、agent 记忆、虚拟环境、构建产物或被忽略的私人文件作为版本收口内容。

错误分级

审查、实现和验收时必须分级：

• 阻断问题：破坏核心功能、owner 边界、安全/隐私、数据真相、构建测试、用户关键体验或当前目标链路；当轮必须收掉。
• 设计风险：不一定立即破坏，但会导致架构漂移、运行面失控或后续难维护；必须说明取舍和验收入口。
• 可记录债务：不影响本轮目标链路，可暂缓；必须说明不处理原因和后续入口。
• 无关优化：不进入本轮范围，禁止借机扩大改造。

没有证据的担忧不能写成阻断；有证据的阻断也不能降级成“后面再说”。

必须停止并询问

出现以下情况时必须停止并询问项目负责人：

• 用户需求、当前代码、agent 宪法、真源文档或验收结果互相冲突。
• 需要进入未确认的新切片实现。
• 需要创建、改写或废弃根宪法、真源索引、产品命名、核心 API、schema、权限模型、部署流程或公开文档。
• 需要删除旧 API、字段、路由、配置、缓存、生成合同、部署脚本或迁移历史。
• 需要同时支持互斥产品路线。
• 当前证据表明用户目标会损害架构、数据、安全、权限、用户体验或长期可维护性。
• 上下文不足以判断 owner 边界，并且猜测会造成不可逆或大范围影响。

停止时必须给出冲突证据、可选处理方向、推荐方向和需要确认的问题。

宪法维护规则

修改本文件前，必须说明：

• 为什么现有规则不够；
• 改动会影响哪些 agent 行为；
• 至少一个真实场景或压力测试如何验证改动有效。

本次宪法从通用模板收敛为项目专用版本，压力测试场景为：后续 agent 想直接进入 URL 采集、证据卡片、Python 执行或 Word/PPT 生成时，本文件必须要求其先等待 SPEC 0002 收口确认，并先编写和确认下一切片 SPEC。

交接规则

当上下文过大、任务尚未闭合、需要换窗口或交给另一个 agent 时，必须产出可直接复制的交接文本，包含：

• 当前目标和已确认的产品/架构边界；
• 当前 git 状态、已改文件、未提交文件和忽略边界；
• 已完成工作、实际验收命令和结果；
• 未闭合风险、漂移警告和禁止触碰的用户改动；
• 下一步最安全命令和停止条件。