From 3c161363e1c1eafec2f804ee428eb11b84cf7aa5 Mon Sep 17 00:00:00 2001 From: QiuSW Date: Thu, 10 Sep 2026 14:27:28 +0800 Subject: [PATCH] docs: configure LexGo light governance and preserve research sources --- .gitignore | 20 +- AGENTS.md | 11 + README.md | 73 +--- docs/00-project-profile.md | 127 ------- docs/01-LinguaCafe需求提取.md | 185 ++++++++++ docs/01-workflow.md | 346 ------------------ docs/02-Go复刻与框架选型分析.md | 265 ++++++++++++++ docs/02-architecture-and-code-map.md | 89 ----- docs/03-business-rules-and-glossary.md | 72 ---- docs/04-local-development-and-verification.md | 174 --------- docs/05-common-changes.md | 78 ---- docs/06-troubleshooting.md | 40 -- docs/07-new-project-documentation-setup.md | 238 ------------ docs/08-existing-project-adoption.md | 235 ------------ docs/09-product-requirements-overview.md | 128 ------- docs/README.md | 101 +---- docs/delivery/README.md | 80 ---- docs/delivery/audience-document-template.md | 96 ----- docs/linguacafe-go-analysis.md | 215 +++++++++++ docs/linguacafe-requirements.md | 139 +++++++ docs/task/.gitkeep | 1 - docs/task/1-Wiki-文档主源.md | 82 ----- docs/task/10-需求记录与流转规则.md | 88 ----- ...交付文档指南与岗位文档模板.md | 80 ---- .../12-已有项目接入DevHarness指南.md | 87 ----- .../13-多子项目与独立交付单元.md | 68 ---- docs/task/2-初级维护者文档体系.md | 81 ---- docs/task/3-dev_scripts目录重命名.md | 72 ---- docs/task/4-Agent效率与范围控制.md | 70 ---- docs/task/5-精简AGENTS重复说明.md | 70 ---- docs/task/6-优化ClaudeCode规则入口.md | 78 ---- docs/task/7-ClaudeCode模型路由.md | 81 ---- docs/task/8-最小工单依赖规则.md | 85 ----- docs/task/9-Agent自然语言快捷指令.md | 94 ----- docs/templates/deployment.md | 282 -------------- docs/templates/task-archive.md | 50 --- wiki-docs.json | 22 +- 37 files changed, 875 insertions(+), 3228 deletions(-) delete mode 100644 docs/00-project-profile.md create mode 100644 docs/01-LinguaCafe需求提取.md delete mode 100644 docs/01-workflow.md create mode 100644 docs/02-Go复刻与框架选型分析.md delete mode 100644 docs/02-architecture-and-code-map.md delete mode 100644 docs/03-business-rules-and-glossary.md delete mode 100644 docs/04-local-development-and-verification.md delete mode 100644 docs/05-common-changes.md delete mode 100644 docs/06-troubleshooting.md delete mode 100644 docs/07-new-project-documentation-setup.md delete mode 100644 docs/08-existing-project-adoption.md delete mode 100644 docs/09-product-requirements-overview.md delete mode 100644 docs/delivery/README.md delete mode 100644 docs/delivery/audience-document-template.md create mode 100644 docs/linguacafe-go-analysis.md create mode 100644 docs/linguacafe-requirements.md delete mode 100644 docs/task/.gitkeep delete mode 100644 docs/task/1-Wiki-文档主源.md delete mode 100644 docs/task/10-需求记录与流转规则.md delete mode 100644 docs/task/11-交付文档指南与岗位文档模板.md delete mode 100644 docs/task/12-已有项目接入DevHarness指南.md delete mode 100644 docs/task/13-多子项目与独立交付单元.md delete mode 100644 docs/task/2-初级维护者文档体系.md delete mode 100644 docs/task/3-dev_scripts目录重命名.md delete mode 100644 docs/task/4-Agent效率与范围控制.md delete mode 100644 docs/task/5-精简AGENTS重复说明.md delete mode 100644 docs/task/6-优化ClaudeCode规则入口.md delete mode 100644 docs/task/7-ClaudeCode模型路由.md delete mode 100644 docs/task/8-最小工单依赖规则.md delete mode 100644 docs/task/9-Agent自然语言快捷指令.md delete mode 100644 docs/templates/deployment.md delete mode 100644 docs/templates/task-archive.md diff --git a/.gitignore b/.gitignore index e563dcb..9739b41 100644 --- a/.gitignore +++ b/.gitignore @@ -1,21 +1,9 @@ -# 本地环境与凭据 +__pycache__/ +*.py[cod] .env .env.* !.env.example gitea.env -*.local - -# 编辑器与系统文件 -.idea/ -.vscode/ -.DS_Store -Thumbs.db - -# 常见构建、测试缓存 -__pycache__/ -.pytest_cache/ -.coverage -coverage/ -dist/ -build/ node_modules/ +.venv/ +dist/ diff --git a/AGENTS.md b/AGENTS.md index 13bfc7b..46f15db 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -252,3 +252,14 @@ MVP 内所有单元任务通过后才能做 MVP 集成验收；MVP 通过后才 - 同步配置只允许写入 `docs/` 下的 Markdown；发现镜像有未提交修改时必须停止。 - Gitea 凭据只通过进程环境或 MCP 安全配置提供，不得写入仓库。 - `dev_scripts/` 只存放 DevHarness 自身工具；业务项目的通用脚本必须使用独立目录，不得混放。 + + +## LexGo 已确认项目决策 + +- 治理模式：轻量。数据库：MySQL 8（用户于 2026-09-10 确认）；具体小版本在工程验证后锁定。 +- 远端：https://git.ilapage.cn/OPC/lexgo.git；分支 main。不得把邻接 dev_harness 工作区当成本项目工作区。 +- 当前为需求和设计阶段，没有产品代码。Go/Gin、Vue、管理底座、Python NLP 与首发语言是待验证建议，不能冒充批准的产品实现。 +- 原四份研究保留为历史参考；PostgreSQL 建议被 MySQL 8 决策覆盖，U/A/N 索引用于追踪而不是批准所有范围。 +- 用户/语言数据所有权、Unicode 原文位置、任务和复习幂等、完整备份恢复是后续方案的必要验收边界。 +- 当前 MCP 连接其他 Gitea 站点，需使用目标站点 API 时记录原因；凭据仅从安全配置进入进程。 +- DevHarness 基线 ecab8995026e57f2c28f307a6aa32b871cb3163f；工具保持原样，不为跳过门禁修改检查。 diff --git a/README.md b/README.md index 9faa394..4db2275 100644 --- a/README.md +++ b/README.md @@ -1,62 +1,23 @@ -# DevHarness +# LexGo -DevHarness 是一个以 Gitea 工单管理任务过程、以 Gitea Wiki 管理长期文档、以 Git 提交记录代码变更、由人负责确认和验收的 AI 辅助开发模板。 +面向自托管场景的阅读式语言学习项目，规划提供内容导入、阅读查词、词汇与短语、复习和实例管理。 -它约束的是开发过程，不限制项目使用 Python、Go、JavaScript 或其他技术栈。 +已确认：**DevHarness 轻量模式、MySQL 8**。当前是需求和设计阶段，没有产品代码；Go/Gin、Vue、管理底座、Python NLP 和首发语言仍属于待验证方案。 -## 需要工单的任务闭环 +- [文档入口](docs/README.md) · [线上 Wiki](https://git.ilapage.cn/OPC/lexgo/wiki/Home) +- [项目档案](docs/00-project-profile.md) · [需求总览](docs/09-product-requirements-overview.md) +- [工作量估算](docs/10-workload-estimate.md)：两人团队假设下首版 60～100 人日，基准范围 140～250 人日，详见前提与排除项。 +- [工作流](docs/01-workflow.md) · [开发与验证](docs/04-local-development-and-verification.md) -```text -讨论需求或缺陷 - -> 阅读代码并提出方案 - -> 人工确认方案 - -> 创建 Epic / MVP / 单元任务工单 - -> Agent 实现并测试 - -> 提交代码并更新工单 - -> 工单集中回写最终证据并等待人工验收 - -> 人工验收后在工单记录结论 - -> 关闭工单并更新父工单；长期事实变化时才同步 Wiki +## 文档与治理 + +远端为 `https://git.ilapage.cn/OPC/lexgo.git`，默认分支 main。需要工单的任务以 Gitea 工单为单次任务事实来源；轻量直接实施项通过 Git 提交和结果报告留痕。长期规则以 Wiki 为主源，docs 为单向镜像；默认不创建任务归档。 + +新项目接入顺序：创建 Gitea 远端仓库并推送当前引导提交，启用工单和 Wiki；优先使用已配置的 Gitea MCP。`Home` 不存在时先创建并回读 `Home`，再逐页发布并读取 revision，最后运行下列验证。本地 `docs/` 的存在不能证明线上 Wiki 已初始化。 + +```powershell +python dev_scripts/harness.py sync --verify +python -m unittest discover -s tests -v ``` -轻量模式下符合直接实施条件的小 Bug、局部 UI 和单模块低风险调整不走上述工单闭环：确认目标 → 最小修改 → 受影响范围测试 → 提交并报告结果。 - -## 快速开始 - -1. 复制或克隆本仓库，并修改仓库名称。 -2. 创建 Gitea 远端仓库并推送当前引导提交，启用工单和 Wiki。 -3. 配置 `wiki-docs.json` 和安全访问方式；优先使用已配置的 Gitea MCP，MCP 不可用时才使用 Gitea API 并记录原因。令牌只通过环境变量或 MCP 安全配置提供。 -4. 按 [新项目文档初始化](docs/07-new-project-documentation-setup.md) 查询线上 Wiki；`Home` 不存在时先创建并回读 `Home`，取得 revision 后再创建其他核心页面。 -5. 在项目档案选择治理模式；内部、单人、低风险项目优先选择轻量，并把不可违反的安全规则写入根目录或子项目的 `AGENTS.md`。 -6. 需要工单时使用 `.gitea/issue_template/` 中的模板；小型项目不要求预先创建 Epic 或 MVP。本地 `docs/` 的存在不能证明线上 Wiki 已初始化。 -7. 开始产品代码前运行： - - ```powershell - python dev_scripts/harness.py sync --verify - ``` - -新仓库在 Gitea 尚未建立前允许一次不关联工单的引导提交。远端和工单系统配置完成后，按项目治理模式和任务真实风险判断是否需要工单；完整独立需求和中高风险变化必须建单。 - -## 目录 - -```text -AGENTS.md Agent 的通用工作规则 -CLAUDE.md Claude Code 的规则入口 -.gitea/issue_template/ Epic、MVP、单元任务工单模板 -docs/00-project-profile.md Wiki 项目档案的只读镜像 -docs/01-workflow.md Wiki 开发工作流的只读镜像 -docs/02-07*.md 代码地图、业务、验证、修改、排错和初始化镜像 -docs/templates/task-archive.md 可选 Wiki 任务快照模板的只读镜像 -docs/task/ 人工明确要求的专项或历史兼容快照 -wiki-docs.json 核心 Wiki 页面到本地镜像的显式映射 -dev_scripts/harness.py check / sync / archive / export 单一入口 -dev_scripts/wiki_docs.py Gitea Wiki 客户端与镜像生成库 -``` - -## 设计原则 - -- 人决定目标、范围和验收结果，Agent 负责检查、实现和验证。 -- 需要工单的任务以 Gitea 工单为单次任务事实来源；轻量直接实施项以 Git 提交和结果报告留痕。Wiki 保存长期有效事实，`docs/` 默认保存核心镜像。 -- 默认不创建任务归档；`archive`、`export` 和 `export --all` 只作为人工显式触发的兼容能力。 -- 一个单元工单只解决一个可独立测试和回退的问题。 -- 实现提交与必要的核心文档镜像提交分开，便于审查与追溯。 -- 凭据、真实个人数据和生产数据不得进入代码、工单或归档；明确虚构的测试数据无需形式化脱敏。 +预期同步/严格检查成功且治理测试全部通过。产品尚无启动命令，治理测试不代表产品已实现。当前 MCP 指向另一 Gitea 站点，本轮回退目标站点 API，原因与证据边界见[初始化记录](docs/07-new-project-documentation-setup.md)。凭据只使用安全配置或环境变量，不写入仓库。 diff --git a/docs/00-project-profile.md b/docs/00-project-profile.md deleted file mode 100644 index ff3c0ad..0000000 --- a/docs/00-project-profile.md +++ /dev/null @@ -1,127 +0,0 @@ - -generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) -wiki_page: Project-Profile -wiki_url: https://git.ilapage.cn/OPC/dev_harness/wiki/Project-Profile.- -wiki_revision: c509e5d74e0d0cb7be35698b809ecc73be3cb50c -synchronized_at: 2026-09-04T06:14:02Z - - -# 项目档案 - -本页记录不经常变化、所有维护者都需要知道的信息。它是项目档案的事实来源；仓库内 `docs/00-project-profile.md` 是只读镜像。 - -## 基本信息 - -| 项目 | 内容 | -|---|---| -| 项目名称 | DevHarness | -| 一句话目标 | 提供以 Gitea 工单、Wiki 和 Git 为事实来源的 AI 辅助开发工作流模板 | -| 主要使用者 | 项目负责人、Claude/Codex Agent、接手简单维护的初级程序员 | -| Gitea 地址 | https://git.ilapage.cn | -| 仓库 | `OPC/dev_harness` | -| 默认分支 | `main` | -| 主要维护者 | `ila` | -| 文档适用范围 | 默认分支当前版本；具体镜像 revision 见每个本地文件头 | - -## 项目治理模式 - -| 项目 | 当前值 | -|---|---| -| 当前治理模式 | 标准；DevHarness 模板自身的流程变更需要工单和验收 | -| 新项目默认 | 使用 DevHarness 创建的新项目默认采用轻量模式；只有负责人明确选择并记录理由时才改为标准或高风险 | -| 选择理由 | 模板维护会影响多个项目；使用模板的新项目应按自身风险裁剪 | -| 升级规则 | 单个任务的真实风险高于项目默认模式时，仅该任务升级到更高模式 | - -DevHarness 上游模板自身继续采用标准模式。复制模板创建其他项目后，继承的“DevHarness / 标准”文字不代表目标项目已经选择标准模式；目标项目未明确填写治理模式时按轻量模式执行并提示补写，不因此阻塞产品开发。只有负责人明确选择标准或高风险并记录理由时才改变项目默认模式。治理模式只裁剪工单、原型、测试和文档流程，不得取消凭据、授权边界和真实测试证据。 - -## DevHarness 来源与基线 - -每个采用 DevHarness 的业务项目都必须填写本节。它记录的是所采用的 DevHarness 上游版本，不是业务项目自己的提交。不得使用“最新版本”“当前 main”等动态描述代替完整提交哈希。 - -| 项目 | 内容 | -|---|---| -| DevHarness 来源仓库 | `https://git.ilapage.cn/OPC/dev_harness` | -| 当前基线提交 | 本仓库是 DevHarness 上游源模板，不适用；复制到业务项目后必须替换为实际采用的完整提交哈希 | -| 最后接入或升级日期 | 2026-08-16 | -| 项目适配说明 | 本仓库维护源模板；业务项目填写保留、改写或未采用的 Harness 规则与工具 | - -首次接入和后续升级都必须在目标项目工单中记录旧基线、新基线和差异分类。升级验收通过后，目标项目应把“当前基线提交”和日期更新为已采用的上游提交；未完成或已回退的升级不得更新基线。 - -## 子项目与交付单元 - -“子项目”是仓库中具有明确职责和规则边界的应用或模块；“交付单元”是能够独立构建、测试、版本化或发布的程序、服务、库或文档包。一个子项目可以对应一个交付单元，也可以包含多个交付单元。 - -| 子项目 / 交付单元 | 职责 | 技术栈 | 构建与测试 | 版本与发布方式 | 规则入口 | 共享边界 | -|---|---|---|---|---|---|---| -| DevHarness 模板 | 提供 Agent 开发流程、Wiki 镜像和结构检查 | Markdown、Python 3 标准库、Gitea 1.25 | `python dev_scripts/harness.py check --strict`；`python -m unittest discover -s tests -v` | 跟随仓库 `main` 分支，不单独发布产品程序 | 根目录 `AGENTS.md` | Gitea 工单、Wiki、Git 和 `docs/` 的事实来源边界 | - -单应用项目只填写一行。多应用单仓库必须逐个填写，并为技术栈、构建测试或安全规则不同的目录增加子目录 `AGENTS.md`。技术栈不同不等于必须拆分 Git 仓库；是否拆仓应根据团队、权限、发布周期、仓库效率、复用关系和共享接口稳定性判断。 - -跨子项目接口或契约必须指定唯一事实来源，并说明各交付单元的兼容范围和验证命令。不得在多个页面维护互不确认的“权威版本”。 - -## 技术栈与运行环境 - -| 部分 | 技术 | 规则文件 | -|---|---|---| -| Harness 规则和模板 | Markdown、Gitea 1.25 | `AGENTS.md` | -| Wiki 镜像与结构检查 | Python 3 标准库 | `AGENTS.md` | -| 主要开发环境 | Windows 10、PowerShell 7 `pwsh`（当前验证 7.3.12）、Git | `AGENTS.md` | - -本项目不需要安装第三方 Python 包。复制到业务项目后，必须把真实语言、框架、版本和支持平台写入本节。 - -## 阅读入口 - -- 新人入口：Home。 -- 产品需求入口：[产品需求总览](Product-Requirements-Overview.-)。 -- 代码入口：[架构与代码地图](Architecture-and-Code-Map.-)。 -- 业务边界：[业务规则与术语](Business-Rules-and-Glossary.-)。 -- 运行验证：[本地开发与验证](Local-Development-and-Verification.-)。 -- 简单维护：[常见修改指南](Common-Changes.-)。 -- 错误定位：[故障排查](Troubleshooting)。 - -## 常用命令 - -所有命令默认从仓库根目录执行。 - -| 用途 | 命令 | 预期结果 | -|---|---|---| -| 查看工作区 | `git status --short --branch` | 显示分支且没有无关修改 | -| 检查模板结构 | `python dev_scripts/harness.py check --strict` | 输出“DevHarness 检查通过” | -| 运行单元测试 | `python -m unittest discover -s tests -v` | 所有测试通过 | -| 导出核心 Wiki 镜像 | `python dev_scripts/harness.py sync` | 核心页面写入 `docs/`，不处理任务归档 | -| 检查核心 Wiki 镜像 | `python dev_scripts/harness.py sync --check` | 输出核心镜像与 Wiki 一致 | -| 创建可选任务快照 | `python dev_scripts/harness.py archive 123 "修复登录超时"` | 仅在人工或项目规则明确要求时创建 Wiki 快照 | -| 增量导出任务归档 | `python dev_scripts/harness.py export` | 只导出新增或 revision 已变化的任务归档 | -| 全量导出任务归档 | `python dev_scripts/harness.py export --all` | 读取并导出全部线上任务归档 | - -## 目录边界 - -| 目录 | 职责 | 不应放入 | -|---|---|---| -| `.gitea/issue_template/` | Gitea 工单模板 | 凭据、单次任务证据 | -| `docs/` | Wiki 自动导出的只读镜像 | 人工直接维护的长期文档 | -| `docs/task/` | 人工明确要求后导出的专项或历史兼容快照，可能不是完整历史 | 默认任务记录、讨论过程和临时方案 | -| `dev_scripts/` | Harness 检查、Wiki 同步和归档工具 | 产品功能代码 | -| `tests/` | Harness 工具自动化测试 | 生产数据 | - -## 环境、配置与凭据 - -- 核心 Wiki 同步配置：仓库根目录 `wiki-docs.json`；可选任务快照不逐页登记，仅在显式归档或导出时动态发现。 -- Gitea 地址可由配置提供，也可通过 `GITEA_URL` 覆盖。 -- Gitea PAT 仅通过 `GITEA_TOKEN` 或 MCP 安全配置提供，不写入仓库。 -- Token 至少需要读取仓库权限；创建或更新 Wiki 时还需要写仓库权限。 -- 配置示例：`wiki-docs.json` 只保存非敏感仓库信息。 -- 日志：本项目不持久化运行日志，命令行错误是主要诊断信息。 -- 测试数据：只使用测试构造的字符串、路径和模拟响应，不使用生产数据。 -- 构建产物：Python 缓存和临时文件不提交。 - -## 项目专用验收要求 - -- 只有长期事实变化时才更新核心 Wiki 并导出本地镜像；单次任务证据保存在工单，默认不创建任务归档，用户或项目专用规则明确要求时才创建或导出专项快照。 -- 镜像必须包含来源页面、revision 和同步时间。 -- 页面删除、重命名和映射变更必须人工确认。 -- 新增核心文档时必须更新 Home、显式映射和 Harness 检查。 -- 代码入口、命令、配置、业务规则或排错方式变化时必须评估文档影响。 -- `python dev_scripts/harness.py check --strict` 必须通过。 -- `python -m unittest discover -s tests -v` 必须通过。 -- 未执行或无法覆盖的验证必须记录到工单。 diff --git a/docs/01-LinguaCafe需求提取.md b/docs/01-LinguaCafe需求提取.md new file mode 100644 index 0000000..19ec9e6 --- /dev/null +++ b/docs/01-LinguaCafe需求提取.md @@ -0,0 +1,185 @@ +# LinguaCafe 功能需求提取 + +调研日期：2026-09-10。用途：作为 LexGo 使用 Go 复刻 LinguaCafe 的需求基线。 + +## 1. 调研基线与可信边界 + +目标仓库：[simjanos-dev/LinguaCafe](https://github.com/simjanos-dev/LinguaCafe)。本次实际读取 main 的提交 `c1ea298ce40c65b9dd33e9b26fd2e52fae66f2c8`，提交时间为 2025-03-19T21:17:36+01:00，消息为 `add: update notes`。日期代表本次获取的提交，不代表已经核实所有分支或镜像版本。 + +方法：阅读仓库手册、路由、管理页面、业务服务、模型、Python 文本处理器和依赖清单，并参考官方 Wiki。本次没有启动原版进行端到端测试；“已确认”表示有文档或代码证据，不表示所有外部集成在今天仍可运行。 + +原仓库只读参考副本：`D:/opc_project/linguacafe-reference`。本目录只保存需求和分析，不包含复刻实现。 + +证据索引（以下源码链接均固定到本次提交）： + +| 编号 | 来源 | 用途 | +|---|---|---| +| S1 | [README](https://github.com/simjanos-dev/LinguaCafe/blob/c1ea298ce40c65b9dd33e9b26fd2e52fae66f2c8/README.md) | 定位、语言清单、声明与资源归属 | +| S2 | [使用手册](https://github.com/simjanos-dev/LinguaCafe/blob/c1ea298ce40c65b9dd33e9b26fd2e52fae66f2c8/manual/Usage%20and%20features.md) | 导入、阅读、词汇、复习、主题与目标 | +| S3 | [安装和配置手册](https://github.com/simjanos-dev/LinguaCafe/blob/c1ea298ce40c65b9dd33e9b26fd2e52fae66f2c8/manual/Setup.md) | 多用户限制、语言、词典、Anki、备份 | +| S4 | [Web 路由](https://github.com/simjanos-dev/LinguaCafe/blob/c1ea298ce40c65b9dd33e9b26fd2e52fae66f2c8/routes/web.php) | 页面/API 和管理员权限边界 | +| S5 | [管理页面](https://github.com/simjanos-dev/LinguaCafe/blob/c1ea298ce40c65b9dd33e9b26fd2e52fae66f2c8/resources/js/components/Admin/AdminSettingsLayout.vue) | 管理区真实菜单 | +| S6 | [文本处理器](https://github.com/simjanos-dev/LinguaCafe/blob/c1ea298ce40c65b9dd33e9b26fd2e52fae66f2c8/tools/tokenizer.py) | 分词、EPUB、字幕、网页、语言模型接口 | +| S7 | [词汇服务](https://github.com/simjanos-dev/LinguaCafe/blob/c1ea298ce40c65b9dd33e9b26fd2e52fae66f2c8/app/Services/VocabularyService.php) | CSV 格式、状态编码、短语与检索 | +| S8 | [复习查询](https://github.com/simjanos-dev/LinguaCafe/blob/c1ea298ce40c65b9dd33e9b26fd2e52fae66f2c8/app/Services/ReviewService.php)、[单词调度](https://github.com/simjanos-dev/LinguaCafe/blob/c1ea298ce40c65b9dd33e9b26fd2e52fae66f2c8/app/Models/EncounteredWord.php)、[复习界面](https://github.com/simjanos-dev/LinguaCafe/blob/c1ea298ce40c65b9dd33e9b26fd2e52fae66f2c8/resources/js/components/Review/Review.vue) | 到期筛选、等级、重学、练习模式 | +| S9 | [导入服务](https://github.com/simjanos-dev/LinguaCafe/blob/c1ea298ce40c65b9dd33e9b26fd2e52fae66f2c8/app/Services/ImportService.php)、[后台任务](https://github.com/simjanos-dev/LinguaCafe/blob/c1ea298ce40c65b9dd33e9b26fd2e52fae66f2c8/app/Jobs/ProcessChapter.php) | 文本处理任务与章节生成 | +| S10 | [Compose](https://github.com/simjanos-dev/LinguaCafe/blob/c1ea298ce40c65b9dd33e9b26fd2e52fae66f2c8/docker-compose.yml) | 部署组件、备份计划 | +| S11 | [管理员中间件](https://github.com/simjanos-dev/LinguaCafe/blob/c1ea298ce40c65b9dd33e9b26fd2e52fae66f2c8/app/Http/Middleware/AdminMiddleware.php) | 服务端 `is_admin` 校验 | + +### 关键冲突：并非完全没有多用户或管理端 + +S1 仍写着每台服务器仅支持一个用户；S3 明确描述已增加多用户支持及其限制。S4、S5、S11 也存在用户管理、管理员判断和管理页面，S8 查询按用户隔离。 + +因此，本报告将其归纳为：**有多用户基础和管理区，但多用户支持尚不完整，不能按成熟多租户平台理解。** 不能只依据 README 判定“只有单用户”，也不能因为有用户表就推定完整隔离已通过验证。 + +## 2. 产品定位与主要流程 + +LinguaCafe 是自托管的外语阅读和词汇学习工具。核心闭环是：导入感兴趣的材料 → 选择适合难度的章节 → 阅读时查询并保存词语 → 在上下文中复习 → 查看学习进展。 + +“书籍”是内容集合，可以是小说，也可以是新闻、播客文本或字幕集合；“章节”是可阅读、可处理、可统计的内容单位。它不是以课程售卖、直播教学或考试为中心的 LMS。 + +角色有普通学习者和实例管理员；个人部署时，同一个账号可以同时承担两种职责。原版未证实教师、组织管理员、付费会员等角色。 + +典型流程： + +1. 管理员完成账号、目标语言、语言模型和词典配置。 +2. 学习者选择语言，导入内容到新书或已有书，等待章节处理。 +3. 根据新词、已知词和学习中词汇数量选择章节。 +4. 阅读时点词、划选短语，保存释义、读音或例句并调整学习状态。 +5. 完成章节，更新阅读统计；按设置批量将新词标为已知。 +6. 按全库、书籍或章节范围复习，或仅练习而不改变复习数据。 +7. 查看每日目标、日历和累计统计，必要时导出词汇或发送 Anki。 + +## 3. 用户端功能清单 + +优先级是 **LexGo 的实施建议**，并非上游优先级。P0 为首个可用闭环；P1 为主要功能补齐；P2 为专项语言或外部集成补齐。完整复刻需要覆盖 P0～P2。 + +| ID | 模块 | 原版需求/行为 | 建议优先级 | 证据 | +|---|---|---|---|---| +| U01 | 身份与偏好 | 登录、修改密码、选择学习语言、个人设置；具有用户管理基础 | P0 | S3、S4 | +| U02 | 内容库 | 创建、修改、删除书籍和章节，管理封面，进入章节阅读/编辑 | P0 | S2、S4 | +| U03 | 难度提示 | 书籍和章节展示独立词、已知词、高亮词、新词等数量 | P0 | S2 | +| U04 | 文本导入 | 粘贴文本、上传文本文件；新建书籍或追加章节 | P0 | S2、S9 | +| U05 | 电子书导入 | 导入 EPUB 并分章；不能由“ebook”推定支持 PDF、MOBI | P1 | S2、S6 | +| U06 | 网页导入 | 输入 URL 提取正文，编辑后入库；有语言/网站适用限制 | P1 | S2、S6 | +| U07 | 字幕导入 | 字幕文件、YouTube 字幕、Jellyfin 外部字幕；保留字幕时间信息的处理路径 | 文件 P1，远程 P2 | S2、S6、S9 | +| U08 | 导入设置 | Simple/Detailed 处理选项与章节长度设置；手册默认 3000、上限 15000 字符 | P0 | S2 | +| U09 | 后台处理 | 章节异步处理，处理状态更新，失败章节重试入口 | P0 | S4、S9 | +| U10 | 阅读器 | 按词语状态高亮文本、切换章节、选择词语、快捷键操作 | P0 | S2 | +| U11 | 词语浮层 | 侧栏、弹窗、移动端底部面板、鼠标悬停四种查询呈现 | 主查询 P0，完整形态 P1 | S2 | +| U12 | 词汇保存 | 保存/修改释义、读音、学习等级、例句；可以标记已知或忽略 | P0 | S2、S4 | +| U13 | 短语 | 连续选择多个词创建短语，保存释义与等级，并在文本中识别 | P0 | S2、S7 | +| U14 | 词典查询 | 导入词典查词；有 lemma 时可用于查词；普通面板可部分匹配，悬停以精确匹配为主 | P0 | S2 | +| U15 | 在线翻译 | DeepL、LibreTranslate、MyMemory、自定义 API 的配置和查询路径 | P1 | S3、S4 | +| U16 | 完成阅读 | 更新阅读数据，可将章节新词批量置为已知；允许关闭自动置已知 | P0 | S2 | +| U17 | 复习 | SRS、全库/书/章节筛选、单词和短语、答对/答错、重学处理 | P0 | S2、S8 | +| U18 | 练习模式 | 不改变复习数据地练习词汇 | P1 | S2、S8 | +| U19 | 词汇库 | 搜索、筛选、排序、编辑词和短语，CSV 导入/导出 | 查询编辑 P0，CSV P1 | S4、S7 | +| U20 | Anki | 经 AnkiConnect 添加卡片；可配置相关连接与卡片字段 | P2 | S3、S4 | +| U21 | 学习目标 | 每日阅读、标记词语、复习目标；日历进展、累计统计及日历数据修改 | P0 | S2、S4 | +| U22 | 朗读 | 阅读/复习页面使用浏览器 SpeechSynthesis，可按语言选择声音 | P1 | S2 | +| U23 | 汉字与读音 | 日语汉字、部首信息；日语/中文机器读音可供显示和人工修正 | P2 | S2、S4、S6 | +| U24 | 外观 | 浅色、深色、电子墨水屏主题，自定义颜色和字体 | 基础主题 P0，完整定制 P1 | S2 | +| U25 | 移动访问 | 响应式布局与 PWA 添加到主屏；手册声明屏幕宽度至少 340px | 响应式 P0，PWA P1 | S2 | +| U26 | 数据维护 | 删除本人某语言学习数据；帮助、更新说明、资源归属入口 | P1 | S4 | + +### 3.1 词语状态与复习规则不能简化成普通生词本 + +原版 CSV 和内部编码映射如下（S7）： + +| 业务状态 | CSV 表达 | 原版内部 stage | +|---|---|---| +| 新词 | `new` | `2` | +| 忽略 | `ignored` | `1` | +| 已知 | `learned` | `0` | +| 学习等级 1～7 | `1`～`7` | `-1`～`-7` | + +等级越接近 0 越接近学会。忽略词不算学会的词。原版把状态和等级合并编码；Go 可以改成显式状态加等级，但 CSV 和迁移层必须保留正确映射。 + +S8 表明：正常复习选取学习状态、到期或重学词条；练习模式不要求到期。答对可能清除重学标记或向 0 前进，答错可能退级并进入重学。单词模型按当前等级配置的候选间隔，选择已有复习数量较少的日期；这不是简单的固定间隔表，也不能直接称为 FSRS。 + +要逐项对齐原版时，还需覆盖短语调度与单词调度的差异、同日重学、时区、重复提交及边界等级。以上是已提取的规则概要，不是完整状态机测试结果。 + +### 3.2 词典及语言数据 + +词典数据与用户保存释义是不同概念：前者是可复用查询资源，后者是个人学习记录。悬停结果还区分个人释义、字典结果和在线翻译。读音或词形还原可能出错，需要保留原词、来源和人工修正能力。（S2、S3） + +S1 列出 27 种语言：中文、克罗地亚语、捷克语、丹麦语、荷兰语、英语、芬兰语、法语、德语、希腊语、意大利语、日语、韩语、拉丁语、马其顿语、挪威语、波兰语、葡萄牙语、罗马尼亚语、俄语、斯洛文尼亚语、西班牙语、瑞典语、泰语、土耳其语、乌克兰语、威尔士语。 + +“支持一种语言”不代表该语言同时具有高质量分词、lemma、词性、性别标注、读音、离线词典和所有翻译服务。S3 的支持矩阵应转换为可配置的能力字段；首期只承诺经过验收的语言组合。 + +### 3.3 CSV 互通 + +原版词汇导入字段按顺序为 Word、Translation、Lemma、Reading、Lemma reading、Level；至少提供 Word。支持跳过首行、仅更新已存在词条，并报告创建、更新、拒绝数量。缺少某列与显式空值语义不同：未提供字段保留旧值，提供空值可能清空旧值。（S3、S7） + +Go 版兼容导入必须测试这些差异；词汇 CSV 不包含全部书籍、设置和复习历史，不能作为完整备份格式。 + +## 4. 管理端功能清单 + +S5 的真实菜单为 Dashboard、Users、Languages、Dictionaries、Fonts、API、Reviews。管理区已存在，应复刻其职责。 + +| ID | 模块 | 已确认的职责 | 建议优先级 | 证据 | +|---|---|---|---|---| +| A01 | 管理员访问 | 服务端管理员权限检查，受限管理页面/API | P0 | S4、S11 | +| A02 | 用户管理 | 创建/查看/更新用户；手册说明用户删除仍缺失 | P0 | S3、S4、S5 | +| A03 | 语言管理 | 安装、查看语言模型；原版手册说明卸载是整体卸载已安装语言 | P0 | S3、S4 | +| A04 | 词典管理 | 支持的词典导入、CSV 测试/导入、编辑/删除、条目数量查询 | 基础 P0，格式补齐 P1 | S4 | +| A05 | 翻译 API | DeepL/LibreTranslate/MyMemory/自定义 API 配置；有 DeepL 用量查询 | P1 | S3、S4 | +| A06 | 字体管理 | 上传、编辑、删除字体；指定字体适用语言 | P1 | S2、S4 | +| A07 | 复习设置 | 配置复习等级对应间隔等参数 | P0 | S2、S5、S8 | +| A08 | 集成设置 | Anki、Jellyfin 等连接配置 | P2 | S3、S5 | +| A09 | 系统设置 | 全局设置读写及管理概览 | P0 | S4、S5 | +| A10 | 备份 | 创建数据库备份、计划备份；完整恢复还依赖文件数据 | P0 | S3、S4、S10 | + +不应把业务词典与后台框架的“数据字典”混为一谈。前者处理大量语言词条、释义、词形和来源；后者通常只是性别、状态等枚举选项。 + +## 5. 非功能要求与已知限制 + +### 原版可观察约束 + +- 自托管：存在 Web、MySQL、Redis、Python 文本服务等组件。（S10） +- 长文本性能：手册提示过长章节拖慢阅读器；短语新增会涉及已导入文本索引，内容量大时可能变慢。（S2） +- 多用户限制：Anki 请求经服务器发送，不适合多个用户各自桌面；用户删除缺失；同一浏览器的部分显示设置在账号间共用。（S3） +- 设置分层：阅读和复习显示设置部分位于浏览器；用户设置页的数据位于服务端。（S2） +- PWA 支持仅证实安装/全屏形态，不能据此承诺离线学习、断网同步或原生 App。（S2） +- 外部资源依赖：模型安装需要联网；网页/字幕抓取和在线翻译需单独验证当前可用性。（S3、S6） +- 数据保护：数据库备份与文件备份要结合；自动数据库备份并不等于完整实例备份。（S3、S10） + +### LexGo 建议新增的质量要求（不是声称原版已具备） + +| ID | 要求 | 可验收标准 | +|---|---|---| +| N01 | 用户隔离 | 用户 B 无法以书籍、词汇、任务或文件 ID 访问/修改用户 A 数据 | +| N02 | 重试幂等 | 重复执行同一导入任务不增加重复章节；重复提交同次复习不重复计数 | +| N03 | 可恢复任务 | Worker 重启后任务能恢复或重试，并有可读失败原因 | +| N04 | 文本完整性 | 分词/渲染后原文空白、标点、Unicode 字符可还原，词语点击位置正确 | +| N05 | 本地核心可用 | 安装完资源后，不依赖在线翻译也能阅读、保存词汇与复习 | +| N06 | 完整备份恢复 | 在空白实例恢复数据库、文件和资源清单后，内容与学习状态相符 | +| N07 | 移动与键盘操作 | 至少覆盖 360px、平板、桌面；键盘可完成查词和复习，不仅靠颜色表达状态 | +| N08 | 性能目标 | 固定 4 核/8GB 测试机、单库 100 万词条、20 并发下，离线查词 API p95 目标 <300ms；须实测后定版 | + +N08 是拟定目标，不是基准测试结果；不包含公网延迟、外部翻译时间和冷启动模型加载。 + +## 6. 不能归入“原版已支持”的扩展 + +多租户组织、课程商城、会员收费、教师班级、社交排行榜、AI 对话、自动生成课程、PDF OCR、视频转写、云端高质量 TTS、原生移动 App、完整离线同步、FSRS 算法、通用用户删除与审计后台，均不能根据本次证据直接认定为现成功能。 + +这些可以另立扩展需求；特别是用户删除、操作审计、个人 Anki 连接与浏览器设置隔离，适合在多用户版中补齐。 + +## 7. 建议首版范围与验收场景 + +首版建议：普通用户/管理员、英语先行、文本导入、章节处理、阅读查词、单词/短语状态、基础复习、统计、基础词典管理、备份。中文/日语通过独立语言验收后加入；英语先行是可调整假设。 + +| 场景 | 通过条件 | +|---|---| +| 全流程 | 安装词典 → 导入一段文本 → 阅读查词 → 保存短语 → 完成阅读 → 到期复习 → 统计更新可完成 | +| 状态一致 | 同一用户同语言同词在不同章节状态一致；忽略与已知统计分开 | +| 完成阅读 | 开关关闭时只更新阅读行为，不批量改变新词；重复请求无重复副作用 | +| 多用户 | A 保存的释义、学习状态和书籍不会进入 B 的查询或复习列表 | +| 后台权限 | 普通用户直接请求管理员 API 得到拒绝，隐藏菜单不是唯一防线 | +| 失败恢复 | 模拟文本处理失败，页面展示错误；重试后章节只生成一份 | +| 复习 | 固定时间测试到期、未到期、重学、答对/答错；练习不改变调度状态 | +| 字符与短语 | 中文、日文、重音字符、emoji、换行与重叠短语不造成错位或原文丢失 | +| 备份 | 恢复后书籍数量、抽样词汇状态、用户设置与文件校验一致 | + +需求提取已完成；具体范围取舍和框架方案见 [Go 复刻与框架选型分析](02-Go复刻与框架选型分析.md)。 diff --git a/docs/01-workflow.md b/docs/01-workflow.md deleted file mode 100644 index ca62c0f..0000000 --- a/docs/01-workflow.md +++ /dev/null @@ -1,346 +0,0 @@ - -generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) -wiki_page: Development-Workflow -wiki_url: https://git.ilapage.cn/OPC/dev_harness/wiki/Development-Workflow.- -wiki_revision: 0ed57c573d29064909095fbf8720629945c31592 -synchronized_at: 2026-09-04T06:12:17Z - - -# 开发工作流 - -## 事实来源边界 - -- 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` 页面（由[部署文档模板](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` 镜像 | -|---|---:|---:|---:| -| 讨论过程和临时方案 | 是 | 否 | 否 | -| 实施进度和阻塞 | 是 | 否 | 否 | -| 长期有效的最终方案 | 链接 | 是 | 镜像 | -| 测试结果与未验证内容 | 是 | 否 | 否 | -| 提交哈希和验收结论 | 是 | 否 | 否 | -| 用户明确要求的任务专项快照 | 提供来源 | 可选 | 可选导出 | -| 与具体代码版本绑定的说明 | 可链接 | 提供入口 | 是 | diff --git a/docs/02-Go复刻与框架选型分析.md b/docs/02-Go复刻与框架选型分析.md new file mode 100644 index 0000000..2917238 --- /dev/null +++ b/docs/02-Go复刻与框架选型分析.md @@ -0,0 +1,265 @@ +# 使用 Go 复刻 LinguaCafe：架构与二次开发选型 + +调研日期：2026-09-10。状态：可供评审的技术建议，尚未进入编码实现。原项目证据、提交基线与需求 ID 见 [需求提取](01-LinguaCafe需求提取.md)。 + +## 1. 结论与适用前提 + +**Go 适合承担账号权限、内容库、词典查询、学习状态、SRS、统计、任务调度和管理 API。推荐 Go 业务后端 + Vue 3 学习前端 + 管理区，先保留独立的 Python NLP 服务。** + +若重点是快速二次开发，首选 **gin-vue-admin 作为管理与通用基础能力的底座，学习业务按模块开发，用户端阅读器独立设计**。若主要供个人自托管，使用 Gin + Vue 3 自建轻量管理区会更精简。 + +本文默认团队熟悉或愿意采用 Go/Vue，希望先交付自托管可用产品，并保留多用户能力；没有假定要做商业 SaaS、组织多租户或收费系统。Go 指主要业务后端，不意味着浏览器界面也必须用 Go 编写。 + +首版不建议将全部服务拆成微服务，也不建议为“纯 Go”一次性重写全部语言模型能力。是否严格禁止 Python、首发学习语言和是否需要旧数据迁移，是后续影响工期最大的决策点；不妨碍本次形成需求和方案。 + +## 2. 原项目技术结构与迁移含义 + +本次读取的源代码依赖声明如下，属于原仓库状态，不是推荐的新项目版本： + +| 层次 | 原项目证据 | Go 版处理 | +|---|---|---| +| Web 业务 | PHP `^8.2`、Laravel `^11.9`；Horizon、Reverb、Sanctum 依赖 | 用 Go 重写应用服务、认证、任务与事件通知 | +| 前端 | Vue `^2.6.12`、Vuetify `^2.6.12`、Vuex、Vue Router 3、Laravel Mix | 建议 Vue 3 + TypeScript + Vite；Vue 2 组件不能直接当 Vue 3 组件复用 | +| 数据 | MySQL、Redis、用户文件目录 | 优先沿用 MySQL 以降低首期迁移与后台集成成本 | +| 文本处理 | Python + Bottle、spaCy、EbookLib、字幕和网页解析依赖 | 保留语言处理边界，逐步替换导入工具或 NLP 实现 | +| 阅读业务 | 词语状态、短语索引、上下文例句、复习交互 | 是核心领域逻辑，需要定制，后台生成器不能直接覆盖 | + +来源：[composer.json](https://github.com/simjanos-dev/LinguaCafe/blob/c1ea298ce40c65b9dd33e9b26fd2e52fae66f2c8/composer.json)、[package.json](https://github.com/simjanos-dev/LinguaCafe/blob/c1ea298ce40c65b9dd33e9b26fd2e52fae66f2c8/package.json)、[PythonDockerfile](https://github.com/simjanos-dev/LinguaCafe/blob/c1ea298ce40c65b9dd33e9b26fd2e52fae66f2c8/docker/PythonDockerfile)、[tokenizer.py](https://github.com/simjanos-dev/LinguaCafe/blob/c1ea298ce40c65b9dd33e9b26fd2e52fae66f2c8/tools/tokenizer.py)。 + +迁移不是把 PHP 文件逐个改写成 Go。原版大部分业务端点位于 `routes/web.php`，带 Web/Session 语义；只有检查 `routes/api.php` 会遗漏主要功能。新 API 可以重新设计，但应按行为验收，不能依据旧路由名称机械推断业务。 + +## 3. 需要用户端和管理端吗？ + +**需要两类功能入口，初期不需要两套后端或两个独立部署系统。** 原版已经有 Admin 页面、服务端管理员校验以及 Users、Languages、Dictionaries、Fonts、API、Reviews 等管理菜单。 + +| 维度 | 用户端 | 管理端 | +|---|---|---| +| 目的 | 阅读与个人学习 | 维护实例资源和配置 | +| 主要页面 | 学习首页、书库、导入、阅读器、词汇库、复习、目标/日历、个人设置 | 用户、语言模型、词典、字体、API、复习策略、任务与备份 | +| 数据边界 | 本人书籍、词汇、进度、个人释义 | 全局资源与系统设置；个人内容访问须另行明确授权 | +| 界面特点 | 阅读舒适、低干扰、键盘与触屏操作 | 表格、表单、任务进度、配置验证 | +| 可复用程度 | 阅读器和复习器大部分定制 | 账号、菜单、权限、CRUD 可复用脚手架 | + +部署建议： + +- 个人版：一个 Vue 项目内分 `/app` 和 `/admin` 两种布局，共用 Go API；默认账号同时具有管理员和学习者身份。 +- 多用户版：同一仓库中可拆 `web/learner` 和 `web/admin` 两个前端构建，共用一个 Go 模块化后端。增加构建分离是工程选择，不是功能必要条件。 +- 组织/SaaS 版：确有组织边界、独立发布或合规需求后，再引入租户模型和更多服务；不能将普通多用户直接称为多租户。 + +管理端 RBAC/Casbin 负责“能否使用某种功能”；业务层还必须校验“这本书是否属于本人”。只有菜单和 API 权限，不等于有数据所有权隔离。 + +推荐页面/API 前缀分别为 `/app/*`、`/admin/*`、`/api/v1/*`、`/api/admin/v1/*`。页面路由与 API 路由分开，统一错误结构、请求 ID、分页和认证语义。 + +## 4. 三种落地路线 + +| 路线 | 组合 | 优点 | 代价 | 适用性 | +|---|---|---|---|---| +| A：管理脚手架二开，推荐 | gin-vue-admin + 独立学习领域模块/页面 + NLP 服务 | 通用管理功能起步快，Go/Vue 生态一致 | 要约束脚手架侵入业务，阅读器仍需自研 | 团队希望较快交付用户端和管理端 | +| B：精简产品工程 | Gin + Vue 3 + GORM + 自建轻量管理区 + NLP 服务 | 依赖和页面更少，学习业务结构清楚 | 认证、管理表单、任务页需自己补齐 | 个人版、自托管优先或重视长期自主维护 | +| C：全 Go 且逐语言实现 | Gin/GoFrame + Vue 3 + Go 文本处理适配器 | 可减少 Python 运行环境 | 分词、lemma、读音、模型覆盖和效果验证成本最高 | 明确要求纯 Go，并接受首版语言收缩 | + +综合建议选择 A；如果实际上只给本人使用，选择 B。路线 C 技术上可以推进，但不能承诺换一种语言实现后仍立即具备原版 27 种语言的同等体验。 + +## 5. 流行框架与二次开发底座比较 + +这里区分 HTTP 框架、工程框架和完整管理脚手架。选型依据是任务匹配度，不是声称某项目在所有场景最好。已核验官方仓库/文档；没有依据星数给出排名，也没有执行候选框架的编译和性能对比。 + +### 5.1 Go 后端候选 + +| 候选 | 类型/已核验能力 | 本项目判断 | +|---|---|---| +| [Gin](https://gin-gonic.com/en/docs/) | HTTP 路由、中间件、绑定/校验与响应处理 | 首选。能与推荐管理底座保持一致；ORM、队列和领域模型仍需组合 | +| [GoFrame](https://github.com/gogf/gf) | 集成式 Go 工程框架及配套工具 | 想要较统一开发规范时可选；采用后不必再叠另一套 HTTP/ORM 约定 | +| [go-zero](https://github.com/zeromicro/go-zero) | 面向云原生服务的框架与代码生成工具 | 团队已熟悉时可用；本项目首期没有足够理由为它主动拆微服务 | + +Gin 足以处理这里的 HTTP 需求。真正需要优化的是语言模型加载、字典检索、章节文本结构和前端渲染；仅比较框架 QPS 对选型帮助有限。 + +### 5.2 管理底座候选 + +| 候选 | 能直接借用什么 | 需要核实/自己开发什么 | 建议 | +|---|---|---|---| +| [gin-vue-admin](https://github.com/flipped-aurora/gin-vue-admin) | Gin/Vue 管理工程、JWT/Casbin、用户角色菜单、文件与代码生成等基础能力 | 学习者身份适配、数据所有权、阅读器、SRS、语言词典、分词任务；确认开源与商业功能边界 | 快速二开首选 | +| [go-admin-team/go-admin](https://github.com/go-admin-team/go-admin) | Gin 系管理脚手架、RBAC、生成器及项目声明的多租户等能力 | 主仓库与具体前端仓库/分支版本组合；租户实现对学习数据的适配 | 团队已用此体系时作为备选 | + +gin-vue-admin 官方项目说明及代码目录指向 Vue 3/Vite/Gin 的组合，能够减少管理端通用开发。本文不会把它宣传为现成语言学习平台。go-admin 存在不同前端方案，不能假定所有历史版本都是同一 Vue 3 技术栈。 + +二开方法：固定一个验证过的上游提交；保留上游来源；仅生成资源维护等标准 CRUD；把 `library`、`reader`、`vocabulary`、`review` 放入独立业务模块，通过接口使用身份和基础设施。避免业务服务依赖后台菜单表、HTTP Context 或全局用户对象。 + +普通用户与后台账号可以基于统一身份体系加角色/资料表实现，首期不必维护两套密码与登录体系。权限模型要明确管理员是否同时可以学习，避免后台角色字段成为学习数据主键。 + +### 5.3 推荐技术栈 + +| 部分 | 推荐 | 原因/限制 | +|---|---|---| +| 业务 API | Go + Gin | 与管理底座一致；领域逻辑独立于 Gin | +| 管理页面 | gin-vue-admin 开源底座 | 缩短通用管理开发；按锁定版本核实能力 | +| 用户页面 | [Vue 3](https://vuejs.org/guide/introduction.html) + TypeScript + Vite | 适合阅读器这种状态丰富的交互界面 | +| 通用组件 | [Element Plus](https://element-plus.org/en-US/) | Vue 3 组件库，适合表单和管理；阅读正文/划词层自行开发 | +| 持久化 | MySQL + [GORM](https://gorm.io/docs/) | 与原版和管理底座衔接较省事；复杂检索允许显式 SQL，迁移用版本化脚本 | +| 异步任务 | Redis + [Asynq](https://github.com/hibiken/asynq) | 处理导入、分词、词典导入与备份；任务可重试，业务必须幂等 | +| NLP | 独立 Python/spaCy 服务 | 保留已验证语言能力，Go 通过内部接口调用；必须固定模型和依赖版本 | +| 任务进度 | 先轮询，确有需要再 SSE | 导入主要是单向状态展示，不必一开始复制完整 WebSocket 栈 | +| 文件 | 本地持久化目录 + 存储接口 | 符合自托管；未来需要时再接对象存储 | +| 部署 | Docker Compose | Go API、Worker、NLP、数据库和 Redis 可独立重启 | + +Asynq 文档声明至少一次执行语义，并提示 v0 系列 API 可能变化、部分脚本与 Redis Cluster 有兼容限制；首期使用常规 Redis 部署并锁定依赖版本。重复执行控制由业务记录、唯一键和事务共同保障，不能只靠队列的去重选项。 + +此处不指定猜测的“最新版本”。开工时按候选项目 `go.mod`、`package.json`、锁文件与 CI 要求选兼容组合，不可仅依据 README 中可能滞后的最低版本号。数据库首期只选一种；若团队已有 PostgreSQL 标准，可以在验证后台底座兼容后替换。 + +## 6. 推荐架构与模块边界 + +```mermaid +flowchart TD + L[Vue 学习端] --> G[Go API] + A[Vue 管理端] --> G + G --> B[账号与学习业务模块] + B --> D[(MySQL)] + B --> F[文件存储] + B --> Q[(Redis 任务队列)] + Q --> W[Go Worker] + W --> N[内部 NLP 服务] + W --> D + W --> F + G --> T[词典与外部翻译适配器] +``` + +API 与 Worker 可以来自同一个 Go 代码库、使用相同领域服务，但运行在不同进程。NLP 单独运行是为了依赖、内存和 CPU 隔离，不需要连带拆分账号、书库和词汇为微服务。 + +| 模块 | 责任 | 主要边界 | +|---|---|---| +| identity | 身份、角色、会话、所有权校验 | 不存储词汇学习规则 | +| library | 书籍、章节、导入源与阅读位置 | 不直接调用某个 Python 包 | +| ingestion | 文件校验、正文提取、分章、任务 | 通过 Parser/Tokenizer 接口处理文本 | +| lexicon | 词典、词条、读音、来源、外部翻译 | 与个人学习状态分离 | +| vocabulary | 用户词语/短语、释义、例句、状态 | 所有读写含用户与语言边界 | +| review | 复习查询、状态转换、调度、事件记录 | 服务端决定下一状态，前端提交作答结果 | +| progress | 阅读、标记、复习事件与统计 | 基于幂等事件聚合，避免重复累计 | +| administration | 全局配置、语言、字体、任务和备份 | 调用已有服务，不复制一套业务规则 | + +建议目录仅作规划：`cmd/api`、`cmd/worker`、`internal/{上述模块}`、`migrations`、`web/learner`、`web/admin`、`services/nlp`、`deploy`。路线 B 可以把两个 Web 目录合并；路线 A 则可适应上游 `server/web` 目录，模块职责比目录命名更重要。 + +## 7. 数据模型建议 + +以下是新设计建议，不表示与原版数据库逐表相同。 + +| 实体 | 关键数据与约束 | +|---|---| +| users / roles | 用户、角色、时区、选中语言；学习者角色与管理员角色可组合 | +| languages / language_models | 语言代码、能力标记、模型版本、安装状态 | +| books / chapters | owner_user_id、language_id、标题、原文、内容版本、处理状态 | +| chapter_tokens | chapter_id、内容版本、顺序、原词、lemma、句子位置、字符边界；存结构化块或表需基准验证 | +| user_terms | user_id、language_id、类型、标准化键、显示文本、释义、状态、等级、到期时间、重学标记 | +| term_occurrences | 用户词语/短语与章节的出现位置，用于按书复习与短语高亮 | +| dictionaries / dictionary_entries | 语言、来源、许可、版本、原词/lemma、释义和读音；与 user_terms 分开 | +| example_sentences | 用户、词语、例句文本、来源章节及版本；章节删除时保留必要快照 | +| review_events | 用户、词条、作答、前后状态、算法版本、事件唯一键 | +| reading_events / daily_stats / goals | 按用户、语言、本地日期记录事件与聚合统计 | +| jobs / import_sources / files | 所有者、来源摘要、状态、错误、输出版本、文件引用 | +| settings / provider_configs | 全局、用户、设备配置分层；凭证不返回普通配置接口 | + +词条的唯一键至少包含用户、语言、词条类型和规范化词语键。原词与 lemma 不应随意合并为同一学习项；需要明确是按词形学习还是按词元学习，并为迁移保留映射。 + +对英语大小写、德语名词大小写、土耳其语大小写、全角半角、组合重音、中文繁简体不能一律粗暴 lowercase。原文始终保留；检索规范化规则应按语言版本化。 + +复习查询索引建议包含 `(user_id, language_id, state, next_review_at)`；词典查询索引包含 `(language_id, normalized_headword)`；章节访问包含 `(owner_user_id, book_id, ordinal)`。具体索引以真实查询计划验证，不能靠 ORM 默认索引解决所有检索问题。 + +## 8. Go 复刻的主要难点和处理方案 + +### 8.1 多语言处理与纯 Go 的边界 + +空白切分能做英语粗分词，但不是 lemma、词性和句法处理，也不足以覆盖中文、日语、泰语。原版已有 Python 调用边界，保留这个边界比先移植全部 NLP 更实际。 + +建议内部 Tokenizer 接口输入语言、原文、处理模式和内容版本，输出 token 列表、原词、lemma、词性/性别、读音、句子索引、字符边界、模型版本与告警。不同语言允许部分字段缺失，UI 按能力呈现，不伪造分析结果。[spaCy 官方语言特性说明](https://spacy.io/usage/linguistic-features)也明确不同注释能力依赖相应流水线和模型。 + +边界单位必须固定：Go 字节偏移、Python 字符索引、JavaScript UTF-16 索引不同。建议跨服务使用 token ID 与约定的 Unicode 标量位置，在浏览器建立映射；保存未改动原文，覆盖 emoji、组合字符及混合语言测试。不能直接拿 Go 字节下标去做 JS `slice`。 + +若最终要求纯 Go，先完成英语基础规则与词典查词，再对每种目标语言建立同一组真实语料对比基准，逐个替换适配器。Go 可编译成二进制，不代表语言模型、数据库和字典也能免安装或没有内存成本。 + +### 8.2 阅读器与短语索引 + +阅读器是最大的前端定制项：点击词语、连续划选、重叠短语、键盘操作、移动端底部面板、读音、状态同步和长文本渲染都需要产品级处理。 + +章节正文与个人状态分开缓存；状态变更只更新当前可见 token 的呈现。先按章节和段落限制渲染量，实测有需要再虚拟化；盲目虚拟化可能破坏原生选择和可访问性。 + +新增短语时不要同步扫描所有文本后才返回。先提交短语，更新当前章节，再以后台任务维护该用户该语言的出现索引；索引任务携带短语/内容版本，过期结果不能覆盖新内容。需规定重叠短语的显示和点击优先级。 + +### 8.3 SRS 要以行为兼容为起点 + +首版实现原版等级/重学思路，并固定时钟、随机顺序和间隔配置建立对照样例。客户端只提交“本次答对/答错”，服务端在事务中验证当前状态、计算调度并写事件。不要把原版前端算出的任意 stage 更新原样暴露为可信 API。 + +FSRS 可以作为独立增强，但会改变复习行为。若添加，要有算法版本、迁移策略和明确选择，不将其标注为忠实复刻要求。练习模式不更新学习调度，是否计入练习统计应独立定义。 + +### 8.4 导入、词典与外部服务 + +导入状态建议为 queued → extracting → tokenizing → indexing → ready，失败进入 failed 并保留失败阶段。以源文件摘要、用户、语言、处理选项、内容版本建立幂等记录；数据库持久化任务状态，再通过 outbox/补偿派发避免事务成功但任务未入队。 + +词典支持分批导入、错误行报告、暂存版本和成功后切换。普通查词与悬停精确查询可以分别设计，缓存键必须包含语言、词典版本、查询模式；用户自定义释义不能进入跨用户共享缓存。 + +网页和外部字幕提取失败要有手动文本/字幕上传回退。在线翻译需要超时、配额、提供方状态提示，返回来源；不能让外部服务失败阻断阅读。 + +### 8.5 多用户与 Anki + +原版手册说明 Anki 由服务器连接，这在多人各用自己桌面时不成立。首版先支持个人 CSV 导出；后续单独设计用户本地桥接或经用户配置的 AnkiConnect 连接，验证浏览器跨域、HTTPS/HTTP 和局域网访问限制。不能让所有账号共用管理员桌面的 Anki 连接。 + +浏览器设置键加入实例标识和用户 ID；服务端保存用户偏好，设备级字号等允许本地覆盖。新增加用户删除时，应有任务化清理、关联数据策略和最后管理员保护。 + +## 9. 接口草案与工程质量 + +下表是 Go 新接口草案，不是原版路由复制： + +| 行为 | 建议接口 | 核心校验 | +|---|---|---| +| 导入材料 | `POST /api/v1/imports` | 当前用户、语言、格式和大小；返回 job_id | +| 查看任务 | `GET /api/v1/jobs/{id}` | 任务所有权，避免泄露其他用户材料 | +| 打开章节 | `GET /api/v1/chapters/{id}/reader` | 所有权、处理状态、内容版本 | +| 查词 | `POST /api/v1/dictionary/lookups` | 语言、查询模式、范围与提供方权限 | +| 保存词语 | `PUT /api/v1/terms/{id}` | 所有权、版本冲突、合法状态 | +| 保存短语 | `POST /api/v1/phrases` | token 范围、章节版本、短语一致性 | +| 完成阅读 | `POST /api/v1/chapters/{id}/completions` | 幂等键、计数语义、批量置已知开关 | +| 获取复习 | `GET /api/v1/reviews` | 用户/语言/书/章节一致性 | +| 提交作答 | `POST /api/v1/review-events` | 事件唯一键、当前词条版本、服务端调度 | +| 导入词典 | `POST /api/admin/v1/dictionaries/imports` | 管理权限、文件与资源配额 | + +公开部署所需的具体防护：HTML/EPUB 正文清理防止脚本注入；URL 导入限制重定向后的地址与内网访问；模型/字典下载只接收受控资源；上传限制解压大小和路径；Cookie 会话配合 CSRF，或按所选 JWT 体系统一续期与撤销策略。不要同时拼接两套互不一致的认证方案。 + +验证优先覆盖领域规则、跨用户访问、任务重试、Unicode 文本定位、复习重复提交和备份恢复。浏览器自动化至少覆盖“导入—阅读—保存—复习”闭环，以及触屏选择和管理员直接 API 访问。此报告没有运行这些测试，属于后续验收计划。 + +## 10. 开发顺序与工作量判断 + +估算前提：两名熟悉 Go/Vue 的工程师、现成测试材料、复用管理底座、保留 Python NLP、不同时建设商业 SaaS 和原生 App。下列是规划量级，不是承诺排期，也不是已有实现进度。 + +| 阶段 | 对应需求 | 交付结果 | 粗估 | +|---|---|---|---| +| M0 风险验证 | U08/U10/U14/U17 | 英语/目标语言分词样例、词典查询、原版状态映射与阅读交互验证 | 1～2 周 | +| M1 核心闭环 | 主要 P0、A01～A04/A07/A09/A10 | 账号隔离、文本导入、阅读器、词语短语、基础复习、统计、最小管理与备份 | 5～8 周 | +| M2 主要功能补齐 | P1 | EPUB/网页/字幕文件、CSV、练习、主题/PWA、字体、在线词典 | 3～5 周 | +| M3 外部/语言专项 | P2 | Anki/Jellyfin/YouTube、日中读音和汉字专项、更多语言验收 | 3～6 周 | +| M4 稳定化 | N01～N08、迁移需求 | 压测、断点恢复、升级/恢复演练和数据迁移工具 | 2～4 周 | + +按阶段顺序粗估约 14～25 周达到较广的功能覆盖；首个核心可用版约 6～10 周。27 种语言逐一达到质量承诺、严格纯 Go、旧实例完整迁移或复杂移动适配都可能显著增加工作量。若 M0 暴露 NLP 或内容格式问题，应重估后续阶段。 + +对用户最有价值的第一个里程碑是可实际使用的阅读学习闭环；先堆满后台菜单而没有可靠阅读器，无法验证产品是否成立。 + +## 11. 原数据迁移与授权边界 + +迁移建议分两层：先做原版 CSV 词汇兼容，再考虑完整迁移工具。完整迁移需盘点用户、语言、书籍/章节、原文、token、个人释义、短语、例句、stage、next_review、设置和文件，建立旧 ID 到新 ID 映射。先只读导出、dry-run 报告和抽样核对，验证通过再导入新实例；保留旧实例可回退。 + +不能把旧 MySQL 数据库直接接到重新设计的 Go 表结构上。重新分词可能改变 token 边界，影响短语位置、例句和阅读位置；因此需要保留源文本版本与迁移日志，不能只有“重新导入书籍”。 + +原项目根 [LICENSE](https://github.com/simjanos-dev/LinguaCafe/blob/c1ea298ce40c65b9dd33e9b26fd2e52fae66f2c8/LICENSE) 是 GPL-3.0 文本；`composer.json` 中 Laravel 脚手架的 MIT 字段不能代替项目级许可证。直接复制/改写原代码或复用前端时，应按适用许可处理修改、分发、声明和对应源码要求；更换实现语言本身不能排除衍生关系。GPL 并不等于禁止商业使用，具体发布方式应结合完整许可判断。 + +若希望采用独立许可，应围绕公开功能规格独立实现，避免复制受保护代码/素材，并在分发前核查具体实现与依赖。字典数据、字形、语言模型和 Python 依赖各有自己的许可：例如上游 README 对 JMDict、CC-CEDICT、EbookLib 等分别列出归属，不可用项目代码许可证概括全部资源。 + +gin-vue-admin 当前官方仓库标示 Apache-2.0，并区分开源功能和商业授权版。引用它不会自动改变被复用 LinguaCafe 代码的许可义务。以上是实现时需要处理的资源边界，不是针对特定商业发行方式的法律结论。 + +## 12. 可直接采用的起步决策 + +1. Go + Gin 作为业务后端；选择 gin-vue-admin 开源底座，固定验证过的提交与依赖。 +2. 用户区与管理区共用后端，按角色和数据所有权授权；阅读器独立开发。 +3. 使用 Vue 3/TypeScript，通用表单采用 Element Plus；先做好桌面与手机浏览器。 +4. MySQL + GORM 管理业务数据；Redis + Asynq 处理导入/分词任务；版本化数据库迁移。 +5. 第一阶段保留 Python NLP，通过接口隔离；首发语言按 M0 验证结果确定。 +6. 先完成需求文档 P0 的闭环，再补 EPUB、完整 CSV、外部翻译和专项语言功能。 +7. 多用户隔离、幂等、文本位置正确性和备份恢复从第一阶段纳入验收。 + +若改为纯个人使用，减少管理底座依赖即可；若强制所有后端组件纯 Go，需要先缩小语言范围并重估 NLP 工作，而不是只更换 Web 框架。 diff --git a/docs/02-architecture-and-code-map.md b/docs/02-architecture-and-code-map.md deleted file mode 100644 index cf2b84b..0000000 --- a/docs/02-architecture-and-code-map.md +++ /dev/null @@ -1,89 +0,0 @@ - -generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) -wiki_page: Architecture-and-Code-Map -wiki_url: https://git.ilapage.cn/OPC/dev_harness/wiki/Architecture-and-Code-Map.- -wiki_revision: 06542b54af9954c186b10ba8cd5f923d501c6018 -synchronized_at: 2026-08-25T00:40:31Z - - -# 架构与代码地图 - -## 本页用途 - -帮助第一次接触项目的人回答三个问题： - -1. 项目由哪些部分组成； -2. 一个功能应该从哪里开始读； -3. 修改后应该运行哪些验证。 - -阅读代码前先看本页；目录、入口或主要数据流变化时必须更新本页。 - -## 项目定位 - -DevHarness 不是业务应用，而是一套开发工作流模板。它约束 Agent 和维护者如何讨论需求、建立工单、修改代码、更新 Wiki、测试、提交和验收，并在明确需要时创建专项快照。 - -```text -用户确认方案 -→ Gitea 单元任务工单 -→ Agent 修改代码与测试 -→ 长期结论更新 Wiki -→ Wiki 单向导出 docs 镜像 -→ Git 提交并回写工单 -→ 用户验收 -``` - -## 代码地图 - -| 能力 | 路径 | 阅读入口 | 主要对象或函数 | 验证位置 | 风险 | -|---|---|---|---|---|---| -| Agent 工作规则 | `AGENTS.md` | “需求到实施” | 工作流条款 | 人工审查、Harness 检查 | 高 | -| 工单结构 | `.gitea/issue_template/` | `task.md` | Epic、MVP、Task 模板 | 创建测试工单或检查模板 | 中 | -| Wiki 页面映射 | `wiki-docs.json` | `mappings` | 页面名、本地路径 | `harness.py sync --check` | 中 | -| Wiki API 和镜像生成 | `dev_scripts/wiki_docs.py` | `WikiClient`、`sync_all` | 配置、页面、镜像元数据 | `tests/test_wiki_docs.py` | 中 | -| 同步与校验 | `dev_scripts/harness.py` | `run_sync()` | `sync [--check] [--verify]` | 线上 Wiki 对照检查 | 低 | -| 可选任务快照 | `dev_scripts/harness.py` | `run_archive()` | `archive <编号> <短标题>` | 单元测试和显式专项归档 | 中 | -| Harness 结构检查 | `dev_scripts/harness.py` | `run_check()` | 必需文件、镜像和已有快照检查 | `check --strict` | 中 | -| 本地文档镜像 | `docs/` | `docs/README.md` | 生成元数据和 Wiki 正文 | 同步检查 | 低 | -| 自动化测试 | `tests/` | `test_wiki_docs.py` | 映射、同步和安全边界 | `unittest discover` | 低 | - -## 两条主要执行路径 - -### Wiki 镜像 - -```text -wiki-docs.json -→ WikiClient 列出并解析页面 -→ 读取 Markdown 与 last_commit.sha -→ 检查本地镜像是否有未提交修改 -→ 写入来源、URL、revision、同步时间 -→ --check 对照正文和 revision -``` - -### 可选任务快照 - -```text -用户或项目专用规则明确要求专项快照 -→ 读取 Wiki 归档模板 -→ 创建 Task-<编号>-<标题> 页面并链接原工单 -→ 按需 export 到 docs/task -``` - -默认任务流程不调用这条路径。单次任务的需求、实现、测试、提交和验收保存在 Gitea 工单；既有归档和导出功能仅用于历史兼容或明确的专项快照。 - -## 修改影响判断 - -| 修改内容 | 通常还要检查 | -|---|---| -| 修改 Agent 工作流 | `README.md`、`CLAUDE.md`、Development-Workflow、工单模板 | -| 修改 Wiki 页面名称 | `wiki-docs.json`、Home 链接、同步测试；必须人工确认 | -| 修改镜像格式 | 解析器、检查器、已有镜像、单元测试 | -| 增加核心文档 | Wiki、显式映射、Home、Harness 必需页面检查 | -| 修改归档字段 | Wiki 归档模板、归档脚本、归档检查和测试 | - -## 不可破坏的边界 - -- 工单管理单次任务，Wiki 管理长期文档，Git 管理代码和版本绑定资料；可选任务快照不是默认事实来源。 -- `docs/` 不是长期文档编辑入口。 -- 同步只允许写入 `docs/` 下的 Markdown。 -- 页面删除、重命名和本地脏镜像不能被静默处理。 -- 凭据不得进入代码、Wiki、工单、日志或镜像。 diff --git a/docs/03-business-rules-and-glossary.md b/docs/03-business-rules-and-glossary.md deleted file mode 100644 index 81e2d17..0000000 --- a/docs/03-business-rules-and-glossary.md +++ /dev/null @@ -1,72 +0,0 @@ - -generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) -wiki_page: Business-Rules-and-Glossary -wiki_url: https://git.ilapage.cn/OPC/dev_harness/wiki/Business-Rules-and-Glossary.- -wiki_revision: 0f860d9e97c0cdc7d2253a3f013d24fd8bd02609 -synchronized_at: 2026-09-02T02:14:01Z - - -# 业务规则与术语 - -## 本页用途 - -解释 DevHarness 中容易混淆的术语、状态和不可破坏的流程规则。新项目复制模板后，应把项目自身的业务术语、状态和关键约束补充到本页。 - -## 核心术语 - -| 术语 | 含义 | 不要误解为 | -|---|---|---| -| Epic | 完整产品目标和长期路线 | 可以直接实施的单个任务 | -| MVP | 第一个可交付范围及集成边界 | 任意里程碑名称 | -| 治理模式 | 项目采用的轻量、标准或高风险流程级别 | 可以覆盖安全底线的开关 | -| 直接实施项 | 轻量模式允许不建单的小范围低风险修改 | 可以扩展为完整需求或高风险修改 | -| 单元任务 | 需要工单时的正式实施单位，可独立测试和回退 | 所有小修改都必须创建的流程记录 | -| 关键原始需求 | 能表达用户目的、场景和限制的少量原话或脱敏摘要 | 完整聊天记录 | -| 正式任务需求 | 用户确认后写入单元工单的目标、非目标、方案和验收标准 | Agent 未确认的理解 | -| 需求变化记录 | 实施期间影响范围或验收的变化、原因及用户确认 | 每一句普通讨论 | -| 事实来源 | 某类信息被正式维护的位置 | 多处内容可以随意覆盖 | -| Wiki 主源 | 长期开发文档首先修改的位置 | 本地 docs 的备份副本 | -| docs 镜像 | 从 Wiki 单向生成的浏览副本 | 可以直接编辑并反向同步的文档 | -| 待验收 | 实现和测试已完成，等待用户确认 | 已完成并可关闭 | -| 未验证部分 | 本次无法真实覆盖的行为 | 可以省略的测试备注 | - -## 工单状态 - -| 状态 | 含义 | 可以进入下一状态的条件 | -|---|---|---| -| 待确认 | 目标或方案仍需用户选择 | 用户明确确认方案 | -| 待实施 | 方案已确认但尚未修改，或真实前置依赖尚未满足 | 前置依赖已满足或明确允许并行，且工作区和范围检查完成 | -| 进行中 | 正在实现、测试或同步文档 | 验收标准逐项检查完成 | -| 阻塞 | 实施过程中出现计划外、当前无法解除的问题 | 阻塞解除并更新工单 | -| 待验收 | 实现、必要测试、提交和最终证据已完成 | 用户明确验收 | -| 已完成 | 用户已验收并完成父任务同步 | 无 | - -## 稳定业务规则 - -- 没有确认方案和单元任务工单，不修改产品行为。 -- 一个单元任务只解决一个可独立验证和回退的问题。 -- 建立后续工单不要求已有工单全部完成；实施前必须检查工单声明的前置依赖。 -- 前置工单未完成且存在实际依赖时保持“待实施”；允许并行时必须写明原因。 -- 需求、接口、数据、安全边界或验收标准变化时先更新工单。 -- 工单正文保存关键原始需求和确认后的任务基线；重要变化、最终证据和验收结论通过评论追加，不保存完整聊天或 Agent 内部推理。 -- 单次任务需求、实现、测试、提交和验收以 Gitea 工单为唯一事实来源；默认不创建 Wiki 任务归档。 -- 长期有效的产品需求和业务规则进入 Wiki；只有长期事实变化时才执行 Wiki 更新和镜像同步，Gitea 工单全文不导出到本地。 -- 用户明确要求专项快照或项目专用规则要求时可以创建 Wiki 任务快照；它不替代原工单，既有归档不删除。 -- 长期文档必须先修改 Wiki，再导出本地镜像。 -- 测试结果必须真实；未执行的验证必须明确记录。 -- 用户未明确验收前，工单保持开启。 -- 初级程序员可以理解和验证低风险修改，但高风险决策仍由 Agent 分析并等待人工确认。 - -## 新项目需要补充什么 - -复制模板后，至少补充： - -- 项目的用户和核心目标； -- 业务名词及容易混淆的概念； -- 主要对象和状态； -- 关键状态流转； -- 必须始终满足的业务规则； -- 数据保留、权限和安全边界； -- 典型输入、输出和失败示例。 - -业务规则必须由项目负责人确认，Agent 可以整理和举例，但不能根据代码自行臆造。 diff --git a/docs/04-local-development-and-verification.md b/docs/04-local-development-and-verification.md deleted file mode 100644 index b3aac3d..0000000 --- a/docs/04-local-development-and-verification.md +++ /dev/null @@ -1,174 +0,0 @@ - -generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) -wiki_page: Local-Development-and-Verification -wiki_url: https://git.ilapage.cn/OPC/dev_harness/wiki/Local-Development-and-Verification.- -wiki_revision: a94b4eaa509f351b77274f007ae882e9e696fc8b -synchronized_at: 2026-09-02T07:20:33Z - - -# 本地开发与验证 - -## 本页用途 - -让维护者能够安装、运行、检查和验证项目。所有命令默认在仓库根目录执行，示例以 Windows PowerShell 为主。 - -## 环境要求 - -| 工具 | 用途 | 检查命令 | -|---|---|---| -| Git | 版本管理和脏文件保护 | `git --version` | -| Python 3 | Harness 脚本和测试 | `python --version` | -| Gitea 连接 | 工单和 Wiki | 浏览仓库或调用 MCP | -| Gitea PAT | 写 Wiki 时使用 | 仅通过 MCP 安全配置或 `GITEA_TOKEN` 提供 | - -不要打印或提交 PAT。 - -## Windows PowerShell 与 UTF-8 - -### Shell 选择 - -- 优先使用当前已经配置的 PowerShell；可选择时优先 PowerShell 7 `pwsh.exe`。 -- 只有 PowerShell 7 不可用或命令明确依赖 Windows PowerShell 5.1 时才使用 `powershell.exe`。 -- 不得仅为设置编码重复启动一层 PowerShell；嵌套进程会增加启动时间、转义复杂度和错误定位成本。 -- 代码搜索仍优先使用代码图工具；非代码文本或图工具不足时优先使用 `rg`，不因本节改用 `Select-String`。 - -### PowerShell 语法与外部命令 - -- Windows 环境默认使用当前 PowerShell 语法，不套用 Bash 的 heredoc、变量、路径、引号或反斜杠转义规则。只有明确调用 Bash、WSL 或 Git Bash，并确认路径与编码边界时，才使用 Bash 专用语法。 -- 不需要变量展开的正则和字符串优先用单引号；单引号字符串内部的单引号写成两个单引号。需要变量展开时才使用双引号。 -- 正则同时包含单双引号或转义复杂时，优先赋值给变量、使用 `rg -e`，或拆成语义等价的简单查询；不得为了避开转义改变 AND/OR 条件或重复执行无关搜索。 - -```powershell -rg -n 'error|warning' docs -$pattern = 'can''t match "value"' -rg -n -e $pattern docs -``` - -PowerShell 不支持 Bash heredoc。需要把多行 Python 送入标准输入时，使用单引号 here-string，避免 PowerShell 展开 Python 中的 dollar sign（`$`）等内容。起始标记后必须立即换行，结束标记必须单独占一行： - -```powershell -@' -print("hello") -'@ | python - -``` - -`foreach`、`if` 等语句块不能裸放在管道左侧；需要管道输出时使用 `$()`、`@()` 或先赋值。普通命令输出无需包装： - -```powershell -@(foreach ($number in 1..3) { $number }) | - Measure-Object -``` - -不要把含 `*` 的搜索路径直接作为 `rg` 路径参数。优先传入真实目录，并用 `-g/--glob` 让 ripgrep 筛选路径： - -```powershell -rg -n -g '*.md' 'PowerShell' docs -``` - -只有确实需要把实体路径列表交给其他命令时，才使用 `Get-ChildItem` 展开并传递 `.FullName`；不要把 `Get-ChildItem -Filter` 设为所有 `rg` 搜索的固定前置。 - -### 文件编码 - -文件解码与控制台输出编码是不同问题。读取 UTF-8 文本时，在命令支持的情况下显式指定编码和字面路径： - -```powershell -Get-Content -LiteralPath "path\to\file.md" -Encoding utf8 -``` - -仓库文件修改仍使用项目规定的编辑工具；不要为了指定编码改用 shell 拼接、重定向或临时写文件。PowerShell 5.1 与 PowerShell 7 对无 BOM UTF-8 和写入默认值存在差异，不能只凭控制台显示判断文件编码。 - -### 控制台与外部命令输出 - -PowerShell 7 默认通常已满足 UTF-8 场景。只有出现真实乱码，或已知宿主/外部程序没有使用 UTF-8 时，才在当前进程设置： - -```powershell -$OutputEncoding = [Console]::OutputEncoding = [System.Text.UTF8Encoding]::new($false) -``` - -确实需要显式启动 PowerShell 7 时使用： - -```powershell -pwsh.exe -NoLogo -NoProfile -NonInteractive -Command '$OutputEncoding = [Console]::OutputEncoding = [System.Text.UTF8Encoding]::new($false); <命令>' -``` - -不要把这个包装应用到每条命令；同一会话中已经生效且环境未变化时不重复设置。 - -### Python 中文输出 - -只有 Python 命令已经出现乱码，或运行宿主已知不是 UTF-8 时，才在当前 PowerShell 进程设置： - -```powershell -$env:PYTHONUTF8 = "1" -$env:PYTHONIOENCODING = "utf-8" -python dev_scripts/harness.py check --strict -``` - -这些变量只影响当前进程及其子进程，不写入仓库或全局用户配置。乱码仍存在时，先判断问题来自文件解码、控制台、管道还是外部程序，再处理首个真实原因。 - -### ExecutionPolicy 边界 - -- `Get-Content`、`rg`、Git、Python 和普通 PowerShell cmdlet 不需要 `-ExecutionPolicy Bypass`。 -- 不得默认添加 `-ExecutionPolicy Bypass`，也不得把它写入所有命令的统一包装。 -- 只有已确认可信的 `.ps1`确实被执行策略阻止、任务范围允许执行且没有更小替代方案时，才可对该次进程使用 Bypass，并在工单记录脚本路径、阻止信息和使用原因。 -- Bypass 只解决执行策略阻止，不解决文件编码、控制台编码、权限或脚本自身错误。 - -## 第一次运行 - -### 1. 检查工作区 - -- 目的：确认没有混入其他任务的修改。 -- 命令：`git status --short --branch` -- 预期：显示当前分支；开始新任务时没有无关文件。 -- 失败检查：确认变更归属，不要擅自重置或覆盖。 - -### 2. 检查 Harness - -- 目的：验证必需文件、项目档案、Wiki 映射和归档结构。 -- 命令：`python dev_scripts/harness.py check --strict` -- 预期：输出“DevHarness 检查通过”。 -- 失败检查：按错误提示检查缺失页面、未填占位符或损坏的镜像头。 - -### 3. 运行测试 - -- 目的：验证同步、路径和安全保护。 -- 命令：`python -m unittest discover -s tests -v` -- 预期：所有测试显示 `ok`。 -- 失败检查：先单独运行失败测试，再查看最近修改的对应脚本。 - -### 4. 对照线上 Wiki - -- 目的：确认本地 docs 是最新镜像。 -- 命令：`python dev_scripts/harness.py sync --check` -- 预期：所有映射显示“一致”。 -- 失败检查：先读取线上页面；确认页面名、revision、网络和 `GITEA_URL`。 - -## 常用调试方式 - -- 只检查 Python 语法：`python -m compileall -q dev_scripts tests`。 -- 查看一个脚本帮助：`python dev_scripts/harness.py sync --help`。 -- 查看未提交差异：`git diff --check` 和 `git diff`。 -- 查看最近提交：`git log -5 --oneline`。 -- 调试失败测试时优先运行单个测试文件，不要先修改多个模块。 - -## 测试数据与日志 - -DevHarness 不使用生产数据，也不需要固定业务测试数据。命令输出是主要诊断信息，不应包含令牌。如果复制到业务项目，应在本节写明： - -- 合成或脱敏测试数据的创建方式； -- 日志路径和日志级别； -- 请求或任务标识如何追踪； -- 禁止使用的数据来源。 - -## 完成修改前 - -依次执行： - -```powershell -python -m unittest discover -s tests -v -python dev_scripts/harness.py check --strict -python dev_scripts/harness.py sync --check -git diff --check -git status --short -``` - -无法执行的命令必须写入工单“未验证部分”。 diff --git a/docs/05-common-changes.md b/docs/05-common-changes.md deleted file mode 100644 index 3c1c975..0000000 --- a/docs/05-common-changes.md +++ /dev/null @@ -1,78 +0,0 @@ - -generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) -wiki_page: Common-Changes -wiki_url: https://git.ilapage.cn/OPC/dev_harness/wiki/Common-Changes.- -wiki_revision: be03ec592df2d491cbc576001f0dda1bbbd39f7e -synchronized_at: 2026-08-24T08:55:46Z - - -# 常见修改指南 - -## 本页用途 - -帮助初级程序员在 Claude/Codex Agent 协助下处理简单 Bug 和小需求。这里说明常见入口、验证方法和停止条件，不代替工单和方案确认。 - -## 风险分级 - -| 等级 | 常见修改 | 处理方式 | -|---|---|---| -| 低风险 | 文案、简单校验、查询条件、独立 UI、小范围回归 Bug | 初级程序员可在 Agent 协助下修改和验证 | -| 中风险 | API、配置、依赖、跨模块逻辑、数据结构 | 由 Agent 实现，程序员理解差异并执行验证 | -| 高风险 | 权限、安全、并发、迁移、支付、删除数据、不可逆操作 | 停止修改，由 Agent 分析并等待人工确认 | - -“代码行数少”不等于低风险。风险等级只决定由谁实施和验证，不改变建单门禁：新功能、缺陷修复、重构及行为变化仍需工单；只有 AGENTS.md 明确列出的非行为修改和纯显示文案豁免可以直接提交。 - -## 修改 Wiki 文案 - -1. 在相关工单确认目标。 -2. 读取线上 Wiki 页面和当前 revision。 -3. 修改线上 Wiki，不直接编辑 `docs/`。 -4. 运行 `python dev_scripts/harness.py sync`。 -5. 运行 `python dev_scripts/harness.py sync --check`。 -6. 审查本地镜像差异并提交。 - -停止条件：页面需要删除、重命名或改变事实源边界。 - -## 增加工单字段 - -1. 阅读 `.gitea/issue_template/task.md` 和 Development-Workflow。 -2. 判断字段是否影响所有任务，避免只为一个任务增加永久字段。 -3. 修改模板和对应流程说明。 -4. 为 Harness 检查增加或调整测试。 -5. 创建一份示例工单草稿检查可读性。 - -停止条件：字段改变权限、审批或关闭条件。 - -## 调整 Harness 检查 - -1. 从 `dev_scripts/harness.py` 的 `run_check()` 开始读。 -2. 新检查应输出具体文件和缺失内容。 -3. 检查结构事实，不声称自动判断文档语义质量。 -4. 在 `tests/` 添加成功和失败用例。 -5. 运行严格检查及全部测试。 - -停止条件：检查会删除、重写文件或依赖生产环境。 - -## 修复 Wiki 同步 Bug - -1. 从 `dev_scripts/wiki_docs.py` 的 `WikiClient`、`parse_mirror` 和 `sync_all` 开始读。 -2. 先编写能复现问题的测试。 -3. 保持 Wiki → docs 单向关系。 -4. 验证中文、路径编码、revision 和脏文件保护。 -5. 使用测试页面验证时，不删除正式页面。 - -停止条件：需要自动删除/重命名页面、覆盖本地未提交修改或输出令牌。 - -## 看懂 Agent 的修改 - -审查时至少回答： - -- 这次解决了哪个工单目标； -- 修改入口和调用路径在哪里； -- 有哪些行为变化； -- 增加或修改了哪些测试； -- 哪些内容没有验证； -- 是否更新了受影响的 Wiki 页面； -- 怎样回退。 - -回答不了时，让 Agent补充说明，不要仅凭“测试通过”验收。 diff --git a/docs/06-troubleshooting.md b/docs/06-troubleshooting.md deleted file mode 100644 index c4e4bcf..0000000 --- a/docs/06-troubleshooting.md +++ /dev/null @@ -1,40 +0,0 @@ - -generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) -wiki_page: Troubleshooting -wiki_url: https://git.ilapage.cn/OPC/dev_harness/wiki/Troubleshooting -wiki_revision: e1a806bb8c6b6c32a4e271c94a9bcaaed36003db -synchronized_at: 2026-08-08T00:58:12Z - - -# 故障排查 - -## 本页用途 - -按“现象 → 原因 → 检查 → 处理”定位 DevHarness 常见问题。处理后如果形成稳定结论，应更新本页；临时过程记录在工单。 - -| 现象 | 常见原因 | 检查方法 | 处理 | -|---|---|---|---| -| `--strict` 提示项目档案未填写 | 新项目仍有占位内容 | 搜索 `<填写` | 先在 Wiki 填写真实内容，再导出镜像 | -| 同步提示镜像有未提交改动 | 有人直接修改 docs，或上次镜像尚未提交 | `git status --short -- docs` | 确认来源；保留人工内容并先更新 Wiki，不要强制覆盖 | -| Wiki 页面不存在 | 页面未创建、标题或映射错误 | 查看 Wiki 页面列表和 `wiki-docs.json` | 修正明确的页面或映射；不要自动删除本地文件 | -| API 路径出现重复 `/api/v1` | `GITEA_URL` 已包含 API 后缀 | 查看非敏感 URL 配置 | 同步器会规范化；新工具也应接受两种写法 | -| 公共仓库读取返回 401/403/404 | 环境令牌失效或属于其他实例 | 不打印令牌；尝试浏览公开页面 | 只读请求可安全降级匿名；写请求必须使用正确 PAT | -| 中文 Wiki 页面读取 404 | `sub_url` 被重复百分号编码 | 查看页面列表返回的 `sub_url` | 保留已有 `%`，不要再次编码 | -| Wiki 页面标题多出 `.-` | Gitea 1.25 的页面规范路径或更新时未显式传标题 | 对照页面 title 和 `sub_url` | 更新中文页面时显式保留原 title；不要猜测路径 | -| `--check` 正文不一致 | Wiki 已更新但镜像未导出，或本地被修改 | 对照 revision 和 Git 差异 | 确认 Wiki 后运行正式同步 | -| 单元测试能过但真实同步失败 | 测试使用模拟数据，网络或 Gitea 行为不同 | 查看工单“未验证部分” | 增加最小真实验证并记录服务端版本 | -| Git 工作区包含无关修改 | 同时存在其他任务或人工工作 | `git status --short` | 保留并隔离无关修改，不重置用户工作 | - -## 排查顺序 - -1. 读取完整错误信息，不只看最后一行。 -2. 检查当前工单、分支和工作区。 -3. 检查项目档案中的真实命令和环境。 -4. 用最小命令复现。 -5. 对照最近提交和 Wiki revision。 -6. 修复后增加回归测试或稳定排错条目。 -7. 无法验证的部分写回工单。 - -## 必须停止的情况 - -出现凭据泄露、数据损坏风险、权限边界变化、不可逆操作或不明来源的工作区改动时，立即停止并说明影响，不继续尝试破坏性修复。 diff --git a/docs/07-new-project-documentation-setup.md b/docs/07-new-project-documentation-setup.md deleted file mode 100644 index 1be4f33..0000000 --- a/docs/07-new-project-documentation-setup.md +++ /dev/null @@ -1,238 +0,0 @@ - -generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) -wiki_page: New-Project-Documentation-Setup -wiki_url: https://git.ilapage.cn/OPC/dev_harness/wiki/New-Project-Documentation-Setup.- -wiki_revision: 3d28f17a2861d3a59256d08f0efba307d441836e -synchronized_at: 2026-09-04T06:13:20Z - - -# 新项目文档初始化 - -## 本页用途 - -从 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. 确定交付对象和文档 - -由项目负责人确认哪些岗位或客户会实际使用、部署、管理、支持、集成或验收产品，并为每类对象确定： - -- 需要完成的工作； -- 所需文档类型； -- 文档可见范围； -- 适用版本、负责人和验证人； -- 不得对外披露的内部信息。 - -按照[交付文档指南](Delivery-Documentation-Guide.-)选择文档，使用[岗位文档模板](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 步确认的受众创建。 - -部署页按需创建，不属于必需核心页面：项目负责人确认存在需要部署的常驻服务时，复制[部署文档模板](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 或负责人； -- 项目采用哪个建设基线，为什么适合二次开发，或者为什么选择从零开发； -- 采用开源基线时，上游仓库、基线版本、许可证、定制范围和升级策略是什么； -- 项目包含哪些子项目和独立交付单元，各自怎样构建、测试和发布； -- 跨子项目共享什么接口或契约，其唯一事实来源在哪里； -- 项目需要向哪些岗位交付什么文档，以及哪些内容不能对外提供。 - -回答不了的问题应继续补充主题文档，而不是堆入任务归档。 diff --git a/docs/08-existing-project-adoption.md b/docs/08-existing-project-adoption.md deleted file mode 100644 index c037c4d..0000000 --- a/docs/08-existing-project-adoption.md +++ /dev/null @@ -1,235 +0,0 @@ - -generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) -wiki_page: Existing-Project-Adoption-Guide -wiki_url: https://git.ilapage.cn/OPC/dev_harness/wiki/Existing-Project-Adoption-Guide.- -wiki_revision: a3c9c0892eeeafeec162a50c1cdfbc15d003897d -synchronized_at: 2026-08-25T00:40:47Z - - -# 已有项目接入 DevHarness 指南 - -## 本页用途 - -本页用于把 DevHarness 的文档模板和开发流程增量接入已经存在的项目。已有项目通常已经有代码、规则、文档、工单、Wiki、Git 历史和未完成工作，因此接入目标是补齐必要能力，不是把项目重置成 DevHarness 模板副本。 - -接入必须先只读盘点、确认差异方案，再建立单元任务工单实施。未经确认不得覆盖、删除、重命名或批量迁移已有内容。 - -## 与新项目初始化的区别 - -| 场景 | 新项目初始化 | 已有项目接入 | -|---|---|---| -| 项目事实 | 从代码骨架和负责人确认开始建立 | 优先保留并核对已有事实 | -| 规则文件 | 可以从模板建立第一版 | 必须合并已有规则，不能直接覆盖 | -| 文档 | 创建核心主题页 | 逐页判断保留、迁移、合并或停止维护 | -| 工单和 Wiki | 新建并开始使用 | 先检查已有工单、Wiki 和状态体系 | -| Git 历史 | 允许一次引导提交 | 保留全部历史，不使用引导提交例外 | -| 任务证据 | Gitea 工单；任务快照仅显式按需创建 | 保留已有工单；不复制 DevHarness 或其他项目的历史归档 | -| 接入方式 | 一次建立最小骨架 | 分阶段增量接入并逐步验收 | - -从模板创建全新仓库时使用[新项目文档初始化](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 基线升级到 -。 - -先只读比较来源仓库中“旧基线..目标基线”的 Harness 变化和当前项目 -适配，列出直接采用、按项目改写、冲突待确认和不采用的内容，以及 -风险、回退、验证和文档影响。不要覆盖项目专用规则、业务文档、Git -历史或无关改动，不复制 DevHarness 工单和任务归档。方案确认后在 -当前项目建单并实施；长期文档先改当前项目 Wiki，再同步本地镜像。 -工单保持待验收，验收通过后确认 Project-Profile 已记录新基线。 -``` - -路径和目标完整提交哈希必须替换为真实值；目标提交未明确时只分析，不实施。 - -## 冲突处理和停止条件 - -出现以下情况时停止实施并请求负责人确认： - -- 现有规则与 DevHarness 的安全、权限、事实来源或验收规则冲突； -- 无法判断某份文档应该保留、迁移、合并还是停止维护； -- 需要删除、重命名 Wiki 页面、覆盖已有文件或清理历史归档； -- 需要改变接口、数据库、权限、部署、发布或其他产品行为； -- 工作区存在可能与接入文件重叠的未知修改； -- Gitea、Wiki、凭据或远端权限不可用； -- 真实命令、环境或业务规则无法从证据或负责人确认。 - -相邻问题最多提示或另建工单，不混入接入任务。 - -## 可复制 Agent 指令 - -### 只分析 - -```text -请把 的文档模板和开发流程接入当前已有项目。 - -先只分析，不修改文件、工单或 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 页面删除、重命名、历史清理或事实来源反向切换不是普通回退，必须另行建单并等待确认。 diff --git a/docs/09-product-requirements-overview.md b/docs/09-product-requirements-overview.md deleted file mode 100644 index f7d741d..0000000 --- a/docs/09-product-requirements-overview.md +++ /dev/null @@ -1,128 +0,0 @@ - -generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) -wiki_page: Product-Requirements-Overview -wiki_url: https://git.ilapage.cn/OPC/dev_harness/wiki/Product-Requirements-Overview.- -wiki_revision: 60a169e4e8e3c396c4c4c35544be48a17548d19c -synchronized_at: 2026-09-02T02:14:07Z - - -# 产品需求总览 - -## 本页用途 - -本页是产品需求的统一导航入口，帮助项目负责人、Agent 和初级维护者快速回答：项目有哪些长期需求、当前状态是什么、详细规则和实施证据在哪里。 - -本页只保存稳定摘要、状态和链接，不复制完整工单、主题文档或聊天内容。需求详情仍在对应事实来源维护，避免形成两份不一致的正式需求。 - -## 事实来源边界 - -| 信息 | 唯一事实来源 | 本页怎样记录 | -|---|---|---| -| 项目目标、用户、范围和技术基线 | Project-Profile | 链接和一句话摘要 | -| 长期功能需求、业务规则和系统边界 | 对应 Wiki 主题页 | 需求领域和详情链接 | -| 单次实现范围、变化和验收标准 | Gitea 单元任务工单 | 工单编号和当前状态 | -| 单次任务方案、实现、测试、遗留问题和验收 | Gitea 单元任务工单 | 工单链接；专项 Wiki 快照仅按需附加 | -| 与版本绑定的原型、设计图或交互稿 | Git 中的 `design/` 或 `prototypes/` | 路径、版本和确认状态 | -| 外部原型 | 原型平台 | 链接、版本或确认日期；重要版本保留可追溯快照 | - -不保存完整聊天记录、Agent 内部推理、密码、令牌、个人数据或生产数据。 - -## 当前需求索引 - -| 需求领域 | 用户与场景 | 状态 | 版本 / MVP | 详细说明 | 实施工单 | 原型 | 验收入口 | -|---|---|---|---|---|---|---|---| -| 文档事实来源与需求追溯 | 负责人和 Agent 需要从需求到实现、验收可追溯且不重复归档 | 已交付 | 模板核心 | [开发工作流](Development-Workflow.-) | [#1](https://git.ilapage.cn/OPC/dev_harness/issues/1)、[#10](https://git.ilapage.cn/OPC/dev_harness/issues/10)、[#14](https://git.ilapage.cn/OPC/dev_harness/issues/14)、[#20](https://git.ilapage.cn/OPC/dev_harness/issues/20)、[#25](https://git.ilapage.cn/OPC/dev_harness/issues/25)、[#26](https://git.ilapage.cn/OPC/dev_harness/issues/26) | 无（流程文档） | [#25](https://git.ilapage.cn/OPC/dev_harness/issues/25)、[#26](https://git.ilapage.cn/OPC/dev_harness/issues/26)、[迁移边界快照](Task-25-单人任务事实来源与工程基线分级.-)；旧 Wiki 归档保留为历史证据 | -| 初级维护者文档 | 初级程序员需要理解项目并处理简单修改 | 已交付 | 模板核心 | [项目档案](Project-Profile.-)、[代码地图](Architecture-and-Code-Map.-)、[常见修改](Common-Changes.-) | [#2](https://git.ilapage.cn/OPC/dev_harness/issues/2)、[#3](https://git.ilapage.cn/OPC/dev_harness/issues/3) | 无（流程文档） | [#2 归档](Task-2-Junior-Maintainer-Docs)、[#3 归档](Task-3-Dev-Scripts-Rename) | -| Agent 范围、效率和 Claude 协作 | Agent 按确认范围实施并选择合适模型 | 已交付 | 模板核心 | [开发工作流](Development-Workflow.-)、仓库 `AGENTS.md` 和 `CLAUDE.md` | [#4](https://git.ilapage.cn/OPC/dev_harness/issues/4)–[#9](https://git.ilapage.cn/OPC/dev_harness/issues/9)、[#19](https://git.ilapage.cn/OPC/dev_harness/issues/19)、[#21](https://git.ilapage.cn/OPC/dev_harness/issues/21)、[#27](https://git.ilapage.cn/OPC/dev_harness/issues/27) | 无（流程文档） | 对应 `Task-4` 至 `Task-9` Wiki 归档；[#19 归档](Task-19-UI原型确认与文字修改双门禁)、[#21 归档](Task-21-Quant-UX原型本地HTML审核快照)、[#27](https://git.ilapage.cn/OPC/dev_harness/issues/27) | -| 交付文档 | 其他岗位和客户需要与版本匹配的使用、部署或支持说明 | 已交付 | 模板核心 | [交付文档指南](Delivery-Documentation-Guide.-)、[岗位文档模板](Audience-Document-Template.-) | [#11](https://git.ilapage.cn/OPC/dev_harness/issues/11) | 无（文档模板） | [#11 归档](Task-11-交付文档指南与岗位文档模板) | -| 已有项目和多交付单元接入 | 维护者需要在保留历史和项目规则的前提下接入 DevHarness | 已交付 | 模板核心 | [已有项目接入指南](Existing-Project-Adoption-Guide.-) | [#12](https://git.ilapage.cn/OPC/dev_harness/issues/12)、[#13](https://git.ilapage.cn/OPC/dev_harness/issues/13) | 无（流程文档） | [#12 归档](Task-12-已有项目接入DevHarness指南)、[#13 归档](Task-13-多子项目与独立交付单元) | -| 建设基线与后续升级 | 新项目和已有项目需要选择、记录并升级可复现的 DevHarness 或开源基线 | 已交付 | 模板核心 | [新项目文档初始化](New-Project-Documentation-Setup.-)、[已有项目接入指南](Existing-Project-Adoption-Guide.-) | [#15](https://git.ilapage.cn/OPC/dev_harness/issues/15)、[#16](https://git.ilapage.cn/OPC/dev_harness/issues/16) | 无（流程文档） | [#15 归档](Task-15-开源建设基线评估)、[#16 归档](Task-16-DevHarness-后续升级与基线记录) | -| 产品需求与原型索引 | 负责人、Agent 和初级维护者需要从一个入口找到需求和证据 | 已交付 | 模板核心 | 本页 | [#18](https://git.ilapage.cn/OPC/dev_harness/issues/18) | 无（当前任务没有产品界面） | [#18 归档](Task-18-产品需求总览与原型索引) | -| 服务部署文档 | 有常驻服务的项目需要可复现的部署、运维和回滚说明 | 已交付 | 模板核心 | [部署文档模板](Deployment-Template.-) | [#24](https://git.ilapage.cn/OPC/dev_harness/issues/24) | 无（文档模板） | [#24 归档](Task-24-部署文档模板与位置约定) | - -基础设施迁移、一次性排错和普通小缺陷不作为长期产品需求单独占一行；只有它们改变长期能力、边界或使用方式时，才更新对应需求领域。 - -## 登记规则 - -每一行代表一项长期需求或稳定需求领域，不代表一个普通 Bug。至少填写： - -- 清楚、稳定的需求名称； -- 谁在什么场景下需要它； -- 当前状态和所属版本、MVP 或发布范围； -- 唯一的详细 Wiki 页面； -- 当前或主要实施工单； -- 原型状态或明确写“无”； -- 已交付时的 Gitea 工单验收入口。 - -需求正文、接口细节、业务规则和验收标准只在各自事实来源修改。本页使用一至两句话摘要并链接过去，不复制大段内容。 - -## 原型与设计资产 - -### 原型门禁 - -先选择最低成本、足以确认需求的设计证据： - -| 修改类型 | 轻量模式 | 最低设计证据 | -|---|---|---| -| 文案、局部样式或布局、复用现有规范的组件调整 | 可直接实施 | 现有界面、一句话或按需标注截图；不制作完整原型 | -| 预期行为明确的小 Bug | 可直接实施 | 复现步骤、原设计或已有验收证据 | -| 不改变接口、数据结构、权限和安全边界的单模块低风险调整 | 可直接实施 | 明确目标和最小验证方法 | -| 完整独立需求、新页面或跨模块功能 | 建单 | 先用文字确认；有明显交互不确定性、返工成本显著或用户要求时才制作可审阅原型 | -| API、数据结构、权限、安全、迁移或其他中高风险任务 | 建单并按风险升级 | 必要的架构、数据、权限、状态、回退或验证设计；不强制无意义的 UI 原型 | - -标准模式对新功能、缺陷修复、重构和用户可感知行为变化建单；新页面、独立用户功能和重大交互使用可审阅原型。高风险模式的正式行为变化必须建单并等待人工确认。 - -原型只在足以降低真实不确定性时建立。已确认设计发生影响页面结构、主要流程、状态、权限、异常处理或验收结果的变化时才重新确认；轻量直接实施项一旦扩展为完整需求或中高风险变化，先建单再继续。 - -### 线上原型与按需 HTML 快照 - -需要完整原型的新页面、独立用户功能、重大交互或导航变化，默认直接通过 Quant-UX 或等效设计工具的线上版本审核。可编辑设计源仍以原设计工具为准，工单记录可访问链接、版本/revision、复制版本或确认日期、审核版本识别方式、确认人、确认时间和覆盖范围。 - -线上链接无法访问或无法区分审核版本时停止审核，等待用户确认等效方案；不能为了节省时间把不稳定链接直接当作已确认原型。页面结构、流程、状态、权限、异常处理或验收结果变化时更新线上版本并重新确认。 - -只有用户明确要求 `导出原型 #N`、`导出全部原型`，或项目专用规则要求离线交付时，才把确认版本导出到 `prototypes/<工单号>/<版本>/index.html`。资源使用相对路径，导出后检查入口、主要交互和资源完整性；已确认快照不得原位覆盖，新版本使用新目录。导出不自动提交，也不顺带扩大到未请求的原型。 - -设计工具无法生成用户明确要求的可用 HTML 时，工单记录限制并停止该导出或离线交付，等待用户确认等效方案；只要线上原型仍可访问且版本明确，不因此阻塞线上审核。已有本地快照继续作为历史审核证据，不反向替代可编辑设计源。 - -### 原型确认记录 - -原型或替代设计证据至少记录线上链接、访问检查、版本/revision、复制版本或确认日期、审核版本识别方式、状态、确认人、确认时间和覆盖范围。只有显式导出时才记录本地路径、版本和资源检查结果。没有 UI 原型时，记录采用的技术设计或无需原型的原因。 - -- 与代码版本绑定的图片、HTML 交互稿和设计源文件放入 Git 的 `design/` 或 `prototypes/`，不要手工放入 Wiki 镜像目录 `docs/`。 -- 外部 Quant-UX、Figma 等原型记录可访问链接、审核版本识别方式、负责人和适用需求；只有用户或项目专用规则明确要求时才保存本地快照。 -- 原型必须标记“草稿、已确认、已废弃”之一。草稿不能作为正式实现依据；已废弃原型保留状态和替代入口，不让 Agent 误用。 -- 原型只表达界面和交互意图，不能代替文字业务规则、安全边界、异常处理和验收标准。 -- 没有原型时写“无”和原因，不创建空图片、空目录或占位原型。 -- 原型包含账号、个人信息或生产数据时必须先脱敏；凭据不得进入原型或截图。 - -## 状态规则 - -需求状态使用：待确认、已确认、开发中、待验收、已交付、已停止。 - -- 方案未确认时为“待确认”；用户确认后才能进入“已确认”。 -- 开始执行单元任务后为“开发中”；实现完成并等待用户确认时为“待验收”。 -- 用户明确验收后改为“已交付”。 -- 需求取消或被替代时改为“已停止”，并链接原因和替代需求，不删除历史记录。 -- 一个需求领域包含多个任务时，以尚未完成的关键任务决定状态，并在状态中简短说明。 - -## 更新时机 - -以下情况必须更新本页： - -1. 用户确认新的长期产品需求或新需求领域； -2. 需求进入开发、待验收、已交付或已停止； -3. 需求的正式 Wiki、主要工单、原型或验收入口变化； -4. 原型从草稿变为已确认或已废弃； -5. MVP、版本范围或用户场景发生变化。 - -普通内部重构、小缺陷和不改变长期能力的任务只保留在工单，不必进入本页。 - -## 最小验收清单 - -- [ ] 新成员能从本页找到每项长期需求的详细说明。 -- [ ] 状态与相关 Gitea 工单一致。 -- [ ] 每项已交付需求具有验收入口。 -- [ ] 原型具有路径或链接、版本和确认状态，或者明确写“无”。 -- [ ] 本页没有复制完整工单或主题文档。 -- [ ] 草稿原型没有被描述为正式需求。 -- [ ] 不包含凭据、个人数据或生产数据。 diff --git a/docs/README.md b/docs/README.md index e8c1626..3692832 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,98 +1,33 @@ - -generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) -wiki_page: Home -wiki_url: https://git.ilapage.cn/OPC/dev_harness/wiki/Home -wiki_revision: e78a0eb55ce09d400e5e54f17ae96cc43c8694fc -synchronized_at: 2026-08-25T00:40:23Z - +# LexGo 文档入口 -# DevHarness 文档中心 - -DevHarness 是一个以 Gitea 工单管理开发任务、以 Wiki 管理长期开发文档、以 Git 记录代码变更的 AI 辅助开发模板。目标是让初级程序员能够理解项目、运行验证，并在 Claude/Codex Agent 协助下处理简单 Bug 和需求。 +状态：2026-09-10，本地文档准备完成后仍需发布至确认的 Gitea 仓库；本页不是 Wiki 镜像。 ## 第一次阅读 -建议按以下顺序，用 10～20 分钟建立整体认识： - -1. [项目档案](Project-Profile.-)：项目目标、环境、命令和目录边界。 -2. [产品需求总览](Product-Requirements-Overview.-)：长期需求、状态、原型和验收入口。 -3. [架构与代码地图](Architecture-and-Code-Map.-)：功能从哪里开始读、测试在哪里。 -4. [业务规则与术语](Business-Rules-and-Glossary.-)：重要名词、状态和不能破坏的规则。 -5. [本地开发与验证](Local-Development-and-Verification.-)：怎样运行、测试和排错。 -6. [常见修改指南](Common-Changes.-)：简单修改的步骤和停止条件。 -7. [故障排查](Troubleshooting)：遇到错误时按什么顺序检查。 -8. [开发工作流](Development-Workflow.-)：完整建单、实施、验收和可选快照流程。 - -从模板创建新项目时先阅读[新项目文档初始化](New-Project-Documentation-Setup.-)；向已有项目增量接入本流程时阅读[已有项目接入 DevHarness 指南](Existing-Project-Adoption-Guide.-)。需要为客户或其他岗位准备说明时，阅读[交付文档指南](Delivery-Documentation-Guide.-)，再按需使用[岗位文档模板](Audience-Document-Template.-)。 +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)。 ## 五分钟开始 -在仓库根目录执行： - -```powershell -git status --short --branch -python dev_scripts/harness.py check --strict -python -m unittest discover -s tests -v -python dev_scripts/harness.py sync --check -``` - -预期结果： - -- 工作区没有不属于当前任务的修改； -- Harness 输出“DevHarness 检查通过”； -- 所有单元测试通过； -- 所有 Wiki 映射显示“一致”。 - -如果失败，先看[故障排查](Troubleshooting)，不要直接重置工作区或覆盖本地文档。 +先阅读项目档案的待决策项，再按工作量估算查看 M0 风险验证。当前没有产品启动命令。工具命令和预期见开发验证页。线上初始化步骤见[初始化记录](harness-drafts/07-new-project-documentation-setup.md)。 ## 简单修改从哪里开始 -| 想做什么 | 先读哪里 | 主要验证 | -|---|---|---| -| 修改文档 | 对应 Wiki 页面、Common-Changes | Wiki 同步检查 | -| 查看或更新产品需求 | Product-Requirements-Overview、对应主题 Wiki 和工单 | 状态、链接和事实来源核对 | -| 接入已有项目 | Existing-Project-Adoption-Guide | 只读盘点、差异确认和分阶段验证 | -| 准备交付文档 | Delivery-Documentation-Guide、Audience-Document-Template | 目标岗位验证和 Wiki 同步检查 | -| 调整工单字段 | `.gitea/issue_template/`、Development-Workflow | Harness 严格检查 | -| 修改同步行为 | `dev_scripts/wiki_docs.py`、Architecture-and-Code-Map | 单元测试和真实 Wiki 检查 | -| 增加结构检查 | `dev_scripts/harness.py` | 成功与失败测试 | -| 排查运行错误 | Troubleshooting、项目档案 | 最小复现命令 | - -权限、安全、并发、迁移、支付、删除数据或不可逆操作不属于简单修改，必须停止并交给 Agent 分析、等待人工确认。 +本次新增文档尚为草稿，可在 `harness-drafts/` 直接修订。原有调研文件保留为证据材料；形成批准的方案后用需求总览关联，不默默覆写历史建议。正式 Wiki 初始化后，从线上主题页修改再单向同步。 ## 事实来源 -| 信息 | 事实来源 | +| 资料 | 使用方式 | |---|---| -| 任务状态、讨论、阻塞、验收过程 | Gitea 工单 | -| 长期产品需求的统一导航和状态 | Gitea Wiki 的 Product-Requirements-Overview | -| 架构、业务规则、开发规范、操作手册和交付文档 | Gitea Wiki | -| 源码和与特定代码版本强绑定的文档 | Git 仓库 | -| 核心长期文档的离线浏览副本 | Git 仓库中的 `docs/` Wiki 镜像 | -| 单次任务需求、实现、测试和验收 | Gitea 工单；专项 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) | 按实际受众准备文档，不预建空白手册 | -本地 `docs/` 不是编辑入口。长期文档必须先修改 Wiki，读取确认后再导出镜像。 - -## 项目入口 - -- [Gitea 工单](https://git.ilapage.cn/OPC/dev_harness/issues) -- [产品需求总览](Product-Requirements-Overview.-) -- [代码仓库](https://git.ilapage.cn/OPC/dev_harness) -- [已有项目接入 DevHarness 指南](Existing-Project-Adoption-Guide.-) -- [交付文档指南](Delivery-Documentation-Guide.-) -- [岗位文档模板](Audience-Document-Template.-) -- [可选任务归档模板（兼容）](Task-Archive-Template.-) - -## 同步原则 - -```text -修改 Wiki → 读取确认 → 导出 docs → 校验差异 → 提交镜像 -``` - -- 核心页面和本地路径通过仓库中的 `wiki-docs.json` 显式映射；普通同步不处理任务归档。 -- 默认不创建任务归档；只有用户明确要求专项快照或项目专用规则要求时，才创建 Wiki 归档并按需导出到 `docs/task/`。 -- 镜像头记录来源页面、Wiki revision 和同步时间。 -- 已映射镜像存在未提交修改时同步必须停止。 -- 页面删除、重命名和映射变更必须人工确认。 -- 长期事实发生变化而核心 Wiki 或必要同步失败时，相关任务不能标记为完成；没有长期文档变化时不运行 Wiki 同步，未请求可选归档不阻止任务完成。 -- 凭据、个人数据和生产数据不得进入 Wiki 或镜像。 +当前事实是上述本地资料和文件检查。产品 Git commit、远端、运行和验收证据尚不存在或未确认；不使用 DevHarness 的 commit 代替产品 commit。 diff --git a/docs/delivery/README.md b/docs/delivery/README.md deleted file mode 100644 index 48508d8..0000000 --- a/docs/delivery/README.md +++ /dev/null @@ -1,80 +0,0 @@ - -generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) -wiki_page: Delivery-Documentation-Guide -wiki_url: https://git.ilapage.cn/OPC/dev_harness/wiki/Delivery-Documentation-Guide.- -wiki_revision: d9de4f8d8abc40630069c67948ca2a5086f90e70 -synchronized_at: 2026-08-10T06:23:38Z - - -# 交付文档指南 - -## 本页用途 - -本页规定项目开发完成后，怎样为客户、最终用户和其他岗位选择、编写、验证及维护交付文档。交付文档面向实际使用产品的人，不替代开发工作流、架构说明和任务归档。 - -最小原则：先确认交付对象，只创建对方完成工作确实需要的文档，不预建空白手册。 - -## 什么时候需要交付文档 - -出现以下任一情况时，应在单元任务工单中评估并更新交付文档： - -- 新增或改变用户可见功能、操作步骤、界面、权限或限制； -- 改变安装、配置、部署、备份、恢复、监控或升级方法； -- 改变外部 API、数据格式、集成条件或兼容范围； -- 改变常见故障的识别、处理或支持方式； -- 发布新版本或交付客户验收。 - -纯内部重构只有在外部行为、操作方式、配置和支持边界均未改变时，才可选择“无交付文档影响”并说明原因。 - -## 受众与文档选择 - -| 交付对象 | 典型文档 | 需要回答的问题 | -|---|---|---| -| 最终用户 | 用户使用说明 | 怎样完成日常操作，失败后怎么办 | -| 管理员 | 管理员指南 | 怎样配置用户、权限和系统参数 | -| 运维人员 | 部署与运维指南 | 怎样安装、启停、监控、备份和恢复 | -| 客服或一线支持 | 支持与排错指南 | 怎样识别问题、收集信息和升级处理 | -| 集成人员 | 接口与集成指南 | 怎样认证、调用接口和处理兼容性 | -| 验收或项目负责人 | 发布、升级与验收说明 | 本次交付了什么，怎样验证和回退 | - -一个项目只选择实际存在的交付对象。多个岗位需要相同内容时可共享一份文档，但必须明确各自可以执行的操作和权限边界。 - -## 内部文档与交付文档边界 - -交付文档可以包含用户完成工作所需的产品地址、公开接口、配置项、操作步骤、结果、限制和支持渠道。 - -面向客户或公开的文档不得包含： - -- 内部工单链接、聊天记录、内部决策过程或任务归档； -- 内部网络地址、仓库路径、无必要的源码模块名和调试细节； -- 密码、令牌、Cookie、私钥、个人数据或生产数据； -- 未经确认的安全实现、漏洞细节或仅供内部使用的恢复手段； -- 未承诺的路线图、期限和功能。 - -交付前必须检查模板中的“可见范围”。同一主题同时存在内部版和客户版时，应分别维护并明确名称，不能依靠读者自行忽略内部内容。 - -## 编写和维护流程 - -1. 在项目初始化或需求确认时识别交付对象、可见范围和所需文档。 -2. 使用[岗位文档模板](Audience-Document-Template.-)按需创建文档，不创建没有明确读者的空页面。 -3. 单元任务在工单“交付文档影响”中选择无影响并说明原因，或列出需要更新的页面和受众。 -4. 功能、配置或流程改变时，代码与对应交付文档在同一任务中更新。 -5. 由熟悉该岗位但未参与实现的人按文档执行关键步骤；不能验证的环境和步骤必须明确标注。 -6. 发布或交付前确认适用版本、最后验证日期、负责人、已知限制和支持渠道。 -7. 长期维护仍遵循 Wiki-first：先修改 Wiki、读取确认，再导出本地 `docs/` 镜像。 - -具体项目创建的岗位文档应增加到 `wiki-docs.json` 的显式映射中。本模板自身的指南和模板镜像位于 `docs/delivery/`。 - -## 最小验收清单 - -- [ ] 文档有明确受众、适用版本、可见范围和负责人。 -- [ ] 前置条件、操作步骤和预期结果完整且可以对应。 -- [ ] 常见失败、恢复方法、安全提示和已知限制已说明。 -- [ ] 关键步骤由目标岗位视角验证，或明确记录未验证项。 -- [ ] 外部版本不含内部链接、敏感数据和无关实现细节。 -- [ ] 本次功能变化涉及的交付文档已更新并与版本一致。 -- [ ] Wiki 已读取确认，本地镜像检查一致。 - -## 不在本页解决的内容 - -开发任务怎样建单、实施和归档见[开发工作流](Development-Workflow.-)；代码结构和维护入口见[架构与代码地图](Architecture-and-Code-Map.-)。本页不规定市场宣传、合同、法务或商务承诺。 diff --git a/docs/delivery/audience-document-template.md b/docs/delivery/audience-document-template.md deleted file mode 100644 index 59e41bf..0000000 --- a/docs/delivery/audience-document-template.md +++ /dev/null @@ -1,96 +0,0 @@ - -generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) -wiki_page: Audience-Document-Template -wiki_url: https://git.ilapage.cn/OPC/dev_harness/wiki/Audience-Document-Template.- -wiki_revision: 7a8f38df566fe639094497c9692e0559c9c080e6 -synchronized_at: 2026-08-10T06:23:41Z - - -# 岗位文档模板 - -> 使用说明：复制本模板创建具体岗位文档，删除说明性文字并填写真实内容。没有明确受众时不要创建文档；不得保留“待填写”后直接交付。 - -## 文档信息 - -| 字段 | 内容 | -|---|---| -| 文档名称 | | -| 适用对象 | 最终用户 / 管理员 / 运维 / 客服 / 集成人员 / 验收人员 / 其他 | -| 适用版本 | | -| 最后验证日期 | YYYY-MM-DD | -| 负责人 | | -| 可见范围 | 内部 / 指定客户 / 公开 | -| 相关产品或模块 | | - -## 目的与适用范围 - -说明读者完成什么工作，以及本文包含和不包含什么。用岗位语言描述结果，不复制内部需求分析。 - -## 前置条件 - -- 所需权限： -- 所需环境或设备： -- 已完成的准备： -- 需要提前获得的信息： - -不得在这里填写真实密码、令牌、个人数据或生产数据。 - -## 操作步骤 - -### 任务一：<明确的操作目标> - -1. <执行动作> -2. <执行动作> -3. <执行动作> - -**预期结果**：<读者可以观察到的成功结果> - -**失败时**：<先检查什么；何时停止并联系支持> - -每个独立任务重复以上结构。命令和界面名称应与适用版本一致；危险或不可逆操作必须在执行前给出醒目警告、影响和回退条件。 - -## 常见错误与恢复 - -| 现象或错误信息 | 可能原因 | 处理步骤 | 何时升级 | -|---|---|---|---| -| | | | | - -只记录经过确认的原因和恢复方法。不要让外部读者执行内部调试、绕过权限或可能扩大损失的操作。 - -## 安全与权限 - -- 本岗位允许执行的操作： -- 明确禁止或需要审批的操作： -- 敏感信息处理规则： -- 数据、日志和截图脱敏要求： -- 删除、发布、迁移或其他高风险操作的确认要求： - -## 已知限制 - -- 支持的环境和版本： -- 当前不支持的场景： -- 兼容性限制： -- 未验证的环境或步骤： - -## 支持与升级处理 - -- 支持渠道： -- 服务时间或响应约定： -- 联系支持前需要收集的信息： -- 不得提交的信息： -- 需要升级到下一岗位或负责人的条件： - -## 版本记录 - -| 日期 | 适用版本 | 变更内容 | 验证人 | -|---|---|---|---| -| | | | | - -## 交付前检查 - -- [ ] 目标岗位能够理解术语和步骤。 -- [ ] 前置条件、步骤与预期结果一一对应。 -- [ ] 关键流程已按目标岗位视角验证。 -- [ ] 常见错误、恢复方法和升级条件清楚。 -- [ ] 没有内部工单、内部地址、敏感数据或无关源码细节。 -- [ ] 适用版本、最后验证日期、负责人和可见范围已填写。 diff --git a/docs/linguacafe-go-analysis.md b/docs/linguacafe-go-analysis.md new file mode 100644 index 0000000..0709dfe --- /dev/null +++ b/docs/linguacafe-go-analysis.md @@ -0,0 +1,215 @@ +# LinguaCafe 的 Go 复刻与框架选型分析 + +日期：2026-09-10。本文是调研建议，尚未开始应用开发。需求与上游固定版本见 [需求提取](linguacafe-requirements.md)。默认目标是可自托管、可继续二次开发的 Web 应用；未假定要做付费 SaaS、原生手机应用或大型多租户平台。 + +## 1. 结论 + +Go 适合实现账号、内容库、词汇状态、复习调度、词典检索、任务处理和系统管理。真正需要投入的部分是阅读器交互、多语言文本处理，以及学习数据的一致性；更换 Web 框架不能替代这些工作。 + +推荐采用 **Go 模块化单体 + Vue 3 + PostgreSQL + 独立 Python NLP 服务**。优先快速二次开发管理功能时，首选评估 **gin-vue-admin** 作为基座；优先控制依赖、维护清晰架构时，使用 **Gin + GORM + Vue 3 + Element Plus** 自建项目。 + +**用户端和管理端都需要，但不必部署两套系统。** 初期一个前端工程划分学习布局与管理布局，一个 Go 服务提供不同权限的 API 即可。只有明确的独立团队、部署节奏或安全边界要求出现后，再拆前端应用。 + +“Go 复刻”建议理解为主要业务后端使用 Go。若要求包括语言处理在内全部使用 Go，可以做，但应缩小首批语言范围，并接受额外的 NLP 适配和质量验证成本。 + +上述推荐为针对本项目的工程判断，并非上游或框架官方推荐。 + +## 2. 原版技术结构与可复用程度 + +| 层 | 本次源码确认的技术 | Go 版处理方式 | +| --- | --- | --- | +| Web 后端 | PHP 8.2 约束、Laravel 11、Horizon、Reverb 等 | 业务能力迁移到 Go，不逐控制器机械翻译 | +| 前端 | Vue 2、Vue Router 3、Vuex 3、Vuetify 2、Laravel Mix | 阅读交互可参考；推荐用 Vue 3 重建，不假定组件直接兼容 | +| 数据 | MySQL 8、文件存储 | 新项目默认 PostgreSQL；迁移保真优先也可选 MySQL | +| 后台处理 | Redis、Laravel 队列、章节处理任务和事件通知 | Go worker 和持久任务；最初可用轮询通知进度 | +| NLP/导入 | Python Bottle、spaCy、pykakasi、pinyin、EbookLib、字幕和网页解析库 | 保留服务边界；逐项选择保留、替换或重写 | +| 部署 | Docker Compose，多个容器 | Go API/worker、数据库、NLP；选 Asynq 时增加 Redis | + +证据：[composer.json](https://github.com/simjanos-dev/LinguaCafe/blob/c1ea298ce40c65b9dd33e9b26fd2e52fae66f2c8/composer.json)、[package.json](https://github.com/simjanos-dev/LinguaCafe/blob/c1ea298ce40c65b9dd33e9b26fd2e52fae66f2c8/package.json)、[Compose](https://github.com/simjanos-dev/LinguaCafe/blob/c1ea298ce40c65b9dd33e9b26fd2e52fae66f2c8/docker-compose.yml)、[tokenizer.py](https://github.com/simjanos-dev/LinguaCafe/blob/c1ea298ce40c65b9dd33e9b26fd2e52fae66f2c8/tools/tokenizer.py)。这里列的是清单约束，不是已安装依赖版本。 + +Go 版减少 PHP 运行环境，但只要保留数据库、任务系统和语言模型，就不是“一个可执行文件搞定全部部署”。NLP 模型依然可能是主要内存开销；不能保证仅更换语言就降低整体内存或支持所有 ARM 设备。 + +## 3. 用户区与管理区的具体划分 + +上游管理区已有七类页面，且 Setup 手册描述了不完整的多用户支持，详见需求文档。这里不是为复刻凭空新增一个企业后台。 + +| 能力 | 学习者 | 管理员 | +| --- | --- | --- | +| 私有书籍、章节、词汇、复习、目标 | 管理自己的数据 | 也可作为学习者使用；不默认浏览他人正文 | +| 密码、主题、阅读习惯 | 管理自己的设置 | 管理自己的设置 | +| 词典查询 | 使用已开放的词典 | 安装和配置共享词典 | +| 语言 | 选择可用语言 | 安装模型、管理语言能力 | +| 字体 | 选择可用字体 | 上传并配置适用语言 | +| 外部服务 | 使用授权能力；个人集成独立配置 | 配置系统服务和限额 | +| 用户 | 不管理他人 | 创建、停用、角色分配；删除是新增能力 | +| 系统 | 无系统操作权限 | 备份、全局复习默认值、任务和运行状态 | + +个人自用：管理员和学习者可以是同一人，管理区可以较小。家庭/小团队：至少 user/admin 两种角色，校验数据归属。公开服务：进一步增加配额、审计、账号生命周期和滥用控制；这些是扩展范围。 + +建议页面边界：`/app/library`、`/app/reader/:chapterId`、`/app/vocabulary`、`/app/review`、`/app/stats`、`/app/settings`；管理区为 `/admin/users`、`/admin/languages`、`/admin/dictionaries`、`/admin/fonts`、`/admin/integrations`、`/admin/reviews`、`/admin/jobs`、`/admin/backups`。 + +管理权限解决“能否执行这个操作”，user_id 检查解决“能否操作这条记录”。即使用了 RBAC/Casbin，也不能省略后者。前端隐藏菜单不是权限边界。 + +## 4. 三条复刻路线 + +| 路线 | 优点 | 代价 | 适用场景 | +| --- | --- | --- | --- | +| A：Go 业务 + Vue 3 + Python NLP | NLP 能力连续性较好，Go 与前端可独立演进 | 仍需管理 Python 依赖、模型和进程 | 推荐，目标是可用且可持续维护 | +| B：全部后端和 NLP 用 Go | Go 侧部署统一，基础功能更容易独立打包 | 分词、词形还原、读音、27 种语言一致性要逐项解决 | 明确要求纯 Go，首期语言少 | +| C：Go API 兼容原版 Vue 2 前端 | 可更快保留一些页面交互 | API 强耦合，仍背负旧前端和随后迁移成本 | 短期内部验证，准备接受后续重构 | + +路线 A 最符合“复刻学习产品”的目标。路线 B 不能用空格切分代替中文、日文、泰语处理；英语也不能简单去掉词尾就宣称完成 lemma。spaCy 的官方文档说明词形还原、词性及分句依赖具体 pipeline 和语言能力。[spaCy 语言特征](https://spacy.io/usage/linguistic-features) + +## 5. Go 框架比较 + +“最好”在这里按二次开发成本、管理基座可用性、生态兼容和长期维护判断，不按路由微基准或未经核实的流行度排行。候选均在本次访问了官方仓库/文档；版本应在立项时锁定，不直接跟随 main。 + +| 候选 | 官方定位/特点 | 本项目判断 | +| --- | --- | --- | +| [Gin](https://github.com/gin-gonic/gin) | HTTP 路由、中间件、绑定和校验；周边生态丰富 | 首选，尤其与 gin-vue-admin 组合时成本最低；业务分层和任务仍要自己设计 | +| [Echo](https://github.com/labstack/echo) | 精简、可扩展的 Go Web 框架 | 可替代 Gin，团队熟悉即可使用；没有明显理由为本项目专门迁移框架 | +| [GoFrame](https://goframe.org/) | 提供数据库、配置、日志、校验、生成工具与工程约定 | 希望获得接近 Laravel 的完整工程体系时可优先考虑；它本身不提供语言学习产品 | +| [Fiber](https://github.com/gofiber/fiber) | Express 风格，基于 fasthttp 的 Web 框架 | 团队熟悉时可用；需要核对标准 net/http 中间件适配，阅读产品不太受益于纯路由性能差异 | +| [go-zero](https://github.com/zeromicro/go-zero) | 面向云原生服务，提供生成工具和治理能力 | 能做单体，但首版不需要为它引入微服务拆分；已有 go-zero 团队栈则可沿用 | + +不要同时叠加 Gin 与 GoFrame 的两套核心路由/ORM，也不要仅因 Go 支持高并发就拆十几个服务。 + +## 6. 适合二次开发的现成项目 + +| 项目 | 可复用部分 | 不会替你完成的部分 | 建议 | +| --- | --- | --- | --- | +| [gin-vue-admin](https://github.com/flipped-aurora/gin-vue-admin) | Gin/Vue 3 管理基座、认证、权限、动态菜单、上传、生成器等 | 阅读器、词汇领域、NLP、SRS、内容导入和数据归属 | 快速二开首选；先做小范围适配验证 | +| [go-admin](https://github.com/go-admin-team/go-admin) | Gin 管理脚手架、用户和权限、生成器；仓库列有多种前端方案 | 学习业务和具体多用户集成隔离 | 备选；明确选择的开源前端分支及许可证，不把所有展示版本视作同一套开源交付 | +| [Vue Vben Admin](https://github.com/vbenjs/vue-vben-admin) | Vue 3/TypeScript 的管理前端工程及布局 | Go 后端、业务和接口适配 | 自建 Go 后端而希望获得完整管理 UI 时适用；它不是 Go 全栈框架 | +| 原版 LinguaCafe | 交互参考、领域行为、数据迁移依据 | Laravel 不能直接变成 Go，Vue 2 也不是 Vue 3 组件库 | 适合行为参考或有意识的兼容迁移 | + +gin-vue-admin 二开建议：固定一个发行版本；保留账号、权限、菜单及必要上传能力；生成器只用于普通管理 CRUD；将 library、vocabulary、review 等业务放入独立模块。学习界面使用专门布局，避免让阅读器继承后台表格导航习惯。不同时引入 Vben 和 gin-vue-admin 两套完整后台。 + +选中脚手架前做一个具体验证：新增“个人书籍”资源，在两名用户下验证列表、详情、修改、附件下载和任务查询均不越权。能生成 CRUD 不等于天然支持数据隔离。 + +## 7. 推荐技术栈与默认取舍 + +| 部分 | 推荐 | 原因与边界 | +| --- | --- | --- | +| 服务 | Go + Gin | 模块化单体，HTTP API 清晰，适配管理基座方便 | +| 持久层 | PostgreSQL + GORM | 业务 CRUD 交付快；批量词典导入、统计热点允许显式 SQL；迁移使用版本化脚本 | +| 前端 | Vue 3 + TypeScript + Vite + Pinia + Vue Router | 响应式阅读交互；共享类型和 API 客户端 | +| UI | Element Plus + 自定义阅读器 | 表单、弹窗和表格复用组件，选词、高亮、短语交互自行开发 | +| 管理基座 | gin-vue-admin，可选 | 强调快速二开时采用；轻量个人工具可直接写少量管理页 | +| NLP | Python 服务，保留 spaCy 等能力 | Go 通过版本化 HTTP 契约调用；保留 Bottle 或改用 FastAPI 都可，框架更换不是首要任务 | +| 任务 | 生产化二开默认 Asynq + Redis | 适合导入、重试及后台作业；仍需幂等与数据库一致性措施 | +| 文件 | 本地持久目录，预留对象存储接口 | 自托管部署简单；多实例时再选择共享/对象存储 | +| TTS | 浏览器 SpeechSynthesis | 对齐原版；云端 TTS 独立作为后续能力 | +| SRS | Go 实现原版语义，策略接口隔离 | 先保证行为一致；FSRS 可选，但不能直接视为原版兼容 | +| 部署 | Docker Compose | Windows 开发可通过 Docker Desktop/WSL2；服务默认只向代理暴露必要端口 | + +组件依据：[GORM](https://gorm.io/docs/)、[Vue](https://vuejs.org/guide/introduction.html)、[Element Plus](https://element-plus.org/en-US/)、[FastAPI](https://fastapi.tiangolo.com/)、[Asynq](https://github.com/hibiken/asynq)、[go-fsrs](https://github.com/open-spaced-repetition/go-fsrs)。选型原因是本次判断。 + +数据库替代：若最优先迁移旧 MySQL 数据并降低查询改写成本，可选 MySQL；若是极简个人版，可评估 SQLite，但大词典导入并发与写锁要测试。第一版只正式支持一种数据库，不同时维护三套语义。 + +队列替代：极简个人版可以使用数据库持久任务表与 Go worker，从而省掉 Redis；不要用只存在内存中的 goroutine 队列承担需要重启恢复的导入任务。正式版本不同时维护两套任务实现。 + +## 8. 推荐模块与数据流 + +```mermaid +flowchart LR + U[Vue 学习区] --> API[Go API] + A[Vue 管理区] --> API + API --> DB[(PostgreSQL)] + API --> Q[(Redis / Asynq)] + API --> F[持久文件目录] + Q --> W[Go Worker] + W --> N[Python NLP] + W --> DB + W --> F + API --> T[翻译适配器] +``` + +上图对应默认二开方案。API 和 Worker 可以来自同一个 Go 工程、共享领域模块；不要求两套业务服务。建议模块：identity、library、ingestion、reader、vocabulary、dictionary、review、statistics、integration、administration。 + +导入流程：校验用户与文件 → 保存原件和导入记录 → 在事务中记录待派发任务 → worker 领取并解析 → 分章 → NLP 处理 → 持久化 token 和索引 → 更新状态。推荐状态为 queued/running/succeeded/failed/cancelled，这是 Go 版设计，不是原版枚举照搬。 + +任务应携带 owner、语言、输入校验和、处理器版本和尝试次数；消费重试必须幂等。数据库提交与 Redis 入队用 outbox 或补偿扫描衔接，避免“数据库成功但任务丢失”。初期进度轮询足够，确有需要再增加 SSE。 + +阅读流程：一次加载章节 token 与词汇状态 → 点词时查本地词典 → 独立请求可选翻译服务 → 保存用户释义/状态 → 局部更新高亮。不要给每个词发一次请求，也不要在打开章节时重新 NLP。 + +## 9. 数据模型建议 + +这是重新设计的概念模型，不是原版数据库结构。共享的语言知识与用户私有的学习状态应分开。 + +| 实体 | 主要内容 | 关键约束 | +| --- | --- | --- | +| users / roles | 账号、角色、状态 | 自用可简化为 admin 标志，多用户按需扩展 | +| languages / language_models | 能力、模型名与版本 | 是否可分词、lemma、读音逐项声明 | +| books / chapters | owner、语言、正文、顺序、处理状态 | 所有读写检查 owner | +| chapter_tokens | token 序号、原文、lemma、读音、句子与偏移 | 绑定文本版本和 NLP 版本 | +| lexemes | 语言、归一化表层词、可选 lemma | lemma 用于辅助查词，不自动合并所有屈折词学习状态 | +| user_vocabulary | owner、lexeme、状态、释义、读音覆盖 | 唯一键覆盖 owner 与词条 | +| phrases / phrase_occurrences | owner、语言、短语内容、出现位置 | 绑定章节版本，支持重建匹配 | +| example_sentences | owner、目标词/短语、文本快照和来源 | 删除书籍后仍能保留例句文字 | +| review_cards / review_logs | owner、目标、状态、到期时间、调度策略 | 复习事件幂等，日志可用于回放 | +| reading_progress / reading_events | 阅读位置和完成事件 | 完成事件去重，按时区统计 | +| dictionaries / dictionary_entries | 来源、语言、释义、许可证、版本 | 发布新词典版本时原子切换 | +| goals / daily_stats | owner、语言、日期、目标及完成值 | 可追溯事件与统计分离 | +| jobs / outbox / assets | 任务、消息派发、文件归属 | 任务和附件的查询也要鉴权 | +| settings / integration_credentials | 用户级/系统级配置、服务凭据 | 不把个人连接串放在共享全局配置 | + +先确定词汇身份究竟按表层词还是 lemma，再做旧数据映射。原版复习服务会按文本中的词串匹配；若新系统全部按 lemma 合并，会改变词数、学习状态和复习卡片，属于行为变更。 + +## 10. 主要难点及解决路径 + +### 10.1 跨语言偏移和阅读交互 + +Go 字符串按 UTF-8 字节存储，JavaScript 常用 UTF-16 索引，Python 字符索引也不同。契约建议以 token ID 作为交互锚点，明确辅助偏移采用 Unicode 码点并在前端转换；不要直接混用切片下标。保留空白、标点、段落与原文，确保 token 重组能还原输入。 + +短语涉及触摸拖选、重叠短语和跨章节匹配，不能用普通富文本表格生成器实现。建立小规模语料测试集覆盖英语缩写、日语无空格句子、中文、emoji 和组合音标。 + +### 10.2 NLP 服务与纯 Go 替代 + +语言处理接口返回 token、lemma、reading、sentence_id、偏移和 processor_version。Go API 不直接依赖 spaCy 对象结构。模型未安装应显式失败或让用户选择基础模式，不能静默生成错误结果。 + +保留 Python 可减少多语言质量回归，但不能假定旧包在当前环境可直接安装；需要锁定依赖、构建镜像并跑语料比较。如果以后换纯 Go，逐语言替换处理器，比较 token 边界、lemma 和阅读行为后再切换。这里未选定或验证任何 Go NLP 库达到原版质量。 + +### 10.3 词典与短语索引 + +大词典采用流式解析、分批插入、语言+规范词索引。先精确匹配与可用 lemma，再进行有上限的扩展查询，避免对所有词条无索引扫描。新短语只扫描候选章节；延迟或异步更新历史匹配，避免每次保存都同步重扫全库。具体算法由数据量基准决定。 + +### 10.4 复习兼容 + +先核对原版 stage 编码、答对/答错变化、relearning、到期日、练习模式及全局间隔，保存对应输入输出样本。将时钟注入调度器，覆盖跨日、时区和重复提交。FSRS 若引入，应记录 scheduler_version 并提供明确迁移策略；它不是原版 Leitner 式算法的同义替换。 + +### 10.5 外部集成 + +YouTube 字幕、网页抓取和翻译存在网络与服务变更，应通过适配器隔离并可关闭。Anki 在用户电脑、Go 服务在服务器时，服务器的 localhost 不代表用户电脑。个人部署可用明确配置的连接；多用户优先提供 CSV 导出，后续再设计用户本地桥接和授权，不能假定浏览器能无条件访问 AnkiConnect。Jellyfin 凭据和用户映射也需独立设计。 + +### 10.6 数据迁移 + +全量迁移不是直接导入旧 SQL。建议独立离线迁移工具：读取固定版备份 → 映射用户/语言/书籍/词汇/短语/例句/复习状态 → 复制文件 → 重建派生索引 → 比较总数与抽样阅读。阶段验收必须检查已知/忽略词数量、到期卡片和例句，不只检查表行数。原密码散列如不兼容，采用明确的重置流程。保留旧实例备份，迁移到新库，不原地覆盖。 + +## 11. 开发顺序与规模判断 + +以下为实施阶段建议，不是已排定的工期；尚无团队规模和首批语言信息，不给出伪精确的完成日期。 + +| 阶段 | 交付 | 退出条件 | +| --- | --- | --- | +| 0：技术验证 | 一种语言的文本导入、token 展示、点击查词；验证管理基座数据隔离 | 关键交互能用，语言结果与样本一致 | +| 1：可用闭环 | 账号、内容库、阅读器、词汇/短语、基础 SRS、最小管理区 | 需求 Q01—Q08 的相关场景通过 | +| 2：主要功能 | EPUB、网页和字幕文件、CSV、统计、字体、TTS、备份、多语言扩展 | 文件解析和恢复验证通过，手机阅读可用 | +| 3：功能对齐 | Anki、YouTube、Jellyfin、日语专用页面及差异补齐 | 逐条关闭上游功能差异，第三方适配可降级 | +| 4：平台扩展 | 用户删除、配额、审计、公共内容或付费能力 | 按新需求独立验收，不混入原版复刻完成率 | + +管理 CRUD 通常是较容易的一段，阅读器、NLP 与数据一致性是主要工作量。框架初始化完成不代表完成产品的大部分工作。要估算人周，应先完成阶段 0，明确首批语言、是否迁移和必须对齐的集成。 + +## 12. 开源复用边界 + +上游根目录采用 [GPL-3.0](https://github.com/simjanos-dev/LinguaCafe/blob/c1ea298ce40c65b9dd33e9b26fd2e52fae66f2c8/LICENSE)。不能因为 Laravel 脚手架的 composer.json 标注 MIT，就认为整个 LinguaCafe 是 MIT。 + +如果直接翻译或修改上游代码，应按原许可证处理对应义务，换成 Go 本身不会消除这些义务。GNU 官方 FAQ 将跨编程语言翻译视为修改的一种。[GNU FAQ](https://www.gnu.org/licenses/gpl-faq.en.html#TranslateCode) + +功能参考与直接搬运代码/资源应分别记录来源。词典、字体、模型、汉字图像和 Python 依赖有各自许可；根项目许可证不能替代这些许可。实际发布或商业分发前应针对最终复用清单核对条款，不预先承诺改写后可任意闭源。 + +## 13. 本次建议采用的默认方案 + +采用路线 A；Go/Gin 负责业务，Vue 3 负责交互，优先评估 gin-vue-admin 的管理基础。用一个前端工程中的两种布局覆盖学习区和管理区，服务端统一鉴权。数据库选 PostgreSQL；若团队决定以旧 MySQL 迁移为第一目标，可在开工前改选 MySQL。保留 Python NLP，先按原版语义做 SRS，暂不默认引入 FSRS。 + +首版先完成阅读学习闭环，再补多来源导入和集成。首批语言、纯 Go 是否硬约束、公开多用户范围和旧数据迁移需求会影响后续实施规格；本文已按默认假设给出完整分析，不将这些尚未指定的选项当作已确认需求。 diff --git a/docs/linguacafe-requirements.md b/docs/linguacafe-requirements.md new file mode 100644 index 0000000..d944d29 --- /dev/null +++ b/docs/linguacafe-requirements.md @@ -0,0 +1,139 @@ +# LinguaCafe 需求提取 + +调研日期：2026-09-10。目标项目：LexGo（Go 复刻方案）。本文提取上游需求，不代表已实现或已完成运行验收。 + +## 1. 基线与证据 + +本次实际拉取并静态检查了 [LinguaCafe](https://github.com/simjanos-dev/LinguaCafe) 的 main 分支，固定提交为 `c1ea298ce40c65b9dd33e9b26fd2e52fae66f2c8`，提交日期为 2025-03-19。调研日期不等于源码发布日期；本文不宣称这是某个最新稳定发行版。检查范围包含仓库手册、路由、管理页面、业务服务、依赖清单及 Python 文本处理代码，没有启动原版容器进行端到端验证。 + +证据索引均指向这个固定提交： + +| 编号 | 来源 | 用途 | +| --- | --- | --- | +| S1 | [README](https://github.com/simjanos-dev/LinguaCafe/blob/c1ea298ce40c65b9dd33e9b26fd2e52fae66f2c8/README.md) | 产品定位、语言范围、部署限制 | +| S2 | [Usage and features](https://github.com/simjanos-dev/LinguaCafe/blob/c1ea298ce40c65b9dd33e9b26fd2e52fae66f2c8/manual/Usage%20and%20features.md) | 阅读、复习、词汇和界面行为 | +| S3 | [Setup](https://github.com/simjanos-dev/LinguaCafe/blob/c1ea298ce40c65b9dd33e9b26fd2e52fae66f2c8/manual/Setup.md) | 多用户限制、语言、词典、集成和备份 | +| S4 | [Web 路由](https://github.com/simjanos-dev/LinguaCafe/blob/c1ea298ce40c65b9dd33e9b26fd2e52fae66f2c8/routes/web.php) | 可访问功能及管理权限分组 | +| S5 | [管理页面](https://github.com/simjanos-dev/LinguaCafe/blob/c1ea298ce40c65b9dd33e9b26fd2e52fae66f2c8/resources/js/components/Admin/AdminSettingsLayout.vue) | 管理端实际导航 | +| S6 | [Python 处理器](https://github.com/simjanos-dev/LinguaCafe/blob/c1ea298ce40c65b9dd33e9b26fd2e52fae66f2c8/tools/tokenizer.py) | 分词、EPUB、字幕、网页导入 | +| S7 | [ReviewService](https://github.com/simjanos-dev/LinguaCafe/blob/c1ea298ce40c65b9dd33e9b26fd2e52fae66f2c8/app/Services/ReviewService.php) | 用户隔离、到期词筛选及练习模式 | +| S8 | [FAQ](https://github.com/simjanos-dev/LinguaCafe/blob/c1ea298ce40c65b9dd33e9b26fd2e52fae66f2c8/manual/FAQ.md) | 删除来源后的词汇保留 | +| S9 | [导入校验](https://github.com/simjanos-dev/LinguaCafe/blob/c1ea298ce40c65b9dd33e9b26fd2e52fae66f2c8/app/Http/Requests/Import/ImportRequest.php) | 章节长度接口约束 | + +下文“已有”表示手册明确描述或源码存在实现入口，不保证所有第三方服务今天仍可用。“建议”表示 Go 版的产品或工程选择。优先级是本次建议：P0 为首个可用版本，P1 为主要功能对齐，P2 为后续完整度补齐。 + +## 2. 产品目标与核心流程 + +LinguaCafe 是自托管的外语阅读和词汇学习工具。用户导入自己想读的材料，在上下文中查词、保存释义和短语，再通过复习巩固；书籍生词统计帮助判断阅读难度。[S1][S2] + +主流程：选择语言 → 导入材料 → 生成书籍和章节 → 文本处理 → 阅读与查词 → 保存单词/短语 → 到期复习 → 查看每日目标和累计进度。 + +“书籍”是内容容器，可装文章、字幕、播客文字稿等，并不限于出版物。现有证据不支持把自动语音识别、PDF OCR、付费课程、社交社区列为原版必备功能。[S2][S6] + +## 3. 多用户现状：必须保留的资料冲突 + +README 写着每台服务器仅支持一个用户；同一提交的 Setup 手册却明确写着已经新增多用户支持，并列出未完成事项。源码存在用户管理页面、`is_admin` 权限检查，复习查询也按 `user_id` 过滤。[S1][S3][S4][S5][S7] + +因此，本次结论是：**原版已有多用户和管理员基础，但多用户体验及集成尚不完整。既不能称为完全没有多用户，也不能称为成熟多租户系统。** + +手册明确的限制包括：用户删除尚未完成；Anki 经服务器连接，不适合多个用户各自使用桌面 Anki；部分浏览器本地设置在同设备不同用户之间共享。管理员 API 页面也提示多用户部署时可能需要禁用 Jellyfin。[S3；[API 设置源码](https://github.com/simjanos-dev/LinguaCafe/blob/c1ea298ce40c65b9dd33e9b26fd2e52fae66f2c8/resources/js/components/Admin/AdminApiSettings.vue)] + +## 4. 用户端功能需求 + +| ID | 模块 | 提取的需求与关键行为 | 证据 | 建议阶段 | +| --- | --- | --- | --- | --- | +| U01 | 账号 | 登录、退出、修改密码；可选择学习语言 | S4 | P0 | +| U02 | 语言隔离 | 切换语言后显示对应阅读内容、词汇及学习数据 | S3、S7 | P0 | +| U03 | 内容库 | 创建、编辑、删除书籍和章节，支持向已有书籍添加章节 | S2、S4 | P0 | +| U04 | 难度统计 | 书籍与章节显示唯一词、已知词、高亮词及新词统计 | S2 | P0 | +| U05 | 文本导入 | 粘贴文本、上传文本文件，导入前可编辑内容 | S2 | P0 | +| U06 | 电子书导入 | 解析 EPUB 并生成章节；不能将“电子书”泛化为任意格式 | S2、S6 | P1 | +| U07 | 网页导入 | 输入网址提取正文、编辑后导入；受语言和网页结构限制 | S2、S6 | P1 | +| U08 | 字幕导入 | 上传字幕文件，或者读取 YouTube 字幕、Jellyfin 外部字幕 | S2、S6 | 文件 P1，在线集成 P2 | +| U09 | 文本处理 | 支持 Simple/Detailed 模式、按长度切章；详细模式按语言提供词元、读音、语法信息 | S2、S3、S6 | 基础 P0，逐语言增强 P1 | +| U10 | 处理状态 | 章节异步处理，提供状态更新及失败重试入口 | S4；app/Jobs/ProcessChapter.php | P0 | +| U11 | 阅读器 | 按词汇状态高亮；点词查词，鼠标连续选择创建短语，支持快捷键 | S2 | P0 | +| U12 | 查词界面 | 桌面侧栏、弹窗、移动端底部抽屉、悬停简版；不同界面查询策略有差别 | S2 | 点击与移动端 P0，悬停 P1 | +| U13 | 释义保存 | 保存或编辑单词/短语释义、读音、学习等级及例句；支持手工释义 | S2、S4 | P0 | +| U14 | 词汇状态 | New、Learning、Known、Ignored；学习等级展示为 1—7，Known 为 0；Ignored 不计已学词 | S2 | P0 | +| U15 | 章节完成 | 完成阅读时更新阅读统计；可配置是否把章节内新词批量标为已知 | S2 | P0 | +| U16 | 词汇检索 | 按文字、等级、书籍、章节、释义、单词/短语过滤；编辑与 CSV 导入导出 | S4 | 搜索编辑 P0，CSV P1 | +| U17 | SRS | 类 Leitner 的间隔复习；范围可为全部、一本书或一章 | S2、S7 | P0 | +| U18 | 练习模式 | 不按正常到期队列限制练习，且不改变正常复习数据 | S2、S7 | P1 | +| U19 | 目标与统计 | 每日阅读、标记、复习目标，日历及累计统计，可编辑目标和完成记录 | S2、S4 | P1 | +| U20 | Anki | 通过 AnkiConnect 添加卡片；已有词条可更新释义、读音和例句，受网络及单用户式配置限制 | S3、S4、API 设置源码 | P2 | +| U21 | TTS | 阅读器与复习页使用浏览器 SpeechSynthesis，按语言选语音，可用性取决于浏览器 | S2 | P1 | +| U22 | 日语扩展 | 汉字查询、详情、部首等信息；部分能力依赖导入 JMDict 相关数据 | S2、S3、S4 | P2，日语优先时提前 | +| U23 | 外观 | 浅色、深色、墨水屏主题；颜色、字体和阅读/复习显示可调整 | S2 | 基础主题 P0，其余 P1 | +| U24 | 多设备 | 手机、平板和桌面布局，手册目标最小宽度 340px；支持添加到主屏幕的 PWA 体验 | S2 | 响应式 P0，PWA P1 | +| U25 | 数据保留 | 删除导入来源不应顺带清除已经积累的词汇 | S8 | P0 | +| U26 | 帮助 | 用户手册、更新记录、资源署名页面 | S4 | P1 | + +### 阅读和复习语义 + +界面中的学习等级不能直接当作数据库编码。手册写 1—7，而 ReviewService 用 `stage < 0` 筛选学习词。Go 版需要建立明确的状态映射，迁移前核对全部编码、下次复习时间和 relearning 行为，不能简单复制正整数等级。[S2][S7] + +原版提到“完成章节”操作难以撤销。因此 Go 版建议将阅读完成事件与批量改词状态分开记录，防止重试重复计数；是否提供撤销属于增强需求。 + +普通查词优先使用可用的 lemma，并展示词典结果；悬停查词更精简，偏向精确匹配。自动生成的中文、日文读音可能错误，应保留原文、机器读音和人工修订的区别。[S2] + +## 5. 管理端功能需求 + +管理端不是推测：原版页面明确包含 Dashboard、Users、Languages、Dictionaries、Fonts、API、Reviews 七个入口，后端路由也有 admin 中间件保护。[S4][S5] + +| ID | 模块 | 已有需求 | 建议阶段 | +| --- | --- | --- | --- | +| A01 | 管理权限 | 管理员才能访问系统级设置和管理 API | P0 | +| A02 | 用户管理 | 查看、创建、编辑用户；用户删除不能标为原版已完成 | P0，删除为增强 | +| A03 | 语言管理 | 查看已安装语言、下载并安装模型；上游手册描述的卸载粒度较粗 | P0 | +| A04 | 本地词典 | 导入官方支持的词典数据、自定义 CSV，查看记录数，编辑和删除词典配置 | P0 | +| A05 | 在线词典 | DeepL、MyMemory、LibreTranslate、自定义 API 配置；支持查询及相关用量信息 | 适配一个 P1，其余 P2 | +| A06 | 字体管理 | 上传、编辑、删除字体，配置适用语言 | P1 | +| A07 | 集成设置 | 管理翻译接口、AnkiConnect、Jellyfin 的地址、开关及凭据 | P1—P2 | +| A08 | 复习设置 | 配置 SRS 规则和复习间隔 | P0 | +| A09 | 备份 | 管理页面触发备份；部署支持定时数据库备份和保留策略 | P1 | + +此表证据为 S3—S5。Go 版建议新增任务失败详情、重试、运行健康信息和操作审计；这些不应描述为上游已具备完整运维平台。 + +## 6. 语言与导入边界 + +上游列出的 27 种语言：中文、克罗地亚语、捷克语、丹麦语、荷兰语、英语、芬兰语、法语、德语、希腊语、意大利语、日语、韩语、拉丁语、马其顿语、挪威语、波兰语、葡萄牙语、罗马尼亚语、俄语、斯洛文尼亚语、西班牙语、瑞典语、泰语、土耳其语、乌克兰语、威尔士语。[S1][S3] + +支持语言不等于每种语言都具有同等分词、lemma、性别标注、词典和翻译能力。上游手册限定中文为普通话和简体字；Go 版如增加繁体应列为扩展。第三方翻译的今日语言覆盖与配额不直接沿用旧手册。[S3] + +另一个资料冲突：手册称默认每章 3000 字符、最高 15000；导入请求校验允许 200—20000。Go 版建议先用默认 3000、统一上限 15000，前后端共用契约；此值为设计建议，不是对原版实际 UI 上限的运行结论。[S2][S9] + +已核实电子书解析针对 EPUB；PDF、MOBI、扫描件 OCR 没有在本次检查中得到支持证据。字幕功能已核实，但完整扩展名清单仍需按上游解析依赖及测试样本验证，不承诺任意字幕格式。[S6] + +## 7. Go 版质量要求与验收建议 + +以下是复刻工程的建议性验收标准，不是上游性能承诺。 + +| ID | 验收场景 | 通过条件 | +| --- | --- | --- | +| Q01 | 阅读闭环 | 导入文本后可打开章节，查词、保存释义、改等级、进入到期复习 | +| Q02 | 数据隔离 | A 用户不能通过替换书籍、章节、词汇、任务或附件 ID 访问 B 用户数据；后台权限由服务端检查 | +| Q03 | 语言隔离 | 同形字符串在不同语言的学习状态互不影响 | +| Q04 | Unicode | 中文、日文、组合字符和 emoji 的高亮、选词、短语边界不发生错位 | +| Q05 | 复习确定性 | 固定时间与输入时，调度输出可重现；Known/Ignored 不进入正常队列，练习不改调度 | +| Q06 | 幂等 | 重试导入、重复提交复习、重复点击章节完成不产生重复内容或统计 | +| Q07 | 保留词汇 | 删除书籍后已积累的词汇仍可检索；来源缺失时例句显示有明确策略 | +| Q08 | 失败处理 | 模型未安装、词典为空、外部服务超时和损坏 EPUB 均显示可理解的失败原因 | +| Q09 | 移动交互 | 340px 宽度下可阅读、打开查词及保存；触摸选择与页面滚动不冲突 | +| Q10 | 备份恢复 | 新实例恢复数据库和文件后，能登录、读书、查词和复习；备份不能只验证文件存在 | +| Q11 | 导入安全 | 富文本清理、压缩包大小和路径检查、URL 抓取的内网访问限制、凭据脱敏 | +| Q12 | 性能 | 以默认章节、15k 字符章节、大词典和多人并发建立基准；先测 p95 延迟及内存，再设发布阈值 | + +## 8. 首版范围与后续范围 + +首版建议至少支持英语，使用单个管理员账号跑通核心闭环，但数据结构从第一天保留 user_id；若首版开放多个账号，Q02 必须先通过。英语先行只是降低变量的默认建议，尚未由用户指定；面向日语用户时应优先建设日语分词与词典能力。 + +P0：账号、语言选择、文本导入、章节处理、阅读高亮、查词、单词和短语、基础 SRS、最小管理区。 + +P1：EPUB/字幕文件/网页导入、CSV、目标日历、TTS、字体、PWA、备份恢复、更多语言与词典。 + +P2：YouTube、Jellyfin、Anki 的完整接入、汉字部首等专门功能，以及更完整的多用户运营管理。 + +用户删除、配额、公共书库、多租户、计费、AI 讲解、云端 TTS、离线同步、FSRS 均应明确列为扩展；P0 完成不能称为完整复刻。 + +对应技术分析见 [Go 复刻与框架选型](linguacafe-go-analysis.md)。 diff --git a/docs/task/.gitkeep b/docs/task/.gitkeep deleted file mode 100644 index 8b13789..0000000 --- a/docs/task/.gitkeep +++ /dev/null @@ -1 +0,0 @@ - diff --git a/docs/task/1-Wiki-文档主源.md b/docs/task/1-Wiki-文档主源.md deleted file mode 100644 index 7ab5498..0000000 --- a/docs/task/1-Wiki-文档主源.md +++ /dev/null @@ -1,82 +0,0 @@ - -generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) -wiki_page: Task-1-Wiki-文档主源 -wiki_url: http://ilaer.eicp.net:8418/opc/dev_harness/wiki/Task-1-Wiki-%E6%96%87%E6%A1%A3%E4%B8%BB%E6%BA%90.- -wiki_revision: dbbf9ddfb2e703486c7054f275538e8e03a570b3 -synchronized_at: 2026-08-08T01:11:20Z - - -# 1 引入 Gitea Wiki 作为长期开发文档主源 - -- 类型：需求 -- 所属 Epic：无 -- 所属 MVP / 版本：无 -- 状态：已完成 -- 日期：2026-08-07 -- Gitea 工单：[opc/dev_harness#1](http://ilaer.eicp.net:8418/opc/dev_harness/issues/1) -- Wiki 页面：Task-1-Wiki-文档主源 -- Wiki revision：见本地镜像头 - -## 背景与目标 - -DevHarness 原来使用 Gitea 工单记录实施过程、使用 Git 记录代码，并把完成后的长期文档直接维护在本地 `docs/`。本任务引入 Gitea Wiki 作为长期开发文档的事实来源，本地 `docs/` 改为仅供离线浏览和代码审查的只读镜像。 - -## 最终方案 - -- Gitea 工单管理任务状态、讨论、阻塞、验证和验收过程。 -- Gitea Wiki 管理架构说明、开发规范、操作手册和任务归档。 -- Git 管理源码、版本绑定资料以及 Wiki 镜像。 -- `wiki-docs.json` 显式登记 Wiki 页面与本地路径，映射仅允许写入 `docs/` 下的 Markdown。 -- `scripts/sync_wiki_docs.py` 只实现 Wiki → docs；镜像记录页面、规范 URL、revision 和同步时间。 -- 同步前检查所有映射镜像的 Git 状态，发现未提交改动立即停止。 -- 页面缺失、删除或重命名时同步失败，不自动传播破坏性变化。 -- `scripts/new_task_archive.py` 改为先创建 Wiki 归档，再登记映射并导出本地镜像。 -- `scripts/check_harness.py --strict` 同时检查项目档案、映射完整性和镜像元数据。 - -Gitea 1.25 会为部分带连字符页面生成带 `.-` 的规范 `sub_url`；客户端先按标题查询页面列表，再使用服务端返回的 `sub_url` 读取内容和构造链接。 - -## 修改文件 - -- `AGENTS.md`：更新事实源、实施、归档与安全规则。 -- `CLAUDE.md`：更新 Agent 文档读取和归档入口。 -- `README.md`：更新工作闭环、目录和快速开始说明。 -- `wiki-docs.json`：新增 Wiki 页面显式映射。 -- `scripts/wiki_docs.py`：实现配置校验、Gitea API、镜像生成、脏文件保护和一致性检查。 -- `scripts/sync_wiki_docs.py`：新增单向同步命令。 -- `scripts/new_task_archive.py`：改为在线优先的任务归档流程。 -- `scripts/check_harness.py`：增加映射和镜像元数据检查。 -- `tests/test_wiki_docs.py`：覆盖映射、元数据、幂等、路径限制和脏文件保护。 -- `docs/**`：由 Wiki 导出的只读镜像。 - -## 验收结果 - -| 验收标准 | 结果 | -|---|---| -| Wiki 是长期开发文档主源，docs 明确为镜像 | 通过 | -| 一条命令导出全部映射页面 | 通过 | -| 镜像包含页面、URL、revision 和同步时间 | 通过 | -| 未提交镜像改动会阻止覆盖 | 通过 | -| 删除或重命名不会自动传播 | 通过 | -| 严格检查和测试通过 | 通过 | -| Wiki、镜像和流程规则一致 | 通过 | - -## 测试 - -- 执行命令：`python -m unittest discover -s tests -v` -- 结果：10 项测试通过。 -- 执行命令：`python scripts/check_harness.py --strict` -- 结果：通过。 -- 执行命令：`python scripts/sync_wiki_docs.py --check` -- 结果：映射页面的 revision 和正文均一致。 -- 执行命令：`python -m py_compile scripts/check_harness.py scripts/wiki_docs.py scripts/sync_wiki_docs.py scripts/new_task_archive.py tests/test_wiki_docs.py` -- 结果：通过。 -- 执行命令：`git diff --check` -- 结果：通过。 -- **未验证部分**：未用独立测试 PAT 调用 `new_task_archive.py` 创建额外测试页面；正式 #1 归档通过同一 Gitea API 的 MCP 写入并导出验证。 - -## 相关提交 - -- `b08a919` feat: 引入 Wiki 文档镜像流程 (#1) -- `f1a7b09` docs: 同步 Wiki 文档镜像 (#1) -- `8c52ea2` test: 覆盖 Wiki 镜像脏文件保护 (#1) -- `1e3915b` fix: 支持中文 Wiki 页面路径 (#1) diff --git a/docs/task/10-需求记录与流转规则.md b/docs/task/10-需求记录与流转规则.md deleted file mode 100644 index 0b4edb3..0000000 --- a/docs/task/10-需求记录与流转规则.md +++ /dev/null @@ -1,88 +0,0 @@ - -generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) -wiki_page: Task-10-需求记录与流转规则 -wiki_url: http://ilaer.eicp.net:8418/opc/dev_harness/wiki/Task-10-%E9%9C%80%E6%B1%82%E8%AE%B0%E5%BD%95%E4%B8%8E%E6%B5%81%E8%BD%AC%E8%A7%84%E5%88%99.- -wiki_revision: d1f9c3198f76216fe8013f9862c26b59f9c179dc -synchronized_at: 2026-08-10T04:00:18Z - - -# 10 需求记录与流转规则 - -- 类型：开发流程优化 -- 所属 Epic：无 -- 所属 MVP / 版本：无 -- 状态：已完成 -- 日期：2026-08-10 -- Gitea 工单：http://ilaer.eicp.net:8418/opc/dev_harness/issues/10 -- Wiki 页面：Task-10-需求记录与流转规则 -- Wiki revision：见本地镜像头 - -## 背景与目标 - -工单原本能够记录目标、方案和验收标准，但没有固定字段保存需求来源、关键原始表达和实施期间的需求变化，未来可能难以追溯用户最初目的以及最终方案变化原因。 - -本任务以最小方式补强需求可追踪性，同时保持 Gitea 工单、Wiki 和本地镜像的事实来源边界。 - -## 最终方案 - -- 单元任务模板增加“原始需求”：来源、提出时间、关键原话或脱敏摘要。 -- 只保存表达用户目的、场景和限制所需的少量原话，不臆造用户原话。 -- 目标、非目标、已确认方案、验收标准和文档影响构成正式任务需求。 -- 增加“需求变化记录”，记录影响范围、接口、数据、风险或验收的变化日期、内容、原因和用户确认。 -- 会改变已确认结果的变化仍须先更新工单并等待再次确认。 -- 不复制完整聊天，不保存 Agent 内部推理，不写入敏感信息；敏感原话必须脱敏。 -- 关键原始需求、正式任务需求、讨论和变化保存在 Gitea 工单，不导出全文。 -- 长期产品需求、业务规则和系统边界进入 Wiki 主题页并导出 `docs/`。 -- 完成结果进入 Wiki 任务归档并导出 `docs/task/`。 -- Harness 检查任务模板、Agent 规则和 Wiki 章节。 -- 没有新增需求数据库、同步脚本、Skill 或聊天抓取功能。 - -实施结果与已确认方案一致。 - -## 修改文件 - -- `AGENTS.md`：增加需求记录和事实来源边界。 -- `.gitea/issue_template/task.md`：增加原始需求和需求变化记录。 -- `dev_scripts/check_harness.py`：检查需求追踪字段和规则。 -- `tests/test_harness_docs.py`：验证缺失需求追踪字段会被报告。 -- `docs/01-workflow.md`：Development-Workflow Wiki 的只读镜像。 -- `docs/03-business-rules-and-glossary.md`：Business-Rules-and-Glossary Wiki 的只读镜像。 -- `wiki-docs.json`：登记本任务 Wiki 归档镜像。 -- `docs/task/10-需求记录与流转规则.md`：本页的自动导出镜像。 - -## 验收结果 - -用户于 2026-08-10 明确验收通过。 - -| 验收标准 | 结果 | -|---|---| -| 模板记录来源、时间和关键原话 | 通过 | -| 模板记录需求变化四项信息 | 通过 | -| 工单保存正式任务需求和变化 | 通过 | -| 长期结论进入 Wiki 和 docs 镜像 | 通过 | -| 不保存完整聊天、内部推理和敏感信息 | 通过 | -| 不导出 Gitea 工单全文 | 通过 | -| Harness 检测字段缺失 | 通过 | -| 未增加脚本或聊天抓取功能 | 通过 | -| Wiki 先更新、确认再导出 | 通过 | -| 测试和严格检查 | 通过 | -| 实现和归档提交分离 | 通过 | - -## 测试 - -- 执行命令：`python -m unittest discover -s tests -v` -- 结果：21/21 通过。 -- 执行命令：`python dev_scripts/check_harness.py --strict` -- 结果：通过。 -- 执行命令：`python dev_scripts/sync_wiki_docs.py --check` -- 结果：归档前 19/19 映射一致；归档后重新检查 20/20。 -- 执行命令：`python -m compileall -q dev_scripts tests` -- 结果：通过。 -- 执行命令：`git diff --check` -- 结果：通过。 -- **未验证部分**：未实现聊天自动抓取或 Gitea 工单全文导出，这些是已确认的非目标。 - -## 相关提交 - -- `353bd97` `feat: 增加需求记录规则 (#10)` -- 归档提交哈希在提交后回写 Gitea 工单，避免归档自引用。 diff --git a/docs/task/11-交付文档指南与岗位文档模板.md b/docs/task/11-交付文档指南与岗位文档模板.md deleted file mode 100644 index 29b604c..0000000 --- a/docs/task/11-交付文档指南与岗位文档模板.md +++ /dev/null @@ -1,80 +0,0 @@ - -generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) -wiki_page: Task-11-交付文档指南与岗位文档模板 -wiki_url: http://ilaer.eicp.net:8418/opc/dev_harness/wiki/Task-11-%E4%BA%A4%E4%BB%98%E6%96%87%E6%A1%A3%E6%8C%87%E5%8D%97%E4%B8%8E%E5%B2%97%E4%BD%8D%E6%96%87%E6%A1%A3%E6%A8%A1%E6%9D%BF.- -wiki_revision: 4e5c30641d9bcbc69d4c235f33ff89dd47259f63 -synchronized_at: 2026-08-10T06:29:01Z - - -# 11 交付文档指南与岗位文档模板 - -- 类型：开发流程优化 -- 所属 Epic：无 -- 所属 MVP / 版本：无 -- 状态：待验收 -- 日期：2026-08-10 -- Gitea 工单：http://ilaer.eicp.net:8418/opc/dev_harness/issues/11 -- Wiki 页面：Task-11-交付文档指南与岗位文档模板 -- Wiki revision：见本地镜像头 - -## 背景与目标 - -DevHarness 已覆盖开发维护文档，但缺少面向客户、最终用户及其他岗位的交付文档选择、内外边界、编写和验收规则，也没有可以复用的岗位文档模板。 - -本任务以最小范围建立交付文档闭环：只增加一份指南和一份通用模板，并把交付文档影响接入工单和新项目初始化流程，不预建没有明确读者的空白手册。 - -## 最终方案 - -- 新增“交付文档指南”，规定适用时机、受众与文档选择、内部与外部信息边界、编写维护流程和最小验收清单。 -- 新增“岗位文档模板”，覆盖文档受众、适用版本、最后验证日期、负责人、可见范围、目的、前置条件、操作步骤、预期结果、常见错误与恢复、安全、限制、支持渠道和版本记录。 -- 明确根据实际受众按需创建用户、管理员、运维、支持、集成或验收文档，不创建没有明确读者的空页面。 -- 单元任务模板增加“交付文档影响”，要求选择无影响并说明原因，或列出新增、更新页面及目标岗位验证方式。 -- 新项目初始化流程增加识别交付对象、可见范围、所需文档和外部信息边界的步骤。 -- Home 增加交付指南和岗位模板入口，并将交付文档纳入 Wiki 长期文档事实来源。 -- 两个新增页面显式映射到 `docs/delivery/`，Harness 将其纳入核心映射和章节检查。 -- 未生成具体岗位手册、PDF、HTML 或发布包，未增加新脚本、框架和第三方依赖。 - -实施结果与已确认方案一致。 - -## 修改文件 - -- `.gitea/issue_template/task.md`：增加交付文档影响字段。 -- `dev_scripts/check_harness.py`：检查新增核心页面、章节和工单字段。 -- `tests/test_harness_docs.py`：验证缺少交付文档影响字段时能够报告错误。 -- `wiki-docs.json`：登记交付指南、岗位模板和本任务归档的镜像映射。 -- `docs/README.md`：Home Wiki 的只读镜像，增加交付文档入口。 -- `docs/07-new-project-documentation-setup.md`：新项目初始化 Wiki 的只读镜像。 -- `docs/delivery/README.md`：交付文档指南的只读镜像。 -- `docs/delivery/audience-document-template.md`：岗位文档模板的只读镜像。 -- `docs/task/11-交付文档指南与岗位文档模板.md`：本页的自动导出镜像。 - -## 验收结果 - -| 验收标准 | 结果 | -|---|---| -| 指南覆盖选择规则、内外边界、流程和验收 | 通过 | -| 岗位模板字段完整且可复用 | 通过 | -| 工单模板要求评估交付文档影响 | 通过 | -| 新项目初始化识别交付对象并按需建文档 | 通过 | -| Home 可进入新增页面 | 通过 | -| 两页镜像到 `docs/delivery/` 并可追踪 revision | 通过 | -| Harness 严格检查和单元测试 | 通过 | -| 实现提交已推送且归档单独提交 | 进行中：归档提交后回写工单 | -| 用户明确验收 | 待验收 | - -## 测试 - -- 执行命令：`python dev_scripts/check_harness.py --strict` -- 结果：通过。 -- 执行命令：`python -m unittest discover -s tests -v` -- 结果：22/22 通过。 -- 执行命令：`python dev_scripts/sync_wiki_docs.py --check` -- 结果：归档前 22/22 映射一致；归档完成后重新检查。 -- 执行命令：`git diff --check` -- 结果：通过。 -- **未验证部分**：未创建具体产品的岗位文档，因此没有真实目标岗位或客户环境可执行验证；这属于已确认非目标，具体项目创建实际文档时必须补充目标岗位验证。 - -## 相关提交 - -- `3474870` `docs: 建立最小交付文档体系 (#11)` -- 归档提交哈希在提交后回写 Gitea 工单，避免归档自引用。 diff --git a/docs/task/12-已有项目接入DevHarness指南.md b/docs/task/12-已有项目接入DevHarness指南.md deleted file mode 100644 index 607b939..0000000 --- a/docs/task/12-已有项目接入DevHarness指南.md +++ /dev/null @@ -1,87 +0,0 @@ - -generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) -wiki_page: Task-12-已有项目接入DevHarness指南 -wiki_url: http://ilaer.eicp.net:8418/opc/dev_harness/wiki/Task-12-%E5%B7%B2%E6%9C%89%E9%A1%B9%E7%9B%AE%E6%8E%A5%E5%85%A5DevHarness%E6%8C%87%E5%8D%97.- -wiki_revision: e4ed7d5fd6a9ac5d4bf97c93f509182f2a8a8a4f -synchronized_at: 2026-08-10T10:00:07Z - - -# 12 已有项目接入 DevHarness 指南 - -- 类型：开发流程优化 -- 所属 Epic：无 -- 所属 MVP / 版本：无 -- 状态：已完成 -- 日期：2026-08-10 -- Gitea 工单：http://ilaer.eicp.net:8418/opc/dev_harness/issues/12 -- Wiki 页面：Task-12-已有项目接入DevHarness指南 -- Wiki revision：见本地镜像头 - -## 背景与目标 - -现有“新项目文档初始化”面向从模板创建的新项目，没有完整覆盖已有项目中现存规则、文档、工单、Wiki、Git 历史、未完成任务和工作区改动的保护与增量接入方式。 - -本任务新增独立的已有项目接入指南，让 Claude、Codex 等 Agent 能先只读盘点、识别冲突、等待方案确认，再通过单元任务安全地分阶段接入 DevHarness。 - -## 最终方案 - -- 新增 `Existing-Project-Adoption-Guide`，明确与新项目初始化的适用边界。 -- 接入前盘点 Agent 规则、README、文档、Wiki、工单、Git 历史、未提交改动、技术栈、命令、权限、安全及任务状态。 -- 区分代码或系统事实、负责人确认规则、待确认假设、规则冲突和必须保留的无关改动。 -- 明确保留 Git 历史、项目专用规则、现有任务状态和无关工作区改动。 -- 禁止复制 DevHarness 历史归档、覆盖已有规则、把模板占位值当成项目事实或自动清理旧文档。 -- 采用“确认差异方案 → 建立单元工单 → 接入规则和工单流程 → 确定长期文档事实来源 → 接入必要 Harness 工具 → 分阶段验证 → 提交和验收”的顺序。 -- 为已有文档提供保留在 Git、迁移到 Wiki、合并、暂不迁移和停止维护五种明确状态。 -- 提供可直接发送给 Agent 的“只分析”和“方案确认后实施”两段指令。 -- 规定冲突、删除重命名、产品行为变化、重叠修改、权限不可用和事实不明时的停止条件。 -- Home 增加指南入口和已有项目接入导航。 -- 页面映射到 `docs/08-existing-project-adoption.md`，并纳入 Harness 核心映射和章节检查。 -- 未增加自动迁移脚本，未修改任何实际业务项目，未改变事实来源边界。 - -实施结果与已确认方案一致。 - -## 修改文件 - -- `dev_scripts/check_harness.py`：增加已有项目接入指南的核心映射和章节检查。 -- `tests/test_harness_docs.py`：验证指南属于必需核心页面。 -- `wiki-docs.json`：登记指南和本任务归档镜像。 -- `docs/README.md`：Home Wiki 只读镜像，增加已有项目接入入口。 -- `docs/08-existing-project-adoption.md`：已有项目接入指南只读镜像。 -- `docs/task/12-已有项目接入DevHarness指南.md`：本页的自动导出镜像。 - -## 验收结果 - -用户于 2026-08-10 明确验收通过。 - -| 验收标准 | 结果 | -|---|---| -| Wiki 存在独立的已有项目接入指南 | 通过 | -| 明确区分已有项目接入与新项目初始化 | 通过 | -| 覆盖只读盘点、内容保护、冲突处理和停止条件 | 通过 | -| 给出分阶段增量接入顺序 | 通过 | -| 包含可直接复制的分析和实施指令 | 通过 | -| 禁止复制历史归档和覆盖已有项目内容 | 通过 | -| Home 可进入指南 | 通过 | -| 页面具有显式映射和有效 revision | 通过 | -| Harness 严格检查和单元测试 | 通过 | -| 实现和归档提交已推送 | 通过 | -| 用户明确验收 | 通过 | - -## 测试 - -- 执行命令：`python dev_scripts/check_harness.py --strict` -- 结果：通过。 -- 执行命令：`python -m unittest discover -s tests -v` -- 结果：23/23 通过。 -- 执行命令：`python dev_scripts/sync_wiki_docs.py --check` -- 结果：25/25 映射一致。 -- 执行命令：`git diff --check` -- 结果：通过。 -- 人工检查：两段 Agent 指令未授权覆盖、删除、重命名或自动迁移已有项目内容。 -- **未验证部分**：未在真实业务仓库执行完整接入，因为修改实际项目属于本任务非目标；首次实际接入时应按指南建立独立工单并记录项目专用验证。 - -## 相关提交 - -- `0271a3e` `docs: 新增已有项目接入指南 (#12)` -- `eba8515` `docs: archive task #12` -- 验收状态提交哈希回写 Gitea 工单，避免归档自引用。 diff --git a/docs/task/13-多子项目与独立交付单元.md b/docs/task/13-多子项目与独立交付单元.md deleted file mode 100644 index 0ff6135..0000000 --- a/docs/task/13-多子项目与独立交付单元.md +++ /dev/null @@ -1,68 +0,0 @@ - -generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) -wiki_page: Task-13-多子项目与独立交付单元 -wiki_url: http://ilaer.eicp.net:8418/opc/dev_harness/wiki/Task-13-%E5%A4%9A%E5%AD%90%E9%A1%B9%E7%9B%AE%E4%B8%8E%E7%8B%AC%E7%AB%8B%E4%BA%A4%E4%BB%98%E5%8D%95%E5%85%83.- -wiki_revision: 92b493258075739341d1591069f6c79b143965e7 -synchronized_at: 2026-08-11T02:22:51Z - - -# 13 多子项目与独立交付单元 - -- 类型：需求 -- 所属 Epic：无 -- 所属 MVP / 版本：无 -- 状态：已完成 -- 日期：2026-08-10 -- 验收日期：2026-08-11 -- 验收结果：用户明确验收通过 -- Gitea 工单：http://ilaer.eicp.net:8418/opc/dev_harness/issues/13 -- Wiki 页面：Task-13-多子项目与独立交付单元 -- Wiki revision：见本地镜像头 - -## 背景与目标 - -DevHarness 需要兼容一个 Git 仓库包含多个终端、服务或其他独立交付单元的项目。目标是在不引入 monorepo 框架、不自动拆仓的前提下，让项目档案、任务范围和接入指南明确每个子项目的职责、构建测试、版本发布、规则入口及共享契约边界。 - -## 最终方案 - -- Project-Profile 增加“子项目与交付单元”表格，记录职责、技术栈、构建测试、版本发布、规则入口和共享边界。 -- 新项目初始化流程先识别全部子项目与独立交付单元，并指定共享契约的唯一事实来源。 -- 已有项目接入指南增加多应用单仓库判断：技术栈不同本身不要求拆仓；按团队、权限、发布周期、仓库效率、复用关系和契约稳定性决定是否拆分。 -- 单元任务模板增加“子项目影响”，强制记录单端或跨端范围、共享契约变化及各端验证。 -- Harness 严格检查上述核心章节与模板字段，并增加对应单元测试。 -- 未增加 monorepo 工具、自动拆仓或迁移、统一版本机制、CI 生成器，也未修改实际业务项目。 - -## 修改文件 - -- `.gitea/issue_template/task.md`：增加子项目影响字段。 -- `dev_scripts/check_harness.py`：检查多子项目核心文档结构和任务模板字段。 -- `tests/test_harness_docs.py`：增加任务模板子项目影响测试。 -- `docs/00-project-profile.md`：镜像项目档案的子项目与交付单元定义。 -- `docs/07-new-project-documentation-setup.md`：镜像新项目识别交付单元的初始化步骤。 -- `docs/08-existing-project-adoption.md`：镜像多应用单仓库判断与最小规则。 - -## 验收结果 - -| 验收标准 | 结果 | -|---|---| -| 项目档案可记录每个子项目和独立交付单元 | 通过 | -| 新项目和已有项目指南说明多应用单仓库的判断规则 | 通过 | -| 单元任务模板明确子项目、跨项目和共享契约影响 | 通过 | -| 共享契约要求指定唯一事实来源和各端验证 | 通过 | -| 严格检查、单元测试和 Wiki 镜像检查通过 | 通过 | -| 不引入拆仓自动化或修改实际业务项目 | 通过 | - -## 测试 - -- 执行命令：`python dev_scripts/check_harness.py --strict` -- 结果：通过。 -- 执行命令：`python -m unittest discover -s tests -v` -- 结果：24 项测试全部通过。 -- 执行命令：`python dev_scripts/sync_wiki_docs.py --check` -- 结果：归档前 25 份 Wiki 镜像全部一致。 -- 人工示例检查：以 Client 与 Admin 两个交付单元填写职责、独立构建测试、版本发布和共享接口时，新增字段能够表达单端与跨端影响。 -- **未验证部分**：未在真实多应用业务仓库执行接入或发布验证；该项不属于本工单范围。 - -## 相关提交 - -- `4e1db45` docs: support multi-project delivery units (#13) diff --git a/docs/task/2-初级维护者文档体系.md b/docs/task/2-初级维护者文档体系.md deleted file mode 100644 index 4936771..0000000 --- a/docs/task/2-初级维护者文档体系.md +++ /dev/null @@ -1,81 +0,0 @@ - -generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) -wiki_page: Task-2-Junior-Maintainer-Docs -wiki_url: http://ilaer.eicp.net:8418/opc/dev_harness/wiki/Task-2-Junior-Maintainer-Docs.- -wiki_revision: 9bf07c395c959501d995cfe7250623438c53dba7 -synchronized_at: 2026-08-08T01:11:23Z - - -# 2 建立面向初级维护者的轻量项目文档体系 - -- 类型：需求 -- 所属 Epic：无 -- 所属 MVP / 版本：无 -- 状态：已完成 -- 日期：2026-08-08 -- Gitea 工单：[opc/dev_harness#2](http://ilaer.eicp.net:8418/opc/dev_harness/issues/2) -- Wiki 页面：Task-2-Junior-Maintainer-Docs -- Wiki revision：见本地镜像头 - -## 背景与目标 - -DevHarness 已具备工单、Wiki 主源和本地镜像流程，但缺少面向初级维护者的代码入口、业务规则、运行验证、简单修改和故障排查。目标是让初级程序员理解项目文档，并在 Claude/Codex Agent 协助下处理简单 Bug 和需求；大部分代码仍由 Agent 实现。 - -## 最终方案 - -- Home 提供 10～20 分钟阅读路径、五分钟验证命令、修改入口和停止条件。 -- 新增架构与代码地图、业务规则与术语、本地开发与验证、常见修改、故障排查、新项目文档初始化六个稳定主题页。 -- 项目档案补充使用者、环境、适用版本、日志、测试数据和阅读入口。 -- 开发工作流和 Agent 规则采用低/中/高风险分级，不以代码行数判断风险。 -- 单元任务模板增加“文档影响”，入口、命令、配置、数据、业务和排错变化必须更新 Wiki。 -- Harness 检查核心页面映射、固定章节及任务模板字段；不把结构检查误认为语义质量判断。 -- 新项目使用明确初始化说明，不增加额外 Wiki 生成框架。 - -## 修改文件 - -- `AGENTS.md`：增加风险边界、核心文档和更新条件。 -- `CLAUDE.md`：增加代码地图、业务规则阅读顺序和文档影响要求。 -- `.gitea/issue_template/task.md`：增加文档影响检查项。 -- `README.md`：链接新项目初始化和新增镜像目录。 -- `wiki-docs.json`：登记六个新增核心页面。 -- `scripts/check_harness.py`：检查核心映射、章节和工单模板。 -- `tests/test_harness_docs.py`：覆盖成功、缺失章节和错误映射。 -- `docs/README.md`、`docs/00-project-profile.md`、`docs/01-workflow.md`：更新后的 Wiki 镜像。 -- `docs/02-architecture-and-code-map.md` 至 `docs/07-new-project-documentation-setup.md`：新增 Wiki 镜像。 - -## 验收结果 - -| 验收标准 | 结果 | -|---|---| -| Home 提供阅读顺序、启动、测试和代码入口 | 通过 | -| 核心页面职责明确且保持轻量结构 | 通过 | -| 简单修改和高风险停止边界清楚 | 通过 | -| 单元任务必须声明文档影响 | 通过 | -| 严格检查能发现页面、映射和章节问题 | 通过 | -| Wiki 与本地镜像一致 | 通过 | -| 自动化测试和严格检查通过 | 通过 | - -## 测试 - -- 执行命令：`python -m unittest discover -s tests -v` -- 结果：16/16 通过。 -- 执行命令：`python scripts/check_harness.py --strict` -- 结果：通过。 -- 执行命令：`python scripts/sync_wiki_docs.py --check` -- 结果：11/11 映射一致。 -- 执行命令：`python -m compileall -q scripts tests` -- 结果：通过。 -- 执行命令：`git diff --check` -- 结果：通过。 -- 人工验证：六个新增 Wiki 页面均可访问，Home 阅读路径、风险分级和初始化顺序完整。 -- **未验证部分**：尚未在全新业务仓库完整执行初始化，也未由真实初级程序员完成可用性测试。 - -## 遗留问题 - -首个采用该模板的业务项目应把“新人能否根据 Home 找到入口、运行测试并理解一次简单修改”纳入实际验收，再根据反馈精简或补充主题页。 - -## 相关提交 - -- `250b055` feat: 建立初级维护者文档体系 (#2) -- `b09658e` docs: 修正文档命令与初始化边界 (#2) -- `c8ccb62` test: 覆盖核心文档映射错误 (#2) diff --git a/docs/task/3-dev_scripts目录重命名.md b/docs/task/3-dev_scripts目录重命名.md deleted file mode 100644 index 6f213f1..0000000 --- a/docs/task/3-dev_scripts目录重命名.md +++ /dev/null @@ -1,72 +0,0 @@ - -generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) -wiki_page: Task-3-Dev-Scripts-Rename -wiki_url: http://ilaer.eicp.net:8418/opc/dev_harness/wiki/Task-3-Dev-Scripts-Rename.- -wiki_revision: 15e71e5f540039f3947754a4a17971e12604dff7 -synchronized_at: 2026-08-08T01:24:35Z - - -# 3 将 DevHarness 工具目录重命名为 dev_scripts - -- 类型：重构 -- 所属 Epic：无 -- 所属 MVP / 版本：无 -- 状态：已完成 -- 日期：2026-08-08 -- Gitea 工单：[opc/dev_harness#3](http://ilaer.eicp.net:8418/opc/dev_harness/issues/3) -- Wiki 页面：Task-3-Dev-Scripts-Rename -- Wiki revision：见本地镜像头 - -## 背景与目标 - -DevHarness 自身工具原来放在根目录 `scripts/`，容易和后续业务项目的脚本混淆。本任务把 Harness 检查、Wiki 同步和任务归档工具统一迁移到 `dev_scripts/`，不保留旧路径兼容入口。 - -## 最终方案 - -- `scripts/check_harness.py` → `dev_scripts/check_harness.py`。 -- `scripts/wiki_docs.py` → `dev_scripts/wiki_docs.py`。 -- `scripts/sync_wiki_docs.py` → `dev_scripts/sync_wiki_docs.py`。 -- `scripts/new_task_archive.py` → `dev_scripts/new_task_archive.py`。 -- 更新测试导入路径、必需文件检查、AGENTS、README 和稳定 Wiki 页面。 -- Wiki 先修改并读取确认，再导出本地镜像。 -- 历史任务 #1、#2 保留旧路径，避免改写历史事实。 -- 旧 `scripts/` 目录不保留包装器，未来业务脚本必须与 `dev_scripts/` 分开。 - -## 修改文件 - -- `scripts/**` → `dev_scripts/**`：整体目录重命名。 -- `dev_scripts/check_harness.py`：必需工具路径改为新目录。 -- `tests/test_wiki_docs.py`、`tests/test_harness_docs.py`：导入新目录。 -- `AGENTS.md`：更新同步、归档命令和目录边界。 -- `README.md`：更新快速开始和目录说明。 -- `docs/README.md`、项目档案、工作流、代码地图、开发验证、常见修改和新项目初始化：线上 Wiki 的更新镜像。 - -## 验收结果 - -| 验收标准 | 结果 | -|---|---| -| 四个工具位于 dev_scripts，旧目录不存在 | 通过 | -| 新命令可运行且不保留旧兼容入口 | 通过 | -| 测试导入和必需文件检查使用新路径 | 通过 | -| 稳定 Wiki 与本地镜像使用新路径 | 通过 | -| 非历史内容没有旧路径引用 | 通过 | -| 测试、严格检查、同步和编译通过 | 通过 | - -## 测试 - -- 执行命令：`python -m unittest discover -s tests -v` -- 结果：16/16 通过。 -- 执行命令：`python dev_scripts/check_harness.py --strict` -- 结果：通过。 -- 执行命令：`python dev_scripts/sync_wiki_docs.py --check` -- 结果：12/12 映射一致。 -- 执行命令：`python -m compileall -q dev_scripts tests` -- 结果：通过。 -- 执行命令：旧目录和非历史旧路径搜索。 -- 结果：旧目录不存在；非历史旧路径无残留。 -- **未验证部分**：仓库外部未纳入版本管理的自动化如果仍使用旧命令，需要使用方自行更新。 - -## 相关提交 - -- `1c99867` refactor: 将 Harness 工具移至 dev_scripts (#3) -- `51278fa` docs: 修正 dev_scripts 编译检查命令 (#3) diff --git a/docs/task/4-Agent效率与范围控制.md b/docs/task/4-Agent效率与范围控制.md deleted file mode 100644 index 6fb8c40..0000000 --- a/docs/task/4-Agent效率与范围控制.md +++ /dev/null @@ -1,70 +0,0 @@ - -generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) -wiki_page: Task-4-Agent-Efficiency-Scope -wiki_url: http://ilaer.eicp.net:8418/opc/dev_harness/wiki/Task-4-Agent-Efficiency-Scope.- -wiki_revision: 3c2d8b9e5d82a0d3da5b71ef9d889e11d813d27d -synchronized_at: 2026-08-08T01:59:47Z - - -# 4 增加 Agent 效率与范围控制规则 - -- 类型：需求 -- 所属 Epic：无 -- 所属 MVP / 版本：无 -- 状态：已完成 -- 日期：2026-08-08 -- Gitea 工单：[opc/dev_harness#4](http://ilaer.eicp.net:8418/opc/dev_harness/issues/4) -- Wiki 页面：Task-4-Agent-Efficiency-Scope -- Wiki revision：见本地镜像头 - -## 背景与目标 - -DevHarness 已有完整安全和交付闭环，但缺少对无关扩展、重复检查、预防性验证和完成后继续优化的限制。本任务在不削弱安全、测试和归档的前提下增加效率规则。 - -## 最终方案 - -- 严格控制范围：默认按用户确认目标和工单执行，只限制无关产物、无关验证和相邻问题。 -- 渐进执行和修复：完成必要前置检查后，用最小命令获得真实反馈，一次处理首个可行动错误。 -- 复用已验证事实：只在同一任务和同一环境状态下复用，关键前提变化时重检。 -- 明确停止条件：完成用户验收标准和仓库必要闭环后停止，首次运行成功不等于完成。 -- 安全、高风险前置检查、代码修改后的测试、提交前状态、推送前远端检查和 Skill 规则不允许省略。 -- Harness 检查开发工作流镜像和 AGENTS 中四组章节是否存在。 - -## 修改文件 - -- `AGENTS.md`：增加效率与范围控制的完整规则。 -- `CLAUDE.md`：增加简明执行入口。 -- `Development-Workflow` Wiki：增加长期工作流说明。 -- `docs/01-workflow.md`：Wiki 更新后的只读镜像。 -- `dev_scripts/check_harness.py`：检查四组核心规则章节。 -- `tests/test_harness_docs.py`：验证当前 Agent 规则结构。 - -## 验收结果 - -| 验收标准 | 结果 | -|---|---| -| 范围限制不禁止任务必需或仓库强制产物 | 通过 | -| 渐进执行保留安全和高风险前置检查 | 通过 | -| 事实复用包含失效条件和重检例外 | 通过 | -| 最小验收包含完整项目闭环 | 通过 | -| 相邻问题不会自动混入 | 通过 | -| Harness 检查四组章节 | 通过 | -| Wiki、测试和严格检查通过 | 通过 | - -## 测试 - -- 执行命令：`python -m unittest discover -s tests -v` -- 结果：17/17 通过。 -- 执行命令：`python dev_scripts/check_harness.py --strict` -- 结果：通过。 -- 执行命令：`python dev_scripts/sync_wiki_docs.py --check` -- 结果：13/13 映射一致。 -- 执行命令：`python -m compileall -q dev_scripts tests` -- 结果：通过。 -- 执行命令：`git diff --check` -- 结果：通过。 -- **未验证部分**：不同新项目中的实际效率提升需要通过后续任务数据验证。 - -## 相关提交 - -- `d3df733` docs: 增加 Agent 效率与范围控制 (#4) diff --git a/docs/task/5-精简AGENTS重复说明.md b/docs/task/5-精简AGENTS重复说明.md deleted file mode 100644 index daf818d..0000000 --- a/docs/task/5-精简AGENTS重复说明.md +++ /dev/null @@ -1,70 +0,0 @@ - -generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) -wiki_page: Task-5-Simplify-Agents -wiki_url: http://ilaer.eicp.net:8418/opc/dev_harness/wiki/Task-5-Simplify-Agents.- -wiki_revision: 2096d9eee938c7680c1188dd6a5fbe490d1fd69c -synchronized_at: 2026-08-08T03:26:17Z - - -# 5 精简 AGENTS 中重复的解释性内容 - -- 类型：重构 -- 所属 Epic：无 -- 所属 MVP / 版本：无 -- 状态：已完成 -- 日期：2026-08-08 -- Gitea 工单：[opc/dev_harness#5](http://ilaer.eicp.net:8418/opc/dev_harness/issues/5) -- Wiki 页面：Task-5-Simplify-Agents -- Wiki revision：见本地镜像头 - -## 背景与目标 - -AGENTS 中部分工单层级、风险示例和核心文档说明已经由 Wiki 完整维护。本任务把 AGENTS 精简为强制规则入口，降低重复维护，同时保证 Agent 只读入口规则时不会遗漏安全和交付要求。 - -## 最终方案 - -- 工单层级保留单元任务唯一实施、父工单索引和同步要求，详细定义链接开发工作流与业务术语。 -- 归档步骤压缩但保留待验收、Wiki 优先、镜像检查、独立提交、证据回写和验收关闭。 -- 风险示例表改为强制结论，详细示例链接常见修改指南。 -- 核心文档清单改为更新触发条件，详细清单链接新项目初始化指南。 -- dev_scripts 不与业务脚本混放的项目红线保留。 -- Harness 检查关键强制规则文本，防止后续精简误删。 -- 六个现有 Wiki 页面已经承接详细内容，本任务未修改稳定 Wiki 正文。 - -## 修改文件 - -- `AGENTS.md`：精简重复解释并增加现有镜像入口。 -- `dev_scripts/check_harness.py`：检查关键强制规则仍然存在。 - -## 验收结果 - -用户于 2026-08-08 明确验收通过。 - -| 验收标准 | 结果 | -|---|---| -| 所有安全和交付强制规则保留 | 通过 | -| 详细层级、风险和文档清单不再重复 | 通过 | -| 被精简内容均有现有文档入口 | 通过 | -| 单元任务仍是唯一实施单位 | 通过 | -| 高风险修改仍需停止和确认 | 通过 | -| 用户验收前不得关闭工单 | 通过 | -| Harness 和测试通过 | 通过 | - -## 测试 - -- AGENTS 非空规则行：115 降至 102。 -- 执行命令：`python -m unittest discover -s tests -v` -- 结果：17/17 通过。 -- 执行命令：`python dev_scripts/check_harness.py --strict` -- 结果：通过。 -- 执行命令：`python dev_scripts/sync_wiki_docs.py --check` -- 结果：14/14 映射一致。 -- 执行命令：`python -m compileall -q dev_scripts tests` -- 结果：通过。 -- 执行命令：`git diff --check` -- 结果：通过。 -- **未验证部分**：无。 - -## 相关提交 - -- `c9f1bc8` refactor: 精简 AGENTS 重复说明 (#5) diff --git a/docs/task/6-优化ClaudeCode规则入口.md b/docs/task/6-优化ClaudeCode规则入口.md deleted file mode 100644 index 40795b8..0000000 --- a/docs/task/6-优化ClaudeCode规则入口.md +++ /dev/null @@ -1,78 +0,0 @@ - -generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) -wiki_page: Task-6-优化ClaudeCode规则入口 -wiki_url: http://ilaer.eicp.net:8418/opc/dev_harness/wiki/Task-6-%E4%BC%98%E5%8C%96ClaudeCode%E8%A7%84%E5%88%99%E5%85%A5%E5%8F%A3.- -wiki_revision: 321e7016b2fcdf39f5bc6453310b233d00e81f07 -synchronized_at: 2026-08-08T03:26:20Z - - -# 6 优化 Claude Code 规则入口 - -- 类型：重构 -- 所属 Epic：无 -- 所属 MVP / 版本：无 -- 状态：已完成 -- 日期：2026-08-08 -- Gitea 工单：http://ilaer.eicp.net:8418/opc/dev_harness/issues/6 -- Wiki 页面：Task-6-优化ClaudeCode规则入口 -- Wiki revision：见本地镜像头 - -## 背景与目标 - -仓库原有 `CLAUDE.md` 已声明 `AGENTS.md` 是共同规则来源，但仍手工复制了阅读顺序、安全、工单、Wiki、Git 和验收等多条共同规则。两处同时维护容易产生内容漂移。 - -本任务把 `CLAUDE.md` 优化为 Claude Code 的轻量入口：使用官方支持的 `@AGENTS.md` 语法直接导入共同规则，仅在本文件记录 Claude Code 专用差异。 - -## 最终方案 - -- 在根目录 `CLAUDE.md` 中使用独立的 `@AGENTS.md` 导入行。 -- 删除原先重复的共同流程清单，仅保留三条入口说明。 -- 明确 `AGENTS.md` 是共同规则事实来源，共同规则只在其中维护。 -- 当前没有 Claude Code 特有的项目规则；以后只有平台或工具差异才写入 `CLAUDE.md`。 -- 将 `CLAUDE.md` 加入 Harness 必需文件。 -- 新增入口检查，要求精确的独立导入行和事实来源说明。 -- 新增自动化测试，覆盖正常入口和缺失导入两种情况。 -- 稳定流程语义未变化，因此没有修改稳定 Wiki 主题页。 - -实施结果与建单方案一致。 - -## 修改文件 - -- `CLAUDE.md`：改为导入式 Claude Code 入口，删除重复共同规则。 -- `dev_scripts/check_harness.py`：增加必需文件和 Claude Code 入口检查。 -- `tests/test_harness_docs.py`：增加入口正向测试和缺失导入失败测试。 -- `wiki-docs.json`：登记本任务 Wiki 归档镜像。 -- `docs/task/6-优化ClaudeCode规则入口.md`：本页的自动导出镜像。 - -## 验收结果 - -用户于 2026-08-08 明确验收通过。 - -| 验收标准 | 结果 | -|---|---| -| 根目录文件名为 `CLAUDE.md` | 通过 | -| 使用 `@AGENTS.md` 导入共同规则 | 通过 | -| 不再复制大段共同流程 | 通过，由 24 行精简为 9 行 | -| 共同规则只维护在 `AGENTS.md` | 通过 | -| Harness 检测缺失入口或导入 | 通过 | -| 测试、严格检查和 Wiki 镜像检查 | 通过 | -| 实现和归档提交分离 | 通过 | - -## 测试 - -- 执行命令：`python -m unittest discover -s tests -v` -- 结果：19/19 通过。 -- 执行命令：`python dev_scripts/check_harness.py --strict` -- 结果：通过。 -- 执行命令：`python dev_scripts/sync_wiki_docs.py --check` -- 结果：归档前 15/15 映射一致；归档后将重新检查 16/16。 -- 执行命令：`python -m compileall -q dev_scripts tests` -- 结果：通过。 -- 执行命令：`git diff --check` -- 结果：通过。 -- **未验证部分**：未启动 Claude Code 交互会话执行 `/memory`；导入语法依据 Claude Code 官方文档，并由仓库检查保证格式。 - -## 相关提交 - -- `2adb30a` `refactor: 优化 Claude Code 规则入口 (#6)` -- 归档提交哈希在提交后回写 Gitea 工单，避免归档自引用。 diff --git a/docs/task/7-ClaudeCode模型路由.md b/docs/task/7-ClaudeCode模型路由.md deleted file mode 100644 index fefa70f..0000000 --- a/docs/task/7-ClaudeCode模型路由.md +++ /dev/null @@ -1,81 +0,0 @@ - -generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) -wiki_page: Task-7-ClaudeCode模型路由 -wiki_url: http://ilaer.eicp.net:8418/opc/dev_harness/wiki/Task-7-ClaudeCode%E6%A8%A1%E5%9E%8B%E8%B7%AF%E7%94%B1.- -wiki_revision: cfd37f7beab92133e1528104df9553e3e7835aff -synchronized_at: 2026-08-08T03:26:21Z - - -# 7 Claude Code 模型路由 - -- 类型：开发规则优化 -- 所属 Epic：无 -- 所属 MVP / 版本：无 -- 状态：已完成 -- 日期：2026-08-08 -- Gitea 工单：http://ilaer.eicp.net:8418/opc/dev_harness/issues/7 -- Wiki 页面：Task-7-ClaudeCode模型路由 -- Wiki revision：见本地镜像头 - -## 背景与目标 - -Claude Code 已通过 `CLAUDE.md` 导入共同开发规则，但没有说明 Opus、Sonnet 和 Haiku 应如何按任务复杂度分工。若每个任务固定依次调用三个模型，会增加重复上下文、Token 和等待时间；如果只用提示语要求 Haiku 只读，又不能真正限制其工具权限。 - -本任务在 Claude Code 专用入口中增加按需模型路由、结构化交接和 Haiku 只读边界。 - -## 最终方案 - -- 目标、范围和修改位置明确的任务默认由 Sonnet 分析、建单和实施。 -- 模糊需求、复杂根因、跨模块架构或高风险任务由 Opus/`opusplan` 制定方案。 -- Opus 方案必须先由用户确认，再交给 Sonnet 创建工单和实施。 -- Haiku 仅用于范围明确的文档、代码入口、日志事实和调用关系检索。 -- Haiku 不承担最终根因、技术方案、风险等级和验收结论。 -- 当前模型足够时不升级，不固定依次调用三个模型。 -- Agent 只交接结构化事实、假设、范围、风险、证据位置和未知项，减少大段重复上下文。 -- Haiku 只读必须由工具权限实现；本任务未创建子 Agent 配置，因此未配置只读权限时不得调用 Haiku 处理项目内容。 -- Harness 检查三个新增章节及关键边界，防止后续误删。 -- 未写死具体模型版本，继续使用模型别名。 - -实施结果与已确认方案一致。 - -## 修改文件 - -- `CLAUDE.md`：增加模型路由、Agent 交接和 Haiku 只读约束。 -- `dev_scripts/check_harness.py`：增加 Claude Code 路由规则的结构检查。 -- `wiki-docs.json`：登记本任务 Wiki 归档镜像。 -- `docs/task/7-ClaudeCode模型路由.md`：本页的自动导出镜像。 - -## 验收结果 - -用户于 2026-08-08 明确验收通过。 - -| 验收标准 | 结果 | -|---|---| -| 保留 `@AGENTS.md` 导入和共同规则来源说明 | 通过 | -| 包含模型路由、Agent 交接和 Haiku 只读约束 | 通过 | -| 不要求每个任务依次调用三个模型 | 通过 | -| Opus 方案经用户确认后由 Sonnet 实施 | 通过 | -| Haiku 不做最终决策 | 通过 | -| Haiku 只读要求工具权限实施 | 通过 | -| 不写死具体模型版本 | 通过 | -| Harness、测试和镜像检查 | 通过 | -| 实现和归档提交分离 | 通过 | - -## 测试 - -- 执行命令：`python -m unittest discover -s tests -v` -- 结果：19/19 通过。 -- 执行命令：`python dev_scripts/check_harness.py --strict` -- 结果：通过。 -- 执行命令：`python dev_scripts/sync_wiki_docs.py --check` -- 结果：归档前 16/16 映射一致；归档后重新检查 17/17。 -- 执行命令：`python -m compileall -q dev_scripts tests` -- 结果：通过。 -- 执行命令：`git diff --check` -- 结果：通过。 -- **未验证部分**：未创建或运行 Haiku 只读子 Agent，未执行多模型 Token/耗时基准；这些均不在本任务范围内。 - -## 相关提交 - -- `3bfe752` `docs: 增加 Claude Code 模型路由 (#7)` -- 归档提交哈希在提交后回写 Gitea 工单，避免归档自引用。 diff --git a/docs/task/8-最小工单依赖规则.md b/docs/task/8-最小工单依赖规则.md deleted file mode 100644 index a8195d6..0000000 --- a/docs/task/8-最小工单依赖规则.md +++ /dev/null @@ -1,85 +0,0 @@ - -generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) -wiki_page: Task-8-最小工单依赖规则 -wiki_url: http://ilaer.eicp.net:8418/opc/dev_harness/wiki/Task-8-%E6%9C%80%E5%B0%8F%E5%B7%A5%E5%8D%95%E4%BE%9D%E8%B5%96%E8%A7%84%E5%88%99.- -wiki_revision: e9a890b18380bfbc02b7a292b8bed95cba8468a0 -synchronized_at: 2026-08-10T04:00:14Z - - -# 8 最小工单依赖规则 - -- 类型：开发流程优化 -- 所属 Epic：无 -- 所属 MVP / 版本：无 -- 状态：已完成 -- 日期：2026-08-10 -- Gitea 工单：http://ilaer.eicp.net:8418/opc/dev_harness/issues/8 -- Wiki 页面：Task-8-最小工单依赖规则 -- Wiki revision：见本地镜像头 - -## 背景与目标 - -项目已经允许建立后续工单，并定义了“待实施”和“阻塞”，但单元任务模板没有前置依赖和并行信息，Agent 实施前也没有明确的依赖检查步骤。 - -本任务采用最小实现：工单显式声明依赖，Agent 实施前人工检查，Harness 只检查模板字段存在，不把 DevHarness 扩展为自动项目管理系统。 - -## 最终方案 - -- 单元任务模板增加“依赖与并行”章节，记录前置工单、是否允许并行和原因。 -- 建立新工单不要求其他工单完成，也不按工单编号限制实施顺序。 -- Agent 开始修改前检查已声明的前置工单。 -- 没有前置工单、前置已完成或明确允许并行时，可以进入“进行中”。 -- 前置未完成且存在真实依赖时不得实施，工单保持“待实施”。 -- 允许并行必须说明不存在实施冲突的原因。 -- 已进入实施后遇到计划外、当前无法解除的问题时才使用“阻塞”。 -- 依赖满足后，任务仍须拥有独立范围、提交、测试和回退方式。 -- Harness 检查模板章节及三个字段，并增加缺失字段测试。 -- 没有增加自动依赖图、联网查询、自动状态门禁或新脚本。 - -实施结果与已确认方案一致。 - -## 修改文件 - -- `AGENTS.md`：增加实施前依赖检查及状态边界。 -- `.gitea/issue_template/task.md`：增加“依赖与并行”字段。 -- `dev_scripts/check_harness.py`：检查模板依赖字段。 -- `tests/test_harness_docs.py`：验证缺失依赖字段会被报告。 -- `docs/01-workflow.md`：Development-Workflow Wiki 的只读镜像。 -- `docs/03-business-rules-and-glossary.md`：Business-Rules-and-Glossary Wiki 的只读镜像。 -- `wiki-docs.json`：登记本任务 Wiki 归档镜像。 -- `docs/task/8-最小工单依赖规则.md`：本页的自动导出镜像。 - -## 验收结果 - -用户于 2026-08-10 明确验收通过。 - -| 验收标准 | 结果 | -|---|---| -| 模板包含依赖与并行三个字段 | 通过 | -| 建单不受其他未完成工单限制 | 通过 | -| 实施前检查声明的前置工单 | 通过 | -| 待实施和阻塞边界明确 | 通过 | -| 允许并行必须写明原因 | 通过 | -| Harness 检测字段缺失 | 通过 | -| 未增加自动门禁或新脚本 | 通过 | -| Wiki 先更新、确认再导出 | 通过 | -| 测试和严格检查 | 通过 | - -## 测试 - -- 执行命令：`python -m unittest discover -s tests -v` -- 结果：20/20 通过。 -- 执行命令：`python dev_scripts/check_harness.py --strict` -- 结果：通过。 -- 执行命令：`python dev_scripts/sync_wiki_docs.py --check` -- 结果：归档前 17/17 映射一致；归档后重新检查 18/18。 -- 执行命令：`python -m compileall -q dev_scripts tests` -- 结果：通过。 -- 执行命令：`git diff --check` -- 结果：通过。 -- **未验证部分**：没有自动查询 Gitea 前置工单状态；这是已确认的非目标，依赖由 Agent 在实施前人工检查。 - -## 相关提交 - -- `a59e3b5` `feat: 增加最小工单依赖规则 (#8)` -- 归档提交哈希在提交后回写 Gitea 工单，避免归档自引用。 diff --git a/docs/task/9-Agent自然语言快捷指令.md b/docs/task/9-Agent自然语言快捷指令.md deleted file mode 100644 index 2a5c123..0000000 --- a/docs/task/9-Agent自然语言快捷指令.md +++ /dev/null @@ -1,94 +0,0 @@ - -generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) -wiki_page: Task-9-Agent自然语言快捷指令 -wiki_url: http://ilaer.eicp.net:8418/opc/dev_harness/wiki/Task-9-Agent%E8%87%AA%E7%84%B6%E8%AF%AD%E8%A8%80%E5%BF%AB%E6%8D%B7%E6%8C%87%E4%BB%A4.- -wiki_revision: 6aedbcf63ad86892681c5f9226c4679dbbe16646 -synchronized_at: 2026-08-10T04:00:17Z - - -# 9 Agent 自然语言快捷指令 - -- 类型：开发流程优化 -- 所属 Epic：无 -- 所属 MVP / 版本：无 -- 状态：已完成 -- 日期：2026-08-10 -- Gitea 工单：http://ilaer.eicp.net:8418/opc/dev_harness/issues/9 -- Wiki 页面：Task-9-Agent自然语言快捷指令 -- Wiki revision：见本地镜像头 - -## 背景与目标 - -Agent 过去能够结合上下文理解“建工单，做”，但仓库没有正式定义快捷指令的名称、允许操作和停止位置，不同平台或会话可能产生不同理解。 - -本任务定义一组共享的自然语言快捷指令，让 Claude Code、Codex 和维护者使用同一套工作流语义，同时保持方案确认、依赖、安全、Wiki 主源和人工验收门禁。 - -## 最终方案 - -正式定义以下 8 个快捷指令： - -- `只分析`：只读检查并给出方案，停在等待确认。 -- `建工单`：根据已确认方案创建工单，建单后停止。 -- `执行工单 #N`：实施现有工单并完成提交、归档和证据，停在“待验收”。 -- `建工单并做`：依次建单和执行；`建工单，做`、`建工单,做` 是等价表达，停在“待验收”。 -- `继续工单 #N`：从首个未完成步骤继续，不重复仍然有效的检查。 -- `检查工单 #N`：只读核对范围、验收、测试和证据，不自动修复。 -- `同步文档`：Wiki → `docs/` 同步并检查，不修改 Wiki、不自动提交。 -- `#N 验收通过`：仅在用户明确验收后完成验收归档、推送、父工单同步并关闭任务。 - -补充边界： - -- 快捷指令只是自然语言别名，不绕过任何强制规则。 -- 方案未确认时，建单或实施类指令停在方案确认。 -- 前置依赖未满足且不允许并行时，实施类指令停在“待实施”。 -- 除 `#N 验收通过` 外，不关闭待验收工单。 -- Gitea 工单保留讨论过程，本地只保存 Wiki 最终任务归档镜像。 -- Harness 检查 Wiki 章节和 8 个指令名称。 -- 没有增加脚本、Skill、Slash Command 或自动编排器。 - -实施结果与已确认方案一致。 - -## 修改文件 - -- `AGENTS.md`：增加 8 个共享自然语言快捷指令和强制边界。 -- `dev_scripts/check_harness.py`：检查 Wiki 章节和快捷指令名称。 -- `tests/test_harness_docs.py`：调整 Agent 规则测试名称以覆盖全部必需规则。 -- `docs/01-workflow.md`：Development-Workflow Wiki 的只读镜像。 -- `wiki-docs.json`：登记本任务 Wiki 归档镜像。 -- `docs/task/9-Agent自然语言快捷指令.md`：本页的自动导出镜像。 - -## 验收结果 - -用户于 2026-08-10 明确验收通过。 - -| 验收标准 | 结果 | -|---|---| -| 8 个指令有明确语义和停止位置 | 通过 | -| 建工单并做及逗号变体停在待验收 | 通过 | -| 只有明确验收指令会关闭工单 | 通过 | -| 只分析和检查工单默认只读 | 通过 | -| 同步文档不修改 Wiki、不自动提交 | 通过 | -| 不绕过确认、依赖、安全和验收 | 通过 | -| 未新增平台专用命令或脚本 | 通过 | -| Wiki 先更新并确认再导出 | 通过 | -| Harness、测试和镜像检查 | 通过 | -| 实现和归档提交分离 | 通过 | - -## 测试 - -- 执行命令：`python -m unittest discover -s tests -v` -- 结果：20/20 通过。 -- 执行命令：`python dev_scripts/check_harness.py --strict` -- 结果：通过。 -- 执行命令：`python dev_scripts/sync_wiki_docs.py --check` -- 结果：归档前 18/18 映射一致；归档后重新检查 19/19。 -- 执行命令：`python -m compileall -q dev_scripts tests` -- 结果：通过。 -- 执行命令：`git diff --check` -- 结果：通过。 -- **未验证部分**：没有实现或运行平台专用 Slash Command、Skill 或自动编排器，这些是已确认的非目标。 - -## 相关提交 - -- `10e82d6` `feat: 定义 Agent 快捷指令 (#9)` -- 归档提交哈希在提交后回写 Gitea 工单，避免归档自引用。 diff --git a/docs/templates/deployment.md b/docs/templates/deployment.md deleted file mode 100644 index fdeaace..0000000 --- a/docs/templates/deployment.md +++ /dev/null @@ -1,282 +0,0 @@ - -generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) -wiki_page: Deployment-Template -wiki_url: https://git.ilapage.cn/OPC/dev_harness/wiki/Deployment-Template.- -wiki_revision: 948321c2f3e4fd7a2923f2764fa8c81c18099a56 -synchronized_at: 2026-08-19T01:52:18Z - - -# 部署文档模板 - -> 使用说明：本页是 DevHarness 模板，不描述任何真实服务。有常驻服务的项目复制本页，在自己的 Gitea Wiki 创建 `Deployment-and-Operations` 页面，并在本项目 `wiki-docs.json` 增加映射（建议镜像到 `docs/10-deployment-and-operations.md`）。填写时删除全部说明性文字，不得保留“待填写”后直接交付。没有常驻服务的项目不要创建部署页，在初始化工单记录原因即可。 -> -> 本模板面向项目内部维护者。面向客户或外部运维岗位的部署说明属于交付文档，使用[岗位文档模板](Audience-Document-Template.-)。 -> -> 标准栈为 nginx 反向代理 + supervisor 进程托管，示例按 Python 服务（gunicorn / uvicorn）编写。实际技术栈不同时替换命令，但保留章节结构和“每条命令写明预期结果”的要求。 - -## 本页用途 - -让维护者能够在一台干净的服务器上完成首次部署、日常运维、健康检查和回滚。所有命令默认以具备 sudo 权限的账号在服务器上执行，示例以 Linux 为主。 - -## 安全边界 - -- 本页只写配置项的**名称和来源**，不写任何真实密码、令牌、私钥、证书内容、生产数据库地址或个人数据。 -- 需要凭据的步骤写明“从哪里取”，例如运维密码库条目名或环境变量名。 -- 涉及删除数据、数据库迁移和不可逆操作的步骤必须给出醒目警告、影响范围和回退条件。 - -## 服务概览 - -| 项目 | 内容 | -|---|---| -| 服务名（supervisor program） | `` | -| 代码部署目录 | `/srv/` | -| 运行账号 | `` | -| 运行时 | Python `<3.x>` | -| 应用服务器 | gunicorn / uvicorn | -| 本地监听地址 | `127.0.0.1:<8000>` | -| 进程数 | `` | -| 对外域名与路径 | `https:///` | -| 依赖的外部服务 | 数据库 / 缓存 / 对象存储 / 无 | -| 日志目录 | `/var/log//` | - -服务只监听 `127.0.0.1`，不直接对外暴露端口；所有外部访问经 nginx 转发。 - -## 环境要求 - -| 组件 | 版本要求 | 检查命令 | 预期结果 | -|---|---|---|---| -| 操作系统 | `` | `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/ --shell /usr/sbin/nologin -sudo mkdir -p /srv/ /var/log/ -sudo chown -R : /srv/ /var/log/ -``` - -**预期结果**：`id ` 输出该账号；两个目录存在且属主为 ``。 - -服务账号使用 `nologin`，不允许直接登录。 - -### 2. 取得代码 - -```bash -sudo -u git clone <仓库地址> /srv//app -cd /srv//app && sudo -u git rev-parse HEAD -``` - -**预期结果**：输出本次部署的完整提交哈希，记录到部署记录中。 - -### 3. 安装依赖 - -```bash -sudo -u python3 -m venv /srv//venv -sudo -u /srv//venv/bin/pip install -r /srv//app/requirements.txt -``` - -**预期结果**：pip 以 `Successfully installed ...` 结束，无 ERROR。 - -### 4. 落位配置文件 - -```bash -sudo install -o -g -m 600 /dev/null /srv//app.env -sudo -u vi /srv//app.env -``` - -**预期结果**：`ls -l /srv//app.env` 显示权限 `-rw-------` 且属主为 ``。 - -配置项清单见下方“配置与凭据来源”。配置文件不进入 Git。 - -### 5. 数据库初始化或迁移 - - - -> **注意**：迁移可能不可逆。执行前必须先备份，并确认回退方式。 - -```bash -sudo -u /srv//venv/bin/python -m .manage migrate -``` - -**预期结果**：输出全部迁移已应用，无失败项。 - -## supervisor 配置 - -写入 `/etc/supervisor/conf.d/.conf`： - -```ini -[program:] -command=/srv//venv/bin/gunicorn .wsgi:application --workers --bind 127.0.0.1:<8000> --timeout 60 -directory=/srv//app -user= -environment=PATH="/srv//venv/bin",APP_ENV_FILE="/srv//app.env" -autostart=true -autorestart=true -startsecs=5 -stopasgroup=true -killasgroup=true -stopwaitsecs=30 -stdout_logfile=/var/log//stdout.log -stderr_logfile=/var/log//stderr.log -stdout_logfile_maxbytes=50MB -stdout_logfile_backups=5 -``` - -> 异步框架使用 uvicorn 时把 `command` 换成： -> `/srv//venv/bin/uvicorn .asgi:app --host 127.0.0.1 --port <8000> --workers ` - -不要在 `environment` 里写明文密码或令牌；敏感值放在 `app.env`，由应用读取。 - -加载配置并启动： - -```bash -sudo supervisorctl reread -sudo supervisorctl update -sudo supervisorctl start -sudo supervisorctl status -``` - -**预期结果**：`reread` 输出 `: available`；`status` 显示 `RUNNING` 且 uptime 持续增长。出现 `BACKOFF` 或 `FATAL` 时查看 `stderr.log`。 - -## nginx 配置 - -写入 `/etc/nginx/sites-available/.conf` 并软链到 `sites-enabled`： - -```nginx -server { - listen 80; - server_name ; - - access_log /var/log/nginx/.access.log; - error_log /var/log/nginx/.error.log; - - client_max_body_size <20m>; - - location /static/ { - alias /srv//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>; - } -} -``` - - - -启用并生效： - -```bash -sudo ln -sf /etc/nginx/sites-available/.conf /etc/nginx/sites-enabled/.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，先修正配置。 - - - -## 配置与凭据来源 - -| 配置项 | 用途 | 来源 | 是否敏感 | -|---|---|---|---| -| `APP_ENV_FILE` | 指向配置文件路径 | supervisor 配置 | 否 | -| `` | 数据库连接 | `/srv//app.env`，值取自运维密码库条目 `<条目名>` | 是 | -| `` | 会话与签名 | 同上 | 是 | -| `` | 日志级别 | `/srv//app.env` | 否 | - -敏感值只记录取用位置，不在本页、工单、日志和提交中出现真实内容。 - -## 日常运维 - -| 操作 | 命令 | 预期结果 | -|---|---|---| -| 查看状态 | `sudo supervisorctl status ` | `RUNNING`，uptime 持续增长 | -| 重启服务 | `sudo supervisorctl restart ` | 输出 `stopped` 后 `started` | -| 停止服务 | `sudo supervisorctl stop ` | 输出 `stopped` | -| 实时日志 | `sudo supervisorctl tail -f stderr` | 持续输出应用日志 | -| 应用日志 | `sudo tail -n 200 /var/log//stderr.log` | 输出最近日志 | -| 接入层日志 | `sudo tail -n 200 /var/log/nginx/.error.log` | 输出 nginx 错误 | -| 重载 nginx | `sudo nginx -t && sudo systemctl reload nginx` | 测试通过后无中断生效 | - -修改 supervisor 配置后必须 `reread` + `update`，只 `restart` 不会加载新配置。 - -## 健康检查 - -每次部署、重启和回滚后必须全部执行： - -```bash -sudo supervisorctl status -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://<健康检查路径> -sudo tail -n 50 /var/log//stderr.log -``` - -**预期结果**：状态为 `RUNNING`；两个 `curl` 均返回 `200`；日志无新增异常堆栈。 - -任何一项不符合时不视为部署成功，按“升级与回滚”处理。 - -## 升级与回滚 - -### 升级 - -```bash -cd /srv//app -sudo -u git rev-parse HEAD # 记录当前提交，回滚需要 -sudo -u git fetch --all -sudo -u git checkout <目标提交或标签> -sudo -u /srv//venv/bin/pip install -r requirements.txt -sudo -u /srv//venv/bin/python -m .manage migrate # 无数据库时删除 -sudo supervisorctl restart -``` - -**预期结果**：restart 后 `status` 为 `RUNNING`，随后健康检查全部通过。 - -升级前必须记录当前提交哈希；涉及数据库迁移时必须先备份。 - -### 回滚 - -```bash -cd /srv//app -sudo -u git checkout <升级前记录的提交> -sudo -u /srv//venv/bin/pip install -r requirements.txt -sudo supervisorctl restart -``` - -**预期结果**：健康检查全部通过。 - -> **注意**：已执行的数据库迁移通常不能通过切回代码撤销。存在迁移时必须先确认迁移是否向后兼容；不兼容时按备份恢复流程处理，并停止自行操作、联系负责人。 - -### 备份与恢复 - - - -## 已知限制 - - - -- diff --git a/docs/templates/task-archive.md b/docs/templates/task-archive.md deleted file mode 100644 index 14c543c..0000000 --- a/docs/templates/task-archive.md +++ /dev/null @@ -1,50 +0,0 @@ - -generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) -wiki_page: Task-Archive-Template -wiki_url: https://git.ilapage.cn/OPC/dev_harness/wiki/Task-Archive-Template.- -wiki_revision: 8f8d1bb9c596a79d37631d670aaf95818d74e7c8 -synchronized_at: 2026-08-07T15:54:05Z - - -# <工单号> <标题> - -- 类型：需求 / 缺陷 / 重构 -- 所属 Epic：# -- 所属 MVP / 版本：# -- 状态：待验收 / 已完成 -- 日期：YYYY-MM-DD -- Gitea 工单：<链接> -- Wiki 页面：<页面名> -- Wiki revision：见本地镜像头 - -## 背景与目标 - - - -## 最终方案 - - - -## 修改文件 - -- `<文件>`：<改动说明> - -## 验收结果 - -| 验收标准 | 结果 | -|---|---| -| | 通过 / 未通过 | - -## 测试 - -- 执行命令：`<命令>` -- 结果： -- **未验证部分**： - -## 遗留问题 - - - -## 相关提交 - -- `<提交哈希>` <提交说明> diff --git a/wiki-docs.json b/wiki-docs.json index 85ef559..450f275 100644 --- a/wiki-docs.json +++ b/wiki-docs.json @@ -2,7 +2,7 @@ "schema_version": 1, "gitea_url": "https://git.ilapage.cn", "owner": "OPC", - "repository": "dev_harness", + "repository": "lexgo", "mappings": [ { "page": "Home", @@ -63,6 +63,26 @@ { "page": "Task-Archive-Template", "path": "docs/templates/task-archive.md" + }, + { + "page": "Workload-Estimate", + "path": "docs/10-workload-estimate.md" + }, + { + "page": "LinguaCafe-Requirements", + "path": "docs/01-LinguaCafe需求提取.md" + }, + { + "page": "Go-Architecture-Analysis", + "path": "docs/02-Go复刻与框架选型分析.md" + }, + { + "page": "LinguaCafe-Requirements-Alternative", + "path": "docs/linguacafe-requirements.md" + }, + { + "page": "Go-Analysis-Alternative", + "path": "docs/linguacafe-go-analysis.md" } ] }