docs: import verified LexGo Wiki baseline

Online sync and strict structure checks pass. Full governance tests identify two documentation gaps; follow-up will add lightweight exemptions and verified Windows shell guidance.
2026-09-10 14:28:41 +08:00
parent 3c161363e1
commit ffa81901cf
20 changed files with 1750 additions and 23 deletions
@@ -0,0 +1,59 @@
+<!-- gitea-wiki-mirror:start -->
+generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
+wiki_page: Project-Profile
+wiki_url: https://git.ilapage.cn/OPC/lexgo/wiki/Project-Profile.-
+wiki_revision: d5832ae249dabbf6ce2515ce350b3adc730fff46
+synchronized_at: 2026-09-10T06:27:39Z
+<!-- gitea-wiki-mirror:end -->
+
+# LexGo 项目档案
+
+
+## 基本信息
+
+目标：围绕“导入内容 → 阅读查词 → 保存词语/短语 → 复习 → 查看进展”建设自托管语言学习 Web 应用。主要受众暂按学习者和实例管理员规划。
+
+现状：只有四份调研文档，无业务代码、依赖锁文件、数据库结构或产品测试。首次盘点时没有本地 `.git`；本轮已连接确认的远端 `https://git.ilapage.cn/OPC/lexgo.git`，默认分支 `main`，已有引导提交 `ecab8995026e57f2c28f307a6aa32b871cb3163f`。仓库归属 OPC，产品验收负责人为当前用户，具体长期维护分工尚未确定。
+
+非目标暂按既有分析：商业 SaaS、多组织租户、课程商城、原生 App、完整离线同步、OCR、视频转写和 FSRS 改造均不包含在本轮基础估算。
+
+## 项目治理模式
+
+**轻量**，依据 2026-09-10 用户明确指令。低风险局部调整直接实施；独立需求及中高风险变化建单；不为初始化强制拆 Epic/MVP。见[工作流](https://git.ilapage.cn/OPC/lexgo/wiki/Development-Workflow.-)。
+
+## DevHarness 来源与基线
+
+本地来源 `D:/opc_project/dev_harness`，Git commit `ecab8995026e57f2c28f307a6aa32b871cb3163f`，核验日 2026-09-10。治理脚本、测试与模板按此基线复制，不复制凭据、Git 历史或旧任务快照。升级先比较该基线之后的变化，按本项目真实需要引入。
+
+LinguaCafe 参考基线由现有调研记录为 `c1ea298ce40c65b9dd33e9b26fd2e52fae66f2c8`；本轮只整理已提供的调研，没有重新核验上游代码、依赖或许可。gin-vue-admin 尚未锁定提交，不能记为已采用工程基线。
+
+## 子项目与交付单元
+
+当前独立交付物只有文档和治理工具。目标按一个产品版本、一个仓库规划：Go API/Worker、Vue 学习与管理界面、内部 NLP 服务；是否拆前端构建尚待确认。暂不创建不存在的产品目录或子项目规则。
+
+## 技术栈与运行环境
+
+| 决策 ID | 议题 | 现有证据与状态 | 对估算的影响 |
+|---|---|---|---|
+| D01 | 工程底座 | 两份分析均建议评估 gin-vue-admin，也允许精简 Gin 路线；未批准 | 通用管理复用程度 |
+| D02 | 数据库 | **已确认 MySQL 8**；依据 2026-09-10 用户原话“使用mysql8”。覆盖两份分析的数据库分歧，具体小版本待基线验证锁定 | 按单一 MySQL 8 数据层估算，不做 PostgreSQL 双库兼容 |
+| D03 | NLP | 保留 Python 为建议，纯 Go 是否硬约束未确认 | 首发语言质量与开发量 |
+| D04 | 首发语言 | 英语先行为估算假设，中文/日语需独立验收 | 分词、读音和 UI |
+| D05 | 用户范围 | 暂按自托管普通用户+管理员，无组织租户 | 数据隔离和部署边界 |
+| D06 | 旧数据 | 全量迁移是否需要未确认，CSV 与完整迁移不同 | 迁移另估 |
+| D07 | 范围与交付 | 首版 P0、后续 P1/P2 为建议；人员、读者、运行环境未确认 | 排期可信度与验收 |
+| D08 | Gitea | 已确认 `https://git.ilapage.cn/OPC/lexgo.git`，分支 main，工单与 Wiki 已启用 | 本轮发布核心 Wiki 并同步验证 |
+
+数据库确定为 MySQL 8。Go/Gin、Vue 3/TypeScript、Redis 任务队列、Python NLP、Compose 为候选组合，具体版本和构建命令在 M0 验证后固定。不能同时按两种数据库承诺交付。
+
+## 阅读入口
+
+[需求总览](https://git.ilapage.cn/OPC/lexgo/wiki/Product-Requirements-Overview.-)、[代码地图](https://git.ilapage.cn/OPC/lexgo/wiki/Architecture-and-Code-Map.-)、[工作量](https://git.ilapage.cn/OPC/lexgo/wiki/Workload-Estimate.-)。现有分析中的许可说明仅作资源评估线索，采用代码、词典、模型和素材前记录来源与实际许可；本轮不作新的法律结论。
+
+## 常用命令
+
+见[开发与验证](https://git.ilapage.cn/OPC/lexgo/wiki/Local-Development-and-Verification.-)。产品构建、启动、测试和部署命令暂不存在，不用示例命令冒充实际可运行入口。
+
+## 环境、配置与凭据
+
+本地 Windows PowerShell，工作目录 `D:/opc_project/lexgo`。当前 Gitea MCP 指向 `ilaer.eicp.net:8418`，并非用户确认的目标站点；本轮因此使用目标站点 Gitea API。凭据从已配置的安全来源读入进程，不复制进项目。Wiki 配置只保存非敏感地址与页面映射，凭据使用 MCP 安全配置或环境变量。
@@ -1,3 +1,11 @@
+<!-- gitea-wiki-mirror:start -->
+generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
+wiki_page: LinguaCafe-Requirements
+wiki_url: https://git.ilapage.cn/OPC/lexgo/wiki/LinguaCafe-Requirements.-
+wiki_revision: 240e5aae95507dda2e349fefc000add901c0189e
+synchronized_at: 2026-09-10T06:27:49Z
+<!-- gitea-wiki-mirror:end -->
+
 # LinguaCafe 功能需求提取

 调研日期：2026-09-10。用途：作为 LexGo 使用 Go 复刻 LinguaCafe 的需求基线。
@@ -182,4 +190,4 @@ N08 是拟定目标，不是基准测试结果；不包含公网延迟、外部
 | 字符与短语 | 中文、日文、重音字符、emoji、换行与重叠短语不造成错位或原文丢失 |
 | 备份 | 恢复后书籍数量、抽样词汇状态、用户设置与文件校验一致 |

-需求提取已完成；具体范围取舍和框架方案见 [Go 复刻与框架选型分析](02-Go复刻与框架选型分析.md)。
+需求提取已完成；具体范围取舍和框架方案见 [Go 复刻与框架选型分析](https://git.ilapage.cn/OPC/lexgo/wiki/Go-Architecture-Analysis.-)。
@@ -0,0 +1,350 @@
+<!-- gitea-wiki-mirror:start -->
+generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
+wiki_page: Development-Workflow
+wiki_url: https://git.ilapage.cn/OPC/lexgo/wiki/Development-Workflow.-
+wiki_revision: 972b8ceddedf00fa2d28a7441855fc4ad3db7c57
+synchronized_at: 2026-09-10T06:27:40Z
+<!-- gitea-wiki-mirror:end -->
+
+# LexGo 工作流适用说明
+
+本项目明确采用轻量模式；下文其他模式仅供风险升级参考。MySQL 8 已确认，产品方案其余候选未定版。阶段表不是已批准工单。
+
+# 开发工作流
+
+## 事实来源边界
+
+- Gitea 工单记录任务状态、讨论、阻塞、方案变化、验证和验收。
+- Gitea Wiki 保存长期架构、契约、业务规则、开发规范、操作手册和稳定需求；默认不重复保存单次任务归档。
+- Git 保存源码、与特定代码版本强绑定的文档，以及 Wiki 的本地镜像。
+- 本地 `docs/` 仅供浏览和审查，不是长期文档编辑入口。
+
+## 语言与术语
+
+- 用户可以使用中文、英文或合理的中英混合语言提出需求和补充信息；Agent 不要求用户先翻译。
+- Agent 默认使用中文进行分析、回复、工单记录和内部项目文档维护。
+- 代码标识符、命令、参数、路径、文件名、API 名称、协议名、日志和错误原文保持原样，不做会影响搜索、复制、执行或排错的翻译。
+- commit、revision、middleware 等通用英文术语可以保留；可能影响初级维护者理解时，在首次出现处补充简短中文解释，不反复注释。
+- 用户明确要求某次回复、交付物或对外文档使用其他语言时，按该次明确要求执行；默认中文不是禁止其他交付语言的门禁。
+- 引用外部材料时保留必要原文并用中文说明结论；不得为了语言统一改写事实、错误信息或接口契约。
+
+## Gitea 交互与工单最小读取
+
+- 所有 Gitea 工单和 Wiki 的查询、创建、更新、评论、状态变更及关闭操作，优先使用项目已配置的 Gitea MCP。
+- MCP 不可用或不支持所需操作时才回退 Gitea API，并在当前工单记录回退原因；初始化阶段尚无工单时记录到初始化工单草稿，建单后补回。凭据只从环境或 MCP 安全配置读取。
+- 首次接手任务时读取工单确认基线和完成当前判断所需的评论，不因节省 Token 跳过范围、依赖、安全、验收或重要变更。
+- 同一任务、同一会话且关键前提未变化时，复用仍有效的工单事实，优先关注当前状态、最新评论和首个未完成步骤，不重复分析已经确认且仍有效的内容。
+- 会话、代码、配置、依赖、凭据、远端状态或关键前提变化，任务基线不清楚，或最新评论声明历史需求、方案、范围、风险或验收发生变化时，重新读取必要历史；无法判断影响范围时读取完整工单。
+- 连接器不支持评论分页或增量读取时允许读取完整工单，但不得把“已读取全文”误当成需要重新分析全部历史，也不得为规避完整读取而新增本地工单、缓存或第二事实来源。
+- 正确性、安全规则和已确认范围优先于 Token 优化；读取边界存在不确定时补读必要证据。
+
+## 新项目 Wiki 初始化门禁
+
+从 DevHarness 创建新项目时，本地 `docs/` 即使完整存在，也只能证明模板镜像存在，不能证明新项目的线上 Wiki 已初始化。开始任何产品代码前必须完成以下闭环：
+
+1. 先创建 Gitea 远端仓库并启用 Wiki，再把 `wiki-docs.json` 指向该仓库。
+2. 优先使用项目已配置的 Gitea MCP 查询 Wiki 页面；MCP 不可用或不支持所需写操作时，才使用 Gitea API，并在初始化工单记录回退原因。凭据只从环境或 MCP 安全配置读取。
+3. 查询线上页面列表；没有 `Home` 时先创建 `Home`，回读正文并记录 revision，然后再创建或更新其他核心映射页面。
+4. 每个核心页面写入后都要在线回读；页面可读取且取得 revision 才算创建成功，不能用本地 `docs/` 文件替代这项证据。
+5. 运行 `python dev_scripts/harness.py sync --verify`。任一映射页面不存在、无法回读或镜像不一致时，停止产品编码并完成初始化。
+
+Gitea 暂时不可用时可以准备工单和 Wiki 草稿，但不得把本地草稿宣称为线上事实，也不得绕过此门禁开始产品功能开发。
+
+## 按治理模式选择最小门禁
+
+使用 DevHarness 创建新项目时默认采用轻量模式。只有项目负责人明确选择标准或高风险模式，并在 Project-Profile 记录理由时，才改变项目默认模式；未明确填写时按轻量模式执行并提示补写，不因此阻塞产品开发。DevHarness 上游模板自身继续采用标准模式。单个任务风险高于项目默认模式时，只升级该任务，不抬高全部日常工作。不得为了流程完整而增加没有实际作用的工单、原型、文档或测试。
+
+### 不可裁剪底线
+
+任何治理模式都必须遵守：
+
+- 密码、令牌、Cookie 和私钥只从环境或安全配置读取，不得写入代码、Git、日志、工单、Wiki 和文档；人工授权不改变此边界；
+- 任务确有需要且得到人工明确授权时，可以在授权范围内处理真实个人数据或生产数据；只使用完成任务所需的最少数据，不把无关副本扩散到代码、Git、Wiki、工单、测试数据和日志，证据优先使用脱敏摘要；
+- 手机号等明确为虚构的测试数据无需形式化脱敏，但必须能与真实用户数据区分；来源不明时按真实个人数据处理；
+- 未经人工明确授权，不执行发布、付款、删除数据、破坏性迁移或其他不可逆操作；授权有效时按下一节执行；
+- 测试结果必须真实，未执行或无法覆盖的验证必须说明；
+- 任务涉及权限、安全、支付、真实个人/生产数据、迁移、并发、删除或不可逆操作时按高风险处理；尚未获得有效授权时等待人工确认，已经获得时不重复确认。
+
+### 明确授权后的执行
+
+- 当前聊天中用户给出的明确指令，或 Gitea 工单中能够归属于有权人工的明确授权，可以作为执行依据；不要求把聊天授权重复复制到工单后再确认。
+- 授权必须能识别操作、对象和范围。Agent 自动生成的工单、草稿、摘要或对用户意图的转述，不能单独构成人工授权。
+- 获得有效授权后，Agent 只核对准确目标、授权范围和当前状态等最小必要前提，然后执行；不得仅因操作不可逆而重复询问或拒绝。
+- 授权只适用于明确范围，不自动覆盖相邻对象或后续任务。环境、对象、范围或影响发生实质变化时，原授权不再覆盖变化部分，应重新确认。
+- 平台自身强制的审批、安全策略或权限限制继续有效；不能把项目内授权解释为绕过平台限制。
+- 执行完成后报告实际结果、影响范围以及是否可以恢复；失败时报告已完成部分和当前状态。
+
+### 先判断是否需要工单
+
+| 治理模式 | 可直接实施 | 必须建单 |
+|---|---|---|
+| 轻量 | 文案、注释、格式、局部样式或布局；预期行为明确的小 Bug；不改变接口、数据结构、权限和安全边界的单模块低风险调整 | 完整独立需求、新页面或跨模块功能；API、数据结构、权限、安全、迁移；范围或预期不明确的变化 |
+| 标准 | 纯文档措辞、格式化、内部标识符改名和确定不改变行为的小整理 | 新功能、缺陷修复、重构及用户可感知的行为变化 |
+| 高风险 | 只读诊断和不会改变行为的文档整理 | 任何正式行为变化；按风险补充人工确认和验证 |
+
+直接实施项无需为了留痕补建工单，也无需填写工单模板；开始前只做必要的工作区和安全检查，完成最小测试后报告结果。无法确定是否符合直接实施条件时，先澄清或建单，不用代码行数代替风险判断。
+
+### 再判断设计证据
+
+- 轻量模式的小 Bug、局部样式或布局、复用现有规范的组件调整无需完整原型；能用一句话、现有界面或标注截图确认时即停止增加设计材料。
+- 完整独立需求、新页面、重大交互或导航变化需要工单；只有存在明显交互不确定性、用户明确要求，或返工成本显著时，才制作 Quant-UX 或其他可审阅原型。
+- 标准模式对新页面、独立用户功能和重大交互使用可审阅原型；小范围 UI 使用最低成本的文字、截图或低保真证据。
+- 高风险任务按影响补充技术设计、数据和权限边界、回退方案及人工确认；非 UI 任务不制作无意义的 UI 原型。
+- 恢复既有确认行为的 Bug 可以复用原设计、截图、复现步骤或已有验收证据。
+
+### 线上原型审核与按需导出
+
+需要完整原型时，默认通过 Quant-UX 或等效工具的可访问线上链接审核，记录可识别的版本和确认范围。只有用户明确发出 `导出原型 #N`、`导出全部原型`，或项目专用规则要求离线交付时，才导出到 `prototypes/<工单号>/<版本>/index.html`；不得把本地快照变成第二份可编辑事实来源。
+
+页面结构、主要流程、权限、状态或异常处理发生影响验收的变化时，才更新设计证据并重新确认。设计工具无法生成用户明确要求的离线 HTML 时，记录限制并等待等效方案；线上版本可访问且可识别时不阻塞线上审核。
+
+## 一次任务怎样完成
+
+### 1. 讨论
+
+用户描述需求或故障。Agent 先检查现状，再给出目标、非目标、方案、风险、回退和验证方法。存在不同实现方向时，说明取舍并等待用户确认。
+
+### 2. 建单
+
+方案确认后，使用 `.gitea/issue_template/task.md` 创建单元任务工单。没有工单号之前不修改产品代码或正式文档。
+
+新产品或较大版本先建立 Epic，再建立 MVP：
+
+```text
+[Epic] 产品或长期目标
+└── [MVP] 第一个可交付版本
+    ├── #101 单元任务
+    ├── #102 单元任务
+    └── #103 单元任务
+```
+
+每个单元任务都应目标单一，能够独立测试、提交和回退。
+
+#### 依赖与并行
+
+建立新工单不要求其他工单已经完成，也不按工单编号限制实施顺序。每个单元任务必须声明：
+
+- 前置工单，没有时填写“无”；
+- 是否允许与未完成的前置工单并行；
+- 判断可以或不可以并行的原因。
+
+开始修改前，Agent 检查工单声明的前置工单：
+
+- 没有前置工单，或前置工单已经完成，可以进入“进行中”；
+- 前置工单未完成且存在实际依赖时，不得开始实施，工单保持“待实施”；
+- 与前置工单没有实施冲突、允许并行时，可以进入“进行中”，但必须在工单写明原因；
+- 已经进入实施后出现计划外、当前无法解除的问题，才使用“阻塞”。
+
+依赖不改变单元任务边界。依赖满足后，该任务仍须拥有独立的范围、提交、测试和回退方式。
+
+### 3. 实施
+
+Agent 检查分支和工作区，只修改工单范围内的文件。发现新问题时先记录到工单；如果不影响当前验收，则另建工单，不扩大当前任务。
+
+重要进度及时写回工单：
+
+- 已确认的根因；
+- 方案或范围变化；
+- 测试结果；
+- 阻塞和未验证内容；
+- Git 提交哈希；
+- 相关 Wiki 页面及 revision。
+
+工单正文保存用户确认的任务基线；根因、范围、方案、风险或阻塞发生重要变化时追加评论。完成实现后用一条评论集中记录最终差异、测试、未验证内容、提交哈希和长期文档影响，保留可追溯时间线，不在 Wiki 重抄同一份任务结果。
+
+只有长期事实发生变化时才执行核心文档闭环：
+
+```text
+修改 Wiki → 读取确认 → 导出核心 docs → 校验差异 → 提交镜像
+```
+
+没有长期文档影响时，在工单写明原因并跳过 Wiki 更新和核心镜像同步；默认任务流程不创建任务归档。长期文档仍不得先编辑本地镜像再反向覆盖 Wiki。
+
+### 4. 待验收
+
+实现和测试完成后，Agent 提交实现代码并将工单更新为“待验收”。用户验收前工单保持开启。
+
+### 5. 待验收和关闭
+
+实现、必要测试和提交完成后，在工单追加一条最终证据评论并保持“待验收”。评论至少记录最终差异、测试结果、未验证内容、提交哈希，以及长期 Wiki 页面和 revision，或“无长期文档影响”及原因。
+
+用户明确验收通过后：
+
+1. 在工单追加验收时间和结论，不重复抄写已有测试与提交证据；
+2. 关闭单元工单并勾选所属 MVP/Epic 子任务；
+3. 只有验收结论改变长期需求状态或其他 Wiki 事实时，才更新 Wiki 并执行同步闭环；没有变化时不重复检查 Wiki；
+4. 默认不创建或导出任务归档。
+
+任务归档只保留为显式兼容能力。只有用户明确要求专项快照，或项目专用规则明确要求时才运行：
+
+```powershell
+python dev_scripts/harness.py archive 123 "修复登录超时"
+python dev_scripts/harness.py export        # 增量导出已有归档
+python dev_scripts/harness.py export --all  # 全量导出已有归档
+```
+
+可选归档不得成为第二个日常维护入口；创建时以工单中的最终证据为来源，并记录工单链接。既有 Wiki 归档和 `docs/task/` 快照不自动删除、重命名或补齐。
+
+## 文档同步规则
+
+- 核心页面映射保存在 `wiki-docs.json`；普通同步只处理这些核心长期文档。
+- 可选任务归档不逐页登记映射；显式执行归档导出时，工具根据 `Task-<编号>-<标题>` 动态发现，已有镜像优先按镜像头匹配原页面。
+- 所有同步和导出只实现 Wiki → `docs/`，不提供反向同步。
+- 镜像头必须记录页面名、页面地址、revision 和同步时间。
+- 已跟踪镜像存在未提交改动时，同步必须停止；确认改动来源后再处理。
+- `sync` 和 `sync --check` 先读取一次页面列表，并用远端 revision 与本地镜像头比较；revision 未变化时不下载正文，只有页面新增、变化、元数据缺失或本地镜像元数据无效时才读取正文。
+- `sync --check` 是核心镜像的日常快速检查，不要求线上任务归档全部存在于本地；它验证 revision 和镜像元数据，不替代正文审计。
+- `sync --deep-check` 显式下载全部映射页面正文并逐页比较，用于疑似镜像损坏、同步算法审计或人工要求的完整核对。
+- `sync --verify` 用于新项目 Wiki 初始化门禁，完整读取并写入核心镜像后执行严格结构检查；同一次运行复用读取结果，不重复下载正文。
+- 已经导出的任务镜像仍必须具有来源页面、revision 和同步时间，并通过 Harness 格式检查。
+- 页面删除和重命名不会自动传播，必须先更新工单并人工确认映射变化。
+- Wiki 更新成功而导出失败时，在工单记录部分完成状态，不得把任务标为完成。
+- 与具体代码版本强绑定的接口或迁移资料可直接随代码维护，但必须在 Wiki 提供入口或适用版本说明。
+
+## 面向初级维护者的修改边界
+
+| 风险 | 示例 | 处理方式 |
+|---|---|---|
+| 低 | 文案、简单校验、查询条件、独立 UI、小范围回归 Bug | 初级程序员可在 Agent 协助下理解、修改和验证 |
+| 中 | API、配置、依赖、跨模块逻辑、数据结构 | 由 Agent 实现，程序员检查差异并执行验证 |
+| 高 | 权限、安全、并发、迁移、支付、删除数据、不可逆操作 | 停止修改，由 Agent 分析并等待人工确认 |
+
+风险由影响范围决定，不按代码行数判断。
+
+## 每个任务的文档影响
+
+单元任务必须明确选择：
+
+- 不影响长期文档，并说明原因；
+- 更新项目档案或运行验证；
+- 更新架构与代码地图；
+- 更新业务规则与术语；
+- 更新常见修改或故障排查；
+- 新增或调整其他 Wiki 页面。
+
+以下变化必须更新相关 Wiki：
+
+- 启动、测试、部署或排错命令变化；
+- 模块入口、目录职责或主要调用路径变化；
+- 配置项、API、数据结构或状态变化；
+- 业务规则、安全边界或权限变化；
+- 日志位置、错误定位或常见处理方式变化。
+
+部署命令的落点：有常驻服务的项目更新自己的 `Deployment-and-Operations` 页面（由[部署文档模板](https://git.ilapage.cn/OPC/lexgo/wiki/Deployment-Template.-)复制建立）；没有常驻服务的项目在工单记录“无部署文档影响”及原因，不要创建空的部署页。
+
+普通内部重构如果入口、行为、配置和验证方式均未改变，可以记录“不影响长期文档”及原因。
+
+## 需求记录与流转
+
+聊天用于分析和确认，不是正式需求的长期事实来源。创建单元任务工单时，Agent 应记录：
+
+- 原始需求的来源和提出时间；
+- 能表达用户目的、使用场景和限制的少量关键原话；
+- 整理后的目标、非目标、确认方案、验收标准和文档影响；
+- 实施期间影响范围、接口、数据、风险或验收的需求变化，以及变化原因和用户确认。
+
+只摘录完成追踪所需的内容，不复制完整聊天，不保存 Agent 内部推理，不写入密码、令牌、个人数据或生产数据。包含敏感信息的原话必须删除敏感部分或改写为脱敏摘要。
+
+需求按以下边界流转：
+
+| 内容 | 事实来源 | 本地镜像 |
+|---|---|---|
+| 关键原始需求、确认后的单次任务需求 | Gitea 单元任务工单 | 无 |
+| 讨论、决定和需求变化 | Gitea 工单正文或评论 | 无 |
+| 长期有效的产品需求、业务规则和系统边界 | 对应 Gitea Wiki 主题页 | `docs/` |
+| 完成后的实现、验证、遗留问题和验收 | Gitea 单元任务工单正文与评论 | 无；用户明确要求时可创建专项 Wiki 快照 |
+
+任务产生长期结论时，先更新对应 Wiki 主题页，再导出本地镜像。Gitea 工单全文不导出到仓库，避免形成第二份任务过程记录。
+
+## 稳定文档与可选历史快照
+
+- Home、项目档案、代码地图、业务规则、开发验证、常见修改和故障排查描述项目现在怎样工作。
+- 工单正文和评论解释某次为什么修改、实际改了什么、如何验证以及怎样验收。
+- 新人先读稳定主题页，只有追查历史原因时才读工单；可选 Wiki 快照和本地任务快照只是专项或历史兼容资料，不是默认事实来源。
+- 任务产生的长期结论必须合并到对应主题页，不能只留在工单或可选快照。
+
+## 效率与范围控制
+
+本节用于减少无关工作和重复检查，不得削弱安全规则、已确认方案、工单范围、必要测试、必要的长期文档同步、Git 提交和人工验收要求。
+
+### 严格控制范围
+
+- 默认严格按用户确认的目标和单元任务范围执行，不主动扩展相邻问题。
+- 除非任务目标、仓库强制规则或已发现的真实阻塞需要，不新增额外文档、辅助脚本、备份文件、框架、重构或扩展性设计。
+- 不执行与本次验收无关的验证；安全检查、受影响范围测试、回归测试和仓库规定的闭环验证不属于“额外验证”。
+- 新发现的相邻问题最多用一句话提示或记录到独立工单，不自动修复或混入当前提交。
+
+### 渐进执行和修复
+
+- 完成已知必要的安全与前置检查后，优先执行能够产生真实反馈的最小命令。
+- 一次执行后先处理首个可定位、可行动的真实错误，不同时猜测并修改多个可能原因。
+- 采用“执行 → 查看错误 → 最小修复 → 从失败点继续或按需重跑”的闭环。
+- 不在真实证据出现前堆叠与已知风险无关的预防性检查。
+- 涉及凭据、权限、安全、数据、迁移、并发、删除、发布或不可逆操作时，必须先完成相应前置检查，不得通过试错获取风险反馈。
+
+### 复用已验证事实
+
+- 在同一任务和同一环境状态下，已经通过的路由、连接、恢复和环境检查不重复执行。
+- 只有会话、环境、代码、配置、依赖、凭据、远端状态或关键前提发生变化时才重新检查。
+- 代码修改后，受影响测试和最终验收必须重新执行；提交前工作区检查、推送前远端分支检查不得因为之前通过而省略。
+- Skill 和平台规则是否需要重新读取，按当前 Agent 平台和任务触发规则执行，不自行跳过。
+
+### 明确停止条件
+
+- 完成用户确认的验收标准和仓库规定的必要闭环后立即停止，不主动继续优化。
+- “最小验收条件”包括当前工单要求的实现、必要测试、文档影响处理、Wiki 镜像检查、提交和证据回写，不等同于功能第一次运行成功。
+- 未影响当前验收的相邻问题只提示或建单，不顺手处理。
+
+## 自然语言快捷指令
+
+快捷指令是对本工作流的自然语言别名，供 Claude Code、Codex 和维护者使用。它们只减少重复描述，不得绕过方案确认、前置依赖、安全规则、工单范围、Wiki 主源、必要验证或人工验收。
+
+| 指令 | 执行动作 | 停止位置 |
+|---|---|---|
+| `只分析` | 只读检查需求、代码、日志和文档，区分事实与假设并给出方案 | 输出方案并等待确认；不建单、不修改 |
+| `建工单` | 根据已经确认的方案创建单元任务工单 | 工单创建并记录完成；不修改代码 |
+| `执行工单 #N` | 读取工单和前置依赖，实施、测试、提交并回写证据；仅有长期文档影响时更新 Wiki 和镜像 | 工单保持“待验收” |
+| `建工单并做` | 依次执行“建工单”和“执行工单”；`建工单，做`、`建工单,做` 含义相同 | 工单保持“待验收” |
+| `继续工单 #N` | 核对工单、Git 和 Wiki 证据，从首个未完成步骤继续，不重复仍然有效的检查 | 到达该工单当前流程的停止条件 |
+| `检查工单 #N` | 只读对照范围、验收标准、测试和证据，报告通过项、缺失项及未验证部分 | 输出检查报告；不自动修复 |
+| `同步文档` | 读取 Wiki，导出核心长期文档镜像并检查一致性，不处理任务归档 | 显示结果和差异；不修改 Wiki、不自动提交 |
+| `导出原型 #N` | 人工触发导出指定工单已确认的原型版本；按工单和版本写入 `prototypes/` | 显示路径和检查结果；不扩展范围、不自动提交 |
+| `导出全部原型` | 人工触发导出当前项目明确范围内的全部已确认原型 | 显示导出范围和结果；不自动提交 |
+| `导出任务归档` | 人工触发增量导出，只写入新增或 revision 已变化的任务归档 | 显示导出或跳过结果；不删除本地文件、不自动提交 |
+| `导出全部任务归档` | 人工触发全量读取并导出线上全部任务归档 | 显示导出结果；不删除本地文件、不自动提交 |
+| `#N 验收通过` | 在工单追加验收结论，按需更新真实变化的长期 Wiki，推送、同步父工单并关闭任务；不创建或导出任务归档 | 工单“已完成”并关闭 |
+
+补充边界：
+
+- 方案未确认时，`建工单`、`建工单并做` 和 `执行工单 #N` 不得绕过确认；Agent 应停在方案确认。
+- 前置依赖未满足且不允许并行时，实施类指令停在“待实施”。
+- `#N 验收通过` 必须来自用户明确表达；其他快捷指令不得关闭待验收工单。
+- `同步文档` 或任务归档导出发现目标镜像有未提交改动时停止，不覆盖现有修改。
+- `导出原型 #N` 和 `导出全部原型` 必须由用户明确提出或项目专用规则明确要求；其他指令不隐式导出原型。
+- `导出任务归档` 和 `导出全部任务归档` 必须由用户明确提出，其他快捷指令不隐式执行。
+- 需要工单的任务以 Gitea 工单为单次任务事实来源，不导出全文；符合轻量模式直接实施条件的任务以用户确认范围、Git 提交和结果报告留痕，不补建工单。`docs/task/` 只保存人工明确要求的专项或历史兼容快照。
+
+## 什么时候重新确认方案
+
+以下变化必须重新确认；已有工单时先更新工单，直接实施项遇到这些变化时不再符合豁免，先建单再继续：
+
+- 交付结果或用户操作发生变化；
+- 增加或删除接口、数据库字段或迁移；
+- 安全边界、权限或不可逆操作发生变化；
+- 原方案不可行，需要更换主要技术路线；
+- 任务范围明显扩大；
+- Wiki 页面删除、重命名或事实源边界改变。
+
+普通内部实现细节不需要反复确认，但重要取舍应记录在工单中。
+
+## 工单、Wiki 与 Git 分别写什么
+
+| 信息 | Gitea 工单 | Gitea Wiki | Git / `docs` 镜像 |
+|---|---:|---:|---:|
+| 讨论过程和临时方案 | 是 | 否 | 否 |
+| 实施进度和阻塞 | 是 | 否 | 否 |
+| 长期有效的最终方案 | 链接 | 是 | 镜像 |
+| 测试结果与未验证内容 | 是 | 否 | 否 |
+| 提交哈希和验收结论 | 是 | 否 | 否 |
+| 用户明确要求的任务专项快照 | 提供来源 | 可选 | 可选导出 |
+| 与具体代码版本绑定的说明 | 可链接 | 提供入口 | 是 |
@@ -1,6 +1,14 @@
+<!-- gitea-wiki-mirror:start -->
+generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
+wiki_page: Go-Architecture-Analysis
+wiki_url: https://git.ilapage.cn/OPC/lexgo/wiki/Go-Architecture-Analysis.-
+wiki_revision: 4df1efc6cfb7a5e493501ce753a120065932271a
+synchronized_at: 2026-09-10T06:27:50Z
+<!-- gitea-wiki-mirror:end -->
+
 # 使用 Go 复刻 LinguaCafe：架构与二次开发选型

-调研日期：2026-09-10。状态：可供评审的技术建议，尚未进入编码实现。原项目证据、提交基线与需求 ID 见 [需求提取](01-LinguaCafe需求提取.md)。
+调研日期：2026-09-10。状态：可供评审的技术建议，尚未进入编码实现。原项目证据、提交基线与需求 ID 见 [需求提取](https://git.ilapage.cn/OPC/lexgo/wiki/LinguaCafe-Requirements.-)。

 ## 1. 结论与适用前提

@@ -0,0 +1,40 @@
+<!-- gitea-wiki-mirror:start -->
+generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
+wiki_page: Architecture-and-Code-Map
+wiki_url: https://git.ilapage.cn/OPC/lexgo/wiki/Architecture-and-Code-Map.-
+wiki_revision: 2f5461e714febafd5a25b6e43f7cad635deaac05
+synchronized_at: 2026-09-10T06:27:41Z
+<!-- gitea-wiki-mirror:end -->
+
+# 架构与代码地图
+
+
+## 项目定位
+
+Go 承担业务与后台任务，浏览器提供阅读学习界面，NLP 保留独立边界是现有分析的建议。用户区与管理区共享身份服务，但功能权限与个人数据所有权分别校验。
+
+## 代码地图
+
+| 现有位置 | 内容 | 能证明什么 |
+|---|---|---|
+| `docs/01-LinguaCafe需求提取.md`、`docs/linguacafe-requirements.md` | 两份需求研究 | 参考需求与上游证据索引 |
+| `docs/02-Go复刻与框架选型分析.md`、`docs/linguacafe-go-analysis.md` | 两份设计建议 | 候选方案，含未解决差异 |
+| `docs/` 核心页面 | Gitea Wiki 的单向镜像 | 仅文档与治理准备，不是产品实现 |
+| `dev_scripts/harness.py`、`dev_scripts/wiki_docs.py` | 原样复制的 DevHarness 工具 | 治理工具入口，无业务 API |
+| `tests/` | 上游治理工具与文档结构测试 | 不验证阅读、NLP 或 SRS |
+
+不存在产品入口、数据库迁移或前端页面。拟定职责：identity（身份）、library（书库）、ingestion（导入）、lexicon（全局词典）、vocabulary（个人词语）、review（复习）、progress（统计）、administration（管理）。底座固定后再决定具体目录。
+
+## 两条主要执行路径
+
+目标路径一：上传文本 → 创建有所有者的导入任务 → 提取/分词/索引 → 章节就绪 → 阅读器按 token 展示原文和用户词语状态。
+
+目标路径二：阅读保存词语或短语 → 写入个人学习状态与例句 → 查询到期词条 → 服务端计算作答后的状态 → 写入幂等事件 → 更新统计。
+
+## 不可破坏的边界
+
+- 词典资源与个人释义分离，共享缓存不能混入个人记录。
+- Go/Python/JavaScript 的偏移契约必须统一；原文与内容版本必须保留。
+- API 与 Worker 复用业务规则；NLP 通过明确契约调用，不泄露模型内部对象到前端。
+- 任务至少可重试而不重复产出；学习事件不重复计数。
+- 共享 API/NLP/状态契约在批准后的主题 Wiki 中建立唯一来源，字段和版本尚未定案；不能以本页概要直接生成冻结接口。
@@ -0,0 +1,43 @@
+<!-- gitea-wiki-mirror:start -->
+generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
+wiki_page: Business-Rules-and-Glossary
+wiki_url: https://git.ilapage.cn/OPC/lexgo/wiki/Business-Rules-and-Glossary.-
+wiki_revision: 014f3da14206e994d55fd32f9c75dbc7220af5f0
+synchronized_at: 2026-09-10T06:27:41Z
+<!-- gitea-wiki-mirror:end -->
+
+# 业务规则与术语
+
+
+## 核心术语
+
+| 术语 | 含义与边界 |
+|---|---|
+| 书籍 / 章节 | 内容集合 / 可阅读处理单元；不限于小说 |
+| 词典词条 | 共享查询资源，不等于用户保存释义 |
+| 个人词语 / 短语 | 用户、语言与词条类型共同限定的学习项 |
+| lemma | 词元/词形还原结果；不能擅自与原词合并学习状态 |
+| SRS | 间隔复习；原版规则不应直接称为 FSRS |
+| 练习 | 不改变复习调度的练习模式 |
+| 轻量模式 | 裁剪流程，不能裁剪数据与验证底线 |
+
+## 工单状态
+
+见[工作流](https://git.ilapage.cn/OPC/lexgo/wiki/Development-Workflow.-)；“代码完成”“AI 自测通过”和“人工验收通过”是不同状态。
+
+## 稳定业务规则
+
+此处“稳定”指准备纳入产品规则的候选语义，并非已批准或已实现：
+
+1. 同一用户、语言、词语跨章节应共享学习状态；不同用户互相隔离。
+2. 忽略与已知分开统计。原版内部 stage 为已知 0、忽略 1、新词 2、学习等级 1～7 对应 -1～-7；内部新设计可显式建模，互通时保留正确映射。
+3. 完成阅读关闭自动置已知开关时，不批量更改新词；重复完成不能重复累计。
+4. 服务端计算复习状态；到期、重学、跨日、时区、边界等级和重复作答要用固定时钟样例验证。
+5. 导入失败应可见、可重试，重试不产生重复章节或旧版本索引覆盖。
+6. CSV 缺列与显式空值语义不同；词汇 CSV 不承担全实例备份。
+7. 普通用户直接访问管理员 API 必须被拒绝；隐藏菜单不构成授权。
+8. 原文空白、标点、Unicode 与位置可还原；词语身份、短语重叠优先级和规范化规则需批准后固定。
+
+## 新项目需要补充什么
+
+M0 固定首发语言语料、词条身份规则、短语选择与重叠规则、SRS 对照样例、时区边界、管理员可见范围、删除级联和恢复口径。性能目标 N08 仅为候选指标，需按硬件、词典和并发数据实测后定版。
@@ -0,0 +1,43 @@
+<!-- gitea-wiki-mirror:start -->
+generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
+wiki_page: Local-Development-and-Verification
+wiki_url: https://git.ilapage.cn/OPC/lexgo/wiki/Local-Development-and-Verification.-
+wiki_revision: 205b5548e0c2b30a4dd517c9e4cfcef0b823223e
+synchronized_at: 2026-09-10T06:27:42Z
+<!-- gitea-wiki-mirror:end -->
+
+# 本地开发与验证
+
+## 环境要求
+
+当前工作区为 Windows PowerShell，文档工具使用 Python 3。产品 Go、Node、MySQL 8 小版本、Redis、NLP 和模型版本在 M0 锁定，尚无产品运行环境。
+
+## Windows PowerShell 与 UTF-8
+
+读中文使用 `Get-Content -Encoding utf8`，复杂路径使用 `-LiteralPath`。Python 输出可设置进程 `PYTHONIOENCODING=utf-8`；文件解码与终端显示分别处理。不得打印凭据。
+
+### PowerShell 语法与外部命令
+
+不要套用 Bash heredoc；Python 脚本可用单引号 here-string。通过 `$LASTEXITCODE` 检查外部命令，使用原生 PowerShell 路径操作，避免跨 shell 拼接。
+
+## 第一次运行
+
+从仓库根目录执行：
+
+| 命令 | 预期与边界 |
+|---|---|
+| `python dev_scripts/harness.py --help` | 退出码 0，列出工具命令 |
+| `python dev_scripts/harness.py check --strict` | 退出码 0，正式主题结构与镜像元数据完整；不单独证明线上状态 |
+| `python dev_scripts/harness.py sync --verify` | 从配置目标读取并同步全部映射页面，再严格检查，预期退出码 0 |
+| `python -m unittest discover -s tests -v` | 全部治理测试通过，不证明阅读器、NLP、SRS 已实现 |
+| `git status --short --branch` | 显示分支与待提交变化，提交后应无意外改动 |
+
+同步会保护已有未提交镜像改动。新项目首次导出前先保存原有资料并提交引导材料；不跳过脏文件检查。凭据只通过安全配置或环境变量 `GITEA_TOKEN` 提供，不进入命令文本、日志或 Git。当前 MCP 连接其他站点，使用 API 的原因见初始化记录。
+
+## 常用调试方式
+
+先处理第一个可定位错误。页面缺失先发布、回读，不伪造 revision；配置错误先核对 owner/repository。产品阶段按用户/语言、任务、API、Worker/NLP 和数据文件逐层追踪，日志避免个人正文和凭据。
+
+## 完成修改前
+
+文档检查来源、链接、事实/建议区分和工作量加总；工具运行受影响的现有测试。产品阶段按具体工单测试隔离、Unicode、幂等、复习或恢复，未执行部分如实记录。当前没有 go.mod、package.json 或 Compose，不能声称产品能启动。
@@ -0,0 +1,30 @@
+<!-- gitea-wiki-mirror:start -->
+generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
+wiki_page: Common-Changes
+wiki_url: https://git.ilapage.cn/OPC/lexgo/wiki/Common-Changes.-
+wiki_revision: 168796cda21f6e0dacc9a3d44cf053caf38044e4
+synchronized_at: 2026-09-10T06:27:43Z
+<!-- gitea-wiki-mirror:end -->
+
+# 常见修改
+
+
+## 风险分级
+
+文案或明确的局部样式走轻量直接实施；新增导入器、阅读页面、词条身份变化、SRS 算法、权限与迁移均需单元工单和对应设计。
+
+## 修改 Wiki 文案
+
+先改线上主题页、回读，再同步核心镜像。旧草稿只用于本轮整理，不再作为后续编辑入口。两份原始调研分歧在项目档案 D01～D08 登记，不能靠删除一份来“解决”。
+
+## 调整 Harness 检查
+
+先判断是文档不完整、远端缺失还是工具问题。工具来自固定上游基线，不为通过检查移除镜像或线上回读门禁。真实工具改动单独记录上游差异，并运行治理工具测试。
+
+## 看懂 Agent 的修改
+
+先看目标和状态，再看文件差异、测试证据、未验证部分及回退方法。没有产品代码时，架构图或目录建议只能证明已做设计。涉及数据或状态的修改必须能解释一个具体输入经过修改后的输出。
+
+## 产品阶段的常见入口
+
+新增词典先定义格式/许可/语言/错误报告再实现 lexicon；新增导入源先定义限制与重试语义再实现 ingestion；修改复习先固定状态转换样例再实现 review。具体路径在工程创建后更新，不把规划模块当作存在的文件。
@@ -0,0 +1,24 @@
+<!-- gitea-wiki-mirror:start -->
+generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
+wiki_page: Troubleshooting
+wiki_url: https://git.ilapage.cn/OPC/lexgo/wiki/Troubleshooting
+wiki_revision: c202a8adb9b720981761e07f52fb7c0033d6d7d2
+synchronized_at: 2026-09-10T06:27:43Z
+<!-- gitea-wiki-mirror:end -->
+
+# 故障排查
+
+## 排查顺序
+
+| 现象 | 判断与处理 | 成功条件 |
+|---|---|---|
+| 没有产品启动入口 | 当前仅文档阶段，先完成 M0 和工程创建 | 有真实构建/运行命令后更新验证页 |
+| MCP 看不到 LexGo | 当前 MCP 指向其他站点；以用户确认的 git.ilapage.cn 为准 | API 能读取 OPC/lexgo |
+| 新 Wiki 列表 404 | 先确认仓库存在且 has_wiki=true；未初始化时创建 Home 并回读 | Home 有正文和 revision |
+| sync 拒绝脏镜像 | 检查并保存合法本地修改，不覆盖现有改动 | 提交/妥善保存后重试 |
+| check 缺少标题或映射 | 补齐真实主题和显式映射 | check --strict 通过 |
+| 数据库方案冲突 | 用户已确定 MySQL 8，历史 PostgreSQL 建议被覆盖 | 档案和新方案一致 |
+
+## 必须停止的情况
+
+目标仓库身份不清时停止远端写入；页面无法回读、无 revision 或同步失败时停止产品编码。数据越权、破坏性操作超出授权时停止相关操作。独立文档整理可以继续。
@@ -0,0 +1,258 @@
+<!-- gitea-wiki-mirror:start -->
+generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
+wiki_page: New-Project-Documentation-Setup
+wiki_url: https://git.ilapage.cn/OPC/lexgo/wiki/New-Project-Documentation-Setup.-
+wiki_revision: 1f84d8d38a6052120351da56639d88b70e99f58f
+synchronized_at: 2026-09-10T06:27:44Z
+<!-- gitea-wiki-mirror:end -->
+
+# LexGo 初始化记录
+
+## 本项目状态与证据边界
+
+2026-09-10 用户确认远端 `https://git.ilapage.cn/OPC/lexgo.git`；main 已有 DevHarness 引导提交 `ecab8995026e57f2c28f307a6aa32b871cb3163f`。本轮将本地 LexGo 连接此远端，保留原调研，发布项目主题和工作量，再执行同步与验证。数据库 MySQL 8、治理轻量已确认，产品代码尚未开始。
+
+本轮使用 Gitea API 的原因：已配置 MCP 连接 `ilaer.eicp.net:8418`，目标却是 `git.ilapage.cn`，MCP 无法操作该目标。先用目标站点安全配置验证身份和仓库，凭据只读入进程；不复制到代码、日志、工单或 Wiki。目标仓库已启用工单/Wiki，初始页面列表返回 404；先创建 Home 并回读 revision 后才创建其他页面。
+
+发布准备、正文回读、同步校验和产品验收是不同证据。最终本地命令与结果见 Git 提交说明及本轮结果报告；不能把工具单测中的模拟 Wiki 输出当真实线上状态。
+
+现有 docs/task 内容属于上游模板历史，不作为 LexGo 的任务完成记录，也不带入项目镜像。原有四份调研分别作为参考页面保留，数据库分歧以 MySQL 8 决策为准。未创建无实际作用的 Epic/MVP 或任务快照。
+
+当前交付对象为负责人和开发维护者，交付规划、规则和估算。尚无产品部署实例；部署模板仅供后续环境确认后使用，不预建可运行运维手册。
+
+## 后续产品步骤
+
+完成本文的 Wiki 门禁后，按已确认目标组织 M0 技术验证；工程底座、Python NLP、首发语言与旧数据范围仍需在方案中明确，不把“继续文档初始化”视为整份产品方案批准。
+
+以下为本项目沿用的 DevHarness 初始化规范，示例不代表 LexGo 已执行产品开发。
+
+# 新项目文档初始化
+
+## 本页用途
+
+从 DevHarness 创建新项目时，指导 Claude/Codex Agent快速建立可供初级程序员阅读的项目文档。初始化只生成可靠的第一版，不允许 Agent 臆造业务规则、凭据、部署环境或生产数据。
+
+## 初始化顺序
+
+### 1. 建立项目边界
+
+由项目负责人确认：
+
+- 项目名称和一句话目标；
+- 用户和主要使用场景；
+- 技术栈和支持环境；
+- Gitea 仓库、默认分支和维护者；
+- 安全、权限、数据和发布红线。
+
+把项目专用红线写入根目录或子目录 `AGENTS.md`。
+
+#### 选择治理模式
+
+使用 DevHarness 创建新项目时默认采用轻量模式，并在 Project-Profile 记录实际模式和理由：
+
+- 目标项目尚未填写治理模式时按轻量模式执行并提示补写，不因此阻塞产品开发；从模板继承的“DevHarness / 标准”文字不代表目标项目已经选择标准模式；
+- 轻量模式尤其适合内部、单人、低风险项目，但默认值不限制后续按真实风险升级；
+- 只有项目负责人明确选择并记录理由时，才将项目默认值改为标准或高风险；
+- 多人协作、对外交付、跨模块接口较多或需要稳定审计时，可以明确选择标准模式；
+- 项目整体持续涉及权限、安全、支付、真实个人/生产数据、迁移、并发、删除或不可逆操作时，可以明确选择高风险模式；
+- 单个任务风险高于项目默认模式时只升级该任务，不自动升级整个项目；不为可能发生的情况预设额外门禁；
+- DevHarness 上游模板自身继续采用标准模式。
+
+治理模式只裁剪工单、原型、测试和文档流程，不覆盖凭据、授权边界和真实测试证据。使用虚构手机号等测试数据时记录其为虚构数据即可，无需为了形式执行脱敏流程；来源不明或来自真实用户时按已确认的数据处理规则执行。
+
+#### 需求总览启用条件
+
+从模板创建项目时保留 Product-Requirements-Overview 这一核心页面。仅有探索性想法时可以只记录已确认目标和待确认项；形成 MVP、长期需求超过少量工单或开始制作原型时，必须建立并持续维护需求索引，把需求领域、状态、主题 Wiki、工单、原型和验收入口关联起来。不要复制完整工单或聊天记录。
+
+### 2. 选择建设基线
+
+确定技术方案前，优先评估是否存在功能和架构匹配、持续维护、许可证兼容且工程流程完善的开源项目。这里要求的是“先评估”，不是强制采用开源项目，也不能只根据知名度、Star 数量或演示效果决定。
+
+至少检查：
+
+- 核心功能、架构和支持平台是否匹配，哪些能力可以直接保留；
+- 许可证是否允许预期的使用、修改、分发和商业模式；不确定时交由负责人或法律专业人员确认；
+- 最近维护活跃度、发布频率、Issue 处理和社区或维护团队的持续性；
+- 已知安全问题、依赖健康度、供应链风险和安全响应方式；
+- 自动化测试、CI、发布、升级、回退和文档是否足以支持长期维护；
+- 定制、学习、迁移和后续跟踪上游的总成本是否低于从零开发；
+- 是否能够固定上游仓库和基线版本，并建立合并上游更新、兼容验证和退出方案。
+
+满足适配、许可证、安全、维护和总成本条件时，优先在该基线上二次开发。不存在合适基线，或引入后会增加不可接受的许可证、安全、架构或维护风险时，可以从零开发，但必须记录排除候选项目和选择从零开发的主要原因。
+
+采用开源基线时，在 Project-Profile 的“技术栈与运行环境”记录上游项目名称、仓库地址、基线版本或提交、许可证、保留能力、定制范围和上游升级策略。尚未确认的候选和取舍先写入首个技术方案工单，不得把假设写成项目事实。
+
+#### 工程基线裁剪
+
+所有项目采用最小工程基线，不按项目规模免除事实和验收要求：
+
+- 用完整 Git commit 和核验日期固定“当前事实”的代码基线；
+- 分开记录“当前已经实现什么”和“目标规范要求什么”，不得用目标描述宣称现有能力；
+- 写明证据路径、可确认行为、未覆盖范围和证据不能证明什么；
+- 明确目标、非目标、安全边界和可判定的验收标准；
+- 跨子项目接口或契约指定唯一事实来源和各端验证命令。
+
+当前事实以指定 commit 的代码、可执行测试和运行证据为依据；目标行为以人工批准的契约、ADR 和业务规则为依据。两者冲突时登记为带编号的差距或缺陷，不允许现有错误实现覆盖目标规范，也不允许目标设计冒充当前实现。
+
+出现跨团队或跨仓库协作、外部交付、接口或状态机复杂、权限安全、迁移并发、明显文档漂移等情况时，采用增强工程基线：按需增加 GAP-ID 差距表、带状态的 ADR、接口与数据契约、需求追踪测试矩阵，以及 PR、RC、Definition of Done 分层门禁。SRS、SAD、安全、运维和测试文档按风险与读者选择，不强制小型单人项目建立完整文档集。
+
+#### 判断案例
+
+以下案例用于说明判断方式，不代表必须选择某种技术或具体开源项目。
+
+##### 案例一：适合基于成熟项目二次开发
+
+计划开发企业内部管理系统。候选项目已经具备用户、权限、审计日志、基础数据管理和自动化测试；功能与目标架构基本匹配，许可证允许预期使用，项目持续维护，发布与升级流程完整，预计只需修改业务模块和界面。
+
+- 结论：优先基于该项目二次开发。
+- 原因：可以减少通用功能的开发和验证成本，定制范围可控。
+- 记录：上游仓库、基线版本、许可证、保留功能、定制模块和上游升级方式。
+
+##### 案例二：项目成熟但许可证不兼容
+
+候选项目功能完整、维护活跃、文档充分，但许可证与当前产品的闭源分发、商业模式或交付条件不兼容。
+
+- 结论：不采用该项目作为建设基线。
+- 原因：技术成熟度不能消除许可证风险；不确定结论必须交由负责人或法律专业人员确认。
+- 记录：候选项目、许可证限制、确认人员和排除原因。
+
+##### 案例三：功能相似但改造成本过高
+
+候选项目表面上覆盖大部分功能，但数据模型、权限体系和部署结构与目标项目差异很大，需要大量删除模块、重写主要接口，并长期维护上游冲突。
+
+- 结论：不直接基于完整项目二次开发，可以评估只复用合适的组件或设计思路。
+- 原因：二次开发的总成本、理解成本和长期维护风险已经高于自主实现核心业务。
+- 记录：主要结构差异、改造估算、长期维护风险和最终选择。
+
+##### 案例四：只复用成熟框架或组件
+
+没有功能高度匹配的完整开源产品，但存在成熟的应用框架、更新组件、日志组件或通信库。
+
+- 结论：从零开发业务功能，同时复用经过评估的成熟框架或组件。
+- 原因：复用基础能力不等于必须采用完整产品，可以避免被不匹配的业务架构绑定。
+- 记录：每个依赖的用途、版本、许可证、安全边界、升级方式和可替换方案。
+
+每个案例的实际评估都必须记录候选项目、判断依据、最终选择、未采用原因，以及升级或退出方式。
+
+### 3. 识别子项目与交付单元
+
+先判断仓库中有几个应用、服务、客户端、库或其他可独立交付的部分。对每个部分确认：
+
+- 职责和目录边界；
+- 技术栈、依赖和支持环境；
+- 构建、测试和运行命令；
+- 是否拥有独立版本号和发布方式；
+- 适用的根目录或子目录 `AGENTS.md`；
+- 与其他子项目共享的接口、数据或业务流程；
+- 共享契约的唯一事实来源和兼容要求。
+
+把结果写入 Project-Profile 的“子项目与交付单元”。单应用项目只填写一个交付单元；多应用单仓库为规则不同的目录增加子目录 `AGENTS.md`，但不因为技术栈不同自动拆仓，也不强制统一版本和发布周期。
+
+### 4. 建立 Gitea
+
+创建远端仓库并完成允许的初始引导提交，开启工单和 Wiki；必须先有远端仓库，才能填写该仓库的线上 Wiki。配置项目已有的 Gitea MCP 和安全凭据；优先使用 MCP，MCP 不可用或不支持所需写操作时才回退到 Gitea API，并在初始化工单记录原因。凭据只通过环境或 MCP 安全配置提供。
+
+引导提交后按项目明确选择的治理模式判断是否需要工单；尚未选择时按轻量模式执行并提示补写，不因此阻塞产品开发。轻量模式的明确小 Bug、局部 UI 和单模块低风险调整可以直接实施；完整独立需求、新页面、跨模块功能和中高风险变化必须先有单元任务工单。开始产品代码前仍须通过第 8 步的线上 Wiki 初始化门禁。
+
+### 5. 修改镜像配置
+
+把 `wiki-docs.json` 中的地址、owner 和 repository 改成新项目；只保留核心主题映射。可选任务快照不逐页登记，默认任务流程不创建。
+
+确认当前目录确实是新项目副本、且 DevHarness 历史归档快照不需要保留后，可以移除对应 `docs/task/` 文件。不要在原 DevHarness 仓库或已有业务项目中执行这项清理。
+
+不要把 PAT 写入配置。
+
+### 6. Agent 检查项目事实
+
+Agent 只读检查：
+
+- README、配置和依赖文件；
+- 启动入口；
+- 主要模块和目录规则；
+- 测试、格式和静态检查命令；
+- 日志、示例配置和测试数据；
+- 已存在的接口、数据模型和状态。
+
+区分“代码中确认的事实”“负责人确认的业务规则”和“仍待确认的假设”。
+
+### 7. 确定交付对象和文档
+
+由项目负责人确认哪些岗位或客户会实际使用、部署、管理、支持、集成或验收产品，并为每类对象确定：
+
+- 需要完成的工作；
+- 所需文档类型；
+- 文档可见范围；
+- 适用版本、负责人和验证人；
+- 不得对外披露的内部信息。
+
+按照[交付文档指南](https://git.ilapage.cn/OPC/lexgo/wiki/Delivery-Documentation-Guide.-)选择文档，使用[岗位文档模板](https://git.ilapage.cn/OPC/lexgo/wiki/Audience-Document-Template.-)按需创建。没有明确读者的文档不创建，不预建空白的用户手册、管理员手册或运维手册。
+
+### 8. 先创建线上 Wiki
+
+#### 在线创建与回读门禁
+
+1. 使用配置好的 Gitea MCP 查询目标仓库的 Wiki 页面列表；MCP 不可用时使用 Gitea API，并记录回退原因。
+2. 如果 `Home` 不存在，先创建 `Home`。创建后立即在线回读正文并记录 revision；`Home` 可读取后才能继续。
+3. 依照 `wiki-docs.json` 逐页创建或更新其他核心页面。每页写入后在线回读正文，记录页面名和 revision。
+4. 本地 `docs/` 是模板或 Wiki 镜像；本地文件存在、标题完整或 `harness.py check --strict` 通过，都不能单独证明线上 Wiki 已初始化。
+5. 页面缺失、回读失败或没有 revision 时停止初始化，不得开始产品代码；Gitea 恢复后从首个失败页面继续。
+
+至少创建或填写：
+
+1. Home；
+2. Project-Profile；
+3. Product-Requirements-Overview；
+4. Architecture-and-Code-Map；
+5. Business-Rules-and-Glossary；
+6. Local-Development-and-Verification；
+7. Common-Changes；
+8. Troubleshooting；
+9. Development-Workflow；
+10. Delivery-Documentation-Guide；
+11. Audience-Document-Template；
+12. Task-Archive-Template。
+
+Home 给出建议阅读顺序；每个命令必须有预期结果；代码地图必须指出入口和测试位置。具体岗位文档仅按第 7 步确认的受众创建。
+
+部署页按需创建，不属于必需核心页面：项目负责人确认存在需要部署的常驻服务时，复制[部署文档模板](https://git.ilapage.cn/OPC/lexgo/wiki/Deployment-Template.-)在本项目 Wiki 建立 `Deployment-and-Operations` 页面，并在本项目 `wiki-docs.json` 增加映射（建议镜像到 `docs/10-deployment-and-operations.md`）；确认没有常驻服务时，在初始化工单记录原因，不创建该页面。
+
+### 9. 人工确认
+
+项目负责人至少确认：
+
+- 一句话目标和业务术语；
+- 关键业务规则和状态；
+- 权限、安全和数据边界；
+- 真实运行、测试和部署命令；
+- 本项目是否有需要部署的常驻服务；
+- 哪些修改属于高风险；
+- 交付对象、文档可见范围和外部信息边界。
+
+### 10. 导出镜像并检查
+
+```powershell
+python dev_scripts/harness.py sync --verify
+python -m unittest discover -s tests -v
+```
+
+只有线上 Wiki 确认后才导出核心 `docs/`。默认不创建或导出任务归档；用户明确要求专项快照时才运行 `archive`、`export` 或 `export --all`。旧项目的任务归档快照不能带入新项目历史。
+
+`harness.py sync --check` 会在线读取全部显式映射页面；任一页面不存在、无法读取或 revision 与镜像不一致时，初始化不通过。只有上述命令全部成功后才允许开始产品代码。
+
+## 完成标准
+
+初级程序员应能仅依靠 Home 和链接页面回答：
+
+- 项目解决什么问题；
+- 当前有哪些长期需求、状态如何，详细规则、工单、原型和验收入口在哪里；
+- 怎样启动和运行测试；
+- 常用功能从哪个目录和入口开始读；
+- 一个简单修改通常要改哪里、验证什么；
+- 哪些情况必须停止并交给 Agent 或负责人；
+- 项目采用哪个建设基线，为什么适合二次开发，或者为什么选择从零开发；
+- 采用开源基线时，上游仓库、基线版本、许可证、定制范围和升级策略是什么；
+- 项目包含哪些子项目和独立交付单元，各自怎样构建、测试和发布；
+- 跨子项目共享什么接口或契约，其唯一事实来源在哪里；
+- 项目需要向哪些岗位交付什么文档，以及哪些内容不能对外提供。
+
+回答不了的问题应继续补充主题文档，而不是堆入任务归档。
@@ -0,0 +1,236 @@
+<!-- gitea-wiki-mirror:start -->
+generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
+wiki_page: Existing-Project-Adoption-Guide
+wiki_url: https://git.ilapage.cn/OPC/lexgo/wiki/Existing-Project-Adoption-Guide.-
+wiki_revision: 974238bcadff9718faf8b368b7e883c77670954b
+synchronized_at: 2026-09-10T06:27:45Z
+<!-- gitea-wiki-mirror:end -->
+
+
+# 已有项目接入 DevHarness 指南
+
+## 本页用途
+
+本页用于把 DevHarness 的文档模板和开发流程增量接入已经存在的项目。已有项目通常已经有代码、规则、文档、工单、Wiki、Git 历史和未完成工作，因此接入目标是补齐必要能力，不是把项目重置成 DevHarness 模板副本。
+
+接入必须先只读盘点、确认差异方案，再建立单元任务工单实施。未经确认不得覆盖、删除、重命名或批量迁移已有内容。
+
+## 与新项目初始化的区别
+
+| 场景 | 新项目初始化 | 已有项目接入 |
+|---|---|---|
+| 项目事实 | 从代码骨架和负责人确认开始建立 | 优先保留并核对已有事实 |
+| 规则文件 | 可以从模板建立第一版 | 必须合并已有规则，不能直接覆盖 |
+| 文档 | 创建核心主题页 | 逐页判断保留、迁移、合并或停止维护 |
+| 工单和 Wiki | 新建并开始使用 | 先检查已有工单、Wiki 和状态体系 |
+| Git 历史 | 允许一次引导提交 | 保留全部历史，不使用引导提交例外 |
+| 任务证据 | Gitea 工单；任务快照仅显式按需创建 | 保留已有工单；不复制 DevHarness 或其他项目的历史归档 |
+| 接入方式 | 一次建立最小骨架 | 分阶段增量接入并逐步验收 |
+
+从模板创建全新仓库时使用[新项目文档初始化](https://git.ilapage.cn/OPC/lexgo/wiki/New-Project-Documentation-Setup.-)；项目已有业务提交、用户或维护历史时使用本页。
+
+## 接入前只读盘点
+
+Agent 在提出方案前只读检查：
+
+- 根目录和相关子目录中的 `AGENTS.md`、`CLAUDE.md` 及其他 Agent 规则；
+- README、现有 `docs/`、Wiki 页面、工单模板和任务状态；
+- Git 默认分支、远端、提交历史、未提交修改和忽略规则；
+- 语言、框架、依赖、启动入口、主要模块和目录职责；
+- 格式检查、静态检查、单元测试和必要集成测试命令；
+- 配置、日志、接口、数据模型、权限、安全、部署和发布边界；
+- 已完成、进行中、阻塞和待验收任务；
+- 现有长期文档的事实来源、负责人和更新方式。
+
+输出时区分：
+
+1. 从代码、配置或现有系统确认的事实；
+2. 项目负责人确认的业务规则；
+3. 尚待确认的假设；
+4. DevHarness 与现有规则的冲突；
+5. 与接入无关、必须保留的工作区改动。
+
+只读盘点不授权修改文件、创建 Wiki、迁移文档或改变工单状态。
+
+## 已有内容保护原则
+
+- 保留 Git 历史、分支、标签和当前任务状态。
+- 保留已有 `AGENTS.md`、README、规则和项目专用红线；DevHarness 规则按冲突结果增量合并。
+- 保留与接入无关的未提交改动，不重置、不覆盖、不混入提交。
+- 不复制 DevHarness 的 `docs/task/`、任务归档映射和历史工单。
+- 不因采用 Wiki-first 就立即删除原本地文档；先逐页确认事实来源和迁移状态。
+- 不把模板占位值当成项目事实，不臆造技术栈、命令、业务规则、凭据或环境。
+- 不把密码、令牌、Cookie、私钥、个人数据或生产数据带入工单、Wiki和镜像。
+- 页面删除、重命名、历史清理和事实来源切换必须单独确认。
+
+## 多应用单仓库判断
+
+一个 Git 仓库可以包含多个技术栈不同、能够独立构建和发布的应用或终端。技术栈不同本身不是拆仓理由；先把每个子项目和交付单元记录到 Project-Profile，再根据实际协作边界判断。
+
+### 适合继续单仓库
+
+- 多个应用共同完成一条产品或业务链路；
+- 由同一团队维护，仓库权限基本一致；
+- 接口变更需要在一个工单中同步修改或验证多端；
+- 共享契约和业务规则由同一项目维护并指定唯一事实来源；
+- 仓库体积、测试时间和工具性能尚未明显影响开发；
+- 初级维护者和 Agent 能通过目录、子目录 `AGENTS.md` 和文档入口清楚定位。
+
+### 可以考虑拆仓
+
+- 长期由不同团队独立负责并需要不同访问权限；
+- 发布周期、版本策略和验收负责人已经完全独立；
+- 某个应用被多个产品复用或需要单独对外提供；
+- 仓库体积、检出、索引或测试耗时已经持续影响效率；
+- 共享接口已经版本化、兼容周期明确，并有跨仓契约测试；
+- 跨应用任务很少，拆仓后的协调成本低于继续共仓。
+
+不满足这些条件时，优先保持单仓库并完善边界，不为了目录整洁或技术栈不同而拆仓。
+
+### 保持单仓库时的最小规则
+
+- 根目录 `AGENTS.md` 只放共同流程、安全和跨项目规则，技术栈专用规则写入子目录 `AGENTS.md`。
+- 每个交付单元拥有自己的构建、测试、版本和发布方式，不强制统一版本。
+- 单元任务必须声明只影响哪个子项目、是否跨子项目、是否修改共享接口，以及各端需要执行的验证。
+- 共享接口或契约只能指定一个事实来源；其他文档引用它，不复制一个“差不多”的版本。
+- 跨子项目契约变更在同一工单中更新事实来源，并验证所有受影响端。
+- 拆仓属于事实来源、任务和发布边界变化，必须另建工单、确认迁移和回退方案后实施。
+
+## 增量接入顺序
+
+### 1. 确认差异方案
+
+根据盘点结果列出目标、非目标、复用项、改写项、冲突项、影响范围、风险、回退、验证和文档影响。方案得到用户明确确认前不实施。
+
+### 2. 建立单元任务工单
+
+使用目标项目的 Gitea 建立接入工单，记录原始需求、范围、依赖、方案和验收标准。目标项目没有可用 Gitea 时，先提交完整工单草稿并说明阻塞，不默认绕过。
+
+### 3. 接入共同规则和工单流程
+
+优先增量合并根规则、Claude 入口和单元任务模板。项目专用安全、业务和目录规则继续有效；冲突时由负责人决定最终表述。
+
+### 4. 确定长期文档事实来源
+
+为每份已有文档标记：
+
+- 保留在 Git：与特定代码版本强绑定；
+- 迁移到 Wiki：长期架构、业务规则、开发规范或操作说明；
+- 合并：内容重复但各有有效事实；
+- 暂不迁移：事实未确认或当前不影响接入；
+- 停止维护：必须由负责人确认，不能由 Agent 自行删除。
+
+切换到 Wiki-first 的页面必须先在线上创建或更新、读取确认，再建立 `wiki-docs.json` 映射并导出本地镜像。避免 Wiki 和手写本地文档长期形成双事实源。
+
+### 5. 接入 Harness 工具
+
+仅复制当前项目实际需要的 `dev_scripts/` 工具、配置和测试。业务脚本使用独立目录。根据目标项目调整核心页面、路径、命令和结构检查，不照搬 DevHarness 项目值。
+
+### 6. 分阶段验证
+
+先验证工单和规则入口，再验证 Wiki 映射，最后启用严格检查。每阶段采用“执行 → 首个真实错误 → 最小修复 → 继续”的闭环，不用一次接入全部旧文档。
+
+### 7. 提交和验收
+
+提交只包含当前接入工单相关文件。在工单评论集中记录测试、未验证部分、提交哈希，以及真实变化的 Wiki revision 或“无长期文档影响”；保持工单“待验收”，等待用户明确验收后再关闭。默认不创建任务归档。
+
+## 后续升级
+
+已接入的项目必须以 Project-Profile 中记录的 DevHarness 来源和当前基线为起点升级，不得重新复制整个模板，也不得用“最新版本”代替可复现的目标提交。
+
+### 升级步骤
+
+1. 读取目标项目的 Project-Profile，确认 DevHarness 来源仓库、当前基线完整提交、最后升级日期和项目适配说明；字段缺失时先补齐可验证事实，无法确认则停止。
+2. 选择一个明确、已审阅的 DevHarness 目标提交，记录旧基线和新基线。先比较两个上游提交之间的变化，再判断这些变化如何作用于目标项目。
+3. 只读比较与 Harness 有关的 `AGENTS.md`、`CLAUDE.md`、工单模板、`dev_scripts/`、Harness 测试和核心 Wiki 结构，把差异分为“直接采用、按项目改写、冲突待确认、不采用”。不得把 DevHarness 的项目事实、工单或任务归档带入目标项目。
+4. 在目标项目建立单元任务工单，写明升级范围、差异分类、项目专用规则、风险、回退、验证和文档影响。会改变产品行为的内容必须拆成独立任务。
+5. 按工单最小合并，保留目标项目更具体的业务、安全、权限和目录规则，以及 Git 历史和无关工作区修改。无法判断哪一方规则有效时停止并等待负责人确认。
+6. 长期文档先更新目标项目 Wiki，读取确认后再同步目标项目的核心 `docs/` 镜像；不得用 DevHarness 的本地镜像覆盖目标项目文档。
+7. 执行目标项目规定的必要检查和受影响测试，提交并回写证据。工单保持“待验收”。
+8. 用户验收通过后，确认目标项目 Project-Profile 已记录新 DevHarness 基线完整提交和升级日期，再关闭工单。升级失败或回退时保留旧基线。
+
+### 升级停止条件
+
+除本页已有的冲突停止条件外，来源仓库与记录不一致、旧基线不存在、目标提交未明确、差异跨越过大而无法可靠分类，或升级需要覆盖项目专用安全规则时，都必须停止并请求确认。可以把升级拆成多个单元任务，但每个任务都要声明最终采用的同一目标基线。
+
+### 可复制升级指令
+
+```text
+请把当前项目从 Project-Profile 记录的 DevHarness 基线升级到
+<DevHarness 目标完整提交哈希>。
+
+先只读比较来源仓库中“旧基线..目标基线”的 Harness 变化和当前项目
+适配，列出直接采用、按项目改写、冲突待确认和不采用的内容，以及
+风险、回退、验证和文档影响。不要覆盖项目专用规则、业务文档、Git
+历史或无关改动，不复制 DevHarness 工单和任务归档。方案确认后在
+当前项目建单并实施；长期文档先改当前项目 Wiki，再同步本地镜像。
+工单保持待验收，验收通过后确认 Project-Profile 已记录新基线。
+```
+
+路径和目标完整提交哈希必须替换为真实值；目标提交未明确时只分析，不实施。
+
+## 冲突处理和停止条件
+
+出现以下情况时停止实施并请求负责人确认：
+
+- 现有规则与 DevHarness 的安全、权限、事实来源或验收规则冲突；
+- 无法判断某份文档应该保留、迁移、合并还是停止维护；
+- 需要删除、重命名 Wiki 页面、覆盖已有文件或清理历史归档；
+- 需要改变接口、数据库、权限、部署、发布或其他产品行为；
+- 工作区存在可能与接入文件重叠的未知修改；
+- Gitea、Wiki、凭据或远端权限不可用；
+- 真实命令、环境或业务规则无法从证据或负责人确认。
+
+相邻问题最多提示或另建工单，不混入接入任务。
+
+## 可复制 Agent 指令
+
+### 只分析
+
+```text
+请把 <DevHarness 路径> 的文档模板和开发流程接入当前已有项目。
+
+先只分析，不修改文件、工单或 Wiki：
+
+1. 阅读 DevHarness 的 AGENTS.md、README.md、项目档案、开发工作流、
+   新项目文档初始化和已有项目接入指南。
+2. 阅读当前项目已有的 Agent 规则、README、docs、Gitea 工单模板、
+   Wiki 配置、代码入口、测试命令和目录结构。
+3. 列出已有规则、文档、任务状态、Git 历史和未提交改动。
+4. 对比后列出可复用项、必须改写项、冲突项、旧文档处理方式、
+   最小接入范围、风险、回退、验证和文档影响。
+5. 不复制 DevHarness 任务归档，不覆盖、删除或重命名已有内容，
+   不把模板占位值当成项目事实。
+6. 输出方案后停止，等待我确认。
+```
+
+### 方案确认后实施
+
+```text
+按照已确认方案建工单并做。
+
+严格按工单范围增量接入 DevHarness，保留当前项目已有规则、历史、
+任务状态和无关改动。长期文档先更新 Gitea Wiki，读取确认后再导出
+本地 docs 镜像。执行必要测试，提交实现并把最终证据回写工单，然后
+保持“待验收”；默认不创建任务归档，未经我明确验收不关闭工单。
+```
+
+路径、仓库地址和项目名称必须替换为当前环境的真实值。第二段指令只有在第一段方案已经明确确认后使用。
+
+## 最小验收清单
+
+- [ ] 已盘点规则、文档、任务、Git 历史和未提交改动。
+- [ ] 已识别所有子项目和独立交付单元。
+- [ ] 跨子项目共享契约已经指定唯一事实来源。
+- [ ] 已明确复用、改写、冲突和暂不处理内容。
+- [ ] 已保留项目专用规则、历史和无关改动。
+- [ ] 未复制 DevHarness 历史归档或模板项目事实。
+- [ ] 已为每类长期文档明确事实来源和迁移状态。
+- [ ] Wiki-first 页面已经读取确认并具有显式镜像映射。
+- [ ] Harness 检查已按目标项目调整并通过。
+- [ ] 必要测试、未验证部分、提交和最终证据已记录。
+- [ ] 工单处于待验收，未提前关闭。
+
+## 回退原则
+
+接入应拆成可回退的小提交。普通回退恢复本次新增或修改的规则、配置、检查和镜像映射，不触碰原有业务提交。Wiki 页面删除、重命名、历史清理或事实来源反向切换不是普通回退，必须另行建单并等待确认。
@@ -0,0 +1,66 @@
+<!-- gitea-wiki-mirror:start -->
+generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
+wiki_page: Product-Requirements-Overview
+wiki_url: https://git.ilapage.cn/OPC/lexgo/wiki/Product-Requirements-Overview.-
+wiki_revision: 77035d7811d6df3880b575e91d1ce224dec21e2e
+synchronized_at: 2026-09-10T06:27:45Z
+<!-- gitea-wiki-mirror:end -->
+
+# 产品需求总览
+
+
+## 本页用途
+
+连接调研、候选交付范围、工作量和验收。详细行为见 [中文需求提取](https://git.ilapage.cn/OPC/lexgo/wiki/LinguaCafe-Requirements.-)，两份分析冲突见[项目档案](https://git.ilapage.cn/OPC/lexgo/wiki/Project-Profile.-)。
+
+## 事实来源边界
+
+当前实现：无。当前证据：已有静态调研。以下状态全部为“待范围确认/未实施”；工单、原型及运行验收入口均尚未建立。不能用上游功能清单计算 LexGo 已完成比例。
+
+## 当前需求索引
+
+| 领域 | 需求定位 | 候选阶段 | 最小验收入口 |
+|---|---|---|---|
+| 身份与管理 | U01、A01/A02/A09、N01 | M1 | A/B 用户数据不可互访，普通用户直接管理 API 被拒绝 |
+| 内容库与文本处理 | U02/U03/U04/U08/U09、N02/N03/N04 | M0/M1 | 导入→就绪→阅读；失败重试无重复；原文可还原 |
+| 阅读器、词语与短语 | U10/U11/U12/U13/U16、N04/N07 | M0/M1 | 点词、划短语、跨章状态与完成阅读开关正确 |
+| 词典与语言资源 | U14、A03/A04、N05 | M0/M1 | 一种已验收语言查词与模型配置，本地核心无需翻译服务 |
+| 复习与词汇库 | U17/U19、A07、N02 | M0/M1 | 到期/重学/时区/等级样例，重复作答不重复记账 |
+| 统计、外观与移动 | U21/U24/U25、N07 | M1 基础、M2 补齐 | 事件统计一致、基础主题、手机与键盘操作 |
+| 备份恢复 | A10、N06 | M1 基础、M4 演练 | 空实例恢复数据库、文件、配置清单后抽样一致 |
+| 多格式导入 | U05/U06/U07 文件部分 | M2 | EPUB/网页/字幕文件成功与失败样例，明确格式限制 |
+| 功能完善 | U11 完整形态/U15/U18/U19 CSV/U22/U24 定制/U25 PWA/U26、A04 格式/A05/A06 | M2 | 练习不改调度、CSV 空值语义、TTS、设置及删除本人数据边界 |
+| 外部与语言专项 | U07 远程/U20/U23、A08 | M3 | 独立验证 Anki/Jellyfin/YouTube 和中日专项，可降级 |
+| 稳定化 | N01～N08 | M1 起持续，M4 集中 | 隔离、恢复、Unicode、幂等、性能实测；N08 待定版 |
+
+## 登记规则
+
+阶段与[工作量表](https://git.ilapage.cn/OPC/lexgo/wiki/Workload-Estimate.-)关联。正式建单后增加真实 URL、状态和设计版本；不编造 #1 等占位编号。拆分某个需求时保留原编号并注明子范围。
+
+## 原型与设计资产
+
+尚无原型。优先验证阅读器和短语交互；低风险管理表单沿用最终选定的规范即可。审核记录需包含链接/版本、覆盖范围及实际确认结果，未确认即保留草稿状态。
+
+## 状态规则
+
+范围确认后更新为待实施；开始执行才标实施中；有实际证据才标待验收；用户明确验收才标已验收。发生范围、技术基线或验收标准变化时更新主题与估算，不用“已写文档”替代产品状态。
+
+## 最小验收清单
+
+首版按完整学习闭环、词语状态一致、阅读完成开关、多用户隔离、管理员越权拒绝、任务失败恢复、固定时间复习、Unicode/短语定位、完整备份恢复九类场景验收。真实测试入口待工程建立后补齐。
+
+### 原型门禁
+
+按轻量模式，只在交互不确定性或明显返工风险下建立可审阅原型；独立功能仍需单元工单。
+
+### 线上原型与按需 HTML 快照
+
+默认以带版本的线上链接审核；仅用户明确要求才导出 HTML，已确认快照不得覆盖。
+
+### 原型确认记录
+
+当前无原型、无审核结论。后续记录链接、revision/日期、范围、确认人和结果。
+
+## 更新时机
+
+范围确认、实际实施状态变化或验收标准变化时更新索引；工单只有实际创建后才填写 URL。
@@ -0,0 +1,84 @@
+<!-- gitea-wiki-mirror:start -->
+generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
+wiki_page: Workload-Estimate
+wiki_url: https://git.ilapage.cn/OPC/lexgo/wiki/Workload-Estimate.-
+wiki_revision: bcba6674445cd28c44216167a321c348a1ae7469
+synchronized_at: 2026-09-10T06:27:48Z
+<!-- gitea-wiki-mirror:end -->
+
+# LexGo 开发工作量估算
+
+
+## 估算口径
+
+暂按两名熟悉 Go/Vue 的工程师、每人每周 5 个有效工作日、每日 8 小时计算。复用管理底座、保留 Python NLP、首发英语、有可用测试语料和合法可用的词典；一个产品、单一 MySQL 8 数据库，无 SaaS/原生 App/全离线同步。MySQL 8 已获用户确认，其他估算条件尚待确认。
+
+每项人日包含分析、实现、相关测试、评审修正和必要文档；不是纯编码时长。M4 只包含跨功能的额外稳定化，不重复计算各功能基础测试。日历周以两人能合理分工为前提，依赖、请假和确认等待会延长日历时间。AI 辅助未作为固定折扣，实际速度用 M0/M1 数据校准。
+
+首版目标暂按 P0 范围；M2/M3 按选定的 P1/P2 能力补齐。27 种语言全部达到质量承诺、旧实例全量迁移和商业扩展不在基准总额内。
+
+## 分阶段总量
+
+| 阶段 | 人日 | 人时 | 两人日历周参考 | 前置与退出条件 |
+|---|---:|---:|---:|---|
+| M0 风险验证与方案定版 | 10～20 | 80～160 | 1～2 | 确认首发语言/底座/数据库；分词位置、查词、复习样例和阅读交互可行 |
+| M1 首个核心可用版 | 50～80 | 400～640 | 5～8 | M0 通过；P0 学习闭环、隔离、幂等与基础恢复可验收 |
+| M2 主要功能补齐 | 30～50 | 240～400 | 3～5 | M1 稳定；选定 P1 格式、练习、CSV、显示与管理补齐 |
+| M3 外部/语言专项 | 30～60 | 240～480 | 3～6 | M1 接口稳定；选定集成与新增语言各有验收证据 |
+| M4 集中稳定化 | 20～40 | 160～320 | 2～4 | 前述目标范围完成；压测、恢复、升级和发布候选验证 |
+| **首版 M0+M1** | **60～100** | **480～800** | **6～10** | 可用闭环，不是全部功能复刻 |
+| **基准合计 M0～M4** | **140～250** | **1120～2000** | **14～25** | 选定范围覆盖，不承诺 27 语言完整对齐 |
+
+两人周数由阶段人日除以 10 得到，是容量参考，不是通过资源排程求出的最早完工时间。单人相同工作量约 28～50 个有效工作周，尚未加入技能差异和等待。
+
+## M0、M1 可分配工作包
+
+这是工作量拆解，不是已批准的实施计划。正式开工时按可独立测试/回退的边界细化单元工单，不机械地为每一行建父子层级。
+
+| 包 | 范围与需求 | 人日 | 依赖 | 验收样例 |
+|---|---|---:|---|---|
+| W00 | 基线、语言、词典、token 定位、SRS 样例、阅读交互风险验证 | 10～20 | D01～D07 的必要范围确认 | 样本文本可还原、点击定位正确；技术选择形成记录 |
+| W01 | 工程接入、身份与最小用户/全局管理 U01/A01/A02/A09 | 5～8 | W00 | 普通用户不能访问管理 API；账号与偏好流程可用 |
+| W02 | 书库/章节/文本导入/分章选项/队列 U02/U04/U08/U09 | 7～11 | W01 与数据契约 | 失败可见；相同任务重试不生成重复章节 |
+| W03 | 语言资源、分词集成、词典基础 A03/A04/U14 | 7～11 | W00/W01，和 W02 契约对齐 | 语言安装状态正确；离线查词可用；错模型明确报错 |
+| W04 | 阅读器、主查询、词语短语、完成阅读 U10～U13/U16 | 12～19 | W02/W03 | 划词与短语正确，跨章状态同步，重复完成不重复计数 |
+| W05 | 复习/基础词汇库/复习配置 U17/U19/A07 | 7～11 | W04 的词条契约 | 固定时钟下到期、重学、等级与重复作答符合样例 |
+| W06 | 难度统计、目标日历、基础主题、响应式 U03/U21/U24/U25 | 6～10 | W02/W04/W05 的事件契约 | 忽略/已知分开，事件统计一致，手机与键盘可操作 |
+| W07 | 首版集成、备份任务与恢复 A10/N01～N07 | 6～10 | W01～W06 | 两账号闭环通过；空实例恢复后数据和文件抽样一致 |
+| **W01～W07 合计** | **M1** | **50～80** | | |
+
+W02/W03 可在契约确定后分工；W04 依赖它们的真实集成结果；W05 不宜在词条身份和状态语义未定时先冻结实现。无法通过简单增加人数消除这条依赖链。
+
+## 后续阶段拆解
+
+| 阶段 | 工作包 | 人日 |
+|---|---|---:|
+| M2 | EPUB/网页/字幕文件导入与失败回退 | 9～15 |
+| M2 | 完整词汇 CSV、练习模式与过滤补齐 | 6～10 |
+| M2 | 查询形态、字体、TTS、主题、PWA 及本人数据维护 | 9～15 |
+| M2 | 词典格式、翻译服务配置与调用补齐 | 6～10 |
+| M3 | Anki、YouTube、Jellyfin 选定连接方式与降级 | 12～24 |
+| M3 | 中日读音/汉字专项与选定新增语言验收 | 12～24 |
+| M3 | 专项集成回归、样例与使用说明 | 6～12 |
+| M4 | 压测、长文/大词典优化 | 7～14 |
+| M4 | Worker 故障、升级/回退、完整恢复演练 | 7～14 |
+| M4 | 发布候选回归、交付文档和验收修正 | 6～12 |
+
+新增功能在各阶段包含自身基础测试；发布候选回归仅覆盖组合与环境差异。原中文分析 M4 同时提到“迁移需求”，但没有定义旧数据范围；本表将全量迁移单列为条件增量，不隐含承诺在 20～40 人日内完成。
+
+## 条件增量与重估点
+
+| 变化 | 处理方式 |
+|---|---|
+| 旧实例全量迁移成为必需 | 先用虚构/获授权样本盘点和 dry-run，再估用户、章节、文件、状态与索引迁移；不把 CSV 工期当全量迁移 |
+| 禁止 Python / 要求所有语言同等支持 | M0 增加逐语言可行性与质量验证，重新估 NLP 工作；当前区间不适用 |
+| 更换底座或数据库 | 在 W01 前解决兼容性；开工后切换需评估数据与接口返工 |
+| 公开服务、多租户或收费 | 另立需求并估算安全、配额、审计及运维，不并入自托管基准 |
+| 第三方字幕/翻译不稳定 | 按选定服务验证降级和成本，调整 M3 范围 |
+| 团队人数/熟练度/有效投入不同 | 用实际可用人日重算日历时间，不线性承诺效率 |
+
+如果需要预算预留，可对基准人日另加 20%：168～300 人日；该比例是管理假设，不是统计置信区间，也不包含新增范围。基准低/高值已经体现已知实现难度，不应再重复加入相同工作包。
+
+## 进度记录方式
+
+当前开发完成量为 0，文档准备不计作上述产品包已完成。本轮编写文档的实际工时未记录，不反推为已消耗人日。M0 后记录实际投入、遗漏项、语言/底座测试结果，再更新 M1～M4；每阶段结束按剩余范围重估。
@@ -1,33 +1,34 @@
-# LexGo 文档入口
+<!-- gitea-wiki-mirror:start -->
+generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
+wiki_page: Home
+wiki_url: https://git.ilapage.cn/OPC/lexgo/wiki/Home
+wiki_revision: e1245504efbb44ee3ab3835b3180fa6f6906b14a
+synchronized_at: 2026-09-10T06:27:39Z
+<!-- gitea-wiki-mirror:end -->

-状态：2026-09-10，本地文档准备完成后仍需发布至确认的 Gitea 仓库；本页不是 Wiki 镜像。
+# LexGo 文档入口

 ## 第一次阅读

-1. [项目档案](harness-drafts/00-project-profile.md)：目标、现状、治理、技术待决策项。
-2. [需求总览](harness-drafts/09-product-requirements-overview.md)：需求编号、阶段和验收入口。
-3. [工作量估算](harness-drafts/10-workload-estimate.md)：前提、人日拆解、依赖及重估条件。
-4. [架构与代码地图](harness-drafts/02-architecture-and-code-map.md)：现有文件与目标模块。
-5. [轻量工作流](harness-drafts/01-workflow.md)：如何开始和完成一个任务。
-6. [开发与验证](harness-drafts/04-local-development-and-verification.md)、[常见修改](harness-drafts/05-common-changes.md)、[排错](harness-drafts/06-troubleshooting.md)。
+1. [项目档案](https://git.ilapage.cn/OPC/lexgo/wiki/Project-Profile.-)：已确认使用轻量模式和 MySQL 8；其余技术候选与范围状态。
+2. [需求总览](https://git.ilapage.cn/OPC/lexgo/wiki/Product-Requirements-Overview.-)、[工作量估算](https://git.ilapage.cn/OPC/lexgo/wiki/Workload-Estimate.-)：首版闭环与后续范围。
+3. [架构与代码地图](https://git.ilapage.cn/OPC/lexgo/wiki/Architecture-and-Code-Map.-)、[业务规则](https://git.ilapage.cn/OPC/lexgo/wiki/Business-Rules-and-Glossary.-)。
+4. [开发工作流](https://git.ilapage.cn/OPC/lexgo/wiki/Development-Workflow.-)、[本地开发与验证](https://git.ilapage.cn/OPC/lexgo/wiki/Local-Development-and-Verification.-)。

 ## 五分钟开始

-先阅读项目档案的待决策项，再按工作量估算查看 M0 风险验证。当前没有产品启动命令。工具命令和预期见开发验证页。线上初始化步骤见[初始化记录](harness-drafts/07-new-project-documentation-setup.md)。
+项目目前只有需求与设计资料、治理工具，没有产品代码。先核对项目档案 D01～D07，再安排 M0 技术验证。数据库已确定 MySQL 8；不把候选技术建议当作已实现能力。
+
+命令从仓库根目录执行：`python dev_scripts/harness.py sync --verify` 同步线上页面并校验结构，预期退出码 0；`python -m unittest discover -s tests -v` 验证治理工具，预期全部通过。产品启动命令尚不存在。

 ## 简单修改从哪里开始

-本次新增文档尚为草稿，可在 `harness-drafts/` 直接修订。原有调研文件保留为证据材料；形成批准的方案后用需求总览关联，不默默覆写历史建议。正式 Wiki 初始化后，从线上主题页修改再单向同步。
+先看[常见修改](https://git.ilapage.cn/OPC/lexgo/wiki/Common-Changes.-)和[故障排查](https://git.ilapage.cn/OPC/lexgo/wiki/Troubleshooting)。轻量局部改动做最小验证；新功能和数据/权限变化建单。长期规则先改 Wiki，再导出镜像。

 ## 事实来源

-| 资料 | 使用方式 |
-|---|---|
-| [中文需求提取](01-LinguaCafe需求提取.md) | U01～U26、A01～A10、N01～N08 的索引来源；静态调研，不是产品验收 |
-| [中文 Go 分析](02-Go复刻与框架选型分析.md) | MySQL 路线和两人团队 14～25 周估算的来源；待确认建议 |
-| [另一份需求提取](linguacafe-requirements.md) | 保留对照，使用自己的编号；不要直接混用编号 |
-| [另一份 Go 分析](linguacafe-go-analysis.md) | PostgreSQL 路线及另一种阶段划分；待确认建议 |
-| [业务规则](harness-drafts/03-business-rules-and-glossary.md) | 提取待批准规则与验收约束 |
-| [交付文档指南](harness-drafts/delivery/README.md) | 按实际受众准备文档，不预建空白手册 |
+Wiki 保存长期规则，工单保存单次实施与验收，Git 保存源码和镜像。当前产品实现为零，已有调研不等于运行验收。数据库选择以用户确认的 MySQL 8 为准，历史 PostgreSQL 建议不再适用。

-当前事实是上述本地资料和文件检查。产品 Git commit、远端、运行和验收证据尚不存在或未确认；不使用 DevHarness 的 commit 代替产品 commit。
+原有四份调研资料作为证据页面保留：[需求提取](https://git.ilapage.cn/OPC/lexgo/wiki/LinguaCafe-Requirements.-)、[Go 分析](https://git.ilapage.cn/OPC/lexgo/wiki/Go-Architecture-Analysis.-)、[另一份需求提取](https://git.ilapage.cn/OPC/lexgo/wiki/LinguaCafe-Requirements-Alternative.-)、[另一份 Go 分析](https://git.ilapage.cn/OPC/lexgo/wiki/Go-Analysis-Alternative.-)。其正文为既有调研记录，不将整份建议视为已批准方案。
+
+[初始化记录与流程](https://git.ilapage.cn/OPC/lexgo/wiki/New-Project-Documentation-Setup.-)、[接入指南](https://git.ilapage.cn/OPC/lexgo/wiki/Existing-Project-Adoption-Guide.-)、[交付文档指南](https://git.ilapage.cn/OPC/lexgo/wiki/Delivery-Documentation-Guide.-)。不默认创建任务快照。
@@ -0,0 +1,30 @@
+<!-- gitea-wiki-mirror:start -->
+generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
+wiki_page: Delivery-Documentation-Guide
+wiki_url: https://git.ilapage.cn/OPC/lexgo/wiki/Delivery-Documentation-Guide.-
+wiki_revision: 2fded6b8141921cffd4a6f9b9c43ea9163b33a6b
+synchronized_at: 2026-09-10T06:27:46Z
+<!-- gitea-wiki-mirror:end -->
+
+# 交付文档指南
+
+
+## 什么时候需要交付文档
+
+按真实读者和可验证产品版本创建。当前负责人需要项目档案、需求范围和工作量估算；开发维护者需要业务边界、工作流与验证入口。尚无可运行产品，不预建空白用户/管理员手册。
+
+## 受众与文档选择
+
+学习者手册在 M1 形成可用闭环后编写，覆盖导入、阅读、保存和复习；部署维护指南在环境及常驻服务确认后编写，覆盖版本、配置、备份恢复和升级；管理员说明覆盖语言、词典、用户及备份授权。具体交付负责人、可见范围和验证人待确认。
+
+## 内部文档与交付文档边界
+
+交付文档仅包含读者所需操作与限制，不泄露凭据、内部配置或个人数据。测试示例明确使用虚构数据。研究建议不能当成对外功能承诺。
+
+## 编写和维护流程
+
+确认读者与版本 → 基于真实流程编写 → 执行操作验证 → 记录已知限制 → 人工验收。通用岗位模板仅供后续使用，不因模板存在认为手册已交付。
+
+## 最小验收清单
+
+入口可访问、步骤与版本一致、预期结果明确、错误可恢复、权限说明正确、敏感信息不外泄。无法执行的步骤明确标注，不能作为已验证交付内容。
@@ -0,0 +1,97 @@
+<!-- gitea-wiki-mirror:start -->
+generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
+wiki_page: Audience-Document-Template
+wiki_url: https://git.ilapage.cn/OPC/lexgo/wiki/Audience-Document-Template.-
+wiki_revision: 43b4bf97a5c289dca1abd39fef312311881440be
+synchronized_at: 2026-09-10T06:27:46Z
+<!-- gitea-wiki-mirror:end -->
+
+
+# 岗位文档模板
+
+> 使用说明：复制本模板创建具体岗位文档，删除说明性文字并填写真实内容。没有明确受众时不要创建文档；不得保留“待填写”后直接交付。
+
+## 文档信息
+
+| 字段 | 内容 |
+|---|---|
+| 文档名称 | |
+| 适用对象 | 最终用户 / 管理员 / 运维 / 客服 / 集成人员 / 验收人员 / 其他 |
+| 适用版本 | |
+| 最后验证日期 | YYYY-MM-DD |
+| 负责人 | |
+| 可见范围 | 内部 / 指定客户 / 公开 |
+| 相关产品或模块 | |
+
+## 目的与适用范围
+
+说明读者完成什么工作，以及本文包含和不包含什么。用岗位语言描述结果，不复制内部需求分析。
+
+## 前置条件
+
+- 所需权限：
+- 所需环境或设备：
+- 已完成的准备：
+- 需要提前获得的信息：
+
+不得在这里填写真实密码、令牌、个人数据或生产数据。
+
+## 操作步骤
+
+### 任务一：<明确的操作目标>
+
+1. <执行动作>
+2. <执行动作>
+3. <执行动作>
+
+**预期结果**：<读者可以观察到的成功结果>
+
+**失败时**：<先检查什么；何时停止并联系支持>
+
+每个独立任务重复以上结构。命令和界面名称应与适用版本一致；危险或不可逆操作必须在执行前给出醒目警告、影响和回退条件。
+
+## 常见错误与恢复
+
+| 现象或错误信息 | 可能原因 | 处理步骤 | 何时升级 |
+|---|---|---|---|
+| | | | |
+
+只记录经过确认的原因和恢复方法。不要让外部读者执行内部调试、绕过权限或可能扩大损失的操作。
+
+## 安全与权限
+
+- 本岗位允许执行的操作：
+- 明确禁止或需要审批的操作：
+- 敏感信息处理规则：
+- 数据、日志和截图脱敏要求：
+- 删除、发布、迁移或其他高风险操作的确认要求：
+
+## 已知限制
+
+- 支持的环境和版本：
+- 当前不支持的场景：
+- 兼容性限制：
+- 未验证的环境或步骤：
+
+## 支持与升级处理
+
+- 支持渠道：
+- 服务时间或响应约定：
+- 联系支持前需要收集的信息：
+- 不得提交的信息：
+- 需要升级到下一岗位或负责人的条件：
+
+## 版本记录
+
+| 日期 | 适用版本 | 变更内容 | 验证人 |
+|---|---|---|---|
+| | | | |
+
+## 交付前检查
+
+- [ ] 目标岗位能够理解术语和步骤。
+- [ ] 前置条件、步骤与预期结果一一对应。
+- [ ] 关键流程已按目标岗位视角验证。
+- [ ] 常见错误、恢复方法和升级条件清楚。
+- [ ] 没有内部工单、内部地址、敏感数据或无关源码细节。
+- [ ] 适用版本、最后验证日期、负责人和可见范围已填写。
@@ -1,6 +1,14 @@
+<!-- gitea-wiki-mirror:start -->
+generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
+wiki_page: Go-Analysis-Alternative
+wiki_url: https://git.ilapage.cn/OPC/lexgo/wiki/Go-Analysis-Alternative.-
+wiki_revision: c1d22173cf01d60b46dd130e860367b8146fdc80
+synchronized_at: 2026-09-10T06:27:51Z
+<!-- gitea-wiki-mirror:end -->
+
 # LinguaCafe 的 Go 复刻与框架选型分析

-日期：2026-09-10。本文是调研建议，尚未开始应用开发。需求与上游固定版本见 [需求提取](linguacafe-requirements.md)。默认目标是可自托管、可继续二次开发的 Web 应用；未假定要做付费 SaaS、原生手机应用或大型多租户平台。
+日期：2026-09-10。本文是调研建议，尚未开始应用开发。需求与上游固定版本见 [需求提取](https://git.ilapage.cn/OPC/lexgo/wiki/LinguaCafe-Requirements-Alternative.-)。默认目标是可自托管、可继续二次开发的 Web 应用；未假定要做付费 SaaS、原生手机应用或大型多租户平台。

 ## 1. 结论

@@ -1,3 +1,11 @@
+<!-- gitea-wiki-mirror:start -->
+generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
+wiki_page: LinguaCafe-Requirements-Alternative
+wiki_url: https://git.ilapage.cn/OPC/lexgo/wiki/LinguaCafe-Requirements-Alternative.-
+wiki_revision: 55fdebd66e3c1ece8c7dae81ca8639f5a8be5388
+synchronized_at: 2026-09-10T06:27:50Z
+<!-- gitea-wiki-mirror:end -->
+
 # LinguaCafe 需求提取

 调研日期：2026-09-10。目标项目：LexGo（Go 复刻方案）。本文提取上游需求，不代表已实现或已完成运行验收。
@@ -136,4 +144,4 @@ P2：YouTube、Jellyfin、Anki 的完整接入、汉字部首等专门功能，

 用户删除、配额、公共书库、多租户、计费、AI 讲解、云端 TTS、离线同步、FSRS 均应明确列为扩展；P0 完成不能称为完整复刻。

-对应技术分析见 [Go 复刻与框架选型](linguacafe-go-analysis.md)。
+对应技术分析见 [Go 复刻与框架选型](https://git.ilapage.cn/OPC/lexgo/wiki/Go-Analysis-Alternative.-)。
@@ -0,0 +1,283 @@
+<!-- gitea-wiki-mirror:start -->
+generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
+wiki_page: Deployment-Template
+wiki_url: https://git.ilapage.cn/OPC/lexgo/wiki/Deployment-Template.-
+wiki_revision: 552a2e7ba27fd76461ee9d8e4c3bb79fa32e0737
+synchronized_at: 2026-09-10T06:27:47Z
+<!-- gitea-wiki-mirror:end -->
+
+
+# 部署文档模板
+
+> 使用说明：本页是 DevHarness 模板，不描述任何真实服务。有常驻服务的项目复制本页，在自己的 Gitea Wiki 创建 `Deployment-and-Operations` 页面，并在本项目 `wiki-docs.json` 增加映射（建议镜像到 `docs/10-deployment-and-operations.md`）。填写时删除全部说明性文字，不得保留“待填写”后直接交付。没有常驻服务的项目不要创建部署页，在初始化工单记录原因即可。
+>
+> 本模板面向项目内部维护者。面向客户或外部运维岗位的部署说明属于交付文档，使用[岗位文档模板](https://git.ilapage.cn/OPC/lexgo/wiki/Audience-Document-Template.-)。
+>
+> 标准栈为 nginx 反向代理 + supervisor 进程托管，示例按 Python 服务（gunicorn / uvicorn）编写。实际技术栈不同时替换命令，但保留章节结构和“每条命令写明预期结果”的要求。
+
+## 本页用途
+
+让维护者能够在一台干净的服务器上完成首次部署、日常运维、健康检查和回滚。所有命令默认以具备 sudo 权限的账号在服务器上执行，示例以 Linux 为主。
+
+## 安全边界
+
+- 本页只写配置项的**名称和来源**，不写任何真实密码、令牌、私钥、证书内容、生产数据库地址或个人数据。
+- 需要凭据的步骤写明“从哪里取”，例如运维密码库条目名或环境变量名。
+- 涉及删除数据、数据库迁移和不可逆操作的步骤必须给出醒目警告、影响范围和回退条件。
+
+## 服务概览
+
+| 项目 | 内容 |
+|---|---|
+| 服务名（supervisor program） | `<myapp>` |
+| 代码部署目录 | `/srv/<myapp>` |
+| 运行账号 | `<myapp>` |
+| 运行时 | Python `<3.x>` |
+| 应用服务器 | gunicorn / uvicorn |
+| 本地监听地址 | `127.0.0.1:<8000>` |
+| 进程数 | `<n>` |
+| 对外域名与路径 | `https://<example.com>/` |
+| 依赖的外部服务 | 数据库 / 缓存 / 对象存储 / 无 |
+| 日志目录 | `/var/log/<myapp>/` |
+
+服务只监听 `127.0.0.1`，不直接对外暴露端口；所有外部访问经 nginx 转发。
+
+## 环境要求
+
+| 组件 | 版本要求 | 检查命令 | 预期结果 |
+|---|---|---|---|
+| 操作系统 | `<Ubuntu 22.04>` | `cat /etc/os-release` | 输出与要求一致 |
+| Python | `<3.11+>` | `python3 --version` | 输出版本号且不低于要求 |
+| nginx | `<1.18+>` | `nginx -v` | 输出版本号 |
+| supervisor | `<4.2+>` | `supervisord --version` | 输出版本号 |
+
+未安装时：
+
+```bash
+sudo apt update
+sudo apt install -y nginx supervisor python3-venv
+```
+
+**预期结果**：`systemctl status nginx` 与 `systemctl status supervisor` 均为 `active (running)`。
+
+## 首次部署
+
+### 1. 创建运行账号与目录
+
+```bash
+sudo useradd --system --home /srv/<myapp> --shell /usr/sbin/nologin <myapp>
+sudo mkdir -p /srv/<myapp> /var/log/<myapp>
+sudo chown -R <myapp>:<myapp> /srv/<myapp> /var/log/<myapp>
+```
+
+**预期结果**：`id <myapp>` 输出该账号；两个目录存在且属主为 `<myapp>`。
+
+服务账号使用 `nologin`，不允许直接登录。
+
+### 2. 取得代码
+
+```bash
+sudo -u <myapp> git clone <仓库地址> /srv/<myapp>/app
+cd /srv/<myapp>/app && sudo -u <myapp> git rev-parse HEAD
+```
+
+**预期结果**：输出本次部署的完整提交哈希，记录到部署记录中。
+
+### 3. 安装依赖
+
+```bash
+sudo -u <myapp> python3 -m venv /srv/<myapp>/venv
+sudo -u <myapp> /srv/<myapp>/venv/bin/pip install -r /srv/<myapp>/app/requirements.txt
+```
+
+**预期结果**：pip 以 `Successfully installed ...` 结束，无 ERROR。
+
+### 4. 落位配置文件
+
+```bash
+sudo install -o <myapp> -g <myapp> -m 600 /dev/null /srv/<myapp>/app.env
+sudo -u <myapp> vi /srv/<myapp>/app.env
+```
+
+**预期结果**：`ls -l /srv/<myapp>/app.env` 显示权限 `-rw-------` 且属主为 `<myapp>`。
+
+配置项清单见下方“配置与凭据来源”。配置文件不进入 Git。
+
+### 5. 数据库初始化或迁移
+
+<!-- 无数据库时删除本节。 -->
+
+> **注意**：迁移可能不可逆。执行前必须先备份，并确认回退方式。
+
+```bash
+sudo -u <myapp> /srv/<myapp>/venv/bin/python -m <myapp>.manage migrate
+```
+
+**预期结果**：输出全部迁移已应用，无失败项。
+
+## supervisor 配置
+
+写入 `/etc/supervisor/conf.d/<myapp>.conf`：
+
+```ini
+[program:<myapp>]
+command=/srv/<myapp>/venv/bin/gunicorn <myapp>.wsgi:application --workers <n> --bind 127.0.0.1:<8000> --timeout 60
+directory=/srv/<myapp>/app
+user=<myapp>
+environment=PATH="/srv/<myapp>/venv/bin",APP_ENV_FILE="/srv/<myapp>/app.env"
+autostart=true
+autorestart=true
+startsecs=5
+stopasgroup=true
+killasgroup=true
+stopwaitsecs=30
+stdout_logfile=/var/log/<myapp>/stdout.log
+stderr_logfile=/var/log/<myapp>/stderr.log
+stdout_logfile_maxbytes=50MB
+stdout_logfile_backups=5
+```
+
+> 异步框架使用 uvicorn 时把 `command` 换成：
+> `/srv/<myapp>/venv/bin/uvicorn <myapp>.asgi:app --host 127.0.0.1 --port <8000> --workers <n>`
+
+不要在 `environment` 里写明文密码或令牌；敏感值放在 `app.env`，由应用读取。
+
+加载配置并启动：
+
+```bash
+sudo supervisorctl reread
+sudo supervisorctl update
+sudo supervisorctl start <myapp>
+sudo supervisorctl status <myapp>
+```
+
+**预期结果**：`reread` 输出 `<myapp>: available`；`status` 显示 `RUNNING` 且 uptime 持续增长。出现 `BACKOFF` 或 `FATAL` 时查看 `stderr.log`。
+
+## nginx 配置
+
+写入 `/etc/nginx/sites-available/<myapp>.conf` 并软链到 `sites-enabled`：
+
+```nginx
+server {
+    listen 80;
+    server_name <example.com>;
+
+    access_log /var/log/nginx/<myapp>.access.log;
+    error_log  /var/log/nginx/<myapp>.error.log;
+
+    client_max_body_size <20m>;
+
+    location /static/ {
+        alias /srv/<myapp>/app/static/;
+        expires 7d;
+    }
+
+    location / {
+        proxy_pass http://127.0.0.1:<8000>;
+        proxy_http_version 1.1;
+        proxy_set_header Host              $host;
+        proxy_set_header X-Real-IP         $remote_addr;
+        proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_connect_timeout 5s;
+        proxy_read_timeout    <60s>;
+    }
+}
+```
+
+<!-- WebSocket 需求存在时，在对应 location 增加 Upgrade 与 Connection 头；无此需求时删除本注释。 -->
+
+启用并生效：
+
+```bash
+sudo ln -sf /etc/nginx/sites-available/<myapp>.conf /etc/nginx/sites-enabled/<myapp>.conf
+sudo nginx -t
+sudo systemctl reload nginx
+```
+
+**预期结果**：`nginx -t` 输出 `syntax is ok` 与 `test is successful`；reload 无输出且 `systemctl status nginx` 仍为 `active (running)`。
+
+`nginx -t` 未通过时不要 reload，先修正配置。
+
+<!-- 需要 HTTPS 时在此记录证书来源、签发方式和续期检查命令；证书内容和私钥不得写入本页。 -->
+
+## 配置与凭据来源
+
+| 配置项 | 用途 | 来源 | 是否敏感 |
+|---|---|---|---|
+| `APP_ENV_FILE` | 指向配置文件路径 | supervisor 配置 | 否 |
+| `<DATABASE_URL>` | 数据库连接 | `/srv/<myapp>/app.env`，值取自运维密码库条目 `<条目名>` | 是 |
+| `<SECRET_KEY>` | 会话与签名 | 同上 | 是 |
+| `<LOG_LEVEL>` | 日志级别 | `/srv/<myapp>/app.env` | 否 |
+
+敏感值只记录取用位置，不在本页、工单、日志和提交中出现真实内容。
+
+## 日常运维
+
+| 操作 | 命令 | 预期结果 |
+|---|---|---|
+| 查看状态 | `sudo supervisorctl status <myapp>` | `RUNNING`，uptime 持续增长 |
+| 重启服务 | `sudo supervisorctl restart <myapp>` | 输出 `stopped` 后 `started` |
+| 停止服务 | `sudo supervisorctl stop <myapp>` | 输出 `stopped` |
+| 实时日志 | `sudo supervisorctl tail -f <myapp> stderr` | 持续输出应用日志 |
+| 应用日志 | `sudo tail -n 200 /var/log/<myapp>/stderr.log` | 输出最近日志 |
+| 接入层日志 | `sudo tail -n 200 /var/log/nginx/<myapp>.error.log` | 输出 nginx 错误 |
+| 重载 nginx | `sudo nginx -t && sudo systemctl reload nginx` | 测试通过后无中断生效 |
+
+修改 supervisor 配置后必须 `reread` + `update`，只 `restart` 不会加载新配置。
+
+## 健康检查
+
+每次部署、重启和回滚后必须全部执行：
+
+```bash
+sudo supervisorctl status <myapp>
+curl -sS -o /dev/null -w "%{http_code}\n" http://127.0.0.1:<8000><健康检查路径>
+curl -sS -o /dev/null -w "%{http_code}\n" https://<example.com><健康检查路径>
+sudo tail -n 50 /var/log/<myapp>/stderr.log
+```
+
+**预期结果**：状态为 `RUNNING`；两个 `curl` 均返回 `200`；日志无新增异常堆栈。
+
+任何一项不符合时不视为部署成功，按“升级与回滚”处理。
+
+## 升级与回滚
+
+### 升级
+
+```bash
+cd /srv/<myapp>/app
+sudo -u <myapp> git rev-parse HEAD          # 记录当前提交，回滚需要
+sudo -u <myapp> git fetch --all
+sudo -u <myapp> git checkout <目标提交或标签>
+sudo -u <myapp> /srv/<myapp>/venv/bin/pip install -r requirements.txt
+sudo -u <myapp> /srv/<myapp>/venv/bin/python -m <myapp>.manage migrate   # 无数据库时删除
+sudo supervisorctl restart <myapp>
+```
+
+**预期结果**：restart 后 `status` 为 `RUNNING`，随后健康检查全部通过。
+
+升级前必须记录当前提交哈希；涉及数据库迁移时必须先备份。
+
+### 回滚
+
+```bash
+cd /srv/<myapp>/app
+sudo -u <myapp> git checkout <升级前记录的提交>
+sudo -u <myapp> /srv/<myapp>/venv/bin/pip install -r requirements.txt
+sudo supervisorctl restart <myapp>
+```
+
+**预期结果**：健康检查全部通过。
+
+> **注意**：已执行的数据库迁移通常不能通过切回代码撤销。存在迁移时必须先确认迁移是否向后兼容；不兼容时按备份恢复流程处理，并停止自行操作、联系负责人。
+
+### 备份与恢复
+
+<!-- 记录备份对象、频率、保存位置、保留期和恢复步骤；无持久化数据时说明原因。 -->
+
+## 已知限制
+
+<!-- 记录本环境无法验证的部分，例如未做过真实回滚演练、未验证高并发表现、灰度或多机部署尚未支持。不得留空，无限制时写“无”。 -->
+
+- <!-- 填写 -->
@@ -0,0 +1,51 @@
+<!-- gitea-wiki-mirror:start -->
+generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
+wiki_page: Task-Archive-Template
+wiki_url: https://git.ilapage.cn/OPC/lexgo/wiki/Task-Archive-Template.-
+wiki_revision: f87960fa6b715ea5cd58d074378cb3b0d8ec8559
+synchronized_at: 2026-09-10T06:27:48Z
+<!-- gitea-wiki-mirror:end -->
+
+
+# <工单号> <标题>
+
+- 类型：需求 / 缺陷 / 重构
+- 所属 Epic：#
+- 所属 MVP / 版本：#
+- 状态：待验收 / 已完成
+- 日期：YYYY-MM-DD
+- Gitea 工单：<链接>
+- Wiki 页面：<页面名>
+- Wiki revision：见本地镜像头
+
+## 背景与目标
+
+<!-- 原来有什么问题，这次达到什么结果。 -->
+
+## 最终方案
+
+<!-- 说明实际实现。与建单方案不同之处必须写清原因。 -->
+
+## 修改文件
+
+- `<文件>`：<改动说明>
+
+## 验收结果
+
+| 验收标准 | 结果 |
+|---|---|
+|  | 通过 / 未通过 |
+
+## 测试
+
+- 执行命令：`<命令>`
+- 结果：
+- **未验证部分**：<!-- 必填；没有就写“无”。 -->
+
+## 遗留问题
+
+<!-- 没有就删除本节。 -->
+
+## 相关提交
+
+- `<提交哈希>` <提交说明>