lexgo/docs/07-new-project-documentation-setup.md

generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) wiki_page: New-Project-Documentation-Setup wiki_url: https://git.ilapage.cn/OPC/lexgo/wiki/New-Project-Documentation-Setup.- wiki_revision: 1f84d8d38a6052120351da56639d88b70e99f58f synchronized_at: 2026-09-10T06:27:44Z

LexGo 初始化记录

本项目状态与证据边界

2026-09-10 用户确认远端 https://git.ilapage.cn/OPC/lexgo.git；main 已有 DevHarness 引导提交 ecab8995026e57f2c28f307a6aa32b871cb3163f。本轮将本地 LexGo 连接此远端，保留原调研，发布项目主题和工作量，再执行同步与验证。数据库 MySQL 8、治理轻量已确认，产品代码尚未开始。

本轮使用 Gitea API 的原因：已配置 MCP 连接 ilaer.eicp.net:8418，目标却是 git.ilapage.cn，MCP 无法操作该目标。先用目标站点安全配置验证身份和仓库，凭据只读入进程；不复制到代码、日志、工单或 Wiki。目标仓库已启用工单/Wiki，初始页面列表返回 404；先创建 Home 并回读 revision 后才创建其他页面。

发布准备、正文回读、同步校验和产品验收是不同证据。最终本地命令与结果见 Git 提交说明及本轮结果报告；不能把工具单测中的模拟 Wiki 输出当真实线上状态。

现有 docs/task 内容属于上游模板历史，不作为 LexGo 的任务完成记录，也不带入项目镜像。原有四份调研分别作为参考页面保留，数据库分歧以 MySQL 8 决策为准。未创建无实际作用的 Epic/MVP 或任务快照。

当前交付对象为负责人和开发维护者，交付规划、规则和估算。尚无产品部署实例；部署模板仅供后续环境确认后使用，不预建可运行运维手册。

后续产品步骤

完成本文的 Wiki 门禁后，按已确认目标组织 M0 技术验证；工程底座、Python NLP、首发语言与旧数据范围仍需在方案中明确，不把“继续文档初始化”视为整份产品方案批准。

以下为本项目沿用的 DevHarness 初始化规范，示例不代表 LexGo 已执行产品开发。

新项目文档初始化

本页用途

从 DevHarness 创建新项目时，指导 Claude/Codex Agent快速建立可供初级程序员阅读的项目文档。初始化只生成可靠的第一版，不允许 Agent 臆造业务规则、凭据、部署环境或生产数据。

初始化顺序

1. 建立项目边界

由项目负责人确认：

• 项目名称和一句话目标；
• 用户和主要使用场景；
• 技术栈和支持环境；
• Gitea 仓库、默认分支和维护者；
• 安全、权限、数据和发布红线。

把项目专用红线写入根目录或子目录 AGENTS.md。

选择治理模式

使用 DevHarness 创建新项目时默认采用轻量模式，并在 Project-Profile 记录实际模式和理由：

• 目标项目尚未填写治理模式时按轻量模式执行并提示补写，不因此阻塞产品开发；从模板继承的“DevHarness / 标准”文字不代表目标项目已经选择标准模式；
• 轻量模式尤其适合内部、单人、低风险项目，但默认值不限制后续按真实风险升级；
• 只有项目负责人明确选择并记录理由时，才将项目默认值改为标准或高风险；
• 多人协作、对外交付、跨模块接口较多或需要稳定审计时，可以明确选择标准模式；
• 项目整体持续涉及权限、安全、支付、真实个人/生产数据、迁移、并发、删除或不可逆操作时，可以明确选择高风险模式；
• 单个任务风险高于项目默认模式时只升级该任务，不自动升级整个项目；不为可能发生的情况预设额外门禁；
• DevHarness 上游模板自身继续采用标准模式。

治理模式只裁剪工单、原型、测试和文档流程，不覆盖凭据、授权边界和真实测试证据。使用虚构手机号等测试数据时记录其为虚构数据即可，无需为了形式执行脱敏流程；来源不明或来自真实用户时按已确认的数据处理规则执行。

需求总览启用条件

从模板创建项目时保留 Product-Requirements-Overview 这一核心页面。仅有探索性想法时可以只记录已确认目标和待确认项；形成 MVP、长期需求超过少量工单或开始制作原型时，必须建立并持续维护需求索引，把需求领域、状态、主题 Wiki、工单、原型和验收入口关联起来。不要复制完整工单或聊天记录。

2. 选择建设基线

确定技术方案前，优先评估是否存在功能和架构匹配、持续维护、许可证兼容且工程流程完善的开源项目。这里要求的是“先评估”，不是强制采用开源项目，也不能只根据知名度、Star 数量或演示效果决定。

至少检查：

• 核心功能、架构和支持平台是否匹配，哪些能力可以直接保留；
• 许可证是否允许预期的使用、修改、分发和商业模式；不确定时交由负责人或法律专业人员确认；
• 最近维护活跃度、发布频率、Issue 处理和社区或维护团队的持续性；
• 已知安全问题、依赖健康度、供应链风险和安全响应方式；
• 自动化测试、CI、发布、升级、回退和文档是否足以支持长期维护；
• 定制、学习、迁移和后续跟踪上游的总成本是否低于从零开发；
• 是否能够固定上游仓库和基线版本，并建立合并上游更新、兼容验证和退出方案。

满足适配、许可证、安全、维护和总成本条件时，优先在该基线上二次开发。不存在合适基线，或引入后会增加不可接受的许可证、安全、架构或维护风险时，可以从零开发，但必须记录排除候选项目和选择从零开发的主要原因。

采用开源基线时，在 Project-Profile 的“技术栈与运行环境”记录上游项目名称、仓库地址、基线版本或提交、许可证、保留能力、定制范围和上游升级策略。尚未确认的候选和取舍先写入首个技术方案工单，不得把假设写成项目事实。

工程基线裁剪

所有项目采用最小工程基线，不按项目规模免除事实和验收要求：

• 用完整 Git commit 和核验日期固定“当前事实”的代码基线；
• 分开记录“当前已经实现什么”和“目标规范要求什么”，不得用目标描述宣称现有能力；
• 写明证据路径、可确认行为、未覆盖范围和证据不能证明什么；
• 明确目标、非目标、安全边界和可判定的验收标准；
• 跨子项目接口或契约指定唯一事实来源和各端验证命令。

当前事实以指定 commit 的代码、可执行测试和运行证据为依据；目标行为以人工批准的契约、ADR 和业务规则为依据。两者冲突时登记为带编号的差距或缺陷，不允许现有错误实现覆盖目标规范，也不允许目标设计冒充当前实现。

出现跨团队或跨仓库协作、外部交付、接口或状态机复杂、权限安全、迁移并发、明显文档漂移等情况时，采用增强工程基线：按需增加 GAP-ID 差距表、带状态的 ADR、接口与数据契约、需求追踪测试矩阵，以及 PR、RC、Definition of Done 分层门禁。SRS、SAD、安全、运维和测试文档按风险与读者选择，不强制小型单人项目建立完整文档集。

判断案例

以下案例用于说明判断方式，不代表必须选择某种技术或具体开源项目。

案例一：适合基于成熟项目二次开发

计划开发企业内部管理系统。候选项目已经具备用户、权限、审计日志、基础数据管理和自动化测试；功能与目标架构基本匹配，许可证允许预期使用，项目持续维护，发布与升级流程完整，预计只需修改业务模块和界面。

• 结论：优先基于该项目二次开发。
• 原因：可以减少通用功能的开发和验证成本，定制范围可控。
• 记录：上游仓库、基线版本、许可证、保留功能、定制模块和上游升级方式。

案例二：项目成熟但许可证不兼容

候选项目功能完整、维护活跃、文档充分，但许可证与当前产品的闭源分发、商业模式或交付条件不兼容。

• 结论：不采用该项目作为建设基线。
• 原因：技术成熟度不能消除许可证风险；不确定结论必须交由负责人或法律专业人员确认。
• 记录：候选项目、许可证限制、确认人员和排除原因。

案例三：功能相似但改造成本过高

候选项目表面上覆盖大部分功能，但数据模型、权限体系和部署结构与目标项目差异很大，需要大量删除模块、重写主要接口，并长期维护上游冲突。

• 结论：不直接基于完整项目二次开发，可以评估只复用合适的组件或设计思路。
• 原因：二次开发的总成本、理解成本和长期维护风险已经高于自主实现核心业务。
• 记录：主要结构差异、改造估算、长期维护风险和最终选择。

案例四：只复用成熟框架或组件

没有功能高度匹配的完整开源产品，但存在成熟的应用框架、更新组件、日志组件或通信库。

• 结论：从零开发业务功能，同时复用经过评估的成熟框架或组件。
• 原因：复用基础能力不等于必须采用完整产品，可以避免被不匹配的业务架构绑定。
• 记录：每个依赖的用途、版本、许可证、安全边界、升级方式和可替换方案。

每个案例的实际评估都必须记录候选项目、判断依据、最终选择、未采用原因，以及升级或退出方式。

3. 识别子项目与交付单元

先判断仓库中有几个应用、服务、客户端、库或其他可独立交付的部分。对每个部分确认：

• 职责和目录边界；
• 技术栈、依赖和支持环境；
• 构建、测试和运行命令；
• 是否拥有独立版本号和发布方式；
• 适用的根目录或子目录 AGENTS.md；
• 与其他子项目共享的接口、数据或业务流程；
• 共享契约的唯一事实来源和兼容要求。

把结果写入 Project-Profile 的“子项目与交付单元”。单应用项目只填写一个交付单元；多应用单仓库为规则不同的目录增加子目录 AGENTS.md，但不因为技术栈不同自动拆仓，也不强制统一版本和发布周期。

4. 建立 Gitea

创建远端仓库并完成允许的初始引导提交，开启工单和 Wiki；必须先有远端仓库，才能填写该仓库的线上 Wiki。配置项目已有的 Gitea MCP 和安全凭据；优先使用 MCP，MCP 不可用或不支持所需写操作时才回退到 Gitea API，并在初始化工单记录原因。凭据只通过环境或 MCP 安全配置提供。

引导提交后按项目明确选择的治理模式判断是否需要工单；尚未选择时按轻量模式执行并提示补写，不因此阻塞产品开发。轻量模式的明确小 Bug、局部 UI 和单模块低风险调整可以直接实施；完整独立需求、新页面、跨模块功能和中高风险变化必须先有单元任务工单。开始产品代码前仍须通过第 8 步的线上 Wiki 初始化门禁。

5. 修改镜像配置

把 wiki-docs.json 中的地址、owner 和 repository 改成新项目；只保留核心主题映射。可选任务快照不逐页登记，默认任务流程不创建。

确认当前目录确实是新项目副本、且 DevHarness 历史归档快照不需要保留后，可以移除对应 docs/task/ 文件。不要在原 DevHarness 仓库或已有业务项目中执行这项清理。

不要把 PAT 写入配置。

6. Agent 检查项目事实

Agent 只读检查：

• README、配置和依赖文件；
• 启动入口；
• 主要模块和目录规则；
• 测试、格式和静态检查命令；
• 日志、示例配置和测试数据；
• 已存在的接口、数据模型和状态。

区分“代码中确认的事实”“负责人确认的业务规则”和“仍待确认的假设”。

7. 确定交付对象和文档

由项目负责人确认哪些岗位或客户会实际使用、部署、管理、支持、集成或验收产品，并为每类对象确定：

• 需要完成的工作；
• 所需文档类型；
• 文档可见范围；
• 适用版本、负责人和验证人；
• 不得对外披露的内部信息。

按照交付文档指南选择文档，使用岗位文档模板按需创建。没有明确读者的文档不创建，不预建空白的用户手册、管理员手册或运维手册。

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 步确认的受众创建。

部署页按需创建，不属于必需核心页面：项目负责人确认存在需要部署的常驻服务时，复制部署文档模板在本项目 Wiki 建立 Deployment-and-Operations 页面，并在本项目 wiki-docs.json 增加映射（建议镜像到 docs/10-deployment-and-operations.md）；确认没有常驻服务时，在初始化工单记录原因，不创建该页面。

9. 人工确认

项目负责人至少确认：

• 一句话目标和业务术语；
• 关键业务规则和状态；
• 权限、安全和数据边界；
• 真实运行、测试和部署命令；
• 本项目是否有需要部署的常驻服务；
• 哪些修改属于高风险；
• 交付对象、文档可见范围和外部信息边界。

10. 导出镜像并检查

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 或负责人；
• 项目采用哪个建设基线，为什么适合二次开发，或者为什么选择从零开发；
• 采用开源基线时，上游仓库、基线版本、许可证、定制范围和升级策略是什么；
• 项目包含哪些子项目和独立交付单元，各自怎样构建、测试和发布；
• 跨子项目共享什么接口或契约，其唯一事实来源在哪里；
• 项目需要向哪些岗位交付什么文档，以及哪些内容不能对外提供。

回答不了的问题应继续补充主题文档，而不是堆入任务归档。