Imported from YiFanAWA/lab-report-assistant (
AGENTS.md). Install upstream withnpx 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 接入,不得写死模型名或供应商私有接口。
当前真源
事实冲突时按以下顺序判断:
- 当前源码、测试、脚本、迁移、运行日志、实际命令输出、当前 git 状态。
- 根目录
AGENTS.md。 dev-docs/README.md指向的当前真源文档。dev-docs/project-charter.md、dev-docs/architecture.md、dev-docs/implementation-plan.md、dev-docs/acceptance.md、当前 SPEC。dev-docs/decisions/中的决策记录。- 历史对话、旧草稿、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 状态、已改文件、未提交文件和忽略边界;
- 已完成工作、实际验收命令和结果;
- 未闭合风险、漂移警告和禁止触碰的用户改动;
- 下一步最安全命令和停止条件。
