lexgo/AGENTS.md

Agent 开发规则

本仓库采用 DevHarness 工作流：需要工单的任务以 Gitea 工单作为需求、变化、实现、测试、提交和验收的事实来源；符合轻量模式直接实施条件的任务以用户确认范围、Git 提交和结果报告留痕。Gitea Wiki 是长期开发文档的事实来源，Git 是代码与版本绑定资料的变更记录。docs/ 默认保存核心 Wiki 的只读镜像，docs/task/ 只保存人工明确要求的专项或历史兼容快照。人负责确认目标与必要验收，Agent 负责检查、实现、测试和留下与风险相称的证据。

开始工作前先阅读任务涉及目录中的 AGENTS.md。目录越深的规则越具体，但不得削弱上级安全规则。

项目档案 按需阅读，不作为每次任务的固定前置。首次接手项目、治理模式不清楚，或出现下列情况之一时必须读：需要环境、配置或凭据来源；需要确认目录边界；需要判断子项目与交付单元划分；需要 DevHarness 来源与基线；需要项目专用验收要求。同一会话已经确认且没有变化时不重复读取；只为查命令不必打开项目档案。

语言与术语

• 用户可以使用中文、英文或合理的中英混合语言交流；默认使用中文分析、回复、编写工单和维护内部项目文档。
• 代码标识符、命令、参数、路径、文件名、API 名称、协议名、日志和错误原文保持原样；合理的英文术语可以保留，必要时首次出现补充简短中文解释。
• 用户明确要求某次回复或交付物使用其他语言时，按该次要求执行；不得为了语言统一改写事实、接口契约或影响搜索和执行的原文。

常用命令

所有命令默认从仓库根目录执行，与项目档案保持一致。

用途	命令
查看工作区	git status --short --branch
检查模板结构	python dev_scripts/harness.py check --strict
运行单元测试	python -m unittest discover -s tests -v
导出核心 Wiki 镜像	python dev_scripts/harness.py sync
快速检查核心 Wiki 镜像	python dev_scripts/harness.py sync --check
深度检查核心 Wiki 镜像	python dev_scripts/harness.py sync --deep-check
创建可选任务快照	python dev_scripts/harness.py archive 123 "修复登录超时"
增量导出已有快照	python dev_scripts/harness.py export
全量导出已有快照	python dev_scripts/harness.py export --all
后端二进制运维	./server/lexgo migrate|bootstrap|serve|backup|restore|verify（部署机无需 Python）
检查部署依赖	python scripts/ops.py install-check
备份实例	python scripts/ops.py backup --out <目录>
恢复到空库	python scripts/ops.py restore --dump <备份.sql.gz> --database <库名> --confirm
校验实例	python scripts/ops.py verify --database <库名>

1. 永久规则

• 密码、令牌、Cookie 和私钥只从环境或安全配置读取，不得写入代码、Git、日志、工单、Wiki 和文档；人工授权不改变此边界。
• 任务确有需要且得到人工明确授权时，可以在授权范围内处理真实个人数据或生产数据；只使用完成任务所需的最少数据，不把无关副本扩散到代码、Git、Wiki、工单、测试数据和日志，证据优先使用脱敏摘要。明确为虚构的测试数据无需形式化脱敏，但必须能与真实数据区分；来源不明时按真实数据处理。
• 未经人工明确授权，不执行发布、付款、删除数据、破坏性迁移或其他不可逆操作；已经获得有效授权时按下节执行。
• 保留用户已有和任务无关的工作区改动，不擅自重置、覆盖或混入提交。
• 发现需求与安全规则、已确认方案或现有数据冲突时，先停止实施并说明影响。
• 测试结果必须真实；未执行或无法覆盖的验证必须明确记录。

项目专用红线写入本文件的“项目专用规则”或对应子目录的 AGENTS.md，不要散落在聊天记录中。

明确授权后的执行

• 当前聊天中用户给出的明确指令，或 Gitea 工单中能够归属于有权人工的明确授权，可以作为执行依据；不要求把聊天授权重复复制到工单后再确认。
• 授权必须能识别操作、对象和范围。Agent 自动生成的工单、草稿、摘要或对用户意图的转述，不能单独构成人工授权。
• 获得有效授权后，只核对准确目标、授权范围和当前状态等最小必要前提，然后执行；不得仅因操作不可逆而重复询问或拒绝。
• 授权只适用于明确范围，不自动覆盖相邻对象或后续任务。环境、对象、范围或影响发生实质变化时，原授权不再覆盖变化部分，应重新确认。
• 平台自身强制的审批、安全策略或权限限制继续有效；不能把项目内授权解释为绕过平台限制。
• 执行完成后报告实际结果、影响范围以及是否可以恢复；失败时报告已完成部分和当前状态。

2. 哪些改动需要工单

项目治理模式记录在项目档案。使用 DevHarness 创建新项目时默认采用轻量模式；只有项目负责人明确选择标准或高风险模式并在项目档案记录理由时，才改变项目默认模式。未明确填写治理模式时按轻量模式执行并提示补写，不因此阻塞产品开发。DevHarness 上游模板自身继续采用标准模式。任务真实风险高于项目模式时，只升级该任务。

• 轻量模式：文案、注释、格式、局部样式或布局、预期行为明确的小 Bug，以及不改变接口、数据结构、权限和安全边界的单模块低风险调整可以直接实施。完整独立需求、新页面或跨模块功能，以及涉及 API、数据结构、权限、安全、迁移或范围不明确的变化必须建单。
• 标准模式：纯文档措辞、格式化、内部标识符改名和确定不改变行为的小整理可以直接实施；新功能、缺陷修复、重构及用户可感知的行为变化必须建单。
• 高风险模式：只读诊断和不改变行为的文档整理可直接进行；正式行为变化必须建单，尚未取得有效人工授权时等待确认，已经取得时不重复确认。

直接实施项无需为了留痕补建工单；只做必要的工作区与安全检查、受影响范围的最小测试并报告结果。涉及权限、安全、支付、真实个人或生产数据、迁移、并发、删除和不可逆操作时始终按高风险处理；已有有效人工授权时不重复索要确认。无法判断时先澄清或建单，不按代码行数判断风险。

3. 需求到实施

1. 先复述目标，阅读相关代码、日志和文档，区分事实与假设。
2. 给出目标、非目标、方案、影响范围、风险、回退方式、验证方法和文档影响。
3. 需要方案确认的任务在用户明确确认前，只做只读诊断和方案整理；轻量模式下目标与预期行为已经明确的直接实施项不增加单独方案门禁。
4. 需要工单时，方案确认后先建单再修改；符合直接实施条件时不建单。
5. 建立新工单不要求其他工单已经完成；开始实施前检查工单声明的前置工单。真实依赖未满足时保持“待实施”，允许并行时必须写明原因。
6. 开始实施前检查分支和工作区，明确哪些现有改动不属于本任务。
7. 严格按工单范围实现；新发现的问题先记录，不顺手混入当前任务。
8. 执行与风险相称的测试，把关键结果和未验证部分更新到工单。实施过程中出现计划外、当前无法解除的问题时才标记“阻塞”。
9. 只有长期事实变化时才修改 Wiki、读取确认，再运行 python dev_scripts/harness.py sync 导出本地镜像；没有长期文档影响时在工单说明原因并跳过 Wiki 同步。不得直接编辑镜像后反向覆盖 Wiki。

工单正文保存用户确认的任务基线；根因、范围、方案、风险或阻塞发生重要变化时追加评论。完成实现后用一条评论集中记录最终差异、测试、未验证内容、提交哈希和文档影响；用户验收后再追加验收时间与结论，不重复覆盖或抄写已有证据。

需要建单而 Gitea 不可用时，输出完整工单草稿并说明阻塞。不得把直接实施豁免扩展到本应建单的任务。

Gitea 交互与工单最小读取

• 所有 Gitea 工单和 Wiki 的查询、创建、更新、评论、状态变更及关闭操作，优先使用项目已配置的 Gitea MCP。
• MCP 不可用或不支持所需操作时才回退 Gitea API，并在当前工单记录回退原因；初始化阶段尚无工单时记录到初始化工单草稿，建单后补回。凭据只从环境或 MCP 安全配置读取。
• 首次接手任务时读取工单确认基线和完成当前判断所需的评论，不因节省 Token 跳过范围、依赖、安全、验收或重要变更。
• 同一任务、同一会话且关键前提未变化时，复用仍有效的工单事实，优先关注当前状态、最新评论和首个未完成步骤，不重复分析已经确认且仍有效的内容。
• 会话、代码、配置、依赖、凭据、远端状态或关键前提变化，任务基线不清楚，或最新评论声明历史需求、方案、范围、风险或验收发生变化时，重新读取必要历史；无法判断影响范围时读取完整工单。
• 连接器不支持评论分页或增量读取时允许读取完整工单，但不得把“已读取全文”误当成需要重新分析全部历史，也不得为规避完整读取而新增本地工单、缓存或第二事实来源。
• 正确性、安全规则和已确认范围优先于 Token 优化；读取边界存在不确定时补读必要证据。

新项目 Wiki 初始化门禁

• 从本模板创建新项目时，先创建 Gitea 远端仓库并启用工单和 Wiki，再配置 wiki-docs.json；不得把模板自带的本地 docs/ 当作新项目 Wiki 已初始化的证据。
• 优先使用项目已配置的 Gitea MCP 查询和写入 Wiki；MCP 不可用或不支持所需写操作时，才使用 Gitea API，并在初始化工单记录回退原因。凭据只从环境或 MCP 安全配置读取。
• 先查询线上页面列表；Home 不存在时必须先创建 Home，在线回读正文并记录 revision，然后再逐页创建或更新其他核心映射页面。
• 每个核心页面写入后必须在线回读并取得 revision。页面缺失、回读失败或没有 revision 时停止初始化，不得开始产品代码。
• 产品编码前必须运行 python dev_scripts/harness.py sync --verify；全部成功才表示线上 Wiki 和核心镜像初始化完成。

按治理模式选择最小设计证据

• 轻量模式的小 Bug、局部样式或布局、复用现有规范的组件调整无需完整原型；一句话、现有界面或标注截图足以确认时停止增加设计材料。
• 完整独立需求、新页面、重大交互或导航变化需要工单；只有存在明显交互不确定性、用户明确要求，或返工成本显著时，才制作 Quant-UX 或其他可审阅原型。
• 标准模式的新页面、独立用户功能和重大交互使用可审阅原型；小范围 UI 使用最低成本的文字、截图或低保真证据。
• 高风险任务按影响补充技术设计、数据和权限边界、回退方案；尚未取得有效人工授权时等待确认，已有授权时不得重复确认。非 UI 任务不制作无意义的 UI 原型。
• 上述完整原型形成待审核版本后，默认直接通过 Quant-UX 或其他设计工具的线上链接审核，不要求每次导出本地 HTML。工单必须记录可访问链接、版本/revision 或确认日期、审核版本识别方式、确认人、确认时间和覆盖范围；线上链接无法访问或无法区分版本时停止审核，等待用户确认等效方案。
• 只有用户明确要求 导出原型 #N、导出全部原型，或项目专用规则明确要求离线交付时，才导出到 prototypes/<工单号>/<版本>/index.html。已确认的本地快照不得原位覆盖；版本目录内资源使用相对路径，导出后检查入口、主要交互和资源完整性，但不自动提交。
• 后端、接口、数据处理和定时任务不强制 UI 原型；仅在存在设计选择或中高风险时确认必要的架构、API、数据、状态或流程设计。恢复既有确认行为的 Bug 可以复用原设计、截图、复现步骤或已有验收证据。
• 需要设计证据的工单记录链接或路径、版本/revision 或日期、状态、确认人、确认时间和覆盖范围；没有 UI 原型时记录替代技术设计或原因。
• 页面结构、主要流程、状态、权限、异常处理或验收结果变化时，必须更新原型或文字需求并重新确认后再继续正式编码。
• 草稿原型可以用于讨论；写入 Git/Wiki、多人协作或单独实施时建立设计任务。草稿和经明确授权的隔离技术验证都不得直接作为生产实现。
• 设计工具无法生成用户明确要求的可用 HTML 时，在工单记录限制并停止该导出或离线交付，等待用户确认等效方案；线上原型可访问且版本明确时不因此阻塞线上审核。纯显示文案、小范围 UI、非 UI 需求和恢复既有行为的 Bug 不强制建立完整线上原型或导出 HTML。

自然语言快捷指令

快捷指令只是本工作流的自然语言别名，不得绕过方案确认、前置依赖、安全规则、工单范围、Wiki 主源、必要验证或人工验收：

• 只分析：只读检查并给出方案；不建单、不修改，停在等待确认。
• 建工单：根据已确认方案创建单元任务工单；建单后停止，不修改代码。
• 执行工单 #N：检查工单和依赖，实施、测试、提交、推送并回写证据；仅在明确要求时创建任务快照；停在“待验收”。
• 建工单并做：依次建单和执行，建工单，做、建工单,做 含义相同；停在“待验收”。
• 继续工单 #N：优先核对当前状态、最新评论、Git 和必要 Wiki 证据，从首个未完成步骤继续；关键前提未变化时不重复读取和分析仍有效的内容。
• 检查工单 #N：只读核对范围、验收、测试和证据并输出报告；不自动修复。
• 同步文档：按 revision 增量读取 Wiki、导出核心 docs/ 并快速检查一致性，不处理任务归档；不修改 Wiki、不自动提交。只有明确要求深度检查时才逐页下载正文。
• 导出原型 #N：人工触发导出指定工单已确认的原型版本，按工单和版本写入 prototypes/；不扩展范围、不自动提交。
• 导出全部原型：人工触发导出当前项目已明确范围内的全部已确认原型；不自动提交。
• 导出任务归档：人工触发 python dev_scripts/harness.py export，只导出新增或 revision 已变化的任务归档；不删除本地文件、不自动提交。
• 导出全部任务归档：人工触发 python dev_scripts/harness.py export --all，读取并导出全部线上任务归档；不删除本地文件、不自动提交。
• #N 验收通过：仅在用户明确验收后，在工单追加验收结论；按需更新真实变化的长期 Wiki，推送、同步父工单并关闭任务；不创建或导出任务归档。

方案未确认或前置依赖未满足时，实施类指令必须停在对应门禁；除 #N 验收通过 外，快捷指令不得关闭待验收工单。原型和任务快照的导出必须由用户明确提出或项目专用规则明确要求，其他指令不得隐式执行。Gitea 工单不导出全文，docs/task/ 只是可能不完整的专项或历史兼容快照。详细语义见 开发工作流。

需求记录与流转

• 创建单元任务工单时，记录原始需求的来源、提出时间，以及能表达用户目的、场景和限制的少量关键原话或脱敏摘要；不得臆造用户原话。
• 工单中的目标、非目标、已确认方案、验收标准和文档影响构成确认后的正式任务需求。
• 影响范围、接口、数据、风险或验收的需求变化必须记录日期、内容、原因和用户确认；会改变已确认结果时先更新工单并等待再次确认。
• 不复制完整聊天，不保存 Agent 内部推理，不写入密码、令牌、Cookie 或私钥；任务需要处理真实个人或生产数据时只记录必要的脱敏摘要，不复制原始数据。
• 长期有效的产品需求、业务规则和系统边界进入对应 Wiki 主题页并导出核心 docs/；单次任务的完成结果和验收保留在工单正文与评论。只有用户明确要求专项快照或项目专用规则要求时才创建 Wiki 任务快照并按需导出 docs/task/。Gitea 工单全文不导出到仓库。

详细记录边界见 开发工作流 与 业务规则和术语。

效率与范围控制

本节只用于减少无关工作和重复检查，不得削弱安全规则、已确认目标、需要工单时的工单范围、必要测试、必要的长期文档同步和 Git 提交要求。

严格控制范围

• 默认严格按用户确认的目标和单元任务范围执行，不主动扩展相邻问题。
• 除非任务目标、仓库强制规则或已发现的真实阻塞需要，不新增额外文档、辅助脚本、备份文件、框架、重构或扩展性设计。
• 不执行与本次验收无关的验证；安全检查、受影响范围测试、回归测试和仓库规定的闭环验证不属于“额外验证”。
• 新发现的相邻问题最多用一句话提示或记录到独立工单，不自动修复或混入当前提交。

渐进执行和修复

• 完成已知必要的安全与前置检查后，优先执行能够产生真实反馈的最小命令。
• 一次执行后先处理首个可定位、可行动的真实错误，不同时猜测并修改多个可能原因。
• 采用“执行 → 查看错误 → 最小修复 → 从失败点继续或按需重跑”的闭环。
• 不在真实证据出现前堆叠与已知风险无关的预防性检查。
• 涉及凭据、权限、安全、数据、迁移、并发、删除、发布或不可逆操作时，必须先完成相应最小前置检查；已有有效人工授权时不得增加重复确认，不得通过试错获取风险反馈。

复用已验证事实

• 在同一任务和同一环境状态下，已经通过的路由、连接、恢复和环境检查不重复执行。
• 只有会话、环境、代码、配置、依赖、凭据、远端状态或关键前提发生变化时才重新检查。
• 代码修改后，受影响测试和最终验收必须重新执行；提交前工作区检查、推送前远端分支检查不得因为之前通过而省略。
• Skill 和平台规则是否需要重新读取，按当前 Agent 平台和任务触发规则执行，不自行跳过。

明确停止条件

• 完成用户确认的验收标准和仓库规定的必要闭环后立即停止，不主动继续优化。
• “最小验收条件”包括当前工单要求的实现、必要测试、文档影响处理、Wiki 镜像检查、提交和证据回写，不等同于功能第一次运行成功。
• 未影响当前验收的相邻问题只提示或建单，不顺手处理。

4. 工单层级

• 需要工单时，单元任务是正式实施单位，记录方案、范围、验收标准、过程和测试结果；直接实施项不进入 Epic/MVP 层级。
• Epic 和 MVP 只维护目标、风险、汇总及 - [ ] #编号 / - [x] #编号 子工单索引，不复制单元任务全文。
• 新任务先建单元工单，再把编号同步到所属 MVP 和 Epic。
• 详细层级、状态和模板入口见 开发工作流 与 业务规则和术语。

5. 实施中的变化

• 范围、接口、数据结构、依赖、验收标准或风险变化时，先更新单元工单。
• 变化影响 MVP 或 Epic 时，同时更新父工单。
• 会改变用户已确认结果的变化，更新工单后必须再次等待用户确认。
• 阻塞、失败方案和新发现根因不能只留在聊天或代码注释中。
• Wiki 页面删除、重命名或事实源边界变化时，必须先更新工单并等待用户确认；同步工具不得自动传播删除或重命名。
• 工单状态应使用：待确认、待实施、进行中、阻塞、待验收、已完成。

6. Git 与验证

• 提交只包含当前任务相关文件。
• 有工单时提交信息引用工单号，例如：fix: 修复登录超时 (#123)；直接实施项不制造工单号。
• 不为流程制造空提交。
• 优先运行项目档案中记录的格式检查、静态检查、单元测试和必要的集成测试。
• 不能验证的真机、生产、迁移或并发行为必须写入工单；存在明确要求的任务快照时再同步记录。
• Windows 环境优先使用当前已配置的 PowerShell；可选择时优先 PowerShell 7 pwsh.exe，不得仅为设置编码重复启动一层 PowerShell。
• Windows 命令不得默认套用 Bash 的 heredoc、变量、路径、引号或转义语法；只有明确调用 Bash、WSL 或 Git Bash，并确认路径与编码边界时才使用。
• PowerShell 中不需要变量展开的正则优先使用单引号；复杂正则优先使用变量或 rg -e，不得为了避开转义而改变查询语义或堆叠重复搜索。
• 多行 Python 使用单引号 PowerShell here-string 管道给 python -；起始标记后立即换行，结束标记单独占一行，不使用 Bash heredoc。
• foreach、if 等语句块的输出进入管道前使用 $()、@() 或变量；普通命令输出直接进入管道。
• rg 使用真实目录配合 -g/--glob 筛选路径；只有确实需要实体路径列表时才用 Get-ChildItem 展开并传递 .FullName。
• 文本文件读写在命令支持时显式指定 UTF-8；文件解码和控制台输出分别处理，只有出现真实乱码或已知宿主非 UTF-8 时才设置当前进程的输出编码或 Python UTF-8 环境变量。
• 不得默认使用 -ExecutionPolicy Bypass；只有可信 .ps1确实被执行策略阻止且没有更小替代方案时，才对该次进程使用并在工单记录原因。

7. 完成和验收

直接实施项完成最小测试、必要文档影响处理和 Git 提交后报告结果即可，不创建工单状态或补写验收记录。以下流程适用于有工单的任务：

1. 逐项完成验收、测试和实现提交，在工单追加最终证据评论，记录最终方案、差异、结果、提交、遗留问题和文档影响。
2. 工单保持“待验收”，用户没有明确验收通过前不得关闭。
3. 有长期文档影响时，读取确认 Wiki，运行 python dev_scripts/harness.py sync --check 检查核心镜像，并把页面 revision 和镜像提交哈希写回工单；没有长期文档影响时不运行 Wiki 同步。
4. 用户验收通过后，在工单追加验收时间和结论，关闭单元工单，并同步更新 MVP 和 Epic；没有真实变化的 Wiki 不重复更新或检查。
5. 默认不创建任务归档。只有用户明确要求专项快照或项目专用规则明确要求时，才运行 python dev_scripts/harness.py archive <编号> "<短标题>"；export 和 export --all 同样必须显式触发。

MVP 内所有单元任务通过后才能做 MVP 集成验收；MVP 通过后才能关闭 MVP。Epic 的全部范围完成后才能关闭 Epic。

详细证据回写、可选快照和文档同步边界见 开发工作流。

8. 可维护性

• 优先使用直白、常见的实现；不要为了少写几行引入晦涩技巧。
• 类和函数保持单一职责，名称表达业务含义。
• 注释解释原因、边界和风险，不逐行翻译代码。
• 错误必须可定位，不静默吞掉失败。
• Wiki 文档先写结论和用途，再写步骤；示例命令应可直接复制，本地 docs/ 由同步工具生成。
• 面向初级维护者说明从哪里开始读、怎样运行和怎样验证。

修改风险

• 低风险修改可由初级程序员在 Agent 协助下处理；接口、配置、依赖、跨模块逻辑和数据结构由 Agent 实现并验证。
• 权限、安全、并发、迁移、支付、删除数据和不可逆操作属于高风险；未取得有效人工授权时必须停止，由 Agent 分析并等待确认，已经取得时完成最小必要核对后执行。
• 风险按影响范围判断，不按代码行数判断；示例见 常见修改指南。

文档影响

• 每个单元任务必须在工单中选择“无长期文档影响并说明原因”或列出需要更新的 Wiki 页面。
• 启动、测试、部署、排错命令，模块入口、目录职责、主要调用路径，配置、API、数据结构、状态、业务规则、安全边界、日志位置发生变化时，必须更新对应 Wiki。
• 部署命令变化时，有常驻服务的项目更新自己的 Deployment-and-Operations 页面（由 部署文档模板 复制建立）；没有常驻服务的项目记录为无部署文档影响，不创建空的部署页。
• 普通内部重构只有在入口、行为、配置和验证方式均未改变时，才可以记录为不影响长期文档。
• 必需核心页面及结构以 python dev_scripts/harness.py check --strict 和 新项目文档初始化 为准；稳定文档与可选历史快照的分工见 开发工作流。

9. 引导提交例外

从本模板创建全新仓库时，Gitea 远端和工单尚不存在，允许一次不带工单号的初始引导提交。该提交只能包含仓库骨架、Harness 规则和远端配置准备，不能包含产品功能。

远端建立并推送后，这个例外立即失效。

10. 项目专用规则

• 长期开发文档以 Gitea Wiki 为事实来源；需要工单的任务证据以 Gitea 工单为事实来源，直接实施项以 Git 提交和结果报告留痕。docs/ 默认保存显式映射生成的核心只读镜像，docs/task/ 是人工明确要求的专项或历史兼容快照，可能不完整或不是最新状态。
• 核心 Wiki 与镜像的固定顺序是：修改 Wiki → 读取确认 → 导出核心 docs → 校验差异 → 提交镜像。
• 默认不创建任务归档；archive、导出任务归档 或 导出全部任务归档 必须由用户明确提出或项目专用规则明确要求，且不得自动传播删除或重命名。
• 同步配置只允许写入 docs/ 下的 Markdown；发现镜像有未提交修改时必须停止。
• Gitea 凭据只通过进程环境或 MCP 安全配置提供，不得写入仓库。
• dev_scripts/ 只存放 DevHarness 自身工具；业务项目的通用脚本必须使用独立目录，不得混放。

LexGo 已确认项目决策

• 治理模式：轻量。数据库：MySQL 8（用户于 2026-09-10 确认）；具体小版本在工程验证后锁定。

• 远端：https://git.ilapage.cn/OPC/lexgo.git；分支 main。不得把邻接 dev_harness 工作区当成本项目工作区。

• 工程基础 #2 已通过用户验收：server 基于指定 go-admin 选用模型扩展账号/会话 API，admin 复用 go-admin-ui，learner 为独立 Vue 3 + TypeScript + Vite 工程。默认英语；阅读、导入、词典与复习尚未接入产品；#3 独立 Python NLP/词典验证小样已通过用户验收。

• 原四份研究保留为历史参考；PostgreSQL 建议被 MySQL 8 决策覆盖，U/A/N 索引用于追踪而不是批准所有范围。

• 用户/语言数据所有权、Unicode 原文位置、任务和复习幂等、完整备份恢复是后续方案的必要验收边界。

• 当前 MCP 连接其他 Gitea 站点，需使用目标站点 API 时记录原因；凭据仅从安全配置进入进程。

• DevHarness 基线 ecab8995026e57f2c28f307a6aa32b871cb3163f；工具保持原样，不为跳过门禁修改检查。

• 管理端采用用户指定的 go-admin/go-admin-ui，固定参考 commit 见项目档案；替换历史 gin-vue-admin 建议，不修改源目录，不直接复制源仓库配置或运行数据库。

• 学习端通过 create-vue 新建，采用 Vue Router、Pinia、Element Plus、Vitest + Playwright；与 go-admin-ui 分开构建，共用基于 go-admin 扩展的 Go 后端和 MySQL 8。阅读器、划词、短语与复习组件定制，未决定移植 LinguaCafe 前端。

• 技术方案不代表候选需求或阶段范围全部获批，不因技术选型自动启动产品实现。

• 用户已确认 MVP 定位为“支持多账号、数据独立的自托管学习工具”，先邀请少量用户使用。F/X 的筛选结果以需求总览为准，不能把定位确认扩展为全部研究功能批准。

• F01～F12 已确认进入 MVP，X 系列本轮不纳入；用户指定 Quant-UX 原型，原型审核后才拆实施工单。默认学习语言已确认英语，原型语料为虚构样例；不导出本地 HTML。

• 原型尽量减少说明文字，与目标页面一致：产品页只保留实际字段、操作与必要反馈；功能编号、模拟边界和审核说明放在独立导览或工单。

• 当前 Quant-UX v1 已获用户验收（工单 #1 评论 7498），实施总览为 #16、单元工单为 #2～#15；LinguaCafe 源码对照与桌面划词验证已由 #4 交付并获用户验收；真机详细测试证据缺口仍保留。

• 学习端和管理端均使用账号（用户名）＋密码登录，账号不要求邮箱格式，邮箱不作为必填登录标识；后端独立校验管理权限与本人学习数据归属。

• 已验证 MySQL 8.4.3，本机 127.0.0.1:3308；开发库 lexgo_dev、测试库 lexgo_test_issue2。密码只从环境或忽略的 .env.local 读取。迁移测试只能使用 lexgo_test_ 前缀专用库，不能借用其他数据库。

• 后端命令使用 python scripts/server.py migrate|bootstrap|serve|build|test|test-integration；仅显式 migrate 修改表。bootstrap 只接受尚无账号的 LexGo 库，不覆盖已有管理员。Go 1.26.5、Node 22.22.1、pnpm 9.15.1；两端分别构建。

• #18 登录日志与操作审计已通过用户验收：schema v2 显式迁移；日志只保存白名单字段，禁止保存凭据、请求/响应正文及私人学习内容。仅管理员查询，默认保留 90 天；启动/每小时及 python scripts/server.py audit-cleanup 仅清理两张审计表的过期记录。

• #3 独立小样位于 spikes/english/，使用 .local/nlp-venv/Scripts/python.exe（3.12.12）运行；固定 spaCy 3.8.7、英语模型 3.8.0、NLTK 3.9.2、WordNet 3.0。资源仅显式准备时下载，摘要见 resources.json。不得把本机无账号的实验接口用于正式学习端；后续集成仍需 Go 授权、数据归属和任务设计。原文不归一化，位置区分 cp/UTF-8/UTF-16，lemma 不自动合并学习状态。

• #4 独立阅读选择小样位于 spikes/selection/，python spikes/selection/serve.py 默认仅本机 5184。桌面鼠标/键盘与 11 项测试已验证，#4 已获用户验收并关闭；真实手机长按/手柄/滚动详细证据仍未提供；禁止把窄屏桌面当作真机验收。Intl.Segmenter 只用于 UI 范围验证，不替代 #3 NLP；释义保存只在内存。固定 LinguaCafe 源码对照和与 v1 的差异记录见架构 Wiki。

• 2026-09-11 用户确认正式 NLP/词典采用全 Go。#5 已验收并合入 main；#6 使用 Go WordNet 解析和词形候选、Go Unicode 原文分片、schema v4 共享词典资源表，不调用 Python NLP。WordNet 3.0 ZIP 来源与摘要见 server/wordnet-resource.json，许可保留在 server/WORDNET-LICENSE.txt。词形候选不等于上下文消歧，不自动合并个人学习状态；#3 Python 小样只保留历史验证。当前词典仅英语释义，个人释义输入为临时草稿，持久化归 #7。

• 2026-09-11 用户确认 #7 个人词条口径（三项由 Agent 定案）：身份为「学习者＋语言＋规范化词形」，大小写合并但不按 lemma/候选合并（dog 与 dogs 是两条记录）；首次保存默认「新词」；状态为 新词/学习中/已知/忽略，只有「学习中」带 1～7 级，对应原版 stage 2/1/0/-1～-7；例句只保存手输内容，不自动关联原文句子。schema v5 新增 lexgo_terms（唯一键加状态/等级检查约束），个人释义与共享词典分离且不进入审计日志；等级编辑 UI 归 #8/#12。

• 2026-09-15 用户确认 #15 交付口径：只交付本机可复现的安装/备份/恢复材料并在本机演练，不对外部署、不创建 release/tag、不邀请用户；生产入口与 HTTPS 只写入文档；前端由反向代理托管 dist（不改后端代码）；试用实例从空库开始、管理员由显式 bootstrap 建立、不带默认密码；备份＝MySQL 全库 dump ＋ 环境配置（凭据只存运维密码库，不进仓库/日志），不新增定时备份；性能用人造数据集实测并写明环境，只作观察不给承诺。备份/恢复规则：restore 必须 --confirm、默认只写空库、覆盖需 --force、库名必须含 lexgo 且不能是系统库、拒绝带 CREATE DATABASE/USE 的 dump，恢复前后比对源库逐表内容校验和。附件（#21）尚未实施，恢复契约目前只覆盖数据库；真实回滚、HTTPS、多机与定时备份仍未验证。部署与运维规则见 Wiki 页 Deployment-and-Operations（镜像 docs/11-deployment-and-operations.md）。

• 2026-09-15 用户确认 #14 显示与键盘口径：theme ∈ {浅色,深色,跟随系统}（默认跟随系统）与正文字号 {标准,大,特大}（1.0/1.15/1.3）按账号保存在本机 lexgo-learner-display:<账号 id>，切换账号即换成该账号偏好或默认，退出回到默认，不跨设备同步；字号经 --reader-font-scale 只作用于阅读面（正文、释义内容、复习卡），不做全局缩放；深色用 html[data-theme] ＋ Element Plus 的 html.dark，style.css 的 :root 是文件内仅有的颜色字面量；阅读位置按账号＋章节保存滚动比例与该章 content_sha256，正文换新版本后不恢复；复习页 空格/Enter 显示答案、1/2/3 评分，输入类控件与聚焦按钮的按键不被劫持，带修饰键不拦截；移动验证用 390×844＋hasTouch 的 Playwright mobile 项目（桌面项目 testIgnore: mobile-*），真机长按选择与手感仍需人工确认，不得用模拟设备结果冒充真机。本单无 schema 与接口变化。

• 2026-09-15 用户确认 #13 完成阅读与进度口径：POST /api/v1/chapters/:id/complete 只记已读、不批量改变词语状态或等级，只有 ready 章节可标记（其他 409），重复调用返回同一行且带 duplicate（不移动时间、不重复计数）；完成记录保存标记时的 content_sha256，正文新版本后该章回到未读（记录保留，重读后更新同一行），只改标题不影响，章节删除随外键级联；GET /api/v1/progress 统计只含本人与当前语言，已读与分母都只算可阅读（ready）章节，已知/学习中/新词/忽略分开计数，dueNow 与到期复习队列共用 dueTermsQuery 与同一服务端时钟；schema 升到 v7（新表 lexgo_chapter_progress，不用 ALTER TABLE），需显式 migrate。不做每日目标、日历、难度评分、统计导出与取消已读，也不做 X10 批量标已知。

• 2026-09-15 既有缺陷记录：#32 编辑章节正文回到曾经用过的版本返回 500（lexgo_ingest_jobs 请求键与 edit:<章节>:<内容摘要> 冲突），已定位未修复，方案待用户确认；#13 的真实验证脚本因此自建 fixture 而不改写既有正文。

• 2026-09-11 用户确认 #12 词汇库口径：GET /api/v1/terms 列表同时匹配规范化身份键、显示原文与个人释义，大小写不敏感（term 为二进制排序规则，查询先转小写），%/_/\ 按字面值转义，status 与 kind 可与搜索组合；分页 page ≥ 1、limit ≤ 100（默认 20）、按最近更新倒序；PATCH /api/v1/terms/:id 复用同一套释义/例句与状态/等级校验，身份不可编辑，只有状态或等级变化才重排复习时间，历史作答记录与计数保留；筛选与页码写入 /vocab URL。原型编辑页的「来自某章节」不实现（词条按身份存储、不引用章节）；CSV（X04）、复习范围筛选（X11）、删除与批量清理（X14）不在范围内。

• 2026-09-11 用户确认 #11 短语口径：短语与单词共用 lexgo_terms，身份键为按阅读顺序的规范化词形以单个空格连接（单词键不含空格），因此 kind 与词数由身份键派生，不新增列、无迁移；范围两端对齐整词、内部标点与换行保留但不参与身份比较，2～12 词、键 ≤128 字符、片段 ≤191 字符，切进单词的范围 400。跨章节匹配按连续词形比对，重叠取最左最长；短语高亮覆盖内部单词但不修改单词数据，点击已保存短语优先打开短语面板；失效引用回退＝高亮消失但词条与复习排期保留。短语进同一到期队列与同一套幂等作答，复习卡把整段短语挖成一个空；选择用原生拖选与手机系统手柄，不拦截 touchmove。同义形式合并、词性消歧、跨书移动、批量编辑（#12）与真机手感不在范围内。

• 2026-09-11 用户确认 #10 编辑与删除口径：可改名、改章节标题、编辑章节正文；只有正文变化才重新处理，重复保存或改回原内容不新建任务，只改标题不改状态。版本键是 content_sha256：任务只在与章节版本一致时才能影响章节，过期版本任务标为 error_reason=superseded 且完全不触碰章节（认领、恢复扫描、重试都按版本裁决）；存储文本重算 SHA 与存储 SHA 不一致时按 content_changed 失败。删除为事务内硬删除 + 外键级联，删章后重排序号；个人词条、复习排期与作答记录不随删除清理。回收站/撤销、批量操作、章节跨书移动与语言变更不在范围内。编辑器行尾归一为 LF 是已知边界。

• 2026-09-11 用户确认 #9 TXT 导入口径：只接受 UTF-8（允许可选 BOM，解码时剥离且不进入原文），非法字节整体拒绝、不使用替换字符；UTF-16 按 BOM 识别后明确拒绝，GB18030 等按非法 UTF-8 拒绝。文件字节上限 2 MiB，之后仍套用单章 100000 码点上限；换行与空白不归一化。文件只在内存中解码、不创建临时文件，客户端文件名不参与任何路径也不入库。解码后交给既有 PasteBook/PasteChapter，分章（一次提交一章）、requestId 幂等与任务恢复与粘贴一致；不改 schema。EPUB/PDF/字幕、UTF-16 转码、按空行自动分章与断点续传不在范围内。

• 2026-09-11 用户确认 #8 到期单词复习决策表：固定间隔表 1/2/4/7/15/30/60 天，答对升级封顶 7、答错降级最低 1、再学一次不改等级，答错与再学立即回队；已知/忽略不入队，新保存的词立即到期，显式「学习中 level N」排 now+间隔[N]；只有新建或状态/等级实际变化才移动复习时间，编辑释义或例句保留原排期，保存未提及等级时保留已获得等级。到期判定用 UTC 绝对时刻（due_at ≤ now），不引入本地日边界。作答按 answerId 去重并以 expectedDueAt 判定过期标签页，重复提交、网络重发与双标签页都不得重复更新次数与间隔（作答响应 result 只取 applied/stale，重放另用 duplicate 标记并返回首次结果）；correct_count 只计答对，wrong_count 计答错与再学。短语复习归 #11，进度统计归 #13，不做策略配置 UI（X11）、练习模式（X08）与 FSRS。