OPC/dev_harness
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

合并 dev_scripts 入口为单一 harness.py #23

New Issue
Closed
opened 2026-08-18 21:24:33 +08:00 by ila · 2 comments
ila commented 2026-08-18 21:24:33 +08:00
Owner
Copy Link
Copy Source

基本信息

  • 类型：重构
  • 所属 Epic：无
  • 所属 MVP / 版本：无
  • 阶段：实施

依赖与并行

  • 前置工单：#22
  • 是否允许与前置工单并行：否
  • 原因：#22 会在 AGENTS.md 内联常用命令表，本工单会改写同一张表中的命令名。串行实施避免同段落冲突。

子项目影响

  • 仅影响的子项目 / 交付单元：DevHarness 模板
  • 是否跨子项目：否
  • 是否修改共享接口或契约：是。命令行入口是 DevHarness 对下游业务项目的公开契约，唯一事实来源为 Wiki 页面 Project-Profile 的「常用命令」表。
  • 各子项目需要执行的验证：python dev_scripts/harness.py check --strict、python -m unittest discover -s tests -v

原始需求

  • 来源：用户对话
  • 提出时间：2026-08-18
  • 关键原话或脱敏摘要：用户要求「节省开发时间和 token」，确认「先做 B + E」；就旧脚本名的处理，用户选择「直接删除，不留兼容层」。

要解决什么

现状：dev_scripts/ 有 4 个命令行入口（check_harness.py、sync_wiki_docs.py、new_task_archive.py、export_task_archives.py）加 1 个共享库 wiki_docs.py。4 个入口需要在 8 处文档中分别描述和记忆；同步核心镜像还必须按顺序跑 3 条命令（sync → check --strict → sync --check）。

目标：合并为单一入口 dev_scripts/harness.py，提供 check / sync / archive / export 四个子命令，并提供 sync --verify 一次完成原来的三步。

做什么 / 不做什么

  • 做：新建 harness.py 承载 4 个子命令；删除 4 个旧入口脚本；新增 sync --verify；更新 tests、check_harness 逻辑中的 REQUIRED_FILES；更新 AGENTS.md、README.md 及相关 Wiki 页面的命令描述。
  • 不做：不改 wiki_docs.py 的任何库函数行为；不改变检查规则、同步语义、归档格式；不保留旧脚本名的兼容转发；不改动 docs/task/ 下已有归档快照。

已确认方案

  1. 新建 dev_scripts/harness.py，argparse 子命令：
    • check [--strict] ← 原 check_harness.py
    • sync [--check] [--verify] ← 原 sync_wiki_docs.py，--verify 依次执行 导出 → check --strict → sync --check
    • archive <issue_number> <title> ← 原 new_task_archive.py
    • export [--all] ← 原 export_task_archives.py
  2. 各命令的实现函数迁入 harness.py，逻辑逐字保留，只改入口装配；wiki_docs.py 保持不变。
  3. 删除 check_harness.py、sync_wiki_docs.py、new_task_archive.py、export_task_archives.py。这是破坏性变更：已采用 DevHarness 的业务项目升级基线时必须同步修改自己的命令与文档。
  4. REQUIRED_FILES 中的 dev_scripts/sync_wiki_docs.py、dev_scripts/export_task_archives.py 改为 dev_scripts/harness.py。
  5. tests 的 import 来源由旧模块改为 harness，用例断言不变。
  6. 命令描述更新范围：AGENTS.md、README.md，以及 Wiki 页面 Project-Profile、Development-Workflow、Local-Development-and-Verification、Common-Changes、New-Project-Documentation-Setup、Home。Wiki 先改并回读 revision，再导出核心镜像。

预计修改文件：

  • 新增 dev_scripts/harness.py
  • 删除 dev_scripts/check_harness.py、dev_scripts/sync_wiki_docs.py、dev_scripts/new_task_archive.py、dev_scripts/export_task_archives.py
  • tests/test_harness_docs.py、tests/test_wiki_docs.py
  • AGENTS.md、README.md
  • Wiki：Project-Profile、Development-Workflow、Local-Development-and-Verification、Common-Changes、New-Project-Documentation-Setup、Home → 对应 docs/ 镜像

需求变化记录

日期 变化内容 原因 用户确认
2026-08-18 旧脚本名不保留兼容转发，直接删除 保留薄壳会使文件数从 5 变 6，抵消合并的简化效果 是

设计与原型门禁

  • 修改类型：非 UI
  • 所需设计证据：架构、API、数据、状态或流程设计
  • 可编辑设计源链接、版本或事实来源：本工单「已确认方案」一节
  • 本地 HTML 审核快照路径和版本（不适用时说明原因）：不适用，非 UI 改动
  • 本地浏览方式和资源完整性检查：不适用
  • 版本、revision 或确认日期：2026-08-18
  • 状态：已确认
  • 确认人、确认时间和覆盖范围：ila，2026-08-18，覆盖子命令划分与删除旧入口的破坏性变更
  • 无需 UI 原型或无需任何原型的原因：命令行工具重构，无用户界面

文档影响

  • 更新项目档案或本地开发与验证
  • 更新常见修改或故障排查
  • 更新其他 Wiki 页面：Home、Development-Workflow、New-Project-Documentation-Setup

交付文档影响

  • 无交付文档影响，原因：本仓库为开发流程模板，命令变更通过 Wiki 与 README 传达给采用方，无独立交付文档受众

验收标准

  • dev_scripts/ 下只剩 harness.py 与 wiki_docs.py
  • 四个子命令行为与原脚本一致（检查结论、同步语义、归档格式、导出范围均未改变）
  • python dev_scripts/harness.py sync --verify 一条命令完成原来的三步
  • python dev_scripts/harness.py check --strict 通过
  • python -m unittest discover -s tests -v 通过
  • python dev_scripts/harness.py sync --check 通过
  • AGENTS.md、README.md 及 6 个 Wiki 页面中不再出现已删除的脚本名（docs/task/ 历史归档除外）
  • Wiki 已更新并回读取得 revision，核心镜像已导出

验证方式

python dev_scripts/harness.py check --strict
python -m unittest discover -s tests -v
python dev_scripts/harness.py sync --verify
grep -rn "check_harness.py\|sync_wiki_docs.py\|new_task_archive.py\|export_task_archives.py" \
  --include=*.md --include=*.py --include=*.json . | grep -v "^./docs/task/"

最后一条应无输出（docs/task/ 下的历史归档保留原文，不回改）。

风险和回退

破坏性变更：删除公开命令入口，下游业务项目升级基线时必须同步调整。缓解方式为在工单和 Wiki 明确记录变更，并要求升级方按 DevHarness 基线升级流程处理。

回退方式：git revert 对应实现提交即可恢复 4 个旧脚本；Wiki 页面恢复到本工单记录的前一版 revision。无数据迁移、无不可逆操作。

## 基本信息 - 类型：重构 - 所属 Epic：无 - 所属 MVP / 版本：无 - 阶段：实施 ## 依赖与并行 - 前置工单：#22 - 是否允许与前置工单并行：否 - 原因：#22 会在 AGENTS.md 内联常用命令表，本工单会改写同一张表中的命令名。串行实施避免同段落冲突。 ## 子项目影响 - 仅影响的子项目 / 交付单元：DevHarness 模板 - 是否跨子项目：否 - 是否修改共享接口或契约：是。命令行入口是 DevHarness 对下游业务项目的公开契约，唯一事实来源为 Wiki 页面 Project-Profile 的「常用命令」表。 - 各子项目需要执行的验证：`python dev_scripts/harness.py check --strict`、`python -m unittest discover -s tests -v` ## 原始需求 - 来源：用户对话 - 提出时间：2026-08-18 - 关键原话或脱敏摘要：用户要求「节省开发时间和 token」，确认「先做 B + E」；就旧脚本名的处理，用户选择「直接删除，不留兼容层」。 ## 要解决什么 现状：`dev_scripts/` 有 4 个命令行入口（check_harness.py、sync_wiki_docs.py、new_task_archive.py、export_task_archives.py）加 1 个共享库 wiki_docs.py。4 个入口需要在 8 处文档中分别描述和记忆；同步核心镜像还必须按顺序跑 3 条命令（sync → check --strict → sync --check）。 目标：合并为单一入口 `dev_scripts/harness.py`，提供 check / sync / archive / export 四个子命令，并提供 `sync --verify` 一次完成原来的三步。 ## 做什么 / 不做什么 - 做：新建 harness.py 承载 4 个子命令；删除 4 个旧入口脚本；新增 `sync --verify`；更新 tests、check_harness 逻辑中的 REQUIRED_FILES；更新 AGENTS.md、README.md 及相关 Wiki 页面的命令描述。 - 不做：不改 wiki_docs.py 的任何库函数行为；不改变检查规则、同步语义、归档格式；不保留旧脚本名的兼容转发；不改动 docs/task/ 下已有归档快照。 ## 已确认方案 1. 新建 `dev_scripts/harness.py`，argparse 子命令： - `check [--strict]` ← 原 check_harness.py - `sync [--check] [--verify]` ← 原 sync_wiki_docs.py，`--verify` 依次执行 导出 → check --strict → sync --check - `archive <issue_number> <title>` ← 原 new_task_archive.py - `export [--all]` ← 原 export_task_archives.py 2. 各命令的实现函数迁入 harness.py，逻辑逐字保留，只改入口装配；wiki_docs.py 保持不变。 3. 删除 check_harness.py、sync_wiki_docs.py、new_task_archive.py、export_task_archives.py。**这是破坏性变更**：已采用 DevHarness 的业务项目升级基线时必须同步修改自己的命令与文档。 4. `REQUIRED_FILES` 中的 `dev_scripts/sync_wiki_docs.py`、`dev_scripts/export_task_archives.py` 改为 `dev_scripts/harness.py`。 5. tests 的 import 来源由旧模块改为 harness，用例断言不变。 6. 命令描述更新范围：AGENTS.md、README.md，以及 Wiki 页面 Project-Profile、Development-Workflow、Local-Development-and-Verification、Common-Changes、New-Project-Documentation-Setup、Home。Wiki 先改并回读 revision，再导出核心镜像。 预计修改文件： - 新增 `dev_scripts/harness.py` - 删除 `dev_scripts/check_harness.py`、`dev_scripts/sync_wiki_docs.py`、`dev_scripts/new_task_archive.py`、`dev_scripts/export_task_archives.py` - `tests/test_harness_docs.py`、`tests/test_wiki_docs.py` - `AGENTS.md`、`README.md` - Wiki：Project-Profile、Development-Workflow、Local-Development-and-Verification、Common-Changes、New-Project-Documentation-Setup、Home → 对应 docs/ 镜像 ## 需求变化记录 | 日期 | 变化内容 | 原因 | 用户确认 | |---|---|---|---| | 2026-08-18 | 旧脚本名不保留兼容转发，直接删除 | 保留薄壳会使文件数从 5 变 6，抵消合并的简化效果 | 是 | ## 设计与原型门禁 - 修改类型：非 UI - 所需设计证据：架构、API、数据、状态或流程设计 - 可编辑设计源链接、版本或事实来源：本工单「已确认方案」一节 - 本地 HTML 审核快照路径和版本（不适用时说明原因）：不适用，非 UI 改动 - 本地浏览方式和资源完整性检查：不适用 - 版本、revision 或确认日期：2026-08-18 - 状态：已确认 - 确认人、确认时间和覆盖范围：ila，2026-08-18，覆盖子命令划分与删除旧入口的破坏性变更 - 无需 UI 原型或无需任何原型的原因：命令行工具重构，无用户界面 ## 文档影响 - [x] 更新项目档案或本地开发与验证 - [x] 更新常见修改或故障排查 - [x] 更新其他 Wiki 页面：Home、Development-Workflow、New-Project-Documentation-Setup ## 交付文档影响 - [x] 无交付文档影响，原因：本仓库为开发流程模板，命令变更通过 Wiki 与 README 传达给采用方，无独立交付文档受众 ## 验收标准 - [ ] `dev_scripts/` 下只剩 `harness.py` 与 `wiki_docs.py` - [ ] 四个子命令行为与原脚本一致（检查结论、同步语义、归档格式、导出范围均未改变） - [ ] `python dev_scripts/harness.py sync --verify` 一条命令完成原来的三步 - [ ] `python dev_scripts/harness.py check --strict` 通过 - [ ] `python -m unittest discover -s tests -v` 通过 - [ ] `python dev_scripts/harness.py sync --check` 通过 - [ ] AGENTS.md、README.md 及 6 个 Wiki 页面中不再出现已删除的脚本名（docs/task/ 历史归档除外） - [ ] Wiki 已更新并回读取得 revision，核心镜像已导出 ## 验证方式 ```bash python dev_scripts/harness.py check --strict python -m unittest discover -s tests -v python dev_scripts/harness.py sync --verify grep -rn "check_harness.py\|sync_wiki_docs.py\|new_task_archive.py\|export_task_archives.py" \ --include=*.md --include=*.py --include=*.json . | grep -v "^./docs/task/" ``` 最后一条应无输出（docs/task/ 下的历史归档保留原文，不回改）。 ## 风险和回退 破坏性变更：删除公开命令入口，下游业务项目升级基线时必须同步调整。缓解方式为在工单和 Wiki 明确记录变更，并要求升级方按 DevHarness 基线升级流程处理。 回退方式：`git revert` 对应实现提交即可恢复 4 个旧脚本；Wiki 页面恢复到本工单记录的前一版 revision。无数据迁移、无不可逆操作。
ila commented 2026-08-18 21:39:36 +08:00
Author
Owner
Copy Link
Copy Source

实施完成，状态：待验收

需求变化记录（补充）

日期 变化内容 原因 用户确认
2026-08-18 受影响 Wiki 页面由 6 个更正为 7 个，增加 Architecture-and-Code-Map 建单时遗漏；代码地图中三行「入口函数」「参数」列指向各脚本的 main()，合并后必须改为 run_check() / run_sync() / run_archive() 和对应子命令 待确认（范围补充，不改变已确认结论）

验收结果

验收标准 结果
dev_scripts/ 下只剩 harness.py 与 wiki_docs.py 通过
四个子命令行为与原脚本一致 通过，实现逻辑整段切出未改写，原有 40 个用例全部通过
sync --verify 一条命令完成原三步 通过，退出码 0
harness.py check --strict 通过
unittest discover -s tests -v 通过，Ran 40 tests，OK
harness.py sync --check 通过
文档中不再出现旧脚本名 通过（docs/task/ 历史归档按验收标准排除；harness.py 文件头保留一行来源说明）
Wiki 已更新并回读 revision，镜像已导出 通过，7 页全部回读

证据

  • 实现提交：bfc0726 refactor: 合并 dev_scripts 入口为单一 harness.py (#23)
  • 镜像提交：bfdf648 docs: 同步命令入口变更的核心 Wiki 镜像 (#23)
  • 任务归档：Task-23-合并dev_scripts入口
  • 归档 revision：bb555229d042b0852dd0fe21caf462349a44b222
  • 未推送远端，等待验收。

未验证部分

  • export / export --all 只有单元测试覆盖，未做真实线上增量导出（导出须由用户明确提出）。
  • 下游业务项目升级后的命令兼容性未验证，属采用方职责。本次为破坏性变更。

遗留问题

harness.py 合并后 725 行，单文件偏长，已按四段分区。若后续继续增长可再考虑拆分库模块。

## 实施完成，状态：待验收 ### 需求变化记录（补充） | 日期 | 变化内容 | 原因 | 用户确认 | |---|---|---|---| | 2026-08-18 | 受影响 Wiki 页面由 6 个更正为 7 个，增加 Architecture-and-Code-Map | 建单时遗漏；代码地图中三行「入口函数」「参数」列指向各脚本的 `main()`，合并后必须改为 `run_check()` / `run_sync()` / `run_archive()` 和对应子命令 | 待确认（范围补充，不改变已确认结论） | ### 验收结果 | 验收标准 | 结果 | |---|---| | `dev_scripts/` 下只剩 harness.py 与 wiki_docs.py | 通过 | | 四个子命令行为与原脚本一致 | 通过，实现逻辑整段切出未改写，原有 40 个用例全部通过 | | `sync --verify` 一条命令完成原三步 | 通过，退出码 0 | | `harness.py check --strict` | 通过 | | `unittest discover -s tests -v` | 通过，Ran 40 tests，OK | | `harness.py sync --check` | 通过 | | 文档中不再出现旧脚本名 | 通过（`docs/task/` 历史归档按验收标准排除；`harness.py` 文件头保留一行来源说明） | | Wiki 已更新并回读 revision，镜像已导出 | 通过，7 页全部回读 | ### 证据 - 实现提交：`bfc0726` refactor: 合并 dev_scripts 入口为单一 harness.py (#23) - 镜像提交：`bfdf648` docs: 同步命令入口变更的核心 Wiki 镜像 (#23) - 任务归档：Task-23-合并dev_scripts入口 - 归档 revision：`bb555229d042b0852dd0fe21caf462349a44b222` - 未推送远端，等待验收。 ### 未验证部分 - `export` / `export --all` 只有单元测试覆盖，未做真实线上增量导出（导出须由用户明确提出）。 - 下游业务项目升级后的命令兼容性未验证，属采用方职责。本次为破坏性变更。 ### 遗留问题 `harness.py` 合并后 725 行，单文件偏长，已按四段分区。若后续继续增长可再考虑拆分库模块。
ila commented 2026-08-18 22:13:17 +08:00
Author
Owner
Copy Link
Copy Source

验收通过并关闭

  • 验收人：ila
  • 验收时间：2026-08-18
  • 归档页面：Task-23-合并dev_scripts入口
  • 归档 revision：f5baa77209c9（状态已置为已完成）
  • 实现提交：bfc0726 / bfdf648
  • 已推送：cdf83fd..bfdf648 → origin/main
  • 本工单无父 Epic / MVP，无需同步父工单。
  • 未导出 docs/task/ 快照；导出需用户明确提出。
## 验收通过并关闭 - 验收人：ila - 验收时间：2026-08-18 - 归档页面：Task-23-合并dev_scripts入口 - 归档 revision：`f5baa77209c9`（状态已置为已完成） - 实现提交：`bfc0726 / bfdf648` - 已推送：`cdf83fd..bfdf648` → origin/main - 本工单无父 Epic / MVP，无需同步父工单。 - 未导出 `docs/task/` 快照；导出需用户明确提出。
ila closed this issue 2026-08-18 22:13:20 +08:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
No items
No labels
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
admin ila
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: OPC/dev_harness#23