docs: evaluate open-source project baselines (#15)

2026-08-16 19:30:22 +08:00
parent d1f55f9df3
commit a959fc385d
3 changed files with 41 additions and 13 deletions
@@ -90,8 +90,9 @@ CORE_DOCUMENT_REQUIREMENTS = {
    ),
    "docs/07-new-project-documentation-setup.md": (
        "## 初始化顺序",
-        "### 2. 识别子项目与交付单元",
-        "### 6. 确定交付对象和文档",
+        "### 2. 选择建设基线",
+        "### 3. 识别子项目与交付单元",
+        "### 7. 确定交付对象和文档",
        "## 完成标准",
    ),
    "docs/08-existing-project-adoption.md": (
@@ -2,8 +2,8 @@
 generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
 wiki_page: New-Project-Documentation-Setup
 wiki_url: http://ilaer.eicp.net:8418/opc/dev_harness/wiki/New-Project-Documentation-Setup.-
-wiki_revision: cf49e125e7e73d8c818df61153d76abac6abfaaa
-synchronized_at: 2026-08-16T11:19:05Z
+wiki_revision: 0d603f4d71a28c3de346b30dc3f450f7917c50e9
+synchronized_at: 2026-08-16T11:29:05Z
 <!-- gitea-wiki-mirror:end -->

 # 新项目文档初始化
@@ -26,7 +26,25 @@ synchronized_at: 2026-08-16T11:19:05Z

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

-### 2. 识别子项目与交付单元
+### 2. 选择建设基线
+
+确定技术方案前，优先评估是否存在功能和架构匹配、持续维护、许可证兼容且工程流程完善的开源项目。这里要求的是“先评估”，不是强制采用开源项目，也不能只根据知名度、Star 数量或演示效果决定。
+
+至少检查：
+
+- 核心功能、架构和支持平台是否匹配，哪些能力可以直接保留；
+- 许可证是否允许预期的使用、修改、分发和商业模式；不确定时交由负责人或法律专业人员确认；
+- 最近维护活跃度、发布频率、Issue 处理和社区或维护团队的持续性；
+- 已知安全问题、依赖健康度、供应链风险和安全响应方式；
+- 自动化测试、CI、发布、升级、回退和文档是否足以支持长期维护；
+- 定制、学习、迁移和后续跟踪上游的总成本是否低于从零开发；
+- 是否能够固定上游仓库和基线版本，并建立合并上游更新、兼容验证和退出方案。
+
+满足适配、许可证、安全、维护和总成本条件时，优先在该基线上二次开发。不存在合适基线，或引入后会增加不可接受的许可证、安全、架构或维护风险时，可以从零开发，但必须记录排除候选项目和选择从零开发的主要原因。
+
+采用开源基线时，在 Project-Profile 的“技术栈与运行环境”记录上游项目名称、仓库地址、基线版本或提交、许可证、保留能力、定制范围和上游升级策略。尚未确认的候选和取舍先写入首个技术方案工单，不得把假设写成项目事实。
+
+### 3. 识别子项目与交付单元

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

@@ -40,11 +58,11 @@ synchronized_at: 2026-08-16T11:19:05Z

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

-### 3. 建立 Gitea
+### 4. 建立 Gitea

 创建远端仓库并完成允许的初始引导提交。开启工单和 Wiki。任何产品功能开发在引导提交后都必须先有单元任务工单。

-### 4. 修改镜像配置
+### 5. 修改镜像配置

 把 `wiki-docs.json` 中的地址、owner 和 repository 改成新项目；只保留核心主题映射，任务归档不逐页登记。

@@ -52,7 +70,7 @@ synchronized_at: 2026-08-16T11:19:05Z

 不要把 PAT 写入配置。

-### 5. Agent 检查项目事实
+### 6. Agent 检查项目事实

 Agent 只读检查：

@@ -65,7 +83,7 @@ Agent 只读检查：

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

-### 6. 确定交付对象和文档
+### 7. 确定交付对象和文档

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

@@ -77,7 +95,7 @@ Agent 只读检查：

 按照[交付文档指南](Delivery-Documentation-Guide.-)选择文档，使用[岗位文档模板](Audience-Document-Template.-)按需创建。没有明确读者的文档不创建，不预建空白的用户手册、管理员手册或运维手册。

-### 7. 先创建线上 Wiki
+### 8. 先创建线上 Wiki

 至少创建或填写：

@@ -93,9 +111,9 @@ Agent 只读检查：
 10. Audience-Document-Template；
 11. Task-Archive-Template。

-Home 给出建议阅读顺序；每个命令必须有预期结果；代码地图必须指出入口和测试位置。具体岗位文档仅按第 5 步确认的受众创建。
+Home 给出建议阅读顺序；每个命令必须有预期结果；代码地图必须指出入口和测试位置。具体岗位文档仅按第 7 步确认的受众创建。

-### 8. 人工确认
+### 9. 人工确认

 项目负责人至少确认：

@@ -106,7 +124,7 @@ Home 给出建议阅读顺序；每个命令必须有预期结果；代码地图
 - 哪些修改属于高风险；
 - 交付对象、文档可见范围和外部信息边界。

-### 9. 导出镜像并检查
+### 10. 导出镜像并检查

 ```powershell
 python dev_scripts/sync_wiki_docs.py
@@ -126,6 +144,8 @@ python -m unittest discover -s tests -v
 - 常用功能从哪个目录和入口开始读；
 - 一个简单修改通常要改哪里、验证什么；
 - 哪些情况必须停止并交给 Agent 或负责人；
+- 项目采用哪个建设基线，为什么适合二次开发，或者为什么选择从零开发；
+- 采用开源基线时，上游仓库、基线版本、许可证、定制范围和升级策略是什么；
 - 项目包含哪些子项目和独立交付单元，各自怎样构建、测试和发布；
 - 跨子项目共享什么接口或契约，其唯一事实来源在哪里；
 - 项目需要向哪些岗位交付什么文档，以及哪些内容不能对外提供。
@@ -58,6 +58,13 @@ class CoreDocumentTests(unittest.TestCase):
        self.assertIn(path, CORE_DOCUMENT_REQUIREMENTS)
        self.assertIn("## 可复制 Agent 指令", CORE_DOCUMENT_REQUIREMENTS[path])

+    def test_new_project_setup_requires_baseline_selection(self) -> None:
+        required = CORE_DOCUMENT_REQUIREMENTS[
+            "docs/07-new-project-documentation-setup.md"
+        ]
+        self.assertIn("### 2. 选择建设基线", required)
+        self.assertIn("### 3. 识别子项目与交付单元", required)
+
    def test_missing_or_wrong_core_mapping_is_reported(self) -> None:
        errors = core_mapping_errors({"Home": "docs/wrong.md"})
        self.assertTrue(any("Home -> docs/README.md" in error for error in errors))