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

refactor: 将 Harness 工具移至 dev_scripts (#3)

Browse Source
This commit is contained in:
QiuSW
2026-08-08 09:18:09 +08:00
parent c69c0fde03
commit 1c998673f3
15 changed files with 53 additions and 52 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/00-project-profile.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` 必须通过。
- 未执行或无法覆盖的验证必须记录到工单。
docs/01-workflow.md
+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、镜像路径和提交哈希写回工单。用户明确验收通过后，关闭单元工单并勾选父工单中的任务。
docs/02-architecture-and-code-map.md
+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` | 低 |
docs/04-local-development-and-verification.md
+7 -7
View File
@@ -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: 43ad9c6ee3f4172059133cca05124f4018267c1e
synchronized_at: 2026-08-08T01:16:53Z
<!-- 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 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
```
docs/05-common-changes.md
+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 和脏文件保护。
docs/07-new-project-documentation-setup.md
+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
```
docs/README.md
+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 分析、等待人工确认。