generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) wiki_page: Project-Profile wiki_url: https://git.ilapage.cn/OPC/dev_harness/wiki/Project-Profile.- wiki_revision: 5323a382fc19433c19441587120d5a0ee6447a24 synchronized_at: 2026-09-02T02:08:46Z # 项目档案 本页记录不经常变化、所有维护者都需要知道的信息。它是项目档案的事实来源；仓库内 `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 上游版本，不是业务项目自己的提交。不得使用“最新版本”“当前 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、PowerShell、Git | `AGENTS.md` | 本项目不需要安装第三方 Python 包。复制到业务项目后，必须把真实语言、框架、版本和支持平台写入本节。 ## 阅读入口 - 新人入口：Home。 - 产品需求入口：[产品需求总览](Product-Requirements-Overview.-)。 - 代码入口：[架构与代码地图](Architecture-and-Code-Map.-)。 - 业务边界：[业务规则与术语](Business-Rules-and-Glossary.-)。 - 运行验证：[本地开发与验证](Local-Development-and-Verification.-)。 - 简单维护：[常见修改指南](Common-Changes.-)。 - 错误定位：[故障排查](Troubleshooting)。 ## 常用命令 所有命令默认从仓库根目录执行。 | 用途 | 命令 | 预期结果 | |---|---|---| | 查看工作区 | `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` 必须通过。 - 未执行或无法覆盖的验证必须记录到工单。