Table of Contents

项目档案

基本信息
项目治理模式
DevHarness 来源与基线
子项目与交付单元
技术栈与运行环境
阅读入口
常用命令
目录边界
环境、配置与凭据
项目专用验收要求

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

项目档案

本页记录不经常变化、所有维护者都需要知道的信息。它是项目档案的事实来源；仓库内 docs/00-project-profile.md 是只读镜像。

基本信息

项目	内容
项目名称	DevHarness
一句话目标	提供以 Gitea 工单、Wiki 和 Git 为事实来源的 AI 辅助开发工作流模板
主要使用者	项目负责人、Claude/Codex Agent、接手简单维护的初级程序员
Gitea 地址	https://git.ilapage.cn
仓库	`OPC/dev_harness`
默认分支	`main`
主要维护者	`ila`
文档适用范围	默认分支当前版本；具体镜像 revision 见每个本地文件头

项目治理模式

项目	当前值
当前治理模式	标准；DevHarness 模板自身的流程变更需要工单和验收
新项目默认	使用 DevHarness 创建的新项目默认采用轻量模式；只有负责人明确选择并记录理由时才改为标准或高风险
选择理由	模板维护会影响多个项目；使用模板的新项目应按自身风险裁剪
升级规则	单个任务的真实风险高于项目默认模式时，仅该任务升级到更高模式

DevHarness 上游模板自身继续采用标准模式。复制模板创建其他项目后，继承的“DevHarness / 标准”文字不代表目标项目已经选择标准模式；目标项目未明确填写治理模式时按轻量模式执行并提示补写，不因此阻塞产品开发。只有负责人明确选择标准或高风险并记录理由时才改变项目默认模式。治理模式只裁剪工单、原型、测试和文档流程，不得取消凭据、授权边界和真实测试证据。

DevHarness 来源与基线

每个采用 DevHarness 的业务项目都必须填写本节。它记录的是所采用的 DevHarness 上游版本，不是业务项目自己的提交。不得使用“最新版本”“当前 main”等动态描述代替完整提交哈希。

项目	内容
DevHarness 来源仓库	`https://git.ilapage.cn/OPC/dev_harness`
当前基线提交	本仓库是 DevHarness 上游源模板，不适用；复制到业务项目后必须替换为实际采用的完整提交哈希
最后接入或升级日期	2026-08-16
项目适配说明	本仓库维护源模板；业务项目填写保留、改写或未采用的 Harness 规则与工具

首次接入和后续升级都必须在目标项目工单中记录旧基线、新基线和差异分类。升级验收通过后，目标项目应把“当前基线提交”和日期更新为已采用的上游提交；未完成或已回退的升级不得更新基线。

子项目与交付单元

“子项目”是仓库中具有明确职责和规则边界的应用或模块；“交付单元”是能够独立构建、测试、版本化或发布的程序、服务、库或文档包。一个子项目可以对应一个交付单元，也可以包含多个交付单元。

子项目 / 交付单元	职责	技术栈	构建与测试	版本与发布方式	规则入口	共享边界
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 仓库；是否拆仓应根据团队、权限、发布周期、仓库效率、复用关系和共享接口稳定性判断。

跨子项目接口或契约必须指定唯一事实来源，并说明各交付单元的兼容范围和验证命令。不得在多个页面维护互不确认的“权威版本”。

技术栈与运行环境

部分	技术	规则文件
Harness 规则和模板	Markdown、Gitea 1.25	`AGENTS.md`
Wiki 镜像与结构检查	Python 3 标准库	`AGENTS.md`
主要开发环境	Windows 10、PowerShell 7 `pwsh`（当前验证 7.3.12）、Git	`AGENTS.md`

本项目不需要安装第三方 Python 包。复制到业务项目后，必须把真实语言、框架、版本和支持平台写入本节。

阅读入口

新人入口：Home。
产品需求入口：产品需求总览。
代码入口：架构与代码地图。
业务边界：业务规则与术语。
运行验证：本地开发与验证。
简单维护：常见修改指南。
错误定位：故障排查。

常用命令

所有命令默认从仓库根目录执行。

用途	命令	预期结果
查看工作区	`git status --short --branch`	显示分支且没有无关修改
检查模板结构	`python dev_scripts/harness.py check --strict`	输出“DevHarness 检查通过”
运行单元测试	`python -m unittest discover -s tests -v`	所有测试通过
导出核心 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`	读取并导出全部线上任务归档

目录边界

目录	职责	不应放入
`.gitea/issue_template/`	Gitea 工单模板	凭据、单次任务证据
`docs/`	Wiki 自动导出的只读镜像	人工直接维护的长期文档
`docs/task/`	人工明确要求后导出的专项或历史兼容快照，可能不是完整历史	默认任务记录、讨论过程和临时方案
`dev_scripts/`	Harness 检查、Wiki 同步和归档工具	产品功能代码
`tests/`	Harness 工具自动化测试	生产数据

环境、配置与凭据

核心 Wiki 同步配置：仓库根目录 wiki-docs.json；可选任务快照不逐页登记，仅在显式归档或导出时动态发现。
Gitea 地址可由配置提供，也可通过 GITEA_URL 覆盖。
Gitea PAT 仅通过 GITEA_TOKEN 或 MCP 安全配置提供，不写入仓库。
Token 至少需要读取仓库权限；创建或更新 Wiki 时还需要写仓库权限。
配置示例：wiki-docs.json 只保存非敏感仓库信息。
日志：本项目不持久化运行日志，命令行错误是主要诊断信息。
测试数据：只使用测试构造的字符串、路径和模拟响应，不使用生产数据。
构建产物：Python 缓存和临时文件不提交。

项目专用验收要求

只有长期事实变化时才更新核心 Wiki 并导出本地镜像；单次任务证据保存在工单，默认不创建任务归档，用户或项目专用规则明确要求时才创建或导出专项快照。
镜像必须包含来源页面、revision 和同步时间。
页面删除、重命名和映射变更必须人工确认。
新增核心文档时必须更新 Home、显式映射和 Harness 检查。
代码入口、命令、配置、业务规则或排错方式变化时必须评估文档影响。
python dev_scripts/harness.py check --strict 必须通过。
python -m unittest discover -s tests -v 必须通过。
未执行或无法覆盖的验证必须记录到工单。