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

.craftkit/.gitignore

@@ -1,3 +1,3 @@
-# Local CraftKit data
+# CraftKit 本地过程资料和可重新生成的缓存不得提交到版本库。
 /local/
 /cache/

.craftkit/README.md

@@ -1,13 +1,15 @@
 # CraftKit 项目资料
 
-本目录保存 JobRadar 可供 Agent 使用的配置、规范和知识索引。
+本目录保存当前项目可供 Agent 使用的配置、规范、知识和交接内容。
 
-- `project.json`：项目类型、技术栈、代码边界、依赖标识和已确认命令。
+- `project.json`：项目类型、技术栈、代码边界、依赖标识、命令和文档生命周期默认策略。
-- `agents/`：项目对 Agent 的补充说明入口。
+- `agents/`：项目对 Agent 的补充指令。
-- `standards/`：项目开发、测试和交付规范入口。
+- `standards/`：项目自身的开发、测试、文档与 Git 规范。
-- `knowledge/`：经过验证的架构决策和可复用知识入口。
+- `standards/document-maintenance.md`：长期文档的审核、持续更新、替代和关闭约定。
+- `knowledge/`：经过验证的技术决策和可复用经验。
+- `designs/`：用户明确要求共享或正式交付的设计文档。
 - `handoff/`：用户明确选择共享的任务交接。
-- `local/`：当前工作副本的本地上下文，不进入 Git。
+- `local/`：当前工作副本的过程文档、任务记录和本地上下文，不进入 Git。
 - `cache/`：可重新生成的缓存，不进入 Git。
 
 共享资料不得包含凭据、个人机器绝对路径或无必要的业务数据。

.craftkit/agents/index.md

@@ -2,6 +2,7 @@
 
 | 主题 | 适用范围 | 入口 |
 | --- | --- | --- |
-| JobRadar Agent 目标、输入输出、工具、状态与人工确认边界 | Agent 运行时、工具和评测相关任务 | `../../docs/agent-contract.md` |
+| 项目通用协作要求 | 全仓库任务 | `../../AGENTS.md` |
+| 岗位研究 Agent 契约 | Agent 运行时、工具和评测任务 | `../../docs/agent-contract.md` |
 
-项目级通用协作要求见仓库根目录 `../../AGENTS.md`。
+新增补充说明时，应记录适用目录、触发条件和文件路径。

.craftkit/knowledge/index.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/`。
+- 其他长期知识应优先并入已有主题，避免同义平行文档。

.craftkit/project.json

@@ -6,78 +6,55 @@
   },
   "project": {
     "name": "JobRadar",
-    "description": "面向个人使用、以 Agent 为核心的智能岗位发现与决策系统",
+    "description": "面向个人求职者、以 Agent 为核心的智能岗位发现与决策系统。",
     "type": "web-application"
   },
   "technology": {
     "languages": [
-      {
+      "Python 3.13"
-        "name": "Python",
-        "version": "3.13"
-      }
     ],
     "frameworks": [
       {
         "name": "Django",
         "version": "6.0.8",
         "profile": ""
+      },
+      {
+        "name": "OpenAI Agents SDK",
+        "version": "0.22.0",
+        "profile": ""
       }
     ],
     "buildTools": [
-      {
+      "Conda"
-        "name": "Conda",
-        "source": "environment.yml"
-      }
     ],
     "databases": [
-      {
+      "SQLite",
-        "name": "SQLite",
+      "PostgreSQL"
-        "usage": "development and test"
-      },
-      {
-        "name": "PostgreSQL",
-        "usage": "integration and production"
-      }
     ]
   },
   "code": {
     "sourceRoots": [
-      "."
+      "JobRadar"
     ],
     "packageRoots": [
       "JobRadar"
     ],
     "modules": [
-      {
+      "JobRadar.settings",
-        "name": "project-config",
+      "JobRadar.urls"
-        "path": "JobRadar",
-        "purpose": "Django project entry points, URL configuration and environment-specific settings"
-      }
     ]
   },
   "dependencies": {
     "internal": [],
     "public": [
-      {
+      "playwright==1.60.0",
-        "name": "playwright",
+      "psycopg[binary]==3.3.5",
-        "version": "1.60.0",
+      "pillow==12.2.0",
-        "purpose": "authorized job-page collection"
+      "pytest==9.1.1",
-      },
+      "pytest-django==4.14.0",
-      {
+      "coverage==7.15.4",
-        "name": "psycopg",
+      "ruff==0.16.4"
-        "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"
-      }
     ]
   },
   "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",

.craftkit/standards/document-maintenance.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` 文档应完成处理，无法处理时列入延后清单并说明影响。

.craftkit/standards/index.md

@@ -2,10 +2,11 @@
 
 | 主题 | 适用范围 | 规则入口 | 优先级 |
 | --- | --- | --- | --- |
-| AI 开发流程、验证与交付 | 全仓库开发任务 | `../../docs/development-guide.md` | 项目规则 |
+| 文档生命周期 | 正式需求、设计、规范和长期知识 | [文档维护规范](document-maintenance.md) | 项目规则 |
-| 架构、模块、数据与部署边界 | 设计和实现任务 | `../../docs/architecture.md` | 项目规则 |
+| AI 开发流程 | 全仓库开发、验证与交付 | [AI 开发约定](../../docs/development-guide.md) | 项目规则 |
-| Agent 契约与安全边界 | Agent、工具和评测任务 | `../../docs/agent-contract.md` | 项目规则 |
+| 架构与数据边界 | 设计和实现任务 | [架构设计](../../docs/architecture.md) | 项目规则 |
-| 阶段范围与实施顺序 | 需求规划和增量实现 | `../../docs/roadmap.md` | 项目计划 |
+| Agent 安全边界 | Agent、工具和评测任务 | [Agent 契约](../../docs/agent-contract.md) | 项目规则 |
-| Python 格式与静态检查配置 | Python 源码 | `../../pyproject.toml` | 工具配置 |
+| 阶段实施顺序 | 需求规划和增量实现 | [实施路线图](../../docs/roadmap.md) | 项目计划 |
+| Python 质量配置 | Python 源码 | [工具配置](../../pyproject.toml) | 工具配置 |
 
-未覆盖主题可由 `guidance` 查询中性公共基线。规划内容不能替代已确认的当前实现规则。
+新增规范时记录主题、适用范围、规则文件和优先级；未覆盖主题可由 `guidance` 查询中性公共基线。

AGENTS.md

@@ -1,30 +1,49 @@
-# JobRadar 项目协作说明
+# 项目协作说明
 
 ## 项目定位
 
 - 项目名称：JobRadar（职途雷达）
-- 项目用途：面向个人使用、以 Agent 为核心的智能岗位发现与决策系统
+- 项目用途：面向个人求职者，以 Agent 编排岗位采集、企业调查、规则筛选、评分和结果管理，形成可追溯的岗位发现与决策流程。
-- 项目类型：Django Web 应用与 Agent 工程
+- 项目类型：Django Web 应用，目前处于工程基线阶段。
 
 ## 技术与代码边界
 
 技术栈、源码根、模块和依赖以 `.craftkit/project.json` 为结构化入口。未确认的信息不得自行补全。
 
-当前项目处于工程基线阶段。只把仓库中已存在的源码和配置视为已实现能力；README、架构文档和路线图中的后续模块均属于规划，不能描述为已完成。
+- 当前语言为 Python 3.13，Web 框架为 Django 6.0.8。
+- Django 配置位于 `JobRadar/settings/`，开发、测试、集成和生产环境必须使用对应配置。
+- 业务模块按 `docs/architecture.md` 的边界增量建立，不提前创建尚不能验证的空业务模块。
+- 框架记录精确版本和已存在的公共 profile；普通开发只使用当前 profile，升级或版本比较任务才读取源、目标两个版本。
 
 ## 项目资料
 
+- 项目说明：`README.md`
+- 架构设计：`docs/architecture.md`
+- Agent 契约：`docs/agent-contract.md`
+- 实施路线图：`docs/roadmap.md`
+- AI 开发约定：`docs/development-guide.md`
 - Agent 补充说明：`.craftkit/agents/index.md`
 - 项目规范：`.craftkit/standards/index.md`
 - 可复用知识：`.craftkit/knowledge/index.md`
-- 项目总览：`README.md`
+- 共享设计文档：`.craftkit/designs/`；开发中过程文档使用 `.craftkit/project.json` 配置的 `documents.workRoot`。
+- 文档维护规则：`.craftkit/standards/document-maintenance.md`；修改实现时检查并同步受影响的长期文档。
 
 ## 工作约束
 
+- 所有回答、项目文档和代码注释使用中文。
+- 修改前先说明方案；复杂改动取得确认后执行，简单改动可以直接处理，但必须说明调整内容。
+- 新增或修改代码时沿用相邻代码的注释格式，并为关键边界、失败路径和不直观逻辑提供详尽注释。
 - 修改前先阅读与目标目录和任务主题相关的项目资料。
-- 区分明确项目规则、公共建议、规划目标和从代码观察到的现状。
+- 区分明确项目规则、公共建议和从代码观察到的现状。
-- 采用增量、小步、可验证的实现方式，不一次性生成所有规划模块。
 - 不提交凭据、个人机器路径、本地状态或可重新生成缓存。
-- 不伪造 Agent 浏览、查询、工具调用、入库结果或验证结论。
+- 外部采集必须遵守授权范围、站点条款和频率限制，不绕过验证码、登录保护或访问控制。
-- 高风险或不可逆操作必须由用户确认；不得自动投递简历或联系招聘人员。
+- 第一版不自动投递简历或联系招聘人员；高风险或不可逆操作必须经过人工确认。
 - 发现规范冲突、信息缺失或多种并存风格时先向用户说明。
+
+## 验证要求
+
+- Django 配置检查：`python manage.py check`
+- 自动化测试：`python manage.py test`
+- 迁移完整性：`python manage.py makemigrations --check --dry-run`
+- 静态检查：`ruff check .`
+- 项目依赖默认在名为 `JobRadar` 的 Conda 环境中运行；若当前解释器缺少依赖，应先确认环境是否已同步。

README.md

@@ -43,9 +43,14 @@ JobRadar 是一套面向个人使用、以 Agent 为核心的智能岗位发现
 
 ```text
 JobRadar/
-├── JobRadar/             Django 项目配置
+├── JobRadar/             Django 项目配置与分环境 settings
 │   ├── asgi.py
-│   ├── settings.py
+│   ├── settings/
+│   │   ├── base.py
+│   │   ├── development.py
+│   │   ├── integration.py
+│   │   ├── production.py
+│   │   └── test.py
 │   ├── urls.py
 │   └── wsgi.py
 ├── docs/                 架构与实施文档
@@ -145,7 +150,7 @@ python -m playwright install chromium
 ## 配置原则
 
 - 本地开发密钥、数据库密码、招聘网站 Cookie 和模型 API Key 不得提交到 Git。
-- 当前 `settings.py` 仍是 Django 生成的开发配置，不可直接用于生产环境。
+- 项目使用 `JobRadar/settings/` 分离开发、测试、集成和生产配置；部署时必须显式选择生产配置。
 - 第一阶段本地开发和自动化测试默认使用 SQLite，数据库文件不得提交到版本库。
 - PostgreSQL 通过环境变量按需启用；阶段结束前至少完成一次空库迁移和核心模型测试。
 - 远程 PostgreSQL 必须使用 TLS、项目专属数据库和低权限账号，自动化测试不得连接生产库。
@@ -215,4 +220,4 @@ JobRadar 仅用于个人岗位信息整理与求职辅助。使用前应确认
 
 当前版本：`0.1.0-dev`
 
-当前阶段：架构与Agent契约已经确定，下一步由AI直接实现阶段一工程基线。
+当前阶段：架构与 Agent 契约已确定，阶段一的配置与依赖基线已落盘，下一步是用户认证与数据归属设计。