# Harness Knowledge Architecture

本文定义 Codex Harness 的项目知识层。Harness 不只负责把任务跑完，还要把执行中被证明有用的经验沉淀成可检索、可追踪、可维护的项目资产。

## 目标

- 让任务执行前能按需读取项目经验，而不是每次从零推导。
- 让任务执行后能把架构决策、风险、流程和坏例归档。
- 让 trace 记录知识引用，支持后续成熟度提升、衰减和冲突治理。
- 控制上下文预算，避免把大量完整知识一次性塞进每个 Codex 会话。

## 与其他知识面的边界

- `AGENTS.md` 和 `.codex/*` 负责宿主自动加载、执行约束和导航路由。
- `docs/ai/*` 负责当前项目导航、任务上下文和局部摘要。
- `docs/harness/*` 负责治理规则、查询顺序和升级边界。
- MCP、外部文档和个人知识默认属于项目外部知识面，只有在验证并沉淀后才进入项目知识层。

## 存储层

当前仓库先落地项目级知识层：

```text
docs/knowledge/
  knowledge-catalog.md      # 全景入口，约 50-120 行
  catalog.md                # 当前项目全部知识条目的一行摘要索引
  models/                   # 实体、数据结构、关系
  decisions/                # 架构决策和技术选型
  guidelines/               # 推荐做法和禁止做法
  pitfalls/                 # 已知风险、失败模式、排查路径
  processes/                # 工作流、业务流、操作步骤
  archive/                  # 过时或低置信条目
```

跨项目团队知识库暂不直接耦合到 runtime。后续如引入独立 Git 知识仓库，应通过同步任务把稳定条目提升出去，而不是让 driver 直接依赖外部仓库可用性。

可选团队知识库建议使用独立 Git 仓库，而不是寄生在某个业务项目中：

```text
team-knowledge/
  knowledge-catalog.md        # 团队级全景入口
  .knowledge-config.yaml      # 成员、角色、同步和冲突策略
  log.md                      # 只追加的知识变更日志
  team-conventions/           # Layer 0-T: 团队约定
  tech-wiki/                  # Layer 1: 跨项目技术知识
  biz-wiki/<domain>/          # Layer 2: 领域业务知识
  project-profiles/           # 项目画像和知识源映射
  contributions/
    pending/                  # 待合并贡献
    conflicts/                # 内容矛盾和人工裁决项
```

团队知识库是可选上层能力。项目 driver 必须能在没有外部知识仓库的情况下继续执行；外部知识同步失败时只能降级为缺少可复用上下文，不应阻断本地验证。

团队知识库的完整同步协议见 `docs/harness/team-knowledge-sync.md`。本文件只定义项目知识层和提升边界；团队知识库的成员角色、贡献暂存、冲突裁决和追加日志由同步协议约束。

## 知识层级

| 层级 | 范围 | 存放建议 | 进入方式 |
| --- | --- | --- | --- |
| Layer 0-P | 个人偏好 | 用户本地配置，不提交项目 | 人工维护 |
| Layer 0-T | 团队约定 | `team-conventions/` | 团队维护 |
| Layer 1 | 跨项目技术知识 | `tech-wiki/` | verified / proven 技术条目提升 |
| Layer 2 | 业务领域知识 | `biz-wiki/<domain>/` | verified / proven 业务条目提升 |
| Layer 3 | 项目知识 | `docs/knowledge/` | `ARCHIVE-*` 或 `KNOWLEDGE-IMPORT-*` 写入 |

提升方向默认从 Layer 3 开始。只有当条目不再是项目特有经验，并且 evidence 显示可跨任务或跨项目复用时，才建议提升到 Layer 1 或 Layer 2。

## 项目知识与导航层的分工

以下内容更适合写在 `docs/ai/*`：

- 当前任务目标、阶段和 owned paths
- 仓库阅读顺序
- 当前系统的快速架构摘要
- API / DB / known issues 的速查摘要

以下内容更适合进入 `docs/knowledge/*`：

- 经验证可复用的长期经验
- 已经不只服务于单个当前任务的决策
- 需要成熟度、衰减、冲突治理的结论

## 知识类型

| 类型 | 用途 | 示例 |
| --- | --- | --- |
| `model` | 描述实体、结构和关系 | task、trace、truth source 的关系 |
| `decision` | 记录技术选择及原因 | driver-first 优先于聊天内手工实现 |
| `guideline` | 记录推荐或禁止做法 | 禁止只写禁令而不给替代方案 |
| `pitfall` | 记录已知风险和排查步骤 | smoke 占位任务被误带入真实项目 |
| `process` | 记录可重复流程 | ARCHIVE 从 trace 提取知识 |

## 成熟度

| 成熟度 | 定义 | 默认处理 |
| --- | --- | --- |
| `draft` | 单次任务、单一来源提取 | 可引用，但不能作为强约束 |
| `verified` | 至少在一个真实任务中被复用并通过验证 | 可作为 reviewer 的参考依据 |
| `proven` | 至少两个不同任务或项目复用并保持有效 | 可提升为规则、模板或 prompt |

成熟度提升必须基于 evidence，不接受口头判断。长期未引用或被发现过时的条目应降级或移入 `docs/knowledge/archive/`。

`verified -> proven` 不应由单个任务静默完成。默认需要两个不同任务或项目的证据；如果只有一个项目内证据，必须有 maintainer 在归档报告或团队知识同步记录中明确审批。

## 提升、衰减和冲突

| 事件 | 默认处理 |
| --- | --- |
| draft 条目在一个真实任务中被引用并通过验证 | 可提升为 `verified` |
| verified 条目在两个不同任务或项目中被引用并保持有效 | 可提升为 `proven` |
| proven 条目 12 个月未被引用 | 建议降级为 `verified` 或标记复核 |
| verified 条目 6 个月未被引用 | 建议降级为 `draft` 或标记复核 |
| draft 条目长期未引用且 lint 标记无入口 | 移入 `docs/knowledge/archive/` |
| 同一主题出现相反结论 | 保留较低成熟度，写入 conflict candidate，等待人工裁决 |
| 仅追加 evidence、last_referenced 或 contributors | 可自动合并 |

自动化只能产生候选，不应静默提升到 `proven` 或删除知识条目。成熟度变更必须在 trace 的 `archive_summary.maturity_changes` 或归档报告中留下证据。

团队知识库引入后，角色边界如下：

| 角色 | 项目知识权限 | 团队知识权限 |
| --- | --- | --- |
| `maintainer` | 可审批归档、衰减和冲突裁决 | 可审批 proven、合并冲突和维护 `log.md` |
| `contributor` | 可新增 draft、追加 evidence、输出候选 | 可写入 `contributions/pending/` |
| `reader` | 可读取并引用知识 | 只读，不写团队仓库 |

## 条目格式

每条知识使用 Markdown 文件，文件名推荐：

```text
<TYPE>-<AREA>-<NNN>.md
```

条目头部使用 YAML frontmatter：

```markdown
---
id: GUIDELINE-HARNESS-001
type: guideline
maturity: draft
tags: [harness, rules, context]
applicable_phases: [analysis, plan, implement, archive]
source_references:
  - traces/<task-id>-<timestamp>.json
last_referenced:
contributors:
  - codex
evidence:
  contributors:
    - name: codex
      source_ref: traces/<task-id>-<timestamp>.json
  validated_projects: []
  contradictions: []
---

# 标题

## Context

这条知识成立的背景。

## Guidance

可执行的规则、判断或流程。

## Evidence

验证命令、trace、review finding 或失败记录。
```

## 渐进式查询

Codex 会话按三层读取：

1. 读 `docs/knowledge/knowledge-catalog.md`，判断有哪些分类和阶段推荐入口。
2. 读 `docs/knowledge/catalog.md`，按 `tags`、`type`、`applicable_phases` 过滤候选条目。
3. 只读取和当前任务直接相关的完整条目。

任务可通过 `knowledge_query_budget` 限制读取量：

```json
{
  "knowledge_query_budget": {
    "catalogs": 2,
    "entries": 5
  }
}
```

## Trace 集成

任务使用知识后，应在最终报告或 trace 中留下：

```json
{
  "knowledge_references": [
    {
      "id": "GUIDELINE-HARNESS-001",
      "title": "规则必须配替代方案",
      "used_in": "Stage 1 review"
    }
  ]
}
```

归档任务读取 `knowledge_references` 后，可以更新 `last_referenced`、提升成熟度，或标记冲突。

归档任务还应输出以下候选清单，供维护者或后续 lint 任务处理：

- promotion candidates：可提升成熟度或提升到团队知识库的条目。
- decay candidates：长期未引用、上下文疑似过时的条目。
- conflict candidates：同一主题存在相反结论或适用条件冲突。
- merge candidates：重复或高度相似条目。

## 归档策略

`ARCHIVE-*` 任务只做知识沉淀和索引维护，不重新定义需求范围。归档输入包括：

- 当前任务 trace
- `progress.txt`
- Stage 1 / Stage 2 review 输出
- failure triage
- changed files
- 验证命令输出

归档输出包括：

- 新增或更新的知识条目
- 更新后的 `knowledge-catalog.md`
- 更新后的 `catalog.md`
- trace 中的 `archive_summary`

归档阶段缺失不应阻塞代码验证，但会降低后续任务复用历史经验的能力。

## 相关流程

- 冷启动导入：`docs/harness/knowledge-import.md`
- 知识健康检查：`docs/harness/knowledge-lint.md`
- 团队知识同步：`docs/harness/team-knowledge-sync.md`
