Compare commits

...
3 Commits
Author SHA1 Message Date
QiuSW 1d3104c002 docs: 归档任务 #3 2026-08-08 09:21:38 +08:00
QiuSW 51278fa47f docs: 修正 dev_scripts 编译检查命令 (#3) 2026-08-08 09:19:45 +08:00
QiuSW 1c998673f3 refactor: 将 Harness 工具移至 dev_scripts (#3) 2026-08-08 09:18:09 +08:00
17 changed files with 130 additions and 53 deletions
+4 -3
View File
@@ -36,7 +36,7 @@
5. 开始实施前检查分支和工作区,明确哪些现有改动不属于本任务。
6. 严格按工单范围实现;新发现的问题先记录,不顺手混入当前任务。
7. 执行与风险相称的测试,把关键结果和未验证部分更新到工单。
8. 长期文档必须先修改 Wiki、读取确认,再运行 `python scripts/sync_wiki_docs.py` 导出本地镜像;不得直接编辑 `docs/` 后反向覆盖 Wiki。
8. 长期文档必须先修改 Wiki、读取确认,再运行 `python dev_scripts/sync_wiki_docs.py` 导出本地镜像;不得直接编辑 `docs/` 后反向覆盖 Wiki。
Gitea 不可用时,输出完整工单草稿并说明阻塞。未经用户明确授权,不得默认绕过建单。
@@ -78,8 +78,8 @@ Epic:完整产品目标和长期路线
1. 实现完成后逐项检查验收标准,并提交代码。
2. 更新单元工单:最终方案、方案差异、测试结果、提交哈希和遗留问题。
3. 工单保持“待验收”,用户没有明确验收通过前不得关闭。
4. 运行 `python scripts/new_task_archive.py <编号> "<短标题>"`,先在 Wiki 创建任务归档,再登记映射并导出 `docs/task/<编号>-<短标题>.md` 镜像。
5. 读取确认 Wiki 页面,运行 `python scripts/sync_wiki_docs.py --check` 校验镜像。
4. 运行 `python dev_scripts/new_task_archive.py <编号> "<短标题>"`,先在 Wiki 创建任务归档,再登记映射并导出 `docs/task/<编号>-<短标题>.md` 镜像。
5. 读取确认 Wiki 页面,运行 `python dev_scripts/sync_wiki_docs.py --check` 校验镜像。
6. 归档镜像单独提交,例如:`docs: 归档任务 #123`。
7. 把 Wiki 页面、revision、镜像路径和提交哈希回写工单。
8. 用户验收通过后关闭单元工单,并同步更新 MVP 和 Epic。
@@ -127,3 +127,4 @@ MVP 内所有单元任务通过后才能做 MVP 集成验收;MVP 通过后才
- Wiki 与镜像的固定顺序是:修改 Wiki → 读取确认 → 导出 `docs` → 校验差异 → 提交镜像。
- 同步配置只允许写入 `docs/` 下的 Markdown;发现镜像有未提交修改时必须停止。
- Gitea 凭据只通过进程环境或 MCP 安全配置提供,不得写入仓库。
- `dev_scripts/` 只存放 DevHarness 自身工具;业务项目的通用脚本必须使用独立目录,不得混放。
+4 -4
View File
@@ -29,7 +29,7 @@ DevHarness 是一个以 Gitea 工单管理任务过程、以 Gitea Wiki 管理
7. 开始产品代码前运行:
```powershell
python scripts/check_harness.py --strict
python dev_scripts/check_harness.py --strict
```
新仓库在 Gitea 尚未建立前允许一次不关联工单的引导提交。远端和工单系统配置完成后,所有改变程序行为的工作都必须先有单元任务工单。
@@ -46,9 +46,9 @@ docs/02-07*.md 代码地图、业务、验证、修改、排
docs/templates/task-archive.md Wiki 任务归档模板的只读镜像
docs/task/ Wiki 任务归档页的只读镜像
wiki-docs.json Wiki 页面到本地镜像的显式映射
scripts/check_harness.py 模板和归档的最小自检
scripts/sync_wiki_docs.py 单向导出或检查 Wiki 镜像
scripts/new_task_archive.py 先创建 Wiki 任务归档,再导出镜像
dev_scripts/check_harness.py 模板和归档的最小自检
dev_scripts/sync_wiki_docs.py 单向导出或检查 Wiki 镜像
dev_scripts/new_task_archive.py 先创建 Wiki 任务归档,再导出镜像
```
## 设计原则
@@ -86,8 +86,8 @@ REQUIRED_FILES = (
"docs/templates/task-archive.md",
*CORE_DOCUMENT_REQUIREMENTS,
"wiki-docs.json",
"scripts/wiki_docs.py",
"scripts/sync_wiki_docs.py",
"dev_scripts/wiki_docs.py",
"dev_scripts/sync_wiki_docs.py",
".gitea/issue_template/epic.md",
".gitea/issue_template/mvp.md",
".gitea/issue_template/task.md",
+8 -8
View File
@@ -2,8 +2,8 @@
generated: true (请先修改 Gitea Wiki,禁止直接编辑本文件)
wiki_page: Project-Profile
wiki_url: http://ilaer.eicp.net:8418/opc/dev_harness/wiki/Project-Profile.-
wiki_revision: df33a1ce9d25d28866e20d942799a5d01fcec935
synchronized_at: 2026-08-08T00:58:02Z
wiki_revision: 2a81c9e4508cf6594f90d0b54368ec1f8a3be220
synchronized_at: 2026-08-08T01:16:47Z
<!-- gitea-wiki-mirror:end -->
# 项目档案
@@ -49,11 +49,11 @@ synchronized_at: 2026-08-08T00:58:02Z
| 用途 | 命令 | 预期结果 |
|---|---|---|
| 查看工作区 | `git status --short --branch` | 显示分支且没有无关修改 |
| 检查模板结构 | `python scripts/check_harness.py --strict` | 输出“DevHarness 检查通过” |
| 检查模板结构 | `python dev_scripts/check_harness.py --strict` | 输出“DevHarness 检查通过” |
| 运行单元测试 | `python -m unittest discover -s tests -v` | 所有测试通过 |
| 导出 Wiki 镜像 | `python scripts/sync_wiki_docs.py` | 映射页面写入 `docs/` |
| 检查 Wiki 镜像 | `python scripts/sync_wiki_docs.py --check` | 输出镜像与 Wiki 一致 |
| 创建任务归档 | `python scripts/new_task_archive.py 123 "修复登录超时"` | 先创建 Wiki 归档页,再登记并导出本地镜像 |
| 导出 Wiki 镜像 | `python dev_scripts/sync_wiki_docs.py` | 映射页面写入 `docs/` |
| 检查 Wiki 镜像 | `python dev_scripts/sync_wiki_docs.py --check` | 输出镜像与 Wiki 一致 |
| 创建任务归档 | `python dev_scripts/new_task_archive.py 123 "修复登录超时"` | 先创建 Wiki 归档页,再登记并导出本地镜像 |
## 目录边界
@@ -62,7 +62,7 @@ synchronized_at: 2026-08-08T00:58:02Z
| `.gitea/issue_template/` | Gitea 工单模板 | 凭据、任务最终归档 |
| `docs/` | Wiki 自动导出的只读镜像 | 人工直接维护的长期文档 |
| `docs/task/` | Wiki 任务归档页的只读镜像 | 讨论过程和临时方案 |
| `scripts/` | Harness 检查、Wiki 同步和归档工具 | 产品功能代码 |
| `dev_scripts/` | Harness 检查、Wiki 同步和归档工具 | 产品功能代码 |
| `tests/` | Harness 工具自动化测试 | 生产数据 |
## 环境、配置与凭据
@@ -83,6 +83,6 @@ synchronized_at: 2026-08-08T00:58:02Z
- 页面删除、重命名和映射变更必须人工确认。
- 新增核心文档时必须更新 Home、显式映射和 Harness 检查。
- 代码入口、命令、配置、业务规则或排错方式变化时必须评估文档影响。
- `python scripts/check_harness.py --strict` 必须通过。
- `python dev_scripts/check_harness.py --strict` 必须通过。
- `python -m unittest discover -s tests -v` 必须通过。
- 未执行或无法覆盖的验证必须记录到工单。
+3 -3
View File
@@ -2,8 +2,8 @@
generated: true (请先修改 Gitea Wiki,禁止直接编辑本文件)
wiki_page: Development-Workflow
wiki_url: http://ilaer.eicp.net:8418/opc/dev_harness/wiki/Development-Workflow.-
wiki_revision: af4c1cbdd73cf9f6df971415487e2664e227ebc9
synchronized_at: 2026-08-08T00:58:03Z
wiki_revision: 2ce05d5688fa3802ad62667a5ba34a90cf2a02f7
synchronized_at: 2026-08-08T01:16:48Z
<!-- gitea-wiki-mirror:end -->
# 开发工作流
@@ -67,7 +67,7 @@ Agent 检查分支和工作区,只修改工单范围内的文件。发现新
使用以下命令在 Wiki 创建任务归档页、登记显式映射并导出本地镜像:
```powershell
python scripts/new_task_archive.py 123 "修复登录超时"
python dev_scripts/new_task_archive.py 123 "修复登录超时"
```
归档内容以 Wiki 页面为主源;本地 `docs/task/<编号>-<短标题>.md` 是镜像。归档镜像单独提交,再把 Wiki 页面、revision、镜像路径和提交哈希写回工单。用户明确验收通过后,关闭单元工单并勾选父工单中的任务。
+6 -6
View File
@@ -2,8 +2,8 @@
generated: true (请先修改 Gitea Wiki,禁止直接编辑本文件)
wiki_page: Architecture-and-Code-Map
wiki_url: http://ilaer.eicp.net:8418/opc/dev_harness/wiki/Architecture-and-Code-Map.-
wiki_revision: 3f86864cecb0600e3b20631b6677446dbc259927
synchronized_at: 2026-08-08T00:58:04Z
wiki_revision: f93132ddd5bbc8fe233270579a63fc182db3b795
synchronized_at: 2026-08-08T01:16:49Z
<!-- gitea-wiki-mirror:end -->
# 架构与代码地图
@@ -39,10 +39,10 @@ DevHarness 不是业务应用,而是一套开发工作流模板。它约束 Ag
| Agent 工作规则 | `AGENTS.md` | “需求到实施” | 工作流条款 | 人工审查、Harness 检查 | 高 |
| 工单结构 | `.gitea/issue_template/` | `task.md` | Epic、MVP、Task 模板 | 创建测试工单或检查模板 | 中 |
| Wiki 页面映射 | `wiki-docs.json` | `mappings` | 页面名、本地路径 | `sync_wiki_docs.py --check` | 中 |
| Wiki API 和镜像生成 | `scripts/wiki_docs.py` | `WikiClient`、`sync_all` | 配置、页面、镜像元数据 | `tests/test_wiki_docs.py` | 中 |
| 手动同步入口 | `scripts/sync_wiki_docs.py` | `main()` | `--check` | 线上 Wiki 对照检查 | 低 |
| 任务归档 | `scripts/new_task_archive.py` | `main()` | 创建页面、登记映射 | 单元测试和正式归档 | 中 |
| Harness 结构检查 | `scripts/check_harness.py` | `main()` | 必需文件、镜像、归档检查 | `--strict` | 中 |
| Wiki API 和镜像生成 | `dev_scripts/wiki_docs.py` | `WikiClient`、`sync_all` | 配置、页面、镜像元数据 | `tests/test_wiki_docs.py` | 中 |
| 手动同步入口 | `dev_scripts/sync_wiki_docs.py` | `main()` | `--check` | 线上 Wiki 对照检查 | 低 |
| 任务归档 | `dev_scripts/new_task_archive.py` | `main()` | 创建页面、登记映射 | 单元测试和正式归档 | 中 |
| Harness 结构检查 | `dev_scripts/check_harness.py` | `main()` | 必需文件、镜像、归档检查 | `--strict` | 中 |
| 本地文档镜像 | `docs/` | `docs/README.md` | 生成元数据和 Wiki 正文 | 同步检查 | 低 |
| 自动化测试 | `tests/` | `test_wiki_docs.py` | 映射、同步和安全边界 | `unittest discover` | 低 |
@@ -2,8 +2,8 @@
generated: true (请先修改 Gitea Wiki,禁止直接编辑本文件)
wiki_page: Local-Development-and-Verification
wiki_url: http://ilaer.eicp.net:8418/opc/dev_harness/wiki/Local-Development-and-Verification.-
wiki_revision: c21eb70ff584721ca899ff46701cdf0e409773bf
synchronized_at: 2026-08-08T01:01:15Z
wiki_revision: b31ef962e1a0a368f067b18bace3071bab60a20d
synchronized_at: 2026-08-08T01:18:31Z
<!-- gitea-wiki-mirror:end -->
# 本地开发与验证
@@ -35,7 +35,7 @@ synchronized_at: 2026-08-08T01:01:15Z
### 2. 检查 Harness
- 目的:验证必需文件、项目档案、Wiki 映射和归档结构。
- 命令:`python scripts/check_harness.py --strict`
- 命令:`python dev_scripts/check_harness.py --strict`
- 预期:输出“DevHarness 检查通过”。
- 失败检查:按错误提示检查缺失页面、未填占位符或损坏的镜像头。
@@ -49,14 +49,14 @@ synchronized_at: 2026-08-08T01:01:15Z
### 4. 对照线上 Wiki
- 目的:确认本地 docs 是最新镜像。
- 命令:`python scripts/sync_wiki_docs.py --check`
- 命令:`python dev_scripts/sync_wiki_docs.py --check`
- 预期:所有映射显示“一致”。
- 失败检查:先读取线上页面;确认页面名、revision、网络和 `GITEA_URL`。
## 常用调试方式
- 只检查 Python 语法:`python -m compileall -q scripts tests`。
- 查看一个脚本帮助:`python scripts/sync_wiki_docs.py --help`。
- 只检查 Python 语法:`python -m compileall -q dev_scripts tests`。
- 查看一个脚本帮助:`python dev_scripts/sync_wiki_docs.py --help`。
- 查看未提交差异:`git diff --check` 和 `git diff`。
- 查看最近提交:`git log -5 --oneline`。
- 调试失败测试时优先运行单个测试文件,不要先修改多个模块。
@@ -76,8 +76,8 @@ DevHarness 不使用生产数据,也不需要固定业务测试数据。命令
```powershell
python -m unittest discover -s tests -v
python scripts/check_harness.py --strict
python scripts/sync_wiki_docs.py --check
python dev_scripts/check_harness.py --strict
python dev_scripts/sync_wiki_docs.py --check
git diff --check
git status --short
```
+6 -6
View File
@@ -2,8 +2,8 @@
generated: true (请先修改 Gitea Wiki,禁止直接编辑本文件)
wiki_page: Common-Changes
wiki_url: http://ilaer.eicp.net:8418/opc/dev_harness/wiki/Common-Changes.-
wiki_revision: 2c41287656577564fc7b78b6cf8554ce81e16003
synchronized_at: 2026-08-08T00:58:10Z
wiki_revision: 9b223d2feada753a6d38bffce6eb0848c4067b85
synchronized_at: 2026-08-08T01:16:55Z
<!-- gitea-wiki-mirror:end -->
# 常见修改指南
@@ -27,8 +27,8 @@ synchronized_at: 2026-08-08T00:58:10Z
1. 在相关工单确认目标。
2. 读取线上 Wiki 页面和当前 revision。
3. 修改线上 Wiki,不直接编辑 `docs/`。
4. 运行 `python scripts/sync_wiki_docs.py`。
5. 运行 `python scripts/sync_wiki_docs.py --check`。
4. 运行 `python dev_scripts/sync_wiki_docs.py`。
5. 运行 `python dev_scripts/sync_wiki_docs.py --check`。
6. 审查本地镜像差异并提交。
停止条件:页面需要删除、重命名或改变事实源边界。
@@ -45,7 +45,7 @@ synchronized_at: 2026-08-08T00:58:10Z
## 调整 Harness 检查
1. 从 `scripts/check_harness.py` 的 `main()` 开始读。
1. 从 `dev_scripts/check_harness.py` 的 `main()` 开始读。
2. 新检查应输出具体文件和缺失内容。
3. 检查结构事实,不声称自动判断文档语义质量。
4. 在 `tests/` 添加成功和失败用例。
@@ -55,7 +55,7 @@ synchronized_at: 2026-08-08T00:58:10Z
## 修复 Wiki 同步 Bug
1. 从 `scripts/wiki_docs.py` 的 `WikiClient`、`parse_mirror` 和 `sync_all` 开始读。
1. 从 `dev_scripts/wiki_docs.py` 的 `WikiClient`、`parse_mirror` 和 `sync_all` 开始读。
2. 先编写能复现问题的测试。
3. 保持 Wiki → docs 单向关系。
4. 验证中文、路径编码、revision 和脏文件保护。
+5 -5
View File
@@ -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: 42ec711392ad8cafbbf72aa95bf5c90245da2249
synchronized_at: 2026-08-08T01:01:21Z
wiki_revision: a0eeab23a41671b5dbfc3153e872b71647ea41c7
synchronized_at: 2026-08-08T01:16:59Z
<!-- gitea-wiki-mirror:end -->
# 新项目文档初始化
@@ -80,9 +80,9 @@ Home 给出建议阅读顺序;每个命令必须有预期结果;代码地图
### 7. 导出镜像并检查
```powershell
python scripts/sync_wiki_docs.py
python scripts/check_harness.py --strict
python scripts/sync_wiki_docs.py --check
python dev_scripts/sync_wiki_docs.py
python dev_scripts/check_harness.py --strict
python dev_scripts/sync_wiki_docs.py --check
python -m unittest discover -s tests -v
```
+6 -6
View File
@@ -2,8 +2,8 @@
generated: true (请先修改 Gitea Wiki,禁止直接编辑本文件)
wiki_page: Home
wiki_url: http://ilaer.eicp.net:8418/opc/dev_harness/wiki/Home
wiki_revision: 6cd3fccc78501c8be5bea6cd05d53799be4c6bd7
synchronized_at: 2026-08-08T00:58:01Z
wiki_revision: f1baf5947fe4e8f08cfc3ccc129946964fbbc3e5
synchronized_at: 2026-08-08T01:16:46Z
<!-- gitea-wiki-mirror:end -->
# DevHarness 文档中心
@@ -30,9 +30,9 @@ DevHarness 是一个以 Gitea 工单管理开发任务、以 Wiki 管理长期
```powershell
git status --short --branch
python scripts/check_harness.py --strict
python dev_scripts/check_harness.py --strict
python -m unittest discover -s tests -v
python scripts/sync_wiki_docs.py --check
python dev_scripts/sync_wiki_docs.py --check
```
预期结果:
@@ -50,8 +50,8 @@ python scripts/sync_wiki_docs.py --check
|---|---|---|
| 修改文档 | 对应 Wiki 页面、Common-Changes | Wiki 同步检查 |
| 调整工单字段 | `.gitea/issue_template/`、Development-Workflow | Harness 严格检查 |
| 修改同步行为 | `scripts/wiki_docs.py`、Architecture-and-Code-Map | 单元测试和真实 Wiki 检查 |
| 增加结构检查 | `scripts/check_harness.py` | 成功与失败测试 |
| 修改同步行为 | `dev_scripts/wiki_docs.py`、Architecture-and-Code-Map | 单元测试和真实 Wiki 检查 |
| 增加结构检查 | `dev_scripts/check_harness.py` | 成功与失败测试 |
| 排查运行错误 | Troubleshooting、项目档案 | 最小复现命令 |
权限、安全、并发、迁移、支付、删除数据或不可逆操作不属于简单修改,必须停止并交给 Agent 分析、等待人工确认。
+72
View File
@@ -0,0 +1,72 @@
<!-- gitea-wiki-mirror:start -->
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: 5e961648835c5d8ba73d2cb515d335294e480ba2
synchronized_at: 2026-08-08T01:21:04Z
<!-- gitea-wiki-mirror:end -->
# 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)
+1 -1
View File
@@ -6,7 +6,7 @@ from pathlib import Path
ROOT = Path(__file__).resolve().parents[1]
sys.path.insert(0, str(ROOT / "scripts"))
sys.path.insert(0, str(ROOT / "dev_scripts"))
from check_harness import ( # noqa: E402
CORE_DOCUMENT_REQUIREMENTS,
+1 -1
View File
@@ -10,7 +10,7 @@ from unittest.mock import Mock, patch
ROOT = Path(__file__).resolve().parents[1]
sys.path.insert(0, str(ROOT / "scripts"))
sys.path.insert(0, str(ROOT / "dev_scripts"))
from new_task_archive import build_archive, safe_title # noqa: E402
from wiki_docs import ( # noqa: E402
+4
View File
@@ -51,6 +51,10 @@
{
"page": "Task-2-Junior-Maintainer-Docs",
"path": "docs/task/2-初级维护者文档体系.md"
},
{
"page": "Task-3-Dev-Scripts-Rename",
"path": "docs/task/3-dev_scripts目录重命名.md"
}
]
}