chore(project): 初始化项目协作与知识基线

2026-09-09 13:01:36 +08:00
parent 6d0d57561d
commit cbc1392feb
9 changed files with 129 additions and 76 deletions
@@ -1,3 +1,3 @@
-# Local CraftKit data
+# CraftKit 本地过程资料和可重新生成的缓存不得提交到版本库。
 /local/
 /cache/
@@ -1,13 +1,15 @@
 # CraftKit 项目资料

-本目录保存 JobRadar 可供 Agent 使用的配置、规范和知识索引。
+本目录保存当前项目可供 Agent 使用的配置、规范、知识和交接内容。

- `project.json`：项目类型、技术栈、代码边界、依赖标识和已确认命令。
- `agents/`：项目对 Agent 的补充说明入口。
- `standards/`：项目开发、测试和交付规范入口。
- `knowledge/`：经过验证的架构决策和可复用知识入口。
+- `project.json`：项目类型、技术栈、代码边界、依赖标识、命令和文档生命周期默认策略。
+- `agents/`：项目对 Agent 的补充指令。
+- `standards/`：项目自身的开发、测试、文档与 Git 规范。
+- `standards/document-maintenance.md`：长期文档的审核、持续更新、替代和关闭约定。
+- `knowledge/`：经过验证的技术决策和可复用经验。
+- `designs/`：用户明确要求共享或正式交付的设计文档。
 - `handoff/`：用户明确选择共享的任务交接。
- `local/`：当前工作副本的本地上下文，不进入 Git。
+- `local/`：当前工作副本的过程文档、任务记录和本地上下文，不进入 Git。
 - `cache/`：可重新生成的缓存，不进入 Git。

 共享资料不得包含凭据、个人机器绝对路径或无必要的业务数据。
@@ -2,6 +2,7 @@

 | 主题 | 适用范围 | 入口 |
 | --- | --- | --- |
-| JobRadar Agent 目标、输入输出、工具、状态与人工确认边界 | Agent 运行时、工具和评测相关任务 | `../../docs/agent-contract.md` |
+| 项目通用协作要求 | 全仓库任务 | `../../AGENTS.md` |
+| 岗位研究 Agent 契约 | Agent 运行时、工具和评测任务 | `../../docs/agent-contract.md` |

-项目级通用协作要求见仓库根目录 `../../AGENTS.md`。
+新增补充说明时，应记录适用目录、触发条件和文件路径。
@@ -1,10 +1,18 @@
 # 项目知识索引

+当前可复用的项目知识以已存在的项目文档为证据入口：
+
 | 主题 | 内容 | 证据入口 |
 | --- | --- | --- |
 | 项目架构 | 目标架构、模块职责、数据边界和部署边界 | `../../docs/architecture.md` |
-| Agent 契约 | 单 Agent 起步、类型化工具、状态、证据与人工确认边界 | `../../docs/agent-contract.md` |
+| Agent 契约 | 单 Agent、类型化工具、状态和人工确认边界 | `../../docs/agent-contract.md` |
 | 工程路线 | 分阶段交付范围和进入下一阶段的条件 | `../../docs/roadmap.md` |
-| 第一阶段工程基线 | 数据库与工程实施决策 | `../../docs/engineering-baseline/dev-plan.md` |
+| 第一阶段工程基线 | 数据库、工程实施决策和验收要求 | `../../docs/engineering-baseline/dev-plan.md` |

-只收录有证据、适用范围明确且能够复用的技术决策与经验。问题经验和新决策按需建立，避免预建空分类。
+只收录有证据、适用范围明确且能够复用的技术决策与经验。
+
+长期知识按 `.craftkit/standards/document-maintenance.md` 保存审核状态并持续更新；过时或历史材料不得作为当前有效依据。
+
+- 问题经验按需建立在 `pitfalls/`，不预建空分类。
+- 重要技术决策按需建立在 `decisions/`。
+- 其他长期知识应优先并入已有主题，避免同义平行文档。
@@ -6,78 +6,55 @@
  },
  "project": {
    "name": "JobRadar",
-    "description": "面向个人使用、以 Agent 为核心的智能岗位发现与决策系统",
+    "description": "面向个人求职者、以 Agent 为核心的智能岗位发现与决策系统。",
    "type": "web-application"
  },
  "technology": {
    "languages": [
-      {
-        "name": "Python",
-        "version": "3.13"
-      }
+      "Python 3.13"
    ],
    "frameworks": [
      {
        "name": "Django",
        "version": "6.0.8",
        "profile": ""
+      },
+      {
+        "name": "OpenAI Agents SDK",
+        "version": "0.22.0",
+        "profile": ""
      }
    ],
    "buildTools": [
-      {
-        "name": "Conda",
-        "source": "environment.yml"
-      }
+      "Conda"
    ],
    "databases": [
-      {
-        "name": "SQLite",
-        "usage": "development and test"
-      },
-      {
-        "name": "PostgreSQL",
-        "usage": "integration and production"
-      }
+      "SQLite",
+      "PostgreSQL"
    ]
  },
  "code": {
    "sourceRoots": [
-      "."
+      "JobRadar"
    ],
    "packageRoots": [
      "JobRadar"
    ],
    "modules": [
-      {
-        "name": "project-config",
-        "path": "JobRadar",
-        "purpose": "Django project entry points, URL configuration and environment-specific settings"
-      }
+      "JobRadar.settings",
+      "JobRadar.urls"
    ]
  },
  "dependencies": {
    "internal": [],
    "public": [
-      {
-        "name": "playwright",
-        "version": "1.60.0",
-        "purpose": "authorized job-page collection"
-      },
-      {
-        "name": "psycopg",
-        "version": "3.3.5",
-        "purpose": "PostgreSQL database driver"
-      },
-      {
-        "name": "pillow",
-        "version": "12.2.0",
-        "purpose": "image processing support"
-      },
-      {
-        "name": "openai-agents",
-        "version": "0.22.0",
-        "purpose": "planned Agent runtime"
-      }
+      "playwright==1.60.0",
+      "psycopg[binary]==3.3.5",
+      "pillow==12.2.0",
+      "pytest==9.1.1",
+      "pytest-django==4.14.0",
+      "coverage==7.15.4",
+      "ruff==0.16.4"
    ]
  },
  "frontend": {
@@ -96,12 +73,21 @@
    ],
    "check": [
      "python manage.py check",
-      "python manage.py makemigrations --check --dry-run"
+      "python manage.py makemigrations --check --dry-run",
+      "ruff check ."
    ]
  },
  "documents": {
+    "workRoot": ".craftkit/local/tasks",
+    "designRoot": ".craftkit/designs",
    "archiveRoot": "docs/archive",
-    "archiveRules": []
+    "archiveRules": [],
+    "lifecycle": {
+      "onTaskComplete": "preview",
+      "localRetentionDays": 7,
+      "trackedFiles": "review-required",
+      "personalConfig": "retain"
+    }
  },
  "guidance": {
    "agentIndex": ".craftkit/agents/index.md",
@@ -0,0 +1,31 @@
+---
+reviewStatus: pending
+reviewedAt: null
+replacedBy: null
+---
+
+# 文档维护规范
+
+## 适用范围
+
+本规范适用于项目正式需求、生效设计、项目规范和长期知识。过程草稿按任务需要维护，不强制逐份审核；历史归档保留当时快照，不作为当前依据。
+
+## 创建与更新
+
+- 任务开始时查找相关已有文档，优先更新现有权威内容，不创建同义平行版本。
+- 新建或实质修改长期文档后，将文档自身的 `reviewStatus` 标为 `pending`。
+- 项目已有审批结果可以直接作为审核依据；通过后标为 `approved`。
+- 已知文档与需求、实现或新证据不一致时标为 `outdated`；更新后回到 `pending` 并重新审核。
+- 排版、错字、链接修复和不改变含义的调整不改变审核状态。
+
+## 状态与替代
+
+项目没有既有元数据格式时，在文档 Frontmatter 使用 `reviewStatus`、`reviewedAt` 和 `replacedBy`。旧文档缺少状态时视为尚未确认，只在实际使用或修改时补齐。
+
+新版替代旧版时更新索引和引用，并通过 `replacedBy` 指向当前版本。旧版根据历史价值归档或删除；归档发现错误时补充勘误和新版链接，不改写历史事实。
+
+## 任务关联与关闭
+
+本地 `task.json` 记录本次创建、更新或引用的文档。关联旧文档不转移所有权，也不产生删除权限。
+
+任务关闭前检查本次实现影响的长期文档已经同步。需要作为当前依据的文档必须为 `approved`；`pending` 或 `outdated` 文档应完成处理，无法处理时列入延后清单并说明影响。
@@ -2,10 +2,11 @@

 | 主题 | 适用范围 | 规则入口 | 优先级 |
 | --- | --- | --- | --- |
-| AI 开发流程、验证与交付 | 全仓库开发任务 | `../../docs/development-guide.md` | 项目规则 |
-| 架构、模块、数据与部署边界 | 设计和实现任务 | `../../docs/architecture.md` | 项目规则 |
-| Agent 契约与安全边界 | Agent、工具和评测任务 | `../../docs/agent-contract.md` | 项目规则 |
-| 阶段范围与实施顺序 | 需求规划和增量实现 | `../../docs/roadmap.md` | 项目计划 |
-| Python 格式与静态检查配置 | Python 源码 | `../../pyproject.toml` | 工具配置 |
+| 文档生命周期 | 正式需求、设计、规范和长期知识 | [文档维护规范](document-maintenance.md) | 项目规则 |
+| AI 开发流程 | 全仓库开发、验证与交付 | [AI 开发约定](../../docs/development-guide.md) | 项目规则 |
+| 架构与数据边界 | 设计和实现任务 | [架构设计](../../docs/architecture.md) | 项目规则 |
+| Agent 安全边界 | Agent、工具和评测任务 | [Agent 契约](../../docs/agent-contract.md) | 项目规则 |
+| 阶段实施顺序 | 需求规划和增量实现 | [实施路线图](../../docs/roadmap.md) | 项目计划 |
+| Python 质量配置 | Python 源码 | [工具配置](../../pyproject.toml) | 工具配置 |

-未覆盖主题可由 `guidance` 查询中性公共基线。规划内容不能替代已确认的当前实现规则。
+新增规范时记录主题、适用范围、规则文件和优先级；未覆盖主题可由 `guidance` 查询中性公共基线。