dev_harness/docs/00-project-profile.md

generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) wiki_page: Project-Profile wiki_url: http://ilaer.eicp.net:8418/opc/dev_harness/wiki/Project-Profile.- wiki_revision: 62d1251f807f7d1b60017790c35d46186ffb9617 synchronized_at: 2026-08-16T11:18:50Z

项目档案

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

基本信息

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

子项目与交付单元

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

子项目 / 交付单元	职责	技术栈	构建与测试	版本与发布方式	规则入口	共享边界
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/ 的事实来源边界

单应用项目只填写一行。多应用单仓库必须逐个填写，并为技术栈、构建测试或安全规则不同的目录增加子目录 AGENTS.md。技术栈不同不等于必须拆分 Git 仓库；是否拆仓应根据团队、权限、发布周期、仓库效率、复用关系和共享接口稳定性判断。

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

技术栈与运行环境

部分	技术	规则文件
Harness 规则和模板	Markdown、Gitea 1.25	AGENTS.md
Wiki 镜像与结构检查	Python 3 标准库	AGENTS.md
主要开发环境	Windows、PowerShell、Git	AGENTS.md

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

阅读入口

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

常用命令

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

用途	命令	预期结果
查看工作区	git status --short --branch	显示分支且没有无关修改
检查模板结构	python dev_scripts/check_harness.py --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	读取并导出全部线上任务归档

目录边界

目录	职责	不应放入
.gitea/issue_template/	Gitea 工单模板	凭据、任务最终归档
docs/	Wiki 自动导出的只读镜像	人工直接维护的长期文档
docs/task/	人工按需导出的 Wiki 任务归档只读快照，可能不是完整历史	讨论过程和临时方案
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，再导出本地镜像；任务归档默认只保存在 Wiki，用户明确要求时才增量或全量导出。
• 镜像必须包含来源页面、revision 和同步时间。
• 页面删除、重命名和映射变更必须人工确认。
• 新增核心文档时必须更新 Home、显式映射和 Harness 检查。
• 代码入口、命令、配置、业务规则或排错方式变化时必须评估文档影响。
• python dev_scripts/check_harness.py --strict 必须通过。
• python -m unittest discover -s tests -v 必须通过。
• 未执行或无法覆盖的验证必须记录到工单。