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

docs: 同步命令入口变更的核心 Wiki 镜像 (#23)

Browse Source 
Wiki 侧已更新 7 个核心页面的命令入口，本提交只导出对应只读镜像。

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
ila
2026-08-18 21:36:15 +08:00
co-authored by Claude Opus 5
parent bfc0726c33
commit bfdf648962
7 changed files with 45 additions and 47 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/00-project-profile.md
+10 -10
View File
@@ -2,8 +2,8 @@
generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
wiki_page: Project-Profile
wiki_url: https://git.ilapage.cn/OPC/dev_harness/wiki/Project-Profile.-
wiki_revision: ad8b8d6e893e426fdfd6c11ee9d5ff7e1dfb5f80
synchronized_at: 2026-08-17T01:57:47Z
wiki_revision: dae88cec817721fe640aebba5c95842f812095c0
synchronized_at: 2026-08-18T13:34:36Z
<!-- gitea-wiki-mirror:end -->
# 项目档案
@@ -42,7 +42,7 @@ synchronized_at: 2026-08-17T01:57:47Z
| 子项目 / 交付单元 | 职责 | 技术栈 | 构建与测试 | 版本与发布方式 | 规则入口 | 共享边界 |
|---|---|---|---|---|---|---|
| DevHarness 模板 | 提供 Agent 开发流程、Wiki 镜像和结构检查 | Markdown、Python 3 标准库、Gitea 1.25 | `python dev_scripts/check_harness.py --strict`；`python -m unittest discover -s tests -v` | 跟随仓库 `main` 分支，不单独发布产品程序 | 根目录 `AGENTS.md` | Gitea 工单、Wiki、Git 和 `docs/` 的事实来源边界 |
| DevHarness 模板 | 提供 Agent 开发流程、Wiki 镜像和结构检查 | Markdown、Python 3 标准库、Gitea 1.25 | `python dev_scripts/harness.py check --strict`；`python -m unittest discover -s tests -v` | 跟随仓库 `main` 分支，不单独发布产品程序 | 根目录 `AGENTS.md` | Gitea 工单、Wiki、Git 和 `docs/` 的事实来源边界 |
单应用项目只填写一行。多应用单仓库必须逐个填写，并为技术栈、构建测试或安全规则不同的目录增加子目录 `AGENTS.md`。技术栈不同不等于必须拆分 Git 仓库；是否拆仓应根据团队、权限、发布周期、仓库效率、复用关系和共享接口稳定性判断。
@@ -75,13 +75,13 @@ synchronized_at: 2026-08-17T01:57:47Z
| 用途 | 命令 | 预期结果 |
|---|---|---|
| 查看工作区 | `git status --short --branch` | 显示分支且没有无关修改 |
| 检查模板结构 | `python dev_scripts/check_harness.py --strict` | 输出“DevHarness 检查通过” |
| 检查模板结构 | `python dev_scripts/harness.py check --strict` | 输出“DevHarness 检查通过” |
| 运行单元测试 | `python -m unittest discover -s tests -v` | 所有测试通过 |
| 导出核心 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 归档页，不写入本地 |
| 增量导出任务归档 | `python dev_scripts/export_task_archives.py` | 只导出新增或 revision 已变化的任务归档 |
| 全量导出任务归档 | `python dev_scripts/export_task_archives.py --all` | 读取并导出全部线上任务归档 |
| 导出核心 Wiki 镜像 | `python dev_scripts/harness.py sync` | 核心页面写入 `docs/`，不处理任务归档 |
| 检查核心 Wiki 镜像 | `python dev_scripts/harness.py sync --check` | 输出核心镜像与 Wiki 一致 |
| 创建任务归档 | `python dev_scripts/harness.py archive 123 "修复登录超时"` | 只创建 Wiki 归档页，不写入本地 |
| 增量导出任务归档 | `python dev_scripts/harness.py export` | 只导出新增或 revision 已变化的任务归档 |
| 全量导出任务归档 | `python dev_scripts/harness.py export --all` | 读取并导出全部线上任务归档 |
## 目录边界
@@ -111,6 +111,6 @@ synchronized_at: 2026-08-17T01:57:47Z
- 页面删除、重命名和映射变更必须人工确认。
- 新增核心文档时必须更新 Home、显式映射和 Harness 检查。
- 代码入口、命令、配置、业务规则或排错方式变化时必须评估文档影响。
- `python dev_scripts/check_harness.py --strict` 必须通过。
- `python dev_scripts/harness.py check --strict` 必须通过。
- `python -m unittest discover -s tests -v` 必须通过。
- 未执行或无法覆盖的验证必须记录到工单。
docs/01-workflow.md
+6 -6
View File
@@ -2,8 +2,8 @@
generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
wiki_page: Development-Workflow
wiki_url: https://git.ilapage.cn/OPC/dev_harness/wiki/Development-Workflow.-
wiki_revision: de22464839289f7ece56e27113d685e6b9e1f5cc
synchronized_at: 2026-08-17T06:53:56Z
wiki_revision: d6afa1cba5cd7e04e589182bb7c010ef97f26cd1
synchronized_at: 2026-08-18T13:34:40Z
<!-- gitea-wiki-mirror:end -->
# 开发工作流
@@ -23,7 +23,7 @@ synchronized_at: 2026-08-17T06:53:56Z
2. 优先使用项目已配置的 Gitea MCP 查询 Wiki 页面；MCP 不可用或不支持所需写操作时，才使用 Gitea API，并在初始化工单记录回退原因。凭据只从环境或 MCP 安全配置读取。
3. 查询线上页面列表；没有 `Home` 时先创建 `Home`，回读正文并记录 revision，然后再创建或更新其他核心映射页面。
4. 每个核心页面写入后都要在线回读；页面可读取且取得 revision 才算创建成功，不能用本地 `docs/` 文件替代这项证据。
5. 运行 `python dev_scripts/sync_wiki_docs.py`、`python dev_scripts/check_harness.py --strict` 和 `python dev_scripts/sync_wiki_docs.py --check`。任一映射页面不存在、无法回读或镜像不一致时，停止产品编码并完成初始化。
5. 运行 `python dev_scripts/harness.py sync --verify`。任一映射页面不存在、无法回读或镜像不一致时，停止产品编码并完成初始化。
Gitea 暂时不可用时可以准备工单和 Wiki 草稿，但不得把本地草稿宣称为线上事实，也不得绕过此门禁开始产品功能开发。
@@ -150,7 +150,7 @@ Agent 检查分支和工作区，只修改工单范围内的文件。发现新
使用以下命令只在 Wiki 创建任务归档页：
```powershell
python dev_scripts/new_task_archive.py 123 "修复登录超时"
python dev_scripts/harness.py archive 123 "修复登录超时"
```
归档内容以 Wiki 页面为事实来源。默认不修改 `wiki-docs.json`，也不写入 `docs/task/`。把 Wiki 页面、revision 和实现提交哈希写回工单；用户明确验收通过后，关闭单元工单并勾选父工单中的任务。
@@ -158,8 +158,8 @@ python dev_scripts/new_task_archive.py 123 "修复登录超时"
只有用户明确提出时才导出任务归档：
```powershell
python dev_scripts/export_task_archives.py # 增量：新增或 revision 变化
python dev_scripts/export_task_archives.py --all # 全量：读取全部线上任务归档
python dev_scripts/harness.py export # 增量：新增或 revision 变化
python dev_scripts/harness.py export --all # 全量：读取全部线上任务归档
```
导出不得自动删除本地文件。`docs/task/` 只是人工按需生成的只读快照，可能不是完整或最新的任务历史。
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: https://git.ilapage.cn/OPC/dev_harness/wiki/Architecture-and-Code-Map.-
wiki_revision: f93132ddd5bbc8fe233270579a63fc182db3b795
synchronized_at: 2026-08-08T01:16:49Z
wiki_revision: 5c8801853ca850e78dd920b7740b1d2b5dc528ad
synchronized_at: 2026-08-18T13:34:44Z
<!-- gitea-wiki-mirror:end -->
# 架构与代码地图
@@ -38,11 +38,11 @@ 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 页面映射 | `wiki-docs.json` | `mappings` | 页面名、本地路径 | `harness.py sync --check` | 中 |
| 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` | 中 |
| 同步与校验 | `dev_scripts/harness.py` | `run_sync()` | `sync [--check] [--verify]` | 线上 Wiki 对照检查 | 低 |
| 任务归档 | `dev_scripts/harness.py` | `run_archive()` | `archive <编号> <短标题>` | 单元测试和正式归档 | 中 |
| Harness 结构检查 | `dev_scripts/harness.py` | `run_check()` | 必需文件、镜像、归档检查 | `check --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: https://git.ilapage.cn/OPC/dev_harness/wiki/Local-Development-and-Verification.-
wiki_revision: b31ef962e1a0a368f067b18bace3071bab60a20d
synchronized_at: 2026-08-08T01:18:31Z
wiki_revision: b519184a1f0aa4f104350e7eed43619e62a23b43
synchronized_at: 2026-08-18T13:34:49Z
<!-- gitea-wiki-mirror:end -->
# 本地开发与验证
@@ -35,7 +35,7 @@ synchronized_at: 2026-08-08T01:18:31Z
### 2. 检查 Harness
- 目的：验证必需文件、项目档案、Wiki 映射和归档结构。
- 命令：`python dev_scripts/check_harness.py --strict`
- 命令：`python dev_scripts/harness.py check --strict`
- 预期：输出“DevHarness 检查通过”。
- 失败检查：按错误提示检查缺失页面、未填占位符或损坏的镜像头。
@@ -49,14 +49,14 @@ synchronized_at: 2026-08-08T01:18:31Z
### 4. 对照线上 Wiki
- 目的：确认本地 docs 是最新镜像。
- 命令：`python dev_scripts/sync_wiki_docs.py --check`
- 命令：`python dev_scripts/harness.py sync --check`
- 预期：所有映射显示“一致”。
- 失败检查：先读取线上页面；确认页面名、revision、网络和 `GITEA_URL`。
## 常用调试方式
- 只检查 Python 语法：`python -m compileall -q dev_scripts tests`。
- 查看一个脚本帮助：`python dev_scripts/sync_wiki_docs.py --help`。
- 查看一个脚本帮助：`python dev_scripts/harness.py sync --help`。
- 查看未提交差异：`git diff --check` 和 `git diff`。
- 查看最近提交：`git log -5 --oneline`。
- 调试失败测试时优先运行单个测试文件，不要先修改多个模块。
@@ -76,8 +76,8 @@ DevHarness 不使用生产数据，也不需要固定业务测试数据。命令
```powershell
python -m unittest discover -s tests -v
python dev_scripts/check_harness.py --strict
python dev_scripts/sync_wiki_docs.py --check
python dev_scripts/harness.py check --strict
python dev_scripts/harness.py sync --check
git diff --check
git status --short
```
docs/05-common-changes.md
+5 -5
View File
@@ -2,8 +2,8 @@
generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
wiki_page: Common-Changes
wiki_url: https://git.ilapage.cn/OPC/dev_harness/wiki/Common-Changes.-
wiki_revision: 9b223d2feada753a6d38bffce6eb0848c4067b85
synchronized_at: 2026-08-08T01:16:55Z
wiki_revision: f3bc14df51d06393466ab49a1e5f490a21d6d8b3
synchronized_at: 2026-08-18T13:34:51Z
<!-- gitea-wiki-mirror:end -->
# 常见修改指南
@@ -27,8 +27,8 @@ synchronized_at: 2026-08-08T01:16:55Z
1. 在相关工单确认目标。
2. 读取线上 Wiki 页面和当前 revision。
3. 修改线上 Wiki，不直接编辑 `docs/`。
4. 运行 `python dev_scripts/sync_wiki_docs.py`。
5. 运行 `python dev_scripts/sync_wiki_docs.py --check`。
4. 运行 `python dev_scripts/harness.py sync`。
5. 运行 `python dev_scripts/harness.py sync --check`。
6. 审查本地镜像差异并提交。
停止条件：页面需要删除、重命名或改变事实源边界。
@@ -45,7 +45,7 @@ synchronized_at: 2026-08-08T01:16:55Z
## 调整 Harness 检查
1. 从 `dev_scripts/check_harness.py` 的 `main()` 开始读。
1. 从 `dev_scripts/harness.py` 的 `run_check()` 开始读。
2. 新检查应输出具体文件和缺失内容。
3. 检查结构事实，不声称自动判断文档语义质量。
4. 在 `tests/` 添加成功和失败用例。
docs/07-new-project-documentation-setup.md
+6 -8
View File
@@ -2,8 +2,8 @@
generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
wiki_page: New-Project-Documentation-Setup
wiki_url: https://git.ilapage.cn/OPC/dev_harness/wiki/New-Project-Documentation-Setup.-
wiki_revision: 69ec9144d1d939d69a2e123a3e58a780ce7b19cc
synchronized_at: 2026-08-17T03:24:42Z
wiki_revision: e186d7119620c2e5eadfb47311538dd8cbeb4db9
synchronized_at: 2026-08-18T13:34:57Z
<!-- gitea-wiki-mirror:end -->
# 新项目文档初始化
@@ -146,7 +146,7 @@ Agent 只读检查：
1. 使用配置好的 Gitea MCP 查询目标仓库的 Wiki 页面列表；MCP 不可用时使用 Gitea API，并记录回退原因。
2. 如果 `Home` 不存在，先创建 `Home`。创建后立即在线回读正文并记录 revision；`Home` 可读取后才能继续。
3. 依照 `wiki-docs.json` 逐页创建或更新其他核心页面。每页写入后在线回读正文，记录页面名和 revision。
4. 本地 `docs/` 是模板或 Wiki 镜像；本地文件存在、标题完整或 `check_harness.py --strict` 通过，都不能单独证明线上 Wiki 已初始化。
4. 本地 `docs/` 是模板或 Wiki 镜像；本地文件存在、标题完整或 `harness.py check --strict` 通过，都不能单独证明线上 Wiki 已初始化。
5. 页面缺失、回读失败或没有 revision 时停止初始化，不得开始产品代码；Gitea 恢复后从首个失败页面继续。
至少创建或填写：
@@ -180,15 +180,13 @@ Home 给出建议阅读顺序；每个命令必须有预期结果；代码地图
### 10. 导出镜像并检查
```powershell
python dev_scripts/sync_wiki_docs.py
python dev_scripts/check_harness.py --strict
python dev_scripts/sync_wiki_docs.py --check
python dev_scripts/harness.py sync --verify
python -m unittest discover -s tests -v
```
只有线上 Wiki 确认后才导出核心 `docs/`。任务归档默认不导出；用户明确要求时再运行 `python dev_scripts/export_task_archives.py` 或加 `--all`。旧项目的任务归档快照不能带入新项目历史。
只有线上 Wiki 确认后才导出核心 `docs/`。任务归档默认不导出；用户明确要求时再运行 `python dev_scripts/harness.py export` 或加 `--all`。旧项目的任务归档快照不能带入新项目历史。
`sync_wiki_docs.py --check` 会在线读取全部显式映射页面；任一页面不存在、无法读取或 revision 与镜像不一致时，初始化不通过。只有上述命令全部成功后才允许开始产品代码。
`harness.py sync --check` 会在线读取全部显式映射页面；任一页面不存在、无法读取或 revision 与镜像不一致时，初始化不通过。只有上述命令全部成功后才允许开始产品代码。
## 完成标准
docs/README.md
+5 -5
View File
@@ -2,8 +2,8 @@
generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
wiki_page: Home
wiki_url: https://git.ilapage.cn/OPC/dev_harness/wiki/Home
wiki_revision: a2600f79f1d4ca4c1c7699ee05835ea19be61dee
synchronized_at: 2026-08-17T02:00:03Z
wiki_revision: 9eeda7d498edb029e8055eb8b3ac78ead630da2a
synchronized_at: 2026-08-18T13:34:34Z
<!-- gitea-wiki-mirror:end -->
# DevHarness 文档中心
@@ -31,9 +31,9 @@ DevHarness 是一个以 Gitea 工单管理开发任务、以 Wiki 管理长期
```powershell
git status --short --branch
python dev_scripts/check_harness.py --strict
python dev_scripts/harness.py check --strict
python -m unittest discover -s tests -v
python dev_scripts/sync_wiki_docs.py --check
python dev_scripts/harness.py sync --check
```
预期结果：
@@ -55,7 +55,7 @@ python dev_scripts/sync_wiki_docs.py --check
| 准备交付文档 | Delivery-Documentation-Guide、Audience-Document-Template | 目标岗位验证和 Wiki 同步检查 |
| 调整工单字段 | `.gitea/issue_template/`、Development-Workflow | Harness 严格检查 |
| 修改同步行为 | `dev_scripts/wiki_docs.py`、Architecture-and-Code-Map | 单元测试和真实 Wiki 检查 |
| 增加结构检查 | `dev_scripts/check_harness.py` | 成功与失败测试 |
| 增加结构检查 | `dev_scripts/harness.py` | 成功与失败测试 |
| 排查运行错误 | Troubleshooting、项目档案 | 最小复现命令 |
权限、安全、并发、迁移、支付、删除数据或不可逆操作不属于简单修改，必须停止并交给 Agent 分析、等待人工确认。